@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/panel/src/client/environment-lifecycle.d.ts

@@ -0,0 +1,19 @@
+import type { LabSnapshot } from "@parity/product-lab/ports/driving";
+interface Options {
+    request(path: string, input?: unknown): Promise<unknown>;
+    snapshot(): LabSnapshot | undefined;
+    refresh(): Promise<void>;
+    error(error: unknown): void;
+    /** Open the recorded runs (Phase 9: they stay readable while the environment is stopped). */
+    recordings?(): void;
+}
+/** Existing runtime lifecycle, separate from the snapshot that exists only while running. */
+export declare function createEnvironmentLifecycle(options: Options): {
+    poll(): Promise<boolean>;
+    sync(): void;
+    restart: () => void;
+    /** Whether Restart can work here: the lab can start what it stops (an attached runtime's owner restarts it). */
+    readonly canRestart: boolean;
+    readonly online: boolean;
+};
+export {};

package/entrypoints/panel/src/client/environment-lifecycle.js

@@ -0,0 +1,164 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { button as uiButton, empty, h, patchChildren } from "./ui.js";
+import { unawaited } from "./unawaited.js";
+import { findById, labQuery, labQueryAll, showModal } from "./lab-document.js";
+import { replaceKeptNotice } from "./replace-kept.js";
+export function createEnvironmentLifecycle(options) {
+    const panel = document.createElement("div");
+    panel.id = "environment-lifecycle";
+    panel.className = "environment-lifecycle";
+    const status = document.createElement("span");
+    status.id = "environment-state";
+    status.setAttribute("role", "status");
+    status.className = "ui-chip ui-chip--neutral";
+    const start = uiButton("Start", { icon: "play", size: "sm", variant: "primary", id: "environment-start" });
+    const stop = uiButton("Stop", { icon: "stop", size: "sm", id: "environment-stop" });
+    panel.append(status, start, stop);
+    (findById("environment-lifecycle-slot") ?? labQuery('[data-section="environment"].drawer-pane')).append(panel);
+    const cover = document.createElement("div");
+    cover.id = "environment-offline";
+    cover.hidden = true;
+    document.querySelector(".workspace").append(cover);
+    const inactive = document.createElement("p");
+    inactive.id = "environment-observations-unavailable";
+    inactive.className = "muted";
+    inactive.hidden = true;
+    inactive.textContent = "No live chain observations while the environment is stopped. Displayed history belongs to the previous session; receipts may no longer be available.";
+    findById("chain-activity").before(inactive);
+    let state, pending = false;
+    const later = unawaited(options.error);
+    const disabled = new Map();
+    function render(next) {
+        state = next;
+        const tone = next.state === "running" ? "success" : next.state === "stopped" ? (next.lastFailure ? "danger" : "neutral") : "accent";
+        status.className = `ui-chip ui-chip--${tone}${next.state === "starting" ? " is-pulsing" : ""}`;
+        patchChildren(status, [...(next.state === "stopped" && !next.lastFailure ? [] : [h("span", { class: "ui-dot" })]), next.state]);
+        status.title = next.state === "stopped" ? (next.lastFailure ? `Stopped: ${next.lastFailure.error}` : "Stopped") : `${next.state === "running" ? "Running" : "Starting"} · ${next.environment}`;
+        status.dataset.state = next.state;
+        start.disabled = pending || !next.canStart || next.state !== "stopped";
+        start.title = next.canStart ? "Start the configured environment. A persistent environment resumes its saved state." : "This attached runtime has no restart declaration; restart its owner";
+        start.hidden = next.state === "running";
+        const snapshot = options.snapshot();
+        const activeRun = snapshot?.jobs.some(job => ["queued", "running", "paused"].includes(job.status)) || ["queued", "running"].includes(snapshot?.featureRun?.status ?? "");
+        stop.disabled = pending || next.state !== "running" || !!activeRun;
+        stop.title = activeRun ? "Finish or cancel the current run before stopping" : snapshot?.retention?.reason ? `Stop the environment's owned processes. ${snapshot.retention.reason}` : "Stop the environment's owned processes";
+        stop.hidden = next.state !== "running";
+        const online = next.state === "running";
+        const live = findById("live-status");
+        if (live)
+            live.hidden = !online;
+        document.body.dataset.environmentState = next.state;
+        cover.hidden = online;
+        inactive.hidden = online;
+        if (next.state === "stopped")
+            findById("application").replaceChildren();
+        if (cover.dataset.state !== next.state) {
+            cover.dataset.state = next.state;
+            delete cover.dataset.replaceKept;
+            cover.replaceChildren(next.state === "starting"
+                ? empty({ icon: "clock", title: "Starting the environment…", body: "The app opens when its chains are ready." })
+                : empty({ icon: "chain", title: "Environment stopped", body: "Its apps open again once it runs.", action: uiButton("Start environment", { icon: "play", variant: "primary", onClick: () => start.click() }) }));
+            if (next.state === "stopped" && options.recordings)
+                cover.append(uiButton("Recorded runs", { icon: "history", id: "environment-offline-recordings", onClick: () => options.recordings() }));
+        }
+        const refused = next.state === "stopped" ? next.lastFailure : undefined;
+        const replaceKey = refused?.chainDayEnded?.kept ? `${refused.environment}:${refused.at}` : "";
+        if ((cover.dataset.replaceKept ?? "") !== replaceKey) {
+            cover.dataset.replaceKept = replaceKey;
+            cover.querySelector("[data-replace-kept]")?.remove();
+            const notice = refused ? replaceKeptNotice(refused.chainDayEnded, () => later(perform("/api/environment-start", { environment: refused.environment, replaceKept: true }))) : null;
+            if (notice)
+                cover.prepend(notice);
+        }
+        cover.querySelector("#replace-kept-chain")?.toggleAttribute("disabled", pending);
+        cover.querySelector(".ui-empty .ui-button")?.toggleAttribute("disabled", start.disabled);
+        if (!online) {
+            findById("compact-progress").textContent = next.state === "starting" ? "Starting environment" : "Environment stopped";
+            findById("compact-progress").dataset.compact = next.state === "starting" ? "Starting" : "Stopped";
+            for (const control of labQueryAll('.drawer-pane button, .drawer-footer button, #dock-run, #dock-stop')) {
+                if (panel.contains(control))
+                    continue;
+                if (control.closest("#recordings"))
+                    continue;
+                if (control.closest("#builder") && !control.matches("#builder-run, #builder-continue, #builder-step, #builder-pause-now, #builder-cancel"))
+                    continue;
+                if (!disabled.has(control))
+                    disabled.set(control, control.disabled);
+                control.disabled = true;
+            }
+        }
+        else {
+            for (const [control, value] of disabled)
+                control.disabled = value;
+            disabled.clear();
+        }
+    }
+    async function perform(path, input) {
+        if (pending)
+            return false;
+        pending = true;
+        if (state)
+            render(state);
+        try {
+            render(await options.request(path, input));
+            await options.refresh();
+            return true;
+        }
+        catch (error) {
+            options.error(error);
+            return false;
+        }
+        finally {
+            pending = false;
+            if (state)
+                render(state);
+        }
+    }
+    start.onclick = () => { const environment = options.snapshot()?.selectedEnvironment; later(perform("/api/environment-start", environment ? { environment } : {})); };
+    const restart = () => {
+        if (state?.state === "stopped")
+            return start.click();
+        const snapshot = options.snapshot();
+        if (!snapshot)
+            return;
+        const label = snapshot.environment;
+        const disposable = snapshot.retention.retention === "disposable";
+        const dismiss = uiButton("Keep running");
+        const confirm = uiButton(disposable ? `Restart ${label} from scratch` : `Restart ${label}`, { variant: disposable ? "danger" : "primary", id: "environment-restart-confirm" });
+        const dialog = h("dialog", { "aria-label": "Restart environment" }, h("h1", {}, `Restart ${label}?`), h("p", {}, disposable ? "It stops and starts again; its chain state is discarded. This cannot be undone." : "Owned processes stop and start again; saved state stays. External services stay under their owner's control."), h("div", { class: "actions" }, dismiss, confirm));
+        dismiss.onclick = () => dialog.close();
+        confirm.onclick = () => {
+            dialog.close();
+            const environment = snapshot.selectedEnvironment;
+            later((async () => { if (await perform("/api/environment-stop", { session: snapshot.environmentId, discard: disposable }))
+                await perform("/api/environment-start", environment ? { environment } : {}); })());
+        };
+        dialog.addEventListener("close", () => dialog.remove());
+        showModal(dialog);
+        dismiss.focus();
+    };
+    stop.onclick = () => {
+        const snapshot = options.snapshot();
+        if (!snapshot)
+            return;
+        const label = snapshot.environment;
+        const disposable = snapshot.retention.retention === "disposable";
+        const dismiss = uiButton("Keep running");
+        const confirm = uiButton(disposable ? `Stop and discard ${label}` : `Stop ${label}`, { variant: disposable ? "danger" : "primary", id: "environment-stop-confirm" });
+        const dialog = h("dialog", { "aria-label": "Stop environment" }, h("h1", {}, `Stop ${label}?`), h("p", {}, disposable ? "Its chain state will be discarded. This cannot be undone." : "Owned processes stop; saved state stays for the next start. External services stay under their owner's control."), h("div", { class: "actions" }, dismiss, confirm));
+        dismiss.onclick = () => dialog.close();
+        confirm.onclick = () => { dialog.close(); later(perform("/api/environment-stop", { session: snapshot.environmentId, discard: disposable })); };
+        dialog.addEventListener("close", () => dialog.remove());
+        showModal(dialog);
+        dismiss.focus();
+    };
+    return {
+        async poll() { const value = await options.request("/api/environment-state"); render(value); return value.state === "running"; },
+        sync() { if (state)
+            render(state); },
+        restart,
+        get canRestart() { return !!state?.canStart && state.state !== "starting" && !pending; },
+        get online() { return !state || state.state === "running"; },
+    };
+}

