browxai 0.7.0

package/dist/page/clock.js

@@ -0,0 +1,167 @@
+// Virtual-time clock control — capability `action`.
+//
+// Wraps CDP `Emulation.setVirtualTimePolicy` so date-sensitive flows
+// (renewal dates, "today" filters, scheduling, expiry edges) can be tested
+// deterministically without touching the OS clock. Per-session.
+//
+// Three modes:
+//   - freeze  → pause virtual time at `atIso` (or "now" if omitted). CDP
+//     policy: `pause` (virtual time is truly halted at the anchor, so a
+//     rAF/timer loop cannot race Date forward; page resource loading runs on
+//     real time and is unaffected).
+//   - advance → jump the virtual clock forward by `byMs`, or to absolute
+//     `atIso`, then re-freeze. CDP policy: `advance` with a `budget` (ms),
+//     then we re-issue a pause so subsequent JS time queries stay pinned.
+//   - release → resume real time. CDP no-op-equivalent via `disabled`.
+//
+// CDP's `setVirtualTimePolicy` is per-target. A renderer swap or fresh page
+// drops it — same shape as src/page/emulation.ts, so we cache the active
+// state per session and re-apply on `framenavigated` (main frame only).
+//
+// BYOB note: when applied to an attached Chrome, the virtual-time policy
+// stays in effect on the human's page until they release it, reload, or
+// close the tab — a wall-clock-looking page that has actually frozen time
+// is a debugging trap. Surfaced as a `warning` on the result.
+const MAX_ADVANCE_MS = 365 * 24 * 60 * 60 * 1000; // one year — sanity ceiling
+function parseIso(iso, field) {
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t)) {
+        throw new Error(`clock: ${field} is not a valid ISO-8601 timestamp (got ${JSON.stringify(iso)})`);
+    }
+    return t;
+}
+function normalizeInput(input, currentMs) {
+    if (input.mode === "release") {
+        return { mode: "release", targetMs: currentMs, advanceBudgetMs: 0 };
+    }
+    if (input.mode === "freeze") {
+        if (input.byMs !== undefined) {
+            throw new Error(`clock: byMs is only valid with mode:"advance" (got mode:"freeze")`);
+        }
+        const targetMs = input.atIso !== undefined ? parseIso(input.atIso, "atIso") : Date.now();
+        return { mode: "freeze", targetMs, advanceBudgetMs: 0 };
+    }
+    // advance
+    if (input.atIso !== undefined && input.byMs !== undefined) {
+        throw new Error(`clock: advance requires exactly one of atIso or byMs, not both`);
+    }
+    if (input.atIso === undefined && input.byMs === undefined) {
+        throw new Error(`clock: advance requires either atIso or byMs`);
+    }
+    let targetMs;
+    if (input.atIso !== undefined) {
+        targetMs = parseIso(input.atIso, "atIso");
+    }
+    else {
+        if (!Number.isFinite(input.byMs) || input.byMs <= 0) {
+            throw new Error(`clock: byMs must be a positive finite number (got ${input.byMs})`);
+        }
+        if (input.byMs > MAX_ADVANCE_MS) {
+            throw new Error(`clock: byMs ${input.byMs} exceeds max ${MAX_ADVANCE_MS} (1 year)`);
+        }
+        targetMs = currentMs + input.byMs;
+    }
+    const advanceBudgetMs = Math.max(0, targetMs - currentMs);
+    if (advanceBudgetMs > MAX_ADVANCE_MS) {
+        throw new Error(`clock: advance distance ${advanceBudgetMs}ms exceeds max ${MAX_ADVANCE_MS}ms (1 year)`);
+    }
+    return { mode: "advance", targetMs, advanceBudgetMs };
+}
+/** Per-session clock controller. One per SessionEntry. */
+export class ClockRegistry {
+    state;
+    /** Re-apply hook installed once per page on first use. */
+    reattachInstalled = new WeakSet();
+    /** Apply the requested mode and remember it. Returns the normalized state. */
+    async apply(cdp, page, input) {
+        const currentMs = this.state?.nowMs ?? Date.now();
+        const norm = normalizeInput(input, currentMs);
+        if (norm.mode === "release") {
+            await this.sendRelease(cdp);
+            this.state = undefined;
+            this.installReattach(page);
+            return { state: undefined, mode: "release", appliedAtIso: null };
+        }
+        if (norm.mode === "freeze") {
+            await this.sendPauseAt(cdp, norm.targetMs);
+            this.state = { nowMs: norm.targetMs, paused: true };
+            this.installReattach(page);
+            return {
+                state: this.state,
+                mode: "freeze",
+                appliedAtIso: new Date(norm.targetMs).toISOString(),
+            };
+        }
+        // advance: start from currentMs (re-pin), then advance by budget, then re-pause
+        await this.sendPauseAt(cdp, currentMs);
+        if (norm.advanceBudgetMs > 0) {
+            await this.sendAdvance(cdp, norm.advanceBudgetMs);
+        }
+        // After advance budget elapses CDP returns to whatever follow-up policy was
+        // queued — we explicitly re-pause at the new target so subsequent JS time
+        // queries see the pinned instant.
+        await this.sendPauseAt(cdp, norm.targetMs);
+        this.state = { nowMs: norm.targetMs, paused: true };
+        this.installReattach(page);
+        return {
+            state: this.state,
+            mode: "advance",
+            appliedAtIso: new Date(norm.targetMs).toISOString(),
+        };
+    }
+    /** Reset on close/teardown if a non-default policy is active. */
+    async resetAll(cdp) {
+        if (this.state) {
+            await this.sendRelease(cdp).catch(() => undefined);
+        }
+        this.state = undefined;
+    }
+    /** Test introspection. */
+    current() {
+        return this.state;
+    }
+    installReattach(page) {
+        if (this.reattachInstalled.has(page))
+            return;
+        this.reattachInstalled.add(page);
+        const onNav = async (frame) => {
+            if (frame.parentFrame())
+                return; // main frame only
+            try {
+                const cdp = await page
+                    .context()
+                    .newCDPSession(page)
+                    .catch(() => null);
+                if (!cdp)
+                    return;
+                if (this.state) {
+                    await this.sendPauseAt(cdp, this.state.nowMs).catch(() => undefined);
+                }
+            }
+            catch {
+                // page may have closed mid-navigation; swallow
+            }
+        };
+        page.on("framenavigated", onNav);
+    }
+    async sendPauseAt(cdp, atMs) {
+        // `pause` truly halts virtual time at `initialVirtualTime`. The earlier
+        // `pauseIfNetworkFetchesPending` only held time while a fetch was in flight —
+        // once the page went network-idle the scheduler resumed and any rAF/timer
+        // loop raced the clock forward (Date jumped days per wall-second), so a
+        // "frozen" page was not actually frozen. `pause` pins Date deterministically.
+        await cdp.send("Emulation.setVirtualTimePolicy", {
+            policy: "pause",
+            initialVirtualTime: atMs / 1000, // CDP expects seconds since epoch
+        });
+    }
+    async sendAdvance(cdp, budgetMs) {
+        await cdp.send("Emulation.setVirtualTimePolicy", {
+            policy: "advance",
+            budget: budgetMs,
+        });
+    }
+    async sendRelease(cdp) {
+        await cdp.send("Emulation.setVirtualTimePolicy", { policy: "advance" });
+    }
+}

