@ultimat3/pwa 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -11,25 +11,27 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 |---|---|
 | `sw.js` | generated, never hand-written, never committed. No file in this package is a SW. |
 | 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. Weights are `@ultimat3/render`'s `compilePattern` (literal 100, `:param` 10, `*` 1), **duplicated** because both packages are tier 4; a wildcard sorts last outright, because a sum over segments cannot say that `/` (0 segments) outranks `/*rest` (1). The shared home is `@ultimat3/core`'s `route-vocabulary.ts`. |
+| 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. |
+| 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: `escapeAttribute` from `@ultimat3/seo` (tier 1, and the only one reachable — render's `html.ts` is tier 4, sideways). `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. |
+| 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. 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. |
@@ -38,17 +40,17 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | `AppUpdateAvailable` | declares exactly the fields the emitted `activate` block posts, and no more. `version-skew.test.ts` reads the literal back out of the generated source and compares it to a fixture typed `Required<AppUpdateAvailable>` — a field added to the interface stops compiling, a field added to the worker fails the assertion. It declared five and posted two until 9.0.0; the three extra described a forced reload nothing performed. |
 | Forced reload | **not a capability of this package.** `updateSignal`/`updatePolicy` computed `forced`/`deadlineAt` with no runtime caller and were deleted in 9.0.0. The two runtimes holding both build ids are BELOW this one — `http`'s `ctx.clientBuildId` (tier 2), `sync`'s `update-available` frame (tier 3) — so neither could ever have called into tier 4 to act on one. The app renders its own affordance; the framework never navigates a client. |
 | A cache copy is never awaited before answering | `Cache.put` reads the whole body, so a strategy that awaited it held a streamed (or slow) document away from the tab until it had ENDED. The emitted strategies hand the copy to `later(wait, …)` — the fetch event's `waitUntil` — and return the response at once. `service-worker-runtime.test.ts` streams a gated body and asserts the page reads the first chunk before it ends; its `StubCache.put` reads the whole body, as the real one does, or the test could not fail. |
-| A per-member document | NEVER stored, in any cache, under any rule (22.3.3, security). `openCache` guards every cache a strategy opens: a response that is `private`/`no-store` or carries `x-ultimate-scope` (`CLIENT_SCOPE_HEADER`) is answered and dropped. 21.0.0 kept one in a per-principal partition (`PAGES~<scope>`) for offline, and after sign-out an offline navigation on a shared device showed the previous member's cases (notificado.co). A PERSONAL route (`PwaRoute.personal`: a policy, a `stream`, a `no-store`/`private` cache) is also `network-only` in `strategyFor` and skipped by `buildPrecacheManifest`. `{type:'clear-pages'}` (`CLEAR_PAGES_MESSAGE`) deletes every `x-pages-*` cache — old partitions included — and answers `pages-cleared`. `offline.personalPages: 'last-member'` (an app's explicit opt-in) restores 21.0.0's partition — `pagesCacheSource(mode)` emits one of the two. `service-worker-pages.test.ts` runs both modes. |
+| A per-member document | NEVER stored, in any cache, under any rule (22.3.3, security). `openCache` guards every cache a strategy opens: a response that is `private`/`no-store` or carries `x-ultimate-scope` (`CLIENT_SCOPE_HEADER`) is answered and dropped. 21.0.0 kept one in a per-principal partition (`PAGES~<scope>`) for offline, and after sign-out an offline navigation on a shared device showed the previous member's cases (notificado.co). A PERSONAL route (`PwaRoute.personal`: a policy, a `stream`, a `no-store`/`private` cache) is also `network-only` in `strategyFor` and skipped by `buildPrecacheManifest`. `{type:'clear-pages'}` (`CLEAR_PAGES_MESSAGE`) deletes every `x-pages-*` cache — old partitions included — and answers `pages-cleared`. `offline.personalPages: 'last-member'` (an app's explicit opt-in) restores 21.0.0's partition — `pagesCacheSource(mode)` emits one of the two, and `routeRules(routes, mode)` gives a personal page a `pages` rule whatever its `offline` (a `precache` rule was never filled, so it was never kept). `service-worker-pages.test.ts` runs both modes. |
 | The installing page | cached on `activate`. It loaded before the worker controlled it, so no strategy saw it and an `offline: 'runtime'` route was unavailable offline until a second online visit. After `clients.claim()` each controlled window's URL runs through its OWN route's strategy (`warm`) — only rules with `c: 'pages'`, same origin, not `NEVER_CACHE` — never a second caching rule. Best effort; a failed warm-up never fails activation. It runs AFTER activation, never inside its `waitUntil`: a fetch event waits for the worker to finish activating, so a warm-up copying a streamed page's whole body there held the claimed tab's every request — the `/feed` e2e hang. The offline page read (`pageOffline`) awaits it instead. `service-worker-runtime.test.ts` runs it. |
 | Outbox drain | the worker SENDS NOTHING, `As of 21.0.0`. The outbox is `@ultimat3/realtime`'s and lives in the page (IndexedDB), so the `sync` event — and the `{type:'flush-outbox'}` fallback message, posted by `registerBackgroundSyncSource` wherever `registration.sync` is absent (Safari, Firefox) — both run `drainOutbox`, which posts `OUTBOX_DRAIN_MESSAGE` (`@ultimat3/core`) to EVERY open window client; realtime's listener drains. No client open = the handler resolves and the next load drains; it never fakes work. `/_x/outbox/flush`, `DEFAULT_FLUSH_ENDPOINT`, and `BackgroundSyncOptions` were deleted, and `X_PWA_SYNC_FLUSH_FAILED` / `X_PWA_SYNC_INCOMPLETE` are still registered but thrown by nothing (shipped codes are stable forever): the worker POSTed to a route nothing in the framework ever mounted. The fallback branch lives in the shared message handler, so `CAPABILITY_SW_MARKERS.backgroundSync` carrying `d.type==='flush-outbox'` is what keeps it gated with the `drainOutbox` it calls. `background-sync.test.ts` and `service-worker-runtime.test.ts` run the emitted code and assert the posted messages. |
 | Outbox | queue, replay, retry and idempotency are all `@ultimat3/realtime`'s. This package only registers the sync trigger and schedules **no retry** — `RetryPolicy`, `DEFAULT_RETRY`, `retryDelayMs`, `shouldRetry` and `BackgroundSyncOptions.retry` were deleted 2026-08-23. |
 | Push strings | i18n keys only, rendered per subscriber locale. Never a literal. |
 | `renotify` | never without a `tag`, at BOTH ends. The Notifications spec makes `showNotification` reject with a `TypeError` for the pair, so the device shows **nothing** — the failure a `renotify: true` with no collapse key produces is the whole notification disappearing. `renderPushPayload` drops the flag and files a `warnings` entry (a knob with no effect is worse than no knob), and the emitted handler recomputes it as `!!d.renotify&&!!d.tag` because a push body is composed by whatever holds the VAPID key. `push.test.ts`'s `showNotification` stub throws the spec's TypeError, so a stub that tolerates the pair cannot go green. |
