scenescout 3.20.0 → 3.20.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # scenescout
 
+## 3.20.2
+
+### Patch Changes
+
+- f8f7ad2: A recorded `scenescout check` (`--record` or `--video`) no longer overwrites a `replay.html` in the output folder that it did not write: it stops before it starts, with exit code 2 and a message naming the file. With `--video`, a video that fails to start no longer stops every later flow from being filmed.
+
+## 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

package/dist/check-run.js

@@ -19,7 +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";
+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);
@@ -106,8 +106,9 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
     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.
+    // --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) {
@@ -128,8 +129,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             memoryStore: store,
             mode: options.mode,
             storageStatePath: options.storageStatePath,
-            ...(record ? { record: true } : {}),
-            ...(video ? { videoDir: path.join(scratch, "video") } : {}),
+            ...(record ? { record: true, ...(frameCap !== undefined ? { maxFrames: frameCap } : {}) } : {}),
             ...(options.browser ? { browser: options.browser } : {}),
             actionTimeoutMs: options.actionTimeoutMs,
             navTimeoutMs: options.navTimeoutMs,
@@ -206,8 +206,7 @@ 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") } : {}),
+                ...(record ? { record: true, ...(frameCap !== undefined ? { maxFrames: frameCap } : {}) } : {}),
                 ...(options.browser ? { browser: options.browser } : {}),
                 actionTimeoutMs: options.actionTimeoutMs,
                 navTimeoutMs: options.navTimeoutMs,
@@ -229,9 +228,9 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
             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.
+                // 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.onOwnPage(walk, path.join(outDir, ...rel.split("/")));
+                const own = await runner.filming(path.join(outDir, ...rel.split("/")), walk);
                 walked = own.value;
                 flowVideos.push(own.video ? rel : null);
                 if (own.videoError)
@@ -275,6 +274,7 @@ export async function runCheck(options, log = () => { }, inputs = { flows: [], f
                     .map((flow, i) => ({ flow, outcome: flowRuns[i].outcome, frames: flowFrames[i], video: flowVideos[i] ?? null })),
                 scratch,
                 say: log,
+                ...(frameCap !== undefined ? { frameCap } : {}),
             })
             : null;
         if (replay)
@@ -465,12 +465,24 @@ async function takeBaselines(engine, options, mode, targets, log) {
  * 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
+ * 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) {
-    fs.rmSync(path.join(outDir, REPLAY_FILE), { force: true });
+    // 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 }))
@@ -500,6 +512,27 @@ export function clearReplayOutput(outDir) {
     if (fs.readdirSync(root).length === 0)
         fs.rmdirSync(root);
 }
+/**
+ * Why a recorded check (--record or --video) must not start, or null: a
+ * replay.html in the output folder that a check did not write is the
+ * project's own, and is neither removed nor overwritten. Asked before the
+ * browser starts, so the run is not spent first.
+ */
+export function replayPageConflict(outDir) {
+    const page = path.join(outDir, REPLAY_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(page, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    if (isGeneratedReplay(text))
+        return null;
+    return `${page} is not a page SceneScout wrote, so a recorded check will not overwrite it. Move or rename it, or pass --out to write the check somewhere else`;
+}
 /**
  * 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
@@ -510,25 +543,30 @@ 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;
+    /** 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 };
     };
-    // The crawl's frames, by the path each visit asked for, in the order they were taken.
+    // 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.frame || e.target === undefined || (e.session ?? own) !== own)
+        if (e.action !== "crawl" || e.target === undefined || (e.session ?? own) !== own)
             continue;
-        crawled.set(e.target, [...(crawled.get(e.target) ?? []), e.frame]);
+        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)) ?? undefined)),
+        visits: o.visited.map((route) => visitOf(route, beside(crawled.get(route.path)?.shift(), path.join(o.scratch, MEMORY_DIRNAME)))),
         journeys: [],
     };
     const roles = [ownSession];
@@ -544,7 +582,7 @@ function recordReplay(o) {
         }
         role.journeys.push(journey);
     }
-    const replay = redactReplay(capFrames({ startedAt: o.startedAt, roles, framesLeftOut: 0 }));
+    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;

package/dist/cli.js

@@ -21,7 +21,7 @@ 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, clearReplayOutput, defaultCheckDir, readCheckInputs, runCheck } from "./check-run.js";
+import { baselinesDirOf, clearReplayOutput, replayPageConflict, 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";
@@ -111,9 +111,8 @@ Usage:
                                      --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))
+                                     --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.
@@ -584,6 +583,10 @@ async function check(args) {
     try {
         // --record, else SCENESCOUT_RECORD, else off.
         options = { ...options, record: recordChoice(options.record, process.env) };
+        // A replay.html the project keeps there is its own: a recorded check refuses to start rather than overwrite it.
+        const conflict = options.record || options.video ? replayPageConflict(outDir) : null;
+        if (conflict)
+            throw new Error(conflict);
         // A replay page an earlier run left must never be read, or uploaded, as this run's.
         clearReplayOutput(outDir);
         inputs = readCheckInputs(options);

package/dist/engine/browser.js

@@ -16,6 +16,7 @@ import { extractCreatedIds, isOwnedResource, normalizeId } from "./ownership.js"
 import { formatJourney, journeyTime, measureJourney } from "./journey.js";
 import { describeStep, elementStateMatches, FLOW_AFTER_LAST_STEP_MS, isAction, matchRequest, notActionable, parseTarget, repeatFailure, splitRefusals, TARGET_HELP, urlMatches, } from "./flow.js";
 import { framePath, RECORD_MAX_FRAMES } from "./replay.js";
+import { film } from "./film.js";
 import { InFlightRequests, keepWatchingUrl, normalizePace, SETTLE_TICK_MS, shouldKeepWaiting } from "./settle.js";
 import { crawledRoute, crawlLine, isFileMediaType, isNonPageResource, mainStateFlag, mediaTypeOf } from "./crawl.js";
 import { authToRemember, BODY_FETCH_MAX, buildRequestScript, formatPageRequests, formatReplay, PageRequests, replaySignature, requestHeaders, resolveMethod, resolveRequestUrl, resolveTarget, staleCredentialNote, toReplayResult, wantsView, } from "./request.js";
@@ -460,6 +461,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 +595,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 +611,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 +638,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 +1112,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;
@@ -1184,7 +1193,6 @@ 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)
@@ -1510,9 +1518,6 @@ 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(() => {
@@ -1675,65 +1680,21 @@ 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).
+     * 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 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) };
-        }
+    async filming(videoTo, work) {
+        const page = this.requirePage();
+        // The page the filming began on is the one stopped, even if the work moved the session to a popup.
+        return film(page.screencast, videoTo, page.viewportSize(), work, {
+            prepare: (file) => fs.promises.mkdir(path.dirname(file), { recursive: true }).then(() => undefined),
+            written: (file) => fs.promises.stat(file).then((st) => st.size > 0, () => false),
+        });
     }
     requirePage() {
         if (!this.page || !this.memory) {
@@ -4469,7 +4430,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 }
@@ -5342,8 +5304,11 @@ export class BrowserEngine {
                 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 (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)
@@ -5402,7 +5367,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));
@@ -5424,7 +5389,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

@@ -17,22 +17,34 @@ 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, null where none was kept.
+ * 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 frame = broke === null || n <= broke ? (frames[i] ?? undefined) : undefined;
-        const base = { n, caption: describeStep(step), ...(frame ? { frame } : {}) };
+        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)
@@ -53,26 +65,30 @@ export function journeyOf(flow, outcome, frames) {
     };
 }
 /** One visited route, from what the crawl measured. */
-export function visitOf(route, frame) {
+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 } : {}),
-        ...(frame ? { frame } : {}),
+        ...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.
+ * 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 = RECORD_MAX_FRAMES) {
-    let leftOut = replay.framesLeftOut;
+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) {
@@ -81,7 +97,7 @@ export function capFrames(replay, max = RECORD_MAX_FRAMES) {
             }
             leftOut += 1;
             const { frame: _dropped, ...rest } = item;
-            return rest;
+            return { ...rest, pastCap: true };
         };
         return {
             ...role,
@@ -89,7 +105,7 @@ export function capFrames(replay, max = RECORD_MAX_FRAMES) {
             journeys: role.journeys.map((j) => ({ ...j, steps: j.steps.map(take) })),
         };
     });
