@ultimat3/cli 22.3.2 → 22.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.2",
+  "version": "22.3.4",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.3.2",
-    "@ultimat3/admin": "22.3.2",
-    "@ultimat3/ai": "22.3.2",
-    "@ultimat3/auth": "22.3.2",
-    "@ultimat3/cache": "22.3.2",
-    "@ultimat3/core": "22.3.2",
-    "@ultimat3/db": "22.3.2",
-    "@ultimat3/entity": "22.3.2",
-    "@ultimat3/flags": "22.3.2",
-    "@ultimat3/http": "22.3.2",
-    "@ultimat3/i18n": "22.3.2",
-    "@ultimat3/jobs": "22.3.2",
-    "@ultimat3/mail": "22.3.2",
-    "@ultimat3/manifest": "22.3.2",
-    "@ultimat3/mcp": "22.3.2",
-    "@ultimat3/money": "22.3.2",
-    "@ultimat3/notify": "22.3.2",
-    "@ultimat3/policy": "22.3.2",
-    "@ultimat3/pwa": "22.3.2",
-    "@ultimat3/query": "22.3.2",
-    "@ultimat3/realtime": "22.3.2",
-    "@ultimat3/render": "22.3.2",
-    "@ultimat3/schema": "22.3.2",
-    "@ultimat3/seo": "22.3.2",
-    "@ultimat3/storage": "22.3.2",
-    "@ultimat3/testing": "22.3.2",
-    "@ultimat3/time": "22.3.2",
+    "@ultimat3/action": "22.3.4",
+    "@ultimat3/admin": "22.3.4",
+    "@ultimat3/ai": "22.3.4",
+    "@ultimat3/auth": "22.3.4",
+    "@ultimat3/cache": "22.3.4",
+    "@ultimat3/core": "22.3.4",
+    "@ultimat3/db": "22.3.4",
+    "@ultimat3/entity": "22.3.4",
+    "@ultimat3/flags": "22.3.4",
+    "@ultimat3/http": "22.3.4",
+    "@ultimat3/i18n": "22.3.4",
+    "@ultimat3/jobs": "22.3.4",
+    "@ultimat3/mail": "22.3.4",
+    "@ultimat3/manifest": "22.3.4",
+    "@ultimat3/mcp": "22.3.4",
+    "@ultimat3/money": "22.3.4",
+    "@ultimat3/notify": "22.3.4",
+    "@ultimat3/policy": "22.3.4",
+    "@ultimat3/pwa": "22.3.4",
+    "@ultimat3/query": "22.3.4",
+    "@ultimat3/realtime": "22.3.4",
+    "@ultimat3/render": "22.3.4",
+    "@ultimat3/schema": "22.3.4",
+    "@ultimat3/seo": "22.3.4",
+    "@ultimat3/storage": "22.3.4",
+    "@ultimat3/testing": "22.3.4",
+    "@ultimat3/time": "22.3.4",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -115,6 +115,28 @@ export function resetAppLoad(): void {
   routeSources.clear();
 }
 
+/**
+ * Every module path the app globs match, SORTED. `Bun.Glob` answers in directory order, which is
+ * the filesystem's — ext4 hashes names with a per-filesystem seed — so two pods of one image
+ * imported the app in two orders, registered its stylesheets in two orders, and served two
+ * different `/styles/<hash>.css` for one page (notificado.co, 22.3.2). Import order is the
+ * stylesheet cascade's order, so it must be the same everywhere.
+ */
+export async function appModulePaths(root: string): Promise<readonly string[]> {
+  // Pattern by pattern, as before — only the order WITHIN a pattern was the filesystem's.
+  const found: string[] = [];
+  const seen = new Set<string>();
+  for (const pattern of APP_GLOBS) {
+    const matched: string[] = [];
+    for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
+      if (!seen.has(absolute)) matched.push(absolute);
+      seen.add(absolute);
+    }
+    found.push(...matched.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)));
+  }
+  return found;
+}
+
 export async function loadApp(root: string): Promise<LoadedApp> {
   // Before any import: a stylesheet's surface is read below the app root, never off its absolute
   // path — under the container's `WORKDIR /app` that path's first segment is `app/`, and every
@@ -127,36 +149,34 @@ export async function loadApp(root: string): Promise<LoadedApp> {
   const files: string[] = [];
   const findings: Finding[] = [];
 
-  for (const pattern of APP_GLOBS) {
-    for await (const absolute of new Bun.Glob(pattern).scan({ cwd: root, absolute: true })) {
-      // A SEGMENT, never a substring: an app checked out under
-      // `~/dev/node_modules-experiments/myapp` answered `includes('node_modules')` for every
-      // file it holds, so this loop imported none of them and the app registered nothing.
-      // The ROOT-RELATIVE path is tested, never the absolute one: an app checked out under
-      // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
-      const file = relative(root, absolute).split(sep).join('/');
-      if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
-      if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
-        continue;
-      }
-      // The source is read BEFORE the import, and only on the file's first pass — a rescan of a
-      // registered module reads nothing here. A route entry is bound to the bytes the module was
-      // evaluated from, and a read AFTER the import cannot know which bytes those were: a save
-      // landing between the two bound V1's component to V2's hash, so the next scan saw nothing to
-      // do and served V1 until the save after. Read first, the worst case is one re-import the
-      // next tick, of a file that did change.
-      const snapshot = registered.has(absolute) ? undefined : await Bun.file(absolute).text();
-      let module: Record<string, unknown>;
-      try {
-        module = (await import(absolute)) as Record<string, unknown>;
-      } catch (error) {
-        findings.push({ ...findingFrom(error), at: file });
-        continue;
-      }
-      files.push(file);
-      const finding = await register(absolute, file, module, snapshot);
-      if (finding !== undefined) findings.push(finding);
+  for (const absolute of await appModulePaths(root)) {
+    // A SEGMENT, never a substring: an app checked out under
+    // `~/dev/node_modules-experiments/myapp` answered `includes('node_modules')` for every
+    // file it holds, so this loop imported none of them and the app registered nothing.
+    // The ROOT-RELATIVE path is tested, never the absolute one: an app checked out under
+    // `~/work/my.test.app` matched `.test.` on every file and loaded none of them.
+    const file = relative(root, absolute).split(sep).join('/');
+    if (hasPathSegment(absolute, 'node_modules') || isTest(file)) continue;
+    if (ENTRY_POINT.test(file) || CLIENT_ENTRY_POINT.test(file) || STATES_FILE.test(file)) {
+      continue;
+    }
+    // The source is read BEFORE the import, and only on the file's first pass — a rescan of a
+    // registered module reads nothing here. A route entry is bound to the bytes the module was
+    // evaluated from, and a read AFTER the import cannot know which bytes those were: a save
+    // landing between the two bound V1's component to V2's hash, so the next scan saw nothing to
+    // do and served V1 until the save after. Read first, the worst case is one re-import the
+    // next tick, of a file that did change.
+    const snapshot = registered.has(absolute) ? undefined : await Bun.file(absolute).text();
+    let module: Record<string, unknown>;
+    try {
+      module = (await import(absolute)) as Record<string, unknown>;
+    } catch (error) {
+      findings.push({ ...findingFrom(error), at: file });
+      continue;
     }
+    files.push(file);
+    const finding = await register(absolute, file, module, snapshot);
+    if (finding !== undefined) findings.push(finding);
   }
 
   files.sort();

package/src/dev-route-table.ts

@@ -124,7 +124,9 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
       persisted: sync.persisted,
       themeHead: theme.head,
       ...(origin === undefined ? {} : { origin }),
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+      ...(pwa === undefined
+        ? {}
+        : { pwaHead: (locale: string) => pwa.headFor(locale) + (serviceWorker?.head ?? '') }),
     }),
   ];
 

