@ultimat3/pwa 22.3.1 → 22.3.2

package/CLAUDE.md

@@ -15,7 +15,8 @@ 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. |
 | 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. |

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "22.3.1",
+  "version": "22.3.2",
   "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.2",
+    "@ultimat3/seo": "22.3.2"
   }
 }

package/src/service-worker.ts

@@ -308,9 +308,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,6 +398,10 @@ 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 {
   return `

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';
@@ -52,6 +53,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,10 +74,10 @@ 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 {