@userflow-tech/react-native 0.1.1 → 0.3.0

package/src/index.ts

@@ -9,6 +9,7 @@
  */
 
 import type {
+  PublicAttributes,
   UserflowAttributes,
   UserflowConfig,
   UserflowEventAttributes,
@@ -16,6 +17,7 @@ import type {
   UserflowIdentifyOptions,
   UserflowInitOptions,
   UserflowTrackOptions,
+  UserflowUpdateGroupOptions,
 } from '@userflow-tech/core';
 
 import './anchors/autoAnchor';
@@ -34,30 +36,69 @@ import {
   startDeepLinking,
   stopDeepLinking,
 } from './deepLinking';
+import {
+  cacheDeviceContextAtInit,
+  getCachedDeviceContext,
+  logDeviceContext as logDeviceContextToConsole,
+  mergeDeviceContextUserAttributes,
+  type DeviceContext,
+} from './deviceContext';
+import { setEvalJsBridgeHandlers } from './evalJs/evalJsBridge';
+import { evalJsController } from './evalJs/evalJsController';
+import {
+  cacheHostAppVersionAtInit,
+  getCachedHostAppVersion,
+  logHostAppVersion as logHostAppVersionToConsole,
+  mergeHostAppVersionUserAttributes,
+  type HostAppVersion,
+} from './hostAppVersion';
 import { LifecycleController } from './lifecycle';
-import { setHostOnNavigate, type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
+import {
+  openFlowNavigateUrl,
+  setHostOnNavigate,
+  type FlowNavigateHandler,
+} from './navigation/openFlowNavigateUrl';
 import { NetworkController } from './network';
 import { getPairingController, installPairingController } from './pairing/pairingRuntime';
+import {
+  attachBannerSessionEngine,
+  clearBannerSessionEngineLocalSession,
+  getBannerSessionEngine,
+  resetBannerSessionEngine,
+} from './runtime/bannerEngine';
 import {
   attachClientConditionEngine,
   resetClientConditionEngine,
 } from './runtime/clientConditions';
 import {
   attachFlowSessionEngine,
+  cancelPendingDraftEnd,
   clearFlowSessionEngineLocalSession,
+  endDraftFlowSession,
+  endEvalJsFlowSession,
   getFlowSessionEngine,
   hasActiveFlowSession,
   resetFlowSessionEngine,
 } from './runtime/flowEngine';
+import { isolateAsync, isolateSync } from './runtime/isolateCall';
 import { getUserflowCore } from './runtime/userflowCore';
 import {
   disableScreenTracking,
   enableScreenTracking,
+  getCurrentScreenLocation,
   handleScreenChange,
+  reportCurrentScreen,
+  SCREEN_VIEWED_EVENT,
+  screenViewedAttributes,
   setScreenChangeReporter,
 } from './screenTracker';
+import { setSurfaceInteractionBlocking as setSurfaceInteractionBlockingConfig } from './surfaces/surfaceInteractionConfig';
 
 export { SDK_VERSION } from './version';
+export type { DeviceContext, DeviceOs, DeviceType, SdkPlatform } from './deviceContext';
+export type { HostAppVersion, HostAppVersionSource } from './hostAppVersion';
+export { EmbedBannerPlaceholder } from './runtime/EmbedBannerPlaceholder';
+export type { EmbedBannerPlaceholderProps } from './runtime/EmbedBannerPlaceholder';
 export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
 export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
 export { useFlowSessionState } from './runtime/useFlowSessionState';
@@ -103,9 +144,18 @@ export type UserflowInitConfig = UserflowInitOptions & {
    * Defaults to `https://e.userflow.com`.
    */
   pairingEndpoint?: string;
+  /**
+   * Override auto-detected native store version. When omitted, the SDK reads
+   * the host app's marketing version at init (Expo modules or native constants).
+   */
+  appVersion?: string;
+  /** Optional build number paired with {@link appVersion}. */
+  appBuild?: string;
 };
 
 export type {
+  PublicAttributeChange,
+  PublicAttributes,
   UserflowAttributes,
   UserflowConfig,
   UserflowEventAttributes,
@@ -113,6 +163,7 @@ export type {
   UserflowIdentifyOptions,
   UserflowInitOptions,
   UserflowTrackOptions,
+  UserflowUpdateGroupOptions,
 } from '@userflow-tech/core';
 
 const core = getUserflowCore();
@@ -123,14 +174,20 @@ const lifecycle = new LifecycleController({
     core.resume();
     // After reconnect, flush mid-flow client messages that failed while offline.
     void getFlowSessionEngine(core).flushPendingSends();
+    void getBannerSessionEngine(core).flushPendingSends();
   },
   clearLocalSession: () => {
     clearFlowSessionEngineLocalSession();
+    clearBannerSessionEngineLocalSession();
     // Engine may not exist yet; still clear any transport join resume id.
     core.setFlowSessionId(null);
+    core.setBannerSessionId(null);
   },
   ensureAlive: () => core.ensureAlive(),
   hasActiveSession: () => hasActiveFlowSession(),
+  onScreenResume: () => {
+    reportCurrentScreen();
+  },
 });
 
 const network = new NetworkController({
@@ -138,26 +195,54 @@ const network = new NetworkController({
   ensureAlive: () => core.ensureAlive(),
 });
 
+/** True when a screen was reported before identify, so first identify should emit `screen_viewed`. */
+let screenViewedAwaitingIdentify = false;
+
+function armScreenViewedForNextIdentify(): void {
+  if (getCurrentScreenLocation() != null) {
+    screenViewedAwaitingIdentify = true;
+  }
+}
+
 function wireScreenChangeReporter(): void {
   setScreenChangeReporter((location) => {
-    lifecycle.reportActivity();
-    const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
-    notifyAnchorScreenChange(screenKey);
-    anchorChangeTicker.notify();
-    if (__DEV__) {
+    isolateSync('updateScreen', () => {
+      lifecycle.reportActivity();
+      const screenKey = 'path' in location ? `path:${location.path}` : `screen:${location.screen}`;
+      notifyAnchorScreenChange(screenKey);
+      anchorChangeTicker.notify();
       const identified = core.getUserId() != null;
-      // eslint-disable-next-line no-console -- intentional development diagnostic
-      console.log(
-        '[Userflow] updateScreen',
-        location,
-        identified ? '(push UpdateClientContext)' : '(buffered until identify)',
-      );
-    }
-    // Mirrors web: only pushes UpdateClientContext after identify; before that the
-    // location is remembered and included on the next end-user channel join.
-    void core.updateScreen(location).catch(() => {
-      // Screen updates are best-effort; connection drops / rate limits should not
-      // surface to the host app's navigation path.
+      if (__DEV__) {
+        // eslint-disable-next-line no-console -- intentional development diagnostic
+        console.log(
+          '[Userflow] updateScreen',
+          location,
+          identified ? '(push UpdateClientContext)' : '(buffered until identify)',
+        );
+      }
+      // Mirrors web: only pushes UpdateClientContext after identify; before that the
+      // location is remembered and included on the next end-user channel join.
+      void isolateAsync('updateScreen', () => core.updateScreen(location), {
+        rethrowHostContract: false,
+      });
+
+      const attrs = screenViewedAttributes(location);
+      if (!attrs) return;
+      if (!identified) {
+        screenViewedAwaitingIdentify = true;
+        return;
+      }
+      screenViewedAwaitingIdentify = false;
+      if (__DEV__) {
+        // eslint-disable-next-line no-console -- intentional development diagnostic
+        console.log('[Userflow] track', SCREEN_VIEWED_EVENT, attrs);
+      }
+      // Screen views are best-effort; connection drops / rate limits should not
+      // surface to the host app's navigation path. Each accepted screen sends
+      // UpdateClientContext + TrackEvent (two slots of the 100/min cap).
+      void isolateAsync('track', () => core.track(SCREEN_VIEWED_EVENT, attrs), {
+        rethrowHostContract: false,
+      });
     });
   });
 }
@@ -171,11 +256,21 @@ function wireDeepLinking(): void {
   });
 }
 
+function mergeSystemUserAttributes<T extends Record<string, unknown>>(
+  attributes?: T,
+): (T & Record<string, unknown>) | undefined {
+  return mergeDeviceContextUserAttributes(mergeHostAppVersionUserAttributes(attributes));
+}
+
 async function afterIdentify(): Promise<void> {
   attachFlowSessionEngine(core);
+  attachBannerSessionEngine(core);
   attachClientConditionEngine(core);
   getPairingController(core).notifyIdentified();
   lifecycle.reportActivity();
+  if (screenViewedAwaitingIdentify) {
+    reportCurrentScreen();
+  }
   try {
     await flushPendingPreviewToken();
   } catch {
@@ -190,6 +285,11 @@ async function afterIdentify(): Promise<void> {
 export const Userflow = {
   /** Validate credentials, store configuration, and wire app-lifecycle handling. */
   init(config: UserflowInitConfig): Promise<UserflowConfig> {
+    cacheHostAppVersionAtInit({
+      ...(config.appVersion !== undefined ? { appVersion: config.appVersion } : {}),
+      ...(config.appBuild !== undefined ? { appBuild: config.appBuild } : {}),
+    });
+    cacheDeviceContextAtInit();
     setHostOnNavigate(config.onNavigate);
     lifecycle.start();
     network.start();
@@ -206,15 +306,23 @@ export const Userflow = {
       clearLocalSession: () => {
         clearFlowSessionEngineLocalSession();
         core.setFlowSessionId(null);
+        clearBannerSessionEngineLocalSession();
+        core.setBannerSessionId(null);
+        evalJsController.reset();
       },
+      endDraftSession: endDraftFlowSession,
+      cancelPendingDraftEnd,
     });
     pairing.notifyInitStarted();
     void pairing.start();
 
     return core.init(config).then(
-      async (resolved) => {
+      (resolved) => {
         enableScreenTracking();
-        await pairing.notifyInitialized();
+        // Pairing connect can take the full socket timeout. Identify, and the
+        // end-user socket that delivers the preview, must not wait on it.
+        // notifyInitialized never rejects; the relay queue covers either order.
+        void pairing.notifyInitialized();
         return resolved;
       },
       (error: unknown) => {
@@ -254,9 +362,13 @@ export const Userflow = {
     if (previousId != null && previousId !== userId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
+      clearBannerSessionEngineLocalSession();
+      core.setBannerSessionId(null);
+      evalJsController.reset();
       await clearAnonymousId();
+      armScreenViewedForNextIdentify();
     }
-    await core.identify(userId, attributes, options);
+    await core.identify(userId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
   /** Identify an anonymous user with a stable auto-generated id stored on device. */
@@ -269,8 +381,12 @@ export const Userflow = {
     if (previousId != null && previousId !== anonymousId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
+      clearBannerSessionEngineLocalSession();
+      core.setBannerSessionId(null);
+      evalJsController.reset();
+      armScreenViewedForNextIdentify();
     }
-    await core.identify(anonymousId, attributes, options);
+    await core.identify(anonymousId, mergeSystemUserAttributes(attributes), options);
     await afterIdentify();
   },
   /**
@@ -291,14 +407,38 @@ export const Userflow = {
     lifecycle.reportActivity();
     return core.group(groupId, attributes, options);
   },
-  /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
+  /**
+   * Upsert attributes for the current user without re-identifying.
+   * Requires a prior {@link identify}. Flow button "Set user attribute" actions
+   * use this path.
+   */
+  updateUser(attributes?: PublicAttributes): Promise<void> {
+    lifecycle.reportActivity();
+    return core.updateUser(attributes);
+  },
+  /**
+   * Upsert attributes for the current group / membership without re-grouping.
+   * Requires a prior {@link group}.
+   */
+  updateGroup(attributes?: PublicAttributes, options?: UserflowUpdateGroupOptions): Promise<void> {
+    lifecycle.reportActivity();
+    return core.updateGroup(attributes, options);
+  },
+  /**
+   * Record a custom analytics event for the current user (and group, unless `userOnly`).
+   * Operational failures (network, rate limit, unexpected SDK bugs) are isolated and
+   * logged; the promise still resolves. `UserflowAuthError` for missing
+   * `init` / `identify` or an invalid event name still rejects.
+   */
   track(
     name: string,
     attributes?: UserflowEventAttributes,
     options?: UserflowTrackOptions,
   ): Promise<void> {
-    lifecycle.reportActivity();
-    return core.track(name, attributes, options);
+    return isolateAsync('track', async () => {
+      lifecycle.reportActivity();
+      await core.track(name, attributes, options);
+    }).then(() => undefined);
   },
   /** The currently identified user id, or `null` before identify. */
   getUserId(): string | null {
@@ -308,15 +448,36 @@ export const Userflow = {
   getAttributes(): UserflowAttributes {
     return core.getAttributes();
   },
+  /**
+   * Host app marketing version cached during {@link init}, or `null` before init
+   * or when auto-detection and any init override are unavailable.
+   */
+  getHostAppVersion(): HostAppVersion | null {
+    return getCachedHostAppVersion();
+  },
+  /**
+   * Platform metadata cached during {@link init} (`sdk`, `deviceOs`, `deviceType`),
+   * or `null` before init.
+   */
+  getDeviceContext(): DeviceContext | null {
+    return getCachedDeviceContext();
+  },
   /** The flow session engine (created lazily; attach runs after identify). */
   getFlowSessionEngine() {
     return getFlowSessionEngine(core);
   },
+  /** The banner session engine (created lazily; attach runs after identify). */
+  getBannerSessionEngine() {
+    return getBannerSessionEngine(core);
+  },
   /** Clears the current user identity and disconnects from Userflow. */
   async reset(): Promise<void> {
     resetClientConditionEngine();
     resetFlowSessionEngine();
+    resetBannerSessionEngine();
+    evalJsController.reset();
     core.reset();
+    armScreenViewedForNextIdentify();
     await clearAnonymousId();
   },
   /** Remove app-lifecycle, network, and deep-link subscriptions (call on unmount / teardown). */
@@ -324,7 +485,9 @@ export const Userflow = {
     getPairingController(core).stop();
     lifecycle.stop();
     network.stop();
+    evalJsController.reset();
     disableScreenTracking();
+    screenViewedAwaitingIdentify = false;
     stopDeepLinking();
   },
   /**
@@ -334,7 +497,9 @@ export const Userflow = {
    * host-app activity the SDK does not observe.
    */
   reportActivity(): void {
-    lifecycle.reportActivity();
+    isolateSync('reportActivity', () => {
+      lifecycle.reportActivity();
+    });
   },
   /**
    * Report the active React Navigation (or manual) screen name. Prefer
@@ -343,7 +508,9 @@ export const Userflow = {
    * with `screen` set (Expo Router pathnames use `path` via the Expo helper).
    */
   updateScreen(screenName: string | undefined): void {
-    handleScreenChange(screenName ? { screen: screenName } : undefined);
+    isolateSync('updateScreen', () => {
+      handleScreenChange(screenName ? { screen: screenName } : undefined);
+    });
   },
   /**
    * Sticky header/footer insets applied when scrolling tooltip targets into
@@ -359,4 +526,65 @@ export const Userflow = {
   setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void {
     setCustomScrollIntoViewConfig(fn);
   },
+  /**
+   * When true (default), tooltip cutout bands and step-transition exit block
+   * taps on the host app underneath. Pass `false` to restore legacy pass-through
+   * tooltip backdrop behavior (dim bands only; `tooltipTargetBlocked` hole seal
+   * is unchanged). Modals always block. Takes effect on the next surface re-render.
+   */
+  setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void {
+    setSurfaceInteractionBlockingConfig(enabled);
+  },
+  /**
+   * Values exposed to Evaluate JavaScript as `window.userflowContext.host`
+   * (language, theme, tab bar height, and anything else the page used to read
+   * from the DOM). Replaces the previous host bag.
+   */
+  setEvalJsContext(values: Record<string, unknown> | null | undefined): void {
+    evalJsController.setHostContext(values ?? {});
+  },
+  /**
+   * Log the host app's native marketing version (store version), not
+   * {@link SDK_VERSION}, and the platform OS (`ios` / `android` / …).
+   * Prefers `expo-application` / `expo-constants` when present; otherwise reads
+   * `NativeModules.RNDeviceInfo` from the bundled device-info native module.
+   */
+  logHostAppVersion(): void {
+    logHostAppVersionToConsole();
+  },
+  /**
+   * Log cached user-attribute values (`sdk`, `device_os`, `device_type`).
+   * Requires {@link init}; before init, logs that init is required.
+   */
+  logDeviceContext(): void {
+    logDeviceContextToConsole();
+  },
 };
+
+setEvalJsBridgeHandlers({
+  track: (name, attributes) => {
+    void Userflow.track(name, attributes as UserflowAttributes | undefined);
+  },
+  updateUser: (attributes) => {
+    void Userflow.updateUser(attributes as PublicAttributes);
+  },
+  updateGroup: (attributes, options) => {
+    void Userflow.updateGroup(
+      attributes as PublicAttributes,
+      options?.membership ? { membership: options.membership as PublicAttributes } : undefined,
+    );
+  },
+  openUrl: (url) => {
+    void isolateAsync('eval-js-open-url', () => openFlowNavigateUrl(url), {
+      rethrowHostContract: false,
+    });
+  },
+  endFlow: (sessionIds) => {
+    void isolateAsync('eval-js-end-flow', () => endEvalJsFlowSession(sessionIds), {
+      rethrowHostContract: false,
+    });
+  },
+  warn: (message) => {
+    console.warn(message);
+  },
+});

package/src/lifecycle.ts

@@ -49,8 +49,16 @@ export interface LifecycleControllerDeps {
    * Do not call while lifecycle-suspended — use {@link resume} instead.
    */
   ensureAlive: () => void;
-  /** True while any mid-flow session (live or draft/preview) is on screen. */
+  /**
+   * True while a mid-flow session is held, including one Temporarily Hide is
+   * suppressing. Idle suspend waits so a later attribute update can still unhide it.
+   */
   hasActiveSession: () => boolean;
+  /**
+   * Re-fire the current screen view after a real background (away past grace).
+   * Not called for Control Center / biometric blurs inside the grace window.
+   */
+  onScreenResume?: () => void;
   scheduler?: LifecycleScheduler;
   now?: () => number;
   /** Override for tests; defaults to {@link SUSPEND_GRACE_MS}. */
@@ -82,6 +90,7 @@ export class LifecycleController {
   private readonly clearLocalSession: () => void;
   private readonly ensureAlive: () => void;
   private readonly hasActiveSession: () => boolean;
+  private readonly onScreenResume: (() => void) | undefined;
   private readonly scheduler: LifecycleScheduler;
   private readonly now: () => number;
   private readonly suspendGraceMs: number;
@@ -103,6 +112,7 @@ export class LifecycleController {
     this.clearLocalSession = deps.clearLocalSession;
     this.ensureAlive = deps.ensureAlive;
     this.hasActiveSession = deps.hasActiveSession;
+    this.onScreenResume = deps.onScreenResume;
     this.scheduler = deps.scheduler ?? defaultScheduler;
     this.now = deps.now ?? (() => Date.now());
     this.suspendGraceMs = deps.suspendGraceMs ?? SUSPEND_GRACE_MS;
@@ -210,6 +220,7 @@ export class LifecycleController {
     this.resume();
     this.suspended = false;
     this.scheduleIdleTimer();
+    this.onScreenResume?.();
   }
 
   private scheduleGraceTimer(): void {

package/src/navigation/WithUserflowReactNavigation.tsx

@@ -4,13 +4,15 @@ import type {
   NavigationState,
   ParamListBase,
 } from '@react-navigation/native';
-import { cloneElement, isValidElement, useCallback, useEffect } from 'react';
+import { cloneElement, isValidElement, useCallback, useEffect, useRef } from 'react';
 import type React from 'react';
 
+import { isolateSync } from '../runtime/isolateCall';
 import { handleScreenChange } from '../screenTracker';
 
 import { chainCallbacks } from './chainCallbacks';
 import { getActiveRouteName } from './getActiveRouteName';
+import { isOverlayPresentation, readNavigationPresentation } from './isOverlayPresentation';
 import { setReactNavigationRef } from './openFlowNavigateUrl';
 
 type NavigationContainerChildProps = {
@@ -51,6 +53,7 @@ export function WithUserflowReactNavigation({
   children,
 }: WithUserflowReactNavigationProps): React.ReactElement {
   const navigationRef = useNavigationContainerRef<ParamListBase>();
+  const overlayWasFocusedRef = useRef(false);
 
   useEffect(() => {
     setReactNavigationRef(navigationRef);
@@ -59,18 +62,34 @@ export function WithUserflowReactNavigation({
     };
   }, [navigationRef]);
 
+  const reportFocusedScreen = useCallback(
+    (state?: NavigationState) => {
+      isolateSync('react-navigation-screen', () => {
+        if (isOverlayPresentation(readNavigationPresentation(navigationRef))) {
+          overlayWasFocusedRef.current = true;
+          return;
+        }
+        const name = getActiveRouteName(state ?? navigationRef.getRootState());
+        handleScreenChange(
+          name ? { screen: name } : undefined,
+          overlayWasFocusedRef.current ? { force: true } : undefined,
+        );
+        overlayWasFocusedRef.current = false;
+      });
+    },
+    [navigationRef],
+  );
+
   const handleReady = useCallback(() => {
     setReactNavigationRef(navigationRef);
-    const name = getActiveRouteName(navigationRef.getRootState());
-    handleScreenChange(name ? { screen: name } : undefined);
-  }, [navigationRef]);
+    reportFocusedScreen();
+  }, [navigationRef, reportFocusedScreen]);
 
   const handleStateChange = useCallback(
     (state?: NavigationState) => {
-      const name = getActiveRouteName(state ?? navigationRef.getRootState());
-      handleScreenChange(name ? { screen: name } : undefined);
+      reportFocusedScreen(state);
     },
-    [navigationRef],
+    [reportFocusedScreen],
   );
 
   if (!isValidElement(children)) {

package/src/navigation/isOverlayPresentation.ts

@@ -0,0 +1,76 @@
+/** React Navigation `options.presentation` values that are overlays, not screens. */
+const OVERLAY_PRESENTATIONS = new Set([
+  'modal',
+  'transparentModal',
+  'containedModal',
+  'containedTransparentModal',
+  'fullScreenModal',
+  'formSheet',
+  'pageSheet',
+]);
+
+/** True when the focused route is a modal / sheet overlay, not a screen navigation. */
+export function isOverlayPresentation(presentation: unknown): boolean {
+  return typeof presentation === 'string' && OVERLAY_PRESENTATIONS.has(presentation);
+}
+
+type OptionsHolder = {
+  getCurrentOptions?: () => { presentation?: string } | undefined;
+};
+
+function presentationFromHolder(holder: unknown): string | undefined {
+  if (holder == null || typeof holder !== 'object') return undefined;
+  const getCurrentOptions = (holder as OptionsHolder).getCurrentOptions;
+  if (typeof getCurrentOptions !== 'function') return undefined;
+  try {
+    return getCurrentOptions()?.presentation;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads `presentation` from a React Navigation container ref.
+ * Accepts either a `NavigationContainerRef` or a `NavigationContainerRefWithCurrent`
+ * (`ref.current` is checked when the wrapper itself has no `getCurrentOptions`).
+ */
+export function readNavigationPresentation(ref: unknown): string | undefined {
+  const fromRef = presentationFromHolder(ref);
+  if (fromRef !== undefined) return fromRef;
+  if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    return presentationFromHolder((ref as { current: unknown }).current);
+  }
+  return undefined;
+}
+
+type StateListenerHolder = {
+  addListener?: (event: string, listener: () => void) => (() => void) | void;
+};
+
+function subscribeHolder(holder: unknown, listener: () => void): (() => void) | undefined {
+  if (holder == null || typeof holder !== 'object') return undefined;
+  const addListener = (holder as StateListenerHolder).addListener;
+  if (typeof addListener !== 'function') return undefined;
+  try {
+    const unsubscribe = addListener.call(holder, 'state', listener);
+    return typeof unsubscribe === 'function' ? unsubscribe : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Subscribes to React Navigation container `state` events.
+ * Accepts a `NavigationContainerRef` or `NavigationContainerRefWithCurrent`.
+ */
+export function subscribeNavigationState(
+  ref: unknown,
+  listener: () => void,
+): (() => void) | undefined {
+  const fromRef = subscribeHolder(ref, listener);
+  if (fromRef) return fromRef;
+  if (ref != null && typeof ref === 'object' && 'current' in ref) {
+    return subscribeHolder((ref as { current: unknown }).current, listener);
+  }
+  return undefined;
+}

package/src/navigation/openFlowNavigateUrl.ts

@@ -2,6 +2,7 @@ import type { NavigationContainerRef, ParamListBase } from '@react-navigation/na
 import { Linking } from 'react-native';
 
 import { isSafeUrl, openSafeUrl } from '../content/openSafeUrl';
+import { isolateAsync, isolateSync } from '../runtime/isolateCall';
 
 export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
 
@@ -75,7 +76,9 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
   if (!trimmed) return;
 
   if (hostOnNavigate) {
-    await hostOnNavigate(trimmed);
+    await isolateAsync('onNavigate', async () => {
+      await hostOnNavigate!(trimmed);
+    });
     return;
   }
 
@@ -86,13 +89,17 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
 
   if (isInAppNavigateUrl(trimmed)) {
     if (expoRouter) {
-      expoRouter.push(normalizeInAppPath(trimmed));
+      isolateSync('onNavigate', () => {
+        expoRouter!.push(normalizeInAppPath(trimmed));
+      });
       return;
     }
     if (navigationRef?.isReady()) {
-      const name = routeNameFromPath(trimmed);
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
-      (navigationRef as NavigationContainerRef<ParamListBase>).navigate(name as any);
+      isolateSync('onNavigate', () => {
+        const name = routeNameFromPath(trimmed);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- route names are host-defined
+        (navigationRef as NavigationContainerRef<ParamListBase>).navigate(name as any);
+      });
       return;
     }
   }