@userflow-tech/react-native 0.1.1 → 0.2.0

package/docs/anchoring.md

@@ -50,8 +50,109 @@ function InviteButton() {
 ```
 
 No SDK import is required on the target view. Prefer **MANUAL** selectors in the
-builder for mobile. `AUTO` (codeless) selectors are not evaluated today;
-conditions that use them stay unknown and gated flows do not start.
+builder for mobile when you control the host code.
+
+### AUTO (codeless) selectors
+
+`AUTO` selectors carry a `MobileAutoData` fingerprint on `selector.autoData`
+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).
+   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
+   scan). A hit must clear the matcher threshold and uniqueness margin, and
+   carries the host fiber when the public instance exposes one so tooltips can
+   scroll the target into view. Babel full mode (the default) is what
+   registers those instances.
+
+Fail-closed mapping for ELEMENT conditions:
+
+| Resolution               | `PRESENT` / `NOT_PRESENT`                    |
+| ------------------------ | -------------------------------------------- |
+| `found`                  | true / false                                 |
+| `absent`                 | false / true                                 |
+| `ambiguous` or `unknown` | unknown (`null`) — gated flow does not start |
+
+`unknown` covers empty registry, missing fingerprint, below-threshold, and
+non-unique matches. An AUTO `NOT_PRESENT` condition therefore does **not**
+become true just because nothing registered.
+
+### Authoring (in-app picker)
+
+While a device is paired, the Builder can send `selectElement` over the pairing
+channel. `UserflowProvider` mounts an overlay that is idle until then:
+
+1. **Navigate / Select** — Navigate lets the author reach the screen; Select
+   hit-tests stamped hosts under the tap (full-mode Babel populates the
+   auto-anchor registry; `stampOnly: true` leaves it empty).
+2. **Confirm** encodes `MobileAutoData`, runs `matchAutoData` against the live
+   registry, and only commits a unique hit on the same instance. Ambiguous or
+   below-threshold fingerprints fail closed (add a `testID` / `userflowId`).
+3. The result is relayed as `selectElementResult`. A missing server ack is
+   ignored; a dropped connection keeps the picker open. Screenshots use required
+   peer `react-native-view-shot` (omitted on the wire if capture fails).
+
+### Live content (dynamic text and inputs)
+
+Build-time stamping only captures **static** JSX strings. Interpolated labels
+(`<Text>{label}</Text>`, `{t('…', { count })}`) and `TextInput` placeholders
+are read from the live fiber at capture and match time:
+
+1. `refreshLiveContent` walks each candidate's fiber (`readHostText`, or
+   `readHostPlaceholder` for `Input` role). Live text wins; the Babel hint is
+   the fallback when nothing readable is on the fiber. Depth is counted in
+   **host** levels, not fibers, because the number of composites, `forwardRef`s
+   and context providers between two hosts is an RN version detail.
+2. `TextInput` is on the Babel allowlist, so inputs register as AUTO hosts.
+   A dynamic `testID={id}` is read from the live host (not the shared Babel
+   callback's last-writer runtime bag) so helper-rendered rows stay unique.
+3. A label broken up by an interpolation reaches React as several children
+   (`<Text>{count} items</Text>` is `[3, ' items']`); the fragments are joined,
+   so the recorded text is `3 items` rather than `3`.
+4. Digit runs in `childText` are collapsed (`Count: 0` ≡ `Count: 1`) so a
+   volatile counter is not disqualified. A true rename (`Save` vs `Cancelar`)
+   is still fatal unless an id/icon vouches. List rows that only differ by a
+   number (`Item 1` / `Item 2`) stay **not-unique** — they tie after
+   normalization and fail closed.
+5. Ambiguity follows the live content. Rows from one helper share a template
+   path and start out flagged, then separate as soon as distinct labels are
+   read; rows that read back the same label stay flagged, and so does a row
+   with no content of its own next to a labelled peer. The picker's
+   "not uniquely identifiable" warning is that flag.
+
+Hand-added `testID` / `userflowId` remains the most durable identity, but it
+is not required for these cases.
+
+#### Reaching the fiber on each renderer
+
+Everything above depends on getting from the public instance an app `ref`
+holds to its host fiber. Where that link lives differs by renderer, so
+resolution is layered — fast path first, then a fallback that needs no
+renderer-specific field. Pinned by `rendererCompat.test.ts`.
+
+| Renderer                                       | Fiber pointer on the instance                                | Live props                                               |
+| ---------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
+| Fabric, RN 0.74+ (`ReactNativeElement`)        | `__internalInstanceHandle`                                   | `memoizedProps`, else `stateNode.canonical.currentProps` |
+| Fabric, RN ≤ 0.73 (`ReactFabricHostComponent`) | `_internalInstanceHandle`                                    | `memoizedProps`                                          |
+| Paper, DEV                                     | only `_internalFiberInstanceHandleDEV`, which we do not read | `memoizedProps`                                          |
+| Paper, release                                 | **none**                                                     | `memoizedProps`                                          |
+
+Paper release builds null out the DEV handle, so a host ref has no route to a
+fiber at all. `FiberScanRoot` covers that: it is a class component, and
+`_reactInternals` is present on class instances in every renderer and build
+type, so we can always walk down from it and index host fibers by native tag
+(`__nativeTag` / `_nativeTag` / `canonical.nativeTag`) and by instance
+identity. The index is built lazily — on renderers where the direct pointer
+works, the walk never happens.
+
+The same layering absorbs a renderer storing something unexpected on the
+handle: `isReactFiber` rejects non-fibers structurally, so resolution falls
+through to the native-tag index instead of walking a foreign object and
+reading nothing.
 
 ### Prop priority
 
@@ -177,18 +278,40 @@ SDK.
 Screen tracking ≠ scroll registration. Only `ScrollView`s you pass through this
 hook participate in the registry override path.
 
+## Card viewport
+
+Modal and tooltip cards stay inside a layout rect of **safe area + 24px
+margin**, plus the Preview-mode banner when it is mounted. Tall content
+(`maxHeight` on the overflow-hidden fill) scrolls inside the card; the
+tooltip notch is laid out against that capped height so it stays attached
+to the card edge instead of floating over the host.
+
+The overlay itself remains full-screen so `measureInWindow` coordinates
+still match card `left` / `top`.
+
+When no side has room (a tall card against a target near a screen edge),
+the pointer is hidden rather than left pointing at empty space. ABOVE and
+BELOW cards cap their height to the room on that side so a scrollable card
+can still sit next to the target.
+
 ## Backdrop interaction
 
-When a tooltip step has `backdrop: true` and `tooltipTargetBlocked: false`, the
-dimmed cutout is **visual only** (`pointerEvents="none"` on the four bands).
-Touches reach the app underneath, so the host screen stays scrollable and
-tappable — React Native cannot block taps while allowing scroll the way web's
-`mousedown`-only swallow does.
+By default, tooltip cutout bands intercept taps outside the highlight hole so
+users cannot reach host CTAs until they act on the flow. The target hole stays
+open when `tooltipTargetBlocked: false` so guided tours can still observe
+"When target element is clicked" via `TargetPressBridge` (the app control
+still receives the press). When `tooltipTargetBlocked: true`, a transparent
+capture layer also covers the hole so the whole screen is sealed.
 
-When `tooltipTargetBlocked: true`, a transparent capture layer covers **only
-the highlight hole** so the target cannot be pressed. The rest of the app stays
-tappable and scrollable (dim bands remain `pointerEvents="none"`). Modal steps
-are unchanged and remain blocking.
+Modals always block — the full-screen backdrop is a `Pressable` hit target.
+
+Pass `Userflow.setSurfaceInteractionBlocking(false)` to restore the legacy
+pass-through tooltip backdrop (`pointerEvents="none"` on dim bands) so the
+host screen stays scrollable and tappable underneath. The `tooltipTargetBlocked`
+hole seal is unchanged — it was independent of band pass-through before UMD-74.
+
+When a tooltip step has `backdrop: false`, the cutout still mounts with dim
+opacity `0` so interaction blocking applies without a visible dim.
 
 ## When target element is clicked
 
@@ -234,8 +357,13 @@ 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.
-Unsupported states (`CLICK`, `DISABLED`, …) and `AUTO` selectors stay unknown —
-see [troubleshooting.md](troubleshooting.md).
+
+`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).
 
 ## How the fiber scan works (brief)
 

