zip-peek 0.5.0 → 0.6.1

package/README.md

@@ -1,257 +1,34 @@
 # zip-peek
 
-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.
+`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.
 
-*We thought browsers could never use a ZIP bucket without killing performance. We were wrong—and zip-peek is how we proved it.*
+It registers a service worker that intercepts requests like:
 
----
-
-## 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
+```text
+https://cdn.example.com/packages/session.zip/path/to/asset.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.
 
-## What `zip-peek` does for our web app
+## When Is This Package Useful?
 
-`zip-peek` registers a **service worker** that intercepts requests like:
+Use this package when your app receives a base path and later appends folders and file names to fetch assets from that path.
 
-```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:
+For example, your app may normally treat the base path as a directory:
 
 ```ts
-// Before (unzipped bucket)
 const basePath = "https://cdn.example.com/packages/session";
-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`;
+const imageUrl = `${basePath}/slides/slide-1/image.png`;
 ```
 
-`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`, and configure **CORS** (S3 `ExposeHeaders` for `Content-Range` / `Accept-Ranges`, plus CloudFront `GET`/`HEAD`/`OPTIONS` with CORS preflight and **CORS-S3Origin** when applicable).
-
-**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:
+If the same assets are sometimes delivered as a ZIP file instead:
 
 ```ts
-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
-```
-
-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
+const basePath = "https://cdn.example.com/packages/session.zip";
+const imageUrl = `${basePath}/slides/slide-1/image.png`;
 ```
 
----
-
-## 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`).
-- **CORS** must allow cross-origin `Range` requests: S3 `ExposeHeaders` must include **`Content-Range`** and **`Accept-Ranges`**; CloudFront behaviors must allow **`GET`**, **`HEAD`**, and **`OPTIONS`**, use **CORS-S3Origin**, and enable **CORS with preflight** on the response headers policy.
-- 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
+`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.
 
 ## What It Does
 
@@ -479,25 +256,19 @@ In the S3 console, open the ZIP bucket → **Permissions** → **Cross-origin re
   {
     "AllowedHeaders": ["*"],
     "AllowedMethods": ["GET", "HEAD"],
-    "AllowedOrigins": [
-      "https://your-app.example.com",
-      "http://localhost:3000"
-    ],
-    "ExposeHeaders": [
-      "Content-Range",
-      "Accept-Ranges"
-    ]
+    "AllowedOrigins": ["https://your-app.example.com", "http://localhost:3000"],
+    "ExposeHeaders": ["Content-Range", "Accept-Ranges"]
   }
 ]
 ```
 
 **Required for zip-peek:**
 
-| Setting | Why |
-|--------|-----|
-| `AllowedHeaders: ["*"]` | Allows the `Range` request header (triggers preflight). |
-| `AllowedMethods`: `GET`, `HEAD` | Manifest and asset reads. |
-| `AllowedOrigins` | Must include your app origin(s). Use `*` only for quick local testing. |
+| Setting                                                   | Why                                                                                                                         |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `AllowedHeaders: ["*"]`                                   | Allows the `Range` request header (triggers preflight).                                                                     |
+| `AllowedMethods`: `GET`, `HEAD`                           | Manifest and asset reads.                                                                                                   |
+| `AllowedOrigins`                                          | Must include your app origin(s). Use `*` only for quick local testing.                                                      |
 | `ExposeHeaders`: **`Content-Range`**, **`Accept-Ranges`** | The service worker reads `Content-Range` when parsing the ZIP index. These two headers are **required** in `ExposeHeaders`. |
 
 S3 answers `OPTIONS` preflight automatically when CORS is configured; you do not list `OPTIONS` in `AllowedMethods`.
@@ -638,10 +409,7 @@ For example, after resolving the emitted filename:
 
 ```ts
 await initZipPeek({
-  workerUrl: new URL(
-    `/assets/${zipServiceWorkerFilename}`,
-    window.location.origin,
-  ).href,
+  workerUrl: new URL(`/assets/${zipServiceWorkerFilename}`, window.location.origin).href,
   scopeUrl: new URL("/", window.location.origin).href,
 });
 ```
