@pwa-platform/engine-workbox 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PWA Platform contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @pwa-platform/engine-workbox
+
+Internal Workbox precache engine for PWA Platform.
+
+Internal precache engine used by the platform worker. It does not expose raw Workbox configuration to applications.
+
+This is a `0.1.0` prerelease. It provides online use, installation integration, static precaching, a safe offline fallback, and controlled updates. It does not enable runtime business API caching, private data caching, automatic write replay, or Push for applications. Production deployment requires the application and infrastructure checks described in the PWA Platform release runbook.
+
+License: MIT.

package/dist/build/index.d.ts

@@ -0,0 +1,2 @@
+export { injectPrecacheManifest, WORKBOX_INJECTION_POINT } from "./inject.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/build/index.js

@@ -0,0 +1,3 @@
+// Build-time entry (`@pwa-platform/engine-workbox`): runs in Node and depends only on @pwa-platform/contracts.
+export { injectPrecacheManifest, WORKBOX_INJECTION_POINT } from "./inject.js";
+//# sourceMappingURL=index.js.map

package/dist/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/build/index.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/build/inject.d.ts

@@ -0,0 +1,14 @@
+import { type PwaPlan } from "@pwa-platform/contracts";
+/** Workbox's default injection point; the platform worker source must contain it exactly once. */
+export declare const WORKBOX_INJECTION_POINT = "self.__WB_MANIFEST";
+/**
+ * Replaces the injection point in `workerSource` with `plan.precache` serialized as a Workbox manifest
+ * (`[{"url": …, "revision": …}]`), in plan order and without adding, removing or rewriting entries. Call it on the
+ * bundled worker: the injection point must survive bundling unchanged (ADR-0011).
+ *
+ * Throws when the plan is invalid (the message lists diagnostic codes and paths only), when the precache holds
+ * entries the worker engine would reject at startup, or when the injection point does not occur exactly once.
+ * Pure and deterministic: no file access, bundling or minification.
+ */
+export declare function injectPrecacheManifest(workerSource: string, plan: PwaPlan): string;
+//# sourceMappingURL=inject.d.ts.map

package/dist/build/inject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject.d.ts","sourceRoot":"","sources":["../../src/build/inject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAErE,kGAAkG;AAClG,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAE5D;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CA+BlF"}

package/dist/build/inject.js

@@ -0,0 +1,50 @@
+import { validatePlan } from "@pwa-platform/contracts";
+/** Workbox's default injection point; the platform worker source must contain it exactly once. */
+export const WORKBOX_INJECTION_POINT = "self.__WB_MANIFEST";
+/**
+ * Replaces the injection point in `workerSource` with `plan.precache` serialized as a Workbox manifest
+ * (`[{"url": …, "revision": …}]`), in plan order and without adding, removing or rewriting entries. Call it on the
+ * bundled worker: the injection point must survive bundling unchanged (ADR-0011).
+ *
+ * Throws when the plan is invalid (the message lists diagnostic codes and paths only), when the precache holds
+ * entries the worker engine would reject at startup, or when the injection point does not occur exactly once.
+ * Pure and deterministic: no file access, bundling or minification.
+ */
+export function injectPrecacheManifest(workerSource, plan) {
+    if (typeof workerSource !== "string")
+        throw new TypeError("The worker source must be a string");
+    const result = validatePlan(plan);
+    if (!result.ok) {
+        const findings = result.diagnostics.map(({ code, path }) => `${code} at ${path === "" ? "(root)" : path}`);
+        throw new Error(`Cannot inject an invalid PwaPlan: ${findings.join(", ")}`);
+    }
+    // contracts accept an empty revision and repeated URLs, which createPrecacheEngine rejects; failing here keeps
+    // such a plan from shipping a worker that cannot start.
+    const seen = new Set();
+    const problems = result.value.precache.flatMap(({ url, revision }, index) => {
+        const found = [];
+        if (revision === "")
+            found.push(`/precache/${index}/revision must be null or a non-empty string`);
+        if (seen.has(url))
+            found.push(`/precache/${index}/url duplicates an earlier entry`);
+        seen.add(url);
+        return found;
+    });
+    if (problems.length > 0) {
+        throw new Error(`Cannot inject a precache manifest the worker engine would reject: ${problems.join(", ")}`);
+    }
+    const occurrences = countOccurrences(workerSource, WORKBOX_INJECTION_POINT);
+    if (occurrences !== 1) {
+        throw new Error(`Expected exactly one ${WORKBOX_INJECTION_POINT} injection point in the worker source, found ${occurrences}`);
+    }
+    const manifest = JSON.stringify(result.value.precache.map(({ url, revision }) => ({ url, revision })));
+    const index = workerSource.indexOf(WORKBOX_INJECTION_POINT);
+    return `${workerSource.slice(0, index)}${manifest}${workerSource.slice(index + WORKBOX_INJECTION_POINT.length)}`;
+}
+function countOccurrences(text, search) {
+    let count = 0;
+    for (let index = text.indexOf(search); index !== -1; index = text.indexOf(search, index + search.length))
+        count += 1;
+    return count;
+}
+//# sourceMappingURL=inject.js.map

