@parity/product-lab 0.1.1 → 0.2.0

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;

package/core/application/src/recordings/record-runs.js

@@ -5,11 +5,13 @@ import { RecordingHealth, RunRecording, StepConsoleErrors } from "@parity/produc
 import { NO_HOST_LOGS, readHostLogs } from "./host-logs.js";
 import { SETTLE_TIMEOUT_MS, StepChainReader } from "./step-chain-reader.js";
 import { HealthSampler } from "./health-sampler.js";
+import { captureStableFrame } from "./frame-sources.js";
 import { RecordingDraft } from "./recording-draft.js";
 import { Deadline } from "./deadline.js";
 const FEATURE_JOB = /^feature:(.*)#(\d+)$/;
 const NO_SOURCE = "No frame source: the environment offers no capture (LabEnvironment.frames) and no lab window registered one";
 const WRITTEN_KEPT = 500;
+const FEATURE_TAIL_MS = 2000;
 export class RecordRuns {
     options;
     open = new Map();
@@ -103,6 +105,47 @@ export class RecordRuns {
                 this.finalize(draft.key, "the load ended");
         await this.flush();
     }
+    stepStarted(scenario, at) {
+        if (this.options.stores.settings.mode === "off")
+            return;
+        const active = this.options.state.active;
+        if (active && !active.closed)
+            this.featureDraft(active, scenario, at);
+    }
+    async stepFinished(scenario, featureStep, identities) {
+        const draft = [...this.open.values()].find((item) => item.kind === "feature" && item.title === scenario);
+        if (!draft || draft.active.closed)
+            return;
+        draft.rememberIdentities(identities);
+        const last = draft.runs.filter((entry) => entry.featureStep === featureStep).at(-1);
+        const index = last && last.run.record.steps.length ? draft.index(last.run, last.run.record.steps.length - 1) : undefined;
+        const captures = Promise.all(identities.map((actor) => {
+            this.noteVideo(draft, actor);
+            return this.capture(draft, actor, "after", index, featureStep, this.options.stores.settings.video);
+        }));
+        if (this.options.stores.settings.video)
+            await captures;
+        else {
+            void captures;
+        }
+    }
+    async scenarioEnded(scenario) {
+        const draft = [...this.open.values()].find((item) => item.kind === "feature" && item.title === scenario);
+        if (!draft)
+            return;
+        if (!draft.active.closed && (this.options.stores.settings.video || draft.videos.size)) {
+            await this.options.clock.sleep(FEATURE_TAIL_MS);
+            draft.tailFinishedAt = this.now();
+            const last = this.options.state.scenarioSteps.get(scenario)?.at(-1);
+            if (last)
+                await this.stepFinished(scenario, last.featureStep, draft.everyIdentity());
+        }
+        if (!draft.featureRun) {
+            await this.settleCaptures();
+            this.finalize(draft.key, "the feature scenario ended");
+            await draft.hostLogs;
+        }
+    }
     now() {
         return this.options.clock.date().getTime();
     }
@@ -207,7 +250,7 @@ export class RecordRuns {
             if (actor)
                 draft.hostRequests?.stepStarted(index, actor);
             this.readUiCalls(draft);
-            this.capture(draft, actor, "before", index);
+            void this.capture(draft, actor, "before", index);
             this.noteVideo(draft, actor);
         }
         else if (event.status === "complete" || event.status === "failed") {
@@ -215,11 +258,11 @@ export class RecordRuns {
             if (!draft.running.size)
                 draft.health?.idle();
             this.observe(draft, index, "end");
-            this.capture(draft, actor, "after", index);
+            void this.capture(draft, actor, "after", index);
             if (event.status === "failed")
                 for (const other of draft.everyIdentity())
                     if (other !== actor)
-                        this.capture(draft, other, "after", index);
+                        void this.capture(draft, other, "after", index);
             this.readChainChanges(draft, index, actor);
             draft.hostRequests?.stepEnded(index);
             this.readUiCalls(draft, index);
@@ -237,13 +280,13 @@ export class RecordRuns {
         const done = draft.runs.flatMap((entry) => entry.run.record.steps.flatMap((step, position) => (step.status === "complete" || step.status === "failed" ? [draft.index(entry.run, position)] : []))).filter((item) => item !== undefined);
         const after = done.length ? Math.max(...done) : undefined;
         for (const actor of new Set([...draft.runs.flatMap((entry) => RecordingDraft.identities(entry.run)), ...identities]))
-            this.capture(draft, actor, "checkpoint", after);
+            void this.capture(draft, actor, "checkpoint", after);
     }
     checkpoint(draft, run) {
         const done = run.record.steps.flatMap((step, position) => (step.status === "complete" ? [draft.index(run, position)] : [])).filter((item) => item !== undefined);
         const after = done.length ? Math.max(...done) : undefined;
         for (const actor of RecordingDraft.identities(run))
-            this.capture(draft, actor, "checkpoint", after);
+            void this.capture(draft, actor, "checkpoint", after);
     }
     readUiCalls(draft, index) {
         const source = this.options.sources.current(draft.active.closed ? undefined : draft.active.environment);
@@ -295,13 +338,14 @@ export class RecordRuns {
         }));
         draft.observations.push({ step, at, recordedAt: this.now(), chains });
     }
-    capture(draft, actor, phase, step) {
+    capture(draft, actor, phase, step, featureStep, stable = false) {
         if (this.options.stores.settings.mode !== "frames" || !actor)
-            return;
+            return Promise.resolve();
         const source = this.options.sources.current(draft.active.closed ? undefined : draft.active.environment);
         const frame = {
             id: `f${draft.frames.length + 1}`,
             ...(step !== undefined ? { step } : {}),
+            ...(featureStep !== undefined ? { featureStep } : {}),
             actor,
             phase,
             status: "unavailable",
@@ -313,19 +357,24 @@ export class RecordRuns {
         };
         draft.frames.push(frame);
         if (!source)
-            return;
+            return Promise.resolve();
         Object.assign(frame, { status: "failed", reason: "The capture had not finished when the recording closed" });
         const limit = this.options.stores.settings.captureTimeoutMs;
         const deadline = new Deadline(limit, (ms, signal) => this.options.clock.sleep(ms, signal));
         const work = deadline
-            .race(Promise.resolve().then(() => source.capture(actor, { signal: deadline.signal, timeoutMs: limit })), "late")
+            .race(Promise.resolve().then(() => {
+            const options = { signal: deadline.signal, timeoutMs: limit };
+            return stable ? captureStableFrame(source, actor, this.options.clock, this.options.stores.settings.settleTimeoutMs, options) : source.capture(actor, options);
+        }), "late")
             .then((result) => {
+            if (stable)
+                Object.assign(frame, { settled: result !== "late" && "settled" in result ? result.settled : false, waitedMs: result !== "late" && "waitedMs" in result ? result.waitedMs : Math.min(limit, this.options.stores.settings.settleTimeoutMs) });
             const done = { capturedAt: this.now(), overlapping: [...draft.running].sort((a, b) => a - b) };
             if (result === "late")
                 Object.assign(frame, { reason: `The capture took longer than ${limit} ms` });
             else if (result.status === "captured") {
                 delete frame.reason;
-                Object.assign(frame, { ...done, status: "captured", file: `${frame.id}.png`, mediaType: result.mediaType, bytes: result.bytes.length });
+                Object.assign(frame, { ...done, status: "captured", file: `${frame.id}.png`, mediaType: result.mediaType, bytes: result.bytes.length, ...(result.loadComplete !== undefined ? { loadComplete: result.loadComplete } : {}) });
                 draft.images.set(frame.id, result.bytes);
             }
             else
@@ -336,6 +385,7 @@ export class RecordRuns {
             .finally(() => deadline.stop());
         draft.pending.add(work);
         void work.finally(() => draft.pending.delete(work));
+        return work;
     }
     noteVideo(draft, actor) {
         if (!actor)
@@ -410,7 +460,12 @@ export class RecordRuns {
         if (featureSteps?.length) {
             this.options.state.scenarioSteps.delete(draft.title);
             const readings = this.options.state.featureStepReadings.get(draft.title);
-            Object.assign(data, { featureSteps: featureSteps.map((step) => ({ ...step, ...(readings?.get(step.featureStep - 1)?.length ? { readings: [...readings.get(step.featureStep - 1)] } : {}) })), startedAt: Math.min(data.startedAt, ...featureSteps.map((step) => step.startedAt)) });
+            Object.assign(data, {
+                featureSteps: featureSteps.map((step) => ({ ...step, ...(readings?.get(step.featureStep - 1)?.length ? { readings: [...readings.get(step.featureStep - 1)] } : {}) })),
+                startedAt: Math.min(data.startedAt, ...featureSteps.map((step) => step.startedAt)),
+                finishedAt: Math.max(data.finishedAt, ...featureSteps.map((step) => step.finishedAt ?? step.startedAt)),
+                ...(!draft.featureStatus && featureSteps.some((step) => step.status === "failed") ? { status: "failed" } : {}),
+            });
         }
         const kept = (await draft.hostLogs) ?? NO_HOST_LOGS;
         const files = new Map([...kept.files].map(([file, bytes]) => [file, new TextEncoder().encode(this.options.redactor.text(new TextDecoder().decode(bytes)))]));

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

@@ -33,6 +33,9 @@ export declare class RecordingDraft {
     readonly observations: ChainObservation[];
     /** Captures still in progress. */
     readonly pending: Set<Promise<void>>;
+    /** Direct steps may create identities without any runtime run. */
+    readonly featureIdentities: Set<string>;
+    tailFinishedAt?: number;
     /** The lab's checks after this recording's failed runs: only its write waits for them, never a scenario's end. */
     readonly checks: Set<Promise<void>>;
     /** The session's people as each run began: a runner that closes them before the write still names them (backlog 110). */
@@ -91,6 +94,7 @@ export declare class RecordingDraft {
     static identities(run: ScenarioRun): string[];
     /** Every identity of the runs recorded so far (backlog 110: a failed step takes each one's frame). */
     everyIdentity(): string[];
+    rememberIdentities(identities: readonly string[]): void;
     /** Each identity's name as the recording gives it (seen while recording, or the environment's now), by id. */
     names(): Map<string, string>;
     /** Whether a recorded run's step failed. */

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

@@ -20,6 +20,8 @@ export class RecordingDraft {
     images = new Map();
     observations = [];
     pending = new Set();
+    featureIdentities = new Set();
+    tailFinishedAt;
     checks = new Set();
     seen = new Map();
     videos = new Map();
@@ -105,7 +107,14 @@ export class RecordingDraft {
         return [...new Set([...record.steps.flatMap((step) => (step.actor ? [step.actor] : [])), ...(record.bindings ?? []).map((binding) => binding.identity), record.actorId].filter(Boolean))];
     }
     everyIdentity() {
-        return [...new Set(this.runs.flatMap((entry) => RecordingDraft.identities(entry.run)))];
+        return [...new Set([...this.featureIdentities, ...this.runs.flatMap((entry) => RecordingDraft.identities(entry.run))])];
+    }
+    rememberIdentities(identities) {
+        for (const id of identities)
+            this.featureIdentities.add(id);
+        if (!this.active.closed)
+            for (const actor of this.active.environment.actors())
+                this.seen.set(actor.id, { name: actor.name, ...(actor.account ? { account: actor.account } : {}) });
     }
     names() {
         const now = this.active.closed ? [] : this.active.environment.actors();
@@ -136,7 +145,7 @@ export class RecordingDraft {
         const hostBypass = observed ? mergeHostBypassEvidence(this.runs.map((entry) => entry.run.record.hostBypass ? this.recordingEvidence(entry.run.record.hostBypass, entry.base ?? 0) : { scope: "unknown", apps: [], ledger: [], gaps: [`No host-bypass evidence recorded for run ${entry.run.id}`] })) : undefined;
         const known = new Map([...this.seen, ...this.active.environment.actors().map((actor) => [actor.id, actor])]);
         const roles = new Map(records.flatMap((record) => (record.bindings ?? []).map((binding) => [binding.identity, binding.actor])));
-        const ids = [...new Set(this.runs.flatMap((entry) => RecordingDraft.identities(entry.run)))];
+        const ids = this.everyIdentity();
         const actors = ids.map((id) => {
             const actor = known.get(id);
             const role = roles.get(id);
@@ -169,7 +178,7 @@ export class RecordingDraft {
         if (unavailable || failed)
             notes.push(`${unavailable} frame${unavailable === 1 ? "" : "s"} unavailable and ${failed} failed: each says why.`);
         if (captured.some((frame) => frame.overlapping.length))
-            notes.push("Captures never wait for the run: a frame taken while a step ran names that step.");
+            notes.push("Asynchronous captures name any overlapping step; video feature after-state captures finish before the next feature step starts.");
         if (media.has("synthetic"))
             notes.push("Some frames come from a browser with a synthetic camera and microphone.");
         if (this.videos.size)
@@ -190,7 +199,7 @@ export class RecordingDraft {
             ...(hostBypass ? { hostBypass } : {}),
             ...(error !== undefined ? { error } : this.runnerFailure ? { error: this.runnerFailure.error } : {}),
             startedAt: this.startedAt,
-            finishedAt: Math.max(this.startedAt, ...finished),
+            finishedAt: Math.max(this.startedAt, this.tailFinishedAt ?? 0, ...finished),
             recordedAt: options.now,
             runs: records.map((record) => record.id),
             ...(this.featureRun !== undefined ? { featureRun: this.featureRun } : {}),

package/core/domain/README.md

@@ -195,3 +195,17 @@ is the page's build). `AppDevServer.parse` accepts `"next-turbopack"`, `"webpack
 arguments name (`configArgument`) or the CLI would find (`DEFAULT_CONFIG_FILES`), the arguments that add the dev
 servers' own proxy setting (`proxySocketArgs`), the content of the lab's files (`webpackSocketOverlay`,
 `rspackSocketWrapper`) and the notice when the lab cannot tell (`proxySocketNotice`). Tests: `tests/dev-server-socket.test.ts`.
+
+## Held feature demos
+
+planDemoHolds makes one frozen segment per step, with a default and minimum 2 s hold rounded upward to whole 25 fps frames. maxSeconds is advisory when the holds exceed it. demoSteps includes direct featureSteps even when no tool run exists. RecordedFrame.featureStep optionally names that direct Gherkin step; the format remains additive at schema version 1. planDemo remains available for existing moving-video callers and the negative control.
+
+`RecordingSettings.settleTimeoutMs` optionally caps video feature after-frame stability (default 3000 ms; `PRODUCT_LAB_RECORDINGS_SETTLE_MS`). `RecordedFrame` adds optional `settled`, `waitedMs` and `loadComplete` fields. Older recordings remain readable; no field is renamed.
+
+
+The effective stability cap reserves time for the final screenshot: it is clamped to `captureTimeoutMs` minus
+1000 ms, or minus half that timeout when it is shorter than 2000 ms. With the default 5000 ms capture timeout,
+`PRODUCT_LAB_RECORDINGS_SETTLE_MS` accepts positive values but uses at most 4000 ms; the default stays 3000 ms.
+A captured frame with `settled: false` is labelled "Taken at the stability cap" in recording-view notes and in
+the demo image manifest and captions, including reused setup and failure context. Older frames without this
+metadata retain their existing labels.

package/core/domain/src/recordings/demo-cut.js

@@ -15,11 +15,13 @@ export const DEMO_DEFAULTS = {
 export function demoSteps(data, video, scenario) {
     const roleOf = (actor) => (actor ? (data.steps.find((step) => step.actor === actor && step.role)?.role ?? data.actors.find((item) => item.id === actor)?.name ?? actor) : undefined);
     const at = (wall) => wall - video.openedAt;
-    const numbers = scenario ? scenario.steps.map((_, index) => index + 1) : [...new Set(data.steps.map((step) => step.featureStep ?? step.index + 1))];
+    const numbers = scenario ? scenario.steps.map((_, index) => index + 1) : [...new Set([...data.steps.map((step) => step.featureStep ?? step.index + 1), ...(data.featureSteps ?? []).map((step) => step.featureStep)])].sort((a, b) => a - b);
     return numbers.map((number) => {
         const recorded = data.steps.filter((step) => (step.featureStep ?? step.index + 1) === number);
         const timed = recorded.filter((step) => step.startedAt !== undefined);
         const gherkin = scenario?.steps[number - 1];
+        const feature = data.featureSteps?.find((step) => step.featureStep === number);
+        const runnerFailure = data.runnerFailure?.featureStep === number ? data.runnerFailure : undefined;
         const actorId = recorded.find((step) => step.actor)?.actor;
         const failed = recorded.find((step) => step.status === "failed");
         const waits = data.transactions
@@ -30,10 +32,10 @@ export function demoSteps(data, video, scenario) {
         return {
             number,
             keyword: gherkin?.keyword.trim() ?? "",
-            text: gherkin?.text ?? recorded[0]?.title.replace(/ \[[^\]]+\]$/, "") ?? `step ${number}`,
+            text: gherkin?.text ?? feature?.text ?? recorded[0]?.title.replace(/ \[[^\]]+\]$/, "") ?? `step ${number}`,
             ...(roleOf(actorId) ? { actor: roleOf(actorId) } : {}),
-            ...(timed.length ? { span: { start: at(Math.min(...timed.map((step) => step.startedAt))), end: at(end) } } : {}),
-            ...(failed ? { status: "failed", ...(failed.error ? { error: failed.error.split("\n")[0] } : {}) } : recorded.length ? { status: "complete" } : {}),
+            ...(feature?.finishedAt !== undefined ? { span: { start: at(feature.startedAt), end: at(feature.finishedAt) } } : timed.length ? { span: { start: at(Math.min(...timed.map((step) => step.startedAt))), end: at(end) } } : {}),
+            ...((failed || runnerFailure || feature?.status === "failed") ? { status: "failed", ...((failed?.error ?? runnerFailure?.error) ? { error: (failed?.error ?? runnerFailure.error).split("\n")[0] } : {}) } : recorded.length || feature?.status === "passed" ? { status: "complete" } : {}),
             chainWaits: waits,
             ...(video.actor && actorId && actorId !== video.actor ? { offVideo: true } : {}),
         };

package/core/domain/src/recordings/demo-holds.d.ts

@@ -0,0 +1,12 @@
+import type { DemoPlan, DemoStep } from "./demo-cut.js";
+/** A step with evidence selected by the caller. A still has no video timestamp. */
+export interface DemoHold {
+    step: DemoStep;
+    atMs?: number;
+    note?: string;
+}
+/** One frozen after-step image per step, in order. The requested maximum never shortens a hold. */
+export declare function planDemoHolds(holds: readonly DemoHold[], sourceMs: number, options?: {
+    holdSeconds?: number;
+    maxSeconds?: number;
+}): DemoPlan;

package/core/domain/src/recordings/demo-holds.js

@@ -0,0 +1,31 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function planDemoHolds(holds, sourceMs, options = {}) {
+    const holdSeconds = options.holdSeconds ?? 2;
+    const maxSeconds = options.maxSeconds ?? 60;
+    if (!Number.isFinite(holdSeconds) || holdSeconds < 2)
+        throw new Error("A demo's hold must be at least 2 seconds");
+    if (!Number.isFinite(maxSeconds) || maxSeconds <= 0)
+        throw new Error("A demo's length must be above 0 seconds");
+    if (!holds.length)
+        throw new Error("The recording holds no step to show");
+    const holdMs = Math.ceil(holdSeconds * 25) * 40;
+    const captions = holds.map(({ step, note }, index) => ({
+        number: step.number, keyword: step.keyword, text: step.text,
+        ...(step.actor ? { actor: step.actor } : {}),
+        ...(step.status ? { status: step.status } : {}),
+        ...((note || step.status === "failed" || step.offVideo) ? { note: [
+                step.status === "failed" ? `failed${step.error ? `: ${step.error}` : ""}` : undefined,
+                step.offVideo ? `${step.actor ?? "another identity"} acts, not in this video` : undefined,
+                note,
+            ].filter(Boolean).join(" · ") } : {}),
+        outputStart: index * holdMs, outputEnd: (index + 1) * holdMs,
+    }));
+    const outputMs = holds.length * holdMs;
+    const fits = outputMs <= maxSeconds * 1000;
+    return {
+        segments: holds.map(({ atMs = 0 }, index) => ({ kind: "result", sourceStart: atMs, sourceEnd: atMs, speed: 1, holdMs, outputStart: index * holdMs, outputEnd: (index + 1) * holdMs })),
+        captions, outputMs, sourceMs, fits,
+        notes: ["Each step shows a frozen recorded app image; waits are omitted.", ...(!fits ? [`The demo is ${outputMs / 1000} s, above the ${maxSeconds} s asked for: ${holds.length} steps each need at least ${holdSeconds} s.`] : [])],
+    };
+}

package/core/domain/src/recordings/index.d.ts

@@ -14,3 +14,4 @@ export * from "./journey-markdown.js";
 export * from "./journeys-declaration.js";
 export * from "./demo-cut.js";
 export * from "./demo-refused-error.js";
+export * from "./demo-holds.js";

package/core/domain/src/recordings/index.js

@@ -16,3 +16,4 @@ export * from "./journey-markdown.js";
 export * from "./journeys-declaration.js";
 export * from "./demo-cut.js";
 export * from "./demo-refused-error.js";
+export * from "./demo-holds.js";

package/core/domain/src/recordings/recording-data.d.ts

@@ -66,10 +66,18 @@ export interface RecordedStep {
     }[];
 }
 export interface RecordedFrame {
+    /** Video feature after-frame stability result; absent for asynchronous captures and older recordings. */
+    settled?: boolean;
+    /** Time spent checking load completion and visual stability, bounded by the configured cap. */
+    waitedMs?: number;
+    /** Present when the source checked the current document before imaging it. */
+    loadComplete?: boolean;
     /** Unique in the recording: `[a-z0-9-]`, also the image's file name without extension. */
     id: string;
-    /** The recorded step it belongs to; absent for a checkpoint frame taken before any step. */
+    /** Atomic recorded step; absent for a direct feature step with no tool run, or an initial checkpoint. */
     step?: number;
+    /** Direct Gherkin step (1-based), including steps with no runtime run. */
+    featureStep?: number;
     /** The identity whose app it shows. */
     actor: string;
     phase: FramePhase;