jev-devtools 0.2.0 → 0.4.0

package/lib/src/JevDevtools.js

@@ -1,7 +1,11 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { emptyFlows } from "./flow-stream.js";
 import { lazy, memo, startTransition, Suspense, useMemo, useState, } from "react";
 import { TraceDiagram } from "./TraceDiagram.js";
 import { JsonBlock, findImage } from "./TraceContent.js";
+const FlowOverview = lazy(() => import("./FlowOverview.js").then((module) => ({
+    default: module.FlowOverview,
+})));
 let questionsLoaded = false;
 const Questions = lazy(() => import("./Questions.js").then((module) => {
     questionsLoaded = true;
@@ -13,7 +17,7 @@ const ms = (value) => value === undefined ? "—" : `${Math.round(value)} ms`;
 const RequestRow = memo(function RequestRow({ trace, selected, onSelect, }) {
     return (_jsxs("button", { className: `request-row ${selected ? "selected" : ""}`, onClick: () => onSelect(trace.id), children: [_jsx("span", { className: `status-dot ${trace.status}` }), _jsxs("span", { children: [_jsx("strong", { children: trace.label }), _jsxs("small", { children: [new Date(trace.startedAt).toLocaleTimeString(), " \u00B7 ", trace.source, " \u00B7", " ", ms(trace.durationMs)] })] }), _jsx("span", { className: "row-status", children: trace.status })] }));
 });
-const RequestDetail = memo(function RequestDetail({ trace, }) {
+export const RequestDetail = memo(function RequestDetail({ trace, }) {
     // Keep tab selection across request switches and clear, as before. Local tab
     // changes no longer rerender the history list.
     const [tab, setTab] = useState("Flow");
@@ -31,7 +35,11 @@ const RequestDetail = memo(function RequestDetail({ trace, }) {
                                 setTab(name);
                         }, children: name }, name))) }), _jsx("div", { className: `detail-body ${tab === "Flow" ? "detail-body-flow" : tab === "Questions" ? "detail-body-questions" : ""}`, children: _jsxs(Suspense, { fallback: _jsx("p", { className: "muted", role: "status", children: "Loading questions\u2026" }), children: [trace.error && (_jsxs("div", { role: "alert", className: "error-banner", children: [_jsx("strong", { children: trace.error.name }), " ", trace.error.message] })), trace.captureWarnings.map((w) => (_jsx("p", { className: "warning", children: w }, w))), tab === "Flow" && _jsx(TraceDiagram, { trace: trace }, trace.id), tab === "Questions" && (_jsx(Questions, { trace: trace }, trace.id)), tab === "Context" && (_jsxs(_Fragment, { children: [_jsx("p", { className: "muted", children: "Captured before dispatch. Known credential fields and email are redacted; captures are size limited." }), findImage(trace.request.state) && (_jsx("img", { className: "context-image", src: findImage(trace.request.state), alt: "Captured context" })), _jsx(JsonBlock, { value: trace.request.state }), trace.request.assets && (_jsx(JsonBlock, { value: trace.request.assets }))] })), tab === "Transport" && (_jsxs(_Fragment, { children: [_jsx("h3", { children: "HTTP attempts" }), _jsx("p", { className: "muted", children: "Attempt duration ends at response headers. Total duration includes SDK processing and retry waits." }), _jsxs("table", { children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Attempt" }), _jsx("th", { children: "Status" }), _jsx("th", { children: "Duration" })] }) }), _jsx("tbody", { children: trace.attempts.map((a) => (_jsxs("tr", { children: [_jsx("td", { children: a.number }), _jsx("td", { children: a.error || a.status || "Pending" }), _jsx("td", { children: ms(a.durationMs) })] }, a.number))) })] }), !trace.attempts.length && _jsx("p", { children: "No HTTP attempt recorded." })] })), tab === "Raw" && _jsx(JsonBlock, { value: trace })] }) })] })) : (_jsxs("div", { className: "empty-detail", children: [_jsx("span", { className: "empty-symbol", children: "\u21B3" }), _jsx("h2", { children: "Follow a Jev request" }), _jsxs("p", { children: ["Context, parallel questions, typed answers.", _jsx("br", {}), "Run a sample above to see the complete flow."] })] })) }));
 });
-export function JevPanel({ traces, connection, onClear, }) {
+export function JevPanel({ traces, flows = emptyFlows, connection, onClear, }) {
+    const [view, setView] = useState("requests");
+    const [selectedRun, setSelectedRun] = useState();
+    const run = flows.runs.find((r) => r.id === selectedRun) ?? flows.runs[0];
+    const definition = flows.definitions.find((d) => d.id === run?.definitionId);
     const [selected, setSelected] = useState();
     const [search, setSearch] = useState("");
     const [status, setStatus] = useState("all");
@@ -42,7 +50,13 @@ export function JevPanel({ traces, connection, onClear, }) {
             `${t.label} ${t.request.model} ${t.id}`.toLowerCase().includes(query));
     }, [traces, search, status]);
     const trace = filtered.find((t) => t.id === selected) || filtered[0];
-    return (_jsxs("div", { className: "jev-inspector", children: [_jsxs("aside", { className: "request-list", children: [_jsxs("header", { children: [_jsxs("h2", { children: ["Jev requests ", _jsx("span", { children: traces.length })] }), _jsx("button", { onClick: () => void onClear().catch((e) => setError(e.message)), disabled: !traces.length, children: "Clear" })] }), _jsxs("div", { className: "list-filters", children: [_jsx("input", { "aria-label": "Search requests", placeholder: "Search requests\u2026", value: search, onChange: (e) => setSearch(e.target.value) }), _jsx("select", { "aria-label": "Filter request status", value: status, onChange: (e) => setStatus(e.target.value), children: ["all", "pending", "success", "error", "cancelled"].map((s) => (_jsx("option", { children: s }, s))) })] }), _jsxs("div", { className: "request-items", children: [filtered.map((t) => (_jsx(RequestRow, { trace: t, selected: trace?.id === t.id, onSelect: setSelected }, t.id))), !filtered.length && (_jsx("p", { className: "empty", children: traces.length
+    return (_jsxs("div", { className: "jev-inspector", children: [_jsxs("aside", { className: "request-list", children: [_jsxs("header", { children: [_jsxs("h2", { children: [view === "requests" ? "Jev requests" : "Jev flows", " ", _jsx("span", { children: view === "requests" ? traces.length : flows.runs.length })] }), _jsx("button", { onClick: () => void onClear().catch((e) => setError(e.message)), disabled: !traces.length && !flows.runs.length, children: "Clear" })] }), (flows.runs.length > 0 || view === "flows") && (_jsxs("nav", { className: "detail-tabs", "aria-label": "History type", children: [_jsx("button", { "aria-pressed": view === "requests", onClick: () => setView("requests"), children: "Requests" }), _jsx("button", { "aria-pressed": view === "flows", onClick: () => {
+                                    setView("flows");
+                                    if (run)
+                                        setSelectedRun(run.id);
+                                }, children: "Flows" })] })), view === "requests" && (_jsxs("div", { className: "list-filters", children: [_jsx("input", { "aria-label": "Search requests", placeholder: "Search requests\u2026", value: search, onChange: (e) => setSearch(e.target.value) }), _jsx("select", { "aria-label": "Filter request status", value: status, onChange: (e) => setStatus(e.target.value), children: ["all", "pending", "success", "error", "cancelled"].map((s) => (_jsx("option", { children: s }, s))) })] })), _jsxs("div", { className: "request-items", children: [view === "flows"
+                                ? flows.runs.map((r) => (_jsxs("button", { className: `request-row ${run?.id === r.id ? "selected" : ""}`, onClick: () => setSelectedRun(r.id), children: [_jsx("span", { className: `status-dot ${r.status}` }), _jsxs("span", { children: [_jsx("strong", { children: r.name }), _jsxs("small", { children: [new Date(r.startedAt).toLocaleTimeString(), " \u00B7", " ", r.outcome ?? r.status] })] }), _jsx("span", { className: "row-status", children: r.status })] }, r.id)))
+                                : filtered.map((t) => (_jsx(RequestRow, { trace: t, selected: trace?.id === t.id, onSelect: setSelected }, t.id))), view === "requests" && !filtered.length && (_jsx("p", { className: "empty", children: traces.length
                                     ? "No matching requests."
-                                    : "Run a scenario to capture your first request." }))] }), (connection !== "connected" || error) && (_jsxs("footer", { children: [connection !== "connected" && (_jsx("span", { role: "status", children: connection })), error && _jsx("p", { role: "alert", children: error })] }))] }), _jsx(RequestDetail, { trace: trace })] }));
+                                    : "Run a scenario to capture your first request." }))] }), (connection !== "connected" || error) && (_jsxs("footer", { children: [connection !== "connected" && (_jsx("span", { role: "status", children: connection })), error && _jsx("p", { role: "alert", children: error })] }))] }), view === "flows" && run && definition ? (_jsx(Suspense, { fallback: _jsx("p", { role: "status", children: "Loading flow\u2026" }), children: _jsx(FlowOverview, { run: run, definition: definition, traces: traces }, run.id) })) : (_jsx(RequestDetail, { trace: trace }))] }));
 }

package/lib/src/TraceDiagram.d.ts

@@ -1,4 +1,7 @@
 import type { Trace } from "./protocol.js";
-export declare function TraceDiagram({ trace }: {
+export declare function TraceDiagram({ trace, embedded, onHeightChange, }: {
     trace: Trace;
+    /** Render in a parent diagram's coordinates, without a nested camera. */
+    embedded?: boolean;
+    onHeightChange?: (height: number) => void;
 }): import("react").JSX.Element;

package/lib/src/TraceDiagram.js

@@ -1,7 +1,8 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo, useState } from "react";
+import { useLayoutEffect, useMemo, useRef, useState } from "react";
 import { useDiagramViewport } from "./useDiagramViewport.js";
-import { findImage, flowAnswer, stateText } from "./flow-model.js";
+import { findImage, flowAnswer } from "./flow-model.js";
+import { DiagramContent } from "./DiagramContent.js";
 import { ChoiceProbabilities } from "./ChoiceProbabilities.js";
 const pct = (v) => `${Math.round(v * 100)}%`;
 function Result({ answer, image, probabilities, }) {
@@ -24,7 +25,20 @@ function Result({ answer, image, probabilities, }) {
                                     height: pct(answer.box.bottom - answer.box.top),
                                 } }))] }), _jsxs("p", { className: "lab-small lab-coordinates", children: ["left ", answer.box.left.toFixed(2), " \u00B7 top ", answer.box.top.toFixed(2), _jsx("br", {}), "right ", answer.box.right.toFixed(2), " \u00B7 bottom", " ", answer.box.bottom.toFixed(2)] })] })), answer.confidence !== undefined && (_jsxs("p", { className: "lab-small", children: ["Confidence ", pct(answer.confidence)] }))] }));
 }
