@parity/product-lab 0.1.1 → 0.1.2

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;

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

@@ -9,6 +9,7 @@ export declare const RECORDING_VARIABLES: {
     readonly maxAgeDays: "PRODUCT_LAB_RECORDINGS_MAX_AGE_DAYS";
     readonly maxMb: "PRODUCT_LAB_RECORDINGS_MAX_MB";
     readonly video: "PRODUCT_LAB_RECORDINGS_VIDEO";
+    readonly settleTimeoutMs: "PRODUCT_LAB_RECORDINGS_SETTLE_MS";
     readonly hostLogs: "PRODUCT_LAB_RECORDINGS_HOST_LOGS";
     readonly hostLogKb: "PRODUCT_LAB_RECORDINGS_HOST_LOG_KB";
 };
@@ -25,13 +26,15 @@ export declare class RecordingSettings {
     static readonly DEFAULT: RecordingSettings;
     readonly mode: RecordingMode;
     readonly retention: RecordingRetention;
-    /** A capture that takes longer is recorded as failed (it never holds the run). */
+    /** A capture that takes longer is recorded as failed; only video feature boundaries wait for it. */
     readonly captureTimeoutMs: number;
     /**
      * Backlog 18b: headless identities' pages are recorded as video into the recordings directory's `videos/` folder,
      * and each recording refers to the videos of the pages its steps acted in. Default off (`product-lab test --video`).
      */
     readonly video: boolean;
+    /** Video feature after-frames compare screenshots for at most this long (default 3000 ms). */
+    readonly settleTimeoutMs: number;
     /**
      * Backlog 192: each host's own log is kept with a failed run's recording (`failed`), with every run's (`always`), or
      * never (`off`); at most `hostLogBytes` of each, its tail.
@@ -43,6 +46,7 @@ export declare class RecordingSettings {
         retention: RecordingRetention;
         captureTimeoutMs: number;
         video?: boolean;
+        settleTimeoutMs?: number;
         hostLogs?: HostLogsMode;
         hostLogBytes?: number;
     });

package/core/domain/src/recordings/recording-settings.js

@@ -9,6 +9,7 @@ export const RECORDING_VARIABLES = {
     maxAgeDays: "PRODUCT_LAB_RECORDINGS_MAX_AGE_DAYS",
     maxMb: "PRODUCT_LAB_RECORDINGS_MAX_MB",
     video: "PRODUCT_LAB_RECORDINGS_VIDEO",
+    settleTimeoutMs: "PRODUCT_LAB_RECORDINGS_SETTLE_MS",
     hostLogs: "PRODUCT_LAB_RECORDINGS_HOST_LOGS",
     hostLogKb: "PRODUCT_LAB_RECORDINGS_HOST_LOG_KB",
 };
@@ -21,6 +22,7 @@ export class RecordingSettings {
     retention;
     captureTimeoutMs;
     video;
+    settleTimeoutMs;
     hostLogs;
     hostLogBytes;
     constructor(settings) {
@@ -31,6 +33,10 @@ export class RecordingSettings {
         this.mode = settings.mode;
         this.retention = settings.retention;
         this.captureTimeoutMs = settings.captureTimeoutMs;
+        const settleTimeoutMs = settings.settleTimeoutMs ?? 3000;
+        if (!Number.isFinite(settleTimeoutMs) || settleTimeoutMs <= 0)
+            throw new RecordingFormatError("A frame stability wait needs a positive timeout");
+        this.settleTimeoutMs = Math.min(settleTimeoutMs, this.captureTimeoutMs - Math.min(1000, this.captureTimeoutMs / 2));
         this.video = settings.mode !== "off" && (settings.video ?? false);
         const hostLogs = settings.hostLogs ?? "failed";
         if (!["failed", "always", "off"].includes(hostLogs))
@@ -74,6 +80,7 @@ export class RecordingSettings {
             }),
             captureTimeoutMs: RecordingSettings.DEFAULT.captureTimeoutMs,
             video: video === "on",
+            settleTimeoutMs: number(RECORDING_VARIABLES.settleTimeoutMs, RecordingSettings.DEFAULT.settleTimeoutMs, 1, false),
             hostLogs,
             hostLogBytes: number(RECORDING_VARIABLES.hostLogKb, HOST_LOG_BYTES, 1024, true),
         });

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

@@ -51,6 +51,8 @@ export declare class RunRecording {
         before: FrameChoice;
         after: FrameChoice;
     };
+    /** A cap frame remains available, with its uncertainty visible wherever the viewer chooses it. */
+    private labelStability;
     private framesOf;
     private before;
     private after;

package/core/domain/src/recordings/run-recording.js

@@ -179,6 +179,8 @@ export class RunRecording {
                 throw new RecordingFormatError(`Recording frame ${id} has an unknown status`);
             if (frame.step !== undefined && (typeof frame.step !== "number" || !Number.isInteger(frame.step) || frame.step < 0 || frame.step >= steps.length))
                 throw new RecordingFormatError(`Recording frame ${id} names step ${String(frame.step)}, which the recording does not have`);
+            if (frame.featureStep !== undefined && (typeof frame.featureStep !== "number" || !Number.isSafeInteger(frame.featureStep) || frame.featureStep < 1))
+                throw new RecordingFormatError("Recording frame featureStep must be a positive step number");
             time(`frames[${index}].requestedAt`, frame.requestedAt);
             if (!Array.isArray(frame.overlapping))
                 throw new RecordingFormatError(`Recording frame ${id} must list the steps it overlapped`);
@@ -239,7 +241,12 @@ export class RunRecording {
         const who = actor ?? step.actor;
         if (!who)
             return { before: RunRecording.missing("This step acted as no identity: pick one to see its app"), after: RunRecording.missing("This step acted as no identity: pick one to see its app") };
-        return { actor: who, before: this.before(step, who), after: this.after(step, who) };
+        return { actor: who, before: this.labelStability(this.before(step, who)), after: this.labelStability(this.after(step, who)) };
+    }
+    labelStability(choice) {
+        if (choice.status !== "captured" || choice.frame?.settled !== false)
+            return choice;
+        return { ...choice, note: `Taken at the stability cap; visual stability was not confirmed. ${choice.note.replace(/^Settled(?=:|,)/, "Capture")}` };
     }
     framesOf(actor) {
         return this.data.frames.filter((frame) => frame.actor === actor);

package/core/ports/README.md

@@ -456,3 +456,9 @@ JSON, only when `extrinsics(blockHash, { includeCallArguments: true })` requests
 neither copy nor retain arguments. Consumers can check transaction contents beside the exact finalized hash; absent
 is unknown, and `null` is a decoded call with no arguments. JSON conversion cuts nesting beyond 12 levels to `"…"`;
 `decoded: "complete"` describes SCALE decoding, not JSON depth coverage. The chain adapter owns decoding.
+
+## Held feature demos
+
+FeatureScenarioHandle optionally exposes startStep and finishStep for custom definitions: observation only, without scheduling their work. VideoEditRequest.stills supplies one complete recorded image per segment. DemoRequest.holdSeconds defaults to 2 and cannot be below 2. A full demo exports step-001.png and later images decoded from each encoded hold midpoint, with a caption band below the app.
+
+`CaptureOptions.loadComplete` optionally requests a read of the current document until loading completes, within `timeoutMs`; `CapturedFrame.loadComplete` reports when the source verified it. The recorder requests this only during video feature after-frame stability checks. Sources without this support leave the result absent.

package/core/ports/src/driven/recording/demo-ports.d.ts

@@ -18,6 +18,8 @@ export interface VideoEditRequest {
     readonly source: string;
     readonly plan: DemoPlan;
     readonly overlays: readonly VideoOverlay[];
+    /** Already composed recorded stills, one per plan segment; replaces the video inputs when supplied. */
+    readonly stills?: readonly Uint8Array[];
     /** Where the cut is written (its parent exists); replaced whole. */
     readonly out: string;
     readonly format: "mp4" | "webm";

package/core/ports/src/driven/recording/frame-capture.d.ts

@@ -7,6 +7,8 @@ export interface CapturedFrame {
     bytes: Uint8Array;
     /** How long the capture waited for the app's screen to settle (`CaptureOptions.settled`), when it was asked to. */
     settledMs?: number;
+    /** Whether the source verified the current document completed loading before this image. */
+    loadComplete?: boolean;
 }
 /** Why no image of that identity's app can be taken (no page, a surface that cannot be captured, …). */
 export interface UnavailableFrame {
@@ -35,6 +37,8 @@ export interface CaptureOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
     mask?: readonly string[];
+    /** Read the current document until readyState is complete before imaging it, bounded by timeoutMs. */
+    loadComplete?: boolean;
     settled?: {
         readonly selectors: readonly string[];
         readonly timeoutMs: number;

package/core/ports/src/driving/demo.d.ts

@@ -8,6 +8,8 @@ export interface DemoRequest {
     out?: string;
     /** The longest the cut should be (default 60). */
     maxSeconds?: number;
+    /** Each after-step image is held this long (default 2, minimum 2 seconds). */
+    holdSeconds?: number;
     format?: "mp4" | "webm";
     /** Only the cut's plan: demo.json and demo.vtt, no video, no slide (needs no ffmpeg). */
     planOnly?: boolean;

package/core/ports/src/driving/feature-session.d.ts

@@ -230,6 +230,13 @@ export interface FeatureScenarioHandle {
     readonly name: string;
     /** Run step `index` once (a custom step is run by its own definition, not here). */
     run(index: number): Promise<FeatureStepTrace>;
+    /** Observe a direct/custom definition, without running it through the scheduler. Generated steps time themselves. */
+    startStep?(index: number): void;
+    /** Observe its after-state; only video runs await capture before the next step or pause. Skipped steps have no boundary. */
+    finishStep?(index: number, outcome: {
+        status: "passed" | "failed";
+        error?: string;
+    }): Promise<void>;
     /** The identity a scenario actor is bound to. */
     actor(name: string): ActorSession;
     /** The scenario's outputs so far. */

package/entrypoints/cli/README.md

@@ -795,9 +795,8 @@ blank. It loads no lab. `pr-suite.yml` posts it. Test: `tests/pr-comment.test.ts
 
 ## Recorded runs
 
-`product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--format mp4|webm] [--plan | --slide-only] [--failed] [--json]`
-(backlog 36) cuts a recorded feature scenario into a demo through `LabRuntime.demo`: about a
-minute, each action at real speed with its result held, waits sped up and labelled, a caption per Gherkin step in the
+`product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--hold-seconds 2] [--format mp4|webm] [--plan | --slide-only] [--failed] [--json]`
+(backlog 36) cuts a recorded feature scenario into a demo through `LabRuntime.demo`: one recorded after-state per step held for at least two seconds, a caption band below the app in the
 lab window's style, with `demo.vtt`, `demo.json` and a slide (`slide.png`, `slide.html`) in
 `<lab>/.product-lab/demos/<recording-id>`. The video needs `ffmpeg` and `ffprobe` on `PATH` (or `PRODUCT_LAB_FFMPEG`
 naming their folder; never bundled); `--plan` and `--slide-only` do not. Starts nothing. Exit 2 when refused (no such
@@ -893,3 +892,7 @@ failure; this detail does not change retries or cancellation. Test:
 `tests/abort-diagnostics.test.ts`.
 
 The generated minimal reference uses the released SDK's native PAPI 3 transaction creator and carries its app's current SDK and client install pins. Its file list and dependency test follow that source; no local signer bridge is copied. The rebased migration is awaiting qualification.
+
+## Held feature demos
+
+Demo holds default to 2 s per feature step; --hold-seconds tunes them upward and --max-seconds never shortens them. Captions occupy a separate band below the app. Full renders also write step-001.png and later files decoded from the midpoint of each hold. Direct/custom feature steps are recorded with their start/end times and after-state images. Default frames-only capture is asynchronous; --video awaits bounded after-step captures and retains a 2 s tail before scenario cleanup. Old footage without a matching after-state is refused rather than replaced with an unrelated screen.

package/entrypoints/cli/src/demo-command.d.ts

@@ -1,4 +1,4 @@
 import type { DemoReport, LabRuntime } from "@parity/product-lab/ports/driving";
-export declare const DEMO_USAGE = "Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60]\n                        [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]\n\nA demo of a recorded feature scenario: its video cut to about a minute, every action at real speed with its result\nheld, waits sped up and labelled (\u00D78 waiting for finality), a caption per Gherkin step, plus demo.vtt (the captions),\ndemo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,\nthe last screen). Record a run with video first (product-lab test --video, or the lab window's recording).\n  <recording-id>    default: the newest passed feature recording\n  --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)\n  --window          cut the lab window's video\n  --out <dir>       default: <lab>/.product-lab/demos/<recording-id>\n  --max-seconds <n> the longest the cut should be (default 60); over it the waits speed up first\n  --format mp4|webm default mp4 (H.264); webm is VP9\n  --plan            only demo.json and demo.vtt (needs no ffmpeg)\n  --slide-only      the plan and the slide, no video (needs no ffmpeg)\n  --failed          allow a failed run: every frame and the slide say it failed\n  --json            print the report as JSON\n  The video needs ffmpeg and ffprobe on PATH (or PRODUCT_LAB_FFMPEG naming their folder); product-lab never bundles them.\n  Exit code: 0 made, 2 refused (no such recording, no video, a failed run without --failed, no ffmpeg) or bad arguments,\n  1 when the lab does not load or the cut fails.";
+export declare const DEMO_USAGE = "Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--hold-seconds 2]\n                        [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]\n\nA demo of a recorded feature scenario: its real after-step images held for at least 2 seconds each,\nwith captions in a band under the app and step-001.png (one encoded midpoint PNG per step), plus demo.vtt (the captions),\ndemo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,\nthe last screen). Record a run with video first (product-lab test --video, or the lab window's recording).\n  <recording-id>    default: the newest passed feature recording\n  --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)\n  --window          cut the lab window's video\n  --out <dir>       default: <lab>/.product-lab/demos/<recording-id>\n  --max-seconds <n> the target length (default 60); never shortens the step holds\n  --hold-seconds <n> hold each after-step image (default 2, minimum 2 seconds)\n  --format mp4|webm default mp4 (H.264); webm is VP9\n  --plan            only demo.json and demo.vtt (needs no ffmpeg)\n  --slide-only      the plan and the slide, no video (needs no ffmpeg)\n  --failed          allow a failed run: every frame and the slide say it failed\n  --json            print the report as JSON\n  The video needs ffmpeg and ffprobe on PATH (or PRODUCT_LAB_FFMPEG naming their folder); product-lab never bundles them.\n  Exit code: 0 made, 2 refused (no such recording, no video, a failed run without --failed, no ffmpeg) or bad arguments,\n  1 when the lab does not load or the cut fails.";
 export declare function renderDemo(report: DemoReport): string;
 export declare function runDemoCommand(runtime: LabRuntime, argv: string[], signal?: AbortSignal, out?: (text: string) => void, err?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/demo-command.js

@@ -2,18 +2,19 @@
 // SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from "node:util";
 import { DemoRefusedError } from "@parity/product-lab/domain/recordings";
-export const DEMO_USAGE = `Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60]
+export const DEMO_USAGE = `Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--hold-seconds 2]
                         [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]
 
-A demo of a recorded feature scenario: its video cut to about a minute, every action at real speed with its result
-held, waits sped up and labelled (×8 waiting for finality), a caption per Gherkin step, plus demo.vtt (the captions),
+A demo of a recorded feature scenario: its real after-step images held for at least 2 seconds each,
+with captions in a band under the app and step-001.png (one encoded midpoint PNG per step), plus demo.vtt (the captions),
 demo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,
 the last screen). Record a run with video first (product-lab test --video, or the lab window's recording).
   <recording-id>    default: the newest passed feature recording
   --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)
   --window          cut the lab window's video
   --out <dir>       default: <lab>/.product-lab/demos/<recording-id>
-  --max-seconds <n> the longest the cut should be (default 60); over it the waits speed up first
+  --max-seconds <n> the target length (default 60); never shortens the step holds
+  --hold-seconds <n> hold each after-step image (default 2, minimum 2 seconds)
   --format mp4|webm default mp4 (H.264); webm is VP9
   --plan            only demo.json and demo.vtt (needs no ffmpeg)
   --slide-only      the plan and the slide, no video (needs no ffmpeg)
@@ -48,6 +49,7 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
                 window: { type: "boolean" },
                 out: { type: "string" },
                 "max-seconds": { type: "string" },
+                "hold-seconds": { type: "string" },
                 format: { type: "string" },
                 plan: { type: "boolean" },
                 "slide-only": { type: "boolean" },
@@ -66,12 +68,14 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
         return 0;
     }
     const maxSeconds = values["max-seconds"] === undefined ? undefined : Number(values["max-seconds"]);
+    const holdSeconds = values["hold-seconds"] === undefined ? undefined : Number(values["hold-seconds"]);
     const problem = positionals.length > 1 ? `Unexpected arguments: ${positionals.slice(1).join(" ")}`
         : values.actor !== undefined && values.window ? "--actor and --window cannot be used together"
             : values.plan && values["slide-only"] ? "--plan and --slide-only cannot be used together"
                 : values.format !== undefined && values.format !== "mp4" && values.format !== "webm" ? `--format must be mp4 or webm, not ${values.format}`
                     : maxSeconds !== undefined && !(Number.isFinite(maxSeconds) && maxSeconds >= 5) ? `--max-seconds must be a number of seconds, at least 5, not ${values["max-seconds"]}`
-                        : undefined;
+                        : holdSeconds !== undefined && !(Number.isFinite(holdSeconds) && holdSeconds >= 2) ? `--hold-seconds must be a number of seconds, at least 2, not ${values["hold-seconds"]}`
+                            : undefined;
     if (problem) {
         err(`${problem}\n${DEMO_USAGE}\n`);
         return 2;
@@ -84,6 +88,7 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
             ...(values.window ? { window: true } : {}),
             ...(values.out !== undefined ? { out: values.out } : {}),
             ...(maxSeconds !== undefined ? { maxSeconds } : {}),
+            ...(holdSeconds !== undefined ? { holdSeconds } : {}),
             ...(values.format ? { format: values.format } : {}),
             ...(values.plan ? { planOnly: true } : {}),
             ...(values["slide-only"] ? { slideOnly: true } : {}),