@userflow-tech/react-native 0.3.0 → 0.4.0

package/docs/anchoring.md

@@ -6,9 +6,9 @@ host app.
 **This matters more than tooltip placement alone.** The same resolver powers:
 
 1. Tooltip target resolution (`TooltipSurface`)
-2. `ELEMENT` client conditions with `PRESENT` / `NOT_PRESENT` — so a missing or
-   misspelled anchor can mean a gated **flow never starts at all**, not merely a
-   misplaced tooltip
+2. `ELEMENT` client conditions (`PRESENT` / `NOT_PRESENT` / `CLICK` /
+   `NOT_CLICK`) — so a missing or misspelled anchor can mean a gated **flow
+   never starts at all**, not merely a misplaced tooltip
 
 ## Preferred: tag with `testID`
 
@@ -23,15 +23,16 @@ return trimmed.startsWith('#') ? trimmed.slice(1) : trimmed;
 Then looks up a measurable host, in order:
 
 1. **`useUserflowAnchor` registry** (explicit override)
-2. Fiber-tree scan for a matching **`testID`**
-3. Else matching **`nativeID`**
-4. Else matching **`accessibilityLabel`**
+2. Fiber-tree scan for a matching **`userflowId`**
+3. Else matching **`testID`**
+4. Else matching **`nativeID`**
+5. Else matching **`accessibilityLabel`**
 
-| Dashboard `selector.css` | Resolved id        | Host code                               |
-| ------------------------ | ------------------ | --------------------------------------- |
-| `#invite-teammates`      | `invite-teammates` | `<Pressable testID="invite-teammates">` |
-| `invite-teammates`       | `invite-teammates` | `<Pressable testID="invite-teammates">` |
-| `  #x  `                 | `x`                | `<View testID="x">`                     |
+| Dashboard `selector.css` | Resolved id        | Host code                                   |
+| ------------------------ | ------------------ | ------------------------------------------- |
+| `#invite-teammates`      | `invite-teammates` | `<Pressable userflowId="invite-teammates">` |
+| `invite-teammates`       | `invite-teammates` | `<Pressable testID="invite-teammates">`     |
+| `  #x  `                 | `x`                | `<View nativeID="x">`                       |
 
 Only a plain id (with optional leading `#`) is supported. Compound CSS
 (`.class`, `[attr]`, `div > button`) is **not** parsed — the trimmed string
