pi-browser-harness 0.12.0 → 0.14.0

package/src/cdp/commands.ts

@@ -1,3 +1,17 @@
+// The typed CDP command table — the extension point for everything the harness sends to Chrome.
+//
+// To add a command:
+//   1. Look the method up in the Chrome DevTools Protocol viewer (https://chromedevtools.github.io/devtools-protocol/).
+//   2. Add a `"Domain.method": cmd(ParamsSchema, ResultSchema)` entry below, in its domain's block.
+//      - Mark optional protocol fields with `Type.Optional(...)` — never with `Type.Union([..., Type.Undefined()])`:
+//        the project compiles with exactOptionalPropertyTypes, so callers must omit a field rather than pass undefined.
+//      - Use `Type.Union([Type.Literal(...), ...])` for enumerated strings so a typo fails to compile.
+//      - Result schemas are `additionalProperties: true` where Chrome may add fields; param schemas are closed.
+//   3. `ParamsOf<"Domain.method">` / `ResultOf<"Domain.method">` now exist, and `session.call("Domain.method", ...)`
+//      requires params exactly when the schema has a required key (see `CallArgs` in session.ts).
+//   4. Results are validated at runtime by `decodeResult`; a payload that does not match is an `invalid_response` error.
+// Events live in ./events.ts and follow the same pattern.
+
 import { Type, type Static, type TSchema } from "typebox";
 import { Compile } from "typebox/compile";
 import { type Result, err, ok } from "../util/result";
