@ultimat3/cli 24.0.0 → 25.1.0

package/src/page-speculation.ts

@@ -8,10 +8,10 @@
 import type { NavigationSurface, SpeculationConfig } from '@ultimat3/core';
 import { DEFAULT_SPECULATION, localeSegment } from '@ultimat3/core';
 import { cspHashSource } from '@ultimat3/http';
-import { localeConfig, routedLocales } from '@ultimat3/i18n';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { RouteDescriptor, RouteEntry } from '@ultimat3/render';
 import {
-  describeRoutes,
+  describePages,
   renderHead,
   routeEntries,
   speculationPattern,
@@ -67,15 +67,18 @@ export interface PageSpeculationInput {
   readonly client: readonly NavigationSurface[];
   readonly entries?: readonly RouteEntry[];
   readonly described?: readonly RouteDescriptor[];
-  /** The NON-default routed locales' URL segments. Read from `@ultimat3/i18n` when absent. */
-  readonly localeSegments?: readonly string[];
+  /**
+   * The NON-default routed locales' URL segments — `otherLocaleSegments(appLocaleSet)`, the set the
+   * manifest, the worker and the prerender read. Every caller passes it: no build reads the
+   * ambient locale config.
+   */
+  readonly localeSegments: readonly string[];
 }
 
-const otherLocaleSegments = (): readonly string[] => {
-  const fallback = localeSegment(localeConfig().fallback);
-  return routedLocales()
-    .map(localeSegment)
-    .filter((segment) => segment !== fallback);
+/** Every routed locale but the default, as the URL segment a prefix is spelled in. */
+export const otherLocaleSegments = (set: AppLocaleSet): readonly string[] => {
+  const fallback = localeSegment(set.defaultLocale);
+  return set.locales.map(localeSegment).filter((segment) => segment !== fallback);
 };
 
 /**
@@ -86,9 +89,9 @@ const otherLocaleSegments = (): readonly string[] => {
 export function pageSpeculation(input: PageSpeculationInput): PageSpeculation | undefined {
   if (input.config.prefetch === false) return undefined;
   const entries = input.entries ?? routeEntries();
-  const described = new Map((input.described ?? describeRoutes()).map((one) => [one.file, one]));
+  const described = new Map((input.described ?? describePages()).map((one) => [one.file, one]));
   const client = new Set<string>(input.client);
-  const segments = input.localeSegments ?? otherLocaleSegments();
+  const segments = input.localeSegments;
   const include = entries
     .filter((entry) => {
       const facts = described.get(entry.file);

package/src/parse.ts

@@ -8,14 +8,6 @@ import { BadFlagError, MissingSubcommandError, UnknownCommandError } from './err
 // anywhere while still refusing with a fix line a shell reads as one argument.
 import { quoteArg } from './shell-quote';
 
-/**
- * The historical name for `@ultimat3/core`'s `nearestName`, kept because it shipped on this
- * package's exported surface and removing it would be a major for a rename. One implementation
- * behind both — this is a delegation, not the second copy of the algorithm that `@ultimat3/policy`
- * used to carry. New callers import `nearestName` from core.
- */
-export const nearest = nearestName;
-
 export type FlagValue = string | boolean;
 
 export interface FlagSpec {

package/src/permission-grants.ts

@@ -7,7 +7,7 @@ import { listActions } from '@ultimat3/action';
 import type { Policy } from '@ultimat3/policy';
 import { roleDefinitions, rolesGranting } from '@ultimat3/policy';
 import { listQueries } from '@ultimat3/query';
-import { describeRoutes, routeEntries } from '@ultimat3/render';
+import { describePages, routeEntries } from '@ultimat3/render';
 import type { Finding } from './output';
 import { quoteArg } from './shell-quote';
 
@@ -46,12 +46,12 @@ export function requirements(): readonly UngrantedRequirement[] {
   // A route a package MOUNTED — the admin's — is in no file and so in no `routeEntries()` row. Its
   // screen decides on every permission of the mount, not only the coarse gate its route config
   // carries, so each one is a requirement: a hand-written entity nobody granted `<table>:read`
-  // for was a green gate and a 403 on its first open. `describeRoutes()` is memoized by the
+  // for was a green gate and a 403 on its first open. `describePages()` is memoized by the
   // registry, so this loop reads a list every other step already built.
   // One requirement per permission per mount, naming the first route that asks it: `posts:write`
   // gates the create form and the edit form, and one missing grant is one finding.
   const asked = new Map<string, { permission: string; by: string; first: string; more: number }>();
-  for (const route of describeRoutes()) {
+  for (const route of describePages()) {
     if (route.mount === undefined) continue;
     for (const permission of route.mount.permissions) {
       const key = `${route.mount.by} ${permission}`;

package/src/posix-path.ts

@@ -0,0 +1,30 @@
+// One answer to "this host path, written with `/`". `relative()` and `Bun.Glob` answer in the
+// host's separator, so on Windows a `\` reached an import specifier (`x fix` wrote
+// `import '..\\foo'`, which breaks every Linux teammate), a fix line and a sort key. Every such
+// result passes through here — `bun run posix-relative` refuses a `relative(` that does not.
+
+// why: Bun ships no path API; `node:path` owns `relative`, and a test hands in its `win32` half to
+// prove the Windows answer on a Linux runner.
+import * as hostPath from 'node:path';
+
+/**
+ * The one method `posixRelative` asks of a path module — structural, not `PlatformPath`: the
+ * scaffold's typecheck resolves `node:path` without that name exported (TS2305).
+ */
+export interface RelativeHost {
+  readonly relative: (from: string, to: string) => string;
+}
+
+/**
+ * `path` with every `\` written as `/`. Unconditional rather than keyed to the host's `sep`: a key,
+ * a specifier and a fix line are POSIX on every host, and a Windows-shaped path handed to a Linux
+ * process (a CI log, a test fixture) must come out the same as it would on Windows.
+ */
+export function toPosix(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+/** `relative(from, to)` in POSIX form. `host` is the platform's own path module but for a test. */
+export function posixRelative(from: string, to: string, host: RelativeHost = hostPath): string {
+  return toPosix(host.relative(from, to));
+}

package/src/prerender-locales.ts

@@ -2,7 +2,8 @@
 // paths and files `renderStatic` computed; every other locale's are served at `/<locale>/<path>`
 // and written to `<locale>/<file>` — the layout every static host resolves with no rewrite rule.
 
-import { localeSegment, localizedPath } from '@ultimat3/i18n';
+import { localeSegment, localizePath } from '@ultimat3/core';
+import type { AppLocaleSet } from '@ultimat3/i18n/app-catalogs';
 import type { StaticArtifact } from '@ultimat3/render/server';
 
 /** A `StaticArtifact` placed for one locale: its served path and its file under `<locale>/`. */
@@ -10,8 +11,7 @@ export type LocalizedArtifact = StaticArtifact & { readonly locale: string };
 
 /** The default's artifacts first, so a report lists the unprefixed page before its translations. */
 export async function localizedArtifacts(
-  locales: readonly string[],
-  defaultLocale: string,
+  { locales, defaultLocale }: AppLocaleSet,
   renderIn: (locale: string) => Promise<readonly StaticArtifact[]>,
 ): Promise<readonly LocalizedArtifact[]> {
   const out: LocalizedArtifact[] = [];
@@ -21,7 +21,9 @@ export async function localizedArtifacts(
       out.push({
         ...artifact,
         locale,
-        path: isDefault ? artifact.path : localizedPath(artifact.path, locale, defaultLocale),
+        path: isDefault
+          ? artifact.path
+          : localizePath(artifact.path, locale, locales, defaultLocale),
         outputPath: isDefault
           ? artifact.outputPath
           : `${localeSegment(locale)}/${artifact.outputPath}`,

package/src/prerender-report.ts

@@ -0,0 +1,58 @@
+// What `x build --target static` reports: every page it wrote, every route it did not and why, and
+// where the stats and the inventory landed. Split from `prerender.ts`, which decides what is
+// written; this file only names the shapes the report carries.
+
+import type { SkippedRoute, UnmeasuredRoute } from './static-report';
+
+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;
+}

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,21 +5,21 @@
 
 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';
@@ -27,13 +27,16 @@ 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';
@@ -48,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 };
 
 /**
@@ -75,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
@@ -187,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[] = [];
@@ -238,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.
@@ -247,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);
@@ -292,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
@@ -307,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),
     );
 
@@ -352,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) {
@@ -377,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 },
@@ -431,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);
     }
@@ -455,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

@@ -21,6 +21,7 @@ import type { PwaColors, PwaOfflineConfig } 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,
@@ -79,6 +80,11 @@ export interface PwaArtifacts {
   readonly offline: PwaOfflineConfig;
   readonly backgroundSync: boolean;
   readonly push: boolean;
+  /**
+   * 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. */
@@ -108,7 +114,7 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
     name: pwa.name,
     colors: pwa.colors,
     block: { ...pwa },
-    locales: appLocales({ locales: config.locales, defaultLocale: config.defaultLocale }),
+    locales: appLocales(await appLocaleSet(root)),
     offline: pwa.offline,
     backgroundSync: pwa.backgroundSync,
     push: pwa.push,
@@ -161,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,

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/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