@knowvah/dot-engine 0.1.0

package/src/layout/dot/sameport.ts

@@ -0,0 +1,278 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * TypeScript port of lib/dotgen/sameport.c — dot_sameports.
+ *
+ * Merges edges with specified samehead/sametail attributes onto the same port.
+ *
+ * @see lib/dotgen/sameport.c
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { Point, Port } from '../../model/geom.js';
+import { VIRTUAL, MC_SCALE } from './fastgr.js';
+import { nodeBoxOf } from './edge-route-helpers.js';
+import { bezierClipNode } from './edge-route-clip.js';
+import { nodeInsideFn } from './edge-route-routing.js';
+import { nodesInSeq } from './decomp.js';
+import { cround } from '../../common/arith.js';
+
+// ---------------------------------------------------------------------------
+// ARR_LEN — distance from node boundary for arr_port
+// @see lib/common/const.h
+// ---------------------------------------------------------------------------
+
+/** @see lib/common/const.h:ARR_LEN (approximate — actual value depends on arrow rendering) */
+export const ARR_LEN = 10;
+
+// ---------------------------------------------------------------------------
+// same_t / same_list — grouping structures
+// @see lib/dotgen/sameport.c
+// ---------------------------------------------------------------------------
+
+/** A group of edges sharing the same samehead/sametail id at a node. */
+export interface SameGroup {
+  id: string;
+  edges: Edge[];
+}
+
+// ---------------------------------------------------------------------------
+// sameedge — register edge in a group
+// @see lib/dotgen/sameport.c:sameedge
+// ---------------------------------------------------------------------------
+
+/** @see lib/dotgen/sameport.c:sameedge */
+export function sameedge(same: SameGroup[], e: Edge, id: string): void {
+  for (const grp of same) {
+    if (grp.id === id) { grp.edges.push(e); return; }
+  }
+  same.push({ id, edges: [e] });
+}
+
+// ---------------------------------------------------------------------------
+// shapeClip — move curve[0] to the node boundary
+// @see lib/dotgen/sameport.c — calls shape_clip(u, curve)
+// ---------------------------------------------------------------------------
+
+/**
+ * Move curve[0] to node u's shape boundary along the Bézier, exactly as C's
+ * shape_clip: build the node's shape inside-function (ellipse vs polygon, pen-
+ * width aware) and bezier-clip with left_inside = insidefn(curve[0]). curve[0]
+ * is the node center, which is always inside, so left_inside is true.
+ *
+ * Replaces an earlier rectangle approximation, which was wrong for ellipse
+ * nodes (every honda head is an ellipse) and shifted the shared port ~17px.
+ *
+ * @see lib/common/splines.c:shape_clip / shape_clip0
+ */
+export function shapeClip(u: Node, curve: Point[]): void {
+  const box = nodeBoxOf(u, u.root);
+  const clipped = bezierClipNode(curve, box.center.x, box.center.y, nodeInsideFn(box), true);
+  for (let i = 0; i < curve.length && i < clipped.length; i++) curve[i] = clipped[i];
+}
+
+// ---------------------------------------------------------------------------
+// buildPort — construct the shared port for a group
+// @see lib/dotgen/sameport.c:sameport
+// ---------------------------------------------------------------------------
+
+/** Compute (x1,y1) offset to node boundary for average direction. */
+export function computeBoundaryOffset(
+  u: Node, x: number, y: number, ranksep: number,
+): { x1: number; y1: number } {
+  const r = Math.max(
+    (u.info.lw ?? 0) + (u.info.rw ?? 0),
+    (u.info.ht ?? 0) + ranksep,
+  );
+  const x2 = x * r + u.info.coord.x;
+  const y2 = y * r + u.info.coord.y;
+  const curve = [
+    { x: u.info.coord.x, y: u.info.coord.y },
+    { x: (2 * u.info.coord.x + x2) / 3, y: (2 * u.info.coord.y + y2) / 3 },
+    { x: (2 * x2 + u.info.coord.x) / 3, y: (2 * y2 + u.info.coord.y) / 3 },
+    { x: x2, y: y2 },
+  ];
+  shapeClip(u, curve);
+  return {
+    x1: curve[0].x - u.info.coord.x,
+    y1: curve[0].y - u.info.coord.y,
+  };
+}
+
+/** Compute the average direction unit vector from u toward each edge's other end. */
+export function averageDirection(u: Node, edges: Edge[]): { x: number; y: number } {
+  let sx = 0, sy = 0;
+  for (const e of edges) {
+    const v = e.head === u ? e.tail : e.head;
+    const dx = v.info.coord.x - u.info.coord.x;
+    const dy = v.info.coord.y - u.info.coord.y;
+    const r = Math.hypot(dx, dy);
+    if (r !== 0) { sx += dx / r; sy += dy / r; }
+  }
+  const r = Math.hypot(sx, sy);
+  return r !== 0 ? { x: sx / r, y: sy / r } : { x: 0, y: 0 };
+}
+
+/** Build the shared port object for this group at node u. */
+export function buildSharedPort(u: Node, edges: Edge[], ranksep: number): Port {
+  const dir = averageDirection(u, edges);
+  const { x1, y1 } = computeBoundaryOffset(u, dir.x, dir.y, ranksep);
+  // C round(): half away from zero. x1/y1 are offsets from the node CENTRE, so
+  // they are negative for roughly half of all samehead/sametail ports.
+  // @see lib/dotgen/sameport.c:149 (`.p = {.x = round(x1), .y = round(y1)}`)
+  const px = cround(x1);
+  const py = cround(y1);
+  const lw = u.info.lw ?? 0;
+  const rw = u.info.rw ?? 0;
+  const order = (lw + rw) !== 0 ? (MC_SCALE * (lw + px)) / (lw + rw) : 0;
+  return {
+    p: { x: px, y: py },
+    theta: 0,
+    bp: null,
+    defined: true,
+    constrained: false,
+    clip: false,
+    dyna: false,
+    order,
+    side: 0,
+    name: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// assignPortToChain — walk virtual chain and assign port
+// @see lib/dotgen/sameport.c:sameport (inner loops)
+// ---------------------------------------------------------------------------
+
+/** Assign prt to edge f at whichever end matches u. */
+export function assignHeadIfMatch(f: Edge, u: Node, prt: Port): void {
+  if (f.head === u) f.info.head_port = prt;
+  if (f.tail === u) f.info.tail_port = prt;
+}
+
+/** Walk the forward virtual chain (via head.out) assigning ports. */
+export function assignPortForwardChain(e: Edge, u: Node, prt: Port): void {
+  for (
+    let f: Edge | undefined = e;
+    f !== undefined;
+    f = (f.info.edge_type ?? 0) === VIRTUAL
+      && (f.head.info.node_type ?? 0) === VIRTUAL
+      && (f.head.info.out?.size ?? 0) === 1
+      ? f.head.info.out!.list[0]
+      : undefined
+  ) {
+    assignHeadIfMatch(f, u, prt);
+  }
+}
+
+/** Walk the backward virtual chain (via tail.in) assigning ports. */
+export function assignPortBackwardChain(e: Edge, u: Node, prt: Port): void {
+  for (
+    let f: Edge | undefined = e;
+    f !== undefined;
+    f = (f.info.edge_type ?? 0) === VIRTUAL
+      && (f.tail.info.node_type ?? 0) === VIRTUAL
+      && (f.tail.info.in?.size ?? 0) === 1
+      ? f.tail.info.in!.list[0]
+      : undefined
+  ) {
+    assignHeadIfMatch(f, u, prt);
+  }
+}
+
+/** Assign prt to all virtual edges of e that touch u. */
+export function assignPortToAllVirts(e: Edge, u: Node, prt: Port): void {
+  for (let virt: Edge | undefined = e; virt !== undefined; virt = virt.info.to_virt) {
+    assignPortForwardChain(virt, u, prt);
+    assignPortBackwardChain(virt, u, prt);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// sameport — assign shared port to all edges in a group
+// @see lib/dotgen/sameport.c:sameport
+// ---------------------------------------------------------------------------
+
+/** @see lib/dotgen/sameport.c:sameport */
+export function sameport(u: Node, edges: Edge[], ranksep: number): void {
+  if (edges.length < 2) return;
+  const prt = buildSharedPort(u, edges, ranksep);
+  for (const e of edges) assignPortToAllVirts(e, u, prt);
+  u.info.has_port = true;
+}
+
+// ---------------------------------------------------------------------------
+// attribute presence checks
+// ---------------------------------------------------------------------------
+
+/** True if any edge in g has a samehead attribute set. */
+export function graphHasSamehead(g: Graph): boolean {
+  for (const e of g.edges) {
+    if (e.info.samehead !== undefined) return true;
+  }
+  return false;
+}
+
+/** True if any edge in g has a sametail attribute set. */
+export function graphHasSametail(g: Graph): boolean {
+  for (const e of g.edges) {
+    if (e.info.sametail !== undefined) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// collectSameGroups — build same-head/tail groups for one node
+// @see lib/dotgen/sameport.c:dot_sameports inner loop
+// ---------------------------------------------------------------------------
+
+/** Collect samehead groups for node n. */
+export function collectSamehead(n: Node): SameGroup[] {
+  const same: SameGroup[] = [];
+  for (const e of n.root.edges) {
+    if (e.head === n && e.tail === n) continue;
+    const id = e.head === n ? e.info.samehead : undefined;
+    if (id && id !== '') sameedge(same, e, id);
+  }
+  return same;
+}
+
+/** Collect sametail groups for node n. */
+export function collectSametail(n: Node): SameGroup[] {
+  const same: SameGroup[] = [];
+  for (const e of n.root.edges) {
+    if (e.head === n && e.tail === n) continue;
+    const id = e.tail === n ? e.info.sametail : undefined;
+    if (id && id !== '') sameedge(same, e, id);
+  }
+  return same;
+}
+
+/** Apply sameport merging for all multi-edge groups at node n. */
+export function applyGroupsToNode(n: Node, groups: SameGroup[], ranksep: number): void {
+  for (const grp of groups) {
+    if (grp.edges.length > 1) sameport(n, grp.edges, ranksep);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// dot_sameports — main entry point
+// @see lib/dotgen/sameport.c:dot_sameports
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge edge ports in g for edges sharing samehead/sametail attributes.
+ * @see lib/dotgen/sameport.c:dot_sameports
+ */
+export function dotSameports(g: Graph): void {
+  const hasSH = graphHasSamehead(g);
+  const hasST = graphHasSametail(g);
+  if (!hasSH && !hasST) return;
+  const ranksep = g.info.ranksep ?? 0;
+  for (const n of nodesInSeq(g)) {
+    if (hasSH) applyGroupsToNode(n, collectSamehead(n), ranksep);
+    if (hasST) applyGroupsToNode(n, collectSametail(n), ranksep);
+  }
+}

package/src/layout/dot/self-loop.ts

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Self-loop routing for the dot engine.
+ *
+ * Ports the self-edge branch of dot_splines_ in lib/dotgen/dotsplines.c:305-409.
+ * Self-loops are stored in ND_other (node.info.other) by class2OneEdge.
+ * This module: collects them, computes sizey from the rank table, and calls
+ * the shared makeSelfEdge dispatcher.
+ *
+ * @see lib/dotgen/dotsplines.c:305-409
+ * @see lib/common/splines.c:makeSelfEdge
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { SplineInfo } from '../../common/types.js';
+import { NORMAL } from './fastgr.js';
+import { setflags, AUXGRAPH } from './splines.js';
+import { swapEndsP, splineMerge } from './splines.js';
+import { makeSelfEdge } from '../../common/splines-selfedge.js';
+
+// ---------------------------------------------------------------------------
+// buildDotSinfo — dot-specific SplineInfo
+// @see lib/dotgen/dotsplines.c:125-126
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the dot-engine SplineInfo (sinfo).
+ * @see lib/dotgen/dotsplines.c:125-126
+ */
+export function buildDotSinfo(): SplineInfo {
+  return {
+    swapEnds: swapEndsP as (e: unknown) => boolean,
+    splineMerge: splineMerge as (n: unknown) => boolean,
+    ignoreSwap: false,
+    isOrtho: false,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// collectOtherEdges — add ND_other edges to the routing list
+// @see lib/dotgen/dotsplines.c:305-318
+// ---------------------------------------------------------------------------
+
+/**
+ * Collect node.info.other edges into `edges`, restoring rw from mval first.
+ *
+ * In position(), each NORMAL node that has self-loops has its rw increased to
+ * accommodate the loop geometry and the original value saved in mval.
+ * We restore the original rw here before routing.
+ *
+ * @see lib/dotgen/dotsplines.c:305-318
+ */
+export function collectOtherEdges(n: Node, edges: Edge[]): void {
+  const other = n.info.other;
+  if (!other?.size) return;
+  if ((n.info.node_type ?? NORMAL) === NORMAL) {
+    // SWAP(&ND_rw(n), &ND_mval(n))
+    const savedRw = n.info.rw ?? 0;
+    n.info.rw = n.info.mval ?? 0;
+    n.info.mval = savedRw;
+  }
+  for (let k = 0; k < other.size; k++) {
+    const e = other.list[k];
+    setflags(e, 0, 0, AUXGRAPH);
+    edges.push(e);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// computeSizey — rank-gap geometry for self-loop sizing
+// @see lib/dotgen/dotsplines.c:389-403
+// ---------------------------------------------------------------------------
+
+/** y-coord of first node in rank r. @see lib/dotgen/dotsplines.c:394 */
+function rankY(g: Graph, r: number): number {
+  return g.info.rank![r].v[0].info.coord?.y ?? 0;
+}
+
+/** sizey when n is at the maximum rank. @see lib/dotgen/dotsplines.c:392-396 */
+function sizeyAtMaxrank(g: Graph, n: Node, r: number): number {
+  if (r > 0) return rankY(g, r - 1) - (n.info.coord?.y ?? 0);
+  return n.info.ht ?? 0;
+}
+
+/** sizey when n is at the minimum rank. @see lib/dotgen/dotsplines.c:397-398 */
+function sizeyAtMinrank(g: Graph, n: Node, r: number): number {
+  return (n.info.coord?.y ?? 0) - rankY(g, r + 1);
+}
+
+/** sizey when n is at a middle rank. @see lib/dotgen/dotsplines.c:400-402 */
+function sizeyAtMidrank(g: Graph, n: Node, r: number): number {
+  const ny  = n.info.coord?.y ?? 0;
+  const upy  = rankY(g, r - 1) - ny;
+  const dwny = ny - rankY(g, r + 1);
+  return Math.min(upy, dwny);
+}
+
+/**
+ * Compute the vertical sizing parameter for self-loops on node n.
+ *
+ * Mirrors the C branch exactly:
+ *   if r == maxrank: sizey = rank[r-1].v[0].y - n.y   (or ht if r==0)
+ *   elif r == minrank: sizey = n.y - rank[r+1].v[0].y
+ *   else: sizey = min(rank[r-1].v[0].y - n.y, n.y - rank[r+1].v[0].y)
+ *
+ * @see lib/dotgen/dotsplines.c:389-403
+ */
+export function computeSizey(g: Graph, n: Node): number {
+  const r       = n.info.rank ?? 0;
+  const minrank = g.info.minrank ?? 0;
+  const maxrank = g.info.maxrank ?? 0;
+  if (r === maxrank) return sizeyAtMaxrank(g, n, r);
+  if (r === minrank) return sizeyAtMinrank(g, n, r);
+  return sizeyAtMidrank(g, n, r);
+}
+
+// ---------------------------------------------------------------------------
+// routeSelfEdgeGroup — route one group of parallel self-loops
+// @see lib/dotgen/dotsplines.c:388-409
+// ---------------------------------------------------------------------------
+
+/**
+ * Route a contiguous group of cnt parallel self-loops via makeSelfEdge.
+ *
+ * @param g       - the graph (provides rank table for sizey)
+ * @param edges   - slice of the sorted edge list starting at the group
+ * @param cnt     - number of parallel self-loops in this group
+ * @param multisep - sd.Multisep (= nodesep)
+ * @param sinfo   - dot SplineInfo callbacks
+ *
+ * @see lib/dotgen/dotsplines.c:388-409
+ */
+export function routeSelfEdgeGroup(
+  g: Graph,
+  edges: Edge[],
+  cnt: number,
+  multisep: number,
+  sinfo: SplineInfo,
+): void {
+  const e0 = edges[0];
+  const n = e0.tail;
+  const sizey = computeSizey(g, n);
+  makeSelfEdge(edges, cnt, multisep, sizey / 2, sinfo);
+}

package/src/layout/dot/splines-clone.ts

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * cloneNode / cloneEdge for the flat-adj recursive pipeline.
+ *
+ * @see lib/dotgen/dotsplines.c:cloneNode, cloneEdge, cleanupCloneGraph
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { Point } from '../../model/geom.js';
+import { Edge as EdgeClass } from '../../model/edge.js';
+import { makePort } from '../../model/edgeInfo.js';
+import { agnode } from '../../model/cgraph-ops.js';
+
+/**
+ * Map a point from the flat-adj auxiliary frame back to the original frame:
+ * un-rotate when the original graph is flipped, then translate by del.
+ * @see lib/dotgen/dotsplines.c:transformf
+ */
+export function transformf(p: Point, del: Point, flip: boolean): Point {
+  const q = flip ? { x: p.y, y: -p.x } : { x: p.x, y: p.y };
+  return { x: q.x + del.x, y: q.y + del.y };
+}
+
+// ---------------------------------------------------------------------------
+// cloneNode
+// @see lib/dotgen/dotsplines.c:cloneNode
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a copy of orign in graph g, carrying geometry from NodeInfo.
+ * @see lib/dotgen/dotsplines.c:cloneNode
+ */
+export function cloneNode(g: Graph, orign: Node): Node {
+  // C: `agnode(g, agnameof(orign), 1)` mints a FRESH AGSEQ for the clone,
+  // scoped to the aux graph's own creation sequence — it does NOT carry
+  // orign's id/AGSEQ across graphs. A prior port carried `orign.id` onto the
+  // clone directly, which corrupted `nodesInSeq(auxg)` (F7): the clone's
+  // "AGSEQ" borrowed the ORIGINAL graph's id ordering instead of reflecting
+  // the aux graph's own auxt/auxh creation order.
+  // @see lib/dotgen/dotsplines.c:cloneNode (agnode(g,...,1))
+  const n = agnode(g, orign.name, true)!;
+  n.info.coord = { x: orign.info.coord.x, y: orign.info.coord.y };
+  n.info.lw = orign.info.lw;
+  n.info.rw = orign.info.rw;
+  n.info.ht = orign.info.ht;
+  n.info.width = orign.info.width;
+  n.info.height = orign.info.height;
+  // Copy string attrs — EXCEPT `fixedsize`. C's flat-adj aux pipeline never
+  // sees fixedsize: cloneGraph→setState rebinds the global N_fixed sym via
+  // `agfindnodeattr(auxg, "fixed")` (dotsplines.c setState), but the real
+  // attribute is named "fixedsize" (input.c:750 binds N_fixed to
+  // "fixedsize"), so N_fixed is NULL inside the aux and gv_nodesize grows a
+  // fixedsize node to enclose its label (e.g. #1949 structDefaultAuto:
+  // main ht 36 clamped, aux ht 66.63). This name mismatch is a load-bearing
+  // C quirk — the aux node-shape clip lands on the GROWN boundary, which is
+  // where the copied flat-adj spline ends.
+  // @see lib/dotgen/dotsplines.c:setState (N_fixed = "fixed"),
+  //      lib/common/input.c:750 (N_fixed = "fixedsize")
+  for (const [k, v] of orign.attrs) {
+    if (k === 'fixedsize') continue;
+    n.attrs.set(k, v);
+  }
+  // Carry the origin's node-default snapshot so inherited attributes (e.g. a
+  // graph-level `node[fontsize=8]` the origin never set explicitly) still
+  // resolve in the aux graph, which has no node defaults of its own. C's
+  // cloneNode does `agcopyattr`, which materialises the origin's inherited attr
+  // values; without this the aux re-sizes an HTML-label node at the built-in
+  // fontsize=14 instead of the inherited 8, ballooning the node (#1949: the
+  // flat-adj aux nodes grew ~2x, adding 33px of graph height).
+  // @see lib/dotgen/dotsplines.c:cloneNode (agcopyattr)
+  if (orign.nodeDefaultsSnapshot !== undefined) {
+    n.nodeDefaultsSnapshot = new Map(orign.nodeDefaultsSnapshot);
+  }
+  return n;
+}
+
+// ---------------------------------------------------------------------------
+// cloneEdge
+// @see lib/dotgen/dotsplines.c:cloneEdge
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a copy of orig between tn→hn in graph g.
+ * @see lib/dotgen/dotsplines.c:cloneEdge
+ */
+export function cloneEdge(g: Graph, tn: Node, hn: Node, orig: Edge): Edge {
+  const e = new EdgeClass(tn, hn, orig.name);
+  e.info.tail_port = { ...makePort(), ...orig.info.tail_port };
+  e.info.head_port = { ...makePort(), ...orig.info.head_port };
+  e.info.weight = orig.info.weight;
+  e.info.minlen = orig.info.minlen;
+  // Copy string attrs
+  for (const [k, v] of orig.attrs) e.attrs.set(k, v);
+  // Edges living under the aux clone's attribute dictionary resolve
+  // arrowsize/penwidth through C's stale (un-remapped) global symbols during
+  // arrow clipping — see EdgeInfo.stale_arrow_attrs for the mechanism.
+  // @see lib/dotgen/dotsplines.c:setState (E_arrowsz/E_penwidth not remapped)
+  e.info.stale_arrow_attrs = true;
+  g.edges.push(e);
+  return e;
+}
+
+// ---------------------------------------------------------------------------
+// cleanupCloneGraph
+// @see lib/dotgen/dotsplines.c:cleanupCloneGraph
+// ---------------------------------------------------------------------------
+
+/**
+ * Release all resources held by the auxiliary clone graph.
+ * In the C implementation this restores global Agsyms and calls dot_cleanup.
+ * In TypeScript, clearing node and edge collections is sufficient.
+ * @see lib/dotgen/dotsplines.c:cleanupCloneGraph
+ */
+export function cleanupCloneGraph(auxg: Graph): void {
+  auxg.nodes.clear();
+  auxg.edges.length = 0;
+  auxg.subgraphs.clear();
+}