@africanpilot/next-snapshot 0.1.0 → 0.1.2

package/README.md

@@ -86,7 +86,8 @@ A config is an ES module; relative paths resolve against it.
 |---|---|---|
 | `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. |
+| `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`, `[::1]` and `0.0.0.0` on the same port are always aliases of each other. |
+| `docker` | — | `{ container, staticPath }` — the app runs in a container, so copy its build output here with `docker cp` before bundling. `staticPath` defaults to `/app/.next/static`. See [Docker](#an-app-running-in-docker). |
 | `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. |
@@ -96,7 +97,7 @@ A config is an ES module; relative paths resolve against it.
 | `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.tabs` | `true` | Click each tab-like control and capture the URL it writes (router push/replace, or a bare `history.replaceState`). Candidates: `[role=tab]`, and "button bars" — an element whose children are two or more buttons and nothing else. `true` clicks each once per page **path**; `"url"` clicks each once per captured **page**, so a route whose pages differ by query (`?programme=…`) gets every tab for every one of them. `"url"` multiplies that route's pages by the number of tabs — use it when clicking through the app moves between a tab and a query at the same time. |
 | `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). |
@@ -108,6 +109,32 @@ A config is an ES module; relative paths resolve against it.
 | `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. |
 
+## An app running in Docker
+
+The tool drives Chrome on your machine, so it reaches the container the same way
+your browser does. Start the app with its port published — `docker run -p
+3000:3000 …`, or `ports: ["3000:3000"]` in compose — and point `url` at it:
+
+```js
+export default {
+  name: "my-app",
+  url: "http://localhost:3000",
+  docker: { container: "my-app" },   // `docker ps` shows the name
+  seeds: ["/"],
+};
+```
+
+`docker` copies the build output out of the container with `docker cp`, so
+chunks that only load later — a modal, a menu — are in the file too. Without it
+the snapshot holds only what the crawl happened to load. If your image puts the
+app somewhere other than `/app`, set `staticPath` to match. A failed copy is a
+warning, not an error: the capture continues without it.
+
+Redirects to `0.0.0.0` need nothing extra. Next's images set
+`HOSTNAME=0.0.0.0`, and an app that builds absolute URLs from it redirects
+there; `0.0.0.0` on the same port is already an alias of the origin. For any
+other host it redirects to, add it to `aliases`.
+
 ## What it cannot do
 
 - **Anything not captured is not there.** A URL no link, prefetch, select or tab
@@ -117,7 +144,9 @@ A config is an ES module; relative paths resolve against it.
   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.
+  not every combination. `explore.tabs: "url"` covers the common case (every
+  tab of every page of a route); for anything else, seed the combinations you
+  need. A URL that was never captured shows a "not in this snapshot" page.
 - **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

package/lib/capture.mjs

@@ -9,6 +9,7 @@
 // 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 { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fss from "node:fs";
 import fs from "node:fs/promises";
