@userflow-tech/react-native 0.4.3 → 0.4.5

package/README.md

@@ -19,7 +19,9 @@ 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.
+0.86. Expo SDK 58 is not supported yet: it bundles `react-native-webview` 14
+and `react-native-view-shot` 6, which are outside the peer ranges below. 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
@@ -73,23 +75,43 @@ needed with any package manager.
 ### Packages
 
 ```bash
-# Expo (dev build)
+# Expo SDK 56–57 (dev build)
+npx expo install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-webview react-native-view-shot
+
+# Expo SDK 55 and older (dev build): pin view-shot, see below
 npx expo install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-webview react-native-view-shot@^5.0.0
 
 # Bare React Native
-npm install @userflow-tech/react-native @react-native-async-storage/async-storage react-native-device-info react-native-webview react-native-view-shot@^5.0.0
+npm install @userflow-tech/react-native '@react-native-async-storage/async-storage@^2' 'react-native-device-info@<16' 'react-native-webview@>=13.8.0 <14' 'react-native-view-shot@^5.0.0'
 cd ios && pod install
 ```
 
+Keep the version ranges in the bare command. Unpinned, npm picks the latest
+majors. `react-native-webview` 14 is outside the peer range, and npm only warns
+`ERESOLVE overriding peer dependency` and installs it anyway. AsyncStorage 3
+sits next to the SDK's own 2.x copy, which leaves two copies of one native
+module. `npx expo install` picks Expo's bundled versions, which fit the ranges
+on Expo SDK 53–57, except view-shot on Expo SDK 55 and older.
+
 `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 the app
-already depends on 4.0.3, that same command is what fixes it: installing the
-SDK alone fails with
+enough).
+
+On Expo SDK 56 and 57, leave view-shot unpinned. Expo's default there (5.1.0)
+satisfies the peer. A `^5.0.0` pin installs the newest 5.x instead, which
+`expo doctor` reports as a version mismatch. To fix an app that already has the
+pin, remove `"react-native-view-shot"` from `expo.install.exclude` if it is
+there, then run `npx expo install react-native-view-shot`. While the exclude is
+set, Expo installs the latest view-shot instead of 5.1.0, and `expo doctor`
+skips the check. Installed with the SDK, npm keeps view-shot on 5.x; installed
+on its own, it can pull 6.x, outside the peer range.
+
+On Expo SDK 55 and older, 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 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
@@ -98,8 +120,9 @@ 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:
+development and names the installed version. On Expo SDK 55 and older, also
+exclude view-shot from Expo's version check. Otherwise `expo doctor` reports
+the pin, and `npx expo install --fix` puts 4.0.3 back:
 
 ```json
 {
@@ -111,6 +134,10 @@ reports the `^5.0.0` pin, exclude it from Expo's version check:
 }
 ```
 
+With the exclude set, always install view-shot as
+`react-native-view-shot@^5.0.0`. Unpinned, Expo skips its version, so npm can
+keep 4.0.3 or pull 6.x.
+
 On a bare React Native app, `expo-secure-store` needs Expo modules installed
 first (`npx install-expo-modules@latest`), then `npx expo install expo-secure-store`.
 
@@ -119,14 +146,41 @@ Optional peers as needed:
 ```bash
 npx expo install react-native-safe-area-context @react-native-community/netinfo expo-secure-store
 # and either expo-router or @react-navigation/native, depending on your router
+
+# Bare React Native
+npm install 'react-native-safe-area-context@<6' '@react-native-community/netinfo@<13'
 ```
 
+### Babel plugin
+
+Add `@userflow-tech/react-native/babel-plugin` to `babel.config.js`. It stamps
+`View`, `Text`, `Pressable`, the Touchables, `TextInput`, and `Image` at build
+time, so elements can be targeted without a `testID`. An Expo app without a
+`babel.config.js` can create one with `npx expo customize babel.config.js`.
+
+```js
+// babel.config.js
+module.exports = function (api) {
+  api.cache(true);
+  return {
+    presets: ['babel-preset-expo'], // or the app's existing preset
+    plugins: ['@userflow-tech/react-native/babel-plugin'],
+  };
+};
+```
+
+Keep the app's own plugins. If it lists `react-native-reanimated/plugin` or
+`react-native-worklets/plugin`, keep that one last. Start Metro once with a
+cleared cache (`npx expo start -c`) so every file is stamped. Apps with Jest
+should read [Babel plugin and snapshot tests](#babel-plugin-and-snapshot-tests).
+
 ### Install with an AI agent
 
-An Agent Skill that installs this SDK in Cursor, Claude Code, and other agents
-will be available soon. It will be `install-react-native-with-ai` in
-[userflow/ai-skills-library](https://github.com/userflow/ai-skills-library).
-Web apps will use `install-with-ai` from that library.
+The `install-userflow-react-native-sdk-with-ai` Agent Skill installs this SDK
+with Cursor, Claude Code, and other agents. It is in
+[userflow/ai-skills-library](https://github.com/userflow/ai-skills-library),
+whose README explains how to add it to your agent. Web apps use
+`install-with-ai` from that library.
 
 ## Quick start
 
@@ -153,12 +207,13 @@ the app to change those.
 
 ### `init` options
 
-| Option        | Default                  | Description                                                                                                  |
-| ------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `clientToken` | —                        | **Required.** The `ct_…` client token from Settings → Environments.                                          |
-| `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`.                                                  |
+| Option           | Default                      | Description                                                                                                              |
+| ---------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `clientToken`    | —                            | **Required.** The `ct_…` client token from Settings → Environments.                                                      |
+| `serverEndpoint` | Picked from the client token | Optional. The region is picked automatically from the client token; only set this for a proxy or a non-production stack. |
+| `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`
 
@@ -193,6 +248,9 @@ export default function RootLayout() {
 }
 ```
 
