pi-browser-harness 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,76 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.3.1 — 2026-05-02
+
+### Bug fixes
+
+- **`browser_list_tabs`** now shows full 32-character targetIds instead of truncated `BE9DD1DC…` prefixes. The `browser_list_tabs` → `browser_switch_tab` round-trip is repaired.
+- **`browser_switch_tab`** now supports prefix matching: pass a unique hex prefix (≥8 chars) and it resolves to the full targetId automatically. Ambiguous prefixes return a clear error listing all matching tabs.
+- **`browser_download`** auto-creates the download directory with `mkdir -p` if it doesn't exist. Previously it required a pre-existing writable directory.
+- **`ensureAlive()`** now probes the page session with `Runtime.evaluate("1")` after the transport health check. If the page target has crashed (e.g. localhost server died), it reattaches automatically instead of returning a cryptic `session_not_found` error on the next tool call.
+
+### Docs & metadata
+
+- **`browser_dispatch_key`** prompt guidelines now explicitly note it dispatches a synthetic DOM `KeyboardEvent` and does NOT type text. Point users to `browser_type` / `browser_press_key` for actual text input.
+- **`browser_navigate`** prompt guidelines now warn that Google and strict-anti-bot sites may reject CDP navigation. `browser_http_get` is the recommended workaround.
+- **`browser_get_network_log`** prompt snippet updated with explicit workaround (`browser_execute_js` with `PerformanceObserver`).
+- **`sharp`** added to `optionalDependencies` so `npm install` attempts it (enables `browser_screenshot` `maxDim` auto-resize).
+- **`SKILL.md`** script bindings section updated to document the actual daemon API: `daemon.evaluateJs()`, `daemon.pageInfo()`, `daemon.listTabs()`, `daemon.session().call()`. Example script updated to match.
+- **`SKILL.md`** troubleshooting section now covers `sharp`/`maxDim` and Google anti-bot navigation.
+
+## 0.3.0 — 2026-05-02
+
+### Internal rewrite
+
+- Per-domain module split: every tool now lives in its own `src/domains/<name>.ts` file. The 1140-line `daemon.ts` and 2277-line `tools.ts` are gone; the three largest files are now `src/cdp/transport.ts` (~220 LOC), `src/client.ts` (~220 LOC), and `src/domains/js.ts` (~200 LOC).
+- New transport/session/client split: `BrowserDaemon` class replaced with `createBrowserClient()` factory composing a `CdpTransport` (factory) and `CdpSession` (factory).
+- All tool handlers now return `Result<T, E>`; one `defineBrowserTool` helper converts to pi's `ToolDefinition` and supplies a uniform `details` shape: `{ ok: true, ... }` on success, `{ ok: false, kind, message, ... }` on error.
+- Strict TypeScript flags enabled (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noPropertyAccessFromIndexSignature`, `noUnusedLocals`, `noUnusedParameters`). Zero `any` in the codebase. All boundary `as` casts documented.
+
+### Bug fixes (predictability)
+
+- `browser_navigate` no longer silently creates a new tab when navigation fails; outcome is reported explicitly via `details.outcome.kind` (`"in_place"` | `"new_tab_created"`).
+- Page-info cache invalidation is now automatic: the session subscribes to CDP `Page.frameNavigated` / `Page.loadEventFired` events. The 5 manual `invalidatePageInfoCache()` calls are gone.
+- Dialog read no longer mutates state on `Page.javascriptDialogClosed` — the dialog persists in the buffer until `takeDialog()` is called, fixing a fast-dismiss race that dropped dialogs.
+- `browser_dispatch_key` now returns `details.matched` (count of elements the synthetic event was dispatched to). Zero matches is an `invalid_state` error instead of a false success.
+- `browser_http_get` timeout now covers the response body read (legacy aborted headers but `await response.text()` could hang indefinitely).
+- `sharp` failures are distinguished from "sharp not installed" — actual errors no longer masked by the install hint.
+- Screenshot paths use `randomUUID()` per-namespace — no more concurrent-write collisions from `Date.now() + global counter`.
+- Reconnect is lazy (via `ensureAlive`) — no background reconnect, no stacked Chrome consent popups.
+- WebSocket events are routed through an `AsyncIterable` bound to each connection — stale events from a previous connection can no longer leak across reconnects.
+- `browser_wait_for_load` returns a typed `timeout` error if the deadline elapses (legacy returned a soft string).
+
+### Security fixes
+
+- All JS evaluation source is built via `safeJs\`...\`` (always JSON.stringify-safe). The previous `replace(/'/g, "\\'")` selector escaping (broken for backslashes, newlines, unicode quotes, `</script>`) is gone.
+- `browser_run_script` now requires:
+  - script path inside `tmpdir()`, `cwd()`, or `BH_SCRIPT_DIR` (other paths rejected with `invalid_state`)
+  - a mandatory timeout (default 60s, max 600s, enforced via `Promise.race`)
+  - the AbortSignal is honored even if the script ignores its `signal` parameter
+  - source size ≤ 1 MB
+  - return shape validated structurally (each content item must be `{ type: "text", text: string }`)
+- `browser_download` validates the directory exists and is writable before calling CDP (Chrome was silently downloading to nowhere if the dir was bogus).
+- `browser_upload_file` verifies the file exists and is readable before any CDP call (prevents half-set state on the input).
+- `pdfPath()` / `screenshotPath()` validate the namespace against a strict regex so a hostile namespace cannot escape `tmpdir()`.
+
+### Parameter renames (saved scripts must be updated)
+
+- `browser_click`: `clicks` → `count`
+- `browser_dispatch_key`: `event` → `eventType`
+
+### Removed
+
+- The unused `tabHistory`, `screenshotDir`, and `debugClicks` fields on persisted state.
+- The dead `tool_result` hook in `index.ts` for tab-history tracking (`details.targetId` was never set by any tool).
+- `src/protocol.ts`, `src/renderers.ts`, `src/daemon.ts`, `src/tools.ts` (replaced by per-domain files and `client.ts`).
+
+### Known follow-ups
+
+- `browser_get_network_log` returns a structured deprecation note. The new transport routes events through an `AsyncIterable` consumed by the session manager; a synchronous `recentEvents()` API is deferred. Use `browser_execute_js` with `PerformanceObserver` or `performance.getEntries()` as a workaround.
+- `browser_run_script` script binding is named `daemon` for back-compat, but the underlying object is now a `BrowserClient`. Scripts using `daemon.cdp(method, params)` should switch to `daemon.session().call(method, params)`.
+- No tests added in this rewrite; that's a separate workstream.
+
 ## [0.2.0] - 2026-05-02
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-harness",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Browser control extension for pi — navigate, click, type, screenshot, and extract data from real Chrome via CDP",
   "keywords": [
     "pi-package",
@@ -62,6 +62,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "optionalDependencies": {
+    "sharp": "^0.33.0"
+  },
   "dependencies": {
     "ws": "^8.20.0"
   }

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

@@ -130,7 +130,18 @@ The script is written to disk, so it's auditable and re-runnable.
 
 **Script bindings:**
 - `params` — the arguments passed to browser_run_script
-- `daemon` — browser daemon (daemon.cdp(), daemon.evaluateJS(), daemon.getPageInfo(), etc.)
+- `daemon` — browser daemon with these methods:
+  - `daemon.evaluateJs(expression)` — run JS in the current page
+  - `daemon.pageInfo()` — get current page info or dialog
+  - `daemon.listTabs()` — returns `{ success, data: [{ targetId, url, title }] }`
+  - `daemon.switchTab(targetId)` — switch to a tab by full targetId
+  - `daemon.newTab(url?)` — open and switch to a new tab
+  - `daemon.current()` — returns `{ targetId, url?, title? }`
+  - `daemon.session(targetId)` — returns a session object for raw CDP:
+    - `session.call(method, params?)` — CDP command on the page target
+    - `session.callOnTarget(method, params, sessionId)` — CDP on a specific session
+    - `session.callBrowser(method, params?)` — CDP on the browser target
+    - `session.takeDialog()` — get/dismiss pending dialog
 - `require` — Node.js require() (use 'fs', 'path', 'crypto', etc.)
 - `signal` — AbortSignal for cancellation
 - `onUpdate` — progress callback: onUpdate({ content: [{ type: 'text', text: '...' }] })
@@ -140,9 +151,9 @@ The script is written to disk, so it's auditable and re-runnable.
 **Example — a script that extracts structured data:**
 ```javascript
 // /tmp/extract-products.js
-const info = await daemon.getPageInfo();
-if ("dialog" in info) throw new Error("Dialog is blocking: " + info.dialog.message);
-const data = await daemon.evaluateJS(`
+const info = await daemon.pageInfo();
+if (info && "dialog" in info) throw new Error("Dialog is blocking: " + info.dialog.message);
+const data = await daemon.evaluateJs(`
   JSON.stringify(Array.from(document.querySelectorAll('${params.rowSelector}')).map(el => ({
     title: el.querySelector('${params.titleSelector}')?.textContent?.trim(),
     price: el.querySelector('${params.priceSelector}')?.textContent?.trim(),
@@ -196,6 +207,8 @@ browser_execute_js("!!document.querySelector('.loaded-content')")
 - **Stale session**: Run `/browser-reload-daemon` to restart the daemon
 - **Dialog blocking**: Run browser_page_info to detect it, then browser_handle_dialog
 - **Status check**: Run `/browser-status` to see daemon health and current page
+- **Screenshot maxDim not working**: Install sharp (`npm install sharp`) for auto-resize support
+- **Google navigation fails**: Google's anti-bot detection may reject CDP navigation; use `browser_http_get` to fetch search results instead
 
 ## Architecture
 

package/src/cdp/discovery.ts

@@ -0,0 +1,95 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { connect as netConnect } from "node:net";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+
+const PORT_PROBE_DEADLINE_MS = 30_000;
+const PORT_PROBE_INTERVAL_MS = 1_000;
+
+const profileDirs = (): ReadonlyArray<string> => {
+  const home = homedir();
+  return [
+    join(home, "Library/Application Support/Google/Chrome"),
+    join(home, "Library/Application Support/Microsoft Edge"),
+    join(home, "Library/Application Support/Microsoft Edge Beta"),
+    join(home, "Library/Application Support/Microsoft Edge Dev"),
+    join(home, "Library/Application Support/Microsoft Edge Canary"),
+    join(home, ".config/google-chrome"),
+    join(home, ".config/chromium"),
+    join(home, ".config/chromium-browser"),
+    join(home, ".config/microsoft-edge"),
+    join(home, ".config/microsoft-edge-beta"),
+    join(home, ".config/microsoft-edge-dev"),
+    join(home, ".var/app/org.chromium.Chromium/config/chromium"),
+    join(home, ".var/app/com.google.Chrome/config/google-chrome"),
+    join(home, ".var/app/com.brave.Browser/config/BraveSoftware/Brave-Browser"),
+    join(home, ".var/app/com.microsoft.Edge/config/microsoft-edge"),
+    join(home, "AppData/Local/Google/Chrome/User Data"),
+    join(home, "AppData/Local/Chromium/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge Beta/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge Dev/User Data"),
+    join(home, "AppData/Local/Microsoft/Edge SxS/User Data"),
+  ];
+};
+
+const probePort = (port: number): Promise<Result<void, CdpError>> =>
+  new Promise((resolve) => {
+    const sock = netConnect({ host: "127.0.0.1", port });
+    let settled = false;
+    const finish = (r: Result<void, CdpError>): void => {
+      if (settled) return;
+      settled = true;
+      sock.setTimeout(0);
+      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)));
+  });
+
+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));
+  }
+  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})`,
+  ));
+};
+
+export const discoverWsUrl = async (): Promise<Result<string, CdpError>> => {
+  const dirs = profileDirs();
+  for (const base of dirs) {
+    const portFile = join(base, "DevToolsActivePort");
+    let raw: string;
+    try {
+      raw = await readFile(portFile, "utf8");
+    } catch (e) {
+      // Node fs errors carry .code; see ErrnoException
+      const code = (e as NodeJS.ErrnoException).code;
+      if (code === "ENOENT" || code === undefined) continue;
+      return err(cdpError("discovery_failed", `failed to read ${portFile}: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    const lines = raw.trim().split("\n");
+    if (lines.length < 2) continue;
+    const port = lines[0]?.trim();
+    const path = lines[1]?.trim();
+    if (!port || !path) continue;
+    const ready = await waitForPort(Number(port));
+    if (!ready.success) return ready;
+    return ok(`ws://127.0.0.1:${port}${path}`);
+  }
+  return err(cdpError(
+    "discovery_failed",
+    `DevToolsActivePort not found in ${dirs.join(", ")} — open chrome://inspect/#remote-debugging in your browser, tick the checkbox, click Allow, then retry. Or set BU_CDP_WS to a remote browser endpoint.`,
+  ));
+};

package/src/cdp/errors.ts

@@ -0,0 +1,19 @@
+export type CdpErrorKind =
+  | "transport_closed"
+  | "timeout"
+  | "session_not_found"
+  | "remote_error"
+  | "discovery_failed"
+  | "invalid_response";
+
+export type CdpError = {
+  readonly kind: CdpErrorKind;
+  readonly message: string;
+  readonly method?: string;
+};
+
+export const cdpError = (
+  kind: CdpErrorKind,
+  message: string,
+  method?: string,
+): CdpError => ({ kind, message, ...(method !== undefined ? { method } : {}) });

package/src/cdp/session.ts

@@ -0,0 +1,139 @@
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+import type { DialogInfo } from "./types";
+import { isInternalUrl } from "./types";
+import type { CdpTransport } from "./transport";
+
+export type CdpSession = {
+  attachFirstPage(): Promise<Result<{ readonly targetId: string; readonly sessionId: string }, CdpError>>;
+  switchTo(targetId: string): Promise<Result<void, CdpError>>;
+  current(): { readonly sessionId: string; readonly targetId: string } | null;
+  call(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  callOnTarget(method: string, params: Record<string, unknown>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  callBrowser(method: string, params?: Record<string, unknown>, opts?: { timeoutMs?: number }): Promise<Result<unknown, CdpError>>;
+  takeDialog(): DialogInfo | null;
+  drainPageInfoInvalidations(): boolean;
+};
+
+export const createCdpSession = (transport: CdpTransport): CdpSession => {
+  let sessionId: string | null = null;
+  let targetId: string | null = null;
+  let dialog: DialogInfo | null = null;
+  let pageInfoDirty = false;
+
+  let activeConsumer: Promise<void> = Promise.resolve();
+
+  const consumeEvents = async (): Promise<void> => {
+    for await (const ev of transport.events()) {
+      if (ev.method === "Page.javascriptDialogOpening") {
+        const params = ev.params as Partial<DialogInfo> | undefined;
+        dialog = {
+          type: (params?.type as DialogInfo["type"]) ?? "alert",
+          message: params?.message ?? "",
+          ...(params?.defaultPrompt !== undefined ? { defaultPrompt: params.defaultPrompt } : {}),
+        };
+        continue;
+      }
+      // Page.javascriptDialogClosed is intentionally NOT cleared here —
+      // the dialog stays in the buffer until takeDialog() is called.
+      // This prevents fast dismiss flows from dropping a dialog the agent
+      // was about to read. (Fix for spec §7 predictability bug #2.)
+      if (ev.method === "Page.frameNavigated" || ev.method === "Page.loadEventFired") {
+        pageInfoDirty = true;
+      }
+    }
+  };
+
+  const restartConsumer = (): void => {
+    activeConsumer = activeConsumer.then(() => consumeEvents()).catch((e: unknown) => {
+      // The .then() chain calls consumeEvents() which iterates the transport's
+      // events() AsyncIterable. The iterable resolves cleanly on close (returns
+      // {done:true}); any rejection here is an unexpected bug in the event
+      // handler, not a normal termination. Surface it on stderr so it's not lost.
+      console.warn("[pi-browser-harness] CDP event consumer crashed:", e);
+    });
+  };
+
+  restartConsumer();
+  transport.onClose(() => {
+    sessionId = null;
+    targetId = null;
+    pageInfoDirty = false;
+    // Do NOT clear `dialog` here — same rationale as inside consumeEvents:
+    // the agent may have a pending takeDialog() call that should still see it.
+    restartConsumer();
+  });
+
+  // TODO(perf): the four enable calls are sequential here for predictability.
+  // Switching to Promise.all over a single WS pipelines the round-trips and
+  // saves ~3× on tab-switch latency. Defer until session.ts has tests.
+  const enableDomains = async (sid: string): Promise<void> => {
+    for (const d of ["Page", "DOM", "Runtime", "Network"]) {
+      await transport.request(`${d}.enable`, {}, { sessionId: sid });
+    }
+  };
+
+  // CDP response shapes are documented in chromedevtools.github.io but not
+  // available as TypeScript types. We cast `as` from `unknown` only in this
+  // file (the CDP boundary). Each cast is paired with the CDP method that
+  // produced the response. Adding runtime guards for every shape would be
+  // noise — Chrome's protocol is stable enough that a wrong cast surfaces
+  // as a clear Error in normal use.
+  return {
+    async attachFirstPage() {
+      const targets = await transport.request("Target.getTargets", {}, { sessionId: null });
+      if (!targets.success) return targets;
+      const data = targets.data as { targetInfos: ReadonlyArray<{ targetId: string; type: string; url: string }> };
+      let pages = data.targetInfos.filter((t) => t.type === "page" && !isInternalUrl(t.url));
+      if (pages.length === 0) {
+        const created = await transport.request("Target.createTarget", { url: "about:blank" }, { sessionId: null });
+        if (!created.success) return created;
+        const c = created.data as { targetId: string };
+        pages = [{ targetId: c.targetId, type: "page", url: "about:blank" }];
+      }
+      const first = pages[0];
+      if (!first) return err(cdpError("invalid_response", "no page targets after creation"));
+      const attached = await transport.request("Target.attachToTarget", { targetId: first.targetId, flatten: true }, { sessionId: null });
+      if (!attached.success) return attached;
+      const a = attached.data as { sessionId: string };
+      sessionId = a.sessionId;
+      targetId = first.targetId;
+      await enableDomains(a.sessionId);
+      return ok({ targetId: first.targetId, sessionId: a.sessionId });
+    },
+    async switchTo(tid) {
+      const activated = await transport.request("Target.activateTarget", { targetId: tid }, { sessionId: null });
+      if (!activated.success) return activated;
+      const attached = await transport.request("Target.attachToTarget", { targetId: tid, flatten: true }, { sessionId: null });
+      if (!attached.success) return attached;
+      const a = attached.data as { sessionId: string };
+      sessionId = a.sessionId;
+      targetId = tid;
+      pageInfoDirty = true;
+      await enableDomains(a.sessionId);
+      return ok(undefined);
+    },
+    current() {
+      return sessionId && targetId ? { sessionId, targetId } : null;
+    },
+    call(method, params = {}, opts = {}) {
+      return transport.request(method, params, { sessionId, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    callOnTarget(method, params, sid, opts = {}) {
+      return transport.request(method, params, { sessionId: sid, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    callBrowser(method, params = {}, opts = {}) {
+      return transport.request(method, params, { sessionId: null, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+    },
+    takeDialog() {
+      const d = dialog;
+      dialog = null;
+      return d;
+    },
+    drainPageInfoInvalidations() {
+      const dirty = pageInfoDirty;
+      pageInfoDirty = false;
+      return dirty;
+    },
+  };
+};

package/src/cdp/transport.ts

@@ -0,0 +1,221 @@
+import WebSocket from "ws";
+import { type Result, err, ok } from "../util/result";
+import { type CdpError, cdpError } from "./errors";
+import { isCdpRawMessage } from "./types";
+import type { CdpEvent, CdpRawMessage } from "./types";
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+type Pending = {
+  readonly resolve: (v: Result<unknown, CdpError>) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+  readonly method: string;
+};
+
+export type CdpTransport = {
+  connect(url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>>;
+  close(): Promise<void>;
+  request(
+    method: string,
+    params: Record<string, unknown>,
+    opts?: { sessionId?: string | null; timeoutMs?: number },
+  ): Promise<Result<unknown, CdpError>>;
+  // Returns the current event queue's iterator. After close()+reconnect, callers
+  // must re-call events() — the old iterator will have received done:true.
+  events(): AsyncIterable<CdpEvent>;
+  state(): "open" | "closed" | "connecting";
+  onClose(cb: () => void): () => void;
+};
+
+export const createCdpTransport = (): CdpTransport => {
+  let ws: WebSocket | null = null;
+  let nextId = 1;
+  const pending = new Map<number, Pending>();
+  const closeListeners = new Set<() => void>();
+
+  type EventQueue = {
+    readonly push: (e: CdpEvent) => void;
+    readonly end: () => void;
+    readonly iter: AsyncIterable<CdpEvent>;
+  };
+
+  const makeEventQueue = (): EventQueue => {
+    const buf: CdpEvent[] = [];
+    const waiters: Array<(v: IteratorResult<CdpEvent>) => void> = [];
+    let ended = false;
+    return {
+      push(e) {
+        if (ended) return;
+        const w = waiters.shift();
+        if (w) w({ value: e, done: false });
+        else buf.push(e);
+      },
+      end() {
+        ended = true;
+        // value: undefined as unknown as CdpEvent is the correct iterator-protocol
+        // pattern: when done=true the value field is conventionally undefined but
+        // the TS type still requires CdpEvent.
+        for (const w of waiters.splice(0)) w({ value: undefined as unknown as CdpEvent, done: true });
+      },
+      iter: {
+        [Symbol.asyncIterator]() {
+          return {
+            next: (): Promise<IteratorResult<CdpEvent>> =>
+              new Promise((resolve) => {
+                const next = buf.shift();
+                if (next) resolve({ value: next, done: false });
+                else if (ended) resolve({ value: undefined as unknown as CdpEvent, done: true });
+                else waiters.push(resolve);
+              }),
+          };
+        },
+      },
+    };
+  };
+
+  let queue = makeEventQueue();
+
+  const handleMessage = (raw: string): void => {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (!isCdpRawMessage(parsed)) return;
+    const msg: CdpRawMessage = parsed;
+    if (msg.id === undefined) {
+      if (msg.method) {
+        queue.push({
+          method: msg.method,
+          params: msg.params,
+          ...(msg.sessionId !== undefined ? { sessionId: msg.sessionId } : {}),
+        });
+      }
+      return;
+    }
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) {
+      const kind = msg.error.message.includes("Session with given id not found")
+        ? "session_not_found"
+        : "remote_error";
+      p.resolve(err(cdpError(kind, msg.error.message, p.method)));
+      return;
+    }
+    p.resolve(ok(msg.result));
+  };
+
+  const cleanup = (reason: string): void => {
+    for (const [, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve(err(cdpError("transport_closed", reason, p.method)));
+    }
+    pending.clear();
+    queue.end();
+    queue = makeEventQueue();
+    for (const cb of closeListeners) cb();
+  };
+
+  return {
+    connect(url, opts = {}): Promise<Result<void, CdpError>> {
+      const timeoutMs = opts.timeoutMs ?? 10_000;
+      return new Promise((resolve) => {
+        let settled = false;
+        const settle = (r: Result<void, CdpError>): void => {
+          if (settled) return;
+          settled = true;
+          resolve(r);
+        };
+        try {
+          ws = new WebSocket(url);
+        } catch (e) {
+          settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
+          return;
+        }
+        const timer = setTimeout(() => {
+          ws?.close();
+          ws = null;
+          settle(err(cdpError("timeout", `CDP WebSocket connection timed out after ${timeoutMs}ms`)));
+        }, timeoutMs);
+        ws.onopen = () => {
+          clearTimeout(timer);
+          settle(ok(undefined));
+        };
+        ws.onmessage = (ev: WebSocket.MessageEvent) => {
+          const data = ev.data;
+          handleMessage(typeof data === "string" ? data : data.toString());
+        };
+        ws.onerror = () => {
+          clearTimeout(timer);
+          settle(err(cdpError("transport_closed", "CDP WebSocket error during connection")));
+        };
+        ws.onclose = () => {
+          clearTimeout(timer);
+          ws = null;
+          cleanup("WebSocket closed");
+          // If onopen already settled the connect promise, this settle is a no-op
+          // (guarded by `settled`). cleanup() above still runs unconditionally so
+          // pending requests are rejected and the event queue is rotated.
+          settle(err(cdpError("transport_closed", "CDP WebSocket closed")));
+        };
+      });
+    },
+    close(): Promise<void> {
+      if (ws) {
+        try { ws.close(1000, "Shutdown"); } catch { /* best effort */ }
+        ws = null;
+      }
+      cleanup("close() called");
+      return Promise.resolve();
+    },
+    request(method, params, opts = {}): Promise<Result<unknown, CdpError>> {
+      const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+      const sessionId = opts.sessionId ?? null;
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        return Promise.resolve(err(cdpError("transport_closed", "Browser not connected. Is Chrome running?", method)));
+      }
+      // Bind to a local const so the non-null is guaranteed even across microtasks
+      // between the readyState check and the send() call.
+      const sock = ws;
+      const id = nextId++;
+      const payload: Record<string, unknown> = { id, method, params };
+      if (sessionId) payload["sessionId"] = sessionId;
+      const json = JSON.stringify(payload);
+      return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          resolve(err(cdpError("timeout", `CDP timeout after ${timeoutMs}ms: ${method}`, method)));
+        }, timeoutMs);
+        pending.set(id, { resolve, timer, method });
+        try {
+          sock.send(json);
+        } catch (e) {
+          clearTimeout(timer);
+          pending.delete(id);
+          resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
+        }
+      });
+    },
+    events(): AsyncIterable<CdpEvent> {
+      // Single-consumer: each connection's event stream may be iterated by
+      // exactly one for-await loop. Calling events() multiple times returns
+      // the same iterable; the second consumer will silently steal events
+      // from the first. After a reconnect, the previous iterator is ended
+      // and callers must re-call events() to receive new events.
+      return queue.iter;
+    },
+    state(): "open" | "closed" | "connecting" {
+      if (!ws) return "closed";
+      if (ws.readyState === WebSocket.CONNECTING) return "connecting";
+      if (ws.readyState === WebSocket.OPEN) return "open";
+      return "closed";
+    },
+    onClose(cb): () => void {
+      closeListeners.add(cb);
+      return () => closeListeners.delete(cb);
+    },
+  };
+};