@knowvah/dot-engine 0.1.0

package/src/layout/twopi/circle.ts

@@ -0,0 +1,339 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Seven-phase radial layout algorithm for the twopi engine.
+ * Ports lib/twopigen/circle.c.
+ *
+ * @see lib/twopigen/circle.c
+ * @see lib/twopigen/circle.h
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { TwopiAlgData } from '../../model/nodeInfo.js';
+import { THETA_UNSET } from '../../model/nodeInfo.js';
+
+/** Default ring separation in inches. @see lib/twopigen/circle.c:#define DEF_RANKSEP */
+const DEF_RANKSEP = 1.0;
+
+/** Minimum per-ring delta. @see lib/common/render.h:MIN_RANKSEP */
+export const MIN_RANKSEP = 0.02;
+
+/** Get the TwopiAlgData record for a node; throws if absent. */
+function rdata(n: Node): TwopiAlgData {
+  const d = n.info.alg;
+  if (!d || d.kind !== 'twopi') throw new Error(`twopi: missing rdata on node ${n.name}`);
+  return d;
+}
+
+/**
+ * Resolve the neighbor of n across ep; null if ep is not incident.
+ * @see lib/twopigen/circle.c (edge traversal pattern)
+ */
+function neighborOf(ep: Edge, n: Node): Node | null {
+  if (ep.tail === n) return ep.head;
+  if (ep.head === n) return ep.tail;
+  return null;
+}
+
+/**
+ * Edges incident to n in agfstedge/agnxtedge order: out-edges first,
+ * then in-edges. C's traversal order is load-bearing for the fan
+ * assignment in setChildPositions.
+ * @see lib/cgraph/edge.c:agfstedge
+ */
+function incidentEdges(g: Graph, n: Node): Edge[] {
+  return [...n.outEdges(g), ...n.inEdges(g)];
+}
+
+/**
+ * Return true if n is a leaf: at most one distinct neighbor.
+ * @see lib/twopigen/circle.c:isLeaf
+ */
+export function isLeaf(g: Graph, n: Node): boolean {
+  let neighp: Node | null = null;
+  for (const ep of incidentEdges(g, n)) {
+    const np = neighborOf(ep, n);
+    if (np === null || np === n) continue;
+    if (neighp === null) { neighp = np; }
+    else if (neighp !== np) { return false; }
+  }
+  return true;
+}
+
+/**
+ * Phase 1: initialize all rdata fields before BFS passes.
+ * @see lib/twopigen/circle.c:initLayout
+ */
+export function initLayout(g: Graph): void {
+  const INF = g.nodes.size * g.nodes.size;
+  for (const n of g.nodes.values()) {
+    n.info.alg = {
+      kind: 'twopi',
+      nStepsToLeaf: isLeaf(g, n) ? 0 : INF,
+      subtreeSize: 0,
+      nChildren: 0,
+      nStepsToCenter: INF,
+      parent: null,
+      span: 0,
+      theta: THETA_UNSET,
+    };
+  }
+}
+
+/** Try to relax leaf-distance on one neighbor; recurse on improvement. */
+function relaxLeafEdge(g: Graph, next: Node, from: Node, nsteps: number): void {
+  const nd2 = rdata(next);
+  if (nsteps < nd2.nStepsToLeaf) {
+    nd2.nStepsToLeaf = nsteps;
+    setNStepsToLeaf(g, next, from);
+  }
+}
+
+/**
+ * DFS to propagate leaf distance outward from n.
+ * @see lib/twopigen/circle.c:setNStepsToLeaf
+ */
+export function setNStepsToLeaf(g: Graph, n: Node, prev: Node | null): void {
+  const nsteps = rdata(n).nStepsToLeaf + 1;
+  for (const ep of incidentEdges(g, n)) {
+    const next = neighborOf(ep, n);
+    if (next !== null && next !== prev) relaxLeafEdge(g, next, n, nsteps);
+  }
+}
+
+/** Try to relax BFS distance to `next` through `cur`. */
+function processBfsEdge(cur: Node, next: Node, nsteps: number, queue: Node[]): void {
+  const nd2 = rdata(next);
+  if (nsteps < nd2.nStepsToCenter) {
+    nd2.nStepsToCenter = nsteps;
+    nd2.parent = cur;
+    rdata(cur).nChildren++;
+    queue.push(next);
+  }
+}
+
+/**
+ * Phase 2: find center node (max nStepsToLeaf).
+ * @see lib/twopigen/circle.c:findCenterNode
+ */
+export function findCenterNode(g: Graph): Node | null {
+  for (const n of g.nodes.values()) {
+    if (rdata(n).nStepsToLeaf === 0) setNStepsToLeaf(g, n, null);
+  }
+  let center: Node | null = null;
+  let maxSteps = 0;
+  for (const n of g.nodes.values()) {
+    const sl = rdata(n).nStepsToLeaf;
+    if (center === null || sl > maxSteps) { maxSteps = sl; center = n; }
+  }
+  return center;
+}
+
+/**
+ * BFS from n assigning SCENTER and SPARENT; skips weight=0 edges.
+ * @see lib/twopigen/circle.c:setNStepsToCenter
+ */
+export function setNStepsToCenter(g: Graph, n: Node): void {
+  const queue: Node[] = [n];
+  let head = 0;
+  while (head < queue.length) {
+    const cur = queue[head++]!;
+    const nsteps = rdata(cur).nStepsToCenter + 1;
+    for (const ep of incidentEdges(g, cur)) {
+      if (ep.attrs.get('weight') === '0') continue;
+      const next = neighborOf(ep, cur);
+      if (next !== null) processBfsEdge(cur, next, nsteps, queue);
+    }
+  }
+}
+
+/**
+ * Phase 3: BFS from center; returns max ring index or MAX_SAFE_INTEGER.
+ * @see lib/twopigen/circle.c:setParentNodes
+ */
+export function setParentNodes(sg: Graph, center: Node): number {
+  const nd = rdata(center);
+  const unset = nd.nStepsToCenter;
+  nd.nStepsToCenter = 0;
+  nd.parent = null;
+  setNStepsToCenter(sg, center);
+  let maxn = 0;
+  for (const n of sg.nodes.values()) {
+    const sc = rdata(n).nStepsToCenter;
+    if (sc === unset) return Number.MAX_SAFE_INTEGER;
+    if (sc > maxn) maxn = sc;
+  }
+  return maxn;
+}
+
+/** Walk the parent chain from n, incrementing subtreeSize at each ancestor. */
+function walkAncestorChain(n: Node): void {
+  let par = rdata(n).parent;
+  while (par !== null) {
+    rdata(par).subtreeSize++;
+    par = rdata(par).parent;
+  }
+}
+
+/**
+ * Phase 4: count BFS-leaves in each subtree bottom-up.
+ * @see lib/twopigen/circle.c:setSubtreeSize
+ */
+export function setSubtreeSize(g: Graph): void {
+  for (const n of g.nodes.values()) {
+    const nd = rdata(n);
+    if (nd.nChildren > 0) continue;
+    nd.subtreeSize++;
+    walkAncestorChain(n);
+  }
+}
+
+/**
+ * Assign span to one child of n; recurse if it has children.
+ * @see lib/twopigen/circle.c:setChildSubtreeSpans (inner body)
+ */
+function applySpanToChild(g: Graph, n: Node, next: Node, ratio: number, seen: Set<Node>): void {
+  const nd2 = rdata(next);
+  if (nd2.parent !== n || nd2.span !== 0 || seen.has(next)) return;
+  seen.add(next);
+  nd2.span = ratio * nd2.subtreeSize;
+  if (nd2.nChildren > 0) setChildSubtreeSpans(g, next);
+}
+
+/**
+ * Recursively partition a node's angular span among its children.
+ * @see lib/twopigen/circle.c:setChildSubtreeSpans
+ */
+export function setChildSubtreeSpans(g: Graph, n: Node): void {
+  const nd = rdata(n);
+  const ratio = nd.span / nd.subtreeSize;
+  const seen = new Set<Node>();
+  for (const ep of incidentEdges(g, n)) {
+    const next = neighborOf(ep, n);
+    if (next !== null) applySpanToChild(g, n, next, ratio, seen);
+  }
+}
+
+/**
+ * Phase 5: root gets 2π span; children get proportional shares.
+ * @see lib/twopigen/circle.c:setSubtreeSpans
+ */
+export function setSubtreeSpans(sg: Graph, center: Node): void {
+  rdata(center).span = 2 * Math.PI;
+  setChildSubtreeSpans(sg, center);
+}
+
+/**
+ * Assign theta to one child and recurse; returns updated fan pointer.
+ * @see lib/twopigen/circle.c:setChildPositions (inner body)
+ */
+function applyThetaToChild(sg: Graph, n: Node, next: Node, theta: number): number {
+  const nd2 = rdata(next);
+  if (nd2.parent !== n || nd2.theta !== THETA_UNSET) return theta;
+  nd2.theta = theta + nd2.span / 2.0;
+  theta += nd2.span;
+  if (nd2.nChildren > 0) setChildPositions(sg, next);
+  return theta;
+}
+
+/**
+ * Assign theta (angular midpoint) to each child of n in a fan.
+ * @see lib/twopigen/circle.c:setChildPositions
+ */
+export function setChildPositions(sg: Graph, n: Node): void {
+  const nd = rdata(n);
+  let theta = nd.parent === null ? 0 : nd.theta - nd.span / 2;
+  for (const ep of incidentEdges(sg, n)) {
+    const next = neighborOf(ep, n);
+    if (next !== null) theta = applyThetaToChild(sg, n, next, theta);
+  }
+}
+
+/**
+ * Phase 6: assign angular positions; root gets theta = 0.
+ * @see lib/twopigen/circle.c:setPositions
+ */
+export function setPositions(sg: Graph, center: Node): void {
+  rdata(center).theta = 0;
+  setChildPositions(sg, center);
+}
+
+/**
+ * Parse colon-separated ranksep parts; returns last delta, next rk, running sum.
+ * @see lib/twopigen/circle.c:getRankseps (parse loop)
+ */
+function parseRanksepParts(
+  parts: string[], ranks: number[], maxrank: number,
+): { delx: number; rk: number; xf: number } {
+  // C initializes delx = 0.0; DEF_RANKSEP applies ONLY when the ranksep attr
+  // is ABSENT. A present-but-unparseable value ("equally") leaves delx 0 and
+  // every ring collapses to radius 0 — a load-bearing quirk (graphs/b80).
+  // @see lib/twopigen/circle.c:getRankseps
+  let xf = 0; let delx = 0; let rk = 1;
+  for (const part of parts) {
+    if (rk > maxrank) break;
+    const d = parseFloat(part.trim());
+    if (!isFinite(d) || d <= 0) break;
+    delx = Math.max(d, MIN_RANKSEP);
+    xf += delx;
+    ranks[rk++] = xf;
+  }
+  return { delx, rk, xf };
+}
+
+/**
+ * Build cumulative radius array from ranksep attribute.
+ * @see lib/twopigen/circle.c:getRankseps
+ */
+export function getRankseps(g: Graph, maxrank: number): number[] {
+  const ranks = new Array<number>(maxrank + 1).fill(0);
+  const raw = g.root.attrs.get('ranksep') ?? g.attrs.get('ranksep');
+  let delx = DEF_RANKSEP; let rk = 1; let xf = 0;
+  if (raw !== undefined && raw.length > 0) {
+    const r = parseRanksepParts(raw.split(':'), ranks, maxrank);
+    delx = r.delx; rk = r.rk; xf = r.xf;
+  }
+  for (let i = rk; i <= maxrank; i++) { xf += delx; ranks[i] = xf; }
+  return ranks;
+}
+
+/**
+ * Phase 7: polar → Cartesian; writes to n.info.pos.
+ * @see lib/twopigen/circle.c:setAbsolutePos
+ */
+export function setAbsolutePos(g: Graph, maxrank: number): void {
+  const ranksep = getRankseps(g, maxrank);
+  for (const n of g.nodes.values()) {
+    const nd = rdata(n);
+    const hyp = ranksep[nd.nStepsToCenter] ?? 0;
+    if (!n.info.pos || n.info.pos.length < 2) n.info.pos = [0, 0];
+    n.info.pos[0] = hyp * Math.cos(nd.theta);
+    n.info.pos[1] = hyp * Math.sin(nd.theta);
+  }
+}
+
+/**
+ * Run the full seven-phase radial layout on a connected subgraph.
+ * Returns the center node used; null only if the graph is empty.
+ * @see lib/twopigen/circle.c:circleLayout
+ */
+export function circleLayout(sg: Graph, center: Node | null): Node | null {
+  if (sg.nodes.size === 1) {
+    const n = sg.nodes.values().next().value as Node;
+    if (!n.info.pos || n.info.pos.length < 2) n.info.pos = [0, 0];
+    n.info.pos[0] = 0; n.info.pos[1] = 0;
+    return center;
+  }
+  initLayout(sg);
+  if (center === null) center = findCenterNode(sg);
+  if (center === null) return null;
+  const maxN = setParentNodes(sg, center);
+  if (maxN === Number.MAX_SAFE_INTEGER) return center;
+  setSubtreeSize(sg);
+  setSubtreeSpans(sg, center);
+  setPositions(sg, center);
+  setAbsolutePos(sg, maxN);
+  return center;
+}

