browxai 0.7.0

package/dist/page/coverage.js

@@ -0,0 +1,280 @@
+// Coverage — capability split: `coverage_start` is `action` (arms CDP state
+// on the target); `coverage_stop` is `read` (pure stop + parse, no file
+// written, no further mutation past releasing the in-flight state).
+//
+// "Half of this CSS file is dead — which selectors?" + "We ship 200KB of JS
+// but boot only uses 30KB — what's unused?" have no diagnostic surface in
+// the existing perf primitives (`perf_audit` consumes coverage *output*; the
+// production of that output is here). Wraps two CDP primitives in lockstep:
+//
+//   - `Profiler.startPreciseCoverage`     — per-script byte-level use counts.
+//   - `CSS.startRuleUsageTracking`        — per-stylesheet rule-level use
+//                                            counts (which selectors fired).
+//
+// Lifecycle:
+//   - coverage_start({session?})  → enables both trackers on this session's
+//                                   CDP target. Idempotent restart: a fresh
+//                                   `coverage_start` while one is already
+//                                   running cleanly stops the in-flight pair
+//                                   and starts new.
+//   - coverage_stop({session?})   → stops both trackers, fetches the buffered
+//                                   results (Profiler.takePreciseCoverage +
+//                                   CSS.takeCoverageDelta), parses into the
+//                                   structured shape the agent reads, and
+//                                   surfaces it. Composes inside `perf_audit`
+//                                   when the audit window spans them.
+//
+// Both shapes are surfaced as `usagePercent` so the agent can scan a table
+// of "delete me first" candidates without bringing a calculator. JS scripts
+// with `usagePercent < 100` and CSS files with `usagePercent < 100` indicate
+// dead code. The audit's `unused-code` category uses a 30% floor (anything
+// below that is "obviously dead, fix first").
+const MAX_DEAD_RANGES_PER_SCRIPT = 50;
+/** Per-session coverage tracker. One instance per SessionEntry; the
+ *  underlying CDP coverage is per-target. */
+export class CoverageTrackerState {
+    running = false;
+    startedAt = 0;
+    /** Snapshot of `getAllStyleSheets()` taken at `start` so `stop` can map
+     *  styleSheetId → URL + total length without a second CDP roundtrip. */
+    cssHeaders = new Map();
+    /** CSS.styleSheetAdded event handler — kept for cleanup. */
+    onStyleSheetAdded = null;
+    isRunning() {
+        return this.running;
+    }
+    /** Start both Profiler + CSS coverage on `cdp`. Returns `{restarted}` —
+     *  if an instance was already running, it is cleanly stopped (results
+     *  discarded) and a fresh one begins. */
+    async start(cdp) {
+        let restarted = false;
+        if (this.running) {
+            restarted = true;
+            await this.stopInternal(cdp).catch(() => undefined);
+        }
+        this.cssHeaders = new Map();
+        // Enable + start profiler precise coverage. `detailed:true` gives us
+        // per-function block ranges (we use them to compute used bytes); other
+        // params keep CPU profiling off — we just want coverage.
+        await cdp.send("Profiler.enable").catch(() => undefined);
+        await cdp.send("Profiler.startPreciseCoverage", {
+            callCount: false,
+            detailed: true,
+            allowTriggeredUpdates: false,
+        });
+        // Enable + start CSS rule usage tracking. Capture pre-existing
+        // stylesheets via styleSheetAdded events while tracking is on (the CDP
+        // event stream is the way to get the URL + length mapping for
+        // styleSheetId; calling `CSS.getStyleSheetText` per id would be slow).
+        await cdp.send("DOM.enable").catch(() => undefined);
+        await cdp.send("CSS.enable").catch(() => undefined);
+        const onAdded = (e) => {
+            if (e?.header?.styleSheetId)
+                this.cssHeaders.set(e.header.styleSheetId, e.header);
+        };
+        cdp.on("CSS.styleSheetAdded", onAdded);
+        this.onStyleSheetAdded = onAdded;
+        await cdp.send("CSS.startRuleUsageTracking");
+        this.running = true;
+        this.startedAt = Date.now();
+        return { startedAt: this.startedAt, restarted };
+    }
+    /** Stop both trackers, fetch + parse the results. Safe to call when no
+     *  coverage is running — returns an empty report with `notRunning:true`. */
+    async stop(cdp) {
+        if (!this.running) {
+            return { jsCoverage: [], cssCoverage: [], durationMs: 0, notRunning: true };
+        }
+        const durationMs = Date.now() - this.startedAt;
+        let jsRaw = {};
+        let cssRaw = {};
+        try {
+            jsRaw = await cdp.send("Profiler.takePreciseCoverage");
+        }
+        catch {
+            jsRaw = { result: [] };
+        }
+        try {
+            cssRaw = await cdp.send("CSS.stopRuleUsageTracking");
+        }
+        catch {
+            cssRaw = { ruleUsage: [] };
+        }
+        await this.stopInternal(cdp);
+        return {
+            jsCoverage: parseJsCoverage(jsRaw.result ?? []),
+            cssCoverage: parseCssCoverage(cssRaw.ruleUsage ?? [], this.cssHeaders),
+            durationMs,
+        };
+    }
+    /** Force-clean teardown for session close. */
+    async closeIfRunning(cdp) {
+        if (!this.running)
+            return;
+        await this.stopInternal(cdp).catch(() => undefined);
+    }
+    async stopInternal(cdp) {
+        try {
+            await cdp.send("Profiler.stopPreciseCoverage").catch(() => undefined);
+        }
+        catch {
+            /* best-effort */
+        }
+        if (this.onStyleSheetAdded) {
+            try {
+                cdp.off("CSS.styleSheetAdded", this.onStyleSheetAdded);
+            }
+            catch {
+                /* best-effort */
+            }
+            this.onStyleSheetAdded = null;
+        }
+        this.running = false;
+    }
+}
+/** Parse the `Profiler.takePreciseCoverage` result into per-script entries.
+ *  Exported for unit tests against a synthetic CDP payload.
+ *
+ *  V8 coverage shape: each script has multiple `functions` entries. The
+ *  first is the synthetic "outer" anonymous wrapper covering the whole
+ *  script — its count is the script-level execution counter and tells us
+ *  nothing about which bytes ran. The remaining entries are real functions
+ *  (or block-coverage subranges within them). The way DevTools' Coverage
+ *  panel computes "used":
+ *    - For each function, if its first (root) range has count:0, the entire
+ *      function body is dead.
+ *    - Otherwise, the function ran; if `isBlockCoverage:true`, sub-ranges
+ *      with count:0 are dead blocks within the live function.
+ *  We follow the same algorithm: aggregate per-function dead ranges, then
+ *  total used = script length - sum of dead ranges. */
+/** The script's total byte span = the largest `endOffset` across all ranges. */
+function scriptTotalSpan(s) {
+    let total = 0;
+    for (const fn of s.functions ?? []) {
+        for (const r of fn.ranges ?? []) {
+            if (typeof r.endOffset === "number" && r.endOffset > total)
+                total = r.endOffset;
+        }
+    }
+    return total;
+}
+/** Collect dead (count:0) byte ranges. The first range in each `ranges[]` is the
+ *  function body; subsequent ranges are sub-blocks (when isBlockCoverage:true). */
+function collectDeadRanges(s) {
+    const deadRanges = [];
+    for (const fn of s.functions ?? []) {
+        const ranges = fn.ranges ?? [];
+        if (ranges.length === 0)
+            continue;
+        const root = ranges[0];
+        if (typeof root.startOffset !== "number" || typeof root.endOffset !== "number")
+            continue;
+        if (root.count === 0) {
+            deadRanges.push([root.startOffset, root.endOffset]); // whole body dead
+            continue;
+        }
+        for (let i = 1; i < ranges.length; i++) {
+            const r = ranges[i];
+            if (r.count === 0 && typeof r.startOffset === "number" && typeof r.endOffset === "number") {
+                deadRanges.push([r.startOffset, r.endOffset]);
+            }
+        }
+    }
+    return deadRanges;
+}
+/** Merge overlapping (sorted-by-start) ranges into a minimal disjoint set. */
+function mergeRanges(ranges) {
+    const sorted = [...ranges].sort((a, b) => a[0] - b[0]);
+    const merged = [];
+    let dStart = -1;
+    let dEnd = -1;
+    for (const [s, e] of sorted) {
+        if (s > dEnd) {
+            if (dEnd > dStart)
+                merged.push([dStart, dEnd]);
+            dStart = s;
+            dEnd = e;
+        }
+        else if (e > dEnd) {
+            dEnd = e;
+        }
+    }
+    if (dEnd > dStart)
+        merged.push([dStart, dEnd]);
+    return merged;
+}
+function parseScriptCoverage(s) {
+    const url = typeof s.url === "string" ? s.url : "";
+    if (!url)
+        return null;
+    const total = scriptTotalSpan(s);
+    const mergedDead = mergeRanges(collectDeadRanges(s));
+    const deadBytes = mergedDead.reduce((sum, [s3, e3]) => sum + (e3 - s3), 0);
+    const used = Math.max(0, total - deadBytes);
+    const usagePercent = total === 0 ? 100 : Math.round((used / total) * 10000) / 100;
+    const dead = mergedDead
+        .slice(0, MAX_DEAD_RANGES_PER_SCRIPT)
+        .map(([s5, e5]) => ({ start: s5, end: e5 }));
+    const entry = { url, totalBytes: total, usedBytes: used, usagePercent };
+    if (dead.length > 0)
+        entry.deadRanges = dead;
+    return entry;
+}
+export function parseJsCoverage(scripts) {
+    const out = [];
+    for (const s of scripts) {
+        const entry = parseScriptCoverage(s);
+        if (entry)
+            out.push(entry);
+    }
+    return out;
+}
+/** Parse `CSS.stopRuleUsageTracking` output into per-stylesheet entries.
+ *  Exported for unit tests against synthetic CDP payloads. */
+export function parseCssCoverage(ruleUsage, headers) {
+    // Group by styleSheetId. Each entry: url + total span + used+dead ranges.
+    const byId = new Map();
+    for (const r of ruleUsage) {
+        const id = r.styleSheetId;
+        if (!id)
+            continue;
+        let g = byId.get(id);
+        if (!g) {
+            g = { used: [], dead: [], maxEnd: 0 };
+            byId.set(id, g);
+        }
+        if (r.endOffset > g.maxEnd)
+            g.maxEnd = r.endOffset;
+        if (r.used)
+            g.used.push([r.startOffset, r.endOffset]);
+        else
+            g.dead.push([r.startOffset, r.endOffset]);
+    }
+    const out = [];
+    for (const [id, g] of byId) {
+        const hdr = headers.get(id);
+        // Prefer the explicit header length when available; CDP sometimes
+        // reports 0 for inline stylesheets without sourceURL — fall back to
+        // the maxEnd observation from the rule-usage stream.
+        const total = hdr?.length && hdr.length > 0 ? hdr.length : g.maxEnd;
+        let usedBytes = 0;
+        for (const [s, e] of g.used)
+            usedBytes += Math.max(0, e - s);
+        const usagePercent = total === 0 ? 100 : Math.round((usedBytes / total) * 10000) / 100;
+        const entry = {
+            url: hdr?.sourceURL || `inline:${id}`,
+            totalBytes: total,
+            usedBytes,
+            usedRules: g.used.length,
+            totalRules: g.used.length + g.dead.length,
+            usagePercent,
+        };
+        if (g.dead.length > 0) {
+            entry.deadRules = g.dead
+                .slice(0, MAX_DEAD_RANGES_PER_SCRIPT)
+                .map(([s, e]) => ({ start: s, end: e }));
+        }
+        out.push(entry);
+    }
+    return out;
+}

