@ultimat3/cli 18.0.0 → 19.0.0

package/src/cdp-e2e-page.ts

@@ -0,0 +1,209 @@
+// 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
+// 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 type { E2eBrowserPage } from './e2e-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 remote = result?.['result'];
+  if (typeof remote !== 'object' || remote === null) return undefined;
+  return (remote as Record<string, unknown>)['value'];
+};
+
+export interface CdpE2ePageOptions {
+  readonly connection: CdpConnection;
+  /**
+   * 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;
+}
+
+/**
+ * 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);
+
+  // **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,
+  );
+
+  // `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);
+  };
+
+  return {
+    url: () => current,
+    async goto(url: string): Promise<unknown> {
+      // **The load EVENT is the signal, not the reply.** Chrome drops `Page.navigate`'s own reply
+      // whenever the navigation swaps the render process — measured on Chrome 150 against a local
+      // server: the page loads, the server is hit, a later `Runtime.evaluate` answers `document
+      // .title` from the new document, and the navigate frame never comes back at all. Awaiting
+      // the reply therefore waited out the full deadline on the most ordinary navigation there is,
+      // `about:blank` → `http://localhost:<port>/`. So the waiter is registered BEFORE the send,
+      // and the reply is raced against it rather than depended on.
+      const loaded = options.connection.once(
+        'Page.loadEventFired',
+        sessionId,
+        options.loadTimeoutMs,
+      );
+      // A dropped reply is expected, so its rejection is answered rather than thrown: what the
+      // reply is still worth reading for is `errorText`, which is the ONLY place a refused
+      // navigation is named — an unreachable host loads no page and fires no load event.
+      const answered = send('Page.navigate', { url }, sessionId).then(
+        (answer) => {
+          const failed = answer.result?.['errorText'];
+          return typeof failed === 'string' && failed !== '' ? failed : undefined;
+        },
+        () => undefined,
+      );
+      const failed = await Promise.race([loaded.then(() => undefined), answered]);
+      if (failed !== undefined) {
+        throw new CdpCallFailedError({ method: `Page.navigate to ${url}`, detail: failed });
+      }
+      current = url;
+      // The load event may already have fired before the waiter was registered on a same-process
+      // 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.
+      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)});
+      }))()`);
+      // The app may have redirected, so the committed url is re-read rather than assumed.
+      const settled = await evaluate('location.href');
+      if (typeof settled === 'string' && settled !== '') current = settled;
+      return undefined;
+    },
+    evaluate,
+    async click(selector: string): Promise<void> {
+      // In-page rather than a synthesised `Input.dispatchMouseEvent`: the port takes a SELECTOR,
+      // and turning one into coordinates means a box model read, a scroll and a hit test — three
+      // more CDP calls, each with its own way to be wrong about an element the page can click.
+      const clicked = await evaluate(
+        `(() => { const el = document.querySelector(${JSON.stringify(selector)}); if (!el) return false; el.click(); return true; })()`,
+      );
+      if (clicked !== true) {
+        throw new CdpCallFailedError({
+          method: `click(${selector})`,
+          detail: 'no element in the page matches that selector',
+        });
+      }
+    },
+    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);
+        }
+      }
+    },
+  };
+}

package/src/cdp-errors.ts

@@ -0,0 +1,56 @@
+// One constructor per way the raw-CDP e2e browser refuses. Every cause quotes a value that came
+// out of a BROWSER or off a spawned process's stderr, so every one is rendered rather than
+// interpolated — the rule `e2e-errors.ts` already states.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+
+/**
+ * No browser to drive. This is the one an author meets first, so its fix names the two ways out:
+ * point the driver at a binary, or accept that this machine cannot run the check.
+ */
+export class CdpBrowserMissingError extends UltimateError {
+  constructor(input: { readonly tried: readonly string[] }) {
+    super({
+      code: 'X_CDP_BROWSER_MISSING',
+      cause: `no Chrome or Chromium executable was found — tried ${renderCauseValue(input.tried)}`,
+      fix: 'set CHROME_PATH to a Chrome or Chromium binary (GitHub-hosted ubuntu runners ship one at /usr/bin/google-chrome), or skip the browser-backed e2e suite by leaving it unset',
+    });
+  }
+}
+
+/** The binary ran and never announced an endpoint — a crash, a bad flag, or a sandbox refusal. */
+export class CdpLaunchFailedError extends UltimateError {
+  constructor(input: { readonly executable: string; readonly detail: string }) {
+    super({
+      code: 'X_CDP_LAUNCH_FAILED',
+      cause: `${renderCauseValue(input.executable)} did not announce a DevTools endpoint: ${renderCauseValue(input.detail)}`,
+      fix: 'run the same binary by hand with --headless=new --remote-debugging-port=0 and read its stderr; inside a container add --no-sandbox --disable-dev-shm-usage, which this launcher already passes',
+    });
+  }
+}
+
+/** A CDP call answered with an error frame, or the connection died under it. */
+export class CdpCallFailedError extends UltimateError {
+  constructor(input: { readonly method: string; readonly detail: string }) {
+    super({
+      code: 'X_CDP_CALL_FAILED',
+      cause: `the browser refused ${renderCauseValue(input.method)}: ${renderCauseValue(input.detail)}`,
+      fix: 'print what the page had: await page.evaluate(() => document.body.innerHTML) — a call that refuses the same way means the browser itself is gone, so read the launch above it',
+    });
+  }
+}
+
+/**
+ * A call that never answered. Its own code rather than `X_TIMEOUT`, because the actionable half is
+ * WHICH call: a hung `Page.navigate` is an app that never finishes responding, and a hung
+ * `Runtime.evaluate` is an expression that never settles.
+ */
+export class CdpTimeoutError extends UltimateError {
+  constructor(input: { readonly method: string; readonly timeoutMs: number }) {
+    super({
+      code: 'X_CDP_TIMEOUT',
+      cause: `${renderCauseValue(input.method)} did not answer inside ${String(input.timeoutMs)}ms`,
+      fix: 'raise timeoutMs on installE2eDriver({ timeoutMs }), or find the request the page is still waiting on — a navigation that never settles is an app that never finishes its response',
+    });
+  }
+}

package/src/cdp-launch.ts

@@ -0,0 +1,130 @@
+// One responsibility: start a Chrome in this container and hand back its DevTools endpoint and the
+// way to stop it. The connection is `cdp-connection.ts` and the page surface `cdp-e2e-page.ts`.
+
+// why: Bun exposes no recursive-remove and no temp-root primitive, so the throwaway profile
+// directory this launcher must create and delete needs both.
+import { mkdtempSync, rmSync } from 'node:fs';
+// why: Bun exposes no tmpdir(), so only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path-join primitive.
+import { join } from 'node:path';
+import { CdpBrowserMissingError, CdpLaunchFailedError } from './cdp-errors';
+
+/**
+ * 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; the two
+ * `/usr/bin` names after it are what GitHub-hosted `ubuntu-latest` ships, which is what lets the
+ * browser-backed suite run in CI with **no download step and no new dependency**.
+ */
+export const CHROME_PATH_ENV = 'CHROME_PATH';
+export const CHROME_CANDIDATES: readonly string[] = [
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+];
+
+/** The first candidate that exists, or `undefined`. An absent browser is a SKIP, never a failure. */
+export async function findChrome(
+  env: Readonly<Record<string, string | undefined>>,
+): Promise<string | undefined> {
+  const declared = env[CHROME_PATH_ENV];
+  const candidates = declared === undefined || declared === '' ? CHROME_CANDIDATES : [declared];
+  for (const candidate of candidates) {
+    if (await Bun.file(candidate).exists()) return candidate;
+  }
+  return undefined;
+}
+
+/**
+ * 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.
+ * `--no-sandbox` and `--disable-dev-shm-usage` are the two a container needs: the sandbox needs
+ * privileges CI does not grant, and `/dev/shm` is 64 MB in a default container, which crashes the
+ * renderer on any real page.
+ */
+const flags = (profileDir: string): readonly string[] => [
+  '--headless=new',
+  '--remote-debugging-port=0',
+  `--user-data-dir=${profileDir}`,
+  '--no-sandbox',
+  '--disable-dev-shm-usage',
+  '--disable-gpu',
+  // 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',
+  '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. */
+  close(): void;
+}
+
+export interface LaunchOptions {
+  readonly executable: string;
+  /** How long Chrome has to announce its endpoint before this gives up and kills it. */
+  readonly timeoutMs: number;
+}
+
+/**
+ * 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.
+ */
+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 close = (): void => {
+    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();
+  }
+  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. */
+export async function launchFoundChrome(
+  env: Readonly<Record<string, string | undefined>>,
+  timeoutMs: number,
+): Promise<LaunchedBrowser> {
+  const executable = await findChrome(env);
+  if (executable === undefined) throw new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+  return launchChrome({ executable, timeoutMs });
+}

package/src/cmd-dev.ts

@@ -14,6 +14,7 @@ import type { OverlayNotice, RequestContext, Route } from '@ultimat3/http';
 import { asCtx } from '@ultimat3/http';
 import type { Manifest } from '@ultimat3/manifest';
 import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { describeRoutes } from '@ultimat3/render';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { loadApp } from './app-load';
@@ -49,6 +50,8 @@ import { flagString } from './parse';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { metricsPortFor } from './serve';
 import { loopFacts, loopFinding, loopNotice } from './statement-loop';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
 
 const DEFAULT_PORT = 3000;
 
@@ -176,6 +179,14 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
   // name it. `undefined` for an app that is not installable, and then nothing is mounted and no
   // document changes — the 0kb baseline is not spent on a `<link>` to a file that does not exist.
   const pwa = await loadPwaArtifacts(options.root);
+  // Built once at boot, from this process's own route table and island bundle. `x dev` rebuilds
+  // islands on the watcher tick and the worker is NOT rebuilt with them, deliberately: a service
+  // worker that changes under a page it already controls is the update path, and re-emitting one
+  // per keystroke would exercise it on every save.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands: state.islands });
 
   const routes: readonly Route[] = [
     ...devDashboardRoutes(dashboard),
@@ -203,10 +214,11 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
       islands: () => state.islands,
       states: () => loadIslandStates(options.root),
     }),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...appRoutes({
       buildId,
       resolveIsland: (file) => state.islands.resolverFor(file),
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
     }),
   ];
 

