@webhands/core 0.4.0 → 0.6.0

package/src/hand-host.ts

@@ -1,11 +1,35 @@
-import {errors as pwErrors, type BrowserContext, type Page} from 'playwright';
+import {
+	errors as pwErrors,
+	type BrowserContext,
+	type Frame,
+	type Locator,
+	type Page,
+} from 'playwright';
 import type {
+	ActionOptions,
+	BoundingBox,
 	Cookie,
+	EvalOptions,
 	WebHandsPage,
+	MouseInput,
+	QueryOptions,
+	QueryRow,
+	Screenshot,
+	ScreenshotOptions,
+	ScrollTarget,
+	SelectChoice,
 	Snapshot,
 	SnapshotOptions,
 	WaitCondition,
 } from './seam.js';
+import {validateSnapshotOptions} from './seam.js';
+import {
+	CrossOriginFrameError,
+	ScreenshotPathError,
+	StaleRefError,
+} from './errors.js';
+import {mkdir} from 'node:fs/promises';
+import {isAbsolute, join, relative, resolve as resolvePath} from 'node:path';
 
 /**
  * The hand-host primitive (Phase 1 of the "hands" prd,
@@ -65,6 +89,17 @@ export interface HandContext {
 	readonly pwPage: Page;
 	readonly context: BrowserContext;
 	readonly ensureOpen: () => void;
+	/**
+	 * The managed SCREENSHOTS directory the `screenshot` verb mints PNGs under
+	 * (Tier-4, prd `broaden-agent-verb-surface`, R3). Resolved by each transport
+	 * from its home root (`<homeRoot>/screenshots`, beside `profiles/`) via
+	 * {@link resolveScreenshotsDir}, so the same `root`/`WEBHANDS_HOME` override
+	 * that isolates profiles in a test isolates screenshots too. The verb creates
+	 * it lazily on first write and validates any caller `out` override stays under
+	 * it ({@link ScreenshotPathError}). Carried HERE (not on the seam) so no path
+	 * policy leaks into the public {@link WebHandsPage} surface (ADR-0003).
+	 */
+	readonly screenshotsDir: string;
 }
 
 /**
@@ -171,6 +206,18 @@ const REQUIRED_VERBS = [
 	'wait',
 	'cookies',
 	'setCookies',
+	'query',
+	'count',
+	'exists',
+	'isVisible',
+	'getAttribute',
+	'press',
+	'hover',
+	'select',
+	'scroll',
+	'drag',
+	'mouse',
+	'screenshot',
 ] as const satisfies ReadonlyArray<keyof WebHandsPage>;
 
 /**
@@ -203,6 +250,17 @@ function assertCompletePage(verbs: Partial<WebHandsPage>): WebHandsPage {
  */
 const NORMAL_CLICK_TIMEOUT_MS = 1_000;
 
+/**
+ * How long {@link resolveSameOriginFrame} waits for the `frame` selector to
+ * resolve to an iframe element before treating it as "no such frame". Short on
+ * purpose: a frame-scoped `eval` against a bad selector should fail LOUD fast,
+ * not burn Playwright's 30s default auto-wait (the same reasoning as
+ * {@link NORMAL_CLICK_TIMEOUT_MS}). An iframe present in the markup resolves
+ * immediately and never approaches this bound; it is the latency cost paid ONLY
+ * on the no-such-frame path.
+ */
+const FRAME_RESOLVE_TIMEOUT_MS = 1_000;
+
 // ---------------------------------------------------------------------------
 // Built-in hands: webhands' OWN eight verbs, each a hand over the host.
 //
