@africanpilot/next-snapshot 0.1.0

package/lib/capture.mjs

@@ -0,0 +1,522 @@
+// Crawl the running app in headless Chrome and record what a browser receives:
+// the HTML of every page, and every asset and client-side GET it triggers.
+//
+// Output is a directory: manifest.json (what was seen, keyed by urlKey) and
+// bodies/<sha> (content-addressed, so a chunk shared by every page and a page
+// identical across variants are each stored once).
+//
+// The crawl is read-only by construction: every request that is not GET, HEAD
+// or OPTIONS is aborted before it leaves the browser. Only a variant's `login`
+// hook, which runs before that guard is installed, can write.
+
+import crypto from "node:crypto";
+import fss from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { launch } from "./browser.mjs";
+import { urlKey } from "./key.js";
+
+const FILE_EXT = /\.(pdf|csv|tsv|xlsx?|docx?|pptx?|zip|gz|tgz|json|txt|xml|png|jpe?g|gif|svg|webp|avif|ico|mp4|webm|mp3|wav)$/i;
+
+const MIME = {
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".map": "application/json",
+  ".html": "text/html; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".pdf": "application/pdf",
+  ".csv": "text/csv; charset=utf-8",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mp3": "audio/mpeg",
+  ".wasm": "application/wasm",
+};
+
+export function mimeFor(p) {
+  return MIME[path.extname(p.split("?")[0]).toLowerCase()] ?? "application/octet-stream";
+}
+
+export async function capture(cfg, log) {
+  const { origin } = cfg;
+  // Every URL the browser reports goes through here, so a redirect to another
+  // spelling of the same host (localhost vs 127.0.0.1) keys as the same page.
+  const canon = (u) => {
+    for (const a of cfg.aliases) if (u === a || u.startsWith(a + "/") || u.startsWith(a + "?")) return origin + u.slice(a.length);
+    return u;
+  };
+  const keyOf = (u, base = origin) => {
+    let abs;
+    try {
+      abs = new URL(String(u), base).href;
+    } catch {
+      return null;
+    }
+    return urlKey(canon(abs), origin, origin);
+  };
+  const bodiesDir = path.join(cfg.captureDir, "bodies");
+  await fs.mkdir(bodiesDir, { recursive: true });
+
+  async function put(buf) {
+    const sha = crypto.createHash("sha256").update(buf).digest("hex").slice(0, 32);
+    const f = path.join(bodiesDir, sha);
+    if (!fss.existsSync(f)) await fs.writeFile(f, buf);
+    return sha;
+  }
+
+  const M = {
+    version: 1,
+    tool: "next-snapshot",
+    origin,
+    createdAt: new Date().toISOString(),
+    title: cfg.title,
+    variants: cfg.variants.map((v) => ({ id: v.id, label: v.label })),
+    defaultVariant: cfg.defaultVariant,
+    start: keyOf(cfg.start),
+    pages: {}, // variant -> key -> {body,status} | {redirect} | {file}
+    assets: {}, // key -> {body,type,status}   shared by every variant
+    variantAssets: {}, // variant -> key -> {body,type,status}   API/data responses
+    blocked: [], // non-GET requests the guard stopped
+    failures: [], // navigations that failed outright
+    liveErrors: [], // errors the *live* app threw — not the tool's fault
+    rscSkipped: 0,
+  };
+  for (const v of cfg.variants) {
+    M.pages[v.id] = {};
+    M.variantAssets[v.id] = {};
+  }
+
+  const allowed = (k) =>
+    !!k && k.startsWith("/") && !cfg.exclude.some((re) => re.test(k)) && (!cfg.include || cfg.include.some((re) => re.test(k)));
+  const discovered = new Set();
+  const discover = (k) => {
+    if (allowed(k) && !discovered.has(k)) {
+      discovered.add(k);
+      return true;
+    }
+    return false;
+  };
+  for (const s of cfg.seeds) discover(keyOf(s));
+  discover(M.start);
+
+  const pending = new Set();
+  const track = (p) => {
+    pending.add(p);
+    p.finally(() => pending.delete(p));
+  };
+
+  const browser = await launch(cfg);
+  const sessions = {};
+  const t0 = Date.now();
+
+  try {
+    // Every variant must answer for every URL any variant found: a URL one role
+    // can open is a URL another role may be redirected away from, and that
+    // redirect is part of what the snapshot has to reproduce.
+    for (;;) {
+      let progressed = false;
+      for (const v of cfg.variants) {
+        const s = (sessions[v.id] ??= await openSession(v));
+        const todo = [...discovered].filter((k) => !s.visited.has(k));
+        if (!todo.length) continue;
+        progressed = true;
+        await crawl(s, todo);
+      }
+      if (!progressed) break;
+    }
+    for (const s of Object.values(sessions)) {
+      for (const k of s.files) if (!M.variantAssets[s.v.id][k] && !M.assets[k]) await fetchFile(s, k);
+    }
+    await Promise.allSettled([...pending]);
+  } finally {
+    await browser.close();
+  }
+
+  if (cfg.includeStatic && cfg.staticDir && fss.existsSync(cfg.staticDir)) {
+    const n = await addDir(cfg.staticDir, cfg.staticPrefix, Infinity);
+    log(`static: +${n} build files from ${path.relative(process.cwd(), cfg.staticDir)}`);
+  }
+  if (cfg.publicDir && fss.existsSync(cfg.publicDir)) {
+    const n = await addDir(cfg.publicDir, "/", cfg.maxPublicFileBytes);
+    if (n) log(`public: +${n} files from ${path.relative(process.cwd(), cfg.publicDir)}`);
+  }
+
+  await fs.writeFile(path.join(cfg.captureDir, "manifest.json"), JSON.stringify(M, null, 1));
+  summarise(M, log, Date.now() - t0);
+  return M;
+
+  // ---------------------------------------------------------------------------
+
+  async function openSession(v) {
+    const context = await browser.newContext({
+      viewport: cfg.viewport,
+      serviceWorkers: "block",
+      ignoreHTTPSErrors: true,
+      locale: cfg.locale,
+      timezoneId: cfg.timezoneId,
+    });
+    if (v.login) {
+      log(`[${v.id}] login`);
+      await v.login({ context, request: context.request, origin });
+    }
+    await context.route("**/*", (route) => {
+      const req = route.request();
+      const m = req.method();
+      if (m === "GET" || m === "HEAD" || m === "OPTIONS") return route.continue();
+      M.blocked.push({ variant: v.id, method: m, url: req.url() });
+      return route.abort("blockedbyclient");
+    });
+    const page = await context.newPage();
+    const s = { v, context, page, visited: new Set(), rsc: new Set(), files: new Set(), explored: new Set(), current: null };
+    context.on("response", (res) => track(onResponse(s, res)));
+    // A click that opens a window must not leave a second crawler behind.
+    context.on("page", (p) => {
+      if (p !== s.page) p.close().catch(() => {});
+    });
+    page.on("pageerror", (e) => {
+      if (M.liveErrors.length < 200) M.liveErrors.push({ variant: v.id, key: s.current, message: e.message.split("\n")[0] });
+    });
+    return s;
+  }
+
+  async function crawl(s, queue) {
+    let count = Object.keys(M.pages[s.v.id]).length;
+    while (queue.length) {
+      const key = queue.shift();
+      if (s.visited.has(key)) continue;
+      if (count >= cfg.maxPages) {
+        log(`[${s.v.id}] maxPages (${cfg.maxPages}) reached; ${queue.length} URL(s) left unvisited`);
+        for (const k of queue) s.visited.add(k);
+        break;
+      }
+      const found = await visit(s, key);
+      count = Object.keys(M.pages[s.v.id]).length;
+      for (const k of found) if (discover(k)) queue.push(k);
+      // Found by another variant earlier, but not yet visited by this one.
+      for (const k of found) if (discovered.has(k) && !s.visited.has(k) && !queue.includes(k)) queue.push(k);
+    }
+  }
+
+  async function visit(s, key) {
+    const { page, v } = s;
+    const P = M.pages[v.id];
+    s.visited.add(key);
+    s.current = key;
+    const started = Date.now();
+    let resp;
+    try {
+      resp = await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs });
+    } catch (e) {
+      if (/Download is starting|net::ERR_ABORTED/.test(e.message)) {
+        await fetchFile(s, key);
+        P[key] = { file: key };
+        return [];
+      }
+      M.failures.push({ variant: v.id, key, message: e.message.split("\n")[0] });
+      log(`[${v.id}] FAIL ${key}: ${e.message.split("\n")[0]}`);
+      return [];
+    }
+    if (!resp) return [];
+
+    const chain = [];
+    for (let r = resp.request().redirectedFrom(); r; r = r.redirectedFrom()) chain.push(keyOf(r.url()));
+    const finalKey = keyOf(resp.url());
+    const type = resp.headers()["content-type"] ?? "";
+    const isHTML = /html/i.test(type);
+
+    if (isHTML) {
+      P[finalKey] = { body: await put(await resp.body()), status: resp.status() };
+    } else {
+      const body = await resp.body().catch(() => null);
+      if (body) M.variantAssets[v.id][finalKey] = { body: await put(body), type, status: resp.status() };
+      P[finalKey] = { file: finalKey };
+    }
+    for (const k of chain) {
+      if (k && k !== finalKey && !P[k]?.body) P[k] = { redirect: finalKey };
+      if (k) s.visited.add(k);
+    }
+    if (finalKey !== key && !P[key]?.body) P[key] = { redirect: finalKey };
+    s.visited.add(finalKey);
+    const note = finalKey !== key ? ` -> ${finalKey}` : "";
+    log(`[${v.id}] ${resp.status()} ${key}${note}  ${Date.now() - started}ms`);
+
+    if (!isHTML || !finalKey.startsWith("/")) return [];
+
+    await settle(page);
+    const found = new Set();
+    const after = keyOf(page.url());
+    if (after && after !== finalKey) found.add(after); // client-side redirect
+
+    const links = await page
+      .evaluate(() =>
+        [...document.querySelectorAll("a[href], area[href]")].map((a) => ({ href: a.href, download: a.hasAttribute("download") })),
+      )
+      .catch(() => []);
+    for (const l of links) {
+      const k = keyOf(l.href);
+      if (!k || !k.startsWith("/")) continue;
+      if (l.download || FILE_EXT.test(k.split("?")[0])) s.files.add(k);
+      else found.add(k);
+    }
+    for (const k of s.rsc) found.add(k); // Next prefetched it, so the app links to it
+    s.rsc.clear();
+
+    if (cfg.explore.selects) for (const k of await exploreSelects(s, finalKey)) found.add(k);
+    if (cfg.explore.tabs || cfg.explore.click.length) for (const k of await exploreClicks(s, finalKey)) found.add(k);
+    if (cfg.explore.custom) {
+      await cfg.explore.custom({
+        page,
+        key: finalKey,
+        variant: v.id,
+        origin,
+        discover: (u) => {
+          const k = keyOf(u, origin + finalKey);
+          if (k) found.add(k);
+        },
+      });
+    }
+    return [...found];
+  }
+
+  async function settle(page) {
+    await page.waitForLoadState("networkidle", { timeout: cfg.idleTimeoutMs }).catch(() => {});
+    if (cfg.settleMs) await page.waitForTimeout(cfg.settleMs);
+  }
+
+  // A <select> that drives the URL (router.push/replace on change) is the
+  // common way a Next page exposes views that links never mention. Try each
+  // option once per (page path, select); a URL change is a page to capture.
+  async function exploreSelects(s, key) {
+    const { page } = s;
+    const found = new Set();
+    const pathOnly = key.split("?")[0];
+    const sels = page.locator("select:visible");
+    const count = await sels.count().catch(() => 0);
+    let navigatedAway = false;
+
+    for (let i = 0; i < count; i++) {
+      if (navigatedAway) {
+        await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs }).catch(() => {});
+        await settle(page);
+        navigatedAway = false;
+      }
+      const sel = sels.nth(i);
+      let meta;
+      try {
+        meta = await sel.evaluate((el) => ({
+          id: el.name || el.id || el.getAttribute("aria-label") || "",
+          value: el.value,
+          options: el.disabled ? [] : [...el.options].filter((o) => !o.disabled).map((o) => o.value),
+        }));
+      } catch {
+        continue;
+      }
+      const sig = `${pathOnly}::${i}:${meta.id}`;
+      if (s.explored.has(sig)) continue;
+      s.explored.add(sig);
+
+      for (const val of meta.options.slice(0, cfg.explore.maxOptions)) {
+        if (val === meta.value) continue;
+        if (navigatedAway) {
+          await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs }).catch(() => {});
+          await settle(page);
+          navigatedAway = false;
+        }
+        try {
+          await sels.nth(i).selectOption(val, { timeout: 3000 });
+          await page.waitForTimeout(150);
+          await settle(page);
+          const k = keyOf(page.url());
+          if (k && k !== key) {
+            found.add(k);
+            navigatedAway = true;
+          }
+        } catch {
+          navigatedAway = true;
+        }
+      }
+    }
+    // Hand the page back where it was found: tab exploration and custom
+    // discovery run next, and must run on this page, not the last option's.
+    if (navigatedAway) {
+      await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs }).catch(() => {});
+      await settle(page);
+    }
+    if (found.size) log(`[${s.v.id}]   selects on ${key}: ${found.size} URL(s)`);
+    return found;
+  }
+
+  // Tab strips that write the URL — router.replace, or history.replaceState for
+  // a tab that never asks the server — expose views that no link names.
+  // Candidates: [role=tab], the configured `explore.click` selectors, and
+  // "button bars" (an element whose children are two or more buttons and
+  // nothing else), which is how most tab strips are built without ARIA. Each
+  // (page path, label) is clicked once per variant.
+  async function exploreClicks(s, key) {
+    const { page } = s;
+    const found = new Set();
+    const pathOnly = key.split("?")[0];
+    const tag = () =>
+      page
+        .evaluate(
+          ({ tabs, extra, deny }) => {
+            const denyRe = new RegExp(deny, "i");
+            const picked = new Set();
+            if (tabs) {
+              document.querySelectorAll('[role="tab"]').forEach((el) => picked.add(el));
+              document.querySelectorAll("button").forEach((b) => {
+                const p = b.parentElement;
+                if (!p || b.form) return;
+                const kids = [...p.children];
+                if (kids.length >= 2 && kids.every((k) => k.tagName === "BUTTON")) picked.add(b);
+              });
+            }
+            for (const sel of extra) document.querySelectorAll(sel).forEach((el) => picked.add(el));
+            const labels = [];
+            for (const el of picked) {
+              if (!(el.offsetParent || el.getClientRects().length)) continue;
+              if (el.disabled || el.getAttribute("aria-disabled") === "true") continue;
+              const label = (el.innerText || el.getAttribute("aria-label") || "").trim().replace(/\s+/g, " ").slice(0, 80);
+              if (!label || denyRe.test(label)) continue;
+              el.setAttribute("data-no-explore", label);
+              labels.push(label);
+            }
+            return [...new Set(labels)];
+          },
+          { tabs: !!cfg.explore.tabs, extra: cfg.explore.click, deny: cfg.explore.denyText.source },
+        )
+        .catch(() => []);
+
+    const labels = (await tag()).slice(0, cfg.explore.maxClicks);
+    let dirty = false;
+    for (const label of labels) {
+      const sig = `${pathOnly}::click:${label}`;
+      if (s.explored.has(sig)) continue;
+      s.explored.add(sig);
+      if (dirty) {
+        await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs }).catch(() => {});
+        await settle(page);
+        dirty = false;
+      }
+      await tag(); // the page may have re-rendered since
+      try {
+        await page.locator(`[data-no-explore=${JSON.stringify(label)}]`).first().click({ timeout: 3000 });
+        await page.waitForTimeout(150);
+        await settle(page);
+        const k = keyOf(page.url());
+        if (k && k !== key) {
+          found.add(k);
+          dirty = true;
+        }
+      } catch {
+        dirty = true;
+      }
+    }
+    if (dirty) {
+      await page.goto(origin + key, { waitUntil: "load", timeout: cfg.navTimeoutMs }).catch(() => {});
+      await settle(page);
+    }
+    if (found.size) log(`[${s.v.id}]   tabs on ${key}: ${found.size} URL(s)`);
+    return found;
+  }
+
+  async function onResponse(s, res) {
+    const req = res.request();
+    if (req.method() !== "GET") return;
+    const url = res.url();
+    const key = keyOf(url);
+    if (!key) return;
+    const status = res.status();
+    if (status >= 300 && status < 400) return;
+    if (req.isNavigationRequest() && req.frame() === s.page.mainFrame()) return; // pages come from visit()
+
+    const headers = res.headers();
+    const type = headers["content-type"] ?? "";
+    const rh = req.headers();
+    if (rh.rsc === "1" || type.startsWith("text/x-component") || /[?&]_rsc=/.test(url)) {
+      M.rscSkipped++;
+      if (key.startsWith("/")) s.rsc.add(key);
+      return;
+    }
+    if (/\/_next\/webpack-hmr|\/__nextjs/.test(url)) return;
+
+    let body;
+    try {
+      body = await res.body();
+    } catch {
+      return;
+    }
+    const entry = { body: await put(body), type: type || mimeFor(key), status };
+    const dynamic =
+      key.startsWith("/") &&
+      !key.startsWith(cfg.staticPrefix) &&
+      (["fetch", "xhr", "eventsource"].includes(req.resourceType()) || key.startsWith("/api/"));
+    if (dynamic) M.variantAssets[s.v.id][key] = entry;
+    else if (!M.assets[key] || M.assets[key].status >= 400) M.assets[key] = entry;
+  }
+
+  async function fetchFile(s, key) {
+    try {
+      const r = await s.context.request.get(origin + key, { maxRedirects: 5 });
+      if (!r.ok()) return;
+      const type = r.headers()["content-type"] ?? mimeFor(key);
+      M.variantAssets[s.v.id][key] = { body: await put(await r.body()), type, status: r.status() };
+      log(`[${s.v.id}] file ${key}`);
+    } catch (e) {
+      M.failures.push({ variant: s.v.id, key, message: `file: ${e.message.split("\n")[0]}` });
+    }
+  }
+
+  async function addDir(dir, prefix, maxBytes) {
+    let n = 0;
+    for (const f of await walk(dir)) {
+      const rel = path.relative(dir, f).split(path.sep).join("/");
+      const key = prefix + rel;
+      if (M.assets[key]) continue;
+      const st = await fs.stat(f);
+      if (st.size > maxBytes) continue;
+      M.assets[key] = { body: await put(await fs.readFile(f)), type: mimeFor(f), status: 200, fromDisk: true };
+      n++;
+    }
+    return n;
+  }
+}
+
+async function walk(dir) {
+  const out = [];
+  for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(p)));
+    else if (e.isFile() && !e.name.endsWith(".map")) out.push(p);
+  }
+  return out;
+}
+
+function summarise(M, log, ms) {
+  log("");
+  log(`capture finished in ${(ms / 1000).toFixed(1)}s`);
+  for (const v of M.variants) {
+    const P = Object.values(M.pages[v.id]);
+    const html = P.filter((e) => e.body).length;
+    const red = P.filter((e) => e.redirect).length;
+    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}`);
+  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

@@ -0,0 +1,106 @@
+// Load a config module and fill in every default, so the rest of the tool reads
+// one fully-resolved object. Relative paths resolve against the config file.
+
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+export async function loadConfig(file) {
+  if (!file) throw new Error("No config given. Pass --config path/to/app.config.mjs");
+  const abs = path.resolve(file);
+  if (!fs.existsSync(abs)) throw new Error(`Config not found: ${abs}`);
+  const mod = await import(pathToFileURL(abs).href);
+  const raw = mod.default ?? mod;
+  const dir = path.dirname(abs);
+  const r = (p) => (p == null ? p : path.resolve(dir, p));
+
+  const name = raw.name ?? path.basename(abs).replace(/\.config\.m?js$/, "").replace(/\.m?js$/, "");
+  const app = raw.app ? { ...raw.app, cwd: r(raw.app.cwd ?? ".") } : null;
+  const port = app?.port ?? 3217;
+  // `localhost`, not 127.0.0.1: Next builds absolute redirect URLs from its own
+  // idea of the host, and a cookie set on one loopback name is not sent to the
+  // other — a sign-in that redirects across them loses its session.
+  const origin = new URL(raw.url ?? `http://localhost:${port}`).origin;
+  const o = new URL(origin);
+  const loopback = ["localhost", "127.0.0.1", "[::1]"];
+  const aliases = [
+    ...(loopback.includes(o.hostname) ? loopback.map((h) => `${o.protocol}//${h}${o.port ? ":" + o.port : ""}`) : []),
+    ...(raw.aliases ?? []),
+  ]
+    .map((a) => new URL(a).origin)
+    .filter((a) => a !== origin);
+  const out = r(raw.out ?? `./${name}.html`);
+
+  const variants = (raw.variants?.length ? raw.variants : [{ id: "default" }]).map((v) => ({
+    label: v.id,
+    ...v,
+  }));
+  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_.-]+`);
+    if (ids.has(v.id)) throw new Error(`Duplicate variant id "${v.id}"`);
+    ids.add(v.id);
+  }
+
+  const defaultStatic = app ? path.join(app.cwd, ".next", "static") : null;
+  const defaultPublic = app ? path.join(app.cwd, "public") : null;
+
+  return {
+    name,
+    file: abs,
+    dir,
+    app,
+    origin,
+    // Other origins that are the same app (loopback spellings, a canonical host
+    // the app redirects to). URLs on them are keyed as if on `origin`.
+    aliases,
+    out,
+    captureDir: r(raw.captureDir) ?? out.replace(/\.html?$/, "") + ".capture",
+    title: raw.title ?? null,
+    start: raw.start ?? "/",
+    seeds: raw.seeds ?? ["/"],
+    // Never crawled as pages. /_next is build output; /api is not a page, and a
+    // GET to it can still have side effects. Add your own with `exclude`.
+    exclude: [/^\/_next\//, /^\/api\//, ...(raw.exclude ?? [])],
+    include: raw.include ?? null,
+    maxPages: raw.maxPages ?? 500,
+    navTimeoutMs: raw.navTimeoutMs ?? 60_000,
+    idleTimeoutMs: raw.idleTimeoutMs ?? 8_000,
+    settleMs: raw.settleMs ?? 300,
+    explore: {
+      selects: true,
+      maxOptions: 40,
+      // Click tab-like controls and record any URL they write.
+      tabs: true,
+      // Extra CSS selectors to click the same way.
+      click: [],
+      maxClicks: 30,
+      // Never clicked, whatever they look like. Writes are blocked at the
+      // network regardless; this keeps client-side state (and the session) intact.
+      denyText: /\b(sign ?out|log ?out|delete|remove|approve|reject|submit|save|release|publish|reset|clear|discard|revoke)\b/i,
+      custom: null,
+      ...(raw.explore ?? {}),
+    },
+    variants,
+    defaultVariant: raw.defaultVariant ?? variants[0].id,
+    includeStatic: raw.includeStatic ?? true,
+    staticDir: r(raw.staticDir) ?? defaultStatic,
+    staticPrefix: raw.staticPrefix ?? "/_next/static/",
+    publicDir: r(raw.publicDir) ?? defaultPublic,
+    maxPublicFileBytes: raw.maxPublicFileBytes ?? 5 * 1024 * 1024,
+    offline: {
+      badge: "bottom-right",
+      switcher: true,
+      post: {},
+      // CSS added to every page, for hiding what makes no sense offline.
+      css: "",
+      // Links to pages the snapshot does not hold: "show", "disable" or "hide".
+      missingLinks: "show",
+      ...(raw.offline ?? {}),
+    },
+    viewport: raw.viewport ?? { width: 1440, height: 900 },
+    browser: raw.browser ?? {},
+    locale: raw.locale ?? "en-US",
+    timezoneId: raw.timezoneId,
+  };
+}

package/lib/key.js

@@ -0,0 +1,29 @@
+// URL -> lookup key, the one normalisation every part of the tool agrees on.
+//
+// Used by the Node side (capture, bundle) and by the browser runtime, which is
+// handed this function's *source text*. Keep it a self-contained plain function:
+// no imports, no closures over module scope, nothing Node-only.
+//
+// A same-origin URL keys as "/path?sorted=query"; anything else keys as its
+// absolute URL. The fragment never matters, `_rsc` (Next's cache-buster) is
+// dropped, parameters are sorted by name so `?b=2&a=1` and `?a=1&b=2` are one
+// page, and a trailing slash is dropped from every path but "/".
+export function urlKey(input, base, origin) {
+  let u;
+  try {
+    u = new URL(input, base);
+  } catch {
+    return null;
+  }
+  if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+  const own = origin || new URL(base).origin;
+  const params = [];
+  u.searchParams.forEach((v, k) => {
+    if (k !== "_rsc") params.push([k, v]);
+  });
+  params.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const search = params.length ? "?" + new URLSearchParams(params).toString() : "";
+  let path = u.pathname;
+  if (path.length > 1 && path.endsWith("/")) path = path.slice(0, -1);
+  return (u.origin === own ? "" : u.origin) + path + search;
+}