@ultimat3/cli 23.0.0 → 25.0.0

package/src/prerender-served.ts

@@ -0,0 +1,52 @@
+// How the build weighs an app/ page it renders only to measure: as the document a request is
+// SERVED — the sync head and page boot both boots compose (`pageSync`), and the runtime chunk that
+// boot makes unfetched. An unscoped render measured a runtime chunk no scoped page downloads and
+// never the boot every one of them does, so `/feed` and `/runs` were budgets about nothing (#505).
+
+import type { ClientSyncHead } from '@ultimat3/render';
+import { loadAppConfig } from './app-config-load';
+import type { MeasureOptions } from './budgets';
+import type { IslandBundle } from './island-bundle';
+import { isRuntimeChunk } from './island-runtime';
+import { pageSync } from './page-sync';
+import { realtimeConfigOf } from './runtime-realtime';
+import { PAGE_BOOT_BASE_PATH } from './worker-bundle';
+
+/** What a served-document measurement adds: to the document's options, and to the measurer's. */
+export interface ServedMeasure {
+  readonly document: {
+    readonly sync?: ClientSyncHead;
+    readonly persisted?: () => readonly string[];
+  };
+  readonly measure: MeasureOptions;
+}
+
+/**
+ * `realtime.enabled: false` serves no sync head and no boot (`pageSync`), and then the measurement
+ * adds nothing: such a page's realtime islands load the runtime chunk, and are charged for it.
+ */
+export async function servedMeasure(
+  root: string,
+  buildId: string,
+  islands: IslandBundle,
+): Promise<ServedMeasure> {
+  const sync = await pageSync(
+    root,
+    process.env,
+    buildId,
+    realtimeConfigOf(await loadAppConfig(root)),
+  );
+  return {
+    document: {
+      ...(sync.head === undefined ? {} : { sync: sync.head }),
+      persisted: sync.persisted,
+    },
+    measure: {
+      served: new Map(sync.scripts.map((script) => [script.url, script.code])),
+      boot: {
+        prefix: `${PAGE_BOOT_BASE_PATH}/`,
+        supplies: new Set(islands.shared.map((one) => one.url).filter(isRuntimeChunk)),
+      },
+    },
+  };
+}

package/src/prerender.ts

@@ -5,34 +5,38 @@
 
 import { join } from 'node:path';
 import {
-  createContext,
+  ctxOf,
   DEFAULT_ENVIRONMENT,
   isUltimateError,
+  localizePath,
   renderThrowable,
   runWithContext,
   tryResolveEnvironment,
 } from '@ultimat3/core';
-import { localeConfig, localizedPath, routedLocales } from '@ultimat3/i18n';
 import type { RouteEntry } from '@ultimat3/render';
-import { describeRoutes, routeEntries } from '@ultimat3/render';
+import { describePages, routeEntries } from '@ultimat3/render';
 import { renderStatic } from '@ultimat3/render/server';
 import { loadApp } from './app-load';
 import { appManifest } from './app-manifest';
 import type { RouteStats } from './budgets';
-import { measureDocumentJs, writeBuildStats } from './budgets';
+import { measureDocumentJs, routeStatsRow, writeBuildStats } from './budgets';
 import { errorPageDocument, STATIC_ERROR_PAGE } from './error-pages';
+import { PrerenderLoadFailedError } from './errors';
 import { FAVICON_PATH, faviconBytes } from './favicon';
 import type { IslandBundle } from './island-bundle';
 import { buildIslands, writeIslands } from './island-bundle';
 import { measureDatabase } from './measure-database';
 import { measurePaths } from './measure-paths';
-import { measureScope, withAppUrl } from './measure-scope';
+import { measurementActorLabel, measureScope, withAppUrl } from './measure-scope';
 import { loadNavigation, pageNavigation } from './page-navigation';
-import { loadSpeculation, pageSpeculation } from './page-speculation';
+import { loadSpeculation, otherLocaleSegments, pageSpeculation } from './page-speculation';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
+import type { PrerenderedPage, PrerenderReport } from './prerender-report';
+import type { ServedMeasure } from './prerender-served';
+import { servedMeasure } from './prerender-served';
 import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
-import { routeDocument } from './runtime-render';
+import { routeDocument, servedDocument } from './runtime-render';
 import { writeSiteAssets } from './site-assets';
 import { loadSiteSettings, originWarning, publicOrigin } from './site-config';
 import type { SkippedRoute, UnmeasuredRoute } from './static-report';
