@userflow-tech/react-native 0.2.0 → 0.3.1

package/README.md

@@ -9,17 +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-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
@@ -27,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
+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
+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
@@ -78,72 +118,187 @@ 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:
-await Userflow.identify('user-123', { name: 'Ada' }, { signature });
+// 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
 
-| Call                             | Before `init()` resolves                               | Before `identify()`                                                                         |
-| -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
-| `identify` / `identifyAnonymous` | **Throws** `Call Userflow.init() before identify()`    | —                                                                                           |
-| `group`                          | **Throws** `Call Userflow.init() before group()`       | **Throws** `Call Userflow.identify() before group()`                                        |
-| `updateUser`                     | **Throws** `Call Userflow.init() before updateUser()`  | **Throws** `Call Userflow.identify() before updateUser()`                                   |
-| `updateGroup`                    | **Throws** `Call Userflow.init() before updateGroup()` | **Throws** `Call Userflow.identify() before updateGroup()`; also requires a prior `group()` |
-| `track`                          | **Throws** `Call Userflow.init() before track()`       | **Throws** `Call Userflow.identify() before track()`                                        |
-| `updateScreen`                   | Silently buffers; included on the next channel join    | Silently buffers                                                                            |
+| Call                             | Before `init()` resolves                               | Before `identify()`                                                                                                                                                             |
+| -------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `identify` / `identifyAnonymous` | **Throws** `Call Userflow.init() before identify()`    | —                                                                                                                                                                               |
+| `group`                          | **Throws** `Call Userflow.init() before group()`       | **Throws** `Call Userflow.identify() before group()`                                                                                                                            |
+| `updateUser`                     | **Throws** `Call Userflow.init() before updateUser()`  | **Throws** `Call Userflow.identify() before updateUser()`                                                                                                                       |
+| `updateGroup`                    | **Throws** `Call Userflow.init() before updateGroup()` | **Throws** `Call Userflow.identify() before updateGroup()`; also requires a prior `group()`                                                                                     |
+| `track`                          | **Throws** `Call Userflow.init() before track()`       | **Throws** `Call Userflow.identify() before track()`. Network, rate-limit, and unexpected SDK errors are isolated (the promise resolves; see [isolation.md](docs/isolation.md)) |
+| `updateScreen`                   | Silently buffers; included on the next channel join    | Silently buffers                                                                                                                                                                |
 
 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
   the server** when the environment has identity verification enabled. See
   [docs/identity-verification.md](docs/identity-verification.md).
 
+## Localization
+
+Pass the end-user's locale the same way as userflow.js: as a user attribute on
+`identify`, `identifyAnonymous`, or `updateUser`. The attribute name is the
+company's locale attribute (default `locale_code`).
+
+```ts
+await Userflow.identify('user-123', { name: 'Ada', locale_code: 'da-DK' }, { signature });
+```
+
+When that locale is enabled on the flow in the Builder, the end-user sees the
+translated content. If the user has no locale stored, or the stored code is not
+a locale the company has set up, the flow stays in its original language.
+Omitting the attribute on a later identify does not clear a locale already
+stored for that user. A locale the company has, but that is not enabled on this
+flow, hides the flow — same as web.
+
+The value is stored on the end user under the company's locale attribute.
+Identifying the same user id on mobile keeps a locale already sent from the web
+app, so mobile does not need to send it again. Sending a new value overwrites
+it; sending `null` clears it. The SDK does not read the device locale.
+
+## Host isolation
+
+The SDK is in-process JS, so it cannot fully sandbox itself from the host app.
+Overlay render errors and fire-and-forget tracking failures are caught, logged
+as `[Userflow] isolated error` via `console.warn`, and swallowed so they cannot
+unmount or crash the host tree. `init` / `identify` still throw — a swallowed
+identify would look like success. Native crashes and errors in **your** children
+of `UserflowProvider` are out of scope.
+
+Details: [docs/isolation.md](docs/isolation.md).
+
 ## Screen tracking
 
 Each accepted screen/path also sends a `screen_viewed` event after identify
-(with `screen_name` or `screen_path`). That is a second client message alongside
-`UpdateClientContext`; both count toward the 100/min cap. Modal / sheet
-presentations are skipped (Expo Router also watches navigation state, so overlays
-that do not change the pathname are skipped too). Returning from background past
-the lifecycle grace window re-fires the current screen.
+(with `screen_name`, which holds the Expo Router path or the screen name). That
+is a second client message alongside `UpdateClientContext`; both count toward
+the 100/min cap. Modal / sheet presentations are skipped (Expo Router also
+watches navigation state, so overlays that do not change the pathname are
+skipped too). Returning from background past the lifecycle grace window
+re-fires the current screen.
 
 ### Expo Router
 
@@ -155,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>
   );
 }
 ```
@@ -175,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>
   );
 }
 ```
@@ -200,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';
@@ -230,10 +393,10 @@ Full contract, prop priority, missing-target behavior, and duplicate-id rules:
 
 To preview draft flows from the Userflow builder onto a device (QR / deep link):
 
