@oxy.so/services 12.12.0 → 12.14.0

package/src/ui/boot/runProviderColdBoot.ts

@@ -121,11 +121,223 @@ export interface RunProviderColdBootOptions {
   ) => Promise<void>;
   markAuthResolved: () => void;
   setTokenReady: (ready: boolean) => void;
+  /**
+   * Show the session saved on this device before any network: the account from
+   * its cached profile, auth resolved. Resolves `true` when it did, `false` when
+   * the device holds nothing a first paint can use (then the boot runs as a
+   * first boot). Never consulted in `sessionMode: 'identity'` or with an OAuth
+   * return on the URL.
+   */
+  paintCachedSession?: () => Promise<boolean>;
+  /**
+   * The server ended the painted session: the registry now classifies the app
+   * as OAuth-only, or the mint answered this holder `invalid_device_secret` /
+   * `no_active_session` and no recovery lane restored one. Sign out now.
+   */
+  onCachedSessionRejected?: () => Promise<void>;
+  /**
+   * The painted session could not be checked yet (offline, the registry or the
+   * mint unreachable). It stays on screen; call `retry` later to ask again.
+   */
+  onCachedSessionUnconfirmed?: (retry: () => Promise<void>) => void;
+}
+
+type ClassificationLane = 'device' | 'oauth';
+
+/** Starts the provider's fresh classification; a rejection is observed, not swallowed. */
+function startClassification(opts: RunProviderColdBootOptions): Promise<ClassificationLane> {
+  const classification = (async () =>
+    opts.resolveSessionLane?.() ??
+    resolveApplicationSessionLane(opts.oxyServices, opts.clientId))();
+  // Observed so a rejection that lands before it is awaited is not reported as
+  // unhandled; every caller still awaits it and sees the rejection.
+  classification.catch(() => undefined);
+  return classification;
+}
+
+/** What the device lanes made of this holder: a session, a verdict against it, or no answer. */
+type DeviceRestoreOutcome = 'session' | 'rejected' | 'unreachable';
+
+/**
+ * The device lanes of the boot (`runSessionColdBoot`), for a first boot or for
+ * the background check of a painted one.
+ *
+ * A first boot (`painted: false`) is on the critical path: its committed
+ * session resolves auth, bounded by {@link SESSION_HANDOFF_DEADLINE_MS}. A
+ * painted boot already resolved auth from the cache, so nothing waits on the
+ * handoff and the pure-local warm token is skipped: the check needs the mint's
+ * verdict, which a still-valid token cannot give.
+ */
+async function restoreDeviceSession(
+  opts: RunProviderColdBootOptions,
+  painted: boolean,
+): Promise<DeviceRestoreOutcome> {
+  const {
+    oxyServices,
+    authStore,
+    sessionMode = 'account',
+    identity,
+    sessionClient,
+    syncDeviceCredentialToHost,
+    commitSession,
+    markAuthResolved,
+  } = opts;
+
+  await opts.beforeDeviceBoot?.();
+
+  // Best-effort connectivity probe up front: an EXPLICIT offline verdict skips
+  // the two doomed network steps so routing settles immediately instead of
+  // burning the overall deadline on a mint that cannot succeed. Any ambiguity
+  // resolves to "online" — the network steps still run.
+  const offline = await detectOfflineHint();
+
+  let outcome: DeviceRestoreOutcome = 'unreachable';
+  let holderRejected = false;
+  await runSessionColdBoot({
+    oxy: oxyServices,
+    store: authStore,
+    platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
+    sessionMode,
+    identity,
+    // The device-wide shared credential slot, enabling the `shared-device-adopt`
+    // lane: a newly installed official app joins this device's existing session
+    // instead of falling back to signing a challenge with the Commons identity
+    // key. `null` on web, where each origin is its own device by design; the
+    // core lane is also skipped outright in `sessionMode: 'identity'`.
+    sharedDeviceCredential: createPlatformSharedDeviceCredentialStore() ?? undefined,
+    overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE_MS,
+    isOffline: () => offline,
+    requireServerVerdict: painted,
+    onHolderRejected: () => {
+      holderRejected = true;
+    },
+    onStepDeadline: (stepId) => {
+      loggerUtil.warn(
+        `Cold-boot step "${stepId}" exceeded the ${COLD_BOOT_OVERALL_DEADLINE_MS}ms overall deadline — abandoned; routing proceeds signed-out`,
+        { component: 'runProviderColdBoot', method: 'onStepDeadline' },
+      );
+    },
+    onSession: async (session) => {
+      outcome = 'session';
+      // Mint already persisted `{deviceId, deviceSecret}` to the store; sync the
+      // in-memory SessionClient host so sockets + tab-focus re-mint can use it.
+      await syncDeviceCredentialToHost();
+      const handoff = commitSession(
+        {
+          sessionId: session.sessionId,
+          accessToken: session.accessToken,
+          userId: session.userId,
+          deviceState: session.state,
+        },
+        { activate: false },
+      );
+      if (painted) {
+        // The account is already on screen; the commit refreshes its profile.
+        await handoff;
+        return;
+      }
+      let handoffDeadlineId: ReturnType<typeof setTimeout> | undefined;
+      await Promise.race([
+        handoff,
+        new Promise<void>((resolve) => {
+          handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE_MS);
+        }),
+      ]).finally(() => {
+        if (handoffDeadlineId !== undefined) {
+          clearTimeout(handoffDeadlineId);
+        }
+      });
+      markAuthResolved();
+    },
+    onSignedOut: async () => {
+      outcome = holderRejected ? 'rejected' : 'unreachable';
+      await syncDeviceCredentialToHost();
+      // A painted session is the caller's to end or keep (see verifyCachedSession).
+      if (painted) return;
+      const cred = await loadPersistedDeviceCredential(authStore);
+      if (cred) {
+        try {
+          await sessionClient.start();
+        } catch (socketError) {
+          if (__DEV__) {
+            loggerUtil.debug(
+              'Device socket start failed (non-fatal)',
+              { component: 'runProviderColdBoot' },
+              socketError,
+            );
+          }
+        }
+      }
+      markAuthResolved();
+    },
+    onStepError: (id, error) => {
+      if (__DEV__) {
+        loggerUtil.debug(
+          `Cold-boot step "${id}" errored (non-fatal, falling through)`,
+          { component: 'runProviderColdBoot' },
+          error,
+        );
+      }
+    },
+  });
+  await opts.afterDeviceBoot?.();
+  return outcome;
+}
+
+/**
+ * The background check of a painted session: the registry's classification and
+ * a mint with this holder's own credential (whose commit refreshes the profile).
+ * Each is asked until the server answers it. A verdict against the session
+ * signs out at that moment; no answer keeps the cached session on screen and
+ * hands the caller a retry.
+ */
+async function verifyCachedSession(
+  opts: RunProviderColdBootOptions,
+  verified: { lane: boolean; session: boolean },
+  classification: Promise<ClassificationLane>,
+): Promise<void> {
+  if (!verified.lane) {
+    let lane: ClassificationLane | null = null;
+    try {
+      lane = await classification;
+    } catch {
+      // The registry could not be asked (offline, timeout, 5xx). That is no
+      // verdict on this app: the cached `device` classification stands until it
+      // answers.
+    }
+    if (lane === 'oauth') {
+      await opts.onCachedSessionRejected?.();
+      return;
+    }
+    verified.lane = lane === 'device';
+  }
+  if (!verified.session) {
+    const outcome = await restoreDeviceSession(opts, true);
+    if (outcome === 'rejected') {
+      await opts.onCachedSessionRejected?.();
+      return;
+    }
+    verified.session = outcome === 'session';
+  }
+  if (!verified.lane || !verified.session) {
+    opts.onCachedSessionUnconfirmed?.(() =>
+      verifyCachedSession(
+        opts,
+        verified,
+        verified.lane ? Promise.resolve('device') : startClassification(opts),
+      ),
+    );
+  }
 }
 
 /**
  * Device-first cold boot for `@oxy.so/services` providers.
  *
+ * A returning session saved on this device (account mode, the app last
+ * classified `device`, its profile cached) paints first, with no network, and
+ * is then checked in the background — see `paintCachedSession`. Otherwise, a
+ * first boot:
+ *
  * Ordered pipeline:
  * 1. Complete an OAuth authorization-code return already on the URL (web)
  * 2. `runSessionColdBoot` — device-secret mint (+ the native Commons-proof lane,
@@ -148,9 +360,6 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
     clientId,
     authRedirectUri,
     sessionMode = 'account',
-    identity,
-    sessionClient,
-    syncDeviceCredentialToHost,
     commitSession,
     markAuthResolved,
     setTokenReady,
@@ -162,14 +371,21 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
 
   try {
     // Classification precedes every USE of a local secret, the shared credential
-    // and the identity key. Unavailable registry metadata fails closed, including
-    // offline boot. It starts now, before anything else, so its round trip
-    // overlaps the local work below.
-    const classification = (async () =>
-      opts.resolveSessionLane?.() ?? resolveApplicationSessionLane(oxyServices, clientId))();
-    // Observed so a rejection that lands before it is awaited is not reported as
-    // unhandled; every path below still awaits it and sees the rejection.
-    classification.catch(() => undefined);
+    // and the identity key. Unavailable registry metadata fails closed on a first
+    // boot, including offline. It starts now, before anything else, so its round
+    // trip overlaps the local work below.
+    const classification = startClassification(opts);
+
+    // A returning session saved on this device paints at once from the cache:
+    // the account, its cached content, auth resolved, no network on the way.
+    // The classification and the session are then checked in the background,
+    // and a verdict against either signs out at that moment. Identity-bound
+    // clients and OAuth returns keep the path below.
+    const freshLaunch = !identityBound && !hasOAuthReturnOnUrl();
+    if (freshLaunch && (await opts.paintCachedSession?.())) {
+      await verifyCachedSession(opts, { lane: false, session: false }, classification);
+      return;
+    }
 
     // The verdict decides HOW a session is restored, never WHETHER there is one.
     // A web origin with nothing to restore and no OAuth return on the URL ends
@@ -177,7 +393,7 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
     // for an answer that cannot change the outcome. The classification still
     // completes below and still gates every later sign-in
     // (`ensureDeviceSessionLane` shares this same in-flight lookup).
-    if (!identityBound && isWebBrowser() && !hasOAuthReturnOnUrl()) {
+    if (freshLaunch && isWebBrowser()) {
       if (!(await hasRestorableState(authStore))) {
         markAuthResolved();
         const lane = await classification;
@@ -215,89 +431,7 @@ export async function runProviderColdBoot(opts: RunProviderColdBootOptions): Pro
       return;
     }
 
-    await opts.beforeDeviceBoot?.();
-
-    // Best-effort connectivity probe up front: an EXPLICIT offline verdict skips
-    // the two doomed network steps so routing settles immediately instead of
-    // burning the overall deadline on a mint that cannot succeed. Any ambiguity
-    // resolves to "online" — the network steps still run.
-    const offline = await detectOfflineHint();
-
-    await runSessionColdBoot({
-      oxy: oxyServices,
-      store: authStore,
-      platform: { isWeb: isWebBrowser(), isNative: !isWebBrowser() },
-      sessionMode,
-      identity,
-      // The device-wide shared credential slot, enabling the `shared-device-adopt`
-      // lane: a newly installed official app joins this device's existing session
-      // instead of falling back to signing a challenge with the Commons identity
-      // key. `null` on web, where each origin is its own device by design; the
-      // core lane is also skipped outright in `sessionMode: 'identity'`.
-      sharedDeviceCredential: createPlatformSharedDeviceCredentialStore() ?? undefined,
-      overallDeadlineMs: COLD_BOOT_OVERALL_DEADLINE_MS,
-      isOffline: () => offline,
-      onStepDeadline: (stepId) => {
-        loggerUtil.warn(
-          `Cold-boot step "${stepId}" exceeded the ${COLD_BOOT_OVERALL_DEADLINE_MS}ms overall deadline — abandoned; routing proceeds signed-out`,
-          { component: 'runProviderColdBoot', method: 'onStepDeadline' },
-        );
-      },
-      onSession: async (session) => {
-        // Mint already persisted `{deviceId, deviceSecret}` to the store; sync the
-        // in-memory SessionClient host so sockets + tab-focus re-mint can use it.
-        await syncDeviceCredentialToHost();
-        const handoff = commitSession(
-          {
-            sessionId: session.sessionId,
-            accessToken: session.accessToken,
-            userId: session.userId,
-            deviceState: session.state,
-          },
-          { activate: false },
-        );
-        let handoffDeadlineId: ReturnType<typeof setTimeout> | undefined;
-        await Promise.race([
-          handoff,
-          new Promise<void>((resolve) => {
-            handoffDeadlineId = setTimeout(resolve, SESSION_HANDOFF_DEADLINE_MS);
-          }),
-        ]).finally(() => {
-          if (handoffDeadlineId !== undefined) {
-            clearTimeout(handoffDeadlineId);
-          }
-        });
-        markAuthResolved();
-      },
-      onSignedOut: async () => {
-        await syncDeviceCredentialToHost();
-        const cred = await loadPersistedDeviceCredential(authStore);
-        if (cred) {
-          try {
-            await sessionClient.start();
-          } catch (socketError) {
-            if (__DEV__) {
-              loggerUtil.debug(
-                'Device socket start failed (non-fatal)',
-                { component: 'runProviderColdBoot' },
-                socketError,
-              );
-            }
-          }
-        }
-        markAuthResolved();
-      },
-      onStepError: (id, error) => {
-        if (__DEV__) {
-          loggerUtil.debug(
-            `Cold-boot step "${id}" errored (non-fatal, falling through)`,
-            { component: 'runProviderColdBoot' },
-            error,
-          );
-        }
-      },
-    });
-    await opts.afterDeviceBoot?.();
+    await restoreDeviceSession(opts, false);
   } catch (error) {
     if (__DEV__) {
       loggerUtil.error(

package/src/ui/components/OxyProvider.tsx

@@ -24,6 +24,7 @@ import { LanguageBridge } from './LanguageBridge';
 import { BloomLocaleBridge } from './BloomLocaleBridge';
 import { useOxy } from '../context/oxyRuntimeContext';
 import { useCurrentUser } from '../hooks/queries/useAccountQueries';
+import { SupervisionStateObserver } from '../hooks/queries/useSupervision';
 
 /** Hydrate owner preferences after the bearer is ready, including on cold boot. */
 function AccountProfileObserver() {
@@ -283,6 +284,7 @@ const OxyProvider: FC<OxyProviderProps> = ({
         onAuthStateChange={onAuthStateChange as OxyRuntimeProviderProps['onAuthStateChange']}
       >
         <AccountProfileObserver />
+        <SupervisionStateObserver />
         {productAnalytics ? <ProductAnalyticsObserver analytics={productAnalytics} /> : null}
         {language ? <LanguageBridge {...language} /> : null}
         <BloomLocaleBridge>

package/src/ui/context/OxyContext.tsx

@@ -59,7 +59,8 @@ import {
   hasPersistedSessionCredential,
   loadPersistedDeviceCredential,
 } from '../utils/deviceCredential';
-import { createTokenLossRecovery } from '../session/tokenLossRecovery';
+import { createTokenLossRecovery, TOKEN_RECOVERY_BACKOFF_MS } from '../session/tokenLossRecovery';
+import { createCachedBootStore, type CachedBootStore } from '../session/cachedBoot';
 import { bindAuthStoreToRuntime } from '../stores/authStore';
 import { useLanguageManagement } from '../hooks/useLanguageManagement';
 import { useSessionManagement } from '../hooks/useSessionManagement';
@@ -222,8 +223,19 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     clientId: string | undefined;
     services: OxyServices;
     lane: 'device' | 'oauth' | null;
+    /**
+     * `lane` is this device's cached verdict, standing in until the registry
+     * answers (a painted cold boot). A fresh lookup keeps it meanwhile.
+     */
+    provisional: boolean;
     pending: Promise<'device' | 'oauth'> | null;
-  }>({ clientId: clientIdProp, services: oxyServices, lane: null, pending: null });
+  }>({
+    clientId: clientIdProp,
+    services: oxyServices,
+    lane: null,
+    provisional: false,
+    pending: null,
+  });
   if (
     registeredLaneRef.current.clientId !== clientIdProp ||
     registeredLaneRef.current.services !== oxyServices
@@ -232,6 +244,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       clientId: clientIdProp,
       services: oxyServices,
       lane: null,
+      provisional: false,
       pending: null,
     };
   }
