@parity/product-lab 0.0.1-placeholder → 0.1.0

package/core/ports/src/driving/lab-settings.d.ts

@@ -0,0 +1,29 @@
+export type LabTheme = "dark" | "light" | "system";
+export type LabCursorSpeed = "slow" | "normal" | "fast";
+export interface LabWindowSettings {
+    /** The lab's controls' theme (never the app's): dark, light or the system's. */
+    theme?: LabTheme;
+    /** Show mode: each identity's cursor, and its speed. */
+    cursor?: {
+        enabled?: boolean;
+        speed?: LabCursorSpeed;
+    };
+    /**
+     * "Keep each fork run's starting state" (5 October 2026), off unless set: each scenario that starts on a state its run
+     * bundle could not rebuild (a fork or another saved environment, no fixture named) saves that state first, so
+     * Reproduce can rebuild it. The lab keeps the last few (`LabSnapshot.runStart`).
+     */
+    keepRunStart?: boolean;
+    /**
+     * "Keep chain and people between starts" (backlog 183), as the person last set it in the lab window. It applies to
+     * the interactive lab only (`product-lab lab`); `product-lab test`, CI and MCP start clean unless asked (`--keep`).
+     * Absent: the entry point's default.
+     */
+    keepBetweenStarts?: boolean;
+}
+export interface LabSettings {
+    /** The saved settings ({} when nothing was saved or the lab keeps no settings). */
+    read(): Promise<LabWindowSettings>;
+    /** Merge `change` into the saved settings and keep them; answers what is saved now. A malformed change is refused. */
+    write(change: LabWindowSettings): Promise<LabWindowSettings>;
+}

package/core/ports/src/driving/lab-settings.js

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

package/core/ports/src/driving/lab-snapshot.d.ts

