browxai 0.7.0

package/dist/page/shadow.js

@@ -0,0 +1,400 @@
+// Shadow DOM deep piercing.
+//
+// Two layers:
+//   1. Open shadow — reachable from page-side JS via `Element.shadowRoot`.
+//      A `Runtime.evaluate`-driven walker covers this case identically to the
+//      one in `dom-export.ts`'s jsonl path.
+//   2. Closed shadow — `Element.shadowRoot === null` for any closed-mode
+//      web component, but DevTools-level access via `DOM.getDocument({pierce:
+//      true, depth: -1})` returns the closed-shadow subtree in each node's
+//      `shadowRoots[]` array (CDP exposes both open + closed; the page-side
+//      JS only ever sees open).
+//
+// Best-effort by design:
+//   - CDP `pierce` is a Chromium DevTools facility, not a web-platform
+//     guarantee. Older Chrome builds, non-Chromium browsers, and pages whose
+//     renderer is throttled / detached will fall back to the open-only view
+//     and surface a `closedShadowAvailable: false` flag.
+//   - Closed shadow piercing is intentionally one-way: we read what CDP
+//     exposes. We never reach in via the page itself (which would require
+//     patching `attachShadow` before the page loaded — out of scope; the
+//     `stealth` capability already covers that direction for adjacent reasons).
+//
+// Everything in this file is read-only.
+/**
+ * Read the full pierced DOM. Returns the root node and a "closed shadow root
+ * exists somewhere" flag. Falls back to an open-only document when CDP refuses
+ * the `pierce` parameter (older Chromium, attached BYOB endpoints whose CDP
+ * vintage differs from the launcher's). Caller is responsible for treating a
+ * `null` result as "shadow walk unavailable" — no exception is thrown so the
+ * outer tool can still emit a partial result.
+ */
+export async function fetchPiercedDocument(cdp) {
+    // depth: -1 = walk full subtree. pierce: true = traverse shadow + iframes.
+    try {
+        const { root } = (await cdp.send("DOM.getDocument", {
+            depth: -1,
+            pierce: true,
+        }));
+        return { root, closedAvailable: hasClosedShadow(root) };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            root: null,
+            closedAvailable: false,
+            warning: `CDP DOM.getDocument({pierce:true}) failed (${msg}); ` +
+                `closed-shadow piercing unavailable on this browser/page. ` +
+                `Open shadow roots are still reachable via the standard walk.`,
+        };
+    }
+}
+function hasClosedShadow(root) {
+    // Iterative DFS to avoid stack blow-up on large documents.
+    const stack = [root];
+    while (stack.length) {
+        const n = stack.pop();
+        for (const sr of n.shadowRoots ?? []) {
+            if (sr.shadowRootType === "closed")
+                return true;
+            stack.push(sr);
+        }
+        for (const c of n.children ?? [])
+            stack.push(c);
+        if (n.contentDocument)
+            stack.push(n.contentDocument);
+    }
+    return false;
+}
+/**
+ * Walk a CDP-pierced document and collect shadow-root entries. When
+ * `rootBackendNodeId` is set, only the subtree rooted at that backend id
+ * contributes. When omitted, the entire document is walked.
+ */
+export function collectShadowTrees(root, opts) {
+    const cap = opts.maxHosts ?? 200;
+    let subtree = root;
+    if (opts.rootBackendNodeId !== undefined) {
+        subtree = findByBackendId(root, opts.rootBackendNodeId);
+        if (!subtree)
+            return { entries: [] };
+    }
+    const entries = [];
+    walkForShadowHosts(subtree, entries, cap);
+    if (entries.length >= cap)
+        return { entries, cappedAt: cap };
+    return { entries };
+}
+function findByBackendId(root, target) {
+    const stack = [root];
+    while (stack.length) {
+        const n = stack.pop();
+        if (n.backendNodeId === target)
+            return n;
+        for (const c of n.children ?? [])
+            stack.push(c);
+        for (const sr of n.shadowRoots ?? [])
+            stack.push(sr);
+        if (n.contentDocument)
+            stack.push(n.contentDocument);
+    }
+    return null;
+}
+/** Summarise the element children of one shadow root (tag + child count + direct
+ *  text), skipping non-element nodes. */
+function summariseShadowChildren(sr) {
+    const children = [];
+    for (const c of sr.children ?? []) {
+        if (c.nodeType !== 1)
+            continue;
+        const summary = {
+            tag: (c.localName ?? c.nodeName ?? "").toLowerCase(),
+            childCount: countElementChildren(c),
+        };
+        const txt = directText(c);
+        if (txt)
+            summary.text = txt;
+        children.push(summary);
+    }
+    return children;
+}
+/** Build the `ShadowTreeEntry` for one host node + shadow root (non-user-agent). */
+function buildShadowEntry(host, sr) {
+    return {
+        hostRef: `backend:${host.backendNodeId ?? 0}`,
+        hostTag: (host.localName ?? host.nodeName ?? "").toLowerCase(),
+        mode: sr.shadowRootType === "closed" ? "closed" : "open",
+        children: summariseShadowChildren(sr),
+        descendantCount: countDescendantElements(sr),
+    };
+}
+function walkForShadowHosts(node, out, cap) {
+    // BFS so we surface hosts in document order — easier for an agent to reason
+    // about than DFS's reverse traversal.
+    const queue = [node];
+    while (queue.length && out.length < cap) {
+        const n = queue.shift();
+        for (const sr of n.shadowRoots ?? []) {
+            if (out.length >= cap)
+                break;
+            // user-agent shadow roots (e.g. <video> internals) aren't the adopter's
+            // app — not what an agent means by "the shadow root under this component."
+            if (sr.shadowRootType === "user-agent")
+                continue;
+            out.push(buildShadowEntry(n, sr));
+            for (const c of sr.children ?? [])
+                queue.push(c); // descend for nested hosts
+        }
+        for (const c of n.children ?? [])
+            queue.push(c);
+        if (n.contentDocument)
+            queue.push(n.contentDocument);
+    }
+}
+function directText(node) {
+    for (const c of node.children ?? []) {
+        if (c.nodeType === 3 && c.nodeValue) {
+            const t = c.nodeValue.replace(/\s+/g, " ").trim();
+            if (t)
+                return t.length > 80 ? `${t.slice(0, 79)}…` : t;
+        }
+    }
+    return undefined;
+}
+function countElementChildren(node) {
+    let n = 0;
+    for (const c of node.children ?? [])
+        if (c.nodeType === 1)
+            n++;
+    return n;
+}
+function countDescendantElements(node) {
+    let n = 0;
+    const stack = [...(node.children ?? [])];
+    while (stack.length) {
+        const c = stack.pop();
+        if (c.nodeType === 1) {
+            n++;
+            for (const cc of c.children ?? [])
+                stack.push(cc);
+            for (const sr of c.shadowRoots ?? [])
+                stack.push(sr);
+        }
+    }
+    return n;
+}
+/**
+ * In-page walker for the OPEN-shadow case. This is the fast path used when
+ * `pierce: "open"` is requested — no CDP `pierce:true` call needed,
+ * Chromium-version-independent. Returns the same `ShadowTreeEntry[]` shape as
+ * the closed-aware walker so the tool surface is uniform.
+ *
+ * Run as a `Runtime.evaluate` — kept ES5-ish so it survives every Chromium
+ * vintage the project supports.
+ */
+const OPEN_SHADOW_WALK = `function(rootSel, max) {
+  var roots = [];
+  var queue = [];
+  if (rootSel) {
+    try {
+      var seed = document.querySelector(rootSel);
+      if (seed) queue.push(seed);
+    } catch (_) { return { trees: [] }; }
+  } else if (document.documentElement) {
+    queue.push(document.documentElement);
+  }
+  function directText(el) {
+    var t = '';
+    var kids = el.childNodes;
+    for (var i = 0; i < kids.length; i++) {
+      if (kids[i].nodeType === 3) t += kids[i].nodeValue || '';
+    }
+    t = t.replace(/\\s+/g, ' ').trim();
+    if (!t) return null;
+    return t.length > 80 ? t.slice(0, 79) + '…' : t;
+  }
+  function descendantCount(root) {
+    var n = 0;
+    var stack = [];
+    for (var i = 0; i < root.children.length; i++) stack.push(root.children[i]);
+    while (stack.length) {
+      var c = stack.pop();
+      n++;
+      for (var j = 0; j < c.children.length; j++) stack.push(c.children[j]);
+      if (c.shadowRoot) {
+        var skids = c.shadowRoot.children;
+        for (var k = 0; k < skids.length; k++) stack.push(skids[k]);
+      }
+    }
+    return n;
+  }
+  while (queue.length && roots.length < max) {
+    var n = queue.shift();
+    if (n.nodeType !== 1) continue;
+    if (n.shadowRoot) {
+      var children = [];
+      var skids = n.shadowRoot.children;
+      for (var i = 0; i < skids.length; i++) {
+        var c = skids[i];
+        var txt = directText(c);
+        var entry = { tag: c.tagName.toLowerCase(), childCount: c.children.length };
+        if (txt) entry.text = txt;
+        children.push(entry);
+      }
+      roots.push({
+        hostTag: n.tagName.toLowerCase(),
+        mode: 'open',
+        children: children,
+        descendantCount: descendantCount(n.shadowRoot)
+      });
+      var sk = n.shadowRoot.children;
+      for (var j = 0; j < sk.length; j++) queue.push(sk[j]);
+    }
+    var kids = n.children;
+    for (var m = 0; m < kids.length; m++) queue.push(kids[m]);
+  }
+  return { trees: roots };
+}`;
+/** Page-side counterpart for `shadow_trees` when only open shadow piercing
+ *  is needed. Cheaper than the CDP `pierce:true` path (no full-document
+ *  serialisation) and entirely Chromium-version-agnostic. The `hostRef`
+ *  field is filled in by the caller (the registry is server-side). */
+export async function runOpenShadowWalk(cdp, rootSelector, max) {
+    const rootArg = rootSelector ? JSON.stringify(rootSelector) : "null";
+    const expr = `(${OPEN_SHADOW_WALK})(${rootArg}, ${max})`;
+    try {
+        const { result } = (await cdp.send("Runtime.evaluate", {
+            expression: expr,
+            returnByValue: true,
+            awaitPromise: false,
+        }));
+        return result.value?.trees ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Harvest interactive / test-attr-bearing elements from CLOSED shadow roots
+ * only. Open-shadow elements are skipped (the page-side `runDomWalk` already
+ * covers them when `pierce: "open"` or `"closed"`). Returns an empty list +
+ * no warning when CDP's `pierce` path is unavailable.
+ *
+ * The walker reads the CDP-pierced DOM tree and identifies closed-mode
+ * shadow roots; for each, it harvests element-shaped descendants and
+ * extracts the same fields the page-side walker would. Doesn't fetch
+ * computed style / `getBoundingClientRect` — closed shadow can't be
+ * resolved to a Playwright locator anyway, so a bbox would be a lie.
+ */
+export async function harvestClosedShadowElements(cdp, testAttrs, maxEntries) {
+    const { root, warning } = await fetchPiercedDocument(cdp);
+    if (!root)
+        return { entries: [], ...(warning ? { warning } : {}) };
+    const entries = [];
+    // Traverse: find every closed shadow root, then walk its descendants.
+    // We're explicit about NOT entering open shadow roots from CDP because
+    // the page-side walker has already covered them — entering twice would
+    // produce duplicate entries that the registry's element-key would then
+    // collapse, masking which path discovered what (the `[from-dom]` /
+    // `[from-both]` evidence loses its meaning).
+    const stack = [root];
+    while (stack.length && entries.length < maxEntries) {
+        const n = stack.pop();
+        for (const sr of n.shadowRoots ?? []) {
+            if (sr.shadowRootType === "closed") {
+                harvestSubtree(sr, testAttrs, entries, maxEntries);
+            }
+            // Don't descend further into closed shadow via `stack` here — the
+            // recursive harvest already covered nested closed-in-closed cases.
+            // Open shadow inside closed shadow IS picked up by harvestSubtree's
+            // recursion (it walks all element children).
+        }
+        for (const c of n.children ?? [])
+            stack.push(c);
+        if (n.contentDocument)
+            stack.push(n.contentDocument);
+    }
+    return { entries };
+}
+const INTERACTIVE_TAGS = new Set(["button", "a", "input", "select", "textarea"]);
+/** Predicate mirroring PAGE_SCRIPT in dom-walk.ts: a node with a role, a standard
+ *  interactive tag, or an interaction attribute is interactive. */
+function isInteractiveNode(tag, attrMap) {
+    return (attrMap.has("role") ||
+        INTERACTIVE_TAGS.has(tag) ||
+        (tag === "a" && attrMap.has("href")) ||
+        attrMap.has("onclick") ||
+        attrMap.has("tabindex") ||
+        attrMap.get("contenteditable") === "true");
+}
+/** Build a closed-shadow entry. Closed shadow has no addressable selector from
+ *  the page side, so the synthetic `structuralPath` documents the boundary (the
+ *  selectorHint then emits `tier 5` role-only and the agent sees why it isn't
+ *  actionable). */
+function buildClosedShadowEntry(n, tag, attrMap, testIdEntry, index) {
+    return {
+        role: attrMap.get("role") || tag,
+        name: nameFromAttrs(attrMap),
+        testId: testIdEntry?.value ?? "",
+        testIdAttr: testIdEntry?.attr ?? "",
+        tag,
+        id: attrMap.get("id") ?? "",
+        structuralPath: `closed-shadow/${tag}[${index}]`,
+        cssPath: "",
+        closedShadow: true,
+    };
+}
+function harvestSubtree(root, testAttrs, out, max) {
+    const stack = [...(root.children ?? [])];
+    while (stack.length && out.length < max) {
+        const n = stack.pop();
+        if (n.nodeType !== 1)
+            continue;
+        const tag = (n.localName ?? n.nodeName ?? "").toLowerCase();
+        const attrMap = readAttrs(n);
+        const testIdEntry = firstTestAttr(attrMap, testAttrs);
+        if (isInteractiveNode(tag, attrMap) || testIdEntry) {
+            out.push(buildClosedShadowEntry(n, tag, attrMap, testIdEntry, out.length));
+        }
+        pushHarvestChildren(stack, n);
+    }
+}
+/** Push a node's element children + its open/closed shadow-root children onto
+ *  the harvest stack (user-agent shadow roots are skipped). */
+function pushHarvestChildren(stack, n) {
+    for (const c of n.children ?? [])
+        stack.push(c);
+    for (const sr of n.shadowRoots ?? []) {
+        if (sr.shadowRootType === "open" || sr.shadowRootType === "closed") {
+            for (const c of sr.children ?? [])
+                stack.push(c);
+        }
+    }
+}
+function readAttrs(n) {
+    const m = new Map();
+    const a = n.attributes ?? [];
+    for (let i = 0; i < a.length; i += 2)
+        m.set(a[i], a[i + 1] ?? "");
+    return m;
+}
+function firstTestAttr(attrs, testAttrs) {
+    for (const a of testAttrs) {
+        const v = attrs.get(a);
+        if (v)
+            return { attr: a, value: v };
+    }
+    return null;
+}
+function nameFromAttrs(attrs) {
+    const aria = attrs.get("aria-label");
+    if (aria)
+        return aria.trim().slice(0, 120);
+    const title = attrs.get("title");
+    if (title)
+        return title.trim().slice(0, 120);
+    const placeholder = attrs.get("placeholder");
+    if (placeholder)
+        return placeholder.trim().slice(0, 120);
+    return "";
+}

package/dist/page/shortcut.d.ts

@@ -0,0 +1,50 @@
+import type { Page } from "playwright-core";
+import type { RefRegistry } from "./refs.js";
+import { type ActionTarget } from "./locator.js";
+import { ClipboardBuffer, type ClipOp } from "./clipboard.js";
+type ChordKind = "copy" | "cut" | "paste" | "other";
+/** Classify a Playwright chord ("Control+C", "Meta+V", "Control+Shift+K").
+ *  copy/cut/paste require a Control or Meta modifier on c / x / v. */
+export declare function classifyChord(chord: string): ChordKind;
+interface ElSumm {
+    tag: string;
+    id?: string;
+    testId?: string;
+    role?: string;
+    name?: string;
+}
+interface KbEvent {
+    type: string;
+    key: string;
+    defaultPrevented: boolean;
+    target: ElSumm | null;
+}
+export interface ShortcutArgs {
+    keys: string | string[];
+    target?: ActionTarget;
+}
+export interface ShortcutResult {
+    ok: boolean;
+    keys: string[];
+    activeElement: ElSumm | null;
+    events: KbEvent[];
+    /** true when a copy/cut/paste event fired OR the app called preventDefault
+     *  on a keydown — i.e. the app actually responded to the shortcut. */
+    handled: boolean;
+    clipboard?: {
+        op: ClipOp | "paste";
+        /** chars captured into the per-session buffer (copy/cut). */
+        capturedChars?: number;
+        /** chars written to the OS clipboard from the per-session buffer (paste). */
+        chars?: number;
+        fromSessionBuffer?: boolean;
+        osSync: boolean;
+        osTool: string;
+    };
+    clipboardNote?: string;
+}
+export declare function runShortcut(page: Page, refs: RefRegistry, args: ShortcutArgs, opts: {
+    clipboardEnabled: boolean;
+    clipboard: ClipboardBuffer;
+}): Promise<ShortcutResult>;
+export {};

package/dist/page/shortcut.js

@@ -0,0 +1,147 @@
+// `shortcut` — keyboard chord / multi-step sequence with handled-observability.
+//
+// `press` drives one combo, but (a) multi-step shortcuts are unergonomic and
+// (b) the agent can't tell whether the *app* handled the shortcut or what was
+// focused — copy/cut/paste especially are opaque (internal vs OS clipboard).
+// This dispatches a chord or an ordered sequence and returns a structured
+// observability block: the active element, which keydown/copy/cut/paste
+// listeners fired, and whether the app called preventDefault.
+//
+// Clipboard (capability `clipboard`, off by default) is per-session and
+// transactional — see clipboard.ts. Observability works without the
+// capability; only the OS-clipboard read/write + per-session buffer engage
+// when it's enabled. No agent JS (fixed server-injected trace script).
+import { locatorFor } from "./locator.js";
+import { osClipboardWrite } from "./clipboard.js";
+/** Classify a Playwright chord ("Control+C", "Meta+V", "Control+Shift+K").
+ *  copy/cut/paste require a Control or Meta modifier on c / x / v. */
+export function classifyChord(chord) {
+    const parts = chord.split("+").map((s) => s.trim().toLowerCase());
+    const key = parts[parts.length - 1];
+    const mod = parts.slice(0, -1);
+    const accel = mod.includes("control") || mod.includes("meta");
+    if (!accel)
+        return "other";
+    if (key === "c")
+        return "copy";
+    if (key === "x")
+        return "cut";
+    if (key === "v")
+        return "paste";
+    return "other";
+}
+const ELSUMM = `function (el) {
+  if (!el || !el.tagName) return null;
+  return {
+    tag: el.tagName.toLowerCase(),
+    id: el.id || undefined,
+    testId: el.getAttribute ? (el.getAttribute('data-testid') || undefined) : undefined,
+    role: el.getAttribute ? (el.getAttribute('role') || undefined) : undefined,
+    name: (el.getAttribute && el.getAttribute('aria-label')) ||
+          (el.textContent ? el.textContent.trim().slice(0, 40) : undefined) || undefined,
+  };
+}`;
+const INSTALL_TRACE = `(() => {
+  var summ = ${ELSUMM};
+  var W = window;
+  var st = { events: [], active: summ(document.activeElement) };
+  W.__browx_kbt = st;
+  var rec = function (type) {
+    return function (e) {
+      st.events.push({ type: type, key: e.key, defaultPrevented: !!e.defaultPrevented, target: summ(e.target) });
+    };
+  };
+  var L = { keydown: rec('keydown'), copy: rec('copy'), cut: rec('cut'), paste: rec('paste') };
+  W.__browx_kbt_l = L;
+  // bubble phase on document: runs after element/app handlers, so
+  // defaultPrevented reflects whether the app handled the event.
+  document.addEventListener('keydown', L.keydown, false);
+  document.addEventListener('copy', L.copy, false);
+  document.addEventListener('cut', L.cut, false);
+  document.addEventListener('paste', L.paste, false);
+})()`;
+const READ_TRACE = `(() => {
+  var s = window.__browx_kbt || { events: [], active: null };
+  return { events: s.events, active: s.active };
+})()`;
+const CLEANUP_TRACE = `(() => {
+  var L = window.__browx_kbt_l;
+  if (L) {
+    document.removeEventListener('keydown', L.keydown, false);
+    document.removeEventListener('copy', L.copy, false);
+    document.removeEventListener('cut', L.cut, false);
+    document.removeEventListener('paste', L.paste, false);
+  }
+  delete window.__browx_kbt; delete window.__browx_kbt_l;
+})()`;
+const READ_SELECTION = `(() => {
+  var a = document.activeElement;
+  if (a && (a.tagName === 'INPUT' || a.tagName === 'TEXTAREA') && typeof a.selectionStart === 'number') {
+    return a.value.substring(a.selectionStart, a.selectionEnd) || a.value || '';
+  }
+  var s = window.getSelection && window.getSelection();
+  return s ? s.toString() : '';
+})()`;
+export async function runShortcut(page, refs, args, opts) {
+    const chords = Array.isArray(args.keys) ? args.keys : [args.keys];
+    if (args.target) {
+        try {
+            await locatorFor(page, refs, args.target).focus({ timeout: 2000 });
+        }
+        catch {
+            /* best-effort focus; page-level shortcut still valid */
+        }
+    }
+    await page.evaluate(INSTALL_TRACE).catch(() => undefined);
+    let clip;
+    for (const chord of chords) {
+        if (classifyChord(chord) === "paste" && opts.clipboardEnabled) {
+            const buf = opts.clipboard.get();
+            if (buf) {
+                // transactional: set the OS clipboard from THIS session's buffer
+                // immediately before the paste keystroke, so the app pastes this
+                // session's content regardless of concurrent sessions.
+                const w = await osClipboardWrite(buf.text);
+                clip = {
+                    op: "paste",
+                    chars: buf.text.length,
+                    fromSessionBuffer: true,
+                    osSync: w.ok,
+                    osTool: w.tool,
+                };
+            }
+        }
+        await page.keyboard.press(chord).catch(() => undefined);
+    }
+    const copyChord = chords.find((c) => classifyChord(c) === "copy" || classifyChord(c) === "cut");
+    if (copyChord && opts.clipboardEnabled) {
+        // READ_SELECTION returns a string by construction (see definition above);
+        // narrow before coercion so we don't `[object Object]` if the page eval
+        // ever returns a non-primitive.
+        const raw = await page.evaluate(READ_SELECTION).catch(() => "");
+        const sel = typeof raw === "string" ? raw : "";
+        const op = classifyChord(copyChord);
+        opts.clipboard.set(sel, op);
+        const w = await osClipboardWrite(sel);
+        clip = { op, capturedChars: sel.length, osSync: w.ok, osTool: w.tool };
+    }
+    const trace = (await page.evaluate(READ_TRACE).catch(() => ({ events: [], active: null })));
+    await page.evaluate(CLEANUP_TRACE).catch(() => undefined);
+    const handled = trace.events.some((e) => e.type === "copy" ||
+        e.type === "cut" ||
+        e.type === "paste" ||
+        (e.type === "keydown" && e.defaultPrevented));
+    return {
+        ok: true,
+        keys: chords,
+        activeElement: trace.active,
+        events: trace.events,
+        handled,
+        ...(clip ? { clipboard: clip } : {}),
+        ...(opts.clipboardEnabled || !chords.some((c) => classifyChord(c) !== "other")
+            ? {}
+            : {
+                clipboardNote: "clipboard capability disabled — keys dispatched and observed, but no OS clipboard read/write and no per-session buffer update (enable BROWX_CAPABILITIES=…,clipboard)",
+            }),
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { A11yNode } from "./a11y.js";
+import type { RefRegistry } from "./refs.js";
+import type { ComposedSnapshot, ComposeOptions } from "./compose.js";
+import type { SnapshotSubstrate } from "./snapshot-substrate.js";
+/** The minimal IO the Safari substrate needs — run a page-context script
+ *  (`execute/sync` body + args → value) and read the current document URL. The
+ *  SafaridriverHybridAdapter supplies this over its `SafariWebDriverClient`. */
+export interface SafariSnapshotIO {
+    /** Run a function-BODY script with args mapped to `arguments`, returning its
+     *  value (the WebDriver `execute/sync` contract). */
+    exec(scriptBody: string, args: unknown[]): Promise<unknown>;
+    /** The current document URL (the Classic substitute for `page.url()`). */
+    currentUrl(): Promise<string>;
+}
+/** 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 declare class SafariClassicSnapshotSubstrate implements SnapshotSubstrate {
+    private readonly io;
+    readonly engine = "safari";
+    constructor(io: SafariSnapshotIO);
+    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, identical to the Playwright substrate's root. */
+    private makeRoot;
+}