pi-browser-harness 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.13.0 — 2026-10-20
+
+### Fixed
+
+- **A killed daemon no longer crashes pi with `read ECONNRESET`.** The daemon's liveness probe, the client transport and the IPC server read the wire protocol through `node:readline`, which re-emits the socket's errors on its own interface with no listener. They now share a small line reader in `src/daemon/lines.ts` that only emits lines.
+- **Waking from sleep no longer stacks up "Allow remote debugging" prompts.** Each dial to Chrome is one prompt, and the daemon abandoned a dial after 10s and started another on the next tool call, so an agent mid-task could open a dozen prompts before anyone was back at the keyboard. A dial now stays open for 5 minutes while callers get a "waiting for the Allow prompt" answer after 10s, every caller joins the dial in flight, and an outright failure starts a doubling cooldown (30s to 5min) during which no automatic dial happens. A dropped connection still re-dials once at the next demand. `/browser-setup` and `/browser-reload-daemon` send `Daemon.reconnect`, which bypasses the cooldown.
+- **Tool failures now reach the model as errors.** `defineBrowserTool` set `isError` on the returned result, but pi only flags a result as an error when `execute` rejects, so every failed browser tool read as a success. Failed handlers now throw with the rendered error text; replayed errors still render in the UI.
+- **The daemon transport no longer exits mid-handshake.** The connect timer was cleared on TCP connect, before the daemon's `registered` reply, and the socket was already unref'd, so a print-mode run could exit before registering. The timer now stays armed until the handshake settles; a daemon that accepts but never registers times out instead of hanging.
+- **Disconnected clients are cleaned up in the daemon.** The idle-timer registration overwrote the bridge's disconnect handler, so router ownership and armed timers leaked per client. The IPC server now keeps a handler list; `deregister` is handled.
+- **`--browser-namespace` works.** The flag was read before it was registered, so it was always undefined.
+- **CDP sessions are reused or detached.** Switching tabs re-attached every time and left the old session alive; destroying the current target left `current()` pointing at it for up to 30s. Sessions are now tracked per target, detached on re-attach, and cleared on `Target.targetDestroyed` / `Inspector.detached`.
+- **Connect timeouts no longer kick every client off the daemon**, overlapping `connect()` calls share one handshake, the detach release reads the session from `params`, and the duplicate-clientId reply is flushed before the socket closes.
+- **Time budgets in `browser_network_requests` and `browser_snapshot` actually bound the work** through a concurrency-limited runner that honours the abort signal.
+- **`browser_handle_dialog` clears the recorded dialog**, so the next `browser_page_info` no longer reports an already-handled dialog.
+- **`browser_press_key` sends virtual key codes for function and modifier keys.**
+- **`browser_open_urls` applies the tab-title marker after the page loads** instead of to the document being replaced.
+- **`browser_print_to_pdf`, screenshots and uploads return `io_error`** on unwritable or unreadable paths instead of throwing.
+- **Element refs are released** (`Runtime.releaseObject`) on every ref path; `browser_read_page` and `browser_open_urls` detach the sessions they attach.
+- sharp "missing" is classified correctly under ESM; `isPathWithin` accepts siblings starting with `..`; `BH_DEBUG_CLICKS=0` disables debug; Linux `chromium-browser` process names are matched after `ps` truncation; discovery probes stale `DevToolsActivePort` candidates concurrently under one deadline.
+
+### Changed
+
+- **Bad arguments return `invalid_args`** instead of `invalid_state`.
+- **`browser_switch_tab` resolves targetId prefixes against owned tabs only**, matching `browser_close_tab`.
+- **`browser_execute_js` details hold a bounded preview**; the full value lives in the text.
+- **CDP calls require params when the method needs them**, and `Input.*`, `Emulation.setDeviceMetricsOverride`, `Page.printToPDF` and `Page.captureScreenshot` have real schemas.
+- **Tool `details` are typed** via a TypeBox schema on the definition and validated on replay.
+- **Page-side JS is TypeScript** under `src/domains/page/*.page.ts`, type-checked against the DOM lib and injected via `fn.toString()`. `src/domains/fill-engine.ts` is removed.
+- The browser prompt's lane lists and the skill file's tool reference are generated from the registry (`npm run gen:skill`).
+
+### Added
+
+- **Other pi extensions can contribute browser tools** through `registerBrowserTools` (see README, Extending).
+- Type-aware ESLint (`npm run lint`) and `npm run check` running typecheck, boundaries, lint and tests. The boundary scanner gained a `raw-js-template` rule.
+- Injection seams on the daemon entry, extension factory, setup and profile binding; tests for every tool in `src/domains` and the previously untested util, profile and daemon modules (365 tests to 1017).
+
 ## 0.12.0 — 2026-10-19
 
 ### Changed

