@userflow-tech/react-native 0.1.0 → 0.2.0

package/README.md

@@ -9,18 +9,21 @@ release for every content change.
 
 ## 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.             |
+| Peer / dependency                           | Required?  | Why                                                                      |
+| ------------------------------------------- | ---------- | ------------------------------------------------------------------------ |
+| `react`, `react-native`                     | Yes        | Host runtime.                                                            |
+| `@react-native-async-storage/async-storage` | Yes (dep)  | Persists the anonymous user id. Installed with this package.             |
+| `react-native-device-info`                  | Yes (dep)  | Reads the host app store version (bundled; native rebuild required).     |
+| `react-native-view-shot`                    | Yes (peer) | Builder in-app picker screenshots. Native module; rebuild after install. |
+| `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.
+package managers will not warn if you skip them. Required peers (not marked
+optional) will warn — or fail the install — if they are missing.
 
 ### Expo Go is not supported
 
@@ -29,15 +32,41 @@ compatible with Expo Go.
 
 ## Install
 
+Packages publish to the private `@userflow-tech` npm org. Create a **granular
+access token** on npm (Read-only, limited to `@userflow-tech`) and put it in
+the host app’s `.npmrc` via an env var — do not commit the token:
+
+```ini
+@userflow-tech:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
 ```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
+# Expo (dev build)
+npx expo install @userflow-tech/react-native react-native-view-shot@^5.0.0
 
 # Bare React Native
-npm install @userflow-tech/react-native @react-native-async-storage/async-storage
+npm install @userflow-tech/react-native react-native-view-shot
 cd ios && pod install
 ```
 
+`react-native-view-shot` is a **required peer** (`>=5.0.0`). It is a native
+module — rebuild after install (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 and breaks New Architecture / bridgeless. Pin
+`^5.0.0` (or `@latest`) as in the command above.
+
+`@react-native-async-storage/async-storage` and `react-native-device-info` are
+dependencies of this package and are installed automatically with a normal npm
+install. After adding or upgrading the SDK, rebuild the native app (`cd ios &&
+pod install`, then run again). If autolinking misses a bundled native module
+(common with local `file:` links), install it in the host app explicitly:
+
+```bash
+npm install @react-native-async-storage/async-storage react-native-device-info
+cd ios && pod install   # iOS
+```
+
 Optional peers as needed:
 
 ```bash
@@ -45,11 +74,8 @@ 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 (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:
+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.
 
 ## Quick start
@@ -90,12 +116,14 @@ 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                                     |
+| 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()`                                        |
+| `updateScreen`                   | Silently buffers; included on the next channel join    | Silently buffers                                                                            |
 
 Other rules:
 
@@ -110,6 +138,13 @@ Other rules:
 
 ## Screen tracking
 
+Each accepted screen/path also sends a `screen_viewed` event after identify
+(with `screen_name` or `screen_path`). That is a second client message alongside
+`UpdateClientContext`; both count toward the 100/min cap. Modal / sheet
+presentations are skipped (Expo Router also watches navigation state, so overlays
+that do not change the pathname are skipped too). Returning from background past
+the lifecycle grace window re-fires the current screen.
+
 ### Expo Router
 
 Mount `UserflowExpoRouterScreenTracker` from the `@userflow-tech/react-native/expo-router`
@@ -196,19 +231,19 @@ Full contract, prop priority, missing-target behavior, and duplicate-id rules:
 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.
+   the env UUID) with the `@userflow-tech/react-native` 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.
+   app should show a **Preview mode** top bar.
 4. Hit **Preview** in the builder. The draft flow lands on that paired device.
 
 ```json
 {
   "expo": {
-    "plugins": [["@userflow-tech/expo", { "schemeId": "userflow-257587" }]]
+    "plugins": [["@userflow-tech/react-native", { "schemeId": "userflow-257587" }]]
   }
 }
 ```
