@ultimat3/pwa 22.14.0 → 22.15.0

package/CLAUDE.md

@@ -17,6 +17,8 @@ Tier 4. May import tiers 0–3: `core`, `schema`, `i18n`, `money`, `time`, `cach
 | 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. |
 | 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. |

package/README.md

@@ -19,7 +19,9 @@ const { source, precache, warnings } = generateServiceWorker(describeRoutes(), c
 
 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()`
+hard reload. `offline: 'precache'` still precaches — for offline. The worker enables navigation
+preload on `activate` and answers a navigation from `event.preloadResponse`, and fills its precache
+`PRECACHE_CONCURRENCY` entries at a time. 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/pwa",
-  "version": "22.14.0",
+  "version": "22.15.0",
   "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.14.0",
-    "@ultimat3/seo": "22.14.0"
+    "@ultimat3/core": "22.15.0",
+    "@ultimat3/seo": "22.15.0"
   }
 }

package/src/index.ts

@@ -110,7 +110,7 @@ export {
 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 { assertScope, generateServiceWorker, PRECACHE_CONCURRENCY } from './service-worker';
 export type {
   PwaRoute,
   StrategyCache,
@@ -120,6 +120,7 @@ export type {
 } from './strategies';
 export {
   cacheFirst,
+  fromNetwork,
   MODE_STRATEGY,
   networkFirst,
   networkOnly,

package/src/service-worker.ts

@@ -29,7 +29,7 @@ import { pushSource } from './push';
 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 { NETWORK_SOURCE, STRATEGY_FN_NAMES, STRATEGY_SOURCE } from './strategies';
 import {
   APP_UPDATE_AVAILABLE,
   assertBuildId,
@@ -158,7 +158,7 @@ export function generateServiceWorker(
     constants(buildId, scope, retained, fallback.neverCache),
     `const PRECACHE_MANIFEST=${serializePrecacheManifest(precache)};`,
     `const ROUTE_RULES=${serializeRules(rules)};`,
-    usedStrategies.map((strategy) => STRATEGY_SOURCE[strategy]).join('\n'),
+    [NETWORK_SOURCE, ...usedStrategies.map((strategy) => STRATEGY_SOURCE[strategy])].join('\n'),
     offlineFallbackSource(fallback, config.localePrefixes ?? []),
     INSTALL_BLOCK,
     activateBlock(),
@@ -252,7 +252,14 @@ function serializeRules(rules: readonly RouteRule[]): string {
  * 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.
+ *
+ * The fill is THROTTLED to `PRECACHE_CONCURRENCY` requests in flight: `Promise.all` over every
+ * entry opened them all at once (72 entries, 2.9 MB on notificado.co), on the visitor's first
+ * visit, against the same connection their first click needs. Nothing waits on the fill but the
+ * worker's own activation, so slower is free.
  */
+export const PRECACHE_CONCURRENCY = 4;
+
 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.
@@ -264,12 +271,18 @@ self.addEventListener('install',(event)=>{
     // first worker that ever installed. A missing entry is fetched from the network when asked for.
     // Revision is a content hash: unchanged assets are not re-downloaded across deploys.
     // The separator is picked per entry: a precache URL may already carry a query.
-    await Promise.all(PRECACHE_MANIFEST.map(async(e)=>{
-      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);
-      }catch(err){}
-    }));
+    // ${PRECACHE_CONCURRENCY} AT A TIME: every entry at once competed with the visitor's first click for the connection.
+    let i=0;
+    const next=async()=>{
+      while(i<PRECACHE_MANIFEST.length){
+        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);
+        }catch(err){}
+      }
+    };
+    await Promise.all(Array.from({length:${PRECACHE_CONCURRENCY}},next));
   })());
 });`.trim();
 
@@ -282,6 +295,9 @@ self.addEventListener('activate',(event)=>{
     await Promise.all(names.filter((n)=>n.startsWith('x-')&&RETAINED.indexOf(n)===-1)
       .map((n)=>caches.delete(n)));
     await self.clients.claim();
+    // Navigation preload: the browser sends a navigation's request WHILE this worker boots, and
+    // 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});
     // NOT part of this waitUntil: a fetch event waits for the worker to finish ACTIVATING, so a
@@ -365,8 +381,17 @@ self.addEventListener('fetch',(event)=>{
   // 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)));
+  // A navigation's preload is the browser's own request, so it carries no build id: skew is read
+  // off the ANSWER instead (seenBuild), which is the new build's document in one round trip.
+  const pre=req.mode==='navigate'&&event.preloadResponse?Promise.resolve(event.preloadResponse).then((r)=>{if(r)seenBuild(r);return r}):undefined;
+  event.respondWith(fn(tagged,cacheName(rule.c),fallbackFor(rule,req),(p)=>event.waitUntil(p),pre).then((res)=>healSkew(req,res)));
 });
+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(()=>{});
+}
 function withBuild(headers){
   const h=new Headers(headers);
   // Once the server has told this worker it is stale, stamping the id again only earns

package/src/strategies.ts

@@ -110,6 +110,32 @@ export interface StrategyOptions {
   readonly cacheName: string;
   /** Served when the network fails and the cache is empty. */
   readonly fallback?: () => Promise<Response>;
+  /**
+   * The fetch event's `preloadResponse`, for a navigation: the request the browser started while
+   * the worker was still booting. Used INSTEAD of a fetch when it resolves to a response.
+   */
+  readonly preload?: Promise<Response | undefined>;
+}
+
+/**
+ * The network's answer — the navigation preload when there is one, else a fetch. A preload that
+ * rejects or resolves empty (the feature is off, or the request was not a navigation) is not a
+ * network failure: the fetch decides that.
+ */
+export async function fromNetwork(
+  request: Request,
+  env: StrategyEnv,
+  options: Pick<StrategyOptions, 'preload'>,
+): Promise<Response> {
+  if (options.preload !== undefined) {
+    try {
+      const early = await options.preload;
+      if (early !== undefined) return early;
+    } catch {
+      // Falls through to the fetch, whose failure is the one the strategy handles.
+    }
+  }
+  return env.fetch(request);
 }
 
 export async function cacheFirst(
@@ -130,7 +156,7 @@ export async function networkFirst(
 ): Promise<Response> {
   const cache = await env.open(options.cacheName);
   try {
-    const response = await env.fetch(request);
+    const response = await fromNetwork(request, env, options);
     if (response.ok) await cache.put(request, response.clone());
     return response;
   } catch (error) {
@@ -149,8 +175,7 @@ export async function staleWhileRevalidate(
 ): Promise<Response> {
   const cache = await env.open(options.cacheName);
   const hit = await cache.match(request);
-  const refresh = env
-    .fetch(request)
+  const refresh = fromNetwork(request, env, options)
     .then(async (response) => {
       if (response.ok) await cache.put(request, response.clone());
       return response;
@@ -173,7 +198,7 @@ export async function networkOnly(
   options: StrategyOptions,
 ): Promise<Response> {
   try {
-    return await env.fetch(request);
+    return await fromNetwork(request, env, options);
   } catch (error) {
     if (options.fallback !== undefined) return options.fallback();
     throw error;
@@ -199,7 +224,7 @@ async function fetchAndStore(
   options: StrategyOptions,
 ): Promise<Response> {
   try {
-    const response = await env.fetch(request);
+    const response = await fromNetwork(request, env, options);
     if (response.ok) await cache.put(request, response.clone());
     return response;
   } catch (error) {
@@ -221,30 +246,41 @@ async function fallbackOrThrow(options: StrategyOptions): Promise<Response> {
  * 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 —
- * the fetch event's `waitUntil`, which keeps the worker alive for the copy.
+ * the fetch event's `waitUntil`, which keeps the worker alive for the copy. The network is `net`
+ * (`NETWORK_SOURCE`), never a bare `fetch`: a navigation's preload answers first.
  */
 export const STRATEGY_SOURCE = Object.freeze<Record<StrategyName, string>>({
-  'cache-first': `async function cacheFirst(req,cn,fb,wait){
+  'cache-first': `async function cacheFirst(req,cn,fb,wait,pre){
   const c=await openCache(cn);const hit=await c.match(req);if(hit)return hit;
-  try{const r=await fetch(req);if(r.ok)later(wait,c.put(req,r.clone()));return r}catch(e){if(fb)return fb();throw e}
+  try{const r=await net(req,pre);if(r.ok)later(wait,c.put(req,r.clone()));return r}catch(e){if(fb)return fb();throw e}
 }`,
-  'network-first': `async function networkFirst(req,cn,fb,wait){
+  'network-first': `async function networkFirst(req,cn,fb,wait,pre){
   const c=await openCache(cn);
-  try{const r=await fetch(req);if(r.ok)later(wait,c.put(req,r.clone()));return r}
+  try{const r=await net(req,pre);if(r.ok)later(wait,c.put(req,r.clone()));return r}
   catch(e){const hit=await c.match(req);if(hit)return hit;if(fb)return fb();throw e}
 }`,
-  'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb,wait){
+  'stale-while-revalidate': `async function staleWhileRevalidate(req,cn,fb,wait,pre){
   const c=await openCache(cn);const hit=await c.match(req);
-  const refresh=fetch(req).then((r)=>{if(r.ok)later(wait,c.put(req,r.clone()));return r})
+  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()));
   if(hit){later(wait,refresh);return hit}
   return refresh
 }`,
-  'network-only': `async function networkOnly(req,cn,fb,wait){
-  try{return await fetch(req)}catch(e){if(fb)return fb();throw e}
+  'network-only': `async function networkOnly(req,cn,fb,wait,pre){
+  try{return await net(req,pre)}catch(e){if(fb)return fb();throw e}
 }`,
 });
 
+/**
+ * The emitted `fromNetwork`: every strategy source above reaches the network through it. `pre` is
+ * the fetch event's `preloadResponse` for a navigation — the request the browser made in parallel
+ * with the worker's start-up — and `undefined` for everything else.
+ */
+export const NETWORK_SOURCE = `async function net(req,pre){
+  if(pre){try{const r=await pre;if(r)return r}catch(e){}}
+  return fetch(req)
+}`;
+
 export const STRATEGY_FN_NAMES = Object.freeze<Record<StrategyName, string>>({
   'cache-first': 'cacheFirst',
   'network-first': 'networkFirst',