@userflow-tech/react-native 0.3.0 → 0.3.1

package/README.md

@@ -9,18 +9,28 @@ release for every content 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.74.0`. 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.
+
+Install AsyncStorage, WebView, and (on bare React Native) device-info in the
+**app**, even though this package also depends on them. Expo SDK 54 and later
+autolink transitive native modules. 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.
+
+| Package                                     | Required?                | Why                                                                                             | If missing                                                                                                                            |
+| ------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `react`, `react-native`                     | Yes                      | Host runtime.                                                                                   | The app cannot load the SDK.                                                                                                          |
+| `@react-native-async-storage/async-storage` | Yes, install in the app  | 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`                  | Yes on 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`          | Yes (peer)               | Builder element-selection screenshots.                                                          | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`.                                                      |
+| `react-native-webview` `>=13.8.0`           | Yes, install in the app  | Evaluate JavaScript and WebView banners.                                                        | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`.                                                         |
+| `react-native-safe-area-context`            | Optional                 | Insets for modal and tooltip surfaces.                                                          | One dev warning. Flow cards use the device's initial safe-area insets, or zero when those are unavailable.                            |
+| `@react-navigation/native`                  | Optional                 | Screen tracking and NAVIGATE routing (React Navigation).                                        | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                    |
+| `expo-router`                               | Optional                 | Screen tracking and NAVIGATE routing (Expo Router).                                             | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                    |
+| `@react-native-community/netinfo`           | Optional                 | Instant offline→online reconnect.                                                               | Recovery still runs on the heartbeat and when the app returns to the foreground.                                                      |
+| `expo-secure-store`                         | Optional                 | Persist the Builder pairing JWT in Keychain/Keystore.                                           | The pairing token stays in memory and is lost when the process ends.                                                                  |
 
 Optional peers are declared `optional: true` in `peerDependenciesMeta`, so
 package managers will not warn if you skip them. Required peers (not marked
@@ -28,46 +38,75 @@ optional) will warn — or fail the install — if they are missing.
 
 ### 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:
+### Access
+
+Packages publish to the private `@userflow-tech` npm org. Userflow adds the
+client's npm user or organization to a **read-only team** on that org. The
+client then creates a **granular access token** on npm (Read-only, limited to
+`@userflow-tech`). A `404` from `npm install` or `npm view @userflow-tech/react-native`
+means the token is missing, or that user or org is not on the team. npm uses
+404 for a private package the caller cannot see.
+
+### npm, Yarn, and CI
+
+npm and Yarn 1 read `.npmrc`. Do not commit the token:
 
 ```ini
 @userflow-tech:registry=https://registry.npmjs.org/
 //registry.npmjs.org/:_authToken=${NPM_TOKEN}
 ```
 
+Yarn 2 and later ignore `.npmrc`. Add this to `.yarnrc.yml` instead:
+
+```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,
+module — 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.
-
-`@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:
+does not satisfy the peer. Pin `^5.0.0` as in the command above. If `expo doctor`
+reports that pin, exclude it from Expo's version check:
 
-```bash
-npm install @react-native-async-storage/async-storage react-native-device-info
-cd ios && pod install   # iOS
+```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 +118,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 +242,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 +310,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 +333,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 +361,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 +479,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 +501,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 +538,146 @@ 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
+logs one warning when something the SDK needs is not linked. It does not
+`require` an unlinked package. Rebuild the native app after fixing the list; a
+Metro reload is not enough. The warning looks 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 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 or WebView is not a direct dependency. 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**.