scenescout 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # scenescout
 
+## 3.1.0
+
+### Minor Changes
+
+- 52d97d8: Record a run, and read the whole thing back afterwards.
+  
+  `scout_attach {record: true}` keeps a frame of the page after every action, and
+  `scout_report` then writes `report.html` beside `report.md`: the report, the
+  screenshots taken around each finding, and every session's trail in the blocks
+  its tasks made — one self-contained page that opens from the file system with
+  nothing running. Recording is off unless asked for, because the frames are
+  pictures of the app under test and no redaction can read a picture
+  ([ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md)).
+  
+  The live view serves the same document at its own address and goes there when
+  the run ends, so the report survives a refresh instead of dying with the board.
+  The close-up gains a timeline: a tick per action, coloured by task, that plays
+  a recorded run back while it is still going. A finding's screenshots also hang
+  under it in the live report panel, which no longer resets itself while it is
+  being read.
+  
+  Fixes: a listener left on a control that had been replaced threw on load and
+  left the board blank; a viewer arriving after the last browser closed saw the
+  empty state instead of the finished run; a finding's evidence could be drawn
+  from a different session than the one that filed it.
+
+## 3.0.1
+
+### Patch Changes
+
+- f99062d: The close-up's feed shows one pastel tint per task again, so a change of task is a change of colour and the block of actions a task covers is legible at a glance; hovering a block names the task in the brief, under the session's objective. The tints are lifted on a light card so they read the same either way. A close-up with no frame now says "No frame available" like a card does, instead of showing a broken-image icon.
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -187,28 +187,67 @@ The agent scans the project (if there is one), attaches read-only, explores, and
 
 When a session attaches, the engine starts a small live view and hands the agent its address on a `Live view:` line, which the agent passes on to you. From a terminal, `scenescout watch` opens the same page. There is one card per session:
 
-<p align="center"><img src="examples/screenshots/live-view.png" alt="The live view during a run of six parallel agents against the demo app: one card per session, each with its role, the tool it is running and for how long, the page it is on, a thumbnail, and a feed of the actions it just took" width="880" /></p>
+<p align="center"><img src="examples/screenshots/live-view.png" alt="The live view during a run of three parallel agents against the demo app: one card per session, each with its role and objective, the task it is on, the tool it is running, the page it is on, a live thumbnail, and a feed of the actions it just took, tinted one colour per task" width="880" /></p>
 
 - **What it is doing:** the tool it is running and for how long, the page it is on, and a thumbnail of that page. This works for headless runs too, which have no window to look at.
 - **What it just did:** a rolling feed of its actions, each with its target and how it turned out, with failures in red. It is the same trail a finding's repro trace uses. The engine never sees the agent's reasoning, so this is what the session *did*, not what it thought.
 - **Stuck, not slow:** a call still running past its own tool's watchdog budget turns the card red, so a wedged session is visible without asking. A crawl legitimately runs for minutes; it is judged against the crawl's budget, not a click's.
 - **Live stream:** switch it on for one card, or for all of them. Click a thumbnail for a close-up.
 - **The report, as it stands:** the Report button in the top bar shows the same document `scout_report` writes at the end, rendered from the run's current state, so findings can be read while the agents are still working.
-- **What it is for:** the close-up puts the feed beside the session's brief: the task the agent gave it when it attached (`scout_attach {task}`), and the goal of the journey it is on right now (`scout_journey`). Actions of one journey share a tint in the feed; point at a group and the brief shows the goal those actions served.
+- **What it is for:** the close-up puts the feed beside the session's brief — the objective it was given when it attached (`scout_attach {objective}`), and underneath it the task it is on right now (`scout_task`), which the engine requires before any tool will act. Each task tints its own block of actions, so a change of task is a change of colour; point at a block and the brief names the task those actions served.
+- **Scrub it back:** under the page is a tick per action, coloured by task. Click one to see the frame from that moment, and `Back to live` to return. On a run that was not recorded the ticks still read the trail; they just have no picture behind them.
 
-<p align="center"><img src="examples/screenshots/live-view-closeup.png" alt="A close-up of one session: its page streaming live, the feed of its recent actions grouped by journey, and beside it the task and current objective" width="880" /></p>
+<p align="center"><img src="examples/screenshots/live-view-closeup.png" alt="A close-up of one session: a frame from a step picked out of the timeline, the timeline itself as a tick per action coloured by task, the feed of the session's actions in the same colours, and beside it the objective and the task it is on" width="880" /></p>
 
-<p align="center"><img src="examples/screenshots/live-view-report.png" alt="The report opened from the live view's top bar while the run is still going: summary table, gap ledger and the findings filed so far" width="880" /></p>
+<p align="center"><img src="examples/screenshots/live-view-report.png" alt="The report opened from the live view's top bar while the run is still going: summary table, gap ledger, and the findings filed so far, each with an accordion of the screenshots taken around it" width="880" /></p>
 