package/dist/page/dom-export.d.ts

@@ -0,0 +1,41 @@
+export type DomExportFormat = "html" | "jsonl";
+export interface DomExportArgs {
+    /** Output format. Default `"html"`. */
+    format?: DomExportFormat;
+    /** Walk open shadow roots when serialising. Default `true`. Closed
+     *  shadow roots are inaccessible (web-platform constraint). */
+    includeShadow?: boolean;
+    /** Workspace-rooted output path. Default
+     *  `dom-dumps/<sessionId>-<ISO>.{html|jsonl}`. Rejected if it escapes
+     *  $BROWX_WORKSPACE. */
+    path?: string;
+}
+export interface DomExportResult {
+    ok: true;
+    format: DomExportFormat;
+    /** Absolute, workspace-rooted output path. */
+    path: string;
+    /** Size on disk, in bytes. */
+    sizeBytes: number;
+    /** Total DOM nodes walked. For `html` mode, derived from a single
+     *  page-side count; for `jsonl` mode, the line count. */
+    nodeCount: number;
+    /** Count of open shadow roots descended into during the walk. Zero
+     *  for `html` mode (shadow content is inaccessible to `outerHTML` —
+     *  see the warning). */
+    shadowRootCount: number;
+    /** Non-fatal advisories. Always carries the secrets-masking caveat;
+     *  also surfaces the closed-shadow + outerHTML-loses-shadow gaps. */
+    warnings: string[];
+}
+/** Workspace-relative default — namespaced under `dom-dumps/`. */
+export declare function defaultDomExportPath(sessionId: string, format: DomExportFormat): string;
+/** Thin adapter — `Page.evaluate(fn, args)`. Keeps the unit tests
+ *  trivial: a stub that returns whatever `PageWalkResult` it was
+ *  programmed with. `evaluate` takes a real function (Playwright
+ *  serializes it + invokes in-page with arg) — passing a stringified
+ *  arrow expression returns the function value uncalled. */
+export interface DomExportPage {
+    evaluate<T, Arg>(fn: (arg: Arg) => T | Promise<T>, args?: Arg): Promise<T>;
+}
+export declare function domExport(page: DomExportPage, workspaceRoot: string, sessionId: string, args?: DomExportArgs): Promise<DomExportResult>;

