browxai 0.7.0

package/dist/page/snapshot-substrate-safari.js

@@ -0,0 +1,84 @@
+// SafariClassicSnapshotSubstrate — the SnapshotSubstrate implementation for the
+// real-Safari engine. Safari has neither CDP (the Chromium/Android
+// substrate) nor a Playwright Page/Frame (the firefox/webkit walker), so it gets
+// a THIRD substrate: the SAME page-side DOM-walk PAGE_SCRIPT, shipped through
+// WebDriver Classic `execute/sync` instead of CDP `Runtime.evaluate` or
+// Playwright `frame.evaluate`. The page-side DOM-walk script
+// returns the identical `DomWalkEntry` shape under
+// `execute/sync`, so this substrate mints the SAME content-hashed refs and emits
+// the SAME tree shape as PlaywrightSnapshotSubstrate — refs are stable across
+// substrates exactly like firefox/webkit.
+//
+// It depends only on a tiny IO seam (`SafariSnapshotIO`: run a script + read the
+// current URL), not on the safaridriver client directly, so the page layer stays
+// decoupled from the engine adapter (the adapter supplies a thin bridge).
+import { elementKey } from "./refs.js";
+import { runDomWalkViaExecute, mergeDomWalkIntoTree } from "./dom-walk.js";
+import { annotateStructuralContext } from "./structural.js";
+/** Safari substrate — the page-side DOM-walk over WebDriver Classic
+ *  `execute/sync`. No CDP, no Playwright Frame. Mirrors PlaywrightSnapshotSubstrate
+ *  (synthetic `WebArea` root + DOM-walk leaves), with the same documented
+ *  fidelity tradeoff: refs + find-ranking signal (role/name/[testid]) are present;
+ *  the deep CDP a11y nesting and closed-shadow piercing are not (no off-Chromium
+ *  protocol reaches them). */
+export class SafariClassicSnapshotSubstrate {
+    io;
+    engine = "safari";
+    constructor(io) {
+        this.io = io;
+    }
+    async compose(refs, testAttributes, opts = {}) {
+        const url = await this.io.currentUrl().catch(() => "");
+        const root = this.makeRoot(refs, url);
+        const entries = await runDomWalkViaExecute((script, args) => this.io.exec(script, args), {
+            testAttributes,
+            pierce: opts.pierce,
+        });
+        const merge = mergeDomWalkIntoTree(root, entries, refs);
+        annotateStructuralContext(root);
+        const warnings = [
+            `snapshot on the "safari" engine is DOM-walk-sourced over WebDriver Classic execute/sync ` +
+                `(Safari has no CDP accessibility tree and no Playwright frame). Refs are stable and the ` +
+                `find-ranking signal (role/name/[testid]) is present; the deep a11y structural nesting ` +
+                `chromium emits is not. [from-dom] markers reflect the source, not a deficiency.`,
+        ];
+        if (opts.pierce === "closed") {
+            warnings.push(`closed-shadow piercing is chromium-only (it needs CDP DOM.getDocument({pierce:true})); ` +
+                `safari has no protocol equivalent, so pierce: "closed" degraded to "open".`);
+        }
+        return {
+            tree: root,
+            stats: {
+                a11yInteractive: 0,
+                domWalkEntries: entries.length,
+                domWalkNew: merge.added,
+                domWalkCombined: merge.combined,
+                ...(opts.pierce === "closed" ? { closedShadowEntries: 0 } : {}),
+            },
+            warnings,
+        };
+    }
+    async a11yTree(refs, testAttributes) {
+        const url = await this.io.currentUrl().catch(() => "");
+        const root = this.makeRoot(refs, url);
+        const entries = await runDomWalkViaExecute((script, args) => this.io.exec(script, args), {
+            testAttributes,
+        });
+        mergeDomWalkIntoTree(root, entries, refs);
+        annotateStructuralContext(root);
+        return root;
+    }
+    /** The synthetic main-frame root — keyed/stable so its ref persists across
+     *  snapshots, identical to the Playwright substrate's root. */
+    makeRoot(refs, url) {
+        const rootKey = elementKey({ role: "WebArea", path: "__main__" });
+        const rootRef = refs.forKey(rootKey, { role: "WebArea", source: "dom" });
+        return {
+            ref: rootRef,
+            role: "WebArea",
+            name: url || "WebArea",
+            source: "dom",
+            children: [],
+        };
+    }
+}

