@ultimat3/cli 23.0.0 → 25.0.0

package/src/serve-retire.ts

@@ -0,0 +1,95 @@
+// `ROLE=worker`'s retire, on SIGUSR2 (issue #669): stop claiming, finish every held job however
+// long it takes, abort nothing — then the ordinary drain, so the process exits 0. It is what a
+// Kubernetes `preStop` sends before the SIGTERM a rollout ends in, for a job whose side effect may
+// happen at most once and may outlast `drain.deadlineMs`. Framework-owned: no port, no app code.
+
+import { drain, logger, renderThrowable } from '@ultimat3/core';
+import type { Worker } from '@ultimat3/jobs';
+
+/** The signal a worker retires on. Free in Bun and Node (SIGUSR1 is the inspector's). */
+export const RETIRE_SIGNAL = 'SIGUSR2';
+
+/** The two calls a retire makes on the worker. */
+export type RetiringWorker = Pick<Worker, 'stats' | 'stop'>;
+
+/** Where the signal is heard — `process` by default, a hand-raised source in a test. */
+export interface RetireSignals {
+  on(signal: typeof RETIRE_SIGNAL, listener: () => void): void;
+  off(signal: typeof RETIRE_SIGNAL, listener: () => void): void;
+}
+
+export interface WorkerRetireOptions {
+  /** Default `process.platform`. `win32` installs nothing: Windows has no SIGUSR2. */
+  readonly platform?: string;
+  readonly signals?: RetireSignals;
+  /** What the retire ends in. Default core's `drain` — the hold then releases and exits 0. */
+  readonly drain?: (signal: string) => Promise<void>;
+}
+
+export interface WorkerRetire {
+  /** The worker the boot started (`null` when it started none) — a signal before this waits. */
+  adopt(worker: RetiringWorker | null): void;
+  /** Give the listener back: a boot that failed, or a hold that is over. */
+  disarm(): void;
+}
+
+const NOTHING: WorkerRetire = Object.freeze({ adopt: () => undefined, disarm: () => undefined });
+
+/**
+ * Listen for `RETIRE_SIGNAL` NOW, before the boot: Bun's default for an unhandled SIGUSR2 ends the
+ * process, so a `preStop` that lands while the pod still boots must meet this listener, which waits
+ * for the worker and then retires it. One retire per process; a second signal joins it.
+ *
+ * Exits rather than holds, decided 2026-10-07: the `preStop` has no channel back but PID 1 itself,
+ * so "retired" has to be observable as "PID 1 is gone" — and a pod that has stopped claiming serves
+ * nothing it could keep holding for. A SIGTERM landing mid-retire is the ordinary drain: it binds
+ * the retire to `drain.deadlineMs` and cuts off at the margin (`packages/jobs/src/worker.ts`).
+ */
+export function armWorkerRetire(options: WorkerRetireOptions = {}): WorkerRetire {
+  if ((options.platform ?? process.platform) === 'win32') return NOTHING;
+  const signals: RetireSignals = options.signals ?? process;
+  const finish = options.drain ?? drain;
+  let adopt: (worker: RetiringWorker | null) => void = () => undefined;
+  const adopted = new Promise<RetiringWorker | null>((resolve) => {
+    adopt = resolve;
+  });
+  let retiring = false;
+
+  const retire = async (): Promise<void> => {
+    const worker = await adopted;
+    try {
+      if (worker !== null) {
+        const before = await worker.stats();
+        logger.info('jobs.worker.retiring', {
+          signal: RETIRE_SIGNAL,
+          workerId: before.workerId,
+          inFlight: before.inFlight,
+        });
+        await worker.stop(RETIRE_SIGNAL);
+        const after = await worker.stats();
+        logger.info('jobs.worker.retired', {
+          signal: RETIRE_SIGNAL,
+          workerId: after.workerId,
+          state: after.state,
+          inFlight: after.inFlight,
+        });
+      }
+    } catch (error) {
+      logger.warn('jobs.worker.retire-failed', { error: renderThrowable(error) });
+    } finally {
+      await finish(RETIRE_SIGNAL);
+    }
+  };
+
+  const listener = (): void => {
+    if (retiring) return;
+    retiring = true;
+    // Never rejects: `retire` catches its own failure and always reaches the drain.
+    void retire();
+  };
+  signals.on(RETIRE_SIGNAL, listener);
+  return {
+    adopt: (worker) => adopt(worker),
+    disarm: () => signals.off(RETIRE_SIGNAL, listener),
+  };
+}

