@ultimat3/cli 20.2.1 → 21.0.0

package/CLAUDE.md

@@ -414,7 +414,11 @@ to know about everything — so the join is here, and it is the same rule
 | `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-e2e-session.ts` | the BROWSER half, `E2eSession`: every target auto-attached at browser level and PAUSED until its Network domain is on (a SharedWorker opens its socket at start-up); `newTab()`, `addInitScript()`, `offline()` for every page and worker including later ones, `setCookie()`, and the log of every WebSocket (`sockets()`) and request (`requests()`) in any realm. A page's own workers attach under it UNPAUSED — paused there, the emitted service worker never took control (measured, `e2e/service-worker.e2e.test.ts`) |
+| `cdp-e2e-page.ts` | one TAB, `E2eTab`: `E2eBrowserPage`'s five methods plus `reload`, `waitFor`, `indexedDbNames`, `close`. `offline()` forwards to the session — the switch is browser-wide |
+| `e2e-app.ts` | `startE2eApp({ root, mode: 'dev' \| 'serve', seed })`: reset + seed + spawn on a THROWAWAY `ULTIMATE_STATE_DIR` (database, disk, dev lock) and a free web AND metrics port, `/readyz`-gated, `stop()` removes the directory. Never the developer's `.x/pgdata`; two apps and an `x dev` coexist. Measured: `examples/dummy` up in ~12 s |
+| `e2e-preload.ts` + `e2e-browser-handle.ts` | the `e2e` step's own preload: with `ULTIMATE_E2E_ROOT` set (`E2E_ROOT_ENV`, by `verify-e2e.ts`) it spawns that app on a throwaway database, opens ONE browser, `installE2eDriver`s its first tab, and publishes the whole `E2eBrowser` for `e2eBrowser()` and the app for `e2eApp()`; `e2eBaseUrl()` is a function answering the spawned app's origin, never an env var |
+| `verify-e2e.ts` | `withE2eApp`: in an APP on a machine with Chrome, the `e2e` step spawns the app and runs the suite with `--preload e2e-preload.ts`. No browser or not an app: the suite runs exactly as before. Until this, no app ever installed a driver, so every `e2eTest` skipped and every `page` fixture refused |
 | `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
@@ -1249,6 +1253,70 @@ is a fact about the deployment, not an app config choice, and one image runs beh
 one cluster and behind nothing on a laptop. Without it `ctx.ip` is the ingress's socket address on
 every request, so the limiter keys the whole fleet's anonymous traffic into one bucket.
 
+### The document carries the page's client scope — on private documents only
+
+`dev-render.ts` puts `@ultimat3/render`'s `clientScopeTag(clientScopeOf(ctx.actor))` (`@ultimat3/auth`) in the head of a
+gated `ssr` page and every `stream` — the documents whose own headers say `private`
+(`documentCarriesScope`). A shareable document carries none, because a CDN would hand one visitor's
+scope to the next. `dev-render-scope.test.ts` drives `static`, `isr`, `ssr` (gated and not) and `stream` over the real pipeline. There is
+no island bootstrap: the page client is created lazily by the first transport call or realtime hook
+(plan 101, decided 2026-09-22; `island-bundle.ts`'s header records what an eager one cost).
+
+### The page's sync target is the framework's, and so is the worker that hosts the socket
+
+`page-sync.ts` is ONE call `cmd-dev.ts` and `serve.ts` both make (plan 101 slice 11, `As of
+2026-09-22`), so the two boots cannot serve different targets:
+
+| File | Job |
+|---|---|
+| `sync-url.ts` | `syncUrlFrom(env)`: `SYNC_URL` verbatim (must be `ws:`/`wss:`, else `X_CONFIG_INVALID` at boot), otherwise the same-origin `SYNC_PATH` — `/_x/sync`, which `x dev`, a combined-role container and the chart's ingress all serve. Never a derived neighbouring port: behind an ingress that is a URL nothing publishes. No app owns a `sync-url.ts` any more |
+| `worker-bundle.ts` | `@ultimat3/realtime/sync-worker`, resolved from the APP root, built as ONE classic-script (`iife`) browser bundle, source-addressed with `island-bundle.ts`'s `graphHash`, served `immutable` at `/_x/sync-worker/<hash>.js`. `undefined` when the app cannot resolve it — no realtime means no socket to share, and the tab-side host falls back in-page. Built at boot only: it is framework code, and a new URL per deploy is what keeps an old tab on the worker it started with. The SAME builder makes `@ultimat3/realtime/boot` at `/_x/page-boot/<hash>.js`: the disk restore and the outbox, once per page instead of in every island (a `useRecord` island 34.8 → 19.4 kB, `examples/dummy`'s `likes-badge` 48.6 → 32.9 kB) |
+| `dev-route-table.ts` | `x dev`'s route table in mount order, and the theme, error-page styles and MCP path it resolved on the way — split from `cmd-dev.ts` at its 500-line ceiling. It is where `pageSync` is called on the dev side |
+| `page-sync.ts` → `persisted` | `@ultimat3/entity`'s `persistedRecordTypes`, read per render, passed as `DocumentOptions.persisted` by both boots: render's `clientPersistTags` puts `ultimate-persist` beside the scope tag and ONLY there — persistence is per principal, so a shareable document names none |
+| `dev-render.ts` | `DocumentOptions.sync` → render's `clientSyncTags`: `ultimate-sync`, `ultimate-build`, `ultimate-sync-worker` on EVERY document (principal-free, unlike the scope tag). The page boot's `<script defer>` (render's `clientBootTags`) is rendered after the body, only when the document carries the SCOPE tag (restoring and replaying are per principal) AND an island this render emitted reaches `@ultimat3/realtime` (`island-realtime.ts` records the answer every island build computes; a page whose islands never touch a record — `examples/dummy`'s settings — pays nothing). `dev-render-scope.test.ts`. Both framework scripts resolve realtime from the root, then from `apps/*` — a workspace app's realtime is `apps/web`'s dependency, and resolving from the root alone silently built no worker and no boot for `examples/dummy`. The static export carries none — it has no sync node |
+
+### Realtime is installed FOR the author, only where it is used
+
+`island-realtime.ts` (plan 101 slice 14, `As of 2026-09-22`): an island whose own import graph
+reaches `@ultimat3/realtime` — walked with `live-routes.ts`'s `firstInGraph`, relative specifiers
+only, the transpiler reading re-exports and erasing `import type` — is built from a virtual entry
+that calls `installRealtime({ signal: createSignal })` with that bundle's solid-js before the
+island's module body runs. Every other island is built from its own file, byte for byte. +103 B on
+a Solid island reading `useConnection`, +0 elsewhere. A PACKAGE importing realtime for an island is
+the walk's blind spot, and a hook there throws `X_REALTIME_UNINSTALLED` by name.
+
+### `x verify` runs the static steps beside the serial suites
+
+`verify-run.ts`'s `BESIDE_SERIAL_SUITES` — `lint`, `boundaries`, `filesize`, `package-shape`,
+`errors` — start when `live` does and are joined before the first step after `eval` (DX ledger #14).
+They read the tree and write nothing a later step reads; `typecheck` stays first and alone, `unit`
+alone. The table, `--json` and every step name keep the declared order; `data.durationMs` is WALL
+time now, not the sum of step times. Measured locally on the framework root, 12 cores, one run
+each, `As of 2026-09-22`: **395 s → 270 s** wall. `verify-run-overlap.test.ts` pins both halves.
+
+### A browser-only read in a module no island imports is `X_LIVE_ROUTE_NO_ISLAND`
+
+`live-routes.ts`, `As of 2026-09-22`: the rule walks each route's SERVER graph (the page's relative
+imports — an island is a `src` string, never an import) and reports every module there that reads
+`useQuery`, `useConnection`, `useMutation`, `useMutationQueue`, `useRecord`, `useChannel` **or
+`hasPageSocket`**, unless some island's own graph imports that module too. Once per module, however
+many routes reach it. `hasPageSocket()` was an EXEMPTION until this date, on the argument that a
+module asking had written its fallback; on the server it answers false every time, so a guarded
+module no browser runs renders nothing forever — `examples/dummy`'s update banner, in a layout no
+island imported, never showed "A new version is ready.". The fix line starts "move it into an
+island".
+
+### A registered code nothing throws must say so
+
+`error-unthrown.ts`'s `checkErrorCodesThrown(root, page)` (DX ledger #9, `X_ERROR_CODE_UNTHROWN`):
+a code a package registry names, used nowhere else in shipped `packages/*/src` — not at a `code:`,
+not as a fallback literal, not through a table member something reads — is reported unless its
+reference row says `thrown by nothing` / `not thrown` or sits under `## Reserved codes`. The fix is
+the row, never the registration: a shipped code is stable forever. A host check, like the other
+reference-page rules — in a generated app every framework code would read as unthrown. Its limit:
+an exported class holding `code: 'X_…'` counts as a thrower whether or not anything constructs it,
+which is why `X_RPC_FAILED`'s `RpcFailedError` is not reported.
+
 ### `island-bundle.ts` is the bundler half of `hydrate`
 
 `@ultimat3/render` shipped `island()`, the collector, `emitIslandAttributes`, `hydrateRuntime`,

