@ultimat3/cli 18.0.0 → 19.1.0

package/src/cmd-dev-fixture.ts

@@ -0,0 +1,147 @@
+// The app `x dev` boots in its tests, and the one place it is declared: every assertion that
+// needs a booted app lives in `cmd-dev.test.ts`, because a process has ONE lifecycle — the second
+// in-process boot is refused (X_LIFECYCLE_DRAINED) — and the coverage gate runs a package in one
+// process. So the fixture is a module of its own, and that file keeps its line budget for tests.
+//
+// What the app declares, and what each declaration is here to prove:
+//   app.config.ts               the root marker a real `x dev` cannot start without; `ai.mcp` by default
+//   apps/web/mcp.ts             the app's own MCP endpoint, mounted by the web role
+//   apps/web/runtime.ts         the app's middleware, reaching a development process
+//   apps/web/app/notes/*        a memory-backed entity and a live query, fed by the in-process bridge
+//   apps/web/app/posts/*        an action, a policy and a query, mounted as HTTP routes
+//   apps/web/site/pricing/*     a static page with its own stylesheet, under the CSP `x dev` sends
+import { resetRegistry as resetActions } from '@ultimat3/action';
+import { clearRegistry as clearEntities } from '@ultimat3/entity';
+import { resetJobs, resetTasks } from '@ultimat3/jobs';
+import { clearPermissions, clearRoles } from '@ultimat3/policy';
+import { resetRegistry as resetQueries } from '@ultimat3/query';
+import type { Frame } from '@ultimat3/realtime';
+import { decode } from '@ultimat3/realtime';
+import type { WsLike } from '@ultimat3/realtime/server';
+import { clearRoutes } from '@ultimat3/render';
+import { resetAppLoad } from './app-load';
+
+export const DEV_FIXTURE_FILES: Readonly<Record<string, string>> = {
+  'package.json': JSON.stringify({ name: 'dev-fixture', version: '1.4.0' }),
+
+  // The root marker a real `x dev` cannot start without, and where `ai.mcp` is declared — by
+  // default `{ expose: true, path: '/mcp' }`, which is what the MCP mount reads.
+  'app.config.ts': `import { defineConfig } from '@ultimat3/core';
+export const config = defineConfig({ name: 'dev-fixture' });
+`,
+
+  // The app's own MCP endpoint, in the contract `app-mcp.ts` reads. `resolveToken` answering
+  // `null` rejects every bearer, which is enough to prove the ROUTE is mounted (401, not 404).
+  'apps/web/mcp.ts': `import { defineAppMcp } from '@ultimat3/mcp';
+export const mcp = defineAppMcp({ include: 'exposed', resolveToken: () => null });
+`,
+
+  // The app's own middleware, in the contract `app-runtime.ts` reads: a header on every response
+  // is the cheapest proof that the chain `x dev` composed is the app's and not only the replica's.
+  'apps/web/runtime.ts': `const stamp = async (request, ctx, next) => {
+  const response = await next(request, ctx);
+  const headers = new Headers(response.headers);
+  headers.set('x-dev-runtime', 'app');
+  return new Response(response.body, { status: response.status, headers });
+};
+export const runtime = { middleware: [stamp] };
+`,
+
+  // A memory-backed entity, so the fixture needs no migration: the row observer sits on
+  // `database()`'s repo wrapper, the same seam a Postgres-backed repo writes through.
+  'apps/web/app/notes/entity.ts': `import { database, entity, memoryDriver, text, uuid } from '@ultimat3/entity';
+export const notes = entity('notes', { columns: { id: uuid().primaryKey(), title: text() } });
+export const db = database({ notes }, { driver: memoryDriver() });
+`,
+  'apps/web/app/notes/live.ts': `import { allow } from '@ultimat3/policy';
+import { from, query, t } from '@ultimat3/query';
+import { db } from './entity';
+export const liveNotes = query({
+  input: t.object({}),
+  policy: allow('public'),
+  live: true,
+  subscribes: ['notes'],
+  sql: () =>
+    from<{ id: string; title: string }>('notes', () => db.notes.where({}).all())
+      .orderBy('id')
+      .limit(50),
+});
+`,
+
+  'apps/web/app/posts/policy.ts': `import { allow, can, definePermissions, defineRoles } from '@ultimat3/policy';
+export const permissions = definePermissions(['post:publish'] as const);
+export const roles = defineRoles({
+  author: { grants: ['post:publish'] },
+  reader: { grants: [] },
+});
+export const canPostWrite = can('post:publish');
+export const anyone = allow();
+`,
+
+  'apps/web/app/posts/actions.ts': `import { action, t } from '@ultimat3/action';
+import { anyone, canPostWrite } from './policy';
+
+export const publishPost = action({
+  input: t.object({ id: t.uuid }),
+  output: t.object({ id: t.uuid }),
+  policy: canPostWrite,
+  async handle({ input }) {
+    return { id: input.id };
+  },
+});
+
+export const echoPost = action({
+  input: t.object({ word: t.string }),
+  output: t.object({ word: t.string }),
+  policy: anyone,
+  async handle({ input }) {
+    return { word: input.word };
+  },
+});
+`,
+
+  // A stylesheet the page imports, because that import is what registers it — and the document's
+  // inline `<style>` is what the CSP has to name. Without one this file served no styled page and
+  // could not have caught the policy that blanked every deployed app.
+  'apps/web/site/pricing/page.module.scss': `.price { color: #123456; }
+`,
+
+  'apps/web/site/pricing/page.tsx': `import { defineRoute } from '@ultimat3/render';
+import './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  offline: 'precache',
+  hydrate: 'never',
+  budget: { js: '0kb' },
+  meta: () => ({ title: 'Pricing', description: 'What it costs' }),
+});
+`,
+};
+
+export const resetRegistries = (): void => {
+  resetActions();
+  resetQueries();
+  clearEntities();
+  clearRoutes();
+  resetJobs();
+  resetTasks();
+  clearPermissions();
+  clearRoles();
+  resetAppLoad();
+};
+
+/** A `WsLike` that keeps every frame the node sends, decoded — what a live assertion reads. */
+export class FakeWs implements WsLike {
+  readonly frames: Frame[] = [];
+  send(data: string): number {
+    this.frames.push(decode(data));
+    return data.length;
+  }
+  close(): void {}
+  subscribe(): void {}
+  unsubscribe(): void {}
+  getBufferedAmount(): number {
+    return 0;
+  }
+}

