@userflow-tech/react-native 0.2.0 → 0.3.0

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

@@ -72,28 +72,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
 
@@ -112,3 +114,24 @@ Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all buil
 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.

package/expo-plugin/withUserflow.d.ts

@@ -1,8 +1,9 @@
 import { type ConfigPlugin } from '@expo/config-plugins';
 export interface UserflowExpoPluginOptions {
     /**
-     * The environment's `scheme_id` from the Userflow dashboard (e.g.
-     * `userflow-257587`). Must be `userflow-` followed by digits.
+     * The environment's `scheme_id` from the Userflow dashboard: `userflow-`
+     * followed by an opaque id (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`).
+     * Copy it exactly and do not rely on its shape.
      *
      * `schemeId` is accepted as an alias for the same value (pairing naming).
      */

package/expo-plugin/withUserflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withUserflow.d.ts","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAiC9B,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA2ED,QAAA,MAAM,MAAM,gDAAmE,CAAC;AAEhF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"withUserflow.d.ts","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAsC9B,MAAM,WAAW,yBAAyB;IACxC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AA4ED,QAAA,MAAM,MAAM,gDAAmE,CAAC;AAEhF,eAAe,MAAM,CAAC"}

package/expo-plugin/withUserflow.js

@@ -5,8 +5,8 @@ const config_plugins_1 = require("@expo/config-plugins");
  * Expo config plugin shipped inside `@userflow-tech/react-native`.
  *
  * Registers the environment's `scheme_id` as a URL scheme. One scheme serves both
- * builder preview (`userflow-257587://?token=...`) and pairing
- * (`userflow-257587://?pairing_token=...`).
+ * builder preview (`userflow-v7twv2fw2ja2jaco7kesvowmem://?token=...`) and
+ * pairing (`userflow-v7twv2fw2ja2jaco7kesvowmem://?pairing_token=...`).
  *
  * Optional peers unlock extras: `@react-native-community/netinfo` enables
  * network-aware reconnect; without it the SDK falls back to heartbeat-based
@@ -17,7 +17,7 @@ const config_plugins_1 = require("@expo/config-plugins");
  *
  *   {
  *     "expo": {
- *       "plugins": [["@userflow-tech/react-native", { "schemeId": "userflow-257587" }]]
+ *       "plugins": [["@userflow-tech/react-native", { "schemeId": "userflow-v7twv2fw2ja2jaco7kesvowmem" }]]
  *     }
  *   }
  *
@@ -28,8 +28,13 @@ const PACKAGE_NAME = '@userflow-tech/react-native';
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const PACKAGE_VERSION = require('../package.json').version;
 const USERFLOW_SCHEME_PREFIX = 'userflow-';
