framewatch-mcp-server 0.1.0

package/dist/engine/layers/network.d.ts

@@ -0,0 +1,62 @@
+import type { Page } from "playwright";
+import type { NetworkEvent } from "../../types.js";
+/**
+ * Network layer.
+ *
+ * Records one event per request that settles during a capture: method, url,
+ * status, how long it took, and when it landed. A request is timestamped at
+ * the moment it *settled*, not when it was sent, because that is the instant
+ * that can explain the frame next to it — a spinner disappears when the
+ * response arrives, not when the fetch was issued.
+ *
+ * Durations come from Chromium's own `request.timing()` rather than from wall
+ * clock in the event handler, so they measure the request and not Node's event
+ * loop. Failed requests have no timing, and fall back to wall clock.
+ *
+ * Requests still in flight when the recording ends are reported too, as
+ * `status: 0, error: "pending"` — a request that never comes back is a finding,
+ * and silently dropping it would hide exactly the bug a developer is chasing.
+ */
+/** One settled request, stamped with absolute (epoch) time and an already-shortened url. */
+export interface NetworkRecord {
+    at: number;
+    method: string;
+    url: string;
+    status: number;
+    duration_ms: number;
+    error?: string;
+}
+/**
+ * Shorten a URL for display, keeping both ends: the path says what was asked
+ * for and the tail usually carries the identifying part of a query string.
+ * data: URIs are collapsed outright — they are content, not an address.
+ */
+export declare function shortenUrl(url: string, maxLength?: number): string;
+export declare class NetworkCollector {
+    #private;
+    constructor(page: Page, limit?: number);
+    /** Start listening. Idempotent. */
+    attach(): this;
+    /** Stop listening. Collected events are kept. */
+    detach(): void;
+    /** Events refused or evicted by the cap, settled and pending alike. */
+    get dropped(): number;
+    /** Requests that never settled before the recording ended. */
+    get pending(): number;
+    /**
+     * Forget everything collected so far, in-flight requests included. See
+     * `BoundedLog.clear`.
+     *
+     * Dropping the in-flight map is deliberate: a request that was already
+     * running before this window started did not begin here, and reporting it
+     * as this action's pending request would be a lie about cause.
+     */
+    clear(): void;
+    /**
+     * Collected events in settle order, with timestamps rebased onto the
+     * recording clock (`origin` is the recording's start in epoch ms). Requests
+     * still in flight are appended as `pending`, timestamped when they started,
+     * so they sort next to the frame that issued them.
+     */
+    events(origin: number): NetworkEvent[];
+}

package/dist/engine/layers/network.js

