zip-peek 0.2.1 → 0.2.3-alpha.0

package/README.md

@@ -1,34 +1,256 @@
 # zip-peek
 
-`zip-peek` lets browser applications load files from a remote `.zip` archive by only requesting the needed range of bytes without downloading and extracting the full ZIP file.
+Load individual files from a remote `.zip` in the browser using HTTP range requests—no full download, no client-side unzip loop. A service worker intercepts URLs like `https://cdn.example.com/pkg.zip/path/to/asset.png` and returns normal responses.
 
-It registers a service worker that intercepts requests like:
+*We thought browsers could never use a ZIP bucket without killing performance. We were wrong—and zip-peek is how we proved it.*
 
-```text
-https://cdn.example.com/packages/session.zip/path/to/asset.png
+---
+
+## The setup every platform team knows
+
+At our company, we serve the same packaged content to two clients: a **mobile app** and a **web app**. For a long time, that meant **two identical buckets** on our CDN—same assets, same structure, duplicated storage and ops:
+
+| Bucket | Consumer | Why it existed |
+|--------|----------|----------------|
+| **Zipped** | Mobile | Users can download the package once and open it offline later. A single archive is the right shape for “take this home.” |
+| **Unzipped** | Web | Loose files under a normal folder path—`base/slides/slide-1/image.png`—because that’s what browsers and our frontend already expected. |
+
+Same content. Two pipelines. Two bills. Two places for drift to creep in (“did we deploy the zip *and* the folder?”).
+
+Nobody loved it, but it felt *correct*. Mobile gets archives. Web gets directories. That’s just how the web works, isn’t it?
+
+### Before → After
+
+| **Before** | **After** |
+|------------|-----------|
+| Mobile → `session.zip` | Mobile → `session.zip` |
+| Web → `session/` (unzipped) | Web → `session.zip` (same bucket) |
+| Duplicate storage & deploys | One source of truth |
+
+```mermaid
+flowchart LR
+  subgraph before [Before]
+    M1[Mobile] --> Z[session.zip]
+    W1[Web] --> U[session/]
+  end
+  subgraph after [After]
+    M2[Mobile] --> Z2[session.zip]
+    W2[Web] --> Z2
+  end
+```
+
+---
+
+## What we believed about browsers and ZIP files
+
+When my manager said we should **remove the unzipped bucket** and have the **web app use the zipped bucket**, my first reaction was honest: *this is madness.*
+
+The mental model was simple and brutal:
+
+1. To use a file inside a ZIP in the browser, you’d have to **download the whole archive**.
+2. Then **unzip it in JavaScript**—CPU, memory, time on the main thread or a worker.
+3. For a large session package (slides, images, audio), that would **destroy first load**, **hurt low-end devices**, and **waste bandwidth** on assets the user never opens.
+
+Mobile can download `session.zip`, stash it, and read entries locally. The web, we assumed, **cannot** download a ZIP and unzip it without a performance cliff—so we **had** to keep the unzipped bucket for the web app.
+
+That belief wasn’t lazy. It matched how most teams ship: ZIP on mobile, folder tree on CDN for web. It’s the industry default.
+
+So when the task landed on my desk—*make the web app work from the zip bucket, performantly*—it felt like being asked to disprove physics.
+
+**Spoiler alert: it can be done wonderfully.** But not by downloading and unpacking the whole ZIP in the page. By changing *where* the work happens.
+
+| ❌ Naive approach | ✓ zip-peek |
+|-------------------|------------|
+| Download entire 200 MB ZIP | Range: ~40 KB for one PNG |
+| Unzip in JS — CPU + memory | One asset at a time |
+| Browser chokes | Fast, normal responses |
+
+---
+
+## The insight: browsers don’t need the whole ZIP—only the bytes for one file
+
+ZIP isn’t a black box you must swallow whole. At the end of every archive is a **central directory**: an index of filenames, compressed sizes, and byte offsets. With **HTTP range requests**, you can:
+
+1. Fetch a small slice from the **end** of the file to find that index.
+2. Fetch only the **central directory** bytes.
+3. For each asset request, fetch **only the byte range** for that one entry.
+4. Inflate that chunk if it’s deflated, return a normal `Response`, and **cache** the result.
+
+No 200 MB download for a 40 KB PNG. No app-wide unzip loop. No rewriting every screen to understand “archive semantics.”
+
+The web doesn’t need a second bucket. It needs something in front of the zip bucket that speaks **URL paths** on the outside and **byte ranges** on the inside.
+
+That something is what I built: **`zip-peek`**.
+
+**What happens (in order):**
+
+1. App requests `session.zip/slides/hero.png`
+2. Service worker intercepts — not a normal loose file
+3. Range: last 64 KB of ZIP → locate End of Central Directory
+4. Range: fetch central directory only (the index)
+5. Range: fetch bytes for `hero.png` only → inflate if needed
+6. Cache extracted asset; return `200 image/png` to the app
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant SW as zip-peek SW
+  participant CDN
+  App->>SW: GET session.zip/.../hero.png
+  SW->>CDN: Range tail 64KB
+  CDN-->>SW: 206
+  SW->>CDN: Range central directory
+  CDN-->>SW: 206
+  SW->>CDN: Range entry bytes only
+  CDN-->>SW: 206
+  SW-->>App: 200 image/png
 ```
 
