@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/src/tui/app.js

@@ -0,0 +1,483 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useCallback, useEffect, useState } from "react";
+import { Box, Text, useInput, useWindowSize } from "ink";
+import { featureControl, featureSelection, panelFeatures, panelRunsDirectory } from "@parity/product-lab/shell";
+import { discoverLogFiles, mentionedPaths, tailFile } from "@parity/product-lab/mcp/logs";
+import { chainDayWords, deleteWords, KEEP_TITLE, keepWords } from "@parity/product-lab/shell/words";
+import { stateBeforeLoad, startingHeader, startInput, Starting } from "./starting.js";
+import { Dot, Heading, KEYS, KeyBar, MARK, Rule } from "./frame.js";
+import { useAgentMenu } from "./agents-menu.js";
+import { useWheel, wheelKey } from "./mouse.js";
+import { Help, Logs, logsBackLimit, useBodyScroll } from "./scroll.js";
+import { chainRows, configRows, environmentRows, filterLines, filterScenarios, headerModel, historyRows, hostRows, labLogLines, peopleStorage, personRows, recordingsWords, reserveWords, runKeys, runModel, scenarioRows, } from "./model.js";
+const h = React.createElement;
+const STEP_MARK = { passed: ["✓", "green"], failed: ["✗", "red"], running: ["…", "yellow"], pending: ["·", "gray"], skipped: ["–", "gray"] };
+const RUN_COLOUR = { starting: "yellow", running: "yellow", paused: "yellow", stopping: "yellow", passed: "green", failed: "red", stopped: "gray" };
+function ChainList({ snapshot, now }) {
+    const rows = chainRows(snapshot, now);
+    if (!rows.length)
+        return h(Text, { dimColor: true }, "No chain is read yet.");
+    return h(Box, { flexDirection: "column" }, ...rows.map((row) => h(Box, { key: row.label, flexDirection: "column" }, h(Box, { columnGap: 1 }, h(Dot, { mark: row.mark }), h(Box, { width: 12, flexShrink: 0 }, h(Text, { wrap: "truncate-end" }, row.label)), h(Box, { flexShrink: 0 }, h(Text, null, row.best ?? "")), row.finalized ? h(Box, { flexShrink: 0 }, h(Text, { dimColor: true }, `final ${row.finalized}`)) : null), 
+    row.note ? h(Box, { paddingLeft: 2 }, h(Text, { color: row.mark === "failed" ? "red" : "yellow", wrap: "wrap" }, row.note)) : null)));
+}
+function PeopleList({ snapshot, now, selected, detail }) {
+    const rows = personRows(snapshot, now);
+    if (!rows.length)
+        return h(Text, { dimColor: true }, "Nobody yet. A scenario run, or n on the People screen (p), makes a person.");
+    return h(Box, { flexDirection: "column" }, ...rows.map((row, index) => h(Box, { key: row.id, flexDirection: "column" }, h(Box, { columnGap: 1 }, h(Box, { flexShrink: 0, columnGap: 1 }, h(Text, { color: "cyan" }, selected === index ? "›" : " "), h(Dot, { mark: row.mark })), h(Box, { width: 14, flexShrink: 0 }, h(Text, { wrap: "wrap" }, row.name)), h(Box, { width: 16, flexShrink: 0 }, h(Text, { wrap: "wrap" }, row.host)), h(Text, { wrap: "wrap", color: row.mark === "failed" ? "red" : undefined }, row.state)), detail ? h(Box, { paddingLeft: 4 }, h(Text, { dimColor: true, wrap: "wrap" }, row.origin)) : null)));
+}
+function SideText({ label, side }) {
+    if (!side)
+        return null;
+    return h(Text, { wrap: "wrap" }, `${label} `, h(Text, { color: side.ok ? "green" : "red" }, side.ok ? "✓" : "✗"), side.where && label === "chain" ? ` ${side.where}` : "");
+}
+function Step({ step, detail }) {
+    const [symbol, colour] = STEP_MARK[step.mark];
+    return h(Box, { flexDirection: "column" }, h(Box, { columnGap: 2 }, h(Text, { color: colour }, symbol), h(Box, { flexGrow: 1, flexShrink: 1 }, h(Text, { wrap: "wrap", dimColor: step.mark === "pending" }, step.text)), h(Box, { flexShrink: 0, columnGap: 2 }, h(SideText, { label: "screen", side: step.screen }), h(SideText, { label: "chain", side: step.chain }), step.took ? h(Text, { dimColor: true }, step.took) : null)), step.unchecked ? h(Box, { paddingLeft: 2 }, h(Text, { color: "yellow", wrap: "wrap" }, step.unchecked)) : null, step.error ? h(Box, { paddingLeft: 2 }, h(Text, { color: "red", wrap: "wrap" }, step.error)) : null, detail && step.screen?.detail ? h(Box, { paddingLeft: 2 }, h(Text, { color: "red", wrap: "wrap" }, `Screen: ${step.screen.detail}`)) : null, detail && step.chain?.detail ? h(Box, { paddingLeft: 2 }, h(Text, { color: "red", wrap: "wrap" }, `Chain: ${step.chain.detail}`)) : null, step.afterFailure ? h(Box, { paddingLeft: 2 }, h(Text, { wrap: "wrap" }, `What it sent: ${step.afterFailure}`)) : null);
+}
+function RunBlock({ run, detail }) {
+    if (!run)
+        return h(Text, { dimColor: true, wrap: "wrap" }, "No run yet. Run a scenario here (s, then r) or in the lab window.");
+    return h(Box, { flexDirection: "column" }, h(Text, { wrap: "wrap" }, h(Text, { bold: true }, run.title), ` · ${run.who} · `, h(Text, { color: RUN_COLOUR[run.state] }, run.when)), ...run.steps.map((step, index) => h(Box, { key: index, paddingLeft: 2 }, h(Step, { step, detail }))), run.error ? h(Box, { paddingLeft: 2 }, h(Text, { color: "red", wrap: "wrap" }, run.error)) : null, run.control ? h(Box, { paddingLeft: 2 }, h(Text, { wrap: "wrap" }, run.control)) : null, run.writes ? h(Box, { paddingLeft: 2 }, h(Text, { wrap: "wrap" }, run.writes)) : null);
+}
+function Home({ snapshot, now, url, wide, started }) {
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Box, { flexDirection: wide ? "row" : "column", columnGap: 4, rowGap: 1 }, h(Box, { flexDirection: "column", flexBasis: wide ? "45%" : undefined }, h(Heading, { title: "CHAINS" }), h(ChainList, { snapshot, now })), h(Box, { flexDirection: "column", flexGrow: 1 }, h(Heading, { title: "PEOPLE" }), h(PeopleList, { snapshot, now }))), h(Box, { flexDirection: "column" }, h(Heading, { title: "RUN" }), h(RunBlock, { run: runModel(snapshot, now, undefined, started), detail: false })), h(Text, { wrap: "wrap" }, h(Text, { bold: true }, "LAB WINDOW"), `  ${url}  `, h(Text, { dimColor: true }, "(o brings it forward)")));
+}
+function Chains({ snapshot, fixtures, now, selected }) {
+    const rows = environmentRows(snapshot, fixtures ?? [], now);
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: "CHAINS", right: "esc back   ↑↓ move" }), h(Box, { flexDirection: "column" }, ...rows.map((row, index) => h(Box, { key: row.id, flexDirection: "column" }, h(Box, { columnGap: 1 }, h(Box, { flexShrink: 0, columnGap: 1 }, h(Text, { color: "cyan" }, selected === index ? "›" : " "), h(Dot, { mark: row.mark })), h(Box, { width: 40, flexShrink: 0 }, h(Text, { bold: row.state === "running", wrap: "wrap" }, row.label)), h(Box, { flexShrink: 0 }, h(Text, { color: row.state === "running" ? "green" : "gray" }, row.state))), 
+    selected === index ? h(Box, { paddingLeft: 4 }, h(Text, { dimColor: true, wrap: "wrap" }, row.description)) : null, selected === index && row.switchWords ? h(Box, { paddingLeft: 4 }, h(Text, { color: row.canSwitch ? undefined : "gray", wrap: "wrap" }, row.switchWords)) : null, ...row.savedStates.map((state) => h(Box, { key: state.name, paddingLeft: 4, flexDirection: "column" }, h(Text, { wrap: "wrap" }, "↳ saved state ", h(Text, { bold: true }, state.name), " ", h(Text, { color: MARK[state.mark][1] }, state.state)), h(Box, { paddingLeft: 2 }, h(Text, { dimColor: true, wrap: "wrap" }, `${state.origin}${state.stored ? `; stored in ${state.stored}` : ""}`))))))), fixtures === undefined ? h(Text, { dimColor: true }, "Reading the saved states…") : null, h(ChainList, { snapshot, now }), h(Pace, { snapshot, now }), h(Keep, { snapshot }), h(Text, { wrap: "wrap" }, h(Text, { bold: true }, "s"), " switch to the chain marked ›   ", h(Text, { bold: true }, "x"), " reset the running chain (asks first)   ", h(Text, { bold: true }, "k"), " keep chain and people between starts, on or off"), h(Text, { dimColor: true, wrap: "wrap" }, "Build a saved state (b) and save the running chain's state (n): in the lab window's chain picker for now. Other kinds of chain (live network, copies of Paseo and Previewnet): g lists each with the lines that turn it on."));
+}
+function Pace({ snapshot, now }) {
+    const words = chainDayWords(snapshot?.chainDays, now, !!snapshot?.keepBetweenStarts?.running.keep);
+    if (!words)
+        return null;
+    return h(Box, { flexDirection: "column" }, h(Text, { wrap: "wrap", color: words.tone === "danger" ? "red" : words.tone === "warning" ? "yellow" : words.tone === "success" ? "green" : undefined }, words.line), words.kept ? h(Text, { color: "yellow", wrap: "wrap" }, words.kept) : null, words.turnOn ? h(Text, { color: "gray", wrap: "wrap" }, `Real time not set: ${words.turnOn}`) : null);
+}
+function Keep({ snapshot }) {
+    const view = snapshot?.keepBetweenStarts;
+    if (!view)
+        return null;
+    const words = keepWords(view);
+    return h(Box, { flexDirection: "column" }, h(Text, { wrap: "wrap" }, h(Text, { bold: true }, KEEP_TITLE), " ", h(Text, { color: words.on ? "green" : "gray" }, words.on ? "on" : "off"), words.locked ? h(Text, { color: "gray" }, ` (${words.locked})`) : null), h(Box, { paddingLeft: 2, flexDirection: "column" }, h(Text, { dimColor: true, wrap: "wrap" }, words.running), words.later ? h(Text, { color: "yellow", wrap: "wrap" }, words.later) : null, 
+    ...words.parts.map((part) => h(Text, { key: part.key, color: part.kept ? undefined : "gray", wrap: "wrap" }, `${part.kept ? "✓" : "–"} ${part.label}: ${part.words}`))));
+}
+function People({ snapshot, now, selected, picking, hostIndex }) {
+    const reserve = reserveWords(snapshot);
+    const hosts = hostRows(snapshot);
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: `PEOPLE on ${snapshot?.environment ?? "no chain"}`, right: "esc back   ↑↓ move" }), h(PeopleList, { snapshot, now, selected, detail: true }), picking
+        ? h(Box, { flexDirection: "column" }, h(Text, { bold: true }, "New person: pick a host (↑↓, ⏎ makes them, esc cancels)"), ...hosts.map((host, index) => h(Box, { key: `${host.id ?? host.label}`, columnGap: 1 }, h(Box, { flexShrink: 0 }, h(Text, { color: "cyan" }, hostIndex === index ? "›" : " ")), h(Box, { width: 32, flexShrink: 0 }, h(Text, { dimColor: !host.usable, wrap: "wrap" }, `${host.label}${host.isDefault ? " (default)" : ""}`)), h(Box, { flexShrink: 1, flexDirection: "column" }, h(Text, { dimColor: !host.usable, wrap: "wrap" }, host.description), host.note ? h(Text, { color: "gray", wrap: "wrap" }, host.note) : null))))
+        : h(Text, { wrap: "wrap" }, h(Text, { bold: true }, "n"), " new person (pick a host)   ", h(Text, { bold: true }, "d"), " remove the person marked › (asks first)"), reserve ? h(Text, { dimColor: true, wrap: "wrap" }, reserve) : null, h(Text, { dimColor: true, wrap: "wrap" }, peopleStorage(snapshot)));
+}
+function Scenarios({ rows, loading, selected, filter, filtering, open, height }) {
+    const room = Math.max(5, height);
+    const first = Math.min(Math.max(0, selected - Math.floor(room / 2)), Math.max(0, rows.length - room));
+    const shown = rows.slice(first, first + room);
+    const marked = rows[selected];
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: "SCENARIOS", right: "/ filter   ↑↓ move   ⏎ details   r run   esc back" }), filtering || filter ? h(Text, null, "Filter: ", h(Text, { color: "cyan" }, filter), filtering ? h(Text, { dimColor: true }, "▏ (⏎ keeps it, esc clears it)") : null) : null, loading ? h(Text, { dimColor: true }, "Reading the lab's scenarios…") : !rows.length ? h(Text, { dimColor: true }, filter ? "No scenario matches the filter." : "This lab has no scenario yet.") : null, h(Box, { flexDirection: "column" }, first > 0 ? h(Text, { dimColor: true }, `  ↑ ${first} more`) : null, ...shown.map((row, index) => {
+        const unrunnable = row.fit?.kind === "unrunnable";
+        const flags = [row.control ? "expected to fail" : "", row.rootCalls ? "root calls: asks first" : ""].filter(Boolean).join(", ");
+        return h(Box, { key: row.key, columnGap: 1 }, h(Box, { flexShrink: 0, columnGap: 1 }, h(Text, { color: "cyan" }, first + index === selected ? "›" : " "), h(Text, { color: unrunnable ? "gray" : "green" }, unrunnable ? "◌" : "●")), h(Box, { flexGrow: 1, flexShrink: 1 }, h(Text, { wrap: "wrap", dimColor: unrunnable }, row.title, flags ? h(Text, { color: "yellow" }, `  ${flags}`) : "")), h(Box, { width: 9, flexShrink: 0 }, h(Text, { dimColor: true }, row.people)), h(Box, { width: 26, flexShrink: 0 }, h(Text, { wrap: "wrap", color: row.fit?.kind === "switch" ? "yellow" : unrunnable ? "gray" : undefined, dimColor: !row.fit }, row.fit?.chip ?? "any chain")));
+    }), first + room < rows.length ? h(Text, { dimColor: true }, `  ↓ ${rows.length - first - room} more`) : null), marked && (open || marked.fit?.kind !== undefined && marked.fit.kind !== "here")
+        ? h(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1 }, h(Text, { bold: true, wrap: "wrap" }, marked.title), h(Text, { dimColor: true, wrap: "wrap" }, `${marked.where} · ${marked.people}${marked.control ? " · a negative control: it must fail, at its step and for its reason" : ""}`), marked.fit && marked.fit.kind !== "here" ? h(Text, { wrap: "wrap", color: marked.fit.kind === "unrunnable" ? "gray" : "yellow" }, marked.fit.title) : null, ...(open ? marked.steps.map((step, index) => h(Text, { key: index, wrap: "wrap" }, step)) : []))
+        : null);
+}
+function Run({ snapshot, now, runKey, started }) {
+    const keys = runKeys(snapshot);
+    const run = runModel(snapshot, now, runKey, started);
+    const at = run ? keys.indexOf(run.key) : -1;
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: runKey ? "RUN (picked in History)" : "RUN (the latest)", right: `${keys.length > 1 ? `← older  → newer (${at + 1} of ${keys.length})   ` : ""}esc back` }), h(RunBlock, { run, detail: true }));
+}
+function History({ snapshot, now, selected, recordings, started }) {
+    const rows = historyRows(snapshot, now, started);
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: "HISTORY", right: "↑↓ move   ⏎ open   esc back" }), rows.length
+        ? h(Box, { flexDirection: "column" }, ...rows.map((run, index) => h(Box, { key: run.key, columnGap: 1 }, h(Box, { flexShrink: 0, columnGap: 1 }, h(Text, { color: "cyan" }, index === selected ? "›" : " "), h(Text, { color: RUN_COLOUR[run.state] }, STEP_MARK[run.state === "passed" ? "passed" : run.state === "failed" ? "failed" : run.state === "stopped" ? "skipped" : "running"][0])), h(Box, { flexGrow: 1, flexShrink: 1 }, h(Text, { wrap: "wrap" }, run.title, h(Text, { dimColor: true }, ` · ${run.who}`))), h(Box, { flexShrink: 0 }, h(Text, { color: RUN_COLOUR[run.state] }, run.when)))))
+        : h(Text, { dimColor: true }, "No run in this session yet."), h(Text, { dimColor: true, wrap: "wrap" }, `This session's runs. ${recordingsWords(recordings)}`));
+}
+function Config({ rows, selected, height }) {
+    const marked = rows[selected];
+    const room = Math.max(3, height);
+    const first = Math.min(Math.max(0, selected - Math.floor(room / 2)), Math.max(0, rows.length - room));
+    const shown = rows.slice(first, first + room);
+    return h(Box, { flexDirection: "column", rowGap: 1 }, h(Heading, { title: "CONFIG", right: "↑↓ move   esc back" }), h(Text, { dimColor: true, wrap: "wrap" }, "What this lab's config turns on. Off ones are greyed with the lines that turn them on (docs/feature-map.md)."), h(Box, { flexDirection: "column" }, first > 0 ? h(Text, { dimColor: true }, `  ↑ ${first} more`) : null, ...shown.map((row, index) => h(Box, { key: row.name, columnGap: 1 }, h(Box, { flexShrink: 0, columnGap: 1 }, h(Text, { color: "cyan" }, first + index === selected ? "›" : " "), h(Text, { color: row.on ? "green" : "gray" }, row.on ? "●" : "○")), h(Box, { width: 38, flexShrink: 0 }, h(Text, { wrap: "wrap", dimColor: !row.on }, row.name)), h(Box, { flexShrink: 1 }, h(Text, { wrap: "wrap", dimColor: !row.on }, row.value)))), first + room < rows.length ? h(Text, { dimColor: true }, `  ↓ ${rows.length - first - room} more`) : null), marked
+        ? h(Box, { flexDirection: "column", borderStyle: "round", borderColor: "gray", paddingX: 1 }, h(Text, { bold: true, wrap: "wrap" }, marked.name), h(Text, { wrap: "wrap" }, `Why: ${marked.why}`), !marked.on && marked.turnOn ? h(Text, { color: "yellow", wrap: "wrap" }, `Turn it on: ${marked.turnOn}`) : null)
+        : null);
+}
+const message = (error) => (error instanceof Error ? error.message : String(error));
+export function LabApp(props) {
+    const clock = props.clock ?? Date.now;
+    const [screen, setScreen] = useState(props.screen ?? "home");
+    const [, setTick] = useState(0);
+    const [fixtures, setFixtures] = useState();
+    const [chainIndex, setChainIndex] = useState(0);
+    const [personIndex, setPersonIndex] = useState(0);
+    const [picking, setPicking] = useState(false);
+    const [hostIndex, setHostIndex] = useState(0);
+    const [prompt, setPrompt] = useState();
+    const [status, setStatus] = useState();
+    const [listing, setListing] = useState();
+    const [scenarioIndex, setScenarioIndex] = useState(0);
+    const [filter, setFilter] = useState("");
+    const [filtering, setFiltering] = useState(false);
+    const [details, setDetails] = useState(false);
+    const [runKey, setRunKey] = useState();
+    const [started] = useState(() => new Map());
+    const [historyIndex, setHistoryIndex] = useState(0);
+    const [configIndex, setConfigIndex] = useState(0);
+    const [recordings, setRecordings] = useState();
+    const [heard, setHeard] = useState([]);
+    const [logFiles, setLogFiles] = useState();
+    const [logIndex, setLogIndex] = useState(0);
+    const [logFilter, setLogFilter] = useState("");
+    const [logBack, setLogBack] = useState(0);
+    const measured = useWindowSize();
+    const { columns, rows: terminalRows } = props.size ?? measured;
+    const width = Math.max(20, columns - 1);
+    const height = Math.max(8, terminalRows || 24);
+    useEffect(() => {
+        const unsubscribe = props.runtime.subscribe((event) => {
+            setTick((tick) => tick + 1);
+            if (event.type === "environment-switched" || event.type === "environment-reset") {
+                setFixtures(undefined);
+                setLogFiles(undefined);
+            }
+            const line = event.type === "environment-progress" ? `${event.environment}: ${event.message}` : event.type === "app-build" ? event.message : event.type === "environment-start-failed" ? `Could not start ${event.environment}: ${event.error}` : event.type === "recording-failed" ? `Could not record “${event.title}”: ${event.error}` : undefined;
+            if (line)
+                setHeard((lines) => [...lines.slice(-499), { at: Date.now(), line }]);
+        });
+        const refresh = props.refreshMs ?? 1000;
+        const timer = refresh > 0 ? setInterval(() => setTick((tick) => tick + 1), refresh) : undefined;
+        return () => {
+            unsubscribe();
+            if (timer)
+                clearInterval(timer);
+        };
+    }, [props.runtime, props.refreshMs]);
+    useEffect(() => {
+        if (screen !== "chains" || fixtures !== undefined)
+            return;
+        let current = true;
+        props.runtime.fixtures().then((list) => { if (current)
+            setFixtures(list); }, () => { if (current)
+            setFixtures([]); });
+        return () => { current = false; };
+    }, [screen, fixtures, props.runtime]);
+    useEffect(() => {
+        if (screen !== "scenarios" || listing !== undefined)
+            return;
+        let current = true;
+        props.runtime.features({ read: true, inspect: true }).then((read) => { if (current)
+            setListing(read); }, (error) => { if (current) {
+            setListing(null);
+            setStatus({ text: `Could not read the scenarios: ${message(error)}`, failed: true });
+        } });
+        return () => { current = false; };
+    }, [screen, listing, props.runtime]);
+    useEffect(() => {
+        if ((screen !== "history" && screen !== "config") || recordings !== undefined)
+            return;
+        let current = true;
+        props.runtime.recordings().then((listing) => { if (current)
+            setRecordings(listing); }, (error) => { if (current)
+            setStatus({ text: `Could not read the recordings: ${message(error)}`, failed: true }); });
+        return () => { current = false; };
+    }, [screen, recordings, props.runtime]);
+    useEffect(() => {
+        if (screen !== "logs" || logFiles !== undefined)
+            return;
+        try {
+            const current = props.runtime.snapshot();
+            setLogFiles(discoverLogFiles([...mentionedPaths(current.provenance), ...(current.workspace ? [current.workspace.directory] : [])]));
+        }
+        catch {
+            setLogFiles([]);
+        }
+    }, [screen, logFiles, props.runtime]);
+    useEffect(() => {
+        if (screen === "config" && fixtures === undefined)
+            props.runtime.fixtures().then(setFixtures, () => setFixtures([]));
+    }, [screen, fixtures, props.runtime]);
+    let snapshot;
+    try {
+        snapshot = props.runtime.snapshot();
+    }
+    catch {
+        snapshot = undefined;
+    }
+    const now = clock();
+    const shown = headerModel(props.runtime.lab?.name ?? props.lab, snapshot, stateBeforeLoad(() => props.runtime.environmentState()), now);
+    const header = props.start ? startingHeader(shown, props.start) : shown;
+    const logSources = ["The lab", ...(logFiles ?? []).map((file) => file.name)];
+    const logSource = Math.min(logIndex, logSources.length - 1);
+    let logLines = [];
+    if (screen === "logs") {
+        const file = logSource > 0 ? logFiles?.[logSource - 1] : undefined;
+        try {
+            logLines = filterLines(file ? tailFile(file.path, 400).lines : labLogLines(snapshot, [...(props.log?.() ?? []), ...heard]), logFilter);
+        }
+        catch (error) {
+            logLines = [`Could not read ${file?.path ?? "the lab's lines"}: ${message(error)}`];
+        }
+    }
+    const scenarios = filterScenarios(scenarioRows(snapshot, listing ? panelFeatures(listing) : []), filter);
+    const start = async (row) => {
+        if (row.run.kind === "feature" && listing) {
+            const control = featureControl(listing, row.run.path, { name: row.run.name });
+            const handle = await props.runtime.runFeatures({
+                ...featureSelection(listing, { path: row.run.path, name: row.run.name }),
+                runsDirectory: panelRunsDirectory(props.runtime),
+                label: "terminal",
+                inProcess: { bindings: {}, pauseAfterStep: false, breakpoints: true },
+                ...(control ? { control } : {}),
+            });
+            started.set(handle.id, row.title);
+        }
+        else if (row.run.kind === "configured") {
+            const people = personRows(snapshot, now);
+            const person = people[personIndex]?.mark === "ok" ? people[personIndex] : people.find((row) => row.mark === "ok");
+            if (!row.run.actors && !person)
+                throw new Error("Nobody is ready to run it: make a person first (p, then n)");
+            const request = { scenario: row.run.id, ...(row.run.actors ? {} : { actor: person.id }), checkpointMode: false };
+            if (props.runtime.startScenario)
+                await props.runtime.startScenario(request);
+            else
+                props.runtime.runScenario(request);
+        }
+        setScreen("run");
+        return `Started “${row.title}”.`;
+    };
+    const runRow = (row) => {
+        if (!row)
+            return setStatus({ text: "Pick a scenario with ↑↓ first.", failed: true });
+        if (row.fit?.kind === "unrunnable")
+            return setStatus({ text: row.fit.title, failed: true });
+        if (row.fit?.kind === "switch" && row.fit.target) {
+            const plan = snapshot?.switchPlans[row.fit.target];
+            if (!plan?.allowed)
+                return setStatus({ text: plan?.reason || `It runs on ${row.fit.target}, which cannot be switched to now.`, failed: true });
+            return setPrompt({
+                question: `“${row.title}” runs on ${plan.targetLabel}, not here. Switch to it first? ${plan.consequences.join(" ")} y switches and runs it, any other key stays.`,
+                yes: async () => {
+                    await props.runtime.switchEnvironment({ environment: plan.target, ...(plan.confirmation ? { confirmation: plan.confirmation } : {}) });
+                    setListing(undefined);
+                    return start(row);
+                },
+            });
+        }
+        const rootCalls = snapshot?.rootCalls;
+        if (row.rootCalls && rootCalls && !rootCalls.confirmed) {
+            const token = snapshot?.confirmations.rootCalls;
+            if (!token)
+                return setStatus({ text: "This chain's root calls cannot be confirmed here.", failed: true });
+            return setPrompt({
+                question: `“${row.title}” makes root calls: sudo on this local copy (${rootCalls.allowed.join(", ")}), with its development key; a public network is always refused. Allow them for this session? y allows and runs it, any other key stays.`,
+                yes: async () => {
+                    props.runtime.allowRootCalls({ confirmation: token });
+                    return start(row);
+                },
+            });
+        }
+        act(`Starting “${row.title}”…`, () => start(row));
+    };
+    const agentMenu = useAgentMenu(props.agents, (text, failed) => setStatus(failed ? { text, failed } : { text }), props.mouse);
+    const pane = useBodyScroll(`${screen}${props.start ? " start" : ""}${agentMenu.open ? " agents" : ""}`);
+    const logsHeight = (terminalRows || 40) - 12;
+    const pickLog = (index) => { setLogIndex(index); setLogBack(0); };
+    const act = useCallback((doing, work) => {
+        setStatus({ text: doing });
+        work().then((done) => setStatus(done ? { text: done } : undefined), (error) => setStatus({ text: message(error), failed: true }));
+    }, []);
+    const onKey = (input, key) => {
+        if (prompt) {
+            setPrompt(undefined);
+            if (input === "y")
+                act("Working…", prompt.yes);
+            else
+                setStatus({ text: "Nothing changed." });
+            return;
+        }
+        if (picking) {
+            const hosts = hostRows(snapshot);
+            if (key.escape)
+                setPicking(false);
+            else if (key.upArrow)
+                setHostIndex((index) => Math.max(0, index - 1));
+            else if (key.downArrow)
+                setHostIndex((index) => Math.min(hosts.length - 1, index + 1));
+            else if (key.return) {
+                const host = hosts[hostIndex];
+                if (!host?.usable || !host.id) {
+                    setStatus({ text: host?.note ?? "That host cannot be used here.", failed: true });
+                    return;
+                }
+                setPicking(false);
+                act(`Making a new person on ${host.label}…`, async () => `Made ${(await props.runtime.createActor({ host: host.id })).name} on ${host.label}.`);
+            }
+            return;
+        }
+        if (filtering) {
+            const set = screen === "logs" ? setLogFilter : setFilter;
+            if (screen === "logs")
+                setLogBack(0);
+            if (key.escape) {
+                set("");
+                setFiltering(false);
+            }
+            else if (key.return)
+                setFiltering(false);
+            else if (key.backspace || key.delete)
+                set((text) => text.slice(0, -1));
+            else if (input && !key.ctrl && !key.meta) {
+                set((text) => text + input);
+                setScenarioIndex(0);
+            }
+            return;
+        }
+        const scrolled = key.upArrow ? -1 : key.downArrow ? 1 : 0;
+        if (scrolled && !agentMenu.open && screen === "logs")
+            return setLogBack((back) => Math.max(0, Math.min(logsBackLimit(logLines.length, logsHeight), back - scrolled)));
+        if (scrolled && !agentMenu.open && (props.start || screen === "home" || screen === "run" || screen === "help"))
+            return pane.scroll(scrolled);
+        if (props.start)
+            return startInput(input, key, { start: props.start, screen, setScreen, setFiltering, setLogIndex: pickLog, logSource, logSources: logSources.length, quit: props.quit, ask: setPrompt });
+        if (agentMenu.input(input, key))
+            return;
+        if (input === "a")
+            return agentMenu.show();
+        const target = KEYS.find(([letter]) => letter === input)?.[2];
+        if (screen === "scenarios") {
+            if (input === "/")
+                return setFiltering(true);
+            if (key.upArrow)
+                return setScenarioIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                return setScenarioIndex((index) => Math.min(scenarios.length - 1, index + 1));
+            if (key.return)
+                return setDetails((open) => !open);
+            if (input === "r")
+                return runRow(scenarios[scenarioIndex]);
+        }
+        if (screen === "history") {
+            const rows = historyRows(snapshot, now);
+            if (key.upArrow)
+                return setHistoryIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                return setHistoryIndex((index) => Math.min(rows.length - 1, index + 1));
+            if (key.return && rows[historyIndex]) {
+                setRunKey(rows[historyIndex].key);
+                return setScreen("run");
+            }
+        }
+        if (screen === "run" && (key.leftArrow || key.rightArrow)) {
+            const keys = runKeys(snapshot);
+            const at = keys.indexOf(runModel(snapshot, now, runKey)?.key ?? "");
+            const next = key.leftArrow ? Math.min(keys.length - 1, at + 1) : Math.max(0, at - 1);
+            return setRunKey(next === 0 ? undefined : keys[next]);
+        }
+        if (screen === "config") {
+            if (key.upArrow)
+                return setConfigIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                return setConfigIndex((index) => Math.min(configRows(snapshot, fixtures, recordings, props.hostLog).length - 1, index + 1));
+        }
+        if (screen === "logs") {
+            if (input === "/")
+                return setFiltering(true);
+            if (key.leftArrow)
+                return pickLog(Math.max(0, logSource - 1));
+            if (key.rightArrow)
+                return pickLog(Math.min(logSources.length - 1, logSource + 1));
+        }
+        if (key.escape)
+            return setScreen("home");
+        if (input === "q" && props.attached)
+            return setPrompt({ question: "Leave? The lab window keeps running (it is another process's; stop it there). y leaves, any other key stays.", yes: async () => { props.quit(); return "Leaving…"; } });
+        if (input === "q")
+            return setPrompt({ question: "Stop the lab? Its window, people and chains stop too (a kept chain is kept). y stops, any other key stays.", yes: async () => { props.quit(); return "Stopping the lab…"; } });
+        if (input === "o")
+            return act("Bringing the lab window forward…", props.openWindow);
+        if (screen === "chains") {
+            const rows = environmentRows(snapshot, fixtures ?? [], now);
+            if (key.upArrow)
+                return setChainIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                return setChainIndex((index) => Math.min(rows.length - 1, index + 1));
+            if (input === "s") {
+                const row = rows[chainIndex];
+                if (!row || !row.canSwitch)
+                    return setStatus({ text: row?.state === "running" ? `${row.label} is the running chain.` : (row?.switchWords ?? "Pick a chain with ↑↓ first."), failed: true });
+                const plan = snapshot?.switchPlans[row.id];
+                return setPrompt({
+                    question: `Switch to ${row.label}? ${row.switchWords ?? ""} y switches, any other key stays.`,
+                    yes: async () => {
+                        await props.runtime.switchEnvironment({ environment: row.id, ...(plan?.confirmation ? { confirmation: plan.confirmation } : {}) });
+                        return `Now running ${row.label}.`;
+                    },
+                });
+            }
+            if (input === "k") {
+                if (props.attached)
+                    return setStatus({ text: `${KEEP_TITLE} is the lab window's switch: turn it there.`, failed: true });
+                const view = snapshot?.keepBetweenStarts;
+                if (!view)
+                    return setStatus({ text: "No chain runs: start one to see what it keeps between starts.", failed: true });
+                const words = keepWords(view);
+                if (words.locked)
+                    return setStatus({ text: words.locked, failed: true });
+                return act(`Turning ${KEEP_TITLE.toLowerCase()} ${words.on ? "off" : "on"}…`, async () => {
+                    await props.runtime.settings().write({ keepBetweenStarts: !words.on });
+                    return `${KEEP_TITLE}: ${words.on ? "off" : "on"} from the next start (the lab window's switch too).`;
+                });
+            }
+            if (input === "x") {
+                const token = snapshot?.confirmations.reset;
+                if (!snapshot?.capabilities.reset || !token)
+                    return setStatus({ text: "This chain cannot be reset here.", failed: true });
+                return setPrompt({ question: `Reset ${snapshot.environment}? Its chain state and people are thrown away and it starts fresh. y resets, any other key stays.`, yes: async () => { await props.runtime.resetEnvironment({ confirmation: token }); return `${snapshot.environment} was reset.`; } });
+            }
+        }
+        if (screen === "people") {
+            const rows = personRows(snapshot, now);
+            if (key.upArrow)
+                return setPersonIndex((index) => Math.max(0, index - 1));
+            if (key.downArrow)
+                return setPersonIndex((index) => Math.min(rows.length - 1, index + 1));
+            if (input === "n") {
+                const hosts = hostRows(snapshot);
+                setHostIndex(Math.max(0, hosts.findIndex((host) => host.isDefault)));
+                return setPicking(true);
+            }
+            if (input === "d") {
+                const row = rows[personIndex];
+                const token = row && snapshot?.confirmations.deleteIdentity[row.id];
+                if (!row || !token)
+                    return setStatus({ text: row ? `${row.name} cannot be removed here.` : "Pick a person with ↑↓ first.", failed: true });
+                const words = deleteWords(row.name, snapshot?.keepBetweenStarts);
+                return setPrompt({ question: `${words.title} ${words.consequence} y deletes, any other key stays.`, yes: async () => { await props.runtime.manageActor({ action: "delete", actor: row.id, confirmation: token, from: "terminal" }); return `Removed ${row.name}.`; } });
+            }
+        }
+        if (target) {
+            setStatus(undefined);
+            if (target === "run")
+                setRunKey(undefined);
+            setScreen(target === screen ? "home" : target);
+        }
+    };
+    useInput(onKey);
+    useWheel(props.mouse, (turn) => { if (!prompt)
+        onKey("", wheelKey(turn)); });
+    const body = agentMenu.node ?? (props.start && screen !== "logs" ? h(Starting, { start: props.start, now })
+        : screen === "home" ? h(Home, { snapshot, now, url: props.url, wide: width >= 100, started })
+            : screen === "chains" ? h(Chains, { snapshot, fixtures, now, selected: chainIndex })
+                : screen === "people" ? h(People, { snapshot, now, selected: personIndex, picking, hostIndex })
+                    : screen === "run" ? h(Run, { snapshot, now, runKey, started })
+                        : screen === "history" ? h(History, { snapshot, now, selected: historyIndex, recordings, started })
+                            : screen === "config" ? h(Config, { rows: configRows(snapshot, fixtures, recordings, props.hostLog), selected: configIndex, height: (terminalRows || 40) - 18 })
+                                : screen === "logs" ? h(Logs, { source: logSources[logSource], sources: logSources.length, index: logSource, lines: logLines, filter: logFilter, filtering, height: logsHeight, back: logBack })
+                                    : screen === "scenarios" ? h(Scenarios, { rows: scenarios, loading: listing === undefined, selected: Math.min(scenarioIndex, Math.max(0, scenarios.length - 1)), filter, filtering, open: details, height: (terminalRows || 40) - 16 })
+                                        : h(Help, { short: height < 30 }));
+    return h(Box, { flexDirection: "column", width: "100%", paddingRight: 1, height, overflow: "hidden" }, 
+    h(Box, { flexShrink: 0 }, h(Box, { flexShrink: 0 }, h(Text, { bold: true }, `product-lab · ${header.lab}`)), h(Box, { flexGrow: 1, flexShrink: 1, justifyContent: "flex-end", overflow: "hidden", marginLeft: 2 }, h(Text, { wrap: "truncate-end" }, header.environment)), h(Box, { flexShrink: 0 }, h(Text, {}, " · ", h(Text, { color: MARK[header.mark][1] }, header.state)))), h(Rule), 
+    h(Box, { ref: pane.outer, flexDirection: "column", flexGrow: 1, flexShrink: 1, overflow: "hidden" }, h(Box, { ref: pane.inner, flexDirection: "column", flexShrink: 0, marginTop: -pane.offset }, body)), prompt ? h(Box, { flexShrink: 0 }, h(Text, { color: "yellow", wrap: "wrap" }, prompt.question)) : status ? h(Box, { flexShrink: 0 }, h(Text, { color: status.failed ? "red" : "cyan", wrap: "wrap" }, status.text)) : null, h(Rule), h(KeyBar, { screen, start: props.start }));
+}