package/dist/page/snapshot-substrate-select.d.ts

@@ -0,0 +1,24 @@
+import type { Page } from "playwright-core";
+import type { SafariSessionHandle } from "../engine/index.js";
+import { type SnapshotSubstrate } from "./snapshot-substrate.js";
+/** The minimal session shape this selector needs — the optional CDP accessor
+ *  (present only on chromium) + the engine tag + the page handle + the optional
+ *  Safari-native handle (present only on the `safari` engine, which has no
+ *  Playwright Page). The full BrowserSession satisfies it; the narrow shape keeps
+ *  the engine/session interfaces out of this page-layer module. */
+export interface SubstrateCapableSession {
+    readonly engine: string;
+    page(): Page;
+    cdp?(): import("playwright-core").CDPSession;
+    safari?(): SafariSessionHandle;
+}
+/** Build the SnapshotSubstrate for a session. Selection is by capability, never a
+ *  scattered engine-name check:
+ *   - Safari (no Playwright Page, no CDP) → the WebDriver-Classic DOM-walk
+ *     substrate, fed by the Safari handle's `execute/sync`.
+ *   - Chromium / Android (CDP present) → the byte-identical CDP substrate.
+ *   - Firefox / WebKit (Playwright Page, no CDP) → the page-side walker.
+ *  A future CDP-bearing engine routes to the CDP substrate automatically; a
+ *  non-CDP Playwright one to the walker — no edit here. Safari is the one engine
+ *  whose `page()` throws, so it MUST be handled before the Playwright branch. */
+export declare function snapshotSubstrateFor(session: SubstrateCapableSession): SnapshotSubstrate;

package/dist/page/snapshot-substrate-select.js

@@ -0,0 +1,34 @@
+// Substrate selection — maps a live session to its SnapshotSubstrate. This is
+// the seam where the engine's snapshot strategy is chosen: chromium (CDP) gets
+// the verbatim CDP substrate; an engine with no CDP escape hatch (firefox /
+// webkit) gets the page-side Playwright walker. The choice is the engine's,
+// declared by whether it exposes the raw-CDP handle — not an engine-name check
+// scattered through the tools.
+//
+// The session layer wires one substrate per entry at creation (server.ts) so the
+// per-call path is a captured-handle delegate with no per-call allocation (the
+// snapshot/find path is hot — architecture doctrine §3). Tools select via this
+// substrate, never via `requireCdp` + an engine branch.
+import { CdpSnapshotSubstrate, PlaywrightSnapshotSubstrate, } from "./snapshot-substrate.js";
+import { SafariClassicSnapshotSubstrate } from "./snapshot-substrate-safari.js";
+/** Build the SnapshotSubstrate for a session. Selection is by capability, never a
+ *  scattered engine-name check:
+ *   - Safari (no Playwright Page, no CDP) → the WebDriver-Classic DOM-walk
+ *     substrate, fed by the Safari handle's `execute/sync`.
+ *   - Chromium / Android (CDP present) → the byte-identical CDP substrate.
+ *   - Firefox / WebKit (Playwright Page, no CDP) → the page-side walker.
+ *  A future CDP-bearing engine routes to the CDP substrate automatically; a
+ *  non-CDP Playwright one to the walker — no edit here. Safari is the one engine
+ *  whose `page()` throws, so it MUST be handled before the Playwright branch. */
+export function snapshotSubstrateFor(session) {
+    if (session.engine === "safari" && session.safari) {
+        const handle = session.safari();
+        return new SafariClassicSnapshotSubstrate({
+            exec: (scriptBody, args) => handle.webDriver.executeScript(handle.sessionId, scriptBody, args),
+            currentUrl: () => handle.webDriver.currentUrl(handle.sessionId),
+        });
+    }
+    if (session.cdp)
+        return new CdpSnapshotSubstrate(session.cdp());
+    return new PlaywrightSnapshotSubstrate(session.page(), session.engine);
+}

