@userflow-tech/react-native 0.3.1 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userflow-tech/react-native",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Userflow SDK for React Native — onboarding flows, tooltips, and modals.",
   "license": "SEE LICENSE IN LICENSE",
   "main": "./lib/commonjs/index.js",
@@ -86,15 +86,16 @@
     "clean": "rimraf lib vendor expo-plugin babel-plugin"
   },
   "peerDependencies": {
-    "@react-native-community/netinfo": ">=11.0.0",
+    "@react-native-community/netinfo": ">=11.0.0 <13.0.0",
     "@react-navigation/native": ">=6.0.0",
     "expo-router": ">=3.0.0",
     "expo-secure-store": ">=13.0.0",
     "react": ">=18.2.0",
-    "react-native": ">=0.74.0",
-    "react-native-safe-area-context": ">=4.0.0",
-    "react-native-view-shot": ">=5.0.0",
-    "react-native-webview": ">=13.8.0"
+    "react-native": ">=0.76.0",
+    "react-native-device-info": ">=11.0.0 <16.0.0",
+    "react-native-safe-area-context": ">=4.0.0 <6.0.0",
+    "react-native-view-shot": "^5.0.0",
+    "react-native-webview": ">=13.8.0 <14.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-community/netinfo": {
@@ -109,12 +110,15 @@
     "expo-secure-store": {
       "optional": true
     },
+    "react-native-device-info": {
+      "optional": true
+    },
     "react-native-safe-area-context": {
       "optional": true
     }
   },
   "dependencies": {
-    "@react-native-async-storage/async-storage": ">=1.23.0",
+    "@react-native-async-storage/async-storage": ">=1.23.0 <3.0.0",
     "@userflow-tech/core": "file:./vendor/core",
     "@userflow-tech/protocol": "file:./vendor/protocol"
   },
@@ -134,6 +138,7 @@
     "react": "19.1.0",
     "react-native": "0.81.5",
     "react-native-builder-bob": "^0.30.0",
+    "react-native-device-info": "15.0.2",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-view-shot": "^5.1.1",
     "react-native-webview": "13.16.1",
@@ -166,6 +171,6 @@
     ]
   },
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   }
 }

package/src/authoring/capturePickerScreenshot.ts

@@ -1,9 +1,12 @@
 import { Dimensions } from 'react-native';
 
+import { isNativeModuleLinked } from '../nativeModules';
+
 import type { ElementPickerScreenshot } from './elementPickerController';
 import type { HitRect } from './hitTest';
 
 const MAX_CAPTURE_WIDTH = 480;
+const VIEW_SHOT_MODULE = 'RNViewShot';
 
 const MISSING_VIEW_SHOT_WARNING =
   '[Userflow] Required peer react-native-view-shot is not installed; ' +
