@knowvah/dot-engine 0.1.0

package/src/layout/dot/edge-route-arrow.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Arrowhead polygon geometry for dot-layout edge rendering.
+ *
+ * @see lib/common/arrows.c:arrow_type_normal0
+ * @see lib/common/arrows.c:miter_shape
+ */
+
+import type { Point } from '../../model/geom.js';
+import { normalizeVec } from './edge-route-geom.js';
+import { parseArrow, resolveArrowType } from '../../common/arrows.js';
+import { arrowDrawOps } from '../../common/arrows-shapes.js';
+import type { ArrowDrawOp } from '../../common/arrows-types.js';
+
+/** Arrow length in points. @see lib/common/arrows.c:#define ARROW_LENGTH 10. */
+export const ARROW_LENGTH = 10;
+
+/** Arrow width factor. @see lib/common/arrows.c:arrowwidth = 0.35 */
+export const ARROW_WIDTH_FACTOR = 0.35;
+
+/**
+ * Three-point arrowhead polygon: [rightBase, adj_tip, leftBase].
+ *
+ * Matches C's arrow_type_normal0 for a standard "normal" arrowhead:
+ *   1. delta_tip correction shifts both the polygon tip and base TOWARD the
+ *      shaft by the miter-join extension length, so the filled polygon covers
+ *      the miter join produced by the SVG renderer at the sharp tip vertex.
+ *      Formula: (penwidth / (2 * arrowwidth)) * sqrt(1 + arrowwidth^2)
+ *   2. Polygon order is [a[1]=right_base, a[2]=adj_tip, a[3]=left_base]
+ *      (matching gvrender_polygon(job, &a[1], 3)).
+ *
+ * @see lib/common/arrows.c:arrow_type_normal0
+ * @see lib/common/arrows.c:miter_shape
+ */
+export function arrowheadPolygon(arrowTip: Point, arrowDir: Point, penwidth = 1.0): Point[] {
+  const dir = normalizeVec(arrowDir);
+  const delta = (penwidth / (2 * ARROW_WIDTH_FACTOR)) * Math.sqrt(1 + ARROW_WIDTH_FACTOR * ARROW_WIDTH_FACTOR);
+  const adj_tip: Point = { x: arrowTip.x + dir.x * delta, y: arrowTip.y + dir.y * delta };
+  const adj_base: Point = {
+    x: arrowTip.x + dir.x * (ARROW_LENGTH + delta),
+    y: arrowTip.y + dir.y * (ARROW_LENGTH + delta),
+  };
+  const hw = ARROW_LENGTH * ARROW_WIDTH_FACTOR;
+  const perp: Point = { x: -dir.y * hw, y: dir.x * hw };
+  return [
+    { x: adj_base.x - perp.x, y: adj_base.y - perp.y },  // a[1] = right base
+    adj_tip,                                                // a[2] = tip
+    { x: adj_base.x + perp.x, y: adj_base.y + perp.y },  // a[3] = left base
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Per-type arrow draw-op dispatch (ADR-1/ADR-2) — replaces the normal-only
+// arrowheadPolygon at the layout storage sites.
+// ---------------------------------------------------------------------------
+
+/** Minimal edge shape exposing the arrow-related attributes. */
+interface ArrowAttrEdge { attrs: Map<string, string> }
+
+/** The arrowhead/arrowtail name for an edge end (default "normal"). */
+export function edgeArrowName(e: ArrowAttrEdge, end: 'head' | 'tail'): string {
+  return e.attrs.get(end === 'head' ? 'arrowhead' : 'arrowtail') ?? 'normal';
+}
+
+/** The `arrowsize` edge attribute (default 1.0; clamped to ≥0 like late_double). */
+export function edgeArrowsize(e: ArrowAttrEdge): number {
+  const s = parseFloat(e.attrs.get('arrowsize') ?? '');
+  return Number.isFinite(s) ? Math.max(s, 0) : 1.0;
+}
+
+/**
+ * Typed arrow draw-ops for one edge end: reads `arrowhead`/`arrowtail` +
+ * `arrowsize`, resolves the compound arrow type, and dispatches to the full
+ * geometry table (`arrowDrawOps`). `tip` is the node-boundary point, `dir`
+ * points from tip toward the shaft (away from the node).
+ *
+ * @see lib/common/arrows.c:arrow_gen
+ */
+export function arrowDrawOpsForEnd(
+  e: ArrowAttrEdge, end: 'head' | 'tail', tip: Point, dir: Point, penwidth: number,
+): ArrowDrawOp[] {
+  const comps = parseArrow(edgeArrowName(e, end)).map(resolveArrowType);
+  // Pass the RAW direction (not normalized): componentU reproduces arrow_gen's
+  // EPSILON normalization, which is relative to the raw shaft magnitude.
+  return arrowDrawOps(comps, tip, dir, edgeArrowsize(e), penwidth);
+}

package/src/layout/dot/edge-route-boxes.ts

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Box assembly helpers for edge spline routing.
+ *
+ * Constructs the path boxes (tail, rank, head) that define the corridor
+ * through which a spline is routed.
+ *
+ * @see lib/common/splines.c:beginpath
+ * @see lib/common/splines.c:endpath
+ * @see lib/dotgen/dotsplines.c:rank_box
+ * @see lib/dotgen/dotsplines.c:maximal_bbox
+ */
+
+import type { Box } from '../../model/geom.js';
+import type { NodeBox } from './edge-route-geom.js';
+
+/** FUDGE padding added around node x-extents in maximal_bbox. */
+const FUDGE = 2;
+
+/**
+ * Assemble the tail-side box (beginpath, REGULAREDGE, no port).
+ *
+ * C sets boxes[0].UR.y = start.p.y. In TS SVG coords C's UR.y maps to
+ * our ll.y. The tail box spans ll.y=startPy (center) to ur.y (bottom).
+ *
+ * @see lib/common/splines.c:beginpath
+ */
+/**
+ * Tail box: nb with ur.y overridden to startPy (= beginpath UR.y = center.y).
+ * C: endp->boxes[0] = nb; endp->boxes[0].UR.y = P->start.p.y
+ * @see lib/common/splines.c:beginpath REGULAREDGE case
+ */
+export function makeTailBox(nb: Box, startPy: number): Box {
+  return { ll: nb.ll, ur: { x: nb.ur.x, y: startPy } };
+}
+
+/**
+ * Assemble the head-side box (endpath, REGULAREDGE, no port).
+ *
+ * C sets boxes[0].LL.y = end.p.y. In TS SVG coords C's LL.y maps to
+ * our ur.y. The head box spans ll.y (top) to ur.y=endPy (center).
+ *
+ * @see lib/common/splines.c:endpath
+ */
+/**
+ * Head box: nb with ll.y overridden to endPy (= endpath LL.y = center.y).
+ * C: endp->boxes[0] = nb; endp->boxes[0].LL.y = P->end.p.y
+ * @see lib/common/splines.c:endpath REGULAREDGE case
+ */
+export function makeHeadBox(nb: Box, endPy: number): Box {
+  return { ll: { x: nb.ll.x, y: endPy }, ur: nb.ur };
+}
+
+/** Parameters for makeRankBox — avoids a 6-parameter signature. */
+export interface RankBoxParams {
+  llx: number;
+  urx: number;
+  tailCy: number;
+  tailHt1: number;
+  headCy: number;
+  headHt2: number;
+}
+
+/**
+ * Inter-rank space box between two adjacent ranks.
+ *
+ * In TS SVG coords: ll.y = tailCy+tailHt1 (bottom of tail node),
+ * ur.y = headCy-headHt2 (top of head node).
+ *
+ * @see lib/dotgen/dotsplines.c:rank_box
+ */
+/**
+ * Inter-rank space box: from head node top (ll.y) to tail node bottom (ur.y).
+ * C: ll.y = headCy + headHt2  (= B.top = 90+18=108)
+ *    ur.y = tailCy - tailHt1  (= A.bottom = 162-18=144)
+ * @see lib/dotgen/dotsplines.c:rank_box
+ */
+export function makeRankBox(p: RankBoxParams): Box {
+  return {
+    ll: { x: p.llx, y: p.headCy + p.headHt2 },
+    ur: { x: p.urx, y: p.tailCy - p.tailHt1 },
+  };
+}
+
+/**
+ * Node bounding box for maximal_bbox (simple node, no neighbors).
+ *
+ * ll = { x: cx-lw-FUDGE, y: cy-ht1 }  (top-left in SVG)
+ * ur = { x: cx+rw+FUDGE, y: cy+ht2 }  (bottom-right in SVG)
+ *
+ * @see lib/dotgen/dotsplines.c:maximal_bbox
+ */
+export function makeMaximalBbox(box: NodeBox, ht1: number, ht2: number): Box {
+  return {
+    ll: { x: box.center.x - box.lw - FUDGE, y: box.center.y - ht1 },
+    ur: { x: box.center.x + box.rw + FUDGE, y: box.center.y + ht2 },
+  };
+}

package/src/layout/dot/edge-route-chain.ts

@@ -0,0 +1,420 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Multi-rank edge routing via virtual-node chains.
+ *
+ * Both back-edges (tail.rank > head.rank) and forward edges spanning
+ * more than one rank (head.rank > tail.rank + 1) are routed by
+ * walking the virtual-node chain that class2/makeChain created and
+ * building a corridor-box path through every intermediate rank.
+ *
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag path)
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Edge as GraphEdge } from '../../model/edge.js';
+import type { Point, Box } from '../../model/geom.js';
+import type { Node } from '../../model/node.js';
+import { VIRTUAL, NORMAL } from './fastgr.js';
+import type { NodeBox } from './edge-route-geom.js';
+import { getSplineBounds } from './edge-route-rank.js';
+import type { Path, PathendT } from '../../common/types.js';
+import { makePort } from '../../model/edgeInfo.js';
+import { beginPath } from '../../common/splines-path-begin.js';
+import { endPath } from '../../common/splines-path-end.js';
+import { routeRegularByType } from './splines-route-type.js';
+import { edgeType, EDGETYPE_LINE, resolveOrigEdge, swapEndsP, swapEdgeSpline } from './splines.js';
+import { clipAndInstall } from '../../common/splines-clip.js';
+import { buildDotSinfo } from './self-loop.js';
+import { TOP, BOTTOM, REGULAREDGE } from '../../common/splines-constants.js';
+import { splineMerge, makeLineEdge, resizeVn, straightLen, straightPath } from './splines-route.js';
+import { EDGE_LABEL } from './rank.js';
+import type { RankEntry } from '../../model/rankEntry.js';
+import { rankHt } from './edge-route-rank.js';
+import { graphRanksep } from './position-aux.js';
+import {
+  maximalBbox, appendRegularEnd, freshEndp, rankBox, completeRegularPath,
+  type BboxCtx,
+} from './edge-route-faithful.js';
+
+// ---------------------------------------------------------------------------
+// Faithful multi-rank side-port routing (make_regular_edge hackflag path)
+// @see lib/dotgen/dotsplines.c:make_regular_edge (forward, abs(rankdiff) > 1)
+// ---------------------------------------------------------------------------
+
+/** Per-call spline bounds. Splinesep = nodesep/4 (C's sd.Splinesep,
+ *  dotsplines.c:267) sets the gap to VIRTUAL neighbors in maximal_bbox, which
+ *  the chain's virtual nodes exercise. C's GD_nodesep is an `int` (types.h:334)
+ *  and the divide is INTEGER (18/4=4); a float divide here (4.5) makes
+ *  maximal_bbox's round() straddle the boundary, shifting a virtual-node box
+ *  wall 1px and forcing an extra bezier piece on near-straight long edges
+ *  (rankdir_dot Unix/TS 3.0->TS 4.0). Truncate to mirror C. */
+function chainBboxCtx(g: Graph): BboxCtx {
+  return {
+    g,
+    sp: {
+      ...getSplineBounds(g),
+      splinesep: Math.trunc((g.info.nodesep ?? 18) / 4),
+    },
+  };
+}
+
+/** Segment edges of a forward virtual chain: tail→v1, v1→v2, …, vk→head. */
+function chainSegments(e: GraphEdge): GraphEdge[] {
+  const segs: GraphEdge[] = [];
+  let cur = e.info.to_virt;
+  while (cur !== undefined) {
+    // Resolve the concentrate merge redirect to the representative chain (C: for
+    // rep=e; ED_to_virt(rep); rep=ED_to_virt(rep)). @see lib/dotgen/conc.c:rebuild_vlists
+    while (cur.info.to_virt !== undefined) cur = cur.info.to_virt;
+    segs.push(cur);
+    if (cur.head === e.head) break;
+    const out = cur.head.info.out;
+    cur = out !== undefined && out.size > 0 ? out.list[0] : undefined;
+  }
+  return segs;
+}
+
+/** beginPath/endPath args for a single non-merged REGULAREDGE chain segment. */
+function chainPathArgs(P: Path, e: GraphEdge, endp: PathendT, merge: boolean, ranksep: number) {
+  return { P, e, et: REGULAREDGE, endp, merge, ranksep };
+}
+
+/** True when n is a non-merged virtual chain node (the C while-loop guard). */
+function isChainVirtual(n: Node): boolean {
+  return (n.info.node_type ?? NORMAL) === VIRTUAL && !splineMerge(n);
+}
+
+/**
+ * straight_len smode threshold: a collinear run is segmented once it is ≥ 5
+ * (4+1) with edge labels on the root graph, else ≥ 3 (2+1).
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (GD_has_labels & EDGE_LABEL)
+ */
+function smodeThreshold(g: Graph): number {
+  return ((g.root.info.has_labels ?? 0) & EDGE_LABEL) ? 5 : 3;
+}
+
+/** Mutable state threaded through the make_regular_edge chain walk. */
+interface ChainWalk {
+  ctx: BboxCtx;
+  ranks: RankEntry[];
+  ranksep: number;
+  et: number;
+  P: Path;
+  pts: Point[];
+  boxes: Box[];
+  segfirst: GraphEdge;
+  tend: PathendT;
+}
+
+function newChainWalk(g: Graph, segs: GraphEdge[]): ChainWalk {
+  return {
+    ctx: chainBboxCtx(g), ranks: g.info.rank!, ranksep: graphRanksep(g), et: edgeType(g),
+    P: { start: makePort(), end: makePort(), nbox: 0, boxes: [], data: null },
+    pts: [], boxes: [], segfirst: segs[0],
+    tend: freshEndp({ ll: { x: 0, y: 0 }, ur: { x: 0, y: 0 } }),
+  };
+}
+
+/**
+ * Open a segment: build the tail box from `chainEdge` (real chain geometry),
+ * beginPath on `portEdge` (carries the real tail port for segment 0; the
+ * virtual segment edge thereafter), and append the BOTTOM regular end.
+ * `constrain` forces the straight-middle exit slope on post-straight segments.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (beginpath + makeregularend BOTTOM)
+ */
+function beginSeg(
+  w: ChainWalk, portEdge: GraphEdge, chainEdge: GraphEdge, ie: GraphEdge | undefined, constrain: boolean,
+): void {
+  const tn = chainEdge.tail;
+  w.tend = freshEndp(maximalBbox(w.ctx, tn, ie, chainEdge));
+  // merge tested on the node beginPath/concSlope uses (portEdge.tail), not the
+  // chain segment's tail — they differ when a concentrate-merged chain starts at
+  // a merge node while portEdge carries the real (normal) tail. Symmetric to
+  // endSeg. @see lib/dotgen/dotsplines.c:make_regular_edge (spline_merge(agtail(e)))
+  beginPath(chainPathArgs(w.P, portEdge, w.tend, splineMerge(portEdge.tail), w.ranksep));
+  appendRegularEnd(w.tend.nb, w.tend, BOTTOM, tn.info.coord.y - rankHt(w.ranks[tn.info.rank!].ht1, tn.info.ht));
+  if (constrain) { w.P.start.theta = -Math.PI / 2; w.P.start.constrained = true; }
+}
+
+/**
+ * Close a segment: build the head box from `chainEdge`, endPath on `portEdge`
+ * (the real head port for the final segment; the virtual segment edge for an
+ * smode top), append the TOP regular end, optionally constrain the entry slope
+ * (smode top), then complete + route the path and append the control points.
+ * Returns false when the path cannot be assembled.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (endpath + completeregularpath + routesplines)
+ */
+function endSeg(
+  w: ChainWalk, portEdge: GraphEdge, chainEdge: GraphEdge, oe: GraphEdge | undefined, constrain: boolean,
+): boolean {
+  const hn = chainEdge.head;
+  const hend = freshEndp(maximalBbox(w.ctx, hn, chainEdge, oe));
+  // merge must be tested on the node endPath/concSlope actually uses (the path
+  // edge's head = portEdge.head), as C does (spline_merge(aghead(e))) — NOT the
+  // chain segment's head. They differ in the final segment when the chain ends
+  // at a concentrator merge node while portEdge carries the real (normal) head;
+  // testing the merge node there would call concSlope on the normal sink (0
+  // in/out edges) and crash. @see lib/dotgen/dotsplines.c:make_regular_edge
+  endPath(chainPathArgs(w.P, portEdge, hend, splineMerge(portEdge.head), w.ranksep));
+  appendRegularEnd(hend.nb, hend, TOP, hn.info.coord.y + rankHt(w.ranks[hn.info.rank!].ht2, hn.info.ht));
+  if (constrain) { w.P.end.theta = Math.PI / 2; w.P.end.constrained = true; }
+  if (!completeRegularPath({ P: w.P, first: w.segfirst, last: chainEdge, tend: w.tend, hend, boxes: w.boxes })) {
+    return false;
+  }
+  const seg = routeRegularByType(w.P, w.et);
+  if (seg === null) return false;
+  for (const p of seg) w.pts.push(p);
+  return true;
+}
+
+/**
+ * Close an smode top segment at `segs[ci]` (constrained entry slope), emit the
+ * straight middle as duplicate points, recover slack, then open the next
+ * segment at the post-straight edge with a constrained exit slope. Returns the
+ * chain index of the next segment's first edge, or -1 when routing fails.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (smode close + straight_path)
+ */
+function closeSmodeSeg(w: ChainWalk, segs: GraphEdge[], ci: number, sl: number, segFirst: number): number {
+  if (!endSeg(w, segs[ci], segs[ci], segs[ci + 1], true)) return -1;
+  straightPath(segs[ci + 1], sl, w.pts);
+  recoverSlack(segs.slice(segFirst), w.P);
+  const next = ci + 1 + sl;
+  w.segfirst = segs[next];
+  w.boxes = [];
+  beginSeg(w, segs[next], segs[next], segs[next].tail.info.in!.list[0], true);
+  return next;
+}
+
+/** Route the final (post-loop) chain segment, ending at the real head node. */
+function finishChain(
+  w: ChainWalk, portEdge: GraphEdge, lastEdge: GraphEdge, segFirst: number, segs: GraphEdge[],
+): boolean {
+  w.boxes.push(rankBox(w.ctx, lastEdge.tail.info.rank!));
+  if (!endSeg(w, portEdge, lastEdge, undefined, false)) return false;
+  recoverSlack(segs.slice(segFirst), w.P);
+  return true;
+}
+
+/**
+ * Route a virtual-node chain through the faithful pipeline, accumulating the
+ * make_regular_edge spline points. Below the straight_len threshold this emits a
+ * single segment (identical to the prior single-pass routing); a long
+ * collinear vnode run is split into spline-top + straight-middle + spline-bottom
+ * via successive beginpath/endpath/routesplines calls, hugging the corridor.
+ * `e` carries the real end ports (first beginpath, final endpath); the chain
+ * edges drive the box geometry.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (1771-1873 smode loop)
+ */
+function routeChainSegmented(
+  g: Graph, beginEdge: GraphEdge, endEdge: GraphEdge, segs: GraphEdge[],
+): Point[] | null {
+  const w = newChainWalk(g, segs);
+  const thr = smodeThreshold(g);
+  beginSeg(w, beginEdge, segs[0], undefined, false);
+  let ei = 0, segFirst = 0, smode = false, si = false, sl = 0;
+  while (isChainVirtual(segs[ei].head)) {
+    w.boxes.push(rankBox(w.ctx, segs[ei].tail.info.rank!));
+    if (!smode) { sl = straightLen(segs[ei].head); if (sl >= thr) { smode = true; si = true; sl -= 2; } }
+    if (smode && !si) {
+      ei = closeSmodeSeg(w, segs, ei, sl, segFirst);
+      if (ei < 0) return null;
+      segFirst = ei; smode = false;
+      continue;
+    }
+    si = false;
+    w.boxes.push(maximalBbox(w.ctx, segs[ei].head, segs[ei], segs[ei + 1]));
+    ei++;
+  }
+  return finishChain(w, endEdge, segs[ei], segFirst, segs) ? w.pts : null;
+}
+
+/**
+ * Route a forward edge spanning ≥2 ranks via its virtual-node chain through the
+ * faithful pipeline (REGULAREDGE side boxes steer the port, routeSplines over
+ * the chain; adjustregularpath inter-rank widening finally fires). Returns
+ * control points in graphviz-internal y-up, or null when the edge is not a
+ * multi-rank chain.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag forward path)
+ */
+export function routeMultiRankEdgeFaithful(g: Graph, e: GraphEdge): Point[] | null {
+  const r = e.tail.info.rank;
+  const rh = e.head.info.rank;
+  if (g.info.rank === undefined || r === undefined || rh === undefined || rh <= r + 1) return null;
+  const et = edgeType(g);
+  // EDGETYPE_LINE: C tries makeLineEdge first (direct tail→head segment),
+  // falling back to the box corridor only when it declines (delr==1, or delr==2
+  // with edge labels). @see lib/dotgen/dotsplines.c:make_regular_edge (1757)
+  if (et === EDGETYPE_LINE) {
+    const line = makeLineEdge(g, e);
+    if (line !== null) return line;
+  }
+  const segs = chainSegments(e);
+  // Route only a COMPLETE chain (last segment reaches e.head). segs.length===1 is
+  // valid (concentrate may merge the whole chain to a direct tail->head segment);
+  // a chain ending at a virtual node is broken — bail, don't crash the loop.
+  // @see dotsplines.c:make_regular_edge
+  if (segs.length === 0 || segs[segs.length - 1].head !== e.head) return null;
+  // C's make_regular_edge drives beginpath with the FIRST chain fast edge and
+  // endpath with the LAST (each carries the orig's copied port, so a dyna
+  // record port resolves toward the adjacent-rank vnode, not the far real
+  // endpoint). @see lib/dotgen/dotsplines.c:make_regular_edge (tn/hn walk),
+  // lib/dotgen/fastgr.c:new_virtual_edge (port copies)
+  return routeChainSegmented(g, segs[0], segs[segs.length - 1], segs);
+}
+
+/**
+ * The merge-bounded run owned by one collected entry: the entry followed by
+ * `out.list[0]` successors while the head is a plain (non-merge) virtual node —
+ * C make_regular_edge's chain walk. Returns null when the entry is NOT a
+ * partial run (neither end at a splineMerge node): plain single-chain entries
+ * belong to the caller's whole-chain routers.
+ * @see lib/dotgen/dotsplines.c:make_regular_edge (while !splineMerge(hn) walk)
+ */
+function entryRunSegments(e: GraphEdge): GraphEdge[] | null {
+  const segs: GraphEdge[] = [e];
+  let hn = e.head;
+  while ((hn.info.node_type ?? NORMAL) === VIRTUAL && !splineMerge(hn)) {
+    const nxt = hn.info.out?.list[0];
+    if (nxt === undefined) return null; // broken chain — leave to the caller
+    segs.push(nxt);
+    hn = nxt.head;
+  }
+  if (!splineMerge(e.tail) && !splineMerge(hn)) return null;
+  return segs;
+}
+
+/**
+ * Route ONE collected entry's merge-bounded run — C's model where every
+ * fast-graph entry of a concentrate-merged chain (lead-in from the real node,
+ * trunk continuation out of a merge node, or a secondary's branch) is its own
+ * cnt=1 group (the group loop's MAINGRAPH break) and make_regular_edge walks
+ * from the entry to the first NORMAL or splineMerge node; clip_and_install
+ * then APPENDS the clipped bezier on the entry's original edge. The entry's
+ * own ports drive begin/endpath (the last segment carries the run's head
+ * port), and the install passes the ENTRY (its to_orig chain resolves the
+ * orig) with the walk's final head node, exactly as C.
+ *
+ * Returns the resolved original edge when the entry was a partial run
+ * (consumed — even if routing declined, so the caller never re-routes the
+ * whole chain), or null when the entry is a plain full chain.
+ * @see lib/dotgen/dotsplines.c:dot_splines_ (group loop), make_regular_edge
+ */
+export function routeEntryRun(g: Graph, entry: GraphEdge): GraphEdge | null {
+  const segs = entryRunSegments(entry);
+  if (segs === null) return null;
+  const last = segs[segs.length - 1];
+  const pts = routeChainSegmented(g, segs[0], last, segs);
+  if (pts !== null) clipAndInstall(entry, last.head, pts, pts.length, buildDotSinfo());
+  return resolveOrigEdge(entry);
+}
+
+/**
+ * After splining, reposition each chain virtual node into the routing box that
+ * contains it (boxes run high-y to low-y). Label vnodes are anchored to the
+ * box's right edge (center = box.ur.x + rw); plain vnodes are centred. This is
+ * what aligns a flat-adj aux label vnode onto its spline so the label lands at
+ * the dot position (DOT-12). @see lib/dotgen/dotsplines.c:recover_slack
+ */
+function resizeVnInBox(vn: Node, box: Box): void {
+  if (vn.info.label != null) resizeVn(vn, box.ll.x, box.ur.x, box.ur.x + vn.info.rw);
+  else resizeVn(vn, box.ll.x, (box.ll.x + box.ur.x) / 2, box.ur.x);
+}
+
+function recoverSlack(segs: GraphEdge[], P: Path): void {
+  let b = 0; // skip first rank box
+  for (let i = 0; i < segs.length; i++) {
+    const vn = segs[i].head;
+    if ((vn.info.node_type ?? NORMAL) !== VIRTUAL || splineMerge(vn)) break;
+    while (b < P.nbox && P.boxes[b].ll.y > vn.info.coord.y) b++;
+    if (b >= P.nbox) break;
+    if (P.boxes[b].ur.y >= vn.info.coord.y) resizeVnInBox(vn, P.boxes[b]);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Back-edge routing
+// @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag back-edge path)
+// ---------------------------------------------------------------------------
+
+/**
+ * Virtual-chain segments of a multi-rank back edge in low-rank → high-rank
+ * order (e.head → e.tail). `chainSegments` cannot be reused: it stops at
+ * e.head, which is the chain's START for a back edge.
+ */
+function backChainSegments(e: GraphEdge): GraphEdge[] {
+  const segs: GraphEdge[] = [];
+  let cur = e.info.to_virt;
+  while (cur !== undefined) {
+    segs.push(cur);
+    if (cur.head === e.tail) break;
+    cur = cur.head.info.out?.list[0];
+  }
+  return segs;
+}
+
+/**
+ * Forward view of any edge (C `makefwdedge`): tail/head swapped when the edge
+ * runs high→low rank (a back edge), fresh portless ends. `beginPath`/`endPath`
+ * read `e.tail`/`e.head`, so the chain must be driven by an edge that runs
+ * low→high rank. Sets `to_orig`/`edge_type=VIRTUAL` so `clipAndInstall`→
+ * `newSpline` installs the spline on the ORIGINAL edge (its `to_orig` loop) and
+ * the post-routing `swapSpline` pass reverses it back to tail→head. Shares
+ * `attrs`/`root`/`to_virt` with `e`. Consumed by T3 for parallel back-members.
+ * @see lib/dotgen/dotsplines.c:makefwdedge
+ * @see lib/common/splines.c:clip_and_install (to_orig install loop)
+ */
+export function makeFwdEdge(e: GraphEdge): GraphEdge {
+  const back = (e.head.info.rank ?? 0) < (e.tail.info.rank ?? 0);
+  const [tail, head] = back ? [e.head, e.tail] : [e.tail, e.head];
+  return {
+    ...e,
+    tail,
+    head,
+    info: {
+      ...e.info,
+      // C makefwdedge SWAPS the ports (does not strip them): a back edge keeps
+      // its corner ports across the forward view so make_regular_edge curls it
+      // (e.g. #241_0 aux back-edge clone sw/se → size 7). Stripping to an empty
+      // Center port straightened every port-bearing back edge (size 4).
+      // @see lib/dotgen/dotsplines.c:makefwdedge (ED_tail_port(new)=ED_head_port(old))
+      tail_port: e.info.head_port ?? makePort(),
+      head_port: e.info.tail_port ?? makePort(),
+      to_orig: e,
+      edge_type: VIRTUAL,
+    },
+  } as GraphEdge;
+}
+
+
+/**
+ * Route a multi-rank back-edge via its virtual node chain, mirroring C exactly:
+ * make_regular_edge routes the makefwdedge (forward) view, clip_and_install
+ * clips THAT forward spline, and the spline is reversed afterward (swapSpline).
+ *
+ * Clipping the forward (un-reversed) spline is load-bearing: bezier_clip bisects
+ * each node end from the same direction C does. The previous reverse-then-clip
+ * path clipped the head node as a tail (bisecting the degenerate spline from the
+ * opposite parameter end), landing the 0.5-tolerance crossing ~0.26-0.33 off
+ * (1644, dfa family). clipAndInstall resolves the spline onto `e` via the
+ * fwdEdge's to_orig and gates arrows by ED_dir, so this also drops the bespoke
+ * reverse/arrow code. @see lib/dotgen/dotsplines.c:make_regular_edge (hackflag)
+ */
+export function routeBackEdge(e: GraphEdge, _tailBox: NodeBox, _headBox: NodeBox, g: Graph): void {
+  const segs = backChainSegments(e);
+  if (segs.length < 2 || segs[segs.length - 1].head !== e.tail) return;
+  const fwdEdge = makeFwdEdge(e);
+  // C's make_regular_edge routes the collected FAST SEGMENT view: beginpath's
+  // edge head is the adjacent chain vnode, so a dyna record port resolves
+  // toward that vnode (closestSide), not the far real endpoint. Passing the
+  // whole-edge fwd view here resolved b15's reversed record-port edges toward
+  // the wrong compass side (In: 's' at field-bottom instead of C's 'w' at
+  // field-left). The segments carry the correctly-oriented copied ports
+  // (fastgr new_virtual_edge copy rules); fwdEdge remains the clip target so
+  // bezier_clip keeps the load-bearing forward direction (1644).
+  // @see lib/dotgen/dotsplines.c:make_regular_edge (segfirst/tn/hn walk)
+  const fwd = routeChainSegmented(g, segs[0], segs[segs.length - 1], segs);
+  if (fwd === null) return;
+  clipAndInstall(fwdEdge, fwdEdge.head, fwd, fwd.length, buildDotSinfo());
+  if (swapEndsP(e)) swapEdgeSpline(e);
+}