package/dist/page/snapshot-substrate.d.ts

@@ -0,0 +1,58 @@
+import type { CDPSession, Page } from "playwright-core";
+import type { A11yNode } from "./a11y.js";
+import type { RefRegistry } from "./refs.js";
+import { type ComposedSnapshot, type ComposeOptions } from "./compose.js";
+/** The a11y+DOM tree source the snapshot/find tools mint refs from. One
+ *  instance wraps one session's engine handle; the methods carry no engine
+ *  type, so the tools above this seam are engine-agnostic. */
+export interface SnapshotSubstrate {
+    /** Engine tag — for diagnostics + the per-engine keystone matrix. */
+    readonly engine: string;
+    /** The composed snapshot (a11y tree + DOM-walk fallback merged) for the
+     *  main frame. The read core (snapshot/find/extract/text_search/set-of-marks)
+     *  consumes this. `opts.pierce` reaches the DOM-walk + (chromium only) the
+     *  closed-shadow CDP pass. */
+    compose(refs: RefRegistry, testAttributes: string[], opts?: ComposeOptions): Promise<ComposedSnapshot>;
+    /** The raw a11y tree only (no DOM-walk merge). The action window's pre/post
+     *  snapshotDelta and `watch`'s region sampling consume this — they need the
+     *  structural a11y tree, not the find-ranking-augmented composed tree. */
+    a11yTree(refs: RefRegistry, testAttributes: string[]): Promise<A11yNode | null>;
+}
+/** Chromium substrate — the existing CDP path, moved behind the interface
+ *  VERBATIM. `compose` / `a11yTree` delegate to the exact functions the tools
+ *  called inline before this seam (composeSnapshot / getA11yTree over the raw
+ *  CDPSession), so the output is byte-identical and the chromium keystones are
+ *  unchanged. The CDP handle is captured here once; callers never see it. */
+export declare class CdpSnapshotSubstrate implements SnapshotSubstrate {
+    private readonly cdp;
+    readonly engine = "chromium";
+    constructor(cdp: CDPSession);
+    compose(refs: RefRegistry, testAttributes: string[], opts?: ComposeOptions): Promise<ComposedSnapshot>;
+    a11yTree(refs: RefRegistry, testAttributes: string[]): Promise<A11yNode | null>;
+}
+/** Firefox / WebKit substrate — the page-side ARIA/DOM walker over
+ *  `frame.evaluate`. No CDP. It runs the SAME PAGE_SCRIPT as the (already
+ *  portable, OOPIF-safe) composeSnapshotForFrame, rooted at the main frame, and
+ *  mints refs through the SAME RefRegistry / elementKey path, so a ref minted
+ *  here is the same shape (and stable across snapshots) as a chromium DOM-walk
+ *  ref.
+ *
+ *  Tree shape: a synthetic `WebArea` root with the walker's interactive /
+ *  test-attribute-bearing elements as leaf children — identical to the
+ *  composeSnapshotForFrame shape. The CDP a11y tree's deep structural nesting is
+ *  not available off-Chromium (Firefox has no `Accessibility.getFullAXTree`),
+ *  but find()/text_search()/extract() walk the tree flat anyway, and the ref
+ *  inputs (role/name/testId/cssPath) — the find-ranking + ref-minting signal —
+ *  are all present. This is the documented, benchmarked fidelity tradeoff of
+ *  the hybrid approach: chromium keeps the deep AX tree; firefox gets the
+ *  walker-grade tree that carries the agentic signal. */
+export declare class PlaywrightSnapshotSubstrate implements SnapshotSubstrate {
+    private readonly page;
+    readonly engine: string;
+    constructor(page: Page, engine?: string);
+    compose(refs: RefRegistry, testAttributes: string[], opts?: ComposeOptions): Promise<ComposedSnapshot>;
+    a11yTree(refs: RefRegistry, testAttributes: string[]): Promise<A11yNode | null>;
+    /** The synthetic main-frame root. Keyed/stable so its ref persists across
+     *  snapshots exactly like the composeSnapshotForFrame root. */
+    private makeRoot;
+}

