@swoff/cli 0.3.7 → 0.3.9

package/dist/lib/generators/sw-sections/fetch-handler.js

@@ -6,65 +6,314 @@
  *   2. URL pattern match — from features.serviceWorker.strategies in swoff.config.json
  *   3. defaultStrategy — fallback from features.serviceWorker.defaultStrategy
  *
- * Cache strategy mode (features.serviceWorker.cacheStrategy):
- *   "all"           — all GET/HEAD requests go through the strategy system (default)
- *   "explicit-only" — only requests with X-SW-Cache-Strategy header go through strategy;
- *                     plain fetch() calls pass through the SW unmodified
+ * Strategies:
+ *   - cache-first:      Serve cache if exists, fetch if missing. No bg refresh.
+ *   - network-first:    Try network first, fall back to cache on failure.
+ *   - stale-while-revalidate: Serve cache + always refresh in background.
+ *   - cache-only:       Never fetch. Cache hit or 404.
+ *   - network-only:     Never cache. Always fetch.
+ *   - reactive:         Serve cache + refresh on configurable triggers (interval,
+ *                       onFocus, onReconnect). staleTime gates ALL triggers.
  *
- * Request dispatch flow:
- *   navigation (SPA fallback) → precache → strategy (if applicable) → pass-through
+ * staleTime, refetchInterval, refetchOnFocus, refetchOnReconnect are
+ * reactive-only fields. Non-reactive strategies ignore them.
+ *
+ * Background refreshes use a shared batch queue with rate limiting.
+ * On successful refresh, CACHE_UPDATED is posted to all clients.
  */
