agent-horde 0.1.4 → 0.1.6

package/src/dashboard-export.ts

@@ -0,0 +1,192 @@
+import * as path from "node:path";
+import * as zlib from "node:zlib";
+
+/** One rendered page; `text` pages (the Mermaid export) carry no links to rewrite. */
+export interface ExportPage {
+  body: string;
+  text?: boolean | undefined;
+}
+
+/** Renders the dashboard page at a URL; must return an error page rather than throw. */
+export type ExportRenderer = (url: URL) => ExportPage;
+
+export interface ZipEntry {
+  path: string;
+  data: Buffer;
+}
+
+const BASE = "http://127.0.0.1";
+const MAX_PAGES = 100_000;
+const ZIP_MAX_ENTRIES = 0xffff;
+const ZIP_MAX_BYTES = 0xffff_ffff;
+
+/** One name component: no separators, and never a dot-only segment, so the zip cannot escape its folder. */
+function safeName(text: string): string {
+  const safe = text.replace(/[^A-Za-z0-9._=~-]/g, "_");
+  return /^\.+$/.test(safe) ? safe.replace(/\./g, "_") : safe;
+}
+
+/** The file a dashboard URL becomes: `/` is index.html, query parameters are sorted into the name. */
+export function exportFile(url: URL): string {
+  const segments = url.pathname.split("/").filter(Boolean).map((segment) => safeName(decodeURIComponent(segment)));
+  const stem = segments.length === 0 ? "index" : segments.join("/");
+  const params = [...url.searchParams.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => safeName(`${k}=${v}`));
+  const name = `${stem}${params.map((pair) => `~${pair}`).join("")}`;
+  return url.pathname.endsWith(".mmd") ? name : `${name}.html`;
+}
+
+function canonical(href: string): URL {
+  const url = new URL(href, BASE);
+  url.hash = "";
+  const sorted = [...url.searchParams.entries()].sort(([a], [b]) => a.localeCompare(b));
+  url.search = "";
+  for (const [k, v] of sorted) url.searchParams.append(k, v);
+  return url;
+}
+
+function unescapeHtml(text: string): string {
+  return text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+}
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+/** Rewrites every dashboard-absolute href in a page to a path relative to the page's own file. */
+function rewriteLinks(body: string, file: string, visit: (url: URL) => string): string {
+  const dir = path.posix.dirname(file);
+  return body.replace(/href="([^"]*)"/g, (match, raw: string) => {
+    const href = unescapeHtml(raw);
+    if (!href.startsWith("/")) return match;
+    const hashAt = href.indexOf("#");
+    const hash = hashAt >= 0 ? href.slice(hashAt) : "";
+    const target = visit(canonical(hashAt >= 0 ? href.slice(0, hashAt) : href));
+    return `href="${escapeHtml(path.posix.relative(dir, target) + hash)}"`;
+  });
+}
+
+const yieldToLoop = (): Promise<void> => new Promise((resolve) => setImmediate(resolve));
+
+/** Renders every page reachable from `/`, as files whose links point at each other, one page per event-loop turn. */
+export async function* crawlDashboard(render: ExportRenderer): AsyncGenerator<ZipEntry> {
+  const files = new Map<string, string>();
+  const queue: URL[] = [];
+  const visit = (url: URL): string => {
+    const key = url.pathname + url.search;
+    const known = files.get(key);
+    if (known !== undefined) return known;
+    if (files.size >= MAX_PAGES) throw new Error(`dashboard export exceeds ${MAX_PAGES} pages`);
+    const file = exportFile(url);
+    files.set(key, file);
+    queue.push(url);
+    return file;
+  };
+  visit(new URL("/", BASE));
+  for (let i = 0; i < queue.length; i++) {
+    const url = queue[i] as URL;
+    const file = files.get(url.pathname + url.search) as string;
+    const page = render(url);
+    const body = page.text ? page.body : rewriteLinks(page.body, file, visit);
+    yield { path: file, data: Buffer.from(body, "utf8") };
+    await yieldToLoop();
+  }
+}
+
+function dosDateTime(date: Date): { time: number; date: number } {
+  const year = Math.min(Math.max(date.getUTCFullYear(), 1980), 2107);
+  return {
+    time: (date.getUTCHours() << 11) | (date.getUTCMinutes() << 5) | (date.getUTCSeconds() >> 1),
+    date: ((year - 1980) << 9) | ((date.getUTCMonth() + 1) << 5) | date.getUTCDate(),
+  };
+}
+
+interface ZipRecord {
+  name: Buffer;
+  method: number;
+  crc: number;
+  compressedSize: number;
+  size: number;
+  offset: number;
+}
+
+function zipHeader(signature: number, record: ZipRecord, stamp: { time: number; date: number }): Buffer {
+  const header = Buffer.alloc(26);
+  header.writeUInt16LE(20, 0);
+  header.writeUInt16LE(0x0800, 2);
+  header.writeUInt16LE(record.method, 4);
+  header.writeUInt16LE(stamp.time, 6);
+  header.writeUInt16LE(stamp.date, 8);
+  header.writeUInt32LE(record.crc, 10);
+  header.writeUInt32LE(record.compressedSize, 14);
+  header.writeUInt32LE(record.size, 18);
+  header.writeUInt16LE(record.name.length, 22);
+  header.writeUInt16LE(0, 24);
+  const sig = Buffer.alloc(4);
+  sig.writeUInt32LE(signature, 0);
+  return Buffer.concat([sig, header]);
+}
+
+function centralEntry(record: ZipRecord, stamp: { time: number; date: number }): Buffer {
+  const madeBy = Buffer.alloc(2);
+  madeBy.writeUInt16LE(20, 0);
+  const tail = Buffer.alloc(14);
+  tail.writeUInt16LE(0, 0);
+  tail.writeUInt16LE(0, 2);
+  tail.writeUInt16LE(0, 4);
+  tail.writeUInt32LE(0, 6);
+  tail.writeUInt32LE(record.offset, 10);
+  const header = zipHeader(0x02014b50, record, stamp);
+  return Buffer.concat([header.subarray(0, 4), madeBy, header.subarray(4), tail, record.name]);
+}
+
+/** A zip archive streamed one entry at a time: deflated where smaller, UTF-8 names, the given modification time. */
+export async function* zipArchive(entries: AsyncIterable<ZipEntry> | Iterable<ZipEntry>, mtime = new Date()): AsyncGenerator<Buffer> {
+  const stamp = dosDateTime(mtime);
+  const records: ZipRecord[] = [];
+  let offset = 0;
+  for await (const entry of entries) {
+    if (records.length >= ZIP_MAX_ENTRIES) throw new Error(`dashboard export exceeds ${ZIP_MAX_ENTRIES} files; zip64 is not supported`);
+    const deflated = zlib.deflateRawSync(entry.data);
+    const compressed = deflated.length < entry.data.length ? deflated : entry.data;
+    const record: ZipRecord = {
+      name: Buffer.from(entry.path, "utf8"),
+      method: compressed === deflated ? 8 : 0,
+      crc: zlib.crc32(entry.data),
+      compressedSize: compressed.length,
+      size: entry.data.length,
+      offset,
+    };
+    const local = Buffer.concat([zipHeader(0x04034b50, record, stamp), record.name, compressed]);
+    records.push(record);
+    offset += local.length;
+    if (offset > ZIP_MAX_BYTES) throw new Error("dashboard export exceeds 4 GiB; zip64 is not supported");
+    yield local;
+  }
+  const central = Buffer.concat(records.map((record) => centralEntry(record, stamp)));
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(0x06054b50, 0);
+  end.writeUInt16LE(0, 4);
+  end.writeUInt16LE(0, 6);
+  end.writeUInt16LE(records.length, 8);
+  end.writeUInt16LE(records.length, 10);
+  end.writeUInt32LE(central.length, 12);
+  end.writeUInt32LE(offset, 16);
+  end.writeUInt16LE(0, 20);
+  yield Buffer.concat([central, end]);
+}
+
+async function* underFolder(entries: AsyncIterable<ZipEntry>, folder: string): AsyncGenerator<ZipEntry> {
+  for await (const entry of entries) yield { ...entry, path: `${folder}/${entry.path}` };
+}
+
+/** Crawls the dashboard into a zip, streamed as it is built, whose top-level folder holds index.html. */
+export function exportDashboard(render: ExportRenderer, folder: string, now = new Date()): AsyncGenerator<Buffer> {
+  return zipArchive(underFolder(crawlDashboard(render), folder), now);
+}
+
+/** The whole stream in one buffer, for callers that want the finished archive. */
+export async function collect(chunks: AsyncIterable<Buffer>): Promise<Buffer> {
+  const parts: Buffer[] = [];
+  for await (const chunk of chunks) parts.push(chunk);
+  return Buffer.concat(parts);
+}