-The view is served on `127.0.0.1` only, behind a token that changes every time the engine starts. It answers `GET` and nothing else, so a viewer can watch a run but not act in it, and no frame is ever written to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)). A stream runs only while someone is watching it. `SCENESCOUT_LIVE=off` keeps the port closed.
+The view is served on `127.0.0.1` only, behind a token that changes every time the engine starts. It answers `GET` and nothing else, so a viewer can watch a run but not act in it, and no frame it shows is written to disk ([ADR 7](docs/adr/0007-the-live-view-is-local-read-only-and-leaves-nothing-behind.md)) unless the run was recorded, which is asked for and off by default ([ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md)). A stream runs only while someone is watching it. `SCENESCOUT_LIVE=off` keeps the port closed.
 
-**Try it with parallel agents.** The demo app has three roles and several separate areas, so a run can be split between agents. Start it with `npm run demo:serve`, then ask your agent to explore it with several agents in parallel, one role and one area each. The pictures above come from a run of six. Two things keep a parallel run efficient:
+**Try it with parallel agents.** The demo app has three roles and several separate areas, so a run can be split between agents. Start it with `npm run demo:serve`, then ask your agent to explore it with several agents in parallel, one role and one area each. The pictures above come from a run of three. Two things keep a parallel run efficient:
 
 - **Each agent opens its own session when it starts and closes it when it is done.** An agent waiting for its turn then holds no browser. Opening every session up front leaves browsers idling while the machine runs out of memory for the agents that are working.
 - **Run about as many agents at once as your machine has cores, less two.** Each one drives a real browser.
 
 ---
 
+## 🎬 Recording a run, and reading it back
+
+A report says what happened. For QA work that is not always enough — the point
+is often to *show* what was checked, not to assert it. Ask for a recorded run
+and the engine keeps a frame of the page after every action:
+
+```
+Use SceneScout to test http://localhost:3000, record the run
+```
+
+or, on the tool directly, `scout_attach {record: true}`.
+
+Then `scout_report` writes two files side by side in `.scenescout/`:
+`report.md` as always, and `report.html` — the whole run as one self-contained
+page. It opens from the file system with nothing running, needs no network, and
+holds:
+
+- **The report**, rendered from the same Markdown.
+- **The screenshots around each finding**, in an accordion under it, from the
+  session that filed it.
+- **Every session's trail**, in the blocks its tasks made, each step with the
+  page as it was at that moment.
+
+<p align="center"><img src="examples/screenshots/run-page.png" alt="The saved copy of a run, opened from the file system with nothing running: a finding with its evidence accordion open, showing the four screenshots taken around it with the action and time under each" width="880" /></p>
+
+The live view serves the same document at `run` while the engine is still up,
+and sends you there when the run ends — so the address survives a refresh
+instead of a panel over a dead board.
+
+**What it costs.** Frames are pictures of the app under test, inside the tested
+project's folder, and the secret redaction that protects everything else the
+engine writes cannot read a picture. That is why it is off unless asked for,
+capped per session, and written only under `.scenescout/`, which ignores itself
+so `git add -A` in the tested project cannot pick the frames up. The reasoning is in
+[ADR 8](docs/adr/0008-a-recorded-run-is-evidence-and-must-be-asked-for.md).
+
+---
+
 ## 🔄 How a run works
 
 One curiosity loop, repeated — breadth first, then judgment where it matters:
@@ -242,7 +281,7 @@ Snapshots are cheap: re-snapshotting a route returns only *what changed*, with s
 | **Look** | `scout_snapshot` `scout_hover` `scout_screenshot` | Read the structured scene (diffed); reveal tooltips/hover cards; capture pixels only when needed |
 | **Act** | `scout_click` `scout_type` `scout_select` `scout_upload` `scout_press` `scout_scroll` `scout_navigate` `scout_back` `scout_run_plan` | Drive the UI like a user; `scout_run_plan` batches a whole mechanical sequence into one call |
 | **Assess** | `scout_design_audit` `scout_journey` | Score a page's craft/a11y/consistency; measure how hard a task is to complete |
-| **Record** | `scout_note` `scout_finding` `scout_resolve` `scout_report` | Curate durable notes; file deduped findings; mark fixes; generate the report |
+| **Record** | `scout_note` `scout_finding` `scout_resolve` `scout_report` | Curate durable notes; file deduped findings; mark fixes; write the report, and on a recorded run the whole run as one page |
 | **Close** | `scout_close` | Tear down one session or all |
 
 A few that punch above their weight:
@@ -290,6 +329,8 @@ A `🛡 WRITE-POLICY blocked` notice is the safety net doing its job, not an app
 - 👥 **A role capability matrix** — what each role could and couldn't reach.
 - 🧾 **A gap ledger** — everything *not* done, so the report is honest about its own coverage.
 
