@userflow-tech/react-native 0.3.0 → 0.4.0

package/README.md

@@ -4,70 +4,125 @@ Official Userflow SDK for React Native and Expo. Deliver guided flows, tooltips,
 and modals authored in the Userflow dashboard — without shipping a new app
 release for every content change.
 
-> Early development. APIs may change. Packages publish to a private npm org
-> (`publishConfig.access: restricted`).
+> Early development. APIs may change.
 
 ## Requirements
 
-| Peer / dependency                           | Required?  | Why                                                                      |
-| ------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
-| `react`, `react-native`                     | Yes        | Host runtime.                                                            |
-| `@react-native-async-storage/async-storage` | Yes (dep)  | Persists the anonymous user id. Installed with this package.             |
-| `react-native-device-info`                  | Yes (dep)  | Reads the host app store version (bundled; native rebuild required).     |
-| `react-native-view-shot`                    | Yes (peer) | Builder in-app picker screenshots. Native module; rebuild after install. |
-| `react-native-webview`                      | Yes (dep)  | Evaluate JavaScript / WebView banners. Native rebuild required.          |
-| `react-native-safe-area-context`            | Optional   | Correct insets for modal/tooltip surfaces.                               |
-| `@react-navigation/native`                  | Optional   | Screen tracking + NAVIGATE routing (React Navigation).                   |
-| `expo-router`                               | Optional   | Screen tracking + NAVIGATE routing (Expo Router).                        |
-| `@react-native-community/netinfo`           | Optional   | Instant offline→online reconnect (enhancement, not required).            |
-| `expo-secure-store`                         | Optional   | Persist Builder pairing JWT in Keychain/Keystore.                        |
+Declared minimums: React `>=18.2.0`, React Native `>=0.76.0`. React Native
+0.74 and 0.75 cannot install this SDK: `react-native-view-shot` 5.x, which
+Builder element selection needs, requires React Native 0.76 or later. This
+package's test suite runs on React Native 0.81 / React 19.1. The TinyTime
+sample app in this repo runs on Expo SDK 57 / React Native 0.86. Expo Go is
+not supported.
+
+`@react-native-async-storage/async-storage` is the only native module this
+package depends on, so npm installs it. `react-native-webview` and
+`react-native-view-shot` are required peers. npm 7+ and pnpm install required
+peers. Yarn 1 and `npm install --legacy-peer-deps` do not, which is why the
+install commands list WebView and view-shot explicitly.
+`react-native-device-info` is an optional peer for bare React Native.
+
+Install those packages in the **app** as well. Expo SDK 54 and later autolink
+native modules found anywhere in the tree. Bare React Native, and Expo SDK 53
+and older, only autolink packages listed in the app's own `package.json`. A
+direct install also picks a version that matches the app's React Native, inside
+the ranges below.
+
+| Package                                                 | Kind                             | Why                                                                                             | If missing                                                                                                                                                                                                                         |
+| ------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react`, `react-native` `>=0.76.0`                      | Required peers                   | Host runtime.                                                                                   | The app cannot load the SDK. React Native older than 0.76 fails install (`ERESOLVE`) because view-shot 5.x requires it.                                                                                                            |
+| `@react-native-async-storage/async-storage` `>=1.23 <3` | Dependency                       | Anonymous user id and the pairing device id.                                                    | `identifyAnonymous()` throws. Pairing keeps a device id in memory for the session. A dev-only warning is logged from `Userflow.init`.                                                                                              |
+| `react-native-device-info` `>=11 <16`                   | Optional peer, bare React Native | Host app `app_version` / `app_build`. Expo reads `expo-application` / `expo-constants` instead. | Those attributes are omitted. A dev-only warning is logged on bare React Native.                                                                                                                                                   |
+| `react-native-view-shot` `^5.0.0`                       | Required peer                    | Builder element-selection screenshots.                                                          | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`. Version 6.x is outside the tested range and requires React Native 0.80 or later.                                                                  |
+| `react-native-webview` `>=13.8.0 <14`                   | Required peer                    | Evaluate JavaScript and WebView banners.                                                        | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`.                                                                                                                                                      |
+| `react-native-safe-area-context` `>=4 <6`               | Optional peer                    | Insets for banners, flow cards, and Builder bars.                                               | In development, `Userflow.init` warns once. Those surfaces draw under the status bar and home indicator. With the package installed but no `<SafeAreaProvider>`, cards use the device's initial insets and log a separate warning. |
+| `@react-navigation/native`                              | Optional peer                    | Screen tracking and NAVIGATE routing (React Navigation).                                        | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                                                                                                                 |
+| `expo-router`                                           | Optional peer                    | Screen tracking and NAVIGATE routing (Expo Router).                                             | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                                                                                                                 |
+| `@react-native-community/netinfo` `>=11 <13`            | Optional peer                    | Instant offline→online reconnect.                                                               | Recovery still runs on the heartbeat and when the app returns to the foreground. If the JavaScript package is installed but `RNCNetInfo` is not in the binary, the SDK skips it instead of showing a red screen.                   |
+| `expo-secure-store`                                     | Optional peer                    | Persist the Builder pairing JWT in Keychain/Keystore.                                           | The pairing token stays in memory and is lost when the process ends. The SDK loads it only when the `ExpoSecureStore` native module is registered.                                                                                 |
 
 Optional peers are declared `optional: true` in `peerDependenciesMeta`, so
-package managers will not warn if you skip them. Required peers (not marked
-optional) will warn — or fail the install — if they are missing.
+package managers do not warn if you skip them.
+
+npm 7+ and pnpm install required peers (`react-native-webview`,
+`react-native-view-shot`) automatically. Yarn 1 and
+`npm install --legacy-peer-deps` do not install peers, and they bury the
+missing-peer warnings among unrelated ones. That is why the install commands
+list WebView and view-shot explicitly. A clean npm install prints no warning
+about optional peers, so install `react-native-safe-area-context` and NetInfo
+yourself when you want the behavior in the table. An app that already depends
+on an older major (view-shot 4.0.3, NetInfo 9.x, safe-area 3.x, WebView 13.6.x
+or 14.x) fails install with `ERESOLVE`.
 
 ### Expo Go is not supported
 
-Use an **Expo development build** (or bare React Native). The SDK is not
-compatible with Expo Go.
+Use an **Expo development build** (or bare React Native). In development,
+`Userflow.init` logs:
+
+```text
+[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).
+```
 
 ## Install
 
-Packages publish to the private `@userflow-tech` npm org. Create a **granular
-access token** on npm (Read-only, limited to `@userflow-tech`) and put it in
-the host app’s `.npmrc` via an env var — do not commit the token:
+The package is public on npm; no token or `.npmrc` setup is needed.
+
+Yarn 2 and later ignore `.npmrc`. Add this to `.yarnrc.yml` instead:
 
-```ini
-@userflow-tech:registry=https://registry.npmjs.org/
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```yaml
+npmScopes:
+  userflow-tech:
+    npmRegistryServer: 'https://registry.npmjs.org'
+    npmAuthToken: '${NPM_TOKEN}'
 ```
 
