@oxyhq/services 22.10.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';
@@ -652,6 +657,28 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
   // 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({
@@ -665,11 +692,9 @@ export const OxyProvider: React.FC<OxyContextProviderProps> = ({
       commitSession: (session) => handleWebSessionRef.current(session),
       commitSwitchedSession: (session) => commitSwitchedSessionRef.current(session),
       onSignedIn: () => {
-        // Dismiss the surface; its settle (`result.finally` below) is what flips
-        // `accountDialogOpen` false. The surface's present→settle lifecycle is the
-        // SINGLE source of truth for "is the account dialog open" — never a manual
-        // flip here.
-        accountDialogSurfaceRef.current?.dismiss();
+        // 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()) {
@@ -694,40 +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. When a
-    // route surface (e.g. ManageAccount) is already open, this stacks the dialog
-    // ABOVE it; dismissing the dialog unwinds back to that surface.
-    if (!accountDialogSurfaceRef.current) {
-      const instance = presentDetached(
-        'AccountDialog',
-        { initialView: view ?? 'accounts' },
-        { placement: { base: 'bottom', md: 'center' }, dismissOnBackdrop: false, maxWidth: 420 },
-      );
-      accountDialogSurfaceRef.current = instance;
-      // The surface settling is the ONE place `accountDialogOpen` flips false —
-      // covering every dismiss path (close button, `onSignedIn`, programmatic
-      // `closeAccountDialog`, host unmount). So the stack owns the open state.
-      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();
-    // Dismiss the surface; its settle (`result.finally` above) flips
-    // `accountDialogOpen` false. Do NOT flip it here — the surface lifecycle is
-    // the single source of truth, so a manual write would be a second authority.
-    accountDialogSurfaceRef.current?.dismiss();
-  }, []);
+    dismissAccountDialogSurface();
+  }, [dismissAccountDialogSurface]);
 
   // Start driving the dialog on mount; tear it down on unmount.
   useEffect(() => {

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,18 +1,23 @@
 /**
  * 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 (typed promises over the shared surface stack — no callback props):
- *   1. `surfaces.present('FileManagement', …)` opens the image-only picker and
- *      resolves with the picked file (or `undefined` if the user cancels).
- *   2. Resolve a private-safe source URL, then `surfaces.present('AvatarCrop', …)`
- *      opens the square-crop editor and resolves with the cropped JPEG.
- *   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';
@@ -21,7 +26,7 @@ import { translate, updateAvatarVisibility } from '@oxyhq/core';
 import type { QueryClient } from '@tanstack/react-query';
 import { toast } from '@oxyhq/bloom';
 import { updateProfileWithAvatar } from '../utils/avatarUtils';
-import { surfaces } from '../navigation/surfaces';
+import { openWithinOrPresent } from '../navigation/surfaces';
 import type { AvatarCropResult } from '../screens/AvatarCropScreen';
 
 interface UseAvatarPickerOptions {
@@ -98,56 +103,36 @@ export function useAvatarPicker({
     [activeSessionId, currentLanguage, oxyServices, queryClient],
   );
 
-  const openAvatarPicker = useCallback(async () => {
-    // 1. Present the image-only picker; it dismisses with the picked file when
-    //    the user taps one, or `undefined` if they cancel.
-    const file = await surfaces.present('FileManagement', {
-      selectMode: true,
-      multiSelect: false,
-      disabledMimeTypes: ['video/', 'audio/', 'application/pdf'],
-    });
-    if (!file) return;
-
-    if (!file.contentType?.startsWith('image/')) {
-      toast.error(
-        translate(currentLanguage ?? undefined, 'editProfile.toasts.selectImage') ||
-          'Please select an image file',
-      );
-      return;
-    }
-
-    // 2. Resolve a working source URL. 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. `assetGetUrl`
-    //    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.
-    let sourceUri: string;
+  /** Clear the avatar so the profile falls back to the user's initials. */
+  const removeAvatar = useCallback(async () => {
     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;
+      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.cropMeasureFailed') ||
-          'Could not load the selected image',
+          translate(currentLanguage ?? undefined, 'editProfile.toasts.updateAvatarFailed'),
       );
-      return;
     }
+  }, [activeSessionId, currentLanguage, oxyServices, queryClient]);
 
-    // 3. Present the square-crop editor in place of the picker; it dismisses
-    //    with the cropped JPEG on confirm, or `undefined` if cancelled.
-    const cropped = await surfaces.present('AvatarCrop', { imageUri: sourceUri });
-    if (!cropped) return;
-
-    // 4. Upload + set as the user's avatar.
-    await finalizeCroppedAvatar(cropped);
-  }, [currentLanguage, finalizeCroppedAvatar, oxyServices]);
+  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

@@ -13,7 +13,7 @@ import type { DialogHeaderConfig } from '@oxyhq/bloom/dialog';
  */
 export type SurfaceHeaderContent = Pick<
   DialogHeaderConfig,