-The service worker fetches only the byte range needed for the requested ZIP entry, inflates the file when required, caches the extracted response, and returns it to the browser as a normal asset response.
+---
 
-## When Is This Package Useful?
+## What `zip-peek` does for our web app
 
-Use this package when your app receives a base path and later appends folders and file names to fetch assets from that path.
+`zip-peek` registers a **service worker** that intercepts requests like:
 
-For example, your app may normally treat the base path as a directory:
+```text
+https://cdn.example.com/packages/session.zip/slides/slide-1/hero.png
+```
+
+Our web app **keeps the same URL-building pattern** it used for the unzipped bucket—only the base path changes from a folder to a `.zip` URL:
 
 ```ts
+// Before (unzipped bucket)
 const basePath = "https://cdn.example.com/packages/session";
-const imageUrl = `${basePath}/slides/slide-1/image.png`;
+const imageUrl = `${basePath}/slides/slide-1/hero.png`;
+
+// After (zip bucket — same pattern)
+const basePath = "https://cdn.example.com/packages/session.zip";
+const imageUrl = `${basePath}/slides/slide-1/hero.png`;
 ```
 
-If the same assets are sometimes delivered as a ZIP file instead:
+`fetch(imageUrl)` and `<img src={imageUrl}>` still work. The service worker:
+
+- Parses the ZIP index from the remote archive (range requests on the tail, then the central directory).
+- Resolves the inner path (`slides/slide-1/hero.png`).
+- Fetches **only** that entry’s bytes.
+- Decompresses when needed (stored or deflated entries).
+- Serves a normal cached response to the browser.
+
+From product code’s perspective, the zip bucket **behaves like a virtual folder**. The “impossible” migration was mostly: point `basePath` at `.zip`, initialize the worker, ensure the CDN supports `Accept-Ranges: bytes`.
+
+**Simple flow:**
+
+1. **Your app** — `fetch()` or `<img src>` — no ZIP code.
+2. **zip-peek (service worker)** — sees a path into a `.zip` file, fetches only that asset from the archive.
+3. **CDN** — sends a small byte range from `session.zip`, not the whole file.
+4. **Back to your app** — a normal image response, as if the PNG lived in a folder.
+
+*The URL looks like a folder path. The service worker makes it work.*
+
+---
+
+## The real win: shared engines, zero code changes
+
+The performance story mattered—but the reason this package was **so** valuable on our stack is structural.
+
+We run **engines** that power both the web app and the mobile app. They are the same code paths: load a package, resolve assets, render slides, play audio, and so on. The host passes in a **`packageBasePath`**, and the engine builds URLs the same way every time:
 
 ```ts
-const basePath = "https://cdn.example.com/packages/session.zip";
-const imageUrl = `${basePath}/slides/slide-1/image.png`;
+const imageUrl = `${packageBasePath}/slides/slide-1/image.png`;
+```
+
+The engine does not branch on web vs mobile. It **`fetch`es** what looks like an ordinary absolute URL and expects the platform to return bytes.
+
+**Mobile and web prepare that base differently**—but the engine never sees the difference in code:
+
+| Host | How the host prepares assets | What the engine receives as `packageBasePath` |
+|------|------------------------------|-----------------------------------------------|
+| **Mobile** | Download `session.zip` → uncompress on device → **localhost** server over the extracted folder | `http://127.0.0.1:3847/` |
+| **Web (before)** | Unzipped CDN bucket | `https://cdn.example.com/packages/session` |
+| **Web (after zip-peek)** | Zip on CDN + `initZipPeek()` | `https://cdn.example.com/packages/session.zip` |
+
+On mobile, the engine always talked to a **real folder**—just served locally:
+
+```text
+http://127.0.0.1:3847/slides/slide-1/image.png
+```
+
+Mobile never passed the zip URL into the engine. The app shell downloaded the archive, unpacked it, stood up localhost, and handed the engine an unzipped base path.
+
+**After `zip-peek`**, web could use the **same zip bucket** mobile downloads from. Web passes:
+
+```text
+https://cdn.example.com/packages/session.zip/slides/slide-1/image.png
 ```
 
