npm - @africanpilot/next-snapshot - Versions diffs - 0.1.2 → 0.2.1 - Mend

@africanpilot/next-snapshot 0.1.2 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md CHANGED Viewed

@@ -106,9 +106,40 @@ A config is an ES module; relative paths resolve against it.
 | `offline.missingLinks` | `"show"` | Links to pages the snapshot does not hold: `"show"` (they open a "not in snapshot" page), `"disable"` (dimmed, not clickable) or `"hide"`. With `include` narrowing the crawl, `"hide"` removes the nav entries for everything left out. |
 | `offline.badge` | `"bottom-right"` | The "Offline snapshot" pill; `false` to hide. |
 | `offline.switcher` | `true` | A variant `<select>` in the badge. |
+| `compress` | `"gzip"` | How pages are packed. `"gzip"` stores each page on its own, decoded by the browser itself. `"zstd"` sorts pages by route, packs them into clusters of `clusterBytes` and compresses each cluster as one stream, inlining an 8 KB decoder — far smaller for an app with many similar pages. See [Size](#size-and-compression). |
+| `clusterBytes` | 4 MB | Raw bytes of pages per cluster, with `compress: "zstd"`. Bigger is smaller, but the first page of each cluster takes longer to open. |
 | `includeStatic` | `true` | Also embed every file under `.next/static`, so lazily-loaded chunks the crawl never triggered are present. |
 | `viewport`, `locale`, `timezoneId`, `browser` | | Passed to Chrome. `browser.executablePath` if Chrome is not installed. |
+## Size and compression
+Pages of an app repeat each other: the same layout, nav and table shell, over
+and over. By default each page is gzipped on its own, which cannot exploit that
+— gzip looks only 32 KB back, and a page's near-twin is further away than that.
+For a handful of pages this costs nothing worth fixing.
+For an app with hundreds of pages, `compress: "zstd"` sorts pages by route,
+packs them into clusters and compresses each cluster as one stream, so the
+repetition is paid for once:
+```js
+export default {
+  // …
+  compress: "zstd",
+  clusterBytes: 4 * 1024 * 1024,   // the default
+};
+```
+On a 260-page report app, measured: **12.4 MB → about 2 MB**. The cost is an
+8 KB decoder inlined in the file, and tens of milliseconds to open the first
+page of a cluster; pages in an already-decoded cluster are free. Assets stay
+per-page gzip either way, since they are wanted all at once at startup and are
+mostly already-compressed formats.
+Why not brotli, which is smaller still: Chrome cannot decompress brotli from
+JavaScript (`DecompressionStream` has no brotli there, and no zstd anywhere), so
+it would mean inlining a 208 KB decoder to save about 10%.
 ## An app running in Docker
 The tool drives Chrome on your machine, so it reaches the container the same way
@@ -164,14 +195,18 @@ other host it redirects to, add it to `aliases`.
 ## Security
 A config is code: `app.build`, `app.start`, `login` hooks and `explore.custom`
-run with your privileges. A snapshot contains every page it captured, for every
-variant — treat it like access to the app. See [SECURITY.md](SECURITY.md),
-including how to report a vulnerability.
+run with your privileges. A snapshot contains every page it captured, and the
+API responses those pages fetched, for every variant — treat it like access to
+the app, and check what is in it before sharing. Replayed pages run in a
+sandboxed frame so that content the app never trusted cannot carry the snapshot
+anywhere. See [SECURITY.md](SECURITY.md), including how to report a
+vulnerability.
 ## Development
 `npm test` runs the unit and end-to-end suites; `npm run test:next` snapshots a
-real Next.js app. See [CONTRIBUTING.md](CONTRIBUTING.md).
+real Next.js app. See [CONTRIBUTING.md](CONTRIBUTING.md). What might come next,
+and what was deliberately ruled out, is in [docs/ROADMAP.md](docs/ROADMAP.md).
 ## License

package/lib/bundle.mjs CHANGED Viewed

@@ -6,12 +6,25 @@
 //         real URL and a placeholder for the frame shim go first in <head>.
 //   (The transformations themselves live in rewrite.mjs.)
 //
-// Every body is gzipped and base64'd into its own inert <script type=text/plain>.
-// The runtime (runtime/shell.js) decodes assets once into blob: URLs, replaces
-// tokens with them, and decodes a page only when it is navigated to.
+// Every body is then packed into the file as base64 in an inert
+// <script type="text/plain">, one of two ways:
+//
+//   compress: "gzip"  each body gzipped on its own. The browser decodes it
+//                     natively, and the file needs no decoder of its own.
+//   compress: "zstd"  pages are sorted by route and packed into clusters of
+//                     `clusterBytes`, each compressed as one zstd stream, with
+//                     a small decoder inlined. Pages of an app repeat each
+//                     other heavily and gzip's window is only 32KB, so a page
+//                     cannot see its near-twin; a cluster can. Assets stay
+//                     per-body gzip: they are wanted all at once at startup,
+//                     and most are already-compressed formats.
+//
+// The runtime (runtime/shell.js) decodes an asset once into a blob: URL, and a
+// page only when it is navigated to — a cluster at a time, cached.
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import zlib from "node:zlib";
@@ -20,6 +33,7 @@ import { urlKey } from "./key.js";
 import { createRewriter, escHTML, serialisePost, virtualiseLocation } from "./rewrite.mjs";
 const HERE = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
 // Nothing in the file may reach the network. Anything that tries is refused by
 // the browser and shows up as a CSP violation, which `verify` reports.
@@ -37,10 +51,26 @@ export const CSP = [
 ].join("; ");
 export async function bundle(cfg, log) {
-  const M = JSON.parse(await fs.readFile(path.join(cfg.captureDir, "manifest.json"), "utf8"));
+  let M;
+  try {
+    M = JSON.parse(await fs.readFile(path.join(cfg.captureDir, "manifest.json"), "utf8"));
+  } catch (e) {
+    throw new Error(
+      `No capture to bundle at ${cfg.captureDir} (${e.code ?? e.message}). Run \`capture\` first, or \`all\` to do both.`,
+    );
+  }
+  if (!M.pages || !M.assets || !M.variantAssets) {
+    throw new Error(`The capture at ${cfg.captureDir} is incomplete or was written by an older version. Run \`capture\` again.`);
+  }
   const origin = M.origin;
   const readBody = (sha) => fs.readFile(path.join(cfg.captureDir, "bodies", sha));
   const t0 = Date.now();
+  const zstd = cfg.compress === "zstd";
+  if (zstd && typeof zlib.zstdCompressSync !== "function") {
+    throw new Error(
+      `compress: "zstd" needs a Node built with zstd (zlib.zstdCompressSync); this is ${process.version}. Upgrade Node, or use compress: "gzip".`,
+    );
+  }
   // --- asset table ---------------------------------------------------------
   const assets = [];
@@ -74,18 +104,17 @@ export async function bundle(cfg, log) {
   });
   // --- bodies ---------------------------------------------------------------
-  const out = []; // id -> base64(gzip)
-  const outIndex = new Map(); // content hash -> id
-  const sizes = []; // {what, raw, packed}
-  function emit(buf, what) {
+  // Collected first, compressed at the end: how they are packed depends on all
+  // of them. Identical content is stored once, whatever refers to it.
+  const bodies = []; // id -> { buf, what, page }
+  const bodyIndex = new Map(); // content hash -> id
+  function emit(buf, what, page = false) {
     const h = crypto.createHash("sha256").update(buf).digest("hex");
-    let id = outIndex.get(h);
+    let id = bodyIndex.get(h);
     if (id == null) {
-      const packed = zlib.gzipSync(buf, { level: 9 }).toString("base64");
-      id = out.length;
-      out.push(packed);
-      outIndex.set(h, id);
-      sizes.push({ what, raw: buf.length, packed: packed.length });
+      id = bodies.length;
+      bodies.push({ buf, what, page });
+      bodyIndex.set(h, id);
     }
     return id;
   }
@@ -127,12 +156,58 @@ export async function bundle(cfg, log) {
         if (i >= 0) pagesOut[v][k] = { a: i };
       } else {
         const html = (await readBody(e.body)).toString("utf8");
-        pagesOut[v][k] = { b: emit(Buffer.from(rewriteHTML(html, k, v)), `page ${v} ${k}`), s: e.status };
+        pagesOut[v][k] = { b: emit(Buffer.from(rewriteHTML(html, k, v)), `page ${v} ${k}`, true), s: e.status };
         pageCount++;
       }
     }
   }