package/docs/deep-linking.md

@@ -132,8 +132,8 @@ await Userflow.init({
 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
+Wrap the tree in `UserflowProvider`. It mounts a **Preview mode** top bar while
+a pairing session is active — that bar 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`)
@@ -159,8 +159,9 @@ cannot start: invalid_client_token: … Fix the init error — most often an inv
 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
+and `UserflowProvider` renders a **Preview unavailable** top bar. The detailed
+reason is logged (search `[Userflow]`); it is no longer shown on the bar itself.
+If you see the app open with no bar at all, check that your
 `init()` call is actually resolving — host apps commonly swallow it:
 
 ```ts
@@ -180,7 +181,7 @@ 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
+**Preview unavailable** top bar when recognisable). Use the `scheme_id` exactly
 as the QR code provides it.
 
 Reporting is limited to URLs the SDK can recognise as pairing attempts, so your
@@ -190,12 +191,13 @@ 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.
+`init()` still resolves and the app runs normally, with the reason logged under
+`[Userflow]` and the top bar switching to the error tone.
 
-Optional: install `expo-secure-store` so the pairing JWT can persist in
-Keychain/Keystore for the duration of the session
-(`npx expo install expo-secure-store`).
+Optional: install `expo-secure-store` (and configure Expo modules in bare
+React Native) so the pairing JWT can persist in Keychain/Keystore for the
+duration of the session (`npx expo install expo-secure-store`). Without Expo
+modules, the SDK falls back to in-memory storage automatically.
 
 ### Host apps that already own Linking
 
@@ -226,8 +228,9 @@ so your own routing still runs. To classify a URL without consuming it, use
 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.
+Call `Userflow.exitPreview()` to disconnect the pairing websocket immediately.
+The top bar's exit control asks for confirmation first; calling `exitPreview()`
+from JS does not.
 
 ## 3. Verify
 
@@ -243,14 +246,14 @@ 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.
+2. Confirm the app shows the **Preview mode** top bar.
 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
+conditions to match, so nothing appears until they do — the top bar reads
+**Waiting for auto-start condition…** meanwhile. A flow that never
 shows up in that mode points at the condition, not at pairing.
 
 ## Local / staging endpoints

package/docs/theme-mapping.md

@@ -13,7 +13,7 @@ Source: `src/surfaces/themeChrome.ts`
 | `bubbleBorderRadius` (default `10`)       | Card `borderRadius`                                              |
 | `bubbleBorderWidth` / `bubbleBorderColor` | Card border                                                      |
 | `tooltipNotchSize` (default `10`)         | Tooltip notch size; `0` hides notch                              |
-| Modal content padding                     | `40` (web modal)                                                 |
+| Modal content padding                     | `24` (mobile; web default is 40)                                 |
 | Tooltip / bubble content padding          | `24` (web tooltip)                                               |
 | Shadow                                    | Approximate dual drop-shadow via `shadow*` + Android `elevation` |
 
@@ -31,20 +31,45 @@ Tooltip cards use `overflow: 'visible'` so the notch is not clipped.
 
 ## Buttons — `StepButton`
 
-| Theme token                     | RN usage                     |
-| ------------------------------- | ---------------------------- |
-| `defaultButtonBackgroundColor`  | Primary button fill          |
-| `defaultButtonFontColor`        | Primary button label         |
-| Button fragment colors when set | Override defaults per button |
+| Theme token                     | RN usage                                                         |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `primaryButton*` / widget brand | Primary filled button                                            |
+| Secondary (DEFAULT)             | Neutral outline: white fill, `#d1d5db` border, `fontColor` 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                  |
+| 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, dim, and interaction blocking (bands block by default; hole sealed when `tooltipTargetBlocked`) |
+
+## Tooltip target highlight
+
+Source: `src/surfaces/resolveHighlightChrome.ts` + `src/surfaces/tooltip/TooltipHighlight.tsx`.
+
+Web paints the ring as one CSS `box-shadow` on `.userflowjs-tooltip-backdrop`.
+RN uses a **2px brand stroke + one translucent halo**, plus iOS `shadow*` /
+Android `boxShadow` for blur. Theme spread is a placement gap only — it is
+not painted as a thick solid bar.
+
+| Web / theme token          | RN usage                                                                         |
+| -------------------------- | -------------------------------------------------------------------------------- |
+| `backdropHighlightColor`   | Stroke color. Near-white (web default `#ffffff`) is treated as unset — see below |
+| `backdropHighlightOpacity` | Caps the halo at `0.32` so it stays a wash                                       |
+| `backdropHighlightRadius`  | Halo thickness (default `4`)                                                     |
+| `backdropHighlightSpread`  | Added to placement pad when type is `OUTSIDE` (default `0`). Not stroke width    |
+| `backdropHighlightType`    | `OUTSIDE` (default) draws outside the hole; `INSIDE` insets                      |
+
+Placement pad for `OUTSIDE` is `spread + strokeWidth + radius` so the tooltip
+sits clear of the painted ring, not only the theme spread token.
+| Corner radius | `8` + `backdropPadding` (web copies the target's computed radius; RN measure cannot) |
+
+Color fallback: non-white `backdropHighlightColor` → `widgetBackgroundColor` →
+`brandBackgroundColor` → `defaultButtonBackgroundColor` → `#1a57e6`. Web's
+`#ffffff` default is skipped so the dimmed cutout does not get a white frame.
 
 ## Typography
 
@@ -96,6 +121,10 @@ Root content uses `gap: 8` (`ROOT_CONTENT_GAP`). Quote/code add
 
 ## 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.
+Surfaces pad with `useSurfaceLayoutInsets`: optional-peer
+`react-native-safe-area-context` (zero fallback) plus a 24px screen margin so
+cards clear Dynamic Island / home indicator regions. While Builder preview is
+active, the measured Preview banner height is added to the top inset so the
+close control is not trapped under the banner. Tall cards cap at that padded
+window height and scroll internally (`overflow: 'hidden'` on the fill; the
+shadow/notch shell stays `overflow: 'visible'`).

package/docs/troubleshooting.md

@@ -5,20 +5,23 @@ 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                                              | 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; 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                                                                                 |
 
 ## Flow never appeared
 
@@ -33,7 +36,7 @@ nothing throws.
 Look for warnings such as:
 
 ```text
-[Userflow] ELEMENT condition … uses an AUTO (codeless) selector; …
+[Userflow] ELEMENT condition … uses an AUTO (codeless) selector that could not be resolved; …
 [Userflow] ELEMENT condition … uses unsupported elementState "CLICK" …
 ```
 
@@ -46,13 +49,15 @@ Or a core warning that a condition type has no evaluator (`INPUT_VALUE`,
 
 ### 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                                                                  |
+| 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`                                                                                                  |
+| “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')`).
 
@@ -63,6 +68,7 @@ Id matching: dashboard `#invite-teammates` ↔ `testID="invite-teammates"` (or `
 | 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                                                                                                                 |
+| No `screen_viewed` events           | Identify has not run, or an overlay (modal/sheet) is focused — overlays are not screen views                                                                                                     |
 
 ### 4. Connection
 
@@ -80,20 +86,21 @@ Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all buil
 | 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 but nothing happens, and no **Preview mode** top bar appears             | `Userflow.init()` rejected, so there is no session to preview into                                                       | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken` or `serverEndpoint`) and re-open the link |
 | Deep link opens the app and the router shows **Unmatched Route** / "page could not be found"     | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<digits>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme                        |
 | Pairing deep link ignored (preview URL may still work)                                           | Scheme is `userflow-*` but not `userflow-` + **digits**                                                                  | Use the env's `scheme_id` from the dashboard (e.g. `userflow-257587`), not the env UUID                                                                                     |
 | Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks                                                                 | Pair again on the device you are watching, or clear the env's pairing session and re-QR                                                                                     |
-| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** banner)                                                              | Confirm the banner before hitting Preview; re-open the pairing QR on this install                                                                                           |
+| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** top bar)                                                             | Confirm the top bar before hitting Preview; re-open the pairing QR on this install                                                                                          |
 | Pairing never connects against a local stack                                                     | `pairingEndpoint` still pointing at production                                                                           | `Userflow.init({ pairingEndpoint: 'http://localhost:40401', serverEndpoint: '…' })`                                                                                         |
 | QR / `https://…/pair/<jwt>` does nothing in the app                                              | SDK only parses the **scheme** form after the backend redirect                                                           | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl`                                                                                |
+| Builder selector has no screenshot after Confirm                                                 | Missing / unlinked `react-native-view-shot`, or Expo SDK 54 pinned 4.x                                                   | Install `react-native-view-shot@^5.0.0` and **rebuild native**. Look for `[Userflow] Required peer react-native-view-shot is not installed`                                 |
 
 ## Expo
 
-| 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`           |
+| 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 the `@userflow-tech/react-native` plugin with `schemeId`, then rebuild native |
 
 ## Still stuck?
@@ -103,5 +110,5 @@ Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all buil
 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
+5. For builder Preview: confirm the **Preview mode** top bar is visible before you
    click Preview in the dashboard.

package/expo-plugin/withUserflow.js

@@ -25,7 +25,7 @@ const config_plugins_1 = require("@expo/config-plugins");
  */
 const PACKAGE_NAME = '@userflow-tech/react-native';
 // When packed into the SDK, this file lives at expo-plugin/ and reads the SDK version.
-// eslint-disable-next-line @typescript-eslint/no-require-imports
+// eslint-disable-next-line @typescript-eslint/no-var-requires
 const PACKAGE_VERSION = require('../package.json').version;
 const USERFLOW_SCHEME_PREFIX = 'userflow-';
 /** Environment scheme_id shape — must match pairing deep-link validation. */

package/expo-plugin/withUserflow.js.map

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