@oxyhq/services 27.1.3 → 29.0.0

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

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.useOxy = exports.OxyProvider = exports.OxyContextProvider = void 0;
+exports.useOxy = exports.useOptionalOxy = exports.OxyRuntimeProvider = exports.OxyProviderMissingError = void 0;
 var _react = require("react");
 var _reactNative = require("react-native");
 var _socket = require("socket.io-client");
@@ -17,7 +17,6 @@ var _deliveryPlatform = require("../utils/deliveryPlatform.js");
 var _runProviderColdBoot = require("../boot/runProviderColdBoot.js");
 var _deviceCredential = require("../utils/deviceCredential.js");
 var _authStore = require("../stores/authStore.js");
-var _shallow = require("zustand/react/shallow");
 var _useLanguageManagement = require("../hooks/useLanguageManagement.js");
 var _useSessionManagement = require("../hooks/useSessionManagement.js");
 var _useAuthOperations = require("./hooks/useAuthOperations.js");
@@ -28,17 +27,36 @@ var _surfaces = require("../navigation/surfaces.js");
 var _reactQuery = require("@tanstack/react-query");
 var _queryClient = require("../hooks/queryClient.js");
 var _useAvatarPicker = require("../hooks/useAvatarPicker.js");
-var _accountStore = require("../stores/accountStore.js");
-var _index = require("../session/index.js");
+var _resetSessionScopedStores = require("../stores/resetSessionScopedStores.js");
+var _useResolvedFileUrls = require("../hooks/useResolvedFileUrls.js");
+var _index = require("../runtime/index.js");
+var _index2 = require("../session/index.js");
 var _oxyContextHelpers = require("./oxyContextHelpers.js");
+var _useFollow = require("../hooks/useFollow.js");
 var _commitSessionFlow = require("./commitSessionFlow.js");
 var _passkeyFlow = require("./passkeyFlow.js");
 var _passkeyClient = require("../../webauthn/passkeyClient");
 var _queryKeys = require("../hooks/queries/queryKeys.js");
 var _useOxyAccountGraph = require("./useOxyAccountGraph.js");
 var _jsxRuntime = require("react/jsx-runtime");
-const OxyContext = /*#__PURE__*/(0, _react.createContext)(null);
-const OxyProvider = ({
+// `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.
+
+const OxyRuntimeContext = /*#__PURE__*/(0, _react.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.
+ */
+const OxyRuntimeProvider = ({
   children,
   oxyServices: providedOxyServices,
   baseURL,
@@ -50,6 +68,7 @@ const OxyProvider = ({
   sessionMode = 'account',
   webAuthMode = 'popup',
   backgroundSession = false,
+  deviceCredentialStorage = 'persistent',
   onAuthStateChange,
   onError
 }) => {
@@ -66,17 +85,24 @@ 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 = (0, _react.useRef)(null);
   if (!authStoreRef.current) {
-    authStoreRef.current = (0, _index.createPlatformAuthStateStore)();
+    authStoreRef.current = (0, _index2.createPlatformAuthStateStore)({
+      sessionMode,
+      storage: deviceCredentialStorage
+    });
   }
   const authStore = authStoreRef.current;
 
@@ -92,38 +118,96 @@ const OxyProvider = ({
   // be downgraded mid-flight into following the device's active account.
   const identityRef = (0, _react.useRef)(null);
   if (sessionMode === 'identity' && !identityRef.current) {
-    identityRef.current = (0, _index.createIdentitySessionBinding)();
+    identityRef.current = (0, _index2.createIdentitySessionBinding)();
   }
   const identity = identityRef.current;
   const isIdentityBound = identity !== null;
+  const logger = (0, _react.useCallback)((message, err) => {
+    if (__DEV__) {
+      _core.logger.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 = (0, _react.useRef)(null);
+  if (!sessionClientPairRef.current) {
+    sessionClientPairRef.current = (0, _index2.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') {
+        (0, _useAuthOperations.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 = (0, _react.useRef)(() => Promise.resolve());
+  const saveSessionIdsRef = (0, _react.useRef)(() => undefined);
+  const subjectChangeRef = (0, _react.useRef)(() => undefined);
+  const reestablishRef = (0, _react.useRef)(() => undefined);
+  const runtimeRef = (0, _react.useRef)(null);
+  if (!runtimeRef.current) {
+    runtimeRef.current = (0, _index.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 = (0, _index.useRuntimeSnapshot)(runtime);
+  const {
+    account: user,
+    sessions,
+    activeSessionId,
     isLoading,
-    error,
-    loginSuccess,
-    loginFailure,
-    logoutStore
-  } = (0, _authStore.useAuthStore)((0, _shallow.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] = (0, _react.useState)(true);
-  const [hasAccessToken, setHasAccessToken] = (0, _react.useState)(() => Boolean(oxyServices.getAccessToken()));
-  const [authResolved, setAuthResolved] = (0, _react.useState)(false);
-  const authResolvedRef = (0, _react.useRef)(false);
-  const userRef = (0, _react.useRef)(user);
-  const isAuthenticatedRef = (0, _react.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] = (0, _react.useState)(false);
   const [accountDialogOpen, setAccountDialogOpen] = (0, _react.useState)(false);
-  const setAuthState = _authStore.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.
+  (0, _react.useEffect)(() => (0, _authStore.bindAuthStoreToRuntime)(runtime), [runtime]);
+  (0, _react.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
@@ -143,13 +227,6 @@ const OxyProvider = ({
     applyToSingleton(oxyServices.getAccessToken());
     return oxyServices.onTokensChanged(applyToSingleton);
   }, [oxyServices]);
-  const logger = (0, _react.useCallback)((message, err) => {
-    if (__DEV__) {
-      _core.logger.warn(message, {
-        component: 'OxyContext'
-      }, err);
-    }
-  }, []);
   const storageKeys = (0, _react.useMemo)(() => (0, _storageHelpers.getStorageKeys)(storageKeyPrefix), [storageKeyPrefix]);
   const clientId = (0, _react.useMemo)(() => {
     const trimmed = clientIdProp?.trim();
@@ -183,6 +260,7 @@ const OxyProvider = ({
       storageReady.resolve(storageInstance);
       if (mounted) {
         setStorage(storageInstance);
+        runtime.setStorageReady(true);
       }
     }).catch(err => {
       if (mounted) {
@@ -197,7 +275,7 @@ const OxyProvider = ({
     return () => {
       mounted = false;
     };
-  }, [logger, onError, storageReady]);
+  }, [logger, onError, runtime, storageReady]);
   const {
     currentLanguage,
     languages: currentLanguages,
@@ -214,85 +292,36 @@ const OxyProvider = ({
   });
   const queryClient = (0, _reactQuery.useQueryClient)();
   const {
-    sessions,
-    activeSessionId,
-    setActiveSessionId,
-    updateSessions,
+    saveSessionIds,
     switchSession,
     clearSessionState,
     saveActiveSessionId
   } = (0, _useSessionManagement.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 = (0, _react.useRef)(switchSession);
-  switchSessionRef.current = switchSession;
-  const clearSessionStateRef = (0, _react.useRef)(clearSessionState);
   clearSessionStateRef.current = clearSessionState;
-  const setActiveSessionIdRef = (0, _react.useRef)(setActiveSessionId);
-  setActiveSessionIdRef.current = setActiveSessionId;
-  const loginSuccessRef = (0, _react.useRef)(loginSuccess);
-  loginSuccessRef.current = loginSuccess;
+  saveSessionIdsRef.current = saveSessionIds;
   const onAuthStateChangeRef = (0, _react.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 = (0, _react.useCallback)(() => {
-    if (authResolvedRef.current) {
-      return;
-    }
-    authResolvedRef.current = true;
-    setTokenReady(true);
-    setAuthResolved(true);
-  }, []);
+    runtime.markAuthResolved();
+  }, [runtime]);
   const markAuthResolvedRef = (0, _react.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 = (0, _react.useRef)(null);
-  if (!sessionClientPairRef.current) {
-    sessionClientPairRef.current = (0, _index.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') {
-        (0, _useAuthOperations.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 = (0, _react.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
@@ -337,78 +366,22 @@ 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 = (0, _react.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 = (0, _index.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 || (0, _index.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((0, _index.deviceStateToClientSessions)(latest, usersById, pinnedAccountId));
-    setActiveSessionId((0, _index.activeSessionIdOf)(latest, pinnedAccountId));
-    const activeUser = (0, _index.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 = (0, _react.useCallback)(() => runtime.reconcileFromClient(), [runtime]);
   const syncFromClientRef = (0, _react.useRef)(syncFromClient);
   syncFromClientRef.current = syncFromClient;
   const syncDeviceCredentialToHost = (0, _react.useCallback)(async () => {
     const cred = await (0, _deviceCredential.loadPersistedDeviceCredential)(authStore);
     sessionClientHost.setDeviceCredential(cred);
   }, [authStore, sessionClientHost]);
-  (0, _react.useEffect)(() => {
-    return sessionClient.subscribe(() => {
-      void syncFromClient();
-    });
-  }, [sessionClient, syncFromClient]);
   const {
     signIn,
     logout,
@@ -417,9 +390,7 @@ const OxyProvider = ({
     oxyServices,
     store: authStore,
     storage,
-    activeSessionId,
-    setActiveSessionId,
-    updateSessions,
+    runtime,
     saveActiveSessionId,
     clearSessionState,
     switchSession,
@@ -427,10 +398,6 @@ const OxyProvider = ({
     syncFromClient,
     onAuthStateChange,
     onError,
-    loginSuccess,
-    loginFailure,
-    logoutStore,
-    setAuthState,
     logger,
     ...(identity ? {
       identityBinding: identity.binding,
@@ -459,7 +426,6 @@ const OxyProvider = ({
     // Explicit FULL wipe: also drop the persisted device credential so a reload
     // finds nothing to restore.
     await authStore.clear();
-    _accountStore.useAccountStore.getState().reset();
     oxyServices.clearCache();
   }, [queryClient, storage, clearSessionState, authStore, logger, oxyServices]);
   const {
@@ -473,7 +439,6 @@ const OxyProvider = ({
     clearSessionState,
     logger
   });
-  const useFollowHook = (0, _oxyContextHelpers.loadUseFollowHook)();
 
   // Token-change side effects: an invalidated bearer (HttpService clears tokens
   // on an unrecoverable 401 and emits `null`) must locally sign out an
@@ -484,16 +449,16 @@ const OxyProvider = ({
   const clearingInvalidTokenRef = (0, _react.useRef)(false);
   (0, _react.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;
         }
@@ -502,19 +467,19 @@ 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
@@ -577,20 +542,25 @@ 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() + _oxyContextHelpers.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() + _oxyContextHelpers.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
@@ -610,11 +580,11 @@ 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 = (0, _react.useRef)(commitSession);
   commitSessionRef.current = commitSession;
 
@@ -637,27 +607,6 @@ 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 = (0, _react.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
@@ -677,13 +626,11 @@ 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 = (0, _react.useRef)(handleWebSession);
   handleWebSessionRef.current = handleWebSession;
-  const commitSwitchedSessionRef = (0, _react.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
@@ -726,12 +673,10 @@ 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: _socket.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`).
@@ -950,7 +895,7 @@ const OxyProvider = ({
     if (identity) {
       await identity.refreshPinnedAccountId();
     }
-  }, [oxyServices, authStore, clientIdProp, authRedirectUri, sessionMode, identity, syncDeviceCredentialToHost, sessionClient]);
+  }, [oxyServices, authStore, clientIdProp, authRedirectUri, sessionMode, identity, syncDeviceCredentialToHost, sessionClient, setTokenReady]);
   (0, _react.useEffect)(() => {
     if (initialized) {
       return;
@@ -1041,7 +986,7 @@ const OxyProvider = ({
   // `switchToAccount`, so leaving it live would be a bypass around the same rule.
   const switchSessionForContext = (0, _react.useCallback)(async sessionId => {
     if (isIdentityBound) {
-      throw new _index.IdentityBoundSessionError('switchSession');
+      throw new _index2.IdentityBoundSessionError('switchSession');
     }
     const targetAccountId = sessionClient.getState()?.accounts.find(account => account.sessionId === sessionId)?.accountId;
     if (!targetAccountId) {
@@ -1049,12 +994,12 @@ const OxyProvider = ({
     }
     await sessionClient.switchAccount(targetAccountId);
     await syncFromClient();
-    const activeUser = _authStore.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
@@ -1090,10 +1035,44 @@ 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 = (0, _react.useCallback)(({
+    previous,
+    next
+  }) => {
+    if (previous === null) {
+      return;
+    }
+    (0, _resetSessionScopedStores.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: [_useResolvedFileUrls.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);
 
@@ -1102,7 +1081,7 @@ const OxyProvider = ({
   // unless the app opted in. Placed AFTER `canUsePrivateApi` because provisioning
   // needs a bearer, and keyed on the signed-in account so a sign-out or an
   // account switch revokes the credential before anything else happens.
-  (0, _index.useBackgroundSessionSync)({
+  (0, _index2.useBackgroundSessionSync)({
     enabled: backgroundSession,
     oxyServices,
     userId: user?.id ?? null,
@@ -1119,7 +1098,7 @@ const OxyProvider = ({
     canUsePrivateApi,
     isPrivateApiPending,
     isAuthResolved: authResolved,
-    isStorageReady: storage !== null,
+    isStorageReady: snapshot.storageReady,
     sessionMode: isIdentityBound ? 'identity' : 'account',
     webAuthMode,
     error,
@@ -1153,7 +1132,7 @@ const OxyProvider = ({
     clientId,
     oxyServices,
     sessionClient,
-    useFollow: useFollowHook,
+    useFollow: _useFollow.useFollow,
     showBottomSheet: showBottomSheetForContext,
     openAvatarPicker,
     accountDialogController,
@@ -1164,85 +1143,57 @@ 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__*/(0, _jsxRuntime.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__*/(0, _jsxRuntime.jsx)(_index.OxyRuntimeHandleProvider, {
+    value: runtime,
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(OxyRuntimeContext.Provider, {
+      value: contextValue,
+      children: children
+    })
   });
 };
-exports.OxyProvider = OxyProvider;
-const OxyContextProvider = exports.OxyContextProvider = OxyProvider;
+exports.OxyRuntimeProvider = OxyRuntimeProvider;
+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.';
+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 _core.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()
-};
+exports.OxyProviderMissingError = OxyProviderMissingError;
 const useOxy = () => {
-  const context = (0, _react.useContext)(OxyContext);
+  const context = (0, _react.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.
+ */
 exports.useOxy = useOxy;
+const useOptionalOxy = () => (0, _react.useContext)(OxyRuntimeContext);
+exports.useOptionalOxy = useOptionalOxy;
 //# sourceMappingURL=OxyContext.js.map