@ultimat3/scraping 30.9.0 → 31.0.0

package/src/cdp-launch-wire.ts

@@ -0,0 +1,171 @@
+// One responsibility: the WIRE a launched Chrome is driven over, per platform — its debugging pipe
+// (fds 3 and 4) where the parent can hold those fds, else a loopback port the browser picks and
+// announces in its profile's `DevToolsActivePort`. Spawning and reaping are `cdp-launch-attempt.ts`.
+
+// why: Bun exposes no path-join primitive; the announcement file lives in the profile directory.
+import { join } from 'node:path';
+import { renderThrowable, stringField } from '@ultimat3/core';
+import type { CdpConnection } from './cdp-connection';
+import { cdpConnect, cdpConnectOver } from './cdp-connection';
+import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
+import { pipeTransport } from './cdp-pipe';
+
+/**
+ * `pipe` everywhere Bun hands the parent the child's extra fds as descriptors, which is POSIX: no
+ * port, so two suites on one machine never collide and nothing else can drive the browser.
+ * `port` on Windows, where those fds are not descriptors `Bun.file` can open: Chrome binds a
+ * loopback port of its own choosing (`=0`, so never a collision either) and writes it down.
+ */
+export type CdpWire = 'pipe' | 'port';
+
+export const defaultWire = (platform: string): CdpWire => (platform === 'win32' ? 'port' : 'pipe');
+
+/** The one flag that differs between the two wires. */
+export const wireFlag = (wire: CdpWire): string =>
+  wire === 'pipe' ? '--remote-debugging-pipe' : '--remote-debugging-port=0';
+
+/** Chrome's fd 3 is where it READS commands and fd 4 where it WRITES replies — pipe wire only. */
+const PIPE_STDIO = ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] as const;
+const PORT_STDIO = ['ignore', 'ignore', 'pipe'] as const;
+export const wireStdio = (wire: CdpWire): typeof PIPE_STDIO | typeof PORT_STDIO =>
+  wire === 'pipe' ? PIPE_STDIO : PORT_STDIO;
+
+/** The pipe wire over a spawned child's fds 3 and 4. Answers nothing until the first `send`. */
+export function pipeConnection(stdio: unknown, timeoutMs: number): CdpConnection {
+  const [, , , toBrowser, fromBrowser] = stdio as readonly number[];
+  const sink = Bun.file(toBrowser ?? -1).writer();
+  return cdpConnectOver(
+    pipeTransport({
+      write: (bytes) => {
+        sink.write(bytes);
+        void sink.flush();
+      },
+      read: Bun.file(fromBrowser ?? -1).stream(),
+      end: () => {
+        void Promise.resolve(sink.end()).catch(() => undefined);
+      },
+    }),
+    timeoutMs,
+  );
+}
+
+export const DEVTOOLS_ACTIVE_PORT = 'DevToolsActivePort';
+
+/**
+ * `<port>\n/devtools/browser/<id>\n` → the browser's WebSocket url, or `undefined` while the file is
+ * still half-written. Loopback by address, never `localhost`, which may resolve to `::1` first
+ * while Chrome listens on IPv4.
+ */
+export function devToolsEndpoint(text: string): string | undefined {
+  const [port, path] = text.split(/\r?\n/);
+  if (port === undefined || !/^\d{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65_535) {
+    return undefined;
+  }
+  if (path === undefined || !/^\/devtools\/browser\/[\w-]+$/.test(path)) return undefined;
+  return `ws://127.0.0.1:${port}${path}`;
+}
+
+const ANNOUNCE_POLL_MS = 25;
+
+/**
+ * Dial, inside what is left of the LAUNCH deadline — `cdpConnect`'s own deadline is the per-call one
+ * the connection keeps afterwards, so it cannot also be the launch's. A dial that loses the race
+ * and connects later is closed, never left holding a socket nobody reads.
+ */
+async function dialWithin(
+  endpoint: string,
+  leftMs: number,
+  timeoutMs: number,
+): Promise<CdpConnection> {
+  const dialing = cdpConnect({ endpoint, timeoutMs });
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const late = new Promise<never>((_, reject) => {
+    timer = setTimeout(
+      () => reject(new CdpTimeoutError({ method: 'connect', timeoutMs: leftMs })),
+      leftMs,
+    );
+  });
+  try {
+    return await Promise.race([dialing, late]);
+  } catch (error) {
+    void dialing.then((connection) => connection.close()).catch(() => undefined);
+    // A timeout stays one — the launcher reads it as the deadline. Any other refusal names the
+    // endpoint it was for: the browser announced it, so the dial is the step that failed.
+    if (error instanceof CdpTimeoutError) throw error;
+    throw new CdpCallFailedError({
+      method: `connect ${endpoint}`,
+      detail: renderThrowable(error),
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export interface PortConnectionInput {
+  readonly profileDir: string;
+  /** True once the browser process has exited — it will never write the file then. */
+  readonly exited: () => boolean;
+  /** How long the browser has to announce itself AND accept the connection, from now. */
+  readonly deadlineMs: number;
+  /** Every call's deadline once connected. */
+  readonly timeoutMs: number;
+  /**
+   * How the announcement is read — `Bun.file(path).text()` unless a test hands a reader that
+   * refuses the way Windows does, which no Linux file system can be made to.
+   */
+  readonly readText?: ((path: string) => Promise<string>) | undefined;
+}
+
+/**
+ * The read errors that mean "not announced YET", never "the launch failed": `ENOENT`, the file
+ * gone between the existence check and the read, and `EBUSY`, which is how Bun reports a Windows
+ * sharing violation — Chrome writes `DevToolsActivePort` in place and holds it open without read
+ * sharing while it does. Seen on windows-latest (PR #668): "DevTools listening" on stderr, the file
+ * present, the read refused, and the launch reported `closed` with the browser alive.
+ */
+const NOT_YET = new Set(['ENOENT', 'EBUSY']);
+
+const readFile = (path: string): Promise<string> => Bun.file(path).text();
+
+/** The announcement's text, or `undefined` while its writer still holds it. */
+async function readAnnouncement(
+  path: string,
+  read: (path: string) => Promise<string>,
+): Promise<string | undefined> {
+  try {
+    return await read(path);
+  } catch (error) {
+    if (NOT_YET.has(stringField(error, 'code') ?? '')) return undefined;
+    throw error;
+  }
+}
+
+/**
+ * The port wire: wait for the profile's `DevToolsActivePort`, then dial it. A browser that exits
+ * first is a CLOSED launch and one still silent at the deadline a TIMED-OUT one — the same two
+ * answers the pipe gives, so the launcher's failure report reads alike on either wire.
+ */
+export async function portConnection(input: PortConnectionInput): Promise<CdpConnection> {
+  const path = join(input.profileDir, DEVTOOLS_ACTIVE_PORT);
+  const began = performance.now();
+  for (;;) {
+    // A FRESH handle per look: a `BunFile` that once answered "absent" keeps answering it (measured
+    // on Bun 1.4.2 — `exists()` false and `text()` empty after the file was written).
+    const text = (await Bun.file(path).exists())
+      ? await readAnnouncement(path, input.readText ?? readFile)
+      : undefined;
+    const endpoint = text === undefined ? undefined : devToolsEndpoint(text);
+    const left = input.deadlineMs - (performance.now() - began);
+    if (endpoint !== undefined) return dialWithin(endpoint, Math.max(1, left), input.timeoutMs);
+    if (input.exited()) {
+      throw new CdpCallFailedError({
+        method: 'the launch',
+        detail: `the browser exited before it wrote ${DEVTOOLS_ACTIVE_PORT}`,
+      });
+    }
+    if (left <= 0) {
+      throw new CdpTimeoutError({ method: DEVTOOLS_ACTIVE_PORT, timeoutMs: input.deadlineMs });
+    }
+    await Bun.sleep(Math.min(ANNOUNCE_POLL_MS, left));
+  }
+}

package/src/cdp-launch.ts

@@ -0,0 +1,216 @@
+// One responsibility: WHICH Chrome, with which flags, and how many starts it gets — the candidate
+// list, the launch deadline and the one relaunch. One start of the process is
+// `cdp-launch-attempt.ts`; the connection is `cdp-connection.ts`. Its callers: `pdf()` here, and
+// `@ultimat3/testing`'s e2e driver and `x shot` through `@ultimat3/scraping/cdp`.
+
+import { finiteCount } from '@ultimat3/core';
+import type { CdpLaunchAttempt } from './cdp-errors';
+import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
+import type { LaunchedBrowser } from './cdp-launch-attempt';
+import { LAUNCH_REAP_MS, launchAttempt } from './cdp-launch-attempt';
+import { chromeCandidates } from './cdp-launch-candidates';
+import { startsChrome } from './cdp-launch-probe';
+import type { CdpWire } from './cdp-launch-wire';
+import { defaultWire, wireFlag } from './cdp-launch-wire';
+
+export type { LaunchedBrowser } from './cdp-launch-attempt';
+export { CLOSE_GRACE_MS, LAUNCH_REAP_MS } from './cdp-launch-attempt';
+export { chromeCandidates } from './cdp-launch-candidates';
+export type { CdpWire } from './cdp-launch-wire';
+export { defaultWire } from './cdp-launch-wire';
+
+/**
+ * Where a Chrome is, in the order worth trying. `CHROME_PATH` first because it is the operator's
+ * answer and the only one that can be right on a machine none of the rest describes; after it, the
+ * install locations of THIS platform (`cdp-launch-candidates.ts`) — on Linux the `/usr/bin` names
+ * GitHub-hosted `ubuntu-latest` ships, which is what lets the browser-backed suite run in CI with
+ * **no download step and no new dependency**; on Windows Chrome and Edge; on macOS the app bundles.
+ */
+export const CHROME_PATH_ENV = 'CHROME_PATH';
+export const CHROME_CANDIDATES: readonly string[] = chromeCandidates(process.platform, process.env);
+
+/**
+ * The first candidate that is a browser this machine can start, or `undefined`. An absent browser is
+ * a SKIP, never a failure — and so is one that is installed but cannot start (`startsChrome`,
+ * `cdp-launch-probe.ts`; on `win32` existence alone, since `chrome.exe --version` never exits).
+ * `platform` is a parameter so the Windows and macOS lists are asserted on a Linux runner too.
+ *
+ * `CHROME_PATH` is answered as given, and never probed: it is the operator's answer, the only one
+ * that can be right on a machine none of the candidates describes, and it is how a wrapper or a
+ * non-standard build is named at all.
+ */
+export async function findChrome(
+  env: Readonly<Record<string, string | undefined>>,
+  platform: string = process.platform,
+): Promise<string | undefined> {
+  const declared = env[CHROME_PATH_ENV];
+  if (declared !== undefined && declared !== '') {
+    return (await Bun.file(declared).exists()) ? declared : undefined;
+  }
+  for (const candidate of chromeCandidates(platform, env)) {
+    if (!(await Bun.file(candidate).exists())) continue;
+    if (await startsChrome(candidate, platform)) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * The two flags a CONTAINER needs, regardless of which process launches Chrome: the sandbox needs
+ * privileges CI (and an Ubuntu 23.10+ host with AppArmor's unprivileged-user-namespace restriction
+ * — Chrome exits "No usable sandbox" there with neither) does not grant, and `/dev/shm` is 64 MB in
+ * a default container, which crashes the renderer on any real page.
+ *
+ * Exported, and in `chromeLaunchFlags` below, so every launcher carries the SAME two. `x shot` had
+ * neither while it launched through `puppeteer-core`, so a box where `x verify`'s e2e gate ran green
+ * could not run `x shot` at all; since 22.0.0 it launches through `launchChrome` here.
+ */
+export const CONTAINER_CHROME_ARGS: readonly string[] = ['--no-sandbox', '--disable-dev-shm-usage'];
+
+/**
+ * The flags, and every one of them earns its line.
+ *
+ * `--headless=new` is Chrome's own headless rather than the retired shim. The wire flag is
+ * `--remote-debugging-pipe` wherever the pipe can be held (`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 — and `--remote-debugging-port=0` on Windows (`cdp-launch-wire.ts`). A
+ * throwaway `--user-data-dir` because a run sharing a profile with a real browser inherits its
+ * cookies and locks its files.
+ */
+export const chromeLaunchFlags = (
+  profileDir: string,
+  wire: CdpWire = defaultWire(process.platform),
+  sandbox = false,
+): readonly string[] => [
+  '--headless=new',
+  wireFlag(wire),
+  `--user-data-dir=${profileDir}`,
+  // `sandbox: true` drops `--no-sandbox` alone: `/dev/shm` is as small in a production container.
+  ...(sandbox
+    ? CONTAINER_CHROME_ARGS.filter((arg) => arg !== '--no-sandbox')
+    : 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. `x shot` launches through here too, so it has both.
+  '--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',
+  '--no-default-browser-check',
+  '--disable-extensions',
+  // `--disable-extensions` leaves Google Chrome's COMPONENT extensions running, each with a page of
+  // its own: the hangouts one (nkeimhogjdpnpccoofpliimaahmaaome) loads `thunk.js` while the browser
+  // starts, and `x shot`'s browser-wide interception paused it and logged it as an off-list request
+  // of the page under test (CI, 2026-10-09). A test browser runs no page it was not handed.
+  '--disable-component-extensions-with-background-pages',
+  'about:blank',
+];
+
+/**
+ * How long a COLD start may take before the browser is given up on. Its own number, never the
+ * per-call deadline: measured 2026-10-02 over `scaffold-smoke` on free `ubuntu-latest` runners, the
+ * first launch of a job cost 5-19 s more than a warm one in 11 green jobs, and the one red job was
+ * still printing start-up lines when a 30 s deadline killed it. Twice that, and finite: a browser
+ * that exits says so at once (its pipe closes), so only one alive and silent waits this long.
+ */
+export const LAUNCH_TIMEOUT_MS = 60_000;
+
+/**
+ * Starts per launch: the first, and ONE more on a fresh profile after the first was reaped. A
+ * process start is the one step here whose failure can belong to the machine rather than the
+ * binary — and the second start of a cold binary is a warm one. Never a loop: two starts that both
+ * went unanswered are `X_CDP_LAUNCH_FAILED` carrying both.
+ */
+export const LAUNCH_ATTEMPTS = 2;
+
+/**
+ * The longest `launchChrome` is DESIGNED to take, for any `timeoutMs` up to `LAUNCH_TIMEOUT_MS`:
+ * every start given its whole deadline, each failed one its bounded reap. A hook that wraps a launch
+ * and gives it less is killed by Bun before the relaunch, and the `X_CDP_LAUNCH_FAILED` that would
+ * have named the slow step never surfaces — the shape of four CI flakes (plan 101, F1).
+ */
+export const LAUNCH_BUDGET_MS = LAUNCH_ATTEMPTS * (LAUNCH_TIMEOUT_MS + LAUNCH_REAP_MS);
+
+/**
+ * The longest a launched browser lives when its caller names no bound: one hour from its spawn, then
+ * `SIGKILL` from the OS. Never the way a browser ends — `close()` is — but the way one ends whose
+ * caller vanished. An hour, because an e2e lease holds ONE browser for a whole run; a caller with a
+ * shorter job (`pdf()`'s one render) passes its own `lifetimeMs`.
+ */
+export const BROWSER_LIFETIME_MS = 60 * 60_000;
+
+export interface LaunchOptions {
+  readonly executable: string;
+  /** Every CDP call's deadline once the browser is up. */
+  readonly timeoutMs: number;
+  /** The first answer's deadline, per start. Defaults to the larger of `timeoutMs` and `LAUNCH_TIMEOUT_MS`. */
+  readonly launchTimeoutMs?: number | undefined;
+  /** The wire. Defaults to this platform's (`defaultWire`): the pipe, and on Windows the port. */
+  readonly wire?: CdpWire | undefined;
+  /** From each start, the longest the process may live before the OS kills it. `BROWSER_LIFETIME_MS`. */
+  readonly lifetimeMs?: number | undefined;
+  /**
+   * Keep Chrome's sandbox — no `--no-sandbox`. Off by default, for the e2e driver and `x shot` on CI
+   * runners that cannot grant it; ON for `pdf()`, which renders user content in production
+   * (`pdfLaunchOptions`, `pdf-render.ts`, says why).
+   */
+  readonly sandbox?: boolean | undefined;
+}
+
+/** What `launchFoundChrome` passes through to `launchChrome`, beside the deadline. */
+export type FoundChromeOptions = Pick<LaunchOptions, 'lifetimeMs' | 'sandbox'>;
+
+/**
+ * Start Chrome on a throwaway profile and answer once it has answered one CDP call. A browser that
+ * dies or stays silent is started once more; twice is `X_CDP_LAUNCH_FAILED` with each start's own
+ * stderr and whether it exited or was killed at the deadline.
+ */
+export async function launchChrome(options: LaunchOptions): Promise<LaunchedBrowser> {
+  // Screened: `setTimeout(fn, NaN)` fires in 1 ms, which reports a healthy browser as silent.
+  const launchTimeoutMs = finiteCount(
+    'launchChrome',
+    'launchTimeoutMs',
+    options.launchTimeoutMs ?? Math.max(options.timeoutMs, LAUNCH_TIMEOUT_MS),
+    1,
+  );
+  const lifetimeMs = finiteCount(
+    'launchChrome',
+    'lifetimeMs',
+    options.lifetimeMs ?? BROWSER_LIFETIME_MS,
+    1,
+  );
+  const wire = options.wire ?? defaultWire(process.platform);
+  const failures: CdpLaunchAttempt[] = [];
+  while (failures.length < LAUNCH_ATTEMPTS) {
+    const started = await launchAttempt({
+      executable: options.executable,
+      flags: (profileDir) => chromeLaunchFlags(profileDir, wire, options.sandbox === true),
+      wire,
+      timeoutMs: options.timeoutMs,
+      launchTimeoutMs,
+      lifetimeMs,
+    });
+    if (started.ok) return started.browser;
+    failures.push(started.failure);
+    // A process that outlived SIGKILL's grace still holds the machine; a second beside it is the
+    // load that made the first one late.
+    if (!started.reaped) break;
+  }
+  throw new CdpLaunchFailedError({ executable: options.executable, attempts: failures });
+}
+
+/** `findChrome` then `launchChrome`. Refuses by name when there is no browser to drive. */
+export async function launchFoundChrome(
+  env: Readonly<Record<string, string | undefined>>,
+  timeoutMs: number,
+  options: FoundChromeOptions = {},
+): Promise<LaunchedBrowser> {
+  const executable = await findChrome(env);
+  if (executable === undefined) {
+    throw new CdpBrowserMissingError({ tried: chromeCandidates(process.platform, env) });
+  }
+  return launchChrome({ executable, timeoutMs, ...options });
+}

package/src/cdp-pipe.ts

@@ -0,0 +1,77 @@
+// One responsibility: CDP over the pipe `--remote-debugging-pipe` opens — Chrome reads commands on
+// its fd 3 and writes replies and events on its fd 4, each message one JSON text ended by a NUL
+// byte. This is the e2e driver's wire; the WebSocket in `cdp-connection.ts` is for a remote browser.
+//
+// Why a pipe rather than the WebSocket Chrome also offers: Bun 1.4.0's WebSocket client handed
+// `onmessage` text spliced from several frames under the dummy's `offline-feed` load — 64
+// unparseable frames in one run, one of them a `Runtime.evaluate` reply that then waited out its
+// 30 s deadline. A frame nobody can parse has no `id`, so no layer above can even tell which call
+// it lost. A pipe is bytes and a delimiter, read here, and nothing in between.
+
+import type { CdpTransport } from './cdp-connection';
+
+/** The two ends a transport needs: a sink for whole messages, and the byte stream Chrome writes. */
+export interface PipeEnds {
+  /** Write these bytes to Chrome's fd 3, in order. */
+  readonly write: (bytes: Uint8Array) => void;
+  /** Chrome's fd 4. */
+  readonly read: ReadableStream<Uint8Array>;
+  /** Release the write end — Chrome treats its fd 3 closing as the client going away. */
+  readonly end: () => void;
+}
+
+const NUL = 0;
+
+/** Concatenate two byte arrays; the reader only ever holds the unterminated tail. */
+const join = (a: Uint8Array, b: Uint8Array): Uint8Array => {
+  if (a.length === 0) return b;
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a);
+  out.set(b, a.length);
+  return out;
+};
+
+export function pipeTransport(ends: PipeEnds): CdpTransport {
+  const encoder = new TextEncoder();
+  let closed = false;
+  const reader = ends.read.getReader();
+  return {
+    send(text: string): void {
+      if (closed) return;
+      const body = encoder.encode(text);
+      const framed = new Uint8Array(body.length + 1);
+      framed.set(body);
+      framed[body.length] = NUL;
+      ends.write(framed);
+    },
+    close(): void {
+      if (closed) return;
+      closed = true;
+      ends.end();
+      void reader.cancel().catch(() => undefined);
+    },
+    listen(handlers): void {
+      void (async () => {
+        // Split on BYTES, decoded per message: a multi-byte character may straddle two reads, and
+        // decoding each read on its own would corrupt it — the failure this file exists to end.
+        const decoder = new TextDecoder();
+        let tail: Uint8Array = new Uint8Array(0);
+        try {
+          for (;;) {
+            const { value, done } = await reader.read();
+            if (done) break;
+            tail = join(tail, value);
+            for (let at = tail.indexOf(NUL); at !== -1; at = tail.indexOf(NUL)) {
+              handlers.message(decoder.decode(tail.subarray(0, at)));
+              tail = tail.subarray(at + 1);
+            }
+          }
+        } catch {
+          // A read that fails is a pipe that is gone — reported as the close it is, below.
+        }
+        closed = true;
+        handlers.closed('the browser closed the CDP pipe');
+      })();
+    },
+  };
+}

package/src/cdp-wire-watch.ts

@@ -0,0 +1,113 @@
+// One responsibility: remember what the wire did, so a call that is never answered can say WHY —
+// its target went away, frames arrived that nothing could parse, or the target simply stayed
+// silent. The connection (`cdp-connection.ts`) feeds every frame in; `CdpTimeoutError` reads it out.
+
+import type { CdpTargetGone, CdpTimeoutObservation } from './cdp-errors';
+
+/** How many of the latest frames a timeout quotes. Bounded: a busy page sends thousands. */
+export const LAST_FRAMES = 8;
+
+/** Where the wire stood when a call was sent — what "since the call" is measured from. */
+export interface WireMark {
+  readonly arrived: number;
+  readonly dropped: number;
+  readonly navigations: number;
+}
+
+export interface WireWatch {
+  /** One frame that parsed: a reply or an event. */
+  frame(frame: Record<string, unknown>): void;
+  /** One frame nothing could parse. It has no `id`, so no call can be failed with it — only counted. */
+  drop(): void;
+  mark(sessionId: string | undefined): WireMark;
+  /** What happened between `mark` and now, for the call sent on `sessionId`. */
+  observe(mark: WireMark, sessionId: string | undefined, open: boolean): CdpTimeoutObservation;
+}
+
+const text = (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;
+};
+
+export function wireWatch(): WireWatch {
+  let arrived = 0;
+  let dropped = 0;
+  const last: string[] = [];
+  const targetOf = new Map<string, string>(); // sessionId → targetId
+  const gone = new Map<string, CdpTargetGone>(); // sessionId → how it went
+  const navigations = new Map<string, number>(); // sessionId → main-frame navigations
+
+  const goneTarget = (targetId: string | undefined, how: CdpTargetGone): void => {
+    for (const [session, target] of targetOf) if (target === targetId) gone.set(session, how);
+  };
+
+  /** The few events that say a session can no longer answer, or that its page was replaced. */
+  const track = (method: string, session: string | undefined, params: unknown): void => {
+    if (method === 'Target.attachedToTarget') {
+      const attached = text(params, 'sessionId');
+      const target = text(
+        (params as Record<string, unknown> | undefined)?.['targetInfo'],
+        'targetId',
+      );
+      if (attached !== undefined && target !== undefined) targetOf.set(attached, target);
+    } else if (method === 'Target.detachedFromTarget') {
+      const detached = text(params, 'sessionId');
+      if (detached !== undefined) gone.set(detached, 'detached');
+    } else if (method === 'Target.targetDestroyed') {
+      goneTarget(text(params, 'targetId'), 'destroyed');
+    } else if (method === 'Target.targetCrashed') {
+      goneTarget(text(params, 'targetId'), 'crashed');
+    } else if (method === 'Inspector.targetCrashed' && session !== undefined) {
+      gone.set(session, 'crashed');
+    } else if (method === 'Page.frameNavigated' && session !== undefined) {
+      const frame = (params as Record<string, unknown> | undefined)?.['frame'];
+      // A frame with a parent is an iframe: the document the call was sent to is still there.
+      if (text(frame, 'parentId') === undefined) {
+        navigations.set(session, (navigations.get(session) ?? 0) + 1);
+      }
+    }
+  };
+
+  const note = (label: string): void => {
+    last.push(label);
+    if (last.length > LAST_FRAMES) last.shift();
+  };
+
+  return {
+    frame(frame): void {
+      arrived += 1;
+      const session = text(frame, 'sessionId');
+      const id = frame['id'];
+      const method = text(frame, 'method');
+      if (typeof id === 'number') note(`reply ${String(id)}`);
+      else if (method === undefined) note('a frame with neither an id nor a method');
+      else {
+        note(session === undefined ? method : `${method} @${session}`);
+        track(method, session, frame['params']);
+      }
+    },
+    drop(): void {
+      dropped += 1;
+    },
+    mark: (sessionId) => ({
+      arrived,
+      dropped,
+      navigations: sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0),
+    }),
+    observe(mark, sessionId, open): CdpTimeoutObservation {
+      const since = arrived - mark.arrived;
+      return {
+        sessionId: sessionId ?? null,
+        framesArrived: since,
+        // Only frames that arrived AFTER the call: an older one says nothing about its reply.
+        lastFrames: since === 0 ? [] : last.slice(-Math.min(since, LAST_FRAMES)),
+        framesDropped: dropped - mark.dropped,
+        transportOpen: open,
+        targetGone: sessionId === undefined ? null : (gone.get(sessionId) ?? null),
+        navigations:
+          sessionId === undefined ? 0 : (navigations.get(sessionId) ?? 0) - mark.navigations,
+      };
+    },
+  };
+}

package/src/cdp.ts

@@ -0,0 +1,46 @@
+// `@ultimat3/scraping/cdp` — the raw-CDP browser as a runtime: find a Chrome, launch it over its
+// pipe, talk to it, and the four `X_CDP_*` refusals. Its own entry, off the `.` barrel: a caller
+// that only launches (`@ultimat3/testing`'s e2e driver, `x shot`) loads no job, storage or scrape
+// module for it. `pdf()` on the barrel prints through the same launcher.
+
+export type {
+  CdpConnection,
+  CdpConnectionOptions,
+  CdpEventListener,
+  CdpResult,
+  CdpTransport,
+} from './cdp-connection';
+export { cdpConnect, cdpConnectOver } from './cdp-connection';
+export type { CdpErrorCode } from './cdp-error-codes';
+export { CDP_ERROR_CODES, CDP_ERROR_TITLES } from './cdp-error-codes';
+export type {
+  CdpLaunchAttempt,
+  CdpTargetGone,
+  CdpTimeoutObservation,
+  CdpTimeoutReading,
+} from './cdp-errors';
+export {
+  CdpBrowserMissingError,
+  CdpCallFailedError,
+  CdpLaunchFailedError,
+  CdpTimeoutError,
+} from './cdp-errors';
+export type { CdpWire, FoundChromeOptions, LaunchedBrowser, LaunchOptions } from './cdp-launch';
+export {
+  BROWSER_LIFETIME_MS,
+  CHROME_CANDIDATES,
+  CHROME_PATH_ENV,
+  CLOSE_GRACE_MS,
+  CONTAINER_CHROME_ARGS,
+  chromeCandidates,
+  chromeLaunchFlags,
+  defaultWire,
+  findChrome,
+  LAUNCH_ATTEMPTS,
+  LAUNCH_BUDGET_MS,
+  LAUNCH_REAP_MS,
+  LAUNCH_TIMEOUT_MS,
+  launchChrome,
+  launchFoundChrome,
+} from './cdp-launch';
+export { LAUNCHED_CLOSE_MS } from './cdp-launch-attempt';