@userflow-tech/react-native 0.1.0

package/LICENSE

@@ -0,0 +1,76 @@
+Userflow React Native SDK
+
+Copyright (c) 2026 Userflow Inc. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL
+
+This software and its source code (the "Software") are the proprietary and
+confidential property of Userflow Inc. ("Userflow"). The Software is licensed,
+not sold.
+
+1. Grant of License
+
+   Use of the Software is permitted only by parties who have entered into a
+   written agreement with Userflow that expressly covers the Software (the
+   "Agreement"), and only for the duration, purposes, and scope set out in
+   that Agreement. Where the Software is provided for evaluation or as part
+   of an early-access or design-partner program, use is limited to internal
+   evaluation and integration testing unless the Agreement states otherwise.
+
+   If you have not entered into such an Agreement with Userflow, you are
+   granted no rights to use, copy, modify, or distribute the Software.
+
+2. Restrictions
+
+   Except as expressly permitted by the Agreement or by applicable law, you
+   may not:
+
+   (a) redistribute, sublicense, sell, rent, lease, or otherwise transfer the
+       Software or any portion of it to any third party, except that you may
+       ship the Software in compiled or bundled form as an integral part of
+       your own applications distributed to your end users, provided you do
+       not redistribute the Software as a standalone library or SDK;
+   (b) modify or create derivative works of the Software, except for
+       automated transformations performed by ordinary build tooling
+       (including transpilation, bundling, minification, tree-shaking, and
+       source-map generation) and other modifications reasonably necessary
+       to integrate the Software into your applications, provided that any
+       such modifications remain subject to this notice;
+   (c) remove or obscure any copyright, trademark, or other proprietary
+       notices contained in the Software;
+   (d) disclose the Software's source code to any third party, except to your
+       employees and contractors who need access for a purpose permitted by
+       the Agreement and who are bound by written confidentiality
+       obligations no less protective than those in the Agreement.
+
+3. Pre-Release Software
+
+   The Software may be provided prior to general availability. It may be
+   incomplete, may change without notice, and may not be backward compatible
+   between versions. Userflow is under no obligation to provide maintenance,
+   support, updates, or future releases except as set out in the Agreement.
+
+4. No Warranty
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
+
+5. Limitation of Liability
+
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   USERFLOW BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+   AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+   CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+6. Precedence
+
+   In the event of a conflict between this notice and the Agreement, the
+   Agreement governs.
+
+For licensing enquiries, contact:
+
+Userflow Inc.
+548 Market St PMB 69598
+San Francisco, CA 94104-5401
+United States

package/README.md

