@ultimat3/cli 18.0.0 → 19.0.0

package/src/messages.ts

@@ -11,6 +11,10 @@ const CATALOG = {
   'cli.commands.heading': 'commands',
   'cli.build.done': 'built {target}',
   'cli.build.failed': '{target} build failed',
+  // A build-output line, so it belongs here rather than inline beside the emitter: `x build` is a
+  // human surface and every other word it prints comes from this catalog.
+  'cli.build.pushUnwired':
+    'pwa.push is true and no VAPID key is configured, so the emitted sw.js carries no push handler',
   // `describeCron`'s vocabulary. `@ultimat3/time` is tier 1 and reaches no i18n runtime, so the
   // caller supplies the words — and the caller here is a rendered `x tasks show` line, which is
   // exactly what this catalog holds. `msg()` leaves an un-supplied `{n}`/`{time}`/`{days}`/

package/src/prerender.ts

@@ -6,7 +6,7 @@
 import { join } from 'node:path';
 import { createContext, renderThrowable, runWithContext } from '@ultimat3/core';
 import type { RouteEntry } from '@ultimat3/render';
-import { routeEntries } from '@ultimat3/render';
+import { describeRoutes, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
@@ -20,6 +20,7 @@ import { buildIslands, writeIslands } from './island-bundle';
 import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
 import { skippedRoute, skipReasonFor, writeStaticReport } from './static-report';
+import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, serviceWorkerArtifacts } from './sw-artifacts';
 
 // Re-exported, never re-declared: `static-report.ts` owns the shape because the report on disk
 // carries it, and this file already imports that module.
@@ -76,6 +77,15 @@ export interface PrerenderReport {
   readonly report: string;
   /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
   readonly islands: readonly string[];
+  /**
+   * What the service worker could not express, and what its precache manifest weighs too much of.
+   *
+   * `PrecacheManifest.warnings` had no reader anywhere in the tree — the precache budget was, in
+   * `wiki/Troubleshooting.md`'s own words, "a designed thing that is not one" (#390). An install
+   * that stalls on a bad connection is invisible on a laptop and fatal on a phone, so the number
+   * has to reach the build's own report. Empty for an app with no service worker.
+   */
+  readonly serviceWorkerWarnings: readonly string[];
 }
 
 /**
@@ -154,6 +164,18 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // wiring exists to close. `undefined` when the app is not installable, and then no document
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
+  // The worker and its registration script, written as FILES. A static host runs no route table,
+  // so a `<script src="/x-sw-register.js">` in every document is a 404 unless the bytes are in the
+  // artifact — the same promise `favicon.ico` and the icons above keep, for the asset that decides
+  // whether the export works offline at all.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
+  if (serviceWorker !== undefined) {
+    await Bun.write(join(options.out, SERVICE_WORKER_PATH.slice(1)), serviceWorker.source);
+    await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorker.register);
+  }
   if (pwa !== undefined) {
     await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
@@ -176,7 +198,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     runWithContext(ctx, () =>
       routeDocument(entry, data, {
         resolveIsland: (file: string) => islands.resolverFor(file),
-        ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+        ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       }),
     );
 
@@ -267,6 +289,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     // stdout — so the one command the finding tells an author to run printed no `unmeasured` key
     // and no reason. Written into the report is what makes the instruction true.
     unmeasured,
+    serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   });
   return {
     out: options.out,
@@ -277,5 +300,6 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     stats,
     report,
     islands: islands.chunks.map((chunk) => chunk.file),
+    serviceWorkerWarnings: serviceWorker?.warnings ?? [],
   };
 }

package/src/pwa-artifacts.ts

@@ -22,7 +22,7 @@ import { existsSync } from 'node:fs';
 // why: Bun exposes no path-join primitive, and `APP_CONFIG_FILE` is app-root-relative — the same
 // necessity `favicon.ts` and `dev-assets.ts` each record for their own root-relative constant.
 import { join } from 'node:path';
-import type { PwaColors } from '@ultimat3/core';
+import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import {
@@ -56,6 +56,15 @@ export interface PwaArtifacts {
    * no manifest is an iOS icon for an app iOS will not add.
    */
   readonly head: string;
+  /**
+   * The three `pwa` keys the SERVICE WORKER needs, carried here because this is the one module
+   * that reads an app's config file — `sw-artifacts.ts` needs the route table and the island
+   * bundle as well, and a second `await import` of `app.config.ts` would be a second answer to
+   * "what did this app declare".
+   */
+  readonly offline: PwaOfflineConfig;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
 }
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
@@ -93,6 +102,9 @@ function colorsOf(value: unknown): PwaColors | undefined {
 interface InstallableApp {
   readonly name: string;
   readonly colors: PwaColors;
+  readonly offline: PwaOfflineConfig;
+  readonly backgroundSync: boolean;
+  readonly push: boolean;
 }
 
 async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
@@ -109,9 +121,36 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
   const name = text(pwa['name']);
   const colors = colorsOf(pwa['colors']);
   if (name === undefined || colors === undefined) return undefined;
-  return { name, colors };
+  return { name, colors, offline: offlineOf(pwa['offline']), ...flags(pwa) };
+}
+
+/**
+ * The offline block, read structurally for `colorsOf`'s reason: `defineConfig` refuses
+ * `enabled: true` without an absolute `offline.fallback`, but a HAND-WRITTEN config object never
+ * passed through it. A missing or relative fallback answers `null`, and `serviceWorkerArtifacts`
+ * then emits no worker at all — never a path the framework invented, which offline would be a
+ * cached 404 answering every navigation.
+ */
+function offlineOf(value: unknown): PwaOfflineConfig {
+  const block = isRecord(value) ? value : {};
+  const fallback = text(block['fallback']);
+  const patterns = block['neverCache'];
+  return {
+    fallback: fallback?.startsWith('/') === true ? fallback : null,
+    image: text(block['image']) ?? null,
+    font: text(block['font']) ?? null,
+    neverCache: Array.isArray(patterns)
+      ? patterns.filter((entry): entry is string => typeof entry === 'string')
+      : [],
+  };
 }
 
