@revyl/verify 0.4.0 → 0.5.0

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 import { RevylClient } from './api/client.js';
 import type { LiveStepType, Platform } from './api/types.js';
 import type { HostedTargetConfig, ResolvedDeviceTarget } from './config.js';
-import { type LocalAgent, type Location, type ModelRun, type Point, type SwipeDirection } from './agent/loop.js';
+import { type Key, type KeyModifier, type LocalAgent, type Location, type ModelRun, type Point, type SwipeDirection } from './agent/loop.js';
 import { type ModelOption } from './agent/providers.js';
 export type StepType = LiveStepType;
 /** The outcome of one instruction or validation, as Revyl's agent reported it. */
@@ -103,27 +103,43 @@ export interface OpenedSession extends Session {
     report(): Promise<Record<string, unknown>>;
     navigate(url: string): Promise<void>;
     open(target: HostedTargetConfig): Promise<OpenedSession>;
-    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. Browsers and devices only. */
+    /** Taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point tapped, in screenshot pixels. Browsers and devices only. */
     tap(at: Location): Promise<Point>;
     /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. Browsers and devices only. */
     type(at: Location, text: string, options?: {
         clear?: boolean;
     }): Promise<Point>;
+    /** Types into the field that already has focus, without tapping, replacing its content unless clear is false. Web only; on iOS and Android, use type(location, text). */
+    typeFocused(text: string, options?: {
+        clear?: boolean;
+    }): Promise<void>;
+    /** Double-taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point, in screenshot pixels. Browsers and devices only. */
+    doubleTap(at: Location): Promise<Point>;
+    /** Presses and holds a point or element for duration milliseconds (1 to 5000, default 1500). Returns the point, in screenshot pixels. Browsers and devices only. */
+    longPress(at: Location, options?: {
+        duration?: number;
+    }): Promise<Point>;
     /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. Browsers and devices only. */
     swipe(direction: SwipeDirection, options?: {
         from?: Location;
     }): Promise<void>;
-    /** Presses Enter or Backspace on the focused field. Browsers and devices only. */
-    pressKey(key: 'enter' | 'backspace'): Promise<void>;
+    /** Presses at one point or element, moves to another and releases. Browsers and devices only. */
+    drag(from: Location, to: Location): Promise<void>;
+    /** Presses a key on the focused element. iOS and Android take 'enter' and 'backspace'; Web also takes the other Key names, and modifiers, with which a lowercase letter or digit also works. */
+    pressKey(key: Key | string, options?: {
+        modifiers?: KeyModifier[];
+    }): Promise<void>;
     /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
     back(): Promise<void>;
+    /** Goes to the home screen on iOS and Android. Not on Web. */
+    goHome(): Promise<void>;
     /** Opens a URL or deep link on a device, or loads a URL in a browser. */
     openUrl(url: string): Promise<void>;
     /** Launches an installed app by bundle ID or package name. Devices only. */
     launchApp(bundleId: string): Promise<void>;
-    /** Asks Revyl's grounding model where an element is on the current screen, in device units. Browsers and devices only. */
+    /** Asks Revyl's grounding model where an element is on the current screen, in screenshot pixels. Browsers and devices only. */
     locate(target: string): Promise<Point>;
-    /** The screen size in device units: iOS points, Android and Web pixels. Browsers and devices only. */
+    /** The screenshot's size in pixels, the space every coordinate uses. Browsers and devices only. */
     screenSize(): Promise<{
         width: number;
         height: number;
@@ -160,6 +176,8 @@ export declare class DeviceSession implements Session {
     private parent?;
     private readySignal?;
     private size?;
+    private sizeSource?;
+    private screenshotSize?;
     private attribution?;
     get expiresAt(): Date | undefined;
     private constructor();
@@ -195,31 +213,51 @@ export declare class DeviceSession implements Session {
     private runStep;
     private runLocal;
     private agentControls;
-    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. */
+    /** Taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point tapped, in screenshot pixels. */
     tap(at: Location): Promise<Point>;
     /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. */
     type(at: Location, text: string, options?: {
         clear?: boolean;
     }): Promise<Point>;
+    /** Types into the field that already has focus, without tapping, replacing its content unless clear is false. Web only. */
+    typeFocused(text: string, options?: {
+        clear?: boolean;
+    }): Promise<void>;
+    /** Double-taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point, in screenshot pixels. */
+    doubleTap(at: Location): Promise<Point>;
+    /** Presses and holds a point or element for duration milliseconds (1 to 5000, default 1500). Returns the point, in screenshot pixels. */
+    longPress(at: Location, options?: {
+        duration?: number;
+    }): Promise<Point>;
     /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. */
     swipe(direction: SwipeDirection, options?: {
         from?: Location;
     }): Promise<void>;
-    /** Presses Enter or Backspace on the focused field. */
-    pressKey(key: 'enter' | 'backspace'): Promise<void>;
+    /** Presses at one point or element, moves to another and releases. */
+    drag(from: Location, to: Location): Promise<void>;
+    /** Presses a key on the focused element, with modifiers held on Web. */
+    pressKey(key: Key | string, options?: {
+        modifiers?: KeyModifier[];
+    }): Promise<void>;
     /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
     back(): Promise<void>;
+    /** Goes to the home screen on iOS and Android. */
+    goHome(): Promise<void>;
     /** Opens a URL or deep link on a device, or loads a URL in a browser. */
     openUrl(url: string): Promise<void>;
     /** Launches an installed app by bundle ID or package name. Devices only. */
     launchApp(bundleId: string): Promise<void>;
-    /** Asks Revyl's grounding model where an element is on the current screen, in device units. */
+    /** Asks Revyl's grounding model where an element is on the current screen, in screenshot pixels. */
     locate(target: string): Promise<Point>;
-    /** The screen size in device units: iOS points, Android and Web pixels. */
+    /** The screenshot's size in pixels, the space every coordinate uses. */
     screenSize(): Promise<{
         width: number;
         height: number;
     }>;
+    /** The screenshot's size and the device size Revyl acts in. They differ on iOS, where Revyl acts in points and a screenshot has more pixels. */
+    private readScreenshotSize;
+    private toDevice;
+    private toScreenshot;
     private readScreenSize;
     private capture;
     private perform;

package/dist/session.js

@@ -6,7 +6,7 @@ import { apiError, edgeBlockedError, parseJson, responseDetail, responseErrorCod
 import { trackSession, untrackSession } from './cleanup.js';
 import { VerifyError, errorMessage, isVerifyError } from './errors.js';
 import { screenHasContent } from './screen-readiness.js';
-import { runLocalStep } from './agent/loop.js';
+import { WEB_KEYS, checkKey, runLocalStep } from './agent/loop.js';
 import { chooseAgent } from './agent/providers.js';
 const POLL_INTERVAL_MS = 2_000;
 const DEVICE_CONNECT_TIMEOUT_MS = 90_000;
@@ -41,6 +41,8 @@ export class DeviceSession {
     parent;
     readySignal;
     size;
+    sizeSource;
+    screenshotSize;
     attribution;
     get expiresAt() {
         return this.parent?.expiresAt;
@@ -423,38 +425,77 @@ export class DeviceSession {
             perform: (action, screenToken, signal) => this.perform(action, screenToken, signal),
         };
     }
-    /** Taps a point in device units, or an element Revyl locates from a description. Returns the point tapped. */
+    /** Taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point tapped, in screenshot pixels. */
     async tap(at) {
-        return (await this.perform({ kind: 'tap', at: checkLocation(at) }));
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'tap', at: location })));
     }
     /** Taps a text field and types into it, clearing it first unless clear is false. Returns the point tapped. */
     async type(at, text, options = {}) {
         if (typeof text !== 'string' || text.length > 16_384)
             throw new VerifyError('INVALID_ARGUMENT', 'type() takes text of at most 16384 characters.');
-        return (await this.perform({ kind: 'type', at: checkLocation(at), text, clear: options.clear !== false }));
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'type', at: location, text, clear: options.clear !== false })));
+    }
+    /** Types into the field that already has focus, without tapping, replacing its content unless clear is false. Web only. */
+    async typeFocused(text, options = {}) {
+        if (this.platform !== 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'typeFocused() is available only on web sessions; on iOS and Android, use type(location, text), which taps the field first.');
+        if (typeof text !== 'string' || text.length > 16_384)
+            throw new VerifyError('INVALID_ARGUMENT', 'typeFocused() takes text of at most 16384 characters.');
+        await this.perform({ kind: 'type_focused', text, clear: options.clear !== false });
+    }
+    /** Double-taps a point in screenshot pixels, or an element Revyl locates from a description. Returns the point, in screenshot pixels. */
+    async doubleTap(at) {
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'double_tap', at: location })));
+    }
+    /** Presses and holds a point or element for duration milliseconds (1 to 5000, default 1500). Returns the point, in screenshot pixels. */
+    async longPress(at, options = {}) {
+        const { duration } = options;
+        if (duration !== undefined && (!Number.isInteger(duration) || duration < 1 || duration > 5_000))
+            throw new VerifyError('INVALID_ARGUMENT', 'longPress() duration is whole milliseconds from 1 to 5000.');
+        const location = await this.toDevice(checkLocation(at));
+        if (this.platform === 'ios')
+            await this.readScreenshotSize();
+        return this.toScreenshot((await this.perform({ kind: 'long_press', at: location, ...(duration !== undefined ? { durationMs: duration } : {}) })));
     }
     /** Swipes from a point or the screen's center. 'up' moves the finger up, which scrolls content down. */
     async swipe(direction, options = {}) {
         if (!['up', 'down', 'left', 'right'].includes(direction))
             throw new VerifyError('INVALID_ARGUMENT', "swipe() takes 'up', 'down', 'left' or 'right'.");
-        await this.perform({ kind: 'swipe', direction, ...(options.from ? { from: checkLocation(options.from) } : {}) });
+        await this.perform({ kind: 'swipe', direction, ...(options.from ? { from: await this.toDevice(checkLocation(options.from)) } : {}) });
+    }
+    /** Presses at one point or element, moves to another and releases. */
+    async drag(from, to) {
+        const [start, end] = [checkLocation(from), checkLocation(to)];
+        await this.perform({ kind: 'drag', from: await this.toDevice(start), to: await this.toDevice(end) });
     }
