@pwa-platform/sw-runtime 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/worker/admit.js

@@ -0,0 +1,99 @@
+// Runtime-cache response admission check, as a pure function: no Cache API, no fetch, no Workbox. It only decides
+// whether a network response may be written to the runtime cache; the caller still returns the response to the page
+// either way (spec "响应准入").
+const ALLOWED_VARY_TOKENS = new Set(["accept", "accept-encoding"]);
+/** True only if `response` may be written to the runtime cache. Never consumes `response` itself. */
+export async function admitRuntimeResponse(response, options) {
+    if (response.type !== "basic" || response.status !== 200 || response.redirected)
+        return false;
+    if (!admittedMediaType(response.headers.get("content-type"), options.resourceClass))
+        return false;
+    if (!admittedCacheControl(response.headers.get("cache-control"), options.strategy))
+        return false;
+    if (!admittedVary(response.headers.get("vary")))
+        return false;
+    // `Set-Cookie` is intentionally not checked: the Fetch spec makes it a forbidden response-header name on a basic
+    // response, so a worker can never read it (see spec.public-read-cache "响应准入").
+    return admittedSize(response, options.maxEntryBytes);
+}
+function admittedMediaType(contentType, resourceClass) {
+    if (contentType === null)
+        return false;
+    const mediaType = contentType.split(";", 1)[0].trim().toLowerCase();
+    if (resourceClass === "navigation-public-dynamic")
+        return mediaType === "text/html";
+    return mediaType === "application/json" || /^application\/[^/]+\+json$/.test(mediaType);
+}
+/** Each directive token, with its value when the token carries one (`max-age=0` and `max-age="0"` both parse to `0`). */
+function directives(headerValue) {
+    const found = new Map();
+    for (const item of headerValue.split(",")) {
+        const [rawToken, ...rawValue] = item.split("=");
+        const token = rawToken?.trim().toLowerCase();
+        if (token === undefined || token.length === 0)
+            continue;
+        const value = rawValue.length === 0 ? undefined : rawValue.join("=").trim().replace(/^"|"$/g, "");
+        found.set(token, value);
+    }
+    return found;
+}
+/** True when `directive` is present with a numeric value of exactly `0` (e.g. `max-age=0`, `max-age="0"`). */
+function isZero(found, directive) {
+    const value = found.get(directive);
+    return value !== undefined && Number(value) === 0;
+}
+function admittedCacheControl(cacheControl, strategy) {
+    if (cacheControl === null)
+        return true;
+    const found = directives(cacheControl);
+    if (found.has("no-store") || found.has("private"))
+        return false;
+    if (strategy === "stale-while-revalidate") {
+        // SWR hands out the cached entry without revalidating; a response that demands revalidation, or one that is
+        // already stale on arrival, must not be written (spec "响应准入", ADR-0035 T13 评审后收紧). network-first is
+        // unaffected: it always tries the network first and only falls back to the cache on failure.
+        if (found.has("no-cache") || found.has("must-revalidate"))
+            return false;
+        if (isZero(found, "max-age") || isZero(found, "s-maxage"))
+            return false;
+    }
+    return true;
+}
+function admittedVary(vary) {
+    if (vary === null)
+        return true;
+    const tokens = vary
+        .split(",")
+        .map((token) => token.trim().toLowerCase())
+        .filter((token) => token.length > 0);
+    return tokens.every((token) => ALLOWED_VARY_TOKENS.has(token));
+}
+async function admittedSize(response, maxEntryBytes) {
+    const contentLength = response.headers.get("content-length");
+    if (contentLength !== null) {
+        const declared = Number(contentLength);
+        if (Number.isInteger(declared) && declared >= 0 && declared > maxEntryBytes)
+            return false;
+    }
+    const body = response.clone().body;
+    if (body === null)
+        return true;
+    const reader = body.getReader();
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            reader.releaseLock();
+            return true;
+        }
+        total += value.length;
+        if (total > maxEntryBytes) {
+            // Stop reading immediately rather than draining the rest of an oversized body. `cancel()` is fire-and-forget:
+            // on a cloned response's tee'd stream, Node's undici never settles this promise even though the cancel signal
+            // itself takes effect right away (no further reads happen upstream), so awaiting it would hang forever.
+            reader.cancel().catch(() => { });
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=admit.js.map

package/dist/worker/admit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admit.js","sourceRoot":"","sources":["../../src/worker/admit.ts"],"names":[],"mappings":"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"}

package/dist/worker/decide.d.ts

@@ -20,9 +20,15 @@ export type PwaPassthroughReason =
  * A manifest-hit, non-navigation request that carries a `Range` header (any value). The precache stores full
  * responses, so `engine.match` cannot answer with a genuine partial response; the network answers instead
  * (ADR-0023). Only used where the decision would otherwise be `precache`: a denied, excluded, unclassified or
- * not-precached request keeps its own reason.
+ * not-precached request keeps its own reason. Also used for a `Range` request under a runtime-cache `public-data`
+ * rule, for the same reason.
  */
- | "range";
+ | "range"
+/**
+ * A non-navigation request under a runtime-cache `public-data` rule that carries an `Authorization` header. The
+ * runtime cache never reads or writes a request whose response could be credential-specific (spec "请求判断").
+ */
+ | "authorization";
 export type PwaRequestDecision = 
 /** The worker does not call `respondWith`: the request behaves exactly as it would without a worker. */
 {
@@ -41,6 +47,19 @@ export type PwaRequestDecision =
  | {
     readonly kind: "navigate";
     readonly fallbacks: readonly string[];
+}
+/**
+ * The request matches a compiled runtime-cache rule: `cache: "pages"` for a navigation under a
+ * `navigation-public-dynamic` rule (whose `fallbacks` are exactly what a `navigate` decision for the same request
+ * would carry), `cache: "data"` for a non-navigation request under a `public-data` rule (`fallbacks: []`, the page
+ * gets a network error when nothing cached answers).
+ */
+ | {
+    readonly kind: "runtime";
+    readonly cache: "pages" | "data";
+    readonly strategy: "network-first" | "stale-while-revalidate";
+    readonly resourceClass: "public-data" | "navigation-public-dynamic";
+    readonly fallbacks: readonly string[];
 };
 export type PwaRequestInput = {
     readonly method: string;
@@ -50,6 +69,8 @@ export type PwaRequestInput = {
     readonly navigation: boolean;
     /** `request.headers.has("range")`, whatever the header's value. Ignored for navigations (ADR-0023). */
     readonly range: boolean;
+    /** `request.headers.has("authorization")`, whatever the header's value. Only acted on for a `public-data` rule. */
+    readonly authorization: boolean;
 };
 export type PwaRouterOptions = {
     readonly config: PwaPlatformWorkerConfig;

package/dist/worker/decide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/worker/decide.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAGnE,MAAM,MAAM,oBAAoB;AAC9B,+DAA+D;AAC7D,SAAS,GACT,cAAc;AAChB;;;GAGG;GACD,UAAU;AACZ;;;GAGG;GACD,QAAQ,GACR,cAAc;AAChB,8FAA8F;GAC5F,eAAe;AACjB,qCAAqC;GACnC,YAAY;AACd;;;;;GAKG;GACD,OAAO,CAAC;AAEZ,MAAM,MAAM,kBAAkB;AAC5B,wGAAwG;AACtG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE;AACzE,sDAAsD;GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAC7D;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uGAAuG;IACvG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAAA;CAAE,CAAC;AAIjF,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,SAAS,CAmC1F"}
+{"version":3,"file":"decide.d.ts","sourceRoot":"","sources":["../../src/worker/decide.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAA6B,MAAM,qBAAqB,CAAC;AAG9F,MAAM,MAAM,oBAAoB;AAC9B,+DAA+D;AAC7D,SAAS,GACT,cAAc;AAChB;;;GAGG;GACD,UAAU;AACZ;;;GAGG;GACD,QAAQ,GACR,cAAc;AAChB,8FAA8F;GAC5F,eAAe;AACjB,qCAAqC;GACnC,YAAY;AACd;;;;;;GAMG;GACD,OAAO;AACT;;;GAGG;GACD,eAAe,CAAC;AAEpB,MAAM,MAAM,kBAAkB;AAC5B,wGAAwG;AACtG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE;AACzE,sDAAsD;GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE;AAC7D;;;GAGG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AACtE;;;;;GAKG;GACD;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,eAAe,GAAG,wBAAwB,CAAC;IAC9D,QAAQ,CAAC,aAAa,EAAE,aAAa,GAAG,2BAA2B,CAAC;IACpE,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,CAAC;AAEN,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,uGAAuG;IACvG,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mHAAmH;IACnH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,yFAAyF;IACzF,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IAAE,MAAM,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB,CAAA;CAAE,CAAC;AAIjF,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,SAAS,CA8D1F"}

package/dist/worker/decide.js

@@ -3,8 +3,12 @@ const PASSTHROUGH = (reason) => ({ kind: "passthrough", reason });
 export function createRouter({ config, manifestUrls, origin }) {
     const matcher = createPathMatcher(config.pathRules);
     const manifest = new Set(manifestUrls);
+    // Keyed by pathPrefix, the same key `matcher` resolves on: `config.runtimeCache.rules` is compiled from the same
+    // ordered path rules, filtered to the ones the runtime cache executes, so a pathPrefix match here is always the
+    // exact rule `matcher` itself would have picked — no second longest-prefix search is needed.
+    const runtimeRules = new Map(config.runtimeCache.enabled ? config.runtimeCache.rules.map((rule) => [rule.pathPrefix, rule]) : []);
     return {
-        decide({ method, url, navigation, range }) {
+        decide({ method, url, navigation, range, authorization }) {
             if (method !== "GET")
                 return PASSTHROUGH("non-get");
             if (!URL.canParse(url))
@@ -27,13 +31,32 @@ export function createRouter({ config, manifestUrls, origin }) {
                 const offline = navigation ? offlineFallback(config, manifest) : undefined;
                 return offline === undefined ? PASSTHROUGH("denied") : { kind: "navigate", fallbacks: [offline] };
             }
+            const runtimeRule = runtimeRules.get(rule.pathPrefix);
+            if (navigation) {
+                const fallbacks = navigationFallbacks(config, manifest, requested);
+                // Only a navigation-public-dynamic rule turns a navigation into a runtime decision; a navigation under a
+                // public-data rule behaves exactly as it does without runtime caching.
+                if (runtimeRule !== undefined && runtimeRule.resourceClass === "navigation-public-dynamic") {
+                    return { kind: "runtime", cache: "pages", strategy: runtimeRule.strategy, resourceClass: runtimeRule.resourceClass, fallbacks };
+                }
+                return { kind: "navigate", fallbacks };
+            }
             // The manifest is the precache's membership list, so the decision stays synchronous; the query string is part
-            // of the key, so `?utm=…` variants of a precached URL are not precached themselves.
+            // of the key, so `?utm=…` variants of a precached URL are not precached themselves. A manifest hit always
+            // wins over the runtime cache.
             const exact = `${requested.pathname}${requested.search}`;
-            if (navigation)
-                return { kind: "navigate", fallbacks: navigationFallbacks(config, manifest, requested) };
-            if (!manifest.has(exact))
+            if (!manifest.has(exact)) {
+                // Only a public-data rule turns a non-navigation request into a runtime decision; a non-navigation request
+                // under a navigation-public-dynamic (page) rule behaves exactly as it does without runtime caching.
+                if (runtimeRule !== undefined && runtimeRule.resourceClass === "public-data") {
+                    if (range)
+                        return PASSTHROUGH("range");
+                    if (authorization)
+                        return PASSTHROUGH("authorization");
+                    return { kind: "runtime", cache: "data", strategy: runtimeRule.strategy, resourceClass: runtimeRule.resourceClass, fallbacks: [] };
+                }
                 return PASSTHROUGH("not-precached");
+            }
             // The precache holds full responses, so a Range request would otherwise get a full 200 body instead of a 206;
             // stepping aside here lets the network answer it directly (ADR-0023). Navigations never look at range.
             return range ? PASSTHROUGH("range") : { kind: "precache", manifestUrl: exact };
@@ -41,18 +64,24 @@ export function createRouter({ config, manifestUrls, origin }) {
     };
 }
 /**
- * What an offline navigation may fall back to, in order: the requested URL itself, the same route's `index.html`,
- * and finally the plan's offline fallback page. Nothing else: no other route's cached content may answer a
- * navigation.
+ * What an offline navigation may fall back to, in order: the requested URL itself (query string intact), the same
+ * route with the query string dropped, that route's `index.html` (query string dropped), and finally the plan's
+ * offline fallback page. Nothing else: no other route's cached content may answer a navigation.
+ *
+ * The exact, query-preserving candidate is tried first so a precached query-string variant still wins when one
+ * exists. Only once that misses does the query string get dropped (ADR-0034, 2026-09-23 amendment): a decorated URL
+ * — for example a return-path query on an entry-recovery link — used to skip its own precached document and land on
+ * the offline page solely because of its query string. Dropping the query string on the fallback candidates lets it
+ * reach that document instead, while still never answering with a different route's cached content.
  *
  * The route's `index.html` is tried for URLs with and without a trailing slash. Frameworks that prerender write
  * `about/index.html` but link to `/about` (Nuxt does by default), and a static host serves both spellings from that
- * one file, so both name the same route (ADR-0012, 2026-09-17 amendment). The query string stays part of every key.
+ * one file, so both name the same route (ADR-0012, 2026-09-17 amendment).
  */
 function navigationFallbacks(config, manifest, requested) {
     const { pathname, search } = requested;
-    const candidates = [`${pathname}${search}`];
-    candidates.push(pathname.endsWith("/") ? `${pathname}index.html${search}` : `${pathname}/index.html${search}`);
+    const candidates = [`${pathname}${search}`, pathname];
+    candidates.push(pathname.endsWith("/") ? `${pathname}index.html` : `${pathname}/index.html`);
     const offline = offlineFallback(config, manifest);
     if (offline !== undefined)
         candidates.push(offline);

package/dist/worker/decide.js.map

@@ -1 +1 @@
-{"version":3,"file":"decide.js","sourceRoot":"","sources":["../../src/worker/decide.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"decide.js","sourceRoot":"","sources":["../../src/worker/decide.ts"],"names":[],"mappings":"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"}

package/dist/worker/handlers.d.ts

@@ -1,10 +1,15 @@
-import type { PwaPrecacheEngine } from "@pwa-platform/engine-workbox/worker";
+import type { createRuntimeCacheEngine, PwaPrecacheEngine } from "@pwa-platform/engine-workbox/worker";
 import type { PwaPlatformWorkerConfig } from "../shared/config.js";
 export type PwaPlatformWorkerHandlers = {
     readonly scope: ServiceWorkerGlobalScope;
     /** Already validated by `registerPlatformWorker`. */
     readonly config: PwaPlatformWorkerConfig;
     readonly engine: PwaPrecacheEngine;
+    /**
+     * Builds a runtime-cache engine. Required whenever `config.runtimeCache.enabled` is true; `registerPlatformWorker`
+     * always supplies the real Workbox-backed factory. Tests inject a fake so they never need to load Workbox.
+     */
+    readonly createRuntimeCacheEngine?: typeof createRuntimeCacheEngine;
 };
 /**
  * Registers `install`, `activate`, `fetch`, `message`, `push` and `notificationclick`, and nothing else. The worker
@@ -12,5 +17,5 @@ export type PwaPlatformWorkerHandlers = {
  * `notificationclick` are always on: see ADR-0021 for why a fixed pair of listeners has no observable effect on an
  * application that never subscribes to push.
  */
-export declare function attachPlatformWorker({ scope, config, engine }: PwaPlatformWorkerHandlers): void;
+export declare function attachPlatformWorker({ scope, config, engine, createRuntimeCacheEngine: runtimeCacheEngineFactory, }: PwaPlatformWorkerHandlers): void;
 //# sourceMappingURL=handlers.d.ts.map

package/dist/worker/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/worker/handlers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAI7E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAOnE,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,yBAAyB,GAAG,IAAI,CAmE/F"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/worker/handlers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,wBAAwB,EAAE,iBAAiB,EAAyB,MAAM,qCAAqC,CAAC;AAI9H,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAUnE,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC;IACzC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,wBAAwB,CAAC;CACrE,CAAC;AASF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,MAAM,EACN,MAAM,EACN,wBAAwB,EAAE,yBAAyB,GACpD,EAAE,yBAAyB,GAAG,IAAI,CAyFlC"}

package/dist/worker/handlers.js

@@ -1,20 +1,28 @@
-import { isOfflineWriteMessage, isSkipWaitingMessage } from "../messages/index.js";
+import { isOfflineWriteMessage, isRuntimeCachePendingMessage, isSkipWaitingMessage } from "../messages/index.js";
 import { validatePushPayload } from "../push-payload/index.js";
+import { admitRuntimeResponse } from "./admit.js";
 import { createRouter } from "./decide.js";
 import { validateOfflineWriteEnqueue, validateOfflineWriteFlush } from "./offline-write-intent.js";
 import { flushOfflineWrites } from "./offline-write-flush.js";
 import { createOfflineWriteStore } from "./offline-write-store.js";
 import { resolveNotificationTarget } from "./notification-target.js";
+import { currentDataCacheName, deleteRuntimeCaches } from "./runtime-cleanup.js";
+const PENDING_SIGNAL_LIMIT = 16;
+const PENDING_SIGNAL_TTL_MS = 30_000;
 /**
  * Registers `install`, `activate`, `fetch`, `message`, `push` and `notificationclick`, and nothing else. The worker
  * never calls `skipWaiting` on its own (updates are prompted) and never claims clients. `push` and
  * `notificationclick` are always on: see ADR-0021 for why a fixed pair of listeners has no observable effect on an
  * application that never subscribes to push.
  */
-export function attachPlatformWorker({ scope, config, engine }) {
+export function attachPlatformWorker({ scope, config, engine, createRuntimeCacheEngine: runtimeCacheEngineFactory, }) {
     const origin = new URL(scope.location.href).origin;
     const router = createRouter({ config, manifestUrls: engine.urls(), origin });
     const offlineWriteStore = config.offlineWrites.enabled ? createOfflineWriteStore(config.offlineWrites) : undefined;
+    const runtimeEngines = config.runtimeCache.enabled
+        ? buildRuntimeEngines(config.runtimeCache, config.networkTimeoutSeconds, requireRuntimeCacheEngineFactory(runtimeCacheEngineFactory))
+        : undefined;
+    const pendingSignals = createPendingSignalStore();
     scope.addEventListener("install", (event) => {
         // The engine passes its work to event.waitUntil, so a failed download fails the install; the rejection is only
         // silenced here to keep it out of the worker's unhandled-rejection log.
@@ -24,6 +32,11 @@ export function attachPlatformWorker({ scope, config, engine }) {
         // The cleanup itself already reached event.waitUntil, so a rejection here carries only the engine's diagnostic
         // signal — it fails loudly when a Workbox update changes the shape of its result. Let that surface.
         void engine.activate(event);
+        // Every new activation removes runtime caches this config no longer wants: the pages cache outright (stale HTML
+        // could reference resources the new precache dropped), and every data cache but the current digest's — all of
+        // them when the runtime cache is disabled (spec "缓存命名与清理"). Activation cannot fail because of this cleanup:
+        // a failure here has nowhere useful to surface and must not become an unhandled rejection on the activate event.
+        event.waitUntil(deleteRuntimeCaches(scope, config.runtimeCache, currentDataCacheName(config.runtimeCache)).catch(() => undefined));
     });
     scope.addEventListener("fetch", (event) => {
         const decision = router.decide({
@@ -32,6 +45,7 @@ export function attachPlatformWorker({ scope, config, engine }) {
             navigation: event.request.mode === "navigate",
             // Any value counts, including "bytes=0-" (ADR-0023); decide() only acts on it for a manifest-hit request.
             range: event.request.headers.has("range"),
+            authorization: event.request.headers.has("authorization"),
         });
         if (decision.kind === "passthrough")
             return;
@@ -39,7 +53,11 @@ export function attachPlatformWorker({ scope, config, engine }) {
             event.respondWith(fromPrecache(scope, engine, decision.manifestUrl, event.request));
             return;
         }
-        event.respondWith(navigate(scope, engine, decision.fallbacks, event.request));
+        if (decision.kind === "runtime") {
+            event.respondWith(respondFromRuntimeCache(scope, engine, runtimeEngineFor(runtimeEngines, decision), decision, event, pendingSignals));
+            return;
+        }
+        event.respondWith(navigate(scope, engine, decision.fallbacks, event.request, config.networkTimeoutSeconds));
     });
     scope.addEventListener("message", (event) => {
         if (!isSameOriginWindow(event.source, origin))
@@ -49,13 +67,23 @@ export function attachPlatformWorker({ scope, config, engine }) {
             event.waitUntil(scope.skipWaiting());
             return;
         }
+        if (isRuntimeCachePendingMessage(event.data)) {
+            const [port, ...rest] = event.ports;
+            if (port === undefined || rest.length !== 0)
+                return;
+            const clientId = windowClientId(event.source);
+            if (clientId === undefined)
+                return;
+            replyPending(port, pendingSignals.take(clientId));
+            return;
+        }
         if (!isOfflineWriteMessage(event.data))
             return;
         const [port, ...rest] = event.ports;
         if (port === undefined || rest.length !== 0)
             return;
         if (event.data.type === "pwa:offline-write:clear") {
-            event.waitUntil(clear(event.data, offlineWriteStore, port));
+            event.waitUntil(clear(event.data, offlineWriteStore, port, scope, config.runtimeCache));
             return;
         }
         if (offlineWriteStore === undefined)
@@ -83,14 +111,31 @@ export function attachPlatformWorker({ scope, config, engine }) {
         event.waitUntil(focusOrOpen(scope, target));
     });
 }
-async function clear(message, store, port) {
+async function clear(message, store, port, scope, runtimeCache) {
     try {
         await store?.clear();
-        replyClear(port, message.requestId);
     }
     catch {
         reply(port, message.requestId, "rejected", "offline-write.storage");
+        return;
     }
+    // Every runtime cache goes on logout, current digest included — unlike activation, nothing is kept (spec "登出").
+    // A failure here must not reply "cleared" while the runtime cache is enabled: the registration stays in place.
+    // When it is disabled, this cleanup is best-effort (ADR-0035 "对 v1/v2 应用的非请求判断影响") — there is normally
+    // nothing to delete, and a failure must not give v1/v2 and unenabled apps a new way for logout to fail.
+    if (runtimeCache.enabled) {
+        try {
+            await deleteRuntimeCaches(scope, runtimeCache);
+        }
+        catch {
+            reply(port, message.requestId, "rejected", "offline-write.storage");
+            return;
+        }
+    }
+    else {
+        await deleteRuntimeCaches(scope, runtimeCache).catch(() => undefined);
+    }
+    replyClear(port, message.requestId);
 }
 async function flush(message, config, origin, store, port, send) {
     const checked = validateOfflineWriteFlush(message, config);
@@ -171,16 +216,75 @@ async function focusOrOpen(scope, target) {
 async function fromPrecache(scope, engine, manifestUrl, request) {
     return (await engine.match(manifestUrl)) ?? (await scope.fetch(request));
 }
-/** Navigation: the network answers whenever it responds at all, including 4xx and 5xx; offline uses the fallbacks. */
-async function navigate(scope, engine, fallbacks, request) {
+/**
+ * Navigation: the network answers whenever it responds at all, including 4xx and 5xx; offline uses the fallbacks.
+ * When `networkTimeoutSeconds` is set (ADR-0038) and the network has not answered within that many seconds, the
+ * fallbacks are consulted early: a match is returned immediately and the still-pending network result is left to
+ * settle on its own (its rejection is swallowed, and navigate() never writes to a cache either way, so nothing is
+ * cached from it). With no matching fallback, navigate() keeps waiting for the network exactly as it would without a
+ * timeout — a timeout must never turn a request that would have succeeded into an error.
+ */
+async function navigate(scope, engine, fallbacks, request, networkTimeoutSeconds) {
+    if (networkTimeoutSeconds === undefined) {
+        try {
+            const response = await scope.fetch(request);
+            if (response.type !== "error")
+                return response;
+        }
+        catch {
+            // A rejected fetch is the usual network-failure signal; an error response follows the same fallback path.
+        }
+        return fallbackResponse(engine, fallbacks);
+    }
+    const networkPromise = scope.fetch(request);
+    let timer;
+    // Whichever settles first: the network (success or failure) clears the timer; the timer never rejects, so it
+    // cannot itself produce an unhandled rejection.
+    const timedOut = await new Promise((resolve) => {
+        timer = setTimeout(() => resolve(true), networkTimeoutSeconds * 1000);
+        networkPromise.then(() => resolve(false), () => resolve(false));
+    });
+    if (timer !== undefined)
+        clearTimeout(timer);
+    if (!timedOut) {
+        try {
+            const response = await networkPromise;
+            if (response.type !== "error")
+                return response;
+        }
+        catch {
+            // A rejected fetch is the usual network-failure signal; an error response follows the same fallback path.
+        }
+        return fallbackResponse(engine, fallbacks);
+    }
+    // Timed out. The network promise above already has a handler attached (the race's own .then), so its eventual
+    // settlement — success or rejection — can never surface as an unhandled rejection; nothing here awaits it while
+    // a fallback is used.
+    try {
+        for (const candidate of fallbacks) {
+            const fallback = await engine.match(candidate);
+            if (fallback !== undefined)
+                return fallback;
+        }
+    }
+    catch {
+        // engine.match rejected: fall through to waiting on the network below rather than turning a possibly-
+        // successful request into an error (the same rule as "no fallback available").
+    }
+    // No fallback available: keep waiting for the network rather than turning a possibly-successful request into an
+    // error (spec "一个都没有时，继续等网络"), then apply the same rules as a request that answered in time.
     try {
-        const response = await scope.fetch(request);
+        const response = await networkPromise;
         if (response.type !== "error")
             return response;
     }
     catch {
-        // A rejected fetch is the usual network-failure signal; an error response follows the same fallback path.
+        // Falls through to fallbackResponse, which finds nothing (again) and returns Response.error().
     }
+    return fallbackResponse(engine, fallbacks);
+}
+/** The first precached fallback that exists, in order, or a network error when none does. */
+async function fallbackResponse(engine, fallbacks) {
     for (const candidate of fallbacks) {
         const response = await engine.match(candidate);
         if (response !== undefined)
@@ -193,4 +297,137 @@ function isSameOriginWindow(source, origin) {
         return false;
     return URL.canParse(source.url) && new URL(source.url).origin === origin;
 }
+/** The requesting window client's id, read without invoking an accessor other than the plain property itself. */
+function windowClientId(source) {
+    if (source === null || typeof source !== "object" || !("id" in source))
+        return undefined;
+    const id = source.id;
+    return typeof id === "string" ? id : undefined;
+}
+function replyPending(port, served) {
+    try {
+        port.postMessage({ type: "pwa:runtime-cache:pending-result", version: 1, served });
+    }
+    catch {
+        // The page may have closed its port; a missed reply must not surface as an unhandled worker rejection.
+    }
+}
+function requireRuntimeCacheEngineFactory(factory) {
+    if (factory === undefined) {
+        throw new Error("attachPlatformWorker: config.runtimeCache.enabled requires a createRuntimeCacheEngine factory");
+    }
+    return factory;
+}
+/**
+ * Builds at most three runtime-cache engines, one per (cache, strategy) pair actually used, the first time each is
+ * needed. `networkTimeoutSeconds` (ADR-0038), when set, is passed through only for the two network-first engines —
+ * "pages" and "data-network-first" — never for "data-stale-while-revalidate", which never waits on the network.
+ */
+function buildRuntimeEngines(runtimeCache, networkTimeoutSeconds, factory) {
+    const built = new Map();
+    return (key) => {
+        const existing = built.get(key);
+        if (existing !== undefined)
+            return existing;
+        const engine = key === "pages"
+            ? factory({
+                cacheName: runtimeCache.pagesCacheName,
+                strategy: "network-first",
+                maxEntries: runtimeCache.maxEntries,
+                maxAgeSeconds: runtimeCache.maxAgeSeconds,
+                admit: (response) => admitRuntimeResponse(response, {
+                    resourceClass: "navigation-public-dynamic",
+                    strategy: "network-first",
+                    maxEntryBytes: runtimeCache.maxEntryBytes,
+                }),
+                ...(networkTimeoutSeconds === undefined ? {} : { networkTimeoutSeconds }),
+            })
+            : factory({
+                cacheName: runtimeCache.dataCacheName,
+                strategy: key === "data-network-first" ? "network-first" : "stale-while-revalidate",
+                maxEntries: runtimeCache.maxEntries,
+                maxAgeSeconds: runtimeCache.maxAgeSeconds,
+                admit: (response) => admitRuntimeResponse(response, {
+                    resourceClass: "public-data",
+                    strategy: key === "data-network-first" ? "network-first" : "stale-while-revalidate",
+                    maxEntryBytes: runtimeCache.maxEntryBytes,
+                }),
+                ...(key === "data-network-first" && networkTimeoutSeconds !== undefined ? { networkTimeoutSeconds } : {}),
+            });
+        built.set(key, engine);
+        return engine;
+    };
+}
+/** `decide()` only ever returns a `"runtime"` decision once `config.runtimeCache.enabled` made `runtimeEngines` non-undefined. */
+function runtimeEngineFor(runtimeEngines, decision) {
+    if (runtimeEngines === undefined)
+        throw new Error("Runtime-cache decision without a runtime-cache configuration");
+    return runtimeEngines(decision.cache === "pages" ? "pages" : decision.strategy === "network-first" ? "data-network-first" : "data-stale-while-revalidate");
+}
+/**
+ * Runs one runtime-cache decision. On success, a cache-served response's signal is delivered — posted straight to
+ * the requesting client for a subresource, or stashed by `event.resultingClientId` for a navigation, since a
+ * navigation's own client may not exist yet to receive a direct post (spec "页面信号", T1). On failure (network down
+ * and nothing cached), a page decision falls back exactly like `navigate()`; a data decision rejects so the page
+ * sees a network error, matching the spec's "read-only cache, no offline story for data" stance.
+ */
+async function respondFromRuntimeCache(scope, precacheEngine, runtimeEngine, decision, event, pendingSignals) {
+    const result = await runtimeEngine.handle(event).catch((error) => {
+        if (decision.cache === "pages")
+            return undefined;
+        throw error;
+    });
+    if (result === undefined)
+        return fallbackResponse(precacheEngine, decision.fallbacks);
+    if (result.servedFromCache !== null) {
+        const signal = {
+            url: requestPath(event.request.url),
+            cachedAt: result.servedFromCache.cachedAt,
+            reason: result.servedFromCache.reason,
+        };
+        if (decision.cache === "pages")
+            pendingSignals.store(event.resultingClientId, signal);
+        else
+            event.waitUntil(postServedFromCacheSignal(scope, event.clientId, signal));
+    }
+    return result.response;
+}
+function requestPath(url) {
+    const { pathname, search } = new URL(url);
+    return `${pathname}${search}`;
+}
+async function postServedFromCacheSignal(scope, clientId, signal) {
+    const client = await scope.clients.get(clientId);
+    if (client === undefined)
+        return;
+    try {
+        client.postMessage({ type: "pwa:runtime-cache:served", version: 1, ...signal });
+    }
+    catch {
+        // The page may have navigated away or closed between the fetch and this signal; nothing to deliver to.
+    }
+}
+/** At most 16 pending navigation signals, oldest evicted first; a signal older than 30s is dropped when taken. */
+function createPendingSignalStore() {
+    const entries = new Map();
+    return {
+        store(clientId, signal) {
+            entries.delete(clientId);
+            entries.set(clientId, { signal, storedAt: Date.now() });
+            while (entries.size > PENDING_SIGNAL_LIMIT) {
+                const oldest = entries.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                entries.delete(oldest);
+            }
+        },
+        take(clientId) {
+            const entry = entries.get(clientId);
+            entries.delete(clientId);
+            if (entry === undefined || Date.now() - entry.storedAt > PENDING_SIGNAL_TTL_MS)
+                return null;
+            return entry.signal;
+        },
+    };
+}
 //# sourceMappingURL=handlers.js.map