@userflow-tech/react-native 0.4.4 → 0.5.0

package/src/anchors/targetPressMonitor.ts

@@ -1,3 +1,8 @@
+import { gestureHandlerHandoff } from './gestureHandlerHandoff';
+import { TARGET_PRESS_TAP_SLOP, type TouchPoint, withinTapSlop } from './tapSlop';
+
+export { TARGET_PRESS_TAP_SLOP, type TouchPoint, withinTapSlop };
+
 /**
  * Active tooltip target-press subscription.
  *
@@ -19,29 +24,10 @@ export interface TargetPressSubscription {
   onPress: () => void;
 }
 
-/** Max finger travel (px) between start and end to count as a tap, not a scroll. */
-export const TARGET_PRESS_TAP_SLOP = 10;
-
 export function pointInRect(x: number, y: number, rect: TargetPressRect): boolean {
   return x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height;
 }
 
-export interface TouchPoint {
-  pageX: number;
-  pageY: number;
-}
-
-/** True when the finger moved no more than `slop` between start and end. */
-export function withinTapSlop(
-  start: TouchPoint,
-  end: TouchPoint,
-  slop: number = TARGET_PRESS_TAP_SLOP,
-): boolean {
-  const dx = end.pageX - start.pageX;
-  const dy = end.pageY - start.pageY;
-  return dx * dx + dy * dy <= slop * slop;
-}
-
 /**
  * True when start and end both land in `rect` and movement stays within tap
  * slop — mirrors a DOM click on the target without claiming the responder.
@@ -70,14 +56,25 @@ export type TouchIdentifier = number | string;
 export class TargetPressMonitor {
   private subscription: TargetPressSubscription | null = null;
   private touchStarts = new Map<TouchIdentifier, TouchPoint>();
+  private handoffStops = new Map<TouchIdentifier, () => void>();
 
   set(subscription: TargetPressSubscription | null): void {
     this.subscription = subscription;
     if (!subscription) {
       this.touchStarts.clear();
+      this.dropHandoffs();
     }
   }
 
+  /** Fingers with a recorded start that have not ended, cancelled, or been handed off. */
+  inProgressIdentifiers(): TouchIdentifier[] {
+    return [...this.touchStarts.keys()];
+  }
+
+  hasTouch(identifier: TouchIdentifier): boolean {
+    return this.touchStarts.has(identifier);
+  }
+
   clear(): void {
     this.set(null);
   }
@@ -113,6 +110,38 @@ export class TargetPressMonitor {
     }
   }
 
+  /**
+   * Gesture-handler cancelled this finger. Press if that handler later ends as
+   * a tap and the start (and the end, when the payload has one) is inside the
+   * current target rect.
+   */
+  handOffTouch(identifier: TouchIdentifier, handlerTags: readonly number[]): void {
+    const start = this.touchStarts.get(identifier);
+    if (!start) return;
+    this.touchStarts.delete(identifier);
+    this.handoffStops.get(identifier)?.();
+    if (!this.subscription || handlerTags.length === 0) return;
+    const stop = gestureHandlerHandoff.track({
+      identifier,
+      pageX: start.pageX,
+      pageY: start.pageY,
+      handlerTags,
+      onResolve: (end) => {
+        const sub = this.subscription;
+        if (!sub) return;
+        const rect = sub.getRect();
+        if (!rect || rect.width <= 0 || rect.height <= 0) return;
+        if (!pointInRect(start.pageX, start.pageY, rect)) return;
+        if (end && !pointInRect(end.pageX, end.pageY, rect)) return;
+        sub.onPress();
+      },
+    });
+    this.handoffStops.set(identifier, () => {
+      stop();
+      this.handoffStops.delete(identifier);
+    });
+  }
+
   /**
    * Drop in-progress gesture(s). With `identifier`, cancels that finger only;
    * otherwise clears all (e.g. blanket `onTouchCancel`).
@@ -120,15 +149,23 @@ export class TargetPressMonitor {
   cancelTouch(identifier?: TouchIdentifier): void {
     if (identifier == null) {
       this.touchStarts.clear();
+      this.dropHandoffs();
       return;
     }
     this.touchStarts.delete(identifier);
+    this.handoffStops.get(identifier)?.();
   }
 
   /** Test helper. */
   resetForTests(): void {
     this.subscription = null;
     this.touchStarts.clear();
+    this.dropHandoffs();
+  }
+
+  private dropHandoffs(): void {
+    for (const stop of this.handoffStops.values()) stop();
+    this.handoffStops.clear();
   }
 }
 