@@ -47,9 +51,13 @@ import {
   serviceWorkerRegistration,
 } from './sw-artifacts';
 import { loadThemeMode, themeBoot } from './theme-boot';
+import { loadThemeBrand } from './theme-brand';
+import { writeErrorLine } from './write-line';
 
+export type { PrerenderedPage, PrerenderReport } from './prerender-report';
 // 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.
+// carries it, and this file already imports that module. The report's own shapes are
+// `prerender-report.ts`'s, re-exported here for the same reason: callers ask this module.
 export type { UnmeasuredRoute };
 
 /**
@@ -74,59 +82,6 @@ export interface PrerenderOptions {
   readonly origin?: string;
 }
 
-export interface PrerenderedPage {
-  /** The DECLARED route, `/blog/:slug` — one route can write many pages, and the report groups them. */
-  readonly route: string;
-  /** The URL the page is served at — `/en/pricing` for a non-default locale. */
-  readonly path: string;
-  /** The locale the page was rendered in. */
-  readonly locale: string;
-  /** Relative to `out`, POSIX — under `<locale>/` for a non-default locale. */
-  readonly file: string;
-  readonly hash: string;
-  readonly bytes: number;
-}
-
-export interface PrerenderReport {
-  readonly out: string;
-  readonly buildId: string;
-  readonly pages: readonly PrerenderedPage[];
-  /**
-   * Every declared route that wrote no file, WITH the cause. A bare path list was the whole of
-   * #242: `.x/static/` held a partial site, the report said only which paths were missing, and a
-   * screenshot tool pointed at the directory filed "the island did not mount" against a route that
-   * had never been in the artifact. The reason is what tells an author whether an edit exists.
-   */
-  readonly skipped: readonly SkippedRoute[];
-  /**
-   * Routes whose budget this build could not weigh, with the reason. `X_BUDGET_UNMEASURED` is what
-   * the gate then reports for each; this is the half that says WHY, which a per-route finding read
-   * off a stats file cannot know.
-   */
-  readonly unmeasured: readonly UnmeasuredRoute[];
-  /** Where the measured stats landed, for the `budgets` gate step to read. */
-  readonly stats: string;
-  /** Where the emitted/skipped inventory landed, for `x build --target static` to read back. */
-  readonly report: string;
-  /** Client entries emitted, one chunk each. Reported so "which JS shipped?" needs no unzip. */
-  readonly islands: readonly string[];
-  /** Surface stylesheets emitted, one file each — the CSS half of the same question. */
-  readonly styles: 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[];
-  /** What this build could not get right on its own — today, a production build with no origin. */
-  readonly warnings: readonly string[];
-  /** The origin every absolute URL in the export was built against — hand it to `siteSeo`. */
-  readonly origin: string;
-}
-
 /**
  * The heaviest thing the document actually boots, named by the source file an author can open.
  * An island chunk is content-addressed, so its URL says nothing on its own — mapping it back
@@ -168,15 +123,17 @@ const NOT_FOUND_STATUS = 404;
  */
 const declaresBudget = (entry: RouteEntry): boolean => {
   const budget = entry.config.budget;
-  return budget !== undefined && (budget.js !== undefined || budget.lcp !== undefined);
+  return budget?.js !== undefined;
 };
 
 export async function prerenderSite(options: PrerenderOptions): Promise<PrerenderReport> {
-  // The same load `x dev` and `x manifest` perform: importing the app's modules IS what fills the
-  // route registry, so there is no route table to prerender before this runs.
-  // Emptied FIRST: the export only ever gained files, so a deleted route's HTML kept shipping.
+  // The load `x dev` and `x manifest` perform: importing the app's modules fills the route registry.
+  // A module that would not import registered nothing, so its page would vanish from the export
+  // under a green build — refused BEFORE the export is emptied, so the last good artifact survives.
+  const loaded = await loadApp(options.root);
+  if (loaded.findings.length > 0) throw new PrerenderLoadFailedError(loaded.findings);
+  // Emptied before anything is written: a deleted route's HTML kept shipping when it only grew.
   await clearPrerenderOut(options.out, options.root);
-  await loadApp(options.root);
   const buildId = (await appManifest(options.root)).manifest.buildId;
   const declaredOrigin =
     options.origin ?? publicOrigin(process.env, await loadSiteSettings(options.root));
@@ -184,11 +141,12 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // Written to stderr as well as returned: an app's `prerender.ts` prints its report as ONE JSON
   // line on stdout, and a build that parses it must not meet a warning inside it.
   const warnings = originWarning(tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT, declaredOrigin);
-  for (const warning of warnings) process.stderr.write(`warning: ${warning}\n`);
-  // After `loadApp`: `defineCatalogs()` configures the locales on the app's own import. The
-  // default first, so every other pass writes beside a tree that already holds the unprefixed one.
-  const locales = routedLocales();
-  const defaultLocale = localeConfig().fallback;
+  for (const warning of warnings) writeErrorLine(`warning: ${warning}`);
+  // The app's locales as `loadApp` read them, ONCE, off `@ultimat3/i18n`'s one reader — the same
+  // answer the PWA manifest and the service worker below are built from. The default first, so
+  // every other pass writes beside a tree that already holds the unprefixed one.
+  const appLocales = loaded.locales;
+  const { locales, defaultLocale } = appLocales;
   const pages: PrerenderedPage[] = [];
   const skipped: SkippedRoute[] = [];
   const routes: RouteStats[] = [];
@@ -235,6 +193,8 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // names it either.
   const pwa = await loadPwaArtifacts(options.root);
   const theme = themeBoot(await loadThemeMode(options.root));
+  // The brand the served process carries, so an exported page and a served one paint alike.
+  const brand = await loadThemeBrand(options.root);
   // The client router, for the surfaces that opted in: written BEFORE any document names it, for
   // the register's reason below — `measureDocumentJs` weighs it off disk, and it is charged to
   // the route (the interactivity the app asked for), so it must be there to be weighed.
@@ -244,6 +204,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const speculation = pageSpeculation({
     config: await loadSpeculation(options.root),
     client: declared.surfaces,
+    localeSegments: otherLocaleSegments(appLocales),
   });
   if (navigation.script !== undefined) {
     await Bun.write(join(options.out, navigation.script.url.slice(1)), navigation.script.code);
@@ -289,11 +250,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   // build. One context for the build, `role: 'web'` because that is the role serving these
   // documents, and this build's own id so a component reading `ctx.buildId` stamps the artifact
   // with the id the report and the stats carry.
-  // ONE PER LOCALE, and the locale is the context's: `createContext` defaults it to core's `en`, so a
+  // ONE PER LOCALE, and the locale is the context's: `ctxOf` defaults it to core's `en`, so a
   // Spanish-default site was prerendered in English — `<html lang="en">` over English copy — while
   // the served process answered Spanish. Each `site/` page is rendered once per routed locale.
   const contexts = new Map(
-    locales.map((locale) => [locale, createContext({ role: 'web', buildId, locale })]),
+    locales.map((locale) => [locale, ctxOf({ role: 'web', buildId, locale })]),
   );
   // A SECOND scope, for the branch below that renders only to weigh (`measure-scope.ts`): a
   // request context holding the app's measurement actor, with the app's own API answered in
@@ -304,23 +265,32 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
   const measure = await measureScope({ origin, buildId });
   // Started on the first route that needs weighing, and released however the loop ends.
   const database = measureDatabase(options.root);
+  const documentOptions = {
+    resolveIsland: (file: string) => islands.resolverFor(file),
+    themeHead: theme.head,
+    ...(brand === undefined ? {} : { brandHead: brand.head }),
+    ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
+    origin,
+    ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
+    ...(pwa === undefined
+      ? {}
+      : { pwaHead: (locale: string) => pwa.headFor(locale) + (swHead ?? '') }),
+  };
   const render = (entry: RouteEntry, data: { url: string; params: Record<string, string> }) =>
-    routeDocument(entry, data, {
-      resolveIsland: (file: string) => islands.resolverFor(file),
-      themeHead: theme.head,
-      ...(speculation === undefined ? {} : { speculationHead: speculation.head }),
-      origin,
-      ...(navigation.head === undefined ? {} : { navigation: navigation.head }),
-      ...(pwa === undefined
-        ? {}
-        : { pwaHead: (locale: string) => pwa.headFor(locale) + (swHead ?? '') }),
-    });
+    routeDocument(entry, data, documentOptions);
+  // The weigh-only branch measures the document a request is SERVED (`prerender-served.ts`):
+  // composed on the first route that needs it, so a build weighing none builds no page boot.
+  let weighing: Promise<ServedMeasure> | undefined;
+  const served = (): Promise<ServedMeasure> => {
+    weighing ??= servedMeasure(options.root, buildId, islands);
+    return weighing;
+  };
   const document = (
     locale: string,
     entry: RouteEntry,
     data: { url: string; params: Record<string, string> },
   ) =>
-    runWithContext(contexts.get(locale) ?? createContext({ role: 'web', buildId, locale }), () =>
+    runWithContext(contexts.get(locale) ?? ctxOf({ role: 'web', buildId, locale }), () =>
       render(entry, data),
     );
 
@@ -349,16 +319,19 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
           let row: RouteStats | undefined;
           for (const { path, params } of plan.paths) {
             const data = { url: new URL(path, origin).href, params };
-            const html = await withAppUrl(origin, () => measure.run(() => render(entry, data)));
-            const measured = await measureDocumentJs(html, options.out);
+            const as = await served();
+            const html = await withAppUrl(origin, () =>
+              measure.run(() =>
+                servedDocument(entry, data, measure.actor, {
+                  ...documentOptions,
+                  ...as.document,
+                  buildId,
+                }),
+              ),
+            );
+            const measured = await measureDocumentJs(html, options.out, as.measure);
             if (row !== undefined && measured.jsBytes <= row.jsBytes) continue;
-            const chain = heaviestSource(islands, measured.entries);
-            row = {
-              path: entry.path,
-              jsBytes: measured.jsBytes,
-              frameworkJsBytes: measured.frameworkBytes,
-              ...(chain === undefined ? {} : { heaviestChain: chain }),
-            };
+            row = routeStatsRow(entry.path, measured, heaviestSource(islands, measured.entries));
           }
           if (row !== undefined) routes.push(row);
         } catch (error) {
@@ -374,16 +347,17 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
             ...(isUltimateError(error)
               ? { code: error.code, cause: error.cause, fix: error.fix }
               : {}),
+            actor: measurementActorLabel(measure.actor),
           });
         }
         continue;
       }
