@oxyhq/services 22.8.7 → 22.9.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 (folded OxyAccountDialog 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
+    // `OxyAccountDialog` component (folded from the standalone dialog); the
+    // surface stack provides the Dialog chrome around it.
+    AccountDialog: () => require('../components/OxyAccountDialog').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/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,174 @@
+import type { ReactNode } from 'react';
+import type { AccountDialogView } from '@oxyhq/core';
+import type { RouteName } from './routes';
+
+/**
+ * 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;
+  FileManagement: SurfaceRoute;
+  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;
+  AvatarCrop: SurfaceRoute;
+  Notifications: SurfaceRoute;
+  ConnectedApps: SurfaceRoute;
+  Preferences: SurfaceRoute;
+  /** Unified account switcher + sign-in surface (folded `OxyAccountDialog` 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` / `manualActivation` / `dynamicBackdrop` / `handleComponent`
+ * describe the in-tree bottom-sheet's pan + scroll behaviour. On Bloom's `Dialog`
+ * surface those concerns are now owned by the shared `DialogBottomSheet` (it opts
+ * pure custom children OUT of its internal ScrollView and manages the pan itself),
+ * so for P1 these fields are informational — reserved for a future Bloom
+ * bottom-placement passthrough. `presentation` (+ `scrollable` for the picker's
+ * flush layout) is what actually drives the surface today.
+ */
+export interface SurfaceRouteConfig {
+  /** Which surface hosts the route. */
+  presentation: SurfacePresentation;
+  /**
+   * When `false`, the route owns its own scroll container (a FlatList /
+   * SectionList / VirtualizedList) and the host must not wrap it in a ScrollView.
+   */
+  scrollable: 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,
+  manualActivation: true,
+  dynamicBackdrop: true,
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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 that owns its own scrolling.
+ */
+export const getSurfaceConfig = (
+  route: RouteName,
+  props: Record<string, unknown>,
+): SurfaceRouteConfig => {
+  if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
+    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', 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;

package/src/ui/navigation/surfaces.ts

@@ -0,0 +1,244 @@
+import { createElement } from 'react';
+import type { ViewStyle } from 'react-native';
+import {
+  surfaces as bloomSurfaces,
+  type PresentOptions,
+  type SurfaceControls,
+} from '@oxyhq/bloom/surfaces';
+import SurfaceScreen from '../components/SurfaceScreen';
+import type { RouteName } from './routes';
+import {
+  getSurfaceConfig,
+  getSurfacePresentation,
+  type SurfacePresentation,
+  type SurfaceProps,
+  type SurfaceResult,
+  type SurfaceRouteConfig,
+} from './surfaceRegistry';
+import { createSurfaceNavStack, type SurfaceNavStack } from './surfaceNavStack';
+
+/**
+ * The SDK's typed surface API — a route registry layered on top of Bloom's
+ * content-agnostic surface stack (`@oxyhq/bloom/surfaces`).
+ *
+ * `present(route)` opens a NEW Bloom surface (the DEPTH axis) whose content is a
+ * {@link SurfaceScreen} driven by the route's own {@link SurfaceNavStack} (the
+ * NAV-WITHIN axis). Navigating within that surface mutates its nav stack and
+ * re-renders the SAME Bloom surface; presenting stacks another surface on top.
+ *
+ * Bloom coordinates z-order / backdrop / dismiss across every surface (SDK's and
+ * apps'), so nothing clashes.
+ */
+
+/** Responsive "sheet": bottom sheet on narrow, centered card on wide. */
+const SHEET_PLACEMENT = { base: 'bottom', md: 'center' } as const;
+
+/** Full-bleed black canvas for the `'fullScreen'` approximation (image picker). */
+const FULLSCREEN_SURFACE_STYLE: ViewStyle = { backgroundColor: '#000000', overflow: 'hidden' };
+
+/** Map a route's presentation taxonomy onto concrete Bloom `Dialog` options. */
+function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
+  switch (config.presentation) {
+    case 'center':
+      return { placement: 'center' };
+    case 'drawer':
+      return { placement: { base: 'bottom', md: 'left' } };
+    case 'fullScreen':
+      // Approximate a full-screen surface with the shared `Dialog`: a tall
+      // sheet / large centered card, flush content, a black canvas and
+      // programmatic-only dismiss — matching the shipped image-picker Dialog.
+      return {
+        placement: SHEET_PLACEMENT,
+        contentPadding: 0,
+        maxWidth: 640,
+        maxHeightRatio: 0.9,
+        dismissOnBackdrop: false,
+        style: FULLSCREEN_SURFACE_STYLE,
+        panelStyle: FULLSCREEN_SURFACE_STYLE,
+      };
+    default:
+      return { placement: SHEET_PLACEMENT };
+  }
+}
+
+/**
+ * A live handle to a presented SDK surface. Exposes DEPTH controls (`dismiss`,
+ * `result`) and NAV-WITHIN controls (`navigate`/`replace`/`goBack`/`setStep`) that
+ * drive this surface's own nav stack. Held by the `showBottomSheet` adapter (base
+ * surface) and by `OxyContext` (the AccountDialog surface).
+ */
+export interface SurfaceInstance<K extends RouteName = RouteName> {
+  readonly route: RouteName;
+  readonly presentation: SurfacePresentation;
+  navigate: (route: RouteName, props?: Record<string, unknown>) => void;
+  replace: (route: RouteName, props?: Record<string, unknown>) => void;
+  goBack: () => boolean;
+  canGoBack: () => boolean;
+  setStep: (step: number) => void;
+  dismiss: (result?: SurfaceResult<K>) => void;
+  readonly result: Promise<SurfaceResult<K> | undefined>;
+}
+
+/**
+ * The type-erased handle the `showBottomSheet` adapter needs from a tracked
+ * surface: what it hosts, and how to drive/dismiss it. Kept result-type-free so
+ * the (generic) `SurfaceInstance<K>` never has to be widened into a shared array.
+ */
+interface TrackedSurface {
+  readonly route: RouteName;
+  readonly presentation: SurfacePresentation;
+  navigate: (route: RouteName, props?: Record<string, unknown>) => void;
+  goBack: () => boolean;
+  dismiss: () => void;
+}
+
+/**
+ * Active SDK "route" surfaces (the `showBottomSheet` lineage), bottom → top.
+ * `present`/`presentRoute` register here; `presentDetached` (AccountDialog) does
+ * NOT, so the base-sheet navigation logic never treats the account modal as a
+ * navigable base. Entries self-remove when their surface is dismissed.
+ */
+const activeRouteSurfaces: TrackedSurface[] = [];
+
+function presentInternal<K extends RouteName>(
+  route: K,
+  props: Record<string, unknown>,
+  opts: PresentOptions | undefined,
+  track: boolean,
+): SurfaceInstance<K> {
+  const navStack = createSurfaceNavStack(route, props);
+  const config = getSurfaceConfig(route, props);
+  const bloomOpts: PresentOptions = { label: route, ...bloomOptionsFor(config), ...opts };
+
+  const result = bloomSurfaces.present<SurfaceResult<K>>((surface: SurfaceControls) =>
+    createElement(SurfaceScreen, { navStack, surface, presentation: config.presentation }),
+    bloomOpts,
+  );
+
+  const instance: SurfaceInstance<K> = {
+    route,
+    presentation: config.presentation,
+    navigate: (nextRoute, nextProps) => navStack.navigate(nextRoute, nextProps),
+    replace: (nextRoute, nextProps) => navStack.replace(nextRoute, nextProps),
+    goBack: () => navStack.goBack(),
+    canGoBack: () => navStack.canGoBack(),
+    setStep: (step) => navStack.setStep(step),
+    dismiss: (dismissResult) => navStack.requestDismiss(dismissResult),
+    result,
+  };
+
+  if (track) {
+    const tracked: TrackedSurface = {
+      route: instance.route,
+      presentation: instance.presentation,
+      navigate: instance.navigate,
+      goBack: instance.goBack,
+      dismiss: () => instance.dismiss(),
+    };
+    activeRouteSurfaces.push(tracked);
+    result.finally(() => {
+      const index = activeRouteSurfaces.indexOf(tracked);
+      if (index >= 0) activeRouteSurfaces.splice(index, 1);
+    });
+  }
+
+  return instance;
+}
+
+/**
+ * Present a NEW route surface on top of the stack (the DEPTH axis). Resolves with
+ * the value the surface is dismissed with. Registered in the route-surface stack.
+ */
+export function present<K extends RouteName>(
+  route: K,
+  props?: SurfaceProps<K>,
+  opts?: PresentOptions,
+): SurfaceInstance<K> {
+  return presentInternal(route, (props ?? {}) as Record<string, unknown>, opts, true);
+}
+
+/**
+ * Present a surface that is NOT part of the `showBottomSheet` base-navigation
+ * lineage (the AccountDialog modal). Otherwise identical to {@link present}.
+ */
+export function presentDetached<K extends RouteName>(
+  route: K,
+  props?: SurfaceProps<K>,
+  opts?: PresentOptions,
+): SurfaceInstance<K> {
+  return presentInternal(route, (props ?? {}) as Record<string, unknown>, opts, false);
+}
+
+/**
+ * Untyped present for the adapter, the nav helpers, and the `SurfaceScreen`
+ * binding (where the route is a runtime value and its props are already erased).
+ */
+export function presentRoute(route: RouteName, props?: Record<string, unknown>): SurfaceInstance {
+  return presentInternal(route, props ?? {}, undefined, true);
+}
+
+/** The top-most active route surface, or `undefined` when none are open. */
+export function topRouteSurface(): TrackedSurface | undefined {
+  return activeRouteSurfaces[activeRouteSurfaces.length - 1];
+}
+
+/**
+ * Dismiss every active route surface (the whole `showBottomSheet` session). The
+ * AccountDialog is untracked, so it is untouched. Iterates a snapshot because
+ * `dismiss` mutates `activeRouteSurfaces` asynchronously as surfaces settle.
+ */
+export function closeAllRouteSurfaces(): void {
+  for (const instance of [...activeRouteSurfaces].reverse()) instance.dismiss();
+}
+
+/**
+ * Drill in from a screen: navigate WITHIN the current surface when the target's
+ * presentation matches, else present the target as a NEW surface on top (so a
+ * sheet screen opening the full-bleed picker gets the right chrome).
+ */
+export function navigateWithinOrPresent(
+  currentPresentation: SurfacePresentation,
+  navStack: SurfaceNavStack,
+  route: RouteName,
+  props?: Record<string, unknown>,
+): void {
+  const nextProps = props ?? {};
+  if (getSurfacePresentation(route, nextProps) === currentPresentation) {
+    navStack.navigate(route, nextProps);
+  } else {
+    presentRoute(route, nextProps);
+  }
+}
+
+/** Replace variant of {@link navigateWithinOrPresent}. */
+export function replaceWithinOrPresent(
+  currentPresentation: SurfacePresentation,
+  navStack: SurfaceNavStack,
+  route: RouteName,
+  props?: Record<string, unknown>,
+): void {
+  const nextProps = props ?? {};
+  if (getSurfacePresentation(route, nextProps) === currentPresentation) {
+    navStack.replace(route, nextProps);
+  } else {
+    presentRoute(route, nextProps);
+  }
+}
+
+/**
+ * The SDK's imperative surface API (a module singleton). `present` is the typed
+ * route presenter; `dismissAll` unwinds the whole session. Not yet exported from
+ * the package root — the public `surfaces`/`useSurfaces` API lands in a later
+ * phase; for P1 the internal adapters (`showBottomSheet`, `openAccountDialog`)
+ * are the only public entry points.
+ */
+export const surfaces = {
+  present: <K extends RouteName>(route: K, props?: SurfaceProps<K>, opts?: PresentOptions) =>
+    present(route, props, opts).result,
+  dismissAll: closeAllRouteSurfaces,
+} as const;
+
+/** Hook form of {@link surfaces} (stable singleton). */
+export function useSurfaces(): typeof surfaces {
+  return surfaces;
+}