@ultimat3/cli 20.2.1 → 21.0.0

package/src/live-routes.ts

@@ -12,29 +12,35 @@ import { join, posix } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
 import { ISLAND_EXTENSION, routeEntries } from '@ultimat3/render';
+import { discoverIslands } from './island-bundle';
 import type { Finding } from './output';
 
 /**
- * The exports that only work with a registered `LiveClient`. Each one either subscribes, mutates
- * or reads the connection, so a module naming one is a module that needs a browser to have booted
- * it — `hasLiveClient` and `LiveClient` itself are deliberately absent: the first IS the guard, and
- * the second is what an island's `mount()` constructs.
+ * The exports that only work in a booted browser page: each one reads the page's store, its socket
+ * or its connection, so a module naming one needs an island to have run it. `hasPageSocket` is
+ * deliberately absent — it IS the guard — and so is `installRealtime`, which the island bundle
+ * writes for the author (plan 101, slice 14).
  */
 export const LIVE_HOOKS = [
-  'useLive',
-  'liveHookFor',
+  'useQuery',
   'useConnection',
   'useMutation',
   'useMutationQueue',
+  'useRecord',
+  'useChannel',
 ] as const;
 
 /**
- * The one escape hatch, and it is a call an author writes on purpose: a module that ASKS whether
- * there is a client has already written what happens when there is none. `app/update-banner.tsx`
- * in the reference app is the shape — imported by the layout, so by every page, and correct on all
- * of them.
+ * NOT an escape hatch, `As of 2026-09-22`: `hasPageSocket()` answers false on the server, every
+ * time, so a module that guards on it and never runs in a browser renders nothing forever. It was
+ * exempted here — "a module that asks has handled the absence" — and that is exactly how
+ * `examples/dummy`'s update banner, in a layout no island imports, never showed "A new version is
+ * ready.". It is a browser-only read like any hook, so it is reported like one.
  */