-| Push URLs | `PushPayload.url` is a PATH and `WindowClient.url` is absolute, so `notificationclick` resolves against `self.location.origin` before comparing. Unresolved, the focus-existing-tab loop matched nothing and every tap opened a second window. |
+| Push URLs | `PushPayload.url` is a PATH and `WindowClient.url` is absolute, so `notificationclick` resolves against `self.location.origin` before comparing. Unresolved, the focus-existing-tab loop matched nothing and every tap opened a second window. A URL that does not resolve to `self.location.origin` (another host, a scheme, malformed, a non-string) opens the root instead (`tapTarget`). The `push` body is parsed INSIDE `waitUntil` (`pushData`): plain text is the body, JSON that is no object is `{}`. `push-handler.test.ts`. |
 | 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,17 +61,18 @@ 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
 
 | Capability | Manifest member | SW code |
 |---|---|---|
-| `push` | — | `push` + `notificationclick` listeners |
+| `push` | — | `push` + `notificationclick` listeners; a tap opens a same-origin URL only |
 | `backgroundSync` | — | `sync` listener that tells every open tab to drain realtime's outbox (`OUTBOX_DRAIN_MESSAGE`) |
 | `badging` | — | `navigator.setAppBadge` after a push |
 | `shareTarget` | `share_target` | — |