package/src/island-routes.ts

@@ -3,7 +3,7 @@
 // would be a page that boots in `x dev` and 404s in the image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
 import type { IslandBundle } from './island-bundle';
 import { ISLAND_BASE_PATH } from './island-bundle';
 
@@ -28,7 +28,7 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
       handler: (request: UltimateRequest): Response => {
         const chunk = source().chunkAt(request.pathname);
         if (chunk === undefined) {
-          return json(
+          const missing = json(
             {
               ok: false,
               error: {
@@ -45,6 +45,8 @@ export function islandRoutes(source: IslandSource): readonly Route[] {
             },
             { status: 404 },
           );
+          // `no-store`: a miss on a content-hashed URL must not be pinned by a CDN or a proxy.
+          return applyCacheHeaders(missing, NO_STORE);
         }
         return applyCacheHeaders(
           new Response(chunk.code, { headers: { 'content-type': 'text/javascript' } }),

package/src/island-store.ts

@@ -7,11 +7,12 @@
 // that names a different set of islands than the app has, or a chunk whose bytes do not hash to
 // what the index recorded is refused, and the boot builds instead — with the reason logged.
 
-import { join } from 'node:path'; // why: Bun ships no path-join primitive.
+import { join, relative, sep } from 'node:path'; // why: Bun ships no path-join primitive.
 import { frameworkVersion, logger } from '@ultimat3/core';
-import { contentHash } from '@ultimat3/render/server';
+import { contentHash, loadStylesheet } from '@ultimat3/render/server';
 import type { IslandBundle, IslandChunk } from './island-bundle';
 import { buildIslands, discoverIslands, islandBundle } from './island-bundle';
+import { islandStylesheets } from './island-styles';
 
 /** App-root-relative: `COPY . .` carries it into the image with the rest of `.x/`. */
 export const ISLAND_STORE_DIR = '.x/islands';
@@ -28,6 +29,13 @@ interface StoreIndex {
   readonly framework: string;
   readonly bun: string;
   readonly chunks: readonly StoredChunk[];
+  /**
+   * The stylesheets the island build registered, app-relative and sorted. Registered again at boot
+   * from the app's own sources, so a container serving these chunks joins the SAME surface
+   * stylesheet a build would — without them an island-only sheet was missing from every pod that
+   * read the store, and present on any that rebuilt.
+   */
+  readonly stylesheets: readonly string[];
 }
 
 const chunkFile = (url: string): string => url.slice(url.lastIndexOf('/') + 1);
@@ -50,7 +58,16 @@ export async function writeIslandStore(
       identity: contentHash(chunk.code),
     });
   }
-  const index: StoreIndex = { framework: frameworkVersion(), bun: Bun.version, chunks };
+  const stylesheets = islandStylesheets()
+    .map((path) => relative(root, path).split(sep).join('/'))
+    .filter((path) => !path.startsWith('..'))
+    .sort();
+  const index: StoreIndex = {
+    framework: frameworkVersion(),
+    bun: Bun.version,
+    chunks,
+    stylesheets,
+  };
   await Bun.write(join(dir, INDEX), `${JSON.stringify(index, null, 2)}\n`);
   return [...written, `${ISLAND_STORE_DIR}/${INDEX}`];
 }
@@ -74,7 +91,10 @@ function parseIndex(value: unknown): StoreIndex | undefined {
       return undefined;
     parsed.push({ file, moduleId, url, identity });
   }
-  return { framework: record['framework'], bun: record['bun'], chunks: parsed };
+  const sheets = record['stylesheets'];
+  // Absent in a 22.3.2 store: read as none, and the boot builds when it matters (see below).
+  const stylesheets = Array.isArray(sheets) ? sheets.filter(isString) : [];
+  return { framework: record['framework'], bun: record['bun'], chunks: parsed, stylesheets };
 }
 
 /** A verified store, or the one sentence saying why it cannot be served. */
@@ -113,6 +133,13 @@ export async function readIslandStore(root: string): Promise<StoreRead> {
       bytes: new TextEncoder().encode(code).byteLength,
     });
   }
