capdag 0.106.243 → 0.119.263

package/cap-graph-renderer.js

@@ -271,7 +271,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,
@@ -663,22 +667,38 @@ function classifyStrandCapSteps(steps) {
   return { capStepIndices, capFlags };
 }
 
-// Build the strand graph. Every Cap step becomes an edge
-// (`from_spec` → `to_spec`). ForEach / Collect are NOT rendered as nodes
-// — they are transitions that annotate the adjacent cap edges:
+// Build the strand graph by mirroring capdag's plan builder
+// (`capdag/src/planner/plan_builder.rs::build_plan_from_path`). The plan
+// builder is the authoritative source of truth for how strand steps
+// translate into a DAG of nodes and edges:
 //
-//   * A Cap whose previous step is ForEach gets the prefix "for each"
-//     on its edge label (the first-body entry edge).
-//   * A Cap whose next step is Collect gets the suffix "collect" on its
-//     edge label (the last-body exit edge).
+//   * Node IDs are positional: `input_slot`, `step_0`, `step_1`, …,
+//     `output`. They are NOT media URN strings — URN comparisons for
+//     graph topology are wrong because the planner connects steps by
+//     the order-theoretic `conformsTo` relation, not by string equality.
+//   * `prev_node_id` is a single running pointer, only advanced by Cap
+//     steps. ForEach steps mark the start of a body span without
+//     advancing prev; the body's first Cap still connects to whatever
+//     was before the ForEach.
+//   * Cap inside a ForEach body connects from `prev_node_id` like any
+//     other cap, AND tracks `body_entry` (first cap in body) and
+//     `body_exit` (most recent cap in body).
+//   * Collect after a ForEach body creates a ForEach node with
+//     boundaries, an iteration edge to body_entry, a Collect node, and
+//     a collection edge from body_exit to Collect. prev_node_id becomes
+//     the Collect node.
+//   * Standalone Collect (no enclosing ForEach) creates a Collect node
+//     consuming prev_node_id directly.
+//   * Unclosed ForEach with no body caps is a terminal unwrap — the
+//     ForEach node is skipped; prev_node_id stays as-is.
+//   * Unclosed ForEach WITH body caps gets a ForEach node, iteration
+//     edge to body_entry, and prev_node_id becomes body_exit.
 //