@@ -49,7 +50,10 @@ function InviteButton() {
 }
 ```
 
-No SDK import is required on the target view. Prefer **MANUAL** selectors in the
+No SDK import is required on the target view. `userflowId` is the strongest
+fiber tier, then `testID`, then `nativeID`. React Native's own prop types do
+not include `userflowId` yet, so a TypeScript host may need a module
+augmentation until the SDK ships one. Prefer **MANUAL** selectors in the
 builder for mobile when you control the host code.
 
 ### AUTO (codeless) selectors
@@ -58,9 +62,9 @@ builder for mobile when you control the host code.
 instead of a CSS id. Play-time resolution (`resolveAutoAnchorHost`):
 
 1. **Exact-id fast path** — if the fingerprint has a real `userflowId`, `testID`,
-   or non-`uf_` `nativeID`, reuse the MANUAL resolver (`resolveAnchorHost`).
-   This works even under Babel `stampOnly: true` (no auto-registry
-   population).
+   or non-`uf_` `nativeID`, reuse the MANUAL resolver (`resolveAnchorHost` for
+   tooltips, `resolveElementTargets` for conditions). This works even under
+   Babel `stampOnly: true` (no auto-registry population).
    A zero-size measure invalidates that id in the fiber cache, same as MANUAL.
 2. **Scored match** — rank live `autoAnchorRegistry` instances on **visible**
    navigator screens (covered stack screens are skipped, same rule as the fiber
@@ -69,11 +73,13 @@ instead of a CSS id. Play-time resolution (`resolveAutoAnchorHost`):
    scroll the target into view. Babel full mode (the default) is what
    registers those instances.
 
-Fail-closed mapping for ELEMENT conditions:
+Fail-closed mapping for ELEMENT conditions. An exact id that matches more than
+one host counts as found (any of them), which is web parity and differs from
+tooltip resolution. A scored match that is not unique stays unknown.
 
 | Resolution               | `PRESENT` / `NOT_PRESENT`                    |
 | ------------------------ | -------------------------------------------- |
-| `found`                  | true / false                                 |
+| `found`                  | true / false, after a non-zero measure       |
 | `absent`                 | false / true                                 |
 | `ambiguous` or `unknown` | unknown (`null`) — gated flow does not start |
 
@@ -156,20 +162,24 @@ reading nothing.
 
 ### Prop priority
 
-When resolving via the fiber scan, the highest matching tier wins so a `testID`
-hit is never made ambiguous by an unrelated `accessibilityLabel` elsewhere on
-the screen:
+When resolving via the fiber scan, the highest matching tier wins so a
+`userflowId` or `testID` hit is never made ambiguous by an unrelated
+`accessibilityLabel` elsewhere on the screen:
 
-1. `testID`
-2. `nativeID`
-3. `accessibilityLabel`
+1. `userflowId`
+2. `testID`
+3. `nativeID`
+4. `accessibilityLabel`
 
-### Duplicate ids fail closed
+### Duplicate ids
 
-Multiple mounts of the same id are allowed, but `TooltipSurface` treats an
-**ambiguous** id as **missing** — it never picks one arbitrarily. Nested
-duplicates on a single root-to-leaf chain (e.g. `Pressable` forwarding `testID`
-to its inner `View`) collapse to one host. Prefer unique ids per screen.
+Multiple mounts of the same id are allowed. Nested duplicates on a single
+root-to-leaf chain (e.g. `Pressable` forwarding `testID` to its inner `View`)
+collapse to one host.
+
+`TooltipSurface` treats a remaining **ambiguous** id as **missing** — it never
+picks one arbitrarily. ELEMENT `PRESENT` / `CLICK` conditions follow the web
+SDK instead: any of the matches counts. Prefer unique ids per screen anyway.
 
 ### Only visible screens are scanned
 
@@ -328,8 +338,10 @@ rect** via a pass-through bridge around app content (`TargetPressBridge` in
 - Empty `actions`, blocked targets, missing/fallback UI, and scrolls that exceed
   the slop do not fire.
 
-ELEMENT condition `CLICK` / `MOUSEDOWN` gating is separate and still unsupported
-— see [client-conditions.md](client-conditions.md) / [troubleshooting.md](troubleshooting.md).
+ELEMENT `CLICK` / `NOT_CLICK` auto-start conditions use the same bridge
+(`elementTapMonitor`) and do not steal the press either. `MOUSEDOWN` and
+`DISABLED` conditions are still unsupported — see
+[client-conditions.md](client-conditions.md) / [troubleshooting.md](troubleshooting.md).
 
 ## Missing-target behavior
 
@@ -352,18 +364,22 @@ missing.
 
 ## ELEMENT client conditions
 
-For `PRESENT` / `NOT_PRESENT` on a MANUAL selector, the evaluator resolves the
-same id through `resolveAnchorHost` (registry + fiber scan). A found host means
-the anchor is uniquely resolvable on a **visible** navigator screen — covered
-stack screens count as absent. Pixel visibility inside a scroll view is not
-checked. Ambiguous ids report unknown (`null`) so gated flows stay blocked.
-
-`AUTO` selectors go through `resolveAutoAnchorHost`. A confident hit or a
-genuine contradiction (`absent`) produces a boolean; weak evidence (`unknown`)
-and ambiguous explicit ids stay unknown so a gated flow never starts just
-because the auto-anchor registry is empty. Hosts on a covered navigator screen
-count as absent, matching MANUAL. Unsupported states (`CLICK`, `DISABLED`, …)
-stay unknown — see [troubleshooting.md](troubleshooting.md).
+`PRESENT` / `NOT_PRESENT` / `CLICK` / `NOT_CLICK` resolve through
+`resolveElementTargets` (registry + fiber scan, including `userflowId`).
+Duplicate ids count as a hit. Covered stack screens count as absent. A measured
+0×0 host counts as absent; opacity and scroll clipping are not checked.
+
+`CLICK` reports false until the user taps the host or a descendant, then stays
+true until the server untracks the condition. `NOT_CLICK` starts true and
+latches false on that tap. A disabled host does not count.
+
+`AUTO` selectors use the same exact-id lookup when the fingerprint carries a
+`userflowId`, `testID`, or real `nativeID`, and otherwise go through
+`resolveAutoAnchorHost`. A confident hit or a genuine contradiction (`absent`)
+produces a boolean; weak evidence (`unknown`) and ambiguous scored matches stay
+unknown so a gated flow never starts just because the auto-anchor registry is
+empty. `DISABLED` and `MOUSEDOWN` stay unknown — see
+[troubleshooting.md](troubleshooting.md).
 
 ## How the fiber scan works (brief)
 

package/docs/troubleshooting.md

@@ -3,25 +3,57 @@
 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`.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ERESOLVE` while installing `@userflow-tech/react-native`                                                                                                                                                                                                                                                                                                                                  | The app already has a version outside a peer range: view-shot 4.0.3 (what unpinned `npx expo install` installs on Expo SDK 54), NetInfo 9.x, safe-area-context 3.x, WebView 13.6.x or 14.x, or React Native older than 0.76. | Move that package into the range in the package README. For view-shot, npm prints `Found: react-native-view-shot@4.0.3` and `peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native`. Install the SDK and `react-native-view-shot@^5.0.0` in one command, then add `"react-native-view-shot"` to `expo.install.exclude` on Expo SDK 54. Do not retry with `--force` or `--legacy-peer-deps`; that leaves 4.0.3 installed. Raise React Native to 0.76 or later when that is the conflict. |
+| Yarn 1 or `npm install --legacy-peer-deps` succeeded, but `react-native-webview` or `react-native-view-shot` is not installed                                                                                                                                                                                                                                                              | Those installs do not fetch peers. WebView and view-shot are required peers, not dependencies.                                                                                                                               | Install `react-native-webview` and `react-native-view-shot@^5.0.0` in the app, then rebuild native.                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Banners, flow cards, or Builder bars draw under the status bar, notch, or home indicator. Development logs `[Userflow] react-native-safe-area-context is not installed, so banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.`                       | `react-native-safe-area-context` is not installed, so insets are zero.                                                                                                                                                       | Install the package and wrap the tree in `<SafeAreaProvider>`.                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `Uncaught Error` / `NativeModule.RNCNetInfo is null` as soon as `Userflow.init` runs                                                                                                                                                                                                                                                                                                       | On SDK 0.3.1 and earlier, NetInfo's JavaScript was loaded while its native module was not in the binary. Debug builds show a red screen. Dismissing it leaves the app running; a release build can crash.                    | Link `@react-native-community/netinfo` and rebuild, or remove it. Current versions skip NetInfo when `RNCNetInfo` is not registered and log one dev warning instead.                                                                                                                                                                                                                                                                                                                                    |
+| `[@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-safe-area-context is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Without the native module, banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it in the app (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | Expo SDK older than 54, and safe-area-context is not a direct dependency, so its native module is not autolinked.                                                                                                            | `npx expo install react-native-safe-area-context` and wrap the tree in `<SafeAreaProvider>`.                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `[Userflow] react-native-view-shot@4.0.3 is older than 5.0.0, so Builder element selection may not get a screenshot.` The installed version is filled in. The warning also says not to retry with `--force` or `--legacy-peer-deps`.                                                                                                                                                       | view-shot 4.x is installed, usually because an `ERESOLVE` was retried with `--force` or `--legacy-peer-deps`, or Expo SDK 54's default 4.0.3 was left in place.                                                              | Install `react-native-view-shot@^5.0.0` in the same command as the SDK and rebuild. On Expo SDK 54, add `"react-native-view-shot"` to `expo.install.exclude`.                                                                                                                                                                                                                                                                                                                                           |
+| `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. A missing safe-area package is a separate warning, because flows still run.                                                    | Install the named packages and rebuild. The footer is `See node_modules/@userflow-tech/react-native/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 +69,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
 
@@ -105,12 +138,21 @@ 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.

package/expo-plugin/hostDependencyWarnings.d.ts

@@ -0,0 +1,21 @@
+/** Printed from the iOS and Android prebuild steps when `schemeId` is omitted. */
+export declare const MISSING_SCHEME_WARNING = "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.";
+export interface HostDependencyWarning {
+    property: string;
+    message: string;
+}
+/**
+ * Prebuild checks that do not change the native config.
+ *
+ * `react-native-view-shot` must be at least 5. Expo SDK 54's unpinned install
+ * resolves 4.0.3. Expo SDK 53 and older only autolink native modules listed in
+ * the app's own package.json, so AsyncStorage, WebView, and safe-area-context
+ * have to be direct dependencies there. Expo SDK 54 and later autolink
+ * safe-area-context when Expo Router or React Navigation brought it in, so
+ * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
+ * the package itself cannot be loaded.
+ */
+export declare function hostDependencyWarnings(projectRoot: string | undefined, sdkVersion: string | null | undefined): HostDependencyWarning[];
+/** Called from inside the iOS and Android config-plugin steps, so it runs at prebuild. */
+export declare function applyPrebuildWarnings(config: object, platform: 'ios' | 'android', schemeId: string | null): void;
+//# sourceMappingURL=hostDependencyWarnings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hostDependencyWarnings.d.ts","sourceRoot":"","sources":["../plugin/hostDependencyWarnings.ts"],"names":[],"mappings":"AAKA,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,wOACoM,CAAC;AAExO,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,qBAAqB,EAAE,CA+CzB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,KAAK,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI,CAaN"}

package/expo-plugin/hostDependencyWarnings.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MISSING_SCHEME_WARNING = void 0;
+exports.hostDependencyWarnings = hostDependencyWarnings;
+exports.applyPrebuildWarnings = applyPrebuildWarnings;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_plugins_1 = require("@expo/config-plugins");
+/** Printed from the iOS and Android prebuild steps when `schemeId` is omitted. */
+exports.MISSING_SCHEME_WARNING = '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.';
+const VIEW_SHOT = 'react-native-view-shot';
+const SAFE_AREA = 'react-native-safe-area-context';
+const TRANSITIVE_NATIVE_MODULES = [
+    '@react-native-async-storage/async-storage',
+    'react-native-webview',
+];
+/**
+ * Prebuild checks that do not change the native config.
+ *
+ * `react-native-view-shot` must be at least 5. Expo SDK 54's unpinned install
+ * resolves 4.0.3. Expo SDK 53 and older only autolink native modules listed in
+ * the app's own package.json, so AsyncStorage, WebView, and safe-area-context
+ * have to be direct dependencies there. Expo SDK 54 and later autolink
+ * safe-area-context when Expo Router or React Navigation brought it in, so
+ * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
+ * the package itself cannot be loaded.
+ */
+function hostDependencyWarnings(projectRoot, sdkVersion) {
+    if (!projectRoot) {
+        return [];
+    }
+    const dependencies = readDirectDependencies(projectRoot);
+    if (!dependencies) {
+        return [];
+    }
+    const warnings = [];
+    const viewShot = dependencies[VIEW_SHOT];
+    if (!viewShot) {
+        warnings.push({
+            property: VIEW_SHOT,
+            message: '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.',
+        });
+    }
+    else {
+        const major = leadingMajor(viewShot);
+        if (major != null && major < 5) {
+            warnings.push({
+                property: VIEW_SHOT,
+                message: `react-native-view-shot@${viewShot} 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.`,
+            });
+        }
+    }
+    const sdkMajor = leadingMajor(sdkVersion ?? '');
+    if (sdkMajor != null && sdkMajor < 54) {
+        if (!dependencies[SAFE_AREA]) {
+            warnings.push({
+                property: SAFE_AREA,
+                message: `react-native-safe-area-context is not listed in the app package.json. Expo SDK ${sdkMajor} does not autolink native modules that the app only receives indirectly. Without the native module, banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it in the app (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.`,
+            });
+        }
+        for (const name of TRANSITIVE_NATIVE_MODULES) {
+            if (!dependencies[name]) {
+                warnings.push({
+                    property: name,
+                    message: `${name} is not listed in the app package.json. Expo SDK ${sdkMajor} does not autolink native modules that the app only receives indirectly. Install it in the app (npx expo install ${name}) and rebuild.`,
+                });
+            }
+        }
+    }
+    return warnings;
+}
+/** Called from inside the iOS and Android config-plugin steps, so it runs at prebuild. */
+function applyPrebuildWarnings(config, platform, schemeId) {
+    const source = config;
+    const add = platform === 'ios' ? config_plugins_1.WarningAggregator.addWarningIOS : config_plugins_1.WarningAggregator.addWarningAndroid;
+    if (!schemeId) {
+        add('schemeId', exports.MISSING_SCHEME_WARNING);
+    }
+    for (const warning of hostDependencyWarnings(source._internal?.projectRoot, source.sdkVersion)) {
+        add(warning.property, warning.message);
+    }
+}
+function readDirectDependencies(projectRoot) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.join)(projectRoot, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        return { ...pkg.dependencies, ...pkg.devDependencies };
+    }
+    catch {
+        return null;
+    }
+}
+/** First integer in a version or range (`^5.0.0` → 5, `54.0.0` → 54). */
+function leadingMajor(specifier) {
+    const match = specifier.match(/\d+/);
+    if (!match) {
+        return null;
+    }
+    return Number(match[0]);
+}
+//# sourceMappingURL=hostDependencyWarnings.js.map