@@ -95,7 +96,6 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | Class | Code | Declared in |
 |---|---|---|
 | `BuildIdMissingError` | `X_BUILD_ID_MISSING` | `src/errors.ts` |
-| `NotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
 | `PwaIconMissingError` | `X_PWA_ICON_MISSING` | `src/errors.ts` |
 | `PwaManifestInvalidError` | `X_PWA_MANIFEST_INVALID` | `src/errors.ts` |
 | `PwaNoOfflineFallbackError` | `X_PWA_NO_OFFLINE_FALLBACK` | `src/errors.ts` |
@@ -107,8 +107,8 @@ 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` |
-| `routeRules`, `assetRules` | the worker's rule list: routes most specific first, runtime asset prefixes (`/islands/`) ahead of them |
+| `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 |
 | `buildId`, `detectSkew`, `retentionPlan` | version skew |
@@ -118,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
@@ -153,9 +153,9 @@ a job boundary the class is gone and the `code` is what survives — match on th
   lands exactly inside `maskableSafeZone(size)`; the ring around it is `background`, which is
   hex or `transparent` (there are no named colours). Same bytes in, same bytes out.
 - **Every HTML sink goes through one escaper.** `appleTouchLinks` and `renderThemeColorMeta`
-  interpolate app configuration into attributes, so both run it through `escapeAttribute` from
-  `@ultimat3/seo` (tier 1, and the one this package can reach — `@ultimat3/render`'s `html.ts` is
-  tier 4, sideways). Never a second escaper here.
+  interpolate app configuration into attributes, so both run it through `escapeHtml` from
+  `@ultimat3/core` — the framework's one HTML character table (`@ultimat3/render`'s `html.ts` is
+  tier 4, sideways, and re-exports the same function). Never a second escaper here.
 - **A precache URL may already carry a query.** `PrecacheAsset.url` is public API and bundlers emit
   `?v=<hash>` of their own, so the install block picks `?` or `&` per entry. A fixed `?` produced
   `...?locale=en?v=<rev>`, and because `cache.addAll` is all-or-nothing a single non-200 there means

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -25,14 +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": "23.0.0",
-    "@ultimat3/seo": "23.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/errors.ts

@@ -20,8 +20,9 @@ export const PWA_OWNED_ERROR_CODES = [
 ] as const;
 
 /**
- * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s. Thrown here, titled only there — the copy this file
- * used to keep was a second title that could drift from core's with nothing to catch it.
+ * `X_NOT_IMPLEMENTED` is `@ultimat3/core`'s — constructed only there, by core's own
+ * `NotImplementedError`, and titled only there: the copy this file used to keep was a second title
+ * that could drift from core's with nothing to catch it.
  */
 export const PWA_BORROWED_ERROR_CODES = ['X_NOT_IMPLEMENTED'] as const;
 
@@ -130,15 +131,3 @@ export class PwaStrategyExhaustedError extends UltimateError {
     });
   }
 }
-
-/** A driver whose interface exists and whose backing implementation does not, yet. */
-export class NotImplementedError extends UltimateError {
-  static readonly code = 'X_NOT_IMPLEMENTED' as const;
-  constructor(cause: string, fix: string) {
-    super({
-      code: NotImplementedError.code,
-      cause,
-      fix,
-    });
-  }
-}

package/src/icons.ts

@@ -4,8 +4,7 @@
  * icons end up with clipped logos.
  */
 
-import { transformImageBytes } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+import { escapeHtml, transformImageBytes } from '@ultimat3/core';
 import { PwaIconMissingError } from './errors';
 import type { ManifestIcon } from './manifest';
 
@@ -186,7 +185,7 @@ export function appleTouchLinks(plan: IconPlan): string {
       // `href` — a quote in it closed the attribute AND the tag, so `<head>` got a live element.
       // seo's escaper is tier 1 and the one this package can reach; render's html.ts is tier 4.
       (entry) =>
-        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${escapeAttribute(entry.outputPath)}">`,
+        `<link rel="apple-touch-icon" sizes="${entry.spec.size}x${entry.spec.size}" href="${escapeHtml(entry.outputPath)}">`,
     )
     .join('');
 }

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,13 +16,12 @@ export {
   CAPABILITIES,
   CAPABILITY_SW_MARKERS,
   enabledCapabilities,
-  isEnabled,
+  hasCapability,
   resolveCapabilities,
 } from './capabilities';
 export type { PwaErrorCode } from './errors';
 export {
   BuildIdMissingError,
-  NotImplementedError,
   PWA_ERROR_CODES,
   PWA_ERROR_TITLES,
   PwaIconMissingError,
@@ -66,7 +62,7 @@ export type {
   IosGuidance,
   ReadSignal,
 } from './install';
-export { createInstallController, iosInstallGuidance } from './install';
+export { installController, iosInstallGuidance } from './install';
 export type {
   DisplayMode,
   FileHandler,
@@ -142,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

@@ -10,9 +10,9 @@
 // with no map between them and nothing asserting they agreed, which is the same axiom-1 defect the
 // two `PwaConfig`s were. An app writes them once, in the one config file.
 import type { PwaColors } from '@ultimat3/core';
-import { escapeAttribute } from '@ultimat3/seo';
+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';
@@ -132,6 +132,8 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
   assertValid(config);
   const capabilities = resolveCapabilities(config.capabilities);
   const scope = config.scope ?? '/';
+  const display = config.display ?? 'standalone';
+  const override = displayOverrideFor(display);
 
   const optional: MutableManifest = {};
   if (config.description !== undefined) optional.description = config.description;
@@ -141,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;
   }
 
@@ -156,8 +158,9 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
     short_name: config.shortName ?? shortNameFrom(config.name),
     start_url: config.startUrl ?? scope,
     scope,
-    display: config.display ?? 'standalone',
-    display_override: ['standalone', 'minimal-ui'],
+    display,
+    // Right after `display`, where it always was: an unchanged config emits unchanged bytes.
+    ...(override.length > 0 ? { display_override: override } : {}),
     orientation: config.orientation ?? 'any',
     lang: config.lang ?? 'en',
     dir: config.dir ?? 'ltr',
@@ -177,6 +180,19 @@ export function generateWebManifest(config: WebManifestInput): WebManifestResult
   };
 }
 
