@parity/product-lab 0.1.1 → 0.2.0

package/core/application/README.md

@@ -179,7 +179,7 @@ environment as unable to start when its sessions' default host runs here on a li
 | `AdvanceEnvironmentTime` | `src/environment/advance-environment-time.ts`; the lab wrapper's check in `src/orchestration/lab/checked-environment-time.ts` | New (backlog 16, 30 September 2026): runs the generic time sentences (`the chain advances {int} blocks`, `time advances by {int} minutes`, kind `time`) through the running environment's `time` control, over every chain it lists, as setup work (a run the setup principal owns, credited to no participant); returns each chain's advance (`fromBlock`, `toBlock`, the clock at both, `checkedBy`) as the step's evidence. `unavailable` gives the environment's own reason (no control; a time sentence where it only builds blocks), which the feature session reports before the scenario runs; the plan also refuses a value outside `TimeAdvance`'s limits and an advance before the first actor. The lab wrapper reads each chain's finalized head and `Timestamp.Now` through its own connection before and after, and fails the step when either the environment's report or its own reading falls short (`tests/time-advance.test.ts`, with the negative control) |
 | `CheckFixtures`, `RefreshFixture`, `FixtureMaintenanceService` | `src/fixtures/check-fixtures.ts`, `refresh-fixture.ts`, `fixture-maintenance-service.ts` | New (keeping fixtures current, 30 September 2026, backlog 1i, same record): `LabRuntime.fixtureMaintenance()`. **Check** starts nothing: it compares each declared fixture's saved key with this checkout's setup, lock and inputs. **Plan**, with the fixture's environment running, splits the key's differences into checkout parts, state (environment, lineage) and runtimes. When the runtimes alone differ and `EnvironmentFixtures.upgradable()` allows it, the plan is `upgrade`; otherwise it is `rebuild`, naming why. **Upgrade** needs the `restoreFixture` confirmation. With the session closed it restores the saved state as it is, then calls `EnvironmentSnapshots.upgrade`. It then saves again through `SaveFixture` with an `upgraded` history entry, keeping the earlier history (`SaveFixture.execute({ history })`). **Rebuild** runs in two steps. `prepareRebuild` needs no environment running: it sets the saved session directories aside (`FixtureStore.setAside`). After the caller has run the setup, `saveRebuilt` records `rebuilt` with the reasons and what the fixture replaced. Tests: `tests/fixture-maintenance.test.ts` |
 | `RunSuite` | `src/suites/run-suite.ts` | New (Phase 7): `product-lab test --suite`. Plans the suite in the domain from the lab's `suites`, features, hosts, version policy and changes (`ChangeSource` for a base, or given paths); runs each runnable row as a feature run (`RunFeatures`: tags, environment, `PRODUCT_LAB_HOST`, candidates resolved once into a run manifest, the lock untouched), one after the other, stopping the row the budget runs out in (a stop that fails, on the budget or an interrupt, is named in the row's reason and fails a row that passed); judges with `judgeSuite`. Modes (`defineLab({ modes })`, `product-lab test --mode`, `SuiteRequest.mode`) plan and run here as suites of their own name: a row's device goes to its run as `PRODUCT_LAB_DEVICE` (checked against the browser's named devices), a row shared out among workers gets exactly its files, a mode's `workers` rows run in waves started together (`RunFeatures.executeTogether`, each with the lab's `workers.env` for its slot; refused without a declaration or above its `max`), and an old environment id names its environment through the lab's aliases (`tests/modes.test.ts`). A row plans exactly what its run runs: the feature runner's `selection` (its configuration loaded with the row's host) gives the files, unless the lab declares its own features (which the row's run then gets as its paths), and its tags and fail-fast always. After the run every planned scenario it did not report is named on the row (`unreported`, `unreportedScenarios`), with why when known (stopped by the budget or an interrupt; after the first failure under fail-fast); one without a reason fails a run that passed. A row that resolved a `host:<kind>` release from a version source asks its host adapter how to run it (`routeRelease`, backlog 27, `row-host-route.ts`): an unsupported route makes the row `unsupported` (never run, never passing, with the reason); otherwise the route goes to the run in `PRODUCT_LAB_HOST_ROUTE`, and the row records `hostRoute` (with the patch set), `timings.hostRouteMs` and how its host ran in the combination. Each record carries `counts` (`suite-metrics.ts`: scenarios planned, reported, executed, passed, failed, skipped, unsupported, not reported; checkpoints) and measured `timings` (version resolution, the run, each environment start the row's run recorded through `RunTimingsFile` in `PRODUCT_LAB_RUN_TIMINGS`, the reported step time, the row total; the suite's planning, critical path and total). Nothing is estimated: an absent value was not measured. `tests/suites.test.ts` |