package/src/layout/twopi/index.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * twopi radial layout engine — public entry point.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { LayoutEngine } from '../../gvc/context.js';
+import { twopiInitGraph, twopiCleanup } from './init.js';
+import { ccomps, normalizeGraphBB } from '../pack/index.js';
+import { layoutSingle, layoutMulti, buildPackInfo } from './pipeline.js';
+import { commonInitNodeEdge, layoutMeasurer } from '../../common/nodeinit.js';
+import { initEdgeLabels } from '../../common/edge-label-init.js';
+import { placeGraphLabel } from '../dot/position-bbox.js';
+import { graphInit } from '../../common/graph-init.js';
+import { gvPostprocess } from '../../common/postproc.js';
+
+export {
+  twopiInitGraph,
+  twopiCleanup,
+  findRootNode,
+  adjustNodes,
+  finaliseCoords,
+} from './init.js';
+export { circleLayout, isLeaf, initLayout } from './circle.js';
+export { THETA_UNSET } from '../../model/nodeInfo.js';
+
+/**
+ * Full twopi layout pipeline for a graph.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout
+ */
+export function twopiLayout(g: Graph): void {
+  if (g.nodes.size === 0) return;
+  // C: gvLayoutJobs runs graph_init(g, LAYOUT_USES_RANKDIR) before twopi_layout;
+  // twopi does not set the flag → useRankdir=false. graph_init also creates the
+  // ROOT graph label, which gvPostprocess below sizes the canvas for and places.
+  // @see lib/common/input.c:600, lib/gvc/gvlayout.c:81
+  graphInit(g, false);
+  commonInitNodeEdge(g);
+  // C twopi_init_edge -> common_init_edge creates the edge label; addXLabels
+  // (in gvPostprocess below) places it at the edge midpoint. @see twopiinit.c:28
+  const measurer = layoutMeasurer(g);
+  if (measurer !== undefined) {
+    for (const e of g.edges) initEdgeLabels(e, g, measurer);
+  }
+  twopiInitGraph(g);
+  const rootAttr = g.attrs.get('root');
+  const setRoot = rootAttr !== undefined;
+  const globalRoot = setRoot && rootAttr !== ''
+    ? (g.nodes.get(rootAttr!) ?? null)
+    : null;
+  const comps = ccomps(g, '_twopi');
+  if (comps.length === 1) {
+    layoutSingle(g, comps, globalRoot, setRoot);
+  } else {
+    layoutMulti(g, comps, globalRoot, buildPackInfo(g));
+  }
+  normalizeGraphBB(g);
+  // C: dotneato_postprocess(g) — cluster labels, edge labels (addXLabels), root
+  // graph label space + translate. @see lib/twopigen/twopiinit.c:152
+  placeGraphLabel(g);
+  gvPostprocess(g);
+}
+
+/**
+ * LayoutEngine descriptor for registration with GvcContext.
+ *
+ * @see lib/gvc/gvcext.h:gvlayout_engine_s
+ * @see lib/twopigen/twopiinit.c (plugin wiring)
+ */
+export const TWOPI_LAYOUT_ENGINE: LayoutEngine = {
+  type: 'twopi',
+  layout: twopiLayout,
+  cleanup: twopiCleanup,
+};