@@ -0,0 +1,169 @@
+import { MAX_NETWORK_EVENTS, MAX_NETWORK_URL_LENGTH } from "../../constants.js";
+import { BoundedLog } from "../../utils/bounded-log.js";
+/**
+ * Shorten a URL for display, keeping both ends: the path says what was asked
+ * for and the tail usually carries the identifying part of a query string.
+ * data: URIs are collapsed outright — they are content, not an address.
+ */
+export function shortenUrl(url, maxLength = MAX_NETWORK_URL_LENGTH) {
+    if (url.startsWith("data:")) {
+        const comma = url.indexOf(",");
+        const head = comma === -1 ? url.slice(0, 40) : url.slice(0, Math.min(comma, 40));
+        return `${head},…(${url.length} chars)`;
+    }
+    if (url.length <= maxLength)
+        return url;
+    const keepEnd = Math.floor((maxLength - 1) / 3);
+    const keepStart = maxLength - 1 - keepEnd;
+    return `${url.slice(0, keepStart)}…${url.slice(url.length - keepEnd)}`;
+}
+/** A response worth keeping when the cap is full: anything that failed or errored. */
+function isNotable(record) {
+    return record.error !== undefined || record.status === 0 || record.status >= 400;
+}
+export class NetworkCollector {
+    #page;
+    #limit;
+    #log;
+    /** Requests seen start but not yet settled. Keyed by Playwright's Request identity. */
+    #inFlight = new Map();
+    #attached = false;
+    #onRequest = (request) => {
+        this.#inFlight.set(request, { started: Date.now(), status: 0 });
+    };
+    #onResponse = (response) => {
+        // Read the status synchronously here; at `requestfinished` it would cost an
+        // await, and an async handler would reorder events against the recording.
+        const pending = this.#inFlight.get(response.request());
+        if (pending)
+            pending.status = response.status();
+    };
+    #onFinished = (request) => {
+        this.#settle(request);
+    };
+    #onFailed = (request) => {
+        this.#settle(request, request.failure()?.errorText ?? "request failed");
+    };
+    constructor(page, limit = MAX_NETWORK_EVENTS) {
+        this.#page = page;
+        this.#limit = Math.max(1, Math.floor(limit));
+        this.#log = new BoundedLog(limit, isNotable);
+    }
+    /** Start listening. Idempotent. */
+    attach() {
+        if (this.#attached)
+            return this;
+        this.#attached = true;
+        this.#page.on("request", this.#onRequest);
+        this.#page.on("response", this.#onResponse);
+        this.#page.on("requestfinished", this.#onFinished);
+        this.#page.on("requestfailed", this.#onFailed);
+        return this;
+    }
+    /** Stop listening. Collected events are kept. */
+    detach() {
+        if (!this.#attached)
+            return;
+        this.#attached = false;
+        this.#page.off("request", this.#onRequest);
+        this.#page.off("response", this.#onResponse);
+        this.#page.off("requestfinished", this.#onFinished);
+        this.#page.off("requestfailed", this.#onFailed);
+    }
+    /** Events refused or evicted by the cap, settled and pending alike. */
+    get dropped() {
+        return this.#log.dropped + this.#pendingOverflow();
+    }
+    /** Requests that never settled before the recording ended. */
+    get pending() {
+        return this.#inFlight.size;
+    }
+    /**
+     * Pending requests bypass the log (they are synthesised at read time), so
+     * they need their own bound — a page holding open hundreds of long-poll
+     * connections would otherwise put every one of them in the response.
+     */
+    #pendingOverflow() {
+        return Math.max(0, this.#inFlight.size - this.#limit);
+    }
+    /**
+     * Forget everything collected so far, in-flight requests included. See
+     * `BoundedLog.clear`.
+     *
+     * Dropping the in-flight map is deliberate: a request that was already
+     * running before this window started did not begin here, and reporting it
+     * as this action's pending request would be a lie about cause.
+     */
+    clear() {
+        this.#log.clear();
+        this.#inFlight.clear();
+    }
+    /**
+     * Collected events in settle order, with timestamps rebased onto the
+     * recording clock (`origin` is the recording's start in epoch ms). Requests
+     * still in flight are appended as `pending`, timestamped when they started,
+     * so they sort next to the frame that issued them.
+     */
+    events(origin) {
+        const settled = this.#log.items.map((record) => ({
+            method: record.method,
+            url: record.url,
+            status: record.status,
+            duration_ms: record.duration_ms,
+            timestamp_ms: Math.round(record.at - origin),
+            ...(record.error !== undefined ? { error: record.error } : {}),
+        }));
+        const now = Date.now();
+        let room = this.#limit;
+        for (const [request, info] of this.#inFlight) {
+            if (room-- <= 0)
+                break;
+            settled.push({
+                method: request.method(),
+                url: shortenUrl(request.url()),
+                status: 0,
+                duration_ms: Math.max(0, Math.round(now - info.started)),
+                timestamp_ms: Math.round(info.started - origin),
+                error: "pending",
+            });
+        }
+        return settled.sort((a, b) => a.timestamp_ms - b.timestamp_ms);
+    }
+    /**
+     * Move a request out of flight and into the log. Chromium's timing gives an
+     * absolute `startTime` and offsets from it; `responseEnd` is -1 for a request
+     * that never got that far, so both the duration and the settle time fall back
+     * to wall clock.
+     */
+    #settle(request, error) {
+        const pending = this.#inFlight.get(request);
+        if (!pending)
+            return;
+        this.#inFlight.delete(request);
+        const now = Date.now();
+        let duration = now - pending.started;
+        let at = now;
+        try {
+            const timing = request.timing();
+            if (timing.startTime > 0 && timing.responseEnd >= 0) {
+                duration = timing.responseEnd;
+                at = timing.startTime + timing.responseEnd;
+            }
+        }
+        catch {
+            // Timing is unavailable once the page is gone; wall clock still is.
+        }
+        this.#log.add({
+            at,
+            method: request.method(),
+            // Shortened here rather than on the way out: a page can request a
+            // multi-megabyte data: URI, and holding a hundred of those until the
+            // recording ends is a lot of memory for text that will be elided anyway.
+            url: shortenUrl(request.url()),
+            status: pending.status,
+            duration_ms: Math.max(0, Math.round(duration)),
+            ...(error !== undefined ? { error } : {}),
+        });
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/engine/layers/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../../src/engine/layers/network.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAoCxD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,YAAoB,sBAAsB;IAChF,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,MAAM,IAAI,GAAG,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QACjF,OAAO,GAAG,IAAI,MAAM,GAAG,CAAC,MAAM,SAAS,CAAC;IAC1C,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,SAAS;QAAE,OAAO,GAAG,CAAC;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,SAAS,GAAG,CAAC,GAAG,OAAO,CAAC;IAC1C,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC;AACzE,CAAC;AAED,sFAAsF;AACtF,SAAS,SAAS,CAAC,MAAqB;IACtC,OAAO,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC;AACnF,CAAC;AAED,MAAM,OAAO,gBAAgB;IAClB,KAAK,CAAO;IACZ,MAAM,CAAS;IACf,IAAI,CAA4B;IACzC,uFAAuF;IAC9E,SAAS,GAAG,IAAI,GAAG,EAAqB,CAAC;IAClD,SAAS,GAAG,KAAK,CAAC;IAET,UAAU,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAC/C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC;IAEO,WAAW,GAAG,CAAC,QAAkB,EAAQ,EAAE;QAClD,4EAA4E;QAC5E,0EAA0E;QAC1E,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,IAAI,OAAO;YAAE,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC;IAClD,CAAC,CAAC;IAEO,WAAW,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAChD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC,CAAC;IAEO,SAAS,GAAG,CAAC,OAAgB,EAAQ,EAAE;QAC9C,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,IAAI,gBAAgB,CAAC,CAAC;IAC1E,CAAC,CAAC;IAEF,YAAY,IAAU,EAAE,QAAgB,kBAAkB;QACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC7C,IAAI,CAAC,IAAI,GAAG,IAAI,UAAU,CAAgB,KAAK,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;IAED,mCAAmC;IACnC,MAAM;QACJ,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5C,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,iBAAiB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iDAAiD;IACjD,MAAM;QACJ,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC7C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;IAED,uEAAuE;IACvE,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,gBAAgB,EAAE,CAAC;IACrD,CAAC;IAED,8DAA8D;IAC9D,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,gBAAgB;QACd,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;OAOG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc;QACnB,MAAM,OAAO,GAAmB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC/D,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC;YAC5C,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/D,CAAC,CAAC,CAAC;QAEJ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACvB,KAAK,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC7C,IAAI,IAAI,EAAE,IAAI,CAAC;gBAAE,MAAM;YACvB,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;gBACxB,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;gBAC9B,MAAM,EAAE,CAAC;gBACT,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;gBACxD,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;gBAC/C,KAAK,EAAE,SAAS;aACjB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC;IACjE,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAgB,EAAE,KAAc;QACtC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAE/B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,QAAQ,GAAG,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;QACrC,IAAI,EAAE,GAAG,GAAG,CAAC;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YAChC,IAAI,MAAM,CAAC,SAAS,GAAG,CAAC,IAAI,MAAM,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC;gBACpD,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC;gBAC9B,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC;YAC7C,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YACZ,EAAE;YACF,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE;YACxB,kEAAkE;YAClE,qEAAqE;YACrE,yEAAyE;YACzE,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;YAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,WAAW,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC9C,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,CAAC,CAAC;IACL,CAAC;CACF","sourcesContent":["import type { Page, Request, Response } from \"playwright\";\nimport { MAX_NETWORK_EVENTS, MAX_NETWORK_URL_LENGTH } from \"../../constants.js\";\nimport type { NetworkEvent } from \"../../types.js\";\nimport { BoundedLog } from \"../../utils/bounded-log.js\";\n\n/**\n * Network layer.\n *\n * Records one event per request that settles during a capture: method, url,\n * status, how long it took, and when it landed. A request is timestamped at\n * the moment it *settled*, not when it was sent, because that is the instant\n * that can explain the frame next to it — a spinner disappears when the\n * response arrives, not when the fetch was issued.\n *\n * Durations come from Chromium's own `request.timing()` rather than from wall\n * clock in the event handler, so they measure the request and not Node's event\n * loop. Failed requests have no timing, and fall back to wall clock.\n *\n * Requests still in flight when the recording ends are reported too, as\n * `status: 0, error: \"pending\"` — a request that never comes back is a finding,\n * and silently dropping it would hide exactly the bug a developer is chasing.\n */\n\n/** One settled request, stamped with absolute (epoch) time and an already-shortened url. */\nexport interface NetworkRecord {\n  at: number;\n  method: string;\n  url: string;\n  status: number;\n  duration_ms: number;\n  error?: string;\n}\n\n/** In-flight bookkeeping for a request we have seen start but not settle. */\ninterface InFlight {\n  started: number;\n  status: number;\n}\n\n/**\n * Shorten a URL for display, keeping both ends: the path says what was asked\n * for and the tail usually carries the identifying part of a query string.\n * data: URIs are collapsed outright — they are content, not an address.\n */\nexport function shortenUrl(url: string, maxLength: number = MAX_NETWORK_URL_LENGTH): string {\n  if (url.startsWith(\"data:\")) {\n    const comma = url.indexOf(\",\");\n    const head = comma === -1 ? url.slice(0, 40) : url.slice(0, Math.min(comma, 40));\n    return `${head},…(${url.length} chars)`;\n  }\n  if (url.length <= maxLength) return url;\n  const keepEnd = Math.floor((maxLength - 1) / 3);\n  const keepStart = maxLength - 1 - keepEnd;\n  return `${url.slice(0, keepStart)}…${url.slice(url.length - keepEnd)}`;\n}\n\n/** A response worth keeping when the cap is full: anything that failed or errored. */\nfunction isNotable(record: NetworkRecord): boolean {\n  return record.error !== undefined || record.status === 0 || record.status >= 400;\n}\n\nexport class NetworkCollector {\n  readonly #page: Page;\n  readonly #limit: number;\n  readonly #log: BoundedLog<NetworkRecord>;\n  /** Requests seen start but not yet settled. Keyed by Playwright's Request identity. */\n  readonly #inFlight = new Map<Request, InFlight>();\n  #attached = false;\n\n  readonly #onRequest = (request: Request): void => {\n    this.#inFlight.set(request, { started: Date.now(), status: 0 });\n  };\n\n  readonly #onResponse = (response: Response): void => {\n    // Read the status synchronously here; at `requestfinished` it would cost an\n    // await, and an async handler would reorder events against the recording.\n    const pending = this.#inFlight.get(response.request());\n    if (pending) pending.status = response.status();\n  };\n\n  readonly #onFinished = (request: Request): void => {\n    this.#settle(request);\n  };\n\n  readonly #onFailed = (request: Request): void => {\n    this.#settle(request, request.failure()?.errorText ?? \"request failed\");\n  };\n\n  constructor(page: Page, limit: number = MAX_NETWORK_EVENTS) {\n    this.#page = page;\n    this.#limit = Math.max(1, Math.floor(limit));\n    this.#log = new BoundedLog<NetworkRecord>(limit, isNotable);\n  }\n\n  /** Start listening. Idempotent. */\n  attach(): this {\n    if (this.#attached) return this;\n    this.#attached = true;\n    this.#page.on(\"request\", this.#onRequest);\n    this.#page.on(\"response\", this.#onResponse);\n    this.#page.on(\"requestfinished\", this.#onFinished);\n    this.#page.on(\"requestfailed\", this.#onFailed);\n    return this;\n  }\n\n  /** Stop listening. Collected events are kept. */\n  detach(): void {\n    if (!this.#attached) return;\n    this.#attached = false;\n    this.#page.off(\"request\", this.#onRequest);\n    this.#page.off(\"response\", this.#onResponse);\n    this.#page.off(\"requestfinished\", this.#onFinished);\n    this.#page.off(\"requestfailed\", this.#onFailed);\n  }\n\n  /** Events refused or evicted by the cap, settled and pending alike. */\n  get dropped(): number {\n    return this.#log.dropped + this.#pendingOverflow();\n  }\n\n  /** Requests that never settled before the recording ended. */\n  get pending(): number {\n    return this.#inFlight.size;\n  }\n\n  /**\n   * Pending requests bypass the log (they are synthesised at read time), so\n   * they need their own bound — a page holding open hundreds of long-poll\n   * connections would otherwise put every one of them in the response.\n   */\n  #pendingOverflow(): number {\n    return Math.max(0, this.#inFlight.size - this.#limit);\n  }\n\n  /**\n   * Forget everything collected so far, in-flight requests included. See\n   * `BoundedLog.clear`.\n   *\n   * Dropping the in-flight map is deliberate: a request that was already\n   * running before this window started did not begin here, and reporting it\n   * as this action's pending request would be a lie about cause.\n   */\n  clear(): void {\n    this.#log.clear();\n    this.#inFlight.clear();\n  }\n\n  /**\n   * Collected events in settle order, with timestamps rebased onto the\n   * recording clock (`origin` is the recording's start in epoch ms). Requests\n   * still in flight are appended as `pending`, timestamped when they started,\n   * so they sort next to the frame that issued them.\n   */\n  events(origin: number): NetworkEvent[] {\n    const settled: NetworkEvent[] = this.#log.items.map((record) => ({\n      method: record.method,\n      url: record.url,\n      status: record.status,\n      duration_ms: record.duration_ms,\n      timestamp_ms: Math.round(record.at - origin),\n      ...(record.error !== undefined ? { error: record.error } : {}),\n    }));\n\n    const now = Date.now();\n    let room = this.#limit;\n    for (const [request, info] of this.#inFlight) {\n      if (room-- <= 0) break;\n      settled.push({\n        method: request.method(),\n        url: shortenUrl(request.url()),\n        status: 0,\n        duration_ms: Math.max(0, Math.round(now - info.started)),\n        timestamp_ms: Math.round(info.started - origin),\n        error: \"pending\",\n      });\n    }\n    return settled.sort((a, b) => a.timestamp_ms - b.timestamp_ms);\n  }\n\n  /**\n   * Move a request out of flight and into the log. Chromium's timing gives an\n   * absolute `startTime` and offsets from it; `responseEnd` is -1 for a request\n   * that never got that far, so both the duration and the settle time fall back\n   * to wall clock.\n   */\n  #settle(request: Request, error?: string): void {\n    const pending = this.#inFlight.get(request);\n    if (!pending) return;\n    this.#inFlight.delete(request);\n\n    const now = Date.now();\n    let duration = now - pending.started;\n    let at = now;\n    try {\n      const timing = request.timing();\n      if (timing.startTime > 0 && timing.responseEnd >= 0) {\n        duration = timing.responseEnd;\n        at = timing.startTime + timing.responseEnd;\n      }\n    } catch {\n      // Timing is unavailable once the page is gone; wall clock still is.\n    }\n\n    this.#log.add({\n      at,\n      method: request.method(),\n      // Shortened here rather than on the way out: a page can request a\n      // multi-megabyte data: URI, and holding a hundred of those until the\n      // recording ends is a lot of memory for text that will be elided anyway.\n      url: shortenUrl(request.url()),\n      status: pending.status,\n      duration_ms: Math.max(0, Math.round(duration)),\n      ...(error !== undefined ? { error } : {}),\n    });\n  }\n}\n"]}