package/dist/page/compose.d.ts

@@ -0,0 +1,55 @@
+import type { CDPSession, Frame } from "playwright-core";
+import { type A11yNode } from "./a11y.js";
+import type { RefRegistry } from "./refs.js";
+export interface ComposedSnapshot {
+    /** The combined tree. Root is the a11y root; DOM-walk leaves are appended as children. */
+    tree: A11yNode | null;
+    /** Counts and source mix — useful for the low-content warning + debugging. */
+    stats: {
+        a11yInteractive: number;
+        domWalkEntries: number;
+        domWalkNew: number;
+        domWalkCombined: number;
+        /** count of closed-shadow elements harvested via CDP.
+         *  Always zero when `pierce !== "closed"` or CDP refused the pierce
+         *  call. */
+        closedShadowEntries?: number;
+    };
+    /** Non-fatal warnings — low-content a11y tree, closed-shadow CDP
+     *  unavailable when pierce: "closed" was requested, etc. */
+    warnings: string[];
+}
+export interface ComposeOptions {
+    /** shadow DOM piercing.
+     *  - `undefined` (default) — pre-v0.5.0 behaviour. Playwright's a11y tree
+     *    already includes open shadow content, but the DOM-walk fallback does
+     *    not recurse into shadow roots.
+     *  - `"open"` — additionally have the DOM-walk recurse through every open
+     *    shadow root reachable from the page side.
+     *  - `"closed"` — open-walk + CDP `pierce:true` pass that surfaces
+     *    interactive / test-attr-bearing elements inside CLOSED shadow roots.
+     *    Best-effort: when CDP refuses the pierce call (older Chromium,
+     *    detached attached-mode session), falls back to the open-only result
+     *    and emits a warning.
+     *  - `false` — neither path recurses into shadow content. The DOM-walk
+     *    sticks to the top document. */
+    pierce?: "open" | "closed" | false;
+}
+export declare function composeSnapshot(cdp: CDPSession, refs: RefRegistry, testAttributes: string[], opts?: ComposeOptions): Promise<ComposedSnapshot>;
+/**
+ * Frame-scoped snapshot. Composes the snapshot for a child iframe.
+ *
+ * Cross-origin frames sit in their own renderer (OOPIF) — the top-level CDP
+ * session's `Accessibility.getFullAXTree` is rooted at the main target and
+ * doesn't reach into them. Same-origin child frames are in the same renderer
+ * but CDP's per-frame a11y query path is fragile across Playwright versions.
+ * Pragmatic choice: for ANY child frame we skip the CDP a11y pass and use the
+ * DOM-walk only via `frame.evaluate(...)`. The DOM walk is what carries find()
+ * on heavy SPAs anyway, and `frame.evaluate` is the portable, identical-
+ * behaviour-across-origin entry point Playwright exposes.
+ *
+ * Refs minted here are bound to `frame` on the registry so subsequent
+ * `locatorFor` calls route through `frame.locator(...)` rather than
+ * `page.locator(...)` — actions land inside the correct OOPIF transparently.
+ */
+export declare function composeSnapshotForFrame(frame: Frame, refs: RefRegistry, testAttributes: string[], frameId: string, opts?: ComposeOptions): Promise<ComposedSnapshot>;