package/README.md

@@ -303,6 +303,91 @@ Scripts must live under the OS temp dir, the cwd, or `BH_SCRIPT_DIR`, and every
 mandatory timeout (60s default, 600s max). They land on disk first, so they're reviewable and
 re-runnable.
 
+### Contributing tools from another pi extension
+
+Another extension can add its own `browser_*` tools to this harness. Contributed tools share the
+same client, mutation mutex, tab ownership, and lane prompt as the built-ins, so a `serialized` tool
+you add queues behind `browser_click` exactly as `browser_fill` does.
+
+Define the tool with `defineBrowserTool` and hand it to `registerBrowserTools` at your extension's
+load time, before pi emits `session_start`. The harness registers it with pi on the next
+`session_start` alongside the built-ins.
+
+```ts
+// my-extension/src/index.ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { defineBrowserTool, registerBrowserTools, ok } from "pi-browser-harness/src/index.ts";
+import { evalJs } from "pi-browser-harness/src/domains/cdp-call.ts";
+
+const pageHeightTool = defineBrowserTool({
+  name: "browser_page_height",
+  label: "Browser Page Height",
+  description: "Report the document's full scroll height in CSS pixels.",
+  promptSnippet: "Measure the page's scroll height",
+  promptGuidelines: [],
+  parameters: Type.Object({}),
+  concurrency: "parallel",
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    return ok({ text: `Scroll height: ${String(height.data)}px` });
+  },
+});
+
+export default function myExtension(_pi: ExtensionAPI): void {
+  const added = registerBrowserTools([pageHeightTool]);
+  if (!added.success) console.warn(added.error.message);
+}
+```
+
+`registerBrowserTools` returns a `Result`. The whole batch is rejected, and nothing is added, when any
+name is already taken by a built-in, an earlier contribution, or another tool in the same batch. Pick
+`concurrency: "serialized"` for anything that changes page or tab state; `"parallel"` for reads.
+`browserTools()` lists what the harness will register, built-ins plus contributions so far.
+
+A tool that wants a custom result view declares a `details` schema next to `parameters`. The handler
+then returns `details` of that shape, and `renderResult` receives them typed. pi stores details with
+the session and replays them later; the harness validates replayed details against the schema first,
+so a renderer never sees a stale shape from an older session (it falls back to the stored text instead).
+Details must be plain JSON: no `Map`s, and omit a key rather than setting it to `undefined`.
+
+```ts
+import { Text } from "@mariozechner/pi-tui";
+
+const PageHeightDetails = Type.Object({ height: Type.Number(), unit: Type.Literal("px") });
+
+const pageHeightTool = defineBrowserTool({
+  // ...name, label, description, promptSnippet, promptGuidelines, parameters, concurrency as above
+  details: PageHeightDetails,
+  handler: async (_args, { client }) => {
+    const height = await evalJs(client, "document.documentElement.scrollHeight");
+    if (!height.success) return height;
+    const px = typeof height.data === "number" ? height.data : 0;
+    return ok({ text: `Scroll height: ${px}px`, details: { height: px, unit: "px" } });
+  },
+  renderResult: (result, _expanded, theme) =>
+    new Text(theme.fg("muted", `${result.details.height}${result.details.unit}`), 0, 0),
+});
+```
+
+Tools without a `details` schema need nothing extra: they may still attach any JSON object for logs,
+and their `renderResult` (if any) sees it untyped.
+
+### Known limits
+
+Two extension points are documented but not implemented; the escape hatches that exist today are
+listed with each.
+
+- **No per-tab extension slot.** `TabSession` in `src/cdp/session.ts` carries only the harness's own
+  per-tab state (session id, dialog, page-info cache). A contributed tool cannot stash its own state
+  on a tab. Keep per-tab state in your extension keyed by `targetId` from `browser_current_tab` or
+  `browser_list_tabs`, or compute it on demand with `browser_run_script` through `daemon.session(targetId)`.
+- **Hardcoded browser list.** `src/profile/paths.ts` knows the user-data directories of a fixed set
+  of Chromium browsers, so `/browser-profile` cannot discover one that is not on that list. Point the
+  harness at any Chromium profile directory with `CHROME_USER_DATA_DIR`, or skip discovery entirely
+  by attaching to a running browser's DevTools endpoint with `BU_CDP_WS`.
+
 ---
 
 ## Commands, flags, and environment