-export function generateFetchHandler(swConfig, tagInvalidation) {
-    const { defaultStrategy, strategies, cacheStrategy = "all", maxCacheEntries, maxCacheAge, navigationPreload, navigationMode, spaEntry } = swConfig;
-    const hasPerRouteLimits = Object.values(strategies || {}).some((s) => typeof s === "object" && (s.maxCacheEntries || s.maxCacheAge));
-    const hasTrim = (maxCacheEntries ?? 0) > 0 || (maxCacheAge ?? 0) > 0 || hasPerRouteLimits;
-    const navMode = navigationMode ?? "spa";
-    const spaPath = spaEntry ?? "/index.html";
+export function generateFetchHandler(swConfig, tagInvalidation, mutationQueueEnabled) {
+    const { strategy: { default: defaultStrategy, patterns: strategies, mode: cacheStrategy = "all", normalizeKey: normalizeCacheKey, ignoreQueryParams }, navigation: { mode: navMode = "spa", preload: navigationPreload, fallback: spaPath = "/index.html" }, refetchQueue: { batchSize: refetchBatchSize = 5, batchDelayMs: refetchBatchDelayMs = 1000, maxRetries: refetchMaxRetries = 3, retryDelayMs: refetchRetryDelayMs = 1000 } } = swConfig;
+    const { staleTime: globalStaleTime, refetchInterval: globalRefetchInterval, refetchOnReconnect: globalRefetchOnReconnect, refetchOnFocus: globalRefetchOnFocus } = swConfig.strategy.reactive?.defaults || {};
     const staleVersionCode = tagInvalidation ? `
     cleanStaleVersions();
-    if (staleVersions.has(request.url)) {
-      event.waitUntil(refreshCache(request).then(() => staleVersions.delete(request.url)));
+    if (staleVersions.has(cacheKey(request))) {
+      queueRefresh(cacheKey(request), new URL(request.url).href);
     }` : "";
     const tagCode = tagInvalidation ? `
   const tagsHeader = request.headers.get("X-SW-Cache-Tags");
   if (tagsHeader) {
-    const url = new URL(request.url).href;
+    const cacheKeyUrl = cacheKey(request);
+    const actualUrl = new URL(request.url).href;
     const tags = tagsHeader.split(",").map((t) => t.trim());
-    await cacheTagUrl(url, tags);
+    await cacheTagUrl(cacheKeyUrl, actualUrl, tags);
   }` : "";
-    const trimCode = hasTrim ? `  await trimRuntimeCache(CACHE_NAME_RUNTIME);\n` : "";
-    const trimFunction = hasTrim ? `
-const MAX_CACHE_ENTRIES = ${maxCacheEntries ?? 0};
-const MAX_CACHE_AGE = ${maxCacheAge ?? 0};
+    const reactGlobalDefaults = {
+        staleTime: globalStaleTime,
+        refetchInterval: globalRefetchInterval,
+        refetchOnReconnect: globalRefetchOnReconnect,
+        refetchOnFocus: globalRefetchOnFocus,
+    };
+    const reactivePatterns = Object.entries(strategies)
+        .filter(([, entry]) => {
+        const resolved = typeof entry === "string" ? { strategy: entry } : entry;
+        return resolved.strategy === "reactive";
+    })
+        .map(([pattern, entry]) => {
+        const resolved = typeof entry === "string" ? { strategy: entry } : entry;
+        return {
+            pattern,
+            staleTime: resolved.staleTime ?? reactGlobalDefaults.staleTime,
+            refetchInterval: resolved.refetchInterval ?? reactGlobalDefaults.refetchInterval,
+            refetchOnReconnect: resolved.refetchOnReconnect ?? reactGlobalDefaults.refetchOnReconnect,
+            refetchOnFocus: resolved.refetchOnFocus ?? reactGlobalDefaults.refetchOnFocus,
+        };
+    });
+    const trimDecl = `const REFETCH_BATCH_SIZE = ${refetchBatchSize};
+const REFETCH_BATCH_DELAY_MS = ${refetchBatchDelayMs};
+const REFRESH_MAX_RETRIES = ${refetchMaxRetries};
+const REFRESH_RETRY_DELAY_MS = ${refetchRetryDelayMs};`;
+    const GLOB_CODE = "\n" +
+        "// --- Glob Pattern Matching ---\n" +
+        "// NOTE: This is an inline copy of the algorithm in shared/glob-matcher.ts.\n" +
+        "// Keep the two implementations in sync when making changes.\n" +
+        "\n" +
+        "function escapeGlobMeta(s) {\n" +
+        "  return s.replace(/[.+^${}()|[\\]\\\\]/g, \"\\\\$$&\");\n" +
+        "}\n" +
+        "\n" +
+        "function globPartRe(part) {\n" +
+        "  for (var o = \"\", i = 0; i < part.length; i++) {\n" +
+        "    var c = part[i];\n" +
+        "    if (c === \"*\") { o += \"[^/]*\"; }\n" +
+        "    else if (c === \"?\") { o += \"[^/]\"; }\n" +
+        "    else if (c === \"{\") {\n" +
+        "      var cl = part.indexOf(\"}\", i);\n" +
+        "      if (cl === -1) { o += \"\\\\\" + c; }\n" +
+        "      else {\n" +
+        "        o += \"(?:\" + part.slice(i + 1, cl).split(\",\").map(function(s) { return escapeGlobMeta(s.trim()); }).join(\"|\") + \")\";\n" +
+        "        i = cl;\n" +
+        "      }\n" +
+        "    } else { o += \"\\\\\" + c; }\n" +
+        "  }\n" +
+        "  return o;\n" +
+        "}\n" +
+        "\n" +
+        "function matchGlob(path, pattern) {\n" +
+        "  if (pattern.charAt(0) === \"!\") return !matchGlob(path, pattern.slice(1));\n" +
+        "  var parts = pattern.split(\"/\").filter(Boolean);\n" +
+        "  var pps = path.split(\"/\").filter(Boolean);\n" +
+        "  var pi = 0, ppi = 0;\n" +
+        "  while (pi < parts.length && ppi < pps.length) {\n" +
+        "    var part = parts[pi];\n" +
+        "    if (part === \"**\") {\n" +
+        "      if (pi === parts.length - 1) return true;\n" +
+        "      var nxt = parts[pi + 1];\n" +
+        "      var found = -1;\n" +
+        "      for (var j = ppi; j < pps.length; j++) {\n" +
+        "        if (nxt.indexOf(\"*\") > -1 || nxt.indexOf(\"?\") > -1 || nxt.indexOf(\"{\") > -1) {\n" +
+        "          if (new RegExp(\"^\" + globPartRe(nxt) + \"$\").test(pps[j])) { found = j; break; }\n" +
+        "        } else if (nxt === pps[j]) { found = j; break; }\n" +
+        "      }\n" +
+        "      if (found === -1) return false;\n" +
+        "      ppi = found;\n" +
+        "      pi++;\n" +
+        "      continue;\n" +
+        "    }\n" +
+        "    if (part.indexOf(\"*\") > -1 || part.indexOf(\"?\") > -1 || part.indexOf(\"{\") > -1) {\n" +
+        "      if (!new RegExp(\"^\" + globPartRe(part) + \"$\").test(pps[ppi])) return false;\n" +
+        "    } else if (part !== pps[ppi]) return false;\n" +
+        "    pi++;\n" +
+        "    ppi++;\n" +
+        "  }\n" +
+        "  return pi === parts.length && ppi === pps.length;\n" +
+        "}\n" +
+        "\n";
+    return `${trimDecl}
+// --- Batch Refresh Queue ---
+
+const _refreshQueue = new Map();
+let _refreshQueueProcessing = false;
+let _refreshQueuePromise = null;
+
+function queueRefresh(cacheKeyUrl, actualUrl${tagInvalidation ? ", tags" : ""}) {
+  // Use Map keyed by cacheKey for proper deduplication${tagInvalidation ? `
+  // Don't let a tagless (SWR/reactive) refresh override an invalidation-triggered entry with tags
+  if (_refreshQueue.has(cacheKeyUrl) && !tags) return;` : ""}
+  _refreshQueue.set(cacheKeyUrl, { cacheKey: cacheKeyUrl, actualUrl: actualUrl || cacheKeyUrl, retryCount: 0${tagInvalidation ? ", tags: tags || null" : ""} });
+  if (!_refreshQueuePromise) {
+    _refreshQueuePromise = _processRefreshQueue().finally(() => {
+      _refreshQueuePromise = null;
+      if (_refreshQueue.size > 0) queueRefresh();
+    });
+  }
+  return _refreshQueuePromise;
+}
 
-async function trimRuntimeCache(cacheName) {
-  const cache = await caches.open(cacheName);
+function resolveActualUrl(entry) {
+  const url = entry.actualUrl || entry.cacheKey;
+  if (url.includes("/__swc/")) {
+    // Virtual cache key — use the stored actual URL from tag registry
+    return url;
+  }
+  return url;
+}
 
-  if (MAX_CACHE_ENTRIES > 0) {
-    const keys = await cache.keys();
-    if (keys.length >= MAX_CACHE_ENTRIES) {
-      const toDelete = keys.slice(0, keys.length - MAX_CACHE_ENTRIES + 1);
-      await Promise.all(toDelete.map((key) => cache.delete(key)));
+async function _processRefreshQueue() {
+  while (_refreshQueue.size > 0) {
+    const batch = [];
+    for (const [cacheKey, entry] of _refreshQueue) {
+      if (batch.length >= REFETCH_BATCH_SIZE) break;
+      batch.push(entry);
+      _refreshQueue.delete(cacheKey);
     }
+    if (batch.length === 0) break;
+
+    const clients = await self.clients.matchAll();
+
+    await Promise.allSettled(batch.map(async (entry) => {
+      const fetchUrl = resolveActualUrl(entry);
+      try {
+        const response = await fetch(fetchUrl);
+        if (response.ok) {
+          const request = new Request(entry.cacheKey);
+          await storeRuntime(request, response);${tagInvalidation ? `
+          if (entry.tags && typeof cacheTagUrl !== "undefined") {
+            await cacheTagUrl(entry.cacheKey, fetchUrl, entry.tags);
+          }` : ""}
+          // Clean up stale version tracking on successful refresh
+          if (typeof staleVersions !== "undefined" && staleVersions.has(entry.cacheKey)) {
+            staleVersions.delete(entry.cacheKey);
+          }
+          for (const client of clients) {
+            client.postMessage({ type: "CACHE_UPDATED", url: fetchUrl });
+          }
+        }
+      } catch {
+        // Refresh failed — retry with exponential backoff
+        if (entry.retryCount < REFRESH_MAX_RETRIES) {
+          entry.retryCount++;
+          const delay = REFRESH_RETRY_DELAY_MS * Math.pow(2, entry.retryCount - 1);
+          _refreshQueue.set(entry.cacheKey, entry);
+          // Schedule re-processing after delay
+          setTimeout(() => {
+            if (!_refreshQueuePromise) {
+              _refreshQueuePromise = _processRefreshQueue().finally(() => {
+                _refreshQueuePromise = null;
+                if (_refreshQueue.size > 0) queueRefresh();
+              });
+            }
+          }, delay);
+        }
+      }
+    }));
+
+    if (_refreshQueue.size > 0 && REFETCH_BATCH_DELAY_MS > 0) {
+      await new Promise(r => setTimeout(r, REFETCH_BATCH_DELAY_MS));
+    }
+  }
+  _refreshQueueProcessing = false;
+}
+
+// --- Reactive Patterns (extracted for interval/focus/reconnect) ---
+
+const REACTIVE_PATTERNS = ${JSON.stringify(reactivePatterns)};
+
+function findReactiveConfig(url) {
+  const path = new URL(url).pathname;
+  for (const cfg of REACTIVE_PATTERNS) {
+    if (matchGlob(path, cfg.pattern)) return cfg;
   }
+  return null;
+}
+
+function shouldReactiveRefresh(cached, config) {
+  if (!config.staleTime && config.staleTime !== 0) return true;
+  if (config.staleTime === 0) return true;
+  return isStale(cached, config.staleTime);
+}
+
+// --- Reactive Interval Timers ---
 
-  if (MAX_CACHE_AGE > 0) {
+${(() => {
+        const patternsWithInterval = reactivePatterns.filter((p) => !!p.refetchInterval && p.refetchInterval > 0);
+        if (patternsWithInterval.length === 0)
+            return "";
+        return `// Start intervals for reactive patterns with refetchInterval
+(async () => {
+${patternsWithInterval.map(p => `  setInterval(async () => {
+    const cache = await caches.open(CACHE_NAME_RUNTIME);
     const keys = await cache.keys();
-    const now = Date.now();
     for (const request of keys) {
-      const response = await cache.match(request);
-      const dateHeader = response?.headers.get("date");
-      if (dateHeader) {
-        const age = now - new Date(dateHeader).getTime();
-        if (age > MAX_CACHE_AGE) {
-          await cache.delete(request);
-        }
+      const url = new URL(request.url);
+      if (url.pathname.startsWith("/__swc/")) continue;
+      if (!matchGlob(url.pathname, "${p.pattern}")) continue;
+      const config = findReactiveConfig(url.href);
+      if (!config) continue;
+      const cached = await cache.match(request);
+      if (cached && shouldReactiveRefresh(cached, config)) {
+        queueRefresh(request.url, url.href);
       }
     }
+  }, ${p.refetchInterval * 1000});`).join("\n")}
+})();
+`;
+    })()}
+async function handleOnline() {
+  const clients = await self.clients.matchAll();
+  if (clients.length === 0) return;
+
+  // Step 1: Retry stale version entries (failed refetches after invalidation)
+  if (typeof staleVersions !== "undefined") {
+    const staleUrls = [...staleVersions.keys()];
+    for (const url of staleUrls) {
+      queueRefresh(url, url);
+    }
+  }
+
+  // Step 2: Refresh reactive entries with refetchOnReconnect
+  const cache = await caches.open(CACHE_NAME_RUNTIME);
+  const keys = await cache.keys();
+  for (const request of keys) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/__swc/")) continue;
+    const config = findReactiveConfig(url.href);
+    if (!config || !config.refetchOnReconnect) continue;
+    const cached = await cache.match(request);
+    if (cached && shouldReactiveRefresh(cached, config)) {
+      queueRefresh(request.url, url.href);
+    }
   }
 }
-` : "";
-    return `${trimFunction}
+
+async function handleOnFocus() {
+  const cache = await caches.open(CACHE_NAME_RUNTIME);
+  const keys = await cache.keys();
+  for (const request of keys) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/__swc/")) continue;
+    const config = findReactiveConfig(url.href);
+    if (!config || !config.refetchOnFocus) continue;
+    const cached = await cache.match(request);
+    if (cached && shouldReactiveRefresh(cached, config)) {
+      queueRefresh(request.url, url.href);
+    }
+  }
+}
+
+// --- Cache Key ---
+
+function cacheKey(request) {
+  const key = request.headers.get("X-SW-Cache-Key");
+  if (key) return new URL("/__swc/" + key, self.location.origin).href;
+  const url = new URL(request.url);${normalizeCacheKey ? `
+  // Sort query params alphabetically for consistent cache keys
+  if (url.search) {
+    const params = new URLSearchParams(url.search);
+    params.sort();
+    url.search = params.toString();
+  }` : ""}${ignoreQueryParams && ignoreQueryParams.length > 0
+        ? `
+  // Strip configured query params from cache key
+  const ignore = ${JSON.stringify(ignoreQueryParams)};
+  if (url.search) {
+    const params = new URLSearchParams(url.search);
+    for (const key of ignore) params.delete(key);
+    url.search = params.toString();
+  }`
+        : ""}
+  return url.href;
+}
+
 // --- Cache Helpers ---
 
 async function fromPrecache(request) {
@@ -74,12 +323,19 @@ async function fromPrecache(request) {
 
 async function fromRuntime(request) {
   const cache = await caches.open(CACHE_NAME_RUNTIME);
-  return cache.match(new URL(request.url).href);
+  return cache.match(cacheKey(request));
 }
 
 async function storeRuntime(request, response) {
   const cache = await caches.open(CACHE_NAME_RUNTIME);
-  await cache.put(new URL(request.url).href, response.clone());
+  const headers = new Headers(response.headers);
+  headers.set("X-SW-Cached-At", String(Date.now()));
+  const cloned = new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+  await cache.put(cacheKey(request), cloned);
 }
 
 async function cacheResponse(request, response) {
@@ -105,42 +361,153 @@ function markFromCache(response) {
   });
 }
 
-// --- Strategy Selection ---
+function isStale(response, staleTimeSeconds) {
+  if (!staleTimeSeconds || staleTimeSeconds <= 0) return false;
+  const cachedAt = response.headers.get("X-SW-Cached-At");
+  if (!cachedAt) return false;
+  return Date.now() - Number(cachedAt) > staleTimeSeconds * 1000;
+}
+
+${GLOB_CODE}// --- Strategy Selection (3-tier config resolution) ---
 
 function resolveStrategyEntry(entry) {
   return typeof entry === "string" ? { strategy: entry } : entry;
 }
 
-function determineCacheStrategy(request, customStrategies, defaultStrategy) {
+function determineCacheStrategy(request, customStrategies, globalDefaults) {
   const override = request.headers.get("X-SW-Strategy");
-  if (override) return { strategy: override };
+  if (override) {
+    return { strategy: override };
+  }
   const path = new URL(request.url).pathname;
   for (const [pattern, entry] of Object.entries(customStrategies)) {
-    if (path.startsWith(pattern.replace("*", ""))) return resolveStrategyEntry(entry);
+    if (matchGlob(path, pattern)) {
+      const resolved = resolveStrategyEntry(entry);
+      return { strategy: resolved.strategy };
+    }
+  }
+  return { strategy: globalDefaults.defaultStrategy };
+}
+
+function determineCacheStrategyForUrl(url, customStrategies, globalDefaults) {
+  const path = new URL(url).pathname;
+  for (const [pattern, entry] of Object.entries(customStrategies)) {
+    if (matchGlob(path, pattern)) {
+      const resolved = resolveStrategyEntry(entry);
+      return { strategy: resolved.strategy };
+    }
   }
-  return { strategy: defaultStrategy };
+  return { strategy: globalDefaults.defaultStrategy };
 }
 
 function applyStrategy(event, request, config) {
-  const { strategy, maxCacheEntries, maxCacheAge } = config;
-  if (strategy === "stale-while-revalidate") {
-    event.respondWith(staleWhileRevalidate(event, request, maxCacheEntries, maxCacheAge));
+  const { strategy } = config;
+  if (strategy === "reactive") {
+    const reactiveCfg = findReactiveConfig(new URL(request.url).href);
+    event.respondWith(reactiveStrategy(event, request, reactiveCfg?.staleTime));
+  } else if (strategy === "stale-while-revalidate") {
+    event.respondWith(staleWhileRevalidate(event, request));
   } else if (strategy === "network-first") {
-    event.respondWith(networkFirst(event, request, maxCacheEntries, maxCacheAge));
+    event.respondWith(networkFirst(event, request));
   } else if (strategy === "cache-only") {
-    event.respondWith(cacheOnly(event, request, maxCacheEntries, maxCacheAge));
+    event.respondWith(cacheOnly(event, request));
   } else if (strategy === "network-only") {
     event.respondWith(networkOnly(event, request));
   } else {
-    event.respondWith(cacheFirst(event, request, maxCacheEntries, maxCacheAge));
+    event.respondWith(cacheFirst(event, request));
+  }
+}
+
+${mutationQueueEnabled ? `// --- Mutation Queue IDB Helpers ---
+
+const MUTATION_DB_NAME = "swoff-queue";
+const MUTATION_STORE_NAME = "mutations";
+
+function openMutationQueueDB() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(MUTATION_DB_NAME, 1);
+    request.onupgradeneeded = (e) => {
+      const db = e.target.result;
+      if (!db.objectStoreNames.contains(MUTATION_STORE_NAME)) {
+        const store = db.createObjectStore(MUTATION_STORE_NAME, { keyPath: "id" });
+        store.createIndex("by-timestamp", "timestamp");
+      }
+    };
+    request.onsuccess = (e) => resolve(e.target.result);
+    request.onerror = (e) => reject(e.target.error);
+  });
+}
+
+async function storeMutationInSW(request) {
+  let body, bodyType;
+  try {
+    body = await request.clone().json();
+    bodyType = "json";
+  } catch {
+    body = await request.clone().text();
+    bodyType = "text";
+  }
+
+  const tagsHeader = request.headers.get("X-SW-Invalidate-Tags");
+  const tags = tagsHeader ? tagsHeader.split(",").map(function(t) { return t.trim(); }) : [];
+
+  const db = await openMutationQueueDB();
+  const tx = db.transaction(MUTATION_STORE_NAME, "readwrite");
+  tx.objectStore(MUTATION_STORE_NAME).add({
+    id: crypto.randomUUID(),
+    method: request.method,
+    url: new URL(request.url).href,
+    body,
+    bodyType,
+    headers: {},
+    timestamp: Date.now(),
+    retryCount: 0,
+    nextRetryAt: 0,
+    tags,
+  });
+  await new Promise(function(resolve, reject) {
+    tx.oncomplete = function() { resolve(); };
+    tx.onerror = function() { reject(tx.error); };
+  });
+}
+
+async function handleMutation(event) {
+  const request = event.request;
+  if (request.headers.get("X-SW-No-Queue") === "true") {
+    return fetch(request.clone());
+  }
+  try {
+    return await fetch(request.clone());
+  } catch {
+    await storeMutationInSW(request);
+    // Notify open clients that a mutation was stored so they can try to process
+    const clients = await self.clients.matchAll();
+    clients.forEach(function(client) {
+      client.postMessage({ type: "MUTATION_STORED" });
+    });
+    const queuedBody = JSON.stringify({ queued: true });
+    return new Response(queuedBody, {
+      status: 202,
+      statusText: "Accepted",
+      headers: { "Content-Type": "application/json", "X-SW-Mutation-Queued": "true" },
+    });
   }
 }
 
