@ultimat3/pwa 1.0.0

package/src/offline-fallback.ts

@@ -0,0 +1,76 @@
+/**
+ * The offline fallback is mandatory. A PWA whose first offline navigation shows the
+ * browser's dinosaur is not offline-capable — it is a website with a manifest. The type
+ * requires it and `requireOfflineFallback` fails the build if it is missing.
+ */
+
+import { PwaNoOfflineFallbackError } from './errors';
+
+export interface OfflineConfig {
+  /** Route path of the offline document, e.g. `/offline`. Required. */
+  readonly fallback: string;
+  /** Optional per-content-type fallbacks. */
+  readonly image?: string;
+  readonly font?: string;
+  /** Requests that must never be answered from a cache (auth, payments). */
+  readonly neverCache?: readonly string[];
+}
+
+export interface OfflineFallback {
+  readonly document: string;
+  readonly image: string | null;
+  readonly font: string | null;
+  readonly neverCache: readonly string[];
+}
+
+const FIX = 'create app/offline.tsx and set offline.fallback';
+
+/**
+ * Build-time gate, called by `generateServiceWorker` and by `x doctor`. The fix line is
+ * the literal two-step edit, not a doc link.
+ */
+export function requireOfflineFallback(
+  config: Partial<OfflineConfig> | undefined | null,
+): OfflineFallback {
+  if (config === undefined || config === null) {
+    throw new PwaNoOfflineFallbackError(
+      'app.config.ts has no `offline` block, so an offline navigation would show the ' +
+        "browser's error page",
+      FIX,
+    );
+  }
+  const fallback = config.fallback;
+  if (fallback === undefined || fallback.trim() === '') {
+    throw new PwaNoOfflineFallbackError(
+      'app.config.ts has an `offline` block with no `fallback` route',
+      FIX,
+    );
+  }
+  if (!fallback.startsWith('/')) {
+    throw new PwaNoOfflineFallbackError(
+      `offline.fallback is ${JSON.stringify(fallback)}, which is not an absolute route path`,
+      `set offline.fallback to '/${fallback.replace(/^\/+/, '')}'`,
+    );
+  }
+
+  return {
+    document: fallback,
+    image: config.image ?? null,
+    font: config.font ?? null,
+    neverCache: config.neverCache ?? [],
+  };
+}
+
+/** Emitted into `sw.js`: what to serve when a navigation cannot be answered. */
+export function offlineFallbackSource(fallback: OfflineFallback): string {
+  const image = fallback.image === null ? 'null' : JSON.stringify(fallback.image);
+  return `
+const OFFLINE_DOC=${JSON.stringify(fallback.document)};
+const OFFLINE_IMAGE=${image};
+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(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/precache.ts

@@ -0,0 +1,137 @@
+/**
+ * The precache manifest, built from the route table. Entries are URL + revision, so a
+ * byte-identical asset across deploys is not re-downloaded; the revision is the content
+ * hash, never the build id, or every deploy would re-fetch everything.
+ */
+
+import type { PwaRoute } from './strategies';
+
+export interface PrecacheAsset {
+  readonly url: string;
+  /** Content hash. Same bytes → same revision → no re-download. */
+  readonly revision: string;
+  readonly bytes: number;
+  /** Critical assets (the shell CSS, the LCP font) are precached even if large. */
+  readonly critical?: boolean;
+}
+
+export interface PrecacheEntry {
+  readonly url: string;
+  readonly revision: string;
+  readonly bytes: number;
+  readonly reason: 'shell' | 'route' | 'route-data' | 'asset' | 'fallback';
+}
+
+export interface PrecacheManifest {
+  readonly buildId: string;
+  readonly entries: readonly PrecacheEntry[];
+  readonly totalBytes: number;
+  readonly warnings: readonly string[];
+}
+
+export interface PrecacheInput {
+  readonly buildId: string;
+  readonly routes: readonly PwaRoute[];
+  readonly assets?: readonly PrecacheAsset[];
+  /** The app shell URL, precached for every `spa` route. */
+  readonly shellUrl?: string;
+  readonly shellRevision?: string;
+  readonly shellBytes?: number;
+  /** The mandatory offline document. */
+  readonly offlineFallbackUrl?: string;
+  readonly offlineFallbackRevision?: string;
+  /** Warn past this total. Default 5 MB: past that, install stalls on a bad connection. */
+  readonly warnBytes?: number;
+}
+
+export const DEFAULT_PRECACHE_WARN_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Deterministic: entries are sorted by URL and every field is derived from the input, so
+ * two builds of the same commit emit byte-identical manifests.
+ */
+export function buildPrecacheManifest(input: PrecacheInput): PrecacheManifest {
+  const entries = new Map<string, PrecacheEntry>();
+  const add = (entry: PrecacheEntry): void => {
+    if (!entries.has(entry.url)) entries.set(entry.url, entry);
+  };
+
+  if (input.shellUrl !== undefined) {
+    add({
+      url: input.shellUrl,
+      revision: input.shellRevision ?? input.buildId,
+      bytes: input.shellBytes ?? 0,
+      reason: 'shell',
+    });
+  }
+
+  if (input.offlineFallbackUrl !== undefined) {
+    add({
+      url: input.offlineFallbackUrl,
+      revision: input.offlineFallbackRevision ?? input.buildId,
+      bytes: 0,
+      reason: 'fallback',
+    });
+  }
+
+  for (const route of input.routes) {
+    if (route.offline !== 'precache') continue;
+    // A dynamic route has no single URL to precache; its instances are runtime-cached.
+    if (route.dynamic === true) continue;
+    add({
+      url: route.path,
+      revision: route.revision ?? input.buildId,
+      bytes: route.bytes ?? 0,
+      reason: 'route',
+    });
+    if (route.dataUrl !== undefined) {
+      add({
+        url: route.dataUrl,
+        revision: route.revision ?? input.buildId,
+        bytes: 0,
+        reason: 'route-data',
+      });
+    }
+  }
+
+  for (const asset of input.assets ?? []) {
+    add({ url: asset.url, revision: asset.revision, bytes: asset.bytes, reason: 'asset' });
+  }
+
+  const sorted = [...entries.values()].sort((a, b) => a.url.localeCompare(b.url));
+  const totalBytes = sorted.reduce((sum, entry) => sum + entry.bytes, 0);
+  const warnBytes = input.warnBytes ?? DEFAULT_PRECACHE_WARN_BYTES;
+
+  const warnings: string[] = [];
+  if (totalBytes > warnBytes) {
+    warnings.push(
+      `precache is ${formatBytes(totalBytes)} (over ${formatBytes(warnBytes)}): install ` +
+        "will stall on a slow connection — move rarely-visited routes to offline: 'runtime'",
+    );
+  }
+  const dynamicPrecache = input.routes.filter(
+    (r) => r.offline === 'precache' && r.dynamic === true,
+  );
+  for (const route of dynamicPrecache) {
+    warnings.push(
+      `${route.path} is dynamic and cannot be precached as one URL; its instances are ` +
+        'runtime-cached instead',
+    );
+  }
+
+  return { buildId: input.buildId, entries: sorted, totalBytes, warnings };
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}b`;
+  if (bytes < 1024 * 1024) return `${Math.round((bytes / 1024) * 10) / 10}kb`;
+  return `${Math.round((bytes / (1024 * 1024)) * 10) / 10}mb`;
+}
+
+/** The manifest as it is embedded in `sw.js`; stable key order for determinism. */
+export function serializePrecacheManifest(manifest: PrecacheManifest): string {
+  const rows = manifest.entries.map(
+    (entry) => `{"url":${JSON.stringify(entry.url)},"revision":${JSON.stringify(entry.revision)}}`,
+  );
+  return `[${rows.join(',')}]`;
+}

