@webhands/core 0.5.0 → 0.6.0

package/dist/seam.d.ts

@@ -65,6 +65,36 @@ export interface Cookie {
     readonly secure?: boolean;
     readonly sameSite?: 'Strict' | 'Lax' | 'None';
 }
+/**
+ * Options for the {@link WebHandsPage.eval} verb.
+ *
+ * This is an OPTIONS OBJECT, not a positional argument, on purpose (R1, the
+ * reversibility invariant): the optional `frame` qualifier is an ADDITION to
+ * this object, so a call passing no options keeps `eval`'s today behaviour
+ * unchanged. `eval` is the ONE verb that carries a `frame?` qualifier, because
+ * it runs page-world JS and CANNOT carry a `frameLocator(...)` expression the
+ * way the locator-taking verbs do (the spike confirmed `ReferenceError`); the
+ * other verbs reach a same-origin frame through a `frameLocator(...)` hop in
+ * their locator string instead (R1).
+ */
+export interface EvalOptions {
+    /**
+     * A transport-neutral SELECTOR for a SAME-ORIGIN child frame to evaluate the
+     * expression in — a CSS selector for the `<iframe>` element (e.g.
+     * `#main-iframe`), the form the single frame resolver understands. NEVER a
+     * Playwright `Frame` handle (no Playwright type crosses the seam, ADR-0003).
+     *
+     * Omitted == today's top-document `eval` (backward compatible). When given,
+     * the expression runs in the named frame and its result crosses the seam by
+     * the SAME structured-clone contract `eval` already has.
+     *
+     * SAME-ORIGIN ONLY: a cross-origin frame is a browser security boundary
+     * page-world JS cannot cross, so a selector that resolves to a CROSS-ORIGIN
+     * frame fails LOUD with a typed error (never a silent empty); cross-origin
+     * reach is the separate Tier-4 frameLocator/coordinate surface.
+     */
+    readonly frame?: string;
+}
 /** What to wait for in the {@link WebHandsPage.wait} verb. */
 export type WaitCondition = {
     readonly kind: 'timeout';
@@ -75,6 +105,153 @@ export type WaitCondition = {
 } | {
     readonly kind: 'navigation';
 };
+/**
+ * Which native `<select>` option the {@link WebHandsPage.select} verb chooses
+ * (prd `broaden-agent-verb-surface`, Tier-2). EXACTLY ONE of `value` / `label`,
+ * a discriminated union so the mutual exclusion is impossible to violate at the
+ * seam (the CLI mirrors it with `wait`-style loud validation, R5):
+ *
+ * - `value` — match the option's `value` attribute (`<option value="v">`).
+ * - `label` — match the option's VISIBLE label (its text), what a human reads.
+ *
+ * Plain strings only, so nothing Playwright-shaped crosses the seam (ADR-0003).
+ */
+export type SelectChoice = {
+    readonly value: string;
+} | {
+    readonly label: string;
+};
+/**
+ * Where the {@link WebHandsPage.scroll} verb scrolls (prd
+ * `broaden-agent-verb-surface`, Tier-2). EXACTLY ONE of `to` / `by`, a
+ * discriminated union mirroring `wait`'s mutually-exclusive forms:
+ *
+ * - `to` — bring the element a locator EXPRESSION addresses into view
+ *   (`scrollIntoViewIfNeeded`); reach an off-viewport control.
+ * - `by` — scroll the page by a pixel delta (`mouse.wheel`), `dx`/`dy` in
+ *   CSS pixels (positive `dy` scrolls DOWN, the wheel convention).
+ *
+ * `to` carries a {@link LocatorString}; `by` carries plain numbers — no
+ * Playwright type crosses the seam (ADR-0003).
+ */
+export type ScrollTarget = {
+    readonly to: LocatorString;
+} | {
+    readonly by: {
+        readonly dx: number;
+        readonly dy: number;
+    };
+};
+/**
+ * Which mouse button the {@link WebHandsPage.mouse} verb uses (prd
+ * `broaden-agent-verb-surface`, Tier-4, R3; story 17). Plain string enum, the
+ * Playwright `page.mouse` button vocabulary, so nothing Playwright-shaped
+ * crosses the seam (ADR-0003 as amended by the Tier-4 ADR).
+ */
+export type MouseButton = 'left' | 'right' | 'middle';
+/**
+ * What the {@link WebHandsPage.mouse} verb does at the given coordinate (prd
+ * `broaden-agent-verb-surface`, Tier-4, R3):
+ *
+ * - `'click'` — a full press-and-release at `(x, y)` (`mouse.click`).
+ * - `'move'` — move the pointer to `(x, y)` without pressing (`mouse.move`),
+ *   e.g. to trigger a hover affordance at a raw coordinate.
+ * - `'down'` / `'up'` — press / release the button at the current position
+ *   (`mouse.down` / `mouse.up`), the two halves of a manual drag.
+ */
+export type MouseAction = 'click' | 'move' | 'down' | 'up';
+/**
+ * A coordinate mouse input (prd `broaden-agent-verb-surface`, Tier-4, R3, story
+ * 17). The coordinate-input counterpart to the locator-addressing `click`, for
+ * the VISION/TILE captcha family and any task that must act at a raw pixel an
+ * agent SAW in a screenshot rather than at a DOM element.
+ *
+ * COORDINATE FRAME (load-bearing). `x`/`y` are VIEWPORT CSS-pixels (the
+ * Playwright `page.mouse` frame), NOT OS-level screen coordinates (webhands
+ * never injects OS input). A pixel `(x, y)` in a VIEWPORT {@link Screenshot}
+ * maps DIRECTLY to a `mouse` click `(x, y)` — that is the look-then-click
+ * contract the agent relies on. A FULL-PAGE screenshot is NOT coordinate-matched
+ * (it includes off-viewport content), so its pixels do not map to `mouse`
+ * coordinates (see {@link ScreenshotScope}).
+ *
+ * Plain numbers + a string enum only, so nothing Playwright-shaped crosses the
+ * seam (ADR-0003 as amended by the Tier-4 ADR).
+ */
+export interface MouseInput {
+    /** What to do at the coordinate (click / move / down / up). */
+    readonly action: MouseAction;
+    /** Viewport CSS-pixel X (left-relative), the `page.mouse` frame. */
+    readonly x: number;
+    /** Viewport CSS-pixel Y (top-relative), the `page.mouse` frame. */
+    readonly y: number;
+    /** Which button for `click`/`down`/`up`. Defaults to `'left'`. */
+    readonly button?: MouseButton;
+}
+/**
+ * Which region a {@link WebHandsPage.screenshot} captures (prd
+ * `broaden-agent-verb-surface`, Tier-4, R3; stories 17-19):
+ *
+ * - `'viewport'` — the DEFAULT: exactly the visible viewport. Its pixels are
+ *   COORDINATE-MATCHED to the `mouse` verb (a pixel at `(x, y)` is the `mouse`
+ *   click `(x, y)`), so it is the shot the look-then-click loop uses.
+ * - `'full'` — the whole scrollable page (`fullPage`), for READING scrolled-out
+ *   content. It is NOT coordinate-matched (it includes off-viewport content), so
+ *   its pixels must NOT be fed back as `mouse` coordinates.
+ * - `'element'` — clipped to the element a locator addresses (just the captcha
+ *   widget, ideal for focusing a vision model). REQUIRES a
+ *   {@link ScreenshotOptions.locator}; absent, the verb rejects LOUD (like
+ *   `wait`'s mutually-exclusive validation).
+ */
+export type ScreenshotScope = 'viewport' | 'full' | 'element';
+/**
+ * Options for the {@link WebHandsPage.screenshot} verb (prd
+ * `broaden-agent-verb-surface`, Tier-4, R3; R5). An OPTIONS OBJECT so future
+ * fields stay additive (R1).
+ *
+ * The seam stays ADR-0003-clean (as amended by the Tier-4 ADR): the verb takes
+ * STRINGS + an enum and returns a file PATH — NEVER image bytes.
+ */
+export interface ScreenshotOptions {
+    /**
+     * Which region to capture. Defaults to `'viewport'` (the coordinate-matched
+     * shot the `mouse` loop uses). See {@link ScreenshotScope}.
+     */
+    readonly scope?: ScreenshotScope;
+    /**
+     * The element to clip to for `scope: 'element'`, a raw Playwright locator
+     * EXPRESSION resolved through the SAME resolver the other verbs use (so a
+     * `frameLocator(...)` hop reaches a frame widget). REQUIRED for `'element'`
+     * and rejected (loud, like `wait`) for the other scopes.
+     */
+    readonly locator?: LocatorString;
+    /**
+     * Caller override for the output PNG path. When omitted, webhands MINTS a
+     * unique path under its managed screenshots dir. When given, it is VALIDATED
+     * to stay UNDER that managed dir (a path that escapes it is rejected with a
+     * typed error), so the verb never writes to an arbitrary filesystem location.
+     * A plain string — no bytes cross the seam.
+     */
+    readonly out?: string;
+}
+/**
+ * The result of a {@link WebHandsPage.screenshot}: the file PATH webhands wrote
+ * the PNG to, plus its pixel dimensions (prd `broaden-agent-verb-surface`,
+ * Tier-4, R3, story 19).
+ *
+ * `path` is a plain STRING — the load-bearing ADR-0003 (as amended) choice: a
+ * path, not image bytes, crosses the seam, so the seam stays string/number-typed
+ * and the agent reads/attaches the file itself. `width`/`height` are the PNG's
+ * pixel dimensions, so an agent knows the coordinate space of a VIEWPORT shot
+ * before it maps a pixel to a `mouse` click.
+ */
+export interface Screenshot {
+    /** The filesystem PATH of the written PNG (a string; never bytes). */
+    readonly path: string;
+    /** The PNG's pixel width. */
+    readonly width: number;
+    /** The PNG's pixel height. */
+    readonly height: number;
+}
 /**
  * Which page view a {@link Snapshot} carries.
  *
@@ -87,7 +264,16 @@ export type WaitCondition = {
  *   `needsAnswers` Q3): default is the accessibility view, `--full` is raw DOM.
  */
 export type SnapshotView = 'accessibility' | 'full';
-/** Options for the {@link WebHandsPage.snapshot} verb. */
+/**
+ * Options for the {@link WebHandsPage.snapshot} verb.
+ *
+ * `full` is the ONLY recognised key. Unknown keys are REJECTED (not silently
+ * ignored) by {@link validateSnapshotOptions}, which every entry point calls:
+ * passing `{view: 'full'}` (a natural mistake, because the RESULT carries a
+ * {@link SnapshotView} `view` field) throws a clear error instead of silently
+ * returning the wrong view. There is no `view` option; `view` is a RESULT
+ * field, set by the verb from `full`.
+ */
 export interface SnapshotOptions {
     /**
      * When `true`, return the raw DOM (`view: 'full'`) instead of the default
@@ -95,6 +281,21 @@ export interface SnapshotOptions {
      */
     readonly full?: boolean;
 }
+/**
+ * Validate a {@link SnapshotOptions} value at a verb entry point, the SINGLE
+ * source of truth shared by the in-process host and the RPC server dispatch so
+ * neither path can silently drop a misspelled option.
+ *
+ * Accepts `undefined`, `{}`, and `{full: boolean}`. REJECTS any object carrying
+ * a key other than `full`, and a non-boolean `full`, by throwing a clear `Error`
+ * that names the offending key and hints the right one (e.g. `{view: 'full'}`
+ * throws `snapshot: unknown option "view" (did you mean { full: true }?)`).
+ *
+ * This turns a silent wrong-result into a loud error: it does not change
+ * behaviour for any valid input. Returns the validated options unchanged so it
+ * can wrap a call site inline.
+ */
+export declare function validateSnapshotOptions(options?: SnapshotOptions): SnapshotOptions | undefined;
 /**
  * A structured, token-cheap view of the current page with stable element refs.
  *
@@ -120,6 +321,152 @@ export interface Snapshot {
     /** Human/agent-readable structured page content (see {@link Snapshot}). */
     readonly content: string;
 }