@@ -718,11 +486,3 @@ For a detailed explanation of the modular service worker (`src/zipServiceWorker.
 - Manifest entry fallback prepends the ZIP basename only (e.g. `session/icon.png` for `session.zip`); generic `*/filename` suffix matching is not used.
 - 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,7 @@
-import type { InitZipPeekOptions, InitZipPeekResult } from "./types";
+import type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions } from "./types";
 import { isZipPackage } from "./zip-utils";
-export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipWorkerConfig, } from "./types";
+export type { InitZipPeekOptions, InitZipPeekResult, RenewPresignedUrlOptions, ZipCacheClearingStrategy, ZipPeekErrorHandler, ZipPeekUrlExpiryHandler, ZipWorkerConfig, } from "./types";
+export { getPresignedUrlExpiryMs } from "./zip-utils";
 /**
  * Registers the zip-peek service worker and configures lazy ZIP asset loading.
  *
@@ -10,6 +11,15 @@ export type { InitZipPeekOptions, InitZipPeekResult, ZipCacheClearingStrategy, Z
  * package URLs and warm their manifests during initialization. Use
  * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
  * ZIP URLs, or clear all zip-peek cache entries before use.
+ *
+ * When `onUrlExpiry` is provided and an allowed URL is a recognized presigned
+ * URL, zip-peek invokes the handler shortly before expiry and re-checks on tab
+ * wake (`visibilitychange`, `pageshow`, `focus`) after sleep or backgrounding.
+ */
+export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, 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.
  */
-export declare function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall, cacheClearingStrategy, allowedZipUrls, requireExactManifestPath, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, }: InitZipPeekOptions): Promise<InitZipPeekResult>;
+export declare function renewPresignedUrl({ previousUrl, nextUrl }: RenewPresignedUrlOptions): Promise<void>;
 export { isZipPackage };

package/dist/index.js

@@ -1,12 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isZipPackage = void 0;
+exports.isZipPackage = exports.getPresignedUrlExpiryMs = void 0;
 exports.initZipPeek = initZipPeek;
+exports.renewPresignedUrl = renewPresignedUrl;
 const types_1 = require("./types");
 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; } });
+/** Default lead time before presigned URL expiry when scheduling renewal. */
+const URL_EXPIRY_LEAD_MS = 10000;
 let currentOnError;
+let currentOnUrlExpiry;
 let clientMessageListenerInstalled = false;
+let expiryWakeListenersInstalled = false;
+/** Timers keyed by normalized zip URL. */
+const urlExpiryTimers = new Map();
+/** Original resolved URLs for expiry parsing, keyed by normalized zip URL. */
+const trackedZipUrls = new Map();
+/** Guard concurrent onUrlExpiry invocations per zip URL. */
+const urlExpiryInFlight = new Set();
 const sessionManifests = new Map();
 function normalizeScopePath(href) {
     let p = new URL(href).pathname;
@@ -101,6 +114,77 @@ function errorFromWorkerResponse(response) {
     }
     return error;
 }
+function clearUrlExpiryTimer(normalizedZipUrl) {
+    const existing = urlExpiryTimers.get(normalizedZipUrl);
+    if (existing !== undefined) {
+        clearTimeout(existing);
+        urlExpiryTimers.delete(normalizedZipUrl);
+    }
+}
+function scheduleUrlExpiry(normalizedZipUrl, originalUrlForExpiry) {
+    clearUrlExpiryTimer(normalizedZipUrl);
+    trackedZipUrls.set(normalizedZipUrl, originalUrlForExpiry);
+    if (!currentOnUrlExpiry) {
+        return;
+    }
+    const expiryMs = (0, zip_utils_1.getPresignedUrlExpiryMs)(originalUrlForExpiry);
+    if (expiryMs == null) {
+        trackedZipUrls.delete(normalizedZipUrl);
+        return;
+    }
+    const delayMs = Math.max(0, expiryMs - Date.now() - URL_EXPIRY_LEAD_MS);
+    const timerId = setTimeout(() => {
+        urlExpiryTimers.delete(normalizedZipUrl);
+        void invokeUrlExpiry(normalizedZipUrl);
+    }, delayMs);
+    urlExpiryTimers.set(normalizedZipUrl, timerId);
+}
+function isZipUrlDueForRenewal(originalUrl) {
+    const expiryMs = (0, zip_utils_1.getPresignedUrlExpiryMs)(originalUrl);
+    if (expiryMs == null) {
+        return false;
+    }
+    return expiryMs - Date.now() <= URL_EXPIRY_LEAD_MS;
+}
+function checkExpiryOnWake() {
+    if (typeof document !== "undefined" && document.visibilityState !== "visible") {
+        return;
+    }
+    if (!currentOnUrlExpiry) {
+        return;
+    }
+    for (const [normalized, original] of trackedZipUrls) {
+        if (isZipUrlDueForRenewal(original)) {
+            void invokeUrlExpiry(normalized);
+            return;
+        }
+        scheduleUrlExpiry(normalized, original);
+    }
+}
+function ensureExpiryWakeListeners() {
+    if (expiryWakeListenersInstalled || typeof document === "undefined") {
+        return;
+    }
+    expiryWakeListenersInstalled = true;
+    document.addEventListener("visibilitychange", checkExpiryOnWake);
+    window.addEventListener("pageshow", checkExpiryOnWake);
+    window.addEventListener("focus", checkExpiryOnWake);
+}
+async function invokeUrlExpiry(normalizedZipUrl) {
+    if (!currentOnUrlExpiry || urlExpiryInFlight.has(normalizedZipUrl)) {
+        return;
+    }
+    urlExpiryInFlight.add(normalizedZipUrl);
+    try {
+        await currentOnUrlExpiry();
+    }
+    catch (error) {
+        reportZipPeekError(currentOnError, error, "onUrlExpiry handler failed");
+    }
+    finally {
+        urlExpiryInFlight.delete(normalizedZipUrl);
+    }
+}
 function ensureClientMessageListener() {
     if (clientMessageListenerInstalled || !("serviceWorker" in navigator)) {
         return;
@@ -194,11 +278,18 @@ async function postWorkerMessageOrThrow(message, info) {
  * package URLs and warm their manifests during initialization. Use
  * `cacheClearingStrategy` to keep existing cache entries, keep only allowed
  * ZIP URLs, or clear all zip-peek cache entries before use.
+ *
+ * When `onUrlExpiry` is provided and an allowed URL is a recognized presigned
+ * URL, zip-peek invokes the handler shortly before expiry and re-checks on tab
+ * wake (`visibilitychange`, `pageshow`, `focus`) after sleep or backgrounding.
  */
-async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, requireExactManifestPath = false, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, }) {
+async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, cacheClearingStrategy = "keep-all", allowedZipUrls, requireExactManifestPath = false, zipAssetCacheName, assetCacheTtlMs, logPrefix, onError, onUrlExpiry, }) {
     if (onError) {
         currentOnError = onError;
     }
+    if (onUrlExpiry) {
+        currentOnUrlExpiry = onUrlExpiry;
+    }
     try {
         const normalizedAllowedZipUrls = normalizeAllowedZipUrls(allowedZipUrls);
         if (cacheClearingStrategy === "keep-allowed-urls" && !normalizedAllowedZipUrls) {
@@ -260,6 +351,17 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
                 allowedZipUrls: normalizedAllowedZipUrls,
             }, "Failed to preload ZIP manifests");
         }
+        if (onUrlExpiry && allowedZipUrls) {
+            ensureExpiryWakeListeners();
+            // Schedule from the original (pre-set-dedupe) URLs so query params used
+            // for expiry parsing are retained; timers are keyed by normalized form.
+            for (const zipUrl of allowedZipUrls) {
+                const resolvedZipUrl = new URL(zipUrl, window.location.href).href;
+                if ((0, zip_utils_1.isZipPackage)(resolvedZipUrl)) {
+                    scheduleUrlExpiry((0, zip_utils_1.normalizeZipUrl)(resolvedZipUrl), resolvedZipUrl);
+                }
+            }
+        }
         return { reloaded: false, initialized: true };
     }
     catch (error) {
@@ -267,3 +369,32 @@ async function initZipPeek({ workerUrl, scopeUrl, reloadOnFirstInstall = true, c
         throw error;
     }
 }
+/**
+ * Replace a presigned ZIP package URL after renewal so the service worker
+ * continue serving assets with the new credentials.
+ */
+async function renewPresignedUrl({ previousUrl, nextUrl }) {
+    if (!("serviceWorker" in navigator)) {
+        throw (0, types_1.createZipPeekError)("Service Worker API not supported in this browser.");
+    }
+    const resolvedPrevious = new URL(previousUrl, window.location.href).href;
+    const resolvedNext = 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.");
+    }
+    const previous = (0, zip_utils_1.normalizeZipUrl)(resolvedPrevious);
+    const next = (0, zip_utils_1.normalizeZipUrl)(resolvedNext);
+    await postWorkerMessageOrThrow({
+        type: "RENEW_ZIP_URL",
+        previousUrl: previous,
+        nextUrl: next,
+    }, "Failed to renew ZIP URL in service worker");
+    const files = sessionManifests.get(previous);
+    if (files) {
+        sessionManifests.set(next, files);
+        sessionManifests.delete(previous);
+    }
+    trackedZipUrls.delete(previous);
+    clearUrlExpiryTimer(previous);
+    scheduleUrlExpiry(next, resolvedNext);
+}

package/dist/types.d.ts

@@ -5,6 +5,11 @@ export type ZipWorkerConfig = {
 };
 export type ZipCacheClearingStrategy = 'keep-all' | 'keep-allowed-urls' | 'clear-all';
 export type ZipPeekErrorHandler = (error: Error, info?: string) => void;
+export type ZipPeekUrlExpiryHandler = () => void | Promise<void>;
+export type RenewPresignedUrlOptions = {
+    previousUrl: string;
+    nextUrl: string;
+};
 export type InitZipPeekOptions = {
     workerUrl: string;
     scopeUrl: string;
@@ -16,6 +21,13 @@ export type InitZipPeekOptions = {
     assetCacheTtlMs?: number;
     logPrefix?: string;
     onError?: ZipPeekErrorHandler;
+    /**
+     * Called shortly before a recognized presigned URL expires (CloudFront
+     * `Expires` or S3 `X-Amz-Date` + `X-Amz-Expires`). Also invoked after tab
+     * wake when a timer was missed due to sleep or background throttling.
+     * Not scheduled for non-presigned ZIP URLs.
+     */
+    onUrlExpiry?: ZipPeekUrlExpiryHandler;
 };
 export type InitZipPeekResult = {
     reloaded: boolean;

package/dist/zip-utils.d.ts

@@ -32,3 +32,9 @@ export type ParsedZipAssetRequest = {
 export declare function parseZipAssetRequest(urlString: string): ParsedZipAssetRequest | null;
 /** Cache key for a zip asset (decoded manifest key + normalized zip URL). */
 export declare function canonicalZipAssetRequestUrl(zipUrl: string, manifestKey: string): string;
+/**
+ * Parse CloudFront `Expires` or S3 `X-Amz-Date` + `X-Amz-Expires` into an
+ * absolute expiry time in ms. Returns `null` when the URL is not recognized
+ * as a time-limited presigned URL.
+ */
+export declare function getPresignedUrlExpiryMs(url: string): number | null;

package/dist/zip-utils.js

@@ -6,6 +6,7 @@ exports.zipBasenameWithoutExtension = zipBasenameWithoutExtension;
 exports.normalizeZipEntryPath = normalizeZipEntryPath;
 exports.parseZipAssetRequest = parseZipAssetRequest;
 exports.canonicalZipAssetRequestUrl = canonicalZipAssetRequestUrl;
+exports.getPresignedUrlExpiryMs = getPresignedUrlExpiryMs;
 /** True when the URL points at a `.zip` package (path ends with `.zip`). */
 function isZipPackage(url) {
     try {
@@ -116,3 +117,58 @@ function parseZipAssetRequest(urlString) {
 function canonicalZipAssetRequestUrl(zipUrl, manifestKey) {
     return zipUrl + "/" + encodeURIComponent(manifestKey);
 }
+/**
+ * Read a raw query param value without `URLSearchParams` so SigV4 `%2F`
+ * credentials are not re-encoded.
+ */
+function getRawQueryParam(urlString, name) {
+    const qIdx = urlString.indexOf("?");
+    if (qIdx === -1)
+        return null;
+    const hashIdx = urlString.indexOf("#", qIdx);
+    const querySection = hashIdx === -1
+        ? urlString.substring(qIdx + 1)
+        : urlString.substring(qIdx + 1, hashIdx);
+    // Presigned ZIP asset requests put the inner path after the query
+    // (`pkg.zip?sig…/asset.png`). Stop at the first raw `/`.
+    const slashIdx = querySection.indexOf("/");
+    const signedQuery = slashIdx === -1 ? querySection : querySection.substring(0, slashIdx);
+    for (const part of signedQuery.split("&")) {
+        const eqIdx = part.indexOf("=");
+        const k = eqIdx === -1 ? part : part.substring(0, eqIdx);
+        if (k === name) {
+            return eqIdx === -1 ? "" : part.substring(eqIdx + 1);
+        }
+    }
+    return null;
+}
+/**
+ * Parse CloudFront `Expires` or S3 `X-Amz-Date` + `X-Amz-Expires` into an
+ * absolute expiry time in ms. Returns `null` when the URL is not recognized
+ * as a time-limited presigned URL.
+ */
+function getPresignedUrlExpiryMs(url) {
+    const expiresRaw = getRawQueryParam(url, "Expires");
+    if (expiresRaw != null && expiresRaw !== "") {
+        const expiresSec = Number(expiresRaw);
+        if (Number.isFinite(expiresSec) && expiresSec > 0) {
+            return expiresSec * 1000;
+        }
+    }
+    const amzDate = getRawQueryParam(url, "X-Amz-Date");
+    const amzExpires = getRawQueryParam(url, "X-Amz-Expires");
+    if (amzDate && amzExpires) {
+        // X-Amz-Date is YYYYMMDD'T'HHMMSS'Z'
+        const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/.exec(amzDate);
+        if (!match)
+            return null;
+        const [, y, mo, d, h, mi, s] = match;
+        const startMs = Date.UTC(Number(y), Number(mo) - 1, Number(d), Number(h), Number(mi), Number(s));
+        const durationSec = Number(amzExpires);
+        if (!Number.isFinite(startMs) || !Number.isFinite(durationSec) || durationSec <= 0) {
+            return null;
+        }
+        return startMs + durationSec * 1000;
+    }
+    return null;
+}