@oxyhq/services 22.8.7 → 22.10.0

package/src/ui/navigation/routes.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactNode } from 'react';
+import type { ComponentType } from 'react';
 import type { BaseScreenProps } from '../types/navigation';
 
 // Lazy loading: Screens are loaded on-demand to break require cycles
@@ -42,7 +42,8 @@ export type RouteName =
     | 'AvatarCrop' // Square-crop editor presented before avatar upload
     | 'Notifications' // Per-channel notification preferences
     | 'ConnectedApps' // OAuth-authorized third-party apps the user can revoke
-    | 'Preferences'; // General user preferences (theme, reduce-motion, etc.)
+    | 'Preferences' // General user preferences (theme, reduce-motion, etc.)
+    | 'AccountDialog'; // Unified account switcher + sign-in surface (OxyAccountDialogScreen body)
 
 // Lazy screen loaders - functions that return screen components on-demand
 // This breaks the require cycle by deferring imports until screens are actually needed
@@ -86,6 +87,10 @@ const screenLoaders: Record<RouteName, () => ComponentType<BaseScreenProps>> = {
     Notifications: () => require('../screens/NotificationsScreen').default,
     ConnectedApps: () => require('../screens/ConnectedAppsScreen').default,
     Preferences: () => require('../screens/PreferencesScreen').default,
+    // Unified account switcher + sign-in surface. Its body lives in the
+    // `OxyAccountDialogScreen` component (folded from the standalone dialog); the
+    // surface stack provides the Dialog chrome around it.
+    AccountDialog: () => require('../components/OxyAccountDialogScreen').default,
 };
 
 // Cache loaded components to avoid re-requiring
@@ -121,107 +126,3 @@ export const getScreenComponent = (routeName: RouteName): ComponentType<BaseScre
 export const isValidRoute = (routeName: string): routeName is RouteName => {
     return routeName in screenLoaders;
 };