+Set `NPM_TOKEN` in the environment that installs dependencies: a local shell,
+CI, and EAS (an EAS secret named `NPM_TOKEN`, available to the install step).
+
+### Packages
+
 ```bash
 # Expo (dev build)
-npx expo install @userflow-tech/react-native react-native-view-shot@^5.0.0 react-native-webview
+npx expo install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-webview react-native-view-shot@^5.0.0
 
 # Bare React Native
-npm install @userflow-tech/react-native react-native-view-shot react-native-webview
+npm install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-device-info react-native-webview react-native-view-shot@^5.0.0
 cd ios && pod install
 ```
 
-`react-native-view-shot` is a **required peer** (`>=5.0.0`). It is a native
-module — rebuild after install (Metro reload is not enough). On Expo SDK 54,
+`react-native-webview` and `react-native-view-shot` (`^5.0.0`) are **required
+peers**. npm 7+ and pnpm install them. Yarn 1 and
+`npm install --legacy-peer-deps` do not, so the commands above install them in
+the app. Both are native modules — rebuild after install (a Metro reload is not
+enough). On Expo SDK 54,
 unpinned `npx expo install react-native-view-shot` resolves **4.0.3**, which
-does not satisfy the peer and breaks New Architecture / bridgeless. Pin
-`^5.0.0` (or `@latest`) as in the command above.
+does not satisfy the peer. Pin `^5.0.0` as in the command above. If the app
+already depends on 4.0.3, that same command is what fixes it: installing the
+SDK alone fails with
 