+/** `=== true` for `enabled`'s reason: a hand-written `backgroundSync: 'yes'` wires nothing. */
+const flags = (pwa: Record<string, unknown>): { backgroundSync: boolean; push: boolean } => ({
+  backgroundSync: pwa['backgroundSync'] === true,
+  push: pwa['push'] === true,
+});
+
 /**
  * Resolved ONCE at boot, like `loadSignInPath` and `loadCacheTiers` and unlike `faviconBytes`:
  * `await import` caches the module, so re-reading per request would answer the same object at a
@@ -139,6 +178,9 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
     icons: icons?.manifestIcons ?? [],
   });
   return {
+    offline: app.offline,
+    backgroundSync: app.backgroundSync,
+    push: app.push,
     body: serializeWebManifest(result.manifest),
     head:
       `<link rel="manifest" href="${escapeAttribute(WEB_MANIFEST_PATH)}">` +

package/src/serve.ts

@@ -20,6 +20,7 @@ import {
   migrate,
 } from '@ultimat3/db';
 import type { Route } from '@ultimat3/http';
+import { describeRoutes } from '@ultimat3/render';
 import { createIsrController } from '@ultimat3/render/server';
 import { apiRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
@@ -46,6 +47,8 @@ import { readMigrations } from './migrations';
 import { startOtlpExport } from './otlp-export';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import type { RuntimeOverrides } from './runtime-overrides';
+import { serviceWorkerArtifacts } from './sw-artifacts';
+import { serviceWorkerRoutes } from './sw-routes';
 
 export const DEFAULT_PORT = 3000;
 
@@ -303,8 +306,16 @@ async function bootRoles(boot: {
   // on a laptop and absent in the image is exactly the dev/prod difference this file exists to
   // prevent, and it is the one an operator cannot see without installing the app.
   const pwa = await loadPwaArtifacts(options.root);
+  // 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.
+  const serviceWorker =
+    pwa === undefined
+      ? undefined
+      : serviceWorkerArtifacts({ pwa, buildId, routes: describeRoutes(), islands });
   const routes: readonly Route[] = [
     ...apiRoutes(),
+    ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...assetRoutes({
       root: options.root,
       storage: runtime.storage,
@@ -316,7 +327,7 @@ async function bootRoles(boot: {
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head }),
+      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
       // Only when a store was supplied. `createIsrController` defaults to a per-process memory
       // store, so twelve replicas hold twelve of them and a purge tag regenerates one twelfth of
       // the fleet while the other eleven keep serving the page it just invalidated.

package/src/static-report.ts

@@ -13,6 +13,7 @@ import { RENDER_MODES } from '@ultimat3/core';
 import type { Surface } from '@ultimat3/render';
 import { SURFACE_SPECS, SURFACES, surfaceAllows } from '@ultimat3/render';
 import type { JsonValue } from './output';
+import { SERVICE_WORKER_PATH } from './sw-artifacts';
 
 /** Beside `.x/build-stats.json`, and written by the same call — see `readStaticReport` below. */
 export const STATIC_REPORT_FILE = join('.x', 'static-report.json');
