@userflow-tech/react-native 0.3.1 → 0.4.1

package/README.md

@@ -1,40 +1,53 @@
 # `@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.
+modals, and banners 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`).
+> Early development. APIs may change.
 
 ## Requirements
 
-Declared minimums: React `>=18.2.0`, React Native `>=0.74.0`. This package's
-test suite runs on React Native 0.81 / React 19.1. The TinyTime sample app in
-this repo runs on Expo SDK 57 / React Native 0.86. Expo Go is not supported.
-
-Install AsyncStorage, WebView, and (on bare React Native) device-info in the
-**app**, even though this package also depends on them. Expo SDK 54 and later
-autolink transitive native modules. Bare React Native, and Expo SDK 53 and
-older, only autolink packages listed in the app's own `package.json`. A direct
-install also picks a version that matches the app's React Native.
-
-| Package                                     | Required?                | Why                                                                                             | If missing                                                                                                                            |
-| ------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `react`, `react-native`                     | Yes                      | Host runtime.                                                                                   | The app cannot load the SDK.                                                                                                          |
-| `@react-native-async-storage/async-storage` | Yes, install in the app  | Anonymous user id and the pairing device id.                                                    | `identifyAnonymous()` throws. Pairing keeps a device id in memory for the session. A dev-only warning is logged from `Userflow.init`. |
-| `react-native-device-info`                  | Yes on bare React Native | Host app `app_version` / `app_build`. Expo reads `expo-application` / `expo-constants` instead. | Those attributes are omitted. A dev-only warning is logged on bare React Native.                                                      |
-| `react-native-view-shot` `>=5.0.0`          | Yes (peer)               | Builder element-selection screenshots.                                                          | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`.                                                      |
-| `react-native-webview` `>=13.8.0`           | Yes, install in the app  | Evaluate JavaScript and WebView banners.                                                        | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`.                                                         |
-| `react-native-safe-area-context`            | Optional                 | Insets for modal and tooltip surfaces.                                                          | One dev warning. Flow cards use the device's initial safe-area insets, or zero when those are unavailable.                            |
-| `@react-navigation/native`                  | Optional                 | Screen tracking and NAVIGATE routing (React Navigation).                                        | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                    |
-| `expo-router`                               | Optional                 | Screen tracking and NAVIGATE routing (Expo Router).                                             | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                    |
-| `@react-native-community/netinfo`           | Optional                 | Instant offline→online reconnect.                                                               | Recovery still runs on the heartbeat and when the app returns to the foreground.                                                      |
-| `expo-secure-store`                         | Optional                 | Persist the Builder pairing JWT in Keychain/Keystore.                                           | The pairing token stays in memory and is lost when the process ends.                                                                  |
+Declared minimums: React `>=18.2.0`, React Native `>=0.76.0`. React Native
+0.74 and 0.75 cannot install this SDK: `react-native-view-shot` 5.x, which
+Builder element selection needs, requires React Native 0.76 or later. The SDK
+is tested on React Native 0.81 / React 19.1 and on Expo SDK 57 / React Native
+0.86. Expo Go is not supported.
+
+`@react-native-async-storage/async-storage` is the only native module this
+package depends on, so npm installs it. `react-native-webview` and
+`react-native-view-shot` are required peers. npm 7+ and pnpm install required
+peers. Yarn 1 and `npm install --legacy-peer-deps` do not, which is why the
+install commands list WebView and view-shot explicitly.
+`react-native-device-info` is an optional peer for bare React Native.
+
+Install those packages in the **app** as well. Expo SDK 54 and later autolink
+native modules found anywhere in the tree. Bare React Native, and Expo SDK 53
+and older, only autolink packages listed in the app's own `package.json`. A
+direct install also picks a version that matches the app's React Native, inside
+the ranges below.
+
+| Package                                                 | Kind                             | Why                                                                                             | If missing                                                                                                                                                                                                                         |
+| ------------------------------------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `react`, `react-native` `>=0.76.0`                      | Required peers                   | Host runtime.                                                                                   | The app cannot load the SDK. React Native older than 0.76 fails install (`ERESOLVE`) because view-shot 5.x requires it.                                                                                                            |
+| `@react-native-async-storage/async-storage` `>=1.23 <3` | Dependency                       | Anonymous user id and the pairing device id.                                                    | `identifyAnonymous()` throws. Pairing keeps a device id in memory for the session. A dev-only warning is logged from `Userflow.init`.                                                                                              |
+| `react-native-device-info` `>=11 <16`                   | Optional peer, bare React Native | Host app `app_version` / `app_build`. Expo reads `expo-application` / `expo-constants` instead. | Those attributes are omitted. A dev-only warning is logged on bare React Native.                                                                                                                                                   |
+| `react-native-view-shot` `^5.0.0`                       | Required peer                    | Builder element-selection screenshots.                                                          | The picker has no screenshot. A dev-only warning is logged from `Userflow.init`. Version 6.x is outside the tested range and requires React Native 0.80 or later.                                                                  |
+| `react-native-webview` `>=13.8.0 <14`                   | Required peer                    | Evaluate JavaScript and WebView banners.                                                        | Those surfaces do not run. A dev-only warning is logged from `Userflow.init`.                                                                                                                                                      |
+| `react-native-safe-area-context` `>=4 <6`               | Optional peer                    | Insets for banners, flow cards, and Builder bars.                                               | In development, `Userflow.init` warns once. Those surfaces draw under the status bar and home indicator. With the package installed but no `<SafeAreaProvider>`, cards use the device's initial insets and log a separate warning. |
+| `@react-navigation/native`                              | Optional peer                    | Screen tracking and NAVIGATE routing (React Navigation).                                        | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                                                                                                                 |
+| `expo-router`                                           | Optional peer                    | Screen tracking and NAVIGATE routing (Expo Router).                                             | Report screens yourself with `updateScreen` / `useUserflowScreen`.                                                                                                                                                                 |
+| `@react-native-community/netinfo` `>=11 <13`            | Optional peer                    | Instant offline→online reconnect.                                                               | Recovery still runs on the heartbeat and when the app returns to the foreground. If the JavaScript package is installed but `RNCNetInfo` is not in the binary, the SDK skips it instead of showing a red screen.                   |
+| `expo-secure-store`                                     | Optional peer                    | Persist the Builder pairing JWT in Keychain/Keystore.                                           | The pairing token stays in memory and is lost when the process ends. The SDK loads it only when the `ExpoSecureStore` native module is registered.                                                                                 |
 
 Optional peers are declared `optional: true` in `peerDependenciesMeta`, so
-package managers will not warn if you skip them. Required peers (not marked
-optional) will warn — or fail the install — if they are missing.
+package managers do not warn if you skip them.
+
+A clean npm install prints no warning about optional peers, so install
+`react-native-safe-area-context` and NetInfo yourself when you want the behavior
+in the table. An app that already depends
+on an older major (view-shot 4.0.3, NetInfo 9.x, safe-area 3.x, WebView 13.6.x
+or 14.x) fails install with `ERESOLVE`.
 
 ### Expo Go is not supported
 
@@ -47,35 +60,8 @@ Use an **Expo development build** (or bare React Native). In development,
 
 ## Install
 
-### Access
-
-Packages publish to the private `@userflow-tech` npm org. Userflow adds the
-client's npm user or organization to a **read-only team** on that org. The
-client then creates a **granular access token** on npm (Read-only, limited to
-`@userflow-tech`). A `404` from `npm install` or `npm view @userflow-tech/react-native`
-means the token is missing, or that user or org is not on the team. npm uses
-404 for a private package the caller cannot see.
-
-### npm, Yarn, and CI
-
-npm and Yarn 1 read `.npmrc`. Do not commit the token:
-
-```ini
-@userflow-tech:registry=https://registry.npmjs.org/
-//registry.npmjs.org/:_authToken=${NPM_TOKEN}
-```
-
-Yarn 2 and later ignore `.npmrc`. Add this to `.yarnrc.yml` instead:
-
-```yaml
-npmScopes:
-  userflow-tech:
-    npmRegistryServer: 'https://registry.npmjs.org'
-    npmAuthToken: '${NPM_TOKEN}'
-```
-
-Set `NPM_TOKEN` in the environment that installs dependencies: a local shell,
-CI, and EAS (an EAS secret named `NPM_TOKEN`, available to the install step).
+The package is public on npm. No token, `.npmrc`, or `.yarnrc.yml` setup is
+needed with any package manager.
 
 ### Packages
 
@@ -88,11 +74,25 @@ npm install @userflow-tech/react-native @react-native-async-storage/async-storag
 cd ios && pod install
 ```
 