package/entrypoints/panel/src/client/environment-options.d.ts

@@ -0,0 +1,18 @@
+import type { EnvironmentOptionView } from "@parity/product-lab/ports/driving";
+import type { LabSnapshot } from "./panel-snapshot.js";
+type Listed = LabSnapshot["environments"][number];
+export interface OptionRowsInput {
+    item: Listed;
+    /** The environment runs now. */
+    current: boolean;
+    /** The option it runs as, when it runs. */
+    running?: string;
+    /** Remember the person's choice; then, for an environment that is not running, switch to it. A refusal shows under the rows. */
+    choose: (option: EnvironmentOptionView) => Promise<void>;
+}
+/** What a row's tooltip says: its description, and when this machine is short, what it needs. */
+export declare function optionTitle(option: EnvironmentOptionView): string;
+/** The chip a row carries: running now, or the one the next start picks (with why), or what a short machine lacks. */
+export declare function optionChip(option: EnvironmentOptionView, input: Pick<OptionRowsInput, "item" | "current" | "running">): HTMLElement | null;
+export declare function environmentOptionRows(input: OptionRowsInput): HTMLElement[];
+export {};

package/entrypoints/panel/src/client/environment-options.js

@@ -0,0 +1,33 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { chip, h, icon } from "./ui.js";
+export function optionTitle(option) {
+    return option.fits ? option.description : `${option.description}\n${option.needs}. This machine has less, so the lab picks another option unless you choose this one.`;
+}
+export function optionChip(option, input) {
+    const pick = input.item.pick;
+    if (input.current && input.running === option.id)
+        return chip("Runs now", { tone: "success", title: pick?.option === option.id ? pick.why : undefined });
+    if (pick?.option === option.id)
+        return chip(input.current ? "Next start" : pick.chosen ? "Your choice" : "Picked", { tone: "accent", title: pick.why });
+    if (!option.fits)
+        return chip("Needs more", { tone: "warning", title: option.needs });
+    return null;
+}
+export function environmentOptionRows(input) {
+    if (!input.item.options?.length)
+        return [];
+    const refused = h("p", { class: "environment-way-error", "data-option-error": input.item.id, role: "alert", hidden: true });
+    const choose = async (option) => {
+        refused.hidden = true;
+        try {
+            await input.choose(option);
+        }
+        catch (failure) {
+            refused.textContent = failure instanceof Error ? failure.message : String(failure);
+            refused.hidden = false;
+        }
+    };
+    const rows = input.item.options.map((option) => h("button", { type: "button", class: `picker-option environment-way${option.fits ? "" : " is-short"}${input.current && input.running === option.id ? " selected" : ""}`, "data-environment": input.item.id, "data-option": option.id, title: optionTitle(option), onclick: () => void choose(option)  }, h("span", { class: "scenario-symbol" }, icon(option.fits ? "chain" : "lock", 13)), h("span", {}, h("strong", {}, option.label), h("small", {}, option.description)), optionChip(option, input)));
+    return [...rows, refused];
+}