package/dist/page/snapshot-substrate.js

@@ -0,0 +1,135 @@
+// The SnapshotSubstrate interface — the engine-agnostic seam beneath the
+// snapshot / find / extract / text_search / set-of-marks / watch tools and the
+// pre/post ActionResult a11y deltas. It is the substrate side of the hybrid
+// snapshot/a11y design: the tools ask a substrate for "the a11y+DOM
+// tree to mint refs from"; an engine-specific implementation answers.
+//
+// Dependency direction (architecture doctrine §1): tools → SnapshotSubstrate
+// (this interface) → implementation → CDP / Playwright. A tool never reaches a
+// CDPSession or a raw Page through this seam; the engine handle is captured at
+// substrate construction, so the per-call surface carries no engine type. That
+// is what un-couples snapshot/find from CDP and lets them run on Firefox.
+//
+// Two implementations behind it (hybrid):
+//   - CdpSnapshotSubstrate (chromium): delegates to composeSnapshot /
+//     getA11yTree VERBATIM — the existing CDP `Accessibility.getFullAXTree` +
+//     `Runtime.evaluate` DOM-walk path, byte-identical output, so the 67+
+//     chromium keystones stay green unchanged.
+//   - PlaywrightSnapshotSubstrate (firefox / webkit): the page-side ARIA/DOM
+//     walker over `frame.evaluate` (main world) — the SAME PAGE_SCRIPT the
+//     already-portable composeSnapshotForFrame uses, generalized to the main
+//     frame. It mints the SAME content-hashed ref shape (role/name/testId/
+//     cssPath via elementKey), so refs are stable across substrates.
+//
+// Why the walker, not ariaSnapshot() (benchmarked):
+// `locator.ariaSnapshot()` carries NO test attributes (data-testid/…), so it
+// produces 0 testId-bearing nodes on a testid-tagged page — find() scores +5 on
+// a testId hit and elementKey hashes testId into the ref, so an ariaSnapshot
+// substrate degrades both ranking and ref stability. On the representative
+// fixture the walker hit 4/5 find targets vs ariaSnapshot's 0/5, carried testId
+// on 9 nodes vs 0, and ran ~10x faster (10 ms vs 104 ms). The walker also emits
+// exactly the DomWalkEntry shape the existing merge path already consumes, so
+// the firefox tree is byte-shape-identical to the chromium DOM-walk leaves.
+import { getA11yTree } from "./a11y.js";
+import { composeSnapshot } from "./compose.js";
+import { runDomWalkOnFrame, mergeDomWalkIntoTree } from "./dom-walk.js";
+import { annotateStructuralContext } from "./structural.js";
+import { elementKey } from "./refs.js";
+/** Chromium substrate — the existing CDP path, moved behind the interface
+ *  VERBATIM. `compose` / `a11yTree` delegate to the exact functions the tools
+ *  called inline before this seam (composeSnapshot / getA11yTree over the raw
+ *  CDPSession), so the output is byte-identical and the chromium keystones are
+ *  unchanged. The CDP handle is captured here once; callers never see it. */
+export class CdpSnapshotSubstrate {
+    cdp;
+    engine = "chromium";
+    constructor(cdp) {
+        this.cdp = cdp;
+    }
+    compose(refs, testAttributes, opts = {}) {
+        return composeSnapshot(this.cdp, refs, testAttributes, opts);
+    }
+    a11yTree(refs, testAttributes) {
+        return getA11yTree(this.cdp, refs, testAttributes);
+    }
+}
+/** Firefox / WebKit substrate — the page-side ARIA/DOM walker over
+ *  `frame.evaluate`. No CDP. It runs the SAME PAGE_SCRIPT as the (already
+ *  portable, OOPIF-safe) composeSnapshotForFrame, rooted at the main frame, and
+ *  mints refs through the SAME RefRegistry / elementKey path, so a ref minted
+ *  here is the same shape (and stable across snapshots) as a chromium DOM-walk
+ *  ref.
+ *
+ *  Tree shape: a synthetic `WebArea` root with the walker's interactive /
+ *  test-attribute-bearing elements as leaf children — identical to the
+ *  composeSnapshotForFrame shape. The CDP a11y tree's deep structural nesting is
+ *  not available off-Chromium (Firefox has no `Accessibility.getFullAXTree`),
+ *  but find()/text_search()/extract() walk the tree flat anyway, and the ref
+ *  inputs (role/name/testId/cssPath) — the find-ranking + ref-minting signal —
+ *  are all present. This is the documented, benchmarked fidelity tradeoff of
+ *  the hybrid approach: chromium keeps the deep AX tree; firefox gets the
+ *  walker-grade tree that carries the agentic signal. */
+export class PlaywrightSnapshotSubstrate {
+    page;
+    engine;
+    constructor(page, engine = "firefox") {
+        this.page = page;
+        this.engine = engine;
+    }
+    async compose(refs, testAttributes, opts = {}) {
+        const root = this.makeRoot(refs);
+        // The main frame's walk — same PAGE_SCRIPT, same `frame.evaluate` entry as
+        // the child-frame path. `pierce` recurses open shadow roots; closed-shadow
+        // CDP piercing is chromium-only (no off-Chromium protocol reaches closed
+        // roots), so we degrade to open and warn.
+        const entries = await runDomWalkOnFrame(this.page.mainFrame(), {
+            testAttributes,
+            pierce: opts.pierce,
+        });
+        const merge = mergeDomWalkIntoTree(root, entries, refs);
+        annotateStructuralContext(root);
+        const warnings = [
+            `snapshot on the "${this.engine}" engine is DOM-walk-sourced (no CDP accessibility tree off Chromium). ` +
+                `Refs are stable and find-ranking signal (role/name/[testid]) is present; the deep a11y structural ` +
+                `nesting chromium emits is not. [from-dom] markers reflect the source, not a deficiency.`,
+        ];
+        if (opts.pierce === "closed") {
+            warnings.push(`closed-shadow piercing is chromium-only (it needs CDP DOM.getDocument({pierce:true}), which ` +
+                `${this.engine} has no protocol equivalent for). pierce: "closed" degraded to "open".`);
+        }
+        return {
+            tree: root,
+            stats: {
+                a11yInteractive: 0,
+                domWalkEntries: entries.length,
+                domWalkNew: merge.added,
+                domWalkCombined: merge.combined,
+                ...(opts.pierce === "closed" ? { closedShadowEntries: 0 } : {}),
+            },
+            warnings,
+        };
+    }
+    async a11yTree(refs, testAttributes) {
+        // The pre/post action delta + watch sampling want the structural tree; off
+        // Chromium that is the same walker-sourced tree compose() builds (without
+        // the find-ranking warnings, which the delta path doesn't surface).
+        const root = this.makeRoot(refs);
+        const entries = await runDomWalkOnFrame(this.page.mainFrame(), { testAttributes });
+        mergeDomWalkIntoTree(root, entries, refs);
+        annotateStructuralContext(root);
+        return root;
+    }
+    /** The synthetic main-frame root. Keyed/stable so its ref persists across
+     *  snapshots exactly like the composeSnapshotForFrame root. */
+    makeRoot(refs) {
+        const rootKey = elementKey({ role: "WebArea", path: "__main__" });
+        const rootRef = refs.forKey(rootKey, { role: "WebArea", source: "dom" });
+        return {
+            ref: rootRef,
+            role: "WebArea",
+            name: this.page.url() || "WebArea",
+            source: "dom",
+            children: [],
+        };
+    }
+}

