@oxyhq/services 22.9.0 → 22.11.0

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', () => {

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

@@ -0,0 +1,149 @@
+import { createSurfaceNavStack } from '../surfaceNavStack';
+import { __resetSurfaceBackBridgeForTests, pushSurfaceBackHandler, __invokeTopSurfaceBackForTests } from '../surfaceBackBridge';
+
+describe('createSurfaceNavStack', () => {
+  it('starts with a single root frame', () => {
+    const stack = createSurfaceNavStack('ManageAccount', { foo: 1 });
+    expect(stack.getTop().route).toBe('ManageAccount');
+    expect(stack.getTop().props).toEqual({ foo: 1 });
+    expect(stack.canGoBack()).toBe(false);
+  });
+
+  it('navigate pushes frames and goBack pops them', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.navigate('EditProfile', { userId: 'u1' });
+    expect(stack.getTop().route).toBe('EditProfile');
+    expect(stack.canGoBack()).toBe(true);
+    expect(stack.goBack()).toBe(true);
+    expect(stack.getTop().route).toBe('ManageAccount');
+    expect(stack.goBack()).toBe(false);
+  });
+
+  it('replace swaps the top frame without growing history', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.navigate('EditProfile');
+    stack.replace('PrivacySettings');
+    expect(stack.getTop().route).toBe('PrivacySettings');
+    expect(stack.goBack()).toBe(true);
+    expect(stack.getTop().route).toBe('ManageAccount');
+  });
+
+  it('tracks wizard steps on the current frame', () => {
+    const stack = createSurfaceNavStack('EditProfile', { initialStep: 2 });
+    expect(stack.getTop().step).toBe(2);
+    expect(stack.canGoBack()).toBe(true);
+    stack.setStep(1);
+    expect(stack.getTop().step).toBe(1);
+  });
+
+  it('requestDismiss flips closing once', () => {
+    const stack = createSurfaceNavStack('ManageAccount');
+    stack.requestDismiss('done');
+    expect(stack.store.getState().closing).toBe(true);
+    expect(stack.store.getState().closeResult).toBe('done');
+    stack.requestDismiss('again');
+    expect(stack.store.getState().closeResult).toBe('done');
+  });
+
+  describe('result-bearing sub-flow (morphed-in avatar picker)', () => {
+    it('resolves with the descendant dismiss result and pops back to the caller frame', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      // Drill into the crop editor within the flow, then confirm.
+      stack.navigate('AvatarCrop', { imageUri: 'file:///x.jpg' });
+      stack.resolveFlowOrDismiss({ uri: 'file:///cropped.jpg' });
+      await expect(flow).resolves.toEqual({ uri: 'file:///cropped.jpg' });
+      // Popped back to the frame that started the flow — surface NOT dismissed.
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    it('resolves undefined when the flow entry frame is backed out of', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.navigate('AvatarCrop');
+      expect(stack.goBack()).toBe(true); // crop -> list (still in flow)
+      expect(stack.goBack()).toBe(true); // list -> EditProfile (cancels flow)
+      await expect(flow).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    it('resolveFlowOrDismiss with NO active flow dismisses the surface (cold present)', () => {
+      const stack = createSurfaceNavStack('ChangeAvatar');
+      stack.resolveFlowOrDismiss({ removed: true });
+      expect(stack.store.getState().closing).toBe(true);
+      expect(stack.store.getState().closeResult).toEqual({ removed: true });
+    });
+
+    it('abandons a pending flow (undefined) when the surface is torn down', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.abandonActiveFlow();
+      await expect(flow).resolves.toBeUndefined();
+    });
+
+    it('NESTS flows: the inner selector resolves first, then the outer avatar flow', async () => {
+      // ChangeAvatar (outer) → "My Oxy files" FileManagement (inner) → back → crop.
+      const stack = createSurfaceNavStack('EditProfile');
+      const avatarFlow = stack.beginFlow('ChangeAvatar');
+      const fileFlow = stack.beginFlow('FileManagement');
+      expect(stack.getTop().route).toBe('FileManagement');
+      // Pick a file → inner flow resolves, pops back to ChangeAvatar (outer still open).
+      stack.resolveFlowOrDismiss({ id: 'file-1' });
+      await expect(fileFlow).resolves.toEqual({ id: 'file-1' });
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      expect(stack.store.getState().closing).toBe(false);
+      // Now drill to crop and confirm → outer flow resolves, pops to EditProfile.
+      stack.navigate('AvatarCrop');
+      stack.resolveFlowOrDismiss({ uri: 'file:///c.jpg' });
+      await expect(avatarFlow).resolves.toEqual({ uri: 'file:///c.jpg' });
+      expect(stack.getTop().route).toBe('EditProfile');
+    });
+
+    it('cancelling the inner selector returns to the outer flow, leaving it open', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const avatarFlow = stack.beginFlow('ChangeAvatar');
+      const fileFlow = stack.beginFlow('FileManagement');
+      expect(stack.goBack()).toBe(true); // FileManagement -> ChangeAvatar (cancels inner)
+      await expect(fileFlow).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      // The outer avatar flow is still pending.
+      let outerSettled = false;
+      void avatarFlow.then(() => { outerSettled = true; });
+      await Promise.resolve();
+      expect(outerSettled).toBe(false);
+    });
+
+    it('tearing down the surface abandons ALL nested flows (undefined)', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const outer = stack.beginFlow('ChangeAvatar');
+      const inner = stack.beginFlow('FileManagement');
+      stack.abandonActiveFlow();
+      await expect(inner).resolves.toBeUndefined();
+      await expect(outer).resolves.toBeUndefined();
+    });
+  });
+});
+
+describe('pushSurfaceBackHandler', () => {
+  afterEach(() => {
+    __resetSurfaceBackBridgeForTests();
+  });
+
+  it('delegates to the topmost handler', () => {
+    const calls: string[] = [];
+    pushSurfaceBackHandler(() => {
+      calls.push('bottom');
+      return true;
+    });
+    pushSurfaceBackHandler(() => {
+      calls.push('top');
+      return true;
+    });
+
+    expect(__invokeTopSurfaceBackForTests()).toBe(true);
+    expect(calls).toEqual(['top']);
+  });
+});