package/dist/page/dom-export.js

@@ -0,0 +1,193 @@
+/// <reference lib="dom" />
+// `dom_export` — full DOM dump.
+//
+// Two formats:
+//
+//   - `html` (default) — `document.documentElement.outerHTML` written
+//     verbatim to a workspace-rooted `.html` file. The agent has already
+//     stabilized the page (`navigate` + any settle) — the tool does NOT
+//     inject its own wait, same posture as `page_archive`.
+//
+//   - `jsonl` — one JSON object per line, depth-first walk:
+//       `{tag, role?, attrs, text?, ref?, depth}`
+//     A grep-friendly serialization for the cases where the agent needs
+//     to scan structure without parsing HTML. `attrs` is a flat
+//     attribute-name → value map; `text` is set only for nodes whose
+//     direct text content is non-empty (whitespace-trimmed); `ref` echoes
+//     the stable `eN` ref when the node was discovered as part of a prior
+//     `snapshot()` / `find()` (otherwise omitted — refs aren't minted
+//     during the dump itself).
+//
+// Shadow-DOM traversal (default ON, `includeShadow:true`):
+//   The walker descends into every open shadow root (`Element.shadowRoot`
+//   when not null). Closed shadow roots are inaccessible by web-platform
+//   design — `shadowRoot` returns null and the tree behind them is
+//   genuinely unreachable. The result envelope surfaces the limitation
+//   via `warnings[]` when the document is detected to have HTML content
+//   that hints at custom elements (best-effort heuristic).
+//
+// Secrets-masking interplay (DELIBERATE GAP):
+//   Same gap as `page_archive` / `element_export`. The dump is faithful;
+//   running egress masking over it would corrupt inline JSON state blobs.
+//   The `warnings[]` array always carries the caveat as its first entry.
+import { resolve as resolvePath, dirname } from "node:path";
+import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { resolveWorkspacePath } from "../session/storage.js";
+/** Workspace-relative default — namespaced under `dom-dumps/`. */
+export function defaultDomExportPath(sessionId, format) {
+    const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_") || "default";
+    const ts = new Date().toISOString().replace(/[:.]/g, "-");
+    const ext = format === "jsonl" ? ".jsonl" : ".html";
+    return `dom-dumps/${safe}-${ts}${ext}`;
+}
+/** Page-side walk function — returns either a single string (html mode)
+ *  or an array of JSONL-ready objects (jsonl mode). One round-trip per
+ *  invocation; the dump is bounded by the page's DOM size, no per-node
+ *  evaluate.
+ *
+ *  Passed as a real function literal (NOT a stringified expression) so
+ *  Playwright's `Page.evaluate(fn, arg)` path serializes the source and
+ *  invokes in-page with the arg — a stringified `(args) => {...}` would
+ *  evaluate to the function value uncalled, which CDP can't serialize. */
+const PAGE_WALK_FN = (args) => {
+    const mode = args.mode;
+    const includeShadow = args.includeShadow;
+    let hasCustomElements = false;
+    try {
+        const all = document.querySelectorAll("*");
+        for (let i = 0; i < all.length && i < 500; i++) {
+            if (all[i].tagName && all[i].tagName.indexOf("-") !== -1) {
+                hasCustomElements = true;
+                break;
+            }
+        }
+    }
+    catch {
+        // best-effort: querySelectorAll can throw on hostile/torn-down documents
+    }
+    if (mode === "html") {
+        const html = document.documentElement ? document.documentElement.outerHTML : "";
+        let count = 0;
+        try {
+            count = document.querySelectorAll("*").length;
+        }
+        catch {
+            // best-effort: leave count=0 if querySelectorAll throws
+        }
+        return { html, nodeCount: count, shadowRootCount: 0, hasCustomElements };
+    }
+    const nodes = [];
+    let shadowRoots = 0;
+    function attrsOf(el) {
+        const a = {};
+        const atts = el.attributes;
+        if (!atts)
+            return a;
+        for (let i = 0; i < atts.length; i++) {
+            a[atts[i].name] = atts[i].value;
+        }
+        return a;
+    }
+    function directText(el) {
+        let t = "";
+        const kids = el.childNodes;
+        for (let i = 0; i < kids.length; i++) {
+            if (kids[i].nodeType === 3)
+                t += kids[i].nodeValue || "";
+        }
+        return t.replace(/\s+/g, " ").trim();
+    }
+    function visit(node, depth) {
+        if (!node || node.nodeType !== 1)
+            return;
+        const entry = {
+            tag: (node.tagName || "").toLowerCase(),
+            attrs: attrsOf(node),
+            depth,
+        };
+        const role = node.getAttribute("role");
+        if (role)
+            entry.role = role;
+        const txt = directText(node);
+        if (txt)
+            entry.text = txt;
+        const refAttr = node.getAttribute("data-browx-ref") || "";
+        if (refAttr)
+            entry.ref = refAttr;
+        nodes.push(entry);
+        if (includeShadow && node.shadowRoot) {
+            shadowRoots++;
+            const sKids = node.shadowRoot.children;
+            for (let j = 0; j < sKids.length; j++)
+                visit(sKids[j], depth + 1);
+        }
+        const kids = node.children;
+        for (let k = 0; k < kids.length; k++)
+            visit(kids[k], depth + 1);
+    }
+    if (document.documentElement)
+        visit(document.documentElement, 0);
+    return {
+        nodes,
+        nodeCount: nodes.length,
+        shadowRootCount: shadowRoots,
+        hasCustomElements,
+    };
+};
+export async function domExport(page, workspaceRoot, sessionId, args = {}) {
+    const format = args.format ?? "html";
+    const includeShadow = args.includeShadow ?? true;
+    const relPath = args.path ?? defaultDomExportPath(sessionId, format);
+    const resolved = resolveWorkspacePath(workspaceRoot, relPath, "dom_export");
+    const walked = await page.evaluate(PAGE_WALK_FN, {
+        mode: format,
+        includeShadow,
+    });
+    const warnings = [
+        "dom_export output is UNMASKED — secrets-masking would corrupt the dump (literal-substring substitution breaks inline JSON / CSS / binary bytes). Treat the dump as sensitive material, same posture as page_archive / dump_storage_state.",
+    ];
+    // Workspace-rooted by construction — `resolved` ⊆ BROWX_WORKSPACE.
+    mkdirSync(dirname(resolved), { recursive: true });
+    let sizeBytes = 0;
+    let nodeCount = walked.nodeCount;
+    const shadowRootCount = walked.shadowRootCount;
+    if (format === "html") {
+        const html = walked.html ?? "";
+        // workspace-rooted: resolved ⊆ BROWX_WORKSPACE (resolveWorkspacePath above).
+        writeFileSync(resolved, html, "utf8");
+        sizeBytes = statSync(resolved).size;
+        // `outerHTML` does not serialise shadow-DOM content (open OR closed),
+        // even though open shadow roots are programmatically reachable. The
+        // gap is intrinsic to the platform serializer; surface it so the
+        // adopter doesn't wonder where the Web Component's interior went.
+        if (walked.hasCustomElements || includeShadow) {
+            warnings.push("html mode: `documentElement.outerHTML` does NOT include shadow-DOM content (open OR closed) — " +
+                'the platform serializer omits shadow trees. For shadow content, use `format:"jsonl"` with `includeShadow:true` (default).');
+        }
+    }
+    else {
+        // jsonl — one JSON object per line.
+        const lines = [];
+        for (const n of walked.nodes ?? []) {
+            lines.push(JSON.stringify(n));
+        }
+        const body = lines.join("\n") + (lines.length > 0 ? "\n" : "");
+        // workspace-rooted: resolved ⊆ BROWX_WORKSPACE (resolveWorkspacePath above).
+        writeFileSync(resolved, body, "utf8");
+        sizeBytes = statSync(resolved).size;
+        nodeCount = lines.length;
+    }
+    if (walked.hasCustomElements) {
+        warnings.push("Document uses custom elements. Closed shadow roots are inaccessible by web-platform design — " +
+            "any tree behind a closed root is genuinely unreachable from this dump.");
+    }
+    return {
+        ok: true,
+        format,
+        path: resolvePath(resolved),
+        sizeBytes,
+        nodeCount,
+        shadowRootCount,
+        warnings,
+    };
+}

