@oxy.so/services 1.0.0

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

@@ -0,0 +1,181 @@
+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 flow)', () => {
+    it('resolves with the descendant dismiss result and pops back to the caller frame', async () => {
+      // Device / camera path: ChangeAvatar navigates straight to the cropper.
+      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('My Oxy files: the picker and cropper are FORWARD frames; the cropper confirm resolves the flow', async () => {
+      // EditProfile → (flow) ChangeAvatar → FileManagement picker → AvatarCrop, all
+      // plain forward frames in the ONE avatar flow. Selecting a file forward-
+      // navigates to the cropper (it does NOT resolve the flow); the cropper's
+      // confirm resolves the flow and pops all the way back to EditProfile.
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.navigate('FileManagement', { selectMode: true }); // "My Oxy files" picker
+      stack.navigate('AvatarCrop', { imageFileId: 'file-1' }); // forward-nav on pick
+      stack.resolveFlowOrDismiss({ uri: 'file:///cropped.jpg' }); // cropper confirm
+      await expect(flow).resolves.toEqual({ uri: 'file:///cropped.jpg' });
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    it('My Oxy files: Back unwinds cropper → picker → list, then cancels the flow', async () => {
+      // The bug this fixes: Back from the cropper must return to the PICKER (re-pick),
+      // not straight to the ChangeAvatar list.
+      const stack = createSurfaceNavStack('EditProfile');
+      const flow = stack.beginFlow('ChangeAvatar');
+      stack.navigate('FileManagement', { selectMode: true });
+      stack.navigate('AvatarCrop', { imageFileId: 'file-1' });
+      expect(stack.goBack()).toBe(true); // crop -> picker (re-pick)
+      expect(stack.getTop().route).toBe('FileManagement');
+      expect(stack.goBack()).toBe(true); // picker -> ChangeAvatar
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      expect(stack.goBack()).toBe(true); // ChangeAvatar -> EditProfile (cancels flow)
+      await expect(flow).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('EditProfile');
+      expect(stack.store.getState().closing).toBe(false);
+    });
+
+    // The stack still supports NESTED flows generically, even though no current
+    // caller opens a flow inside another (the avatar flow uses one flow + forward
+    // frames). These guard that capability.
+    it('supports NESTED flows: the inner flow resolves first, then the outer one', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const outer = stack.beginFlow('ChangeAvatar');
+      const inner = stack.beginFlow('FileManagement');
+      expect(stack.getTop().route).toBe('FileManagement');
+      stack.resolveFlowOrDismiss({ id: 'file-1' });
+      await expect(inner).resolves.toEqual({ id: 'file-1' });
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      expect(stack.store.getState().closing).toBe(false);
+      stack.navigate('AvatarCrop');
+      stack.resolveFlowOrDismiss({ uri: 'file:///c.jpg' });
+      await expect(outer).resolves.toEqual({ uri: 'file:///c.jpg' });
+      expect(stack.getTop().route).toBe('EditProfile');
+    });
+
+    it('backing out of a NESTED inner flow leaves the outer flow pending', async () => {
+      const stack = createSurfaceNavStack('EditProfile');
+      const outer = stack.beginFlow('ChangeAvatar');
+      const inner = stack.beginFlow('FileManagement');
+      expect(stack.goBack()).toBe(true); // inner entry backed out -> cancels inner only
+      await expect(inner).resolves.toBeUndefined();
+      expect(stack.getTop().route).toBe('ChangeAvatar');
+      let outerSettled = false;
+      void outer.then(() => { outerSettled = true; });
+      await Promise.resolve();
+      expect(outerSettled).toBe(false);
+    });
+
+    it('tearing down the surface abandons ALL pending 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

@@ -0,0 +1,114 @@
+/**
+ * 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 '@oxy.so/core';
+
+/** An app-owned action rendered inside the shared account menu. */
+export interface AccountDialogMenuItem {
+  key: string;
+  label: string;
+  icon?: string;
+  onPress: () => void;
+}
+
+/**
+ * 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;
+  menuItems?: readonly AccountDialogMenuItem[];
+}
+
+let controls: AccountDialogControls | null = null;
+let consumerHooks: AccountDialogConsumerHooks | null = null;
+const visibilityListeners = new Set<(visible: boolean) => void>();
+const consumerHookListeners = new Set<() => void>();
+
+function notifyConsumerHookListeners(): void {
+  for (const listener of consumerHookListeners) {
+    listener();
+  }
+}
+
+export function registerAccountDialogControls(next: AccountDialogControls): () => void {
+  controls = next;
+  return () => {
+    if (controls === next) {
+      controls = null;
+    }
+  };
+}
+
+/** Register app-local manage/add/profile handlers for the account dialog. */
+export function registerAccountDialogConsumerHooks(
+  next: AccountDialogConsumerHooks | null,
+): () => void {
+  consumerHooks = next;
+  notifyConsumerHookListeners();
+  return () => {
+    if (consumerHooks === next) {
+      consumerHooks = null;
+      notifyConsumerHookListeners();
+    }
+  };
+}
+
+export function getAccountDialogConsumerHooks(): AccountDialogConsumerHooks | null {
+  return consumerHooks;
+}
+
+/** Subscribe to consumer-hook registration changes (menu items, manage/add overrides). */
+export function subscribeToAccountDialogConsumerHooks(listener: () => void): () => void {
+  consumerHookListeners.add(listener);
+  return () => {
+    consumerHookListeners.delete(listener);
+  };
+}
+
+/** Open the account dialog on `view` (default `accounts`). No-op before mount. */
+export function openAccountDialog(view?: AccountDialogView): void {
+  controls?.open(view);
+}
+
+/** Close the account dialog. No-op before mount. */
+export function closeAccountDialog(): void {
+  controls?.close();
+}
+
+/** Report dialog visibility to subscribers (e.g. `OxySignInButton` loading state). */
+export function notifyAccountDialogVisibility(visible: boolean): void {
+  for (const listener of visibilityListeners) {
+    listener(visible);
+  }
+}
+
+/** Subscribe to account dialog visibility changes. */
+export function subscribeToAccountDialog(listener: (visible: boolean) => void): () => void {
+  visibilityListeners.add(listener);
+  return () => {
+    visibilityListeners.delete(listener);
+  };
+}

package/src/ui/navigation/bottomSheetManager.ts

@@ -0,0 +1,60 @@
+import type { RouteName } from './routes';
+import { isValidRoute } from './routes';
+import { getSurfaceConfig } from './surfaceRegistry';
+import { closeAllRouteSurfaces, presentRoute, topRouteSurface } from './surfaces';
+
+/**
+ * Bottom-sheet manager — the INTERNAL adapter that keeps the historical
+ * `showBottomSheet` / `closeBottomSheet` API working on top of the new Bloom
+ * surface stack (`navigation/surfaces.ts`). The public signatures are unchanged;
+ * this file just re-expresses them as thin calls into the typed surface layer.
+ *
+ * The old single-surface store is gone: `showBottomSheet` now open-or-navigates
+ * the "base" (top-most) route surface, and cross-presentation targets (the
+ * full-bleed image picker) stack a NEW surface on top — Bloom coordinates the
+ * z-order / backdrop / dismiss so nothing clashes.
+ */
+
+/**
+ * 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.
+ */
+export const showBottomSheet = (
+  screenOrConfig:
+    | RouteName
+    | { screen: RouteName; props?: Record<string, unknown>; fullScreen?: boolean },
+): void => {
+  const screen = typeof screenOrConfig === 'string' ? screenOrConfig : screenOrConfig.screen;
+  const props = typeof screenOrConfig === 'string' ? {} : screenOrConfig.props ?? {};
+
+  if (!isValidRoute(screen)) {
+    if (__DEV__) console.warn(`[BottomSheet] Invalid route: ${screen}`);
+    return;
+  }
+
+  const top = topRouteSurface();
+  if (top && !getSurfaceConfig(screen, props).stacks) {
+    top.navigate(screen, props);
+  } else {
+    presentRoute(screen, props);
+  }
+};
+
+/** Dismiss the whole bottom-sheet session (every active route surface). */
+export const closeBottomSheet = (): void => {
+  closeAllRouteSurfaces();
+};
+
+/**
+ * Step back within the top-most surface's route history. Returns `true` when a
+ * frame was popped, `false` when the surface is already at its root frame.
+ */
+export const goBack = (): boolean => {
+  const top = topRouteSurface();
+  return top ? top.goBack() : false;
+};

package/src/ui/navigation/routes.ts

@@ -0,0 +1,140 @@
+import { lazy, type ComponentType } from 'react';
+import type { BaseScreenProps } from '../types/navigation';
+
+// Define all available route names
+export type RouteName =
+    | 'ManageAccount'    // Unified "Manage your Oxy Account" surface
+    | 'AccountVerification'
+    | 'PaymentGateway'
+    | 'Profile'
+    | 'LanguageSelector'
+    | 'PrivacySettings'
+    | 'SearchSettings'
+    | 'FileManagement'
+    | 'HelpSupport'
+    | 'FAQ'
+    | 'Feedback'
+    | 'LegalDocuments'
+    | 'AppInfo'
+    | 'PremiumSubscription'
+    | 'WelcomeNewUser'
+    | 'UserLinks'
+    | 'HistoryView'
+    | 'SavesCollections'
+    | 'EditProfile'      // Profile-editing hub: one row per editable field
+    | 'EditProfileField' // Dedicated screen for editing a single profile field
+    | 'LearnMoreUsernames' // Informational screen about usernames
+    | 'TrustCenter'
+    | 'TrustLeaderboard'
+    | 'TrustRewards'
+    | 'TrustRules'
+    | 'AboutTrust'
+    | 'TrustFAQ'
+    | 'FollowersList'  // List of user's followers
+    | 'FollowingList' // List of users being followed
+    | '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
+    | '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 (OxyAccountDialogScreen body)
+
+/**
+ * The component for each route, loaded on demand.
+ *
+ * Every entry is `lazy(() => import(...))`: the screen module is fetched and
+ * evaluated the first time its surface is presented, never at import time. That
+ * matters twice over — screens import `OxyContext`, which reaches back here, so
+ * eager evaluation would run screens mid-cycle; and it keeps native-only screen
+ * dependencies out of the evaluation path of every consumer that merely touches
+ * the SDK.
+ *
+ * What defers the load must NOT be `require()`. `@oxy.so/services` ships an ESM
+ * build, and a `require()` in ESM output forces web bundlers into CommonJS
+ * interop: rolldown-vite defers every module in the required subgraph behind a
+ * lazy initializer and then hands a consumer that statically imported one of
+ * them the still-`undefined` binding. That is how `OxySignInRequestSurface`
+ * reached auth.oxy.so/authorize as `undefined` and blanked the page with React
+ * error #130 — this registry pulled `OxyAccountDialogScreen`, and the whole
+ * sign-in surface subgraph with it, through `require()`.
+ *
+ * The value type is `ComponentType<never>`, which every screen satisfies. A few
+ * screens (`Profile`, `PaymentGateway`, `UserLinks`, `FollowersList`,
+ * `FollowingList`) declare props BEYOND {@link BaseScreenProps} — `userId`,
+ * `amount` — that only reach them through the route's untyped props bag
+ * (`present(route, props)`), so this map cannot prove they are satisfied. The
+ * previous `require()` returned `any` and hid that entirely; stating it here
+ * confines the gap to one documented widening in {@link getScreenComponent}.
+ */
+const screenComponents: Record<RouteName, ComponentType<never>> = {
+    ManageAccount: lazy(() => import('../screens/ManageAccountScreen')),
+    AccountVerification: lazy(() => import('../screens/AccountVerificationScreen')),
+    PaymentGateway: lazy(() => import('../screens/PaymentGatewayScreen')),
+    Profile: lazy(() => import('../screens/ProfileScreen')),
+    LanguageSelector: lazy(() => import('../screens/LanguageSelectorScreen')),
+    PrivacySettings: lazy(() => import('../screens/PrivacySettingsScreen')),
+    SearchSettings: lazy(() => import('../screens/SearchSettingsScreen')),
+    FileManagement: lazy(() => import('../screens/FileManagementScreen')),
+    HelpSupport: lazy(() => import('../screens/HelpSupportScreen')),
+    FAQ: lazy(() => import('../screens/FAQScreen')),
+    Feedback: lazy(() => import('../screens/FeedbackScreen')),
+    LegalDocuments: lazy(() => import('../screens/LegalDocumentsScreen')),
+    AppInfo: lazy(() => import('../screens/AppInfoScreen')),
+    PremiumSubscription: lazy(() => import('../screens/PremiumSubscriptionScreen')),
+    WelcomeNewUser: lazy(() => import('../screens/WelcomeNewUserScreen')),
+    UserLinks: lazy(() => import('../screens/UserLinksScreen')),
+    HistoryView: lazy(() => import('../screens/HistoryViewScreen')),
+    SavesCollections: lazy(() => import('../screens/SavesCollectionsScreen')),
+    EditProfile: lazy(() => import('../screens/EditProfileScreen')),
+    EditProfileField: lazy(() => import('../screens/EditProfileFieldScreen')),
+    // Informational screens
+    LearnMoreUsernames: lazy(() => import('../screens/LearnMoreUsernamesScreen')),
+    // Oxy Trust screens
+    TrustCenter: lazy(() => import('../screens/trust/TrustCenterScreen')),
+    TrustLeaderboard: lazy(() => import('../screens/trust/TrustLeaderboardScreen')),
+    TrustRewards: lazy(() => import('../screens/trust/TrustRewardsScreen')),
+    TrustRules: lazy(() => import('../screens/trust/TrustRulesScreen')),
+    AboutTrust: lazy(() => import('../screens/trust/TrustAboutScreen')),
+    TrustFAQ: lazy(() => import('../screens/trust/TrustFAQScreen')),
+    // User list screens (followers/following)
+    FollowersList: lazy(() => import('../screens/FollowersListScreen')),
+    FollowingList: lazy(() => import('../screens/FollowingListScreen')),
+    CreateAccount: lazy(() => import('../screens/CreateAccountScreen')),
+    AccountMembers: lazy(() => import('../screens/AccountMembersScreen')),
+    AccountSettings: lazy(() => import('../screens/AccountSettingsScreen')),
+    ChangeAvatar: lazy(() => import('../screens/ChangeAvatarScreen')),
+    AvatarCrop: lazy(() => import('../screens/AvatarCropScreen')),
+    Notifications: lazy(() => import('../screens/NotificationsScreen')),
+    ConnectedApps: lazy(() => import('../screens/ConnectedAppsScreen')),
+    Preferences: lazy(() => import('../screens/PreferencesScreen')),
+    // 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: lazy(() => import('../components/OxyAccountDialogScreen')),
+};
+
+/**
+ * Resolve the component for a route.
+ *
+ * The map is total over {@link RouteName} — the compiler enforces that at its
+ * declaration — so this returns `undefined` only for a caller that reached here
+ * with an unchecked string; {@link isValidRoute} is how such a caller narrows.
+ *
+ * The surface host renders the result with {@link BaseScreenProps} merged with
+ * the route's own props bag, so that is the type it is handed back as. This one
+ * widening is where the gap documented on {@link screenComponents} lives: the map
+ * dispatches on a string key, so a screen's extra prop requirements are met at
+ * `present(route, props)` call sites, not provable here. No caching is needed —
+ * React memoizes each `lazy()` component's module after its first load.
+ */
+export const getScreenComponent = (routeName: RouteName): ComponentType<BaseScreenProps> | undefined =>
+    screenComponents[routeName] as ComponentType<BaseScreenProps>;
+
+// Helper function to check if a route exists
+// Uses the screenComponents map to check existence without loading the screen
+export const isValidRoute = (routeName: string): routeName is RouteName => {
+    return routeName in screenComponents;
+};

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;
+}