@ultimat3/cli 18.0.0 → 19.0.0

package/CLAUDE.md

@@ -329,26 +329,120 @@ to know about everything — so the join is here, and it is the same rule
 | `e2e-evaluate.ts` | the closure→string crossing, which is the only lossy edge in the adapter |
 | `e2e-errors.ts` | one constructor per refusal |
 | `e2e-dom-fixture.ts` | a document small enough to hold in a test and real enough to RUN the expressions above |
-
-**Absent by default, and that is a requirement rather than a state.** CI has no Chrome. Nothing here
-runs until `installE2eDriver` is called, so `hasE2eDriver()` still answers `false` and the gate's
-`e2e` step still refuses instead of passing over a browser it does not have.
+| `cdp-browser.ts` | the two doors: `openE2eBrowserIfAvailable()` (undefined when there is no browser) and `openE2eBrowser()` (refuses by name), and the close that undoes both halves |
+| `cdp-launch.ts` | which Chrome, and starting it — the candidate list, the flags, and the endpoint read off its stderr |
+| `cdp-connection.ts` | CDP over Bun's own `WebSocket`: request framing, reply correlation by `id`, one-shot event waiters, the per-call deadline |
+| `cdp-e2e-page.ts` | `E2eBrowserPage`'s five methods over an attached, flattened session |
+| `cdp-errors.ts` | one constructor per way the browser half refuses |
+
+**Absent by default, and that is a requirement rather than a state.** Nothing here runs until
+`installE2eDriver` is called, so `hasE2eDriver()` still answers `false` and the gate's `e2e` step
+still refuses instead of passing over a browser it does not have. This paragraph also said "CI has
+no Chrome" until 2026-08-27, and that is false and was the reason issue #390's fourth requirement
+— a real browser check — was recorded as out of reach: GitHub-hosted `ubuntu-latest` ships one at
+`/usr/bin/google-chrome`, preinstalled, with no download step and no new dependency.
+
+**The browser is RAW CDP over Bun's own `WebSocket`, and carries no dependency.**
+`packages/scraping/src/cdp-port.ts` declares a ~25-method port because `ScrapePage` is a full
+scraping surface and its intended implementation is `puppeteer-core`. `E2eBrowserPage` is FIVE
+methods, and CDP's wire format is one JSON object with an `id` — so the whole thing an e2e driver
+needs is four small modules, which is why `x test e2e` needs nothing installed that `bun install`
+did not already put there. `e2e/cdp-browser.e2e.test.ts` drives a real Chrome against a real
+`Bun.serve` and asserts all five methods; `openE2eBrowserIfAvailable()` answering `undefined` is
+what makes it a SKIP on a laptop without one rather than a red step.
+
+**The load EVENT is the completion signal, never `Page.navigate`'s reply.** Measured on Chrome 150:
+a navigation that swaps the render process — `about:blank` → `http://localhost:<port>/`, the most
+ordinary one there is — loads the page, hits the server and answers a later `Runtime.evaluate` from
+the new document, and the navigate frame **never comes back at all**. A driver that awaited the
+reply waited out its full deadline on every first navigation. So `cdpConnect().once()` registers a
+`Page.loadEventFired` waiter BEFORE the send, and the reply is raced against it — still read, but
+only for `errorText`, which is the one place a refused navigation is named.
+
+**A CDP call is deadlined and a close settles every call in flight.** Without that, a suite whose
+browser died waits out one full deadline per call and reports a timeout, where the true fault is a
+dead browser. The four codes are four repairs, which is why they are not one:
+`X_CDP_BROWSER_MISSING` (install one), `X_CDP_LAUNCH_FAILED` (read the browser's own stderr, which
+the cause carries), `X_CDP_CALL_FAILED` (look at the page), `X_CDP_TIMEOUT` (raise the deadline).
 
 **`evaluate` is the edge that cannot be lossless.** `PageLike.evaluate` takes a closure and every
 browser port in this framework takes a string, so what crosses is `Function.prototype.toString()`
 and nothing else. A zero-parameter closure naming only page globals is supported; a native or bound
 function, a declared parameter and a method shorthand are refused STATICALLY, before a byte leaves;
 a binding the page does not have comes back named, from the page's own `ReferenceError`. Measured on
