tapline-host 1.0.0 → 1.2.0

package/dist/tool-text-data.d.ts

@@ -1,5 +1,5 @@
 /** The shared core block of the MCP `instructions` (TOOL-TEXT section 1). */
-export declare const CORE_INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button @24,610 354x48.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `\u2195` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true`. For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: outside the apps you were given. The first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`) or `no_apps` (you were given none: tell the user).\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.";
+export declare const CORE_INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n- `run` does several steps in one call and stops at the first that fails; `audit` checks the screen's accessibility.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `\u2195` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n- A button, tab or link can be tapped, an input typed into, a switch toggled and a scroll view scrolled; other actions are listed in brackets.\n- A long old value in `(was \"\u2026\")` is cut to what changed, with `\u2026` where it was cut.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true` (never for `disabled`: the app has to enable it). For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: the first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`), `no_apps` (you were given none: tell the user), `needs_confirmation` (a person must OK this touch in the live view; when they have, make the same call again) or `blocked` (the policy forbids it; don't try another way).\n- `expect_failed`: a `run` step's expectation didn't hold. `look`, then fix the step or report the bug.\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- Some touches need a person's OK first (`needs_confirmation`). You can never give it yourself. `dry_run: true` on a touch or on `run` says what would happen without doing it.\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.";
 /** The "Tapline adds" block of the MCP `instructions`. */
 export declare const TAPLINE_ADDS = "Tapline works inside one React Native app and reads its React tree. It calls the app's handlers; it doesn't make real touches.\n- `logs` shows console output and JS errors. `check_layout` and `compare_screen` check the screen. `app_command` runs the app's own test commands.\n- The header may show `Route:` (the current screen) and `Network:` (requests in flight). `wait_for` can wait for `network_idle`.\n- OS alerts, the keyboard, other apps and Home are out of reach. An `Alert:` line from the OS needs the user to tap it. Tapline can't launch apps: `pair` connects one.";
 /** Core tools (TOOL-TEXT section 2): the shared paragraph, and the `Tapline:` line when the tool has one. */
@@ -53,19 +53,36 @@ export declare const CORE_TOOL_TEXT: {
     };
     readonly viewer: {
         readonly shared: "The link to the live view, where the user can watch the app as you work and take over. Their touches go first, and they can pause you. Give the link to the user only.";
-        readonly tapline: "Tapline: opens in a browser; also reports capture time and stutter while frames are on.";
+        readonly tapline: "Tapline: opens the live view in a browser on this computer and keeps its link from you (the key in it approves held-back touches); also reports capture time and stutter while frames are on.";
+    };
+    readonly swipe: {
+        readonly shared: "Drag from `x0, y0` to `x1, y1`, in points, over `seconds` (default 0.35). For sliders, carousels, swipe actions and edge gestures; for lists, use `scroll`.";
+        readonly tapline: "Tapline: drives what React Native's touch system handles (a pan view, a sheet's swipe to close); a gesture that react-native-gesture-handler or a native view handles (sliders, maps) answers `no_action`, and its message says what can make it.";
+    };
+    readonly run: {
+        readonly shared: "Runs several steps in one call, in order, and answers once: `Ran 5 of 5 steps in 3.4 s.` then the changes since your last list. Each step is a tool call written as an object (`{\"tool\": \"tap\", \"target\": {\"id\": \"save\"}}`) with an optional `expect` checked after it: one of text, id or label, with gone, value (a switch: \"on\"/\"off\", or \"true\"/\"false\") and timeout (default 2 s); or `matches` (a `compare_screen` reference the screen must match). It stops at the first step that fails or whose expectation doesn't hold and says which: `Error expect_failed: Ran 3 of 5 steps; stopped at step 4 (tap \"Save\"): its action ran, but text \"Saved\" didn't appear within 2 s.` `expect` matches as `wait_for` does: exact text first, then part of a text. `dry_run: true` checks the steps and says what step 1 would do. Use it to fill a form or walk a flow you're sure of; read the answer before the next batch.";
+        readonly tapline: "Tapline: `expect` looks through the app's whole list, off screen too.";
+    };
+    readonly audit: {
+        readonly shared: "Checks the screen in front for accessibility problems: `contrast`, `hit_region`, `description`, `dynamic_type`, `clipped_text`, `trait`, `element_detection`, `overlap`, `duplicate_id`; `types` narrows it. Answers one numbered issue per line with its fix, then which types were checked. It costs no image: run it on each new screen.";
+        readonly tapline: "Tapline: runs its checks in the app; in a development build each issue adds the file and line that wrote the element. `dynamic_type` and `element_detection` need iOS's own audit, so Tapline lists them as not checked.";
+    };
+    readonly record: {
+        readonly shared: "Record a run as a script that replays without an AI: `start: true` (with a `name`), then every action that succeeds becomes a step, then `stop: true` saves it (to `path`, or under the name). A `wait_for` right after an action becomes that step's `expect`, and a `compare_screen` its `expect.matches`; the reference pictures are saved next to the script. Targets are saved by id, else label, else text (with `index` when it matched several); refs only last one run.";
+    };
+    readonly replay: {
+        readonly shared: "Run a saved script like `run` and answer the same way: it stops at the first step that fails or whose expectation doesn't hold. Give `name` (a saved script) or `path` (a script file); without either, lists saved scripts. It starts the app fresh first unless the script says `\"fresh\": false`. The user can run the same script without an agent (`tapline replay <name>`, `tapwright replay <name>`).";
+        readonly tapline: "Tapline: also stops when a step ends on a different screen (route) than when it was recorded.";
     };
 };
 /** Tapline extras (TOOL-TEXT section 3). */
 export declare const EXTRA_TOOL_TEXT: {
-    readonly check_layout: "Checks the current screen from the element tree, with no screenshot: tap areas under 44x44 pt, elements cut off at the edges, overlaps, text contrast below WCAG, buttons with no label, and text likely cut off. Findings name elements by ref.";
-    readonly compare_screen: "Visual regression: the first call for a `name` (or with `update: true`) saves the screen as the reference; later calls compare it pixel by pixel and report how much changed, where, and an image with changes in red. Keep the same `width` for a name.";
+    readonly check_layout: "A quick layout check of the screen from the element tree, with no screenshot: tap areas under 44x44 pt, elements cut off at the edges, overlaps, text contrast below WCAG, buttons with no label, and text likely cut off. Findings name elements by ref. `audit` covers the same and more, in the shared report format with fixes and code lines; it judges native switches as iOS does.";
+    readonly inspect: "Shows where an element comes from, in a development build: the components that draw it (screen first), the file and line of the app's code that wrote it, that line itself, and the component's props in short. Use it to say where to fix a bug you found. Release builds answer unsupported.";
+    readonly compare_screen: "Visual regression: the first call for a `name` (or with `update: true`) saves the screen as the reference; later calls compare it and answer `Matches` or `Differs` with how much changed, where, and on a difference a picture with the changes in red. `threshold` is the percent that may change and still match (default 0.5); `ignore` paints out elements or rects that always change, such as a clock. Keep the same `width` for a name. In `run` and scripts it is a check: `expect: {\"matches\": name}` on a step, or a `compare_screen` step.";
     readonly filmstrip: "Several screenshots in one numbered image, for animations and loading states; cheaper than separate shots. `tap` first taps an element, then films what it sets off.";
-    readonly record: "Record a run as a script to replay without an AI: `start` with a `name`, then every action becomes a step, then `stop` saves it. Also `status` and `discard`. Targets are saved by id, else label, else text; refs only last one run.";
-    readonly replay: "Run a saved script step by step and report each step. It stops at the first step that fails or ends on a different screen. Without `name`, lists saved scripts.";
     readonly logs: "Recent console output and JS errors from the app (last 500). `since` (epoch ms) returns only newer lines; each result ends with the latest timestamp to reuse.";
     readonly reload: "Reload the JavaScript bundle (development builds only), wait for the app to reconnect, and answer the screen. If it isn't back in time, it says so: `look` again shortly. Other builds answer `unsupported`.";
     readonly app_command: "Without `name`, lists the commands the app offers for testing (switch language, sign in as a test user, load sample data). With `name` and `args`, runs one and answers its result and what changed. Built in: `appearance` (`light`, `dark`, `system`).";
-    readonly swipe: "Drag from `x0, y0` to `x1, y1`, in points, over `seconds` (default 0.35). For sliders, carousels, swipe actions and edge gestures; for lists, use `scroll`.\nTapline: drives what React Native's touch system handles (a pan view, a sheet's swipe to close); a gesture that react-native-gesture-handler or a native view handles (sliders, maps) answers `no_action`, and its message says what can make it.";
-    readonly pair: "Make a pairing link and QR code for the user's phone (valid 10 minutes, works once). The user scans it and taps Connect in the app. Needs the app's URL scheme. Show the user the QR code.";
+    readonly pair: "Connect the user's phone. A development build that loads its JavaScript from this computer asks by itself within a few seconds: the user only taps Connect, and no `scheme` is needed. For TestFlight and release builds, pass the app's URL `scheme` to get a pairing link and QR code (valid 10 minutes, works once) and show the user the QR code.";
 };