+`.scenescout/report.html` — the same report as one self-contained page, with every session's trail beside it, and on a [recorded run](#-recording-a-run-and-reading-it-back) the screenshots under each finding.
+
 👀 Watch a run live: `node dist/cli.js status <project-path>`.
 
 ---
@@ -514,8 +555,9 @@ src/
     design.ts       the design audit + page scoring
     memory.ts       cross-run storage + finding dedup
     report.ts       the gap ledger + report generation
+    replay.ts       the run as one page: steps, tasks, frames under each finding
     …               collector · dispatch · fixtures · authloss · reaper
-scripts/            the 12 test suites (smoke/ holds the real-browser ones)
+scripts/            the 14 test suites (smoke/ holds the real-browser ones)
 test-app/           fixtures for the real-browser smoke tests
 skills/scenescout/   the testing method (SKILL.md): a skill in Claude Code, served by the server everywhere else
 docs/adr/           why it's built this way

package/dist/engine/browser.js

@@ -10,6 +10,7 @@ import { COLLECT_INTERACTABLES_SCRIPT, VISIBLE_SRC, geometryIssues, BROKEN_IMAGE
 import { OracleMonitor, formatViolations } from "./oracles.js";
 import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js";
 import { formatJourney, measureJourney } from "./journey.js";
+import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
 import { defaultEngine, focusAdvanceKey, REMOVE_SHARED_WORKER_SCRIPT, screencastSupport, serviceWorkerPolicy, sharedWorkersAllowed, } from "../browsers.js";
 import { revealedLines } from "./hover.js";
 import { explainLaunchFailure, isMissingBrowser } from "./launch.js";
@@ -102,6 +103,8 @@ function actionabilityDiagnostic(message) {
  */
 /** A screencast whose page has been gone for this many 500 ms ticks ends and says so; a re-attach takes fewer. */
 const SCREENCAST_PAGELESS_TICKS = 20;
+/** A frame for the record is worth a moment, not a stall: the action has already happened. */
+const RECORD_SHOT_TIMEOUT_MS = 2500;
 export class BrowserEngine {
     browser = null;
     context = null;
@@ -206,6 +209,57 @@ export class BrowserEngine {
     journey = null;
     /** The session's objective: the whole remit the agent was given at scout_attach. Empty when none was given. */
     sessionObjective = "";
+    /**
+     * Keep a frame of the page after each action, as evidence. Off by default:
+     * a recording is pictures of somebody's app sitting in their project
+     * folder, which is the rule ADR 7 otherwise holds ("no frame touches the
+     * disk"). QA work is what earns the exception — a report says what was
+     * checked, a recording shows it.
+     */
+    recording = false;
+    framesKept = 0;
+    /** How many frames could not be written. The first one says so in the log; the rest are counted. */
+    framesFailed = 0;
+    /**
+     * The frame for the step just taken, as a path relative to the memory
+     * directory, or undefined when this run is not recorded. Failing to write
+     * one must never fail the action: evidence is worth having, not worth
+     * losing a run over.
+     */
+    async recordFrame(action) {
+        const dir = this.memory?.dir;
+        if (!this.recording || !dir || this.framesKept >= RECORD_MAX_FRAMES)
+            return undefined;
+        const jpeg = await this.liveShot(RECORD_SHOT_TIMEOUT_MS);
+        if (!jpeg)
+            return undefined;
+        const rel = framePath(this.sessionKey, this.framesKept + 1, action);
+        try {
+            await fs.promises.mkdir(path.dirname(path.join(dir, rel)), { recursive: true });
+            await fs.promises.writeFile(path.join(dir, rel), jpeg);
+        }
+        catch (err) {
+            // A frame that cannot be written must not fail the action, but a run
+            // that keeps NOTHING — a read-only checkout, a full disk — would
+            // otherwise finish silently and produce a report with no evidence in
+            // it, which is the one thing recording exists to prevent. Said once,
+            // through the action log, so it reaches the live feed and the report.
+            this.framesFailed += 1;
+            if (this.framesFailed === 1) {
+                this.logAction({
+                    action: "record:failed",
+                    target: `no frame could be written under ${dir} (${err instanceof Error ? err.message : String(err)}); later failures are not repeated here`,
+                    url: this.page?.url() ?? "",
+                });
+            }
+            return undefined;
+        }
+        this.framesKept += 1;
+        if (this.framesKept === RECORD_MAX_FRAMES) {
+            this.logAction({ action: "record:full", target: `${RECORD_MAX_FRAMES} frames kept; later steps have none`, url: this.page?.url() ?? "" });
+        }
+        return rel;
+    }
     /**
      * The batch of actions running right now. Required before a tool may act
      * (task.ts), stated by the agent on the call or by a journey, and kept
@@ -352,6 +406,11 @@ export class BrowserEngine {
         }
         this.mode = opts.mode ?? "read-only";
         this.sessionObjective = (opts.objective ?? "").trim().replace(/\s+/g, " ").slice(0, 300);
+        this.recording = opts.record === true;
+        // A re-attached engine starts a new recording: numbering from where the
+        // last one stopped would run into the cap with frames it never took.
+        this.framesKept = 0;
+        this.framesFailed = 0;
         this.headed = opts.headed ?? false;
         this.blockedRequests = [];
         this.pendingCreations = new Set();
@@ -887,7 +946,8 @@ export class BrowserEngine {
                 blocked +
                 formatViolations(this.oracles.drain()));
         }
-        this.logAction({ action, target, url });
+        const frame = await this.recordFrame(action);
+        this.logAction({ action, target, url, ...(frame ? { frame } : {}) });
         await this.scanForInjections();
         const violations = this.oracles.drain();
         const mutations = this.drainMutations() + this.drainBlocked() + this.drainCreated();

package/dist/engine/live-page.js

@@ -54,7 +54,8 @@ export const LIVE_PAGE = `<!doctype html>
   #finished h2 { margin: 0 0 8px; font-size: 18px; }
   #finished p { margin: 0 0 8px; color: var(--muted); }
   #finished .where { font: 12px/1.6 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; overflow-wrap: anywhere; }
-  #finished button { margin-top: 8px; padding: 7px 14px; font-weight: 600; }
+  #finished .btn { display: inline-block; margin-top: 8px; padding: 8px 16px; font-weight: 600; text-decoration: none;
+    color: #fff; background: var(--accent); border-radius: 6px; }
   main { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 320px), 1fr)); gap: 12px; padding: 16px; }
   .card { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; display: flex; flex-direction: column; }
   .card.stuck { border-color: var(--stuck); }
@@ -82,12 +83,23 @@ export const LIVE_PAGE = `<!doctype html>
     font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; max-height: 108px; overflow-y: auto; overscroll-behavior: contain; }
   .feed .row { display: flex; gap: 6px; white-space: nowrap; }
   /* Consecutive actions of one journey share a tint, so where one goal ends and the next begins is visible in the log. */
-  .feed .group { border-left: 1px solid transparent; padding-left: 5px; margin-left: -6px; border-radius: 3px; }
-  .feed .g0 { background: rgba(96, 165, 250, .13); border-color: rgba(96, 165, 250, .7); }
-  .feed .g1 { background: rgba(52, 211, 153, .13); border-color: rgba(52, 211, 153, .7); }
-  .feed .g2 { background: rgba(251, 191, 36, .13); border-color: rgba(251, 191, 36, .7); }
-  .feed .g3 { background: rgba(244, 114, 182, .13); border-color: rgba(244, 114, 182, .7); }
-  #focus .feed .group:hover { outline: 1px solid rgba(230, 233, 238, .35); }
+  /* One tint per task, so a change of task is a change of colour: the block of
+     actions a task covers is legible at a glance, and hovering it names the task. */
+  .feed .group { border-left: 2px solid transparent; padding-left: 6px; margin-left: -8px; border-radius: 4px; margin-bottom: 2px; }
+  .feed .g0 { background: rgba(96, 165, 250, .22); border-color: rgba(96, 165, 250, .85); }
+  .feed .g1 { background: rgba(52, 211, 153, .22); border-color: rgba(52, 211, 153, .85); }
+  .feed .g2 { background: rgba(251, 191, 36, .24); border-color: rgba(251, 191, 36, .9); }
+  .feed .g3 { background: rgba(244, 114, 182, .22); border-color: rgba(244, 114, 182, .85); }
+  .feed .group:hover { cursor: default; }
+  #focus .feed .group:hover { outline: 1px solid rgba(230, 233, 238, .45); }
+  /* The tints sit on a dark panel in the close-up and on a light one in a card;
+     lift them there so they read as the same pastel either way. */
+  @media (prefers-color-scheme: light) {
+    :root:not([data-theme="dark"]) .feed .g0 { background: rgba(37, 99, 235, .14); }
+    :root:not([data-theme="dark"]) .feed .g1 { background: rgba(5, 150, 105, .14); }
+    :root:not([data-theme="dark"]) .feed .g2 { background: rgba(217, 119, 6, .16); }
+    :root:not([data-theme="dark"]) .feed .g3 { background: rgba(219, 39, 119, .13); }
+  }
   .feed .t { color: var(--muted); flex: 0 0 auto; }
   .feed .a { color: var(--text); font-weight: 600; flex: 0 0 auto; }
   .feed .d { color: var(--muted); overflow: hidden; text-overflow: ellipsis; }
@@ -116,7 +128,24 @@ export const LIVE_PAGE = `<!doctype html>
   #focus .bar { display: flex; align-items: center; gap: 12px; color: #fff; }
   #focus .bar .line { color: #cbd5e1; padding: 0; flex: 1 1 auto; }
   #focus .bar .line b { color: #fff; }
-  #focus img { flex: 1 1 auto; min-height: 0; width: 100%; object-fit: contain; background: #000; border-radius: 6px; }
+  #focus .stage { flex: 1 1 auto; min-height: 0; position: relative; }
+  #timeline { flex: 0 0 auto; display: flex; gap: 2px; overflow-x: auto; padding: 6px 0 2px; scrollbar-width: thin; }
+  #timeline button { flex: 0 0 auto; width: 16px; height: 26px; padding: 0; border: 0; border-radius: 3px; cursor: pointer;
+    background: rgba(230,233,238,.18); }
+  #timeline button.g0 { background: rgba(96,165,250,.75); } #timeline button.g1 { background: rgba(52,211,153,.75); }
+  #timeline button.g2 { background: rgba(251,191,36,.8); }  #timeline button.g3 { background: rgba(244,114,182,.75); }
+  #timeline button.framed { height: 34px; }
+  #timeline .none { color: var(--muted); font-size: 12px; align-self: center; }
+  #timeline button.bad { outline: 2px solid var(--stuck); outline-offset: -2px; }
+  #timeline button[aria-pressed="true"] { outline: 2px solid #fff; outline-offset: -2px; }
+  #focus .scrub { display: flex; align-items: center; gap: 10px; color: #cbd5e1; font-size: 12px; }
+  #focus .scrub b { color: #fff; }
+  #focus .scrub button { padding: 3px 10px; }
+  #focus img { width: 100%; height: 100%; object-fit: contain; background: #000; border-radius: 6px; display: block; }
+  #focus .none { position: absolute; inset: 0; display: none; align-items: center; justify-content: center; padding: 16px;
+    color: #98a2b3; font-size: 13px; text-align: center; }
+  #focus .stage.empty .none { display: flex; }
+  #focus .stage.empty img { visibility: hidden; }
   #report { display: none; position: fixed; inset: 0; z-index: 6; background: var(--bg); overflow-y: auto; padding: 0 16px 32px; }
   #report.open { display: block; }
   #report .bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; align-items: center; gap: 8px 12px;
@@ -136,6 +165,18 @@ export const LIVE_PAGE = `<!doctype html>
   #report .doc details { margin: 8px 0; }
   #report .doc summary { cursor: pointer; color: var(--muted); }
   #report .doc .unset { color: var(--muted); font-style: italic; }
+  #report .doc details.evidence { margin: 10px 0 16px; padding: 8px 12px; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+  #report .doc details.evidence[open] summary { margin-bottom: 10px; }
+  #report .doc details.evidence figure { margin: 0 0 12px; }
+  #report .doc details.evidence .shots { display: flex; flex-wrap: wrap; gap: 14px; }
+  #report .doc details.evidence figure { flex: 1 1 320px; max-width: 440px; }
+  #report .doc details.evidence img { display: block; width: 100%; max-height: 280px; object-fit: cover; object-position: top;
+    border: 1px solid var(--line); border-radius: 4px; background: var(--shade); }
+  #report .doc details.evidence .gone img { display: none; }
+  #report .doc details.evidence .gone-note { display: none; margin: 0 0 4px; padding: 12px; border: 1px dashed var(--line);
+    border-radius: 4px; color: var(--muted); font-size: 12px; }
+  #report .doc details.evidence .gone .gone-note { display: block; }
+  #report .doc details.evidence figcaption { margin-top: 4px; font: 11px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: var(--muted); }
   @media (prefers-reduced-motion: no-preference) { .badge.running { animation: pulse 1.6s ease-in-out infinite; } }
   @keyframes pulse { 50% { opacity: .55; } }
 </style>
@@ -157,7 +198,7 @@ export const LIVE_PAGE = `<!doctype html>
   <h2>The run has finished</h2>
   <p>Its browsers are closed, so there is nothing left to watch. What it found is in the report.</p>
   <p class="where" id="finished-where" data-testid="live-finished-where"></p>
-  <button type="button" id="finished-report" data-testid="live-finished-report">Read the report</button>
+  <p><a class="btn" href="run" id="finished-run" data-testid="live-finished-run">Open the whole run</a></p>
 </div>
 <main id="grid"></main>
 <div id="report" role="dialog" aria-modal="true" aria-label="The run's report" data-testid="live-report-dialog">
@@ -176,7 +217,13 @@ export const LIVE_PAGE = `<!doctype html>
     <span class="line" id="focus-line"></span>
     <button type="button" id="focus-close" data-testid="live-focus-close">Close</button>
   </div>
-  <img id="focus-img" alt="">
+  <div class="stage" id="focus-stage">
+    <img id="focus-img" alt="">
+    <span class="none">No frame available. The session's page may be closed, or not answering.</span>
+  </div>
+  <div class="scrub"><span id="scrub-where" data-testid="live-scrub-where">Live</span><span class="spacer"></span>
+    <button type="button" id="scrub-live" data-testid="live-scrub-live" hidden>Back to live</button></div>
+  <div id="timeline" data-testid="live-timeline" role="group" aria-label="The steps this session took"></div>
   <div class="lower">
     <div class="feed" id="focus-feed" data-testid="live-focus-feed"></div>
     <aside class="brief" aria-label="What this session is doing" data-testid="live-focus-brief">
@@ -201,6 +248,10 @@ export const LIVE_PAGE = `<!doctype html>
   var eventsKey = '';
   var frames = {};
   var hoverTask = null;
+  // A step the viewer picked from the timeline: the stage shows its frame
+  // instead of the live page, so a run can be watched back while it runs.
+  var scrubbed = null;
+  var timelineLines = [];
   var reportOpen = false;
   var reportTimer = null;
   var reportProblem = null;
@@ -211,6 +262,10 @@ export const LIVE_PAGE = `<!doctype html>
   var reportShown = false;
   var reportFile = null;
   var reportMarkdown = null;
+  // What the panel last rendered, so an unchanged report is left alone.
+  var reportKey = null;
+  // Per-finding frames from api/report: empty unless the run was recorded.
+  var reportEvidence = [];
   var savedACopy = false;
   // A result that reads as a failure is shown in red.
   var BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
@@ -257,7 +312,7 @@ export const LIVE_PAGE = `<!doctype html>
       frames[d.session] = src;
       var card = cards[d.session];
       if (card && card.live) card.img.src = src;
-      if (focused === d.session) document.getElementById('focus-img').src = src;
+      if (focused === d.session && !scrubbed) document.getElementById('focus-img').src = src;
     });
     events.addEventListener('unavailable', function (e) {
       var d;
@@ -356,6 +411,35 @@ export const LIVE_PAGE = `<!doctype html>
     }
     if (last < text.length) node.appendChild(document.createTextNode(text.slice(last)));
   }