package/src/layout/twopi/init.ts

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * twopi engine initialisation: per-node/edge init, graph init, cleanup.
+ * Ports lib/twopigen/twopiinit.c: twopi_init_node_edge, twopi_init_graph,
+ * findRootNode, twopi_cleanup.
+ *
+ * @see lib/twopigen/twopiinit.c
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { TwopiAlgData } from '../../model/nodeInfo.js';
+import { THETA_UNSET } from '../../model/nodeInfo.js';
+import { setEdgeTypeFromAttr } from '../dot/index.js';
+import { EDGETYPE_LINE } from '../neato/splines.js';
+import { adjustNodesFull } from '../neato/fdp-adjust.js';
+
+/** Points per inch, used to convert pos (inches) → coord (points). */
+const POINTS_PER_INCH = 72;
+
+/**
+ * Build a zeroed TwopiAlgData record for one node.
+ * Mirrors gv_calloc(n_nodes, sizeof(rdata)) — all fields at zero/INF defaults.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_init_node_edge (gv_calloc call)
+ */
+function makeRdata(INF: number): TwopiAlgData {
+  return {
+    kind: 'twopi',
+    nStepsToLeaf: INF,
+    subtreeSize: 0,
+    nChildren: 0,
+    nStepsToCenter: INF,
+    parent: null,
+    span: 0,
+    theta: THETA_UNSET,
+  };
+}
+
+/**
+ * Initialize a node for twopi layout: ensure pos[0..1] exist, set defaults.
+ * Mirrors neato_init_node for the twopi engine.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_init_node_edge (neato_init_node call)
+ */
+export function twopiInitNode(n: Node): void {
+  if (!n.info.pos || n.info.pos.length < 2) n.info.pos = [0, 0];
+  if (!n.info.width) n.info.width = 0.75;
+  if (!n.info.height) n.info.height = 0.5;
+}
+
+/**
+ * Initialize an edge for twopi layout: set ED_factor from weight attribute.
+ * Default weight 1.0; minimum 0.0.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_init_edge
+ */
+export function twopiInitEdge(e: Edge): void {
+  const wt = e.attrs.get('weight');
+  const w = wt !== undefined ? Math.max(0.0, parseFloat(wt)) : 1.0;
+  e.info.factor = isFinite(w) ? w : 1.0;
+}
+
+/**
+ * Initialize all nodes and edges in g for twopi layout.
+ *
+ * Mirrors the C twopi_init_node_edge: allocates a contiguous rdata block
+ * (one TwopiAlgData per node), populates GD_neato_nlist, assigns ND_alg,
+ * then initialises every out-edge.
+ *
+ * The contiguous-allocation semantics are preserved: all TwopiAlgData objects
+ * are created here in one pass (matching gv_calloc(n_nodes, sizeof(rdata))),
+ * so twopiCleanup can mirror the C free(ND_alg(first_node)) by nulling only
+ * the first node's alg field.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_init_node_edge
+ */
+export function twopiInitNodeEdge(g: Graph): void {
+  const INF = g.nodes.size * g.nodes.size;
+  const nlist: Node[] = [];
+
+  // Allocate the contiguous rdata block and wire into nodes + nlist.
+  for (const n of g.nodes.values()) {
+    twopiInitNode(n);
+    n.info.alg = makeRdata(INF);
+    nlist.push(n);
+  }
+  g.info.neato_nlist = nlist;
+
+  // Initialise all edges.
+  for (const e of g.edges) twopiInitEdge(e);
+}
+
+/**
+ * Full graph initialisation: set edge type to line, force 2D, init nodes/edges.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_init_graph
+ */
+export function twopiInitGraph(g: Graph): void {
+  // C: setEdgeType(g, EDGETYPE_LINE) — the C setEdgeType FUNCTION reads the
+  // graph's `splines` attr first; EDGETYPE_LINE is only the fallback default.
+  // @see lib/common/utils.c:1423 setEdgeType
+  setEdgeTypeFromAttr(g, EDGETYPE_LINE);
+  g.info.ndim = 2;
+  twopiInitNodeEdge(g);
+}
+
+/**
+ * Scan sg for the first node whose `root` attribute is truthy.
+ * Returns null if no such node exists.
+ *
+ * @see lib/twopigen/twopiinit.c:findRootNode
+ */
+export function findRootNode(sg: Graph): Node | null {
+  for (const n of sg.nodes.values()) {
+    const v = n.attrs.get('root');
+    if (v === '1' || v === 'true' || v === 'yes') return n;
+  }
+  return null;
+}
+
+/**
+ * Convert pos (inches) to coord (points) for every node in g.
+ * Matches the neatoSetAspect / dotneato_postprocess coordinate finalisation.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout (post-layout coord write)
+ * @see lib/neatogen/neatoinit.c:neatoSetAspect
+ */
+export function finaliseCoords(g: Graph): void {
+  for (const n of g.nodes.values()) {
+    const pos = n.info.pos;
+    if (!pos) continue;
+    n.info.coord = {
+      x: (pos[0] ?? 0) * POINTS_PER_INCH,
+      y: (pos[1] ?? 0) * POINTS_PER_INCH,
+    };
+  }
+}
+
+/**
+ * Overlap adjustment: scale-family modes via scAdjust, PRISM (the GTS
+ * build's resolution of overlap=false / unrecognized values) via
+ * fdpAdjust; remaining modes (voronoi, vpsc, ortho*) are unported no-ops.
+ *
+ * @see lib/neatogen/adjust.c:adjustNodes
+ * @see lib/neatogen/constraint.c:scAdjust
+ */
+export function adjustNodes(g: Graph): void {
+  adjustNodesFull(g);
+}
+
+/**
+ * Release twopi-specific per-node state after layout.
+ *
+ * Mirrors the C twopi_layout cleanup: free(ND_alg(first_node)) / ND_alg = NULL
+ * on the FIRST node only (the contiguous block was allocated as a single unit).
+ * Other nodes' ND_alg pointers were interior offsets into that block so they
+ * do not need to be freed separately.
+ *
+ * ORDERING: must be called BEFORE splineEdges because edge routing may
+ * store its own data in n.info.alg.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout (free(ND_alg) placement note)
+ * @see lib/twopigen/twopiinit.c:twopi_cleanup
+ */
+export function twopiCleanup(g: Graph): void {
+  const first = g.nodes.values().next().value as Node | undefined;
+  if (first !== undefined && first.info.alg?.kind === 'twopi') {
+    first.info.alg = undefined;
+  }
+  g.info.neato_nlist = undefined;
+}