package/src/compile-externals.ts

@@ -11,10 +11,17 @@
  * anyway, and that is the whole failure: Bun 1.3 refuses the build with
  * `Could not resolve: "@babel/preset-typescript/package.json"`, while Bun 1.4 bundles the
  * unresolvable `require` as a runtime throw — so one tree compiled on a laptop and did not in CI.
- * That skew is closed `As of 2026-08-20`: CI pins `1.4.x` (`.github/actions/setup/action.yml`),
- * `docker/Dockerfile` builds on `oven/bun:1.4-slim` and `scripts/setup.ts` holds contributors to
- * 1.4.0, so every builder now takes the second branch. The external stays regardless — it is the
- * `--compile` graph that must not reach an unresolvable `require`, on either Bun.
+ *
+ * **This list is what closed that, and the version pin never was.** The paragraph here said the
+ * skew was closed `As of 2026-08-20` by CI moving to `1.4.x`, "so every builder now takes the
+ * second branch", and added that the external stays regardless. Read together those are two fixes
+ * for one bug, and only the second is a fix: pinning the whole repository to the Bun that TOLERATES
+ * an unresolvable `require` leaves the `--compile` graph still reaching one, so the next Bun that
+ * tightens resolution breaks the build again. Marking the specifier external means the graph never
+ * reaches it, on either Bun — measured on 2026-08-27, when the 1.4 pin was trialled in reverse:
+ * `docker build -f docker/Dockerfile` is green on `oven/bun:1.3-slim` and the image answers
+ * `--version`. So this file does not depend on the series above it, and a future move of that pin
+ * costs it nothing.
  *
  * Marking the dead specifier external rather than the two live ones: `serve.ts` calls
  * `buildIslands` on every boot, unconditionally, so a binary with `@babel/core` external is a