+  // In sorted order, as `island` sheets: `stylesFor` orders those by path, so this is the same
+  // surface stylesheet the build that wrote the store joined.
+  for (const sheet of index.stylesheets) {
+    const source = Bun.file(join(root, sheet));
+    if (!(await source.exists())) return { stale: `${sheet}, an island stylesheet, is missing` };
+    loadStylesheet(join(root, sheet), await source.text(), 'island');
+  }
   return { bundle: islandBundle(chunks) };
 }
 

package/src/island-styles.ts

@@ -16,6 +16,16 @@ import { IslandBuildFailedError } from './errors';
  */
 const STYLESHEET = /\.s?css$/;
 
+/**
+ * Every stylesheet an island build has loaded in this process, absolute. `x build --target docker`
+ * writes them into the island store, so a container that serves the stored chunks registers the
+ * same sheets a build would have — and every pod of one image joins the same surface stylesheet.
+ */
+const islandSheets = new Set<string>();
+
+/** Sorted, so the store index is byte-identical for identical input. */
+export const islandStylesheets = (): readonly string[] => [...islandSheets].sort();
+
 /**
  * `loadStylesheet`, not `compileStylesheet`: compiling alone answers the class names and drops the
  * RULES on the floor, and an island is the one importer a document's own module graph never sees.
@@ -28,7 +38,8 @@ export const islandStylesPlugin: BunPlugin = {
     build.onLoad({ filter: STYLESHEET }, async ({ path }) => {
       const source = await Bun.file(path).text();
       try {
-        return { contents: loadStylesheet(path, source), loader: 'js' };
+        islandSheets.add(path);
+        return { contents: loadStylesheet(path, source, 'island'), loader: 'js' };
       } catch (error) {
         // A coded failure already names the file and carries a fix — re-wrapping it would bury
         // both. Anything else is rendered through `renderThrowable`, because this is the plugin's

package/src/prerender.ts

@@ -29,7 +29,7 @@ import { measurePaths } from './measure-paths';
 import { measureScope, withAppUrl } from './measure-scope';
 import { localizedArtifacts } from './prerender-locales';
 import { clearPrerenderOut } from './prerender-out';
-import { loadPwaArtifacts, WEB_MANIFEST_PATH, writePwaIcons } from './pwa-artifacts';
+import { loadPwaArtifacts, writePwaIcons } from './pwa-artifacts';
 import { routeDocument } from './runtime-render';
 import { writeSiteAssets } from './site-assets';
 import { loadSiteSettings, originWarning, publicOrigin } from './site-config';
@@ -249,7 +249,11 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
     await Bun.write(join(options.out, SW_REGISTER_PATH.slice(1)), serviceWorkerRegistration());
   }
   if (pwa !== undefined) {
-    await Bun.write(join(options.out, WEB_MANIFEST_PATH.slice(1)), pwa.body);
+    // One per routed locale — `/en/manifest.webmanifest` beside the default one — each at the
+    // path its own documents link.
+    for (const manifest of pwa.manifests) {
+      await Bun.write(join(options.out, manifest.path.slice(1)), manifest.body);
+    }
     // And the icons that manifest NAMES. A static host runs no `assetRoutes()`, so every
     // `/icons/*` entry would be a 404 in the install prompt — the manifest half of the same
     // promise `favicon.ico` above keeps. Nothing when the app committed no source icon, which is
@@ -285,7 +289,9 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
       resolveIsland: (file: string) => islands.resolverFor(file),
       themeHead: theme.head,
       origin,
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (swHead ?? '') }),
+      ...(pwa === undefined
+        ? {}
+        : { pwaHead: (locale: string) => pwa.headFor(locale) + (swHead ?? '') }),
     });
   const document = (
     locale: string,
@@ -391,10 +397,15 @@ export async function prerenderSite(options: PrerenderOptions): Promise<Prerende
         // so the precache revision and the HTTP validator can never disagree about one document.
         // Keyed by the FILLED path, which for a non-dynamic route is the declared one; a dynamic
         // route is not precached as a single URL anyway (`buildPrecacheManifest` skips it).
-        documents.set(artifact.path, { revision: artifact.hash, bytes });
         // Measured from the document that was just written, so the `budgets` step compares a
         // declared budget against bytes that exist on disk rather than against a graph's estimate.
         const measured = await measureDocumentJs(artifact.html, options.out);
+        // `assets` too: the chunks this page names are the ones the worker precaches with it.
+        documents.set(artifact.path, {
+          revision: artifact.hash,
+          bytes,
+          assets: measured.entries.map((entry) => entry.url),
+        });
         const chain = heaviestSource(islands, measured.entries);
         if (heaviest !== undefined && heaviest.jsBytes >= measured.jsBytes) continue;
         heaviest = {

package/src/pwa-artifacts.ts

@@ -23,7 +23,8 @@ import { existsSync } from 'node:fs';
 // necessity `favicon.ts` and `runtime-assets.ts` each record for their own root-relative constant.
 import { join } from 'node:path';
 import type { PwaColors, PwaOfflineConfig } from '@ultimat3/core';
-import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
+import { localeSegment } from '@ultimat3/core';
+import type { CacheHint, RequestContext, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
 import {
   appleTouchLinks,
@@ -35,6 +36,8 @@ import { escapeAttribute } from '@ultimat3/seo';
 import { APP_CONFIG_EXPORT } from './app-auth';
 import { APP_CONFIG_FILE } from './app-root';
 import { hasSourceIcon, iconPlan, iconRenderer } from './icon-assets';
+import type { AppLocales } from './pwa-manifest-locales';
+import { appLocales, localeMembers, spellIn } from './pwa-manifest-locales';
 
 /** What a browser fetches from `<link rel="manifest">`. The spec's own extension, not `.json`. */
 export const WEB_MANIFEST_PATH = '/manifest.webmanifest';