package/entrypoints/cli/src/tui/frame.d.ts

@@ -0,0 +1,23 @@
+import { type ReactElement } from "react";
+import { type StartView } from "./starting.js";
+import type { Mark } from "./model.js";
+export type Screen = "home" | "chains" | "people" | "run" | "scenarios" | "history" | "config" | "logs" | "help";
+/** The keys on every screen, in the key bar's order: the letter, its word, and the screen it opens (none: an action). */
+export declare const KEYS: readonly (readonly [string, string, Screen | undefined])[];
+/** A line across the box: its top border, laid out with the box, so a resize never draws one of the old width. */
+export declare function Rule(): ReactElement;
+/** The keys at the bottom; while the lab starts, only the start's (`startKeys`). */
+export declare function KeyBar({ screen, start }: {
+    screen: Screen;
+    start?: StartView | undefined;
+}): ReactElement;
+/** A state's mark and colour: running, busy, off, failed. */
+export declare const MARK: Record<Mark, [string, string]>;
+export declare function Dot({ mark }: {
+    mark: Mark;
+}): import("react").FunctionComponentElement<import("ink").TextProps>;
+/** A screen's title, and its keys on the right. */
+export declare function Heading({ title, right }: {
+    title: string;
+    right?: string;
+}): ReactElement;