@@ -236,6 +294,10 @@ export const snapshotHand: Hand = ({pwPage, ensureOpen}) => ({
 	verbs: {
 		async snapshot(options?: SnapshotOptions): Promise<Snapshot> {
 			ensureOpen();
+			// Reject an unknown/misshapen option LOUDLY (e.g. `{view: 'full'}`)
+			// rather than silently returning the wrong view. Single source of
+			// truth in the seam, shared with the RPC server dispatch.
+			validateSnapshotOptions(options);
 			const url = pwPage.url();
 			if (options?.full === true) {
 				// `--full`: the raw DOM. `documentElement.outerHTML` is the serialized
@@ -259,15 +321,29 @@ export const snapshotHand: Hand = ({pwPage, ensureOpen}) => ({
 	},
 });
 
-/** The `click` + `type` verbs: page interaction by raw locator (ADR-0004). */
+/**
+ * The `click` + `type` verbs: page interaction by raw locator (ADR-0004).
+ *
+ * With `{byRef: true}` the target is a durable `query` {@link QueryRow.ref}: it
+ * is resolved through the SAME {@link resolveLocator} but FIRST asserted to match
+ * EXACTLY ONE element ({@link assertRefResolvesToOne}), so a stale (zero) or
+ * ambiguous (many) ref fails LOUD with a {@link StaleRefError} instead of
+ * silently acting on the wrong element — the safety the durable ref exists for.
+ */
 export const interactionHand: Hand = ({pwPage, ensureOpen}) => ({
 	verbs: {
-		async click(t): Promise<void> {
+		async click(t, options?: ActionOptions): Promise<void> {
 			ensureOpen();
+			if (options?.byRef === true) {
+				await assertRefResolvesToOne(pwPage, t, 'click');
+			}
 			await clickLocator(pwPage, t);
 		},
-		async type(t, text): Promise<void> {
+		async type(t, text, options?: ActionOptions): Promise<void> {
 			ensureOpen();
+			if (options?.byRef === true) {
+				await assertRefResolvesToOne(pwPage, t, 'type');
+			}
 			await resolveLocator(pwPage, t).fill(text);
 		},
 	},
@@ -276,22 +352,9 @@ export const interactionHand: Hand = ({pwPage, ensureOpen}) => ({
 /** The `eval` escape hatch: run a JS EXPRESSION in the page, return by value. */
 export const evalHand: Hand = ({pwPage, ensureOpen}) => ({
 	verbs: {
-		async eval(expression: string): Promise<unknown> {
+		async eval(expression: string, options?: EvalOptions): Promise<unknown> {
 			ensureOpen();
-			// The `eval` escape hatch (PRD story 9): run the raw JS EXPRESSION in the
-			// page and return its serializable result. Playwright's `evaluate`
-			// already IS the seam's serialization contract (see {@link WebHandsPage.eval}):
-			// it passes a string as an expression, awaits a returned Promise, and
-			// structurally clones the result out of the page by VALUE. That clone is
-			// richer than JSON: it preserves NaN/Infinity/BigInt and circular
-			// structures (back-refs become a `[Circular]` marker), yields `undefined`
-			// for functions/symbols, and returns an opaque preview string for a live
-			// host object (a DOM node never crosses the process boundary). A page-side
-			// throw rejects. We pass it straight through rather than re-encode it:
-			// wrapping the value in a transport-specific envelope would invent a
-			// dialect the seam deliberately avoids. The thrown error is a plain
-			// `Error`, so no Playwright/CDP type leaks across the seam (ADR-0003).
-			return pwPage.evaluate(expression);
+			return evalExpression(pwPage, expression, options);
 		},
 	},
 });
@@ -326,7 +389,147 @@ export const cookiesHand: Hand = ({context, ensureOpen}) => ({
 });
 
 /**
- * webhands' eight built-in verbs as built-in hands, in composition order. Both
+ * The Tier-1 read verbs (prd `broaden-agent-verb-surface`, R2): the `query`
+ * extraction verb plus the thin state shorthands `count` / `exists` /
+ * `isVisible` / `getAttribute`. All five address element(s) by the SAME raw
+ * Playwright locator expression the other verbs use, resolved through the ONE
+ * existing {@link resolveLocator} (so a `frameLocator(...)` same-origin frame
+ * hop in the string Just Works, and there is no parallel addressing scheme —
+ * R1). They are pure READS: no page mutation.
+ *
+ * `query` returns one row per match carrying EXACTLY the requested fields (R2);
+ * the state verbs are computed over the same machinery (see {@link queryRows}
+ * and the per-verb bodies). Read values cross by structured clone, the same
+ * contract as `eval` (ADR-0003).
+ */
+export const queryHand: Hand = ({pwPage, ensureOpen}) => ({
+	verbs: {
+		async query(target, options?: QueryOptions): Promise<QueryRow[]> {
+			ensureOpen();
+			return queryRows(pwPage, target, options);
+		},
+		async count(target): Promise<number> {
+			ensureOpen();
+			return resolveLocator(pwPage, target).count();
+		},
+		async exists(target): Promise<boolean> {
+			ensureOpen();
+			return (await resolveLocator(pwPage, target).count()) > 0;
+		},
+		async isVisible(target): Promise<boolean> {
+			ensureOpen();
+			// The FIRST match's actionability-grade visibility. `.first().isVisible()`
+			// returns `false` for an ABSENT element too (no match cannot be visible),
+			// which is the loud, correct answer for the absent case.
+			return resolveLocator(pwPage, target).first().isVisible();
+		},
+		async getAttribute(target, name: string): Promise<string | null> {
+			ensureOpen();
+			// The FIRST match's DOM attribute. `.first().getAttribute()` resolves to
+			// `null` for an absent attribute AND surfaces a clean miss for an absent
+			// element (it would otherwise time out); we treat "no element" as `null`
+			// (there is no attribute value to read) rather than hanging.
+			if ((await resolveLocator(pwPage, target).count()) === 0) {
+				return null;
+			}
+			return resolveLocator(pwPage, target).first().getAttribute(name);
+		},
+	},
+});
+
+/**
+ * The Tier-2 rich INPUT verbs (prd `broaden-agent-verb-surface`, stories 8-12):
+ * `press` / `hover` / `select` / `scroll` / `drag`. These lift page-level
+ * Playwright actions a hand already has on `pwPage` (`keyboard.press`,
+ * `hover`, `selectOption`, `mouse.wheel`/`scrollIntoViewIfNeeded`, `dragTo`) up
+ * to the agent verb seam so a seam-only agent can drive a browser game or a
+ * richer form, not just `click`/`type`.
+ *
+ * Every locator-addressing form resolves through the SAME single
+ * {@link resolveLocator} the other verbs use (so a same-origin `frameLocator(...)`
+ * hop in the string Just Works — no parallel addressing scheme, R1). Keys are
+ * strings, offsets are numbers, locators are strings: nothing Playwright-shaped
+ * crosses the seam (ADR-0003).
+ */
+export const inputHand: Hand = ({pwPage, ensureOpen}) => ({
+	verbs: {
+		async press(key, target): Promise<void> {
+			ensureOpen();
+			if (target !== undefined) {
+				// At a locator: Playwright focuses the element first, then presses
+				// (the `locator.press` semantics).
+				await resolveLocator(pwPage, target).press(key);
+				return;
+			}
+			// No locator: the page's currently focused element receives the key.
+			await pwPage.keyboard.press(key);
+		},
+		async hover(target): Promise<void> {
+			ensureOpen();
+			await resolveLocator(pwPage, target).hover();
+		},
+		async select(target, choice: SelectChoice): Promise<void> {
+			ensureOpen();
+			// EXACTLY ONE of value/label (the seam type enforces it); map to
+			// Playwright's `selectOption({value})` / `selectOption({label})`.
+			const option =
+				'value' in choice ? {value: choice.value} : {label: choice.label};
+			await resolveLocator(pwPage, target).selectOption(option);
+		},
+		async scroll(target: ScrollTarget): Promise<void> {
+			ensureOpen();
+			if ('to' in target) {
+				// Reach an off-viewport element by scrolling it into view.
+				await resolveLocator(pwPage, target.to).scrollIntoViewIfNeeded();
+				return;
+			}
+			// Scroll the page by a pixel delta (the wheel convention: positive dy
+			// scrolls DOWN).
+			await pwPage.mouse.wheel(target.by.dx, target.by.dy);
+		},
+		async drag(source, target): Promise<void> {
+			ensureOpen();
+			await resolveLocator(pwPage, source).dragTo(
+				resolveLocator(pwPage, target),
+			);
+		},
+	},
+});
+
+/**
+ * The Tier-4 COORDINATE + SCREENSHOT hand (prd `broaden-agent-verb-surface`,
+ * R3; stories 17-19): the `mouse` coordinate-input verb and the `screenshot`
+ * path-returning verb, the look-then-click pair that lets a seam-only agent
+ * handle the VISION/TILE captcha family and any visual task.
+ *
+ * The seam stays ADR-0003-clean (as amended by the Tier-4 ADR) by passing ONLY
+ * numbers + a string enum (`mouse`) and returning ONLY a file PATH + dimensions
+ * (`screenshot`): NO image bytes and NO Playwright/CDP type cross the seam.
+ *
+ * - `mouse` drives Playwright `page.mouse` at VIEWPORT CSS-pixels (NOT OS-level
+ *   input). A VIEWPORT screenshot's pixels map directly to these coordinates
+ *   (the look-then-click contract); a FULL-PAGE shot does not.
+ * - `screenshot` MINTS a PNG under the managed {@link HandContext.screenshotsDir}
+ *   and returns its path. The `element` scope clips to a locator (resolved
+ *   through the SAME {@link resolveLocator}, so a cross-origin `frameLocator(...)`
+ *   widget shot Just Works). A caller `out` override is validated to stay under
+ *   the managed dir ({@link ScreenshotPathError}).
+ */
+export const coordinateHand: Hand = ({pwPage, ensureOpen, screenshotsDir}) => ({
+	verbs: {
+		async mouse(input: MouseInput): Promise<void> {
+			ensureOpen();
+			await doMouse(pwPage, input);
+		},
+		async screenshot(options?: ScreenshotOptions): Promise<Screenshot> {
+			ensureOpen();
+			return takeScreenshot(pwPage, screenshotsDir, options);
+		},
+	},
+});
+
+/**
+ * webhands' built-in verbs as built-in hands, in composition order. Both
  * Playwright transports compose THIS exact set, so the verb surface is
  * identical across launch and attach (the only legitimate difference is the
  * per-transport SESSION LIFECYCLE, which is not a hand's concern).
@@ -338,6 +541,9 @@ export const BUILT_IN_HANDS: readonly Hand[] = [
 	evalHand,
 	waitHand,
 	cookiesHand,
+	queryHand,
+	inputHand,
+	coordinateHand,
 ];
 
 /**
@@ -416,6 +622,144 @@ export async function waitFor(
 	}
 }
 
+/**
+ * Run the `eval` verb against a Playwright page (PRD story 9; frame scope from
+ * prd `broaden-agent-verb-surface`, Tier-3), shared by both Playwright
+ * transports (via the built-in eval hand) so the verb behaves identically (no
+ * parallel second implementation).
+ *
+ * With no `frame`, this is the top-document escape hatch: Playwright's
+ * `evaluate` IS the seam's serialization contract (see {@link WebHandsPage.eval}):
+ * it passes a string as an expression, awaits a returned Promise, and
+ * structurally clones the result out of the page by VALUE. That clone is richer
+ * than JSON: it preserves NaN/Infinity/BigInt and circular structures (back-refs
+ * become a `[Circular]` marker), yields `undefined` for functions/symbols, and
+ * returns an opaque preview string for a live host object (a DOM node never
+ * crosses the process boundary). A page-side throw rejects. We pass it straight
+ * through rather than re-encode it: wrapping the value in a transport-specific
+ * envelope would invent a dialect the seam deliberately avoids. The thrown error
+ * is a plain `Error`, so no Playwright/CDP type leaks across the seam (ADR-0003).
+ *
+ * With a `frame` selector, the SAME structured-clone contract holds, but the
+ * expression runs in the named SAME-ORIGIN child frame (resolved through the
+ * single {@link resolveSameOriginFrame}, which reuses the same
+ * {@link resolveLocator} the locator-taking verbs use). A cross-origin frame
+ * REJECTS with a typed {@link CrossOriginFrameError} (see that resolver).
+ */
+export async function evalExpression(
+	page: Page,
+	expression: string,
+	options?: EvalOptions,
+): Promise<unknown> {
+	if (options?.frame === undefined) {
+		return page.evaluate(expression);
+	}
+	const frame = await resolveSameOriginFrame(page, options.frame);
+	// `frame.evaluate` honours the SAME structured-clone contract as
+	// `page.evaluate` (it is the same Playwright serialization), so the
+	// frame-scoped result crosses the seam by value exactly as the top-document
+	// `eval` does.
+	return frame.evaluate(expression);
+}
+
+/**
+ * Resolve a `frame` SELECTOR string to a live, SAME-ORIGIN Playwright
+ * {@link Frame} for a frame-scoped `eval` (prd `broaden-agent-verb-surface`,
+ * Tier-3, R1). This is the SINGLE frame resolver: it reuses the very same
+ * {@link resolveLocator} the locator-taking verbs use (a `frameLocator(...)`
+ * over the selector), then walks the iframe element handle to its content
+ * frame — there is no parallel frame-addressing scheme.
+ *
+ * SAME-ORIGIN ONLY, enforced LOUD. Playwright will happily `evaluate` inside a
+ * CROSS-ORIGIN OOPIF (it attaches out-of-band), so a cross-origin frame would
+ * NOT throw on its own — it would silently succeed, which is exactly the
+ * contract violation this verb forbids (page-world JS cannot cross a security
+ * boundary; the seam is same-origin only). So we DETECT cross-origin by
+ * comparing the frame's origin to the page's main-frame origin and reject with a
+ * typed {@link CrossOriginFrameError} when they differ, never returning a frame
+ * the page world could not legitimately reach.
+ *
+ * Failure modes are loud/typed: a selector that matches NO iframe element
+ * rejects (the locator resolves nothing); a matched frame with no content frame
+ * rejects; a cross-origin frame rejects with {@link CrossOriginFrameError}.
+ */
+export async function resolveSameOriginFrame(
+	page: Page,
+	selector: string,
+): Promise<Frame> {
+	// Reuse the ONE resolver: treat the selector as the argument to
+	// `frameLocator(...)`, exactly how a locator-taking verb would frame-hop. We
+	// build the expression with a JSON-encoded selector so an arbitrary CSS
+	// selector cannot break out of the call.
+	const frameLocator = resolveLocator(
+		page,
+		`p.frameLocator(${JSON.stringify(selector)})`,
+	) as unknown as {owner(): Locator};
+	// Bound the resolve: a selector that matches NO iframe must fail LOUD quickly
+	// rather than burn Playwright's 30s default auto-wait (mirrors the short
+	// bound `clickLocator` uses for a non-actionable element). `elementHandle`
+	// throws a TimeoutError on no match within the bound; we map it to a clear
+	// "no iframe matched" error.
+	let handle: Awaited<ReturnType<Locator['elementHandle']>>;
+	try {
+		handle = await frameLocator
+			.owner()
+			.elementHandle({timeout: FRAME_RESOLVE_TIMEOUT_MS});
+	} catch (cause) {
+		if (cause instanceof pwErrors.TimeoutError) {
+			throw new Error(
+				`eval --frame: no iframe element matched selector ${JSON.stringify(
+					selector,
+				)}.`,
+			);
+		}
+		throw cause;
+	}
+	if (handle === null) {
+		throw new Error(
+			`eval --frame: no iframe element matched selector ${JSON.stringify(
+				selector,
+			)}.`,
+		);
+	}
+	try {
+		const frame = await handle.contentFrame();
+		if (frame === null) {
+			throw new Error(
+				`eval --frame: the element matched by selector ${JSON.stringify(
+					selector,
+				)} is not a frame.`,
+			);
+		}
+		const pageOrigin = originOf(page.mainFrame().url());
+		const frameOrigin = originOf(frame.url());
+		if (frameOrigin === null || frameOrigin !== pageOrigin) {
+			throw new CrossOriginFrameError(selector, {
+				frameOrigin: frameOrigin ?? undefined,
+				pageOrigin: pageOrigin ?? undefined,
+			});
+		}
+		return frame;
+	} finally {
+		await handle.dispose();
+	}
+}
+
+/**
+ * The origin (`scheme://host:port`) of a frame/page URL, or `null` when the URL
+ * has no parseable origin (e.g. `about:blank`). Used to compare a child frame's
+ * origin against the page's, the same-origin check the frame-scoped `eval`
+ * enforces. An unparseable / opaque origin reads as NOT same-origin (loud over
+ * silent): the frame is not provably reachable, so we treat it as cross-origin.
+ */
+function originOf(url: string): string | null {
+	try {
+		return new URL(url).origin;
+	} catch {
+		return null;
+	}
+}
+
 /**
  * Resolve a raw Playwright locator EXPRESSION (ADR-0004) against the page. The
  * verb surface passes locator expressions like `getByRole('button', …)`; we
@@ -455,6 +799,19 @@ export function resolveLocator(page: Page, expression: string) {
  * bad locator) surfaces its timeout quickly instead of hanging the dispatch on
  * Playwright's 30s default — the dispatch escape is for elements that EXIST but
  * are not actionable (hidden custom inputs), not for absent ones.
+ *
+ * The happy-path click passes `noWaitAfter: true` on purpose. Playwright's
+ * `Locator.click()` normally clicks AND THEN auto-waits for any navigation the
+ * click scheduled to finish, and that post-click wait counts against the same
+ * timeout. A real submit button whose navigation takes longer than
+ * {@link NORMAL_CLICK_TIMEOUT_MS} would therefore have its (already-performed)
+ * click reported as a `TimeoutError` and be wrongly routed to the dispatch
+ * escape, which then re-clicks a page that is already navigating away. We only
+ * want the short budget to measure ACTIONABILITY (can we click it?), not how
+ * long the resulting navigation takes — `noWaitAfter` returns as soon as the
+ * click is performed, so a slow-but-successful submit no longer trips the
+ * fallback. A genuinely non-actionable hidden input still cannot be clicked
+ * within the budget and still falls through to `dispatchEvent` as before.
  */
 export async function clickLocator(
 	page: Page,
@@ -462,7 +819,7 @@ export async function clickLocator(
 ): Promise<void> {
 	const target = resolveLocator(page, expression);
 	try {
-		await target.click({timeout: NORMAL_CLICK_TIMEOUT_MS});
+		await target.click({timeout: NORMAL_CLICK_TIMEOUT_MS, noWaitAfter: true});
 	} catch (cause) {
 		if (!(cause instanceof pwErrors.TimeoutError)) {
 			throw cause;
@@ -473,6 +830,425 @@ export async function clickLocator(
 	}
 }
 
+/**
+ * Run the `query` verb (prd `broaden-agent-verb-surface`, R2) against a
+ * Playwright page: resolve the locator EXPRESSION through the SINGLE existing
+ * {@link resolveLocator} (so a same-origin `frameLocator(...)` hop in the string
+ * Just Works), then return ONE ROW PER MATCH carrying EXACTLY the requested
+ * fields and nothing else.
+ *
+ * The split is LOUD and never auto-detected:
+ * - `attrs[name]` is the element's `getAttribute(name)` (the markup value;
+ *   `null` if absent).
+ * - `props[name]` is the live `el[name]` JS property (runtime state), read in
+ *   one page-world `evaluate` over the element so the value is structurally
+ *   cloned out by VALUE — the SAME serialization contract `eval` documents
+ *   (ADR-0003: no Playwright/CDP type leak; richer than JSON).
+ * - `pw.visible` / `pw.bbox` are the closed Playwright-locator extras
+ *   (`isVisible()` / `boundingBox()`), the only facts not expressible as an
+ *   attribute or a property. `bbox` is in VIEWPORT CSS-pixels.
+ *
+ * `limit` bounds the row count. With no fields requested every row is an empty
+ * object (the caller asked for nothing; R2). Each row is built independently so
+ * a per-element read failure is the page's own throw, surfaced faithfully like
+ * `eval` (no silent swallow).
+ */
+export async function queryRows(
+	page: Page,
+	expression: string,
+	options?: QueryOptions,
+): Promise<QueryRow[]> {
+	const attrs = options?.attrs ?? [];
+	const props = options?.props ?? [];
+	const pw = options?.pw ?? [];
+	const withRefs = options?.refs === true;
+	const base = resolveLocator(page, expression);
+	const total = await base.count();
+	const limit =
+		options?.limit !== undefined ? Math.max(0, options.limit) : total;
+	const rowCount = Math.min(total, limit);
+
+	// Refs are single-`query`-scoped: each `refs: true` query SWEEPS the PRIOR
+	// query's minted attributes FIRST (page-wide), so a ref can never resolve a
+	// stale element minted two queries ago. Reused stable attrs (ladder step 1)
+	// are the framework's own and are untouched. Done once, before iterating.
+	if (withRefs) {
+		await sweepPriorMints(page);
+	}
+
+	const rows: QueryRow[] = [];
+	for (let i = 0; i < rowCount; i++) {
+		rows.push(await readRow(base.nth(i), attrs, props, pw, withRefs));
+	}
+	return rows;
+}
+
+/**
+ * The namespaced attribute the MINT fallback (ladder step 2) stamps on an
+ * anonymous element. A `query({refs: true})` sweeps every node carrying it
+ * before re-minting, so mints stay single-query-scoped.
+ */
+const REF_MINT_ATTR = 'data-webhands-ref';
+
+/**
+ * Remove EVERY {@link REF_MINT_ATTR} attribute currently in the document, the
+ * single-`query`-scope sweep run at the start of each `refs: true` query. This
+ * touches ONLY webhands' own minted attribute — never a framework's stable attrs
+ * (ladder step 1 reuses those, it does not stamp them), so a sweep cannot break
+ * a reused-attribute ref.
+ */
+async function sweepPriorMints(page: Page): Promise<void> {
+	await page.evaluate((attr) => {
+		document.querySelectorAll('[' + attr + ']').forEach((el) => {
+			el.removeAttribute(attr);
+		});
+	}, REF_MINT_ATTR);
+}
+
+/**
+ * Compute the durable {@link QueryRow.ref} for ONE matched element by the R4
+ * PREFERENCE LADDER, in page-world (the finding
+ * `query-ref-mint-mechanism-attribute-beats-weakmap` settled the mechanism: a
+ * `data-webhands-ref` ATTRIBUTE, not a WeakMap).
+ *
+ * Returns the ref as a LOCATOR EXPRESSION the ONE existing {@link resolveLocator}
+ * resolves — `p.locator('<css>')` — NOT a bare CSS string, so `click`/`type`
+ * feed it back through the exact same resolver path as any other locator (no new
+ * addressing engine, R1). The human-legible CSS the ladder picks rides INSIDE
+ * that expression (`p.locator('#buy-charlie')`).
+ *
+ * Ladder:
+ * 1. REUSE the element's own stable, VERIFIED-UNIQUE attribute, in priority
+ *    `id` > `data-testid`/`data-test`/`data-id` > `name` > a link's `href` >
+ *    a unique `aria-label`. The CSS IS the element's real address: durable
+ *    across reconciliation (the framework keeps its OWN attrs), legible, ZERO
+ *    DOM mutation. Uniqueness is VERIFIED with
+ *    `querySelectorAll(...).length === 1`; a duplicate (e.g. two equal ids)
+ *    FALLS THROUGH to the next rung.
+ * 2. MINT a namespaced {@link REF_MINT_ATTR} as the fallback for an anonymous
+ *    element with no stable unique address, addressed by
+ *    `[data-webhands-ref="<id>"]`.
+ *
+ * The minted-id counter lives on `window` so ids are unique within the page for
+ * the life of the document (the sweep clears stale ATTRIBUTES, not the counter,
+ * so a re-mint never reuses an id a still-resolvable ref might hold).
+ */
+async function computeRef(cell: Locator): Promise<string> {
+	const css = await cell.evaluate((el: Element, attr: string): string => {
+		const cssEscape = (v: string): string =>
+			typeof (window as {CSS?: {escape?: (s: string) => string}}).CSS
+				?.escape === 'function'
+				? (
+						window as unknown as {CSS: {escape: (s: string) => string}}
+					).CSS.escape(v)
+				: v.replace(/[^a-zA-Z0-9_-]/g, (c) => '\\' + c);
+		const uniq = (selector: string): boolean =>
+			document.querySelectorAll(selector).length === 1;
+
+		// Ladder step 1: reuse a stable, VERIFIED-UNIQUE existing attribute.
+		const id = el.getAttribute('id');
+		if (id !== null && id !== '') {
+			const sel = '#' + cssEscape(id);
+			if (uniq(sel)) return sel;
+		}
+		for (const name of ['data-testid', 'data-test', 'data-id', 'name']) {
+			const value = el.getAttribute(name);
+			if (value !== null && value !== '') {
+				const sel = '[' + name + '="' + value.replace(/"/g, '\\"') + '"]';
+				if (uniq(sel)) return sel;
+			}
+		}
+		// A link's href (only meaningful on an anchor).
+		if (el.tagName === 'A') {
+			const href = el.getAttribute('href');
+			if (href !== null && href !== '') {
+				const sel = 'a[href="' + href.replace(/"/g, '\\"') + '"]';
+				if (uniq(sel)) return sel;
+			}
+		}
+		// A unique aria-label.
+		const aria = el.getAttribute('aria-label');
+		if (aria !== null && aria !== '') {
+			const sel = '[aria-label="' + aria.replace(/"/g, '\\"') + '"]';
+			if (uniq(sel)) return sel;
+		}
+
+		// Ladder step 2: MINT the namespaced attribute (the fallback).
+		const w = window as unknown as {__webhandsRefSeq?: number};
+		w.__webhandsRefSeq = (w.__webhandsRefSeq ?? 0) + 1;
+		const mintedId = 'wr' + w.__webhandsRefSeq;
+		el.setAttribute(attr, mintedId);
+		return '[' + attr + '="' + mintedId + '"]';
+	}, REF_MINT_ATTR);
+	// Wrap the chosen CSS in a `p.locator(...)` expression so the ref resolves
+	// through the SAME resolver as every other locator. JSON-encode the CSS so a
+	// quote/backslash in a reused attribute value cannot break out of the call.
+	return `p.locator(${JSON.stringify(css)})`;
+}
+
+/**
+ * Resolve a durable `query` `ref` and assert it matches EXACTLY ONE element,
+ * else throw a typed {@link StaleRefError} (resolve-to-ZERO = removed/replaced;
+ * resolve-to-MANY = a cloned subtree / non-unique attribute). The loud-stale
+ * guard `click`/`type` run BEFORE acting when `{byRef: true}`, so a stale or
+ * ambiguous ref NEVER silently acts on the wrong element (the safety a ref has
+ * over a positional `.nth(i)`). Resolved through the SAME {@link resolveLocator}
+ * the verbs already use — no parallel addressing path.
+ */
+export async function assertRefResolvesToOne(
+	page: Page,
+	ref: string,
+	verb: string,
+): Promise<void> {
+	const matched = await resolveLocator(page, ref).count();
+	if (matched !== 1) {
+		throw new StaleRefError(ref, matched, verb);
+	}
+}
+
+/**
+ * Read ONE matched element into a {@link QueryRow}, carrying only the requested
+ * families. `attrs` and `props` are read in a SINGLE page-world `evaluate` over
+ * the element handle (so a row is one round-trip and `props` values are cloned
+ * by value); the `pw` extras use the locator API (`isVisible`/`boundingBox`).
+ */
+async function readRow(
+	cell: Locator,
+	attrs: readonly string[],
+	props: readonly string[],
+	pw: readonly string[],
+	withRef: boolean,
+): Promise<QueryRow> {
+	const row: {
+		attrs?: Record<string, string | null>;
+		props?: Record<string, unknown>;
+		pw?: {visible?: boolean; bbox?: BoundingBox | null};
+		ref?: string;
+	} = {};
+
+	if (attrs.length > 0 || props.length > 0) {
+		// One page-world read of the live element: `getAttribute` for the markup
+		// attrs, `el[name]` for the live JS props. The returned object is
+		// structurally cloned out of the page by Playwright (the `eval` contract),
+		// so a prop value crosses the seam by VALUE with no type leak.
+		const read = await cell.evaluate(
+			(
+				el: Element,
+				{
+					attrNames,
+					propNames,
+				}: {attrNames: readonly string[]; propNames: readonly string[]},
+			) => {
+				const out: {
+					attrs?: Record<string, string | null>;
+					props?: Record<string, unknown>;
+				} = {};
+				if (attrNames.length > 0) {
+					const a: Record<string, string | null> = {};
+					for (const name of attrNames) {
+						a[name] = el.getAttribute(name);
+					}
+					out.attrs = a;
+				}
+				if (propNames.length > 0) {
+					const p: Record<string, unknown> = {};
+					for (const name of propNames) {
+						p[name] = (el as unknown as Record<string, unknown>)[name];
+					}
+					out.props = p;
+				}
+				return out;
+			},
+			{attrNames: [...attrs], propNames: [...props]},
+		);
+		if (read.attrs !== undefined) {
+			row.attrs = read.attrs;
+		}
+		if (read.props !== undefined) {
+			row.props = read.props;
+		}
+	}
+
+	if (pw.length > 0) {
+		const extras: {visible?: boolean; bbox?: BoundingBox | null} = {};
+		if (pw.includes('visible')) {
+			extras.visible = await cell.isVisible();
+		}
+		if (pw.includes('bbox')) {
+			extras.bbox = await cell.boundingBox();
+		}
+		row.pw = extras;
+	}
+
+	// The durable handle (opt-in). Computed by the R4 ladder in page-world:
+	// reuse a stable unique attribute, else mint `data-webhands-ref`. Done after
+	// the reads so a mint can never perturb an attr/prop read of this row.
+	if (withRef) {
+		row.ref = await computeRef(cell);
+	}
+
+	return row;
+}
+
+/**
+ * Run the `mouse` verb (prd `broaden-agent-verb-surface`, Tier-4, R3) against a
+ * Playwright page: drive `page.mouse` at the given VIEWPORT CSS-pixel
+ * coordinate. Viewport-relative, NOT OS-level input — the same coordinate frame
+ * a VIEWPORT `screenshot` is captured in, so a pixel an agent saw maps directly
+ * to the click. Shared by both transports (via the coordinate hand) so the verb
+ * behaves identically. Plain numbers + a string enum only (ADR-0003 as amended).
+ */
+export async function doMouse(page: Page, input: MouseInput): Promise<void> {
+	const button = input.button ?? 'left';
+	switch (input.action) {
+		case 'move':
+			// A bare move takes no button (it is a pointer move, not a press).
+			await page.mouse.move(input.x, input.y);
+			return;
+		case 'click':
+			await page.mouse.click(input.x, input.y, {button});
+			return;
+		case 'down':
+			// down/up press/release at the CURRENT pointer position, so move there
+			// first to honour the (x, y) the caller named (the two halves of a manual
+			// drag both land at the intended spot).
+			await page.mouse.move(input.x, input.y);
+			await page.mouse.down({button});
+			return;
+		case 'up':
+			await page.mouse.move(input.x, input.y);
+			await page.mouse.up({button});
+			return;
+	}
+}
+
+/**
+ * Run the `screenshot` verb (prd `broaden-agent-verb-surface`, Tier-4, R3;
+ * stories 17-19) against a Playwright page: capture the requested SCOPE to a PNG
+ * FILE under the managed `screenshotsDir` and return `{path, width, height}` —
+ * NEVER image bytes (the load-bearing ADR-0003-as-amended choice). Shared by
+ * both transports (via the coordinate hand).
+ *
+ * Scopes:
+ * - `viewport` (default) — the visible viewport, COORDINATE-MATCHED to `mouse`.
+ * - `full` — the whole scrollable page (`fullPage: true`), NOT coordinate-matched.
+ * - `element` — clipped to the locator's element (REQUIRED; resolved through the
+ *   SAME {@link resolveLocator}, so a `frameLocator(...)` frame widget works even
+ *   cross-origin). A missing locator for `element`, or a stray locator on a
+ *   non-`element` scope, is a LOUD validation error (mirrors `wait`).
+ *
+ * The PNG is written by Playwright to a path webhands MINTS under the managed
+ * dir (or a caller `out` override VALIDATED to stay under it, else
+ * {@link ScreenshotPathError}). We read the PNG's IHDR for the real pixel
+ * dimensions (so the number is the image's, not an assumed viewport size).
+ */
+export async function takeScreenshot(
+	page: Page,
+	screenshotsDir: string,
+	options?: ScreenshotOptions,
+): Promise<Screenshot> {
+	const scope = options?.scope ?? 'viewport';
+	// LOUD scope/locator validation (mirrors `wait`'s exactly-one-of): `element`
+	// MUST carry a locator; the other scopes must NOT (a stray locator is a
+	// caller mistake, not a silent no-op).
+	if (scope === 'element' && options?.locator === undefined) {
+		throw new Error(
+			'screenshot --scope element requires --locator <expr> (the element to clip to).',
+		);
+	}
+	if (scope !== 'element' && options?.locator !== undefined) {
+		throw new Error(
+			`screenshot --locator is only valid with --scope element (got scope ${JSON.stringify(
+				scope,
+			)}).`,
+		);
+	}
+
+	const path = await resolveScreenshotPath(screenshotsDir, options?.out);
+	await mkdir(screenshotsDir, {recursive: true});
+
+	let buffer: Buffer;
+	if (scope === 'element') {
+		// Clip to just the element (the captcha widget). Resolve through the ONE
+		// shared resolver so a `frameLocator(...)` hop reaches a frame widget,
+		// including cross-origin (Playwright `frameLocator` crosses; the spike).
+		buffer = await resolveLocator(page, options!.locator!)
+			.first()
+			.screenshot({path, type: 'png'});
+	} else {
+		buffer = await page.screenshot({
+			path,
+			type: 'png',
+			fullPage: scope === 'full',
+		});
+	}
+
+	const {width, height} = pngDimensions(buffer, path);
+	return {path, width, height};
+}
+
+/**
+ * The PNG magic + IHDR layout: an 8-byte signature, then the IHDR chunk whose
+ * width/height are big-endian uint32s at byte offsets 16 and 20. Reading them is
+ * how we report the image's REAL pixel dimensions without decoding the whole
+ * PNG or assuming a viewport size.
+ */
+function pngDimensions(
+	buffer: Buffer,
+	path: string,
+): {width: number; height: number} {
+	const PNG_SIGNATURE = '89504e470d0a1a0a';
+	if (
+		buffer.length < 24 ||
+		buffer.subarray(0, 8).toString('hex') !== PNG_SIGNATURE
+	) {
+		throw new Error(
+			`screenshot: the file written at ${path} is not a valid PNG (no PNG signature).`,
+		);
+	}
+	return {
+		width: buffer.readUInt32BE(16),
+		height: buffer.readUInt32BE(20),
+	};
+}
+
+/**
+ * Resolve the PNG output path: a caller `out` override (VALIDATED to stay under
+ * the managed dir) or a freshly MINTED unique path under it. A relative `out` is
+ * resolved against the managed dir; an absolute (or `..`-escaping) `out` that
+ * lands outside it is refused with {@link ScreenshotPathError} — webhands never
+ * writes a screenshot to an arbitrary location.
+ */
+async function resolveScreenshotPath(
+	screenshotsDir: string,
+	out?: string,
+): Promise<string> {
+	if (out === undefined || out === '') {
+		return join(screenshotsDir, mintScreenshotName());
+	}
+	const managedRoot = resolvePath(screenshotsDir);
+	const candidate = isAbsolute(out)
+		? resolvePath(out)
+		: resolvePath(managedRoot, out);
+	const rel = relative(managedRoot, candidate);
+	// `rel` starting with `..` (or being absolute on a different root) means the
+	// candidate escapes the managed dir.
+	if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+		throw new ScreenshotPathError(out, managedRoot);
+	}
+	return candidate;
+}
+
+/**
+ * Mint a unique PNG filename: a timestamp plus random suffix, so concurrent /
+ * rapid shots never collide and the name is sortable by capture time.
+ */
+function mintScreenshotName(): string {
+	const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+	const rand = Math.random().toString(36).slice(2, 10);
+	return `webhands-${stamp}-${rand}.png`;
+}
+
 /** Map a Playwright cookie to the transport-neutral seam {@link Cookie}. */
 function toSeamCookie(c: {
 	name: string;