package/dist/build/inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject.js","sourceRoot":"","sources":["../../src/build/inject.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAgB,MAAM,yBAAyB,CAAC;AAErE,kGAAkG;AAClG,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE5D;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,YAAoB,EAAE,IAAa;IACxE,IAAI,OAAO,YAAY,KAAK,QAAQ;QAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;IAEhG,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3G,MAAM,IAAI,KAAK,CAAC,qCAAqC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9E,CAAC;IAED,+GAA+G;IAC/G,wDAAwD;IACxD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,EAAE;QAC1E,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,QAAQ,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,8CAA8C,CAAC,CAAC;QAClG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,kCAAkC,CAAC,CAAC;QACpF,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,qEAAqE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9G,CAAC;IAED,MAAM,WAAW,GAAG,gBAAgB,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;IAC5E,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,wBAAwB,uBAAuB,gDAAgD,WAAW,EAAE,CAAC,CAAC;IAChI,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IACvG,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC5D,OAAO,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,GAAG,uBAAuB,CAAC,MAAM,CAAC,EAAE,CAAC;AACnH,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,MAAc;IACpD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC;QAAE,KAAK,IAAI,CAAC,CAAC;IACrH,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/worker/engine.d.ts

@@ -0,0 +1,31 @@
+import { type PwaPrecacheEngineOptions } from "./options.js";
+export type PwaPrecacheInstallResult = {
+    /** Absolute URLs, without `__WB_REVISION__`, of the manifest entries downloaded into the precache during this install. */
+    readonly updatedUrls: readonly string[];
+    /** Absolute URLs, without `__WB_REVISION__`, of the manifest entries that were already cached with the same revision. */
+    readonly notUpdatedUrls: readonly string[];
+};
+export type PwaPrecacheActivateResult = {
+    /**
+     * Cache keys removed from the precache because they are no longer in the manifest: absolute request URLs, including
+     * the `__WB_REVISION__` query of revisioned entries.
+     */
+    readonly deletedUrls: readonly string[];
+};
+/** Precache port used by the platform worker (sw-runtime); it only acts when one of its methods is called. */
+export type PwaPrecacheEngine = {
+    /** Call from the install event; downloads new or changed manifest entries and fails if any request fails. */
+    install(event: ExtendableEvent): Promise<PwaPrecacheInstallResult>;
+    /** Call from the activate event; removes entries of this precache that are no longer in the manifest. */
+    activate(event: ExtendableEvent): Promise<PwaPrecacheActivateResult>;
+    /** Reads a manifest URL from this precache only; returns `undefined` otherwise, including for unparsable URLs, and never uses the network. */
+    match(url: string): Promise<Response | undefined>;
+    /** Manifest URLs in manifest order, exactly as given in `entries` (paths, not absolute URLs). */
+    urls(): readonly string[];
+};
+/**
+ * Creates the precache port for one plan. It registers no event listeners, never calls `skipWaiting` or
+ * `clients.claim`, and touches no cache other than `cacheName`.
+ */
+export declare function createPrecacheEngine(options: PwaPrecacheEngineOptions): PwaPrecacheEngine;
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/worker/engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAqD,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAEhH,MAAM,MAAM,wBAAwB,GAAG;IACrC,0HAA0H;IAC1H,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,yHAAyH;IACzH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAAC;AAEF,8GAA8G;AAC9G,MAAM,MAAM,iBAAiB,GAAG;IAC9B,6GAA6G;IAC7G,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACnE,yGAAyG;IACzG,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IACrE,8IAA8I;IAC9I,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;IAClD,iGAAiG;IACjG,IAAI,IAAI,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAkCzF"}

package/dist/worker/engine.js

