zip-peek 0.7.2 → 0.7.3

package/README.md

@@ -40,7 +40,7 @@ The package provides two pieces:
 At runtime, the package:
 
 1. Registers the ZIP service worker with the configured `workerUrl` and `scopeUrl`.
-2. Reloads once after first service worker install when needed, so the page becomes controlled.
+2. Reloads once after first service worker install when needed, so the page becomes controlled. On later loads it calls `registration.update()` and reloads once when a newer worker version activates.
 3. Intercepts matching `.zip/...` asset requests within the service worker scope.
 4. Loads and caches the ZIP central directory on first use, or during init when `allowedZipUrls` is provided.
 5. Streams the entry byte span (`offset` through `nextOffset − 1`), parses the local file header, and incrementally inflates deflated entries using `fflate`.
@@ -95,13 +95,14 @@ type InitZipPeekOptions = {
   workerUrl: string;
   scopeUrl: string;
   reloadOnFirstInstall?: boolean;
+  reloadOnWorkerUpdate?: boolean;
   cacheClearingStrategy?: ZipCacheClearingStrategy;
   allowedZipUrls?: string[];
   requireExactManifestPath?: boolean;
   zipAssetCacheName?: string;
   assetCacheTtlMs?: number;
   logPrefix?: string;
-  onError?: (error: Error, info?: string) => void;
+  onError?: (error: Error, info: string | undefined, level: "error" | "warn") => void;
 };
 
 type ZipCacheClearingStrategy = "keep-all" | "keep-allowed-urls" | "clear-all";
@@ -152,6 +153,16 @@ Choose the smallest scope that includes the pages and asset requests you want th
 
 Defaults to `true`. When a service worker is installed for the first time, the current page may not yet be controlled by it. With this option enabled, the package reloads once and returns `{ reloaded: true, initialized: false }`.
 
+`reloadOnWorkerUpdate`
+
+Defaults to `true`. When a matching registration already exists, `initZipPeek()` calls `registration.update()` so a new `zipServiceWorker.js` is found on this load instead of after the browser's own update check. If the page already has a controller and a newer worker is installing, init waits up to 10 seconds for it to activate, then reloads the page and returns `{ reloaded: true, initialized: false }`. If the new worker fails to install or does not activate in time, init continues on the current worker and `onError` receives a `warn` titled `Updated service worker did not activate` (`reason=redundant` or `reason=timeout`).
+
+After a successful init, zip-peek also reloads the page if the controlling worker changes mid-session (for example after the browser's own update check), because the new worker has not received this page's configuration.
+
+Set it to `false` to skip both reloads. Init then sends its configuration to the newly activated worker and continues without a reload. A mid-session worker change is not reloaded either, and that worker runs without this page's configuration until the next init.
+
+The reload is `window.location.reload()` of the window that runs `initZipPeek()`. Inside an iframe, only the iframe reloads.
+
 `cacheClearingStrategy`
 
 Defaults to `'keep-all'`. Controls which zip-peek cache entries are cleared during initialization.
@@ -188,15 +199,17 @@ When fallback resolution succeeds, the asset is still served normally, but `onEr
 
 `onError`
 
-Optional error handler for zip-peek failures and informational reports from the service worker. Receives `(error, info?)`.
+Optional error handler for zip-peek failures and informational reports from the service worker. Receives `(error, info, level)`. `level` is `"warn"` for a thrown network fetch, a file missing from the manifest, a successful zip-basename fallback, a service worker version mismatch, and an updated worker that does not activate. Every other report is `"error"`.
 
 - `error.message` is a **stable title** for telemetry grouping, always prefixed with `[zip-peek-error]`. Unique presigned query strings are not included in the title.
-- `info` holds request-specific details (`path=… zipPath=… reason=… status=… cause=…`).
+- `info` holds request-specific details (`path=… zipPath=… reason=… status=… cause=… zipSW=… zipPeek=…`). `zipSW` is the service-worker build version (the package version baked into `zipServiceWorker.js`). `zipPeek` is the zip-peek package version running on the page. They match on a fresh install and differ when a cached worker is older than the page. Manifest preload and manifest fetch failures also include `phase` (`tail` or `cd`) and `online`. The init step label is kept in front of those fields.
 
 Service-worker fetch failures post `ZIP_SW_ERROR` so `onError` runs (allow-list 403, missing manifest/file 404, renew 502, origin/handler 500). A thrown `fetch()` (offline, DNS, CORS) uses `[zip-peek-error] [NetworkError] ZIP asset fetch failed` or `[zip-peek-error] [NetworkError] ZIP manifest fetch failed`. An HTTP error response from origin is not tagged `[NetworkError]`.
 
 Besides those failures, `onError` is also called when exact manifest lookup fails but zip-basename folder fallback succeeds (see `requireExactManifestPath`). Use this to log or telemetry mismatches between request paths and manifest layout without blocking the response.
 
+During init, zip-peek asks the worker for its build version. If it differs from the page's zip-peek version, `onError` receives a `warn` titled `Service worker version mismatch` with `info` such as `zipSW=0.7.2 zipPeek=0.7.3`. This means the page and the worker came from different deploys, for example because a CDN served an old `zipServiceWorker.js`. Workers built before this check do not answer; after a 500 ms timeout the same warning is reported with `zipSW=unknown`. Init continues in every case.
+
 `zipAssetCacheName`
 
 Overrides the browser Cache API bucket used by the service worker for ZIP manifests and extracted assets.
@@ -375,6 +388,16 @@ or:
 Service-Worker-Allowed: /
 ```
 
+### 6. Do not cache a stable worker URL
+
+When the worker is served under a stable name such as `zipServiceWorker.js`, serve it with:
+
+```http
+Cache-Control: no-cache
+```
+
+(or `max-age=0`), and make sure a CDN in front of it does not cache it for long. The browser skips its own HTTP cache when checking for worker updates, but a CDN or proxy can still return an old script. In that case `registration.update()` finds nothing new, and pages keep running the old worker. The `Service worker version mismatch` warning in `onError` shows when this happens.
+
 ## Bundler Configuration
 
 The package ships the worker as:

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions } from "./types";
 import { isZipPackage } from "./zip-utils";