+  // --- packing ------------------------------------------------------------------
+  const gzipB64 = (buf) => zlib.gzipSync(buf, { level: 9 }).toString("base64");
+  const blocks = new Map(); // body id -> base64, for bodies stored on their own
+  const clusters = []; // base64 of each cluster
+  const locs = {}; // body id -> [cluster, offset, length], for clustered pages
+  let clusterRawMax = 0;
+  if (!zstd) {
+    for (let i = 0; i < bodies.length; i++) blocks.set(i, gzipB64(bodies[i].buf));
+  } else {
+    for (let i = 0; i < bodies.length; i++) if (!bodies[i].page) blocks.set(i, gzipB64(bodies[i].buf));
+    // Sorted by route and query, so a cluster holds pages that resemble each
+    // other — which is the whole reason a cluster is smaller than its parts.
+    const pageIds = bodies.map((b, i) => i).filter((i) => bodies[i].page).sort((x, y) => (bodies[x].what < bodies[y].what ? -1 : 1));
+    // A window at least as large as a cluster: a page must be able to match
+    // against any earlier page in the same cluster.
+    const windowLog = Math.min(27, Math.max(20, Math.ceil(Math.log2(Math.max(cfg.clusterBytes, 1)))));
+    let cur = [];
+    let size = 0;
+    const flush = () => {
+      if (!cur.length) return;
+      let offset = 0;
+      for (const i of cur) {
+        locs[i] = [clusters.length, offset, bodies[i].buf.length];
+        offset += bodies[i].buf.length;
+      }
+      const raw = Buffer.concat(cur.map((i) => bodies[i].buf));
+      clusterRawMax = Math.max(clusterRawMax, raw.length);
+      clusters.push(
+        zlib
+          .zstdCompressSync(raw, {
+            params: { [zlib.constants.ZSTD_c_compressionLevel]: 19, [zlib.constants.ZSTD_c_windowLog]: windowLog },
+          })
+          .toString("base64"),
+      );
+      cur = [];
+      size = 0;
+    };
+    for (const i of pageIds) {
+      if (cur.length && size + bodies[i].buf.length > cfg.clusterBytes) flush();
+      cur.push(i);
+      size += bodies[i].buf.length;
+    }
+    flush();
+  }
   // --- runtime + output ---------------------------------------------------------
   const frameSrc = await fs.readFile(path.join(HERE, "runtime", "frame.js"), "utf8");
   const shellSrc = (await fs.readFile(path.join(HERE, "runtime", "shell.js"), "utf8"))
