scenescout 3.19.2 → 3.20.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # scenescout
 
+## 3.20.1
+
+### Patch Changes
+
+- 5d5240e: `scenescout check --video` now films each saved flow on the session's own page, so sessionStorage one flow writes is there for the next, and only the flows are filmed, not the crawl. The replay page marks and counts every step and visit left without a frame because its session reached the frame cap, has no scripts or inline event handlers, and carries a generator mark: a check removes only a `replay.html` that has it, so a file of that name the project keeps in the output folder stays.
+
+## 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, isGeneratedReplay, 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,22 @@ 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 flow is filmed on its session's page, from its first step to its hand-back, and saved beside the report.
+    const video = options.video === true;
+    const frameCap = options.maxFrames;
+    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 +126,10 @@ 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, ...(frameCap !== undefined ? { maxFrames: frameCap } : {}) } : {}),
             ...(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,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                 memoryStore: new MemoryStore(roleDir),
                 mode: options.mode,
                 role,
+                ...(record ? { record: true, ...(frameCap !== undefined ? { maxFrames: frameCap } : {}) } : {}),
                 ...(options.browser ? { browser: options.browser } : {}),
                 actionTimeoutMs: options.actionTimeoutMs,
                 navTimeoutMs: options.navTimeoutMs,
@@ -197,10 +218,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) {
+                // Filmed on the session's own page, so the flow runs exactly as it would unfilmed and the video holds it alone.
+                const rel = journeyVideoPath(flowRuns.length + 1, flow.file);
+                const own = await runner.filming(path.join(outDir, ...rel.split("/")), walk);
+                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 +262,23 @@ 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,
+                ...(frameCap !== undefined ? { frameCap } : {}),
+            })
+            : 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,135 @@ 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. replay.html goes only when it carries
+ * the check's generator mark (isGeneratedReplay). 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) {
+    // Only a page a check wrote: a file of the same name the project keeps there is its own.
+    const page = path.join(outDir, REPLAY_FILE);
+    let text = null;
+    try {
+        text = fs.readFileSync(page, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    if (text !== null && isGeneratedReplay(text))
+        fs.rmSync(page);
+    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();
+    /** A shot with its frame's path moved to where it is copied beside the page. */
+    const beside = (shot, memoryDir) => {
+        if (!shot?.frame)
+            return shot?.pastCap ? { pastCap: true } : {};
+        const to = replayFramePath(shot.frame);
+        if (!to)
+            return {};
+        sources.set(to, path.join(memoryDir, ...shot.frame.split("/")));
+        return { frame: to };
+    };
+    // What the crawl kept for each visit, by the path it asked for, in the order the visits ran.
+    const own = replaySessionKey();
+    const crawled = new Map();
+    for (const e of o.log) {
+        if (e.action !== "crawl" || e.target === undefined || (e.session ?? own) !== own)
+            continue;
+        const shot = e.frame ? { frame: e.frame } : e.framePastCap ? { pastCap: true } : {};
+        crawled.set(e.target, [...(crawled.get(e.target) ?? []), shot]);
+    }
+    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)))),
+        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, ...(o.frameCap !== undefined ? { frameCap: o.frameCap } : {}) }));
+    // 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,12 @@ 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, and only of the flows,
+                                      into replay-videos/, played on 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 +577,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 +629,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 +653,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