-export function TraceDiagram({ trace }) {
+export function TraceDiagram({ trace, embedded = false, onHeightChange, }) {
+    const root = useRef(null);
+    useLayoutEffect(() => {
+        if (!embedded || !root.current || !onHeightChange)
+            return;
+        const element = root.current;
+        const observer = new ResizeObserver(() => {
+            // Closed drawers and skipped offscreen content cannot replace retained bounds.
+            if (element.offsetHeight > 0)
+                onHeightChange(element.offsetHeight);
+        });
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [embedded, onHeightChange]);
     const [selected, setSelected] = useState(""), [flow, setFlow] = useState(true), [extraCategories, setExtraCategories] = useState({}), [entering, setEntering] = useState(null), [probabilityView, setProbabilityView] = useState(null);
     const entries = Object.entries(trace.request.questions ?? {}).filter(([, q]) => q && typeof q === "object" && typeof q.type === "string"), [key, question] = entries.find(([key]) => key === selected) ??
         entries[0] ?? ["", undefined];
@@ -79,7 +93,7 @@ export function TraceDiagram({ trace }) {
             active: output.active,
         })),
     ];
-    return (_jsxs("div", { className: `lab-flow ${compact ? "lab-flow-compact" : ""}`, children: [_jsxs("div", { className: "lab-flow-toolbar", children: [_jsxs("label", { children: ["Question", _jsx("select", { "aria-label": "Diagram question", value: key, onChange: (event) => {
+    return (_jsxs("div", { ref: root, className: `lab-flow ${compact ? "lab-flow-compact" : ""} ${embedded ? "lab-flow-embedded" : ""}`, children: [_jsxs("div", { className: "lab-flow-toolbar", children: [_jsxs("label", { children: ["Question", _jsx("select", { "aria-label": "Diagram question", value: key, onChange: (event) => {
                                     setEntering(null);
                                     setSelected(event.target.value);
                                 }, children: entries.map(([name, q]) => (_jsxs("option", { value: name, children: [name, " \u00B7 ", q.type] }, name))) })] }), _jsxs("div", { children: [answer?.type === "choice" && (_jsx("button", { "aria-pressed": showProbabilities, onClick: () => {
@@ -91,21 +105,19 @@ export function TraceDiagram({ trace }) {
                                             preserveCamera();
                                             setEntering(null);
                                             setExtraCategories((counts) => ({ ...counts, [key]: 0 }));
-                                        }, children: "Show fewer" })), _jsx("button", { "aria-label": "Zoom diagram out", disabled: zoom <= 10, onClick: () => zoomBy(1 / 1.2), children: "\u2212" }), _jsxs("output", { "aria-label": "Diagram zoom", children: [zoom, "%"] }), _jsx("button", { "aria-label": "Zoom diagram in", disabled: zoom >= 400, onClick: () => zoomBy(1.2), children: "+" }), _jsx("button", { onClick: fit, children: "Fit" }), _jsx("button", { "aria-pressed": flow, onClick: () => setFlow(!flow), children: flow ? "Pause flow" : "Play flow" })] }))] })] }), showProbabilities && answer && (_jsx(ChoiceProbabilities, { answer: answer }, key)), _jsx("div", { hidden: showProbabilities, className: "lab-flow-viewport", ref: viewport, tabIndex: 0, role: "group", "aria-label": "Jev diagram. Drag to pan, scroll or pinch to zoom. Arrow keys pan, plus and minus zoom, zero fits.", children: _jsxs("div", { ref: canvas, className: "lab-flow-canvas", style: { width: 1120, height }, children: [_jsxs("svg", { className: "lab-connections", width: "1120", height: height, "aria-hidden": "true", children: [paths.map((path) => (_jsxs("g", { children: [_jsx("path", { d: path.d, pathLength: 1, className: `${path.active ? "active" : ""} ${"delay" in path && path.delay !== undefined ? "lab-branch-enter" : ""}`, style: {
+                                        }, children: "Show fewer" })), !embedded && (_jsxs(_Fragment, { children: [_jsx("button", { "aria-label": "Zoom diagram out", disabled: zoom <= 10, onClick: () => zoomBy(1 / 1.2), children: "\u2212" }), _jsxs("output", { "aria-label": "Diagram zoom", children: [zoom, "%"] }), _jsx("button", { "aria-label": "Zoom diagram in", disabled: zoom >= 400, onClick: () => zoomBy(1.2), children: "+" }), _jsx("button", { onClick: fit, children: "Fit" })] })), _jsx("button", { "aria-pressed": flow, onClick: () => setFlow(!flow), children: flow ? "Pause flow" : "Play flow" })] }))] })] }), showProbabilities && answer && (_jsx(ChoiceProbabilities, { answer: answer }, key)), _jsx("div", { hidden: showProbabilities, className: embedded ? "lab-flow-surface" : "lab-flow-viewport", ref: embedded ? undefined : viewport, style: embedded ? { height } : undefined, tabIndex: embedded ? undefined : 0, role: "group", "aria-label": embedded
+                    ? "Jev request diagram"
+                    : "Jev diagram. Drag to pan, scroll or pinch to zoom. Arrow keys pan, plus and minus zoom, zero fits.", children: _jsxs("div", { ref: embedded ? undefined : canvas, className: "lab-flow-canvas", style: { width: 1120, height }, children: [_jsxs("svg", { className: "lab-connections", width: "1120", height: height, "aria-hidden": "true", children: [paths.map((path) => (_jsxs("g", { children: [_jsx("path", { d: path.d, pathLength: 1, className: `${path.active ? "active" : ""} ${"delay" in path && path.delay !== undefined ? "lab-branch-enter" : ""}`, style: {
                                                 animationDelay: "delay" in path ? path.delay : undefined,
                                             } }), flow &&
                                             !showProbabilities &&
                                             path.active &&
-                                            !["error", "cancelled"].includes(trace.status) && (_jsx("circle", { r: "3", className: "lab-flow-dot", children: _jsx("animateMotion", { dur: "3.2s", repeatCount: "indefinite", path: path.d }) }))] }, path.id))), _jsx("text", { x: "305", y: mid - 65, children: "state" }), _jsx("text", { x: "300", y: mid + 65, children: "question" })] }), _jsxs("article", { className: "lab-card", style: { left: 20, top: 32, width: 240, height: 180 }, children: [_jsx("span", { className: "lab-eyebrow", children: image ? "IMAGE STATE" : "STATE" }), _jsx("h3", { children: "Shared context" }), image ? (_jsx("img", { className: "lab-source-image", src: image, alt: "Captured image state" })) : (_jsx("p", { className: "lab-copy", title: stateText(trace), children: stateText(trace) }))] }), _jsxs("article", { className: "lab-card", style: { left: 20, top: 288, width: 240, height: 180 }, children: [_jsx("span", { className: "lab-eyebrow", children: "INSTRUCTIONS" }), _jsxs("h3", { children: ["Question \u00B7 ", question.type] }), _jsx("p", { className: "lab-copy", title: typeof question.instructions === "string"
-                                        ? question.instructions
-                                        : JSON.stringify(question.instructions), children: typeof question.instructions === "string"
-                                        ? question.instructions
-                                        : JSON.stringify(question.instructions) })] }), _jsxs("article", { className: "lab-card lab-answer-card", style: {
+                                            !["error", "cancelled"].includes(trace.status) && (_jsx("circle", { r: "3", className: "lab-flow-dot", children: _jsx("animateMotion", { dur: "3.2s", repeatCount: "indefinite", path: path.d }) }))] }, path.id))), _jsx("text", { x: "305", y: mid - 65, children: "state" }), _jsx("text", { x: "300", y: mid + 65, children: "question" })] }), _jsxs("article", { className: "lab-card lab-content-card", style: { left: 20, top: 32, width: 240, height: 180 }, children: [_jsx("span", { className: "lab-eyebrow", children: image ? "IMAGE STATE" : "STATE" }), _jsx("h3", { children: "Shared context" }), image ? (_jsx("img", { className: "lab-source-image", src: image, alt: "Captured image state" })) : (_jsx(DiagramContent, { value: trace.request.state, label: "State properties" }, trace.id))] }), _jsxs("article", { className: "lab-card lab-content-card", style: { left: 20, top: 288, width: 240, height: 180 }, children: [_jsx("span", { className: "lab-eyebrow", children: "INSTRUCTIONS" }), _jsxs("h3", { children: ["Question \u00B7 ", question.type] }), _jsx(DiagramContent, { value: question.instructions, label: "Question instructions" }, `${trace.id}:${key}`)] }), _jsxs("article", { className: "lab-card lab-answer-card", style: {
                                 left: 390,
                                 top: ry,
                                 width: 320,
                                 minHeight: resultHeight,
-                            }, children: [_jsxs("span", { className: "lab-eyebrow", children: ["JEV \u00B7 ", question.type.toUpperCase()] }), _jsx("h3", { title: key, children: key }), compact && (_jsxs("p", { className: "lab-small", children: ["Showing ", shownProbabilities.length, " of ", allProbabilities.length, " ", "probabilities"] })), _jsx(Result, { answer: answer, image: image, probabilities: compact ? shownProbabilities : undefined })] }), outputs.map((output, i) => (_jsxs("article", { className: `lab-card lab-output ${output.active ? "" : "lab-idle"} ${enteringDelay(i) !== undefined ? "lab-card-enter" : ""}`, onAnimationEnd: () => {
+                            }, children: [_jsxs("span", { className: "lab-eyebrow", children: ["JEV \u00B7 ", question.type.toUpperCase()] }), _jsx("h3", { title: key, children: key }), compact && (_jsxs("p", { className: "lab-small", children: ["Showing ", shownProbabilities.length, " of ", allProbabilities.length, " ", "probabilities"] })), _jsx(Result, { answer: answer, image: image, probabilities: compact ? shownProbabilities : undefined })] }), outputs.map((output, i) => (_jsxs("article", { className: `lab-card lab-output ${"probability" in output ? "lab-noul-output" : ""} ${output.active ? "" : "lab-idle"} ${enteringDelay(i) !== undefined ? "lab-card-enter" : ""}`, onAnimationEnd: () => {
                                 if (entering?.question === key && i === entering.to - 1)
                                     setEntering(null);
                             }, style: {
@@ -114,6 +126,12 @@ export function TraceDiagram({ trace }) {
                                 width: 230,
                                 minHeight: compact ? 96 : 104,
                                 animationDelay: enteringDelay(i),
+                                ...("probability" in output &&
+                                    Number.isFinite(output.probability)
+                                    ? {
+                                        "--lab-noul-probability": Math.max(0, Math.min(1, output.probability)),
+                                    }
+                                    : {}),
                             }, children: [_jsx("span", { className: "lab-eyebrow", children: output.eyebrow }), _jsx("h3", { title: output.label, children: output.label }), _jsx("p", { children: output.detail })] }, `${key}-${output.label}`))), remaining > 0 && (_jsxs("article", { className: "lab-card lab-choice-remainder", style: {
                                 left: 870,
                                 top: 40 + outputs.length * spacing,
@@ -130,5 +148,5 @@ export function TraceDiagram({ trace }) {
                                             ...counts,
                                             [key]: (counts[key] ?? 0) + 3,
                                         }));
-                                    }, children: "Show More" }), _jsxs("p", { className: "lab-small", children: [remaining, " remaining \u00B7 Add ", Math.min(3, remaining)] })] }))] }) }), !showProbabilities && (_jsxs("p", { className: "muted lab-flow-caption", children: [_jsx("span", { className: "lab-gesture-hint", children: "Drag to pan \u00B7 Scroll or pinch to zoom \u00B7 0 to fit" }), entries.length, " parallel question", entries.length === 1 ? "" : "s", " in one request. Connections show data flow, not model timing. Application routes and thresholds are not captured. Full inputs and criteria are in Questions and Context."] }))] }));
+                                    }, children: "Show More" }), _jsxs("p", { className: "lab-small", children: [remaining, " remaining \u00B7 Add ", Math.min(3, remaining)] })] }))] }) }), !showProbabilities && !embedded && (_jsxs("p", { className: "muted lab-flow-caption", children: [_jsx("span", { className: "lab-gesture-hint", children: "Drag to pan \u00B7 Scroll or pinch to zoom \u00B7 0 to fit" }), entries.length, " parallel question", entries.length === 1 ? "" : "s", " in one request. Connections show data flow, not model timing. Application routes and thresholds are not captured. Full inputs and criteria are in Questions and Context."] }))] }));
 }