package/src/push.ts

@@ -0,0 +1,171 @@
+/**
+ * Web Push: subscription lifecycle, VAPID config, typed payloads, and a per-locale body.
+ *
+ * The locale is stored ON the subscription, not read from the sending request: a push is
+ * composed on a server with no request context, and a notification in the wrong language
+ * is a real bug that users report as "the app is broken".
+ */
+
+export interface VapidConfig {
+  readonly publicKey: string;
+  /** `mailto:` or an https URL — required by the spec, checked by every push service. */
+  readonly subject: string;
+}
+
+export interface PushSubscriptionKeys {
+  readonly p256dh: string;
+  readonly auth: string;
+}
+
+export interface PushSubscriptionRecord {
+  readonly endpoint: string;
+  readonly keys: PushSubscriptionKeys;
+  /** BCP-47, captured at subscribe time. */
+  readonly locale: string;
+  readonly timeZone: string;
+  readonly actorId: string | null;
+  readonly createdAt: number;
+  readonly expirationTime: number | null;
+}
+
+export type SubscriptionState = 'active' | 'expired' | 'gone';
+
+/** A 404/410 from the push service means the subscription is dead — delete it, don't retry. */
+export function subscriptionState(
+  record: PushSubscriptionRecord,
+  lastStatus: number | null,
+  now = Date.now(),
+): SubscriptionState {
+  if (lastStatus === 404 || lastStatus === 410) return 'gone';
+  if (record.expirationTime !== null && record.expirationTime <= now) return 'expired';
+  return 'active';
+}
+
+/** Translation function from `@ultimat3/i18n`, bound to the subscriber's locale. */
+export type Translate = (key: string, params?: Readonly<Record<string, string | number>>) => string;
+
+export interface PushPayload {
+  /** i18n catalog keys, never literal strings. */
+  readonly titleKey: string;
+  readonly bodyKey: string;
+  readonly params?: Readonly<Record<string, string | number>>;
+  /** Deep link opened by `notificationclick`. */
+  readonly url: string;
+  /** Collapse key: a newer notification with the same tag replaces the older one. */
+  readonly tag?: string;
+  readonly icon?: string;
+  readonly badge?: string;
+  readonly renotify?: boolean;
+  readonly requireInteraction?: boolean;
+  readonly actions?: readonly { readonly action: string; readonly titleKey: string }[];
+}
+
+export interface RenderedNotification {
+  readonly title: string;
+  readonly body: string;
+  readonly url: string;
+  readonly tag: string | null;
+  readonly icon: string | null;
+  readonly badge: string | null;
+  readonly renotify: boolean;
+  readonly requireInteraction: boolean;
+  readonly actions: readonly { readonly action: string; readonly title: string }[];
+  readonly locale: string;
+  /** Missing-key markers (`⟦key⟧`) surfaced instead of being shipped to a user. */
+  readonly warnings: readonly string[];
+}
+
+const MISSING_MARKER = '⟦';
+
+export function renderPushPayload(
+  payload: PushPayload,
+  locale: string,
+  translate: Translate,
+): RenderedNotification {
+  const warnings: string[] = [];
+  const render = (key: string): string => {
+    const value = translate(key, payload.params);
+    if (value.startsWith(MISSING_MARKER)) {
+      warnings.push(`missing ${locale} translation for ${key}`);
+    }
+    return value;
+  };
+
+  return {
+    title: render(payload.titleKey),
+    body: render(payload.bodyKey),
+    url: payload.url,
+    tag: payload.tag ?? null,
+    icon: payload.icon ?? null,
+    badge: payload.badge ?? null,
+    renotify: payload.renotify ?? false,
+    requireInteraction: payload.requireInteraction ?? false,
+    actions: (payload.actions ?? []).map((action) => ({
+      action: action.action,
+      title: render(action.titleKey),
+    })),
+    locale,
+    warnings,
+  };
+}
+
+/** The wire body the SW receives. Rendered server-side so the SW ships no catalog. */
+export function serializePushMessage(notification: RenderedNotification): string {
+  return JSON.stringify({
+    title: notification.title,
+    body: notification.body,
+    url: notification.url,
+    tag: notification.tag,
+    icon: notification.icon,
+    badge: notification.badge,
+    renotify: notification.renotify,
+    requireInteraction: notification.requireInteraction,
+    actions: notification.actions,
+    lang: notification.locale,
+  });
+}
+
+export interface PushSourceOptions {
+  readonly defaultIcon?: string;
+  readonly defaultBadge?: string;
+  /** Emit `navigator.setAppBadge` calls — gated by the `badging` capability. */
+  readonly badging?: boolean;
+}
+
+/** Emitted into `sw.js` only when the `push` capability is on. */
+export function pushSource(options: PushSourceOptions = {}): string {
+  const icon = JSON.stringify(options.defaultIcon ?? '/icons/icon-192.png');
+  const badge = JSON.stringify(options.defaultBadge ?? '/icons/icon-mono-512.png');
+  const badging = options.badging === true;
+
+  return `
+self.addEventListener('push',(event)=>{
+  const d=event.data?event.data.json():{};
+  const opts={body:d.body||'',icon:d.icon||${icon},badge:d.badge||${badge},
+    tag:d.tag||undefined,renotify:!!d.renotify,requireInteraction:!!d.requireInteraction,
+    lang:d.lang||undefined,actions:d.actions||[],data:{url:d.url||'/'}};
+  event.waitUntil(self.registration.showNotification(d.title||'',opts)${
+    badging ? '.then(()=>navigator.setAppBadge&&navigator.setAppBadge())' : ''
+  });
+});
+self.addEventListener('notificationclick',(event)=>{
+  event.notification.close();
+  const url=(event.notification.data&&event.notification.data.url)||'/';
+  event.waitUntil(clients.matchAll({type:'window',includeUncontrolled:true}).then((ws)=>{
+    for(const w of ws){if(w.url===url&&'focus'in w)return w.focus()}
+    return clients.openWindow(url)
+  }));
+});`.trim();
+}
+
+/** Client-side subscribe. The locale travels with the subscription, by design. */
+export function subscribeSource(vapid: VapidConfig): string {
+  return `
+export async function subscribePush(registration,locale,timeZone){
+  const existing=await registration.pushManager.getSubscription();
+  if(existing)return {subscription:existing.toJSON(),locale,timeZone};
+  const sub=await registration.pushManager.subscribe({userVisibleOnly:true,
+    applicationServerKey:${JSON.stringify(vapid.publicKey)}});
+  return {subscription:sub.toJSON(),locale,timeZone}
+}`.trim();
+}