@@ -0,0 +1,42 @@
+import { PrecacheController } from "workbox-precaching";
+import { resolveManifestUrl, validatePrecacheEngineOptions } from "./options.js";
+/**
+ * Creates the precache port for one plan. It registers no event listeners, never calls `skipWaiting` or
+ * `clients.claim`, and touches no cache other than `cacheName`.
+ */
+export function createPrecacheEngine(options) {
+    const { cacheName, entries } = validatePrecacheEngineOptions(options);
+    const controller = new PrecacheController({ cacheName, fallbackToNetwork: false });
+    controller.addToCacheList(entries.map(({ url, revision }) => ({ url, revision })));
+    const urls = entries.map(({ url }) => url);
+    return {
+        async install(event) {
+            const { updatedURLs, notUpdatedURLs } = await controller.install(event);
+            return { updatedUrls: [...updatedURLs], notUpdatedUrls: [...notUpdatedURLs] };
+        },
+        async activate(event) {
+            // Workbox 7.4.1 declares the result as `{ deletedCacheRequests }` but returns `{ deletedURLs }`, so read the
+            // field it actually returns and fail loudly if a Workbox update changes it again.
+            const { deletedURLs } = (await controller.activate(event));
+            if (!Array.isArray(deletedURLs) || !deletedURLs.every((url) => typeof url === "string")) {
+                throw new Error("Workbox did not report the deleted precache requests");
+            }
+            return { deletedUrls: [...deletedURLs] };
+        },
+        async match(url) {
+            if (!URL.canParse(url, self.location.href))
+                return undefined;
+            // Workbox keys its URL-to-cache-key map by the exact absolute URL of each manifest entry, so any other URL
+            // (another query, a missing index.html, another origin) has no cache key and is never looked up.
+            const cacheKey = controller.getCacheKeyForURL(resolveManifestUrl(url, self.location.href));
+            if (cacheKey === undefined)
+                return undefined;
+            // CacheStorage.match with cacheName reads that cache only and, unlike caches.open, never creates it.
+            return (await self.caches.match(cacheKey, { cacheName })) ?? undefined;
+        },
+        urls() {
+            return [...urls];
+        },
+    };
+}
+//# sourceMappingURL=engine.js.map

package/dist/worker/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/worker/engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAiC,MAAM,cAAc,CAAC;AA6BhH;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAiC;IACpE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,6BAA6B,CAAC,OAAO,CAAC,CAAC;IACtE,MAAM,UAAU,GAAG,IAAI,kBAAkB,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,UAAU,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC;IAEnF,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAE3C,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,KAAK;YACjB,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;YACxE,OAAO,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC,GAAG,cAAc,CAAC,EAAE,CAAC;QAChF,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,KAAK;YAClB,6GAA6G;YAC7G,kFAAkF;YAClF,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAkD,CAAC;YAC5G,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;gBACxF,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;YAC1E,CAAC;YACD,OAAO,EAAE,WAAW,EAAE,CAAC,GAAG,WAAW,CAAC,EAAE,CAAC;QAC3C,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,GAAG;YACb,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC7D,2GAA2G;YAC3G,iGAAiG;YACjG,MAAM,QAAQ,GAAG,UAAU,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3F,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC7C,qGAAqG;YACrG,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,IAAI,SAAS,CAAC;QACzE,CAAC;QACD,IAAI;YACF,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/worker/index.d.ts

@@ -0,0 +1,4 @@
+export { createPrecacheEngine } from "./engine.js";
+export type { PwaPrecacheActivateResult, PwaPrecacheEngine, PwaPrecacheInstallResult } from "./engine.js";
+export type { PwaPrecacheEngineOptions, PwaPrecacheManifestEntry } from "./options.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC"}

package/dist/worker/index.js

@@ -0,0 +1,4 @@
+// Worker entry (`@pwa-platform/engine-workbox/worker`): runs in a service worker after bundling and depends only
+// on workbox-precaching and workbox-core, never on Node modules.
+export { createPrecacheEngine } from "./engine.js";
+//# sourceMappingURL=index.js.map

package/dist/worker/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/worker/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,iEAAiE;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/worker/options.d.ts

@@ -0,0 +1,17 @@
+/** One entry of the injected manifest (`self.__WB_MANIFEST`), mirroring `PwaPlan.precache`. */
+export type PwaPrecacheManifestEntry = {
+    /** Canonical absolute path, as in `PwaPlan.precache`: no query, fragment, dot segments, `//` or backslashes. */
+    readonly url: string;
+    /** Content revision, or `null` when the URL itself is versioned (fingerprinted). */
+    readonly revision: string | null;
+};
+export type PwaPrecacheEngineOptions = {
+    /** The contracts `cacheName(identity, "precache")` for the running plan. */
+    readonly cacheName: string;
+    readonly entries: readonly PwaPrecacheManifestEntry[];
+};
+/** Validates engine options and returns a fresh copy. Messages name fields and indexes, never input values. */
+export declare function validatePrecacheEngineOptions(options: unknown): PwaPrecacheEngineOptions;
+/** Resolves `url` against `base` and drops the fragment; the query string is kept, so matching stays exact. */
+export declare function resolveManifestUrl(url: string, base: string): string;
+//# sourceMappingURL=options.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/worker/options.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,MAAM,wBAAwB,GAAG;IACrC,gHAAgH;IAChH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACvD,CAAC;AAOF,+GAA+G;AAC/G,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,OAAO,GAAG,wBAAwB,CAqCxF;AAiBD,+GAA+G;AAC/G,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIpE"}

