@userflow-tech/react-native 0.1.1 → 0.3.0

package/README.md

@@ -9,18 +9,22 @@ release for every content change.
 
 ## Requirements
 
-| 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-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-webview`                      | Yes (dep)  | Evaluate JavaScript / WebView banners. Native rebuild required.          |
+| `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
 
@@ -40,16 +44,29 @@ the host app’s `.npmrc` via an env var — do not commit the token:
 
 ```bash
 # Expo (dev build)
-npx expo install @userflow-tech/react-native
+npx expo install @userflow-tech/react-native react-native-view-shot@^5.0.0 react-native-webview
 
 # Bare React Native
-npm install @userflow-tech/react-native
+npm install @userflow-tech/react-native react-native-view-shot react-native-webview
 cd ios && pod install
 ```
 
-`@react-native-async-storage/async-storage` is a dependency of this package and
-is installed automatically. If autolinking misses it, run
-`npx expo install @react-native-async-storage/async-storage`.
+`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:
 
@@ -73,8 +90,9 @@ await Userflow.init({
   // 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 });
+// Identified user — signature is computed by YOUR backend, never in the app.
+// `locale_code` is the same user attribute as web (see Localization below).
+await Userflow.identify('user-123', { name: 'Ada', locale_code: 'da-DK' }, { signature });
 
 // …or anonymous (id stored in AsyncStorage):
 await Userflow.identifyAnonymous();
@@ -100,12 +118,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()`. 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                                                                                                                                                                |
 
 Other rules:
 
@@ -118,8 +138,49 @@ Other rules:
   the server** when the environment has identity verification enabled. See
   [docs/identity-verification.md](docs/identity-verification.md).
 
+## Localization
+
+Pass the end-user's locale the same way as userflow.js: as a user attribute on
+`identify`, `identifyAnonymous`, or `updateUser`. The attribute name is the
+company's locale attribute (default `locale_code`).
+
+```ts
+await Userflow.identify('user-123', { name: 'Ada', locale_code: 'da-DK' }, { signature });
+```
+
+When that locale is enabled on the flow in the Builder, the end-user sees the
+translated content. If the user has no locale stored, or the stored code is not
+a locale the company has set up, the flow stays in its original language.
+Omitting the attribute on a later identify does not clear a locale already
+stored for that user. A locale the company has, but that is not enabled on this
+flow, hides the flow — same as web.
+
+The value is stored on the end user under the company's locale attribute.
+Identifying the same user id on mobile keeps a locale already sent from the web
+app, so mobile does not need to send it again. Sending a new value overwrites
+it; sending `null` clears it. The SDK does not read the device locale.
+
+## Host isolation
+
+The SDK is in-process JS, so it cannot fully sandbox itself from the host app.
+Overlay render errors and fire-and-forget tracking failures are caught, logged
+as `[Userflow] isolated error` via `console.warn`, and swallowed so they cannot
+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).
+
 ## Screen tracking
 
+Each accepted screen/path also sends a `screen_viewed` event after identify
+(with `screen_name`, which holds the Expo Router path or the screen name). 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`
@@ -205,20 +266,22 @@ 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/react-native` config plugin, then
-   **rebuild native** (`npx expo prebuild` / a new development client). Metro
-   reload is not enough.
+1. Register the environment's **`scheme_id`** (e.g.
+   `userflow-v7twv2fw2ja2jaco7kesvowmem` — **not** 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/react-native", { "schemeId": "userflow-257587" }]]
+    "plugins": [
+      ["@userflow-tech/react-native", { "schemeId": "userflow-v7twv2fw2ja2jaco7kesvowmem" }]
+    ]
   }
 }
 ```
@@ -234,12 +297,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=…`, optionally `&purpose=preview` or `&purpose=select_element`).                                                                                                             |
+| `exitPreview()`         | Disconnect the pairing websocket and leave preview mode.                                                                                                                                                                     |
+| `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:
@@ -274,48 +337,54 @@ 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. 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=…`; 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. Overlay render errors are isolated from host children.                                                                                                                             |
+| `PreviewModeBanner`                     | Shown by the provider while a Builder pairing session is active. It 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. |
+| `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` |
+| Import                                    | Provides                                                                                                |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                                                                           |
+| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter`, `redirectSystemPath` (for `+native-intent`) |
 
 ### Constants
 
@@ -328,19 +397,25 @@ 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/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)          |
+| 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)           |
+
+## 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

@@ -1,3 +1,21 @@
 // Expo loads this file as the config plugin entry.
 // Hosts register: plugins: [['@userflow-tech/react-native', { schemeId: 'userflow-…' }]]
-module.exports = require('./expo-plugin/withUserflow.js');
+// A checkout must never load the vendored copy: prepack writes it into the
+// working tree, and it goes stale as soon as the plugin source changes.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const vendored = path.join(__dirname, 'expo-plugin/withUserflow.js');
+const workspacePackage = path.join(__dirname, '../expo/package.json');
+const workspace = path.join(__dirname, '../expo/build/withUserflow.js');
+
+if (fs.existsSync(workspacePackage)) {
+  if (!fs.existsSync(workspace)) {
+    throw new Error(
+      `@userflow-tech/react-native/app.plugin: ${workspace} is missing. Run \`pnpm build\` at the repo root.`,
+    );
+  }
+  module.exports = require(workspace);
+} else {
+  module.exports = require(vendored);
+}