-| `RecordRuns` | `src/recordings/record-runs.ts` | New (Phase 9): follows `run-started`, `run-finished` and the environment events, and each run's step and status events; one recording per configured scenario run and one per feature scenario (its `feature:<scenario>#<n>` runs grouped under the in-process feature run, else while they keep coming); since 3 October 2026 (backlog 20) a feature scenario's recording names where it was written (`feature`: uri, line, tags, fixture) from what its runner gave `FeatureSession.begin` (`LabState.scenarioSources`), so a Cucumber process's recordings carry it too, and an in-process run's report replaces it; how the runner saw the scenario end (`FeatureScenarioHandle.end(outcome)`, `LabState.scenarioOutcomes`) makes a scenario that failed outside the lab's runs (a custom step, a hook) a failed recording with `runnerFailure`, never a passed one. Asks for a frame of the acting identity as a step starts and ends and of every identity at a checkpoint (a scenario run's pause; since 30 September 2026 also an in-process feature run's `feature-paused`, where every identity the scenario used and every running identity is taken, so a stepping feature's next "before" frame is settled: `tests/recording-feature-pause.test.ts`), never waiting in the run (each frame records its timing and the steps that overlapped it; no source, a throw or a timeout is `unavailable` or `failed` with the reason); records the chain heads observed at each step start and end, transactions and evidence blocks; redacts everything with the runtime's `Redactor` and writes through the `RecordingStore` with retention (`recording-saved`, `recording-failed` events). Helpers `RecordingDraft`, `RecordingStores`, `FrameSources` (the lab window's registered source first, else `LabEnvironment.frames`). Since backlog 18b (headless half; 52) a step's start also asks the source for its identity's page video (`FrameCapture.video`), named once per file in `capture.videos` with when its page opened, with a note that videos are not redacted; a video that cannot be named is a note, never a guess. `tests/recordings.test.ts` |. Since backlog 20 (3 October 2026) a feature recording also names its scenario (`feature`: file, line, tags, fixture), from the feature run's report when the run completes Since backlog 110 (5 October 2026) it keeps what each step did on screen (`uiCalls`): the frame source's own UI calls (`FrameCapture.uiCalls`, the lab window's) read as a step starts (what came between steps is left out) and as it ends, with a cursor per source; a source that keeps none gives no block (`tests/recordings.test.ts`). Since backlog 110 a feature scenario's recording also keeps its Gherkin steps with their times (`featureSteps`, kept by `FeatureScenario` through `timedFeatureStep` in `src/features/feature-step-times.ts` in `LabState.scenarioSteps`), the identity steps that run no lab run included, and starts where its first step did (`tests/recording-feature-steps.test.ts`).
+| `RecordRuns` | `src/recordings/record-runs.ts` | New (Phase 9): follows `run-started`, `run-finished` and the environment events, and each run's step and status events; one recording per configured scenario run and one per feature scenario (its `feature:<scenario>#<n>` runs grouped under the in-process feature run, else while they keep coming); since 3 October 2026 (backlog 20) a feature scenario's recording names where it was written (`feature`: uri, line, tags, fixture) from what its runner gave `FeatureSession.begin` (`LabState.scenarioSources`), so a Cucumber process's recordings carry it too, and an in-process run's report replaces it; how the runner saw the scenario end (`FeatureScenarioHandle.end(outcome)`, `LabState.scenarioOutcomes`) makes a scenario that failed outside the lab's runs (a custom step, a hook) a failed recording with `runnerFailure`, never a passed one. Asks for a frame of the acting identity as a step starts and ends and of every identity at a checkpoint (a scenario run's pause; since 30 September 2026 also an in-process feature run's `feature-paused`, where every identity the scenario used and every running identity is taken, so a stepping feature's next "before" frame is settled: `tests/recording-feature-pause.test.ts`), without waiting in default frames-only runs; video feature boundaries await bounded after-state captures and keep a 2-second tail before cleanup (each frame records its timing and the steps that overlapped it; no source, a throw or a timeout is `unavailable` or `failed` with the reason); records the chain heads observed at each step start and end, transactions and evidence blocks; redacts everything with the runtime's `Redactor` and writes through the `RecordingStore` with retention (`recording-saved`, `recording-failed` events). Helpers `RecordingDraft`, `RecordingStores`, `FrameSources` (the lab window's registered source first, else `LabEnvironment.frames`). Since backlog 18b (headless half; 52) a step's start also asks the source for its identity's page video (`FrameCapture.video`), named once per file in `capture.videos` with when its page opened, with a note that videos are not redacted; a video that cannot be named is a note, never a guess. `tests/recordings.test.ts` |. Since backlog 20 (3 October 2026) a feature recording also names its scenario (`feature`: file, line, tags, fixture), from the feature run's report when the run completes Since backlog 110 (5 October 2026) it keeps what each step did on screen (`uiCalls`): the frame source's own UI calls (`FrameCapture.uiCalls`, the lab window's) read as a step starts (what came between steps is left out) and as it ends, with a cursor per source; a source that keeps none gives no block (`tests/recordings.test.ts`). Since backlog 110 a feature scenario's recording also keeps its Gherkin steps with their times (`featureSteps`, kept by `FeatureScenario` through `timedFeatureStep` in `src/features/feature-step-times.ts` in `LabState.scenarioSteps`), the identity steps that run no lab run included, and starts where its first step did (`tests/recording-feature-steps.test.ts`).
 | `BundleRecording`, `OpenRunBundle`, `ReproduceRun`, `controlSteps`, `RunBundlesService`, `RunBundleSources` | `src/runs/bundles/` | New (backlog 20, 3 October 2026): a recorded feature scenario written as one run bundle (the recording verbatim, the feature file, the lab lock, the run manifest, the fixture it started from as fixture export writes it, the lab's and each app's source revision through `ChangeSource.revision`); an identity whose key comes from a lab secret (`LabCatalog.preOnboardedActors`) is withheld and named, and a plain-text entry holding a lab secret's value refuses the bundle. `OpenRunBundle` reads the index first, extracts and checks every entry, shows each recording read-only (`recordingView`) and names every reason a reproduction here would be refused (`RunBundleReproduction`). `ReproduceRun` refuses with every reason first, then rebuilds the starting state (fixture imported; else the environment started, or the running one reset with its confirmation), reruns the scenario in process, judges the rerun's recording (`controlSteps`) against the bundled failure and writes a bundle holding every run; with `reruns` (backlog 26) it reruns from the same rebuilt state up to that many times, stopping at the first rerun that does not fail (verdict `flaky`, never passing). Ports: `RunBundlePorts` (`archives`, `recordingsAt`). Tests: `composition/tests/run-bundles.test.ts`, `tests/reproduce-run.test.ts` | Since backlog 110 `BundleRecording.reproducibility(id)` (`LabRunBundles.reproducibility`) says before anything is bundled or started whether a recording's run can be reproduced, from the facts a bundle records (feature file, public network, starting state, fixture, keys from lab secrets), in plain words with one way forward (`tests/reproducibility.test.ts`).
 | `BisectRegression`, `ProbeSession` | `src/bisect/bisect-regression.ts`, `src/bisect/probe-session.ts` | New (backlog 37, 4 October 2026): `product-lab bisect`. Reads two suite records, compares them as `report compare` does and takes one change; the domain's `bisectPlan` gives its axes or refuses it. An app axis is the lab's commits (`ChangeSource.commits`), a runtime or host axis the published releases between the two versions (`VersionSource.publishedVersions`). Each probe runs the one scenario as its row ran it (`RunSuite.probe`, every version pinned), twice by default, and the domain judges it; the ends first. With several axes each is first moved alone to its bad value. A probe of the lab's source runs from a worktree under the lab's cache with its dependencies installed frozen from its own lockfile (the package cache under the lab's cache; which lockfile and whether the cache was warm are recorded), and every worktree is removed in a `finally` block. Nothing starts below 15 GB of free disk (`BISECT_MIN_FREE_DISK`); each probe's disk use is recorded. Writes `product-lab-bisect.json` and `summary.md`; `reproduce` is one shell command that reruns the first bad value (for the lab's source, from the repository's top: `git worktree add`, the frozen install, the run from the lab's directory). A probe's worktree report is read through `readReport` (the feature runner's reader of its Cucumber JSON). Test: `tests/bisect-regression.test.ts` |
 | `ListRecordings`, `OpenRecording` | `src/recordings/` | New (Phase 9): the history and one recording with the domain's frame choice per step and identity, and a frame's image. Read the store only: no environment needed, nothing changes (`tests/recordings.test.ts` checks the runtime is unchanged, with a negative control) | Since backlog 25 `RecordingView.health` gives each step's health and findings (`RecordingHealth.DEFAULT`), so the lab window shows what `product-lab recordings` shows.
@@ -515,3 +515,32 @@ A step aborted by its limit, cancellation or interruption keeps the abort reason
 pass through the configured error describer. `StepReport.reason` and scheduling decisions
 still use the abort reason and original error text; reconciliation receives that original reason, and quarantine
 keeps it. See `tests/scheduler-abort-diagnostics.test.ts`.
+
+## Held feature demos
+
+FeatureScenario observes direct definitions through startStep/finishStep as well as generated runs. RecordRuns opens at the first feature step. Frames-only capture remains asynchronous; video runs await bounded captures at step boundaries and keep a 2 s tail before closing scenario services. Frames name their 1-based featureStep, including steps with no tool run. DemoRecording prefers these frames, uses planDemoHolds, renders a separate caption band, and decodes step-001.png and later midpoint images from the encoded cut. Slide-only output without ffmpeg uses the last available recorded frame with an explicit label when it predates the final step. Tests cover coverage, reload tail, direct failures and the former planner as a negative control.
+
+Scenario cleanup settles pending captures before finalizing its recording, then awaits its host-log read before
+closing identities and scenario services. Recording writes can still await background transaction checks; cleanup
+does not wait for those writes.
+
+
+Video feature after-frames first check that the current document has completed loading, then compare exact PNGs
+across a 200 ms window, sampling at least 100 ms apart. The stability wait is capped at 3000 ms by default
+(`RecordingSettings.settleTimeoutMs`, or `PRODUCT_LAB_RECORDINGS_SETTLE_MS`). At the cap, the recorder takes a
+fresh frame anyway and adds `settled: false` and `waitedMs` to its metadata. Successful checks add `settled: true`;
+`loadComplete` records when the source verified the document. The existing `captureTimeoutMs` still bounds the
+whole capture, including this wait and any final image. The wait never changes the step's own timestamps or outcome.
+
+Only feature after-frames with video enabled wait for visual stability, including the final frame after the
+2-second scenario tail. Tool-run captures, before-frames, checkpoints and default frames-only feature captures
+retain their existing asynchronous policy. Scenario cleanup still settles captures already in flight. Custom
+capture sources may ignore the optional load check; absent `loadComplete` means load completion is unknown.
+
+
+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/application/src/features/direct-feature-steps.d.ts

@@ -0,0 +1,23 @@
+import type { LabState } from "../lab/lab-state.js";
+import type { FeatureRecording } from "./feature-recording.js";
+import type { ScenarioPlan } from "@parity/product-lab/domain";
+/** Observes custom definitions without treating them as scheduler-owned work. */
+export declare class DirectFeatureSteps {
+    private readonly options;
+    constructor(options: {
+        state: LabState;
+        scenario: string;
+        now: () => number;
+        redact: (text: string) => string;
+        plan: ScenarioPlan;
+        ended: () => boolean;
+        ran: Set<number>;
+        identities: () => string[];
+        recording?: FeatureRecording;
+    });
+    start(index: number): void;
+    finish(index: number, outcome: {
+        status: "passed" | "failed";
+        error?: string;
+    }): Promise<void>;
+}

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

@@ -0,0 +1,25 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { startFeatureStep } from "./feature-step-times.js";
+export class DirectFeatureSteps {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    start(index) {
+        const step = this.options.plan.steps[index];
+        if (!step?.custom || this.options.ended() || this.options.ran.has(index))
+            return;
+        this.options.ran.add(index);
+        const at = this.options.now();
+        startFeatureStep(this.options.state, this.options.scenario, index, step.text, at);
+        this.options.recording?.stepStarted(this.options.scenario, at);
+    }
+    async finish(index, outcome) {
+        const step = this.options.state.scenarioSteps.get(this.options.scenario)?.find((item) => item.featureStep === index + 1);
+        if (!step || step.finishedAt !== undefined)
+            return;
+        Object.assign(step, { status: outcome.status, finishedAt: this.options.now(), ...(outcome.error ? { error: this.options.redact(outcome.error) } : {}) });
+        await this.options.recording?.stepFinished(this.options.scenario, index + 1, this.options.identities());
+    }
+}

package/core/application/src/features/feature-recording.d.ts

@@ -0,0 +1,6 @@
+/** Recording boundaries include direct/custom feature steps that create no runtime run. */
+export interface FeatureRecording {
+    stepStarted(scenario: string, at: number): void;
+    stepFinished(scenario: string, featureStep: number, identities: readonly string[]): Promise<void>;
+    scenarioEnded(scenario: string): Promise<void>;
+}

package/core/application/src/features/feature-recording.js

@@ -0,0 +1,3 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export {};

package/core/application/src/features/feature-scenario.d.ts

@@ -8,7 +8,9 @@ import type { ManageActors } from "../actors/manage-actors.js";
 import type { LabState } from "../lab/lab-state.js";
 import type { RunScenario } from "../runs/run-scenario.js";
 import type { ScenarioStepChecks } from "./scenario-step-checks.js";
+import type { FeatureRecording } from "./feature-recording.js";
 export interface ScenarioDependencies {
+    recording?: FeatureRecording;
     id: string;
     state: LabState;
     runScenario: RunScenario;
@@ -61,6 +63,7 @@ export declare class FeatureScenario implements FeatureScenarioHandle {
     private readonly ownedRuns;
     /** New actors created ahead of their steps (scenario-actor-creation.ts). */
     private readonly creation;
+    private readonly directSteps;
     /** Backlog 31: the controls this scenario set a condition through, by identity: each is reset when it ends. */
     private readonly conditioned;
     readonly outputs: StepOutputs;
@@ -78,22 +81,21 @@ export declare class FeatureScenario implements FeatureScenarioHandle {
     /** What a paused run shows about this scenario (backlog 17; scenario-inspection.ts). */
     inspect(next: number): ScenarioInspection;
     /** Every output recorded so far, the ones the scenario began with included (backlog 21). */
-    recorded(): readonly RecordedOutput[];
-    trace(): readonly FeatureStepTrace[];
+    recorded: () => readonly RecordedOutput[];
+    trace: () => readonly FeatureStepTrace[];
     run(index: number): Promise<FeatureStepTrace>;
     private runStep;
+    startStep: (index: number) => void;
+    finishStep: (index: number, outcome: {
+        status: "passed" | "failed";
+        error?: string;
+    }) => Promise<void>;
     private stepBody;
     /**
      * Backlog 40: after a step passed, each actor that acted in it is checked (a screenshot against its baseline, an
      * accessibility scan); what the checks found is kept in the step's trace, and a failure fails the step.
      */
     private checkStep;
-    /**
-     * A run that shows each actor's app on a surface of its own (the lab window's tiles): an identity call ends once each
-     * of its actors' surfaces shows the app ready, so no later step acts on, or conditions, an app that has not loaded.
-     * The session readied its own page; a tile is another document of the same app.
-     */
-    private surfacesReady;
     /**
      * `{actor} is a new actor` / `these actors exist:`: create an identity per new name (manual mode reuses a bound
      * one). When the environment creates several identities at once (`actorCreation.concurrency`), the new names of

package/core/application/src/features/feature-scenario.js

@@ -14,8 +14,9 @@ import { RunScopedValues } from "./run-scoped-values.js";
 import { ConditionProfiles, ConditionStep, describeNetwork } from "@parity/product-lab/domain/conditions";
 import { conditionControl } from "./scenario-conditions.js";
 import { raceStepDelay } from "./scenario-race.js";
-import { readIdentities, timedFeatureStep } from "./feature-step-times.js";
+import { readIdentities, readyFeatureSurfaces, timedFeatureStep } from "./feature-step-times.js";
 import { ScenarioActorCreation } from "./scenario-actor-creation.js";
+import { DirectFeatureSteps } from "./direct-feature-steps.js";
 const NAVIGATION_WAIT_MS = 30_000;
 export class FeatureScenario {
     name;
@@ -38,6 +39,7 @@ export class FeatureScenario {
     inFlight = new Set();
     ownedRuns = new Set();
     creation;
+    directSteps;
     conditioned = new Map();
     outputs;
     fixture;
@@ -59,6 +61,7 @@ export class FeatureScenario {
         this.outputs = this.view(undefined);
         this.creation = new ScenarioActorCreation({ steps: plan.steps, manageActors: deps.manageActors, ...(deps.clock ? { clock: deps.clock } : {}), signal: this.abort.signal, environment: () => this.active.environment, bound: (name) => this.bindings.has(name), conditions: () => this.conditionedNames(), created: (id) => { if (this.binding === "fresh")
                 this.created.push(id); }, chosenHost: (name) => deps.hosts?.[name], scenario: this.name });
+        this.directSteps = new DirectFeatureSteps({ state: deps.state, scenario: name, now: () => deps.runScenario.clock.date().getTime(), redact: (text) => deps.redactor.text(text), identities: () => this.identities(), ...(deps.recording ? { recording: deps.recording } : {}), plan, ended: () => this.ended, ran: this.ran });
     }
     current() {
         const active = this.deps.state.active;
@@ -90,12 +93,8 @@ export class FeatureScenario {
     inspect(next) {
         return inspectScenario(this.plan, next, this.store, this.bindings, this.deps.redactor);
     }
-    recorded() {
-        return this.store.entries();
-    }
-    trace() {
-        return this.deps.redactor.value(this.steps);
-    }
+    recorded = () => this.store.entries();
+    trace = () => this.deps.redactor.value(this.steps);
     run(index) {
         if (this.ended)
             return Promise.reject(new Error(`Scenario "${this.name}" has ended`));
@@ -117,8 +116,10 @@ export class FeatureScenario {
         this.ran.add(index);
         this.current();
         const now = () => this.deps.runScenario.clock.date().getTime();
-        return timedFeatureStep(this.deps.state, this.name, index, step.text, now, (text) => this.deps.redactor.text(text), () => this.stepBody(index, step));
+        return timedFeatureStep(this.deps.state, this.name, index, step.text, now, (text) => this.deps.redactor.text(text), () => this.stepBody(index, step), { recording: this.deps.recording, identities: () => this.identities() });
     }
+    startStep = (index) => this.directSteps.start(index);
+    finishStep = (index, outcome) => this.directSteps.finish(index, outcome);
     async stepBody(index, step) {
         const calls = step.calls.map((call) => ({
             owner: call.entry.owner,
@@ -158,7 +159,7 @@ export class FeatureScenario {
             await flush();
             try {
                 await this.identity(call, calls[position], index);
-                await this.surfacesReady(introducedNames(call));
+                await readyFeatureSurfaces(this.deps.surface, introducedNames(call), this.bindings, this.abort.signal);
                 calls[position].status = "complete";
             }
             catch (error) {
@@ -187,12 +188,6 @@ export class FeatureScenario {
         if (failures.length)
             throw FeatureStepError.of(`Step ${index + 1} ("${step.text}"): ${failures.join("; ")}`, this.deps.redactor.value(trace), reasons?.[0]);
     }
-    async surfacesReady(names) {
-        if (!this.deps.surface)
-            return;
-        const ids = [...new Set(names.map((name) => this.bindings.get(name)).filter((id) => id !== undefined))];
-        await Promise.all(ids.map((id) => this.deps.surface(id)?.ready?.({ signal: this.abort.signal })));
-    }
     async identity(call, trace, index) {
         const names = introducedNames(call);
         const unfunded = call.entry.owner === NEW_UNFUNDED_ACTOR_OWNER;
@@ -572,6 +567,7 @@ export class FeatureScenario {
             run.interrupt(reason);
         await Promise.allSettled([...this.inFlight]);
         await this.creation.settled();
+        await this.deps.recording?.scenarioEnded(this.name);
         await this.deps.state.beforeClose.settle();
         const errors = [];
         for (const [actorId, control] of this.conditioned) {

package/core/application/src/features/feature-step-times.d.ts

@@ -1,7 +1,17 @@
+import type { RecordedFeatureStep } from "@parity/product-lab/domain/recordings";
 import type { LabEnvironment } from "@parity/product-lab/ports/lab";
 import type { LabState } from "../lab/lab-state.js";
+import type { FeatureRecording } from "./feature-recording.js";
+import type { FeatureSessionOptions } from "@parity/product-lab/ports/driving";
 /** Run step `index` (`work`) of scenario `name`, keeping its times and outcome; `redact` cleans a failure's message. */
-export declare function timedFeatureStep<T>(state: LabState, name: string, index: number, text: string, now: () => number, redact: (text: string) => string, work: () => Promise<T>): Promise<T>;
+export declare function timedFeatureStep<T>(state: LabState, name: string, index: number, text: string, now: () => number, redact: (text: string) => string, work: () => Promise<T>, observe?: {
+    recording?: FeatureRecording;
+    identities: () => string[];
+}): Promise<T>;
+/** Direct/custom definitions use the same timing data as steps run through the scheduler. */
+export declare function startFeatureStep(state: LabState, name: string, index: number, text: string, at: number): RecordedFeatureStep;
+/** A visible tile is a separate document from the session's own page; ready it before later steps use it. */
+export declare function readyFeatureSurfaces(surface: FeatureSessionOptions["surface"], names: readonly string[], bindings: ReadonlyMap<string, string>, signal: AbortSignal): Promise<void>;
 /**
  * Backlog 160: what the environment reads of the identities a step made, on chain and on their screens, kept as the
  * step's checks (`LabState.featureStepReadings`). A reading the environment cannot take fails the step: a new identity

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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