package/src/serve-web.ts

@@ -4,21 +4,23 @@
 // spared: render's server half, the PWA, SEO, MCP and island subsystems.
 
 import type { Route } from '@ultimat3/http';
-import { describeRoutes } from '@ultimat3/render';
-import { createIsrController } from '@ultimat3/render/server';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
+
+import { describePages } from '@ultimat3/render';
 import { apiMountRoutes, apiRoutes, pagePostRoutes } from './api-routes';
 import { loadSignInPath } from './app-auth';
 import { mountAppMcp } from './app-mcp';
-import { errorPageStyleSources } from './error-page-csp';
+import { errorPageStyleBodies } from './error-page-csp';
 import { islandRoutes } from './island-routes';
 import type { LoadedIslands } from './island-store';
 import { loadOrBuildIslands } from './island-store';
 import { loadNavigation, pageNavigation } from './page-navigation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { adminMountRoutes } from './runtime-admin';
 import { assetRoutes } from './runtime-assets';
+import { attachedIsr } from './runtime-isr';
 import { appRoutes } from './runtime-render';
 import type { RunningServices } from './runtime-services';
 import { servedStorage, storageRoutes } from './runtime-storage';
@@ -30,18 +32,21 @@ import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
 import { serviceWorkerRoutes } from './sw-routes';
 import { loadThemeMode, themeBoot } from './theme-boot';