@@ -393,6 +478,7 @@ path-restricted and timeout-bounded, but that is a blast-radius limit, not a san
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, conventions, and the PR process.
+`npm run check` runs the typecheck, the boundary scan, the type-aware ESLint pass and the test suite in that order; it is the one command a PR must pass.
 Release history lives in [CHANGELOG.md](CHANGELOG.md).
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -49,18 +49,24 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@eslint/js": "10.0.1",
     "@mariozechner/pi-coding-agent": "*",
     "@mariozechner/pi-tui": "*",
     "@types/ws": "^8.18.1",
+    "eslint": "10.11.0",
     "typebox": "*",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "typescript-eslint": "8.71.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util}/**/*-test.ts\"",
+    "typecheck": "tsc -b tsconfig.page.json && tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "node --conditions=import --import tsx --test \"test/{profile,domains,cdp,daemon,util,types}/**/*-test.ts\"",
     "boundaries": "tsx scripts/check-boundaries.ts",
-    "check": "npm run typecheck && npm run boundaries && npm test",
-    "prepublishOnly": "tsc --noEmit"
+    "gen:skill": "node --conditions=import --import tsx scripts/gen-skill.ts",
+    "check": "npm run typecheck && npm run boundaries && npm run lint && npm test",
+    "prepublishOnly": "npm run typecheck",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
   },
   "publishConfig": {
     "access": "public"

package/skills/pi-browser-harness/SKILL.md

@@ -41,6 +41,61 @@ Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot
 
 `browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. Pair them for a research question: search for candidate URLs, then read the promising ones.
 
+## Tool reference
+
+Every tool, its concurrency lane, and a one-line summary. `serialized` tools queue through one
+shared mutation lane; `parallel` tools may run alongside them. The decision tree above says which
+to reach for first; the tool descriptions and parameter schemas carry per-tool detail.
+
+<!-- tools:start -->
+Generated from `src/registry.ts` by `npm run gen:skill`; do not edit by hand.
+
+| Tool | Lane | Summary |
+|---|---|---|
+| `browser_clear_headers` | serialized | Clear extra request headers from the current owned tab |
+| `browser_click` | serialized | Click an element by ref (preferred) or pixel coordinates |
+| `browser_close_tab` | serialized | Close an owned tab |
+| `browser_console` | parallel | Read JS errors / console output on the current tab |
+| `browser_current_tab` | parallel | Get current tab info |
+| `browser_dispatch_key` | serialized | Dispatch a DOM KeyboardEvent on an element by ref (preferred) or selector |
+| `browser_download` | serialized | Configure download directory |
+| `browser_drag_and_drop` | serialized | Drag and drop between two coordinates |
+| `browser_execute_js` | parallel | Execute JS in the page — surgical DOM reads (preferred over screenshot) |
+| `browser_fill` | serialized | Fill a form field by ref (preferred) or selector (works with React/Vue controlled inputs) |
+| `browser_fill_form` | serialized | Fill many form fields at once by ref — React-safe, self-confirming |
+| `browser_focus` | serialized | Focus an element by ref (preferred) or selector |
+| `browser_go_back` | serialized | Go back one page |
+| `browser_go_forward` | serialized | Go forward one page |
+| `browser_handle_dialog` | serialized | Accept or dismiss a JS dialog |
+| `browser_http_get` | parallel | HTTP GET (outside browser; for APIs/static pages) |
+| `browser_list_tabs` | parallel | List browser tabs |
+| `browser_navigate` | serialized | Navigate to a URL |
+| `browser_network_requests` | parallel | Inspect recent network requests on the current page |
+| `browser_new_tab` | serialized | Open a new tab |
+| `browser_open_urls` | serialized | Open multiple URLs in new tabs (parallel) |
+| `browser_page_info` | parallel | Get current page URL, title, viewport, and scroll position |
+| `browser_press_key` | serialized | Press a key (Enter, Tab, Escape, arrows, or any character) |
+| `browser_print_to_pdf` | serialized | Print the current page to PDF |
+| `browser_read_page` | parallel | Read a page's main content as clean text |
+| `browser_reload` | serialized | Reload the page |
+| `browser_run_script` | parallel | Run a temporary script with daemon + Node access (security-bounded) |
+| `browser_screenshot` | parallel | Capture a screenshot — visual verification only |
+| `browser_scroll` | serialized | Scroll the page (deltaY positive=down, negative=up) |
+| `browser_select_option` | serialized | Select an option in a native <select> by ref (preferred) or selector |
+| `browser_set_checked` | serialized | Set a checkbox/radio checked state by ref |
+| `browser_set_headers` | serialized | Set extra request headers on the current owned tab |
+| `browser_setup` | parallel | Initialize browser connection |
+| `browser_snapshot` | parallel | Get accessibility-tree snapshot with stable element refs (default for page inspection) |
+| `browser_switch_tab` | serialized | Switch tabs |
+| `browser_type` | serialized | Type text into the focused element |
+| `browser_upload_file` | serialized | Upload a file to a file input by ref (preferred) or selector |
+| `browser_viewport_resize` | serialized | Resize the viewport (responsive testing) |
+| `browser_wait` | parallel | Wait N seconds |
+| `browser_wait_for` | parallel | Wait for an element or text to appear (or an element to disappear) |
+| `browser_wait_for_load` | serialized | Wait for the page to finish loading |
+| `browser_web_search` | serialized | Search the web for a query |
+<!-- tools:end -->
+
 ## Connection Setup
 
 Browser control is **on-demand** — the daemon does NOT start automatically.
@@ -111,11 +166,11 @@ When a workflow repeats 3+ times or needs Node.js APIs, write a script to disk a
 
 ## Troubleshooting: "Could not start the browser daemon"
 
-`browser_setup` spawns the daemon as `node <tsx cli> <pkg>/src/daemon/index.ts` with `stdio: "ignore"` (tsx is resolved from the package directory upward, so in pi's hoisted install it sits beside the package rather than inside it). A crash before the socket binds is completely silent and all you see is `Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock.`
+`browser_setup` spawns the daemon as `node <tsx cli> <pkg>/src/daemon/main.ts` with `stdio: "ignore"` (tsx is resolved from the package directory upward, so in pi's hoisted install it sits beside the package rather than inside it). A crash before the socket binds is completely silent and all you see is `Could not start the browser daemon. Check /tmp/pi-browser-daemon.sock.`
 
 Run it in the foreground to see the real error (it prints whether it reached Chrome):
 
-    cd <pkg> && node "$(node -p "require.resolve('tsx/cli')")" src/daemon/index.ts
+    cd <pkg> && node "$(node -p "require.resolve('tsx/cli')")" src/daemon/main.ts
 
 Known cause (package 0.11.1): `Error: Cannot find module 'typebox'` at `src/cdp/discovery.ts`. The package declares `typebox` in `peerDependencies` and `devDependencies`, and pi installs packages with dev and peer dependencies omitted, so the tree has no physical copy. It still resolves inside the pi extension host, which maps `typebox` to pi's bundled copy, but not in the spawned daemon process, which resolves modules from the package directory upward. The daemon dies, no socket appears, and every browser tool reports `not_connected`.
 

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,
@@ -219,9 +335,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 +399,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 +432,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":