-self.addEventListener("fetch", (event) => {
-  const { request } = event;
-  if (request.method !== "GET" && request.method !== "HEAD") return;
+` : ""}self.addEventListener("fetch", (event) => {
+  const { request } = event;${mutationQueueEnabled ? `
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    if (request.headers.get("X-SW-Cache-Strategy") === "mutation") {
+      event.respondWith(handleMutation(event));
+      return;
+    }
+    if (!request.headers.get("X-SW-Cache-Key")) return;
+  }` : `
+  if (request.method !== "GET" && request.method !== "HEAD") {
+    if (!request.headers.get("X-SW-Cache-Key")) return;
+  }`}
   ${cacheStrategy === "explicit-only" ? `if (!request.headers.get("X-SW-Cache-Strategy")) return;` : ""}
-  applyStrategy(event, request, determineCacheStrategy(event.request, ${JSON.stringify(strategies)}, "${defaultStrategy}"));
+  applyStrategy(event, request, determineCacheStrategy(event.request, ${JSON.stringify(strategies)}, { defaultStrategy: "${defaultStrategy}" }));
 });
 
 // --- Strategies ---
@@ -155,43 +522,7 @@ async function fetchWithPreload(event, request) {
 }
 ` : ""}const _fetch = ${navigationPreload ? "fetchWithPreload" : `(event, request) => fetch(request)`};
 