+/**
+ * The Playwright-locator-derived extras a {@link QueryRow} can carry under
+ * `pw`. This is the ONLY fixed (closed) set in {@link QueryOptions}: these two
+ * facts are NOT expressible as a DOM attribute or a live JS property, so they
+ * cannot ride in `attrs`/`props` (which are caller-named and open). Everything
+ * else the agent wants is named freely as an attribute or a property (R2, no
+ * curated DOM field set).
+ *
+ * - `'visible'` — actionability-grade visibility (`locator.isVisible()`),
+ *   strictly better than the `offsetParent` hack: a present-but-hidden element
+ *   reads `false`.
+ * - `'bbox'` — the element's bounding box (`locator.boundingBox()`) in VIEWPORT
+ *   CSS-pixels, the coordinate frame the future Tier-4 `mouse` verb uses.
+ */
+export type PwExtra = 'visible' | 'bbox';
+/**
+ * An element's bounding box in VIEWPORT CSS-pixels, the value of a
+ * {@link QueryRow}'s `pw.bbox`. Plain numbers only, so nothing Playwright-typed
+ * crosses the seam (ADR-0003). `null` when the element has no box (e.g. it is
+ * not rendered), mirroring `locator.boundingBox()`.
+ */
+export interface BoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Options for the {@link WebHandsPage.query} verb (R2).
+ *
+ * This is an OPTIONS OBJECT, not positional fields, on purpose (R1, the
+ * reversibility invariant a reviewer checks): a future optional `frame?`
+ * qualifier AND the T1b `ref` field are then PURE ADDITIONS to this object,
+ * breaking no existing call. Do NOT turn these into positional arguments.
+ *
+ * There is NO curated DOM field set: a row carries EXACTLY what the caller
+ * names here and nothing else. `attrs` and `props` are caller-named and OPEN
+ * (the agent already knows DOM/Playwright vocabulary); `pw` is the one closed
+ * set ({@link PwExtra}).
+ *
+ * `refs` is the OPT-IN durable-handle switch (R4): default `query` is a PURE
+ * READ that mints nothing and returns no `ref`; `refs: true` adds a `ref` to
+ * each row (see {@link QueryRow.ref}). It is a dedicated boolean, NOT a member
+ * of `pw`, because a `ref` is not a Playwright-locator-derived FACT about the
+ * element (the closed `pw` set) — it is an ADDRESS the agent acts on later. The
+ * CLI exposes it as `--with-refs`.
+ *
+ * The `attrs` vs `props` split is deliberate and LOUD — webhands NEVER
+ * auto-detects which of the two a name like `value`/`checked` means, because a
+ * silent attribute-vs-property guess is the footgun this repo's "loud over
+ * silent" style rejects.
+ */
+export interface QueryOptions {
+    /**
+     * DOM ATTRIBUTES to read by name, via `getAttribute(name)` — what is written
+     * in the markup (`href`, `data-sitekey`, `type`). A missing attribute reads
+     * `null`.
+     */
+    readonly attrs?: readonly string[];
+    /**
+     * Live JS PROPERTIES to read by name, via `el[name]` — runtime state
+     * (`innerText`, `value`, `checked`, `selectedIndex`). `text` is just
+     * `props: ['innerText']`; there is no special `text` field.
+     */
+    readonly props?: readonly string[];
+    /**
+     * Playwright-locator-derived extras to include (the ONLY closed set; see
+     * {@link PwExtra}).
+     */
+    readonly pw?: readonly PwExtra[];
+    /** Bound the number of rows returned (token economy on a multi-match). */
+    readonly limit?: number;
+    /**
+     * Opt-in to a durable element {@link QueryRow.ref} per row (R4; finding
+     * `query-ref-mint-mechanism-attribute-beats-weakmap`). Default (omitted /
+     * `false`) keeps `query` a PURE READ: no `ref` field, and the page is NOT
+     * mutated. `true` computes a `ref` per matched element by the PREFERENCE
+     * LADDER — REUSE the element's own stable UNIQUE attribute when present
+     * (`id`/`data-testid`/…, ZERO DOM mutation), MINT a namespaced
+     * `data-webhands-ref` attribute ONLY as the fallback for an anonymous element.
+     *
+     * Mints are single-`query`-scoped: each `refs: true` query SWEEPS the prior
+     * query's mints first, so a ref can never match a stale element from two
+     * queries ago. An action verb resolves a `ref` with loud staleness detection
+     * (resolve-to-zero / resolve-to-many => {@link StaleRefError}); see
+     * {@link ActionOptions.byRef}.
+     */
+    readonly refs?: boolean;
+}
+/**
+ * One matched element's data, carrying EXACTLY the fields the caller named in
+ * {@link QueryOptions} and nothing else (R2). A sub-object is present ONLY when
+ * the caller asked for that family, and within it a key is present for every
+ * name requested:
+ *
+ * - `attrs[name]` is the `getAttribute(name)` value (`null` if absent).
+ * - `props[name]` is the live `el[name]` value, structurally cloned by VALUE
+ *   (the same contract as `eval`; ADR-0003: no Playwright/CDP type leaks).
+ * - `pw.visible` / `pw.bbox` are the requested {@link PwExtra} values.
+ *
+ * When `query` is called with NO fields, each row is an empty object `{}`: the
+ * caller asked for nothing, so the row carries nothing (R2, "a row carries
+ * EXACTLY what the caller asked for").
+ */
+export interface QueryRow {
+    readonly attrs?: Readonly<Record<string, string | null>>;
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly pw?: {
+        readonly visible?: boolean;
+        readonly bbox?: BoundingBox | null;
+    };
+    /**
+     * The element's durable HANDLE, present ONLY when the caller asked
+     * ({@link QueryOptions.refs}). It is a LOCATOR STRING the agent feeds back to
+     * an action verb (`click`/`type`) with `{byRef: true}` to act on THIS element
+     * later even after the list mutates — fixing the index-drift footgun where a
+     * positional `.nth(i)` silently clicks the wrong row.
+     *
+     * It is computed by the LADDER (R4): when the element has a stable UNIQUE
+     * attribute it IS that real locator (`#buy-charlie`, `[data-testid="x"]`),
+     * durable across framework reconciliation and ZERO DOM mutation; otherwise it
+     * is a minted `[data-webhands-ref="<id>"]` selector. Either way it is a plain
+     * STRING resolved through the ONE existing resolver — no new addressing engine,
+     * no Playwright type on the seam (ADR-0003/0004). It is a SHORT-LIVED handle:
+     * acting on it after a NODE-REPLACEMENT re-render or a navigation fails LOUD
+     * with {@link StaleRefError}, never a silent wrong-element action.
+     */
+    readonly ref?: string;
+}
+/**
+ * Options for an ACTION verb that may act on a durable {@link QueryRow.ref}
+ * instead of a raw locator (R4). An OPTIONS OBJECT so it is an ADDITIVE,
+ * non-breaking extension of `click`/`type` (R1): a today call passing no options
+ * is unchanged.
+ *
+ * `byRef: true` tells the verb its `target` is a `ref` from a prior
+ * `query({refs: true})`, so it must enforce the loud-stale contract: resolve the
+ * ref through the SAME single resolver, then assert it matches EXACTLY ONE
+ * element — resolve-to-zero (removed/replaced) OR resolve-to-many (a cloned
+ * subtree) BOTH reject with a typed {@link StaleRefError}, never a silent
+ * wrong-element action. Omitted / `false` keeps the verb's plain locator
+ * behaviour (auto-waiting, first-match), unchanged.
+ */
+export interface ActionOptions {
+    readonly byRef?: boolean;
+}
 /**
  * The page-level verb surface. One method per verb in the domain glossary.
  * All element addressing flows through {@link LocatorString}.
@@ -130,13 +477,31 @@ export interface WebHandsPage {
     /**
      * Return a structured, token-cheap view of the page. Defaults to the
      * accessibility-tree + visible-text view with stable refs; pass
-     * `{full: true}` to get the raw DOM instead (PRD story 7).
+     * `{full: true}` to get the raw DOM instead (PRD story 7). An unknown or
+     * misshapen option REJECTS (e.g. `{view: 'full'}`), it is never silently
+     * ignored (see {@link validateSnapshotOptions}).
      */
     snapshot(options?: SnapshotOptions): Promise<Snapshot>;