package/dist/page/dom-walk.d.ts

@@ -0,0 +1,91 @@
+import type { CDPSession, Frame } from "playwright-core";
+import { RefRegistry } from "./refs.js";
+import type { A11yNode } from "./a11y.js";
+export interface DomWalkEntry {
+    role: string;
+    name: string;
+    testId: string;
+    testIdAttr: string;
+    tag: string;
+    id: string;
+    structuralPath: string;
+    /** Valid CSS selector built from the `:nth-child` chain at walk time.
+     *  Used as the locator for refs whose role is a bare tag (`td`, `div`,
+     *  generic) where `getByRole` would be ambiguous or wrong. */
+    cssPath: string;
+}
+export interface DomWalkOptions {
+    /** Attributes treated as "test ids" (tier-1 selectorHint candidates). */
+    testAttributes?: string[];
+    /** Hard cap on returned entries (sanity bound; the JS side already caps). */
+    maxEntries?: number;
+    /** shadow DOM piercing.
+     *  - `"open"` (the implicit default — preserves pre-v0.5.0 behaviour;
+     *    the page-side walk recurses into every `Element.shadowRoot` it sees,
+     *    same as `querySelectorAll` semantics on open roots).
+     *  - `"closed"` — additionally invokes the CDP `DOM.getDocument(
+     *    {pierce:true})` path and harvests interactive / test-attr-bearing
+     *    elements that live inside closed shadow roots. Best-effort; falls
+     *    back to open-only when CDP refuses pierce.
+     *  - `false` — no shadow recursion. Equivalent to walking only the top
+     *    document's children.
+     */
+    pierce?: "open" | "closed" | false;
+}
+/**
+ * Run the in-page DOM-walk and return the discovered entries.
+ *
+ * Notes:
+ *  - The script runs in page context — keep it ECMAScript-only (no TS).
+ *  - Stringified function so we can pass it through `Runtime.evaluate` with
+ *    `returnByValue: true`.
+ *  - Visibility is checked at walk time (`getBoundingClientRect` non-zero + computed
+ *    `visibility !== hidden` + `display !== none`). This intentionally skips offscreen
+ *    elements (they wouldn't be clickable from the agent's POV right now).
+ */
+export declare function runDomWalk(cdp: CDPSession, opts?: DomWalkOptions): Promise<DomWalkEntry[]>;
+/**
+ * Frame-scoped DOM walk. Same `PAGE_SCRIPT`, but evaluated inside
+ * a Playwright `Frame` via `frame.evaluate(...)` instead of the top-level
+ * CDP `Runtime.evaluate`. Works transparently for both same-origin and
+ * cross-origin (OOPIF) child frames — Playwright's frame API spans both.
+ *
+ * Honours `pierce` the same way the top-level walk does: `"open"` / `"closed"`
+ * recurses into reachable open shadow roots inside the frame; `false` /
+ * undefined sticks to the frame's top document. Closed-shadow CDP harvesting
+ * is not run for child frames (the CDP path is rooted at the top target).
+ */
+export declare function runDomWalkOnFrame(frame: Frame, opts?: DomWalkOptions): Promise<DomWalkEntry[]>;
+/**
+ * Transport-agnostic DOM walk. Runs the SAME `PAGE_SCRIPT` via an injected
+ * `exec` that takes a function BODY + an args array and returns the value —
+ * exactly the WebDriver-Classic `execute/sync` shape (`{script, args}`). This is
+ * the seam the Safari snapshot substrate uses: Safari has neither
+ * CDP nor a Playwright Frame, but `safaridriver`'s `execute/sync` runs the script
+ * identically (the returned `DomWalkEntry` shape matches
+ * `frame.evaluate` byte-for-byte).
+ * `PAGE_SCRIPT` stays encapsulated here; callers pass only the transport.
+ */
+export declare function runDomWalkViaExecute(exec: (scriptBody: string, args: unknown[]) => Promise<unknown>, opts?: DomWalkOptions): Promise<DomWalkEntry[]>;
+/**
+ * Convert DOM-walk entries to A11yNode leaves and add them as children of `root`,
+ * minting refs through the same `RefRegistry` so the IDs are stable across snapshots
+ * (and round-trip with the a11y nodes' refs when both paths see the same element).
+ *
+ * Returns the count of *new* nodes added (i.e. nodes whose stable key wasn't already
+ * present in the registry) so the caller can emit a low-content warning.
+ */
+export interface MergeOptions {
+    /** when set, refs minted here are namespaced to this frame
+     *  (via `elementKey`'s `frameId`) so two iframes with identical markup
+     *  don't collide on the same ref. */
+    frameId?: string;
+    /** when set, refs minted here are bound to this Frame on the
+     *  registry so action-time `locatorFor` routes through `frame.locator(...)`
+     *  instead of `page.locator(...)`. */
+    frame?: Frame;
+}
+export declare function mergeDomWalkIntoTree(root: A11yNode, entries: DomWalkEntry[], refs: RefRegistry, opts?: MergeOptions): {
+    added: number;
+    combined: number;
+};