@ultimat3/cli 20.2.0 → 21.0.0

package/src/sync-url.ts

@@ -0,0 +1,31 @@
+// Where a page's one socket dials — the framework's answer, so no app owns a `sync-url.ts`. Read
+// once at boot from the deployment's env and handed to every document as `ultimate-sync`.
+
+import { ConfigInvalidError } from '@ultimat3/core';
+
+/**
+ * The sync node's own path (`createSyncNode`'s default in `@ultimat3/realtime`). Same origin by
+ * default because every rung already serves it there: `x dev` and a combined-role container mount
+ * the node on the web port, and `docker/helm`'s ingress routes `/_x/sync` to the `sync` service.
+ */
+export const SYNC_PATH = '/_x/sync';
+
+/**
+ * `SYNC_URL` verbatim when the deployment states one — the Compose rung publishes `sync` on its
+ * own port with no proxy in front, so only the deployment knows that URL — else `SYNC_PATH`,
+ * resolved by the browser against its own origin. Never derived from a port: behind any ingress a
+ * neighbouring port is a URL nothing publishes.
+ */
+export function syncUrlFrom(env: Readonly<Record<string, string | undefined>>): string {
+  const declared = env['SYNC_URL']?.trim() ?? '';
+  if (declared === '') return SYNC_PATH;
+  const parsed = URL.parse(declared);
+  if (parsed === null || (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:')) {
+    throw new ConfigInvalidError({
+      cause: 'SYNC_URL is set but is not a ws:// or wss:// URL, so no browser could dial it',
+      fix: 'export SYNC_URL="wss://sync.example.com/_x/sync"   # or unset it to dial /_x/sync on the page origin',
+      meta: { key: 'SYNC_URL' },
+    });
+  }
+  return declared;
+}

package/src/templates/resource-form-island.ts

@@ -37,6 +37,7 @@ const formIslandSource = (
 //   <${feature.pascal}Form endpoint={derivePath('create${feature.pascal}').path} locale={locale} labels={labels} />
 // A string has no import edge, so the page's bundle graph stays the page's (axiom 6).
 
+import { clientTransport } from '@ultimat3/core';
 import { Button, Form, Input, setSolidRuntime, UiProvider } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import {
@@ -71,25 +72,21 @@ type SaveState = 'idle' | 'saved' | 'failed';
  * Presentation only: the action this submits to owns validation server-side, so the form never
  * re-implements the invariant — a blank title fails at the boundary, not in the DOM.
  *
- * A plain \`fetch\` to the path the server minted, not the typed client: \`rpc()\` pulls
- * \`@ultimat3/action\` into the chunk, which is larger than everything else here put together. The
- * naming rule is still the framework's; only the transport is second.
+ * \`clientTransport\` — the framework's one browser HTTP function — to the path the server minted.
+ * Never a raw \`fetch\`: the transport is what decodes a refusal into its code, fences a sign-out,
+ * and hands any entity rows the answer carries to the page's store.
  */
 function ${feature.pascal}FormBody(props: ${feature.pascal}FormProps): JSX.Element {
   const [title, setTitle] = createSignal('');
   const [state, setState] = createSignal<SaveState>('idle');
 
-  // A rejected \`fetch\` — offline, DNS, an aborted request — is the same OUTCOME as a refused one,
-  // and it is the one \`retry\` exists for. Without the catch, \`setState\` is never reached: the
-  // status line stays empty, and the rejection escapes the \`void send()\` below as an unhandled one.
+  // A refusal and a request that never got a response both REJECT here — the transport turns a
+  // non-2xx into its code and an offline \`fetch\` into X_CLIENT_TRANSPORT_FAILED — and both are the
+  // outcome \`retry\` exists for. Without the catch the rejection escapes \`void send()\` unhandled.
   const send = async (): Promise<void> => {
     try {
-      const response = await fetch(props.endpoint, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({ title: title() }),
-      });
-      setState(response.ok ? 'saved' : 'failed');
+      await clientTransport({ method: 'POST', url: props.endpoint, body: { title: title() } });
+      setState('saved');
     } catch {
       setState('failed');
     }
@@ -198,13 +195,14 @@ beforeAll(async () => {
     // What the server rendered inside the island's wrapper. \`mount\` replaces it.
     shell: '<p>Loading</p>',
     globals: {
-      fetch: (url: string, init: { body: string }): Promise<{ ok: boolean }> => {
+      // The form sends through \`clientTransport\`, which calls \`globalThis.fetch\` — this stub.
+      fetch: (url: string, init: { body: string }): Promise<Response> => {
         calls.push({ url, body: JSON.parse(init.body) as Record<string, unknown> });
-        // What a browser rejects with when there is no network. Not a response: \`response.ok\`
-        // is never read on this path, which is exactly why the form has to catch it.
+        // What a browser rejects with when there is no network. Not a response, which is exactly
+        // why the form has to catch it.
         return networkFails
           ? Promise.reject(new TypeError('Failed to fetch'))
-          : Promise.resolve({ ok: true });
+          : Promise.resolve(Response.json({ id: 'created' }));
       },
     },
   });
@@ -221,6 +219,18 @@ afterAll(() => {
   mounted?.[Symbol.dispose]();
 });
 
+/**
+ * Until the status line changes, a bounded number of macrotasks: the send is several awaits deep
+ * inside \`clientTransport\`, so counting microtasks would pin the transport, not the form.
+ */
+async function statusSettled(): Promise<void> {
+  const before = mounted.text('[data-role="status"]');
+  for (let tick = 0; tick < 50; tick += 1) {
+    if (mounted.text('[data-role="status"]') !== before) return;
+    await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  }
+}
+
 /**
  * One mount, driven as a session: the cases below run in order against the same island, because
  * building the real chunk costs seconds and repeating it per case would pay them for state each
@@ -242,7 +252,7 @@ describe('the ${feature.kebab} form island', () => {
     // identical to a selector typo otherwise.
     expect(mounted.fire(field, 'input')).toBe(true);
     expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
-    await Promise.resolve();
+    await statusSettled();
 
     expect(calls).toEqual([{ url: ENDPOINT, body: { title: 'First ${feature.camel}' } }]);
   });
@@ -253,12 +263,11 @@ describe('the ${feature.kebab} form island', () => {
   });
 
   test('a request that never got a response still reaches retry', async () => {
-    // The outcome \`retry\` is FOR. A \`fetch\` that rejects reaches no \`response.ok\`, so without
-    // the catch in \`send\` the status line stays on its last value and the rejection escapes.
+    // The outcome \`retry\` is FOR. A \`fetch\` that rejects produces no answer, so without the
+    // catch in \`send\` the status line stays on its last value and the rejection escapes.
     networkFails = true;
     expect(mounted.fire('form', 'submit', { preventDefault: () => {} })).toBe(true);
-    await Promise.resolve();
-    await Promise.resolve();
+    await statusSettled();
 
     expect(mounted.text('[data-role="status"]')).toBe(LABELS.retry);
   });

package/src/templates/route.ts

@@ -219,6 +219,9 @@ import { e2eTest, expect } from '@ultimat3/testing';
 // \`e2eTest\` reports itself skipped, naming the command that builds what it would drive.
 e2eTest('/${path} renders offline', async ({ page, offline }) => {
   await page.goto('/${sampleUrl(path)}');
+  // \`offline()\` cuts the service worker's network too, so the reload is answered from its cache
+  // or not at all — which needs the worker in control of this page before the cut.
+  await page.waitForServiceWorker();
   await offline();
   await page.reload();
   expect(await page.title()).not.toBe('');

package/src/templates/scaffold-container.ts

@@ -112,6 +112,13 @@ coverage
 **/playwright-report
 `;
 
+/**
+ * The production env file, relative to the app root. Named once because two readers must agree:
+ * the compose file's \`env_file:\` (what the containers see) and \`x deploy\`'s \`--env-file\` (what
+ * compose interpolates \`\${VAR:?…}\` from). Two spellings would let them drift apart silently.
+ */
+export const PROD_ENV_FILE = '.env.production';
+
 const composeProd = (
   app: NameSet,
 ): string => `# The production topology: one service per role, one image, differing only by ROLE and replicas.
@@ -119,6 +126,12 @@ const composeProd = (
 #
 #   IMAGE=ghcr.io/you/${app.kebab}:1.2.3 x deploy --image ghcr.io/you/${app.kebab}:1.2.3
 #
+# By hand, always with \`--env-file ${PROD_ENV_FILE}\`: Compose fills \`\${VAR:?…}\` below from the shell
+# and \`--env-file\` only, NEVER from \`env_file:\`, so without it a value set only in that file is
+# "missing" and the parse fails. \`x deploy\` passes it on every step.
+#
+#   docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d
+#
 # A published host port has exactly one binder, so \`web\` and \`sync\` run at 1 here. Compose is one
 # box; horizontal scaling of those two belongs to an orchestrator — \`docker/helm\`, beside this
 # file, is the chart \`x deploy --method helm\` installs. To scale them on one box anyway, drop
@@ -128,7 +141,7 @@ name: ${app.kebab}
 
 x-image: &image
   image: \${IMAGE:-${app.kebab}:dev}
-  env_file: [../.env.production]
+  env_file: [../${PROD_ENV_FILE}]
   restart: unless-stopped
   stop_grace_period: 30s # SIGTERM → drain in-flight requests, jobs and sockets
   depends_on:
@@ -193,7 +206,9 @@ services:
 
   web:
     <<: *image
-    environment: [ROLE=web]
+    # The page dials SYNC_URL; unset, it dials /_x/sync on :3000, which web does not serve here.
+    # Set it in ${PROD_ENV_FILE}: \`--env-file\` (header) is what lets this line read it there.
+    environment: [ROLE=web, 'SYNC_URL=\${SYNC_URL:?set SYNC_URL=ws://<host>:3001/_x/sync, see wiki/Deployment.md}']
     depends_on:
       db: { condition: service_healthy }
       migrate: { condition: service_completed_successfully }
@@ -276,7 +291,7 @@ docker run -p 3000:3000 -e DATABASE_URL=postgres://... ${app.kebab}:dev
 ## One box, every role
 
 \`\`\`sh
-docker compose -f docker/docker-compose.prod.yml up -d      # db → migrate → the rest
+docker compose --env-file ${PROD_ENV_FILE} -f docker/docker-compose.prod.yml up -d   # db → migrate → the rest
 x deploy --image ${app.kebab}:dev --dry-run --json           # the same plan, printed
 \`\`\`
 

package/src/templates/scaffold-dashboard-shared.ts

@@ -17,10 +17,13 @@ export const routeConfig = (load: string): string => `export const config = defi
   // Auth is a policy, never a route-local flag: one authz system, evaluated everywhere.
   policy: { permission: 'dashboard:read' },
   // Only the toggle island hydrates; the tiles, the chart and the table are server markup. The
-  // island measured 60.9kb minified under Bun 1.4.2 — solid-js is 12.6kb of it, the catalog's
-  // toggle, provider and the ui runtime they share are the rest — so 64kb is that figure plus
-  // the few hundred bytes the minifier moves between Bun patch versions, not headroom to spend.
-  budget: { js: '64kb' },${load}
+  // island measured 34.0kb minified under Bun 1.4.0 (37.0kb under 1.4.2, which honours
+  // \`sideEffects\` and keeps core's declared modules) — solid-js is 15.1kb of it, the catalog's
+  // toggle, provider, the ui runtime they share and the error registry are the rest. It was
+  // 60.9kb before the framework stopped shipping solid-js twice and the i18n catalog with it
+  // (issue #490), which is what put this at 64kb; 60kb is the figure the scaffold budgets held
+  // before that, kept rather than tightened so a Bun patch cannot red a first \`bin/check\`.
+  budget: { js: '60kb' },${load}
   meta: ({ t }) => ({
     title: t('app.dashboard.title'),
     description: t('app.dashboard.description'),
@@ -69,6 +72,6 @@ unitTest('the dashboard renders on the server, is gated, and has an offline stra
 
 unitTest('the dashboard hydrates its one island inside a stated budget', () => {
   expect(config.hydrate).toBe('visible');
-  expect(config.budget.js).toBe('64kb');
+  expect(config.budget.js).toBe('60kb');
 });
 `;

package/src/templates/scaffold-env.ts

@@ -29,6 +29,12 @@ export const SCAFFOLD_ENV_SCHEMA = {
     role: 'sync',
     description: 'Realtime fan-out cluster. Only the sync role is asked for it.',
   },
+  SYNC_URL: {
+    type: 'string',
+    required: false,
+    role: 'web',
+    description: 'Where a page dials the sync socket. Compose: ws://<host>:3001/_x/sync',
+  },
   SESSION_SECRET: {
     type: 'string',
     required: false,

package/src/verify-e2e.ts

@@ -0,0 +1,38 @@
+// What the gate's `e2e` step does around the suite in an APP: when this machine has a browser, it
+// runs the suite with the e2e preload and names the app root, and the PRELOAD spawns the app — so
+// the app lives in the test process, where `deploy.newBuild()` can restart it. No browser, or not an
+// app: the suite runs as before and its browser-backed cases skip — or refuse under
+// `E2E_BROWSER_REQUIRED=1`.
+
+// why: Bun exposes no path API — the preload is addressed by an absolute path the child resolves.
+import { join } from 'node:path';
+import { findChrome } from './cdp-launch';
+import { E2E_ROOT_ENV } from './e2e-browser-handle';
+import type { ExecResult } from './exec';
+
+/** The preload `bun test` is handed, beside the app's own from `bunfig.toml`. */
+export const E2E_PRELOAD = join(import.meta.dir, 'e2e-preload.ts');
+
+export interface E2eRun {
+  readonly command: readonly string[];
+  readonly env: Readonly<Record<string, string | undefined>>;
+}
+
+/** Wrap one e2e `bun test` invocation: `run` receives the command and extra environment to use. */
+export async function withE2eApp(
+  input: {
+    readonly root: string;
+    readonly isApp: boolean;
+    readonly command: readonly string[];
+    readonly env: Readonly<Record<string, string | undefined>>;
+  },
+  run: (e2e: E2eRun) => Promise<ExecResult>,
+): Promise<ExecResult> {
+  const chrome = input.isApp ? await findChrome(Bun.env) : undefined;
+  if (chrome === undefined) return run({ command: input.command, env: input.env });
+  const [bun = 'bun', test = 'test', ...rest] = input.command;
+  return run({
+    command: [bun, test, '--preload', E2E_PRELOAD, ...rest],
+    env: { ...input.env, [E2E_ROOT_ENV]: input.root },
+  });
+}

package/src/verify-run.ts

@@ -14,7 +14,7 @@ import {
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 
 /**
- * Run every step in order, never bailing early: an agent fixing three things at once needs all
+ * Run every step, never bailing early: an agent fixing three things at once needs all
  * three findings from one run, not one per round-trip.
  *
  * `ctx.only` narrows the list to one step. The narrowing lives HERE rather than in `cmd-verify.ts`
@@ -26,61 +26,43 @@ export async function runVerify(
   ctx: VerifyContext,
 ): Promise<CommandResult> {
   const floor = await readVerifyFloor(ctx.root);
-  const results: StepResult[] = [];
   const selected = ctx.only === undefined ? steps : steps.filter((step) => step.name === ctx.only);
+  const byName = new Map<string, StepResult>();
+  const began = performance.now();
+  // The static steps wait for the serial suites and then run BESIDE them — only when `live` is in
+  // the list, so a one-step run (`--only`) and a list with no serial suite keep today's order.
+  const overlapping = selected.some((step) => step.name === SERIAL_SUITES[0]);
+  const beside = overlapping ? selected.filter((step) => BESIDE_SERIAL_SUITES.has(step.name)) : [];
+  let pending: Promise<void> | undefined;
+  const join = async (): Promise<void> => {
+    await pending;
+    pending = undefined;
+  };
   for (const step of selected) {
-    const applies = step.applies === undefined ? true : await step.applies(ctx);
-    if (!applies) {
-      // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
-      // that claim, committed — so "nothing to check" now means the suite was deleted, and the
-      // gate says so on the step's own line rather than counting one more thing not to worry
-      // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
-      // the summary, `data.failed`, and the reference-app gate's own red list.
-      const required = floorRequires(floor, step.name);
-      results.push({
-        name: step.name,
-        ok: !required,
-        durationMs: 0,
-        skipped: !required,
-        findings: required ? [vanishedSuiteFinding(step.name)] : [],
-      });
-      continue;
+    if (beside.includes(step)) continue;
+    if (step.name === SERIAL_SUITES[0]) {
+      pending = Promise.all(
+        beside.map(async (other) => {
+          byName.set(other.name, await runStep(other, ctx, floor));
+        }),
+      ).then(() => undefined);
+    } else if (!SERIAL_SUITES.includes(step.name)) {
+      await join();
     }
-    const started = performance.now();
-    const outcome = await step.run(ctx).catch(
-      (error: unknown): StepOutcome => ({
-        ok: false,
-        findings: [findingOf(error, step.name)],
-      }),
-    );
-    // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
-    // over an all-skipped file, so the counts are the only channel that can tell the two apart.
-    // ONE definition of "nothing ran", read twice, because the floor decides which of the two
-    // things it means — exactly as it already does for a step whose `applies` said no.
-    const tests = outcome.tests;
-    const nothingRan = tests !== undefined && tests.ran === 0;
-    const required = floorRequires(floor, step.name);
-    // A step the floor requires whose suite executed nothing is the same vanished suite as a step
-    // with no files at all — the run just had to finish before it could be seen. Appended to the
-    // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
-    const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
-    results.push({
-      name: step.name,
-      ok: outcome.ok && vanished.length === 0,
-      durationMs: Math.round(performance.now() - started),
-      // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
-      // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
-      // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
-      skipped: nothingRan && !required,
-      findings: [...outcome.findings, ...vanished],
-      ...(outcome.output === undefined ? {} : { output: outcome.output }),
-      ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
-      ...(tests === undefined ? {} : { tests }),
-    });
+    byName.set(step.name, await runStep(step, ctx, floor));
   }
+  await join();
+  // Reported in the declared order, whatever order the steps finished in: the table, `--json` and
+  // every gate parsing either read the same sequence they always did.
+  const results = selected.flatMap((step) => {
+    const result = byName.get(step.name);
+    return result === undefined ? [] : [result];
+  });
   const failedSteps = results.filter((step) => !step.ok).map((step) => step.name);
   const skippedSteps = results.filter((step) => step.skipped === true).map((step) => step.name);
-  const totalMs = results.reduce((sum, step) => sum + step.durationMs, 0);
+  // WALL time, not the sum of step times: with steps overlapping, the sum overstates what a run
+  // costs, and the wall clock is the number a CI job waits on.
+  const totalMs = Math.round(performance.now() - began);
   const summary = verifySummary({
     results,
     failed: failedSteps,
@@ -139,6 +121,79 @@ function verifySummary(input: {
   return msg(clean ? 'cli.verify.fail' : 'cli.verify.failSkipped', params);
 }
 
+/**
+ * `x verify`'s wall time was the SUM of 20 serial steps (#14, the DX ledger): measured locally, 395s,
+ * of which `lint`, `boundaries`, `filesize`, `package-shape` and `errors` were 127s spent while
+ * nothing else ran. They read the tree and write nothing a later step reads (`lint` is biome over
+ * files; the rest are in-process scans), so they run BESIDE the serial suites — `live` and `e2e`
+ * are one worker each, Postgres- and browser-bound, and mostly waiting. `typecheck` stays first
+ * and alone: `tsc -b` writes `.tsbuildinfo` and `dist/`, and `unit` saturates every core.
+ */
+export const BESIDE_SERIAL_SUITES: ReadonlySet<string> = new Set([
+  'lint',
+  'boundaries',
+  'filesize',
+  'package-shape',
+  'errors',
+]);
+
+/** The consecutive run of steps the static group overlaps, in the order `VERIFY_STEP_NAMES` holds. */
+export const SERIAL_SUITES: readonly string[] = ['live', 'job', 'e2e', 'eval'];
+
+async function runStep(
+  step: VerifyStep,
+  ctx: VerifyContext,
+  floor: Awaited<ReturnType<typeof readVerifyFloor>>,
+): Promise<StepResult> {
+  const applies = step.applies === undefined ? true : await step.applies(ctx);
+  if (!applies) {
+    // A skip this repo already ruled out is not a skip. The step ran here before — the floor is
+    // that claim, committed — so "nothing to check" now means the suite was deleted, and the
+    // gate says so on the step's own line rather than counting one more thing not to worry
+    // about. Recorded as failed and NOT as skipped, so every reader of a step table sees it:
+    // the summary, `data.failed`, and the reference-app gate's own red list.
+    const required = floorRequires(floor, step.name);
+    return {
+      name: step.name,
+      ok: !required,
+      durationMs: 0,
+      skipped: !required,
+      findings: required ? [vanishedSuiteFinding(step.name)] : [],
+    };
+  }
+  const started = performance.now();
+  const outcome = await step.run(ctx).catch(
+    (error: unknown): StepOutcome => ({
+      ok: false,
+      findings: [findingOf(error, step.name)],
+    }),
+  );
+  // A suite that executed nothing did not run, whatever its exit code says: `bun test` exits 0
+  // over an all-skipped file, so the counts are the only channel that can tell the two apart.
+  // ONE definition of "nothing ran", read twice, because the floor decides which of the two
+  // things it means — exactly as it already does for a step whose `applies` said no.
+  const tests = outcome.tests;
+  const nothingRan = tests !== undefined && tests.ran === 0;
+  const required = floorRequires(floor, step.name);
+  // A step the floor requires whose suite executed nothing is the same vanished suite as a step
+  // with no files at all — the run just had to finish before it could be seen. Appended to the
+  // step's own findings so `data.failed`, the counts and every gate reading this table carry it.
+  const vanished = nothingRan && required ? [skippedSuiteFinding(step.name, tests.skipped)] : [];
+  return {
+    name: step.name,
+    ok: outcome.ok && vanished.length === 0,
+    durationMs: Math.round(performance.now() - started),
+    // Without a floor to require it, a suite that ran nothing is a SKIP and not a pass (#434):
+    // the `e2e` step printed `✓ e2e 46ms` over its one skipped test, which is the one thing a
+    // step table may never do — a reader cannot tell a lane that ran from a lane that did not.
+    skipped: nothingRan && !required,
+    findings: [...outcome.findings, ...vanished],
+    ...(outcome.output === undefined ? {} : { output: outcome.output }),
+    ...(outcome.workers === undefined ? {} : { workers: outcome.workers }),
+    ...(tests === undefined ? {} : { tests }),
+  };
+}
+
 function findingOf(error: unknown, step: string): Finding {
   // A step may throw anything, including an Error that fights being read: `instanceof` runs a
   // Proxy's `getPrototypeOf` trap and `.message` runs a getter, so a hostile throw would take the

package/src/verify-tests.ts

@@ -19,6 +19,7 @@ import { testEnvOverrides } from './test-dotenv';
 import type { TestFile } from './test-select';
 import { discoverTests } from './test-select';
 import { defaultWorkers } from './test-workers';
+import { withE2eApp } from './verify-e2e';
 import type { StepOutcome, VerifyContext, VerifyStep } from './verify-step';
 import { fromExec, fromFindings } from './verify-step';
 import { runParallel } from './verify-test-run';
@@ -162,6 +163,12 @@ const ignoreFlags = (patterns: readonly string[]): readonly string[] =>
 export const typeFiltersOf = (type: Exclude<TestType, 'unit'>): readonly string[] =>
   OWNERSHIP.filter(([owner]) => owner === type).map(([, filter]) => filter);
 
+/**
+ * An e2e test's own budget: a first navigation waits on `x dev` compiling the route and its island,
+ * which bun's default 5 s does not cover — a timeout there reads as an app bug that is not one.
+ */
+export const E2E_TEST_TIMEOUT_MS = 60_000;
+
 /** Unit is everything the typed suites do not claim, so no test can fall between two steps. */
 export const testStepCommand = (type: TestType): readonly string[] =>
   type === 'unit'
@@ -173,6 +180,7 @@ export const testStepCommand = (type: TestType): readonly string[] =>
     : [
         'bun',
         'test',
+        ...(type === 'e2e' ? [`--timeout=${String(E2E_TEST_TIMEOUT_MS)}`] : []),
         ...ignoreFlags([...NEVER_A_TEST, ...disownedBy(type)]),
         ...typeFiltersOf(type),
       ];
@@ -203,10 +211,19 @@ export const resetTestDiscovery = (): void => discovered.clear();
 const runSerial = async (ctx: VerifyContext, type: TestType): Promise<StepOutcome> => {
   const command = testStepCommand(type);
   const envOverrides = testEnvOverrides(ctx.root, ctx.env ?? Bun.env);
-  const result = await ctx.runner(command, {
-    cwd: ctx.root,
-    ...(Object.keys(envOverrides).length === 0 ? {} : { env: envOverrides }),
-  });
+  const exec = (e2e: { command: readonly string[]; env: typeof envOverrides }) =>
+    ctx.runner(e2e.command, {
+      cwd: ctx.root,
+      ...(Object.keys(e2e.env).length === 0 ? {} : { env: e2e.env }),
+    });
+  // The e2e step drives a real browser against the app it spawns, when this machine has one.
+  const result =
+    type === 'e2e'
+      ? await withE2eApp(
+          { root: ctx.root, isApp: isApp(ctx.root), command, env: envOverrides },
+          exec,
+        )
+      : await exec({ command, env: envOverrides });
   return {
     ...fromExec(result, {
       code: 'X_TEST_FAILED',