-`@react-native-async-storage/async-storage` and `react-native-device-info` are
-dependencies of this package and are installed automatically with a normal npm
-install. After adding or upgrading the SDK, rebuild the native app (`cd ios &&
-pod install`, then run again). If autolinking misses a bundled native module
-(common with local `file:` links), install it in the host app explicitly:
+```text
+npm error Found: react-native-view-shot@4.0.3
+npm error peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native
+```
 
-```bash
-npm install @react-native-async-storage/async-storage react-native-device-info
-cd ios && pod install   # iOS
+Do not retry with `--force` or `--legacy-peer-deps`. That installs the SDK and
+leaves 4.0.3 in place. If that already happened, `Userflow.init` warns in
+development and names the installed version. If `expo doctor`
+reports the `^5.0.0` pin, exclude it from Expo's version check:
+
+```json
+{
+  "expo": {
+    "install": {
+      "exclude": ["react-native-view-shot"]
+    }
+  }
+}
 ```
 
+On a bare React Native app, `expo-secure-store` needs Expo modules installed
+first (`npx install-expo-modules@latest`), then `npx expo install expo-secure-store`.
+
 Optional peers as needed:
 
 ```bash
@@ -79,42 +134,116 @@ For local tarball installs from this monorepo, pack with `pnpm pack:all` at the
 repo root and install the single `@userflow-tech/react-native` tarball. Steps:
 `docs/local-testing.md` in the monorepo.
 