package/src/ui/navigation/accountDialogManager.ts

@@ -1,16 +1,40 @@
 /**
- * Imperative controls for the unified {@link OxyAccountDialog}.
+ * Imperative, outside-React entry points for the unified `OxyAccountDialogScreen`.
+ *
+ * These delegate to the live handles the mounted `OxyProvider` registers via
+ * {@link registerAccountDialogControls}. Under the hood `open`/`close` present
+ * and dismiss the `AccountDialog` surface on the shared Bloom surface stack
+ * (`OxyContext.openAccountDialog` → `presentDetached('AccountDialog', …)`), so
+ * whether the dialog is open is owned by that stack — this module is only the
+ * thin bridge that reaches the provider's controller (which sets the dialog
+ * view) from a non-React call site.
  */
 
 import type { AccountDialogView } from '@oxyhq/core';
 
-/** Live open/close handles registered by the mounted provider. */
+/**
+ * Live open/close handles registered by the mounted provider. `open` presents
+ * the `AccountDialog` surface (and points its view); `close` dismisses it. Both
+ * are stack operations — this interface never carries visibility state.
+ */
 export interface AccountDialogControls {
   open: (view?: AccountDialogView) => void;
   close: () => void;
 }
 
+/**
+ * Optional consumer overrides for account-dialog actions. `ProfileButton` (and
+ * similar hosts) register these while mounted so inbox/accounts can route
+ * "Manage" / "Add account" to app-local navigation instead of the SDK default.
+ */
+export interface AccountDialogConsumerHooks {
+  onNavigateManage?: () => void;
+  onAddAccount?: () => void;
+  onNavigateProfile?: () => void;
+}
+
 let controls: AccountDialogControls | null = null;
+let consumerHooks: AccountDialogConsumerHooks | null = null;
 const visibilityListeners = new Set<(visible: boolean) => void>();
 
 export function registerAccountDialogControls(next: AccountDialogControls): () => void {
@@ -22,6 +46,22 @@ export function registerAccountDialogControls(next: AccountDialogControls): () =
   };
 }
 
