@oxyhq/services 22.9.0 → 22.11.0

package/src/ui/navigation/surfaceRegistry.ts

@@ -1,6 +1,8 @@
 import type { ReactNode } from 'react';
-import type { AccountDialogView } from '@oxyhq/core';
+import type { AccountDialogView, FileMetadata } from '@oxyhq/core';
 import type { RouteName } from './routes';
+import type { AvatarCropResult } from '../screens/AvatarCropScreen';
+import type { AvatarRemovalResult } from '../screens/ChangeAvatarScreen';
 
 /**
  * The SDK's typed surface registry — the contract layer the SDK stacks on top of
@@ -28,7 +30,13 @@ export interface SurfaceRegistry {
   LanguageSelector: SurfaceRoute;
   PrivacySettings: SurfaceRoute;
   SearchSettings: SurfaceRoute;
-  FileManagement: 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;
@@ -53,11 +61,22 @@ export interface SurfaceRegistry {
   CreateAccount: SurfaceRoute;
   AccountMembers: SurfaceRoute;
   AccountSettings: SurfaceRoute;
-  AvatarCrop: SurfaceRoute;
+  /**
+   * Profile-picture source list — the ONE entry into changing an avatar. Every
+   * source that yields an image navigates WITHIN this surface to `AvatarCrop`
+   * (so the panel morphs), and the crop's own dismissal resolves this surface.
+   * Hence the union: a confirmed crop, or the user removing their photo.
+   */
+  ChangeAvatar: SurfaceRoute<Record<string, unknown>, AvatarCropResult | AvatarRemovalResult>;
+  /**
+   * Square-crop editor. Dismissed with the cropped {@link AvatarCropResult}.
+   * Reached only by navigating within a `ChangeAvatar` surface.
+   */
+  AvatarCrop: SurfaceRoute<Record<string, unknown>, AvatarCropResult>;
   Notifications: SurfaceRoute;
   ConnectedApps: SurfaceRoute;
   Preferences: SurfaceRoute;
-  /** Unified account switcher + sign-in surface (folded `OxyAccountDialog` body). */
+  /** Unified account switcher + sign-in surface (folded `OxyAccountDialogScreen` body). */
   AccountDialog: SurfaceRoute<{ initialView?: AccountDialogView }>;
 }
 
@@ -83,15 +102,18 @@ 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.
+ *   - `'sheet'`      → responsive `{ base: 'bottom', md: 'center' }` (the default,
+ *                      and — since every screen morphs — the presentation of EVERY
+ *                      route today: a bottom sheet on narrow, a centered card wide).
+ *   - `'center'`     → a plain centered modal at every width. Currently unused.
  *   - `'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.
+ *                      Currently unused.
+ *   - `'fullScreen'` → a flush black-canvas surface (`contentPadding: 0`,
+ *                      programmatic-only dismiss). Currently unused: the flagship
+ *                      photo picker now MORPHS in place as a `sheet` (it paints its
+ *                      own black canvas + bar inside the themed panel), so nothing
+ *                      needs a stacked full-bleed surface. Retained for a future
+ *                      route that genuinely must be full-bleed.
  */
 export type SurfacePresentation = 'sheet' | 'center' | 'drawer' | 'fullScreen';
 
@@ -99,22 +121,72 @@ 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.
+ * 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) and the host must not wrap it in a ScrollView.
+   * 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 MORPHS when this route is navigated to WITHIN it — the
+   * panel animates from the outgoing frame's size to this one's instead of
+   * hard-cutting (the in-place NAV-WITHIN size animation). `true` for every
+   * ordinary route screen; a wizard step swap counts as a frame here too.
+   *
+   * Distinct from {@link stacks}: `morph` tunes the size animation of an IN-PLACE
+   * frame swap; `stacks` decides whether the frame lands in place at all or opens
+   * a new surface. A stacked surface can still morph between ITS OWN frames.
+   */
+  morph: boolean;
+  /**
+   * An EXPLICIT target size the panel MORPHS to for this route, instead of the
+   * measured natural height / the surface width. This is how an own-scroller frame
+   * (its content owns its own scroll, so the panel can't measure it) still GROWS
+   * its container to a large declared size — the panel animates UP to it on entry
+   * and back DOWN on exit while the frame's inner list scrolls within. `heightRatio`
+   * is a fraction of the viewport height (clamped there); `maxWidth` (px) widens the
+   * centered card beyond the ordinary sheet. Omit for the normal measured behaviour.
+   */
+  frameSize?: { heightRatio?: number; maxWidth?: number };
+  /**
+   * Whether navigating TO this route from INSIDE an existing surface opens a NEW
+   * stacked surface (its own backdrop + entry animation — the DEPTH axis) instead
+   * of morphing in place within the current one (the NAV-WITHIN axis).
+   *
+   * `false` (the DEFAULT) — morph in place: the route is pushed as a frame in the
+   * host surface's nav stack and the panel reshapes from the previous frame to it
+   * (size-animated per {@link morph}). Every ordinary screen. This is what makes
+   * morph the default: a drill-in navigates WITHIN unless the target opts out.
+   *
+   * `true` — the route's chrome is fundamentally incompatible with morphing into
+   * a host, so it must own its own surface: the full-bleed `fullScreen` image
+   * picker (black canvas, flush content, programmatic-only dismiss). Presented on
+   * top; dismissing it unwinds back to the surface that opened it.
+   *
+   * NOTE: the DEPTH `present` / `presentDetached` APIs ALWAYS open a new surface
+   * regardless of this flag — `stacks` only governs the in-surface drill-in
+   * (`navigate` / `showBottomSheet`) decision in `navigateWithinOrPresent`.
+   */
+  stacks: 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). */
@@ -127,10 +199,37 @@ export interface SurfaceRouteConfig {
 const DEFAULT_SURFACE_CONFIG: SurfaceRouteConfig = {
   presentation: 'sheet',
   scrollable: true,
+  header: true,
+  morph: true,
+  stacks: false,
   manualActivation: true,
   dynamicBackdrop: true,
 };
 
+/**
+ * Routes that render NO Dialog nav header — they own their chrome:
+ * - `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.
+ *
+ * `AvatarCrop` used to be here too, for its own translucent Cancel/title/Done
+ * bar. It is now reached ONLY by navigating within a `ChangeAvatar` surface, and
+ * the Dialog's `header` is fixed for a surface's whole life — a headerless frame
+ * inside a header-mode surface would stack two bars. So the crop declares its
+ * title + its "Use photo" action through `useSurfaceHeader` like every other
+ * screen, and keeps only its dark crop stage.
+ */
+const HEADERLESS_ROUTES: ReadonlySet<RouteName> = new Set<RouteName>([
+  'PaymentGateway',
+  'WelcomeNewUser',
+  'Profile',
+]);
+
 /**
  * Predicate matching `FileManagementScreen`'s internal `isImageOnlyPicker`
  * derivation. When the consumer restricts to image MIME types (no videos, no
@@ -153,16 +252,57 @@ const isFileManagementImageOnlyPicker = (props: Record<string, unknown>): boolea
 };
 
 /**
- * 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.
+ * 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. Every route defaults to
+ * the responsive sheet and MORPHS in place when navigated to from within a surface
+ * (no route stacks — genuine overlays are Bloom-raw `surfaces.present`/`confirm`
+ * calls, outside this registry). The image-only FileManagement picker is a normal
+ * sheet that owns its own scroll + translucent bar (no Dialog nav header); every
+ * other own-scroller is marked `scrollable: false`.
  */
 export const getSurfaceConfig = (
   route: RouteName,
   props: Record<string, unknown>,
 ): SurfaceRouteConfig => {
   if (route === 'FileManagement' && isFileManagementImageOnlyPicker(props)) {
-    return { ...DEFAULT_SURFACE_CONFIG, presentation: 'fullScreen', scrollable: false };
+    // The flagship photo picker MORPHS in place like every other screen. It is an
+    // own-scroller (`PhotoPickerView`'s FlatList) that paints its OWN full-bleed
+    // black canvas + translucent top bar INSIDE the themed panel, so it takes no
+    // Dialog nav header. It needs ROOM for the photo grid, so it declares an
+    // explicit LARGE morph target — the panel grows UP to a near-full-height,
+    // wider card on entry (and back down on pick→crop), the grid scrolling within.
+    return {
+      ...DEFAULT_SURFACE_CONFIG,
+      scrollable: false,
+      header: false,
+      frameSize: { heightRatio: 0.9, maxWidth: 640 },
+    };
+  }
+  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;
 };

package/src/ui/navigation/surfaces.ts

@@ -9,8 +9,6 @@ import SurfaceScreen from '../components/SurfaceScreen';
 import type { RouteName } from './routes';
 import {
   getSurfaceConfig,
-  getSurfacePresentation,
-  type SurfacePresentation,
   type SurfaceProps,
   type SurfaceResult,
   type SurfaceRouteConfig,
@@ -36,13 +34,42 @@ 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' };
 
+/**
+ * Every SDK screen owns its own background + content padding + scroll region
+ * (they were authored for the bare `BottomSheet`). So the shared `Dialog` must
+ * NOT add its own `contentPadding` on top (that double-pads) — it owns only the
+ * structural chrome: the surface card, the size cap (`maxHeightRatio`) and the
+ * scroll boundary. `contentPadding: 0` makes the screen's own padding the single
+ * source, matching the image-picker (`fullScreen`) surface.
+ */
+const SDK_SURFACE_CHROME = { contentPadding: 0, maxHeightRatio: 0.9 } as const;
+
 /** Map a route's presentation taxonomy onto concrete Bloom `Dialog` options. */
 function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
+  // Threaded onto every placement so a route that owns its own scroll container
+  // (`scrollable: false`) opts out of the Dialog's internal ScrollView.
+  const scrollable = config.scrollable;
+  // Surface-level morph opt-out (the DEPTH axis is untouched — this only governs
+  // whether the panel reshapes when the content is swapped in place). Each frame
+  // additionally declares its own opt-out through `useDialogFrame` in
+  // `SurfaceScreen`, so a surface can morph for most routes and not for one.
+  const morph = config.morph;
+  // Nav-header mode marker: turns on the Dialog's OWN sticky gradient nav bar +
+  // large collapsing title over its scroll content. The title/subtitle/action
+  // slots are contributed at runtime by the mounted screen via `useSurfaceHeader`
+  // (resolved in `SurfaceScreen`), so the seed here just enables the scaffold.
+  const header = config.header ? { largeTitle: true } : undefined;
   switch (config.presentation) {
     case 'center':
-      return { placement: 'center' };
+      return { placement: 'center', scrollable, header, morph, ...SDK_SURFACE_CHROME };
     case 'drawer':
-      return { placement: { base: 'bottom', md: 'left' } };
+      return {
+        placement: { base: 'bottom', md: 'left' },
+        scrollable,
+        header,
+        morph,
+        ...SDK_SURFACE_CHROME,
+      };
     case 'fullScreen':
       // Approximate a full-screen surface with the shared `Dialog`: a tall
       // sheet / large centered card, flush content, a black canvas and
@@ -53,11 +80,13 @@ function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
         maxWidth: 640,
         maxHeightRatio: 0.9,
         dismissOnBackdrop: false,
+        scrollable,
+        morph,
         style: FULLSCREEN_SURFACE_STYLE,
         panelStyle: FULLSCREEN_SURFACE_STYLE,
       };
     default:
-      return { placement: SHEET_PLACEMENT };
+      return { placement: SHEET_PLACEMENT, scrollable, header, morph, ...SDK_SURFACE_CHROME };
   }
 }
 
