@userflow-tech/react-native 0.4.5 → 0.5.0

package/src/anchors/resolveAutoAnchorHost.ts

@@ -9,7 +9,7 @@ import type { AutoAnchorInstance } from './AutoAnchorRegistry';
 import type { AnyFiber } from './fiber/fiberInternals';
 import { fiberFromPublicInstance } from './fiber/fiberInternals';
 import { createFiberMeasureInWindow } from './fiber/measureHostFiber';
-import { resolveFiberPath } from './fiber/resolveFiberPath';
+import { resolveFiberPath, type FiberPathMissReason } from './fiber/resolveFiberPath';
 import { createVisibleInstanceFilter } from './isInstanceOnVisibleScreen';
 import { resolveAnchorHost } from './resolveAnchorHost';
 import { matchFingerprint, type MatchResult } from './semanticMatcher';
@@ -28,7 +28,15 @@ export type AutoAnchorResolution =
     }
   | { status: 'ambiguous'; match?: MatchResult }
   | { status: 'absent'; match?: MatchResult }
-  | { status: 'unknown'; match?: MatchResult };
+  | {
+      status: 'unknown';
+      match?: MatchResult;
+      /**
+       * Set when a fiber path did not resolve. Element conditions treat
+       * `no-match` as absent and `no-root` / `empty` as unknown.
+       */
+      fiberMiss?: FiberPathMissReason;
+    };
 
 type MeasureInWindowCallback = (x: number, y: number, width: number, height: number) => void;
 
@@ -121,7 +129,8 @@ export function resolveScoredAutoAnchor(fp: MobileFingerprint): AutoAnchorResolu
   if (visible.instance) return mapMatch(visible);
 
   if (visible.reason === 'no-candidates') {
-    const any = matchFingerprint(fp);
+    // Nothing can commit between the two matches, so the first read stands.
+    const any = matchFingerprint(fp, { liveContentFresh: true });
     if (any.instance) return { status: 'absent', match: any };
     if (any.reason === 'all-contradicted') return mapMatch(any);
   }
@@ -136,10 +145,11 @@ export function resolveScoredAutoAnchor(fp: MobileFingerprint): AutoAnchorResolu
  * carries a real `testID` / `userflowId` / non-`uf_` `nativeID` still resolves
  * under Babel `stampOnly: true` (no auto-registry population).
  *
- * Scored matches run over `autoAnchorRegistry` and fail closed: weak or
- * non-unique evidence is `unknown`, not `absent`, so ELEMENT gates stay blocked
- * rather than inventing a truth value. Hosts on a covered navigator screen
- * are skipped the same way the fiber scan skips them.
+ * Scored matches run over `autoAnchorRegistry`. A covered screen and a
+ * contradicted fingerprint are `absent`. Weak, missing, or tied evidence stays
+ * `unknown` here; element conditions decide which of those count as absent.
+ * Hosts on a covered navigator screen are skipped the same way the fiber scan
+ * skips them.
  */
 export function resolveAutoAnchorHost(
   autoData: string | MobileAutoData | null | undefined,
@@ -159,7 +169,7 @@ export function resolveAutoAnchorHost(
       };
     }
     if (fiberHit.status === 'ambiguous') return { status: 'ambiguous' };
-    return { status: 'unknown' };
+    return { status: 'unknown', fiberMiss: fiberHit.reason };
   }
 
   const exactId = exactIdFromFingerprint(fp);

package/src/anchors/resolveElementTargets.ts

@@ -6,9 +6,16 @@
  * `testID`, then a real `nativeID`) use that same multi-host lookup, and fall
  * through to scoring only when nothing matched.
  */
-import { decodeMobileAutoData, type FlowSelectorFragment } from '@userflow-tech/protocol';
+import {
+  decodeMobileAutoData,
+  type FlowSelectorFragment,
+  type MobileAutoData,
+} from '@userflow-tech/protocol';
+
+import { screenIdFromLocation, getCurrentScreenLocation } from '../screenTracker';
 
 import { type AnchorHost, anchorRegistry } from './AnchorRegistry';
+import { autoAnchorRegistry } from './AutoAnchorRegistry';
 import type { ElementTap } from './elementTapMonitor';
 import { anchorIdsAboveTap } from './elementTargetMatch';
 import { fiberScanRoot } from './fiber/FiberScanRoot';
@@ -85,21 +92,38 @@ function resolveAutoTargets(autoData: string | null): ElementTargetResolution {
   if (!decoded || !fingerprint) return { status: 'unknown' };
 
   if (decoded.resolver === 'fiber' && decoded.fiberPath) {
-    return fromAutoResolution(resolveAutoAnchorHost(decoded));
+    return conditionVerdict(resolveAutoAnchorHost(decoded), decoded);
   }
 
   const exactId = exactIdFromFingerprint(fingerprint);
+  let exactIdAbsent = false;
   if (exactId) {
     const manual = resolveManualTargets(exactId);
     if (manual.status === 'found') return manual;
+    // "Absent" before a scan root exists only means we have not looked yet.
+    exactIdAbsent = fiberScanRoot.getFiber() != null;
   }
 
   // The exact id already missed above, so go straight to scoring rather than
   // letting resolveAutoAnchorHost scan for it again.
-  return fromAutoResolution(resolveScoredAutoAnchor(fingerprint));
+  return conditionVerdict(resolveScoredAutoAnchor(fingerprint), decoded, exactIdAbsent);
 }
 