package/src/dashboard-html.ts

@@ -24,6 +24,7 @@ import type {
   TranscriptVm,
 } from "./dashboard-data.js";
 import { RUN_FILES } from "./dashboard-data.js";
+import { buildInfo } from "./build-info.js";
 import { detailKey, formatClock, formatElapsed, formatTokens, oneLine } from "./format.js";
 import { renderRunGraphMermaid } from "./run-graph-mermaid.js";
 import { GRAPH_CSS, graphLegendHtml, renderRunGraphSvg } from "./run-graph-svg.js";
@@ -39,6 +40,8 @@ export interface RenderContext {
   origin?: string | undefined;
   /** The run the collaboration and graph links target: this page's run, else the newest. */
   navRun?: string | undefined;
+  /** Rendering for the static export: no refresh, no export control, native disclosure. */
+  export?: boolean | undefined;
 }
 
 interface Crumb {
@@ -52,9 +55,26 @@ const CSS =
   "th,td{border:1px solid #000;padding:2px 6px;vertical-align:top;text-align:left}" +
   "th{background:#eee}pre{white-space:pre-wrap;word-break:break-word;margin:0}" +
   "nav a{margin-right:8px}.r{text-align:right}h1,h2{font-size:13px;margin:8px 0 4px}" +
-  "details>summary{cursor:pointer}a{color:#000}" +
+  "details>summary{cursor:pointer}a{color:#000}footer{margin-top:16px;color:#666}footer a{color:#666}" +
+  ".export{position:absolute;top:8px;right:8px;line-height:0}" +
+  ".modal{display:none;position:fixed;inset:0;background:rgba(0,0,0,.7)}" +
+  ".modal:target{display:flex;align-items:center;justify-content:center}" +
+  ".modal-box{background:#fff;border:3px solid #000;padding:32px;width:min(90vw,760px);font-size:18px;line-height:1.5}" +
+  ".modal-box h2{font-size:24px;margin:0 0 16px}" +
+  ".modal-box .btn{display:inline-block;border:2px solid #000;padding:8px 16px;margin-right:12px}" +
   GRAPH_CSS;
 
+const EXPORT_ICON =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="22" height="22" aria-hidden="true">' +
+  '<path d="M12 3v12m0 0l-5-5m5 5l5-5M4 17v3h16v-3" fill="none" stroke="currentColor" stroke-width="2" ' +
+  'stroke-linecap="round" stroke-linejoin="round"/></svg>';
+
+const EXPORT_WARNING =
+  "The zip holds every page of this dashboard as static HTML: every run, every member transcript and log, " +
+  "the run documents, the shared ledgers and the event audit. Transcripts include everything members read " +
+  "and produced on this machine: file contents, command output, paths, and any secrets or credentials they " +
+  "encountered. Review the export before sharing it with anyone who should not see all of that.";
+
 const ESCAPES: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
 
 function escapeHtml(text: string): string {
@@ -142,7 +162,7 @@ export function renderCollaboration(vm: CollaborationVm, ctx: RenderContext): st
     anchor(m.id), e(`${m.sender} -> ${m.to}`), e(`${m.state}${m.blocking ? " BLOCKING" : ""} / ${formatElapsed(Date.now() - Date.parse(m.createdAt))}`),
     e(`${m.target}@${m.revision}`), pre(messageThread(m)),
   ]));
