touchpress 0.1.0 → 0.1.2

package/dist/core/index.d.mts

@@ -52,9 +52,11 @@ type Comparison = {
  */
 declare function compareScreenshot(expected: Buffer, actual: Buffer, options: CompareOptions): Comparison;
 /**
- * The box is clamped to the image, because a rect comes from a snapshot and a
+ * The box is clipped to the image, because a rect comes from a snapshot and a
  * screenshot is a separate capture. A control flush against the bottom edge can
- * round a pixel past it, and that is not a reason to fail an assertion.
+ * round a pixel past it, and that is not a reason to fail an assertion. A box
+ * with no pixel inside the image is a different thing, a rect the screenshot
+ * does not show, and cutting a placeholder out of the corner would hide that.
  */
 declare function cropScreenshot(source: Buffer, box: PixelBox): Buffer;
 declare function sizeOf(source: Buffer): Size;

package/dist/core/index.mjs

@@ -1,2 +1,2 @@
-import { A as textMatch, C as renderScreen, D as parseDeviceOptions, E as deviceNameForSlot, O as describeQuery, S as parseScreen, T as TOUCHPRESS_DEFAULTS, a as sizeOf, b as renderTitle, d as createScrollSearch, f as directionToward, g as sessionName, h as openSession, i as relativeTo, j as TouchpressError, k as normalizeText, l as captureEvidence, m as probe, n as compareScreenshot, o as toPixelBox, p as formatFailure, r as cropScreenshot, t as preflight, u as createDevice, v as describeCheck, w as resolve, x as silentSink, y as evaluate } from "../preflight-B7KrbqSO.mjs";
+import { A as normalizeText, C as parseScreen, D as deviceNameForSlot, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, a as sizeOf, d as createScrollSearch, f as directionToward, g as evaluate, h as describeCheck, i as relativeTo, j as textMatch, k as describeQuery, l as captureEvidence, m as probe, n as compareScreenshot, o as toPixelBox, p as formatFailure, r as cropScreenshot, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle, y as sessionName } from "../preflight-CWeJYtS7.mjs";
 export { TOUCHPRESS_DEFAULTS, TouchpressError, captureEvidence, compareScreenshot, createDevice, createScrollSearch, cropScreenshot, describeCheck, describeQuery, deviceNameForSlot, directionToward, evaluate, formatFailure, normalizeText, openSession, parseDeviceOptions, parseScreen, preflight, probe, relativeTo, renderScreen, renderTitle, resolve, sessionName, silentSink, sizeOf, textMatch, toPixelBox };

package/dist/index.d.mts

@@ -1,6 +1,28 @@
 import { E as ReadyQuery, _t as Screen, a as ExpectedValue, at as Filter, b as DeviceSession, ct as TextMatch, g as Locator, h as FilterOptions, ht as Rect, i as ErrorInfo, k as TouchpressOptions$1, n as PreflightReport, o as TouchpressError, ot as Query, p as Device$1, pt as Platform, r as preflight, st as Role, t as PreflightDevice, vt as ScreenNode } from "./preflight-Czhj9QFM.mjs";
 import { ExpectMatcherState } from "@playwright/test";
-import { FlexibleSchema, LanguageModel } from "ai";
+//#region src/ai/options.d.ts
+/**
+ * What `use.aiModel` accepts, spelled structurally so the main entry's
+ * declarations never import from `ai`. A gateway model id such as
+ * `'anthropic/claude-sonnet-5'` and a provider model instance both fit, and
+ * every AI SDK language model, v2 through v4, carries these three fields.
+ */
+type AiModel = string | {
+  readonly specificationVersion: string;
+  readonly provider: string;
+  readonly modelId: string;
+};
+/**
+ * The one key `act` and `extract` add to Playwright's `use`. It is not part of
+ * `core/config.ts`, because nothing under `core/` may name an AI SDK type.
+ *
+ * Unset is the default, and it fails at the first `act` rather than at worker
+ * start, so a project that never calls one needs no model.
+ */
+type AiOptions = {
+  aiModel: AiModel | undefined;
+};
+//#endregion
 //#region src/ai/device.d.ts
 /** A loop can run for minutes, so its budget is its own rather than the action timeout a deterministic step takes. */
 type ActOptions = {
@@ -10,6 +32,24 @@ type ActOptions = {
 type ExtractOptions = {
   timeout?: number;
 };
+/**
+ * What `extract` accepts, spelled structurally so the main entry's declarations
+ * never import from `ai`. The first branch is a Standard Schema, which Zod
+ * 3.25+, Zod 4, and Valibot implement, with `T` read off its output type. The
+ * second is the AI SDK's own `Schema`, which `jsonSchema()` returns.
+ */
+type ExtractSchema<T> = {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: {
+      readonly output: T;
+    };
+  };
+} | {
+  readonly jsonSchema: unknown;
+  readonly _type?: T;
+};
 type AiDevice = {
   /**
    * Drives the app with a model until the instruction is satisfied. Resolves
@@ -18,21 +58,7 @@ type AiDevice = {
    */
   act(instruction: string, options?: ActOptions): Promise<string>;
   /** Asks a model one question about the current screen and validates the answer against `schema`. */
-  extract<T>(question: string, schema: FlexibleSchema<T>, options?: ExtractOptions): Promise<T>;
-};
-//#endregion
-//#region src/ai/options.d.ts
-/**
- * The one key `act` and `extract` add to Playwright's `use`. It is not part of
- * `core/config.ts`, because nothing under `core/` may name an AI SDK type.
- *
- * A gateway model id such as `'anthropic/claude-sonnet-5'` and a provider
- * model instance are both `LanguageModel`, so a config picks either without a
- * second key. Unset is the default, and it fails at the first `act` rather than
- * at worker start, so a project that never calls one needs no model.
- */
-type AiOptions = {
-  aiModel: LanguageModel | undefined;
+  extract<T>(question: string, schema: ExtractSchema<T>, options?: ExtractOptions): Promise<T>;
 };
 //#endregion
 //#region src/playwright/fixtures.d.ts
@@ -117,4 +143,4 @@ declare const expect: import("@playwright/test").Expect<{
 type TouchpressOptions = TouchpressOptions$1 & AiOptions;
 type Device = Device$1 & AiDevice;
 //#endregion
-export { type ActOptions, type AiDevice, type AiOptions, Device, type ErrorInfo, type ExpectedValue, type ExtractOptions, type Filter, type FilterOptions, type Locator, type Platform, type PreflightDevice, type PreflightReport, type Query, type ReadyQuery, type Rect, type Role, type Screen, type ScreenNode, type ScreenshotOptions, type TextMatch, TouchpressError, TouchpressOptions, expect, preflight, setupTest, test };
+export { type ActOptions, type AiDevice, type AiModel, type AiOptions, Device, type ErrorInfo, type ExpectedValue, type ExtractOptions, type ExtractSchema, type Filter, type FilterOptions, type Locator, type Platform, type PreflightDevice, type PreflightReport, type Query, type ReadyQuery, type Rect, type Role, type Screen, type ScreenNode, type ScreenshotOptions, type TextMatch, TouchpressError, TouchpressOptions, expect, preflight, setupTest, test };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as textMatch, C as renderScreen, D as parseDeviceOptions, S as parseScreen, T as TOUCHPRESS_DEFAULTS, _ as sleep, a as sizeOf, b as renderTitle, c as createClient, h as openSession, i as relativeTo, j as TouchpressError, l as captureEvidence, n as compareScreenshot, o as toPixelBox, r as cropScreenshot, s as createAgentDeviceDriver, t as preflight, u as createDevice, w as resolve, x as silentSink } from "./preflight-B7KrbqSO.mjs";
+import { C as parseScreen, E as TOUCHPRESS_DEFAULTS, M as TouchpressError, O as parseDeviceOptions, S as silentSink, T as resolve, _ as createQueue, a as sizeOf, b as sleep, c as createClient, i as relativeTo, j as textMatch, l as captureEvidence, n as compareScreenshot, o as toPixelBox, r as cropScreenshot, s as createAgentDeviceDriver, t as preflight, u as createDevice, v as openSession, w as renderScreen, x as renderTitle } from "./preflight-CWeJYtS7.mjs";
 import { expect as expect$1, test as test$1 } from "@playwright/test";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
@@ -106,10 +106,11 @@ async function createDeviceTools(session, platform) {
 	for (const name of DEVICE_TOOLS.keys()) {
 		const built = tools[name];
 		if (built === void 0) throw new Error(`agent-device no longer exposes the "${name}" tool`);
+		const schema = prune(built.inputSchema.jsonSchema);
 		kept[name] = tool({
 			description: built.description,
-			inputSchema: jsonSchema(prune(built.inputSchema.jsonSchema)),
-			execute: wrapDeviceTool(name, platform, built.execute)
+			inputSchema: jsonSchema(schema),
+			execute: wrapDeviceTool(name, platform, built.execute, new Set(Object.keys(schema.properties ?? {})))
 		});
 	}
 	return kept;
@@ -117,14 +118,19 @@ async function createDeviceTools(session, platform) {
 /**
 * The one place a command's input and output are reshaped for the model, so the
 * table above stays the only thing that says which command gets which shape.
+*
+* `accepted` is the key set of the pruned schema. A schema handed to
+* `jsonSchema()` describes the tool and validates nothing, so a model that
+* sends a key the schema no longer lists would otherwise have it forwarded.
 */
-function wrapDeviceTool(name, platform, execute) {
+function wrapDeviceTool(name, platform, execute, accepted) {
 	const shape = DEVICE_TOOLS.get(name)?.output ?? "raw";
 	return async (input, options) => {
+		const declared = Object.fromEntries(Object.entries(asObject(input)).filter(([key]) => accepted.has(key)));
 		const output = await execute(shape === "screen" ? {
-			...asObject(input),
+			...declared,
 			forceFull: true
-		} : withRefSigil(input), options);
+		} : withRefSigil(declared), options);
 		return shape === "screen" ? compactSnapshot(asSnapshot(output), platform) : compactResult(name, output);
 	};
 }
@@ -273,7 +279,7 @@ function runAct(run) {
 	}), async () => {
 		const { ToolLoopAgent, hasToolCall, jsonSchema, stepCountIs, tool } = await loadAi();
 		const result = await new ToolLoopAgent({
-			model: run.model,
+			model: languageModel(run.model),
 			instructions: instructionsFor(run.platform),
 			tools: {
 				...reporting(run.tools, run.sink),
@@ -349,6 +355,18 @@ function runAct(run) {
 		return outcome.summary;
 	});
 }
+/**
+* The public types are structural so the main entry's declarations never
+* import from `ai`, and these two casts are where they meet the SDK's own.
+* Every `LanguageModel` and every `FlexibleSchema` satisfies the structural
+* type it is cast from, so nothing the SDK accepts is turned away.
+*/
+function languageModel(model) {
+	return model;
+}
+function flexibleSchema(schema) {
+	return schema;
+}
 /** One capture, one question, one answer. No tools, so the model cannot change the screen it is describing. */
 function runExtract(run) {
 	return run.sink.step(renderTitle({
@@ -357,9 +375,9 @@ function runExtract(run) {
 	}), async () => {
 		const { ToolLoopAgent, Output } = await loadAi();
 		return (await new ToolLoopAgent({
-			model: run.model,
+			model: languageModel(run.model),
 			instructions: EXTRACT_INSTRUCTIONS,
-			output: Output.object({ schema: run.schema })
+			output: Output.object({ schema: flexibleSchema(run.schema) })
 		}).generate({
 			prompt: [
 				`Question: ${run.question}`,
@@ -371,8 +389,14 @@ function runExtract(run) {
 		})).output;
 	});
 }
-/** Every model action becomes a step wrapping its own execution, so a report shows the loop as it ran. */
+/**
+* Every model action becomes a step wrapping its own execution, so a report
+* shows the loop as it ran. The executions share one queue, because the AI SDK
+* runs the tool calls of one step concurrently and a snapshot overlapping a
+* press on the device reads a screen the press is changing.
+*/
 function reporting(tools, sink) {
+	const queue = createQueue();
 	const wrapped = {};
 	for (const [name, built] of Object.entries(tools)) {
 		const { execute } = built;
@@ -382,7 +406,7 @@ function reporting(tools, sink) {
 		}
 		wrapped[name] = {
 			...built,
-			execute: (input, options) => sink.step(renderTitle(toolRecord(name, input)), async () => {
+			execute: (input, options) => queue.enqueue(() => sink.step(renderTitle(toolRecord(name, input)), async () => {
 				const text = typedText(name, input);
 				if (text !== null) await sink.step(renderTitle({
 					kind: "typed",
@@ -392,7 +416,7 @@ function reporting(tools, sink) {
 					}
 				}), () => Promise.resolve(), { box: true });
 				return execute(input, options);
-			})
+			}))
 		};
 	}
 	return wrapped;
@@ -870,10 +894,16 @@ function write(path, png) {
 	mkdirSync(dirname(path), { recursive: true });
 	writeFileSync(path, png);
 }
+/**
+* The describe path is part of the name, the way Playwright's own screenshot
+* assertion names its baselines, so two blocks each holding a test called
+* "shot" do not write over one baseline. The first element is the file, which
+* `snapshotPath` already places the baseline under.
+*/
 function defaultName(info) {
 	const next = (ordinals.get(info) ?? 0) + 1;
 	ordinals.set(info, next);
-	return `${info.title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}-${String(next)}.png`;
+	return `${info.titlePath.slice(1).join(" ").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}-${String(next)}.png`;
 }
 //#endregion
 //#region src/playwright/expect.ts

package/dist/{preflight-B7KrbqSO.mjs → preflight-CWeJYtS7.mjs}

@@ -145,7 +145,9 @@ function matchesText(match, candidate) {
 	switch (match.kind) {
 		case "exact": return candidate === match.value;
 		case "substring": return candidate.toLowerCase().includes(match.value.toLowerCase());
-		case "regex": return match.value.test(candidate);
+		case "regex":
+			match.value.lastIndex = 0;
+			return match.value.test(candidate);
 		default: throw new Error(`unhandled text match ${JSON.stringify(match)}`);
 	}
 }
@@ -417,7 +419,9 @@ const IOS_ROLES = {
 * Native 0.86 sample app, except the trailing widget block, which this app never
 * renders and stays a plausible guess. `android.view.ViewGroup` is what every
 * React Native `View` reports, testID containers included, so it is stated here
-* rather than left to the `other` fall-through in `roleOf`.
+* rather than left to the `other` fall-through in `roleOf`. A password field is
+* an `EditText` too. agent-device 0.20.10 parses the tree's `password` flag but
+* does not emit it, so once it does, map it to `secure-text-field` here.
 */
 const ANDROID_ROLES = {
 	"android.widget.Button": "button",
@@ -701,89 +705,6 @@ const silentSink = {
 	outputPath: (fileName) => fileName
 };
 //#endregion
-//#region src/core/checks.ts
-/**
-* A `many` outcome never passes anything but `toHaveCount`. An ambiguous locator
-* is a strictness violation, and it reports through the same message path as a
-* plain mismatch rather than guessing which node was meant.
-*/
-function evaluate(check, resolution) {
-	if (check.name === "toHaveCount") {
-		const count = countOf(resolution);
-		return {
-			pass: count === check.expected,
-			actual: String(count)
-		};
-	}
-	if (resolution.outcome === "none") return {
-		pass: false,
-		actual: null
-	};
-	if (resolution.outcome === "many") return {
-		pass: false,
-		actual: `${String(resolution.nodes.length)} matching nodes`
-	};
-	const node = resolution.node;
-	switch (check.name) {
-		case "toBeVisible": return {
-			pass: true,
-			actual: describeNode(node)
-		};
-		case "toHaveText": {
-			const text = node.name ?? node.value;
-			return {
-				pass: matchesText(check.expected, text),
-				actual: text === null ? null : `"${text}"`
-			};
-		}
-		case "toHaveValue": return {
-			pass: matchesText(check.expected, node.value),
-			actual: node.value === null ? null : `"${node.value}"`
-		};
-		case "toBeEnabled": return {
-			pass: node.enabled,
-			actual: node.enabled ? "enabled" : "disabled"
-		};
-		case "toBeSelected": return {
-			pass: node.selected,
-			actual: node.selected ? "selected" : "not selected"
-		};
-		case "toBeFocused": return {
-			pass: node.focused,
-			actual: node.focused ? "focused" : "not focused"
-		};
-		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
-	}
-}
-function countOf(resolution) {
-	switch (resolution.outcome) {
-		case "one": return 1;
-		case "none": return 0;
-		case "many": return resolution.nodes.length;
-		default: throw new Error(`unhandled resolution ${JSON.stringify(resolution)}`);
-	}
-}
-/** The `Expected:` line. */
-function describeCheck(check) {
-	switch (check.name) {
-		case "toBeVisible": return "visible";
-		case "toHaveText": return `text ${describeExpected(check.expected)}`;
-		case "toHaveValue": return `value ${describeExpected(check.expected)}`;
-		case "toBeEnabled": return "enabled";
-		case "toBeSelected": return "selected";
-		case "toBeFocused": return "focused";
-		case "toHaveCount": return `count ${String(check.expected)}`;
-		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
-	}
-}
-function describeExpected(match) {
-	return match.kind === "regex" ? String(match.value) : `"${match.value}"`;
-}
-function describeNode(node) {
-	const name = node.name === null ? "" : ` "${node.name}"`;
-	return `${node.ref} [${node.role}]${name}`;
-}
-//#endregion
 //#region src/core/session.ts
 const READY_POLL_MS = 250;
 const SNAPSHOT_TIMEOUT_MS = 15e3;
@@ -986,6 +907,89 @@ function sleep(ms) {
 	return new Promise((done) => setTimeout(done, ms));
 }
 //#endregion
+//#region src/core/checks.ts
+/**
+* A `many` outcome never passes anything but `toHaveCount`. An ambiguous locator
+* is a strictness violation, and it reports through the same message path as a
+* plain mismatch rather than guessing which node was meant.
+*/
+function evaluate(check, resolution) {
+	if (check.name === "toHaveCount") {
+		const count = countOf(resolution);
+		return {
+			pass: count === check.expected,
+			actual: String(count)
+		};
+	}
+	if (resolution.outcome === "none") return {
+		pass: false,
+		actual: null
+	};
+	if (resolution.outcome === "many") return {
+		pass: false,
+		actual: `${String(resolution.nodes.length)} matching nodes`
+	};
+	const node = resolution.node;
+	switch (check.name) {
+		case "toBeVisible": return {
+			pass: true,
+			actual: describeNode(node)
+		};
+		case "toHaveText": {
+			const text = node.name ?? node.value;
+			return {
+				pass: matchesText(check.expected, text),
+				actual: text === null ? null : `"${text}"`
+			};
+		}
+		case "toHaveValue": return {
+			pass: matchesText(check.expected, node.value),
+			actual: node.value === null ? null : `"${node.value}"`
+		};
+		case "toBeEnabled": return {
+			pass: node.enabled,
+			actual: node.enabled ? "enabled" : "disabled"
+		};
+		case "toBeSelected": return {
+			pass: node.selected,
+			actual: node.selected ? "selected" : "not selected"
+		};
+		case "toBeFocused": return {
+			pass: node.focused,
+			actual: node.focused ? "focused" : "not focused"
+		};
+		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
+	}
+}
+function countOf(resolution) {
+	switch (resolution.outcome) {
+		case "one": return 1;
+		case "none": return 0;
+		case "many": return resolution.nodes.length;
+		default: throw new Error(`unhandled resolution ${JSON.stringify(resolution)}`);
+	}
+}
+/** The `Expected:` line. */
+function describeCheck(check) {
+	switch (check.name) {
+		case "toBeVisible": return "visible";
+		case "toHaveText": return `text ${describeExpected(check.expected)}`;
+		case "toHaveValue": return `value ${describeExpected(check.expected)}`;
+		case "toBeEnabled": return "enabled";
+		case "toBeSelected": return "selected";
+		case "toBeFocused": return "focused";
+		case "toHaveCount": return `count ${String(check.expected)}`;
+		default: throw new Error(`unhandled check ${JSON.stringify(check)}`);
+	}
+}
+function describeExpected(match) {
+	return match.kind === "regex" ? String(match.value) : `"${match.value}"`;
+}
+function describeNode(node) {
+	const name = node.name === null ? "" : ` "${node.name}"`;
+	return `${node.ref} [${node.role}]${name}`;
+}
+//#endregion
 //#region src/core/probe.ts
 const POLL_INTERVAL_MS = 250;
 const SCREEN_LISTING_NODES = 60;
@@ -1300,10 +1304,10 @@ function perform(session, sink, record, options, dispatch, write) {
 					}
 					attempts += 1;
 					if (!settled.settled) sink.note("settle", `${renderTitle(record)} finished before the screen went quiet`);
-					if (confirmation === null) return;
+					if (confirmation === null || write === void 0) return;
 					if (attempts === 1) await sink.step(renderTitle({
 						kind: "typed",
-						typed: typedOf(confirmation)
+						typed: typedOf(resolution.node.role, write)
 					}), () => Promise.resolve(), { box: true });
 					target = identityOf(screen, resolution.node);
 					screen = await device.capture();
@@ -1391,26 +1395,37 @@ function ambiguous(locator, nodes, screen) {
 	});
 }
 function confirmationOf(role, write) {
+	const length = write.text.length;
 	if (role === "secure-text-field") return {
 		kind: "mask",
-		length: write.text.length
+		length
 	};
+	const value = normalizeText(write.text);
 	return write.secret ? {
 		kind: "secret",
-		value: write.text
+		value,
+		length
 	} : {
 		kind: "open",
-		value: write.text
+		value,
+		length
 	};
 }
 function holds(confirmation, actual) {
 	switch (confirmation.kind) {
-		case "mask": return actual.length === confirmation.length && new Set(actual).size <= 1;
+		case "mask": return isMask(actual, confirmation.length);
 		case "secret":
-		case "open": return actual === confirmation.value;
+		case "open": return actual === confirmation.value || isMask(actual, confirmation.length);
 		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
 	}
 }
+/**
+* Requiring one repeated character stops a placeholder of the right length, which
+* is what an untouched password field reports, from passing as a landed write.
+*/
+function isMask(actual, length) {
+	return actual.length === length && new Set(actual).size <= 1;
+}
 function expectedOf(confirmation) {
 	switch (confirmation.kind) {
 		case "mask": return {
@@ -1428,22 +1443,16 @@ function expectedOf(confirmation) {
 		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
 	}
 }
-function typedOf(confirmation) {
-	switch (confirmation.kind) {
-		case "mask": return {
-			kind: "hidden",
-			length: confirmation.length
-		};
-		case "secret": return {
-			kind: "hidden",
-			length: confirmation.value.length
-		};
-		case "open": return {
-			kind: "text",
-			value: confirmation.value
-		};
-		default: throw new Error(`unhandled confirmation ${JSON.stringify(confirmation)}`);
-	}
+/** What the report says was typed, verbatim, which the normalized confirmation no longer holds. */
+function typedOf(role, write) {
+	if (role === "secure-text-field" || write.secret) return {
+		kind: "hidden",
+		length: write.text.length
+	};
+	return {
+		kind: "text",
+		value: write.text
+	};
 }
 /** An actual value may be repeated back only as far as the expected one could be. */
 function disclose(expected, actual) {
@@ -1747,21 +1756,24 @@ function compareScreenshot(expected, actual, options) {
 	};
 }
 /**
-* The box is clamped to the image, because a rect comes from a snapshot and a
+* The box is clipped to the image, because a rect comes from a snapshot and a
 * screenshot is a separate capture. A control flush against the bottom edge can
-* round a pixel past it, and that is not a reason to fail an assertion.
+* round a pixel past it, and that is not a reason to fail an assertion. A box
+* with no pixel inside the image is a different thing, a rect the screenshot
+* does not show, and cutting a placeholder out of the corner would hide that.
 */
 function cropScreenshot(source, box) {
 	const image = PNG.sync.read(source);
-	const clamped = clamp(box, {
+	const clipped = intersect(box, {
 		width: image.width,
 		height: image.height
 	});
+	if (clipped === null) throw new Error(`the crop at ${String(box.x)},${String(box.y)} ${String(box.width)}x${String(box.height)} lies outside the ${String(image.width)}x${String(image.height)} screenshot`);
 	const cut = new PNG({
-		width: clamped.width,
-		height: clamped.height
+		width: clipped.width,
+		height: clipped.height
 	});
-	PNG.bitblt(image, cut, clamped.x, clamped.y, clamped.width, clamped.height, 0, 0);
+	PNG.bitblt(image, cut, clipped.x, clipped.y, clipped.width, clipped.height, 0, 0);
 	return PNG.sync.write(cut);
 }
 function sizeOf(source) {
@@ -1790,21 +1802,30 @@ function relativeTo(box, origin) {
 		y: box.y - origin.y
 	};
 }
-function clamp(box, size) {
-	const x = Math.min(Math.max(box.x, 0), Math.max(size.width - 1, 0));
-	const y = Math.min(Math.max(box.y, 0), Math.max(size.height - 1, 0));
+/**
+* The part of the box inside the image, or null when none of it is. A mask
+* resolved off a node outside a crop must paint nothing, because moving it
+* inside would black out real pixels at the crop's edge.
+*/
+function intersect(box, size) {
+	const left = Math.max(box.x, 0);
+	const top = Math.max(box.y, 0);
+	const right = Math.min(box.x + box.width, size.width);
+	const bottom = Math.min(box.y + box.height, size.height);
+	if (right <= left || bottom <= top) return null;
 	return {
-		x,
-		y,
-		width: Math.max(Math.min(box.width, size.width - x), 1),
-		height: Math.max(Math.min(box.height, size.height - y), 1)
+		x: left,
+		y: top,
+		width: right - left,
+		height: bottom - top
 	};
 }
 function paintBlack(image, box) {
-	const region = clamp(box, {
+	const region = intersect(box, {
 		width: image.width,
 		height: image.height
 	});
+	if (region === null) return;
 	for (let row = region.y; row < region.y + region.height; row += 1) for (let column = region.x; column < region.x + region.width; column += 1) {
 		const at = image.width * row + column << 2;
 		image.data[at] = 0;
@@ -1896,4 +1917,4 @@ function notBooted(platform, name, booted) {
 	return `No booted ${platform} device is named '${name}'. Booted right now: ${booted.map((device) => `'${device.name}'`).join(", ")}. Set use.deviceName to one of those or boot '${name}'.`;
 }
 //#endregion
-export { textMatch as A, renderScreen as C, parseDeviceOptions as D, deviceNameForSlot as E, describeQuery as O, parseScreen as S, TOUCHPRESS_DEFAULTS as T, sleep as _, sizeOf as a, renderTitle as b, createClient as c, createScrollSearch as d, directionToward as f, sessionName as g, openSession as h, relativeTo as i, TouchpressError as j, normalizeText as k, captureEvidence as l, probe as m, compareScreenshot as n, toPixelBox as o, formatFailure as p, cropScreenshot as r, createAgentDeviceDriver as s, preflight as t, createDevice as u, describeCheck as v, resolve as w, silentSink as x, evaluate as y };
+export { normalizeText as A, parseScreen as C, deviceNameForSlot as D, TOUCHPRESS_DEFAULTS as E, TouchpressError as M, parseDeviceOptions as O, silentSink as S, resolve as T, createQueue as _, sizeOf as a, sleep as b, createClient as c, createScrollSearch as d, directionToward as f, evaluate as g, describeCheck as h, relativeTo as i, textMatch as j, describeQuery as k, captureEvidence as l, probe as m, compareScreenshot as n, toPixelBox as o, formatFailure as p, cropScreenshot as r, createAgentDeviceDriver as s, preflight as t, createDevice as u, openSession as v, renderScreen as w, renderTitle as x, sessionName as y };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "touchpress",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "End-to-end testing for mobile apps.",
   "homepage": "https://github.com/wobsoriano/touchpress#readme",
   "bugs": {