@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/runtime/UserflowProvider.tsx

@@ -1,16 +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 { PreviewModeBanner } from '../pairing/PreviewModeBanner';
-import { getPairingController } from '../pairing/pairingRuntime';
-import { usePairingState } from '../pairing/usePairingState';
+import { DoubleTapBridge } from '../authoring/chrome/DoubleTapBridge';
+import { elementPickerController } from '../authoring/elementPickerController';
 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 { isolateSync } from './isolateCall';
+import { useBannerSession } from './useBannerSession';
 import { getUserflowCore } from './userflowCore';
 
 export interface UserflowContextValue {
@@ -21,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;
 }
 
 /**
@@ -31,14 +82,20 @@ export interface UserflowProviderProps {
  * calling {@link Userflow.init}.
  *
  * Children render normally. An absolute overlay sits above them with
- * `pointerEvents="box-none"` so taps pass through except where flow UI sits.
+ * `pointerEvents="box-none"` so taps pass through except where flow UI blocks
+ * them (modals always; tooltips when interaction blocking is enabled).
  * 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 changes
- * and path-like NAVIGATE actions are wired. The tracker is a separate entry so
- * apps without `expo-router` are not forced to install that peer.
+ * `@userflow-tech/react-native/expo-router` under this provider so pathname and
+ * navigation-state changes and path-like NAVIGATE actions are wired. The tracker
+ * is a separate entry so apps without `expo-router` are not forced to install
+ * that peer.
  *
  * **React Navigation:** wrap `NavigationContainer` with
  * {@link WithUserflowReactNavigation} from `@userflow-tech/react-native/navigation`.
@@ -46,30 +103,108 @@ 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 overlayResetKey = useOverlayErrorBoundaryResetKey(engine);
+  const [trapHostAccessibility, setTrapHostAccessibility] = React.useState(false);
 
-  const onExitPreview = React.useCallback(() => {
-    void getPairingController(getUserflowCore()).exitPreview();
+  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,
+  );
+
+  React.useEffect(() => {
+    return elementPickerController.subscribe((next) => {
+      setPickerActive(next.active);
+    });
+  }, []);
+
+  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 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}>
-      <View style={styles.root} collapsable={false}>
-        <TargetPressBridge>
-          <FiberScanRoot>{children}</FiberScanRoot>
-        </TargetPressBridge>
-        <View style={styles.overlay} pointerEvents="box-none">
-          <PreviewModeBanner state={pairingState} onExit={onExitPreview} />
-          <FlowRenderer engine={engine} />
-        </View>
-      </View>
-    </UserflowContext.Provider>
+    <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}
+              />
+              <View style={styles.overlay} pointerEvents="box-none">
+                <SdkErrorBoundary
+                  scope="overlay"
+                  resetKey={overlayResetKey}
+                  onError={onOverlayError}
+                >
+                  <UserflowOverlay
+                    engine={engine}
+                    bannerEngine={bannerEngine}
+                    onTrapChange={onTrapChange}
+                  />
+                </SdkErrorBoundary>
+              </View>
+            </View>
+          </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);
@@ -83,6 +218,9 @@ const styles = StyleSheet.create({
   root: {
     flex: 1,
   },
+  appContent: {
+    flex: 1,
+  },
   overlay: {
     ...ABSOLUTE_FILL,
   },

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/changedTouchPoints.ts

@@ -0,0 +1,34 @@
+import type { GestureResponderEvent, NativeTouchEvent } from 'react-native';
+
+/**
+ * Touches that just started/ended/cancelled for this event. Prefer
+ * `changedTouches` so multi-touch uses the finger(s) that actually changed —
+ * `touches[0]` may be an already-active finger. Each touch carries `identifier`
+ * so monitors can pair start/end per finger.
+ */
+export function changedTouchPoints(
+  event: GestureResponderEvent,
+): Array<Pick<NativeTouchEvent, 'identifier' | 'pageX' | 'pageY'>> {
+  const { changedTouches, touches, identifier, pageX, pageY } = event.nativeEvent;
+  if (changedTouches && changedTouches.length > 0) {
+    return changedTouches.map((touch) => ({
+      identifier: touch.identifier,
+      pageX: touch.pageX,
+      pageY: touch.pageY,
+    }));
+  }
+  if (touches && touches.length > 0) {
+    const touch = touches[touches.length - 1]!;
+    return [{ identifier: touch.identifier, pageX: touch.pageX, pageY: touch.pageY }];
+  }
+  return [{ identifier: identifier ?? 0, pageX, pageY }];
+}
+
+export function forEachChangedTouch(
+  event: GestureResponderEvent,
+  fn: (identifier: NativeTouchEvent['identifier'], pageX: number, pageY: number) => void,
+): void {
+  for (const touch of changedTouchPoints(event)) {
+    fn(touch.identifier, touch.pageX, touch.pageY);
+  }
+}

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,9 +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;
 }
@@ -41,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;
 }

package/src/runtime/flowSessionViewState.ts

