@ultimat3/pwa 22.3.1 → 22.3.3

package/CLAUDE.md

@@ -15,7 +15,10 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
 | 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. |
+| 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. |
+| 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. |
 | 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. |
@@ -33,7 +36,7 @@ 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 served from cache while online, and partitioned by principal offline (21.0.0, security). The pages cache was keyed by URL alone, so `/feed` (`stream`, SWR) rendered for kenji answered bruno on a shared browser. The emitted strategies open caches through `openCache`; for `PAGES` that is a facade: a shareable response is stored and read as before, a PRIVATE one (`private`/`no-store`, or carrying `x-ultimate-scope` — `CLIENT_SCOPE_HEADER`, set by `@ultimat3/cli`'s `dev-render.ts` exactly where the scope meta is) is never read from `PAGES` and is kept only in `PAGES~<scope>`, written in the BACKGROUND (a stream's put would otherwise hold the navigation) and read only by `pageOffline`. Storing one principal's page deletes every other partition, so offline answers the most recent member only; private with no scope is not kept at all. `service-worker-runtime.test.ts` runs two members on one URL. |
+| 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. |
 | 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. |

package/README.md

@@ -12,11 +12,15 @@ const { source, precache, warnings } = generateServiceWorker(describeRoutes(), c
 
 | Render mode | Strategy | Why |
 |---|---|---|
-| `static` | cache-first | built once; the URL's bytes only change on deploy |
-| `isr` | stale-while-revalidate | stale is correct by construction, refresh behind |
-| `stream` | stale-while-revalidate | shell is reusable, holes come from the network |
+| `static` | network-first | the document names this deploy's hashed assets; the precache is the offline copy |
+| `isr` | network-first | the server's ISR cache is already the stale one; a browser copy only delays a deploy |
+| `stream` | network-first | the shell names this deploy's chunks; the cache is the offline copy |
 | `ssr` | network-first | freshness is the point; cache is the offline safety net |
-| `spa` | cache-first | the shell is identical for every actor |
+
+Every rule is a document, so every mode is network-first (22.3.2): `static` was cache-first and
+`isr`/`stream` stale-while-revalidate, and an online visitor got the previous deploy's HTML until a
+hard reload. `offline: 'precache'` still precaches — for offline. The worker calls `skipWaiting()`
+in `install`, so a deploy takes over without every tab closing; it never reloads a page.
 
 Overrides: `offline: 'network-only'` forces `network-only`; a per-route `strategy` wins over
 everything. `api/` routes get no cache rule at all.
@@ -101,7 +105,9 @@ 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 |
+| `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 |
+| `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 |
 | `generateWebManifest` | the manifest + `theme-color` metas for both schemes, from a `WebManifestInput`. Called by `@ultimat3/cli` (`pwa-artifacts.ts`) `As of 2026-08-27`, so `x dev`, the container and the static export all emit `manifest.webmanifest` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "22.3.1",
+  "version": "22.3.3",
   "description": "Generated service worker, web manifest, icons, push and version-skew handling.",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.3.1",
-    "@ultimat3/seo": "22.3.1"
+    "@ultimat3/core": "22.3.3",
+    "@ultimat3/seo": "22.3.3"
   }
 }

package/src/index.ts

