web: run detail Graph tab with executed styling and stage panes (R5)

Add the run detail's Graph tab (between Summary and Input), reusing the
shared src/graph.js renderer (P6) rather than a second renderer. In run
mode a visited stage is executed (solid fill + border), an unvisited one
hollow with a dashed muted border; a terminal is executed only when a
visit resolved to it; a route is executed only when a recorded visit
produced that outcome (solid with an arrowhead, success first, error
last, others alphabetical, `error*` for the fallback). The Executed /
Not executed legend shows only for a run. While the run executes the
current stage carries a pulsing halo (static under prefers-reduced-motion)
and a ticking elapsed badge; a finished run shows neither. Clicking a
stage opens the existing visit pane at that stage's latest visit, and
Back/Escape return focus. The empty state is the exact
"This server did not include the run graph."

extend src/graph.js with the run-mode inputs (runState-driven executed
styling, legend, active halo/elapsed badge); keep app.js to wiring.
Extend graph.test.mjs with focused run-mode unit tests and ui-smoke.mjs
with the run 438 / run 440 / live-run captures. Mark R5 done in
web/PARITY.md.

Checks: node --check on every touched file; cd web && node --test test/
(178 pass, 0 fail); cd web && node test/ui-smoke.mjs --out captures
(UI SMOKE PASS, captures 28-31).
This commit is contained in:
2026-10-19 04:05:37 +01:00
parent 2e9ff1704f
commit 94d4ff02d3
8 changed files with 569 additions and 32 deletions
+69 -10
View File
@@ -24,6 +24,8 @@ import {
} from "./artifacts.js";
import {
PIPELINE_GRAPH_EMPTY,
RUN_GRAPH_MISSING,
RUN_GRAPH_NOTE,
mount as mountGraph,
} from "./graph.js";
import {
@@ -87,6 +89,7 @@ import {
runLabelFor,
runDurationText,
runTimeline,
runGraphState,
nodeLabel,
headlineFields,
runStepFields,
@@ -142,6 +145,10 @@ const state = {
// handle is dropped on every re-render so its listeners can never leak.
pipelineGraph: null,
pipelineGraphExpanded: false,
// The mounted run-mode graph (R5) on the run detail's Graph tab. Dropped on
// every re-render and on a run change, so its wheel/pointer/resize listeners
// and its elapsed timer can never leak.
runGraph: null,
versionsExpanded: false,
pipelinesLoaded: false,
runsLoaded: false,
@@ -268,6 +275,10 @@ function renderContent() {
state.pipelineGraph.unmount();
state.pipelineGraph = null;
}
if (state.runGraph) {
state.runGraph.unmount();
state.runGraph = null;
}
const nodes = [];
if (state.error) {
nodes.push(h("div", { class: "banner error" }, h("strong", { text: "Error: " }), state.error));
@@ -1081,12 +1092,13 @@ function closeMenu() {
}
/**
* The run detail: a tab strip (Summary / Input / Output / Timeline) over the
* selected tab's body, wired from the pure helpers in runDetail.js. Summary is
* the default and carries the run's identity, key/value rows and diagnostic;
* Input/Output are one collapsed section per recorded field; the Timeline is one
* compact row per visit that opens the stage pane. Every server string is set
* with textContent, never innerHTML.
* The run detail: a tab strip (Summary / Graph / Input / Output / Timeline) over
* the selected tab's body, wired from the pure helpers in runDetail.js. Summary
* is the default and carries the run's identity, key/value rows and diagnostic;
* the Graph tab mounts the shared workflow graph in run mode; Input/Output are
* one collapsed section per recorded field; the Timeline is one compact row per
* visit that opens the stage pane. Every server string is set with textContent,
* never innerHTML.
*/
function renderRunDetail() {
const d = state.runDetail;
@@ -1111,7 +1123,9 @@ function renderRunDetail() {
),
),
);
if (state.runTab === "input") {
if (state.runTab === "graph") {
pane.append(renderRunGraphTab(d));
} else if (state.runTab === "input") {
pane.append(renderRunFieldTab(d.input, "input", EMPTY_INPUT_MESSAGE));
} else if (state.runTab === "output") {
pane.append(renderRunFieldTab(d.output, "output", EMPTY_OUTPUT_MESSAGE));
@@ -1124,6 +1138,41 @@ function renderRunDetail() {
return pane;
}
/**
* The Graph tab (R5): the run's own guidance note plus the shared workflow graph
* mounted in run mode, or the app's exact missing-graph sentence when the server
* sent no stages. The active stage pulses with its elapsed time while the run
* executes; clicking a stage opens the existing visit pane at that stage's most
* recent visit. The mount handle is tracked in `state.runGraph` so a re-render
* (or a tab/run change) always unmounts the previous wheel/pointer/resize
* listeners and the elapsed timer.
*/
function renderRunGraphTab(d) {
const wrap = h("div", { class: "run-tab-body" });
const stages = d.graph?.stages ?? [];
if (!stages.length) {
wrap.append(h("div", { class: "run-empty muted", text: RUN_GRAPH_MISSING }));
return wrap;
}
wrap.append(h("p", { class: "graph-note muted", text: RUN_GRAPH_NOTE }));
const host = h("div", { class: "graph-host" });
wrap.append(host);
state.runGraph = mountGraph(host, d.graph, {
runState: runGraphState(d),
onStageTap: (key) => openStagePane(key, latestVisitIndex(d, key)),
});
return wrap;
}
/**
* The visit index the graph opens for a stage: its most recent recorded visit
* (`visits.size - 1`, never negative), exactly as RunGraphTab computes it.
*/
function latestVisitIndex(d, key) {
const visits = runTimeline(d.steps ?? []).visitsByStage.get(key) ?? [];
return Math.max(0, visits.length - 1);
}
/** The Summary tab: identity, chip row, key/value rows, diagnostic and gallery. */
function renderRunSummaryTab(d) {
const wrap = h("div", { class: "run-tab-body" });
@@ -1488,7 +1537,14 @@ function closeStagePane() {
const row = [...document.querySelectorAll(".timeline-row")].find(
(node) => node.dataset.stageKey === closing.stageKey && node.dataset.visitIndex === String(closing.visitIndex),
);
row?.focus();
// A pane opened from the Timeline returns to its row; one opened from the Graph
// returns to the stage node that opened it (there is no timeline row then).
const focusTarget =
row ??
[...document.querySelectorAll(".graph-node")].find(
(candidate) => candidate.dataset.key === closing.stageKey,
);
focusTarget?.focus();
}
/** Whether the configured server URL can resolve a server-relative artifact. */
@@ -1963,9 +2019,12 @@ async function selectPipeline(summary) {
async function selectRun(id, { silent = false } = {}) {
state.selectedRunId = id;
if (!silent) {
state.runDetail = null;
// A different run reseeds the detail: Summary tab, every section closed and
// no stage pane left over from the run the operator navigated away from.
// no stage pane left over from the run the operator navigated away from. Drop
// the mounted run graph first so a live run's timer can never outlive it.
state.runGraph?.unmount();
state.runGraph = null;
state.runDetail = null;
state.runTab = "summary";
state.runSections = new Set();
state.runStagePane = null;
+112 -9
View File
@@ -26,6 +26,7 @@
import { Protocol, isTerminal, resolveTarget } from "./protocol.js";
import { effectiveStageType } from "./templates.js";
import { formatDuration, secondsSince } from "./runs.js";
// Re-exported so a caller (and the unit tests) can reach the shared "blank is
// the model stage" rule from the graph module it belongs to without a second
@@ -61,6 +62,19 @@ const DRAG_THRESHOLD = 4;
/** The run tab's empty state when the server omitted the run graph (R5). */
export const RUN_GRAPH_MISSING = "This server did not include the run graph.";
/**
* The run tab's guidance note: the browser adaptation of RunGraphTab's own
* sentence, so the app's pinch/tap become mouse wheel/click while everything
* else (the live pulse, the settled finish, the executed/not-executed shapes)
* stays verbatim.
*/
export const RUN_GRAPH_NOTE =
"The running stage pulses with its elapsed time and executed routes flow; " +
"a finished run settles, and with animations off the running stage stays marked. " +
"Solid means executed, dashed and outlined not executed; executed success and " +
"failure routes are drawn thickest. Mouse wheel to zoom, drag to pan, " +
"click a stage for details.";
/**
* The pipeline detail's empty state when the parsed definition declares no
* stages. The template gallery has its own Android-authored analogue
@@ -203,6 +217,18 @@ export function edgeIsExecuted(edge, runState) {
return inSet(runState.takenRoutes, edge) || inSet(runState.takenRoutes, edge.id);
}
/**
* The key of the stage a run is executing right now, else null. Only a live run
* (still `executing`) has an active stage, so a finished run never carries a
* halo or an elapsed badge. Pure: drawing, the elapsed badge and the tests share
* one definition of "active".
*/
export function activeStage(runState) {
if (runState == null || !runState.executing) return null;
const key = runState.currentStage;
return key == null || key === "" ? null : key;
}
// ---------------------------------------------------------------------------
// Pure viewport maths (WorkflowGraph.kt)
// ---------------------------------------------------------------------------
@@ -895,19 +921,38 @@ function pathFromPoints(points) {
* space does nothing.
*
* Options:
* runState — omitted for the definition view (every route executed);
* R5 passes `{ visitedStages, takenRoutes }` to dash the
* routes a run did not take.
* runState — omitted for the definition view (every route executed and
* no legend); R5 passes the `runGraphState(run)` shape
* ({ visitedStages, takenRoutes, currentStage, executing,
* currentStageStartedAt }) to render the run: executed nodes
* solid, unvisited ones hollow/dashed, executed routes
* arrowed, the live stage's halo + elapsed badge and the
* Executed / Not executed legend.
* animationsEnabled — honour the caller's animation gate. Defaults to the
* page's `prefers-reduced-motion` setting; when false the
* active stage keeps a static ring instead of pulsing.
* expanded — start with the taller panel.
* onStageTap — called with the node key on a node click.
* onStageTap — called with the node key on a node click. When supplied
* (the run tab), the click opens the caller's own stage
* pane and no definition pane is drawn.
* onExpandedChange — called with the new expanded flag on toggle.
* metrics — layout metrics override (tests).
*
* Returns `{ unmount }`; call it before discarding the container so the wheel,
* pointer and resize listeners never leak.
* pointer, resize and elapsed-timer handles never leak.
*/
export function mount(container, graph, options = {}) {
const runState = options.runState ?? null;
const activeKey = activeStage(runState);
const reducedMotion =
typeof window !== "undefined" &&
typeof window.matchMedia === "function" &&
window.matchMedia("(prefers-reduced-motion: reduce)").matches;
// The caller may force animations off; otherwise the page's motion preference
// decides. A finished run never animates regardless (activeKey is null then).
const animationsEnabled =
options.animationsEnabled === undefined ? !reducedMotion : Boolean(options.animationsEnabled);
const pulse = activeKey != null && animationsEnabled;
const layout = layoutGraph(graph, options.metrics);
const stagesByKey = new Map((graph?.stages ?? []).map((stage) => [stage.key, stage]));
@@ -983,6 +1028,7 @@ export function mount(container, graph, options = {}) {
// Node layer: real buttons, positioned in graph space.
const nodeLayer = el("div", "graph-node-layer");
let elapsedBadge = null;
for (const node of layout.nodes) {
const kind = graphNodeKind(node.terminal, node.key, stagesByKey.get(node.key)?.type);
const button = el("button", `graph-node ${nodeKindClass(kind)}`, node.label);
@@ -998,13 +1044,25 @@ export function mount(container, graph, options = {}) {
? `${node.label}, open details`
: `Stage ${node.key}, ${node.type}, open details`,
);
if (!stageIsExecuted(node.key, runState)) button.classList.add("not-executed");
const executed = stageIsExecuted(node.key, runState);
if (runState != null) button.classList.add(executed ? "executed" : "not-executed");
if (node.key === activeKey) {
button.classList.add("active");
if (pulse) button.classList.add("pulsing");
const badge = el("span", "graph-elapsed");
badge.setAttribute("aria-hidden", "true");
button.append(badge);
elapsedBadge = badge;
}
button.addEventListener("click", (event) => {
if (dragged) {
event.preventDefault();
return;
}
selectNode(node.key);
// The run tab owns its own stage pane (the shared timeline visit pane), so
// a supplied handler replaces the definition pane rather than stacking on it.
if (typeof options.onStageTap === "function") options.onStageTap(node.key);
else selectNode(node.key);
});
nodeLayer.append(button);
}
@@ -1026,7 +1084,27 @@ export function mount(container, graph, options = {}) {
controls.append(fitButton, expandButton);
viewport.append(controls);
// The definition pane, hidden until a node is clicked.
// The legend, only under a run (never the definition-only view): a solid,
// arrowed swatch means "executed", a dashed, arrowless one "not executed",
// matching what the graph draws.
if (runState != null) {
const legend = el("div", "graph-legend");
legend.setAttribute("role", "note");
legend.setAttribute("aria-label", "Executed and not executed routes");
for (const entry of [
{ label: "Executed", executed: true },
{ label: "Not executed", executed: false },
]) {
const item = el("span", "graph-legend-entry");
item.append(el("span", `graph-legend-swatch ${entry.executed ? "executed" : "not-executed"}`));
item.append(el("span", "graph-legend-label", entry.label));
legend.append(item);
}
viewport.append(legend);
}
// The definition pane, hidden until a node is clicked (definition view only;
// the run tab opens its own pane through onStageTap instead).
const pane = el("div", "graph-pane");
pane.hidden = true;
root.append(viewport, pane);
@@ -1122,7 +1200,28 @@ export function mount(container, graph, options = {}) {
pane.replaceChildren(...children);
pane.hidden = false;
if (typeof options.onStageTap === "function") options.onStageTap(key);
}
// --- Elapsed badge (live run only) ---------------------------------------
function updateElapsed() {
if (!elapsedBadge) return;
const seconds = secondsSince(runState?.currentStageStartedAt, Date.now());
elapsedBadge.textContent = seconds == null ? "" : formatDuration(seconds);
}
let elapsedTimer = null;
if (elapsedBadge != null) {
updateElapsed();
// Tick only while the graph has a live stage with a known start; a still
// ring (reduced motion) and a finished run never wake up once a second.
if (
pulse &&
typeof setInterval === "function" &&
String(runState?.currentStageStartedAt ?? "").trim() !== ""
) {
elapsedTimer = setInterval(updateElapsed, 1000);
}
}
// --- Interactions --------------------------------------------------------
@@ -1230,6 +1329,10 @@ export function mount(container, graph, options = {}) {
return {
unmount() {
if (elapsedTimer != null) {
clearInterval(elapsedTimer);
elapsedTimer = null;
}
resizeObserver?.disconnect();
viewport.removeEventListener("pointerdown", onPointerDown);
viewport.removeEventListener("pointermove", onPointerMove);
+65 -5
View File
@@ -36,9 +36,9 @@ import { effectiveStageType } from "./templates.js";
/**
* The run-detail tabs, Summary first so it is the default selection. The Graph
* tab is present (Android `runDetailTabs`) but has no rendered body yet — it is
* the R5 item — so the renderer filters it out until then. The timeline keeps
* Android's stable key `steps` with the visible title `Timeline`.
* tab sits between Summary and Input (R5) and mounts the shared workflow graph
* in run mode. The timeline keeps Android's stable key `steps` with the visible
* title `Timeline`.
*/
export const RUN_DETAIL_TABS = [
{ key: "summary", label: "Summary" },
@@ -48,8 +48,8 @@ export const RUN_DETAIL_TABS = [
{ key: "steps", label: "Timeline" },
];
/** The tabs the browser currently renders (the Graph body is the R5 item). */
export const RENDERED_RUN_TABS = RUN_DETAIL_TABS.filter((tab) => tab.key !== "graph");
/** The tabs the browser renders: all of them, including the Graph body (R5). */
export const RENDERED_RUN_TABS = RUN_DETAIL_TABS;
// The empty-state sentences, exactly as the app spells them.
export const EMPTY_INPUT_MESSAGE = "No input recorded.";
@@ -330,6 +330,66 @@ export function graphEdges(graph) {
return result;
}
/**
* Which stages and routes a run actually recorded, for the graph's execution
* highlighting. Mirrors Android `RunGraphState.from` (GraphSemantics.kt:91-116):
* every step's stage key is a visited stage (insertion order), a step with a
* non-blank outcome and target contributes a taken route
* `{source, outcome, resolvedTarget}` (recorded as a `source\0outcome\0target`
* key the graph matches) and, when that resolved target is a terminal, marks the
* terminal visited too. `currentStage` is the run's own stage, else the last
* visit's stage, else null; `executing` mirrors the run; `currentStageStartedAt`
* is the running visit's start for the active stage, only while executing. Pure
* and DOM-free so the renderer and the tests share one definition.
*/
export function runGraphState(run) {
const visitedStages = [];
const seenStages = new Set();
const takenRoutes = [];
const seenRoutes = new Set();
const steps = run?.steps ?? [];
const visit = (key) => {
if (key == null || seenStages.has(key)) return;
seenStages.add(key);
visitedStages.push(key);
};
for (const step of steps) {
visit(step?.stage);
const outcome = String(step?.outcome ?? "");
const target = String(step?.target ?? "");
if (target.trim() !== "" && outcome.trim() !== "") {
const resolved = resolveTarget(outcome, target);
const route = `${step?.stage}\u0000${outcome}\u0000${resolved}`;
if (!seenRoutes.has(route)) {
seenRoutes.add(route);
takenRoutes.push(route);
}
if (isTerminal(resolved)) visit(resolved);
}
}
const lastStage = steps.length > 0 ? steps[steps.length - 1]?.stage : "";
const rawCurrent = String(run?.current_stage ?? "").trim() !== "" ? run.current_stage : lastStage;
const currentStage = String(rawCurrent ?? "").trim() !== "" ? String(rawCurrent) : null;
const executing = Boolean(run?.executing);
let currentStageStartedAt = null;
if (executing && currentStage != null) {
for (let index = steps.length - 1; index >= 0; index -= 1) {
const step = steps[index];
if (step?.stage === currentStage && step?.status === "running") {
const started = String(step?.started_at ?? "");
if (started.trim() !== "") currentStageStartedAt = started;
break;
}
}
}
return { visitedStages, takenRoutes, currentStage, executing, currentStageStartedAt };
}
// ---------------------------------------------------------------------------
// Stage pane (ui/graph/StageDetailPane.kt)
// ---------------------------------------------------------------------------