package/lib/src/condition-inputs.d.ts

@@ -0,0 +1,9 @@
+import type { Json, Trace } from "./protocol.js";
+import type { FlowRun } from "./flow-protocol.js";
+export type ConditionInput = {
+    reference: string;
+    name: string;
+    value: string;
+};
+export declare function conditionInputs(rule: Json, run: FlowRun, traces: Map<string, Trace>, stepNames?: Map<string, string>): ConditionInput[];
+export declare function conditionRequirement(rule: Json, inputs: ConditionInput[]): string;

package/lib/src/condition-inputs.js

@@ -0,0 +1,109 @@
+import { formatFlowCondition, formatConditionLiteral, } from "./flow-condition.js";
+export function conditionInputs(rule, run, traces, stepNames = new Map()) {
+    const inputs = new Map();
+    const sources = new Map();
+    const visit = (node, depth = 0) => {
+        if (depth > 16 || !node || typeof node !== "object" || Array.isArray(node))
+            return;
+        if (node.op === "reference" &&
+            typeof node.label === "string" &&
+            !inputs.has(node.label)) {
+            const name = typeof node.name === "string" ? node.name : "Input";
+            const readable = name
+                .replace(/[_-]+/g, " ")
+                .replace(/([a-z])([A-Z])/g, "$1 $2");
+            const trace = typeof node.stepId === "string"
+                ? traces.get(run.steps[node.stepId]?.traceId ?? "")
+                : undefined;
+            let value = trace?.result;
+            let available = !!trace?.result;
+            if (node.source === "task" && typeof node.stepId === "string") {
+                const data = run.steps[node.stepId]?.data;
+                available =
+                    !!data &&
+                        typeof data === "object" &&
+                        !Array.isArray(data) &&
+                        Object.hasOwn(data, "output");
+                value = available ? data.output : undefined;
+            }
+            if (!Array.isArray(node.path) ||
+                !node.path.every((key) => typeof key === "string"))
+                available = false;
+            else
+                for (const key of node.path) {
+                    if (!available ||
+                        !value ||
+                        typeof value !== "object" ||
+                        !Object.hasOwn(value, String(key))) {
+                        available = false;
+                        break;
+                    }
+                    value = value[String(key)];
+                }
+            const text = !available
+                ? "Not captured"
+                : node.probability === true &&
+                    typeof value === "number" &&
+                    Number.isFinite(value)
+                    ? formatConditionLiteral(value, true)
+                    : typeof value === "object" && value !== null
+                        ? "Structured value"
+                        : String(value);
+            if (typeof node.stepId === "string")
+                sources.set(node.label, stepNames.get(node.stepId) ?? node.stepId);
+            inputs.set(node.label, {
+                reference: node.label,
+                name: readable.charAt(0).toUpperCase() + readable.slice(1),
+                value: text,
+            });
+        }
+        if (Array.isArray(node.args))
+            for (const arg of node.args)
+                visit(arg, depth + 1);
+    };
+    visit(rule);
+    const list = [...inputs.values()];
+    return list.map((input) => list.filter((other) => other.name === input.name).length > 1
+        ? {
+            ...input,
+            name: `${input.name} · ${sources.get(input.reference) ?? input.reference}`,
+        }
+        : input);
+}
+export function conditionRequirement(rule, inputs) {
+    const names = new Map(inputs.map((input) => [input.reference, input.name]));
+    // A single reference-to-literal comparison already has its subject in Incoming.
+    if (rule &&
+        typeof rule === "object" &&
+        !Array.isArray(rule) &&
+        Array.isArray(rule.args) &&
+        rule.args.length === 2) {
+        const [left, right] = rule.args;
+        if (left &&
+            right &&
+            typeof left === "object" &&
+            typeof right === "object" &&
+            !Array.isArray(left) &&
+            !Array.isArray(right) &&
+            left.op === "reference" &&
+            right.op === "literal" &&
+            ["gte", "lt", "gt", "eq"].includes(String(rule.op))) {
+            return `${rule.op === "gte" ? "At least" : rule.op === "lt" ? "Less than" : rule.op === "gt" ? "Greater than" : "Equal to"} ${formatConditionLiteral(right.value, left.probability === true)}`;
+        }
+    }
+    const rename = (node, depth = 0) => {
+        if (depth > 16 || !node || typeof node !== "object" || Array.isArray(node))
+            return node;
+        if (node.op === "reference")
+            return {
+                ...node,
+                label: typeof node.label === "string"
+                    ? names.get(node.label) ?? "Input"
+                    : "Input",
+            };
+        if (Array.isArray(node.args))
+            return { ...node, args: node.args.map((arg) => rename(arg, depth + 1)) };
+        return node;
+    };
+    return formatFlowCondition(rename(rule));
+}