@@ -0,0 +1,361 @@
+import type { SideReading } from "@parity/product-lab/domain/checks";
+import type { ActorSession, HostBypassEvidence, OptionPick, Principal, PublicTargetData, RetentionView, RunStatus, StepStatus } from "@parity/product-lab/domain";
+import type { CheckedTransaction, StoreCheck, SubmissionAttributionView, SubmissionOutcome } from "./reports.js";
+import type { InputField } from "../driven/lab/scenario.js";
+import type { EnvironmentHost, IdentityReserveStatus, PreOnboardedActorView, UnconfiguredHost, WorkspaceStatus } from "../driven/lab/lab-environment.js";
+import type { ActivitySnapshot, DeclaredWrite } from "./activity.js";
+import type { EnvironmentOptionView, LabRegistry } from "./lab-registry.js";
+import type { EnvironmentRpcView } from "./environment-rpc.js";
+import type { ChainDay, ChainDayEnded } from "../driven/environment/environment-time.js";
+import type { NavigationSnapshot } from "./navigation-view.js";
+import type { FeatureRunRecord } from "./features.js";
+import type { CurrentFixture, FixtureBuild } from "./fixtures.js";
+import type { StartPhaseUpdate } from "../driven/environment/start-phases.js";
+import type { AppBuildRef, AppBuildView } from "./app-builds.js";
+/** One step of a run, as views show it. */
+export interface ExecutionStep {
+    hostBypass?: HostBypassEvidence;
+    title: string;
+    /** The domain's `StepStatus`; views use pending, running, complete, skipped and failed. */
+    status: Extract<StepStatus, "pending" | "running" | "complete" | "skipped" | "failed">;
+    /** What the step returned, recorded when it completes. */
+    evidence?: unknown;
+    /** Why it failed, as a reason id (the domain's failure-reason.ts), beside its `error`. */
+    reason?: string;
+    /** `false`: the step changes nothing (it reads, or acts on the screen only); absent: it may change chain state. */
+    mutates?: false;
+    /**
+     * What the step attached while it ran (`ScenarioContext.attach`), kept whether it completed or failed; absent when
+     * it attached nothing.
+     */
+    attached?: Record<string, unknown>;
+    /**
+     * Phase 5 (views and per-actor lanes): the identity the step acts as, the scenario actor it plays, and the resources it held.
+     * Absent on a setup step (`principal` setup): setup work acts as no identity.
+     */
+    actor?: string;
+    /** Who the step acts as (29 September 2026): the setup principal, or `actor`'s identity. Views say "Setup" for setup. */
+    principal?: Principal;
+    role?: string;
+    resources?: string[];
+    /** The run-together group it ran in (steps with the same key overlapped where their resources allowed). */
+    together?: string;
+    /**
+     * In a run-together group: the earlier steps of the group it waited for (by index in the run) and the resources
+     * they shared; they did not overlap. Absent when it waited for none.
+     */
+    waitsFor?: {
+        step: number;
+        resources: string[];
+    }[];
+    startedAt?: number;
+    finishedAt?: number;
+    /** Why the step failed (or was cancelled after it started), as the run reports it. */
+    error?: string;
+    /** Additional abort diagnostics for display only; not part of failure classification or control matching. */
+    abortDetail?: string;
+    /**
+     * A mutating step that failed after submitting: whether its transactions
+     * landed, decided from finalized state (by the Scheduler's reconciliation
+     * inside the run, or by the lab's own check after it: `afterFailure`).
+     * `not-submitted`: a step that declares `reportsSubmission` failed before
+     * reporting a transaction, so it submitted nothing (no chain was asked).
+     * `attribution`: the step recorded no transaction, and its submissions were
+     * told from what the chain and the host saw of its identity's account while
+     * it ran (backlog item 63); an ambiguous one leaves the outcome unknown.
+     * `source: "action"`: the failed action declared the outcome itself (`KnownSubmissionError`: its own read-back
+     * knows), so no reconciler was asked; `detail` says it in words, and a known outcome needs no reconciling.
+     */
+    /** Backlog 99: the writes to a content store the step declared (`statement` and `preimage` activity events), in order. */
+    declaredWrites?: DeclaredWrite[];
+    reconciliation?: {
+        outcome: SubmissionOutcome;
+        at: number;
+        transactions: CheckedTransaction[];
+        attribution?: SubmissionAttributionView;
+        stores?: StoreCheck[];
+        source?: "action";
+        detail?: string;
+    };
+    /**
+     * A mutating step that failed: what the lab says about what it sent, in words. `checking` while the lab looks at the
+     * chain after the run ended (the step may have sent a transaction; the next run need not wait); `answered` once it
+     * knows, or knows it cannot tell (`words` says which and why). A step that failed before sending anything is answered
+     * at once. Nothing waits for it: a failure never blocks the lab.
+     */
+    afterFailure?: {
+        state: "checking" | "answered";
+        startedAt: number;
+        answeredAt?: number;
+        words: string;
+    };
+    /**
+     * Hot reload (backlog item 5): the build of each watched app the step ran against, taken when it started acting as
+     * its identity. Absent when no app is watched or the step acts as no identity.
+     */
+    appBuilds?: AppBuildRef[];
+}
+/** One scenario actor's identity for a run (fixed when the run started). */
+export interface ExecutionBinding {
+    actor: string;
+    /** The actor session id. */
+    identity: string;
+    origin: "existing" | "provisioned";
+    provisionMs: number;
+}
+/**
+ * One scenario run (the Execution record): a live view of the run's `Run`
+ * aggregate and its Scheduler's step reports, plus timings and messages.
+ * Times are wall-clock milliseconds since the Unix epoch.
+ */
+export interface Execution {
+    hostBypass?: HostBypassEvidence;
+    id: string;
+    scenarioId: string;
+    /** The identity that owns the run; empty when the setup principal owns it (`owner`). */
+    actorId: string;
+    /**
+     * Who owns the run (29 September 2026): the identity `actorId`, or the setup principal for a feature step whose calls
+     * include setup work (then `actorId` is empty and setup work is credited to no participant; each step names its own
+     * `principal`). Absent on records from before principals: read `actorId`.
+     */
+    owner?: Principal;
+    /** The run's status (the domain `Run` aggregate's); `pausing` is reported as `running`, `idle` never. */
+    status: Exclude<RunStatus, "idle" | "pausing">;
+    startedAt: number;
+    finishedAt?: number;
+    pausedAt?: number;
+    pausedMs: number;
+    /** Checkpoint mode: pause after every step. */
+    pauseAfterStep: boolean;
+    pauseReason?: "checkpoint-mode" | "requested";
+    steps: ExecutionStep[];
+    messages: string[];
+    error?: string;
+    /** A scenario that declares actors: who played each one (manual or fresh binding). */
+    bindings?: ExecutionBinding[];
+}
+export interface LabOperation {
+    label: string;
+    startedAt: number;
+    finishedAt?: number;
+    status: "running" | "complete" | "failed";
+    error?: string;
+    /** The phases an environment reported while this operation started it (a switch), in first-seen order. */
+    phases?: OperationPhase[];
+    /** The latest one-line stage that environment reported (EnvironmentStartOptions.progress). */
+    message?: string;
+    /**
+     * It stops the running environment's identities and their hosts (a switch, a reset): the lab window closes their apps
+     * as it begins, so no app is left calling a host that stopped (walk of 6 October 2026, item 4).
+     */
+    leaving?: true;
+    /** A switch refused because the kept chain's day had ended (`ChainDayEnded`), and to which environment: the window offers a new chain. */
+    chainDayEnded?: ChainDayEnded & {
+        readonly environment: string;
+    };
+}
+/** One start phase as an operation keeps it: the latest update, and when it began and ended (ms). */
+export interface OperationPhase extends StartPhaseUpdate {
+    readonly startedAt?: number;
+    readonly endedAt?: number;
+}
+/** What switching to another configured environment would do, decided by the runtime (SwitchEnvironment). */
+export interface SwitchPlan {
+    target: string;
+    targetLabel: string;
+    currentLabel: string;
+    allowed: boolean;
+    /** Why the switch is refused (empty when allowed). */
+    reason: string;
+    /** Selecting the current environment changes nothing. */
+    noop: boolean;
+    /** Leaving the current environment discards its chain state. */
+    destructive: boolean;
+    /** The confirmation a destructive switch needs (`Confirmations.leave`). */
+    confirmation?: string;
+    consequences: string[];
+    /**
+     * Backlog 184: the way the target starts ("Light (fewer nodes, for smaller laptops)") and why (the person's last
+     * choice, else this machine's fit): the target's registry `pick`. Absent for an environment with one way to run.
+     */
+    option?: {
+        id: string;
+        label: string;
+        why: string;
+    };
+}
+/**
+ * The confirmations destructive operations need in the current environment
+ * session, issued by the runtime for every caller (panel, MCP, CLI). A
+ * confirmation from an earlier session (before a reset or switch) is refused.
+ */
+export interface ConfirmationTokens {
+    /** For `resetEnvironment`, when the environment can be reset. */
+    reset?: string;
+    /** For `manageActor("delete", id)`, per actor id. */
+    deleteIdentity: Record<string, string>;
+    /** For `restoreFixture`, when the environment can save and restore its state (fixtures). */
+    restoreFixture?: string;
+    /** For `allowRootCalls`, when the lab declares root calls for this environment. */
+    rootCalls?: string;
+}
+/**
+ * Backlog 180: this environment's root calls, when the lab declares them for it (`defineLab({ rootCalls })`): the calls
+ * its policy allows, and whether this session confirmed them (`LabRuntime.allowRootCalls`; a reset or switch ends it).
+ */
+export interface RootCallsView {
+    allowed: string[];
+    confirmed: boolean;
+}
+export interface LabSnapshot {
+    /** The environment session: a new id after every start, switch and reset, and after a fixture save or restore. */
+    environmentId: string;
+    /**
+     * The earlier sessions this one continues, oldest first: a fixture save or restore (an `@isolated` scenario's
+     * included) reopens the session on the same environment under a new id. Absent after a start, switch or reset, which
+     * begin a new lineage. The lab window's run keeps acting in its identities' tiles across such a reopening.
+     */
+    environmentLineage?: readonly string[];
+    name: string;
+    /**
+     * The running environment's one display name: its configured label (the same one `environments` lists for the
+     * picker), else its registry entry's label, else the session's own name (a lab with no configured environments).
+     * Views show this and never compose another name for it.
+     */
+    environment: string;
+    provider: string;
+    provenance: Record<string, unknown>;
+    actors: readonly ActorSession[];
+    scenarios: {
+        id: string;
+        title: string;
+        description: string;
+        inputs: Record<string, InputField>;
+        /** The actors the scenario names; a run binds each to an identity. */
+        actors?: string[];
+    }[];
+    capabilities: {
+        createActor: boolean;
+        reset: boolean;
+        manageActors?: boolean;
+        manageWorkspace?: boolean;
+        /** What a reset discards of the chains, in the environment's words (A4, 6 October 2026); the people are `actors`. */
+        resetDiscards?: string;
+        /** Why there is no reset, in the environment's words; absent when there is one. */
+        resetUnsupported?: string;
+    };
+    workspace?: WorkspaceStatus;
+    /** Each chain's day (`ChainDay`): when its clock leaves the wall clock's day; absent: its chains keep the wall clock's time. */
+    chainDays?: ChainDay[];
+    /** Identities the environment keeps ready for "New identity" and new scenario actors (not listed in `actors`). */
+    identityReserve?: IdentityReserveStatus;
+    /**
+     * The hosts the lab declares, as the running environment reports them (`LabEnvironment.hosts()`): the one a new
+     * identity gets by default, and why one cannot be used here. Absent: the environment runs everyone on its one host.
+     */
+    hosts?: readonly EnvironmentHost[];
+    /** Host adapters the lab can use but does not declare: New identity lists them greyed, with how to turn each on. */
+    unconfiguredHosts?: readonly UnconfiguredHost[];
+    /** The lab's pre-onboarded identities (backlog A3): existing accounts by name, opened or not; no secret value. */
+    preOnboarded?: readonly PreOnboardedActorView[];
+    /** Set when the running environment is on a public network (backlog A6): what views say about it (nothing resets). */
+    public?: PublicTargetData;
+    job: Execution | null;
+    /** The latest feature run in this process (Phase 4, the manual panel): its steps so far and where it waits. */
+    /**
+     * Backlog 160: what the feature scenarios' steps that run no lab run read on each side (a new identity's chain and
+     * screen readings), by scenario name, then by step index (0-based).
+     */
+    featureStepReadings?: Record<string, Record<number, SideReading[]>>;
+    featureRun?: FeatureRunRecord;
+    /**
+     * The conditions a scenario set on each identity's session and that still hold (backlog 31), by identity id: the
+     * network profile's name and the CPU slowdown. Absent or empty: every identity is online at full speed.
+     */
+    actorConditions?: Readonly<Record<string, {
+        readonly network?: string;
+        readonly cpu?: number;
+    }>>;
+    /** Bounded session history, including the current job; receipts load separately. */
+    jobs: Execution[];
+    activity: ActivitySnapshot;
+    notices: readonly string[];
+    registry?: LabRegistry;
+    /** Each actor's active application, when the environment follows host navigation. */
+    navigation?: NavigationSnapshot;
+    /**
+     * `rpc`: an environment that takes the lab's RPC per chain (3 October 2026). `options` and `pick` (backlog 184): the
+     * ways it can run and the one its next start runs as.
+     */
+    environments: {
+        id: string;
+        label: string;
+        description: string;
+        rpc?: EnvironmentRpcView;
+        options?: EnvironmentOptionView[];
+        pick?: OptionPick;
+    }[];
+    selectedEnvironment?: string;
+    /** Backlog 184: the option the running environment runs as, and why. */
+    selectedOption?: OptionPick;
+    /** What leaving the current environment does to its state (the runtime's one retention rule). */
+    retention: RetentionView;
+    /** Per configured environment, what switching to it would do now. */
+    switchPlans: Record<string, SwitchPlan>;
+    /** Backlog 180: root calls here, when the lab declares them for this environment. */
+    rootCalls?: RootCallsView;
+    confirmations: ConfirmationTokens;
+    /**
+     * Why the environment itself cannot run anything until it is reset or restarted (its cleanup failed, or it lost a
+     * chain or process it runs). Never set by a failed run: a failure never blocks the lab.
+     */
+    blockedReason?: string;
+    operation?: LabOperation;
+    /** Hot reload (backlog item 5): each watched app's build and what its latest change did; absent when nothing is watched. */
+    appBuilds?: AppBuildView[];
+    /** The fixture the running state is exactly (restored or just saved), until anything runs on it. */
+    fixture?: CurrentFixture;
+    /**
+     * Set when the running environment's scenarios start on a state their run bundles cannot rebuild unless it is kept
+     * (a fork or another saved environment): whether "Keep each fork run's starting state" is on, and how many it keeps.
+     */
+    runStart?: {
+        readonly keeping: boolean;
+        readonly kept: number;
+    };
+    /** "Keep chain and people between starts" (backlog 183): this start's choice, the next one's, and what keeping keeps. */
+    keepBetweenStarts?: KeepBetweenStartsView;
+    /** The latest fixture build in this process (`LabRuntime.buildFixture`). */
+    fixtureBuild?: FixtureBuild;
+    serverTime: number;
+}
+/** Whether a start keeps the chains and people as the last start left them, and why (backlog 183). */
+export interface KeepChoice {
+    readonly keep: boolean;
+    /** "you turned it on", "asked for this start (--clean)", the entry point's default reason. */
+    readonly why: string;
+}
+/** The lab window's "Keep chain and people between starts" (backlog 183). */
+export interface KeepBetweenStartsView {
+    /** The running environment's start: kept or clean, and why. */
+    readonly running: KeepChoice;
+    /** The next start's, as the switch stands now. */
+    readonly next: KeepChoice;
+    /** The switch decides (the interactive lab); otherwise it shows the choice and why, greyed. */
+    readonly switchable: boolean;
+    /** What keeping keeps of the running environment's chains (its provider's words); absent: `chainsNot` says why. */
+    readonly chains?: string;
+    readonly chainsNot?: string;
+    /** What keeping keeps of the people (`defineLab({ keepBetweenStarts })`); absent: `peopleNot` says why. */
+    readonly people?: string;
+    readonly peopleNot?: string;
+}
+/** The entry point's default for "Keep chain and people between starts": whether starts keep, why, and whether the lab window's switch decides. */
+export interface KeepPolicy {
+    readonly default: boolean;
+    /** Why, for the switch's hover: "the interactive lab keeps them, so you find your chain and people as you left them". */
+    readonly why: string;
+    /** The interactive lab: the lab window's remembered switch applies. */
+    readonly switchable: boolean;
+}

