@knowvah/dot-engine 0.1.0

package/src/layout/dot/splines-flat-labeled.ts

@@ -0,0 +1,408 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * make_flat_labeled_edge — route a non-adjacent same-rank (flat) edge that
+ * carries a center label, around the label virtual node created by flat_node
+ * (flat.ts:flatNode, T1). Sets the label position and installs the spline.
+ *
+ * Split out of splines-flat.ts (which is at the file-size cap) and reuses its
+ * makeFlatEndBox / flatBboxCtx / freshFlatPath helpers. Dispatched from the
+ * live router (edge-route.ts:routeForwardEdge) — see decisions.md#ad-3.
+ *
+ * @see lib/dotgen/dotsplines.c:make_flat_labeled_edge
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Edge } from '../../model/edge.js';
+import type { Node } from '../../model/node.js';
+import type { Box, Point } from '../../model/geom.js';
+import { makeFlatEndBox, flatBboxCtx, freshFlatPath } from './splines-flat.js';
+import { graphRanksep } from './position-aux.js';
+import { addBox } from '../../common/splines-path-shared.js';
+import { routeSplines, routePolylines } from '../../common/splines-routespl.js';
+import { clipAndInstall } from '../../common/splines-clip.js';
+import { buildDotSinfo } from './self-loop.js';
+import { TOP } from '../../common/splines-constants.js';
+import { edgeType, EDGETYPE_LINE, EDGETYPE_SPLINE, EDGETYPE_PLINE, getMainEdge, swapEndsP, swapEdgeSpline } from './splines.js';
+import { shortestPath, routeSpline, polyBarriers, makePolyline } from '../../pathplan/index.js';
+import { gvQsort } from '../../util/bsd-qsort.js';
+
+/** Space between stacked flat labels, in points. @see lib/dotgen/dotsplines.c:937 */
+const LBL_SPACE = 6;
+
+/**
+ * Walk `ED_to_virt(e)` to the end of the chain; the tail of the last edge is the
+ * label virtual node `ln`. @see lib/dotgen/dotsplines.c:make_flat_labeled_edge 1328-1330
+ */
+export function findLabelNode(e: Edge): Node | null {
+  let f = e.info.to_virt;
+  if (f === undefined) return null;
+  while (f.info.to_virt !== undefined) f = f.info.to_virt;
+  return f.tail;
+}
+
+/**
+ * The label box `lb` straddling the label node, with the C `ydelta`/6 clamp.
+ * @see lib/dotgen/dotsplines.c:make_flat_labeled_edge 1349-1355
+ */
+export function flatLabelBox(g: Graph, ln: Node, tn: Node): Box {
+  const rk = g.info.rank![tn.info.rank!];
+  const ydelta = (ln.info.coord.y - rk.ht1 - tn.info.coord.y + rk.ht2) / 6;
+  const ury = ln.info.coord.y + ln.info.ht / 2;
+  return {
+    ll: { x: ln.info.coord.x - ln.info.lw, y: ury - Math.max(5, ydelta) },
+    ur: { x: ln.info.coord.x + ln.info.rw, y: ury },
+  };
+}
+
+/**
+ * The three connector boxes between the tail end, label box, and head end.
+ * @see lib/dotgen/dotsplines.c:make_flat_labeled_edge 1360-1393
+ */
+export function flatLabeledBoxes(tlast: Box, hlast: Box, lb: Box): Box[] {
+  return [
+    { ll: { x: tlast.ll.x, y: tlast.ur.y }, ur: { x: lb.ll.x, y: lb.ll.y } },
+    { ll: { x: tlast.ll.x, y: lb.ll.y }, ur: { x: hlast.ur.x, y: lb.ur.y } },
+    { ll: { x: lb.ur.x, y: hlast.ur.y }, ur: { x: hlast.ur.x, y: lb.ll.y } },
+  ];
+}
+
+/**
+ * EDGETYPE_LINE 7-point polyline: start, label (lowered by half label height),
+ * end. @see lib/dotgen/dotsplines.c:make_flat_labeled_edge 1335-1347
+ */
+export function flatLabeledLinePoints(tn: Node, hn: Node, e: Edge): Point[] {
+  const lbl = e.info.label!;
+  const sx = tn.info.coord.x + e.info.tail_port.p.x;
+  const sy = tn.info.coord.y + e.info.tail_port.p.y;
+  const ex = hn.info.coord.x + e.info.head_port.p.x;
+  const ey = hn.info.coord.y + e.info.head_port.p.y;
+  const lx = lbl.pos.x;
+  const ly = lbl.pos.y - lbl.dimen.y / 2;
+  return [
+    { x: sx, y: sy }, { x: sx, y: sy },
+    { x: lx, y: ly }, { x: lx, y: ly }, { x: lx, y: ly },
+    { x: ex, y: ey }, { x: ex, y: ey },
+  ];
+}
+
+/**
+ * Build the tail/label/head box channel and route a spline (or polyline)
+ * through it. @see lib/dotgen/dotsplines.c:make_flat_labeled_edge 1349-1411
+ */
+export function routeFlatLabeledChannel(g: Graph, e: Edge, ln: Node, et: number): Point[] | null {
+  const tn = e.tail, hn = e.head;
+  const lb = flatLabelBox(g, ln, tn);
+  const ctx = flatBboxCtx(g);
+  const ranksep = graphRanksep(g);
+  const P = freshFlatPath();
+  const tend = makeFlatEndBox({ ctx, P, e, n: tn, side: TOP, ranksep, isBegin: true });
+  const hend = makeFlatEndBox({ ctx, P, e, n: hn, side: TOP, ranksep, isBegin: false });
+  const boxes = flatLabeledBoxes(tend.boxes[tend.boxn - 1], hend.boxes[hend.boxn - 1], lb);
+  for (let i = 0; i < tend.boxn; i++) addBox(P, tend.boxes[i]);
+  for (const b of boxes) addBox(P, b);
+  for (let i = hend.boxn - 1; i >= 0; i--) addBox(P, hend.boxes[i]);
+  return et === EDGETYPE_SPLINE ? routeSplines(P) : routePolylines(P);
+}
+
+/**
+ * Decline unless `e` is a non-adjacent, same-rank, labeled flat edge with a
+ * label vnode reachable via its to_virt chain; otherwise return that vnode.
+ */
+export function flatLabelTarget(e: Edge): Node | null {
+  if (e.info.label === undefined || (e.info.adjacent ?? 0) !== 0) return null;
+  if (e.tail.info.rank === undefined || e.tail.info.rank !== e.head.info.rank) return null;
+  return findLabelNode(e);
+}
+
+/**
+ * Route a non-adjacent labeled flat edge around its label vnode and install the
+ * spline. Sets `ED_label(e).pos` / `.set` so the label `<text>` is emitted.
+ * Returns false (declining) when `e` is not such an edge so the caller falls
+ * back to its normal routing. @see lib/dotgen/dotsplines.c:make_flat_labeled_edge
+ */
+export function makeFlatLabeledEdge(g: Graph, e: Edge): boolean {
+  const ln = flatLabelTarget(e);
+  if (ln === null) return false;
+  const lbl = e.info.label!;
+  lbl.pos = { x: ln.info.coord.x, y: ln.info.coord.y };
+  lbl.set = true;
+  const et = edgeType(g);
+  if (et === EDGETYPE_LINE) {
+    const ps = flatLabeledLinePoints(e.tail, e.head, e);
+    if (ps !== null && ps.length !== 0) clipAndInstall(e, e.head, ps, ps.length, buildDotSinfo());
+    return true;
+  }
+  // C make_flat_edge forward-normalizes a backward (tail right of head by node
+  // ORDER) flat edge via makefwdedge BEFORE make_flat_labeled_edge builds the
+  // left→right channel — else the middle box inverts (LL.x > UR.x) and
+  // routesplines returns no points. Build the channel on a left→right sample,
+  // then reverse the points for an edge whose tail is the right node so they run
+  // tail→head, and install with ignoreSwap (the orientation is already fixed).
+  // @see lib/dotgen/dotsplines.c:make_flat_edge (makefwdedge), make_flat_labeled_edge
+  const tailIsLeft = (e.tail.info.order ?? 0) <= (e.head.info.order ?? 0);
+  const sample: Edge = tailIsLeft ? e : {
+    ...e, tail: e.head, head: e.tail,
+    info: { ...e.info, tail_port: e.info.head_port, head_port: e.info.tail_port },
+  } as Edge;
+  const ps = routeFlatLabeledChannel(g, sample, ln, et);
+  // Degenerate route (routesplines pn=0): label set, no spline installed — C's
+  // make_flat_labeled_edge returns the same way; emit's edge_in_box then decides
+  // whether the (untranslated) label overlaps the clip. Still HANDLED → true.
+  if (ps === null || ps.length === 0) return true;
+  if (!tailIsLeft) ps.reverse();
+  clipAndInstall(e, e.head, ps, ps.length, { ...buildDotSinfo(), ignoreSwap: true });
+  return true;
+}
+
+/**
+ * True when `e` is an adjacent, same-rank flat edge with no declared ports —
+ * C's make_flat_adj_edges no-port dispatch (makeSimpleFlat / makeSimpleFlatLabels).
+ * Port-bearing adjacent flats route via the rotated aux graph instead.
+ *
+ * `adjacent` is read from the flat representative — the end of the `to_virt`
+ * chain — not from `e` directly. C's `dot_splines_` routes the `flat_out`/`other`
+ * edge that `checkFlatAdjacent` marked; the port instead routes the cgraph
+ * out-edge, which for a nonconstraint cross-cluster flat (e.g. 258 `B->D`) is a
+ * *different* object linked to the marked representative through `to_virt`
+ * (R -> v -> M, with `adjacent` set on M). Following the chain reunites the
+ * routed edge with its flag. For an ordinary adjacent flat the chain is empty,
+ * so the rep is `e` itself. @see lib/dotgen/dotsplines.c:dot_splines_ (flat gather)
+ */
+export function isAdjFlatCandidate(e: Edge): boolean {
+  if (e.tail.info.rank === undefined || e.tail.info.rank !== e.head.info.rank) return false;
+  if (e.info.tail_port.defined || e.info.head_port.defined) return false;
+  // Resolve `adjacent` from the flat representative (to_virt chain end) ONLY
+  // when it is the SAME logical edge (same unordered endpoint pair). C's
+  // dot_splines_ routes the flat_out/other edge that carries the flag; the
+  // port routes the cgraph out-edge, which for a nonconstraint cross-cluster
+  // flat (258 B->D) reaches its marked rep through to_virt. The same-pair
+  // guard prevents inheriting an UNRELATED edge's adjacency on dense graphs
+  // (which would mis-route many edges through makeSimpleFlat). @see dotsplines.c
+  let rep = e;
+  while (rep.info.to_virt !== undefined && rep.info.to_virt !== rep) rep = rep.info.to_virt;
+  const samePair = (rep.tail === e.tail && rep.head === e.head)
+    || (rep.tail === e.head && rep.head === e.tail);
+  const adj = samePair ? rep.info.adjacent : e.info.adjacent;
+  return (adj ?? 0) !== 0;
+}
+
+/**
+ * Group: every no-port adjacent flat edge between e's two endpoints, in BOTH
+ * directions (the UNORDERED {tail,head} set). C's make_flat_adj_edges groups by
+ * the unordered pair — opposing legs (a->b and b->a) and parallel siblings route
+ * as one call (dotsplines.c:1122; the dispatch loop's "all flat adjacent edges
+ * at once" at dotsplines.c:357). Keying on the ordered (tail,head) split the
+ * opposing leg into its own cnt=1 group, drawn straight instead of as the
+ * earray[1] arc. @see lib/dotgen/flat.c:flat_edges (ND_other)
+ */
+export function collectAdjFlatGroup(g: Graph, e: Edge): Edge[] {
+  const me = getMainEdge(e);
+  const out: Edge[] = [];
+  for (const f of g.edges) {
+    const samePair = (f.tail === e.tail && f.head === e.head)
+      || (f.tail === e.head && f.head === e.tail);
+    if (samePair && isAdjFlatCandidate(f) && getMainEdge(f) === me) out.push(f);
+  }
+  return out;
+}
+
+/**
+ * The group's tail/head, oriented left→right by node order. C's
+ * make_flat_adj_edges takes tn/hn from the forward-normalized representative
+ * (makefwdedge makes the lower-order node the tail); every routing point is
+ * built tp(tn)→hp(hn) and clip_and_install re-orients each reversed leg.
+ * @see lib/dotgen/dotsplines.c:make_flat_adj_edges 1136
+ */
+function groupTnHn(group: Edge[]): { tn: Node; hn: Node } {
+  const a = group[0].tail, b = group[0].head;
+  return (a.info.order ?? 0) <= (b.info.order ?? 0) ? { tn: a, hn: b } : { tn: b, hn: a };
+}
+
+/** edgelblcmpfn: labeled first; among labeled, larger dimen (x then y) first. */
+export function edgeLblCmp(a: Edge, b: Edge): number {
+  const la = a.info.label, lb = b.info.label;
+  if (la === undefined) return lb === undefined ? 0 : 1;
+  if (lb === undefined) return -1;
+  if (la.dimen.x !== lb.dimen.x) return la.dimen.x > lb.dimen.x ? -1 : 1;
+  if (la.dimen.y !== lb.dimen.y) return la.dimen.y > lb.dimen.y ? -1 : 1;
+  return 0;
+}
+
+/** Pshortestpath → (make_polyline | Proutespline) over an 8-point boundary poly.
+ *  @see lib/common/routespl.c:simpleSplineRoute */
+function simpleSplineRoute(tp: Point, hp: Point, polyPts: Point[], polyline: boolean): Point[] | null {
+  const route = shortestPath({ ps: polyPts }, [tp, hp]);
+  if (route === null) return null;
+  if (polyline) return makePolyline(route);
+  return routeSpline(polyBarriers([{ ps: polyPts }]), route, [{ x: 0, y: 0 }, { x: 0, y: 0 }]);
+}
+
+/** Running bounds + fixed endpoints for the stacked flat-label boxes. */
+interface FlatStack {
+  miny: number; maxy: number; uminx: number; umaxx: number;
+  lminx: number; lmaxx: number; leftend: number; rightend: number; ctrx: number;
+  tp: Point; hp: Point; tn: Node;
+}
+
+/** Boundary poly for a flat edge routed BELOW the rank (i odd). @see dotsplines.c:1003-1010 */
+function flatDownBox(tp: Point, hp: Point, miny: number, lminx: number, lmaxx: number): Point[] {
+  return [
+    { x: tp.x, y: tp.y }, { x: tp.x, y: miny - LBL_SPACE }, { x: hp.x, y: miny - LBL_SPACE },
+    { x: hp.x, y: hp.y }, { x: lmaxx, y: hp.y }, { x: lmaxx, y: miny },
+    { x: lminx, y: miny }, { x: lminx, y: tp.y },
+  ];
+}
+
+/** Boundary poly for a flat edge routed ABOVE the rank (i even). @see dotsplines.c:1012-1020 */
+function flatUpBox(tp: Point, hp: Point, maxy: number, uminx: number, umaxx: number): Point[] {
+  return [
+    { x: tp.x, y: tp.y }, { x: uminx, y: tp.y }, { x: uminx, y: maxy }, { x: umaxx, y: maxy },
+    { x: umaxx, y: hp.y }, { x: hp.x, y: hp.y }, { x: hp.x, y: maxy + LBL_SPACE },
+    { x: tp.x, y: maxy + LBL_SPACE },
+  ];
+}
+
+/** Box + label-center for stacked edge i (down if odd, up if even); mutates bounds. */
+function stackFlatBox(st: FlatStack, i: number, dim: Point, labeled: boolean): { box: Point[]; ctry: number } {
+  if (i % 2 === 1) {
+    if (i === 1 && labeled) { st.lminx = st.ctrx - dim.x / 2; st.lmaxx = st.ctrx + dim.x / 2; }
+    if (i === 1 && !labeled) { st.lminx = (2 * st.leftend + st.rightend) / 3; st.lmaxx = (st.leftend + 2 * st.rightend) / 3; }
+    st.miny -= LBL_SPACE + dim.y;
+    return { box: flatDownBox(st.tp, st.hp, st.miny, st.lminx, st.lmaxx), ctry: st.miny + dim.y / 2 };
+  }
+  const box = flatUpBox(st.tp, st.hp, st.maxy, st.uminx, st.umaxx);
+  const ctry = st.maxy + dim.y / 2 + LBL_SPACE;
+  st.maxy += dim.y + LBL_SPACE;
+  return { box, ctry };
+}
+
+/** Set an edge label position. */
+function setFlatLabel(e: Edge, x: number, y: number): void {
+  const lbl = e.info.label!;
+  lbl.pos = { x, y };
+  lbl.set = true;
+}
+
+/**
+ * Install one flat leg. Points are always built left→right (tn→hn). For a leg
+ * whose tail is the RIGHT node (e.tail !== tn) the stored spline must run
+ * tail→head (right→left), so reverse the points and install with ignoreSwap
+ * (orientation already fixed). C's clip_and_install reverses such reversed flat
+ * legs internally; the port stores points verbatim, so the caller reverses —
+ * the same idiom makeFlatLabeledEdge uses (tailIsLeft + reverse + ignoreSwap).
+ */
+function installFlatLeg(e: Edge, pts: Point[], _tn: Node): void {
+  // C makeSimpleFlat installs the tn->hn points FORWARD via
+  // `clip_and_install(e, aghead(e), points)`, letting clip_and_install swap
+  // tn/hn for a reversed flat edge (splines.c:252); the resulting spline is then
+  // emitted in the original tail->head direction (makefwdedge un-normalization).
+  // Clipping the FORWARD spline is load-bearing: bezier_clip's 0.5-tolerance
+  // bisection is direction-dependent, so clipping a PRE-reversed spline converged
+  // ~0.35px off C (pgram PP->OCT). So clip forward, then swap the spline back —
+  // exactly the regular back-edge pattern (edge-route-chain.ts:412).
+  // @see lib/dotgen/dotsplines.c:makeSimpleFlat, lib/common/splines.c:clip_and_install
+  clipAndInstall(e, e.head, pts, pts.length, buildDotSinfo());
+  if (swapEndsP(e)) swapEdgeSpline(e);
+}
+
+/** Route the stacked (i>=1) edges of the group through simpleSplineRoute. */
+function routeStackedFlats(earray: Edge[], nLbls: number, st: FlatStack, et: number): void {
+  for (let i = 1; i < earray.length; i++) {
+    const labeled = i < nLbls;
+    const dim = labeled ? earray[i].info.label!.dimen : { x: 0, y: 0 };
+    const { box, ctry } = stackFlatBox(st, i, dim, labeled);
+    const ps = simpleSplineRoute(st.tp, st.hp, box, et === EDGETYPE_PLINE);
+    if (ps === null || ps.length === 0) return;
+    if (labeled) setFlatLabel(earray[i], st.ctrx, ctry);
+    installFlatLeg(earray[i], ps, st.tn);
+  }
+}
+
+/**
+ * Route a parallel group of adjacent (no-port) flat edges: the first goes
+ * straight with its label above; the rest stack up/down around the rank, each
+ * routed via simpleSplineRoute. @see lib/dotgen/dotsplines.c:makeSimpleFlatLabels
+ */
+export function makeSimpleFlatLabels(group: Edge[], et: number): void {
+  // C qsort(earray, edgelblcmpfn) — UNSTABLE; edgelblcmpfn returns 0 when two
+  // edges' labels have equal dimensions, so the tie order is qsort's, not
+  // insertion order. @see util/bsd-qsort.ts · dotsplines.c:make_flat_labeled_edge
+  const earray = gvQsort([...group], edgeLblCmp);
+  // tn/hn are the group's left/right nodes (C: agtail/aghead of the
+  // forward-normalized rep), NOT earray[0]'s own direction — earray[0] (widest
+  // label) may run right->left. Every routing point is built tn->hn; the
+  // per-edge clip_and_install auto-swap (swapEndsP) re-orients each reversed leg.
+  const { tn, hn } = groupTnHn(group);
+  const e0 = earray[0];
+  const tp = { x: tn.info.coord.x + e0.info.tail_port.p.x, y: tn.info.coord.y + e0.info.tail_port.p.y };
+  const hp = { x: hn.info.coord.x + e0.info.head_port.p.x, y: hn.info.coord.y + e0.info.head_port.p.y };
+  const leftend = tp.x + tn.info.rw, rightend = hp.x - hn.info.lw;
+  const ctrx = (leftend + rightend) / 2;
+  const nLbls = earray.filter(e => e.info.label !== undefined).length;
+  const dim0 = e0.info.label!.dimen;
+  installFlatLeg(e0, [tp, { ...tp }, hp, { ...hp }], tn);
+  setFlatLabel(e0, ctrx, tp.y + (dim0.y + LBL_SPACE) / 2);
+  const st: FlatStack = {
+    miny: tp.y + LBL_SPACE / 2, maxy: tp.y + LBL_SPACE / 2 + dim0.y,
+    uminx: ctrx - dim0.x / 2, umaxx: ctrx + dim0.x / 2,
+    lminx: 0, lmaxx: 0, leftend, rightend, ctrx, tp, hp, tn,
+  };
+  routeStackedFlats(earray, nLbls, st, et);
+}
+
+/** Bezier (SPLINE/LINE) or polyline (PLINE) control points for one flat
+ *  spindle edge at vertical height dy. @see dotsplines.c:makeSimpleFlat 1089-1106 */
+function simpleFlatPoints(tp: Point, hp: Point, dy: number, et: number): Point[] {
+  const a = (2 * tp.x + hp.x) / 3, b = (2 * hp.x + tp.x) / 3;
+  if (et === EDGETYPE_SPLINE || et === EDGETYPE_LINE) {
+    return [{ x: tp.x, y: tp.y }, { x: a, y: dy }, { x: b, y: dy }, { x: hp.x, y: hp.y }];
+  }
+  return [
+    { x: tp.x, y: tp.y }, { x: tp.x, y: tp.y },
+    { x: a, y: dy }, { x: a, y: dy }, { x: a, y: dy },
+    { x: b, y: dy }, { x: b, y: dy }, { x: b, y: dy },
+    { x: hp.x, y: hp.y }, { x: hp.x, y: hp.y },
+  ];
+}
+
+/**
+ * Spindle of splines for a no-port, no-label adjacent flat group: fan the cnt
+ * edges vertically across the tail node's height (stepy = ht/(cnt-1), centred
+ * on tp.y). cnt == 1 yields a single straight line.
+ * @see lib/dotgen/dotsplines.c:makeSimpleFlat (1075)
+ */
+export function makeSimpleFlat(group: Edge[], et: number): void {
+  const e0 = group[0];
+  const { tn, hn } = groupTnHn(group);
+  const tp = { x: tn.info.coord.x + e0.info.tail_port.p.x, y: tn.info.coord.y + e0.info.tail_port.p.y };
+  const hp = { x: hn.info.coord.x + e0.info.head_port.p.x, y: hn.info.coord.y + e0.info.head_port.p.y };
+  const cnt = group.length;
+  const stepy = cnt > 1 ? tn.info.ht / (cnt - 1) : 0;
+  let dy = tp.y - (cnt > 1 ? tn.info.ht / 2 : 0);
+  for (let i = 0; i < cnt; i++) {
+    const pts = simpleFlatPoints(tp, hp, dy, et);
+    dy += stepy;
+    installFlatLeg(group[i], pts, tn);
+  }
+}
+
+/**
+ * Dispatch an adjacent no-port flat edge group (C's `make_flat_adj_edges`
+ * no-port branch): a group with any label routes via makeSimpleFlatLabels, a
+ * group with none via makeSimpleFlat. Both route the whole parallel group at
+ * once. Declines only when `e` is not a no-port adjacent flat.
+ * @see lib/dotgen/dotsplines.c:make_flat_adj_edges 1156-1166
+ */
+export function makeAdjFlatNoPortEdge(g: Graph, e: Edge): boolean {
+  if (!isAdjFlatCandidate(e)) return false;
+  // The group is rendered as a unit (both directions). When the opposing leg is
+  // dispatched later it is already installed — skip re-rendering but report it
+  // handled. C does the whole unordered group in one make_flat_adj_edges call.
+  if (e.info.spl !== undefined) return true;
+  const group = collectAdjFlatGroup(g, e);
+  const et = edgeType(g);
+  if (group.some(x => x.info.label !== undefined)) makeSimpleFlatLabels(group, et);
+  else makeSimpleFlat(group, et);
+  return true;
+}

