@userflow-tech/react-native 0.3.0 → 0.3.1

package/src/anchors/useUserflowAnchor.ts

@@ -71,6 +71,7 @@ export function useUserflowAnchor(id: string): React.RefCallback<View> {
       measureInWindow: (callback) => {
         node.measureInWindow(callback);
       },
+      node,
       scrollIntoView: () => {
         const scrollable = node as View & {
           scrollIntoView?: (options?: { block?: string; inline?: string }) => void;

package/src/anonymousId.ts

@@ -1,9 +1,17 @@
-import AsyncStorage from '@react-native-async-storage/async-storage';
 import { UserflowAuthError } from '@userflow-tech/core';
 
+import { getAsyncStorage } from './storage/asyncStorage';
+
 /** Matches the web SDK's `userflow:anonymousId` localStorage key. */
 export const ANONYMOUS_ID_STORAGE_KEY = 'userflow:anonymousId';
 
+export const ANONYMOUS_STORAGE_UNAVAILABLE =
+  'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.';
+
+export const ANONYMOUS_STORAGE_NOT_LINKED =
+  'Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not ' +
+  "linked in this native build. Add it to your app's package.json, run pod install, and rebuild.";
+
 export function uuid(): string {
   const webcrypto = globalThis.crypto;
   if (webcrypto?.randomUUID) return webcrypto.randomUUID();
@@ -15,24 +23,27 @@ export function uuid(): string {
 }
 
 export async function getOrCreateAnonymousId(): Promise<string> {
+  const storage = getAsyncStorage();
+  if (!storage) {
+    throw new UserflowAuthError(ANONYMOUS_STORAGE_NOT_LINKED, { isHostContract: true });
+  }
   try {
-    let externalId = await AsyncStorage.getItem(ANONYMOUS_ID_STORAGE_KEY);
+    let externalId = await storage.getItem(ANONYMOUS_ID_STORAGE_KEY);
     if (!externalId) {
       externalId = `anon-${uuid()}`;
-      await AsyncStorage.setItem(ANONYMOUS_ID_STORAGE_KEY, externalId);
+      await storage.setItem(ANONYMOUS_ID_STORAGE_KEY, externalId);
     }
     return externalId;
   } catch {
-    throw new UserflowAuthError(
-      'Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.',
-      { isHostContract: true },
-    );
+    throw new UserflowAuthError(ANONYMOUS_STORAGE_UNAVAILABLE, { isHostContract: true });
   }
 }
 
 export async function clearAnonymousId(): Promise<void> {
+  const storage = getAsyncStorage();
+  if (!storage) return;
   try {
-    await AsyncStorage.removeItem(ANONYMOUS_ID_STORAGE_KEY);
+    await storage.removeItem(ANONYMOUS_ID_STORAGE_KEY);
   } catch {
     // Best-effort clear, mirroring the web SDK when storage access is denied.
   }

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,191 @@
+import { isEvalJsWebViewNativeLinked } from './evalJs/getWebView';
+import { isAsyncStorageLinked } from './storage/asyncStorage';
+
+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 docs/troubleshooting.md.';
+
+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 NativeLookup {
+  NativeModules?: Record<string, unknown>;
+  TurboModuleRegistry?: { get?: (name: string) => unknown };
+}
+
+interface ExpoConstantsModule {
+  executionEnvironment?: string;
+  default?: { executionEnvironment?: string };
+}
+
+let didWarn = false;
+
+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;
+  }
+}
+
+function isNativeModuleLinked(name: string): boolean {
+  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;
+  }
+}
+
+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;
+  }
+}
+
+/** 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, plus a separate warning
+ * when the host is Expo Go. Release builds stay quiet.
+ */
+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));
+  }
+
+  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/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/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/safeArea.ts

