@webhands/core 0.5.0 → 0.6.0

package/README.md

@@ -83,10 +83,26 @@ This is a **personal-use** tool. Its whole premise is that you drive a browser
 [`docs/adr/0002`](docs/adr/0002-real-session-over-fingerprint-spoofing.md)). It is
 deliberately local and single-session by design.
 
-- **No login-bypass, no CAPTCHA-solving.** The human does the one-time login and
-  clears any anti-bot challenge in the headed `setup-profile` step. This tool
-  does NOT bypass authentication or solve CAPTCHAs programmatically, and it is not
-  intended to.
+- **No login-bypass, no built-in CAPTCHA solver.** The human does the one-time
+  login and clears any anti-bot challenge in the headed `setup-profile` step.
+  webhands ships NO captcha solver and NO provider key, and does not bypass
+  authentication itself. What changed: the verb surface is now rich enough that it
+  no longer STANDS IN THE WAY of a capable agent that brings its OWN key. Such an
+  agent can get past a captcha by poking the page with verbs, both families: the
+  token-harvest family by reading the sitekey with a frame-aware `query`, `type`ing
+  a provider token into the response sink, and firing the callback; the vision/tile
+  family with the coordinate `mouse`, the element-clipped `screenshot`, and the
+  cross-origin frame read. We do not solve it; we no longer stand in the way. The
+  agent supplies its own key and its own logic (or uses a hand, below). webhands
+  is capable, not a solver.
+- **Hands are the simpler path (still).** A *hand* is a third-party capability
+  module (`iamhuman` today, a future buy-on-amazon hand) that closes over the live
+  page and makes the hard thing ONE call. A dumb agent plus a hand still gets there
+  in a single call, even though a capable agent can now do the same over several
+  verb turns. The two paths coexist: the verb surface is the floor that makes the
+  unaided path POSSIBLE; a hand is the ramp that makes it EASY. (A hand is a
+  trusted in-process peer, loaded only when you name it in `hands.json`; see
+  [`docs/adr/0007`](docs/adr/0007-public-hand-contract-and-explicit-declarative-loading.md).)
 - **No fingerprint-spoofing / anti-detect tricks.** It leans on being a *real*
   browser/profile/IP rather than spoofing. There is no proxy *rotation* or
   anti-detect build here. (A single, user-chosen SOCKS proxy for traffic/DNS

package/dist/errors.d.ts

@@ -15,7 +15,7 @@
  * has to re-derive paths.
  */
 /** The closed set of identifiable `core` error conditions. */
-export type ControllerErrorCode = 'missing-browser-binary' | 'missing-stealth-dependency' | 'invalid-proxy' | 'missing-profile' | 'attach-not-chromium' | 'attach-no-context' | 'no-live-server' | 'session-already-active';
+export type ControllerErrorCode = 'missing-browser-binary' | 'missing-stealth-dependency' | 'invalid-proxy' | 'missing-profile' | 'attach-not-chromium' | 'attach-no-context' | 'no-live-server' | 'session-already-active' | 'cross-origin-frame' | 'screenshot-path-outside-managed-dir' | 'stale-ref';
 /**
  * Base class for every identifiable `core` error. Branch on {@link code}.
  *
@@ -159,6 +159,97 @@ export declare class SessionAlreadyActiveError extends ControllerError {
         cause?: unknown;
     });
 }
+/**
+ * A frame-scoped `eval` (or any same-origin-frame op) addressed a CROSS-ORIGIN
+ * child frame. Page-world JS cannot cross a browser security boundary, so the
+ * frame-scoped `eval` reaches the top document and SAME-ORIGIN descendant frames
+ * ONLY (the idea's honest-scope note); a cross-origin frame is unreachable BY
+ * DESIGN, not a missing feature. We refuse LOUDLY with this typed condition
+ * rather than return a silent empty result, because a silent empty would let an
+ * agent believe its callback fired / its read succeeded when the security
+ * boundary actually blocked it.
+ *
+ * Cross-origin frame reach is the SEPARATE Tier-4 `frameLocator`/coordinate
+ * surface, not this verb; the message points there so the agent is not left
+ * guessing. Mirrors the other typed conditions: the CLI maps {@link code} to a
+ * message, and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export declare class CrossOriginFrameError extends ControllerError {
+    readonly code = "cross-origin-frame";
+    /** The frame selector the caller passed (echoed back so it is visible). */
+    readonly frame: string;
+    /** The cross-origin frame's origin, when known (e.g. `https://hcaptcha.com`). */
+    readonly frameOrigin?: string;
+    /** The page's own (main-frame) origin the frame had to match. */
+    readonly pageOrigin?: string;
+    constructor(frame: string, details?: {
+        frameOrigin?: string;
+        pageOrigin?: string;
+    }, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A `screenshot --out <path>` override pointed OUTSIDE the managed screenshots
+ * dir. webhands MINTS screenshots under one managed directory it owns (under the
+ * controller home root, beside `profiles/`); a caller MAY override the output
+ * path, but only WITHIN that managed dir (prd `broaden-agent-verb-surface`, R3:
+ * "validate it stays under a sane managed dir"). An override that escapes it
+ * (an absolute path elsewhere, or a `..` traversal out) is refused LOUDLY with
+ * this typed condition rather than silently writing a PNG to an arbitrary
+ * filesystem location — the seam returns a path, so an unbounded path would let
+ * the verb clobber any file the process can write.
+ *
+ * Mirrors the other typed conditions: the CLI maps {@link code} to a message,
+ * and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export declare class ScreenshotPathError extends ControllerError {
+    readonly code = "screenshot-path-outside-managed-dir";
+    /** The offending caller-supplied `out` path, echoed back so it is visible. */
+    readonly path: string;
+    /** The managed screenshots dir the path had to stay under. */
+    readonly managedDir: string;
+    constructor(path: string, managedDir: string, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A durable `query` `ref` (prd `broaden-agent-verb-surface`, R4; finding
+ * `query-ref-mint-mechanism-attribute-beats-weakmap`) failed to resolve to
+ * EXACTLY ONE element when an action verb (`click`/`type`) tried to act on it.
+ * A `ref` is a SHORT-LIVED handle, not a stable identity: between the `query`
+ * that minted it and the act, the page may have re-rendered (React keyed-list /
+ * Svelte `{#each}` NODE REPLACEMENT), navigated, or cloned a subtree carrying
+ * our minted attribute. Two stale shapes, BOTH this one error, never a silent
+ * wrong-element action:
+ *
+ * - resolve-to-ZERO ({@link matched} `=== 0`) — the element was removed or
+ *   replaced (its minted node is gone, or a reused stable attribute it carried
+ *   no longer exists). The agent must re-`query` against the fresh DOM.
+ * - resolve-to-MANY ({@link matched} `> 1`) — the ref matches more than one
+ *   element (a framework cloned a subtree carrying our minted attribute, or a
+ *   reused attribute turned out non-unique after a mutation). We refuse to
+ *   "pick the first", because that is exactly the silent wrong-element click the
+ *   ref exists to PREVENT.
+ *
+ * This is STRICTLY SAFER than re-addressing by a positional `.nth(i)`, which
+ * SILENTLY clicks whatever now sits at that index. The agent is told "re-query,
+ * the page changed" — its natural loop anyway. Mirrors the other typed
+ * conditions: the CLI maps {@link code} to a message, and
+ * {@link isControllerError} narrows it across a bundle boundary.
+ */
+export declare class StaleRefError extends ControllerError {
+    readonly code = "stale-ref";
+    /** The ref locator string that went stale (echoed back so it is visible). */
+    readonly ref: string;
+    /** How many elements the ref resolved to (0 = removed/replaced, >1 = ambiguous). */
+    readonly matched: number;
+    /** Which verb tried to act on the stale ref (e.g. `click`, `type`). */
+    readonly verb: string;
+    constructor(ref: string, matched: number, verb: string, message?: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Narrow an unknown caught value to a {@link ControllerError}. Prefer this over
  * `instanceof` at package boundaries: it checks the {@link ControllerError.isControllerError}

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/errors.js

@@ -165,6 +165,106 @@ export class SessionAlreadyActiveError extends ControllerError {
         super(message, options);
     }
 }
+/**
+ * A frame-scoped `eval` (or any same-origin-frame op) addressed a CROSS-ORIGIN
+ * child frame. Page-world JS cannot cross a browser security boundary, so the
+ * frame-scoped `eval` reaches the top document and SAME-ORIGIN descendant frames
+ * ONLY (the idea's honest-scope note); a cross-origin frame is unreachable BY
+ * DESIGN, not a missing feature. We refuse LOUDLY with this typed condition
+ * rather than return a silent empty result, because a silent empty would let an
+ * agent believe its callback fired / its read succeeded when the security
+ * boundary actually blocked it.
+ *
+ * Cross-origin frame reach is the SEPARATE Tier-4 `frameLocator`/coordinate
+ * surface, not this verb; the message points there so the agent is not left
+ * guessing. Mirrors the other typed conditions: the CLI maps {@link code} to a
+ * message, and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class CrossOriginFrameError extends ControllerError {
+    code = 'cross-origin-frame';
+    /** The frame selector the caller passed (echoed back so it is visible). */
+    frame;
+    /** The cross-origin frame's origin, when known (e.g. `https://hcaptcha.com`). */
+    frameOrigin;
+    /** The page's own (main-frame) origin the frame had to match. */
+    pageOrigin;
+    constructor(frame, details, message = `The frame ${JSON.stringify(frame)} is CROSS-ORIGIN${details?.frameOrigin !== undefined && details?.pageOrigin !== undefined
+        ? ` (frame origin ${details.frameOrigin}, page origin ${details.pageOrigin})`
+        : ''} and is unreachable from page-world JS. eval --frame reaches the top document and SAME-ORIGIN child frames only; a cross-origin frame is a browser security boundary. Reach cross-origin frames with the Tier-4 frameLocator/coordinate ops instead.`, options) {
+        super(message, options);
+        this.frame = frame;
+        this.frameOrigin = details?.frameOrigin;
+        this.pageOrigin = details?.pageOrigin;
+    }
+}
+/**
+ * A `screenshot --out <path>` override pointed OUTSIDE the managed screenshots
+ * dir. webhands MINTS screenshots under one managed directory it owns (under the
+ * controller home root, beside `profiles/`); a caller MAY override the output
+ * path, but only WITHIN that managed dir (prd `broaden-agent-verb-surface`, R3:
+ * "validate it stays under a sane managed dir"). An override that escapes it
+ * (an absolute path elsewhere, or a `..` traversal out) is refused LOUDLY with
+ * this typed condition rather than silently writing a PNG to an arbitrary
+ * filesystem location — the seam returns a path, so an unbounded path would let
+ * the verb clobber any file the process can write.
+ *
+ * Mirrors the other typed conditions: the CLI maps {@link code} to a message,
+ * and {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class ScreenshotPathError extends ControllerError {
+    code = 'screenshot-path-outside-managed-dir';
+    /** The offending caller-supplied `out` path, echoed back so it is visible. */
+    path;
+    /** The managed screenshots dir the path had to stay under. */
+    managedDir;
+    constructor(path, managedDir, message = `The screenshot output path ${JSON.stringify(path)} is OUTSIDE the managed screenshots dir (${managedDir}). A caller may override --out only within the managed dir; webhands never writes a screenshot to an arbitrary location.`, options) {
+        super(message, options);
+        this.path = path;
+        this.managedDir = managedDir;
+    }
+}
+/**
+ * A durable `query` `ref` (prd `broaden-agent-verb-surface`, R4; finding
+ * `query-ref-mint-mechanism-attribute-beats-weakmap`) failed to resolve to
+ * EXACTLY ONE element when an action verb (`click`/`type`) tried to act on it.
+ * A `ref` is a SHORT-LIVED handle, not a stable identity: between the `query`
+ * that minted it and the act, the page may have re-rendered (React keyed-list /
+ * Svelte `{#each}` NODE REPLACEMENT), navigated, or cloned a subtree carrying
+ * our minted attribute. Two stale shapes, BOTH this one error, never a silent
+ * wrong-element action:
+ *
+ * - resolve-to-ZERO ({@link matched} `=== 0`) — the element was removed or
+ *   replaced (its minted node is gone, or a reused stable attribute it carried
+ *   no longer exists). The agent must re-`query` against the fresh DOM.
+ * - resolve-to-MANY ({@link matched} `> 1`) — the ref matches more than one
+ *   element (a framework cloned a subtree carrying our minted attribute, or a
+ *   reused attribute turned out non-unique after a mutation). We refuse to
+ *   "pick the first", because that is exactly the silent wrong-element click the
+ *   ref exists to PREVENT.
+ *
+ * This is STRICTLY SAFER than re-addressing by a positional `.nth(i)`, which
+ * SILENTLY clicks whatever now sits at that index. The agent is told "re-query,
+ * the page changed" — its natural loop anyway. Mirrors the other typed
+ * conditions: the CLI maps {@link code} to a message, and
+ * {@link isControllerError} narrows it across a bundle boundary.
+ */
+export class StaleRefError extends ControllerError {
+    code = 'stale-ref';
+    /** The ref locator string that went stale (echoed back so it is visible). */
+    ref;
+    /** How many elements the ref resolved to (0 = removed/replaced, >1 = ambiguous). */
+    matched;
+    /** Which verb tried to act on the stale ref (e.g. `click`, `type`). */
+    verb;
+    constructor(ref, matched, verb, message = matched === 0
+        ? `${verb}: the ref ${JSON.stringify(ref)} is STALE — it now matches NO element (the page changed: the element was removed, replaced by a re-render, or the page navigated). Re-run query to get a fresh ref.`
+        : `${verb}: the ref ${JSON.stringify(ref)} is AMBIGUOUS — it now matches ${matched} elements (the page changed: a subtree was cloned, or the attribute is no longer unique). Refusing to act on a guessed element; re-run query to get a fresh ref.`, options) {
+        super(message, options);
+        this.ref = ref;
+        this.matched = matched;
+        this.verb = verb;
+    }
+}
 /**
  * Narrow an unknown caught value to a {@link ControllerError}. Prefer this over
  * `instanceof` at package boundaries: it checks the {@link ControllerError.isControllerError}

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/hand-host.d.ts

@@ -1,5 +1,5 @@
-import { type BrowserContext, type Page } from 'playwright';
-import type { WebHandsPage, WaitCondition } from './seam.js';
+import { type BrowserContext, type Frame, type Locator, type Page } from 'playwright';
+import type { EvalOptions, WebHandsPage, MouseInput, QueryOptions, QueryRow, Screenshot, ScreenshotOptions, WaitCondition } from './seam.js';
 /**
  * The hand-host primitive (Phase 1 of the "hands" prd,
  * `work/prds/tasked/hands-pluggable-page-capabilities.md`).
@@ -57,6 +57,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;
 }
 /**
  * What a hand contributes once given its {@link HandContext}: a set of named
@@ -117,7 +128,15 @@ export declare function composePage(ctx: HandContext, hands: readonly Hand[]): C
 export declare const navigationHand: Hand;
 /** The `snapshot` verb: the token-cheap a11y view, or `--full` raw DOM. */
 export declare const snapshotHand: Hand;
-/** 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 declare const interactionHand: Hand;
 /** The `eval` escape hatch: run a JS EXPRESSION in the page, return by value. */
 export declare const evalHand: Hand;
@@ -130,7 +149,57 @@ export declare const waitHand: Hand;
  */
 export declare const cookiesHand: Hand;
 /**
- * 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 declare const queryHand: Hand;
+/**
+ * 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 declare const inputHand: Hand;
+/**
+ * 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 declare const coordinateHand: Hand;
+/**
+ * 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).
@@ -181,6 +250,53 @@ export declare function composeWithHands(ctx: HandContext, extraHands: readonly
  * verb behaviour stays identical (no parallel second implementation).
  */
 export declare function waitFor(page: Page, condition: WaitCondition): Promise<void>;
+/**
+ * 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 declare function evalExpression(page: Page, expression: string, options?: EvalOptions): Promise<unknown>;
+/**
+ * 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 declare function resolveSameOriginFrame(page: Page, selector: string): Promise<Frame>;
 /**
  * Resolve a raw Playwright locator EXPRESSION (ADR-0004) against the page. The
  * verb surface passes locator expressions like `getByRole('button', …)`; we
@@ -191,7 +307,7 @@ export declare function waitFor(page: Page, condition: WaitCondition): Promise<v
  * One resolution path for both transports (via the built-in interaction/wait
  * hands), so there is no parallel addressing scheme.
  */
-export declare function resolveLocator(page: Page, expression: string): import("playwright").Locator;
+export declare function resolveLocator(page: Page, expression: string): Locator;
 /**
  * Run the `click` verb against a Playwright page (PRD story 8), shared by both
  * Playwright transports (via the built-in interaction hand) so the verb behaves
@@ -212,6 +328,83 @@ export declare function resolveLocator(page: Page, expression: string): import("
  * 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 declare function clickLocator(page: Page, expression: string): Promise<void>;
+/**
+ * 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 declare function queryRows(page: Page, expression: string, options?: QueryOptions): Promise<QueryRow[]>;
+/**
+ * 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 declare function assertRefResolvesToOne(page: Page, ref: string, verb: string): Promise<void>;
+/**
+ * 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 declare function doMouse(page: Page, input: MouseInput): Promise<void>;
+/**
+ * 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 declare function takeScreenshot(page: Page, screenshotsDir: string, options?: ScreenshotOptions): Promise<Screenshot>;
 //# sourceMappingURL=hand-host.d.ts.map

package/dist/hand-host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hand-host.d.ts","sourceRoot":"","sources":["../src/hand-host.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,IAAI,EAAC,MAAM,YAAY,CAAC;AAC9E,OAAO,KAAK,EAEX,YAAY,EAGZ,aAAa,EACb,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAC1B,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,SAAS,IAAI,EAAE,GACpB,aAAa,CAgCf;AAsDD,8EAA8E;AAC9E,eAAO,MAAM,cAAc,EAAE,IAe3B,CAAC;AAEH,2EAA2E;AAC3E,eAAO,MAAM,YAAY,EAAE,IAyBzB,CAAC;AAEH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,IAW5B,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,QAAQ,EAAE,IAoBrB,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,QAAQ,EAAE,IAOrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,IAYxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,IAAI,EAOzC,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,aAAa,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,WAAW,EAChB,UAAU,EAAE,SAAS,IAAI,EAAE,GACzB,aAAa,CAEf;AAOD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,OAAO,CAC5B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,gCAO5D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,YAAY,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAYf"}
+{"version":3,"file":"hand-host.d.ts","sourceRoot":"","sources":["../src/hand-host.ts"],"names":[],"mappings":"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"}