package/dist/engine/layers/performance.d.ts

@@ -0,0 +1,55 @@
+import type { Page } from "playwright";
+import type { PerformanceInfo } from "../../types.js";
+import { type InstallOptions } from "./probe.js";
+export type PerfKind = "paint" | "lcp" | "shift";
+/** One performance entry, as pushed by the page. Timestamps are absolute (epoch ms). */
+export interface RawPerfRecord {
+    /** Absolute time the browser recorded the entry (not when the observer saw it). */
+    t: number;
+    kind: PerfKind;
+    /** `entry.startTime` — ms since this document's navigation start. */
+    start: number;
+    /** Paint entry name: "first-contentful-paint" or "first-paint". */
+    name?: string;
+    /** Layout shift score. */
+    value?: number;
+}
+/** One performance entry, rebased onto the recording clock. */
+export interface PerfSample {
+    timestamp_ms: number;
+    kind: PerfKind;
+    start_ms: number;
+    name?: string;
+    value?: number;
+}
+export declare class PerformanceCollector {
+    #private;
+    constructor(page: Page, limit?: number);
+    /**
+     * Install the probe. Call before the page navigates, or pass
+     * `{ runNow: true }` to also measure the document that is already loaded —
+     * `buffered: true` means the observers still receive what it recorded
+     * earlier, so a page that painted before this ran is not lost.
+     */
+    attach(options?: InstallOptions): Promise<this>;
+    /** Entries the cap refused. */
+    get dropped(): number;
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear(): void;
+    /**
+     * Collected entries in time order, rebased onto the recording clock
+     * (`origin` is the recording's start in epoch ms). Entries from before the
+     * recording started keep their negative timestamp: first paint routinely
+     * happens before frame 0, and belongs on the first card.
+     */
+    samples(origin: number): PerfSample[];
+}
+/**
+ * Reduce one card's entries to the numbers worth printing beside it.
+ *
+ * Only what actually happened in this window is reported — LCP is not repeated
+ * on every card after it was measured, because a number that never changes on
+ * twenty cards is noise, not context. Returns undefined when the window is
+ * empty, so cards with nothing to report carry no Performance section at all.
+ */
+export declare function summarisePerformance(samples: PerfSample[]): PerformanceInfo | undefined;