package/src/layout/dot/splines-flat-multi.ts

@@ -0,0 +1,188 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Faithful cnt>=2 non-adjacent flat multi-edge routing.
+ *
+ * C make_flat_edge (top branch, dotsplines.c:1502) and make_flat_bottom_edges
+ * (bottom branch, 1418) group every non-labeled, identical-port, non-adjacent
+ * flat edge between a same-rank node pair into ONE call and NEST their splines:
+ * `stepx = Multisep/(cnt+1)`, `stepy = vspace/(cnt+1)`; ONE shared makeFlatEnd
+ * tail+head; then edge `i` is offset by `(i+1)*step` on the two END boxes while
+ * the MIDDLE box keeps plain `stepy`. cnt=1 reduces to routeFlatEdgeFaithful
+ * (`Multisep/2 = nodesep/2`, `(0+1)*step = step`) — identical (AD-1).
+ *
+ * The port routes each non-adjacent flat independently at `nodesep/2`, so cnt>=2
+ * edges come out identical/overlapping; this module restores the nesting.
+ *
+ * @see lib/dotgen/dotsplines.c:make_flat_edge, make_flat_bottom_edges, dot_splines_
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Edge } from '../../model/edge.js';
+import type { Node } from '../../model/node.js';
+import type { Port, Box } from '../../model/geom.js';
+import type { Path, PathendT } from '../../common/types.js';
+import { routeSplines } from '../../common/splines-routespl.js';
+import { clipAndInstall } from '../../common/splines-clip.js';
+import { graphRanksep } from './position-aux.js';
+import { buildDotSinfo } from './self-loop.js';
+import {
+  isFlatAdjacent, makeFlatEndBox, topBoxes, bottomBoxes, flatSide, flatVspace,
+  freshFlatPath, assembleFlatPath, flatBboxCtx,
+} from './splines-flat.js';
+
+/** Loop-invariant routing context shared across the cnt-loop iterations.
+ * Declared here (not between functions) so lizard's length accounting does not
+ * fold it into a neighbour. @see lizard-length-inter-comment */
+interface GroupRouteCtx {
+  P: Path;
+  tend: PathendT;
+  hend: PathendT;
+  tlast: Box;
+  hlast: Box;
+  bottom: boolean;
+  stepx: number;
+  stepy: number;
+  /** Geometric left end node of the channel (lower order). routeSplines yields
+   * points left→right; an edge whose tail is the RIGHT node is reversed so the
+   * installed spline runs tail→head, matching C's clip_and_install orientation. */
+  leftNode: Node;
+}
+
+
+/**
+ * portcmp == 0: both undefined, or both defined with an equal aiming point.
+ * @see lib/dotgen/dotsplines.c:portcmp
+ */
+function portEq(a: Port, b: Port): boolean {
+  if (!a.defined && !b.defined) return true;
+  if (!a.defined || !b.defined) return false;
+  return a.p.x === b.p.x && a.p.y === b.p.y;
+}
+
+/** The declared ports of e oriented relative to the left node `lo`. */
+function flatPortKey(e: Edge, lo: Node): { loP: Port; hiP: Port } {
+  return e.tail === lo
+    ? { loP: e.info.tail_port, hiP: e.info.head_port }
+    : { loP: e.info.head_port, hiP: e.info.tail_port };
+}
+
+/** True when x is an unrouted non-adjacent same-rank flat edge (C make_flat_edge
+ * routes EVERY non-adjacent flat; side ports are not a precondition). */
+function isNonAdjGroupable(x: Edge, g: Graph): boolean {
+  return x.info.spl === undefined
+    && x.tail.info.rank !== undefined
+    && x.tail.info.rank === x.head.info.rank
+    && !isFlatAdjacent(g, x);
+}
+
+/** True when x's ports (oriented to lo) equal the lead key (C portcmp == 0). */
+function samePortsAs(x: Edge, lo: Node, key: { loP: Port; hiP: Port }): boolean {
+  const k = flatPortKey(x, lo);
+  return portEq(k.loP, key.loP) && portEq(k.hiP, key.hiP);
+}
+
+/**
+ * Collect all unrouted non-adjacent same-rank side-port flat edges between e's
+ * endpoints that share e's tail/head ports (C portcmp), ordered so group[0].tail
+ * is the lower-order (left) node, ties by seq (AD-3). Mirrors edge-route.ts:
+ * collectAdjacentFlatGroup with the non-adjacent + identical-port group key.
+ * @see lib/dotgen/dotsplines.c:dot_splines_ (portcmp 370-373), make_flat_edge
+ */
+export function collectNonAdjacentFlatGroup(e: Edge, g: Graph): Edge[] {
+  const u = e.tail, v = e.head;
+  const lo = (u.info.order ?? 0) <= (v.info.order ?? 0) ? u : v;
+  const key = flatPortKey(e, lo);
+  const sharesPair = (x: Edge): boolean =>
+    (x.tail === u && x.head === v) || (x.tail === v && x.head === u);
+  // C's edgecmp keeps a flat group contiguous only while labels are equal
+  // (ED_label(e0)!=ED_label(e1) breaks the run); a labeled opposing leg must not
+  // be pulled into an unlabeled rep's group. @see lib/dotgen/dotsplines.c:edgecmp
+  const group = g.edges.filter(
+    x => sharesPair(x) && isNonAdjGroupable(x, g) && samePortsAs(x, lo, key)
+      && x.info.label === e.info.label);
+  group.sort((a, b) => Number(b.tail === lo) - Number(a.tail === lo) || a.seq - b.seq);
+  return group;
+}
+
+/**
+ * Deep-copy a pathend's boxes so routeSplines (which mutates boxes in place)
+ * cannot corrupt the shared tend/hend reused across the cnt-loop. C copies each
+ * box by value via add_box; the port stores references, so the loop must copy.
+ * @see lib/common/routespl.c:routesplines (mutates boxes), add_box (value copy)
+ */
+function copyPathEnd(end: PathendT): PathendT {
+  return {
+    ...end,
+    boxes: end.boxes.map(b => ({ ll: { ...b.ll }, ur: { ...b.ur } })),
+  };
+}
+
+/**
+ * Build edge i's three connecting boxes (END boxes offset (i+1)*step, MIDDLE
+ * plain stepy), assemble the path, route, and clip+install on e. Resets P.nbox
+ * first (C: `P->nbox = 0` per iteration). Returns false on an empty route.
+ * @see lib/dotgen/dotsplines.c:make_flat_edge / make_flat_bottom_edges (loop body)
+ */
+function routeGroupEdge(e: Edge, i: number, c: GroupRouteCtx): boolean {
+  c.P.nbox = 0;
+  const endStepX = (i + 1) * c.stepx;
+  const endStepY = (i + 1) * c.stepy;
+  const mid = c.bottom
+    ? bottomBoxes(c.tlast, c.hlast, endStepX, endStepY, c.stepy)
+    : topBoxes(c.tlast, c.hlast, endStepX, endStepY, c.stepy);
+  assembleFlatPath(c.P, copyPathEnd(c.tend), copyPathEnd(c.hend), mid);
+  const pts = routeSplines(c.P);
+  if (pts === null || pts.length === 0) return false;
+  // routeSplines returns points left→right (tend = leftNode). Reverse for an edge
+  // whose tail is the right node so the points run tail→head; pass ignoreSwap so
+  // clipAndInstall clips/arrows by the real tail/head instead of re-deriving the
+  // orientation from node order (which would undo the reversal).
+  // @see lib/dotgen/dotsplines.c:make_flat_edge (clip_and_install)
+  if (e.tail !== c.leftNode) pts.reverse();
+  clipAndInstall(e, e.head, pts, pts.length, { ...buildDotSinfo(), ignoreSwap: true });
+  return true;
+}
+
+/**
+ * Faithful make_flat_edge / make_flat_bottom_edges cnt-loop: ONE shared
+ * makeFlatEnd tail+head; for i in 0..cnt-1 route edge i nested by (i+1)*step.
+ * Installs spl on every edges[i]; returns true iff all installed. cnt=1 reduces
+ * to routeFlatEdgeFaithful (AD-1). `edges` must be group-ordered (collect...).
+ * @see lib/dotgen/dotsplines.c:make_flat_edge, make_flat_bottom_edges
+ */
+export function routeFlatEdgeGroupFaithful(g: Graph, edges: Edge[], cnt: number): boolean {
+  const lead = edges[0];
+  if (g.info.rank === undefined || lead.tail.info.rank === undefined
+    || lead.head.info.rank !== lead.tail.info.rank) return false;
+  // C makefwdedge: build the channel left→right by node order, else the middle
+  // box inverts for a right-to-left (tail right of head) flat edge.
+  const tailIsLeft = (lead.tail.info.order ?? 0) <= (lead.head.info.order ?? 0);
+  const leftNode = tailIsLeft ? lead.tail : lead.head;
+  const rightNode = tailIsLeft ? lead.head : lead.tail;
+  // C makefwdedge: the box-building sample edge must run left→right so beginpath
+  // anchors the path START at the LEFT node (not the original tail). For a
+  // right-to-left flat edge, swap tail/head + ports for the sample only; the
+  // per-edge clip/install still uses the original edge.
+  // @see lib/dotgen/dotsplines.c:make_flat_edge (makefwdedge), makefwdedge
+  const sample: Edge = tailIsLeft ? lead : {
+    ...lead, tail: leftNode, head: rightNode,
+    info: { ...lead.info, tail_port: lead.info.head_port, head_port: lead.info.tail_port },
+  } as Edge;
+  const { bottom, side } = flatSide(sample);
+  const ctx = flatBboxCtx(g);
+  const ranksep = graphRanksep(g);
+  const P = freshFlatPath();
+  const tend = makeFlatEndBox({ ctx, P, e: sample, n: leftNode, side, ranksep, isBegin: true });
+  const hend = makeFlatEndBox({ ctx, P, e: sample, n: rightNode, side, ranksep, isBegin: false });
+  const stepx = (g.info.nodesep ?? 18) / (cnt + 1);
+  const stepy = flatVspace(g, leftNode, !bottom) / (cnt + 1);
+  const rc: GroupRouteCtx = {
+    P, tend, hend, tlast: tend.boxes[tend.boxn - 1], hlast: hend.boxes[hend.boxn - 1],
+    bottom, stepx, stepy, leftNode,
+  };
+  for (let i = 0; i < cnt; i++) {
+    if (!routeGroupEdge(edges[i], i, rc)) return false;
+  }
+  return true;
+}