package/dist/tool-text-data.js

@@ -1,7 +1,7 @@
 // Generated word for word from tapline-tapwright-drafts/TOOL-TEXT.md (AGENT-TOOLS v1.3 shared tool text).
 // Edit the shared text there, not here. Tapwright lines and blocks are left out on purpose.
 /** The shared core block of the MCP `instructions` (TOOL-TEXT section 1). */
-export const CORE_INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button @24,610 354x48.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `↕` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true`. For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: outside the apps you were given. The first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`) or `no_apps` (you were given none: tell the user).\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.";
+export const CORE_INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n- `run` does several steps in one call and stops at the first that fails; `audit` checks the screen's accessibility.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `↕` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n- A button, tab or link can be tapped, an input typed into, a switch toggled and a scroll view scrolled; other actions are listed in brackets.\n- A long old value in `(was \"…\")` is cut to what changed, with `…` where it was cut.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true` (never for `disabled`: the app has to enable it). For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: the first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`), `no_apps` (you were given none: tell the user), `needs_confirmation` (a person must OK this touch in the live view; when they have, make the same call again) or `blocked` (the policy forbids it; don't try another way).\n- `expect_failed`: a `run` step's expectation didn't hold. `look`, then fix the step or report the bug.\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- Some touches need a person's OK first (`needs_confirmation`). You can never give it yourself. `dry_run: true` on a touch or on `run` says what would happen without doing it.\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.";
 /** The "Tapline adds" block of the MCP `instructions`. */
 export const TAPLINE_ADDS = "Tapline works inside one React Native app and reads its React tree. It calls the app's handlers; it doesn't make real touches.\n- `logs` shows console output and JS errors. `check_layout` and `compare_screen` check the screen. `app_command` runs the app's own test commands.\n- The header may show `Route:` (the current screen) and `Network:` (requests in flight). `wait_for` can wait for `network_idle`.\n- OS alerts, the keyboard, other apps and Home are out of reach. An `Alert:` line from the OS needs the user to tap it. Tapline can't launch apps: `pair` connects one.";
 /** Core tools (TOOL-TEXT section 2): the shared paragraph, and the `Tapline:` line when the tool has one. */