+  /**
+   * The frames recorded around one finding, as a closed accordion. Nothing is
+   * shown when the run was not recorded: the report reads the same as before.
+   */
+  function evidenceFor(id) {
+    var found = null;
+    reportEvidence.forEach(function (e) { if (e.id === id) found = e; });
+    if (!found || !found.frames.length) return null;
+    var box = el('details', 'evidence');
+    box.setAttribute('data-testid', 'live-report-evidence-' + id);
+    box.appendChild(el('summary', '', found.frames.length + (found.frames.length === 1 ? ' screenshot' : ' screenshots') + ' from around this finding'));
+    var shots = el('div', 'shots');
+    box.appendChild(shots);
+    found.frames.forEach(function (f) {
+      var fig = el('figure');
+      var img = el('img');
+      img.loading = 'lazy';
+      img.src = 'record/' + f.frame;
+      img.alt = f.action + ' ' + f.detail;
+      // A recording deleted since the run leaves a broken icon under a finding
+      // that still counts it as evidence. Say which it is.
+      img.addEventListener('error', function () { fig.classList.add('gone'); });
+      fig.appendChild(img);
+      fig.appendChild(el('figcaption', '', clock(f.at) + ' · ' + f.action + ' · ' + f.detail));
+      fig.appendChild(el('p', 'gone-note', 'This frame is no longer in ' + f.frame.replace(/\\/[^/]*$/, '') + '.'));
+      shots.appendChild(fig);
+    });
+    return box;
+  }
   function renderMarkdown(root, md) {
     root.textContent = '';
     var lines = md.split('\\n');
@@ -371,14 +455,23 @@ export const LIVE_PAGE = `<!doctype html>
     }
     function list(tag, re) {
       var box = el(tag);
+      var ids = [];
       var m;
       while (i < lines.length && (m = re.exec(lines[i]))) {
         var li = el('li');
         inline(li, m[1]);
         box.appendChild(li);
+        // A finding names its id on its first bullet; the frames recorded
+        // around it hang under that list, so the proof sits with the claim.
+        var id = /^\\*\\*Id:\\*\\* \`([^\`]+)\`/.exec(m[1]);
+        if (id) ids.push(id[1]);
         i += 1;
       }
       container.appendChild(box);
+      ids.forEach(function (id) {
+        var shots = evidenceFor(id);
+        if (shots) container.appendChild(shots);
+      });
     }
     while (i < lines.length) {
       var line = lines[i];
@@ -463,8 +556,26 @@ export const LIVE_PAGE = `<!doctype html>
           return;
         }
         reportMarkdown = d.markdown;