package/core/ports/src/driving/lab-snapshot.js

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

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

@@ -0,0 +1,22 @@
+import type { LoadGuardLimits, LoadReport } from "@parity/product-lab/domain/load";
+export interface LoadRequest {
+    readonly actors: number;
+    /** One registered sentence with `{actor}` where each identity's name goes: `{actor} publishes a note`. */
+    readonly action: string;
+    /** Calls of the action per identity (default 1). */
+    readonly each?: number;
+    /** The machine guard (default `DEFAULT_LOAD_GUARD`: 1.5 per CPU, 64, 2 GB free memory). */
+    readonly guard?: Partial<LoadGuardLimits>;
+    /** How often the guard reads the machine while the load runs (default 1000 ms). */
+    readonly guardIntervalMs?: number;
+    /** Lines saying what the load is doing (identities made, guard readings, stop). */
+    readonly onProgress?: (message: string) => void;
+    readonly signal?: AbortSignal;
+}
+export interface LoadRunReport extends LoadReport {
+    /** The load scenario's name, as its recording is titled. */
+    readonly name: string;
+    readonly recording?: string;
+    /** Why the load did not complete, when it did not (a step failed, the guard stopped it, the run was stopped). */
+    readonly error?: string;
+}

package/core/ports/src/driving/load.js

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