package/dist/page/compose.js

@@ -0,0 +1,169 @@
+// Compose the a11y tree + the DOM-walk fallback into a single tree.
+//  .
+//
+// Behaviour:
+//   - Always get the a11y tree first (it carries roles, accessible names, structure).
+//   - Always run the DOM walk (uniform behaviour, predictable cost — one
+//     Runtime.evaluate per snapshot is cheap relative to the rest of a CDP roundtrip).
+//   - Merge: DOM-walk entries become children of the root tree. Entries whose stable
+//     key already matches an a11y node get `source: "both"`; entries new to the
+//     registry get `source: "dom"`. The a11y nodes keep `source: "a11y"` (default).
+//   - If the a11y tree has fewer than LOW_A11Y_THRESHOLD interactive descendants
+//     under the root, emit a warning telling the agent the DOM-walk source carried
+//     the load (#11) — most adopters interpret an empty-ish a11y tree as "page is
+//     empty" rather than "a11y is sparse on this codebase." This warning closes that
+//     ambiguity.
+import { getA11yTree, walk } from "./a11y.js";
+import { runDomWalk, runDomWalkOnFrame, mergeDomWalkIntoTree, } from "./dom-walk.js";
+import { annotateStructuralContext } from "./structural.js";
+import { LOW_A11Y_THRESHOLD } from "../util/config.js";
+import { elementKey } from "./refs.js";
+import { harvestClosedShadowElements } from "./shadow.js";
+const INTERACTIVE_ROLES = new Set([
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "combobox",
+    "checkbox",
+    "radio",
+    "switch",
+    "slider",
+    "spinbutton",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "option",
+    "tab",
+    "treeitem",
+]);
+export async function composeSnapshot(cdp, refs, testAttributes, opts = {}) {
+    const a11y = await getA11yTree(cdp, refs, testAttributes).catch(() => null);
+    if (a11y)
+        markSource(a11y, "a11y");
+    const a11yInteractive = a11y ? countInteractive(a11y) : 0;
+    const entries = await runDomWalk(cdp, { testAttributes, pierce: opts.pierce });
+    // closed-shadow elements come from a separate CDP pass.
+    // Same DomWalkEntry shape; merged via the same registry path so the
+    // selectorHint tier + `[from-dom]` evidence remain coherent.
+    let closedEntries = [];
+    let closedShadowWarning;
+    let closedShadowCount = 0;
+    if (opts.pierce === "closed") {
+        const harvested = await harvestClosedShadowElements(cdp, testAttributes, 500);
+        closedEntries = harvested.entries.map((e) => ({
+            role: e.role,
+            name: e.name,
+            testId: e.testId,
+            testIdAttr: e.testIdAttr,
+            tag: e.tag,
+            id: e.id,
+            structuralPath: e.structuralPath,
+            cssPath: e.cssPath,
+        }));
+        closedShadowCount = closedEntries.length;
+        closedShadowWarning = harvested.warning;
+    }
+    const allEntries = [...entries, ...closedEntries];
+    const merge = a11y ? mergeDomWalkIntoTree(a11y, allEntries, refs) : { added: 0, combined: 0 };
+    // After merging a11y + DOM-walk, tag descendants of repeated containers
+    // with their structural neighbourhood (row/column/rowText). Cheap O(n)
+    // pass; callers like `find()` ship these annotations as candidate
+    // evidence and 's container-probe references them.
+    if (a11y)
+        annotateStructuralContext(a11y);
+    const warnings = [];
+    if (a11yInteractive < LOW_A11Y_THRESHOLD) {
+        warnings.push(`low-content a11y tree (${a11yInteractive} interactive descendants under root); ` +
+            `the DOM-walk fallback supplied ${merge.added} new node(s) (${allEntries.length} total candidates seen). ` +
+            `Heavy SPAs with non-semantic markup often surface useful state through the DOM-walk source — ` +
+            `use [from-dom]-marked entries with their [testid=…] hints when present.`);
+    }
+    if (closedShadowWarning)
+        warnings.push(closedShadowWarning);
+    if (closedShadowCount > 0) {
+        warnings.push(`${closedShadowCount} candidate(s) discovered inside CLOSED shadow root(s) via CDP. ` +
+            `Closed-shadow elements are platform-protected — action tools (click/fill/etc) ` +
+            `CANNOT reach them through Playwright's locator engine. Use them as evidence ` +
+            `("this widget exists at depth N") only.`);
+    }
+    return {
+        tree: a11y,
+        stats: {
+            a11yInteractive,
+            domWalkEntries: allEntries.length,
+            domWalkNew: merge.added,
+            domWalkCombined: merge.combined,
+            ...(opts.pierce === "closed" ? { closedShadowEntries: closedShadowCount } : {}),
+        },
+        warnings,
+    };
+}
+/**
+ * Frame-scoped snapshot. Composes the snapshot for a child iframe.
+ *
+ * Cross-origin frames sit in their own renderer (OOPIF) — the top-level CDP
+ * session's `Accessibility.getFullAXTree` is rooted at the main target and
+ * doesn't reach into them. Same-origin child frames are in the same renderer
+ * but CDP's per-frame a11y query path is fragile across Playwright versions.
+ * Pragmatic choice: for ANY child frame we skip the CDP a11y pass and use the
+ * DOM-walk only via `frame.evaluate(...)`. The DOM walk is what carries find()
+ * on heavy SPAs anyway, and `frame.evaluate` is the portable, identical-
+ * behaviour-across-origin entry point Playwright exposes.
+ *
+ * Refs minted here are bound to `frame` on the registry so subsequent
+ * `locatorFor` calls route through `frame.locator(...)` rather than
+ * `page.locator(...)` — actions land inside the correct OOPIF transparently.
+ */
+export async function composeSnapshotForFrame(frame, refs, testAttributes, frameId, opts = {}) {
+    // Synthetic root so the serialiser has a tree to walk; child-frame
+    // discovery is leaf-shaped (DOM-walk produces flat entries).
+    const rootKey = elementKey({
+        role: "WebArea",
+        name: undefined,
+        path: `__frame__/${frameId}`,
+        frameId,
+    });
+    const rootRef = refs.forKey(rootKey, { role: "WebArea", source: "dom", frameId });
+    refs.bindFrame(rootRef, frame);
+    const root = {
+        ref: rootRef,
+        role: "WebArea",
+        name: frame.url() || frame.name() || `frame:${frameId}`,
+        source: "dom",
+        children: [],
+    };
+    const entries = await runDomWalkOnFrame(frame, { testAttributes, pierce: opts.pierce });
+    const merge = mergeDomWalkIntoTree(root, entries, refs, { frameId, frame });
+    annotateStructuralContext(root);
+    const warnings = [
+        `frame "${frameId}": snapshot is DOM-walk-sourced only — CDP accessibility-tree extraction is not run for child frames (OOPIF / cross-origin compatibility). [from-dom] markers reflect the source, not a deficiency.`,
+    ];
+    if (opts.pierce === "closed") {
+        warnings.push(`frame "${frameId}": closed-shadow piercing via CDP is not run inside child frames (the CDP pierce path is rooted at the top target). pierce: "closed" degraded to "open" for this frame.`);
+    }
+    return {
+        tree: root,
+        stats: {
+            a11yInteractive: 0,
+            domWalkEntries: entries.length,
+            domWalkNew: merge.added,
+            domWalkCombined: merge.combined,
+        },
+        warnings,
+    };
+}
+function markSource(root, source) {
+    for (const { node } of walk(root)) {
+        if (!node.source)
+            node.source = source;
+    }
+}
+function countInteractive(root) {
+    let n = 0;
+    for (const { node } of walk(root)) {
+        if (INTERACTIVE_ROLES.has(node.role))
+            n++;
+    }
+    return n;
+}

