pi-browser-harness 0.2.0 → 0.3.2

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to pi-browser-harness will be documented in this file.
 
+## 0.3.2 — 2026-05-05
+
+### Added
+
+- **Parallel tool execution with automatic mutation serialization.** Observation tools (`browser_screenshot`, `browser_page_info`, `browser_execute_js`, `browser_list_tabs`, `browser_http_get` etc.) can now run in parallel with each other and with mutation tools. Mutation tools (`browser_click`, `browser_type`, `browser_scroll`, `browser_navigate`, `browser_switch_tab`, etc.) are automatically serialized through a shared async mutex so they never race on shared CDP session/page state. LLMs can emit independent operations in the same turn for better latency.
+- **New `src/util/mutex.ts`** — lightweight async mutex (~25 LOC) with FIFO queue. `serialized?: boolean` flag added to `BrowserToolDefinition`; `mutationMutex()` exposed on `BrowserClient`.
+- **Prompt and SKILL.md** updated with parallel-execution guidance and safe-parallel-call examples.
+
+### Fixed
+
+- **Scroll tool deltaY sign convention corrected.** Previously `deltaY` was documented as positive=up (inverted vs W3C wheel events). Now follows the W3C convention: positive=down, negative=up. Default changed from `-300` to `300` (scroll down). Prompt snippets, tool descriptions, and guidelines all updated.
+- **Scroll tool now calls `Page.bringToFront`** before dispatching mouse events, preventing silent-drop when the target page is not the active browser tab. Mouse events now include explicit `button:"none"`, `buttons:0`, `pointerType:"mouse"`.
+- **Screenshot TUI render no longer crashes the host on long file paths.** The `Image` text-fallback render did not respect terminal width, so a long path could overflow and crash the host TUI. Each rendered line is now truncated with `truncateToWidth` to fit the available width.
+
+## 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.2",
   "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

@@ -32,6 +32,50 @@ browser_screenshot() → browser_click(x, y) → browser_screenshot()
 Compositor-level clicks (`Input.dispatchMouseEvent`) work through iframes, shadow DOM,
 and cross-origin content. No selectors needed.
 
+## Parallelization
+
+**Always parallelize when possible.** The harness automatically serializes mutation tools so they never race on shared state. Emit independent tools in the same turn for better performance.
+
+### What can run in parallel
+
+- **Observation tools** (`browser_screenshot`, `browser_page_info`, `browser_execute_js`, `browser_list_tabs`, `browser_current_tab`, `browser_http_get`, `browser_print_to_pdf`) can run in parallel with each other and with mutation tools.
+
+- **Opening result pages:** Use `browser_open_urls` to open multiple URLs in parallel tabs. After opening, use `browser_list_tabs` to see the new tabs and `browser_switch_tab` to visit each one.
+
+- **API calls:** `browser_http_get` calls are independent of browser state — fire multiple GETs in parallel.
+
+- **Read + browser tools:** Use `read` and `browser_*` tools in the same turn — reading files or previous results is independent of browser actions.
+
+### What must be sequential (harness enforces this)
+
+- **Mutation tools** (`click`, `type`, `scroll`, `navigate`, `switch_tab`, `press_key`, `drag_and_drop`, `upload_file`, `go_back`, `go_forward`, `reload`, `handle_dialog`, `viewport_resize`, `wait_for_load`, `download`) are automatically queued through a mutex. Even if you emit them in parallel, they execute serially in FIFO order. You do not need to worry about race conditions.
+
+- **Tab switching then acting:** `browser_switch_tab` must complete before acting on the switched-to tab. This is enforced automatically.
+
+### Pattern: Parallel research across tabs
+
+```
+# Step 1: Open all result pages at once
+browser_open_urls(["url1", "url2", "url3"])
+
+# Step 2: Wait for them to load, then extract in parallel
+browser_list_tabs()  # get targetIds
+
+# Step 3: Extract data from each tab (parallel)
+browser_switch_tab(targetId1) → browser_screenshot()   # These are sequential per tab
+browser_switch_tab(targetId2) → browser_execute_js(...) # but you batch switch+act
+```
+
+### Pattern: Parallel observation + mutation
+
+```
+# Fire observation tools while a mutation is in progress
+browser_click(x, y)                           # mutation (queued)
+browser_screenshot()                            # observation (runs immediately in parallel)
+browser_page_info()                             # observation (runs immediately in parallel)
+browser_http_get("https://api.example.com")    # external (runs immediately in parallel)
+```
+
 ## Available Tools
 
 ### Navigation
@@ -49,7 +93,7 @@ and cross-origin content. No selectors needed.
 - `browser_scroll` — scroll the page at coordinates
 
 ### Visual
-- `browser_screenshot` — capture PNG screenshot
+- `browser_screenshot` — capture PNG or JPEG screenshot (rendered inline in the TUI)
 
 ### Data Extraction
 - `browser_execute_js` — execute JavaScript and return result
@@ -86,8 +130,9 @@ browser_http_get("https://api.example.com/data")
 
 ### Scrolling
 ```
-browser_screenshot() → browser_scroll({ deltaY: -500 }) → browser_screenshot()
+browser_screenshot() → browser_scroll({ deltaY: 500 }) → browser_screenshot()
 ```
+Note: deltaY follows W3C wheel-event convention: positive=down, negative=up. Default deltaY=300 scrolls down.
 
 ### Research (search engine + browser_open_urls)
 ```
@@ -130,7 +175,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 +196,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 +252,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;
+    },
+  };
+};