@webhands/core 0.5.0 → 0.6.0

package/dist/hand-host.js

@@ -1,4 +1,8 @@
-import { errors as pwErrors } from 'playwright';
+import { errors as pwErrors, } from 'playwright';
+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';
 /**
  * Compose a set of hands over one live {@link HandContext} into a single
  * {@link WebHandsPage}. This is the host primitive both Playwright transports call to
@@ -54,6 +58,18 @@ const REQUIRED_VERBS = [
     'wait',
     'cookies',
     'setCookies',
+    'query',
+    'count',
+    'exists',
+    'isVisible',
+    'getAttribute',
+    'press',
+    'hover',
+    'select',
+    'scroll',
+    'drag',
+    'mouse',
+    'screenshot',
 ];
 /**
  * Assert the composed verbs cover the whole seam {@link WebHandsPage}, then return it
@@ -79,6 +95,16 @@ function assertCompletePage(verbs) {
  * (animations, late layout) before deciding to dispatch.
  */
 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.
 //
@@ -110,6 +136,10 @@ export const snapshotHand = ({ pwPage, ensureOpen }) => ({
     verbs: {
         async snapshot(options) {
             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
@@ -130,15 +160,29 @@ export const snapshotHand = ({ 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 = ({ pwPage, ensureOpen }) => ({
     verbs: {
-        async click(t) {
+        async click(t, options) {
             ensureOpen();
+            if (options?.byRef === true) {
+                await assertRefResolvesToOne(pwPage, t, 'click');
+            }
             await clickLocator(pwPage, t);
         },
-        async type(t, text) {
+        async type(t, text, options) {
             ensureOpen();
+            if (options?.byRef === true) {
+                await assertRefResolvesToOne(pwPage, t, 'type');
+            }
             await resolveLocator(pwPage, t).fill(text);
         },
     },
@@ -146,22 +190,9 @@ export const interactionHand = ({ pwPage, ensureOpen }) => ({
 /** The `eval` escape hatch: run a JS EXPRESSION in the page, return by value. */
 export const evalHand = ({ pwPage, ensureOpen }) => ({
     verbs: {
-        async eval(expression) {
+        async eval(expression, options) {
             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);
         },
     },
 });
@@ -193,7 +224,141 @@ export const cookiesHand = ({ 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 = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async query(target, options) {
+            ensureOpen();
+            return queryRows(pwPage, target, options);
+        },
+        async count(target) {
+            ensureOpen();
+            return resolveLocator(pwPage, target).count();
+        },
+        async exists(target) {
+            ensureOpen();
+            return (await resolveLocator(pwPage, target).count()) > 0;
+        },
+        async isVisible(target) {
+            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) {
+            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 = ({ pwPage, ensureOpen }) => ({
+    verbs: {
+        async press(key, target) {
+            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) {
+            ensureOpen();
+            await resolveLocator(pwPage, target).hover();
+        },
+        async select(target, choice) {
+            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) {
+            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) {
+            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 = ({ pwPage, ensureOpen, screenshotsDir }) => ({
+    verbs: {
+        async mouse(input) {
+            ensureOpen();
+            await doMouse(pwPage, input);
+        },
+        async screenshot(options) {
+            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).
@@ -205,6 +370,9 @@ export const BUILT_IN_HANDS = [
     evalHand,
     waitHand,
     cookiesHand,
+    queryHand,
+    inputHand,
+    coordinateHand,
 ];
 /**
  * Compose webhands' built-in hands over a live context into the seam's
@@ -272,6 +440,122 @@ export async function waitFor(page, condition) {
             return;
     }
 }
+/**
+ * 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, expression, options) {
+    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, selector) {
+    // 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)})`);
+    // 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;
+    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) {
+    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
@@ -307,11 +591,24 @@ export function resolveLocator(page, expression) {
  * 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, expression) {
     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)) {
@@ -322,6 +619,352 @@ export async function clickLocator(page, expression) {
         await target.dispatchEvent('click', { timeout: NORMAL_CLICK_TIMEOUT_MS });
     }
 }
+/**
+ * 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, expression, options) {
+    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 = [];
+    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) {
+    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) {
+    const css = await cell.evaluate((el, attr) => {
+        const cssEscape = (v) => typeof window.CSS
+            ?.escape === 'function'
+            ? window.CSS.escape(v)
+            : v.replace(/[^a-zA-Z0-9_-]/g, (c) => '\\' + c);
+        const uniq = (selector) => 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;
+        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, ref, verb) {
+    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, attrs, props, pw, withRef) {
+    const row = {};
+    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, { attrNames, propNames, }) => {
+            const out = {};
+            if (attrNames.length > 0) {
+                const a = {};
+                for (const name of attrNames) {
+                    a[name] = el.getAttribute(name);
+                }
+                out.attrs = a;
+            }
+            if (propNames.length > 0) {
+                const p = {};
+                for (const name of propNames) {
+                    p[name] = el[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 = {};
+        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, input) {
+    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, screenshotsDir, options) {
+    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;
+    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, path) {
+    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, out) {
+    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() {
+    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) {
     return {