browxai 0.7.0

package/dist/page/memory-diff.js

@@ -0,0 +1,105 @@
+// memory_diff — capability `read`. Pure-function consumer of two
+// `.heapsnapshot` files. No browser interaction.
+//
+// "Take a snapshot → do thing → take another snapshot → who grew?" is the
+// canonical leak-detection workflow. The two snapshots are the existing
+// `heap_snapshot` tool output. This tool diffs them: groups nodes by
+// `${type}:${name}`, sums self_size per group, reports per-group deltas
+// (sizeBefore / sizeAfter / deltaBytes / deltaPercent / type).
+//
+// Noise filter: groups with `|deltaBytes| < 1024` are dropped — sub-KB
+// noise is rampant in V8 heaps and crowds the actionable signal.
+//
+// Reuses the snapshot parser from `src/page/heap.ts`.
+import { resolve, sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { parseHeapSnapshot } from "./heap.js";
+const NOISE_FILTER_BYTES = 1024;
+const MAX_GROWTH_ROWS = 100;
+/** Workspace-rooted path helper — same shape as `resolvePerfTracePath`. */
+export function resolveHeapPath(workspaceRoot, p, tool) {
+    const resolved = resolve(workspaceRoot, p);
+    if (resolved !== workspaceRoot && !resolved.startsWith(workspaceRoot + sep)) {
+        throw new Error(`${tool}: paths must resolve inside $BROWX_WORKSPACE — got "${p}".`);
+    }
+    return resolved;
+}
+/** Pure aggregator — group nodes by `${type}:${name}` and sum self_size.
+ *  Exported for unit tests against tiny in-memory snapshot JSON values. */
+export function aggregateNodeSizes(parsed) {
+    const out = new Map();
+    const total = parsed.nodes.length / parsed.nodeFieldCount;
+    for (let i = 0; i < total; i++) {
+        const base = i * parsed.nodeFieldCount;
+        const typeIdx = parsed.nodes[base + parsed.fieldIdx.nodeType] ?? 0;
+        const nameIdx = parsed.nodes[base + parsed.fieldIdx.nodeName] ?? 0;
+        const selfSize = parsed.nodes[base + parsed.fieldIdx.nodeSelfSize] ?? 0;
+        const type = parsed.nodeTypes[typeIdx] ?? "";
+        const name = parsed.strings[nameIdx] ?? "";
+        const display = type && name ? `${type}:${name}` : name || type || "<unknown>";
+        const slot = out.get(display);
+        if (slot)
+            slot.size += selfSize;
+        else
+            out.set(display, { type, name, size: selfSize });
+    }
+    return out;
+}
+/** Pure diff helper — given two aggregator maps, return the growth report.
+ *  Exported for unit tests. */
+export function diffSizeMaps(before, after) {
+    const keys = new Set();
+    for (const k of before.keys())
+        keys.add(k);
+    for (const k of after.keys())
+        keys.add(k);
+    const rows = [];
+    let totalGrowth = 0;
+    for (const k of keys) {
+        const b = before.get(k);
+        const a = after.get(k);
+        const sizeBefore = b?.size ?? 0;
+        const sizeAfter = a?.size ?? 0;
+        const deltaBytes = sizeAfter - sizeBefore;
+        if (Math.abs(deltaBytes) < NOISE_FILTER_BYTES)
+            continue;
+        const type = a?.type ?? b?.type ?? "";
+        const deltaPercent = sizeBefore === 0 ? "+inf" : Math.round((deltaBytes / sizeBefore) * 10000) / 100;
+        rows.push({
+            node: k,
+            type,
+            sizeBefore,
+            sizeAfter,
+            deltaBytes,
+            deltaPercent,
+        });
+        if (deltaBytes > 0)
+            totalGrowth += deltaBytes;
+    }
+    rows.sort((a, b) => b.deltaBytes - a.deltaBytes);
+    const top3 = rows.slice(0, 3).map((r) => ({
+        node: r.node,
+        deltaBytes: r.deltaBytes,
+        deltaPercent: r.deltaPercent,
+    }));
+    return {
+        retainerGrowth: rows.slice(0, MAX_GROWTH_ROWS),
+        summary: { totalGrowth, top3Growers: top3 },
+    };
+}
+/** Diff two heap snapshots at the given workspace-rooted paths. */
+export function diffHeapSnapshots(workspaceRoot, beforePath, afterPath, tool = "memory_diff") {
+    const beforeResolved = resolveHeapPath(workspaceRoot, beforePath, tool);
+    const afterResolved = resolveHeapPath(workspaceRoot, afterPath, tool);
+    if (!existsSync(beforeResolved)) {
+        throw new Error(`${tool}: beforePath not found at "${beforeResolved}"`);
+    }
+    if (!existsSync(afterResolved)) {
+        throw new Error(`${tool}: afterPath not found at "${afterResolved}"`);
+    }
+    const beforeParsed = parseHeapSnapshot(readFileSync(beforeResolved, "utf8"));
+    const afterParsed = parseHeapSnapshot(readFileSync(afterResolved, "utf8"));
+    const beforeMap = aggregateNodeSizes(beforeParsed);
+    const afterMap = aggregateNodeSizes(afterParsed);
+    return diffSizeMaps(beforeMap, afterMap);
+}

package/dist/page/network-mask.d.ts

@@ -0,0 +1,8 @@
+import type { SecretRegistry } from "../util/secrets.js";
+/** Apply the URL sanitiser (strips credentials / secret-shaped query
+ *  params) then the per-session secrets-masking layer. Order matters:
+ *  secrets-masking is literal substring; the URL sanitiser may already
+ *  have stripped a credentialled query, but a real-value that landed in
+ *  the path is still caught by the literal scan after. */
+export declare function maskedUrl(url: string, secrets: SecretRegistry | null): string;
+export declare function maskedText(text: string, secrets: SecretRegistry | null): string;

package/dist/page/network-mask.js

@@ -0,0 +1,18 @@
+// Shared egress-masking helpers for the network/WebSocket capture modules.
+// One chokepoint so the URL-sanitiser + per-session secrets-masking order is
+// identical across the CDP (`network.ts`), Playwright (`network-playwright.ts`),
+// and WebSocket (`network-ws.ts`) paths.
+import { sanitizeUrl, sanitizeUrlsInText } from "../util/url-sanitizer.js";
+/** Apply the URL sanitiser (strips credentials / secret-shaped query
+ *  params) then the per-session secrets-masking layer. Order matters:
+ *  secrets-masking is literal substring; the URL sanitiser may already
+ *  have stripped a credentialled query, but a real-value that landed in
+ *  the path is still caught by the literal scan after. */
+export function maskedUrl(url, secrets) {
+    const u = sanitizeUrl(url);
+    return secrets ? secrets.applyMaskInText(u) : u;
+}
+export function maskedText(text, secrets) {
+    const t = sanitizeUrlsInText(text);
+    return secrets ? secrets.applyMaskInText(t) : t;
+}

package/dist/page/network-playwright.d.ts

@@ -0,0 +1,96 @@
+import type { BrowserContext, Page } from "playwright-core";
+import type { SecretRegistry } from "../util/secrets.js";
+import { type MutationEntry, type NetworkEntry, type NetworkSummary } from "./network.js";
+import { type WsFrame } from "./network-ws.js";
+/** Action-window network tap on Playwright context events — the off-Chromium
+ *  twin of `NetworkTap`. Same lifecycle (`open()` before dispatch, `close()`
+ *  after settle) and same `{summary, requests, mutations}` return shape. */
+export declare class PlaywrightNetworkTap {
+    private context;
+    private secrets;
+    private pending;
+    private finished;
+    private mutationPromises;
+    private listeners;
+    constructor(context: BrowserContext, secrets?: SecretRegistry | null);
+    open(): Promise<void>;
+    close(): Promise<{
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+        mutations: MutationEntry[];
+    }>;
+}
+/** Session-wide network ring on Playwright context events — the off-Chromium
+ *  twin of `NetworkBuffer`. Same ring + `recent()` / `iter()` shape; additionally
+ *  captures response bodies at response time into a bounded LRU so `network_body`
+ *  can resolve a `requestId` after the fact (there is no off-Chromium analogue of
+ *  CDP `Network.getResponseBody`'s lazy fetch). */
+export declare class PlaywrightNetworkBuffer {
+    private context;
+    private cap;
+    /** how many recent response bodies to retain for `network_body`. Bounded so
+     *  capturing every body doesn't grow unbounded (the doctrine: bound the
+     *  buffer). Default 50 — the agent fetches a body right after the request. */
+    private bodyCap;
+    private maxBodyBytes;
+    private ring;
+    private ids;
+    /** captured bodies keyed by synthetic request id, bounded LRU. */
+    private bodies;
+    private enabled;
+    private secrets;
+    constructor(context: BrowserContext, cap?: number, 
+    /** how many recent response bodies to retain for `network_body`. Bounded so
+     *  capturing every body doesn't grow unbounded (the doctrine: bound the
+     *  buffer). Default 50 — the agent fetches a body right after the request. */
+    bodyCap?: number, maxBodyBytes?: number);
+    setSecrets(secrets: SecretRegistry): void;
+    attach(): Promise<void>;
+    private captureBody;
+    private push;
+    /** Raw, read-only snapshot of the ring (asset_export iterates this). */
+    iter(): readonly NetworkEntry[];
+    /** Most-recent N entries; noise + beacons folded into `other`. */
+    recent(limit?: number): {
+        summary: NetworkSummary;
+        requests: NetworkEntry[];
+    };
+    /** Resolve a `requestId` to its captured body. Bytes were stored as a Buffer
+     *  at response time; emit as utf-8 unless they aren't valid text, in which case
+     *  base64 (matching the CDP `Network.getResponseBody` base64Encoded contract).
+     *  Secrets masking is applied to text bodies (base64 passes through, same as
+     *  the CDP path). */
+    fetchBody(requestId: string, secrets: SecretRegistry | null): Promise<{
+        ok: boolean;
+        body?: string;
+        base64Encoded?: boolean;
+        truncated?: boolean;
+        error?: string;
+    }>;
+}
+/** Session-wide WebSocket/SSE ring on Playwright events — the off-Chromium twin
+ *  of `WsBuffer`. `page.on('websocket')` + `ws.on('framesent'|'framereceived')`
+ *  are cross-browser. Server-Sent-Events are not exposed as a discrete Playwright
+ *  event (they arrive as a long-lived `eventsource` response, not WS frames), so
+ *  the SSE half degrades off Chromium — documented in the per-engine matrix. */
+export declare class PlaywrightWsBuffer {
+    private page;
+    private cap;
+    private maxPayload;
+    private ring;
+    private enabled;
+    private secrets;
+    constructor(page: Page, cap?: number, maxPayload?: number);
+    setSecrets(secrets: SecretRegistry): void;
+    private trunc;
+    private push;
+    attach(): Promise<void>;
+    private frame;
+    /** Most-recent N frames, optionally filtered by a url substring. */
+    recent(limit?: number, urlPattern?: string): {
+        total: number;
+        frames: WsFrame[];
+    };
+    /** Frames since a timestamp — for the per-action `ActionResult` slice. */
+    since(ts: number, cap?: number): WsFrame[];
+}

package/dist/page/network-playwright.js

@@ -0,0 +1,353 @@
+// Off-Chromium network/WebSocket capture — the Playwright-events twin of the
+// CDP classes in `network.ts`.
+//
+// Firefox/WebKit have no CDP `Network.*` domain (Firefox removed CDP in v141),
+// so the network slice rides Playwright's cross-browser context events instead:
+//   - `context.on('request')`        → a pending request (mirrors requestWillBeSent)
+//   - `context.on('response')`       → status arrived (mirrors responseReceived)
+//   - `context.on('requestfailed')`  → load error  (mirrors loadingFailed)
+//   - `context.on('requestfinished')`→ encoded byte size (mirrors loadingFinished)
+//   - `page.on('websocket')` + `ws.on('framesent'|'framereceived')` → WS frames
+//
+// These classes produce byte-identical egress shapes to the CDP ones (the same
+// NetworkEntry / NetworkSummary / MutationEntry / WsFrame, the same noise-fold via
+// `foldInteresting`, the same secrets masking), so every consumer above the seam
+// is engine-blind. Playwright `Request` objects have no protocol id, so a
+// monotonic synthetic id is minted per request and used as the `requestId` handle
+// `network_body` resolves. Re-exported through `./network.js` so callers import
+// the whole network surface from the one barrel, unchanged.
+import { cdpTypeFromPlaywright, extractTopLevelKeys, foldInteresting, mutationWithoutShape, mutationWithShape, MAX_BODY_BYTES_TO_PARSE, MUTATION_METHODS, } from "./network.js";
+import { sanitizeFrame } from "./network-ws.js";
+let pwRequestSeq = 0;
+function nextPwRequestId() {
+    return `pw-${(pwRequestSeq = (pwRequestSeq + 1) % Number.MAX_SAFE_INTEGER)}`;
+}
+/** Best-effort mutation-detail probe over a Playwright `Response` (the off-
+ *  Chromium analogue of `probeMutation`). Reads the body via `response.body()`
+ *  (cross-browser), extracts only the top-level JSON keys. Returns null on any
+ *  failure so the caller filters nulls out, identical to the CDP probe. */
+async function probeMutationPlaywright(response, detail) {
+    try {
+        const buf = await response.body();
+        if (buf.length > MAX_BODY_BYTES_TO_PARSE)
+            return mutationWithoutShape(detail);
+        const trimmed = buf.toString("utf-8").trim();
+        if (!trimmed)
+            return mutationWithoutShape(detail);
+        if (trimmed[0] !== "{" && trimmed[0] !== "[")
+            return mutationWithoutShape(detail);
+        const parsed = JSON.parse(trimmed);
+        return mutationWithShape(detail, extractTopLevelKeys(parsed));
+    }
+    catch {
+        return null;
+    }
+}
+/** Action-window network tap on Playwright context events — the off-Chromium
+ *  twin of `NetworkTap`. Same lifecycle (`open()` before dispatch, `close()`
+ *  after settle) and same `{summary, requests, mutations}` return shape. */
+export class PlaywrightNetworkTap {
+    context;
+    secrets;
+    pending = new Map();
+    finished = [];
+    mutationPromises = [];
+    listeners = [];
+    constructor(context, secrets = null) {
+        this.context = context;
+        this.secrets = secrets;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async open() {
+        this.pending.clear();
+        this.finished = [];
+        this.mutationPromises = [];
+        const onRequest = (req) => {
+            this.pending.set(req, {
+                method: req.method(),
+                url: req.url(),
+                type: cdpTypeFromPlaywright(req.resourceType()),
+                startedAt: Date.now(),
+            });
+        };
+        const onResponse = (res) => {
+            const req = res.request();
+            const r = this.pending.get(req);
+            if (!r)
+                return;
+            const ms = Date.now() - r.startedAt;
+            const status = res.status();
+            this.finished.push({ method: r.method, url: r.url, status, type: r.type, ms });
+            if (MUTATION_METHODS.has(r.method) && status >= 200 && status < 300) {
+                this.mutationPromises.push(probeMutationPlaywright(res, { method: r.method, url: r.url, status, durationMs: ms }));
+            }
+            this.pending.delete(req);
+        };
+        const onFailed = (req) => {
+            const r = this.pending.get(req);
+            if (!r)
+                return;
+            this.finished.push({
+                method: r.method,
+                url: r.url,
+                type: r.type,
+                failed: true,
+                ms: Date.now() - r.startedAt,
+            });
+            this.pending.delete(req);
+        };
+        this.context.on("request", onRequest);
+        this.context.on("response", onResponse);
+        this.context.on("requestfailed", onFailed);
+        this.listeners = [
+            () => this.context.off("request", onRequest),
+            () => this.context.off("response", onResponse),
+            () => this.context.off("requestfailed", onFailed),
+        ];
+    }
+    async close() {
+        for (const off of this.listeners)
+            off();
+        this.listeners = [];
+        const { summary, requests } = foldInteresting(this.finished, this.secrets);
+        const mutationsRaw = (await Promise.all(this.mutationPromises)).filter((m) => m !== null);
+        const mutations = mutationsRaw.map((m) => {
+            const out = {
+                ...m,
+                urlPattern: this.secrets ? this.secrets.applyMaskInText(m.urlPattern) : m.urlPattern,
+            };
+            if (m.responseShape && this.secrets) {
+                out.responseShape = m.responseShape.map((k) => this.secrets.applyMaskInText(k));
+            }
+            return out;
+        });
+        return { summary, requests, mutations };
+    }
+}
+/** Session-wide network ring on Playwright context events — the off-Chromium
+ *  twin of `NetworkBuffer`. Same ring + `recent()` / `iter()` shape; additionally
+ *  captures response bodies at response time into a bounded LRU so `network_body`
+ *  can resolve a `requestId` after the fact (there is no off-Chromium analogue of
+ *  CDP `Network.getResponseBody`'s lazy fetch). */
+export class PlaywrightNetworkBuffer {
+    context;
+    cap;
+    bodyCap;
+    maxBodyBytes;
+    ring = [];
+    ids = new WeakMap();
+    /** captured bodies keyed by synthetic request id, bounded LRU. */
+    bodies = new Map();
+    enabled = false;
+    secrets = null;
+    constructor(context, cap = 500, 
+    /** how many recent response bodies to retain for `network_body`. Bounded so
+     *  capturing every body doesn't grow unbounded (the doctrine: bound the
+     *  buffer). Default 50 — the agent fetches a body right after the request. */
+    bodyCap = 50, maxBodyBytes = 256_000) {
+        this.context = context;
+        this.cap = cap;
+        this.bodyCap = bodyCap;
+        this.maxBodyBytes = maxBodyBytes;
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async attach() {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        this.context.on("request", (req) => {
+            this.ids.set(req, nextPwRequestId());
+        });
+        this.context.on("response", (res) => {
+            const req = res.request();
+            const id = this.ids.get(req) ?? nextPwRequestId();
+            const entry = {
+                method: req.method(),
+                url: req.url(),
+                status: res.status(),
+                type: cdpTypeFromPlaywright(req.resourceType()),
+                ms: 0,
+                requestId: id,
+            };
+            const mime = res.headers()["content-type"];
+            if (mime)
+                entry.mimeType = mime;
+            this.push(entry);
+            // capture the body at response time (bounded) — bodies aren't fetchable
+            // after the fact off Chromium. Best-effort: a failed read leaves no cache
+            // entry and `network_body` reports "not available".
+            void this.captureBody(id, res);
+        });
+        this.context.on("requestfinished", (req) => {
+            const id = this.ids.get(req);
+            if (!id)
+                return;
+            const entry = this.ring.find((e) => e.requestId === id);
+            if (!entry)
+                return;
+            void req
+                .sizes()
+                .then((s) => {
+                if (typeof s.responseBodySize === "number" && s.responseBodySize >= 0)
+                    entry.bytes = s.responseBodySize;
+            })
+                .catch(() => undefined);
+        });
+        this.context.on("requestfailed", (req) => {
+            const id = this.ids.get(req) ?? nextPwRequestId();
+            this.push({
+                method: req.method(),
+                url: req.url(),
+                type: cdpTypeFromPlaywright(req.resourceType()),
+                failed: true,
+                ms: 0,
+                requestId: id,
+            });
+        });
+    }
+    async captureBody(id, res) {
+        try {
+            const buf = await res.body();
+            const truncated = buf.length > this.maxBodyBytes;
+            const stored = truncated ? buf.subarray(0, this.maxBodyBytes) : buf;
+            this.bodies.set(id, { buf: stored, truncated });
+            // LRU eviction — keep the most recent `bodyCap` bodies.
+            if (this.bodies.size > this.bodyCap) {
+                const oldest = this.bodies.keys().next().value;
+                if (oldest !== undefined)
+                    this.bodies.delete(oldest);
+            }
+        }
+        catch {
+            /* body not retained (e.g. a redirect / no-body response) — best-effort */
+        }
+    }
+    push(entry) {
+        this.ring.push(entry);
+        if (this.ring.length > this.cap)
+            this.ring.shift();
+    }
+    /** Raw, read-only snapshot of the ring (asset_export iterates this). */
+    iter() {
+        return this.ring;
+    }
+    /** Most-recent N entries; noise + beacons folded into `other`. */
+    recent(limit = 50) {
+        return foldInteresting(this.ring.slice(-limit), this.secrets);
+    }
+    /** Resolve a `requestId` to its captured body. Bytes were stored as a Buffer
+     *  at response time; emit as utf-8 unless they aren't valid text, in which case
+     *  base64 (matching the CDP `Network.getResponseBody` base64Encoded contract).
+     *  Secrets masking is applied to text bodies (base64 passes through, same as
+     *  the CDP path). */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async fetchBody(requestId, secrets) {
+        const cached = this.bodies.get(requestId);
+        if (!cached) {
+            return {
+                ok: false,
+                error: `response body not available for "${requestId}" — off Chromium, bodies are captured at ` +
+                    `response time into a bounded recent-window cache (no after-the-fact protocol fetch like CDP ` +
+                    `Network.getResponseBody). Read the body right after the request, before ${this.bodyCap} newer ` +
+                    `responses evict it; bodies aren't retained across navigations.`,
+            };
+        }
+        // Decide text-vs-base64: a body that round-trips through utf-8 cleanly is
+        // text; otherwise base64 (the agent decodes + re-masks on its side).
+        const utf8 = cached.buf.toString("utf-8");
+        const isText = Buffer.from(utf8, "utf-8").equals(cached.buf);
+        if (isText) {
+            const out = secrets ? secrets.applyMaskInText(utf8) : utf8;
+            return {
+                ok: true,
+                body: out,
+                base64Encoded: false,
+                ...(cached.truncated ? { truncated: true } : {}),
+            };
+        }
+        return {
+            ok: true,
+            body: cached.buf.toString("base64"),
+            base64Encoded: true,
+            ...(cached.truncated ? { truncated: true } : {}),
+        };
+    }
+}
+/** Session-wide WebSocket/SSE ring on Playwright events — the off-Chromium twin
+ *  of `WsBuffer`. `page.on('websocket')` + `ws.on('framesent'|'framereceived')`
+ *  are cross-browser. Server-Sent-Events are not exposed as a discrete Playwright
+ *  event (they arrive as a long-lived `eventsource` response, not WS frames), so
+ *  the SSE half degrades off Chromium — documented in the per-engine matrix. */
+export class PlaywrightWsBuffer {
+    page;
+    cap;
+    maxPayload;
+    ring = [];
+    enabled = false;
+    secrets = null;
+    constructor(page, cap = 500, maxPayload = 2000) {
+        this.page = page;
+        this.cap = cap;
+        this.maxPayload = maxPayload;
+    }
+    setSecrets(secrets) {
+        this.secrets = secrets;
+    }
+    trunc(s) {
+        if (s.length <= this.maxPayload)
+            return { payload: s };
+        return { payload: s.slice(0, this.maxPayload), truncated: true };
+    }
+    push(f) {
+        this.ring.push(f);
+        if (this.ring.length > this.cap)
+            this.ring.shift();
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async attach() {
+        if (this.enabled)
+            return;
+        this.enabled = true;
+        this.page.on("websocket", (ws) => {
+            const url = ws.url();
+            // Playwright surfaces text frames as strings and binary frames as Buffers.
+            // We only stringify; binary payloads become their utf-8 lossy form (the CDP
+            // path likewise carries `payloadData` as the protocol delivered it). Opcode
+            // 1 (text) / 2 (binary) is inferred from the payload runtime type.
+            ws.on("framesent", (data) => this.push(this.frame(url, "sent", data.payload)));
+            ws.on("framereceived", (data) => this.push(this.frame(url, "recv", data.payload)));
+        });
+    }
+    frame(url, dir, payload) {
+        const isText = typeof payload === "string";
+        const text = isText ? payload : payload.toString("utf-8");
+        return {
+            url,
+            dir,
+            kind: "ws",
+            opcode: isText ? 1 : 2,
+            ...this.trunc(text),
+            ts: Date.now(),
+        };
+    }
+    /** Most-recent N frames, optionally filtered by a url substring. */
+    recent(limit = 50, urlPattern) {
+        let frames = this.ring;
+        if (urlPattern)
+            frames = frames.filter((f) => f.url.includes(urlPattern));
+        return {
+            total: frames.length,
+            frames: frames.slice(-limit).map((f) => sanitizeFrame(f, this.secrets)),
+        };
+    }
+    /** Frames since a timestamp — for the per-action `ActionResult` slice. */
+    since(ts, cap = 25) {
+        return this.ring
+            .filter((f) => f.ts >= ts)
+            .slice(-cap)
+            .map((f) => sanitizeFrame(f, this.secrets));
+    }
+}

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

@@ -0,0 +1,18 @@
+import type { CDPSession, Page } from "playwright-core";
+import { type NetworkSubstrate } from "./network-substrate.js";
+/** The minimal session shape this selector needs — the optional CDP accessor
+ *  (present only on chromium) + the engine tag + the page handle. The full
+ *  BrowserSession satisfies it; the narrow shape keeps the engine/session
+ *  interfaces out of this page-layer module. */
+export interface NetworkSubstrateCapableSession {
+    readonly engine: string;
+    page(): Page;
+    cdp?(): CDPSession;
+}
+/** Build the NetworkSubstrate for a session. Chromium (CDP present) → the
+ *  byte-identical CDP substrate; any engine without CDP → the Playwright context-
+ *  event substrate. The presence of `cdp` is the capability signal — the same one
+ *  `requireCdp` and `snapshotSubstrateFor` key on — so a future CDP-bearing engine
+ *  routes to the CDP substrate automatically and a non-CDP one to the event path,
+ *  with no edit here. */
+export declare function networkSubstrateFor(session: NetworkSubstrateCapableSession): NetworkSubstrate;

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

@@ -0,0 +1,32 @@
+// Network substrate selection — maps a live session to its NetworkSubstrate.
+// This is the seam where the engine's network strategy is chosen: chromium (CDP)
+// gets the verbatim CDP substrate (NetworkBuffer / WsBuffer / NetworkTap /
+// fetchResponseBody); an engine with no CDP escape hatch (firefox / webkit) gets
+// the Playwright context-event substrate. The choice is the engine's, declared
+// by whether it exposes the raw-CDP handle — not an engine-name check scattered
+// through the tools. Mirrors `snapshotSubstrateFor`.
+//
+// The session layer wires one substrate per entry at creation (server.ts) so the
+// per-call path is a captured-handle delegate: the session buffers are attached
+// once, and the per-action tap the action window mints is the same allocation the
+// CDP path already made. No new per-action cost on chromium (the envelope is the
+// hottest path, so the per-call delegate reuses the attached buffers rather than
+// reallocating; measured).
+import { CdpNetworkSubstrate, PlaywrightNetworkSubstrate, SafariNoopNetworkSubstrate, } from "./network-substrate.js";
+/** Build the NetworkSubstrate for a session. Chromium (CDP present) → the
+ *  byte-identical CDP substrate; any engine without CDP → the Playwright context-
+ *  event substrate. The presence of `cdp` is the capability signal — the same one
+ *  `requireCdp` and `snapshotSubstrateFor` key on — so a future CDP-bearing engine
+ *  routes to the CDP substrate automatically and a non-CDP one to the event path,
+ *  with no edit here. */
+export function networkSubstrateFor(session) {
+    // Safari has no network substrate at all (no CDP tap, no BiDi network domain) —
+    // and no Playwright Page to feed the event path — so it gets the empty no-op
+    // substrate; the network tools are capability-gated. Handled before page().
+    if (session.engine === "safari")
+        return new SafariNoopNetworkSubstrate();
+    if (session.cdp)
+        return new CdpNetworkSubstrate(session.cdp());
+    const page = session.page();
+    return new PlaywrightNetworkSubstrate(page.context(), page, session.engine);
+}