@@ -31,8 +34,14 @@ function warnMissingViewShot(): void {
 }
 
 function loadViewShot(): ViewShotModule | null {
+  // view-shot 4 calls TurboModuleRegistry.getEnforcing at import. Metro reports
+  // that throw as fatal before this try/catch can see it.
+  if (!isNativeModuleLinked(VIEW_SHOT_MODULE)) {
+    warnMissingViewShot();
+    return null;
+  }
   try {
-    // Required peer; degrade if unlinked or the JS package is missing.
+    // Required peer; degrade if the JS package is missing.
     // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-require-imports
     return require('react-native-view-shot') as ViewShotModule;
   } catch {

package/src/evalJs/getWebView.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, Ref } from 'react';
-import { NativeModules, TurboModuleRegistry } from 'react-native';
+
+import { isNativeModuleLinked } from '../nativeModules';
 
 /**
  * Minimal surface of `react-native-webview` this spike uses.
@@ -45,20 +46,11 @@ let warnedMissing = false;
 /**
  * True when the native `react-native-webview` binary is linked. Do not
  * `require('react-native-webview')` before this passes — the JS entry calls
- * `TurboModuleRegistry.getEnforcing('RNCWebViewModule')` and can red-screen.
+ * `TurboModuleRegistry.getEnforcing('RNCWebViewModule')` and Metro reports that
+ * throw as fatal before try/catch.
  */
 export function isEvalJsWebViewNativeLinked(): boolean {
-  try {
-    if (typeof TurboModuleRegistry?.get === 'function') {
-      if (TurboModuleRegistry.get('RNCWebViewModule') != null) {
-        return true;
-      }
-    }
-    const legacy = NativeModules.RNCWebViewModule as unknown;
-    return legacy != null;
-  } catch {
-    return false;
-  }
+  return isNativeModuleLinked('RNCWebViewModule');
 }
 
 /**
@@ -101,6 +93,7 @@ export function getEvalJsWebView(): EvalJsWebViewComponent | null {
 function warnMissing(reason: 'native' | 'js' | 'unavailable'): void {
   if (warnedMissing) return;
   warnedMissing = true;
+  if (!__DEV__) return;
   if (reason === 'native') {
     console.warn(
       'Userflow: react-native-webview is listed in package.json but RNCWebViewModule is not in ' +

package/src/hostAppVersion.ts

@@ -2,7 +2,7 @@
  * Read the host app's native marketing version (store version), not the
  * SDK package version. React Native does not expose the store version on
  * `Platform`; Expo hosts may use optional expo modules; bare RN reads
- * `NativeModules.RNDeviceInfo` constants from the bundled device-info native
+ * `NativeModules.RNDeviceInfo` constants from the device-info native
  * module (after autolink + rebuild). The OS name is `Platform.OS`.
  *
  * Do not `require('react-native-device-info')` — that package throws at import
@@ -10,6 +10,8 @@
  * even inside try/catch.
  */
 
+import { isNativeModuleLinked } from './nativeModules';
+
 export type HostAppVersionSource =
   | 'expo-application'
   | 'expo-constants'
@@ -42,6 +44,10 @@ function unwrapModule(mod: unknown): Record<string, unknown> | null {
 }
 
 function tryRequireExpoApplication(): unknown {
+  // expo-application calls requireNativeModule('ExpoApplication') at import.
+  // Skip the require when that module is not registered so a missing binary
+  // cannot surface as a fatal error.
+  if (!isNativeModuleLinked('ExpoApplication')) return undefined;
   try {
     // Optional on bare RN — Metro requires a string literal.
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires

package/src/installCheck.ts

@@ -1,5 +1,7 @@
 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):';
@@ -16,7 +18,30 @@ export const INSTALL_WEBVIEW_LINE =
 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 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).';
@@ -27,11 +52,6 @@ export const INIT_OPTIONS_IGNORED_WARNING =
 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 };