-`react-native-view-shot` is a **required peer** (`>=5.0.0`). It is a native
-module — rebuild after install (a Metro reload is not enough). On Expo SDK 54,
+`react-native-webview` and `react-native-view-shot` (`^5.0.0`) are **required
+peers**. npm 7+ and pnpm install them. Yarn 1 and
+`npm install --legacy-peer-deps` do not, so the commands above install them in
+the app. Both are native modules — rebuild after install (a Metro reload is not
+enough). On Expo SDK 54,
 unpinned `npx expo install react-native-view-shot` resolves **4.0.3**, which
-does not satisfy the peer. Pin `^5.0.0` as in the command above. If `expo doctor`
-reports that pin, exclude it from Expo's version check:
+does not satisfy the peer. Pin `^5.0.0` as in the command above. If the app
+already depends on 4.0.3, that same command is what fixes it: installing the
+SDK alone fails with
+
+```text
+npm error Found: react-native-view-shot@4.0.3
+npm error peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native
+```
+
+Do not retry with `--force` or `--legacy-peer-deps`. That installs the SDK and
+leaves 4.0.3 in place. If that already happened, `Userflow.init` warns in
+development and names the installed version. If `expo doctor`
+reports the `^5.0.0` pin, exclude it from Expo's version check:
 
 ```json
 {
@@ -114,10 +114,6 @@ npx expo install react-native-safe-area-context @react-native-community/netinfo
 # and either expo-router or @react-navigation/native, depending on your router
 ```
 