-// Source-to-body and body-to-target continuity is guaranteed by the
-// strand structure itself: consecutive cap steps satisfy
-// `stepN.to_spec == stepN+1.from_spec`, and fix-up edges are added
-// explicitly when the strand's `source_spec` differs from the first cap
-// step's `from_spec` (the ForEach shape transition) or when the strand's
-// `target_spec` differs from the last cap step's `to_spec` (the Collect
-// shape transition).
+// Node labels come from the `media_display_names` map keyed by the
+// step's canonical URN (or source_spec/target_spec for the boundary
+// nodes). ForEach and Collect nodes display "for each" / "collect".
+// Cap edges carry the cap title plus cardinality marker when either
+// input or output is a sequence.
 function buildStrandGraphData(data) {
   validateStrandPayload(data);
 
@@ -686,158 +706,520 @@ function buildStrandGraphData(data) {
   const sourceSpec = canonicalMediaUrn(data.source_spec);
   const targetSpec = canonicalMediaUrn(data.target_spec);
 
-  const canonicalDisplayLookup = new Map();
+  // Look up a display name for a media URN via the host-supplied map.
+  // Uses `MediaUrn.isEquivalent` so tag-order variation doesn't defeat
+  // the lookup — URNs are compared semantically, never as raw strings.
+  const MediaUrn = requireHostDependency('MediaUrn');
+  const displayEntries = [];
   for (const [urn, display] of Object.entries(mediaDisplayNames)) {
-    if (typeof display === 'string' && display.length > 0) {
-      canonicalDisplayLookup.set(canonicalMediaUrn(urn), display);
+    if (typeof display !== 'string' || display.length === 0) continue;
+    try {
+      displayEntries.push({ media: MediaUrn.fromString(urn), display });
+    } catch (_) {
+      // Skip entries with unparseable URN keys — the host payload is
+      // trusted, but malformed keys are not fatal.
+    }
+  }
+  function displayNameFor(canonicalUrn) {
+    const candidate = MediaUrn.fromString(canonicalUrn);
+    for (const entry of displayEntries) {
+      if (candidate.isEquivalent(entry.media)) return entry.display;
     }
+    return mediaNodeLabel(canonicalUrn);
   }
 
-  const nodesMap = new Map();
-  function ensureNode(canonicalUrn) {
-    if (!nodesMap.has(canonicalUrn)) {
-      const displayName = canonicalDisplayLookup.get(canonicalUrn);
-      nodesMap.set(canonicalUrn, {
-        id: canonicalUrn,
-        label: displayName !== undefined ? displayName : mediaNodeLabel(canonicalUrn),
-        fullUrn: canonicalUrn,
-      });
+  const nodes = [];
+  const edges = [];
+  const nodeIds = new Set();
+
+  function addNode(id, label, fullUrn, nodeClass) {
+    if (nodeIds.has(id)) return;
+    nodeIds.add(id);
+    nodes.push({
+      id,
+      label,
+      fullUrn: fullUrn || '',
+      nodeClass: nodeClass || '',
+    });
+  }
+  let edgeCounter = 0;
+  function addEdge(source, target, label, title, fullUrn, edgeClass, meta) {
+    const m = meta || {};
+    edges.push({
+      id: `strand-edge-${edgeCounter}`,
+      source,
+      target,
+      label: label || '',
+      title: title || '',
+      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,
+      // `singleCapClosedBody` flags a foreach-entry cap edge whose
+      // body is closed by a Collect AND contains exactly one cap.
+      // Such a cap is both the body entry and the body exit; the
+      // render labels the edge with (n→n) to combine iterate+collect.
+      singleCapClosedBody: m.singleCapClosedBody === true,
+    });
+    edgeCounter++;
+  }
+  // Find the most recently added cap edge whose target is `nodeId`
+  // and stamp it with `singleCapClosedBody=true`. Used by the Collect
+  // handler when a closed body has exactly one cap (bodyEntry === bodyExit).
+  function markSingleCapClosedBody(nodeId) {
+    if (!nodeId) return;
+    for (let idx = edges.length - 1; idx >= 0; idx--) {
+      const e = edges[idx];
+      if (e.edgeClass === 'strand-cap-edge' && e.target === nodeId) {
+        e.singleCapClosedBody = true;
+        return;
+      }
     }
-    return canonicalUrn;
   }
 
-  ensureNode(sourceSpec);
-  ensureNode(targetSpec);
+  // Entry node — the strand's source media spec.
+  const inputSlotId = 'input_slot';
+  addNode(inputSlotId, displayNameFor(sourceSpec), sourceSpec, 'strand-source');
 
-  const { capStepIndices } = classifyStrandCapSteps(data.steps);
-  const firstCapIdx = capStepIndices.length > 0 ? capStepIndices[0] : -1;
-  const lastCapIdx = capStepIndices.length > 0 ? capStepIndices[capStepIndices.length - 1] : -1;
-  const hasLeadingForEach = data.steps.some((s, i) =>
-    Object.keys(s.step_type)[0] === 'ForEach' && i < (firstCapIdx === -1 ? Infinity : firstCapIdx));
-  const hasTrailingCollect = data.steps.some((s, i) =>
-    Object.keys(s.step_type)[0] === 'Collect' && i > (lastCapIdx === -1 ? -Infinity : lastCapIdx));
+  let prevNodeId = inputSlotId;
 
-  const edges = [];
-  let capEdgeIdx = 0;
+  // Track ForEach body membership. `insideForEachBody = { index, nodeId }`
+  // records which ForEach step we're inside and the id we'll give its
+  // eventual node. `bodyEntry`/`bodyExit` track the first and most
+  // recent Cap step inside that body.
+  let insideForEachBody = null;
+  let bodyEntry = null;
+  let bodyExit = null;
 
-  // Prepend a fix-up edge from source_spec to the first cap step's
-  // from_spec when they differ. This is the ForEach shape transition
-  // rendered as an explicit edge.
-  if (firstCapIdx >= 0) {
-    const firstCap = data.steps[firstCapIdx];
-    const firstCapFrom = canonicalMediaUrn(firstCap.from_spec);
-    if (firstCapFrom !== sourceSpec) {
-      ensureNode(firstCapFrom);
-      const label = hasLeadingForEach ? 'for each' : '';
-      edges.push({
-        id: `strand-edge-${capEdgeIdx}`,
-        source: sourceSpec,
-        target: firstCapFrom,
-        title: label || 'fan-out',
-        label,
-        cardinality: '',
-        capUrn: '',
-        color: edgeHueColor(capEdgeIdx),
-      });
-      capEdgeIdx++;
-    }
+  // Finalize an outer ForEach body when a nested ForEach starts before
+  // 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}`;
+    addNode(outerForEach.nodeId, 'for each', '', 'strand-foreach');
+    addEdge(outerForEachInput, outerForEach.nodeId, 'for each', 'for each', '', 'strand-iteration');
+    addEdge(outerForEach.nodeId, outerEntry, '', '', '', 'strand-iteration');
+    return outerExit;
   }
 
-  // Cap step edges. Each Cap's edge connects its from_spec to its
-  // to_spec. Adjacent cap edges are continuous because the planner
-  // guarantees stepN.to_spec == stepN+1.from_spec. "for each" and
-  // "collect" labels belong on the fix-up edges around the cap chain,
-  // not on the cap edges themselves — those labels describe shape
-  // transitions between the source list and the first body scalar (and
-  // between the last body scalar and the target list), which are the
-  // fix-up edges.
-  data.steps.forEach((step) => {
+  data.steps.forEach((step, i) => {
     const variant = Object.keys(step.step_type)[0];
-    if (variant !== 'Cap') return;
-    const body = step.step_type.Cap;
-    const fromCanonical = canonicalMediaUrn(step.from_spec);
-    const toCanonical = canonicalMediaUrn(step.to_spec);
-    ensureNode(fromCanonical);
-    ensureNode(toCanonical);
+    const nodeId = `step_${i}`;
+
+    if (variant === 'Cap') {
+      const body = step.step_type.Cap;
+      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',
+        { foreachEntry: isForeachEntry }
+      );
+
+      if (insideForEachBody !== null) {
+        if (bodyEntry === null) bodyEntry = nodeId;
+        bodyExit = nodeId;
+      }
 
-    let label = body.title;
-    const cardinality = cardinalityLabel(body.input_is_sequence, body.output_is_sequence);
-    if (cardinality !== '1\u21921') {
-      label = `${label} (${cardinality})`;
+      prevNodeId = nodeId;
+      return;
     }
 
-    edges.push({
-      id: `strand-edge-${capEdgeIdx}`,
-      source: fromCanonical,
-      target: toCanonical,
-      title: body.title,
-      label,
-      cardinality,
-      capUrn: body.cap_urn,
-      color: edgeHueColor(capEdgeIdx),
-    });
-    capEdgeIdx++;
+    if (variant === 'ForEach') {
+      // If we're already inside a ForEach body when another ForEach
+      // starts, finalize the outer one first.
+      if (insideForEachBody !== null) {
+        const outer = insideForEachBody;
+        const entry = bodyEntry !== null ? bodyEntry : prevNodeId;
+        const exit = bodyExit !== null ? bodyExit : prevNodeId;
+        if (bodyEntry === null) {
+          // Outer ForEach with no body caps is an illegal nesting; the
+          // plan builder throws. Mirror that.
+          throw new Error(
+            `CapGraphRenderer strand: nested ForEach at step[${i}] but outer ForEach at step[${outer.index}] has no body caps`
+          );
+        }
+        prevNodeId = finalizeOuterForEach(outer, entry, exit);
+        bodyEntry = null;
+        bodyExit = null;
+      }
+      insideForEachBody = { index: i, nodeId };
+      bodyEntry = null;
+      bodyExit = null;
+      // Do NOT advance prevNodeId — the body's first cap will connect
+      // to whatever was before the ForEach.
+      return;
+    }
+
+    if (variant === 'Collect') {
+      if (insideForEachBody !== null) {
+        const outer = insideForEachBody;
+        const entry = bodyEntry !== null ? bodyEntry : prevNodeId;
+        const exit = bodyExit !== null ? bodyExit : prevNodeId;
+        const outerForEachInput = outer.index === 0
+          ? inputSlotId
+          : `step_${outer.index - 1}`;
+
+        addNode(outer.nodeId, 'for each', '', 'strand-foreach');
+        addEdge(outerForEachInput, outer.nodeId, 'for each', 'for each', '', 'strand-iteration');
+        addEdge(outer.nodeId, entry, '', '', '', 'strand-iteration');
+
+        addNode(nodeId, 'collect', '', 'strand-collect');
+        addEdge(exit, nodeId, 'collect', 'collect', '', 'strand-collection');
+
+        // Single-cap closed body: the single cap serves as both the
+        // body entry and the body exit. The render collapse uses
+        // this flag to pick the (n→n) combined cardinality marker
+        // for the entry edge and emit a plain unlabeled connector
+        // for the synthesized exit edge.
+        if (bodyEntry !== null && bodyEntry === bodyExit) {
+          markSingleCapClosedBody(bodyEntry);
+        }
+
+        insideForEachBody = null;
+        bodyEntry = null;
+        bodyExit = null;
+        prevNodeId = nodeId;
+      } else {
+        // Standalone Collect — scalar → list-of-one. Mirrors
+        // 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;
+      }
+      return;
+    }
+
+    throw new Error(`CapGraphRenderer strand: unknown step_type variant '${variant}' at step[${i}]`);
   });
 
-  // Append a fix-up edge from the last cap's to_spec to target_spec
-  // when they differ. This is the Collect shape transition as an
-  // explicit edge.
-  if (lastCapIdx >= 0) {
-    const lastCap = data.steps[lastCapIdx];
-    const lastCapTo = canonicalMediaUrn(lastCap.to_spec);
-    if (lastCapTo !== targetSpec) {
-      const label = hasTrailingCollect ? 'collect' : '';
-      edges.push({
-        id: `strand-edge-${capEdgeIdx}`,
-        source: lastCapTo,
-        target: targetSpec,
-        title: label || 'fan-in',
-        label,
-        cardinality: '',
-        capUrn: '',
-        color: edgeHueColor(capEdgeIdx),
-      });
-      capEdgeIdx++;
+  // Handle unclosed ForEach after the walk. Mirrors plan_builder.rs:362-428.
+  // An unclosed ForEach with a body is NOT marked as `singleCapClosedBody`
+  // because there's no Collect closing it — the body "fans out" but
+  // never converges. The body entry still gets (1→n) on its incoming
+  // edge via the foreachEntry flag set in the Cap handler.
+  if (insideForEachBody !== null) {
+    const outer = insideForEachBody;
+    const hasBodyEntry = bodyEntry !== null;
+    if (hasBodyEntry) {
+      const entry = bodyEntry;
+      const exit = bodyExit;
+      const outerForEachInput = outer.index === 0
+        ? inputSlotId
+        : `step_${outer.index - 1}`;
+      addNode(outer.nodeId, 'for each', '', 'strand-foreach');
+      addEdge(outerForEachInput, outer.nodeId, 'for each', 'for each', '', 'strand-iteration');
+      addEdge(outer.nodeId, entry, '', '', '', 'strand-iteration');
+      prevNodeId = exit;
+    }
+    // hasBodyEntry === false is a terminal unwrap — skip the ForEach
+    // node entirely, prev_node_id stays as-is.
+    insideForEachBody = null;
+    bodyEntry = null;
+    bodyExit = null;
+  }
+
+  // Final output node. Mirrors plan_builder.rs:430-432.
+  const outputId = 'output';
+  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 };
+}
+
+// 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 (1→n) overrides whatever cardinality
+//      the cap's own `input_is_sequence`/`output_is_sequence` would
+//      produce, because visually the transition is the foreach.
+//
+//   3. The last cap edge exiting a ForEach body is replaced by a
+//      synthesized bridging edge labeled `<cap_title> (n→1)` — the
+//      symmetric counterpart of the foreach-entry (1→n) label.
+//      For a single-cap body (same cap is entry and exit) the flag
+//      `singleCapClosedBody` collapses both markers into a single
+//      `(n→n)` label on the entry edge, and the exit side becomes
+//      a plain unlabeled connector.
+//
+//   4. Standalone Collect (not wrapping a ForEach) synthesizes a
+//      plain edge labeled `"collect"` — the Collect is rendered
+//      as a transition, not the preceding cap's own label.
+//
+//   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');
+  const foreachCardinality = cardinalityLabel(false, true); // "1→n"
+  const collectCardinality = cardinalityLabel(true, false); // "n→1"
+
+  // 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 the
+  // 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. To preserve
+  // the flow from body_exit to `next`, we synthesize a new edge
+  // body_exit → next. Its label depends on the Collect's
+  // context (determined by inspecting the body_exit cap's own
+  // incoming edge):
+  //
+  //   * Standalone Collect (no enclosing foreach; body_exit is a
+  //     plain cap with no foreach markers): synthesize a plain
+  //     edge labeled "collect" — the Collect itself is the
+  //     transition the user sees.
+  //
+  //   * Closed-body Collect with a single-cap body (the body_exit
+  //     cap edge is flagged `singleCapClosedBody`): synthesize an
+  //     unlabeled connector. The single cap's own entry edge is
+  //     relabeled with (n→n) in step 2 and carries both the
+  //     iterate and collect semantics at once.
+  //
+  //   * Closed-body Collect with a multi-cap body (body_exit cap
+  //     edge is a plain cap edge inside the body, NOT marked as
+  //     foreachEntry or singleCapClosedBody): label the synth
+  //     edge with the body-exit cap's title + (n→1) — the
+  //     symmetric counterpart of the foreach-entry (1→n) 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);
+        // Is the Collect part of a closed foreach body? A Collect
+        // is "closed" when the body_exit cap is reachable from the
+        // same foreach that the Collect closes. We detect this by
+        // checking whether the Collect's target node has any
+        // incoming iteration edge (i.e. there's a strand-foreach
+        // node whose outgoing iteration reaches the body_exit or
+        // one of its upstream cap nodes). Simpler heuristic that
+        // works for every shape we emit: the body_exit has an
+        // ancestor that is a strand-foreach node.
+        let hasEnclosingForeach = false;
+        {
+          const visited = new Set();
+          const stack = [bodyExitNodeId];
+          while (stack.length > 0) {
+            const cur = stack.pop();
+            if (visited.has(cur)) continue;
+            visited.add(cur);
+            const curNode = built.nodes.find(n => n.id === cur);
+            if (curNode && curNode.nodeClass === 'strand-foreach') {
+              hasEnclosingForeach = true;
+              break;
+            }
+            for (const up of built.edges) {
+              if (up.target === cur) stack.push(up.source);
+            }
+          }
+        }
+        let synthLabel;
+        let synthTitle;
+        let synthFullUrn;
+        if (!hasEnclosingForeach) {
+          // Standalone Collect.
+          synthLabel = 'collect';
+          synthTitle = 'collect';
+          synthFullUrn = '';
+        } else if (bodyExitCapEdge && bodyExitCapEdge.singleCapClosedBody) {
+          // Single-cap closed body. The cap's own entry edge is
+          // relabeled with (n→n) in step 2; the exit side is just
+          // a connector with no duplicate label.
+          synthLabel = '';
+          synthTitle = '';
+          synthFullUrn = '';
+        } else {
+          // Multi-cap closed body. The body_exit cap's own
+          // incoming edge stays unmodified (carrying just the
+          // cap title, no cardinality markers). The synthesized
+          // exit edge carries the (n→1) collect marker.
+          const title = bodyExitCapEdge ? bodyExitCapEdge.title : '';
+          synthLabel = `${title} (${collectCardinality})`;
+          synthTitle = title;
+          synthFullUrn = bodyExitCapEdge ? bodyExitCapEdge.fullUrn : '';
+        }
+        synthesizedExitEdges.push({
+          id: `${node.id}-collapsed-exit-${synthesizedExitEdges.length}`,
+          source: bodyExitNodeId,
+          target: outEdge.target,
+          label: synthLabel,
+          title: synthTitle,
+          fullUrn: synthFullUrn,
+          edgeClass: 'strand-cap-edge',
+          color: bodyExitCapEdge ? bodyExitCapEdge.color : inEdge.color,
+          foreachEntry: false,
+          singleCapClosedBody: false,
+        });
+      }
     }
   }
 
-  // Edge case: if there are no Cap steps at all, still connect source
-  // to target directly so the graph has at least one edge. This handles
-  // degenerate strands (e.g. identity).
-  if (firstCapIdx === -1 && sourceSpec !== targetSpec) {
-    edges.push({
-      id: `strand-edge-${capEdgeIdx}`,
-      source: sourceSpec,
-      target: targetSpec,
-      title: '',
-      label: '',
-      cardinality: '',
-      capUrn: '',
-      color: edgeHueColor(capEdgeIdx),
-    });
+  // 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: relabel flagged foreach-entry cap edges with the
+  // cap title + cardinality marker.
+  //
+  // When the body is a single cap (bodyEntry === bodyExit under a
+  // closed Collect), the cap edge has `singleCapClosedBody: true`
+  // and we use (n→n) — the outer sequence is iterated, the cap
+  // runs per-item, and the result is collected back into a
+  // sequence. Otherwise we use plain (1→n) for the foreach entry.
+  const iterAndCollectCardinality = cardinalityLabel(true, true); // "n→n"
+  edges = edges.map(e => {
+    if (e.edgeClass !== 'strand-cap-edge') return e;
+    if (e.foreachEntry && e.singleCapClosedBody) {
+      return Object.assign({}, e, {
+        label: `${e.title} (${iterAndCollectCardinality})`,
+      });
+    }
+    if (e.foreachEntry) {
+      return Object.assign({}, e, {
+        label: `${e.title} (${foreachCardinality})`,
+      });
+    }
+    return e;
+  });
+
+  // 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: Array.from(nodesMap.values()),
-    edges,
-    sourceSpec,
-    targetSpec,
-  };
+  return { nodes, edges };
 }
 
-function strandCytoscapeElements(built) {
-  const nodeElements = built.nodes.map(node => ({
+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,
       label: node.label,
       fullUrn: node.fullUrn,
     },
-    classes: node.id === built.sourceSpec ? 'strand-source'
-           : node.id === built.targetSpec ? 'strand-target'
-           : '',
+    classes: node.nodeClass || '',
   }));
-  const edgeElements = built.edges.map(edge => ({
+  const edgeElements = source.edges.map(edge => ({
     group: 'edges',
     data: {
       id: edge.id,
@@ -845,10 +1227,10 @@ function strandCytoscapeElements(built) {
       target: edge.target,
       label: edge.label,
       title: edge.title,
-      cardinality: edge.cardinality,
-      fullUrn: edge.capUrn,
+      fullUrn: edge.fullUrn,
       color: edge.color,
     },
+    classes: edge.edgeClass || '',
   }));
   return nodeElements.concat(edgeElements);
 }
@@ -870,20 +1252,98 @@ function findCapStepIndexByUrn(steps, targetUrnString) {
   return -1;
 }
 
+// Remove body-interior cap nodes (caps strictly AFTER the first
+// body cap) from a COLLAPSED strand backbone so that per-body
+// replicas are the only visible path through the foreach body.
+// The FIRST body cap node is retained — its incoming foreachEntry
+// edge is the backbone "fallback connector" that keeps the graph
+// connected when zero bodies succeed.
+//
+// Dropping interior body caps also drops their outgoing edges,
+// including any synthesized collect-exit edge that would have
+// connected the last body cap to the post-collect target. To
+// preserve connectivity, the function replaces those with a
+// plain bridging edge from the first body cap directly to the
+// post-collect target.
+function stripRunBackboneBodyInterior(built, steps, foreachStepIdx, collectStepIdx) {
+  if (foreachStepIdx < 0) return built;
+  const bodyEnd = collectStepIdx >= 0 ? collectStepIdx : steps.length;
+
+  const interiorStepIdxs = [];
+  for (let i = foreachStepIdx + 1; i < bodyEnd; i++) {
+    if (Object.keys(steps[i].step_type)[0] === 'Cap') {
+      interiorStepIdxs.push(i);
+    }
+  }
+  if (interiorStepIdxs.length <= 1) {
+    // Zero or one body cap — no prototype chain to strip.
+    return built;
+  }
+
+  const firstBodyStepId = `step_${interiorStepIdxs[0]}`;
+  const lastBodyStepId = `step_${interiorStepIdxs[interiorStepIdxs.length - 1]}`;
+  const dropInteriorIds = new Set();
+  for (let i = 1; i < interiorStepIdxs.length; i++) {
+    dropInteriorIds.add(`step_${interiorStepIdxs[i]}`);
+  }
+
+  // Find the post-body target: the node that the last body cap's
+  // outgoing edge points at in the collapsed backbone. This is
+  // usually `output` or (after the collect-exit synth) the merged
+  // target node.
+  const postBodyEdge = built.edges.find(e => e.source === lastBodyStepId);
+  const postBodyTarget = postBodyEdge ? postBodyEdge.target : null;
+
+  const keptNodes = built.nodes.filter(n => !dropInteriorIds.has(n.id));
+  let keptEdges = built.edges.filter(e =>
+    !dropInteriorIds.has(e.source) && !dropInteriorIds.has(e.target));
+
+  // Bridge firstBody → postBodyTarget directly with a plain
+  // unlabeled connector so the graph stays connected. Replicas
+  // will overlay labeled chains alongside this connector.
+  if (postBodyTarget && postBodyTarget !== firstBodyStepId) {
+    const bridgeExists = keptEdges.some(e =>
+      e.source === firstBodyStepId && e.target === postBodyTarget);
+    if (!bridgeExists) {
+      keptEdges = keptEdges.concat([{
+        id: `run-bridge-${firstBodyStepId}-${postBodyTarget}`,
+        source: firstBodyStepId,
+        target: postBodyTarget,
+        label: '',
+        title: '',
+        fullUrn: '',
+        edgeClass: 'strand-cap-edge',
+        color: postBodyEdge ? postBodyEdge.color : edgeHueColor(0),
+        foreachEntry: false,
+        singleCapClosedBody: false,
+      }]);
+    }
+  }
+
+  return {
+    nodes: keptNodes,
+    edges: keptEdges,
+    sourceSpec: built.sourceSpec,
+    targetSpec: built.targetSpec,
+  };
+}
+
 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 cosmetic
+  // collapse — run mode uses the SAME cleaned-up backbone that
+  // strand mode uses (no ForEach/Collect nodes). Replicas are an
+  // additional overlay on top of that collapsed backbone.
   const strandInput = Object.assign({}, data.resolved_strand, {
     media_display_names: data.media_display_names,
   });
-  const strandBuilt = buildStrandGraphData(strandInput);
+  const strandBuiltRaw = buildStrandGraphData(strandInput);
+  const strandBuiltCollapsed = collapseStrandShapeTransitions(strandBuiltRaw);
 
-  // Locate the ForEach/Collect span in the backbone for body-replica
-  // placement. We anchor body replicas to the first Cap step after a
-  // ForEach (the fan-out point) and merge back at the first Collect.
+  // 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 are the body caps.
   const steps = data.resolved_strand.steps;
   let foreachStepIdx = -1;
   let collectStepIdx = -1;
@@ -894,6 +1354,15 @@ function buildRunGraphData(data) {
   }
   const hasForeach = foreachStepIdx >= 0;
 
+  // Drop interior body-cap nodes (caps 2..N inside the body) from
+  // the collapsed backbone so the prototype chain doesn't duplicate
+  // the per-body replicas visually. The FIRST body cap is retained
+  // as the body-entry node so the backbone's foreachEntry edge
+  // (`<cap_title> (1→n)`) still has a landing point.
+  let strandBuilt = hasForeach
+    ? stripRunBackboneBodyInterior(strandBuiltCollapsed, steps, foreachStepIdx, collectStepIdx)
+    : strandBuiltCollapsed;
+
   // Filter and bound the outcomes.
   const allOutcomes = data.body_outcomes.slice().sort((a, b) => a.body_index - b.body_index);
   const successes = allOutcomes.filter(o => o.success);
@@ -903,10 +1372,8 @@ function buildRunGraphData(data) {
   const hiddenSuccessCount = successes.length - visibleSuccess.length;
   const hiddenFailureCount = failures.length - visibleFailure.length;
 
-  // Map each displayed body to its per-body chain. The chain starts at
-  // the first Cap step's from_spec (the node immediately after the
-  // ForEach) and extends through either all body caps (success) or up to
-  // the failed_cap (failure).
+  // Collect the Cap steps inside the ForEach body. Each body replica
+  // chains through these caps.
   const bodyCapSteps = [];
   const bodyStart = hasForeach ? foreachStepIdx + 1 : 0;
   const bodyEnd = collectStepIdx >= 0 ? collectStepIdx : steps.length;
@@ -916,19 +1383,94 @@ function buildRunGraphData(data) {
     }
   }
 
-  // Replica node/edge ids are prefixed to avoid collision with backbone
-  // ids.
+  // Body replicas fan out from the node BEFORE the foreach (which,
+  // in the collapsed backbone, is the source of the foreachEntry
+  // edge). For a foreach at step index k, the pre-foreach node is
+  // `step_${k-1}` when k > 0, or `input_slot` when k == 0. This
+  // node survives the collapse as a regular `strand-cap` or
+  // `strand-source` node.
+  //
+  // Replicas merge back at the node AFTER the body. After collapse,
+  // this is the FIRST body cap node (`step_${bodyCapSteps[0]}`)
+  // when the ForEach has a single-cap body, or the post-collect
+  // node for multi-cap bodies. The post-collect node is whatever
+  // the plan builder's Collect step connected to downstream, which
+  // after collapse is either the next cap (`step_${collectStepIdx+1}`)
+  // or the target/output node (possibly merged into the last body
+  // cap if their URNs are equivalent).
+  const anchorNodeId = hasForeach && foreachStepIdx > 0
+    ? `step_${foreachStepIdx - 1}`
+    : 'input_slot';
+
+  // Find the merge node by scanning the collapsed backbone for the
+  // node the body reaches after the foreach body. Start from the
+  // first body cap node and follow forward edges until we leave
+  // the body. For a single-body-cap strand where the body cap IS
+  // the merged target, `mergeNodeId` resolves to that node.
+  let mergeNodeId;
+  {
+    // Find body cap step indices in the resolved strand so we can
+    // identify which step IDs are "inside body" (should be skipped
+    // when finding the merge target).
+    const bodyInteriorSet = new Set();
+    const bodyEnd = collectStepIdx >= 0 ? collectStepIdx : steps.length;
+    for (let i = foreachStepIdx + 1; i < bodyEnd; i++) {
+      if (Object.keys(steps[i].step_type)[0] === 'Cap') {
+        bodyInteriorSet.add(`step_${i}`);
+      }
+    }
+    // Start from the first body cap and walk forward.
+    const firstBodyCapIdx = (() => {
+      for (let i = foreachStepIdx + 1; i < bodyEnd; i++) {
+        if (Object.keys(steps[i].step_type)[0] === 'Cap') return i;
+      }
+      return -1;
+    })();
+    if (firstBodyCapIdx < 0) {
+      mergeNodeId = 'output';
+    } else {
+      // Walk the collapsed strand's edges starting from the first
+      // body cap node; the merge target is the first node reached
+      // that isn't inside the body.
+      let cursor = `step_${firstBodyCapIdx}`;
+      let guard = 64;
+      const collapsedNodeIds = new Set(strandBuilt.nodes.map(n => n.id));
+      while (guard-- > 0) {
+        // If the cursor is itself outside the body, we've found it.
+        if (!bodyInteriorSet.has(cursor) && collapsedNodeIds.has(cursor)) {
+          mergeNodeId = cursor;
+          break;
+        }
+        // Otherwise follow the cursor's outgoing edge.
+        const out = strandBuilt.edges.find(e => e.source === cursor);
+        if (!out) {
+          // Nothing to follow — the body cap IS the end of the
+          // strand. Use the cursor as the merge point (it's
+          // typically the merged target node).
+          mergeNodeId = cursor;
+          break;
+        }
+        cursor = out.target;
+      }
+      if (mergeNodeId === undefined) {
+        // Guard exhausted — fall back to output. This is impossible
+        // for any well-formed strand but keeps the runtime safe.
+        mergeNodeId = 'output';
+      }
+    }
+  }
+
   const replicaNodes = [];
   const replicaEdges = [];
 
-  function buildBodyReplica(outcome, groupIndex) {
+  function buildBodyReplica(outcome) {
     const success = outcome.success;
     const successClass = success ? 'body-success' : 'body-failure';
     const edgeClass = success ? 'body-success' : 'body-failure';
     const colorVar = success ? '--graph-body-edge-success' : '--graph-body-edge-failure';
 
-    // Find the trace end (failed_cap stops the trace for failed
-    // bodies). Comparison uses 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) {
       const CapUrn = requireHostDependency('CapUrn');
@@ -941,12 +1483,9 @@ function buildRunGraphData(data) {
         }
       }
     }
-    if (traceEnd === 0) return; // Nothing to render for this body.
+    if (traceEnd === 0) return;
 
-    // Anchor to the first body cap's from_spec, which equals the
-    // ForEach's from_spec (fan-out from the same source node).
-    const anchorCanonical = canonicalMediaUrn(bodyCapSteps[0].step.from_spec);
-    let prevBodyNodeId = anchorCanonical;
+    let prevBodyNodeId = anchorNodeId;
     const bodyKey = `body-${outcome.body_index}`;
     const titleLabel = typeof outcome.title === 'string' && outcome.title.length > 0
       ? outcome.title
@@ -973,6 +1512,11 @@ function buildRunGraphData(data) {
           id: `${bodyKey}-e-${i}`,
           source: prevBodyNodeId,
           target: replicaNodeId,
+          // Replica edges carry no inline label — the cap title is
+          // identical across every visible replica and would just
+          // pile up as unreadable rotated text over the fan-out.
+          // Hover tooltip exposes the title via `title`; the edge
+          // color + the replica node identify the body.
           label: '',
           title: body.title,
           fullUrn: body.cap_urn,
@@ -984,16 +1528,17 @@ function buildRunGraphData(data) {
       prevBodyNodeId = replicaNodeId;
     }
 
-    // If the collect exists and the body succeeded, attach the replica
-    // tail to the collect's to_spec node so the graph visibly fans in.
-    if (success && collectStepIdx >= 0) {
-      const collectTo = canonicalMediaUrn(steps[collectStepIdx].to_spec);
+    // 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) {
       replicaEdges.push({
         group: 'edges',
         data: {
           id: `${bodyKey}-merge`,
           source: prevBodyNodeId,
-          target: collectTo,
+          target: mergeNodeId,
           label: '',
           title: 'collect',
           fullUrn: '',
@@ -1005,14 +1550,51 @@ function buildRunGraphData(data) {
     }
   }
 
-  visibleSuccess.forEach((o, i) => buildBodyReplica(o, i));
-  visibleFailure.forEach((o, i) => buildBodyReplica(o, i));
+  visibleSuccess.forEach((o) => buildBodyReplica(o));
+  visibleFailure.forEach((o) => buildBodyReplica(o));
+
+  // Once any replicas are rendered (success or failure), the
+  // backbone foreach-entry edge becomes a stale placeholder — the
+  // replicas ARE the actual execution traces, so the user
+  // shouldn't see a duplicate labeled "1→n" edge alongside them.
+  // Drop the backbone foreach-entry edge whenever we emit
+  // replicas, AND if there were zero successful replicas also
+  // drop the orphaned merge node: nothing reached it, and
+  // showing a disconnected node misleads the user into thinking
+  // the target was reached.
+  if (hasForeach && (visibleSuccess.length > 0 || visibleFailure.length > 0)) {
+    const backboneForeachEntry = strandBuilt.edges.find(e =>
+      e.edgeClass === 'strand-cap-edge' &&
+      e.source === anchorNodeId &&
+      e.foreachEntry === true);
+    let newEdges = strandBuilt.edges;
+    let newNodes = strandBuilt.nodes;
+    if (backboneForeachEntry) {
+      newEdges = newEdges.filter(e => e.id !== backboneForeachEntry.id);
+    }
+    // If no successful replica will merge into `mergeNodeId`, and
+    // the merge node is now only reachable via the (just-dropped)
+    // backbone edge, drop the merge node itself.
+    if (visibleSuccess.length === 0 && mergeNodeId) {
+      const stillIncoming = newEdges.some(e => e.target === mergeNodeId);
+      const replicaIncoming = replicaEdges.some(e => e.data && e.data.target === mergeNodeId);
+      if (!stillIncoming && !replicaIncoming) {
+        newNodes = newNodes.filter(n => n.id !== mergeNodeId);
+        newEdges = newEdges.filter(e => e.source !== mergeNodeId && e.target !== mergeNodeId);
+      }
+    }
+    strandBuilt = {
+      nodes: newNodes,
+      edges: newEdges,
+      sourceSpec: strandBuilt.sourceSpec,
+      targetSpec: strandBuilt.targetSpec,
+    };
+  }
 
   // Build success and failure "show more" nodes when there are hidden
-  // outcomes. Anchored at the same ForEach fan-out source.
+  // outcomes. Anchored at the ForEach node (or input_slot if none).
   const showMoreNodes = [];
   if (hasForeach && bodyCapSteps.length > 0) {
-    const anchorCanonical = canonicalMediaUrn(bodyCapSteps[0].step.from_spec);
     if (hiddenSuccessCount > 0) {
       const nodeId = 'show-more-success';
       showMoreNodes.push({
@@ -1030,7 +1612,7 @@ function buildRunGraphData(data) {
         group: 'edges',
         data: {
           id: 'show-more-success-edge',
-          source: anchorCanonical,
+          source: anchorNodeId,
           target: nodeId,
           label: '',
           title: '',
@@ -1057,7 +1639,7 @@ function buildRunGraphData(data) {
         group: 'edges',
         data: {
           id: 'show-more-failure-edge',
-          source: anchorCanonical,
+          source: anchorNodeId,
           target: nodeId,
           label: '',
           title: '',
@@ -1085,7 +1667,10 @@ function buildRunGraphData(data) {
 }
 
 function runCytoscapeElements(built) {
-  const strandElements = strandCytoscapeElements(built.strandBuilt);
+  // Do NOT collapse ForEach/Collect nodes in run mode — body replicas
+  // anchor at the ForEach node (fan-out) and merge at the Collect
+  // node (fan-in). Those junctions must stay visible.
+  const strandElements = strandCytoscapeElements(built.strandBuilt, { collapse: false });
   return strandElements
     .concat(built.replicaNodes)
     .concat(built.showMoreNodes)
@@ -1988,6 +2573,7 @@ if (typeof module !== 'undefined' && module.exports) {
     mediaNodeLabel,
     buildBrowseGraphData,
     buildStrandGraphData,
+    collapseStrandShapeTransitions,
     buildRunGraphData,
     buildMachineGraphData,
     classifyStrandCapSteps,