@@ -224,12 +259,12 @@ await Userflow.init({
 
 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.              |
+| 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-bleed top bar). |
 
 Full scheme registration, Linking ownership, and verify commands:
 [docs/deep-linking.md](docs/deep-linking.md). Symptom table:
@@ -264,41 +299,47 @@ 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; `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).          |
+| 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.                                                                           |
+| `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).                                                                                    |
+| `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
 
-| 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).            |
+| Export                                  | Description                                                                              |
+| --------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `UserflowProvider`                      | Root overlay host. Does not track screens on its own.                                    |
+| `PreviewModeBanner`                     | Shown by the provider as a full-bleed top bar 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
 
@@ -326,11 +367,16 @@ Screen tracking ≠ action routing. React Navigation apps need
 | [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)          |
 
+## 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).
+
 ## 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**.

package/app.plugin.js

@@ -0,0 +1,13 @@
+// Expo loads this file as the config plugin entry.
+// Hosts register: plugins: [['@userflow-tech/react-native', { schemeId: 'userflow-…' }]]
+const fs = require('node:fs');
+const path = require('node:path');
+
+const vendored = path.join(__dirname, 'expo-plugin/withUserflow.js');
+const workspace = path.join(__dirname, '../expo/build/withUserflow.js');
+
+if (fs.existsSync(vendored)) {
+  module.exports = require(vendored);
+} else {
+  module.exports = require(workspace);
+}

package/babel-plugin/index.d.ts

@@ -0,0 +1,43 @@
+import type { PluginObj, PluginPass, types as BabelTypes } from '@babel/core';
+export interface UserflowBabelPluginOptions {
+    rootDir?: string;
+    allowlist?: string[];
+    injectUfidProp?: boolean;
+    exclude?: string[];
+    /**
+     * When true, only stamp `nativeID` (and `collapsable={false}` when needed).
+     * Skips the SDK import, `__ufRef` helper, ref wrapping, hints, and scope
+     * capture. Leaf identity then uses parent-scoped ordinals instead of
+     * static text, so `uf_*` hashes differ from full mode.
+     *
+     * Default is `false` (full auto-register mode). The SDK exports
+     * `__userflowAutoAnchor`; full mode populates the registry the in-app
+     * picker and scored AUTO matching need. Opt into `stampOnly: true` only
+     * when you want nativeID stamping without that runtime import.
+     */
+    stampOnly?: boolean;
+}
+interface PluginState extends PluginPass {
+    ufStamped?: boolean;
+    ufCallSiteCounters?: Map<string, Map<string, number>>;
+    /**
+     * Parent-scoped ordinals precomputed against the pristine JSX tree, keyed by
+     * opening-element node. Populated in `Program.enter` before `@babel/preset-react`
+     * rewrites `<El>` into `_jsx(El, …)` — otherwise earlier same-type siblings are
+     * already gone by the time we visit a later one and every element mis-reads as
+     * `#0`, colliding their `uf_<hash>` ids.
+     */
+    ufOrdinals?: WeakMap<BabelTypes.Node, {
+        ordinal: number;
+        siblingIndex: number;
+    }>;
+}
+export default function userflowAutoStamp(api: {
+    types: typeof BabelTypes;
+    template: {
+        statement: (tpl: string) => (replacements?: Record<string, unknown>) => BabelTypes.Statement;
+    };
+    env?: (name?: string) => boolean;
+}): PluginObj<PluginState>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/babel-plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAY,SAAS,EAAE,UAAU,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,aAAa,CAAC;AA4iBxF,MAAM,WAAW,0BAA0B;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD,UAAU,WAAY,SAAQ,UAAU;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kBAAkB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClF;AAgHD,MAAM,CAAC,OAAO,UAAU,iBAAiB,CAAC,GAAG,EAAE;IAC7C,KAAK,EAAE,OAAO,UAAU,CAAC;IACzB,QAAQ,EAAE;QACR,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,UAAU,CAAC,SAAS,CAAC;KAC9F,CAAC;IACF,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC,GAAG,SAAS,CAAC,WAAW,CAAC,CA+TzB"}