+/** The spec's own fallback chain for `display`, app windows only — `browser` is no window. */
+const DISPLAY_CHAIN: readonly DisplayMode[] = ['fullscreen', 'standalone', 'minimal-ui'];
+
+/**
+ * `display_override` is read BEFORE `display`, so it must start where `display` does: a fixed
+ * `['standalone','minimal-ui']` opened a `browser` app in its own window and gave a `fullscreen`
+ * one browser UI. `browser` gets none — any override would be a window it did not ask for.
+ */
+function displayOverrideFor(display: DisplayMode): readonly DisplayMode[] {
+  const from = DISPLAY_CHAIN.indexOf(display);
+  return from < 0 ? [] : DISPLAY_CHAIN.slice(from);
+}
+
 type MutableManifest = { -readonly [K in keyof WebManifest]?: WebManifest[K] };
 
 /** Home-screen labels are truncated by the OS well before this; the cap only bounds the string. */
@@ -231,7 +247,7 @@ export function renderThemeColorMeta(metas: readonly ThemeColorMeta[]): string {
       // quote in one emitted a second, live attribute — same class as `appleTouchLinks`, same
       // escaper, one per package rather than one per call site.
       (meta) =>
-        `<meta name="theme-color" content="${escapeAttribute(meta.content)}" media="${escapeAttribute(meta.media)}">`,
+        `<meta name="theme-color" content="${escapeHtml(meta.content)}" media="${escapeHtml(meta.media)}">`,
     )
     .join('');
 }

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/push.ts