package/entrypoints/panel/src/client/environment.d.ts

@@ -0,0 +1,189 @@
+import type { RetentionView } from "@parity/product-lab/domain/lab";
+import { type OffConfigItem } from "@parity/product-lab/domain/lab/resolved-config";
+import type { EnvironmentKind, EnvironmentRpcRequest, EnvironmentRpcView, KeepBetweenStartsView, LabRegistry, LabSnapshot, SwitchPlan, TopologyView, VersionsReport } from "@parity/product-lab/ports/driving";
+export type { SwitchPlan };
+type Offer = LabRegistry["environment"]["offer"];
+export interface EnvironmentRow {
+    id: string;
+    label: string;
+    /** The configured label alone. */
+    name: string;
+    description?: string;
+    current: boolean;
+    retention: RetentionView;
+    /** Why it cannot start (empty when it can). */
+    problems: string[];
+    apps: {
+        app: string;
+        available: boolean;
+        reason: string;
+    }[];
+    offer?: Offer;
+    topology?: TopologyView;
+    /** The RPC per chain it takes of the lab's choice (lab.config's, remembered), when its provider takes one. */
+    rpc?: EnvironmentRpcView;
+    /** Switch is possible now; otherwise `reason` says why not. */
+    switchable: boolean;
+    reason: string;
+    /** This start kept its chains (backlog A5): what they keep, in the provider's words (`keptChains`). */
+    kept?: string;
+}
+export interface EnvironmentTabView {
+    current: {
+        id?: string;
+        label: string;
+        /** The configured label alone, as the frame names the environment everywhere. */
+        name: string;
+        /** The workspace directory the environment keeps its state in, when it has one. */
+        workspace?: string;
+        retention: RetentionView;
+        offer?: Offer;
+        topology?: TopologyView;
+        endpoints: {
+            id: string;
+            url: string;
+        }[];
+        manifest?: string;
+        /** The CLI command that shows (and previews changes to) the same resolution. */
+        envShow?: string;
+        /** This start kept its chains (backlog A5): what they keep, in the provider's words (`keptChains`). */
+        kept?: string;
+    };
+    environments: EnvironmentRow[];
+    /** A product config: the environments, live networks and live people it leaves off or unset, greyed with their lines. */
+    off?: OffConfigItem[];
+    /** The lab's version selectors against the lock, when the panel could read them. */
+    versions?: VersionsView;
+    /** The lab's directory (where lab.lock.json lives), when known: paths are shown relative to it. */
+    root?: string;
+    /** Topology options are shown, not edited, in this version. */
+    editing: "read-only";
+}
+export interface VersionRowView {
+    id: string;
+    /** The lab's selector (`-` when the lab no longer selects a locked component). */
+    selector: string;
+    /** The locked version and its source (`-` when the lock has none). */
+    locked: string;
+    status: string;
+}
+export interface VersionsView {
+    /** The lock file and its digest, or "none". */
+    lock: string;
+    rows: VersionRowView[];
+    /** Set when the versions could not be read (the reason), or when the lab selects none. */
+    note?: string;
+    /** The CLI that changes and checks the lock. */
+    commands: string;
+}
+/** The Versions section from `/api/versions` (a `VersionsReport`) or the error reading it. */
+export declare function versionsView(report: VersionsReport | {
+    error: string;
+} | undefined, options?: {
+    configFile?: string;
+}): VersionsView | undefined;
+export declare function switchPlan(snapshot: LabSnapshot, target: string): SwitchPlan;
+/** Current environment id: the runtime's selection, else the registry's. */
+export declare function currentEnvironmentId(snapshot: LabSnapshot): string | undefined;
+/** Topology labels repeat across environments ("relayless (custom): people"), so name the id too. */
+export declare const environmentName: (id: string | undefined, label: string) => string;
+/**
+ * Backlog A5: what this start kept of its chains ("Keep chain and people between starts", backlog 183), in the
+ * provider's words; undefined when it started clean or keeps no chain. The provider's own retention says what its
+ * declared start does ("a new chain each start", "thrown away when stopped"): a kept start is not that.
+ */
+export declare function keptChains(view: KeepBetweenStartsView | undefined): string | undefined;
+/** A kept start's retention, in the words the switch uses (keep-words.ts): kept, what, and why this start kept. */
+export declare function keptRetention(view: KeepBetweenStartsView, chains: string): RetentionView;
+export declare function environmentView(snapshot: LabSnapshot, options?: {
+    configFile?: string;
+    versions?: VersionsReport | {
+        error: string;
+    };
+}): EnvironmentTabView;
+/**
+ * A path relative to the lab's directory when it lies inside it, else its last three segments (`…/runs/x/run.json`);
+ * never an absolute path. The full path stays in the tooltip and the copy.
+ */
+export declare function labPath(path: string, root: string | undefined): string;
+export interface EnvironmentHandlers {
+    /** Called after the user confirmed (or, for a non-destructive switch, reviewed) the plan. */
+    onSwitch(id: string, confirmation?: string): void;
+    /** Current snapshot, re-read when a dialog is confirmed so a stale plan is never submitted. */
+    snapshot(): LabSnapshot | undefined;
+    /** Remember an environment's RPC for its next starts, or clear it; rejects with the runtime's refusal. */
+    onRpc?(id: string, input: {
+        action: "remember";
+        rpc: EnvironmentRpcRequest;
+    } | {
+        action: "clear";
+    }): Promise<unknown>;
+}
+/**
+ * Why the RPC fields of an environment cannot be remembered as typed (empty when they can). Never echoes a URL: a
+ * credential in one is named by its chain only. The runtime checks the same again.
+ */
+export declare function rpcFieldProblems(view: Pick<EnvironmentRpcView, "role">, chains: Readonly<Record<string, string>>, reason: string, options: {
+    publicTarget: boolean;
+}): string[];
+/** What stopping keeps, in words ("thrown away when stopped"), as the chip and the bottom bar say it. */
+export declare const retentionWords: (retention: RetentionView) => string;
+/** What stopping keeps, as a chip whose tooltip says why. */
+export declare function retentionChip(retention: RetentionView): HTMLSpanElement;
+/**
+ * Render the tab. `container` (#environment-tab, inside Advanced) receives the resolved configuration and versions as
+ * facts; the configured environments go to #environment-others when the page has it (the Environment view places it
+ * in the main flow), else to `container`. Callers re-render only when the view changes.
+ */
+export declare function renderEnvironment(container: HTMLElement, view: EnvironmentTabView, handlers: EnvironmentHandlers, blocked?: string): void;
+/** Where more environments come from, when the lab defines only one. */
+/**
+ * Every kind of chain a lab can run on (docs/feature-map.md, "Chains"): what it is, why to choose it, and the config
+ * that adds one. The chain picker lists the kinds a lab does not configure, greyed, never hidden.
+ */
+export declare const ENVIRONMENT_KINDS: readonly {
+    kind: EnvironmentKind;
+    label: string;
+    why: string;
+    turnOn: string;
+}[];
+/**
+ * The environments, live networks and live people a product config (`defineLab({ app })`) leaves off or unset, from
+ * the loader's resolved config (LabRegistry.config): each greyed with the line that adds it, never hidden.
+ */
+export declare function offEnvironmentItems(registry: Pick<LabRegistry, "config"> | undefined): OffConfigItem[] | undefined;
+/** One greyed row for something the config leaves off: what it is, why it is off, and the line to add (copyable). */
+export declare function offConfigRow(item: OffConfigItem, className: string): HTMLElement;
+/**
+ * The chain picker's greyed rows. A product config: what its resolved config leaves off, by the loader's lines. An
+ * older definition: each kind of chain the lab's environments do not include, with how to add it.
+ */
+export declare function unconfiguredEnvironments(environments: readonly {
+    kind?: EnvironmentKind;
+}[] | undefined, registry?: Pick<LabRegistry, "config">): HTMLElement[];
+export declare function oneEnvironmentHint(): HTMLDivElement;
+/** A chain's id as people say it: "people" is People, "asset-hub" Asset Hub, "relay" the relay chain. */
+export declare function chainName(id: string): string;
+/**
+ * The running chains in plain words, in the order the environment declares them ("People + Bulletin"): the runtime
+ * lists them as each comes up, so the bottom bar's line would change order from one start to the next.
+ */
+export declare function chainsLine(running: readonly {
+    label: string;
+}[], declared?: readonly string[]): string;
+/** Where an environment's chain state comes from, in plain words (0e's first-time-user audit, item 1: "fresh genesis"). */
+export declare function stateWords(state: string): string;
+/**
+ * One short line for an environment: its chains and where its state comes from ("People, Bulletin · a new chain each
+ * start"), else what stopping keeps. A start that kept its chains says so (backlog A5), whatever its provider declares.
+ */
+export declare function environmentSummary(item: Pick<EnvironmentRow, "topology" | "offer" | "retention" | "kept">): string;
+/** A long id or hash in short form (`0x4a2b5b…ad48`), the whole value in its tooltip and copy. */
+export declare function shortValue(value: string): HTMLSpanElement;
+/** Provenance as facts: its scalar entries (ids in short form) and, per chain, the runtime and the block it started from. */
+export declare function provenanceFacts(provenance: Record<string, unknown>): HTMLDListElement;
+/**
+ * Show what switching does; destructive switches need the explicit confirm button. In the lab window, a switch that
+ * needs the window without its debugging port says so in the same confirm, and yes reopens it first (window-switch.ts).
+ */
+export declare function confirmSwitch(id: string, handlers: EnvironmentHandlers): void;