dsh-archify-projects 0.0.0-stage → 0.1.0

package/skills/archify/renderers/lifecycle/README.md

@@ -0,0 +1,171 @@
+# Lifecycle Renderer
+
+Render `diagram_type: "lifecycle"` JSON files into the standard Archify HTML
+template.
+
+```bash
+node archify/renderers/lifecycle/render-lifecycle.mjs input.lifecycle.json output.html
+```
+
+The renderer validates input against `archify/schemas/lifecycle.schema.json`
+with the bundled standalone validator. No dependency installation is required.
+
+If `output.html` is omitted, the renderer uses the required `meta.output` value
+from the JSON file.
+
+## Input
+
+Lifecycle JSON files must set:
+
+```json
+{
+  "schema_version": 2,
+  "diagram_type": "lifecycle",
+  "meta": {
+    "title": "Deployment Release Lifecycle",
+    "output": "deployment-release-lifecycle.html"
+  },
+  "lanes": [],
+  "states": [],
+  "transitions": [],
+  "cards": []
+}
+```
+
+`schema_version` is `1` or `2`; author new diagrams as `2`. Lane ids `main`
+(required) and `terminal` are reserved in both versions.
+
+- **v2** renders one row per populated lane: `main` first, `terminal` last,
+  other lanes in `lanes[]` order, each titled in the left gutter. A complete
+  example lives at `archify/examples/deployment-release.lifecycle.json`.
+- **v1** keeps the fixed three bands: `main` is the top phase band,
+  `terminal` the bottom outcome band, and every other lane shares the middle
+  event band, whose header joins their labels with ` + `. A complete example
+  lives at `archify/examples/agent-run.lifecycle.json`.
+
+The schema lives at:
+
+```text
+archify/schemas/lifecycle.schema.json
+```
+
+## Legend and state marks
+
+State color follows `states[].type`: active and start are cyan, waiting amber,
+decision purple, success green, failure rose, neutral and external slate.
+Structure is drawn, not colored: every `start` state gets a UML initial marker
+(a dot and arrow into its left side), and a state with no outgoing transition
+gets a double border as a final state (in v1, a main state followed by
+another main column is not final, because the implied rail continues).
+
+The default legend derives kinds from `states[].type`; the `start` entry shows
+the initial marker, and a non-interactive `final` entry appears when a final
+state exists. Supported `meta.legend.entries` keys, in stable order, are
+`start`, `active`, `waiting`, `decision`, `success`, `failure`, `neutral`, and
+`external`. Labels and visibility may be overridden through the shared legend
+contract; only kinds backed by rendered states receive Semantic Legend
+controls.
+
+State decorations share one top rail: the type sigil and `step` on the left,
+the brand mark at the right corner, and the Viewer's runtime source badge just
+left of the brand. Label layout reserves the badge's width whenever the state
+has verified repository sources.
+
+## Layout budget (v2)
+
+| Item | Value |
+|------|-------|
+| Columns | `col` 0–4, one x grid shared by every row |
+| Default state | 140×64 (text 11px label, 8px sublabel and tag) |
+| Column gap | 64px, widened until a labelled same-row neighbour transition fits beside its line; all gaps shrink toward 44px when the canvas would exceed the desktop readability budget of the smallest state text |
+| Row gap | at least 120px, opened further for the horizontal tracks its routes need |
+| Canvas | sized from the rows, columns, and measured legend when `meta.viewBox` is omitted; an authored `viewBox` is honored and validated |
+
+Transitions without `via`, a channel, or a non-`auto` route use the v2 grid
+router: neighbours in one row connect horizontally (a reciprocal pair runs as
+two parallel lines), rows connect through the facing top/bottom sides with one
+turn in a row gap, a state blocking a straight descent sends the route through
+the empty corridor between columns, and an unlabelled route blocked in an
+outer column loops around the outside of the grid. Each gap assigns tracks in
+the order that minimizes crossings. There is no implied rail; a forward
+transition between two `main` states without a `variant` renders as the
+emphasized primary path. Showcase labels are ranked beside their line, then on
+it, then outward past neighbouring parallels.
+
+Explicit `fromSide` / `toSide` values remain authoritative. Pins that match the
+grid router's chosen sides keep its routes and adaptive row gaps. If an automatic
+transition pins a different side, the scene uses the shared side-aware obstacle
+planner, retaining the v2 state grid and shared port spreading.
+
+## Layout budget (v1)
+
+| Band | Lane id | Top y | Column centers | Default state |
+|------|---------|-------|----------------|---------------|
+| Phase | `main` (required) | 126 | `col` 0–4 → x = 94, 248, 402, 556, 710 | 118×62 |
+| Event | any other id | 278 | `col` 0–2 → x = 402, 556, 710 | 126×58 |
+| Outcome | `terminal` | 450 | `col` 0–2 → x = 402, 556, 710 | 118×58 |
+
+Event and terminal columns are intentionally offset from the main rail:
+event/terminal `col: N` uses the same x coordinate as main `col: N + 2`.
+For example, lower-band columns 0, 1, and 2 align beneath main columns 2, 3,
+and 4 respectively.
+
+| Constant | Value |
+|----------|-------|
+| viewBox | default `[980, 660]`; schema minimum `[420, 566]` |
+| State area | x within `[32, width − 32]`; state bottom at or above `height − 122` |
+| State spacing | ≥10px between any two states — checked across lanes, because all event lanes share one band; separate same-band states with `col` or `yOffset` |
+| Transition length | ≥32px between endpoints |
+| Legend row | final baseline y = height − 36; extra measured rows wrap upward |
+
+The primary lifecycle rail runs along the phase band and extends to the
+furthest occupied phase column. Route presets for transitions: `straight`,
+`drop` (bend at `channelY`, defaulting to the vertical midpoint),
+`bottom-channel`, `top-channel`, `right-channel`, `left-channel`, explicit
+`via` points, or the default `auto`. Multi-segment transitions get rounded
+corners; tune them with `cornerRadius` (default 10, `0` for sharp bends).
+
+Transition `label` and `note` are independently optional. A non-empty `note`
+renders even when `label` is omitted or empty, using its existing secondary
+text style on a single row and retaining the note's fine-detail visibility.
+With both fields present, the note stays below the label. Notes participate in
+automatic label placement, route-space reservation, and label collision checks;
+the existing `labelAt`, `labelDx`, `labelDy`, and
+`labelSegment` controls also position a note-only text block.
+
+## Design Rules
+
+- Treat lifecycle diagrams as a phase map, not a dense state-transition graph.
+- Put the primary lifecycle on one horizontal row using the `main` lane; in v2,
+  author each step of it as a transition.
+- In v2, place an interruption, recovery, or exit in the column of the state it
+  leaves so its transition drops straight down.
+- Use `step` labels for ordered phases, such as `01`, `02`, and `03`.
+- Use lower lanes only for interruptions, recovery, and terminal exits.
+- Keep transition labels out of the main SVG unless the label is essential;
+  prefer node labels, tags, legend entries, and summary cards.
+- Prefer axis-aligned lines and avoid crossings. Terminal exits should drop
+  vertically from their source event whenever possible. Explicit `straight`
+  routes remain supported; see the [authored routing contract](../../references/authoring-contract.md#executable-geometry-rules).
+- Use `success` for completion, `failure` for failure/terminal exits,
+  `waiting` for pauses, and `decision` for quality gates.
+
+Schema violations exit non-zero with path-prefixed messages annotated with the
+element's id or label. The renderer additionally fails when it can detect
+layout problems, including a missing `main` lane, duplicate state IDs, unknown
+lanes, unknown transition endpoints, states outside the lifecycle area,
+overlapping states (including across lanes), labels colliding with states or
+other labels, labels wider than their state, unreadably short transitions, or
+transitions crossing unrelated states (2px Clean Flow clearance). Lifecycle
+bands remain intentional pass-through containers.
+Text width is estimated CJK-aware: fullwidth glyphs count as two units.
+
+Set `meta.quality_profile` to `showcase` for polished delivery. Unrelated proper
+X crossings then fail with `composition/proper-crossing`; default `standard`
+keeps them as artifact-receipt warnings. The final artifact check samples
+rounded `Q` corners. Collinear corridors remain outside the proper-X rule, but
+a separate gate warns in `standard` and fails in `showcase` when unrelated
+transitions overlap for at least 8px. Shared semantic endpoints, point touches,
+and shorter overlaps remain valid. Showcase also rejects any route segment
+below 8px and any interior turn segment below 16px; ordinary 8–15px endpoint
+stubs remain valid.

package/skills/archify/renderers/lifecycle/grid-routing.mjs

@@ -0,0 +1,429 @@
+// Orthogonal router for schema_version 2 lifecycle diagrams.
+//
+// v2 states sit on a fixed grid: one row per lane and a shared column pitch,
+// with empty gaps between rows and between columns. That structure lets
+// every automatic transition use a small, predictable set of shapes instead
+// of a general obstacle search:
+//   - neighbours in one row connect with a horizontal line;
+//   - other states in one row connect through the gap above (below for the
+//     first row);
+//   - states in different rows leave through the facing top/bottom side,
+//     turn once in a row gap, and enter the target's facing side; when a
+//     state blocks the straight descent, the route steps sideways through the
+//     empty corridor between two columns.
+// Ports on each side are spread in the order of where their routes head, and
+// the horizontal runs in each gap get their own tracks, ordered to minimize
+// crossings. Reciprocal pairs therefore render as two parallel lines.
+
+const PORT_GUTTER = 16;
+const PORT_SPACING = 30;
+const SNAP_LIMIT = 16;
+const TRACK_TOP_CLEARANCE = 18;
+const TRACK_BOTTOM_CLEARANCE = 18;
+const PREFERRED_TRACK_SPACING = 22;
+const MAX_TRACK_SPACING = 24;
+const CORRIDOR_SPACING = 10;
+const EXHAUSTIVE_TRACK_LIMIT = 7;
+
+const opposite = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
+
+function permutations(items) {
+  if (items.length <= 1) return [items];
+  return items.flatMap((item, index) => permutations([...items.slice(0, index), ...items.slice(index + 1)])
+    .map((rest) => [item, ...rest]));
+}
+
+export function createLifecycleGridRouter(states, transitions, { rowOf, columnXs }) {
+  const byRow = new Map();
+  for (const state of states.values()) {
+    const row = rowOf(state);
+    if (!Number.isInteger(row)) continue;
+    if (!byRow.has(row)) byRow.set(row, []);
+    byRow.get(row).push(state);
+  }
+  const rows = [...byRow.keys()].sort((a, b) => a - b);
+  const rowTop = new Map(rows.map((row) => [row, Math.min(...byRow.get(row).map((s) => s.y))]));
+  const rowBottom = new Map(rows.map((row) => [row, Math.max(...byRow.get(row).map((s) => s.y + s.height))]));
+  const nextRow = (row) => rows.find((candidate) => candidate > row);
+  const previousRow = (row) => [...rows].reverse().find((candidate) => candidate < row);
+
+  // Gap g sits below row g. The gap under the last row borders the legend,
+  // so it only receives tracks when nothing else is possible.
+  function gapBand(row) {
+    const below = nextRow(row);
+    const top = rowBottom.get(row) + TRACK_TOP_CLEARANCE;
+    const bottom = below === undefined ? rowBottom.get(row) + 40 : rowTop.get(below) - TRACK_BOTTOM_CLEARANCE;
+    return [top, Math.max(top, bottom)];
+  }
+
+  function blocksVertical(x, fromRow, toRow, exclude) {
+    const [low, high] = fromRow < toRow ? [fromRow, toRow] : [toRow, fromRow];
+    return [...states.values()].some((state) => {
+      if (exclude.has(state.id)) return false;
+      const row = rowOf(state);
+      return row > low && row < high && x >= state.x - 6 && x <= state.x + state.width + 6;
+    });
+  }
+
+  function blocksHorizontal(from, to) {
+    const row = rowOf(from);
+    const [left, right] = from.cx < to.cx ? [from, to] : [to, from];
+    return byRow.get(row).some((state) => state !== left && state !== right
+      && state.x < right.x && state.x + state.width > left.x + left.width
+      && state.y < Math.max(left.y + left.height, right.y + right.height)
+      && state.y + state.height > Math.min(left.y, right.y));
+  }
+
+  // The empty corridors between neighbouring columns.
+  const corridorXs = columnXs.slice(1).map((x, index) => (x + columnXs[index]) / 2);
+  const allStates = [...states.values()];
+  const leftmostX = Math.min(...allStates.map((state) => state.cx));
+  const rightmostX = Math.max(...allStates.map((state) => state.cx));
+  const gridLeft = Math.min(...allStates.map((state) => state.x));
+  const gridRight = Math.max(...allStates.map((state) => state.x + state.width));
+  // The initial-state marker occupies a start state's left side.
+  function loopBlocked(from, to, side) {
+    if (side !== 'left') return false;
+    const [low, high] = [Math.min(rowOf(from), rowOf(to)), Math.max(rowOf(from), rowOf(to))];
+    return allStates.some((state) => state.type === 'start' && Math.abs(state.cx - from.cx) < 1
+      && rowOf(state) >= low && rowOf(state) <= high);
+  }
+
+  // Plan: sides, the gap each horizontal run uses, and where each end heads.
+  const plans = new Map();
+  for (const transition of transitions) {
+    const from = states.get(transition.from);
+    const to = states.get(transition.to);
+    if (!from || !to || from === to) continue;
+    const fromRow = rowOf(from);
+    const toRow = rowOf(to);
+    if (!Number.isInteger(fromRow) || !Number.isInteger(toRow)) continue;
+    const exclude = new Set([from.id, to.id]);
+    if (fromRow === toRow) {
+      if (!blocksHorizontal(from, to)) {
+        const fromSide = to.cx > from.cx ? 'right' : 'left';
+        plans.set(transition, { kind: 'horizontal', from, to, fromSide, toSide: opposite[fromSide] });
+      } else {
+        const gapRow = previousRow(fromRow);
+        const useAbove = gapRow !== undefined;
+        const side = useAbove ? 'top' : 'bottom';
+        plans.set(transition, {
+          kind: 'channel', from, to, fromSide: side, toSide: side,
+          runs: [{ gap: useAbove ? gapRow : fromRow, legs: useAbove ? ['down', 'down'] : ['up', 'up'] }],
+        });
+      }
+      continue;
+    }
+    const down = toRow > fromRow;
+    const fromSide = down ? 'bottom' : 'top';
+    const toSide = down ? 'top' : 'bottom';
+    const gapNearTarget = down ? previousRow(toRow) : toRow;
+    const gapNearSource = down ? fromRow : previousRow(fromRow);
+    const legs = down ? ['up', 'down'] : ['down', 'up'];
+    if (!blocksVertical(from.cx, fromRow, toRow, exclude) && Math.abs(from.cx - to.cx) < 1) {
+      plans.set(transition, { kind: 'vertical', from, to, fromSide, toSide, runs: [{ gap: gapNearTarget, legs }] });
+    } else if (!blocksVertical(from.cx, fromRow, toRow, exclude)) {
+      plans.set(transition, { kind: 'channel', from, to, fromSide, toSide, runs: [{ gap: gapNearTarget, legs }] });
+    } else if (!blocksVertical(to.cx, fromRow, toRow, exclude)) {
+      plans.set(transition, { kind: 'channel', from, to, fromSide, toSide, runs: [{ gap: gapNearSource, legs }] });
+    } else if (!transition.label && !transition.note
+      && Math.abs(from.cx - to.cx) < 1 && (from.cx <= leftmostX || from.cx >= rightmostX)
+      && !loopBlocked(from, to, from.cx <= leftmostX ? 'left' : 'right')) {
+      // A blocked edge column loops around the outside of the grid, like a
+      // bracket, instead of weaving through the rows' interior corridors.
+      // The margin has no room for a label, so only unlabeled edges loop.
+      const side = from.cx <= leftmostX ? 'left' : 'right';
+      plans.set(transition, { kind: 'loop', from, to, fromSide: side, toSide: side, side });
+    } else {
+      const middle = (from.cx + to.cx) / 2;
+      const corridor = corridorXs
+        .filter((x) => !blocksVertical(x, fromRow, toRow, new Set()))
+        .sort((a, b) => Math.abs(a - middle) - Math.abs(b - middle))[0];
+      plans.set(transition, corridor === undefined
+        ? { kind: 'channel', from, to, fromSide, toSide, runs: [{ gap: gapNearTarget, legs }] }
+        : {
+          kind: 'corridor', from, to, fromSide, toSide, corridor,
+          runs: [{ gap: gapNearSource, legs }, { gap: gapNearTarget, legs }],
+        });
+    }
+  }
+
+  // Corridor offsets: routes sharing one corridor run side by side.
+  const corridorUse = new Map();
+  for (const plan of plans.values()) {
+    if (plan.kind !== 'corridor') continue;
+    const list = corridorUse.get(plan.corridor) || [];
+    list.push(plan);
+    corridorUse.set(plan.corridor, list);
+  }
+  for (const [x, list] of corridorUse) {
+    list.sort((a, b) => a.from.cx - b.from.cx || a.to.cx - b.to.cx);
+    list.forEach((plan, index) => { plan.corridorX = x + (index - (list.length - 1) / 2) * CORRIDOR_SPACING; });
+  }
+  // Outer loops nest: a longer span sits further out so loops never cross.
+  for (const side of ['left', 'right']) {
+    const loops = [...plans.values()].filter((plan) => plan.kind === 'loop' && plan.side === side)
+      .sort((a, b) => Math.abs(rowOf(a.from) - rowOf(a.to)) - Math.abs(rowOf(b.from) - rowOf(b.to)));
+    loops.forEach((plan, index) => {
+      plan.loopX = side === 'left' ? gridLeft - 18 - index * CORRIDOR_SPACING : gridRight + 18 + index * CORRIDOR_SPACING;
+    });
+  }
+
+  // Where each end heads after leaving its side, used to order the ports.
+  function headingFor(plan, end) {
+    const self = end === 'source' ? plan.from : plan.to;
+    const other = end === 'source' ? plan.to : plan.from;
+    if (plan.kind === 'horizontal' || plan.kind === 'loop') return other.cy;
+    if (plan.kind === 'corridor') return plan.corridorX;
+    return other === self ? self.cx : other.cx;
+  }
+
+  const sideEnds = new Map();
+  for (const [transition, plan] of plans) {
+    for (const end of ['source', 'target']) {
+      const state = end === 'source' ? plan.from : plan.to;
+      const side = end === 'source' ? plan.fromSide : plan.toSide;
+      const key = `${state.id}:${side}`;
+      if (!sideEnds.has(key)) sideEnds.set(key, { state, side, ends: [] });
+      // Movers in the positive direction (right/down) take the first slot so
+      // both ends of a reciprocal pair line up.
+      const positive = plan.kind === 'horizontal'
+        ? plan.to.cx > plan.from.cx
+        : rowOf(plan.to) > rowOf(plan.from) || (rowOf(plan.to) === rowOf(plan.from) && plan.to.cx > plan.from.cx);
+      sideEnds.get(key).ends.push({ transition, end, heading: headingFor(plan, end), positive });
+    }
+  }
+
+  const ports = new Map();
+  for (const { state, side, ends } of sideEnds.values()) {
+    ends.sort((a, b) => a.heading - b.heading || Number(b.positive) - Number(a.positive));
+    const horizontalSide = side === 'top' || side === 'bottom';
+    const length = horizontalSide ? state.width : state.height;
+    const gutter = Math.min(PORT_GUTTER, length / 4);
+    const spacing = ends.length > 1 ? Math.min(PORT_SPACING, (length - gutter * 2) / (ends.length - 1)) : 0;
+    ends.forEach((entry, index) => {
+      const offset = (index - (ends.length - 1) / 2) * spacing;
+      const point = horizontalSide
+        ? [state.cx + offset, side === 'top' ? state.y : state.y + state.height]
+        : [side === 'left' ? state.x : state.x + state.width, state.cy + offset];
+      const record = ports.get(entry.transition) || {};
+      record[entry.end] = point;
+      ports.set(entry.transition, record);
+    });
+  }
+
+  // Straight connections whose spread ports landed a few px apart would
+  // otherwise need a jog shorter than a readable turn: move one end onto the
+  // other's line when that side still has room there.
+  function sideRange(state, side) {
+    return side === 'top' || side === 'bottom'
+      ? [state.x + PORT_GUTTER / 2, state.x + state.width - PORT_GUTTER / 2]
+      : [state.y + PORT_GUTTER / 2, state.y + state.height - PORT_GUTTER / 2];
+  }
+  function portsOnSide(state, side, except) {
+    return (sideEnds.get(`${state.id}:${side}`)?.ends || [])
+      .filter((entry) => entry.transition !== except)
+      .map((entry) => ports.get(entry.transition)[entry.end]);
+  }
+  for (const [transition, plan] of plans) {
+    const record = ports.get(transition);
+    const axis = plan.kind === 'horizontal' ? 1 : 0;
+    const delta = Math.abs(record.source[axis] - record.target[axis]);
+    if (delta < 0.5 || delta >= SNAP_LIMIT || !(plan.kind === 'horizontal' || plan.kind === 'vertical' || plan.kind === 'channel')) continue;
+    for (const [end, fixed] of [['target', 'source'], ['source', 'target']]) {
+      const state = end === 'source' ? plan.from : plan.to;
+      const side = end === 'source' ? plan.fromSide : plan.toSide;
+      const value = record[fixed][axis];
+      const [low, high] = sideRange(state, side);
+      const crowded = portsOnSide(state, side, transition).some((point) => Math.abs(point[axis] - value) < 10);
+      if (value >= low && value <= high && !crowded) {
+        record[end] = axis ? [record[end][0], value] : [value, record[end][1]];
+        break;
+      }
+    }
+  }
+
+  // Horizontal runs per gap, then tracks ordered to minimize crossings.
+  const runsByGap = new Map();
+  for (const [transition, plan] of plans) {
+    if (plan.kind === 'horizontal' || plan.kind === 'loop') continue;
+    const { source, target } = ports.get(transition);
+    plan.runs.forEach((run, index) => {
+      const x1 = index === 0 ? source[0] : plan.corridorX;
+      const x2 = plan.kind === 'corridor' && index === 0 ? plan.corridorX : target[0];
+      if (plan.kind !== 'corridor' && Math.abs(x1 - x2) < 0.5) return;
+      const entry = { transition, index, x1, x2, legs: run.legs };
+      if (!runsByGap.has(run.gap)) runsByGap.set(run.gap, []);
+      runsByGap.get(run.gap).push(entry);
+    });
+  }
+
+  const trackY = new Map();
+  const trackCounts = new Map();
+  for (const [gap, runs] of runsByGap) {
+    const [top, bottom] = gapBand(gap);
+    // Greedy interval colouring keeps unrelated runs on shared tracks only
+    // when they do not overlap.
+    const sorted = [...runs].sort((a, b) => Math.min(a.x1, a.x2) - Math.min(b.x1, b.x2));
+    const classes = [];
+    for (const run of sorted) {
+      const low = Math.min(run.x1, run.x2) - 8;
+      const high = Math.max(run.x1, run.x2) + 8;
+      let target = classes.find((members) => members.every((other) => (
+        high < Math.min(other.x1, other.x2) - 8 || low > Math.max(other.x1, other.x2) + 8
+      )));
+      if (!target || runs.length <= EXHAUSTIVE_TRACK_LIMIT) {
+        target = [];
+        classes.push(target);
+      }
+      target.push(run);
+    }
+    const count = classes.length;
+    trackCounts.set(gap, count);
+    // The renderer sizes each gap for its track count; a fixed canvas that
+    // cannot grow compresses the tracks rather than leaving the gap.
+    const spacing = count > 1 ? Math.min(MAX_TRACK_SPACING, (bottom - top) / (count - 1)) : 0;
+    const center = (top + bottom) / 2;
+    const ys = classes.map((_, index) => center + (index - (count - 1) / 2) * spacing);
+    const crossings = (order) => {
+      const y = new Map();
+      order.forEach((members, index) => members.forEach((run) => y.set(run, ys[index])));
+      let total = 0;
+      for (const a of runs) {
+        for (const b of runs) {
+          if (a === b || a.transition === b.transition) continue;
+          const [low, high] = [Math.min(a.x1, a.x2), Math.max(a.x1, a.x2)];
+          for (const [x, leg] of [[b.x1, b.legs[0]], [b.x2, b.legs[1]]]) {
+            // An up leg and a down leg on one x overlap when the down leg
+            // starts above where the up leg ends: that merges two routes.
+            for (const [ax, aLeg] of [[a.x1, a.legs[0]], [a.x2, a.legs[1]]]) {
+              if (Math.abs(ax - x) < 1 && aLeg === 'up' && leg === 'down' && y.get(b) < y.get(a)) total += 100;
+            }
+            if (x <= low + 0.5 || x >= high - 0.5) continue;
+            if ((leg === 'up' && y.get(a) < y.get(b)) || (leg === 'down' && y.get(a) > y.get(b))) total += 1;
+          }
+        }
+      }
+      return total;
+    };
+    let best = classes;
+    let bestScore = crossings(best);
+    if (count <= EXHAUSTIVE_TRACK_LIMIT) {
+      for (const order of permutations(classes).slice(1)) {
+        const score = crossings(order);
+        if (score < bestScore) {
+          best = order;
+          bestScore = score;
+        }
+      }
+    } else {
+      // Too many tracks to enumerate: swap pairs while that still helps.
+      for (let improved = true; improved;) {
+        improved = false;
+        for (let i = 0; i < count && !improved; i += 1) {
+          for (let j = i + 1; j < count && !improved; j += 1) {
+            const order = [...best];
+            [order[i], order[j]] = [order[j], order[i]];
+            const score = crossings(order);
+            if (score < bestScore) {
+              best = order;
+              bestScore = score;
+              improved = true;
+            }
+          }
+        }
+      }
+    }
+    best.forEach((members, index) => members.forEach((run) => trackY.set(`${gap}:${run.index}:${transitions.indexOf(run.transition)}`, ys[index])));
+  }
+
+  const pathCache = new Map();
+  function pointsFor(transition) {
+    const plan = plans.get(transition);
+    if (!plan) {
+      // Self transitions and unknown endpoints are rejected by validation;
+      // a degenerate stub keeps that diagnostic reachable.
+      const state = states.get(transition.from) || states.get(transition.to);
+      const point = state ? [state.x + state.width, state.cy] : [0, 0];
+      return [point, point];
+    }
+    const { source, target } = ports.get(transition);
+    if (plan.kind === 'horizontal') {
+      if (Math.abs(source[1] - target[1]) < 0.5) return [source, target];
+      const x = (source[0] + target[0]) / 2;
+      return [source, [x, source[1]], [x, target[1]], target];
+    }
+    if (plan.kind === 'loop') return [source, [plan.loopX, source[1]], [plan.loopX, target[1]], target];
+    const trackFor = (index) => trackY.get(`${plan.runs[index].gap}:${index}:${transitions.indexOf(transition)}`);
+    if (plan.kind === 'corridor') {
+      const y1 = trackFor(0);
+      const y2 = trackFor(1);
+      return [source, [source[0], y1], [plan.corridorX, y1], [plan.corridorX, y2], [target[0], y2], target];
+    }
+    if (Math.abs(source[0] - target[0]) < 0.5) return [source, target];
+    const y = trackFor(0);
+    return [source, [source[0], y], [target[0], y], target];
+  }
+
+  // Ports of two routes can still line up across a gap so their vertical
+  // runs share one line. Nudge a turning route's end sideways on its side.
+  for (const transition of plans.keys()) pathCache.set(transition, pointsFor(transition));
+  const verticals = (points) => points.slice(1).flatMap((end, index) => {
+    const start = points[index];
+    if (Math.abs(start[0] - end[0]) >= 0.5 || Math.abs(start[1] - end[1]) < 0.5) return [];
+    return [{ x: start[0], low: Math.min(start[1], end[1]), high: Math.max(start[1], end[1]), index, last: index === points.length - 2 }];
+  });
+  for (let round = 0; round < 12; round += 1) {
+    const entries = [...pathCache.entries()];
+    let conflict = null;
+    for (let i = 0; i < entries.length && !conflict; i += 1) {
+      for (let j = i + 1; j < entries.length && !conflict; j += 1) {
+        for (const left of verticals(entries[i][1])) {
+          const right = verticals(entries[j][1]).find((other) => Math.abs(other.x - left.x) < 1
+            && Math.min(other.high, left.high) - Math.max(other.low, left.low) > 0.5);
+          if (right) {
+            conflict = [[entries[i][0], left], [entries[j][0], right]];
+            break;
+          }
+        }
+      }
+    }
+    if (!conflict) break;
+    let moved = false;
+    for (const [transition, segment] of conflict) {
+      const plan = plans.get(transition);
+      const end = segment.index === 0 ? 'source' : segment.last ? 'target' : null;
+      if (!end || pathCache.get(transition).length < 4 || !['channel', 'corridor'].includes(plan.kind)) continue;
+      const state = end === 'source' ? plan.from : plan.to;
+      const side = end === 'source' ? plan.fromSide : plan.toSide;
+      const record = ports.get(transition);
+      const [low, high] = sideRange(state, side);
+      const x = [12, -12, 20, -20].map((delta) => record[end][0] + delta).find((candidate) => (
+        candidate >= low && candidate <= high
+        && !portsOnSide(state, side, transition).some((point) => Math.abs(point[0] - candidate) < 10)
+      ));
+      if (x === undefined) continue;
+      record[end] = [x, record[end][1]];
+      pathCache.set(transition, pointsFor(transition));
+      moved = true;
+      break;
+    }
+    if (!moved) break;
+  }
+
+  return {
+    // Height a gap below `row` needs for its tracks at a readable spacing.
+    gapHeight(row) {
+      const count = trackCounts.get(row) || 0;
+      return TRACK_TOP_CLEARANCE + TRACK_BOTTOM_CLEARANCE + Math.max(0, count - 1) * PREFERRED_TRACK_SPACING;
+    },
+    connectionSides(transition) {
+      const plan = plans.get(transition);
+      return plan ? { fromSide: plan.fromSide, toSide: plan.toSide } : { fromSide: 'right', toSide: 'right' };
+    },
+    pathFor(transition) {
+      if (!pathCache.has(transition)) pathCache.set(transition, pointsFor(transition));
+      return pathCache.get(transition);
+    },
+  };
+}