@@ -69,12 +98,13 @@ function bloomOptionsFor(config: SurfaceRouteConfig): PresentOptions {
  */
 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;
+  /** Open a result-bearing sub-flow WITHIN this surface (morph). See {@link openWithinOrPresent}. */
+  beginFlow: (route: RouteName, props?: Record<string, unknown>) => Promise<unknown>;
   dismiss: (result?: SurfaceResult<K>) => void;
   readonly result: Promise<SurfaceResult<K> | undefined>;
 }
@@ -83,12 +113,15 @@ export interface SurfaceInstance<K extends RouteName = RouteName> {
  * 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.
+ * Exported so `OxyContext` can hold the surface it MORPHS the account dialog into
+ * (see {@link topRouteSurface}).
  */
-interface TrackedSurface {
+export interface TrackedSurface {
   readonly route: RouteName;
-  readonly presentation: SurfacePresentation;
   navigate: (route: RouteName, props?: Record<string, unknown>) => void;
   goBack: () => boolean;
+  /** Open a result-bearing sub-flow WITHIN this surface (morph). See {@link openWithinOrPresent}. */
+  beginFlow: (route: RouteName, props?: Record<string, unknown>) => Promise<unknown>;
   dismiss: () => void;
 }
 
@@ -100,6 +133,17 @@ interface TrackedSurface {
  */
 const activeRouteSurfaces: TrackedSurface[] = [];
 
+/**
+ * The frontmost DETACHED surface (the AccountDialog), while open. Detached
+ * surfaces are kept OUT of `activeRouteSurfaces` so `closeAllRouteSurfaces` never
+ * touches them — but the AccountDialog IS a valid morph target: a result-bearing
+ * flow opened from within it (the account-menu hero avatar → `ChangeAvatar`) must
+ * morph INTO it, not stack a new surface behind it. Invariant: whenever set, this
+ * surface is frontmost — every account-menu action that opens a tracked surface
+ * (Manage, Help, …) dismisses the dialog FIRST, so the two never overlap.
+ */
+let detachedFrontSurface: TrackedSurface | null = null;
+
 function presentInternal<K extends RouteName>(
   route: K,
   props: Record<string, unknown>,
@@ -111,35 +155,55 @@ function presentInternal<K extends RouteName>(
   const bloomOpts: PresentOptions = { label: route, ...bloomOptionsFor(config), ...opts };
 
   const result = bloomSurfaces.present<SurfaceResult<K>>((surface: SurfaceControls) =>
-    createElement(SurfaceScreen, { navStack, surface, presentation: config.presentation }),
+    createElement(SurfaceScreen, {
+      navStack,
+      surface,
+      dismissOnBackdrop: bloomOpts.dismissOnBackdrop ?? true,
+    }),
     bloomOpts,
   );
 
   const instance: SurfaceInstance<K> = {
     route,
-    presentation: config.presentation,
-    navigate: (nextRoute, nextProps) => navStack.navigate(nextRoute, nextProps),
+    navigate: (nextRoute, nextProps) => {
+      const top = navStack.getTop();
+      if (top.route === nextRoute) navStack.replace(nextRoute, nextProps);
+      else navStack.navigate(nextRoute, nextProps);
+    },
     replace: (nextRoute, nextProps) => navStack.replace(nextRoute, nextProps),
     goBack: () => navStack.goBack(),
     canGoBack: () => navStack.canGoBack(),
     setStep: (step) => navStack.setStep(step),
+    beginFlow: (nextRoute, nextProps) => navStack.beginFlow(nextRoute, nextProps),
     dismiss: (dismissResult) => navStack.requestDismiss(dismissResult),
     result,
   };
 
+  // If the surface is torn down (backdrop, `closeAll`, host unmount) while a
+  // result-bearing sub-flow is still open, settle that flow so an awaiting caller
+  // never hangs. Runs for tracked and detached surfaces alike.
+  result.finally(() => navStack.abandonActiveFlow());
+
+  const tracked: TrackedSurface = {
+    route: instance.route,
+    navigate: instance.navigate,
+    goBack: instance.goBack,
+    beginFlow: instance.beginFlow,
+    dismiss: () => instance.dismiss(),
+  };
   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);
     });
+  } else {
+    // Detached (the AccountDialog): NOT in the closeAll lineage, but recorded as
+    // the frontmost morph target so a flow opened from within it morphs IN.
+    detachedFrontSurface = tracked;
+    result.finally(() => {
+      if (detachedFrontSurface === tracked) detachedFrontSurface = null;
+    });
   }
 
   return instance;
@@ -182,6 +246,16 @@ export function topRouteSurface(): TrackedSurface | undefined {
   return activeRouteSurfaces[activeRouteSurfaces.length - 1];
 }
 
+/**
+ * The frontmost surface a result-bearing flow should morph INTO: the detached
+ * AccountDialog if open (it sits on top of everything), else the top tracked
+ * route surface. Used by {@link openWithinOrPresent} so the account-menu hero
+ * avatar morphs the dialog into `ChangeAvatar` instead of stacking a new surface.
+ */
+export function topMorphableSurface(): TrackedSurface | undefined {
+  return detachedFrontSurface ?? topRouteSurface();
+}
+
 /**
  * Dismiss every active route surface (the whole `showBottomSheet` session). The
  * AccountDialog is untracked, so it is untouched. Iterates a snapshot because
@@ -192,37 +266,70 @@ export function closeAllRouteSurfaces(): void {
 }
 
 /**
- * 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).
+ * Drill in from a screen. From inside a surface the DEFAULT is to navigate WITHIN
+ * it — the panel MORPHS from the current frame's size to the next's. EVERY screen
+ * morphs; a NEW surface is stacked on top ONLY when the target route declares
+ * `stacks` (reserved for genuine overlays — none today, since action sheets /
+ * confirms / prompts are Bloom-raw `surfaces.present` calls outside this
+ * registry). A stacked surface gets its own backdrop + entry animation; dismissing
+ * it unwinds back to the surface that opened it.
  */
 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 {
+  if (getSurfaceConfig(route, nextProps).stacks) {
     presentRoute(route, nextProps);
+  } else {
+    navStack.navigate(route, nextProps);
   }
 }
 
-/** Replace variant of {@link navigateWithinOrPresent}. */
+/** Replace variant of {@link navigateWithinOrPresent} (swaps the top frame). */
 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 {
+  if (getSurfaceConfig(route, nextProps).stacks) {
     presentRoute(route, nextProps);
+  } else {
+    navStack.replace(route, nextProps);
+  }
+}
+
+/**
+ * Open a result-bearing route the SAME way a drill-in navigates (the morph-by-
+ * default rule), but returning the route's dismissal RESULT to the caller.
+ *
+ * When a surface is already open and the target morphs into it (the default —
+ * anything not marked `stacks`), it runs as a SUB-FLOW inside that surface: the
+ * panel morphs from the current screen into the target, and the promise resolves
+ * with the target's `dismiss(result)` (or `undefined` when cancelled), popping
+ * back to the caller's frame WITHOUT closing the host. Otherwise (no surface, or a
+ * route that stacks) it presents a fresh surface and resolves with its dismissal —
+ * identical to the historical `present(route).result`.
+ *
+ * The entry seam for the avatar picker AND its nested "My Oxy files" media
+ * selector: each awaits its result whether it morphed into the caller's surface
+ * or opened cold, with no morph-vs-present branch of its own.
+ */
+export function openWithinOrPresent<K extends RouteName>(
+  route: K,
+  props?: SurfaceProps<K>,
+): Promise<SurfaceResult<K> | undefined> {
+  const nextProps = (props ?? {}) as Record<string, unknown>;
+  const host = topMorphableSurface();
+  if (host && !getSurfaceConfig(route, nextProps).stacks) {
+    // Morph: run as a sub-flow inside the host. The erased `Promise<unknown>` is
+    // narrowed to this route's result at the typed boundary (the sub-flow resolves
+    // with exactly the value a descendant screen passes to `dismiss(result)`).
+    return host.beginFlow(route, nextProps) as Promise<SurfaceResult<K> | undefined>;
   }
+  return present(route, props).result;
 }
 
 /**