@@ -84,6 +85,15 @@ export type StaticReport = {
    * the reader.
    */
   readonly unmeasured: readonly UnmeasuredRoute[];
+  /**
+   * The service worker's own findings: a capability declared with nothing to wire it to, and a
+   * precache manifest over its byte ceiling. `PrecacheManifest.warnings` had no reader anywhere in
+   * the tree (#390), so the ceiling was — in `wiki/Troubleshooting.md`'s own words — "a designed
+   * thing that is not one". Written here for `unmeasured`'s reason: `cmd-build.ts` discards a
+   * successful subprocess's stdout, so a warning that lives only on the in-process report reaches
+   * nobody. Empty for an app with no service worker.
+   */
+  readonly serviceWorkerWarnings: readonly string[];
 };
 
 /**
@@ -177,7 +187,7 @@ const isEmitted = (value: unknown): value is EmittedPage =>
  */
 export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (!isRecord(value)) return undefined;
-  const { target, out, buildId, emitted, skipped, unmeasured } = value;
+  const { target, out, buildId, emitted, skipped, unmeasured, serviceWorkerWarnings } = value;
   if (target !== 'static' || typeof out !== 'string' || typeof buildId !== 'string') {
     return undefined;
   }
@@ -190,7 +200,25 @@ export function parseStaticReport(value: unknown): StaticReport | undefined {
   if (unmeasured !== undefined && (!Array.isArray(unmeasured) || !unmeasured.every(isUnmeasured))) {
     return undefined;
   }
-  return { target, out, buildId, emitted, skipped, unmeasured: unmeasured ?? [] };
+  // Optional on the way in for `unmeasured`'s reason, and a non-string entry drops the whole
+  // report for a malformed skip row's reason: a warning list with a hole in it is a build that
+  // says less than it measured, which is how the worker's findings went unread in the first place.
+  if (
+    serviceWorkerWarnings !== undefined &&
+    (!Array.isArray(serviceWorkerWarnings) ||
+      !serviceWorkerWarnings.every((entry) => typeof entry === 'string'))
+  ) {
+    return undefined;
+  }
+  return {
+    target,
+    out,
+    buildId,
+    emitted,
+    skipped,
+    unmeasured: unmeasured ?? [],
+    serviceWorkerWarnings: (serviceWorkerWarnings as readonly string[] | undefined) ?? [],
+  };
 }
 
 export async function writeStaticReport(root: string, report: StaticReport): Promise<string> {
@@ -232,7 +260,12 @@ export function staticReportData(report: StaticReport | undefined): Record<strin
   // which the inventory is about — `data` already carries `artifact` and the build's own id.
   return report === undefined
     ? {}
-    : { emitted: report.emitted, skipped: report.skipped, unmeasured: report.unmeasured };
+    : {
+        emitted: report.emitted,
+        skipped: report.skipped,
+        unmeasured: report.unmeasured,
+        serviceWorkerWarnings: report.serviceWorkerWarnings,
+      };
 }
 
 /**
@@ -247,6 +280,16 @@ export function renderStaticReport(report: StaticReport): readonly string[] {
     // whose budget could not be weighed is invisible in `emitted` and, when it also rendered, in
     // `skipped` too — and it is the row `X_BUDGET_UNMEASURED` sends its reader here to read.
     ...report.unmeasured.map((route) => ['unmeasured', route.path, route.reason]),
+    // The service worker's own findings, in the same three columns — a precache manifest over its
+    // byte ceiling AND a capability declared with nothing to wire it to, which is why neither the
+    // field nor this label says `precache`. `sw.js` is the one artifact that keeps serving after a
+    // deploy is over, so both are build-time facts that have to be visible in the build's own
+    // output — `PrecacheManifest` computed the first and nothing read it (#390).
+    ...report.serviceWorkerWarnings.map((warning) => [
+      'service-worker',
+      SERVICE_WORKER_PATH,
+      warning,
+    ]),
   ];
   const widths = [0, 1].map((index) =>
     Math.max(...rows.map((row) => (row[index] ?? '').length), 0),

package/src/sw-artifacts.ts

@@ -0,0 +1,162 @@
+// `sw.js` and its registration script, built from the route table and the island bundle — the one
+// caller of `@ultimat3/pwa`'s `generateServiceWorker`, which had none outside its own package
+// until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
+// file, this one needs a booted app and a finished build.
+
+import type { PrecacheAsset, PrecacheManifest, PwaRoute } from '@ultimat3/pwa';
+import { generateServiceWorker } from '@ultimat3/pwa';
+import type { RouteDescriptor } from '@ultimat3/render';
+import type { IslandBundle } from './island-bundle';
+import { msg } from './messages';
+import type { PwaArtifacts } from './pwa-artifacts';
+
+/** Root scope, so `/sw.js` and nothing under a directory — `assertScope` refuses the rest. */
+export const SERVICE_WORKER_PATH = '/sw.js';
+export const SW_SCOPE = '/';
+
+/**
+ * The registration is an EXTERNAL script, never inline, and that is a CSP fact rather than a
+ * preference: `startWeb` computes a `script-src` sha256 for each inline script it serves, so an
+ * unhashed one is blocked in the container while passing report-only under `x dev` — which is
+ * exactly how the hydration runtime shipped broken once already.
+ */
+export const SW_REGISTER_PATH = '/x-sw-register.js';
+
+export interface ServiceWorkerArtifacts {
+  /** `sw.js`, deterministic for identical input. */
+  readonly source: string;
+  /** `x-sw-register.js`, the four lines that install it. */
+  readonly register: string;
+  /** The `<script src>` tag, appended to `PwaArtifacts.head` by every surface that serves it. */
+  readonly head: string;
+  readonly precache: PrecacheManifest;
+  /** Precache budget findings — reported by `x build`, so the ceiling is not a designed thing. */
+  readonly warnings: readonly string[];
+}
+
+export interface ServiceWorkerInput {
+  /**
+   * What `loadPwaArtifacts` read out of `app.config.ts`. The whole object rather than three loose
+   * fields, because a second reader of that file is a second answer to what the app declared.
+   */
+  readonly pwa: PwaArtifacts;
+  readonly buildId: string;
+  readonly routes: readonly RouteDescriptor[];
+  readonly islands: IslandBundle;
+}
+
+/**
+ * The route table, as the service worker sees it. `api/` is dropped: an API response is a JSON
+ * document whose freshness is the app's business, and precaching one serves a stale answer to a
+ * client that had a network. Only the four fields `PwaRoute` reads cross — a descriptor carries
+ * budgets and policy flags that a browser has no use for.
+ */
+const pwaRoutes = (routes: readonly RouteDescriptor[]): readonly PwaRoute[] =>
+  // `flatMap` rather than `filter().map()`: the filter's predicate does not narrow `surface` for
+  // the map that follows it, and `PwaRoute` declares the two navigable surfaces only. A cast would
+  // hide the day a fifth surface arrives.
+  routes.flatMap((route): readonly PwaRoute[] => {
+    // `shared/` is dropped with `api/`, and for a stronger reason: it is not a URL at all — the
+    // surface exists so two routes can import one module, and a browser can never navigate to it.
+    if (route.surface !== 'site' && route.surface !== 'app') return [];
+    return [
+      {
+        path: route.path,
+        surface: route.surface,
+        mode: route.mode,
+        offline: route.offline,
+        dynamic: route.dynamic,
+      },
+    ];
+  });
+
+/**
+ * Every island chunk, precached. They are content-addressed and served `immutable`, so the
+ * revision IS the URL's hash and a byte-identical chunk across deploys is never re-downloaded.
+ *
+ * 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 islandAssets = (islands: IslandBundle): readonly PrecacheAsset[] =>
+  [...islands.chunks]
+    .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));
+
+/**
+ * Four lines, and every one of them earns it. `load` because registration competes with the page's
+ * own first paint for the same network. `scope: '/'` stated rather than inferred, so a change to
+ * where the file is served is a build-time refusal (`assertScope`) instead of a worker that
+ * silently controls a subdirectory. The `catch` because a registration that throws in a browser
+ * with service workers disabled — an incognito profile, an enterprise policy — must not take an
+ * otherwise working page down with it.
+ */
+const registerSource = (): string =>
+  `if ('serviceWorker' in navigator) {
+  addEventListener('load', function () {
+    navigator.serviceWorker
+      .register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: ${JSON.stringify(SW_SCOPE)} })
+      .catch(function (error) { console.warn('service worker registration failed', error); });
+  });
+}
+`;
+
+/**
+ * Build the worker, or answer `undefined` for an app that declared no PWA.
+ *
+ * A bad `sw.js` is sticky in a way a manifest is not: a manifest a browser dislikes is ignored, a
+ * worker that installs and caches wrong keeps serving wrong bytes until the user clears site data.
+ * That is why this landed only once a real browser could be driven —
+ * `packages/cli/e2e/service-worker.e2e.test.ts` installs the emitted worker in Chrome, takes the
+ * network away and asserts the fallback renders.
+ *
+ * `pwa.enabled` is the one switch, and it is already spent: `loadPwaArtifacts` answers `undefined`
+ * for an app that declared no PWA, so a caller only reaches this with an installable one.
+ * `defineConfig` refuses `enabled: true` without an absolute `offline.fallback`, and a
+ * hand-written config that lacks one reads as `null` here — so `requireOfflineFallback` inside
+ * `generateServiceWorker` can never be the thing that fails, and the app gets no worker rather
+ * than a worker caching a path nobody declared.
+ */
+export function serviceWorkerArtifacts(
+  input: ServiceWorkerInput,
+): ServiceWorkerArtifacts | undefined {
+  const pwa = input.pwa;
+  if (pwa.offline.fallback === null) return undefined;
+  const output = generateServiceWorker(
+    pwaRoutes(input.routes),
+    {
+      scope: SW_SCOPE,
+      swPath: SERVICE_WORKER_PATH,
+      offline: {
+        fallback: pwa.offline.fallback,
+        ...(pwa.offline.image === null ? {} : { image: pwa.offline.image }),
+        ...(pwa.offline.font === null ? {} : { font: pwa.offline.font }),
+        neverCache: pwa.offline.neverCache,
+      },
+      capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
+      assets: islandAssets(input.islands),
+    },
+    input.buildId,
+  );
+  return {
+    source: output.source,
+    register: registerSource(),
+    head: `<script src="${SW_REGISTER_PATH}" defer></script>`,
+    precache: output.precache,
+    // `output.warnings` IS `output.precache.warnings` — the generator returns the manifest's list
+    // verbatim — so it is read once, not twice. The push line is this module's own, and it is the
+    // one thing the generator cannot say: `generateServiceWorker` emits a push handler only when a
+    // VAPID key comes with the capability, and drops it in SILENCE otherwise. `pwa.push: true` in
+    // an `app.config.ts` therefore wires nothing and reports nothing, which is `jobs.driver`'s
+    // shape one package over.
+    warnings: [...output.warnings, ...pushWarning(pwa)],
+  };
+}
+
+/**
+ * `pwa.push: true` with nothing to sign a subscription with. There is no `pwa.vapid` config key
+ * yet, so today this fires for EVERY app that sets the flag — deliberately: a switch that silently
+ * does nothing is the defect this framework keeps re-shipping, and a warning naming the missing
+ * half is the smallest honest answer until the key exists.
+ */
+const pushWarning = (pwa: PwaArtifacts): readonly string[] =>
+  pwa.push ? [msg('cli.build.pushUnwired')] : [];