package/dist/worker/options.js

@@ -0,0 +1,63 @@
+const CACHE_NAME_PREFIX = "pwa:";
+const CACHE_NAME_SUFFIX = ":precache";
+// Only used to check the form of paths; never requested.
+const PATH_BASE = "https://engine-workbox.invalid/";
+/** Validates engine options and returns a fresh copy. Messages name fields and indexes, never input values. */
+export function validatePrecacheEngineOptions(options) {
+    if (!isRecord(options))
+        throw new TypeError("Precache engine options must be an object");
+    const { cacheName, entries } = options;
+    const hasPlatformShape = typeof cacheName === "string" &&
+        cacheName.startsWith(CACHE_NAME_PREFIX) &&
+        cacheName.endsWith(CACHE_NAME_SUFFIX) &&
+        cacheName.length > CACHE_NAME_PREFIX.length + CACHE_NAME_SUFFIX.length;
+    if (!hasPlatformShape) {
+        throw new Error('cacheName must be a contracts precache cache name of the form "pwa:<…>:precache"');
+    }
+    if (!Array.isArray(entries))
+        throw new TypeError("entries must be an array");
+    const seen = new Set();
+    const normalised = entries.map((entry, index) => {
+        if (!isRecord(entry))
+            throw new TypeError(`entries[${index}] must be an object`);
+        const keys = Object.keys(entry).sort();
+        if (keys.length !== 2 || keys[0] !== "revision" || keys[1] !== "url") {
+            throw new Error(`entries[${index}] must have exactly the fields url and revision`);
+        }
+        const { url, revision } = entry;
+        if (typeof url !== "string" || !isCanonicalPath(url)) {
+            throw new Error(`entries[${index}].url must be a canonical same-origin absolute path: no query, fragment, dot segments, "//", backslashes or characters the URL parser would change`);
+        }
+        if (revision !== null && (typeof revision !== "string" || revision === "")) {
+            throw new Error(`entries[${index}].revision must be a non-empty string or null`);
+        }
+        // Canonical paths have exactly one spelling, so equal strings are the only duplicates.
+        if (seen.has(url))
+            throw new Error(`entries[${index}].url duplicates an earlier entry`);
+        seen.add(url);
+        return { url, revision };
+    });
+    return { cacheName, entries: normalised };
+}
+/**
+ * The rule contracts' `isCanonicalPath` applies to `PwaPlan.precache` URLs, repeated here because the worker entry
+ * does not import contracts. The URL parser treats `\` as `/` and drops tabs and newlines, so without the final
+ * comparison `/\evil.example/a.js` would resolve to another origin.
+ */
+function isCanonicalPath(value) {
+    return (value.startsWith("/") &&
+        !value.includes("//") &&
+        !value.includes("\\") &&
+        URL.canParse(value, PATH_BASE) &&
+        new URL(value, PATH_BASE).pathname === value);
+}
+/** Resolves `url` against `base` and drops the fragment; the query string is kept, so matching stays exact. */
+export function resolveManifestUrl(url, base) {
+    const resolved = new URL(url, base);
+    resolved.hash = "";
+    return resolved.href;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=options.js.map

package/dist/worker/options.js.map

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@pwa-platform/engine-workbox",
+  "version": "0.1.0-beta.0",
+  "description": "Internal Workbox precache engine for PWA Platform.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/build/index.d.ts",
+      "import": "./dist/build/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "import": "./dist/worker/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "workbox-core": "7.4.1",
+    "workbox-precaching": "7.4.1",
+    "@pwa-platform/contracts": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.63.0",
+    "@types/node": "24.13.4",
+    "vite": "8.3.0",
+    "@pwa-platform/browser-test-harness": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "next"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.worker.build.json",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "typecheck": "tsc --noEmit --project tsconfig.json && tsc --noEmit --project tsconfig.worker.json && tsc --noEmit --project tsconfig.browser.json"
+  }
+}