package/src/layout/twopi/pipeline.ts

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Internal pipeline helpers for the twopi layout engine.
+ * Isolated from index.ts so lizard can parse each function boundary cleanly.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { PackInfo } from '../pack/index.js';
+import {
+  twopiCleanup,
+  findRootNode,
+  adjustNodes,
+  finaliseCoords,
+} from './init.js';
+import { circleLayout } from './circle.js';
+import { packSubgraphs, getPackInfo, PackMode } from '../pack/index.js';
+import { splineEdgesShifted } from '../neato/splines.js';
+
+/** Margin constant matching C CL_OFFSET. @see lib/pack/pack.h:CL_OFFSET */
+export const CL_OFFSET = 8;
+
+/** circleLayout return type; Node | null. */
+export type Center = Node | null;
+
+/** Add only edges whose both endpoints belong to sg. */
+export function induceEdges(g: Graph, sg: Graph): void {
+  sg.edges = g.edges.filter(
+    e => sg.nodes.has(e.tail.name) && sg.nodes.has(e.head.name),
+  );
+}
+
+/** Prefer globalRoot if it is in sg; otherwise scan for root attribute. */
+export function resolveCenter(sg: Graph, globalRoot: Center): Center {
+  if (globalRoot !== null && sg.nodes.has(globalRoot.name)) return globalRoot;
+  return findRootNode(sg);
+}
+
+/** Lay out one component; return the chosen center node. */
+export function layoutComponent(g: Graph, sg: Graph, globalRoot: Center): Center {
+  induceEdges(g, sg);
+  const lctr = resolveCenter(sg, globalRoot);
+  const center = circleLayout(sg, lctr);
+  adjustNodes(sg);
+  return center;
+}
+
+/**
+ * Build a PackInfo for multi-component packing.
+ *
+ * @see lib/twopigen/twopiinit.c:twopi_layout (getPackInfo call with l_node)
+ */
+export function buildPackInfo(g: Graph): PackInfo {
+  const pinfo: PackInfo = {
+    aspect: 1, sz: 0, margin: CL_OFFSET, doSplines: false,
+    mode: PackMode.Node, fixed: null, vals: null, flags: 0,
+  };
+  // C: getPackInfo(g, l_node, CL_OFFSET) — polyomino node-mode packing.
+  getPackInfo(g, PackMode.Node, CL_OFFSET, pinfo);
+  pinfo.doSplines = false;
+  return pinfo;
+}
+
+/** Single-component pipeline: layout → cleanup → splines → coords. */
+export function layoutSingle(g: Graph, comps: Graph[], globalRoot: Center, setRoot: boolean): void {
+  const sg = comps[0]!;
+  const center = layoutComponent(g, sg, globalRoot);
+  if (setRoot && globalRoot === null && center !== null) {
+    g.attrs.set('root', center.name);
+  }
+  twopiCleanup(g); // ORDERING: before spline routing
+  // C: spline_edges(g) — shifts pos to the origin, syncs coord, routes.
+  splineEdgesShifted(g);
+  finaliseCoords(g);
+}
+
+/**
+ * Multi-component pipeline: per-component layout + coords, then cleanup,
+ * pack, re-sync coords, splines.
+ *
+ * finaliseCoords per component runs BEFORE packSubgraphs so that
+ * computeSubgraphBB reads real point-coords for bounding-box calculation.
+ * After packing shifts pos (inches), finaliseCoords re-syncs coord.
+ */
+export function layoutMulti(g: Graph, comps: Graph[], globalRoot: Center, pinfo: PackInfo): void {
+  for (const sg of comps) {
+    layoutComponent(g, sg, globalRoot);
+    finaliseCoords(sg);
+  }
+  twopiCleanup(g); // ORDERING: before spline routing
+  packSubgraphs(comps.length, comps, g, pinfo);
+  // C: spline_edges(g) — shifts pos to the origin, syncs coord, routes.
+  splineEdgesShifted(g);
+  finaliseCoords(g);
+}