package/dist/page/console.d.ts

@@ -0,0 +1,39 @@
+import type { Page } from "playwright-core";
+import type { SecretRegistry } from "../util/secrets.js";
+export interface ConsoleMessage {
+    ts: number;
+    type: string;
+    text: string;
+}
+export declare class ConsoleBuffer {
+    private cap;
+    private msgs;
+    private errs;
+    /** Optional per-session secrets registry. Injected by the server after
+     *  session creation so the egress masking layer applies on every read. */
+    private secrets;
+    constructor(cap?: number);
+    /** Wire a per-session secrets registry. After this, every `recent` /
+     *  `errorsSince` / `pageErrorsSince` read substitutes registered real-values
+     *  with their `<NAME>` aliases AFTER the URL sanitiser runs (the
+     *  query-string secret-stripper that runs first so encoded secrets in URLs
+     *  don't leak past the name-substitution pass). */
+    setSecrets(secrets: SecretRegistry): void;
+    attach(page: Page): void;
+    /** Ingest a console entry from a NON-Playwright source — the safari engine has
+     *  no Playwright Page, so its console arrives via the BiDi `log.entryAdded`
+     *  stream. Mirrors the `page.on("console")` push so
+     *  `recent()` / `warningCountSince()` / `errorsSince()` work identically. The
+     *  BiDi level (`debug`/`info`/`warn`/`error`) is mapped to the console `type`
+     *  vocabulary (`warn` → `warning`) the readers key on. */
+    ingest(level: string, text: string): void;
+    /** Compose the two egress layers: URL-sanitise first (regex on URL shape),
+     *  then secrets-mask (literal real-value substitution). They don't fight —
+     *  the URL sanitiser already redacted `?token=…`; the literal scan still
+     *  catches a registered secret that landed elsewhere in the text. */
+    private sanitiseEgress;
+    recent(limit?: number): ConsoleMessage[];
+    errorsSince(ts: number): string[];
+    pageErrorsSince(ts: number): string[];
+    warningCountSince(ts: number): number;
+}

