@userflow-tech/react-native 0.3.0 → 0.4.0

package/src/index.ts

@@ -52,6 +52,12 @@ import {
   mergeHostAppVersionUserAttributes,
   type HostAppVersion,
 } from './hostAppVersion';
+import {
+  commitInitOptions,
+  releaseFailedInitOptions,
+  warnIfInitOptionsIgnored,
+  warnIfInstallIncomplete,
+} from './installCheck';
 import { LifecycleController } from './lifecycle';
 import {
   openFlowNavigateUrl,
@@ -285,10 +291,12 @@ async function afterIdentify(): Promise<void> {
 export const Userflow = {
   /** Validate credentials, store configuration, and wire app-lifecycle handling. */
   init(config: UserflowInitConfig): Promise<UserflowConfig> {
+    warnIfInitOptionsIgnored(config);
     cacheHostAppVersionAtInit({
       ...(config.appVersion !== undefined ? { appVersion: config.appVersion } : {}),
       ...(config.appBuild !== undefined ? { appBuild: config.appBuild } : {}),
     });
+    warnIfInstallIncomplete();
     cacheDeviceContextAtInit();
     setHostOnNavigate(config.onNavigate);
     lifecycle.start();
@@ -318,6 +326,7 @@ export const Userflow = {
 
     return core.init(config).then(
       (resolved) => {
+        commitInitOptions();
         enableScreenTracking();
         // Pairing connect can take the full socket timeout. Identify, and the
         // end-user socket that delivers the preview, must not wait on it.
@@ -326,6 +335,7 @@ export const Userflow = {
         return resolved;
       },
       (error: unknown) => {
+        releaseFailedInitOptions();
         pairing.notifyInitFailed(error);
         throw error;
       },

package/src/installCheck.ts

@@ -0,0 +1,225 @@
+import { isEvalJsWebViewNativeLinked } from './evalJs/getWebView';
+import { isNativeModuleLinked } from './nativeModules';
+import { isAsyncStorageLinked } from './storage/asyncStorage';
+import { isSafeAreaContextInstalled } from './surfaces/safeArea';
+
+export const INSTALL_CHECK_HEADER =
+  '[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):';
+
+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.';
+
+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.';
+
+export const INSTALL_DEVICE_INFO_LINE =
+  '- react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.';
+
+export const INSTALL_CHECK_FOOTER =
+  'See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.';
+
+/**
+ * Separate from {@link INSTALL_CHECK_HEADER}. Flows still run without
+ * safe-area-context; they draw under the status bar.
+ */
+export const INSTALL_SAFE_AREA_WARNING =
+  '[Userflow] react-native-safe-area-context is not installed, so banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.\n' +
+  INSTALL_CHECK_FOOTER;
+
+/**
+ * Separate from {@link INSTALL_CHECK_HEADER}. Flows still run on view-shot 4;
+ * Builder screenshots may not. The installed version is interpolated.
+ */
+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' +
+    INSTALL_CHECK_FOOTER
+  );
+}
+
+export const EXPO_GO_WARNING =
+  '[Userflow] This app is running in Expo Go, which cannot load the SDK native modules. Builder preview links will not open the app. Use a development build (npx expo run:ios / npx expo run:android).';
+
+export const INIT_OPTIONS_IGNORED_WARNING =
+  '[Userflow] Userflow.init() already ran with different options. The new clientToken, serverEndpoint, and pairingEndpoint are ignored because init runs once per process. Userflow.reset() does not apply new credentials. Restart the app to change them.';
+
+const VIEW_SHOT_MODULE = 'RNViewShot';
+const DEVICE_INFO_MODULE = 'RNDeviceInfo';
+
+interface ExpoConstantsModule {
+  executionEnvironment?: string;
+  default?: { executionEnvironment?: string };
+}
+
+let didWarn = false;
+
+function readExpoConstants(): ExpoConstantsModule | null {
+  try {
+    // Optional. Bare React Native does not have this package.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('expo-constants') as ExpoConstantsModule;
+    const record = mod?.default ?? mod;
+    if (record == null || typeof record !== 'object') return null;
+    // Touch the field so a throwing getter (missing package stand-in) is caught.
+    void record.executionEnvironment;
+    return record;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Installed view-shot version, read from package.json only. Requiring the
+ * package entry loads the native module, and view-shot 4 calls
+ * `TurboModuleRegistry.getEnforcing` at import.
+ */
+function readViewShotVersion(): string | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const pkg = require('react-native-view-shot/package.json') as { version?: unknown };
+    return typeof pkg.version === 'string' && pkg.version.length > 0 ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Dev warning when view-shot 4.x is installed. Null on 5.x or when it is absent. */
+export function viewShotVersionWarning(): string | null {
+  const version = readViewShotVersion();
+  if (!version) return null;
+  const match = version.match(/\d+/);
+  const major = match ? Number(match[0]) : null;
+  if (major == null || major >= 5) return null;
+  return formatViewShotVersionWarning(version);
+}
+
+/** Lines for missing native modules. Empty when the build looks complete. */
+export function collectInstallFindings(): string[] {
+  const findings: string[] = [];
+  if (!isAsyncStorageLinked()) findings.push(INSTALL_ASYNC_STORAGE_LINE);
+  if (!isNativeModuleLinked(VIEW_SHOT_MODULE)) findings.push(INSTALL_VIEW_SHOT_LINE);
+  if (!isEvalJsWebViewNativeLinked()) findings.push(INSTALL_WEBVIEW_LINE);
+  // Expo reads the store version from expo-constants / expo-application.
+  // device-info is the bare React Native path.
+  if (readExpoConstants() == null && !isNativeModuleLinked(DEVICE_INFO_MODULE)) {
+    findings.push(INSTALL_DEVICE_INFO_LINE);
+  }
+  return findings;
+}
+
+export function expoGoWarning(): string | null {
+  const constants = readExpoConstants();
+  const environment = constants?.executionEnvironment;
+  return environment === 'storeClient' ? EXPO_GO_WARNING : null;
+}
+
+export function formatInstallWarning(findings: readonly string[]): string {
+  return [INSTALL_CHECK_HEADER, ...findings, INSTALL_CHECK_FOOTER].join('\n');
+}
+
+/**
+ * One development warning for missing native modules, separate warnings when
+ * safe-area-context is not installed or view-shot is older than 5, and a
+ * separate warning when the host is Expo Go. Release builds stay quiet. The
+ * safe-area and old view-shot warnings are not part of the native-module list:
+ * flows still run, and that list says they may not.
+ */
+export function warnIfInstallIncomplete(): void {
+  if (!__DEV__ || didWarn) return;
+  didWarn = true;
+
+  const findings = collectInstallFindings();
+  if (findings.length > 0) {
+    // eslint-disable-next-line no-console -- intentional install diagnostic
+    console.warn(formatInstallWarning(findings));
+  }
+
+  if (!isSafeAreaContextInstalled()) {
+    // eslint-disable-next-line no-console -- intentional install diagnostic
+    console.warn(INSTALL_SAFE_AREA_WARNING);
+  }
+
+  const oldViewShot = viewShotVersionWarning();
+  if (oldViewShot) {
+    // eslint-disable-next-line no-console -- intentional install diagnostic
+    console.warn(oldViewShot);
+  }
+
+  const expoGo = expoGoWarning();
+  if (expoGo) {
+    // eslint-disable-next-line no-console -- intentional install diagnostic
+    console.warn(expoGo);
+  }
+}
+
+/** @internal */
+export function resetInstallCheckForTests(): void {
+  didWarn = false;
+  recordedInitOptions = null;
+  initOptionsCommitted = false;
+}
+
+interface RecordedInitOptions {
+  clientToken: string;
+  serverEndpoint: string;
+  pairingEndpoint: string;
+}
+
+let recordedInitOptions: RecordedInitOptions | null = null;
+/** True once an `init` promise has resolved. A rejection before that clears the record. */
+let initOptionsCommitted = false;
+
+function recordInitOptions(config: {
+  clientToken: string;
+  serverEndpoint?: string;
+  pairingEndpoint?: string;
+}): RecordedInitOptions {
+  return {
+    clientToken: config.clientToken,
+    serverEndpoint: config.serverEndpoint ?? '',
+    pairingEndpoint: config.pairingEndpoint ?? '',
+  };
+}
+
+export function warnIfInitOptionsIgnored(config: {
+  clientToken: string;
+  serverEndpoint?: string;
+  pairingEndpoint?: string;
+}): void {
+  const next = recordInitOptions(config);
+  if (!recordedInitOptions) {
+    recordedInitOptions = next;
+    return;
+  }
+  if (
+    recordedInitOptions.clientToken === next.clientToken &&
+    recordedInitOptions.serverEndpoint === next.serverEndpoint &&
+    recordedInitOptions.pairingEndpoint === next.pairingEndpoint
+  ) {
+    return;
+  }
+  if (!__DEV__) return;
+  // eslint-disable-next-line no-console -- intentional install diagnostic
+  console.warn(INIT_OPTIONS_IGNORED_WARNING);
+}
+
+/** The in-flight `init` resolved, so later calls really are ignored. */
+export function commitInitOptions(): void {
+  initOptionsCommitted = true;
+}
+
+/**
+ * The in-flight `init` rejected. Core drops its cached promise and will run
+ * the next call, so a corrected token or endpoint must not warn.
+ * A rejection after a successful init does not forget that success.
+ */
+export function releaseFailedInitOptions(): void {
+  if (initOptionsCommitted) return;
+  recordedInitOptions = null;
+}

package/src/nativeModules.ts

@@ -0,0 +1,48 @@
+/**
+ * Whether a native module is registered in this binary.
+ *
+ * Check this before `require`ing a package that throws while it loads when the
+ * native half is missing. Metro reports that throw as a fatal error before the
+ * caller's try/catch runs, which is a red screen in debug and can crash a
+ * release build.
+ *
+ * React Native modules show up on `TurboModuleRegistry` or `NativeModules`.
+ * Expo modules are on `globalThis.expo.modules` (see `requireOptionalNativeModule`).
+ */
+
+interface NativeLookup {
+  NativeModules?: Record<string, unknown>;
+  TurboModuleRegistry?: { get?: (name: string) => unknown };
+}
+
+interface ExpoRuntime {
+  modules?: Record<string, unknown>;
+}
+
+function loadReactNative(): NativeLookup | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('react-native') as NativeLookup;
+  } catch {
+    return null;
+  }
+}
+
+export function isNativeModuleLinked(name: string): boolean {
+  const expoModules = (globalThis as { expo?: ExpoRuntime }).expo?.modules;
+  if (expoModules?.[name] != null) return true;
+
+  const reactNative = loadReactNative();
+  if (!reactNative) return false;
+  try {
+    const turbo = reactNative.TurboModuleRegistry;
+    if (typeof turbo?.get === 'function' && turbo.get(name) != null) return true;
+  } catch {
+    // Fall through to the legacy registry.
+  }
+  try {
+    return reactNative.NativeModules?.[name] != null;
+  } catch {
+    return false;
+  }
+}

package/src/network.ts

@@ -14,6 +14,8 @@
  * recovers within a few seconds of the next beat / foreground return.
  */
 
+import { isNativeModuleLinked } from './nativeModules';
+
 export interface NetworkStatus {
   isConnected: boolean | null;
   /** `null` means unknown — treat as reachable when connected. */
@@ -30,10 +32,31 @@ function isOnline(status: NetworkStatus): boolean {
   return status.isConnected === true && status.isInternetReachable !== false;
 }
 
+const NETINFO_MODULE = 'RNCNetInfo';
+
+const NETINFO_UNAVAILABLE_WARNING =
+  '[Userflow] Optional peer @react-native-community/netinfo is not installed or not linked; ' +
+  'skipping instant network-aware reconnect. Connection recovery still works ' +
+  'via the adaptive heartbeat and foreground liveness probe.';
+
+function warnNetInfoUnavailable(): void {
+  if (!__DEV__) return;
+  // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+  console.warn(NETINFO_UNAVAILABLE_WARNING);
+}
+
 function defaultSubscribe(handler: (status: NetworkStatus) => void): () => void {
-  // Lazy require so the SDK works without the optional peer. When installed,
-  // NetInfo makes offline→online reconnect fast; when absent the transport's
-  // adaptive heartbeat + foreground probe still recover the connection.
+  // Check the native module before require. NetInfo throws while its module
+  // loads when RNCNetInfo is missing, and Metro reports that as fatal before
+  // this try/catch can see it.
+  if (!isNativeModuleLinked(NETINFO_MODULE)) {
+    warnNetInfoUnavailable();
+    return () => {};
+  }
+
+  // Lazy require so the SDK works without the optional peer. When installed
+  // and linked, NetInfo makes offline→online reconnect fast; when absent the
+  // transport's adaptive heartbeat + foreground probe still recover.
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
     const NetInfo = require('@react-native-community/netinfo') as {
@@ -51,14 +74,7 @@ function defaultSubscribe(handler: (status: NetworkStatus) => void): () => void
       });
     });
   } catch {
-    if (__DEV__) {
-      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
-      console.warn(
-        '[Userflow] Optional peer @react-native-community/netinfo is not installed; ' +
-          'skipping instant network-aware reconnect. Connection recovery still works ' +
-          'via the adaptive heartbeat and foreground liveness probe.',
-      );
-    }
+    warnNetInfoUnavailable();
     return () => {};
   }
 }

package/src/pairing/deviceId.ts

@@ -1,6 +1,5 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
-
 import { uuid } from '../anonymousId';
+import { getAsyncStorage } from '../storage/asyncStorage';
 
 /**
  * Stable id for this install on the pairing channel.
@@ -16,21 +15,25 @@ let memoized: string | null = null;
 export async function getOrCreatePairingDeviceId(): Promise<string> {
   if (memoized !== null) return memoized;
 
-  try {
-    const stored = await AsyncStorage.getItem(PAIRING_DEVICE_ID_STORAGE_KEY);
-    if (typeof stored === 'string' && stored.length > 0) {
-      memoized = stored;
-      return stored;
+  const storage = getAsyncStorage();
+  if (storage) {
+    try {
+      const stored = await storage.getItem(PAIRING_DEVICE_ID_STORAGE_KEY);
+      if (typeof stored === 'string' && stored.length > 0) {
+        memoized = stored;
+        return stored;
+      }
+    } catch {
+      memoized = uuid();
+      return memoized;
     }
-  } catch {
-    memoized = uuid();
-    return memoized;
   }
 
   const created = uuid();
   memoized = created;
+  if (!storage) return created;
   try {
-    await AsyncStorage.setItem(PAIRING_DEVICE_ID_STORAGE_KEY, created);
+    await storage.setItem(PAIRING_DEVICE_ID_STORAGE_KEY, created);
   } catch {
     // Keep the in-memory id for this process. A later launch may mint another.
   }

package/src/pairing/tokenStorage.ts

@@ -6,6 +6,8 @@
 
 import type { PairingPurpose } from '@userflow-tech/core';
 
+import { isNativeModuleLinked } from '../nativeModules';
+
 import { parsePairingPurpose } from './deepLink';
 
 // SecureStore rejects keys outside [A-Za-z0-9._-], so no `userflow:` prefix here.
@@ -34,12 +36,24 @@ type SecureStoreModule = {
 
 let cachedSecureStore: SecureStoreModule | null | undefined;
 
+const SECURE_STORE_MODULE = 'ExpoSecureStore';
+
+const SECURE_STORE_UNAVAILABLE_WARNING =
+  '[Userflow] Optional peer expo-secure-store is unavailable; ' +
+  'pairing JWT persistence falls back to in-memory storage.';
+
 /** Expo modules must be installed natively — not just the JS package. */
 function isExpoModulesRuntimeAvailable(): boolean {
   const expo = (globalThis as { expo?: { EventEmitter?: unknown } }).expo;
   return typeof expo?.EventEmitter === 'function';
 }
 
+function warnSecureStoreUnavailable(): void {
+  if (!__DEV__) return;
+  // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
+  console.warn(SECURE_STORE_UNAVAILABLE_WARNING);
+}
+
 function tryLoadExpoSecureStore(): SecureStoreModule | null {
   if (cachedSecureStore !== undefined) return cachedSecureStore;
 
@@ -48,19 +62,21 @@ function tryLoadExpoSecureStore(): SecureStoreModule | null {
     return cachedSecureStore;
   }
 
+  // expo-secure-store calls requireNativeModule at import and throws when the
+  // native module is missing. Metro reports that as fatal before try/catch.
+  if (!isNativeModuleLinked(SECURE_STORE_MODULE)) {
+    cachedSecureStore = null;
+    warnSecureStoreUnavailable();
+    return cachedSecureStore;
+  }
+
   try {
     // Optional peer — absent in bare RN without expo-secure-store.
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- optional peer at import time
     cachedSecureStore = require('expo-secure-store') as SecureStoreModule;
   } catch {
     cachedSecureStore = null;
-    if (__DEV__) {
-      // eslint-disable-next-line no-console -- intentional missing-optional-peer diagnostic
-      console.warn(
-        '[Userflow] Optional peer expo-secure-store is unavailable; ' +
-          'pairing JWT persistence falls back to in-memory storage.',
-      );
-    }
+    warnSecureStoreUnavailable();
   }
 
   return cachedSecureStore;

package/src/runtime/TargetPressBridge.tsx

@@ -1,6 +1,8 @@
 import * as React from 'react';
 import { StyleSheet, View, type GestureResponderEvent } from 'react-native';
 
+import { elementTapMonitor } from '../anchors/elementTapMonitor';
+import { touchBelongsToEvent, touchTargetFiber } from '../anchors/fiber/touchTargetFiber';
 import { targetPressMonitor } from '../anchors/targetPressMonitor';
 
 import { changedTouchPoints, forEachChangedTouch } from './changedTouchPoints';
@@ -17,7 +19,8 @@ export interface TargetPressBridgeProps {
  *
  * The Userflow overlay is a sibling above the app, so hole Pressables would
  * intercept presses. Instead we hit-test bubbled `onTouchStart` / `onTouchEnd`
- * against the rect registered by {@link TooltipSurface}.
+ * against the rect registered by {@link TooltipSurface}, and — while an
+ * element click condition is tracked — against the fiber under the finger.
  *
  * Preview-chrome double taps are observed by `DoubleTapBridge` around the
  * whole provider tree — this bridge never sees overlay touches.
@@ -27,16 +30,27 @@ export interface TargetPressBridgeProps {
 export function TargetPressBridge({ children }: TargetPressBridgeProps): React.ReactElement {
   const onTouchStart = React.useCallback((event: GestureResponderEvent) => {
     isolateSync('target-press', () => {
+      const observingTaps = elementTapMonitor.subscriberCount > 0;
       forEachChangedTouch(event, (identifier, pageX, pageY) => {
         targetPressMonitor.handleTouchStart(identifier, pageX, pageY);
+        if (!observingTaps || !touchBelongsToEvent(event, identifier)) return;
+        elementTapMonitor.handleTouchStart(
+          identifier,
+          pageX,
+          pageY,
+          touchTargetFiber(event, identifier),
+        );
       });
     });
   }, []);
 
   const onTouchEnd = React.useCallback((event: GestureResponderEvent) => {
     isolateSync('target-press', () => {
+      const observingTaps = elementTapMonitor.subscriberCount > 0;
       forEachChangedTouch(event, (identifier, pageX, pageY) => {
         targetPressMonitor.handleTouchEnd(identifier, pageX, pageY);
+        if (!observingTaps) return;
+        elementTapMonitor.handleTouchEnd(identifier, pageX, pageY);
       });
     });
   }, []);
@@ -46,10 +60,12 @@ export function TargetPressBridge({ children }: TargetPressBridgeProps): React.R
       const points = changedTouchPoints(event);
       if (points.length === 0) {
         targetPressMonitor.cancelTouch();
+        elementTapMonitor.cancelTouch();
         return;
       }
       for (const touch of points) {
         targetPressMonitor.cancelTouch(touch.identifier);
+        elementTapMonitor.cancelTouch(touch.identifier);
       }
     });
   }, []);

package/src/runtime/UserflowProvider.tsx

@@ -6,7 +6,11 @@ import { FiberScanRoot } from '../anchors/fiber/FiberScanRoot';
 import { DoubleTapBridge } from '../authoring/chrome/DoubleTapBridge';
 import { elementPickerController } from '../authoring/elementPickerController';
 import { ABSOLUTE_FILL } from '../surfaces/absoluteFill';
-import { getSafeAreaInsetsContext, useUserflowSafeAreaInsets } from '../surfaces/safeArea';
+import {
+  getSafeAreaInsetsContext,
+  useParentSafeAreaInsets,
+  useUserflowSafeAreaInsets,
+} from '../surfaces/safeArea';
 import type { EdgeInsets } from '../surfaces/safeArea';
 import { SurfaceLayoutInsetsProvider } from '../surfaces/surfaceLayoutInsets';
 
@@ -198,11 +202,14 @@ function HostSafeArea({
   children: React.ReactNode;
 }): React.ReactElement {
   const Context = getSafeAreaInsetsContext();
-  const defaultInsets = useUserflowSafeAreaInsets();
-  if (!Context) {
+  // Re-provide only when a parent already supplied insets, or when a banner
+  // override applies. Supplying a value with no parent would hide the host's
+  // own missing SafeAreaProvider from its useSafeAreaInsets() calls.
+  const parent = useParentSafeAreaInsets();
+  if (!Context || (insets == null && parent == null)) {
     return <>{children}</>;
   }
-  return <Context.Provider value={insets ?? defaultInsets}>{children}</Context.Provider>;
+  return <Context.Provider value={insets ?? parent}>{children}</Context.Provider>;
 }
 
 /** Access the flow session engine from inside {@link UserflowProvider}. */

package/src/storage/asyncStorage.ts

@@ -0,0 +1,88 @@
+interface ReactNativeNativeLookup {
+  NativeModules?: Record<string, unknown>;
+  TurboModuleRegistry?: { get?: (name: string) => unknown };
+}
+const ASYNC_STORAGE_NATIVE_MODULES = [
+  'RNAsyncStorage',
+  'RNCAsyncStorage',
+  'RNC_AsyncSQLiteDBStorage',
+  'PlatformLocalStorage',
+  'AsyncSQLiteDBStorage',
+  'AsyncLocalStorage',
+] as const;
+
+export interface AsyncStorageLike {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+  removeItem(key: string): Promise<void>;
+}
+
+let cached: AsyncStorageLike | null | undefined;
+
+function loadReactNative(): ReactNativeNativeLookup | null {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    return require('react-native') as ReactNativeNativeLookup;
+  } catch {
+    return null;
+  }
+}
+
+function nativeModuleRegistered(name: string, reactNative: ReactNativeNativeLookup): boolean {
+  try {
+    const turbo = reactNative.TurboModuleRegistry;
+    if (typeof turbo?.get === 'function' && turbo.get(name) != null) {
+      return true;
+    }
+  } catch {
+    // A missing turbo registry is not a failed link check.
+  }
+  try {
+    return reactNative.NativeModules?.[name] != null;
+  } catch {
+    return false;
+  }
+}
+
+/** True when some AsyncStorage native binary is in this build. */
+export function isAsyncStorageLinked(): boolean {
+  const reactNative = loadReactNative();
+  if (!reactNative) return false;
+  return ASYNC_STORAGE_NATIVE_MODULES.some((name) => nativeModuleRegistered(name, reactNative));
+}
+
+/**
+ * The AsyncStorage JS API, or `null` when the package or its native module is
+ * missing. Never requires the package until the native module is registered.
+ */
+export function getAsyncStorage(): AsyncStorageLike | null {
+  if (cached !== undefined) return cached;
+
+  if (typeof require !== 'function' || !isAsyncStorageLinked()) {
+    cached = null;
+    return cached;
+  }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+    const mod = require('@react-native-async-storage/async-storage') as {
+      default?: Partial<AsyncStorageLike>;
+    } & Partial<AsyncStorageLike>;
+    const storage = mod?.default ?? mod;
+    cached =
+      typeof storage?.getItem === 'function' &&
+      typeof storage.setItem === 'function' &&
+      typeof storage.removeItem === 'function'
+        ? (storage as AsyncStorageLike)
+        : null;
+  } catch {
+    cached = null;
+  }
+
+  return cached;
+}
+
+/** @internal */
+export function resetAsyncStorageCacheForTests(): void {
+  cached = undefined;
+}

package/src/surfaces/BannerSurface.tsx

@@ -61,11 +61,13 @@ export function BannerSurface({
     if (!webView) {
       if (!warnedMissingWebView) {
         warnedMissingWebView = true;
-        console.warn(
-          'Userflow: WebView banner requires react-native-webview in the native binary. ' +
-            'Add it to your app (e.g. npx expo install react-native-webview), run pod install under ios/, ' +
-            'then rebuild with expo run:ios (not Expo Go). Falling back to the native banner bar.',
-        );
+        if (__DEV__) {
+          console.warn(
+            'Userflow: WebView banner requires react-native-webview in the native binary. ' +
+              'Add it to your app (e.g. npx expo install react-native-webview), run pod install under ios/, ' +
+              'then rebuild with expo run:ios (not Expo Go). Falling back to the native banner bar.',
+          );
+        }
       }
       return <BannerBar session={session} onActions={onActions} onDismiss={onDismiss} />;
     }