@@ -77,6 +91,82 @@ const AxNode = Type.Object(
 
 export type AxNodeResult = Static<typeof AxNode>;
 
+// Page.Viewport: a clip rectangle in CSS pixels.
+const Viewport = Type.Object({
+  x: Type.Number(),
+  y: Type.Number(),
+  width: Type.Number(),
+  height: Type.Number(),
+  scale: Type.Number(),
+});
+
+// Browser.setDownloadBehavior — "allowAndName" saves under the download's GUID; "default" restores Chrome's own policy.
+const DownloadBehavior = Type.Union([
+  Type.Literal("deny"),
+  Type.Literal("allow"),
+  Type.Literal("allowAndName"),
+  Type.Literal("default"),
+]);
+
+const ScreenshotFormat = Type.Union([Type.Literal("jpeg"), Type.Literal("png"), Type.Literal("webp")]);
+
+// Input.MouseButton
+const MouseButton = Type.Union([
+  Type.Literal("none"),
+  Type.Literal("left"),
+  Type.Literal("middle"),
+  Type.Literal("right"),
+  Type.Literal("back"),
+  Type.Literal("forward"),
+]);
+
+const MouseEventType = Type.Union([
+  Type.Literal("mousePressed"),
+  Type.Literal("mouseReleased"),
+  Type.Literal("mouseMoved"),
+  Type.Literal("mouseWheel"),
+]);
+
+const KeyEventType = Type.Union([
+  Type.Literal("keyDown"),
+  Type.Literal("keyUp"),
+  Type.Literal("rawKeyDown"),
+  Type.Literal("char"),
+]);
+
+const DragEventType = Type.Union([
+  Type.Literal("dragEnter"),
+  Type.Literal("dragOver"),
+  Type.Literal("drop"),
+  Type.Literal("dragCancel"),
+]);
+
+// Input.DragDataItem / Input.DragData. `data` is the payload as a string (binary payloads are base64).
+const DragDataItem = Type.Object({
+  mimeType: Type.String(),
+  data: Type.String(),
+  title: Type.Optional(Type.String()),
+  baseURL: Type.Optional(Type.String()),
+});
+
+const DragData = Type.Object({
+  items: Type.Array(DragDataItem),
+  files: Type.Optional(Type.Array(Type.String())),
+  // Bit field of allowed operations: 1=Copy, 2=Link, 16=Move.
+  dragOperationsMask: Type.Integer(),
+});
+
+// Emulation.ScreenOrientation
+const ScreenOrientation = Type.Object({
+  type: Type.Union([
+    Type.Literal("portraitPrimary"),
+    Type.Literal("portraitSecondary"),
+    Type.Literal("landscapePrimary"),
+    Type.Literal("landscapeSecondary"),
+  ]),
+  angle: Type.Integer(),
+});
+
 export const COMMANDS = {
   "Target.attachToTarget": cmd(
     Type.Object({ targetId: Type.String(), flatten: Type.Optional(Type.Boolean()) }),
@@ -117,7 +207,8 @@ export const COMMANDS = {
   ),
   "Browser.setDownloadBehavior": cmd(
     Type.Object({
-      behavior: Type.String(),
+      behavior: DownloadBehavior,
+      browserContextId: Type.Optional(Type.String()),
       downloadPath: Type.Optional(Type.String()),
       eventsEnabled: Type.Optional(Type.Boolean()),
     }),
@@ -147,14 +238,39 @@ export const COMMANDS = {
   "Page.navigateToHistoryEntry": cmd(Type.Object({ entryId: Type.Number() }), Empty),
   "Page.captureScreenshot": cmd(
     Type.Object({
-      format: Type.Optional(Type.String()),
-      quality: Type.Optional(Type.Number()),
-      clip: Type.Optional(Type.Unknown()),
+      format: Type.Optional(ScreenshotFormat),
+      // 0–100, jpeg and webp only.
+      quality: Type.Optional(Type.Integer()),
+      clip: Type.Optional(Viewport),
+      fromSurface: Type.Optional(Type.Boolean()),
       captureBeyondViewport: Type.Optional(Type.Boolean()),
+      optimizeForSpeed: Type.Optional(Type.Boolean()),
     }),
     Type.Object({ data: Type.String() }),
   ),
-  "Page.printToPDF": cmd(Type.Object({}, { additionalProperties: true }), Type.Object({ data: Type.String() })),
+  "Page.printToPDF": cmd(
+    Type.Object({
+      landscape: Type.Optional(Type.Boolean()),
+      displayHeaderFooter: Type.Optional(Type.Boolean()),
+      printBackground: Type.Optional(Type.Boolean()),
+      scale: Type.Optional(Type.Number()),
+      // Paper size and margins are in inches.
+      paperWidth: Type.Optional(Type.Number()),
+      paperHeight: Type.Optional(Type.Number()),
+      marginTop: Type.Optional(Type.Number()),
+      marginBottom: Type.Optional(Type.Number()),
+      marginLeft: Type.Optional(Type.Number()),
+      marginRight: Type.Optional(Type.Number()),
+      pageRanges: Type.Optional(Type.String()),
+      headerTemplate: Type.Optional(Type.String()),
+      footerTemplate: Type.Optional(Type.String()),
+      preferCSSPageSize: Type.Optional(Type.Boolean()),
+      transferMode: Type.Optional(Type.Union([Type.Literal("ReturnAsBase64"), Type.Literal("ReturnAsStream")])),
+      generateTaggedPDF: Type.Optional(Type.Boolean()),
+      generateDocumentOutline: Type.Optional(Type.Boolean()),
+    }),
+    Type.Object({ data: Type.String(), stream: Type.Optional(Type.String()) }),
+  ),
   "Page.handleJavaScriptDialog": cmd(
     Type.Object({ accept: Type.Boolean(), promptText: Type.Optional(Type.String()) }),
     Empty,
@@ -167,6 +283,7 @@ export const COMMANDS = {
         returnByValue: Type.Optional(Type.Boolean()),
         awaitPromise: Type.Optional(Type.Boolean()),
         userGesture: Type.Optional(Type.Boolean()),
+        replMode: Type.Optional(Type.Boolean()),
       },
       { additionalProperties: true },
     ),
@@ -209,6 +326,10 @@ export const COMMANDS = {
     Type.Object({ nodeId: Type.Optional(Type.Number()), backendNodeId: Type.Optional(Type.Number()) }),
     Type.Object({ object: RemoteObject }),
   ),
+  "DOM.describeNode": cmd(
+    Type.Object({ objectId: Type.String() }),
+    Type.Object({ node: Type.Object({ backendNodeId: Type.Number() }, { additionalProperties: true }) }),
+  ),
   "DOM.setFileInputFiles": cmd(
     Type.Object({
       files: Type.Array(Type.String()),
@@ -219,9 +340,60 @@ export const COMMANDS = {
     Empty,
   ),
 
-  "Input.dispatchMouseEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
-  "Input.dispatchKeyEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
-  "Input.dispatchDragEvent": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Input.dispatchMouseEvent": cmd(
+    Type.Object({
+      type: MouseEventType,
+      x: Type.Number(),
+      y: Type.Number(),
+      // Bit field: 1=Alt, 2=Ctrl, 4=Meta/Command, 8=Shift.
+      modifiers: Type.Optional(Type.Integer()),
+      timestamp: Type.Optional(Type.Number()),
+      button: Type.Optional(MouseButton),
+      // Bit field of pressed buttons: 1=Left, 2=Right, 4=Middle, 8=Back, 16=Forward.
+      buttons: Type.Optional(Type.Integer()),
+      clickCount: Type.Optional(Type.Integer()),
+      force: Type.Optional(Type.Number()),
+      tangentialPressure: Type.Optional(Type.Number()),
+      tiltX: Type.Optional(Type.Number()),
+      tiltY: Type.Optional(Type.Number()),
+      twist: Type.Optional(Type.Integer()),
+      deltaX: Type.Optional(Type.Number()),
+      deltaY: Type.Optional(Type.Number()),
+      pointerType: Type.Optional(Type.Union([Type.Literal("mouse"), Type.Literal("pen")])),
+    }),
+    Empty,
+  ),
+  "Input.dispatchKeyEvent": cmd(
+    Type.Object({
+      type: KeyEventType,
+      modifiers: Type.Optional(Type.Integer()),
+      timestamp: Type.Optional(Type.Number()),
+      text: Type.Optional(Type.String()),
+      unmodifiedText: Type.Optional(Type.String()),
+      keyIdentifier: Type.Optional(Type.String()),
+      code: Type.Optional(Type.String()),
+      key: Type.Optional(Type.String()),
+      windowsVirtualKeyCode: Type.Optional(Type.Integer()),
+      nativeVirtualKeyCode: Type.Optional(Type.Integer()),
+      autoRepeat: Type.Optional(Type.Boolean()),
+      isKeypad: Type.Optional(Type.Boolean()),
+      isSystemKey: Type.Optional(Type.Boolean()),
+      // 0=Standard, 1=Left, 2=Right, 3=Numpad.
+      location: Type.Optional(Type.Integer()),
+      commands: Type.Optional(Type.Array(Type.String())),
+    }),
+    Empty,
+  ),
+  "Input.dispatchDragEvent": cmd(
+    Type.Object({
+      type: DragEventType,
+      x: Type.Number(),
+      y: Type.Number(),
+      data: DragData,
+      modifiers: Type.Optional(Type.Integer()),
+    }),
+    Empty,
+  ),
   "Input.insertText": cmd(Type.Object({ text: Type.String() }), Empty),
 
   "Network.getResponseBody": cmd(
@@ -232,9 +404,27 @@ export const COMMANDS = {
     Type.Object({ headers: Type.Record(Type.String(), Type.String()) }),
     Empty,
   ),
-  "Emulation.setDeviceMetricsOverride": cmd(Type.Object({}, { additionalProperties: true }), Empty),
+  "Emulation.setDeviceMetricsOverride": cmd(
+    Type.Object({
+      // 0 disables the override for that dimension.
+      width: Type.Integer(),
+      height: Type.Integer(),
+      // 0 disables the override.
+      deviceScaleFactor: Type.Number(),
+      mobile: Type.Boolean(),
+      scale: Type.Optional(Type.Number()),
+      screenWidth: Type.Optional(Type.Integer()),
+      screenHeight: Type.Optional(Type.Integer()),
+      positionX: Type.Optional(Type.Integer()),
+      positionY: Type.Optional(Type.Integer()),
+      dontSetVisibleSize: Type.Optional(Type.Boolean()),
+      screenOrientation: Type.Optional(ScreenOrientation),
+      viewport: Type.Optional(Viewport),
+    }),
+    Empty,
+  ),
   "Accessibility.getFullAXTree": cmd(
-    Type.Object({ depth: Type.Optional(Type.Number()) }, { additionalProperties: true }),
+    Type.Object({ depth: Type.Optional(Type.Number()), frameId: Type.Optional(Type.String()) }),
     Type.Object({ nodes: Type.Array(AxNode) }),
   ),
 };
@@ -247,14 +437,15 @@ export const decodeResult = <M extends CdpMethod>(
   method: M,
   raw: unknown,
 ): Result<ResultOf<M>, CdpError> => {
+  // `method` is a key of COMMANDS, so the lookup cannot miss.
   const spec = COMMANDS[method];
-  if (spec === undefined) {
-    return err(cdpError("invalid_response", `unknown CDP method`, method));
-  }
   if (!spec.validate.Check(raw)) {
     const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
     return err(cdpError("invalid_response", why, method));
   }
-  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result, which TS cannot correlate from a generic key.
+  // Guarded assertion: the check above proves `raw` matches COMMANDS[method].result. TS resolves
+  // `spec.validate` through a generic key to the union of every validator, so the predicate
+  // narrows `raw` to the union of every result type rather than to ResultOf<M>.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- sanctioned decoder, see scripts/boundary-allowlist.ts
   return ok(raw as ResultOf<M>);
 };

package/src/cdp/console-buffer.ts

@@ -1,32 +1,39 @@
+import { Type, type Static } from "typebox";
 import { decodeEvent } from "./events";
-import { createRecordStore } from "./record-store";
+import { createRecordStore, type DrainPage } from "./record-store";
 
 export type ConsoleLevel = "log" | "info" | "warn" | "error" | "debug";
 
-export type ConsoleRecord = {
-  seq: number;
-  timestampMs: number;
-  level: ConsoleLevel;
-  text: string;
-  source: "console-api" | "log-entry";
-  url?: string;
-  lineNumber?: number;
-  stackTrace?: string;
-};
+// The one declaration of a console record: the buffer produces it and browser_console validates replayed
+// details against it, so the two cannot drift.
+export const ConsoleRecordSchema = Type.Object({
+  seq: Type.Number(),
+  timestampMs: Type.Number(),
+  level: Type.Union([
+    Type.Literal("log"),
+    Type.Literal("info"),
+    Type.Literal("warn"),
+    Type.Literal("error"),
+    Type.Literal("debug"),
+  ]),
+  text: Type.String(),
+  source: Type.Union([Type.Literal("console-api"), Type.Literal("log-entry")]),
+  url: Type.Optional(Type.String()),
+  lineNumber: Type.Optional(Type.Number()),
+  stackTrace: Type.Optional(Type.String()),
+});
+
+export type ConsoleRecord = Readonly<Static<typeof ConsoleRecordSchema>>;
 
 export type ConsoleFilter = {
-  levels?: ConsoleLevel[];
-  textPattern?: string;
-  sinceSeq?: number;
-  sinceMs?: number;
-  limit?: number;
+  readonly levels?: ReadonlyArray<ConsoleLevel>;
+  readonly textPattern?: string;
+  readonly sinceSeq?: number;
+  readonly sinceMs?: number;
+  readonly limit?: number;
 };
 
-export type ConsoleDrainResult = {
-  readonly records: ConsoleRecord[];
-  readonly total: number;
-  readonly bufferOverflowed: boolean;
-};
+export type ConsoleDrainResult = DrainPage<ConsoleRecord>;
 
 export type ConsoleBuffer = {
   ingestConsoleApi(p: unknown): void;
@@ -43,7 +50,9 @@ const compileTextMatcher = (pattern: string): ((text: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (text) => re.test(text);
-    } catch {}
+    } catch {
+      // Not a valid regex: fall through and match the pattern as a literal substring.
+    }
   }
   return (text) => text.includes(pattern);
 };
@@ -60,7 +69,8 @@ const stringifyRemoteObject = (
     try {
       return JSON.stringify(arg.value);
     } catch {
-      return String(arg.value);
+      // Circular or BigInt payloads cannot be JSON-encoded; fall back to the CDP description.
+      return arg.description ?? arg.type ?? "";
     }
   }
   if (arg.description !== undefined) return arg.description;
@@ -69,6 +79,8 @@ const stringifyRemoteObject = (
 
 const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
   switch (type) {
+    case undefined:
+      return "log";
     case "error":
     case "assert":
       return "error";
@@ -86,6 +98,8 @@ const mapConsoleApiLevel = (type: string | undefined): ConsoleLevel => {
 
 const mapLogEntryLevel = (level: string | undefined): ConsoleLevel => {
   switch (level) {
+    case undefined:
+      return "info";
     case "error":
       return "error";
     case "warning":

package/src/cdp/discovery.ts

@@ -6,6 +6,7 @@ import { type Result, err, ok } from "../util/result";
 import { userDataDirCandidates } from "../profile/paths";
 import { type CdpError, cdpError } from "./errors";
 import { asString, errnoCode, isRecord } from "../util/guards";
+import { sleep } from "../util/sleep";
 
 const PORT_PROBE_DEADLINE_MS = 30_000;
 const PORT_PROBE_INTERVAL_MS = 1_000;
@@ -40,24 +41,57 @@ const probePort = (port: number): Promise<Result<void, CdpError>> =>
       sock.destroy();
       resolve(r);
     };
-    sock.setTimeout(1000, () => finish(err(cdpError("discovery_failed", "probe timeout"))));
-    sock.once("error", (e) => finish(err(cdpError("discovery_failed", e.message))));
-    sock.once("connect", () => finish(ok(undefined)));
+    sock.setTimeout(1000, () => { finish(err(cdpError("discovery_failed", "probe timeout"))); });
+    sock.once("error", (e) => { finish(err(cdpError("discovery_failed", e.message))); });
+    sock.once("connect", () => { finish(ok(undefined)); });
   });
 
-const waitForPort = async (port: number): Promise<Result<void, CdpError>> => {
-  const end = Date.now() + PORT_PROBE_DEADLINE_MS;
-  let lastMessage = "unknown";
-  while (Date.now() < end) {
-    const probe = await probePort(port);
-    if (probe.success) return probe;
-    lastMessage = probe.error.message;
-    await new Promise((r) => setTimeout(r, PORT_PROBE_INTERVAL_MS));
+export type PortProbe = (port: number) => Promise<Result<void, CdpError>>;
+
+export type PortRaceOptions = {
+  readonly probe?: PortProbe;
+  readonly deadlineMs?: number;
+  readonly intervalMs?: number;
+};
+
+// Polls every candidate port at once under ONE deadline and settles on the first that answers; a stale DevToolsActivePort can no longer hold discovery for its own full deadline before the next candidate is tried.
+export const firstReadyPort = async <C extends { readonly port: number }>(
+  candidates: ReadonlyArray<C>,
+  opts: PortRaceOptions = {},
+): Promise<Result<C, CdpError>> => {
+  const probe = opts.probe ?? probePort;
+  const deadlineMs = opts.deadlineMs ?? PORT_PROBE_DEADLINE_MS;
+  const intervalMs = opts.intervalMs ?? PORT_PROBE_INTERVAL_MS;
+  if (candidates.length === 0) return err(cdpError("discovery_failed", "no DevTools port candidates to probe"));
+
+  // One controller ends every loser the moment a winner appears (or the deadline passes).
+  const stop = new AbortController();
+  const deadline = setTimeout(() => { stop.abort(); }, deadlineMs);
+  const lastMessages = new Map<number, string>();
+
+  const poll = async (c: C): Promise<C> => {
+    while (!stop.signal.aborted) {
+      const r = await probe(c.port);
+      if (r.success) return c;
+      lastMessages.set(c.port, r.error.message);
+      await sleep(intervalMs, stop.signal);
+    }
+    throw new Error(lastMessages.get(c.port) ?? "aborted");
+  };
+
+  try {
+    return ok(await Promise.any(candidates.map(poll)));
+  } catch {
+    const ports = candidates.map((k) => `127.0.0.1:${k.port}`).join(", ");
+    const detail = [...lastMessages.entries()].map(([port, m]) => `${port}: ${m}`).join("; ") || "unknown";
+    return err(cdpError(
+      "discovery_failed",
+      `Chrome's remote-debugging page is open, but DevTools is not live yet on ${ports} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${detail})`,
+    ));
+  } finally {
+    clearTimeout(deadline);
+    stop.abort();
   }
-  return err(cdpError(
-    "discovery_failed",
-    `Chrome's remote-debugging page is open, but DevTools is not live yet on 127.0.0.1:${port} — if Chrome opened a profile picker, choose your normal profile first, then tick the checkbox and click Allow if shown (last error: ${lastMessage})`,
-  ));
 };
 
 const isPortLive = async (port: number): Promise<boolean> => (await probePort(port)).success;
@@ -81,7 +115,7 @@ const queryLiveWsUrl = (port: number, timeoutMs = 1_500): Promise<string | null>
       },
     );
     req.on("timeout", () => { req.destroy(); resolve(null); });
-    req.on("error", () => resolve(null));
+    req.on("error", () => { resolve(null); });
     req.end();
   });
 
@@ -126,7 +160,9 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
       raw = await readFile(portFile, "utf8");
       try {
         mtimeMs = (await stat(portFile)).mtimeMs;
-      } catch {}
+      } catch {
+        // The file was readable a moment ago; without an mtime it is simply treated as fresh.
+      }
     } catch (e) {
       // EPERM/EACCES is common under sandboxes; remember it and fall back to network probing rather than failing the whole discovery.
       const code = errnoCode(e);
@@ -175,13 +211,9 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
   const ordered = liveCandidates.length > 0 ? liveCandidates : unique;
 
   // Some browsers disable the /json/version endpoint when remote debugging is toggled via chrome://inspect rather than a launch flag, hence the DevToolsActivePort fallback.
-  let lastErr: Result<CdpEndpoint, CdpError> | null = null;
-  for (const c of ordered) {
-    const ready = await waitForPort(c.port);
-    if (!ready.success) {
-      lastErr = err(ready.error);
-      continue;
-    }
+  const ready = await firstReadyPort(ordered);
+  if (ready.success) {
+    const c = ready.data;
     const liveUrl = await queryLiveWsUrl(c.port);
     return ok({ wsUrl: liveUrl ?? `ws://127.0.0.1:${c.port}${c.path}`, userDataDir: c.userDataDir });
   }
@@ -192,7 +224,7 @@ export const discoverEndpoint = async (): Promise<Result<CdpEndpoint, CdpError>>
     if (liveUrl) return ok({ wsUrl: liveUrl });
   }
 
-  return lastErr ?? err(cdpError("discovery_failed", "no live DevTools endpoint among discovered candidates"));
+  return err(ready.error);
 };
 
 export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {

package/src/cdp/events.ts

@@ -39,6 +39,11 @@ const ConsoleArg = Type.Object(
 
 export const EVENTS = {
   "Inspector.detached": ev(Anything),
+  // Browser-level notice that a session ended; carries the session id in params rather than on the envelope.
+  "Target.detachedFromTarget": ev(
+    Type.Object({ sessionId: Type.String(), targetId: Type.Optional(Type.String()) }, open),
+  ),
+  "Page.javascriptDialogClosed": ev(Anything),
 
   "Page.javascriptDialogOpening": ev(
     Type.Object(
@@ -52,6 +57,7 @@ export const EVENTS = {
   ),
   "Page.loadEventFired": ev(Anything),
   "Page.frameNavigated": ev(Anything),
+  "Page.downloadWillBegin": ev(Anything),
 
   "Runtime.consoleAPICalled": ev(
     Type.Object(
@@ -158,13 +164,13 @@ export const decodeEvent = <E extends CdpEventName>(
   name: E,
   raw: unknown,
 ): Result<EventParamsOf<E>, CdpError> => {
+  // `name` is a key of EVENTS, so the lookup cannot miss.
   const spec = EVENTS[name];
-  if (spec === undefined) {
-    return err(cdpError("invalid_response", "unknown CDP event", name));
-  }
   if (!spec.validate.Check(raw)) {
     const why = spec.validate.Errors(raw).map((e) => e.message).join("; ");
     return err(cdpError("invalid_response", why, name));
   }
+  // Guarded assertion: same generic-key correlation limit as decodeResult in cdp/commands.ts.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- sanctioned decoder, see scripts/boundary-allowlist.ts
   return ok(raw as EventParamsOf<E>);
 };

package/src/cdp/network-buffer.ts

@@ -1,37 +1,40 @@
+import { Type, type Static } from "typebox";
 import { decodeEvent, type EventParamsOf } from "./events";
-import { createRecordStore } from "./record-store";
-
-export type NetworkRecord = {
-  requestId: string;
-  method: string;
-  url: string;
-  status?: number;
-  statusText?: string;
-  type: string;
-  mimeType?: string;
-  requestStartedMs: number;
-  durationMs?: number;
-  requestBodySize: number;
-  responseBodySize?: number;
-  failed?: boolean;
-  errorText?: string;
-  body?: string | null;
-};
+import { createRecordStore, type DrainPage } from "./record-store";
+
+// Only the buffer itself may update a record in place as follow-up events arrive; everything it hands out is readonly.
+// The one declaration of a network record: the buffer produces it and browser_network_requests validates
+// replayed details against it, so the two cannot drift.
+export const NetworkRecordSchema = Type.Object({
+  requestId: Type.String(),
+  method: Type.String(),
+  url: Type.String(),
+  status: Type.Optional(Type.Number()),
+  statusText: Type.Optional(Type.String()),
+  type: Type.String(),
+  mimeType: Type.Optional(Type.String()),
+  requestStartedMs: Type.Number(),
+  durationMs: Type.Optional(Type.Number()),
+  requestBodySize: Type.Number(),
+  responseBodySize: Type.Optional(Type.Number()),
+  failed: Type.Optional(Type.Boolean()),
+  errorText: Type.Optional(Type.String()),
+  body: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+});
+
+type MutableNetworkRecord = Static<typeof NetworkRecordSchema>;
+export type NetworkRecord = Readonly<MutableNetworkRecord>;
 
 export type NetworkFilter = {
-  urlPattern?: string;
-  methodFilter?: string[];
-  statusFilter?: { min?: number; max?: number };
-  resourceTypes?: string[];
-  sinceMs?: number;
-  limit?: number;
+  readonly urlPattern?: string;
+  readonly methodFilter?: ReadonlyArray<string>;
+  readonly statusFilter?: { readonly min?: number; readonly max?: number };
+  readonly resourceTypes?: ReadonlyArray<string>;
+  readonly sinceMs?: number;
+  readonly limit?: number;
 };
 
-export type DrainResult = {
-  readonly records: NetworkRecord[];
-  readonly total: number;
-  readonly bufferOverflowed: boolean;
-};
+export type DrainResult = DrainPage<NetworkRecord>;
 
 export type NetworkBuffer = {
   ingestRequestWillBeSent(p: unknown): void;
@@ -47,7 +50,9 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
     try {
       const re = new RegExp(pattern.slice(1, -1));
       return (url) => re.test(url);
-    } catch {}
+    } catch {
+      // Not a valid regex: fall through and match the pattern as a literal substring.
+    }
   }
   return (url) => url.includes(pattern);
 };
@@ -55,13 +60,13 @@ const compileUrlMatcher = (pattern: string): ((url: string) => boolean) => {
 type UpdateEvent = "Network.responseReceived" | "Network.loadingFinished" | "Network.loadingFailed";
 
 export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
-  const records = createRecordStore<string, NetworkRecord>(capacity);
+  const records = createRecordStore<string, MutableNetworkRecord>(capacity);
 
   // All three follow-up events say the same thing first: decode, find the request they belong to, give up quietly if it is gone.
   const update = <E extends UpdateEvent>(
     method: E,
     p: unknown,
-    apply: (r: NetworkRecord, params: EventParamsOf<E>) => void,
+    apply: (r: MutableNetworkRecord, params: EventParamsOf<E>) => void,
   ): void => {
     const decoded = decodeEvent(method, p);
     if (!decoded.success) return;
@@ -80,6 +85,7 @@ export const createNetworkBuffer = (capacity = 500): NetworkBuffer => {
       const url = params?.request.url;
       const method = params?.request.method;
       if (!id || !url || !method) return;
+      // Delete before set: the store evicts by insertion order, so a request id that is re-sent (redirects reuse it) must move to the newest slot rather than keep its old age.
       records.delete(id);
       const postData = params.request.postData;
       records.set(id, {