package/babel-plugin/index.d.ts

@@ -5,15 +5,15 @@ export interface UserflowBabelPluginOptions {
     injectUfidProp?: boolean;
     exclude?: string[];
     /**
-     * When true (the default), only stamp `nativeID` (and `collapsable={false}`
-     * when needed). Skips the SDK import, `__ufRef` helper, ref wrapping, hints,
-     * and scope capture. Use this against the current official SDK, which
-     * resolves anchors via fiber `nativeID` matching and does not yet export
-     * `__userflowAutoAnchor`.
+     * 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.
      *
-     * Set to `false` only when the host SDK provides `__userflowAutoAnchor`
-     * (full auto-register mode). Enabling full mode without that export will
-     * inject a broken import into every stamped module.
+     * 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;
 }

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

@@ -1 +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;AAyiBxF,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;AAED,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;AA8GD,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,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;AAyDD,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,CA6TzB"}

package/babel-plugin/index.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = userflowAutoStamp;
+const nodeFs = __importStar(require("node:fs"));
 const nodePath = __importStar(require("node:path"));
 /**
  * @userflow-tech/react-native/babel-plugin — semantic auto-stamp + auto-register (rn-v2).
@@ -44,9 +45,11 @@ const nodePath = __importStar(require("node:path"));
  *   3. Runtime bag (dynamic ids/labels + inherited `__ufScope` when captured)
  *   4. Call-site `__ufScope` on first-party custom components
  *
- * When `stampOnly` is set, only `nativeID` and `collapsable` are injected —
- * no SDK import, no `__ufRef` helper, no ref wrapping, and no scope capture.
- * That mode is enough for the SDK's fiber scanner to resolve stamped hosts.
+ * Full mode (the default) also injects `__userflowAutoAnchor`, a `__ufRef`
+ * helper, ref wrapping, and `__ufScope` capture so scored AUTO matching can
+ * populate the auto-anchor registry. Set `stampOnly: true` to stamp only
+ * `nativeID` and `collapsable` — enough for the fiber scanner, but the
+ * in-app picker and scored AUTO matches stay empty.
  *
  * Existing app props are composed, never replaced: `ref` (callback, object,
  * legacy string, or single `{...props}.ref`), `nativeID`, and `collapsable`
@@ -61,6 +64,7 @@ const DEFAULT_ALLOWLIST = [
     'TouchableNativeFeedback',
     'View',
     'Text',
+    'TextInput',
     'Image',
 ];
 const COLLAPSABLE_NAMES = new Set([
@@ -478,6 +482,59 @@ function buildRuntimeExpr(t, findAttr, includeScope) {
     }
     return t.objectExpression(props);
 }
+function isStampOnly(opts) {
+    return opts.stampOnly === true;
+}
+const SDK_PACKAGE_SCOPE = '@userflow-tech/';
+const sdkPackageDirCache = new Map();
+function readPackageName(dir) {
+    try {
+        const parsed = JSON.parse(nodeFs.readFileSync(nodePath.join(dir, 'package.json'), 'utf8'));
+        const name = parsed?.name;
+        return typeof name === 'string' ? name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether `filename` belongs to a Userflow SDK package, judged by the nearest
+ * named `package.json`. A workspace or `file:` link resolves the SDK outside
+ * `node_modules`; stamping its own overlay would register SDK chrome as app
+ * anchors, and `TooltipSurface` re-renders on every registry change.
+ */
+function isInsideSdkPackage(filename) {
+    const visited = [];
+    let dir = nodePath.dirname(filename);
+    let result = false;
+    for (;;) {
+        const cached = sdkPackageDirCache.get(dir);
+        if (cached !== undefined) {
+            result = cached;
+            break;
+        }
+        visited.push(dir);
+        const name = readPackageName(dir);
+        if (name !== undefined) {
+            result = name.startsWith(SDK_PACKAGE_SCOPE);
+            break;
+        }
+        const parent = nodePath.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    for (const d of visited)
+        sdkPackageDirCache.set(d, result);
+    return result;
+}
+function isSkippedFile(filename, opts) {
+    if (!filename || filename.includes('node_modules'))
+        return true;
+    if (opts.exclude?.some((frag) => filename.includes(frag)))
+        return true;
+    return isInsideSdkPackage(filename);
+}
 function enclosingComponentName(t, openingPath, filename) {
     let fn = openingPath.getFunctionParent();
     let sawDefaultExport = false;
@@ -546,7 +603,9 @@ function ensureScopeCapture(t, fnPath) {
     const first = params[0];
     let propsAccess;
     if (t.isIdentifier(first)) {
-        propsAccess = t.memberExpression(first, t.identifier(UF_SCOPE_PROP));
+        // Optional: helpers like `envelope(fp)` and type predicates also match
+        // `Function` enter. A missing first arg must not throw at module init.
+        propsAccess = t.optionalMemberExpression(first, t.identifier(UF_SCOPE_PROP), false, true);
     }
     else if (t.isObjectPattern(first)) {
         // Look for __ufScope in pattern or add member via rest — skip if complex
@@ -600,8 +659,8 @@ function userflowAutoStamp(api) {
                     if (!state.ufStamped)
                         return;
                     const opts = (state.opts ?? {});
-                    // stampOnly (default) never wraps refs, so there is nothing to import or helper.
-                    if (opts.stampOnly !== false)
+                    // stampOnly never wraps refs, so there is nothing to import or helper.
+                    if (isStampOnly(opts))
                         return;
                     // Bind the runtime installer into every stamped module so production
                     // tree-shaking cannot drop `globalThis.__userflowAutoAnchor` when the
@@ -659,12 +718,10 @@ function userflowAutoStamp(api) {
             Function: {
                 enter(fnPath, state) {
                     const opts = (state.opts ?? {});
-                    if (opts.stampOnly !== false)
+                    if (isStampOnly(opts))
                         return;
                     const filename = state.filename ?? state.file.opts.filename ?? '';
-                    if (!filename || filename.includes('node_modules'))
-                        return;
-                    if (opts.exclude?.some((frag) => filename.includes(frag)))
+                    if (isSkippedFile(filename, opts))
                         return;
                     // Do not pollute the injected `__ufRef` helper (Program.exit re-visits it).
                     if ((fnPath.isFunctionDeclaration() || fnPath.isFunctionExpression()) &&
@@ -683,12 +740,10 @@ function userflowAutoStamp(api) {
                     return;
                 const name = nameNode.name;
                 const allowlist = opts.allowlist ?? DEFAULT_ALLOWLIST;
-                // Default true — full mode is unsafe until __userflowAutoAnchor ships.
-                const stampOnly = opts.stampOnly !== false;
+                // Default false — full mode populates the auto-anchor registry.
+                const stampOnly = isStampOnly(opts);
                 const filename = state.filename ?? state.file.opts.filename ?? '';
-                if (!filename || filename.includes('node_modules'))
-                    return;
-                if (opts.exclude?.some((frag) => filename.includes(frag)))
+                if (isSkippedFile(filename, opts))
                     return;
                 const rootDir = opts.rootDir ?? state.cwd ?? process.cwd();
                 const rel = nodePath.relative(rootDir, filename).split(nodePath.sep).join('/') || filename;