-    /** Click the element addressed by a raw Playwright locator string. */
-    click(target: LocatorString): Promise<void>;
-    /** Type text into the element addressed by a raw Playwright locator string. */
-    type(target: LocatorString, text: string): Promise<void>;
+    /**
+     * Click the element addressed by a raw Playwright locator string.
+     *
+     * With `{byRef: true}` the `target` is treated as a durable
+     * {@link QueryRow.ref} from a prior `query({refs: true})`: it is resolved
+     * through the SAME resolver but MUST match EXACTLY ONE element, else a typed
+     * {@link StaleRefError} (resolve-to-zero / resolve-to-many) — the loud-stale
+     * guarantee that makes a ref strictly safer than a positional `.nth(i)`. The
+     * options object is additive (R1); omitted keeps today's plain-locator click.
+     */
+    click(target: LocatorString, options?: ActionOptions): Promise<void>;
+    /**
+     * Type text into the element addressed by a raw Playwright locator string.
+     *
+     * With `{byRef: true}` the `target` is a durable {@link QueryRow.ref}, resolved
+     * with the same EXACTLY-ONE loud-stale contract as {@link WebHandsPage.click}
+     * (a typed {@link StaleRefError} on zero/many). The options object is additive
+     * (R1); omitted keeps today's plain-locator type.
+     */
+    type(target: LocatorString, text: string, options?: ActionOptions): Promise<void>;
     /**
      * Run a JavaScript EXPRESSION in the active page's context and return its
      * result, the `eval` escape hatch for cases no other verb covers (PRD story
@@ -177,14 +542,143 @@ export interface WebHandsPage {
      * narrow it. This is deliberately a thin passthrough to the transport's
      * serialize-and-return: `eval` does not re-encode or wrap the result, so an
      * agent gets exactly what the page produced.
+     *
+     * FRAME SCOPE ({@link EvalOptions.frame}). With no `frame` this is exactly
+     * the top-document `eval` above. With a `frame` selector the expression runs
+     * in that NAMED SAME-ORIGIN child frame instead (e.g. to fire a captcha
+     * `data-callback` or read a runtime-only value the top document cannot see),
+     * returning by the same structured clone. The frame resolves through the
+     * SAME single resolver `click`/`type` use (a `frameLocator(...)` over the
+     * selector; R1), so there is no parallel frame-addressing path. A selector
+     * that resolves to a CROSS-ORIGIN frame REJECTS with a typed
+     * cross-origin-frame error (page-world JS cannot cross a security boundary),
+     * never a silent empty result.
      */
