scenescout 3.19.2 → 3.20.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # scenescout
 
+## 3.20.0
+
+### Minor Changes
+
+- eb79ce8: `scenescout check --record` (or `SCENESCOUT_RECORD=on`) keeps a frame after each route visit and each saved-flow step and writes `replay.html` beside the report: each role, each journey with a pass or fail badge, each step with its caption, result and frame, the first failing step highlighted, and the run's version, times, origin and commit in the header. `--video` records a WebM of each saved flow, each on a page of its own, and the replay page plays it beside the journey's steps. The GitHub Action gains `record` and `video` inputs and a `replay` output, and keeps the page, its frames and its videos in the uploaded artifact.
+
 ## 3.19.2
 
 ### Patch Changes

package/README.md

@@ -277,7 +277,9 @@ Use SceneScout to test http://localhost:3000, record the run
 ```
 
 or, on the tool directly, `scout_attach {record: true}`. `SCENESCOUT_RECORD=on` in
-the server's environment records every run.
+the server's environment records every run. A CI gate records too:
+`scenescout check --record` writes `replay.html`, every journey step by step with
+its frames ([recording a check](docs/ci.md#recording-a-check)).
 
 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
@@ -454,6 +456,7 @@ With the default settings its saved flows send no HTTP write (they replay under
 - `--on-refused-step report|stop` (default `report`): `report` marks a flow whose step was refused "could not run", keeps every other verdict and exits 2; `stop` exits 2 at that step with no results.
 - `--gate-retests never|high|all` (default `high`): which still-reproducing re-tested findings fail the gate.
 - `--baseline off|compare|update` (default `off`), with `--baselines <dir>` and `--baseline-threshold <percent>` (default `0.1`, so small anti-aliasing noise between machines passes): visual baselines, below.
+- `--record` (or `SCENESCOUT_RECORD=on`; the action's `record: on`) keeps a frame after each route visit and each saved-flow step and writes `replay.html` beside the report: each role, each journey with a pass or fail badge, each step with its caption, result and frame, the first failing step highlighted. `--video` (the action's `video: on`) adds a WebM of each journey, played on that page beside its steps. Both off by default. [docs/ci.md](docs/ci.md#recording-a-check) covers size, privacy and publishing it.
 
 The defaults are what an unconfigured check does, for a first try or an AI agent running it unattended: its flows send no HTTP write and it never silently hides a result. Each setting is a choice for the project; the report and `check.json` print the values a check ran with.
 

package/dist/check-run.js

@@ -19,6 +19,7 @@ import { decodePng, encodePng } from "./engine/png.js";
 import { firstLineOf } from "./engine/limits.js";
 import { isNonPageResource } from "./engine/crawl.js";
 import { checkRetestPlan, retestResults, wellFormedFindings } from "./engine/verify.js";
+import { capFrames, isReplayFrameFile, journeyOf, journeyVideoPath, isJourneyVideoFile, redactReplay, REPLAY_VIDEOS_DIRNAME, replayVideos, REPLAY_FILE, REPLAY_FRAMES_DIRNAME, replayFramePath, replayFrames, replaySessionKey, visitOf, } from "./engine/check-replay.js";
 /** The baselines folder a check uses: the one --baselines names, else the project's own. */
 export function baselinesDirOf(options) {
     return options.baselinesDir ?? defaultBaselinesDir(options.projectDir);
@@ -99,6 +100,21 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
     const engine = new BrowserEngine();
     /** One browser per role a flow runs as, each attached once, on first use, and closed with the check's own. */
     const roleEngines = new Map();
+    // --record: every browser keeps a frame after each step, under its own session name, in its own memory folder.
+    const record = options.record === true;
+    const startedAt = new Date().toISOString();
+    const store = new MemoryStore(scratch);
+    if (record)
+        engine.sessionKey = replaySessionKey();
+    // --video: each browser records every page into its own scratch folder, and each flow's own page is saved beside the report.
+    const video = options.video === true;
+    const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
+    // The default folder is inside .scenescout/, which ignores itself; its .gitignore goes first, so no frame or video is ever unignored.
+    if ((record || video) && !options.outDir) {
+        const scenescoutDir = path.join(options.projectDir, MEMORY_DIRNAME);
+        fs.mkdirSync(scenescoutDir, { recursive: true });
+        writeSelfIgnore(scenescoutDir);
+    }
     const start = new URL(options.url);
     // From the start of the run, browser launch included: the budget is wall-clock time a person waits.
     const deadline = options.timeBudgetMs !== undefined ? Date.now() + options.timeBudgetMs : undefined;
@@ -109,9 +125,11 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
         const attached = await engine.attach({
             url: start.origin,
             projectDir: options.projectDir,
-            memoryStore: new MemoryStore(scratch),
+            memoryStore: store,
             mode: options.mode,
             storageStatePath: options.storageStatePath,
+            ...(record ? { record: true } : {}),
+            ...(video ? { videoDir: path.join(scratch, "video") } : {}),
             ...(options.browser ? { browser: options.browser } : {}),
             actionTimeoutMs: options.actionTimeoutMs,
             navTimeoutMs: options.navTimeoutMs,
@@ -178,6 +196,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 return known;
             const roleEngine = new BrowserEngine();
             roleEngines.set(role, roleEngine);
+            if (record)
+                roleEngine.sessionKey = replaySessionKey(role);
             const roleDir = path.join(scratch, `role-${role}`);
             fs.mkdirSync(roleDir, { recursive: true });
             const attachedAs = await roleEngine.attach({
@@ -186,6 +206,8 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 memoryStore: new MemoryStore(roleDir),
                 mode: options.mode,
                 role,
+                ...(record ? { record: true } : {}),
+                ...(video ? { videoDir: path.join(roleDir, "video") } : {}),
                 ...(options.browser ? { browser: options.browser } : {}),
                 actionTimeoutMs: options.actionTimeoutMs,
                 navTimeoutMs: options.navTimeoutMs,
@@ -197,10 +219,29 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 throw new Error(`the saved sign-in for role "${role}" no longer signs in: ${lost.replace(/ Continuing now tests a logged-out app\.$/, "")}`);
             return roleEngine;
         };
+        /** On a recorded check, the frames each flow's steps left, beside the flow. */
+        const flowFrames = [];
+        /** On a check with --video, each flow's video beside the report (relative to it), or null where none was saved. */
+        const flowVideos = [];
         for (const flow of runFlows) {
             const runner = await engineFor(flow.role);
             // --flow-writes never: observe's rule, whatever --mode lets the crawl do.
-            const replay = await runner.replayFlow(flow.steps, options.flowWrites === "never" ? "observe" : options.mode);
+            const walk = () => runner.replayFlow(flow.steps, options.flowWrites === "never" ? "observe" : options.mode);
+            let walked;
+            if (video) {
+                // A page of its own, so the video is this journey's alone; the context, and so the sign-in, is the role's.
+                const rel = journeyVideoPath(flowRuns.length + 1, flow.file);
+                const own = await runner.onOwnPage(walk, path.join(outDir, ...rel.split("/")));
+                walked = own.value;
+                flowVideos.push(own.video ? rel : null);
+                if (own.videoError)
+                    log(`  flow ${flow.name}: its video could not be saved (${own.videoError})`);
+            }
+            else {
+                walked = await walk();
+            }
+            const { frames, ...replay } = walked;
+            flowFrames.push(frames ?? []);
             flowRuns.push({ name: flow.name, file: flow.file, steps: flow.steps.length, ...(flow.role === undefined ? {} : { role: flow.role }), ...replay });
             log(`  flow ${flow.name}${flow.role === undefined ? "" : ` (as ${flow.role})`}: ${replay.outcome.status}${replay.outcome.status === "passed" ? "" : ` at step ${replay.outcome.step}`}`);
             // --on-refused-step stop: nothing after a refused step runs, and the check ends without a verdict.
@@ -222,6 +263,22 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 }))),
             }
             : null;
+        const replay = record || video
+            ? recordReplay({
+                options,
+                startedAt,
+                ownRole: engine.role,
+                log: store.actionLog,
+                visited: [...routes, ...retestPages],
+                flows: runFlows
+                    .slice(0, flowRuns.length)
+                    .map((flow, i) => ({ flow, outcome: flowRuns[i].outcome, frames: flowFrames[i], video: flowVideos[i] ?? null })),
+                scratch,
+                say: log,
+            })
+            : null;
+        if (replay)
+            log(`  kept ${replayFrames(replay).length} frame(s) and ${replayVideos(replay).length} video(s) for ${REPLAY_FILE}`);
         const { pages: measured, resources } = splitResources(redactRoutes(routes.map(withoutOwnResponse)));
         const flows = redactFlowRuns(flowRuns);
         const pictured = baselines ? redactBaselineRun(baselines) : null;
@@ -248,6 +305,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             retest,
             settings: settingsOf(options),
             baselines: pictured,
+            ...(replay ? { replay } : {}),
         };
         // A value taken from the environment (a code, a password) is never written, wherever the page echoed it.
         return envValues.size > 0 ? JSON.parse(maskEnvValues(JSON.stringify(result), envValues)) : result;
@@ -403,3 +461,118 @@ async function takeBaselines(engine, options, mode, targets, log) {
     }
     return { mode, engine: engineName, threshold: options.baselineThreshold, dir: shownDir(dir, options.projectDir), results };
 }
+/**
+ * Remove what an earlier recorded check left beside the report: replay.html,
+ * the frames under replay-frames/ and the journey videos under replay-videos/
+ * that a check names as it names them (isReplayFrameFile, isJourneyVideoFile),
+ * then any folder that leaves empty. Run before every
+ * check, recorded or not, so a page from an earlier run is never read, or
+ * uploaded, as this one's; whatever else the folder holds stays.
+ */
+export function clearReplayOutput(outDir) {
+    fs.rmSync(path.join(outDir, REPLAY_FILE), { force: true });
+    const videos = path.join(outDir, REPLAY_VIDEOS_DIRNAME);
+    if (fs.existsSync(videos)) {
+        for (const file of fs.readdirSync(videos, { withFileTypes: true }))
+            if (file.isFile() && isJourneyVideoFile(file.name))
+                fs.rmSync(path.join(videos, file.name));
+        if (fs.readdirSync(videos).length === 0)
+            fs.rmdirSync(videos);
+    }
+    const root = path.join(outDir, REPLAY_FRAMES_DIRNAME);
+    let folders;
+    try {
+        folders = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+    for (const folder of folders.filter((f) => f.isDirectory())) {
+        const dir = path.join(root, folder.name);
+        for (const file of fs.readdirSync(dir, { withFileTypes: true }))
+            if (file.isFile() && isReplayFrameFile(file.name))
+                fs.rmSync(path.join(dir, file.name));
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    if (fs.readdirSync(root).length === 0)
+        fs.rmdirSync(root);
+}
+/**
+ * The replay page's model for a recorded check, with its frames copied from
+ * the browsers' scratch folders to replay-frames/ beside the report: routes
+ * visited in the check's own session, then each flow under the role it ran
+ * as. Capped and redacted here, so what is copied is exactly what the page shows.
+ */
+function recordReplay(o) {
+    const outDir = o.options.outDir ?? defaultCheckDir(o.options.projectDir);
+    /** Where each frame the page names is copied from. */
+    const sources = new Map();
+    const beside = (recorded, memoryDir) => {
+        const to = recorded ? replayFramePath(recorded) : null;
+        if (to && recorded)
+            sources.set(to, path.join(memoryDir, ...recorded.split("/")));
+        return to;
+    };
+    // The crawl's frames, by the path each visit asked for, in the order they were taken.
+    const own = replaySessionKey();
+    const crawled = new Map();
+    for (const e of o.log) {
+        if (e.action !== "crawl" || !e.frame || e.target === undefined || (e.session ?? own) !== own)
+            continue;
+        crawled.set(e.target, [...(crawled.get(e.target) ?? []), e.frame]);
+    }
+    const ownSession = {
+        role: o.ownRole,
+        own: true,
+        // A MemoryStore keeps its files, frames included, in the .scenescout folder of the directory it is given.
+        visits: o.visited.map((route) => visitOf(route, beside(crawled.get(route.path)?.shift(), path.join(o.scratch, MEMORY_DIRNAME)) ?? undefined)),
+        journeys: [],
+    };
+    const roles = [ownSession];
+    for (const { flow, outcome, frames, video } of o.flows) {
+        const memoryDir = path.join(flow.role === undefined ? o.scratch : path.join(o.scratch, `role-${flow.role}`), MEMORY_DIRNAME);
+        const journey = journeyOf(flow, outcome, frames.map((f) => beside(f, memoryDir)));
+        if (video)
+            journey.video = video;
+        let role = flow.role === undefined ? ownSession : roles.find((r) => !r.own && r.role === flow.role);
+        if (!role) {
+            role = { role: flow.role, own: false, visits: [], journeys: [] };
+            roles.push(role);
+        }
+        role.journeys.push(journey);
+    }
+    const replay = redactReplay(capFrames({ startedAt: o.startedAt, roles, framesLeftOut: 0 }));
+    // A frame that cannot be copied is left off the page rather than shown broken.
+    const copied = new Set();
+    let failed = false;
+    for (const rel of replayFrames(replay)) {
+        const from = sources.get(rel);
+        if (!from)
+            continue;
+        try {
+            const to = path.join(outDir, ...rel.split("/"));
+            fs.mkdirSync(path.dirname(to), { recursive: true });
+            fs.copyFileSync(from, to);
+            copied.add(rel);
+        }
+        catch (err) {
+            // Said once: a folder that refuses one frame usually refuses them all.
+            if (!failed)
+                o.say(`  could not copy a recorded frame to ${outDir}: ${firstLineOf(err)}; frames that could not be copied are left off ${REPLAY_FILE}`);
+            failed = true;
+        }
+    }
+    const keep = (item) => {
+        if (!item.frame || copied.has(item.frame))
+            return item;
+        const { frame: _gone, ...rest } = item;
+        return rest;
+    };
+    return {
+        ...replay,
+        roles: replay.roles.map((r) => ({ ...r, visits: r.visits.map(keep), journeys: r.journeys.map((j) => ({ ...j, steps: j.steps.map(keep) })) })),
+    };
+}

package/dist/cli.js

@@ -21,7 +21,9 @@ import { APPROX_DISK_MB, defaultAttachNote, defaultEngine, launchTarget, parseBr
 import { CLIENT_LABELS, firstMessageHint, manualFor, parseClients, registerWithClient, vscodeBinary } from "./clients.js";
 import { CLAUDE_CODE_NOT_NEEDED, CLI_NAME, desktopExtensionRoots, diagnose, doctorAllGood, findDesktopExtension, installClosing, ensureCommand, findOnUserPath, installSkill, isEphemeralRoot, launchCommand, manualRegisterCommand, planCommand, registerMcp, resolveClaudeDir, spawnRunner, } from "./installer.js";
 import { downloadBrowsers, presentBrowsers } from "./installer.js";
-import { baselinesDirOf, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { baselinesDirOf, clearReplayOutput, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { buildCheckReplayHtml, commitOf, REPLAY_FILE, replayFrames, replayVideos } from "./engine/check-replay.js";
+import { recordChoice } from "./engine/capture.js";
 import { httpClient, httpJudgeAsk, runCi } from "./ci-run.js";
 import { runExport } from "./export-run.js";
 import { runLogin, runScriptedLogin, savedLine } from "./login-run.js";
@@ -29,7 +31,7 @@ import { credentialRedactor, LOGIN_ENV, readScriptedLogin } from "./engine/scrip
 import { parseLoginArgs } from "./engine/profiles.js";
 import { detectProvider, EXIT_CI, judgeEffort, KEY_ENV, parseCiArgs, redactKeys, secretValues } from "./engine/ci.js";
 import { VISUAL_DIRNAME } from "./engine/baseline.js";
-import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, toSarif, toSummaryJson, unmeasuredReason, } from "./engine/check.js";
+import { EXIT, exitCodeOf, formatCheck, parseCheckArgs, refusedFlowReason, summarise, toSarif, toSummaryJson, unmeasuredReason, } from "./engine/check.js";
 import { downloadLine, EXIT_FIRST_RUN, FIRST_RUN_DIRNAME, firstRunCheckOptions, firstRunDownloads, firstRunSummary, formatFirstRun, modeSentence, parseFirstRunArgs, reportFolderProblem, unreachableReason, writeFirstRunReport, } from "./first-run.js";
 import { credentialSecrets, EXIT_EXPORT, parseExportArgs } from "./engine/export.js";
 import { LEGACY_MEMORY_DIRNAME, MEMORY_DIRNAME, writeSelfIgnore } from "./engine/memory.js";
@@ -105,7 +107,13 @@ Usage:
                                       passes; 0 counts every changed pixel);
                                      --sarif-file-anchor path: the repository file a SARIF result points at when
                                       no saved flow raised it (default: the running workflow's file on GitHub
-                                      Actions, else package.json, else README.md))
+                                      Actions, else package.json, else README.md);
+                                     --record [on|off]: keep a frame after each route visit and each flow step
+                                      and write replay.html beside the report, role → journey → step (default:
+                                      SCENESCOUT_RECORD, else off; the frames go in replay-frames/);
+                                     --video [on|off]: record a WebM of each saved flow, each on a page of its
+                                      own, into replay-videos/, linked from replay.html beside its steps
+                                      (default off))
                                     Exit code: 0 passed, 1 failed the gate, 2 could not run.
   scenescout ci <url>               An exploratory run with no person present: a model reached through its API
                                     drives the tools by the SceneScout method and the run ends in the report.
@@ -570,10 +578,14 @@ async function check(args) {
         console.error(`scenescout check: ${parsed.error}`);
         process.exit(EXIT.error);
     }
-    const options = parsed.options;
+    let options = parsed.options;
     const outDir = options.outDir ?? defaultCheckDir(options.projectDir);
     let inputs;
     try {
+        // --record, else SCENESCOUT_RECORD, else off.
+        options = { ...options, record: recordChoice(options.record, process.env) };
+        // A replay page an earlier run left must never be read, or uploaded, as this run's.
+        clearReplayOutput(outDir);
         inputs = readCheckInputs(options);
     }
     catch (err) {
@@ -618,6 +630,19 @@ async function check(args) {
             console.error(`scenescout check: ${sarifFiles.warning}`);
         fs.writeFileSync(path.join(outDir, "check.sarif"), JSON.stringify(toSarif(result, version, sarifFiles), null, 2) + "\n");
         fs.writeFileSync(path.join(outDir, "check.json"), JSON.stringify(toSummaryJson(result, version), null, 2) + "\n");
+        if (result.replay) {
+            const { passed, couldNotRun } = summarise(result);
+            const html = buildCheckReplayHtml(result.replay, {
+                version,
+                origin: new URL(result.url).origin,
+                startedAt: result.replay.startedAt,
+                endedAt: result.generatedAt,
+                commit: commitOf(process.env),
+                passed,
+                couldNotRun,
+            });
+            fs.writeFileSync(path.join(outDir, REPLAY_FILE), html);
+        }
         // On GitHub Actions the verdict also goes on the run's summary page.
         if (process.env.GITHUB_STEP_SUMMARY)
             fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, markdown);
@@ -629,6 +654,8 @@ async function check(args) {
     }
     console.log("\n" + markdown);
     console.log(`Wrote report.md, check.sarif and check.json to ${outDir}`);
+    if (result.replay)
+        console.log(`Wrote ${REPLAY_FILE} to ${outDir}, with ${replayFrames(result.replay).length} frame(s) and ${replayVideos(result.replay).length} journey video(s) beside it: open it in a browser to see each step`);
     const pictured = result.baselines?.results.filter((r) => r.files).length ?? 0;
     if (pictured > 0)
         console.log(`Wrote the pictures of ${pictured} changed baseline(s) under ${path.join(outDir, VISUAL_DIRNAME)}`);

package/dist/engine/browser.js

@@ -1184,6 +1184,7 @@ export class BrowserEngine {
                 viewport: opts.viewport ?? { width: 1280, height: 900 },
                 ...(opts.deviceScaleFactor !== undefined ? { deviceScaleFactor: opts.deviceScaleFactor } : {}),
                 serviceWorkers: serviceWorkerPolicy(this.engineName),
+                ...(opts.videoDir ? { recordVideo: { dir: opts.videoDir } } : {}),
             });
             const restoreSession = sessionStorageInitScript(profile?.sessionStorage ?? []);
             if (restoreSession)
@@ -1509,6 +1510,9 @@ export class BrowserEngine {
         // oracles attached); close foreign-origin popups so exploration cannot
         // silently escape the app under test.
         this.context.on("page", (newPage) => {
+            // A page the engine opened for itself (onOwnPage) is not a popup to adopt or close.
+            if (this.openingOwnPage)
+                return;
             newPage
                 .waitForLoadState("domcontentloaded", { timeout: this.limits.backNavMs })
                 .then(() => {
@@ -1671,6 +1675,66 @@ export class BrowserEngine {
     nativeDialogAt = 0;
     /** When a native dialog that asks something (confirm, prompt, a leave confirmation) last opened; an alert only tells. */
     nativeQuestionAt = 0;
+    /** True while onOwnPage opens its page, so the popup handler leaves it alone. */
+    openingOwnPage = false;
+    /** Open a page in this session's context and drive it from now on, wired as attach wires its first page. */
+    async driveNewPage() {
+        const context = this.context;
+        if (!context)
+            throw new Error("Not attached. Call scout_attach first with the app URL and project path.");
+        this.openingOwnPage = true;
+        let page;
+        try {
+            page = await context.newPage();
+        }
+        finally {
+            this.openingOwnPage = false;
+        }
+        this.oracles.attach(page);
+        this.wireDialogHandler(page);
+        this.wireEmbedMoves(page);
+        this.page = page;
+        this.refs.clear();
+        this.snapshotUrl = "";
+        this.forgetSnapshots();
+        return page;
+    }
+    /**
+     * Run `work` on a page of its own in this session's context, then close it.
+     * The context is the session's, so its cookies and storage carry over; on a
+     * session attached with `videoDir`, the page's video is this run's alone,
+     * and is saved to `videoTo`. Every page the work left open is closed with
+     * it, and a fresh page is driven afterwards. The video is null when the
+     * session records none or it could not be saved (`videoError` says why).
+     */
+    async onOwnPage(work, videoTo) {
+        const own = await this.driveNewPage();
+        let value;
+        try {
+            value = await work();
+        }
+        finally {
+            const context = this.context;
+            // The work may have adopted a popup, or been left on its own page: everything open now is the work's.
+            if (context)
+                await BrowserEngine.settleWithin(Promise.allSettled(context.pages().map((p) => p.close().catch(() => { }))), 10_000);
+            this.page = null;
+            if (context)
+                await this.driveNewPage();
+        }
+        const recording = own.video();
+        if (!recording || !videoTo)
+            return { value, video: null };
+        try {
+            await fs.promises.mkdir(path.dirname(videoTo), { recursive: true });
+            // saveAs waits until the page is closed and the video written.
+            await recording.saveAs(videoTo);
+            return { value, video: videoTo };
+        }
+        catch (err) {
+            return { value, video: null, videoError: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+        }
+    }
     requirePage() {
         if (!this.page || !this.memory) {
             throw new Error("Not attached. Call scout_attach first with the app URL and project path.");
@@ -5085,7 +5149,15 @@ export class BrowserEngine {
                     refusedBackground.push(sig);
             return charged;
         };
-        const done = (outcome) => ({ outcome, violations, refusedBackground, websockets: [...websockets] });
+        /** On a recorded session, the frame after each step that ran (null where none was kept), for the check's replay page. */
+        const frames = [];
+        const done = (outcome) => ({
+            outcome,
+            violations,
+            refusedBackground,
+            websockets: [...websockets],
+            ...(this.recording ? { frames } : {}),
+        });
         // Nothing from the crawl before this flow is charged to it.
         this.oracles.drain(false);
         this.blockedRequests = [];
@@ -5269,6 +5341,9 @@ export class BrowserEngine {
                 const n = i + 1;
                 const did = describeStep(step);
                 const { failure, refusal } = step.action === "repeat" ? await runRepeat(step) : await runStep(step);
+                // Taken whatever the step's result: the frame of a step that broke is the evidence of how it broke.
+                if (this.recording)
+                    frames.push((await this.recordFrame(`flow-${step.action}`)) ?? null);
                 if (refusal)
                     return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
                 if (failure)

package/dist/engine/check-replay.js

@@ -0,0 +1,287 @@
+/**
+ * The replay page of a recorded `scenescout check` (`--record`): what each
+ * role did, journey by journey and step by step, with the frame the page
+ * showed after each step, so a green run leaves evidence of what passed and a
+ * red one shows where it broke.
+ *
+ * A journey is a saved flow (flow.ts); a role is the session it ran in, the
+ * check's own or the one its `role` names. The check's own session also lists
+ * the routes it visited, one frame each.
+ *
+ * Everything here is pure: the mapping of steps to captions and results, the
+ * frame cap, the redaction and the page itself are table-tested. check-run.ts
+ * gathers the frames from the browser and copies them beside the page.
+ */
+import { redactRoute } from "./memory.js";
+import { describeStep } from "./flow.js";
+import { escapeHtml, plainSegment, RECORD_MAX_FRAMES } from "./replay.js";
+/** The file the page is written to, beside report.md. */
+export const REPLAY_FILE = "replay.html";
+/** The folder beside it that holds the frames the page shows. */
+export const REPLAY_FRAMES_DIRNAME = "replay-frames";
+/** The folder beside it that holds one video per journey (--video). */
+export const REPLAY_VIDEOS_DIRNAME = "replay-videos";
+/**
+ * Each step of a replayed flow with its caption, its result and its frame.
+ * The replay stops at the first step that breaks, so every step before it
+ * passed, it is the failing one, and those after it never ran (and have no
+ * frame). `frames` holds one entry per executed step, null where none was kept.
+ */
+export function journeySteps(steps, outcome, frames = []) {
+    const broke = outcome.status === "passed" ? null : outcome.step;
+    return steps.map((step, i) => {
+        const n = i + 1;
+        const frame = broke === null || n <= broke ? (frames[i] ?? undefined) : undefined;
+        const base = { n, caption: describeStep(step), ...(frame ? { frame } : {}) };
+        if (broke === null || n < broke)
+            return { ...base, result: "passed" };
+        if (n > broke)
+            return { n, caption: base.caption, result: "not-run" };
+        // `broke` is set only when the outcome is not "passed".
+        const failed = outcome;
+        return { ...base, result: failed.status, reason: failed.reason, path: failed.path };
+    });
+}
+/** One journey of the page, from a flow and how its replay went. */
+export function journeyOf(flow, outcome, frames) {
+    return {
+        name: flow.name,
+        file: flow.file,
+        status: outcome.status,
+        steps: journeySteps(flow.steps, outcome, frames),
+        ...(outcome.status === "passed" ? {} : { firstFailing: outcome.step }),
+    };
+}
+/** One visited route, from what the crawl measured. */
+export function visitOf(route, frame) {
+    const result = route.loadError !== undefined ? "not-loaded" : route.loginRedirect ? "sign-in" : route.status !== null && route.status >= 400 ? "http-error" : "loaded";
+    return {
+        path: route.path,
+        status: route.status,
+        result,
+        ...(route.loadError !== undefined ? { reason: route.loadError } : {}),
+        ...(frame ? { frame } : {}),
+    };
+}
+/**
+ * At most `max` frames per role, the first ones kept: the same cap a recorded
+ * session keeps (RECORD_MAX_FRAMES), held here too so the page never shows
+ * more than the run was allowed to take, whatever it is handed.
+ */
+export function capFrames(replay, max = RECORD_MAX_FRAMES) {
+    let leftOut = replay.framesLeftOut;
+    const roles = replay.roles.map((role) => {
+        let kept = 0;
+        const take = (item) => {
+            if (!item.frame)
+                return item;
+            if (kept < max) {
+                kept += 1;
+                return item;
+            }
+            leftOut += 1;
+            const { frame: _dropped, ...rest } = item;
+            return rest;
+        };
+        return {
+            ...role,
+            visits: role.visits.map(take),
+            journeys: role.journeys.map((j) => ({ ...j, steps: j.steps.map(take) })),
+        };
+    });
+    return { ...replay, roles, framesLeftOut: leftOut };
+}
+/** The report's redaction (memory.ts redactRoute) on every path, caption and reason the page shows. */
+export function redactReplay(replay) {
+    return {
+        ...replay,
+        roles: replay.roles.map((role) => ({
+            ...role,
+            visits: role.visits.map((v) => ({ ...v, path: redactRoute(v.path), ...(v.reason !== undefined ? { reason: redactRoute(v.reason) } : {}) })),
+            journeys: role.journeys.map((j) => ({
+                ...j,
+                steps: j.steps.map((s) => ({
+                    ...s,
+                    caption: redactRoute(s.caption),
+                    ...(s.reason !== undefined ? { reason: redactRoute(s.reason) } : {}),
+                    ...(s.path !== undefined ? { path: redactRoute(s.path) } : {}),
+                })),
+            })),
+        })),
+    };
+}
+/**
+ * Where the video of the n-th journey run (1-based) goes beside the page. The
+ * flow's file name is reduced to a plain segment, so it decides nothing about
+ * where the file is written; the number keeps two flows' videos apart.
+ */
+export function journeyVideoPath(n, file) {
+    return `${REPLAY_VIDEOS_DIRNAME}/journey-${String(n).padStart(2, "0")}-${plainSegment(file.replace(/\.json$/i, ""), "flow")}.webm`;
+}
+/** Whether a file under replay-videos/ is a video a check wrote, and so one an earlier run's clean-up may remove. */
+export function isJourneyVideoFile(name) {
+    return /^journey-\d{2,}-[a-z0-9._-]+\.webm$/i.test(name);
+}
+/** Every journey video the page links, in page order. */
+export function replayVideos(replay) {
+    return replay.roles.flatMap((r) => r.journeys.flatMap((j) => (j.video ? [j.video] : [])));
+}
+/** Every frame the page shows, in page order. */
+export function replayFrames(replay) {
+    return replay.roles.flatMap((r) => [
+        ...r.visits.flatMap((v) => (v.frame ? [v.frame] : [])),
+        ...r.journeys.flatMap((j) => j.steps.flatMap((s) => (s.frame ? [s.frame] : []))),
+    ]);
+}
+const RECORDED_FRAME = /^recordings\/([a-z0-9._-]+)\/(\d{4}-[a-z0-9._-]+\.jpg)$/i;
+/**
+ * Where a frame a session recorded (replay.ts framePath) goes beside the
+ * page, or null for anything that is not one: the path is used to write a
+ * file, so nothing else is let through.
+ */
+export function replayFramePath(recorded) {
+    const m = RECORDED_FRAME.exec(recorded);
+    return m ? `${REPLAY_FRAMES_DIRNAME}/${m[1]}/${m[2]}` : null;
+}
+/** Whether a file in a session folder under replay-frames/ is a frame a check wrote, and so one an earlier run's clean-up may remove. */
+export function isReplayFrameFile(name) {
+    return /^\d{4}-[a-z0-9._-]+\.jpg$/i.test(name);
+}
+/** The session name a check's own browser records its frames under, and one for each role's. Distinct, so their frames never share a folder. */
+export function replaySessionKey(role) {
+    return role === undefined ? "check" : `role-${plainSegment(role, "role")}`;
+}
+/** A commit to name in the page's header: GITHUB_SHA when it is one, else none. */
+export function commitOf(env) {
+    const sha = (env.GITHUB_SHA ?? "").trim();
+    return /^[0-9a-f]{7,64}$/i.test(sha) ? sha.toLowerCase() : undefined;
+}
+const RESULT_WORD = { passed: "passed", failed: "failed", refused: "refused", "not-run": "not run" };
+const VISIT_WORD = {
+    loaded: "loaded",
+    "http-error": "HTTP error",
+    "sign-in": "sent to sign-in",
+    "not-loaded": "did not load",
+};
+/** A UTC time as the page shows it: the reader's own clock is not this page's to assume. */
+function stamp(iso) {
+    return iso.length >= 19 ? `${iso.slice(0, 10)} ${iso.slice(11, 19)} UTC` : iso;
+}
+const GONE = `onerror="this.parentNode.classList.add('gone')"`;
+function frameHtml(frame, alt) {
+    if (!frame)
+        return `<p class="noframe">No frame</p>`;
+    const src = escapeHtml(frame);
+    return (`<a class="frame" href="${src}" target="_blank" rel="noreferrer" data-testid="replay-frame-open"><img loading="lazy" ${GONE} src="${src}" alt="${escapeHtml(alt)}">` +
+        `<span class="gone-note">This frame is not beside this file. Frames live in the <code>${REPLAY_FRAMES_DIRNAME}/</code> folder, which travels with it.</span></a>`);
+}
+function stepHtml(s, anchor) {
+    const first = s.result === "failed" || s.result === "refused";
+    const detail = [s.reason, s.path ? `on ${s.path}` : ""].filter(Boolean).join(" ");
+    return (`<li class="step ${s.result}${first ? " first-failing" : ""}"${first ? ` id="${anchor}"` : ""} data-result="${s.result}">` +
+        `<div class="caption"><span class="n">${s.n}</span> <span class="what">${escapeHtml(s.caption)}</span> <span class="result r-${s.result}">${RESULT_WORD[s.result]}</span></div>` +
+        (detail ? `<p class="why">${escapeHtml(detail)}</p>` : "") +
+        (s.result === "not-run" ? "" : frameHtml(s.frame, `The page after step ${s.n}: ${s.caption}`)) +
+        `</li>`);
+}
+function journeyHtml(j, id) {
+    const ok = j.status === "passed";
+    const anchor = `${id}-first-failing`;
+    const badge = ok ? `<span class="badge pass">passed</span>` : `<span class="badge fail">${j.status}</span>`;
+    const jump = j.firstFailing !== undefined
+        ? `<a class="jump" href="#${anchor}" data-testid="replay-first-failing-link">Step ${j.firstFailing} ${j.status}</a>`
+        : `<span class="count">${j.steps.length} step${j.steps.length === 1 ? "" : "s"}</span>`;
+    return (`<details class="journey ${ok ? "pass" : "fail"}"${ok ? "" : " open"} data-status="${j.status}"><summary data-testid="replay-journey-toggle">${badge} <b>${escapeHtml(j.name)}</b> <span class="file">${escapeHtml(j.file)}</span> ${jump}</summary>` +
+        (j.video
+            ? `<figure class="video"><video controls preload="metadata" src="${escapeHtml(j.video)}" data-testid="replay-journey-video"></video>` +
+                `<figcaption>The whole journey as it ran. <a href="${escapeHtml(j.video)}" target="_blank" rel="noreferrer" data-testid="replay-video-open">Open the video</a></figcaption></figure>`
+            : "") +
+        `<ol class="steps">${j.steps.map((s) => stepHtml(s, anchor)).join("")}</ol></details>`);
+}
+function visitsHtml(visits) {
+    if (visits.length === 0)
+        return "";
+    const items = visits
+        .map((v) => `<li class="visit ${v.result}"><div class="caption"><span class="what">visit ${escapeHtml(v.path)}</span> <span class="result v-${v.result}">${v.status ?? "—"} · ${VISIT_WORD[v.result]}</span></div>` +
+        (v.reason ? `<p class="why">${escapeHtml(v.reason)}</p>` : "") +
+        frameHtml(v.frame, `The page at ${v.path}`) +
+        `</li>`)
+        .join("");
+    return `<details class="visits"><summary data-testid="replay-visits-toggle">Routes visited <span class="count">${visits.length}</span></summary><ol class="steps">${items}</ol></details>`;
+}
+function roleHtml(r, i) {
+    const failing = r.journeys.filter((j) => j.status !== "passed").length;
+    const tally = `${r.journeys.length} journey${r.journeys.length === 1 ? "" : "s"}${failing ? `, ${failing} not passed` : ""}`;
+    return (`<section class="role" id="role-${i}"><h2>${escapeHtml(r.role)} <span class="count">${r.own ? "the check's own session · " : ""}${tally}</span></h2>` +
+        visitsHtml(r.visits) +
+        (r.journeys.length > 0 ? r.journeys.map((j, k) => journeyHtml(j, `role-${i}-journey-${k}`)).join("") : `<p class="none">No journey ran as this role.</p>`) +
+        `</section>`);
+}
+const STYLE = `
+:root { color-scheme: light dark; --bg:#f6f7f9; --panel:#fff; --line:#d9dde3; --text:#15181d; --muted:#5d6673; --accent:#2563eb; --pass:#047857; --pass-bg:#d1fae5; --fail:#b91c1c; --fail-bg:#fee2e2; }
+@media (prefers-color-scheme: dark) { :root { --bg:#0e1116; --panel:#161a21; --line:#2a303a; --text:#e6e9ee; --muted:#98a2b3; --accent:#7aa2ff; --pass:#6ee7b7; --pass-bg:#063b2c; --fail:#fca5a5; --fail-bg:#3f1010; } }
+* { 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 { padding:14px 20px; background:var(--panel); border-bottom:1px solid var(--line); }
+header h1 { margin:0 0 4px; font-size:18px; display:flex; gap:10px; align-items:center; flex-wrap:wrap; }
+header dl { display:flex; flex-wrap:wrap; gap:4px 18px; margin:0; font-size:13px; color:var(--muted); }
+header dt { font-weight:600; } header dd { margin:0 0 0 4px; overflow-wrap:anywhere; }
+header .pair { display:flex; }
+main { max-width:1000px; margin:0 auto; padding:20px 16px 64px; }
+h2 { font-size:19px; margin:28px 0 10px; }
+.count, .file { color:var(--muted); font-size:13px; font-weight:400; }
+.badge { display:inline-block; padding:1px 8px; border-radius:999px; font-size:12px; font-weight:700; text-transform:uppercase; letter-spacing:.03em; }
+.badge.pass { color:var(--pass); background:var(--pass-bg); } .badge.fail { color:var(--fail); background:var(--fail-bg); }
+details.journey, details.visits { background:var(--panel); border:1px solid var(--line); border-radius:8px; margin:10px 0; padding:10px 14px; }
+details.journey.fail { border-color:var(--fail); }
+summary { cursor:pointer; }
+.jump { color:var(--fail); font-size:13px; margin-left:6px; }
+ol.steps { list-style:none; margin:10px 0 0; padding:0; }
+.step, .visit { border-left:3px solid var(--line); padding:6px 10px; margin:0 0 10px; }
+.step.passed, .visit.loaded { border-color:var(--pass); }
+.step.failed, .step.refused, .visit.http-error, .visit.not-loaded, .visit.sign-in { border-color:var(--fail); }
+.step.first-failing { background:var(--fail-bg); border-left-width:6px; }
+.step.not-run { opacity:.6; }
+.caption { display:flex; flex-wrap:wrap; gap:6px 10px; align-items:baseline; }
+.caption .n { font-weight:700; color:var(--muted); min-width:1.5em; }
+.caption .what { font:13px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; overflow-wrap:anywhere; }
+.result { margin-left:auto; font-size:12px; font-weight:700; }
+.r-passed, .v-loaded { color:var(--pass); } .r-failed, .r-refused, .v-http-error, .v-not-loaded, .v-sign-in { color:var(--fail); } .r-not-run { color:var(--muted); }
+.why { margin:4px 0; font-size:13px; overflow-wrap:anywhere; }
+a.frame { display:block; margin:6px 0 2px; max-width:min(100%,720px); }
+a.frame img { max-width:100%; max-height:400px; object-fit:cover; object-position:top; border:1px solid var(--line); border-radius:6px; display:block; }
+.gone-note { display:none; padding:12px; border:1px dashed var(--line); border-radius:6px; color:var(--muted); font-size:12px; }
+a.frame.gone img { display:none; } a.frame.gone .gone-note { display:block; }
+.noframe, .none { color:var(--muted); font-size:12px; font-style:italic; margin:4px 0; }
+.note { color:var(--muted); font-size:13px; }
+figure.video { margin:10px 0; max-width:min(100%,720px); }
+figure.video video { width:100%; border:1px solid var(--line); border-radius:6px; display:block; background:#000; }
+figure.video figcaption { color:var(--muted); font-size:12px; margin-top:4px; }
+`;
+/** The whole page: one HTML file with no external assets or scripts; its frames sit beside it in replay-frames/. */
+export function buildCheckReplayHtml(replay, meta) {
+    const verdict = meta.couldNotRun > 0 ? "could not run every flow" : meta.passed ? "passed" : "failed";
+    const badge = `<span class="badge ${meta.passed && meta.couldNotRun === 0 ? "pass" : "fail"}" data-testid="replay-verdict">${verdict}</span>`;
+    const pair = (term, value) => `<div class="pair"><dt>${term}</dt><dd>${escapeHtml(value)}</dd></div>`;
+    const frames = replayFrames(replay).length;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>SceneScout check replay — ${escapeHtml(meta.origin)}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+<header>
+  <h1>SceneScout check replay ${badge}</h1>
+  <dl>${pair("App", meta.origin)}${pair("Started", stamp(meta.startedAt))}${pair("Ended", stamp(meta.endedAt))}${meta.commit ? pair("Commit", meta.commit) : ""}${pair("SceneScout", `v${meta.version}`)}${pair("Frames", String(frames))}${replayVideos(replay).length > 0 ? pair("Videos", String(replayVideos(replay).length)) : ""}</dl>
+</header>
+<main>
+<p class="note">Each role, then each journey it walked, step by step, with the page as it was after the step${frames === 0 ? " when the check was recorded (--record)" : ""}. Typed values are never shown, and secrets in addresses are redacted as in the report.${replay.framesLeftOut > 0 ? ` ${replay.framesLeftOut} frame(s) past the cap of ${RECORD_MAX_FRAMES} per role are not kept; those steps show no frame.` : ""}</p>
+${replay.roles.map(roleHtml).join("\n") || '<p class="none">Nothing was recorded.</p>'}
+</main>
+</body>
+</html>
+`;
+}

package/dist/engine/check.js

@@ -501,7 +501,13 @@ export const CHECK_OPTION_NAMES = [
     "baselines",
     "baseline-threshold",
     "sarif-file-anchor",
+    "record",
+    "video",
 ];
+/** Options that may be given alone, meaning on: `--record`, as well as `--record on` and `--record=off`. */
+const SWITCH_OPTIONS = new Set(["record", "video"]);
+const SWITCH_ON = ["on", "true", "1"];
+const SWITCH_OFF = ["off", "false", "0"];
 export const MAX_CHECK_ROUTES = 150;
 /** Link discovery rounds: each crawl reveals the routes its pages link to. Past a few, a site is paginating rather than revealing. */
 export const MAX_DISCOVERY_ROUNDS = 6;
@@ -522,6 +528,14 @@ export function parseCheckArgs(args, cwd) {
         }
         const eq = a.indexOf("=");
         const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+        // A switch takes the next argument only when it is on or off: `--record http://…` records, and checks that URL.
+        if (eq < 0 && SWITCH_OPTIONS.has(name)) {
+            const next = args[i + 1]?.toLowerCase();
+            if (next !== undefined && [...SWITCH_ON, ...SWITCH_OFF].includes(next))
+                i += 1;
+            flags.set(name, next !== undefined && [...SWITCH_ON, ...SWITCH_OFF].includes(next) ? next : "on");
+            continue;
+        }
         const value = eq > 0 ? a.slice(eq + 1) : args[i + 1];
         if (value === undefined || (eq < 0 && value.startsWith("--")))
             return { ok: false, error: `--${name} needs a value` };
@@ -663,6 +677,14 @@ export function parseCheckArgs(args, cwd) {
     const anchor = flags.has("sarif-file-anchor") ? checkSarifAnchor(flags.get("sarif-file-anchor")) : undefined;
     if (anchor && !anchor.ok)
         return anchor;
+    const recordRaw = flags.get("record")?.trim().toLowerCase();
+    if (recordRaw !== undefined && !SWITCH_ON.includes(recordRaw) && !SWITCH_OFF.includes(recordRaw)) {
+        return { ok: false, error: "--record is on or off, or given alone for on" };
+    }
+    const videoRaw = flags.get("video")?.trim().toLowerCase();
+    if (videoRaw !== undefined && !SWITCH_ON.includes(videoRaw) && !SWITCH_OFF.includes(videoRaw)) {
+        return { ok: false, error: "--video is on or off, or given alone for on" };
+    }
     const resolve = (p) => resolveArgPath(cwd, p);
     return {
         ok: true,
@@ -689,6 +711,8 @@ export function parseCheckArgs(args, cwd) {
             ...(baselinesDir !== undefined ? { baselinesDir: resolve(baselinesDir) } : {}),
             baselineThreshold: threshold.value,
             ...(anchor ? { sarifFileAnchor: anchor.value } : {}),
+            ...(recordRaw !== undefined ? { record: SWITCH_ON.includes(recordRaw) } : {}),
+            ...(videoRaw !== undefined && SWITCH_ON.includes(videoRaw) ? { video: true } : {}),
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scenescout",
-  "version": "3.19.2",
+  "version": "3.20.0",
   "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",