@tangle-network/sandbox-ui 0.92.0 → 0.93.1

package/dist/{WorkflowGraph-GUX7XN7Y.js → WorkflowGraph-YII62JEW.js}

@@ -10,8 +10,9 @@ import {
   fmtDuration,
   fmtTokens,
   providerLabel,
-  shortModel
-} from "./chunk-2NS724P4.js";
+  shortModel,
+  triggerNodeIndex
+} from "./chunk-YOSNN3QU.js";
 import {
   ModelBrandStack,
   modelBrandFor
@@ -22,8 +23,11 @@ import "./chunk-CZ7CSFO4.js";
 // src/workflows/WorkflowGraph.tsx
 import {
   Background,
+  BaseEdge,
   Controls,
+  EdgeLabelRenderer,
   getNodesBounds,
+  getSmoothStepPath,
   getViewportForBounds,
   Handle,
   MarkerType,
@@ -47,6 +51,7 @@ import {
 
 // src/workflows/flow-graph.ts
 import { Position } from "@xyflow/react";
+var WF_EDGE_TYPE = "wfEdge";
 function isNodeStateMap(arg) {
   const values = Object.values(arg);
   return values.length > 0 && values.every(
@@ -55,7 +60,7 @@ function isNodeStateMap(arg) {
 }
 function normalizeFlowGraphOptions(arg) {
   if (!arg) return {};
-  if ("nodeState" in arg || "direction" in arg || "compact" in arg) {
+  if ("nodeState" in arg || "direction" in arg || "compact" in arg || "edges" in arg) {
     return arg;
   }
   return isNodeStateMap(arg) ? { nodeState: arg } : {};
@@ -68,7 +73,8 @@ function buildFlowGraph(yaml, optionsOrNodeState) {
   const graph = buildWorkflowGraph(yaml, {
     reserveRunState: nodeState !== void 0,
     direction,
-    compact
+    compact,
+    ...options.edges ? { edges: options.edges } : {}
   });
   const isLR = direction === "LR";
   const sourcePosition = isLR ? Position.Right : Position.Bottom;
@@ -82,6 +88,13 @@ function buildFlowGraph(yaml, optionsOrNodeState) {
         position: n.position,
         width: n.width,
         height: n.height,
+        // A node is a `do` entry, and removing one is a list edit — never a
+        // canvas gesture. This matters most on an EDITABLE canvas, where the
+        // delete key is armed for edges: React Flow deletes a selected node
+        // together with every edge touching it, so a node left deletable would
+        // vanish from the canvas AND report each of its edges as removed,
+        // asking the host to drop declared edges nobody touched.
+        deletable: false,
         // Fix the DOM box to the laid-out size so the card can't grow past its
         // reserved space and overlap a neighbour (see model.ts nodeHeight).
         style: { width: n.width, height: n.height },
@@ -90,12 +103,20 @@ function buildFlowGraph(yaml, optionsOrNodeState) {
         data: nodeState?.[n.id] ? { ...n.data, state: nodeState[n.id] } : n.data
       })
     ),
-    edges: graph.edges.map((e) => ({
-      id: e.id,
-      source: e.source,
-      target: e.target,
-      type: "smoothstep"
-    }))
+    edges: graph.edges.map((e) => {
+      const decorated = e.whenLabel !== void 0 || e.backEdge === true;
+      return {
+        id: e.id,
+        source: e.source,
+        target: e.target,
+        type: decorated ? WF_EDGE_TYPE : "smoothstep",
+        data: {
+          kind: e.kind,
+          ...e.whenLabel !== void 0 ? { whenLabel: e.whenLabel } : {},
+          ...e.backEdge === true ? { backEdge: true } : {}
+        }
+      };
+    })
   };
 }
 function sameRunState(a, b) {
@@ -248,10 +269,13 @@ import {
   Bell,
   Box,
   Cable,
+  Camera,
   Circle,
   Clock,
+  Code,
   GitBranch,
   Repeat,
+  ScanSearch,
   Sparkles,
   UserCheck,
   Webhook,
@@ -335,7 +359,11 @@ function progressFill(status) {
 }
 var KIND_ICON = {
   schedule: Clock,
+  // Both wake the workflow on an inbound POST, so they share the mark. A
+  // `provider_event` normally shows its provider's LOGO instead and reaches this
+  // glyph only when the connector has none.
   provider_event: Webhook,
+  webhook: Webhook,
   trigger: Zap,
   "agent.run": Sparkles,
   "integration.invoke": Cable,
@@ -343,7 +371,10 @@ var KIND_ICON = {
   parallel: GitBranch,
   foreach: Repeat,
   decision: UserCheck,
-  "sandbox.spawn": Box
+  "sandbox.spawn": Box,
+  "sandbox.snapshot": Camera,
+  "script.run": Code,
+  "trace.analyze": ScanSearch
 };
 function NodeMark({
   kind,
@@ -421,6 +452,15 @@ function useColorMode() {
 }
 var DirectionContext = createContext("LR");
 var DensityContext = createContext(false);
+var SelectedNodeContext = createContext(void 0);
+var SELECTION_OUTLINE = {
+  outline: "2px solid hsl(var(--primary))",
+  outlineOffset: 2
+};
+var ConnectableContext = createContext(false);
+function isEditableEdge(edge) {
+  return edge.data?.kind !== "fork" && triggerNodeIndex(edge.source) === null;
+}
 function StatusFooter({
   status,
   rounds,
@@ -475,6 +515,7 @@ function StatusPill({ status }) {
   );
 }
 var HANDLE_CLASS = "!h-2 !w-2 !min-w-0 !border-0 !bg-transparent opacity-0";
+var HANDLE_CONNECTABLE_CLASS = "!h-2.5 !w-2.5 !min-w-0 !rounded-full !border !border-border !bg-muted-foreground/70 opacity-100 transition-opacity hover:!bg-primary";
 function compactHandleStyle(position, isLR) {
   const tileLeft = isLR ? (COMPACT_NODE_SIZE.width - COMPACT_TILE) / 2 : 0;
   const center = COMPACT_TILE / 2;
@@ -496,11 +537,14 @@ function compactHandleStyle(position, isLR) {
       return anchor(tileLeft + center, COMPACT_TILE);
   }
 }
-function WorkflowNode({ data }) {
+function WorkflowNode({ id, data }) {
   const d = data;
   const state = d.state;
   const direction = useContext(DirectionContext);
   const compact = useContext(DensityContext);
+  const connectable = useContext(ConnectableContext);
+  const hostSelection = useContext(SelectedNodeContext);
+  const selected = hostSelection !== void 0 && hostSelection === id;
   const isLR = direction === "LR";
   const targetPos = isLR ? Position2.Left : Position2.Top;
   const sourcePos = isLR ? Position2.Right : Position2.Bottom;
@@ -527,13 +571,14 @@ function WorkflowNode({ data }) {
     );
     return shape.kind === "empty" ? null : { shape, tone: source.tone, label: source.label };
   })();
+  const handleClass = connectable ? HANDLE_CONNECTABLE_CLASS : HANDLE_CLASS;
   const handles = /* @__PURE__ */ jsxs2(Fragment, { children: [
     !d.isRoot && /* @__PURE__ */ jsx3(
       Handle,
       {
         type: "target",
         position: targetPos,
-        className: HANDLE_CLASS,
+        className: handleClass,
         style: compact ? compactHandleStyle(targetPos, isLR) : void 0
       }
     ),
@@ -542,7 +587,7 @@ function WorkflowNode({ data }) {
       {
         type: "source",
         position: sourcePos,
-        className: HANDLE_CLASS,
+        className: handleClass,
         style: compact ? compactHandleStyle(sourcePos, isLR) : void 0
       }
     )
@@ -563,7 +608,10 @@ function WorkflowNode({ data }) {
                 height: COMPACT_TILE,
                 ...state ? statusBorder(state.status) : {
                   borderColor: `color-mix(in srgb, ${accent} 40%, hsl(var(--border)))`
-                }
+                },
+                // The TILE is the compact node (the name beside it is unboxed), so
+                // the selection ring belongs to it and not to the wider box.
+                ...selected ? SELECTION_OUTLINE : {}
               },
               children: [
                 /* @__PURE__ */ jsx3("span", { className: "wf-node-body-in flex items-center justify-center", children: /* @__PURE__ */ jsx3(
@@ -624,8 +672,11 @@ function WorkflowNode({ data }) {
     "div",
     {
       className: "relative flex h-full w-full flex-col overflow-hidden rounded-xl border bg-card shadow-sm transition-colors",
-      style: state ? statusBorder(state.status) : {
-        borderColor: `color-mix(in srgb, ${accent} 40%, hsl(var(--border)))`
+      style: {
+        ...state ? statusBorder(state.status) : {
+          borderColor: `color-mix(in srgb, ${accent} 40%, hsl(var(--border)))`
+        },
+        ...selected ? SELECTION_OUTLINE : {}
       },
       children: [
         handles,
@@ -695,22 +746,88 @@ function WorkflowNode({ data }) {
     }
   );
 }
+var EDGE_CHIP_CLASS = "rounded-full border border-border bg-card/90 px-1.5 py-[1px] text-[10px] leading-tight backdrop-blur";
+function WfEdgeRenderer({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  data,
+  markerEnd,
+  style
+}) {
+  const [path, labelX, labelY] = getSmoothStepPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition
+  });
+  const backEdge = data?.backEdge === true;
+  const whenLabel = data?.whenLabel;
+  const visits = data?.maxNodeVisits;
+  return /* @__PURE__ */ jsxs2(Fragment, { children: [
+    /* @__PURE__ */ jsx3(BaseEdge, { id, path, markerEnd, style }),
+    /* @__PURE__ */ jsx3(EdgeLabelRenderer, { children: /* @__PURE__ */ jsxs2(
+      "div",
+      {
+        className: "nodrag nopan absolute flex flex-col items-center gap-0.5",
+        style: {
+          transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)`
+        },
+        children: [
+          whenLabel && /* @__PURE__ */ jsx3(
+            "span",
+            {
+              title: whenLabel,
+              className: `${EDGE_CHIP_CLASS} max-w-40 truncate text-muted-foreground`,
+              children: whenLabel
+            }
+          ),
+          backEdge && /* @__PURE__ */ jsx3(
+            "span",
+            {
+              title: visits !== void 0 ? `Loops back \u2014 each node runs at most ${visits} time${visits === 1 ? "" : "s"} per run` : "Loops back to a step that has already run",
+              className: `${EDGE_CHIP_CLASS} shrink-0 text-foreground`,
+              children: visits !== void 0 ? `\u21BA \u2264${visits}` : "\u21BA"
+            }
+          )
+        ]
+      }
+    ) })
+  ] });
+}
 var NODE_TYPES = { wfNode: WorkflowNode };
-function buildStyledEdges(base, nodeState) {
+var EDGE_TYPES = { [WF_EDGE_TYPE]: WfEdgeRenderer };
+function buildStyledEdges(base, nodeState, maxNodeVisits) {
   return base.map((e) => {
     const status = nodeState?.[e.target]?.status;
     const color = edgeColor(nodeState ? status : void 0);
+    const backEdge = e.data?.backEdge === true;
     return {
       ...e,
-      // The active hop flows; everything else is static.
-      animated: status === "running",
-      style: { strokeWidth: 1.75, stroke: color },
+      // The active hop flows; everything else is static. A cycle-closing edge
+      // never flows even into a running target: it is the loop's RETURN path,
+      // and animating it would read as the run travelling backwards.
+      animated: !backEdge && status === "running",
+      style: {
+        strokeWidth: 1.75,
+        stroke: color,
+        // Dashed, so a return path is distinguishable from a forward hop before
+        // its badge is read — and at a zoom where the badge isn't legible.
+        ...backEdge ? { strokeDasharray: "6 3" } : {}
+      },
       markerEnd: {
         type: MarkerType.ArrowClosed,
         width: 15,
         height: 15,
         color
-      }
+      },
+      ...backEdge && maxNodeVisits !== void 0 && e.data ? { data: { ...e.data, maxNodeVisits } } : {}
     };
   });
 }
@@ -721,28 +838,41 @@ function WorkflowGraph({
   defaultCompact = true,
   className,
   nodeState,
-  onNodeClick
+  edges: declaredEdges,
+  maxNodeVisits,
+  selectedNodeId,
+  onNodeClick,
+  onEdgeConnect,
+  onEdgeDelete,
+  onEdgeClick
 }) {
+  const editable = onEdgeConnect !== void 0;
   const colorMode = useColorMode();
   const isPreview = variant === "preview";
   const [userCompact, setUserCompact] = useState(defaultCompact);
   const compact = isPreview || userCompact;
   const [displayCompact, setDisplayCompact] = useState(compact);
-  const rfRef = useRef(null);
+  const rfRef = useRef(
+    null
+  );
   const wrapperRef = useRef(null);
   const hasRunOverlay = nodeState !== void 0;
   const structural = useMemo(
     () => buildFlowGraph(yaml, {
       nodeState: hasRunOverlay ? {} : void 0,
       direction,
-      compact
+      compact,
+      ...declaredEdges ? { edges: declaredEdges } : {}
     }),
-    [yaml, hasRunOverlay, direction, compact]
-  );
-  const styledEdges = useMemo(
-    () => buildStyledEdges(structural.edges, nodeState),
-    [structural.edges, nodeState]
+    [yaml, hasRunOverlay, direction, compact, declaredEdges]
   );
+  const styledEdges = useMemo(() => {
+    const styled = buildStyledEdges(structural.edges, nodeState, maxNodeVisits);
+    return styled.map((e) => ({
+      ...e,
+      deletable: editable ? isEditableEdge(e) : false
+    }));
+  }, [structural.edges, nodeState, maxNodeVisits, editable]);
   const [nodes, setNodes, onNodesChange] = useNodesState(structural.nodes);
   const [edges, setEdges, onEdgesChange] = useEdgesState(styledEdges);
   const nodesRef = useRef(nodes);
@@ -844,6 +974,20 @@ function WorkflowGraph({
     },
     [onNodeClick]
   );
+  const handleNodeKeyDown = useCallback(
+    (event) => {
+      if (event.key !== "Enter" && event.key !== " ") return;
+      if (!(event.target instanceof HTMLElement)) return;
+      const nodeId = event.target.closest(".react-flow__node")?.getAttribute("data-id");
+      if (!nodeId) return;
+      const node = nodesRef.current.find((n) => n.id === nodeId);
+      if (!node) return;
+      event.preventDefault();
+      event.stopPropagation();
+      onNodeClick?.(node.id, node.data);
+    },
+    [onNodeClick]
+  );
   if (structural.error || structural.nodes.length === 0) {
     return /* @__PURE__ */ jsx3(
       "div",
@@ -853,7 +997,7 @@ function WorkflowGraph({
       }
     );
   }
-  return /* @__PURE__ */ jsx3(DirectionContext.Provider, { value: direction, children: /* @__PURE__ */ jsx3(DensityContext.Provider, { value: displayCompact, children: /* @__PURE__ */ jsx3("div", { ref: wrapperRef, className: `wf-graph ${className ?? ""}`, children: /* @__PURE__ */ jsxs2(
+  return /* @__PURE__ */ jsx3(DirectionContext.Provider, { value: direction, children: /* @__PURE__ */ jsx3(DensityContext.Provider, { value: displayCompact, children: /* @__PURE__ */ jsx3(SelectedNodeContext.Provider, { value: selectedNodeId, children: /* @__PURE__ */ jsx3(ConnectableContext.Provider, { value: editable, children: /* @__PURE__ */ jsx3("div", { ref: wrapperRef, className: `wf-graph ${className ?? ""}`, children: /* @__PURE__ */ jsxs2(
     ReactFlow,
     {
       nodes,
@@ -861,20 +1005,39 @@ function WorkflowGraph({
       onNodesChange,
       onEdgesChange,
       nodeTypes: NODE_TYPES,
+      edgeTypes: EDGE_TYPES,
       colorMode,
       onInit: (inst) => {
         rfRef.current = inst;
       },
       onNodeClick: onNodeClick ? handleNodeClick : void 0,
+      onKeyDown: onNodeClick ? handleNodeKeyDown : void 0,
       fitView: true,
       fitViewOptions: { ...FIT_VIEW, maxZoom: fitZoomCeiling(compact) },
       proOptions: { hideAttribution: true },
       nodesDraggable: !isPreview,
-      nodesConnectable: false,
-      deleteKeyCode: null,
+      nodesConnectable: editable,
+      deleteKeyCode: editable ? ["Backspace", "Delete"] : null,
       edgesReconnectable: false,
       elementsSelectable: !isPreview,
-      edgesFocusable: false,
+      edgesFocusable: editable,
+      onConnect: editable ? (connection) => {
+        if (connection.source && connection.target) {
+          onEdgeConnect(connection.source, connection.target);
+        }
+      } : void 0,
+      onEdgesDelete: editable ? (deleted) => {
+        for (const edge of deleted) {
+          if (isEditableEdge(edge)) {
+            onEdgeDelete?.(edge.source, edge.target);
+          }
+        }
+      } : void 0,
+      onEdgeClick: editable ? (_event, edge) => {
+        if (isEditableEdge(edge)) {
+          onEdgeClick?.(edge.source, edge.target);
+        }
+      } : void 0,
       zoomOnScroll: false,
       zoomOnPinch: true,
       zoomOnDoubleClick: !isPreview,
@@ -903,14 +1066,17 @@ function WorkflowGraph({
         ] })
       ]
     }
-  ) }) }) });
+  ) }) }) }) }) });
 }
 export {
+  ConnectableContext,
   DensityContext,
   DirectionContext,
   LAYOUT_TRANSITION_MS,
+  SelectedNodeContext,
   WorkflowGraph,
   WorkflowNode,
   buildStyledEdges,
-  fitZoomCeiling
+  fitZoomCeiling,
+  isEditableEdge
 };

package/dist/{chunk-2NS724P4.js → chunk-YOSNN3QU.js}

@@ -214,9 +214,26 @@ function providerLabel(provider) {
 
 // src/workflows/model.ts
 import { parse as parseYaml } from "yaml";
+var TRIGGER_NODE_ID = "trigger";
+var TRIGGER_NODE_ID_PATTERN = new RegExp(`^${TRIGGER_NODE_ID}:(\\d+)$`);
+function triggerNodeId(index) {
+  return index === 0 ? TRIGGER_NODE_ID : `${TRIGGER_NODE_ID}:${index}`;
+}
+function triggerNodeIndex(nodeId) {
+  if (nodeId === TRIGGER_NODE_ID) return 0;
+  const match = TRIGGER_NODE_ID_PATTERN.exec(nodeId);
+  return match ? Number(match[1]) : null;
+}
+function actionNodeId(index) {
+  return `a${index}`;
+}
+function branchNodeId(actionIndex, branchIndex) {
+  return `${actionNodeId(actionIndex)}-b${branchIndex}`;
+}
 var NODE_W = 292;
 var RANK_SEP = 72;
 var CROSS_SEP = 24;
+var EDGE_LABEL_LANE = 180;
 var CARD_CHROME = 20;
 var HEADER_ROW = 34;
 var DESCRIPTION_ROW = 40;
@@ -372,6 +389,50 @@ function describeActionBase(action) {
         tone: "structural"
       };
     }
+    case "script.run": {
+      const connections = Array.isArray(cfg.connections) ? cfg.connections.filter((c) => typeof c === "string") : [];
+      return {
+        title: "Script",
+        kind,
+        // What the box is GRANTED is the thing that distinguishes one script
+        // step from another at a glance; the timeout is a bound, and bounds read
+        // in the detail view with the rest of the config.
+        subtitle: connections.length > 0 ? `TypeScript \xB7 ${connections.length} connection${connections.length === 1 ? "" : "s"}` : "TypeScript",
+        // The head of the module — the same role the prompt plays on an agent:
+        // the text that says what this particular step actually does.
+        description: describeText(cfg.source),
+        isRoot: false,
+        tone: "action"
+      };
+    }
+    case "sandbox.snapshot":
+      return {
+        title: "Snapshot",
+        kind,
+        // WHICH sandbox is the only thing separating one snapshot step from
+        // another, and it is usually a `${steps…}` reference — so the subtitle
+        // reads as the step whose disk is being captured.
+        subtitle: str(cfg.sandbox) ?? "Capture a sandbox",
+        isRoot: false,
+        tone: "action"
+      };
+    case "trace.analyze": {
+      const kinds = Array.isArray(cfg.kinds) ? cfg.kinds.filter((k) => typeof k === "string") : [];
+      return {
+        title: "Trace analysis",
+        kind,
+        // The analysts that run ARE the step. The model it runs them on is
+        // incidental here (unlike agent.run, where the model IS the identity),
+        // so it stays in the config for the detail view and the node keeps its
+        // own glyph rather than borrowing a lab's brand mark.
+        subtitle: kinds.length > 0 ? describeText(
+          kinds.map((k) => humanizeIdentifier(k, "lower")).join(", ")
+        ) : "Default analysts",
+        description: describeText(cfg.trace),
+        isRoot: false,
+        tone: "action"
+      };
+    }
     default:
       return {
         // An action kind this version doesn't model yet still gets a readable
@@ -465,6 +526,18 @@ function describeTrigger(on) {
       sch
     );
   }
+  if (rec.webhook !== void 0) {
+    return withConfig(
+      {
+        title: "Webhook",
+        kind: "webhook",
+        subtitle: "On an inbound POST",
+        isRoot: true,
+        tone: "trigger"
+      },
+      asRecord(rec.webhook)
+    );
+  }
   const [kind] = Object.keys(rec);
   return withConfig(
     {
@@ -519,10 +592,74 @@ function layoutLayers(nodes, direction, rankSep, crossSep) {
   }
   return out;
 }
+function classifyBackEdges(orderedIds, edges) {
+  const outgoing = /* @__PURE__ */ new Map();
+  const hasIncoming = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    const list = outgoing.get(e.source);
+    if (list) list.push(e);
+    else outgoing.set(e.source, [e]);
+    hasIncoming.add(e.target);
+  }
+  const walkOrder = [
+    ...orderedIds.filter((id) => !hasIncoming.has(id)),
+    ...orderedIds.filter((id) => hasIncoming.has(id))
+  ];
+  const back = /* @__PURE__ */ new Set();
+  const color = new Map(orderedIds.map((id) => [id, 0]));
+  for (const start of walkOrder) {
+    if (color.get(start) !== 0) continue;
+    color.set(start, 1);
+    const stack = [{ id: start, next: 0 }];
+    while (stack.length > 0) {
+      const frame = stack[stack.length - 1];
+      const out = outgoing.get(frame.id);
+      if (!out || frame.next >= out.length) {
+        color.set(frame.id, 2);
+        stack.pop();
+        continue;
+      }
+      const edge = out[frame.next];
+      frame.next += 1;
+      const target = color.get(edge.target);
+      if (target === 1) {
+        back.add(edge.id);
+      } else if (target === 0) {
+        color.set(edge.target, 1);
+        stack.push({ id: edge.target, next: 0 });
+      }
+    }
+  }
+  return back;
+}
+function rankByTopology(orderedIds, edges, backEdgeIds) {
+  const outgoing = /* @__PURE__ */ new Map();
+  const indegree = new Map(orderedIds.map((id) => [id, 0]));
+  for (const e of edges) {
+    if (backEdgeIds.has(e.id)) continue;
+    const list = outgoing.get(e.source);
+    if (list) list.push(e);
+    else outgoing.set(e.source, [e]);
+    indegree.set(e.target, (indegree.get(e.target) ?? 0) + 1);
+  }
+  const rank = new Map(orderedIds.map((id) => [id, 0]));
+  const queue = orderedIds.filter((id) => indegree.get(id) === 0);
+  for (let head = 0; head < queue.length; head += 1) {
+    const id = queue[head];
+    for (const e of outgoing.get(id) ?? []) {
+      rank.set(e.target, Math.max(rank.get(e.target) ?? 0, (rank.get(id) ?? 0) + 1));
+      const remaining = (indegree.get(e.target) ?? 0) - 1;
+      indegree.set(e.target, remaining);
+      if (remaining === 0) queue.push(e.target);
+    }
+  }
+  return rank;
+}
 function buildWorkflowGraph(yaml, options) {
   const reserveRunState = options?.reserveRunState ?? false;
   const direction = options?.direction ?? "LR";
   const compact = options?.compact ?? false;
+  const declared = options?.edges;
   if (!yaml || yaml.trim() === "") {
     return { nodes: [], edges: [], error: "No definition" };
   }
@@ -534,7 +671,8 @@ function buildWorkflowGraph(yaml, options) {
   }
   const def = asRecord(parsed);
   const actions = Array.isArray(def.do) ? def.do : [];
-  if (!def.on && actions.length === 0) {
+  const triggers = !def.on ? [] : Array.isArray(def.on) ? def.on : [def.on];
+  if (triggers.length === 0 && actions.length === 0) {
     return { nodes: [], edges: [], error: "Empty workflow" };
   }
   const logical = [];
@@ -547,24 +685,39 @@ function buildWorkflowGraph(yaml, options) {
     };
     logical.push({ id, data, width: dims.width, height: dims.height, rank: rank2 });
   };
-  const addEdge = (source, target, kind) => {
-    edges.push({ id: `${source}->${target}`, source, target, kind });
+  const edgeIds = /* @__PURE__ */ new Set();
+  const addEdge = (source, target, kind, whenLabel) => {
+    const id = `${source}->${target}`;
+    if (edgeIds.has(id)) return;
+    edgeIds.add(id);
+    edges.push({
+      id,
+      source,
+      target,
+      kind,
+      ...whenLabel ? { whenLabel } : {}
+    });
   };
   let rank = 0;
   let prevExits = [];
   const branchLeafIds = /* @__PURE__ */ new Set();
-  if (def.on) {
-    addNode("trigger", describeTrigger(def.on), rank, false);
-    prevExits = ["trigger"];
+  const triggerIds = triggers.map((_, i) => triggerNodeId(i));
+  triggers.forEach((trigger, i) => {
+    addNode(triggerNodeId(i), describeTrigger(trigger), rank, false);
+  });
+  if (triggers.length > 0) {
+    prevExits = [...triggerIds];
     rank += 1;
   }
   actions.forEach((action, i) => {
-    const id = `a${i}`;
+    const id = actionNodeId(i);
     const data = describeAction(action);
-    if (i === 0 && !def.on) data.isRoot = true;
+    if (i === 0 && triggers.length === 0) data.isRoot = true;
     addNode(id, data, rank, reserveRunState);
-    for (const from of prevExits) {
-      addEdge(from, id, branchLeafIds.has(from) ? "join" : "spine");
+    if (!declared) {
+      for (const from of prevExits) {
+        addEdge(from, id, branchLeafIds.has(from) ? "join" : "spine");
+      }
     }
     const rec = asRecord(action);
     const children = "parallel" in rec ? Array.isArray(asRecord(rec.parallel).branches) ? asRecord(rec.parallel).branches : [] : "foreach" in rec ? (
@@ -575,7 +728,7 @@ function buildWorkflowGraph(yaml, options) {
       const branchRank = rank + 1;
       const branchIds = [];
       children.forEach((child, j) => {
-        const cid = `${id}-b${j}`;
+        const cid = branchNodeId(i, j);
         addNode(cid, describeAction(child), branchRank, reserveRunState);
         addEdge(id, cid, "fork");
         branchIds.push(cid);
@@ -588,8 +741,43 @@ function buildWorkflowGraph(yaml, options) {
       rank += 1;
     }
   });
+  if (declared) {
+    const known = new Set(logical.map((n) => n.id));
+    for (const spec of declared) {
+      const missing = !known.has(spec.from) ? spec.from : !known.has(spec.to) ? spec.to : null;
+      if (missing !== null) {
+        return {
+          nodes: [],
+          edges: [],
+          error: `Declared topology names "${missing}", which this definition has no step for`
+        };
+      }
+      addEdge(spec.from, spec.to, "spine", spec.whenLabel);
+    }
+    const rootward = new Set(edges.map((e) => e.target));
+    for (const n of logical) {
+      if (triggerNodeIndex(n.id) !== null) continue;
+      if (rootward.has(n.id)) continue;
+      for (const triggerId of triggerIds) addEdge(triggerId, n.id, "spine");
+    }
+    const orderedIds = logical.map((n) => n.id);
+    const backEdgeIds = classifyBackEdges(orderedIds, edges);
+    for (const e of edges) {
+      if (backEdgeIds.has(e.id)) e.backEdge = true;
+    }
+    const rankById = rankByTopology(orderedIds, edges, backEdgeIds);
+    const incoming = new Set(edges.map((e) => e.target));
+    for (const n of logical) {
+      n.rank = rankById.get(n.id) ?? 0;
+      n.data = { ...n.data, isRoot: !incoming.has(n.id) };
+    }
+  }
+  const labelled = edges.some(
+    (e) => e.whenLabel !== void 0 || e.backEdge === true
+  );
+  const rankSep = labelled ? Math.max(geo.rankSep, EDGE_LABEL_LANE) : geo.rankSep;
   return {
-    nodes: layoutLayers(logical, direction, geo.rankSep, geo.crossSep),
+    nodes: layoutLayers(logical, direction, rankSep, geo.crossSep),
     edges,
     error: null
   };
@@ -602,6 +790,11 @@ export {
   fmtTokens,
   shortModel,
   providerLabel,
+  TRIGGER_NODE_ID,
+  triggerNodeId,
+  triggerNodeIndex,
+  actionNodeId,
+  branchNodeId,
   COMPACT_TILE,
   COMPACT_NODE_SIZE,
   buildWorkflowGraph

package/dist/globals.css

@@ -718,6 +718,9 @@
   .\!h-2 {
     height: calc(var(--spacing) * 2) !important;
   }
+  .\!h-2\.5 {
+    height: calc(var(--spacing) * 2.5) !important;
+  }
   .h-1 {
     height: var(--spacing);
   }
@@ -796,6 +799,9 @@
   .h-\[24rem\] {
     height: 24rem;
   }
+  .h-\[26rem\] {
+    height: 26rem;
+  }
   .h-\[28rem\] {
     height: 28rem;
   }
@@ -967,6 +973,9 @@
   .\!w-2 {
     width: calc(var(--spacing) * 2) !important;
   }
+  .\!w-2\.5 {
+    width: calc(var(--spacing) * 2.5) !important;
+  }
   .w-0 {
     width: 0px;
   }
@@ -1210,6 +1219,9 @@
   .max-w-6xl {
     max-width: var(--container-6xl);
   }
+  .max-w-40 {
+    max-width: calc(var(--spacing) * 40);
+  }
   .max-w-\[14rem\] {
     max-width: 14rem;
   }
@@ -1698,6 +1710,9 @@
   .overscroll-x-contain {
     overscroll-behavior-x: contain;
   }
+  .\!rounded-full {
+    border-radius: calc(infinity * 1px) !important;
+  }
   .rounded {
     border-radius: 0.25rem;
   }
@@ -1781,6 +1796,10 @@
   .rounded-bl-lg {
     border-bottom-left-radius: var(--radius-lg);
   }
+  .\!border {
+    border-style: var(--tw-border-style) !important;
+    border-width: 1px !important;
+  }
   .\!border-0 {
     border-style: var(--tw-border-style) !important;
     border-width: 0px !important;
@@ -1841,6 +1860,9 @@
     --tw-border-style: none;
     border-style: none;
   }
+  .\!border-border {
+    border-color: var(--color-border) !important;
+  }
   .border-\[var\(--accent-text\)\] {
     border-color: var(--accent-text);
   }
@@ -2081,6 +2103,12 @@
   .border-b-primary {
     border-bottom-color: var(--color-primary);
   }
+  .\!bg-muted-foreground\/70 {
+    background-color: color-mix(in srgb, hsl(var(--muted-foreground)) 70%, transparent) !important;
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-muted-foreground) 70%, transparent) !important;
+    }
+  }
   .\!bg-transparent {
     background-color: transparent !important;
   }
@@ -2300,6 +2328,12 @@
       background-color: color-mix(in oklab, var(--color-card) 80%, transparent);
     }
   }
+  .bg-card\/90 {
+    background-color: color-mix(in srgb, hsl(var(--card)) 90%, transparent);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-card) 90%, transparent);
+    }
+  }
   .bg-destructive {
     background-color: var(--color-destructive);
   }
@@ -3893,6 +3927,9 @@
         border-color: color-mix(in oklab, var(--color-primary) 50%, transparent);
       }
     }
+    .hover\:\!bg-primary:hover {
+      background-color: var(--color-primary) !important;
+    }
     .hover\:bg-\[var\(--accent-surface-soft\)\]:hover {
       background-color: var(--accent-surface-soft);
     }

package/dist/styles.css

@@ -718,6 +718,9 @@
   .\!h-2 {
     height: calc(var(--spacing) * 2) !important;
   }
+  .\!h-2\.5 {
+    height: calc(var(--spacing) * 2.5) !important;
+  }
   .h-1 {
     height: var(--spacing);
   }
@@ -796,6 +799,9 @@
   .h-\[24rem\] {
     height: 24rem;
   }
+  .h-\[26rem\] {
+    height: 26rem;
+  }
   .h-\[28rem\] {
     height: 28rem;
   }
@@ -967,6 +973,9 @@
   .\!w-2 {
     width: calc(var(--spacing) * 2) !important;
   }
+  .\!w-2\.5 {
+    width: calc(var(--spacing) * 2.5) !important;
+  }
   .w-0 {
     width: 0px;
   }
@@ -1210,6 +1219,9 @@
   .max-w-6xl {
     max-width: var(--container-6xl);
   }
+  .max-w-40 {
+    max-width: calc(var(--spacing) * 40);
+  }
   .max-w-\[14rem\] {
     max-width: 14rem;
   }
@@ -1698,6 +1710,9 @@
   .overscroll-x-contain {
     overscroll-behavior-x: contain;
   }
+  .\!rounded-full {
+    border-radius: calc(infinity * 1px) !important;
+  }
   .rounded {
     border-radius: 0.25rem;
   }
@@ -1781,6 +1796,10 @@
   .rounded-bl-lg {
     border-bottom-left-radius: var(--radius-lg);
   }
+  .\!border {
+    border-style: var(--tw-border-style) !important;
+    border-width: 1px !important;
+  }
   .\!border-0 {
     border-style: var(--tw-border-style) !important;
     border-width: 0px !important;
@@ -1841,6 +1860,9 @@
     --tw-border-style: none;
     border-style: none;
   }
+  .\!border-border {
+    border-color: var(--color-border) !important;
+  }
   .border-\[var\(--accent-text\)\] {
     border-color: var(--accent-text);
   }
@@ -2081,6 +2103,12 @@
   .border-b-primary {
     border-bottom-color: var(--color-primary);
   }
+  .\!bg-muted-foreground\/70 {
+    background-color: color-mix(in srgb, hsl(var(--muted-foreground)) 70%, transparent) !important;
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-muted-foreground) 70%, transparent) !important;
+    }
+  }
   .\!bg-transparent {
     background-color: transparent !important;
   }
@@ -2300,6 +2328,12 @@
       background-color: color-mix(in oklab, var(--color-card) 80%, transparent);
     }
   }
+  .bg-card\/90 {
+    background-color: color-mix(in srgb, hsl(var(--card)) 90%, transparent);
+    @supports (color: color-mix(in lab, red, red)) {
+      background-color: color-mix(in oklab, var(--color-card) 90%, transparent);
+    }
+  }
   .bg-destructive {
     background-color: var(--color-destructive);
   }
@@ -3893,6 +3927,9 @@
         border-color: color-mix(in oklab, var(--color-primary) 50%, transparent);
       }
     }
+    .hover\:\!bg-primary:hover {
+      background-color: var(--color-primary) !important;
+    }
     .hover\:bg-\[var\(--accent-surface-soft\)\]:hover {
       background-color: var(--accent-surface-soft);
     }

package/dist/workflows.d.ts

@@ -119,14 +119,80 @@ interface WfNode {
     height: number;
     data: WfNodeData;
 }
+/**
+ * Node ids are PUBLIC contract, not an internal detail. A host keys its live
+ * `nodeState` by them, points the graph's `selectedNodeId` at one, and — once it
+ * supplies a declared topology — names its own edge endpoints with them. They
+ * are bare strings, so a host that re-derives the format at the call site gets
+ * no type error when the format changes here; the graph simply renders without
+ * edges. The format is therefore written in exactly one place (these helpers)
+ * and read everywhere else through them.
+ */
+/** The workflow's first (or only) trigger. */
+declare const TRIGGER_NODE_ID = "trigger";
+/** The node for the `index`th entry of a list-form `on:`. Entry 0 IS
+ *  {@link TRIGGER_NODE_ID}, so a single-trigger graph — the overwhelmingly
+ *  common one — keeps the plain id a host may already have persisted.
+ *
+ *  `index` is a position in the definition's `on:` list: a non-negative
+ *  integer. Anything else formats an id no node bears, which a declared
+ *  topology then rejects by name ("…names "trigger:NaN", which this definition
+ *  has no step for") — reported there rather than thrown from here, because
+ *  {@link buildWorkflowGraph} calls this and must never throw. */
+declare function triggerNodeId(index: number): string;
+/** The `on:` entry a trigger node stands for, or null when the id names
+ *  anything else — so a host can tell a trigger from an action without
+ *  matching the id format itself. */
+declare function triggerNodeIndex(nodeId: string): number | null;
+/** The node for the `do` entry at `index`. */
+declare function actionNodeId(index: number): string;
+/** The node for the `branchIndex`th fan-out leaf of the `do` entry at
+ *  `actionIndex` — a `parallel` branch or a `foreach` template. */
+declare function branchNodeId(actionIndex: number, branchIndex: number): string;
 type WfEdgeKind = "spine" | "fork" | "join";
 interface WfEdge {
     id: string;
     source: string;
     target: string;
     /** Spine = trigger→action→action; fork = fan-out into a branch leaf; join =
-     *  a branch leaf reconverging onto the next spine node. Drives edge styling. */
+     *  a branch leaf reconverging onto the next spine node. Drives edge styling.
+     *
+     *  A DECLARED edge ({@link BuildWorkflowGraphOptions.edges}) is a `spine`
+     *  edge: it is the flow. Fork edges survive a declared topology unchanged (a
+     *  branch leaf is this module's own node, which no declared spec addresses);
+     *  join edges do not exist under one, because what follows a fan-out is then
+     *  declared rather than inferred from list position. */
     kind: WfEdgeKind;
+    /** Short, already-human summary of the edge's guard, when it carries one.
+     *  Supplied by {@link WfEdgeSpec.whenLabel} — this module never interprets a
+     *  condition, it only places the label its host wrote. */
+    whenLabel?: string;
+    /** True when this edge closes a cycle: it points back at a node that is
+     *  already on the path reaching it. Rendered distinctly (dashed, with the
+     *  visit budget) because such an edge is the one that can run a node twice. */
+    backEdge?: boolean;
+}
+/**
+ * One edge of a DECLARED topology — the caller's answer to "what actually
+ * connects to what", replacing the positional spine this module would otherwise
+ * infer from `do`-list order.
+ *
+ * Endpoints are node ids from THIS graph, so name them with {@link actionNodeId}
+ * / {@link branchNodeId} / {@link TRIGGER_NODE_ID} rather than by hand. Edges
+ * into a node that has none are how a root is identified: every trigger node
+ * gets an edge to every root, so the caller declares only the topology it owns
+ * and never has to restate what the trigger connects to.
+ *
+ * The guard arrives PRE-SUMMARIZED (`whenLabel`). A condition's schema belongs
+ * to the system that compiles and evaluates it — this library renders graphs and
+ * has no business owning a second, drifting interpretation of one. The same
+ * summary the host writes here is then the one it can show elsewhere (a skipped
+ * step's row), which is what keeps the two readings identical.
+ */
+interface WfEdgeSpec {
+    from: string;
+    to: string;
+    whenLabel?: string;
 }
 interface WfGraph {
     nodes: WfNode[];
@@ -151,12 +217,29 @@ interface BuildWorkflowGraphOptions {
     /** Collapse every node to the fixed icon-tile size, and pitch the layers for
      *  it. Defaults to `false` (the full, expanded card). */
     compact?: boolean;
+    /**
+     * The graph's DECLARED topology. Omit — the default — and edges are inferred
+     * from `do`-list order: a linear spine, which is exactly right for a workflow
+     * that runs as one, and wrong for any workflow whose definition declares its
+     * own edges (`needs`, guards, cycles). Supply it and the inferred spine is
+     * replaced wholesale by these edges, the layout is re-ranked to the shape they
+     * describe (so a diamond reads as a diamond rather than a chain drawn over
+     * one), and cycle-closing edges are marked {@link WfEdge.backEdge}.
+     *
+     * An edge naming a node this graph has no slot for is an ERROR
+     * ({@link WfGraph.error}), never a quiet fall back to the positional spine:
+     * the two disagreeing means the topology and the definition came from
+     * different places, and a graph that draws edges the run will not take is
+     * worse than one that says it cannot be drawn.
+     */
+    edges?: readonly WfEdgeSpec[];
 }
 /** Build a positioned graph from a workflow YAML string. Never throws —
  *  malformed YAML or an empty definition returns an `error` the UI can fall
  *  back on (e.g. show the raw YAML while authoring). `reserveRunState` leaves
  *  room for the rows live run state adds (see {@link nodeHeight}); `direction`
- *  picks the flow axis (default "LR"); `compact` collapses nodes to icon tiles. */
+ *  picks the flow axis (default "LR"); `compact` collapses nodes to icon tiles;
+ *  `edges` replaces the inferred positional spine with a declared topology. */
 declare function buildWorkflowGraph(yaml: string, options?: BuildWorkflowGraphOptions): WfGraph;
 
 interface WorkflowGraphProps {
@@ -187,11 +270,46 @@ interface WorkflowGraphProps {
      * fresh record each update — e.g. from a poll/SSE tick — satisfies this.
      */
     nodeState?: Record<string, WfNodeState>;
+    /**
+     * The graph's DECLARED topology, replacing the spine inferred from `do`-list
+     * order — see {@link WfEdgeSpec}. Name endpoints with the exported id helpers
+     * (`actionNodeId`, `branchNodeId`, `TRIGGER_NODE_ID`).
+     *
+     * Immutability contract, as for `nodeState`: the layout memo keys on this
+     * array's reference, so pass a stable one (a `useMemo`, or a value derived
+     * once per fetch) rather than a fresh literal each render.
+     */
+    edges?: readonly WfEdgeSpec[];
+    /** Per-node visit budget for a cyclic graph, shown on cycle-closing edges.
+     *  Meaningless without `edges` (an inferred spine cannot loop). */
+    maxNodeVisits?: number;
+    /** The node to ring as selected — e.g. the one whose detail panel is open.
+     *  Selection is the host's state; the graph only reflects it. */
+    selectedNodeId?: string;
     /** Click handler for a node (e.g. open a detail drawer). Absent ⇒ nodes are
      *  non-interactive on click. */
     onNodeClick?: (nodeId: string, data: WfNodeData) => void;
+    /**
+     * Editing gestures. Supplying `onEdgeConnect` turns the canvas from a diagram
+     * into an EDITOR: node handles become visible and draggable, an edge can be
+     * selected and removed with Delete/Backspace, and clicking one asks to edit
+     * its guard. Omit all three — the default — and the graph stays the read-only
+     * visualisation it has always been.
+     *
+     * Every callback speaks node ids (`actionNodeId`, `branchNodeId`), never
+     * positions: this component reports the gesture, and turning it into a
+     * definition edit is the host's job — it owns the YAML, and only it knows
+     * what a `needs` row is. Fan-out and trigger edges never fire any of these
+     * ({@link isEditableEdge}), because neither is a row in anyone's topology.
+     *
+     * The canvas holds no pending state: an accepted edit comes back as new
+     * `yaml` + `edges`, and a rejected one simply never arrives.
+     */
+    onEdgeConnect?: (sourceId: string, targetId: string) => void;
+    onEdgeDelete?: (sourceId: string, targetId: string) => void;
+    onEdgeClick?: (sourceId: string, targetId: string) => void;
 }
 
 declare function WorkflowGraph(props: WorkflowGraphProps): React.JSX.Element;
 
-export { type BuildWorkflowGraphOptions, type WfEdge, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, buildWorkflowGraph };
+export { type BuildWorkflowGraphOptions, TRIGGER_NODE_ID, type WfEdge, type WfEdgeKind, type WfEdgeSpec, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, actionNodeId, branchNodeId, buildWorkflowGraph, triggerNodeId, triggerNodeIndex };

package/dist/workflows.js

@@ -1,6 +1,11 @@
 import {
-  buildWorkflowGraph
-} from "./chunk-2NS724P4.js";
+  TRIGGER_NODE_ID,
+  actionNodeId,
+  branchNodeId,
+  buildWorkflowGraph,
+  triggerNodeId,
+  triggerNodeIndex
+} from "./chunk-YOSNN3QU.js";
 import {
   ModelBrandStack,
   modelBrandFor
@@ -31,7 +36,7 @@ function retryImport(factory, retries = 2, delayMs = 350) {
 function lazyWorkflowGraph() {
   return lazy(
     () => retryImport(
-      () => import("./WorkflowGraph-GUX7XN7Y.js").then((m) => ({ default: m.WorkflowGraph }))
+      () => import("./WorkflowGraph-YII62JEW.js").then((m) => ({ default: m.WorkflowGraph }))
     )
   );
 }
@@ -103,7 +108,12 @@ function WorkflowGraph(props) {
 }
 export {
   ModelBrandStack,
+  TRIGGER_NODE_ID,
   WorkflowGraph as WorkflowGraphLazy,
+  actionNodeId,
+  branchNodeId,
   buildWorkflowGraph,
-  modelBrandFor
+  modelBrandFor,
+  triggerNodeId,
+  triggerNodeIndex
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-ui",
-  "version": "0.92.0",
+  "version": "0.93.1",
   "description": "Unified UI component library for Tangle Sandbox — primitives, chat, dashboard, terminal, editor, and workspace components",
   "repository": {
     "type": "git",