@@ -55,20 +55,37 @@ export const CORE_TOOL_TEXT = {
     },
     "viewer": {
         "shared": "The link to the live view, where the user can watch the app as you work and take over. Their touches go first, and they can pause you. Give the link to the user only.",
-        "tapline": "Tapline: opens in a browser; also reports capture time and stutter while frames are on."
+        "tapline": "Tapline: opens the live view in a browser on this computer and keeps its link from you (the key in it approves held-back touches); also reports capture time and stutter while frames are on."
+    },
+    "swipe": {
+        "shared": "Drag from `x0, y0` to `x1, y1`, in points, over `seconds` (default 0.35). For sliders, carousels, swipe actions and edge gestures; for lists, use `scroll`.",
+        "tapline": "Tapline: drives what React Native's touch system handles (a pan view, a sheet's swipe to close); a gesture that react-native-gesture-handler or a native view handles (sliders, maps) answers `no_action`, and its message says what can make it."
+    },
+    "run": {
+        "shared": "Runs several steps in one call, in order, and answers once: `Ran 5 of 5 steps in 3.4 s.` then the changes since your last list. Each step is a tool call written as an object (`{\"tool\": \"tap\", \"target\": {\"id\": \"save\"}}`) with an optional `expect` checked after it: one of text, id or label, with gone, value (a switch: \"on\"/\"off\", or \"true\"/\"false\") and timeout (default 2 s); or `matches` (a `compare_screen` reference the screen must match). It stops at the first step that fails or whose expectation doesn't hold and says which: `Error expect_failed: Ran 3 of 5 steps; stopped at step 4 (tap \"Save\"): its action ran, but text \"Saved\" didn't appear within 2 s.` `expect` matches as `wait_for` does: exact text first, then part of a text. `dry_run: true` checks the steps and says what step 1 would do. Use it to fill a form or walk a flow you're sure of; read the answer before the next batch.",
+        "tapline": "Tapline: `expect` looks through the app's whole list, off screen too."
+    },
+    "audit": {
+        "shared": "Checks the screen in front for accessibility problems: `contrast`, `hit_region`, `description`, `dynamic_type`, `clipped_text`, `trait`, `element_detection`, `overlap`, `duplicate_id`; `types` narrows it. Answers one numbered issue per line with its fix, then which types were checked. It costs no image: run it on each new screen.",
+        "tapline": "Tapline: runs its checks in the app; in a development build each issue adds the file and line that wrote the element. `dynamic_type` and `element_detection` need iOS's own audit, so Tapline lists them as not checked."
+    },
+    "record": {
+        "shared": "Record a run as a script that replays without an AI: `start: true` (with a `name`), then every action that succeeds becomes a step, then `stop: true` saves it (to `path`, or under the name). A `wait_for` right after an action becomes that step's `expect`, and a `compare_screen` its `expect.matches`; the reference pictures are saved next to the script. Targets are saved by id, else label, else text (with `index` when it matched several); refs only last one run."
+    },
+    "replay": {
+        "shared": "Run a saved script like `run` and answer the same way: it stops at the first step that fails or whose expectation doesn't hold. Give `name` (a saved script) or `path` (a script file); without either, lists saved scripts. It starts the app fresh first unless the script says `\"fresh\": false`. The user can run the same script without an agent (`tapline replay <name>`, `tapwright replay <name>`).",
+        "tapline": "Tapline: also stops when a step ends on a different screen (route) than when it was recorded."
     }
 };
 /** Tapline extras (TOOL-TEXT section 3). */
 export const EXTRA_TOOL_TEXT = {
-    "check_layout": "Checks the current screen from the element tree, with no screenshot: tap areas under 44x44 pt, elements cut off at the edges, overlaps, text contrast below WCAG, buttons with no label, and text likely cut off. Findings name elements by ref.",
-    "compare_screen": "Visual regression: the first call for a `name` (or with `update: true`) saves the screen as the reference; later calls compare it pixel by pixel and report how much changed, where, and an image with changes in red. Keep the same `width` for a name.",
+    "check_layout": "A quick layout check of the screen from the element tree, with no screenshot: tap areas under 44x44 pt, elements cut off at the edges, overlaps, text contrast below WCAG, buttons with no label, and text likely cut off. Findings name elements by ref. `audit` covers the same and more, in the shared report format with fixes and code lines; it judges native switches as iOS does.",
+    "inspect": "Shows where an element comes from, in a development build: the components that draw it (screen first), the file and line of the app's code that wrote it, that line itself, and the component's props in short. Use it to say where to fix a bug you found. Release builds answer unsupported.",
+    "compare_screen": "Visual regression: the first call for a `name` (or with `update: true`) saves the screen as the reference; later calls compare it and answer `Matches` or `Differs` with how much changed, where, and on a difference a picture with the changes in red. `threshold` is the percent that may change and still match (default 0.5); `ignore` paints out elements or rects that always change, such as a clock. Keep the same `width` for a name. In `run` and scripts it is a check: `expect: {\"matches\": name}` on a step, or a `compare_screen` step.",
     "filmstrip": "Several screenshots in one numbered image, for animations and loading states; cheaper than separate shots. `tap` first taps an element, then films what it sets off.",
-    "record": "Record a run as a script to replay without an AI: `start` with a `name`, then every action becomes a step, then `stop` saves it. Also `status` and `discard`. Targets are saved by id, else label, else text; refs only last one run.",
-    "replay": "Run a saved script step by step and report each step. It stops at the first step that fails or ends on a different screen. Without `name`, lists saved scripts.",
     "logs": "Recent console output and JS errors from the app (last 500). `since` (epoch ms) returns only newer lines; each result ends with the latest timestamp to reuse.",
     "reload": "Reload the JavaScript bundle (development builds only), wait for the app to reconnect, and answer the screen. If it isn't back in time, it says so: `look` again shortly. Other builds answer `unsupported`.",
     "app_command": "Without `name`, lists the commands the app offers for testing (switch language, sign in as a test user, load sample data). With `name` and `args`, runs one and answers its result and what changed. Built in: `appearance` (`light`, `dark`, `system`).",
-    "swipe": "Drag from `x0, y0` to `x1, y1`, in points, over `seconds` (default 0.35). For sliders, carousels, swipe actions and edge gestures; for lists, use `scroll`.\nTapline: drives what React Native's touch system handles (a pan view, a sheet's swipe to close); a gesture that react-native-gesture-handler or a native view handles (sliders, maps) answers `no_action`, and its message says what can make it.",
-    "pair": "Make a pairing link and QR code for the user's phone (valid 10 minutes, works once). The user scans it and taps Connect in the app. Needs the app's URL scheme. Show the user the QR code."
+    "pair": "Connect the user's phone. A development build that loads its JavaScript from this computer asks by itself within a few seconds: the user only taps Connect, and no `scheme` is needed. For TestFlight and release builds, pass the app's URL `scheme` to get a pairing link and QR code (valid 10 minutes, works once) and show the user the QR code."
 };
 //# sourceMappingURL=tool-text-data.js.map