@@ -5,6 +5,12 @@ import type { FlowSessionFragment, FlowStepFragment } from '@userflow-tech/proto
 export interface FlowSessionViewState {
   session: FlowSessionFragment | null;
   currentStepId: string | null;
+  /**
+   * Bumped on every `goToStep`, including a ForceGoToStep back to the current
+   * step, so tooltip targeting can re-bootstrap when session/step identity
+   * would otherwise be unchanged (draft preview restart).
+   */
+  stepShowNonce: number;
 }
 
 export function initialFlowSessionViewState(
@@ -13,15 +19,19 @@ export function initialFlowSessionViewState(
   return {
     session,
     currentStepId: session?.currentStep?.id ?? null,
+    stepShowNonce: 0,
   };
 }
 
 /**
  * Reduces engine events into view state.
  *
- * Important: `goToStep` updates `currentStepId` without requiring a new
- * `sessionChange` — the engine mutates `session.currentStep` in place and
- * `ForceGoToStep` does not update it at all.
+ * `goToStep` updates `currentStepId` without a new `sessionChange`. A later
+ * same-session SetFlowSession must not snap back to `session.currentStep` —
+ * tracking a button event enqueues `check_sessions`, which can push a stale
+ * current step. Web `FlowApp` `updateSession` keeps the local step for the
+ * same session id (and only falls back if that step was deleted from the
+ * version).
  */
 export function reduceFlowSessionViewState(
   state: FlowSessionViewState,
@@ -31,21 +41,49 @@ export function reduceFlowSessionViewState(
     case 'sessionChange':
       return {
         session: event.session,
-        currentStepId: event.session?.currentStep?.id ?? null,
+        currentStepId: resolveSessionChangeStepId(state, event.session),
+        stepShowNonce: state.session?.id === event.session?.id ? state.stepShowNonce : 0,
       };
     case 'goToStep':
       return {
         ...state,
         currentStepId: event.stepId,
+        stepShowNonce: state.stepShowNonce + 1,
       };
     case 'flowEnded':
       return {
         session: null,
         currentStepId: null,
+        stepShowNonce: 0,
       };
   }
 }
 
+function resolveSessionChangeStepId(
+  state: FlowSessionViewState,
+  session: FlowSessionFragment | null,
+): string | null {
+  if (session == null) {
+    return null;
+  }
+  if (state.session?.id !== session.id || state.currentStepId == null) {
+    return session.currentStep?.id ?? null;
+  }
+  const previousStep = state.session.version.steps.find((step) => step.id === state.currentStepId);
+  const byCrossVersionId =
+    previousStep == null
+      ? undefined
+      : session.version.steps.find((step) => step.crossVersionId === previousStep.crossVersionId);
+  if (byCrossVersionId) {
+    return byCrossVersionId.id;
+  }
+  const byId = session.version.steps.find((step) => step.id === state.currentStepId);
+  if (byId) {
+    return byId.id;
+  }
+  return session.currentStep?.id ?? null;
+}
+
 export function resolveCurrentStep(
   session: FlowSessionFragment | null,
   currentStepId: string | null,

package/src/runtime/isolateCall.ts

@@ -0,0 +1,53 @@
+import { reportSdkError } from './reportSdkError';
+
+/**
+ * True for missing `init` / `identify`, invalid event or attribute names — not
+ * for transport `UserflowAuthError`s. The flag is set at the throw site on
+ * `UserflowAuthError.isHostContract`; message text is not consulted.
+ * Matched by `error.name` plus the flag so mocked test doubles with the same
+ * name are treated like the real class.
+ */
+export function isHostContractError(error: unknown): boolean {
+  if (!(error instanceof Error) || error.name !== 'UserflowAuthError') {
+    return false;
+  }
+  return (error as { isHostContract?: boolean }).isHostContract === true;
+}
+
+export interface IsolateAsyncOptions {
+  /**
+   * When true (default), host-contract `UserflowAuthError`s are rethrown so the
+   * host sees integration misuse. Internal fire-and-forget paths pass false.
+   */
+  rethrowHostContract?: boolean;
+}
+
+/** Run synchronous SDK work; swallow and report anything except host-contract errors. */
+export function isolateSync<T>(scope: string, work: () => T): T | undefined {
+  try {
+    return work();
+  } catch (error) {
+    if (isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}
+
+/** Run async SDK work; swallow and report anything except host-contract errors. */
+export async function isolateAsync<T>(
+  scope: string,
+  work: () => Promise<T>,
+  options?: IsolateAsyncOptions,
+): Promise<T | undefined> {
+  try {
+    return await work();
+  } catch (error) {
+    if ((options?.rethrowHostContract ?? true) && isHostContractError(error)) {
+      throw error;
+    }
+    reportSdkError(scope, error);
+    return undefined;
+  }
+}

package/src/runtime/reportSdkError.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal reporter for SDK failures that must not reach the host app.
+ * Always logs (not `__DEV__`-only) so a swallowed error is still diagnosable.
+ *
+ * Uses `console.warn`, not `console.error`: React Native release builds forward
+ * `console.error` to the native exception manager (Crashlytics / Sentry), which
+ * would report an isolated tooltip failure as a host crash.
+ */
+export function reportSdkError(scope: string, error: unknown, extra?: unknown): void {
+  // eslint-disable-next-line no-console -- isolation diagnostics must reach host logs
+  console.warn('[Userflow] isolated error', scope, error, extra ?? '');
+}