@@ -0,0 +1,337 @@
+# `@userflow-tech/react-native`
+
+Official Userflow SDK for React Native and Expo. Deliver guided flows, tooltips,
+and modals authored in the Userflow dashboard — without shipping a new app
+release for every content change.
+
+> Early development. APIs may change. Packages publish to a private npm org
+> (`publishConfig.access: restricted`).
+
+## Requirements
+
+| Peer dependency                             | Required? | Why                                                           |
+| ------------------------------------------- | --------- | ------------------------------------------------------------- |
+| `react`, `react-native`                     | Yes       | Host runtime.                                                 |
+| `@react-native-async-storage/async-storage` | Yes       | Persists the anonymous user id across launches.               |
+| `react-native-safe-area-context`            | Optional  | Correct insets for modal/tooltip surfaces.                    |
+| `@react-navigation/native`                  | Optional  | Screen tracking + NAVIGATE routing (React Navigation).        |
+| `expo-router`                               | Optional  | Screen tracking + NAVIGATE routing (Expo Router).             |
+| `@react-native-community/netinfo`           | Optional  | Instant offline→online reconnect (enhancement, not required). |
+| `expo-secure-store`                         | Optional  | Persist Builder pairing JWT in Keychain/Keystore.             |
+
+Optional peers are declared `optional: true` in `peerDependenciesMeta`, so
+package managers will not warn if you skip them.
+
+### Expo Go is not supported
+
+Use an **Expo development build** (or bare React Native). The SDK is not
+compatible with Expo Go.
+
+## Install
+
+```bash
+# Expo (dev build) — include the config plugin for Builder deep-link schemes
+npx expo install @userflow-tech/react-native @userflow-tech/expo @react-native-async-storage/async-storage
+
+# Bare React Native
+npm install @userflow-tech/react-native @react-native-async-storage/async-storage
+cd ios && pod install
+```
+
+Optional peers as needed:
+
+```bash
+npx expo install react-native-safe-area-context @react-native-community/netinfo expo-secure-store
+# and either expo-router or @react-navigation/native, depending on your router
+```
+
+For local tarball installs from this monorepo (before the private registry is
+set up), pack with `pnpm pack:all` at the repo root and install **all four**
+tarballs together — a single `@userflow-tech/react-native` tarball alone will fail
+because `@userflow-tech/core@0.1.0` is not on the public registry, and Expo hosts
+need `@userflow-tech/expo` for scheme registration. Steps:
+`docs/local-testing.md` in the monorepo.
+
+## Quick start
+
+```tsx
+import { Userflow, UserflowProvider } from '@userflow-tech/react-native';
+
+await Userflow.init({
+  clientToken: 'ct_...', // from the Userflow dashboard → Environments
+  // serverEndpoint: 'https://e.userflow.com', // default; set for staging/local
+  // pairingEndpoint: 'https://e.userflow.com', // default; set for local Builder pairing
+});
+
+// Identified user — signature is computed by YOUR backend, never in the app:
+await Userflow.identify('user-123', { name: 'Ada' }, { signature });
+
+// …or anonymous (id stored in AsyncStorage):
+await Userflow.identifyAnonymous();
+```
+
+Wrap the app tree so flows can render:
+
+```tsx
+import { UserflowProvider } from '@userflow-tech/react-native';
+
+export default function RootLayout() {
+  return (
+    <UserflowProvider>
+      <App />
+    </UserflowProvider>
+  );
+}
+```
+
+Call `Userflow.teardown()` when tearing the SDK down (removes AppState and
+NetInfo subscriptions). Call `Userflow.reset()` on logout to clear identity and
+disconnect.
+
+### Call order
+
+| Call                             | Before `init()` resolves                            | Before `identify()`                                  |
+| -------------------------------- | --------------------------------------------------- | ---------------------------------------------------- |
+| `identify` / `identifyAnonymous` | **Throws** `Call Userflow.init() before identify()` | —                                                    |
+| `group`                          | **Throws** `Call Userflow.init() before group()`    | **Throws** `Call Userflow.identify() before group()` |
+| `track`                          | **Throws** `Call Userflow.init() before track()`    | **Throws** `Call Userflow.identify() before track()` |
+| `updateScreen`                   | Silently buffers; included on the next channel join | Silently buffers                                     |
+
+Other rules:
+
+- `init()` is **idempotent**. A second call returns the cached promise and does
+  **not** apply new options. Restart the process (or call `reset()` then
+  re-init carefully) if you need different credentials.
+- `identify()` with a **different** user id resets the previous identity first.
+  Same-id re-identify merges attributes.
+- Identity verification `signature` is optional in the type, but **required by
+  the server** when the environment has identity verification enabled. See
+  [docs/identity-verification.md](docs/identity-verification.md).
+
+## Screen tracking
+
+### Expo Router
+
+Mount `UserflowExpoRouterScreenTracker` from the `@userflow-tech/react-native/expo-router`
+subpath under `UserflowProvider` (the tracker is a separate entry so apps without
+`expo-router` are not forced to install that peer):
+
+```tsx
+import { UserflowProvider } from '@userflow-tech/react-native';
+import { UserflowExpoRouterScreenTracker } from '@userflow-tech/react-native/expo-router';
+import { Stack } from 'expo-router';
+
+export default function RootLayout() {
+  return (
+    <UserflowProvider>
+      <UserflowExpoRouterScreenTracker />
+      <Stack />
+    </UserflowProvider>
+  );
+}
+```
+
+### React Navigation
+
+Wrap `NavigationContainer` with `WithUserflowReactNavigation` from the
+`@userflow-tech/react-native/navigation` subpath:
+
+```tsx
+import { UserflowProvider } from '@userflow-tech/react-native';
+import { WithUserflowReactNavigation } from '@userflow-tech/react-native/navigation';
+import { NavigationContainer } from '@react-navigation/native';
+
+export default function App() {
+  return (
+    <UserflowProvider>
+      <WithUserflowReactNavigation>
+        <NavigationContainer>{/* navigators */}</NavigationContainer>
+      </WithUserflowReactNavigation>
+    </UserflowProvider>
+  );
+}
+```
+
+### Manual
+
+```tsx
+import { Userflow, useUserflowScreen } from '@userflow-tech/react-native';
+
+Userflow.updateScreen('Profile');
+// or inside a component:
+useUserflowScreen(route.name);
+```
+
+## Element targeting (anchors)
+
+Tooltip steps and ELEMENT client conditions resolve a dashboard selector like
+`#invite-teammates` to a host view. Prefer a plain `testID` (or `nativeID` /
+`accessibilityLabel`) — no SDK hook required. A misspelled or missing anchor can
+mean the tooltip misses **or** a gated flow never starts at all.
+
+```tsx
+import { Pressable, Text } from 'react-native';
+
+function InviteScreen() {
+  return (
+    <Pressable testID="invite-teammates">
+      <Text>Invite teammates</Text>
+    </Pressable>
+  );
+}
+```
+
+Targets inside a `ScrollView` / `FlatList` are scrolled into view automatically.
+`useUserflowScrollContainer` is only needed as an override for scroll libraries
+the fiber walk cannot drive — see [docs/anchoring.md](docs/anchoring.md).
+
+In the Userflow builder, set the MANUAL step selector CSS to `#invite-teammates`
+(or `invite-teammates`). Use `useUserflowAnchor(id)` only when you need an
+explicit override (e.g. a third-party component that does not accept `testID`).
+Full contract, prop priority, missing-target behavior, and duplicate-id rules:
+[docs/anchoring.md](docs/anchoring.md).
+
+## Builder preview & pairing
+
+To preview draft flows from the Userflow builder onto a device (QR / deep link):
+
+1. Register the environment's **`scheme_id`** (e.g. `userflow-257587` — **not**
+   the env UUID) with the `@userflow-tech/expo` config plugin, then **rebuild
+   native** (`npx expo prebuild` / a new development client). Metro reload is
+   not enough.
+2. Call `Userflow.init` (optionally with `pairingEndpoint` / `serverEndpoint`
+   for staging or local stacks) and wrap the tree in `UserflowProvider`.
+3. Open the builder Preview dialog → **Pair a device** → scan/open the QR. The
+   app should show a **Preview mode** banner.
+4. Hit **Preview** in the builder. The draft flow lands on that paired device.
+
+```json
+{
+  "expo": {
+    "plugins": [["@userflow-tech/expo", { "schemeId": "userflow-257587" }]]
+  }
+}
+```
+
+```ts
+await Userflow.init({
+  clientToken: 'ct_...',
+  // Local Userflow stack example:
+  // serverEndpoint: 'http://localhost:40401',
+  // pairingEndpoint: 'http://localhost:40401',
+});
+```
+
+Deep-link / pairing helpers:
+
+| Member                  | Description                                              |
+| ----------------------- | -------------------------------------------------------- |
+| `didHandleURL(url)`     | Handle a one-shot preview deep link (`…://?token=…`).    |
+| `handlePairingUrl(url)` | Handle a pairing deep link (`…://?pairing_token=…`).     |
+| `exitPreview()`         | Disconnect the pairing websocket and leave preview mode. |
+| `PreviewModeBanner`     | Mounted by `UserflowProvider` while paired.              |
+
+Full scheme registration, Linking ownership, and verify commands:
+[docs/deep-linking.md](docs/deep-linking.md). Symptom table:
+[docs/troubleshooting.md](docs/troubleshooting.md#builder-preview--pairing).
+
+## Connection resilience
+
+Recovery from a dropped or silently-dead socket works out of the box:
+
+1. Reconnect ladder on socket `close` / `error`
+2. Adaptive heartbeat with a short reply deadline
+3. Foreground liveness probe when the app returns
+
+`@react-native-community/netinfo` is an optional enhancement for near-instant
+offline→online recovery. Without it, recovery still happens at the next
+heartbeat or foreground return.
+
+## NAVIGATE actions
+
+Flow NAVIGATE buttons open URLs in this order:
+
+1. Host `onNavigate` from `Userflow.init({ onNavigate })` / `Userflow.setOnNavigate` (wins)
+2. http(s) / mailto / tel → Linking
+3. Path-like in-app URLs → Expo Router `push` or React Navigation `navigate`
+4. Otherwise best-effort Linking
+
+Screen tracking ≠ action routing. React Navigation apps need
+`WithUserflowReactNavigation` for in-app NAVIGATE. Expo Router apps need
+`UserflowExpoRouterScreenTracker` from `@userflow-tech/react-native/expo-router`.
+
+## API reference
+
+### `Userflow`
+
+| Member                                                    | Description                                                                    |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `init(config)`                                            | Validate credentials, store config, start lifecycle + network controllers.     |
+| `identify(userId, attributes?, options?)`                 | Identify a user; `options.signature` for identity verification.                |
+| `identifyAnonymous(attributes?, options?)`                | Stable anonymous id via AsyncStorage.                                          |
+| `group(groupId, attributes?, options?)`                   | Associate the current user with a group.                                       |
+| `track(name, attributes?, options?)`                      | Record a custom event (literal attribute values only); `userOnly` skips group. |
+| `reset()`                                                 | Clear identity, client conditions, flow session; disconnect.                   |
+| `teardown()`                                              | Stop AppState / NetInfo / screen-tracking subscriptions.                       |
+| `updateScreen(name)`                                      | Report the active screen (prefer hooks when possible).                         |
+| `setOnNavigate(handler)`                                  | Override or clear the host NAVIGATE handler.                                   |
+| `reportActivity()`                                        | Reset the idle timer; reconnect an idle-suspended socket.                      |
+| `didHandleURL(url)`                                       | Handle a Userflow preview deep link (`…://?token=…`).                          |
+| `handlePairingUrl(url)`                                   | Handle a Builder pairing deep link (`…://?pairing_token=…`; dev builds only).  |
+| `exitPreview()`                                           | Leave Builder preview mode; disconnect the pairing websocket (dev only).       |
+| `inspectPairingDeepLink(url)`                             | Classify a URL as pairing without consuming it; reports rejection reason.      |
+| `isPairingAttempt(reason)`                                | True when a rejection was a recognisable pairing attempt worth reporting.      |
+| `parsePairingDeepLink(url)` / `isUserflowPairingUrl(url)` | Parse / detect a pairing deep link.                                            |
+| `getUserId()`                                             | Current user id, or `null` before identify.                                    |
+| `getAttributes()`                                         | Copy of attributes for the current user.                                       |
+| `getFlowSessionEngine()`                                  | Mid-flow session engine (created lazily; attach runs after identify).          |
+
+### Hooks and components
+
+| Export                                  | Description                                                              |
+| --------------------------------------- | ------------------------------------------------------------------------ |
+| `UserflowProvider`                      | Root overlay host. Does not track screens on its own.                    |
+| `PreviewModeBanner`                     | Shown by the provider while a Builder pairing session is active.         |
+| `useUserflow()`                         | Provider context (`{ engine }`); throws outside the provider.            |
+| `useFlowSessionState()`                 | Reactive view of the active mid-flow session (advanced / custom UI).     |
+| `useUserflowScreen(name)`               | Report the active screen from a React tree.                              |
+| `useUserflowAnchor(id)`                 | Optional override: register a view as a MANUAL target (beats `testID`).  |
+| `useUserflowScrollContainer(onScroll?)` | Optional override: register a `ScrollView` for tooltip scroll-into-view. |
+| `Userflow.setScrollPadding(padding)`    | Sticky chrome insets when scrolling targets into view.                   |
+| `Userflow.setCustomScrollIntoView(fn)`  | Replace scroll-into-view (e.g. unsupported scroll libraries).            |
+
+### Subpath exports
+
+| Import                                    | Provides                                                   |
+| ----------------------------------------- | ---------------------------------------------------------- |
+| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                              |
+| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter` |
+
+### Constants
+
+| Export                              | Meaning                                                          |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| `SDK_VERSION`                       | Package version string injected at build time.                   |
+| `SUSPEND_GRACE_MS`                  | Grace window before background suspend (3s).                     |
+| `SESSION_STALE_AFTER_BACKGROUND_MS` | Clear mid-flow session after this long away (5 min).             |
+| `INACTIVITY_TIMEOUT_MS`             | Foreground idle suspend (5 min; skipped while a flow is active). |
+
+## Guides in this package
+
+| Doc                                                            | Topic                                                      |
+| -------------------------------------------------------------- | ---------------------------------------------------------- |
+| [docs/anchoring.md](docs/anchoring.md)                         | Manual targets, scroll containers, missing-target behavior |
+| [docs/deep-linking.md](docs/deep-linking.md)                   | Builder preview URLs and pairing sessions                  |
+| [docs/identity-verification.md](docs/identity-verification.md) | HMAC signature on your backend                             |
+| [docs/troubleshooting.md](docs/troubleshooting.md)             | Symptom → cause for common integration failures            |
+| [docs/theme-mapping.md](docs/theme-mapping.md)                 | Web → RN theme token mapping (contributor-facing)          |
+
+## What is not available yet
+
+- Banners and embed (inline) surfaces
+- `Userflow.track()` / custom event tracking
+- Codeless / AUTO element targeting
+- `INPUT_VALUE` / `FILLED_IN_INPUT` client conditions
+
+Flows gated on unsupported client conditions stay unknown and **never start**.
+See [docs/troubleshooting.md](docs/troubleshooting.md).

package/docs/anchoring.md

@@ -0,0 +1,264 @@
+# Element targeting (anchors)
+
+How element targeting works in the React Native SDK, and how to wire it in a
+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
+
+## Preferred: tag with `testID`
+
+Dashboard MANUAL selectors store a CSS-like string on `step.selector.css` (or
+`condition.selector.css`). The SDK resolves it with:
+
+```typescript
+// packages/react-native/src/anchors/resolveManualAnchorId.ts
+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`**
+
+| 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">`                     |
+
+Only a plain id (with optional leading `#`) is supported. Compound CSS
+(`.class`, `[attr]`, `div > button`) is **not** parsed — the trimmed string
+minus a leading `#` becomes the registry / prop key literally.
+
+```tsx
+import { Pressable, Text } from 'react-native';
+
+function InviteButton() {
+  return (
+    <Pressable testID="invite-teammates">
+      <Text>Invite teammates</Text>
+    </Pressable>
+  );
+}
+```
+
+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.
+
+### 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:
+
+1. `testID`
+2. `nativeID`
+3. `accessibilityLabel`
+
+### Duplicate ids fail closed
+
+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.
+
+### Only visible screens are scanned
+
+A navigator keeps earlier screens mounted, so the scan skips screens that are
+covered by another one. Without this, an anchor on the screen underneath would
+resolve and measure to a plausible on-screen rect, and reusing one id across two
+stacked screens would fail closed as ambiguous.
+
+Visibility comes from `react-native-screens`:
+
+- **Native stack** (`RNSScreenStack`): every mounted screen reports
+  `activityState === 2`, so the **last** sibling branch is treated as the top
+  one (including iOS `modal` / `transparentModal`, which render as
+  `RNSModalScreen`).
+- **Container navigators** (tabs, etc.): `activityState` picks the focused
+  branch(es). When several branches are active (multi-pane), all stay
+  scannable — last-sibling fallback is stack-only so visible panes are not
+  pruned.
+
+Views outside the screen stack — tab bars, headers, other global chrome — are
+always scanned. Apps without `react-native-screens` prune nothing and behave as
+before.
+
+`useUserflowAnchor` is checked before the scan and is not screen-scoped, so it
+can still pin a target on a covered screen when you need that.
+
+### Rows inside virtualized lists
+
+`FlatList` / `SectionList` only mount rows near the viewport, so a `testID` on a
+far-off row does not exist in the tree yet and resolves as **missing** — the same
+way `document.querySelector` cannot see an unrendered row on web. Anchor to
+something already mounted, or keep the target row rendered.
+
+### Third-party / composite components
+
+If a wrapper carries `testID` but does not forward it to a native host, the SDK
+still finds it and measures the shallowest host descendant under that composite.
+
+## Override: `useUserflowAnchor`
+
+Use the hook when you need an explicit override — for example a library
+component that does not accept `testID`, or when the same string appears on
+multiple views and you must pin one:
+
+```typescript
+function useUserflowAnchor(id: string): React.RefCallback<View>;
+```
+
+```tsx
+import { Pressable, Text } from 'react-native';
+import { useUserflowAnchor } from '@userflow-tech/react-native';
+
+function InviteButton() {
+  const inviteRef = useUserflowAnchor('invite-teammates');
+  return (
+    <Pressable ref={inviteRef}>
+      <Text>Invite teammates</Text>
+    </Pressable>
+  );
+}
+```
+
+Notes:
+
+- Empty / falsy `id` never registers.
+- On unmount or ref detach, the host is unregistered.
+- Changing `id` re-registers under the new key.
+- A registered hook host **beats** a fiber `testID` match for the same id.
+- Text-only or pure-JS components without a native handle will not measure.
+
+## `useUserflowScrollContainer` (optional override)
+
+For `testID` anchors inside a `ScrollView` / `FlatList`, the SDK discovers the
+scroll ancestor via the fiber walk and scrolls the target into view
+automatically — no hook required.
+
+Register a scroll container explicitly when:
+
+- The scroller is a library the fiber walk cannot drive (some FlashList /
+  Reanimated setups), or
+- The target is only registered via `useUserflowAnchor` without a discoverable
+  fiber
+
+```tsx
+import { Pressable, ScrollView, Text } from 'react-native';
+import { useUserflowScrollContainer } from '@userflow-tech/react-native';
+
+function InviteScreen() {
+  const scroll = useUserflowScrollContainer();
+
+  return (
+    <ScrollView {...scroll}>
+      <Pressable testID="invite-teammates">
+        <Text>Invite teammates</Text>
+      </Pressable>
+    </ScrollView>
+  );
+}
+```
+
+You can also replace scroll behavior entirely with
+`Userflow.setCustomScrollIntoView(fn)`, or reserve space for sticky chrome with
+`Userflow.setScrollPadding({ top, bottom, left, right })` — both mirror the web
+SDK.
+
+Screen tracking ≠ scroll registration. Only `ScrollView`s you pass through this
+hook participate in the registry override path.
+
+## 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.
+
+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.
+
+## When target element is clicked
+
+Builder “When target element is clicked” maps to the step’s `actions` list (same
+as web). While a tooltip target is measured, `actions` is non-empty, and
+`tooltipTargetBlocked` is false, the SDK observes taps on the **measured target
+rect** via a pass-through bridge around app content (`TargetPressBridge` in
+`UserflowProvider`).
+
+- The app control still receives the press (no overlay hole `Pressable`).
+- A tap that starts and ends inside the target within a small movement slop
+  runs `engine.handleActions(step.actions)` — typically `GO_TO_STEP` / close /
+  navigate, same executor as tooltip buttons.
+- 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).
+
+## Missing-target behavior
+
+When a tooltip cannot resolve / measure its target:
+
+1. **Before first measure** — renders nothing (blank overlay).
+2. **Waiting** — centered “Looking for target…” spinner.
+3. **After** `theme.tooltipMissingToleranceSeconds` (default **5s**) — the
+   theme’s `tooltipMissingBehavior` applies:
+
+| Behavior         | After tolerance                                                                |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `FLAG` (default) | Centered “Target not found” card; keeps remeasuring slowly for recovery        |
+| `ERROR`          | Same missing UI as `FLAG`                                                      |
+| `BUBBLE`         | Centered card with normal step content (modal-like fallback)                   |
+| `END`            | Hides the flow UI (`null`); in draft/preview mode shows the missing UI instead |
+
+Ambiguous ids, missing hosts, and zero-width/height measures all count as
+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.
+Unsupported states (`CLICK`, `DISABLED`, …) and `AUTO` selectors stay unknown —
+see [troubleshooting.md](troubleshooting.md).
+
+## How the fiber scan works (brief)
+
+`UserflowProvider` wraps the app in a class-component scan root that exposes its
+production `_reactInternals` fiber. When a MANUAL selector is not in the
+explicit registry, the SDK walks that subtree (bounded DFS, skipping covered
+screens), matches the id on `memoizedProps`, and measures the host via a
+feature-detected
+`measureInWindow` chain (Paper host method, Fabric
+`nativeFabricUIManager`, then `UIManager` by tag). Accessors never throw — an RN
+internals rename degrades to not-found rather than crashing the host app.
+
+The walk is capped so a dense tree cannot stall the JS thread. Hitting the cap
+warns (every time in `__DEV__`, once per process in production) and otherwise
+looks like a missing anchor — prefer
+[`useUserflowAnchor`](#override-useuserflowanchor) for targets the scan cannot
+reach.
+
+The Userflow overlay is a _sibling_ of the scan root, so SDK-owned `testID`s
+(`userflow-tooltip-surface`, …) cannot self-match.
+
+## See also
+
+- [troubleshooting.md](troubleshooting.md) — “flow never appeared” checklist
+- [theme-mapping.md](theme-mapping.md) — chrome tokens that affect tooltip UI
+- Repo `docs/client-conditions.md` (monorepo only) — track / toggle protocol internals