package/dist/engine/layers/performance.js

@@ -0,0 +1,215 @@
+import { MAX_PERF_SAMPLES } from "../../constants.js";
+import { installProbe, probeConfig } from "./probe.js";
+/**
+ * Performance layer.
+ *
+ * Three PerformanceObservers installed at document start report when the
+ * browser first painted, when it settled on the largest contentful element,
+ * and every time the layout jumped. Each entry carries two clocks:
+ * `entry.startTime` (the metric itself — ms since *this document's*
+ * navigation start, so an LCP of 800ms means the same thing here as in
+ * Lighthouse) and, derived from it and `performance.timeOrigin`, the
+ * wall-clock instant it happened, which decides the diff card it lands on.
+ *
+ * `buffered: true` means the observers also receive entries recorded before
+ * they were registered, so nothing is lost to the gap between document start
+ * and the first observer callback. After a navigation the timers restart with
+ * the new document, which is correct: the new page's LCP is not a continuation
+ * of the old page's.
+ *
+ * Layout shifts are counted whether or not they followed user input, unlike
+ * Chrome's CLS. FrameWatch is watching what the page *looks* like, and a jump
+ * that happens right after a click is often exactly the one being hunted.
+ */
+const BINDING = "__framewatch_perf";
+/**
+ * The page-side probe. Written against `globalThis` for the same reasons as
+ * the DOM probe: no DOM lib at compile time, and everything it touches may be
+ * missing in the page it lands in (PerformanceObserver entry types vary by
+ * browser and are gated behind flags in some embedded contexts).
+ */
+const PERF_PROBE = (config) => {
+    const g = globalThis;
+    // Main frame only: LCP, FCP and layout shift are whole-page metrics.
+    if (g.top && g.top !== g)
+        return;
+    // The probe can be asked for twice on one document (installed on a page that
+    // is already open, then re-run by the init script); a second set of observers
+    // would report every entry twice.
+    const installed = config.binding + "_observing";
+    if (g[installed])
+        return;
+    g[installed] = true;
+    const send = g[config.binding];
+    if (typeof send !== "function" || typeof g.PerformanceObserver !== "function")
+        return;
+    let queue = [];
+    let scheduled = false;
+    let budget = config.max_records;
+    const flush = () => {
+        scheduled = false;
+        if (queue.length === 0)
+            return;
+        const batch = queue;
+        queue = [];
+        try {
+            const result = send(batch);
+            if (result && typeof result.catch === "function")
+                result.catch(() => { });
+        }
+        catch {
+            // The page is being torn down; there is nowhere left to push to.
+        }
+    };
+    const push = (record) => {
+        if (budget <= 0)
+            return;
+        budget--;
+        if (queue.length >= config.max_batch)
+            flush();
+        queue.push(record);
+        if (!scheduled) {
+            scheduled = true;
+            g.setTimeout(flush, config.flush_ms);
+        }
+    };
+    try {
+        g.addEventListener("pagehide", flush, true);
+    }
+    catch {
+        // Not fatal: records wait for the timer instead.
+    }
+    // `entry.startTime` is measured from this document's navigation start, and
+    // `performance.timeOrigin` is that instant in epoch ms — so the two together
+    // give the wall-clock moment the browser actually painted or shifted. That is
+    // what a record has to be stamped with: an observer callback can run long
+    // after the entry it reports (LCP in particular), and stamping with Date.now()
+    // would file a paint on whichever frame happened to be next.
+    const origin = typeof g.performance?.timeOrigin === "number" ? g.performance.timeOrigin : null;
+    const observe = (type, kind) => {
+        try {
+            new g.PerformanceObserver((list) => {
+                for (const entry of list.getEntries()) {
+                    const start = typeof entry.startTime === "number" ? entry.startTime : 0;
+                    push({
+                        t: origin === null ? Date.now() : origin + start,
+                        kind,
+                        start,
+                        ...(kind === "paint" ? { name: String(entry.name || "") } : {}),
+                        ...(kind === "shift" ? { value: typeof entry.value === "number" ? entry.value : 0 } : {}),
+                    });
+                }
+            }).observe({ type, buffered: true });
+        }
+        catch {
+            // This entry type is unsupported here; the others still report.
+        }
+    };
+    observe("paint", "paint");
+    observe("largest-contentful-paint", "lcp");
+    observe("layout-shift", "shift");
+};
+export class PerformanceCollector {
+    #page;
+    #limit;
+    #records = [];
+    #dropped = 0;
+    constructor(page, limit = MAX_PERF_SAMPLES) {
+        this.#page = page;
+        this.#limit = Math.max(1, limit);
+    }
+    /**
+     * Install the probe. Call before the page navigates, or pass
+     * `{ runNow: true }` to also measure the document that is already loaded —
+     * `buffered: true` means the observers still receive what it recorded
+     * earlier, so a page that painted before this ran is not lost.
+     */
+    async attach(options = {}) {
+        const config = probeConfig(BINDING);
+        await installProbe(this.#page, config, PERF_PROBE, (batch) => this.#ingest(batch), options);
+        return this;
+    }
+    /** Entries the cap refused. */
+    get dropped() {
+        return this.#dropped;
+    }
+    /** Forget everything collected so far. See `BoundedLog.clear`. */
+    clear() {
+        this.#records.length = 0;
+        this.#dropped = 0;
+    }
+    /**
+     * Collected entries in time order, rebased onto the recording clock
+     * (`origin` is the recording's start in epoch ms). Entries from before the
+     * recording started keep their negative timestamp: first paint routinely
+     * happens before frame 0, and belongs on the first card.
+     */
+    samples(origin) {
+        return this.#records.map((record) => ({
+            timestamp_ms: Math.round(record.t - origin),
+            kind: record.kind,
+            start_ms: Math.round(record.start),
+            ...(record.name !== undefined ? { name: record.name } : {}),
+            ...(record.value !== undefined ? { value: record.value } : {}),
+        }));
+    }
+    #ingest(batch) {
+        for (const record of batch) {
+            // The page pushes this, so nothing about it is trusted.
+            if (!record || typeof record.t !== "number" || typeof record.start !== "number")
+                continue;
+            if (record.kind !== "paint" && record.kind !== "lcp" && record.kind !== "shift")
+                continue;
+            if (this.#records.length >= this.#limit) {
+                this.#dropped++;
+                continue;
+            }
+            this.#records.push(record);
+        }
+    }
+}
+/**
+ * Reduce one card's entries to the numbers worth printing beside it.
+ *
+ * Only what actually happened in this window is reported — LCP is not repeated
+ * on every card after it was measured, because a number that never changes on
+ * twenty cards is noise, not context. Returns undefined when the window is
+ * empty, so cards with nothing to report carry no Performance section at all.
+ */
+export function summarisePerformance(samples) {
+    if (samples.length === 0)
+        return undefined;
+    let paint;
+    let lcp;
+    let shifts = 0;
+    let score = 0;
+    for (const sample of samples) {
+        if (sample.kind === "paint") {
+            // Prefer first-contentful-paint; first-paint is the fallback when the
+            // browser reported only that (both arrive together on a normal load).
+            if (!paint || (paint.name !== "first-contentful-paint" && sample.name === "first-contentful-paint")) {
+                paint = sample;
+            }
+        }
+        else if (sample.kind === "lcp") {
+            // LCP grows as the browser finds larger elements: the last one wins.
+            if (!lcp || sample.start_ms >= lcp.start_ms)
+                lcp = sample;
+        }
+        else {
+            shifts++;
+            score += sample.value ?? 0;
+        }
+    }
+    const info = {};
+    if (paint)
+        info.paint_time_ms = paint.start_ms;
+    if (shifts > 0) {
+        info.layout_shifts = shifts;
+        info.layout_shift_score = Math.round(score * 10_000) / 10_000;
+    }
+    if (lcp)
+        info.lcp_ms = lcp.start_ms;
+    return Object.keys(info).length > 0 ? info : undefined;
+}
+//# sourceMappingURL=performance.js.map

