@ultimat3/pwa 24.0.0 → 25.0.0

package/CLAUDE.md

@@ -13,24 +13,25 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Determinism | no `Date.now()`, no randomness, sort every collection. Same input → same bytes. `subscriptionState` took `now = Date.now()` and was the one exception; it takes a `Clock` `As of 2026-08-23`, so a frozen clock freezes this package too. |
 | Rule ORDER | most specific first, then the path. `ruleFor` in the emitted worker returns the FIRST pattern that matches and has no notion of specificity, so the sort IS the routing decision. Alphabetical, `:` (0x3A) and `*` (0x2A) sort before every letter: `/posts/:id` shadowed `/posts/new`, and one `/*` catch-all shadowed the whole table — every `PRECACHE_MANIFEST` entry downloaded at install and never looked up, and a cacheable route served `network-only`, which offline is the `/offline` document. The order is `@ultimat3/core`'s `routeRank` — the ONE route precedence, also `@ultimat3/render`'s `CompiledPattern.specificity`: the request router's order, segment by segment. Never a local copy, never a sum. |
 | A generated header | names something that regenerates the file. `sw.js` says `regenerate: x build`, and `As of 2026-08` a build really writes it (#390); it named the CALL for as long as none did. |
-| What is WIRED, and what is not | **every generator here has a caller, `As of 2026-08`.** `generateWebManifest`, `renderThemeColorMeta`, `planIcons`, `appleTouchLinks` and `BuiltinImagePipeline` through `pwa-artifacts.ts` / `dev-assets.ts` (#362); `generateServiceWorker` — and with it `buildPrecacheManifest`, `offlineFallbackSource`, `backgroundSyncSource` and `pushSource` — through `sw-artifacts.ts` (#390). So `x dev`, the container and the static export emit `manifest.webmanifest`, `sw.js` and `x-sw-register.js` alike. The worker half landed a release later because a bad `sw.js` is sticky: it waited on a real browser check (`packages/cli/e2e/service-worker.e2e.test.ts`), which nothing in the gate could run until #400. **`pwa.push` is the one capability still unwired** — the generator emits a push handler only when a VAPID key comes with it and there is no `pwa.vapid` config key, so `x build` reports it as a `serviceWorkerWarnings` entry rather than dropping it in silence. |
+| What is WIRED, and what is not | **every generator here has a caller, `As of 2026-08`.** `generateWebManifest`, `renderThemeColorMeta`, `planIcons`, `appleTouchLinks` and `BuiltinImagePipeline` through `pwa-artifacts.ts` / `runtime-assets.ts` (#362); `generateServiceWorker` — and with it `buildPrecacheManifest`, `offlineFallbackSource`, `backgroundSyncSource` and `pushSource` — through `sw-artifacts.ts` (#390). So `x dev`, the container and the static export emit `manifest.webmanifest`, `sw.js` and `x-sw-register.js` alike. The worker half landed a release later because a bad `sw.js` is sticky: it waited on a real browser check (`packages/cli/e2e/service-worker.e2e.test.ts`), which nothing in the gate could run until #400. **`pwa.push` is the one capability still unwired** — the generator emits a push handler only when a VAPID key comes with it and there is no `pwa.vapid` config key, so `x build` reports it as a `serviceWorkerWarnings` entry rather than dropping it in silence. |
 | Route input | `PwaRoute` is a **structural** view of render's `RouteDescriptor`. Never import render. |
 | Strategy choice | derived from render mode via `MODE_STRATEGY`. Per-route override only. Every row is `network-first` `As of 22.3.2`: every rule is a DOCUMENT, and `static: 'cache-first'` / `isr`,`stream: 'stale-while-revalidate'` answered online navigations with the old deploy's HTML (and so its old hashed assets) until Shift+F5. Precache ≠ cache-first — the precached copy is the offline answer. |
 | Worker update | `self.skipWaiting()` in `install`, `As of 22.3.2` — worker-side, because the browsers that must converge run a 22.3.1 worker and register script that never post `skip-waiting`. Safe for an open tab: the worker routes no chunk. Never a reload — the next navigation is fresh. The `skip-waiting` message stays. |
 | Navigation preload | enabled on `activate`; every emitted strategy reaches the network through `net(req,pre)` (`NETWORK_SOURCE`), never a bare `fetch`, so a navigation is answered by `event.preloadResponse`. The preload carries no build id: `seenBuild` reads skew off the ANSWER. `fromNetwork` is the exported mirror. `service-worker-preload.test.ts` executes it. |
-| Install fill | `PRECACHE_CONCURRENCY` (4) in flight, never `Promise.all` over the manifest: it runs on the first visit against the connection the first click needs. Still one entry per failure. An answer stamped with another build's `BUILD_ID_HEADER` is not stored (an old pod mid-rollout); an unstamped one is. |
+| Install fill | `PRECACHE_CONCURRENCY` (4) in flight, never `Promise.all` over the manifest: it runs on the first visit against the connection the first click needs. Still one entry per failure. An answer stamped with another build's core `BUILD_ID_HEADER` is not stored (an old pod mid-rollout); an unstamped one is. |
 | Rule patterns | built from the DECODED route path, matched against the PERCENT-ENCODED `url.pathname`: a literal segment goes through the WHATWG serializer (`URL.pathname`, never `encodeURI` — it escapes `\|`, `[`, `^`, `%` a browser leaves literal), either hex case. A catch-all is `(?:/.*)?`, so `/docs/*path` owns `/docs`. `route-rules.test.ts`; the e2e drives both in Chrome. |
 | Runtime assets | `ServiceWorkerConfig.runtimeAssets` prefixes (`/islands/`) are `cache-first` runtime rules AHEAD of every page rule (`assetRules`, `route-rules.ts`), and go to the network as the browser asked — no build-id header, because a classic script is a `no-cors` request whose headers a worker may not extend. The precache names only what a precached page boots (the CLI chooses: `sw-precache-plan.ts`); all 43 islands (~1 MB) were precached on a first anonymous visit until 22.3.3. |
 | Locales | the worker matches pathnames and the server strips `/en/` before it matches, so the CALLER spells every route once per routed locale (`@ultimat3/cli`'s `sw-precache-plan.ts`). `localePrefixes` is only for the offline document: a navigation under `/en/` tries `/en` + `OFFLINE_DOC` first. |
+| What is a navigation | to `offlineFallback`: `mode === 'navigate'`, or the client router's soft visit — a `fetch` carrying `CLIENT_NAVIGATION_HEADER: soft` (core's constant, interpolated). Its `prefetch` is a guess: the 503, or the offline page would be cached as a later click's answer. `offline-fallback.test.ts`. |
 | Precache revision | content hash. Never the build id — that re-downloads everything per deploy. |
 | A truncation of author text | CODE POINTS, never `slice`. `short_name` falls back to the first 12 of `name`, and a UTF-16 `slice` cuts inside a surrogate pair — the lone half encodes as U+FFFD, so an app named with an emoji got a home-screen label ending in a replacement character. `Array.from(name).slice(0, n).join('')` is the form. |
 | Declared and never wired | `ServiceWorkerConfig.shellUrl` / `shellRevision` / `shellBytes` and `PwaRoute.dataUrl`. No caller in the framework's build path sets any of them, so `precache.ts`'s `reason: 'shell'` and `reason: 'route-data'` branches are reachable only from a hand-built `generateServiceWorker` call. Each doc comment now says so; the shell trio's said "precached for every `spa` route" while `spa` was already deleted from `RENDER_MODES`. **Kept, not deleted** — a public field is a major — and carried as candidates for the next major's declared-and-never-wired half. `revision` and `bytes` are the pair that IS fed, by the CLI's prerender pass. |
-| Every byte count and every threshold | a whole number of 0 or more, screened with `finiteCount` where it is READ — `buildPrecacheManifest`'s `warnBytes` AND each entry's own `bytes` (shell, route, asset), `createInstallController`'s `minEngagementMs`, `retentionPlan`'s `keep`. `totalBytes > warnBytes` is false when EITHER side is `NaN`, so one asset whose byte count did not arrive as a number took down the install-size warning for every other entry, silently, in the function whose output is otherwise byte-identical per commit; `now() - startedAt < NaN` is false at every instant, so the install prompt fired on first paint; and `Math.max(1, NaN)` is `NaN` with `slice(0, NaN)` `[]`, so a retention plan evicted every deploy including the running one. `Math.max` is not a validator — it propagates. `keep: 0` still means 1 (`version-skew.test.ts` pins it), so the floor is 0 everywhere here. `bun run finite-bounds` is the ratchet. |
+| Every byte count and every threshold | a whole number of 0 or more, screened with `finiteCount` where it is READ — `buildPrecacheManifest`'s `warnBytes` AND each entry's own `bytes` (shell, route, asset), `installController`'s `minEngagementMs`, `retentionPlan`'s `keep`. `totalBytes > warnBytes` is false when EITHER side is `NaN`, so one asset whose byte count did not arrive as a number took down the install-size warning for every other entry, silently, in the function whose output is otherwise byte-identical per commit; `now() - startedAt < NaN` is false at every instant, so the install prompt fired on first paint; and `Math.max(1, NaN)` is `NaN` with `slice(0, NaN)` `[]`, so a retention plan evicted every deploy including the running one. `Math.max` is not a validator — it propagates. `keep: 0` still means 1 (`version-skew.test.ts` pins it), so the floor is 0 everywhere here. `bun run finite-bounds` is the ratchet. |
 | Precache KEY | the bare URL, always. The revision addresses the FETCH (`?v=<hash>`), never the key: every strategy looks an entry up with `caches.match(req)` and `ignoreSearch` defaults to `false`, so an entry left keyed under `?v=` is a permanent miss — offline serves the fallback document instead of the precached page, and online every precached byte is downloaded twice. Each entry is fetched and `put` on its own, `As of 22.3.4`: `addAll`'s all-or-nothing let one 404 (a stylesheet another pod minted) fail the install of every deploy, so every visitor stayed on the first worker that ever installed (notificado.co). A failed entry costs its offline copy only. `service-worker-runtime.test.ts` executes the emitted `sw.js` against stub `caches`/`fetch` rather than asserting its text. |
 | Precache FETCH | the revision is appended with `?` or `&`, picked per entry. `PrecacheAsset.url` is public API and a bundler emits `?v=<hash>` of its own, so a fixed `?` built `...?locale=en?v=<rev>`; `addAll` is all-or-nothing, so one non-200 there means `install` rejects and the worker never activates at all. |
 | SW scope | `assertScope` refuses a relative `swPath`. `lastIndexOf('/')` on `sw.js` is `-1`, so the directory was `''` and `scope.startsWith('')` passed for every scope — the check waved through exactly the config most likely to be wrong. |
 | HTML sinks | one escaper: `escapeHtml` from `@ultimat3/core`, the framework's one character table (`bun run flight-copies`, `X_HELPER_COPY`). `appleTouchLinks` and `renderThemeColorMeta` interpolate app config into attributes; both escape. Never a second escaper here. |
-| A byte count in a warning | `formatBytes` from `@ultimat3/core`, never a local one. The copy that lived in `precache.ts` stopped at `mb`, so a precache past a gigabyte reported a four-digit `mb` — and `@ultimat3/render`'s copy stopped at `kb`, so the two halves of one build printed different units for the same bytes. Still on this barrel: a size report is what a caller of this package prints. |
+| A byte count in a warning | `formatBytes` from `@ultimat3/core`, never a local one. The copy that lived in `precache.ts` stopped at `mb`, so a precache past a gigabyte reported a four-digit `mb` — and `@ultimat3/render`'s copy stopped at `kb`, so the two halves of one build printed different units for the same bytes. Imported from core by callers too: 25.0.0 dropped this barrel's re-export. |
 | Cache names | always `cacheNamespace(buildId, kind)`. An unkeyed cache name is a rejected change. |
 | Offline fallback | `requireOfflineFallback` runs inside `generateServiceWorker`. Never optional. |
 | Its `fix:` names a route the framework accepts | `x g route offline --surface site   # then set pwa.offline.fallback to '/offline' in app.config.ts`. It said `create app/offline.tsx and set offline.fallback`, and BOTH halves were wrong: `<name>.tsx` is not a route file — `registerRoute` refuses it with `X_ROUTE_FILE_INVALID`, because the directory is the URL — and `offline.fallback` names no key `app.config.ts` has. A reader who followed it built a component nothing imports, left `/offline` a URL that does not exist, and met the same refusal on the next build; `wiki/Upgrading.md` had already recorded that path as the wrong one. `--surface site`, not `app`: the document answering a lost network must render with no network, no session and no database, which `app/` (`ssr \| stream`) cannot promise. `@ultimat3/cli`'s `doctor-offline.ts` writes the same line for the same code. |
@@ -49,7 +50,7 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | Colours | `@ultimat3/core`'s `PwaColors`, passed in as `WebManifestInput.tokens`. Never a hex literal in this package — a test fixture asserting the parser is the one exception. This package declared `ThemeTokens`/`SchemeColors` itself until 2026-08-27: structurally identical to what `app.config.ts` already carried, with no map between them and nothing asserting they agreed, which is the axiom-1 defect the two `PwaConfig`s were. Deleted; tier 0 owns the shape. |
 | `WebManifestInput` | what `generateWebManifest` takes, and **not** the `pwa` block of `app.config.ts` — it was called `PwaConfig` and said it was, while `@ultimat3/core` exported a different type of the same name that really is the block. An app declares `name` and `colors`; every other member is a caller's (`icons` from `planIcons`, `capabilities` from the build). `packages/cli/src/pwa-artifacts.ts` is the one composer of the two, and the only caller of `generateWebManifest` in the tree. |
 | Icons | one source image → `BuiltinImagePipeline` → a square PNG per `ICON_MATRIX` entry, rendered by `@ultimat3/core`'s image pipeline. Never a second scaler, never `sharp`, never a vendor CDN. |
-| Icon source | a **PNG** (core decodes PNG and JPEG only). `x new` scaffolds one; `@ultimat3/cli`'s `dev-assets.ts` reads it at `ICON_SOURCE` and serves every entry at its `outputPath`. This package renders bytes and mounts nothing. |
+| Icon source | a **PNG** (core decodes PNG and JPEG only). `x new` scaffolds one; `@ultimat3/cli`'s `runtime-assets.ts` reads it at `ICON_SOURCE` (through `icon-assets.ts`) and serves every entry at its `outputPath`. This package renders bytes and mounts nothing. |
 | Icon background | `IconSourceConfig.background`, hex or `transparent` — core's grammar has no named colours. Default transparent. |
 | Errors | `errors.ts` subclasses only. `X_NOT_IMPLEMENTED` must carry a real `fix:`. |
 | Errors in `sw.js` | no bundler there, so no `UltimateError` import. Never emit a bare `throw new Error`: a coded failure in the worker gets a code in `errors.ts` and a local class carrying `code`, `cause`, `fix`, `docs`. `As of 21.0.0` the emitted worker throws nothing of its own. |

package/README.md

@@ -5,7 +5,7 @@ whole thesis: a hand-written service worker encodes routing decisions a second t
 the second copy is the one nobody updates.
 
 ```ts
-const { source, precache, warnings } = generateServiceWorker(describeRoutes(), config, buildId);
+const { source, precache, warnings } = generateServiceWorker(describePages(), config, buildId);
 ```
 
 ## Render mode → runtime strategy
@@ -41,7 +41,7 @@ and the app dies with a blank screen and no error anyone can act on.
 | Mechanism | Rule |
 |---|---|
 | Build id | immutable per deploy, derived from the commit sha; `X_BUILD_ID_MISSING` if absent |
-| Client → server | every SW-proxied request carries `x-ultimate-build` |
+| Client → server | every SW-proxied request carries `x-ultimate-build` — `@ultimat3/core`'s `BUILD_ID_HEADER` |
 | Retention | `retentionPlan(deploys, keep)` keeps the last N deploys' assets alive (default 3) |
 | Stale client | gets `AppUpdateAvailable`, never a 404 |
 | Forced reload | none. This package never navigates a client — the app decides what to do with the message |
@@ -61,11 +61,12 @@ detectSkew(clientBuildId, message.to); // 'current' | 'stale' | 'unknown'
 ```
 X_PWA_NO_OFFLINE_FALLBACK: no offline fallback route
   cause: app.config.ts has no `offline` block, so an offline navigation would show the browser's error page
-  fix:   x g route offline --surface site   # then set pwa.offline.fallback to '/offline' in app.config.ts
+  fix:   set pwa: { offline: { fallback: '/offline' } } in app.config.ts, then create the route it names: x g route offline --surface site
 ```
 
 `requireOfflineFallback(config)` runs inside `generateServiceWorker`, so the build fails
-before an un-shippable PWA exists.
+before an un-shippable PWA exists. `pwa.offline.image` and `pwa.offline.font` are the
+placeholders a failed image or font request gets — each served only from the precache.
 
 ## Capabilities are opt-in, and gate bytes
 
@@ -106,7 +107,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Export | Owns |
 |---|---|
 | `generateServiceWorker` | `sw.js` from the route table; deterministic for identical input |
-| `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table; a `personal` route is `network-only` |
+| `strategyFor`, `MODE_STRATEGY`, `cacheFirst`, … | the four strategies + the mapping table; a `personal` route is `network-only`. Each answers what its emitted `sw.js` twin answers: the cache copy goes to `env.wait` and is never awaited (a failed copy costs the copy, not the response), and an exhausted strategy with no fallback rejects — `staleWhileRevalidate` with `X_PWA_STRATEGY_EXHAUSTED` |
 | `routeRules`, `assetRules` | the worker's rule list: routes most specific first, runtime asset prefixes (`/islands/`) ahead of them. `routeRules(routes, personalPages)` — `'last-member'` gives a personal page a `pages` rule; a pattern matches the browser's percent-encoded pathname, and a catch-all its bare prefix |
 | `CLEAR_PAGES_MESSAGE`, `PAGES_CLEARED_MESSAGE` | `{ type: 'clear-pages' }` — post it to the worker on sign-out; it empties every pages cache and answers `{ type: 'pages-cleared' }` |
 | `buildPrecacheManifest` | precache entries (url + content-hash revision), size warnings |
@@ -117,7 +118,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `requireOfflineFallback` | the mandatory offline route |
 | `backgroundSyncSource`, `registerBackgroundSyncSource` | the Background Sync trigger. No retry policy: the handler rejects and the PLATFORM reschedules it |
 | `renderPushPayload`, `pushSource`, `subscribeSource` | Web Push, per-locale bodies |
-| `createInstallController`, `iosInstallGuidance` | install prompt, never on first paint |
+| `installController`, `iosInstallGuidance` | install prompt, never on first paint |
 | `PwaStrategyExhaustedError` and the other `errors.ts` classes | the codes this package throws, catchable by an app |
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "24.0.0",
+  "version": "25.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "24.0.0"
+    "@ultimat3/core": "25.0.0"
   }
 }

package/src/capabilities.ts

@@ -34,7 +34,7 @@ export function resolveCapabilities(flags: CapabilityFlags = {}): ResolvedCapabi
   return resolved;
 }
 
-export function isEnabled(capabilities: ResolvedCapabilities, capability: Capability): boolean {
+export function hasCapability(capabilities: ResolvedCapabilities, capability: Capability): boolean {
   return capabilities[capability];
 }
 

package/src/index.ts

@@ -6,9 +6,6 @@
  * re-exported here; a consumer still needs one import, and now it names the real type.
  */
 export type { OfflineStrategy, RenderMode } from '@ultimat3/core';
-// Moved to `@ultimat3/core` (one formatter, `b`/`kb`/`mb`/`gb`); still named here because a service
-// worker's size report is what a caller of this package prints.
-export { formatBytes } from '@ultimat3/core';
 export {
   backgroundSyncSource,
   registerBackgroundSyncSource,
@@ -19,7 +16,7 @@ export {
   CAPABILITIES,
   CAPABILITY_SW_MARKERS,
   enabledCapabilities,
-  isEnabled,
+  hasCapability,
   resolveCapabilities,
 } from './capabilities';
 export type { PwaErrorCode } from './errors';
@@ -65,7 +62,7 @@ export type {
   IosGuidance,
   ReadSignal,
 } from './install';
-export { createInstallController, iosInstallGuidance } from './install';
+export { installController, iosInstallGuidance } from './install';
 export type {
   DisplayMode,
   FileHandler,
@@ -141,10 +138,7 @@ export type {
   SkewState,
 } from './version-skew';
 export {
-  APP_UPDATE_AVAILABLE,
   assertBuildId,
-  BUILD_ID_HEADER,
-  BUILD_ID_META,
   buildId,
   cacheNamespace,
   detectSkew,

package/src/install.ts

@@ -77,13 +77,13 @@ export interface InstallController {
   dispose(): void;
 }
 
-export function createInstallController(options: InstallOptions): InstallController {
+export function installController(options: InstallOptions): InstallController {
   const host = options.host;
   // `now() - startedAt < NaN` is false at every instant, so a threshold that arrived non-finite
   // does not shorten the wait — it deletes it, and the prompt fires on first paint. `0` stays
   // legal: "ask as soon as the browser offers" is a decision, and it is a comparison that works.
   const minEngagementMs = finiteCount(
-    'createInstallController',
+    'installController',
     'minEngagementMs',
     options.minEngagementMs ?? MIN_ENGAGEMENT_MS,
   );

package/src/manifest.ts

@@ -12,7 +12,7 @@
 import type { PwaColors } from '@ultimat3/core';
 import { escapeHtml } from '@ultimat3/core';
 import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
-import { isEnabled, resolveCapabilities } from './capabilities';
+import { hasCapability, resolveCapabilities } from './capabilities';
 import { PwaManifestInvalidError } from './errors';
 
 export type DisplayMode = 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
@@ -143,13 +143,13 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
   if (config.screenshots !== undefined) optional.screenshots = config.screenshots;
 
   // A disabled capability contributes no manifest member at all — not an empty one.
-  if (isEnabled(capabilities, 'shareTarget') && config.shareTarget !== undefined) {
+  if (hasCapability(capabilities, 'shareTarget') && config.shareTarget !== undefined) {
     optional.share_target = config.shareTarget;
   }
-  if (isEnabled(capabilities, 'fileHandlers') && config.fileHandlers !== undefined) {
+  if (hasCapability(capabilities, 'fileHandlers') && config.fileHandlers !== undefined) {
     optional.file_handlers = config.fileHandlers;
   }
-  if (isEnabled(capabilities, 'protocolHandlers') && config.protocolHandlers !== undefined) {
+  if (hasCapability(capabilities, 'protocolHandlers') && config.protocolHandlers !== undefined) {
     optional.protocol_handlers = config.protocolHandlers;
   }
 

package/src/offline-fallback.ts

@@ -4,6 +4,7 @@
  * requires it and `requireOfflineFallback` fails the build if it is missing.
  */
 
+import { CLIENT_NAVIGATION_HEADER, isSameOriginPath } from '@ultimat3/core';
 import { PwaNoOfflineFallbackError } from './errors';
 import type { PersonalPages } from './pages-cache-source';
 
@@ -78,39 +79,68 @@ export function requireOfflineFallback(
       `set pwa.offline.fallback to '/${fallback.replace(/^\/+/, '')}' in app.config.ts`,
     );
   }
+  // Core's predicate, judged by resolution: every URL here is precached at install and served as
+  // the answer to a failed request, so an off-origin one is a third party's bytes in the cache.
+  if (!isSameOriginPath(fallback)) throw offOrigin('fallback', fallback, '/offline');
 
   return {
     document: fallback,
-    image: config.image ?? null,
-    font: config.font ?? null,
+    image: placeholder('image', config.image, '/icons/offline.png'),
+    font: placeholder('font', config.font, '/fonts/fallback.woff2'),
     neverCache: config.neverCache ?? [],
     personalPages: config.personalPages === 'last-member' ? 'last-member' : 'never',
   };
 }
 
+function offOrigin(key: string, url: string, example: string): PwaNoOfflineFallbackError {
+  return new PwaNoOfflineFallbackError(
+    `pwa.offline.${key} is ${JSON.stringify(url)}, which is not a path on this origin — it is precached and served as the offline answer`,
+    `defineConfig({ pwa: { offline: { ${key}: '${example}' } } })   # pwa.offline.${key} in app.config.ts — a path this app serves`,
+  );
+}
+
+/** `pwa.offline.image` / `.font`: absent is `null`; present must be a same-origin path. */
+function placeholder(
+  key: 'image' | 'font',
+  url: string | undefined,
+  example: string,
+): string | null {
+  if (url === undefined || url === null) return null;
+  if (!isSameOriginPath(url)) throw offOrigin(key, url, example);
+  return url;
+}
+
 /**
- * Emitted into `sw.js`: what to serve when a navigation cannot be answered. `localePrefixes` are
- * the non-default routed locales' URL segments: a navigation under `/en/` tries `/en` + the offline
- * document first, so an English visitor offline is not handed the default locale's page.
+ * Emitted into `sw.js`: what to serve when a request cannot be answered — the offline document for
+ * a navigation, the `image`/`font` placeholders for those destinations (each only if the app
+ * precached it), else a 503. `localePrefixes` are the non-default routed locales' URL segments: a
+ * navigation under `/en/` tries `/en` + the offline document first, so an English visitor offline
+ * is not handed the default locale's page. A navigation is the browser's own (`mode`) or the client
+ * router's soft visit — a `fetch` carrying `CLIENT_NAVIGATION_HEADER: soft`, which otherwise got the
+ * bare 503 (#627). Its `prefetch` is a guess, not a visit: never answered with the offline page.
  */
 export function offlineFallbackSource(
   fallback: OfflineFallback,
   localePrefixes: readonly string[] = [],
 ): string {
   const image = fallback.image === null ? 'null' : JSON.stringify(fallback.image);
+  const font = fallback.font === null ? 'null' : JSON.stringify(fallback.font);
   const locales = [...new Set(localePrefixes)].sort();
   return `
 const OFFLINE_DOC=${JSON.stringify(fallback.document)};
 const OFFLINE_IMAGE=${image};
+const OFFLINE_FONT=${font};
 const OFFLINE_LOCALES=${JSON.stringify(locales)};
+const OFFLINE_NAV_HEADER=${JSON.stringify(CLIENT_NAVIGATION_HEADER)};
 async function offlineFallback(req){
   const c=await caches.open(PRECACHE);
-  if(req.mode==='navigate'){
+  if(req.mode==='navigate'||req.headers.get(OFFLINE_NAV_HEADER)==='soft'){
     const seg=new URL(req.url).pathname.split('/')[1];
     if(OFFLINE_LOCALES.indexOf(seg)!==-1){const l=await c.match('/'+seg+OFFLINE_DOC);if(l)return l}
     const d=await c.match(OFFLINE_DOC);if(d)return d
   }
   if(OFFLINE_IMAGE&&req.destination==='image'){const i=await c.match(OFFLINE_IMAGE);if(i)return i}
+  if(OFFLINE_FONT&&req.destination==='font'){const f=await c.match(OFFLINE_FONT);if(f)return f}
   return new Response('',{status:503,statusText:'Offline'})
 }`.trim();
 }

package/src/service-worker.ts

@@ -8,10 +8,10 @@
  * update check does not fire on a no-op deploy.
  */
 
-import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
+import { APP_UPDATE_MESSAGE, BUILD_ID_HEADER, CLIENT_SCOPE_HEADER } from '@ultimat3/core';
 import { backgroundSyncSource } from './background-sync';
 import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
-import { isEnabled, resolveCapabilities } from './capabilities';
+import { hasCapability, resolveCapabilities } from './capabilities';
 import { SwScopeInvalidError } from './errors';
 import type { OfflineConfig } from './offline-fallback';
 import { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
@@ -30,12 +30,7 @@ import type { RouteRule } from './route-rules';
 import { assetRules, routeRules } from './route-rules';
 import type { PwaRoute } from './strategies';
 import { NETWORK_SOURCE, STRATEGY_FN_NAMES, STRATEGY_SOURCE } from './strategies';
-import {
-  APP_UPDATE_AVAILABLE,
-  assertBuildId,
-  BUILD_ID_HEADER,
-  cacheNamespace,
-} from './version-skew';
+import { assertBuildId, cacheNamespace } from './version-skew';
 
 export interface ServiceWorkerConfig {
   readonly scope?: string;
@@ -162,13 +157,13 @@ export function generateServiceWorker(
     INSTALL_BLOCK,
     activateBlock(),
     fetchBlock(fallback.personalPages),
-    messageBlock(isEnabled(capabilities, 'backgroundSync')),
+    messageBlock(hasCapability(capabilities, 'backgroundSync')),
   ];
 
-  if (isEnabled(capabilities, 'push') && config.vapid !== undefined) {
-    blocks.push(pushSource({ badging: isEnabled(capabilities, 'badging') }));
+  if (hasCapability(capabilities, 'push') && config.vapid !== undefined) {
+    blocks.push(pushSource({ badging: hasCapability(capabilities, 'badging') }));
   }
-  if (isEnabled(capabilities, 'backgroundSync')) {
+  if (hasCapability(capabilities, 'backgroundSync')) {
     blocks.push(backgroundSyncSource());
   }
 
@@ -300,7 +295,7 @@ self.addEventListener('activate',(event)=>{
     // the fetch handler answers from it (net) — start-up is off every navigation's critical path.
     try{if(self.registration&&self.registration.navigationPreload)await self.registration.navigationPreload.enable()}catch(e){}
     const cs=await self.clients.matchAll({type:'window'});
-    for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_AVAILABLE)},to:BUILD_ID});
+    for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_MESSAGE)},to:BUILD_ID});
     // NOT part of this waitUntil: a fetch event waits for the worker to finish ACTIVATING, so a
     // warm-up that copies a streamed page's whole body in here held every request of the tab it
     // just claimed — /feed's own reads included — until that body had ended. Kicked off, never