package/lib/src/flow-condition.d.ts

@@ -0,0 +1,4 @@
+import type { Json } from "./protocol.js";
+export declare function formatConditionLiteral(value: Json, probability?: boolean): string;
+/** Format captured rules only; never evaluate or infer the branch result. */
+export declare function formatFlowCondition(value: Json, depth?: number): string;

package/lib/src/flow-condition.js

@@ -0,0 +1,48 @@
+export function formatConditionLiteral(value, probability = false) {
+    if (probability && typeof value === "number" && value >= 0 && value <= 1) {
+        const [coefficient, exponent = "0"] = String(value).split("e");
+        return `${Number(`${coefficient}e${Number(exponent) + 2}`)}%`;
+    }
+    return JSON.stringify(value) ?? "[value unavailable]";
+}
+/** Format captured rules only; never evaluate or infer the branch result. */
+export function formatFlowCondition(value, depth = 0) {
+    if (depth > 16)
+        return "[rule truncated]";
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return typeof value === "string" ? value : "[rule unavailable]";
+    if (value.op === "reference")
+        return typeof value.label === "string"
+            ? value.label
+            : "[reference unavailable]";
+    if (value.op === "literal")
+        return formatConditionLiteral(value.value);
+    if (!Array.isArray(value.args))
+        return "[rule unavailable]";
+    const args = value.args;
+    const format = (v) => formatFlowCondition(v, depth + 1);
+    if (value.op === "not")
+        return `NOT (${format(args[0])})`;
+    if (value.op === "all" || value.op === "any") {
+        if (!args.length)
+            return value.op === "all"
+                ? "TRUE (no conditions)"
+                : "FALSE (no conditions)";
+        return `(${args.map(format).join(value.op === "all" ? " AND " : " OR ")})`;
+    }
+    if (!["eq", "lt", "gt", "gte"].includes(String(value.op)) ||
+        args.length !== 2)
+        return "[rule unavailable]";
+    const probability = args.some((arg) => arg &&
+        typeof arg === "object" &&
+        !Array.isArray(arg) &&
+        arg.op === "reference" &&
+        arg.probability === true);
+    const operand = (arg) => arg &&
+        typeof arg === "object" &&
+        !Array.isArray(arg) &&
+        arg.op === "literal"
+        ? formatConditionLiteral(arg.value, probability)
+        : format(arg);
+    return `${operand(args[0])} ${value.op === "eq" ? "=" : value.op === "lt" ? "<" : value.op === "gt" ? ">" : "≥"} ${operand(args[1])}`;
+}