-function fromAutoResolution(resolution: AutoAnchorResolution): ElementTargetResolution {
+/**
+ * Turn an AUTO resolution into the value an element condition can report.
+ *
+ * A miss (nothing scored, or an exact id that a scan did not find) is absent,
+ * matching web. A tie stays unknown on the screen where the element was picked,
+ * because the target may be one of the look-alikes, and is absent on any other
+ * screen. An empty registry with no exact id, a missing scan root, and a
+ * missing fingerprint stay unknown so `stampOnly` cannot open a "not present"
+ * gate.
+ */
+function conditionVerdict(
+  resolution: AutoAnchorResolution,
+  decoded: MobileAutoData,
+  exactIdAbsent = false,
+): ElementTargetResolution {
   if (resolution.status === 'found') {
     // Scored matches only try the direct ref pointer, which Paper release
     // builds null out. Without the index fallback a tap could never match.
@@ -112,12 +136,45 @@ function fromAutoResolution(resolution: AutoAnchorResolution): ElementTargetReso
     };
   }
   if (resolution.status === 'absent') return { status: 'absent' };
-  // Ambiguous and unknown both fail closed. Ambiguous is a real tie, not a
-  // broken selector, so it does not warn.
-  if (resolution.status === 'ambiguous') return { status: 'unknown', silent: true };
+
+  if (resolution.status === 'unknown') {
+    if (resolution.fiberMiss === 'no-root' || resolution.fiberMiss === 'empty') {
+      return { status: 'unknown' };
+    }
+    if (resolution.fiberMiss === 'no-match') return { status: 'absent' };
+  }
+
+  const reason = resolution.match?.reason;
+  const tie =
+    resolution.status === 'ambiguous' ||
+    reason === 'not-unique' ||
+    reason === 'ambiguous-explicit-id';
+  if (tie) {
+    if (offPickedScreen(decoded.screenId)) return { status: 'absent' };
+    // A real tie is not a broken selector, so it does not warn. A weak
+    // not-unique miss still does, matching the previous unknown report.
+    return reason === 'not-unique' ? { status: 'unknown' } : { status: 'unknown', silent: true };
+  }
+
+  if (reason === 'below-threshold') return { status: 'absent' };
+
+  if (reason === 'no-candidates') {
+    const nothingToMatch = autoAnchorRegistry.allInstances().length === 0 && !exactIdAbsent;
+    if (nothingToMatch) return { status: 'unknown' };
+    return { status: 'absent' };
+  }
+
   return { status: 'unknown' };
 }
 
+/** True when the picked screen is known and the app is on a different one. */
+function offPickedScreen(pickedScreenId: string | undefined): boolean {
+  if (!pickedScreenId || pickedScreenId === 'unknown') return false;
+  const current = screenIdFromLocation(getCurrentScreenLocation());
+  if (current === 'unknown') return false;
+  return current !== pickedScreenId;
+}
+
 function resolveManualTargets(id: string): ElementTargetResolution {
   const registered = anchorRegistry.getAll(id);
   if (registered.length > 0) {

package/src/anchors/semanticMatcher.ts

@@ -190,18 +190,21 @@ function intrinsicNonTextAgrees(fp: MobileFingerprint, inst: AutoAnchorInstance)
   );
 }
 