+/** Register app-local manage/add/profile handlers for the account dialog. */
+export function registerAccountDialogConsumerHooks(
+  next: AccountDialogConsumerHooks | null,
+): () => void {
+  consumerHooks = next;
+  return () => {
+    if (consumerHooks === next) {
+      consumerHooks = null;
+    }
+  };
+}
+
+export function getAccountDialogConsumerHooks(): AccountDialogConsumerHooks | null {
+  return consumerHooks;
+}
+
 /** Open the account dialog on `view` (default `accounts`). No-op before mount. */
 export function openAccountDialog(view?: AccountDialogView): void {
   controls?.open(view);

package/src/ui/navigation/bottomSheetManager.ts

@@ -1,6 +1,6 @@
 import type { RouteName } from './routes';
 import { isValidRoute } from './routes';
-import { getSurfacePresentation } from './surfaceRegistry';
+import { getSurfaceConfig } from './surfaceRegistry';
 import { closeAllRouteSurfaces, presentRoute, topRouteSurface } from './surfaces';
 
 /**
@@ -16,11 +16,10 @@ import { closeAllRouteSurfaces, presentRoute, topRouteSurface } from './surfaces
  */
 
 /**
- * Open a bottom-sheet route. If the top-most active surface hosts the SAME
- * presentation (the common all-sheets case) the route is drilled into it; a route
- * with a different presentation (the image picker's full-bleed surface) is
- * presented as a NEW surface on top. Opening with no active surface presents the
- * first one.
+ * Open a bottom-sheet route. By DEFAULT it drills into the top-most active
+ * surface — morphing it in place (every screen morphs). A NEW surface is stacked
+ * on top only when the target route declares `stacks` (reserved for genuine
+ * overlays — none today). Opening with no active surface presents the first one.
  *
  * `fullScreen` is accepted for signature compatibility and ignored — a route's
  * surface is now derived from its registry config, not a per-call flag.
@@ -39,7 +38,7 @@ export const showBottomSheet = (
   }
 
   const top = topRouteSurface();
-  if (top && top.presentation === getSurfacePresentation(screen, props)) {
+  if (top && !getSurfaceConfig(screen, props).stacks) {
     top.navigate(screen, props);
   } else {
     presentRoute(screen, props);

package/src/ui/navigation/routes.ts

@@ -39,11 +39,12 @@ export type RouteName =
     | 'CreateAccount' // Create a new account (organization / project / bot)
     | 'AccountMembers' // Manage an account's members (invite / roles / transfer)
     | 'AccountSettings' // Per-account profile edit + members + danger zone
-    | 'AvatarCrop' // Square-crop editor presented before avatar upload
+    | 'ChangeAvatar' // Profile-picture source list — the ONE entry into changing an avatar
+    | 'AvatarCrop' // Square-crop editor, reached by navigating within the ChangeAvatar surface
     | 'Notifications' // Per-channel notification preferences
     | 'ConnectedApps' // OAuth-authorized third-party apps the user can revoke
     | 'Preferences' // General user preferences (theme, reduce-motion, etc.)
-    | 'AccountDialog'; // Unified account switcher + sign-in surface (folded OxyAccountDialog body)
+    | '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
@@ -83,14 +84,15 @@ const screenLoaders: Record<RouteName, () => ComponentType<BaseScreenProps>> = {
     CreateAccount: () => require('../screens/CreateAccountScreen').default,
     AccountMembers: () => require('../screens/AccountMembersScreen').default,
     AccountSettings: () => require('../screens/AccountSettingsScreen').default,
+    ChangeAvatar: () => require('../screens/ChangeAvatarScreen').default,
     AvatarCrop: () => require('../screens/AvatarCropScreen').default,
     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
+    // `OxyAccountDialogScreen` component (folded from the standalone dialog); the
     // surface stack provides the Dialog chrome around it.
-    AccountDialog: () => require('../components/OxyAccountDialog').default,
+    AccountDialog: () => require('../components/OxyAccountDialogScreen').default,
 };
 
 // Cache loaded components to avoid re-requiring

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

@@ -48,6 +48,27 @@ export interface SurfaceNavStack {
   setStep(step: number): void;
   /** Request dismissal of the whole surface, resolving its promise with `result`. */
   requestDismiss(result?: unknown): void;
+  /**
+   * Begin a result-bearing SUB-FLOW inside this surface: push `route` as a frame
+   * and return a promise that settles when the flow finishes — a descendant's
+   * `dismiss(result)` resolves it with `result`, backing out of the flow's entry
+   * frame resolves it with `undefined` (cancelled) — popping the surface back to
+   * the frame that started the flow WITHOUT dismissing it. This is how a screen
+   * already living inside a surface (EditProfile, ManageAccount, ChangeAvatar)
+   * opens the avatar picker / media selector as a MORPH instead of a stacked
+   * surface while still awaiting its result. Flows NEST (ChangeAvatar → the "My
+   * Oxy files" selector → back), maintained as a stack.
+   */
+  beginFlow(route: RouteName, props?: Record<string, unknown>): Promise<unknown>;
+  /**
+   * Resolve the INNERMOST active sub-flow with `result` and pop back to its entry
+   * (the frame that called {@link beginFlow}), leaving the surface open. With NO
+   * active flow this falls back to {@link requestDismiss} — so a screen presented
+   * as its OWN surface still dismisses it. Wired to every screen's `dismiss` prop.
+   */
+  resolveFlowOrDismiss(result?: unknown): void;
+  /** Settle EVERY still-pending sub-flow with `undefined` (the surface is going away). */
+  abandonActiveFlow(): void;
   /** The current (top) frame. */
   getTop(): NavFrame;
 }