-export type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipPeekUrlExpiryHandler, ZipWorkerConfig, } from "./types";
+export type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipPeekLogLevel, ZipPeekUrlExpiryHandler, ZipWorkerConfig, } from "./types";
 export { getPresignedUrlExpiryMs, isPresignedUrlExpired } from "./zip-utils";
 /**
  * Registers the zip-peek service worker and configures lazy ZIP asset loading.
@@ -23,7 +23,7 @@ export { getPresignedUrlExpiryMs, isPresignedUrlExpired } from "./zip-utils";
  * sleep or backgrounding, and when a cache-miss fetch finds the URL already
  * expired. Concurrent callers share one in-flight renewal.
  */
-export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, requireExactManifestPath, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
+export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, reloadOnWorkerUpdate, cacheClearingStrategy, allowedZipUrls, requireExactManifestPath, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
 /**
  * Replace a presigned ZIP package URL after renewal so the service worker
  * continue serving assets with the new credentials.

package/dist/index.js

@@ -4,21 +4,38 @@ exports.isZipPackage = exports.isPresignedUrlExpired = exports.getPresignedUrlEx
 exports.initZipPeek = initZipPeek;
 exports.renewPresignedUrl = renewPresignedUrl;
 const types_1 = require("./types");
+const version_1 = require("./version");
 const zip_utils_1 = require("./zip-utils");
 Object.defineProperty(exports, "isZipPackage", { enumerable: true, get: function () { return zip_utils_1.isZipPackage; } });
 var zip_utils_2 = require("./zip-utils");
 Object.defineProperty(exports, "getPresignedUrlExpiryMs", { enumerable: true, get: function () { return zip_utils_2.getPresignedUrlExpiryMs; } });
 Object.defineProperty(exports, "isPresignedUrlExpired", { enumerable: true, get: function () { return zip_utils_2.isPresignedUrlExpired; } });
+const ZIP_PEEK_VERSION_FIELD = `zipPeek=${version_1.ZIP_PEEK_VERSION}`;
+/** Append the page package version. Kept off error.message so titles stay stable. */
+function withPackageVersion(info) {
+    if (!info)
+        return ZIP_PEEK_VERSION_FIELD;
+    if (info.includes("zipPeek="))
+        return info;
+    return `${info} ${ZIP_PEEK_VERSION_FIELD}`;
+}
 /** Default lead time before presigned URL expiry when scheduling renewal. */
 const URL_EXPIRY_LEAD_MS = 10000;
 /** Retry delay when onUrlExpiry runs but the URL is still tracked (renew failed / skipped). */
 const URL_EXPIRY_RETRY_MS = 5000;
 /** Avoid delayMs=0 tight loops while a renewal is already in flight. */
 const URL_EXPIRY_MIN_DELAY_MS = 1000;
