@parity/product-lab 0.1.1 → 0.1.2

package/core/application/src/features/feature-step-times.js

@@ -1,11 +1,8 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
-export async function timedFeatureStep(state, name, index, text, now, redact, work) {
-    const kept = { featureStep: index + 1, text, status: "running", startedAt: now() };
-    let steps = state.scenarioSteps.get(name);
-    if (!steps)
-        state.scenarioSteps.set(name, (steps = []));
-    steps.push(kept);
+export async function timedFeatureStep(state, name, index, text, now, redact, work, observe) {
+    const kept = startFeatureStep(state, name, index, text, now());
+    observe?.recording?.stepStarted(name, kept.startedAt);
     try {
         const result = await work();
         Object.assign(kept, { status: "passed", finishedAt: now() });
@@ -15,6 +12,23 @@ export async function timedFeatureStep(state, name, index, text, now, redact, wo
         Object.assign(kept, { status: "failed", finishedAt: now(), error: redact(error instanceof Error ? error.message : String(error)) });
         throw error;
     }
+    finally {
+        await observe?.recording?.stepFinished(name, index + 1, observe.identities());
+    }
+}
+export function startFeatureStep(state, name, index, text, at) {
+    const kept = { featureStep: index + 1, text, status: "running", startedAt: at };
+    let steps = state.scenarioSteps.get(name);
+    if (!steps)
+        state.scenarioSteps.set(name, (steps = []));
+    steps.push(kept);
+    return kept;
+}
+export async function readyFeatureSurfaces(surface, names, bindings, signal) {
+    if (!surface)
+        return;
+    const ids = [...new Set(names.map((name) => bindings.get(name)).filter((id) => id !== undefined))];
+    await Promise.all(ids.map((id) => surface(id)?.ready?.({ signal })));
 }
 export async function readIdentities(at, ids) {
     const read = at.environment.actorReadings;

package/core/application/src/features/lab-feature-session.d.ts

@@ -10,6 +10,7 @@ import type { PrepareScenarioFixture } from "../fixtures/prepare-scenario-fixtur
 import type { IsolateScenario } from "../fixtures/isolate-scenario.js";
 import type { KeepRunStart } from "../fixtures/keep-run-start.js";
 import type { StepChecks } from "./step-checks.js";
+import type { FeatureRecording } from "./feature-recording.js";
 export declare class LabFeatureSession implements FeatureSession {
     private readonly state;
     private readonly runScenario;
@@ -28,6 +29,7 @@ export declare class LabFeatureSession implements FeatureSession {
     private readonly clock?;
     /** Keeps the state a scenario without a fixture starts on, when the lab's setting asks (5 October 2026). */
     private readonly runStart?;
+    private readonly recording?;
     /** The latest scenario begun under each name (what a pause gate names). */
     private readonly begun;
     constructor(state: LabState, runScenario: RunScenario, manageActors: ManageActors, redactor: Redactor, ids: IdGenerator, options: FeatureSessionOptions, conditions?: ReadScenarioConditions | undefined, 
@@ -40,7 +42,7 @@ export declare class LabFeatureSession implements FeatureSession {
     /** Times of new actors created ahead of their steps (scenario-actor-creation.ts). */
     clock?: Clock | undefined, 
     /** Keeps the state a scenario without a fixture starts on, when the lab's setting asks (5 October 2026). */
-    runStart?: KeepRunStart | undefined);
+    runStart?: KeepRunStart | undefined, recording?: FeatureRecording | undefined);
     /** The scenario's tags that do not fit the running environment (read once per environment session; unknown: none). */
     notFor(tags: readonly string[]): Promise<readonly UnmetCondition[]>;
     sentences(): SentenceView[];

package/core/application/src/features/lab-feature-session.js

@@ -28,13 +28,14 @@ export class LabFeatureSession {
     stepChecks;
     clock;
     runStart;
+    recording;
     begun = new Map();
     constructor(state, runScenario, manageActors, redactor, ids, options, conditions, 
     fixtures, 
     isolation, 
     stepChecks, 
     clock, 
-    runStart) {
+    runStart, recording) {
         this.state = state;
         this.runScenario = runScenario;
         this.manageActors = manageActors;
@@ -47,6 +48,7 @@ export class LabFeatureSession {
         this.stepChecks = stepChecks;
         this.clock = clock;
         this.runStart = runStart;
+        this.recording = recording;
     }
     async notFor(tags) {
         return this.conditions ? this.conditions.unmet(tags) : [];
@@ -83,7 +85,7 @@ export class LabFeatureSession {
             tags: request.tags ?? [],
             ...(request.fixtureGroup !== undefined ? { group: request.fixtureGroup } : {}),
             ...(this.options.fixtures ? { policy: this.options.fixtures } : {}),
-            setupSession: (fixtureSetup) => new LabFeatureSession(this.state, this.runScenario, this.manageActors, this.redactor, this.ids, { binding: "manual", fixtureSetup, ...(this.options.surface ? { surface: this.options.surface } : {}), ...(this.options.surfaceConditions ? { surfaceConditions: this.options.surfaceConditions } : {}) }, this.conditions, this.fixtures, this.isolation, this.stepChecks, this.clock),
+            setupSession: (fixtureSetup) => new LabFeatureSession(this.state, this.runScenario, this.manageActors, this.redactor, this.ids, { binding: "manual", fixtureSetup, ...(this.options.surface ? { surface: this.options.surface } : {}), ...(this.options.surfaceConditions ? { surfaceConditions: this.options.surfaceConditions } : {}) }, this.conditions, this.fixtures, this.isolation, this.stepChecks, this.clock, undefined, this.recording),
         });
         const start = fixture || isolatedScenario(request.tags ?? []) ? undefined : await this.runStart?.execute(this.ids.next());
         const kept = start && "kept" in start ? start.kept : undefined;
@@ -167,6 +169,7 @@ export class LabFeatureSession {
             ...(race ? { race: race.jitter } : {}),
             ...(request.outputs?.length ? { outputs: request.outputs } : {}),
             ...(this.clock ? { clock: this.clock } : {}),
+            ...(this.recording ? { recording: this.recording } : {}),
             ...(request.hosts && Object.keys(request.hosts).length ? { hosts: request.hosts } : {}),
         });
         this.begun.set(request.name, scenario);

package/core/application/src/features/run-feature-steps.d.ts

@@ -9,6 +9,7 @@ import type { PrepareScenarioFixture } from "../fixtures/prepare-scenario-fixtur
 import type { IsolateScenario } from "../fixtures/isolate-scenario.js";
 import type { KeepRunStart } from "../fixtures/keep-run-start.js";
 import type { StepChecks } from "./step-checks.js";
+import type { FeatureRecording } from "./feature-recording.js";
 export declare class RunFeatureSteps {
     private readonly state;
     private readonly runScenario;
@@ -26,6 +27,7 @@ export declare class RunFeatureSteps {
     private readonly clock?;
     /** "Keep each fork run's starting state" (5 October 2026). */
     private readonly runStart?;
+    private readonly recording?;
     constructor(state: LabState, runScenario: RunScenario, manageActors: ManageActors, redactor: Redactor, ids: IdGenerator, conditions?: ReadScenarioConditions | undefined, 
     /** Restores the fixture a scenario's tags name (`@fixture:<name>`) before it is planned (backlog 1b). */
     fixtures?: PrepareScenarioFixture | undefined, 
@@ -36,6 +38,6 @@ export declare class RunFeatureSteps {
     /** Times of new actors created ahead of their steps (scenario-actor-creation.ts). */
     clock?: Clock | undefined, 
     /** "Keep each fork run's starting state" (5 October 2026). */
-    runStart?: KeepRunStart | undefined);
+    runStart?: KeepRunStart | undefined, recording?: FeatureRecording | undefined);
     open(options?: FeatureSessionOptions): LabFeatureSession;
 }

package/core/application/src/features/run-feature-steps.js

@@ -13,12 +13,13 @@ export class RunFeatureSteps {
     stepChecks;
     clock;
     runStart;
+    recording;
     constructor(state, runScenario, manageActors, redactor, ids, conditions, 
     fixtures, 
     isolation, 
     stepChecks, 
     clock, 
-    runStart) {
+    runStart, recording) {
         this.state = state;
         this.runScenario = runScenario;
         this.manageActors = manageActors;
@@ -30,8 +31,9 @@ export class RunFeatureSteps {
         this.stepChecks = stepChecks;
         this.clock = clock;
         this.runStart = runStart;
+        this.recording = recording;
     }
     open(options = {}) {
-        return new LabFeatureSession(this.state, this.runScenario, this.manageActors, this.redactor, this.ids, options, this.conditions, this.fixtures, this.isolation, this.stepChecks, this.clock, this.runStart);
+        return new LabFeatureSession(this.state, this.runScenario, this.manageActors, this.redactor, this.ids, options, this.conditions, this.fixtures, this.isolation, this.stepChecks, this.clock, this.runStart, this.recording);
     }
 }

package/core/application/src/lab-runtime-use-cases.js

@@ -105,7 +105,11 @@ export function labRuntimeUseCases(ports) {
     const stepChecks = new StepChecks(state, frameSources, ports.stepChecks ?? {}, redactor);
     const manageLabSettings = new ManageLabSettings(ports.labSettings);
     const keepRunStart = new KeepRunStart(state, ports.fixtures, manageLabSettings, saveFixture, ports.clock);
-    const runFeatureSteps = new RunFeatureSteps(state, runScenario, manageActors, redactor, ports.ids, readScenarioConditions, prepareScenarioFixture, isolateScenario, stepChecks, ports.clock, keepRunStart);
+    const runFeatureSteps = new RunFeatureSteps(state, runScenario, manageActors, redactor, ports.ids, readScenarioConditions, prepareScenarioFixture, isolateScenario, stepChecks, ports.clock, keepRunStart, {
+        stepStarted: (scenario, at) => recordRuns.stepStarted(scenario, at),
+        stepFinished: (scenario, step, identities) => recordRuns.stepFinished(scenario, step, identities),
+        scenarioEnded: (scenario) => recordRuns.scenarioEnded(scenario),
+    });
     const manageBreakpoints = new ManageBreakpoints(listFeatures, ports.breakpoints);
     const lintLab = new LintLab(state, listFeatures, ports.featureRunner, redactor, ports.clientBundles);
     const runFeatures = new RunFeatures(state, ports.featureRunner, listFeatures, ports.clock, ports.ids, redactor, judgeNegativeControl, policy, runFeatureSteps, readScenarioConditions, events, manageBreakpoints, lintLab);

package/core/application/src/recordings/demo-markup.d.ts

@@ -37,6 +37,13 @@ export declare function waitLabelHtml(label: string): string;
 export declare function footerHtml(text: string): string;
 /** A failed run's banner, on every frame: the demo never reads as a pass. */
 export declare function failureBannerHtml(text: string): string;
+/** A complete held frame. The app keeps a 1280×720 area; all text lives in the separate band below it. */
+export declare function demoFrameHtml(image: string, caption: {
+    number: number;
+    keyword: string;
+    text: string;
+    note?: string;
+}, phase: GherkinPhase, footer: string, banner?: string): string;
 export interface DemoSlide {
     title: string;
     feature: string;
@@ -60,6 +67,7 @@ export interface DemoSlide {
     recordedAt: string;
     /** The last settled screen, as a data URL. */
     image?: string;
+    imageNote?: string;
     banner?: string;
 }
 /** The demo's slide (1600×900): the scenario, each step and its outcome, who and where, and the last screen. */

package/core/application/src/recordings/demo-markup.js

@@ -56,6 +56,16 @@ export function failureBannerHtml(text) {
     return page(`body{background:transparent;height:100vh}
 .banner{position:absolute;top:0;left:0;right:0;background:var(--danger);color:#fff;font-weight:640;font-size:18px;text-align:center;padding:10px 20px}`, `<div class="banner">${escapeHtml(text)}</div>`);
 }
+export function demoFrameHtml(image, caption, phase, footer, banner) {
+    return page(`body{width:1280px;height:960px;background:var(--canvas);display:grid;grid-template-rows:720px 240px}
+.app{width:1280px;height:720px;display:flex;align-items:center;justify-content:center;background:var(--canvas);overflow:hidden}
+.app img{width:100%;height:100%;object-fit:contain;display:block}
+.band{height:240px;border-top:1px solid var(--line);padding:12px 24px;display:flex;flex-direction:column;gap:7px;overflow:hidden;background:var(--surface)}
+.row{display:flex;gap:12px;align-items:baseline;font-size:23px;line-height:1.25}
+.n{font:600 16px var(--font-mono);color:var(--secondary)}.k{font-weight:700;color:var(--phase-${phase})}.t{font-weight:540}
+.note{font-size:17px;line-height:1.2;color:var(--secondary)}.failure{font-size:17px;line-height:1.2;color:var(--danger);font-weight:700}
+.footer{margin-top:auto;font-size:12px;line-height:1.2;color:var(--secondary)}.brand{color:var(--accent);font-weight:700}`, `<div class="app"><img src="${escapeHtml(image)}" alt="Recorded app state"></div><div class="band">${banner ? `<div class="failure">${escapeHtml(banner)}</div>` : ""}<div class="row"><span class="n">${caption.number}</span><span class="k">${escapeHtml(caption.keyword)}</span><span class="t">${escapeHtml(caption.text)}</span></div>${caption.note ? `<div class="note">${escapeHtml(caption.note)}</div>` : ""}<div class="footer"><span class="brand">product·lab</span> · ${escapeHtml(footer)} · recorded still</div></div>`);
+}
 const seconds = (value) => `${value < 10 ? value.toFixed(1) : value.toFixed(0)} s`;
 export function slideHtml(slide) {
     const phases = gherkinPhases(slide.steps.map((step) => step.keyword));
@@ -86,5 +96,5 @@ dl{display:grid;grid-template-columns:120px 1fr;gap:6px 14px;margin:28px 0 0;fon
 .shot img{max-width:100%;max-height:786px;display:block}
 .empty{color:var(--secondary);padding:40px;font-size:15px}
 .foot{font-size:12px;color:var(--secondary);margin-top:20px}
-.banner{grid-column:1/-1;background:var(--danger);color:#fff;border-radius:var(--radius-md);padding:10px 16px;font-weight:640;margin:-28px 0 0}`, `${slide.banner ? `<div class="banner">${escapeHtml(slide.banner)}</div>` : ""}<section><div class="brand">product·lab</div><h1>${escapeHtml(slide.title)}</h1><div class="feature">${escapeHtml(slide.feature)}</div><span class="status ${slide.status}">${slide.status === "passed" ? "Passed" : "Failed"}</span><ol>${rows}</ol><dl>${facts.map(([name, value]) => `<dt>${escapeHtml(name)}</dt><dd>${escapeHtml(value)}</dd>`).join("")}</dl><div class="foot">Recorded run ${escapeHtml(slide.recording)}, ${escapeHtml(slide.recordedAt)}. Screens are the apps as they painted themselves.</div></section><div class="shot">${slide.image ? `<img src="${slide.image}" alt="The last screen">` : `<div class="empty">No screenshot of the last screen was recorded.</div>`}</div>`);
+.banner{grid-column:1/-1;background:var(--danger);color:#fff;border-radius:var(--radius-md);padding:10px 16px;font-weight:640;margin:-28px 0 0}`, `${slide.banner ? `<div class="banner">${escapeHtml(slide.banner)}</div>` : ""}<section><div class="brand">product·lab</div><h1>${escapeHtml(slide.title)}</h1><div class="feature">${escapeHtml(slide.feature)}</div><span class="status ${slide.status}">${slide.status === "passed" ? "Passed" : "Failed"}</span><ol>${rows}</ol><dl>${facts.map(([name, value]) => `<dt>${escapeHtml(name)}</dt><dd>${escapeHtml(value)}</dd>`).join("")}</dl><div class="foot">Recorded run ${escapeHtml(slide.recording)}, ${escapeHtml(slide.recordedAt)}. Screens are the apps as they painted themselves.${slide.imageNote ? ` ${escapeHtml(slide.imageNote)}` : ""}</div></section><div class="shot">${slide.image ? `<img src="${slide.image}" alt="${slide.imageNote ? "Last available recorded frame" : "The last screen"}">` : `<div class="empty">No screenshot of the last screen was recorded.</div>`}</div>`);
 }

package/core/application/src/recordings/demo-recording.d.ts

@@ -26,7 +26,5 @@ export declare class DemoRecording {
     private video;
     /** The scenario's Gherkin, as the .feature file writes it. */
     private scenario;
-    /** The recording's last after-frame of the video's identity (or any), when stored. */
-    private lastFrame;
     private failure;
 }

package/core/application/src/recordings/demo-recording.js

@@ -1,9 +1,10 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
-import { DemoRefusedError, demoSteps, demoVtt, planDemo } from "@parity/product-lab/domain/recordings";
+import { DemoRefusedError, demoSteps, demoVtt, planDemoHolds } from "@parity/product-lab/domain/recordings";
 import { joinPath as join } from "../runs/bundles/bundle-paths.js";
-import { captionHtml, failureBannerHtml, footerHtml, gherkinPhases, slideHtml, waitLabelHtml } from "./demo-markup.js";
-const VIDEO = { width: 1280, height: 720 };
+import { demoFrameHtml, gherkinPhases, slideHtml } from "./demo-markup.js";
+import { demoFrameSources } from "./frame-sources.js";
+const VIDEO = { width: 1280, height: 960 };
 const SLIDE = { width: 1600, height: 900 };
 const utc = (at) => `${new Date(at).toISOString().slice(0, 16).replace("T", " ")} UTC`;
 const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -64,7 +65,11 @@ export class DemoRecording {
         const probe = this.ports.video ? await this.ports.video.probe() : { available: false, reason: "This runtime has no video editor" };
         const durationMs = probe.available ? await this.ports.video.durationMs(source) : Math.max(1, (video.closedAt ?? data.finishedAt) - video.openedAt);
         const steps = demoSteps(data, { openedAt: video.openedAt, ...(video.actor ? { actor: video.actor } : {}) }, scenario);
-        const plan = planDemo(steps, durationMs, { ...(request.maxSeconds !== undefined ? { maxSeconds: request.maxSeconds } : {}) });
+        const sources = demoFrameSources(recording, steps, video, durationMs);
+        const plan = planDemoHolds(steps.map((step, index) => ({ step, ...sources[index] })), durationMs, {
+            ...(request.maxSeconds !== undefined ? { maxSeconds: request.maxSeconds } : {}),
+            ...(request.holdSeconds !== undefined ? { holdSeconds: request.holdSeconds } : {}),
+        });
         const redacted = this.redactor.value(plan);
         notes.push(...redacted.notes);
         const banner = failed ? this.failure(data) : undefined;
@@ -86,6 +91,7 @@ export class DemoRecording {
             status: data.status,
             video: { file: video.file, source: video.source, ...(shown ? { actor: shown } : {}), openedAt: video.openedAt, ...(video.bytes !== undefined ? { bytes: video.bytes } : {}), durationMs },
             plan: redacted,
+            images: sources,
             ...(banner ? { banner } : {}),
         }, null, 2)}\n`);
         const report = (editor) => this.redactor.value({
@@ -103,8 +109,23 @@ export class DemoRecording {
             return report();
         if (!this.ports.slides)
             notes.push("No slide renderer: slide.html was written without its PNG");
-        const lastResult = [...redacted.segments].reverse().find((segment) => segment.kind === "result");
-        const image = probe.available && lastResult ? await this.ports.video.frame(source, Math.max(0, lastResult.sourceEnd - 100)) : await this.lastFrame(target.store, recording, video.actor);
+        const readImage = async (index) => {
+            const chosen = sources[index];
+            if (chosen.frame) {
+                const stored = await target.store.frame(data.id, chosen.frame);
+                if (stored)
+                    return stored.bytes;
+                throw new DemoRefusedError(`Step ${steps[index].number}'s after-frame ${chosen.frame} is missing`, "refused");
+            }
+            if (probe.available && chosen.atMs !== undefined)
+                return this.ports.video.frame(source, chosen.atMs);
+            throw new DemoRefusedError(`Step ${steps[index].number} needs ffmpeg to read its after-step video frame`, "missing-tools");
+        };
+        const fallback = !probe.available ? [...data.frames].reverse().find((frame) => frame.status === "captured" && !frame.overlapping.length && (!video.actor || frame.actor === video.actor)) : undefined;
+        const image = fallback ? (await target.store.frame(data.id, fallback.id))?.bytes : probe.available ? await readImage(steps.length - 1) : undefined;
+        const imageNote = fallback && fallback.id !== sources.at(-1)?.frame ? "Last available recorded frame; the final step's screen is unavailable without ffmpeg." : undefined;
+        if (imageNote)
+            notes.push(imageNote);
         const phases = gherkinPhases(redacted.captions.map((caption) => caption.keyword));
         const stepsSlide = steps.map((step) => ({
             number: step.number,
@@ -127,6 +148,7 @@ export class DemoRecording {
             recording: data.id,
             recordedAt: utc(data.recordedAt),
             ...(image ? { image: dataUrl(image) } : {}),
+            ...(imageNote ? { imageNote } : {}),
             ...(banner ? { banner } : {}),
         }));
         write("slide.html", html);
@@ -138,18 +160,17 @@ export class DemoRecording {
             throw new DemoRefusedError(`${probe.reason}; --plan and --slide-only work without it (the plan, demo.vtt and the slide are in ${out})`, "missing-tools");
         if (!this.ports.slides)
             throw new DemoRefusedError("This runtime has no slide renderer for the captions", "missing-tools");
-        const overlays = [];
-        const render = async (overlayHtml) => this.ports.slides.render(this.redactor.text(overlayHtml), VIDEO, { transparent: true });
         const footer = [data.title, data.environment.label, failed ? "failed" : "passed", ...(shown ? [`${shown}'s app`] : [])].join(" · ");
-        overlays.push({ png: await render(footerHtml(footer)), startMs: 0, endMs: redacted.outputMs });
-        if (banner)
-            overlays.push({ png: await render(failureBannerHtml(banner)), startMs: 0, endMs: redacted.outputMs });
-        for (const [index, caption] of redacted.captions.entries())
-            overlays.push({ png: await render(captionHtml(caption, phases[index])), startMs: caption.outputStart, endMs: caption.outputEnd });
-        for (const segment of redacted.segments.filter((item) => item.kind === "wait" && item.label))
-            overlays.push({ png: await render(waitLabelHtml(segment.label)), startMs: segment.outputStart, endMs: segment.outputEnd });
+        const stills = [];
+        for (const [index, caption] of redacted.captions.entries()) {
+            const html = this.redactor.text(demoFrameHtml(dataUrl(await readImage(index)), caption, phases[index], footer, banner));
+            const png = await this.ports.slides.render(html, VIDEO);
+            stills.push(png);
+        }
         const file = join(out, `demo.${request.format ?? "mp4"}`);
-        const result = await this.ports.video.render({ source, plan: redacted, overlays, out: file, format: request.format ?? "mp4", size: VIDEO, ...(request.signal ? { signal: request.signal } : {}) });
+        const result = await this.ports.video.render({ source, plan: redacted, overlays: [], stills, out: file, format: request.format ?? "mp4", size: VIDEO, ...(request.signal ? { signal: request.signal } : {}) });
+        for (const caption of redacted.captions)
+            write(`step-${String(caption.number).padStart(3, "0")}.png`, await this.ports.video.frame(result.file, (caption.outputStart + caption.outputEnd) / 2));
         written.push(result.file);
         notes.push(`The cut is ${(result.durationMs / 1000).toFixed(1)} s of a ${(redacted.sourceMs / 1000).toFixed(1)} s scenario (${(result.bytes / 1024).toFixed(0)} KB); captions and labels are burned in, demo.vtt has them as text.`);
         return report(probe.version);
@@ -199,15 +220,11 @@ export class DemoRecording {
         const found = features.find((feature) => feature.path === uri)?.scenarios.find((item) => item.name === name);
         return found ? { name: found.name, steps: [...(found.background ?? []), ...found.steps].map((step) => ({ keyword: step.keyword, text: step.text })) } : undefined;
     }
-    async lastFrame(store, recording, actor) {
-        const frames = recording.data.frames.filter((frame) => frame.status === "captured" && frame.phase === "after" && (!actor || frame.actor === actor));
-        const last = frames.at(-1);
-        return last ? (await store.frame(recording.data.id, last.id))?.bytes : undefined;
-    }
     failure(data) {
         const step = data.steps.find((item) => item.status === "failed");
-        const reason = (step?.error ?? data.runnerFailure?.error ?? data.error ?? "no reason recorded").split("\n")[0];
-        const at = step?.featureStep ?? data.runnerFailure?.featureStep;
+        const direct = data.featureSteps?.find((item) => item.status === "failed");
+        const reason = (step?.error ?? direct?.error ?? data.runnerFailure?.error ?? data.error ?? "no reason recorded").split("\n")[0];
+        const at = step?.featureStep ?? direct?.featureStep ?? data.runnerFailure?.featureStep;
         return this.redactor.text(`Failed${at ? ` at step ${at}` : ""}: ${reason}`);
     }
 }

package/core/application/src/recordings/frame-sources.d.ts

@@ -1,5 +1,7 @@
+import { type DemoStep, type RecordedVideo, type RunRecording } from "@parity/product-lab/domain/recordings";
 import type { LabEnvironment } from "@parity/product-lab/ports/lab";
-import type { FrameCapture } from "@parity/product-lab/ports/recording";
+import type { Clock } from "@parity/product-lab/ports/system";
+import type { CaptureOptions, CapturedFrame, UnavailableFrame, FrameCapture } from "@parity/product-lab/ports/recording";
 export declare class FrameSources {
     private live;
     /** Use `capture` until the returned function is called. */
@@ -7,3 +9,20 @@ export declare class FrameSources {
     /** The source a frame of `environment`'s identities is taken with, or undefined when nothing can take one. */
     current(environment: LabEnvironment | undefined): FrameCapture | undefined;
 }
+/** Evidence for one held demo image. Context is explicitly labelled when a step predates the app. */
+export interface DemoFrameSource {
+    frame?: string;
+    atMs?: number;
+    note?: string;
+}
+/** Prefer a step's last settled after-frame; never clamp a missing video span onto unrelated footage. */
+export declare function demoFrameSources(recording: RunRecording, steps: readonly DemoStep[], video: RecordedVideo, durationMs: number): DemoFrameSource[];
+/**
+ * Exact PNG equality across a 200 ms window (samples at least 100 ms apart). No pixel tolerance: even a small
+ * animation keeps waiting. Loading is checked by sources that support it on each sample. At the cap, take a
+ * fresh image without a load wait and label it unsettled. The caller still bounds all capture I/O separately.
+ */
+export declare function captureStableFrame(source: FrameCapture, actor: string, clock: Clock, timeoutMs: number, options: CaptureOptions): Promise<(CapturedFrame | UnavailableFrame) & {
+    settled: boolean;
+    waitedMs: number;
+}>;

package/core/application/src/recordings/frame-sources.js

@@ -1,5 +1,7 @@
 // Copyright 2026 Parity Technologies (UK) Ltd.
 // SPDX-License-Identifier: Apache-2.0
+import { DemoRefusedError } from "@parity/product-lab/domain/recordings";
+import { Deadline } from "./deadline.js";
 export class FrameSources {
     live = [];
     register(capture) {
@@ -12,3 +14,90 @@ export class FrameSources {
         return this.live.at(-1) ?? environment?.frames?.();
     }
 }
+export function demoFrameSources(recording, steps, video, durationMs) {
+    const data = recording.data;
+    const recorded = (number) => data.steps.filter((step) => (step.featureStep ?? step.index + 1) === number);
+    const ownFrame = (step) => {
+        const calls = recorded(step.number);
+        const actor = video.actor ?? [...calls].reverse().find((call) => call.actor)?.actor;
+        const direct = data.frames.filter((frame) => frame.featureStep === step.number && frame.phase === "after" && frame.status === "captured" && !frame.overlapping.length && (!actor || frame.actor === actor)).at(-1);
+        if (direct)
+            return direct;
+        if (data.frames.some((frame) => frame.featureStep === step.number && (!actor || frame.actor === actor)))
+            return undefined;
+        const last = calls.filter((call) => !actor || call.actor === actor).at(-1);
+        return last ? data.frames.filter((frame) => frame.step === last.index && frame.phase === "after" && frame.status === "captured" && !frame.overlapping.length && (!actor || frame.actor === actor)).at(-1) : undefined;
+    };
+    const directFrames = (step) => data.frames.filter((frame) => frame.featureStep === step.number && (!video.actor || frame.actor === video.actor));
+    const beforeApp = (step) => !recorded(step.number).length && !ownFrame(step) && (!step.span || step.span.end < 0) && !directFrames(step).some((frame) => frame.status === "failed");
+    const firstApp = steps.find((step) => ownFrame(step) || (!beforeApp(step) && step.span && step.span.end >= 0 && step.span.end < durationMs));
+    const choose = (step) => {
+        const frame = ownFrame(step);
+        if (frame)
+            return { frame: frame.id, ...(frame.settled === false ? { note: "Taken at the stability cap; visual stability was not confirmed" } : {}) };
+        if (directFrames(step).length)
+            throw new DemoRefusedError(`Step ${step.number}'s after-state was not captured: ${directFrames(step).map((frame) => frame.reason ?? "capture overlaps a running step").join("; ")}`, "refused");
+        const at = step.span?.end;
+        if (at !== undefined && at >= 0 && at < durationMs)
+            return { atMs: at };
+        throw new DemoRefusedError(`Step ${step.number} has no settled after-frame or matching video timestamp; cannot invent its app state`, "refused");
+    };
+    const context = (source, note) => ({ ...source, note: [source.note, note].filter(Boolean).join(". ") });
+    return steps.map((step) => {
+        if (firstApp && step.number < firstApp.number && beforeApp(step)) {
+            return context(choose(firstApp), "Setup before the app opened; showing the first recorded app state");
+        }
+        const failure = [...steps].reverse().find((other) => other.number < step.number && other.status === "failed");
+        if (failure && !step.span && !recorded(step.number).length && !directFrames(step).length)
+            return context(choose(failure), `No recorded execution; showing step ${failure.number}'s failure state`);
+        return choose(step);
+    });
+}
+export async function captureStableFrame(source, actor, clock, timeoutMs, options) {
+    const started = clock.date().getTime();
+    const deadline = new Deadline(timeoutMs, (ms, signal) => clock.sleep(ms, signal));
+    const stop = () => deadline.stop();
+    options.signal?.addEventListener("abort", stop, { once: true });
+    let previous;
+    let unchangedSince = started;
+    const check = async () => {
+        for (;;) {
+            deadline.signal.throwIfAborted();
+            options.signal?.throwIfAborted();
+            try {
+                const frame = await source.capture(actor, { ...options, signal: deadline.signal, loadComplete: true, timeoutMs: Math.max(1, Math.min(options.timeoutMs ?? timeoutMs, timeoutMs - (clock.date().getTime() - started))) });
+                const now = clock.date().getTime();
+                if (frame.status === "captured") {
+                    const same = previous?.length === frame.bytes.length && previous.every((byte, index) => byte === frame.bytes[index]);
+                    if (!same)
+                        unchangedSince = now;
+                    if (same && now - unchangedSince >= 200)
+                        return frame;
+                    previous = frame.bytes;
+                }
+                else {
+                    previous = undefined;
+                    unchangedSince = now;
+                }
+            }
+            catch {
+                previous = undefined;
+                unchangedSince = clock.date().getTime();
+            }
+            await clock.sleep(100, deadline.signal);
+        }
+    };
+    try {
+        const result = await deadline.race(check(), undefined);
+        const waitedMs = Math.min(timeoutMs, Math.max(0, clock.date().getTime() - started));
+        deadline.stop();
+        if (result)
+            return { ...result, settled: true, waitedMs };
+        options.signal?.throwIfAborted();
+        return { ...await source.capture(actor, { ...options, loadComplete: false }), settled: false, waitedMs };
+    }
+    finally {
+        deadline.stop();
+        options.signal?.removeEventListener("abort", stop);
+    }
+}

package/core/application/src/recordings/record-runs.d.ts

@@ -4,7 +4,7 @@ import type { FeatureRun } from "../features/feature-run.js";
 import type { LabState } from "../lab/lab-state.js";
 import type { RuntimeEvents } from "../lab/runtime-events.js";
 import type { CollectEvidence } from "../runs/collect-evidence.js";
-import type { FrameSources } from "./frame-sources.js";
+import { type FrameSources } from "./frame-sources.js";
 import type { RecordingStores } from "./recording-stores.js";
 export interface RecordRunsOptions {
     state: LabState;
@@ -72,6 +72,12 @@ export declare class RecordRuns {
     private remember;
     /** Write the open recording of feature scenario `title` now (a load reads it at once, backlog 43), then wait for writes. */
     closeScenario(title: string): Promise<void>;
+    /** Open on the first direct step, rather than only on the first tool run. */
+    stepStarted(scenario: string, at: number): void;
+    /** Only video runs await after-state captures; default frames-only runs keep capture asynchronous. */
+    stepFinished(scenario: string, featureStep: number, identities: readonly string[]): Promise<void>;
+    /** Called before feature services/identities close, including scenarios consisting only of direct steps. */
+    scenarioEnded(scenario: string): Promise<void>;
     private now;
     private onRuntimeEvent;
     private runStarted;