package/dist/engine/layers/performance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance.js","sourceRoot":"","sources":["../../../src/engine/layers/performance.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from \"playwright\";\nimport { MAX_PERF_SAMPLES } from \"../../constants.js\";\nimport type { PerformanceInfo } from \"../../types.js\";\nimport { installProbe, probeConfig, type InstallOptions, type ProbeConfig } from \"./probe.js\";\n\n/**\n * Performance layer.\n *\n * Three PerformanceObservers installed at document start report when the\n * browser first painted, when it settled on the largest contentful element,\n * and every time the layout jumped. Each entry carries two clocks:\n * `entry.startTime` (the metric itself — ms since *this document's*\n * navigation start, so an LCP of 800ms means the same thing here as in\n * Lighthouse) and, derived from it and `performance.timeOrigin`, the\n * wall-clock instant it happened, which decides the diff card it lands on.\n *\n * `buffered: true` means the observers also receive entries recorded before\n * they were registered, so nothing is lost to the gap between document start\n * and the first observer callback. After a navigation the timers restart with\n * the new document, which is correct: the new page's LCP is not a continuation\n * of the old page's.\n *\n * Layout shifts are counted whether or not they followed user input, unlike\n * Chrome's CLS. FrameWatch is watching what the page *looks* like, and a jump\n * that happens right after a click is often exactly the one being hunted.\n */\n\nconst BINDING = \"__framewatch_perf\";\n\nexport type PerfKind = \"paint\" | \"lcp\" | \"shift\";\n\n/** One performance entry, as pushed by the page. Timestamps are absolute (epoch ms). */\nexport interface RawPerfRecord {\n  /** Absolute time the browser recorded the entry (not when the observer saw it). */\n  t: number;\n  kind: PerfKind;\n  /** `entry.startTime` — ms since this document's navigation start. */\n  start: number;\n  /** Paint entry name: \"first-contentful-paint\" or \"first-paint\". */\n  name?: string;\n  /** Layout shift score. */\n  value?: number;\n}\n\n/** One performance entry, rebased onto the recording clock. */\nexport interface PerfSample {\n  timestamp_ms: number;\n  kind: PerfKind;\n  start_ms: number;\n  name?: string;\n  value?: number;\n}\n\n/**\n * The page-side probe. Written against `globalThis` for the same reasons as\n * the DOM probe: no DOM lib at compile time, and everything it touches may be\n * missing in the page it lands in (PerformanceObserver entry types vary by\n * browser and are gated behind flags in some embedded contexts).\n */\nconst PERF_PROBE = (config: ProbeConfig): void => {\n  const g = globalThis as any;\n  // Main frame only: LCP, FCP and layout shift are whole-page metrics.\n  if (g.top && g.top !== g) return;\n  // The probe can be asked for twice on one document (installed on a page that\n  // is already open, then re-run by the init script); a second set of observers\n  // would report every entry twice.\n  const installed = config.binding + \"_observing\";\n  if (g[installed]) return;\n  g[installed] = true;\n  const send = g[config.binding];\n  if (typeof send !== \"function\" || typeof g.PerformanceObserver !== \"function\") return;\n\n  let queue: unknown[] = [];\n  let scheduled = false;\n  let budget = config.max_records;\n\n  const flush = (): void => {\n    scheduled = false;\n    if (queue.length === 0) return;\n    const batch = queue;\n    queue = [];\n    try {\n      const result = send(batch);\n      if (result && typeof result.catch === \"function\") result.catch(() => {});\n    } catch {\n      // The page is being torn down; there is nowhere left to push to.\n    }\n  };\n\n  const push = (record: unknown): void => {\n    if (budget <= 0) return;\n    budget--;\n    if (queue.length >= config.max_batch) flush();\n    queue.push(record);\n    if (!scheduled) {\n      scheduled = true;\n      g.setTimeout(flush, config.flush_ms);\n    }\n  };\n\n  try {\n    g.addEventListener(\"pagehide\", flush, true);\n  } catch {\n    // Not fatal: records wait for the timer instead.\n  }\n\n  // `entry.startTime` is measured from this document's navigation start, and\n  // `performance.timeOrigin` is that instant in epoch ms — so the two together\n  // give the wall-clock moment the browser actually painted or shifted. That is\n  // what a record has to be stamped with: an observer callback can run long\n  // after the entry it reports (LCP in particular), and stamping with Date.now()\n  // would file a paint on whichever frame happened to be next.\n  const origin = typeof g.performance?.timeOrigin === \"number\" ? g.performance.timeOrigin : null;\n\n  const observe = (type: string, kind: string): void => {\n    try {\n      new g.PerformanceObserver((list: any) => {\n        for (const entry of list.getEntries()) {\n          const start = typeof entry.startTime === \"number\" ? entry.startTime : 0;\n          push({\n            t: origin === null ? Date.now() : origin + start,\n            kind,\n            start,\n            ...(kind === \"paint\" ? { name: String(entry.name || \"\") } : {}),\n            ...(kind === \"shift\" ? { value: typeof entry.value === \"number\" ? entry.value : 0 } : {}),\n          });\n        }\n      }).observe({ type, buffered: true });\n    } catch {\n      // This entry type is unsupported here; the others still report.\n    }\n  };\n\n  observe(\"paint\", \"paint\");\n  observe(\"largest-contentful-paint\", \"lcp\");\n  observe(\"layout-shift\", \"shift\");\n};\n\nexport class PerformanceCollector {\n  readonly #page: Page;\n  readonly #limit: number;\n  readonly #records: RawPerfRecord[] = [];\n  #dropped = 0;\n\n  constructor(page: Page, limit: number = MAX_PERF_SAMPLES) {\n    this.#page = page;\n    this.#limit = Math.max(1, limit);\n  }\n\n  /**\n   * Install the probe. Call before the page navigates, or pass\n   * `{ runNow: true }` to also measure the document that is already loaded —\n   * `buffered: true` means the observers still receive what it recorded\n   * earlier, so a page that painted before this ran is not lost.\n   */\n  async attach(options: InstallOptions = {}): Promise<this> {\n    const config = probeConfig(BINDING);\n    await installProbe<RawPerfRecord>(this.#page, config, PERF_PROBE, (batch) => this.#ingest(batch), options);\n    return this;\n  }\n\n  /** Entries the cap refused. */\n  get dropped(): number {\n    return this.#dropped;\n  }\n\n  /** Forget everything collected so far. See `BoundedLog.clear`. */\n  clear(): void {\n    this.#records.length = 0;\n    this.#dropped = 0;\n  }\n\n  /**\n   * Collected entries in time order, rebased onto the recording clock\n   * (`origin` is the recording's start in epoch ms). Entries from before the\n   * recording started keep their negative timestamp: first paint routinely\n   * happens before frame 0, and belongs on the first card.\n   */\n  samples(origin: number): PerfSample[] {\n    return this.#records.map((record) => ({\n      timestamp_ms: Math.round(record.t - origin),\n      kind: record.kind,\n      start_ms: Math.round(record.start),\n      ...(record.name !== undefined ? { name: record.name } : {}),\n      ...(record.value !== undefined ? { value: record.value } : {}),\n    }));\n  }\n\n  #ingest(batch: RawPerfRecord[]): void {\n    for (const record of batch) {\n      // The page pushes this, so nothing about it is trusted.\n      if (!record || typeof record.t !== \"number\" || typeof record.start !== \"number\") continue;\n      if (record.kind !== \"paint\" && record.kind !== \"lcp\" && record.kind !== \"shift\") continue;\n      if (this.#records.length >= this.#limit) {\n        this.#dropped++;\n        continue;\n      }\n      this.#records.push(record);\n    }\n  }\n}\n\n/**\n * Reduce one card's entries to the numbers worth printing beside it.\n *\n * Only what actually happened in this window is reported — LCP is not repeated\n * on every card after it was measured, because a number that never changes on\n * twenty cards is noise, not context. Returns undefined when the window is\n * empty, so cards with nothing to report carry no Performance section at all.\n */\nexport function summarisePerformance(samples: PerfSample[]): PerformanceInfo | undefined {\n  if (samples.length === 0) return undefined;\n\n  let paint: PerfSample | undefined;\n  let lcp: PerfSample | undefined;\n  let shifts = 0;\n  let score = 0;\n\n  for (const sample of samples) {\n    if (sample.kind === \"paint\") {\n      // Prefer first-contentful-paint; first-paint is the fallback when the\n      // browser reported only that (both arrive together on a normal load).\n      if (!paint || (paint.name !== \"first-contentful-paint\" && sample.name === \"first-contentful-paint\")) {\n        paint = sample;\n      }\n    } else if (sample.kind === \"lcp\") {\n      // LCP grows as the browser finds larger elements: the last one wins.\n      if (!lcp || sample.start_ms >= lcp.start_ms) lcp = sample;\n    } else {\n      shifts++;\n      score += sample.value ?? 0;\n    }\n  }\n\n  const info: PerformanceInfo = {};\n  if (paint) info.paint_time_ms = paint.start_ms;\n  if (shifts > 0) {\n    info.layout_shifts = shifts;\n    info.layout_shift_score = Math.round(score * 10_000) / 10_000;\n  }\n  if (lcp) info.lcp_ms = lcp.start_ms;\n  return Object.keys(info).length > 0 ? info : undefined;\n}\n"]}

