@userflow-tech/react-native 0.2.0 → 0.3.1

package/docs/deep-linking.md

@@ -20,14 +20,15 @@ pick the environment.
 Example:
 
 ```text
-userflow-257587://?token=SFMyNTY...
+userflow-v7twv2fw2ja2jaco7kesvowmem://?token=SFMyNTY...
 ```
 
-- `{schemeId}` is your environment's `scheme_id` from the dashboard — a full
-  scheme of the form `userflow-` followed by **digits** (not the env UUID). This
-  is the **only** scheme you register; the same one also carries pairing links.
-  The SDK never parses an environment out of the URL — `clientToken` passed to
-  `init` is what identifies the environment.
+- `{schemeId}` is your environment's `scheme_id` from the dashboard:
+  `userflow-` followed by an opaque id (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`).
+  Copy it exactly and do not rely on its shape. It is **not** the env UUID.
+  This is the **only** scheme you register; the same one also
+  carries pairing links. The SDK never parses an environment out of the URL —
+  `clientToken` passed to `init` is what identifies the environment.
 - `{startFlowToken}` is a short-lived token minted by the builder
   (`prepareDraftFlow`).
 
@@ -44,22 +45,41 @@ preview.
 ```
 
 The builder QR usually points at `https://<api-host>/pair/<jwt>`; the backend
-redirects that to the scheme form the SDK parses. Pairing requires the
-`scheme_id` shape specifically (`userflow-` + digits) — an arbitrary
-`userflow-*` scheme can match preview links but **not** pairing ones.
+redirects that to the scheme form the SDK parses. Pairing requires a
+well-formed `scheme_id`: `userflow-` plus one or more letters and digits,
+optionally split by single hyphens. A malformed `userflow-*` scheme (empty id,
+stray hyphens) can match preview links but **not** pairing ones.
 
 ## Expo Router hosts
 
-No extra host files are required for Builder pairing or preview.
+Add `app/+native-intent.ts` so pairing and preview links do not navigate:
+
+```ts
+export { redirectSystemPath } from '@userflow-tech/react-native/expo-router';
+```
 
 The builder QR redirects to `{schemeId}://?pairing_token=…`. Expo Router treats
-that as `/`, which every app already has, so there is no **Unmatched Route**
-screen. The SDK still consumes the URL through React Native `Linking` after
-`Userflow.init()`. Preview tokens travel over the pairing websocket after
-connect — there is no separate preview path URL from the builder.
+that as `/`. For a signed-out user the app's home route then redirects, which
+mounts a second copy of the screen already showing (Sign In, for example).
+Element selection then rejects controls that look duplicated. A signed-in user
+may also be moved off the screen they were on, back to `/`. Returning `null`
+from `redirectSystemPath` keeps the current screen. The SDK still consumes the
+URL through React Native `Linking` after `Userflow.init()`. Preview tokens
+travel over the pairing websocket after connect — there is no separate preview
+path URL from the builder.
+
+If the app already has a `+native-intent.ts`, wrap the existing handler:
+
+```ts
+import { createRedirectSystemPath } from '@userflow-tech/react-native/expo-router';
+
+export const redirectSystemPath = createRedirectSystemPath({
+  next: (event) => event.path,
+});
+```
 
 Bare React Native / React Navigation apps need nothing beyond scheme
-registration either.
+registration.
 
 ## 1. Register the scheme at build time
 
@@ -71,7 +91,7 @@ If you are using `app.config.js`:
 // app.config.js
 module.exports = {
   expo: {
-    plugins: [['@userflow-tech/react-native', { schemeId: 'userflow-257587' }]],
+    plugins: [['@userflow-tech/react-native', { schemeId: 'userflow-v7twv2fw2ja2jaco7kesvowmem' }]],
   },
 };
 ```
@@ -82,7 +102,9 @@ If you are using `app.json`:
 // app.json
 {
   "expo": {
-    "plugins": [["@userflow-tech/react-native", { "schemeId": "userflow-257587" }]]
+    "plugins": [
+      ["@userflow-tech/react-native", { "schemeId": "userflow-v7twv2fw2ja2jaco7kesvowmem" }]
+    ]
   }
 }
 ```
@@ -101,7 +123,7 @@ register the URL scheme. Expo Go is not supported.
   <dict>
     <key>CFBundleURLSchemes</key>
     <array>
-      <string>userflow-257587</string>
+      <string>userflow-v7twv2fw2ja2jaco7kesvowmem</string>
     </array>
   </dict>
 </array>
@@ -114,7 +136,7 @@ register the URL scheme. Expo Go is not supported.
   <action android:name="android.intent.action.VIEW" />
   <category android:name="android.intent.category.DEFAULT" />
   <category android:name="android.intent.category.BROWSABLE" />
-  <data android:scheme="userflow-257587" />
+  <data android:scheme="userflow-v7twv2fw2ja2jaco7kesvowmem" />
 </intent-filter>
 ```
 
@@ -172,17 +194,17 @@ Userflow.init({ clientToken: 'ct_...' }).catch((error) => {
 ```
 
 Other pairing links the SDK reports rather than dropping: one whose scheme is
-not a valid `scheme_id` (`userflow-` followed by digits), one **opened with your
-app's own scheme** instead of the `scheme_id`, one with no `pairing_token`, and a
-session that fails to connect because the token expired or the device is already
-paired.
+not a valid `scheme_id` (`userflow-` followed by letters and digits, optionally
+split by single hyphens), one **opened with your app's own scheme** instead of
+the `scheme_id`, one with no `pairing_token`, and a session that fails to
+connect because the token expired or the device is already paired.
 
 That third case is worth spelling out, because it does not look like a Userflow
 problem. Substituting your app's scheme — `myapp://?pairing_token=…` instead of
-`userflow-257587://?pairing_token=…` — still launches the app, since your own
-scheme is registered, but the SDK rejects it as a foreign scheme (logged +
-**Preview unavailable** top bar when recognisable). Use the `scheme_id` exactly
-as the QR code provides it.
+`userflow-v7twv2fw2ja2jaco7kesvowmem://?pairing_token=…` — still launches the app,
+since your own scheme is registered, but the SDK rejects it as a foreign scheme
+(logged + **Preview unavailable** top bar when recognisable). Use the
+`scheme_id` exactly as the QR code provides it.
 
 Reporting is limited to URLs the SDK can recognise as pairing attempts, so your
 own deep links stay quiet — as do preview links, which accept any `userflow-*`
@@ -194,10 +216,25 @@ A pairing failure never fails `Userflow.init()`. If the QR token has expired,
 `init()` still resolves and the app runs normally, with the reason logged under
 `[Userflow]` and the top bar switching to the error tone.
 
-Optional: install `expo-secure-store` (and configure Expo modules in bare
-React Native) so the pairing JWT can persist in Keychain/Keystore for the
-duration of the session (`npx expo install expo-secure-store`). Without Expo
-modules, the SDK falls back to in-memory storage automatically.
+Relaunching a paired app resumes the Builder session until the pairing token
+expires or you call `Userflow.exitPreview()`. Opening the app from its icon is
+enough — that is what the Builder means by "Open the app if you've paired this
+device". A new pairing link always wins over the stored session.
+
+`Userflow.exitPreview()` (or **Exit preview** in the top bar) also ends the
+previewed flow on the server. Otherwise identify would restore it at its last
+step on the next launch.
+
+Resume requires `expo-secure-store` (Keychain / Keystore). Install it with
+`npx expo install expo-secure-store` and configure Expo modules in bare React
+Native. Without that module the SDK keeps the token in memory only, so killing
+the app does not resume.
+
+The SDK also stores a stable pairing device id in AsyncStorage
+(`userflow:pairingDeviceId`). The server uses it to recognize this install when
+the app rejoins, including a cold start from the pairing link. `reset()` and
+`exitPreview()` do not clear it. A cold start shows **Connecting to Builder…**
+while `Userflow.init()` is still resolving, then **Preview mode**.
 
 ### Host apps that already own Linking
 
@@ -236,10 +273,10 @@ from JS does not.
 
 ```sh
 # iOS
-npx uri-scheme open "userflow-257587://?token=TEST" --ios
+npx uri-scheme open "userflow-v7twv2fw2ja2jaco7kesvowmem://?token=TEST" --ios
 
 # Android
-npx uri-scheme open "userflow-257587://?token=TEST" --android
+npx uri-scheme open "userflow-v7twv2fw2ja2jaco7kesvowmem://?token=TEST" --android
 ```
 
 Use a real token from the builder when testing end-to-end. For the full

package/docs/isolation.md

@@ -0,0 +1,75 @@
+# Host isolation
+
+What “isolated as possible” means for `@userflow-tech/react-native`.
+
+The SDK is in-process JavaScript in the host React tree. It cannot get a
+separate VM, OS process, or native exception handler. Isolation is the set of
+guards below — not a sandbox.
+
+## Default host-visible behavior
+
+**No overlay, no event, no crash.** Failures inside SDK code are caught, logged
+with `console.warn` and a `[Userflow] isolated error` prefix (always, not
+`__DEV__`-only), and swallowed from the host app’s perspective. `console.warn`
+is intentional: React Native release builds forward `console.error` to the
+native exception manager (Crashlytics / Sentry).
+
+## What we contain
+
+| Path                                                                                                                                                | Mechanism                                                                                               |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| React **render / lifecycle** errors in overlay UI (flow surfaces, preview banner, element picker)                                                   | Class `SdkErrorBoundary` around the overlay sibling — **not** around host children                      |
+| Unexpected exceptions and promise rejections on fire-and-forget APIs (`Userflow.track`, `updateScreen`, `reportActivity`, internal `screen_viewed`) | `isolateAsync` / `isolateSync`                                                                          |
+| Event-handler throws on SDK bridges that wrap the host tree (`TargetPressBridge`, `DoubleTapBridge`)                                                | Local try/catch (`isolateSync`). React error boundaries do not catch event handlers.                    |
+| Screen-report callbacks in `WithUserflowReactNavigation`                                                                                            | `isolateSync` around the report path only — **not** a React error boundary around `NavigationContainer` |
+
+A later flow step can still render after an overlay crash: the boundary retries
+when the session/step identity changes to one that has not already failed.
+Reconnecting the same crashed step stays blank. It does not call `endFlow`
+(that can loop or throw again).
+
+## What still throws (host contract)
+
+These are integration mistakes or identity-critical results the host must see:
+
+- `UserflowAuthError` for misuse (`isHostContract`): missing `init` / `identify`,
+  invalid event or attribute names, identity-verification failures. Transport
+  `UserflowAuthError`s leave that flag unset.
+- Failures on **identity-critical** APIs: `init`, `identify`,
+  `identifyAnonymous`, `reset`. A swallowed `identify` would look like success.
+- `group` / `updateUser` / `updateGroup` still reject on auth and transport
+  errors (they are part of the identity path, not fire-and-forget).
+- `useUserflow()` still throws outside `UserflowProvider`.
+- `WithUserflowReactNavigation` still throws if its child is not a single React
+  element (host API misuse).
+
+`Userflow.track()`:
+
+- **Rejects** `UserflowAuthError` (`Call Userflow.init() before track()`,
+  `Call Userflow.identify() before track()`, invalid event name).
+- **Resolves** on network failure, rate limit (`UserflowRateLimitError`), and
+  unexpected SDK bugs. Check device logs for `[Userflow] isolated error`.
+
+## What we cannot contain
+
+- Native module / JSI / Hermes **fatal** crashes.
+- Errors in **host children** of `UserflowProvider`. The app tree is never
+  inside `SdkErrorBoundary` — wrapping it would hide the customer’s own bugs.
+- Host callbacks the SDK invokes (`onNavigate`, `setCustomScrollIntoView`).
+  Those stay the host’s responsibility. The SDK wraps those _call sites_
+  (`openFlowNavigateUrl` / `scrollAnchorIntoView`) so a host throw does not take
+  down overlay internals, but it does not swallow the host’s own render errors.
+
+## Reading the logs
+
+Isolated failures look like:
+
+```text
+[Userflow] isolated error overlay Error: …
+[Userflow] isolated error track Error: socket dropped
+```
+
+The second token is the **scope** (`overlay`, `track`, `updateScreen`,
+`reportActivity`, `double-tap`, `target-press`, `react-navigation-screen`).
+Search logs for `[Userflow] isolated error` when a flow vanishes or an event
+seems missing but the app is still running.

package/docs/troubleshooting.md

@@ -3,25 +3,51 @@
 Symptom → cause for common `@userflow-tech/react-native` integration failures.
 Messages are quoted exactly so you can search logs for them.
 
+## Install
+
+| Symptom / log message                                                                                                                                                                                                                                                                          | Likely cause                                                                                                                                                         | Fix                                                                                                                                                                                             |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `404` from `npm install` or `npm view @userflow-tech/react-native`                                                                                                                                                                                                                             | The npm token is missing, or the npm user or org is not on the read-only `@userflow-tech` team. npm returns 404 for a private package the caller cannot see.         | Ask Userflow to add the npm user or org to the read-only team, then create a granular read-only token limited to `@userflow-tech`.                                                              |
+| Yarn 2+ still 404s with a valid `.npmrc`                                                                                                                                                                                                                                                       | Yarn 2 and later ignore `.npmrc`.                                                                                                                                    | Set `npmScopes.userflow-tech.npmRegistryServer` and `npmAuthToken` in `.yarnrc.yml`.                                                                                                            |
+| EAS or CI install 404s while local install works                                                                                                                                                                                                                                               | `NPM_TOKEN` is not available to that environment.                                                                                                                    | Add `NPM_TOKEN` as an EAS secret or CI secret. The `.npmrc` line `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` reads it at install time.                                                      |
+| `expo doctor` reports `react-native-view-shot`                                                                                                                                                                                                                                                 | The app pins `^5.0.0` and Expo SDK 54's expected version is 4.0.3.                                                                                                   | Keep the pin. Add `"react-native-view-shot"` to `expo.install.exclude`.                                                                                                                         |
+| `Unable to resolve module` for an optional peer (`netinfo`, `expo-secure-store`, `expo-router`, safe-area, navigation)                                                                                                                                                                         | A custom Metro config does not extend `getDefaultConfig`, so `allowOptionalDependencies` is off.                                                                     | Extend `getDefaultConfig` from `expo/metro-config` or `@react-native/metro-config`.                                                                                                             |
+| `[@userflow-tech/react-native] schemeId "…" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.`                                                                                                    | The config plugin received the environment UUID.                                                                                                                     | Pass the `scheme_id` (`userflow-…`) from the dashboard.                                                                                                                                         |
+| `No schemeId was passed, so the plugin left the native config unchanged. Builder preview and pairing links will not open this app. Pass the environment scheme_id (userflow-...) from the Userflow dashboard as the plugin schemeId.`                                                          | `expo prebuild` ran the plugin without `schemeId`.                                                                                                                   | Add `{ "schemeId": "userflow-…" }` and rebuild native.                                                                                                                                          |
+| react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 54, an unpinned `npx expo install react-native-view-shot` resolves 4.0.3. Pin ^5.0.0. If expo doctor reports a version mismatch, add "react-native-view-shot" to expo.install.exclude. | Prebuild did not find view-shot in the app `package.json`.                                                                                                           | `npx expo install react-native-view-shot@^5.0.0` and rebuild.                                                                                                                                   |
+| `react-native-view-shot@4.0.3 is older than 5.0.0. Expo SDK 54's default is 4.0.3, which does not work with this SDK. Pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude if expo doctor complains.`                                                                           | The app has view-shot 4.x.                                                                                                                                           | Pin `^5.0.0` and rebuild.                                                                                                                                                                       |
+| `@react-native-async-storage/async-storage is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Install it in the app (npx expo install @react-native-async-storage/async-storage) and rebuild.`                         | Expo SDK older than 54, and AsyncStorage is only a transitive dependency. The WebView line is the same shape with `react-native-webview`.                            | Install that package in the app and rebuild.                                                                                                                                                    |
+| `[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):`                                                                                                                                                   | Dev-only check on the first `Userflow.init`. Following lines name each missing native module.                                                                        | Install the named packages and rebuild. The footer is `See docs/troubleshooting.md.`                                                                                                            |
+| `- @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.`                                           | AsyncStorage's native module is not in this binary.                                                                                                                  | Add it to the app `package.json`, 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.`                                                                         | `RNViewShot` is not registered.                                                                                                                                      | Install `react-native-view-shot@^5.0.0` and rebuild.                                                                                                                                            |
+| `- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.`                                                                                                                                  | The WebView native module is not registered.                                                                                                                         | 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.`                                                                                                                                                     | Bare React Native, and `RNDeviceInfo` is not registered. Expo apps that have `expo-constants` do not log this line.                                                  | `npm install react-native-device-info` and rebuild.                                                                                                                                             |
+| `[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).`                                                                                         | The app is the Expo Go store client.                                                                                                                                 | Use a development build.                                                                                                                                                                        |
+| `[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.`                                                                                            | `UserflowProvider` has no `SafeAreaProvider` ancestor. The app does not crash. Cards use `initialWindowMetrics`, or zero insets when those are unavailable.          | Wrap the tree in `SafeAreaProvider`.                                                                                                                                                            |
+| `Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not linked in this native build. Add it to your app's package.json, run pod install, and rebuild.`                                                                                                     | `identifyAnonymous()` ran without a linked AsyncStorage native module.                                                                                               | Install and rebuild, then call it again.                                                                                                                                                        |
+| `clientToken is an environment secret key (esk_...). That key must never ship in the app. Pass the client token (ct_...) from Settings → Environments instead.`                                                                                                                                | `init` was given an `esk_` secret key.                                                                                                                               | Pass the `ct_…` client token.                                                                                                                                                                   |
+| `For EU-hosted environments pass serverEndpoint: 'https://e.eu.userflow.com'.`                                                                                                                                                                                                                 | The default US host rejected the token with `invalid_client_token`. This sentence is appended to that error. It is omitted when `serverEndpoint` was set explicitly. | For an EU environment, pass `serverEndpoint: 'https://e.eu.userflow.com'`. Pairing stays on `https://e.userflow.com`.                                                                           |
+| `[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.`                                     | A later `init` passed a different token or endpoint while a previous `init` is in flight or has succeeded.                                                           | Restart the app after a successful init. `reset()` clears the user and does not apply new credentials. If the previous `init` rejected, call `init` again with the corrected token or endpoint. |
+
 ## Init / identify / group
 
-| Symptom / log message                                                                   | Likely cause                                                      | Fix                                                                                                                                  |
-| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `Call Userflow.init() before identify()`                                                | `identify` / `identifyAnonymous` before `init()` resolved         | `await Userflow.init(...)` first                                                                                                     |
-| `Call Userflow.init() before group()`                                                   | `group` before init                                               | Same                                                                                                                                 |
-| `Call Userflow.identify() before group()`                                               | `group` before any identify                                       | Call `identify` or `identifyAnonymous` first                                                                                         |
-| `Call Userflow.init() before updateUser()` / `updateGroup()`                            | `updateUser` / `updateGroup` before init                          | `await Userflow.init(...)` first                                                                                                     |
-| `Call Userflow.identify() before updateUser()`                                          | `updateUser` before any identify                                  | Call `identify` or `identifyAnonymous` first                                                                                         |
-| `Call Userflow.group() before updateGroup()`                                            | `updateGroup` or a group-scoped button attribute before `group()` | Call `Userflow.group(...)` first                                                                                                     |
-| `Missing clientToken`                                                                   | Empty / whitespace token                                          | Pass the `ct_...` value from the dashboard                                                                                           |
-| `… invalid_client_token: Invalid Userflow.js Token: …`                                  | Wrong token, wrong region, or deactivated env                     | Copy the token from the matching environment; EU tokens may need an EU `serverEndpoint`                                              |
-| `… user_signature_required: …`                                                          | Env requires identity verification; no `signature`                | Compute HMAC on your backend — [identity-verification.md](identity-verification.md)                                                  |
-| `… incorrect_user_signature: …`                                                         | Signature does not match HMAC-SHA256(secret, userId)              | Sign the **same** id string; use `esk_...`, not `ct_...`                                                                             |
-| `… group_signature_required` / `incorrect_group_signature`                              | Same rules for `group()`                                          | Sign the group id with the env secret key                                                                                            |
-| `Client message rate limit exceeded (100/min)`                                          | Too many client messages in a 60s window                          | Each accepted screen uses two slots (`UpdateClientContext` + `screen_viewed`); slow down navigation or wait for the window to refill |
-| `Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.` | AsyncStorage threw at runtime                                     | Ensure `@react-native-async-storage/async-storage` is installed and linked                                                           |
-| Module resolution failure for AsyncStorage                                              | Autolinking missed the SDK dependency                             | `npx expo install @react-native-async-storage/async-storage`                                                                         |
-| Second `init()` seems to ignore new options                                             | `init()` is idempotent                                            | Expected; use a fresh process or `reset()` carefully                                                                                 |
+| Symptom / log message                                                                                                                                                                      | Likely cause                                                                       | Fix                                                                                                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Call Userflow.init() before identify()`                                                                                                                                                   | `identify` / `identifyAnonymous` before `init()` resolved                          | `await Userflow.init(...)` first                                                                                                                                                                                                                                            |
+| `Call Userflow.init() before group()`                                                                                                                                                      | `group` before init                                                                | Same                                                                                                                                                                                                                                                                        |
+| `Call Userflow.identify() before group()`                                                                                                                                                  | `group` before any identify                                                        | Call `identify` or `identifyAnonymous` first                                                                                                                                                                                                                                |
+| `Call Userflow.init() before updateUser()` / `updateGroup()`                                                                                                                               | `updateUser` / `updateGroup` before init                                           | `await Userflow.init(...)` first                                                                                                                                                                                                                                            |
+| `Call Userflow.identify() before updateUser()`                                                                                                                                             | `updateUser` before any identify                                                   | Call `identify` or `identifyAnonymous` first                                                                                                                                                                                                                                |
+| `Call Userflow.group() before updateGroup()`                                                                                                                                               | `updateGroup` or a group-scoped button attribute before `group()`                  | Call `Userflow.group(...)` first                                                                                                                                                                                                                                            |
+| `Missing clientToken`                                                                                                                                                                      | Empty / whitespace token                                                           | Pass the `ct_...` value from the dashboard                                                                                                                                                                                                                                  |
+| `… invalid_client_token: Invalid Userflow.js Token: …`                                                                                                                                     | Wrong token, wrong region, or deactivated env                                      | Copy the token from the matching environment. When the default US host returns this, the message also says `For EU-hosted environments pass serverEndpoint: 'https://e.eu.userflow.com'.`                                                                                   |
+| `… user_signature_required: …`                                                                                                                                                             | Env requires identity verification; no `signature`                                 | Compute HMAC on your backend — [identity-verification.md](identity-verification.md)                                                                                                                                                                                         |
+| `… incorrect_user_signature: …`                                                                                                                                                            | Signature does not match HMAC-SHA256(secret, userId)                               | Sign the **same** id string; use `esk_...`, not `ct_...`                                                                                                                                                                                                                    |
+| `… group_signature_required` / `incorrect_group_signature`                                                                                                                                 | Same rules for `group()`                                                           | Sign the group id with the env secret key                                                                                                                                                                                                                                   |
+| `Client message rate limit exceeded (100/min)`                                                                                                                                             | Too many client messages in a 60s window                                           | Each accepted screen uses two slots (`UpdateClientContext` + `screen_viewed`); slow down navigation or wait for the window to refill                                                                                                                                        |
+| `Userflow.identifyAnonymous() is not supported when persistent storage is unavailable.`                                                                                                    | AsyncStorage threw while reading or writing the anonymous id                       | Ensure `@react-native-async-storage/async-storage` is installed and linked                                                                                                                                                                                                  |
+| `Userflow.identifyAnonymous() needs @react-native-async-storage/async-storage, which is not linked in this native build. Add it to your app's package.json, run pod install, and rebuild.` | The native module is not in this binary                                            | Add it to the app `package.json`, run `pod install`, and rebuild                                                                                                                                                                                                            |
+| Second `init()` seems to ignore new options                                                                                                                                                | A previous `init` is in flight or has succeeded. A rejected `init` can be retried. | Development 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.` |
 
 ## Flow never appeared
 
@@ -37,29 +63,30 @@ Look for warnings such as:
 
 ```text
 [Userflow] ELEMENT condition … uses an AUTO (codeless) selector that could not be resolved; …
-[Userflow] ELEMENT condition … uses unsupported elementState "CLICK" …
+[Userflow] ELEMENT condition … uses unsupported elementState "DISABLED" …
 ```
 
 Or a core warning that a condition type has no evaluator (`INPUT_VALUE`,
-`FILLED_IN_INPUT`, …).
+`FILLED_IN_INPUT`, …). `PRESENT`, `NOT_PRESENT`, `CLICK`, and `NOT_CLICK` are
+evaluated. `DISABLED`, `NOT_DISABLED`, and `MOUSEDOWN` are not.
 
-**Workaround:** author the start condition with a **MANUAL** selector and
-`PRESENT` / `NOT_PRESENT`, and tag the target with matching `testID="…"` (or
-`useUserflowAnchor('…')`). See [anchoring.md](anchoring.md).
+**Workaround:** author the start condition with a **MANUAL** selector and one of
+the four supported states, and tag the target with matching `userflowId`,
+`testID`, or `nativeID` (or `useUserflowAnchor('…')`). See [anchoring.md](anchoring.md).
 
 ### 2. Anchor / tooltip placement
 
 | Symptom                                           | Likely cause                                                                                                                                                          |
 | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| “Looking for target…” then “Target not found”     | Wrong id vs dashboard `#css`, no matching `testID`/`nativeID`/`accessibilityLabel` or `useUserflowAnchor`, or zero-size measure                                       |
-| Tooltip never attaches despite a visible element  | **Duplicate** id on disjoint views (ambiguous → fail closed)                                                                                                          |
+| “Looking for target…” then “Target not found”     | Wrong id vs dashboard `#css`, no matching `userflowId`/`testID`/`nativeID`/`accessibilityLabel` or `useUserflowAnchor`, or zero-size measure                          |
+| Tooltip never attaches despite a visible element  | **Duplicate** id on disjoint views (tooltips fail closed; element conditions still treat any match as present)                                                        |
 | Off-screen target not scrolled into view          | Parent `ScrollView` not registered with `useUserflowScrollContainer`                                                                                                  |
 | “To the left/right of target” renders above/below | No room beside the target for even the card's own padding — it shrinks first and flips only as a last resort. Draft/dev logs `… could not be drawn beside the target` |
 | Side-placed tooltip looks unusually narrow        | Expected: a side card takes the room left beside the target and grows taller. Move the target inward, or pick above/below, if you want it wider                       |
 | Flow vanished after a few seconds                 | Theme `tooltipMissingBehavior: END` after tolerance                                                                                                                   |
 | Centered card with step content, no notch         | Theme `tooltipMissingBehavior: BUBBLE` after missing tolerance                                                                                                        |
 
-Id matching: dashboard `#invite-teammates` ↔ `testID="invite-teammates"` (or `useUserflowAnchor('invite-teammates')`).
+Id matching: dashboard `#invite-teammates` ↔ `userflowId="invite-teammates"`, then `testID`, then `nativeID` (or `useUserflowAnchor('invite-teammates')`).
 
 ### 3. Screen / provider
 
@@ -72,28 +99,30 @@ Id matching: dashboard `#invite-teammates` ↔ `testID="invite-teammates"` (or `
 
 ### 4. Connection
 
-| Symptom                                                   | Likely cause                                                                |
-| --------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `WebSocket connection timed out` / `failed`               | Bad `serverEndpoint`, network, or VPN                                       |
-| `invalid_message` on channel join / `UpdateClientContext` | ClientContext missing required `pageUrl`, or sending legacy `path`/`screen` | SDK must send `pageUrl: ""` plus `screenPath` / `screenName` (not `path` / `screen`) |
-| Long recovery after Wi-Fi ↔ cellular while foregrounded   | Install optional `@react-native-community/netinfo` for instant probe        |
-| Session cleared after returning from background           | Away ≥ `SESSION_STALE_AFTER_BACKGROUND_MS` (5 minutes) — by design          |
+| Symptom                                                   | Likely cause                                                                                                                                       |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WebSocket connection timed out` / `failed`               | Bad `serverEndpoint`, network, or VPN                                                                                                              |
+| `invalid_message` on channel join / `UpdateClientContext` | ClientContext missing required `pageUrl`, or sending `screenPath` / legacy `path`/`screen`. The SDK must send `pageUrl: ""` plus `screenName` only |
+| Long recovery after Wi-Fi ↔ cellular while foregrounded   | Install optional `@react-native-community/netinfo` for instant probe                                                                               |
+| Session cleared after returning from background           | Away ≥ `SESSION_STALE_AFTER_BACKGROUND_MS` (5 minutes) — by design                                                                                 |
 
 ## Builder preview / pairing
 
 Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all builds (including release).
 
-| Symptom                                                                                          | Likely cause                                                                                                             | Fix                                                                                                                                                                         |
-| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Deep link opens the app but nothing happens                                                      | Scheme added in config but **no native rebuild**                                                                         | `npx expo prebuild` / new development client; Metro reload is not enough                                                                                                    |
-| Deep link opens the app but nothing happens, and no **Preview mode** top bar appears             | `Userflow.init()` rejected, so there is no session to preview into                                                       | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken` or `serverEndpoint`) and re-open the link |
-| Deep link opens the app and the router shows **Unmatched Route** / "page could not be found"     | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<digits>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme                        |
-| Pairing deep link ignored (preview URL may still work)                                           | Scheme is `userflow-*` but not `userflow-` + **digits**                                                                  | Use the env's `scheme_id` from the dashboard (e.g. `userflow-257587`), not the env UUID                                                                                     |
-| Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks                                                                 | Pair again on the device you are watching, or clear the env's pairing session and re-QR                                                                                     |
-| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** top bar)                                                             | Confirm the top bar before hitting Preview; re-open the pairing QR on this install                                                                                          |
-| Pairing never connects against a local stack                                                     | `pairingEndpoint` still pointing at production                                                                           | `Userflow.init({ pairingEndpoint: 'http://localhost:40401', serverEndpoint: '…' })`                                                                                         |
-| QR / `https://…/pair/<jwt>` does nothing in the app                                              | SDK only parses the **scheme** form after the backend redirect                                                           | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl`                                                                                |
-| Builder selector has no screenshot after Confirm                                                 | Missing / unlinked `react-native-view-shot`, or Expo SDK 54 pinned 4.x                                                   | Install `react-native-view-shot@^5.0.0` and **rebuild native**. Look for `[Userflow] Required peer react-native-view-shot is not installed`                                 |
+| Symptom                                                                                          | Likely cause                                                                                                             | Fix                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deep link opens the app but nothing happens                                                      | Scheme added in config but **no native rebuild**                                                                         | `npx expo prebuild` / new development client; Metro reload is not enough                                                                                                                                               |
+| Deep link opens the app but nothing happens, and no **Preview mode** top bar appears             | `Userflow.init()` rejected, so there is no session to preview into                                                       | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken` or `serverEndpoint`) and re-open the link                                            |
+| Killed app opens from a pairing link with no banner, or Preview returns on the wrong step        | Pairing did not resume, or the install joined as a new device while the old presence was still on the topic              | Install `expo-secure-store` so a relaunch can resume. A cold start should show **Connecting to Builder…** immediately, then **Preview mode**, with the flow at step 1. `exitPreview()` or an expired token ends resume |
+| Deep link opens the app and the router shows **Unmatched Route** / "page could not be found"     | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<id>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme                                                                       |
+| "Can't select this element" right after pairing, or the app jumps to home when pairing           | Expo Router navigated on the pairing link                                                                                | Add `app/+native-intent.ts` exporting `redirectSystemPath` from `@userflow-tech/react-native/expo-router` (see [deep-linking.md](deep-linking.md#expo-router-hosts))                                                   |
+| Pairing deep link ignored (preview URL may still work)                                           | Scheme is `userflow-*` but the id after it is empty or has stray hyphens                                                 | Use the env's `scheme_id` from the dashboard exactly (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`), not the env UUID                                                                                                    |
+| Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks                                                                 | Pair again on the device you are watching, or clear the env's pairing session and re-QR                                                                                                                                |
+| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** top bar)                                                             | Confirm the top bar before hitting Preview; re-open the pairing QR on this install                                                                                                                                     |
+| Pairing never connects against a local stack                                                     | `pairingEndpoint` still pointing at production                                                                           | `Userflow.init({ pairingEndpoint: 'http://localhost:40401', serverEndpoint: '…' })`                                                                                                                                    |
+| QR / `https://…/pair/<jwt>` does nothing in the app                                              | SDK only parses the **scheme** form after the backend redirect                                                           | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl`                                                                                                                           |
+| Builder selector has no screenshot after Confirm                                                 | Missing / unlinked `react-native-view-shot`, or Expo SDK 54 pinned 4.x                                                   | Install `react-native-view-shot@^5.0.0` and **rebuild native**. Look for `[Userflow] Required peer react-native-view-shot is not installed`                                                                            |
 
 ## Expo
 
@@ -103,12 +132,42 @@ Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all buil
 | Duplicate React / RN instance crashes when linking local packages | Force singletons in Metro — monorepo `docs/metro.md`                              |
 | Preview / pairing scheme not registered                           | Add the `@userflow-tech/react-native` plugin with `schemeId`, then rebuild native |
 
+## Jest
+
+| Symptom                                                                                                                               | Likely cause                                                                                                                                                   | Fix                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Snapshots gain `nativeID="uf_…"`, `collapsable={false}`, `__ufid`, or `__ufManual` props, and keep changing after unrelated JSX edits | The Babel plugin runs under Jest, because `babel-jest` reads `babel.config.js`. Its ids depend on file path, component name, sibling order, and static labels. | Skip the plugin when `api.env('test')` is true. See the README section "Babel plugin and snapshot tests". |
+| `Caching has already been configured with .never or .forever()` after adding `api.env('test')`                                        | `babel.config.js` still calls `api.cache(true)` before `api.env`.                                                                                              | Remove `api.cache(true)`. `api.env` already caches per environment.                                       |
+| Component tests load the SDK after enabling the Babel plugin                                                                          | Full mode imports `@userflow-tech/react-native` into every stamped file.                                                                                       | Mock the SDK in the Jest setup file, or skip the plugin in tests.                                         |
+
 ## Still stuck?
 
 1. Confirm `await Userflow.init` → `await Userflow.identify` → `UserflowProvider`.
 2. Search logs for `[Userflow]` and the exact strings in the tables above.
-3. Verify the published flow’s start conditions use MANUAL + PRESENT/NOT_PRESENT
-   if they depend on an on-device element.
+3. Verify the published flow’s start conditions use a supported element state
+   (`PRESENT`, `NOT_PRESENT`, `CLICK`, `NOT_CLICK`) if they depend on an
+   on-device element.
 4. Confirm the anchor id in code matches the builder selector after stripping `#`.
 5. For builder Preview: confirm the **Preview mode** top bar is visible before you
    click Preview in the dashboard.
+
+## Isolated SDK errors (host app still running)
+
+The SDK contains overlay render errors and fire-and-forget `track` /
+`updateScreen` failures so they cannot crash the host app. The flow or event is
+dropped; the app keeps running. Isolated failures are logged with
+`console.warn` (not `console.error`, which React Native would report as a
+native crash).
+
+Look for:
+
+```text
+[Userflow] isolated error overlay …
+[Userflow] isolated error track …
+```
+
+Contract mistakes still throw (`Call Userflow.init() before identify()`,
+`Call Userflow.identify() before track()`, …). Native module crashes and errors
+in **your** children of `UserflowProvider` are not contained.
+
+Full contract: [isolation.md](isolation.md).

package/docs/webview-custom-banner-poc.md

@@ -0,0 +1,64 @@
+# WebView banner POC (React Native)
+
+Proof of concept for React Native banners that use **Evaluate JavaScript** on buttons—the same `window.userflow` bridge and (when the WebView path is used) web banner DOM + theme **custom.css** as userflow.js on web.
+
+## Enabling
+
+1. **Custom CSS (theme):** Publish custom CSS in the builder (**Edit custom CSS**). When the theme has a `cssVersion`, banners use the WebView renderer and load `custom.css` from the CDN (same URL as userflow.js iframes). Use `.userflow-custom-container-<name>` on container blocks and `.userflow-custom-button-<name>` as button appearance in the builder.
+2. **Evaluate JavaScript:** Use a button whose **only** action is **Evaluate JavaScript** if the script should auto-run when the WebView loads (once per banner session). Mixed-action buttons run eval on click only.
+3. `react-native-webview` ships as an SDK dependency; after install or upgrade, **rebuild** the native app (`pod install` on iOS). If Metro still cannot load it, add `react-native-webview` explicitly in the host app and rebuild again.
+
+For local SDK development without custom CSS or Evaluate JavaScript, use `setDebugForceWebViewBanner` from `bannerNeedsWebView.ts` (not exported on the public `Userflow` API).
+
+Web embeds are unchanged (native userflow.js banner).
+
+## Architecture
+
+- **Native shell:** `BannerHost` / `EmbedBannerPlaceholder` unchanged (overlay vs flow, safe area, margins, max width).
+- **Single WebView:** `BannerWebViewBar` renders the web DOM (`userflowjs-banner-*`, `userflowjs-bubble-button-*`) plus inlined frame CSS and a link to `https://cdn.{host}/themes/{themeId}/stylesheets/{cssVersion}/custom.css` when the theme has `cssVersion`.
+- **Actions:** Button clicks post to RN → `BannerSessionEngine.handleActions` → `EVAL_JS` uses the **same** WebView via `evalJsController` (overlay `EvalJsHost` is suppressed while the banner owns the page).
+- **Dismiss from JS:** `userflow.endFlow()` and `userflow.close()` end the **banner session** (same as the native X), not only the tour flow engine.
+
+## Manual test checklist (iOS + Android)
+
+- [ ] Standard banner (no Evaluate JavaScript): native `BannerBar`, unchanged layout.
+- [ ] WebView banner: theme custom CSS applies to buttons/content (use builder theme + custom classes on buttons).
+- [ ] Top (`BODY_FIRST`) and bottom (`BODY_LAST`) placement; overlay on/off.
+- [ ] Button **Evaluate JavaScript** runs (`userflow.track`, `userflow.updateUser`, etc.).
+- [ ] **Auto-run on show:** Evaluate JavaScript on an **eval-only** banner button (no other actions on that button) runs when the WebView loads. TinyTime fixture: `apps/tinytime/eval-js-samples/etoro-crypto-deposit-banner-rn.js`.
+- [ ] Dismiss (X) ends banner with user-closed reason.
+- [ ] Small phone, large phone, and tablet aspect ratios—watch for clipped or extra-tall bar (height comes from WebView content measurement).
+- [ ] Rotation: bar height updates after orientation change.
+
+## Findings
+
+### Feasibility
+
+- **Works in principle:** WebView can load CDN `custom.css` and reuse web class names; eval JS reuses the existing `wrapCode` / `window.userflow` bridge.
+- **Gaps vs web:** Rich content HTML export is a **subset** (paragraphs, headings, lists, quotes, code, links, attributes)—no images/video/button groups inside content. Button hidden/disabled conditions are not evaluated in the WebView. Fonts rely on theme `fontFamily` / custom CSS, not full web font loading.
+
+### Layout and screen-size risks
+
+- Height is driven by content measurement on `.userflowjs-banner-root` and `ResizeObserver` when available; there can be a one-frame jump before measure completes.
+- `overlay: false` push layout depends on measured WebView height—verify on long copy and multiple buttons wrapping.
+- Safe area is applied on the **native** host, not inside the WebView document (unlike some full-screen eval JS samples).
+
+### Single WebView / eval routing
+
+- While a WebView banner is mounted, `evalJsController.bannerOwnsWebView` prevents a second overlay WebView.
+- **Conflict:** A flow **Evaluate JavaScript** step running at the same time as a WebView banner would share the banner WebView—not supported in this POC.
+
+### Security / performance
+
+- Custom CSS is fetched from the CDN at runtime (network required on first paint).
+- One WebView per banner session with eval JS; memory cost is acceptable for typical use but not ideal for many simultaneous surfaces.
+
+### Follow-ups before production
+
+- Builder copy review; document unsupported banner capabilities (sticky scroll, element embed modes, condition-driven buttons).
+- Align with UMD-166 (banner component) and UMD-168 (banner eval extension).
+- Optional: ship compiled `bubble-frame` CSS from CDN instead of bundled subset.
+
+## Customer sample fixtures
+
+When validating against a specific customer banner, paste their theme **custom.css** and button **Evaluate JavaScript** into the builder test flow and attach the same snippets to the Jira ticket for regression reference.