@ultimat3/cli 20.2.0 → 21.0.0

package/src/cdp-e2e-page.ts

@@ -1,136 +1,100 @@
-// One responsibility: `E2eBrowserPage` over a raw CDP connection — attach a tab, navigate,
-// evaluate, click, and set the browser's offline condition. Launching is `cdp-launch.ts` and the
+// One responsibility: one TAB over a raw CDP session — navigate, reload, evaluate, click, wait. The
+// session (`cdp-e2e-session.ts`) attaches it and owns everything browser-wide: the network
+// condition, the init scripts, the socket and request log. Launching is `cdp-launch.ts` and the
 // wire is `cdp-connection.ts`.
 //
 // FIVE methods, which is the whole reason this exists next to `@ultimat3/scraping` rather than
 // through it: `ScrapePage` is a full scraping surface whose intended implementation is
 // `puppeteer-core`, and an e2e driver needs none of it.
 
-import { assert } from '@ultimat3/core';
 import type { CdpConnection } from './cdp-connection';
-import { CdpCallFailedError } from './cdp-errors';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
 import type { E2eBrowserPage } from './e2e-page';
 
+/** What the page threw, when `Runtime.evaluate` answered with an exception rather than a value. */
+const thrownIn = (result: Record<string, unknown> | undefined): string | undefined => {
+  const thrown = result?.['exceptionDetails'];
+  if (typeof thrown !== 'object' || thrown === null) return undefined;
+  const text = (thrown as Record<string, unknown>)['text'];
+  return typeof text === 'string' ? text : 'the expression threw in the page';
+};
+
 /** `Runtime.evaluate`'s answer, unwrapped. Every field here is somebody else's JSON. */
 const evaluated = (result: Record<string, unknown> | undefined): unknown => {
-  const thrown = result?.['exceptionDetails'];
-  if (typeof thrown === 'object' && thrown !== null) {
-    const text = (thrown as Record<string, unknown>)['text'];
-    throw new CdpCallFailedError({
-      method: 'Runtime.evaluate',
-      detail: typeof text === 'string' ? text : 'the expression threw in the page',
-    });
+  const threw = thrownIn(result);
+  if (threw !== undefined) {
+    throw new CdpCallFailedError({ method: 'Runtime.evaluate', detail: threw });
   }
   const remote = result?.['result'];
   if (typeof remote !== 'object' || remote === null) return undefined;
   return (remote as Record<string, unknown>)['value'];
 };
 
-export interface CdpE2ePageOptions {
+/** One tab: the port the driver drives, plus what a multi-tab acceptance suite asks of one. */
+export interface E2eTab extends E2eBrowserPage {
+  readonly targetId: string;
+  /** Browser-wide, like the switch it models: every tab AND every worker goes with it. */
+  offline(enabled: boolean): Promise<void>;
+  /** Reload and wait for the load, at the url the tab already had. */
+  reload(): Promise<void>;
+  /** Poll `expression` in the page until it is truthy, or refuse naming `what`. */
+  waitFor(expression: string, what: string, timeoutMs?: number): Promise<void>;
+  /** The IndexedDB databases this tab's origin holds, by name, sorted. */
+  indexedDbNames(): Promise<readonly string[]>;
+  close(): Promise<void>;
+}
+
+export interface CdpE2eTabOptions {
   readonly connection: CdpConnection;
+  /** The attached tab's flattened session — every page call carries it. */
+  readonly sessionId: string;
+  readonly targetId: string;
   /**
    * How long a navigation's load event may take. Distinct from the connection's per-call deadline:
    * `Page.navigate` ANSWERS as soon as the navigation is committed, so the wait for the load event
    * is a second budget and is the one an app makes long.
    */
   readonly loadTimeoutMs: number;
+  /** The session's browser-wide switch, which `offline()` forwards to. */
+  readonly offline: (enabled: boolean) => Promise<void>;
 }
 
-/**
- * Attach a fresh tab and give back the page.
- *
- * `flatten: true` is not optional: without it every page call has to be wrapped in
- * `Target.sendMessageToTarget` and the answers arrive as nested strings. Flattened, a `sessionId`
- * on the frame is the whole of it, which is what keeps `cdp-connection.ts` a single map.
- */
-export async function cdpE2ePage(options: CdpE2ePageOptions): Promise<E2eBrowserPage> {
-  const send = options.connection.send.bind(options.connection);
-  const created = await send('Target.createTarget', { url: 'about:blank' });
-  const targetId = created.result?.['targetId'];
-  assert(
-    typeof targetId === 'string',
-    'the browser created a tab and answered no targetId',
-    'check the Chrome version supports Target.createTarget — every build since 60 does',
-  );
-  const attached = await send('Target.attachToTarget', { targetId, flatten: true });
-  const sessionId = attached.result?.['sessionId'];
-  assert(
-    typeof sessionId === 'string',
-    'the browser attached to the tab and answered no sessionId',
-    'check the Chrome version supports Target.attachToTarget with flatten: true — every build since 79 does',
-  );
-
-  await send('Page.enable', {}, sessionId);
-  await send('Runtime.enable', {}, sessionId);
-  // Enabled at attach rather than inside `offline()`, because `Network.emulateNetworkConditions`
-  // is silently ignored on a session whose Network domain was never enabled — the exact shape of
-  // an `offline()` that does nothing while the assertion after it reads as proof.
-  await send('Network.enable', {}, sessionId);
+const POLL_MS = 100;
 
-  // **A SERVICE WORKER FETCHES ON ITS OWN TARGET, and that is what `offline()` used to miss.**
-  // Measured against the framework's own emitted `sw.js`: with the page session offline, a
-  // `networkFirst` route the cache had never seen still answered from the network, because the
-  // worker's fetches never crossed the session the condition was set on. The assertion after
-  // `offline()` then read as proof of an offline fallback that had not run.
-  //
-  // So worker targets are AUTO-ATTACHED and carry the same condition. `waitForDebuggerOnStart:
-  // false`, or every worker starts paused and the page that registered it never becomes
-  // controlled.
-  const workers = new Set<string>();
-  let offline = false;
-  const applyOffline = async (target: string | undefined): Promise<void> => {
-    // `-1` is CDP's "no throttling" for both throughputs. Passing 0 would be a browser that can
-    // never transfer a byte, which is a different failure wearing the same name.
-    await send(
-      'Network.emulateNetworkConditions',
-      { offline, latency: 0, downloadThroughput: -1, uploadThroughput: -1 },
-      target,
-    );
-  };
-  options.connection.on('Target.attachedToTarget', (params) => {
-    const info = params['targetInfo'];
-    const kind =
-      typeof info === 'object' && info !== null
-        ? (info as Record<string, unknown>)['type']
-        : undefined;
-    const attachedTo = params['sessionId'];
-    if (typeof attachedTo !== 'string') return;
-    if (kind !== 'service_worker' && kind !== 'worker' && kind !== 'shared_worker') return;
-    workers.add(attachedTo);
-    // A worker that attaches while the page is offline inherits the condition — it did not exist
-    // when `offline(true)` ran, and a worker registered mid-test is the ordinary case for a PWA.
-    void (async () => {
-      try {
-        await send('Network.enable', {}, attachedTo);
-        if (offline) await applyOffline(attachedTo);
-      } catch {
-        // A worker that died between attaching and being configured is not this driver's problem;
-        // its session is gone and every later call on it would report the same thing.
-        workers.delete(attachedTo);
-      }
-    })();
-  });
-  await send(
-    'Target.setAutoAttach',
-    { autoAttach: true, waitForDebuggerOnStart: false, flatten: true },
-    sessionId,
-  );
+/** A tab over a session the caller has already attached and enabled (`cdp-e2e-session.ts`). */
+export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
+  const send = options.connection.send.bind(options.connection);
+  const { sessionId } = options;
 
   // `url()` is SYNCHRONOUS on the port, and CDP has no synchronous read — so the last committed
   // url is tracked here. Seeded with the tab's own starting url rather than '' so a `reload()`
   // before any `goto()` navigates somewhere real.
   let current = 'about:blank';
 
-  const evaluate = async (expression: string): Promise<unknown> => {
-    const answer = await send(
-      'Runtime.evaluate',
-      { expression, returnByValue: true, awaitPromise: true },
-      sessionId,
-    );
-    return evaluated(answer.result);
+  const evaluateRaw = (expression: string) =>
+    send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, sessionId);
+  const evaluate = async (expression: string): Promise<unknown> =>
+    evaluated((await evaluateRaw(expression)).result);
+
+  // A poll that THROWS is a poll that does not hold yet, not a refusal: a click that navigates
+  // leaves the next poll reading a document whose `<body>` is not parsed, and
+  // `document.body.textContent` throws there once and holds a poll later. The last throw is kept
+  // and named at the deadline, so an expression that can never evaluate still says why.
+  const waitFor = async (expression: string, what: string, timeoutMs = options.loadTimeoutMs) => {
+    // Only the PAGE's throw is swallowed: a connection that died still refuses at once.
+    let threw: string | undefined;
+    for (let waited = 0; waited < timeoutMs; waited += POLL_MS) {
+      const answer = (await evaluateRaw(`Boolean(${expression})`)).result;
+      threw = thrownIn(answer);
+      if (threw === undefined && evaluated(answer) === true) return;
+      await Bun.sleep(POLL_MS);
+    }
+    const last = threw === undefined ? '' : `, and its last poll threw: ${threw}`;
+    throw new CdpTimeoutError({ method: `waitFor(${what})${last}`, timeoutMs });
   };
 
-  return {
+  const tab: E2eTab = {
+    targetId: options.targetId,
     url: () => current,
     async goto(url: string): Promise<unknown> {
       // **The load EVENT is the signal, not the reply.** Chrome drops `Page.navigate`'s own reply
@@ -164,12 +128,14 @@ export async function cdpE2ePage(options: CdpE2ePageOptions): Promise<E2eBrowser
       // navigation, and `answered` can win the race on one too. So the document is asked directly:
       // a `readyState` that is already `complete` resolves at once, and the deadline resolves
       // rather than throwing — a slow page is the app's business, and the assertion after this is
-      // what should fail.
+      // what should fail. HALF the budget, because the budget is also the connection's per-call
+      // deadline: a page timer of the full budget raced that deadline and lost, reporting a page
+      // that never fired `load` as "Runtime.evaluate did not answer" instead.
       await evaluate(`(() => new Promise((resolve) => {
         if (document.readyState === 'complete') { resolve(true); return; }
         const done = () => resolve(true);
         addEventListener('load', done, { once: true });
-        setTimeout(done, ${String(options.loadTimeoutMs)});
+        setTimeout(done, ${String(Math.floor(options.loadTimeoutMs / 2))});
       }))()`);
       // The app may have redirected, so the committed url is re-read rather than assumed.
       const settled = await evaluate('location.href');
@@ -191,19 +157,24 @@ export async function cdpE2ePage(options: CdpE2ePageOptions): Promise<E2eBrowser
         });
       }
     },
-    async offline(enabled: boolean): Promise<void> {
-      offline = enabled;
-      // The page first, then every worker attached to it. Sequential rather than `Promise.all`:
-      // the set is small, and a worker session that has gone away must not take the page's own
-      // condition down with it.
-      await applyOffline(sessionId);
-      for (const worker of [...workers]) {
-        try {
-          await applyOffline(worker);
-        } catch {
-          workers.delete(worker);
-        }
-      }
+    offline: (enabled: boolean) => options.offline(enabled),
+    async reload(): Promise<void> {
+      const at = current;
+      // Reload is a navigation to the url the tab already has — the one wait the port proves.
+      await tab.goto(at);
+    },
+    waitFor,
+    async indexedDbNames(): Promise<readonly string[]> {
+      const names = await evaluate(
+        '(async () => (await indexedDB.databases()).map((db) => db.name ?? "").sort())()',
+      );
+      return Array.isArray(names)
+        ? names.filter((name): name is string => typeof name === 'string')
+        : [];
+    },
+    async close(): Promise<void> {
+      await send('Target.closeTarget', { targetId: options.targetId });
     },
   };
+  return tab;
 }

package/src/cdp-e2e-session.ts

@@ -0,0 +1,199 @@
+// One responsibility: the BROWSER half of the e2e driver — every target auto-attached at browser
+// level, so a second tab, a SharedWorker, a dedicated worker and a service worker are all watched
+// from their first byte; the offline switch, the init scripts, and the log of every WebSocket and
+// request the browser made. A tab is `cdp-e2e-page.ts`'s; this file decides what every tab shares.
+
+import type { CdpConnection } from './cdp-connection';
+import type { E2eTab } from './cdp-e2e-page';
+import { cdpE2eTab } from './cdp-e2e-page';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { offlineScripts } from './cdp-offline-script';
+
+export interface E2eSession {
+  /** A new tab in the same profile — same cookies, same origin storage, same SharedWorker. */
+  newTab(): Promise<E2eTab>;
+  /** Runs in every page before its own scripts, in tabs open now and tabs opened later. */
+  addInitScript(source: string): Promise<void>;
+  /** Cut or restore the network for every page AND every worker, including ones attached later. */
+  offline(enabled: boolean): Promise<void>;
+  setCookie(url: string, name: string, value: string): Promise<void>;
+  /** Every WebSocket url the browser opened, in any realm — page, dedicated, shared or service worker. */
+  sockets(): readonly string[];
+  /** Every request the browser sent, `METHOD url`, in order. */
+  requests(): readonly string[];
+}
+
+export interface CdpE2eSessionOptions {
+  readonly connection: CdpConnection;
+  /** The load budget every tab's `goto` waits on, and how long a new tab may take to attach. */
+  readonly loadTimeoutMs: number;
+}
+
+const POLL_MS = 50;
+
+const field = (from: unknown, key: string): string | undefined => {
+  const value =
+    typeof from === 'object' && from !== null ? (from as Record<string, unknown>)[key] : undefined;
+  return typeof value === 'string' ? value : undefined;
+};
+
+/**
+ * Start watching the browser. Targets are attached PAUSED (`waitForDebuggerOnStart: true`) and
+ * released only once their network domain is ENABLED, in dispatch order — a SharedWorker opens its
+ * socket at start-up, so a target configured any later than that is a socket nothing ever counted.
+ * Released with `Runtime.runIfWaitingForDebugger` whatever happens and without waiting for any
+ * answer, or a page that registered a worker never becomes controlled.
+ */
+export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eSession> {
+  const { connection } = options;
+  const send = connection.send.bind(connection);
+  const sessions = new Set<string>();
+  const pages = new Map<string, string>(); // targetId → sessionId
+  const scripts: string[] = [];
+  const sockets: string[] = [];
+  const requests: string[] = [];
+  let cut = false;
+
+  // `-1` is CDP's "no throttling" for both throughputs; 0 would be a browser that can never
+  // transfer a byte, which is a different failure wearing the same name.
+  const pageSessions = new Set<string>();
+  const onLineScripts = offlineScripts(send);
+  const condition = (session: string): Promise<unknown> =>
+    send(
+      'Network.emulateNetworkConditions',
+      { offline: cut, latency: 0, downloadThroughput: -1, uploadThroughput: -1 },
+      session,
+    );
+
+  connection.on('Network.webSocketCreated', (params) => {
+    sockets.push(field(params, 'url') ?? '');
+  });
+  connection.on('Network.requestWillBeSent', (params) => {
+    const request = params['request'];
+    requests.push(`${field(request, 'method') ?? '?'} ${field(request, 'url') ?? ''}`);
+  });
+  connection.on('Target.attachedToTarget', (params) => {
+    const session = field(params, 'sessionId');
+    if (session === undefined) return;
+    const info = params['targetInfo'];
+    const type = field(info, 'type');
+    sessions.add(session);
+    void (async () => {
+      // Every configuration call is SENT before the release and none is AWAITED before it. A
+      // session dispatches in order, so the target is still configured before its first byte runs —
+      // but a paused target may answer nothing until it is released: measured in a full `x verify`,
+      // a SharedWorker's `Network.enable` went unanswered for the whole 30 s deadline, the worker
+      // stayed paused that long, and the shared gate page stalled behind it. Awaiting the answers
+      // before releasing was a deadlock with a timeout for an exit.
+      //
+      // `Network.enable` first: `emulateNetworkConditions` is silently ignored on a session whose
+      // Network domain is off — an `offline()` that does nothing while the assertion after it
+      // reads as proof.
+      const configured: Promise<unknown>[] = [send('Network.enable', {}, session)];
+      if (cut) configured.push(condition(session));
+      if (type === 'page') {
+        configured.push(send('Page.enable', {}, session), send('Runtime.enable', {}, session));
+        pageSessions.add(session);
+        for (const source of scripts) {
+          configured.push(send('Page.addScriptToEvaluateOnNewDocument', { source }, session));
+        }
+        if (cut) configured.push(onLineScripts.add(session));
+        // The page's own workers attach under it UNPAUSED. Measured: paused here, the emitted
+        // service worker never took control of its page (`e2e/service-worker.e2e.test.ts` went
+        // red), because it is also attached at browser level. A dedicated worker's first request
+        // can therefore precede its Network.enable — the SharedWorker, which is what owns the
+        // socket, is a browser-level target and IS paused.
+        configured.push(
+          send(
+            'Target.setAutoAttach',
+            { autoAttach: true, waitForDebuggerOnStart: false, flatten: true },
+            session,
+          ),
+        );
+      }
+      const released = send('Runtime.runIfWaitingForDebugger', {}, session).catch(() => undefined);
+      // Settled, not `all`: a target that went away refuses EVERY call, and `all` would leave the
+      // refusals after the first as unhandled rejections. It has nothing left to watch.
+      const answers = await Promise.allSettled(configured);
+      if (answers.some((answer) => answer.status === 'rejected')) sessions.delete(session);
+      await released;
+      // Published only once RELEASED: a tab handed out while still paused would take its first
+      // `goto` into a page that is waiting for a debugger.
+      const targetId = field(info, 'targetId');
+      if (type === 'page' && targetId !== undefined && sessions.has(session)) {
+        pages.set(targetId, session);
+      }
+    })();
+  });
+  await send('Target.setDiscoverTargets', { discover: true });
+  await send('Target.setAutoAttach', {
+    autoAttach: true,
+    waitForDebuggerOnStart: true,
+    flatten: true,
+  });
+
+  const offline = async (enabled: boolean): Promise<void> => {
+    cut = enabled;
+    // Sequential, and a session that has gone away is dropped rather than taking the rest down.
+    for (const session of [...sessions]) {
+      await condition(session).catch(() => sessions.delete(session));
+    }
+    // And `navigator.onLine` from a new document's first script (`cdp-offline-script.ts`) — the
+    // network condition alone reaches a reloaded page only after its scripts have run.
+    for (const session of [...pageSessions]) {
+      const toggled = enabled ? onLineScripts.add(session) : onLineScripts.remove(session);
+      await toggled.catch(() => pageSessions.delete(session));
+    }
+  };
+
+  const attached = async (targetId: string): Promise<string> => {
+    for (let waited = 0; waited < options.loadTimeoutMs; waited += POLL_MS) {
+      const session = pages.get(targetId);
+      if (session !== undefined) return session;
+      await Bun.sleep(POLL_MS);
+    }
+    throw new CdpTimeoutError({
+      method: `Target.attachedToTarget for tab ${targetId}`,
+      timeoutMs: options.loadTimeoutMs,
+    });
+  };
+
+  return {
+    async newTab(): Promise<E2eTab> {
+      const created = await send('Target.createTarget', { url: 'about:blank' });
+      const targetId = field(created.result, 'targetId');
+      if (targetId === undefined) {
+        throw new CdpCallFailedError({
+          method: 'Target.createTarget',
+          detail: 'the browser created a tab and answered no targetId',
+        });
+      }
+      const sessionId = await attached(targetId);
+      return cdpE2eTab({
+        connection,
+        sessionId,
+        targetId,
+        loadTimeoutMs: options.loadTimeoutMs,
+        offline,
+      });
+    },
+    async addInitScript(source: string): Promise<void> {
+      scripts.push(source);
+      // A closed tab refuses every call; it is dropped rather than taking the open tabs down with
+      // it, exactly as `offline()` drops one.
+      for (const [targetId, session] of [...pages]) {
+        await send('Page.addScriptToEvaluateOnNewDocument', { source }, session).catch(() => {
+          pages.delete(targetId);
+          sessions.delete(session);
+          pageSessions.delete(session);
+        });
+      }
+    },
+    offline,
+    async setCookie(url: string, name: string, value: string): Promise<void> {
+      await send('Storage.setCookies', { cookies: [{ name, value, url, path: '/' }] });
+    },
+    sockets: () => [...sockets],
+    requests: () => [...requests],
+  };
+}

package/src/cdp-launch.ts

@@ -8,7 +8,10 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 // why: Bun exposes no path-join primitive.
 import { join } from 'node:path';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnectOver } from './cdp-connection';
 import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
 
 /**
  * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
@@ -52,17 +55,25 @@ export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disa
 /**
  * The flags, and every one of them earns its line.
  *
- * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-port=0`
- * asks the OS for a free port, so two suites on one machine never collide — the port is read back
- * off stderr, which is the only place Chrome states the one it took. A throwaway `--user-data-dir`
- * because a run sharing a profile with a real browser inherits its cookies and locks its files.
+ * `--headless=new` is Chrome's own headless rather than the retired shim. `--remote-debugging-pipe`
+ * is the wire (`cdp-pipe.ts` says why it is not the WebSocket): no port, so two suites on one
+ * machine can never collide, and nothing but this process can drive the browser. A throwaway
+ * `--user-data-dir` because a run sharing a profile with a real browser inherits its cookies and
+ * locks its files.
  */