package/dist/engine/layers/probe.d.ts

@@ -0,0 +1,50 @@
+import type { Page } from "playwright";
+/**
+ * In-page probe plumbing, shared by the DOM and performance layers.
+ *
+ * Console and network are Playwright events, but "what changed in the DOM" and
+ * "when did the browser paint" only exist inside the page, so those two layers
+ * inject an observer and push what it sees back to Node.
+ *
+ * The push is an `exposeBinding` function rather than one `page.evaluate` at
+ * the end of the recording, for one reason: a navigation destroys the document
+ * and everything buffered in it. Bindings and init scripts are reinstalled on
+ * every new document, so a capture that navigates keeps the records from both
+ * pages — and a capture whose page freezes or dies keeps whatever it pushed
+ * before it went.
+ *
+ * Each probe inlines its own batching queue (page scripts cannot import, and
+ * `eval`ing a shared one would break on any page with a strict CSP). Records
+ * are stamped when they are *made*, never when their batch is flushed, so
+ * batching cannot move a record onto the wrong diff card.
+ */
+/** Config handed to the page-side script. Must stay JSON-serialisable. */
+export interface ProbeConfig {
+    /** Name of the `window` function the page pushes batches through. */
+    binding: string;
+    /** How long to coalesce records before pushing a batch. */
+    flush_ms: number;
+    /** Records one batch may carry. */
+    max_batch: number;
+    /** Records the probe may push over the lifetime of one document. */
+    max_records: number;
+}
+export declare function probeConfig(binding: string): ProbeConfig;
+/**
+ * Expose `config.binding` on the page and arrange for `script` to run at the
+ * start of every document (including after a navigation).
+ *
+ * `onBatch` must never throw: it runs as the resolution of a promise the page
+ * is holding, so a throw here surfaces inside the page under test as an
+ * unhandled rejection — which the console layer would then dutifully report as
+ * a bug in the user's app. It is wrapped here so callers cannot get that wrong.
+ */
+export declare function installProbe<T>(page: Page, config: ProbeConfig, script: (config: ProbeConfig) => void, onBatch: (records: T[]) => void, options?: InstallOptions): Promise<void>;
+export interface InstallOptions {
+    /**
+     * Also run the probe against the document the page already has. Needed for
+     * `framewatch_interact`, which acts on a page that is open before the layer
+     * is asked for; captures attach before navigating and do not need it.
+     */
+    runNow?: boolean;
+}

