@oxyhq/services 22.9.0 → 22.11.0

package/src/ui/context/OxyContext.tsx

@@ -45,7 +45,12 @@ import { useDeviceManagement } from '../hooks/useDeviceManagement';
 import { getStorageKeys, createPlatformStorage, type StorageInterface } from '../utils/storageHelpers';
 import type { RouteName } from '../navigation/routes';
 import { showBottomSheet as globalShowBottomSheet } from '../navigation/bottomSheetManager';
-import { presentDetached, type SurfaceInstance } from '../navigation/surfaces';
+import {
+  presentDetached,
+  topRouteSurface,
+  type SurfaceInstance,
+  type TrackedSurface,
+} from '../navigation/surfaces';
 import { useQueryClient, onlineManager } from '@tanstack/react-query';
 import { clearQueryCache } from '../hooks/queryClient';
 import { useAvatarPicker } from '../hooks/useAvatarPicker';
@@ -644,11 +649,36 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   const commitSwitchedSessionRef = useRef(commitSwitchedSession);
   commitSwitchedSessionRef.current = commitSwitchedSession;
 
-  // The live AccountDialog surface (a stacked Bloom surface), while open. Held so
+  // The live AccountDialog surface (a stacked Bloom surface), while open — the
+  // SINGLE source of truth for "is the account dialog open". Held so
   // `openAccountDialog` can no-op when already open and `closeAccountDialog` /
-  // `onSignedIn` can dismiss it. Cleared when the surface settles.
+  // `onSignedIn` can dismiss it. Its present→settle lifecycle is what drives the
+  // reactive `accountDialogOpen` mirror below: presenting flips it true, the
+  // surface settling (`result.finally`) flips it false — no other write site.
   const accountDialogSurfaceRef = useRef<SurfaceInstance<'AccountDialog'> | null>(null);
 
