@ultimat3/cli 17.0.0 → 19.0.0

package/src/island-verdict.ts

@@ -27,10 +27,13 @@ export const ISLAND_SHOT_MESSAGE_KEYS = [
  * this tool cannot support — and both are properties of the port rather than of a run, which is
  * why they are a constant and not a per-run list.
  *
- * The crop one is the honest limit of the shipped browser port: `CaptureRequest` is `fullPage`
- * alone (`packages/scraping/src/page.ts`), so a picture is the VIEWPORT and the framing knob is the
- * state's own `viewport`, not a clip rectangle. The locale one is the reach of a page-side clock
- * patch: `date.toLocaleString()` resolves the zone inside the engine and never through the patched
+ * The crop one is what a rectangle still cannot see: the picture IS the component's own box now
+ * (`clipFor`, `island-shot.ts`), so what a reader loses is the surroundings — a component that
+ * overflows its box, or one whose fault is the space around it, is outside the frame. It said the
+ * opposite until 2026-08-26 — "the browser port takes no clip rectangle" — which stopped being
+ * true when the port gained `CaptureClip`, and a blind spot that names a capability the tool has
+ * is the same lie as one that hides a gap. The locale one is the reach of a page-side clock patch:
+ * `date.toLocaleString()` resolves the zone inside the engine and never through the patched
  * `Intl.DateTimeFormat`.
  */
 export const ISLAND_BLIND_SPOTS = [
@@ -54,7 +57,15 @@ export interface IslandReadiness {
   readonly mounted: boolean;
   readonly failed: string | null;
   readonly filled: boolean;
+  /** The crop target's rectangle in VIEWPORT coordinates, which is what the DOM answers. */
   readonly box: IslandBox;
+  /**
+   * The page's scroll offset at the moment the box was measured. A capture clip is in PAGE
+   * coordinates, so this is what turns one into the other — and it is a separate field rather than
+   * an addition inside the probe because `box` is published in the verdict and means the DOM's own
+   * answer there.
+   */
+  readonly scroll: { readonly x: number; readonly y: number };
 }
 
 const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
@@ -66,6 +77,7 @@ const readinessSchema: StandardSchemaV1<unknown, IslandReadiness> = t.object({
   failed: t.nullable(t.string),
   filled: t.boolean,
   box: t.object({ x: t.number, y: t.number, width: t.number, height: t.number }),
+  scroll: t.object({ x: t.number, y: t.number }),
 }) as unknown as StandardSchemaV1<unknown, IslandReadiness>;
 
 /**

package/src/mcp-errors.ts

@@ -78,6 +78,15 @@ 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',
+  // 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.
+  X_CDP_BROWSER_MISSING:
+    'x doctor --json   # or set CHROME_PATH to a Chrome binary; unset, the browser-backed suite skips',
+  X_CDP_LAUNCH_FAILED:
+    'x test e2e --json   # the cause carries the last lines of the browser\u2019s own stderr',
+  X_CDP_CALL_FAILED: 'x test e2e --json   # the cause names the DevTools call the browser refused',
+  X_CDP_TIMEOUT: 'x test e2e --json   # the cause names the call that never answered',
   X_GH_UNAVAILABLE: 'gh auth login   # install first from https://cli.github.com',
   X_GH_NOT_AUTHENTICATED: 'gh auth login',
   X_GH_COMMAND_FAILED: 'x ci --json   # the finding carries the gh invocation that failed',
@@ -168,6 +177,12 @@ const CLI_FIXES: Readonly<Record<CliErrorCode, string>> = {
   // reproduces the finding, and the finding names the file and the header line to add.
   X_MIGRATION_UNGENERATABLE:
     'x verify --only drift --json   # then add the `-- ungeneratable: <n>` header line the finding names',
+  // The edit comes first and the command re-runs it, exactly as the two schema codes above do:
+  // the cause names the query and the name that matched nothing, and `subscribes:` is a field in
+  // that query's own file. Regenerating is safe here — this refusal happens BEFORE anything is
+  // written, so there is no half-generated migration to undo.
+  X_QUERY_SUBSCRIBES_UNKNOWN:
+    'x db gen "retry after fixing subscribes" --json   # first edit subscribes: on the query the cause names',
   X_DB_MIGRATE_FAILED: 'x doctor --json   # cause carries the Postgres error verbatim',
   X_DB_BRANCH_FAILED: 'x db branch ls --json',
   X_DB_STUDIO_FAILED: 'x doctor --json',

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}`/
@@ -212,7 +216,7 @@ const CATALOG = {
   'cli.shot.island.picture': '  pictures {path}',
   'cli.shot.island.verdict': '  verdict  {path}',
   'cli.shot.island.blind.crop':
-    'the picture is the viewport, not a crop — the browser port takes no clip rectangle, so a state sizes its own frame with viewport',
+    'the picture is the crop target and nothing around it — a component that overflows its own box, or whose fault is the space beside it, is outside the frame',
   'cli.shot.island.blind.locale':
     'toLocaleString() on a Date resolves its zone inside the engine — only an explicit timeZone is pinned by this harness',
   'cli.ci.failed':

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';
@@ -17,8 +17,10 @@ import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 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.
@@ -75,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[];
 }
 
 /**
@@ -147,6 +158,32 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     join(options.out, STATIC_ERROR_PAGE),
     await errorPageDocument(options.root, NOT_FOUND_STATUS),
   );
+  // And the file every document above is about to name. A static export is served with no process
+  // behind it, so `<link rel="manifest">` resolves to a 404 unless the bytes are in the artifact —
+  // an installable app that is installable only under `x dev` is the dev/prod split this whole
+  // 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
+    // `/icons/*` entry would be a 404 in the install prompt — the manifest half of the same
+    // promise `favicon.ico` above keeps. Nothing when the app committed no source icon, which is
+    // also when the manifest names no icon.
+    await writePwaIcons(options.root, options.out);
+  }
 
   // Every render below goes through `routeDocument`, which is the function a REQUEST reaches — and
   // a request arrives inside `runWithContext`, installed by the HTTP pipeline (`dev-render.ts`).
@@ -161,6 +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 + (serviceWorker?.head ?? '') }),
       }),
     );
 
@@ -251,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,
@@ -261,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

@@ -0,0 +1,230 @@
+// The web manifest an installable app promises, and that no build had ever produced.
+//
+// `pwa.enabled` was a switch with no reader anywhere in the tree (issue #362, and
+// `scripts/lib/config-reader-pins.ts` pinned it as a `jobs.driver` candidate). `@ultimat3/pwa` has
+// shipped `generateWebManifest`, `renderThemeColorMeta`, `planIcons` and `appleTouchLinks` since it
+// existed and NOTHING called them, so every Ultimate app served a `<head>` with no
+// `<link rel="manifest">`, no `theme-color` and no apple-touch icon — and no browser has ever
+// offered to install one, however the config was written.
+//
+// WHY HERE. `dev-assets.ts`'s reason exactly: three packages declare what an installable app is and
+// none of them can read a config file off disk. This one composes tier 0's `pwa` block with tier
+// 4's generator and hands both served surfaces and the static export the same two strings.
+//
+// WHAT IT DOES NOT DO: emit a service worker. `offline`, `backgroundSync` and `push` still have no
+// build behind them — `wiki/PWA-And-Offline.md` says so — and a bad `sw.js` is sticky in a way a
+// manifest is not, so the worker lands behind a real browser check rather than beside this.
+
+// why: Bun exposes no synchronous file-existence primitive, and this read is the same one
+// `app-auth.ts` and `dev-cache.ts` each make before importing an app's config — a root with no
+// `app.config.ts` is an ordinary answer here (a scratch root, `x build` outside an app).
+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, PwaOfflineConfig } from '@ultimat3/core';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { applyCacheHeaders } from '@ultimat3/http';
+import {
+  appleTouchLinks,
+  generateWebManifest,
+  renderThemeColorMeta,
+  serializeWebManifest,
+} from '@ultimat3/pwa';
+import { escapeAttribute } from '@ultimat3/seo';
+import { APP_CONFIG_EXPORT } from './app-auth';
+import { APP_CONFIG_FILE } from './app-root';
+import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
+
+/** What a browser fetches from `<link rel="manifest">`. The spec's own extension, not `.json`. */
+export const WEB_MANIFEST_PATH = '/manifest.webmanifest';
+
+/**
+ * Short, never immutable. The path carries no content hash, so an app that changed its install
+ * title must be able to publish it — an hour is `favicon.ts`'s number, for the same asset class.
+ */
+const MANIFEST_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
+
+/** The two strings every surface needs: the file's bytes, and what `<head>` must carry to name it. */
+export interface PwaArtifacts {
+  /** `manifest.webmanifest`, serialized. */
+  readonly body: string;
+  /**
+   * `<link rel="manifest">`, both `theme-color` metas, and every apple-touch icon link. One string
+   * because a document either carries all of it or none: a manifest link with no theme colour
+   * installs an app whose status bar flashes white on every launch, and an apple-touch link with
+   * 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> =>
+  typeof value === 'object' && value !== null;
+
+const text = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.trim() !== '' ? value : undefined;
+
+/**
+ * `colors` read structurally, for `loadSignInPath`'s reason: `defineConfig` returns a plain object
+ * and a config resolved through an older core simply has no such key. `validate()` already refused
+ * a blank one an `await import` above this line, so anything this rejects is a hand-written config
+ * object — and the honest answer for one is no manifest at all, never a colour we invented.
+ */
+function colorsOf(value: unknown): PwaColors | undefined {
+  if (!isRecord(value)) return undefined;
+  const light = isRecord(value['light']) ? value['light'] : undefined;
+  const dark = isRecord(value['dark']) ? value['dark'] : undefined;
+  if (light === undefined || dark === undefined) return undefined;
+  const [lt, lb, dt, db] = [
+    text(light['themeColor']),
+    text(light['backgroundColor']),
+    text(dark['themeColor']),
+    text(dark['backgroundColor']),
+  ];
+  if (lt === undefined || lb === undefined || dt === undefined || db === undefined)
+    return undefined;
+  return {
+    light: { themeColor: lt, backgroundColor: lb },
+    dark: { themeColor: dt, backgroundColor: db },
+  };
+}
+
+/** The `pwa` block, as much of it as this file needs, or `undefined` when the app declares none. */
+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> {
+  const configPath = join(root, APP_CONFIG_FILE);
+  if (!existsSync(configPath)) return undefined;
+  const module = (await import(configPath)) as Record<string, unknown>;
+  const config = module[APP_CONFIG_EXPORT];
+  if (!isRecord(config)) return undefined;
+  const pwa = config['pwa'];
+  // `pwa.enabled`, read. Not a truthiness test: `enabled` is the key this whole file exists to
+  // give a reader, and `=== true` is what makes a hand-written `enabled: 'yes'` produce no
+  // manifest rather than one nobody asked for.
+  if (!isRecord(pwa) || pwa['enabled'] !== true) return undefined;
+  const name = text(pwa['name']);
+  const colors = colorsOf(pwa['colors']);
+  if (name === undefined || colors === undefined) return undefined;
+  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
+ * per-request cost, and the head string has to be available synchronously while a document renders.
+ */
+export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | undefined> {
+  const app = await loadInstallable(root);
+  if (app === undefined) return undefined;
+  // The icons the manifest promises are exactly the ones `/icons/*` serves and `x build` writes —
+  // ONE plan, so no surface can name a size another will not produce.
+  //
+  // AND ONLY WHEN THE APP HAS A SOURCE FOR THEM. `planIcons` answers the same fourteen entries
+  // whether `apps/web/site/icon.png` exists or not, so a manifest built off it unconditionally
+  // promises twelve icons and three apple-touch links that are twelve 404s in an install prompt —
+  // the promise-nothing-keeps shape this whole module exists to close, one level down.
+  // `examples/dummy` is exactly that app: it declares `pwa.enabled: true` and commits no icon.
+  // A missing source is NOT reported here — `x doctor` already refuses it by name with
+  // `X_PWA_ICON_MISSING`, and a second reporter of one condition is the duplication this package's
+  // own rule forbids. Read at boot, like the rest of this function: adding the file takes effect
+  // on the next start, because the manifest is generated once and served as bytes.
+  const icons = (await hasSourceIcon(root)) ? iconPlan() : undefined;
+  const result = generateWebManifest({
+    name: app.name,
+    tokens: app.colors,
+    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)}">` +
+      renderThemeColorMeta(result.themeColorMeta) +
+      (icons === undefined ? '' : appleTouchLinks(icons)),
+  };
+}
+
+/**
+ * The icon bytes a STATIC export has to carry, written under `out`. Answers the paths it wrote.
+ *
+ * A static host runs no `assetRoutes()`, so every `/icons/*` entry the manifest names is a 404
+ * unless the bytes are in the artifact — the same rule `prerenderSite` already applies to
+ * `favicon.ico` and `404.html`, one asset class further along. Nothing when the app has no source
+ * icon, which is also when the manifest names none.
+ */
+export async function writePwaIcons(root: string, out: string): Promise<readonly string[]> {
+  if (!(await hasSourceIcon(root))) return [];
+  const plan = iconPlan();
+  const render = iconRenderer(root);
+  const written: string[] = [];
+  for (const entry of plan.entries) {
+    // `outputPath` is `/icons/<file>`; `out` is the export root, so the leading slash goes.
+    await Bun.write(join(out, entry.outputPath.slice(1)), await render(plan, entry.outputPath));
+    written.push(entry.outputPath);
+  }
+  return written;
+}
+
+/**
+ * Mounted through `assetRoutes`, so `x dev` and the container serve it from one place — a surface
+ * that answers in dev and not in the image is the failure that file's own header names.
+ * Public: a browser fetches a manifest before anyone has signed in, and an installable app that
+ * needs a session to describe itself is not installable.
+ */
+export const pwaManifestRoute = (artifacts: PwaArtifacts): Route => ({
+  method: 'GET',
+  path: WEB_MANIFEST_PATH,
+  meta: { name: 'assets.manifest', auth: 'public', cache: MANIFEST_CACHE, tags: ['assets'] },
+  handler: async (_request: UltimateRequest): Promise<Response> =>
+    applyCacheHeaders(
+      new Response(artifacts.body, {
+        headers: { 'content-type': 'application/manifest+json; charset=utf-8' },
+      }),
+      MANIFEST_CACHE,
+    ),
+});

package/src/serve.ts

@@ -20,11 +20,13 @@ 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';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
+import { acceptCreatedTables } from './db-accept-created';
 import { assetRoutes } from './dev-assets';
 import { startQueue } from './dev-queue';
 import { appRoutes } from './dev-render';
@@ -43,7 +45,10 @@ import { islandRoutes } from './island-routes';
 import { DEFAULT_METRICS_PORT } from './metrics-endpoint';
 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;
 
@@ -200,7 +205,11 @@ export async function runMigrations(options: ServeOptions): Promise<MigratedApp>
       available: migrations.length,
       appVersion: report.appVersion,
     });
-    const drift = await checkDrift({ migrations });
+    // Every migration above has just been applied, so a `create table` in one of them is proof
+    // the app owns that relation — and a snapshot records only what ENTITIES declare, so without
+    // this a hand-written table is `unexpected-table` on this deploy and on every deploy after it
+    // (issue #345). Only that one difference, only for a name a migration's SQL creates.
+    const drift = acceptCreatedTables(await checkDrift({ migrations }), migrations);
     // Logged with the first difference, not just a count: a release phase's log is the only place
     // an operator sees this, and "3 differences" names nothing to act on.
     if (!drift.ok) {
@@ -293,18 +302,32 @@ async function bootRoles(boot: {
   // does from the same source — the alternative is a second bundler invocation in the image build
   // whose output nothing compares against the one the dev loop proved.
   const islands = await buildIslands(options.root);
+  // The same two strings `x dev` resolves, from the same reader: a `<link rel="manifest">` served
+  // 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,
       ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
+      ...(pwa === undefined ? {} : { pwa }),
     }),
     ...storageRoutes({ storage: runtime.storage }),
     ...islandRoutes(() => islands),
     ...appRoutes({
       buildId,
       resolveIsland: (file) => islands.resolverFor(file),
+      ...(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),