-const GLOBAL_MAX_ENTRIES = ${maxCacheEntries ?? 0};
-const GLOBAL_MAX_AGE = ${maxCacheAge ?? 0};
-
-${hasTrim ? `
-async function trimRuntimeCache(cacheName, maxEntries, maxAge) {
-  const _maxEntries = maxEntries ?? GLOBAL_MAX_ENTRIES;
-  const _maxAge = maxAge ?? GLOBAL_MAX_AGE;
-  const cache = await caches.open(cacheName);
-
-  if (_maxEntries > 0) {
-    const keys = await cache.keys();
-    if (keys.length >= _maxEntries) {
-      const toDelete = keys.slice(0, keys.length - _maxEntries + 1);
-      await Promise.all(toDelete.map((key) => cache.delete(key)));
-    }
-  }
-
-  if (_maxAge > 0) {
-    const keys = await cache.keys();
-    const now = Date.now();
-    for (const request of keys) {
-      const response = await cache.match(request);
-      const dateHeader = response?.headers.get("date");
-      if (dateHeader) {
-        const age = now - new Date(dateHeader).getTime();
-        if (age > _maxAge) {
-          await cache.delete(request);
-        }
-      }
-    }
-  }
-}
-` : ""}function _trim(cacheName, maxEntries, maxAge) {
-${hasTrim ? `  trimRuntimeCache(cacheName, maxEntries, maxAge);` : ""}
-}
-
-async function cacheFirst(event, request, maxEntries, maxAge) {
+async function cacheFirst(event, request) {
   const cached = await fromRuntime(request);
   if (cached) {${staleVersionCode}
     return markFromCache(cached);
@@ -205,75 +536,84 @@ async function cacheFirst(event, request, maxEntries, maxAge) {
 
   const response = await _fetch(event, request);
   if (response.ok) {
-    event.waitUntil(
-      (async () => {
-        await cacheResponse(request, response);
-        _trim(CACHE_NAME_RUNTIME, maxEntries, maxAge);
-      })(),
-    );
+    const responseToCache = response.clone();
+    event.waitUntil(cacheResponse(request, responseToCache));
   }
   return response;
 }
 
-async function networkFirst(event, request, maxEntries, maxAge) {
+async function networkFirst(event, request) {
   try {
     const response = await _fetch(event, request);
     if (response.ok) {
-      event.waitUntil(
-        (async () => {
-          await cacheResponse(request, response);
-          _trim(CACHE_NAME_RUNTIME, maxEntries, maxAge);
-        })(),
-      );
+      const responseToCache = response.clone();
+      event.waitUntil(cacheResponse(request, responseToCache));
     }
     return response;
   } catch {
     const cached = await fromRuntime(request);
-    if (cached) return cached;
+    if (cached) {
+      return markFromCache(cached);
+    }
 
     const precached = await fromPrecache(request);
-    if (precached) return precached;
+    if (precached) return markFromCache(precached);
 
     const fallback = await fromSpaFallback(request);
     if (fallback) return fallback;
 
-    throw new Error("Request failed and no cached response available");
+    throw new Error("Network request failed and no cached response available");
   }
 }
 
-async function staleWhileRevalidate(event, request, maxEntries, maxAge) {
+async function staleWhileRevalidate(event, request) {
   const cached = await fromRuntime(request);
   if (cached) {
-    event.waitUntil(refreshCache(request));
+    event.waitUntil(queueRefresh(cacheKey(request), new URL(request.url).href));
     return markFromCache(cached);
   }
 
   const precached = await fromPrecache(request);
   if (precached) {
-    event.waitUntil(refreshCache(request));
+    event.waitUntil(queueRefresh(cacheKey(request), new URL(request.url).href));
     return markFromCache(precached);
   }
 
   const response = await _fetch(event, request);
   if (response.ok) {
-    await cacheResponse(request, response);
-    _trim(CACHE_NAME_RUNTIME, maxEntries, maxAge);
+    const responseToCache = response.clone();
+    await cacheResponse(request, responseToCache);
   }
   return response;
 }
 
-async function refreshCache(request) {
-  try {
-    const response = await fetch(request);
-    if (response.ok) {
-      await storeRuntime(request, response);
+async function reactiveStrategy(event, request, staleTime) {
+  const cached = await fromRuntime(request);
+  // Per-request staleTime header overrides config-level staleTime
+  const headerStale = request.headers.get("X-SW-Stale-Time");
+  const effectiveStaleTime = headerStale !== null ? Number(headerStale) : staleTime;
+  if (cached) {${staleVersionCode}
+    if (shouldReactiveRefresh(cached, { staleTime: effectiveStaleTime })) {
+      event.waitUntil(queueRefresh(cacheKey(request), new URL(request.url).href));
     }
-  } catch {
-    // Background refresh failed - stale cache remains usable
+    return markFromCache(cached);
+  }
+
+  const precached = await fromPrecache(request);
+  if (precached) return markFromCache(precached);
+
+  const fallback = await fromSpaFallback(request);
+  if (fallback) return fallback;
+
+  const response = await _fetch(event, request);
+  if (response.ok) {
+    const responseToCache = response.clone();
+    await cacheResponse(request, responseToCache);
   }
+  return response;
 }
 
-async function cacheOnly(event, request, maxEntries, maxAge) {
+async function cacheOnly(event, request) {
   const cached = await fromRuntime(request);
   if (cached) {${staleVersionCode}
     return markFromCache(cached);