package/dist/tool-text-data.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-text-data.js","sourceRoot":"","sources":["../src/tool-text-data.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,4FAA4F;AAE5F,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,spIAAspI,CAAC;AAExrI,0DAA0D;AAC1D,MAAM,CAAC,MAAM,YAAY,GAAG,+jBAA+jB,CAAC;AAE5lB,6GAA6G;AAC7G,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE,wXAAwX;QAClY,SAAS,EAAE,kFAAkF;KAC9F;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,6WAA6W;QACvX,SAAS,EAAE,yCAAyC;KACrD;IACD,YAAY,EAAE;QACZ,QAAQ,EAAE,uJAAuJ;QACjK,SAAS,EAAE,qDAAqD;KACjE;IACD,WAAW,EAAE;QACX,QAAQ,EAAE,kXAAkX;QAC5X,SAAS,EAAE,uDAAuD;KACnE;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,iYAAiY;QAC3Y,SAAS,EAAE,wFAAwF;KACpG;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,sLAAsL;QAChM,SAAS,EAAE,uCAAuC;KACnD;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,2KAA2K;QACrL,SAAS,EAAE,6DAA6D;KACzE;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,4FAA4F;QACtG,SAAS,EAAE,gGAAgG;KAC5G;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,oLAAoL;KAC/L;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,kPAAkP;QAC5P,SAAS,EAAE,4DAA4D;KACxE;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,wFAAwF;QAClG,SAAS,EAAE,iEAAiE;KAC7E;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,6IAA6I;QACvJ,SAAS,EAAE,0IAA0I;KACtJ;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,wKAAwK;QAClL,SAAS,EAAE,yFAAyF;KACrG;CACwF,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,cAAc,EAAE,kPAAkP;IAClQ,gBAAgB,EAAE,0PAA0P;IAC5Q,WAAW,EAAE,sKAAsK;IACnL,QAAQ,EAAE,uOAAuO;IACjP,QAAQ,EAAE,iKAAiK;IAC3K,MAAM,EAAE,gKAAgK;IACxK,QAAQ,EAAE,8MAA8M;IACxN,aAAa,EAAE,0PAA0P;IACzQ,OAAO,EAAE,gZAAgZ;IACzZ,MAAM,EAAE,4LAA4L;CAC3J,CAAC"}
+{"version":3,"file":"tool-text-data.js","sourceRoot":"","sources":["../src/tool-text-data.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,4FAA4F;AAE5F,6EAA6E;AAC7E,MAAM,CAAC,MAAM,iBAAiB,GAAG,w7JAAw7J,CAAC;AAE19J,0DAA0D;AAC1D,MAAM,CAAC,MAAM,YAAY,GAAG,+jBAA+jB,CAAC;AAE5lB,6GAA6G;AAC7G,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE,wXAAwX;QAClY,SAAS,EAAE,kFAAkF;KAC9F;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,6WAA6W;QACvX,SAAS,EAAE,yCAAyC;KACrD;IACD,YAAY,EAAE;QACZ,QAAQ,EAAE,uJAAuJ;QACjK,SAAS,EAAE,qDAAqD;KACjE;IACD,WAAW,EAAE;QACX,QAAQ,EAAE,kXAAkX;QAC5X,SAAS,EAAE,uDAAuD;KACnE;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,iYAAiY;QAC3Y,SAAS,EAAE,wFAAwF;KACpG;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,sLAAsL;QAChM,SAAS,EAAE,uCAAuC;KACnD;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,2KAA2K;QACrL,SAAS,EAAE,6DAA6D;KACzE;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,4FAA4F;QACtG,SAAS,EAAE,gGAAgG;KAC5G;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,oLAAoL;KAC/L;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,kPAAkP;QAC5P,SAAS,EAAE,4DAA4D;KACxE;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,wFAAwF;QAClG,SAAS,EAAE,iEAAiE;KAC7E;IACD,UAAU,EAAE;QACV,QAAQ,EAAE,6IAA6I;QACvJ,SAAS,EAAE,0IAA0I;KACtJ;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,wKAAwK;QAClL,SAAS,EAAE,+LAA+L;KAC3M;IACD,OAAO,EAAE;QACP,QAAQ,EAAE,6JAA6J;QACvK,SAAS,EAAE,mPAAmP;KAC/P;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,s5BAAs5B;QACh6B,SAAS,EAAE,uEAAuE;KACnF;IACD,OAAO,EAAE;QACP,QAAQ,EAAE,6UAA6U;QACvV,SAAS,EAAE,0NAA0N;KACtO;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,kdAAkd;KAC7d;IACD,QAAQ,EAAE;QACR,QAAQ,EAAE,+YAA+Y;QACzZ,SAAS,EAAE,+FAA+F;KAC3G;CACwF,CAAC;AAE5F,4CAA4C;AAC5C,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,cAAc,EAAE,2XAA2X;IAC3Y,SAAS,EAAE,gSAAgS;IAC3S,gBAAgB,EAAE,0hBAA0hB;IAC5iB,WAAW,EAAE,sKAAsK;IACnL,MAAM,EAAE,gKAAgK;IACxK,QAAQ,EAAE,8MAA8M;IACxN,aAAa,EAAE,0PAA0P;IACzQ,MAAM,EAAE,uVAAuV;CACtT,CAAC"}

package/dist/tool-text.d.ts

@@ -2,7 +2,7 @@ import { CORE_TOOL_TEXT, EXTRA_TOOL_TEXT } from "./tool-text-data.js";
 /** Joins a core tool's shared paragraph and its `Tapline:` line. The one place the format lives. */
 export declare function joinToolText(shared: string, tapline?: string): string;
 /** The MCP `instructions`: the shared core block, a blank line, then what Tapline adds. */
-export declare const INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button @24,610 354x48.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `\u2195` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true`. For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: outside the apps you were given. The first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`) or `no_apps` (you were given none: tell the user).\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.\n\nTapline works inside one React Native app and reads its React tree. It calls the app's handlers; it doesn't make real touches.\n- `logs` shows console output and JS errors. `check_layout` and `compare_screen` check the screen. `app_command` runs the app's own test commands.\n- The header may show `Route:` (the current screen) and `Network:` (requests in flight). `wait_for` can wait for `network_idle`.\n- OS alerts, the keyboard, other apps and Home are out of reach. An `Alert:` line from the OS needs the user to tap it. Tapline can't launch apps: `pair` connects one.";
+export declare const INSTRUCTIONS = "You can see and drive a real mobile app, to test it. Work in a loop: look, act, read the answer.\n\nWorkflow\n- `apps` lists what you can drive. `open_app` picks one. `look` reads the screen.\n- Every action answers with what changed. Read it before the next step: check that the action did what you meant, not only that it didn't fail.\n- When the screen is mid-change, `wait` or `wait_for` instead of acting on it. Don't use fixed waits when `wait_for` fits.\n- `run` does several steps in one call and stops at the first that fails; `audit` checks the screen's accessibility.\n\nTargets\n- Tools that act on an element take one `target` with exactly one of: `ref` (from your last list, like \"e3\"), `id` (exact identifier, React Native testID), `label` (exact, ignoring case), `text` (visible text: exact first, then partial), or `x` and `y` (points, for things with no element).\n- `index` (0-based, in reading order) picks among several matches of `id`, `label` or `text`.\n- Prefer `id`, then `ref`, then `label`, then `text`. Use `x` and `y` last.\n\nAnswers\n- The first line says what was done, like `Tapped e3 button \"Log in\" id=login-button.`\n- Then `Same screen. Changes:` with `+` new, `-` gone, `~` changed, `\u2195` moved elements (a `~` line marked `off screen` is a change out of view, and has no ref); or `No visible change.`; or the full list when the screen changed or most of it did. Elements still on screen keep their refs, and anything new counts on from the highest ref given. An element that went away and comes back may have its old ref or a new one: read it from the answer. Only `look` starts again at e1.\n- `Alert:`, `Keyboard:` and similar header lines come first when they changed.\n- `Settled in 0.31 s.` is how long the screen took to settle. `wait` answers `Waited 1.0 s.` instead.\n- `Note:` lines come last. Read them.\n- Positions and sizes are in points, origin top-left.\n- A button, tab or link can be tapped, an input typed into, a switch toggled and a scroll view scrolled; other actions are listed in brackets.\n- A long old value in `(was \"\u2026\")` is cut to what changed, with `\u2026` where it was cut.\n\nErrors: `Error <code>: <message>`. The message says what to do next.\n- `not_found`: nothing matches. `look`, then pick another target.\n- `ambiguous`: several match. Retry with one candidate's ref, or add `index`.\n- `not_actionable`: the first word is the reason: `disabled`, `off_screen`, `covered`, `under_tab_bar`, `behind_alert`, `no_action`. Fix the cause (`scroll` with `to: \"target\"`, close the alert) or pass `force: true` (never for `disabled`: the app has to enable it). For `no_action`, pick another element or tool.\n- `stale`: a person changed the screen since your list. `look` again.\n- `busy`: a person is using the app. Wait a few seconds, retry.\n- `paused`: the user paused you. Ask them to resume.\n- `locked`: the phone is locked. Ask the user to unlock it.\n- `in_background`: the app is in the background. Ask the user to open it.\n- `not_answering`: the app in front stopped answering. Close it and open it again (`close_app`, then `open_app`, where the tool has them), or ask the user to.\n- `reconnecting`: the link dropped. Wait a few seconds, then `look`.\n- `not_connected`: nothing to drive. Follow the setup steps in the message.\n- `timeout`: no answer in time. The action may have happened: `look` before retrying.\n- `bad_params`: the call's arguments are invalid. Fix the call.\n- `unsupported`: this tool can't do it. Use the alternative the message names.\n- `not_allowed`: the first word is the reason: `outside_apps` (another app is in front, or the call names one: go back with `open_app`), `no_apps` (you were given none: tell the user), `needs_confirmation` (a person must OK this touch in the live view; when they have, make the same call again) or `blocked` (the policy forbids it; don't try another way).\n- `expect_failed`: a `run` step's expectation didn't hold. `look`, then fix the step or report the bug.\n- `internal`: a bug. Report it.\n\nScreenshots\n- Actions send none unless you pass `screenshot: true`. `look` sends one: `screenshot: false` skips it, `width` (160-1320 px, default 600) sizes it, `labels: true` draws each actionable element's box and ref.\n- Screenshots cost image tokens. Drive by text, and `look` at the picture only when you need it.\n\nSafety\n- Some touches need a person's OK first (`needs_confirmation`). You can never give it yourself. `dry_run: true` on a touch or on `run` says what would happen without doing it.\n- A person may be watching or driving in the live view (`viewer`). Their input goes first.\n- Don't buy, subscribe, send messages, post, delete data, or change account, privacy or security settings, unless the user asked for exactly that step. Ask when unsure.\n- Use test accounts and test data the user gives you. Don't sign in with credentials you find.\n- Don't read or repeat private content you see beyond what the test needs.\n- Give the live view's link to the user only. It carries a key.\n\nTapline works inside one React Native app and reads its React tree. It calls the app's handlers; it doesn't make real touches.\n- `logs` shows console output and JS errors. `check_layout` and `compare_screen` check the screen. `app_command` runs the app's own test commands.\n- The header may show `Route:` (the current screen) and `Network:` (requests in flight). `wait_for` can wait for `network_idle`.\n- OS alerts, the keyboard, other apps and Home are out of reach. An `Alert:` line from the OS needs the user to tap it. Tapline can't launch apps: `pair` connects one.";
 type CoreName = keyof typeof CORE_TOOL_TEXT;
 type ExtraName = keyof typeof EXTRA_TOOL_TEXT;
 /** The description of a tool that TOOL-TEXT covers, as an agent should read it. */