-For local tarball installs from this monorepo, pack with `pnpm pack:all` at the
-repo root and install the single `@userflow-tech/react-native` tarball. Steps:
-`docs/local-testing.md` in the monorepo.
-
 ### Install with an AI agent
 
 Cursor, Claude Code, and other agents that read Agent Skills can do this
@@ -143,7 +139,7 @@ Claude Code loads it from the plugin:
 import { Userflow, UserflowProvider } from '@userflow-tech/react-native';
 
 await Userflow.init({
-  clientToken: 'ct_...', // from the Userflow dashboard → Environments. Never an esk_ secret key.
+  clientToken: 'ct_...', // from Settings → Environments in the Userflow dashboard. Never an esk_ secret key.
   // serverEndpoint: 'https://e.userflow.com', // default (US). EU: 'https://e.eu.userflow.com'
   // pairingEndpoint: 'https://e.userflow.com', // default; pairing stays on the US host
 });
@@ -162,6 +158,17 @@ NetInfo subscriptions). Call `Userflow.reset()` on logout to clear identity and
 disconnect. `reset()` does not apply a new `clientToken` or endpoint; restart
 the app to change those.
 
+### `init` options
+
+| Option            | Default                  | Description                                                                                                  |
+| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `clientToken`     | —                        | **Required.** The `ct_…` client token from Settings → Environments.                                          |
+| `serverEndpoint`  | `https://e.userflow.com` | Userflow host. EU environments use `https://e.eu.userflow.com`.                                              |
+| `pairingEndpoint` | `https://e.userflow.com` | Builder pairing host. Stays on the US host for EU environments too.                                          |
+| `onNavigate`      | —                        | Handler for flow NAVIGATE actions. Wins over React Navigation, Expo Router, and Linking. See NAVIGATE below. |
+| `appVersion`      | Read from the native app | Override the host app version sent as `app_version`.                                                         |
+| `appBuild`        | Read from the native app | Build number sent as `app_build`, paired with `appVersion`.                                                  |
+
 ### Where to put `init`, `identify`, and `UserflowProvider`
 
 Call `Userflow.init` once, as early as you can, from the root component
