@oxyhq/services 27.1.3 → 29.0.0

package/lib/module/ui/context/OxyContext.js

@@ -13,8 +13,7 @@ import { isWebBrowser } from "../utils/isWebBrowser.js";
 import { resolveDeliveryPlatform } from "../utils/deliveryPlatform.js";
 import { runProviderColdBoot } from "../boot/runProviderColdBoot.js";
 import { loadPersistedDeviceCredential } from "../utils/deviceCredential.js";
-import { useAuthStore } from "../stores/authStore.js";
-import { useShallow } from 'zustand/react/shallow';
+import { bindAuthStoreToRuntime } from "../stores/authStore.js";
 import { useLanguageManagement } from "../hooks/useLanguageManagement.js";
 import { useSessionManagement } from "../hooks/useSessionManagement.js";
 import { useAuthOperations, clearPersistedAuthSafe } from "./hooks/useAuthOperations.js";
@@ -25,17 +24,35 @@ import { presentDetached, topRouteSurface } from "../navigation/surfaces.js";
 import { useQueryClient, onlineManager } from '@tanstack/react-query';
 import { clearQueryCache } from "../hooks/queryClient.js";
 import { useAvatarPicker } from "../hooks/useAvatarPicker.js";
-import { useAccountStore } from "../stores/accountStore.js";
-import { createSessionClient, createIdentitySessionBinding, createPlatformAuthStateStore, deviceStateToClientSessions, activeSessionIdOf, activeUserOf, accountIdsOf, IdentityBoundSessionError, useBackgroundSessionSync } from "../session/index.js";
-import { DEFAULT_SESSION_VALIDITY_MS, loadUseFollowHook } from "./oxyContextHelpers.js";
+import { resetSessionScopedStores } from "../stores/resetSessionScopedStores.js";
+import { ASSET_DOWNLOAD_URLS_QUERY_KEY } from "../hooks/useResolvedFileUrls.js";
+import { createOxyRuntime, OxyRuntimeHandleProvider, useRuntimeSnapshot } from "../runtime/index.js";
+import { createSessionClient, createIdentitySessionBinding, createPlatformAuthStateStore, IdentityBoundSessionError, useBackgroundSessionSync } from "../session/index.js";
+import { DEFAULT_SESSION_VALIDITY_MS } from "./oxyContextHelpers.js";
+// `useFollow` imports this module back, so the binding must only be READ inside
+// the provider body — at render time, once every module has evaluated. It is
+// never dereferenced at module scope here.
+import { useFollow } from "../hooks/useFollow.js";
 import { commitDeviceSetAndResolve } from "./commitSessionFlow.js";
 import { runPasskeyLogin, runPasskeyRegister, runPasskeyAdd } from "./passkeyFlow.js";
 import { isPasskeySupported, runRegistrationCeremony, runAuthenticationCeremony } from '../../webauthn/passkeyClient';
 import { queryKeys } from "../hooks/queries/queryKeys.js";
 import { useOxyAccountGraph } from "./useOxyAccountGraph.js";
 import { jsx as _jsx } from "react/jsx-runtime";