package/dist/tools.d.ts

@@ -2,6 +2,8 @@ import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type { ControlQueue } from "./control.js";
 import type { InputOutcome, OverlayRead, PersonInput, QualityPreset, ViewerAction } from "./viewer.js";
+import { Confirmations } from "./confirm.js";
+import { type PolicyFile } from "./policy.js";
 import { type TaplineHost } from "./server.js";
 export declare const targetSchema: z.ZodObject<{
     ref: z.ZodOptional<z.ZodString>;
@@ -19,7 +21,7 @@ export declare const toolShapes: {
         readonly app: z.ZodString;
     };
     readonly pair: {
-        readonly scheme: z.ZodString;
+        readonly scheme: z.ZodOptional<z.ZodString>;
     };
     readonly look: {
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
@@ -27,6 +29,30 @@ export declare const toolShapes: {
         readonly labels: z.ZodOptional<z.ZodBoolean>;
     };
     readonly check_layout: {};
+    readonly audit: {
+        readonly types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            contrast: "contrast";
+            hit_region: "hit_region";
+            description: "description";
+            dynamic_type: "dynamic_type";
+            clipped_text: "clipped_text";
+            trait: "trait";
+            element_detection: "element_detection";
+            overlap: "overlap";
+            duplicate_id: "duplicate_id";
+        }>>>;
+    };
+    readonly inspect: {
+        readonly target: z.ZodObject<{
+            ref: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            index: z.ZodOptional<z.ZodNumber>;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    };
     readonly tap: {
         readonly target: z.ZodObject<{
             ref: z.ZodOptional<z.ZodString>;
@@ -37,7 +63,9 @@ export declare const toolShapes: {
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+        readonly index: z.ZodOptional<z.ZodNumber>;
         readonly force: z.ZodOptional<z.ZodBoolean>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -51,8 +79,10 @@ export declare const toolShapes: {
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+        readonly index: z.ZodOptional<z.ZodNumber>;
         readonly seconds: z.ZodOptional<z.ZodNumber>;
         readonly force: z.ZodOptional<z.ZodBoolean>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -67,9 +97,11 @@ export declare const toolShapes: {
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readonly index: z.ZodOptional<z.ZodNumber>;
         readonly replace: z.ZodOptional<z.ZodBoolean>;
         readonly submit: z.ZodOptional<z.ZodBoolean>;
         readonly force: z.ZodOptional<z.ZodBoolean>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -82,9 +114,9 @@ export declare const toolShapes: {
         }>>;
         readonly amount: z.ZodOptional<z.ZodNumber>;
         readonly to: z.ZodOptional<z.ZodEnum<{
+            target: "target";
             end: "end";
             start: "start";
-            target: "target";
         }>>;
         readonly target: z.ZodOptional<z.ZodObject<{
             ref: z.ZodOptional<z.ZodString>;
@@ -95,6 +127,7 @@ export declare const toolShapes: {
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -108,8 +141,10 @@ export declare const toolShapes: {
             x: z.ZodOptional<z.ZodNumber>;
             y: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>;
+        readonly index: z.ZodOptional<z.ZodNumber>;
         readonly value: z.ZodOptional<z.ZodBoolean>;
         readonly force: z.ZodOptional<z.ZodBoolean>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -119,6 +154,7 @@ export declare const toolShapes: {
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
     readonly back: {
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -128,6 +164,7 @@ export declare const toolShapes: {
         readonly x1: z.ZodNumber;
         readonly y1: z.ZodNumber;
         readonly seconds: z.ZodOptional<z.ZodNumber>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
         readonly look: z.ZodOptional<z.ZodBoolean>;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
@@ -141,6 +178,21 @@ export declare const toolShapes: {
         readonly name: z.ZodString;
         readonly update: z.ZodOptional<z.ZodBoolean>;
         readonly width: z.ZodOptional<z.ZodNumber>;
+        readonly threshold: z.ZodOptional<z.ZodNumber>;
+        readonly ignore: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strict>, z.ZodObject<{
+            ref: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            text: z.ZodOptional<z.ZodString>;
+            index: z.ZodOptional<z.ZodNumber>;
+            x: z.ZodOptional<z.ZodNumber>;
+            y: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>]>>>;
     };
     readonly filmstrip: {
         readonly frames: z.ZodOptional<z.ZodNumber>;
@@ -158,16 +210,22 @@ export declare const toolShapes: {
     };
     readonly viewer: {};
     readonly record: {
-        readonly action: z.ZodEnum<{
+        readonly start: z.ZodOptional<z.ZodBoolean>;
+        readonly stop: z.ZodOptional<z.ZodBoolean>;
+        readonly name: z.ZodOptional<z.ZodString>;
+        readonly path: z.ZodOptional<z.ZodString>;
+        readonly action: z.ZodOptional<z.ZodEnum<{
             status: "status";
             start: "start";
             stop: "stop";
             discard: "discard";
-        }>;
-        readonly name: z.ZodOptional<z.ZodString>;
+        }>>;
     };
     readonly replay: {
         readonly name: z.ZodOptional<z.ZodString>;
+        readonly path: z.ZodOptional<z.ZodString>;
+        readonly look: z.ZodOptional<z.ZodBoolean>;
+        readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
     readonly wait_for: {
         readonly text: z.ZodOptional<z.ZodString>;
@@ -189,6 +247,26 @@ export declare const toolShapes: {
         readonly seconds: z.ZodNumber;
         readonly screenshot: z.ZodOptional<z.ZodBoolean>;
     };
+    readonly run: {
+        readonly steps: z.ZodArray<z.ZodObject<{
+            tool: z.ZodString;
+            expect: z.ZodOptional<z.ZodObject<{
+                text: z.ZodOptional<z.ZodString>;
+                id: z.ZodOptional<z.ZodString>;
+                label: z.ZodOptional<z.ZodString>;
+                gone: z.ZodOptional<z.ZodBoolean>;
+                value: z.ZodOptional<z.ZodString>;
+                matches: z.ZodOptional<z.ZodString>;
+                threshold: z.ZodOptional<z.ZodNumber>;
+                ignore: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+                timeout: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+        }, z.core.$loose>>;
+        readonly trace: z.ZodOptional<z.ZodBoolean>;
+        readonly dry_run: z.ZodOptional<z.ZodBoolean>;
+        readonly look: z.ZodOptional<z.ZodBoolean>;
+        readonly screenshot: z.ZodOptional<z.ZodBoolean>;
+    };
 };
 type Shape<K extends keyof typeof toolShapes> = z.infer<z.ZodObject<(typeof toolShapes)[K]>>;
 export interface ConnectInfo {
@@ -199,6 +277,19 @@ export interface ConnectInfo {
 }
 export interface ToolsOptions {
     connect: ConnectInfo;
+    /** Where the action log goes (AGENT-TOOLS 1.8 §12); none: no log. */
+    logDir?: string;
+    /** The safety policy (AGENT-TOOLS 1.8 §11). Default: the built-in words; --no-policy passes empty lists. */
+    policy?: PolicyFile;
+    /** Where a person's OK is asked for and given (the live viewer listens). Default: a fresh one. */
+    confirmations?: Confirmations;
+    /** False when nobody can answer a request (--viewer off). Default true. */
+    canConfirm?: boolean;
+    /**
+     * Where `pair` writes the development offer for the Metro helper (`~/.tapline/offers`), so a phone that can
+     * only reach Metro (a firewall in the way of 7210-7219) still finds it. None: only the host's own endpoint.
+     */
+    offerDir?: string;
     /** Where `pair` also saves the QR code as a PNG (so the user can open it). */
     pairImagePath?: string;
     /** How long that PNG is kept. Default: the code's 10 minutes. */
@@ -226,6 +317,14 @@ export interface ToolsOptions {
     onAction?: (action: ViewerAction) => void;
     /** The live viewer's links (with its token), for the `viewer` tool. */
     viewerLinks?: () => string[];
+    /**
+     * Opens the live view on this computer (the default browser). When set, `viewer` opens it and never
+     * shows the agent the link: its key could approve a held-back touch. Unset (tests) or with
+     * `viewerLinkToAgent`, the link is in the answer.
+     */
+    openViewer?: (link: string) => boolean;
+    /** `--viewer-link`: give the agent the link (benchmarks and scripts that drive the viewer themselves). */
+    viewerLinkToAgent?: boolean;
     /** Whether the app's frames are on and at which quality, for the `viewer` tool's stats. */
     viewerFeed?: () => {
         on: boolean;
@@ -252,6 +351,16 @@ export declare class TaplineTools {
     private readonly host;
     private readonly options;
     private readonly reloadWaitMs;
+    /** The action log (§12), when one is configured. */
+    private readonly actionLog;
+    /** When the action in flight started, for the log's `ms`. */
+    private actionStartedAt;
+    /** Set while `run` runs a step: the log ties the action to its batch. */
+    private batch;
+    /** Extra fields for the next log line (a dry run, a confirmed touch). */
+    private logExtra;
+    readonly confirmations: Confirmations;
+    private readonly policy;
     private readonly reloadSettleMs;
     private readonly noScreenshot;
     private readonly shotFiles;
@@ -269,6 +378,15 @@ export declare class TaplineTools {
     private personNotePending;
     private recording;
     private replaying;
+    /**
+     * While a script replays (AGENT-TOOLS 1.9 §14.3): the references folder next to it (looked in first), where a
+     * failed check puts its red picture, and whether the checks save instead of compare (`--update-references`).
+     */
+    private replayContext;
+    /** Where the latest failed check of the running batch saved its picture. */
+    private diffSaved;
+    /** The elements the latest comparison painted its ignore list from: a recording saves its mask from the same list. */
+    private lastMaskElements;
     /** The screen size in points from the latest list or overlay, for the live viewer's 0..1 positions. */
     private lastScreen;
     private shotCount;
@@ -282,11 +400,25 @@ export declare class TaplineTools {
     /** How to connect an app, shown when nothing is connected. */
     noAppMessage(): string;
     pair(args: Shape<"pair">): Promise<CallToolResult>;
+    /** `<offerDir>/<port>.json` (0600): the open offer for the Metro helper. Never fails the pair call. */
+    private writeOffer;
     apps(): CallToolResult;
     /** One line of the `apps` list. */
     private appLine;
     openApp(args: Shape<"open_app">): CallToolResult;
     look(args?: Shape<"look">): Promise<CallToolResult>;
+    run(args: Shape<"run">): Promise<CallToolResult>;
+    /** `run` with dry_run (§11.4): the steps are checked already; step 1 is resolved, nothing is touched. */
+    private dryRunBatch;
+    /** One step of `run`, as its own tool call without a list. */
+    private runStep;
+    /** The screen's route names now (one cheap read), or null when the app has no router or didn't answer. */
+    private currentRoute;
+    /** Null when the expectation holds within its time; else how it failed. */
+    private expectMissed;
+    private textExpectMissed;
+    inspect(args: Shape<"inspect">): Promise<CallToolResult>;
+    audit(args?: Shape<"audit">): Promise<CallToolResult>;
     checkLayout(_args?: Shape<"check_layout">): Promise<CallToolResult>;
     /** Saves a file-mode screenshot (0600, newest `screenshotKeep` kept) and returns its path. */
     private saveShot;
@@ -296,10 +428,18 @@ export declare class TaplineTools {
     private takePersonNote;
     /** Runs a request, then (unless disabled) appends the fresh element list and how long the app took to settle. */
     private act;
+    /**
+     * When the agent's ref was saved as a testID, label or text that more than one element on screen has, add
+     * the element's `index` among them (reading order), so the replay picks the same one instead of
+     * answering `ambiguous`. One extra read, only while recording and only for ref targets.
+     */
+    private withIndexIfShared;
     /** An element's frame (points) as 0..1 of the screen. */
     private normalized;
     /** The viewer's description of an action: its kind (protocol 1.4), its element's name and where it was. */
     private describeAction;
+    /** One line in the action log (§12). Never fails the action. */
+    private logAction;
     private showAction;
     /** The screen size in points, from the latest list or a fresh overlay read. */
     private screenSize;
@@ -318,15 +458,89 @@ export declare class TaplineTools {
     private takeShot;
     /** Adds an image to a result: inline, or saved with its path in file mode. */
     private deliver;
+    /** Where this app's reference pictures are kept, or an error answer. */
+    private referenceFolder;
+    /** The element list for naming regions and masking, read as a peek: the agent's refs and baseline must stay as they are. */
+    private peekElements;
+    /**
+     * Takes the screen and compares it with the saved reference called `name`, never saving. `referencesDirs` are the
+     * folders to look in, in order. A missing reference hands back the screenshot, so the caller may save it.
+     */
+    private checkAgainstReference;
+    /** Why a check does not hold (for `run`, as a step or as `matches`), or null when it matches. */
+    private referenceReason;
+    /** Whether the screen matches the reference `name` now (`expect.matches`): null when it does, else the reason. */
+    private matchMissed;
+    /** Where a check looks for `<name>.jpg`: the folder next to a replayed script first, then the app's own store. */
+    private referencesDirs;
+    /** In a replay, a failed check leaves its red picture at `<script>.diff/<name>.jpg`. */
+    private keepDiff;
+    /** Takes the screen and saves it as the reference `name` in `dir`. */
+    private saveReferenceHere;
+    private writeReference;
+    /** A `compare_screen` step of `run`: it never saves; it holds on a match and stops the batch otherwise. */
+    private compareStep;
+    /**
+     * Saves a visual check that held as a `compareScreen` step of the recording, when one is running: the name, and the
+     * threshold, the ignore list (refs made stable) and the width when given. `update` is never written. Answers an
+     * error line when an ignore ref can't be kept in a script, else null (also when nothing is recording).
+     */
+    private recordCompare;
+    /**
+     * `ignore` as a script keeps it (AGENT-TOOLS 1.9 §14.2): a ref becomes the element's id, else label, else text,
+     * read from the list now. A string is the error answer when a ref can't be kept.
+     */
+    private stableIgnore;
     compareScreen(args: Shape<"compare_screen">): Promise<CallToolResult>;
+    private compareScreenNow;
     filmstrip(args: Shape<"filmstrip">): Promise<CallToolResult>;
     private scriptPath;
     record(args: Shape<"record">): Promise<CallToolResult>;
+    /** `<script dir>/<script name>.references` and `.diff` for a script file. */
+    private scriptSideFolder;
+    /** Copies each reference the steps use from the app's store next to the script; null when there are none. */
+    private copyReferences;
     private scriptList;
-    replay(args: Shape<"replay">): Promise<CallToolResult>;
+    replay(args: Shape<"replay">, options?: {
+        updateReferences?: boolean;
+    }): Promise<CallToolResult>;
     private withLook;
-    /** The line (without its actions) of the element a result carries under `key`. */
+    /**
+     * The element a result carries under `key`, for an answer's first line: without its actions, position or
+     * size (AGENT-TOOLS 1.8 §13 rule 1; the change block or list has them). `withoutValue` for type_text,
+     * whose sentence says the value (rule 5).
+     */
     private elementName;
+    /**
+     * A guarded touch: the app resolves the target in a dry run, the policy's words are matched against the
+     * element's own label and text, and a confirm word waits for a person's OK in the live view. The check runs
+     * inside the agent's turn, right before the touch, so nothing a person does in between can change what is
+     * touched; when the check can't be made, nothing is touched (fail closed).
+     */
+    private guarded;
+    /**
+     * The policy's verdict on a touch about to happen: stop with an answer (blocked, needs a person's OK, or
+     * the check couldn't be made: fail closed), or go on (`granted` when a person's OK is being used up).
+     */
+    private policyGate;
+    /** Which policy word, if any, the elements the target could mean carry: a block word first, then a confirm word. */
+    private policyWords;
+    private blockedLine;
+    /** A dry run the app answers itself (scroll, back, swipe): its checks, nothing touched, one line. */
+    private dryCall;
+    /** A dry run of a tool the policy doesn't guard (type_text): the app's checks, nothing touched. */
+    private dryRun;
+    /**
+     * What a touch would act on. Apps that know dry runs resolve it themselves, with every check; older
+     * apps only give their element list, and every element the target could mean is checked.
+     */
+    private resolveForPolicy;
+    /** `Would tap e12 button "Delete trip" at 215,640.` */
+    private wouldLine;
+    /** `e12 button "Delete trip"`: ref (when asked), role and name, nothing else. */
+    private shortName;
+    /** A `{ref}` target after a person used the app: refs may point elsewhere. */
+    private staleRef;
     tap(args: Shape<"tap">): Promise<CallToolResult>;
     /** `seconds` is accepted for the shared interface; Tapline calls the handler, so it doesn't hold. */
     longPress(args: Shape<"long_press">): Promise<CallToolResult>;