package/src/cmd-dev.ts

@@ -14,15 +14,19 @@ 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';
 import { appManifest } from './app-manifest';
+import { mountAppMcp } from './app-mcp';
 import { requireAppRoot } from './app-root';
+import { loadAppRuntime } from './app-runtime';
 import type { CliCommand, CommandContext } from './command';
 import { assetRoutes } from './dev-assets';
 import type { DevDashboardInput, DevStatus } from './dev-dashboard';
 import { devDashboardRoutes, devPanels } from './dev-dashboard';
+import { liveFeedLabel } from './dev-live-feed';
 import { clearLock, preflight, writeLock } from './dev-lock';
 import { createStatementLedger } from './dev-n-plus-one';
 import { appRoutes } from './dev-render';
@@ -49,6 +53,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;
 
@@ -68,6 +74,8 @@ export interface DevServer {
   readonly runtime: RunningServices;
   /** Panel keys `/_x` mounted, in tab order. Reported so `--json` names what is reachable. */
   readonly panels: readonly string[];
+  /** `POST <path>` of the app's own MCP endpoint, or `null` when nothing was mounted. */
+  readonly mcp: string | null;
   stop(): Promise<void>;
 }
 
@@ -176,12 +184,25 @@ 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 });
 
+  // The app's own MCP endpoint, discovered from `apps/<app>/mcp.ts` and mounted through the SAME
+  // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
+  // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
+  const mcpMount = await mountAppMcp(options.root);
   const routes: readonly Route[] = [
     ...devDashboardRoutes(dashboard),
     // The same API table the container serves: a read that answers here and 404s in production
     // is exactly the drift one composition exists to prevent.
     ...apiRoutes(),
+    ...mcpMount.routes,
     // The image pipeline's only HTTP surface: the icons the web manifest declares, and the
     // variants every `srcset` promises. Mounted before the app's own routes so a page route can
     // never shadow `/icons` or `/media`.
@@ -203,14 +224,22 @@ 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 ?? '') }),
     }),
   ];
 