@@ -372,6 +385,15 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
   }
   const storageReady = storageReadyRef.current;
 
+  // What a returning session's first paint needs (the app's classification and
+  // the account's profile), kept in the same storage as the account query cache.
+  const cachedBoot = useMemo(
+    () => (storage ? createCachedBootStore(storage, storageKeyPrefix) : null),
+    [storage, storageKeyPrefix],
+  );
+  const cachedBootRef = useRef<CachedBootStore | null>(cachedBoot);
+  cachedBootRef.current = cachedBoot;
+
   useEffect(() => {
     // `null` means the public provider owns initialization and has not resolved
     // it yet. `undefined` means this internal provider was mounted directly and
@@ -535,11 +557,17 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     if (selected.clientId !== clientIdProp || selected.services !== oxyServices)
       throw new Error('Provider classification was superseded');
     if (selected.pending) return selected.pending;
-    selected.lane = null;
+    if (!selected.provisional) selected.lane = null;
     const pending = (async () => {
       const lane = await resolveApplicationSessionLane(oxyServices, clientIdProp);
       if (registeredLaneRef.current !== selected)
         throw new Error('Provider classification was superseded');
+      if (clientIdProp) void cachedBootRef.current?.saveLane(clientIdProp, lane);
+      if (selected.provisional) {
+        // The registry has answered: its verdict replaces the cached one now.
+        selected.provisional = false;
+        selected.lane = lane;
+      }
       if (lane === 'oauth' && !hasIsolatedOAuthSession(runtime)) {
         sessionClient.resetLocalState();
         sessionClientHost.setDeviceCredential(null);
@@ -1284,6 +1312,115 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     if (!accountDialogOpen) clearSignInFlows(accountDialogControllerRef.current);
   }, [accountDialogOpen]);
 
+  // ── Cached first paint ───────────────────────────────────────────────────
+  // Keep the profile the runtime holds for the signed-in account, so the next
+  // cold boot can paint it before the network answers. Only for a device-lane
+  // account session: an identity-bound client and an isolated OAuth session
+  // always boot through the network. A sign-out deletes it.
+  const cachedAccountJsonRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!cachedBoot || identity) return;
+    if (user === null) {
+      if (cachedAccountJsonRef.current !== null) {
+        cachedAccountJsonRef.current = null;
+        void cachedBoot.clearAccount();
+      }
+      return;
+    }
+    if (registeredLaneRef.current.lane !== 'device' || hasIsolatedOAuthSession(runtime)) return;
+    const json = JSON.stringify(user);
+    if (json === cachedAccountJsonRef.current) return;
+    cachedAccountJsonRef.current = json;
+    void cachedBoot.saveAccount(user);
+  }, [cachedBoot, identity, user, runtime]);
+
+  // Paint the session saved on this device: the bearer it left (when still
+  // valid), the session mirror, the account from its cached profile, auth
+  // resolved. Local reads only; the boot checks it all in the background.
+  const paintCachedSession = useCallback(async (): Promise<boolean> => {
+    const cache = cachedBootRef.current;
+    if (identity || !clientIdProp || !cache) return false;
+    const cached = await cache.readSession(clientIdProp, authStore);
+    const selected = registeredLaneRef.current;
+    if (
+      !cached ||
+      selected.clientId !== clientIdProp ||
+      selected.services !== oxyServices ||
+      selected.lane === 'oauth'
+    ) {
+      return false;
+    }
+    if (selected.lane === null) {
+      // The cached verdict stands in for the registry until it answers, so the
+      // refresh handler, lost-token recovery and sign-in treat this app as the
+      // device lane it was on last run.
+      selected.lane = 'device';
+      selected.provisional = true;
+    }
+    if (cached.warmToken) oxyServices.session.setAccessToken(cached.warmToken);
+    await syncDeviceCredentialToHost();
+    const now = new Date();
+    runtime.batch(() => {
+      runtime.mergeSessions(
+        [
+          {
+            sessionId: cached.sessionId,
+            deviceId: cached.deviceId,
+            expiresAt: new Date(now.getTime() + DEFAULT_SESSION_VALIDITY_MS).toISOString(),
+            lastActive: now.toISOString(),
+            userId: cached.userId,
+            isCurrent: true,
+          },
+        ],
+        { merge: true },
+      );
+      runtime.setActiveSessionId(cached.sessionId);
+      runtime.setAccount(cached.user);
+    });
+    onAuthStateChangeRef.current?.(cached.user);
+    markAuthResolvedRef.current();
+    return true;
+  }, [identity, clientIdProp, authStore, oxyServices, runtime, syncDeviceCredentialToHost]);
+
+  // A painted session the server could not be asked about yet stays on screen
+  // and is asked again: on the lost-token backoff, and at once when the device
+  // comes back online. Signed out meanwhile, there is nothing left to ask.
+  const cachedSessionCheckRef = useRef<{
+    timer: ReturnType<typeof setTimeout> | null;
+    attempt: number;
+    runNow: (() => void) | null;
+  }>({ timer: null, attempt: 0, runNow: null });
+  const scheduleCachedSessionCheck = useCallback(
+    (retry: () => Promise<void>): void => {
+      const check = cachedSessionCheckRef.current;
+      if (check.timer !== null) clearTimeout(check.timer);
+      const run = (): void => {
+        if (check.timer !== null) clearTimeout(check.timer);
+        check.timer = null;
+        check.runNow = null;
+        if (runtime.getSnapshot().account === null) return;
+        retry().catch((retryError) => {
+          logger('Failed to check the cached session', retryError);
+        });
+      };
+      const delay =
+        TOKEN_RECOVERY_BACKOFF_MS[Math.min(check.attempt, TOKEN_RECOVERY_BACKOFF_MS.length - 1)];
+      check.attempt += 1;
+      check.runNow = run;
+      check.timer = setTimeout(run, delay);
+    },
+    [runtime, logger],
+  );
+  useEffect(
+    () => () => {
+      const check = cachedSessionCheckRef.current;
+      if (check.timer !== null) clearTimeout(check.timer);
+      check.timer = null;
+      check.runNow = null;
+    },
+    [],
+  );
+
   // ── Cold boot ────────────────────────────────────────────────────────────
   // Device-first session restore via `runProviderColdBoot` (see boot/runProviderColdBoot.ts).
   const runColdBoot = useCallback(async (): Promise<void> => {
@@ -1314,6 +1451,9 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       commitSession: (input, options) => commitSessionRef.current(input, options),
       markAuthResolved: () => markAuthResolvedRef.current(),
       setTokenReady,
+      paintCachedSession,
+      onCachedSessionRejected: () => clearSessionStateRef.current(),
+      onCachedSessionUnconfirmed: scheduleCachedSessionCheck,
     });
     // The boot may have (re-)established the identity session or cleared a pin
     // whose key no longer exists, so re-resolve rather than trusting the memo