-1. Register the environment's **`scheme_id`** (e.g. `userflow-257587` — **not**
-   the env UUID) with the `@userflow-tech/react-native` config plugin, then
-   **rebuild native** (`npx expo prebuild` / a new development client). Metro
-   reload is not enough.
+1. Register the environment's **`scheme_id`** (e.g.
+   `userflow-v7twv2fw2ja2jaco7kesvowmem` — **not** the env UUID) with the
+   `@userflow-tech/react-native` config plugin, then **rebuild native**
+   (`npx expo prebuild` / a new development client). Metro reload is not enough.
 2. Call `Userflow.init` (optionally with `pairingEndpoint` / `serverEndpoint`
    for staging or local stacks) and wrap the tree in `UserflowProvider`.
 3. Open the builder Preview dialog → **Pair a device** → scan/open the QR. The
@@ -243,7 +406,9 @@ To preview draft flows from the Userflow builder onto a device (QR / deep link):
 ```json
 {
   "expo": {
-    "plugins": [["@userflow-tech/react-native", { "schemeId": "userflow-257587" }]]
+    "plugins": [
+      ["@userflow-tech/react-native", { "schemeId": "userflow-v7twv2fw2ja2jaco7kesvowmem" }]
+    ]
   }
 }
 ```
@@ -259,12 +424,12 @@ await Userflow.init({
 
 Deep-link / pairing helpers:
 
-| Member                  | Description                                                      |
-| ----------------------- | ---------------------------------------------------------------- |
-| `didHandleURL(url)`     | Handle a one-shot preview deep link (`…://?token=…`).            |
-| `handlePairingUrl(url)` | Handle a pairing deep link (`…://?pairing_token=…`).             |
-| `exitPreview()`         | Disconnect the pairing websocket and leave preview mode.         |
-| `PreviewModeBanner`     | Mounted by `UserflowProvider` while paired (full-bleed top bar). |
+| Member                  | Description                                                                                                                                                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `didHandleURL(url)`     | Handle a one-shot preview deep link (`…://?token=…`).                                                                                                                                                                        |
+| `handlePairingUrl(url)` | Handle a pairing deep link (`…://?pairing_token=…`, optionally `&purpose=preview` or `&purpose=select_element`).                                                                                                             |
+| `exitPreview()`         | Disconnect the pairing websocket and leave preview mode.                                                                                                                                                                     |
+| `PreviewModeBanner`     | Mounted by `UserflowProvider` while paired. The top bar shows at once for a preview link, stays hidden for an element-selection link and after any pick until the next preview, and waits briefly on a link with no purpose. |
 
 Full scheme registration, Linking ownership, and verify commands:
 [docs/deep-linking.md](docs/deep-linking.md). Symptom table:
@@ -299,54 +464,54 @@ Screen tracking ≠ action routing. React Navigation apps need
 
 ### `Userflow`
 
-| Member                                                    | Description                                                                                                                                              |
-| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `init(config)`                                            | Validate credentials, store config, start lifecycle + network controllers.                                                                               |
-| `identify(userId, attributes?, options?)`                 | Identify a user; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build` from init; `options.signature` for identity verification. |
-| `identifyAnonymous(attributes?, options?)`                | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build`.                                     |
-| `group(groupId, attributes?, options?)`                   | Associate the current user with a group.                                                                                                                 |
-| `updateUser(attributes?)`                                 | Upsert attributes for the current user without re-identifying.                                                                                           |
-| `updateGroup(attributes?, options?)`                      | Upsert group / membership attributes without re-grouping.                                                                                                |
-| `track(name, attributes?, options?)`                      | Record a custom event (literal attribute values only); `userOnly` skips group.                                                                           |
-| `reset()`                                                 | Clear identity, client conditions, flow session; disconnect.                                                                                             |
-| `teardown()`                                              | Stop AppState / NetInfo / screen-tracking subscriptions.                                                                                                 |
-| `updateScreen(name)`                                      | Report the active screen (prefer hooks when possible).                                                                                                   |
-| `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).                                                                                 |
-| `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.                                                                                                                      |
-| `getUserId()`                                             | Current user id, or `null` before identify.                                                                                                              |
-| `getAttributes()`                                         | Copy of attributes for the current user.                                                                                                                 |
-| `getFlowSessionEngine()`                                  | Mid-flow session engine (created lazily; attach runs after identify).                                                                                    |
-| `getHostAppVersion()`                                     | Host app native version cached at init, or `null` before init / when unavailable.                                                                        |
-| `getDeviceContext()`                                      | Platform metadata cached during `init` (`sdk`, `deviceOs`, `deviceType`), or `null` before init.                                                         |
-| `logHostAppVersion()`                                     | Log the host app's native version (not `SDK_VERSION`) and platform OS. Uses bundled device-info on bare RN.                                              |
-| `logDeviceContext()`                                      | Log cached user-attribute values (`sdk` / `device_os` / `device_type`). Requires `init`.                                                                 |
+| Member                                                    | Description                                                                                                                                                        |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `init(config)`                                            | Validate credentials, store config, start lifecycle + network controllers.                                                                                         |
+| `identify(userId, attributes?, options?)`                 | Identify a user; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build` from init; `options.signature` for identity verification.           |
+| `identifyAnonymous(attributes?, options?)`                | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build`.                                               |
+| `group(groupId, attributes?, options?)`                   | Associate the current user with a group.                                                                                                                           |
+| `updateUser(attributes?)`                                 | Upsert attributes for the current user without re-identifying.                                                                                                     |
+| `updateGroup(attributes?, options?)`                      | Upsert group / membership attributes without re-grouping.                                                                                                          |
+| `track(name, attributes?, options?)`                      | Record a custom event (literal attribute values only); `userOnly` skips group. Misuse (`UserflowAuthError`) rejects; network / rate-limit / SDK bugs are isolated. |
+| `reset()`                                                 | Clear identity, client conditions, flow session; disconnect.                                                                                                       |
+| `teardown()`                                              | Stop AppState / NetInfo / screen-tracking subscriptions.                                                                                                           |
+| `updateScreen(name)`                                      | Report the active screen (prefer hooks when possible).                                                                                                             |
+| `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=…`). 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.                                                                                                                                |
+| `getUserId()`                                             | Current user id, or `null` before identify.                                                                                                                        |
+| `getAttributes()`                                         | Copy of attributes for the current user.                                                                                                                           |
+| `getFlowSessionEngine()`                                  | Mid-flow session engine (created lazily; attach runs after identify).                                                                                              |
+| `getHostAppVersion()`                                     | Host app native version cached at init, or `null` before init / when unavailable.                                                                                  |
+| `getDeviceContext()`                                      | Platform metadata cached during `init` (`sdk`, `deviceOs`, `deviceType`), or `null` before init.                                                                   |
+| `logHostAppVersion()`                                     | Log the host app's native version (not `SDK_VERSION`) and platform OS. Uses bundled device-info on bare RN.                                                        |
+| `logDeviceContext()`                                      | Log cached user-attribute values (`sdk` / `device_os` / `device_type`). Requires `init`.                                                                           |
 
 ### Hooks and components
 
-| Export                                  | Description                                                                              |
-| --------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `UserflowProvider`                      | Root overlay host. Does not track screens on its own.                                    |
-| `PreviewModeBanner`                     | Shown by the provider as a full-bleed top bar while a Builder pairing session is active. |
-| `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`).                  |
-| `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).                            |
+| Export                                  | Description                                                                                                                                                                                                                              |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `UserflowProvider`                      | Root overlay host. Does not track screens on its own. Overlay render errors are isolated from host children.                                                                                                                             |
+| `PreviewModeBanner`                     | Shown by the provider while a Builder pairing session is active. It shows at once for a preview link, stays hidden for an element-selection link and after any pick until the next preview, and waits briefly on a link with no purpose. |
+| `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 `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).                                                                                                                                                                            |
 
 ### Subpath exports
 
-| Import                                    | Provides                                                   |
-| ----------------------------------------- | ---------------------------------------------------------- |
-| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                              |
-| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter` |
+| Import                                    | Provides                                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                                                                           |
+| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter`, `redirectSystemPath` (for `+native-intent`) |
 
 ### Constants
 
@@ -359,24 +524,160 @@ Screen tracking ≠ action routing. React Navigation apps need
 
 ## Guides in this package
 
-| Doc                                                            | Topic                                                      |
-| -------------------------------------------------------------- | ---------------------------------------------------------- |
-| [docs/anchoring.md](docs/anchoring.md)                         | Manual targets, scroll containers, missing-target behavior |
-| [docs/deep-linking.md](docs/deep-linking.md)                   | Builder preview URLs and pairing sessions                  |
-| [docs/identity-verification.md](docs/identity-verification.md) | HMAC signature on your backend                             |
-| [docs/troubleshooting.md](docs/troubleshooting.md)             | Symptom → cause for common integration failures            |
-| [docs/theme-mapping.md](docs/theme-mapping.md)                 | Web → RN theme token mapping (contributor-facing)          |
+| Doc                                                            | Topic                                                       |
+| -------------------------------------------------------------- | ----------------------------------------------------------- |
+| [docs/anchoring.md](docs/anchoring.md)                         | Manual targets, scroll containers, missing-target behavior  |
+| [docs/isolation.md](docs/isolation.md)                         | What “isolated as possible” means; overlay + `track` guards |
+| [docs/deep-linking.md](docs/deep-linking.md)                   | Builder preview URLs and pairing sessions                   |
+| [docs/identity-verification.md](docs/identity-verification.md) | HMAC signature on your backend                              |
+| [docs/troubleshooting.md](docs/troubleshooting.md)             | Symptom → cause for common integration failures             |
+| [docs/theme-mapping.md](docs/theme-mapping.md)                 | Web → RN theme token mapping (contributor-facing)           |
 
 ## Experimental
 
 - 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**.