package/expo-plugin/hostDependencyWarnings.js.map

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

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;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"}
+{"version":3,"file":"withUserflow.d.ts","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AA2C9B,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;AA2FD,QAAA,MAAM,MAAM,gDAAmE,CAAC;AAEhF,eAAe,MAAM,CAAC"}

package/expo-plugin/withUserflow.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const config_plugins_1 = require("@expo/config-plugins");
+const hostDependencyWarnings_1 = require("./hostDependencyWarnings");
 /**
  * Expo config plugin shipped inside `@userflow-tech/react-native`.
  *
@@ -35,6 +36,8 @@ const USERFLOW_SCHEME_PREFIX = 'userflow-';
  * one or more alphanumeric segments joined by single hyphens.
  */
 const USERFLOW_SCHEME = /^userflow-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Environment ids are UUIDs. The plugin needs `scheme_id`, which is not that UUID. */
+const ENVIRONMENT_UUID = /^(?:userflow-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 function normalizeUrlScheme(urlScheme) {
     if (urlScheme == null)
         return null;
@@ -46,6 +49,9 @@ function normalizeUrlScheme(urlScheme) {
         .replace(/:$/, '');
     if (!trimmed)
         return null;
+    if (ENVIRONMENT_UUID.test(trimmed)) {
+        throw new Error(`[${PACKAGE_NAME}] schemeId "${trimmed}" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.`);
+    }
     if (trimmed.includes('://') || trimmed.includes('/') || trimmed.includes(':')) {
         throw new Error(`[${PACKAGE_NAME}] urlScheme must be a bare scheme (e.g. "userflow-v7twv2fw2ja2jaco7kesvowmem"), got "${urlScheme}"`);
     }
@@ -61,6 +67,7 @@ function normalizeUrlScheme(urlScheme) {
 }
 const withUserflowUrlSchemeIos = (config, urlScheme) => {
     return (0, config_plugins_1.withInfoPlist)(config, (config) => {
+        (0, hostDependencyWarnings_1.applyPrebuildWarnings)(config, 'ios', urlScheme);
         if (!config_plugins_1.IOSConfig.Scheme.hasScheme(urlScheme, config.modResults)) {
             config.modResults = config_plugins_1.IOSConfig.Scheme.appendScheme(urlScheme, config.modResults);
         }
@@ -69,6 +76,7 @@ const withUserflowUrlSchemeIos = (config, urlScheme) => {
 };
 const withUserflowUrlSchemeAndroid = (config, urlScheme) => {
     return (0, config_plugins_1.withAndroidManifest)(config, (config) => {
+        (0, hostDependencyWarnings_1.applyPrebuildWarnings)(config, 'android', urlScheme);
         const mainActivity = config_plugins_1.AndroidConfig.Manifest.getMainActivityOrThrow(config.modResults);
         const intentFilters = mainActivity['intent-filter'] ?? [];
         const alreadyRegistered = intentFilters.some((filter) => {
@@ -92,6 +100,14 @@ const withUserflowUrlSchemeAndroid = (config, urlScheme) => {
 const withUserflow = (config, options = {}) => {
     const urlScheme = normalizeUrlScheme(options?.urlScheme ?? options?.schemeId);
     if (!urlScheme) {
+        config = (0, config_plugins_1.withInfoPlist)(config, (mod) => {
+            (0, hostDependencyWarnings_1.applyPrebuildWarnings)(mod, 'ios', null);
+            return mod;
+        });
+        config = (0, config_plugins_1.withAndroidManifest)(config, (mod) => {
+            (0, hostDependencyWarnings_1.applyPrebuildWarnings)(mod, 'android', null);
+            return mod;
+        });
         return config;
     }
     config = withUserflowUrlSchemeIos(config, urlScheme);

package/expo-plugin/withUserflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"withUserflow.js","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":";;AAAA,yDAO8B;AAE9B;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,YAAY,GAAG,6BAA6B,CAAC;AACnD,uFAAuF;AACvF,8DAA8D;AAC9D,MAAM,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,OAAiB,CAAC;AACrE,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAC3C;;;;;GAKG;AACH,MAAM,eAAe,GAAG,qCAAqC,CAAC;AAiB9D,SAAS,kBAAkB,CAAC,SAA6B;IACvD,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,MAAM,OAAO,GAAG,SAAS;SACtB,IAAI,EAAE;SACN,WAAW,EAAE;SACb,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC;SACxB,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;SACnB,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACrB,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,wFAAwF,SAAS,GAAG,CACrH,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,sBAAsB,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,gCAAgC,sBAAsB,WAAW,SAAS,GAAG,CAC9F,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,IAAI,YAAY,oDAAoD;YAClE,IAAI,sBAAsB,wDAAwD;YAClF,qEAAqE,SAAS,GAAG,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,wBAAwB,GAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE;IAC3E,OAAO,IAAA,8BAAa,EAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACtC,IAAI,CAAC,0BAAS,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9D,MAAM,CAAC,UAAU,GAAG,0BAAS,CAAC,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,4BAA4B,GAAyB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE;IAC/E,OAAO,IAAA,oCAAmB,EAAC,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QAC5C,MAAM,YAAY,GAAG,8BAAa,CAAC,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACtF,MAAM,aAAa,GAAG,YAAY,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;QAC1D,MAAM,iBAAiB,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACtD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;YAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,gBAAgB,CAAC,KAAK,SAAS,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,iBAAiB,EAAE,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC;gBACjB,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,4BAA4B,EAAE,EAAE,CAAC;gBACjE,QAAQ,EAAE;oBACR,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE,EAAE;oBAC5D,EAAE,CAAC,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE,EAAE;iBAC/D;gBACD,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,gBAAgB,EAAE,SAAS,EAAE,EAAE,CAAC;aAC/C,CAAC,CAAC;YACH,YAAY,CAAC,eAAe,CAAC,GAAG,aAAa,CAAC;QAChD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,YAAY,GAAmD,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,EAAE;IAC5F,MAAM,SAAS,GAAG,kBAAkB,CAAC,OAAO,EAAE,SAAS,IAAI,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC9E,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,GAAG,wBAAwB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrD,MAAM,GAAG,4BAA4B,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACzD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC;AAEF,MAAM,MAAM,GAAG,IAAA,oCAAmB,EAAC,YAAY,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC;AAEhF,kBAAe,MAAM,CAAC;AACtB,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC;AACxB,MAAM,CAAC,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC"}
+{"version":3,"file":"withUserflow.js","sourceRoot":"","sources":["../plugin/withUserflow.ts"],"names":[],"mappings":"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"}