+  // When the account dialog is shown by MORPHING an already-open route surface
+  // (e.g. ManageAccount → the account switcher) it is pushed as a frame ONTO that
+  // surface rather than presented as its own. This holds that host surface so the
+  // close path can pop the AccountDialog frame back to it. `null` when the dialog
+  // is its OWN detached surface (opened cold, with no surface underneath).
+  const accountDialogHostRef = useRef<TrackedSurface | null>(null);
+
+  // The single teardown for the account dialog wherever it lives: pop the morphed
+  // frame back to its host surface (reshaping Manage ← switcher), or dismiss the
+  // detached surface (whose settle then flips `accountDialogOpen`). Reads only
+  // stable refs + `setAccountDialogOpen`, so its identity never changes.
+  const dismissAccountDialogSurface = useCallback((): void => {
+    const host = accountDialogHostRef.current;
+    if (host) {
+      accountDialogHostRef.current = null;
+      setAccountDialogOpen(false);
+      host.goBack();
+      return;
+    }
+    accountDialogSurfaceRef.current?.dismiss();
+  }, []);
+
   const accountDialogControllerRef = useRef<AccountDialogController | null>(null);
   if (!accountDialogControllerRef.current) {
     accountDialogControllerRef.current = createAccountDialogController({
@@ -662,8 +692,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       commitSession: (session) => handleWebSessionRef.current(session),
       commitSwitchedSession: (session) => commitSwitchedSessionRef.current(session),
       onSignedIn: () => {
-        accountDialogSurfaceRef.current?.dismiss();
-        setAccountDialogOpen(false);
+        // Close the dialog: pop the morphed frame back to its host surface, or
+        // dismiss the detached surface (whose settle flips `accountDialogOpen`).
+        dismissAccountDialogSurface();
       },
       openUrl: (url) => {
         if (isWebBrowser()) {
@@ -688,31 +719,55 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   const accountDialogController = accountDialogControllerRef.current;
 
   const openAccountDialog = useCallback((view?: AccountDialogView): void => {
-    accountDialogControllerRef.current?.setView(view ?? 'accounts');
-    // Present the AccountDialog surface on the shared Bloom stack the FIRST time
-    // (subsequent opens just re-point the controller's view above). `presentDetached`
-    // keeps it OUT of the `showBottomSheet` route-surface lineage, so closing the
-    // bottom-sheet session never touches the account dialog and vice-versa.
-    if (!accountDialogSurfaceRef.current) {
-      const instance = presentDetached(
-        'AccountDialog',
-        { initialView: view ?? 'accounts' },
-        { placement: { base: 'bottom', md: 'center' }, dismissOnBackdrop: false, maxWidth: 420 },
-      );
-      accountDialogSurfaceRef.current = instance;
-      instance.result.finally(() => {
-        if (accountDialogSurfaceRef.current === instance) accountDialogSurfaceRef.current = null;
-        setAccountDialogOpen(false);
-      });
+    const nextView = view ?? 'accounts';
+    accountDialogControllerRef.current?.setView(nextView);
+
+    // Its own detached surface is already open → just re-point the view above.
+    if (accountDialogSurfaceRef.current) {
+      setAccountDialogOpen(true);
+      return;
+    }
+
+    // When a route surface (e.g. ManageAccount) is already open, MORPH it in
+    // place: push the AccountDialog as a frame ONTO that surface, so the panel
+    // reshapes from that surface to the switcher and a back returns to it. With no
+    // surface open (opened cold from a sign-in button), present the dialog as its
+    // OWN detached surface — kept OUT of the `showBottomSheet` route-surface
+    // lineage so closing the bottom-sheet session never touches it and vice-versa.
+    // `navigate` is idempotent for the top frame (it replaces rather than
+    // duplicates), so calling this while already morphed in just re-points the
+    // view, and calling it after a back re-pushes the frame — no stale guard.
+    const host = topRouteSurface();
+    if (host) {
+      accountDialogHostRef.current = host;
+      host.navigate('AccountDialog', { initialView: nextView });
+      setAccountDialogOpen(true);
+      return;
     }
+
+    const instance = presentDetached(
+      'AccountDialog',
+      { initialView: nextView },
+      { placement: { base: 'bottom', md: 'center' }, dismissOnBackdrop: false, maxWidth: 420 },
+    );
+    accountDialogSurfaceRef.current = instance;
+    // The surface settling is the ONE place `accountDialogOpen` flips false for
+    // the detached path — covering every dismiss (close button, `onSignedIn`,
+    // programmatic `closeAccountDialog`, host unmount). The morphed path clears
+    // its own state in `dismissAccountDialogSurface`.
+    instance.result.finally(() => {
+      if (accountDialogSurfaceRef.current === instance) {
+        accountDialogSurfaceRef.current = null;
+        setAccountDialogOpen(false);
+      }
+    });
     setAccountDialogOpen(true);
   }, []);
 
   const closeAccountDialog = useCallback((): void => {
     accountDialogControllerRef.current?.cancelSignIn();
-    accountDialogSurfaceRef.current?.dismiss();
-    setAccountDialogOpen(false);
-  }, []);
+    dismissAccountDialogSurface();
+  }, [dismissAccountDialogSurface]);
 
   // Start driving the dialog on mount; tear it down on unmount.
   useEffect(() => {
@@ -960,7 +1015,6 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
     currentLanguage,
     activeSessionId,
     queryClient,
-    showBottomSheet: showBottomSheetForContext,
   });
 
   const { accounts, refreshAccounts, switchToAccount, createAccount: createAccountFn } = useOxyAccountGraph({

package/src/ui/hooks/queries/queryKeys.ts

@@ -100,6 +100,13 @@ export const queryKeys = {
     usage: (accountScope?: string) => [...queryKeys.storage.all, 'usage', accountScope] as const,
   },
 
+  // User file library (infinite-paginated; owner-scoped so switching the active
+  // account shows that account's files without a manual reset)
+  files: {
+    all: ['files'] as const,
+    list: (ownerId?: string) => [...queryKeys.files.all, 'list', ownerId || 'anonymous'] as const,
+  },
+
   // Connected apps (OAuth grants the user has authorized)
   connectedApps: {
     all: ['connectedApps'] as const,
@@ -204,3 +211,11 @@ export const invalidateConnectedAppsQueries = (queryClient: QueryClient): void =
   queryClient.invalidateQueries({ queryKey: queryKeys.connectedApps.all });
 };
 
+/**
+ * Helper to invalidate the user's file library (all owners). Pass an ownerId via
+ * `queryKeys.files.list(ownerId)` for a scoped invalidation instead.
+ */
+export const invalidateFileQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.files.all });
+};
+

package/src/ui/hooks/queries/useFileQueries.ts

@@ -0,0 +1,162 @@
+/**
+ * User file-library queries + cache helpers.
+ *
+ * The file list is owned by React Query (`useInfiniteQuery`), NOT a zustand
+ * store: server pages live in the query cache, and every optimistic mutation
+ * (upload / delete / visibility) edits that cache via the pure `*InCache`
+ * helpers below. The `queryFn` is side-effect-free — it only fetches and maps a
+ * page. This is what lets the file manager stay effect-free while preserving
+ * infinite scroll, pull-to-refresh, and optimistic upload reconciliation.
+ */
+
+import {
+    useInfiniteQuery,
+    type InfiniteData,
+    type QueryClient,
+} from '@tanstack/react-query';
+import type { FileMetadata } from '@oxyhq/core';
+import { useOxy } from '../../context/OxyContext';
+import { queryKeys } from './queryKeys';
+
+/** Files fetched per page. */
+export const FILES_PAGE_SIZE = 40;
+
+/** Raw file record as returned by `oxyServices.listUserFiles` / `assetUpload`. */
+export interface RawUserFile {
+    id: string;
+    originalName?: string;
+    sha256?: string;
+    mime?: string;
+    size?: number;
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+    variants?: unknown[];
+}
+
+/** One page of the infinite file list. */
+export interface UserFilesPage {
+    files: FileMetadata[];
+    total: number;
+    hasMore: boolean;
+    nextOffset: number;
+}
+
+export type UserFilesInfinite = InfiniteData<UserFilesPage>;
+
+/** Normalize a raw API file record into the client `FileMetadata` shape. */
+export function mapRawFileToMetadata(raw: RawUserFile): FileMetadata {
+    return {
+        id: raw.id,
+        filename: raw.originalName ?? raw.sha256 ?? '',
+        contentType: raw.mime ?? '',
+        length: raw.size ?? 0,
+        chunkSize: 0,
+        uploadDate: raw.createdAt ?? '',
+        metadata: raw.metadata ?? {},
+        variants: (raw.variants ?? []) as FileMetadata['variants'],
+    };
+}
+
+/**
+ * Infinite-paginated list of the owner's files. Fires on mount and whenever
+ * `ownerId` changes (a new key); `staleTime: 0` reloads on every open. The
+ * rendered list is `data.pages.flatMap(p => p.files)`.
+ */
+export const useUserFilesInfinite = (ownerId?: string) => {
+    const { oxyServices } = useOxy();
+    return useInfiniteQuery<UserFilesPage, Error>({
+        queryKey: queryKeys.files.list(ownerId),
+        queryFn: async ({ pageParam }) => {
+            const offset = typeof pageParam === 'number' ? pageParam : 0;
+            const response = await oxyServices.listUserFiles(FILES_PAGE_SIZE, offset);
+            const raw = (response.files ?? []) as RawUserFile[];
+            const files = raw.map(mapRawFileToMetadata);
+            return {
+                files,
+                total: response.total ?? offset + files.length,
+                hasMore: Boolean(response.hasMore),
+                nextOffset: offset + FILES_PAGE_SIZE,
+            };
+        },
+        initialPageParam: 0,
+        getNextPageParam: (lastPage) => (lastPage.hasMore ? lastPage.nextOffset : undefined),
+        enabled: Boolean(ownerId),
+        staleTime: 0,
+        refetchOnWindowFocus: false,
+    });
+};
+
+// --- Pure cache transforms (optimistic updates) -----------------------------
+// Each edits the cached `InfiniteData` for one owner. All no-op when nothing is
+// cached yet (e.g. an upload before the first page loads) — the subsequent
+// `invalidateQueries` reconcile then brings the authoritative record.
+
+const fileListKey = (ownerId?: string) => queryKeys.files.list(ownerId);
+
+const mapPages = (
+    data: UserFilesInfinite,
+    fn: (files: FileMetadata[]) => FileMetadata[],
+): UserFilesInfinite => ({
+    ...data,
+    pages: data.pages.map((page) => ({ ...page, files: fn(page.files) })),
+});
+
+/** Prepend an (optimistic) file to the first page. */
+export function prependFileToCache(
+    queryClient: QueryClient,
+    ownerId: string | undefined,
+    file: FileMetadata,
+): void {
+    queryClient.setQueryData<UserFilesInfinite>(fileListKey(ownerId), (data) => {
+        if (!data || data.pages.length === 0) return data;
+        return {
+            ...data,
+            pages: data.pages.map((page, index) =>
+                index === 0 ? { ...page, files: [file, ...page.files] } : page,
+            ),
+        };
+    });
+}
+
+/** Remove a file (by id) from every page. */
+export function removeFileFromCache(
+    queryClient: QueryClient,
+    ownerId: string | undefined,
+    fileId: string,
+): void {
+    queryClient.setQueryData<UserFilesInfinite>(fileListKey(ownerId), (data) =>
+        data ? mapPages(data, (files) => files.filter((f) => f.id !== fileId)) : data,
+    );
+}
+
+/** Swap an optimistic file (by id) for its persisted counterpart. */
+export function replaceFileInCache(
+    queryClient: QueryClient,
+    ownerId: string | undefined,
+    oldId: string,
+    newFile: FileMetadata,
+): void {
+    queryClient.setQueryData<UserFilesInfinite>(fileListKey(ownerId), (data) =>
+        data ? mapPages(data, (files) => files.map((f) => (f.id === oldId ? newFile : f))) : data,
+    );
+}
+
+/** Shallow-merge a metadata patch into a cached file (e.g. visibility change). */
+export function patchFileMetadataInCache(
+    queryClient: QueryClient,
+    ownerId: string | undefined,
+    fileId: string,
+    metadataPatch: Record<string, unknown>,
+): void {
+    queryClient.setQueryData<UserFilesInfinite>(fileListKey(ownerId), (data) =>
+        data
+            ? mapPages(data, (files) =>
+                files.map((f) =>
+                    f.id === fileId
+                        ? { ...f, metadata: { ...f.metadata, ...metadataPatch } as FileMetadata['metadata'] }
+                        : f,
+                ),
+            )
+            : data,
+    );
+}

package/src/ui/hooks/useAvatarPicker.ts

@@ -1,26 +1,32 @@
 /**
  * Avatar Picker Hook
  *
- * Extracts avatar selection logic from OxyContext for better modularity.
+ * The ONE write path for a user's profile picture. It owns no UI: the whole
+ * choose-and-crop experience is a single surface.
  *
- * Flow:
- *   1. Open the FileManagement bottom sheet in select mode for image files.
- *   2. After the user picks an image, route to the AvatarCrop screen so they
- *      can square-crop + zoom before the avatar is set.
- *   3. The cropped JPEG is uploaded as a NEW file via `oxyServices.assetUpload`
- *      and that file becomes the user's avatar.
+ * Flow (typed promise over the shared surface stack — no callback props):
+ *   1. `openWithinOrPresent('ChangeAvatar')` opens the source list (device gallery,
+ *      camera, existing Oxy files, remove) — MORPHING into the caller's surface
+ *      when one is open, else presenting cold. Whichever source the user picks, it
+ *      navigates WITHIN to the crop editor — so there is exactly one cropper and
+ *      one entry into it.
+ *   2. The surface resolves with the cropped JPEG, with `{ removed: true }` when
+ *      the user removed their photo, or `undefined` when they cancelled.
+ *   3. A crop is uploaded as a NEW file via `oxyServices.assetUpload` and set as
+ *      the avatar; a removal clears the avatar field.
  *
- * `expo-image-manipulator` is required for the crop step (declared as an
- * optional peer in the consuming app) — see AvatarCropScreen.
+ * `expo-image-manipulator` is required for the crop step and `expo-image-picker`
+ * for the device/camera sources (both declared as optional peers in the
+ * consuming app) — see AvatarCropScreen / ChangeAvatarScreen.
  */
 
 import { useCallback } from 'react';
-import type { FileMetadata, OxyServices } from '@oxyhq/core';
+import type { OxyServices } from '@oxyhq/core';
 import { translate, updateAvatarVisibility } from '@oxyhq/core';
 import type { QueryClient } from '@tanstack/react-query';
 import { toast } from '@oxyhq/bloom';
-import type { RouteName } from '../navigation/routes';
 import { updateProfileWithAvatar } from '../utils/avatarUtils';
+import { openWithinOrPresent } from '../navigation/surfaces';
 import type { AvatarCropResult } from '../screens/AvatarCropScreen';
 
 interface UseAvatarPickerOptions {
@@ -28,7 +34,6 @@ interface UseAvatarPickerOptions {
   currentLanguage: string | null | undefined;
   activeSessionId: string | null;
   queryClient: QueryClient;
-  showBottomSheet: (config: { screen: RouteName; props?: Record<string, unknown> }) => void;
 }
 
 /** Upload result shape returned by oxyServices.assetUpload (single-file path). */
@@ -52,7 +57,6 @@ export function useAvatarPicker({
   currentLanguage,
   activeSessionId,
   queryClient,
-  showBottomSheet,
 }: UseAvatarPickerOptions) {
   /**
    * Final step: take the cropped JPEG, upload it as a new public file, then
@@ -99,68 +103,36 @@ export function useAvatarPicker({
     [activeSessionId, currentLanguage, oxyServices, queryClient],
   );
 
-  /**
-   * After the user picks a file in the FileManagement sheet, resolve a working
-   * source URL and route to the crop screen.
-   *
-   * The picked file is usually PRIVATE, so the synchronous
-   * `getFileDownloadUrl` (public CDN origin) would 404 and the crop screen's
-   * `Image.getSize` would fail silently. We resolve the authenticated URL via
-   * `assetGetUrl` (which throws on failure — unlike `getFileDownloadUrlAsync`,
-   * which swallows errors and falls back to the broken public URL) so a
-   * failure surfaces a real user-facing error instead of a blank crop canvas.
-   * No variant is requested — cropping needs the original.
-   */
-  const handleFilePicked = useCallback(
-    async (file: FileMetadata) => {
-      if (!file.contentType?.startsWith('image/')) {
-        toast.error(
-          translate(currentLanguage ?? undefined, 'editProfile.toasts.selectImage') ||
-            'Please select an image file',
-        );
-        return;
-      }
-
-      let sourceUri: string;
-      try {
-        const resolved = await oxyServices.assetGetUrl(file.id);
-        if (!resolved?.url) {
-          throw new Error('No download URL returned for the selected image');
-        }
-        sourceUri = resolved.url;
-      } catch (e: unknown) {
-        const message = e instanceof Error ? e.message : undefined;
-        toast.error(
-          message ||
-            translate(currentLanguage ?? undefined, 'editProfile.toasts.cropMeasureFailed') ||
-            'Could not load the selected image',
-        );
-        return;
-      }
-
-      showBottomSheet({
-        screen: 'AvatarCrop',
-        props: {
-          imageUri: sourceUri,
-          onConfirm: finalizeCroppedAvatar,
-        },
-      });
-    },
-    [currentLanguage, finalizeCroppedAvatar, oxyServices, showBottomSheet],
-  );
+  /** Clear the avatar so the profile falls back to the user's initials. */
+  const removeAvatar = useCallback(async () => {
+    try {
+      await updateProfileWithAvatar({ avatar: '' }, oxyServices, activeSessionId, queryClient);
+      toast.success(
+        translate(currentLanguage ?? undefined, 'editProfile.toasts.avatarRemoved'),
+      );
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : undefined;
+      toast.error(
+        message ||
+          translate(currentLanguage ?? undefined, 'editProfile.toasts.updateAvatarFailed'),
+      );
+    }
+  }, [activeSessionId, currentLanguage, oxyServices, queryClient]);
 
-  const openAvatarPicker = useCallback(() => {
-    showBottomSheet({
-      screen: 'FileManagement',
-      props: {
-        selectMode: true,
-        multiSelect: false,
-        disabledMimeTypes: ['video/', 'audio/', 'application/pdf'],
-        afterSelect: 'none',
-        onSelect: handleFilePicked,
-      },
-    });
-  }, [handleFilePicked, showBottomSheet]);
+  const openAvatarPicker = useCallback(async () => {
+    // The source list + crop editor are ONE flow. When triggered from a screen
+    // already inside a surface (EditProfile, ManageAccount, WelcomeNewUser — every
+    // current entry point), it MORPHS into that surface and pops back on finish;
+    // triggered with no surface open it presents cold. Either way it resolves with
+    // the cropped JPEG, a removal, or `undefined` when the user backs out.
+    const result = await openWithinOrPresent('ChangeAvatar');
+    if (!result) return;
+    if ('removed' in result) {
+      await removeAvatar();
+      return;
+    }
+    await finalizeCroppedAvatar(result);
+  }, [finalizeCroppedAvatar, removeAvatar]);
 
   return { openAvatarPicker };
 }

package/src/ui/hooks/useReduceMotion.ts

@@ -0,0 +1,58 @@
+/**
+ * useReduceMotion
+ *
+ * Reactive boolean reflecting the OS "reduce motion" accessibility preference.
+ * Wraps `AccessibilityInfo` as an external store via `useSyncExternalStore` — the
+ * effect-free, React-Compiler-safe way to read an external mutable source. The
+ * initial value is read asynchronously once (the platform API is a Promise) and
+ * cached module-side; subsequent changes arrive via the `reduceMotionChanged`
+ * event. Mirrors the `useOnlineStatus` pattern.
+ *
+ * Consumers use it to pin entrance/stagger animations off under reduce-motion.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+let cachedReduceMotion = false;
+let initialized = false;
+const listeners = new Set<() => void>();
+
+const notifyAll = (): void => {
+    for (const listener of listeners) listener();
+};
+
+const setCached = (value: boolean): void => {
+    if (cachedReduceMotion === value) return;
+    cachedReduceMotion = value;
+    notifyAll();
+};
+
+const subscribeReduceMotion = (notify: () => void): (() => void) => {
+    // Populate the cache the first time anyone subscribes (the platform read is
+    // async, so it cannot be a synchronous `getSnapshot`).
+    if (!initialized) {
+        initialized = true;
+        AccessibilityInfo.isReduceMotionEnabled()
+            .then(setCached)
+            .catch(() => {
+                // No preference available — the `false` default stands.
+            });
+    }
+    listeners.add(notify);
+    const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setCached);
+    return () => {
+        listeners.delete(notify);
+        sub.remove();
+    };
+};
+
+const getSnapshot = (): boolean => cachedReduceMotion;
+
+// SSR/web-first paint: assume motion is allowed (no reduce) until the async read
+// resolves — matches the prior default.
+const getServerSnapshot = (): boolean => false;
+
+export function useReduceMotion(): boolean {
+    return useSyncExternalStore(subscribeReduceMotion, getSnapshot, getServerSnapshot);
+}

package/src/ui/hooks/useSurfaceHeader.ts

@@ -0,0 +1,57 @@
+import { createContext, useContext, useLayoutEffect } from 'react';
+import type { DialogHeaderConfig } from '@oxyhq/bloom/dialog';
+
+/**
+ * The header content a mounted surface screen contributes at runtime: its
+ * (translated) title/subtitle and optional slot nodes. Back/close affordances
+ * are owned by the surface host (`SurfaceScreen`) — a screen never wires them.
+ *
+ * A `right` slot is the canonical place for a screen-state action (e.g. a Save
+ * button whose disabled/loading state reflects the form). Slot nodes MUST be
+ * referentially stable (memoize them with `useMemo`) so the header does not
+ * thrash.
+ */
+export type SurfaceHeaderContent = Pick<
+  DialogHeaderConfig,
+  'title' | 'titleContent' | 'subtitle' | 'largeTitle' | 'left' | 'right' | 'onBack'
+>;
+
+interface SurfaceHeaderContextValue {
+  setContent: (content: SurfaceHeaderContent | null) => void;
+}
+
+/**
+ * Provided by {@link ../components/SurfaceScreen}. Bridges a screen's runtime
+ * header contribution up to the host, which merges it with the back/close
+ * wiring and drives the Dialog's own nav header. `null` outside a surface (or in
+ * a headerless surface), so {@link useSurfaceHeader} is a safe no-op there.
+ */
+export const SurfaceHeaderContext = createContext<SurfaceHeaderContextValue | null>(null);
+
+/**
+ * Declare the Dialog nav header's content from within a surface screen — its
+ * title/subtitle and any action slot. Merges over nothing (the host owns
+ * back/close), replaces on change, and clears on unmount. Call it unconditionally;
+ * it is a no-op outside a header-mode surface.
+ */
+export function useSurfaceHeader(content: SurfaceHeaderContent | null | undefined): void {
+  const ctx = useContext(SurfaceHeaderContext);
+  const set = ctx?.setContent;
+  // Set synchronously in the commit's layout phase so the bar/title fill in
+  // BEFORE the browser paints — no first-frame flash of an empty bar.
+  useLayoutEffect(() => {
+    if (!set) return;
+    set(content ?? null);
+    return () => set(null);
+    // Slot nodes (`left`/`right`) are compared by identity; callers memoize them.
+  }, [
+    set,
+    content?.title,
+    content?.titleContent,
+    content?.subtitle,
+    content?.largeTitle,
+    content?.left,
+    content?.right,
+    content?.onBack,
+  ]);
+}

package/src/ui/hooks/useSwitchableAccounts.ts

@@ -32,7 +32,7 @@ const EMPTY_SNAPSHOT: AccountDialogSnapshot = {
  * real per-account name / email / avatar / color.
  *
  * This is a thin binding over the shared `AccountDialogController` in
- * `@oxyhq/core` (the SAME headless source the {@link OxyAccountDialog} renders),
+ * `@oxyhq/core` (the SAME headless source the {@link OxyAccountDialogScreen} renders),
  * so there is ONE projection (`projectSwitchableAccounts`) and one switch path
  * (`controller.switchTo`) across the whole SDK — the local duplicate projection
  * this hook used to own has been removed. Every switch routes through