-`zip-peek` lets the app keep using the same URL-building pattern. The app does not need to know whether the base path points to a normal directory or a ZIP file, and the ZIP-specific work stays inside the service worker.
+Only the **service worker** knows that URL points *into* a remote ZIP.
+
+- **Mobile:** unchanged (download zip → unzip → localhost → directory `packageBasePath`).
+- **Web:** inject the zip URL and wire up `initZipPeek()` once.
+- **Engine:** zero changes.
+
+```mermaid
+flowchart TB
+  subgraph engine["Shared engine — unchanged"]
+    U["`${packageBasePath}/asset.png`"]
+    F[fetch]
+    U --> F
+  end
+  subgraph mobile["Mobile host"]
+    CDN1[(CDN session.zip)]
+    DL[Download and unzip]
+    LH[Localhost server]
+    PM["packageBasePath = http://127.0.0.1:…/"]
+    CDN1 --> DL --> LH --> PM --> engine
+  end
+  subgraph web["Web host"]
+    CDN2[(CDN session.zip)]
+    P["packageBasePath = …/session.zip"]
+    SW[zip-peek service worker]
+    CDN2 --> P --> engine
+    F -. intercepted .-> SW
+    SW --> CDN2
+  end
+```
+
+---
+
+## From “pure madness” to one source of truth
+
+| Before | After |
+|--------|--------|
+| Two buckets, same content | **One zip bucket** for mobile *and* web |
+| Web tied to unzipped CDN layout | Web uses **path-under-zip** URLs |
+| Fear of full-archive download + JS unzip | **Range-based peek** per asset + Cache API |
+| “Browsers can’t do ZIP performantly” | **Browsers can**, with the right network layer |
+
+Mobile still downloads the zip, uncompresses it, and serves it on localhost for offline—that workflow unchanged. Web now reads from the **same zip on the CDN**, on demand via zip-peek, without downloading the full archive.
+
+---
+
+## What had to be true on the infrastructure side
+
+- The zip origin must support **HTTP byte ranges** (`Accept-Ranges: bytes`, `206 Partial Content`).
+- The service worker script must be served **same-origin** (with `Service-Worker-Allowed` when scope is wider than the worker path).
+- Package URLs should end with **`.zip`**.
+
+We also support **presigned URLs**, **allow-lists** for zip URLs, and **cache TTL** for extracted assets. See the [README](../README.md#documentation) for details.
+
+---
+
+## A note to the next person who hears “use the zip bucket on web”
+
+If your gut says *browsers will choke*, you’re half right: **browsers will choke if you download and unzip the whole archive in the client.**
+
+If your gut says *therefore we need a parallel unzipped bucket forever*, that’s the part we overturned.
+
+The performant model is **peek, don’t gulp**: index the archive remotely, pull one entry at a time, cache what you’ve already extracted.
+
+**It can be done wonderfully.**
+
+---
+
+## Documentation
 
 ## What It Does
 
@@ -43,10 +265,9 @@ At runtime, the package:
 2. Reloads once after first service worker install when needed, so the page becomes controlled.
 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. Fetches only the byte range needed for the requested file.
-6. Inflates deflated files using `fflate`.
-7. Returns the extracted file bytes to the browser request as a normal `Response`.
-8. Caches extracted assets in the browser Cache API.
+5. Fetches the entry byte span (`offset` through `nextOffset − 1`), parses the local file header, and inflates deflated entries using `fflate`.
+6. Returns the extracted bytes as a normal `Response` (or `206` when the client sent a `Range` header).
+7. Caches manifests and extracted assets in the browser Cache API.
 
 ## Installation
 
@@ -161,7 +382,7 @@ Defaults to `'keep-all'`. Controls which zip-peek cache entries are cleared duri
 
 `allowedZipUrls`
 
-Restricts zip-peek to a known set of ZIP package URLs. When omitted, zip-peek lazily serves any matching `.zip/...` request inside the service worker scope. When provided, the array must contain at least one ZIP URL, and zip-peek transparently passes matching requests for ZIP URLs outside the list.
+Restricts zip-peek to a known set of ZIP package URLs. When omitted, zip-peek lazily serves any matching `.zip/...` request inside the service worker scope. When provided, the array must contain at least one ZIP URL; requests to ZIP URLs outside the list receive **403** from the service worker.
 
 The allow-list also acts as a warmup list: zip-peek loads and caches each allowed ZIP manifest during initialization.
 
@@ -377,10 +598,11 @@ If your app is served from a subpath, adjust both `workerUrl` and `scopeUrl` to
 
 The service worker stores:
 
-- the parsed ZIP manifest
-- extracted full assets
+- parsed ZIP manifests (in `zip-cache-v1` by default, keyed per ZIP URL)
+- fully extracted and decompressed assets (with `X-ZipSW-Cached-At` TTL metadata)
+- persisted `allowedZipUrls` in a separate config cache (`zip-peek-config-v1`)
 
-The default cache bucket is:
+The default asset/manifest cache bucket is:
 
 ```text
 zip-cache-v1
@@ -392,7 +614,7 @@ Use `cacheClearingStrategy` to control initialization-time cleanup. `keep-all` l
 
 ## Internal Flow
 
-For a detailed explanation of how the service worker intercepts requests, parses ZIP files, and handles caching, see the [Zip Service Worker Flow documentation](./docs/ZIP_SERVICE_WORKER_FLOW.md).
+For a detailed explanation of the modular service worker (`src/zipServiceWorker.ts` + `src/worker/*`), request interception, manifest fetching, entry extraction, allow-list behavior, and caching, see the [Zip Service Worker Flow documentation](./docs/ZIP_SERVICE_WORKER_FLOW.md).
 
 ## Limitations
 
@@ -402,4 +624,14 @@ For a detailed explanation of how the service worker intercepts requests, parses
 - The service worker can only intercept requests inside its registered scope.
 - Supported ZIP compression methods are stored (`0`) and deflated (`8`).
 - ZIP64 is not currently supported.
+- Ambiguous suffix path matches (e.g. two manifest keys ending in `/icon.png`) return 404.
+- Multi-range client requests are not supported (416).
 - The package is browser-only and depends on Service Worker, Cache API, and HTTP range request support.
+
+---
+
+## Further reading
+
+- [Medium-style article (HTML)](./docs/MEDIUM_POST.html) — animated diagrams
+- [Article (Markdown)](./docs/MEDIUM_POST.md) — same story as Markdown
+- [Zip service worker flow](./docs/ZIP_SERVICE_WORKER_FLOW.md)

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { InitZipPeekOptions, InitZipPeekResult } from "./types";
 import { isZipPackage } from "./zip-utils";
-export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, ZipWorkerConfig, } from "./types";
+export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipWorkerConfig, } from "./types";
 /**
  * Registers the zip-peek service worker and configures lazy ZIP asset loading.
  *
@@ -11,5 +11,5 @@ export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, Z
  * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
  * ZIP URLs, or clear all zip-peek cache entries before use.
  */
-export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
+export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
 export { isZipPackage };

package/dist/index.js

@@ -5,6 +5,46 @@ exports.initZipPeek = initZipPeek;
 const registerZipServiceWorker_1 = require("./registerZipServiceWorker");
 const zip_utils_1 = require("./zip-utils");
 Object.defineProperty(exports, "isZipPackage", { enumerable: true, get: function () { return zip_utils_1.isZipPackage; } });
+let currentOnError;
+let clientErrorListenerInstalled = false;
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function toZipPeekError(error, info) {
+    const err = toError(error);
+    if (info) {
+        err.zipPeekInfo = info;
+    }
+    return err;
+}
+function reportZipPeekError(onError, error, info) {
+    const err = toError(error);
+    onError?.(err, info ?? err.zipPeekInfo);
+}
+function errorFromWorkerResponse(response) {
+    const error = new Error(response.error ?? "zip-peek: service worker message failed.");
+    if (response.errorStack) {
+        error.stack = response.errorStack;
+    }
+    return error;
+}
+function ensureClientErrorListener() {
+    if (clientErrorListenerInstalled || !("serviceWorker" in navigator)) {
+        return;
+    }
+    clientErrorListenerInstalled = true;
+    navigator.serviceWorker.addEventListener("message", (event) => {
+        const data = event.data;
+        if (!data || data.type !== "ZIP_SW_ERROR" || !currentOnError) {
+            return;
+        }
+        const error = new Error(data.error?.message ?? "zip-peek: service worker error");
+        if (data.error?.stack) {
+            error.stack = data.error.stack;
+        }
+        currentOnError(error, data.info);
+    });
+}
 function normalizeAllowedZipUrls(allowedZipUrls) {
     if (allowedZipUrls === undefined) {
         return undefined;
@@ -18,7 +58,7 @@ function normalizeAllowedZipUrls(allowedZipUrls) {
         if (!(0, zip_utils_1.isZipPackage)(resolvedZipUrl)) {
             throw new Error(`zip-peek: allowedZipUrls contains a non-ZIP URL: ${zipUrl}`);
         }
-        normalized.add((0, zip_utils_1.normalizeZipUrlForSw)(resolvedZipUrl));
+        normalized.add((0, zip_utils_1.normalizeZipUrl)(resolvedZipUrl));
     }
     return Array.from(normalized);
 }
@@ -36,7 +76,7 @@ function postWorkerMessage(message) {
                 resolve();
             }
             else {
-                reject(new Error(response.error ?? "zip-peek: service worker message failed."));
+                reject(errorFromWorkerResponse(response));
             }
         };
         channel.port1.onmessageerror = () => {
@@ -46,6 +86,14 @@ function postWorkerMessage(message) {
         controller.postMessage(message, [channel.port2]);
     });
 }