package/src/sw-routes.ts

@@ -0,0 +1,53 @@
+// The two GET routes that serve what `sw-artifacts.ts` built, and the cache policy each one needs.
+// Split from the emitter because mounting is HTTP and generation is a build: `prerender.ts` writes
+// both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
+
+import type { CacheHint, Route } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import type { ServiceWorkerArtifacts } from './sw-artifacts';
+import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
+
+/**
+ * `no-store`, and it is the one asset here that must be. A cached `sw.js` is a worker that cannot
+ * be replaced: the browser re-fetches it to decide whether an update exists, and an intermediary
+ * answering the old bytes pins every client to the deploy that shipped them. Browsers cap SW
+ * script caching at 24h on their own; this removes the question.
+ */
+const SW_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
+
+/** Content-addressed in neither path, so the register script gets the favicon's hour. */
+const REGISTER_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/** `/sw.js` and `/x-sw-register.js`, mounted by `x dev` and by the container alike. */
+export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly Route[] => [
+  {
+    method: 'GET',
+    path: SERVICE_WORKER_PATH,
+    meta: { name: 'pwa.serviceWorker', auth: 'public' },
+    handler: () =>
+      applyCacheHeaders(
+        new Response(artifacts.source, {
+          headers: {
+            'content-type': 'text/javascript; charset=utf-8',
+            // Without it the browser refuses to let a worker served from `/` control `/`, which
+            // is the failure `assertScope` cannot see: the scope a REGISTRATION asks for has to be
+            // allowed by the script's own response, not only by its path.
+            'service-worker-allowed': SW_SCOPE,
+          },
+        }),
+        SW_CACHE,
+      ),
+  },
+  {
+    method: 'GET',
+    path: SW_REGISTER_PATH,
+    meta: { name: 'pwa.serviceWorkerRegister', auth: 'public' },
+    handler: () =>
+      applyCacheHeaders(
+        new Response(artifacts.register, {
+          headers: { 'content-type': 'text/javascript; charset=utf-8' },
+        }),
+        REGISTER_CACHE,
+      ),
+  },
+];