package/src/service-worker.ts

@@ -0,0 +1,267 @@
+/**
+ * `sw.js` is emitted from the route table. You never open it — that is this package's
+ * whole thesis. Hand-written service workers rot because they encode routing decisions a
+ * second time, and the second copy is the one nobody updates.
+ *
+ * Output is deterministic for identical input: no timestamps, no randomness, sorted
+ * everything, so two builds of the same commit produce byte-identical bytes and the SW
+ * update check does not fire on a no-op deploy.
+ */
+
+import type { BackgroundSyncOptions } from './background-sync';
+import { backgroundSyncSource } from './background-sync';
+import type { CapabilityFlags, ResolvedCapabilities } from './capabilities';
+import { isEnabled, resolveCapabilities } from './capabilities';
+import { SwScopeInvalidError } from './errors';
+import type { OfflineConfig } from './offline-fallback';
+import { offlineFallbackSource, requireOfflineFallback } from './offline-fallback';
+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 {
+  APP_UPDATE_AVAILABLE,
+  assertBuildId,
+  BUILD_ID_HEADER,
+  cacheNamespace,
+} from './version-skew';
+
+export interface ServiceWorkerConfig {
+  readonly scope?: string;
+  /** Where `sw.js` is served from. Must be at or above `scope`. */
+  readonly swPath?: string;
+  readonly offline: Partial<OfflineConfig>;
+  readonly capabilities?: CapabilityFlags;
+  readonly assets?: readonly PrecacheAsset[];
+  readonly shellUrl?: string;
+  readonly shellRevision?: string;
+  readonly shellBytes?: number;
+  readonly vapid?: VapidConfig;
+  readonly backgroundSync?: BackgroundSyncOptions;
+  /** 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;
+  readonly rules: readonly RouteRule[];
+  readonly capabilities: ResolvedCapabilities;
+  readonly warnings: readonly string[];
+}
+
+/**
+ * A SW served from `/js/sw.js` can only control `/js/`. This is the single most common
+ * "why is my PWA not working" and it is checkable at build time.
+ */
+export function assertScope(swPath: string, scope: string): void {
+  const directory = swPath.slice(0, swPath.lastIndexOf('/') + 1);
+  if (!scope.startsWith(directory)) {
+    throw new SwScopeInvalidError(
+      `sw.js is served from ${swPath}, which can only control ${directory}, but the ` +
+        `configured scope is ${scope}`,
+      `serve the service worker from ${scope}sw.js, or set pwa.scope to '${directory}'`,
+    );
+  }
+}
+
+export function routeRules(routes: readonly PwaRoute[]): readonly RouteRule[] {
+  return [...routes]
+    .filter((route) => route.surface !== 'api')
+    .sort((a, b) => a.path.localeCompare(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[],
+  config: ServiceWorkerConfig,
+  buildId: string,
+): ServiceWorkerOutput {
+  assertBuildId(buildId);
+  const scope = config.scope ?? '/';
+  assertScope(config.swPath ?? `${scope}sw.js`, scope);
+
+  const fallback = requireOfflineFallback(config.offline);
+  const capabilities = resolveCapabilities(config.capabilities);
+  const rules = routeRules(routes);
+
+  const precache = buildPrecacheManifest({
+    buildId,
+    routes,
+    offlineFallbackUrl: fallback.document,
+    ...(config.assets === undefined ? {} : { assets: config.assets }),
+    ...(config.shellUrl === undefined ? {} : { shellUrl: config.shellUrl }),
+    ...(config.shellRevision === undefined ? {} : { shellRevision: config.shellRevision }),
+    ...(config.shellBytes === undefined ? {} : { shellBytes: config.shellBytes }),
+    ...(config.precacheWarnBytes === undefined ? {} : { warnBytes: config.precacheWarnBytes }),
+  });
+
+  const usedStrategies = [...new Set(rules.map((rule) => rule.strategy))].sort();
+  const retained = [...new Set([buildId, ...(config.retainBuildIds ?? [])])].sort();
+
+  const blocks: string[] = [
+    header(buildId),
+    constants(buildId, scope, retained, fallback.neverCache),
+    `const PRECACHE_MANIFEST=${serializePrecacheManifest(precache)};`,
+    `const ROUTE_RULES=${serializeRules(rules)};`,
+    usedStrategies.map((strategy) => STRATEGY_SOURCE[strategy]).join('\n'),
+    offlineFallbackSource(fallback),
+    INSTALL_BLOCK,
+    activateBlock(),
+    fetchBlock(),
+    messageBlock(),
+  ];
+
+  if (isEnabled(capabilities, 'push') && config.vapid !== undefined) {
+    blocks.push(pushSource({ badging: isEnabled(capabilities, 'badging') }));
+  }
+  if (isEnabled(capabilities, 'backgroundSync')) {
+    blocks.push(backgroundSyncSource(config.backgroundSync ?? {}));
+  }
+
+  return {
+    source: `${blocks.join('\n\n')}\n`,
+    precache,
+    rules,
+    capabilities,
+    warnings: precache.warnings,
+  };
+}
+
+function header(buildId: string): string {
+  return `// GENERATED by @ultimat3/pwa from the route table — do not edit.
+// build: ${buildId}   regenerate: x build`;
+}
+
+function constants(
+  buildId: string,
+  scope: string,
+  retained: readonly string[],
+  neverCache: readonly string[],
+): string {
+  return `
+const BUILD_ID=${JSON.stringify(buildId)};
+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 RETAINED=${JSON.stringify(retainedCaches(retained))};
+const NEVER_CACHE=${JSON.stringify(neverCache)};
+const BUILD_HEADER=${JSON.stringify(BUILD_ID_HEADER)};`.trim();
+}
+
+function retainedCaches(buildIds: readonly string[]): readonly string[] {
+  return buildIds.flatMap((id) => [
+    cacheNamespace(id, 'precache'),
+    cacheNamespace(id, 'runtime'),
+    cacheNamespace(id, 'pages'),
+  ]);
+}
+
+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)}}`,
+  );
+  return `[${rows.join(',')}]`;
+}
+
+const INSTALL_BLOCK = `
+self.addEventListener('install',(event)=>{
+  event.waitUntil((async()=>{
+    const cache=await caches.open(PRECACHE);
+    // Revision is a content hash: unchanged assets are not re-downloaded across deploys.
+    await cache.addAll(PRECACHE_MANIFEST.map((e)=>new Request(e.url+'?v='+e.revision,{cache:'reload'})));
+  })());
+});`.trim();
+
+function activateBlock(): string {
+  return `
+self.addEventListener('activate',(event)=>{
+  event.waitUntil((async()=>{
+    // Retain the last N deploys so a tab open across a release still resolves its chunks.
+    const names=await caches.keys();
+    await Promise.all(names.filter((n)=>n.startsWith('x-')&&RETAINED.indexOf(n)===-1)
+      .map((n)=>caches.delete(n)));
+    await self.clients.claim();
+    const cs=await self.clients.matchAll({type:'window'});
+    for(const c of cs)c.postMessage({type:${JSON.stringify(APP_UPDATE_AVAILABLE)},to:BUILD_ID});
+  })());
+});`.trim();
+}
+
+function fetchBlock(): 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}
+const STRATEGIES={cacheFirst:typeof cacheFirst==='function'?cacheFirst:null,
+  networkFirst:typeof networkFirst==='function'?networkFirst:null,
+  staleWhileRevalidate:typeof staleWhileRevalidate==='function'?staleWhileRevalidate:null,
+  networkOnly:typeof networkOnly==='function'?networkOnly:null};
+self.addEventListener('fetch',(event)=>{
+  const req=event.request;
+  if(req.method!=='GET')return;
+  const url=new URL(req.url);
+  if(url.origin!==self.location.origin)return;
+  if(NEVER_CACHE.some((p)=>url.pathname.startsWith(p)))return;
+  const rule=ruleFor(url);
+  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)});
+  event.respondWith(fn(tagged,cacheName(rule.c),()=>offlineFallback(req)));
+});
+function withBuild(headers){
+  const h=new Headers(headers);h.set(BUILD_HEADER,BUILD_ID);return h
+}`.trim();
+}
+
+function messageBlock(): string {
+  return `
+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});
+});`.trim();
+}