@ultimat3/cli 22.3.1 → 22.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.3.1",
+  "version": "22.3.3",
   "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.1",
-    "@ultimat3/admin": "22.3.1",
-    "@ultimat3/ai": "22.3.1",
-    "@ultimat3/auth": "22.3.1",
-    "@ultimat3/cache": "22.3.1",
-    "@ultimat3/core": "22.3.1",
-    "@ultimat3/db": "22.3.1",
-    "@ultimat3/entity": "22.3.1",
-    "@ultimat3/flags": "22.3.1",
-    "@ultimat3/http": "22.3.1",
-    "@ultimat3/i18n": "22.3.1",
-    "@ultimat3/jobs": "22.3.1",
-    "@ultimat3/mail": "22.3.1",
-    "@ultimat3/manifest": "22.3.1",
-    "@ultimat3/mcp": "22.3.1",
-    "@ultimat3/money": "22.3.1",
-    "@ultimat3/notify": "22.3.1",
-    "@ultimat3/policy": "22.3.1",
-    "@ultimat3/pwa": "22.3.1",
-    "@ultimat3/query": "22.3.1",
-    "@ultimat3/realtime": "22.3.1",
-    "@ultimat3/render": "22.3.1",
-    "@ultimat3/schema": "22.3.1",
-    "@ultimat3/seo": "22.3.1",
-    "@ultimat3/storage": "22.3.1",
-    "@ultimat3/testing": "22.3.1",
-    "@ultimat3/time": "22.3.1",
+    "@ultimat3/action": "22.3.3",
+    "@ultimat3/admin": "22.3.3",
+    "@ultimat3/ai": "22.3.3",
+    "@ultimat3/auth": "22.3.3",
+    "@ultimat3/cache": "22.3.3",
+    "@ultimat3/core": "22.3.3",
+    "@ultimat3/db": "22.3.3",
+    "@ultimat3/entity": "22.3.3",
+    "@ultimat3/flags": "22.3.3",
+    "@ultimat3/http": "22.3.3",
+    "@ultimat3/i18n": "22.3.3",
+    "@ultimat3/jobs": "22.3.3",
+    "@ultimat3/mail": "22.3.3",
+    "@ultimat3/manifest": "22.3.3",
+    "@ultimat3/mcp": "22.3.3",
+    "@ultimat3/money": "22.3.3",
+    "@ultimat3/notify": "22.3.3",
+    "@ultimat3/policy": "22.3.3",
+    "@ultimat3/pwa": "22.3.3",
+    "@ultimat3/query": "22.3.3",
+    "@ultimat3/realtime": "22.3.3",
+    "@ultimat3/render": "22.3.3",
+    "@ultimat3/schema": "22.3.3",
+    "@ultimat3/seo": "22.3.3",
+    "@ultimat3/storage": "22.3.3",
+    "@ultimat3/testing": "22.3.3",
+    "@ultimat3/time": "22.3.3",
     "babel-preset-solid": "^1.9.15"
   }
 }

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/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/revalidated-response.ts