-/** Environment scheme_id shape — must match pairing deep-link validation. */
-const USERFLOW_SCHEME = /^userflow-\d+$/;
+/**
+ * Environment scheme_id shape — must match pairing deep-link validation
+ * (`packages/react-native/src/pairing/deepLink.ts`). Everything after
+ * `userflow-` is an opaque id owned by the backend, so only check that it is
+ * one or more alphanumeric segments joined by single hyphens.
+ */
+const USERFLOW_SCHEME = /^userflow-[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function normalizeUrlScheme(urlScheme) {
     if (urlScheme == null)
         return null;
@@ -42,14 +47,15 @@ function normalizeUrlScheme(urlScheme) {
     if (!trimmed)
         return null;
     if (trimmed.includes('://') || trimmed.includes('/') || trimmed.includes(':')) {
-        throw new Error(`[${PACKAGE_NAME}] urlScheme must be a bare scheme (e.g. "userflow-257587"), got "${urlScheme}"`);
+        throw new Error(`[${PACKAGE_NAME}] urlScheme must be a bare scheme (e.g. "userflow-v7twv2fw2ja2jaco7kesvowmem"), got "${urlScheme}"`);
     }
     if (!trimmed.startsWith(USERFLOW_SCHEME_PREFIX)) {
         throw new Error(`[${PACKAGE_NAME}] urlScheme must start with "${USERFLOW_SCHEME_PREFIX}", got "${urlScheme}"`);
     }
     if (!USERFLOW_SCHEME.test(trimmed)) {
-        throw new Error(`[${PACKAGE_NAME}] urlScheme must be "${USERFLOW_SCHEME_PREFIX}" followed by digits ` +
-            `(e.g. "userflow-257587"), got "${urlScheme}"`);
+        throw new Error(`[${PACKAGE_NAME}] urlScheme must be your environment's scheme_id: ` +
+            `"${USERFLOW_SCHEME_PREFIX}" followed by letters and digits, optionally split by ` +
+            `single hyphens (e.g. "userflow-v7twv2fw2ja2jaco7kesvowmem"), got "${urlScheme}"`);
     }
     return trimmed;
 }

package/expo-plugin/withUserflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"withUserflow.js","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"withUserflow.js","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"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"}

package/lib/commonjs/anchors/AutoAnchorRegistry.js

@@ -148,6 +148,10 @@ class AutoAnchorRegistry {
   updateInstance(instanceId, patch) {
     const inst = this.instances.get(instanceId);
     if (!inst) return;
+    // Stamped hosts call this on every render; notifying for a no-op patch
+    // re-renders registry subscribers, which re-render the stamps.
+    const keys = Object.keys(patch);
+    if (keys.every(key => Object.is(inst[key], patch[key]))) return;
     const prevIds = {
       manualId: inst.manualId,
       userflowId: inst.userflowId,
@@ -315,6 +319,20 @@ class AutoAnchorRegistry {
     return byManual.length > 1 || byManual.some(i => i.ambiguous);
   }
 
+  /**
+   * Whether `inst` still has a look-alike inside `include`.
+   *
+   * The stored {@link AutoAnchorInstance.ambiguous} flag is registry-wide, so a
+   * copy on a covered screen keeps it set. Visibility can only clear that, never
+   * add ambiguity: an instance the registry considers unique stays unique.
+   */
+  isAmbiguousAmong(inst, include) {
+    if (!inst.ambiguous) return false;
+    const peers = list => list.filter(i => i === inst || include(i));
+    if (inst.manualId) return peers(this.getInstancesByManualId(inst.manualId)).length > 1;
+    return this.isTwinWithin(inst, peers(this.getInstancesByTemplatePath(inst.templatePath))) || this.isTwinWithin(inst, peers(this.getInstancesByRegistryKey(inst.registryKey)));
+  }
+
   /** Test helper — drop every instance and reset ids. */
   clear() {
     this.instances.clear();
@@ -359,6 +377,24 @@ class AutoAnchorRegistry {
     }
   }
 
+  /**
+   * True when `inst` cannot be told apart from another instance in `list`.
+   * An unlabelled group only: no content of its own, or a content signature a
+   * peer shares.
+   */
+  isTwinWithin(inst, list) {
+    const unlabelled = list.length > 1 && list.every(i => !i.manualId);
+    if (!unlabelled) return false;
+    const sig = contentSignature(inst);
+    if (!sig) return true;
+    let count = 0;
+    for (const peer of list) {
+      if (contentSignature(peer) === sig) count += 1;
+      if (count > 1) return true;
+    }
+    return false;
+  }
+
   /**
    * Instances sharing a template path are only twins while they look alike.
    * Four rows from one `field()` helper are indistinguishable at register time
@@ -368,18 +404,8 @@ class AutoAnchorRegistry {
    */
   recomputeAmbiguity(registryKey, templatePath, manualId) {
     const mark = list => {
-      const unlabelled = list.length > 1 && list.every(i => !i.manualId);
-      const shared = new Map();
-      if (unlabelled) {
-        for (const i of list) {
-          const sig = contentSignature(i);
-          if (sig) shared.set(sig, (shared.get(sig) ?? 0) + 1);
-        }
-      }
       for (const i of list) {
-        const sig = unlabelled ? contentSignature(i) : undefined;
-        const twins = unlabelled && (!sig || (shared.get(sig) ?? 0) > 1);
-        i.ambiguous = twins || (i.manualId ? this.getInstancesByManualId(i.manualId).length > 1 : false);
+        i.ambiguous = this.isTwinWithin(i, list) || (i.manualId ? this.getInstancesByManualId(i.manualId).length > 1 : false);
       }
     };
     mark(this.getInstancesByRegistryKey(registryKey));