@userflow-tech/react-native 0.4.4 → 0.5.0

package/README.md

@@ -75,7 +75,10 @@ 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
@@ -88,17 +91,27 @@ 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.
+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 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
+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
@@ -107,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
 {
@@ -120,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`.
 
@@ -133,12 +151,36 @@ npx expo install react-native-safe-area-context @react-native-community/netinfo
 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
 
@@ -206,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
@@ -404,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
 {
@@ -422,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:
 
@@ -465,12 +524,17 @@ heartbeat or foreground return.
 
 ## NAVIGATE actions
 
-Flow NAVIGATE buttons open URLs in this order:
+Flow and banner **Navigate to page** button actions (and in-content links) open
+URLs in this order:
 
 1. Host `onNavigate` from `Userflow.init({ onNavigate })` / `Userflow.setOnNavigate` (wins)
 2. http(s) / mailto / tel → Linking
 3. Path-like in-app URLs → Expo Router `push` or React Navigation `navigate`
-4. Otherwise best-effort Linking
+4. Otherwise allowlisted http(s) / mailto / tel via Linking
+
+In the builder **Navigate to page** action, use a full URL such as
+`https://example.com` to open the system browser, a React Navigation screen
+name such as `Profile`, or an Expo Router path such as `/settings`.
 
 Screen tracking ≠ action routing. React Navigation apps need
 `WithUserflowReactNavigation` for in-app NAVIGATE. Expo Router apps need
@@ -537,10 +601,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
 
@@ -568,17 +632,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
 
@@ -602,7 +665,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.
@@ -666,6 +729,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
@@ -673,8 +758,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:
@@ -705,7 +790,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
@@ -713,7 +799,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/anchoring.md

@@ -354,7 +354,7 @@ When a tooltip cannot resolve / measure its target:
 
 | Behavior         | After tolerance                                                                |
 | ---------------- | ------------------------------------------------------------------------------ |
-| `FLAG` (default) | Centered “Target not found” card; keeps remeasuring slowly for recovery        |
+| `FLAG` (default) | Centered “Target not found” card; keeps looking for the target to recover      |
 | `ERROR`          | Same missing UI as `FLAG`                                                      |
 | `BUBBLE`         | Centered card with normal step content (modal-like fallback)                   |
 | `END`            | Hides the flow UI (`null`); in draft/preview mode shows the missing UI instead |
@@ -362,6 +362,11 @@ When a tooltip cannot resolve / measure its target:
 Ambiguous ids, missing hosts, and zero-width/height measures all count as
 missing.
 
+While the target is missing, the SDK keeps looking with a backoff (up to every
+4 s), looks again right away when the screen changes or the app returns to the
+foreground, and within ~500 ms when a registered element mounts. Nothing runs
+while the app is in the background.
+
 ## ELEMENT client conditions
 
 `PRESENT` / `NOT_PRESENT` / `CLICK` / `NOT_CLICK` resolve through

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.
 

package/docs/troubleshooting.md

@@ -7,23 +7,23 @@ Messages are quoted exactly so you can search logs for them.
 
 | Symptom / log message                                                                                                                                                                                                                                                                                                                                                                      | Likely cause                                                                                                                                                                                                                           | Fix                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `expo doctor` reports `react-native-view-shot`                                                                                                                                                                                                                                                                                                                                             | The app pins `^5.0.0` and Expo SDK 55 and older expect 4.0.3.                                                                                                                                                                          | Keep the pin. Add `"react-native-view-shot"` to `expo.install.exclude`.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `expo doctor` reports `react-native-view-shot`                                                                                                                                                                                                                                                                                                                                             | The app pins `^5.0.0`. Expo SDK 55 and older expect 4.0.3. Expo SDK 56 and 57 expect 5.1.0, and the pin installed a newer 5.x.                                                                                                         | Expo SDK 55 and older: keep the pin and add `"react-native-view-shot"` to `expo.install.exclude`. Expo SDK 56 and 57: drop the pin, remove `"react-native-view-shot"` from `expo.install.exclude` if it is there, and reinstall with `npx expo install react-native-view-shot`.                                                                                                                                                                                                                                   |
 | `Unable to resolve module` for an optional peer (`netinfo`, `expo-secure-store`, `expo-router`, safe-area, navigation)                                                                                                                                                                                                                                                                     | A custom Metro config does not extend `getDefaultConfig`, so `allowOptionalDependencies` is off.                                                                                                                                       | Extend `getDefaultConfig` from `expo/metro-config` or `@react-native/metro-config`.                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `ERESOLVE` while installing `@userflow-tech/react-native`                                                                                                                                                                                                                                                                                                                                  | The app already has a version outside a peer range: view-shot 4.0.3 (what unpinned `npx expo install` installs on Expo SDK 55 and older), NetInfo 9.x, safe-area-context 3.x, WebView 13.6.x or 14.x, or React Native older than 0.76. | Move that package into the range in the package README. For view-shot, npm prints `Found: react-native-view-shot@4.0.3` and `peer react-native-view-shot@"^5.0.0" from @userflow-tech/react-native`. Install the SDK and `react-native-view-shot@^5.0.0` in one command, then add `"react-native-view-shot"` to `expo.install.exclude` on Expo SDK 55 and older. Do not retry with `--force` or `--legacy-peer-deps`; that leaves 4.0.3 installed. Raise React Native to 0.76 or later when that is the conflict. |
 | `npm warn ERESOLVE overriding peer dependency` naming `react-native-webview`, or `npm ls` lists two versions of `@react-native-async-storage/async-storage`                                                                                                                                                                                                                                | An unpinned bare install picked WebView 14 (outside `>=13.8.0 <14`) or AsyncStorage 3 (the SDK keeps its own 2.x copy). npm only warns and installs the invalid tree.                                                                  | Reinstall with the ranges from the bare command in the package README: `'@react-native-async-storage/async-storage@^2'` and `'react-native-webview@>=13.8.0 <14'`. Then run `pod install` and rebuild.                                                                                                                                                                                                                                                                                                            |
-| Yarn 1 or `npm install --legacy-peer-deps` succeeded, but `react-native-webview` or `react-native-view-shot` is not installed                                                                                                                                                                                                                                                              | Those installs do not fetch peers. WebView and view-shot are required peers, not dependencies.                                                                                                                                         | Install `react-native-webview` and `react-native-view-shot@^5.0.0` in the app, then rebuild native.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Yarn 1 or `npm install --legacy-peer-deps` succeeded, but `react-native-webview` or `react-native-view-shot` is not installed                                                                                                                                                                                                                                                              | Those installs do not fetch peers. WebView and view-shot are required peers, not dependencies.                                                                                                                                         | Install `react-native-webview` and `react-native-view-shot` in the app (on Expo SDK 56 and 57, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`), then rebuild native.                                                                                                                                                                                                                                                                                               |
 | Banners, flow cards, or Builder bars draw under the status bar, notch, or home indicator. Development logs `[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>.`                       | `react-native-safe-area-context` is not installed, so insets are zero.                                                                                                                                                                 | Install the package and wrap the tree in `<SafeAreaProvider>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `Uncaught Error` / `NativeModule.RNCNetInfo is null` as soon as `Userflow.init` runs                                                                                                                                                                                                                                                                                                       | On SDK 0.3.1 and earlier, NetInfo's JavaScript was loaded while its native module was not in the binary. Debug builds show a red screen. Dismissing it leaves the app running; a release build can crash.                              | Link `@react-native-community/netinfo` and rebuild, or remove it. Current versions skip NetInfo when `RNCNetInfo` is not registered and log one dev warning instead.                                                                                                                                                                                                                                                                                                                                              |
 | `[@userflow-tech/react-native] schemeId "…" looks like an environment id. Pass the scheme_id value that starts with userflow- (an opaque id from the dashboard), not the environment UUID.`                                                                                                                                                                                                | The config plugin received the environment UUID.                                                                                                                                                                                       | Pass the `scheme_id` (`userflow-…`) from the dashboard.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `No schemeId was passed, so the plugin left the native config unchanged. Builder preview and pairing links will not open this app. Pass the environment scheme_id (userflow-...) from the Userflow dashboard as the plugin schemeId.`                                                                                                                                                      | `expo prebuild` ran the plugin without `schemeId`.                                                                                                                                                                                     | Add `{ "schemeId": "userflow-…" }` and rebuild native.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 54, an unpinned `npx expo install react-native-view-shot` resolves 4.0.3. Pin ^5.0.0. If expo doctor reports a version mismatch, add "react-native-view-shot" to expo.install.exclude.                                                                                             | Prebuild did not find view-shot in the app `package.json`.                                                                                                                                                                             | `npx expo install react-native-view-shot@^5.0.0` and rebuild.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 and 57, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.                                | Prebuild did not find view-shot in the app `package.json`.                                                                                                                                                                             | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned). Expo SDK 55 and older: `npx expo install react-native-view-shot@^5.0.0` and add `"react-native-view-shot"` to `expo.install.exclude`. Then rebuild.                                                                                                                                                                                                                                                                                     |
 | `react-native-safe-area-context is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Without the native module, banners, flow cards, and Builder bars draw under the status bar and home indicator. Install it in the app (npx expo install react-native-safe-area-context) and wrap the app in <SafeAreaProvider>.` | Expo SDK older than 54, and safe-area-context is not a direct dependency, so its native module is not autolinked.                                                                                                                      | `npx expo install react-native-safe-area-context` and wrap the tree in `<SafeAreaProvider>`.                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `[Userflow] react-native-view-shot@4.0.3 is older than 5.0.0, so Builder element selection may not get a screenshot.` The installed version is filled in. The warning also says not to retry with `--force` or `--legacy-peer-deps`.                                                                                                                                                       | view-shot 4.x is installed, usually because an `ERESOLVE` was retried with `--force` or `--legacy-peer-deps`, or the 4.0.3 default on Expo SDK 55 and older was left in place.                                                         | Install `react-native-view-shot@^5.0.0` in the same command as the SDK and rebuild. On Expo SDK 55 and older, add `"react-native-view-shot"` to `expo.install.exclude`.                                                                                                                                                                                                                                                                                                                                           |
-| `react-native-view-shot@4.0.3 is older than 5.0.0. Expo SDK 54's default is 4.0.3, which does not work with this SDK. Pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude if expo doctor complains.`                                                                                                                                                                       | The app has view-shot 4.x.                                                                                                                                                                                                             | Pin `^5.0.0` and rebuild.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `[Userflow] react-native-view-shot@4.0.3 is older than 5.0.0, so Builder element selection may not get a screenshot.` The installed version is filled in. The warning also says not to retry with `--force` or `--legacy-peer-deps`.                                                                                                                                                       | view-shot 4.x is installed, usually because an `ERESOLVE` was retried with `--force` or `--legacy-peer-deps`, or the 4.0.3 default on Expo SDK 55 and older was left in place.                                                         | Expo SDK 56 and 57: remove any view-shot entry from `expo.install.exclude`, run `npx expo install react-native-view-shot` unpinned, and rebuild. Otherwise install `react-native-view-shot@^5.0.0` in the same command as the SDK and rebuild; on Expo SDK 55 and older, also add `"react-native-view-shot"` to `expo.install.exclude`.                                                                                                                                                                           |
+| `react-native-view-shot@4.0.3 is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.`                                                                | The app has view-shot 4.x.                                                                                                                                                                                                             | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned), then rebuild. Expo SDK 55 and older: pin `^5.0.0`, add the exclude, and rebuild.                                                                                                                                                                                                                                                                                                                                                        |
 | `@react-native-async-storage/async-storage is not listed in the app package.json. Expo SDK 53 does not autolink native modules that the app only receives indirectly. Install it in the app (npx expo install @react-native-async-storage/async-storage) and rebuild.`                                                                                                                     | Expo SDK older than 54, and AsyncStorage is only a transitive dependency. The WebView line is the same shape with `react-native-webview`.                                                                                              | Install that package in the app and rebuild.                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `[Userflow] Native setup is incomplete. Flows may not run until you fix the following, then rebuild the app (a Metro reload is not enough):`                                                                                                                                                                                                                                               | Dev-only check on the first `Userflow.init`. Following lines name each missing native module. A missing safe-area package is a separate warning, because flows still run.                                                              | Install the named packages and rebuild. The footer is `See node_modules/@userflow-tech/react-native/docs/troubleshooting.md.`                                                                                                                                                                                                                                                                                                                                                                                     |
 | `- @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.`                                                                                                                                       | AsyncStorage's native module is not in this binary.                                                                                                                                                                                    | Add it to the app `package.json`, 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.`                                                                                                                                                                     | `RNViewShot` is not registered.                                                                                                                                                                                                        | Install `react-native-view-shot@^5.0.0` and rebuild.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `- 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.`                         | `RNViewShot` is not registered.                                                                                                                                                                                                        | Expo SDK 56 and 57: `npx expo install react-native-view-shot` (unpinned). Otherwise install `react-native-view-shot@^5.0.0`. Then rebuild.                                                                                                                                                                                                                                                                                                                                                                        |
 | `- react-native-webview is not linked. Evaluate JavaScript and WebView banners will not run. Install it (npx expo install react-native-webview) and rebuild.`                                                                                                                                                                                                                              | The WebView native module is not registered.                                                                                                                                                                                           | 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.`                                                                                                                                                                                                                                                 | Bare React Native, and `RNDeviceInfo` is not registered. Expo apps that have `expo-constants` do not log this line.                                                                                                                    | `npm install react-native-device-info` and rebuild.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `[Userflow] This app is running in Expo Go, which cannot load the SDK native modules. Builder preview links will not open the app. Use a development build (npx expo run:ios / npx expo run:android).`                                                                                                                                                                                     | The app is the Expo Go store client.                                                                                                                                                                                                   | Use a development build.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
@@ -78,6 +78,32 @@ evaluated. `DISABLED`, `NOT_DISABLED`, and `MOUSEDOWN` are not.
 the four supported states, and tag the target with matching `userflowId`,
 `testID`, or `nativeID` (or `useUserflowAnchor('…')`). See [anchoring.md](anchoring.md).
 
+### Click conditions and gesture-handler controls
+
+`RectButton`, `BorderlessButton`, `BaseButton`, the older gesture-handler
+touchables, and a `GestureDetector` gesture with `.runOnJS(true)` still count
+as a tap, including when they cancel React Native's touch. A plain React Native
+`Pressable`, including one inside a `Modal`, counts through the normal touch
+stream. A manual id on the view touched at the start of the press still matches
+after that press navigates away, once a live scan no longer finds that id.
+
+On-device checks of these controls (iOS 26, Android API 35) saw a normal touch
+end, so that is the path those runs exercised. A control that instead cancels
+the touch is counted when its handler later ends from `ACTIVE`. That hand-off
+is covered by unit tests.
+
+These do **not** count. `CLICK` stays false and `NOT_CLICK` stays true:
+
+| Control                                                                     | Why                                                                                                                                                                                                                 |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| A scroll in a gesture-handler `ScrollView`, `FlatList`, or `RefreshControl` | Those handlers set `disallowInterruption` and report no finger position, so a scroll must not latch the row it started on. A button inside the container still counts.                                              |
+| A worklet `GestureDetector` gesture that also cancels React Native's touch  | The end stays on the UI thread and never arrives as `onGestureHandlerStateChange`. Add `.runOnJS(true)` if you can. A worklet gesture that leaves the touch stream alone still counts through the normal touch end. |
+| The same controls on the old architecture (Paper)                           | That architecture does not deliver the state-change event this watches. React Native 0.86 is new-architecture only.                                                                                                 |
+
+A drag that starts on the control, a long press, and a finger that slides off
+it are not taps. A tap in the first half-second after a flow closes can also
+miss: the server has not re-tracked the condition yet.
+
 ### 2. Anchor / tooltip placement
 
 | Symptom                                           | Likely cause                                                                                                                                                          |
@@ -114,18 +140,18 @@ Id matching: dashboard `#invite-teammates` ↔ `userflowId="invite-teammates"`,
 
 Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all builds (including release).
 
-| Symptom                                                                                          | Likely cause                                                                                                             | Fix                                                                                                                                                                                                                                                                                                           |
-| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Deep link opens the app but nothing happens                                                      | Scheme added in config but **no native rebuild**                                                                         | `npx expo prebuild` / new development client; Metro reload is not enough                                                                                                                                                                                                                                      |
-| Deep link opens the app but nothing happens, and no **Preview mode** top bar appears             | `Userflow.init()` rejected, so there is no session to preview into                                                       | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken`) and re-open the link                                                                                                                                                       |
-| Killed app opens from a pairing link with no banner, or Preview returns on the wrong step        | Pairing did not resume, or the install joined as a new device while the old presence was still on the topic              | Install `expo-secure-store` so a relaunch can resume. A cold start should show **Connecting to Builder…** immediately, then **Preview mode**, with the flow at step 1. `exitPreview()` or an expired token ends resume                                                                                        |
-| Deep link opens the app and the router shows **Unmatched Route** / "page could not be found"     | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<id>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme                                                                                                                                                              |
-| "Can't select this element" right after pairing, or the app jumps to home when pairing           | Expo Router navigated on the pairing link                                                                                | Add `app/+native-intent.ts` exporting `redirectSystemPath` from `@userflow-tech/react-native/expo-router` (see [deep-linking.md](deep-linking.md#expo-router-hosts))                                                                                                                                          |
-| Pairing deep link ignored (preview URL may still work)                                           | Scheme is `userflow-*` but the id after it is empty or has stray hyphens                                                 | Use the env's `scheme_id` from the dashboard exactly (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`), not the env UUID                                                                                                                                                                                           |
-| Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks                                                                 | Pair again on the device you are watching, or clear the env's pairing session and re-QR                                                                                                                                                                                                                       |
-| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** top bar)                                                             | Confirm the top bar before hitting Preview; re-open the pairing QR on this install                                                                                                                                                                                                                            |
-| QR / `https://…/pair/<jwt>` does nothing in the app                                              | SDK only parses the **scheme** form after the backend redirect                                                           | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl`                                                                                                                                                                                                                  |
-| Builder selector has no screenshot after Confirm                                                 | Missing / unlinked `react-native-view-shot`, or 4.0.3 from Expo SDK 55 and older                                         | Install `react-native-view-shot@^5.0.0` and **rebuild native**. At init, look for `- react-native-view-shot is not linked, so Builder element selection gets no screenshot`. When confirming a pick, look for `[Userflow] Required peer react-native-view-shot is not installed; skipping picker screenshot.` |
+| Symptom                                                                                          | Likely cause                                                                                                             | Fix                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Deep link opens the app but nothing happens                                                      | Scheme added in config but **no native rebuild**                                                                         | `npx expo prebuild` / new development client; Metro reload is not enough                                                                                                                                                                                                                                                                                                                                       |
+| Deep link opens the app but nothing happens, and no **Preview mode** top bar appears             | `Userflow.init()` rejected, so there is no session to preview into                                                       | Check the logs for `[Userflow] Builder pairing link received, but Userflow.init() failed` — fix that error (usually `clientToken`) and re-open the link                                                                                                                                                                                                                                                        |
+| Killed app opens from a pairing link with no banner, or Preview returns on the wrong step        | Pairing did not resume, or the install joined as a new device while the old presence was still on the topic              | Install `expo-secure-store` so a relaunch can resume. A cold start should show **Connecting to Builder…** immediately, then **Preview mode**, with the flow at step 1. `exitPreview()` or an expired token ends resume                                                                                                                                                                                         |
+| Deep link opens the app and the router shows **Unmatched Route** / "page could not be found"     | Deep link is not the root form from the QR; **or** the link was rebuilt with the app's own scheme instead of `scheme_id` | Open the QR unmodified (`userflow-<id>://?pairing_token=…`). If the log says `a scheme Userflow does not own`, do not substitute your app scheme                                                                                                                                                                                                                                                               |
+| "Can't select this element" right after pairing, or the app jumps to home when pairing           | Expo Router navigated on the pairing link                                                                                | Add `app/+native-intent.ts` exporting `redirectSystemPath` from `@userflow-tech/react-native/expo-router` (see [deep-linking.md](deep-linking.md#expo-router-hosts))                                                                                                                                                                                                                                           |
+| Pairing deep link ignored (preview URL may still work)                                           | Scheme is `userflow-*` but the id after it is empty or has stray hyphens                                                 | Use the env's `scheme_id` from the dashboard exactly (e.g. `userflow-v7twv2fw2ja2jaco7kesvowmem`), not the env UUID                                                                                                                                                                                                                                                                                            |
+| Builder says “A device was paired earlier…” and Preview closes immediately after a brief spinner | Stale pairing session still present; a ghost device acks                                                                 | Pair again on the device you are watching, or clear the env's pairing session and re-QR                                                                                                                                                                                                                                                                                                                        |
+| Preview succeeds on the server but the phone stays idle                                          | App is not the paired instance (no **Preview mode** top bar)                                                             | Confirm the top bar before hitting Preview; re-open the pairing QR on this install                                                                                                                                                                                                                                                                                                                             |
+| QR / `https://…/pair/<jwt>` does nothing in the app                                              | SDK only parses the **scheme** form after the backend redirect                                                           | Open via the OS (scan QR) or forward `{schemeId}://?pairing_token=…` with `handlePairingUrl`                                                                                                                                                                                                                                                                                                                   |
+| Builder selector has no screenshot after Confirm                                                 | Missing / unlinked `react-native-view-shot`, or 4.0.3 from Expo SDK 55 and older                                         | Install view-shot (on Expo SDK 56 and 57, `npx expo install react-native-view-shot` unpinned; otherwise `react-native-view-shot@^5.0.0`) and **rebuild native**. At init, look for `- react-native-view-shot is not linked, so Builder element selection gets no screenshot`. When confirming a pick, look for `[Userflow] Required peer react-native-view-shot is not installed; skipping picker screenshot.` |
 
 ## Expo
 
@@ -137,11 +163,12 @@ Full setup: [deep-linking.md](deep-linking.md). Pairing is available in all buil
 
 ## Jest
 
-| Symptom                                                                                                                               | Likely cause                                                                                                                                                   | Fix                                                                                                       |
-| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| Snapshots gain `nativeID="uf_…"`, `collapsable={false}`, `__ufid`, or `__ufManual` props, and keep changing after unrelated JSX edits | The Babel plugin runs under Jest, because `babel-jest` reads `babel.config.js`. Its ids depend on file path, component name, sibling order, and static labels. | Skip the plugin when `api.env('test')` is true. See the README section "Babel plugin and snapshot tests". |
-| `Caching has already been configured with .never or .forever()` after adding `api.env('test')`                                        | `babel.config.js` still calls `api.cache(true)` before `api.env`.                                                                                              | Remove `api.cache(true)`. `api.env` already caches per environment.                                       |
-| Component tests load the SDK after enabling the Babel plugin                                                                          | Full mode imports `@userflow-tech/react-native` into every stamped file.                                                                                       | Mock the SDK in the Jest setup file, or skip the plugin in tests.                                         |
+| Symptom                                                                                                                               | Likely cause                                                                                                                                                                 | Fix                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `Jest encountered an unexpected token` in a test that loads `@userflow-tech/react-native` or one of its subpaths                      | The package's `react-native` entry is TypeScript source, and the app's `transformIgnorePatterns` does not include `@userflow-tech`, so Jest reads that source untransformed. | Add the README's Jest mock to the setup file, with a mock for each subpath the app imports. See the README section "Jest". |
+| Snapshots gain `nativeID="uf_…"`, `collapsable={false}`, `__ufid`, or `__ufManual` props, and keep changing after unrelated JSX edits | The Babel plugin runs under Jest, because `babel-jest` reads `babel.config.js`. Its ids depend on file path, component name, sibling order, and static labels.               | Skip the plugin when `api.env('test')` is true. See the README section "Babel plugin and snapshot tests".                  |
+| `Caching has already been configured with .never or .forever()` after adding `api.env('test')`                                        | `babel.config.js` still calls `api.cache(true)` before `api.env`.                                                                                                            | Remove `api.cache(true)`. `api.env` already caches per environment.                                                        |
+| Component tests load the SDK after enabling the Babel plugin                                                                          | Full mode imports `@userflow-tech/react-native` into every stamped file.                                                                                                     | Mock the SDK in the Jest setup file, or skip the plugin in tests.                                                          |
 
 ## Still stuck?
 

package/expo-plugin/hostDependencyWarnings.d.ts

@@ -7,10 +7,12 @@ export interface HostDependencyWarning {
 /**
  * Prebuild checks that do not change the native config.
  *
- * `react-native-view-shot` must be at least 5. Expo SDK 54's unpinned install
- * resolves 4.0.3. Expo SDK 53 and older only autolink native modules listed in
- * the app's own package.json, so AsyncStorage, WebView, and safe-area-context
- * have to be direct dependencies there. Expo SDK 54 and later autolink
+ * `react-native-view-shot` must be at least 5. On Expo SDK 55 and older an
+ * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0, so a
+ * `^5.0.0` pin there only adds a version mismatch. Expo SDK 53 and older only
+ * autolink native modules listed in the app's own package.json, so
+ * AsyncStorage, WebView, and safe-area-context have to be direct dependencies
+ * there. Expo SDK 54 and later autolink
  * safe-area-context when Expo Router or React Navigation brought it in, so
  * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
  * the package itself cannot be loaded.

package/expo-plugin/hostDependencyWarnings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hostDependencyWarnings.d.ts","sourceRoot":"","sources":["../plugin/hostDependencyWarnings.ts"],"names":[],"mappings":"AAKA,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,wOACoM,CAAC;AAExO,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,qBAAqB,EAAE,CA+CzB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,KAAK,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI,CAaN"}
+{"version":3,"file":"hostDependencyWarnings.d.ts","sourceRoot":"","sources":["../plugin/hostDependencyWarnings.ts"],"names":[],"mappings":"AAKA,kFAAkF;AAClF,eAAO,MAAM,sBAAsB,wOACoM,CAAC;AAExO,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACpC,qBAAqB,EAAE,CA+CzB;AAED,0FAA0F;AAC1F,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,KAAK,GAAG,SAAS,EAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,IAAI,CAaN"}

package/expo-plugin/hostDependencyWarnings.js

@@ -17,10 +17,12 @@ const TRANSITIVE_NATIVE_MODULES = [
 /**
  * Prebuild checks that do not change the native config.
  *
- * `react-native-view-shot` must be at least 5. Expo SDK 54's unpinned install
- * resolves 4.0.3. Expo SDK 53 and older only autolink native modules listed in
- * the app's own package.json, so AsyncStorage, WebView, and safe-area-context
- * have to be direct dependencies there. Expo SDK 54 and later autolink
+ * `react-native-view-shot` must be at least 5. On Expo SDK 55 and older an
+ * unpinned install resolves 4.0.3; Expo SDK 56 and 57 bundle 5.1.0, so a
+ * `^5.0.0` pin there only adds a version mismatch. Expo SDK 53 and older only
+ * autolink native modules listed in the app's own package.json, so
+ * AsyncStorage, WebView, and safe-area-context have to be direct dependencies
+ * there. Expo SDK 54 and later autolink
  * safe-area-context when Expo Router or React Navigation brought it in, so
  * prebuild does not warn about it on those SDKs. `Userflow.init` warns when
  * the package itself cannot be loaded.
@@ -38,7 +40,7 @@ function hostDependencyWarnings(projectRoot, sdkVersion) {
     if (!viewShot) {
         warnings.push({
             property: VIEW_SHOT,
-            message: 'react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 54, an unpinned `npx expo install react-native-view-shot` resolves 4.0.3. Pin ^5.0.0. If expo doctor reports a version mismatch, add "react-native-view-shot" to expo.install.exclude.',
+            message: 'react-native-view-shot is not a direct dependency. Builder element selection needs >=5.0.0. On Expo SDK 56 and 57, run `npx expo install react-native-view-shot` unpinned, with no expo.install.exclude entry for it. On Expo SDK 55 and older, an unpinned install resolves 4.0.3, so pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.',
         });
     }
     else {
@@ -46,7 +48,7 @@ function hostDependencyWarnings(projectRoot, sdkVersion) {
         if (major != null && major < 5) {
             warnings.push({
                 property: VIEW_SHOT,
-                message: `react-native-view-shot@${viewShot} is older than 5.0.0. Expo SDK 54's default is 4.0.3, which does not work with this SDK. Pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude if expo doctor complains.`,
+                message: `react-native-view-shot@${viewShot} is older than 5.0.0, which does not work with this SDK. On Expo SDK 56 and 57, run npx expo install react-native-view-shot unpinned, with no expo.install.exclude entry for it. Expo SDK 55 and older default to 4.0.3: pin ^5.0.0 and add "react-native-view-shot" to expo.install.exclude.`,
             });
         }
     }