@@ -231,14 +238,14 @@ to the device's initial insets:
 
 ### 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()`                                                                                                                            |
-| `updateUser`                     | **Throws** `Call Userflow.init() before updateUser()`  | **Throws** `Call Userflow.identify() before updateUser()`                                                                                                                       |
-| `updateGroup`                    | **Throws** `Call Userflow.init() before updateGroup()` | **Throws** `Call Userflow.identify() before updateGroup()`; also requires a prior `group()`                                                                                     |
-| `track`                          | **Throws** `Call Userflow.init() before track()`       | **Throws** `Call Userflow.identify() before track()`. Network, rate-limit, and unexpected SDK errors are isolated (the promise resolves; see [isolation.md](docs/isolation.md)) |
-| `updateScreen`                   | Silently buffers; included on the next channel join    | Silently buffers                                                                                                                                                                |
+| 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()`                                                                                                                                                                          |
+| `updateUser`                     | **Throws** `Call Userflow.init() before updateUser()`  | **Throws** `Call Userflow.identify() before updateUser()`                                                                                                                                                                     |
+| `updateGroup`                    | **Throws** `Call Userflow.init() before updateGroup()` | **Throws** `Call Userflow.identify() before updateGroup()`; also requires a prior `group()`                                                                                                                                   |
+| `track`                          | **Throws** `Call Userflow.init() before track()`       | **Throws** `Call Userflow.identify() before track()`. Network, rate-limit, and unexpected SDK errors are isolated (the promise resolves; see [isolation.md](https://unpkg.com/@userflow-tech/react-native/docs/isolation.md)) |
+| `updateScreen`                   | Silently buffers; included on the next channel join    | Silently buffers                                                                                                                                                                                                              |
 
 Other rules:
 
@@ -255,7 +262,7 @@ Other rules:
   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).
+  [docs/identity-verification.md](https://unpkg.com/@userflow-tech/react-native/docs/identity-verification.md).
 
 ## Localization
 
@@ -288,7 +295,7 @@ unmount or crash the host tree. `init` / `identify` still throw — a swallowed
 identify would look like success. Native crashes and errors in **your** children
 of `UserflowProvider` are out of scope.
 
-Details: [docs/isolation.md](docs/isolation.md).
+Details: [docs/isolation.md](https://unpkg.com/@userflow-tech/react-native/docs/isolation.md).
 
 ## Screen tracking
 
@@ -381,13 +388,13 @@ function InviteScreen() {
 
 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).
+the fiber walk cannot drive — see [docs/anchoring.md](https://unpkg.com/@userflow-tech/react-native/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).
+[docs/anchoring.md](https://unpkg.com/@userflow-tech/react-native/docs/anchoring.md).
 
 ## Builder preview & pairing
 
@@ -432,8 +439,8 @@ Deep-link / pairing helpers:
 | `PreviewModeBanner`     | Mounted by `UserflowProvider` while paired. The top bar shows at once for a preview link, stays hidden for an element-selection link and after any pick until the next preview, and waits briefly on a link with no purpose. |
 
 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).
+[docs/deep-linking.md](https://unpkg.com/@userflow-tech/react-native/docs/deep-linking.md). Symptom table: the "Builder preview / pairing" section of
+[docs/troubleshooting.md](https://unpkg.com/@userflow-tech/react-native/docs/troubleshooting.md).
 
 ## Connection resilience
 
@@ -464,33 +471,35 @@ Screen tracking ≠ action routing. React Navigation apps need
 
 ### `Userflow`
 
-| Member                                                    | Description                                                                                                                                                        |
-| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `init(config)`                                            | Validate credentials, store config, start lifecycle + network controllers.                                                                                         |
-| `identify(userId, attributes?, options?)`                 | Identify a user; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build` from init; `options.signature` for identity verification.           |
-| `identifyAnonymous(attributes?, options?)`                | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build`.                                               |
-| `group(groupId, attributes?, options?)`                   | Associate the current user with a group.                                                                                                                           |
-| `updateUser(attributes?)`                                 | Upsert attributes for the current user without re-identifying.                                                                                                     |
-| `updateGroup(attributes?, options?)`                      | Upsert group / membership attributes without re-grouping.                                                                                                          |
-| `track(name, attributes?, options?)`                      | Record a custom event (literal attribute values only); `userOnly` skips group. Misuse (`UserflowAuthError`) rejects; network / rate-limit / SDK bugs are isolated. |
-| `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=…`). Works in every build; the signed JWT gates the session.                                               |
-| `exitPreview()`                                           | Leave Builder preview mode; disconnect the pairing websocket. Works in every build.                                                                                |
-| `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).                                                                                              |
-| `getHostAppVersion()`                                     | Host app native version cached at init, or `null` before init / when unavailable.                                                                                  |
-| `getDeviceContext()`                                      | Platform metadata cached during `init` (`sdk`, `deviceOs`, `deviceType`), or `null` before init.                                                                   |
-| `logHostAppVersion()`                                     | Log the host app's native version (not `SDK_VERSION`) and platform OS. Uses bundled device-info on bare RN.                                                        |
-| `logDeviceContext()`                                      | Log cached user-attribute values (`sdk` / `device_os` / `device_type`). Requires `init`.                                                                           |
+| Member                                     | Description                                                                                                                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `init(config)`                             | Validate credentials, store config, start lifecycle + network controllers.                                                                                         |
+| `identify(userId, attributes?, options?)`  | Identify a user; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build` from init; `options.signature` for identity verification.           |
+| `identifyAnonymous(attributes?, options?)` | Stable anonymous id via AsyncStorage; auto-sets `sdk` / `device_os` / `device_type` and `app_version` / `app_build`.                                               |
+| `group(groupId, attributes?, options?)`    | Associate the current user with a group.                                                                                                                           |
+| `updateUser(attributes?)`                  | Upsert attributes for the current user without re-identifying.                                                                                                     |
+| `updateGroup(attributes?, options?)`       | Upsert group / membership attributes without re-grouping.                                                                                                          |
+| `track(name, attributes?, options?)`       | Record a custom event (literal attribute values only); `userOnly` skips group. Misuse (`UserflowAuthError`) rejects; network / rate-limit / SDK bugs are isolated. |
+| `reset()`                                  | Clear identity, the stored anonymous id, client conditions, and flow and banner sessions; 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=…`). Works in every build; the signed JWT gates the session.                                               |
+| `exitPreview()`                            | Leave Builder preview mode; disconnect the pairing websocket. Works in every build.                                                                                |
+| `setScrollPadding(padding)`                | Sticky header/footer insets used when scrolling tooltip targets into view.                                                                                         |
+| `setCustomScrollIntoView(fn)`              | Replace scroll-into-view (e.g. unsupported scroll libraries). Pass `null` to restore the default.                                                                  |
+| `setSurfaceInteractionBlocking(enabled)`   | `true` (default) blocks taps on the app under tooltip backdrops. `false` lets them through. Modals always block.                                                   |
+| `setEvalJsContext(values)`                 | Values exposed to Evaluate JavaScript as `window.userflowContext.host`. Replaces the previous values.                                                              |
+| `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).                                                                                              |
+| `getBannerSessionEngine()`                 | Banner session engine (created lazily; attach runs after identify).                                                                                                |
+| `getHostAppVersion()`                      | Host app native version cached at init, or `null` before init / when unavailable.                                                                                  |
+| `getDeviceContext()`                       | Platform metadata cached during `init` (`sdk`, `deviceOs`, `deviceType`), or `null` before init.                                                                   |
+| `logHostAppVersion()`                      | Log the host app's native version (not `SDK_VERSION`) and platform OS. Uses bundled device-info on bare RN.                                                        |
+| `logDeviceContext()`                       | Log cached user-attribute values (`sdk` / `device_os` / `device_type`). Requires `init`.                                                                           |
 
 ### Hooks and components
 
@@ -503,8 +512,19 @@ Screen tracking ≠ action routing. React Navigation apps need
 | `useUserflowScreen(name)`               | Report the active screen from a React tree.                                                                                                                                                                                              |
 | `useUserflowAnchor(id)`                 | Optional override: register a view as a MANUAL target (beats `userflowId` / `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).                                                                                                                                                                            |