package/src/e2e-driver.ts

@@ -11,34 +11,52 @@ import {
   unavailableFixture,
   useE2eDriver,
 } from '@ultimat3/testing';
-import type { E2ePageOptions } from './e2e-page';
+import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 
 export type E2eDriverOptions = E2ePageOptions;
 
 /**
- * The three `E2eFixtures` members this driver cannot build, and why each is a REFUSAL rather than
- * a no-op. A fixture that silently did nothing 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.
- *
- * All three are genuinely out of reach of the shipped port, not merely unimplemented:
- * `CdpPageLike` (`packages/scraping/src/cdp-port.ts`) declares twelve methods and none of them is
- * `setOfflineMode`, and a new build id is a fact about the SERVER, which no page port has ever
- * been able to speak for.
+ * A member this driver cannot build is a REFUSAL, never a no-op. A fixture that silently did
+ * nothing 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.
  */
 const refuse =
   (name: string, needs: string): (() => Promise<void>) =>
   () =>
     Promise.reject(new FixtureUnavailableError({ name, needs }));
 
-/** What `e2eTest` hands its body: a real page, and three members that say what they are missing. */
-export const e2eFixtures = (page: PageLike): E2eFixtures => ({
+/**
+ * `offline()`/`online()` FORWARD, `As of 2026-08-27`. They refused until then on a reason the tree
+ * contradicted on the day it was written: this file said `CdpPageLike`
+ * (`packages/scraping/src/cdp-port.ts`) "declares twelve methods and none of them is
+ * `setOfflineMode`". It declares it at line 71 — optional, guarded, with a coded
+ * `X_NOT_IMPLEMENTED` in `cdp-target.ts` for a launcher that lacks it — and `page-over-target.ts`
+ * exposes it as `ScrapePage.offline()`. All of that landed in **the same commit as the comment**
+ * (#351), so the refusal was never true, and it is the reason issue #390 records a real browser
+ * check as out of reach.
+ *
+ * Optional on `E2eBrowserPage` rather than required, for the reason `CdpPageLike` gives about the
+ * same method: this port is the shape of somebody ELSE's object, and a six-line test double must
+ * still satisfy it. Absent, the refusal stands — and now it names the method the double is missing
+ * rather than a capability the framework does not have.
+ */
+const networkFixtures = (browser: E2eBrowserPage): Pick<E2eFixtures, 'offline' | 'online'> => {
+  const setOffline = browser.offline?.bind(browser);
+  if (setOffline === undefined) {
+    const needs =
+      "a page whose driver implements offline(enabled) — @ultimat3/scraping's ScrapePage does; a hand-rolled E2eBrowserPage may not";
+    return { offline: refuse('offline', needs), online: refuse('online', needs) };
+  }
+  return { offline: () => setOffline(true), online: () => setOffline(false) };
+};
+
+/** What `e2eTest` hands its body: a real page, the network condition, and one honest refusal. */
+export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixtures => ({
   page,
-  offline: refuse(
-    'offline',
-    "a CDP method for the browser's own network state — the shipped CdpPageLike has no setOfflineMode",
-  ),
-  online: refuse('online', 'the same CDP method offline() needs, in order to undo it'),
+  ...networkFixtures(browser),
+  // The one that is still genuinely out of reach, and it is not a port gap: a new build id is a
+  // fact about the SERVER, which no page port has ever been able to speak for.
   update: refuse(
     'update',
     'a second build served under a new immutable build id, which is a server fact',
@@ -65,7 +83,7 @@ export function installE2eDriver(options: E2eDriverOptions): () => void {
   const page = e2ePage(options);
   defineFixtures({ page: () => page });
   useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page)));
+    bunTest(name, () => body(e2eFixtures(page, options.page)));
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than

package/src/e2e-page.ts

@@ -10,15 +10,27 @@ import { e2eLocator } from './e2e-locator';
 import type { E2eSelection } from './e2e-selection';
 
 /**
- * What this adapter needs of a browser: four members, every one of them on `ScrapePage`. Declared
- * structurally rather than as `ScrapePage` so a test can stand one up in six lines — the same
- * bargain `cdp-port.ts` makes about puppeteer, one layer up.
+ * What this adapter needs of a browser: four required members, every one of them on `ScrapePage`.
+ * Declared structurally rather than as `ScrapePage` so a test can stand one up in six lines — the
+ * same bargain `cdp-port.ts` makes about puppeteer, one layer up.
  */
 export interface E2eBrowserPage {
   url(): string;
   goto(url: string, options?: { readonly timeout?: number | undefined }): Promise<unknown>;
   evaluate(expression: string): Promise<unknown>;
   click(selector: string): Promise<void>;
+  /**
+   * The browser's own network condition, which `E2eFixtures.offline()`/`online()` forward to.
+   * `ScrapePage` has it (`page-over-target.ts`), reaching `CdpPageLike.setOfflineMode` through
+   * `cdp-target.ts`'s guard.
+   *
+   * OPTIONAL for the reason the four above are structural: this port is the shape of somebody
+   * ELSE's object, and requiring it would cost every six-line double a type error for a capability
+   * a test that never goes offline does not need. Absent, `e2e-driver.ts` keeps refusing by name —
+   * a coded refusal, never a silent no-op, because an `offline()` that did nothing would let the
+   * app's ONLINE page pass an offline test.
+   */
+  offline?(enabled: boolean): Promise<void>;
 }
 
 export interface E2ePageOptions {

package/src/error-codes.ts

@@ -166,6 +166,13 @@ export const CLI_OWNED_ERROR_CODES = [
   'X_E2E_LOCATOR_EMPTY',
   'X_E2E_LOCATOR_AMBIGUOUS',
   'X_E2E_SERVICE_WORKER_ABSENT',
+  // The raw-CDP browser under that driver — `cdp-launch.ts`, `cdp-connection.ts`,
+  // `cdp-e2e-page.ts`, `cdp-browser.ts`. Four codes and not one, because the four repairs differ:
+  // install a browser, read the browser's own stderr, look at the page, raise a deadline.
+  'X_CDP_BROWSER_MISSING',
+  'X_CDP_LAUNCH_FAILED',
+  'X_CDP_CALL_FAILED',
+  'X_CDP_TIMEOUT',
   'X_GH_UNAVAILABLE',
   'X_GH_NOT_AUTHENTICATED',
   'X_GH_COMMAND_FAILED',
@@ -294,6 +301,10 @@ export const CLI_ERROR_TITLES: Readonly<Record<CliOwnedErrorCode, string>> = {
   X_E2E_LOCATOR_EMPTY: 'an e2e locator matched no element',
   X_E2E_LOCATOR_AMBIGUOUS: 'an e2e locator matched more than one element and was asked to click',
   X_E2E_SERVICE_WORKER_ABSENT: 'no service worker took control of the page within the budget',
+  X_CDP_BROWSER_MISSING: 'no Chrome or Chromium is installed for the e2e driver to launch',
+  X_CDP_LAUNCH_FAILED: 'the browser started and never announced a DevTools endpoint',
+  X_CDP_CALL_FAILED: 'the browser refused a DevTools call',
+  X_CDP_TIMEOUT: 'a DevTools call did not answer inside its deadline',
   X_GH_UNAVAILABLE: 'the GitHub CLI is not runnable from here',
   X_GH_NOT_AUTHENTICATED: 'gh holds no credentials for this host',
   X_GH_COMMAND_FAILED: 'a gh invocation exited non-zero',

package/src/index.ts

@@ -25,6 +25,33 @@ export type { BoundaryCut, BoundarySplit } from './boundary-cuts';
 export { planBoundaryCuts } from './boundary-cuts';
 export type { BuildStats, RouteStats } from './budgets';
 export { BUILD_STATS_FILE, checkBudgets, readBuildStats } from './budgets';
+// The raw-CDP browser the driver above runs on. `openE2eBrowserIfAvailable()` is what an app's
+// test preload calls: it answers `undefined` on a machine with no Chrome, so the browser-backed
+// suite SKIPS rather than turning a gate red for a reason unrelated to the change.
+export type { E2eBrowser, OpenE2eBrowserOptions } from './cdp-browser';
+export {
+  DEFAULT_CDP_TIMEOUT_MS,
+  openE2eBrowser,
+  openE2eBrowserIfAvailable,
+} from './cdp-browser';
+export type { CdpConnection, CdpConnectionOptions, CdpResult } from './cdp-connection';
+export { cdpConnect } from './cdp-connection';
+export type { CdpE2ePageOptions } from './cdp-e2e-page';
+export { cdpE2ePage } from './cdp-e2e-page';
+export {
+  CdpBrowserMissingError,
+  CdpCallFailedError,
+  CdpLaunchFailedError,
+  CdpTimeoutError,
+} from './cdp-errors';
+export type { LaunchedBrowser, LaunchOptions } from './cdp-launch';
+export {
+  CHROME_CANDIDATES,
+  CHROME_PATH_ENV,
+  findChrome,
+  launchChrome,
+  launchFoundChrome,
+} from './cdp-launch';
 export type { BuildTarget } from './cmd-build';
 export {
   argsFor,

package/src/mcp-errors.ts

@@ -78,6 +78,15 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   X_E2E_LOCATOR_AMBIGUOUS:
     'x test e2e --json   # the fix line carries the same call with .first() on it',
   X_E2E_SERVICE_WORKER_ABSENT: 'x build --target static --json',
+  // The four raw-CDP codes. `x doctor` for the missing browser, because that is the command whose
+  // whole job is reporting what this machine does not have; the other three are raised inside a
+  // running suite, so the runnable half is the command that re-runs it.
+  X_CDP_BROWSER_MISSING:
+    'x doctor --json   # or set CHROME_PATH to a Chrome binary; unset, the browser-backed suite skips',
+  X_CDP_LAUNCH_FAILED:
+    'x test e2e --json   # the cause carries the last lines of the browser\u2019s own stderr',
+  X_CDP_CALL_FAILED: 'x test e2e --json   # the cause names the DevTools call the browser refused',
+  X_CDP_TIMEOUT: 'x test e2e --json   # the cause names the call that never answered',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',