bun-webview2 0.0.0-stage → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.3.0 — 2026-10-13
+
+- Window layer replaced: hosts now drive the [C `webview` library](https://github.com/webview/webview) through `bun:ffi` — zero npm runtime dependencies. The DLL (~540 KB) is built once with `zig c++` (no MSVC, no cmake); sources and pinned WebView2 SDK headers live in the build workspace.
+- Command channel: `bwv2_host_cmd` bound via `webview_bind`; the host replies through `webview_return`, so the page-side promise the parent awaits resolves exactly when the host applies the command — no separate ack protocol. All host JS runs re-entrantly inside `webview_run`'s native Win32 loop; there is no JS event loop to wedge.
+- Window controls (decorations, always-on-top, position, min/max, focus) via FFI'd user32 on the webview's HWND.
+- Parents kill their host children on exit (no orphaned hosts wedging the shared browser for the data folder).
+- Why the switch: the wry/tao host's Windows "non-blocking" pump (`run_return`) could freeze a host's entire JS event loop (verified upstream, root cause in webviewjs's `app.rs`), requiring three workarounds (page-relay commands, stdout acks, resend-until-ack). The C library has no JS loop at all, eliminating the failure class.
+- Window events, split by layer: window-level events (`move`, `resize`, `focus`/`blur` via `WM_ACTIVATE`, `theme-changed`) are forwarded from a subclassed window procedure (`SetWindowLongPtrW` via FFI, chained with `CallWindowProcW`); page-surface events (`key-down`/`key-up`, `mouse-*`, `scroll`, `file-drop`) are DOM events captured by an injected bridge and forwarded through the existing CDP binding. The split exists because input over the page never reaches the top-level window procedure (the WebView2 child HWND consumes it) — verified by live interaction testing.
+- `file-drop` delivers `File` descriptors (name/size/type) from the DOM drop event — not filesystem paths.
+- Benchmarks unchanged by the event architecture (cold ~0.8 s, evaluate/IP C sub-millisecond).
+
+## 0.2.1 — 2026-10-12
+
+- Window commands no longer depend on the host process's JS event loop. On Windows, webviewjs's pump is tao's blocking `run_return()`, which can freeze a host's whole Bun loop (timers, sockets, stdin). Commands now ride the page: `window.ipc.postMessage(...)` via CDP, delivered natively by wry, acked on stdout — immune to the wedge. (stdin and TCP control channels both proved unreliable and were removed.)
+- Hosts exit when their window closes (user close or `close` command) instead of lingering.
+- Window events verified to flow across CDP-driven navigations in both wedged and healthy hosts (an earlier "events stop after navigation" claim was a test artifact — the probe resized to an already-current size, so no event could fire).
+
+## 0.2.0 — 2026-10-12
+
+- Native window events on `win.on(...)`, typed and forwarded from the host process: `move`, `resize`, `focus`, `blur`, `key-down`, `key-up`, `mouse-enter/leave/down/up`, `scroll`, `file-drop` (drag & drop), `file-hover`, `file-hover-cancel`, `theme-changed`.
+- `win.cdp` — direct access to the live CDP connection (Network, DOM, Input, Emulation, …).
+- `serveApp(handler)` — serve app content from Bun on a free loopback port (fetch-style `Request → Response`); the answer to custom protocols.
+
+## 0.1.0 — 2026-10-12
+
+Initial release.
+
+- `Webview2Window` / `createWindow`: native WebView2 windows on Windows, created and controlled from Bun.
+- One host process per window (`src/host.ts` via `@webviewjs/webview`): wry/tao only supports window creation before its event loop is ever pumped, so each window gets a fresh, proven creation context — plus per-window crash isolation.
+- Page control over CDP loopback: `navigate`, `setHTML`, `evaluate`, `screenshot`.
+- Page → Bun IPC via `win.expose()` / `window.bwv2.call()`, JSON round-tripped, error propagation included.
+- Default hardening: Chromium context menu and DevTools/browser accelerators blocked (opt out with `contextMenu` / `devToolsKeys`).
+- Native window controls proxied: title, size, position, decorations, always-on-top, focus, minimize, maximize.
+- Content deliberately never flows through wry's `loadUrl`/`loadHtml` (first-navigation stall); everything is delivered via CDP.
+- Targets are "primed" with one throwaway `about:blank` navigation before CDP setup: on a never-navigated webview, `Runtime.enable` and even `Page.navigate` can wedge forever.
+- Per-app WebView2 data folder (`dataDir` option; default keyed to the project directory) so different Bun webview apps don't share one browser process; same-app second processes are treated as single-instance conflicts.
+- `BWV2_HOST_EXE` lets compiled executables ship a pre-compiled host binary.
+- Every CDP call rejects after a timeout (default 30s) instead of hanging forever on a wedged target; the target-wait failure names its likely causes (second app instance, hard-killed previous run) and remedies.

package/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2026 bun-webview2 contributors
+
+The bundled native/webview.dll incorporates source code from the webview
+project (https://github.com/webview/webview), Copyright (c) 2017 Serge
+Zaitsev, Copyright (c) 2022 Steffen André Langnes, licensed under the MIT
+License. The WebView2 SDK headers used to compile it are Copyright (c)
+Microsoft Corporation and are used under their license; no Microsoft code is
+redistributed in this package.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,185 @@
-# Temporary Holding Version
+# bun-webview2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Desktop apps with Bun on Windows — native **WebView2** windows you fully control from Bun, driven over the **Chrome DevTools Protocol**.
+
+No browser UI. No tab strip, no address bar, no Edge "App bar", no first-run nags. Your window, your icon, your process — and sub-millisecond control of the page inside it.
+
+Zero npm runtime dependencies: the window layer is the [C `webview` library](https://github.com/webview/webview) — a single ~540 KB DLL, built once with `zig c++` (no MSVC, no cmake) and driven directly through `bun:ffi`.
+
+## Quick start
+
+```bash
+bun add bun-webview2
+```
+
+```ts
+import { createWindow } from "bun-webview2";
+
+const win = await createWindow({
+  title: "My App",
+  width: 900,
+  height: 600,
+  html: `<h1>Hello from Bun ${Bun.version}</h1>`,
+});
+
+// Call Bun from the page
+await win.expose("readFile", async (path: string) => Bun.file(path).text());
+// ...then in the page: `await window.bwv2.call("readFile", "notes.txt")`
+
+// Drive the page from Bun
+await win.navigate("https://example.com");
+const title = await win.evaluate<string>("document.title");
+
+await Bun.write("shot.png", await win.screenshot());
+```
+
+Serve your frontend from Bun itself — the custom-protocol answer:
+
+```ts
+import { createWindow, serveApp } from "bun-webview2";
+
+const served = serveApp((req) =>
+  req.url.endsWith("/api/hello")
+    ? Response.json({ hello: "world" })
+    : new Response("<h1>My App</h1>", { headers: { "Content-Type": "text/html" } }),
+);
+await createWindow({ url: served.url });
+```
+
+Run it with `bun run`. Close the window (or call `win.close()`) and the process exits.
+
+## How it works
+
+Each window is owned by a dedicated **host process** — a tiny Bun script shipped with the library (`src/host-ffi.ts`) that creates one native window through the C webview library via `bun:ffi` and nothing else. Your process drives the page over CDP:
+
+```mermaid
+graph TB
+    A["Your Bun app"] -- "spawns one per window" --> H1["host process #1\n(C webview lib via bun:ffi)"]
+    A -- "spawns one per window" --> H2["host process #2\n(C webview lib via bun:ffi)"]
+    A -- "CDP over ws://127.0.0.1:<port>" --> P1["page target #1"]
+    A -- "CDP over ws://127.0.0.1:<port>" --> P2["page target #2"]
+    H1 -- "renders" --> P1
+    H2 -- "renders" --> P2
+```
+
+- **One host process per window** — buys per-window crash isolation: a dying window never takes your app down.
+- **Debug port** — the library passes `--remote-debugging-port` and the data folder to each host via the WebView2 loader environment variables (`WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS` / `WEBVIEW2_USER_DATA_FOLDER`). All windows of an app share one WebView2 browser process and one port; each window claims its own page target.
+- **Everything else is CDP.** Navigation, evaluation, IPC, and screenshots flow over a loopback WebSocket using Bun's built-in client. No native module is loaded in your process.
+- **Window commands ride the page.** The host's only JS runs re-entrantly inside `webview_run` — the C library's plain Win32 `GetMessage` pump, so there is no JS event loop to lose at all. Commands are CDP-evaluated as `bwv2_host_cmd(...)` in the page; the C library delivers them to the host's bind callback natively, and `webview_return` resolves the page-side promise the parent awaits — a resolved call IS the delivery confirmation. (This design came from a hard lesson: the previous wry/tao-based host's "non-blocking" pump could freeze the whole JS event loop; the C library has no loop to freeze.)
+- **Events are split by layer.** Window-level events (`move`, `resize`, `focus`/`blur` via `WM_ACTIVATE`, `theme-changed`) are forwarded from the host's subclassed window procedure. Page-surface events (`key-down`/`key-up`, `mouse-*`, `scroll`, `file-drop`) are captured as DOM events by an injected bridge and forwarded over the existing CDP binding — richer than Win32 could report (layout-aware `key`/`code`, readable `File` objects on drop) and working everywhere input actually lands, including cross-origin documents.
+
+### Why all content flows through CDP (and why windows are "primed")
+
+wry's own initial-navigation path (`NativeWindow.loadUrl` / `loadHtml`) can stall the first page load for seconds on some machines. CDP-driven navigation against the exact same WebView2 process commits in ~30 ms. bun-webview2 therefore never touches the wry navigation path — `html` and `url` options are delivered via CDP, and you get the fast path for free. (Measured on the reference machine: cold start → loaded page ≈ 1 s; `evaluate` round-trip ≈ 0.5–1 ms.)
+
+Related, and also handled for you: on a never-navigated webview target, CDP commands that need a renderer (`Runtime.enable`, even `Page.navigate` itself) can wedge forever. The library sends one throwaway `about:blank` navigation before any other setup, which commits a document and makes the whole protocol deterministic. Window events keep flowing across CDP-driven navigations — verified with real size changes in both wedged and healthy hosts.
+
+## API
+
+### `createWindow(options) → Promise<Webview2Window>`
+
+`Webview2Window.create(...)` is identical. Resolves once the initial content has loaded.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `"bun-webview2"` | Window title |
+| `width` / `height` | `number` | `800` / `600` | Initial window size |
+| `url` | `string` | — | Initial URL to load |
+| `html` | `string` | — | Initial inline HTML (loaded as a `data:` URL) |
+| `contextMenu` | `boolean` | `false` | Allow the native Chromium right-click menu (blocked by default) |
+| `devToolsKeys` | `boolean` | `false` | Allow F12 / Ctrl+Shift+I/J/C / Ctrl+U/S/P (blocked by default) |
+| `port` | `number` | auto | Fixed CDP port; all windows in a process share one port |
+| `dataDir` | `string` | `%LOCALAPPDATA%\bun-webview2\<hash>` | WebView2 user-data folder (cookies, storage, cache); process-wide, first window wins |
+| `navigationTimeoutSeconds` | `number` | `30` | `navigate()` timeout |
+
+### `Webview2Window`
+
+| Member | Description |
+|---|---|
+| `navigate(url)` | Navigate; resolves when the main frame's `load` event fires; rejects on failure/timeout |
+| `setHTML(html)` | Replace the page with inline HTML |
+| `evaluate<T>(expression)` | Evaluate an expression in the page; promises awaited; result JSON round-tripped |
+| `expose(name, fn)` | Expose a Bun function to the page as `await window.bwv2.call(name, ...args)` |
+| `screenshot({ format, quality })` | Capture the viewport as a PNG/JPEG `Blob` |
+| `on(event, handler)` | Typed window + page events: `move`, `resize`, `focus`, `blur`, `key-down`, `key-up`, `mouse-enter`/`-leave`/`-down`/`-up`, `scroll`, `file-drop`, `theme-changed`. Window events come from the host's subclassed WndProc; page events are DOM events forwarded through the injected bridge (`file-drop` gives `File` descriptors — name/size/type — not paths). |
+| | Nuances: `mouse-enter`/`-leave` fire on document-boundary crossings (the page surface); `file-drop` fires on the completed drop, not while hovering. |
+| `cdp` | The live CDP connection — escape hatch to the full DevTools protocol (Network, DOM, Input, Emulation, …) |
+| `url` | Current page URL (tracked across navigations, including page-initiated ones) |
+| `closed` / `onClosed(cb)` / `close()` | Lifecycle |
+| `setTitle`, `setSize`, `setPosition`, `setDecorations`, `setAlwaysOnTop`, `focus`, `minimize`, `maximize` | Native window controls |
+
+### Page → Bun IPC
+
+The library injects a bridge into every new document:
+
+```ts
+// Bun side
+await win.expose("greet", async (name: string) => `hello ${name}`);
+```
+
+```js
+// Page side — works in every frame, survives navigations
+const greeting = await window.bwv2.call("greet", "bun");
+```
+
+Arguments and return values are JSON round-tripped; thrown errors surface as rejected promises in the page.
+
+## Hardening
+
+bun-webview2 windows are app windows, so they ship app-hardened by default:
+
+- The Chromium right-click menu (Back / Save as / Print / Inspect / …) is **blocked** — `contextMenu: true` restores it.
+- DevTools and browser accelerators — F12, Ctrl+Shift+I/J/C, Ctrl+U/S/P — are **blocked** via injected key handlers. `devToolsKeys: true` restores them.
+
+Residual, documented honestly: Ctrl+Shift+I/J/C are browser-reserved accelerators in some WebView2 builds and may still open DevTools even when blocked. For a hard guarantee, set the `DeveloperToolsAvailability=2` (+ `DeveloperToolsAvailabilityAllowlist` for your origin) Edge policy on target machines — that also blocks CDP inspection of other targets, so read the [policy doc](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-policies/developertoolsavailability) first.
+
+## Requirements
+
+- Windows 10/11 with the WebView2 runtime (preinstalled on Windows 11 and on any machine with Edge; [download link](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) for the rest).
+- Bun 1.2+.
+
+macOS/Linux are not supported by this package (its window layer is WebView2-specific).
+
+## Security notes
+
+- The CDP port is bound to `127.0.0.1`, but **anything running on the same machine can connect to it and control your page**. This is normal for local desktop tooling and the same trade-off every CDP-driven automation tool makes. Don't build a multi-user kiosk on it.
+- Hardening is UX policy, not a security boundary: the injected key/context-menu blockers prevent accidents, not a determined local user.
+
+## Data folder and single-instance behavior
+
+Each app gets its own WebView2 data folder (overridable with `dataDir`), so two
+*different* Bun webview apps can run side by side. But one WebView2 browser
+process serves one data folder: launching a **second process of the same app**
+attaches it to the first process's browser, and its CDP port never appears —
+window creation fails with a timeout. Treat that as a single-instance guard;
+route "new window" to the running instance instead of spawning again.
+
+## Distribution
+
+- Each window spawns a host process. In development that's `bun` running the library's `src/host.ts`; your machine needs Bun on the PATH-compatible `process.execPath`.
+- For `bun build --compile` executables, compile the host separately and point the `BWV2_HOST_EXE` environment variable at it:
+  ```bash
+  bun build --compile --minify src/host-ffi.ts --outfile host.exe   # inside node_modules: copy out first
+  BWV2_HOST_EXE=./host.exe ./your-app.exe
+  ```
+- `native/webview.dll` (and the host script, unless compiled) must ship **alongside** your binary — `bun build --compile` embeds neither.
+- Give the exe a custom icon with [rcedit](https://github.com/electron/rcedit); the window inherits the process icon.
+- WebView2 writes its user-data folder per app; if you need to control where (e.g. Program Files installs), patch `userDataFolder` at the window layer.
+
+## Costs, honestly
+
+- Every window costs one Bun process (~40 MB) plus its share of the shared WebView2 browser tree. For 1–3 windows this is desktop-app normal.
+- One WebView2 browser process per app means one app instance at a time (see the data-folder section above).
+- The CDP debug port is a local-loopback control channel: fine for desktop apps, not for hostile multi-user machines (see security notes).
+
+## Development
+
+```bash
+bun x tsc --noEmit      # typecheck
+bun run example/verify.ts   # end-to-end verification (opens windows, needs display + network)
+bun run example/quickstart.ts  # human demo
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "bun-webview2",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "devDependencies": {
+    "bun-types": "^1.4.3",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "description": "Desktop apps with Bun: native WebView2 windows you fully control, driven over the Chrome DevTools Protocol.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abmach/bun-webview2.git"
+  },
+  "bugs": {
+    "url": "https://github.com/abmach/bun-webview2/issues"
+  },
+  "engines": {
+    "bun": ">=1.2"
+  },
+  "files": [
+    "src",
+    "native",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "bun",
+    "webview2",
+    "webview",
+    "desktop",
+    "gui",
+    "cdp",
+    "windows"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "types": "./src/index.ts"
+}

package/src/cdp.ts

@@ -0,0 +1,173 @@
+/**
+ * Minimal Chrome DevTools Protocol client over Bun's native WebSocket.
+ *
+ * One connection per page target. Supports command/response dispatch and
+ * event subscriptions. Deliberately tiny: bun-webview2 only needs
+ * Runtime, Page, and a handful of methods — nothing more.
+ */
+
+export interface CdpTargetInfo {
+  readonly type: string;
+  readonly title: string;
+  readonly url: string;
+  readonly webSocketDebuggerUrl: string;
+}
+
+interface CdpResponse {
+  readonly id?: number;
+  readonly method?: string;
+  readonly params?: unknown;
+  readonly result?: unknown;
+  readonly error?: { readonly message: string; readonly data?: string };
+}
+
+export interface CdpErrorPayload {
+  readonly code: number;
+  readonly message: string;
+  readonly data?: string;
+}
+
+type CdpEventHandler = (params: unknown) => void;
+
+/** Ask the OS for a free TCP port by briefly listening on port 0. */
+export async function pickFreePort(): Promise<number> {
+  const listener = Bun.listen({
+    hostname: "127.0.0.1",
+    port: 0,
+    socket: { data() {}, open() {}, close() {} },
+  });
+  const port = listener.port;
+  listener.stop(true);
+  return port;
+}
+
+/**
+ * Poll the DevTools HTTP endpoint until it lists an unclaimed page target.
+ * The endpoint only exists once the WebView2 environment is live, which is
+ * asynchronous relative to NativeWindow construction.
+ */
+export async function waitForPageTarget(
+  port: number,
+  claimed: ReadonlySet<string>,
+  timeoutMs = 15_000,
+  dataDirHint?: string,
+): Promise<CdpTargetInfo> {
+  const deadline = performance.now() + timeoutMs;
+  while (performance.now() < deadline) {
+    try {
+      const targets = (await (
+        await fetch(`http://127.0.0.1:${port}/json`, { signal: AbortSignal.timeout(500) })
+      ).json()) as unknown;
+      if (Array.isArray(targets)) {
+        const page = targets.find(
+          (t): t is CdpTargetInfo =>
+            typeof t === "object" && t !== null &&
+            "type" in t && (t as CdpTargetInfo).type === "page" &&
+            "webSocketDebuggerUrl" in t && typeof (t as CdpTargetInfo).webSocketDebuggerUrl === "string" &&
+            !claimed.has((t as CdpTargetInfo).webSocketDebuggerUrl),
+        );
+        if (page) return page;
+      }
+    } catch {
+      // endpoint not up yet — keep polling
+    }
+    await new Promise<void>((resolve) => setTimeout(resolve, 50));
+  }
+  throw new Error(
+    `bun-webview2: no CDP page target appeared on port ${port} within ${timeoutMs}ms. ` +
+      "Likely causes: another instance of this app is already running (apps are single-instance per data folder), " +
+      "or a previous run was hard-killed leaving a wedged WebView2 browser process. " +
+      (dataDirHint
+        ? `Kill lingering msedgewebview2 processes for this data folder or delete it (${dataDirHint}), or pass a different dataDir.`
+        : "Pass a different dataDir."),
+  );
+}
+
+export class CdpConnection {
+  readonly #ws: WebSocket;
+  readonly #pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
+  readonly #events = new Map<string, Set<CdpEventHandler>>();
+  #nextId = 1;
+  #closed = false;
+
+  constructor(readonly wsUrl: string) {
+    this.#ws = new WebSocket(wsUrl);
+  }
+
+  connect(): Promise<void> {
+    const { promise, resolve, reject } = Promise.withResolvers<void>();
+    this.#ws.addEventListener("open", () => resolve(), { once: true });
+    this.#ws.addEventListener("error", () => reject(new Error(`bun-webview2: failed to open CDP socket ${this.wsUrl}`)), { once: true });
+    this.#ws.addEventListener("message", (ev: MessageEvent) => this.#dispatch(ev));
+    this.#ws.addEventListener("close", () => this.#handleClose());
+    return promise;
+  }
+
+  #dispatch(ev: MessageEvent): void {
+    const msg = JSON.parse(String(ev.data)) as CdpResponse;
+    if (msg.id !== undefined) {
+      const entry = this.#pending.get(msg.id);
+      if (entry) {
+        this.#pending.delete(msg.id);
+        if (msg.error) entry.reject(new Error(`bun-webview2: CDP error: ${msg.error.message}`));
+        else entry.resolve(msg.result);
+      }
+      return;
+    }
+    if (msg.method !== undefined) {
+      this.#events.get(msg.method)?.forEach((handler) => handler(msg.params));
+    }
+  }
+
+  #handleClose(): void {
+    this.#closed = true;
+    const err = new Error("bun-webview2: CDP connection closed");
+    for (const entry of this.#pending.values()) entry.reject(err);
+    this.#pending.clear();
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  /** Send a command and await its response result. Commands that never get a
+   * response become rejections after timeoutMs instead of hanging forever —
+   * wedged WebView2 targets are a real failure mode, not a theory. */
+  call(method: string, params: Record<string, unknown> = {}, timeoutMs = 30_000): Promise<unknown> {
+    if (this.#closed) return Promise.reject(new Error("bun-webview2: CDP connection closed"));
+    const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+    const id = this.#nextId++;
+    const timer = setTimeout(() => {
+      this.#pending.delete(id);
+      reject(new Error(`bun-webview2: CDP call ${method} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    this.#pending.set(id, {
+      resolve: (value: unknown) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      reject: (err: Error) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    });
+    this.#ws.send(JSON.stringify({ id, method, params }));
+    return promise;
+  }
+
+  /** Subscribe to a CDP event; returns an unsubscribe function. */
+  on(method: string, handler: CdpEventHandler): () => void {
+    let handlers = this.#events.get(method);
+    if (!handlers) {
+      handlers = new Set();
+      this.#events.set(method, handlers);
+    }
+    handlers.add(handler);
+    return () => handlers.delete(handler);
+  }
+
+  close(): void {
+    if (!this.#closed) this.#ws.close();
+    this.#handleClose();
+  }
+}