package/dist/page/snapshot.d.ts

@@ -0,0 +1,24 @@
+import { type A11yNode } from "./a11y.js";
+export interface SerialiseOptions {
+    /** Indent string per depth level. Default `"  "`. */
+    indent?: string;
+    /** Maximum characters of `name` to keep per node. Default 80. */
+    maxNameLen?: number;
+    /** If true, drop generic / presentational nodes that contribute nothing. */
+    pruneGeneric?: boolean;
+    /** cap on emitted lines. When exceeded, the serialisation cuts
+     *  off and appends `... [+N more nodes elided]`. */
+    maxNodes?: number;
+    /** case-insensitive substring patterns matched against each node's
+     *  `role`, `name`, or `testId`. A matching node *and its entire subtree* is skipped.
+     *  Useful for omitting known-noisy regions (long lists, virtualised tables). */
+    omit?: string[];
+}
+/** Render an A11yNode tree to the compact `role "name" [ref=eN] [state]` form. */
+export declare function serialise(root: A11yNode, opts?: SerialiseOptions): string;
+/**
+ * Find a subtree by ref. Returns the matching node (or null) so callers can
+ * `serialise(findByRef(tree, "e42"), { … })` for scoped snapshots.
+ */
+export declare function findByRef(root: A11yNode, ref: string): A11yNode | null;
+export declare function fmtState(n: A11yNode): string;