+async function postWorkerMessageOrThrow(message, info) {
+    try {
+        await postWorkerMessage(message);
+    }
+    catch (error) {
+        throw toZipPeekError(error, info);
+    }
+}
 /**
  * Registers the zip-peek service worker and configures lazy ZIP asset loading.
  *
@@ -56,38 +104,36 @@ function postWorkerMessage(message) {
  * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
  * ZIP URLs, or clear all zip-peek cache entries before use.
  */
-async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, }) {
-    const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
-    if (cacheClearingStrategy === "keep-allowed-urls" &&
-        !normalizedAllowedZipUrls) {
-        throw new Error('zip-peek: cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.');
+async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, }) {
+    if (onError) {
+        currentOnError = onError;
+        ensureClientErrorListener();
     }
-    if (!("serviceWorker" in navigator)) {
-        console.warn("zip-peek: Service Worker API not supported.");
-        return { reloaded: false, initialized: false };
-    }
-    const reloaded = await (0, registerZipServiceWorker_1.ensureZipServiceWorkerRegistered)({
-        workerUrl,
-        scopeUrl,
-        reloadOnFirstInstall,
-    });
-    if (reloaded) {
-        return { reloaded: true, initialized: false };
-    }
-    await postWorkerMessage({
-        type: "ZIP_SW_CONFIG",
-        config: {
-            zipAssetCacheName,
-            assetCacheTtlMs,
-            logPrefix,
-            allowedZipUrls: normalizedAllowedZipUrls ?? null,
-        },
-    });
-    if (cacheClearingStrategy === "clear-all") {
-        await postWorkerMessage({
-            type: "CLEAR_ALL_ZIP_ASSETS",
-        });
-        await postWorkerMessage({
+    try {
+        const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
+        if (cacheClearingStrategy === "keep-allowed-urls" &&
+            !normalizedAllowedZipUrls) {
+            throw new Error('zip-peek: cacheClearingStrategy "keep-allowed-urls" requires a non-empty allowedZipUrls allow-list.');
+        }
+        if (!("serviceWorker" in navigator)) {
+            console.warn("zip-peek: Service Worker API not supported.");
+            return { reloaded: false, initialized: false };
+        }
+        let reloaded;
+        try {
+            reloaded = await (0, registerZipServiceWorker_1.ensureZipServiceWorkerRegistered)({
+                workerUrl,
+                scopeUrl,
+                reloadOnFirstInstall,
+            });
+        }
+        catch (error) {
+            throw toZipPeekError(error, "zip-peek: service worker registration failed");
+        }
+        if (reloaded) {
+            return { reloaded: true, initialized: false };
+        }
+        await postWorkerMessageOrThrow({
             type: "ZIP_SW_CONFIG",
             config: {
                 zipAssetCacheName,
@@ -95,20 +141,38 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                 logPrefix,
                 allowedZipUrls: normalizedAllowedZipUrls ?? null,
             },
-        });
-    }
-    else if (cacheClearingStrategy === "keep-allowed-urls" &&
-        normalizedAllowedZipUrls) {
-        await postWorkerMessage({
-            type: "CLEAR_ZIP_ASSETS_EXCEPT_ALLOWED",
-            allowedZipUrls: normalizedAllowedZipUrls,
-        });
+        }, "zip-peek: failed to configure service worker");
+        if (cacheClearingStrategy === "clear-all") {
+            await postWorkerMessageOrThrow({
+                type: "CLEAR_ALL_ZIP_ASSETS",
+            }, "zip-peek: failed to clear zip assets");
+            await postWorkerMessageOrThrow({
+                type: "ZIP_SW_CONFIG",
+                config: {
+                    zipAssetCacheName,
+                    assetCacheTtlMs,
+                    logPrefix,
+                    allowedZipUrls: normalizedAllowedZipUrls ?? null,
+                },
+            }, "zip-peek: failed to reconfigure service worker after cache clear");
+        }
+        else if (cacheClearingStrategy === "keep-allowed-urls" &&
+            normalizedAllowedZipUrls) {
+            await postWorkerMessageOrThrow({
+                type: "CLEAR_ZIP_ASSETS_EXCEPT_ALLOWED",
+                allowedZipUrls: normalizedAllowedZipUrls,
+            }, "zip-peek: failed to clear disallowed zip assets");
+        }
+        if (normalizedAllowedZipUrls) {
+            await postWorkerMessageOrThrow({
+                type: "PRELOAD_ZIP_MANIFESTS",
+                allowedZipUrls: normalizedAllowedZipUrls,
+            }, "zip-peek: failed to preload zip manifests");
+        }
+        return { reloaded: false, initialized: true };
     }
-    if (normalizedAllowedZipUrls) {
-        await postWorkerMessage({
-            type: "PRELOAD_ZIP_MANIFESTS",
-            allowedZipUrls: normalizedAllowedZipUrls,
-        });
+    catch (error) {
+        reportZipPeekError(onError, error);
+        throw error;
     }
-    return { reloaded: false, initialized: true };
 }

package/dist/registerZipServiceWorker.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureZipServiceWorkerRegistered = ensureZipServiceWorkerRegistered;
 function normalizeScopePath(href) {
     let p = new URL(href).pathname;
-    if (p.length > 1 && p.endsWith('/')) {
+    if (p.length > 1 && p.endsWith("/")) {
         p = p.slice(0, -1);
     }
     return p;
@@ -62,7 +62,7 @@ async function unregisterMismatchedScopeZipServiceWorkerIfNeeded(expectedWorkerU
  * @returns true if the page is reloading and callers should abort init.
  */
 async function ensureZipServiceWorkerRegistered({ workerUrl, scopeUrl, reloadOnFirstInstall = true, }) {
-    if (!('serviceWorker' in navigator)) {
+    if (!("serviceWorker" in navigator)) {
         return false;
     }
     await unregisterMismatchedScopeZipServiceWorkerIfNeeded(workerUrl, scopeUrl);
@@ -73,10 +73,10 @@ async function ensureZipServiceWorkerRegistered({ workerUrl, scopeUrl, reloadOnF
             zipServiceWorkerScriptMatches(existing.installing?.scriptURL, workerUrl));
     if (!alreadyRegistered) {
         await navigator.serviceWorker.register(workerUrl, { scope: scopeUrl });
-        console.log('Zip service worker registered successfully');
+        console.log("Zip service worker registered successfully");
     }
     else {
-        console.log('Zip service worker already registered; skipping register().');
+        console.log("Zip service worker already registered; skipping register().");
     }
     await navigator.serviceWorker.ready;
     if (reloadOnFirstInstall && !navigator.serviceWorker.controller) {

package/dist/types.d.ts

@@ -4,6 +4,7 @@ export type ZipWorkerConfig = {
     logPrefix?: string;
 };
 export type ZipCacheClearingStrategy = 'keep-all' | 'keep-allowed-urls' | 'clear-all';
+export type ZipPeekErrorHandler = (error: Error, info?: string) => void;
 export type InitZipPeekOptions = {
     workerUrl: string;
     scopeUrl: string;
@@ -13,6 +14,7 @@ export type InitZipPeekOptions = {
     zipAssetCacheName?: string;
     assetCacheTtlMs?: number;
     logPrefix?: string;
+    onError?: ZipPeekErrorHandler;
 };
 export type InitZipPeekResult = {
     reloaded: boolean;
@@ -21,4 +23,5 @@ export type InitZipPeekResult = {
 export type WorkerMessageResponse = {
     ok: boolean;
     error?: string;
+    errorStack?: string;
 };

package/dist/zip-utils.d.ts

@@ -1,13 +1,17 @@
 /** True when the URL points at a `.zip` package (path ends with `.zip`). */
 export declare function isZipPackage(url: string): boolean;
+export type NormalizeZipUrlOptions = {
+    /** Remove cache-buster `t` query param (default: true). */
+    stripCacheBuster?: boolean;
+    /** Drop fragment `#...` (default: true). */
+    stripHash?: boolean;
+};
 /**
- * Strip only the `t` cache-buster query param; keep everything else verbatim.
+ * Normalize a ZIP package URL for cache keys, allow-lists, and manifests.
  * Avoids `URL` / `URLSearchParams` so SigV4 values (e.g. `%2F` in credentials)
  * are not re-encoded.
  */
-export declare function stripTParam(urlString: string): string;
-/** Same key the service worker uses for manifests / purge (presigned query kept). */
-export declare const normalizeZipUrlForSw: typeof stripTParam;
+export declare function normalizeZipUrl(urlString: string, options?: NormalizeZipUrlOptions): string;
 /** Align zip entry names with URL paths under `*.zip/…`. */
 export declare function normalizeZipEntryPath(name: string): string;
 export type ParsedZipAssetRequest = {
@@ -24,5 +28,5 @@ export type ParsedZipAssetRequest = {
  * Returns `null` for bare `.zip` GETs (e.g. manifest bootstrap).
  */
 export declare function parseZipAssetRequest(urlString: string): ParsedZipAssetRequest | null;
-/** Cache key for a zip asset (decoded manifest key + zip URL without `t`). */
+/** Cache key for a zip asset (decoded manifest key + normalized zip URL). */
 export declare function canonicalZipAssetRequestUrl(zipUrl: string, manifestKey: string): string;