+### Install with an AI agent
+
+Cursor, Claude Code, and other agents that read Agent Skills can do this
+install. The skill is `install-react-native-with-ai` in
+[userflow/ai-skills-library](https://github.com/userflow/ai-skills-library).
+Web apps use `install-with-ai` from that library instead.
+
+```bash
+npx skills add userflow/ai-skills-library@install-react-native-with-ai
+```
+
+Claude Code loads it from the plugin:
+
+```text
+/plugin marketplace add userflow/ai-skills-library
+/plugin install userflow@ai-skills-library
+/userflow:install-react-native-with-ai
+```
+
 ## Quick start
 
 ```tsx
 import { Userflow, UserflowProvider } from '@userflow-tech/react-native';
 
 await Userflow.init({
-  clientToken: 'ct_...', // from the Userflow dashboard → Environments
-  // serverEndpoint: 'https://e.userflow.com', // default; set for staging/local
-  // pairingEndpoint: 'https://e.userflow.com', // default; set for local Builder pairing
+  clientToken: 'ct_...', // from the Userflow dashboard → Environments. Never an esk_ secret key.
+  // serverEndpoint: 'https://e.userflow.com', // default (US). EU: 'https://e.eu.userflow.com'
+  // pairingEndpoint: 'https://e.userflow.com', // default; pairing stays on the US host
 });
 
 // Identified user — signature is computed by YOUR backend, never in the app.
 // `locale_code` is the same user attribute as web (see Localization below).
 await Userflow.identify('user-123', { name: 'Ada', locale_code: 'da-DK' }, { signature });
 
-// …or anonymous (id stored in AsyncStorage):
+// Anonymous users count toward MAU. Call this only when you intend to identify
+// signed-out users. The id is stored in AsyncStorage.
 await Userflow.identifyAnonymous();
 ```
 
-Wrap the app tree so flows can render:
+Call `Userflow.teardown()` when tearing the SDK down (removes AppState and
+NetInfo subscriptions). Call `Userflow.reset()` on logout to clear identity and
+disconnect. `reset()` does not apply a new `clientToken` or endpoint; restart
+the app to change those.
+
+### Where to put `init`, `identify`, and `UserflowProvider`
+
+Call `Userflow.init` once, as early as you can, from the root component
+(`app/_layout.tsx` with Expo Router, `App.tsx` with bare React Native or React
+Navigation). `UserflowProvider` can mount before that promise resolves. Put it
+once, near the top of the tree, inside `SafeAreaProvider`. Call `identify` after
+sign-in. `identifyAnonymous` identifies signed-out users and counts them toward
+MAU, so use it only when you mean to. Call `Userflow.reset()` on logout.
+
+Expo Router:
 
 ```tsx
-import { UserflowProvider } from '@userflow-tech/react-native';
+import { useEffect } from 'react';
+import { Userflow, UserflowProvider } from '@userflow-tech/react-native';
+import { UserflowExpoRouterScreenTracker } from '@userflow-tech/react-native/expo-router';
+import { Stack } from 'expo-router';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 export default function RootLayout() {
+  useEffect(() => {
+    void Userflow.init({ clientToken: 'ct_...' });
+  }, []);
+
   return (
-    <UserflowProvider>
-      <App />
-    </UserflowProvider>
+    <SafeAreaProvider>
+      <UserflowProvider>
+        <UserflowExpoRouterScreenTracker />
+        <Stack />
+      </UserflowProvider>
+    </SafeAreaProvider>
   );
 }
 ```
 
-Call `Userflow.teardown()` when tearing the SDK down (removes AppState and
-NetInfo subscriptions). Call `Userflow.reset()` on logout to clear identity and
-disconnect.
+React Navigation:
+
+```tsx
+import { useEffect } from 'react';
+import { Userflow, UserflowProvider } from '@userflow-tech/react-native';
+import { WithUserflowReactNavigation } from '@userflow-tech/react-native/navigation';
+import { NavigationContainer } from '@react-navigation/native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+
+export default function App() {
+  useEffect(() => {
+    void Userflow.init({ clientToken: 'ct_...' });
+  }, []);
+
+  return (
+    <SafeAreaProvider>
+      <UserflowProvider>
+        <WithUserflowReactNavigation>
+          <NavigationContainer>{/* navigators */}</NavigationContainer>
+        </WithUserflowReactNavigation>
+      </UserflowProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+Without `SafeAreaProvider`, development logs this once and flow cards fall back
+to the device's initial insets:
+
+```text
+[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.
+```
 
 ### Call order
 
@@ -129,9 +258,15 @@ disconnect.
 
 Other rules:
 
-- `init()` is **idempotent**. A second call returns the cached promise and does
-  **not** apply new options. Restart the process (or call `reset()` then
-  re-init carefully) if you need different credentials.
+- `init()` is **idempotent** once it has succeeded. A later call returns the
+  cached promise and does **not** apply new options. In development, a call
+  with a different `clientToken`, `serverEndpoint`, or `pairingEndpoint` while
+  that init is in flight or has succeeded logs
+  `[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.`
+  Restart the app to change them after a successful init. If `init` rejects
+  (wrong token, or the EU endpoint hint), call it again with the corrected
+  options; that retry runs. `Userflow.reset()` clears the signed-in user;
+  it does not apply new credentials.
 - `identify()` with a **different** user id resets the previous identity first.
   Same-id re-identify merges attributes.
 - Identity verification `signature` is optional in the type, but **required by
@@ -191,13 +326,16 @@ subpath under `UserflowProvider` (the tracker is a separate entry so apps withou
 import { UserflowProvider } from '@userflow-tech/react-native';
 import { UserflowExpoRouterScreenTracker } from '@userflow-tech/react-native/expo-router';
 import { Stack } from 'expo-router';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 export default function RootLayout() {
   return (
-    <UserflowProvider>
-      <UserflowExpoRouterScreenTracker />
-      <Stack />
-    </UserflowProvider>
+    <SafeAreaProvider>
+      <UserflowProvider>
+        <UserflowExpoRouterScreenTracker />
+        <Stack />
+      </UserflowProvider>
+    </SafeAreaProvider>
   );
 }
 ```
@@ -211,14 +349,17 @@ Wrap `NavigationContainer` with `WithUserflowReactNavigation` from the
 import { UserflowProvider } from '@userflow-tech/react-native';
 import { WithUserflowReactNavigation } from '@userflow-tech/react-native/navigation';
 import { NavigationContainer } from '@react-navigation/native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 
 export default function App() {
   return (
-    <UserflowProvider>
-      <WithUserflowReactNavigation>
-        <NavigationContainer>{/* navigators */}</NavigationContainer>
-      </WithUserflowReactNavigation>
-    </UserflowProvider>
+    <SafeAreaProvider>
+      <UserflowProvider>
+        <WithUserflowReactNavigation>
+          <NavigationContainer>{/* navigators */}</NavigationContainer>
+        </WithUserflowReactNavigation>
+      </UserflowProvider>
+    </SafeAreaProvider>
   );
 }
 ```
@@ -236,9 +377,11 @@ useUserflowScreen(route.name);
 ## Element targeting (anchors)
 
 Tooltip steps and ELEMENT client conditions resolve a dashboard selector like
-`#invite-teammates` to a host view. Prefer a plain `testID` (or `nativeID` /
-`accessibilityLabel`) — no SDK hook required. A misspelled or missing anchor can
-mean the tooltip misses **or** a gated flow never starts at all.
+`#invite-teammates` to a host view. Tag it with `userflowId` (strongest), then
+`testID`, then `nativeID`, then `accessibilityLabel` — no SDK hook required. A
+misspelled or missing anchor can mean the tooltip misses **or** a gated flow
+never starts at all. `PRESENT`, `NOT_PRESENT`, `CLICK`, and `NOT_CLICK`
+auto-start conditions are evaluated on device.
 
 ```tsx
 import { Pressable, Text } from 'react-native';
@@ -352,8 +495,8 @@ Screen tracking ≠ action routing. React Navigation apps need
 | `setOnNavigate(handler)`                                  | Override or clear the host NAVIGATE handler.                                                                                                                       |
 | `reportActivity()`                                        | Reset the idle timer; reconnect an idle-suspended socket.                                                                                                          |
 | `didHandleURL(url)`                                       | Handle a Userflow preview deep link (`…://?token=…`).                                                                                                              |
-| `handlePairingUrl(url)`                                   | Handle a Builder pairing deep link (`…://?pairing_token=…`; dev builds only).                                                                                      |
-| `exitPreview()`                                           | Leave Builder preview mode; disconnect the pairing websocket (dev only).                                                                                           |
+| `handlePairingUrl(url)`                                   | Handle a Builder pairing deep link (`…://?pairing_token=…`). Works in every build; the signed JWT gates the session.                                               |
+| `exitPreview()`                                           | Leave Builder preview mode; disconnect the pairing websocket. Works in every build.                                                                                |
 | `inspectPairingDeepLink(url)`                             | Classify a URL as pairing without consuming it; reports rejection reason.                                                                                          |
 | `isPairingAttempt(reason)`                                | True when a rejection was a recognisable pairing attempt worth reporting.                                                                                          |
 | `parsePairingDeepLink(url)` / `isUserflowPairingUrl(url)` | Parse / detect a pairing deep link.                                                                                                                                |
@@ -374,7 +517,7 @@ Screen tracking ≠ action routing. React Navigation apps need
 | `useUserflow()`                         | Provider context (`{ engine }`); throws outside the provider.                                                                                                                                                                            |
 | `useFlowSessionState()`                 | Reactive view of the active mid-flow session (advanced / custom UI).                                                                                                                                                                     |
 | `useUserflowScreen(name)`               | Report the active screen from a React tree.                                                                                                                                                                                              |
-| `useUserflowAnchor(id)`                 | Optional override: register a view as a MANUAL target (beats `testID`).                                                                                                                                                                  |
+| `useUserflowAnchor(id)`                 | Optional override: register a view as a MANUAL target (beats `userflowId` / `testID`).                                                                                                                                                   |
 | `useUserflowScrollContainer(onScroll?)` | Optional override: register a `ScrollView` for tooltip scroll-into-view.                                                                                                                                                                 |
 | `Userflow.setScrollPadding(padding)`    | Sticky chrome insets when scrolling targets into view.                                                                                                                                                                                   |
 | `Userflow.setCustomScrollIntoView(fn)`  | Replace scroll-into-view (e.g. unsupported scroll libraries).                                                                                                                                                                            |
@@ -411,11 +554,158 @@ Screen tracking ≠ action routing. React Navigation apps need
 - AUTO / codeless element targeting (exact-id fast path + scored matcher;
   scored path needs Babel full mode to populate the auto-anchor registry).
   See [docs/anchoring.md](docs/anchoring.md).
+- Build-time stamping with `@userflow-tech/react-native/babel-plugin`. Jest
+  runs the plugin too, which changes snapshots. Read
+  [Babel plugin and snapshot tests](#babel-plugin-and-snapshot-tests) before
+  enabling it.
+
+## Install diagnostics
+
+In development, the first `Userflow.init` checks native module registration and
+whether `react-native-safe-area-context` is installed. Missing native modules
+share one warning. A missing safe-area package gets its own warning, because
+flows still run and draw under the status bar. It does not `require` an
+unlinked package (including NetInfo, whose import throws when `RNCNetInfo` is
+absent). Rebuild the native app after fixing a native-module line; a Metro
+reload is not enough. Installing safe-area-context also needs a rebuild, then a
+`<SafeAreaProvider>` around the app. The warnings look like this (only the
+missing lines are included):
+
+```text
+[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):
+- @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.
+- react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install react-native-view-shot@^5.0.0 and rebuild. On Expo SDK 54, pin ^5.0.0; an unpinned npx expo install resolves 4.0.3.
+- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.
+- react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.
+See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
+```
+
+```text
+[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>.
+See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
+```
+
+Passing an environment secret key as `clientToken` throws:
+
+```text
+clientToken is an environment secret key (esk_...). That key must never ship in the app. Pass the client token (ct_...) from Settings → Environments instead.
+```
+
+When the default US endpoint rejects the token with `invalid_client_token`, the
+error also says: `For EU-hosted environments pass serverEndpoint: 'https://e.eu.userflow.com'.`
+Pairing stays on `https://e.userflow.com`.
+
+`expo prebuild` warns when the config plugin has no `schemeId`, when
+`react-native-view-shot` is missing or older than 5, and (on Expo SDK 53 and
+older) when AsyncStorage, WebView, or safe-area-context is not a direct
+dependency. Expo SDK 54 and later autolink safe-area-context when another
+package such as Expo Router brought it in, so prebuild stays quiet in that
+case. `Userflow.init` still warns when the package itself cannot be loaded.
+Passing an environment UUID as `schemeId` fails the prebuild:
+
+```text
+[@userflow-tech/react-native] schemeId "550e8400-e29b-41d4-a716-446655440000" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.
+```
+
+## Jest
+
+Mock the package in the host app's Jest setup so tests do not load native
+modules. Mock the router entry you import as well:
+
+```ts
+// jest.setup.ts
+import type { ReactNode } from 'react';
+
+jest.mock('@userflow-tech/react-native', () => ({
+  Userflow: {
+    init: jest.fn(() => Promise.resolve()),
+    identify: jest.fn(() => Promise.resolve()),
+    identifyAnonymous: jest.fn(() => Promise.resolve()),
+    reset: jest.fn(() => Promise.resolve()),
+    track: jest.fn(() => Promise.resolve()),
+    updateScreen: jest.fn(),
+  },
+  UserflowProvider: ({ children }: { children: ReactNode }) => children,
+}));
+
+// Expo Router
+jest.mock('@userflow-tech/react-native/expo-router', () => ({
+  UserflowExpoRouterScreenTracker: () => null,
+}));
+
+// React Navigation
+jest.mock('@userflow-tech/react-native/navigation', () => ({
+  WithUserflowReactNavigation: ({ children }: { children: ReactNode }) => children,
+}));
+```
+
+In a JavaScript setup file, drop the `ReactNode` import and the type
+annotations.
+
+A custom Metro config that does not extend `getDefaultConfig` from `expo/metro-config`
+or `@react-native/metro-config` leaves `allowOptionalDependencies` off. Optional
+peers that this package loads inside `try/catch` then fail the bundle with
+`Unable to resolve module`. Extend the default config so that flag stays on.
+
+### Babel plugin and snapshot tests
+
+If you add the optional `@userflow-tech/react-native/babel-plugin` to
+`babel.config.js`, Jest runs it too, because `babel-jest` reads the same config.
+The plugin adds props to `View`, `Text`, `Pressable`, the Touchables,
+`TextInput`, and `Image`, and React Native's Jest mocks render them, so they
+appear in snapshots:
+
+```diff
+ <Text
++  __ufid="src/SettingsScreen.tsx::SettingsScreen > View#0 > Text{text=Settings}"
++  collapsable={false}
++  nativeID="uf_1mcelg9"
+ >
+   Settings
+ </Text>
+```
+
+- `nativeID="uf_…"` is added to elements without a `testID`, `nativeID`, or
+  `userflowId`.
+- `collapsable={false}` is added to `View`, `Text`, `Pressable`, and the
+  Touchables, including elements that have a `testID`.
+- `__ufid` (the element's path in the file) is added in every non-production
+  build, which includes Jest.
+- `__ufManual="true"` is added to elements that have a `testID`, `nativeID`, or
+  `userflowId`.
+
+Updating the snapshots once does not settle it. The ids come from the file path,
+the component name, each element's position among siblings of the same type, and
+static labels. Changing a label, adding an element above others of the same type,
+or moving or renaming a file changes them again. The plugin also imports this
+package into every stamped file, so any test that renders a stamped component
+loads the SDK. Keep the mock above in the Jest setup file.
+
+Skip the plugin under Jest:
+
+```js
+// babel.config.js
+module.exports = function (api) {
+  const isTest = api.env('test');
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: isTest ? [] : ['@userflow-tech/react-native/babel-plugin'],
+  };
+};
+```
+
+Remove `api.cache(true)` if your config has it. Called before `api.env`, it makes
+Babel throw `Caching has already been configured with .never or .forever()`.
+`api.env` already caches the config per environment. Development and release
+builds still run the plugin.
+
+To keep some stamping under test, pass `{ stampOnly: isTest }` to the plugin
+instead. Snapshots then gain only `nativeID` and `collapsable`, and stamped files
+skip the SDK import. The plugin's `exclude` option does not help here: it skips
+the files it lists, not the components a test renders.
 
 ## What is not available yet
 
-- Banners and embed (inline) surfaces
-- `Userflow.track()` / custom event tracking
 - `INPUT_VALUE` / `FILLED_IN_INPUT` client conditions
 
 Flows gated on unsupported client conditions stay unknown and **never start**.