@africanpilot/next-snapshot 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,149 @@
+# next-snapshot
+
+Capture a running Next.js app and bundle it into **one HTML file** that opens
+from disk — double-click, `file://`, network off — and still behaves like the
+app: client components run, links and router navigation work, selects and tabs
+work, and every page shows the data it showed when captured.
+
+## Install
+
+Requires **Node 22+** and **Google Chrome** (or any Chromium — see `browser`
+below). Run it without installing:
+
+```bash
+npx @africanpilot/next-snapshot all --config my-app.config.mjs --screens
+```
+
+or add it to a project, where the command is `next-snapshot`:
+
+```bash
+npm install --save-dev @africanpilot/next-snapshot
+npx next-snapshot all --config my-app.config.mjs
+```
+
+Write a config for your app, starting from
+[`examples/basic.config.mjs`](https://github.com/africanpilot/next-snapshot/blob/main/examples/basic.config.mjs)
+(or [`roles.config.mjs`](https://github.com/africanpilot/next-snapshot/blob/main/examples/roles.config.mjs)
+for an app with sign-in). The commands:
+
+```bash
+next-snapshot all     --config my-app.config.mjs   # capture, bundle, verify
+next-snapshot capture --config my-app.config.mjs   # crawl the app (starts it if configured)
+next-snapshot bundle  --config my-app.config.mjs   # capture dir -> one .html
+next-snapshot verify  --config my-app.config.mjs   # open the .html offline, check it
+```
+
+`verify` checks a sample — two URLs per route per variant — unless given
+`--full`. `--screens` saves a screenshot of each page it checks.
+
+Two examples: `examples/basic.config.mjs` (start the app, crawl from a couple of
+entry points) and `examples/roles.config.mjs` (every role as a variant, the
+app's own sign-in screen as the switcher, a POST emulated offline).
+
+## How it works
+
+A Next app cannot simply be inlined: its pages are rendered by a server (server
+components, cookies, redirects), its client fetches more from that server as you
+navigate, and a `file://` page cannot `fetch`, cannot load module scripts from
+disk, and cannot `pushState` to a new path. So the tool does not transform the
+source. It **records the real app and replays it**.
+
+1. **Capture** (`lib/capture.mjs`). Starts the app (`next start`), then crawls it
+   in headless Chrome, once per *variant* (e.g. per role). It records the HTML of
+   every page exactly as served, every asset and client GET the page triggers,
+   and every redirect. It follows links, the URLs Next prefetches, and the URLs
+   a `<select>` produces when changed. Every non-GET request is aborted in the
+   browser, so the crawl cannot write to the app. Bodies are content-addressed,
+   so a chunk shared by 200 pages is stored once.
+2. **Bundle** (`lib/bundle.mjs`). Rewrites every `location` reference in the
+   app's JS to a virtual location (esbuild `define`, so strings and local
+   variables are untouched), turns asset URLs in HTML and CSS into tokens, and
+   gzips + base64s every body into an inert `<script type="text/plain">`. One
+   file out, with a Content-Security-Policy that forbids all network access.
+3. **Replay** (`lib/runtime/`). The outer page decodes assets into `blob:` URLs
+   and shows each page in a **fresh srcdoc iframe**. A shim runs first in every
+   frame: it supplies the virtual `location`, answers `fetch`/XHR from the
+   snapshot, maps runtime-created script/style/img URLs to their blobs (and
+   reports the original back to chunk loaders that look themselves up), and
+   intercepts links and forms. Next's RSC requests are deliberately answered
+   with a non-RSC response: Next then falls back to a full navigation, which
+   becomes a fresh frame of that page's captured HTML. Every navigation is
+   therefore a clean boot of exactly what the server sent — no framework state
+   to reconcile, no partial payloads to match.
+4. **Verify** (`lib/verify.mjs`). Opens the file from `file://` with the network
+   off, loads every captured page, checks that React hydrated, clicks a link on
+   a few pages, and reports console errors, shim reports, and any attempt to
+   reach the network.
+
+The address bar hash carries the page: `my-app.html#editor:/reports?year=2026`
+opens that page as that variant, and back/forward work.
+
+## Config
+
+A config is an ES module; relative paths resolve against it.
+
+| key | default | |
+|---|---|---|
+| `app.cwd`, `app.start`, `app.build`, `app.port` | — | How to run the app. `{port}` is substituted into `start`. `build` runs when there is no `.next/BUILD_ID`, or with `--build`. Omit `app` and set `url` to capture a server you started yourself. |
+| `url` | `http://localhost:{port}` | Origin to capture. `localhost`, because Next builds redirect URLs on it and a session cookie set on `127.0.0.1` is not sent to `localhost`. |
+| `aliases` | loopback spellings | Other origins that are the same app (a canonical host it redirects to); URLs on them are treated as the app's own. `localhost`, `127.0.0.1` and `[::1]` are always aliases of each other. |
+| `out` | `./<name>.html` | Output file. The capture directory, bundle report, verify report and screenshots sit next to it. |
+| `title` | — | Title shown while the file opens. |
+| `start` | `/` | Page to open when the file has no hash. |
+| `seeds` | `["/"]` | Where the crawl starts. Add any URL links and selects do not reach. |
+| `exclude`, `include` | `/_next/`, `/api/` excluded | Regexes on the path+query key. |
+| `maxPages` | 500 | Per variant. |
+| `variants` | one | `[{ id, label, login({context, request, origin}) }]`. One crawl per variant; the file can switch between them. |
+| `defaultVariant` | first | |
+| `explore.selects` | `true` | Try each option of each visible `<select>` once per page path. |
+| `explore.tabs` | `true` | Click each tab-like control once per page path: `[role=tab]`, and "button bars" — an element whose children are two or more buttons and nothing else. A URL the click writes (router push/replace, or a bare `history.replaceState`) is captured. |
+| `explore.click` | `[]` | Extra CSS selectors to click the same way. |
+| `explore.denyText` | sign out, delete, approve, submit, save… | Controls whose label matches are never clicked. Writes are blocked at the network anyway; this protects the session and client-side state. |
+| `explore.custom` | — | `async ({page, key, variant, discover}) => {}` for app-specific discovery (clicking tabs that change the URL, etc). |
+| `offline.post` | `{}` | `{ "/path": (fields, {variant, key}) => ({ variant?, location?, message? }) }` — emulate a POST in the browser. Must be an arrow or `function` expression; it is serialised into the file. Any POST without a handler is refused as read-only. |
+| `offline.css` | `""` | CSS added to every page — for hiding what has no meaning offline (a sign-out button, a user menu). |
+| `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. |
+| `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. |
+
+## What it cannot do
+
+- **Anything not captured is not there.** A URL no link, prefetch, select or tab
+  led to shows a "not in this snapshot" page listing what was captured. Add it to
+  `seeds`, or teach `explore.custom` how to reach it. One exception: a URL the
+  app writes itself while you use the file (a tab calling `replaceState`) is
+  remembered, and returning to it re-serves the page it came from at that URL.
+- **Exploration is one option at a time.** Each select option and each tab is
+  tried once per page path, from the first URL of that path the crawl reached —
+  not every combination. Seed the combinations you need.
+- **Writes.** Forms and fetches that POST/PUT/DELETE are refused unless an
+  `offline.post` handler emulates them. Server Actions fail the same way.
+- **Soft navigation.** Every navigation is a full page boot, so in-memory client
+  state (a React context, an open panel) does not survive a page change.
+  `localStorage` does, where the browser allows it on `file://`.
+- **Size.** The file carries every page's HTML, including the data server
+  components embedded in it. Pages that differ only a little still compress
+  separately. Check the bundle report's "largest bodies".
+- **Runtime URLs built inside CSS-in-JS** (`url()` in a style string set from
+  JS) are not remapped; they are reported as blocked by `verify`.
+- **Other frameworks.** Nothing here is Next-specific except the RSC fallback
+  and the `.next/static` default; a plain SPA or a Remix/Nuxt app should capture,
+  but only Next App Router is tested.
+
+## 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.
+
+## 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).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/cli.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// next-snapshot — capture a running Next.js app and bundle it into one HTML file
+// that opens from disk with no network.
+//
+//   node cli.mjs all     --config app.config.mjs   capture, bundle, verify
+//   node cli.mjs capture --config app.config.mjs   crawl the app (starts it if configured)
+//   node cli.mjs bundle  --config app.config.mjs   capture dir -> one .html
+//   node cli.mjs verify  --config app.config.mjs   open the .html offline, walk every page
+//
+// Options: --build (rebuild the app first)  --screens (verify saves screenshots)
+//          --limit N / --variant ID (verify a subset)  --no-verify (all: skip verify)
+
+import { parseArgs } from "node:util";
+
+import { bundle } from "./lib/bundle.mjs";
+import { capture } from "./lib/capture.mjs";
+import { loadConfig } from "./lib/config.mjs";
+import { withServer } from "./lib/server.mjs";
+import { verify } from "./lib/verify.mjs";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    config: { type: "string", short: "c" },
+    build: { type: "boolean" },
+    screens: { type: "boolean" },
+    full: { type: "boolean" },
+    limit: { type: "string" },
+    variant: { type: "string" },
+    "no-verify": { type: "boolean" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+
+const cmd = positionals[0] ?? "all";
+if (values.help || !["all", "capture", "bundle", "verify"].includes(cmd)) {
+  console.log(
+    "usage: next-snapshot [all|capture|bundle|verify] --config app.config.mjs [--build] [--screens] [--full] [--limit N] [--variant ID] [--no-verify]",
+  );
+  process.exit(values.help ? 0 : 2);
+}
+
+const log = (s = "") => console.log(s);
+const cfg = await loadConfig(values.config);
+const verifyOpts = { screens: values.screens, full: values.full, limit: values.limit ? +values.limit : 0, variant: values.variant };
+
+try {
+  if (cmd === "capture" || cmd === "all") {
+    await withServer(cfg, { build: values.build }, log, () => capture(cfg, log));
+  }
+  if (cmd === "bundle" || cmd === "all") await bundle(cfg, log);
+  if (cmd === "verify" || (cmd === "all" && !values["no-verify"])) {
+    const r = await verify(cfg, verifyOpts, log);
+    if (r.failed || r.leaks || r.clickFailures) process.exitCode = 1;
+  }
+} catch (e) {
+  console.error(`\nnext-snapshot: ${e.message}`);
+  if (process.env.DEBUG) console.error(e.stack);
+  process.exit(1);
+}

package/lib/browser.mjs

@@ -0,0 +1,63 @@
+// Find a Chromium to drive. Installed Chrome first (no download needed), then
+// any browser Playwright has cached, then whatever the config names.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { chromium } from "playwright-core";
+
+export async function launch(cfg) {
+  const b = cfg.browser ?? {};
+  const tries = [];
+  if (b.executablePath) tries.push({ executablePath: b.executablePath });
+  if (b.channel !== false) tries.push({ channel: b.channel ?? "chrome" });
+  for (const p of cachedChromiums()) tries.push({ executablePath: p });
+
+  let last;
+  for (const t of tries) {
+    try {
+      return await chromium.launch({ headless: b.headless ?? true, ...t });
+    } catch (e) {
+      last = e;
+    }
+  }
+  throw new Error(
+    "No Chromium could be launched. Install Google Chrome, or set browser.executablePath in the config.\n" +
+      (last?.message ?? ""),
+  );
+}
+
+function cachedChromiums() {
+  const roots = [
+    process.env.PLAYWRIGHT_BROWSERS_PATH,
+    path.join(os.homedir(), "Library", "Caches", "ms-playwright"),
+    path.join(os.homedir(), ".cache", "ms-playwright"),
+    path.join(os.homedir(), "AppData", "Local", "ms-playwright"),
+  ].filter(Boolean);
+  const rels = [
+    "chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+    "chrome-mac/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing",
+    "chrome-mac-arm64/Chromium.app/Contents/MacOS/Chromium",
+    "chrome-mac/Chromium.app/Contents/MacOS/Chromium",
+    "chrome-linux64/chrome",
+    "chrome-linux/chrome",
+    "chrome-win64/chrome.exe",
+    "chrome-win/chrome.exe",
+  ];
+  const out = [];
+  for (const root of roots) {
+    let names;
+    try {
+      names = fs.readdirSync(root);
+    } catch {
+      continue;
+    }
+    for (const n of names.filter((n) => /^chromium-\d+$/.test(n)).sort().reverse()) {
+      for (const rel of rels) {
+        const p = path.join(root, n, rel);
+        if (fs.existsSync(p)) out.push(p);
+      }
+    }
+  }
+  return out;
+}

package/lib/bundle.mjs

@@ -0,0 +1,213 @@
+// Turn a capture directory into one HTML file.
+//
+//   JS    location references are rewritten to a virtual location object.
+//   CSS   url(...) and @import references become asset tokens.
+//   HTML  asset-bearing attributes become tokens; a <base> naming the page's
+//         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.
+
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
+
+import { urlKey } from "./key.js";
+import { createRewriter, escHTML, serialisePost, virtualiseLocation } from "./rewrite.mjs";
+
+const HERE = path.dirname(fileURLToPath(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.
+export const CSP = [
+  "default-src 'none'",
+  "script-src 'unsafe-inline' 'unsafe-eval' blob: data:",
+  "style-src 'unsafe-inline' blob: data:",
+  "img-src blob: data:",
+  "font-src blob: data:",
+  "media-src blob: data:",
+  "connect-src blob: data:",
+  "worker-src blob:",
+  "frame-src blob: data: about:",
+  "form-action 'none'",
+].join("; ");
+
+export async function bundle(cfg, log) {
+  const M = JSON.parse(await fs.readFile(path.join(cfg.captureDir, "manifest.json"), "utf8"));
+  const origin = M.origin;
+  const readBody = (sha) => fs.readFile(path.join(cfg.captureDir, "bodies", sha));
+  const t0 = Date.now();
+
+  // --- asset table ---------------------------------------------------------
+  const assets = [];
+  for (const [k, e] of Object.entries(M.assets)) assets.push({ k, v: null, ...e });
+  for (const [v, map] of Object.entries(M.variantAssets)) for (const [k, e] of Object.entries(map)) assets.push({ k, v, ...e });
+  const index = new Map(assets.map((a, i) => [`${a.v ?? ""}\n${a.k}`, i]));
+  const lookup = (key, v) => {
+    if (!key) return -1;
+    let i = index.get(`${v ?? ""}\n${key}`) ?? index.get(`\n${key}`);
+    if (i == null && key.includes("?") && key.startsWith(cfg.staticPrefix)) i = index.get(`\n${key.split("?")[0]}`);
+    return i ?? -1;
+  };
+
+  // --- per-page CSS ----------------------------------------------------------
+  const cssRules = [cfg.offline.css ?? ""];
+  if (cfg.offline.missingLinks === "hide") cssRules.push("a[data-no-missing],area[data-no-missing]{display:none!important}");
+  if (cfg.offline.missingLinks === "disable") {
+    cssRules.push("a[data-no-missing],area[data-no-missing]{opacity:.45;pointer-events:none;cursor:not-allowed}");
+  }
+  const pageCSS = cssRules.join("\n").trim()
+    ? `<style data-no-css>${cssRules.join("\n").replace(/<\/style/gi, "<\\/style")}</style>`
+    : "";
+
+  const missing = new Map(); // referenced but never captured -> count
+  const { rewriteCSS, rewriteHTML } = createRewriter({
+    origin,
+    aliases: cfg.aliases,
+    lookup,
+    pageCSS,
+    onMiss: (k) => missing.set(k, (missing.get(k) ?? 0) + 1),
+  });
+
+  // --- bodies ---------------------------------------------------------------
+  const out = []; // id -> base64(gzip)
+  const outIndex = new Map(); // content hash -> id
+  const sizes = []; // {what, raw, packed}
+  function emit(buf, what) {
+    const h = crypto.createHash("sha256").update(buf).digest("hex");
+    let id = outIndex.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 });
+    }
+    return id;
+  }
+
+  const jsCache = new Map();
+  let jsRewritten = 0;
+  const isJS = (a) => /javascript|ecmascript/i.test(a.type) || /\.m?js$/.test(a.k.split("?")[0]);
+  const isCSS = (a) => /text\/css/i.test(a.type) || /\.css$/.test(a.k.split("?")[0]);
+
+  for (const a of assets) {
+    let buf = await readBody(a.body);
+    if (isJS(a)) {
+      if (!jsCache.has(a.body)) {
+        try {
+          jsCache.set(a.body, Buffer.from(await virtualiseLocation(buf.toString("utf8"))));
+        } catch (e) {
+          log(`  warn: esbuild could not parse ${a.k}; left as-is, location in it is NOT virtualised (${e.message.split("\n")[0]})`);
+          jsCache.set(a.body, buf);
+        }
+      }
+      buf = jsCache.get(a.body);
+      jsRewritten++;
+    } else if (isCSS(a)) {
+      const base = a.k.startsWith("/") ? origin + a.k : a.k;
+      buf = Buffer.from(rewriteCSS(buf.toString("utf8"), base, a.v));
+    }
+    a.b = emit(buf, `asset ${a.k}`);
+  }
+
+  // --- pages ------------------------------------------------------------------
+  const pagesOut = {};
+  let pageCount = 0;
+  for (const [v, P] of Object.entries(M.pages)) {
+    pagesOut[v] = {};
+    for (const [k, e] of Object.entries(P)) {
+      if (e.redirect != null) pagesOut[v][k] = { r: e.redirect };
+      else if (e.file != null) {
+        const i = lookup(e.file, v);
+        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 };
+        pageCount++;
+      }
+    }
+  }
+
+  // --- 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"))
+    .replace("/*@URLKEY@*/null", () => `(${urlKey.toString()})`)
+    .replace('/*@FRAME@*/""', () => JSON.stringify(frameSrc).replace(/</g, "\\u003c"))
+    .replace("/*@POST@*/{}", () => serialisePost(cfg.offline.post));
+
+  const manifestOut = {
+    v: 1,
+    origin,
+    aliases: cfg.aliases,
+    title: cfg.title ?? M.title ?? null,
+    createdAt: M.createdAt,
+    variants: M.variants,
+    defaultVariant: M.defaultVariant,
+    start: M.start,
+    badge: cfg.offline.badge,
+    switcher: cfg.offline.switcher,
+    missingLinks: cfg.offline.missingLinks,
+    assets: assets.map((a) => [a.k, a.v, a.b, a.type, a.status ?? 200]),
+    pages: pagesOut,
+  };
+
+  const title = escHTML(manifestOut.title ?? "Offline snapshot");
+  const parts = [
+    `<!doctype html>\n<html lang="en"><head><meta charset="utf-8">`,
+    `<meta name="viewport" content="width=device-width, initial-scale=1">`,
+    `<meta http-equiv="Content-Security-Policy" content="${CSP}">`,
+    `<meta name="generator" content="next-snapshot">`,
+    `<title>${title}</title>`,
+    `<style>${SHELL_CSS}</style></head><body>`,
+    `<noscript>This offline snapshot needs JavaScript enabled.</noscript>`,
+    `<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>`);
+  parts.push(`<script>${shellSrc.replace(/<\/script/gi, "<\\/script").replace(/<!--/g, "<\\!--")}</script>`);
+  parts.push(`</body></html>\n`);
+
+  await fs.mkdir(path.dirname(cfg.out), { recursive: true });
+  const html = parts.join("\n");
+  await fs.writeFile(cfg.out, html);
+
+  // --- 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);
+  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(`  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 (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 };
+  await fs.writeFile(cfg.out.replace(/\.html?$/, "") + ".bundle.json", JSON.stringify(report, null, 1));
+  return report;
+}
+
+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}
+.no-frame.loading{visibility:hidden}
+#no-loading{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;font:14px system-ui,-apple-system,"Segoe UI",sans-serif;color:#666;background:#fff;z-index:1}
+#no-badge{position:fixed;z-index:2147483646;display:flex;align-items:center;gap:8px;padding:5px 10px;border-radius:999px;background:rgba(20,20,20,.82);color:#fff;font:500 11px/1.3 system-ui,-apple-system,"Segoe UI",sans-serif;opacity:.5;transition:opacity .15s;box-shadow:0 2px 8px rgba(0,0,0,.2)}
+#no-badge:hover,#no-badge:focus-within{opacity:1}
+#no-badge.bottom-right{right:12px;bottom:12px}#no-badge.bottom-left{left:12px;bottom:12px}#no-badge.top-right{right:12px;top:12px}#no-badge.top-left{left:12px;top:12px}
+#no-badge select{font:inherit;color:#fff;background:rgba(255,255,255,.12);border:1px solid rgba(255,255,255,.25);border-radius:6px;padding:1px 4px}
+#no-badge select option{color:#000}
+#no-badge .dot{width:7px;height:7px;border-radius:50%;background:#e9b949;flex:none}
+#no-toast{position:fixed;left:50%;bottom:24px;transform:translateX(-50%);z-index:2147483647;max-width:min(520px,calc(100vw - 32px));padding:10px 14px;border-radius:8px;background:#1f1f1f;color:#fff;font:13px/1.4 system-ui,-apple-system,"Segoe UI",sans-serif;box-shadow:0 6px 24px rgba(0,0,0,.25);opacity:0;transition:opacity .2s;pointer-events:none}
+#no-toast.show{opacity:1}
+`;