+Expo Router apps also add `app/+native-intent.ts`, so Builder pairing links do
+not navigate. See [Builder preview & pairing](#builder-preview--pairing).
+
 React Navigation:
 
 ```tsx
@@ -391,10 +449,12 @@ To preview draft flows from the Userflow builder onto a device (QR / deep link):
    `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` and wrap the tree in `UserflowProvider`.
-3. Open the builder Preview dialog → **Pair a device** → scan/open the QR. The
+2. Expo Router only: add `app/+native-intent.ts` (below) so pairing and preview
+   links do not navigate.
+3. Call `Userflow.init` and wrap the tree in `UserflowProvider`.
+4. Open the builder Preview dialog → **Pair a device** → scan/open the QR. The
    app should show a **Preview mode** top bar.
-4. Hit **Preview** in the builder. The draft flow lands on that paired device.
+5. Hit **Preview** in the builder. The draft flow lands on that paired device.
 
 ```json
 {
@@ -409,8 +469,20 @@ To preview draft flows from the Userflow builder onto a device (QR / deep link):
 `schemeId` is the env's `scheme_id` from the dashboard, copied exactly. It is
 `userflow-` followed by an opaque id. Do not rely on its shape. Preview links
 (`…://?token=…`) and pairing links (`…://?pairing_token=…`) both ride that one
-scheme. Expo Router needs no extra host files for these root-form URLs, and
-pairing works in every build, including release.
+scheme. Pairing works in every build, including release.
+
+Expo Router treats these root-form URLs as `/`, so without
+`app/+native-intent.ts` it navigates when a link arrives: the app jumps to its
+home route, or element selection fails with "Can't select this element".
+Re-export the SDK's handler to keep the current screen:
+
+```ts
+// app/+native-intent.ts
+export { redirectSystemPath } from '@userflow-tech/react-native/expo-router';
+```
+
+If the app already has a `+native-intent.ts`, wrap it instead. See
+[docs/deep-linking.md](https://unpkg.com/@userflow-tech/react-native/docs/deep-linking.md).
 
 Deep-link / pairing helpers:
 
@@ -524,10 +596,10 @@ and forwards URLs itself.
 
 ### Subpath exports
 
-| Import                                    | Provides                                                                                                |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                                                                           |
-| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter`, `redirectSystemPath` (for `+native-intent`) |
+| Import                                    | Provides                                                                                                                                                                                       |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@userflow-tech/react-native/navigation`  | `WithUserflowReactNavigation`                                                                                                                                                                  |
+| `@userflow-tech/react-native/expo-router` | `UserflowExpoRouterScreenTracker`, `useUserflowExpoRouter`, `redirectSystemPath` and `createRedirectSystemPath` (for `+native-intent`), `isUserflowLinkPath`, type `RedirectSystemPathOptions` |
 
 ## Guides in this package
 
@@ -555,17 +627,16 @@ These guides also ship in the package, under
 - Client conditions — `ELEMENT` PRESENT / NOT_PRESENT on manual anchors and
   AUTO selectors (guarded: weak evidence stays unknown)
 - Connection lifecycle — suspend/resume, reconnect, optional NetInfo
+- Build-time stamping with `@userflow-tech/react-native/babel-plugin`
+  (`stampOnly: true` stamps `nativeID` only; full mode is the default). Jest
+  runs the plugin too, which changes snapshots; see
+  [Babel plugin and snapshot tests](#babel-plugin-and-snapshot-tests).
 
 ### 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](https://unpkg.com/@userflow-tech/react-native/docs/anchoring.md).
-- Build-time stamping with `@userflow-tech/react-native/babel-plugin`
-  (`stampOnly: true` stamps `nativeID` only; full mode is the default). Jest
-  runs the plugin too, which changes snapshots. Read
-  [Babel plugin and snapshot tests](#babel-plugin-and-snapshot-tests) before
-  enabling it.
 
 ### Not available yet
 
@@ -589,7 +660,7 @@ 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):
 - @react-native-async-storage/async-storage is not linked. Anonymous users and Builder pairing will not persist. Add it to the app package.json (npx expo install @react-native-async-storage/async-storage), run pod install on iOS, and rebuild.
-- 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-view-shot is not linked, so Builder element selection gets no screenshot. Install it and rebuild. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Otherwise install react-native-view-shot@^5.0.0; on Expo SDK 55 and older, 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 node_modules/@userflow-tech/react-native/docs/troubleshooting.md.
@@ -653,6 +724,28 @@ jest.mock('@userflow-tech/react-native/navigation', () => ({
 In a JavaScript setup file, drop the `ReactNode` import and the type
 annotations.
 
+If `app/+native-intent.ts` imports `redirectSystemPath` or
+`createRedirectSystemPath`, replace the `@userflow-tech/react-native/expo-router`
+mock above with the one below (in a JavaScript setup file, drop its type
+annotations too). Two `jest.mock` calls for one path do not merge; the later
+one wins. Expo Router loads `+native-intent.ts` when a test renders the
+router, and the mock replaces the whole module, so an export it leaves out is
+`undefined`. A `+native-intent.ts` that calls `createRedirectSystemPath()` then
+fails the suite with `createRedirectSystemPath is not a function`. These stubs
+pass every URL through, as the real handlers do for links that are not Userflow
+links:
+
+```ts
+jest.mock('@userflow-tech/react-native/expo-router', () => ({
+  UserflowExpoRouterScreenTracker: () => null,
+  redirectSystemPath: ({ path }: { path: string }) => path,
+  createRedirectSystemPath:
+    ({ next }: { next?: (event: { path: string }) => unknown } = {}) =>
+    (event: { path: string }) =>
+      next ? next(event) : event.path,
+}));
+```
+
 A custom Metro config that does not extend `getDefaultConfig` from `expo/metro-config`
 or `@react-native/metro-config` leaves `allowOptionalDependencies` off. Optional
 peers that this package loads inside `try/catch` then fail the bundle with
@@ -660,8 +753,8 @@ peers that this package loads inside `try/catch` then fail the bundle with
 
 ### Babel plugin and snapshot tests
 
-If you add the optional `@userflow-tech/react-native/babel-plugin` to
-`babel.config.js`, Jest runs it too, because `babel-jest` reads the same config.
+With `@userflow-tech/react-native/babel-plugin` in `babel.config.js`, Jest
+runs it too, because `babel-jest` reads the same config.
 The plugin adds props to `View`, `Text`, `Pressable`, the Touchables,
 `TextInput`, and `Image`, and React Native's Jest mocks render them, so they
 appear in snapshots:
@@ -692,7 +785,8 @@ or moving or renaming a file changes them again. The plugin also imports this
 package into every stamped file, so any test that renders a stamped component
 loads the SDK. Keep the mock above in the Jest setup file.
 
-Skip the plugin under Jest:
+Skip the plugin under Jest, and keep the app's own plugins in every
+environment:
 
 ```js
 // babel.config.js
@@ -700,7 +794,11 @@ module.exports = function (api) {
   const isTest = api.env('test');
   return {
     presets: ['babel-preset-expo'],
-    plugins: isTest ? [] : ['@userflow-tech/react-native/babel-plugin'],
+    plugins: [
+      // ...the app's own plugins
+      ...(isTest ? [] : ['@userflow-tech/react-native/babel-plugin']),
+      // react-native-reanimated/plugin or react-native-worklets/plugin, if listed, stays last
+    ],
   };
 };
 ```

package/docs/deep-linking.md

@@ -78,6 +78,32 @@ export const redirectSystemPath = createRedirectSystemPath({
 });
 ```
 
+`next` runs only for links that are not Userflow links. A pairing or preview
+link returns `null` before `next` is called, so host code inside `next` (logging
+incoming URLs, for example) never sees it. If the host must see every URL, run
+its code first, then return the SDK handler's result:
+
+```ts
+import {
+  createRedirectSystemPath,
+  type RedirectSystemPathOptions,
+} from '@userflow-tech/react-native/expo-router';
+
+const userflowRedirectSystemPath = createRedirectSystemPath({
+  next: (event) => event.path, // the host's handling of non-Userflow links
+});
+
+export function redirectSystemPath(event: RedirectSystemPathOptions) {
+  try {
+    // Runs for every URL, Userflow links included. Use the app's own logger here.
+    console.log('[app] incoming URL', event.path);
+  } catch {
+    // Expo warns that throwing here can crash the app.
+  }
+  return userflowRedirectSystemPath(event);
+}
+```
+
 Bare React Native / React Navigation apps need nothing beyond scheme
 registration.