-
-/**
- * Configuration that BottomSheetRouter applies to the underlying BottomSheet
- * for a given route. Adding new options here is additive — never rename or
- * remove fields without bumping the consumer surface as a breaking change.
- */
-export interface SheetRouteConfig {
-    /**
-     * Which surface hosts the route. `'sheet'` (default) renders the screen in
-     * the in-tree `BottomSheet`. `'dialog'` renders it in a responsive Bloom
-     * `<Dialog>` (bottom-sheet on narrow, centered card on `md+`) — used for the
-     * flagship image picker, which reads better as a centered panel on wide
-     * viewports than a full-width sheet. `BottomSheetRouter` keeps BOTH surfaces
-     * mounted and routes the active screen into exactly one based on this value.
-     */
-    presentation: 'sheet' | 'dialog';
-    /**
-     * When `false`, BottomSheet skips its internal ScrollView and lets the
-     * screen own scrolling. Required for screens that render a FlatList,
-     * SectionList, or any other VirtualizedList — nesting one inside a
-     * plain ScrollView breaks windowing and triggers a RN warning.
-     *
-     * Ignored for `presentation: 'dialog'` routes — those don't render in the
-     * in-tree `BottomSheet` at all.
-     */
-    scrollable: boolean;
-    /**
-     * Controls the body-pan activation strategy on the underlying bloom
-     * `BottomSheet`. `true` uses RNGH's `manualActivation` with scroll-handoff
-     * (recommended for scrollable content — the only RNGH 2.x pattern that
-     * doesn't steal vertical events from the inner scroller on Android).
-     * `false` uses an always-active body pan that gates on scroll offset.
-     *
-     * Defaults to `true` for all routes — matches the historical in-tree
-     * BottomSheet behavior. Per-route opt-out is possible if a screen needs
-     * the always-active pan instead.
-     */
-    manualActivation: boolean;
-    /**
-     * When `true`, the backdrop dims proportionally with drag distance (iOS
-     * Photos style). Defaults to `true` for all routes — matches the
-     * historical in-tree BottomSheet behavior.
-     */
-    dynamicBackdrop: boolean;
-    /**
-     * Optional custom handle slot. When provided, replaces the default
-     * 36×5 pill drag handle. The handle remains unconditionally draggable
-     * via the dedicated handle gesture (when `manualActivation` is `true`).
-     * Use sparingly — screens should default to the standard handle for
-     * platform consistency.
-     */
-    handleComponent?: () => ReactNode;
-}
-
-/**
- * Predicate matching FileManagementScreen's internal `isImageOnlyPicker`
- * derivation. When the consumer restricts to image MIME types (no videos,
- * no audio, no documents), FileManagement renders the flagship PhotoPickerView
- * which owns its own FlatList. The sheet must therefore stop scrolling
- * children. Kept in sync with `FileManagementScreen` — both check the same
- * disabled MIME type families.
- */
-const isFileManagementImageOnlyPicker = (props: Record<string, unknown>): boolean => {
-    if (!props.selectMode) return false;
-    const disabled = props.disabledMimeTypes;
-    if (!Array.isArray(disabled) || disabled.length === 0) return false;
-    const has = (predicate: (mt: string) => boolean): boolean =>
-        disabled.some((mt) => typeof mt === 'string' && predicate(mt));
-    const blocksVideos = has((mt) => mt === 'video/' || mt.startsWith('video/'));
-    const blocksAudio = has((mt) => mt === 'audio/' || mt.startsWith('audio/'));
-    const blocksDocs = has(
-        (mt) => mt === 'application/pdf' || mt === 'application/' || mt.startsWith('application/'),
-    );
-    return blocksVideos && blocksAudio && blocksDocs;
-};
-
-/** Defaults shared across all routes — preserves the historical in-tree BS UX. */
-const DEFAULT_SHEET_CONFIG: SheetRouteConfig = {
-    presentation: 'sheet',
-    scrollable: true,
-    manualActivation: true,
-    dynamicBackdrop: true,
-};
-
-/**
- * Returns the bottom-sheet configuration for a route. Defaults match the
- * pre-refactor in-tree `BottomSheet` (scrollable, manualActivation,
- * dynamicBackdrop). Routes opt out per-field as needed.
- */
-export const getSheetConfig = (
-    routeName: RouteName | null,
-    screenProps: Record<string, unknown>,
-): SheetRouteConfig => {
-    if (!routeName) return DEFAULT_SHEET_CONFIG;
-    if (routeName === 'FileManagement' && isFileManagementImageOnlyPicker(screenProps)) {
-        // The flagship photo picker renders in a responsive Bloom `<Dialog>`
-        // (bottom-sheet on narrow, centered card on `md+`) rather than the
-        // in-tree BottomSheet — it owns its own FlatList and reads better as a
-        // centered panel on wide viewports. The Dialog surface, not this
-        // config's `scrollable`, governs its scrolling.
-        return { ...DEFAULT_SHEET_CONFIG, presentation: 'dialog' };
-    }
-    return DEFAULT_SHEET_CONFIG;
-};

package/src/ui/navigation/surfaceBackBridge.ts

@@ -0,0 +1,69 @@
+import { BackHandler, Platform } from 'react-native';
+
+/**
+ * Per-surface system-back handlers (Android hardware back + web Escape).
+ *
+ * Bloom's `SurfaceHost` dismisses the whole top surface on back/Escape. The SDK
+ * needs the old `BottomSheetRouter` semantics first: pop nav history, step a
+ * wizard back, then dismiss. A single global listener delegates to the topmost
+ * registered handler so stacked surfaces route correctly.
+ */
+
+export type SurfaceBackHandler = () => boolean;
+
+const handlerStack: SurfaceBackHandler[] = [];
+let androidInstalled = false;
+let escapeInstalled = false;
+
+function invokeTopHandler(): boolean {
+  const handler = handlerStack[handlerStack.length - 1];
+  return handler ? handler() : false;
+}
+
+function installAndroidHandler(): void {
+  if (androidInstalled || Platform.OS !== 'android') return;
+  androidInstalled = true;
+  BackHandler.addEventListener('hardwareBackPress', () => {
+    if (handlerStack.length === 0) return false;
+    return invokeTopHandler();
+  });
+}
+
+function installEscapeHandler(): void {
+  if (escapeInstalled || Platform.OS !== 'web') return;
+  if (typeof window === 'undefined') return;
+  escapeInstalled = true;
+  window.addEventListener(
+    'keydown',
+    (event) => {
+      if (event.key !== 'Escape' || handlerStack.length === 0) return;
+      invokeTopHandler();
+      event.stopImmediatePropagation();
+      event.preventDefault();
+    },
+    true,
+  );
+}
+
+/** Register before Bloom's `SurfaceHost` mounts so Escape capture runs first. */
+installEscapeHandler();
+
+/** Push a handler for one live surface; returns unregister. */
+export function pushSurfaceBackHandler(handler: SurfaceBackHandler): () => void {
+  handlerStack.push(handler);
+  installAndroidHandler();
+  return () => {
+    const index = handlerStack.lastIndexOf(handler);
+    if (index >= 0) handlerStack.splice(index, 1);
+  };
+}
+
+/** Test-only: invoke the top handler. */
+export function __invokeTopSurfaceBackForTests(): boolean {
+  return invokeTopHandler();
+}
+
+/** Test-only reset. */
+export function __resetSurfaceBackBridgeForTests(): void {
+  handlerStack.length = 0;
+}