+        reportEvidence = d.evidence || [];
         meta.textContent = (finished ? 'as the run left it at ' : 'as the run stands at ') + clock(d.at) + ' · ' + whereItIs();
+        // The report is re-read every few seconds while the run goes on.
+        // Re-rendering an unchanged document threw away what the reader was
+        // doing with it: an opened accordion shut itself, and the page jumped
+        // back to the top, every five seconds.
+        var key = d.markdown + '\\u0000' + JSON.stringify(reportEvidence);
+        if (key === reportKey) return;
+        var open = {};
+        var was = doc.querySelectorAll('details[open][data-testid]');
+        for (var k = 0; k < was.length; k += 1) open[was[k].getAttribute('data-testid')] = true;
+        var top = doc.parentNode ? doc.parentNode.scrollTop : 0;
+        reportKey = key;
         renderMarkdown(doc, d.markdown);
+        // A finding whose evidence the reader had open stays open through a change.
+        Object.keys(open).forEach(function (id) {
+          var node = doc.querySelector('details[data-testid="' + id + '"]');
+          if (node) node.open = true;
+        });
+        if (doc.parentNode) doc.parentNode.scrollTop = top;
       })
       .catch(function (err) {
         // The last rendering stays; with none, say why there is nothing to read.
@@ -512,6 +623,65 @@ export const LIVE_PAGE = `<!doctype html>
     document.getElementById('report-open').focus();
   }
 
+  // One tick per step, coloured by the task it served: a run can be scrolled
+  // back through while it is still going, and a step with a frame is taller.
+  function renderTimeline(lines) {
+    // Kept so a re-render (picking a step, say) draws the same run back. The
+    // status poll carries six lines and the close-up three hundred: redrawing
+    // from whichever was nearest to hand shrank the timeline to six ticks.
+    timelineLines = lines || timelineLines;
+    lines = timelineLines;
+    var node = document.getElementById('timeline');
+    var atEnd = node.scrollLeft + node.clientWidth >= node.scrollWidth - 8;
+    node.textContent = '';
+    var groups = 0;
+    var last = null;
+    (lines || []).forEach(function (line) {
+      var task = line.task || '';
+      if (task && task !== last) groups += 1;
+      last = task;
+      var tick = el('button');
+      tick.type = 'button';
+      tick.className = (task ? 'g' + ((groups - 1) % 4) : '') + (line.frame ? ' framed' : '') + (BAD_RESULT.test(line.result || '') ? ' bad' : '');
+      tick.title = clock(line.at) + '  ' + line.action + (line.target ? ' ' + line.target : '') + (task ? '\\n' + task : '');
+      tick.setAttribute('aria-label', tick.title);
+      tick.setAttribute('aria-pressed', scrubbed && scrubbed.at === line.at && scrubbed.action === line.action ? 'true' : 'false');
+      tick.addEventListener('click', function () { showStep(line); });
+      node.appendChild(tick);
+    });
+    if (atEnd) node.scrollLeft = node.scrollWidth;
+  }
+
+  // Show one step: its frame if the run was recorded, and what it was doing.
+  function showStep(line) {
+    var where = document.getElementById('scrub-where');
+    var back = document.getElementById('scrub-live');
+    scrubbed = line;
+    back.hidden = false;
+    if (!line.frame) {
+      where.textContent = clock(line.at) + ' ' + line.action + ' — this run kept no frame for that step';
+      // Leaving the live frame up under that caption is the most misleading
+      // state this page can reach: it reads as the page at that moment.
+      document.getElementById('focus-img').removeAttribute('src');
+      document.getElementById('focus-stage').classList.add('empty');
+      renderTimeline(null);
+      return;
+    }
+    document.getElementById('focus-stage').classList.remove('empty');
+    document.getElementById('focus-img').src = 'record/' + line.frame;
+    where.textContent = clock(line.at) + ' ' + line.action + (line.task ? ' · ' + line.task : '');
+    renderTimeline(null);
+  }
+
+  function backToLive() {
+    scrubbed = null;
+    document.getElementById('scrub-where').textContent = 'Live';
+    document.getElementById('scrub-live').hidden = true;
+    if (focused) document.getElementById('focus-img').src = frames[focused] || shotUrl(focused);
+    // Otherwise the step just left keeps its outline until the next full feed.
+    renderTimeline(null);
+  }
+
   // Built with textContent only: an action's target is text from the app under test.
   function renderFeed(node, lines, onGroup) {
     // Measured before the node is emptied: an empty node always reads as scrolled to its end.
@@ -570,9 +740,17 @@ export const LIVE_PAGE = `<!doctype html>
 
   function openFocus(name) {
     focused = name;
+    scrubbed = null;
+    // The ticks belong to the session just left; showing them under this one's
+    // name, and playing its frames when one is clicked, is worse than none.
+    timelineLines = [];
+    renderTimeline([]);
+    document.getElementById('focus-stage').classList.remove('empty');
     document.getElementById('focus-name').textContent = name;
     document.getElementById('focus-img').alt = 'Live view of ' + name;
     document.getElementById('focus-img').src = frames[name] || shotUrl(name);
+    document.getElementById('scrub-where').textContent = 'Live';
+    document.getElementById('scrub-live').hidden = true;
     document.getElementById('focus').classList.add('open');
     hoverTask = null;
     renderFeed(document.getElementById('focus-feed'), (latest[name] || {}).feed, showTask);
@@ -592,8 +770,21 @@ export const LIVE_PAGE = `<!doctype html>
   function loadFullFeed(name) {
     fetch('api/activity?session=' + encodeURIComponent(name), { cache: 'no-store' })
       .then(function (r) { return r.ok ? r.json() : null; })
-      .then(function (d) { if (d && focused === d.session) renderFeed(document.getElementById('focus-feed'), d.feed, showTask); })
-      .catch(function () { /* the short feed from the last poll stays on screen */ });
+      .then(function (d) {
+        if (!d || focused !== d.session) return;
+        renderFeed(document.getElementById('focus-feed'), d.feed, showTask);
+        renderTimeline(d.feed);
+      })
+      .catch(function () {
+        // The short feed from the last poll stays on screen, but the timeline
+        // is drawn from this call alone: an empty strip would read as a
+        // session that did nothing.
+        if (!timelineLines.length) {
+          var strip = document.getElementById('timeline');
+          strip.textContent = '';
+          strip.appendChild(el('span', 'none', 'The step list could not be loaded. Trying again.'));
+        }
+      });
   }
 
   function setBrief(id, text, unset) {
@@ -665,7 +856,10 @@ export const LIVE_PAGE = `<!doctype html>
     });
     syncEvents();
     reportFile = snap.report || reportFile;
-    if (snap.sessions.length > 0) sawRun = true;
+    // A viewer who opens the board after the last browser closed never sees a
+    // session, but the engine only names a report file once one has attached:
+    // that is a finished run, not a board waiting for its first attach.
+    if (snap.sessions.length > 0 || snap.report) sawRun = true;
     finished = sawRun && snap.sessions.length === 0;
     document.getElementById('empty').style.display = snap.sessions.length || finished ? 'none' : 'block';
     document.getElementById('finished').classList.toggle('open', finished);
@@ -673,10 +867,18 @@ export const LIVE_PAGE = `<!doctype html>
       var where = document.getElementById('finished-where');
       where.textContent = whereItIs();
       where.className = 'where' + (reportFile && reportFile.written ? '' : ' unset');
-      // The moment somebody wants the report is the moment the run ends: show it.
+      // The moment somebody wants the run is the moment it ends, and a panel
+      // over a dead board is lost on the next refresh. The run has its own
+      // address; go there, so the address IS the report from then on.
       if (!reportShown) {
         reportShown = true;
-        if (!reportOpen) openReport();
+        // The run has its own address, and going there means a refresh shows
+        // the report instead of a dead board. Ask whether it is there first:
+        // a run with no page to serve would otherwise land on a 404, and the
+        // panel below is the only other copy.
+        fetch('run', { cache: 'no-store' })
+          .then(function (r) { if (r.ok) location.href = 'run'; else openReport(); })
+          .catch(function () { openReport(); });
       }
     }
     document.getElementById('engine').textContent = 'engine pid ' + snap.pid + ' · v' + snap.version;
@@ -698,12 +900,23 @@ export const LIVE_PAGE = `<!doctype html>
     this.textContent = streamAll ? 'Streaming all' : 'Stream all';
     Object.keys(cards).forEach(function (name) { setLive(cards[name], streamAll); });
   });