+| `EmbedBannerPlaceholder`                | Slot for a banner placed on an element (`<EmbedBannerPlaceholder id="welcome-banner" />` matches the selector `#welcome-banner`). Renders nothing until a matching banner is active. Top and bottom banners ignore it.                   |
+
+### Pairing helpers
+
+Named exports, not members of `Userflow`. Use them when your app owns `Linking`
+and forwards URLs itself.
+
+| Export                        | Description                                                               |
+| ----------------------------- | ------------------------------------------------------------------------- |
+| `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)`   | Parse a pairing deep link.                                                |
+| `isUserflowPairingUrl(url)`   | Detect a pairing deep link.                                               |
 
 ### Subpath exports
 
@@ -524,20 +544,22 @@ Screen tracking ≠ action routing. React Navigation apps need
 
 ## Guides in this package
 
-| Doc                                                            | Topic                                                       |
-| -------------------------------------------------------------- | ----------------------------------------------------------- |
-| [docs/anchoring.md](docs/anchoring.md)                         | Manual targets, scroll containers, missing-target behavior  |
-| [docs/isolation.md](docs/isolation.md)                         | What “isolated as possible” means; overlay + `track` guards |
-| [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)           |
+These guides also ship in the package, under
+`node_modules/@userflow-tech/react-native/docs/`.
+
+| Doc                                                                                                          | Topic                                                       |
+| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| [docs/anchoring.md](https://unpkg.com/@userflow-tech/react-native/docs/anchoring.md)                         | Manual targets, scroll containers, missing-target behavior  |
+| [docs/isolation.md](https://unpkg.com/@userflow-tech/react-native/docs/isolation.md)                         | What “isolated as possible” means; overlay + `track` guards |
+| [docs/deep-linking.md](https://unpkg.com/@userflow-tech/react-native/docs/deep-linking.md)                   | Builder preview URLs and pairing sessions                   |
+| [docs/identity-verification.md](https://unpkg.com/@userflow-tech/react-native/docs/identity-verification.md) | HMAC signature on your backend                              |
+| [docs/troubleshooting.md](https://unpkg.com/@userflow-tech/react-native/docs/troubleshooting.md)             | Symptom → cause for common integration failures             |
 
 ## Experimental
 
 - AUTO / codeless element targeting (exact-id fast path + scored matcher;
   scored path needs Babel full mode to populate the auto-anchor registry).
-  See [docs/anchoring.md](docs/anchoring.md).
+  See [docs/anchoring.md](https://unpkg.com/@userflow-tech/react-native/docs/anchoring.md).
 - Build-time stamping with `@userflow-tech/react-native/babel-plugin`. Jest
   runs the plugin too, which changes snapshots. Read
   [Babel plugin and snapshot tests](#babel-plugin-and-snapshot-tests) before
@@ -546,10 +568,14 @@ Screen tracking ≠ action routing. React Navigation apps need
 ## Install diagnostics
 
 In development, the first `Userflow.init` checks native module registration and
-logs one warning when something the SDK needs is not linked. It does not
-`require` an unlinked package. Rebuild the native app after fixing the list; a
-Metro reload is not enough. The warning looks like this (only the missing lines
-are included):
+whether `react-native-safe-area-context` is installed. Missing native modules
+share one warning. A missing safe-area package gets its own warning, because
+flows still run and draw under the status bar. It does not `require` an
+unlinked package (including NetInfo, whose import throws when `RNCNetInfo` is
+absent). Rebuild the native app after fixing a native-module line; a Metro
+reload is not enough. Installing safe-area-context also needs a rebuild, then a
+`<SafeAreaProvider>` around the app. The warnings look like this (only the
+missing lines are included):
 
 ```text
 [Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):
@@ -557,7 +583,12 @@ are included):
 - react-native-view-shot is not linked, so Builder element selection gets no screenshot. Install react-native-view-shot@^5.0.0 and rebuild. On Expo SDK 54, pin ^5.0.0; an unpinned npx expo install resolves 4.0.3.
 - react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.
 - react-native-device-info is not linked, so app_version and app_build are not sent. npm install react-native-device-info, then rebuild.
-See docs/troubleshooting.md.
+See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
+```
+
+```text
+[Userflow] react-native-safe-area-context is not installed, so banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.
+See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
 ```
 
 Passing an environment secret key as `clientToken` throws:
@@ -572,8 +603,11 @@ Pairing stays on `https://e.userflow.com`.
 
 `expo prebuild` warns when the config plugin has no `schemeId`, when
 `react-native-view-shot` is missing or older than 5, and (on Expo SDK 53 and
-older) when AsyncStorage or WebView is not a direct dependency. Passing an
-environment UUID as `schemeId` fails the prebuild:
+older) when AsyncStorage, WebView, or safe-area-context is not a direct
+dependency. Expo SDK 54 and later autolink safe-area-context when another
+package such as Expo Router brought it in, so prebuild stays quiet in that
+case. `Userflow.init` still warns when the package itself cannot be loaded.
+Passing an environment UUID as `schemeId` fails the prebuild:
 
 ```text
 [@userflow-tech/react-native] schemeId "550e8400-e29b-41d4-a716-446655440000" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.
@@ -681,4 +715,4 @@ the files it lists, not the components a test renders.
 - `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).
+See [docs/troubleshooting.md](https://unpkg.com/@userflow-tech/react-native/docs/troubleshooting.md).

package/docs/anchoring.md

@@ -16,7 +16,7 @@ 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
+// src/anchors/resolveManualAnchorId.ts
 return trimmed.startsWith('#') ? trimmed.slice(1) : trimmed;
 ```
 
@@ -318,7 +318,7 @@ 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.
+hole seal is unchanged.
 
 When a tooltip step has `backdrop: false`, the cutout still mounts with dim
 opacity `0` so interaction blocking applies without a visible dim.
@@ -341,7 +341,7 @@ rect** via a pass-through bridge around app content (`TargetPressBridge` in
 ELEMENT `CLICK` / `NOT_CLICK` auto-start conditions use the same bridge
 (`elementTapMonitor`) and do not steal the press either. `MOUSEDOWN` and
 `DISABLED` conditions are still unsupported — see
-[client-conditions.md](client-conditions.md) / [troubleshooting.md](troubleshooting.md).
+[troubleshooting.md](troubleshooting.md).
 
 ## Missing-target behavior
 
@@ -405,4 +405,3 @@ The Userflow overlay is a _sibling_ of the scan root, so SDK-owned `testID`s
 
 - [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