package/src/ui/navigation/surfaceNavStack.ts

@@ -0,0 +1,110 @@
+import { createStore, type StoreApi } from 'zustand/vanilla';
+import type { RouteName } from './routes';
+
+/**
+ * Per-surface route history — the NAV-WITHIN axis.
+ *
+ * Bloom's surface stack owns DEPTH (a surface presented on top of another). This
+ * store owns the ORTHOGONAL axis: the route history INSIDE one SDK surface. Each
+ * SDK surface holds its own {@link SurfaceNavStack}; `navigate`/`replace`/`goBack`
+ * mutate it and the SAME Bloom surface re-renders its content from the new top
+ * frame. It is the per-surface reincarnation of the old global
+ * `bottomSheetStore`'s `history` + `currentStep`.
+ *
+ * `closing`/`closeResult` model a pending dismissal: the surface's `SurfaceScreen`
+ * watches them and calls the Bloom surface's `dismiss(result)` from an effect —
+ * so a dismiss requested BEFORE the surface has mounted still resolves once it
+ * does, with no controls-capture race and no render-phase side effect.
+ */
+
+/** One frame in a surface's route history. */
+export interface NavFrame {
+  route: RouteName;
+  props: Record<string, unknown>;
+  /** Current wizard step for step-based screens (seeded from `props.initialStep`). */
+  step: number;
+}
+
+export interface NavStackState {
+  /** Bottom → top; the last frame is the visible screen. */
+  frames: NavFrame[];
+  /** Flipped once a dismiss is requested; the host resolves the Bloom surface. */
+  closing: boolean;
+  /** The value the surface's `present()` promise resolves with on dismissal. */
+  closeResult: unknown;
+}
+
+export interface SurfaceNavStack {
+  store: StoreApi<NavStackState>;
+  /** Drill in: push a new frame. */
+  navigate(route: RouteName, props?: Record<string, unknown>): void;
+  /** Swap the top frame in place (no history entry). */
+  replace(route: RouteName, props?: Record<string, unknown>): void;
+  /** Pop one frame. Returns `false` when already at the root frame. */
+  goBack(): boolean;
+  /** Whether a back is possible (a deeper frame OR a prior wizard step). */
+  canGoBack(): boolean;
+  /** Set the current frame's wizard step. */
+  setStep(step: number): void;
+  /** Request dismissal of the whole surface, resolving its promise with `result`. */
+  requestDismiss(result?: unknown): void;
+  /** The current (top) frame. */
+  getTop(): NavFrame;
+}
+
+function makeFrame(route: RouteName, props?: Record<string, unknown>): NavFrame {
+  const resolved = props ?? {};
+  const step = typeof resolved.initialStep === 'number' ? resolved.initialStep : 0;
+  return { route, props: resolved, step };
+}
+
+export function createSurfaceNavStack(
+  route: RouteName,
+  props?: Record<string, unknown>,
+): SurfaceNavStack {
+  const store = createStore<NavStackState>(() => ({
+    frames: [makeFrame(route, props)],
+    closing: false,
+    closeResult: undefined,
+  }));
+
+  const getTop = (): NavFrame => {
+    const { frames } = store.getState();
+    return frames[frames.length - 1];
+  };
+
+  return {
+    store,
+    getTop,
+    navigate(nextRoute, nextProps) {
+      store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
+    },
+    replace(nextRoute, nextProps) {
+      store.setState((state) => ({
+        frames: [...state.frames.slice(0, -1), makeFrame(nextRoute, nextProps)],
+      }));
+    },
+    goBack() {
+      const { frames } = store.getState();
+      if (frames.length <= 1) return false;
+      store.setState({ frames: frames.slice(0, -1) });
+      return true;
+    },
+    canGoBack() {
+      const { frames } = store.getState();
+      return frames.length > 1 || (frames[frames.length - 1]?.step ?? 0) > 0;
+    },
+    setStep(step) {
+      store.setState((state) => {
+        const frames = state.frames.slice();
+        const index = frames.length - 1;
+        frames[index] = { ...frames[index], step };
+        return { frames };
+      });
+    },
+    requestDismiss(result) {
+      if (store.getState().closing) return;
+      store.setState({ closing: true, closeResult: result });
+    },
+  };
+}