+  // A session with nothing to show answers 503; say so rather than leaving a broken-image icon.
+  document.getElementById('focus-img').addEventListener('error', function () {
+    document.getElementById('focus-stage').classList.add('empty');
+    // A live session with nothing to show and a recorded frame that has since
+    // been deleted look identical here; only the second is worth explaining.
+    if (scrubbed) {
+      document.getElementById('scrub-where').textContent =
+        clock(scrubbed.at) + ' ' + scrubbed.action + ' — its frame could not be loaded; the recording may have been removed';
+    }
+  });
+  document.getElementById('focus-img').addEventListener('load', function () { document.getElementById('focus-stage').classList.remove('empty'); });
   document.getElementById('focus-close').addEventListener('click', closeFocus);
   // A re-rendered feed replaces the group under the pointer without a mouseleave; leaving the feed itself still resets.
   document.getElementById('focus-feed').addEventListener('mouseleave', function () { showTask(null); });
   document.getElementById('focus').addEventListener('click', function (e) { if (e.target === this) closeFocus(); });
+  document.getElementById('scrub-live').addEventListener('click', backToLive);
   document.getElementById('report-open').addEventListener('click', openReport);
-  document.getElementById('finished-report').addEventListener('click', openReport);
   document.getElementById('report-save').addEventListener('click', saveACopy);
   // Closing the tab on a finished run whose report was never written to disk
   // throws the only copy away. The browser shows its own confirm/dismiss, and