@@ -1,4 +1,4 @@
-import type { Context } from 'react';
+import React, { type Context } from 'react';
 
 export interface EdgeInsets {
   top: number;
@@ -9,40 +9,97 @@ export interface EdgeInsets {
 
 const ZERO_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
 
-type UseSafeAreaInsetsFn = () => EdgeInsets;
-
-let cachedHook: UseSafeAreaInsetsFn | null | undefined;
-let cachedInsetsContext: Context<EdgeInsets | null> | null | undefined;
-
 /**
- * Resolve `useSafeAreaInsets` from the optional peer `react-native-safe-area-context`.
- * Returns a zero-inset hook when the peer is not installed.
+ * Used only when `react-native-safe-area-context` is not installed, so
+ * {@link useUserflowSafeAreaInsets} can call `useContext` unconditionally.
  */
-function resolveUseSafeAreaInsets(): UseSafeAreaInsetsFn {
-  if (cachedHook !== undefined) return cachedHook ?? (() => ZERO_INSETS);
+const FallbackInsetsContext = React.createContext<EdgeInsets | null>(null);
+
+export const MISSING_SAFE_AREA_PROVIDER_WARNING =
+  '[Userflow] UserflowProvider is not inside a <SafeAreaProvider>, so flow cards use the ' +
+  "device's initial safe-area insets. Wrap your app in <SafeAreaProvider> from " +
+  'react-native-safe-area-context.';
+
+interface SafeAreaModule {
+  SafeAreaInsetsContext?: Context<EdgeInsets | null>;
+  initialWindowMetrics?: { insets?: Partial<EdgeInsets> } | null;
+}
+
+let cachedModule: SafeAreaModule | null | undefined;
+let warnedMissingProvider = false;
+
+function loadSafeAreaModule(): SafeAreaModule | null {
+  if (cachedModule !== undefined) return cachedModule;
 
   if (typeof require !== 'function') {
-    cachedHook = null;
-    return () => ZERO_INSETS;
+    cachedModule = null;
+    return null;
   }
 
   try {
     // Optional peer — Expo / React Navigation apps usually have it.
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const mod = require('react-native-safe-area-context') as {
-      useSafeAreaInsets?: UseSafeAreaInsetsFn;
-    };
-    cachedHook = typeof mod.useSafeAreaInsets === 'function' ? mod.useSafeAreaInsets : null;
+    const mod = require('react-native-safe-area-context') as SafeAreaModule;
+    cachedModule = mod?.SafeAreaInsetsContext ? mod : null;
   } catch {
-    cachedHook = null;
+    cachedModule = null;
   }
 
-  return cachedHook ?? (() => ZERO_INSETS);
+  return cachedModule;
+}
+
+function copyInsets(insets: Partial<EdgeInsets> | null | undefined): EdgeInsets | null {
+  if (!insets) return null;
+  const top = insets.top;
+  const right = insets.right;
+  const bottom = insets.bottom;
+  const left = insets.left;
+  if (
+    typeof top !== 'number' ||
+    typeof right !== 'number' ||
+    typeof bottom !== 'number' ||
+    typeof left !== 'number'
+  ) {
+    return null;
+  }
+  return { top, right, bottom, left };
+}
+
+/** Device insets from the optional peer, before any provider has measured. */
+function readInitialInsets(): EdgeInsets | null {
+  return copyInsets(loadSafeAreaModule()?.initialWindowMetrics?.insets);
+}
+
+function warnMissingProvider(): void {
+  if (warnedMissingProvider || !__DEV__) return;
+  warnedMissingProvider = true;
+  // eslint-disable-next-line no-console -- intentional missing-provider diagnostic
+  console.warn(MISSING_SAFE_AREA_PROVIDER_WARNING);
+}
+
+/**
+ * Safe-area insets for flow chrome.
+ *
+ * Reads `SafeAreaInsetsContext` directly. `useSafeAreaInsets()` throws when the
+ * peer is installed but no `SafeAreaProvider` is mounted, which would take down
+ * the host tree. A missing provider falls back to `initialWindowMetrics`, then
+ * zero, and warns once in development.
+ */
+function insetsContext(): Context<EdgeInsets | null> {
+  return loadSafeAreaModule()?.SafeAreaInsetsContext ?? FallbackInsetsContext;
+}
+
+/** Value from the nearest provider, or `null` when the peer or provider is absent. */
+export function useParentSafeAreaInsets(): EdgeInsets | null {
+  return copyInsets(React.useContext(insetsContext()));
 }
 
-/** Safe-area insets with a zero fallback when the optional peer is missing. */
 export function useUserflowSafeAreaInsets(): EdgeInsets {
-  return resolveUseSafeAreaInsets()();
+  const fromProvider = useParentSafeAreaInsets();
+  if (fromProvider) return fromProvider;
+  if (!loadSafeAreaModule()) return ZERO_INSETS;
+  warnMissingProvider();
+  return readInitialInsets() ?? ZERO_INSETS;
 }
 
 /**
@@ -50,28 +107,11 @@ export function useUserflowSafeAreaInsets(): EdgeInsets {
  * In-flow banners override this so host screens do not add the inset the banner already consumed.
  */
 export function getSafeAreaInsetsContext(): Context<EdgeInsets | null> | null {
-  if (cachedInsetsContext !== undefined) return cachedInsetsContext;
-
-  if (typeof require !== 'function') {
-    cachedInsetsContext = null;
-    return null;
-  }
-
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires
-    const mod = require('react-native-safe-area-context') as {
-      SafeAreaInsetsContext?: Context<EdgeInsets | null>;
-    };
-    cachedInsetsContext = mod.SafeAreaInsetsContext ?? null;
-  } catch {
-    cachedInsetsContext = null;
-  }
-
-  return cachedInsetsContext;
+  return loadSafeAreaModule()?.SafeAreaInsetsContext ?? null;
 }
 
 /** @internal */
 export function resetSafeAreaInsetsCacheForTests(): void {
-  cachedHook = undefined;
-  cachedInsetsContext = undefined;
+  cachedModule = undefined;
+  warnedMissingProvider = false;
 }

package/src/version.ts

@@ -1,2 +1,2 @@
 /** Generated by scripts/write-version.mjs — do not edit. */
-export const SDK_VERSION = '0.3.0';
+export const SDK_VERSION = '0.3.1';