+import { loadThemeBrand } from './theme-brand';
 
 /** Everything `startRoles` is handed that only a process serving documents has. */
 export interface WebSurface {
   readonly routes: readonly Route[];
   /** The theme boot and the speculation rules: the two inline bodies every document may carry. */
   readonly inlineScripts: readonly string[];
-  /** The app's own error pages' `<style>` bodies, which the enforced policy must admit. */
+  /** The app's error pages' and its brand's `<style>` bodies, which the enforced policy admits. */
   readonly inlineStyles: readonly string[];
   /** Where a browser that opened a guarded page is sent — the declaration `x dev` reads. */
   readonly signInPath: string | null;
   /** Present when this boot built the islands itself: how many chunks, and why not the store. */
   readonly islandsBuilt?: LoadedIslands['built'];
+  /** Detaches the ISR controller from `invalidateTags` — on the boot's stop list. */
+  readonly release: () => void;
 }
 
 export async function webSurface(
@@ -58,6 +63,8 @@ export async function webSurface(
   // 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 app's brand (`apps/web/shared/theme.ts`), or nothing: the same reader `x dev` calls.
+  const brand = await loadThemeBrand(options.root);
   // `site.origin` and `seo.robots.disallow`: the absolute URLs every document and the sitemap carry.
   const site = await loadSiteSettings(options.root);
   const origin = publicOrigin(options.env, site);
@@ -71,8 +78,9 @@ export async function webSurface(
   const speculation = pageSpeculation({
     config: await loadSpeculation(options.root),
     client: declared.surfaces,
+    localeSegments: otherLocaleSegments(await appLocaleSet(options.root)),
   });
-  // The worker, from the SAME route table this process is about to serve — `describeRoutes()` is
+  // The worker, from the SAME route table this process is about to serve — `describePages()` 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 =
@@ -81,7 +89,7 @@ export async function webSurface(
       : serviceWorkerArtifacts({
           pwa,
           buildId,
-          routes: describeRoutes(),
+          routes: describePages(),
           islands,
           styles: styleBundle(),
           scripts: [
@@ -93,6 +101,13 @@ export async function webSurface(
   const mcpMount = await mountAppMcp(options.root);
   // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
   const served = servedStorage(runtime.storage);
+  // Attached, so a tag bust marks this process's ISR pages stale. The store is the deployment's
+  // when it supplied one: the default is per process, so twelve replicas hold twelve of them and a
+  // purge regenerates one twelfth of the fleet while the other eleven keep the invalidated page.
+  const isr = attachedIsr({
+    buildId,
+    ...(options.runtime?.isrStore === undefined ? {} : { store: options.runtime.isrStore }),
+  });
   const routes: readonly Route[] = [
     ...apiRoutes(),
     // The bearer doors onto a cut of the same routes (`defineApi({ http: { mounts } })`), counted
@@ -126,6 +141,7 @@ export async function webSurface(
     ...adminMountRoutes({
       buildId: buildId,
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(origin === undefined ? {} : { origin }),
     }),
     ...appRoutes({
@@ -135,6 +151,7 @@ export async function webSurface(
       persisted: sync.persisted,
       ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
       themeHead: theme.head,
+      ...(brand === undefined ? {} : { brandHead: brand.head }),
       ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
       // A `static` page is the same bytes for every request of this process: rendered once.
       memoStatic: true,
@@ -142,23 +159,22 @@ export async function webSurface(
       ...(pwa === undefined
         ? {}
         : { pwaHead: (locale: string) => pwa.headFor(locale) + (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.
-      ...(options.runtime?.isrStore === undefined
-        ? {}
-        : { isr: createIsrController({ buildId, store: options.runtime.isrStore }) }),
+      isr: isr.isr,
     }),
   ];
   return {
     routes,
     inlineScripts: [theme.cspSource, ...(speculation === undefined ? [] : [speculation.cspSource])],
     // The enforced policy this process sends must admit the app's own error pages' `<style>` and
-    // the theme boot the documents carry; `x dev` is report-only, so only here was it a blank page.
-    inlineStyles: await errorPageStyleSources(options.root),
+    // the brand's; `x dev` is report-only, so only here was a missing hash an unstyled page.
+    inlineStyles: [
+      ...(await errorPageStyleBodies(options.root)),
+      ...(brand === undefined ? [] : [brand.style]),
+    ],
     // Same declaration `x dev` reads. Without it a container answers a browser that opened a
     // guarded page with the problem document, rendered as raw JSON in the viewport.
     signInPath: await loadSignInPath(options.root),
     ...(islandsBuilt === undefined ? {} : { islandsBuilt }),
+    release: isr.release,
   };
 }

package/src/serve.ts

@@ -5,10 +5,10 @@
 // interface — every one by default, because a container is reached through a port mapping.
 
 import { assertNoDevSecretsOutsideLocal, logger } from '@ultimat3/core';
-import { assertNoDrift, checkDrift, migrate } from '@ultimat3/db';
+import { assertNoSchemaDrift, checkDrift, migrate } from '@ultimat3/db';
 import { loadAppRuntime } from './app-runtime';
 import { acceptCreatedTables } from './db-accept-created';
-import { holdUntilShutdown } from './hold';
+import { type BootedHold, holdWhileBooting } from './hold';
 import { startMetricsEndpoint } from './metrics-endpoint';
 import { readMigrations } from './migrations';
 import { resolveServices } from './runtime-bindings';
@@ -174,19 +174,36 @@ export async function runRole(input: ServeOptions): Promise<StartedApp> {
     // returned. `x db migrate` calls the same `runMigrations` and renders every difference as a
     // finding before exiting non-zero; a container that logged one and exited 0 would let the
     // deploy roll on over a schema nobody can reconstruct, which is the failure drift exists for.
-    assertNoDrift(migrated.drift);
+    assertNoSchemaDrift(migrated.drift);
     return migrated;
   }
-  const app = await serveApp({ ...options, role });
-  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  // The drain's handlers BEFORE the boot (`holdWhileBooting`): the worker claims inside
+  // `startRoles`, so a SIGTERM during boot has to be a drain of what started, never Bun's kill.
   // `exit` because this is the one entry point with nothing above it: `bin.ts` ends in
   // `process.exit(code)` and `apps/web/server.ts` — which is what awaits this — does not. One
   // non-unref'd interval anywhere in the app then holds an event loop that has nothing left to do,
   // until `terminationGracePeriodSeconds` runs out and the kubelet SIGKILLs a drained process.
-  await holdUntilShutdown('serve', () => app.stop(), {
-    exit: (code) => {
-      process.exit(code);
-    },
-  })();
+  //
+  // A worker also retires on SIGUSR2 (`serve-retire.ts`) — armed before the boot for the same
+  // reason: Bun's default for an unhandled SIGUSR2 ends the process, and a `preStop` may land
+  // while the pod still boots. The retire ends in the same drain, so the same hold exits 0.
+  // Behind `await import()`, as the serving graph is: `ROLE=migrate` never loads it.
+  const retire = role === 'worker' ? (await import('./serve-retire')).armWorkerRetire() : undefined;
+  let booted: BootedHold<ServedApp>;
+  try {
+    booted = await holdWhileBooting('serve', () => serveApp({ ...options, role }), {
+      exit: (code) => {
+        retire?.disarm();
+        process.exit(code);
+      },
+    });
+  } catch (error) {
+    retire?.disarm();
+    throw error;
+  }
+  const { app, hold } = booted;
+  retire?.adopt(app.running.worker);
+  logger.info('ultimate started', { role: app.role, url: app.url, buildId: app.buildId });
+  await hold();
   return app;
 }

package/src/server-barrels.ts

@@ -27,9 +27,12 @@ export interface BarrelImport {
   readonly entry: string;
 }
 
-/** `import` / `export … from` / `import()` of a VALUE from the barrel. `import type` runs nothing. */
+/**
+ * `import` / `export … from` / `import()` of a VALUE from the barrel, and the side-effect
+ * `import '…'` that binds nothing yet evaluates the whole module. `import type` runs nothing.
+ */
 const IMPORTS =
-  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)/g;
+  /\b(?:import|export)\s+(?!type\s)[^;'"]*?\bfrom\s*(['"])([^'"]+)\1|\bimport\s*\(\s*(['"])([^'"]+)\3\s*\)|\bimport\s*(['"])([^'"]+)\5/g;
 
 export function barrelImports(
   source: string,
@@ -41,7 +44,7 @@ export function barrelImports(
   const lineAt = lineIndex(code);
   const found: BarrelImport[] = [];
   for (const match of code.matchAll(IMPORTS)) {
-    const spec = match[2] ?? match[4] ?? '';
+    const spec = match[2] ?? match[4] ?? match[6] ?? '';
     const entry = barrels.get(spec);
     if (entry === undefined) continue;
     // `import { type A, type B } from …` binds nothing at runtime either.

package/src/shot-browser.ts

@@ -96,7 +96,7 @@ export function shotBrowserChoice(input: ShotBrowserInput): ShotBrowserChoice {
       flag: 'browser',
       command: 'shot',
       reason: `no executable at "${executablePath}"`,
-      fix: 'x shot / --browser /usr/bin/chromium',
+      fix: 'x shot / --browser /usr/bin/chromium   # macOS: --browser "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; Windows: --browser "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"',
     });
   }
   return { executablePath };

package/src/shot-locale.ts

@@ -3,41 +3,14 @@
 // on the language of the machine's Chrome. A non-default locale is also a URL prefix (`/en/…`),
 // because on a `site/` route the unprefixed path is always the default locale whatever the header.
 
-import { join } from 'node:path'; // why: Bun ships no path join.
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import { BadFlagError } from './errors';
 
-export interface ShotLocales {
-  readonly locales: readonly string[];
-  readonly defaultLocale: string;
-}
-
-/** An app that declares nothing is `en` only — the framework's own default. */
-export const FALLBACK_SHOT_LOCALES: ShotLocales = { locales: ['en'], defaultLocale: 'en' };
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null;
-
-/** `app.config.ts`'s `locales` and `defaultLocale`, read the way `loadThemeMode` reads `theme`. */
-export async function loadShotLocales(root: string): Promise<ShotLocales> {
-  const configPath = join(root, APP_CONFIG_FILE);
-  if (!(await Bun.file(configPath).exists())) return FALLBACK_SHOT_LOCALES;
-  const module = (await import(configPath)) as Record<string, unknown>;
-  const config = module[APP_CONFIG_EXPORT];
-  if (!isRecord(config)) return FALLBACK_SHOT_LOCALES;
-  const declared = config['locales'];
-  const locales = Array.isArray(declared)
-    ? declared.filter((locale): locale is string => typeof locale === 'string')
-    : [];
-  const fallback = config['defaultLocale'];
-  const defaultLocale =
-    typeof fallback === 'string' && fallback !== '' ? fallback : (locales[0] ?? 'en');
-  return {
-    locales: locales.length === 0 ? [defaultLocale] : locales,
-    defaultLocale,
-  };
-}
+/**
+ * `@ultimat3/i18n/app-catalogs`'s `appLocaleSet(root)` — the one reader, and its one answer for an
+ * app that declares nothing (`UNDECLARED_LOCALES`, the framework default alone).
+ */
+export type ShotLocales = AppLocaleSet;
 
 /** `--locale <l>`, refused by name when the app does not declare it — a typo costs no browser. */
 export function readLocaleFlag(value: string | undefined, app: ShotLocales): string | undefined {

package/src/shot-settle.ts

@@ -32,9 +32,9 @@ export interface SettleOptions {
 /**
  * Read the probe until every booted island has settled, or the window runs out.
  *
- * `DEFAULT_SETTLE_MS` is the deadline at which the hydration runtime CALLS `import()` — `mounted`
- * and `failed` land after it — so a single read at that instant reports `mounted: 0` for a page
- * that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
+ * The default window, `IDLE_HYDRATE_TIMEOUT_MS`, is the deadline at which the hydration runtime
+ * CALLS `import()` — `mounted` and `failed` land after it — so a single read at that instant
+ * reports `mounted: 0` for a page that hydrates perfectly and the verdict was taken one tick before the outcome existed. Polling
  * is the only shape that ends EARLY on a fast page and still bounds a slow one.
  *
  * A `null` answer never overwrites a real count: `null` means "not counted", and a probe that

package/src/shot-theme.ts

@@ -5,7 +5,7 @@
 // (issue #489). A requested theme is therefore stored as the visitor's CHOICE, on the page's origin,
 // before the boot reads it: the picture is then what a visitor who chose that theme sees.
 
-import { THEME_STORAGE_KEY } from '@ultimat3/render';
+import { THEME_STORAGE_KEY } from '@ultimat3/core';
 import type { ShotColorScheme } from './browser-launcher-port';
 import { BadFlagError } from './errors';
 

package/src/shot-viewport.ts

@@ -0,0 +1,152 @@
+// `x shot --viewport 390x844,1440x900`: the flag read into sizes, and one route photographed once
+// per size into `<out>/<w>x<h>/` over ONE dev server. Every responsive picture used to need a
+// hand-written browser script beside the tool that exists to make that unnecessary (#444).
+
+// why: no Bun native joins a path.
+import { join } from 'node:path';
+import { renderCauseValue } from '@ultimat3/core';
+import type { ShotRun } from './cmd-shot';
+import { BadFlagError } from './errors';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import type { ShotServer } from './shot-server';
+import type { ShotArtifacts } from './shot-verdict';
+import { shotLines, shotSummary, verdictJson } from './shot-verdict';
+
+/** CSS pixels a page is laid out in. */
+export interface ShotViewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The largest side a size may have: Chrome's maximum texture dimension, past which a capture is
+ * tiles the compositor never painted. One bound for both sides, so the refusal states one number.
+ */
+export const VIEWPORT_MAX = 16_384;
+
+/** Digits only: `0x10`, `1e3` and `390.5` are not a size anybody typed meaning a size. */
+const SIZE = /^(\d+)x(\d+)$/i;
+
+const FIX = 'x shot / --viewport 390x844,1440x900 --json';
+
+const refuse = (reason: string): never => {
+  throw new BadFlagError({ flag: 'viewport', command: 'shot', reason, fix: FIX });
+};
+
+/**
+ * An island state declares its own `viewport` in its `*.island.states.ts`, and the harness opens one
+ * browser per declared size — so a size asked for beside `--island`/`--all-islands` is a second
+ * answer to a question the states already answer.
+ */
+export function refuseViewportWithComponent(): never {
+  throw new BadFlagError({
+    flag: 'viewport',
+    command: 'shot',
+    reason: 'sizes a route capture; an island is photographed at the viewport each state declares',
+    fix: FIX,
+  });
+}
+
+/** A size is its own directory name, so two sizes can never write one picture. */
+export const viewportDir = (viewport: ShotViewport): string =>
+  `${String(viewport.width)}x${String(viewport.height)}`;
+
+function readSize(entry: string): ShotViewport {
+  const match = SIZE.exec(entry);
+  if (match === null) {
+    return refuse(`${renderCauseValue(entry)} is not <width>x<height>, e.g. 390x844`);
+  }
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  if (width < 1 || height < 1 || width > VIEWPORT_MAX || height > VIEWPORT_MAX) {
+    return refuse(`${renderCauseValue(entry)} is outside 1..${String(VIEWPORT_MAX)} on a side`);
+  }
+  return { width, height };
+}
+
+/**
+ * The flag, every entry judged before any is returned — a run that photographed the good half and
+ * refused afterwards would leave a reader with half a set and a failure. Absent is `undefined`:
+ * no override, the capture's own default size. Refused, never skipped: an empty entry and the same
+ * size twice are both a list the reader did not mean, and the second would overwrite the first.
+ */
+export function parseViewports(raw: string | undefined): readonly ShotViewport[] | undefined {
+  if (raw === undefined) return undefined;
+  const sizes = raw.split(',').map((entry) => readSize(entry.trim()));
+  const seen = new Set<string>();
+  for (const size of sizes) {
+    const dir = viewportDir(size);
+    if (seen.has(dir)) return refuse(`${dir} is listed twice`);
+    seen.add(dir);
+  }
+  return sizes;
+}
+
+export interface ViewportRun {
+  readonly viewports: readonly ShotViewport[];
+  /** Absolute; each size lands in `<outDir>/<w>x<h>/`. */
+  readonly outDir: string;
+  readonly boot: () => Promise<ShotServer>;
+  /** `runShot`, handed in so this module never imports the command that imports it. */
+  readonly shoot: (run: ShotRun) => Promise<ShotArtifacts>;
+  /** Everything a size shares: the route, the driver, the waits, the locale, the theme. */
+  readonly base: Omit<ShotRun, 'outDir' | 'boot' | 'viewport'>;
+}
+
+/**
+ * One server for every size, `runShotMatrix`'s rule: each capture gets a boot that never stops it,
+ * and the run stops it once after the last picture. Each size is an ordinary `runShot`, so its
+ * `verdict.json` means exactly what a single shot's does; `ok` only when every one is.
+ */
+export async function runShotViewports(run: ViewportRun): Promise<CommandResult> {
+  // `parseViewports` never answers an empty list; a hand-built one is refused before the boot.
+  if (run.viewports.length === 0) refuse('lists no size');
+  const server = await run.boot();
+  const shared: ShotServer = { ...server, stop: () => Promise.resolve() };
+  const shots: { readonly viewport: ShotViewport; readonly artifacts: ShotArtifacts }[] = [];
+  try {
+    for (const viewport of run.viewports) {
+      const artifacts = await run.shoot({
+        ...run.base,
+        viewport,
+        outDir: join(run.outDir, viewportDir(viewport)),
+        boot: () => Promise.resolve(shared),
+      });
+      shots.push({ viewport, artifacts });
+    }
+  } finally {
+    await server.stop().catch(() => undefined);
+  }
+  // The summary is the first failure's, else the first picture's — labelled by its size, so a
+  // reader of one line knows which of the sizes it speaks for.
+  const worst = shots.find((shot) => !shot.artifacts.verdict.ok) ?? shots[0];
+  return {
+    ok: shots.every((shot) => shot.artifacts.verdict.ok),
+    command: 'shot',
+    summary:
+      worst === undefined
+        ? refuse('lists no size')
+        : msg('cli.shot.viewport.summary', {
+            size: viewportDir(worst.viewport),
+            summary: shotSummary(worst.artifacts.verdict),
+          }),
+    lines: shots.flatMap((shot) => [
+      msg('cli.shot.viewport.line', {
+        size: viewportDir(shot.viewport),
+        summary: shotSummary(shot.artifacts.verdict),
+      }),
+      ...shotLines(shot.artifacts).map((line) => `  ${line}`),
+    ]),
+    data: {
+      outDir: run.outDir,
+      shots: shots.map((shot) => ({
+        width: shot.viewport.width,
+        height: shot.viewport.height,
+        image: shot.artifacts.image,
+        verdictFile: shot.artifacts.verdictFile,
+        verdict: verdictJson(shot.artifacts.verdict),
+      })),
+    },
+  };
+}

package/src/signal-shred.ts

@@ -4,24 +4,38 @@
 
 export type Reraise = (signal: NodeJS.Signals) => void;
 
+/** Ctrl-C, a supervisor's stop, and a terminal closing under the editor. */
+const SHRED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const;
+
 const reraiseDefault: Reraise = (signal) => {
   process.kill(process.pid, signal);
 };
 
 /**
- * Shred on SIGINT/SIGTERM, then re-raise the same signal: `once` has already removed this
- * listener, so the re-raised signal meets the default action and terminates. Returns the undo for
- * the normal path, which shreds in its own `finally`.
+ * Shred on SIGINT/SIGTERM/SIGHUP, then re-raise the same signal with the listeners gone, so it
+ * meets the default action and terminates. Returns the undo for the normal path, which shreds in
+ * its own `finally`.
+ *
+ * The listeners stay installed UNTIL the shred is done, and a repeat meanwhile is ignored. With
+ * `once` the listener was gone the moment the first signal was dispatched, so a second one — a
+ * Ctrl-C the terminal delivers to the whole group and a wrapper forwards again — met the default
+ * action: a kernel-level kill mid-`rmSync`, the plaintext left in $TMPDIR (30 of 40 runs).
  */
 export function shredOnSignal(shred: () => void, reraise: Reraise = reraiseDefault): () => void {
-  const handler = (signal: NodeJS.Signals): void => {
-    shred();
-    reraise(signal);
-  };
-  process.once('SIGINT', handler);
-  process.once('SIGTERM', handler);
-  return () => {
-    process.off('SIGINT', handler);
-    process.off('SIGTERM', handler);
+  let shredding = false;
+  const undo = (): void => {
+    for (const signal of SHRED_SIGNALS) process.off(signal, handler);
   };
+  function handler(signal: NodeJS.Signals): void {
+    if (shredding) return;
+    shredding = true;
+    try {
+      shred();
+    } finally {
+      undo();
+      reraise(signal);
+    }
+  }
+  for (const signal of SHRED_SIGNALS) process.on(signal, handler);
+  return undo;
 }

package/src/site-asset-routes.ts

@@ -5,7 +5,7 @@
 
 import { isUltimateError } from '@ultimat3/core';
 import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, jsonResponse } from '@ultimat3/http';
 import type { SiteAsset, SiteAssetTable } from './site-assets';
 import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
 
@@ -13,7 +13,7 @@ import { parseHashedAssetUrl, SITE_ASSET_BASE_PATH } from './site-assets';
 export const SITE_ASSET_CACHE: CacheHint = { mode: 'immutable' };
 
 const notFound = (code: string, cause: string, fix: string): Response =>
-  json({ ok: false, error: { code, cause, fix } }, { status: 404 });
+  jsonResponse({ ok: false, error: { code, cause, fix } }, { status: 404 });
 
 /** One `bytes=` range, resolved against the file's size; `null` when it cannot be satisfied. */
 export function byteRange(

package/src/site-assets.ts

@@ -9,6 +9,7 @@ import { copyFileSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path'; // why: Bun ships no path API.
 import type { AssetExtension, AssetPath } from '@ultimat3/render';
 import { ASSET_DIR, AssetMissingError, assetPathProblem } from '@ultimat3/render';
+import { contentHash } from '@ultimat3/render/server';
 
 /** App-root-relative, beside `favicon.ico`: `apps/web/site/` is where an app's public files live. */
 export const SITE_ASSETS_SOURCE = `apps/web/site/${ASSET_DIR}`;
@@ -37,7 +38,7 @@ export interface SiteAsset {
   readonly path: AssetPath;
   /** Absolute path on disk. */
   readonly file: string;
-  /** xxHash32 of the bytes, 8 hex characters — the algorithm `contentHash` uses for CSS. */
+  /** `@ultimat3/render`'s `contentHash` of the bytes, 8 hex characters — the one CSS and HTML get. */
   readonly hash: string;
   /** `/assets/brand/logo.<hash>.svg`. */
   readonly url: string;
@@ -69,9 +70,6 @@ export function parseHashedAssetUrl(
   return { path: path as AssetPath, hash: match[2] ?? '' };
 }
 
-const hashBytes = (bytes: Uint8Array): string =>
-  Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0');
-
 export interface SiteAssetTable {
   /** The asset `asset()` named, hashed as the bytes are NOW. Throws `X_ASSET_MISSING`. */
   resolve(path: AssetPath): SiteAsset;
@@ -110,7 +108,7 @@ export function createSiteAssetTable(root: string): SiteAssetTable {
     const cached = cache.get(path);
     if (cached !== undefined && cached.stamp === stamp) return cached.asset;
     const bytes = readFileSync(file);
-    const hash = hashBytes(bytes);
+    const hash = contentHash(bytes);
     // `assetPathProblem` already refused an unknown extension; the guard keeps `constructor` from
     // ever answering an `Object` member if that check is loosened.
     const extension = splitExtension(path).extension.toLowerCase();