-Bun 1.4.0 and load-bearing: **Bun's transpiler folds `wanted === 3` to `!0` before `toString()` ever
+Bun 1.3.14 and 1.4.0 alike — re-measured on both when the repo moved back to the 1.3 series, because a version-stamped claim that names one runtime is unread evidence on the other — and load-bearing: **Bun's transpiler folds `wanted === 3` to `!0` before `toString()` ever
 runs**, so a captured PRIMITIVE can vanish from the source and never fail at all, while a captured
 reference always survives as its name. No static rule in this process can see the difference — which
 is why the refusal is raised from the page's answer rather than from a scan of the source.
 
-**Three of `E2eFixtures`' four members refuse, deliberately.** `offline()` and `online()` need a CDP
-method for the browser's own network state and `CdpPageLike` declares none; `update()` needs a second
-build served under a new id, which is a fact about the server. A fixture that silently no-opped would
-make the assertion after it read as proof — `offline()` followed by "the fallback rendered" is the
-app's ONLINE page passing an offline test.
+**One of `E2eFixtures`' four members still refuses, and it is the one that is not a port gap.**
+`update()` needs a second build served under a new immutable build id, which is a fact about the
+SERVER, and no page port has ever been able to speak for one. `offline()`/`online()` FORWARD — to
+`E2eBrowserPage.offline`, which `cdp-e2e-page.ts` implements as
+`Network.emulateNetworkConditions` and `@ultimat3/scraping` implements through
+`CdpPageLike.setOfflineMode`. They refused until 2026-08-27 on a reason the tree contradicted on
+the day it was written. A fixture that silently no-opped would make the assertion after it read as
+proof — `offline()` followed by "the fallback rendered" is the app's ONLINE page passing an offline
+test — so an `E2eBrowserPage` that declares no `offline` still gets the refusal, now naming the
+method the double is missing rather than a capability the framework does not have.
+
+## The service worker is emitted here, because the emitter needs facts only a build has
+
+`@ultimat3/pwa` shipped `generateServiceWorker`, `buildPrecacheManifest`, `offlineFallbackSource`,
+`backgroundSyncSource` and `pushSource` since it existed, and every one had **zero callers** outside
+its own package. So `pwa.offline`, `pwa.backgroundSync`, `pwa.push` and every route's own `offline:`
+were declarations with no build behind them, and no Ultimate app worked offline however its config
+was written (#390). `sw-artifacts.ts` is the caller.
+
+**Why here and not beside the manifest.** `loadPwaArtifacts(root)` needs a root and a config file;
+the worker needs the ROUTE TABLE and the ISLAND BUNDLE as well — facts only a booted app and a
+finished build have. Splitting them keeps `loadPwaArtifacts` callable before either exists, which
+`x doctor` and the icon writer rely on. The route table is `describeRoutes()`, the one projection
+`x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a route added to the app
+cannot be missing from the precache manifest.
+
+| Surface | What it does with the worker |
+|---|---|
+| `cmd-dev.ts` | mounts `/sw.js` and `/x-sw-register.js`; built ONCE at boot and deliberately not rebuilt on the watcher tick — a worker that changes under a page it already controls is the update path, and re-emitting one per keystroke exercises it on every save |
+| `serve.ts` | the same two routes in the container, from the same call |
+| `prerender.ts` | writes both as FILES into the export — a static host runs no route table, so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the artifact |
+
+**Registration is an EXTERNAL script, never inline**, and that is a CSP fact rather than a
+preference: `startWeb` computes a `script-src` sha256 per inline script, so an unhashed one is
+blocked in the container while passing report-only under `x dev` — which is how the hydration
+runtime shipped broken once already.
+
+**`sw.js` is served `no-store` with `Service-Worker-Allowed: /`.** A cached `sw.js` is a worker that
+cannot be replaced: the browser re-fetches it to decide whether an update exists, and an
+intermediary answering the old bytes pins every client to the deploy that shipped them. Without the
+header the browser refuses to let a worker served from `/` control `/` — the failure `assertScope`
+cannot see, because the scope a REGISTRATION asks for has to be allowed by the script's own response
+and not only by its path.
+
+**`api/` and `shared/` never cross.** An API response is a JSON document whose freshness is the
+app's business, and precaching one serves a stale answer to a client that had a network; `shared/`
+is not a URL at all. The filter is a `flatMap` rather than `filter().map()` because the predicate
+does not narrow `surface` for the map that follows it, and a cast would hide the day a fifth surface
+arrives.
+
+**`pwa.push` is read and still wires nothing, and it says so.** `generateServiceWorker` emits a push
+handler only when a VAPID key comes with the capability, there is no `pwa.vapid` config key, and it
+drops the handler in SILENCE otherwise. `pushWarning` is this module's own finding, reported through
+`x build --json`'s `serviceWorkerWarnings` — `jobs.driver`'s shape one package over, refused the same way.
+
+**The browser check is what let any of this ship.** #390's fourth requirement was *"a real browser
+check that the emitted worker installs, activates and serves the fallback offline. Until it exists,
+do not ship the worker"* — a bad `sw.js` is sticky in a way a manifest is not.
+`e2e/service-worker.e2e.test.ts` registers the emitted file in a real Chrome, waits for it to take
+control, takes the network away, and asserts that a runtime route with nothing cached renders the
+offline document.
+
+**And it found the driver bug first.** `E2eFixtures.offline()` did not take the SERVICE WORKER
+offline: a worker fetches on its own CDP target, the condition was only ever set on the page's, and
+a `networkFirst` route the cache had never seen still answered from the network. So an offline
+assertion made on a PWA tested nothing. `cdp-e2e-page.ts` now auto-attaches worker targets and
+carries the condition onto each, including one that attaches AFTER `offline(true)` — the ordinary
+case for a PWA.
 
 ## The `errors` step enforces the error contract
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -37,34 +37,34 @@
   },
   "dependencies": {
     "@babel/core": "^7.28.4",
-    "@ultimat3/action": "18.0.0",
-    "@ultimat3/admin": "18.0.0",
-    "@ultimat3/ai": "18.0.0",
-    "@ultimat3/auth": "18.0.0",
-    "@ultimat3/cache": "18.0.0",
-    "@ultimat3/core": "18.0.0",
-    "@ultimat3/db": "18.0.0",
-    "@ultimat3/entity": "18.0.0",
-    "@ultimat3/flags": "18.0.0",
-    "@ultimat3/http": "18.0.0",
-    "@ultimat3/i18n": "18.0.0",
-    "@ultimat3/jobs": "18.0.0",
-    "@ultimat3/mail": "18.0.0",
-    "@ultimat3/manifest": "18.0.0",
-    "@ultimat3/mcp": "18.0.0",
-    "@ultimat3/money": "18.0.0",
-    "@ultimat3/notify": "18.0.0",
-    "@ultimat3/policy": "18.0.0",
-    "@ultimat3/pwa": "18.0.0",
-    "@ultimat3/query": "18.0.0",
-    "@ultimat3/realtime": "18.0.0",
-    "@ultimat3/render": "18.0.0",
-    "@ultimat3/schema": "18.0.0",
-    "@ultimat3/scraping": "18.0.0",
-    "@ultimat3/seo": "18.0.0",
-    "@ultimat3/storage": "18.0.0",
-    "@ultimat3/testing": "18.0.0",
-    "@ultimat3/time": "18.0.0",
+    "@ultimat3/action": "19.0.0",
+    "@ultimat3/admin": "19.0.0",
+    "@ultimat3/ai": "19.0.0",
+    "@ultimat3/auth": "19.0.0",
+    "@ultimat3/cache": "19.0.0",
+    "@ultimat3/core": "19.0.0",
+    "@ultimat3/db": "19.0.0",
+    "@ultimat3/entity": "19.0.0",
+    "@ultimat3/flags": "19.0.0",
+    "@ultimat3/http": "19.0.0",
+    "@ultimat3/i18n": "19.0.0",
+    "@ultimat3/jobs": "19.0.0",
+    "@ultimat3/mail": "19.0.0",
+    "@ultimat3/manifest": "19.0.0",
+    "@ultimat3/mcp": "19.0.0",
+    "@ultimat3/money": "19.0.0",
+    "@ultimat3/notify": "19.0.0",
+    "@ultimat3/policy": "19.0.0",
+    "@ultimat3/pwa": "19.0.0",
+    "@ultimat3/query": "19.0.0",
+    "@ultimat3/realtime": "19.0.0",
+    "@ultimat3/render": "19.0.0",
+    "@ultimat3/schema": "19.0.0",
+    "@ultimat3/scraping": "19.0.0",
+    "@ultimat3/seo": "19.0.0",
+    "@ultimat3/storage": "19.0.0",
+    "@ultimat3/testing": "19.0.0",
+    "@ultimat3/time": "19.0.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-root.ts

@@ -12,12 +12,21 @@ export const MANIFEST_FILE = 'x.manifest.json';
  * through 2026-08-27 while `x test` spent `bun test --isolate` — a flag Bun introduced in
  * **1.3.13** — so a user on a Bun this file declared supported got an unknown-flag failure out of
  * the gate's dominant step, with `x doctor` reporting the runtime as fine. `--parallel` arrived in
- * the same release and is emitted now.
+ * the same release and is emitted now, so the floor may never fall below that patch.
  *
  * `1.4.0` rather than `1.3.13` because a floor is a claim about a runtime somebody TESTED: CI pins
  * `1.4.x`, both images build on `oven/bun:1.4-*`, and the per-worker database rests on
  * `BUN_TEST_WORKER_ID`'s numbering, probed on 1.4.0 and on nothing older. `scripts/bun-pin.test.ts`
  * holds this to the same series as every other pin.
+ *
+ * **Lowering it to 1.3.14 was tried on 2026-08-27 and refused**, and the argument for trying was
+ * sound — `--isolate` and `--parallel` are 1.3.13 features, no package here calls a 1.4-only API
+ * (`bun run typecheck` is clean against `@types/bun@1.3.14`), and `>=1.4.0` therefore bars Bun 1.3
+ * users for a capability the framework does not use. What refused it is a Bun 1.3.14 defect, not
+ * the paperwork: a service shutdown against a destroyed database never resolves there
+ * (`queue.stop()`, reproduced by `dev-runtime.live.test.ts`), so an app on a runtime this line
+ * declared supported would hang on graceful shutdown the moment its database went away. The full
+ * measurement is in `.github/actions/setup/action.yml`; read it before lowering this.
  */
 export const REQUIRED_BUN = '1.4.0';
 

package/src/cdp-browser.ts

@@ -0,0 +1,100 @@
+// One responsibility: compose the three halves — find a browser, connect to it, attach a page —
+// into the one object `installE2eDriver({ page })` takes, plus the way to shut it down.
+//
+// **Absent is a SKIP, never a failure, and that is a requirement rather than a state.** A CI box
+// with no Chrome must not turn the `e2e` step red for a reason unrelated to the change, which is
+// the rule `packages/cli/CLAUDE.md` already states about `x shot`, `x pr` and `x ci`.
+// `openE2eBrowserIfAvailable` is that door; `openE2eBrowser` refuses by name for a caller that has
+// already decided a browser is required.
+
+import { finiteCount } from '@ultimat3/core';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnect } from './cdp-connection';
+import { cdpE2ePage } from './cdp-e2e-page';
+import { CdpBrowserMissingError } from './cdp-errors';
+import type { LaunchedBrowser } from './cdp-launch';
+import { CHROME_CANDIDATES, findChrome, launchChrome } from './cdp-launch';
+import type { E2eBrowserPage } from './e2e-page';
+
+/** How long a launch, a connect or a single CDP call may take. One number, three deadlines. */
+export const DEFAULT_CDP_TIMEOUT_MS = 30_000;
+
+export interface E2eBrowser {
+  readonly page: E2eBrowserPage;
+  /** Idempotent, and it closes both halves: the CDP socket, then the process and its profile. */
+  close(): void;
+}
+
+export interface OpenE2eBrowserOptions {
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly timeoutMs?: number | undefined;
+}
+
+/**
+ * Screened HERE, before a browser exists, and not where it lands. It becomes three deadlines — the
+ * launch, the handshake and every CDP call — and `Number(process.env.E2E_TIMEOUT ?? '')` is `NaN`
+ * for an unset variable and is not nullish, so `??` keeps it: a `setTimeout` given `NaN` fires at
+ * 1ms in this Bun, which makes every call report `X_CDP_TIMEOUT` against a browser that was
+ * answering. A misdiagnosis reported as a test failure is worse than the failure.
+ */
+const budget = (options: OpenE2eBrowserOptions): number =>
+  finiteCount('openE2eBrowser', 'timeoutMs', options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS);
+
+const compose = (
+  launched: LaunchedBrowser,
+  connection: CdpConnection,
+  page: E2eBrowserPage,
+): E2eBrowser => ({
+  page,
+  close(): void {
+    // The socket first: closing the process out from under an open connection makes every
+    // in-flight call report "the browser closed the CDP connection", which is true and useless.
+    connection.close();
+    launched.close();
+  },
+});
+
+/**
+ * Launch a browser and attach one page to it. Refuses with `X_CDP_BROWSER_MISSING` when there is
+ * nothing to launch — the caller that wants a skip asks `openE2eBrowserIfAvailable` instead.
+ */
+export async function openE2eBrowser(options: OpenE2eBrowserOptions = {}): Promise<E2eBrowser> {
+  const timeoutMs = budget(options);
+  const executable = await findChrome(options.env ?? process.env);
+  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+  return openLaunched(executable, timeoutMs);
+}
+
+/** `undefined` when this machine has no browser. Every other failure still throws. */
+export async function openE2eBrowserIfAvailable(
+  options: OpenE2eBrowserOptions = {},
+): Promise<E2eBrowser | undefined> {
+  const timeoutMs = budget(options);
+  const executable = await findChrome(options.env ?? process.env);
+  if (executable === undefined) return undefined;
+  return openLaunched(executable, timeoutMs);
+}
+
+/**
+ * The half both doors share. Each step undoes the ones before it on the way out: a Chrome that
+ * launched and then refused the CDP handshake would otherwise be left running, holding its profile
+ * directory, for the rest of the test process — one leaked browser per failing suite.
+ */
+async function openLaunched(executable: string, timeoutMs: number): Promise<E2eBrowser> {
+  const launched = await launchChrome({ executable, timeoutMs });
+  let connection: CdpConnection;
+  try {
+    connection = await cdpConnect({ endpoint: launched.endpoint, timeoutMs });
+  } catch (error) {
+    launched.close();
+    throw error;
+  }
+  try {
+    const page = await cdpE2ePage({ connection, loadTimeoutMs: timeoutMs });
+    return compose(launched, connection, page);
+  } catch (error) {
+    connection.close();
+    launched.close();
+    throw error;
+  }
+}

package/src/cdp-connection.ts

@@ -0,0 +1,211 @@
+// One responsibility: a Chrome DevTools Protocol connection over Bun's own WebSocket — request
+// framing, response correlation, and the per-call deadline. Launching a browser is `cdp-launch.ts`
+// and the page surface is `cdp-e2e-page.ts`; this file knows nothing about either.
+//
+// **No library, and that is the point rather than an economy.** `packages/scraping/src/cdp-port.ts`
+// declares a ~25-method port because `ScrapePage` is a full scraping surface, and its intended
+// implementation is `puppeteer-core`. `E2eBrowserPage` is FIVE methods, and CDP's wire format is
+// one JSON object with an `id` — so the whole thing an e2e driver needs is this file plus two
+// small ones, on Bun's native `WebSocket`, with no dependency to add to a repo whose first
+// non-negotiable is that Bun's natives replace most of them.
+
+import { assert } from '@ultimat3/core';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+
+/** One CDP result. `unknown` because every payload here is somebody else's JSON. */
+export interface CdpResult {
+  readonly result?: Record<string, unknown> | undefined;
+}
+
+export interface CdpConnection {
+  /** Send one command. `sessionId` targets an attached page rather than the browser itself. */
+  send(method: string, params?: Record<string, unknown>, sessionId?: string): Promise<CdpResult>;
+  /**
+   * Wait for the next occurrence of one CDP **event**, or for the deadline. Answers `true` when the
+   * event arrived and `false` when it did not — it never throws, because every caller has a better
+   * assertion to fail on than "the event was late".
+   *
+   * It exists because a command's reply is not always the signal. `Page.navigate`'s reply is
+   * DROPPED whenever the navigation swaps the render process — measured on Chrome 150: the page
+   * loads, the server is hit, a later `Runtime.evaluate` answers, and the navigate frame never
+   * comes back at all. A driver that treated the reply as the completion signal waits out its full
+   * deadline on the most ordinary navigation there is.
+   */
+  once(method: string, sessionId: string | undefined, timeoutMs: number): Promise<boolean>;
+  /**
+   * Subscribe to every occurrence of one CDP event, until the returned function is called.
+   *
+   * `once` cannot express what this is for: a target that attaches AFTER the driver stopped
+   * listening is a service worker whose network conditions nobody set, which is an `offline()`
+   * that silently does nothing to the one thing serving the page.
+   */
+  on(method: string, listener: (params: Record<string, unknown>) => void): () => void;
+  close(): void;
+}
+
+interface Pending {
+  readonly resolve: (value: CdpResult) => void;
+  readonly reject: (reason: Error) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+}
+
+/** A CDP error frame: `{ error: { code, message } }`, both fields somebody else's. */
+const errorText = (frame: Record<string, unknown>): string | undefined => {
+  const error = frame['error'];
+  if (typeof error !== 'object' || error === null) return undefined;
+  const message = (error as Record<string, unknown>)['message'];
+  return typeof message === 'string' ? message : 'the browser refused the call';
+};
+
+export interface CdpConnectionOptions {
+  readonly endpoint: string;
+  /** Per-call deadline. A CDP call that never answers is a suite that never finishes. */
+  readonly timeoutMs: number;
+}
+
+export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConnection> {
+  assert(
+    options.endpoint.startsWith('ws://') || options.endpoint.startsWith('wss://'),
+    `the CDP endpoint is ${options.endpoint === '' ? 'empty' : 'not a WebSocket url'}`,
+    'pass the `webSocketDebuggerUrl` Chrome prints on stderr, or the one /json/version answers',
+  );
+  const socket = new WebSocket(options.endpoint);
+  const pending = new Map<number, Pending>();
+  const waiters = new Set<(method: string, sessionId: string | undefined) => void>();
+  const listeners = new Map<string, Set<(params: Record<string, unknown>) => void>>();
+  let nextId = 0;
+  let closed = false;
+
+  // Every in-flight call is settled on close. Without this a suite whose browser died waits out
+  // one full deadline per call and reports a timeout, where the true fault is a dead browser.
+  const abandon = (reason: string): void => {
+    closed = true;
+    for (const [, one] of pending) {
+      clearTimeout(one.timer);
+      one.reject(new CdpCallFailedError({ method: 'the connection', detail: reason }));
+    }
+    pending.clear();
+    // A waiter is a "did this happen" question, and on a dead connection the answer is no. Its
+    // own timer settles it, so nothing is left hanging; clearing the set only stops a late frame
+    // from resolving a waiter whose connection has gone.
+    waiters.clear();
+  };
+
+  socket.onmessage = (event: MessageEvent): void => {
+    const raw = typeof event.data === 'string' ? event.data : '';
+    let frame: Record<string, unknown>;
+    try {
+      frame = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      // An unparseable frame is the browser's, not ours, and there is no call to fail with it:
+      // correlation is by `id`, and a frame we cannot read has none. Events land here too.
+      return;
+    }
+    const id = frame['id'];
+    if (typeof id !== 'number') {
+      const method = frame['method'];
+      if (typeof method !== 'string') return;
+      const on = frame['sessionId'];
+      for (const waiter of [...waiters]) waiter(method, typeof on === 'string' ? on : undefined);
+      const subscribed = listeners.get(method);
+      if (subscribed !== undefined) {
+        const params = frame['params'];
+        const payload: Record<string, unknown> =
+          typeof params === 'object' && params !== null ? (params as Record<string, unknown>) : {};
+        // A copy, because a listener may unsubscribe itself while this loop is running.
+        for (const listener of [...subscribed]) listener(payload);
+      }
+      return;
+    }
+    const one = pending.get(id);
+    if (one === undefined) return;
+    pending.delete(id);
+    clearTimeout(one.timer);
+    const failed = errorText(frame);
+    if (failed !== undefined) {
+      one.reject(new CdpCallFailedError({ method: `call ${String(id)}`, detail: failed }));
+      return;
+    }
+    const result = frame['result'];
+    one.resolve({
+      result:
+        typeof result === 'object' && result !== null
+          ? (result as Record<string, unknown>)
+          : undefined,
+    });
+  };
+  socket.onclose = (): void => abandon('the browser closed the CDP connection');
+  socket.onerror = (): void => abandon('the CDP connection failed');
+
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new CdpTimeoutError({ method: 'connect', timeoutMs: options.timeoutMs }));
+    }, options.timeoutMs);
+    socket.onopen = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    // `onerror` is replaced for the handshake only, then restored above: a failure BEFORE open has
+    // no pending call to abandon, and rejecting is the only way the caller hears about it.
+    socket.onerror = (): void => {
+      clearTimeout(timer);
+      reject(
+        new CdpCallFailedError({ method: 'connect', detail: 'the browser refused the connection' }),
+      );
+    };
+  });
+  socket.onerror = (): void => abandon('the CDP connection failed');
+
+  return {
+    send(method, params = {}, sessionId): Promise<CdpResult> {
+      if (closed) {
+        return Promise.reject(
+          new CdpCallFailedError({ method, detail: 'the CDP connection is already closed' }),
+        );
+      }
+      nextId += 1;
+      const id = nextId;
+      return new Promise<CdpResult>((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pending.delete(id);
+          reject(new CdpTimeoutError({ method, timeoutMs: options.timeoutMs }));
+        }, options.timeoutMs);
+        pending.set(id, { resolve, reject, timer });
+        socket.send(
+          JSON.stringify({ id, method, params, ...(sessionId === undefined ? {} : { sessionId }) }),
+        );
+      });
+    },
+    once(method, sessionId, timeoutMs): Promise<boolean> {
+      if (closed) return Promise.resolve(false);
+      return new Promise<boolean>((resolve) => {
+        const waiter = (seen: string, on: string | undefined): void => {
+          if (seen !== method) return;
+          if (sessionId !== undefined && on !== sessionId) return;
+          clearTimeout(timer);
+          waiters.delete(waiter);
+          resolve(true);
+        };
+        const timer = setTimeout(() => {
+          waiters.delete(waiter);
+          resolve(false);
+        }, timeoutMs);
+        waiters.add(waiter);
+      });
+    },
+    on(method, listener): () => void {
+      const subscribed = listeners.get(method) ?? new Set();
+      subscribed.add(listener);
+      listeners.set(method, subscribed);
+      return () => {
+        subscribed.delete(listener);
+        if (subscribed.size === 0) listeners.delete(method);
+      };
+    },
+    close(): void {
+      listeners.clear();
+      abandon('the driver closed the CDP connection');
+      socket.close();
+    },
+  };
+}