package/dist/page/snapshot.js

@@ -0,0 +1,162 @@
+// Compact, token-efficient text serialisation of the a11y tree. Same grammar used
+// everywhere browxai emits a tree (snapshot(), find() context, ActionResult.snapshotDelta) —
+// that's the coherence constraint.
+import { walk } from "./a11y.js";
+/** Render an A11yNode tree to the compact `role "name" [ref=eN] [state]` form. */
+export function serialise(root, opts = {}) {
+    const indent = opts.indent ?? "  ";
+    const maxNameLen = opts.maxNameLen ?? 80;
+    const pruneGeneric = opts.pruneGeneric ?? true;
+    const maxNodes = opts.maxNodes ?? Infinity;
+    const omitPatterns = (opts.omit ?? []).map((p) => p.toLowerCase());
+    const lines = [];
+    let emitted = 0;
+    let truncated = false;
+    let elided = 0;
+    let elidedBranches = 0;
+    // Manual walk so we can prune subtrees on `omit` matches (the generator yields
+    // depth-first; pruning needs to skip descendants explicitly). `visitForSerialise`
+    // decides this node's disposition (skip-subtree / emit / silent-skip); the loop
+    // only owns stack management.
+    const stack = [{ node: root, depth: 0 }];
+    while (stack.length) {
+        const { node, depth } = stack.pop();
+        const v = visitForSerialise(node, depth, {
+            omitPatterns,
+            pruneGeneric,
+            maxNameLen,
+            indent,
+            emitted,
+            maxNodes,
+        });
+        elidedBranches += v.elidedBranches;
+        elided += v.elided;
+        if (v.truncated)
+            truncated = true;
+        if (v.line !== null) {
+            lines.push(v.line);
+            emitted++;
+        }
+        if (v.skipSubtree)
+            continue;
+        for (let i = node.children.length - 1; i >= 0; i--) {
+            stack.push({ node: node.children[i], depth: depth + 1 });
+        }
+    }
+    if (truncated)
+        lines.push(`... [+${elided} more nodes elided; raise maxNodes or pass scope=<ref> to drill in]`);
+    if (elidedBranches > 0 && !truncated) {
+        lines.push(`... [omit matched ${elidedBranches} subtree(s), ${elided} nodes total]`);
+    }
+    return lines.join("\n");
+}
+/** Decide one node's disposition during `serialise`: an `omit` match prunes the
+ *  whole subtree, the maxNodes cap truncates, generic noise is silently dropped,
+ *  otherwise the node is formatted. Pure — the loop applies the result. */
+function visitForSerialise(node, depth, o) {
+    if (matchesOmit(node, o.omitPatterns)) {
+        return {
+            line: null,
+            skipSubtree: true,
+            elided: countSubtree(node),
+            elidedBranches: 1,
+            truncated: false,
+        };
+    }
+    if (o.pruneGeneric && isGenericNoise(node)) {
+        return { line: null, skipSubtree: false, elided: 0, elidedBranches: 0, truncated: false };
+    }
+    if (o.emitted >= o.maxNodes) {
+        // this node + its descendants we'd have emitted.
+        return {
+            line: null,
+            skipSubtree: true,
+            elided: countSubtree(node),
+            elidedBranches: 0,
+            truncated: true,
+        };
+    }
+    return {
+        line: formatNode(node, depth, o.indent, o.maxNameLen),
+        skipSubtree: false,
+        elided: 0,
+        elidedBranches: 0,
+        truncated: false,
+    };
+}
+function matchesOmit(node, patterns) {
+    if (patterns.length === 0)
+        return false;
+    const hay = `${node.role}|${node.name ?? ""}|${node.testId ?? ""}`.toLowerCase();
+    return patterns.some((p) => hay.includes(p));
+}
+function countSubtree(node) {
+    let n = 1;
+    for (const c of node.children)
+        n += countSubtree(c);
+    return n;
+}
+/**
+ * Find a subtree by ref. Returns the matching node (or null) so callers can
+ * `serialise(findByRef(tree, "e42"), { … })` for scoped snapshots.
+ */
+export function findByRef(root, ref) {
+    for (const { node } of walk(root)) {
+        if (node.ref === ref)
+            return node;
+    }
+    return null;
+}
+function formatNode(node, depth, indent, maxNameLen) {
+    const pad = indent.repeat(depth);
+    const nm = node.name ? ` "${truncate(node.name, maxNameLen)}"` : "";
+    // Emit the actual attribute name (e.g. `[data-testid="…"]` or `[data-type="…"]`) so
+    // the agent can transcribe it directly. Falls back to `data-testid` when the source
+    // didn't tell us which attr matched.
+    const tid = node.testId
+        ? ` [${node.testIdAttr ?? "data-testid"}=${JSON.stringify(node.testId)}]`
+        : "";
+    const src = node.source === "dom" ? " [from-dom]" : node.source === "both" ? " [from-both]" : "";
+    return `${pad}${node.role}${nm} [ref=${node.ref}]${tid}${src}${fmtState(node)}`;
+}
+export function fmtState(n) {
+    const bits = [];
+    if (n.disabled)
+        bits.push("disabled");
+    if (n.checked !== undefined)
+        bits.push(`checked=${n.checked}`);
+    if (n.pressed !== undefined)
+        bits.push(`pressed=${n.pressed}`);
+    if (n.selected)
+        bits.push("selected");
+    if (n.expanded !== undefined)
+        bits.push(`expanded=${n.expanded}`);
+    if (n.focused)
+        bits.push("focused");
+    if (n.value !== undefined && n.value !== "") {
+        bits.push(`value=${JSON.stringify(String(n.value).slice(0, 60))}`);
+    }
+    return bits.length ? ` [${bits.join(", ")}]` : "";
+}
+function truncate(s, n) {
+    return s.length <= n ? s : s.slice(0, n - 1) + "…";
+}
+/**
+ * Drop generic / presentational nodes that carry no agent signal:
+ * - role "generic" / "presentation" with no name and no testId
+ * - role "none"
+ * - "text" leaves with no name (i.e. empty)
+ * These nodes still let their *children* through (caller walks the tree); we
+ * just skip emitting a line for them.
+ */
+function isGenericNoise(n) {
+    if (n.testId)
+        return false;
+    if (n.role === "none")
+        return true;
+    if ((n.role === "generic" || n.role === "presentation") && !n.name)
+        return true;
+    if (n.role === "StaticText" && !n.name)
+        return true;
+    return false;
+}

