@ultimat3/cli 20.2.0 → 21.0.0

package/src/dev-render.ts

@@ -14,15 +14,32 @@
 // navigation, with a re-parse on top. The static export writes the file (`writeStyles`), so the
 // "second file" cost is one `Bun.write`.
 
+// why: Bun ships no path API; an island's file is its route file's directory joined to its `src`.
+import { posix } from 'node:path';
+import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx } from '@ultimat3/core';
+import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
 import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
 import { asCtx, html, stream } from '@ultimat3/http';
 import { currentLocale } from '@ultimat3/i18n';
-import type { IslandCollector, RenderResult, RouteData, RouteEntry } from '@ultimat3/render';
+import type {
+  ClientSyncHead,
+  IslandCollector,
+  RenderResult,
+  RouteData,
+  RouteEntry,
+} from '@ultimat3/render';
 import {
+  clientBootTags,
+  clientPersistTags,
+  clientScopeTag,
+  clientSyncTags,
   createIslandCollector,
+  documentCarriesScope,
   headFromMeta,
   hydrateRuntime,
+  islandModuleId,
+  islandModuleIds,
   metaContextFor,
   renderHead,
   routeDataFor,
@@ -39,9 +56,11 @@ import {
   ROOT_ELEMENT_ID,
   renderComponent,
   renderSsr,
+  ssrHeaders,
   staticHeaders,
   streamResult,
 } from '@ultimat3/render/server';
+import { realtimeIslandFiles } from './island-realtime';
 import { styleBundle } from './style-bundle';
 
 /**
@@ -71,6 +90,18 @@ export interface DocumentOptions {
    * decided by `app.config.ts`, which the boot read and the renderer cannot.
    */
   readonly themeHead?: string;
+  /**
+   * The page's sync target — `pageSync(…).head` — rendered as render's `clientSyncTags` on every
+   * document this process serves. Principal-free, so a shareable document carries it too; absent
+   * for a caller that serves no socket at all (the static export).
+   */
+  readonly sync?: ClientSyncHead;
+  /**
+   * The record types the app persists (`entity(…, { persist: true })`), read per render. Rendered
+   * as `ultimate-persist` beside the scope tag only — persistence is per principal, so a document
+   * with no scope carries none.
+   */
+  readonly persisted?: () => readonly string[];
 }
 
 export interface DevRenderOptions extends DocumentOptions {
@@ -94,16 +125,32 @@ export interface DevRouteData extends Record<string, unknown> {
  */
 const lang = (): string => currentLocale();
 
+/**
+ * `scope` is present only on a PRIVATE document (a gated `ssr` page, every `stream`): the page's
+ * client scope (`@ultimat3/auth`'s `clientScopeOf`), which core's `pageClient()` reads to fence its
+ * one store per principal. A shareable document (`static`, `isr`, ungated `ssr`) carries NO scope
+ * tag — absent means "not rendered for anyone", a different answer from `''`, the anonymous page.
+ */
 const headFor = async (
   entry: RouteEntry,
   ctx: DevRouteData,
   data: RouteData,
   options: DocumentOptions,
+  scope?: string,
 ): Promise<string> =>
   renderHead(
     headFromMeta(
       await entry.config.meta(metaContextFor(ctx, data)),
       seoRenderers({ path: new URL(ctx.url).pathname }),
+      [
+        ...(options.sync === undefined ? [] : clientSyncTags(options.sync)),
+        // The page boot rides the scope tag: its whole job — restoring a principal's persisted
+        // records and replaying its queued writes — is per principal, and a shareable document
+        // (no scope tag) has neither. Cheaper than walking the page's islands, and exact.
+        ...(scope === undefined
+          ? []
+          : [clientScopeTag(scope), ...clientPersistTags(options.persisted?.() ?? [])]),
+      ],
     ),
   ) +
   (options.themeHead ?? '') +
@@ -166,6 +213,33 @@ export async function routeBody(
  * an island never declares its own timing, and `resolve` is the build's — identity when nothing
  * built any, which fails at the first island by name rather than emitting an unusable entry.
  */
+/**
+ * Realtime's page boot, as one deferred script — or nothing. Two conditions, both exact: the
+ * document carries a principal scope (restoring persisted records and replaying queued writes are
+ * per principal; a shareable document has neither), AND one of the islands this render emitted
+ * reaches `@ultimat3/realtime` (a page whose islands never touch a record has nothing to restore
+ * into and no write to replay). After the body, because which islands rendered is a fact the walk
+ * just recorded; still before the hydration runtime, so it runs first among the deferred scripts.
+ */
+function bootScript(
+  entry: RouteEntry,
+  islands: IslandCollector,
+  options: DocumentOptions,
+  scope: string | undefined,
+): string {
+  if (scope === undefined || options.sync === undefined) return '';
+  const rendered = new Set(islandModuleIds(islands.directives));
+  if (rendered.size === 0) return '';
+  // An island's module id is derived from its `src`, written relative to the page that renders it:
+  // each realtime island file, spelled from THIS page, is the id its directive would carry.
+  const pageDir = posix.dirname(entry.file);
+  const reaches = [...realtimeIslandFiles()].some((file) => {
+    const src = posix.relative(pageDir, file);
+    return rendered.has(islandModuleId(src.startsWith('.') ? src : `./${src}`));
+  });
+  return reaches ? renderHead(clientBootTags(options.sync)) : '';
+}
+
 const collectorFor = (entry: RouteEntry, options: DocumentOptions): IslandCollector =>
   createIslandCollector({
     file: entry.file,
@@ -199,15 +273,16 @@ async function documentFrom(
   ctx: DevRouteData,
   data: RouteData,
   options: DocumentOptions,
+  scope?: string,
 ): Promise<string> {
   const islands = collectorFor(entry, options);
   const [head, body] = await Promise.all([
-    headFor(entry, ctx, data, options),
+    headFor(entry, ctx, data, options, scope),
     routeBody(entry, ctx, data, islands),
   ]);
   return (
     `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head>` +
-    `<body>${body}${hydrateRuntime(islands.directives)}</body></html>`
+    `<body>${body}${bootScript(entry, islands, options, scope)}${hydrateRuntime(islands.directives)}</body></html>`
   );
 }
 
@@ -256,31 +331,55 @@ async function resultFor(
       // correct output, no streaming benefit.
       const islands = collectorFor(entry, options);
       const [head, shell] = await Promise.all([
-        headFor(entry, request, data, options),
+        // A stream is always `private, no-store` (`streamResult`), so it always carries the scope.
+        headFor(entry, request, data, options, clientScopeOf(ctx.actor)),
         routeBody(entry, request, data, islands),
       ]);
-      return streamResult(
-        {
-          head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
-          // The runtime rides the first flush, with the shell it boots. A later chunk would leave
-          // the window between flush one and the close with inert islands and no listeners on
-          // them — which is exactly the first-click-lost failure `interaction` replay exists for.
-          shell: `${shell}${hydrateRuntime(islands.directives)}`,
-          holes: [],
-        },
-        { buildId: options.buildId },
-        status,
+      return withScope(
+        streamResult(
+          {
+            head: `<!doctype html><html lang="${lang()}"><head>${head}${styleTag(entry)}</head><body>`,
+            // The runtime rides the first flush, with the shell it boots. A later chunk would leave
+            // the window between flush one and the close with inert islands and no listeners on
+            // them — which is exactly the first-click-lost failure `interaction` replay exists for.
+            shell: `${shell}${bootScript(entry, islands, options, clientScopeOf(ctx.actor))}${hydrateRuntime(islands.directives)}`,
+            holes: [],
+          },
+          { buildId: options.buildId },
+          status,
+        ),
+        clientScopeOf(ctx.actor),
       );
     }
-    default:
-      return renderSsr(
-        { entry, params: request.params, url, ctx },
-        () => documentFrom(entry, request, data, options),
-        { buildId: options.buildId, status },
+    default: {
+      // Asked of the headers `renderSsr` is about to send: a gated page is private and carries the
+      // scope; an ungated one is `public, s-maxage` and a CDN may hand it to anyone, so it carries
+      // none — absent, which core reads as "not rendered for anyone", never as anonymous.
+      const scope = documentCarriesScope(ssrHeaders(entry, { buildId: options.buildId }))
+        ? clientScopeOf(ctx.actor)
+        : undefined;
+      return withScope(
+        await renderSsr(
+          { entry, params: request.params, url, ctx },
+          () => documentFrom(entry, request, data, options, scope),
+          { buildId: options.buildId, status },
+        ),
+        scope,
       );
+    }
   }
 }
 
+/**
+ * A private document's scope, as a RESPONSE header too: the service worker partitions its offline
+ * pages by principal and never parses HTML, so the meta alone cannot reach it. Exactly the
+ * documents that carry the scope tag carry this — a shareable one carries neither.
+ */
+const withScope = (result: RenderResult, scope: string | undefined): RenderResult =>
+  scope === undefined
+    ? result
+    : { ...result, headers: { ...result.headers, [CLIENT_SCOPE_HEADER]: scope } };
+
 const responseOf = (result: RenderResult): Response =>
   typeof result.body === 'string'
     ? html(result.body, { status: result.status, headers: result.headers })

package/src/dev-route-table.ts

@@ -0,0 +1,119 @@
+// The route table `x dev` serves, in mount order: the dashboard, the API, the assets a document
+// names, the island and sync-worker scripts, and the app's pages last. Split from `cmd-dev.ts` at its
+// 500-line ceiling; `serve.ts` composes the production table from the same builders.
+
+import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
+import type { Storage } from '@ultimat3/storage';
+import { apiRoutes } from './api-routes';
+import { mountAppMcp } from './app-mcp';
+import { assetRoutes } from './dev-assets';
+import type { DevDashboardInput } from './dev-dashboard';
+import { devDashboardRoutes } from './dev-dashboard';
+import { appRoutes } from './dev-render';
+import { storageRoutes } from './dev-storage';
+import { errorPageStyleSources } from './error-page-csp';
+import type { IslandBundle } from './island-bundle';
+import { islandHarnessRoutes } from './island-harness-route';
+import { islandRoutes } from './island-routes';
+import { loadIslandStates } from './island-states-load';
+import { pageSync } from './page-sync';
+import { loadPwaArtifacts } from './pwa-artifacts';
+import { styleBundle } from './style-bundle';
+import { styleRoutes } from './style-routes';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
+import type { ThemeBoot } from './theme-boot';
+import { loadThemeMode, themeBoot } from './theme-boot';
+
+export interface DevRouteTableInput {
+  readonly root: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly buildId: string;
+  readonly storage: Storage;
+  readonly dashboard: DevDashboardInput;
+  /** A getter: the watcher tick rebuilds the islands, and a captured bundle would serve the first. */
+  readonly islands: () => IslandBundle;
+}
+
+export interface DevRouteTable {
+  readonly routes: readonly Route[];
+  /** The theme boot, whose `cspSource` the web role admits. */
+  readonly theme: ThemeBoot;
+  /** The app's own error pages' inline styles, admitted the same way. */
+  readonly errorStyles: readonly string[];
+  /** Where the app's MCP endpoint was mounted, or `undefined`. */
+  readonly mcpPath: string | null;
+}
+
+export async function devRouteTable(input: DevRouteTableInput): Promise<DevRouteTable> {
+  // Resolved once, before the first route. `undefined` for an app that is not installable: nothing
+  // is mounted, and the 0kb baseline is not spent on a `<link>` to a file that does not exist.
+  const pwa = await loadPwaArtifacts(input.root);
+  const theme = themeBoot(await loadThemeMode(input.root));
+  // The same call `serve.ts` makes, so the two boots cannot serve different sync targets.
+  const sync = await pageSync(input.root, input.env, input.buildId);
+  const errorStyles = await errorPageStyleSources(input.root);
+  // Built once at boot and NOT rebuilt with the islands on a watcher tick: a service worker that
+  // changes under a page it controls is the update path, and one per keystroke exercises it per save.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({
+          pwa,
+          buildId: input.buildId,
+          routes: describeRoutes(),
+          islands: input.islands(),
+          styles: styleBundle(),
+          scripts: sync.scripts,
+        });
+
+  // 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(input.root);
+  const routes: readonly Route[] = [
+    ...devDashboardRoutes(input.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`.
+    ...assetRoutes({
+      root: input.root,
+      storage: input.storage,
+      ...(pwa === undefined ? {} : { pwa }),
+    }),
+    ...storageRoutes({ storage: input.storage }),
+    // The chunks the documents below name. Mounted before the app's routes for the reason
+    // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
+    ...islandRoutes(() => input.islands()),
+    // And the stylesheet every one of those documents links. Read through the getter for the
+    // reason the islands are: a rebuilt island registers CSS, which mints a new URL, and a table
+    // captured at boot would answer 404 for the href the document now carries.
+    ...styleRoutes(() => styleBundle()),
+    // `x shot --island`'s harness, in the `/_x` dev namespace so no app route can shadow it. It
+    // lives here rather than in a second server because everything it needs is in THIS process:
+    // the built chunks, the app's stylesheet registry, and the one embedded Postgres a checkout
+    // may have. The states are read per REQUEST — an author editing a state and re-running the
+    // command must not need a restart to see it.
+    ...islandHarnessRoutes({
+      islands: () => input.islands(),
+      states: () => loadIslandStates(input.root),
+    }),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
+    ...sync.routes,
+    ...appRoutes({
+      buildId: input.buildId,
+      resolveIsland: (file) => input.islands().resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
+      themeHead: theme.head,
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+    }),
+  ];
+
+  return { routes, theme, errorStyles, mcpPath: mcpMount.path };
+}

package/src/dev-services.ts

@@ -40,7 +40,10 @@ const nonEmpty = (value: string | undefined): string | undefined =>
  * is a directory delete rather than a container dance.
  */
 export function resolveServices(root: string, env: Env): DevServices {
-  const stateDir = join(root, '.x');
+  // `ULTIMATE_STATE_DIR` relocates the whole of `.x/` — the embedded database, the local disk and
+  // the dev lock — for one process tree. It is how an e2e run boots the app on a THROWAWAY database
+  // (`e2e-app.ts`) instead of resetting the developer's own, beside a running `x dev`.
+  const stateDir = nonEmpty(env['ULTIMATE_STATE_DIR']) ?? join(root, '.x');
   const databaseUrl = nonEmpty(env['DATABASE_URL']);
   const natsUrl = nonEmpty(env['NATS_URL']);
   const s3Endpoint = nonEmpty(env['S3_ENDPOINT']);

package/src/dev-sync.ts

@@ -131,6 +131,8 @@ 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;
+  /** The node's channel hub — fed the same changes, so a declared channel's `records` flow in dev. */
+  readonly hub: ChannelHub;
   stop(): Promise<void>;
 }
 
@@ -212,7 +214,7 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     // second copy of `/_x/sync` here is the copy that stays behind when it moves.
     mount: { path: node.path, fetch: node.fetch, websocket: node.websocket },
     stop: () => node.stop(),
-    listen: async (appUrl) => await listen(options, node, registry, appUrl),
+    listen: async (appUrl) => await listen(options, node, { registry, hub }, appUrl),
   };
 }
 
@@ -241,7 +243,7 @@ function syncPortFrom(requested: number, appUrl: string | null): number {
 async function listen(
   options: StartRolesOptions,
   node: SyncNode,
-  registry: LiveQueryRegistry,
+  feeds: Pick<RunningSync, 'registry' | 'hub'>,
   appUrl: string | null,
 ): Promise<RunningSync> {
   const port = syncPortFrom(options.port, appUrl);
@@ -266,7 +268,7 @@ async function listen(
     });
     return {
       url: listener.url,
-      registry,
+      ...feeds,
       stop: async () => {
         listener.stop();
         await node.stop();

package/src/e2e-app.ts

@@ -0,0 +1,103 @@
+// The app an e2e suite drives, spawned on a THROWAWAY state directory: its own embedded database,
+// its own disk, its own dev lock, created per call and removed on `stop()`. Never the developer's
+// `.x/pgdata` — resetting that from a test run destroys the data an `x dev` beside it is using.
+// This file is the DATABASE half; spawning, readiness and the restart are `e2e-spawn.ts`'s.
+
+// why: Bun ships no temp-directory primitive or recursive remove; `tmpdir()` is node:os's alone.
+import { mkdtemp, rm } from 'node:fs/promises';
+// why: Bun exposes no tmpdir() — only node:os answers the platform temp root.
+import { tmpdir } from 'node:os';
+// why: Bun exposes no path API — the state dir is joined, not concatenated.
+import { join } from 'node:path';
+import { finiteCount } from '@ultimat3/core';
+import type { E2eAppMode } from './e2e-spawn';
+import { inherited, refuse, spawnE2eApp, X_BIN } from './e2e-spawn';
+
+export type { E2eAppMode } from './e2e-spawn';
+
+export interface StartE2eAppOptions {
+  /** The app root — the directory holding `app.config.ts`. */
+  readonly root: string;
+  readonly mode?: E2eAppMode | undefined;
+  /**
+   * The arguments after `x db seed`, or `false` for no seeding. Default `['--tier', 'dev']`: every
+   * dev-tier seed, which is what a developer's own `x dev` starts from.
+   */
+  readonly seed?: readonly string[] | false | undefined;
+  /** Extra environment for every process — the reset, the seed and the app. */
+  readonly env?: Readonly<Record<string, string>> | undefined;
+  /** How long the app may take to answer `/readyz`. */
+  readonly readyTimeoutMs?: number | undefined;
+}
+
+export interface E2eApp {
+  /** `http://localhost:<port>`, no trailing slash. */
+  readonly base: string;
+  /** The throwaway `.x` this app runs on — the one directory a test may inspect or corrupt. */
+  readonly stateDir: string;
+  /** Kill the app and delete its state directory. Idempotent. */
+  stop(): Promise<void>;
+  /**
+   * Stop the app and start it again on the SAME port and state directory, with `env` added — a
+   * deploy. `{ BUILD_ID: 'b2' }` is a new build the open tabs have not seen (`deploy.newBuild()`).
+   */
+  restart(env?: Readonly<Record<string, string>>): Promise<void>;
+}
+
+const DEFAULT_READY_TIMEOUT_MS = 90_000;
+
+function x(args: readonly string[], root: string, env: Record<string, string>): void {
+  const run = Bun.spawnSync(['bun', X_BIN, ...args], {
+    cwd: root,
+    env: { ...inherited(), ...env },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+  if (run.exitCode !== 0) {
+    throw refuse(`x ${args.join(' ')}`, `${run.stdout.toString()}${run.stderr.toString()}`);
+  }
+}
+
+/**
+ * Reset and seed a fresh state directory, then spawn the app on a free port and wait for `/readyz`.
+ * The reset runs against the throwaway directory, so it is a first migration, never a data loss.
+ */
+export async function startE2eApp(options: StartE2eAppOptions): Promise<E2eApp> {
+  // Screened FIRST, before a directory or a process exists: `waited < NaN` is false, so a NaN budget would never poll and report a dead app.
+  const deadline = finiteCount(
+    'startE2eApp',
+    'readyTimeoutMs',
+    options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS,
+  );
+  const stateDir = await mkdtemp(join(tmpdir(), 'ultimate-e2e-'));
+  const env: Record<string, string> = { ...options.env, ULTIMATE_STATE_DIR: stateDir };
+  const cleanup = (): Promise<void> => rm(stateDir, { recursive: true, force: true });
+  try {
+    x(['db', 'reset'], options.root, env);
+    const seed = options.seed ?? ['--tier', 'dev'];
+    if (seed !== false) x(['db', 'seed', ...seed], options.root, env);
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+  try {
+    const spawned = await spawnE2eApp({
+      root: options.root,
+      mode: options.mode ?? 'dev',
+      env,
+      readyTimeoutMs: deadline,
+    });
+    return {
+      base: spawned.base,
+      stateDir,
+      restart: (next) => spawned.restart(next),
+      async stop(): Promise<void> {
+        await spawned.stop();
+        await cleanup();
+      },
+    };
+  } catch (error) {
+    await cleanup();
+    throw error;
+  }
+}

package/src/e2e-browser-handle.ts

@@ -0,0 +1,55 @@
+// The browser and the app the e2e step opened, reachable from a test file: `e2eBrowser()` and
+// `e2eApp()`. On `globalThis` under one `Symbol.for` key, because the preload and a test may each
+// hold their own copy of this module — the page-client handle's reason, one runtime over.
+
+import type { E2eBrowser } from './cdp-browser';
+import { CdpBrowserMissingError } from './cdp-errors';
+import { CHROME_CANDIDATES } from './cdp-launch';
+import type { E2eApp } from './e2e-app';
+
+/** Set by the e2e step to the app root; the preload spawns that app and opens a browser. */
+export const E2E_ROOT_ENV = 'ULTIMATE_E2E_ROOT';
+
+interface E2eRun {
+  browser: E2eBrowser;
+  readonly app: E2eApp;
+}
+
+const KEY = Symbol.for('ultimate.e2e.run');
+
+export function publishE2eRun(run: E2eRun): void {
+  Object.defineProperty(globalThis, KEY, { value: run, configurable: true });
+}
+
+const current = (): E2eRun | undefined => Reflect.get(globalThis, KEY) as E2eRun | undefined;
+
+/** Swap in a relaunched browser — the app stays; only the dead browser is replaced. */
+export function republishE2eBrowser(browser: E2eBrowser): void {
+  const run = current();
+  if (run !== undefined) run.browser = browser;
+}
+
+const missing = (): CdpBrowserMissingError =>
+  new CdpBrowserMissingError({ tried: CHROME_CANDIDATES });
+
+/**
+ * The run's browser: `page`, and `session` for a second tab, an init script, the socket and request
+ * log and the offline switch for every worker. Refuses by name outside an e2e run that found one.
+ */
+export function e2eBrowser(): E2eBrowser {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.browser;
+}
+
+/** The app the run spawned: `base`, `stateDir`, and `restart({ BUILD_ID })` — a deploy. */
+export function e2eApp(): E2eApp {
+  const run = current();
+  if (run === undefined) throw missing();
+  return run.app;
+}
+
+/** The spawned app's origin, or `undefined` outside an e2e run. */
+export function e2eBaseUrl(): string | undefined {
+  return current()?.app.base;
+}

package/src/e2e-driver.ts

@@ -14,7 +14,14 @@ import {
 import type { E2eBrowserPage, E2ePageOptions } from './e2e-page';
 import { e2ePage } from './e2e-page';
 
-export type E2eDriverOptions = E2ePageOptions;
+export interface E2eDriverOptions extends E2ePageOptions {
+  /**
+   * Switch the running app to a new build — the SERVER half no page port can speak for. Given, it
+   * becomes the `deploy` fixture's `newBuild()` and `e2eTest`'s `update()`; absent, both refuse by
+   * name. The gate's e2e preload passes the spawned app's `restart({ BUILD_ID })`.
+   */
+  readonly newBuild?: (() => Promise<void>) | undefined;
+}
 
 /**
  * A member this driver cannot build is a REFUSAL, never a no-op. A fixture that silently did
@@ -52,15 +59,21 @@ const networkFixtures = (browser: E2eBrowserPage): Pick<E2eFixtures, 'offline' |
 };
 
 /** What `e2eTest` hands its body: a real page, the network condition, and one honest refusal. */
-export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixtures => ({
+export const e2eFixtures = (
+  page: PageLike,
+  browser: E2eBrowserPage,
+  newBuild?: () => Promise<void>,
+): E2eFixtures => ({
   page,
   ...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',
-  ),
+  // A new build id is a fact about the SERVER, which no page port can speak for — so it is
+  // forwarded when whoever spawned the app can restart it, and refused by name otherwise.
+  update:
+    newBuild ??
+    refuse(
+      'update',
+      'a second build served under a new immutable build id, which is a server fact',
+    ),
 });
 
 /**
@@ -73,7 +86,7 @@ export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixture
  * `test.skip` — which the gate now reports as a SKIPPED step rather than the green check it
  * printed until #434, and which a repo whose `x.verify.json` names `e2e` gets red for.
  *
- * `budget`, `signIn` and `deploy` are deliberately NOT registered here. Each needs something a
+ * `budget` and `signIn` are deliberately NOT registered here, and `deploy` only with `newBuild`. Each needs something a
  * page cannot supply — byte counts off a built `dist/`, an app's own sign-in route, a second build
  * — so each keeps refusing with `X_TEST_FIXTURE_UNAVAILABLE` naming what it waits for.
  *
@@ -82,16 +95,23 @@ export const e2eFixtures = (page: PageLike, browser: E2eBrowserPage): E2eFixture
  */
 export function installE2eDriver(options: E2eDriverOptions): () => void {
   const page = e2ePage(options);
-  defineFixtures({ page: () => page });
+  const newBuild = options.newBuild;
+  defineFixtures({
+    page: () => page,
+    ...(newBuild === undefined ? {} : { deploy: () => ({ newBuild }) }),
+  });
   useE2eDriver((name, body: E2eBody) => {
-    bunTest(name, () => body(e2eFixtures(page, options.page)));
+    bunTest(name, () => body(e2eFixtures(page, options.page, newBuild)));
   });
   return () => {
     // Both halves, because both were installed. Putting the DECLARATION back — rather than
     // deleting the key — is what keeps a later file's `{ page }` failing as
     // `X_TEST_FIXTURE_UNAVAILABLE` (a driver is missing) instead of `X_TEST_FIXTURE_UNKNOWN`
     // (register it), which is the wrong instruction for a name the framework declares.
-    defineFixtures({ page: unavailableFixture('page') });
+    defineFixtures({
+      page: unavailableFixture('page'),
+      ...(newBuild === undefined ? {} : { deploy: unavailableFixture('deploy') }),
+    });
     resetE2eDriver();
   };
 }

package/src/e2e-errors.ts

@@ -101,3 +101,17 @@ export class E2eServiceWorkerAbsentError extends UltimateError {
     });
   }
 }
+
+/**
+ * The app an e2e run spawns (`e2e-app.ts`) did not come up: its reset, its seed, or its boot. The
+ * cause carries that process's own output, rendered, because it is the only place the reason is.
+ */
+export class E2eAppFailedError extends UltimateError {
+  constructor(input: { readonly step: string; readonly output: string }) {
+    super({
+      code: 'X_E2E_APP_FAILED',
+      cause: `${renderCauseValue(input.step)} failed for the e2e app: ${renderCauseValue(input.output)}`,
+      fix: 'x dev --json   # boot the same app by hand and read why it would not start; the e2e run used a throwaway ULTIMATE_STATE_DIR, so your own .x is untouched',
+    });
+  }
+}

package/src/e2e-page.ts

@@ -67,11 +67,14 @@ const TITLE = '(() => JSON.stringify({ title: document.title }))()';
  * The cost, stated rather than hidden: this is a SECOND request to the same route, so what it
  * measures is that route's streaming behaviour and not the byte-for-byte first chunk the open
  * document received. It runs in the page, so it carries the page's cookies and its origin — a
- * `fetch` from the test process would carry neither.
+ * `fetch` from the test process would carry neither. The reader is CANCELLED after that chunk: a
+ * streamed response nobody pulls stays open until its last hole fills, holding one of the page's
+ * six connections to its origin for the rest of the test.
  */
 const firstFlushExpression = (url: string): string =>
   `(() => fetch(${JSON.stringify(url)}, { credentials: 'same-origin' })
-    .then((response) => response.body.getReader().read())
+    .then((response) => { const reader = response.body.getReader(); return reader.read()
+      .then((chunk) => { reader.cancel().catch(() => {}); return chunk; }); })
     .then((chunk) => JSON.stringify({ html: new TextDecoder().decode(chunk.value || new Uint8Array()) })))()`;
 
 /**