@@ -152,6 +227,9 @@ export async function bundle(cfg, log) {
     badge: cfg.offline.badge,
     switcher: cfg.offline.switcher,
     missingLinks: cfg.offline.missingLinks,
+    staticPrefix: cfg.staticPrefix,
+    codec: zstd ? "zstd" : "gzip",
+    locs: zstd ? locs : undefined,
     assets: assets.map((a) => [a.k, a.v, a.b, a.type, a.status ?? 200]),
     pages: pagesOut,
   };
@@ -168,7 +246,9 @@ export async function bundle(cfg, log) {
     `<div id="no-loading">Opening ${title}…</div>`,
     `<script type="application/json" id="no-manifest">${JSON.stringify(manifestOut).replace(/</g, "\\u003c")}</script>`,
   ];
-  for (let i = 0; i < out.length; i++) parts.push(`<script type="text/plain" id="no-b${i}">${out[i]}</script>`);
+  for (const [id, b64] of blocks) parts.push(`<script type="text/plain" id="no-b${id}">${b64}</script>`);
+  for (let i = 0; i < clusters.length; i++) parts.push(`<script type="text/plain" id="no-c${i}">${clusters[i]}</script>`);
+  if (zstd) parts.push(`<script>${await inlineZstdDecoder()}</script>`);
   parts.push(`<script>${shellSrc.replace(/<\/script/gi, "<\\/script").replace(/<!--/g, "<\\!--")}</script>`);
   parts.push(`</body></html>\n`);
