capdag 0.109.248 → 0.124.274

package/cap-graph-renderer.js

@@ -185,7 +185,7 @@ function layoutForMode(mode) {
       'elk.spacing.nodeNode': 35,
     });
   }
-  if (mode === 'machine') {
+  if (mode === 'editor-graph') {
     // Editor graph is a small bipartite-ish DAG; orthogonal routing
     // reads more cleanly than polyline at this density.
     return {
@@ -199,6 +199,16 @@ function layoutForMode(mode) {
       'elk.layered.nodePlacement.bk.fixedAlignment': 'BALANCED',
     };
   }
+  if (mode === 'machine') {
+    // Resolved-machine graph: a (potentially multi-strand) DAG laid
+    // out left-to-right with the same spacing the strand mode uses
+    // for single strands. Multiple disconnected strands are placed
+    // side by side by elk's component packer.
+    return Object.assign({}, base, {
+      'elk.layered.spacing.nodeNodeBetweenLayers': 120,
+      'elk.spacing.nodeNode': 40,
+    });
+  }
   throw new Error(`CapGraphRenderer: unknown mode '${mode}'`);
 }
 
@@ -222,6 +232,16 @@ function buildStylesheet() {
   const bodyEdgeSuccess = getCssVar('--graph-body-edge-success');
   const bodyEdgeFailure = getCssVar('--graph-body-edge-failure');
 
+  // Machine mode uses a dedicated palette exposed by the notation
+  // editor's CSS (`--graph-node-color`, `--graph-loop-color`,
+  // `--graph-edge-color`, `--graph-text`, `--graph-muted`). Caps
+  // are collapsed into edges so there's no cap-node color.
+  const machineNodeColor = getCssVar('--graph-node-color');
+  const machineLoopColor = getCssVar('--graph-loop-color');
+  const machineEdgeColor = getCssVar('--graph-edge-color');
+  const machineText = getCssVar('--graph-text');
+  const machineMuted = getCssVar('--graph-muted');
+
   return [
     {
       selector: 'node',
@@ -271,7 +291,11 @@ function buildStylesheet() {
     {
       selector: 'node.show-more',
       style: {
-        'background-color': getCssVar('--graph-bg'),
+        // Use the normal node fill; the dashed border is what
+        // distinguishes a show-more node from a regular cap.
+        // The renderer never reads `--graph-bg` — the graph
+        // canvas background is entirely the host's concern.
+        'background-color': nodeBg,
         'border-style': 'dashed',
         'border-width': '2px',
         'border-color': nodeBorderHighlighted,
@@ -286,11 +310,14 @@ function buildStylesheet() {
         'font-weight': '500',
         'color': 'data(color)',
         'text-background-color': edgeTextBg,
-        'text-background-opacity': edgeTextBgOpacity,
-        'text-background-padding': '3px',
+        'text-background-opacity': 1,
+        'text-background-padding': '4px',
         'text-background-shape': 'roundrectangle',
-        'text-rotation': 'autorotate',
-        'text-margin-y': -8,
+        // Keep labels horizontal — autorotate clips along
+        // fan-out edges and rotates labels into unreadable
+        // angles when multiple edges share a source.
+        'text-rotation': 0,
+        'text-margin-y': 0,
         'curve-style': 'bezier',
         'control-point-step-size': 40,
         'width': 1.5,
@@ -316,11 +343,21 @@ function buildStylesheet() {
     },
     {
       selector: 'edge.body-success',
-      style: { 'line-color': bodyEdgeSuccess, 'target-arrow-color': bodyEdgeSuccess },
+      style: {
+        'line-color': bodyEdgeSuccess,
+        'target-arrow-color': bodyEdgeSuccess,
+        // Label text uses the resolved success color too, not the
+        // unresolved `var(...)` string stored in `data.color`.
+        'color': bodyEdgeSuccess,
+      },
     },
     {
       selector: 'edge.body-failure',
-      style: { 'line-color': bodyEdgeFailure, 'target-arrow-color': bodyEdgeFailure },
+      style: {
+        'line-color': bodyEdgeFailure,
+        'target-arrow-color': bodyEdgeFailure,
+        'color': bodyEdgeFailure,
+      },
     },
     {
       selector: 'node.path-highlighted',
@@ -330,6 +367,44 @@ function buildStylesheet() {
       selector: 'edge.path-highlighted',
       style: { 'width': 3, 'z-index': 999, 'line-style': 'solid' },
     },
+
+    // -------- Machine / editor-graph mode ------------------------------
+    // Shared between the resolved-machine view (`mode: 'machine'`,
+    // canonical `Machine::to_render_payload_json`) and the notation
+    // editor's live graph (`mode: 'editor-graph'`, ast-driven). Both
+    // collapse each cap application into a single labeled edge
+    // between its input and output data slots — caps do NOT appear
+    // as separate nodes. Only data slots are nodes; cap semantics
+    // are carried on edges.
+    //
+    // Reads the editor's dedicated palette so nodes, edges and
+    // loop markers match the text theme.
+    {
+      selector: 'node.machine-node',
+      style: {
+        'background-color': machineNodeColor || nodeBg,
+        'border-color': machineNodeColor || nodeBorder,
+        'color': machineText || nodeText,
+        'border-opacity': 1,
+      },
+    },
+    {
+      selector: 'edge.machine-edge',
+      style: {
+        'line-color': machineEdgeColor || 'data(color)',
+        'target-arrow-color': machineEdgeColor || 'data(color)',
+        'color': machineMuted || nodeText,
+      },
+    },
+    {
+      selector: 'edge.machine-loop',
+      style: {
+        'line-color': machineLoopColor || nodeBorderActive,
+        'target-arrow-color': machineLoopColor || nodeBorderActive,
+        'color': machineLoopColor || nodeBorderActive,
+        'line-style': 'dashed',
+      },
+    },
   ];
 }
 
@@ -444,6 +519,9 @@ function validateStrandPayload(data) {
       && (data.media_display_names === null || typeof data.media_display_names !== 'object')) {
     throw new Error('CapGraphRenderer strand mode: data.media_display_names must be an object when present');
   }
+  if (data.source_display !== undefined && typeof data.source_display !== 'string') {
+    throw new Error('CapGraphRenderer strand mode: data.source_display must be a string when present');
+  }
 }
 
 function validateBodyOutcome(outcome, path) {
@@ -495,25 +573,93 @@ function validateRunPayload(data) {
   }
 }
 
-function validateMachinePayload(data) {
+function validateEditorGraphPayload(data) {
   if (!data || typeof data !== 'object') {
-    throw new Error('CapGraphRenderer machine mode: data must be an object');
+    throw new Error('CapGraphRenderer editor-graph mode: data must be an object');
   }
-  assertArray(data.elements, 'machine mode data.elements');
+  assertArray(data.elements, 'editor-graph mode data.elements');
   data.elements.forEach((el, idx) => {
     if (!el || typeof el !== 'object') {
-      throw new Error(`CapGraphRenderer machine mode: data.elements[${idx}] is not an object`);
+      throw new Error(`CapGraphRenderer editor-graph mode: data.elements[${idx}] is not an object`);
     }
     if (el.kind !== 'node' && el.kind !== 'cap' && el.kind !== 'edge') {
       throw new Error(
-        `CapGraphRenderer machine mode: data.elements[${idx}].kind must be "node" | "cap" | "edge" (got: ${JSON.stringify(el.kind)})`
+        `CapGraphRenderer editor-graph mode: data.elements[${idx}].kind must be "node" | "cap" | "edge" (got: ${JSON.stringify(el.kind)})`
       );
     }
-    assertString(el.graph_id, `machine mode data.elements[${idx}].graph_id`);
+    assertString(el.graph_id, `editor-graph mode data.elements[${idx}].graph_id`);
     if (el.kind === 'edge') {
-      assertString(el.source_graph_id, `machine mode data.elements[${idx}].source_graph_id`);
-      assertString(el.target_graph_id, `machine mode data.elements[${idx}].target_graph_id`);
+      assertString(el.source_graph_id, `editor-graph mode data.elements[${idx}].source_graph_id`);
+      assertString(el.target_graph_id, `editor-graph mode data.elements[${idx}].target_graph_id`);
+    }
+  });
+}
+
+// `validateResolvedMachinePayload` checks the canonical machine
+// render payload produced by Rust `Machine::to_render_payload_json`.
+// Shape:
+//   {
+//     "strands": [
+//       {
+//         "nodes": [{"id": "n0", "urn": "media:pdf"}, ...],
+//         "edges": [{
+//           "alias": "edge_0",
+//           "cap_urn": "...",
+//           "is_loop": false,
+//           "assignment": [{"cap_arg_media_urn": "media:pdf", "source_node": "n0"}, ...],
+//           "target_node": "n1"
+//         }, ...],
+//         "input_anchor_nodes": ["n0"],
+//         "output_anchor_nodes": ["n2"]
+//       },
+//       ...
+//     ]
+//   }
+function validateResolvedMachinePayload(data) {
+  if (!data || typeof data !== 'object') {
+    throw new Error('CapGraphRenderer machine mode: data must be an object');
+  }
+  assertArray(data.strands, 'machine mode data.strands');
+  data.strands.forEach((strand, sIdx) => {
+    if (!strand || typeof strand !== 'object') {
+      throw new Error(`CapGraphRenderer machine mode: data.strands[${sIdx}] is not an object`);
     }
+    assertArray(strand.nodes, `machine mode data.strands[${sIdx}].nodes`);
+    strand.nodes.forEach((n, nIdx) => {
+      if (!n || typeof n !== 'object') {
+        throw new Error(`CapGraphRenderer machine mode: data.strands[${sIdx}].nodes[${nIdx}] is not an object`);
+      }
+      assertString(n.id, `machine mode data.strands[${sIdx}].nodes[${nIdx}].id`);
+      assertString(n.urn, `machine mode data.strands[${sIdx}].nodes[${nIdx}].urn`);
+    });
+    assertArray(strand.edges, `machine mode data.strands[${sIdx}].edges`);
+    strand.edges.forEach((e, eIdx) => {
+      if (!e || typeof e !== 'object') {
+        throw new Error(`CapGraphRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}] is not an object`);
+      }
+      assertString(e.alias, `machine mode data.strands[${sIdx}].edges[${eIdx}].alias`);
+      assertString(e.cap_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].cap_urn`);
+      if (typeof e.is_loop !== 'boolean') {
+        throw new Error(`CapGraphRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].is_loop must be boolean`);
+      }
+      assertArray(e.assignment, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment`);
+      e.assignment.forEach((b, bIdx) => {
+        if (!b || typeof b !== 'object') {
+          throw new Error(`CapGraphRenderer machine mode: data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}] is not an object`);
+        }
+        assertString(b.cap_arg_media_urn, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].cap_arg_media_urn`);
+        assertString(b.source_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].assignment[${bIdx}].source_node`);
+      });
+      assertString(e.target_node, `machine mode data.strands[${sIdx}].edges[${eIdx}].target_node`);
+    });
+    assertArray(strand.input_anchor_nodes, `machine mode data.strands[${sIdx}].input_anchor_nodes`);
+    strand.input_anchor_nodes.forEach((id, iIdx) => {
+      assertString(id, `machine mode data.strands[${sIdx}].input_anchor_nodes[${iIdx}]`);
+    });
+    assertArray(strand.output_anchor_nodes, `machine mode data.strands[${sIdx}].output_anchor_nodes`);
+    strand.output_anchor_nodes.forEach((id, oIdx) => {
+      assertString(id, `machine mode data.strands[${sIdx}].output_anchor_nodes[${oIdx}]`);
+    });
   });
 }
 
@@ -739,7 +885,8 @@ function buildStrandGraphData(data) {
     });
   }
   let edgeCounter = 0;
-  function addEdge(source, target, label, title, fullUrn, edgeClass) {
+  function addEdge(source, target, label, title, fullUrn, edgeClass, meta) {
+    const m = meta || {};
     edges.push({
       id: `strand-edge-${edgeCounter}`,
       source,
@@ -749,6 +896,11 @@ function buildStrandGraphData(data) {
       fullUrn: fullUrn || '',
       edgeClass: edgeClass || '',
       color: edgeHueColor(edgeCounter),
+      // `foreachEntry` flags a cap edge as the first cap entering a
+      // ForEach body (the "phantom direct edge" in plan builder's
+      // terminology). Render-time collapse uses this to relabel the
+      // edge with the cap title + (1→n) marker. Defaults to false.
+      foreachEntry: m.foreachEntry === true,
     });
     edgeCounter++;
   }
@@ -768,13 +920,14 @@ function buildStrandGraphData(data) {
   let bodyExit = null;
 
   // Finalize an outer ForEach body when a nested ForEach starts before
-  // the outer's Collect. Mirrors plan_builder.rs:238-289.
+  // the outer's Collect. Mirrors plan_builder.rs:238-289. The render
+  // collapse will later drop the ForEach node and synthesize the
+  // bridging edges, so we only need to emit the plan-builder
+  // topology here.
   function finalizeOuterForEach(outerForEach, outerEntry, outerExit) {
     const outerForEachInput = outerForEach.index === 0
       ? inputSlotId
       : `step_${outerForEach.index - 1}`;
-    // Create the ForEach node + direct edge from its input + iteration
-    // edge into the body's first cap.
     addNode(outerForEach.nodeId, 'for each', '', 'strand-foreach');
     addEdge(outerForEachInput, outerForEach.nodeId, 'for each', 'for each', '', 'strand-iteration');
     addEdge(outerForEach.nodeId, outerEntry, '', '', '', 'strand-iteration');
@@ -790,12 +943,27 @@ function buildStrandGraphData(data) {
       const toCanonical = canonicalMediaUrn(step.to_spec);
       addNode(nodeId, displayNameFor(toCanonical), toCanonical, 'strand-cap');
 
+      // The first cap inside a ForEach body is the "foreach entry"
+      // — its incoming edge crosses the foreach boundary. Strand
+      // mode's render collapse relabels that edge with a (1→n)
+      // cardinality marker regardless of the cap's own sequence
+      // flags, because visually the transition IS the foreach.
+      const isForeachEntry = insideForEachBody !== null && bodyEntry === null;
+
       let label = body.title;
       const cardinality = cardinalityLabel(body.input_is_sequence, body.output_is_sequence);
       if (cardinality !== '1\u21921') {
         label = `${label} (${cardinality})`;
       }
-      addEdge(prevNodeId, nodeId, label, body.title, body.cap_urn, 'strand-cap-edge');
+      addEdge(
+        prevNodeId,
+        nodeId,
+        label,
+        body.title,
+        body.cap_urn,
+        'strand-cap-edge',
+        { foreachEntry: isForeachEntry }
+      );
 
       if (insideForEachBody !== null) {
         if (bodyEntry === null) bodyEntry = nodeId;
@@ -854,7 +1022,11 @@ function buildStrandGraphData(data) {
         prevNodeId = nodeId;
       } else {
         // Standalone Collect — scalar → list-of-one. Mirrors
-        // plan_builder.rs:333-355.
+        // plan_builder.rs:333-355. There is no enclosing foreach
+        // body, so the preceding cap is NOT flagged as a
+        // foreach-exit; the render-time collapse will synthesize a
+        // plain "collect" marker on the synthesized edge replacing
+        // the dropped Collect node.
         addNode(nodeId, 'collect', '', 'strand-collect');
         addEdge(prevNodeId, nodeId, 'collect', 'collect', '', 'strand-collection');
         prevNodeId = nodeId;
@@ -866,6 +1038,10 @@ function buildStrandGraphData(data) {
   });
 
   // Handle unclosed ForEach after the walk. Mirrors plan_builder.rs:362-428.
+  // An unclosed ForEach with a body just creates the synthetic
+  // ForEach node + iteration edge and leaves `prev_node_id` at
+  // the last body cap. The render collapse drops the ForEach node;
+  // the cap edges inside the body keep their own labels verbatim.
   if (insideForEachBody !== null) {
     const outer = insideForEachBody;
     const hasBodyEntry = bodyEntry !== null;
@@ -892,11 +1068,180 @@ function buildStrandGraphData(data) {
   addNode(outputId, displayNameFor(targetSpec), targetSpec, 'strand-target');
   addEdge(prevNodeId, outputId, '', '', '', 'strand-cap-edge');
 
+  // Return the raw plan-builder topology. Strand mode collapses
+  // ForEach/Collect nodes into edge labels at render time (see
+  // `strandCytoscapeElements`); run mode keeps them as explicit
+  // nodes because body replicas anchor at the ForEach/Collect
+  // junctions.
   return { nodes, edges, sourceSpec, targetSpec };
 }
 
-function strandCytoscapeElements(built) {
-  const nodeElements = built.nodes.map(node => ({
+// Transform the plan-builder strand topology into the render shape
+// strand mode actually displays. Pure function; does NOT mutate the
+// input. Run mode bypasses this transform and consumes the raw
+// topology directly (see `runCytoscapeElements`).
+//
+// The display rules (per user spec):
+//
+//   1. ForEach and Collect are NOT rendered as nodes. They're
+//      execution-layer concepts; the visible semantic is carried on
+//      the surrounding cap edges.
+//
+//   2. The first cap edge entering a ForEach body is relabeled to
+//      `<cap_title> (1→n)`. The builder flags those edges with
+//      `foreachEntry: true`. The collapse does NOT relabel this
+//      edge — the cap's own cardinality marker (from its
+//      `input_is_sequence`/`output_is_sequence`) is the single
+//      source of truth. A `(1→n)` marker on a strand edge means
+//      the cap on that edge produces a sequence, and that's
+//      already reflected in the builder's label.
+//
+//   3. Every Collect (whether closing a body or standalone) is
+//      replaced by a plain unlabeled bridging edge from the
+//      body-exit node to the post-collect target. Any cardinality
+//      shift introduced by the collect is already visible on the
+//      post-collect cap's `input_is_sequence=true` flag.
+//
+//   4. If the last cap step's `to_spec` is semantically equivalent
+//      to the strand's `target_spec` (via MediaUrn.isEquivalent),
+//      the separate `output` target node is dropped and the last
+//      cap edge lands on that merged endpoint. Removes the visible
+//      duplicate node.
+function collapseStrandShapeTransitions(built) {
+  const MediaUrn = requireHostDependency('MediaUrn');
+
+  // Index for lookups.
+  const nodeById = new Map();
+  for (const n of built.nodes) nodeById.set(n.id, n);
+
+  // Step 1: before dropping Collect nodes, synthesize a plain
+  // bridging edge that replaces each dropped Collect. For a
+  // Collect node C the plan builder produced:
+  //   body_exit → C   (strand-collection, label="collect")
+  //   C → next        (strand-cap-edge, label="")
+  // The collapse drops C and its two touching edges. We emit an
+  // unlabeled `body_exit → next` cap edge in their place. The
+  // Collect transition itself is invisible — any cardinality
+  // shift is already on the post-collect cap's own label.
+  const synthesizedExitEdges = [];
+  for (const node of built.nodes) {
+    if (node.nodeClass !== 'strand-collect') continue;
+    const incoming = built.edges.filter(e =>
+      e.target === node.id && e.edgeClass === 'strand-collection');
+    const outgoing = built.edges.filter(e =>
+      e.source === node.id && e.edgeClass === 'strand-cap-edge');
+    for (const inEdge of incoming) {
+      for (const outEdge of outgoing) {
+        const bodyExitNodeId = inEdge.source;
+        const bodyExitCapEdge = built.edges.find(e =>
+          e.edgeClass === 'strand-cap-edge' && e.target === bodyExitNodeId);
+        // The Collect transition is invisible in the render.
+        // Every Collect becomes a plain unlabeled bridge edge
+        // from the body-exit node to the post-collect target.
+        // Any cardinality shift is already visible on the
+        // body-exit cap's own label (via its input/output
+        // sequence flags) or on the post-collect cap's label.
+        synthesizedExitEdges.push({
+          id: `${node.id}-collapsed-exit-${synthesizedExitEdges.length}`,
+          source: bodyExitNodeId,
+          target: outEdge.target,
+          label: '',
+          title: '',
+          fullUrn: '',
+          edgeClass: 'strand-cap-edge',
+          color: bodyExitCapEdge ? bodyExitCapEdge.color : inEdge.color,
+          foreachEntry: false,
+        });
+      }
+    }
+  }
+
+  // Drop all ForEach/Collect nodes and every edge that touches
+  // them (direct, iteration, collection, and the trailing collect
+  // cap-edge connector). The render never shows those nodes.
+  const dropNodeIds = new Set();
+  for (const node of built.nodes) {
+    if (node.nodeClass === 'strand-foreach' || node.nodeClass === 'strand-collect') {
+      dropNodeIds.add(node.id);
+    }
+  }
+  let nodes = built.nodes.filter(n => !dropNodeIds.has(n.id));
+  let edges = built.edges.filter(e =>
+    !dropNodeIds.has(e.source) &&
+    !dropNodeIds.has(e.target) &&
+    e.edgeClass !== 'strand-iteration' &&
+    e.edgeClass !== 'strand-collection');
+  edges = edges.concat(synthesizedExitEdges);
+
+  // Step 2: foreach-entry cap edges keep whatever label the
+  // strand builder emitted — the cap's own cardinality marker
+  // (from input_is_sequence/output_is_sequence) is the single
+  // source of truth for which edge carries a (1→n) / (n→1) /
+  // (n→n) annotation. The ForEach/Collect shape transitions
+  // themselves are invisible in the render; the cap preceding a
+  // ForEach (with output_is_sequence=true) already produces the
+  // (1→n) marker, and the cap following a Collect (with
+  // input_is_sequence=true) produces (n→1). No relabeling.
+
+  // Step 3: merge the trailing `step_N → output` edge when step_N
+  // and output represent the same media URN. The strand builder
+  // always emits a separate `output` node with a (possibly empty)
+  // connector edge from the last prev; when the URNs coincide the
+  // output is a visible duplicate.
+  //
+  // Find the `strand-target` node and look for a single incoming
+  // edge from a `strand-cap` (or `strand-source`) node. Compare the
+  // endpoints' `fullUrn` semantically.
+  const targetNode = nodes.find(n => n.nodeClass === 'strand-target');
+  if (targetNode) {
+    const incomingToTarget = edges.filter(e => e.target === targetNode.id);
+    if (incomingToTarget.length === 1) {
+      const trailing = incomingToTarget[0];
+      const upstreamNode = nodes.find(n => n.id === trailing.source);
+      if (upstreamNode && upstreamNode.fullUrn && targetNode.fullUrn) {
+        let equivalent = false;
+        try {
+          const a = MediaUrn.fromString(upstreamNode.fullUrn);
+          const b = MediaUrn.fromString(targetNode.fullUrn);
+          equivalent = a.isEquivalent(b);
+        } catch (_) {
+          equivalent = false;
+        }
+        // Merge only if the trailing edge is the unadorned connector
+        // (empty label). A labeled last-cap edge carries meaningful
+        // info and must not be collapsed away.
+        if (equivalent && (!trailing.label || trailing.label.length === 0)) {
+          // Drop the trailing connector edge and the target node.
+          // The upstream node effectively becomes the target visually.
+          // Rename its display label to the target's display to
+          // preserve the user-configured media_display_names entry.
+          edges = edges.filter(e => e.id !== trailing.id);
+          nodes = nodes
+            .filter(n => n.id !== targetNode.id)
+            .map(n => n.id === upstreamNode.id
+              ? Object.assign({}, n, { label: targetNode.label, nodeClass: 'strand-target' })
+              : n);
+        }
+      }
+    }
+  }
+
+  return { nodes, edges };
+}
+
+function strandCytoscapeElements(built, options) {
+  // Strand mode presents ForEach and Collect as edge labels, not as
+  // boxed nodes. Apply the cosmetic collapse right before emitting
+  // cytoscape elements so the underlying plan-builder topology stays
+  // intact for any callers that need it.
+  //
+  // Run mode opts out (`options.collapse === false`) because its body
+  // replicas visually fan out from the ForEach node and merge at the
+  // Collect node — those junctions must remain as explicit graph
+  // nodes for the fan-in/fan-out to be visible.
+  const shouldCollapse = !(options && options.collapse === false);
+  const source = shouldCollapse ? collapseStrandShapeTransitions(built) : built;
+  const nodeElements = source.nodes.map(node => ({
     group: 'nodes',
     data: {
       id: node.id,
@@ -905,7 +1250,7 @@ function strandCytoscapeElements(built) {
     },
     classes: node.nodeClass || '',
   }));
-  const edgeElements = built.edges.map(edge => ({
+  const edgeElements = source.edges.map(edge => ({
     group: 'edges',
     data: {
       id: edge.id,
@@ -938,31 +1283,21 @@ function findCapStepIndexByUrn(steps, targetUrnString) {
   return -1;
 }
 
-// Remove nodes and edges belonging to the ForEach body's interior cap
-// steps from a strand backbone. In run mode, these are replaced by
-// per-body replicas; keeping the prototype chain alongside the
-// replicas produces a confusing double-render. The ForEach and Collect
-// nodes themselves, plus their iteration/collection edges, stay.
-function stripBodyInteriorFromStrandBackbone(built, steps, foreachStepIdx, collectStepIdx) {
-  const bodyEnd = collectStepIdx >= 0 ? collectStepIdx : steps.length;
-  // Collect the positional IDs of body-interior cap steps (the caps
-  // strictly between ForEach and Collect).
-  const interiorIds = new Set();
-  for (let i = foreachStepIdx + 1; i < bodyEnd; i++) {
-    if (Object.keys(steps[i].step_type)[0] === 'Cap') {
-      interiorIds.add(`step_${i}`);
-    }
-  }
-  if (interiorIds.size === 0) return built;
-
-  const keptNodes = built.nodes.filter(n => !interiorIds.has(n.id));
+// Remove backbone cap nodes that will be replaced by per-body
+// replicas from the collapsed strand backbone. Every step_id in
+// `dropStepIds` is erased along with its incoming and outgoing
+// edges. Replicas own the per-body rendering of those nodes.
+//
+// The function does NOT try to stitch the backbone back together —
+// the replicas are responsible for connecting the anchor to the
+// merge target, and the "no outcomes yet" case is handled by
+// `buildRunGraphData`'s backbone-drop logic which also removes the
+// now-dangling target node when there are zero successful replicas.
+function stripRunBackboneReplicaNodes(built, dropStepIds) {
+  if (dropStepIds.size === 0) return built;
+  const keptNodes = built.nodes.filter(n => !dropStepIds.has(n.id));
   const keptEdges = built.edges.filter(e =>
-    !interiorIds.has(e.source) && !interiorIds.has(e.target));
-
-  // After stripping, the ForEach node and the Collect node (or the
-  // output node if no Collect) may become disconnected — the body
-  // replicas will bridge them. That's fine; cytoscape's ELK layout
-  // handles disconnected subgraphs.
+    !dropStepIds.has(e.source) && !dropStepIds.has(e.target));
   return {
     nodes: keptNodes,
     edges: keptEdges,
@@ -974,20 +1309,34 @@ function stripBodyInteriorFromStrandBackbone(built, steps, foreachStepIdx, colle
 function buildRunGraphData(data) {
   validateRunPayload(data);
 
-  // The backbone is rendered with the same rules as strand mode. Feed
-  // the strand portion to the strand builder to inherit all its
-  // ForEach/Collect labeling and cardinality-marker logic.
+  // Build the raw strand topology and then apply the strand
+  // collapse so the run backbone inherits the same cosmetic
+  // transform (no ForEach/Collect nodes, fix-up edges for
+  // foreach-entry, merged trailing target).
   const strandInput = Object.assign({}, data.resolved_strand, {
     media_display_names: data.media_display_names,
   });
   const strandBuiltRaw = buildStrandGraphData(strandInput);
+  let strandBuiltCollapsed = collapseStrandShapeTransitions(strandBuiltRaw);
+
+  // Run mode overrides the input_slot node's label with the
+  // host-supplied `source_display` (runtime input filename).
+  // Strand mode ignores this field so the abstract graph shows
+  // the media spec's title from `media_display_names`.
+  if (typeof data.source_display === 'string' && data.source_display.length > 0) {
+    strandBuiltCollapsed = {
+      nodes: strandBuiltCollapsed.nodes.map(n =>
+        n.id === 'input_slot' ? Object.assign({}, n, { label: data.source_display }) : n),
+      edges: strandBuiltCollapsed.edges,
+      sourceSpec: strandBuiltCollapsed.sourceSpec,
+      targetSpec: strandBuiltCollapsed.targetSpec,
+    };
+  }
 
-  // Locate the ForEach/Collect span in the backbone for body-replica
-  // placement. The strand builder uses positional node IDs mirroring
-  // the plan builder (`step_0`, `step_1`, …). The ForEach node at
-  // step index i has id `step_i`; body replicas fan out from that
-  // ForEach node and (when a Collect closes the body) merge into the
-  // Collect node at `step_j`.
+  // Locate the ForEach/Collect span in the raw steps. Positional
+  // IDs survive the collapse (node IDs are `step_${i}` from the
+  // builder), so we can still identify which collapsed nodes
+  // correspond to body-interior caps.
   const steps = data.resolved_strand.steps;
   let foreachStepIdx = -1;
   let collectStepIdx = -1;
@@ -997,17 +1346,7 @@ function buildRunGraphData(data) {
     if (variant === 'Collect' && collectStepIdx < 0) collectStepIdx = i;
   }
   const hasForeach = foreachStepIdx >= 0;
-
-  // In run mode we want per-body replicas to REPLACE the prototype cap
-  // chain inside the ForEach body, not sit alongside it. Strip the
-  // backbone nodes and edges that correspond to body-interior Cap
-  // steps and their direct edges, keeping only the input slot, the
-  // ForEach node, the Collect node (if any), the output node, and any
-  // caps OUTSIDE the body span. Body replicas will connect from the
-  // ForEach node and merge at the Collect node.
-  const strandBuilt = hasForeach
-    ? stripBodyInteriorFromStrandBackbone(strandBuiltRaw, steps, foreachStepIdx, collectStepIdx)
-    : strandBuiltRaw;
+  const hasCollect = collectStepIdx >= 0;
 
   // Filter and bound the outcomes.
   const allOutcomes = data.body_outcomes.slice().sort((a, b) => a.body_index - b.body_index);
@@ -1017,27 +1356,180 @@ function buildRunGraphData(data) {
   const visibleFailure = failures.slice(0, data.visible_failure_count);
   const hiddenSuccessCount = successes.length - visibleSuccess.length;
   const hiddenFailureCount = failures.length - visibleFailure.length;
+  const visibleOutcomes = visibleSuccess.concat(visibleFailure);
 
-  // Collect the Cap steps inside the ForEach body. Each body replica
-  // chains through these caps.
+  // Per-body replicas only fire when there's a ForEach AND at
+  // least one visible outcome. Without outcomes, the strand
+  // backbone renders the "plan preview" unchanged.
+  const shouldExpand = hasForeach && visibleOutcomes.length > 0;
+
+  // Body-interior Cap steps — each body iteration chains through
+  // these caps once. Only valid when `shouldExpand` is true.
   const bodyCapSteps = [];
-  const bodyStart = hasForeach ? foreachStepIdx + 1 : 0;
-  const bodyEnd = collectStepIdx >= 0 ? collectStepIdx : steps.length;
-  for (let i = bodyStart; i < bodyEnd; i++) {
-    if (Object.keys(steps[i].step_type)[0] === 'Cap') {
-      bodyCapSteps.push({ globalIndex: i, step: steps[i] });
+  if (hasForeach) {
+    const bodyStart = foreachStepIdx + 1;
+    const bodyEnd = hasCollect ? collectStepIdx : steps.length;
+    for (let i = bodyStart; i < bodyEnd; i++) {
+      if (Object.keys(steps[i].step_type)[0] === 'Cap') {
+        bodyCapSteps.push({ globalIndex: i, step: steps[i] });
+      }
     }
   }
 
-  // Body replicas fan out from the ForEach node. If no ForEach, fall
-  // back to the input_slot. When the strand closes the body with a
-  // Collect, replicas merge into that Collect node; otherwise
-  // (unclosed ForEach) they merge into the `output` node.
-  const anchorNodeId = hasForeach ? `step_${foreachStepIdx}` : 'input_slot';
-  const mergeNodeId = collectStepIdx >= 0 ? `step_${collectStepIdx}` : 'output';
+  // Short-circuit: no outcomes → the backbone IS the render.
+  // `anchorNodeId` and `mergeNodeId` are unused in this path.
+  if (!shouldExpand) {
+    return {
+      strandBuilt: strandBuiltCollapsed,
+      replicaNodes: [],
+      replicaEdges: [],
+      showMoreNodes: [],
+      totals: {
+        hiddenSuccessCount,
+        hiddenFailureCount,
+        totalBodyCount: data.total_body_count,
+        visibleSuccessCount: visibleSuccess.length,
+        visibleFailureCount: visibleFailure.length,
+      },
+    };
+  }
+
+  // Expanding. The plan mirrors the working
+  // `machfab-mac/.scrap/working_graph/.../RunGraphViewer.html`:
+  //
+  //   pre-foreach backbone ... → [anchor]
+  //                                 │
+  //                                 │ (Disbind PDF Into Pages, fork)
+  //                                 ▼
+  //             body_N_entry (per-body page, e.g. "page_3")
+  //                   │ (Make a Decision)
+  //                   ▼
+  //             body_N_step_0 (per-body Decision output)
+  //                   │
+  //                   ▼  (if Collect exists) → shared collect target
+  //                      (else terminal leaf)
+  //
+  // If the cap immediately before the ForEach has
+  // `output_is_sequence=true`, THAT cap is the fan-out point:
+  // its output IS the sequence the ForEach iterates. Its
+  // backbone output node is dropped (replicas own the per-body
+  // rendering), and its step becomes the "fork cap" whose title
+  // labels the anchor→entry edge on the first body.
+  //
+  // Without such a preceding sequence cap, the source itself is
+  // already a list (e.g. `media:pdf;list` source_spec) and the
+  // ForEach iterates it directly.
+  let seqProducerStepIdx = -1;
+  let seqProducerStep = null;
+  if (hasForeach && foreachStepIdx > 0) {
+    const preStep = steps[foreachStepIdx - 1];
+    if (Object.keys(preStep.step_type)[0] === 'Cap'
+        && preStep.step_type.Cap.output_is_sequence === true) {
+      seqProducerStepIdx = foreachStepIdx - 1;
+      seqProducerStep = preStep;
+    }
+  }
+
+  // The anchor is the node BEFORE the sequence producer (or
+  // before the ForEach if there is none). Every body iteration
+  // shares this node as its starting point; per-body entries fan
+  // out from here.
+  let anchorNodeId;
+  if (seqProducerStepIdx >= 0) {
+    anchorNodeId = seqProducerStepIdx > 0
+      ? `step_${seqProducerStepIdx - 1}`
+      : 'input_slot';
+  } else {
+    anchorNodeId = foreachStepIdx > 0
+      ? `step_${foreachStepIdx - 1}`
+      : 'input_slot';
+  }
+
+  // Strip nodes whose per-body replicas will replace them:
+  // the sequence producer's backbone output (if any) AND every
+  // body-interior cap. The foreach-entry edge is dropped
+  // automatically because its source/target is in this set.
+  const dropStepIds = new Set(bodyCapSteps.map(b => `step_${b.globalIndex}`));
+  if (seqProducerStepIdx >= 0) {
+    dropStepIds.add(`step_${seqProducerStepIdx}`);
+  }
+  let strandBuilt = stripRunBackboneReplicaNodes(strandBuiltCollapsed, dropStepIds);
+
+  // If there's a Collect, find the post-collect target in the
+  // backbone — the node successful replicas merge into. This is
+  // the first node reachable forward from the last body cap that
+  // isn't itself a body cap. Walk the pre-strip backbone so we
+  // can cross over the now-dropped body cap nodes.
+  let collectTargetId = null;
+  if (hasCollect && bodyCapSteps.length > 0) {
+    const lastBodyStepId = `step_${bodyCapSteps[bodyCapSteps.length - 1].globalIndex}`;
+    let cursor = lastBodyStepId;
+    let guard = 64;
+    while (guard-- > 0) {
+      const out = strandBuiltCollapsed.edges.find(e => e.source === cursor);
+      if (!out) break;
+      cursor = out.target;
+      if (!dropStepIds.has(cursor)) {
+        collectTargetId = cursor;
+        break;
+      }
+    }
+    // If the last-body-step is itself the merged terminal (no
+    // outgoing edge), there's no separate collect target —
+    // replicas simply don't merge and the terminal node stays
+    // dropped.
+  }
 
   const replicaNodes = [];
   const replicaEdges = [];
+  let replicasBuiltCount = 0;
+
+  // Look up a display name for a media URN via the host-supplied
+  // `media_display_names` map. Uses `MediaUrn.isEquivalent` for
+  // semantic URN equality.
+  const MediaUrn = requireHostDependency('MediaUrn');
+  const mediaDisplayNames = data.media_display_names || {};
+  const displayEntries = [];
+  for (const [urn, display] of Object.entries(mediaDisplayNames)) {
+    if (typeof display !== 'string' || display.length === 0) continue;
+    try {
+      displayEntries.push({ media: MediaUrn.fromString(urn), display });
+    } catch (_) { /* ignore malformed keys */ }
+  }
+  function displayNameFor(canonicalUrn) {
+    const candidate = MediaUrn.fromString(canonicalUrn);
+    for (const entry of displayEntries) {
+      if (candidate.isEquivalent(entry.media)) return entry.display;
+    }
+    return mediaNodeLabel(canonicalUrn);
+  }
+
+  // The per-body "entry" node represents one item of the
+  // sequence being iterated. Its URN is:
+  //   * the sequence producer cap's `to_spec` (if such a cap
+  //     precedes the ForEach) — this is what Disbind produces,
+  //     one-per-body.
+  //   * otherwise the ForEach step's own `to_spec` — used when
+  //     the source spec is already a list.
+  // Its label defaults to the display name of that URN and is
+  // overridden by the host's per-body `outcome.title` (e.g.
+  // "page_3") when provided.
+  const entryUrn = seqProducerStep
+    ? canonicalMediaUrn(seqProducerStep.to_spec)
+    : canonicalMediaUrn(steps[foreachStepIdx].to_spec);
+  const entryDefaultLabel = displayNameFor(entryUrn);
+
+  // Label shown on the anchor → first-body-entry edge. When the
+  // fan-out is caused by a sequence-producing cap, its title
+  // (e.g. "Disbind PDF Into Pages") labels that edge. The label
+  // appears on the FIRST body's fork edge only to avoid N copies
+  // of the same title cluttering the fan.
+  const forkEdgeTitle = seqProducerStep
+    ? seqProducerStep.step_type.Cap.title
+    : '';
+  const forkEdgeFullUrn = seqProducerStep
+    ? seqProducerStep.step_type.Cap.cap_urn
+    : '';
 
   function buildBodyReplica(outcome) {
     const success = outcome.success;
@@ -1045,7 +1537,7 @@ function buildRunGraphData(data) {
     const edgeClass = success ? 'body-success' : 'body-failure';
     const colorVar = success ? '--graph-body-edge-success' : '--graph-body-edge-failure';
 
-    // Trace end: failures stop at failed_cap. `CapUrn.isEquivalent`
+    // Trace end: failures stop at `failed_cap`. `CapUrn.isEquivalent`
     // is used for the match — never string equality.
     let traceEnd = bodyCapSteps.length;
     if (!success && typeof outcome.failed_cap === 'string' && outcome.failed_cap.length > 0) {
@@ -1059,13 +1551,48 @@ function buildRunGraphData(data) {
         }
       }
     }
-    if (traceEnd === 0) return;
 
-    let prevBodyNodeId = anchorNodeId;
     const bodyKey = `body-${outcome.body_index}`;
     const titleLabel = typeof outcome.title === 'string' && outcome.title.length > 0
       ? outcome.title
-      : `body ${outcome.body_index}`;
+      : entryDefaultLabel;
+
+    // Per-body entry node: one item from the iterated sequence.
+    const entryNodeId = `${bodyKey}-entry`;
+    replicaNodes.push({
+      group: 'nodes',
+      data: {
+        id: entryNodeId,
+        label: titleLabel,
+        fullUrn: entryUrn,
+        bodyIndex: outcome.body_index,
+        bodyTitle: titleLabel,
+      },
+      classes: successClass,
+    });
+
+    // Fan-out edge from the pre-foreach anchor to this body's
+    // entry. The fork label (cap title) shows on the FIRST body
+    // only to avoid N copies of the same title cluttering the
+    // fan. The `title` tooltip always exposes the cap title.
+    const isFirstReplica = replicasBuiltCount === 0;
+    const forkLabel = (forkEdgeTitle && isFirstReplica) ? forkEdgeTitle : '';
+    replicaEdges.push({
+      group: 'edges',
+      data: {
+        id: `${bodyKey}-fork`,
+        source: anchorNodeId,
+        target: entryNodeId,
+        label: forkLabel,
+        title: forkEdgeTitle || `body ${outcome.body_index}`,
+        fullUrn: forkEdgeFullUrn,
+        color: `var(${colorVar})`,
+        bodyIndex: outcome.body_index,
+      },
+      classes: edgeClass,
+    });
+
+    let prevBodyNodeId = entryNodeId;
 
     for (let i = 0; i < traceEnd; i++) {
       const body = bodyCapSteps[i].step.step_type.Cap;
@@ -1075,7 +1602,7 @@ function buildRunGraphData(data) {
         group: 'nodes',
         data: {
           id: replicaNodeId,
-          label: mediaNodeLabel(targetCanonical),
+          label: displayNameFor(targetCanonical),
           fullUrn: targetCanonical,
           bodyIndex: outcome.body_index,
           bodyTitle: titleLabel,
@@ -1088,7 +1615,11 @@ function buildRunGraphData(data) {
           id: `${bodyKey}-e-${i}`,
           source: prevBodyNodeId,
           target: replicaNodeId,
-          label: i === 0 ? body.title : '',
+          // Replica edges carry no inline label — the cap title is
+          // identical across every visible replica and would pile
+          // up as unreadable rotated text across the fan-out. The
+          // hover tooltip exposes the title via `title`.
+          label: '',
           title: body.title,
           fullUrn: body.cap_urn,
           color: `var(${colorVar})`,
@@ -1099,17 +1630,18 @@ function buildRunGraphData(data) {
       prevBodyNodeId = replicaNodeId;
     }
 
-    // Successful bodies merge their replica tail back into the Collect
-    // node (or `output` if the ForEach is unclosed) so the graph
-    // visibly fans in. Failed bodies do NOT merge — the trace
-    // terminates at the failed cap.
-    if (success) {
+    // Successful bodies merge into the collect target ONLY when a
+    // Collect closes the foreach body. Without a Collect (the
+    // common "unclosed foreach" case in machfab realize_strand),
+    // replicas terminate at their last body step — each body has
+    // its own separate output, no shared merge.
+    if (success && hasCollect && collectTargetId) {
       replicaEdges.push({
         group: 'edges',
         data: {
-          id: `${bodyKey}-merge`,
+          id: `${bodyKey}-collect`,
           source: prevBodyNodeId,
-          target: mergeNodeId,
+          target: collectTargetId,
           label: '',
           title: 'collect',
           fullUrn: '',
@@ -1119,10 +1651,11 @@ function buildRunGraphData(data) {
         classes: edgeClass,
       });
     }
+
+    replicasBuiltCount++;
   }
 
-  visibleSuccess.forEach((o) => buildBodyReplica(o));
-  visibleFailure.forEach((o) => buildBodyReplica(o));
+  visibleOutcomes.forEach((o) => buildBodyReplica(o));
 
   // Build success and failure "show more" nodes when there are hidden
   // outcomes. Anchored at the ForEach node (or input_slot if none).
@@ -1200,7 +1733,11 @@ function buildRunGraphData(data) {
 }
 
 function runCytoscapeElements(built) {
-  const strandElements = strandCytoscapeElements(built.strandBuilt);
+  // Run mode's `buildRunGraphData` already applied the strand
+  // collapse to its backbone (and dropped body-interior caps
+  // that are replaced by per-body replicas). Emit the backbone
+  // verbatim — `{ collapse: false }` prevents a second pass.
+  const strandElements = strandCytoscapeElements(built.strandBuilt, { collapse: false });
   return strandElements
     .concat(built.replicaNodes)
     .concat(built.showMoreNodes)
@@ -1209,67 +1746,150 @@ function runCytoscapeElements(built) {
 
 // --------- Machine mode builder ---------------------------------------------
 
-function buildMachineGraphData(data) {
-  validateMachinePayload(data);
-  const nodes = [];
-  const edges = [];
-  let capEdgeIdx = 0;
+// The notation analyzer emits a bipartite graph where each cap
+// application is a 3-element chain:
+//
+//   data_node → [argument edge] → cap_node → [argument edge] → data_node
+//
+// The render collapses that chain into a single labeled data→data
+// edge carrying the cap's name (and cardinality marker derived
+// from the source/target data nodes' `is_sequence` flags). Cap
+// nodes and argument edges are dropped. The result is a clean
+// abstract-machine view that matches strand mode's rendering
+// style: one edge per cap application, labeled with the cap
+// title, with cardinality markers where relevant.
+function buildEditorGraphData(data) {
+  validateEditorGraphPayload(data);
+
+  // Index elements by kind for quick lookup.
+  const dataNodes = new Map(); // graph_id → element
+  const capNodes = new Map();  // graph_id → element
+  const argEdges = [];         // list of edge elements
   for (const el of data.elements) {
     if (el.kind === 'node') {
-      nodes.push({
-        group: 'nodes',
-        data: {
-          id: el.graph_id,
-          label: el.label || '',
-          fullUrn: el.detail || el.label || '',
-          tokenId: el.token_id || '',
-          kind: 'node',
-        },
-        classes: 'machine-node',
-      });
+      dataNodes.set(el.graph_id, el);
     } else if (el.kind === 'cap') {
-      nodes.push({
-        group: 'nodes',
-        data: {
-          id: el.graph_id,
-          label: el.label || '',
-          fullUrn: el.detail || el.label || '',
-          tokenId: el.token_id || '',
-          kind: 'cap',
-        },
-        classes: 'machine-cap' + (el.is_loop ? ' machine-loop' : ''),
-      });
+      capNodes.set(el.graph_id, el);
     } else if (el.kind === 'edge') {
-      edges.push({
-        group: 'edges',
-        data: {
-          id: el.graph_id,
-          source: el.source_graph_id,
-          target: el.target_graph_id,
-          label: el.label || '',
-          title: el.label || '',
-          fullUrn: el.detail || '',
-          tokenId: el.token_id || '',
-          color: el.is_loop
-            ? 'var(--graph-node-border-highlighted)'
-            : edgeHueColor(capEdgeIdx),
-        },
-        classes: 'machine-edge' + (el.is_loop ? ' machine-loop' : ''),
-      });
-      capEdgeIdx++;
+      argEdges.push(el);
+    }
+  }
+
+  // For each cap, identify its incoming and outgoing argument
+  // edges. Incoming edges connect a data-slot source → this cap.
+  // Outgoing edges connect this cap → a data-slot target.
+  const capIncoming = new Map(); // capId → [argEdge, ...]
+  const capOutgoing = new Map(); // capId → [argEdge, ...]
+  for (const e of argEdges) {
+    if (capNodes.has(e.target_graph_id)) {
+      if (!capIncoming.has(e.target_graph_id)) capIncoming.set(e.target_graph_id, []);
+      capIncoming.get(e.target_graph_id).push(e);
+    }
+    if (capNodes.has(e.source_graph_id)) {
+      if (!capOutgoing.has(e.source_graph_id)) capOutgoing.set(e.source_graph_id, []);
+      capOutgoing.get(e.source_graph_id).push(e);
     }
   }
+
+  const nodes = [];
+  const edges = [];
+
+  // Emit the data slot nodes verbatim.
+  for (const el of dataNodes.values()) {
+    nodes.push({
+      group: 'nodes',
+      data: {
+        id: el.graph_id,
+        label: el.label || '',
+        fullUrn: el.detail || el.label || '',
+        tokenId: el.token_id || '',
+        kind: 'node',
+        isSequence: el.is_sequence === true,
+      },
+      classes: 'machine-node',
+    });
+  }
+
+  // Collapse each cap into one labeled edge per (input, output)
+  // data-slot pair. For a simple single-input single-output cap
+  // that's one edge. Multi-arg caps emit one edge per combination,
+  // preserving the argument structure while still using a single
+  // visual target per cap application.
+  let capEdgeIdx = 0;
+  for (const [capId, capEl] of capNodes) {
+    const incoming = capIncoming.get(capId) || [];
+    const outgoing = capOutgoing.get(capId) || [];
+
+    // Degenerate cases: a cap with no incoming or no outgoing
+    // argument edges (e.g. partially-written notation). Render
+    // nothing for it — the user sees a missing edge where they
+    // need to complete the notation.
+    if (incoming.length === 0 || outgoing.length === 0) continue;
+
+    // Cardinality of the cap's visual edge comes from the
+    // source-side and target-side data-slot `is_sequence` flags.
+    // When a cap has multiple inputs/outputs, use the MOST
+    // restrictive reading (any seq input → `is_sequence=true` on
+    // that side). This mirrors how cardinalityLabel collapses
+    // multi-arg caps in the strand/browse builders.
+    const inputIsSequence = incoming.some(e => {
+      const src = dataNodes.get(e.source_graph_id);
+      return src && src.is_sequence === true;
+    });
+    const outputIsSequence = outgoing.some(e => {
+      const tgt = dataNodes.get(e.target_graph_id);
+      return tgt && tgt.is_sequence === true;
+    });
+    const cardinality = cardinalityLabel(inputIsSequence, outputIsSequence);
+    const capTitle = capEl.label || '';
+    const label = cardinality === '1\u21921'
+      ? capTitle
+      : `${capTitle} (${cardinality})`;
+
+    const color = capEl.is_loop
+      ? 'var(--graph-loop-color)'
+      : edgeHueColor(capEdgeIdx);
+    const baseClasses = capEl.is_loop ? 'machine-edge machine-loop' : 'machine-edge';
+
+    // Cartesian over incoming × outgoing.  For the common case
+    // of one incoming + one outgoing, that's exactly one emitted
+    // edge.
+    for (const inEdge of incoming) {
+      for (const outEdge of outgoing) {
+        edges.push({
+          group: 'edges',
+          data: {
+            id: `${capId}-${inEdge.graph_id}-${outEdge.graph_id}`,
+            source: inEdge.source_graph_id,
+            target: outEdge.target_graph_id,
+            label,
+            title: capTitle,
+            fullUrn: capEl.linked_cap_urn || capEl.detail || '',
+            // The cap node's token id is what the editor uses
+            // for cross-highlighting; prefer that over the arg
+            // edge token ids so clicking the rendered edge
+            // selects the cap in the source text.
+            tokenId: capEl.token_id || '',
+            color: color,
+          },
+          classes: baseClasses,
+        });
+      }
+    }
+    capEdgeIdx++;
+  }
+
   return { nodes, edges };
 }
 
-function machineCytoscapeElements(built) {
+function editorGraphCytoscapeElements(built) {
   return built.nodes.concat(built.edges);
 }
 
-// A cheap signature for machine-mode inputs. The editor streams updates
-// on every keystroke; we skip the expensive rebuild when the element
-// shape is unchanged.
-function machineGraphSignature(data) {
+// A cheap signature for editor-graph mode inputs. The editor streams
+// updates on every keystroke; we skip the expensive rebuild when the
+// element shape is unchanged.
+function editorGraphSignature(data) {
   if (!data || !Array.isArray(data.elements)) return '';
   const parts = [];
   for (const el of data.elements) {
@@ -1278,6 +1898,110 @@ function machineGraphSignature(data) {
   return parts.join(';');
 }
 
+// `buildResolvedMachineGraphData` consumes the canonical
+// `Machine::to_render_payload_json` shape and produces the cytoscape
+// elements list directly. Each strand contributes its own nodes and
+// edges to the same graph; cytoscape lays disconnected components
+// side by side.
+//
+// Node ids and edge aliases are globally unique across all strands
+// (the Rust serializer assigns them from a single global counter),
+// so we can pass them straight through to cytoscape without name
+// collisions.
+//
+// Each cap edge is rendered as one cytoscape edge per
+// (assignment.source_node, target_node) pair. The common
+// single-input cap produces exactly one rendered edge; multi-input
+// (fan-in) caps produce one edge per source-arg slot, all sharing
+// the cap title and color so they read as a single fan-in.
+function buildResolvedMachineGraphData(data) {
+  validateResolvedMachinePayload(data);
+
+  const nodes = [];
+  const edges = [];
+  const seenNodeIds = new Set();
+  let edgeCounter = 0;
+
+  data.strands.forEach((strand, strandIdx) => {
+    const inputAnchorSet = new Set(strand.input_anchor_nodes);
+    const outputAnchorSet = new Set(strand.output_anchor_nodes);
+
+    for (const node of strand.nodes) {
+      // Each node id is unique across the whole machine; the
+      // Rust side guarantees this via its global counter. If a
+      // duplicate appears it indicates a malformed payload, so
+      // fail hard rather than silently dropping.
+      if (seenNodeIds.has(node.id)) {
+        throw new Error(
+          `CapGraphRenderer machine mode: duplicate node id "${node.id}" in strand ${strandIdx}`
+        );
+      }
+      seenNodeIds.add(node.id);
+
+      const nodeClasses = ['machine-node'];
+      if (inputAnchorSet.has(node.id)) nodeClasses.push('strand-source');
+      if (outputAnchorSet.has(node.id)) nodeClasses.push('strand-target');
+
+      nodes.push({
+        group: 'nodes',
+        data: {
+          id: node.id,
+          label: mediaNodeLabel(canonicalMediaUrn(node.urn)),
+          fullUrn: node.urn,
+          strandIndex: strandIdx,
+        },
+        classes: nodeClasses.join(' '),
+      });
+    }
+
+    for (const edge of strand.edges) {
+      const cardinality = edge.is_loop ? 'n\u21921' : '1\u21921';
+      const capUrn = edge.cap_urn;
+      // Title falls back to the canonical cap URN. The host can
+      // pre-resolve a friendlier title via `step_titles` on the
+      // proto message and use it elsewhere in the UI; the graph
+      // renderer is intentionally registry-free.
+      const capTitle = capUrn;
+      const label = cardinality === '1\u21921'
+        ? edge.alias
+        : `${edge.alias} (${cardinality})`;
+
+      const color = edge.is_loop
+        ? 'var(--graph-loop-color)'
+        : edgeHueColor(edgeCounter);
+      const baseClasses = edge.is_loop
+        ? 'machine-edge machine-loop'
+        : 'machine-edge';
+
+      for (const binding of edge.assignment) {
+        edges.push({
+          group: 'edges',
+          data: {
+            id: `machine-edge-${edgeCounter}`,
+            source: binding.source_node,
+            target: edge.target_node,
+            label,
+            title: `${capTitle} (${binding.cap_arg_media_urn})`,
+            fullUrn: capUrn,
+            color,
+            strandIndex: strandIdx,
+            capArgMediaUrn: binding.cap_arg_media_urn,
+            isLoop: edge.is_loop,
+          },
+          classes: baseClasses,
+        });
+        edgeCounter++;
+      }
+    }
+  });
+
+  return { nodes, edges };
+}
+
+function resolvedMachineCytoscapeElements(built) {
+  return built.nodes.concat(built.edges);
+}
+
 // =============================================================================
 // Renderer class.
 // =============================================================================
@@ -1291,9 +2015,9 @@ class CapGraphRenderer {
       throw new Error('CapGraphRenderer: options must be an object');
     }
     const mode = options.mode;
-    if (mode !== 'browse' && mode !== 'strand' && mode !== 'run' && mode !== 'machine') {
+    if (mode !== 'browse' && mode !== 'strand' && mode !== 'run' && mode !== 'machine' && mode !== 'editor-graph') {
       throw new Error(
-        `CapGraphRenderer: options.mode must be one of "browse", "strand", "run", "machine" (got ${JSON.stringify(mode)})`
+        `CapGraphRenderer: options.mode must be one of "browse", "strand", "run", "machine", "editor-graph" (got ${JSON.stringify(mode)})`
       );
     }
 
@@ -1357,8 +2081,12 @@ class CapGraphRenderer {
     this._strandBuilt = null;
     this._runBuilt = null;
 
-    // Machine state.
-    this._machineSignature = null;
+    // Editor-graph state (Monaco machine-notation editor live view).
+    this._editorGraphSignature = null;
+    this._editorGraphBuilt = null;
+
+    // Resolved-machine state (canonical Machine render payload from
+    // Rust `Machine::to_render_payload_json`).
     this._machineBuilt = null;
 
     // Theme observer.
@@ -1410,15 +2138,19 @@ class CapGraphRenderer {
       this._runBuilt = buildRunGraphData(data);
       return this;
     }
-    if (this.mode === 'machine') {
-      const signature = machineGraphSignature(data);
-      if (signature === this._machineSignature && this.cy) {
+    if (this.mode === 'editor-graph') {
+      const signature = editorGraphSignature(data);
+      if (signature === this._editorGraphSignature && this.cy) {
         // Same shape — restyle for theme changes and return.
         this.cy.style(buildStylesheet());
         return this;
       }
-      this._machineSignature = signature;
-      this._machineBuilt = buildMachineGraphData(data);
+      this._editorGraphSignature = signature;
+      this._editorGraphBuilt = buildEditorGraphData(data);
+      return this;
+    }
+    if (this.mode === 'machine') {
+      this._machineBuilt = buildResolvedMachineGraphData(data);
       return this;
     }
     throw new Error(`CapGraphRenderer: unreachable mode '${this.mode}'`);
@@ -1486,7 +2218,7 @@ class CapGraphRenderer {
       maxZoom: 10,
       wheelSensitivity: 0.3,
       boxSelectionEnabled: false,
-      autounselectify: this.mode === 'machine',
+      autounselectify: this.mode === 'editor-graph' || this.mode === 'machine',
     });
 
     const resizeAndRefit = () => {
@@ -1519,9 +2251,13 @@ class CapGraphRenderer {
       if (!this._runBuilt) return [];
       return runCytoscapeElements(this._runBuilt);
     }
+    if (this.mode === 'editor-graph') {
+      if (!this._editorGraphBuilt) return [];
+      return editorGraphCytoscapeElements(this._editorGraphBuilt);
+    }
     if (this.mode === 'machine') {
       if (!this._machineBuilt) return [];
-      return machineCytoscapeElements(this._machineBuilt);
+      return resolvedMachineCytoscapeElements(this._machineBuilt);
     }
     throw new Error(`CapGraphRenderer: unreachable mode '${this.mode}'`);
   }
@@ -1782,12 +2518,13 @@ class CapGraphRenderer {
   }
 
   // ===========================================================================
-  // Machine mode API — used by the editor for cross-highlight.
+  // Editor-graph mode API — used by the notation editor for
+  // cross-highlight between source-text spans and graph elements.
   // ===========================================================================
 
-  applyMachineActiveTokenIds(tokenIds) {
-    if (this.mode !== 'machine') {
-      throw new Error(`CapGraphRenderer: applyMachineActiveTokenIds is only valid in machine mode (current: ${this.mode})`);
+  applyEditorGraphActiveTokenIds(tokenIds) {
+    if (this.mode !== 'editor-graph') {
+      throw new Error(`CapGraphRenderer: applyEditorGraphActiveTokenIds is only valid in editor-graph mode (current: ${this.mode})`);
     }
     if (!this.cy) return;
     const wanted = new Set(tokenIds || []);
@@ -2103,12 +2840,15 @@ if (typeof module !== 'undefined' && module.exports) {
     mediaNodeLabel,
     buildBrowseGraphData,
     buildStrandGraphData,
+    collapseStrandShapeTransitions,
     buildRunGraphData,
-    buildMachineGraphData,
+    buildEditorGraphData,
+    buildResolvedMachineGraphData,
     classifyStrandCapSteps,
     validateStrandPayload,
     validateRunPayload,
-    validateMachinePayload,
+    validateEditorGraphPayload,
+    validateResolvedMachinePayload,
     validateStrandStep,
     validateBodyOutcome,
   };