package/lib/src/flow-model.d.ts

@@ -1,9 +1,14 @@
-import type { AnswerView, Json, Trace } from "./protocol.js";
+import type { AnswerView, Json } from "./protocol.js";
 export declare function findImage(value: Json): string | undefined;
 export declare function flowAnswer(answer?: AnswerView): {
     label: string;
     detail: string;
     active: boolean;
     eyebrow: string;
+}[] | {
+    label: string;
+    detail: string;
+    active: boolean;
+    eyebrow: string;
+    probability: number;
 }[];
-export declare function stateText(trace: Trace): string;

package/lib/src/flow-model.js

@@ -37,12 +37,14 @@ export function flowAnswer(answer) {
                 detail: `${Math.round(answer.noul * 100)}% probability`,
                 active: true,
                 eyebrow: "P(TRUE)",
+                probability: answer.noul,
             },
             {
                 label: "False",
                 detail: `${Math.round((1 - answer.noul) * 100)}% probability`,
                 active: true,
                 eyebrow: "P(FALSE)",
+                probability: 1 - answer.noul,
             },
         ];
     if (answer.type === "box")
@@ -56,14 +58,3 @@ export function flowAnswer(answer) {
         ];
     return [];
 }
-export function stateText(trace) {
-    const state = trace.request.state;
-    if (typeof state === "string")
-        return state;
-    if (state && typeof state === "object" && !Array.isArray(state)) {
-        for (const key of ["message", "text", "description"])
-            if (typeof state[key] === "string")
-                return state[key];
-    }
-    return JSON.stringify(state, null, 2) ?? "";
-}