-      const artifacts = await localizedArtifacts(locales, defaultLocale, (locale) =>
+      const artifacts = await localizedArtifacts(appLocales, (locale) =>
         renderStatic(
           entry,
           ({ path, params }) =>
             document(locale, entry, {
-              url: new URL(localizedPath(path, locale, defaultLocale), origin).href,
+              url: new URL(localizePath(path, locale, locales, defaultLocale), origin).href,
               params,
             }),
           { buildId },
@@ -428,14 +402,8 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
           bytes,
           assets: measured.entries.map((entry) => entry.url),
         });
-        const chain = heaviestSource(islands, measured.entries);
         if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
-        heaviest = {
-          path: entry.path,
-          jsBytes: measured.jsBytes,
-          frameworkJsBytes: measured.frameworkBytes,
-          ...(chain === undefined ? {} : { heaviestChain: chain }),
-        };
+        heaviest = routeStatsRow(entry.path, measured, heaviestSource(islands, measured.entries));
       }
       if (heaviest !== undefined) routes.push(heaviest);
     }
@@ -452,7 +420,7 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       : serviceWorkerArtifacts({
           pwa,
           buildId,
-          routes: describeRoutes(),
+          routes: describePages(),
           islands,
           styles,
           documents,

package/src/pwa-artifacts.ts

@@ -15,17 +15,13 @@
 // 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 `runtime-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 `runtime-assets.ts` each record for their own root-relative constant.
+// why: Bun exposes no path-join primitive, and the export writes each icon under an out directory.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import { localeSegment } from '@ultimat3/core';
+import { escapeHtml, localeSegment } from '@ultimat3/core';
 import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
+import { appLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import {
   appleTouchLinks,
   generateWebManifest,
@@ -34,9 +30,7 @@ import {
 } from '@ultimat3/pwa';
 import type { AssetPath } from '@ultimat3/render';
 import { assetPathProblem } from '@ultimat3/render';
-import { escapeAttribute } from '@ultimat3/seo';
-import { APP_CONFIG_EXPORT } from './app-auth';
-import { APP_CONFIG_FILE } from './app-root';
+import { loadAppConfig } from './app-config-load';
 import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
 import type { AppLocales } from './pwa-manifest-locales';
 import { appLocales, localeMembers, spellIn } from './pwa-manifest-locales';
@@ -80,45 +74,17 @@ export interface PwaArtifacts {
   /** The `<head>` for a document in `locale` — it links that locale's manifest. */
   headFor(locale: string): 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".
+   * The three `pwa` keys the SERVICE WORKER needs, carried here so `sw-artifacts.ts` — which needs
+   * the route table and the island bundle as well — reads them off the same resolved block.
    */
   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 routed locales the manifests above were built from, default first — `appLocaleSet`'s one
+   * answer, carried here so the service worker prefixes exactly the locales the manifests name.
+   */
+  readonly locales: AppLocales;
 }
 
 /** The `pwa` block, as much of it as this file needs, or `undefined` when the app declares none. */
@@ -133,60 +99,30 @@ interface InstallableApp {
   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,
-    block: pwa,
-    locales: appLocales(config),
-    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.
+ * `pwa.enabled`, read, off the one loader (`app-config-load.ts`). Core's validator refuses an
+ * enabled block without a name, both colour schemes or an absolute `offline.fallback`, so nothing
+ * here invents a colour or a fallback route; `colors` is optional only in the type.
  */
-function offlineOf(value: unknown): PwaOfflineConfig {
-  const block = isRecord(value) ? value : {};
-  const fallback = text(block['fallback']);
-  const patterns = block['neverCache'];
+async function loadInstallable(root: string): Promise<InstallableApp | undefined> {
+  const config = await loadAppConfig(root);
+  const pwa = config?.pwa;
+  if (config === undefined || pwa === undefined || !pwa.enabled || pwa.colors === undefined) {
+    return undefined;
+  }
   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')
-      : [],
-    personalPages: block['personalPages'] === 'last-member' ? 'last-member' : 'never',
+    name: pwa.name,
+    colors: pwa.colors,
+    block: { ...pwa },
+    locales: appLocales(await appLocaleSet(root)),
+    offline: pwa.offline,
+    backgroundSync: pwa.backgroundSync,
+    push: pwa.push,
   };
 }
 
-/** `=== 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`:
+ * Resolved ONCE at boot, like `loadSignInPath` and unlike `faviconBytes`: the loader's
  * `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.
  */
@@ -219,7 +155,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
       path,
       body: serializeWebManifest(result.manifest),
       head:
-        `<link rel="manifest" href="${escapeAttribute(path)}">` +
+        `<link rel="manifest" href="${escapeHtml(path)}">` +
         renderThemeColorMeta(result.themeColorMeta) +
         (icons === undefined ? '' : appleTouchLinks(icons)),
     };
@@ -231,6 +167,7 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
     offline: app.offline,
     backgroundSync: app.backgroundSync,
     push: app.push,
+    locales: app.locales,
     body: primary.body,
     head: primary.head,
     manifests,
@@ -244,7 +181,9 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
  * `asset()` does in a page. The site serves an asset ONLY at its hashed URL, and the manifest took
  * `src` verbatim, so an app had to hash its own screenshots to avoid shipping a 404 in the install
  * sheet (notificado.co's `pwa-install.ts`). A missing file is `X_ASSET_MISSING` at boot, never a
- * broken image in an install prompt; any other `src` (absolute, already hashed) passes untouched.
+ * broken image in an install prompt; any other `src` passes untouched — an absolute path outside
+ * `/assets/`, an already hashed one, or a shortcut icon's off-site URL (core screens screenshots and
+ * shortcut urls to absolute paths, not icon sources).
  */
 function withHashedAssets<M extends ReturnType<typeof localeMembers>>(members: M, root: string): M {
   const resolve = (src: string): string => {

package/src/pwa-manifest-locales.ts

@@ -3,6 +3,7 @@
 // routed locale from this; the `pwa` block is read structurally, for `colorsOf`'s reason there.
 
 import { localeSegment, localizePath } from '@ultimat3/core';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type {
   ManifestIcon,
   ManifestScreenshot,
@@ -10,7 +11,7 @@ import type {
   WebManifestInput,
 } from '@ultimat3/pwa';
 
-/** The app's locales as `app.config.ts` declares them, default first. */
+/** The app's locales as its catalogs declare them (`defineCatalogs`), default first. */
 export interface AppLocales {
   readonly routed: readonly string[];
   readonly fallback: string;
@@ -23,15 +24,14 @@ const strings = (value: unknown): readonly string[] =>
   Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
 
 /**
- * `locales` and `defaultLocale`, read off the config object. The manifest's `lang` was the
- * generator's hardcoded `'en'` for an `es-co` app (notificado.co, 22.3.2). An untyped config with
- * neither is core's own default, `en`.
+ * The manifests' locales, off `appLocaleSet`'s answer (`@ultimat3/i18n/app-catalogs`) — an app
+ * with no catalogs is `UNDECLARED_LOCALES`, the framework default alone. The manifest's `lang` was
+ * the generator's hardcoded `'en'` for an `es-co` app (notificado.co, 22.3.2). Deduplicated by URL
+ * segment, the unit a locale prefix is spelled in.
  */
-export function appLocales(config: Record<string, unknown>): AppLocales {
-  const declared = strings(config['locales']);
-  const named = config['defaultLocale'];
-  const fallback = typeof named === 'string' && named !== '' ? named : (declared[0] ?? 'en');
-  const others = declared.filter((locale) => localeSegment(locale) !== localeSegment(fallback));
+export function appLocales(set: AppLocaleSet): AppLocales {
+  const fallback = set.defaultLocale;
+  const others = set.locales.filter((locale) => localeSegment(locale) !== localeSegment(fallback));
   return { routed: [fallback, ...others], fallback };
 }
 

package/src/registry.ts

@@ -7,6 +7,7 @@
 // dev server it never started (plan 101 slice 12 d).
 
 import { affectedSpec } from './cmd-affected-spec';
+import { authSpec } from './cmd-auth-spec';
 import { buildSpec } from './cmd-build-spec';
 import { ciSpec } from './cmd-ci-spec';
 import { dbSpec } from './cmd-db-spec';
@@ -85,6 +86,7 @@ export const LAZY_COMMANDS: readonly LazyCommand[] = [
   lazy(deploySpec, async () => (await import('./cmd-deploy')).deployCommand),
   lazy(envSpec, async () => (await import('./cmd-env')).envCommand),
   lazy(secretsSpec, async () => (await import('./cmd-secrets')).secretsCommand),
+  lazy(authSpec, async () => (await import('./cmd-auth')).authCommand),
   lazy(manifestSpec, async () => (await import('./cmd-manifest')).manifestCommand),
   lazy(routesSpec, async () => (await import('./cmd-routes')).routesCommand),
   lazy(actionsSpec, async () => (await import('./cmd-registries')).actionsCommand),

package/src/retry-memo.ts

@@ -15,7 +15,7 @@ export interface RetryMemo<T> {
 }
 
 /**
- * `start` runs at most once per SUCCESS. `@ultimat3/db`'s `createPgliteClient` states the rule this
+ * `start` runs at most once per SUCCESS. `@ultimat3/db`'s `pgliteClient` states the rule this
  * generalises — "a failed boot must not be cached" — and the clearing handler is attached at
  * creation for the reason that matters: it therefore runs ahead of every caller's own `await`
  * continuation, so by the time anyone sees the rejection the slot is already empty and the next

package/src/revalidated-response.ts

@@ -4,6 +4,7 @@
 // name that outlives its bytes is a file no client refreshes for a year.
 
 import type { UltimateRequest } from '@ultimat3/http';
+import { contentHash } from '@ultimat3/render/server';
 import { etagMatches } from './runtime-storage';
 
 /**
@@ -14,8 +15,8 @@ import { etagMatches } from './runtime-storage';
 export const REVALIDATE_CACHE_CONTROL = 'public, max-age=0, must-revalidate';
 
 /**
- * A strong validator from the bytes — xxHash32, the function `contentHash` applies to a document,
- * taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
+ * A strong validator from the bytes — `@ultimat3/render`'s `contentHash`, the function a document's
+ * ETag is, taken here over bytes because an icon is not a string. Revalidating costs a request and no body.
  */
 export function revalidatedResponse(
   request: UltimateRequest,
@@ -25,7 +26,7 @@ export function revalidatedResponse(
   // Copied, not passed through: a `Uint8Array<ArrayBufferLike>` may be backed by a
   // `SharedArrayBuffer`, which `Response` does not accept — `runtime-assets.ts`'s rule, verbatim.
   const bytes = typeof body === 'string' ? new TextEncoder().encode(body) : new Uint8Array(body);
-  const etag = `"${Bun.hash.xxHash32(bytes).toString(16).padStart(8, '0')}"`;
+  const etag = `"${contentHash(bytes)}"`;
   const headers = {
     'content-type': contentType,
     'cache-control': REVALIDATE_CACHE_CONTROL,