@knowvah/dot-engine 0.1.0

package/src/layout/circo/index.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Circo circular layout engine — public entry point.
+ *
+ * Wires circoInitGraph, circoLayout, and cleanup into the LayoutEngine
+ * interface and exports CIRCO_LAYOUT_ENGINE for registration with GvcContext.
+ *
+ * Ordering (matches C circo_layout):
+ *   1. commonInitNodeEdge — set lw/rw/ht defaults for all nodes
+ *   2. circoInitGraph  — allocate ndata
+ *   3. circoLayout     — biconn + circle layout
+ *   4. freeNData       — null alg on first node (shared ndata block GC'd)
+ *   5. (spline routing — handled by caller / renderer)
+ *   6. dotneato_postprocess — handled by caller / renderer
+ *
+ * @see lib/circogen/circularinit.c:circo_layout
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { LayoutEngine } from '../../gvc/context.js';
+import { circoInitGraph, freeNData } from './init.js';
+import { circoLayout } from './circular.js';
+import { commonInitNodeEdge, layoutMeasurer } from '../../common/nodeinit.js';
+import { initEdgeLabels } from '../../common/edge-label-init.js';
+import { splineEdgesShifted } from '../neato/splines.js';
+import { placeGraphLabel } from '../dot/position-bbox.js';
+import { graphInit } from '../../common/graph-init.js';
+import { gvPostprocess } from '../../common/postproc.js';
+
+// Re-export key functions for consumers that need them individually.
+export { circoInitGraph, freeNData } from './init.js';
+export { circoLayout } from './circular.js';
+export { circPos } from './position.js';
+export { createBlocktree, freeBlocktree } from './blocktree.js';
+export { layoutBlock } from './blockpath.js';
+
+// ---------------------------------------------------------------------------
+// LayoutEngine implementation
+// ---------------------------------------------------------------------------
+
+/** @see lib/circogen/circularinit.c:circo_layout */
+export function circoLayoutFull(g: Graph): void {
+  // C: gvLayoutJobs runs graph_init(g, LAYOUT_USES_RANKDIR) before circo_layout;
+  // circo 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 circular_init_edge -> common_init_edge creates the edge label; addXLabels
+  // (in gvPostprocess below) places it at the edge midpoint. @see circularinit.c:27
+  const measurer = layoutMeasurer(g);
+  if (measurer !== undefined) {
+    for (const e of g.edges) initEdgeLabels(e, g, measurer);
+  }
+  circoInitGraph(g);
+  circoLayout(g);
+  // ORDERING: alg freed HERE, before spline routing (matches C source).
+  freeNData(g);
+  // C: spline_edges(g) shifts pos to the origin, syncs coord (x72), and routes.
+  // splineEdgesShifted seeds a fresh node-extent bb BEFORE routing and
+  // clipAndInstall then EXPANDS it per installed bezier (C compute_bb +
+  // update_bb_bz) — a compass port can poke outside the node box, and the
+  // gvPostprocess translate must see that overhang. Do NOT recompute the bb
+  // from nodes here: it clobbers the spline expansion.
+  splineEdgesShifted(g);
+  // C: dotneato_postprocess(g) — cluster labels, then addXLabels (edge labels),
+  // root graph label space + translate. @see circularinit.c:233 circo_layout
+  placeGraphLabel(g);
+  gvPostprocess(g);
+}
+
+/** @see lib/circogen/circularinit.c:circo_cleanup */
+export function circoCleanup(g: Graph): void {
+  // Derived graph was stored in g.info.alg during circoLayout; clear it.
+  g.info.alg = undefined;
+  g.info.neato_nlist = undefined;
+}
+
+/**
+ * Registered layout engine for the 'circo' algorithm.
+ *
+ * @see lib/gvc/gvcext.h:gvlayout_engine_s
+ * @see lib/circogen/circularinit.c (plugin wiring)
+ */
+export const CIRCO_LAYOUT_ENGINE: LayoutEngine = {
+  type: 'circo',
+  layout: circoLayoutFull,
+  cleanup: circoCleanup,
+};

package/src/layout/circo/init.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Per-node ndata type and graph initialisation for the circo engine.
+ *
+ * Ports the ndata struct from lib/circogen/circular.h and the
+ * circo_init_graph / circular_init_node_edge functions from
+ * lib/circogen/circularinit.c.
+ *
+ * Note: CircoCData (cdata) lives in blocks.ts alongside DerivedNode to
+ * avoid a circular import — cdata holds a back-reference to DerivedNode.
+ *
+ * @see lib/circogen/circular.h:ndata
+ * @see lib/circogen/circularinit.c:circo_init_graph
+ */
+
+import type { Graph } from '../../model/graph.js';
+import { setEdgeTypeFromAttr } from '../dot/index.js';
+import { EDGETYPE_LINE } from '../neato/splines.js';
+import type { Node } from '../../model/node.js';
+
+// ---------------------------------------------------------------------------
+// ndata — lightweight wrapper stored during Pass 0 (original graph nodes)
+// @see lib/circogen/circular.h:ndata
+// ---------------------------------------------------------------------------
+
+/**
+ * Algorithm data stored in ND_alg on original-graph nodes during init.
+ * Maps each original node to its counterpart in the derived graph.
+ *
+ * MEMORY: In C all ndata objects are allocated as one contiguous array;
+ * only the first node's alg reference is nulled in cleanup
+ * (matches C single-free pattern).
+ *
+ * @see lib/circogen/circular.h:ndata
+ */
+export interface CircoNData {
+  readonly kind: 'circo-ndata';
+  /** Pointer to this node's counterpart in the derived graph. */
+  dnode: Node | null;
+}
+
+// ---------------------------------------------------------------------------
+// Graph init
+// @see lib/circogen/circularinit.c:circo_init_graph
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialise all nodes in g for the circo layout pass.
+ *
+ * Allocates a CircoNData per node, sets 2-D position arrays, and builds
+ * the neato_nlist — matching circular_init_node_edge in the C source.
+ *
+ * ORDERING: alg must be freed (via freeNData) before spline routing.
+ *
+ * @see lib/circogen/circularinit.c:circo_init_graph
+ * @see lib/circogen/circularinit.c:circular_init_node_edge
+ */
+export function circoInitGraph(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;
+  const nlist: Node[] = [];
+  for (const n of g.nodes.values()) {
+    const ndata: CircoNData = { kind: 'circo-ndata', dnode: null };
+    n.info.alg = ndata;
+    n.info.pos = [0, 0];
+    nlist.push(n);
+  }
+  g.info.neato_nlist = nlist;
+}
+
+/**
+ * Release ndata from the first node (frees the shared contiguous block in C).
+ * Must be called before spline routing.
+ *
+ * @see lib/circogen/circularinit.c:circo_layout (free ND_alg line)
+ */
+export function freeNData(g: Graph): void {
+  const first = g.info.neato_nlist?.[0];
+  if (first) first.info.alg = undefined;
+}

package/src/layout/circo/position-helpers.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Low-level rotation and delta-application helpers for block-tree positioning.
+ *
+ * Ports applyDelta and getRotation from lib/circogen/circpos.c.
+ * All functions are exported so lizard counts each one independently.
+ *
+ * @see lib/circogen/circpos.c
+ */
+
+import type { Node } from '../../model/node.js';
+import type { Block } from './blocks.js';
+import { isCoalesced } from './blocks.js';
+
+/** 2-D rotation of (x,y) by (cosR, sinR). */
+export function rotatePoint(
+  x: number, y: number, cosR: number, sinR: number,
+): [number, number] {
+  return [x * cosR - y * sinR, x * sinR + y * cosR];
+}
+
+/** Read psi from a node's alg field (set during Pass 4). */
+export function nodePsi(n: Node): number {
+  return (n.info.alg as { psi?: number } | undefined)?.psi ?? 0;
+}
+
+/** getRotation: single-node block with preset parent_pos. */
+export function rotFromParentPos(sn: Block, theta: number): number {
+  let r = theta + Math.PI - sn.parentPos;
+  if (r < 0) r += 2 * Math.PI;
+  return r;
+}
+
+/** Find the node in sn closest to origin after translation by (x,y). */
+export function closestNode(sn: Block, x: number, y: number, skip: Node): Node {
+  let best = skip;
+  let bestDist = Math.hypot(skip.info.pos![0]! + x, skip.info.pos![1]! + y);
+  for (const dn of sn.subGraph.nodes) {
+    if (dn.orig === skip) continue;
+    const d = Math.hypot(dn.orig.info.pos![0]! + x, dn.orig.info.pos![1]! + y);
+    if (d < bestDist) { bestDist = d; best = dn.orig; }
+  }
+  return best;
+}
+
+/** getRotation: COALESCED block — off-center trigonometric correction. */
+export function rotCoalesced(
+  sn: Block, x: number, y: number, nbr: Node, theta: number,
+): number {
+  const rho = sn.rad0;
+  const r = sn.radius - rho;
+  const nx = nbr.info.pos![0]!;
+  const ny = nbr.info.pos![1]!;
+  if (-r >= nx) {
+    const phi = Math.atan2(ny, nx);
+    return theta + Math.PI - phi - nodePsi(nbr);
+  }
+  const R = Math.hypot(x, y);
+  const phi = Math.atan2(ny, nx + r);
+  const l = r - rho / Math.cos(phi);
+  return theta + Math.PI / 2 - phi - Math.asin((l / R) * Math.cos(phi));
+}
+
+/** getRotation: general multi-node non-coalesced block. */
+export function rotGeneral(
+  sn: Block, x: number, y: number, nbr: Node, theta: number,
+): number {
+  if (closestNode(sn, x, y, nbr) === nbr) return 0;
+  if (isCoalesced(sn)) return rotCoalesced(sn, x, y, nbr, theta);
+  const phi = Math.atan2(nbr.info.pos![1]!, nbr.info.pos![0]!);
+  let r = theta + Math.PI - phi - nodePsi(nbr);
+  if (r > 2 * Math.PI) r -= 2 * Math.PI;
+  return r;
+}
+
+/**
+ * Apply rotation then translation to all nodes in sn and its children.
+ * @see lib/circogen/circpos.c:applyDelta
+ */
+export function applyDelta(sn: Block, x: number, y: number, rotate: number): void {
+  const cosR = Math.cos(rotate);
+  const sinR = Math.sin(rotate);
+  for (const dn of sn.subGraph.nodes) {
+    const pos = dn.orig.info.pos!;
+    const [X, Y] = rotatePoint(pos[0]!, pos[1]!, cosR, sinR);
+    pos[0] = X + x;
+    pos[1] = Y + y;
+  }
+  for (const child of sn.children) applyDelta(child, x, y, rotate);
+}
+
+/**
+ * Determine rotation angle for block sn given center offset (x, y).
+ * @see lib/circogen/circpos.c:getRotation
+ */
+export function getRotation(sn: Block, x: number, y: number, theta: number): number {
+  if (sn.parentPos >= 0) return rotFromParentPos(sn, theta);
+  if (sn.circleList.length === 2) return theta - Math.PI / 2;
+  // C: neighbor = CHILD(sn) — the node in sn connected to the parent.
+  const nbr = sn.child;
+  if (!nbr) return 0;
+  return rotGeneral(sn, x, y, nbr, theta);
+}

package/src/layout/circo/position.ts

@@ -0,0 +1,196 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Block-tree positioning orchestration for the circo layout engine.
+ *
+ * Ports getInfo, setInfo, positionChildren, position, doBlock, circPos
+ * from lib/circogen/circpos.c. All functions are exported so lizard
+ * counts each one independently.
+ *
+ * @see lib/circogen/circpos.c
+ */
+
+import type { Node } from '../../model/node.js';
+import type { Block, SubGraph, CircState } from './blocks.js';
+import { blkParent, setCoalesced, FLAGS_ISPARENT } from './blocks.js';
+import { applyDelta, getRotation } from './position-helpers.js';
+import { layoutBlock } from './blockpath.js';
+
+export type PosState = {
+  radius: number; subtreeR: number; nodeAngle: number;
+  firstAngle: number; lastAngle: number;
+  /** All child blocks of the block being positioned (C: sn->children list). */
+  cp: Block[]; neighbor: Node | null;
+};
+
+export type PosInfo = {
+  n: Node; theta: number; minRadius: number; maxRadius: number;
+  diameter: number; scale: number; childCount: number;
+};
+
+/** Context bundle for placeChild — keeps param count ≤5. */
+export type PlaceCtx = { childRadius: number; incAngle: number; mindistAngle: number; length: number };
+
+/** Child blocks attached at node n with a non-empty circle list. */
+export function childrenAtNode(stp: PosState, n: Node): Block[] {
+  return stp.cp.filter((c) => blkParent(c) === n && c.circleList.length > 0);
+}
+
+/** @see lib/circogen/circpos.c:getInfo */
+export function getInfo(pi: PosInfo, stp: PosState, minDist: number): number {
+  let maxR = 0; let diam = 0; let cnt = 0;
+  for (const c of stp.cp) {
+    if (blkParent(c) !== pi.n) continue;
+    cnt++; maxR = Math.max(maxR, c.radius); diam += 2 * c.radius + minDist;
+  }
+  pi.diameter = diam; pi.childCount = cnt;
+  pi.minRadius = stp.radius + minDist + maxR; pi.maxRadius = maxR;
+  return maxR;
+}
+
+/** @see lib/circogen/circpos.c:setInfo */
+export function setInfo(p0: PosInfo, p1: PosInfo, delta: number): void {
+  const t = Math.max(
+    (p0.diameter * p1.minRadius + p1.diameter * p0.minRadius)
+      / (2 * delta * p0.minRadius * p1.minRadius), 1,
+  );
+  p0.scale = Math.max(p0.scale, t);
+  p1.scale = Math.max(p1.scale, t);
+}
+
+/** Rotate and translate one child block; return advanced angle. */
+export function placeChild(child: Block, ca: number, ctx: PlaceCtx): number {
+  const dx = ctx.childRadius * Math.cos(ca);
+  const dy = ctx.childRadius * Math.sin(ca);
+  applyDelta(child, dx, dy, getRotation(child, dx, dy, ca));
+  return ctx.length === 1
+    ? ca + ctx.incAngle + ctx.mindistAngle
+    : ca + ctx.incAngle + ctx.mindistAngle / 2;
+}
+
+/** Advance child angle for length===1 blocks; updates firstAngle/lastAngle. */
+export function advanceAngleL1(
+  ca: number, inc: number, total: number, cnt: number, stp: PosState,
+): number {
+  const next = cnt === 0 ? 0 : (total === 2 ? Math.PI : ca + inc);
+  if (stp.firstAngle < 0) stp.firstAngle = next;
+  stp.lastAngle = next;
+  return next;
+}
+
+/** Advance child angle for multi-node blocks. */
+export function advanceAngleLN(ca: number, inc: number, mda: number, total: number, theta: number): number {
+  if (total === 1) return theta;
+  return ca + inc + mda / 2;
+}
+
+/** Write psi midpoint angle to node alg when conditions are met. */
+export function maybeWritePsi(n: Node, stp: PosState, ca: number, isMid: boolean): void {
+  if (isMid && n === stp.neighbor) {
+    const alg = n.info.alg as Record<string, unknown> | undefined;
+    if (alg) alg['psi'] = ca;
+  }
+}
+
+/** @see lib/circogen/circpos.c:positionChildren */
+export function positionChildren(pi: PosInfo, stp: PosState, length: number, minDist: number): void {
+  const children = childrenAtNode(stp, pi.n);
+  if (children.length === 0) return;
+  let cr = pi.scale * pi.minRadius;
+  let md = minDist;
+  if (length === 1) {
+    cr = Math.max(cr, pi.diameter / (2 * Math.PI));
+    // C redistributes leftover circumference into min_dist.
+    const d = 2 * Math.PI * cr - pi.diameter;
+    if (d > 0) md += d / pi.childCount;
+  }
+  stp.subtreeR = Math.max(stp.subtreeR, cr + pi.maxRadius);
+  const mda = md / cr;
+  let ca = length === 1 ? 0 : pi.theta - pi.diameter / (2 * cr);
+  const mid = Math.floor((pi.childCount + 1) / 2);
+  const ctx: PlaceCtx = { childRadius: cr, incAngle: 0, mindistAngle: mda, length };
+  let cnt = 0;
+  for (const child of children) {
+    ctx.incAngle = child.radius / cr;
+    ca = length === 1
+      ? advanceAngleL1(ca, ctx.incAngle, pi.childCount, cnt, stp)
+      : advanceAngleLN(ca, ctx.incAngle, mda, pi.childCount, pi.theta);
+    ca = placeChild(child, ca, ctx);
+    cnt++;
+    maybeWritePsi(pi.n, stp, ca, cnt === mid && length > 1);
+  }
+}
+
+/** Build PosInfo array for all articulation nodes in the circle path. */
+export function buildParents(nodepath: Node[], stp: PosState, minDist: number): PosInfo[] {
+  const parents: PosInfo[] = [];
+  for (let i = 0; i < nodepath.length; i++) {
+    const n = nodepath[i]!;
+    const flags = (n.info.alg as { flags?: number } | undefined)?.flags ?? 0;
+    if (!(flags & FLAGS_ISPARENT)) continue;
+    const pi: PosInfo = { n, theta: i * stp.nodeAngle, minRadius: 0, maxRadius: 0, diameter: 0, scale: 1.0, childCount: 0 };
+    getInfo(pi, stp, minDist);
+    parents.push(pi);
+  }
+  return parents;
+}
+
+/** Apply pairwise setInfo scale factors. */
+export function applyScaleFactors(parents: PosInfo[]): void {
+  if (parents.length < 2) return;
+  if (parents.length === 2) {
+    let d = parents[1]!.theta - parents[0]!.theta;
+    if (d > Math.PI) d = 2 * Math.PI - d;
+    setInfo(parents[0]!, parents[1]!, d); return;
+  }
+  for (let i = 0; i < parents.length; i++) {
+    const next = parents[(i + 1) % parents.length]!;
+    let d = next.theta - parents[i]!.theta;
+    if (d <= 0) d += 2 * Math.PI;
+    setInfo(parents[i]!, next, d);
+  }
+}
+
+/** Apply coalesce or expand radius after positioning children. */
+export function finaliseRadius(sn: Block, maxR: number, minDist: number, stp: PosState, childCount: number): void {
+  if (childCount === 1) {
+    applyDelta(sn, -(maxR + minDist / 2), 0, 0);
+    sn.radius += minDist / 2 + maxR;
+    setCoalesced(sn);
+  } else {
+    sn.radius = stp.subtreeR;
+  }
+}
+
+/** @see lib/circogen/circpos.c:position */
+export function position(childCount: number, length: number, nodepath: Node[], sn: Block, minDist: number): number {
+  const stp: PosState = {
+    cp: sn.children, subtreeR: sn.radius, radius: sn.radius,
+    // C: state.neighbor = CHILD(sn) — the cut node within this block.
+    neighbor: sn.child, nodeAngle: (2 * Math.PI) / length, firstAngle: -1, lastAngle: -1,
+  };
+  const parents = buildParents(nodepath, stp, minDist);
+  applyScaleFactors(parents);
+  let maxR = 0;
+  for (const pi of parents) { maxR = Math.max(maxR, pi.maxRadius); positionChildren(pi, stp, length, minDist); }
+  finaliseRadius(sn, maxR, minDist, stp, childCount);
+  return (stp.firstAngle + stp.lastAngle) / 2 - Math.PI;
+}
+
+/** @see lib/circogen/circpos.c:doBlock */
+export function doBlock(g: SubGraph, sn: Block, minDist: number, state: CircState): void {
+  let cc = 0;
+  for (const child of sn.children) { doBlock(g, child, minDist, state); cc++; }
+  const longest = layoutBlock(g, sn, minDist, state);
+  sn.circleList = longest;
+  let ca = Math.PI;
+  if (cc > 0) ca = position(cc, longest.length, longest, sn, minDist);
+  if (longest.length === 1 && blkParent(sn)) {
+    sn.parentPos = ca < 0 ? ca + 2 * Math.PI : ca;
+  }
+}
+
+/** @see lib/circogen/circpos.c:circPos */
+export function circPos(g: SubGraph, sn: Block, state: CircState): void {
+  doBlock(g, sn, state.minDist, state);
+}

package/src/layout/dot/__fixtures__/xcoord-pivot-divergence.gv

@@ -0,0 +1,79 @@
+strict digraph {
+rankdir=BT
+subgraph {
+"0_447" [label="GetElementPtr"]
+"0_441" [label="Load"]
+"0_447" -> "0_441"
+"0_449" [label="Load"]
+"0_449" -> "0_447"
+cluster=true
+label=<Static occurrences: 1678>
+}
+subgraph {
+"1_2630" [label="GetElementPtr"]
+"1_2626" [label="Phi"]
+"1_2630" -> "1_2626"
+"1_2631" [label="Load"]
+"1_2631" -> "1_2630"
+"1_2620" [label="Load"]
+"1_2626" -> "1_2620"
+cluster=true
+label=<Static occurrences: 655>
+}
+subgraph {
+"2_1303" [label="Store"]
+"2_1097" [label="Load"]
+"2_1303" -> "2_1097"
+cluster=true
+label=<Static occurrences: 491>
+}
+subgraph {
+"3_289" [label="Load"]
+"3_282" [label="Load"]
+"3_289" -> "3_282"
+cluster=true
+label=<Static occurrences: 317>
+}
+subgraph {
+"4_452" [label="GetElementPtr"]
+"4_447" [label="GetElementPtr"]
+"4_452" -> "4_447"
+"4_441" [label="Load"]
+"4_447" -> "4_441"
+"4_453" [label="Load"]
+"4_453" -> "4_452"
+cluster=true
+label=<Static occurrences: 269>
+}
+subgraph {
+"5_2634" [label="Load"]
+"5_2626" [label="Phi"]
+"5_2634" -> "5_2626"
+"5_2620" [label="Load"]
+"5_2626" -> "5_2620"
+cluster=true
+label=<Static occurrences: 261>
+}
+subgraph {
+"6_2661" [label="Add"]
+"6_2622" [label="Load"]
+"6_2661" -> "6_2622"
+"6_2662" [label="Store"]
+"6_2662" -> "6_2661"
+cluster=true
+label=<Static occurrences: 160>
+}
+subgraph {
+"7_109" [label="GetElementPtr"]
+"7_101" [label="Select"]
+"7_109" -> "7_101"
+"7_100" [label="ICmp"]
+"7_99" [label="Load"]
+"7_100" -> "7_99"
+"7_113" [label="Load"]
+"7_113" -> "7_109"
+"7_101" -> "7_100"
+cluster=true
+label=<Static occurrences: 126>
+}
+}

package/src/layout/dot/acyclic.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: EPL-2.0
+/** @see lib/dotgen/acyclic.c */
+import type { Node } from '../../model/node.js';
+import type { Graph } from '../../model/graph.js';
+import { reverseEdge } from './fastgr.js';
+
+interface DfsFrame { n: Node; i: number; }
+
+/** Advance the top frame one step: descend a tree edge (push), reverse a back
+ *  edge in place, or finish the node (clear onstack, pop). @see acyclic.c:dfs */
+function dfsStep(stack: DfsFrame[]): void {
+  const f = stack[stack.length - 1];
+  const out = f.n.info.out;
+  while (out && f.i < out.size) {
+    const e = out.list[f.i];
+    const w = e.head;
+    if (w.info.onstack) {
+      reverseEdge(e); // zapinlist swap-shrinks out; re-examine same slot
+    } else if (!w.info.mark) {
+      w.info.mark = 1;
+      w.info.onstack = 1;
+      f.i++; // advance past this tree edge before descending
+      stack.push({ n: w, i: 0 });
+      return; // descended
+    } else {
+      f.i++; // already visited, not on stack: skip
+    }
+  }
+  f.n.info.onstack = 0;
+  stack.pop();
+}
+
+/**
+ * Iterative DFS back-edge reversal (AD-3). The recursive form (C acyclic.c:dfs)
+ * descends to depth O(V) and overflows V8's small stack on deep chains; this
+ * explicit-stack form is browser-safe and bit-identical (same visit order,
+ * same `onstack` post-order, same in-place edge reversal).
+ * @see lib/dotgen/acyclic.c:dfs
+ */
+function dfs(start: Node): void {
+  if (start.info.mark) return;
+  start.info.mark = 1;
+  start.info.onstack = 1;
+  const stack: DfsFrame[] = [{ n: start, i: 0 }];
+  while (stack.length > 0) dfsStep(stack);
+}
+
+/**
+ * Break cycles in the fast graph by reversing DFS back edges.
+ * Reversed edges carry `EdgeInfo.reversed = true`.
+ * @see lib/dotgen/acyclic.c:acyclic
+ */
+export function acyclic(g: Graph): void {
+  const comp = g.info.comp ?? [];
+  for (let c = 0; c < comp.length; c++) {
+    g.info.nlist = comp[c];
+    for (let n: Node | undefined = comp[c]; n !== undefined; n = n.info.next) n.info.mark = 0;
+    for (let n: Node | undefined = comp[c]; n !== undefined; n = n.info.next) dfs(n);
+  }
+}

package/src/layout/dot/aspect.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Aspect ratio control for dot layout.
+ *
+ * The 'aspect' feature was never completed in Graphviz. This file exists
+ * to satisfy the pipeline call in dotinit.c.
+ *
+ * @see lib/dotgen/aspect.c
+ */
+
+import type { Graph } from '../../model/graph.js';
+
+/**
+ * Aspect ratio control — reads the 'aspect' attribute and would adjust
+ * layout, but the feature was never completed. This is a no-op.
+ *
+ * @see lib/dotgen/aspect.c:setAspect
+ */
+export function setAspect(_g: Graph): void {
+  /* aspect feature was never completed in Graphviz — no-op per AD in mission brief */
+}