@@ -171,28 +171,46 @@ export function pushSource(options: PushSourceOptions = {}): string {
   const badging = options.badging === true;
 
   return `
+// Parsed INSIDE waitUntil: json() on a body that is not JSON threw out of the listener before it
+// was extended, and nothing was shown. Plain text is the body; JSON that is no object reads as {}.
+function pushData(event){
+  if(!event.data)return {};
+  let v;
+  try{v=event.data.json()}catch(e){return {body:event.data.text()}}
+  return v!==null&&typeof v==='object'&&!Array.isArray(v)?v:{}
+}
 self.addEventListener('push',(event)=>{
-  const d=event.data?event.data.json():{};
-  // renotify needs the tag: showNotification rejects with a TypeError when the flag is set and
-  // the tag is empty, and the device shows nothing. renderPushPayload refuses the pair too, but a
-  // push body is composed by whatever holds the VAPID key, so this is the last guard there is.
-  // A NON-EMPTY STRING, never truthiness: WebIDL converts every tag to a DOMString, and [] and {}
-  // are truthy in JS while converting to '' and '[object Object]'. !!d.tag therefore enabled
-  // renotify for a JSON [] whose converted tag is empty — the rejection this line exists to avoid.
-  const tg=typeof d.tag==='string'&&d.tag!==''?d.tag:undefined;
-  const opts={body:d.body||'',icon:d.icon||${icon},badge:d.badge||${badge},
-    tag:tg,renotify:!!d.renotify&&tg!==undefined,requireInteraction:!!d.requireInteraction,
-    lang:d.lang||undefined,actions:d.actions||[],data:{url:d.url||'/'}};
-  event.waitUntil(self.registration.showNotification(d.title||'',opts)${
-    badging ? '.then(()=>navigator.setAppBadge&&navigator.setAppBadge())' : ''
-  });
+  event.waitUntil((async()=>{
+    const d=pushData(event);
+    // renotify needs the tag: showNotification rejects with a TypeError when the flag is set and
+    // the tag is empty, and the device shows nothing. renderPushPayload refuses the pair too, but a
+    // push body is composed by whatever holds the VAPID key, so this is the last guard there is.
+    // A NON-EMPTY STRING, never truthiness: WebIDL converts every tag to a DOMString, and [] and {}
+    // are truthy in JS while converting to '' and '[object Object]'. !!d.tag therefore enabled
+    // renotify for a JSON [] whose converted tag is empty — the rejection this line exists to avoid.
+    const tg=typeof d.tag==='string'&&d.tag!==''?d.tag:undefined;
+    const opts={body:d.body||'',icon:d.icon||${icon},badge:d.badge||${badge},
+      tag:tg,renotify:!!d.renotify&&tg!==undefined,requireInteraction:!!d.requireInteraction,
+      lang:d.lang||undefined,actions:Array.isArray(d.actions)?d.actions:[],data:{url:d.url||'/'}};
+    await self.registration.showNotification(d.title||'',opts);${
+      badging ? '\n    if(navigator.setAppBadge)await navigator.setAppBadge();' : ''
+    }
+  })());
 });
+// A tap opens THIS app only: the URL comes from the push body, whoever composed it. Another host, a
+// non-http scheme, a malformed URL or a non-string opens the app's root instead.
+function tapTarget(raw){
+  const root=new URL('/',self.location.origin).href;
+  if(typeof raw!=='string')return root;
+  try{const u=new URL(raw,self.location.origin);return u.origin===self.location.origin?u.href:root}
+  catch(e){return root}
+}
 self.addEventListener('notificationclick',(event)=>{
   event.notification.close();
   // PushPayload.url is a PATH and WindowClient.url is absolute, so the comparison below is only
   // ever true after resolving — unresolved it matched no client at all and every tap opened a
   // second window on an app the user already had open. Same resolve as the fetch block's.
-  const url=new URL((event.notification.data&&event.notification.data.url)||'/',self.location.origin).href;
+  const url=tapTarget(event.notification.data&&event.notification.data.url);
   event.waitUntil(clients.matchAll({type:'window',includeUncontrolled:true}).then((ws)=>{
     for(const w of ws){if(w.url===url&&'focus'in w)return w.focus()}
     return clients.openWindow(url)

package/src/route-rules.ts

@@ -4,7 +4,9 @@
  * that are no route: content-addressed chunks, cached the first time a page asks for one.
  */
 
+import { routeRank } from '@ultimat3/core';
 import { SwScopeInvalidError } from './errors';
+import type { PersonalPages } from './pages-cache-source';
 import type { PwaRoute, StrategyName } from './strategies';
 import { strategyFor } from './strategies';
 
@@ -23,35 +25,8 @@ const segmentsOf = (path: string): readonly string[] =>
   path.split('/').filter((segment) => segment.length > 0);
 
 /**
- * How specifically a path claims a URL: a literal segment beats a `:param`, which beats a `*`.
- * The weights are `@ultimat3/render`'s `compilePattern`, verbatim (100 / 10 / 1), so the service
- * worker and the server rank the same pathname the same way.
- *
- * DUPLICATED, not imported: `render` and `pwa` are both tier 4 and a sideways import is a build
- * error. The shared home is `@ultimat3/core`'s `route-vocabulary.ts` — tier 0, already the owner of
- * `RENDER_MODES` / `OFFLINE_STRATEGIES` / `HYDRATE_STRATEGIES` for exactly this reason — and moving
- * it there is the follow-up this comment exists to name.
- */
-function specificityOf(path: string): number {
-  return segmentsOf(path).reduce((total, segment) => {
-    if (segment.startsWith('*')) return total + 1;
-    if (segment.startsWith(':')) return total + 10;
-    return total + 100;
-  }, 0);
-}
-
-/**
- * A catch-all is a FALLBACK, and it sorts behind every rule that is not one — a second key, because
- * a sum over segments cannot say it. `/` has no segments and so scores 0, while `/*rest` scores 1:
- * on specificity alone a single root catch-all outranks the home page, and with it every precached
- * entry in the table. The rule this expresses is the one a reader already assumes — a pattern that
- * matches everything answers only what nothing else claimed.
- */
-const hasWildcard = (path: string): boolean =>
-  segmentsOf(path).some((segment) => segment.startsWith('*'));
-
-/**
- * Ordered MOST SPECIFIC FIRST, because the emitted `ruleFor` returns the first pattern that
+ * Ordered MOST SPECIFIC FIRST — `@ultimat3/core`'s `routeRank`, the one rule `@ultimat3/render` and
+ * the request router share — because the emitted `ruleFor` returns the first pattern that
  * matches and has no notion of specificity of its own. Sorted alphabetically it did not: `:` (0x3A)
  * and `*` (0x2A) both sort before every letter, so `/posts/:id` shadowed `/posts/new` and a single
  * `/*` catch-all shadowed the entire table — every entry in `PRECACHE_MANIFEST` downloaded at
@@ -66,17 +41,21 @@ const hasWildcard = (path: string): boolean =>
  */
 const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
 
-export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
+/**
+ * `personalPages: 'last-member'` routes a personal page by its render mode again — the pages facade
+ * partitions it per member. `'never'` (the default) leaves it `network-only`.
+ */
+export function routeRules(
+  routes: readonly PwaRoute[],
+  personalPages: PersonalPages = 'never',
+): readonly RouteRule[] {
   return [...routes]
     .filter((route) => route.surface !== 'api')
-    .sort(
-      (a, b) =>
-        Number(hasWildcard(a.path)) - Number(hasWildcard(b.path)) ||
-        specificityOf(b.path) - specificityOf(a.path) ||
-        byCodeUnit(a.path, b.path),
-    )
+    .sort((a, b) => routeRank(b.path) - routeRank(a.path) || byCodeUnit(a.path, b.path))
     .map((route) => {
-      const strategy = strategyFor(route);
+      const strategy = strategyFor(
+        personalPages === 'last-member' ? { ...route, personal: false } : route,
+      );
       return {
         pattern: toPattern(route.path),
         strategy,
@@ -85,27 +64,53 @@ export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
     });
 }
 
+/**
+ * A personal page that reaches a cache at all goes to `pages`, never `precache`: it is never in the
+ * precache manifest (fetched anonymously at install it is a sign-in redirect), so a `precache` rule
+ * was a cache that always missed — and only the pages facade files a member's page by member.
+ */
 function cacheFor(route: PwaRoute, strategy: StrategyName): 'precache' | 'runtime' | 'pages' {
   if (strategy === 'network-only') return 'runtime';
+  if (route.personal === true) return 'pages';
   if (route.offline === 'precache' && route.dynamic !== true) return 'precache';
   return 'pages';
 }
 
+const escapeRegex = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * A literal segment as the browser's `url.pathname` spells it — the WHATWG serializer itself, so a
+ * route path (the DECODED directory name) matches the PERCENT-ENCODED pathname `ruleFor` tests:
+ * `/precios-españa` and `/a b` were never handled. Not `encodeURI`, which also escapes `|`, `[`,
+ * `^` and `%` where a browser leaves them literal. A `%XX` escape matches either hex case, as a
+ * hand-typed link may carry one.
+ */
+function literal(segment: string): string {
+  const url = new URL('https://x.invalid/');
+  url.pathname = `/${segment}`;
+  return escapeRegex(url.pathname.slice(1)).replace(
+    /%([0-9A-Fa-f]{2})/g,
+    (_, hex: string) =>
+      `%${[...hex].map((c) => (/[A-Fa-f]/.test(c) ? `[${c.toUpperCase()}${c.toLowerCase()}]` : c)).join('')}`,
+  );
+}
+
 /**
  * A trailing slash is dropped before the pattern is built, because the pattern allows one anyway:
- * a locale's home is spelled `/en/`, and `^/en//?$` matched `/en/` and missed `/en`.
+ * a locale's home is spelled `/en/`, and `^/en//?$` matched `/en/` and missed `/en`. A catch-all
+ * takes its leading slash with it, `(?:/.*)?`, so `/docs/*path` matches the bare `/docs` that
+ * `@ultimat3/render`'s static export writes for an empty `path`.
  */
 function toPattern(path: string): string {
-  const bare = path.replace(/\/+$/, '');
-  if (bare === '') return '^/$';
-  const body = bare
-    .split('/')
+  const segments = segmentsOf(path);
+  if (segments.length === 0) return '^/$';
+  const body = segments
     .map((segment) => {
-      if (segment.startsWith(':')) return '[^/]+';
-      if (segment.startsWith('*')) return '.*';
-      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (segment.startsWith(':')) return '/[^/]+';
+      if (segment.startsWith('*')) return '(?:/.*)?';
+      return `/${literal(segment)}`;
     })
-    .join('/');
+    .join('');
   return `^${body}/?$`;
 }
 
@@ -125,7 +130,7 @@ export function assetRules(prefixes: readonly string[], scope: string): readonly
       );
     }
     return {
-      pattern: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+      pattern: `^${escapeRegex(prefix)}`,
       strategy: 'cache-first',
       cache: 'runtime',
       asset: true,

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;
@@ -123,13 +118,12 @@ export function generateServiceWorker(
 
   const fallback = requireOfflineFallback(config.offline);
   const capabilities = resolveCapabilities(config.capabilities);
-  // `last-member` routes a personal page by its render mode again — the pages facade partitions it.
-  // The precache below still skips it: fetched anonymously at install, it is a sign-in redirect.
-  const routed =
-    fallback.personalPages === 'last-member'
-      ? routes.map((route) => ({ ...route, personal: false }))
-      : routes;
-  const rules = [...assetRules(config.runtimeAssets ?? [], scope), ...routeRules(routed)];
+  // The precache below skips a personal page in both modes: fetched anonymously at install, it is a
+  // sign-in redirect. `routeRules` decides where `last-member` keeps it instead — the pages facade.
+  const rules = [
+    ...assetRules(config.runtimeAssets ?? [], scope),
+    ...routeRules(routes, fallback.personalPages),
+  ];
 
   const precache = buildPrecacheManifest({
     buildId,
@@ -163,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());
   }
 
@@ -278,7 +272,9 @@ self.addEventListener('install',(event)=>{
         const e=PRECACHE_MANIFEST[i++];
         try{
           const r=await fetch(new Request(e.url+(e.url.indexOf('?')<0?'?':'&')+'v='+e.revision,{cache:'reload'}));
-          if(r.ok)await cache.put(new Request(e.url),r);
+          // Mid-rollout an OLD pod may answer: its document is not this build's offline copy.
+          const b=r.headers.get(BUILD_HEADER);
+          if(r.ok&&(b===null||b===BUILD_ID))await cache.put(new Request(e.url),r);
         }catch(err){}
       }
     };
@@ -299,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
@@ -390,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);
@@ -409,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;