@revyl/verify 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.5.0 (unreleased)
+
+- Early access: more exact actions on Web, iOS and Android. `doubleTap(at)` double-taps (double-clicks on Web), `longPress(at, { duration })` presses and holds for `duration` milliseconds (1 to 5000, 1500 by default), and `drag(from, to)` presses at one location, moves to the other and releases. They take a description or screenshot pixels like `tap`, and `doubleTap` and `longPress` resolve with the point.
+- Web: `typeFocused(text, { clear })` types into the field that already has focus, without clicking, and replaces its text unless `clear` is `false`, the same default as `type()`. `pressKey` also takes `'tab'`, `'escape'`, `'delete'`, `'space'`, `'arrowup'`, `'arrowdown'`, `'arrowleft'`, `'arrowright'`, `'home'`, `'end'`, `'pageup'` and `'pagedown'`, and `{ modifiers }`: up to four of `'ctrl'`, `'shift'`, `'alt'` and `'meta'`, with which a lowercase letter or digit works too, as in `pressKey('a', { modifiers: ['ctrl'] })`. The `Key` and `KeyModifier` types are exported.
+- iOS and Android: `goHome()` goes to the home screen.
+- A call the platform lacks throws `NOT_AVAILABLE_ON_PLATFORM` before anything is sent, and the message names what to use: `typeFocused` on iOS and Android (use `type(location, text)`), keys other than `'enter'` and `'backspace'` or any modifiers on iOS and Android, and `goHome` on Web. Computers refuse all of them, like the other exact actions.
+- Your own model can choose `double_tap`, `long_press` and `drag` on every platform, `type_focused` and the wider `press_key` on Web, and `go_home` on iOS and Android, with both groundings. The model sees these extra tools in its tool list; the tools it had before send the same requests as 0.4.1.
+- Every existing call sends the same requests as 0.4.1. Your own model choosing `open_url` with a deep link on Web gets the `openUrl()` wording.
+- Docs: the platform table, `api.md`, the web and mobile guides with a script for the new calls, `agents.md` and `llms.txt`.
+
+## Go 0.4.0 (unreleased)
+
+Published as the `go/v0.4.0` tag.
+
+- Early access: more exact actions on Web, iOS and Android, as in TypeScript 0.5.0. `DoubleTap(ctx, at)` and `LongPress(ctx, at, LongPressOptions{Duration})` return the point; `Duration` is whole milliseconds from 1 millisecond to 5 seconds, and zero leaves Revyl's 1.5 seconds. `Drag(ctx, from, to)` presses, moves and releases.
+- Web: `TypeFocused(ctx, text, TypeOptions{Clear})` types into the field that already has focus and replaces its text unless `Clear` points to `false`. `PressKey(ctx, key, KeyOptions{Modifiers})` adds `KeyTab`, `KeyEscape`, `KeyDelete`, `KeySpace`, `KeyArrowUp`, `KeyArrowDown`, `KeyArrowLeft`, `KeyArrowRight`, `KeyHome`, `KeyEnd`, `KeyPageUp` and `KeyPageDown`, and modifiers (`ModifierCtrl`, `ModifierShift`, `ModifierAlt`, `ModifierMeta`), with which `Key("a")` and other lowercase letters and digits work too. Existing `PressKey(ctx, key)` calls compile unchanged.
+- iOS and Android: `GoHome(ctx)`.
+- A call the platform lacks returns `ErrNotAvailableOnPlatform` before anything is sent, naming the alternative. Your own model can choose the new actions with both groundings, so it sees more tools; the tools it had send the same requests as v0.3.1, as does every existing call.
+- `ErrInstructionFailed` names the step and the reason, as TypeScript does: `Instruction failed: "<text>". <reason> See <link>`. The uncertain-action message says "The step deadline passed". Your own model choosing `open_url` with a deep link on Web gets the `OpenURL` wording.
+
+## Python 0.3.0 (unreleased)
+
+- Early access: more exact actions on Web, iOS and Android, as in TypeScript 0.5.0. `double_tap(at)` and `long_press(at, duration=None)` return the point; `duration` is seconds, 0.001 to 5 in whole milliseconds, 1.5 by default. `drag(start, end)` presses, moves and releases.
+- Web: `type_focused(text, clear=True)` types into the field that already has focus and replaces its text unless `clear` is `False`. `press_key(key, modifiers=())` adds `"tab"`, `"escape"`, `"delete"`, `"space"`, the arrows, `"home"`, `"end"`, `"pageup"` and `"pagedown"`, and modifiers (`"ctrl"`, `"shift"`, `"alt"`, `"meta"`), with which a lowercase letter or digit works too. `Key` and `KeyModifier` are exported.
+- iOS and Android: `go_home()`. `AsyncSession` has every new method.
+- A call the platform lacks raises `NOT_AVAILABLE_ON_PLATFORM` before anything is sent, naming the alternative. Your own model can choose the new actions with both groundings, so it sees more tools; the tools it had send the same requests as 0.2.1, as does every existing call.
+- `INSTRUCTION_FAILED` names the step and the reason, as TypeScript does: `Instruction failed: "<text>". <reason> See <link>`, and the progress line for a failed step on your own model ends with the reason. Your own model choosing `open_url` with a deep link on Web gets the `open_url()` wording.
+
+## 0.4.1 (2026-11-12)
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform. On iOS, `tap`, `type`, `swipe`'s `from`, `locate`, `screenSize` and the points `tap` and `type` return used the screen's points (440 × 956 on an iPhone whose screenshots are 1320 × 2868); they now use the screenshot's pixels, and Verify converts them to points for you. A script that passed iOS points must pass screenshot pixels instead: multiply by the screenshot's width over 0.4.0's `screenSize()` width (3 on that iPhone). Android and Web coordinates are unchanged, because their screenshots already match the screen.
+- A point outside the screenshot is refused with `INVALID_ARGUMENT` before any action is sent, and the message names the valid range. The first call in a session that takes or returns a point reads the screen size once (on iOS, plus one screenshot), and later calls reuse it. Before refusing a point, Verify reads the size again, so a rotated device or a resized Web viewport doesn't get a valid point refused. On Android and Web, if the size can't be read, the action is sent as in 0.4.0; on iOS the call fails, because the scale is needed. Calls by description send the same requests as 0.4.0 on Android and Web.
+- `locate()` keeps an off-screen match outside `screenSize()` instead of moving it to the edge, so you can tell it is off screen, and an action at it is refused.
+- `instruction()` and `validation()` on your own model are unchanged: the model still sees screenshots, and Verify still maps its answers to the device.
+- Docs: one coordinate rule in the same words for TypeScript, Python and Go, in the README, `api.md`, the web and mobile guides, `agents.md` and `llms.txt`. Web coordinates are screenshot pixels, which are CSS pixels at the default device scale factor of 1.
+
+## Go 0.3.1 (2026-11-12)
+
+Published as the `go/v0.3.1` tag.
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform, as in TypeScript 0.4.1. On iOS, `Tap`, `Type`, `Swipe`'s `From`, `Locate`, `ScreenSize` and the points `Tap` and `Type` return used the screen's points; they now use the screenshot's pixels, and Verify converts them to points for you. Android and Web coordinates are unchanged.
+- A point outside the screenshot returns `ErrInvalidArgument` before any action is sent, naming the valid range, after Verify reads the size again in case the screen rotated. The screen size is read once per session. On Android and Web a failed size read skips the check and sends the action as before; on iOS it returns the error.
+- README: the same coordinate rule as TypeScript and Python.
+
+## Python 0.2.1 (2026-11-12)
+
+- **Breaking for iOS exact actions (early access):** coordinates are now screenshot pixels on every platform, as in TypeScript 0.4.1. On iOS, `tap`, `type`, `swipe`'s `from_`, `locate`, `screen_size` and the points `tap` and `type` return used the screen's points; they now use the screenshot's pixels, and Verify converts them to points for you. Android and Web coordinates are unchanged. `AsyncSession` behaves the same.
+- A point outside the screenshot raises `INVALID_ARGUMENT` before any action is sent, naming the valid range, after Verify reads the size again in case the screen rotated. The screen size is read once per session. On Android and Web a failed size read skips the check and sends the action as before; on iOS it raises.
+- README: the same coordinate rule as TypeScript and Go.
+
 ## 0.4.0 (2026-11-11)
 
 - Early access: run `instruction()` and `validation()` on your own model. `open('ios', { model: 'anthropic/claude-sonnet-5-5' })` runs every step on Claude with the key from `ANTHROPIC_API_KEY`; a step's `{ model }` overrides it. Built-in providers: Anthropic, OpenAI, Google, OpenRouter, Groq, Cerebras, xAI and Ollama, each reading its usual key variable; `anthropic/` and `openai/` also honour `ANTHROPIC_BASE_URL` and `OPENAI_BASE_URL` for proxies and gateways. `{ id, baseURL, apiKey, headers }` reaches any OpenAI-compatible endpoint, with the key taken only from `apiKey`. Your model names elements and Revyl's grounding model finds them. `StepResult.model` reports turns and tokens. Revyl's agent remains the default.