-    /** Presses Enter or Backspace on the focused field. */
-    async pressKey(key) {
-        if (key !== 'enter' && key !== 'backspace')
-            throw new VerifyError('INVALID_ARGUMENT', "pressKey() takes 'enter' or 'backspace'.");
-        await this.perform({ kind: 'key', key });
+    /** Presses a key on the focused element, with modifiers held on Web. */
+    async pressKey(key, options = {}) {
+        const checked = checkKey(this.platform, key, options.modifiers ?? []);
+        await this.perform({ kind: 'key', key: checked.key, ...(checked.modifiers.length ? { modifiers: checked.modifiers } : {}) });
     }
     /** Goes back: browser history on Web, the back button on Android. Not on iOS. */
     async back() {
         await this.perform({ kind: 'back' });
     }
+    /** Goes to the home screen on iOS and Android. */
+    async goHome() {
+        if (this.platform === 'web')
+            throw new VerifyError('NOT_AVAILABLE_ON_PLATFORM', 'goHome() is available only on iOS and Android sessions; on web, use openUrl() or navigate() to load a page.');
+        await this.perform({ kind: 'go_home' });
+    }
     /** Opens a URL or deep link on a device, or loads a URL in a browser. */
     async openUrl(url) {
         if (typeof url !== 'string' || url.length === 0 || url.length > 8_192)
             throw new VerifyError('INVALID_ARGUMENT', 'openUrl() takes a URL of 1 to 8192 characters.');
-        if (this.platform === 'web' && !/^https?:/i.test(url))
-            throw new VerifyError('INVALID_ARGUMENT', 'On web, openUrl() takes an http(s) URL; deep links such as myapp://orders/42 open only on iOS and Android.');
         await this.perform({ kind: 'open_url', url });
     }
     /** Launches an installed app by bundle ID or package name. Devices only. */
@@ -465,14 +506,69 @@ export class DeviceSession {
             throw new VerifyError('INVALID_ARGUMENT', 'launchApp() takes a bundle ID or package name.');
         await this.act('launch', { bundle_id: bundleId });
     }
-    /** Asks Revyl's grounding model where an element is on the current screen, in device units. */
+    /** Asks Revyl's grounding model where an element is on the current screen, in screenshot pixels. */
     async locate(target) {
         const { x, y } = await this.resolve(checkLocation({ target }));
-        return { x, y };
+        return this.toScreenshot({ x, y });
+    }
+    /** The screenshot's size in pixels, the space every coordinate uses. */
+    async screenSize() {
+        const { width, height } = await this.readScreenshotSize();
+        return { width, height };
+    }
+    /** The screenshot's size and the device size Revyl acts in. They differ on iOS, where Revyl acts in points and a screenshot has more pixels. */
+    async readScreenshotSize(fresh = false) {
+        if (fresh) {
+            const cached = [this.size, this.sizeSource, this.screenshotSize];
+            [this.size, this.sizeSource, this.screenshotSize] = [undefined, undefined, undefined];
+            try {
+                return await this.readScreenshotSize();
+            }
+            catch (error) {
+                [this.size, this.sizeSource, this.screenshotSize] = cached;
+                throw error;
+            }
+        }
+        if (this.screenshotSize)
+            return this.screenshotSize;
+        const device = await this.readScreenSize();
+        let size = device;
+        if (this.platform === 'ios') {
+            if (this.sizeSource !== 'health')
+                throw new VerifyError('ACTION_FAILED', `Revyl did not report this iOS screen's size in points, so Verify cannot map screenshot pixels to it and sent no action. See ${this.viewerUrl}`);
+            size = pngSize((await this.capture()).png);
+        }
+        this.screenshotSize = { width: size.width, height: size.height, device };
+        return this.screenshotSize;
+    }
+    async toDevice(at) {
+        if ('target' in at)
+            return at;
+        const read = async (fresh) => {
+            try {
+                return await this.readScreenshotSize(fresh);
+            }
+            catch (error) {
+                if (this.platform === 'ios' || !(error instanceof VerifyError))
+                    throw error;
+                return undefined;
+            }
+        };
+        let size = await read(false);
+        if (size && (at.x >= size.width || at.y >= size.height))
+            size = await read(true);
+        if (!size)
+            return at;
+        if (at.x >= size.width || at.y >= size.height) {
+            throw new VerifyError('INVALID_ARGUMENT', `(${at.x}, ${at.y}) is outside the screenshot: x must be 0 to ${size.width - 1} and y 0 to ${size.height - 1}, in screenshot pixels.`);
+        }
+        return { x: Math.min(size.device.width - 1, Math.round((at.x * size.device.width) / size.width)), y: Math.min(size.device.height - 1, Math.round((at.y * size.device.height) / size.height)) };
     }
-    /** The screen size in device units: iOS points, Android and Web pixels. */
-    screenSize() {
-        return this.readScreenSize();
+    async toScreenshot(point) {
+        if (this.platform !== 'ios')
+            return point;
+        const size = await this.readScreenshotSize();
+        return { x: Math.round((point.x * size.width) / size.device.width), y: Math.round((point.y * size.height) / size.device.height) };
     }
     async readScreenSize(signal) {
         if (this.size)
@@ -481,6 +577,7 @@ export class DeviceSession {
             const health = parseJson(await this.worker('GET', 'health', { retry: true, ...(signal ? { signal } : {}) }), 'health');
             if (Number.isInteger(health.screen_width) && Number.isInteger(health.screen_height) && health.screen_width > 0 && health.screen_height > 0) {
                 this.size = { width: health.screen_width, height: health.screen_height };
+                this.sizeSource = 'health';
                 return this.size;
             }
         }
@@ -513,11 +610,30 @@ export class DeviceSession {
                 await this.act('tap', pointBody(point, action.at), signal);
                 return { x: point.x, y: point.y };
             }
+            case 'double_tap': {
+                const point = await this.resolve(action.at, screenToken, signal);
+                await this.act('double_tap', pointBody(point, action.at), signal);
+                return { x: point.x, y: point.y };
+            }
+            case 'long_press': {
+                const point = await this.resolve(action.at, screenToken, signal);
+                await this.act('longpress', { ...pointBody(point, action.at), ...(action.durationMs !== undefined ? { duration_ms: action.durationMs } : {}) }, signal);
+                return { x: point.x, y: point.y };
+            }
             case 'type': {
                 const point = await this.resolve(action.at, screenToken, signal);
                 await this.act('input', { ...pointBody(point, action.at), text: action.text, clear_first: action.clear }, signal);
                 return { x: point.x, y: point.y };
             }
+            case 'type_focused':
+                await this.act('input', { text: action.text, clear_first: action.clear }, signal);
+                return undefined;
+            case 'drag': {
+                const from = await this.resolve(action.from, screenToken, signal);
+                const to = await this.resolve(action.to, screenToken, signal);
+                await this.act('drag', { start_x: from.x, start_y: from.y, end_x: to.x, end_y: to.y }, signal);
+                return undefined;
+            }
             case 'swipe': {
                 const point = action.from ? await this.resolve(action.from, screenToken, signal) : await this.readScreenSize(signal).then((size) => ({ x: Math.floor(size.width / 2), y: Math.floor(size.height / 2) }));
                 const direction = this.platform === 'web' ? { up: 'down', down: 'up', left: 'right', right: 'left' }[action.direction] : action.direction;
@@ -525,7 +641,10 @@ export class DeviceSession {
                 return undefined;
             }
             case 'key':
-                await this.act('key', { key: this.platform === 'web' ? (action.key === 'enter' ? 'Enter' : 'Backspace') : action.key.toUpperCase() }, signal);
+                await this.act('key', { key: this.platform === 'web' ? (WEB_KEYS[action.key] ?? action.key) : action.key.toUpperCase(), ...(action.modifiers?.length ? { modifiers: action.modifiers } : {}) }, signal);
+                return undefined;
+            case 'go_home':
+                await this.act('go_home', undefined, signal);
                 return undefined;
             case 'back':
                 if (this.platform === 'ios')
@@ -534,6 +653,8 @@ export class DeviceSession {
                 return undefined;
             case 'open_url':
                 signal?.throwIfAborted();
+                if (this.platform === 'web' && !/^https?:/i.test(action.url))
+                    throw new VerifyError('INVALID_ARGUMENT', 'On web, openUrl() takes an http(s) URL; deep links such as myapp://orders/42 open only on iOS and Android.');
                 if (this.platform === 'web')
                     await this.navigateTo(action.url, signal);
                 else
@@ -765,7 +886,7 @@ function checkLocation(at) {
         return { target: at.target.trim() };
     }
     if (!at || typeof at !== 'object' || !Number.isInteger(at.x) || !Number.isInteger(at.y) || at.x < 0 || at.y < 0) {
-        throw new VerifyError('INVALID_ARGUMENT', 'A location is { x, y } in non-negative whole device units, or { target: "description" }.');
+        throw new VerifyError('INVALID_ARGUMENT', 'A location is { x, y } in non-negative whole screenshot pixels, or { target: "description" }.');
     }
     return { x: at.x, y: at.y };
 }

package/docs/agents.md

@@ -22,6 +22,39 @@ This page is for AI coding agents (Claude Code, Cursor, Codex, and others) that
 4. Run it with `node path/to/script.ts`. Share the session link from the first `[verify]` line with the user, so they can watch.
 5. Read the outcome from the exit code and stderr. Each step prints `✓` or `✗` with its text; a failure prints `CODE: message`, ending with the session link. Look at any screenshot you saved before changing the script or the app.
 
+## Exact actions and coordinates
+
+Use `instruction()` when the step needs judgement, and exact actions (`tap`, `doubleTap`, `longPress`, `type`, `swipe`, `drag`, `pressKey`, `locate`, `screenSize`) when you know exactly what to press. They work on Web, iOS and Android, not on computers. On Web, `typeFocused(text)` types into the field that has focus, and `pressKey` also takes keys such as `'escape'`, `'tab'` and arrows, with `modifiers`. On iOS and Android, `goHome()` goes to the home screen, `pressKey` takes only `'enter'` and `'backspace'`, and you type with `type(location, text)`. A call the platform lacks throws `NOT_AVAILABLE_ON_PLATFORM` before anything is sent, and the message names what to use instead.
+
+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.
+
+`swipe('up')` moves the finger up, so content scrolls down, on every platform. Actions return once Revyl accepts them, so after a swipe, drag, `goHome`, `openUrl` or `launchApp`, wait for the screen to settle before you `locate` or tap by coordinates.
+
+```ts
+import { open } from '@revyl/verify';
+
+const session = await open('ios');
+try {
+  await session.tap({ target: 'General' });                 // first choice: describe the element
+  const about = await session.locate('About');              // a point in screenshot pixels
+  await session.tap(about);                                 // so it goes straight to tap()
+
+  await session.screenshot({ path: '.verify/screen.png' }); // open it and find what to press
+  await session.tap({ x: 660, y: 1500 });                   // a position read off the screenshot, unchanged
+  await session.swipe('up', { from: { x: 660, y: 2000 } }); // swipe from a screenshot position too
+  const { width, height } = await session.screenSize();     // the screenshot's size
+  console.log(`x is 0 to ${width - 1}, y is 0 to ${height - 1}`);
+
+  await session.longPress({ target: 'Wi-Fi row' });          // press and hold, 1.5 s by default
+  await session.drag({ x: 660, y: 2000 }, { x: 660, y: 800 }); // press, move, release: the list follows the finger
+  await session.goHome();                                   // the home screen, on iOS and Android
+} finally {
+  await session.close();
+}
+```
+
+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 state the same rule with each language's names. [api.md](api.md#exact-actions) lists every call and its errors.
+
 ## Rules
 
 Mac computers are early access. Ask support@revyl.ai about access before starting a computer; do not repeat an uncertain start/stop to probe availability.

package/docs/api.md

@@ -84,12 +84,15 @@ Web only, hosted or normal. Sends one deterministic `open_url` action and checks
 
 ## Exact actions
 
-**Since 0.4.0. 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. Web, iOS and Android sessions take device actions that need no agent.
+**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. Web, iOS and Android sessions take device actions that need no agent.
 
 | 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 |
@@ -97,25 +100,40 @@ Web only, hosted or normal. Sends one deterministic `open_url` action and checks
 | `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.
+A call a platform doesn't support throws `NOT_AVAILABLE_ON_PLATFORM`, and its message names the alternative.
 
-A location is `{ x, y }` in device units (iOS points, Android and Web pixels, from the top-left corner; `screenSize()` gives the bounds) or `{ target: 'Login button' }`, which Revyl's grounding model finds on the current screen.
+A location is `{ x, y }` in screenshot pixels (see [Coordinates](#coordinates)) or `{ target: 'Login button' }`, which Revyl's grounding model finds on the current screen.
 
 | Call | What it does |
 | --- | --- |
 | `tap(at)` | Taps and resolves with the point tapped |
+| `doubleTap(at)` | Double-taps (double-clicks on Web) and resolves with the point |
+| `longPress(at, { duration })` | Presses and holds for `duration` milliseconds, 1 to 5000 (default 1500), and resolves with the point |
 | `type(at, text, { clear })` | Taps a text field and types into it, clearing it first unless `clear` is `false` |
+| `typeFocused(text, { clear })` | Web only: types into the field that already has focus, without clicking, replacing its text unless `clear` is `false`. Focus the field first, for example with `tap` or `pressKey('tab')`. With no field focused nothing is typed and no error is thrown, so check the result. On iOS and Android it throws `NOT_AVAILABLE_ON_PLATFORM`; use `type(location, text)` |
 | `swipe(direction, { from })` | Swipes from a location or the screen's center; `'up'` moves the finger up, which scrolls content down |
-| `pressKey('enter' \| 'backspace')` | Presses a key on the focused field |
+| `drag(from, to)` | Presses at one location, moves to the other and releases, for example to reorder a list, move a slider or select text |
+| `pressKey(key, { modifiers })` | Presses a key on the focused element. Every platform takes `'enter'` and `'backspace'`. Web 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'`, held while the key is pressed. With modifiers a lowercase letter or digit works too, such as `pressKey('a', { modifiers: ['ctrl'] })`. Other keys and any modifiers throw `NOT_AVAILABLE_ON_PLATFORM` on iOS and Android |
 | `back()` | Browser history on Web, the back button on Android; iOS throws `NOT_AVAILABLE_ON_PLATFORM` |
+| `goHome()` | Goes to the home screen on iOS and Android; Web throws `NOT_AVAILABLE_ON_PLATFORM` |
 | `openUrl(url)` | Opens a URL or deep link on a device, or loads a URL in a browser |
 | `launchApp(bundleId)` | Launches an installed app on a device |
 | `locate(target)` | Resolves with Revyl's best match on the current screen, without acting |
-| `screenSize()` | Resolves with `{ width, height }` in device units |
+| `screenSize()` | Resolves with the screenshot's `{ width, height }` in pixels |
 
 A failed action throws `ACTION_FAILED`, including when Revyl cannot find a target or nothing at a point can take the action. One whose outcome Revyl can't confirm throws `ACTION_UNCERTAIN` or `TIMEOUT`, so check the session before acting again. Actions are never repeated. If Verify can't reach Revyl, the action fails with `API_ERROR` and isn't resent either, so check the session before trying it again.
 
-Exact actions return when Revyl has accepted them, not when the screen has finished changing. After `swipe`, `openUrl` or `launchApp`, let the screen settle or check it before you `locate` or tap coordinates. `locate` returns Revyl's best match on the current screen and can return a point for an element that is off screen, so bring the element on screen first and check the point before you use it.
+Exact actions return when Revyl has accepted them, not when the screen has finished changing. After `swipe`, `drag`, `goHome`, `openUrl` or `launchApp`, let the screen settle or check it before you `locate` or tap coordinates. `locate` returns Revyl's best match on the current screen and can return a point for an element that is off screen, so bring the element on screen first. A point outside `screenSize()` is off screen, and an action at it is refused.
+
+### 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.
+
+```ts
+await session.screenshot({ path: '.verify/screen.png' });  // open it and find the element
+await session.tap({ x: 660, y: 1500 });                    // the position as you read it, on every platform
+const { width, height } = await session.screenSize();      // the screenshot's size: x is 0 to width - 1
+```
 
 ## session.report()
 
@@ -162,7 +180,7 @@ When inspecting `revyl device report --session-id <id>`, read validation verdict
 
 ## Your own model
 
-**Since 0.4.0. 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#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. Runs instructions and validations on a model you choose, in your process, instead of Revyl's agent. Revyl still provides the browser or device. Leave `model` out and Revyl's agent runs the step, as before.
+**Early access.** 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. Runs instructions and validations on a model you choose, in your process, instead of Revyl's agent. Revyl still provides the browser or device. Leave `model` out and Revyl's agent runs the step, as before.
 
 ```ts
 const session = await open('ios', { model: 'anthropic/claude-sonnet-5-5' });  // every step on your model
@@ -198,7 +216,7 @@ const session = await open('ios', { agent });
 ```
 
 - `model`: a `ModelAdapter`. `anthropic({ model, apiKey, baseURL, maxTokens, maxRetries })` uses `ANTHROPIC_API_KEY` and `ANTHROPIC_BASE_URL` for what you leave out. `openaiCompatible({ model, baseURL, apiKey, headers, provider, maxTokens, maxRetries })` uses `OPENAI_BASE_URL` and `OPENAI_API_KEY` only when `baseURL` is left out, so a key never reaches another provider; it then sends OpenAI's `max_completion_tokens`. To wrap another SDK or runtime, implement `{ name, complete(request, signal) }`: it gets the system prompt, text, screenshot and tools, and returns the chosen tool call and token usage.
-- `grounding`: `'revyl'` (default) as above. `'model'` has the model give screenshot coordinates instead, so Revyl receives only taps, typing and swipes, never element descriptions; it needs a model that points accurately.
+- `grounding`: `'revyl'` (default) as above. `'model'` has the model give screenshot coordinates instead, so Revyl receives only device actions such as taps, typing and swipes, never element descriptions; it needs a model that points accurately.
 - `maxTurns` (default 20, up to 100), `modelTimeout` per model call (default 60000), `maxImageSide` for screenshots sent to the model (default 1280).
 
 ## session.screenshot(options?)

package/docs/configuration.md

@@ -36,7 +36,7 @@ Mac targets are early access. Ask support@revyl.ai about access. See [computer a
 | `app.url` | A public HTTPS URL to open, registered as a build each time a session opens. |
 | `app.buildId` | An exact Revyl web build to open instead of a URL. |
 | `app.branch` | Branch to register the URL on, or to take the newest build from. |
-| `viewport` | `{ width, height, deviceScaleFactor? }` in CSS pixels |
+| `viewport` | `{ width, height, deviceScaleFactor? }` in CSS pixels. Screenshots, and so exact-action coordinates, are `deviceScaleFactor` times the CSS size |
 | `signIn` | `{ path, secret, persona? }`: a test-only sign-in route. See [web.md](web.md). |
 | `startTimeout` | Milliseconds to wait for the browser. Default 600000. |
 | `idleTimeoutSeconds` | Revyl stops the session after this much inactivity. Default 600. |

package/docs/errors.md

@@ -37,7 +37,7 @@ try {
 
 | Code | What happened | What to do |
 | --- | --- | --- |
-| `INVALID_ARGUMENT` | A call got a bad value: an unknown target name, an empty step, two steps at once on one session | The message names the argument |
+| `INVALID_ARGUMENT` | A call got a bad value: an unknown target name, an empty step, two steps at once on one session, a point outside the screenshot | The message names the argument |
 | `CONFIG_NOT_FOUND` | `open('name')` found no `verify.config.ts` at or above the current folder | Run `npx @revyl/verify init`, pass `options.config`, or pass a target object |
 | `CONFIG_INVALID` | The config failed validation or did not load | The message names the exact option and the rule |
 | `AUTH_MISSING` | No `REVYL_API_KEY` and no saved login | Run `npx @revyl/verify login` in a terminal, or set `REVYL_API_KEY` |
@@ -48,7 +48,7 @@ try {
 | `SESSION_ENDED` | The session was closed, stopped, or expired, or Revyl answered 404 for the session itself | Close explicitly; computer expiry does not prove release |
 | `SESSION_BUSY` | A step conflict, computer operation limit, or recording requested before terminal state and confirmed release | Inspect the state before another call; a terminal computer alone does not prove release |
 | `COMPUTER_LIMIT` | Computer admission was refused due to queued work (including iOS) or the concurrency limit | Wait for capacity; Verify does not retry or stop a definitely refused start |
-| `NOT_AVAILABLE_ON_PLATFORM` | The call is unavailable: computer agent steps, device shell/file/recording methods, computer access or runtime unavailable, or a backend without web steps | See [web.md](web.md) and [computers.md](computers.md#availability-and-errors) |
+| `NOT_AVAILABLE_ON_PLATFORM` | The call is unavailable: computer agent steps, device shell/file/recording methods, an exact action the platform lacks (such as `back()` on iOS, `goHome()` or `launchApp()` on Web, `typeFocused()` or keys other than Enter and Backspace on iOS and Android), computer access or runtime unavailable, or a backend without web steps | See [web.md](web.md) and [computers.md](computers.md#availability-and-errors) |
 | `COMMAND_FAILED` | A computer command exited nonzero | Read its reason; use `exec(argv, { check: false })` to inspect the exit code and output instead |
 | `NOT_FOUND` | A computer file or resource was not found | Check the workspace-relative path |
 | `ACCESS_DENIED` | The computer refused access | Check permissions; do not assume host/root access |

package/docs/llms.txt

@@ -16,4 +16,10 @@ Mac computers are early access; ask support@revyl.ai about access. See computers
 - [CI and test runners](ci.md): GitHub Actions, node:test, Vitest, Jest, Playwright Test
 - [Use your own model](own-model.md): run instructions and validations on Claude, GPT, Gemini, a local model or any OpenAI-compatible endpoint; providers, limits, privacy and troubleshooting
 - [Errors](errors.md): every error code and what to do about it
-- [For coding agents](agents.md): the workflow and rules for agents using Verify
+- [For coding agents](agents.md): the workflow and rules for agents using Verify, and the coordinate rule for exact actions
+
+## Exact actions and 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. See [For coding agents](agents.md#exact-actions-and-coordinates) for a runnable example.
+
+Exact actions are `tap`, `doubleTap`, `longPress`, `type`, `swipe`, `drag`, `pressKey`, `locate` and `screenSize` on Web, iOS and Android. Web adds `typeFocused(text)`, which types into the field that has focus, and `pressKey` keys such as `'escape'`, `'tab'` and arrows with `modifiers`. iOS and Android add `goHome()`; their `pressKey` takes only `'enter'` and `'backspace'`, and you type with `type(location, text)`. A call the platform lacks throws `NOT_AVAILABLE_ON_PLATFORM` before anything is sent, naming what to use instead. See [api.md](api.md#exact-actions) for every call.