@@ -45,9 +48,18 @@ export const WEB_MANIFEST_PATH = '/manifest.webmanifest';
  */
 const MANIFEST_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
 
+/** One routed locale's manifest: where it is served, its bytes, and the `<head>` that names it. */
+export interface LocalizedManifest {
+  readonly locale: string;
+  /** `/manifest.webmanifest` for the default locale, `/en/manifest.webmanifest` for `en`. */
+  readonly path: string;
+  readonly body: string;
+  readonly head: string;
+}
+
 /** The two strings every surface needs: the file's bytes, and what `<head>` must carry to name it. */
 export interface PwaArtifacts {
-  /** `manifest.webmanifest`, serialized. */
+  /** The DEFAULT locale's `manifest.webmanifest`, serialized — `manifests[0].body`. */
   readonly body: string;
   /**
    * `<link rel="manifest">`, both `theme-color` metas, and every apple-touch icon link. One string
@@ -56,6 +68,14 @@ export interface PwaArtifacts {
    * no manifest is an iOS icon for an app iOS will not add.
    */
   readonly head: string;
+  /**
+   * One manifest per routed locale, default first. Each speaks its own `lang`, starts at its own
+   * home and spells its shortcuts in its own locale; one `id` makes them one installed app. There
+   * was one manifest, `lang: "en"`, for an `es-co` app with an English half (22.3.2).
+   */
+  readonly manifests: readonly LocalizedManifest[];
+  /** 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
@@ -102,6 +122,9 @@ function colorsOf(value: unknown): PwaColors | undefined {
 interface InstallableApp {
   readonly name: string;
   readonly colors: PwaColors;
+  /** The block itself, for the manifest members `pwa-manifest-locales.ts` reads per locale. */
+  readonly block: Record<string, unknown>;
+  readonly locales: AppLocales;
   readonly offline: PwaOfflineConfig;
   readonly backgroundSync: boolean;
   readonly push: boolean;
@@ -121,7 +144,14 @@ async function loadInstallable(root: string): Promise<InstallableApp | undefined
   const name = text(pwa['name']);
   const colors = colorsOf(pwa['colors']);
   if (name === undefined || colors === undefined) return undefined;
-  return { name, colors, offline: offlineOf(pwa['offline']), ...flags(pwa) };
+  return {
+    name,
+    colors,
+    block: pwa,
+    locales: appLocales(config),
+    offline: offlineOf(pwa['offline']),
+    ...flags(pwa),
+  };
 }
 
 /**
@@ -142,6 +172,7 @@ function offlineOf(value: unknown): PwaOfflineConfig {
     neverCache: Array.isArray(patterns)
       ? patterns.filter((entry): entry is string => typeof entry === 'string')
       : [],
+    personalPages: block['personalPages'] === 'last-member' ? 'last-member' : 'never',
   };
 }
 
@@ -172,23 +203,47 @@ export async function loadPwaArtifacts(root: string): Promise<PwaArtifacts | und
   // own rule forbids. Read at boot, like the rest of this function: adding the file takes effect
   // on the next start, because the manifest is generated once and served as bytes.
   const icons = (await hasSourceIcon(root)) ? iconPlan() : undefined;
-  const result = generateWebManifest({
-    name: app.name,
-    tokens: app.colors,
-    icons: icons?.manifestIcons ?? [],
+  const manifests = app.locales.routed.map((locale): LocalizedManifest => {
+    const result = generateWebManifest({
+      name: app.name,
+      tokens: app.colors,
+      icons: icons?.manifestIcons ?? [],
+      ...localeMembers(app.block, locale, app.locales),
+    });
+    const path = spellIn(WEB_MANIFEST_PATH, locale, app.locales);
+    return {
+      locale,
+      path,
+      body: serializeWebManifest(result.manifest),
+      head:
+        `<link rel="manifest" href="${escapeAttribute(path)}">` +
+        renderThemeColorMeta(result.themeColorMeta) +
+        (icons === undefined ? '' : appleTouchLinks(icons)),
+    };
   });
+  // `routed` always holds the default first, so this is never undefined; the guard is the type's.
+  const primary = manifests[0];
+  if (primary === undefined) return undefined;
   return {
     offline: app.offline,
     backgroundSync: app.backgroundSync,
     push: app.push,
-    body: serializeWebManifest(result.manifest),
-    head:
-      `<link rel="manifest" href="${escapeAttribute(WEB_MANIFEST_PATH)}">` +
-      renderThemeColorMeta(result.themeColorMeta) +
-      (icons === undefined ? '' : appleTouchLinks(icons)),
+    body: primary.body,
+    head: primary.head,
+    manifests,
+    headFor: (locale: string): string => manifestIn(manifests, locale)?.head ?? primary.head,
   };
 }
 
+/** The manifest `locale` names, by URL segment (`es-CO` is `es-co`), if the app routes it. */
+const manifestIn = (
+  manifests: readonly LocalizedManifest[],
+  locale: string | undefined,
+): LocalizedManifest | undefined =>
+  locale === undefined
+    ? undefined
+    : manifests.find((manifest) => localeSegment(manifest.locale) === localeSegment(locale));
+
 /**
  * The icon bytes a STATIC export has to carry, written under `out`. Answers the paths it wrote.
  *
@@ -219,10 +274,18 @@ export async function writePwaIcons(root: string, out: string): Promise<readonly
 export const pwaManifestRoute = (artifacts: PwaArtifacts): Route => ({
   method: 'GET',
   path: WEB_MANIFEST_PATH,
-  meta: { name: 'assets.manifest', auth: 'public', cache: MANIFEST_CACHE, tags: ['assets'] },
-  handler: async (_request: UltimateRequest): Promise<Response> =>
+  // `'path'`: `/en/manifest.webmanifest` reaches this route with its prefix split off and `en` as the
+  // locale, and the bare path is the default locale's — never negotiated, so a CDN may cache both.
+  meta: {
+    name: 'assets.manifest',
+    auth: 'public',
+    cache: MANIFEST_CACHE,
+    tags: ['assets'],
+    localeSource: 'path',
+  },
+  handler: async (_request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
     applyCacheHeaders(
-      new Response(artifacts.body, {
+      new Response(manifestIn(artifacts.manifests, ctx.locale)?.body ?? artifacts.body, {
         headers: { 'content-type': 'application/manifest+json; charset=utf-8' },
       }),
       MANIFEST_CACHE,

package/src/pwa-manifest-locales.ts

@@ -0,0 +1,147 @@
+// The manifest members an app declares beyond `name` and `colors`, spelled for ONE locale: its
+// `lang`, its `start_url`, its text and its shortcut URLs. `pwa-artifacts.ts` builds one manifest per
+// routed locale from this; the `pwa` block is read structurally, for `colorsOf`'s reason there.
+
+import { localeSegment, localizePath } from '@ultimat3/core';
+import type {
+  ManifestIcon,
+  ManifestScreenshot,
+  ManifestShortcut,
+  WebManifestInput,
+} from '@ultimat3/pwa';
+
+/** The app's locales as `app.config.ts` declares them, default first. */
+export interface AppLocales {
+  readonly routed: readonly string[];
+  readonly fallback: string;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+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`.
+ */
+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));
+  return { routed: [fallback, ...others], fallback };
+}
+
+/** `path` as `locale` spells it — `/en/panel` — by core's one arithmetic, the one `http` routes. */
+export const spellIn = (path: string, locale: string, locales: AppLocales): string =>
+  localizePath(path, locale, locales.routed, locales.fallback);
+
+/**
+ * `PwaText`: a string is every locale's; a record answers `locale`, then the default locale. A
+ * value that is neither — or a record naming neither — is absent, never `'undefined'`.
+ */
+function textIn(value: unknown, locale: string, locales: AppLocales): string | undefined {
+  if (typeof value === 'string') return value.trim() === '' ? undefined : value;
+  if (!isRecord(value)) return undefined;
+  for (const key of [locale, locales.fallback]) {
+    const entry = value[key];
+    if (typeof entry === 'string' && entry.trim() !== '') return entry;
+  }
+  return undefined;
+}
+
+const PURPOSES = new Set(['any', 'maskable', 'monochrome']);
+
+function iconsOf(value: unknown): readonly ManifestIcon[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((icon): readonly ManifestIcon[] => {
+    if (!isRecord(icon)) return [];
+    const { src, sizes, type, purpose } = icon;
+    if (typeof src !== 'string' || typeof sizes !== 'string' || typeof type !== 'string') return [];
+    return [
+      {
+        src,
+        sizes,
+        type,
+        ...(typeof purpose === 'string' && PURPOSES.has(purpose)
+          ? { purpose: purpose as NonNullable<ManifestIcon['purpose']> }
+          : {}),
+      },
+    ];
+  });
+}
+
+function shortcutsIn(value: unknown, locale: string, locales: AppLocales): ManifestShortcut[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((shortcut): ManifestShortcut[] => {
+    if (!isRecord(shortcut) || typeof shortcut['url'] !== 'string') return [];
+    const name = textIn(shortcut['name'], locale, locales);
+    if (name === undefined) return [];
+    const shortName = textIn(shortcut['shortName'], locale, locales);
+    const description = textIn(shortcut['description'], locale, locales);
+    const icons = iconsOf(shortcut['icons']);
+    return [
+      {
+        name,
+        ...(shortName === undefined ? {} : { short_name: shortName }),
+        ...(description === undefined ? {} : { description }),
+        url: spellIn(shortcut['url'], locale, locales),
+        ...(icons.length === 0 ? {} : { icons }),
+      },
+    ];
+  });
+}
+
+function screenshotsIn(value: unknown, locale: string, locales: AppLocales): ManifestScreenshot[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((shot): ManifestScreenshot[] => {
+    if (!isRecord(shot)) return [];
+    const src = textIn(shot['src'], locale, locales);
+    const { sizes, type, formFactor } = shot;
+    if (src === undefined || typeof sizes !== 'string' || typeof type !== 'string') return [];
+    const label = textIn(shot['label'], locale, locales);
+    return [
+      {
+        src,
+        sizes,
+        type,
+        ...(formFactor === 'narrow' || formFactor === 'wide' ? { form_factor: formFactor } : {}),
+        ...(label === undefined ? {} : { label }),
+      },
+    ];
+  });
+}
+
+type LocaleMembers = Pick<
+  WebManifestInput,
+  'lang' | 'id' | 'startUrl' | 'description' | 'categories' | 'shortcuts' | 'screenshots'
+>;
+
+/**
+ * Everything one locale's manifest says beyond name, colours and icons. `id` is the SAME in every
+ * locale — the scope unless the app names one — so a browser sees one app installed from either
+ * language rather than two; `start_url` is that locale's home.
+ */
+export function localeMembers(
+  pwa: Record<string, unknown>,
+  locale: string,
+  locales: AppLocales,
+): LocaleMembers {
+  const description = textIn(pwa['description'], locale, locales);
+  const categories = strings(pwa['categories']);
+  const shortcuts = shortcutsIn(pwa['shortcuts'], locale, locales);
+  const screenshots = screenshotsIn(pwa['screenshots'], locale, locales);
+  const id = pwa['id'];
+  return {
+    lang: locale,
+    id: typeof id === 'string' && id.startsWith('/') ? id : '/',
+    startUrl: spellIn('/', locale, locales),
+    ...(description === undefined ? {} : { description }),
+    ...(categories.length === 0 ? {} : { categories }),
+    ...(shortcuts.length === 0 ? {} : { shortcuts }),
+    ...(screenshots.length === 0 ? {} : { screenshots }),
+  };
+}

package/src/runtime-render.ts

@@ -88,7 +88,7 @@ export interface DocumentOptions {
    * projects per-route SEO. Passed through `DocumentOptions` for `resolveIsland`'s reason — the
    * boot knows it, the renderer cannot ask.
    */
-  readonly pwaHead?: string;
+  readonly pwaHead?: string | ((locale: string) => string);
   /**
    * The no-flash theme `<script>` from `theme-boot.ts`, or absent for a caller that renders no
    * documents a browser paints. Document-level for `pwaHead`'s reason — the same tag on every page,
@@ -176,7 +176,8 @@ const headFor = async (
       ),
     ) +
     (options.themeHead ?? '') +
-    (options.pwaHead ?? '')
+    // Per locale: each links its own locale's manifest (`PwaArtifacts.headFor`).
+    (typeof options.pwaHead === 'function' ? options.pwaHead(meta.locale) : (options.pwaHead ?? ''))
   );
 };
 

package/src/serve-boot.ts

@@ -189,7 +189,9 @@ async function webSurface(
       persisted: sync.persisted,
       themeHead: theme.head,
       ...(origin === undefined ? {} : { origin }),
-      ...(pwa === undefined ? {} : { pwaHead: pwa.head + (serviceWorker?.head ?? '') }),
+      ...(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.

package/src/style-bundle.ts

@@ -72,15 +72,37 @@ let memo: { readonly revision: number; readonly bundle: StyleBundle } | undefine
 export function styleBundle(): StyleBundle {
   const revision = stylesheetsRevision();
   if (memo !== undefined && memo.revision === revision) return memo.bundle;
-  const bundle = styleBundleOf(
+  const current = styleBundleOf(
     STYLED_SURFACES.map((surface) => ({ surface, css: stylesFor(surface) })).filter(
       (sheet) => sheet.css.length > 0,
     ),
   );
+  for (const chunk of current.chunks) {
+    minted.delete(chunk.url);
+    minted.set(chunk.url, chunk);
+  }
+  while (minted.size > MINTED_KEPT) {
+    const oldest = minted.keys().next().value;
+    if (oldest === undefined) break;
+    minted.delete(oldest);
+  }
+  const bundle: StyleBundle = {
+    ...current,
+    chunkAt: (url: string): StyleChunk | undefined => current.chunkAt(url) ?? minted.get(url),
+  };
   memo = { revision, bundle };
   return bundle;
 }
 
+/**
+ * Every stylesheet this process has minted, newest last, so a URL it once linked keeps answering
+ * after the registry moves — a module imported late, an island rebuilt under `x dev`. The worker
+ * precached the boot-time URL and a document rendered a minute ago names it; a 404 there is a page
+ * with no CSS. Bounded, because `x dev` mints one per edit.
+ */
+const minted = new Map<string, StyleChunk>();
+const MINTED_KEPT = 32;
+
 /**
  * Test seam, and the shape `islandBundle` has: a table built from what the caller supplies.
  *

package/src/style-routes.ts

@@ -4,7 +4,7 @@
 // image.
 
 import type { Route, UltimateRequest } from '@ultimat3/http';
-import { applyCacheHeaders, json } from '@ultimat3/http';
+import { applyCacheHeaders, json, NO_STORE } from '@ultimat3/http';
 import type { StyleBundle } from './style-bundle';
 import { STYLE_BASE_PATH } from './style-bundle';
 
@@ -32,7 +32,7 @@ export function styleRoutes(source: StyleSource): readonly Route[] {
       handler: (request: UltimateRequest): Response => {
         const chunk = source().chunkAt(request.pathname);
         if (chunk === undefined) {
-          return json(
+          const missing = json(
             {
               ok: false,
               error: {
@@ -45,6 +45,8 @@ export function styleRoutes(source: StyleSource): readonly Route[] {
             },
             { status: 404 },
           );
+          // `no-store`: a miss on a content-hashed URL must not be pinned by a CDN or a proxy.
+          return applyCacheHeaders(missing, NO_STORE);
         }
         return applyCacheHeaders(
           new Response(chunk.css, { headers: { 'content-type': 'text/css; charset=utf-8' } }),

package/src/sw-artifacts.ts

@@ -3,13 +3,19 @@
 // until #390. Beside `pwa-artifacts.ts` and not inside it: that file needs a root and a config
 // file, this one needs a booted app and a finished build.
 
-import type { PrecacheAsset, PrecacheManifest, PwaRoute } from '@ultimat3/pwa';
+import { localeConfig, routedLocales } from '@ultimat3/i18n';
+import type { PrecacheManifest } from '@ultimat3/pwa';
 import { generateServiceWorker } from '@ultimat3/pwa';
 import type { RouteDescriptor } from '@ultimat3/render';
 import type { IslandBundle } from './island-bundle';
+import { ISLAND_BASE_PATH } from './island-bundle';
 import { msg } from './messages';
 import type { PwaArtifacts } from './pwa-artifacts';
 import type { StyleBundle } from './style-bundle';
+import type { RenderedDocument, RoutedLocales } from './sw-precache-plan';
+import { localePrefixes, precacheAssets, pwaRoutes } from './sw-precache-plan';
+
+export type { RenderedDocument, RoutedLocales } from './sw-precache-plan';
 
 /** Root scope, so `/sw.js` and nothing under a directory — `assertScope` refuses the rest. */
 export const SERVICE_WORKER_PATH = '/sw.js';
@@ -66,75 +72,13 @@ export interface ServiceWorkerInput {
    * offline reload that cannot load the boot restores no record and shows the old count.
    */
   readonly scripts?: readonly { readonly url: string; readonly bytes: number }[];
+  /**
+   * The routed locales, default first. Absent, `@ultimat3/i18n`'s own — the answer the server routes
+   * with, set once the app's catalogs are loaded, which every caller has done by now.
+   */
+  readonly locales?: RoutedLocales;
 }
 
-/**
- * One rendered document, as the precache manifest needs it.
- *
- * `revision` is `contentHash(html)` — `@ultimat3/render`'s own, the function that already stamps
- * an ETag — and never the build id. `precache.ts`' header states the rule and nothing kept it:
- * `pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
- * `{"url":"/","revision":"build-aaa","bytes":0}` and two deploys of a byte-identical site
- * re-fetched every precached document. The zero was the second half — `DEFAULT_PRECACHE_WARN_BYTES`
- * is a 5 MB budget over a total that could not count one byte of HTML.
- */
-export interface RenderedDocument {
-  readonly revision: string;
-  readonly bytes: number;
-}
-
-/**
- * The route table, as the service worker sees it. `api/` is dropped: an API response is a JSON
- * document whose freshness is the app's business, and precaching one serves a stale answer to a
- * client that had a network. Only the fields a browser can act on cross — a descriptor carries
- * budgets and policy flags it has no use for — plus, for a route this build rendered, the content
- * hash and the byte count of the document it produced.
- */
-const pwaRoutes = (
-  routes: readonly RouteDescriptor[],
-  documents: ReadonlyMap<string, RenderedDocument>,
-): readonly PwaRoute[] =>
-  // `flatMap` rather than `filter().map()`: the filter's predicate does not narrow `surface` for
-  // the map that follows it, and `PwaRoute` declares the two navigable surfaces only. A cast would
-  // hide the day a fifth surface arrives.
-  routes.flatMap((route): readonly PwaRoute[] => {
-    // `shared/` is dropped with `api/`, and for a stronger reason: it is not a URL at all — the
-    // surface exists so two routes can import one module, and a browser can never navigate to it.
-    if (route.surface !== 'site' && route.surface !== 'app') return [];
-    // A `Map`, so a route path that happens to spell a prototype member cannot answer with one.
-    const document = documents.get(route.path);
-    return [
-      {
-        path: route.path,
-        surface: route.surface,
-        mode: route.mode,
-        offline: route.offline,
-        dynamic: route.dynamic,
-        // Absent rather than invented for a route no build rendered — an `ssr` page, or one this
-        // pass could not produce. `buildPrecacheManifest` then falls back to the build id, which
-        // is the honest answer when there are no bytes to hash.
-        ...(document === undefined ? {} : { revision: document.revision, bytes: document.bytes }),
-      },
-    ];
-  });
-
-/**
- * Every island chunk and every surface stylesheet, precached. They are content-addressed and
- * served `immutable`, so the revision IS the URL's hash and a byte-identical asset across deploys
- * is never re-downloaded.
- *
- * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
- * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
- */
-const staticAssets = (
-  islands: IslandBundle,
-  styles: StyleBundle,
-  scripts: readonly { readonly url: string; readonly bytes: number }[],
-): readonly PrecacheAsset[] =>
-  [...islands.chunks, ...styles.chunks, ...scripts]
-    .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
-    .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
-
 /**
  * The registration, and every line of it earns its bytes. `load` because registration competes with
  * the page's own first paint for the same network. `scope: '/'` stated rather than inferred, so a
@@ -212,10 +156,13 @@ export function serviceWorkerArtifacts(
   // Absent when this pass did not render the fallback (no route serves it — `x doctor` reports
   // that as `X_PWA_NO_OFFLINE_FALLBACK`), and then `@ultimat3/pwa` falls back to the build id.
   const fallbackDocument = documents.get(fallback);
+  const locales = input.locales ?? { routed: routedLocales(), fallback: localeConfig().fallback };
   const output = generateServiceWorker(
-    pwaRoutes(input.routes, documents),
+    pwaRoutes(input.routes, documents, locales),
     {
       scope: SW_SCOPE,
+      runtimeAssets: [`${ISLAND_BASE_PATH}/`],
+      localePrefixes: localePrefixes(locales),
       swPath: SERVICE_WORKER_PATH,
       ...(fallbackDocument === undefined
         ? {}
@@ -228,9 +175,18 @@ export function serviceWorkerArtifacts(
         ...(pwa.offline.image === null ? {} : { image: pwa.offline.image }),
         ...(pwa.offline.font === null ? {} : { font: pwa.offline.font }),
         neverCache: pwa.offline.neverCache,
+        personalPages: pwa.offline.personalPages,
       },
       capabilities: { backgroundSync: pwa.backgroundSync, push: pwa.push },
-      assets: staticAssets(input.islands, input.styles, input.scripts ?? []),
+      assets: precacheAssets({
+        routes: input.routes,
+        documents,
+        locales,
+        islands: input.islands,
+        styles: input.styles,
+        scripts: input.scripts ?? [],
+        fallback,
+      }),
     },
     input.buildId,
   );

package/src/sw-precache-plan.ts

@@ -0,0 +1,145 @@
+// What the service worker is told about: every navigable route spelled once per routed locale, and
+// the precache narrowed to the island chunks a precached page actually boots. Split from
+// `sw-artifacts.ts`, which composes the worker; this file decides its inputs.
+
+import { localeSegment, localizePath } from '@ultimat3/core';
+import type { PrecacheAsset, PwaRoute } from '@ultimat3/pwa';
+import { strategyFor } from '@ultimat3/pwa';
+import type { RouteDescriptor } from '@ultimat3/render';
+import type { IslandBundle } from './island-bundle';
+import type { StyleBundle } from './style-bundle';
+
+/**
+ * One rendered document, as the precache manifest needs it.
+ *
+ * `revision` is `contentHash(html)` — `@ultimat3/render`'s own, the function that already stamps
+ * an ETag — and never the build id. `precache.ts`' header states the rule and nothing kept it:
+ * `pwaRoutes` projected four of `PwaRoute`'s eight fields, so every route entry read
+ * `{"url":"/","revision":"build-aaa","bytes":0}` and two deploys of a byte-identical site
+ * re-fetched every precached document. The zero was the second half — `DEFAULT_PRECACHE_WARN_BYTES`
+ * is a 5 MB budget over a total that could not count one byte of HTML.
+ */
+export interface RenderedDocument {
+  readonly revision: string;
+  readonly bytes: number;
+  /**
+   * The same-origin scripts and island entries the document names (`measureDocumentJs`'s
+   * `entries`), so a precached page's islands are precached with it and no other page's are.
+   */
+  readonly assets?: readonly string[];
+}
+
+/** The app's routed locales, default first — `@ultimat3/i18n`'s `routedLocales()` and fallback. */
+export interface RoutedLocales {
+  readonly routed: readonly string[];
+  readonly fallback: string;
+}
+
+type NavigableRoute = RouteDescriptor & { readonly surface: 'site' | 'app' };
+
+/** `api/` and `shared/` are no document a browser navigates to. */
+const navigable = (route: RouteDescriptor): route is NavigableRoute =>
+  route.surface === 'site' || route.surface === 'app';
+
+const spell = (path: string, locale: string, locales: RoutedLocales): string =>
+  localizePath(path, locale, locales.routed, locales.fallback);
+
+/**
+ * The route table, as the service worker sees it — once per routed locale. The server strips a
+ * `/en/` prefix before it matches (`@ultimat3/http`'s `locale-prefix.ts`), and the worker matches
+ * pathnames: with one spelling per route, no `/en/…` URL had a rule, so the English site was never
+ * cached and never offline (notificado.co, 22.3.2). Only the fields a browser can act on cross,
+ * plus — for a spelling this build rendered — the content hash and byte count of its document.
+ */
+export function pwaRoutes(
+  routes: readonly RouteDescriptor[],
+  documents: ReadonlyMap<string, RenderedDocument>,
+  locales: RoutedLocales,
+): readonly PwaRoute[] {
+  return routes.filter(navigable).flatMap((route) =>
+    locales.routed.map((locale): PwaRoute => {
+      const path = spell(route.path, locale, locales);
+      // A `Map`, so a route path that happens to spell a prototype member cannot answer with one.
+      const document = documents.get(path);
+      return {
+        path,
+        surface: route.surface,
+        mode: route.mode,
+        offline: route.offline,
+        dynamic: route.dynamic,
+        personal: route.personal,
+        // Absent rather than invented for a route no build rendered — an `ssr` page, or one this
+        // pass could not produce. `buildPrecacheManifest` then falls back to the build id.
+        ...(document === undefined ? {} : { revision: document.revision, bytes: document.bytes }),
+      };
+    }),
+  );
+}
+
+/** `['en']` for an `es-co` app routing `es-co` and `en` — the prefixes the default locale has not. */
+export const localePrefixes = (locales: RoutedLocales): readonly string[] =>
+  locales.routed
+    .map(localeSegment)
+    .filter((segment) => segment !== localeSegment(locales.fallback));
+
+const precached = (route: PwaRoute): boolean =>
+  route.offline === 'precache' && route.dynamic !== true && strategyFor(route) !== 'network-only';
+
+export interface PrecacheAssetInput {
+  readonly routes: readonly RouteDescriptor[];
+  readonly documents: ReadonlyMap<string, RenderedDocument>;
+  readonly locales: RoutedLocales;
+  readonly islands: IslandBundle;
+  readonly styles: StyleBundle;
+  readonly scripts: readonly { readonly url: string; readonly bytes: number }[];
+  /** The offline document's path: its islands ride the precache whatever its own route says. */
+  readonly fallback: string;
+}
+
+/**
+ * The island chunks a PRECACHED page boots, every surface stylesheet and every framework script.
+ * Every island in the app was precached, so a first anonymous visit to a marketing page downloaded
+ * the admin, KYC and payment islands too — 43 chunks, ~1 MB on notificado.co (22.3.2). The rest are
+ * cached the first time a page asks for one (`ISLAND_BASE_PATH` is a runtime asset prefix).
+ *
+ * Two readers of "which islands", because only one of them exists per build: the static export
+ * rendered the documents and knows the chunk URLs each one names; `x dev` and the container emit
+ * the worker at boot, before any page has rendered, and resolve each precached route's declared
+ * island `src` against its own file — `island()` is route-module-local by construction.
+ *
+ * Sorted by url, because `buildPrecacheManifest` sorts its own entries but the ASSET list is what
+ * decides which of two equal urls wins, and `sw.js` must be byte-identical for identical input.
+ */
+export function precacheAssets(input: PrecacheAssetInput): readonly PrecacheAsset[] {
+  const wanted = new Set<string>();
+  const paths = new Set(
+    pwaRoutes(input.routes, input.documents, input.locales)
+      .filter(precached)
+      .map((route) => route.path),
+  );
+  for (const locale of input.locales.routed)
+    paths.add(spell(input.fallback, locale, input.locales));
+  for (const path of paths) {
+    for (const url of input.documents.get(path)?.assets ?? []) wanted.add(url);
+  }
+  for (const route of input.routes.filter(navigable)) {
+    const isFallback = route.path === input.fallback;
+    if (!isFallback && !precached(route)) continue;
+    const resolve = input.islands.resolverFor(route.file);
+    for (const src of route.islandSources) {
+      try {
+        wanted.add(resolve(src));
+      } catch {
+        // A src the bundle cannot resolve fails the RENDER that names it, with its own finding;
+        // here it only means there is no chunk to precache.
+      }
+    }
+  }
+  return [
+    ...input.islands.chunks.filter((chunk) => wanted.has(chunk.url)),
+    ...input.styles.chunks,
+    ...input.scripts,
+  ]
+    .map((chunk) => ({ url: chunk.url, revision: chunk.url, bytes: chunk.bytes }))
+    .sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+}