package/dist/engine/layers/probe.js

@@ -0,0 +1,39 @@
+import { LAYER_FLUSH_MS, MAX_LAYER_BATCH, MAX_LAYER_RECORDS_PER_DOCUMENT } from "../../constants.js";
+export function probeConfig(binding) {
+    return {
+        binding,
+        flush_ms: LAYER_FLUSH_MS,
+        max_batch: MAX_LAYER_BATCH,
+        max_records: MAX_LAYER_RECORDS_PER_DOCUMENT,
+    };
+}
+/**
+ * Expose `config.binding` on the page and arrange for `script` to run at the
+ * start of every document (including after a navigation).
+ *
+ * `onBatch` must never throw: it runs as the resolution of a promise the page
+ * is holding, so a throw here surfaces inside the page under test as an
+ * unhandled rejection — which the console layer would then dutifully report as
+ * a bug in the user's app. It is wrapped here so callers cannot get that wrong.
+ */
+export async function installProbe(page, config, script, onBatch, options = {}) {
+    await page.exposeBinding(config.binding, (_source, batch) => {
+        try {
+            if (Array.isArray(batch))
+                onBatch(batch);
+        }
+        catch {
+            // A collector must never break the page it is watching.
+        }
+    });
+    await page.addInitScript(script, config);
+    if (options.runNow === true) {
+        // Init scripts only reach *new* documents, so a probe installed on a page
+        // that is already loaded would watch nothing until the next navigation.
+        // Running it once by hand covers the document that is already there; the
+        // probes guard against being installed twice, so the init script running
+        // later on the same document is harmless.
+        await page.evaluate(script, config).catch(() => { });
+    }
+}
+//# sourceMappingURL=probe.js.map