@@ -391,7 +386,7 @@ function seenBuild(res){
   const server=res.headers.get(BUILD_HEADER);
   if(SKEWED||server===null||server===BUILD_ID)return;
   SKEWED=true;
-  self.clients.matchAll({type:'window'}).then((cs)=>{for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_AVAILABLE)},to:server})}).catch(()=>{});
+  self.clients.matchAll({type:'window'}).then((cs)=>{for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_MESSAGE)},to:server})}).catch(()=>{});
 }
 function withBuild(headers){
   const h=new Headers(headers);
@@ -410,7 +405,7 @@ async function healSkew(req,res){
   // Answering the request for real is what breaks that loop.
   SKEWED=true;
   const cs=await self.clients.matchAll({type:'window'});
-  for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_AVAILABLE)},to:server});
+  for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_MESSAGE)},to:server});
   return fetch(new Request(req,{headers:withBuild(req.headers)}));
 }`.trim();
 }

package/src/strategies.ts

@@ -157,7 +157,7 @@ export async function networkFirst(
   const cache = await env.open(options.cacheName);
   try {
     const response = await fromNetwork(request, env, options);
-    if (response.ok) await cache.put(request, response.clone());
+    if (response.ok) later(env, cache.put(request, response.clone()));
     return response;
   } catch (error) {
     const hit = await cache.match(request);
@@ -176,8 +176,8 @@ export async function staleWhileRevalidate(
   const cache = await env.open(options.cacheName);
   const hit = await cache.match(request);
   const refresh = fromNetwork(request, env, options)
-    .then(async (response) => {
-      if (response.ok) await cache.put(request, response.clone());
+    .then((response) => {
+      if (response.ok) later(env, cache.put(request, response.clone()));
       return response;
     })
     .catch(async () => (hit !== undefined ? hit : fallbackOrThrow(options)));
@@ -185,8 +185,8 @@ export async function staleWhileRevalidate(
   if (hit !== undefined) {
     // The refresh is handed to the event's `waitUntil` NOW, before the cached answer returns:
     // taken after `respondWith` settled, a browser refuses the extension (`InvalidStateError`) and
-    // may kill the worker mid-refresh. `later` also swallows its rejection, as `.catch` did.
-    env.wait?.(refresh.catch(() => undefined));
+    // may kill the worker mid-refresh. `later` also swallows its rejection.
+    later(env, refresh);
     return hit;
   }
   return refresh;
@@ -225,7 +225,7 @@ async function fetchAndStore(
 ): Promise<Response> {
   try {
     const response = await fromNetwork(request, env, options);
-    if (response.ok) await cache.put(request, response.clone());
+    if (response.ok) later(env, cache.put(request, response.clone()));
     return response;
   } catch (error) {
     if (options.fallback !== undefined) return options.fallback();
@@ -233,16 +233,33 @@ async function fetchAndStore(
   }
 }
 
+/**
+ * Work behind the answer: the emitted worker's `later`. A cache copy is never awaited — `Cache.put`
+ * reads the whole body, so awaiting it held a streamed document away from the tab, and a put that
+ * REJECTED (quota) turned a fresh network answer into the stale copy or a throw. The copy goes to
+ * the event's `waitUntil`, which keeps the worker alive until it lands; a failed copy costs the
+ * copy, never the response.
+ */
+function later(env: StrategyEnv, work: Promise<unknown>): void {
+  const settled = work.catch(() => undefined);
+  env.wait?.(settled);
+}
+
+/**
+ * Exhausted with nothing to answer: REJECT, as the other three strategies do on both halves. In a
+ * worker a rejected `respondWith` is the same network error `Response.error()` would be, and
+ * in-process the caller gets a code and a fix instead of a status-0 response it has to recognise.
+ */
 async function fallbackOrThrow(options: StrategyOptions): Promise<Response> {
   if (options.fallback !== undefined) return options.fallback();
   throw new PwaStrategyExhaustedError({ cacheName: options.cacheName });
 }
 
 /**
- * The emitted counterpart of the functions above. Kept as source strings because the
- * service worker is a generated artifact with no bundler in the loop — the shapes are
- * identical on purpose and `strategies.test.ts` asserts both halves stay in step. They open a
- * cache through the worker's `openCache`, never `caches.open`: the pages cache is a facade that
+ * The emitted counterpart of the functions above. Kept as source strings because the service
+ * worker is a generated artifact with no bundler in the loop — the shapes are identical on purpose
+ * and `strategies.test.ts` RUNS each source against the fake its twin gets. They open a cache
+ * through the worker's `openCache`, never `caches.open`: the pages cache is a facade that
  * partitions a per-member document by principal (`service-worker.ts`, `pagesCache`). And the cache
  * copy is NEVER awaited before answering: `Cache.put` reads the whole body, so awaiting it held a
  * streamed document away from the tab until it had ended. It goes to `later(wait, …)` instead —
@@ -262,7 +279,7 @@ export const STRATEGY_SOURCE = Object.freeze<Record<StrategyName, string>>({
   'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb,wait,pre){
   const c=await openCache(cn);const hit=await c.match(req);
   const refresh=net(req,pre).then((r)=>{if(r.ok)later(wait,c.put(req,r.clone()));return r})
-    .catch(()=>hit||(fb?fb():Response.error()));
+    .catch((e)=>{if(hit)return hit;if(fb)return fb();throw e});
   if(hit){later(wait,refresh);return hit}
   return refresh
 }`,