package/package.json

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

package/src/app-env.ts

@@ -2,9 +2,9 @@
 // `app.config.ts`, the `.env.example` projected from it, and the drift between the two. One
 // declaration, both files (axiom 2) — nothing here holds a second list of variable names.
 
-// Bun ships no equivalent: `existsSync` answers whether this root is an app, `join` builds the
-// host-separator path to the two files this module reads.
+// why: Bun ships no synchronous exists; `existsSync` answers whether this root is an app.
 import { existsSync } from 'node:fs';
+// why: Bun exposes no path API — the two files this module reads are joined to the app root.
 import { join } from 'node:path';
 import type { EnvSchema, EnvVarDecl } from '@ultimat3/core';
 import {

package/src/budgets.ts

@@ -48,8 +48,21 @@ export interface RouteStats {
 
 export interface BuildStats {
   readonly routes: readonly RouteStats[];
+  /** The measurement rules that wrote the file — `BUILD_STATS_RULES` at the time. */
+  readonly measuredBy?: number;
+  /** Set by `readBuildStats` on a file an earlier rule wrote: there are no numbers to read. */
+  readonly stale?: true;
 }
 
+/**
+ * The version of the rules `measureDocumentJs` measures by. BUMP IT whenever what is charged
+ * changes — a script exempted, a kind of tag excluded — so every stats file written under the old
+ * rule stops being read as a measurement. `.x/` survives across framework upgrades, and
+ * `examples/dummy` was charged 250 B for `/x-sw-register.js` by a file written before
+ * `FRAMEWORK_SCRIPTS` exempted it. `2`: that exemption and the page-boot decision (ledger #28).
+ */
+export const BUILD_STATS_RULES = 2;
+
 const chainOf = (stats: RouteStats): string =>
   stats.heaviestChain === undefined ? 'unknown import chain' : stats.heaviestChain.join(' -> ');
 
@@ -78,7 +91,16 @@ function declaredBudgets(js: number | null, lcp: number | undefined): string {
  * second build's. Reporting the first as the second is what sends a reader to re-run a build that
  * already did everything it was going to do.
  */
-function unmeasuredFinding(url: string, declared: string, built: boolean): Finding {
+function unmeasuredFinding(url: string, declared: string, built: boolean, stale = false): Finding {
+  if (stale) {
+    return {
+      code: 'X_BUDGET_UNMEASURED',
+      cause: `${url} declares a ${declared} budget and ${BUILD_STATS_FILE} was written by an earlier measurement rule than this gate's (v${String(BUILD_STATS_RULES)}), so its numbers are not this gate's to read`,
+      fix: 'x build --target static --json && x verify --json',
+      docs: ERROR_DOCS_URL,
+      at: url,
+    };
+  }
   return {
     code: 'X_BUDGET_UNMEASURED',
     cause: built
@@ -153,7 +175,12 @@ export function checkBudgets(
       if (js !== null || lcp !== undefined) {
         findings.push(
           ownCodeFinding(route.url, unmeasured) ??
-            unmeasuredFinding(route.url, declaredBudgets(js, lcp), stats !== undefined),
+            unmeasuredFinding(
+              route.url,
+              declaredBudgets(js, lcp),
+              stats !== undefined,
+              stats?.stale === true,
+            ),
         );
       }
       continue;
@@ -183,7 +210,9 @@ export function checkBudgets(
 export async function readBuildStats(root: string): Promise<BuildStats | undefined> {
   const path = join(root, BUILD_STATS_FILE);
   if (!existsSync(path)) return undefined;
-  return (await Bun.file(path).json()) as BuildStats;
+  const read = (await Bun.file(path).json()) as BuildStats;
+  // A file the current rules did not write carries no numbers this gate may read.
+  return read.measuredBy === BUILD_STATS_RULES ? read : { routes: [], stale: true };
 }
 
 const SCRIPT_TAG = /<script(?<attrs>[^>]*)>(?<body>[\s\S]*?)<\/script>/g;
@@ -242,14 +271,17 @@ export interface MeasuredJs {
  * and the next build measured the one before it and recorded 250. Same commit, green then red,
  * decided by whether anything had cleaned the output directory.
  *
- * ENUMERATED, and it is one entry: `serviceWorkerHead` is the only `<script src>` the framework
- * puts in a prerendered document — measured on a fresh scaffold plus `x g island` and
- * `x g route`, where `<script src="/x-sw-register.js" defer>` is the only script tag across every
- * emitted page. Two framework scripts are deliberately NOT here. `render/src/hydrate.ts`'s inline
- * module runtime is charged, because it exists only when the page ships an island — it is the
- * cost of the app's own interactivity, and a page with a `0kb` budget has none. `island-props.ts`'
- * `<script type="application/json">` is already excluded as data, by `carriesJson`. A third one
- * joins this set by a decision, here, with the same argument.
+ * ENUMERATED, and it is one entry — the service-worker register is the only framework
+ * `<script src>` EXEMPTED, not the only one emitted. Three framework scripts are deliberately
+ * CHARGED. The page boot (plan 101: the page client, the principal fence, the sync target) is
+ * framework-emitted too, and charged by decision (DX ledger #28, 2026-09-22): it ships only on a
+ * page that hydrates something, so it is part of the interactivity the app opted into, and
+ * `examples/dummy`'s route budgets already include it. `render/src/hydrate.ts`'s inline module
+ * runtime is charged for the same reason — it exists only when the page ships an island, and a
+ * page with a `0kb` budget has none. `island-props.ts`' `<script type="application/json">` is
+ * excluded as data, by `carriesJson`, not by this set. A further entry joins this set by a
+ * decision, here, with the register's argument: every document carries it and no author can
+ * remove it.
  */
 export const FRAMEWORK_SCRIPTS: ReadonlySet<string> = new Set([SW_REGISTER_PATH]);
 
@@ -335,6 +367,7 @@ export async function measureDocumentJs(html: string, out: string): Promise<Meas
  */
 export async function writeBuildStats(root: string, stats: BuildStats): Promise<string> {
   const path = join(root, BUILD_STATS_FILE);
-  await Bun.write(path, `${JSON.stringify(stats, null, 2)}\n`);
+  const stamped: BuildStats = { ...stats, measuredBy: BUILD_STATS_RULES };
+  await Bun.write(path, `${JSON.stringify(stamped, null, 2)}\n`);
   return path;
 }

package/src/build-errors.ts

@@ -0,0 +1,54 @@
+// The CLI's build and bundle refusals: an entry an app does not have, an island that will not
+// compile, a framework browser script that will not bundle. Split from `errors.ts` at its 500-line
+// ceiling; `errors.ts` re-exports every name, so no import site moves.
+
+import { UltimateError } from '@ultimat3/core';
+import { quoteArg } from './shell-quote';
+
+/**
+ * A build target names an entry file the app does not have. `x build` refuses before it spawns the
+ * builder: `bun build`'s own "module not found" says nothing about which file an Ultimate app is
+ * supposed to own, and `docker build`'s says nothing about which target wanted it.
+ */
+export class BuildEntryMissingError extends UltimateError {
+  constructor(input: { target: string; entry: string }) {
+    super({
+      code: 'X_BUILD_ENTRY_MISSING',
+      cause: `x build --target ${input.target} builds from ${input.entry}, and the app does not have it`,
+      fix: `x new scratch-app --dry-run --json   # its file list carries ${input.entry}; copy that file into this app`,
+    });
+  }
+}
+
+/**
+ * A client entry would not compile. `X_BUILD_FAILED`, not a code of its own: an island is a bundle
+ * entry point like any other, and the target's own logs are what says which line. The fix builds
+ * exactly that one file, so the next message an author reads is the compiler's and not the CLI's.
+ */
+export class IslandBuildFailedError extends UltimateError {
+  constructor(input: { file: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `${input.file} is an island entry point and would not bundle: ${input.logs}`,
+      fix: `bun build --target browser ${input.file}`,
+    });
+  }
+}
+
+/** Which framework script a page ships: the one sync worker, or the one page boot. */
+export type FrameworkScriptKind = 'sync worker' | 'page boot';
+
+/**
+ * One of the page's framework scripts would not bundle. Same code as an island: "a browser entry
+ * the framework builds did not build" is one condition, and the entry here is framework code, not
+ * the app's — the cause names WHICH script, so the reader knows what the page is now missing.
+ */
+export class FrameworkScriptBuildFailedError extends UltimateError {
+  constructor(input: { what: FrameworkScriptKind; entry: string; logs: string }) {
+    super({
+      code: 'X_BUILD_FAILED',
+      cause: `the ${input.what} (${input.entry}) would not bundle for the browser: ${input.logs}`,
+      fix: `bun build --target browser --format iife ${quoteArg(input.entry)}`,
+    });
+  }
+}

package/src/cdp-browser.ts

@@ -1,4 +1,4 @@
-// One responsibility: compose the three halves — find a browser, connect to it, attach a page —
+// One responsibility: compose the halves — find a browser, launch it over its pipe, 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
@@ -8,19 +8,25 @@
 // 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 type { E2eTab } from './cdp-e2e-page';
+import type { E2eSession } from './cdp-e2e-session';
+import { cdpE2eSession } from './cdp-e2e-session';
 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;
+  /** The first tab — what `installE2eDriver({ page })` drives. */
+  readonly page: E2eTab;
+  /**
+   * The browser itself: more tabs in the same profile, init scripts, the offline switch for every
+   * page and worker, and the log of every socket and request. What a multi-tab acceptance suite
+   * drives, on the same launch as `page` — one harness, never a second one beside the driver.
+   */
+  readonly session: E2eSession;
   /** Idempotent, and it closes both halves: the CDP socket, then the process and its profile. */
   close(): void;
 }
@@ -40,18 +46,13 @@ export interface OpenE2eBrowserOptions {
 const budget = (options: OpenE2eBrowserOptions): number =>
   finiteCount('openE2eBrowser', 'timeoutMs', options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS);
 
-const compose = (
-  launched: LaunchedBrowser,
-  connection: CdpConnection,
-  page: E2eBrowserPage,
-): E2eBrowser => ({
+const compose = (launched: LaunchedBrowser, session: E2eSession, page: E2eTab): 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();
-  },
+  session,
+  // The connection first, then the process — `launched.close()` does both, in that order: 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.
+  close: () => launched.close(),
 });
 
 /**
@@ -82,18 +83,11 @@ export async function openE2eBrowserIfAvailable(
  */
 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;
-  }
+  const { connection } = launched;
   try {
-    const page = await cdpE2ePage({ connection, loadTimeoutMs: timeoutMs });
-    return compose(launched, connection, page);
+    const session = await cdpE2eSession({ connection, loadTimeoutMs: timeoutMs });
+    return compose(launched, session, await session.newTab());
   } catch (error) {
-    connection.close();
     launched.close();
     throw error;
   }

package/src/cdp-connection.ts

@@ -1,6 +1,8 @@
-// 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.
+// One responsibility: a Chrome DevTools Protocol connection — request framing, response
+// correlation, and the per-call deadline — over a TRANSPORT that moves whole messages. Two exist:
+// the pipe a launched Chrome is driven over (`cdp-pipe.ts`, what the e2e driver uses) and a remote
+// browser's WebSocket (`cdpConnect` below). Launching is `cdp-launch.ts`; 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
@@ -57,12 +59,33 @@ const errorText = (frame: Record<string, unknown>): string | undefined => {
   return typeof message === 'string' ? message : 'the browser refused the call';
 };
 
+/**
+ * What a connection needs of the wire: whole messages out, whole messages in, and a close. Framing
+ * is the transport's — a WebSocket frames per message, the pipe splits on NUL — so correlation and
+ * deadlines are written once, over either.
+ */
+export interface CdpTransport {
+  send(text: string): void;
+  close(): void;
+  /** Installed exactly once, by the connection, before the first `send`. */
+  listen(handlers: {
+    readonly message: (text: string) => void;
+    readonly closed: (reason: string) => void;
+  }): void;
+}
+
 export interface CdpConnectionOptions {
   readonly endpoint: string;
   /** Per-call deadline. A CDP call that never answers is a suite that never finishes. */
   readonly timeoutMs: number;
 }
 
+/**
+ * A remote browser over its WebSocket url. NOT the e2e driver's wire: measured in the dummy's
+ * `offline-feed` suite on Bun 1.4.0, Bun's WebSocket client handed `onmessage` text spliced out of
+ * several frames — 64 unparseable frames in one run, one of them the reply to a `Runtime.evaluate`
+ * that then waited out its whole deadline. A launched Chrome is driven over `cdp-pipe.ts` instead.
+ */
 export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConnection> {
   assert(
     options.endpoint.startsWith('ws://') || options.endpoint.startsWith('wss://'),
@@ -70,6 +93,40 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
     'pass the `webSocketDebuggerUrl` Chrome prints on stderr, or the one /json/version answers',
   );
   const socket = new WebSocket(options.endpoint);
+  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 the handshake's only until `listen` below reassigns it: 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' }),
+      );
+    };
+  });
+
+  const transport: CdpTransport = {
+    send: (text) => socket.send(text),
+    close: () => socket.close(),
+    listen(handlers) {
+      socket.onmessage = (event: MessageEvent): void => {
+        handlers.message(typeof event.data === 'string' ? event.data : '');
+      };
+      socket.onclose = (): void => handlers.closed('the browser closed the CDP connection');
+      socket.onerror = (): void => handlers.closed('the CDP connection failed');
+    },
+  };
+  return cdpConnectOver(transport, options.timeoutMs);
+}
+
+/** A connection over any transport — correlation, deadlines and events, written once. */
+export function cdpConnectOver(transport: CdpTransport, timeoutMs: number): CdpConnection {
   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>>();
@@ -91,8 +148,7 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
     waiters.clear();
   };
 
-  socket.onmessage = (event: MessageEvent): void => {
-    const raw = typeof event.data === 'string' ? event.data : '';
+  const message = (raw: string): void => {
     let frame: Record<string, unknown>;
     try {
       frame = JSON.parse(raw) as Record<string, unknown>;
@@ -134,27 +190,7 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
           : 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');
+  transport.listen({ message, closed: abandon });
 
   return {
     send(method, params = {}, sessionId): Promise<CdpResult> {
@@ -168,10 +204,10 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
       return new Promise<CdpResult>((resolve, reject) => {
         const timer = setTimeout(() => {
           pending.delete(id);
-          reject(new CdpTimeoutError({ method, timeoutMs: options.timeoutMs }));
-        }, options.timeoutMs);
+          reject(new CdpTimeoutError({ method, timeoutMs: timeoutMs }));
+        }, timeoutMs);
         pending.set(id, { resolve, reject, timer });
-        socket.send(
+        transport.send(
           JSON.stringify({ id, method, params, ...(sessionId === undefined ? {} : { sessionId }) }),
         );
       });
@@ -205,7 +241,7 @@ export async function cdpConnect(options: CdpConnectionOptions): Promise<CdpConn
     close(): void {
       listeners.clear();
       abandon('the driver closed the CDP connection');
-      socket.close();
+      transport.close();
     },
   };
 }