browxai 0.7.0

package/dist/page/asset-export.js

@@ -0,0 +1,376 @@
+// `asset_export` — filter the session's network ring and persist matching
+// responses to a workspace-rooted directory.
+//
+// Design posture (mirrors `downloads.ts`):
+//   - **Workspace-rooted paths only.** Exports land under
+//     `$BROWX_WORKSPACE/assets/<sessionId>-<ISO>/` by default; an explicit
+//     `intoDir` is resolved INSIDE the workspace (escape rejected).
+//   - **Filename sanitisation** is the same posture as `downloads.sanitiseFilename`
+//     — no path separators, no NUL/control bytes, no leading dots, length-capped,
+//     all-stripped names fall back to `"asset"`. Collisions are resolved by
+//     appending `-N` to the stem so a second `logo.png` becomes `logo-1.png`.
+//   - **Bounded.** Caller can raise `maxCount` / `maxBytes` but never above a
+//     hard ceiling — a misconfigured filter on a long-running session must not
+//     fill the workspace. Defaults: 10000 files / 500 MiB.
+//   - **CORS tolerance.** When the response body isn't in the renderer's cache
+//     (CDP `Network.getResponseBody` returns "not available" — bodies are
+//     short-lived) we fall back to a same-origin in-page `fetch()` for the
+//     original URL. Cross-origin URLs without CORS headers may reject; we record
+//     the failure on `droppedCount` and keep going.
+//   - **No new capability.** Reuses `file-io` (same as `upload_file` /
+//     `downloads_capture` / `download_get`).
+import { mkdirSync, writeFileSync, statSync } from "node:fs";
+import { join, resolve, sep, basename } from "node:path";
+import { log } from "../util/logging.js";
+// ---------- caps & defaults --------------------------------------------------
+/** Hard ceiling on the per-call file count cap — even a caller-supplied
+ *  `maxCount` is clamped to this. Bounds a runaway export on a long session. */
+export const ASSET_EXPORT_HARD_MAX_COUNT = 50_000;
+/** Hard ceiling on the per-call byte cap. */
+export const ASSET_EXPORT_HARD_MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2 GiB
+/** Default per-call file count cap. Caller can override up to the hard max. */
+export const ASSET_EXPORT_DEFAULT_MAX_COUNT = 10_000;
+/** Default per-call byte cap (500 MiB). */
+export const ASSET_EXPORT_DEFAULT_MAX_BYTES = 500 * 1024 * 1024;
+/** Maximum bytes for a single response body — same posture as
+ *  `fetchResponseBody`'s default. Larger responses are skipped with a
+ *  warning so one huge video can't blow the whole export. */
+const SINGLE_BODY_MAX_BYTES = 64 * 1024 * 1024; // 64 MiB
+/** Cap on the on-disk filename length, accounting for the `-N` collision
+ *  suffix room and 255-byte filesystem name limits. */
+const FILENAME_MAX_CHARS = 200;
+// ---------- pure helpers (exported for unit tests) ---------------------------
+/** Build the regex once at the boundary. Throws `Error` on invalid source so
+ *  the tool layer surfaces a structured failure instead of a runtime crash
+ *  deep inside the loop. */
+export function compileUrlPattern(src) {
+    if (!src)
+        return null;
+    try {
+        return new RegExp(src, "i");
+    }
+    catch (err) {
+        throw new Error(`asset_export: invalid \`filter.urlPattern\` — ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Status gate: an explicit allow-list, else default 2xx. */
+function statusMatches(entry, status) {
+    if (entry.status === undefined)
+        return false;
+    return status ? status.has(entry.status) : entry.status >= 200 && entry.status < 300;
+}
+/** MIME gate: substring on the captured Content-Type; no mime info → reject
+ *  (an entry that never reported a Content-Type can't be classified). */
+function mimeMatches(entry, mime) {
+    if (!mime || mime.length === 0)
+        return true;
+    if (!entry.mimeType)
+        return false;
+    const lower = entry.mimeType.toLowerCase();
+    return mime.some((m) => lower.includes(m.toLowerCase()));
+}
+/** Byte-bound gate: only enforced when bytes have landed (still-in-flight
+ *  entries are admitted here; the fetch step counts actual bytes). */
+function bytesMatch(entry, minBytes, maxBytes) {
+    if (typeof entry.bytes !== "number")
+        return true;
+    if (typeof minBytes === "number" && entry.bytes < minBytes)
+        return false;
+    if (typeof maxBytes === "number" && entry.bytes > maxBytes)
+        return false;
+    return true;
+}
+/** Filter a single `NetworkEntry` against a normalised filter. Pure — uses only
+ *  the entry's captured metadata; no I/O. Exported so the test suite can pin
+ *  every branch without spinning a NetworkBuffer. */
+export function matchesFilter(entry, filter) {
+    if (!statusMatches(entry, filter.status))
+        return false;
+    if (!mimeMatches(entry, filter.mime))
+        return false;
+    if (filter.urlPattern && !filter.urlPattern.test(entry.url))
+        return false;
+    return bytesMatch(entry, filter.minBytes, filter.maxBytes);
+}
+/** Sanitise a URL-derived asset filename. Same posture as
+ *  `downloads.sanitiseFilename`:
+ *    - strip path separators (`/`, `\`) and NUL/control bytes — collapses any
+ *      traversal attempt to a flat filename.
+ *    - collapse runs of dots so the literal `..` substring never survives.
+ *    - strip leading dots so we don't write a hidden file.
+ *    - cap length (leaves room for a `-N` collision suffix).
+ *    - empty / all-stripped → fall back to `"asset"`.
+ *  Exported for unit tests. */
+export function sanitiseAssetFilename(raw) {
+    if (typeof raw !== "string")
+        return "asset";
+    // strip NUL + control bytes (0x00-0x1f, 0x7f) and path separators.
+    // eslint-disable-next-line no-control-regex
+    let name = raw.replace(/[\x00-\x1f\x7f/\\]/g, "_");
+    // collapse runs of dots ("../.." → ".") so the literal substring `..`
+    // never survives — eliminates "looks-like-traversal" even though the
+    // lack of separators already makes traversal impossible.
+    name = name.replace(/\.{2,}/g, ".");
+    // collapse repeated underscores from the strip pass.
+    name = name.replace(/_+/g, "_");
+    // strip leading dots so we don't write a hidden file.
+    name = name.replace(/^\.+/, "");
+    // strip leading/trailing whitespace, dots, underscores — these only exist
+    // because of the strip passes above.
+    name = name.replace(/^[._\s]+|[._\s]+$/g, "");
+    if (name.length > FILENAME_MAX_CHARS)
+        name = name.slice(0, FILENAME_MAX_CHARS);
+    if (!name)
+        return "asset";
+    return name;
+}
+/** Derive a base filename from a URL: take the last path segment, decode
+ *  percent-encoding, drop a query string. Falls back to `"asset"` when the
+ *  URL has no usable basename (e.g. `https://example.com/`). Exported for
+ *  unit tests. */
+export function filenameFromUrl(url) {
+    let pathname;
+    try {
+        pathname = new URL(url).pathname;
+    }
+    catch {
+        pathname = url;
+    }
+    // basename strips the trailing slash; pathname like `/` → `""`.
+    let base = basename(pathname);
+    if (!base)
+        base = "asset";
+    try {
+        base = decodeURIComponent(base);
+    }
+    catch {
+        // malformed percent-encoding — keep the raw form, sanitisation handles it.
+    }
+    return sanitiseAssetFilename(base);
+}
+/** Resolve a collision by appending `-N` before the extension. Pure; uses
+ *  the supplied `Set` of already-used names. Exported for unit tests. */
+export function resolveCollision(name, used) {
+    if (!used.has(name))
+        return name;
+    const dot = name.lastIndexOf(".");
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    const ext = dot > 0 ? name.slice(dot) : "";
+    for (let i = 1; i < 1_000_000; i++) {
+        const candidate = `${stem}-${i}${ext}`;
+        if (!used.has(candidate))
+            return candidate;
+    }
+    // 1M collisions on the same stem is effectively impossible; if it happens,
+    // disambiguate with the current timestamp + a random tail.
+    return `${stem}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`;
+}
+/** ISO-8601 timestamp safe for use in a directory name (`:` replaced with `-`). */
+export function timestampForDir(d = new Date()) {
+    return d.toISOString().replace(/[:.]/g, "-");
+}
+// ---------- workspace path safety -------------------------------------------
+/** Resolve the export dir. Default: `assets/<sessionId>-<ISO>/`. Caller-
+ *  supplied `intoDir` is resolved INSIDE `workspaceRoot`; any escape throws
+ *  the same structured error as `upload_file` / `pdf_save`. */
+export function resolveAssetExportDir(workspaceRoot, sessionId, intoDir) {
+    const rel = intoDir ?? `assets/${sessionId}-${timestampForDir()}`;
+    const resolved = resolve(workspaceRoot, rel);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`asset_export: \`intoDir\` must resolve inside $BROWX_WORKSPACE — got "${rel}". ` +
+            `Use a workspace-relative path.`);
+    }
+    return resolved;
+}
+// ---------- body fetch -------------------------------------------------------
+/** Try CDP `Network.getResponseBody` first; on "not available" fall back to
+ *  an in-page `fetch()` against the original URL. Returns the bytes (decoded)
+ *  + the effective content-type, or an `{ error }` envelope when both attempts
+ *  fail. The CORS caveat: cross-origin URLs without permissive CORS headers
+ *  will reject the in-page fetch; that's surfaced as `droppedCount` by the
+ *  caller, not a crash. */
+export async function fetchBodyBytes(cdp, page, entry) {
+    // First try the renderer's cached body — short-lived but free.
+    if (entry.requestId) {
+        try {
+            const { body, base64Encoded } = await cdp.send("Network.getResponseBody", {
+                requestId: entry.requestId,
+            });
+            const buf = base64Encoded ? Buffer.from(body, "base64") : Buffer.from(body, "utf8");
+            const out = { ok: true, bytes: buf };
+            if (entry.mimeType !== undefined)
+                out.mimeType = entry.mimeType;
+            return out;
+        }
+        catch {
+            // body discarded by the renderer — fall through to the in-page fetch.
+        }
+    }
+    // Fallback: in-page `fetch()`. CORS caveat — cross-origin URLs without
+    // permissive headers will throw; we report it as a drop, not a crash.
+    try {
+        const result = await page.evaluate(async (url) => {
+            try {
+                const res = await fetch(url);
+                const buf = await res.arrayBuffer();
+                const arr = new Uint8Array(buf);
+                // Encode as base64 inside the page so the bridge marshalling is
+                // string-only (avoids the structured-clone size cliff on big buffers).
+                let bin = "";
+                const chunk = 0x8000;
+                for (let i = 0; i < arr.length; i += chunk) {
+                    bin += String.fromCharCode(...arr.subarray(i, Math.min(i + chunk, arr.length)));
+                }
+                return {
+                    ok: true,
+                    base64: btoa(bin),
+                    mimeType: res.headers.get("content-type") ?? undefined,
+                };
+            }
+            catch (e) {
+                return { ok: false, error: e instanceof Error ? e.message : String(e) };
+            }
+        }, entry.url);
+        if (!result.ok)
+            return { ok: false, error: `in-page fetch failed: ${result.error}` };
+        const out = {
+            ok: true,
+            bytes: Buffer.from(result.base64, "base64"),
+        };
+        const mt = result.mimeType ?? entry.mimeType;
+        if (mt !== undefined)
+            out.mimeType = mt;
+        return out;
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+/** Persist one fetched body to disk, appending its manifest entry (or recording
+ *  a drop / workspace-escape refusal). Returns "break" only on a maxBytes stop. */
+function persistAssetBody(st, entry, fetched) {
+    if (st.runningBytes + fetched.bytes.length > st.maxBytes) {
+        st.warnings.push(`maxBytes (${st.maxBytes}) would be exceeded by ${entry.url} (${fetched.bytes.length} bytes); stopping export`);
+        return "break";
+    }
+    const finalName = resolveCollision(filenameFromUrl(entry.url), st.used);
+    st.used.add(finalName);
+    // Defence in depth — the sanitised name has no separators, so the join can't
+    // escape `intoDir`; verify anyway ($BROWX_WORKSPACE-rooted by construction).
+    const resolved = resolve(join(st.intoDir, finalName));
+    if (resolved !== st.intoDir && !resolved.startsWith(st.intoDir + sep)) {
+        st.droppedCount += 1;
+        st.warnings.push(`refused to write outside intoDir: ${entry.url}`);
+        return "continue";
+    }
+    try {
+        writeFileSync(resolved, fetched.bytes);
+    }
+    catch (err) {
+        st.droppedCount += 1;
+        st.warnings.push(`write failed for ${entry.url}: ${err instanceof Error ? err.message : String(err)}`);
+        return "continue";
+    }
+    let sizeBytes = fetched.bytes.length;
+    try {
+        sizeBytes = statSync(resolved).size;
+    }
+    catch {
+        /* best-effort */
+    }
+    st.runningBytes += sizeBytes;
+    const m = { url: entry.url, sizeBytes, savedAs: finalName };
+    const mt = fetched.mimeType ?? entry.mimeType;
+    if (mt !== undefined)
+        m.mime = mt;
+    if (entry.status !== undefined)
+        m.status = entry.status;
+    st.manifest.push(m);
+    return "continue";
+}
+/** Process one matched entry: cap checks → fetch → size checks → persist. */
+async function processAssetEntry(deps, st, entry) {
+    st.matchedCount += 1;
+    if (st.manifest.length >= st.maxCount) {
+        st.warnings.push(`maxCount (${st.maxCount}) reached — ${st.matchedCount - st.manifest.length} additional matches were not persisted`);
+        return "break";
+    }
+    if (typeof entry.bytes === "number" && entry.bytes > SINGLE_BODY_MAX_BYTES) {
+        st.droppedCount += 1;
+        st.warnings.push(`skipped ${entry.url} — single-response size (${entry.bytes} bytes) exceeds SINGLE_BODY_MAX_BYTES (${SINGLE_BODY_MAX_BYTES})`);
+        return "continue";
+    }
+    const fetched = await fetchBodyBytes(deps.cdp, deps.page, entry);
+    if (!fetched.ok) {
+        st.droppedCount += 1;
+        st.warnings.push(`skipped ${entry.url} — ${fetched.error}`);
+        return "continue";
+    }
+    if (fetched.bytes.length > SINGLE_BODY_MAX_BYTES) {
+        st.droppedCount += 1;
+        st.warnings.push(`skipped ${entry.url} — fetched body (${fetched.bytes.length} bytes) exceeds SINGLE_BODY_MAX_BYTES (${SINGLE_BODY_MAX_BYTES})`);
+        return "continue";
+    }
+    return persistAssetBody(st, entry, fetched);
+}
+export async function assetExport(deps, args) {
+    const filter = args.filter ?? {};
+    const urlPattern = compileUrlPattern(filter.urlPattern);
+    const statusSet = filter.status && filter.status.length > 0 ? new Set(filter.status) : null;
+    const intoDir = resolveAssetExportDir(deps.workspaceRoot, deps.sessionId, args.intoDir);
+    // `intoDir` is workspace-rooted by construction: `resolveAssetExportDir`
+    // resolves it inside `workspaceRoot` ($BROWX_WORKSPACE) and rejects any escape.
+    // Every write below is under this dir, never cwd.
+    mkdirSync(intoDir, { recursive: true });
+    const all = deps.buffer.iter();
+    const totalCount = all.length;
+    const st = {
+        intoDir,
+        maxCount: Math.min(Math.max(1, args.maxCount ?? ASSET_EXPORT_DEFAULT_MAX_COUNT), ASSET_EXPORT_HARD_MAX_COUNT),
+        maxBytes: Math.min(Math.max(1, args.maxBytes ?? ASSET_EXPORT_DEFAULT_MAX_BYTES), ASSET_EXPORT_HARD_MAX_BYTES),
+        warnings: [],
+        manifest: [],
+        used: new Set(),
+        matchedCount: 0,
+        droppedCount: 0,
+        runningBytes: 0,
+    };
+    for (const entry of all) {
+        const matched = matchesFilter(entry, {
+            mime: filter.mime,
+            urlPattern,
+            minBytes: filter.minBytes,
+            maxBytes: filter.maxBytes,
+            status: statusSet,
+        });
+        if (!matched)
+            continue;
+        if ((await processAssetEntry(deps, st, entry)) === "break")
+            break;
+    }
+    const { warnings, manifest, matchedCount, droppedCount } = st;
+    // Write `_manifest.json` last so a crash mid-export doesn't leave a
+    // misleading manifest pointing at files that weren't all written.
+    // `intoDir` is workspace-rooted ($BROWX_WORKSPACE / workspaceRoot) by
+    // construction — see `resolveAssetExportDir` above.
+    try {
+        const manifestPath = join(intoDir, "_manifest.json");
+        writeFileSync(manifestPath, JSON.stringify({ intoDir, manifest }, null, 2));
+    }
+    catch (err) {
+        log.warn("asset_export: writing _manifest.json failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        warnings.push(`writing _manifest.json failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+        ok: true,
+        intoDir,
+        totalCount,
+        matchedCount,
+        persistedCount: manifest.length,
+        droppedCount,
+        manifest,
+        warnings,
+    };
+}

package/dist/page/await_network.d.ts

@@ -0,0 +1,16 @@
+export interface NetworkMatch {
+    /** case-insensitive substring of the request URL. */
+    urlPattern?: string;
+    /** exact HTTP method (case-insensitive). */
+    method?: string;
+    /** exact response status. */
+    status?: number;
+}
+export interface ResponseLike {
+    url: string;
+    method: string;
+    status: number;
+}
+/** Pure predicate — does this response satisfy the match? An empty match
+ *  matches nothing (refuse to "wait for anything"). Exported for tests. */
+export declare function matchesResponse(resp: ResponseLike, match: NetworkMatch): boolean;

package/dist/page/await_network.js

@@ -0,0 +1,23 @@
+// act_and_wait_for_network matcher.
+//
+// `ActionResult.network` only sees requests inside the action window; async
+// SPAs fire follow-up requests after it. This lets a caller drive an action
+// and wait for a *specific* request to complete, with a precise match.
+/** Pure predicate — does this response satisfy the match? An empty match
+ *  matches nothing (refuse to "wait for anything"). Exported for tests. */
+export function matchesResponse(resp, match) {
+    if (match.urlPattern === undefined && match.method === undefined && match.status === undefined) {
+        return false;
+    }
+    if (match.urlPattern !== undefined &&
+        !resp.url.toLowerCase().includes(match.urlPattern.toLowerCase())) {
+        return false;
+    }
+    if (match.method !== undefined && resp.method.toUpperCase() !== match.method.toUpperCase()) {
+        return false;
+    }
+    if (match.status !== undefined && resp.status !== match.status) {
+        return false;
+    }
+    return true;
+}

package/dist/page/bbox.d.ts

@@ -0,0 +1,37 @@
+import type { CDPSession, Frame, Page } from "playwright-core";
+export interface VisibleRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Compute the visible-rect bbox of a CDP-known DOM node. Returns null when the
+ * element is fully clipped (offscreen, inside a collapsed overflow container,
+ * detached). The caller surfaces null as `bbox: null, clipped: true`.
+ */
+export declare function visibleRect(cdp: CDPSession, backendDOMNodeId: number): Promise<VisibleRect | null>;
+/**
+ * Playwright locator-based bounding box, used as a *fallback* when the CDP
+ * `visibleRect` path returns null. On attached/BYOB Chromes the CDP
+ * `DOM.resolveNode` → `Runtime.callFunctionOn` rect path can spuriously fail
+ * for DOM-walk-sourced nodes (no live backend node, cross-frame quirks),
+ * producing a bogus `bbox:null` → `off-screen` for an element that is in fact
+ * rendered. Playwright's own `boundingBox()` resolves the element through the
+ * locator engine and reports its real rendered box; a non-empty box means
+ * "this is on the page" regardless of what the CDP path said. Best-effort:
+ * any error / empty box → null (the caller then treats it as truly clipped).
+ *
+ * `opts.timeoutMs` caps Playwright's auto-wait so a probe call against an
+ * unmatched selector fails fast instead of pinning the default `actionTimeout`
+ * (30 s). This is the perf hot-path for `find()` candidate evaluation — find()
+ * emits locator hints derived from DOM-walk-sourced roles that don't always
+ * map to a real Playwright role selector (e.g. `role=a` when the tag is `<a>`),
+ * and the bounding-box probe on those mismatched hints would otherwise hang
+ * for the full action-timeout window per candidate. Default cap is 500 ms —
+ * the wedge class is now a known hazard on every call site; per-caller opt-in
+ * (e.g. `{ timeoutMs: 1000 }`) raises it when the caller can absorb the wait.
+ */
+export declare function locatorBoundingBox(root: Page | Frame, selector: string, opts?: {
+    timeoutMs?: number;
+}): Promise<VisibleRect | null>;

package/dist/page/bbox.js

@@ -0,0 +1,115 @@
+// Visible-rect bbox computation — .
+//
+// `getBoundingClientRect()` intersected with each ancestor whose `overflow` isn't
+// `visible`, then with the viewport. Returns null + clipped:true when the result
+// is empty. Same definition site-docs's runtime computes, so calibration-time
+// bbox == execution-time bbox for the same selector.
+// Function source (runs in page context). Stringified so we can pass it to
+// `Runtime.callFunctionOn` with the resolved DOM node as `this`.
+//
+// clipping is *only* triggered by `overflow: hidden` or `overflow: clip`.
+// `overflow: auto` / `scroll` are scrollable, **not** clipping — the element's
+// `getBoundingClientRect()` already accounts for the current scroll position,
+// so the rect reflects the element's actual visible position. The previous
+// check treated any non-`visible` overflow as clipping, which collapsed bboxes
+// to zero on attached Chromes whose body/html or layout containers used
+// `overflow: auto` (common pattern). Reported by the non-Claude verification
+// run: visible elements returned `bbox: null` + `actionable: "off-screen"`.
+const VISIBLE_RECT_FN = `function () {
+  function r(rect) { return { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom }; }
+  function clips(cs) {
+    return cs.overflow === 'hidden' || cs.overflow === 'clip'
+        || cs.overflowX === 'hidden' || cs.overflowX === 'clip'
+        || cs.overflowY === 'hidden' || cs.overflowY === 'clip';
+  }
+  let b = r(this.getBoundingClientRect());
+  let n = this.parentElement;
+  while (n) {
+    const cs = getComputedStyle(n);
+    if (clips(cs)) {
+      const pr = r(n.getBoundingClientRect());
+      b = {
+        left:   Math.max(b.left,   pr.left),
+        top:    Math.max(b.top,    pr.top),
+        right:  Math.min(b.right,  pr.right),
+        bottom: Math.min(b.bottom, pr.bottom),
+      };
+    }
+    n = n.parentElement;
+  }
+  // Viewport. Fall back to documentElement / document.body dims when innerWidth/
+  // innerHeight read as zero (some attached contexts report bogus window metrics
+  // before first paint).
+  var vw = window.innerWidth || (document.documentElement && document.documentElement.clientWidth) || 0;
+  var vh = window.innerHeight || (document.documentElement && document.documentElement.clientHeight) || 0;
+  if (!vw || !vh) {
+    // Last resort: skip viewport intersection — return the un-clipped client rect.
+    // Better to over-report bbox than to under-report (which currently produces
+    // bogus 'off-screen' actionability).
+    if (b.right <= b.left || b.bottom <= b.top) return null;
+    return { x: b.left, y: b.top, width: b.right - b.left, height: b.bottom - b.top };
+  }
+  b = {
+    left:   Math.max(b.left,   0),
+    top:    Math.max(b.top,    0),
+    right:  Math.min(b.right,  vw),
+    bottom: Math.min(b.bottom, vh),
+  };
+  if (b.right <= b.left || b.bottom <= b.top) return null;
+  return { x: b.left, y: b.top, width: b.right - b.left, height: b.bottom - b.top };
+}`;
+/**
+ * Compute the visible-rect bbox of a CDP-known DOM node. Returns null when the
+ * element is fully clipped (offscreen, inside a collapsed overflow container,
+ * detached). The caller surfaces null as `bbox: null, clipped: true`.
+ */
+export async function visibleRect(cdp, backendDOMNodeId) {
+    try {
+        const { object } = (await cdp.send("DOM.resolveNode", { backendNodeId: backendDOMNodeId }));
+        if (!object?.objectId)
+            return null;
+        const { result } = (await cdp.send("Runtime.callFunctionOn", {
+            objectId: object.objectId,
+            functionDeclaration: VISIBLE_RECT_FN,
+            returnByValue: true,
+        }));
+        return result.value ?? null;
+    }
+    catch {
+        // Node detached, no live DOM, etc. Treat as clipped.
+        return null;
+    }
+}
+/**
+ * Playwright locator-based bounding box, used as a *fallback* when the CDP
+ * `visibleRect` path returns null. On attached/BYOB Chromes the CDP
+ * `DOM.resolveNode` → `Runtime.callFunctionOn` rect path can spuriously fail
+ * for DOM-walk-sourced nodes (no live backend node, cross-frame quirks),
+ * producing a bogus `bbox:null` → `off-screen` for an element that is in fact
+ * rendered. Playwright's own `boundingBox()` resolves the element through the
+ * locator engine and reports its real rendered box; a non-empty box means
+ * "this is on the page" regardless of what the CDP path said. Best-effort:
+ * any error / empty box → null (the caller then treats it as truly clipped).
+ *
+ * `opts.timeoutMs` caps Playwright's auto-wait so a probe call against an
+ * unmatched selector fails fast instead of pinning the default `actionTimeout`
+ * (30 s). This is the perf hot-path for `find()` candidate evaluation — find()
+ * emits locator hints derived from DOM-walk-sourced roles that don't always
+ * map to a real Playwright role selector (e.g. `role=a` when the tag is `<a>`),
+ * and the bounding-box probe on those mismatched hints would otherwise hang
+ * for the full action-timeout window per candidate. Default cap is 500 ms —
+ * the wedge class is now a known hazard on every call site; per-caller opt-in
+ * (e.g. `{ timeoutMs: 1000 }`) raises it when the caller can absorb the wait.
+ */
+export async function locatorBoundingBox(root, selector, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 500;
+    try {
+        const box = await root.locator(selector).first().boundingBox({ timeout: timeoutMs });
+        if (!box || box.width <= 0 || box.height <= 0)
+            return null;
+        return { x: box.x, y: box.y, width: box.width, height: box.height };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/page/canvas-capture.d.ts

@@ -0,0 +1,82 @@
+export type CanvasFormat = "png" | "webgl-framebuffer" | "2d-imagedata";
+export interface CanvasCaptureArgs {
+    /** Stable ref of the target `<canvas>` element (from snapshot/find).
+     *  Omit to capture the first `<canvas>` in the document. */
+    ref?: string;
+    /** Optional CSS selector used as a fallback when `ref` lookup fails
+     *  (or for callers who want a raw selector path). Honoured by the
+     *  page-side capture function. */
+    selector?: string;
+    /** Output format. */
+    format: CanvasFormat;
+}
+export interface CanvasCapturePngResult {
+    ok: true;
+    format: "png";
+    /** Base64-encoded PNG bytes. */
+    contentBase64: string;
+    byteLength: number;
+    width: number;
+    height: number;
+}
+export interface CanvasCaptureRgbaResult {
+    ok: true;
+    format: "2d-imagedata" | "webgl-framebuffer";
+    /** Base64-encoded RGBA byte array (row-major, top-left origin for
+     *  2d-imagedata; for webgl-framebuffer, the page-side capture flips
+     *  the readPixels result into top-left order to match imagedata's
+     *  convention, so downstream `canvas_diff` math is consistent). */
+    contentBase64: string;
+    width: number;
+    height: number;
+    channelCount: 4;
+    /** Only set for `webgl-framebuffer` so the caller can tell the two
+     *  RGBA formats apart on result. */
+    isWebGL?: true;
+}
+export type CanvasCaptureResult = CanvasCapturePngResult | CanvasCaptureRgbaResult | {
+    ok: false;
+    error: string;
+    code?: string;
+};
+/** Max canvas dimensions accepted by `canvas_capture`. Larger canvases
+ *  refuse with a structured error rather than allocating a giant byte
+ *  payload. 16384 matches Chromium's `max_texture_size` for most
+ *  hardware — a `<canvas>` larger than this would not paint correctly
+ *  anyway. */
+export declare const CANVAS_MAX_DIMENSION = 16384;
+/** Page-side raw-capture return — the loose discriminated union the page
+ *  function produces (every field optional so it serializes cleanly across
+ *  the CDP boundary). The host side narrows it back into CanvasCaptureResult. */
+export interface PageCaptureRaw {
+    ok: boolean;
+    format?: CanvasFormat;
+    contentBase64?: string;
+    byteLength?: number;
+    width?: number;
+    height?: number;
+    channelCount?: number;
+    isWebGL?: boolean;
+    error?: string;
+    code?: string;
+}
+/** Page-side capture function — REAL function literal (NOT stringified).
+ *  Playwright's `page.evaluate(fn, arg)` serializes the source + invokes
+ *  in-page with the arg. Mirror of the pattern used in `dom_export` /
+ *  `element_export` / `overflow_detect` — a stringified arrow function
+ *  evaluates to the function value uncalled, which CDP can't serialize.
+ *
+ *  Returns a structured discriminated union (mirror of CanvasCaptureResult)
+ *  so the host side can pass it straight back. */
+export declare const PAGE_CAPTURE_FN: (args: {
+    ref?: string;
+    selector?: string;
+    format: CanvasFormat;
+    maxDimension: number;
+}) => PageCaptureRaw;
+/** Thin adapter so unit tests can stub `page.evaluate` without launching
+ *  Chromium. */
+export interface CanvasCapturePage {
+    evaluate<T, Arg>(fn: (arg: Arg) => T | Promise<T>, args?: Arg): Promise<T>;
+}
+export declare function canvasCapture(page: CanvasCapturePage, args: CanvasCaptureArgs): Promise<CanvasCaptureResult>;