@@ -178,25 +258,58 @@ export async function bundle(cfg, log) {
   // --- report ----------------------------------------------------------------------
   const mb = (n) => (n / 1024 / 1024).toFixed(2) + " MB";
-  const pageBytes = sizes.filter((s) => s.what.startsWith("page")).reduce((n, s) => n + s.packed, 0);
-  const assetBytes = sizes.filter((s) => s.what.startsWith("asset")).reduce((n, s) => n + s.packed, 0);
+  // By body, not by asset row: one block shared by several keys is one cost.
+  const assetBytes = [...new Set(assets.map((a) => a.b))].reduce((n, b) => n + (blocks.get(b)?.length ?? 0), 0);
+  const pageBytes = zstd
+    ? clusters.reduce((n, c) => n + c.length, 0)
+    : bodies.reduce((n, b, i) => n + (b.page ? blocks.get(i).length : 0), 0);
   log("");
   log(`bundle finished in ${((Date.now() - t0) / 1000).toFixed(1)}s -> ${path.relative(process.cwd(), cfg.out)}`);
   log(`  file size        ${mb(html.length)}   (pages ${mb(pageBytes)}, assets ${mb(assetBytes)})`);
-  log(`  pages            ${pageCount} captured, ${out.length} unique bodies after dedupe`);
+  log(`  pages            ${pageCount} captured, ${bodies.filter((b) => b.page).length} unique bodies after dedupe`);
   log(`  assets           ${assets.length} (${jsRewritten} scripts with location virtualised)`);
-  const biggest = [...sizes].sort((a, b) => b.packed - a.packed).slice(0, 6);
-  log(`  largest bodies   ${biggest.map((s) => `${s.what.slice(0, 70)} ${mb(s.packed)}`).join("\n                   ")}`);
+  if (zstd) {
+    log(`  clusters         ${clusters.length} zstd, up to ${mb(clusterRawMax)} of pages each, decoded on demand`);
+  } else {
+    log(`  compression      gzip per page — try compress: "zstd" if this file is large`);
+  }
   if (missing.size) {
     const top = [...missing.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10);
     log(`  NOT CAPTURED     ${missing.size} referenced URL(s) will fail offline:`);
     for (const [k, n] of top) log(`                   ${k}  (${n}x)`);
   }
-  const report = { file: cfg.out, bytes: html.length, pageCount, bodies: out.length, missing: Object.fromEntries(missing), sizes };
+  const report = {
+    file: cfg.out,
+    bytes: html.length,
+    pageCount,
+    codec: manifestOut.codec,
+    clusters: clusters.length,
+    pageBytes,
+    assetBytes,
+    missing: Object.fromEntries(missing),
+  };
   await fs.writeFile(cfg.out.replace(/\.html?$/, "") + ".bundle.json", JSON.stringify(report, null, 1));
   return report;
 }