package/dist/page/console.js

@@ -0,0 +1,73 @@
+// Ring buffer of console messages + page errors, hooked off Playwright Page events.
+// Always-on (cheap); ActionResult slices the "since action started" view; the
+// `console_read` MCP tool exposes the buffer.
+import { sanitizeUrlsInText } from "../util/url-sanitizer.js";
+const DEFAULT_CAP = 200;
+export class ConsoleBuffer {
+    cap;
+    msgs = [];
+    errs = [];
+    /** Optional per-session secrets registry. Injected by the server after
+     *  session creation so the egress masking layer applies on every read. */
+    secrets = null;
+    constructor(cap = DEFAULT_CAP) {
+        this.cap = cap;
+    }
+    /** Wire a per-session secrets registry. After this, every `recent` /
+     *  `errorsSince` / `pageErrorsSince` read substitutes registered real-values
+     *  with their `<NAME>` aliases AFTER the URL sanitiser runs (the
+     *  query-string secret-stripper that runs first so encoded secrets in URLs
+     *  don't leak past the name-substitution pass). */
+    setSecrets(secrets) {
+        this.secrets = secrets;
+    }
+    attach(page) {
+        page.on("console", (m) => {
+            this.msgs.push({ ts: Date.now(), type: m.type(), text: m.text() });
+            if (this.msgs.length > this.cap)
+                this.msgs.shift();
+        });
+        page.on("pageerror", (err) => {
+            this.errs.push({ ts: Date.now(), text: err.message });
+            if (this.errs.length > this.cap)
+                this.errs.shift();
+        });
+    }
+    /** Ingest a console entry from a NON-Playwright source — the safari engine has
+     *  no Playwright Page, so its console arrives via the BiDi `log.entryAdded`
+     *  stream. Mirrors the `page.on("console")` push so
+     *  `recent()` / `warningCountSince()` / `errorsSince()` work identically. The
+     *  BiDi level (`debug`/`info`/`warn`/`error`) is mapped to the console `type`
+     *  vocabulary (`warn` → `warning`) the readers key on. */
+    ingest(level, text) {
+        const type = level === "warn" ? "warning" : level;
+        this.msgs.push({ ts: Date.now(), type, text });
+        if (this.msgs.length > this.cap)
+            this.msgs.shift();
+    }
+    /** Compose the two egress layers: URL-sanitise first (regex on URL shape),
+     *  then secrets-mask (literal real-value substitution). They don't fight —
+     *  the URL sanitiser already redacted `?token=…`; the literal scan still
+     *  catches a registered secret that landed elsewhere in the text. */
+    sanitiseEgress(text) {
+        const afterUrl = sanitizeUrlsInText(text);
+        return this.secrets ? this.secrets.applyMaskInText(afterUrl) : afterUrl;
+    }
+    // URL substrings + registered-secret values in console / page-error text are
+    // sanitized at the egress boundary (read time) — the ring keeps raw text;
+    // only what leaves the server toward an MCP result is redacted.
+    recent(limit = 50) {
+        return this.msgs.slice(-limit).map((m) => ({ ...m, text: this.sanitiseEgress(m.text) }));
+    }
+    errorsSince(ts) {
+        return this.msgs
+            .filter((m) => m.type === "error" && m.ts >= ts)
+            .map((m) => this.sanitiseEgress(m.text));
+    }
+    pageErrorsSince(ts) {
+        return this.errs.filter((e) => e.ts >= ts).map((e) => this.sanitiseEgress(e.text));
+    }
+    warningCountSince(ts) {
+        return this.msgs.filter((m) => m.type === "warning" && m.ts >= ts).length;
+    }
+}