package/core/ports/src/driving/navigation-view.d.ts

@@ -0,0 +1,23 @@
+/** The application an actor currently has in front of them. */
+export interface ActiveApplication {
+    actorId: string;
+    appId: string;
+    /** Root-relative path the app was opened at (`/` when none was given). */
+    path: string;
+    /** Address of the destination session's page, for the shell to show;
+     * absent when the session could not report one. */
+    url?: string;
+    /** When it became active (unix ms). */
+    since: number;
+    /** The navigation request that made it active; absent for a session the
+     * lab opened directly. */
+    navigation?: {
+        url: string;
+        requestedAt: number;
+        outcome: "opened" | "focused";
+        fromApp: string;
+    };
+}
+export interface NavigationSnapshot {
+    active: ActiveApplication[];
+}

package/core/ports/src/driving/navigation-view.js

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

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

@@ -0,0 +1,103 @@
+import type { FrameChoice, RecordingLane, RecordingMode, RecordingSummary, RunRecordingData, StepHealth, StepSpeedReport } from "@parity/product-lab/domain/recordings";
+import type { FrameCapture } from "../driven/recording/frame-capture.js";
+/** The lab's recorded runs, newest first. */
+export interface RecordingListing {
+    /** How this runtime records (`off` records nothing), and its retention in words. */
+    mode: RecordingMode;
+    retention: string;
+    /** Where recordings are kept; absent when there is nowhere to keep them (why in `disabled`). */
+    location?: string;
+    /**
+     * Where pages are recorded as video when this runtime records video (backlog 18b, `PRODUCT_LAB_RECORDINGS_VIDEO=on`):
+     * `<location>/videos`. A lab window recording there has its video named by the recordings of its runs. Absent: no
+     * video is recorded for recordings.
+     */
+    videos?: string;
+    disabled?: string;
+    recordings: RecordingSummary[];
+    /** Stored recordings that could not be read, with why (kept for a person to inspect). */
+    unreadable: {
+        id: string;
+        error: string;
+    }[];
+    /** The last recording this runtime failed to write, if any. */
+    lastFailure?: {
+        at: number;
+        error: string;
+    };
+}
+/** Both sides of one step for one identity. */
+export interface RecordingFramePair {
+    before: FrameChoice;
+    after: FrameChoice;
+}
+/** One recording, ready to show: its data, its timeline lanes and, per step and identity, the frames to show. */
+export interface RecordingView {
+    recording: RunRecordingData;
+    lanes: RecordingLane[];
+    /** Per step (index), per identity of the recording: what shows its app before and after that step. */
+    frames: {
+        step: number;
+        actors: Record<string, RecordingFramePair>;
+    }[];
+    /** Machine and chain health per step with its findings (backlog 25, `RecordingHealth.DEFAULT`), when the recording sampled it. */
+    health?: StepHealth[];
+    /** Always true: a recording is evidence of what happened; nothing in it can act. */
+    readOnly: true;
+}
+export interface RecordingFrameImage {
+    mediaType: string;
+    bytes: Uint8Array;
+}
+/** The read-only recordings side of `LabRuntime` (RecordRuns, ListRecordings, OpenRecording). */
+/** Which recording to check against its history, and optional limits (backlog 29; defaults: `StepSpeedLimits.DEFAULT`). */
+export interface StepSpeedRequest {
+    id: string;
+    factor?: number;
+    minimumGapMs?: number;
+    minimumSamples?: number;
+}
+/**
+ * Backlog 244: one step of a run this runtime started: a scenario run's step (0-based, as `RunHandle.evidence`), or a
+ * feature run's Gherkin step in one of its scenarios (1-based, Background steps first, hooks not counted).
+ */
+export type RunStepHealthRequest = {
+    run: string;
+    step: number;
+} | {
+    featureRun: string;
+    scenario: string;
+    featureStep: number;
+};
+/**
+ * That step's machine and chain health with its findings (`RecordingHealth.DEFAULT`), one entry per recorded step (a
+ * Gherkin step may run several): from the samples so far while its recording is open (`live`), else from the written
+ * recording (`recording`). `none` says why there is none.
+ */
+export type RunStepHealth = {
+    health: StepHealth[];
+    live: boolean;
+    recording?: string;
+} | {
+    none: string;
+    recording?: string;
+};
+export interface LabRecordings {
+    recordings(): Promise<RecordingListing>;
+    /** Backlog 244: a step's health while its run is recorded, and after; absent: this runtime records no runs of its own. */
+    runStepHealth?(request: RunStepHealthRequest): Promise<RunStepHealth>;
+    /** Throws when there is no recording with that id. */
+    recording(id: string): Promise<RecordingView>;
+    /** Throws when the recording has no stored image for that frame. */
+    recordingFrame(request: {
+        id: string;
+        frame: string;
+    }): Promise<RecordingFrameImage>;
+    /** Each step of a recording against the same step in earlier passed runs of its scenario (backlog 29). Throws when there is no recording with that id. */
+    recordingSpeed(request: StepSpeedRequest): Promise<StepSpeedReport>;
+    /**
+     * A live frame source for recordings (the lab window's actor frames): used before the environment's own capture
+     * until the returned function is called. Captures only read pixels.
+     */
+    captureFramesFrom(capture: FrameCapture): () => void;
+}

package/core/ports/src/driving/recordings.js

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