+/**
+ * fzstd's UMD build, which assigns a `fzstd` global when run as a plain script.
+ * Read by path rather than resolved: the package's exports map does not expose
+ * this build, and it is the only one that works inside the snapshot.
+ */
+async function inlineZstdDecoder() {
+  // Resolved through the package's main entry, then up to its directory: the
+  // exports map does not expose "./package.json" or "./umd/index.js", so
+  // neither can be resolved by subpath.
+  const pkg = path.dirname(path.dirname(require.resolve("fzstd")));
+  const umd = path.join(pkg, "umd", "index.js");
+  try {
+    return await fs.readFile(umd, "utf8");
+  } catch (e) {
+    throw new Error(`compress: "zstd" needs fzstd's UMD build at ${umd}, which is missing (${e.code}). Reinstall dependencies, or use compress: "gzip".`);
+  }
+}
 const SHELL_CSS = `
 html,body{margin:0;height:100%;overflow:hidden;background:#fff}
 .no-frame{position:fixed;inset:0;width:100%;height:100%;border:0;display:block;background:#fff}

package/lib/capture.mjs CHANGED Viewed

@@ -116,8 +116,11 @@ export async function capture(cfg, log) {
   const pending = new Set();
   const track = (p) => {
-    pending.add(p);
-    p.finally(() => pending.delete(p));
+    // Caught here: an unhandled rejection from a background body read (a full
+    // disk, too many open files) would otherwise end the whole crawl silently.
+    const q = p.catch((e) => log(`  warn: recording a response failed: ${e.message}`));
+    pending.add(q);
+    q.finally(() => pending.delete(q));
   };
   const browser = await launch(cfg);
@@ -567,6 +570,12 @@ function summarise(M, log, ms) {
     log(`  ${v.id.padEnd(22)} ${String(html).padStart(4)} pages  ${String(red).padStart(4)} redirects  ${Object.keys(M.variantAssets[v.id]).length} data responses`);
   }
   log(`  shared assets: ${Object.keys(M.assets).length}   RSC payloads skipped: ${M.rscSkipped}`);
+  // An app that is answering with error pages captures perfectly happily; say
+  // so, or the snapshot looks complete and is a book of 500s.
+  const errorPages = M.variants.flatMap((v) => Object.entries(M.pages[v.id]).filter(([, e]) => e.body && e.status >= 400));
+  if (errorPages.length) {
+    log(`  WARNING: ${errorPages.length} captured page(s) are error responses — e.g. ${errorPages[0][1].status} ${errorPages[0][0]}`);
+  }
   if (M.blocked.length) log(`  blocked ${M.blocked.length} non-GET request(s) — the crawl never writes`);
   if (M.failures.length) log(`  ${M.failures.length} navigation failure(s): ${M.failures.slice(0, 3).map((f) => f.key).join(", ")}`);
   if (M.liveErrors.length) log(`  the LIVE app threw ${M.liveErrors.length} error(s) during capture (first: ${M.liveErrors[0].message})`);

package/lib/config.mjs CHANGED Viewed

@@ -38,6 +38,9 @@ export async function loadConfig(file) {
     label: v.id,
     ...v,
   }));
+  const compress = raw.compress ?? "gzip";
+  if (compress !== "gzip" && compress !== "zstd") throw new Error(`compress must be "gzip" or "zstd", not ${JSON.stringify(compress)}`);
   const ids = new Set();
   for (const v of variants) {
     if (!/^[A-Za-z0-9_.-]+$/.test(v.id)) throw new Error(`Variant id "${v.id}" must be [A-Za-z0-9_.-]+`);
@@ -93,6 +96,17 @@ export async function loadConfig(file) {
     // `docker cp` it out before bundling. `staticPath` is where the build lives
     // inside the image (Next's own Dockerfile puts it under /app).
     docker: raw.docker ? { staticPath: "/app/.next/static", ...raw.docker } : null,
+    // How page bodies are packed into the file.
+    //
+    //   "gzip"  each page gzipped on its own, decoded by the browser itself.
+    //   "zstd"  pages of a route packed together into clusters and compressed
+    //           as one stream, with a small decoder inlined. Pages of an app
+    //           mostly repeat each other, and gzip's 32KB window cannot see
+    //           past one page — clustering is what makes a big app small.
+    compress,
+    // Raw bytes of pages per cluster, when clustering. Bigger is smaller but
+    // slower to open the first page of each cluster.
+    clusterBytes: raw.clusterBytes ?? 4 * 1024 * 1024,
     includeStatic: raw.includeStatic ?? true,
     staticDir: r(raw.staticDir) ?? defaultStatic,
     staticPrefix: raw.staticPrefix ?? "/_next/static/",

package/lib/runtime/frame.js CHANGED Viewed

@@ -291,7 +291,8 @@
       NO.openInNewTab(u.href);
       return null;
     }
-    return realOpen.call(W, u.href, target || "_blank", features);
+    NO.external(u.href);
+    return null;
   };
   var jar = NO.cookies;
   try {
@@ -322,7 +323,7 @@
     if (!/^https?:$/.test(u.protocol)) return;
     e.preventDefault();
     if (a.hasAttribute("download") || NO.isAsset(u.href)) { NO.openAsset(u.href, a.getAttribute("download")); return; }
-    if (u.origin !== cur.origin) { realOpen.call(W, u.href, "_blank", "noopener"); return; }
+    if (u.origin !== cur.origin) { NO.external(u.href); return; }
     var t = a.getAttribute("target");
     if (newTab || e.metaKey || e.ctrlKey || e.shiftKey || (t && !/^_(self|top|parent)$/i.test(t))) { NO.openInNewTab(u.href); return; }
     go(u.href);

package/lib/runtime/shell.js CHANGED Viewed

@@ -41,15 +41,39 @@
     for (var i = 0; i < n; i++) a[i] = bin.charCodeAt(i);
     return a;
   }
+  // Pages may be packed in clusters: many of them compressed as one stream,
+  // because pages of an app repeat each other and gzip cannot see past one
+  // page. A cluster is decoded on first use and the last few are kept.
+  var LOCS = M.locs || null;
+  var clusterCache = new Map();
+  function cluster(i) {
+    var hit = clusterCache.get(i);
+    if (hit) return hit;
+    var p = (async function () {
+      var el = document.getElementById("no-c" + i);
+      if (!el) throw new Error("snapshot cluster " + i + " is missing");
+      return fzstd.decompress(b64(el.textContent.trim()));
+    })();
+    clusterCache.set(i, p);
+    // Three decoded clusters is a few MB; older ones cost nothing to redo.
+    if (clusterCache.size > 3) clusterCache.delete(clusterCache.keys().next().value);
+    return p;
+  }
   var kept = {};
   function body(id, keep) {
     if (kept[id]) return kept[id];
-    var p = (async function () {
-      var el = document.getElementById("no-b" + id);
-      if (!el) throw new Error("snapshot body " + id + " is missing");
-      var stream = new Blob([b64(el.textContent.trim())]).stream().pipeThrough(new DecompressionStream("gzip"));
-      return new Uint8Array(await new Response(stream).arrayBuffer());
-    })();
+    var loc = LOCS && LOCS[id];
+    var p = loc
+      ? cluster(loc[0]).then(function (bytes) {
+          return bytes.subarray(loc[1], loc[1] + loc[2]);
+        })
+      : (async function () {
+          var el = document.getElementById("no-b" + id);
+          if (!el) throw new Error("snapshot body " + id + " is missing");
+          var stream = new Blob([b64(el.textContent.trim())]).stream().pipeThrough(new DecompressionStream("gzip"));
+          return new Uint8Array(await new Response(stream).arrayBuffer());
+        })();
     if (keep) kept[id] = p;
     return p;
   }
@@ -63,11 +87,15 @@
     idx[(a.v || "") + "\u0000" + a.k] = i;
   });
   var variant = M.defaultVariant;
+  // Where the build output lives, which basePath moves: the bundler and the
+  // runtime must agree, or a chunk with a query is found at bundle time and
+  // lost at read time.
+  var STATIC_PREFIX = M.staticPrefix || "/_next/static/";
   function lookup(key, v) {
     if (key == null) return -1;
     var i = idx[(v || "") + "\u0000" + key];
     if (i == null) i = idx["\u0000" + key];
-    if (i == null && key.indexOf("?") > 0 && key.indexOf("/_next/static/") === 0) i = idx["\u0000" + key.split("?")[0]];
+    if (i == null && key.indexOf("?") > 0 && key.indexOf(STATIC_PREFIX) === 0) i = idx["\u0000" + key.split("?")[0]];
     return i == null ? -1 : i;
   }
   var bytes = await Promise.all(A.map(function (a) { return body(a.b, true); }));
@@ -87,7 +115,12 @@
     return u;
   }
   function tokens(text) {
-    return text.replace(/__NOA(\d+)__/g, function (_, i) { return assetURL(+i); });
+    // A captured page may contain the token's own shape as ordinary text. An
+    // index that names no asset is left as it stands: one odd string in a page
+    // must not take down the file.
+    return text.replace(/__NOA(\d+)__/g, function (whole, i) {
+      return +i >= 0 && +i < A.length ? assetURL(+i) : whole;
+    });
   }
   for (var i = 0; i < A.length; i++) assetURL(i);
@@ -167,8 +200,20 @@
   }
   async function load(v, rawKey, hash, mode) {
+    try {
+      await loadPage(v, rawKey, hash, mode);
+    } catch (err) {
+      // A body that will not decode — a truncated file, a half-finished copy.
+      // Saying so beats leaving the reader on "Opening…" for ever.
+      NO.report("error", "could not open " + rawKey + ": " + ((err && err.message) || err));
+      current = { variant: variant, key: rawKey, hash: hash || "", base: rawKey };
+      mount(brokenHTML(rawKey, (err && err.message) || String(err)), NO.seq);
+    }
+  }
+  async function loadPage(v, rawKey, hash, mode) {
     var seq = ++NO.seq;
-    if (!M.pages[v]) v = M.defaultVariant;
+    if (!Object.prototype.hasOwnProperty.call(M.pages, v)) v = M.defaultVariant;
     setVariant(v);
     var r = resolvePage(rawKey, v), e = r.entry, html, base = r.key;
     if (!e && soft[v + "\u0000" + r.key]) {
@@ -192,6 +237,12 @@
     var f = document.createElement("iframe");
     f.className = "no-frame loading";
     f.setAttribute("title", M.title || "Application");
+    // A captured page may contain content its app never trusted — a comment
+    // field, a hostile API value — and its inline scripts run here. Same-origin
+    // is kept because the shim needs `parent.__NO`, but without top navigation
+    // or popups that content cannot carry the snapshot off to a server. Links
+    // that genuinely lead outside go through the shell instead (NO.external).
+    f.setAttribute("sandbox", "allow-scripts allow-same-origin allow-forms allow-modals");
     f.addEventListener("load", function () {
       NO.frameReady(f.contentWindow, seq);
       if (seq === NO.seq) {
@@ -252,6 +303,17 @@
     var u = new URL(href, ORIGIN);
     window.open(location.href.split("#")[0] + hashFor(variant, NO.key(u.href), u.hash), "_blank");
   };
+  // A link out of the app. The frame cannot open one itself — that is the point
+  // of its sandbox — so the shell asks, and the reader decides. Anything the
+  // page does without a click never gets here.
+  NO.external = function (href) {
+    var u;
+    try { u = new URL(href); } catch (e) { return; }
+    if (!/^https?:$/.test(u.protocol)) return;
+    if (window.confirm("This link leaves the offline snapshot and connects to the internet:\n\n" + u.href + "\n\nOpen it?")) {
+      window.open(u.href, "_blank", "noopener");
+    }
+  };
   NO.openAsset = function (href, name) {
     var i = NO.assetIndex(href);
     if (i >= 0) openAssetIndex(i, name);
@@ -394,6 +456,17 @@
   function esc(s) {
     return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
   }
+  function brokenHTML(key, why) {
+    return (
+      '<!doctype html><html><head><base href="' + esc(ORIGIN + key) + '"><script data-no-shim></script>' +
+      '<meta charset="utf-8"><title>This page could not be opened</title><style>body{font:14px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif;margin:48px auto;padding:0 24px;color:#222;max-width:720px}' +
+      "code{background:#f2f2f2;padding:1px 5px;border-radius:4px}</style></head><body>" +
+      '<h1 style="font-size:20px">This page could not be opened</h1><p><code>' + esc(key) + "</code> is in this snapshot, but its content would not decode:</p>" +
+      "<p><code>" + esc(why) + "</code></p>" +
+      "<p>The file is probably incomplete — a copy or download that did not finish. Try the original file again.</p></body></html>"
+    );
+  }
   function missingHTML(v, key) {
     var P = M.pages[v] || {}, path = key.split("?")[0];
     var pages = Object.keys(P).filter(function (k) { return P[k].b != null; }).sort();
@@ -414,7 +487,9 @@
   // --- boot ------------------------------------------------------------------------------------
   var start = parseHash();
-  if (start && M.pages[start.variant]) variant = start.variant;
+  // hasOwnProperty: a hash of "#__proto__:/" would otherwise name a variant
+  // that exists only on Object.prototype.
+  if (start && Object.prototype.hasOwnProperty.call(M.pages, start.variant)) variant = start.variant;
   renderBadge();
   NO.ready = true;
   if (start) load(variant, start.key, start.hash, "replace");

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@africanpilot/next-snapshot",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Capture a running Next.js app and bundle it into one self-contained, offline HTML file.",
   "keywords": [
     "nextjs",
@@ -45,6 +45,7 @@
   },
   "dependencies": {
     "esbuild": "^0.28.2",
+    "fzstd": "^0.1.1",
     "playwright-core": "~1.63.0"
   },
   "publishConfig": {