@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/panel/src/client/resize.js

@@ -0,0 +1,137 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { h, icon } from "./ui.js";
+export const SIZE_KEY = (mode) => `product-lab-panel-size-${mode}`;
+export const DEFAULT_SIZE = { left: 420, right: 420, bottom: 320 };
+export const MIN_SIZE = { width: 280, height: 180 };
+export const STAGE_SHARE = 0.4;
+const STEP = 16, BIG_STEP = 64;
+const vertical = (mode) => mode !== "bottom";
+const pixels = (name) => parseFloat(getComputedStyle(document.documentElement).getPropertyValue(name)) || 0;
+const mode = () => { const value = document.body.dataset.dock; return value === "bottom" || value === "right" ? value : "left"; };
+export function bounds(dock) {
+    const gap = pixels("--frame-gap"), dockHeight = pixels("--dock-height");
+    const room = vertical(dock) ? innerWidth - gap * 3 : innerHeight - dockHeight - gap * 4;
+    const max = Math.floor(room * (1 - STAGE_SHARE));
+    const min = Math.min(vertical(dock) ? MIN_SIZE.width : MIN_SIZE.height, max);
+    return { min, max };
+}
+const clamp = (dock, size) => { const { min, max } = bounds(dock); return Math.round(Math.min(max, Math.max(min, size))); };
+function stored(dock) {
+    try {
+        const value = Number(localStorage.getItem(SIZE_KEY(dock)));
+        return Number.isFinite(value) && value > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function remember(dock, size) {
+    try {
+        if (size === undefined)
+            localStorage.removeItem(SIZE_KEY(dock));
+        else
+            localStorage.setItem(SIZE_KEY(dock), String(size));
+    }
+    catch {  }
+}
+export function createResizer(panel) {
+    const handle = h("div", { class: "lab-resize", role: "separator", tabindex: 0, "aria-label": "Resize the lab (arrow keys move it, double-click resets)", title: "Drag to resize the lab; double-click for the default size" });
+    panel.append(handle);
+    const size = () => stored(mode()) ?? DEFAULT_SIZE[mode()];
+    function show(value) {
+        const dock = mode();
+        const style = document.body.style;
+        style.removeProperty("--panel-user-width");
+        style.removeProperty("--panel-user-height");
+        const shown = clamp(dock, value ?? DEFAULT_SIZE[dock]);
+        if (value !== undefined)
+            style.setProperty(vertical(dock) ? "--panel-user-width" : "--panel-user-height", `${shown}px`);
+        const { min, max } = bounds(dock);
+        handle.setAttribute("aria-orientation", vertical(dock) ? "vertical" : "horizontal");
+        handle.setAttribute("aria-valuemin", String(min));
+        handle.setAttribute("aria-valuemax", String(max));
+        handle.setAttribute("aria-valuenow", String(shown));
+        return shown;
+    }
+    function set(value) {
+        const dock = mode();
+        delete document.body.dataset.panelPreset;
+        const shown = show(value);
+        remember(dock, value === undefined ? undefined : shown);
+    }
+    handle.addEventListener("pointerdown", (event) => {
+        if (event.button !== 0)
+            return;
+        event.preventDefault();
+        handle.setPointerCapture(event.pointerId);
+        const dock = mode();
+        document.body.dataset.resizing = vertical(dock) ? "width" : "height";
+        const rect = panel.getBoundingClientRect();
+        const from = vertical(dock) ? rect.width : rect.height;
+        const at = (x, y) => from + (dock === "left" ? x - event.clientX : dock === "right" ? event.clientX - x : event.clientY - y);
+        const move = (next) => { delete document.body.dataset.panelPreset; show(at(next.clientX, next.clientY)); };
+        const end = (last) => {
+            handle.removeEventListener("pointermove", move);
+            handle.removeEventListener("pointerup", end);
+            handle.removeEventListener("pointercancel", end);
+            delete document.body.dataset.resizing;
+            set(at(last.clientX, last.clientY));
+        };
+        handle.addEventListener("pointermove", move);
+        handle.addEventListener("pointerup", end);
+        handle.addEventListener("pointercancel", end);
+    });
+    handle.addEventListener("dblclick", () => set(undefined));
+    handle.addEventListener("keydown", (event) => {
+        const dock = mode();
+        const step = event.shiftKey ? BIG_STEP : STEP;
+        const grow = dock === "left" ? "ArrowRight" : dock === "right" ? "ArrowLeft" : "ArrowUp";
+        const shrink = dock === "left" ? "ArrowLeft" : dock === "right" ? "ArrowRight" : "ArrowDown";
+        const { min, max } = bounds(dock);
+        const next = event.key === grow ? size() + step : event.key === shrink ? size() - step : event.key === "Home" ? min : event.key === "End" ? max : undefined;
+        if (next === undefined)
+            return;
+        event.preventDefault();
+        set(clamp(dock, next));
+    });
+    document.addEventListener("product-lab:dock", () => show(stored(mode())));
+    addEventListener("resize", () => show(stored(mode())));
+    show(stored(mode()));
+    return handle;
+}
+export function presetMenu() {
+    const menu = h("div", { class: "panel-size-menu", role: "menu", "aria-label": "Panel size", hidden: true });
+    const wide = () => Math.min(760, Math.round(innerWidth * 0.52));
+    const choose = (preset) => {
+        const dock = mode();
+        menu.hidden = true;
+        if (preset === "full") {
+            document.body.dataset.panelPreset = "full";
+            return;
+        }
+        delete document.body.dataset.panelPreset;
+        const style = document.body.style;
+        if (preset === "normal") {
+            style.removeProperty("--panel-user-width");
+            style.removeProperty("--panel-user-height");
+            remember(dock, undefined);
+        }
+        else {
+            const value = clamp(dock, vertical(dock) ? wide() : Math.round(innerHeight * 0.6));
+            style.setProperty(vertical(dock) ? "--panel-user-width" : "--panel-user-height", `${value}px`);
+            remember(dock, value);
+        }
+        document.querySelector(".lab-resize")?.setAttribute("aria-valuenow", String(stored(dock) ?? DEFAULT_SIZE[dock]));
+    };
+    for (const [preset, label] of [["normal", "Normal"], ["wide", "Wide"], ["full", "Full: the lab over the whole frame"]])
+        menu.append(h("button", { type: "button", role: "menuitem", "data-preset": preset, onclick: () => choose(preset) }, label));
+    const toggle = h("button", { type: "button", class: "panel-size", "aria-label": "Panel size", title: "Panel size: normal, wide or full", "aria-haspopup": "menu", onclick: () => { menu.hidden = !menu.hidden; } }, icon("maximize-2", 14));
+    document.addEventListener("pointerdown", (event) => { if (!menu.hidden && !menu.contains(event.target) && !toggle.contains(event.target))
+        menu.hidden = true; });
+    document.addEventListener("keydown", (event) => { if (event.key === "Escape" && !menu.hidden) {
+        event.preventDefault();
+        menu.hidden = true;
+    } });
+    return h("div", { class: "panel-size-wrap" }, toggle, menu);
+}

package/entrypoints/panel/src/client/root-call-confirm.d.ts

@@ -0,0 +1,11 @@
+import type { LabSnapshot } from "@parity/product-lab/ports/driving";
+/** The confirmation's words, from the snapshot; nothing is shown or allowed. */
+export declare function rootCallWords(snapshot: Pick<LabSnapshot, "environment" | "selectedEnvironment" | "public" | "rootCalls">, scenario: string): {
+    title: string;
+    lead: string;
+    facts: string[];
+    confirm: string;
+    dismiss: string;
+};
+/** Show the confirmation; resolves true when the person allows root calls. */
+export declare function confirmRootCalls(snapshot: LabSnapshot, scenario: string): Promise<boolean>;

package/entrypoints/panel/src/client/root-call-confirm.js

@@ -0,0 +1,35 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { showModal } from "./lab-document.js";
+import { button, h } from "./ui.js";
+export function rootCallWords(snapshot, scenario) {
+    const where = snapshot.selectedEnvironment ?? snapshot.environment;
+    return {
+        title: `Allow root calls on ${where}?`,
+        lead: `"${scenario}" makes root calls: calls dispatched with the chain's Root origin, through its own Sudo pallet, signed by the sudo key the lab declares for ${where}. The lab makes none until you allow them for this session.`,
+        facts: [
+            `Allowed calls: ${(snapshot.rootCalls?.allowed ?? []).join(", ") || "none"}. Any other call is refused before it is signed.`,
+            snapshot.public
+                ? `${where} is a public network: root calls are refused there whatever you confirm.`
+                : `${where} is a local copy the lab started on this machine, with a development sudo key: what the calls change stays in it.`,
+            "A mainnet, a public network or a chain the lab did not start is still refused, whatever you confirm here.",
+            "This lasts until the environment is reset, switched or stopped. From a terminal: product-lab test <feature> --root-calls.",
+        ],
+        confirm: "Allow root calls and run",
+        dismiss: "Don't allow",
+    };
+}
+export function confirmRootCalls(snapshot, scenario) {
+    const words = rootCallWords(snapshot, scenario);
+    return new Promise((resolve) => {
+        let allowed = false;
+        const dismiss = button(words.dismiss, { id: "root-calls-dismiss" });
+        const confirm = button(words.confirm, { variant: "danger", id: "root-calls-confirm" });
+        const dialog = h("dialog", { id: "root-calls-dialog", "aria-labelledby": "root-calls-title" }, h("h1", { id: "root-calls-title" }, words.title), h("p", { class: "root-calls-lead" }, words.lead), h("ul", { class: "root-calls-facts" }, ...words.facts.map((fact) => h("li", {}, fact))), h("div", { class: "actions" }, dismiss, confirm));
+        dismiss.onclick = () => dialog.close();
+        confirm.onclick = () => { allowed = true; dialog.close(); };
+        dialog.addEventListener("close", () => { dialog.remove(); resolve(allowed); });
+        showModal(dialog);
+        dismiss.focus();
+    });
+}

package/entrypoints/panel/src/client/run-mode.d.ts

@@ -0,0 +1,105 @@
+import type { Inputs } from "@parity/product-lab/ports/lab";
+import type { BuilderFeature } from "@parity/product-lab/domain";
+import type { ToolRunView } from "@parity/product-lab/ports/driving";
+import type { BindingChoice } from "./bindings.js";
+import type { CursorModeView } from "./show-cursor.js";
+export type RunMode = "watch" | "background";
+/** The outcome each lab window binding resolves with (src/visible/runner.ts). */
+export interface BindingResult {
+    status: string;
+    error?: string;
+}
+/**
+ * What the lab window (src/visible/runner.ts, Playwright `exposeBinding` before the shell loads) defines on this
+ * page, and the highlight the shell defines for it (client.ts). Any other tab has none of them.
+ */
+export interface LabWindowBindings {
+    __productLabRun?: (request: {
+        actor: string;
+        scenario: string;
+        inputs: Inputs;
+        pause: boolean;
+        actors?: Record<string, BindingChoice>;
+    }) => Promise<BindingResult & {
+        job: string;
+    }>;
+    __productLabFeatureRun?: (request: {
+        actor: string;
+        path: string;
+        name: string;
+        line?: number;
+        example?: number;
+        bindings: Record<string, unknown>;
+        pause: boolean;
+    }) => Promise<BindingResult & {
+        run: string;
+        control?: string;
+    }>;
+    __productLabBuilderRun?: (request: {
+        feature: BuilderFeature;
+        scenario: number;
+        bindings: Record<string, unknown>;
+        pause: boolean;
+    }) => Promise<BindingResult & {
+        run: string;
+    }>;
+    /** The Tools page's Watch (src/visible/runner.ts TOOL_BINDING): start a tool whose runs act in the tiles; resolves as it starts. */
+    __productLabToolRun?: (request: {
+        tool: string;
+        options: Record<string, string | number>;
+    }) => Promise<ToolRunView>;
+    /** Draw or clear (`null`) a highlight ring; `key` names one per acting identity, absent means the window's one ring. */
+    __productLabRing?: (box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null, key?: string) => void;
+    /**
+     * Apply the run view now (backlog 4b): read the lab's snapshot, draw it (the tiles the active runs show), and resolve
+     * with the active run ids that snapshot has. The runner calls it in the input lane before a run's first gesture, so
+     * rings and cursors are placed in the layout the run keeps, not in the one before the shell's next poll.
+     */
+    __productLabRunView?: () => Promise<{
+        runs: string[];
+    }>;
+    /** Bring an identity's shown frame into view (scroll its tile, close a lab overlay over it); false when it has no shown tile. */
+    __productLabReveal?: (actor: string) => boolean;
+    /** The window's visible UI calls so far (src/visible/ui-activity.ts), for a shell that loaded after they were made. */
+    __productLabUiCalls?: () => Promise<unknown[]>;
+    /** Show mode (src/visible/runner.ts CURSOR_BINDING): set part of it (an empty request reads it); resolves with the mode now. */
+    __productLabCursorMode?: (request: Partial<CursorModeView>) => Promise<CursorModeView>;
+    /** Move (or hide, `null`) an identity's show-mode cursor; the shell defines it (show-cursor.ts), the runner calls it. */
+    __productLabCursor?: (key: string, point: {
+        x: number;
+        y: number;
+    } | null, options: {
+        name: string;
+        glideMs: number;
+        click: boolean;
+    }) => void;
+    /** The lab window's detached identities (backlog 31b, src/visible/detached-identities.ts `DETACH_BINDING`). */
+    __productLabDetach?: (request: {
+        op: "list" | "detach" | "reattach";
+        actor?: string;
+        device?: string | object;
+    }) => Promise<unknown>;
+}
+/** This page's `window` with the lab window's bindings: browser globals Playwright adds, so the DOM types cannot name them. */
+export declare function labWindow(): Window & LabWindowBindings;
+/** This page is the lab window: its runner binding exists (Playwright exposeBinding). */
+export declare function inLabWindow(): boolean;
+/** The mode a Run starts in now: the lab window's choice (a running tool's while it runs), else Background. */
+export declare function runMode(): RunMode;
+/** Choose the mode from elsewhere than the dock (the Tools page's Watch | Background): one choice, shown on the dock. */
+export declare function setRunMode(value: RunMode): void;
+/** A tool run started (its mode) or ended (`undefined`): while it runs the dock shows its mode and cannot change. */
+export declare function setToolRun(value: RunMode | undefined): void;
+export declare function watching(): boolean;
+/**
+ * Wire the toggle (`#run-mode`, two buttons with `data-run-mode`) and show it only in the lab window.
+ * `changed` redraws the panel after a choice.
+ */
+export declare function mountRunMode(root: HTMLElement, changed: () => void): void;
+/** Draw the toggle's state; `busy` (a run is starting or active) keeps the choice fixed until it ends. */
+export declare function renderRunMode(root: HTMLElement, busy: boolean): void;

package/entrypoints/panel/src/client/run-mode.js

@@ -0,0 +1,49 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { findById } from "./lab-document.js";
+export function labWindow() {
+    return window;
+}
+let mode = "watch";
+let toolRun;
+let busyNow = false;
+export function inLabWindow() {
+    return typeof labWindow().__productLabRun === "function";
+}
+export function runMode() {
+    return inLabWindow() ? (toolRun ?? mode) : "background";
+}
+export function setRunMode(value) {
+    mode = value;
+    redrawRunMode();
+}
+export function setToolRun(value) {
+    toolRun = value;
+    redrawRunMode();
+}
+function redrawRunMode() {
+    const root = findById("run-mode");
+    if (root)
+        renderRunMode(root, busyNow);
+}
+export function watching() {
+    return runMode() === "watch";
+}
+export function mountRunMode(root, changed) {
+    for (const control of root.querySelectorAll("button[data-run-mode]"))
+        control.onclick = () => {
+            mode = control.dataset.runMode === "background" ? "background" : "watch";
+            renderRunMode(root, false);
+            changed();
+        };
+    renderRunMode(root, false);
+}
+export function renderRunMode(root, busy) {
+    busyNow = busy;
+    root.hidden = !inLabWindow();
+    root.dataset.mode = runMode();
+    for (const control of root.querySelectorAll("button[data-run-mode]")) {
+        control.setAttribute("aria-pressed", String(control.dataset.runMode === runMode()));
+        control.disabled = busy || toolRun !== undefined;
+    }
+}

package/entrypoints/panel/src/client/run-outcome.d.ts

@@ -0,0 +1,28 @@
+import type { FeatureRunRecord } from "@parity/product-lab/ports/driving";
+export interface FeatureFailure {
+    scenario: string;
+    /** 1-based among the scenario's steps (hooks excluded); 0 for a hook. */
+    step: number;
+    text: string;
+    /** The error's first line, without its class name ("The list shows 4 notes, not 3 (at finalized block 266)"). */
+    message: string;
+    /** The whole recorded error (stack included), for the disclosure. */
+    detail: string;
+    hook: boolean;
+}
+/** `FeatureStepError: The list shows 4 notes…\n    at …` → `The list shows 4 notes…`. */
+export declare function errorHeadline(error: string): string;
+/** Every failed step of the run, in order, with its error. */
+export declare function featureFailures(run: FeatureRunRecord | undefined): FeatureFailure[];
+/** The run's scenarios include a negative control (`@negative-control`). */
+export declare function isNegativeControl(run: FeatureRunRecord | undefined, tags?: readonly string[]): boolean;
+/** The failure a control's verdict judged, as one line under it: its reason id and its message's first line. */
+export declare function controlFailureLine(run: FeatureRunRecord): string | undefined;
+/** The sentence under a negative control's result: what it must fail at, and how to judge it for real. */
+export declare function negativeControlNote(run: FeatureRunRecord, failures: readonly FeatureFailure[]): string;
+/** The command that judges a negative control for real, as a person types it: by its tags (where and why it must fail). */
+export declare function negativeControlCommand(run: FeatureRunRecord): string;
+/** Fill `container` with the run's failures (and the negative-control note); empty and hidden when there are none. */
+export declare function renderFeatureOutcome(container: HTMLElement, run: FeatureRunRecord | undefined, options?: {
+    negativeControl?: boolean;
+}): void;

package/entrypoints/panel/src/client/run-outcome.js

@@ -0,0 +1,110 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function errorHeadline(error) {
+    const first = error.split("\n").find((line) => line.trim()) ?? "";
+    return first.replace(/^\s*(?:[A-Z]\w*)?(?:Error|Exception|AssertionError)(?: \[[^\]]*\])?:\s*/, "").trim() || first.trim();
+}
+export function featureFailures(run) {
+    if (!run)
+        return [];
+    return run.scenarios.flatMap((scenario) => {
+        let index = 0;
+        return scenario.steps.flatMap((step) => {
+            if (!step.hidden)
+                index++;
+            if (step.status !== "failed")
+                return [];
+            const detail = step.error ?? "";
+            return [
+                {
+                    scenario: scenario.name,
+                    step: step.hidden ? 0 : index,
+                    text: step.hidden ? `${step.keyword} hook` : `${step.keyword} ${step.name}`.trim(),
+                    message: detail ? errorHeadline(detail) : "failed without an error message",
+                    detail,
+                    hook: !!step.hidden,
+                },
+            ];
+        });
+    });
+}
+export function isNegativeControl(run, tags = []) {
+    return tags.includes("@negative-control") || !!run?.scenarios.some((scenario) => scenario.tags.includes("@negative-control"));
+}
+const shellQuote = (value) => "'" + value.replace(/'/g, "'\\''") + "'";
+export function controlFailureLine(run) {
+    const failure = run.control?.failure;
+    return failure ? `${failure.reason}: ${errorHeadline(failure.message)}` : undefined;
+}
+export function negativeControlNote(run, failures) {
+    const path = run.selection.paths[0] ?? "<feature>";
+    const by = run.control?.expected?.step || run.control?.expected?.marker ? ` (judged by text: step "${run.control.expected.step ?? "?"}" with "${run.control.expected.marker ?? "?"}")` : "";
+    if (run.control?.verdict === "failed-as-intended")
+        return `Failed as intended, the lab caught it: ${run.control.reason}.`;
+    if (run.control?.verdict === "wrong-reason")
+        return `Failed for another reason: ${run.control.reason}${by}. This does not count as a working control.`;
+    if (run.control)
+        return `Negative control not verified: ${run.control.reason}.`;
+    if (run.status === "passed")
+        return "Negative control passed: the check did not catch the deliberate mistake. That is a failure of the control.";
+    if (failures.some((failure) => failure.hook) || run.error)
+        return "Negative control not verified: the run failed in setup or a hook, not at the intended scenario step.";
+    const failed = failures.filter((failure) => !failure.hook);
+    if (failed.length !== 1)
+        return `Negative control: ${failed.length} failed steps; a valid control fails at exactly one scenario step, so this result does not count.`;
+    return `Negative control not verified: only a failure at the step and for the reason it was written for counts, and this run was not judged. Judge it with product-lab test ${shellQuote(path)} --negative-control (its tags say where and why: @fails-at-step-N, @fails-with:<reason>).`;
+}
+export function negativeControlCommand(run) {
+    return `product-lab test ${run.selection.paths[0]?.replace(/:\d+(?::\d+)*$/, "") ?? "<feature>"} --negative-control`;
+}
+const node = (tag, text, className) => {
+    const element = document.createElement(tag);
+    if (text !== undefined)
+        element.textContent = text;
+    if (className)
+        element.className = className;
+    return element;
+};
+export function renderFeatureOutcome(container, run, options = {}) {
+    const finished = !!run && run.status !== "queued" && run.status !== "running";
+    const failures = featureFailures(run);
+    const control = !!run && finished && (options.negativeControl || isNegativeControl(run));
+    const key = JSON.stringify([run?.id, run?.status, failures, run?.error, run?.control, control]);
+    if (container.dataset.key === key)
+        return;
+    container.dataset.key = key;
+    const children = [];
+    for (const failure of failures) {
+        const item = node("div", undefined, "run-failure");
+        item.dataset.failedStep = String(failure.step);
+        item.append(node("strong", `${failure.hook ? "A hook" : `Step ${failure.step}`} failed: ${failure.text}`));
+        const message = node("p", failure.message, "run-failure-message");
+        item.append(message);
+        if (failure.detail && failure.detail.trim() !== failure.message) {
+            const details = node("details");
+            details.append(node("summary", "Full error"), node("pre", failure.detail));
+            item.append(details);
+        }
+        children.push(item);
+    }
+    if (run?.error) {
+        const item = node("div", undefined, "run-failure");
+        item.dataset.runError = "";
+        item.append(node("strong", "The run could not complete"), node("p", run.error, "run-failure-message"));
+        children.push(item);
+    }
+    if (control && run) {
+        const note = node("p", negativeControlNote(run, failures), "run-control-note");
+        note.dataset.negativeControl = run.control?.verdict ?? "not judged";
+        children.push(note);
+        const judged = controlFailureLine(run);
+        if (judged) {
+            const line = node("p", judged, "run-control-failure");
+            line.dataset.controlReason = run.control.failure.reason;
+            children.push(line);
+        }
+    }
+    container.replaceChildren(...children);
+    container.hidden = children.length === 0;
+    container.dataset.negativeControl = String(control);
+}

package/entrypoints/panel/src/client/run-preludes.d.ts

@@ -0,0 +1,54 @@
+import type { FeatureRunRecord } from "@parity/product-lab/ports/driving";
+/** The step before a run's own steps: the switch the lab window made for it. */
+export interface RunPrelude {
+    kind: "switch";
+    /** The environment it left, and the one it switched to (ids). */
+    from: string;
+    to: string;
+    /** "Switch to paseo-copy (Local Paseo)". */
+    title: string;
+    status: "running" | "passed" | "failed";
+    startedAt: number;
+    finishedAt?: number;
+    /** What the switch is doing now (the start's phase), or why it failed. */
+    detail?: string;
+    /** Passed, and the run waits on the person before it starts ("Waiting for you to allow the root calls"). */
+    waiting?: string;
+    /** The scenario it was made for. */
+    scenario: {
+        path: string;
+        name: string;
+    };
+}
+/** A switch for a run begins. */
+export declare function beginPrelude(prelude: Omit<RunPrelude, "status" | "kind">): RunPrelude;
+/** What the switch is doing now (the environment start's phase). */
+export declare function preludeProgress(detail: string): void;
+/** The switch ended: passed (the run starts next) or failed (no run starts; the step says why). */
+export declare function settlePrelude(outcome: {
+    ok: true;
+    at: number;
+} | {
+    ok: false;
+    at: number;
+    error: string;
+}): void;
+/**
+ * A passed switch whose run waits on the person (a root-call confirmation): the Run tab keeps showing the switch, saying
+ * what it waits for, instead of "No run yet" behind the dialog (user, 6 October 2026).
+ */
+export declare function preludeWaiting(why: string): void;
+/** The person declined what the run waited for: no run starts, and the switch leaves the Run tab. */
+export declare function abandonPrelude(): void;
+/** The switch still under way, one that failed before its run could start, or one waiting on the person: the Run tab shows it as a run. */
+export declare function pendingPrelude(): RunPrelude | undefined;
+/**
+ * The switch made for this feature run: the first run of its scenario that started once the switch passed takes it,
+ * and keeps it.
+ */
+export declare function preludeOf(run: Pick<FeatureRunRecord, "id" | "startedAt">, scenario: {
+    path: string;
+    name: string;
+} | undefined): RunPrelude | undefined;
+/** Forget every switch (tests). */
+export declare function clearPreludes(): void;

package/entrypoints/panel/src/client/run-preludes.js

@@ -0,0 +1,46 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+const settled = new Map();
+let current;
+export function beginPrelude(prelude) {
+    current = { kind: "switch", ...prelude, status: "running" };
+    return current;
+}
+export function preludeProgress(detail) {
+    if (current?.status === "running")
+        current = { ...current, detail };
+}
+export function settlePrelude(outcome) {
+    if (!current)
+        return;
+    const { detail: _stage, ...rest } = current;
+    current = { ...rest, status: outcome.ok ? "passed" : "failed", finishedAt: outcome.at, ...(outcome.ok ? {} : { detail: outcome.error }) };
+}
+export function preludeWaiting(why) {
+    if (current?.status === "passed")
+        current = { ...current, waiting: why };
+}
+export function abandonPrelude() {
+    if (current?.status === "passed")
+        current = undefined;
+}
+export function pendingPrelude() {
+    return current && (current.status !== "passed" || current.waiting) ? current : undefined;
+}
+export function preludeOf(run, scenario) {
+    const kept = settled.get(run.id);
+    if (kept)
+        return kept;
+    if (current?.status !== "passed" || !scenario || current.finishedAt === undefined)
+        return undefined;
+    if (scenario.path !== current.scenario.path || scenario.name !== current.scenario.name || run.startedAt + 1000 < current.finishedAt)
+        return undefined;
+    const { waiting: _waiting, ...claimed } = current;
+    settled.set(run.id, claimed);
+    current = undefined;
+    return settled.get(run.id);
+}
+export function clearPreludes() {
+    settled.clear();
+    current = undefined;
+}