-const GUARD = 'hasLiveClient';
+const GUARD = 'hasPageSocket';
+
+/** Everything that only means something in a booted browser page: the hooks, and the guard. */
+const BROWSER_ONLY: readonly string[] = [GUARD, ...LIVE_HOOKS];
 
 /** Value imports only: `import type` is erased, so it boots nothing and needs nothing. */
 const REALTIME_IMPORT = /import\s+([^;]*?)from\s*['"]@ultimat3\/realtime(?:\/[\w-]+)?['"]/g;
@@ -45,18 +51,14 @@ const bindingsOf = (clause: string): readonly string[] =>
     .map((entry) => entry.split(/\bas\b/)[0]?.trim() ?? '')
     .filter((name) => name.length > 0 && !name.startsWith('type '));
 
-/**
- * Which live hooks one module imports, or `[]` — including for a module that guards, which is a
- * per-FILE verdict on purpose: the guard is written next to the read it protects.
- */
+/** Which browser-only reads one module imports — the hooks and `hasPageSocket` — or `[]`. */
 export function liveHooksIn(source: string): readonly string[] {
   const hooks: string[] = [];
   for (const match of source.matchAll(REALTIME_IMPORT)) {
     const clause = match[1] ?? '';
     if (clause.trimStart().startsWith('type ')) continue;
     const names = bindingsOf(clause);
-    if (names.includes(GUARD)) return [];
-    for (const hook of LIVE_HOOKS) if (names.includes(hook)) hooks.push(hook);
+    for (const hook of BROWSER_ONLY) if (names.includes(hook)) hooks.push(hook);
   }
   return hooks;
 }
@@ -88,14 +90,18 @@ export interface LiveReach {
 }
 
 /**
- * Walk the route module's own import graph and answer the first live hook in it.
+ * Walk a module's own import graph and answer the first thing `probe` finds in it.
  *
  * Relative specifiers only. A bare one resolves through `node_modules` or a workspace name, and
  * following either would mean guessing which package a name came from — the limit `fix-imports.ts`
  * records for the same walk. So this UNDER-reports rather than over-reports: a finding here is
  * always a real one, which is what lets the rule ship with no pin table.
  */
-export async function liveReachOf(root: string, file: string): Promise<LiveReach | undefined> {
+export async function firstInGraph<T>(
+  root: string,
+  file: string,
+  probe: (source: string, path: string) => T | undefined,
+): Promise<T | undefined> {
   const seen = new Set<string>();
   const queue = [file];
   while (queue.length > 0) {
@@ -104,8 +110,8 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
     seen.add(next);
     const module = await readModule(root, next);
     if (module === undefined) continue;
-    const hook = liveHooksIn(module.source)[0];
-    if (hook !== undefined) return { at: module.path, hook };
+    const found = probe(module.source, module.path);
+    if (found !== undefined) return found;
     const loader = module.path.endsWith('x') ? 'tsx' : 'ts';
     // Bun's transpiler is the parser, exactly as in `scripts/boundaries.ts`: it erases type-only
     // imports and finds the dynamic ones, which no regex over this source could do.
@@ -117,6 +123,36 @@ export async function liveReachOf(root: string, file: string): Promise<LiveReach
   return undefined;
 }
 
+/** Every module in a file's relative import graph, app-root-relative — one walk, no probe. */
+export async function graphModules(root: string, file: string): Promise<ReadonlySet<string>> {
+  const seen = new Set<string>();
+  await firstInGraph(root, file, (_source, path) => {
+    seen.add(path);
+    return undefined;
+  });
+  return seen;
+}
+
+/** Every module a browser can run: the union of every island's graph in the app. */
+async function islandModules(root: string): Promise<ReadonlySet<string>> {
+  const modules = new Set<string>();
+  for (const island of await discoverIslands(root)) {
+    for (const path of await graphModules(root, island)) modules.add(path);
+  }
+  return modules;
+}
+
+/** Each module in the route's graph that reads a browser-only name, with the first name it reads. */
+async function browserOnlyReads(root: string, file: string): Promise<readonly LiveReach[]> {
+  const reads: LiveReach[] = [];
+  await firstInGraph(root, file, (source, path) => {
+    const hook = liveHooksIn(source)[0];
+    if (hook !== undefined) reads.push({ at: path, hook });
+    return undefined;
+  });
+  return reads;
+}
+
 export interface LiveRouteGap extends LiveReach {
   readonly route: string;
   readonly file: string;
@@ -132,28 +168,34 @@ const generatorFor = (file: string): string => {
 };
 
 /**
- * Every route that reads live rows with nothing to receive them. Two shapes, one condition — no
- * island at all, and an island the route declares `hydrate: 'never'` for. `X_ISLAND_NOT_HYDRATED`
- * covers the second only at render time, and only for a render that reaches the island, so a route
- * can hold the contradiction and never be asked.
+ * Every browser-only read a route's SERVER graph holds that no browser will ever run. A page's
+ * imports are server-rendered — an island is reached by a `src` string, never an import — so a
+ * module there runs in a browser only if some island's own graph imports it too. Anything else
+ * renders its server state (nothing, or `loading`) forever, at 200. `hydrate: 'never'` boots no
+ * island at all, so every read on such a route is reported. One finding per MODULE: a layout every
+ * page imports is one mistake, not one per route.
  */
 export async function liveRouteGaps(
   root: string,
   entries: readonly RouteEntry[],
 ): Promise<readonly LiveRouteGap[]> {
+  const inBrowser = await islandModules(root);
+  const reported = new Set<string>();
   const gaps: LiveRouteGap[] = [];
   for (const entry of entries) {
     if (entry.surface === 'api') continue;
-    if (entry.islands.length > 0 && entry.config.hydrate !== 'never') continue;
-    const reach = await liveReachOf(root, entry.file);
-    if (reach === undefined) continue;
-    gaps.push({
-      ...reach,
-      route: entry.path,
-      file: entry.file,
-      hydrate: entry.config.hydrate,
-      islands: entry.islands,
-    });
+    const never = entry.config.hydrate === 'never';
+    for (const read of await browserOnlyReads(root, entry.file)) {
+      if (reported.has(read.at) || (!never && inBrowser.has(read.at))) continue;
+      reported.add(read.at);
+      gaps.push({
+        ...read,
+        route: entry.path,
+        file: entry.file,
+        hydrate: entry.config.hydrate,
+        islands: entry.islands,
+      });
+    }
   }
   return gaps;
 }
@@ -161,14 +203,12 @@ export async function liveRouteGaps(
 export const liveRouteFindingFor = (gap: LiveRouteGap): Finding => ({
   code: 'X_LIVE_ROUTE_NO_ISLAND',
   cause:
-    `${gap.route} reads ${gap.hook}() (${gap.at}) and ` +
-    (gap.islands.length === 0
-      ? 'declares no island'
-      : `declares hydrate: 'never' beside ${gap.islands.join(', ')}`) +
-    ', so no module of this route ever runs in a browser: its rows have nowhere to arrive and the page renders its loading branch forever, at 200',
+    `${gap.route} reads ${gap.hook}() in ${gap.at}, which ` +
+    (gap.hydrate === 'never' ? `sits on a route declaring hydrate: 'never'` : 'no island imports') +
+    ' — so it only ever runs on the server, where it answers its server state (nothing, or loading) forever, at 200',
   fix:
-    `${generatorFor(gap.file)}, declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) above defineRoute in ${gap.file}, ` +
-    `and move the ${gap.hook}() read into its mount() — which is where setLiveClient() can be called`,
+    `move it into an island: ${generatorFor(gap.file)}, import ${gap.at} from that island's mount(), and declare it with island({ src: './${posix.basename(posix.dirname(gap.file))}${ISLAND_EXTENSION}' }) in ${gap.file}` +
+    (gap.hydrate === 'never' ? `, with a hydrate other than 'never'` : ''),
   docs: ERROR_DOCS_URL,
   at: gap.at,
 });

package/src/mcp-errors.ts

@@ -102,6 +102,7 @@ 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',
+  X_E2E_APP_FAILED: 'x dev --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.
@@ -122,6 +123,8 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
     'x errors list --json   # register the code in its package src/errors.ts, or move its row under "Reserved codes"',
   X_ERROR_CODE_UNRESOLVED:
     'x verify --json   # the finding names the file, the line and the name it could not resolve',
+  X_ERROR_CODE_UNTHROWN:
+    'x errors explain X_ERROR_CODE_UNTHROWN --json   # then mark the row "registered, thrown by nothing since <version>"',
   X_CLI_UNEXPECTED: 'x doctor --json',
   X_TYPECHECK_FAILED: 'bunx tsc -b --pretty false',
   X_LINT_FAILED: 'bunx biome check --write .',

package/src/page-sync.ts

@@ -0,0 +1,54 @@
+// What a page needs to reach the sync node, composed ONCE for `x dev` and the container alike: the
+// worker bundle and the page boot with their routes, the head a document carries (`ultimate-sync`,
+// `ultimate-build`, `ultimate-sync-worker`, the boot script), and the persisted record types a
+// private document names. One call from both boots, so the two cannot serve different targets.
+
+import { persistedRecordTypes } from '@ultimat3/entity';
+import type { Route } from '@ultimat3/http';
+import type { ClientSyncHead } from '@ultimat3/render';
+import { syncUrlFrom } from './sync-url';
+import {
+  buildPageBoot,
+  buildSyncWorker,
+  type FrameworkScript,
+  pageBootRoutes,
+  syncWorkerRoutes,
+} from './worker-bundle';
+
+export interface PageSync {
+  readonly routes: readonly Route[];
+  /** The scripts those routes serve, for the service worker to precache beside the islands. */
+  readonly scripts: readonly FrameworkScript[];
+  readonly head: ClientSyncHead;
+  /**
+   * The record types the app persists, read per render off the entity registry — the app's modules
+   * register their entities during boot, so a value captured here could predate them.
+   */
+  readonly persisted: () => readonly string[];
+}
+
+/**
+ * Built at boot and never on the watcher tick: the worker is framework code, not the app's, and a
+ * worker that changes under tabs already running it is exactly what a source-addressed URL exists
+ * to keep from happening mid-session.
+ */
+export async function pageSync(
+  root: string,
+  env: Readonly<Record<string, string | undefined>>,
+  buildId: string,
+): Promise<PageSync> {
+  const syncUrl = syncUrlFrom(env);
+  const worker = await buildSyncWorker(root);
+  const boot = await buildPageBoot(root);
+  return {
+    routes: [...syncWorkerRoutes(() => worker), ...pageBootRoutes(() => boot)],
+    scripts: [worker, boot].filter((script): script is FrameworkScript => script !== undefined),
+    head: {
+      syncUrl,
+      buildId,
+      ...(worker === undefined ? {} : { workerUrl: worker.url }),
+      ...(boot === undefined ? {} : { bootUrl: boot.url }),
+    },
+    persisted: persistedRecordTypes,
+  };
+}

package/src/realtime-browser-probe-fixture.ts

@@ -4,6 +4,6 @@
 // Bundled AND imported by `realtime-browser-barrel.test.ts` — the import is what gives it an lcov
 // record, since `Bun.build()` reads this file without evaluating it.
 
-import { useLive } from '@ultimat3/realtime';
+import { useQuery } from '@ultimat3/realtime';
 
-export const probeUseLive = useLive;
+export const probeUseQuery = useQuery;

package/src/serve.ts

@@ -48,6 +48,7 @@ import { islandRoutes } from './island-routes';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
+import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
 import { styleBundle } from './style-bundle';
@@ -363,6 +364,9 @@ async function bootRoles(boot: {
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // The page's sync target and its scripts — the same call `x dev` makes, so the two cannot differ.
+  // Before the service worker, which precaches those scripts.
+  const sync = await pageSync(options.root, options.env, buildId);
   // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
   // the one projection `x.manifest.json`, `/_x`, the sitemap and `sw.js` are all built from, so a
   // route added here cannot be missing from the precache manifest.
@@ -375,6 +379,7 @@ async function bootRoles(boot: {
           routes: describeRoutes(),
           islands,
           styles: styleBundle(),
+          scripts: sync.scripts,
         });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
@@ -393,9 +398,13 @@ async function bootRoles(boot: {
     // The surface stylesheets the documents link. Built from the registry the `loadApp` above
     // filled, so this process serves exactly the CSS it renders against.
     ...styleRoutes(() => styleBundle()),
+    // The page's one socket: its worker script, served beside the islands for their reason.
+    ...sync.routes,
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      sync: sync.head,
+      persisted: sync.persisted,
       themeHead: theme.head,
       ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory

package/src/sw-artifacts.ts

@@ -57,6 +57,12 @@ export interface ServiceWorkerInput {
    * this map does not name.
    */
   readonly documents?: ReadonlyMap<string, RenderedDocument>;
+  /**
+   * The page's framework scripts — realtime's page boot and sync worker (`pageSync(…).scripts`).
+   * Precached beside the island chunks for their reason: source-addressed and `immutable`, and an
+   * offline reload that cannot load the boot restores no record and shows the old count.
+   */
+  readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
 }
 
 /**
@@ -117,8 +123,12 @@ const pwaRoutes = (
  * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
  * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
  */
-const staticAssets = (islands: IslandBundle, styles: StyleBundle): readonly PrecacheAsset[] =>
-  [...islands.chunks, ...styles.chunks]
+const staticAssets = (
+  islands: IslandBundle,
+  styles: StyleBundle,
+  scripts: readonly { readonly url: string; readonly bytes: number }[],
+): readonly PrecacheAsset[] =>
+  [...islands.chunks, ...styles.chunks, ...scripts]
     .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
     .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
 
@@ -200,7 +210,7 @@ export function serviceWorkerArtifacts(
         neverCache: pwa.offline.neverCache,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: staticAssets(input.islands, input.styles),
+      assets: staticAssets(input.islands, input.styles, input.scripts ?? []),
     },
     input.buildId,
   );

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-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 },
+  });
+}