@@ -84,6 +84,8 @@ export type {
 export { generateWebManifest, renderThemeColorMeta, serializeWebManifest } from './manifest';
 export type { OfflineConfig, OfflineFallback } from './offline-fallback';
 export { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
+export type { PersonalPages } from './pages-cache-source';
+export { CLEAR_PAGES_MESSAGE, PAGES_CLEARED_MESSAGE } from './pages-cache-source';
 export type { PrecacheAsset, PrecacheEntry, PrecacheInput, PrecacheManifest } from './precache';
 export {
   buildPrecacheManifest,
@@ -105,8 +107,10 @@ export {
   subscribeSource,
   subscriptionState,
 } from './push';
-export type { RouteRule, ServiceWorkerConfig, ServiceWorkerOutput } from './service-worker';
-export { assertScope, generateServiceWorker, routeRules } from './service-worker';
+export type { RouteRule } from './route-rules';
+export { assetRules, routeRules } from './route-rules';
+export type { ServiceWorkerConfig, ServiceWorkerOutput } from './service-worker';
+export { assertScope, generateServiceWorker } from './service-worker';
 export type {
   PwaRoute,
   StrategyCache,

package/src/offline-fallback.ts

@@ -5,6 +5,7 @@
  */
 
 import { PwaNoOfflineFallbackError } from './errors';
+import type { PersonalPages } from './pages-cache-source';
 
 export interface OfflineConfig {
   /** Route path of the offline document, e.g. `/offline`. Required. */
@@ -14,6 +15,8 @@ export interface OfflineConfig {
   readonly font?: string;
   /** Requests that must never be answered from a cache (auth, payments). */
   readonly neverCache?: readonly string[];
+  /** A page rendered for someone: `'never'` cached (default), or `'last-member'`. `PersonalPages`. */
+  readonly personalPages?: PersonalPages;
 }
 
 export interface OfflineFallback {
@@ -21,6 +24,7 @@ export interface OfflineFallback {
   readonly image: string | null;
   readonly font: string | null;
   readonly neverCache: readonly string[];
+  readonly personalPages: PersonalPages;
 }
 
 /**
@@ -80,18 +84,32 @@ export function requireOfflineFallback(
     image: config.image ?? null,
     font: config.font ?? null,
     neverCache: config.neverCache ?? [],
+    personalPages: config.personalPages === 'last-member' ? 'last-member' : 'never',
   };
 }
 
-/** Emitted into `sw.js`: what to serve when a navigation cannot be answered. */
-export function offlineFallbackSource(fallback: OfflineFallback): string {
+/**
+ * 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.
+ */
+export function offlineFallbackSource(
+  fallback: OfflineFallback,
+  localePrefixes: readonly string[] = [],
+): string {
   const image = fallback.image === null ? 'null' : JSON.stringify(fallback.image);
+  const locales = [...new Set(localePrefixes)].sort();
   return `
 const OFFLINE_DOC=${JSON.stringify(fallback.document)};
 const OFFLINE_IMAGE=${image};
+const OFFLINE_LOCALES=${JSON.stringify(locales)};
 async function offlineFallback(req){
   const c=await caches.open(PRECACHE);
-  if(req.mode==='navigate'){const d=await c.match(OFFLINE_DOC);if(d)return d}
+  if(req.mode==='navigate'){
+    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}
   return new Response('',{status:503,statusText:'Offline'})
 }`.trim();

package/src/pages-cache-source.ts

@@ -1,25 +1,66 @@
 /**
- * The emitted worker's page storage, as source: the facade every strategy opens the pages cache
- * through, the per-principal partitions a private document is kept in, the background copy, and
- * the offline read. Its own module because `service-worker.ts` is the rest of `sw.js`; it is
- * spliced into the fetch block and reads that block's constants (`PAGES`, `SCOPE_HEADER`) and
- * `warming` from the activate block. `service-worker-pages.test.ts` runs it.
+ * The emitted worker's cache access, as source: the guard every strategy opens a cache through, the
+ * background copy, the offline page read and the sign-out purge. Its own module because
+ * `service-worker.ts` is the rest of `sw.js`; it is spliced into the fetch block and reads that
+ * block's constants (`PAGES`, `PAGES_PREFIX`, `SCOPE_HEADER`) and `warming` from the activate block.
+ * `service-worker-pages.test.ts` runs both modes.
  */
 
-export const PAGES_CACHE_SOURCE = `// The pages cache is a FACADE, because a document rendered for one member is not a page: keyed by
-// URL alone, /feed rendered for kenji answered bruno on the same browser. A shareable document is
-// stored and read as before. A private one (\`private\`/\`no-store\`, or carrying the scope header)
-// is never read from here — so no strategy can answer it from cache while online — and is kept
-// only in its principal's own partition, PAGES~<scope>, which offline alone reads. Storing one
-// principal's page wipes every other partition: offline answers the most recent member only.
-function openCache(cn){return cn===PAGES?pagesCache():caches.open(cn)}
-// A cache copy the strategy does NOT await: handed to the event's waitUntil when there is one, and
+/**
+ * What a page posts to the active worker on sign-out — `navigator.serviceWorker.controller
+ * ?.postMessage({ type: 'clear-pages' })` — to empty every build's pages cache. The worker answers
+ * the posting window with `{ type: 'pages-cleared' }` once they are gone.
+ */
+export const CLEAR_PAGES_MESSAGE = 'clear-pages';
+export const PAGES_CLEARED_MESSAGE = 'pages-cleared';
+
+/** Every build's pages cache starts with this — `cacheNamespace(id, 'pages')` is `x-pages-<id>`. */
+export const PAGES_CACHE_PREFIX = 'x-pages-';
+
+/**
+ * What the worker does with a page rendered for someone — `pwa.offline.personalPages`.
+ *
+ * `'never'`, the default `As of 22.3.3`: not cached, in any cache, under any rule, and a personal
+ * route is `network-only`. `'last-member'`: 21.0.0's offline-first mode, kept for an app that
+ * declares it — never answered from cache online, kept only in the most recent member's own
+ * partition for offline. An app that picks it must clear on sign-out (`clear-pages`, or
+ * `Clear-Site-Data: "storage"`): on a shared device the partition is the previous member's data.
+ */
+export type PersonalPages = 'never' | 'last-member';
+
+const SHARED = `// A cache copy the strategy does NOT await: handed to the event's waitUntil when there is one, and
 // never allowed to reject into nobody — a failed copy costs the copy, not the response.
 function later(wait,p){const settled=p.catch(()=>{});if(wait)wait(settled);return settled}
 function isPrivate(r){
   if(r.headers.has(SCOPE_HEADER))return true;
   return /(^|,)\\s*(private|no-store)\\s*(,|$)/i.test(r.headers.get('cache-control')||'')
 }
+// Every cache but the pages cache is GUARDED in both modes: a private response is never stored there.
+function guarded(c){return{match:(req)=>c.match(req),put:async(req,r)=>{if(!isPrivate(r))return c.put(req,r)}}}
+function fallbackFor(rule,req){return rule.c==='pages'?()=>pageOffline(req):()=>offlineFallback(req)}
+// The app's sign-out: every build's pages cache, and every per-member partition.
+async function clearPages(){
+  const names=await caches.keys();
+  await Promise.all(names.filter((n)=>n.startsWith(PAGES_PREFIX)).map((n)=>caches.delete(n)));
+}`;
+
+const NEVER = `// A private response (\`private\`/\`no-store\`, or carrying the scope header) is never stored,
+// whatever the rule. 21.0.0 kept one per member for offline, and after sign-out an offline
+// navigation on a shared device answered the previous member's data. \`no-store\` means what it says.
+function openCache(cn){return caches.open(cn).then(guarded)}
+/** Offline only: the shared copy (a warm-up may have landed it late), then the offline document. */
+async function pageOffline(req){
+  await warming;
+  const shared=await (await caches.open(PAGES)).match(req);
+  if(shared)return shared;
+  return offlineFallback(req)
+}`;
+
+const LAST_MEMBER = `// personalPages: 'last-member'. The pages cache is a FACADE: a shareable document is stored and
+// read as before; a private one is never read from here — so no strategy answers it from cache
+// while online — and is kept only in its principal's own partition, PAGES~<scope>, which offline
+// alone reads. Storing one principal's page wipes every other partition. clear-pages empties them.
+function openCache(cn){return cn===PAGES?Promise.resolve(pagesCache()):caches.open(cn).then(guarded)}
 function pagesCache(){return{
   match:async(req)=>(await caches.open(PAGES)).match(req),
   put:async(req,r)=>{
@@ -27,9 +68,7 @@ function pagesCache(){return{
     const scope=r.headers.get(SCOPE_HEADER);
     // Private with no scope: no principal to file it under, so it is not kept at all.
     if(scope===null)return;
-    // NOT awaited by the strategy: a private document is usually a stream, and a strategy awaits
-    // its put before answering — the navigation would wait for the whole body to be copied into
-    // the cache. The offline read waits for it instead (pageOffline), which is the only reader.
+    // In the background: a private document is usually a stream, and the offline read waits for it.
     keeping=keeping.then(()=>keepScoped(req,r,PAGES+'~'+scope)).catch(()=>{});
   }
 }}
@@ -39,11 +78,10 @@ async function keepScoped(req,r,name){
   const names=await caches.keys();
   await Promise.all(names.filter((n)=>n.startsWith(PAGES+'~')&&n!==name).map((n)=>caches.delete(n)));
 }
-/** Offline only: the most recent member's own copy, then the offline document. */
+/** Offline only: the shared copy, then the most recent member's own copy, then the offline document. */
 async function pageOffline(req){
   await warming;
   await keeping;
-  // The shared copy first — a warm-up may have landed it after the strategy's own read missed.
   const shared=await (await caches.open(PAGES)).match(req);
   if(shared)return shared;
   for(const n of await caches.keys()){
@@ -52,5 +90,7 @@ async function pageOffline(req){
     if(hit)return hit;
   }
   return offlineFallback(req)
-}
-function fallbackFor(rule,req){return rule.c==='pages'?()=>pageOffline(req):()=>offlineFallback(req)}`;
+}`;
+
+export const pagesCacheSource = (mode: PersonalPages): string =>
+  `${mode === 'last-member' ? LAST_MEMBER : NEVER}\n${SHARED}`;

package/src/precache.ts

@@ -8,6 +8,7 @@
 // budget message on the other side of the build stopped at `kb`, for the same byte count.
 import { finiteCount, formatBytes } from '@ultimat3/core';
 import type { PwaRoute } from './strategies';
+import { strategyFor } from './strategies';
 
 export interface PrecacheAsset {
   readonly url: string;
@@ -102,6 +103,10 @@ export function buildPrecacheManifest(input: PrecacheInput): PrecacheManifest {
     if (route.offline !== 'precache') continue;
     // A dynamic route has no single URL to precache; its instances are runtime-cached.
     if (route.dynamic === true) continue;
+    // A page the worker will never answer from a cache (`personal`, or an explicit network-only
+    // override) is not worth an install-time download — and a personal one fetched anonymously
+    // at install is a sign-in redirect, stored.
+    if (strategyFor(route) === 'network-only') continue;
     add({
       url: route.path,
       revision: route.revision ?? input.buildId,

package/src/route-rules.ts

@@ -0,0 +1,134 @@
+/**
+ * The route table as the worker's rule list: which pattern, which strategy, which cache — ordered
+ * most specific first, because the emitted `ruleFor` answers the FIRST match. Plus the asset rules
+ * that are no route: content-addressed chunks, cached the first time a page asks for one.
+ */
+
+import { SwScopeInvalidError } from './errors';
+import type { PwaRoute, StrategyName } from './strategies';
+import { strategyFor } from './strategies';
+
+export interface RouteRule {
+  readonly pattern: string;
+  readonly strategy: StrategyName;
+  readonly cache: 'precache' | 'runtime' | 'pages';
+  /**
+   * An asset prefix, not a page: fetched as the browser asked (no build-id header — a classic
+   * script is a `no-cors` request, whose headers a worker may not extend) and never warmed.
+   */
+  readonly asset?: true;
+}
+
+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
+ * 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
+ * install and then never looked up, and a route the app declared cacheable served `network-only`,
+ * which offline is the `/offline` document.
+ *
+ * The path stays as the tie-break, so the emitted file is still byte-identical for identical input
+ * — compared by CODE UNIT, never `localeCompare`, which answers from the runtime's ICU default and
+ * collation version: `/Posts` sorted before `/posts` on one machine and after it on the next, for
+ * the same route table. The rule `@ultimat3/jobs`' `job.ts` states for `x.manifest.json`, applied
+ * to the artifact this file emits.
+ */
+const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+export function routeRules(routes: readonly PwaRoute[]): 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),
+    )
+    .map((route) => {
+      const strategy = strategyFor(route);
+      return {
+        pattern: toPattern(route.path),
+        strategy,
+        cache: cacheFor(route, strategy),
+      };
+    });
+}
+
+function cacheFor(route: PwaRoute, strategy: StrategyName): 'precache' | 'runtime' | 'pages' {
+  if (strategy === 'network-only') return 'runtime';
+  if (route.offline === 'precache' && route.dynamic !== true) return 'precache';
+  return 'pages';
+}
+
+/**
+ * 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`.
+ */
+function toPattern(path: string): string {
+  const bare = path.replace(/\/+$/, '');
+  if (bare === '') return '^/$';
+  const body = bare
+    .split('/')
+    .map((segment) => {
+      if (segment.startsWith(':')) return '[^/]+';
+      if (segment.startsWith('*')) return '.*';
+      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    })
+    .join('/');
+  return `^${body}/?$`;
+}
+
+/**
+ * `runtimeAssets` as rules, AHEAD of every page rule: a prefix like `/islands/` names
+ * content-addressed chunks, so the first copy is the only copy and `cache-first` is exact. They are
+ * what the precache leaves out — every island in the app was precached, so a first anonymous visit
+ * downloaded the admin, KYC and payment islands too (~1 MB on notificado.co, 22.3.2).
+ */
+export function assetRules(prefixes: readonly string[], scope: string): readonly RouteRule[] {
+  return [...new Set(prefixes)].sort(byCodeUnit).map((prefix) => {
+    if (!prefix.startsWith(scope)) {
+      throw new SwScopeInvalidError(
+        `runtime asset prefix ${JSON.stringify(prefix)} is not an absolute path under the ` +
+          `worker's scope ${scope}, so no request pathname would ever match it`,
+        `name the prefix as the browser requests it, e.g. '${scope}islands/'`,
+      );
+    }
+    return {
+      pattern: `^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`,
+      strategy: 'cache-first',
+      cache: 'runtime',
+      asset: true,
+    };
+  });
+}

package/src/service-worker.ts

@@ -15,13 +15,21 @@ import { isEnabled, resolveCapabilities } from './capabilities';
 import { SwScopeInvalidError } from './errors';
 import type { OfflineConfig } from './offline-fallback';
 import { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
-import { PAGES_CACHE_SOURCE } from './pages-cache-source';
+import type { PersonalPages } from './pages-cache-source';
+import {
+  CLEAR_PAGES_MESSAGE,
+  PAGES_CACHE_PREFIX,
+  PAGES_CLEARED_MESSAGE,
+  pagesCacheSource,
+} from './pages-cache-source';
 import type { PrecacheAsset, PrecacheManifest } from './precache';
 import { buildPrecacheManifest, serializePrecacheManifest } from './precache';
 import type { VapidConfig } from './push';
 import { pushSource } from './push';
-import type { PwaRoute, StrategyName } from './strategies';
-import { STRATEGY_FN_NAMES, STRATEGY_SOURCE, strategyFor } from './strategies';
+import type { RouteRule } from './route-rules';
+import { assetRules, routeRules } from './route-rules';
+import type { PwaRoute } from './strategies';
+import { STRATEGY_FN_NAMES, STRATEGY_SOURCE } from './strategies';
 import {
   APP_UPDATE_AVAILABLE,
   assertBuildId,
@@ -54,17 +62,22 @@ export interface ServiceWorkerConfig {
   readonly offlineFallbackRevision?: string;
   readonly offlineFallbackBytes?: number;
   readonly vapid?: VapidConfig;
+  /**
+   * Path prefixes of content-addressed assets the precache leaves out (`/islands/`), cached the
+   * first time a page asks for one — `cache-first`, runtime cache. See `assetRules`.
+   */
+  readonly runtimeAssets?: readonly string[];
+  /**
+   * The URL segments of every non-default routed locale (`['en']` for an `es-co` app). A navigation
+   * under `/en/` that finds no network gets `/en` + the offline document when that one is
+   * precached, never the default locale's page.
+   */
+  readonly localePrefixes?: readonly string[];
   /** Build ids whose caches must survive this activation (see `retentionPlan`). */
   readonly retainBuildIds?: readonly string[];
   readonly precacheWarnBytes?: number;
 }
 
-export interface RouteRule {
-  readonly pattern: string;
-  readonly strategy: StrategyName;
-  readonly cache: 'precache' | 'runtime' | 'pages';
-}
-
 export interface ServiceWorkerOutput {
   readonly source: string;
   readonly precache: PrecacheManifest;
@@ -98,91 +111,6 @@ export function assertScope(swPath: string, scope: string): void {
   }
 }
 
-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
- * 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
- * install and then never looked up, and a route the app declared cacheable served `network-only`,
- * which offline is the `/offline` document.
- *
- * The path stays as the tie-break, so the emitted file is still byte-identical for identical input
- * — compared by CODE UNIT, never `localeCompare`, which answers from the runtime's ICU default and
- * collation version: `/Posts` sorted before `/posts` on one machine and after it on the next, for
- * the same route table. The rule `@ultimat3/jobs`' `job.ts` states for `x.manifest.json`, applied
- * to the artifact this file emits.
- */
-const byCodeUnit = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
-
-export function routeRules(routes: readonly PwaRoute[]): 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),
-    )
-    .map((route) => {
-      const strategy = strategyFor(route);
-      return {
-        pattern: toPattern(route.path),
-        strategy,
-        cache: cacheFor(route, strategy),
-      };
-    });
-}
-
-function cacheFor(route: PwaRoute, strategy: StrategyName): 'precache' | 'runtime' | 'pages' {
-  if (strategy === 'network-only') return 'runtime';
-  if (route.offline === 'precache' && route.dynamic !== true) return 'precache';
-  return 'pages';
-}
-
-function toPattern(path: string): string {
-  if (path === '/') return '^/$';
-  const body = path
-    .split('/')
-    .map((segment) => {
-      if (segment.startsWith(':')) return '[^/]+';
-      if (segment.startsWith('*')) return '.*';
-      return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    })
-    .join('/');
-  return `^${body}/?$`;
-}
-
 /** Emit `sw.js`. `routes` are `@ultimat3/render` descriptors, passed as data. */
 export function generateServiceWorker(
   routes: readonly PwaRoute[],
@@ -195,7 +123,13 @@ export function generateServiceWorker(
 
   const fallback = requireOfflineFallback(config.offline);
   const capabilities = resolveCapabilities(config.capabilities);
-  const rules = routeRules(routes);
+  // `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)];
 
   const precache = buildPrecacheManifest({
     buildId,
@@ -225,10 +159,10 @@ export function generateServiceWorker(
     `const PRECACHE_MANIFEST=${serializePrecacheManifest(precache)};`,
     `const ROUTE_RULES=${serializeRules(rules)};`,
     usedStrategies.map((strategy) => STRATEGY_SOURCE[strategy]).join('\n'),
-    offlineFallbackSource(fallback),
+    offlineFallbackSource(fallback, config.localePrefixes ?? []),
     INSTALL_BLOCK,
     activateBlock(),
-    fetchBlock(),
+    fetchBlock(fallback.personalPages),
     messageBlock(isEnabled(capabilities, 'backgroundSync')),
   ];
 
@@ -272,6 +206,7 @@ const SCOPE=${JSON.stringify(scope)};
 const PRECACHE=${JSON.stringify(cacheNamespace(buildId, 'precache'))};
 const RUNTIME=${JSON.stringify(cacheNamespace(buildId, 'runtime'))};
 const PAGES=${JSON.stringify(cacheNamespace(buildId, 'pages'))};
+const PAGES_PREFIX=${JSON.stringify(PAGES_CACHE_PREFIX)};
 const RETAINED=${JSON.stringify(retainedCaches(retained))};
 const NEVER_CACHE=${JSON.stringify(neverCache)};
 const BUILD_HEADER=${JSON.stringify(BUILD_ID_HEADER)};
@@ -291,7 +226,7 @@ function serializeRules(rules: readonly RouteRule[]): string {
   const rows = rules.map(
     (rule) =>
       `{"p":${JSON.stringify(rule.pattern)},"s":${JSON.stringify(STRATEGY_FN_NAMES[rule.strategy])},` +
-      `"c":${JSON.stringify(rule.cache)}}`,
+      `"c":${JSON.stringify(rule.cache)}${rule.asset === true ? ',"a":1' : ''}}`,
   );
   return `[${rows.join(',')}]`;
 }
@@ -308,9 +243,20 @@ function serializeRules(rules: readonly RouteRule[]): string {
  * and a bundler emits a query of its own: a fixed `?` built `...?locale=en?v=<rev>`, and a single
  * non-200 for it rejects `addAll`, which rejects the install — no precache, no offline document,
  * no version-skew header, and a worker that never activates at all.
+ *
+ * `skipWaiting()` FIRST, `As of 22.3.2`: a new worker activates as soon as its precache is filled,
+ * never "once every tab of the origin is closed", which for a returning visitor was days. Nothing
+ * else could do it — no page ever posted `skip-waiting` — and it has to be the worker's own call,
+ * because the one that must converge is a browser still running a 22.3.1 worker and that release's
+ * register script, neither of which will ever ask. Safe for a tab open across the release: this
+ * worker routes documents only (content-hashed chunks come from the network and the HTTP cache,
+ * never from a cache it deletes on activate), and it never reloads a page — the tab's NEXT
+ * navigation is answered network-first by the new worker.
  */
 const INSTALL_BLOCK = `
 self.addEventListener('install',(event)=>{
+  // Take over as soon as the precache is in: a waiting worker otherwise waits for every tab to close.
+  self.skipWaiting();
   event.waitUntil((async()=>{
     const cache=await caches.open(PRECACHE);
     // Revision is a content hash: unchanged assets are not re-downloaded across deploys.
@@ -387,15 +333,19 @@ const SKEW_STATUS = 409;
  * is stale, it stops stamping, re-issues the request untagged so the document actually loads, and
  * tells every window an update is waiting. Skew detection is not lost — it has already fired, and
  * its whole purpose is to get the client onto the new build, which is what the app now does.
+ *
+ * Still needed after the install block's `skipWaiting()` (22.3.2): that removes the WAITING half,
+ * but the server can roll forward before the browser has fetched the new `sw.js` at all, and a
+ * worker from before 22.3.2 is the one answering in between.
  */
-function fetchBlock(): string {
+function fetchBlock(personalPages: PersonalPages): string {
   return `
 function ruleFor(url){
   for(const r of ROUTE_RULES){if(new RegExp(r.p).test(url.pathname))return r}
   return null
 }
 function cacheName(kind){return kind==='precache'?PRECACHE:kind==='pages'?PAGES:RUNTIME}
-${PAGES_CACHE_SOURCE}
+${pagesCacheSource(personalPages)}
 const STRATEGIES={cacheFirst:typeof cacheFirst==='function'?cacheFirst:null,
   networkFirst:typeof networkFirst==='function'?networkFirst:null,
   staleWhileRevalidate:typeof staleWhileRevalidate==='function'?staleWhileRevalidate:null,
@@ -410,8 +360,9 @@ self.addEventListener('fetch',(event)=>{
   if(!rule)return;
   const fn=STRATEGIES[rule.s];
   if(!fn)return;
-  // Every proxied request carries the client's build id so the server can detect skew.
-  const tagged=new Request(req,{headers:withBuild(req.headers)});
+  // Every proxied DOCUMENT carries the client's build id so the server can detect skew. An asset
+  // goes as the browser asked: a no-cors request's headers cannot be extended.
+  const tagged=rule.a?req:new Request(req,{headers:withBuild(req.headers)});
   event.respondWith(fn(tagged,cacheName(rule.c),fallbackFor(rule,req),(p)=>event.waitUntil(p)).then((res)=>healSkew(req,res)));
 });
 function withBuild(headers){
@@ -456,6 +407,7 @@ function messageBlock(backgroundSync: boolean): string {
 self.addEventListener('message',(event)=>{
   const d=event.data||{};
   if(d.type==='skip-waiting')self.skipWaiting();
-  if(d.type==='build-id')event.source&&event.source.postMessage({type:'build-id',buildId:BUILD_ID});${flush}
+  if(d.type==='build-id')event.source&&event.source.postMessage({type:'build-id',buildId:BUILD_ID});
+  if(d.type===${JSON.stringify(CLEAR_PAGES_MESSAGE)})event.waitUntil(clearPages().then(()=>event.source&&event.source.postMessage({type:${JSON.stringify(PAGES_CLEARED_MESSAGE)}})));${flush}
 });`.trim();
 }

package/src/strategies.ts

@@ -1,7 +1,8 @@
 /**
  * The four caching strategies as named functions, plus the render-mode → strategy table.
- * You never choose a strategy by hand: the route's render mode already encodes how fresh
- * its bytes have to be, so the mapping is derived and the override is the exception.
+ * You never choose a strategy by hand: the mapping is derived and the override is the exception.
+ * Every rule the worker routes is a DOCUMENT, and a document is network-first in every mode — the
+ * cached copy is what offline gets, never what an online visitor gets (22.3.2).
  */
 
 import type { OfflineStrategy, RenderMode } from '@ultimat3/core';
@@ -32,6 +33,12 @@ export interface PwaRoute {
   readonly dynamic?: boolean;
   /** Explicit per-route override; wins over the derived strategy. */
   readonly strategy?: StrategyName;
+  /**
+   * Rendered FOR someone — a policy, a `stream`, a declared `no-store`/`private` cache (render's
+   * `RouteDescriptor.personal`). Such a page is `network-only` and never precached: kept for
+   * offline, it answered the previous member's data on a shared device after sign-out.
+   */
+  readonly personal?: boolean;
   /**
    * Content hash of the built HTML — the precache revision. Fed by the CLI's prerender pass; the
    * `buildId` is the fallback, and it re-downloads every precached page on every deploy.
@@ -52,6 +59,16 @@ export interface PwaRoute {
 /**
  * Render mode → runtime strategy. The whole reason `sw.js` is generated, not written.
  *
+ * Every row is `network-first`, `As of 22.3.2`, because every rule this table feeds is a
+ * DOCUMENT: `routeRules` projects page routes only, and content-hashed chunks never get a rule —
+ * they are `immutable` in the browser's HTTP cache. `static: 'cache-first'` and
+ * `isr`/`stream: 'stale-while-revalidate'` answered an ONLINE navigation from the copy the old
+ * worker held, and that copy is the old HTML naming the old hashed CSS and islands, so a visitor saw
+ * a deploy only after Shift+F5 (measured on notificado.co, 22.3.1). A precached or pages-cached
+ * document is the OFFLINE answer, which `networkFirst` already is on a failed fetch; the render
+ * mode still decides WHERE that copy lives (`cacheFor`: precache or pages), not whether it is
+ * served while the network answers. A per-route `strategy` is still the override.
+ *
  * Two separate things make the closed set hold, and the table needed both. `Record<RenderMode, …>`
  * over the TIER-0 union is the exhaustiveness check — this was keyed on a hand-copy, which is how
  * `spa` went on mapping to `cache-first` after `spa` was deleted from the vocabulary: the one
@@ -63,16 +80,16 @@ export interface PwaRoute {
  * AND an extra key are both build errors.
  */
 export const MODE_STRATEGY = Object.freeze<Record<RenderMode, StrategyName>>({
-  static: 'cache-first',
-  isr: 'stale-while-revalidate',
+  static: 'network-first',
+  isr: 'network-first',
   ssr: 'network-first',
-  stream: 'stale-while-revalidate',
+  stream: 'network-first',
 });
 
 export function strategyFor(route: PwaRoute): StrategyName {
   if (route.strategy !== undefined) return route.strategy;
   // `network-only` is a declaration that this URL must never be answered from a cache.
-  if (route.offline === 'network-only') return 'network-only';
+  if (route.offline === 'network-only' || route.personal === true) return 'network-only';
   return MODE_STRATEGY[route.mode];
 }