package/src/ui/navigation/surfaceRegistry.ts

@@ -0,0 +1,240 @@
+import type { ReactNode } from 'react';
+import type { AccountDialogView, FileMetadata } from '@oxyhq/core';
+import type { RouteName } from './routes';
+import type { AvatarCropResult } from '../screens/AvatarCropScreen';
+
+/**
+ * The SDK's typed surface registry — the contract layer the SDK stacks on top of
+ * Bloom's content-agnostic surface stack (`@oxyhq/bloom/surfaces`). One entry per
+ * route describing its `props` (what the presenter must pass) and its `result`
+ * (what awaiting `present()` resolves with). Hand-maintained, contract-first:
+ * adding a route here is the single edit that types it end to end.
+ *
+ * For P1 most routes keep permissive `Record<string, unknown>` props + a `void`
+ * result — the historical grab-bag `showBottomSheet`/`navigate` props are
+ * unchanged. Later phases tighten individual routes without changing this shape.
+ */
+
+/** One registry entry: the props a route is presented with + its dismissal result. */
+type SurfaceRoute<Props = Record<string, unknown>, Result = void> = {
+  props: Props;
+  result: Result;
+};
+
+export interface SurfaceRegistry {
+  ManageAccount: SurfaceRoute;
+  AccountVerification: SurfaceRoute;
+  PaymentGateway: SurfaceRoute;
+  Profile: SurfaceRoute;
+  LanguageSelector: SurfaceRoute;
+  PrivacySettings: SurfaceRoute;
+  SearchSettings: SurfaceRoute;
+  /**
+   * File picker / manager. In single-select picker mode the surface is
+   * dismissed with the picked {@link FileMetadata} (the avatar-picker promise
+   * flow); legacy callers that pass an `onSelect`/`onConfirmSelection` callback
+   * keep their callback behaviour and this result goes unread.
+   */
+  FileManagement: SurfaceRoute<Record<string, unknown>, FileMetadata>;
+  HelpSupport: SurfaceRoute;
+  FAQ: SurfaceRoute;
+  Feedback: SurfaceRoute;
+  LegalDocuments: SurfaceRoute;
+  AppInfo: SurfaceRoute;
+  PremiumSubscription: SurfaceRoute;
+  WelcomeNewUser: SurfaceRoute;
+  UserLinks: SurfaceRoute;
+  HistoryView: SurfaceRoute;
+  SavesCollections: SurfaceRoute;
+  EditProfile: SurfaceRoute;
+  EditProfileField: SurfaceRoute;
+  LearnMoreUsernames: SurfaceRoute;
+  TrustCenter: SurfaceRoute;
+  TrustLeaderboard: SurfaceRoute;
+  TrustRewards: SurfaceRoute;
+  TrustRules: SurfaceRoute;
+  AboutTrust: SurfaceRoute;
+  TrustFAQ: SurfaceRoute;
+  FollowersList: SurfaceRoute;
+  FollowingList: SurfaceRoute;
+  CreateAccount: SurfaceRoute;
+  AccountMembers: SurfaceRoute;
+  AccountSettings: SurfaceRoute;
+  /** Square-crop editor. Dismissed with the cropped {@link AvatarCropResult}. */
+  AvatarCrop: SurfaceRoute<Record<string, unknown>, AvatarCropResult>;
+  Notifications: SurfaceRoute;
+  ConnectedApps: SurfaceRoute;
+  Preferences: SurfaceRoute;
+  /** Unified account switcher + sign-in surface (folded `OxyAccountDialogScreen` body). */
+  AccountDialog: SurfaceRoute<{ initialView?: AccountDialogView }>;
+}
+
+/**
+ * Compile-time guard: the registry keys must be EXACTLY the route names. If a new
+ * `RouteName` is added without a registry entry (or vice-versa) this alias
+ * resolves to `never` and the `satisfies` assertion below fails to type-check.
+ */
+type RegistryCoversRoutes = [RouteName] extends [keyof SurfaceRegistry]
+  ? [keyof SurfaceRegistry] extends [RouteName]
+    ? true
+    : never
+  : never;
+const _registryCoversRoutes: RegistryCoversRoutes = true;
+void _registryCoversRoutes;
+
+/** Typed props a route is presented with. */
+export type SurfaceProps<K extends RouteName> = SurfaceRegistry[K]['props'];
+/** What awaiting a route's `present()` resolves with when it is dismissed. */
+export type SurfaceResult<K extends RouteName> = SurfaceRegistry[K]['result'];
+
+/**
+ * How a surface renders — the SDK's presentation taxonomy. Each value maps to a
+ * concrete Bloom `Dialog` placement/chrome in `surfaces.ts`:
+ *
+ *   - `'sheet'`      → responsive `{ base: 'bottom', md: 'center' }` (the default:
+ *                      a bottom sheet on narrow viewports, a centered card on wide).
+ *   - `'center'`     → a plain centered modal at every width.
+ *   - `'drawer'`     → responsive `{ base: 'bottom', md: 'left' }` side drawer.
+ *   - `'fullScreen'` → approximated with the shared `Dialog`: a full-height sheet /
+ *                      large centered card, flush (`contentPadding: 0`) content, a
+ *                      black canvas and programmatic-only dismiss (the flagship
+ *                      image picker). A real Bloom `'fullScreen'` placement is a
+ *                      follow-up if the approximation reads wrong on device.
+ */
+export type SurfacePresentation = 'sheet' | 'center' | 'drawer' | 'fullScreen';
+
+/**
+ * Per-route surface configuration. Merges the historical `SheetRouteConfig`
+ * knobs with the new {@link SurfacePresentation}.
+ *
+ * NOTE: `scrollable` is LIVE — it is threaded through `bloomOptionsFor` onto the
+ * Bloom `Dialog` surface (`scrollable` prop), so a route that owns its own scroll
+ * container opts OUT of the Dialog's internal ScrollView. `manualActivation` /
+ * `dynamicBackdrop` / `handleComponent` remain informational — reserved for a
+ * future Bloom bottom-placement passthrough; the shared `DialogBottomSheet`
+ * currently owns pan coordination itself.
+ */
+export interface SurfaceRouteConfig {
+  /** Which surface hosts the route. */
+  presentation: SurfacePresentation;
+  /**
+   * When `false`, the route owns its own scroll container (a FlatList /
+   * SectionList / VirtualizedList, or its own ScrollView) and the host must not
+   * wrap it in a ScrollView. Threaded onto Bloom's `Dialog` via `bloomOptionsFor`.
+   */
+  scrollable: boolean;
+  /**
+   * Whether the surface renders the Dialog's OWN navigation header (sticky
+   * gradient nav bar + large collapsing title over the surface's scroll content).
+   * `true` for every route screen — screens render NO header of their own and
+   * declare their title/subtitle (+ any action slot) via `useSurfaceHeader`.
+   * `false` for surfaces with their own chrome (the account dialog, the flagship
+   * full-bleed image picker).
+   */
+  header: boolean;
+  /** Body-pan activation strategy — reserved (owned by Bloom's Dialog surface). */
+  manualActivation: boolean;
+  /** Drag-proportional backdrop dim — reserved (owned by Bloom's Dialog surface). */
+  dynamicBackdrop: boolean;
+  /** Optional custom drag-handle slot — reserved (owned by Bloom's Dialog surface). */
+  handleComponent?: () => ReactNode;
+}
+
+/** Defaults shared across all routes — the canonical responsive "sheet". */
+const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
+  presentation: 'sheet',
+  scrollable: true,
+  header: true,
+  manualActivation: true,
+  dynamicBackdrop: true,
+};
+
+/**
+ * Routes that render NO Dialog nav header — they own their chrome:
+ * - `AvatarCrop` — its own translucent Cancel / title / Done top bar.
+ * - `PaymentGateway` — the payment surface owns its controls.
+ * - `WelcomeNewUser` — a full-bleed onboarding wizard with its own step chrome.
+ * - `Profile` — a full profile view, no nav-header chrome.
+ * (The flagship full-bleed image picker is handled separately below.)
+ *
+ * `AccountDialog` used to be here — it now uses the SHARED Dialog nav header like
+ * every other screen (its per-view title/subtitle + view-back go through
+ * `useSurfaceHeader`), so the account/sign-in surface no longer feels bespoke.
+ */
+const HEADERLESS_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
+  'AvatarCrop',
+  'PaymentGateway',
+  'WelcomeNewUser',
+  'Profile',
+]);
+
+/**
+ * Predicate matching `FileManagementScreen`'s internal `isImageOnlyPicker`
+ * derivation. When the consumer restricts to image MIME types (no videos, no
+ * audio, no documents), FileManagement renders the flagship `PhotoPickerView`,
+ * which owns its own FlatList and reads best as a full-bleed picker. Kept in sync
+ * with `FileManagementScreen` — both check the same disabled MIME type families.
+ */
+const isFileManagementImageOnlyPicker = (props: Record<string, unknown>): boolean => {
+  if (!props.selectMode) return false;
+  const disabled = props.disabledMimeTypes;
+  if (!Array.isArray(disabled) || disabled.length === 0) return false;
+  const has = (predicate: (mt: string) => boolean): boolean =>
+    disabled.some((mt) => typeof mt === 'string' && predicate(mt));
+  const blocksVideos = has((mt) => mt === 'video/' || mt.startsWith('video/'));
+  const blocksAudio = has((mt) => mt === 'audio/' || mt.startsWith('audio/'));
+  const blocksDocs = has(
+    (mt) => mt === 'application/pdf' || mt === 'application/' || mt.startsWith('application/'),
+  );
+  return blocksVideos && blocksAudio && blocksDocs;
+};
+
+/**
+ * Routes whose screen owns its OWN scroll container — a FlatList /
+ * VirtualizedList (`ConnectedApps`, `TrustLeaderboard`, `FollowersList` /
+ * `FollowingList` via `UserListScreen`) or its own vertical `ScrollView`
+ * (`FileManagement`). These MUST opt out of the Dialog's internal ScrollView
+ * (`scrollable: false`) so there is exactly ONE scroll container — otherwise a
+ * VirtualizedList nests inside a plain ScrollView (RN warning) or a nested
+ * vertical scroll-in-scroll breaks windowing. Screens with only a HORIZONTAL
+ * ScrollView (FAQ's category row, Premium's plan carousel) are NOT listed — a
+ * horizontal scroller does not conflict with the Dialog's vertical scroll.
+ */
+const OWN_SCROLL_CONTAINER_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
+  'FileManagement',
+  'ConnectedApps',
+  'TrustLeaderboard',
+  'FollowersList',
+  'FollowingList',
+]);
+
+/**
+ * Resolve the surface configuration for a route + props. Defaults to the
+ * responsive sheet; the image-only FileManagement picker upgrades to a full-bleed
+ * `'fullScreen'` surface, and every route that owns its own scroll container is
+ * marked `scrollable: false`.
+ */
+export const getSurfaceConfig = (
+  route: RouteName,
+  props: Record<string, unknown>,
+): SurfaceRouteConfig => {
+  if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
+    // The full-bleed image picker owns its own translucent top bar — no nav header.
+    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false, header: false };
+  }
+  if (HEADERLESS_ROUTES.has(route)) {
+    return { ...DEFAULT_SURFACE_CONFIG, header: false };
+  }
+  if (OWN_SCROLL_CONTAINER_ROUTES.has(route)) {
+    // Own-scroller list screens keep the nav header (static, non-collapsing —
+    // there is no Dialog scroll offset to drive the large-title collapse).
+    return { ...DEFAULT_SURFACE_CONFIG, scrollable: false };
+  }
+  return DEFAULT_SURFACE_CONFIG;
+};
+
+/** Convenience: just the presentation taxonomy for a route + props. */
+export const getSurfacePresentation = (
+  route: RouteName,
+  props: Record<string, unknown>,
+): SurfacePresentation => getSurfaceConfig(route, props).presentation;