@userflow-tech/react-native 0.2.0 → 0.3.0

package/src/runtime/TargetPressBridge.tsx

@@ -4,6 +4,7 @@ import { StyleSheet, View, type GestureResponderEvent } from 'react-native';
 import { targetPressMonitor } from '../anchors/targetPressMonitor';
 
 import { changedTouchPoints, forEachChangedTouch } from './changedTouchPoints';
+import { isolateSync } from './isolateCall';
 
 export interface TargetPressBridgeProps {
   children: React.ReactNode;
@@ -25,26 +26,32 @@ export interface TargetPressBridgeProps {
  */
 export function TargetPressBridge({ children }: TargetPressBridgeProps): React.ReactElement {
   const onTouchStart = React.useCallback((event: GestureResponderEvent) => {
-    forEachChangedTouch(event, (identifier, pageX, pageY) => {
-      targetPressMonitor.handleTouchStart(identifier, pageX, pageY);
+    isolateSync('target-press', () => {
+      forEachChangedTouch(event, (identifier, pageX, pageY) => {
+        targetPressMonitor.handleTouchStart(identifier, pageX, pageY);
+      });
     });
   }, []);
 
   const onTouchEnd = React.useCallback((event: GestureResponderEvent) => {
-    forEachChangedTouch(event, (identifier, pageX, pageY) => {
-      targetPressMonitor.handleTouchEnd(identifier, pageX, pageY);
+    isolateSync('target-press', () => {
+      forEachChangedTouch(event, (identifier, pageX, pageY) => {
+        targetPressMonitor.handleTouchEnd(identifier, pageX, pageY);
+      });
     });
   }, []);
 
   const onTouchCancel = React.useCallback((event: GestureResponderEvent) => {
-    const points = changedTouchPoints(event);
-    if (points.length === 0) {
-      targetPressMonitor.cancelTouch();
-      return;
-    }
-    for (const touch of points) {
-      targetPressMonitor.cancelTouch(touch.identifier);
-    }
+    isolateSync('target-press', () => {
+      const points = changedTouchPoints(event);
+      if (points.length === 0) {
+        targetPressMonitor.cancelTouch();
+        return;
+      }
+      for (const touch of points) {
+        targetPressMonitor.cancelTouch(touch.identifier);
+      }
+    });
   }, []);
 
   return (

package/src/runtime/UserflowOverlay.tsx

@@ -0,0 +1,118 @@
+import type { BannerSessionEngine, FlowSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+
+import { ElementPickerOverlay } from '../authoring/ElementPickerOverlay';
+import { elementPickerController } from '../authoring/elementPickerController';
+import { EvalJsHost } from '../evalJs/EvalJsHost';
+import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
+import { getPairingController } from '../pairing/pairingRuntime';
+import { usePairingState } from '../pairing/usePairingState';
+import { usePreviewBarHold } from '../pairing/usePreviewBarHold';
+
+import { BannerHost } from './BannerHost';
+import { FlowRenderer } from './FlowRenderer';
+import { useFlowSessionState } from './useFlowSessionState';
+import { getUserflowCore } from './userflowCore';
+
+export interface UserflowOverlayProps {
+  engine: FlowSessionEngine;
+  bannerEngine: BannerSessionEngine;
+  /** Keep the host a11y trap in the provider (outside this error boundary). */
+  onTrapChange: (trap: boolean) => void;
+}
+
+/**
+ * SDK overlay chrome: preview banner, active flow surface, element picker.
+ * Mounted inside {@link SdkErrorBoundary} so a render throw here cannot
+ * unmount host children of {@link UserflowProvider}.
+ */
+export function UserflowOverlay({
+  engine,
+  bannerEngine,
+  onTrapChange,
+}: UserflowOverlayProps): React.ReactElement {
+  const pairingState = usePairingState();
+  const { session, currentStep } = useFlowSessionState(engine);
+  const [previewConfirming, setPreviewConfirming] = React.useState(false);
+  const [pickerActive, setPickerActive] = React.useState(
+    () => elementPickerController.getState().active,
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setPickerActive(next.active);
+    });
+  }, []);
+
+  const previewHeld = usePreviewBarHold(pairingState, pickerActive);
+
+  const trapHostAccessibility = React.useMemo(() => {
+    // Picking hides flow chrome, so the host must stay in the accessibility tree.
+    if (pickerActive) {
+      return false;
+    }
+    if (previewConfirming) {
+      return true;
+    }
+    if (!session || !currentStep) {
+      return false;
+    }
+    const appearance = String(currentStep.appearance).toUpperCase();
+    if (appearance === 'HIDDEN') {
+      return false;
+    }
+    if (appearance !== 'TOOLTIP') {
+      return true;
+    }
+    return currentStep.tooltipTargetBlocked;
+  }, [pickerActive, previewConfirming, session, currentStep]);
+
+  React.useLayoutEffect(() => {
+    onTrapChange(trapHostAccessibility);
+    return () => {
+      // Release whenever this overlay unmounts — including when
+      // SdkErrorBoundary replaces it with null and onError never runs.
+      onTrapChange(false);
+    };
+  }, [onTrapChange, trapHostAccessibility]);
+
+  const onExitPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).exitPreview();
+  }, []);
+
+  const onRestartPreview = React.useCallback(() => {
+    void getPairingController(getUserflowCore()).restartPreview();
+  }, []);
+
+  return (
+    <>
+      {/*
+       * Under the preview banner and flow chrome (later siblings paint on top).
+       * Outside FlowRenderer so picking, which unmounts flow chrome, does not
+       * destroy a running script. `suppressed` hides it for the pick.
+       */}
+      <EvalJsHost suppressed={pickerActive} />
+      <PreviewModeBanner
+        onConfirmingChange={setPreviewConfirming}
+        onExit={onExitPreview}
+        held={previewHeld}
+        onRestart={onRestartPreview}
+        state={pairingState}
+        suppressed={pickerActive}
+      />
+      {/*
+       * Unmount flow chrome for the whole pick. The session stays alive;
+       * captureScreen would otherwise include the modal or tooltip.
+       * Remounting reads the same session back.
+       */}
+      <BannerHost engine={bannerEngine} hidden={pickerActive} />
+      {pickerActive ? null : (
+        <FlowRenderer
+          engine={engine}
+          previewRestartGeneration={pairingState.previewRestartGeneration}
+        />
+      )}
+      <ElementPickerOverlay />
+    </>
+  );
+}

package/src/runtime/UserflowProvider.tsx

@@ -1,21 +1,25 @@
-import type { FlowSessionEngine } from '@userflow-tech/core';
+import type { BannerSessionEngine, FlowSessionEngine } from '@userflow-tech/core';
 import * as React from 'react';
 import { StyleSheet, View } from 'react-native';
 
 import { FiberScanRoot } from '../anchors/fiber/FiberScanRoot';
-import { ElementPickerOverlay } from '../authoring/ElementPickerOverlay';
 import { DoubleTapBridge } from '../authoring/chrome/DoubleTapBridge';
 import { elementPickerController } from '../authoring/elementPickerController';
-import { PreviewModeBanner } from '../pairing/PreviewModeBanner';
-import { getPairingController } from '../pairing/pairingRuntime';
-import { usePairingState } from '../pairing/usePairingState';
 import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
+import { getSafeAreaInsetsContext, useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+import type { EdgeInsets } from '../surfaces/safeArea';
 import { SurfaceLayoutInsetsProvider } from '../surfaces/surfaceLayoutInsets';
 
-import { FlowRenderer } from './FlowRenderer';
+import { BannerHost } from './BannerHost';
+import { SdkErrorBoundary } from './SdkErrorBoundary';
 import { TargetPressBridge } from './TargetPressBridge';
+import { UserflowOverlay } from './UserflowOverlay';
+import { getBannerSessionEngine } from './bannerEngine';
+import { BannerEngineContext } from './bannerEngineContext';
+import { bannerEdge } from './bannerPlacement';
 import { getFlowSessionEngine } from './flowEngine';
-import { useFlowSessionState } from './useFlowSessionState';
+import { isolateSync } from './isolateCall';
+import { useBannerSession } from './useBannerSession';
 import { getUserflowCore } from './userflowCore';
 
 export interface UserflowContextValue {
@@ -26,8 +30,50 @@ const UserflowContext = React.createContext<UserflowContextValue | null>(null);
 
 export interface UserflowProviderProps {
   children: React.ReactNode;
-  /** Override the module singleton engine (tests). */
+  /** Override the module singleton tour engine (tests). */
   engine?: FlowSessionEngine;
+  /** Override the module singleton banner engine (tests). */
+  bannerEngine?: BannerSessionEngine;
+}
+
+function overlayResetKeyFromEngine(engine: FlowSessionEngine): string {
+  const session = engine.getFlowSession();
+  if (!session) {
+    return '';
+  }
+  // `ForceGoToStep` updates displayedStepId without rewriting session.currentStep.
+  return `${session.id}:${engine.getCurrentStep()?.id ?? ''}`;
+}
+
+/**
+ * Session/step identity for retrying a crashed overlay. Lives in an effect so a
+ * throw cannot unmount host children (session hooks run inside the overlay
+ * boundary instead).
+ */
+function useOverlayErrorBoundaryResetKey(engine: FlowSessionEngine): string {
+  const [resetKey, setResetKey] = React.useState(() => {
+    try {
+      return overlayResetKeyFromEngine(engine);
+    } catch {
+      return '';
+    }
+  });
+
+  React.useEffect(() => {
+    const apply = (next: string) => {
+      setResetKey(next);
+    };
+    isolateSync('overlay-reset-key', () => {
+      apply(overlayResetKeyFromEngine(engine));
+    });
+    return engine.on(() => {
+      isolateSync('overlay-reset-key', () => {
+        apply(overlayResetKeyFromEngine(engine));
+      });
+    });
+  }, [engine]);
+
+  return resetKey;
 }
 
 /**
@@ -41,6 +87,10 @@ export interface UserflowProviderProps {
  * We deliberately do not use RN `<Modal>` — it is the wrong primitive for
  * non-modal tooltips (WS6).
  *
+ * Overlay render errors are contained by {@link SdkErrorBoundary}; host
+ * children are never inside that boundary. See
+ * `packages/react-native/docs/isolation.md`.
+ *
  * **Expo Router:** also mount `UserflowExpoRouterScreenTracker` from
  * `@userflow-tech/react-native/expo-router` under this provider so pathname and
  * navigation-state changes and path-like NAVIGATE actions are wired. The tracker
@@ -53,12 +103,23 @@ export interface UserflowProviderProps {
 export function UserflowProvider({
   children,
   engine: engineProp,
+  bannerEngine: bannerEngineProp,
 }: UserflowProviderProps): React.ReactElement {
   const engine = engineProp ?? getFlowSessionEngine(getUserflowCore());
+  const bannerEngine = bannerEngineProp ?? getBannerSessionEngine(getUserflowCore());
   const contextValue = React.useMemo<UserflowContextValue>(() => ({ engine }), [engine]);
-  const pairingState = usePairingState();
-  const { session, currentStep } = useFlowSessionState(engine);
-  const [previewConfirming, setPreviewConfirming] = React.useState(false);
+  const overlayResetKey = useOverlayErrorBoundaryResetKey(engine);
+  const [trapHostAccessibility, setTrapHostAccessibility] = React.useState(false);
+
+  const onTrapChange = React.useCallback((trap: boolean) => {
+    setTrapHostAccessibility(trap);
+  }, []);
+
+  const onOverlayError = React.useCallback(() => {
+    setTrapHostAccessibility(false);
+  }, []);
+  const bannerSession = useBannerSession(bannerEngine);
+  const safeInsets = useUserflowSafeAreaInsets();
   const [pickerActive, setPickerActive] = React.useState(
     () => elementPickerController.getState().active,
   );
@@ -69,67 +130,81 @@ export function UserflowProvider({
     });
   }, []);
 
-  const trapHostAccessibility = React.useMemo(() => {
-    if (previewConfirming) {
-      return true;
-    }
-    if (!session || !currentStep) {
-      return false;
-    }
-    const appearance = String(currentStep.appearance).toUpperCase();
-    if (appearance === 'HIDDEN') {
-      return false;
-    }
-    if (appearance !== 'TOOLTIP') {
-      return true;
-    }
-    return currentStep.tooltipTargetBlocked;
-  }, [previewConfirming, session, currentStep]);
-
-  const onExitPreview = React.useCallback(() => {
-    void getPairingController(getUserflowCore()).exitPreview();
-  }, []);
+  const banner = bannerSession?.version.banner ?? null;
+  const flowEdge =
+    banner && banner.overlay === false && !pickerActive ? bannerEdge(banner.embedMode) : null;
+  const hostInsets: EdgeInsets | null =
+    flowEdge === 'top' || flowEdge === 'bottom'
+      ? {
+          ...safeInsets,
+          top: flowEdge === 'top' ? 0 : safeInsets.top,
+          bottom: flowEdge === 'bottom' ? 0 : safeInsets.bottom,
+        }
+      : null;
 
-  const onRestartPreview = React.useCallback(() => {
-    void getPairingController(getUserflowCore()).restartPreview();
-  }, []);
+  const appContent = (
+    <View
+      style={styles.appContent}
+      testID="userflow-app-content"
+      importantForAccessibility={trapHostAccessibility ? 'no-hide-descendants' : undefined}
+      accessibilityElementsHidden={trapHostAccessibility ? true : undefined}
+    >
+      <TargetPressBridge>
+        <FiberScanRoot>{children}</FiberScanRoot>
+      </TargetPressBridge>
+    </View>
+  );
 
   return (
-    <UserflowContext.Provider value={contextValue}>
-      <SurfaceLayoutInsetsProvider>
-        <DoubleTapBridge>
-          <View style={styles.root} collapsable={false}>
-            <View
-              style={styles.appContent}
-              testID="userflow-app-content"
-              importantForAccessibility={trapHostAccessibility ? 'no-hide-descendants' : undefined}
-              accessibilityElementsHidden={trapHostAccessibility ? true : undefined}
-            >
-              <TargetPressBridge>
-                <FiberScanRoot>{children}</FiberScanRoot>
-              </TargetPressBridge>
-            </View>
-            <View style={styles.overlay} pointerEvents="box-none">
-              <PreviewModeBanner
-                onConfirmingChange={setPreviewConfirming}
-                onExit={onExitPreview}
-                onRestart={onRestartPreview}
-                state={pairingState}
-                suppressed={pickerActive}
+    <BannerEngineContext.Provider value={bannerEngine}>
+      <UserflowContext.Provider value={contextValue}>
+        <SurfaceLayoutInsetsProvider>
+          <DoubleTapBridge>
+            <View style={styles.root} collapsable={false} testID="userflow-root">
+              <BannerHost engine={bannerEngine} placement="flow" edge="top" hidden={pickerActive} />
+              <HostSafeArea insets={hostInsets}>{appContent}</HostSafeArea>
+              <BannerHost
+                engine={bannerEngine}
+                placement="flow"
+                edge="bottom"
+                hidden={pickerActive}
               />
-              <FlowRenderer
-                engine={engine}
-                previewRestartGeneration={pairingState.previewRestartGeneration}
-              />
-              <ElementPickerOverlay />
+              <View style={styles.overlay} pointerEvents="box-none">
+                <SdkErrorBoundary
+                  scope="overlay"
+                  resetKey={overlayResetKey}
+                  onError={onOverlayError}
+                >
+                  <UserflowOverlay
+                    engine={engine}
+                    bannerEngine={bannerEngine}
+                    onTrapChange={onTrapChange}
+                  />
+                </SdkErrorBoundary>
+              </View>
             </View>
-          </View>
-        </DoubleTapBridge>
-      </SurfaceLayoutInsetsProvider>
-    </UserflowContext.Provider>
+          </DoubleTapBridge>
+        </SurfaceLayoutInsetsProvider>
+      </UserflowContext.Provider>
+    </BannerEngineContext.Provider>
   );
 }
 
+function HostSafeArea({
+  insets,
+  children,
+}: {
+  insets: EdgeInsets | null;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const Context = getSafeAreaInsetsContext();
+  const defaultInsets = useUserflowSafeAreaInsets();
+  if (!Context) {
+    return <>{children}</>;
+  }
+  return <Context.Provider value={insets ?? defaultInsets}>{children}</Context.Provider>;
+}
+
 /** Access the flow session engine from inside {@link UserflowProvider}. */
 export function useUserflow(): UserflowContextValue {
   const ctx = React.useContext(UserflowContext);

package/src/runtime/bannerEngine.ts

@@ -0,0 +1,55 @@
+import { BannerSessionEngine, type UserflowCore } from '@userflow-tech/core';
+
+import { evalJsController } from '../evalJs/evalJsController';
+import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
+
+import { getFlowSessionEngine } from './flowEngine';
+import { isolateAsync } from './isolateCall';
+
+let bannerEngine: BannerSessionEngine | null = null;
+
+/** Build (once) the module-level banner session engine over a {@link UserflowCore} transport. */
+export function getBannerSessionEngine(core: UserflowCore): BannerSessionEngine {
+  if (!bannerEngine) {
+    bannerEngine = new BannerSessionEngine({
+      transport: {
+        send: (message) => core.send(message),
+        onServerMessage: (handler) => core.onServerMessage(handler),
+        setBannerSessionId: (id) => core.setBannerSessionId(id),
+      },
+      flowActions: () => getFlowSessionEngine(core),
+      onOpenExternalUrl: (url) => {
+        void isolateAsync('navigate', () => openFlowNavigateUrl(url), {
+          rethrowHostContract: false,
+        });
+      },
+      onEvalJs: (request) => {
+        evalJsController.enqueue(request);
+      },
+    });
+  }
+  return bannerEngine;
+}
+
+/** Subscribe the engine to inbound server messages. Call after identify. */
+export function attachBannerSessionEngine(core: UserflowCore): BannerSessionEngine {
+  const engine = getBannerSessionEngine(core);
+  engine.attach();
+  return engine;
+}
+
+/** Clear the banner session and detach. Call from {@link Userflow.reset}. */
+export function resetBannerSessionEngine(): void {
+  bannerEngine?.reset();
+}
+
+/** Drop the local banner without detaching (preview exit, user switch). */
+export function clearBannerSessionEngineLocalSession(): void {
+  bannerEngine?.clearLocalSession();
+}
+
+/** Test helper: drop the singleton so the next get recreates it. */
+export function __resetBannerSessionEngineForTests(): void {
+  bannerEngine?.reset();
+  bannerEngine = null;
+}

package/src/runtime/bannerEngineContext.ts

@@ -0,0 +1,5 @@
+import type { BannerSessionEngine } from '@userflow-tech/core';
+import * as React from 'react';
+
+/** Banner engine for host slots. Null outside {@link UserflowProvider}. */
+export const BannerEngineContext = React.createContext<BannerSessionEngine | null>(null);

package/src/runtime/bannerPlacement.ts

@@ -0,0 +1,36 @@
+import type { BannerEmbedMode, BannerFragment } from '@userflow-tech/protocol';
+
+import { resolveManualAnchorId } from '../anchors/resolveManualAnchorId';
+
+const warned = new Set<string>();
+
+/** Body-first is the top edge; body-last is the bottom. Element modes use a placeholder. */
+export function bannerEdge(mode: BannerEmbedMode | string): 'top' | 'bottom' | null {
+  if (mode === 'BODY_FIRST') return 'top';
+  if (mode === 'BODY_LAST') return 'bottom';
+  return null;
+}
+
+/**
+ * Id of the {@link EmbedBannerPlaceholder} an element-mode banner fills.
+ * Manual selectors use `#welcome-banner` or `welcome-banner`. Body modes
+ * return null so a top/bottom bar never occupies a host slot.
+ */
+export function embedBannerPlaceholderId(banner: BannerFragment): string | null {
+  if (bannerEdge(banner.embedMode)) return null;
+  return resolveManualAnchorId(banner.embedSelector?.css);
+}
+
+export function warnBannerOnce(
+  key: string,
+  message: string,
+  warn: (message: string) => void = console.warn,
+): void {
+  if (warned.has(key)) return;
+  warned.add(key);
+  warn(message);
+}
+
+export function resetBannerWarningsForTests(): void {
+  warned.clear();
+}

package/src/runtime/embedBannerRegistry.ts

@@ -0,0 +1,28 @@
+import { warnBannerOnce } from './bannerPlacement';
+
+const counts = new Map<string, number>();
+
+/** Record a mounted {@link EmbedBannerPlaceholder}. Returns the unregister function. */
+export function registerEmbedBannerPlaceholder(id: string): () => void {
+  const next = (counts.get(id) ?? 0) + 1;
+  counts.set(id, next);
+  if (next > 1) {
+    warnBannerOnce(
+      `embed-banner-dup:${id}`,
+      `Userflow: more than one EmbedBannerPlaceholder uses id "${id}"`,
+    );
+  }
+  return () => {
+    const current = counts.get(id) ?? 0;
+    if (current <= 1) counts.delete(id);
+    else counts.set(id, current - 1);
+  };
+}
+
+export function hasEmbedBannerPlaceholder(id: string): boolean {
+  return (counts.get(id) ?? 0) > 0;
+}
+
+export function resetEmbedBannerPlaceholdersForTests(): void {
+  counts.clear();
+}

package/src/runtime/flowEngine.ts

@@ -1,8 +1,15 @@
 import { FlowSessionEngine, type UserflowCore } from '@userflow-tech/core';
+import type { EndFlowReasonInput } from '@userflow-tech/protocol';
 
+import { evalJsController } from '../evalJs/evalJsController';
 import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
 
+import { isolateAsync } from './isolateCall';
+
 let flowEngine: FlowSessionEngine | null = null;
+/** Exit asked to end a draft that identify has not delivered yet. */
+let endDraftOnArrival = false;
+let unsubscribeDraftArrival: (() => void) | null = null;
 
 /** Build (once) the module-level flow session engine over a {@link UserflowCore} transport. */
 export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
@@ -14,11 +21,17 @@ export function getFlowSessionEngine(core: UserflowCore): FlowSessionEngine {
         setFlowSessionId: (id) => core.setFlowSessionId(id),
       },
       onOpenExternalUrl: (url) => {
-        void openFlowNavigateUrl(url);
+        void isolateAsync('navigate', () => openFlowNavigateUrl(url), {
+          rethrowHostContract: false,
+        });
+      },
+      onEvalJs: (request) => {
+        evalJsController.enqueue(request);
       },
       updateUser: (attributes) => core.updateUser(attributes),
       updateGroup: (attributes, options) => core.updateGroup(attributes, options),
     });
+    if (endDraftOnArrival) watchForRestoredDraft();
   }
   return flowEngine;
 }
@@ -43,13 +56,73 @@ export function clearFlowSessionEngineLocalSession(): void {
   flowEngine?.clearLocalSession();
 }
 
-/** Whether any mid-flow session (live or draft/preview) is currently on screen. */
+/**
+ * Whether a mid-flow session is held (live, draft, or suppressed by Temporarily
+ * Hide). Foreground idle uses this so a hidden session keeps the socket that
+ * can deliver the attribute update which shows it again.
+ */
 export function hasActiveFlowSession(): boolean {
-  return flowEngine?.getFlowSession() != null;
+  return flowEngine?.hasHeldFlowSession() === true;
+}
+
+/**
+ * End the current flow on the server if it is a Builder preview draft. The
+ * server restores every active draft on identify, so clearing it locally is
+ * not enough to keep it from returning on the next launch.
+ *
+ * A draft Temporarily Hide is suppressing is still ended. `getFlowSession()`
+ * hides it, but the server will send it again. When exit runs before identify
+ * has delivered the draft, the next draft session is ended when it arrives.
+ * {@link cancelPendingDraftEnd} drops that wait; a new preview must call it
+ * so the preview's own draft is not ended.
+ */
+export async function endDraftFlowSession(): Promise<void> {
+  const session = flowEngine?.getHeldFlowSession();
+  if (flowEngine && session?.draftMode) {
+    cancelPendingDraftEnd();
+    await flowEngine.endFlow('USER_CLOSED' as EndFlowReasonInput);
+    return;
+  }
+  watchForRestoredDraft();
+}
+
+/** Drop a pending end from {@link endDraftFlowSession}. A new preview calls this. */
+export function cancelPendingDraftEnd(): void {
+  endDraftOnArrival = false;
+  unsubscribeDraftArrival?.();
+  unsubscribeDraftArrival = null;
+}
+
+function watchForRestoredDraft(): void {
+  endDraftOnArrival = true;
+  if (!flowEngine || unsubscribeDraftArrival) return;
+
+  const engine = flowEngine;
+  unsubscribeDraftArrival = engine.on((event) => {
+    if (event.type !== 'sessionChange' || !endDraftOnArrival) return;
+    const session = engine.getHeldFlowSession();
+    if (!session?.draftMode) return;
+    cancelPendingDraftEnd();
+    void engine.endFlow('USER_CLOSED' as EndFlowReasonInput).catch(() => {
+      // The session can disappear before EndFlow is built. Nothing to send.
+    });
+  });
+}
+
+/**
+ * `userflow.endFlow()` from an Evaluate JavaScript page. Ends the current
+ * session only if one of the page's scripts came from it, so a stale page
+ * cannot end a flow that started later.
+ */
+export async function endEvalJsFlowSession(sessionIds: ReadonlySet<string>): Promise<void> {
+  const session = flowEngine?.getFlowSession();
+  if (!flowEngine || !session || !sessionIds.has(session.id)) return;
+  await flowEngine.endFlow('USERFLOWJS' as EndFlowReasonInput);
 }
 
 /** Test helper: drop the singleton so the next get recreates it. */
 export function __resetFlowSessionEngineForTests(): void {
+  cancelPendingDraftEnd();
   flowEngine?.reset();
   flowEngine = null;
 }