-const OxyContext = /*#__PURE__*/createContext(null);
-export const OxyProvider = ({
+const OxyRuntimeContext = /*#__PURE__*/createContext(null);
+
+/**
+ * The SDK's internal runtime provider — the session/account state machine that
+ * backs `useOxy()`.
+ *
+ * This is NOT the component consumers mount. The one public composition root is
+ * `OxyProvider` (`../components/OxyProvider`), which mounts this alongside the
+ * QueryClient, Bloom's dialog/surface/toast hosts, safe areas, the gesture root
+ * and the keyboard provider. Naming both of them `OxyProvider` (as this file
+ * used to) made every error message, stack frame and doc reference ambiguous —
+ * see ADR 0004.
+ */
+export const OxyRuntimeProvider = ({
   children,
   oxyServices: providedOxyServices,
   baseURL,
@@ -47,6 +64,7 @@ export const OxyProvider = ({
   sessionMode = 'account',
   webAuthMode = 'popup',
   backgroundSession = false,
+  deviceCredentialStorage = 'persistent',
   onAuthStateChange,
   onError
 }) => {
@@ -63,17 +81,24 @@ export const OxyProvider = ({
         authRedirectUri
       });
     } else {
-      throw new Error('Either oxyServices or baseURL must be provided to OxyContextProvider');
+      throw new Error('Either oxyServices or baseURL must be provided to OxyProvider');
     }
   }
   const oxyServices = oxyServicesRef.current;
 
-  // The device-first persisted auth-state store (per-origin zero-cookie device
-  // credential on web; SecureStore session blob on native). Built ONCE per
-  // provider mount.
+  // The device-first persisted auth-state store (per-origin device credential on
+  // web; SecureStore session blob on native). Built ONCE per provider mount.
+  //
+  // `deviceCredentialStorage` is mount-time configuration for the same reason
+  // `sessionMode` is: it decides where the durable credential lives, and letting
+  // it change mid-flight would mean a session that started ephemeral could begin
+  // writing one.
   const authStoreRef = useRef(null);
   if (!authStoreRef.current) {
-    authStoreRef.current = createPlatformAuthStateStore();
+    authStoreRef.current = createPlatformAuthStateStore({
+      sessionMode,
+      storage: deviceCredentialStorage
+    });
   }
   const authStore = authStoreRef.current;
 
@@ -93,34 +118,92 @@ export const OxyProvider = ({
   }
   const identity = identityRef.current;
   const isIdentityBound = identity !== null;
+  const logger = useCallback((message, err) => {
+    if (__DEV__) {
+      loggerUtil.warn(message, {
+        component: 'OxyContext'
+      }, err);
+    }
+  }, []);
+
+  // Server-authoritative device session client. Built ONCE per `oxyServices`
+  // instance. Device-scoped sockets connect with deviceId+deviceSecret when no
+  // bearer is planted yet, so cross-origin apps sync via `session_state`.
+  const sessionClientPairRef = useRef(null);
+  if (!sessionClientPairRef.current) {
+    sessionClientPairRef.current = createSessionClient(oxyServices, origin => {
+      // Erase the DURABLE device credential only on a `request`-origin verdict
+      // (a REST sign-out / revocation). A `push`-origin empty state is a socket
+      // broadcast that may be a transient reconnect artifact — clearing the
+      // credential on it would strand the user signed out with no way back, so
+      // we clear only the local UI session and keep the credential (a dead one
+      // re-mints to `no_active_session` and resolves signed-out on next boot).
+      if (origin === 'request') {
+        clearPersistedAuthSafe(authStore, logger);
+      }
+      void clearSessionStateRef.current().catch(clearError => {
+        logger('Failed to clear local state on remote sign-out', clearError);
+      });
+    },
+    // `null` for every account-mode provider — identical to omitting the
+    // option — and the pinned account id once an identity-bound provider has
+    // resolved its pin. Read through the ref so the resolver stays stable for
+    // the client's lifetime while still seeing later resolutions.
+    () => identityRef.current?.getPinnedAccountId() ?? null);
+  }
   const {
-    user,
-    isAuthenticated,
+    client: sessionClient,
+    host: sessionClientHost
+  } = sessionClientPairRef.current;
+
+  // ── The runtime ──────────────────────────────────────────────────────────
+  // One owner for the session facts (ADR 0004), built ONCE and never rebuilt,
+  // so the context value below can hand out a reference that never changes.
+  //
+  // Its three callbacks reach forward through refs because the collaborators
+  // they need — the storage-backed teardown, the account-graph refresh — are
+  // hooks declared after it. Latching the runtime here rather than after them
+  // is deliberate: a runtime rebuilt mid-flight would drop its `SessionClient`
+  // subscription and every subscriber with it.
+  const clearSessionStateRef = useRef(() => Promise.resolve());
+  const saveSessionIdsRef = useRef(() => undefined);
+  const subjectChangeRef = useRef(() => undefined);
+  const reestablishRef = useRef(() => undefined);
+  const runtimeRef = useRef(null);
+  if (!runtimeRef.current) {
+    runtimeRef.current = createOxyRuntime({
+      oxyServices,
+      sessionClient,
+      sessionClientHost,
+      identity,
+      onSubjectChange: transition => subjectChangeRef.current(transition),
+      onDeviceEmpty: () => clearSessionStateRef.current(),
+      onSessionsProjected: sessionIds => saveSessionIdsRef.current(sessionIds),
+      onIdentityUnbound: (binding, revision) => reestablishRef.current(binding, revision),
+      logger
+    });
+  }
+  const runtime = runtimeRef.current;
+  const snapshot = useRuntimeSnapshot(runtime);
+  const {
+    account: user,
+    sessions,
+    activeSessionId,
     isLoading,
-    error,
-    loginSuccess,
-    loginFailure,
-    logoutStore
-  } = useAuthStore(useShallow(state => ({
-    user: state.user,
-    isAuthenticated: state.isAuthenticated,
-    isLoading: state.isLoading,
-    error: state.error,
-    loginSuccess: state.loginSuccess,
-    loginFailure: state.loginFailure,
-    logoutStore: state.logout
-  })));
-  const [tokenReady, setTokenReady] = useState(true);
-  const [hasAccessToken, setHasAccessToken] = useState(() => Boolean(oxyServices.getAccessToken()));
-  const [authResolved, setAuthResolved] = useState(false);
-  const authResolvedRef = useRef(false);
-  const userRef = useRef(user);
-  const isAuthenticatedRef = useRef(isAuthenticated);
-  userRef.current = user;
-  isAuthenticatedRef.current = isAuthenticated;
+    tokenReady,
+    hasAccessToken,
+    authResolved
+  } = snapshot;
+  const isAuthenticated = user !== null;
+  const error = snapshot.error?.message ?? null;
   const [initialized, setInitialized] = useState(false);
   const [accountDialogOpen, setAccountDialogOpen] = useState(false);
-  const setAuthState = useAuthStore.setState;
+
+  // Project the runtime onto `useAuthStore`, which a dozen out-of-band callers
+  // (mutation success handlers, cache helpers, the Commons app) still read the
+  // signed-in user through. It is a projection, not a second store.
+  useEffect(() => bindAuthStoreToRuntime(runtime), [runtime]);
+  useEffect(() => runtime.start(), [runtime]);
 
   // Keep the shared `oxyClient` singleton's token store in lockstep with the
   // session owned by THIS provider's instance (many apps build API clients
@@ -140,13 +223,6 @@ export const OxyProvider = ({
     applyToSingleton(oxyServices.getAccessToken());
     return oxyServices.onTokensChanged(applyToSingleton);
   }, [oxyServices]);
-  const logger = useCallback((message, err) => {
-    if (__DEV__) {
-      loggerUtil.warn(message, {
-        component: 'OxyContext'
-      }, err);
-    }
-  }, []);
   const storageKeys = useMemo(() => getStorageKeys(storageKeyPrefix), [storageKeyPrefix]);
   const clientId = useMemo(() => {
     const trimmed = clientIdProp?.trim();
@@ -180,6 +256,7 @@ export const OxyProvider = ({
       storageReady.resolve(storageInstance);
       if (mounted) {
         setStorage(storageInstance);
+        runtime.setStorageReady(true);
       }
     }).catch(err => {
       if (mounted) {
@@ -194,7 +271,7 @@ export const OxyProvider = ({
     return () => {
       mounted = false;
     };
-  }, [logger, onError, storageReady]);
+  }, [logger, onError, runtime, storageReady]);
   const {
     currentLanguage,
     languages: currentLanguages,
@@ -211,85 +288,36 @@ export const OxyProvider = ({
   });
   const queryClient = useQueryClient();
   const {
-    sessions,
-    activeSessionId,
-    setActiveSessionId,
-    updateSessions,
+    saveSessionIds,
     switchSession,
     clearSessionState,
     saveActiveSessionId
   } = useSessionManagement({
     oxyServices,
+    runtime,
     storage,
     storageKeyPrefix,
-    loginSuccess,
-    logoutStore,
     onAuthStateChange,
     onError,
-    setAuthError: message => setAuthState({
-      error: message
-    }),
+    setAuthError: message => runtime.setError(message),
     logger,
-    setTokenReady,
     queryClient
   });
-
-  // Refs so callbacks below can invoke the latest session-management functions
-  // without widening dependency arrays.
-  const switchSessionRef = useRef(switchSession);
-  switchSessionRef.current = switchSession;
-  const clearSessionStateRef = useRef(clearSessionState);
   clearSessionStateRef.current = clearSessionState;
-  const setActiveSessionIdRef = useRef(setActiveSessionId);
-  setActiveSessionIdRef.current = setActiveSessionId;
-  const loginSuccessRef = useRef(loginSuccess);
-  loginSuccessRef.current = loginSuccess;
+  saveSessionIdsRef.current = saveSessionIds;
   const onAuthStateChangeRef = useRef(onAuthStateChange);
   onAuthStateChangeRef.current = onAuthStateChange;
 
-  // Flip the auth-resolution gate (`authResolved` + `tokenReady`) the moment a
-  // session commits or the boot concludes signed out. Idempotent + monotonic.
+  // Flip the auth-resolution gate the moment a session commits or the boot
+  // concludes signed out. Idempotent + monotonic, enforced by the runtime.
   const markAuthResolved = useCallback(() => {
-    if (authResolvedRef.current) {
-      return;
-    }
-    authResolvedRef.current = true;
-    setTokenReady(true);
-    setAuthResolved(true);
-  }, []);
+    runtime.markAuthResolved();
+  }, [runtime]);
   const markAuthResolvedRef = useRef(markAuthResolved);
   markAuthResolvedRef.current = markAuthResolved;
-
-  // Server-authoritative device session client. Built ONCE per `oxyServices`
-  // instance. Device-scoped sockets connect with deviceId+deviceSecret when no
-  // bearer is planted yet, so cross-origin apps sync via `session_state` after
-  // the one-shot join redirect.
-  const sessionClientPairRef = useRef(null);
-  if (!sessionClientPairRef.current) {
-    sessionClientPairRef.current = createSessionClient(oxyServices, origin => {
-      // Erase the DURABLE device credential only on a `request`-origin verdict
-      // (a REST sign-out / revocation). A `push`-origin empty state is a socket
-      // broadcast that may be a transient reconnect artifact — clearing the
-      // credential on it would strand the user signed out with no way back, so
-      // we clear only the local UI session and keep the credential (a dead one
-      // re-mints to `no_active_session` and resolves signed-out on next boot).
-      if (origin === 'request') {
-        clearPersistedAuthSafe(authStore, logger);
-      }
-      void clearSessionStateRef.current().catch(clearError => {
-        logger('Failed to clear local state on remote sign-out', clearError);
-      });
-    },
-    // `null` for every account-mode provider — identical to omitting the
-    // option — and the pinned account id once an identity-bound provider has
-    // resolved its pin. Read through the ref so the resolver stays stable for
-    // the client's lifetime while still seeing later resolutions.
-    () => identityRef.current?.getPinnedAccountId() ?? null);
-  }
-  const {
-    client: sessionClient,
-    host: sessionClientHost
-  } = sessionClientPairRef.current;
+  const setTokenReady = useCallback(ready => {
+    runtime.setTokenReady(ready);
+  }, [runtime]);
 
   // Re-establishment lane for an identity-bound provider whose pin is missing or
   // whose pinned account is no longer part of this device's session set (another
@@ -334,78 +362,22 @@ export const OxyProvider = ({
       tracker.inFlight = false;
     });
   }, [oxyServices, authStore, sessionClient, logger]);
+  reestablishRef.current = reestablishIdentitySession;
 
-  // Projects `client.getState()` onto the exposed `sessions`/`activeSessionId`/
-  // `user`. Sole authority for both locally-initiated mutations (switch/logout)
-  // AND remotely-pushed `session_state` over the `device:<deviceId>` socket.
-  const syncFromClient = useCallback(async () => {
-    const state = sessionClient.getState();
-    if (state === null) {
-      return;
-    }
-    if (state.accounts.length === 0) {
-      // Clear the LOCAL UI session on any applied empty state, but NEVER the
-      // durable device credential here: `syncFromClient` runs for socket-pushed
-      // (possibly transient) states too, and wiping the credential on one would
-      // strand the user signed out. The credential wipe is gated on a
-      // `request`-origin verdict in `onUnauthenticated` above.
-      sessionClientHost.setCurrentAccountId(null);
-      await clearSessionState();
-      return;
-    }
-    // Last-write-wins guard: capture the revision this projection is for, then
-    // after the async profile fetch bail if a fresher state has landed.
-    const capturedRevision = state.revision;
-    // Resolve the pin BEFORE the profile fetch (memoised: one storage + keychain
-    // read per boot) so every projection below is bound on the FIRST pass over a
-    // freshly applied state. Deferring it would let a sibling app's switch render
-    // once as this client's user before the pin corrected it. `null` for every
-    // account-mode provider, where each projection falls back to the device's
-    // active account exactly as before.
-    const pinnedAccountId = identity ? await identity.ensurePinnedAccountId() : null;
-    const ids = accountIdsOf(state);
-    let users = [];
-    try {
-      users = ids.length > 0 ? await oxyServices.getUsersByIds(ids) : [];
-    } catch (fetchError) {
-      logger('Failed to resolve account profiles during syncFromClient', fetchError);
-      return;
-    }
-    const latest = sessionClient.getState();
-    if (!latest || latest.revision !== capturedRevision) {
-      return;
-    }
-    if (identity && (pinnedAccountId === null || activeSessionIdOf(latest, pinnedAccountId) === null)) {
-      // Either no verified pin, or the pinned account left this device's session
-      // set. Projecting anything here would mean projecting SOMEBODY ELSE's
-      // account, so leave the current projection untouched and re-derive the
-      // session from the local identity key instead.
-      reestablishIdentitySession(identity, latest.revision);
-      return;
-    }
-    const usersById = new Map(users.map(resolvedUser => [resolvedUser.id, resolvedUser]));
-    updateSessions(deviceStateToClientSessions(latest, usersById, pinnedAccountId));
-    setActiveSessionId(activeSessionIdOf(latest, pinnedAccountId));
-    const activeUser = activeUserOf(latest, usersById, pinnedAccountId);
-    if (activeUser) {
-      loginSuccess(activeUser);
-    }
-    // The host's current account feeds the socket handshake and the bearer's
-    // token-account comparisons, so it tracks the PIN — never the account another
-    // app switched the device to.
-    sessionClientHost.setCurrentAccountId(pinnedAccountId ?? latest.activeAccountId);
-  }, [identity, oxyServices, reestablishIdentitySession, sessionClient, sessionClientHost, updateSessions, setActiveSessionId, loginSuccess, clearSessionState, logger]);
+  /**
+   * Project the server-authoritative device state onto the runtime.
+   *
+   * The projection itself lives in the runtime; this is the awaitable handle
+   * the commit/logout/reconnect paths already had. It is stable, because the
+   * runtime is.
+   */
+  const syncFromClient = useCallback(() => runtime.reconcileFromClient(), [runtime]);
   const syncFromClientRef = useRef(syncFromClient);
   syncFromClientRef.current = syncFromClient;
   const syncDeviceCredentialToHost = useCallback(async () => {
     const cred = await loadPersistedDeviceCredential(authStore);
     sessionClientHost.setDeviceCredential(cred);
   }, [authStore, sessionClientHost]);
-  useEffect(() => {
-    return sessionClient.subscribe(() => {
-      void syncFromClient();
-    });
-  }, [sessionClient, syncFromClient]);
   const {
     signIn,
     logout,
@@ -414,9 +386,7 @@ export const OxyProvider = ({
     oxyServices,
     store: authStore,
     storage,
-    activeSessionId,
-    setActiveSessionId,
-    updateSessions,
+    runtime,
     saveActiveSessionId,
     clearSessionState,
     switchSession,
@@ -424,10 +394,6 @@ export const OxyProvider = ({
     syncFromClient,
     onAuthStateChange,
     onError,
-    loginSuccess,
-    loginFailure,
-    logoutStore,
-    setAuthState,
     logger,
     ...(identity ? {
       identityBinding: identity.binding,
@@ -456,7 +422,6 @@ export const OxyProvider = ({
     // Explicit FULL wipe: also drop the persisted device credential so a reload
     // finds nothing to restore.
     await authStore.clear();
-    useAccountStore.getState().reset();
     oxyServices.clearCache();
   }, [queryClient, storage, clearSessionState, authStore, logger, oxyServices]);
   const {
@@ -470,7 +435,6 @@ export const OxyProvider = ({
     clearSessionState,
     logger
   });
-  const useFollowHook = loadUseFollowHook();
 
   // Token-change side effects: an invalidated bearer (HttpService clears tokens
   // on an unrecoverable 401 and emits `null`) must locally sign out an
@@ -481,16 +445,16 @@ export const OxyProvider = ({
   const clearingInvalidTokenRef = useRef(false);
   useEffect(() => {
     const handleTokenChange = accessToken => {
-      setHasAccessToken(Boolean(accessToken));
+      runtime.setHasAccessToken(Boolean(accessToken));
       if (accessToken) {
-        setTokenReady(true);
+        runtime.setTokenReady(true);
         if (sessionClient.getState()?.accounts.length) {
           void syncFromClientRef.current();
         }
         return;
       }
-      if (userRef.current || isAuthenticatedRef.current) {
-        setTokenReady(false);
+      if (runtime.getSnapshot().account !== null) {
+        runtime.setTokenReady(false);
         if (clearingInvalidTokenRef.current) {
           return;
         }
@@ -499,19 +463,19 @@ export const OxyProvider = ({
           logger('Failed to clear invalidated auth session', clearError);
         }).finally(() => {
           clearingInvalidTokenRef.current = false;
-          if (authResolvedRef.current) {
-            setTokenReady(true);
+          if (runtime.getSnapshot().authResolved) {
+            runtime.setTokenReady(true);
           }
         });
         return;
       }
-      if (authResolvedRef.current) {
-        setTokenReady(true);
+      if (runtime.getSnapshot().authResolved) {
+        runtime.setTokenReady(true);
       }
     };
     handleTokenChange(oxyServices.getAccessToken());
     return oxyServices.onTokensChanged(handleTokenChange);
-  }, [logger, oxyServices, sessionClient]);
+  }, [logger, oxyServices, runtime, sessionClient]);
 
   // Unified in-session refresh (SDK-owned; every RP inherits it). Installs the
   // ONE core refresh handler (re-mint from the persisted zero-cookie device
@@ -574,20 +538,25 @@ export const OxyProvider = ({
     }
 
     // Fast local mirror so the UI updates before the server round-trip; the
-    // SessionClient projection below overwrites it with server truth.
+    // SessionClient projection below overwrites it with server truth. Batched
+    // so the mirror and the active id land in ONE transition — unbatched, a
+    // subscriber woken between them would see the new session list still
+    // pointing at the previous active id.
     if (input.userId) {
       const now = new Date();
-      updateSessions([{
-        sessionId: input.sessionId,
-        deviceId: input.deviceId ?? '',
-        expiresAt: input.expiresAt || new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
-        lastActive: now.toISOString(),
-        userId: input.userId,
-        isCurrent: true
-      }], {
-        merge: true
+      runtime.batch(() => {
+        runtime.mergeSessions([{
+          sessionId: input.sessionId,
+          deviceId: input.deviceId ?? '',
+          expiresAt: input.expiresAt || new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
+          lastActive: now.toISOString(),
+          userId: input.userId,
+          isCurrent: true
+        }], {
+          merge: true
+        });
+        runtime.setActiveSessionId(input.sessionId);
       });
-      setActiveSessionId(input.sessionId);
     }
 
     // Register into the device set, hydrate the full user, and flip the
@@ -607,11 +576,11 @@ export const OxyProvider = ({
       startSocket: () => sessionClient.start(),
       syncFromClient,
       getCurrentUser: () => oxyServices.getCurrentUser(),
-      loginSuccess,
+      loginSuccess: fullUser => runtime.setAccount(fullUser),
       onAuthStateChange: onAuthStateChangeRef.current,
       markAuthResolved: markAuthResolvedRef.current
     });
-  }, [oxyServices, authStore, updateSessions, setActiveSessionId, sessionClient, sessionClientHost, syncFromClient, loginSuccess, logger]);
+  }, [oxyServices, authStore, runtime, sessionClient, sessionClientHost, syncFromClient, logger]);
   const commitSessionRef = useRef(commitSession);
   commitSessionRef.current = commitSession;
 
@@ -634,27 +603,6 @@ export const OxyProvider = ({
     });
   }, [commitSession]);
 
-  // Commit a minted graph-SWITCH session through the same funnel as
-  // `handleWebSession`. Nothing extra to do IN-PLACE: the switch already
-  // propagates across tabs/apps via the server's `session_state` socket
-  // broadcast.
-  const commitSwitchedSession = useCallback(async session => {
-    if (!session?.user || !session?.sessionId || !session.accessToken) {
-      throw new Error('Session response did not include a usable session');
-    }
-    await commitSession({
-      sessionId: session.sessionId,
-      accessToken: session.accessToken,
-      deviceSecret: session.deviceSecret,
-      deviceId: session.deviceId,
-      expiresAt: session.expiresAt,
-      userId: session.user.id,
-      user: session.user
-    }, {
-      activate: true
-    });
-  }, [commitSession]);
-
   // ── Web third-party OAuth sign-in ──────────────────────────────────────────
   // The shared operation `OxySignInButton` (and any RP-owned button) delegates
   // to, so no consumer ever writes popup listeners or a token exchange. The
@@ -674,13 +622,11 @@ export const OxyProvider = ({
   // ── Unified account dialog ─────────────────────────────────────────────────
   // The single account-chooser + sign-in surface. Built ONCE per provider mount
   // and bound to the live `oxyServices` + `sessionClient` + this provider's
-  // commit funnels. Both funnels are threaded through refs so the controller
-  // keeps STABLE commit callbacks (rebuilding the controller on every
-  // commit-identity change would drop its subscription + state).
+  // sign-in commit funnel, threaded through a ref so the controller keeps a
+  // STABLE commit callback (rebuilding the controller on every commit-identity
+  // change would drop its subscription + state).
   const handleWebSessionRef = useRef(handleWebSession);
   handleWebSessionRef.current = handleWebSession;
-  const commitSwitchedSessionRef = useRef(commitSwitchedSession);
-  commitSwitchedSessionRef.current = commitSwitchedSession;
 
   // The live AccountDialog surface (a stacked Bloom surface), while open — the
   // SINGLE source of truth for "is the account dialog open". Held so
@@ -723,12 +669,10 @@ export const OxyProvider = ({
       oxyServices,
       sessionClient,
       clientId,
-      locale: currentLanguage,
       // Same statically-injected `io` as the SessionClient: gives the QR flow an
       // instant `/auth-session` `auth_update` wake instead of a slow poll.
       socketFactory: io,
       commitSession: session => handleWebSessionRef.current(session),
-      commitSwitchedSession: session => commitSwitchedSessionRef.current(session),
       onSignedIn: () => {
         // Close the dialog: pop the morphed frame back to its host surface, or
         // dismiss the detached surface (whose settle flips `accountDialogOpen`).
@@ -947,7 +891,7 @@ export const OxyProvider = ({
     if (identity) {
       await identity.refreshPinnedAccountId();
     }
-  }, [oxyServices, authStore, clientIdProp, authRedirectUri, sessionMode, identity, syncDeviceCredentialToHost, sessionClient]);
+  }, [oxyServices, authStore, clientIdProp, authRedirectUri, sessionMode, identity, syncDeviceCredentialToHost, sessionClient, setTokenReady]);
   useEffect(() => {
     if (initialized) {
       return;
@@ -1046,12 +990,12 @@ export const OxyProvider = ({
     }
     await sessionClient.switchAccount(targetAccountId);
     await syncFromClient();
-    const activeUser = useAuthStore.getState().user;
+    const activeUser = runtime.getSnapshot().account;
     if (!activeUser) {
       throw new Error('Active account profile could not be resolved after switch');
     }
     return activeUser;
-  }, [isIdentityBound, sessionClient, syncFromClient]);
+  }, [isIdentityBound, runtime, sessionClient, syncFromClient]);
 
   // Thin passthroughs to the platform-agnostic KeyManager. NOTE: both now THROW
   // `IdentityUnavailableError` (from `@oxyhq/core`) when identity storage is
@@ -1087,10 +1031,44 @@ export const OxyProvider = ({
     sessionClient,
     syncFromClient,
     commitSession,
-    queryClient,
     accountDialogControllerRef,
     clearSessionStateRef
   });
+
+  // The account-scoped cache reset, run by the runtime BETWEEN committing the
+  // new subject's bearer and waking anybody (ADR 0002). It used to trail the two
+  // branches of `switchToAccount`, which meant a switch pushed over the socket
+  // by another app on this device got none of it: the follow stores, the scoped
+  // media URLs and every warm query stayed on the previous subject until
+  // something happened to refetch.
+  //
+  // An initial sign-in is deliberately exempt. There is nothing account-scoped
+  // cached before the first account, so invalidating everything there would only
+  // buy a refetch storm at first paint.
+  const handleSubjectChange = useCallback(({
+    previous,
+    next
+  }) => {
+    if (previous === null) {
+      return;
+    }
+    resetSessionScopedStores();
+    if (next === null) {
+      // A sign-out: `clearSessionState` owns the rest of the teardown, and
+      // invalidating a cache we are about to clear would only refetch as the
+      // bearer disappears.
+      return;
+    }
+    // Scoped media tokens are per-viewer — drop any cached URLs immediately so
+    // `keepPreviousData`-style placeholders cannot flash the prior account's
+    // private thumbnails while the new bearer mint lands.
+    queryClient.removeQueries({
+      queryKey: [ASSET_DOWNLOAD_URLS_QUERY_KEY]
+    });
+    queryClient.invalidateQueries();
+    void refreshAccounts();
+  }, [queryClient, refreshAccounts]);
+  subjectChangeRef.current = handleSubjectChange;
   const canUsePrivateApi = authResolved && isAuthenticated && tokenReady && hasAccessToken;
   const isPrivateApiPending = !authResolved || isAuthenticated && (!tokenReady || !hasAccessToken);
 
@@ -1116,7 +1094,7 @@ export const OxyProvider = ({
     canUsePrivateApi,
     isPrivateApiPending,
     isAuthResolved: authResolved,
-    isStorageReady: storage !== null,
+    isStorageReady: snapshot.storageReady,
     sessionMode: isIdentityBound ? 'identity' : 'account',
     webAuthMode,
     error,
@@ -1150,7 +1128,7 @@ export const OxyProvider = ({
     clientId,
     oxyServices,
     sessionClient,
-    useFollow: useFollowHook,
+    useFollow,
     showBottomSheet: showBottomSheetForContext,
     openAvatarPicker,
     accountDialogController,
@@ -1161,83 +1139,53 @@ export const OxyProvider = ({
     switchToAccount,
     refreshAccounts,
     createAccount: createAccountFn
-  }), [user, sessions, activeSessionId, isAuthenticated, isLoading, tokenReady, hasAccessToken, canUsePrivateApi, isPrivateApiPending, authResolved, storage, isIdentityBound, webAuthMode, error, currentLanguage, currentLanguages, currentLanguageMetadata, currentLanguageName, currentNativeLanguageName, hasIdentity, getPublicKey, signIn, signInWithPasskey, registerWithPasskey, addPasskey, removePasskey, revokeSuspiciousSignIn, handleWebSession, startWebOAuthSignInForContext, logout, logoutAll, switchSessionForContext, refreshSessionsForContext, setLanguage, getDeviceSessions, logoutAllDeviceSessions, updateDeviceName, clearSessionState, clearAllAccountData, storageKeyPrefix, clientId, oxyServices, sessionClient, useFollowHook, showBottomSheetForContext, openAvatarPicker, accountDialogController, accountDialogOpen, openAccountDialog, closeAccountDialog, accounts, switchToAccount, refreshAccounts, createAccountFn]);
-  return /*#__PURE__*/_jsx(OxyContext.Provider, {
-    value: contextValue,
-    children: children
+  }), [user, sessions, activeSessionId, isAuthenticated, isLoading, tokenReady, hasAccessToken, canUsePrivateApi, isPrivateApiPending, authResolved, snapshot.storageReady, isIdentityBound, webAuthMode, error, currentLanguage, currentLanguages, currentLanguageMetadata, currentLanguageName, currentNativeLanguageName, hasIdentity, getPublicKey, signIn, signInWithPasskey, registerWithPasskey, addPasskey, removePasskey, revokeSuspiciousSignIn, handleWebSession, startWebOAuthSignInForContext, logout, logoutAll, switchSessionForContext, refreshSessionsForContext, setLanguage, getDeviceSessions, logoutAllDeviceSessions, updateDeviceName, clearSessionState, clearAllAccountData, storageKeyPrefix, clientId, oxyServices, sessionClient, showBottomSheetForContext, openAvatarPicker, accountDialogController, accountDialogOpen, openAccountDialog, closeAccountDialog, accounts, switchToAccount, refreshAccounts, createAccountFn]);
+
+  // Two contexts, deliberately. The inner one carries the wide compatibility
+  // value every `useOxy()` consumer reads, rebuilt whenever any of its members
+  // moves. The outer one carries the runtime reference, which never changes
+  // identity — so `useActiveAccount()` and friends re-render on the fact they
+  // selected and nothing else. Phase 8 retires the inner one.
+  return /*#__PURE__*/_jsx(OxyRuntimeHandleProvider, {
+    value: runtime,
+    children: /*#__PURE__*/_jsx(OxyRuntimeContext.Provider, {
+      value: contextValue,
+      children: children
+    })
   });
 };
-export const OxyContextProvider = OxyProvider;
+const PROVIDER_MISSING_ERROR_MESSAGE = 'useOxy() was called outside <OxyProvider>. Mount <OxyProvider clientId="…"> above this component, ' + 'or use useOptionalOxy() if this component legitimately renders both inside and outside the provider.';
+export class OxyProviderMissingError extends Error {
+  code = 'oxy_provider_missing';
+  constructor() {
+    super(PROVIDER_MISSING_ERROR_MESSAGE);
+    this.name = 'OxyProviderMissingError';
+  }
+}
 
 /**
- * Loading-state stub used when `useOxy()` is called outside an OxyProvider.
- * All async methods reject with a clear error so misuse is caught early.
+ * The base runtime hook. THROWS when no `<OxyProvider>` is mounted.
+ *
+ * It used to return a fabricated forever-loading runtime — `isLoading: true`,
+ * `isPrivateApiPending: true`, every method a rejecting no-op — which turned a
+ * missing provider into a UI that spins forever with nothing in the console.
+ * Failing here names the mistake at the exact component that made it (ADR 0004).
+ *
+ * A component that legitimately renders both inside and outside the provider
+ * uses {@link useOptionalOxy} instead.
  */
-const PROVIDER_MISSING_ERROR_MESSAGE = 'OxyProvider is not mounted. Wrap your app in <OxyProvider> before calling useOxy() methods.';
-const rejectMissingProvider = () => Promise.reject(new Error(PROVIDER_MISSING_ERROR_MESSAGE));
-const LOADING_STATE_OXY_SERVICES = new OxyServices({
-  baseURL: 'about:blank'
-});
-const LOADING_STATE = {
-  user: null,
-  sessions: [],
-  activeSessionId: null,
-  isAuthenticated: false,
-  isLoading: true,
-  isTokenReady: false,
-  hasAccessToken: false,
-  canUsePrivateApi: false,
-  isPrivateApiPending: true,
-  isAuthResolved: false,
-  isStorageReady: false,
-  sessionMode: 'account',
-  webAuthMode: 'popup',
-  error: null,
-  currentLanguage: 'en-US',
-  currentLanguages: [],
-  currentLanguageMetadata: null,
-  currentLanguageName: 'English (United States)',
-  currentNativeLanguageName: 'English (United States)',
-  hasIdentity: () => Promise.resolve(false),
-  getPublicKey: () => Promise.resolve(null),
-  signIn: () => rejectMissingProvider(),
-  signInWithPasskey: () => rejectMissingProvider(),
-  registerWithPasskey: () => rejectMissingProvider(),
-  addPasskey: () => rejectMissingProvider(),
-  removePasskey: () => rejectMissingProvider(),
-  revokeSuspiciousSignIn: () => rejectMissingProvider(),
-  handleWebSession: () => rejectMissingProvider(),
-  startWebOAuthSignIn: () => rejectMissingProvider(),
-  logout: () => rejectMissingProvider(),
-  logoutAll: () => rejectMissingProvider(),
-  switchSession: () => rejectMissingProvider(),
-  removeSession: () => rejectMissingProvider(),
-  refreshSessions: () => rejectMissingProvider(),
-  setLanguage: () => rejectMissingProvider(),
-  getDeviceSessions: () => Promise.resolve([]),
-  logoutAllDeviceSessions: () => rejectMissingProvider(),
-  updateDeviceName: () => rejectMissingProvider(),
-  clearSessionState: () => rejectMissingProvider(),
-  clearAllAccountData: () => rejectMissingProvider(),
-  storageKeyPrefix: 'oxy_session',
-  clientId: null,
-  oxyServices: LOADING_STATE_OXY_SERVICES,
-  sessionClient: null,
-  openAvatarPicker: () => {},
-  accountDialogController: null,
-  isAccountDialogOpen: false,
-  openAccountDialog: () => {},
-  closeAccountDialog: () => {},
-  accounts: [],
-  switchToAccount: () => rejectMissingProvider(),
-  refreshAccounts: () => rejectMissingProvider(),
-  createAccount: () => rejectMissingProvider()
-};
 export const useOxy = () => {
-  const context = useContext(OxyContext);
+  const context = useContext(OxyRuntimeContext);
   if (!context) {
-    return LOADING_STATE;
+    throw new OxyProviderMissingError();
   }
   return context;
 };
+
+/**
+ * `useOxy()` for the rare component that renders both inside and outside the
+ * provider — returns `null` instead of throwing. Callers must handle `null`;
+ * there is no fabricated runtime to fall back on.
+ */
+export const useOptionalOxy = () => useContext(OxyRuntimeContext);
 //# sourceMappingURL=OxyContext.js.map