package/lib/src/flow-protocol.d.ts

@@ -0,0 +1,93 @@
+import type { Json } from "./protocol.js";
+/** Authored diagram copy, never instructions for Jev or executable routing logic. */
+export type FlowDisplay = {
+    title?: string;
+    description?: string;
+};
+/** Rule literals are captured/redacted by the recorder before browser delivery. */
+export type FlowCondition = {
+    op: "reference";
+    label: string;
+    probability: boolean;
+    name?: string;
+    stepId?: string;
+    path?: string[];
+    source?: "task";
+} | {
+    op: "literal";
+    value: string | number | boolean | null;
+} | {
+    op: "eq" | "lt" | "gt" | "gte" | "all" | "any" | "not";
+    args: FlowCondition[];
+};
+/** Structural metadata and authored rules; runtime inputs/answers stay in request captures. */
+export type FlowNode = FlowDisplay & {
+    id: string;
+    kind: "jev" | "task" | "map" | "loop" | "if" | "merge" | "branch" | "parallel" | "output";
+    dependencies: string[];
+    path: string[];
+    condition?: string;
+    /** Conditional merge edges; only the selected arm supplies a value. */
+    merge?: {
+        condition: string;
+        then: string;
+        else: string;
+    };
+    /** Optional for older captures; Json allows redacted/truncated subtrees. */
+    conditionRule?: Json | FlowCondition;
+    /** Named concurrent lanes; optional for older captures. */
+    lanes?: string[];
+    /** Reusable item program; map nesting is not supported in v1. */
+    itemDefinition?: FlowDefinition;
+};
+export type FlowDefinition = {
+    version: 1;
+    id: string;
+    name: string;
+    nodes: FlowNode[];
+};
+export type FlowStep = {
+    id: string;
+    executionId: string;
+    status: "waiting" | "running" | "completed" | "untaken" | "blocked" | "error" | "cancelled";
+    startedAt?: number;
+    durationMs?: number;
+    decision?: boolean;
+    traceId?: string;
+    error?: string;
+    /** Optional bounded, redacted task input/output or selected merge value; never executable code. */
+    data?: Json;
+    captureWarnings?: string[];
+    loop?: {
+        maxIterations: number;
+        stopReason?: "condition" | "limit";
+    };
+    collection?: {
+        total: number;
+        concurrency: number;
+        items: Array<{
+            index: number;
+            status: FlowStep["status"];
+            run?: FlowRun;
+        }>;
+    };
+};
+export type FlowRun = {
+    version: 1;
+    id: string;
+    definitionId: string;
+    name: string;
+    startedAt: number;
+    durationMs?: number;
+    status: "pending" | "success" | "error" | "cancelled";
+    steps: Record<string, FlowStep>;
+    outcome?: string;
+    value?: Json;
+    error?: string;
+};
+export type FlowUpdate = {
+    version: 1;
+    definitions: FlowDefinition[];
+    upserts: FlowRun[];
+    order: string[];
+};