-  const replicaOverride = replicaOverrides(undefined, services.db, options.env);
+  // The app's `apps/<app>/runtime.ts`, composed exactly as `runRole` composes a caller's
+  // `runtime`: the replica scope in front, the app's own middleware behind it. Before this the
+  // first argument was `undefined` here and an app's middleware reached no development process.
+  const replicaOverride = replicaOverrides(
+    await loadAppRuntime(options.root),
+    services.db,
+    options.env,
+  );
   const running = await startRoles({
     roles: options.roles ?? DEV_ROLES,
     port: options.port,
@@ -266,6 +295,7 @@ export async function startDev(options: StartDevOptions): Promise<DevServer> {
     url: running.url ?? `http://localhost:${options.port}`,
     services,
     roles: running.roles,
+    mcp: mcpMount.path,
     get buildId(): string {
       return state.manifest.buildId;
     },
@@ -368,7 +398,7 @@ export const devCommand: CliCommand = {
         panels: server.panels.length,
         // Rendered text, so the mail and CDN halves come from the catalog; `data` below carries the
         // status values a script parses, which is why the two are different calls and not one.
-        services: `${describeServices(server.services)} ${mailLabel(server.runtime)} ${cdnLabel(server.runtime)}`,
+        services: `${describeServices(server.services)} ${mailLabel(server.runtime)} ${cdnLabel(server.runtime)} ${liveFeedLabel(server.running.liveFeed)}`,
       }),
       findings: server.findings,
       // Every fact `lines` prints is a fact `--json` carries, `manifest` included — or the two
@@ -393,10 +423,15 @@ export const devCommand: CliCommand = {
         // on one database is the one topology mistake that cannot be seen from the outside, so the
         // slot is a scriptable fact rather than a line in a log.
         replicationSlot: server.running.replicator?.slot ?? null,
+        // Which change feed the sync node has: `in-process` under the embedded database, where
+        // this process's own writes reach subscribers; `replication` with a real one; `none`
+        // when no sync role runs here. The label on the ready line is this same fact.
+        liveFeed: server.running.liveFeed,
         buildId: server.buildId,
         manifest: join(root, MANIFEST_FILENAME),
         introspect: `${server.url}/_x`,
         panels: [...server.panels],
+        mcp: server.mcp,
       },
       lines: [
         // A hard kill leaves the lock behind; clearing it is normal and worth one line, never a
@@ -406,6 +441,9 @@ export const devCommand: CliCommand = {
         msg('cli.dev.panels', { panels: server.panels.join(', ') }),
         msg('cli.dev.manifest', { path: join(root, MANIFEST_FILENAME) }),
         msg('cli.dev.introspect', { url: `${server.url}/_x` }),
+        // Only when something was mounted: the unmounted case has already said why, once, as a
+        // warning with a fix, and a summary line reading `mcp none` would be a second copy of it.
+        ...(server.mcp === null ? [] : [msg('cli.dev.mcp', { path: server.mcp })]),
       ],
     };
     await writeLock(services.stateDir, {

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/dev-live-feed.ts

@@ -0,0 +1,61 @@
+// Where a `sync` node's changes come from when this process boots one. Production decodes the
+// write-ahead log (`x dev --role replicator`, `PgLogicalReplicationFeed`, a real `DATABASE_URL`).
+// The embedded database has no walsender, and until 2026-09-05 nothing stood in for it: a live
+// subscription under `x dev` took its snapshot and then heard nothing, so every `--live` query in
+// every scaffolded app was dead in development — which is where an author first tries one.
+//
+// The bridge is `@ultimat3/testing`'s `startLiveReplicator`, the same in-process row observer the
+// framework's own live tests run on: a repository write in THIS process becomes a `ChangeEvent`
+// shaped exactly as the WAL decoder shapes one, fanned into the node's registry. Its honest bound
+// is stated there and repeated here — a write another process makes is invisible — and `x dev` is
+// the one boot where that bound holds by construction: every role runs in this one process.
+
+import { logger, renderThrowable } from '@ultimat3/core';
+import type { LiveReplicator } from '@ultimat3/testing';
+import { startLiveReplicator } from '@ultimat3/testing';
+import type { ServiceMode } from './dev-services';
+import type { RunningSync } from './dev-sync';
+
+/** What feeds the sync node, said out loud on the boot line and in `--json`. */
+export type LiveFeed = 'in-process' | 'replication' | 'none';
+
+export interface RunningLiveFeed {
+  readonly feed: LiveFeed;
+  /** The installed bridge, so a test can await `settled()`; `null` for the other two feeds. */
+  readonly bridge: LiveReplicator | null;
+  stop(): void;
+}
+
+export interface LiveFeedInput {
+  /** The sync node this process booted, or `null` when the role was not selected. */
+  readonly sync: RunningSync | null;
+  /** The database's binding: `embedded` is PGlite, which has no log to decode. */
+  readonly dbMode: ServiceMode;
+}
+
+/** The label the `x dev` boot line carries beside `db=`, `events=` and `storage=`. */
+export const liveFeedLabel = (feed: LiveFeed): string => `live=${feed}`;
+
+/**
+ * `embedded` → the in-process bridge; anything else → replication, which is the WAL decoder's
+ * job whether the replicator role runs in this process or another. Never both: with a real
+ * database the decoder already delivers this process's own writes, and a bridge beside it would
+ * deliver every one of them twice. No sync node, no feed to speak of.
+ */
+export async function startLiveFeed(input: LiveFeedInput): Promise<RunningLiveFeed> {
+  if (input.sync === null) return { feed: 'none', bridge: null, stop: () => undefined };
+  if (input.dbMode !== 'embedded') {
+    return { feed: 'replication', bridge: null, stop: () => undefined };
+  }
+  const bridge = await startLiveReplicator({
+    registry: input.sync.registry,
+    // Logged, never thrown: one change nobody could fan out must not take the dev server down.
+    onError: (error) =>
+      logger.warn('live.bridge_delivery_failed', { error: renderThrowable(error) }),
+  });
+  logger.info('live feed in-process', {
+    detail:
+      'the embedded database has no walsender; repository writes in this process reach subscribers',
+  });
+  return { feed: 'in-process', bridge, stop: () => bridge.stop() };
+}

package/src/dev-roles.ts

@@ -26,7 +26,11 @@ import {
   jobDriver,
   pgSchedulerState,
 } from '@ultimat3/jobs';
+import type { LiveQueryRegistry } from '@ultimat3/realtime/server';
+import type { LiveReplicator } from '@ultimat3/testing';
 import { devHooks } from './dev-hooks';
+import type { LiveFeed } from './dev-live-feed';
+import { startLiveFeed } from './dev-live-feed';
 import { pgExecutorFor } from './dev-queue';
 import type { RunningReplicator } from './dev-replicator';
 import { startReplicator } from './dev-replicator';
@@ -130,6 +134,12 @@ export interface RunningRoles {
   readonly scheduler: Scheduler | null;
   /** The slot and feed this process holds; null when the replicator was not selected. */
   readonly replicator: RunningReplicator | null;
+  /** What feeds the sync node: this process's own writes, the WAL decoder, or nothing. */
+  readonly liveFeed: LiveFeed;
+  /** The in-process bridge when `liveFeed` is `in-process`, so a test can await `settled()`. */
+  readonly liveBridge: LiveReplicator | null;
+  /** The sync node's registry, so a test can hold a real subscription; null without the role. */
+  readonly liveRegistry: LiveQueryRegistry | null;
   stop(): Promise<void>;
 }
 
@@ -426,6 +436,12 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       : null;
     if (replicator !== null) started.push(() => replicator.stop());
 
+    // What feeds the sync node this process booted. The embedded database has no log to decode,
+    // so under it the node is fed by this process's own repository writes (`dev-live-feed.ts`);
+    // with a real database the WAL decoder above is the feed, here or in another process.
+    const live = await startLiveFeed({ sync, dbMode: options.runtime.services.db.mode });
+    started.push(async () => live.stop());
+
     return {
       roles: selected,
       url: server === null ? null : server.url(),
@@ -435,8 +451,12 @@ export async function startRoles(options: StartRolesOptions): Promise<RunningRol
       worker,
       scheduler,
       replicator,
+      liveFeed: live.feed,
+      liveBridge: live.bridge,
+      liveRegistry: sync?.registry ?? null,
       async stop() {
         // Reverse boot order, so the slot is released before the bus it published to closes.
+        live.stop();
         await replicator?.stop();
         await scheduler?.stop();
         // Before the worker, so nothing publishes into a queue whose consumer has already gone —

package/src/dev-sync.ts

@@ -96,6 +96,8 @@ export function syncPortFor(port: number): number {
 /** What `startRoles` holds on to: where the node listens, and how to take it down. */
 export interface RunningSync {
   readonly url: string;
+  /** The node's registry, so the boot can hand it a change feed the database cannot produce. */
+  readonly registry: LiveQueryRegistry;
   stop(): Promise<void>;
 }
 
@@ -154,9 +156,10 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
   // override is how a deployment states a window its credential already declares (a token's
   // `exp`), or resolves identity from a header the adapter deliberately does not retain.
   const authenticate = options.overrides?.syncAuthenticate ?? syncAuthenticator(options.buildId);
+  const registry = registerLiveQueries(options);
   const node = createSyncNode({
     hub,
-    registry: registerLiveQueries(options),
+    registry,
     transport: options.runtime.transport,
     buildId: options.buildId,
     sockets,
@@ -177,6 +180,7 @@ export async function startSync(options: StartRolesOptions): Promise<RunningSync
     const listener = listenSyncNode(node, { port });
     return {
       url: listener.url,
+      registry,
       stop: async () => {
         listener.stop();
         await node.stop();

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,