package/dist/page/coverage.d.ts

@@ -0,0 +1,97 @@
+import type { CDPSession } from "playwright-core";
+/** Per-script JS coverage entry — one per Script URL the profiler observed. */
+export interface JsCoverageEntry {
+    url: string;
+    totalBytes: number;
+    usedBytes: number;
+    /** 0-100. `totalBytes:0` is reported as `usagePercent:100` (no code → no
+     *  dead code). */
+    usagePercent: number;
+    /** Optional list of dead byte ranges (only emitted when small enough to
+     *  surface — top 50 ranges per script). */
+    deadRanges?: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/** Per-stylesheet CSS coverage entry — one per <style>/<link rel=stylesheet>
+ *  the page used. */
+export interface CssCoverageEntry {
+    url: string;
+    totalBytes: number;
+    usedBytes: number;
+    /** Approximate count derived from used-rule ranges. */
+    usedRules: number;
+    /** Same approximation against total ranges. */
+    totalRules: number;
+    /** 0-100. */
+    usagePercent: number;
+    /** Dead-rule byte ranges (top 50 per stylesheet). */
+    deadRules?: Array<{
+        start: number;
+        end: number;
+    }>;
+}
+/** Result of `coverage_stop` — the parsed report. */
+export interface CoverageStopResult {
+    jsCoverage: JsCoverageEntry[];
+    cssCoverage: CssCoverageEntry[];
+    durationMs: number;
+}
+/** CDP Profiler.takePreciseCoverage response shape (only the fields we touch). */
+interface CdpScriptCoverage {
+    url?: string;
+    functions?: Array<{
+        functionName?: string;
+        isBlockCoverage?: boolean;
+        ranges?: Array<{
+            startOffset: number;
+            endOffset: number;
+            count: number;
+        }>;
+    }>;
+}
+/** CDP CSS.takeCoverageDelta response shape. */
+interface CdpRuleUsage {
+    styleSheetId: string;
+    startOffset: number;
+    endOffset: number;
+    used: boolean;
+}
+interface CdpStyleSheetHeader {
+    styleSheetId: string;
+    sourceURL?: string;
+    length?: number;
+}
+/** Per-session coverage tracker. One instance per SessionEntry; the
+ *  underlying CDP coverage is per-target. */
+export declare class CoverageTrackerState {
+    private running;
+    private startedAt;
+    /** Snapshot of `getAllStyleSheets()` taken at `start` so `stop` can map
+     *  styleSheetId → URL + total length without a second CDP roundtrip. */
+    private cssHeaders;
+    /** CSS.styleSheetAdded event handler — kept for cleanup. */
+    private onStyleSheetAdded;
+    isRunning(): boolean;
+    /** 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. */
+    start(cdp: CDPSession): Promise<{
+        startedAt: number;
+        restarted: boolean;
+    }>;
+    /** Stop both trackers, fetch + parse the results. Safe to call when no
+     *  coverage is running — returns an empty report with `notRunning:true`. */
+    stop(cdp: CDPSession): Promise<CoverageStopResult & {
+        notRunning?: true;
+    }>;
+    /** Force-clean teardown for session close. */
+    closeIfRunning(cdp: CDPSession): Promise<void>;
+    private stopInternal;
+}
+export declare function parseJsCoverage(scripts: CdpScriptCoverage[]): JsCoverageEntry[];
+/** Parse `CSS.stopRuleUsageTracking` output into per-stylesheet entries.
+ *  Exported for unit tests against synthetic CDP payloads. */
+export declare function parseCssCoverage(ruleUsage: CdpRuleUsage[], headers: Map<string, CdpStyleSheetHeader>): CssCoverageEntry[];
+export {};