package/src/version-skew.ts

@@ -10,12 +10,13 @@
  * The app decides what to do with that message. This package never navigates a client.
  */
 
-import { APP_UPDATE_MESSAGE, CLIENT_BUILD_META, finiteCount } from '@ultimat3/core';
+import type { APP_UPDATE_MESSAGE } from '@ultimat3/core';
+import { finiteCount } from '@ultimat3/core';
 import { BuildIdMissingError } from './errors';
 
-export const BUILD_ID_HEADER = 'x-ultimate-build';
-/** Shipped name for core's `CLIENT_BUILD_META` — the meta render writes, one literal for both. */
-export const BUILD_ID_META = CLIENT_BUILD_META;
+// The header every proxied request carries is core's `BUILD_ID_HEADER`, the document meta core's
+// `CLIENT_BUILD_META` and the worker's message type core's `APP_UPDATE_MESSAGE` — imported where
+// they are used, never re-published under this package's names (25.0.0, `X_HELPER_COPY`).
 
 export type DeployChannel = 'production' | 'preview' | 'branch';
 
@@ -125,8 +126,8 @@ export function detectSkew(
 
 /**
  * The client-side contract, and the whole of it: what the generated worker posts to every page it
- * controls on activation. The page compares `to` against its own `BUILD_ID_META` — `detectSkew`
- * is that comparison — and renders its own "refresh to update" affordance.
+ * controls on activation. The page compares `to` against its own `CLIENT_BUILD_META` meta (core's)
+ * — `detectSkew` is that comparison — and renders its own "refresh to update" affordance.
  *
  * It declared `from`, `forced` and `deadlineAt` too, for a forced reload after a grace period that
  * NOTHING performed: `updateSignal`/`updatePolicy` computed the three and had no runtime caller,
@@ -141,6 +142,3 @@ export interface AppUpdateAvailable {
   /** The build the worker that posted this was generated for. */
   readonly to: string;
 }
-
-/** Shipped name for core's `APP_UPDATE_MESSAGE` — one literal for the worker and the page. */
-export const APP_UPDATE_AVAILABLE = APP_UPDATE_MESSAGE;