package/lib/src/flow-protocol.js

@@ -0,0 +1 @@
+export {};

package/lib/src/flow-stream.d.ts

@@ -0,0 +1,8 @@
+import type { FlowDefinition, FlowRun } from "./flow-protocol.js";
+export type FlowHistory = {
+    runs: FlowRun[];
+    definitions: FlowDefinition[];
+};
+export declare const emptyFlows: FlowHistory;
+/** Separate opt-in stream; no extra rendering of request rows on flow-only updates. */
+export declare function connectFlowStream(url: string, onUpdate: (history: FlowHistory) => void): () => void;

package/lib/src/flow-stream.js

@@ -0,0 +1,80 @@
+export const emptyFlows = { runs: [], definitions: [] };
+/** Separate opt-in stream; no extra rendering of request rows on flow-only updates. */
+export function connectFlowStream(url, onUpdate) {
+    let alive = true, source, frame, fallback, retry;
+    let runs = new Map(), definitions = new Map(), pending;
+    const cancel = () => {
+        if (frame !== undefined)
+            cancelAnimationFrame(frame);
+        clearTimeout(fallback);
+        frame = undefined;
+        pending = undefined;
+    };
+    const publish = () => {
+        const next = pending;
+        cancel();
+        if (alive && next)
+            onUpdate(next);
+    };
+    const connect = () => {
+        if (!alive)
+            return;
+        runs = new Map();
+        definitions = new Map();
+        const current = new EventSource(url + "/flows/events");
+        source = current;
+        current.addEventListener("flows", (event) => {
+            if (!alive || source !== current)
+                return;
+            try {
+                const data = JSON.parse(event.data);
+                if (data.version !== 1 ||
+                    !Array.isArray(data.order) ||
+                    data.order.length > 200 ||
+                    new Set(data.order).size !== data.order.length ||
+                    !Array.isArray(data.upserts) ||
+                    !Array.isArray(data.definitions))
+                    throw new Error("Invalid flow stream");
+                for (const definition of data.definitions) {
+                    if (definition.version !== 1 ||
+                        !Array.isArray(definition.nodes) ||
+                        definition.nodes.length > 256)
+                        throw new Error("Invalid flow definition");
+                    if (!definitions.has(definition.id))
+                        definitions.set(definition.id, definition);
+                }
+                for (const run of data.upserts) {
+                    if (run.version !== 1 || !definitions.has(run.definitionId))
+                        throw new Error("Invalid flow run");
+                    runs.set(run.id, run);
+                }
+                const ordered = data.order.map((id) => {
+                    const run = runs.get(id);
+                    if (!run)
+                        throw new Error("Missing run");
+                    return run;
+                });
+                runs = new Map(ordered.map((r) => [r.id, r]));
+                const used = new Set(ordered.map((r) => r.definitionId));
+                definitions = new Map([...definitions].filter(([id]) => used.has(id)));
+                pending = { runs: ordered, definitions: [...definitions.values()] };
+                if (frame === undefined) {
+                    frame = requestAnimationFrame(publish);
+                    fallback = setTimeout(publish, 100);
+                }
+            }
+            catch {
+                cancel();
+                current.close();
+                retry = setTimeout(connect, 1000);
+            }
+        });
+    };
+    connect();
+    return () => {
+        alive = false;
+        cancel();
+        clearTimeout(retry);
+        source?.close();
+    };
+}