@prisma-next/cli 0.12.0-dev.75 → 0.12.0-dev.77

package/src/utils/formatters/migration-graph-grid-layout.ts

@@ -7,16 +7,17 @@
  */
 
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
-import type {
-  Cell,
-  CellLine,
-  Direction,
-  Grid,
-  GridOptions,
-  Highlight,
-  LineRef,
-  NodeRef,
-  PathRole,
+import {
+  type Cell,
+  type CellLine,
+  DEFAULT_COLS_PER_LANE,
+  type Direction,
+  type Grid,
+  type GridOptions,
+  type Highlight,
+  type LineRef,
+  type NodeRef,
+  type PathRole,
 } from './migration-graph-model';
 import type { ClassifiedEdge, MigrationGraphRowModel } from './migration-graph-rows';
 
@@ -27,6 +28,14 @@ import type { ClassifiedEdge, MigrationGraphRowModel } from './migration-graph-r
 interface LaneAssignment {
   nodeLane: Map<string, number>;
   nodeRank: Map<string, number>;
+  /**
+   * Per-edge lane override. Set for "direct fork-to-merge" branch edges whose
+   * endpoints both land on lane 0 after merge reconciliation, but whose BFS
+   * traversal allocated them a non-zero branch lane. Using this override lets
+   * the branch edge render in its branch column even when the merge tip was
+   * pulled back to the trunk lane.
+   */
+  edgeLane: Map<string, number>;
   /** Total number of lanes allocated. */
   numLanes: number;
 }
@@ -35,15 +44,10 @@ function buildLaneAssignment(
   nodes: readonly (string | null)[],
   edges: readonly ClassifiedEdge[],
 ): LaneAssignment {
-  const allNodes = new Set<string>();
-  for (const n of nodes) {
-    if (n !== null) allNodes.add(n);
-  }
-
   // Separate forward (non-self) edges
   const fwdEdges = edges.filter((e) => e.kind === 'forward' && e.from !== e.to);
 
-  // Build adjacency: outbound forward edges per node, sorted lex by migrationHash
+  // Build outbound/inbound adjacency sorted by dirName
   const outbound = new Map<string, ClassifiedEdge[]>();
   const inbound = new Map<string, ClassifiedEdge[]>();
   for (const edge of fwdEdges) {
@@ -58,14 +62,32 @@ function buildLaneAssignment(
   for (const list of outbound.values()) list.sort((a, b) => a.dirName.localeCompare(b.dirName));
   for (const list of inbound.values()) list.sort((a, b) => a.dirName.localeCompare(b.dirName));
 
-  // Compute longest-forward-path rank from roots (tips get highest rank)
+  // Split nodes into per-component groups (null sentinels separate components)
+  const components: string[][] = [];
+  let current: string[] = [];
+  for (const n of nodes) {
+    if (n === null) {
+      if (current.length > 0) components.push(current);
+      current = [];
+    } else {
+      current.push(n);
+    }
+  }
+  if (current.length > 0) components.push(current);
+
+  // Global rank map (longest-forward-path; computed across all nodes together
+  // so rollback edges crossing components don't interfere with rank within each)
+  const allNodes = new Set<string>();
+  for (const n of nodes) {
+    if (n !== null) allNodes.add(n);
+  }
   const nodeRank = new Map<string, number>();
   for (const n of allNodes) nodeRank.set(n, 0);
   for (let pass = 0; pass < allNodes.size; pass++) {
     let changed = false;
-    for (const [from, edges] of outbound) {
+    for (const [from, es] of outbound) {
       const base = nodeRank.get(from) ?? 0;
-      for (const e of edges) {
+      for (const e of es) {
         const next = base + 1;
         if (next > (nodeRank.get(e.to) ?? 0)) {
           nodeRank.set(e.to, next);
@@ -76,53 +98,139 @@ function buildLaneAssignment(
     if (!changed) break;
   }
 
-  // Lane assignment: BFS from roots, trunk keeps parent's lane
+  // Lane assignment: BFS per component, resetting nextLane to 0 for each.
+  // Each component's roots start at lane 0, so disconnected components never
+  // interleave lanes.
   const nodeLane = new Map<string, number>();
-  let nextLane = 0;
+  // Per-edge lane: records the BFS-allocated branch lane for each edge. Used
+  // to preserve branch-column rendering even after merge-tip reconciliation.
+  const edgeLane = new Map<string, number>();
+  let totalLanes = 0;
+
+  for (const componentNodes of components) {
+    const componentSet = new Set(componentNodes);
+    let nextLane = 0;
+
+    const roots: string[] = [];
+    for (const n of componentNodes) {
+      if ((inbound.get(n) ?? []).length === 0) roots.push(n);
+    }
+    roots.sort((a, b) => {
+      if (a === EMPTY_CONTRACT_HASH) return -1;
+      if (b === EMPTY_CONTRACT_HASH) return 1;
+      return a.localeCompare(b);
+    });
 
-  // Roots: nodes with no inbound forward edges
-  const roots: string[] = [];
-  for (const n of allNodes) {
-    if ((inbound.get(n) ?? []).length === 0) roots.push(n);
-  }
-  roots.sort((a, b) => {
-    if (a === EMPTY_CONTRACT_HASH) return -1;
-    if (b === EMPTY_CONTRACT_HASH) return 1;
-    return a.localeCompare(b);
-  });
+    const bfsQueue: Array<{ node: string; lane: number }> = [];
+    for (const root of roots) {
+      if (!nodeLane.has(root)) {
+        nodeLane.set(root, nextLane++);
+        bfsQueue.push({ node: root, lane: nodeLane.get(root)! });
+      }
+    }
 
-  const bfsQueue: Array<{ node: string; lane: number }> = [];
-  for (const root of roots) {
-    if (!nodeLane.has(root)) {
-      nodeLane.set(root, nextLane++);
-      bfsQueue.push({ node: root, lane: nodeLane.get(root)! });
-    }
-  }
-
-  // BFS expansion
-  let head = 0;
-  while (head < bfsQueue.length) {
-    const item = bfsQueue[head++]!;
-    const { node, lane } = item;
-    const children = outbound.get(node) ?? [];
-    let first = true;
-    for (const childEdge of children) {
-      const child = childEdge.to;
-      if (!nodeLane.has(child)) {
-        const childLane = first ? lane : nextLane++;
-        nodeLane.set(child, childLane);
-        bfsQueue.push({ node: child, lane: childLane });
+    let head = 0;
+    while (head < bfsQueue.length) {
+      const item = bfsQueue[head++]!;
+      const { node, lane } = item;
+      const children = outbound.get(node) ?? [];
+      let first = true;
+      for (const childEdge of children) {
+        const child = childEdge.to;
+        if (!componentSet.has(child)) continue;
+        if (!nodeLane.has(child)) {
+          const childLane = first ? lane : nextLane++;
+          nodeLane.set(child, childLane);
+          bfsQueue.push({ node: child, lane: childLane });
+          edgeLane.set(childEdge.migrationHash, childLane);
+        } else {
+          // Child already assigned — record this edge's lane as the max of the
+          // parent's lane and the child's current lane (same as the original
+          // Math.max formula). May be updated by reconciliation below for trunk
+          // edges into reconciled merge nodes.
+          edgeLane.set(childEdge.migrationHash, Math.max(lane, nodeLane.get(child)!));
+        }
+        first = false;
+      }
+    }
+
+    // Isolated nodes within the component
+    for (const n of componentNodes) {
+      if (!nodeLane.has(n)) nodeLane.set(n, nextLane++);
+    }
+
+    // Merge-node lane reconciliation: a node with multiple inbound forward edges
+    // should sit on the lane of its highest-rank parent (furthest along the
+    // longest path). When a short arm and a long arm converge, the merge node
+    // follows the long arm's lane.
+    //
+    // When a merge node's lane changes, update the edgeLane for all edges
+    // pointing TO that node so they reflect the reconciled column. Edges from
+    // nodes that were on a BRANCH (non-trunk) lane keep their original branch
+    // lane so the branch column renders correctly.
+    for (const n of componentNodes) {
+      const parents = inbound.get(n);
+      if (!parents || parents.length <= 1) continue;
+      let trunkParent = parents[0]!.from;
+      let trunkRank = nodeRank.get(trunkParent) ?? 0;
+      let trunkLane = nodeLane.get(trunkParent) ?? 0;
+      for (let i = 1; i < parents.length; i++) {
+        const parent = parents[i]!.from;
+        const rank = nodeRank.get(parent) ?? 0;
+        const lane = nodeLane.get(parent) ?? 0;
+        if (rank > trunkRank || (rank === trunkRank && lane < trunkLane)) {
+          trunkParent = parent;
+          trunkRank = rank;
+          trunkLane = lane;
+        }
+      }
+      const trunkParentLane = nodeLane.get(trunkParent) ?? 0;
+      const currentNodeLane = nodeLane.get(n) ?? 0;
+      if (currentNodeLane === trunkParentLane) continue;
+
+      nodeLane.set(n, trunkParentLane);
+
+      // Update edgeLane for each inbound edge:
+      // - Trunk edge (from the highest-rank parent): use the trunk lane
+      // - Branch edges: keep the ORIGINAL edgeLane (the branch column), so
+      //   the branch edge still renders in its allocated branch column.
+      for (const parentEdge of parents) {
+        const isFromTrunkParent = parentEdge.from === trunkParent;
+        if (isFromTrunkParent) {
+          edgeLane.set(parentEdge.migrationHash, trunkParentLane);
+        }
+        // Branch edges keep whatever lane they were assigned during BFS.
+      }
+
+      // Propagate the lane change to forward descendants that inherited the
+      // old lane. BFS from this merge node through outbound edges: any
+      // descendant still on oldLane moves to the new (trunk) lane. Stop the
+      // traversal at nodes that are already on a different lane — they belong
+      // to branches that forked independently and must not move.
+      const bfsDescendants: string[] = [n];
+      let descHead = 0;
+      while (descHead < bfsDescendants.length) {
+        const current = bfsDescendants[descHead++]!;
+        const children = outbound.get(current) ?? [];
+        for (const childEdge of children) {
+          const child = childEdge.to;
+          if (!componentSet.has(child)) continue;
+          if ((nodeLane.get(child) ?? 0) !== currentNodeLane) continue;
+          nodeLane.set(child, trunkParentLane);
+          // Update the edge lane for the edge from current→child
+          const existingEdgeLane = edgeLane.get(childEdge.migrationHash);
+          if (existingEdgeLane !== undefined && existingEdgeLane === currentNodeLane) {
+            edgeLane.set(childEdge.migrationHash, trunkParentLane);
+          }
+          bfsDescendants.push(child);
+        }
       }
-      first = false;
     }
-  }
 
-  // Isolated nodes (no edges) get their own lane
-  for (const n of allNodes) {
-    if (!nodeLane.has(n)) nodeLane.set(n, nextLane++);
+    if (nextLane > totalLanes) totalLanes = nextLane;
   }
 
-  return { nodeLane, nodeRank, numLanes: nextLane };
+  return { nodeLane, nodeRank, edgeLane, numLanes: totalLanes };
 }
 
 // ---------------------------------------------------------------------------
@@ -135,20 +243,42 @@ interface NodeDisplay {
   rank: number;
 }
 
+/**
+ * A `null` sentinel in the display order marks a component boundary.
+ * The grid builder emits a separator row at each boundary.
+ */
+type NodeDisplayOrSeparator = NodeDisplay | null;
+
 function computeDisplayOrder(
   nodes: readonly (string | null)[],
   nodeLane: Map<string, number>,
   nodeRank: Map<string, number>,
-): NodeDisplay[] {
+): NodeDisplayOrSeparator[] {
   const seen = new Set<string>();
-  const result: NodeDisplay[] = [];
+  const result: NodeDisplayOrSeparator[] = [];
+
+  // Collect each component's nodes then sort within it (rank desc, lane asc).
+  // null sentinels mark component boundaries; they become separator entries.
+  let componentBuffer: NodeDisplay[] = [];
+
+  function flushComponent(): void {
+    componentBuffer.sort((a, b) => b.rank - a.rank || a.lane - b.lane);
+    for (const d of componentBuffer) result.push(d);
+    componentBuffer = [];
+  }
+
   for (const n of nodes) {
-    if (n === null || seen.has(n)) continue;
+    if (n === null) {
+      flushComponent();
+      result.push(null);
+      continue;
+    }
+    if (seen.has(n)) continue;
     seen.add(n);
-    result.push({ hash: n, lane: nodeLane.get(n) ?? 0, rank: nodeRank.get(n) ?? 0 });
+    componentBuffer.push({ hash: n, lane: nodeLane.get(n) ?? 0, rank: nodeRank.get(n) ?? 0 });
   }
-  // Tips first (rank desc), within same rank lane asc
-  result.sort((a, b) => b.rank - a.rank || a.lane - b.lane);
+  flushComponent();
+
   return result;
 }
 
@@ -172,18 +302,24 @@ export function buildGrid(
   opts: GridOptions = {},
   highlight: Highlight = { mode: 'flat', onPath: new Set() },
 ): Grid {
-  const colsPerLane = opts.colsPerLane ?? 2;
+  const colsPerLane = opts.colsPerLane ?? DEFAULT_COLS_PER_LANE;
   const isFocus = highlight.mode === 'focus';
 
-  const { nodeLane, nodeRank, numLanes } = buildLaneAssignment(rowModel.nodes, rowModel.edges);
+  const { nodeLane, nodeRank, edgeLane, numLanes } = buildLaneAssignment(
+    rowModel.nodes,
+    rowModel.edges,
+  );
 
   const displayOrder = computeDisplayOrder(rowModel.nodes, nodeLane, nodeRank);
 
-  // Display index per node (0 = topmost row).
+  // Display index per node (0 = topmost position; nulls skipped).
   const displayIndex = new Map<string, number>();
-  displayOrder.forEach((d, i) => {
-    displayIndex.set(d.hash, i);
-  });
+  let nodeIdx = 0;
+  for (const d of displayOrder) {
+    if (d !== null) {
+      displayIndex.set(d.hash, nodeIdx++);
+    }
+  }
 
   // ── Back-arc planning ────────────────────────────────────────────────────
   // Each rollback edge runs against the forward grain. An *adjacent* rollback
@@ -192,22 +328,26 @@ export function buildGrid(
   // back-lane to the right: it tees off the source node row (○─╮), runs a
   // vertical │ down its back-lane, and lands into the target node (◂╯).
   //
-  // Two independent numbers per routed back-arc:
+  // Three independent numbers per routed back-arc:
   //   geomLane   — the column its rail occupies. Outermost (largest) goes to the
   //                arc reaching the lowest target (ties: higher source first), so
   //                interleaving spans cross and nested spans nest cleanly.
-  //   colourLane — the lane index used purely for colour. Assigned by
-  //                migrationHash order, continuing after the forward lanes, so the
-  //                first rollback is lane numLanes, the next numLanes+1, etc.
-  // These differ whenever two arcs interleave (rollback-cross): the inner column
-  // may carry the higher colour. Colour is read off LineRef.lane; the column is
-  // where the cell is placed.
+  //   colourLane — the lane index used purely for colour (flat mode). Assigned
+  //                by greedy colouring (bottom-up walk; see below) so that no
+  //                two concurrently-active lanes/arcs share a palette colour,
+  //                and no arc reuses its origin branch's colour or green.
+  //   planeLane  — the z-order index for occlusion within a shared back-lane.
+  //                Arcs sharing the same geomLane are sorted by sourceIndex
+  //                descending: the arc whose source is lowest in display
+  //                (largest sourceIndex = bottom-most visually) draws on top
+  //                (smallest planeLane number). Decoupled from colourLane.
   interface RoutedBackArc {
     readonly edge: ClassifiedEdge;
     readonly sourceIndex: number;
     readonly targetIndex: number;
     readonly geomLane: number;
     readonly colourLane: number;
+    readonly planeLane: number;
   }
 
   const rollbackEdges = rowModel.edges.filter((e) => e.kind === 'rollback' && e.from !== e.to);
@@ -223,37 +363,146 @@ export function buildGrid(
     else skippingRollbacks.push(e);
   }
 
-  // colourLane by migration NAME (dirName) order — chronological, not hash.
-  const colourLaneOf = new Map<string, number>();
-  [...skippingRollbacks]
-    .sort((a, b) => a.dirName.localeCompare(b.dirName))
-    .forEach((e, i) => {
-      colourLaneOf.set(e.migrationHash, numLanes + i);
-    });
-
-  // geomLane: outermost rail to the arc with the lowest target (largest target
-  // index); ties broken by the highest source (smallest source index). The first
-  // in this order gets the outermost (largest) geometric lane.
-  const geomOrder = [...skippingRollbacks].sort((a, b) => {
-    const ta = displayIndex.get(a.to) ?? 0;
-    const tb = displayIndex.get(b.to) ?? 0;
-    if (ta !== tb) return tb - ta; // lower target (larger index) first
-    const sa = displayIndex.get(a.from) ?? 0;
-    const sb = displayIndex.get(b.from) ?? 0;
-    return sa - sb; // higher source (smaller index) first
+  // Convergence: group skipping rollbacks by their target node. Arcs sharing a
+  // target share one geometric lane (rail column). Each distinct target gets its
+  // own rail; arcs within the group compose via occlusion.
+  //
+  // geomLane ordering: outermost rail goes to the group whose target is lowest
+  // in display order (largest target index — deepest in the chain). Within a
+  // group, the group's representative target index drives the ordering.
+  const targetGroups = new Map<string, ClassifiedEdge[]>();
+  for (const e of skippingRollbacks) {
+    const group = targetGroups.get(e.to);
+    if (group) group.push(e);
+    else targetGroups.set(e.to, [e]);
+  }
+  // Sort target-group keys: largest target index (lowest in display) → outermost lane.
+  const sortedTargetKeys = [...targetGroups.keys()].sort((a, b) => {
+    const ta = displayIndex.get(a) ?? 0;
+    const tb = displayIndex.get(b) ?? 0;
+    return tb - ta; // largest index first = outermost
   });
+  const numTargetGroups = sortedTargetKeys.length;
   const geomLaneOf = new Map<string, number>();
-  const outermost = numLanes + skippingRollbacks.length - 1;
-  geomOrder.forEach((e, i) => {
-    geomLaneOf.set(e.migrationHash, outermost - i);
+  const outermostGroup = numLanes + numTargetGroups - 1;
+  sortedTargetKeys.forEach((targetHash, i) => {
+    const groupGeomLane = outermostGroup - i;
+    for (const e of targetGroups.get(targetHash)!) {
+      geomLaneOf.set(e.migrationHash, groupGeomLane);
+    }
   });
 
+  // ── planeLane: z-order for back-arcs ────────────────────────────────────
+  // The arc whose source is furthest down the display (largest sourceIndex)
+  // draws on top (lowest planeLane). This applies both within shared back-lanes
+  // and at crossing points where arcs on different geomLanes overlap.
+  // planeLane = totalNodes - sourceIndex gives: larger sourceIndex → smaller value.
+  const totalDisplayNodes = displayOrder.filter((d) => d !== null).length;
+  const planeLaneOf = new Map<string, number>();
+  for (const e of skippingRollbacks) {
+    const si = displayIndex.get(e.from) ?? 0;
+    planeLaneOf.set(e.migrationHash, totalDisplayNodes - si);
+  }
+
+  // ── colourLane: greedy assignment (flat mode) ─────────────────────────────
+  // Walk displayOrder bottom → top. Maintain the set of concurrently-active
+  // palette-colour indices (forward lanes + active back-arc assignments). When
+  // a new arc first becomes visible (at its target node, going upward), pick the
+  // lowest palette index not in use. Additionally exclude:
+  //   - the arc's origin lane's colour (nodeLane.get(from) % PALETTE_SIZE)
+  //   - index 5 (green — reserved for focus on-path)
+  // When the arc's source node is processed, release its colour.
+  //
+  // Forward lanes hold colour = laneIndex % PALETTE_SIZE (unchanged); back-arc
+  // colourLane is set to the chosen palette index directly (0–5), so that
+  // `colourLane % 6 == chosenIndex`.
+  const PALETTE_SIZE = 6;
+  const GREEN_PALETTE_IDX = 5;
+
+  // Precompute per-arc display indices for the walk.
+  const arcSourceIndex = new Map<string, number>();
+  const arcTargetIndex = new Map<string, number>();
+  for (const e of skippingRollbacks) {
+    arcSourceIndex.set(e.migrationHash, displayIndex.get(e.from) ?? 0);
+    arcTargetIndex.set(e.migrationHash, displayIndex.get(e.to) ?? 0);
+  }
+
+  // Build lookup: arcs by target node hash and source node hash.
+  const arcsByTarget = new Map<string, ClassifiedEdge[]>();
+  const arcsBySource = new Map<string, ClassifiedEdge[]>();
+  for (const e of skippingRollbacks) {
+    const tb = arcsByTarget.get(e.to);
+    if (tb) tb.push(e);
+    else arcsByTarget.set(e.to, [e]);
+    const sb = arcsBySource.get(e.from);
+    if (sb) sb.push(e);
+    else arcsBySource.set(e.from, [e]);
+  }
+
+  // Greedy walk: bottom → top through displayOrder.
+  const colourLaneOf = new Map<string, number>();
+  // activeArcColours: migHash → palette index currently in use by that arc.
+  const activeArcColours = new Map<string, number>();
+  // activeFwdLaneColours: set of palette indices held by currently-active forward lanes.
+  const activeFwdLaneColours = new Set<number>();
+
+  for (let i = displayOrder.length - 1; i >= 0; i--) {
+    const nd = displayOrder[i];
+    if (nd === null || nd === undefined) continue; // separator or missing — skip
+
+    const { hash: nodeHash } = nd;
+    const nodeFwdLane = nodeLane.get(nodeHash) ?? 0;
+
+    // 1. Activate this node's forward lane (if not already active from a lower node).
+    activeFwdLaneColours.add(nodeFwdLane % PALETTE_SIZE);
+
+    // 2. Assign colour to arcs that TARGET this node. They become visible
+    //    starting here, running upward to their source.
+    const incomingArcs = arcsByTarget.get(nodeHash) ?? [];
+    // Process in a stable order (dirName) for determinism.
+    const sortedIncoming = [...incomingArcs].sort((a, b) => a.dirName.localeCompare(b.dirName));
+    for (const arc of sortedIncoming) {
+      const originLaneColour = (nodeLane.get(arc.from) ?? 0) % PALETTE_SIZE;
+      // Colours currently occupied.
+      const occupied = new Set<number>(activeFwdLaneColours);
+      for (const c of activeArcColours.values()) occupied.add(c);
+      occupied.add(GREEN_PALETTE_IDX);
+      occupied.add(originLaneColour);
+      // Pick the lowest free index; if all are taken, pick lowest excluding green.
+      let chosen = -1;
+      for (let ci = 0; ci < PALETTE_SIZE; ci++) {
+        if (!occupied.has(ci)) {
+          chosen = ci;
+          break;
+        }
+      }
+      if (chosen === -1) {
+        // Palette exhausted — forced reuse. Pick lowest excluding green.
+        for (let ci = 0; ci < PALETTE_SIZE; ci++) {
+          if (ci !== GREEN_PALETTE_IDX) {
+            chosen = ci;
+            break;
+          }
+        }
+      }
+      colourLaneOf.set(arc.migrationHash, chosen === -1 ? 0 : chosen);
+      activeArcColours.set(arc.migrationHash, chosen === -1 ? 0 : chosen);
+    }
+
+    // 3. Release arcs that SOURCE at this node. Their rail runs from here
+    //    downward; above this node they're gone.
+    for (const arc of arcsBySource.get(nodeHash) ?? []) {
+      activeArcColours.delete(arc.migrationHash);
+    }
+  }
+
   const routedBackArcs: RoutedBackArc[] = skippingRollbacks.map((e) => ({
     edge: e,
     sourceIndex: displayIndex.get(e.from) ?? 0,
     targetIndex: displayIndex.get(e.to) ?? 0,
     geomLane: geomLaneOf.get(e.migrationHash) ?? numLanes,
-    colourLane: colourLaneOf.get(e.migrationHash) ?? numLanes,
+    colourLane: colourLaneOf.get(e.migrationHash) ?? 0,
+    planeLane: planeLaneOf.get(e.migrationHash) ?? numLanes,
   }));
 
   const backArcsBySource = new Map<string, RoutedBackArc[]>();
@@ -280,7 +529,7 @@ export function buildGrid(
   for (const list of adjacentBySource.values())
     list.sort((a, b) => a.dirName.localeCompare(b.dirName));
 
-  const numBackLanes = skippingRollbacks.length;
+  const numBackLanes = numTargetGroups;
   const totalCols = (numLanes + numBackLanes) * colsPerLane;
 
   // Build edge lookup maps (classified)
@@ -430,8 +679,8 @@ export function buildGrid(
 
   function backArcPlane(arc: RoutedBackArc): number {
     const role = roleOf(arc.edge.migrationHash);
-    if (!isFocus) return arc.colourLane;
-    return role === 'on-path' ? 0 : arc.colourLane + 1;
+    if (!isFocus) return arc.planeLane;
+    return role === 'on-path' ? 0 : arc.planeLane + 1;
   }
 
   // Compose a CellLine into a row cell (never overwrite — occlusion arbitrates).
@@ -638,8 +887,16 @@ export function buildGrid(
     return row;
   }
 
-  // Process each node in display order
+  // Process each node in display order; null = component boundary → separator row
   for (const nodeDisplay of displayOrder) {
+    if (nodeDisplay === null) {
+      // Emit one blank separator row between disconnected components.
+      const sepRow = makeRow();
+      sepRow[0] = { lines: [], separator: true };
+      grid.push(sepRow);
+      continue;
+    }
+
     const { hash: nodeHash } = nodeDisplay;
     const nodeLaneNum = nodeLane.get(nodeHash) ?? 0;
 
@@ -648,10 +905,17 @@ export function buildGrid(
     // ── 1. Fork connector (BEFORE the node row) ──────────────────────────
     const outEdges = outboundFwd.get(nodeHash) ?? [];
     if (outEdges.length > 1) {
-      const trunkChildLane = nodeLane.get(outEdges[0]!.to) ?? nodeLaneNum;
+      // Use the per-edge lane for branch children so that "direct fork-to-merge"
+      // edges (whose target was reconciled back to trunk lane) still appear in
+      // their allocated branch column.
+      const trunkEdgeForFork = outEdges[0]!;
+      const trunkChildLane =
+        edgeLane.get(trunkEdgeForFork.migrationHash) ??
+        nodeLane.get(trunkEdgeForFork.to) ??
+        nodeLaneNum;
       const branchEntries = outEdges
         .slice(1)
-        .map((e) => ({ lane: nodeLane.get(e.to) ?? 0, edge: e }))
+        .map((e) => ({ lane: edgeLane.get(e.migrationHash) ?? nodeLane.get(e.to) ?? 0, edge: e }))
         .filter((b) => b.lane !== trunkChildLane && activeLanes.has(b.lane));
 
       if (branchEntries.length > 0) {
@@ -742,11 +1006,28 @@ export function buildGrid(
     // its lane's current edge NOW (before emitting the back-arc arrow rows, merge
     // connector, and migration rows) so pass-through verticals colour from the
     // forward edge actually occupying the trunk below this node.
+    //
+    // edgeLaneFor: resolve the lane for an inbound forward edge. Uses the
+    // per-edge override from edgeLane (set during BFS for branch edges) when
+    // available; falls back to Max(fromLane, toLane) for edges not in the map.
+    function edgeLaneFor(edge: ClassifiedEdge): number {
+      const override = edgeLane.get(edge.migrationHash);
+      if (override !== undefined) return override;
+      return Math.max(nodeLane.get(edge.from) ?? 0, nodeLane.get(edge.to) ?? 0);
+    }
+
+    // Sort inEdges so the trunk edge (lowest edgeLane = trunk column) comes
+    // first. Ties broken by dirName. This ensures the merge connector treats
+    // the trunk-column edge as the trunk regardless of alphabetical order.
     const inEdges = inboundFwd.get(nodeHash) ?? [];
-    inEdges.sort((a, b) => a.dirName.localeCompare(b.dirName));
+    inEdges.sort((a, b) => {
+      const aLane = edgeLaneFor(a);
+      const bLane = edgeLaneFor(b);
+      if (aLane !== bLane) return aLane - bLane;
+      return a.dirName.localeCompare(b.dirName);
+    });
     for (const edge of inEdges) {
-      const edgeLane = Math.max(nodeLane.get(edge.from) ?? 0, nodeLane.get(edge.to) ?? 0);
-      laneCurrentEdge.set(edgeLane, edge);
+      laneCurrentEdge.set(edgeLaneFor(edge), edge);
     }
 
     // ── 3b. Back-arc arrow rows ──────────────────────────────────────────────
@@ -771,9 +1052,7 @@ export function buildGrid(
 
     // ── 4. Merge connector (AFTER the node row) ────────────────────────────
     if (inEdges.length > 1) {
-      const branchEntries = inEdges
-        .slice(1)
-        .map((e) => ({ lane: nodeLane.get(e.from) ?? 0, edge: e }));
+      const branchEntries = inEdges.slice(1).map((e) => ({ lane: edgeLaneFor(e), edge: e }));
 
       const trunkEdge = inEdges[0];
       const connRow = emitConnectorRow(nodeLaneNum, branchEntries, 'merge', trunkEdge);
@@ -783,20 +1062,18 @@ export function buildGrid(
       for (const b of branchEntries) activeLanes.add(b.lane);
     }
 
-    // ── 5. Migration rows (one per inbound edge, ordered by migration hash) ─
+    // ── 5. Migration rows (one per inbound edge, ordered by edge lane) ─────
     for (const edge of inEdges) {
-      const fromLane = nodeLane.get(edge.from) ?? 0;
-      const toLane = nodeLane.get(edge.to) ?? 0;
-      const edgeLane = Math.max(fromLane, toLane);
+      const eLane = edgeLaneFor(edge);
       const row = makeRow();
-      const railCol = edgeLane * colsPerLane;
-      const connCol = edgeLane * colsPerLane + 1;
-      const line = lineRefFor(edge, edgeLane);
+      const railCol = eLane * colsPerLane;
+      const connCol = eLane * colsPerLane + 1;
+      const line = lineRefFor(edge, eLane);
 
       row[railCol] = vertCell(line);
       row[connCol] = dirCell(line, new Set<Direction>(['up']));
 
-      placeVerticals(row, new Set([edgeLane]));
+      placeVerticals(row, new Set([eLane]));
       placeBackVerticals(row);
       grid.push(row);
     }