package/dist/page/solve-captcha.d.ts

@@ -0,0 +1,76 @@
+/** Provider names this version of the module knows how to talk to. Other
+ *  providers can be added without breaking the env-config surface — new
+ *  names just append. */
+export declare const KNOWN_PROVIDERS: readonly ["2captcha", "capmonster"];
+export type CaptchaProvider = (typeof KNOWN_PROVIDERS)[number];
+/** Captcha types this tool surfaces in its input schema. The string is
+ *  forwarded to the provider — providers themselves accept the same shape
+ *  (`recaptcha2`, `hcaptcha`, `image`, etc.) so we keep the vocabulary thin. */
+export type CaptchaType = "recaptcha2" | "recaptcha3" | "hcaptcha" | "image" | "turnstile";
+/** Resolved provider config (from env). `apiKey` is sensitive — NEVER log it,
+ *  NEVER include it on the tool result. */
+export interface CaptchaProviderConfig {
+    provider: CaptchaProvider;
+    apiKey: string;
+    /** Override the provider's base URL. Default is the canonical endpoint for
+     *  the chosen provider. Useful for self-hosted CapMonster-compatible
+     *  proxies or for testing. */
+    apiBase: string;
+    /** Per-attempt polling deadline in milliseconds. Default 120_000
+     *  (2 minutes) — most providers take 10–60s for image/recaptcha. */
+    timeoutMs: number;
+    /** Poll interval between `getTaskResult` calls. Default 5000 ms. */
+    pollMs: number;
+}
+/** Read provider config from env. Returns `null` when nothing is configured —
+ *  the caller surfaces a structured `ok:false` with a "no provider
+ *  configured" hint rather than throwing (the capability is on but the
+ *  deployment hasn't wired a solver — recoverable, not a server-startup
+ *  error). Returns an `error` object on partial config (provider set without
+ *  api-key, unknown provider name) so the agent sees a clear pointer. */
+export declare function resolveCaptchaProvider(env?: NodeJS.ProcessEnv): {
+    ok: true;
+    config: CaptchaProviderConfig;
+} | {
+    ok: false;
+    reason: "unconfigured" | "partial";
+    error?: string;
+};
+/** A challenge ready to submit. The shape mirrors the 2Captcha `in.php` form:
+ *  `googlekey` + `pageurl` for recaptcha2/3, `sitekey` + `pageurl` for
+ *  hcaptcha / turnstile, `body` (base64) for image. The tool layer extracts
+ *  these from the page given `type` + `selector` + the current page URL. */
+export interface CaptchaChallenge {
+    type: CaptchaType;
+    pageUrl: string;
+    /** For recaptcha/hcaptcha/turnstile: the site-key as published on the page. */
+    siteKey?: string;
+    /** For image captchas: base64-encoded image bytes (without the data URL prefix). */
+    imageBase64?: string;
+}
+/** Solver result envelope. `solution` is the provider-returned token / text
+ *  the agent then types into a hidden form field or invokes a JS callback
+ *  with. We do NOT auto-submit — the agent is in the driver's seat for
+ *  what to do with the solution (different sites wire reCAPTCHA differently). */
+export interface CaptchaSolution {
+    ok: true;
+    provider: CaptchaProvider;
+    solution: string;
+    /** Provider-specific task id (for logs / cost reconciliation, never sensitive). */
+    taskId: string;
+    elapsedMs: number;
+}
+export interface CaptchaFailure {
+    ok: false;
+    provider: CaptchaProvider | null;
+    error: string;
+    hint: string;
+    /** Best-effort: when the provider returned a structured error, surface its
+     *  code so the agent can decide whether to retry. */
+    providerCode?: string;
+}
+export declare function submitToProvider(challenge: CaptchaChallenge, config: CaptchaProviderConfig, fetchImpl?: typeof fetch, nowFn?: () => number, sleepFn?: (ms: number) => Promise<void>): Promise<CaptchaSolution | CaptchaFailure>;
+/** Build the structured "no provider configured" failure — used when the
+ *  capability is on but env vars are unset. Hints at exactly what to set and
+ *  names the per-deployment / no-bundled-solver / no-auto-purchase posture. */
+export declare function unconfiguredFailure(): CaptchaFailure;