@@ -39,31 +59,6 @@ interface ExpoConstantsModule {
 
 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.
@@ -79,6 +74,31 @@ function readExpoConstants(): ExpoConstantsModule | 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[] = [];
@@ -104,8 +124,11 @@ export function formatInstallWarning(findings: readonly string[]): string {
 }
 
 /**
- * One development warning for missing native modules, plus a separate warning
- * when the host is Expo Go. Release builds stay quiet.
+ * 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;
@@ -117,6 +140,17 @@ export function warnIfInstallIncomplete(): void {
     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

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/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/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} />;
     }

package/src/surfaces/safeArea.ts

@@ -48,6 +48,11 @@ function loadSafeAreaModule(): SafeAreaModule | null {
   return cachedModule;
 }
 
+/** True when the optional peer's JavaScript package can be loaded. */
+export function isSafeAreaContextInstalled(): boolean {
+  return loadSafeAreaModule() != null;
+}
+
 function copyInsets(insets: Partial<EdgeInsets> | null | undefined): EdgeInsets | null {
   if (!insets) return null;
   const top = insets.top;

package/src/version.ts

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

package/vendor/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userflow-tech/core",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Userflow React Native SDK core — platform-agnostic engine and protocol client.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/vendor/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@userflow-tech/protocol",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Userflow React Native SDK protocol — wire contracts and shared types.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/docs/theme-mapping.md

@@ -1,130 +0,0 @@
-# Theme mapping (web → React Native)
-
-Phase 3 maps Userflow web theme tokens onto React Native styles used by flow chrome.
-This is an interim visual baseline aligned with the mobile tooltip/modal design specs.
-
-## Card chrome — `resolveBubbleChrome`
-
-Source: `src/surfaces/themeChrome.ts`
-
-| Web / theme token                         | RN usage                                                         |
-| ----------------------------------------- | ---------------------------------------------------------------- |
-| `backgroundColor`                         | Card `backgroundColor`                                           |
-| `bubbleBorderRadius` (default `10`)       | Card `borderRadius`                                              |
-| `bubbleBorderWidth` / `bubbleBorderColor` | Card border                                                      |
-| `tooltipNotchSize` (default `10`)         | Tooltip notch size; `0` hides notch                              |
-| Modal content padding                     | `24` (mobile; web default is 40)                                 |
-| Tooltip / bubble content padding          | `24` (web tooltip)                                               |
-| Shadow                                    | Approximate dual drop-shadow via `shadow*` + Android `elevation` |
-
-Modal cards use `overflow: 'hidden'` so the progress bar clips to the radius.
-Tooltip cards use `overflow: 'visible'` so the notch is not clipped.
-
-## Progress — `ProgressBar`
-
-| Theme token                              | RN usage                                          |
-| ---------------------------------------- | ------------------------------------------------- |
-| `progressBarEnabled`                     | Show / hide                                       |
-| `progressBarPosition` (`TOP` / `BOTTOM`) | Placement flush on the card edge                  |
-| `progressBarType`                        | `DEFAULT` fraction bar; `NUMBERED` shows `1 of N` |
-| Step `progress` + step index             | Fraction via `resolveStepProgress`                |
-
-## Buttons — `StepButton`
-
-| Theme token                     | RN usage                                                         |
-| ------------------------------- | ---------------------------------------------------------------- |
-| `primaryButton*` / widget brand | Primary filled button                                            |
-| Secondary (DEFAULT)             | Neutral outline: white fill, `#d1d5db` border, `fontColor` label |
-| Button fragment colors when set | Override defaults per button                                     |
-
-## Backdrop & cutout
-
-| Theme token                                                  | RN usage                                                                                                             |
-| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `backdropColor`                                              | Modal full-screen backdrop; tooltip cutout fill                                                                      |
-| `backdropOpacity`                                            | Parsed float (`parseBackdropOpacity`)                                                                                |
-| `modalBackdropOnclick`                                       | `DISMISS` → tap backdrop ends flow                                                                                   |
-| Step `backdrop` / `backdropPadding` / `tooltipTargetBlocked` | Tooltip cutout hole, dim, and interaction blocking (bands block by default; hole sealed when `tooltipTargetBlocked`) |
-
-## Tooltip target highlight
-
-Source: `src/surfaces/resolveHighlightChrome.ts` + `src/surfaces/tooltip/TooltipHighlight.tsx`.
-
-Web paints the ring as one CSS `box-shadow` on `.userflowjs-tooltip-backdrop`.
-RN uses a **2px brand stroke + one translucent halo**, plus iOS `shadow*` /
-Android `boxShadow` for blur. Theme spread is a placement gap only — it is
-not painted as a thick solid bar.
-
-| Web / theme token          | RN usage                                                                         |
-| -------------------------- | -------------------------------------------------------------------------------- |
-| `backdropHighlightColor`   | Stroke color. Near-white (web default `#ffffff`) is treated as unset — see below |
-| `backdropHighlightOpacity` | Caps the halo at `0.32` so it stays a wash                                       |
-| `backdropHighlightRadius`  | Halo thickness (default `4`)                                                     |
-| `backdropHighlightSpread`  | Added to placement pad when type is `OUTSIDE` (default `0`). Not stroke width    |
-| `backdropHighlightType`    | `OUTSIDE` (default) draws outside the hole; `INSIDE` insets                      |
-
-Placement pad for `OUTSIDE` is `spread + strokeWidth + radius` so the tooltip
-sits clear of the painted ring, not only the theme spread token.
-| Corner radius | `8` + `backdropPadding` (web copies the target's computed radius; RN measure cannot) |
-
-Color fallback: non-white `backdropHighlightColor` → `widgetBackgroundColor` →
-`brandBackgroundColor` → `defaultButtonBackgroundColor` → `#1a57e6`. Web's
-`#ffffff` default is skipped so the dimmed cutout does not get a white frame.
-
-## Typography
-
-| Theme token  | RN usage                            |
-| ------------ | ----------------------------------- |
-| `fontColor`  | Body / heading / close affordance   |
-| `fontSize`   | Base body size                      |
-| `fontFamily` | Applied where Text styles accept it |
-
-## Quote / code-block — TreeDoc chrome
-
-Source of truth: web `userflowjs/styles/bubble-frame.styl` in the main Userflow
-web repo (blockquote / `code` / `pre > code`) and TreeDoc markup
-(`blockquote`, `pre > code`). Spacing tokens from web `$padding-*` assume
-**1rem = 16px**.
-
-Implementation: `src/content/RichContentRenderer.tsx` + `src/content/themeColor.ts`.
-
-| Token         | rem   | RN px |
-| ------------- | ----- | ----- |
-| `$padding-2`  | 0.125 | 2     |
-| `$padding-4`  | 0.25  | 4     |
-| `$padding-8`  | 0.5   | 8     |
-| `$padding-16` | 1     | 16    |
-
-Root content uses `gap: 8` (`ROOT_CONTENT_GAP`). Quote/code add
-`marginBottom: 8` when not last so gap + margin ≈ web’s 16px block spacing.
-
-### Quote (`blockquote`)
-
-| Web rule                                        | RN                                                                               |
-| ----------------------------------------------- | -------------------------------------------------------------------------------- |
-| `border-inline-start: 2px solid rgba(fg, 0.15)` | `borderStartWidth: 2`, `borderStartColor` via `foregroundAlpha(fontColor, 0.15)` |
-| `padding: $padding-4 $padding-16`               | `paddingVertical: 4`, `paddingHorizontal: 16`                                    |
-| `margin-bottom: $padding-16` when not last      | `marginBottom: 8` (+ root gap 8); last painted sibling: 0                        |
-| `min-height: var(--userflow-line-height, 24px)` | `minHeight: 24`                                                                  |
-| Not italic by default                           | No forced `fontStyle: 'italic'`                                                  |
-
-### Code-block (`pre > code`) and inline `code` mark
-
-| Web rule                                                                   | RN                                                                 |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Mono stack (`SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace`) | iOS `Menlo`, Android `monospace`                                   |
-| `font-size: calc(font-size * 0.875)`                                       | `fontSize * 0.875`                                                 |
-| `background: rgba(fg, 0.05)`                                               | `foregroundAlpha(fontColor, 0.05)` (hex / rgb / rgba)              |
-| `border-radius: calc(font-size * 0.25)`                                    | `fontSize * 0.25`                                                  |
-| `pre > code` padding `$padding-8`                                          | `padding: 8` + horizontal `ScrollView` (`nestedScrollEnabled`)     |
-| Inline `code` padding `$padding-2 $padding-4`                              | View chrome wrapper + `paddingVertical: 2`, `paddingHorizontal: 4` |
-
-## Safe area
-
-Surfaces pad with `useSurfaceLayoutInsets`: optional-peer
-`react-native-safe-area-context` (zero fallback) plus a 24px screen margin so
-cards clear Dynamic Island / home indicator regions. While Builder preview is
-active, the measured Preview banner height is added to the top inset so the
-close control is not trapped under the banner. Tall cards cap at that padded
-window height and scroll internally (`overflow: 'hidden'` on the fill; the
-shadow/notch shell stays `overflow: 'visible'`).