@@ -0,0 +1,38 @@
+// The one answer for a public file whose URL carries NO content hash: cacheable, revalidated on
+// every use, and a 304 when the bytes have not moved. `immutable` belongs to a URL that IS its
+// content (islands, styles, `asset()` files) and to nothing else — a file served immutable under a
+// name that outlives its bytes is a file no client refreshes for a year.
+
+import type { UltimateRequest } from '@ultimat3/http';
+import { etagMatches } from './runtime-storage';
+
+/**
+ * The document's own posture (`@ultimat3/render`'s `render-static.ts`), for the same reason: the
+ * URL says nothing about the bytes, so a cache may keep them and must ask before reusing them.
+ * Written as a header rather than a `CacheHint`, which has no `must-revalidate`.
+ */
+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.
+ */
+export function revalidatedResponse(
+  request: UltimateRequest,
+  body: string | Uint8Array,
+  contentType: string,
+): Response {
+  // 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 headers = {
+    'content-type': contentType,
+    'cache-control': REVALIDATE_CACHE_CONTROL,
+    etag,
+  };
+  if (etagMatches(request.header('if-none-match'), etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(bytes, { headers });
+}

package/src/runtime-assets.ts

@@ -20,6 +20,7 @@ import { faviconRoute } from './favicon';
 import { iconPlan, iconRenderer } from './icon-assets';
 import type { PwaArtifacts } from './pwa-artifacts';
 import { pwaManifestRoute } from './pwa-artifacts';
+import { revalidatedResponse } from './revalidated-response';
 import {
   AUTHORIZED_OBJECT_CACHE,
   assertReadableKey,
@@ -41,8 +42,10 @@ import { siteAssetTable } from './site-assets';
 export const MEDIA_BASE_PATH = '/media';
 
 /**
- * A generated icon and a content-addressed variant answer forever with the same bytes, so the
- * immutable hint is a fact about the key. It is NOT a fact about this route — see `mediaCache`.
+ * A content-addressed variant answers forever with the same bytes, so the immutable hint is a fact
+ * about the key. It is NOT a fact about this route — see `mediaCache`. The generated ICONS are not
+ * content-addressed (`/icons/icon-192.png` names a size, not bytes), so they revalidate instead —
+ * see `revalidatedResponse`.
  */
 const IMMUTABLE_IMAGE: CacheHint = { mode: 'immutable' };
 
@@ -198,8 +201,12 @@ export function assetRoutes(options: AssetRoutesOptions): readonly Route[] {
     method: 'GET',
     path: entry.outputPath,
     meta: { name: `assets.icon.${entry.spec.filename}`, auth: 'public', tags: ['assets'] },
+    // Revalidated, never `immutable` (22.3.2): the file name is the icon's SIZE, so a new
+    // `icon.png` shipped under the same URLs and every client that had seen the old one kept it for
+    // a year. The manifest and the apple-touch links name these paths, so a hashed URL would move
+    // every document and the manifest with it; a 304 is the cheaper fix.
     handler: async (request: UltimateRequest): Promise<Response> =>
-      imageResponse(await render(plan, request.pathname), 'image/png', IMMUTABLE_IMAGE),
+      revalidatedResponse(request, await render(plan, request.pathname), 'image/png'),
   }));
   // The icons above are genuinely public — they are rendered from a file committed in the app, and
   // an install prompt fetches them before anyone has signed in. `/media` is the opposite: it serves

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/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';
@@ -23,10 +29,13 @@ export const SW_SCOPE = '/';
  */
 export const SW_REGISTER_PATH = '/x-sw-register.js';
 