@@ -460,6 +460,8 @@ export class BrowserEngine {
      * checked, a recording shows it.
      */
     recording = false;
+    /** Most frames this recorded session keeps (attach's maxFrames). */
+    maxFrames = RECORD_MAX_FRAMES;
     framesKept = 0;
     /** How many frames could not be written. The first one says so in the log; the rest are counted. */
     framesFailed = 0;
@@ -592,8 +594,13 @@ export class BrowserEngine {
      * page looked like: `...(await this.frameFor("crawl"))`.
      */
     async frameFor(action) {
+        const pastCap = this.framePastCap();
         const frame = await this.recordFrame(action);
-        return frame ? { frame } : {};
+        return frame ? { frame } : pastCap ? { framePastCap: true } : {};
+    }
+    /** On a recorded session, whether the next step gets no frame because the session already keeps as many as it may. */
+    framePastCap() {
+        return this.recording && this.framesKept >= this.maxFrames;
     }
     /**
      * The frame for the step just taken, as a path relative to the memory
@@ -603,7 +610,7 @@ export class BrowserEngine {
      */
     async recordFrame(action) {
         const dir = this.memory?.dir;
-        if (!this.recording || !dir || this.framesKept >= RECORD_MAX_FRAMES)
+        if (!this.recording || !dir || this.framesKept >= this.maxFrames)
             return undefined;
         const jpeg = await this.liveShot(RECORD_SHOT_TIMEOUT_MS);
         if (!jpeg)
@@ -630,8 +637,8 @@ export class BrowserEngine {
             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() ?? "" });
+        if (this.framesKept === this.maxFrames) {
+            this.logAction({ action: "record:full", target: `${this.maxFrames} frames kept; later steps have none`, url: this.page?.url() ?? "" });
         }
         return rel;
     }
@@ -1104,6 +1111,7 @@ export class BrowserEngine {
         this.setTask(opts.task ?? "Attaching and taking stock", opts.task !== undefined);
         this.setPace(opts.paceMs);
         this.recording = opts.record === true;
+        this.maxFrames = opts.maxFrames ?? RECORD_MAX_FRAMES;
         // 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;
@@ -1671,6 +1679,41 @@ 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;
+    /**
+     * Run `work` while the session's page is filmed into `videoTo` (a WebM,
+     * Playwright's page screencast), so the video holds that work and nothing
+     * the session did before or after it. The page, its tab and so its
+     * sessionStorage are the session's own: the work runs exactly as it would
+     * unfilmed. The video is null when it could not be started or saved
+     * (`videoError` says why); the work's own result and errors are untouched.
+     */
+    async filming(videoTo, work) {
+        const page = this.requirePage();
+        const why = (err) => (err instanceof Error ? err.message.split("\n")[0] : String(err));
+        let videoError;
+        let filming = false;
+        try {
+            await fs.promises.mkdir(path.dirname(videoTo), { recursive: true });
+            await page.screencast.start({ path: videoTo, ...(page.viewportSize() ? { size: page.viewportSize() } : {}) });
+            filming = true;
+        }
+        catch (err) {
+            videoError = `the video could not be started: ${why(err)}`;
+        }
+        let value;
+        try {
+            value = await work();
+        }
+        finally {
+            // The page the filming began on, even if the work moved the session to a popup.
+            if (filming)
+                await page.screencast.stop().catch((err) => (videoError = `the video could not be saved: ${why(err)}`));
+        }
+        if (videoError)
+            return { value, video: null, videoError };
+        const saved = await fs.promises.stat(videoTo).then((st) => st.size > 0, () => false);
+        return saved ? { value, video: videoTo } : { value, video: null, videoError: "no video was written" };
+    }
     requirePage() {
         if (!this.page || !this.memory) {
             throw new Error("Not attached. Call scout_attach first with the app URL and project path.");
@@ -4405,7 +4448,8 @@ export class BrowserEngine {
     async inspectRoute(page, elements, url) {
         const { geometry, brokenImages } = await this.measureLayout(page, elements, url);
         try {
-            const { defects, sampled } = await this.auditPage();
+            // The crawl has just kept this page's frame; a second of the same page would only use up the session's cap.
+            const { defects, sampled } = await this.auditPage({ frame: false });
             // Nothing styled to read is not a clean page: contrast, focus and target size went unmeasured.
             return sampled > 0
                 ? { geometry, brokenImages, design: defects }
@@ -5085,7 +5129,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 +5321,12 @@ 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) {
+                    const pastCap = this.framePastCap();
+                    const frame = await this.recordFrame(`flow-${step.action}`);
+                    frames.push(frame ? { frame } : pastCap ? { pastCap: true } : {});
+                }
                 if (refusal)
                     return done({ status: "refused", step: n, did, reason: refusal.split("\n")[0], path: here() });
                 if (failure)
@@ -5327,7 +5385,7 @@ export class BrowserEngine {
         return `URL: ${url}\n` + report;
     }
     /** The design audit's measurements, as data as well as prose; scout_design_audit and a check's crawl share it. */
-    async auditPage() {
+    async auditPage(opts = {}) {
         const page = this.requirePage();
         await this.settle();
         const payload = (await page.evaluate(DESIGN_COLLECT_SCRIPT));
@@ -5349,7 +5407,12 @@ export class BrowserEngine {
             this.memory?.setPageScore(route, { ...score, at: new Date().toISOString(), url: page.url() });
             this.memory?.markRouteFact(route, { audited: true });
         }
-        this.logAction({ action: "design-audit", url: page.url(), result: score ? `score:${score.overall}` : undefined, ...(await this.frameFor("design-audit")) });
+        this.logAction({
+            action: "design-audit",
+            url: page.url(),
+            result: score ? `score:${score.overall}` : undefined,
+            ...(opts.frame === false ? {} : await this.frameFor("design-audit")),
+        });
         return { url: page.url(), report, defects, sampled: payload.records.length };
     }
     /**

package/dist/engine/check-replay.js

@@ -0,0 +1,315 @@
+/**
+ * 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 page's generator mark: an earlier run's page is removed only when it carries it, never a file of the same name. */
+export const REPLAY_GENERATOR = "scenescout-check-replay";
+/** Whether a replay.html is one a check wrote. */
+export function isGeneratedReplay(html) {
+    return html.includes(`<meta name="generator" content="${REPLAY_GENERATOR}">`);
+}
+/** 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";
+/** A shot's fields as an item carries them. */
+function shotFields(shot) {
+    if (shot?.frame)
+        return { frame: shot.frame };
+    return shot?.pastCap ? { pastCap: true } : {};
+}
+/**
+ * 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: its frame, or why it has none.
+ */
+export function journeySteps(steps, outcome, frames = []) {
+    const broke = outcome.status === "passed" ? null : outcome.step;
+    return steps.map((step, i) => {
+        const n = i + 1;
+        const shot = broke === null || n <= broke ? shotFields(frames[i]) : {};
+        const base = { n, caption: describeStep(step), ...shot };
+        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, shot) {
+    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 } : {}),
+        ...shotFields(shot),
+    };
+}
+/**
+ * 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. A step
+ * dropped here is marked past the cap like one the session did not take, and
+ * `framesLeftOut` counts both, so the page says why each has no frame.
+ */
+export function capFrames(replay, max = replay.frameCap ?? RECORD_MAX_FRAMES) {
+    let leftOut = 0;
+    const roles = replay.roles.map((role) => {
+        let kept = 0;
+        const take = (item) => {
+            if (item.pastCap)
+                leftOut += 1;
+            if (!item.frame)
+                return item;
+            if (kept < max) {
+                kept += 1;
+                return item;
+            }
+            leftOut += 1;
+            const { frame: _dropped, ...rest } = item;
+            return { ...rest, pastCap: true };
+        };
+        return {
+            ...role,
+            visits: role.visits.map(take),
+            journeys: role.journeys.map((j) => ({ ...j, steps: j.steps.map(take) })),
+        };
+    });
+    return { ...replay, roles, framesLeftOut: leftOut, frameCap: max };
+}
+/** 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;
+}
+/**
+ * A frame, or a line saying why there is none. No script: the note sits in the
+ * same grid cell under the picture, so a picture that loads covers it and one
+ * that is missing (a copy sent without replay-frames/) leaves it showing.
+ */
+function frameHtml(item, alt, cap) {
+    if (!item.frame)
+        return item.pastCap
+            ? `<p class="noframe">No frame: the session had already kept ${cap}, the most one session keeps.</p>`
+            : `<p class="noframe">No frame</p>`;
+    const src = escapeHtml(item.frame);
+    return (`<a class="frame" href="${src}" target="_blank" rel="noreferrer" data-testid="replay-frame-open">` +
+        `<span class="gone-note">If no picture shows here, this frame is not beside this file. Frames live in the <code>${REPLAY_FRAMES_DIRNAME}/</code> folder, which travels with it.</span>` +
+        `<img loading="lazy" src="${src}" alt="${escapeHtml(alt)}"></a>`);
+}
+function stepHtml(s, anchor, cap) {
+    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, `The page after step ${s.n}: ${s.caption}`, cap)) +
+        `</li>`);
+}
+function journeyHtml(j, id, cap) {
+    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, cap)).join("")}</ol></details>`);
+}
+function visitsHtml(visits, cap) {
+    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, `The page at ${v.path}`, cap) +
+        `</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, cap) {
+    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, cap) +
+        (r.journeys.length > 0
+            ? r.journeys.map((j, k) => journeyHtml(j, `role-${i}-journey-${k}`, cap)).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: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); }
+.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; }
+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 scripts, no event handlers and no external assets; its frames and videos sit beside it. */
+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">
+<meta name="generator" content="${REPLAY_GENERATOR}">
+<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} step(s) and visit(s) have no frame because their session had already kept ${replay.frameCap ?? RECORD_MAX_FRAMES}, the most one session keeps.`
+        : ""}</p>
+${replay.roles.map((r, i) => roleHtml(r, i, replay.frameCap ?? RECORD_MAX_FRAMES)).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.1",
   "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",