@@ -1329,6 +1469,8 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
     syncDeviceCredentialToHost,
     sessionClient,
     setTokenReady,
+    paintCachedSession,
+    scheduleCachedSessionCheck,
   ]);
 
   useEffect(() => {
@@ -1427,6 +1569,7 @@ export const OxyRuntimeProvider: React.FC<OxyRuntimeProviderProps> = ({
       if (!online || !wasOffline) {
         return;
       }
+      cachedSessionCheckRef.current.runNow?.();
       void (async () => {
         if (hasIsolatedOAuthSession(runtime)) return;
         if (oxyServices.session.accessToken || !sessionClientHost.getDeviceCredential()) {

package/src/ui/hooks/queries/__tests__/useSupervision.test.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from 'react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { SUPERVISION_CHANGED_EVENT } from '@oxy.so/contracts/client';
+import { SupervisionStateObserver, useSupervision } from '../useSupervision';
+
+const mockSupervisionState = jest.fn();
+const mockServerEvents = new Map<string, (payload: unknown) => void>();
+jest.mock('../../../context/oxyRuntimeContext', () => ({
+  useOxy: () => ({
+    oxyServices: { safety: { supervisionState: mockSupervisionState } },
+    user: { id: 'child', kind: 'personal' },
+    canUsePrivateApi: true,
+    activeSessionId: 'session',
+    sessionClient: {
+      onServerEvent: (event: string, listener: (payload: unknown) => void) => {
+        mockServerEvents.set(event, listener);
+        return () => mockServerEvents.delete(event);
+      },
+    },
+  }),
+}));
+
+const state = (status: 'active' | 'ended') => ({
+  self: {
+    childAccountId: 'child',
+    guardianAccountId: 'guardian',
+    status,
+    policyVersion: '2',
+    consentVersion: '1',
+    createdAt: '2026-10-23T00:00:00.000Z',
+  },
+  children: [],
+  invitations: [],
+});
+
+function setup() {
+  const client = new QueryClient();
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={client}>{children}</QueryClientProvider>
+  );
+  render(<SupervisionStateObserver />, { wrapper });
+  return wrapper;
+}
+
+beforeEach(() => {
+  mockSupervisionState.mockReset();
+  mockServerEvents.clear();
+});
+
+it('serves the session state to a new screen from the cache, without a request', async () => {
+  mockSupervisionState.mockResolvedValue(state('active'));
+  const wrapper = setup();
+  await waitFor(() => expect(mockSupervisionState).toHaveBeenCalledTimes(1));
+  await act(async () => {});
+
+  const { result } = renderHook(() => useSupervision(), { wrapper });
+
+  expect(result.current.data?.self?.status).toBe('active');
+  expect(mockSupervisionState).toHaveBeenCalledTimes(1);
+});
+
+it('refetches when the session socket signals a supervision change', async () => {
+  mockSupervisionState.mockResolvedValueOnce(state('active')).mockResolvedValue(state('ended'));
+  const wrapper = setup();
+  const { result } = renderHook(() => useSupervision(), { wrapper });
+  await waitFor(() => expect(result.current.data?.self?.status).toBe('active'));
+
+  act(() => mockServerEvents.get(SUPERVISION_CHANGED_EVENT)?.(undefined));
+
+  await waitFor(() => expect(result.current.data?.self?.status).toBe('ended'));
+  expect(mockSupervisionState).toHaveBeenCalledTimes(2);
+});