+/**
+ * An id or kind conflict, or a childText disagreement no text-independent
+ * identity (authoritative id, matching icon/image) vouches for.
+ */
+function isContradicted(fp: MobileFingerprint, inst: AutoAnchorInstance): boolean {
+  if (contradictsStrong(fp, inst)) return true;
+  return childTextDisagrees(fp, inst) && !idAgrees(fp, inst) && !intrinsicNonTextAgrees(fp, inst);
+}
+
 function scoreInstance(
   fp: MobileFingerprint,
   inst: AutoAnchorInstance,
   ambiguous: boolean,
 ): number {
-  if (contradictsStrong(fp, inst)) return -Infinity;
-
-  // A childText disagreement is disqualifying unless a text-independent identity
-  // vouches for the element (authoritative id, or matching icon/image).
-  if (childTextDisagrees(fp, inst) && !idAgrees(fp, inst) && !intrinsicNonTextAgrees(fp, inst)) {
-    return -Infinity;
-  }
+  if (isContradicted(fp, inst)) return -Infinity;
 
   let score = 0;
 
@@ -231,11 +234,14 @@ function scoreInstance(
 
   score += scoreAncestors(fp.ancestors ?? [], inst.ancestors ?? []);
 
-  const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
-  score += scoreSiblingWindow(fp.previousSiblings ?? [], window.previous);
-  // Score next siblings once. The POC added a reversed pass *and* a direct pass,
-  // which double-counted the next window.
-  score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
+  // The window scans the registry, so skip it when there is nothing to compare.
+  if (fp.previousSiblings?.length || fp.nextSiblings?.length) {
+    const window = autoAnchorRegistry.siblingWindow(inst.instanceId, 2);
+    score += scoreSiblingWindow(fp.previousSiblings ?? [], window.previous);
+    // Score next siblings once. The POC added a reversed pass *and* a direct pass,
+    // which double-counted the next window.
+    score += scoreSiblingWindow(fp.nextSiblings ?? [], window.next);
+  }
 
   if (ambiguous && !inst.manualId) score -= 40;
 
@@ -246,6 +252,8 @@ type InstanceFilter = (inst: AutoAnchorInstance) => boolean;
 
 interface MatchOptions {
   instanceFilter?: InstanceFilter;
+  /** The caller refreshed live content earlier in this same synchronous call. */
+  liveContentFresh?: boolean;
 }
 
 /** Each instance's visibility is computed once per match. */
@@ -260,10 +268,7 @@ function memoizeFilter(filter: InstanceFilter): InstanceFilter {
   };
 }
 
-function candidatePool(
-  fp: MobileFingerprint,
-  instanceFilter?: InstanceFilter,
-): AutoAnchorInstance[] {
+function candidatePool(fp: MobileFingerprint): AutoAnchorInstance[] {
   // Explicit ids are authoritative: a miss is no-candidates, not a full-registry search.
   let pool: AutoAnchorInstance[];
   if (fp.manualId) {
@@ -286,29 +291,45 @@ function candidatePool(
       if (filtered.length > 0) pool = filtered;
     }
   }
-  return instanceFilter ? pool.filter(instanceFilter) : pool;
+  return pool;
 }
 
 function miss(reason: MatchMissReason, score = 0, secondScore = 0): MatchResult {
   return { instance: null, score, secondScore, reason };
 }
 
-function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFilter): MatchResult {
+function matchFingerprintCore(
+  fp: MobileFingerprint,
+  instanceFilter?: InstanceFilter,
+  liveContentFresh = false,
+): MatchResult {
   // Live text / testID must be applied *before* pooling. A shared Babel helper
   // (`const field = () => <TextInput testID={id} />`) reuses one auto-anchor
   // callback, so the runtime bag is last-writer-wins until we read the host.
+  // An unchanged host is a fiber and props-identity check after one shared
+  // ancestor walk per pass, so refreshing every instance stays cheap; the
+  // per-instance screen walk is what is not, and it only runs for the pool
+  // below.
+  const all = autoAnchorRegistry.allInstances();
+  if (all.length > 0 && !liveContentFresh) {
+    autoAnchorRegistry.refreshLiveContent(all);
+  }
+
   // A filter's verdict is memoized so covered-screen checks run once per instance.
   const filter = instanceFilter ? memoizeFilter(instanceFilter) : undefined;
-  const broad = filter
-    ? autoAnchorRegistry.allInstances().filter(filter)
-    : autoAnchorRegistry.allInstances();
-  if (broad.length > 0) {
-    autoAnchorRegistry.refreshLiveContent(broad);
+  const candidates = candidatePool(fp);
+  // A contradiction does not depend on visibility, so settle it before the
+  // covered-screen check. Visibility of contradicted instances only matters to
+  // tell `all-contradicted` from `no-candidates` when nothing else is left.
+  const viable: AutoAnchorInstance[] = [];
+  const contradicted: AutoAnchorInstance[] = [];
+  for (const inst of candidates) {
+    (isContradicted(fp, inst) ? contradicted : viable).push(inst);
   }
-
-  const pool = candidatePool(fp, filter);
+  const pool = filter ? viable.filter(filter) : viable;
   if (pool.length === 0) {
-    return miss('no-candidates');
+    const anyContradictedCandidate = filter ? contradicted.some(filter) : contradicted.length > 0;
+    return miss(anyContradictedCandidate ? 'all-contradicted' : 'no-candidates');
   }
 
   // Visibility can clear a registry-wide ambiguous flag (a covered twin) but
@@ -367,7 +388,7 @@ function matchFingerprintCore(fp: MobileFingerprint, instanceFilter?: InstanceFi
  * can flag weak (`structural`) targets.
  */
 export function matchFingerprint(fp: MobileFingerprint, opts?: MatchOptions): MatchResult {
-  const result = matchFingerprintCore(fp, opts?.instanceFilter);
+  const result = matchFingerprintCore(fp, opts?.instanceFilter, opts?.liveContentFresh);
   if (fp.identityStrength) result.identityStrength = fp.identityStrength;
   return result;
 }

package/src/anchors/tapSlop.ts

@@ -0,0 +1,18 @@
+/** Max finger travel (px) between start and end to count as a tap, not a scroll. */
+export const TARGET_PRESS_TAP_SLOP = 10;
+
+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;
+}

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();