npm - scenescout - Versions diffs - 3.0.0 → 3.1.0 - Mend

scenescout 3.0.0 → 3.1.0

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

Files changed (9) hide show

package/CHANGELOG.md +32 -0
package/README.md +50 -8
package/dist/engine/browser.js +61 -1
package/dist/engine/live-page.js +230 -17
package/dist/engine/live.js +40 -2
package/dist/engine/replay.js +348 -0
package/dist/engine/report.js +101 -1
package/dist/mcp-server.js +84 -8
package/package.json +1 -1

package/dist/engine/live.js CHANGED Viewed

@@ -80,6 +80,8 @@ export function feedForSession(log, session, limit, redact = (s) => s) {
             line.target = e.target;
         if (e.result !== undefined)
             line.result = e.result;
+        if (e.frame !== undefined)
+            line.frame = e.frame;
         if (task !== undefined)
             line.task = task;
         lines.push(line);
@@ -90,8 +92,13 @@ export function feedForSession(log, session, limit, redact = (s) => s) {
 }
 /** How many feed lines a status poll carries per session. Enough to read the last move at a glance; the close-up asks for more. */
 export const FEED_LINES = 6;
-/** The cap the close-up gets. A long run's log is thousands of lines and none of it needs to reach the page. */
-export const FEED_LINES_MAX = 60;
+/**
+ * The cap the close-up gets. A long run's log is thousands of lines and none
+ * of it needs to reach the page — but this is also what the timeline is drawn
+ * from, and a timeline that only reaches back a minute cannot be scrubbed.
+ * The whole run, every step of it, is the page at `run`.
+ */
+export const FEED_LINES_MAX = 300;
 /**
  * How long a call may run before the session is judged wedged rather than
  * busy, when the entry does not carry the tool's own watchdog budget (an
@@ -251,6 +258,13 @@ export function watchTarget(input) {
         };
     return { url: `http://127.0.0.1:${port}/${clean}/` };
 }
+/** What `run` says when there is no run to show: a page, because a person navigated here. */
+export const NO_RUN_PAGE = '<!doctype html><html lang="en"><head><meta charset="utf-8"><title>No run to show</title>' +
+    "<style>body{margin:0;display:grid;place-items:center;min-height:100vh;background:#0e1116;color:#e6e9ee;" +
+    'font:16px/1.6 system-ui,-apple-system,"Segoe UI",sans-serif}main{max-width:34rem;padding:2rem;text-align:center}' +
+    "a{color:#7aa2ff}</style></head><body><main><h1>Nothing to show yet</h1>" +
+    "<p>This run has not produced a report. It may not have started, or its engine may have exited since you opened this page.</p>" +
+    '<p><a href="./">Back to the live board</a></p></main></body></html>';
 const LIVE_CSP = "default-src 'none'; img-src 'self' data:; style-src 'unsafe-inline'; script-src 'unsafe-inline'; connect-src 'self'; base-uri 'none'; form-action 'none'";
 const BOUNDARY = "scenescoutframe";
 /** A thumbnail younger than this is served again instead of taking a new one. */
@@ -381,6 +395,30 @@ export class LiveServer {
                 return this.send(res, 404, "no run attached");
             return this.send(res, 200, JSON.stringify(report), "application/json; charset=utf-8");
         }
+        if (route === "run" && !name) {
+            const doc = this.provider.replay();
+            // Somebody clicked a button or refreshed a bookmark to get here, so an
+            // answer they cannot read is worse than no link at all.
+            if (!doc)
+                return this.send(res, 404, NO_RUN_PAGE, "text/html; charset=utf-8", { "Content-Security-Policy": LIVE_CSP });
+            return this.send(res, 200, doc, "text/html; charset=utf-8", { "Content-Security-Policy": LIVE_CSP });
+        }
+        if (route === "record" && name) {
+            // A recorded frame, by the path the feed gave. The provider decides what
+            // exists; nothing here builds a filesystem path from the request.
+            const rel = parts.slice(2).join("/");
+            let asked;
+            try {
+                asked = decodeURIComponent(rel);
+            }
+            catch {
+                return this.send(res, 404, "not found");
+            }
+            const jpeg = await this.provider.frame(asked);
+            if (!jpeg)
+                return this.send(res, 404, "no such frame");
+            return this.send(res, 200, jpeg, "image/jpeg", { "Content-Length": jpeg.length, "Cache-Control": "private, max-age=3600" });
+        }
         if (route === "events" && !name) {
             const wanted = this.param(req, "sessions");
             if (wanted === null)

package/dist/engine/replay.js ADDED Viewed

@@ -0,0 +1,348 @@
+/**
+ * The run, as one file that outlives it.
+ *
+ * The live view dies with the engine: its address is a port in a process, so
+ * refreshing after a run is over gets nothing. This builds a self-contained
+ * HTML document instead — the report, and every session's steps grouped by
+ * the task they served — written next to report.md. It opens from the file
+ * system with no server, works offline, and can be handed to somebody who was
+ * never watching.
+ *
+ * Frames appear beside the steps only when the run was recorded
+ * (`scout_attach {record:true}`), which is off by default: a recording is
+ * pictures of somebody's app sitting in their project folder, and ADR 7's
+ * "no frame touches the disk" is the rule it deliberately relaxes. The
+ * document is built the same way either way; a step with no frame simply
+ * shows none.
+ *
+ * Everything here is pure string work — no browser, no filesystem — so the
+ * escaping and the grouping are table-tested.
+ */
+import path from "node:path";
+/** Most frames one recorded session keeps. A long run is thousands of actions, and a project folder is not a video store. */
+export const RECORD_MAX_FRAMES = 600;
+/**
+ * Where a recorded frame is stored, relative to the memory directory — and
+ * the path the live view serves it at, so it is always written with forward
+ * slashes. The session name is the agent's and the action the tool's, so both
+ * are reduced to a plain file name here: a session called `../../etc` decides
+ * nothing about where the engine writes.
+ */
+export function framePath(session, index, action) {
+    const plain = (text, fallback) => text
+        .replace(/[^a-z0-9._-]+/gi, "-")
+        .replace(/^[.-]+/, "")
+        .slice(0, 60) || fallback;
+    return `recordings/${plain(session, "session")}/${String(index).padStart(4, "0")}-${plain(action, "step")}.jpg`;
+}
+/**
+ * The file a viewer's frame request names, or null when it is not one of this
+ * run's frames. The path comes from a browser and may be anything, so it is
+ * resolved and then required to still be under the recordings directory —
+ * `..`, an absolute path and a sibling directory whose name merely starts the
+ * same way are all refused. The one filesystem rule in the frame route, kept
+ * here so it can be table-tested rather than reached only through HTTP.
+ */
+export function resolveFrame(root, relPath) {
+    if (!relPath)
+        return null;
+    const inside = relPath.replace(/^recordings[\\/]/, "");
+    if (!inside || inside.includes("\0"))
+        return null;
+    // Both sides resolved: on Windows `path.resolve` prefixes the drive, so
+    // comparing its output against a root that has none rejects every frame.
+    const base = path.resolve(root);
+    const file = path.resolve(base, inside);
+    return file.startsWith(base + path.sep) ? file : null;
+}
+/** Text from the app under test reaches this document, so nothing is interpolated unescaped. */
+export function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+}
+/**
+ * A session's steps in the blocks its tasks made. Consecutive steps that
+ * served the same task are one block, so the document reads the way the live
+ * feed did: a change of task is a change of block, and of colour.
+ */
+export function taskBlocks(steps) {
+    const blocks = [];
+    for (const step of steps) {
+        const task = step.task ?? null;
+        const last = blocks[blocks.length - 1];
+        if (!last || last.task !== task)
+            blocks.push({ task, steps: [step] });
+        else
+            last.steps.push(step);
+    }
+    return blocks;
+}
+/** The viewer's own clock is not this document's to assume; times are shown as they were logged. */
+function clock(iso) {
+    const at = iso.length >= 19 ? iso.slice(11, 19) : iso;
+    return at;
+}
+/**
+ * When the document was written. The log is UTC and this page may be opened
+ * anywhere, so it says which clock it is quoting rather than implying the
+ * reader's own.
+ */
+function stamp(iso) {
+    return iso.length >= 16 ? `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC` : iso;
+}
+/**
+ * What an image that will not load does. This page is meant to be handed on,
+ * and a copy sent without its `recordings/` folder would otherwise show a row
+ * of broken icons under a finding that still counts them as evidence.
+ */
+const GONE = `onerror="this.parentNode.classList.add('gone')"`;
+/** A result that reads as a failure, so a step that went wrong is visible without reading every line. */
+const BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
+function renderStep(step, framePrefix = "", savedAt = "") {
+    const detail = [step.target, step.result ? `→ ${step.result}` : ""].filter(Boolean).join(" ") || step.url || "";
+    const bad = BAD_RESULT.test(step.result ?? "") ? " bad" : "";
+    const frame = step.frame
+        ? `<a class="frame" href="${escapeHtml(framePrefix + step.frame)}" target="_blank" rel="noreferrer"><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + step.frame)}" alt="What the page showed at this step"></a>`
+        : "";
+    const where = savedAt && step.frame ? `<p class="onDisk">${escapeHtml(savedAt + "/" + step.frame)}</p>` : "";
+    return (`<li class="step"><div class="row"><span class="t">${escapeHtml(clock(step.at))}</span>` +
+        `<span class="a${bad}">${escapeHtml(step.action)}</span>` +
+        `<span class="d" title="${escapeHtml([step.target, step.result, step.url].filter(Boolean).join(" · "))}">${escapeHtml(detail)}</span></div>${frame}${where}</li>`);
+}
+function renderSession(s, index, framePrefix = "", savedAt = "") {
+    const blocks = taskBlocks(s.steps);
+    const body = blocks
+        .map((b, i) => {
+        const head = b.task ? `<p class="task">${escapeHtml(b.task)}</p>` : `<p class="task none">No task stated for these</p>`;
+        return `<section class="block g${i % 4}">${head}<ol class="steps">${b.steps.map((step) => renderStep(step, framePrefix, savedAt)).join("")}</ol></section>`;
+    })
+        .join("");
+    const framed = s.steps.filter((x) => x.frame).length;
+    return (`<details class="session"${index === 0 ? " open" : ""}><summary><b>${escapeHtml(s.session)}</b> <span class="role">${escapeHtml(s.role)}</span>` +
+        `<span class="count">${s.steps.length} steps · ${blocks.length} task${blocks.length === 1 ? "" : "s"}${framed ? ` · ${framed} frames` : ""}</span></summary>` +
+        (s.objective ? `<p class="objective">${escapeHtml(s.objective)}</p>` : "") +
+        body +
+        `</details>`);
+}
+/**
+ * The steps that were on screen just before a finding was filed. The report's
+ * own repro trace says what happened; on a recorded run these show it.
+ */
+export function evidenceFor(steps, foundAt, most = 4) {
+    const before = steps.filter((x) => x.frame && x.at <= foundAt);
+    return before.slice(-most).map((x) => ({
+        at: x.at,
+        action: x.action,
+        detail: [x.target, x.result ? `→ ${x.result}` : ""].filter(Boolean).join(" ") || x.url || "",
+        frame: x.frame,
+    }));
+}
+function renderEvidence(e, framePrefix = "", savedAt = "") {
+    if (e.frames.length === 0)
+        return "";
+    const shots = e.frames
+        .map((f) => `<figure><img loading="lazy" ${GONE} src="${escapeHtml(framePrefix + f.frame)}" alt="The page when this step ran">` +
+        `<p class="gone-note">This frame is not beside this file. Frames live in the run's <code>recordings/</code> folder, which travels with it.</p>` +
+        `<figcaption>${escapeHtml(clock(f.at))} <b>${escapeHtml(f.action)}</b> ${escapeHtml(f.detail)}` +
+        (savedAt ? `<span class="onDisk">${escapeHtml(savedAt + "/" + f.frame)}</span>` : "") +
+        `</figcaption></figure>`)
+        .join("");
+    return `<details class="evidence"><summary>Evidence — the ${e.frames.length} step${e.frames.length === 1 ? "" : "s"} on screen before this was filed</summary><div class="shots">${shots}</div></details>`;
+}
+/**
+ * The report's markdown as elements. A deliberately small subset — headings,
+ * tables, lists, code fences, the report's own <details> repro blocks — built
+ * by escaping every piece of text, because finding titles and element names
+ * come from the app under test.
+ */
+export function renderMarkdown(md, evidence = [], framePrefix = "", savedAt = "") {
+    const out = [];
+    const lines = md.split("\n");
+    let i = 0;
+    let para = [];
+    const inline = (text) => escapeHtml(text)
+        .replace(/`([^`]+)`/g, "<code>$1</code>")
+        .replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    const flush = () => {
+        if (para.length)
+            out.push(`<p>${inline(para.join(" "))}</p>`);
+        para = [];
+    };
+    while (i < lines.length) {
+        const line = lines[i];
+        let m;
+        if (/^```/.test(line)) {
+            flush();
+            const code = [];
+            i += 1;
+            while (i < lines.length && !/^```/.test(lines[i])) {
+                code.push(lines[i]);
+                i += 1;
+            }
+            i += 1;
+            out.push(`<pre><code>${escapeHtml(code.join("\n"))}</code></pre>`);
+        }
+        else if ((m = /^(#{1,6}) (.*)$/.exec(line))) {
+            flush();
+            const level = Math.min(6, m[1].length + 1);
+            out.push(`<h${level}>${inline(m[2])}</h${level}>`);
+            i += 1;
+        }
+        else if ((m = /^<details><summary>(.*)<\/summary>$/.exec(line))) {
+            flush();
+            out.push(`<details><summary>${inline(m[1])}</summary>`);
+            i += 1;
+        }
+        else if (/^<\/details>$/.test(line)) {
+            flush();
+            out.push(`</details>`);
+            i += 1;
+        }
+        else if (/^\|/.test(line)) {
+            flush();
+            const rows = [];
+            let first = true;
+            while (i < lines.length && /^\|/.test(lines[i])) {
+                const row = lines[i];
+                i += 1;
+                if (/^\|(\s*:?-+:?\s*\|)+\s*$/.test(row))
+                    continue;
+                const cells = row
+                    .replace(/^\||\|\s*$/g, "")
+                    .split("|")
+                    .map((c) => `<${first ? "th" : "td"}>${inline(c.trim())}</${first ? "th" : "td"}>`);
+                rows.push(`<tr>${cells.join("")}</tr>`);
+                first = false;
+            }
+            out.push(`<table>${rows.join("")}</table>`);
+        }
+        else if (/^\s*[-*] /.test(line)) {
+            flush();
+            const items = [];
+            // A finding's id sits in this list; its evidence goes straight under it,
+            // which is where a reader is when they ask "show me".
+            let found;
+            while (i < lines.length && (m = /^\s*[-*] (.*)$/.exec(lines[i]))) {
+                const id = /\*\*Id:\*\* `([0-9a-f]+)`/.exec(m[1])?.[1];
+                if (id)
+                    found = evidence.find((e) => e.id === id);
+                items.push(`<li>${inline(m[1])}</li>`);
+                i += 1;
+            }
+            out.push(`<ul>${items.join("")}</ul>`);
+            if (found)
+                out.push(renderEvidence(found, framePrefix, savedAt));
+        }
+        else if (/^\d+\. /.test(line)) {
+            flush();
+            const items = [];
+            while (i < lines.length && (m = /^\d+\. (.*)$/.exec(lines[i]))) {
+                items.push(`<li>${inline(m[1])}</li>`);
+                i += 1;
+            }
+            out.push(`<ol>${items.join("")}</ol>`);
+        }
+        else if (line.trim() === "") {
+            flush();
+            i += 1;
+        }
+        else {
+            para.push(line);
+            i += 1;
+        }
+    }
+    flush();
+    return out.join("\n");
+}
+const STYLE = `
+:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --bad:#b91c1c; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --bad:#fca5a5; } }
+* { box-sizing: border-box; }
+body { margin:0; background:var(--bg); color:var(--text); font:15px/1.55 system-ui,-apple-system,"Segoe UI",sans-serif; }
+header { position:sticky; top:0; z-index:2; display:flex; flex-wrap:wrap; gap:8px 16px; align-items:baseline; padding:14px 20px; background:var(--panel); border-bottom:1px solid var(--line); }
+header h1 { margin:0; font-size:17px; }
+header .meta { color:var(--muted); font-size:13px; }
+nav { margin-left:auto; display:flex; gap:12px; font-size:14px; }
+nav a { color:var(--accent); }
+main { max-width:1000px; margin:0 auto; padding:24px 20px 64px; }
+h2 { font-size:21px; margin:32px 0 12px; padding-top:20px; border-top:1px solid var(--line); }
+h3 { font-size:17px; margin:24px 0 8px; }
+h4 { font-size:15px; margin:20px 0 6px; }
+table { border-collapse:collapse; margin:10px 0 16px; font-size:13px; }
+th, td { border:1px solid var(--line); padding:5px 9px; text-align:left; vertical-align:top; }
+th { background:var(--panel); }
+code { font:12px/1.4 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; background:var(--panel); border:1px solid var(--line); border-radius:4px; padding:0 4px; }
+pre { padding:12px; background:var(--panel); border:1px solid var(--line); border-radius:6px; overflow-x:auto; }
+pre code { border:0; padding:0; background:none; }
+details.session { background:var(--panel); border:1px solid var(--line); border-radius:8px; margin:12px 0; padding:10px 14px; }
+details.session > summary { cursor:pointer; font-size:15px; display:flex; gap:10px; align-items:baseline; }
+details.session .role { color:var(--muted); font-size:13px; }
+details.session .count { margin-left:auto; color:var(--muted); font-size:12px; }
+.objective { margin:8px 0 14px; color:var(--muted); }
+.block { border-left:2px solid transparent; border-radius:4px; padding:6px 10px; margin:8px 0; }
+.block.g0 { background:rgba(96,165,250,.22); border-color:rgba(96,165,250,.85); }
+.block.g1 { background:rgba(52,211,153,.22); border-color:rgba(52,211,153,.85); }
+.block.g2 { background:rgba(251,191,36,.24); border-color:rgba(251,191,36,.9); }
+.block.g3 { background:rgba(244,114,182,.22); border-color:rgba(244,114,182,.85); }
+@media (prefers-color-scheme: light) {
+  .block.g0 { background:rgba(37,99,235,.13); } .block.g1 { background:rgba(5,150,105,.13); }
+  .block.g2 { background:rgba(217,119,6,.15); } .block.g3 { background:rgba(219,39,119,.12); }
+}
+.task { margin:2px 0 8px; font-weight:600; }
+.task.none { font-weight:400; color:var(--muted); font-style:italic; }
+ol.steps { list-style:none; margin:0; padding:0; }
+.step { margin:0 0 2px; }
+.step .row { display:flex; gap:8px; font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+.step .t { color:var(--muted); flex:0 0 auto; }
+.step .a { font-weight:600; flex:0 0 auto; }
+.step .a.bad { color:var(--bad); }
+.step .d { color:var(--muted); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+.step .frame { display:block; margin:4px 0 10px; }
+.step .frame img { max-width:min(100%,720px); max-height:360px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+details.evidence { margin:6px 0 18px; padding:8px 12px; background:var(--panel); border:1px solid var(--line); border-radius:8px; }
+details.evidence > summary { cursor:pointer; color:var(--muted); font-size:13px; }
+details.evidence .shots { display:flex; flex-wrap:wrap; gap:14px; margin-top:12px; }
+details.evidence figure { margin:0; max-width:min(100%,460px); }
+details.evidence img { width:100%; max-height:300px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+.onDisk { display:block; margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+header .served { flex:1 1 100%; margin:6px 0 0; color:var(--muted); font-size:12px; }
+header .served code { font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+.gone-note { display:none; margin:0; padding:14px; border:1px dashed var(--line); border-radius:6px; color:var(--muted); font-size:12px; }
+figure.gone .gone-note, a.gone .gone-note { display:block; }
+figure.gone img, a.gone img { display:none; }
+a.frame.gone { display:block; max-width:min(100%,720px); }
+details.evidence figcaption { margin-top:4px; color:var(--muted); font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+`;
+/** The whole document: one file, no external assets, opens from the file system. */
+export function buildReplayHtml(input) {
+    const framed = input.sessions.some((s) => s.steps.some((x) => x.frame));
+    const prefix = input.framePrefix ?? "";
+    const savedAt = input.savedAt ?? "";
+    const sessions = input.sessions.map((s, i) => renderSession(s, i, prefix, savedAt)).join("\n");
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SceneScout run — ${escapeHtml(input.project)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>SceneScout run</h1>
+  <span class="meta">${escapeHtml(input.project)} · written ${escapeHtml(stamp(input.at))}${input.version ? ` · v${escapeHtml(input.version)}` : ""}</span>
+  ${savedAt ? `<p class="served">This page is served by the engine and goes when it does. The copy that stays is <code>${escapeHtml(savedAt)}/report.html</code>, beside the frames it shows.</p>` : ""}
+  <nav><a href="#report">Report</a><a href="#steps">Steps</a></nav>
+</header>
+<main>
+<h2 id="report">Report</h2>
+${renderMarkdown(input.markdown, input.evidence ?? [], prefix, savedAt)}
+<h2 id="steps">What each session did</h2>
+<p class="objective">Every action, in the blocks its tasks made. ${framed
+        ? "Each step shows the page as it was; click a frame to open it full size."
+        : "This run was not recorded, so there are no frames — attach with record:true to keep them."}</p>
+${sessions || "<p>No session recorded any action.</p>"}
+</main>
+</body>
+</html>
+`;
+}

package/dist/engine/report.js CHANGED Viewed

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { SHARED_CHROME_ROUTE } from "./memory.js";
+import { feedForSession } from "./live.js";
+import { buildReplayHtml, evidenceFor } from "./replay.js";
 function playwrightSkeleton(f) {
     const routeClass = f.state.split("#")[0].split("?")[0];
     let gotoPath = routeClass;
@@ -56,6 +58,66 @@ function violationRollup(oracleLog) {
 }
 const SEVERITY_ORDER = { high: 0, medium: 1, low: 2 };
 const SEVERITY_ICON = { high: "🔴", medium: "🟠", low: "🟡" };
+/**
+ * What to call the project in a document meant to be handed on. The memory
+ * directory's absolute path names a person's home directory and often the
+ * machine it ran on; the project's own folder name says which project it was
+ * without any of that.
+ */
+function projectName(dir) {
+    const parent = path.dirname(dir);
+    return path.basename(parent) || path.basename(dir) || "project";
+}
+/** Every session that did anything, with its steps in order — what the HTML replays. */
+function replaySessions(memory) {
+    const names = [...new Set(memory.actionLog.map((e) => e.session ?? "default"))];
+    return names.map((session) => ({
+        session,
+        // The role a session ran as is not on the log's entries; until it is, the
+        // session's own name is the honest label rather than a guess from coverage.
+        role: "",
+        // No redactor: the log is redacted as it is WRITTEN (memory.logAction
+        // covers url, target and result), so what is stored is already clean.
+        // Filtering again here would run a regex over every step of a long run to
+        // find what cannot be there. `replay-redaction` in contract-test pins it.
+        steps: feedForSession(memory.actionLog, session, Number.MAX_SAFE_INTEGER),
+    }));
+}
+/** The frames that were on screen while each finding was being found. */
+export function findingEvidence(memory, sessions) {
+    const all = sessions.flatMap((s) => s.steps).sort((a, b) => a.at.localeCompare(b.at));
+    return memory.findings
+        .map((f) => {
+        // The session that filed it, where it said so: with three browsers
+        // running at once, the run's whole log interleaves them, and the steps
+        // before a finding would come from whichever lane acted last.
+        const own = f.session ? sessions.find((s) => s.session === f.session) : undefined;
+        return { id: f.id, frames: evidenceFor(own ? own.steps : all, f.foundAt) };
+    })
+        .filter((e) => e.frames.length > 0);
+}
+/**
+ * The whole run as one page, for the live view to serve at its own address.
+ * Frames go through the view's own route, since the browser is reading this
+ * over HTTP rather than from the folder the frames live in.
+ */
+export function replayDocument(memory, markdown, version = "") {
+    const sessions = replaySessions(memory);
+    return buildReplayHtml({
+        markdown,
+        sessions,
+        evidence: findingEvidence(memory, sessions),
+        project: projectName(memory.dir),
+        at: new Date().toISOString(),
+        version,
+        framePrefix: "record/",
+        savedAt: memory.dir,
+    });
+}
+/** What the live view shows under each finding on a recorded run: the frames it was found on. */
+export function reportEvidence(memory) {
+    return findingEvidence(memory, replaySessions(memory));
+}
 /**
  * Split an element key into words. Keys are `tid:some-test-id` or `role:name`,
  * and testids come in every casing convention there is — a `\b`-anchored regex
@@ -492,13 +554,51 @@ export function generateReport(memory, oracleLog, extras, opts = {}) {
     }
     const markdown = lines.join("\n");
     const outPath = path.join(memory.dir, "report.md");
-    if (opts.write !== false)
+    const htmlPath = path.join(memory.dir, "report.html");
+    let htmlWritten = false;
+    let htmlProblem = "";
+    if (opts.write !== false) {
         fs.writeFileSync(outPath, markdown);
+        // The same run as one file that outlives the engine: the live view's
+        // address is a port in a process, and refreshing after the run is over
+        // gets nothing. This opens from the file system, offline, forever.
+        try {
+            const sessions = replaySessions(memory);
+            fs.writeFileSync(htmlPath, buildReplayHtml({
+                markdown,
+                sessions,
+                evidence: findingEvidence(memory, sessions),
+                project: projectName(memory.dir),
+                at: new Date().toISOString(),
+                version: extras?.version ?? "",
+            }));
+            htmlWritten = true;
+        }
+        catch (err) {
+            // The markdown is the report of record and is already on disk, so this
+            // must not fail the report — but the summary then says what went wrong
+            // rather than naming a file that is not there.
+            htmlProblem = err instanceof Error ? err.message : String(err);
+            // An earlier run's page would otherwise sit beside a fresh report.md,
+            // carrying its own timestamp, looking like this run.
+            try {
+                fs.rmSync(htmlPath, { force: true });
+            }
+            catch {
+                htmlProblem += "; an older one may still be beside it";
+            }
+        }
+    }
     // Bounded summary for the tool result: full reports have exceeded client
     // token limits in real runs (66–72KB observed) — the wire gets the digest,
     // the disk gets the document.
     const summaryLines = [
         `Report written to ${outPath}`,
+        ...(htmlWritten
+            ? [`The same run as one page, with every session's steps: ${htmlPath}`]
+            : htmlProblem
+                ? [`The one-page version of this run could NOT be written (${htmlProblem}); ${outPath} is unaffected.`]
+                : []),
         ``,
         `OPEN FINDINGS: ${open.length} (${open.filter((f) => f.severity === "high").length} high) — ${current.length} this session, ${historical.length} historical${resolved.length ? `, ${resolved.length} resolved` : ""}`,
         ...(extras && extras.routesTotal > 0