-  const reviews = table(["review", "target revision", "verdict", "scope / evidence"], state.reviews.map((r) => [`${anchor(r.id)} @${e(r.actor)}`, e(`${r.target}@${r.revision}`), e(`${r.verdict} [${r.support}]`), pre(`Checked: ${r.checked}\nUnchecked: ${r.unchecked || "none declared"}\nEvidence: ${r.evidence.join(", ")}\n${r.text}`)]));
+  const reviews = table(["review", "target revision", "verdict", "scope / evidence"], state.reviews.map((r) => [`${anchor(r.id)} @${e(r.actor)}`, e(`${r.target}@${r.revision}`), e(`${r.verdict} [${r.support}]`), pre(`Checked: ${r.checked}\nUnchecked: ${r.unchecked || "none declared"}\nLimits: ${r.limits || "none disclosed"}\nEvidence: ${r.evidence.join(", ")}${r.reattests ? `\nReattests: ${r.reattests}` : ""}\n${r.text}`)]));
   const artifacts = table(["artifact", "hash / dependencies", "acceptance"], state.artifacts.map((a) => [`${anchor(a.id)} ${e(`${a.path} @${a.owner} (${a.kind ?? "runnable"})`)}`, pre(`${a.hash}\n${JSON.stringify(a.dependencies)}`), e(report.acceptedArtifacts.includes(a.id) ? "accepted" : "excluded / needs review")]));
   const events = vm.events.map((event) => `<div id="${e(event.eventId)}">${details(`${event.eventId} ${event.at} ${event.actor}/${event.attempt} ${event.action} ${event.outcome}`, pre(JSON.stringify(event, null, 2)), `event:${report.runId}:${event.eventId}`)}</div>`).join("");
   return page(`Collaboration ${report.runId}`, [{ text: "runs", href: "/" }, { text: report.runId, href: runHref(report.runId) }, { text: "collaboration" }],
@@ -182,13 +202,49 @@ function persistentDetails(body: string, href = "/"): string {
   });
 }
 
