@parity/product-lab 0.1.0 → 0.1.2

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;

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/ai-kit/skills/product-lab-integration/references/notes-lab.md

@@ -9,7 +9,7 @@ A tiny notes SPA tested end to end: the local dev chain (Omni Node) with People
 1. Install the dev dependencies the files import before the first MCP call (pin these versions; `@cucumber/cucumber` must be the same version product-lab uses, so step files and the testing kit share one Cucumber). A tool call that fails with a module resolution error right after an install succeeds when repeated: the server reloads the lab.
 
    ```sh
-   npm install --save-dev @cucumber/cucumber@12.9.0 playwright@1.63.0 @noble/hashes@1.8.0 @polkadot-labs/hdkd@0.0.32 @polkadot-labs/hdkd-helpers@0.0.34 @polkadot-api/metadata-builders@0.14.3 @polkadot-api/substrate-bindings@0.20.3 @polkadot-api/ws-provider@0.9.1 @parity/product-sdk-host@0.29.0 polkadot-api@2.2.2 vite@7.3.6
+   npm install --save-dev @cucumber/cucumber@12.9.0 playwright@1.63.0 @noble/hashes@1.8.0 @polkadot-labs/hdkd@0.0.32 @polkadot-labs/hdkd-helpers@0.0.34 @polkadot-api/metadata-builders@0.14.3 @polkadot-api/substrate-bindings@0.20.3 @polkadot-api/ws-provider@0.9.1 @parity/product-sdk-host@0.29.0 polkadot-api@2.2.2 vite@7.3.7
    ```
 
    Only for `launch: "deployed-local"` (lab/deployed-local.ts deploys to Bulletin): also `npm install --save-dev bulletin-deploy@0.21.0`. It is an optional peer dependency of `@parity/product-lab` under GPL-3.0-or-later (product-lab itself is Apache-2.0), so it is not installed with product-lab; without it a deployed-local run fails with an error naming this command.

package/entrypoints/cli/ai-kit/skills/product-lab-setup/SKILL.md

@@ -98,6 +98,7 @@ In CI, cache the shared cache keyed on `lab.lock.json`, run `npx --no-install pr
 | `PRODUCT_LAB_RECORDINGS`, `PRODUCT_LAB_RECORDINGS_DIR`, `…_KEEP`, `…_MAX_AGE_DAYS`, `…_MAX_MB` | Run recordings and their retention |
 | `PRODUCT_LAB_STEP_TIMEOUT_MINUTES`, `PRODUCT_LAB_STARTUP_TIMEOUT_MINUTES`, `PRODUCT_LAB_CLEANUP_TIMEOUT_MINUTES` | Feature-run timeouts (10, 30, 5) |
 | `PRODUCT_LAB_BASE` | Git base a mode's `onlyAffected` compares with (`test --mode <name>`; default `main`) |
+| `PRODUCT_LAB_FORK_BUNDLE` | `keep` or `fresh` (default): what a start of a local copy of a network does about a newer published fork bundle. `fresh` downloads it in the background; `keep` only reads the release record and says how old the kept bundle is. `lab --refresh` works under both |
 
 Your lab's own variables (a port base, an app directory) are yours to name. Codex passes only listed variables to the MCP server: list them under `env_vars` in `.codex/config.toml` (`ai init` writes product-lab's).
 

package/entrypoints/cli/ai-kit/skills/product-lab-setup/references/minimal-lab.md

@@ -9,7 +9,7 @@ One page, one button, one signed remark on People, checked on the finalized chai
 1. Install the dev dependencies the files import (pin these versions):
 
    ```sh
-   npm install --save-dev @parity/product-lab playwright@1.63.0 @noble/hashes@1.8.0 polkadot-api@3.2.1 @parity/product-sdk-host@0.29.0 vite@7.3.6
+   npm install --save-dev @parity/product-lab playwright@1.63.0 @noble/hashes@1.8.0 polkadot-api@3.2.1 @parity/product-sdk-host@0.29.0 vite@7.3.7
    ```
 
 2. Copy `lab.config.ts`, `lab/` and `lab.lock.json` into your repository. Run `npx --no-install product-lab fetch` (it caches the runtime and node binary the lock pins) and `npx --no-install product-lab doctor` (what this machine still lacks, and what fits it). `lab.config.ts` below already runs your people on the released truAPI WASM test host, which `@parity/product-lab` installs (`defaultHost: "truapi-wasm"`, and its modes' hosts): changed from the truAPI CLI host the minimal lab was written for. That host's locked official release takes the lab's local endpoints (https://github.com/paritytech/host-rust-core/pull/1166), so it runs a product's local environment too; `npx --no-install product-lab doctor` says which release is locked and what it provides. No environment variable is required.