scenescout 3.23.1 → 3.23.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # scenescout
 
+## 3.23.3
+
+### Patch Changes
+
+- 43012d7: The live board's report panel keeps showing a finding's pictures when sessions in two project folders are attached at once and the session that filed the finding has closed. The report now names the project it describes, and the board loads its pictures from that folder rather than from whichever project is attached first.
+- 1cda780: The live view's run page keeps showing its pictures after a session attaches to another project folder. Its picture addresses now name the project the page was written for, so a page already open in a browser loads them from that folder rather than from whichever project attached last.
+
+## 3.23.2
+
+### Patch Changes
+
+- 63329f7: On a recorded check's `replay.html`, each step's frame now fills its box, so the note shown when a frame is missing no longer shows beside a frame that loaded. In a test report laid out from a template, table cells wrap at word boundaries, so short columns such as Result no longer break a word across lines; hashes, paths and frame links still wrap anywhere.
+
 ## 3.23.1
 
 ### Patch Changes

package/README.md

@@ -11,11 +11,11 @@ Works with Claude Code · Cursor · VS Code (Copilot) · Codex CLI · Gemini CLI
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![node >= 20](https://img.shields.io/badge/node-%E2%89%A5%2020-339933?logo=node.js&logoColor=white)
 
-[📖 Guide](docs/guide/Home.md) · [🐛 What it catches](#-what-it-catches) · [🚀 Get started](#-get-started) · [🚦 CI](#-in-ci) · [🔒 Safety](#-safe-by-default) · [📚 Docs](#-documentation)
+[📖 Guide](docs/guide/Home.md) · [🐛 What it catches](#-what-it-catches) · [🎬 QA with evidence](#-automated-qa-with-evidence) · [🚀 Get started](#-get-started) · [🚦 CI](#-in-ci) · [🔒 Safety](#-safe-by-default) · [📚 Docs](#-documentation)
 
 </div>
 
-Scripted end-to-end tests answer one question: *does this exact flow still work?* They say nothing about the rest of the app. SceneScout lets the agent you already use explore a running web app like a curious, thorough tester. It clicks, fills forms, switches roles and calls the API behind a hidden button, then writes a report of what is **broken** and what could be **better**, with evidence for every line.
+Scripted end-to-end tests answer one question: *does this exact flow still work?* They say nothing about the rest of the app. SceneScout lets the agent you already use explore a running web app like a curious, thorough tester. It clicks, fills forms, switches roles and calls the API behind a hidden button, then writes a report of what is **broken** and what could be **better**, with a picture and evidence for every line.
 
 Try it on any app you are allowed to test. No account, no API key, no setup:
 
@@ -23,9 +23,26 @@ Try it on any app you are allowed to test. No account, no API key, no setup:
 npx -y scenescout http://localhost:3000
 ```
 
+```mermaid
+flowchart LR
+  A["🧠 Your coding agent<br/>Claude Code, Cursor, Copilot…"] -- MCP --> S["🔭 SceneScout<br/>browser · checks · memory"]
+  S --> App["🌐 Your running app"]
+  S --> R["📋 Report<br/>plain words + pictures"]
+  S --> E["🎬 Evidence<br/>replay, videos, test report"]
+```
+
+## 👥 Who it's for
+
+| 🛠️ **Developers** | 🧑‍💼 **QA, product and non-technical teams** |
+|---|---|
+| Findings with the request that failed (`GET /api/orders?status=archived → 500`), the steps, and a Playwright regression-test skeleton | Each problem in plain words first: what was done, what was expected, what happened, and a picture of the page |
+| Next to the source, the file behind the bug and a likely fix | Visible problems shown, not described: a covered button, a broken image, text too faint to read |
+| A deterministic gate for pull requests, with SARIF for code scanning | Journeys recorded step by step, as frames and video, so a pass is something you can watch |
+| Runs from your editor's agent, or unattended in CI | A test report laid out by **your** template, with expected and actual results, deviations and blank sign-off rows |
+
 ## 🐛 What it catches
 
-A real run against the small demo app in this repository, which has bugs planted on purpose:
+A real run against the small demo app in this repository, which has bugs planted on purpose. The two you can see are outlined:
 
 <p align="center"><img src="examples/screenshots/dashboard-annotated.png" alt="The demo app's dashboard with two defects outlined in red: 1, a yellow badge covering the All orders button; 2, the weekly chart image failing to load" width="760" /></p>
 
@@ -45,20 +62,77 @@ It filed twelve findings. A few from [the report](examples/report.md):
 
 What it looks for, on every page, after every action:
 
+- 📐 **Broken layout, from geometry:** controls that overlap, sit off-screen, hide under a sticky bar or can never be scrolled into view. The CSS bugs a person spots at a glance, found without one.
 - 🧨 **Real breakage:** console errors, crashes, failed requests, 4xx and 5xx responses, broken images, dead-end pages.
 - 🔓 **Permission leaks:** it calls the app's own API as each role, so "the button is hidden" becomes "the server refuses it", or doesn't.
 - 🤥 **Pages that lie:** "Saved!" after the server refused the save, or an empty table after the request failed.
 - 👆 **Impatient users:** a double-click that sends the same order twice.
-- 📐 **Broken layout, from geometry:** controls that overlap, sit off-screen, hide under a sticky bar or can never be scrolled into view.
 - ♿ **Accessibility and craft:** contrast, focus, labels, target sizes, spacing and type, with a 0 to 100 score per page.
 - 🧭 **Friction:** how many steps a task takes, and where a user had to go back.
 - 💉 **Security smells:** typed markup that comes back as an element, and tokens posted to any window.
 
-Every finding comes with the evidence, the steps to reproduce it, a picture, and a Playwright regression-test skeleton. Next to the source code, it also names the file behind the bug and a likely fix. [Everything it checks](docs/guide/What-it-checks.md).
+[Everything it checks](docs/guide/What-it-checks.md).
+
+## 🎬 Automated QA with evidence
+
+Save the journeys that matter, the happy paths and the ones that must fail politely, and `scenescout check` replays them on every pull request with no model involved. Recorded, each run leaves proof you can watch and hand to someone who never opens a terminal.
+
+```mermaid
+flowchart LR
+  PR["🔀 Pull request"] --> C["🚦 scenescout check<br/>--record --video --template"]
+  F["📝 Saved journeys<br/>.scenescout/flows/*.json"] --> C
+  C --> G["✅ / ❌ A gate on the pull request"]
+  C --> RP["🖼️ replay.html<br/>every step, with frames"]
+  C --> V["🎞️ A video per journey"]
+  C --> TR["📄 Test report<br/>your template, SHA-256 manifest,<br/>blank sign-off rows"]
+```
+
+A journey is a few lines of JSON, written by hand or kept from a flow your agent just walked. This is [the demo's happy path](examples/flows/01-place-an-order.json):
+
+```json
+{
+  "name": "place an order",
+  "id": "TC-01",
+  "requirements": ["REQ-ORD-1", "REQ-ORD-2"],
+  "steps": [
+    { "action": "navigate", "target": "/orders-new.html", "expected": "The new-order form is shown" },
+    { "action": "type", "target": "testid=new-order-customer", "value": "Harbour Bakery", "expected": "The customer is filled in" },
+    { "action": "type", "target": "testid=new-order-items", "value": "4", "replace": true, "expected": "The item count is 4" },
+    { "action": "click", "target": "testid=new-order-submit", "expected": "The order is created" },
+    { "action": "expect-request", "request": "POST /api/orders", "status": "2xx" },
+    { "action": "expect-element", "target": "testid=new-order-created-link", "state": "visible", "expected": "A link to the new order is shown" }
+  ]
+}
+```
+
+Against the [demo app](demo-app/), with the three journeys in [examples/flows](examples/flows/) (one creates an order, so the check is allowed to send it):
+
+```bash
+npx scenescout check http://127.0.0.1:4173 --flows examples/flows --mode read-only --flow-writes allow \
+  --record --video --template examples/report-template.json
+```
+
+**The journey, as it ran** (one of the videos it filmed):
+
+<p align="center"><img src="examples/screenshots/journey-place-order.gif" alt="A recorded journey on the demo app: the new-order form is filled with a customer and four items, Create order is clicked, and the confirmation with a link to the new order appears" width="760" /></p>
+
+**The replay page:** each journey with a pass or fail badge. A journey that broke opens at the step that broke, with the page as it was after every step:
+
+<p align="center"><img src="examples/screenshots/check-replay.png" alt="The check's replay page: verdict FAILED, the app's address, start and end times, 24 frames and 3 videos; two journeys passed and one, see archived orders, failed at step 3" width="820" /></p>
+
+<p align="center"><img src="examples/screenshots/check-replay-failed.png" alt="The failed journey opened: step 1 navigates to the orders page and passes, step 2 selects Archived and passes with an empty table, step 3 expected GET /api/orders to answer 200 and it answered 500, highlighted in red" width="760" /></p>
+
+**The test report**, laid out by [a template](examples/report-template.json) you write once: test IDs, the requirements each covers, expected and actual results, a screenshot per step, every deviation listed again for the reviewer, and the SHA-256 of each piece of evidence. SceneScout signs nothing; the sign-off rows are for your people.
+
+<p align="center"><img src="examples/screenshots/test-report-results.png" alt="The test report's results table: test TC-01, place an order, covering REQ-ORD-1 and REQ-ORD-2; each step with its expected result, actual result As expected, result Pass, and a screenshot of the page after the step" width="820" /></p>
+
+<p align="center"><img src="examples/screenshots/test-report-deviations.png" alt="The test report's deviations: TC-03, see archived orders, step 3 expected GET /api/orders to answer 200, actual GET /api/orders answered 500, result Fail" width="820" /></p>
+
+Everything is one self-contained HTML page per report, with no scripts, nothing loaded from the network, and a layout that prints. [Recording a check](docs/ci.md#recording-a-check) and [a test report from a template](docs/ci.md#a-test-report-from-a-template) have the details, including what to keep out of the pictures.
 
 ## 📺 Watch it work
 
-Each run opens a live view on your machine, with one card per agent: what it is doing, the page it is on, and a feed of every action. Three agents are testing the demo app in parallel here:
+Each exploratory run opens a live view on your machine, with one card per agent: what it is doing, the page it is on, and a feed of every action. Three agents are testing the demo app in parallel here:
 
 <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>
 
@@ -71,6 +145,17 @@ You can read the report while the agents are still working, and scrub back throu
 - 🛡️ **Safety is enforced on the network, not requested in a prompt.** Nothing existing is changed unless you allow it, and a blocked write never reaches your server.
 - ✅ **"Done" is a contract.** The report lists everything not tested, and at the `extensive` level refuses to finish while any known page is unvisited.
 - 🧠 **It remembers.** Each run starts from what the last one learned, and re-tests the bugs earlier runs left open.
+- 📊 **It is measured, not asserted.** Every change to how it explores is scored against an app with planted bugs and a held-out app it is never tuned on ([the log](docs/benchmark.md)):
+
+```mermaid
+xychart-beta
+  title "Planted defects found per run, demo app (13 planted)"
+  x-axis "Run" ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12"]
+  y-axis "Found" 0 --> 13
+  bar [11, 12, 9, 10, 11, 11, 10, 10, 11, 13, 11, 11, 12]
+```
+
+<sub>Each bar is one run of eight parallel agents, re-scored against today's answer key. One run is noisy: read the trend across runs, not a single bar.</sub>
 
 ## 🚀 Get started
 
@@ -115,17 +200,20 @@ npx -y scenescout login http://localhost:3000 --role admin    # then: /scenescou
 
 | | What it does | Needs a model? |
 |---|---|---|
-| [`scenescout check`](docs/guide/Ways-to-use-it.md#scenescout-check-a-gate-in-ci) | A deterministic gate: measures every page, replays your saved flows and visual baselines, fails only on what it can prove | No |
+| [`scenescout check`](docs/guide/Ways-to-use-it.md#scenescout-check-a-gate-in-ci) | A deterministic gate: measures every page, replays your saved journeys and visual baselines, fails only on what it can prove; recorded, it leaves the [evidence above](#-automated-qa-with-evidence) | No |
 | [`scenescout ci`](docs/guide/Ways-to-use-it.md#scenescout-ci-an-unattended-exploratory-run) | An unattended exploratory run, driven by the Anthropic or OpenAI API. It reports and never fails the build | An API key |
 | [`/scenescout qa`](docs/guide/Ways-to-use-it.md#scenescout-qa-on-a-pull-request) | A comment on a pull request that tests its preview deploy and replies with the results; `/scenescout qa check` runs your own check instead | An API key (`qa check`: none) |
 | [`scenescout export`](docs/guide/Ways-to-use-it.md#filing-findings-as-issues) | Files the findings as GitHub or Jira issues, each once | No |
 
-A gate on every pull request, as a GitHub Action:
+A gate on every pull request that keeps its evidence, as a GitHub Action:
 
 ```yaml
 - uses: brunoboto96/SceneScout@v3
   with:
     url: http://127.0.0.1:3000
+    record: on
+    video: on
+    template: tests/report-template.json
 ```
 
 [docs/ci.md](docs/ci.md) has complete workflows, every option, and the same check on GitLab CI, CircleCI or any shell.
@@ -139,7 +227,7 @@ A gate on every pull request, as a GitHub Action:
 | 🟡 `safe-write` | Creates records, and edits or deletes only the ones it created |
 | 🔴 `destructive` | Everything. Only when you say the data is disposable; the agent never picks it |
 
-The policy sits on the network, so a blocked request never reaches your server. The page gets a refusal instead, which is how SceneScout catches a page that claims success anyway. Findings, memory and reports stay in a `.scenescout/` folder that keeps itself out of git.
+The policy sits on the network, so a blocked request never reaches your server. The page gets a refusal instead, which is how SceneScout catches a page that claims success anyway. A saved journey that creates something, like the order above, runs only when the check is told `--flow-writes allow`, against a test environment. Findings, memory and reports stay in a `.scenescout/` folder that keeps itself out of git.
 
 > [!IMPORTANT]
 > Only test sites you own or are allowed to test. [Safety model](docs/guide/Safety-model.md).
@@ -155,6 +243,7 @@ The policy sits on the network, so a blocked request never reaches your server.
 | [Recipes](docs/guide/Recipes.md) | Setups for seven kinds of project |
 | [Configuration reference](docs/guide/Configuration-reference.md) | Every option, environment variable and action input |
 | [Troubleshooting](docs/guide/Troubleshooting.md) | Symptoms and fixes, upgrading and uninstalling |
+| [Running it in CI](docs/ci.md) | Saved journeys, recording, test reports from templates, every workflow |
 | [How it works](docs/how-it-works.md) | Diagrams of a run, an action, the write policy, lanes |
 | [Benchmark](docs/benchmark.md) · [Validation](docs/validation.md) | How runs are scored against answer keys, and runs on public apps |
 | [Design decisions](docs/adr/README.md) | Why the rules are what they are |

package/dist/engine/check-replay.js

@@ -285,7 +285,7 @@ ol.steps { list-style:none; margin:10px 0 0; padding:0; }
 .why { margin:4px 0; font-size:13px; overflow-wrap:anywhere; }
 a.frame { display:grid; margin:6px 0 2px; max-width:min(100%,720px); color:var(--muted); font-size:12px; }
 a.frame > * { grid-area:1 / 1; }
-a.frame img { position:relative; max-width:100%; max-height:400px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
+a.frame img { position:relative; width:100%; max-height:400px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; background:var(--panel); }
 .gone-note { align-self:end; padding:2.6em 12px 12px; border:1px dashed var(--line); border-radius:6px; }
 .noframe, .none { color:var(--muted); font-size:12px; font-style:italic; margin:4px 0; }
 .note { color:var(--muted); font-size:13px; }

package/dist/engine/check-report.js

@@ -431,7 +431,7 @@ header.title h1 { font-size:22px; margin:0 0 4px; }
 header.title .subtitle { margin:0 0 8px; color:var(--muted); }
 h2 { font-size:17px; margin:28px 0 8px; border-bottom:1px solid var(--line); padding-bottom:4px; }
 table { border-collapse:collapse; width:100%; margin:8px 0; }
-th, td { border:1px solid var(--line); padding:5px 8px; text-align:left; vertical-align:top; overflow-wrap:anywhere; }
+th, td { border:1px solid var(--line); padding:5px 8px; text-align:left; vertical-align:top; overflow-wrap:break-word; }
 thead th, table.facts th { background:var(--head); }
 table.facts { width:auto; min-width:50%; }
 tr.test-head th { background:var(--head); font-weight:400; }
@@ -444,7 +444,8 @@ td.r-passed { color:var(--pass); font-weight:700; } td.r-failed, td.r-refused {
 tr.failed td, tr.refused td { background:var(--fail-bg); }
 a.frame { display:block; color:var(--muted); font-size:11px; }
 a.frame img { display:block; max-width:220px; max-height:150px; object-fit:cover; object-position:top; border:1px solid var(--line); }
-td.hash, td.path { font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+td.hash, td.path { font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+a.frame { overflow-wrap:anywhere; }
 table.sign td.blank { height:2.6em; min-width:8em; }
 .none { color:var(--muted); font-style:italic; }
 @media print { main { max-width:none; padding:0; } a { color:inherit; text-decoration:none; } tbody, tr { break-inside:avoid; } }

package/dist/engine/live-page.js

@@ -297,6 +297,8 @@ export const LIVE_PAGE = `<!doctype html>
   var reportKey = null;
   // Per-finding frames from api/report: empty unless the run was recorded.
   var reportEvidence = [];
+  // Where the report's pictures are served from: the project it was rendered from (api/report names it).
+  var reportFramePrefix = 'record/';
   var savedACopy = false;
   // A result that reads as a failure is shown in red.
   var BAD_RESULT = /error|fail|refus|block|violation|abandoned/i;
@@ -509,13 +511,13 @@ export const LIVE_PAGE = `<!doctype html>
       picture = el('figure', 'picture');
       picture.setAttribute('data-testid', 'live-report-picture-' + id);
       var link = el('a');
-      link.href = 'record/' + found.picture.file;
+      link.href = reportFramePrefix + found.picture.file;
       link.target = '_blank';
       link.rel = 'noreferrer';
       link.setAttribute('data-testid', 'live-report-picture-open');
       var pic = el('img');
       pic.loading = 'lazy';
-      pic.src = 'record/' + found.picture.file;
+      pic.src = reportFramePrefix + found.picture.file;
       pic.alt = 'What the finding is about, when it was filed';
       pic.addEventListener('error', function () { picture.classList.add('gone'); });
       link.appendChild(pic);
@@ -533,7 +535,7 @@ export const LIVE_PAGE = `<!doctype html>
       var fig = el('figure');
       var img = el('img');
       img.loading = 'lazy';
-      img.src = 'record/' + f.frame;
+      img.src = reportFramePrefix + 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.
@@ -607,7 +609,7 @@ export const LIVE_PAGE = `<!doctype html>
         var fig = el('figure', 'picture');
         var pic = el('img');
         pic.loading = 'lazy';
-        pic.src = 'record/' + m[2];
+        pic.src = reportFramePrefix + m[2];
         pic.alt = m[1];
         fig.appendChild(pic);
         container.appendChild(fig);
@@ -680,12 +682,13 @@ export const LIVE_PAGE = `<!doctype html>
         }
         reportMarkdown = d.markdown;
         reportEvidence = d.evidence || [];
+        reportFramePrefix = d.framePrefix || 'record/';
         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);
+        var key = d.markdown + '\\u0000' + JSON.stringify(reportEvidence) + '\\u0000' + reportFramePrefix;
         if (key === reportKey) return;
         var open = {};
         var was = doc.querySelectorAll('details[open][data-testid]');

package/dist/engine/replay.js

@@ -18,6 +18,7 @@
  * Everything here is pure string work — no browser, no filesystem — so the
  * escaping and the grouping are table-tested.
  */
+import crypto from "node:crypto";
 import path from "node:path";
 import { isSafeRelativePath } from "./plain.js";
 /** Most frames one recorded session keeps. A long run is thousands of actions, and a project folder is not a video store. */
@@ -59,6 +60,39 @@ export function resolveFrame(root, relPath) {
     const file = path.resolve(base, inside);
     return file.startsWith(base + path.sep) ? file : null;
 }
+/**
+ * A short name for a project folder, used in the live view's frame addresses so
+ * a page says which project its pictures belong to. One engine can serve runs
+ * in several folders in turn, and a page already open in a browser loads its
+ * images later, after another folder may have attached. The name is derived
+ * from the folder's resolved path and reveals nothing of it.
+ */
+export function projectKey(dir) {
+    return "p-" + crypto.createHash("sha256").update(path.resolve(dir)).digest("hex").slice(0, 12);
+}
+/** A frame address split into the project it names, when it names one, and the path inside that project's recordings. */
+export function splitProjectFrame(relPath) {
+    const m = /^(p-[0-9a-f]{12})\/(.+)$/.exec(relPath);
+    return m ? { key: m[1], rest: m[2] } : { rest: relPath };
+}
+/**
+ * The project folders this process has rendered a run page or a board report
+ * for, by key. Only a folder one was rendered from can be named, so a viewer
+ * cannot reach any other folder by guessing a key.
+ */
+export class ProjectDirs {
+    byKey = new Map();
+    /** Remember `dir` and return its key. */
+    remember(dir) {
+        const key = projectKey(dir);
+        this.byKey.set(key, dir);
+        return key;
+    }
+    /** The folder a key names, or undefined when nothing was rendered from one with that key. */
+    dir(key) {
+        return this.byKey.get(key);
+    }
+}
 /** 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]);

package/dist/engine/report.js

@@ -4,7 +4,7 @@ import { baseRoute, reachedRoutes, routeIdentity, isEmbedKey, isWorthALook, judg
 import { sayVerification } from "./verify.js";
 import { describePicture, readFindingPicture } from "./capture.js";
 import { feedForSession } from "./live.js";
-import { buildReplayHtml, evidenceFor } from "./replay.js";
+import { buildReplayHtml, evidenceFor, projectKey } from "./replay.js";
 import { calibrate, formatCalibration } from "./calibration.js";
 import { formatPace, measurePace } from "./pace.js";
 import { formatNeverSubmittedEmpty } from "./forms.js";
@@ -221,7 +221,8 @@ export function replayDocument(memory, markdown, version = "") {
         project: projectName(memory.dir),
         at: new Date().toISOString(),
         version,
-        framePrefix: "record/",
+        // Keyed by project, so the page's pictures still load after a session attaches to another folder (replay.ts).
+        framePrefix: `record/${projectKey(memory.dir)}/`,
         savedAt: memory.dir,
     });
 }

package/dist/mcp-server.js

@@ -70,7 +70,7 @@ import { CRITERION_VERDICTS, findCriterion, formatCriteriaForLanes, formatReadin
 import { ACTION_TIMEOUT_ENV, DEFAULT_ACTION_TIMEOUT_MS, DEFAULT_CRAWL_NAV_TIMEOUT_MS, DEFAULT_NAV_TIMEOUT_MS, LIMIT_BOUNDS, NAV_TIMEOUT_ENV, watchdogFor, } from "./engine/limits.js";
 import { MAX_READ_POSTS, READ_POSTS_ENV } from "./engine/policy.js";
 import { chooseProjectFolder, PROJECTS_DIR_ENV, workspaceFromRoots } from "./engine/project-folder.js";
-import { RECORD_MAX_FRAMES, resolveFrame } from "./engine/replay.js";
+import { ProjectDirs, RECORD_MAX_FRAMES, resolveFrame, splitProjectFrame } from "./engine/replay.js";
 import { describePace, normalizePace } from "./engine/settle.js";
 import { needsTask, taskRefusal, TASK_MAX } from "./engine/task.js";
 import { formElicitationSupported, INTAKE_FORM_MESSAGE, INTAKE_TOOL, intakeFormSchema, intakeFromForm, intakeReplyText } from "./intake.js";
@@ -149,6 +149,8 @@ let liveError = null;
  * found — which is the moment somebody most wants to read it.
  */
 let lastRun = null;
+/** Every project folder a run page or the board's report has been rendered from, so their pictures resolve against it later (#457, #463). */
+const pageProjects = new ProjectDirs();
 /** Render the report for a session that is about to close, so the live view keeps it. */
 function keepReport(eng) {
     if (!eng.memory)
@@ -167,6 +169,7 @@ function keepReport(eng) {
     }
     try {
         lastRun.evidence = reportEvidence(eng.memory);
+        pageProjects.remember(eng.memory.dir);
         lastRun.replay = replayDocument(eng.memory, lastRun.markdown, PKG_VERSION);
     }
     catch (err) {
@@ -185,6 +188,10 @@ function reportFile(dir) {
         return { path: file, written: false };
     }
 }
+/** The address a report's frames start with: keyed by project, and the folder is remembered so the key resolves (#463). */
+function framePrefixFor(dir) {
+    return `record/${pageProjects.remember(dir)}/`;
+}
 const liveProvider = {
     snapshot: () => ({
         pid: process.pid,
@@ -204,9 +211,14 @@ const liveProvider = {
     report: () => {
         const eng = (lastWriter && engines.get(lastWriter.session)) ?? engines.values().next().value;
         if (!eng?.memory)
-            return lastRun ? { markdown: lastRun.markdown, at: lastRun.at, evidence: lastRun.evidence } : null;
+            return lastRun ? { markdown: lastRun.markdown, at: lastRun.at, evidence: lastRun.evidence, framePrefix: framePrefixFor(lastRun.dir) } : null;
         const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
-        return { markdown: redactSecrets(markdown), at: new Date().toISOString(), evidence: reportEvidence(eng.memory) };
+        return {
+            markdown: redactSecrets(markdown),
+            at: new Date().toISOString(),
+            evidence: reportEvidence(eng.memory),
+            framePrefix: framePrefixFor(eng.memory.dir),
+        };
     },
     /**
      * The whole run as one page, served at its own address. The live view sends
@@ -219,6 +231,7 @@ const liveProvider = {
             return lastRun?.replay || null;
         try {
             const { markdown } = generateReport(eng.memory, eng.oracleLog.all, reportExtras(eng), { write: false });
+            pageProjects.remember(eng.memory.dir);
             return replayDocument(eng.memory, redactSecrets(markdown), PKG_VERSION);
         }
         catch (err) {
@@ -233,12 +246,19 @@ const liveProvider = {
      * comes from a viewer, so it is resolved and then required to still be
      * inside that directory: nothing else in the project is reachable this way.
      */
-    frame: async (relPath) => {
-        // Sessions may hold different project directories, so the frame belongs to
-        // the session its own path names — not to whichever engine happens to be
-        // first. Falling back keeps a finished run's frames reachable.
-        const named = relPath.replace(/^recordings[\\/]/, "").split("/")[0];
-        const dir = engines.get(named)?.memory?.dir ?? engines.values().next().value?.memory?.dir ?? lastRun?.dir;
+    frame: async (address) => {
+        // A run page names the project it was rendered from, so its pictures load
+        // after a session attaches to another folder. The live board's own frames
+        // carry no project: they belong to the session their path names, and
+        // falling back keeps a finished run's frames reachable.
+        const { key, rest: relPath } = splitProjectFrame(address);
+        let dir;
+        if (key)
+            dir = pageProjects.dir(key);
+        else {
+            const named = relPath.replace(/^recordings[\\/]/, "").split("/")[0];
+            dir = engines.get(named)?.memory?.dir ?? engines.values().next().value?.memory?.dir ?? lastRun?.dir;
+        }
         if (!dir)
             return null;
         const file = resolveFrame(path.join(dir, "recordings"), relPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.23.1",
+  "version": "3.23.3",
   "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",