-const flags = (profileDir: string): readonly string[] => [
+export const chromeLaunchFlags = (profileDir: string): readonly string[] => [
   '--headless=new',
-  '--remote-debugging-port=0',
+  '--remote-debugging-pipe',
   `--user-data-dir=${profileDir}`,
   ...CONTAINER_CHROME_ARGS,
   '--disable-gpu',
+  // The cookie store's encryption key comes from the OS keyring, asked over D-Bus on the first
+  // cookie access — which is the first navigation. With no keyring answering, Chrome waits out the
+  // D-Bus timeout: measured 7-25 s on the first `Page.navigate` of every launch, against a 30 s CDP
+  // deadline, which is the intermittent `X_CDP_TIMEOUT` of a full e2e run. A throwaway profile has
+  // no secret worth a keyring. `puppeteer-core` passes both by default, so `x shot` never had this.
+  '--password-store=basic',
+  '--use-mock-keychain',
   // Nothing here should reach the network on its own account, and a first-run bubble or an update
   // check is a page load the test did not ask for.
   '--no-first-run',
@@ -71,61 +82,104 @@ const flags = (profileDir: string): readonly string[] => [
   'about:blank',
 ];
 
-const ENDPOINT = /DevTools listening on (ws:\/\/\S+)/;
-
 export interface LaunchedBrowser {
-  readonly endpoint: string;
-  /** Idempotent: killing a dead process and deleting a gone directory are both no-ops. */
+  /** The browser's own CDP connection, over its debugging pipe. Already answering. */
+  readonly connection: CdpConnection;
+  /** Idempotent: closes the connection, kills the process, deletes the profile. */
   close(): void;
 }
 
 export interface LaunchOptions {
   readonly executable: string;
-  /** How long Chrome has to announce its endpoint before this gives up and kills it. */
+  /** How long Chrome has to answer its first call, and every call's deadline after that. */
   readonly timeoutMs: number;
 }
 
+const STDERR_TAIL_CHARS = 4_000;
+
+/**
+ * Read stderr to its end for the life of the process, keeping only a bounded tail. A pipe nobody
+ * reads fills, and Chrome's next stderr write then blocks the thread making it — a browser that
+ * stops answering mid-run for a reason no log shows. The tail is the launch-failure diagnostics:
+ * a missing library, a sandbox refusal and a bad flag are all named there and nowhere else.
+ */
+function stderrTail(stream: ReadableStream<Uint8Array>): {
+  readonly text: () => string;
+  /** Settles once the stream has ended — every byte the process wrote has been read. */
+  readonly drained: Promise<void>;
+} {
+  let text = '';
+  const drained = (async () => {
+    const decoder = new TextDecoder();
+    for await (const chunk of stream) {
+      text = (text + decoder.decode(chunk, { stream: true })).slice(-STDERR_TAIL_CHARS);
+    }
+  })().catch(() => undefined);
+  return { text: () => text, drained };
+}
+
 /**
- * Chrome announces `DevTools listening on ws://…` on **stderr**, once, before it is usable. Reading
- * it there rather than polling `/json/version` is what makes `--remote-debugging-port=0` safe: with
- * a random port there is no URL to poll until Chrome has said which one it took.
+ * How long a browser that failed its first call gets to finish dying, and its stderr to finish
+ * draining, before the tail is read. The pipe ending and the stderr reader reaching the last line
+ * are two unordered events; read at the first, the reason a browser died was reported as "printed
+ * nothing". Bounded, because a WEDGED browser neither exits nor closes stderr.
+ */
+const FAILURE_DRAIN_MS = 1_000;
+
+const within = (ms: number, work: Promise<unknown>): Promise<unknown> =>
+  Promise.race([work, Bun.sleep(ms)]);
+
+/**
+ * Start Chrome on a throwaway profile and answer once it has answered one CDP call. With a pipe
+ * there is no "DevTools listening" line to wait for — the first reply IS the readiness signal, and
+ * a browser that dies or stays silent before it is `X_CDP_LAUNCH_FAILED` carrying its own stderr.
  */
 export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
   const profileDir = mkdtempSync(join(tmpdir(), 'x-e2e-chrome-'));
-  const child = Bun.spawn([options.executable, ...flags(profileDir)], {
-    stderr: 'pipe',
-    stdout: 'ignore',
+  const child = Bun.spawn([options.executable, ...chromeLaunchFlags(profileDir)], {
+    // Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies and events.
+    stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'],
   });
+  const tail = stderrTail(child.stderr as ReadableStream<Uint8Array>);
+  const [, , , toBrowser, fromBrowser] = child.stdio as unknown as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  const connection = cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    options.timeoutMs,
+  );
+  let closed = false;
   const close = (): void => {
+    if (closed) return;
+    closed = true;
+    connection.close();
     child.kill();
     rmSync(profileDir, { recursive: true, force: true });
   };
-
-  const reader = (child.stderr as ReadableStream<Uint8Array>).getReader();
-  const decoder = new TextDecoder();
-  let seen = '';
-  const deadline = Bun.nanoseconds() + options.timeoutMs * 1_000_000;
   try {
-    while (Bun.nanoseconds() < deadline) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      seen += decoder.decode(value, { stream: true });
-      const found = ENDPOINT.exec(seen);
-      if (found?.[1] !== undefined) return { endpoint: found[1], close };
-    }
-  } finally {
-    reader.releaseLock();
+    await connection.send('Browser.getVersion');
+    return { connection, close };
+  } catch {
+    await within(FAILURE_DRAIN_MS, child.exited);
+    close();
+    await within(FAILURE_DRAIN_MS, tail.drained);
+    const seen = tail.text().trim();
+    throw new CdpLaunchFailedError({
+      executable: options.executable,
+      detail:
+        seen === ''
+          ? 'it answered no DevTools call and printed nothing before the deadline'
+          : seen.split('\n').slice(-3).join(' | '),
+    });
   }
-  close();
-  // Chrome's own stderr is the actionable half — a missing library, a sandbox refusal, a bad flag
-  // are all named there — so it is reported rather than "the launch failed".
-  throw new CdpLaunchFailedError({
-    executable: options.executable,
-    detail:
-      seen.trim() === ''
-        ? 'it printed nothing before the deadline'
-        : seen.trim().split('\n').slice(-3).join(' | '),
-  });
 }
 
 /** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */