@oxyhq/services 28.0.0 → 30.0.0

package/src/ui/context/hooks/useAuthOperations.ts

@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
 import type { ApiError, AuthStateStore, IdentityBinding, SessionClient, User } from '@oxyhq/core';
-import type { AuthState } from '../../stores/authStore';
 import type { ClientSession, SessionLoginResponse } from '@oxyhq/core';
+import type { OxyRuntime } from '../../runtime';
 import { DeviceManager } from '@oxyhq/core';
 import { fetchSessionsWithFallback } from '../../utils/sessionHelpers';
 import { handleAuthError, isInvalidSessionError } from '../../utils/errorHandlers';
@@ -20,9 +20,12 @@ export interface UseAuthOperationsOptions {
    * warm-restores without a redirect.
    */
   store: AuthStateStore;
-  activeSessionId: string | null;
-  setActiveSessionId: (sessionId: string | null) => void;
-  updateSessions: (sessions: ClientSession[], options?: { merge?: boolean }) => void;
+  /**
+   * The one owner of the session facts. Reads (`activeSessionId`) and writes
+   * (the account, the session mirror, the loading/error gates) both go through
+   * it, so this hook holds no copy of anything to fall out of step.
+   */
+  runtime: OxyRuntime;
   saveActiveSessionId: (sessionId: string) => Promise<void>;
   clearSessionState: () => Promise<void>;
   /** Used only by `performSignIn`'s same-user duplicate-session dedup (legacy session-validate path; unrelated to the SessionClient device-account set). */
@@ -38,10 +41,6 @@ export interface UseAuthOperationsOptions {
   syncFromClient: () => Promise<void>;
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
-  loginSuccess: (user: User) => void;
-  loginFailure: (message: string) => void;
-  logoutStore: () => void;
-  setAuthState: (state: Partial<AuthState>) => void;
   logger?: (message: string, error?: unknown) => void;
   /**
    * Identity-bound session (`sessionMode: 'identity'`). When set, a successful
@@ -91,9 +90,7 @@ export function clearPersistedAuthSafe(
 export const useAuthOperations = ({
   oxyServices,
   store,
-  activeSessionId,
-  setActiveSessionId,
-  updateSessions,
+  runtime,
   saveActiveSessionId,
   clearSessionState,
   switchSession,
@@ -101,10 +98,6 @@ export const useAuthOperations = ({
   syncFromClient,
   onAuthStateChange,
   onError,
-  loginSuccess,
-  loginFailure,
-  logoutStore,
-  setAuthState,
   logger,
   identityBinding,
   refreshPinnedAccountId,
@@ -231,7 +224,7 @@ export const useAuthOperations = ({
           }
         }
         await switchSession(existingSession.sessionId);
-        updateSessions(
+        runtime.mergeSessions(
           allDeviceSessions.filter((session) => session.sessionId !== sessionResponse.sessionId),
           { merge: false },
         );
@@ -239,27 +232,28 @@ export const useAuthOperations = ({
         return fullUser;
       }
 
-      setActiveSessionId(sessionResponse.sessionId);
+      // One transition: the active id, the session mirror and the account all
+      // land together, so nothing is woken holding two of the three.
+      runtime.batch(() => {
+        runtime.setActiveSessionId(sessionResponse.sessionId);
+        runtime.mergeSessions(allDeviceSessions, { merge: true });
+        runtime.setAccount(fullUser);
+      });
       await saveActiveSessionId(sessionResponse.sessionId);
-      updateSessions(allDeviceSessions, { merge: true });
-
-      loginSuccess(fullUser);
       onAuthStateChange?.(fullUser);
 
       return fullUser;
     },
     [
       logger,
-      loginSuccess,
       onAuthStateChange,
       oxyServices,
+      runtime,
       saveActiveSessionId,
       sessionClient,
-      setActiveSessionId,
       store,
       switchSession,
       syncFromClient,
-      updateSessions,
       identityBinding,
       refreshPinnedAccountId,
     ],
@@ -270,7 +264,10 @@ export const useAuthOperations = ({
    */
   const signIn = useCallback(
     async (publicKey: string, deviceName?: string): Promise<User> => {
-      setAuthState({ isLoading: true, error: null });
+      runtime.batch(() => {
+        runtime.setLoading(true);
+        runtime.setError(null);
+      });
 
       try {
         return await performSignIn(publicKey);
@@ -279,16 +276,16 @@ export const useAuthOperations = ({
           defaultMessage: 'Sign in failed',
           code: LOGIN_ERROR_CODE,
           onError,
-          setAuthError: (msg: string) => setAuthState({ error: msg }),
+          setAuthError: (msg: string) => runtime.setError(msg),
           logger,
         });
-        loginFailure(message);
+        runtime.setError(message);
         throw error;
       } finally {
-        setAuthState({ isLoading: false });
+        runtime.setLoading(false);
       }
     },
-    [setAuthState, performSignIn, loginFailure, onError, logger],
+    [runtime, performSignIn, onError, logger],
   );
 
   /**
@@ -296,6 +293,7 @@ export const useAuthOperations = ({
    */
   const logout = useCallback(
     async (targetSessionId?: string): Promise<void> => {
+      const activeSessionId = runtime.getSnapshot().activeSessionId;
       if (!activeSessionId) return;
 
       try {
@@ -342,20 +340,19 @@ export const useAuthOperations = ({
           defaultMessage: 'Logout failed',
           code: LOGOUT_ERROR_CODE,
           onError,
-          setAuthError: (msg: string) => setAuthState({ error: msg }),
+          setAuthError: (msg: string) => runtime.setError(msg),
           logger,
           status: isInvalid ? 401 : undefined,
         });
       }
     },
     [
-      activeSessionId,
       clearSessionState,
       store,
       logger,
       onError,
+      runtime,
       sessionClient,
-      setAuthState,
       syncFromClient,
     ],
   );
@@ -364,9 +361,9 @@ export const useAuthOperations = ({
    * Logout from all sessions
    */
   const logoutAll = useCallback(async (): Promise<void> => {
-    if (!activeSessionId) {
+    if (!runtime.getSnapshot().activeSessionId) {
       const error = new Error('No active session found');
-      setAuthState({ error: error.message });
+      runtime.setError(error.message);
       onError?.({ message: error.message, code: LOGOUT_ALL_ERROR_CODE, status: 404 });
       throw error;
     }
@@ -387,12 +384,12 @@ export const useAuthOperations = ({
         defaultMessage: 'Logout all failed',
         code: LOGOUT_ALL_ERROR_CODE,
         onError,
-        setAuthError: (msg: string) => setAuthState({ error: msg }),
+        setAuthError: (msg: string) => runtime.setError(msg),
         logger,
       });
       throw error instanceof Error ? error : new Error('Logout all failed');
     }
-  }, [activeSessionId, clearSessionState, store, logger, onError, sessionClient, setAuthState]);
+  }, [clearSessionState, store, logger, onError, runtime, sessionClient]);
 
   return {
     signIn,

package/src/ui/context/oxyContextHelpers.ts

@@ -1,6 +1,3 @@
-import type { UseFollowHook } from '../hooks/useFollow.types';
-import { logger as loggerUtil } from '@oxyhq/core';
-
 /** Local display hint when a session lacks explicit `expiresAt` (7 days). */
 export const DEFAULT_SESSION_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -29,30 +26,3 @@ export function getHttpStatus(error: unknown): number | undefined {
 export function isUnauthorizedStatus(error: unknown): boolean {
   return getHttpStatus(error) === 401;
 }
-
-let cachedUseFollowHook: UseFollowHook | null = null;
-
-export const loadUseFollowHook = (): UseFollowHook => {
-  if (cachedUseFollowHook) {
-    return cachedUseFollowHook;
-  }
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const { useFollow } = require('../hooks/useFollow');
-    cachedUseFollowHook = useFollow as UseFollowHook;
-    return cachedUseFollowHook;
-  } catch (error) {
-    if (__DEV__) {
-      loggerUtil.warn(
-        'useFollow hook is not available. Please import useFollow from @oxyhq/services directly.',
-        { component: 'OxyContext', method: 'loadUseFollowHook' },
-        error,
-      );
-    }
-    const fallback: UseFollowHook = () => {
-      throw new Error('useFollow hook is only available in the UI bundle. Import it from @oxyhq/services.');
-    };
-    cachedUseFollowHook = fallback;
-    return cachedUseFollowHook;
-  }
-};

package/src/ui/context/oxyContextTypes.ts

@@ -151,7 +151,7 @@ export interface OxyContextState {
   createAccount: (data: CreateAccountInput) => Promise<AccountNode>;
 }
 
-export interface OxyContextProviderProps {
+export interface OxyRuntimeProviderProps {
   children: ReactNode;
   oxyServices?: OxyServices;
   baseURL?: string;
@@ -198,6 +198,14 @@ export interface OxyContextProviderProps {
    * @default false
    */
   backgroundSession?: boolean;
+  /**
+   * Whether this origin/app persists the durable device credential at all. See
+   * `OxyProviderProps.deviceCredentialStorage` for the full rule and the one
+   * caller of `'ephemeral'`.
+   *
+   * @default 'persistent'
+   */
+  deviceCredentialStorage?: 'persistent' | 'ephemeral';
   onAuthStateChange?: (user: User | null) => void;
   onError?: (error: ApiError) => void;
 }

package/src/ui/context/useOxyAccountGraph.ts

@@ -1,11 +1,7 @@
 import { useCallback, useEffect, useState, type RefObject } from 'react';
-import type { QueryClient } from '@tanstack/react-query';
 import type { OxyServices, AccountNode, CreateAccountInput, AccountDialogController, SessionClient } from '@oxyhq/core';
 import { logger as loggerUtil } from '@oxyhq/core';
-import { useAuthStore } from '../stores/authStore';
 import { isUnauthorizedStatus } from './oxyContextHelpers';
-import { resetSessionScopedStores } from '../stores/resetSessionScopedStores';
-import { ASSET_DOWNLOAD_URLS_QUERY_KEY } from '../hooks/useResolvedFileUrls';
 import { IdentityBoundSessionError } from '../session';
 import type { CommitInput } from './oxyContextTypes';
 
@@ -23,7 +19,6 @@ interface UseOxyAccountGraphParams {
   sessionClient: SessionClient;
   syncFromClient: () => Promise<void>;
   commitSession: (input: CommitInput, options: { activate: boolean }) => Promise<void>;
-  queryClient: QueryClient;
   accountDialogControllerRef: RefObject<AccountDialogController | null>;
   clearSessionStateRef: RefObject<() => Promise<void>>;
 }
@@ -37,7 +32,6 @@ export function useOxyAccountGraph({
   sessionClient,
   syncFromClient,
   commitSession,
-  queryClient,
   accountDialogControllerRef,
   clearSessionStateRef,
 }: UseOxyAccountGraphParams) {
@@ -70,16 +64,6 @@ export function useOxyAccountGraph({
     }
   }, [identityBound, isAuthenticated, initialized, tokenReady, refreshAccounts, accountDialogControllerRef]);
 
-  const runPostAccountSwitchSideEffects = useCallback(async (): Promise<void> => {
-    resetSessionScopedStores();
-    // 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] });
-    await refreshAccounts();
-    queryClient.invalidateQueries();
-  }, [refreshAccounts, queryClient]);
-
   const switchToAccount = useCallback(
     async (accountId: string): Promise<void> => {
       if (identityBound) {
@@ -92,7 +76,6 @@ export function useOxyAccountGraph({
       if (deviceState?.accounts.some((account) => account.accountId === accountId)) {
         await sessionClient.switchAccount(accountId);
         await syncFromClient();
-        await runPostAccountSwitchSideEffects();
         return;
       }
 
@@ -114,9 +97,12 @@ export function useOxyAccountGraph({
         // `session_state` socket.
         { activate: true },
       );
-      await runPostAccountSwitchSideEffects();
     },
-    [identityBound, oxyServices, sessionClient, syncFromClient, commitSession, runPostAccountSwitchSideEffects],
+    // The account-scoped cache reset that used to trail both branches here now
+    // runs inside the runtime's subject transition, BEFORE any subscriber is
+    // woken — so a socket-pushed switch (which never reached this function at
+    // all) gets it too.
+    [identityBound, oxyServices, sessionClient, syncFromClient, commitSession],
   );
 
   const createAccount = useCallback(

package/src/ui/hooks/accountDialogSnapshot.ts

@@ -0,0 +1,37 @@
+import type { AccountDialogSnapshot } from '@oxyhq/core';
+
+/**
+ * The snapshot `useSyncExternalStore` reads before a controller exists.
+ *
+ * `useSyncExternalStore` calls `getSnapshot` several times per commit and
+ * compares by identity, so the no-controller answer has to be one constant
+ * reference — a fresh object literal loops.
+ *
+ * It is ONE constant because there were three, byte-identical, in the hook and
+ * both dialog surfaces. Adding a field to `AccountDialogSnapshot` broke all
+ * three at once and would have gone on doing so; a shared constant makes the
+ * compiler point at one place.
+ */
+export const EMPTY_ACCOUNT_DIALOG_SNAPSHOT: AccountDialogSnapshot = {
+  view: 'accounts',
+  directory: null,
+  activeContext: null,
+  activatingContextId: null,
+  removingContextId: null,
+  removingPrincipalId: null,
+  loading: false,
+  error: null,
+  signIn: {
+    phase: 'idle',
+    authorizeCode: null,
+    qrPayload: null,
+    expiresAt: null,
+    error: null,
+    route: null,
+    routeFailed: false,
+    pushSentAt: null,
+    openedAt: null,
+    progress: 'idle',
+  },
+  commonsAvailability: 'unknown',
+};

package/src/ui/hooks/mutations/useAccountMutations.ts

@@ -18,9 +18,7 @@ import {
 import { mutationKeys } from './mutationKeys';
 import { useOxy } from '../../context/OxyContext';
 import { toast } from '@oxyhq/bloom/toast';
-import { refreshAvatarInStore } from '../../utils/avatarUtils';
 import { useAuthStore } from '../../stores/authStore';
-import { useAccountStore } from '../../stores/accountStore';
 import {
   clearedFieldsFromProfileUpdate,
   upsertCachedUser,
@@ -114,18 +112,6 @@ export const useUpdateProfile = () => {
         cleared: cleared.length > 0 ? cleared : undefined,
       });
 
-      // Avatar add/remove: keep the account switcher in sync with profile writes
-      if (typeof updates.avatar === 'string' && activeSessionId) {
-        if (updates.avatar && oxyServices) {
-          refreshAvatarInStore(activeSessionId, updates.avatar, oxyServices);
-        } else {
-          useAccountStore.getState().updateAccount(activeSessionId, {
-            avatar: undefined,
-            avatarUrl: undefined,
-          });
-        }
-      }
-
       // Invalidate all related queries so every consumer (the account dialog,
       // session lists, managed accounts, etc.) refetches the fresh profile.
       // This is critical right after `username` is set the first time, when
@@ -209,11 +195,6 @@ export const useUploadAvatar = () => {
       // Update authStore so frontend components see the changes immediately
       useAuthStore.getState().setUser(data);
       
-      // Refresh accountStore with cache-busted URL if avatar was updated
-      if (data?.avatar && activeSessionId && oxyServices) {
-        refreshAvatarInStore(activeSessionId, data.avatar, oxyServices);
-      }
-
       // Invalidate all related queries to refresh everywhere, including the
       // sessions cache so other-account avatars update too.
       invalidateUserQueries(queryClient);

package/src/ui/hooks/queries/__tests__/userCache.test.ts

@@ -17,7 +17,8 @@ import { upsertCachedUser, upsertCachedUsers } from '../userCache';
 import { patchCachedUserRelationship } from '../userCacheRelationship';
 import type { CacheableUser } from '../userCache';
 import { queryKeys } from '../queryKeys';
-import { useAuthStore } from '../../../stores/authStore';
+import { bindAuthStoreToRuntime, useAuthStore } from '../../../stores/authStore';
+import { createTestRuntime } from '../../../../../__tests__/helpers/runtimeHarness';
 
 function makeClient(): QueryClient {
   return new QueryClient({
@@ -35,11 +36,21 @@ function readByUsername(qc: QueryClient, username: string, viewerId: string): Ca
   return qc.getQueryData<CacheableUser>(queryKeys.users.byUsername(username, viewerId));
 }
 
+// `useAuthStore` projects the runtime now, so the viewer these cases read has
+// to live somewhere: bind a runtime per test and let the writes go through it.
+let unbindAuthStore: (() => void) | null = null;
+
 beforeEach(() => {
+  unbindAuthStore = bindAuthStoreToRuntime(createTestRuntime());
   // Default to anonymous viewer unless a test sets one.
   useAuthStore.setState({ user: null });
 });
 
+afterEach(() => {
+  unbindAuthStore?.();
+  unbindAuthStore = null;
+});
+
 describe('upsertCachedUser — cold slot', () => {
   it('seeds the full object and marks it STALE (updatedAt: 0) under both keys', () => {
     const qc = makeClient();

package/src/ui/hooks/useDeviceSwitcher.ts

@@ -0,0 +1,110 @@
+import { useCallback, useMemo, useSyncExternalStore } from 'react';
+import {
+    buildSwitcherRows,
+    projectDevicePrincipals,
+    type DeviceContext,
+    type SwitcherPrincipalRow,
+} from '@oxyhq/core';
+import { useOxy } from '../context/OxyContext';
+import { useI18n } from './useI18n';
+import { EMPTY_ACCOUNT_DIALOG_SNAPSHOT } from './accountDialogSnapshot';
+
+export interface UseDeviceSwitcherResult {
+    /**
+     * Everyone signed in on this device, each with the accounts they may act as,
+     * with names, handles and avatar URLs already resolved.
+     *
+     * Grouped by PERSON, which is the whole point: the same organization
+     * reachable through two people is two rows under two humans. The flat list
+     * this replaced was keyed by account id and could show only one of them.
+     */
+    principals: SwitcherPrincipalRow[];
+    /** The active `principal acting as account` pair, or `null`. */
+    activeContext: DeviceContext | null;
+    /** True until the first directory read settles with nothing to show. */
+    isLoading: boolean;
+    /** The `contextId` of an activation in flight, or `null`. */
+    activatingContextId: string | null;
+    /** The `contextId` of a context removal in flight, or `null`. */
+    removingContextId: string | null;
+    /** The `principalId` of a principal removal in flight, or `null`. */
+    removingPrincipalId: string | null;
+    /**
+     * Make one pair active. Resolves `false` when it was refused — the reason is
+     * on the dialog controller's `error`, and the row is simply not offered
+     * again after the refresh that follows.
+     */
+    activateContext: (contextId: string) => Promise<boolean>;
+    /** Drop ONE `principal → account` pair, leaving anyone else's route intact. */
+    signOutContext: (contextId: string) => Promise<boolean>;
+    /** Drop ONE PERSON and every context they reach, and nobody else's. */
+    signOutPrincipal: (principalId: string) => Promise<boolean>;
+}
+
+/**
+ * The device switcher, straight from `GET /session/device/directory` (ADR 0002).
+ *
+ * A thin binding over the shared `AccountDialogController` in `@oxyhq/core` —
+ * the SAME headless source `OxyAccountDialogScreen` renders — so the SDK's own
+ * dialog and the `auth.oxy.so` chooser show one list, built once, on the server.
+ *
+ * It used to hand back a flat `SwitchableAccount[]` assembled here from
+ * `listAccounts()` + `getUsersByIds()` unioned with the device's session set.
+ * That union was not merely redundant: the client holds ONE caller's account
+ * graph, so on a device holding two people it presented one person's answer as
+ * the device's, and switchability — an authorization question — was decided
+ * client-side. Both are the server's answers now, and selecting a row activates
+ * a `contextId`, never an `accountId`.
+ */
+export function useDeviceSwitcher(): UseDeviceSwitcherResult {
+    const { accountDialogController: controller, oxyServices } = useOxy();
+    const { locale } = useI18n();
+
+    const subscribe = useCallback(
+        (listener: () => void) => (controller ? controller.subscribe(listener) : () => undefined),
+        [controller],
+    );
+    const getSnapshot = useCallback(
+        () => (controller ? controller.getSnapshot() : EMPTY_ACCOUNT_DIALOG_SNAPSHOT),
+        [controller],
+    );
+    const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+    // `directory` is a stable reference between reads (`SessionClient` holds the
+    // one it applied), so this recomputes only when the device actually moved.
+    const principals = useMemo(
+        () =>
+            buildSwitcherRows(
+                projectDevicePrincipals(snapshot.directory),
+                snapshot.activeContext?.contextId ?? null,
+                (avatar) => (avatar ? oxyServices.getFileDownloadUrl(avatar, 'thumb') : undefined),
+                locale,
+            ),
+        [snapshot.directory, snapshot.activeContext, oxyServices, locale],
+    );
+
+    const activateContext = useCallback(
+        async (contextId: string) => (controller ? controller.activateContext(contextId) : false),
+        [controller],
+    );
+    const signOutContext = useCallback(
+        async (contextId: string) => (controller ? controller.signOutContext(contextId) : false),
+        [controller],
+    );
+    const signOutPrincipal = useCallback(
+        async (principalId: string) => (controller ? controller.signOutPrincipal(principalId) : false),
+        [controller],
+    );
+
+    return {
+        principals,
+        activeContext: snapshot.activeContext,
+        isLoading: snapshot.loading,
+        activatingContextId: snapshot.activatingContextId,
+        removingContextId: snapshot.removingContextId,
+        removingPrincipalId: snapshot.removingPrincipalId,
+        activateContext,
+        signOutContext,
+        signOutPrincipal,
+    };
+}

package/src/ui/hooks/useI18n.ts

@@ -1,12 +1,32 @@
 import { useMemo } from 'react';
-import { useOxy } from '../context/OxyContext';
+import { useOptionalOxy } from '../context/OxyContext';
 import { translate } from '@oxyhq/core';
 
+/**
+ * The locale `@oxyhq/core`'s translator falls back to. Mirrors its own
+ * `FALLBACK`, so a surface rendered without a provider reads the same strings
+ * an unrecognised locale would.
+ */
+const FALLBACK_LOCALE = 'en-US';
+
+/**
+ * Display copy for SDK surfaces.
+ *
+ * This is the ONE hook that reads the runtime optionally. The locale is display
+ * metadata, not session state — ADR 0004 lists it among the things that come off
+ * the central value entirely — and purely presentational surfaces
+ * (`OxyConsentScreen`, `OxySignInRequestSurface`) are rendered outside a
+ * provider on purpose: `packages/auth`'s production-bundle probe builds the real
+ * Vite bundle and renders the surface standalone to prove every element beneath
+ * it links. Throwing there would report a linkage failure that is not one.
+ *
+ * Anything that reads or mutates session state uses `useOxy()`, which throws.
+ */
 export function useI18n() {
-  const { currentLanguage } = useOxy();
+  const oxy = useOptionalOxy();
+  const currentLanguage = oxy?.currentLanguage ?? FALLBACK_LOCALE;
   const t = useMemo(() => {
     return (key: string, vars?: Record<string, string | number>) => translate(currentLanguage, key, vars);
   }, [currentLanguage]);
   return { t, locale: currentLanguage };
 }
-