-export function page(title: string, crumbs: Crumb[], body: string, ctx: RenderContext): string {
-  body = persistentDetails(body, ctx.href);
-  const meta = ctx.refresh?.on ? `<meta http-equiv="refresh" content="${ctx.refresh.seconds}">` : "";
+/** The export opens the modal on the paused page, so a refresh cannot close it; cancel restores the page. */
+function exportControl(ctx: RenderContext): string {
+  if (ctx.export) return "";
+  const current = ctx.href ?? "/";
+  const paused = ctx.refresh?.on ? ctx.refresh.toggleHref : current;
+  return (
+    `<a class="export" href="${e(`${paused}#export`)}" title="export dashboard" aria-label="export dashboard">${EXPORT_ICON}</a>` +
+    `<div id="export" class="modal"><div class="modal-box"><h2>Export this dashboard?</h2><p>${EXPORT_WARNING}</p>` +
+    `<p><a class="btn" href="${e(`/export${query({ back: current })}`)}">download zip</a><a class="btn" href="${e(current)}">cancel</a></p></div></div>`
+  );
+}
+
+/** Shown once the download is confirmed; it starts the download itself and says what the wait is. */
+export function renderExportStart(zipHref: string, backHref: string, ctx: RenderContext): string {
+  const body =
+    "<p>The archive is being packed one page at a time and streamed to your browser, so it appears in the " +
+    "browser's download list right away and grows until it is complete. A dashboard with long transcripts takes " +
+    "a while; the dashboard stays usable meanwhile.</p>" +
+    `<p>If no download appears, ${link(zipHref, "download it directly")}.</p>` +
+    `<p>${link(backHref, "back to the dashboard")}</p>`;
+  const start = `<meta http-equiv="refresh" content="0;url=${e(zipHref)}">`;
+  return page("exporting dashboard", [{ text: "runs", href: "/" }, { text: "export" }], body, { ...ctx, refresh: undefined }, start);
+}
+
+/** The static export has no server, so disclosure falls back to the browser's own details element. */
+function nativeDetails(body: string): string {
+  return body.replace(/<details data-expand="[a-f0-9]+">/g, "<details>");
+}
+
+/** Which agent-horde produced the page: the package version and, from a checkout, the commit. */
+function footer(): string {
+  const { name, version, commit, repository } = buildInfo();
+  const at = commit ? ` at ${repository ? link(`${repository}/commit/${commit.replace(/-dirty$/, "")}`, commit) : e(commit)}` : "";
+  return `<footer>${e(name)} ${e(version)}${at}</footer>`;
+}
+
+export function page(title: string, crumbs: Crumb[], body: string, ctx: RenderContext, head = ""): string {
+  body = ctx.export ? nativeDetails(body) : persistentDetails(body, ctx.href);
+  const meta = ctx.refresh?.on ? `<meta http-equiv="refresh" content="${ctx.refresh.seconds}">` : head;
   return (
     `<!doctype html><html><head><meta charset="utf-8"><title>${e(title)}</title>${meta}` +
-    `<style>${CSS}</style></head><body>${nav(ctx)}${crumbLine(crumbs)}${refreshLine(ctx)}` +
-    `<h1>${e(title)}</h1>${body}</body></html>`
+    `<style>${CSS}</style></head><body>${exportControl(ctx)}${nav(ctx)}${crumbLine(crumbs)}${refreshLine(ctx)}` +
+    `<h1>${e(title)}</h1>${body}${footer()}</body></html>`
   );
 }
 
@@ -331,7 +387,7 @@ export function renderMemberDetail(vm: MemberDetailVm, ctx: RenderContext): stri
     ["session file", vm.sessionFile ? e(vm.sessionFile) : "none mapped; see " + link(`${runHref(vm.runId)}/sessions`, "session files")],
   ];
   const transcript = vm.sessionFile