-    eval(expression: string): Promise<unknown>;
+    eval(expression: string, options?: EvalOptions): Promise<unknown>;
     /** Pace actions by waiting for a condition. */
     wait(condition: WaitCondition): Promise<void>;
     /** Read the session's cookies. */
     cookies(): Promise<readonly Cookie[]>;
     /** Seed the session's cookies. */
     setCookies(cookies: readonly Cookie[]): Promise<void>;
+    /**
+     * Read STRUCTURED data out of the element(s) addressed by a raw Playwright
+     * locator string (ADR-0004; already frame-capable for same-origin frames via
+     * a `frameLocator(...)` expression). Returns ONE ROW PER MATCH, each carrying
+     * EXACTLY the fields named in {@link QueryOptions} — caller-named `attrs`
+     * (DOM attributes) and `props` (live JS properties), plus the closed `pw`
+     * extras (R2). This kills the `eval`-returns-a-JSON-string pattern.
+     *
+     * The options are an OPTIONS OBJECT so a future `frame?` field is a
+     * non-breaking addition (R1); the locator resolves through the SAME single
+     * resolver `click`/`type`/`wait` use — no parallel addressing scheme.
+     *
+     * With `{refs: true}` (OPT-IN) each row also carries a durable
+     * {@link QueryRow.ref} the agent feeds back to `click`/`type` (`{byRef: true}`)
+     * to act on THAT element after the page mutates, fixing the index-drift
+     * footgun. The default (no `refs`) is a PURE READ that mints nothing.
+     *
+     * Values cross by structured clone, the SAME contract as `eval` (ADR-0003: no
+     * Playwright/CDP types on the seam). With no fields requested, each row is an
+     * empty object.
+     */
+    query(target: LocatorString, options?: QueryOptions): Promise<QueryRow[]>;
+    /**
+     * The number of elements the locator matches (a property of the MATCH SET,
+     * not a row field). A thin shorthand over the same machinery as
+     * {@link WebHandsPage.query}.
+     */
+    count(target: LocatorString): Promise<number>;
+    /** Whether the locator matches at least one element (`count(target) > 0`). */
+    exists(target: LocatorString): Promise<boolean>;
+    /**
+     * The first match's actionability-grade visibility (its `pw:['visible']`): a
+     * present-but-hidden element reads `false`, and an ABSENT element reads
+     * `false` too (no match cannot be visible).
+     */
+    isVisible(target: LocatorString): Promise<boolean>;
+    /**
+     * The first match's `name` DOM attribute (its `attrs:[name]`), via
+     * `getAttribute`. `null` when the attribute is absent OR the locator matches
+     * no element — both "there is no such attribute value to read".
+     */
+    getAttribute(target: LocatorString, name: string): Promise<string | null>;
+    /**
+     * Press a keyboard key or chord (prd `broaden-agent-verb-surface`, Tier-2,
+     * story 8) — arrows, `Enter`, `Space`, a letter (`w`), or a chord like
+     * `Control+A`. The chord grammar is Playwright's `keyboard.press` grammar:
+     * `Modifier+Modifier+Key`, modifiers `Control`/`Alt`/`Shift`/`Meta`, key names
+     * like `ArrowLeft`/`Enter`/`a` (see the task's ## Decisions note). The key is a
+     * plain STRING, so nothing Playwright-shaped crosses the seam (ADR-0003).
+     *
+     * With `target`, the key is sent to the element that locator addresses (it is
+     * focused first, the `locator.press` semantics); WITHOUT it, the key is sent to
+     * the page's currently focused element (`keyboard.press`). `target` is an
+     * optional trailing arg so a future `frame?` stays additive (R1).
+     */
+    press(key: string, target?: LocatorString): Promise<void>;
+    /**
+     * Hover the pointer over the element a locator addresses (prd
+     * `broaden-agent-verb-surface`, Tier-2, story 9), to reveal a hover menu /
+     * on-hover control `click` cannot surface (`locator.hover`).
+     */
+    hover(target: LocatorString): Promise<void>;
+    /**
+     * Choose an option in the native `<select>` a locator addresses (prd
+     * `broaden-agent-verb-surface`, Tier-2, story 10), by `value` OR by `label`
+     * (EXACTLY ONE; see {@link SelectChoice}). Maps to Playwright
+     * `locator.selectOption`; the chosen option is reflected in the element's live
+     * state (its `value` / `selectedIndex`).
+     */
+    select(target: LocatorString, choice: SelectChoice): Promise<void>;
+    /**
+     * Scroll the page, either TO an element a locator addresses or BY a pixel
+     * delta (prd `broaden-agent-verb-surface`, Tier-2, story 11; EXACTLY ONE form,
+     * see {@link ScrollTarget}). `to` reaches lazy-loaded / off-viewport content
+     * (`scrollIntoViewIfNeeded`); `by` nudges the page a fixed amount
+     * (`mouse.wheel`).
+     */
+    scroll(target: ScrollTarget): Promise<void>;
+    /**
+     * Drag the element `source` addresses onto the element `target` addresses (prd
+     * `broaden-agent-verb-surface`, Tier-2, story 12), for drag-reorder UIs and
+     * drag-slider challenges (`locator.dragTo`). Both are raw locator EXPRESSIONS
+     * resolved through the SAME resolver as `click`/`type` (ADR-0004).
+     */
+    drag(source: LocatorString, target: LocatorString): Promise<void>;
+    /**
+     * Coordinate mouse input at VIEWPORT CSS-pixels (prd
+     * `broaden-agent-verb-surface`, Tier-4, R3, story 17): click / move / press /
+     * release at a raw `(x, y)` the agent SAW in a VIEWPORT {@link
+     * WebHandsPage.screenshot}, the input half of the look-then-click loop. This
+     * is the coordinate counterpart to the locator-addressing {@link
+     * WebHandsPage.click}, for the vision/tile captcha family and any pixel-level
+     * task. It uses Playwright `page.mouse` semantics (viewport-relative CSS
+     * pixels), NOT OS-level screen input — see {@link MouseInput}.
+     *
+     * Plain numbers + a string enum cross the seam (ADR-0003 as amended by the
+     * Tier-4 ADR); no Playwright/CDP type leaks.
+     */
+    mouse(input: MouseInput): Promise<void>;
+    /**
+     * Capture the page to a PNG FILE and return its PATH (prd
+     * `broaden-agent-verb-surface`, Tier-4, R3; stories 17-19). webhands MINTS the
+     * PNG under its managed screenshots dir and returns `{path, width, height}`;
+     * NO image bytes cross the seam (the load-bearing ADR-0003-as-amended choice),
+     * so an agent reads / attaches the file by path.
+     *
+     * Three scopes ({@link ScreenshotScope}): `viewport` (default,
+     * COORDINATE-MATCHED to {@link WebHandsPage.mouse} — a pixel `(x, y)` here is
+     * the `mouse` click `(x, y)`), `full` (the whole scrollable page, for reading
+     * scrolled-out content, NOT coordinate-matched), and `element` (clipped to the
+     * element a locator addresses; the locator is REQUIRED and validated loud like
+     * `wait`).
+     *
+     * A caller MAY override the path ({@link ScreenshotOptions.out}); it is
+     * validated to stay UNDER the managed dir (an escaping path rejects with a
+     * typed error), so the verb never writes to an arbitrary location.
+     */
+    screenshot(options?: ScreenshotOptions): Promise<Screenshot>;
 }
 /**
  * A live browser session owning one active {@link WebHandsPage}. The session lifetime

package/dist/seam.d.ts.map

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

package/dist/seam.js

@@ -22,4 +22,35 @@
 export function locator(expression) {
     return expression;
 }
+/**
+ * Validate a {@link SnapshotOptions} value at a verb entry point, the SINGLE
+ * source of truth shared by the in-process host and the RPC server dispatch so
+ * neither path can silently drop a misspelled option.
+ *
+ * Accepts `undefined`, `{}`, and `{full: boolean}`. REJECTS any object carrying
+ * a key other than `full`, and a non-boolean `full`, by throwing a clear `Error`
+ * that names the offending key and hints the right one (e.g. `{view: 'full'}`
+ * throws `snapshot: unknown option "view" (did you mean { full: true }?)`).
+ *
+ * This turns a silent wrong-result into a loud error: it does not change
+ * behaviour for any valid input. Returns the validated options unchanged so it
+ * can wrap a call site inline.
+ */
+export function validateSnapshotOptions(options) {
+    if (options === undefined) {
+        return options;
+    }
+    if (typeof options !== 'object' || options === null) {
+        throw new Error(`snapshot: options must be an object like { full: true }, got ${typeof options}`);
+    }
+    const unknownKeys = Object.keys(options).filter((key) => key !== 'full');
+    if (unknownKeys.length > 0) {
+        const named = unknownKeys.map((key) => `"${key}"`).join(', ');
+        throw new Error(`snapshot: unknown option ${named} (did you mean { full: true }?)`);
+    }
+    if (options.full !== undefined && typeof options.full !== 'boolean') {
+        throw new Error(`snapshot: option "full" must be a boolean, got ${typeof options.full}`);
+    }
+    return options;
+}
 //# sourceMappingURL=seam.js.map

package/dist/seam.js.map

@@ -1 +1 @@
-{"version":3,"file":"seam.js","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,UAAkB;IACzC,OAAO,UAA2B,CAAC;AACpC,CAAC"}
+{"version":3,"file":"seam.js","sourceRoot":"","sources":["../src/seam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,sEAAsE;AACtE,MAAM,UAAU,OAAO,CAAC,UAAkB;IACzC,OAAO,UAA2B,CAAC;AACpC,CAAC;AA8PD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACtC,OAAyB;IAEzB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACd,gEAAgE,OAAO,OAAO,EAAE,CAChF,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC;IACzE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,IAAI,KAAK,CACd,4BAA4B,KAAK,iCAAiC,CAClE,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACd,kDAAkD,OAAO,OAAO,CAAC,IAAI,EAAE,CACvE,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC"}