@userflow-tech/react-native 0.1.0

package/docs/deep-linking.md

@@ -0,0 +1,271 @@
+# Deep linking (builder preview & pairing)
+
+The React Native SDK can open a draft flow when the host app receives a Userflow
+preview deep link (typically from a QR code in the builder), and can keep a
+**Builder pairing** websocket session open so repeated Previews land on the same
+device without rescanning.
+
+Session auth is unchanged: `clientToken` + `identify` / `identifyAnonymous`. The
+deep link only carries a short-lived preview or pairing credential — it does not
+pick the environment.
+
+## URL formats
+
+### One-shot preview
+
+```text
+{schemeId}://?token={startFlowToken}
+```
+
+Example:
+
+```text
+userflow-257587://?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.
+- `{startFlowToken}` is a short-lived token minted by the builder
+  (`prepareDraftFlow`).
+
+The SDK matches inbound URLs by **scheme prefix** (`userflow-`) and a root query
+(`?token=…`). There is no `urlScheme` option on `Userflow.init()`. Register your
+`scheme_id` at build time so the OS routes the builder QR into your app. A root
+URL carrying `pairing_token` instead of `token` is treated as pairing, not
+preview.
+
+### Builder pairing
+
+```text
+{schemeId}://?pairing_token={pairingJwt}
+```
+
+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.
+
+## Expo Router hosts
+
+No extra host files are required for Builder pairing or preview.
+
+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.
+
+Bare React Native / React Navigation apps need nothing beyond scheme
+registration either.
+
+## 1. Register the scheme at build time
+
+### Expo
+
+If you are using `app.config.js`:
+
+```js
+// app.config.js
+module.exports = {
+  expo: {
+    plugins: [['@userflow-tech/expo', { schemeId: 'userflow-257587' }]],
+  },
+};
+```
+
+If you are using `app.json`:
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [["@userflow-tech/expo", { "schemeId": "userflow-257587" }]]
+  }
+}
+```
+
+Then **rebuild native projects** (`npx expo prebuild` and a new development
+client, or `npx expo run:ios` / `run:android`). A Metro reload alone does **not**
+register the URL scheme. Expo Go is not supported.
+
+### Bare React Native
+
+**iOS** — add a URL type in `Info.plist`:
+
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>userflow-257587</string>
+    </array>
+  </dict>
+</array>
+```
+
+**Android** — add an intent filter on your main activity in `AndroidManifest.xml`:
+
+```xml
+<intent-filter>
+  <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" />
+</intent-filter>
+```
+
+Rebuild the native app after changing these files.
+
+## 2. Initialize the SDK
+
+```ts
+await Userflow.init({
+  clientToken: 'ct_...',
+  // Defaults to production. Override for staging / local stacks:
+  // serverEndpoint: 'http://localhost:40401',
+  // pairingEndpoint: 'http://localhost:40401',
+});
+await Userflow.identify(userId); // or identifyAnonymous()
+```
+
+Wrap the tree in `UserflowProvider`. It mounts a **Preview mode** banner while
+a pairing session is active — that banner is the success signal that this
+device is the one the builder will preview into.
+
+`Userflow.init()` attaches the inbound-URL listeners (React Native `Linking`)
+**before** it validates credentials, so a link that arrives while init is still
+in flight is held rather than dropped, then applied once init resolves. If a
+preview link arrives before identify, the token is buffered and sent as
+`StartFlowWithToken` once a user is identified. Pairing websocket paths are
+available in all builds (including release).
+
+### When `init()` fails
+
+Pairing needs a live end-user session, so a failed `init()` means a scanned QR
+code cannot connect. This is worth calling out because the failure is easy to
+misread: the URL scheme is registered in the **native** project at build time,
+so the OS still launches your app from the QR code — it just arrives in an app
+with no session to preview into.
+
+The SDK does not fail silently here. It logs an actionable reason:
+
+```text
+[Userflow] Builder pairing link received, but Userflow.init() failed so pairing
+cannot start: invalid_client_token: … Fix the init error — most often an invalid
+clientToken or an unreachable serverEndpoint — then re-open the pairing link.
+```
+
+and `UserflowProvider` renders a **Preview unavailable** banner carrying the
+same reason. If you see the app open with no banner at all, check that your
+`init()` call is actually resolving — host apps commonly swallow it:
+
+```ts
+// Don't hide the failure that explains why pairing never starts.
+Userflow.init({ clientToken: 'ct_...' }).catch((error) => {
+  console.warn('[app] Userflow init failed', 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.
+
+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** banner 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-*`
+scheme and so cannot be judged on scheme shape. A foreign scheme is only claimed
+when the URL is the root form with a `pairing_token` parameter. Pairing tokens
+are redacted from anything the SDK logs.
+
+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 and
+shown in the banner.
+
+Optional: install `expo-secure-store` so the pairing JWT can persist in
+Keychain/Keystore for the duration of the session
+(`npx expo install expo-secure-store`).
+
+### Host apps that already own Linking
+
+```ts
+import { Linking } from 'react-native';
+import { Userflow } from '@userflow-tech/react-native';
+
+Linking.addEventListener('url', async ({ url }) => {
+  // Preview tokens
+  if (await Userflow.didHandleURL(url)) return;
+  // Builder pairing
+  if (await Userflow.handlePairingUrl(url)) return;
+  // handle your own deep links
+});
+```
+
+`didHandleURL` returns `true` only for Userflow preview URLs.
+`handlePairingUrl` returns `true` only for pairing URLs. Both are safe alongside
+the SDK auto-listener.
+
+`handlePairingUrl` returns `true` as soon as it recognises a pairing link — the
+URL belongs to Userflow, so stop routing it — even when connecting is deferred
+until `init()` resolves. It returns `false` for links that are not Userflow's,
+so your own routing still runs. To classify a URL without consuming it, use
+`inspectPairingDeepLink(url)`, which reports why a URL was rejected
+(`not-userflow`, `foreign-scheme`, `bad-scheme-shape`, `unparseable`,
+`not-pair-path`, `missing-token`). `isPairingAttempt(reason)` narrows that to the
+rejections worth reporting — the ones where the URL was a recognisable pairing
+attempt that could not be used.
+
+Call `Userflow.exitPreview()` (or the banner's Exit control) to disconnect the
+pairing websocket.
+
+## 3. Verify
+
+```sh
+# iOS
+npx uri-scheme open "userflow-257587://?token=TEST" --ios
+
+# Android
+npx uri-scheme open "userflow-257587://?token=TEST" --android
+```
+
+Use a real token from the builder when testing end-to-end. For the full
+pair-then-preview loop:
+
+1. Open Preview in the builder → **Pair a device** → scan/open the QR.
+2. Confirm the app shows the **Preview mode** banner.
+3. Hit **Preview** in the builder — the draft flow should appear on that device.
+
+The builder offers two preview modes. Previewing directly starts the draft flow
+immediately, skipping its start conditions. Previewing **when auto start
+conditions are triggered** instead leaves the server waiting for the flow's
+conditions to match, so nothing appears until they do — the banner reads
+**Waiting for auto-start condition to trigger…** meanwhile. A flow that never
+shows up in that mode points at the condition, not at pairing.
+
+## Local / staging endpoints
+
+Defaults target production (`https://e.userflow.com` for the end-user socket;
+pairing defaults to the US-pinned production host). When pointing at a local or
+staging stack, set both:
+
+```ts
+await Userflow.init({
+  clientToken: 'ct_...',
+  serverEndpoint: 'http://localhost:40401',
+  pairingEndpoint: 'http://localhost:40401',
+});
+```
+
+See [troubleshooting.md](troubleshooting.md#builder-preview--pairing) for common
+pairing failures.

package/docs/identity-verification.md

@@ -0,0 +1,95 @@
+# Identity verification
+
+How to compute the `signature` option for `Userflow.identify` and
+`Userflow.group`.
+
+The React Native SDK mirrors the web SDK: the signature is an **HMAC-SHA256 of
+the external id**, computed on **your backend** with the environment’s **secret
+key**. Never embed the secret key in the mobile app.
+
+## Keys
+
+| Key          | Prefix    | Where it goes                               |
+| ------------ | --------- | ------------------------------------------- |
+| Client token | `ct_...`  | `Userflow.init({ clientToken })` in the app |
+| Secret key   | `esk_...` | Your backend only (HMAC signing)            |
+
+Find both under **Userflow dashboard → Settings → Environments**.
+
+## Algorithm
+
+The Userflow backend verifies:
+
+```text
+HMAC-SHA256(secret_key, userId_or_groupId) → lowercase hex
+```
+
+Equivalent Node.js:
+
+```javascript
+const crypto = require('crypto');
+
+function signExternalId(id, secretKey) {
+  return crypto.createHmac('sha256', secretKey).update(String(id)).digest('hex');
+}
+
+// Example Express handler — never call this from the mobile app:
+app.get('/userflow/signature', requireAuth, (req, res) => {
+  const userId = req.user.id; // same string you will pass to Userflow.identify
+  const signature = signExternalId(userId, process.env.USERFLOW_SECRET_KEY);
+  res.json({ userId, signature });
+});
+```
+
+Uppercase hex is accepted by the server (it lowercases before compare), but
+prefer lowercase.
+
+## App usage
+
+```ts
+import { Userflow } from '@userflow-tech/react-native';
+
+await Userflow.init({ clientToken: 'ct_...' });
+
+const { signature } = await yourApi.fetchUserflowSignature();
+await Userflow.identify('user-123', { name: 'Ada' }, { signature });
+```
+
+For groups:
+
+```ts
+await Userflow.group(
+  'org-9',
+  { name: 'Acme' },
+  {
+    signature: groupSignature, // HMAC of the group id
+    membership: { role: 'admin' },
+  },
+);
+```
+
+## When is it required?
+
+- **Client type:** `signature` is always optional.
+- **Server:** if the environment has identity verification enabled
+  (`signature_required`), joins without a signature fail with
+  `user_signature_required`, and wrong signatures fail with
+  `incorrect_user_signature` (same pattern for groups).
+
+Anonymous credential validation during `init()` can succeed even when
+signatures are required for real users — identity verification is enforced on
+the identified end-user channel join, not on the anonymous probe.
+
+## Common mistakes
+
+| Mistake                                           | Result                            |
+| ------------------------------------------------- | --------------------------------- |
+| Signing with the client token (`ct_...`)          | `incorrect_user_signature`        |
+| Signing a different string than the `identify` id | `incorrect_user_signature`        |
+| Computing HMAC in the app / shipping `esk_...`    | Security incident; rotate the key |
+| Omitting signature when the env requires it       | `user_signature_required`         |
+
+## See also
+
+- [troubleshooting.md](troubleshooting.md) — exact error strings
+- Web docs: https://userflow.com/docs/dev/identity-verification

package/docs/theme-mapping.md

@@ -0,0 +1,101 @@
+# Theme mapping (web → React Native)
+
+Phase 3 maps Userflow web theme tokens onto React Native styles used by flow chrome.
+This is an interim visual baseline aligned with the mobile tooltip/modal design specs.
+
+## Card chrome — `resolveBubbleChrome`
+
+Source: `src/surfaces/themeChrome.ts`
+
+| Web / theme token                         | RN usage                                                         |
+| ----------------------------------------- | ---------------------------------------------------------------- |
+| `backgroundColor`                         | Card `backgroundColor`                                           |
+| `bubbleBorderRadius` (default `10`)       | Card `borderRadius`                                              |
+| `bubbleBorderWidth` / `bubbleBorderColor` | Card border                                                      |
+| `tooltipNotchSize` (default `10`)         | Tooltip notch size; `0` hides notch                              |
+| Modal content padding                     | `40` (web modal)                                                 |
+| Tooltip / bubble content padding          | `24` (web tooltip)                                               |
+| Shadow                                    | Approximate dual drop-shadow via `shadow*` + Android `elevation` |
+
+Modal cards use `overflow: 'hidden'` so the progress bar clips to the radius.
+Tooltip cards use `overflow: 'visible'` so the notch is not clipped.
+
+## Progress — `ProgressBar`
+
+| Theme token                              | RN usage                                          |
+| ---------------------------------------- | ------------------------------------------------- |
+| `progressBarEnabled`                     | Show / hide                                       |
+| `progressBarPosition` (`TOP` / `BOTTOM`) | Placement flush on the card edge                  |
+| `progressBarType`                        | `DEFAULT` fraction bar; `NUMBERED` shows `1 of N` |
+| Step `progress` + step index             | Fraction via `resolveStepProgress`                |
+
+## Buttons — `StepButton`
+
+| Theme token                     | RN usage                     |
+| ------------------------------- | ---------------------------- |
+| `defaultButtonBackgroundColor`  | Primary button fill          |
+| `defaultButtonFontColor`        | Primary button label         |
+| Button fragment colors when set | Override defaults per button |
+
+## Backdrop & cutout
+
+| Theme token                                                  | RN usage                                        |
+| ------------------------------------------------------------ | ----------------------------------------------- |
+| `backdropColor`                                              | Modal full-screen backdrop; tooltip cutout fill |
+| `backdropOpacity`                                            | Parsed float (`parseBackdropOpacity`)           |
+| `modalBackdropOnclick`                                       | `DISMISS` → tap backdrop ends flow              |
+| Step `backdrop` / `backdropPadding` / `tooltipTargetBlocked` | Tooltip cutout hole + blocking                  |
+
+## Typography
+
+| Theme token  | RN usage                            |
+| ------------ | ----------------------------------- |
+| `fontColor`  | Body / heading / close affordance   |
+| `fontSize`   | Base body size                      |
+| `fontFamily` | Applied where Text styles accept it |
+
+## Quote / code-block — TreeDoc chrome
+
+Source of truth: web `userflowjs/styles/bubble-frame.styl` in the main Userflow
+web repo (blockquote / `code` / `pre > code`) and TreeDoc markup
+(`blockquote`, `pre > code`). Spacing tokens from web `$padding-*` assume
+**1rem = 16px**.
+
+Implementation: `src/content/RichContentRenderer.tsx` + `src/content/themeColor.ts`.
+
+| Token         | rem   | RN px |
+| ------------- | ----- | ----- |
+| `$padding-2`  | 0.125 | 2     |
+| `$padding-4`  | 0.25  | 4     |
+| `$padding-8`  | 0.5   | 8     |
+| `$padding-16` | 1     | 16    |
+
+Root content uses `gap: 8` (`ROOT_CONTENT_GAP`). Quote/code add
+`marginBottom: 8` when not last so gap + margin ≈ web’s 16px block spacing.
+
+### Quote (`blockquote`)
+
+| Web rule                                        | RN                                                                               |
+| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| `border-inline-start: 2px solid rgba(fg, 0.15)` | `borderStartWidth: 2`, `borderStartColor` via `foregroundAlpha(fontColor, 0.15)` |
+| `padding: $padding-4 $padding-16`               | `paddingVertical: 4`, `paddingHorizontal: 16`                                    |
+| `margin-bottom: $padding-16` when not last      | `marginBottom: 8` (+ root gap 8); last painted sibling: 0                        |
+| `min-height: var(--userflow-line-height, 24px)` | `minHeight: 24`                                                                  |
+| Not italic by default                           | No forced `fontStyle: 'italic'`                                                  |
+
+### Code-block (`pre > code`) and inline `code` mark
+
+| Web rule                                                                   | RN                                                                 |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Mono stack (`SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace`) | iOS `Menlo`, Android `monospace`                                   |
+| `font-size: calc(font-size * 0.875)`                                       | `fontSize * 0.875`                                                 |
+| `background: rgba(fg, 0.05)`                                               | `foregroundAlpha(fontColor, 0.05)` (hex / rgb / rgba)              |
+| `border-radius: calc(font-size * 0.25)`                                    | `fontSize * 0.25`                                                  |
+| `pre > code` padding `$padding-8`                                          | `padding: 8` + horizontal `ScrollView` (`nestedScrollEnabled`)     |
+| Inline `code` padding `$padding-2 $padding-4`                              | View chrome wrapper + `paddingVertical: 2`, `paddingHorizontal: 4` |
+
+## Safe area
+
+Surfaces pad with `useUserflowSafeAreaInsets` (optional peer
+`react-native-safe-area-context`, zero fallback) so cards clear Dynamic Island /
+home indicator regions on notched devices.

package/docs/troubleshooting.md

@@ -0,0 +1,107 @@
+# Troubleshooting
+
+Symptom → cause for common `@userflow-tech/react-native` integration failures.
+Messages are quoted exactly so you can search logs for them.
+
+## 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                                            |
+| `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                  | Reduce chatter; 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                                              | Required peer missing                                     | `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                                    |
+
+## Flow never appeared
+
+Check **device logs first** (`__DEV__` warnings), then the checklist below.
+
+### 1. Unsupported client condition (silent)
+
+A flow gated on a condition the SDK cannot evaluate stays `isTrue: null`. The
+server treats **unknown exactly like false**, so the flow **never starts** and
+nothing throws.
+
+Look for warnings such as:
+
+```text
+[Userflow] ELEMENT condition … uses an AUTO (codeless) selector; …
+[Userflow] ELEMENT condition … uses unsupported elementState "CLICK" …
+```
+
+Or a core warning that a condition type has no evaluator (`INPUT_VALUE`,
+`FILLED_IN_INPUT`, …).
+
+**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).
+
+### 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)                                                                    |
+| Off-screen target not scrolled into view         | Parent `ScrollView` not registered with `useUserflowScrollContainer`                                                            |
+| 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')`).
+
+### 3. Screen / provider
+
+| Symptom                             | Likely cause                                                                                                                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| No overlay at all                   | Missing `UserflowProvider` above the tree                                                                                                                                                        |
+| Wrong screen / flow never qualifies | Screen not reported — Expo Router needs `UserflowExpoRouterScreenTracker` under the provider; React Navigation needs `WithUserflowReactNavigation`; or call `updateScreen` / `useUserflowScreen` |
+| Works only after identify           | Expected for server-driven sessions; `updateScreen` before identify only buffers                                                                                                                 |
+
+### 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          |
+
+## 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** banner 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** banner)                                                              | Confirm the banner 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`                                                                                |
+
+## Expo
+
+| Symptom                                                           | Fix                                                            |
+| ----------------------------------------------------------------- | -------------------------------------------------------------- |
+| Crashes or missing native modules in Expo Go                      | Use a **development build**; Expo Go is not supported          |
+| Duplicate React / RN instance crashes when linking local packages | Force singletons in Metro — monorepo `docs/metro.md`           |
+| Preview / pairing scheme not registered                           | Add `@userflow-tech/expo` with `schemeId`, then rebuild native |
+
+## 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.
+4. Confirm the anchor id in code matches the builder selector after stripping `#`.
+5. For builder Preview: confirm the **Preview mode** banner is visible before you
+   click Preview in the dashboard.

package/lib/commonjs/anchors/AnchorRegistry.js

@@ -0,0 +1,72 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.anchorRegistry = exports.AnchorRegistry = void 0;
+/** Host view that can be measured in window coordinates. */
+
+/**
+ * Manual-anchor registry for Phase 3 (WS6). Codeless resolution is Phase 4.
+ * Multiple mounts of the same id keep a set; {@link get} returns the most
+ * recently registered host.
+ */
+class AnchorRegistry {
+  anchors = new Map();
+  listeners = new Set();
+  register(id, host) {
+    if (!id) return;
+    let set = this.anchors.get(id);
+    if (!set) {
+      set = new Set();
+      this.anchors.set(id, set);
+    }
+    set.add(host);
+    this.emit();
+  }
+  unregister(id, host) {
+    const set = this.anchors.get(id);
+    if (!set) return;
+    set.delete(host);
+    if (set.size === 0) {
+      this.anchors.delete(id);
+    }
+    this.emit();
+  }
+  get(id) {
+    const set = this.anchors.get(id);
+    if (!set || set.size === 0) return null;
+    let last = null;
+    for (const host of set) {
+      last = host;
+    }
+    return last;
+  }
+
+  /** True when more than one host is registered for the same id. */
+  isAmbiguous(id) {
+    return (this.anchors.get(id)?.size ?? 0) > 1;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** Test helper — clear all anchors. */
+  clear() {
+    this.anchors.clear();
+    this.emit();
+  }
+  emit() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+/** Module singleton used by {@link useUserflowAnchor} and TooltipSurface. */
+exports.AnchorRegistry = AnchorRegistry;
+const anchorRegistry = exports.anchorRegistry = new AnchorRegistry();
+//# sourceMappingURL=AnchorRegistry.js.map

package/lib/commonjs/anchors/AnchorRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["AnchorRegistry","anchors","Map","listeners","Set","register","id","host","set","get","add","emit","unregister","delete","size","last","isAmbiguous","subscribe","listener","clear","exports","anchorRegistry"],"sourceRoot":"../../../src","sources":["anchors/AnchorRegistry.ts"],"mappings":";;;;;;AAAA;;AAcA;AACA;AACA;AACA;AACA;AACO,MAAMA,cAAc,CAAC;EACTC,OAAO,GAAG,IAAIC,GAAG,CAA0B,CAAC;EAC5CC,SAAS,GAAG,IAAIC,GAAG,CAAW,CAAC;EAEhDC,QAAQA,CAACC,EAAU,EAAEC,IAAgB,EAAQ;IAC3C,IAAI,CAACD,EAAE,EAAE;IACT,IAAIE,GAAG,GAAG,IAAI,CAACP,OAAO,CAACQ,GAAG,CAACH,EAAE,CAAC;IAC9B,IAAI,CAACE,GAAG,EAAE;MACRA,GAAG,GAAG,IAAIJ,GAAG,CAAC,CAAC;MACf,IAAI,CAACH,OAAO,CAACO,GAAG,CAACF,EAAE,EAAEE,GAAG,CAAC;IAC3B;IACAA,GAAG,CAACE,GAAG,CAACH,IAAI,CAAC;IACb,IAAI,CAACI,IAAI,CAAC,CAAC;EACb;EAEAC,UAAUA,CAACN,EAAU,EAAEC,IAAgB,EAAQ;IAC7C,MAAMC,GAAG,GAAG,IAAI,CAACP,OAAO,CAACQ,GAAG,CAACH,EAAE,CAAC;IAChC,IAAI,CAACE,GAAG,EAAE;IACVA,GAAG,CAACK,MAAM,CAACN,IAAI,CAAC;IAChB,IAAIC,GAAG,CAACM,IAAI,KAAK,CAAC,EAAE;MAClB,IAAI,CAACb,OAAO,CAACY,MAAM,CAACP,EAAE,CAAC;IACzB;IACA,IAAI,CAACK,IAAI,CAAC,CAAC;EACb;EAEAF,GAAGA,CAACH,EAAU,EAAqB;IACjC,MAAME,GAAG,GAAG,IAAI,CAACP,OAAO,CAACQ,GAAG,CAACH,EAAE,CAAC;IAChC,IAAI,CAACE,GAAG,IAAIA,GAAG,CAACM,IAAI,KAAK,CAAC,EAAE,OAAO,IAAI;IACvC,IAAIC,IAAuB,GAAG,IAAI;IAClC,KAAK,MAAMR,IAAI,IAAIC,GAAG,EAAE;MACtBO,IAAI,GAAGR,IAAI;IACb;IACA,OAAOQ,IAAI;EACb;;EAEA;EACAC,WAAWA,CAACV,EAAU,EAAW;IAC/B,OAAO,CAAC,IAAI,CAACL,OAAO,CAACQ,GAAG,CAACH,EAAE,CAAC,EAAEQ,IAAI,IAAI,CAAC,IAAI,CAAC;EAC9C;EAEAG,SAASA,CAACC,QAAkB,EAAc;IACxC,IAAI,CAACf,SAAS,CAACO,GAAG,CAACQ,QAAQ,CAAC;IAC5B,OAAO,MAAM;MACX,IAAI,CAACf,SAAS,CAACU,MAAM,CAACK,QAAQ,CAAC;IACjC,CAAC;EACH;;EAEA;EACAC,KAAKA,CAAA,EAAS;IACZ,IAAI,CAAClB,OAAO,CAACkB,KAAK,CAAC,CAAC;IACpB,IAAI,CAACR,IAAI,CAAC,CAAC;EACb;EAEQA,IAAIA,CAAA,EAAS;IACnB,KAAK,MAAMO,QAAQ,IAAI,IAAI,CAACf,SAAS,EAAE;MACrCe,QAAQ,CAAC,CAAC;IACZ;EACF;AACF;;AAEA;AAAAE,OAAA,CAAApB,cAAA,GAAAA,cAAA;AACO,MAAMqB,cAAc,GAAAD,OAAA,CAAAC,cAAA,GAAG,IAAIrB,cAAc,CAAC,CAAC","ignoreList":[]}