package/README.md

@@ -1,6 +1,6 @@
 # Verify
 
-![Terminal output from one Verify script beside a Mac computer's Terminal window showing the macOS version, and the screens the script reached in a cloud browser, an Android emulator, and an iOS simulator](https://raw.githubusercontent.com/RevylAI/verify/v0.4.0/docs/images/verify-hero.webp)
+![Terminal output from one Verify script beside a Mac computer's Terminal window showing the macOS version, and the screens the script reached in a cloud browser, an Android emulator, and an iOS simulator](https://raw.githubusercontent.com/RevylAI/verify/v0.5.0/docs/images/verify-hero.webp)
 
 Verify runs end-to-end checks in a cloud browser, iOS simulator, or Android emulator on Revyl. You write what the agent should do and what must be true afterward, in plain sentences, and call it from a script, a coding agent, CI, or the test runner you already use. When you know exactly what to press, you can tap, type and swipe yourself instead. Verify also opens Mac computers for commands, files, and screenshots.
 
@@ -41,24 +41,26 @@ Or set it up yourself:
 npx @revyl/verify init
 ```
 
-`init` adds Verify to your project, asks what to open, writes `verify.config.ts` and an example script, signs you in through the browser on the first interactive run, and prints the command that runs the example. With no app id, the iOS and Android examples open the built-in Settings app, so they run on a new account before you upload anything. To skip the config, run `npm install @revyl/verify` and save the example above as `verify/check.mts`, then run `node verify/check.mts`. [Getting started](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/ci.md).
+`init` adds Verify to your project, asks what to open, writes `verify.config.ts` and an example script, signs you in through the browser on the first interactive run, and prints the command that runs the example. With no app id, the iOS and Android examples open the built-in Settings app, so they run on a new account before you upload anything. To skip the config, run `npm install @revyl/verify` and save the example above as `verify/check.mts`, then run `node verify/check.mts`. [Getting started](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/getting-started.md) covers sign-in, your own app, and [CI](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/ci.md).
 
-For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.4.0/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.4.0/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.4.0/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.4.0/examples/mac-workspace/), a small [agent platform](https://github.com/RevylAI/verify/tree/v0.4.0/examples/agent-platform/) that runs web and iOS side by side, and [your own model](https://github.com/RevylAI/verify/tree/v0.4.0/examples/byo-model/) (with [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/examples/byo_model.py) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/examples/byomodel/main.go) versions).
+For finished projects, see [`examples/`](https://github.com/RevylAI/verify/tree/v0.5.0/examples/): a [web store](https://github.com/RevylAI/verify/tree/v0.5.0/examples/web-store/), [mobile Settings](https://github.com/RevylAI/verify/tree/v0.5.0/examples/mobile-settings/), a [Mac workspace](https://github.com/RevylAI/verify/tree/v0.5.0/examples/mac-workspace/), a small [agent platform](https://github.com/RevylAI/verify/tree/v0.5.0/examples/agent-platform/) that runs web and iOS side by side, and [your own model](https://github.com/RevylAI/verify/tree/v0.5.0/examples/byo-model/) (with [Python](https://github.com/RevylAI/verify/blob/v0.5.0/python/examples/byo_model.py) and [Go](https://github.com/RevylAI/verify/blob/v0.5.0/go/examples/byomodel/main.go) versions).
 
 ## Exact actions
 
-Tap, type, swipe and press keys yourself, by a description Revyl locates on screen or by coordinates, in the same script as your steps:
+Tap, double-tap, long-press, drag, type, swipe and press keys yourself, by a description Revyl locates on screen or by coordinates, in the same script as your steps:
 
 ```ts
 await session.type({ target: 'Email field' }, 'demo@example.com');   // Revyl finds the element you describe
 await session.pressKey('enter');
 await session.swipe('up');                                            // scrolls the content down
-await session.tap({ x: 196, y: 640 });                                // or device coordinates
+await session.tap({ x: 196, y: 640 });                                // or a point in screenshot pixels
+await session.longPress({ target: 'First message row' });             // press and hold, 1.5 s by default
+await session.drag({ target: 'Third item handle' }, { target: 'First item' });  // press, move, release
 await session.instruction('Accept the terms if they are shown');      // the agent where it's fuzzy
 await session.validation('The welcome screen is shown');
 ```
 
-`back`, `openUrl`, `launchApp`, `locate` and `screenSize` round them out; [which call works where](#which-call-works-where) shows the platform limits. Early access. In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.3.0); the [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md#exact-actions) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/README.md#exact-actions) READMEs show them with each language's names. The [web](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/web.md#exact-actions) and [mobile](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/mobile.md#exact-actions) guides have runnable scripts, and [api.md](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/api.md#exact-actions) lists every call.
+`doubleTap`, `typeFocused`, `back`, `goHome`, `openUrl`, `launchApp`, `locate` and `screenSize` round them out; [which call works where](#which-call-works-where) shows the platform limits. Early access. Since TypeScript (`@revyl/verify`) 0.4.0, Python (`revyl-verify`) 0.2.0 and Go v0.3.0. `doubleTap`, `longPress`, `drag`, `typeFocused`, `goHome`, and Web keys and modifiers in `pressKey`, are new in TypeScript 0.5.0, Python 0.3.0 and Go v0.4.0. The [Python](https://github.com/RevylAI/verify/blob/v0.5.0/python/README.md#exact-actions) and [Go](https://github.com/RevylAI/verify/blob/v0.5.0/go/README.md#exact-actions) READMEs show them with each language's names. The [web](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/web.md#exact-actions) and [mobile](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/mobile.md#exact-actions) guides have runnable scripts, and [api.md](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/api.md#exact-actions) lists every call.
 
 ## Your own model
 
@@ -72,7 +74,7 @@ await session.instruction('Open Privacy', { model: 'openai/gpt-5.5' });
 await open('ios', { model: { id: 'qwen-3.8-27b', baseURL: 'https://api.cerebras.ai/v1', apiKey: process.env.CEREBRAS_API_KEY } });
 ```
 
-In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.3.0); the [Python](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md#your-own-model) and [Go](https://github.com/RevylAI/verify/blob/v0.4.0/go/README.md#your-own-model) READMEs show them with each language's names. Built in: `anthropic`, `openai`, `google`, `openrouter`, `groq`, `cerebras`, `xai` and `ollama`; anything OpenAI-compatible works through `baseURL`. Early access; [Use your own model](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/own-model.md) covers the providers, picking a model, what Revyl still sees, limits and troubleshooting.
+Since TypeScript (`@revyl/verify`) 0.4.0, Python (`revyl-verify`) 0.2.0 and Go v0.3.0; the [Python](https://github.com/RevylAI/verify/blob/v0.5.0/python/README.md#your-own-model) and [Go](https://github.com/RevylAI/verify/blob/v0.5.0/go/README.md#your-own-model) READMEs show them with each language's names. Built in: `anthropic`, `openai`, `google`, `openrouter`, `groq`, `cerebras`, `xai` and `ollama`; anything OpenAI-compatible works through `baseURL`. Early access; [Use your own model](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/own-model.md) covers the providers, picking a model, what Revyl still sees, limits and troubleshooting.
 
 ## Packages
 
@@ -80,8 +82,8 @@ In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.
 | --- | --- | --- |
 | [`@revyl/verify`](https://www.npmjs.com/package/@revyl/verify) | `npm install @revyl/verify` | TypeScript SDK and the `verify` CLI (`init`, `login`, `logout`, `whoami`). Published on npm, Node.js 22.18 or later. |
 | [`revyl-verify`](https://www.npmjs.com/package/revyl-verify) (npm) | `npm install revyl-verify` | Alias of `@revyl/verify` at the same version. |
-| [Go module](https://github.com/RevylAI/verify/tree/go/v0.3.0/go) | `go get github.com/RevylAI/verify/go@v0.3.0` | Published as the `go/v0.3.0` tag, Go 1.26.9 or later. Calls return errors instead of throwing. |
-| [`revyl-verify`](https://pypi.org/project/revyl-verify/) (PyPI) | `pip install revyl-verify` or `uv add revyl-verify` | Python SDK, published on PyPI. Python 3.10 or later, sync and asyncio APIs, no CLI; see the [Python guide](https://github.com/RevylAI/verify/blob/v0.4.0/python/README.md). |
+| [Go module](https://github.com/RevylAI/verify/tree/go/v0.4.0/go) | `go get github.com/RevylAI/verify/go@v0.4.0` | Published as the `go/v0.4.0` tag, Go 1.26.9 or later. Calls return errors instead of throwing. |
+| [`revyl-verify`](https://pypi.org/project/revyl-verify/) (PyPI) | `pip install revyl-verify` or `uv add revyl-verify` | Python SDK, published on PyPI. Python 3.10 or later, sync and asyncio APIs, no CLI; see the [Python guide](https://github.com/RevylAI/verify/blob/v0.5.0/python/README.md). |
 
 ## Platforms
 
@@ -96,8 +98,11 @@ In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.
 
 | Call | Web | iOS | Android | Mac computer |
 | --- | --- | --- | --- | --- |
-| `tap`, `type`, `swipe`, `pressKey`, `locate`, `screenSize` | Yes | Yes | Yes | No, use `exec()` and files |
+| `tap`, `doubleTap`, `longPress`, `type`, `swipe`, `drag`, `locate`, `screenSize` | Yes | Yes | Yes | No, use `exec()` and files |
+| `pressKey(key, { modifiers })` | Yes: `'enter'`, `'backspace'`, `'tab'`, `'escape'`, arrows and more, with modifiers | `'enter'` and `'backspace'` only | `'enter'` and `'backspace'` only | No |
+| `typeFocused(text)` | Yes, types into the focused field | No, use `type(location, text)` | No, use `type(location, text)` | No |
 | `back()` | Yes, browser history | No, tap the on-screen back control | Yes, the system back button | No |
+| `goHome()` | No, use `openUrl` or `navigate` | Yes, the home screen | Yes, the home screen | No |
 | `openUrl(url)` | Yes, loads an http(s) URL in the tab | Yes, a URL or deep link | Yes, a URL or deep link | No |
 | `launchApp(bundleId)` | No, use `openUrl` or `navigate` | Yes | Yes | No |
 | `navigate(url)` | Yes | No, use `openUrl` | No, use `openUrl` | No |
@@ -105,18 +110,20 @@ In TypeScript (`@revyl/verify` 0.4.0), Python (`revyl-verify` 0.2.0) and Go (v0.
 | `screenshot()` | Yes | Yes | Yes | Yes |
 | `exec`, files, processes | No, open a Mac computer | No, open a Mac computer | No, open a Mac computer | Yes |
 
-Coordinates are in iOS points, Android pixels and Web CSS pixels, from the top-left corner. A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM`, and its message names the alternative.
+**Coordinates.** Prefer a description, such as `tap({ target: 'Sign in button' })`: Revyl finds the element on the current screen, and you never handle coordinates. Otherwise a point is `{ x, y }` in screenshot pixels on every platform: whole numbers from the top-left corner of the image `screenshot()` returns. So a position you read off a screenshot goes to `tap()`, `type()`, `swipe()` and every other exact action unchanged. `screenSize()` returns the screenshot's width and height, and `locate()` and the points `tap()`, `doubleTap()`, `longPress()` and `type()` return use the same pixels. A point outside the screenshot is refused with `INVALID_ARGUMENT` before any action is sent, and the message names the valid range. On iOS, Verify converts the pixels to the screen's points for you. On Web they equal CSS pixels at the default device scale factor of 1, and you still pass screenshot pixels at any other. This holds from TypeScript 0.4.1, Python 0.2.1 and Go v0.3.1; earlier versions took iOS points.
 
-Web is available to every organization. Mac computers are early access and have a server-bounded lifetime; see [computers](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/computers.md).
+A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM`, and its message names the alternative.
+
+Web is available to every organization. Mac computers are early access and have a server-bounded lifetime; see [computers](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/computers.md).
 
 ## Documentation
 
-The [documentation](https://github.com/RevylAI/verify/tree/v0.4.0/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/ci.md), [your own model](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/own-model.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/end-to-end.md). The npm package ships these pages in `node_modules/@revyl/verify/docs/`, with an [llms.txt](https://github.com/RevylAI/verify/blob/v0.4.0/packages/verify/docs/llms.txt) index, so a coding agent can read the docs for the version you installed. The Revyl docs site has an overview at [docs.revyl.com/verify](https://docs.revyl.com/verify).
+The [documentation](https://github.com/RevylAI/verify/tree/v0.5.0/packages/verify/docs/) covers the [API](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/api.md), [configuration](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/configuration.md), [web](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/web.md), [mobile](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/mobile.md), [computers](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/computers.md), [CI](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/ci.md), [your own model](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/own-model.md), [errors and troubleshooting](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/errors.md), [coding agents](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/agents.md), and [live end-to-end results](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/end-to-end.md). The npm package ships these pages in `node_modules/@revyl/verify/docs/`, with an [llms.txt](https://github.com/RevylAI/verify/blob/v0.5.0/packages/verify/docs/llms.txt) index, so a coding agent can read the docs for the version you installed. The Revyl docs site has an overview at [docs.revyl.com/verify](https://docs.revyl.com/verify).
 
 ## Status
 
-Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.4.0/CHANGELOG.md) records each release. Mac computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.4.0/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.4.0/RELEASING.md) to work on Verify.
+Verify is at 0.x, so APIs can still change between minor releases; the [changelog](https://github.com/RevylAI/verify/blob/v0.5.0/CHANGELOG.md) records each release. Mac computers are early access. See [Contributing](https://github.com/RevylAI/verify/blob/v0.5.0/CONTRIBUTING.md) and [Releasing](https://github.com/RevylAI/verify/blob/v0.5.0/RELEASING.md) to work on Verify.
 
 ## License
 
-[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.4.0/LICENSE).
+[Apache 2.0](https://github.com/RevylAI/verify/blob/v0.5.0/LICENSE).

package/dist/agent/loop.d.ts

@@ -1,5 +1,5 @@
 import type { ModelAdapter } from './model.js';
-/** A point in device units: iOS points, Android and Web pixels, from the top-left corner. */
+/** A point in screenshot pixels, from the top-left corner. */
 export interface Point {
     x: number;
     y: number;
@@ -10,27 +10,69 @@ export interface Target {
 }
 export type Location = Point | Target;
 export type SwipeDirection = 'up' | 'down' | 'left' | 'right';
+/** Keys pressKey() takes on Web. iOS and Android take only 'enter' and 'backspace'. */
+export declare const WEB_KEYS: {
+    readonly enter: "Enter";
+    readonly backspace: "Backspace";
+    readonly tab: "Tab";
+    readonly escape: "Escape";
+    readonly delete: "Delete";
+    readonly space: "Space";
+    readonly arrowup: "ArrowUp";
+    readonly arrowdown: "ArrowDown";
+    readonly arrowleft: "ArrowLeft";
+    readonly arrowright: "ArrowRight";
+    readonly home: "Home";
+    readonly end: "End";
+    readonly pageup: "PageUp";
+    readonly pagedown: "PageDown";
+};
+export type Key = keyof typeof WEB_KEYS;
+export type KeyModifier = 'ctrl' | 'shift' | 'alt' | 'meta';
 export type DeviceAction = {
     kind: 'tap';
     at: Location;
+} | {
+    kind: 'double_tap';
+    at: Location;
+} | {
+    kind: 'long_press';
+    at: Location;
+    durationMs?: number;
 } | {
     kind: 'type';
     at: Location;
     text: string;
     clear: boolean;
+} | {
+    kind: 'type_focused';
+    text: string;
+    clear: boolean;
 } | {
     kind: 'swipe';
     direction: SwipeDirection;
     from?: Location;
+} | {
+    kind: 'drag';
+    from: Location;
+    to: Location;
 } | {
     kind: 'key';
-    key: 'enter' | 'backspace';
+    key: string;
+    modifiers?: KeyModifier[];
 } | {
     kind: 'back';
+} | {
+    kind: 'go_home';
 } | {
     kind: 'open_url';
     url: string;
 };
+/** Checks a key and its modifiers for the platform, before any request. */
+export declare function checkKey(platform: string, key: unknown, modifiers?: unknown): {
+    key: string;
+    modifiers: KeyModifier[];
+};
 /** What the agent loop needs from a session. DeviceSession provides it. */
 export interface AgentControls {
     readonly platform: 'ios' | 'android' | 'web';

package/dist/agent/loop.js

@@ -1,6 +1,40 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { VerifyError, errorMessage, isVerifyError } from '../errors.js';
 import { fitPng } from './image.js';
+/** Keys pressKey() takes on Web. iOS and Android take only 'enter' and 'backspace'. */
+export const WEB_KEYS = {
+    enter: 'Enter',
+    backspace: 'Backspace',
+    tab: 'Tab',
+    escape: 'Escape',
+    delete: 'Delete',
+    space: 'Space',
+    arrowup: 'ArrowUp',
+    arrowdown: 'ArrowDown',
+    arrowleft: 'ArrowLeft',
+    arrowright: 'ArrowRight',
+    home: 'Home',
+    end: 'End',
+    pageup: 'PageUp',
+    pagedown: 'PageDown',
+};
+/** Checks a key and its modifiers for the platform, before any request. */
+export function checkKey(platform, key, modifiers = []) {
+    if (!Array.isArray(modifiers) || modifiers.length > 4 || !modifiers.every((modifier) => ['ctrl', 'shift', 'alt', 'meta'].includes(modifier))) {
+        throw new VerifyError('INVALID_ARGUMENT', "pressKey() modifiers are up to four of 'ctrl', 'shift', 'alt' and 'meta'.");
+    }
+    if (platform !== 'web') {
+        if ((key === 'enter' || key === 'backspace') && !modifiers.length)
+            return { key, modifiers: [] };
+        if (modifiers.length || (typeof key === 'string' && key in WEB_KEYS)) {
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', "On iOS and Android, pressKey() takes only 'enter' or 'backspace', with no modifiers; tap the on-screen control instead.");
+        }
+        throw new VerifyError('INVALID_ARGUMENT', "pressKey() takes 'enter' or 'backspace'.");
+    }
+    if (typeof key === 'string' && (key in WEB_KEYS || (/^[a-z0-9]$/.test(key) && modifiers.length)))
+        return { key, modifiers: [...modifiers] };
+    throw new VerifyError('INVALID_ARGUMENT', `pressKey() takes one of ${Object.keys(WEB_KEYS).map((name) => `'${name}'`).join(', ')}, or a lowercase letter or digit with modifiers, such as pressKey('a', { modifiers: ['ctrl'] }).`);
+}
 /** Runs instructions and validations on a model you choose, on your machine. Revyl only receives device actions. */
 export function localAgent(options) {
     if (!options || typeof options.model?.complete !== 'function' || typeof options.model.name !== 'string') {
@@ -93,45 +127,67 @@ export async function runLocalStep(type, task, agent, controls, signal, log) {
 }
 function toAction(call, platform, grounding, image, size) {
     const args = call.arguments;
-    const location = (required) => {
+    const location = (required, prefix = '') => {
+        const [target, x, y] = [args[`${prefix}target`], args[`${prefix}x`], args[`${prefix}y`]];
         if (grounding === 'revyl') {
-            if (typeof args.target === 'string' && args.target.trim())
-                return { target: args.target.trim().slice(0, 500) };
+            if (typeof target === 'string' && target.trim())
+                return { target: target.trim().slice(0, 500) };
             if (required)
-                throw new VerifyError('INVALID_ARGUMENT', 'target is required: describe the element by its visible text or appearance.');
+                throw new VerifyError('INVALID_ARGUMENT', `${prefix}target is required: describe the element by its visible text or appearance.`);
             return undefined;
         }
-        if (typeof args.x !== 'number' || typeof args.y !== 'number') {
+        if (typeof x !== 'number' || typeof y !== 'number') {
             if (required)
-                throw new VerifyError('INVALID_ARGUMENT', 'x and y are required.');
+                throw new VerifyError('INVALID_ARGUMENT', `${prefix}x and ${prefix}y are required.`);
             return undefined;
         }
-        if (args.x < 0 || args.y < 0 || args.x >= image.width || args.y >= image.height) {
-            throw new VerifyError('INVALID_ARGUMENT', `(${args.x}, ${args.y}) is outside the ${image.width}x${image.height} screenshot.`);
+        if (x < 0 || y < 0 || x >= image.width || y >= image.height) {
+            throw new VerifyError('INVALID_ARGUMENT', `(${x}, ${y}) is outside the ${image.width}x${image.height} screenshot.`);
         }
-        return { x: Math.round((args.x * size.width) / image.width), y: Math.round((args.y * size.height) / image.height) };
+        return { x: Math.round((x * size.width) / image.width), y: Math.round((y * size.height) / image.height) };
     };
     switch (call.name) {
         case 'tap':
             return { kind: 'tap', at: location(true) };
+        case 'double_tap':
+            return { kind: 'double_tap', at: location(true) };
+        case 'long_press':
+            return { kind: 'long_press', at: location(true) };
         case 'type':
             if (typeof args.text !== 'string')
                 throw new VerifyError('INVALID_ARGUMENT', 'text is required.');
             return { kind: 'type', at: location(true), text: args.text, clear: args.clear !== false };
+        case 'type_focused':
+            if (platform !== 'web')
+                throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'type_focused is available only in a web browser; use type, which taps the field first.');
+            if (typeof args.text !== 'string')
+                throw new VerifyError('INVALID_ARGUMENT', 'text is required.');
+            return { kind: 'type_focused', text: args.text, clear: args.clear !== false };
+        case 'drag':
+            return { kind: 'drag', from: location(true, 'from_'), to: location(true, 'to_') };
         case 'swipe': {
             if (!['up', 'down', 'left', 'right'].includes(String(args.direction)))
                 throw new VerifyError('INVALID_ARGUMENT', 'direction must be up, down, left or right.');
             const from = location(false);
             return { kind: 'swipe', direction: args.direction, ...(from ? { from } : {}) };
         }
-        case 'press_key':
-            if (args.key !== 'enter' && args.key !== 'backspace')
-                throw new VerifyError('INVALID_ARGUMENT', 'key must be enter or backspace.');
-            return { kind: 'key', key: args.key };
+        case 'press_key': {
+            if (platform !== 'web') {
+                if (args.key !== 'enter' && args.key !== 'backspace')
+                    throw new VerifyError('INVALID_ARGUMENT', 'key must be enter or backspace.');
+                return { kind: 'key', key: args.key };
+            }
+            const { key, modifiers } = checkKey(platform, args.key, args.modifiers ?? []);
+            return { kind: 'key', key, ...(modifiers.length ? { modifiers } : {}) };
+        }
         case 'back':
             if (platform === 'ios')
                 throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'iOS has no back button; tap the on-screen back control.');
             return { kind: 'back' };
+        case 'go_home':
+            if (platform === 'web')
+                throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'A web browser has no home screen; use open_url to load a page.');
+            return { kind: 'go_home' };
         case 'open_url':
             if (typeof args.url !== 'string' || !args.url)
                 throw new VerifyError('INVALID_ARGUMENT', 'url is required.');
@@ -145,14 +201,24 @@ function describe(action) {
     switch (action.kind) {
         case 'tap':
             return `tap${where(action.at)}`;
+        case 'double_tap':
+            return `double tap${where(action.at)}`;
+        case 'long_press':
+            return `long press${where(action.at)}`;
         case 'type':
             return `type ${JSON.stringify(action.text.length > 40 ? `${action.text.slice(0, 40)}…` : action.text)} into${where(action.at)}`;
+        case 'type_focused':
+            return `type ${JSON.stringify(action.text.length > 40 ? `${action.text.slice(0, 40)}…` : action.text)} into the focused field`;
         case 'swipe':
             return `swipe ${action.direction}${action.from ? ` from${where(action.from)}` : ''}`;
+        case 'drag':
+            return `drag from${where(action.from)} to${where(action.to)}`;
         case 'key':
-            return `press ${action.key}`;
+            return `press ${[...(action.modifiers ?? []), action.key].join('+')}`;
         case 'back':
             return 'back';
+        case 'go_home':
+            return 'home';
         case 'open_url':
             return `open ${action.url}`;
     }
@@ -188,25 +254,57 @@ function instructionTools(platform, grounding) {
     const at = grounding === 'revyl'
         ? { properties: { target: { type: 'string', description: 'The element, by its visible text or look.' } }, required: ['target'] }
         : { properties: { x: { type: 'integer', description: 'Screenshot pixel x.' }, y: { type: 'integer', description: 'Screenshot pixel y.' } }, required: ['x', 'y'] };
-    const tools = [
+    const prefixed = (prefix) => ({
+        properties: Object.fromEntries(Object.entries(at.properties).map(([name, schema]) => [`${prefix}${name}`, schema])),
+        required: at.required.map((name) => `${prefix}${name}`),
+    });
+    const [from, to] = [prefixed('from_'), prefixed('to_')];
+    const web = platform === 'web';
+    return [
         { name: 'tap', description: 'Tap an element.', parameters: { type: 'object', ...at } },
+        { name: 'double_tap', description: 'Double-tap an element.', parameters: { type: 'object', ...at } },
+        { name: 'long_press', description: 'Press and hold an element, for example to open a context menu.', parameters: { type: 'object', ...at } },
         {
             name: 'type',
             description: 'Tap a text field and type into it. Clears the field first unless clear is false.',
             parameters: { type: 'object', properties: { ...at.properties, text: { type: 'string' }, clear: { type: 'boolean' } }, required: [...at.required, 'text'] },
         },
+        ...(web
+            ? [{
+                    name: 'type_focused',
+                    description: 'Type into the field that already has focus, without tapping. Clears the field first unless clear is false.',
+                    parameters: { type: 'object', properties: { text: { type: 'string' }, clear: { type: 'boolean' } }, required: ['text'] },
+                }]
+            : []),
         {
             name: 'swipe',
             description: "Swipe from a point, or from the screen's center. up moves the finger up, which scrolls content down.",
             parameters: { type: 'object', properties: { direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] }, ...at.properties }, required: ['direction'] },
         },
-        { name: 'press_key', description: 'Press a key on the focused field.', parameters: { type: 'object', properties: { key: { type: 'string', enum: ['enter', 'backspace'] } }, required: ['key'] } },
-        { name: 'open_url', description: platform === 'web' ? 'Load a URL in the current tab.' : 'Open a URL or deep link on the device.', parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
+        {
+            name: 'drag',
+            description: 'Press an element, move it to another place and release, for example to reorder a list or move a slider.',
+            parameters: { type: 'object', properties: { ...from.properties, ...to.properties }, required: [...from.required, ...to.required] },
+        },
+        web
+            ? {
+                name: 'press_key',
+                description: 'Press a key on the focused element, optionally with modifiers held, such as escape, tab, arrowdown, or a with ctrl.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        key: { type: 'string', description: `One of ${Object.keys(WEB_KEYS).join(', ')}, or a lowercase letter or digit when modifiers are given.` },
+                        modifiers: { type: 'array', items: { type: 'string', enum: ['ctrl', 'shift', 'alt', 'meta'] } },
+                    },
+                    required: ['key'],
+                },
+            }
+            : { name: 'press_key', description: 'Press a key on the focused field.', parameters: { type: 'object', properties: { key: { type: 'string', enum: ['enter', 'backspace'] } }, required: ['key'] } },
+        ...(platform !== 'ios' ? [{ name: 'back', description: web ? 'Go back in browser history.' : 'Press the Android back button.', parameters: { type: 'object', properties: {} } }] : []),
+        ...(!web ? [{ name: 'go_home', description: 'Go to the home screen.', parameters: { type: 'object', properties: {} } }] : []),
+        { name: 'open_url', description: web ? 'Load a URL in the current tab.' : 'Open a URL or deep link on the device.', parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] } },
         { name: 'done', description: 'Finish the task.', parameters: { type: 'object', properties: { success: { type: 'boolean' }, reason: { type: 'string' } }, required: ['success', 'reason'] } },
     ];
-    if (platform !== 'ios')
-        tools.splice(4, 0, { name: 'back', description: platform === 'web' ? 'Go back in browser history.' : 'Press the Android back button.', parameters: { type: 'object', properties: {} } });
-    return tools;
 }
 function bounded(value, min, max, name) {
     if (!Number.isInteger(value) || value < min || value > max)

package/dist/computer-session.d.ts

@@ -29,9 +29,14 @@ export declare class ComputerSession implements Session {
     navigate(): Promise<never>;
     tap(): Promise<never>;
     type(): Promise<never>;
+    typeFocused(): Promise<never>;
+    doubleTap(): Promise<never>;
+    longPress(): Promise<never>;
     swipe(): Promise<never>;
+    drag(): Promise<never>;
     pressKey(): Promise<never>;
     back(): Promise<never>;
+    goHome(): Promise<never>;
     openUrl(): Promise<never>;
     launchApp(): Promise<never>;
     locate(): Promise<never>;

package/dist/computer-session.js

@@ -129,15 +129,30 @@ export class ComputerSession {
     type() {
         return this.unavailable('type');
     }
+    typeFocused() {
+        return this.unavailable('typeFocused');
+    }
+    doubleTap() {
+        return this.unavailable('doubleTap');
+    }
+    longPress() {
+        return this.unavailable('longPress');
+    }
     swipe() {
         return this.unavailable('swipe');
     }
+    drag() {
+        return this.unavailable('drag');
+    }
     pressKey() {
         return this.unavailable('pressKey');
     }
     back() {
         return this.unavailable('back');
     }
+    goHome() {
+        return this.unavailable('goHome');
+    }
     openUrl() {
         return this.unavailable('openUrl');
     }

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export type { Platform, ComputerPlatform, MobilePlatform } from './api/types.js'
 export { VerifyError, isVerifyError } from './errors.js';
 export type { RefusalReason, VerifyErrorCode } from './errors.js';
 export { localAgent } from './agent/loop.js';
-export type { Grounding, LocalAgent, LocalAgentOptions, Location, ModelRun, ModelTurn, Point, SwipeDirection, Target } from './agent/loop.js';
+export type { Grounding, Key, KeyModifier, LocalAgent, LocalAgentOptions, Location, ModelRun, ModelTurn, Point, SwipeDirection, Target } from './agent/loop.js';
 export type { CustomModel, ModelOption } from './agent/providers.js';
 export { anthropic, openaiCompatible } from './agent/model.js';
 export type { AnthropicOptions, JsonSchema, ModelAdapter, ModelReply, ModelRequest, ModelTool, ModelToolCall, ModelUsage, OpenAICompatibleOptions } from './agent/model.js';