-    return { ...replay, roles, framesLeftOut: leftOut };
+    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) {
@@ -167,24 +183,31 @@ const VISIT_WORD = {
 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>`);
+/**
+ * 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) {
+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.frame, `The page after step ${s.n}: ${s.caption}`)) +
+        (s.result === "not-run" ? "" : frameHtml(s, `The page after step ${s.n}: ${s.caption}`, cap)) +
         `</li>`);
 }
-function journeyHtml(j, id) {
+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>`;
@@ -196,25 +219,27 @@ function journeyHtml(j, id) {
             ? `<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>`);
+        `<ol class="steps">${j.steps.map((s) => stepHtml(s, anchor, cap)).join("")}</ol></details>`);
 }
-function visitsHtml(visits) {
+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.frame, `The page at ${v.path}`) +
+        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) {
+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) +
-        (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>`) +
+        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 = `
@@ -248,17 +273,17 @@ ol.steps { list-style:none; margin:10px 0 0; padding:0; }
 .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; }
+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 external assets or scripts; its frames sit beside it in replay-frames/. */
+/** 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>`;
@@ -269,6 +294,7 @@ export function buildCheckReplayHtml(replay, meta) {
 <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>
@@ -278,8 +304,10 @@ export function buildCheckReplayHtml(replay, meta) {
   <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>'}
+<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/film.js

@@ -0,0 +1,41 @@
+/**
+ * Filming one piece of work into a video file (`scenescout check --video`):
+ * start, run the work, stop, and say whether a video was saved. The browser
+ * hands in its page's screencast; nothing here needs Playwright, so the
+ * failure paths are table-tested.
+ */
+const why = (err) => (err instanceof Error ? err.message.split("\n")[0] : String(err));
+/**
+ * Run `work` while `screencast` films it into `videoTo`. The work's own result
+ * and errors are never touched by the filming: a video that cannot be started
+ * or saved is reported in `videoError`, and the work runs regardless.
+ *
+ * A start that fails is followed by a stop, its error ignored: a screencast
+ * left half-started would refuse every later start ("already started"), so
+ * one failure would cost the video of every flow after it.
+ */
+export async function film(screencast, videoTo, size, work, io) {
+    let videoError;
+    let filming = false;
+    try {
+        await io.prepare(videoTo);
+        await screencast.start({ path: videoTo, ...(size ? { size } : {}) });
+        filming = true;
+    }
+    catch (err) {
+        videoError = `the video could not be started: ${why(err)}`;
+        // Whatever the failed start left running is stopped, so the next flow can start afresh; there is nothing to save.
+        await screencast.stop().catch(() => undefined);
+    }
+    let value;
+    try {
+        value = await work();
+    }
+    finally {
+        if (filming)
+            await screencast.stop().catch((err) => (videoError = `the video could not be saved: ${why(err)}`));
+    }
+    if (videoError)
+        return { value, video: null, videoError };
+    return (await io.written(videoTo)) ? { value, video: videoTo } : { value, video: null, videoError: "no video was written" };
+}

package/package.json

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