package/entrypoints/cli/src/tui/frame.js

@@ -0,0 +1,24 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createElement as h } from "react";
+import { Box, Text } from "ink";
+import { startKeys } from "./starting.js";
+export const KEYS = [
+    ["c", "chains", "chains"], ["p", "people", "people"], ["s", "scenarios", "scenarios"], ["r", "run", "run"], ["h", "history", "history"],
+    ["g", "config", "config"], ["l", "logs", "logs"], ["o", "window", undefined], ["a", "agent", undefined], ["?", "help", "help"], ["q", "quit", undefined],
+];
+export function Rule() {
+    return h(Box, { flexShrink: 0, borderStyle: "single", borderTop: true, borderBottom: false, borderLeft: false, borderRight: false, borderDimColor: true });
+}
+export function KeyBar({ screen, start }) {
+    const keys = start ? startKeys(KEYS, start) : KEYS;
+    return h(Box, { flexWrap: "wrap", columnGap: 2, flexShrink: 0 }, ...keys.map(([key, label, target]) => h(Text, { key }, h(Text, { bold: true, color: target === screen ? "cyan" : undefined }, key), ` ${label}`)));
+}
+export const MARK = { ok: ["●", "green"], busy: ["◐", "yellow"], off: ["○", "gray"], failed: ["✗", "red"] };
+export function Dot({ mark }) {
+    const [symbol, colour] = MARK[mark];
+    return h(Text, { color: colour }, symbol);
+}
+export function Heading({ title, right }) {
+    return h(Box, { justifyContent: "space-between" }, h(Text, { bold: true }, title), right ? h(Text, { dimColor: true }, right) : null);
+}