package/src/templates/scaffold-app.ts

@@ -190,16 +190,63 @@ unitTest('the dashboard renders on the server, is gated, and has an offline stra
 });
 `;
 
+const offlineTest =
+  (): string => `// The offline fallback has to render with nothing: no network, no session, no database, and no
+// JavaScript. Every one of those is a config field here, and every one of them rots the moment
+// someone adds an import or a policy — at which point the page the service worker precaches is a
+// page that cannot render when it is finally needed.
+import { metaContextFor, routeDataFor } from '@ultimat3/render';
+import { expect, unitTest } from '@ultimat3/testing';
+import { config } from './page';
+
+const ctx = { params: {}, url: 'https://example.test/offline' };
+
+unitTest('the offline fallback is static, precached, and ships no JavaScript', async () => {
+  expect(config.render).toBe('static');
+  // 'precache', or the document that answers a lost network is itself fetched over the network.
+  expect(config.offline).toBe('precache');
+  expect(config.hydrate).toBe('never');
+  expect(config.budget.js).toBe('0kb');
+  // A cached error page has nothing to index, and an indexed one outranks the page it stood in for
+  // on the day the crawler happened to be offline.
+  const meta = await config.meta(metaContextFor(ctx, await routeDataFor(config, ctx)));
+  expect(meta.robots?.index).toBe(false);
+});
+`;
+
 const offlineFallback = (
   app: NameSet,
-): string => `// The offline fallback. Every app/ route with offline: 'runtime' falls back here, so a train
-// tunnel shows the product's own shell instead of the browser's error page.
+): string => `// The offline fallback, and it is a ROUTE — \`pwa.offline.fallback\` in app.config.ts names this
+// path, the generated sw.js precaches it, and every app/ route with offline: 'runtime' falls back
+// here. So a train tunnel shows the product's own shell instead of the browser's error page.
+//
+// site/ and render: 'static', deliberately: the document that answers a lost network has to render
+// with no network, no session and no database, which is what site/ guarantees and app/ (ssr |
+// stream) cannot. \`offline: 'precache'\` for the same reason one level down — a fallback fetched
+// over the network when the network is gone is not a fallback.
 
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
-import { useT } from '@${app.kebab}/i18n';
-import styles from './offline.module.scss';
+${sortedImports([
+  `import { useT } from '@${app.kebab}/i18n';`,
+  `import { defineRoute } from '@ultimat3/render';`,
+])}
+import styles from './page.module.scss';
+
+export const config = defineRoute({
+  render: 'static',
+  offline: 'precache',
+  hydrate: 'never',
+  budget: { js: '0kb' },
+  meta: ({ t }) => ({
+    title: t('app.offline.title'),
+    description: t('app.offline.description'),
+    // A cached error page has nothing to index, and an indexed one outranks the page it stood in
+    // for on the day the crawler happened to be offline.
+    robots: { index: false },
+  }),
+});
 
-export function OfflineFallback() {
+export function OfflinePage() {
   const t = useT();
 
   return (
@@ -390,8 +437,12 @@ export function appFiles(app: NameSet, example: boolean): readonly GeneratedFile
     // policy and `shared/roles.ts` declares the grants, and until this file existed nothing
     // answered "who is this?" — so every one of those routes refused every request.
     ...authFiles(app),
-    { path: 'apps/web/app/offline.tsx', contents: offlineFallback(app) },
-    { path: 'apps/web/app/offline.module.scss', contents: offlineStyle() },
+    // `site/offline/page.tsx`, not `app/offline.tsx`: the directory is the URL and `<name>.tsx` is
+    // not a route file, so the old path shipped a component nothing rendered and left `/offline` a
+    // URL the generated service worker could not fall back to.
+    { path: 'apps/web/site/offline/page.tsx', contents: offlineFallback(app) },
+    { path: 'apps/web/site/offline/page.module.scss', contents: offlineStyle() },
+    { path: 'apps/web/site/offline/page.test.ts', contents: offlineTest() },
     // The third surface, and the one call that registers what the app declares — `scaffold-api.ts`.
     ...apiFiles(example),
     { path: 'apps/web/shared/tokens.scss', contents: sharedTokens() },

package/src/templates/scaffold-repo.ts

@@ -187,7 +187,10 @@ export const config = defineConfig({
   // else in an app.
   pwa: {
     enabled: true,
-    offline: 'runtime',
+    // The document an offline navigation gets when the cache has no answer, and the path
+    // \`apps/web/site/offline/page.tsx\` serves. Required once \`enabled\` is true: an installable
+    // app that shows the browser's error page offline is the failure the block exists to prevent.
+    offline: { fallback: '/offline' },
     name: '${titleCase(app.raw)}',
     colors: {
       light: { themeColor: '#1b1f3b', backgroundColor: '#ffffff' },