package/src/authoring/fingerprintFromInstance.ts

@@ -16,7 +16,7 @@ import { fibersMatch, resolveFiberPath } from '../anchors/fiber/resolveFiberPath
 import { createVisibleInstanceFilter } from '../anchors/isInstanceOnVisibleScreen';
 import * as semanticMatcher from '../anchors/semanticMatcher';
 import type { MatchMissReason } from '../anchors/semanticMatcher';
-import { getCurrentScreenLocation } from '../screenTracker';
+import { getCurrentScreenLocation, screenIdFromLocation } from '../screenTracker';
 
 import type { PickTarget } from './hitTest';
 
@@ -35,10 +35,9 @@ function deriveIdentityStrength(inst: AutoAnchorInstance): IdentityStrength {
 }
 
 function screenFromLocation(): { screenId: string; screenName?: string } {
-  const location = getCurrentScreenLocation();
-  if (!location) return { screenId: 'unknown' };
-  if ('path' in location) return { screenId: location.path, screenName: location.path };
-  return { screenId: location.screen, screenName: location.screen };
+  const screenId = screenIdFromLocation(getCurrentScreenLocation());
+  if (screenId === 'unknown') return { screenId };
+  return { screenId, screenName: screenId };
 }
 
 function deviceMetadata(): DeviceMetadata | undefined {

package/src/content/RichContentRenderer.tsx

@@ -8,6 +8,8 @@ import * as React from 'react';
 import type { TextStyle, ViewStyle } from 'react-native';
 import { Image, Platform, Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
 
+import { openFlowNavigateUrl } from '../navigation/openFlowNavigateUrl';
+
 import { StepButton } from './StepButton';
 import {
   deserializeRichContentDoc,
@@ -17,7 +19,6 @@ import {
 } from './deserialize';
 import { resolveImageFrame } from './imageLayout';
 import { migrateFlowBlocksIntoContent } from './migrateFlowBlocks';
-import { openSafeUrl } from './openSafeUrl';
 import {
   ROOT_CONTENT_GAP,
   WEB_CODE_BG_ALPHA,
@@ -401,7 +402,7 @@ function RenderedLink({
       accessibilityRole="link"
       accessibilityHint={href || undefined}
       onPress={() => {
-        void openSafeUrl(href);
+        void openFlowNavigateUrl(href);
       }}
     >
       <InlineChildren
@@ -480,7 +481,7 @@ function RenderedImage({
         accessibilityRole="link"
         accessibilityLabel="Image link"
         onPress={() => {
-          void openSafeUrl(href);
+          void openFlowNavigateUrl(href);
         }}
       >
         {framed}

package/src/content/openSafeUrl.ts

@@ -15,7 +15,9 @@ export function isSafeUrl(url: string | null | undefined): boolean {
     const parsed = new URL(trimmed);
     return ALLOWED_PROTOCOLS.has(parsed.protocol);
   } catch {
-    return false;
+    // Hermes / older runtimes can lack a full URL implementation; still allow
+    // obvious http(s) strings so NAVIGATE does not fall through to Expo Router.
+    return /^https?:\/\//i.test(trimmed);
   }
 }
 

package/src/expo-router/useUserflowExpoRouter.ts

@@ -6,7 +6,11 @@ import {
   readNavigationPresentation,
   subscribeNavigationState,
 } from '../navigation/isOverlayPresentation';
-import { setExpoRouterNavigator } from '../navigation/openFlowNavigateUrl';
+import {
+  mustNotUseExpoRouterPush,
+  shouldOpenExternalNavigateUrl,
+} from '../navigation/navigateUrlUtils';
+import { openFlowNavigateUrl, setExpoRouterNavigator } from '../navigation/openFlowNavigateUrl';
 import { handleScreenChange } from '../screenTracker';
 
 /**
@@ -73,6 +77,11 @@ export function useUserflowExpoRouter(): void {
   useEffect(() => {
     setExpoRouterNavigator({
       push: (href) => {
+        const trimmed = String(href).trim();
+        if (mustNotUseExpoRouterPush(trimmed) || shouldOpenExternalNavigateUrl(trimmed)) {
+          void openFlowNavigateUrl(trimmed);
+          return;
+        }
         router.push(href as never);
       },
     });

package/src/index.ts

@@ -80,13 +80,13 @@ import {
   attachFlowSessionEngine,
   cancelPendingDraftEnd,
   clearFlowSessionEngineLocalSession,
-  endDraftFlowSession,
   endEvalJsFlowSession,
   getFlowSessionEngine,
   hasActiveFlowSession,
   resetFlowSessionEngine,
 } from './runtime/flowEngine';
 import { isolateAsync, isolateSync } from './runtime/isolateCall';
+import { endDraftPreviewSessions, prepareForBuilderPreviewStart } from './runtime/previewStart';
 import { getUserflowCore } from './runtime/userflowCore';
 import {
   disableScreenTracking,
@@ -100,7 +100,9 @@ import {
 } from './screenTracker';
 import { setSurfaceInteractionBlocking as setSurfaceInteractionBlockingConfig } from './surfaces/surfaceInteractionConfig';
 
-export { SDK_VERSION } from './version';
+import { SDK_VERSION } from './version';
+
+export { SDK_VERSION };
 export type { DeviceContext, DeviceOs, DeviceType, SdkPlatform } from './deviceContext';
 export type { HostAppVersion, HostAppVersionSource } from './hostAppVersion';
 export { EmbedBannerPlaceholder } from './runtime/EmbedBannerPlaceholder';
@@ -141,8 +143,8 @@ export type {
 /** Configuration passed to {@link Userflow.init}. */
 export type UserflowInitConfig = UserflowInitOptions & {
   /**
-   * Optional host handler for flow NAVIGATE actions. When set, wins over
-   * React Navigation / Expo Router / Linking.
+   * Optional host handler for flow and banner NAVIGATE actions. When set, wins
+   * over React Navigation / Expo Router / Linking.
    */
   onNavigate?: FlowNavigateHandler;
   /**
@@ -297,6 +299,10 @@ export const Userflow = {
       ...(config.appBuild !== undefined ? { appBuild: config.appBuild } : {}),
     });
     warnIfInstallIncomplete();
+    if (__DEV__) {
+      // eslint-disable-next-line no-console -- intentional development diagnostic
+      console.log(`[Userflow] react-native SDK ${SDK_VERSION} (source)`);
+    }
     cacheDeviceContextAtInit();
     setHostOnNavigate(config.onNavigate);
     lifecycle.start();
@@ -311,6 +317,7 @@ export const Userflow = {
     // the success path makes a failed init look like a broken deep link.
     const pairing = installPairingController(core, {
       ...(config.pairingEndpoint !== undefined ? { pairingEndpoint: config.pairingEndpoint } : {}),
+      prepareForBuilderPreviewStart: () => prepareForBuilderPreviewStart(core),
       clearLocalSession: () => {
         clearFlowSessionEngineLocalSession();
         core.setFlowSessionId(null);
@@ -318,7 +325,7 @@ export const Userflow = {
         core.setBannerSessionId(null);
         evalJsController.reset();
       },
-      endDraftSession: endDraftFlowSession,
+      endDraftSession: endDraftPreviewSessions,
       cancelPendingDraftEnd,
     });
     pairing.notifyInitStarted();
@@ -354,8 +361,8 @@ export const Userflow = {
     return getPairingController(core).exitPreview();
   },
   /**
-   * Override or clear the host NAVIGATE handler (same as `init({ onNavigate })`).
-   * Wins over React Navigation / Expo Router / Linking when set.
+   * Override or clear the host NAVIGATE handler for flows and banners (same as
+   * `init({ onNavigate })`). Wins over React Navigation / Expo Router / Linking.
    */
   setOnNavigate(handler: FlowNavigateHandler | null | undefined): void {
     setHostOnNavigate(handler);
@@ -372,7 +379,9 @@ export const Userflow = {
     if (previousId != null && previousId !== userId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
-      clearBannerSessionEngineLocalSession();
+      clearFlowSessionEngineLocalSession();
+      clearBannerSessionEngineLocalSession({ rememberDraftForPreviewEnd: false });
+      core.setFlowSessionId(null);
       core.setBannerSessionId(null);
       evalJsController.reset();
       await clearAnonymousId();
@@ -391,7 +400,9 @@ export const Userflow = {
     if (previousId != null && previousId !== anonymousId) {
       resetClientConditionEngine();
       core.setClientConditions([]);
-      clearBannerSessionEngineLocalSession();
+      clearFlowSessionEngineLocalSession();
+      clearBannerSessionEngineLocalSession({ rememberDraftForPreviewEnd: false });
+      core.setFlowSessionId(null);
       core.setBannerSessionId(null);
       evalJsController.reset();
       armScreenViewedForNextIdentify();

package/src/installCheck.ts

@@ -10,7 +10,7 @@ export const INSTALL_ASYNC_STORAGE_LINE =
   '- @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.';
 
 export const INSTALL_VIEW_SHOT_LINE =
-  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install react-native-view-shot@^5.0.0 and rebuild. On Expo SDK 54, pin ^5.0.0; an unpinned npx expo install resolves 4.0.3.';
+  '- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, an unpinned npx expo install resolves 4.0.3.';
 
 export const INSTALL_WEBVIEW_LINE =
   '- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.';
@@ -36,9 +36,9 @@ export const INSTALL_SAFE_AREA_WARNING =
 export function formatViewShotVersionWarning(version: string): string {
   return (
     `[Userflow] react-native-view-shot@${version} is older than 5.0.0, so Builder element selection may not get a screenshot. ` +
-    'Install react-native-view-shot@^5.0.0 in the same command as the SDK and rebuild. ' +
-    'Do not retry the install with --force or --legacy-peer-deps; that leaves this version in place. ' +
-    'On Expo SDK 54, pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.\n' +
+    'On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it, and rebuild. ' +
+    'Otherwise install react-native-view-shot@^5.0.0 in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add "react-native-view-shot" to expo.install.exclude. ' +
+    'Do not retry the install with --force or --legacy-peer-deps; that leaves this version in place.\n' +
     INSTALL_CHECK_FOOTER
   );
 }

package/src/navigation/navigateUrlUtils.ts

@@ -0,0 +1,100 @@
+const ABSOLUTE_WEB_URL = /^https?:\/\//i;
+
+/** Hostname.tld with optional port, path, query, or hash — not an in-app screen name like `Profile`. */
+const BARE_EXTERNAL_HOST =
+  /^[\w.-]+\.[a-z]{2,}(?::\d+)?(?:\/[^\s?#]*)?(?:\?[^\s#]*)?(?:#[^\s]*)?$/i;
+
+function isAllowlistedWebUrl(url: string): boolean {
+  const trimmed = url.trim();
+  if (!trimmed) {
+    return false;
+  }
+  if (!ABSOLUTE_WEB_URL.test(trimmed) && !/^mailto:/i.test(trimmed) && !/^tel:/i.test(trimmed)) {
+    return false;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return (
+      parsed.protocol === 'http:' ||
+      parsed.protocol === 'https:' ||
+      parsed.protocol === 'mailto:' ||
+      parsed.protocol === 'tel:'
+    );
+  } catch {
+    return ABSOLUTE_WEB_URL.test(trimmed);
+  }
+}
+
+/** Fix common builder typos before classification (`https:/google.com`). */
+export function normalizeNavigateUrlInput(url: string): string {
+  const trimmed = url.trim();
+  return trimmed.replace(/^(https?):\/(?!\/)/i, '$1://');
+}
+
+/** Prefix `https://` when the builder URL omitted the scheme (e.g. `google.com`). */
+export function normalizeExternalNavigateUrl(url: string): string {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (ABSOLUTE_WEB_URL.test(trimmed)) {
+    return trimmed;
+  }
+  if (BARE_EXTERNAL_HOST.test(trimmed) && !trimmed.startsWith('/')) {
+    return `https://${trimmed}`;
+  }
+  return trimmed;
+}
+
+/** True when the URL should open outside the app (browser / mail / tel). */
+export function shouldOpenExternalNavigateUrl(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) {
+    return false;
+  }
+  if (isAllowlistedWebUrl(trimmed)) {
+    return true;
+  }
+  if (ABSOLUTE_WEB_URL.test(trimmed)) {
+    return true;
+  }
+  if (/^mailto:/i.test(trimmed) || /^tel:/i.test(trimmed)) {
+    return true;
+  }
+  if (BARE_EXTERNAL_HOST.test(trimmed) && !trimmed.startsWith('/')) {
+    return true;
+  }
+  return false;
+}
+
+/** True for http(s) / mailto / tel (external). */
+export function isExternalNavigateUrl(url: string): boolean {
+  return shouldOpenExternalNavigateUrl(url);
+}
+
+/** Path-like in-app URL: leading slash, or no scheme. */
+export function isInAppNavigateUrl(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) return false;
+  if (shouldOpenExternalNavigateUrl(trimmed)) return false;
+  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
+  return true;
+}
+
+/** Never pass absolute / external URLs to Expo Router `push`. */
+export function mustNotUseExpoRouterPush(url: string): boolean {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (!trimmed) return false;
+  if (shouldOpenExternalNavigateUrl(trimmed)) return true;
+  if (trimmed.includes('://')) return true;
+  return false;
+}
+
+export function normalizeInAppPath(url: string): string {
+  const trimmed = normalizeNavigateUrlInput(url);
+  if (trimmed.startsWith('/')) return trimmed;
+  return `/${trimmed}`;
+}
+
+export function routeNameFromPath(path: string): string {
+  const normalized = normalizeInAppPath(path).replace(/^\//, '');
+  const [first] = normalized.split(/[/?#]/);
+  return first || normalized;
+}

package/src/navigation/openExternalNavigateUrl.ts

@@ -0,0 +1,9 @@
+import { openSafeUrl } from '../content/openSafeUrl';
+
+import { normalizeExternalNavigateUrl } from './navigateUrlUtils';
+
+/** Open http(s)/mailto/tel via Linking (documented SDK behavior). */
+export async function openExternalNavigateUrl(url: string): Promise<void> {
+  const external = normalizeExternalNavigateUrl(url);
+  await openSafeUrl(external);
+}

package/src/navigation/openFlowNavigateUrl.ts

@@ -1,9 +1,18 @@
 import type { NavigationContainerRef, ParamListBase } from '@react-navigation/native';
-import { Linking } from 'react-native';
 
-import { isSafeUrl, openSafeUrl } from '../content/openSafeUrl';
+import { isSafeUrl } from '../content/openSafeUrl';
 import { isolateAsync, isolateSync } from '../runtime/isolateCall';
 
+import {
+  isInAppNavigateUrl,
+  mustNotUseExpoRouterPush,
+  normalizeInAppPath,
+  normalizeNavigateUrlInput,
+  routeNameFromPath,
+  shouldOpenExternalNavigateUrl,
+} from './navigateUrlUtils';
+import { openExternalNavigateUrl } from './openExternalNavigateUrl';
+
 export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
 
 export type ExpoRouterLike = {
@@ -31,38 +40,19 @@ export function setExpoRouterNavigator(router: ExpoRouterLike | null | undefined
   expoRouter = router ?? null;
 }
 
-/** True for http(s) / mailto / tel (external). */
-export function isExternalNavigateUrl(url: string): boolean {
-  return isSafeUrl(url);
-}
-
-/** Path-like in-app URL: leading slash, or no scheme. */
-export function isInAppNavigateUrl(url: string): boolean {
-  const trimmed = url.trim();
-  if (!trimmed) return false;
-  if (isExternalNavigateUrl(trimmed)) return false;
-  if (/^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return false;
-  return true;
-}
-
-function normalizeInAppPath(url: string): string {
-  const trimmed = url.trim();
-  if (trimmed.startsWith('/')) return trimmed;
-  return `/${trimmed}`;
-}
-
-function routeNameFromPath(path: string): string {
-  const normalized = normalizeInAppPath(path).replace(/^\//, '');
-  const [first] = normalized.split(/[/?#]/);
-  return first || normalized;
-}
+export {
+  isExternalNavigateUrl,
+  isInAppNavigateUrl,
+  normalizeExternalNavigateUrl,
+  shouldOpenExternalNavigateUrl,
+} from './navigateUrlUtils';
 
 /**
  * Open a flow NAVIGATE url.
  *
  * Priority:
  * 1. Host `onNavigate` (custom schemes / exotic routing)
- * 2. External allowlisted schemes → Linking / `openSafeUrl`
+ * 2. External allowlisted schemes → in-app browser / Linking
  * 3. Path-like → Expo Router `push` or React Navigation `navigate`
  * 4. Fallback → Linking (best-effort)
  *
@@ -72,9 +62,18 @@ function routeNameFromPath(path: string): string {
  * `@userflow-tech/react-native/expo-router` under `UserflowProvider`.
  */
 export async function openFlowNavigateUrl(url: string): Promise<void> {
-  const trimmed = url.trim();
+  const trimmed = normalizeNavigateUrlInput(url);
   if (!trimmed) return;
 
+  if (__DEV__) {
+    // eslint-disable-next-line no-console -- intentional development diagnostic
+    console.log('[Userflow] NAVIGATE openFlowNavigateUrl', {
+      url: trimmed,
+      external: shouldOpenExternalNavigateUrl(trimmed),
+      inApp: isInAppNavigateUrl(trimmed),
+    });
+  }
+
   if (hostOnNavigate) {
     await isolateAsync('onNavigate', async () => {
       await hostOnNavigate!(trimmed);
@@ -82,13 +81,17 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
     return;
   }
 
-  if (isExternalNavigateUrl(trimmed)) {
-    await openSafeUrl(trimmed);
+  if (shouldOpenExternalNavigateUrl(trimmed)) {
+    await openExternalNavigateUrl(trimmed);
     return;
   }
 
   if (isInAppNavigateUrl(trimmed)) {
     if (expoRouter) {
+      if (mustNotUseExpoRouterPush(trimmed)) {
+        await openExternalNavigateUrl(trimmed);
+        return;
+      }
       isolateSync('onNavigate', () => {
         expoRouter!.push(normalizeInAppPath(trimmed));
       });
@@ -104,11 +107,8 @@ export async function openFlowNavigateUrl(url: string): Promise<void> {
     }
   }
 
-  // Last resort — may fail for custom schemes; hosts should set onNavigate.
-  try {
-    await Linking.openURL(trimmed);
-  } catch {
-    // Best-effort.
+  if (isSafeUrl(trimmed) || /^https?:\/\//i.test(trimmed)) {
+    await openExternalNavigateUrl(trimmed);
   }
 }
 

package/src/pairing/PairingController.ts

@@ -46,6 +46,11 @@ export interface PairingControllerOptions {
   tokenStore?: PairingTokenStore;
   /** Clear mid-flow session when exiting preview. */
   clearLocalSession?: () => void;
+  /**
+   * Runs before a Builder preview start is sent on the end-user channel.
+   * Defaults to {@link clearLocalSession} when omitted.
+   */
+  prepareForBuilderPreviewStart?: () => void | Promise<void>;
   /** End the previewed draft on the server when exiting preview. */
   endDraftSession?: () => Promise<void>;
   /**
@@ -84,6 +89,7 @@ export class PairingController {
   private readonly LinkingModule: NonNullable<PairingControllerOptions['LinkingModule']>;
   private readonly AppStateModule: NonNullable<PairingControllerOptions['AppStateModule']>;
   private readonly clearLocalSession: (() => void) | undefined;
+  private readonly prepareForBuilderPreviewStart: (() => void | Promise<void>) | undefined;
   private readonly endDraftSession: (() => Promise<void>) | undefined;
   private readonly cancelPendingDraftEnd: (() => void) | undefined;
   private readonly core: UserflowCore;
@@ -122,6 +128,7 @@ export class PairingController {
     this.LinkingModule = options.LinkingModule ?? Linking;
     this.AppStateModule = options.AppStateModule ?? AppState;
     this.clearLocalSession = options.clearLocalSession ?? undefined;
+    this.prepareForBuilderPreviewStart = options.prepareForBuilderPreviewStart ?? undefined;
     this.endDraftSession = options.endDraftSession ?? undefined;
     this.cancelPendingDraftEnd = options.cancelPendingDraftEnd ?? undefined;
     this.logger = options.logger ?? defaultPairingLogger;
@@ -596,7 +603,8 @@ export class PairingController {
         ...(this.pairingDeviceId !== null ? { device_id: this.pairingDeviceId } : {}),
       }),
       onBeforePreviewStart: () => {
-        this.clearLocalSession?.();
+        const run = this.prepareForBuilderPreviewStart ?? this.clearLocalSession;
+        return run?.();
       },
     });