+/** How long a returning tab waits between two `sw.js` update checks — five minutes. */
+export const SW_UPDATE_INTERVAL_MS = 300_000;
+
 export interface ServiceWorkerArtifacts {
   /** `sw.js`, deterministic for identical input. */
   readonly source: string;
-  /** `x-sw-register.js`, the four lines that install it. */
+  /** `x-sw-register.js`, the lines that install it and look for its successor. */
   readonly register: string;
   /** The `<script src>` tag, appended to `PwaArtifacts.head` by every surface that serves it. */
   readonly head: string;
@@ -63,95 +72,50 @@ 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.
+ * 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
+ * change to where the file is served is a build-time refusal (`assertScope`) instead of a worker
+ * that silently controls a subdirectory. The `catch` because a registration that throws in a
+ * browser with service workers disabled — an incognito profile, an enterprise policy — must not
+ * take an otherwise working page down with it.
  *
- * 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));
-
-/**
- * Four lines, and every one of them earns it. `load` because registration competes with the page's
- * own first paint for the same network. `scope: '/'` stated rather than inferred, so a change to
- * where the file is served is a build-time refusal (`assertScope`) instead of a worker that
- * silently controls a subdirectory. The `catch` because a registration that throws in a browser
- * with service workers disabled — an incognito profile, an enterprise policy — must not take an
- * otherwise working page down with it.
+ * `registration.update()` when a hidden tab comes back, at most once per `SW_UPDATE_INTERVAL_MS`
+ * (22.3.2). A browser checks for a new `sw.js` on a NAVIGATION; a tab left open for days makes
+ * none, so the new worker was found only on the click that was already answered by the old one. The
+ * throttle keeps an alt-tabbing reader from re-downloading the worker on every focus, and the
+ * swallowed rejection is the offline case. It never posts `skip-waiting` and never reloads: the
+ * worker skips waiting itself (`@ultimat3/pwa`'s install block), and a reload under a reader who is
+ * typing is the one thing an update must not do — the next navigation gets the new HTML.
  *
  * EXPORTED because a static export has to put these bytes on disk BEFORE it renders, not after.
  * The file is named by every document and weighed by `measureDocumentJs`, and it used to be
  * written last, beside `sw.js` — so the measurement read a file that did not exist yet on a clean
  * output directory, and the PREVIOUS build's copy on a reused one. `sw.js` still comes last, for
  * the reason its own comment gives (its precache manifest is built from the rendered documents'
- * content hashes); this half depends on nothing but two constants, so it can and must come first.
+ * content hashes); this half depends on nothing but constants, so it can and must come first.
  */
 export const serviceWorkerRegistration = (): string =>
   `if ('serviceWorker' in navigator) {
   addEventListener('load', function () {
     navigator.serviceWorker
       .register(${JSON.stringify(SERVICE_WORKER_PATH)}, { scope: ${JSON.stringify(SW_SCOPE)} })
+      .then(function (registration) {
+        var checked = Date.now();
+        document.addEventListener('visibilitychange', function () {
+          if (document.visibilityState !== 'visible') return;
+          if (Date.now() - checked < ${SW_UPDATE_INTERVAL_MS}) return;
+          checked = Date.now();
+          registration.update().catch(function () {});
+        });
+      })
       .catch(function (error) { console.warn('service worker registration failed', error); });
   });
 }
@@ -192,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
         ? {}
@@ -208,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));
+}

package/src/sw-routes.ts

@@ -2,8 +2,9 @@
 // Split from the emitter because mounting is HTTP and generation is a build: `prerender.ts` writes
 // both artifacts as files and mounts nothing, and it must not have to import a route table to do it.
 
-import type { CacheHint, Route } from '@ultimat3/http';
+import type { CacheHint, Route, UltimateRequest } from '@ultimat3/http';
 import { applyCacheHeaders } from '@ultimat3/http';
+import { revalidatedResponse } from './revalidated-response';
 import type { ServiceWorkerArtifacts } from './sw-artifacts';
 import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts';
 
@@ -15,9 +16,6 @@ import { SERVICE_WORKER_PATH, SW_REGISTER_PATH, SW_SCOPE } from './sw-artifacts'
  */
 const SW_CACHE: CacheHint = { mode: 'private', maxAgeSeconds: 0 };
 
-/** Content-addressed in neither path, so the register script gets the favicon's hour. */
-const REGISTER_CACHE: CacheHint = { mode: 'public', maxAgeSeconds: 3600 };
-
 /** `/sw.js` and `/x-sw-register.js`, mounted by `x dev` and by the container alike. */
 export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly Route[] => [
   {
@@ -42,12 +40,11 @@ export const serviceWorkerRoutes = (artifacts: ServiceWorkerArtifacts): readonly
     method: 'GET',
     path: SW_REGISTER_PATH,
     meta: { name: 'pwa.serviceWorkerRegister', auth: 'public' },
-    handler: () =>
-      applyCacheHeaders(
-        new Response(artifacts.register, {
-          headers: { 'content-type': 'text/javascript; charset=utf-8' },
-        }),
-        REGISTER_CACHE,
-      ),
+    // Revalidated on every load, never an hour (22.3.2). The URL carries no content hash — it is
+    // named by every document, so hashing it would re-render them all for a four-line script — and
+    // at `max-age=3600` a changed register script reached a returning visitor up to an hour late.
+    // A strong ETag makes the check a 304. Still an EXTERNAL script: see `SW_REGISTER_PATH`.
+    handler: (request: UltimateRequest) =>
+      revalidatedResponse(request, artifacts.register, 'text/javascript; charset=utf-8'),
   },
 ];