+/** How long init waits for an updated service worker to activate before continuing on the current one. */
+const WORKER_ACTIVATION_TIMEOUT_MS = 10000;
+/** Workers built before ZIP_SW_VERSION never reply, so the version check must not wait forever. */
+const WORKER_VERSION_TIMEOUT_MS = 500;
 let currentOnError;
 let currentOnUrlExpiry;
+let currentReloadOnWorkerUpdate = true;
 let clientMessageListenerInstalled = false;
+let controllerChangeListenerInstalled = false;
 let expiryWakeListenersInstalled = false;
+let reloadRequested = false;
 /**
  * Last allow-list sent to the service worker from this page.
  * `undefined` = initZipPeek not completed; `null` = unrestricted; `string[]` = claim.
@@ -31,6 +48,39 @@ const trackedZipUrls = new Map();
 /** In-flight onUrlExpiry promises keyed by normalized zip URL. */
 const urlExpiryInFlight = new Map();
 const sessionManifests = new Map();
+function reloadPage(reason) {
+    if (reloadRequested) {
+        return;
+    }
+    reloadRequested = true;
+    console.log(ZIP_PEEK_VERSION_FIELD, `Reloading page: ${reason}`);
+    window.location.reload();
+}
+function waitForWorkerActivated(worker, timeoutMs) {
+    if (worker.state === "activated") {
+        return Promise.resolve("activated");
+    }
+    if (worker.state === "redundant") {
+        return Promise.resolve("redundant");
+    }
+    return new Promise((resolve) => {
+        const finish = (result) => {
+            clearTimeout(timer);
+            worker.removeEventListener("statechange", onStateChange);
+            resolve(result);
+        };
+        const onStateChange = () => {
+            if (worker.state === "activated") {
+                finish("activated");
+            }
+            else if (worker.state === "redundant") {
+                finish("redundant");
+            }
+        };
+        const timer = setTimeout(() => finish("timeout"), timeoutMs);
+        worker.addEventListener("statechange", onStateChange);
+    });
+}
 function normalizeScopePath(href) {
     let p = new URL(href).pathname;
     if (p.length > 1 && p.endsWith("/")) {
@@ -79,38 +129,60 @@ async function unregisterMismatchedScopeZipServiceWorkerIfNeeded(expectedWorkerU
         const regScopePath = normalizeScopePath(reg.scope);
         if (regScopePath !== wantScopePath) {
             await reg.unregister();
-            console.log(`Unregistered zip service worker (scope ${reg.scope}); re-registering with ${expectedScopeUrl}`);
+            console.log(ZIP_PEEK_VERSION_FIELD, `Unregistered zip service worker (scope ${reg.scope}); re-registering with ${expectedScopeUrl}`);
         }
     }
 }
-async function ensureZipServiceWorkerRegistered({ workerUrl, scopeUrl, reloadOnFirstInstall = true, }) {
-    var _a, _b, _c;
+async function ensureZipServiceWorkerRegistered({ workerUrl, scopeUrl, reloadOnFirstInstall = true, reloadOnWorkerUpdate = true, }) {
+    var _a, _b, _c, _d;
     if (!("serviceWorker" in navigator)) {
         return false;
     }
+    const hadController = Boolean(navigator.serviceWorker.controller);
     await unregisterMismatchedScopeZipServiceWorkerIfNeeded(workerUrl, scopeUrl);
     const existing = await navigator.serviceWorker.getRegistration(scopeUrl);
     const alreadyRegistered = existing &&
         (zipServiceWorkerScriptMatches((_a = existing.active) === null || _a === void 0 ? void 0 : _a.scriptURL, workerUrl) ||
             zipServiceWorkerScriptMatches((_b = existing.waiting) === null || _b === void 0 ? void 0 : _b.scriptURL, workerUrl) ||
             zipServiceWorkerScriptMatches((_c = existing.installing) === null || _c === void 0 ? void 0 : _c.scriptURL, workerUrl));
+    let registration;
     if (!alreadyRegistered) {
         try {
-            await navigator.serviceWorker.register(workerUrl, { scope: scopeUrl });
-            console.log("Zip service worker registered successfully");
+            registration = await navigator.serviceWorker.register(workerUrl, { scope: scopeUrl });
+            console.log(ZIP_PEEK_VERSION_FIELD, "Zip service worker registered successfully");
         }
         catch (error) {
             const context = describeRegistrationFailureContext();
-            console.error("zip-peek: service worker registration failed", context, error);
+            console.error(ZIP_PEEK_VERSION_FIELD, "zip-peek: service worker registration failed", context, error);
             throw attachZipPeekInfo(error, `Service worker registration failed (${context})`);
         }
     }
     else {
-        console.log("Zip service worker already registered; skipping register().");
+        registration = existing;
+        console.log(ZIP_PEEK_VERSION_FIELD, "Zip service worker already registered; checking for updates.");
+        try {
+            await existing.update();
+        }
+        catch (error) {
+            console.warn(ZIP_PEEK_VERSION_FIELD, "zip-peek: service worker update check failed", error);
+        }
+    }
+    const incomingWorker = (_d = registration.installing) !== null && _d !== void 0 ? _d : registration.waiting;
+    if (hadController && incomingWorker) {
+        const result = await waitForWorkerActivated(incomingWorker, WORKER_ACTIVATION_TIMEOUT_MS);
+        if (result === "activated") {
+            if (reloadOnWorkerUpdate) {
+                reloadPage("service worker updated");
+                return true;
+            }
+        }
+        else {
+            reportZipPeekError(currentOnError, (0, types_1.createZipPeekError)("Updated service worker did not activate", "warn"), `reason=${result}`);
+        }
     }
     await navigator.serviceWorker.ready;
     if (reloadOnFirstInstall && !navigator.serviceWorker.controller) {
-        window.location.reload();
+        reloadPage("first service worker install");
         return true;
     }
     return false;
@@ -138,21 +210,26 @@ function describeRegistrationFailureContext() {
 }
 function attachZipPeekInfo(error, info) {
     const err = (0, types_1.toZipPeekError)(error);
-    if (info) {
-        err.zipPeekInfo = (0, types_1.formatZipPeekError)(info);
-    }
+    if (!info)
+        return err;
+    const step = (0, types_1.formatZipPeekError)(info);
+    err.zipPeekInfo = err.zipPeekInfo ? `${step} ${err.zipPeekInfo}` : step;
     return err;
 }
 function reportZipPeekError(onError, error, info) {
     const err = (0, types_1.toZipPeekError)(error);
-    onError === null || onError === void 0 ? void 0 : onError(err, info !== null && info !== void 0 ? info : err.zipPeekInfo);
+    onError === null || onError === void 0 ? void 0 : onError(err, withPackageVersion(info !== null && info !== void 0 ? info : err.zipPeekInfo), err.zipPeekLevel);
 }
 function errorFromWorkerResponse(response) {
-    var _a;
+    var _a, _b;
     const error = new Error((_a = response.error) !== null && _a !== void 0 ? _a : (0, types_1.formatZipPeekError)("Service worker did not acknowledge the message."));
     if (response.errorStack) {
         error.stack = response.errorStack;
     }
+    if (response.info) {
+        error.zipPeekInfo = response.info;
+    }
+    error.zipPeekLevel = (_b = response.level) !== null && _b !== void 0 ? _b : "error";
     return error;
 }
 function clearUrlExpiryTimer(normalizedZipUrl) {
@@ -312,7 +389,7 @@ function ensureClientMessageListener() {
     }
     clientMessageListenerInstalled = true;
     navigator.serviceWorker.addEventListener("message", (event) => {
-        var _a, _b, _c;
+        var _a, _b, _c, _d;
         const data = event.data;
         if (!data) {
             return;
@@ -364,7 +441,26 @@ function ensureClientMessageListener() {
         if ((_c = data.error) === null || _c === void 0 ? void 0 : _c.stack) {
             error.stack = data.error.stack;
         }
-        currentOnError(error, data.info ? (0, types_1.formatZipPeekError)(data.info) : undefined);
+        currentOnError(error, withPackageVersion(data.info ? (0, types_1.formatZipPeekError)(data.info) : undefined), (_d = data.level) !== null && _d !== void 0 ? _d : "error");
+    });
+}
+/**
+ * After init, a worker swap (browser soft update + skipWaiting/claim) leaves
+ * the page talking to a worker that never received ZIP_SW_CONFIG, so reload.
+ */
+function ensureControllerChangeListener() {
+    if (controllerChangeListenerInstalled || !("serviceWorker" in navigator)) {
+        return;
+    }
+    controllerChangeListenerInstalled = true;
+    let hadController = Boolean(navigator.serviceWorker.controller);
+    navigator.serviceWorker.addEventListener("controllerchange", () => {
+        const previouslyControlled = hadController;
+        hadController = Boolean(navigator.serviceWorker.controller);
+        if (!previouslyControlled || !currentReloadOnWorkerUpdate) {
+            return;
+        }
+        reloadPage("service worker changed mid-session");
     });
 }
 function normalizeAllowedZipUrls(allowedZipUrls) {
@@ -372,13 +468,13 @@ function normalizeAllowedZipUrls(allowedZipUrls) {
         return undefined;
     }
     if (allowedZipUrls.length === 0) {
-        throw (0, types_1.createZipPeekError)("allowedZipUrls must contain at least one ZIP URL when provided.");
+        throw (0, types_1.createZipPeekError)("allowedZipUrls must contain at least one ZIP URL when provided.", "error");
     }
     const normalized = new Set();
     for (const zipUrl of allowedZipUrls) {
         const resolvedZipUrl = new URL(zipUrl, window.location.href).href;
         if (!(0, zip_utils_1.isZipPackage)(resolvedZipUrl)) {
-            throw (0, types_1.createZipPeekError)(`allowedZipUrls contains a non-ZIP URL: ${zipUrl}`);
+            throw (0, types_1.createZipPeekError)(`allowedZipUrls contains a non-ZIP URL: ${zipUrl}`, "error");
         }
         normalized.add((0, zip_utils_1.normalizeZipUrl)(resolvedZipUrl));
     }
@@ -388,7 +484,7 @@ async function postWorkerMessage(message) {
     var _a;
     const worker = (_a = navigator.serviceWorker.controller) !== null && _a !== void 0 ? _a : (await navigator.serviceWorker.ready).active;
     if (!worker) {
-        throw (0, types_1.createZipPeekError)("No active service worker.");
+        throw (0, types_1.createZipPeekError)("No active service worker.", "error");
     }
     return new Promise((resolve, reject) => {
         const channel = new MessageChannel();
@@ -404,11 +500,51 @@ async function postWorkerMessage(message) {
         };
         channel.port1.onmessageerror = () => {
             channel.port1.close();
-            reject((0, types_1.createZipPeekError)("Failed to deserialize the service worker response on MessageChannel."));
+            reject((0, types_1.createZipPeekError)("Failed to deserialize the service worker response on MessageChannel.", "error"));
         };
         worker.postMessage(message, [channel.port2]);
     });
 }
+async function readWorkerVersion(timeoutMs) {
+    var _a;
+    const worker = (_a = navigator.serviceWorker.controller) !== null && _a !== void 0 ? _a : (await navigator.serviceWorker.ready).active;
+    if (!worker) {
+        return undefined;
+    }
+    return new Promise((resolve) => {
+        const channel = new MessageChannel();
+        const finish = (version) => {
+            clearTimeout(timer);
+            channel.port1.onmessage = null;
+            channel.port1.close();
+            resolve(version);
+        };
+        const timer = setTimeout(() => finish(undefined), timeoutMs);
+        channel.port1.onmessage = (event) => {
+            const data = event.data;
+            finish(typeof (data === null || data === void 0 ? void 0 : data.version) === "string" ? data.version : undefined);
+        };
+        try {
+            worker.postMessage({ type: "ZIP_SW_VERSION" }, [channel.port2]);
+        }
+        catch (_a) {
+            finish(undefined);
+        }
+    });
+}
+/** Diagnostics only: reports a page/worker build mismatch through onError and never blocks init. */
+async function checkWorkerVersion(onError) {
+    try {
+        const workerVersion = await readWorkerVersion(WORKER_VERSION_TIMEOUT_MS);
+        if (workerVersion === version_1.ZIP_PEEK_VERSION) {
+            return;
+        }
+        reportZipPeekError(onError, (0, types_1.createZipPeekError)("Service worker version mismatch", "warn"), `zipSW=${workerVersion !== null && workerVersion !== void 0 ? workerVersion : "unknown"}`);
+    }
+    catch (error) {
+        console.warn(ZIP_PEEK_VERSION_FIELD, "zip-peek: service worker version check failed", error);
+    }
+}
 async function postWorkerMessageOrThrow(message, info) {
     try {
         await postWorkerMessage(message);
@@ -438,21 +574,22 @@ async function postWorkerMessageOrThrow(message, info) {
  * sleep or backgrounding, and when a cache-miss fetch finds the URL already
  * expired. Concurrent callers share one in-flight renewal.
  */
-async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, requireExactManifestPath = false, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }) {
+async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, reloadOnWorkerUpdate = true, cacheClearingStrategy = "keep-all", allowedZipUrls, requireExactManifestPath = false, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }) {
     if (onError) {
         currentOnError = onError;
     }
     if (onUrlExpiry) {
         currentOnUrlExpiry = onUrlExpiry;
     }
+    currentReloadOnWorkerUpdate = reloadOnWorkerUpdate;
     try {
         const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
         if (cacheClearingStrategy === "keep-allowed-urls" && !normalizedAllowedZipUrls) {
-            throw (0, types_1.createZipPeekError)('cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.');
+            throw (0, types_1.createZipPeekError)('cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.', "error");
         }
         if (!("serviceWorker" in navigator)) {
             // Usually happens in the built in Facebook/Messenger browser.
-            console.warn("zip-peek: Service Worker API not supported in this browser.");
+            console.warn(ZIP_PEEK_VERSION_FIELD, "zip-peek: Service Worker API not supported in this browser.");
             alert("Browser not supported. Please try a different browser.");
             return { reloaded: false, initialized: false };
         }
@@ -463,6 +600,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                 workerUrl,
                 scopeUrl,
                 reloadOnFirstInstall,
+                reloadOnWorkerUpdate,
             });
         }
         catch (error) {
@@ -475,6 +613,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
         if (reloaded) {
             return { reloaded: true, initialized: false };
         }
+        await checkWorkerVersion(onError);
         await postWorkerMessageOrThrow({
             type: "ZIP_SW_CONFIG",
             config: {
@@ -525,6 +664,7 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                 }
             }
         }
+        ensureControllerChangeListener();
         return { reloaded: false, initialized: true };
     }
     catch (error) {
@@ -540,7 +680,7 @@ async function renewPresignedUrl({ previousUrl, nextUrl }) {
     if (!("serviceWorker" in navigator)) {
         // Usually happens in the built in Facebook/Messenger browser.
         alert("Browser not supported. Please try a different browser.");
-        throw (0, types_1.createZipPeekError)("Service Worker API not supported in this browser.");
+        throw (0, types_1.createZipPeekError)("Service Worker API not supported in this browser.", "error");
     }
     // Prefer the host-provided absolute strings as-is so SigV4 query encoding is
     // preserved; only resolve relative URLs against the page location.
@@ -551,7 +691,7 @@ async function renewPresignedUrl({ previousUrl, nextUrl }) {
         ? nextUrl
         : new URL(nextUrl, window.location.href).href;
     if (!(0, zip_utils_1.isZipPackage)(resolvedPrevious) || !(0, zip_utils_1.isZipPackage)(resolvedNext)) {
-        throw (0, types_1.createZipPeekError)("renewPresignedUrl requires both previousUrl and nextUrl to be ZIP package URLs.");
+        throw (0, types_1.createZipPeekError)("renewPresignedUrl requires both previousUrl and nextUrl to be ZIP package URLs.", "error");
     }
     const previous = (0, zip_utils_1.normalizeZipUrl)(resolvedPrevious);
     const next = (0, zip_utils_1.normalizeZipUrl)(resolvedNext);

package/dist/types.d.ts

@@ -9,7 +9,8 @@ export type ZipCacheClearingStrategy = "keep-all" | "keep-allowed-urls" | "clear
  * client claims** (all tabs under the same service worker scope that have
  * configured `allowedZipUrls`), not only the calling tab's list.
  */
-export type ZipPeekErrorHandler = (error: Error, info?: string) => void;
+export type ZipPeekLogLevel = "error" | "warn";
+export type ZipPeekErrorHandler = (error: Error, info: string | undefined, level: ZipPeekLogLevel) => void;
 /**
  * Invoked shortly before a tracked presigned ZIP URL expires.
  */
@@ -25,6 +26,12 @@ export type InitZipPeekOptions = {
     workerUrl: string;
     scopeUrl: string;
     reloadOnFirstInstall?: boolean;
+    /**
+     * Reload the page after a newer service worker version activates, either
+     * during init (found by `registration.update()`) or later in the session.
+     * Defaults to `true`.
+     */
+    reloadOnWorkerUpdate?: boolean;
     cacheClearingStrategy?: ZipCacheClearingStrategy;
     allowedZipUrls?: string[];
     requireExactManifestPath?: boolean;
@@ -51,6 +58,9 @@ export type WorkerMessageResponse = {
     ok: boolean;
     error?: string;
     errorStack?: string;
+    /** `key=value` diagnostics (`phase`, `zipPath`, `online`, `reason`, `status`, `cause`). */
+    info?: string;
+    level?: ZipPeekLogLevel;
 };
 export declare const ZIP_PEEK_ERROR_PREFIX = "[zip-peek-error]";
 export declare const NETWORK_ERROR_PREFIX = "[NetworkError]";
@@ -59,8 +69,13 @@ export declare function formatZipPeekError(message: string): string;
 export declare function zipErrorInfo(fields: Record<string, string | number | boolean | null | undefined>): string;
 export type ZipPeekError = Error & {
     zipPeekInfo?: string;
+    /** HTTP status to return for this failure. Unset means the fetch-handler default (500). */
+    httpStatus?: number;
+    /** Origin status when the response status was remapped (for example 200 → 502). */
+    upstreamStatus?: number;
+    zipPeekLevel: ZipPeekLogLevel;
 };
-export declare function createZipPeekError(message: string, info?: string): Error;
+export declare function createZipPeekError(message: string, level: ZipPeekLogLevel, info?: string): ZipPeekError;
 export declare function toZipPeekError(error: unknown): ZipPeekError;
 export declare function zipPeekErrorInfo(error: unknown): string | undefined;
 export declare function errorMessage(error: unknown): string;

package/dist/types.js

@@ -26,8 +26,9 @@ function zipErrorInfo(fields) {
         .map(([key, value]) => `${key}=${String(value)}`)
         .join(" ");
 }
-function createZipPeekError(message, info) {
+function createZipPeekError(message, level, info) {
     const err = new Error(formatZipPeekError(message));
+    err.zipPeekLevel = level;
     if (info) {
         err.zipPeekInfo = info;
     }
@@ -38,6 +39,9 @@ function toZipPeekError(error) {
     if (!err.message.startsWith(exports.ZIP_PEEK_ERROR_PREFIX)) {
         err.message = formatZipPeekError(err.message);
     }
+    if (!err.zipPeekLevel) {
+        err.zipPeekLevel = "error";
+    }
     return err;
 }
 function zipPeekErrorInfo(error) {

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** Package version. The page reads the installed package; the worker build inlines this number. */
+export declare const ZIP_PEEK_VERSION: string;

package/dist/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZIP_PEEK_VERSION = void 0;
+/** Package version. The page reads the installed package; the worker build inlines this number. */
+exports.ZIP_PEEK_VERSION = require("../package.json").version;