-    ? `<p>${link(`${base}/transcript?from=last&n=40`, "transcript (tail)")} | ${link(`${base}/transcript?from=0&n=50`, "transcript (start)")}</p>`
+    ? `<p>${link(`${base}/transcript?from=last&n=${TRANSCRIPT_PAGE}`, "transcript (tail)")} | ${link(`${base}/transcript?from=0&n=${TRANSCRIPT_PAGE}`, "transcript (start)")}</p>`
     : "";
   const last = vm.lastText ? `<h2>last text</h2>${pre(vm.lastText)}` : "";
   const final = vm.finalText
@@ -359,6 +415,8 @@ export function renderMemberLog(vm: MemberLogVm, ctx: RenderContext): string {
 // Transcript
 // ---------------------------------------------------------------------------
 
+const TRANSCRIPT_PAGE = 50;
+
 function transcriptBase(vm: { runId: string; member?: string | undefined; file: string }): string {
   return vm.member
     ? `${memberHref(vm.runId, vm.member)}/transcript`
@@ -409,18 +467,27 @@ function entryRow(entry: TranscriptEntry, base: string, full: boolean, file: str
   return [link(href, `#${entry.index}`), clock(entry.timestamp), entryRole(entry), content, entryUsage(entry)];
 }
 
-function pagingBar(vm: TranscriptVm, base: string): string {
+/** The export crawls one page size, so it offers no size links. */
+function pagingBar(vm: TranscriptVm, base: string, ctx: RenderContext): string {
   const to = Math.min(vm.total, vm.from + vm.n);
   const go = (from: number | "last", n = vm.n): string => `${base}${query({ from: String(from), n: String(n) })}`;
   const prev = vm.from > 0 ? link(go(Math.max(0, vm.from - vm.n)), "prev") : "prev";
   const next = vm.hasMore ? link(go(vm.from + vm.n), "next") : "next";
-  const sizes = [20, 50, 100].map((n) => (n === vm.n ? `n=${n}` : link(go(vm.from, n), `n=${n}`))).join(" ");
+  const sizes = ctx.export
+    ? ""
+    : ` | ${[20, 50, 100].map((n) => (n === vm.n ? `n=${n}` : link(go(vm.from, n), `n=${n}`))).join(" ")}`;
   return (
     `<p>entries ${vm.from}..${to} of ${vm.total} | ${link(go(0), "first")} ${prev} ${next} ` +
-    `${link(go("last"), "last")} | ${sizes}</p>`
+    `${link(go("last"), "last")}${sizes}</p>`
   );
 }
 
+/** Live pages centre the entry in a short window; the export returns to the crawled page holding it. */
+function transcriptPageHref(base: string, index: number, ctx: RenderContext): string {
+  if (ctx.export) return `${base}?from=${Math.floor(index / TRANSCRIPT_PAGE) * TRANSCRIPT_PAGE}&n=${TRANSCRIPT_PAGE}`;
+  return `${base}?from=${Math.max(0, index - 10)}&n=20`;
+}
+
 function transcriptCrumbs(vm: { runId: string; member?: string | undefined; file: string }, leaf: string): Crumb[] {
   const crumbs: Crumb[] = [{ text: "runs", href: "/" }, { text: vm.runId, href: runHref(vm.runId) }];
   if (vm.member) crumbs.push({ text: vm.member, href: memberHref(vm.runId, vm.member) });
@@ -433,18 +500,17 @@ export function renderTranscript(vm: TranscriptVm, ctx: RenderContext): string {
   const base = transcriptBase(vm);
   const body =
     `<p>file ${e(vm.file)}${vm.sessionId ? `, session ${e(vm.sessionId)}` : ""}${vm.cwd ? `, cwd ${e(vm.cwd)}` : ""}</p>` +
-    pagingBar(vm, base) +
+    pagingBar(vm, base, ctx) +
     table(["#", "time", "role", "content", "in/out"], vm.entries.map((entry) => entryRow(entry, base, false, vm.file)), "no entries") +
-    pagingBar(vm, base);
+    pagingBar(vm, base, ctx);
   const title = `${vm.member ?? vm.file} transcript`;
   return page(title, transcriptCrumbs(vm, "transcript"), body, ctx);
 }
 
 export function renderTranscriptEntry(vm: TranscriptEntryVm, ctx: RenderContext): string {
   const base = transcriptBase(vm);
-  const from = Math.max(0, vm.entry.index - 10);
   const body =
-    `<p>${link(`${base}?from=${from}&n=20`, "back to transcript")}</p>` +
+    `<p>${link(transcriptPageHref(base, vm.entry.index, ctx), "back to transcript")}</p>` +
     table(["#", "time", "role", "content", "in/out"], [entryRow(vm.entry, base, true, vm.file)]) +
     details("raw json", pre(vm.raw), `${base}:${vm.file}:${vm.entry.index}:raw`);
   return page(`entry #${vm.entry.index}`, transcriptCrumbs(vm, `#${vm.entry.index}`), body, ctx);
@@ -529,16 +595,17 @@ function findingsHref(vm: FindingsVm, open: number[]): string {
   return `/findings${query({ run: vm.run, view: vm.view, open: open.length > 0 ? open.join(",") : undefined })}`;
 }
 
-/** The body is expanded when its id is in the URL, so the state survives auto-refresh. */
-function findingBody(f: FindingEntry, vm: FindingsVm): string {
+/** The body is expanded when its id is in the URL, so the state survives auto-refresh; the export shows it inline. */
+function findingBody(f: FindingEntry, vm: FindingsVm, ctx: RenderContext): string {
   if (!f.body) return "";
+  if (ctx.export) return pre(f.body);
   if (vm.open.includes(f.id)) {
     return pre(f.body) + link(findingsHref(vm, vm.open.filter((id) => id !== f.id)), "[hide body]");
   }
   return ` ${link(findingsHref(vm, [...vm.open, f.id]), "[show body]")}`;
 }
 
-function findingRow(f: FindingEntry, vm: FindingsVm): string[] {
+function findingRow(f: FindingEntry, vm: FindingsVm, ctx: RenderContext): string[] {
   const idea = f.ideaId === undefined ? "" : link(`/ideas#idea-${f.ideaId}`, `#${f.ideaId}`);
   const authors = [f.author, ...f.corroborators].map((a) => authorLink(a, f.runId)).join(", ");
   const title = (f.supersededBy !== undefined ? "<b>SUPERSEDED</b> " : "") + e(f.title);
@@ -555,7 +622,7 @@ function findingRow(f: FindingEntry, vm: FindingsVm): string[] {
     f.supersedes === undefined ? "" : link(`#F${f.supersedes}`, `F${f.supersedes}`),
     f.supersededBy === undefined ? "" : link(`#F${f.supersededBy}`, `F${f.supersededBy}`),
     e(vm.reviewStates?.[f.id] ?? (f.verifiedBy ? `legacy (${f.verifiedBy})` : "unreviewed")),
-    title + findingBody(f, vm),
+    title + findingBody(f, vm, ctx),
   ];
 }
 
@@ -577,13 +644,13 @@ export function renderFindings(vm: FindingsVm, ctx: RenderContext): string {
         const deltas = cluster.deltaMembers.length > 0 ? `; deltas ${cluster.deltaMembers.join(", ")}` : "";
         return (
           `<h2>cluster ${i + 1}: F${cluster.representative}, members ${e(members)}${e(deltas)}</h2>` +
-          table(FINDING_HEADERS, cluster.findings.map((f) => findingRow(f, vm)))
+          table(FINDING_HEADERS, cluster.findings.map((f) => findingRow(f, vm, ctx)))
         );
       })
       .join("");
     if (vm.clusters.length === 0) body += "<p>no findings</p>";
   } else {
-    body += table(FINDING_HEADERS, vm.findings.map((f) => findingRow(f, vm)), "no findings");
+    body += table(FINDING_HEADERS, vm.findings.map((f) => findingRow(f, vm, ctx)), "no findings");
   }
   return page("findings", [{ text: "findings" }], body, ctx);
 }

package/src/dashboard.ts

@@ -29,6 +29,7 @@ import {
   renderClaims,
   renderCollaboration,
   renderError,
+  renderExportStart,
   renderFacts,
   renderFile,
   renderFindings,
@@ -45,8 +46,12 @@ import {
   renderTranscriptEntry,
 } from "./dashboard-html.js";
 import type { RenderContext } from "./dashboard-html.js";
+import { collect, exportDashboard } from "./dashboard-export.js";
+import type { ExportPage } from "./dashboard-export.js";
 
 const DEFAULT_PORT = 7433;
+const EXPORT_PAGE = "/export";
+const EXPORT_PATH = "/export.zip";
 const REFRESH_SECONDS = 3;
 const MAX_URL_LENGTH = 4096;
 const CLOSE_GUARD_MS = 2_000;
@@ -57,6 +62,8 @@ interface DashboardResponse {
   contentType: string;
   body: string;
   headers: Record<string, string>;
+  /** Written after the headers in place of `body`, as it is produced. */
+  stream?: AsyncIterable<Buffer> | undefined;
 }
 
 interface Route {
@@ -282,6 +289,12 @@ function respond(status: number, contentType: string, body: string, extra: Recor
   return { status, contentType, body, headers: { ...baseHeaders(), ...extra } };
 }
 
+/** A same-origin dashboard path, else `/`; the export page returns here. */
+function backPath(query: URLSearchParams): string {
+  const back = query.get("back") ?? "/";
+  return /^\/(?![/\\])[^\s]{0,2000}$/.test(back) ? back : "/";
+}
+
 function parentPath(pathname: string): string {
   const trimmed = pathname.replace(/\/+$/, "");
   const parent = trimmed.slice(0, trimmed.lastIndexOf("/"));
@@ -316,24 +329,33 @@ function routeMatch(pathname: string): { route: Route; params: string[] } | unde
   return undefined;
 }
 
-function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderContext): DashboardResponse {
+/** The run this page belongs to, and the run the nav's collaboration and graph links target. */
+function runContext(src: DashboardSource, url: URL, params: string[]): Pick<RenderContext, "runId" | "navRun"> {
+  const runId = RUN_ID_RE.test(params[0] ?? "") ? params[0] : undefined;
+  const filterRun = url.searchParams.get("run");
+  const navRun = runId ?? (filterRun && RUN_ID_RE.test(filterRun) ? filterRun : undefined) ?? latestRunId(src);
+  return { runId, navRun };
+}
+
+/** The export costs seconds of work per request, so pages from other sites may not start one. */
+function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderContext, crossSite: boolean): DashboardResponse {
   const pathname = json ? url.pathname.slice("/api".length) || "/" : url.pathname;
+  if (!json && (pathname === EXPORT_PATH || pathname === EXPORT_PAGE)) {
+    if (crossSite) return errorResponse(403, "the export can only be started from the dashboard itself", url, json, ctx);
+    if (pathname === EXPORT_PATH) return exportResponse(src, url, ctx);
+    return respond(200, "text/html; charset=utf-8", renderExportStart(EXPORT_PATH, backPath(url.searchParams), ctx));
+  }
   const matched = routeMatch(pathname);
   if (!matched) throw new DashboardError(404, `no such page: ${pathname}`);
   const { route, params } = matched;
   const refreshParam = queryEnum(url.searchParams, "refresh", ["0", String(REFRESH_SECONDS)] as const, String(REFRESH_SECONDS));
   const vm = route.load(src, params, url.searchParams);
   if (json) return respond(200, "application/json; charset=utf-8", JSON.stringify(vm));
-  const runId = RUN_ID_RE.test(params[0] ?? "") ? params[0] : undefined;
-  const filterRun = url.searchParams.get("run");
-  const navRun = runId ?? (filterRun && RUN_ID_RE.test(filterRun) ? filterRun : undefined) ?? latestRunId(src);
   const live = route.live(vm, src, params, url.searchParams);
   const on = live && refreshParam !== "0";
   const pageCtx: RenderContext = {
     ...ctx,
-    runId,
-    navRun,
-    href: url.pathname + url.search,
+    ...runContext(src, url, params),
     refresh: live ? { on, toggleHref: refreshToggle(url, on), seconds: REFRESH_SECONDS } : undefined,
   };
   const body = route.render(vm as never, pageCtx);
@@ -341,17 +363,68 @@ function handleRoute(src: DashboardSource, url: URL, json: boolean, ctx: RenderC
   return respond(200, "text/html; charset=utf-8", body);
 }
 
-/** Pure request handler: validates method and host, dispatches, maps errors to responses. */
-export function routeRequest(src: DashboardSource, method: string, url: URL, host: string | undefined): DashboardResponse {
+/** One page of the static export; errors become pages so no exported link dangles. */
+function exportPage(src: DashboardSource, url: URL): ExportPage {
+  const ctx: RenderContext = { activeId: src.getActive()?.id, href: url.pathname + url.search, export: true };
+  try {
+    const matched = routeMatch(url.pathname);
+    if (!matched) throw new DashboardError(404, `no such page: ${url.pathname}`);
+    const { route, params } = matched;
+    const vm = route.load(src, params, url.searchParams);
+    return { body: route.render(vm as never, { ...ctx, ...runContext(src, url, params) }), text: route.text };
+  } catch (error) {
+    const status = error instanceof DashboardError ? error.status : 500;
+    const message = error instanceof DashboardError ? error.message : `dashboard error: ${error instanceof Error ? error.message : String(error)}`;
+    return { body: renderError(status, message, parentPath(url.pathname), ctx) };
+  }
+}
+
+/** The whole dashboard as a zip of static pages, streamed as it is built, named for the moment it was taken. */
+export function exportDashboardArchive(src: DashboardSource, now = new Date()): { filename: string; zip: AsyncGenerator<Buffer> } {
+  const folder = `horde-dashboard-${now.toISOString().slice(0, 19).replace(/[T:]/g, "-")}`;
+  return { filename: `${folder}.zip`, zip: exportDashboard((url) => exportPage(src, url), folder, now) };
+}
+
+/** The finished archive in one buffer. */
+export async function exportDashboardBuffer(src: DashboardSource, now = new Date()): Promise<{ filename: string; zip: Buffer }> {
+  const { filename, zip } = exportDashboardArchive(src, now);
+  return { filename, zip: await collect(zip) };
+}
+
+let exporting = false;
+
+/** Marks the export busy from its first chunk until the stream ends or its reader goes away. */
+async function* exclusive(stream: AsyncIterable<Buffer>): AsyncGenerator<Buffer> {
+  exporting = true;
+  try {
+    yield* stream;
+  } finally {
+    exporting = false;
+  }
+}
+
+/** Headers go out at once so the browser shows the download while the pages are still being packed; one at a time. */
+function exportResponse(src: DashboardSource, url: URL, ctx: RenderContext): DashboardResponse {
+  if (exporting) return errorResponse(503, "an export is already in progress; wait for it to finish", url, false, ctx);
+  const { filename, zip } = exportDashboardArchive(src);
+  return { ...respond(200, "application/zip", "", { "Content-Disposition": `attachment; filename="${filename}"` }), stream: exclusive(zip) };
+}
+
+/** Pure request handler: validates method and host, dispatches, maps errors to responses. `fetchSite` is the Sec-Fetch-Site header. */
+export function routeRequest(src: DashboardSource, method: string, url: URL, host: string | undefined, fetchSite?: string): DashboardResponse {
   const json = url.pathname === "/api" || url.pathname.startsWith("/api/");
-  const ctx: RenderContext = { activeId: src.getActive()?.id, origin: host ? `http://${host}` : undefined };
+  const ctx: RenderContext = {
+    activeId: src.getActive()?.id,
+    origin: host ? `http://${host}` : undefined,
+    href: url.pathname + url.search,
+  };
   try {
     if (method !== "GET" && method !== "HEAD") {
       return { ...errorResponse(405, `method ${method} not allowed`, url, json, ctx), headers: { ...baseHeaders(), Allow: "GET, HEAD" } };
     }
     if (!host || !HOST_RE.test(host)) return errorResponse(403, "host must be 127.0.0.1 or localhost", url, json, ctx);
     if (url.href.length > MAX_URL_LENGTH) return errorResponse(414, "url too long", url, json, ctx);
-    return handleRoute(src, url, json, ctx);
+    return handleRoute(src, url, json, ctx, fetchSite === "cross-site");
   } catch (error) {
     if (error instanceof DashboardError) return errorResponse(error.status, error.message, url, json, ctx);
     const message = error instanceof Error ? error.message : String(error);
@@ -383,12 +456,41 @@ function listenError(error: NodeJS.ErrnoException, port: number): Error {
   return new Error(`dashboard could not listen on ${port}: ${error.message}`);
 }
 
+const drained = (res: http.ServerResponse): Promise<void> =>
+  new Promise((resolve) => {
+    const done = (): void => {
+      res.off("drain", done);
+      res.off("close", done);
+      resolve();
+    };
+    res.once("drain", done);
+    res.once("close", done);
+  });
+
+/** Writes the chunks as they come, pausing for the client; a failure mid-stream cuts the connection. */
+async function streamBody(res: http.ServerResponse, stream: AsyncIterable<Buffer>): Promise<void> {
+  try {
+    for await (const chunk of stream) {
+      if (res.destroyed) return;
+      if (!res.write(chunk)) await drained(res);
+    }
+    res.end();
+  } catch (error) {
+    res.destroy(error instanceof Error ? error : new Error(String(error)));
+  }
+}
+
 function serve(src: DashboardSource, req: http.IncomingMessage, res: http.ServerResponse): void {
   req.resume();
   res.on("error", () => {});
   const url = new URL(req.url ?? "/", "http://127.0.0.1");
-  const response = routeRequest(src, req.method ?? "GET", url, req.headers.host);
+  const fetchSite = req.headers["sec-fetch-site"];
+  const response = routeRequest(src, req.method ?? "GET", url, req.headers.host, Array.isArray(fetchSite) ? fetchSite[0] : fetchSite);
   res.writeHead(response.status, { ...response.headers, "Content-Type": response.contentType });
+  if (response.stream && req.method !== "HEAD") {
+    void streamBody(res, response.stream);
+    return;
+  }
   res.end(response.body);
 }