@@ -146,9 +147,13 @@ export async function capture(cfg, log) {
     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)}`);
+  // The build output, so chunks the crawl never triggered are in the file too.
+  // In Docker it lives inside the container; copy it out first.
+  let staticDir = cfg.staticDir;
+  if (cfg.docker?.container) staticDir = copyFromContainer(cfg, log) ?? staticDir;
+  if (cfg.includeStatic && staticDir && fss.existsSync(staticDir)) {
+    const n = await addDir(staticDir, cfg.staticPrefix, Infinity);
+    log(`static: +${n} build files from ${path.relative(process.cwd(), staticDir)}`);
   }
   if (cfg.publicDir && fss.existsSync(cfg.publicDir)) {
     const n = await addDir(cfg.publicDir, "/", cfg.maxPublicFileBytes);
@@ -181,7 +186,20 @@ export async function capture(cfg, log) {
       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 };
+    const s = {
+      v,
+      context,
+      page,
+      visited: new Set(),
+      rsc: new Set(),
+      files: new Set(),
+      explored: new Set(),
+      // Keys a tab click produced. In "url" mode they are not explored again:
+      // their tab strip leads back to pages already captured, and re-clicking
+      // it on every one of them is what turns this from linear into expensive.
+      fromTabs: 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) => {
@@ -364,12 +382,19 @@ export async function capture(cfg, log) {
   // 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.
+  // nothing else), which is how most tab strips are built without ARIA.
+  //
+  // `explore.tabs: true` clicks each label once per page *path*: cheap, but a
+  // route whose pages differ by query (?programme=…) then holds tab views for
+  // only the first of them. `"url"` clicks each label once per captured page,
+  // so every programme gets every tab — pages, and file size, multiply by the
+  // number of tabs.
   async function exploreClicks(s, key) {
     const { page } = s;
     const found = new Set();
-    const pathOnly = key.split("?")[0];
+    const perUrl = cfg.explore.tabs === "url";
+    if (perUrl && s.fromTabs.has(key)) return found;
+    const scope = perUrl ? key : key.split("?")[0];
     const tag = () =>
       page
         .evaluate(
@@ -404,7 +429,7 @@ export async function capture(cfg, log) {
     const labels = (await tag()).slice(0, cfg.explore.maxClicks);
     let dirty = false;
     for (const label of labels) {
-      const sig = `${pathOnly}::click:${label}`;
+      const sig = `${scope}::click:${label}`;
       if (s.explored.has(sig)) continue;
       s.explored.add(sig);
       if (dirty) {
@@ -420,6 +445,7 @@ export async function capture(cfg, log) {
         const k = keyOf(page.url());
         if (k && k !== key) {
           found.add(k);
+          s.fromTabs.add(k);
           dirty = true;
         }
       } catch {
@@ -496,6 +522,31 @@ export async function capture(cfg, log) {
   }
 }
 
+/**
+ * `docker cp <container>:<staticPath>` into the capture directory. Returns the
+ * local path, or null with a warning — a missing build is worth saying out
+ * loud, but it does not stop a capture that is otherwise fine.
+ */
+function copyFromContainer(cfg, log) {
+  const { container, staticPath } = cfg.docker;
+  const dest = path.join(cfg.captureDir, "docker-static");
+  // Ours, written by the previous run: `docker cp` nests into a directory that
+  // already exists, which would bury the files a level deeper each time.
+  fss.rmSync(dest, { recursive: true, force: true });
+  const r = spawnSync("docker", ["cp", `${container}:${staticPath}`, dest], { encoding: "utf8" });
+  if (r.error?.code === "ENOENT") {
+    log(`  warn: docker is not installed, so ${container}:${staticPath} could not be copied`);
+    return null;
+  }
+  if (r.status !== 0) {
+    log(`  warn: docker cp ${container}:${staticPath} failed — ${(r.stderr || "").trim().split("\n")[0]}`);
+    log(`  warn: continuing without the build output; lazily-loaded chunks may be missing offline`);
+    return null;
+  }
+  log(`docker: copied ${container}:${staticPath}`);
+  return dest;
+}
+
 async function walk(dir) {
   const out = [];
   for (const e of await fs.readdir(dir, { withFileTypes: true })) {

package/lib/config.mjs

@@ -22,7 +22,10 @@ export async function loadConfig(file) {
   // 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]"];
+  // 0.0.0.0 is here because of Docker: Next's own images set HOSTNAME=0.0.0.0,
+  // and an app that builds absolute URLs from that redirects to 0.0.0.0:PORT.
+  // Without the alias those pages look like a different site and are dropped.
+  const loopback = ["localhost", "127.0.0.1", "[::1]", "0.0.0.0"];
   const aliases = [
     ...(loopback.includes(o.hostname) ? loopback.map((h) => `${o.protocol}//${h}${o.port ? ":" + o.port : ""}`) : []),
     ...(raw.aliases ?? []),
@@ -70,7 +73,10 @@ export async function loadConfig(file) {
     explore: {
       selects: true,
       maxOptions: 40,
-      // Click tab-like controls and record any URL they write.
+      // Click tab-like controls and record any URL they write. `true` clicks
+      // each once per page path; "url" clicks each once per captured page, so
+      // a route whose pages differ by query gets every tab for every one of
+      // them — at the cost of multiplying pages by the number of tabs.
       tabs: true,
       // Extra CSS selectors to click the same way.
       click: [],
@@ -83,6 +89,10 @@ export async function loadConfig(file) {
     },
     variants,
     defaultVariant: raw.defaultVariant ?? variants[0].id,
+    // The app runs in a container: its build output is not on this disk, so
+    // `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,
     includeStatic: raw.includeStatic ?? true,
     staticDir: r(raw.staticDir) ?? defaultStatic,
     staticPrefix: raw.staticPrefix ?? "/_next/static/",

package/lib/server.mjs

@@ -8,7 +8,10 @@ import path from "node:path";
 export async function withServer(cfg, opts, log, fn) {
   if (!cfg.app?.start) {
     if (!(await isUp(cfg.origin))) {
-      throw new Error(`Nothing is answering at ${cfg.origin}. Start the app, or give the config an app.start command.`);
+      throw new Error(
+        `Nothing is answering at ${cfg.origin}. Start the app, or give the config an app.start command.\n` +
+          `If it runs in Docker, publish the port to this machine (docker run -p 3000:3000 …) and set url to that port.`,
+      );
     }
     log(`using the server already running at ${cfg.origin}`);
     return fn();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@africanpilot/next-snapshot",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Capture a running Next.js app and bundle it into one self-contained, offline HTML file.",
   "keywords": [
     "nextjs",