@@ -73,9 +94,41 @@ export function createSurfaceNavStack(
     return frames[frames.length - 1];
   };
 
+  // Result-bearing sub-flows currently running in this surface (the morphed-in
+  // avatar picker, and — NESTED within it — the "My Oxy files" media selector).
+  // A STACK: flows nest (ChangeAvatar → FileManagement → back to ChangeAvatar).
+  // Held OUTSIDE the store (resolvers are functions; flow presence must not
+  // re-render frames). Each flow's `returnLength` is the frame count BEFORE its
+  // entry frame was pushed, so settling pops back to exactly the frame that
+  // started it. `flowStack` is ordered outer → inner; the top is the innermost.
+  const flowStack: { returnLength: number; resolve: (result: unknown) => void }[] = [];
+
+  const requestDismiss = (result?: unknown): void => {
+    // Dismissing the whole surface abandons EVERY pending sub-flow — settle each
+    // promise so an awaiting caller (the avatar picker) never hangs.
+    while (flowStack.length) flowStack.pop()?.resolve(undefined);
+    if (store.getState().closing) return;
+    store.setState({ closing: true, closeResult: result });
+  };
+
+  const goBack = (): boolean => {
+    const { frames } = store.getState();
+    if (frames.length <= 1) return false;
+    const nextLength = frames.length - 1;
+    store.setState({ frames: frames.slice(0, -1) });
+    // Backing out past a sub-flow's entry frame cancels it (resolve undefined).
+    // A single pop crosses at most one boundary, but loop for safety.
+    while (flowStack.length && nextLength <= flowStack[flowStack.length - 1].returnLength) {
+      flowStack.pop()?.resolve(undefined);
+    }
+    return true;
+  };
+
   return {
     store,
     getTop,
+    requestDismiss,
+    goBack,
     navigate(nextRoute, nextProps) {
       store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
     },
@@ -84,12 +137,6 @@ export function createSurfaceNavStack(
         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;
@@ -102,9 +149,25 @@ export function createSurfaceNavStack(
         return { frames };
       });
     },
-    requestDismiss(result) {
-      if (store.getState().closing) return;
-      store.setState({ closing: true, closeResult: result });
+    beginFlow(nextRoute, nextProps) {
+      const returnLength = store.getState().frames.length;
+      store.setState((state) => ({ frames: [...state.frames, makeFrame(nextRoute, nextProps)] }));
+      return new Promise<unknown>((resolve) => {
+        flowStack.push({ returnLength, resolve });
+      });
+    },
+    resolveFlowOrDismiss(result) {
+      const flow = flowStack.pop();
+      if (!flow) {
+        // No flow → this screen owns its surface; dismiss it as before.
+        requestDismiss(result);
+        return;
+      }
+      store.setState((state) => ({ frames: state.frames.slice(0, flow.returnLength) }));
+      flow.resolve(result);
+    },
+    abandonActiveFlow() {
+      while (flowStack.length) flowStack.pop()?.resolve(undefined);
     },
   };
 }