-  'title' | 'subtitle' | 'largeTitle' | 'left' | 'right' | 'onBack'
+  'title' | 'titleContent' | 'subtitle' | 'largeTitle' | 'left' | 'right' | 'onBack'
 >;
 
 interface SurfaceHeaderContextValue {
@@ -47,6 +47,7 @@ export function useSurfaceHeader(content: SurfaceHeaderContent | null | undefine
   }, [
     set,
     content?.title,
+    content?.titleContent,
     content?.subtitle,
     content?.largeTitle,
     content?.left,

package/src/ui/navigation/__tests__/getSurfaceConfig.test.ts

@@ -1,10 +1,10 @@
 import { getSurfaceConfig, getSurfacePresentation } from '../surfaceRegistry';
 
 /**
- * `getSurfaceConfig` resolves which Bloom surface a route is presented in. The
- * flagship image picker (FileManagement in image-only select mode) upgrades to a
- * full-bleed `'fullScreen'` surface that owns its own scrolling; every other
- * route stays on the responsive `'sheet'`. These guard the routing contract.
+ * `getSurfaceConfig` resolves how a route renders. EVERY route is a responsive
+ * `'sheet'` that MORPHS in place; NO route stacks (genuine overlays are Bloom-raw
+ * calls outside this registry). The flagship image picker is a sheet that owns its
+ * own scrolling + chrome. These guard the routing contract.
  */
 describe('getSurfaceConfig presentation', () => {
     const imageOnlyPickerProps = {
@@ -18,11 +18,59 @@ describe('getSurfaceConfig presentation', () => {
         expect(getSurfacePresentation('ManageAccount', {})).toBe('sheet');
     });
 
-    it('routes the FileManagement image-only picker to a full-screen surface', () => {
+    it('renders the FileManagement image-only picker as a morphing own-scroller sheet', () => {
         const config = getSurfaceConfig('FileManagement', imageOnlyPickerProps);
-        expect(config.presentation).toBe('fullScreen');
-        // The full-bleed picker owns its own FlatList → the host must not wrap it.
+        // It morphs in place like every screen — a sheet, not a stacked full-bleed.
+        expect(config.presentation).toBe('sheet');
+        expect(config.stacks).toBe(false);
+        // PhotoPickerView owns its own FlatList → the host must not wrap it in a
+        // ScrollView; and its own translucent bar → no Dialog nav header.
         expect(config.scrollable).toBe(false);
+        expect(config.header).toBe(false);
+    });
+
+    it('morphs the surface for every route, the picker included', () => {
+        // NAV-WITHIN: drilling into these swaps the content inside ONE surface,
+        // which reshapes the panel instead of hard-cutting.
+        expect(getSurfaceConfig('ManageAccount', {}).morph).toBe(true);
+        expect(getSurfaceConfig('FAQ', {}).morph).toBe(true);
+        expect(getSurfaceConfig('FollowersList', {}).morph).toBe(true);
+        expect(getSurfaceConfig('FileManagement', imageOnlyPickerProps).morph).toBe(true);
+    });
+
+    it('never stacks any route — every screen morphs in place', () => {
+        // `stacks` is the DECLARATIVE morph-vs-stack signal, and it is FALSE for
+        // every route: overlays (action sheets / confirm / prompt) are Bloom-raw
+        // `surfaces.present`/`confirm` calls outside this registry.
+        expect(getSurfaceConfig('ManageAccount', {}).stacks).toBe(false);
+        expect(getSurfaceConfig('AvatarCrop', {}).stacks).toBe(false);
+        expect(getSurfaceConfig('ChangeAvatar', {}).stacks).toBe(false);
+        expect(getSurfaceConfig('AccountDialog', {}).stacks).toBe(false);
+        expect(getSurfaceConfig('FileManagement', imageOnlyPickerProps).stacks).toBe(false);
+        expect(getSurfaceConfig('FileManagement', {}).stacks).toBe(false);
+    });
+
+    it('lets the avatar flow morph list → crop inside ONE surface', () => {
+        // ChangeAvatar navigates WITHIN its surface to AvatarCrop, so both frames
+        // must share a presentation (else the crop would open on top instead of
+        // morphing) and both must opt IN to the morph.
+        const list = getSurfaceConfig('ChangeAvatar', {});
+        const crop = getSurfaceConfig('AvatarCrop', {});
+        expect(crop.presentation).toBe(list.presentation);
+        expect(list.morph).toBe(true);
+        expect(crop.morph).toBe(true);
+        // The morph can only RESIZE the panel when the Dialog owns the scroll
+        // container — an own-scroller surface cross-fades but never reshapes.
+        expect(list.scrollable).toBe(true);
+        expect(crop.scrollable).toBe(true);
+    });
+
+    it('gives the avatar flow the Dialog nav header on both frames', () => {
+        // The Dialog's `header` is fixed for a surface's whole life, so a
+        // headerless crop frame inside a header-mode surface would stack two
+        // bars. Both frames declare their chrome through `useSurfaceHeader`.
+        expect(getSurfaceConfig('ChangeAvatar', {}).header).toBe(true);
+        expect(getSurfaceConfig('AvatarCrop', {}).header).toBe(true);
     });
 
     it('keeps FileManagement on the sheet when it is not an image-only picker', () => {