Add basic tests for refactored files

review
Remove the derived hooks from ClientContext
2026-11-13 01:12:29 +00:00 · 2026-11-12 17:47:27 +01:00 · 2026-11-12 13:25:45 +01:00 · 2026-11-12 13:25:45 +01:00 · 2026-11-12 13:25:45 +01:00 · 2026-11-12 13:25:45 +01:00
41 changed files with 2462 additions and 1035 deletions
@@ -73,6 +73,7 @@ import {
 } from "../src/UrlParams";
 import { MediaDevicesContext } from "../src/MediaDevicesContext";
 import { AppViewModel } from "../src/state/AppViewModel";
+import { hostClientSession } from "../src/state/ClientSession";
 import { ObservableScope } from "../src/state/ObservableScope";
 import { BackgroundEffectsProvider } from "../src/tracks/BackgroundEffectsContext";
 import { Config } from "../src/config/Config";
@@ -189,20 +190,25 @@ export const ElementCall: FC<ElementCallProps> = ({
    [roomId, intent, stableConfig],
  );

-  // Created in an effect so that the scope it lives in ends when the component
-  // is unmounted (or these options change), rather than keeping its device
-  // observers running for the rest of the page's life. Null until then, which
-  // is one render.
  const { controlledAudioDevices, callIntent } = params;
  const [vm, setVm] = useState<AppViewModel | null>(null);
  useEffect(() => {
    const scope = new ObservableScope();
-    setVm(new AppViewModel(scope, { controlledAudioDevices, callIntent }));
+    setVm(
+      new AppViewModel(
+        scope,
+        { controlledAudioDevices, callIntent },
+        // The host owns the client. We create a clientSession wrapping the host client.
+        hostClientSession(client),
+        // The host owns the session too, so there is nothing to manage here
+        null,
+      ),
+    );
    return (): void => {
      setVm(null);
      scope.end();
    };
-  }, [controlledAudioDevices, callIntent]);
+  }, [controlledAudioDevices, callIntent, client]);

  const room = client.getRoom(roomId);
  const rtcSession = useMemo(
@@ -250,7 +256,7 @@ export const ElementCall: FC<ElementCallProps> = ({
                    >
                      <Decoration>
                        <TooltipProvider>
-                          <ClientProvider client={client}>
+                          <ClientProvider session={vm.clientSession}>
                            <MediaDevicesContext value={vm.mediaDevices}>
                              <BackgroundEffectsProvider
                                effects={vm.backgroundEffects}
@@ -3,7 +3,7 @@ networks:

 services:
  auth-service:
-    image: ghcr.io/element-hq/lk-jwt-service:0.8.0
+    image: ghcr.io/element-hq/lk-jwt-service:0.10.0
    pull_policy: always
    hostname: auth-server
    environment:
@@ -33,7 +33,7 @@ services:
      - ecbackend

  auth-service-1:
-    image: ghcr.io/element-hq/lk-jwt-service:0.8.0
+    image: ghcr.io/element-hq/lk-jwt-service:0.10.0
    pull_policy: always
    hostname: auth-server-1
    environment:
@@ -23,14 +23,13 @@ import {
 import * as Sentry from "@sentry/react";
 import { TooltipProvider } from "@vector-im/compound-web";
 import { logger } from "matrix-js-sdk/lib/logger";
-import { type MatrixClient } from "matrix-js-sdk";
 import { I18nextProvider } from "react-i18next";

 import { HomePage } from "./home/HomePage";
 import { LoginPage } from "./auth/LoginPage";
 import { RegisterPage } from "./auth/RegisterPage";
 import { RoomPage } from "./room/RoomPage";
-import { ClientProvider } from "./ClientContext";
+import { ClientManagerProvider, ClientProvider } from "./ClientContext";
 import { ErrorPage, LoadingPage } from "./FullScreenView";
 import { Initializer } from "./initializer";
 import { type WidgetHelpers } from "./widget";
@@ -131,22 +130,9 @@ export const App: FC<Props> = ({ vm, widget }) => {
      .catch(logger.error);
  });

-  // As a widget, the client comes from the host over the widget API. Standalone,
-  // Element Call finds one itself, so there is nothing to wait for here.
-  const [widgetClient, setWidgetClient] = useState<MatrixClient | undefined>(
-    undefined,
-  );
-  useEffect(() => {
-    if (widget === null) return;
-    widget.client
-      .then(setWidgetClient)
-      .catch((e) => logger.error("Failed to obtain the host's client", e));
-  }, [widget]);
-  const clientReady = widget === null || widgetClient !== undefined;
-
-  const content =
-    loaded && clientReady ? (
-      <ClientProvider client={widgetClient}>
+  const content = loaded ? (
+    <ClientProvider session={vm.clientSession}>
+      <ClientManagerProvider value={vm.clientManager}>
        <MediaDevicesContext value={vm.mediaDevices}>
          <BackgroundEffectsProvider effects={vm.backgroundEffects}>
            <Sentry.ErrorBoundary
@@ -161,10 +147,11 @@ export const App: FC<Props> = ({ vm, widget }) => {
            </Sentry.ErrorBoundary>
          </BackgroundEffectsProvider>
        </MediaDevicesContext>
-      </ClientProvider>
-    ) : (
-      <LoadingPage />
-    );
+      </ClientManagerProvider>
+    </ClientProvider>
+  ) : (
+    <LoadingPage />
+  );

  return (
    <I18nextProvider i18n={i18n}>
@@ -12,6 +12,7 @@ import { type FC, type PropsWithChildren } from "react";

 import { ClientContextProvider } from "./ClientContext";
 import { Avatar } from "./Avatar";
+import { hostClientSession } from "./state/ClientSession";
 import { mockMatrixRoomMember, mockRtcMembership } from "./utils/test";
 import {
  type HostBridge,
@@ -26,22 +27,7 @@ const TestComponent: FC<
  }>
 > = ({ client, hostBridge = nullHostBridge, children }) => {
  return (
-    <ClientContextProvider
-      value={{
-        state: "valid",
-        disconnected: false,
-        supportedFeatures: {
-          reactions: true,
-        },
-        setClient: vi.fn(),
-        authenticated: {
-          client,
-          isPasswordlessUser: true,
-          changePassword: vi.fn(),
-          logout: vi.fn(),
-        },
-      }}
-    >
+    <ClientContextProvider value={hostClientSession(client)}>
      <HostBridgeProvider value={hostBridge}>{children}</HostBridgeProvider>
    </ClientContextProvider>
  );
@@ -15,7 +15,7 @@ import {
 import { Avatar as CompoundAvatar } from "@vector-im/compound-web";
 import { type MatrixClient } from "matrix-js-sdk";

-import { useClientState } from "./ClientContext";
+import { useClient } from "./ClientContext";
 import { useHostBridge } from "./HostBridge";

 export enum Size {
@@ -74,7 +74,7 @@ export const Avatar: FC<Props> = ({
  style,
  ...props
 }) => {
-  const clientState = useClientState();
+  const { client } = useClient();
  const hostBridge = useHostBridge();

  const sizePx = useMemo(
@@ -87,7 +87,7 @@ export const Avatar: FC<Props> = ({

  const [avatarUrl, setAvatarUrl] = useState<string | undefined>(undefined);

-  // In theory, a change in `clientState` or `sizePx` could run extra media
+  // In theory, a change in `client` or `sizePx` could run extra media
  // downloads, but in practice they should be stable long before this code runs.
  useEffect(() => {
    if (!src) {
@@ -99,12 +99,8 @@ export const Avatar: FC<Props> = ({

    if (hostBridge.downloadMedia) {
      blob = hostBridge.downloadMedia(src);
-    } else if (
-      clientState?.state === "valid" &&
-      clientState.authenticated?.client &&
-      sizePx
-    ) {
-      blob = getAvatarFromServer(clientState.authenticated.client, src, sizePx);
+    } else if (client && sizePx) {
+      blob = getAvatarFromServer(client, src, sizePx);
    } else {
      setAvatarUrl(undefined);
      return;
@@ -133,7 +129,7 @@ export const Avatar: FC<Props> = ({
        URL.revokeObjectURL(objectUrl);
      }
    };
-  }, [clientState, hostBridge, src, sizePx]);
+  }, [client, hostBridge, src, sizePx]);

  return (
    <CompoundAvatar
@@ -6,12 +6,25 @@ Please see LICENSE in the repository root for full details.
 */

 import { expect, test, vi } from "vitest";
-import { render, waitFor } from "@testing-library/react";
+import { act, render, renderHook } from "@testing-library/react";
 import { BrowserRouter } from "react-router-dom";
 import { type MatrixClient } from "matrix-js-sdk";
 import { type FC } from "react";
+import { BehaviorSubject } from "rxjs";

-import { ClientProvider, useClientState } from "./ClientContext";
+import {
+  ClientManagerProvider,
+  ClientProvider,
+  useClientManager,
+  useClientManagerIfAny,
+  useClientSessionState,
+} from "./ClientContext";
+import {
+  type ClientManager,
+  type ClientSession,
+  type ClientSessionState,
+  hostClientSession,
+} from "./state/ClientSession";

 const mockClient = (userId = "@alice:example.org"): MatrixClient =>
  ({
@@ -24,67 +37,47 @@ const mockClient = (userId = "@alice:example.org"): MatrixClient =>

 /** Reports what the context says, so a test can assert on it. */
 const ShowClientState: FC = () => {
-  const state = useClientState();
-  if (state === undefined) return <span>loading</span>;
-  if (state.state === "error") return <span>error</span>;
-  return (
-    <span>{state.authenticated?.client.getUserId() ?? "unauthenticated"}</span>
-  );
+  const state = useClientSessionState();
+  switch (state.state) {
+    case "signedIn":
+      return <span>{state.client.getUserId()}</span>;
+    case "signedOut":
+      return <span>unauthenticated</span>;
+    default:
+      return <span>{state.state}</span>;
+  }
 };

-test("uses a client supplied by the host without waiting", () => {
-  const client = mockClient();
-
-  const { container } = render(
+const renderProvider = (
+  session: ClientSession,
+  children = <ShowClientState />,
+): ReturnType<typeof render> =>
+  render(
    <BrowserRouter>
-      <ClientProvider client={client}>
-        <ShowClientState />
-      </ClientProvider>
+      <ClientProvider session={session}>{children}</ClientProvider>
    </BrowserRouter>,
  );

+test("uses a client supplied by the host without waiting", () => {
+  const { container } = renderProvider(hostClientSession(mockClient()));
+
  // Available on the very first render: a supplied client needs no session
  // restoring, so there is no loading state to pass through.
  expect(container.textContent).toBe("@alice:example.org");
 });

-test("does not claim exclusive use of storage when given a client", () => {
-  // The channel is created when the module loads, so spy on the prototype
-  // rather than trying to replace the global.
-  const postMessage = vi.spyOn(BroadcastChannel.prototype, "postMessage");
-
-  render(
-    <BrowserRouter>
-      <ClientProvider client={mockClient()}>
-        <ShowClientState />
-      </ClientProvider>
-    </BrowserRouter>,
-  );
-
-  // The broadcast shuts down other instances to protect Element Call's own
-  // stores. A host's client brings its own, so there is nothing to protect.
-  expect(postMessage).not.toHaveBeenCalled();
-
-  postMessage.mockRestore();
-});
-
 test("follows the client when the host swaps it", () => {
-  const first = mockClient();
-  const second = mockClient("@bob:example.org");
-
-  const { container, rerender } = render(
-    <BrowserRouter>
-      <ClientProvider client={first}>
-        <ShowClientState />
-      </ClientProvider>
-    </BrowserRouter>,
+  const { container, rerender } = renderProvider(
+    hostClientSession(mockClient()),
  );
  expect(container.textContent).toBe("@alice:example.org");

  // A host that re-authenticates hands us a new client on a mounted component
  rerender(
    <BrowserRouter>
-      <ClientProvider client={second}>
+      <ClientProvider
+        session={hostClientSession(mockClient("@bob:example.org"))}
+      >
        <ShowClientState />
      </ClientProvider>
    </BrowserRouter>,
@@ -93,23 +86,63 @@ test("follows the client when the host swaps it", () => {
  expect(container.textContent).toBe("@bob:example.org");
 });

-test("finds a client of its own when the host supplies none", async () => {
-  const client = mockClient();
-  vi.doMock("./utils/spa", () => ({
-    initSPA: vi.fn().mockResolvedValue({ client, passwordlessUser: true }),
-  }));
-
-  const { container } = render(
-    <BrowserRouter>
-      <ClientProvider>
-        <ShowClientState />
-      </ClientProvider>
-    </BrowserRouter>,
-  );
+test("follows a session of its own as it is restored", () => {
+  const state$ = new BehaviorSubject<ClientSessionState>({ state: "loading" });
+  const { container } = renderProvider({ state$ });

  // Nothing to show until a session has been restored or created
  expect(container.textContent).toBe("loading");
-  await waitFor(() => expect(container.textContent).toBe("@alice:example.org"));
+  act(() =>
+    state$.next({
+      state: "signedIn",
+      client: mockClient(),
+      passwordlessUser: true,
+    }),
+  );
+  expect(container.textContent).toBe("@alice:example.org");
+});

-  vi.doUnmock("./utils/spa");
+test("has no one signed in when the session says so", () => {
+  const { container } = renderProvider({
+    state$: new BehaviorSubject<ClientSessionState>({ state: "signedOut" }),
+  });
+  expect(container.textContent).toBe("unauthenticated");
+});
+
+test("shows the session's error in place of its children", () => {
+  const { container } = renderProvider({
+    state$: new BehaviorSubject<ClientSessionState>({
+      state: "error",
+      error: new Error("Opened elsewhere"),
+    }),
+  });
+  // The error page, not the children
+  expect(container.textContent).not.toContain("error");
+  expect(container.textContent).toContain("Something went wrong");
+});
+
+test("hands the session's manager to views that need one", () => {
+  const manager: ClientManager = {
+    login: vi.fn(),
+    register: vi.fn(),
+    logout: vi.fn(),
+  };
+  const { result } = renderHook(
+    () => [useClientManager(), useClientManagerIfAny()],
+    {
+      wrapper: ({ children }) => (
+        <ClientManagerProvider value={manager}>
+          <>{children}</>
+        </ClientManagerProvider>
+      ),
+    },
+  );
+  expect(result.current).toEqual([manager, manager]);
+});
+
+test("has no manager for a host's session", () => {
+  // The component and the widget provide none; a view that insists on one is
+  // in the wrong build
+  expect(renderHook(() => useClientManagerIfAny()).result.current).toBeNull();
+  expect(() => renderHook(() => useClientManager())).toThrow();
 });
@@ -5,30 +5,18 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */

-import {
-  type FC,
-  useCallback,
-  useEffect,
-  useState,
-  createContext,
-  use,
-  useRef,
-  useMemo,
-  type JSX,
-} from "react";
-import { logger } from "matrix-js-sdk/lib/logger";
-import { type ISyncStateData, type SyncState } from "matrix-js-sdk/lib/sync";
-import { ClientEvent, type MatrixClient } from "matrix-js-sdk";
+import { type FC, useEffect, createContext, use, type JSX } from "react";
+import { type MatrixClient } from "matrix-js-sdk";

 import { ErrorPage } from "./FullScreenView";
-import { useHostBridge } from "./HostBridge";
-import { useLeaveToHome } from "./LeaveToHomeContext";
+import { PosthogAnalytics } from "./analytics/PosthogAnalytics";
+import { useBehavior } from "./useBehavior";
+import { constant } from "./state/Behavior";
 import {
-  PosthogAnalytics,
-  RegistrationType,
-} from "./analytics/PosthogAnalytics";
-import { useEventTarget } from "./useEvents";
-import { OpenElsewhereError } from "./RichError";
+  type ClientManager,
+  type ClientSession,
+  type ClientSessionState,
+} from "./state/ClientSession";

 declare global {
  interface Window {
@@ -37,360 +25,70 @@ declare global {
  }
 }

-export type ClientState = ValidClientState | ErrorState;
-
-export type ValidClientState = {
-  state: "valid";
-  authenticated?: AuthenticatedClient;
-  // 'Disconnected' rather than 'connected' because it tracks specifically
-  // whether the client is supposed to be connected but is not
-  disconnected: boolean;
-  supportedFeatures: {
-    reactions: boolean;
-  };
-  setClient: (client: MatrixClient, session: Session) => void;
+// Without a provider, no one is signed in and there is no session to act on
+const noClientSession: ClientSession = {
+  state$: constant({ state: "signedOut" }),
 };

-export type AuthenticatedClient = {
-  client: MatrixClient;
-  isPasswordlessUser: boolean;
-  changePassword: (password: string) => Promise<void>;
-  logout: () => void;
-};
-
-export type ErrorState = {
-  state: "error";
-  error: Error;
-};
-
-const ClientContext = createContext<ClientState | undefined>(undefined);
+const ClientContext = createContext<ClientSession>(noClientSession);

 export const ClientContextProvider = ClientContext.Provider;

-export const useClientState = (): ClientState | undefined => use(ClientContext);
+export const useClientSessionState = (): ClientSessionState =>
+  useBehavior(use(ClientContext).state$);

-export function useClient(): {
-  client?: MatrixClient;
-  setClient?: (client: MatrixClient, session: Session) => void;
-} {
-  let client;
-  let setClient;
-
-  const clientState = useClientState();
-  if (clientState?.state === "valid") {
-    client = clientState.authenticated?.client;
-    setClient = clientState.setClient;
-  }
-
-  return { client, setClient };
+export function useClient(): { client?: MatrixClient } {
+  const state = useClientSessionState();
+  return { client: state.state === "signedIn" ? state.client : undefined };
 }

-// Plain representation of the `ClientContext` as a helper for old components that expected an object with multiple fields.
-export function useClientLegacy(): {
-  client?: MatrixClient;
-  setClient?: (client: MatrixClient, session: Session) => void;
-  passwordlessUser: boolean;
-  loading: boolean;
-  authenticated: boolean;
-  logout?: () => void;
-  error?: Error;
-} {
-  const clientState = useClientState();
+// Null where the session is a host's: the component, and the widget
+const ClientManagerContext = createContext<ClientManager | null>(null);

-  let client;
-  let setClient;
-  let passwordlessUser = false;
-  let loading = true;
-  let error;
-  let authenticated = false;
-  let logout;
+export const ClientManagerProvider = ClientManagerContext.Provider;

-  if (clientState?.state === "valid") {
-    client = clientState.authenticated?.client;
-    setClient = clientState.setClient;
-    passwordlessUser = clientState.authenticated?.isPasswordlessUser ?? false;
-    loading = false;
-    authenticated = client !== undefined;
-    logout = clientState.authenticated?.logout;
-  } else if (clientState?.state === "error") {
-    error = clientState.error;
-    loading = false;
-  }
-
-  return {
-    client,
-    setClient,
-    passwordlessUser,
-    loading,
-    authenticated,
-    logout,
-    error,
-  };
+/**
+ * The manager of a session that is Element Call's own, for views that only
+ * the standalone app mounts: the login and registration pages. Throws
+ * elsewhere, as those views have no business being there.
+ */
+export function useClientManager(): ClientManager {
+  const manager = use(ClientManagerContext);
+  if (manager === null)
+    throw new Error("This view needs a session of Element Call's own");
+  return manager;
 }

-const loadChannel =
-  "BroadcastChannel" in window ? new BroadcastChannel("load") : null;
+/**
+ * The session's manager, or null where the session is a host's. For views
+ * shared with the widget, which can offer to sign out only when that is ours
+ * to do.
+ */
+export const useClientManagerIfAny = (): ClientManager | null =>
+  use(ClientManagerContext);

 interface Props {
  children: JSX.Element;
-  /**
-   * The client Element Call should use.
-   *
-   * An application hosting Element Call as a component already has a client,
-   * and owns the user's session; supplying it here means Element Call neither
-   * authenticates anyone nor manages their session. Left out, Element Call finds a client
-   * itself — from the widget API, or by restoring or creating a session of its
-   * own.
-   */
-  client?: MatrixClient;
+  /** a session from Element Call SPA, from a widget or the host (EW) */
+  session: ClientSession;
 }

-export const ClientProvider: FC<Props> = ({ children, client }) => {
-  const leaveToHome = useLeaveToHome();
-  const hostBridge = useHostBridge();
-
-  // null = signed out, undefined = loading
-  const [initClientState, setInitClientState] = useState<
-    InitResult | null | undefined
-  >(
-    client === undefined
-      ? undefined
-      : // A supplied client belongs to the host, so there is no session of ours
-        // to restore and nothing to wait for.
-        { client, passwordlessUser: false },
-  );
-
-  const initializing = useRef(false);
-  useEffect(() => {
-    if (client !== undefined) {
-      // Nothing to load, but a host may hand us a different client later — on
-      // re-authenticating, say — so follow whichever one it has given us.
-      setInitClientState((current) =>
-        current?.client === client
-          ? current
-          : { client, passwordlessUser: false },
-      );
-      // Analytics still need to follow the user's choices.
-      if (PosthogAnalytics.instance.isEnabled())
-        PosthogAnalytics.instance.startListeningToSettingsChanges();
-      return;
-    }
-    // In case the component is mounted, unmounted, and remounted quickly (as
-    // React does in strict mode), we need to make sure not to doubly initialize
-    // the client.
-    if (initializing.current) return;
-    initializing.current = true;
-
-    loadClient()
-      .then((initResult) => {
-        setInitClientState(initResult);
-        if (PosthogAnalytics.instance.isEnabled())
-          PosthogAnalytics.instance.startListeningToSettingsChanges();
-      })
-      .catch((err) => logger.error(err))
-      .finally(() => (initializing.current = false));
-  }, [client]);
-
-  const changePassword = useCallback(
-    async (password: string) => {
-      const session = loadSession();
-      if (!initClientState?.client || !session) {
-        return;
-      }
-
-      await initClientState.client.setPassword(
-        {
-          type: "m.login.password",
-          identifier: {
-            type: "m.id.user",
-            user: session.user_id,
-          },
-          user: session.user_id,
-          password: session.tempPassword,
-        },
-        password,
-      );
-
-      saveSession({ ...session, passwordlessUser: false });
-
-      setInitClientState({
-        ...initClientState,
-        passwordlessUser: false,
-      });
-    },
-    [initClientState],
-  );
-
-  const setClient = useCallback(
-    (client: MatrixClient, session: Session) => {
-      const oldClient = initClientState?.client;
-      if (oldClient && oldClient !== client) {
-        oldClient.stopClient();
-      }
-
-      saveSession(session);
-      setInitClientState({
-        client,
-        passwordlessUser: session.passwordlessUser,
-      });
-      if (PosthogAnalytics.instance.isEnabled())
-        PosthogAnalytics.instance.startListeningToSettingsChanges();
-    },
-    [initClientState?.client],
-  );
-
-  const logout = useCallback(async () => {
-    const client = initClientState?.client;
-    if (!client) {
-      return;
-    }
-
-    await client.logout(true);
-    await client.clearStores();
-    clearSession();
-    setInitClientState(null);
-    leaveToHome?.();
-    PosthogAnalytics.instance.logout();
-    PosthogAnalytics.instance.setRegistrationType(RegistrationType.Guest);
-  }, [leaveToHome, initClientState?.client]);
-
-  // To protect against multiple sessions writing to the same storage
-  // simultaneously, we send a broadcast message that shuts down all other
-  // running instances of the app. Element Call only has storage of its own to
-  // protect when it created the session itself; given a client — by a host, or
-  // over the widget API — it is mostly stateless.
-  const ownsSession = client === undefined;
-  useEffect(() => {
-    if (ownsSession) loadChannel?.postMessage({});
-  }, [ownsSession]);
-
-  const [alreadyOpenedErr, setAlreadyOpenedErr] = useState<Error | undefined>(
-    undefined,
-  );
-  useEventTarget(
-    loadChannel,
-    "message",
-    useCallback(() => {
-      initClientState?.client.stopClient();
-      setAlreadyOpenedErr(new OpenElsewhereError());
-    }, [initClientState?.client, setAlreadyOpenedErr]),
-  );
-
-  const [isDisconnected, setIsDisconnected] = useState(false);
-  const [supportsReactions, setSupportsReactions] = useState(false);
-
-  const state: ClientState | undefined = useMemo(() => {
-    if (alreadyOpenedErr) {
-      return { state: "error", error: alreadyOpenedErr };
-    }
-
-    if (initClientState === undefined) return undefined;
-
-    const authenticated =
-      initClientState === null
-        ? undefined
-        : {
-            client: initClientState.client,
-            isPasswordlessUser: initClientState.passwordlessUser,
-            changePassword,
-            logout,
-          };
-
-    return {
-      state: "valid",
-      authenticated,
-      setClient,
-      disconnected: isDisconnected,
-      supportedFeatures: {
-        reactions: supportsReactions,
-      },
-    };
-  }, [
-    alreadyOpenedErr,
-    changePassword,
-    initClientState,
-    logout,
-    setClient,
-    isDisconnected,
-    supportsReactions,
-  ]);
-
-  const onSync = useCallback(
-    (state: SyncState, _old: SyncState | null, data?: ISyncStateData) => {
-      setIsDisconnected(clientIsDisconnected(state, data));
-    },
-    [],
-  );
+export const ClientProvider: FC<Props> = ({ children, session }) => {
+  const state = useBehavior(session.state$);

  useEffect(() => {
-    if (!initClientState) {
-      return;
-    }
-
-    window.matrixclient = initClientState.client;
-    window.passwordlessUser = initClientState.passwordlessUser;
+    if (state.state !== "signedIn") return;
+    window.matrixclient = state.client;
+    window.passwordlessUser = state.passwordlessUser;

    if (PosthogAnalytics.hasInstance())
      PosthogAnalytics.instance.onLoginStatusChanged();
+    // Analytics follow the user's choices whoever the client belongs to
+    if (PosthogAnalytics.instance.isEnabled())
+      PosthogAnalytics.instance.startListeningToSettingsChanges();
+  }, [state]);

-    if (initClientState.client) {
-      initClientState.client.on(ClientEvent.Sync, onSync);
-    }
+  if (state.state === "error") return <ErrorPage error={state.error} />;

-    if (!hostBridge.supportsReactions)
-      logger.warn("The host does not permit reactions");
-    setSupportsReactions(hostBridge.supportsReactions);
-
-    return (): void => {
-      if (initClientState.client) {
-        initClientState.client.removeListener(ClientEvent.Sync, onSync);
-      }
-    };
-  }, [initClientState, onSync, hostBridge]);
-
-  if (alreadyOpenedErr) {
-    return <ErrorPage error={alreadyOpenedErr} />;
-  }
-
-  return <ClientContext value={state}>{children}</ClientContext>;
+  return <ClientContext value={session}>{children}</ClientContext>;
 };
-
-export type InitResult = {
-  client: MatrixClient;
-  passwordlessUser: boolean;
-};
-
-/**
- * Restores or creates a session of Element Call's own. Only reached when no
- * client was supplied for it to use.
- */
-async function loadClient(): Promise<InitResult | null> {
-  const { initSPA } = await import("./utils/spa");
-  return initSPA(loadSession, clearSession);
-}
-
-export interface Session {
-  user_id: string;
-  device_id: string;
-  access_token: string;
-  passwordlessUser: boolean;
-  tempPassword?: string;
-}
-
-const clearSession = (): void => localStorage.removeItem("matrix-auth-store");
-const saveSession = (s: Session): void =>
-  localStorage.setItem("matrix-auth-store", JSON.stringify(s));
-const loadSession = (): Session | undefined => {
-  const data = localStorage.getItem("matrix-auth-store");
-  if (!data) {
-    return undefined;
-  }
-
-  return JSON.parse(data);
-};
-
-const clientIsDisconnected = (
-  syncState: SyncState,
-  syncData?: ISyncStateData,
-): boolean =>
-  syncState === "ERROR" && syncData?.error?.name === "ConnectionError";
@@ -0,0 +1,43 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test, vi } from "vitest";
+import { act, render } from "@testing-library/react";
+import { type MatrixClient } from "matrix-js-sdk";
+
+import { ClientProvider } from "./ClientContext";
+import { DisconnectedBanner } from "./DisconnectedBanner";
+import { hostClientSession } from "./state/ClientSession";
+
+test("shows while the client's sync fails to connect", () => {
+  const client = {
+    on: vi.fn(),
+    removeListener: vi.fn(),
+    getUserId: () => "@alice:example.org",
+  } as Partial<MatrixClient> as MatrixClient;
+  const { container } = render(
+    <ClientProvider session={hostClientSession(client)}>
+      <DisconnectedBanner />
+    </ClientProvider>,
+  );
+  expect(container.textContent).toBe("");
+
+  const [, onSync] = vi.mocked(client.on).mock.calls[0] as [
+    unknown,
+    (state: string, old: null, data?: { error?: Error }) => void,
+  ];
+  const connectionError = Object.assign(new Error("offline"), {
+    name: "ConnectionError",
+  });
+  act(() => onSync("ERROR", null, { error: connectionError }));
+  expect(container.textContent).not.toBe("");
+  // Any other failure is not a connection problem
+  act(() => onSync("ERROR", null, { error: new Error("rate limited") }));
+  expect(container.textContent).toBe("");
+  act(() => onSync("SYNCING", null));
+  expect(container.textContent).toBe("");
+});
@@ -6,30 +6,60 @@ Please see LICENSE in the repository root for full details.
 */

 import classNames from "classnames";
-import { type FC, type HTMLAttributes, type ReactNode } from "react";
+import {
+  type FC,
+  type HTMLAttributes,
+  type ReactNode,
+  useEffect,
+  useState,
+} from "react";
 import { useTranslation } from "react-i18next";
+import { ClientEvent, type MatrixClient } from "matrix-js-sdk";
+import { type ISyncStateData, type SyncState } from "matrix-js-sdk/lib/sync";

 import styles from "./DisconnectedBanner.module.css";
-import { type ValidClientState, useClientState } from "./ClientContext";
+import { useClient } from "./ClientContext";

 interface Props extends HTMLAttributes<HTMLElement> {
  children?: ReactNode;
  className?: string;
 }

+/**
+ * Shown while the signed-in client is supposed to be connected but is not.
+ */
 export const DisconnectedBanner: FC<Props> = ({
  children,
  className,
  ...rest
 }) => {
  const { t } = useTranslation();
-  const clientState = useClientState();
-  let shouldShowBanner = false;
+  const { client } = useClient();
+  // Tagged with the client it describes, so that a swapped client does not
+  // inherit the old one's verdict before its first sync
+  const [disconnected, setDisconnected] = useState<
+    [MatrixClient, boolean] | null
+  >(null);

-  if (clientState?.state === "valid") {
-    const validClientState = clientState as ValidClientState;
-    shouldShowBanner = validClientState.disconnected;
-  }
+  useEffect(() => {
+    if (client === undefined) return;
+    const onSync = (
+      syncState: SyncState,
+      _old: SyncState | null,
+      data?: ISyncStateData,
+    ): void => {
+      const clientIsDisconnected =
+        syncState === "ERROR" && data?.error?.name === "ConnectionError";
+      setDisconnected([client, clientIsDisconnected]);
+    };
+    client.on(ClientEvent.Sync, onSync);
+    return (): void => {
+      client.removeListener(ClientEvent.Sync, onSync);
+    };
+  }, [client]);
+
+  const shouldShowBanner =
+    disconnected !== null && disconnected[0] === client && disconnected[1];

  return (
    <>
@@ -0,0 +1,96 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { BrowserRouter } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+import { TooltipProvider } from "@vector-im/compound-web";
+import { BehaviorSubject } from "rxjs";
+
+import { ClientManagerProvider, ClientProvider } from "./ClientContext";
+import { LeaveToHomeProvider } from "./LeaveToHomeContext";
+import {
+  type ClientManager,
+  type ClientSession,
+  type ClientSessionState,
+  hostClientSession,
+} from "./state/ClientSession";
+import { UserMenuContainer } from "./UserMenuContainer";
+import { flushPromises } from "./utils/test";
+
+vi.mock("./settings/SettingsModal", () => ({
+  defaultSettingsTab: "audio",
+  SettingsModal: (): null => null,
+}));
+
+const mockClient = (): MatrixClient =>
+  ({
+    on: vi.fn(),
+    removeListener: vi.fn(),
+    getUserId: () => "@alice:example.org",
+    getUserIdLocalpart: () => "alice",
+    getDeviceId: () => "AAAA",
+    getUser: () => null,
+    stopClient: vi.fn(),
+  }) as Partial<MatrixClient> as MatrixClient;
+
+test("leaves for home after logging out of the session", async () => {
+  const logout = vi.fn().mockResolvedValue(undefined);
+  const leaveToHome = vi.fn();
+  renderMenu(
+    {
+      state$: new BehaviorSubject<ClientSessionState>({
+        state: "signedIn",
+        client: mockClient(),
+        passwordlessUser: false,
+      }),
+    },
+    { login: vi.fn(), register: vi.fn(), logout },
+    leaveToHome,
+  );
+
+  await selectSignOut();
+  expect(logout).toHaveBeenCalled();
+  expect(leaveToHome).toHaveBeenCalled();
+});
+
+test("cannot end a session that is not ours", async () => {
+  const leaveToHome = vi.fn();
+  renderMenu(hostClientSession(mockClient()), null, leaveToHome);
+
+  await selectSignOut();
+  expect(leaveToHome).not.toHaveBeenCalled();
+});
+
+async function selectSignOut(): Promise<void> {
+  const user = userEvent.setup();
+  await user.click(screen.getByTestId("usermenu_open"));
+  await user.click(await screen.findByTestId("usermenu_logout"));
+  await flushPromises();
+}
+
+function renderMenu(
+  session: ClientSession,
+  manager: ClientManager | null,
+  leaveToHome: (() => void) | null = null,
+): void {
+  render(
+    <BrowserRouter>
+      <TooltipProvider>
+        <LeaveToHomeProvider value={leaveToHome}>
+          <ClientProvider session={session}>
+            <ClientManagerProvider value={manager}>
+              <UserMenuContainer />
+            </ClientManagerProvider>
+          </ClientProvider>
+        </LeaveToHomeProvider>
+      </TooltipProvider>
+    </BrowserRouter>,
+  );
+}
@@ -9,7 +9,12 @@ import { type FC, useCallback, useState } from "react";
 import { useNavigate, useLocation } from "react-router-dom";
 import { logger } from "matrix-js-sdk/lib/logger";

-import { useClientLegacy } from "./ClientContext";
+import {
+  useClient,
+  useClientManagerIfAny,
+  useClientSessionState,
+} from "./ClientContext";
+import { useLeaveToHome } from "./LeaveToHomeContext";
 import { useProfile } from "./profile/useProfile";
 import { defaultSettingsTab, SettingsModal } from "./settings/SettingsModal";
 import { UserMenu } from "./UserMenu";
@@ -21,7 +26,13 @@ interface Props {
 export const UserMenuContainer: FC<Props> = ({ preventNavigation = false }) => {
  const location = useLocation();
  const navigate = useNavigate();
-  const { client, logout, authenticated, passwordlessUser } = useClientLegacy();
+  const { client } = useClient();
+  const session = useClientSessionState();
+  const passwordlessUser =
+    session.state === "signedIn" && session.passwordlessUser;
+  // Absent when the session is a host's, which Element Call cannot end
+  const logout = useClientManagerIfAny()?.logout;
+  const leaveToHome = useLeaveToHome();
  const { displayName, avatarUrl } = useProfile(client);
  const [settingsModalOpen, setSettingsModalOpen] = useState(false);
  const onDismissSettingsModal = useCallback(
@@ -43,7 +54,9 @@ export const UserMenuContainer: FC<Props> = ({ preventNavigation = false }) => {
          setSettingsModalOpen(true);
          break;
        case "logout":
-          logout?.();
+          logout?.()
+            .then(() => leaveToHome?.())
+            .catch((e) => logger.error("Failed to log out", e));
          break;
        case "login":
          navigate("/login", { state: { from: location } })?.catch((error) =>
@@ -52,7 +65,7 @@ export const UserMenuContainer: FC<Props> = ({ preventNavigation = false }) => {
          break;
      }
    },
-    [navigate, location, logout, setSettingsModalOpen],
+    [navigate, location, logout, leaveToHome, setSettingsModalOpen],
  );

  const userName = client?.getUserIdLocalpart() ?? "";
@@ -60,7 +73,7 @@ export const UserMenuContainer: FC<Props> = ({ preventNavigation = false }) => {
    <>
      <UserMenu
        preventNavigation={preventNavigation}
-        isAuthenticated={authenticated}
+        isAuthenticated={client !== undefined}
        isPasswordlessUser={passwordlessUser}
        avatarUrl={avatarUrl}
        onAction={onAction}
@@ -0,0 +1,78 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { type FC } from "react";
+import { MemoryRouter, useLocation } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+
+import { LoginPage } from "./LoginPage";
+import { ClientManagerProvider } from "../ClientContext";
+import { type ClientManager } from "../state/ClientSession";
+import { Config } from "../config/Config";
+
+beforeEach(() => {
+  vi.spyOn(Config, "defaultHomeserverUrl").mockReturnValue(
+    "https://hs.example.org",
+  );
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+test("signs in with the session's manager and goes home", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.login).mockResolvedValue({} as MatrixClient);
+  renderLogin(manager);
+
+  await submit("alice", "hunter2");
+
+  expect(manager.login).toHaveBeenCalledWith(
+    "https://hs.example.org",
+    "alice",
+    "hunter2",
+  );
+  expect(await screen.findByText("at /")).toBeVisible();
+});
+
+test("shows why signing in failed", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.login).mockRejectedValue(new Error("Wrong password"));
+  renderLogin(manager);
+
+  await submit("alice", "hunter2");
+
+  expect(await screen.findByText("Wrong password")).toBeVisible();
+  expect(screen.getByText("at /login")).toBeVisible();
+});
+
+async function submit(username: string, password: string): Promise<void> {
+  const user = userEvent.setup();
+  await user.type(screen.getByTestId("login_username"), username);
+  await user.type(screen.getByTestId("login_password"), password);
+  await user.click(screen.getByTestId("login_login"));
+}
+
+function mockManager(): ClientManager {
+  return { login: vi.fn(), register: vi.fn(), logout: vi.fn() };
+}
+
+const WhereAmI: FC = () => <span>at {useLocation().pathname}</span>;
+
+function renderLogin(manager: ClientManager): void {
+  render(
+    <MemoryRouter initialEntries={["/login"]}>
+      <ClientManagerProvider value={manager}>
+        <LoginPage />
+        <WhereAmI />
+      </ClientManagerProvider>
+    </MemoryRouter>,
+  );
+}
@@ -11,10 +11,9 @@ import { Trans, useTranslation } from "react-i18next";
 import { Button } from "@vector-im/compound-web";

 import Logo from "../icons/LogoLarge.svg?react";
-import { useClient } from "../ClientContext";
+import { useClientManager } from "../ClientContext";
 import { FieldRow, InputField, ErrorMessage } from "../input/Input";
 import styles from "./LoginPage.module.css";
-import { useInteractiveLogin } from "./useInteractiveLogin";
 import { usePageTitle } from "../usePageTitle";
 import { PosthogAnalytics } from "../analytics/PosthogAnalytics";
 import { Config } from "../config/Config";
@@ -24,8 +23,7 @@ export const LoginPage: FC = () => {
  const { t } = useTranslation();
  usePageTitle(t("login_title"));

-  const { client, setClient } = useClient();
-  const login = useInteractiveLogin(client);
+  const { login } = useClientManager();
  const homeserver = Config.defaultHomeserverUrl(); // TODO: Make this configurable
  const usernameRef = useRef<HTMLInputElement>(null);
  const passwordRef = useRef<HTMLInputElement>(null);
@@ -46,15 +44,8 @@ export const LoginPage: FC = () => {
        setLoading(false);
        return;
      }
-
      login(homeserver, usernameRef.current.value, passwordRef.current.value)
-        .then(async ([client, session]) => {
-          if (!setClient) {
-            return;
-          }
-
-          setClient(client, session);
-
+        .then(async () => {
          const locationState = location.state;
          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
          // @ts-ignore
@@ -72,7 +63,7 @@ export const LoginPage: FC = () => {
          setLoading(false);
        });
    },
-    [login, location, navigate, homeserver, setClient],
+    [login, location, navigate, homeserver],
  );
  // we need to limit the length of the homserver name to not cover the whole loginview input with the string.
  let shortendHomeserverName = Config.defaultServerName()?.slice(0, 25);
@@ -0,0 +1,133 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { type FC } from "react";
+import { MemoryRouter, useLocation } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+import { BehaviorSubject } from "rxjs";
+
+import { RegisterPage } from "./RegisterPage";
+import { ClientContextProvider, ClientManagerProvider } from "../ClientContext";
+import {
+  type ClientManager,
+  type ClientSessionState,
+} from "../state/ClientSession";
+
+vi.mock("./useRecaptcha", () => ({
+  useRecaptcha: () => ({
+    execute: vi.fn().mockResolvedValue("captcha-response"),
+    reset,
+    recaptchaId: "recaptcha",
+  }),
+}));
+vi.mock("./useRegistrationTerms", () => ({
+  useRegistrationTerms: () => ({ recaptchaKey: "site-key" }),
+}));
+
+const reset = vi.fn();
+
+afterEach(() => vi.clearAllMocks());
+
+test("waits for the session to be restored", () => {
+  renderRegister({ state: "loading" }, mockManager());
+  expect(screen.getByRole("heading", { name: "Loading…" })).toBeVisible();
+});
+
+test("registers an account, signs in and goes home", async () => {
+  const manager = mockManager();
+  const setSignedIn = vi.fn();
+  vi.mocked(manager.register).mockResolvedValue({
+    client: {} as MatrixClient,
+    setSignedIn,
+  });
+  renderRegister({ state: "signedOut" }, manager);
+
+  await submit("alice", "hunter2");
+
+  expect(manager.register).toHaveBeenCalledWith(
+    "alice",
+    "hunter2",
+    "alice",
+    "captcha-response",
+    false,
+  );
+  expect(setSignedIn).toHaveBeenCalled();
+  expect(await screen.findByText("at /")).toBeVisible();
+});
+
+test("upgrades a passwordless user to a full account", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.register).mockResolvedValue({
+    client: {} as MatrixClient,
+    setSignedIn: vi.fn(),
+  });
+  renderRegister(
+    {
+      state: "signedIn",
+      client: { getUserId: () => "@guest:example.org" } as MatrixClient,
+      passwordlessUser: true,
+    },
+    manager,
+  );
+
+  await submit("alice", "hunter2");
+
+  expect(manager.register).toHaveBeenCalledWith(
+    "alice",
+    "hunter2",
+    "alice",
+    "captcha-response",
+    true,
+  );
+});
+
+test("shows why registering failed and resets the captcha", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.register).mockRejectedValue(new Error("Name taken"));
+  renderRegister({ state: "signedOut" }, manager);
+
+  await submit("alice", "hunter2");
+
+  expect(await screen.findByText("Name taken")).toBeVisible();
+  expect(reset).toHaveBeenCalled();
+  expect(screen.getByText("at /register")).toBeVisible();
+});
+
+async function submit(username: string, password: string): Promise<void> {
+  const user = userEvent.setup();
+  await user.type(screen.getByTestId("register_username"), username);
+  await user.type(screen.getByTestId("register_password"), password);
+  await user.type(screen.getByTestId("register_confirm_password"), password);
+  await user.click(screen.getByTestId("register_register"));
+}
+
+function mockManager(): ClientManager {
+  return { login: vi.fn(), register: vi.fn(), logout: vi.fn() };
+}
+
+const WhereAmI: FC = () => <span>at {useLocation().pathname}</span>;
+
+function renderRegister(
+  state: ClientSessionState,
+  manager: ClientManager,
+): void {
+  render(
+    <MemoryRouter initialEntries={["/register"]}>
+      <ClientContextProvider
+        value={{ state$: new BehaviorSubject<ClientSessionState>(state) }}
+      >
+        <ClientManagerProvider value={manager}>
+          <RegisterPage />
+          <WhereAmI />
+        </ClientManagerProvider>
+      </ClientContextProvider>
+    </MemoryRouter>,
+  );
+}
@@ -22,8 +22,12 @@ import { logger } from "matrix-js-sdk/lib/logger";
 import { Button, Text } from "@vector-im/compound-web";

 import { FieldRow, InputField, ErrorMessage } from "../input/Input";
-import { useClientLegacy } from "../ClientContext";
-import { useInteractiveRegistration } from "./useInteractiveRegistration";
+import {
+  useClient,
+  useClientManager,
+  useClientSessionState,
+} from "../ClientContext";
+import { useRegistrationTerms } from "./useRegistrationTerms";
 import styles from "./LoginPage.module.css";
 import Logo from "../icons/LogoLarge.svg?react";
 import { LoadingPage } from "../FullScreenView";
@@ -37,8 +41,13 @@ export const RegisterPage: FC = () => {
  const { t } = useTranslation();
  usePageTitle(t("action.register"));

-  const { loading, authenticated, passwordlessUser, client, setClient } =
-    useClientLegacy();
+  const session = useClientSessionState();
+  const loading = session.state === "loading";
+  const passwordlessUser =
+    session.state === "signedIn" && session.passwordlessUser;
+  const { client } = useClient();
+  const authenticated = client !== undefined;
+  const { register } = useClientManager();

  const confirmPasswordRef = useRef<HTMLInputElement>(null);
  const navigate = useNavigate();
@@ -47,7 +56,7 @@ export const RegisterPage: FC = () => {
  const [error, setError] = useState<Error>();
  const [password, setPassword] = useState("");
  const [passwordConfirmation, setPasswordConfirmation] = useState("");
-  const { recaptchaKey, register } = useInteractiveRegistration(client);
+  const { recaptchaKey } = useRegistrationTerms();
  const { execute, reset, recaptchaId } = useRecaptcha(recaptchaKey);

  const onSubmitRegisterForm = useCallback(
@@ -64,7 +73,7 @@ export const RegisterPage: FC = () => {
        setRegistering(true);

        const recaptchaResponse = await execute();
-        const [newClient, session] = await register(
+        const { client: newClient, setSignedIn } = await register(
          userName,
          password,
          userName,
@@ -95,7 +104,7 @@ export const RegisterPage: FC = () => {
          }
        }

-        setClient?.(newClient, session);
+        setSignedIn();
        PosthogAnalytics.instance.eventSignup.cacheSignupEnd(new Date());
      };

@@ -117,16 +126,7 @@ export const RegisterPage: FC = () => {
          reset();
        });
    },
-    [
-      register,
-      location,
-      navigate,
-      passwordlessUser,
-      reset,
-      execute,
-      client,
-      setClient,
-    ],
+    [register, location, navigate, passwordlessUser, reset, execute, client],
  );

  useEffect(() => {
@@ -0,0 +1,104 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, expect, test, vi } from "vitest";
+import { createClient, type MatrixClient, MatrixError } from "matrix-js-sdk";
+import type * as MatrixJsSdk from "matrix-js-sdk";
+
+import { loginWithPassword, registerWithPassword } from "./interactiveAuth";
+
+vi.mock("matrix-js-sdk", async (importOriginal) => ({
+  ...(await importOriginal<typeof MatrixJsSdk>()),
+  createClient: vi.fn(),
+}));
+
+const credentials = {
+  user_id: "@alice:example.org",
+  device_id: "AAAA",
+  access_token: "secret",
+};
+
+// What interactive auth asks of the client besides the request itself
+const authClient = { generateClientSecret: () => "client-secret" };
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+test("logs in with a password", async () => {
+  const login = vi.fn().mockResolvedValue({ ...credentials, extra: "ignored" });
+  vi.mocked(createClient).mockReturnValue({
+    ...authClient,
+    login,
+  } as Partial<MatrixClient> as MatrixClient);
+
+  await expect(
+    loginWithPassword("https://hs.example.org", "alice", "hunter2"),
+  ).resolves.toEqual(credentials);
+
+  expect(createClient).toHaveBeenCalledWith({
+    baseUrl: "https://hs.example.org",
+  });
+  expect(login).toHaveBeenCalledWith("m.login.password", {
+    identifier: { type: "m.id.user", user: "alice" },
+    password: "hunter2",
+  });
+});
+
+test("registers, agreeing to the terms and answering the recaptcha", async () => {
+  // The homeserver turns the first request away with the stages to complete
+  // No error in it: that is the shape of a challenge rather than a refusal
+  const challenge = new MatrixError(
+    {
+      session: "session",
+      flows: [{ stages: ["m.login.terms", "m.login.recaptcha"] }],
+      params: {},
+      completed: [],
+    },
+    401,
+  );
+  const registerRequest = vi
+    .fn()
+    .mockImplementation(({ auth }: { auth?: { type: string } }) => {
+      if (auth === undefined) throw challenge;
+      challenge.data.completed = [
+        ...(challenge.data.completed as string[]),
+        auth.type,
+      ];
+      if (challenge.data.completed.length < 2) throw challenge;
+      return credentials;
+    });
+  vi.mocked(createClient).mockReturnValue({
+    ...authClient,
+    registerRequest,
+  } as Partial<MatrixClient> as MatrixClient);
+
+  await expect(
+    registerWithPassword(
+      "https://hs.example.org",
+      "alice",
+      "hunter2",
+      "captcha",
+    ),
+  ).resolves.toEqual(credentials);
+
+  expect(registerRequest).toHaveBeenCalledWith(
+    expect.objectContaining({
+      username: "alice",
+      password: "hunter2",
+      auth: expect.objectContaining({ type: "m.login.terms" }),
+    }),
+  );
+  expect(registerRequest).toHaveBeenCalledWith(
+    expect.objectContaining({
+      auth: expect.objectContaining({
+        type: "m.login.recaptcha",
+        response: "captcha",
+      }),
+    }),
+  );
+});
@@ -0,0 +1,106 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  createClient,
+  InteractiveAuth,
+  type LoginResponse,
+  type RegisterResponse,
+} from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+import { type StoredSession } from "../state/ClientSession";
+
+/** What the homeserver hands out for a new session. */
+export type Credentials = Pick<
+  StoredSession,
+  "user_id" | "device_id" | "access_token"
+>;
+
+/**
+ * Logs in to the given homeserver with a password.
+ */
+export async function loginWithPassword(
+  homeserver: string,
+  username: string,
+  password: string,
+): Promise<Credentials> {
+  const authClient = createClient({ baseUrl: homeserver });
+  const interactiveAuth = new InteractiveAuth({
+    matrixClient: authClient,
+    doRequest: async (): Promise<LoginResponse> =>
+      authClient.login("m.login.password", {
+        identifier: {
+          type: "m.id.user",
+          user: username,
+        },
+        password,
+      }),
+    stateUpdated: (): void => {},
+    requestEmailToken: async (): Promise<{ sid: string }> =>
+      Promise.resolve({ sid: "" }),
+  });
+  return credentials(await interactiveAuth.attemptAuth());
+}
+
+/**
+ * Registers an account on the given homeserver, accepting its terms and
+ * answering its recaptcha challenge.
+ */
+export async function registerWithPassword(
+  homeserver: string,
+  username: string,
+  password: string,
+  recaptchaResponse: string,
+): Promise<Credentials> {
+  const authClient = createClient({ baseUrl: homeserver });
+  const interactiveAuth = new InteractiveAuth({
+    matrixClient: authClient,
+    doRequest: async (auth): Promise<RegisterResponse> =>
+      authClient.registerRequest({
+        username,
+        password,
+        auth: auth || undefined,
+      }),
+    stateUpdated: (nextStage, status): void => {
+      if (status.error) {
+        throw new Error(status.error);
+      }
+
+      if (nextStage === "m.login.terms") {
+        interactiveAuth
+          .submitAuthDict({
+            type: "m.login.terms",
+          })
+          .catch((e) => {
+            logger.error(e);
+          });
+      } else if (nextStage === "m.login.recaptcha") {
+        interactiveAuth
+          .submitAuthDict({
+            type: "m.login.recaptcha",
+            response: recaptchaResponse,
+          })
+          .catch((e) => {
+            logger.error(e);
+          });
+      }
+    },
+    requestEmailToken: async (): Promise<{ sid: string }> =>
+      Promise.resolve({ sid: "dummy" }),
+  });
+  return credentials(await interactiveAuth.attemptAuth());
+}
+
+// XXX: attemptAuth claims to return an IAuthData which contains none of these
+// things - the js-sdk types may be wrong?
+function credentials(authData: unknown): Credentials {
+  /* eslint-disable camelcase */
+  const { user_id, access_token, device_id } = authData as Credentials;
+  return { user_id, access_token, device_id };
+  /* eslint-enable camelcase */
+}
@@ -1,84 +0,0 @@
-/*
-Copyright 2022-2024 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import { useCallback } from "react";
-import { InteractiveAuth } from "matrix-js-sdk";
-import {
-  createClient,
-  type LoginResponse,
-  type MatrixClient,
-} from "matrix-js-sdk";
-
-import { initClient } from "../utils/matrix";
-import { type Session } from "../ClientContext";
-/**
- * This provides the login method to login using user credentials.
- * @param oldClient If there is an already authenticated client it should be passed to this hook
- * this allows the interactive login to sign out the client before logging in.
- * @returns A async method that can be called/awaited to log in with the provided credentials.
- */
-export function useInteractiveLogin(
-  oldClient?: MatrixClient,
-): (
-  homeserver: string,
-  username: string,
-  password: string,
-) => Promise<[MatrixClient, Session]> {
-  return useCallback<
-    (
-      homeserver: string,
-      username: string,
-      password: string,
-    ) => Promise<[MatrixClient, Session]>
-  >(
-    async (homeserver: string, username: string, password: string) => {
-      const authClient = createClient({ baseUrl: homeserver });
-
-      const interactiveAuth = new InteractiveAuth({
-        matrixClient: authClient,
-        doRequest: async (): Promise<LoginResponse> =>
-          authClient.login("m.login.password", {
-            identifier: {
-              type: "m.id.user",
-              user: username,
-            },
-            password,
-          }),
-        stateUpdated: (): void => {},
-        requestEmailToken: async (): Promise<{ sid: string }> =>
-          Promise.resolve({ sid: "" }),
-      });
-
-      // XXX: This claims to return an IAuthData which contains none of these
-      // things - the js-sdk types may be wrong?
-      /* eslint-disable camelcase,@typescript-eslint/no-explicit-any */
-      const { user_id, access_token, device_id } =
-        (await interactiveAuth.attemptAuth()) as any;
-      const session = {
-        user_id,
-        access_token,
-        device_id,
-        passwordlessUser: false,
-      };
-
-      // To not confuse the rust crypto sessions we need to logout the old client before initializing the new one.
-      await oldClient?.logout(true);
-      const client = await initClient(
-        {
-          baseUrl: homeserver,
-          accessToken: access_token,
-          userId: user_id,
-          deviceId: device_id,
-        },
-        false,
-      );
-      /* eslint-enable camelcase */
-      return [client, session];
-    },
-    [oldClient],
-  );
-}
@@ -1,145 +0,0 @@
-/*
-Copyright 2022-2024 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import { InteractiveAuth } from "matrix-js-sdk";
-import {
-  createClient,
-  type MatrixClient,
-  type RegisterResponse,
-} from "matrix-js-sdk";
-import { logger } from "matrix-js-sdk/lib/logger";
-
-import { initClient } from "../utils/matrix";
-import { type Session } from "../ClientContext";
-import { Config } from "../config/Config";
-import { useUrlParams } from "../UrlParams";
-
-export const useInteractiveRegistration = (
-  oldClient?: MatrixClient,
-): {
-  privacyPolicyUrl?: string;
-  recaptchaKey?: string;
-  register: (
-    username: string,
-    password: string,
-    displayName: string,
-    recaptchaResponse: string,
-    passwordlessUser: boolean,
-  ) => Promise<[MatrixClient, Session]>;
-} => {
-  const { isWidget } = useUrlParams();
-  const [privacyPolicyUrl, setPrivacyPolicyUrl] = useState<string | undefined>(
-    undefined,
-  );
-  const [recaptchaKey, setRecaptchaKey] = useState<string | undefined>(
-    undefined,
-  );
-
-  const authClient = useRef<MatrixClient | undefined>(undefined);
-  if (!authClient.current) {
-    authClient.current = createClient({
-      baseUrl: Config.defaultHomeserverUrl()!,
-    });
-  }
-
-  useEffect(() => {
-    if (isWidget) return;
-    // An empty registerRequest is used to get the privacy policy and recaptcha key.
-    authClient.current!.registerRequest({}).catch((error) => {
-      setPrivacyPolicyUrl(
-        error.data?.params["m.login.terms"]?.policies?.privacy_policy?.en?.url,
-      );
-      setRecaptchaKey(error.data?.params["m.login.recaptcha"]?.public_key);
-    });
-  }, [isWidget]);
-
-  const register = useCallback(
-    async (
-      username: string,
-      password: string,
-      displayName: string,
-      recaptchaResponse: string,
-      passwordlessUser: boolean,
-    ): Promise<[MatrixClient, Session]> => {
-      const interactiveAuth = new InteractiveAuth({
-        matrixClient: authClient.current!,
-        doRequest: async (auth): Promise<RegisterResponse> =>
-          authClient.current!.registerRequest({
-            username,
-            password,
-            auth: auth || undefined,
-          }),
-        stateUpdated: (nextStage, status): void => {
-          if (status.error) {
-            throw new Error(status.error);
-          }
-
-          if (nextStage === "m.login.terms") {
-            interactiveAuth
-              .submitAuthDict({
-                type: "m.login.terms",
-              })
-              .catch((e) => {
-                logger.error(e);
-              });
-          } else if (nextStage === "m.login.recaptcha") {
-            interactiveAuth
-              .submitAuthDict({
-                type: "m.login.recaptcha",
-                response: recaptchaResponse,
-              })
-              .catch((e) => {
-                logger.error(e);
-              });
-          }
-        },
-        requestEmailToken: async (): Promise<{ sid: string }> =>
-          Promise.resolve({ sid: "dummy" }),
-      });
-
-      // XXX: This claims to return an IAuthData which contains none of these
-      // things - the js-sdk types may be wrong?
-      /* eslint-disable camelcase,@typescript-eslint/no-explicit-any */
-      const { user_id, access_token, device_id } =
-        (await interactiveAuth.attemptAuth()) as any;
-      await oldClient?.logout(true);
-      const client = await initClient(
-        {
-          baseUrl: Config.defaultHomeserverUrl()!,
-          accessToken: access_token,
-          userId: user_id,
-          deviceId: device_id,
-        },
-        false,
-      );
-
-      await client.setDisplayName(displayName);
-
-      const session: Session = {
-        user_id,
-        device_id,
-        access_token,
-        passwordlessUser,
-      };
-      /* eslint-enable camelcase */
-
-      if (passwordlessUser) {
-        session.tempPassword = password;
-      }
-
-      const user = client.getUser(client.getUserId()!)!;
-      user.setRawDisplayName(displayName);
-      user.setDisplayName(displayName);
-
-      return [client, session];
-    },
-    [oldClient],
-  );
-
-  return { privacyPolicyUrl, recaptchaKey, register };
-};
@@ -0,0 +1,116 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, expect, test, vi } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { type FC, type PropsWithChildren } from "react";
+import { type MatrixClient } from "matrix-js-sdk";
+
+import { useRegisterPasswordlessUser } from "./useRegisterPasswordlessUser";
+import { ClientManagerProvider } from "../ClientContext";
+import { type ClientManager } from "../state/ClientSession";
+import { computeUrlParams, UrlParamsProvider } from "../UrlParams";
+
+vi.mock("./useRecaptcha", () => ({
+  useRecaptcha: () => ({
+    execute: vi.fn().mockResolvedValue("captcha-response"),
+    reset,
+    recaptchaId: "recaptcha",
+  }),
+}));
+vi.mock("./useRegistrationTerms", () => ({
+  useRegistrationTerms: () => ({
+    privacyPolicyUrl: "https://hs.example.org/privacy",
+    recaptchaKey: "site-key",
+  }),
+}));
+vi.mock("./generateRandomName", () => ({
+  generateRandomName: () => "Random Name",
+}));
+
+const reset = vi.fn();
+
+afterEach(() => vi.clearAllMocks());
+
+test("registers a user under a random name and signs them in", async () => {
+  const setSignedIn = vi.fn();
+  const manager = mockManager();
+  vi.mocked(manager.register).mockResolvedValue({
+    client: {} as MatrixClient,
+    setSignedIn,
+  });
+
+  const { result } = renderHook(() => useRegisterPasswordlessUser(), {
+    wrapper: wrapper(manager, false),
+  });
+  await result.current.registerPasswordlessUser("Alice");
+
+  expect(manager.register).toHaveBeenCalledWith(
+    "Random Name",
+    expect.stringMatching(/^.{16}$/),
+    "Alice",
+    "captcha-response",
+    true,
+  );
+  expect(setSignedIn).toHaveBeenCalled();
+  expect(result.current.privacyPolicyUrl).toBe(
+    "https://hs.example.org/privacy",
+  );
+  expect(result.current.recaptchaId).toBe("recaptcha");
+});
+
+test("resets the captcha when registration fails", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.register).mockRejectedValue(new Error("Nope"));
+
+  const { result } = renderHook(() => useRegisterPasswordlessUser(), {
+    wrapper: wrapper(manager, false),
+  });
+
+  await expect(
+    result.current.registerPasswordlessUser("Alice"),
+  ).rejects.toThrow("Nope");
+  expect(reset).toHaveBeenCalled();
+});
+
+test("cannot register on a session that is not ours", async () => {
+  const { result } = renderHook(() => useRegisterPasswordlessUser(), {
+    wrapper: wrapper(null, false),
+  });
+
+  await expect(
+    result.current.registerPasswordlessUser("Alice"),
+  ).rejects.toThrow("This session cannot register");
+});
+
+test("never registers as a widget", async () => {
+  const manager = mockManager();
+  const { result } = renderHook(() => useRegisterPasswordlessUser(), {
+    wrapper: wrapper(manager, true),
+  });
+
+  await expect(
+    result.current.registerPasswordlessUser("Alice"),
+  ).rejects.toThrow(/embedded mode/);
+  expect(manager.register).not.toHaveBeenCalled();
+});
+
+function mockManager(): ClientManager {
+  return { login: vi.fn(), register: vi.fn(), logout: vi.fn() };
+}
+
+function wrapper(
+  manager: ClientManager | null,
+  isWidget: boolean,
+): FC<PropsWithChildren> {
+  const params = { ...computeUrlParams(), isWidget };
+  return ({ children }) => (
+    <UrlParamsProvider value={params}>
+      <ClientManagerProvider value={manager}>{children}</ClientManagerProvider>
+    </UrlParamsProvider>
+  );
+}
@@ -8,8 +8,8 @@ Please see LICENSE in the repository root for full details.
 import { useCallback } from "react";
 import { secureRandomString } from "matrix-js-sdk/lib/randomstring";

-import { useClient } from "../ClientContext";
-import { useInteractiveRegistration } from "../auth/useInteractiveRegistration";
+import { useClientManagerIfAny } from "../ClientContext";
+import { useRegistrationTerms } from "../auth/useRegistrationTerms";
 import { generateRandomName } from "../auth/generateRandomName";
 import { useRecaptcha } from "../auth/useRecaptcha";
 import { useUrlParams } from "../UrlParams";
@@ -21,16 +21,16 @@ interface UseRegisterPasswordlessUserType {
 }

 export function useRegisterPasswordlessUser(): UseRegisterPasswordlessUserType {
-  const { setClient } = useClient();
+  // Null in the widget, which never registers anyone
+  const register = useClientManagerIfAny()?.register;
  const { isWidget } = useUrlParams();
-  const { privacyPolicyUrl, recaptchaKey, register } =
-    useInteractiveRegistration();
+  const { privacyPolicyUrl, recaptchaKey } = useRegistrationTerms();
  const { execute, reset, recaptchaId } = useRecaptcha(recaptchaKey);

  const registerPasswordlessUser = useCallback(
    async (displayName: string) => {
-      if (!setClient) {
-        throw new Error("No client context");
+      if (!register) {
+        throw new Error("This session cannot register");
      }
      if (isWidget) {
        throw new Error(
@@ -41,20 +41,20 @@ export function useRegisterPasswordlessUser(): UseRegisterPasswordlessUserType {
      try {
        const recaptchaResponse = await execute();
        const userName = generateRandomName();
-        const [client, session] = await register(
+        const { setSignedIn } = await register(
          userName,
          secureRandomString(16),
          displayName,
          recaptchaResponse,
          true,
        );
-        setClient(client, session);
+        setSignedIn();
      } catch (e) {
        reset();
        throw e;
      }
    },
-    [execute, reset, register, setClient, isWidget],
+    [execute, reset, register, isWidget],
  );

  return { privacyPolicyUrl, registerPasswordlessUser, recaptchaId };
@@ -0,0 +1,98 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type * as MatrixJsSdk from "matrix-js-sdk";
+import { createClient, type MatrixClient } from "matrix-js-sdk";
+import { type FC, type PropsWithChildren } from "react";
+
+import { useRegistrationTerms } from "./useRegistrationTerms";
+import { computeUrlParams, UrlParamsProvider } from "../UrlParams";
+import { Config } from "../config/Config";
+
+vi.mock("matrix-js-sdk", async (importOriginal) => ({
+  ...(await importOriginal<typeof MatrixJsSdk>()),
+  createClient: vi.fn(),
+}));
+
+const registerRequest = vi.fn();
+
+beforeEach(() => {
+  vi.spyOn(Config, "defaultHomeserverUrl").mockReturnValue(
+    "https://hs.example.org",
+  );
+  vi.mocked(createClient).mockReturnValue({
+    registerRequest,
+  } as Partial<MatrixClient> as MatrixClient);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+test("reads the terms the homeserver asks for from a registration attempt", async () => {
+  registerRequest.mockRejectedValue({
+    data: {
+      params: {
+        "m.login.terms": {
+          policies: {
+            privacy_policy: { en: { url: "https://hs.example.org/privacy" } },
+          },
+        },
+        "m.login.recaptcha": { public_key: "site-key" },
+      },
+    },
+  });
+
+  const { result } = renderHook(() => useRegistrationTerms(), {
+    wrapper: wrapper(false),
+  });
+
+  expect(createClient).toHaveBeenCalledWith({
+    baseUrl: "https://hs.example.org",
+  });
+  await waitFor(() =>
+    expect(result.current).toEqual({
+      privacyPolicyUrl: "https://hs.example.org/privacy",
+      recaptchaKey: "site-key",
+    }),
+  );
+});
+
+test("has nothing to agree to where the homeserver asks for nothing", async () => {
+  registerRequest.mockRejectedValue({ data: { params: {} } });
+
+  const { result } = renderHook(() => useRegistrationTerms(), {
+    wrapper: wrapper(false),
+  });
+
+  await waitFor(() => expect(registerRequest).toHaveBeenCalled());
+  expect(result.current).toEqual({
+    privacyPolicyUrl: undefined,
+    recaptchaKey: undefined,
+  });
+});
+
+test("asks the homeserver nothing as a widget", () => {
+  const { result } = renderHook(() => useRegistrationTerms(), {
+    wrapper: wrapper(true),
+  });
+
+  expect(createClient).not.toHaveBeenCalled();
+  expect(result.current).toEqual({
+    privacyPolicyUrl: undefined,
+    recaptchaKey: undefined,
+  });
+});
+
+function wrapper(isWidget: boolean): FC<PropsWithChildren> {
+  const params = { ...computeUrlParams(), isWidget };
+  return ({ children }) => (
+    <UrlParamsProvider value={params}>{children}</UrlParamsProvider>
+  );
+}
@@ -0,0 +1,46 @@
+/*
+Copyright 2022-2024 New Vector Ltd.
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { useEffect, useState } from "react";
+import { createClient } from "matrix-js-sdk";
+
+import { Config } from "../config/Config";
+import { useUrlParams } from "../UrlParams";
+
+/**
+ * What the homeserver asks of a registration: its privacy policy to agree to
+ * and the recaptcha key to answer a challenge with.
+ */
+export function useRegistrationTerms(): {
+  privacyPolicyUrl?: string;
+  recaptchaKey?: string;
+} {
+  const { isWidget } = useUrlParams();
+  const [privacyPolicyUrl, setPrivacyPolicyUrl] = useState<string | undefined>(
+    undefined,
+  );
+  const [recaptchaKey, setRecaptchaKey] = useState<string | undefined>(
+    undefined,
+  );
+
+  useEffect(() => {
+    if (isWidget) return;
+    // An empty registerRequest is used to get the privacy policy and recaptcha key.
+    createClient({ baseUrl: Config.defaultHomeserverUrl()! })
+      .registerRequest({})
+      .catch((error) => {
+        setPrivacyPolicyUrl(
+          error.data?.params["m.login.terms"]?.policies?.privacy_policy?.en
+            ?.url,
+        );
+        setRecaptchaKey(error.data?.params["m.login.recaptcha"]?.public_key);
+      });
+  }, [isWidget]);
+
+  return { privacyPolicyUrl, recaptchaKey };
+}
@@ -0,0 +1,62 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { BrowserRouter } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+import { BehaviorSubject } from "rxjs";
+
+import { HomePage } from "./HomePage";
+import { ClientContextProvider } from "../ClientContext";
+import { type ClientSessionState } from "../state/ClientSession";
+
+vi.mock("./RegisteredView", () => ({
+  RegisteredView: ({ client }: { client: MatrixClient }) => (
+    <span>registered as {client.getUserId()}</span>
+  ),
+}));
+vi.mock("./UnauthenticatedView", () => ({
+  UnauthenticatedView: () => <span>unauthenticated</span>,
+}));
+
+test("waits for the session to be restored", () => {
+  renderHome({ state: "loading" });
+  expect(screen.getByRole("heading", { name: "Loading…" })).toBeVisible();
+});
+
+test("shows the session's error", () => {
+  vi.spyOn(console, "error").mockImplementation(() => {});
+  renderHome({ state: "error", error: new Error("Opened elsewhere") });
+  expect(screen.getByText("Something went wrong")).toBeVisible();
+});
+
+test("welcomes a signed-in user", () => {
+  renderHome({
+    state: "signedIn",
+    client: { getUserId: () => "@alice:example.org" } as MatrixClient,
+    passwordlessUser: false,
+  });
+  expect(screen.getByText("registered as @alice:example.org")).toBeVisible();
+});
+
+test("invites a signed-out user to start a call", () => {
+  renderHome({ state: "signedOut" });
+  expect(screen.getByText("unauthenticated")).toBeVisible();
+});
+
+function renderHome(state: ClientSessionState): void {
+  render(
+    <BrowserRouter>
+      <ClientContextProvider
+        value={{ state$: new BehaviorSubject<ClientSessionState>(state) }}
+      >
+        <HomePage />
+      </ClientContextProvider>
+    </BrowserRouter>,
+  );
+}
@@ -8,7 +8,7 @@ Please see LICENSE in the repository root for full details.
 import { useTranslation } from "react-i18next";
 import { type FC } from "react";

-import { useClientState } from "../ClientContext";
+import { useClientSessionState } from "../ClientContext";
 import { ErrorPage, LoadingPage } from "../FullScreenView";
 import { UnauthenticatedView } from "./UnauthenticatedView";
 import { RegisteredView } from "./RegisteredView";
@@ -18,17 +18,16 @@ export const HomePage: FC = () => {
  const { t } = useTranslation();
  usePageTitle(t("common.home"));

-  const clientState = useClientState();
+  const session = useClientSessionState();

-  if (!clientState) {
-    return <LoadingPage />;
-  } else if (clientState.state === "error") {
-    return <ErrorPage error={clientState.error} />;
-  } else {
-    return clientState.authenticated ? (
-      <RegisteredView client={clientState.authenticated.client} />
-    ) : (
-      <UnauthenticatedView />
-    );
+  switch (session.state) {
+    case "loading":
+      return <LoadingPage />;
+    case "error":
+      return <ErrorPage error={session.error} />;
+    case "signedIn":
+      return <RegisteredView client={session.client} />;
+    case "signedOut":
+      return <UnauthenticatedView />;
  }
 };
@@ -0,0 +1,136 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { type FC } from "react";
+import { MemoryRouter, useLocation } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+
+import { UnauthenticatedView } from "./UnauthenticatedView";
+import { ClientManagerProvider } from "../ClientContext";
+import { type ClientManager } from "../state/ClientSession";
+import { computeUrlParams, UrlParamsProvider } from "../UrlParams";
+import type * as matrixUtils from "../utils/matrix";
+import { createRoom, getRelativeRoomUrl } from "../utils/matrix";
+import { E2eeType } from "../e2ee/e2eeType";
+
+vi.mock("../auth/useRecaptcha", () => ({
+  useRecaptcha: () => ({
+    execute: vi.fn().mockResolvedValue("captcha-response"),
+    reset,
+    recaptchaId: "recaptcha",
+  }),
+}));
+vi.mock("../auth/useRegistrationTerms", () => ({
+  useRegistrationTerms: () => ({ recaptchaKey: "site-key" }),
+}));
+vi.mock("../auth/generateRandomName", () => ({
+  generateRandomName: () => "Random Name",
+}));
+vi.mock("../utils/matrix", async (importOriginal) => ({
+  ...(await importOriginal<typeof matrixUtils>()),
+  createRoom: vi.fn(),
+}));
+vi.mock("../UserMenuContainer", () => ({ UserMenuContainer: () => null }));
+
+const reset = vi.fn();
+const client = {} as MatrixClient;
+
+afterEach(() => vi.clearAllMocks());
+
+test("registers a guest, creates their call and signs them in", async () => {
+  const manager = mockManager();
+  const setSignedIn = vi.fn();
+  vi.mocked(manager.register).mockResolvedValue({ client, setSignedIn });
+  vi.mocked(createRoom).mockResolvedValue({
+    roomId: "!call:example.org",
+    alias: "#my-call:example.org",
+    password: "secret",
+  });
+  renderView(manager);
+
+  await submit("My Call", "Alice");
+
+  expect(manager.register).toHaveBeenCalledWith(
+    "Random Name",
+    expect.stringMatching(/^.{16}$/),
+    "Alice",
+    "captcha-response",
+    true,
+  );
+  expect(createRoom).toHaveBeenCalledWith(
+    client,
+    "My Call",
+    E2eeType.SHARED_KEY,
+  );
+  expect(setSignedIn).toHaveBeenCalled();
+  const url = getRelativeRoomUrl(
+    "!call:example.org",
+    { kind: E2eeType.SHARED_KEY, secret: "secret" },
+    "My Call",
+  );
+  expect(await screen.findByText(`at ${url}`)).toBeVisible();
+});
+
+test("signs in only once the user chooses to join a call that exists", async () => {
+  const manager = mockManager();
+  const setSignedIn = vi.fn();
+  vi.mocked(manager.register).mockResolvedValue({ client, setSignedIn });
+  vi.mocked(createRoom).mockRejectedValue({ errcode: "M_ROOM_IN_USE" });
+  renderView(manager);
+
+  await submit("My Call", "Alice");
+
+  const join = await screen.findByRole("button", { name: "Yes, join call" });
+  expect(setSignedIn).not.toHaveBeenCalled();
+  await userEvent.click(join);
+  expect(setSignedIn).toHaveBeenCalled();
+  expect(await screen.findByText("at /my-call")).toBeVisible();
+});
+
+test("shows why registering failed and resets the captcha", async () => {
+  const manager = mockManager();
+  vi.mocked(manager.register).mockRejectedValue(new Error("Rate limited"));
+  renderView(manager);
+
+  await submit("My Call", "Alice");
+
+  expect(await screen.findByText("Rate limited")).toBeVisible();
+  expect(reset).toHaveBeenCalled();
+  expect(createRoom).not.toHaveBeenCalled();
+});
+
+async function submit(callName: string, displayName: string): Promise<void> {
+  const user = userEvent.setup();
+  await user.type(screen.getByTestId("home_callName"), callName);
+  await user.type(screen.getByTestId("home_displayName"), displayName);
+  await user.click(screen.getByTestId("home_go"));
+}
+
+function mockManager(): ClientManager {
+  return { login: vi.fn(), register: vi.fn(), logout: vi.fn() };
+}
+
+const WhereAmI: FC = () => {
+  const { pathname, search, hash } = useLocation();
+  return <span>{`at ${pathname}${search}${hash}`}</span>;
+};
+
+function renderView(manager: ClientManager): void {
+  render(
+    <MemoryRouter initialEntries={["/"]}>
+      <UrlParamsProvider value={computeUrlParams()}>
+        <ClientManagerProvider value={manager}>
+          <UnauthenticatedView />
+          <WhereAmI />
+        </ClientManagerProvider>
+      </UrlParamsProvider>
+    </MemoryRouter>,
+  );
+}
@@ -12,7 +12,7 @@ import { Button, Heading, Text } from "@vector-im/compound-web";
 import { logger } from "matrix-js-sdk/lib/logger";
 import { useNavigate } from "react-router-dom";

-import { useClient } from "../ClientContext";
+import { useClientManager } from "../ClientContext";
 import { Header, HeaderLogo, LeftNav, RightNav } from "../Header";
 import { UserMenuContainer } from "../UserMenuContainer";
 import { FieldRow, InputField, ErrorMessage } from "../input/Input";
@@ -22,7 +22,7 @@ import {
  roomAliasLocalpartFromRoomName,
  sanitiseRoomNameInput,
 } from "../utils/matrix";
-import { useInteractiveRegistration } from "../auth/useInteractiveRegistration";
+import { useRegistrationTerms } from "../auth/useRegistrationTerms";
 import { JoinExistingCallModal } from "./JoinExistingCallModal";
 import { useRecaptcha } from "../auth/useRecaptcha";
 import { Form } from "../form/Form";
@@ -37,12 +37,12 @@ import { ExternalLink, Link } from "../button/Link";
 import { useUrlParams } from "../UrlParams";

 export const UnauthenticatedView: FC = () => {
-  const { setClient } = useClient();
+  const { register } = useClientManager();
  const { header } = useUrlParams();
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<Error>();
  const [optInAnalytics] = useOptInAnalytics();
-  const { recaptchaKey, register } = useInteractiveRegistration();
+  const { recaptchaKey } = useRegistrationTerms();
  const { execute, reset, recaptchaId } = useRecaptcha(recaptchaKey);

  const [joinExistingCallModalOpen, setJoinExistingCallModalOpen] =
@@ -67,7 +67,9 @@ export const UnauthenticatedView: FC = () => {
        setLoading(true);
        const recaptchaResponse = await execute();
        const userName = generateRandomName();
-        const [client, session] = await register(
+        // Signed in only once the call exists too: this view is replaced the
+        // moment the session has a user, and the call is what they came for
+        const { client, setSignedIn } = await register(
          userName,
          secureRandomString(16),
          displayName,
@@ -83,15 +85,12 @@ export const UnauthenticatedView: FC = () => {
            E2eeType.SHARED_KEY,
          );
        } catch (error) {
-          if (!setClient) {
-            throw error;
-          }
-
          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
          // @ts-ignore
          if (error.errcode === "M_ROOM_IN_USE") {
-            setOnFinished(() => {
-              setClient(client, session);
+            // Wrapped once more, as a bare function would be taken for an updater
+            setOnFinished(() => () => {
+              setSignedIn();
              const aliasLocalpart = roomAliasLocalpartFromRoomName(roomName);
              navigate(`/${aliasLocalpart}`)?.catch((error) => {
                logger.error("Failed to navigate to alias localpart", error);
@@ -106,14 +105,10 @@ export const UnauthenticatedView: FC = () => {
          }
        }

-        // Only consider the registration successful if we managed to create the room, too
-        if (!setClient) {
-          throw new Error("setClient is undefined");
-        }
        if (!createRoomResult.password)
          throw new Error("Failed to create room with shared secret");

-        setClient(client, session);
+        setSignedIn();
        await navigate(
          getRelativeRoomUrl(
            createRoomResult.roomId,
@@ -130,14 +125,7 @@ export const UnauthenticatedView: FC = () => {
        reset();
      });
    },
-    [
-      register,
-      reset,
-      execute,
-      navigate,
-      setJoinExistingCallModalOpen,
-      setClient,
-    ],
+    [register, reset, execute, navigate, setJoinExistingCallModalOpen],
  );

  return (
@@ -20,7 +20,9 @@ import { App } from "./App";
 import { init as initRageshake } from "./settings/rageshake";
 import { Initializer } from "./initializer";
 import { AppViewModel } from "./state/AppViewModel";
+import { pendingHostClientSession } from "./state/ClientSession";
 import { globalScope } from "./state/ObservableScope";
+import { StandaloneClientSession } from "./state/StandaloneClientSession";
 import { getUrlParams } from "./UrlParams";

 initRageshake().catch((e) => {
@@ -51,17 +53,25 @@ if (fatalError !== null) {
 Initializer.initBeforeReact()
  .then((widget) => {
    const { controlledAudioDevices, callIntent } = getUrlParams();
+    // As a widget, the client comes from the host over the widget API, and
+    // the session is the host's. Standalone, Element Call restores or creates
+    // a session of its own, which it also manages.
+    const options = { controlledAudioDevices, callIntent };
+    let vm: AppViewModel;
+    if (widget === null) {
+      const session = new StandaloneClientSession(globalScope);
+      vm = new AppViewModel(globalScope, options, session, session);
+    } else {
+      vm = new AppViewModel(
+        globalScope,
+        options,
+        pendingHostClientSession(globalScope, widget.client),
+        null,
+      );
+    }
    root.render(
      <StrictMode>
-        <App
-          vm={
-            new AppViewModel(globalScope, {
-              controlledAudioDevices,
-              callIntent,
-            })
-          }
-          widget={widget}
-        />
+        <App vm={vm} widget={widget} />
      </StrictMode>,
    );
  })
@@ -18,7 +18,7 @@ import { type MatrixRTCSession } from "matrix-js-sdk/lib/matrixrtc";
 import { logger } from "matrix-js-sdk/lib/logger";

 import { useMatrixRTCSessionMemberships } from "../useMatrixRTCSessionMemberships";
-import { useClientState } from "../ClientContext";
+import { useHostBridge } from "../HostBridge";
 import { ElementCallReactionEventType, type ReactionOption } from ".";
 import { type CallViewModel } from "../state/CallViewModel/CallViewModel";
 import { useBehavior } from "../useBehavior";
@@ -54,9 +54,7 @@ export const ReactionsSenderProvider = ({
  vm: CallViewModel;
 }): JSX.Element => {
  const memberships = useMatrixRTCSessionMemberships(rtcSession);
-  const clientState = useClientState();
-  const supportsReactions =
-    clientState?.state === "valid" && clientState.supportedFeatures.reactions;
+  const { supportsReactions } = useHostBridge();
  const room = rtcSession.room;
  const myUserId = room.client.getUserId();
  const myDeviceId = room.client.getDeviceId();
@@ -0,0 +1,101 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, expect, test, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { type MatrixClient } from "matrix-js-sdk";
+import { BehaviorSubject } from "rxjs";
+
+import { RoomPage } from "./RoomPage";
+import { ClientContextProvider } from "../ClientContext";
+import { type ClientSessionState } from "../state/ClientSession";
+import { computeUrlParams, UrlParamsProvider } from "../UrlParams";
+import { useLoadGroupCall } from "./useLoadGroupCall";
+
+vi.mock("./useLoadGroupCall", () => ({
+  useLoadGroupCall: vi.fn(() => ({ kind: "loading" })),
+  CallTerminatedMessage: class extends Error {},
+}));
+vi.mock("./useRoomName", () => ({ useRoomName: () => null }));
+vi.mock("../profile/useProfile", () => ({ useProfile: () => ({}) }));
+vi.mock("../auth/useRegisterPasswordlessUser", () => ({
+  useRegisterPasswordlessUser: () => ({ registerPasswordlessUser }),
+}));
+vi.mock("./RoomAuthView", () => ({
+  RoomAuthView: () => <span>room auth view</span>,
+}));
+vi.mock("../home/HomePage", () => ({
+  HomePage: () => <span>home page</span>,
+}));
+vi.mock("./CallView", () => ({
+  CallView: ({ isPasswordlessUser }: { isPasswordlessUser: boolean }) => (
+    <span>call view, passwordless: {String(isPasswordlessUser)}</span>
+  ),
+}));
+vi.mock("./KnockLobbyView", () => ({ KnockLobbyView: () => null }));
+
+const registerPasswordlessUser = vi.fn().mockResolvedValue(undefined);
+
+afterEach(() => vi.clearAllMocks());
+
+test("waits for the session to be restored", () => {
+  renderRoom({ state: "loading" }, "/call");
+  expect(screen.getByRole("heading", { name: "Loading…" })).toBeVisible();
+});
+
+test("asks a signed-out user to join as a guest", () => {
+  renderRoom({ state: "signedOut" }, "/call");
+  expect(screen.getByText("room auth view")).toBeVisible();
+  expect(registerPasswordlessUser).not.toHaveBeenCalled();
+});
+
+test("registers a passwordless user when the URL names one", () => {
+  renderRoom({ state: "signedOut" }, "/call", "Alice");
+  expect(registerPasswordlessUser).toHaveBeenCalledWith("Alice");
+});
+
+test("falls back to the home page without a room", () => {
+  renderRoom(signedIn(false), "/");
+  expect(screen.getByText("home page")).toBeVisible();
+});
+
+test("tells the call whether its user is passwordless", () => {
+  vi.mocked(useLoadGroupCall).mockReturnValue({
+    kind: "loaded",
+    rtcSession: { room: {} },
+  } as unknown as ReturnType<typeof useLoadGroupCall>);
+
+  renderRoom(signedIn(true), "/call");
+  expect(screen.getByText("call view, passwordless: true")).toBeVisible();
+});
+
+function signedIn(passwordlessUser: boolean): ClientSessionState {
+  return {
+    state: "signedIn",
+    client: { getUserId: () => "@alice:example.org" } as MatrixClient,
+    passwordlessUser,
+  };
+}
+
+function renderRoom(
+  state: ClientSessionState,
+  path: string,
+  displayName: string | null = null,
+): void {
+  render(
+    <MemoryRouter initialEntries={[path]}>
+      <UrlParamsProvider value={{ ...computeUrlParams(), displayName }}>
+        <ClientContextProvider
+          value={{ state$: new BehaviorSubject<ClientSessionState>(state) }}
+        >
+          <RoomPage />
+        </ClientContextProvider>
+      </UrlParamsProvider>
+    </MemoryRouter>,
+  );
+}
@@ -12,7 +12,7 @@ import { logger } from "matrix-js-sdk/lib/logger";
 import { Trans, useTranslation } from "react-i18next";
 import { UnknownSolidIcon } from "@vector-im/compound-design-tokens/assets/web/icons";

-import { useClientLegacy } from "../ClientContext";
+import { useClient, useClientSessionState } from "../ClientContext";
 import { ErrorPage, FullScreenView, LoadingPage } from "../FullScreenView";
 import { RoomAuthView } from "./RoomAuthView";
 import { CallView } from "./CallView";
@@ -42,8 +42,12 @@ export const RoomPage: FC = (): ReactNode => {
  const { registerPasswordlessUser } = useRegisterPasswordlessUser();
  const [isRegistering, setIsRegistering] = useState(false);

-  const { loading, authenticated, client, error, passwordlessUser } =
-    useClientLegacy();
+  const { client } = useClient();
+  const session = useClientSessionState();
+  const loading = session.state === "loading";
+  const passwordlessUser =
+    session.state === "signedIn" && session.passwordlessUser;
+  const authenticated = client !== undefined;
  const { avatarUrl, displayName: userDisplayName } = useProfile(client);

  const groupCallState = useLoadGroupCall(client, roomIdOrAlias, viaServers);
@@ -184,7 +188,6 @@ export const RoomPage: FC = (): ReactNode => {
  };

  if (loading || isRegistering) return <LoadingPage />;
-  if (error) return <ErrorPage error={error} />;
  if (!client) return <RoomAuthView />;
  // TODO: This doesn't belong here, the app routes need to be reworked
  if (!roomIdOrAlias) return <HomePage />;
@@ -20,6 +20,7 @@ import { type MatrixClient } from "matrix-js-sdk/lib/client";

 import { useSubmitRageshake, getRageshakeSubmitUrl } from "./submit-rageshake";
 import { ClientContextProvider } from "../ClientContext";
+import { hostClientSession } from "../state/ClientSession";
 import { getUrlParams } from "../UrlParams";
 import { mockConfig } from "../utils/test";
 import { DEFAULT_CONFIG } from "../config/ConfigOptions";
@@ -74,22 +75,7 @@ function renderWithMockClient(
  } as unknown as MatrixClient);

  render(
-    <ClientContextProvider
-      value={{
-        state: "valid",
-        disconnected: false,
-        supportedFeatures: {
-          reactions: true,
-        },
-        setClient: vi.fn(),
-        authenticated: {
-          client,
-          isPasswordlessUser: true,
-          changePassword: vi.fn(),
-          logout: vi.fn(),
-        },
-      }}
-    >
+    <ClientContextProvider value={hostClientSession(client)}>
      <TestComponent
        sendLogs={sendLogs}
        getRageshakeSubmitUrl={getRageshakeSubmitUrl}
@@ -5,6 +5,7 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */

+import { type ClientManager, type ClientSession } from "./ClientSession";
 import { type AudioOutputOptions, MediaDevices } from "./MediaDevices";
 import { type ObservableScope } from "./ObservableScope";
 import { createAppBackgroundEffects } from "../tracks/BackgroundEffectsContext";
@@ -22,8 +23,14 @@ export class AppViewModel {
  // TODO: Move more application logic here. The CallViewModel, at the very
  // least, ought to be accessible from this object.

+  /**
+   * @param clientSession Where the client comes from. SPA js-sdk, EW host, widget
+   */
  public constructor(
    private readonly scope: ObservableScope,
    private readonly audioOutputOptions: AudioOutputOptions,
+    public readonly clientSession: ClientSession,
+    /** Null where the session is a host's and not ours to manage. */
+    public readonly clientManager: ClientManager | null,
  ) {}
 }
@@ -0,0 +1,45 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { expect, test } from "vitest";
+import { type MatrixClient } from "matrix-js-sdk";
+
+import { hostClientSession, pendingHostClientSession } from "./ClientSession";
+import { flushPromises, testScope } from "../utils/test";
+
+const client = {} as MatrixClient;
+
+test("a host's client is signed in from the start", () => {
+  const session = hostClientSession(client);
+  expect(session.state$.value).toEqual({
+    state: "signedIn",
+    client,
+    passwordlessUser: false,
+  });
+});
+
+test("a pending host client is loading until it arrives", async () => {
+  const session = pendingHostClientSession(
+    testScope(),
+    Promise.resolve(client),
+  );
+  expect(session.state$.value).toEqual({ state: "loading" });
+  await flushPromises();
+  expect(session.state$.value).toEqual({
+    state: "signedIn",
+    client,
+    passwordlessUser: false,
+  });
+});
+
+test("a pending host client that never arrives is an error", async () => {
+  const error = new Error("no widget API");
+  const session = pendingHostClientSession(testScope(), Promise.reject(error));
+  await flushPromises();
+  // An error page rather than a spinner that never ends
+  expect(session.state$.value).toEqual({ state: "error", error });
+});
@@ -0,0 +1,104 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { type MatrixClient } from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+import { catchError, from, map, of } from "rxjs";
+
+import { type Behavior, constant } from "./Behavior";
+import { type ObservableScope } from "./ObservableScope";
+
+/**
+ * A session of Element Call's own, as the standalone app stores it.
+ */
+export interface StoredSession {
+  user_id: string;
+  device_id: string;
+  access_token: string;
+  passwordlessUser: boolean;
+}
+
+export type ClientSessionState =
+  | { state: "loading" }
+  | { state: "signedOut" }
+  | { state: "signedIn"; client: MatrixClient; passwordlessUser: boolean }
+  | { state: "error"; error: Error };
+
+/**
+ * A newly registered account, with its client started. Registering and signing
+ * in are separate steps, as a caller may have more to do with the account
+ * before the session changes hands — creating the call it was registered for,
+ * say.
+ */
+export interface Registration {
+  client: MatrixClient;
+  setSignedIn: () => void;
+}
+
+/**
+ * Where Element Call's client comes from. Every build has one: a session of
+ * Element Call's own, or one a host has supplied.
+ */
+export interface ClientSession {
+  state$: Behavior<ClientSessionState>;
+}
+
+/**
+ * What can be done with a client created in EC (SPA). Widget and host client
+ * wont have this, see useClientManager and useClientManagerIfAny
+ */
+export interface ClientManager {
+  /** Signs in to the homeserver with a password, ending any current session. */
+  login: (
+    homeserver: string,
+    username: string,
+    password: string,
+  ) => Promise<MatrixClient>;
+  /** Registers an account on the default homeserver. */
+  register: (
+    username: string,
+    password: string,
+    displayName: string,
+    recaptchaResponse: string,
+    passwordlessUser: boolean,
+  ) => Promise<Registration>;
+  logout: () => Promise<void>;
+}
+
+/**
+ * A client supplied by the host, which owns the user's session: signed in from
+ * the start, nothing to restore. Used for the component target.
+ */
+export function hostClientSession(client: MatrixClient): ClientSession {
+  return { state$: constant(signedIn(client)) };
+}
+
+/**
+ * A client the host is still handing over.
+ * Used for the embedded target, widget API.
+ */
+export function pendingHostClientSession(
+  scope: ObservableScope,
+  client: Promise<MatrixClient>,
+): ClientSession {
+  return {
+    state$: scope.behavior<ClientSessionState>(
+      from(client).pipe(
+        map(signedIn),
+        catchError((e) => {
+          logger.error("Failed to obtain the host's client", e);
+          return of<ClientSessionState>({ state: "error", error: e });
+        }),
+      ),
+      { state: "loading" },
+    ),
+  };
+}
+
+function signedIn(client: MatrixClient): ClientSessionState {
+  return { state: "signedIn", client, passwordlessUser: false };
+}
@@ -0,0 +1,265 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+import { type MatrixClient, MatrixError, type User } from "matrix-js-sdk";
+
+import { StandaloneClientSession } from "./StandaloneClientSession";
+import { type StoredSession } from "./ClientSession";
+import { initClient } from "../utils/initClient";
+import {
+  loginWithPassword,
+  registerWithPassword,
+} from "../auth/interactiveAuth";
+import { PosthogAnalytics } from "../analytics/PosthogAnalytics";
+import { Config } from "../config/Config";
+import { OpenElsewhereError } from "../RichError";
+import { flushPromises, testScope } from "../utils/test";
+
+vi.mock("../utils/initClient", () => ({ initClient: vi.fn() }));
+vi.mock("../auth/interactiveAuth", () => ({
+  loginWithPassword: vi.fn(),
+  registerWithPassword: vi.fn(),
+}));
+
+const SESSION_KEY = "matrix-auth-store";
+
+const session: StoredSession = {
+  user_id: "@alice:example.org",
+  device_id: "AAAA",
+  access_token: "secret",
+  passwordlessUser: true,
+};
+
+const user = { setRawDisplayName: vi.fn(), setDisplayName: vi.fn() };
+const mockClient = (): MatrixClient =>
+  ({
+    stopClient: vi.fn(),
+    logout: vi.fn().mockResolvedValue(undefined),
+    clearStores: vi.fn().mockResolvedValue(undefined),
+    setDisplayName: vi.fn().mockResolvedValue(undefined),
+    getUserId: () => session.user_id,
+    getUser: () => user as unknown as User,
+  }) as Partial<MatrixClient> as MatrixClient;
+
+const credentials = {
+  user_id: "@bob:example.org",
+  device_id: "BBBB",
+  access_token: "fresh",
+};
+
+const storeSession = (): void =>
+  localStorage.setItem(SESSION_KEY, JSON.stringify(session));
+const storedSession = (): StoredSession | null =>
+  JSON.parse(localStorage.getItem(SESSION_KEY) ?? "null");
+
+beforeEach(() => {
+  vi.spyOn(Config, "init").mockResolvedValue(undefined);
+  vi.spyOn(Config, "defaultHomeserverUrl").mockReturnValue(
+    "https://hs.example.org",
+  );
+  localStorage.clear();
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+test("restores the stored session once the config is loaded", async () => {
+  storeSession();
+  const client = mockClient();
+  vi.mocked(initClient).mockResolvedValue(client);
+
+  const clientSession = new StandaloneClientSession(testScope());
+  expect(clientSession.state$.value).toEqual({ state: "loading" });
+
+  await flushPromises();
+  expect(Config.init).toHaveBeenCalled();
+  expect(initClient).toHaveBeenCalledWith(
+    expect.objectContaining({
+      baseUrl: "https://hs.example.org",
+      accessToken: "secret",
+      userId: "@alice:example.org",
+      deviceId: "AAAA",
+    }),
+    // Restoring: the crypto store is the session's, not to be wiped
+    true,
+  );
+  expect(clientSession.state$.value).toEqual({
+    state: "signedIn",
+    client,
+    passwordlessUser: true,
+  });
+});
+
+test("has no one signed in when there is no session to restore", async () => {
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+  expect(initClient).not.toHaveBeenCalled();
+  expect(clientSession.state$.value).toEqual({ state: "signedOut" });
+});
+
+test("drops a session the homeserver no longer knows", async () => {
+  storeSession();
+  vi.mocked(initClient).mockRejectedValue(
+    new MatrixError({ errcode: "M_UNKNOWN_TOKEN", error: "Unknown token" }),
+  );
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+  expect(storedSession()).toBeNull();
+  expect(clientSession.state$.value).toEqual({ state: "signedOut" });
+});
+
+test("drops the session and reports any other error", async () => {
+  storeSession();
+  const error = new Error("offline");
+  vi.mocked(initClient).mockRejectedValue(error);
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+  expect(storedSession()).toBeNull();
+  // An error page rather than a spinner that never ends
+  expect(clientSession.state$.value).toEqual({ state: "error", error });
+});
+
+test("logs in with a password, ending the session it had", async () => {
+  storeSession();
+  const restored = mockClient();
+  vi.mocked(initClient).mockResolvedValueOnce(restored);
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+
+  const client = mockClient();
+  vi.mocked(loginWithPassword).mockResolvedValue(credentials);
+  vi.mocked(initClient).mockResolvedValueOnce(client);
+  await expect(
+    clientSession.login("https://other.example.org", "bob", "hunter2"),
+  ).resolves.toBe(client);
+
+  expect(loginWithPassword).toHaveBeenCalledWith(
+    "https://other.example.org",
+    "bob",
+    "hunter2",
+  );
+  // The old session is logged out before the new client starts, so that the
+  // crypto stores are not shared between the two
+  expect(restored.logout).toHaveBeenCalledWith(true);
+  expect(initClient).toHaveBeenLastCalledWith(
+    {
+      baseUrl: "https://other.example.org",
+      accessToken: "fresh",
+      userId: "@bob:example.org",
+      deviceId: "BBBB",
+    },
+    false,
+  );
+  expect(clientSession.state$.value).toEqual({
+    state: "signedIn",
+    client,
+    passwordlessUser: false,
+  });
+  expect(storedSession()).toEqual({ ...credentials, passwordlessUser: false });
+});
+
+test("registers a passwordless account, signing in only when asked", async () => {
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+
+  const client = mockClient();
+  vi.mocked(registerWithPassword).mockResolvedValue(credentials);
+  vi.mocked(initClient).mockResolvedValue(client);
+  const registration = await clientSession.register(
+    "bob",
+    "temporary",
+    "Bob",
+    "captcha",
+    true,
+  );
+
+  expect(registerWithPassword).toHaveBeenCalledWith(
+    "https://hs.example.org",
+    "bob",
+    "temporary",
+    "captcha",
+  );
+  expect(registration.client).toBe(client);
+  expect(client.setDisplayName).toHaveBeenCalledWith("Bob");
+  expect(user.setDisplayName).toHaveBeenCalledWith("Bob");
+  // Registered, but not yet signed in: the caller may still be setting up
+  expect(clientSession.state$.value).toEqual({ state: "signedOut" });
+  expect(storedSession()).toBeNull();
+
+  registration.setSignedIn();
+  expect(clientSession.state$.value).toEqual({
+    state: "signedIn",
+    client,
+    passwordlessUser: true,
+  });
+  expect(storedSession()).toEqual({ ...credentials, passwordlessUser: true });
+});
+
+test("registers an account with a password of its own", async () => {
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+  vi.mocked(registerWithPassword).mockResolvedValue(credentials);
+  vi.mocked(initClient).mockResolvedValue(mockClient());
+
+  const { setSignedIn } = await clientSession.register(
+    "bob",
+    "hunter2",
+    "Bob",
+    "captcha",
+    false,
+  );
+  setSignedIn();
+
+  expect(storedSession()).toEqual({ ...credentials, passwordlessUser: false });
+});
+
+test("logs out, clearing the client's stores and the stored session", async () => {
+  storeSession();
+  const client = mockClient();
+  vi.mocked(initClient).mockResolvedValue(client);
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+
+  const analyticsLogout = vi.spyOn(PosthogAnalytics.instance, "logout");
+
+  await clientSession.logout();
+
+  expect(client.logout).toHaveBeenCalledWith(true);
+  expect(client.clearStores).toHaveBeenCalled();
+  expect(storedSession()).toBeNull();
+  expect(clientSession.state$.value).toEqual({ state: "signedOut" });
+  // Analytics forget the user along with the session
+  expect(analyticsLogout).toHaveBeenCalled();
+});
+
+test("claims exclusive use of storage from other instances of the app", () => {
+  // The channel is created with the session, so spy on the prototype rather
+  // than trying to replace the global.
+  const postMessage = vi.spyOn(BroadcastChannel.prototype, "postMessage");
+  new StandaloneClientSession(testScope());
+  expect(postMessage).toHaveBeenCalled();
+});
+
+test("stops when another instance of the app claims storage", async () => {
+  storeSession();
+  const client = mockClient();
+  vi.mocked(initClient).mockResolvedValue(client);
+  const clientSession = new StandaloneClientSession(testScope());
+  await flushPromises();
+
+  new BroadcastChannel("load").postMessage({});
+  await vi.waitFor(() =>
+    expect(clientSession.state$.value).toMatchObject({ state: "error" }),
+  );
+  expect(client.stopClient).toHaveBeenCalled();
+  const { value } = clientSession.state$;
+  expect(value.state === "error" && value.error).toBeInstanceOf(
+    OpenElsewhereError,
+  );
+});
@@ -0,0 +1,222 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { type MatrixClient, MatrixError } from "matrix-js-sdk";
+import { logger } from "matrix-js-sdk/lib/logger";
+import { BehaviorSubject } from "rxjs";
+
+import {
+  PosthogAnalytics,
+  RegistrationType,
+} from "../analytics/PosthogAnalytics";
+import { Config } from "../config/Config";
+import { OpenElsewhereError } from "../RichError";
+import {
+  loginWithPassword,
+  registerWithPassword,
+} from "../auth/interactiveAuth";
+import { initClient } from "../utils/initClient";
+import { fallbackICEServerAllowed } from "../utils/matrix";
+import { type Behavior } from "./Behavior";
+import {
+  type ClientManager,
+  type ClientSession,
+  type ClientSessionState,
+  type Registration,
+  type StoredSession,
+} from "./ClientSession";
+import { type ObservableScope } from "./ObservableScope";
+
+const SESSION_KEY = "matrix-auth-store";
+
+/**
+ * A client session for the SPA: restored from storage on construction, and
+ * signed in to, out of, or re-authenticated by the login, registration and
+ * account flows.
+ *
+ * This class is responsible for restoring from store and logout and change Pwd.
+ *
+ * To make sure we do not load/bundle the client store worker it is important
+ * that this is a separate file: only this module reaches `utils/initClient`,
+ * and therefore the client store worker, so it may only be imported by the
+ * standalone app's entry point.
+ */
+export class StandaloneClientSession implements ClientSession, ClientManager {
+  private readonly state = new BehaviorSubject<ClientSessionState>({
+    state: "loading",
+  });
+  public readonly state$: Behavior<ClientSessionState> = this.scope.behavior(
+    this.state,
+  );
+
+  // To protect against multiple sessions writing to the same storage
+  // simultaneously, we send a broadcast message that shuts down all other
+  // running instances of the app.
+  private readonly loadChannel =
+    "BroadcastChannel" in window ? new BroadcastChannel("load") : null;
+
+  public constructor(private readonly scope: ObservableScope) {
+    this.loadChannel?.postMessage({});
+    const onOpenedElsewhere = (): void => {
+      this.client?.stopClient();
+      this.state.next({ state: "error", error: new OpenElsewhereError() });
+    };
+    this.loadChannel?.addEventListener("message", onOpenedElsewhere);
+    scope.onEnd(() =>
+      this.loadChannel?.removeEventListener("message", onOpenedElsewhere),
+    );
+
+    this.restore().catch((e) => {
+      logger.error("Failed to restore the session", e);
+      this.state.next({ state: "error", error: e });
+    });
+  }
+
+  private get client(): MatrixClient | undefined {
+    const { value } = this.state;
+    return value.state === "signedIn" ? value.client : undefined;
+  }
+
+  private async restore(): Promise<void> {
+    // The homeserver to restore against is in the config, which is loaded
+    // concurrently with this
+    await Config.init();
+    try {
+      const session = loadSession();
+      if (session === undefined) {
+        logger.log("No session stored; continuing without a client");
+        this.state.next({ state: "signedOut" });
+        return;
+      }
+
+      logger.log("Using a standalone client");
+      const client = await initClient(
+        {
+          baseUrl: Config.defaultHomeserverUrl()!,
+          accessToken: session.access_token,
+          userId: session.user_id,
+          deviceId: session.device_id,
+          fallbackICEServerAllowed,
+          livekitServiceURL: Config.get().livekit?.livekit_service_url,
+        },
+        true,
+      );
+      this.state.next({
+        state: "signedIn",
+        client,
+        passwordlessUser: session.passwordlessUser,
+      });
+    } catch (e) {
+      // Whatever went wrong, the stored session is not to be tried again
+      clearSession();
+      if (e instanceof MatrixError && e.errcode === "M_UNKNOWN_TOKEN") {
+        logger.log(
+          "The session from local store is invalid; continuing without a client",
+        );
+        this.state.next({ state: "signedOut" });
+        return;
+      }
+      throw e;
+    }
+  }
+
+  public readonly login = async (
+    homeserver: string,
+    username: string,
+    password: string,
+  ): Promise<MatrixClient> => {
+    const session: StoredSession = {
+      ...(await loginWithPassword(homeserver, username, password)),
+      passwordlessUser: false,
+    };
+    const client = await this.createClient(homeserver, session);
+    this.signIn(client, session);
+    return client;
+  };
+
+  public readonly register = async (
+    username: string,
+    password: string,
+    displayName: string,
+    recaptchaResponse: string,
+    passwordlessUser: boolean,
+  ): Promise<Registration> => {
+    const homeserver = Config.defaultHomeserverUrl()!;
+    const session: StoredSession = {
+      ...(await registerWithPassword(
+        homeserver,
+        username,
+        password,
+        recaptchaResponse,
+      )),
+      passwordlessUser,
+    };
+    const client = await this.createClient(homeserver, session);
+
+    await client.setDisplayName(displayName);
+    const user = client.getUser(client.getUserId()!)!;
+    user.setRawDisplayName(displayName);
+    user.setDisplayName(displayName);
+
+    return { client, setSignedIn: (): void => this.signIn(client, session) };
+  };
+
+  /**
+   * Starts a client for a new session, ending the current one first.
+   */
+  private async createClient(
+    homeserver: string,
+    session: StoredSession,
+  ): Promise<MatrixClient> {
+    // To not confuse the rust crypto sessions we need to log out the old
+    // client before initializing the new one
+    await this.client?.logout(true);
+    return initClient(
+      {
+        baseUrl: homeserver,
+        accessToken: session.access_token,
+        userId: session.user_id,
+        deviceId: session.device_id,
+      },
+      false,
+    );
+  }
+
+  private signIn(client: MatrixClient, session: StoredSession): void {
+    saveSession(session);
+    this.state.next({
+      state: "signedIn",
+      client,
+      passwordlessUser: session.passwordlessUser,
+    });
+  }
+
+  public readonly logout = async (): Promise<void> => {
+    const client = this.client;
+    if (!client) return;
+
+    await client.logout(true);
+    await client.clearStores();
+    clearSession();
+    this.state.next({ state: "signedOut" });
+    PosthogAnalytics.instance.logout();
+    PosthogAnalytics.instance.setRegistrationType(RegistrationType.Guest);
+  };
+}
+
+function loadSession(): StoredSession | undefined {
+  const data = localStorage.getItem(SESSION_KEY);
+  return data ? JSON.parse(data) : undefined;
+}
+
+function saveSession(session: StoredSession): void {
+  localStorage.setItem(SESSION_KEY, JSON.stringify(session));
+}
+
+function clearSession(): void {
+  localStorage.removeItem(SESSION_KEY);
+}
@@ -0,0 +1,214 @@
+/*
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import { EventEmitter } from "events";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type Mock,
+  vi,
+} from "vitest";
+import {
+  ClientEvent,
+  createClient,
+  type ICreateClientOpts,
+  IndexedDBStore,
+  MemoryStore,
+} from "matrix-js-sdk";
+import type * as MatrixSdk from "matrix-js-sdk";
+
+import { initClient } from "./initClient";
+import { flushPromises } from "./test";
+
+interface Store {
+  startup: Mock<() => Promise<void>>;
+  getSavedSyncToken: Mock<() => Promise<string | null>>;
+}
+
+const store = (): Store => ({
+  startup: vi.fn<() => Promise<void>>().mockResolvedValue(undefined),
+  getSavedSyncToken: vi
+    .fn<() => Promise<string | null>>()
+    .mockResolvedValue(null),
+});
+
+// The client is the SDK's business; what these tests are about is how it is
+// set up: its stores, its crypto, and when it counts as ready.
+vi.mock("matrix-js-sdk", async (importOriginal) => ({
+  ...(await importOriginal<typeof MatrixSdk>()),
+  createClient: vi.fn(),
+  IndexedDBStore: vi.fn(function (this: Store) {
+    Object.assign(this, store());
+  }),
+  MemoryStore: vi.fn(function (this: Store) {
+    Object.assign(this, store());
+  }),
+}));
+
+interface FakeClient extends EventEmitter {
+  store: Store;
+  clearStores: Mock<() => Promise<void>>;
+  initRustCrypto: Mock<() => Promise<void>>;
+  startClient: Mock<() => Promise<void>>;
+}
+
+/**
+ * A client that, unless told otherwise, reports its first sync a tick after
+ * being started, as the real one does once the network answers.
+ */
+function fakeClient(opts: ICreateClientOpts, syncs = true): FakeClient {
+  const client = Object.assign(new EventEmitter(), {
+    store: opts.store as unknown as Store,
+    clearStores: vi.fn<() => Promise<void>>().mockResolvedValue(undefined),
+    initRustCrypto: vi.fn<() => Promise<void>>().mockResolvedValue(undefined),
+    startClient: vi.fn(async () => {
+      if (!syncs) return;
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      client.emit(ClientEvent.Sync, "PREPARED", null);
+    }),
+  });
+  return client;
+}
+
+const options: ICreateClientOpts = { baseUrl: "https://hs.example.org" };
+const clients = vi.mocked(createClient) as unknown as Mock<
+  (opts: ICreateClientOpts) => FakeClient
+>;
+const indexedDBStores = vi.mocked(IndexedDBStore);
+const memoryStores = vi.mocked(MemoryStore);
+
+describe("initClient", () => {
+  beforeEach(() => {
+    clients.mockImplementation((opts) => fakeClient(opts));
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+    vi.unstubAllEnvs();
+  });
+
+  it("hands back the client once its first sync is done", async () => {
+    const client = await initClient(options, true);
+
+    expect(client).toBe(clients.mock.results[0].value);
+    expect(client.startClient).toHaveBeenCalledWith({
+      clientWellKnownPollPeriod: 600,
+    });
+    expect(clients).toHaveBeenCalledWith(
+      expect.objectContaining({
+        baseUrl: "https://hs.example.org",
+        useAuthorizationHeader: true,
+        localTimeoutMs: 5000,
+      }),
+    );
+  });
+
+  it("keeps the stores when restoring a session", async () => {
+    const client = (await initClient(options, true)) as unknown as FakeClient;
+    expect(client.clearStores).not.toHaveBeenCalled();
+  });
+
+  it("clears the stores before starting them when not restoring", async () => {
+    const client = (await initClient(options, false)) as unknown as FakeClient;
+
+    expect(client.clearStores).toHaveBeenCalled();
+    expect(client.clearStores.mock.invocationCallOrder[0]).toBeLessThan(
+      client.store.startup.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("syncs into memory where there is no IndexedDB", async () => {
+    // jsdom has no indexedDB
+    const client = await initClient(options, true);
+
+    expect(client.store).toBe(memoryStores.mock.instances[0]);
+    expect(indexedDBStores).not.toHaveBeenCalled();
+  });
+
+  it("syncs into IndexedDB through a worker, where it was bundled", async () => {
+    vi.stubGlobal("indexedDB", {});
+    vi.stubEnv("DEV", false);
+
+    const client = await initClient(options, true);
+
+    expect(client.store).toBe(indexedDBStores.mock.instances[0]);
+    const [storeOptions] = indexedDBStores.mock.calls[0];
+    expect(storeOptions.dbName).toBe("element-call-sync");
+    expect(storeOptions.workerFactory).toBeTypeOf("function");
+  });
+
+  it("syncs into IndexedDB without a worker in development", async () => {
+    vi.stubGlobal("indexedDB", {});
+    vi.stubEnv("DEV", true);
+
+    await initClient(options, true);
+
+    // The dev server does not bundle the worker
+    expect(indexedDBStores.mock.calls[0][0].workerFactory).toBeUndefined();
+  });
+
+  it("falls back to memory when the IndexedDB store cannot start", async () => {
+    vi.stubGlobal("indexedDB", {});
+    const failing = store();
+    failing.startup.mockRejectedValue(new Error("quota exceeded"));
+    indexedDBStores.mockImplementationOnce(function (this: IndexedDBStore) {
+      Object.assign(this, failing);
+    });
+
+    const client = await initClient(options, true);
+
+    expect(client.store).toBe(memoryStores.mock.instances[0]);
+    expect(client.store.startup).toHaveBeenCalled();
+  });
+
+  it("carries on without crypto when it cannot be initialised", async () => {
+    clients.mockImplementation((opts) => {
+      const client = fakeClient(opts);
+      client.initRustCrypto.mockRejectedValue(new Error("stores in use"));
+      return client;
+    });
+
+    await expect(initClient(options, true)).resolves.toBeDefined();
+  });
+
+  it("waits for a sync from the network, past one restored from the store", async () => {
+    let client!: FakeClient;
+    clients.mockImplementation((opts) => {
+      client = fakeClient(opts, false);
+      client.store.getSavedSyncToken.mockResolvedValue("saved");
+      return client;
+    });
+    let ready = false;
+    const result = initClient(options, true).then(() => (ready = true));
+    await flushPromises();
+
+    // The first sync the client reports is the one restored from the store
+    client.emit(ClientEvent.Sync, "PREPARED", null);
+    await flushPromises();
+    expect(ready).toBe(false);
+
+    client.emit(ClientEvent.Sync, "PREPARED", null);
+    await result;
+    expect(ready).toBe(true);
+  });
+
+  it("fails when the first sync does", async () => {
+    let client!: FakeClient;
+    clients.mockImplementation((opts) => (client = fakeClient(opts, false)));
+    const result = initClient(options, true);
+    await flushPromises();
+
+    client.emit(ClientEvent.Sync, "ERROR", null, {
+      error: new Error("offline"),
+    });
+
+    await expect(result).rejects.toThrow("offline");
+  });
+});
@@ -0,0 +1,165 @@
+/*
+Copyright 2022-2024 New Vector Ltd.
+Copyright 2026 Element Creations Ltd.
+
+SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
+Please see LICENSE in the repository root for full details.
+*/
+
+import {
+  ClientEvent,
+  createClient,
+  type ICreateClientOpts,
+  IndexedDBStore,
+  type MatrixClient,
+  MemoryStore,
+} from "matrix-js-sdk";
+import { type ISyncStateData, type SyncState } from "matrix-js-sdk/lib/sync";
+import { logger } from "matrix-js-sdk/lib/logger";
+
+// This import pulls in many MBs of SDK code and crypto WASM which should only
+// be included in full SPA builds, which is why `initClient` gets its own module.
+import IndexedDBWorker from "../IndexedDBWorker?worker";
+import { getUrlParams } from "../UrlParams";
+import { Config } from "../config/Config";
+import { fallbackICEServerAllowed } from "./matrix";
+
+const SYNC_STORE_NAME = "element-call-sync";
+
+/**
+ * Initialises and returns a new standalone Matrix Client.
+ * This can only be called safely if no other client is running
+ * otherwise rust crypto will throw since it is not ready to initialize a new session.
+ * If another client is running make sure `.logout()` is called before executing this function.
+ * @param clientOptions Object of options passed through to the client
+ * @param restore If the rust crypto should be reset before the client initialization or
+ * if the initialization should try to restore the crypto state from the indexDB.
+ * @returns The MatrixClient instance
+ */
+export async function initClient(
+  clientOptions: ICreateClientOpts,
+  restore: boolean,
+): Promise<MatrixClient> {
+  let indexedDB: IDBFactory | undefined;
+  try {
+    indexedDB = window.indexedDB;
+  } catch (e) {
+    logger.warn("Could not get indexDB from window.", e);
+  }
+
+  // options we always pass to the client (stuff that we need in order to work)
+  const baseOpts = {
+    fallbackICEServerAllowed: fallbackICEServerAllowed,
+    isVoipWithNoMediaAllowed:
+      Config.get().features?.feature_group_calls_without_video_and_audio,
+  } as ICreateClientOpts;
+
+  if (indexedDB && localStorage) {
+    baseOpts.store = new IndexedDBStore({
+      indexedDB: window.indexedDB,
+      localStorage,
+      dbName: SYNC_STORE_NAME,
+      // We can't use the worker in dev mode because Vite simply doesn't bundle workers
+      // in dev mode: it expects them to use native modules. Ours don't, and even then only
+      // Chrome supports it. (It bundles them fine in production mode.)
+      workerFactory: import.meta.env.DEV
+        ? undefined
+        : (): Worker => new IndexedDBWorker(),
+    });
+  } else if (localStorage) {
+    baseOpts.store = new MemoryStore({ localStorage });
+  }
+
+  // XXX: we read from the URL params in RoomPage too:
+  // it would be much better to read them in one place and pass
+  // the values around, but we initialise the matrix client in
+  // many different places so we'd have to pass it into all of
+  // them.
+  const { e2eEnabled } = getUrlParams();
+  if (!e2eEnabled) {
+    logger.info("Disabling E2E: group call signalling will NOT be encrypted.");
+  }
+
+  const client = createClient({
+    ...baseOpts,
+    ...clientOptions,
+    useAuthorizationHeader: true,
+    // Use a relatively low timeout for API calls: this is a realtime app
+    // so we don't want API calls taking ages, we'd rather they just fail.
+    localTimeoutMs: 5000,
+    useE2eForGroupCall: e2eEnabled,
+    fallbackICEServerAllowed: fallbackICEServerAllowed,
+  });
+
+  // In case of logging in a new matrix account but there is still crypto local store. This is needed for:
+  // - We lost the auth tokens and cannot restore the client resulting in registering a new user.
+  // - We start the sign in flow but are registered with a guest user. (It should additionally log out the guest before)
+  // - A new account is created because of missing LocalStorage: "matrix-auth-store", but the crypto IndexDB is still available.
+  if (!restore) {
+    await client.clearStores();
+  }
+
+  // Start client store.
+  // Note: The `client.store` is used to store things like sync results. It's independent of
+  // the cryptostore, and uses a separate indexeddb database.
+  try {
+    await client.store.startup();
+  } catch (error) {
+    logger.error(
+      "Error starting matrix client indexDB store. Falling back to memory store.",
+      error,
+    );
+    client.store = new MemoryStore({ localStorage });
+    await client.store.startup();
+  }
+
+  // Also creates and starts any crypto related stores.
+  try {
+    await client.initRustCrypto();
+  } catch (err) {
+    logger.warn(
+      err,
+      "Make sure to clear client stores before initializing the rust crypto.",
+    );
+  }
+
+  // Once startClient is called, syncs are run asynchronously.
+  // Also, sync completion is communicated only via events.
+  // So, apply the event listener *before* starting the client.
+  // Otherwise, a sync may complete before the listener gets applied,
+  // and we will miss it.
+  const syncPromise = waitForSync(client);
+  await client.startClient({ clientWellKnownPollPeriod: 60 * 10 });
+  await syncPromise;
+
+  return client;
+}
+
+async function waitForSync(client: MatrixClient): Promise<void> {
+  // If there is a saved sync, the client will fire an additional sync event
+  // for restoring it before it runs the first network sync.
+  // However, the sync we want to wait for is the network sync,
+  // as the saved sync may be missing some state.
+  // Thus, don't resolve on the first sync when we know it's for the saved sync.
+  let waitForSavedSync = !!(await client.store.getSavedSyncToken());
+  return new Promise<void>((resolve, reject) => {
+    const onSync = (
+      state: SyncState,
+      _old: SyncState | null,
+      data?: ISyncStateData,
+    ): void => {
+      if (state === "PREPARED") {
+        if (waitForSavedSync) {
+          waitForSavedSync = false;
+        } else {
+          client.removeListener(ClientEvent.Sync, onSync);
+          resolve();
+        }
+      } else if (state === "ERROR") {
+        client.removeListener(ClientEvent.Sync, onSync);
+        reject(data?.error);
+      }
+    };
+    client.on(ClientEvent.Sync, onSync);
+  });
+}
@@ -5,21 +5,14 @@ SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
 Please see LICENSE in the repository root for full details.
 */

-import {
-  ClientEvent,
-  createClient,
-  IndexedDBStore,
-  MemoryStore,
-  Preset,
-  Visibility,
-} from "matrix-js-sdk";
-import { type ISyncStateData, type SyncState } from "matrix-js-sdk/lib/sync";
+// *Do not* import any client stores in this module, to keep the component
+// build lean.
+import { ClientEvent, Preset, Visibility } from "matrix-js-sdk";
 import { logger } from "matrix-js-sdk/lib/logger";
 import { secureRandomBase64Url } from "matrix-js-sdk/lib/randomstring";

-import type { ICreateClientOpts, MatrixClient, Room } from "matrix-js-sdk";
-import IndexedDBWorker from "../IndexedDBWorker?worker";
-import { generateUrlSearchParams, getUrlParams } from "../UrlParams";
+import type { MatrixClient, Room } from "matrix-js-sdk";
+import { generateUrlSearchParams } from "../UrlParams";
 import { Config } from "../config/Config";
 import { E2eeType } from "../e2ee/e2eeType";
 import {
@@ -30,146 +23,6 @@ import {
 export const fallbackICEServerAllowed =
  import.meta.env.VITE_FALLBACK_STUN_ALLOWED === "true";

-const SYNC_STORE_NAME = "element-call-sync";
-
-async function waitForSync(client: MatrixClient): Promise<void> {
-  // If there is a saved sync, the client will fire an additional sync event
-  // for restoring it before it runs the first network sync.
-  // However, the sync we want to wait for is the network sync,
-  // as the saved sync may be missing some state.
-  // Thus, don't resolve on the first sync when we know it's for the saved sync.
-  let waitForSavedSync = !!(await client.store.getSavedSyncToken());
-  return new Promise<void>((resolve, reject) => {
-    const onSync = (
-      state: SyncState,
-      _old: SyncState | null,
-      data?: ISyncStateData,
-    ): void => {
-      if (state === "PREPARED") {
-        if (waitForSavedSync) {
-          waitForSavedSync = false;
-        } else {
-          client.removeListener(ClientEvent.Sync, onSync);
-          resolve();
-        }
-      } else if (state === "ERROR") {
-        client.removeListener(ClientEvent.Sync, onSync);
-        reject(data?.error);
-      }
-    };
-    client.on(ClientEvent.Sync, onSync);
-  });
-}
-
-/**
- * Initialises and returns a new standalone Matrix Client.
- * This can only be called safely if no other client is running
- * otherwise rust crypto will throw since it is not ready to initialize a new session.
- * If another client is running make sure `.logout()` is called before executing this function.
- * @param clientOptions Object of options passed through to the client
- * @param restore If the rust crypto should be reset before the client initialization or
- * if the initialization should try to restore the crypto state from the indexDB.
- * @returns The MatrixClient instance
- */
-export async function initClient(
-  clientOptions: ICreateClientOpts,
-  restore: boolean,
-): Promise<MatrixClient> {
-  let indexedDB: IDBFactory | undefined;
-  try {
-    indexedDB = window.indexedDB;
-  } catch (e) {
-    logger.warn("Could not get indexDB from window.", e);
-  }
-
-  // options we always pass to the client (stuff that we need in order to work)
-  const baseOpts = {
-    fallbackICEServerAllowed: fallbackICEServerAllowed,
-    isVoipWithNoMediaAllowed:
-      Config.get().features?.feature_group_calls_without_video_and_audio,
-  } as ICreateClientOpts;
-
-  if (indexedDB && localStorage) {
-    baseOpts.store = new IndexedDBStore({
-      indexedDB: window.indexedDB,
-      localStorage,
-      dbName: SYNC_STORE_NAME,
-      // We can't use the worker in dev mode because Vite simply doesn't bundle workers
-      // in dev mode: it expects them to use native modules. Ours don't, and even then only
-      // Chrome supports it. (It bundles them fine in production mode.)
-      workerFactory: import.meta.env.DEV
-        ? undefined
-        : (): Worker => new IndexedDBWorker(),
-    });
-  } else if (localStorage) {
-    baseOpts.store = new MemoryStore({ localStorage });
-  }
-
-  // XXX: we read from the URL params in RoomPage too:
-  // it would be much better to read them in one place and pass
-  // the values around, but we initialise the matrix client in
-  // many different places so we'd have to pass it into all of
-  // them.
-  const { e2eEnabled } = getUrlParams();
-  if (!e2eEnabled) {
-    logger.info("Disabling E2E: group call signalling will NOT be encrypted.");
-  }
-
-  const client = createClient({
-    ...baseOpts,
-    ...clientOptions,
-    useAuthorizationHeader: true,
-    // Use a relatively low timeout for API calls: this is a realtime app
-    // so we don't want API calls taking ages, we'd rather they just fail.
-    localTimeoutMs: 5000,
-    useE2eForGroupCall: e2eEnabled,
-    fallbackICEServerAllowed: fallbackICEServerAllowed,
-  });
-
-  // In case of logging in a new matrix account but there is still crypto local store. This is needed for:
-  // - We lost the auth tokens and cannot restore the client resulting in registering a new user.
-  // - We start the sign in flow but are registered with a guest user. (It should additionally log out the guest before)
-  // - A new account is created because of missing LocalStorage: "matrix-auth-store", but the crypto IndexDB is still available.
-  if (!restore) {
-    await client.clearStores();
-  }
-
-  // Start client store.
-  // Note: The `client.store` is used to store things like sync results. It's independent of
-  // the cryptostore, and uses a separate indexeddb database.
-  try {
-    await client.store.startup();
-  } catch (error) {
-    logger.error(
-      "Error starting matrix client indexDB store. Falling back to memory store.",
-      error,
-    );
-    client.store = new MemoryStore({ localStorage });
-    await client.store.startup();
-  }
-
-  // Also creates and starts any crypto related stores.
-  try {
-    await client.initRustCrypto();
-  } catch (err) {
-    logger.warn(
-      err,
-      "Make sure to clear client stores before initializing the rust crypto.",
-    );
-  }
-
-  // Once startClient is called, syncs are run asynchronously.
-  // Also, sync completion is communicated only via events.
-  // So, apply the event listener *before* starting the client.
-  // Otherwise, a sync may complete before the listener gets applied,
-  // and we will miss it.
-  const syncPromise = waitForSync(client);
-  await client.startClient({ clientWellKnownPollPeriod: 60 * 10 });
-  await syncPromise;
-
-  return client;
-}
-
 export function roomAliasLocalpartFromRoomName(roomName: string): string {
  return roomName
    .trim()
@@ -1,62 +0,0 @@
-/*
-Copyright 2024 New Vector Ltd.
-
-SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
-Please see LICENSE in the repository root for full details.
-*/
-
-import { type ICreateClientOpts, MatrixError } from "matrix-js-sdk";
-import { logger } from "matrix-js-sdk/lib/logger";
-
-import { Config } from "../config/Config";
-import { fallbackICEServerAllowed, initClient } from "./matrix";
-import type { InitResult, Session } from "../ClientContext";
-
-export async function initSPA(
-  loadSession: () => Session | undefined,
-  clearSession: () => void,
-): Promise<InitResult | null> {
-  // We're running as a standalone application
-  try {
-    const session = loadSession();
-    if (!session) {
-      logger.log("No session stored; continuing without a client");
-      return null;
-    }
-
-    logger.log("Using a standalone client");
-
-    /* eslint-disable camelcase */
-    const { user_id, device_id, access_token, passwordlessUser } = session;
-    const initClientParams: ICreateClientOpts = {
-      baseUrl: Config.defaultHomeserverUrl()!,
-      accessToken: access_token,
-      userId: user_id,
-      deviceId: device_id,
-      fallbackICEServerAllowed,
-      livekitServiceURL: Config.get().livekit?.livekit_service_url,
-    };
-
-    try {
-      const client = await initClient(initClientParams, true);
-      return {
-        client,
-        passwordlessUser,
-      };
-    } catch (err) {
-      if (err instanceof MatrixError && err.errcode === "M_UNKNOWN_TOKEN") {
-        // We can't use this session anymore, so let's log it out
-        logger.log(
-          "The session from local store is invalid; continuing without a client",
-        );
-        clearSession();
-        // returning null = "no client` pls register" (undefined = "loading" which is the current value when reaching this line)
-        return null;
-      }
-      throw err;
-    }
-  } catch (err) {
-    clearSession();
-    throw err;
-  }
-}
Author	SHA1	Message	Date
Timo K.	80ca4d7e0f	Add basic tests for refactored files	2026-11-12 17:47:27 +01:00
Timo K.	a2e3a2c13f	review	2026-11-12 13:25:45 +01:00
Timo K.	8d5d482771	Remove the derived hooks from ClientContext Those were hooks just used in one place. We move them directly into their component. This is acceptable because the disconnect banner needs a new appraoch when not having a syncing clinet but just a matrixBackend.	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	87f2726dd8	Hand the client provider a session ClientProvider had a `client` prop and a `loadClient` prop and ran the session in an effect: restoring, exposing setClient, changePassword and logout, and holding the "load" broadcast. It takes one `ClientSession` now and only renders what the session says, so the context carries the session itself rather than a parallel `ClientState` shape. - main.tsx builds a `StandaloneClientSession` for the SPA and a `pendingHostClientSession` for the widget; App.tsx no longer waits for the widget client itself. The component wraps the host's client in a `hostClientSession`. - The login and registration pages call `session.login` and `session.register`, and sign a registration in with `setSignedIn` once they are done with the account, in place of `setClient`. The two wrapper hooks and `utils/spa` go; their logic lives in the holder. - `useClient` and `useClientLegacy` keep their shapes minus `setClient`; `useClientSession` and `useClientSessionState` are the new way in. Logging out leaves for home and resets analytics from `useClientLegacy`, as before, around the session's own logout. - `useClientDisconnected` reads the session state directly. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	5fb9d6a81e	Add a client session holder for the standalone app Where the client comes from, and what may be done with the session behind it, is state that outlives any React tree: main.tsx, the widget and the component each need to construct a different one and hand it down. `ClientSession` names that: a Behavior of the session state plus the actions a session offers, which are absent when the session is not Element Call's to manage. `hostClientSession` wraps a client a host already has, `pendingHostClientSession` one still arriving over the widget API. `StandaloneClientSession` is the one for the SPA. Nothing in it is new logic: `restore` is `initSPA` from `utils/spa`; `login`, `register` and `createClient` are the tails of `useInteractiveLogin` and `useInteractiveRegistration` after the auth split; `changePassword`, `logout` and the "load" broadcast that shuts other instances down are lifted out of `ClientProvider`. Registering and signing in are separate steps, as a caller may have more to do with the account before the session changes hands. `StoredSession` is `Session` from the context, which goes once the provider takes a session. Nothing consumes the holder yet; the next commit switches the provider over. Both are tested through every state here, while the code they replace is still around to compare against. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	ba6bcdc4eb	Separate interactive auth from client creation The login and registration hooks each did three things: talk the user-interactive auth flow through with the homeserver, start a client on the credentials it handed out, and, for registration, fetch the terms and recaptcha key. Only the first is auth. `interactiveAuth.ts` keeps that part as two plain functions, with the UIA bodies moved verbatim, so they can be unit tested without React or a client store: `loginWithPassword` and `registerWithPassword` resolve to the credentials the homeserver issued and nothing else. Fetching the terms is `useRegistrationTerms` now. The two hooks are left as thin wrappers that compose the pieces, with the same signatures, so their callers do not change in this commit. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	56d73d1dfc	Track the client's connection in a hook of its own Whether the client is disconnected is a fact about the client's sync, not about the session, yet the provider owned the sync listener and put the flag on the context state, so the banner had to reach through the whole `ClientState` to read it. `useClientDisconnected` listens on whichever client is signed in, tagging its verdict with that client so a swapped client does not inherit the old one's before its first sync. The avatar, which only needs the client, takes it from `useClient` in the same spirit: consumers read the narrowest hook that answers them. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	89ad1ec936	Read reaction support from the host bridge The client context copied `hostBridge.supportsReactions` into a `supportedFeatures` field, and the one consumer, the reactions sender, read it from there. It reads the host bridge itself now, which is where the fact comes from; the context carries one thing less that has nothing to do with the client. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Timo K.andClaude Fable 5.1	b9a3cc6678	Reword the store worker comments Shorter notes on why `initClient` has a module of its own and why `utils/matrix` must not import a client store; the reasoning is the same. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-12 13:25:45 +01:00
Johannes Marbach	99f48ff987	Merge pull request #4454 from element-hq/johannes/lk-jwt-service-0.10.0 Bump lk-jwt-service to 0.10.0	2026-11-12 13:01:09 +01:00
Timo	6846c8dd3e	Merge pull request #4431 from element-hq/toger5/component-no-store-worker Keep the store worker out of the component package	2026-11-12 12:27:47 +01:00
Johannes Marbach	28ee707ace	Bump lk-jwt-service to 0.10.0	2026-11-12 08:29:26 +01:00
Timo K.andClaude Fable 5.1	3100c1c410	Cover the standalone client's initialisation and session restore Neither had a test before the move, so the moved lines showed up as uncovered. The client initialisation is tested through a fake client and mocked stores: which store it syncs into with and without IndexedDB, with and without the worker, the fallback to memory when the IndexedDB store cannot start, clearing the stores only when not restoring, carrying on without crypto, and counting as ready only after a sync from the network rather than the one restored from the store. The session restore is tested for no stored session, a restored one, one the homeserver no longer knows, and any other failure. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-11 19:24:21 +01:00
Timo K.andClaude Fable 5.1	fc1e91f54c	Keep the store worker out of the component package The package carried the standalone app's IndexedDB store worker: 11 MB with a copy of the Matrix SDK and its crypto wasm, referenced by an absolute path no host could serve, and never used by the component, which takes the host's client. The bundler emits the worker file as soon as it loads the `?worker` import, used or not, and the import sat in the Matrix utilities the component reaches for the room URLs. The client initialisation moves into a module of its own, with the worker import, which only the standalone login, registration and session restore paths import. ClientProvider takes the session loader through a `loadClient` prop instead of importing it itself, since even a dynamic import keeps a module in the package: the standalone app passes a lazy `initSPA` from App.tsx, the component passes nothing, and given neither a client nor a loader no one is signed in. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>	2026-11-11 19:24:21 +01:00