@knowvah/dot-engine 0.1.0

package/src/layout/pack/index.ts

@@ -0,0 +1,570 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Public API for rectangle packing and connected-component decomposition.
+ * Ports lib/pack/pack.c and lib/pack/ccomps.c.
+ *
+ * @see lib/pack/pack.c
+ * @see lib/pack/ccomps.c
+ */
+
+import type { Graph } from '../../model/graph.js';
+import type { Node } from '../../model/node.js';
+import type { Edge } from '../../model/edge.js';
+import type { Box, Point } from '../../model/geom.js';
+import type { ArrowDrawOp } from '../../common/arrows-types.js';
+import { mapArrowOpPoints } from '../../common/arrows-shapes-util.js';
+import { arrayRects } from './array-pack.js';
+import { polyRects } from './poly-pack.js';
+import { updateBbBz } from '../../common/splines-geom.js';
+import { polyGraphs } from './poly-place.js';
+import {
+  PackMode, PackInfo,
+  PS2INCH, PK_COL_MAJOR, PK_USER_VALS, PK_LEFT_ALIGN,
+  PK_RIGHT_ALIGN, PK_TOP_ALIGN, PK_BOT_ALIGN, PK_INPUT_ORDER,
+} from './types.js';
+
+export {
+  PackMode, PS2INCH,
+  PK_COL_MAJOR, PK_USER_VALS, PK_LEFT_ALIGN, PK_RIGHT_ALIGN,
+  PK_TOP_ALIGN, PK_BOT_ALIGN, PK_INPUT_ORDER,
+};
+export type { PackInfo };
+export { ps2inch, inch2ps } from './types.js';
+
+// ---------------------------------------------------------------------------
+// putRects / packRects
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute bounding-box packing offsets for ng bare rectangles.
+ * Returns null for Aspect mode (not implemented in C) or Node/Cluster mode
+ * (no node geometry available).
+ * @see lib/pack/pack.c:putRects
+ */
+export function putRects(ng: number, bbs: Box[], pinfo: PackInfo): Point[] | null {
+  if (ng <= 0) return [];
+  if (pinfo.mode === PackMode.Aspect) return null;
+  if (pinfo.mode === PackMode.Node || pinfo.mode === PackMode.Cluster) return null;
+  if (pinfo.mode === PackMode.Array) return arrayRects(ng, bbs, pinfo);
+  return polyRects(ng, bbs, pinfo);
+}
+
+/**
+ * Pack bare rectangles; updates bbs in place. Returns 0 on success.
+ * @see lib/pack/pack.c:packRects
+ */
+export function packRects(ng: number, bbs: Box[], pinfo: PackInfo): number {
+  const pts = putRects(ng, bbs, pinfo);
+  if (!pts) return -1;
+  for (let i = 0; i < ng; i++) {
+    const w = bbs[i].ur.x - bbs[i].ll.x;
+    const h = bbs[i].ur.y - bbs[i].ll.y;
+    bbs[i].ll.x = pts[i].x;
+    bbs[i].ll.y = pts[i].y;
+    bbs[i].ur.x = pts[i].x + w;
+    bbs[i].ur.y = pts[i].y + h;
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Graph bounding-box extraction
+// ---------------------------------------------------------------------------
+
+/** Node x-coordinate (0 if unset). */
+export function nodeCoordX(n: Node): number {
+  return n.info.coord !== undefined ? n.info.coord.x : 0;
+}
+/** Node y-coordinate (0 if unset). */
+export function nodeCoordY(n: Node): number {
+  return n.info.coord !== undefined ? n.info.coord.y : 0;
+}
+/** Expand accumulated bounds by one node. */
+export function expandBounds(
+  b: { llx: number; lly: number; urx: number; ury: number },
+  n: Node, margin: number,
+): void {
+  const x = nodeCoordX(n);
+  const y = nodeCoordY(n);
+  const lw = n.info.lw !== undefined ? n.info.lw : 18;
+  const rw = n.info.rw !== undefined ? n.info.rw : 18;
+  const ht = n.info.ht !== undefined ? n.info.ht : 18;
+  b.llx = Math.min(b.llx, x - lw - margin);
+  b.lly = Math.min(b.lly, y - ht / 2 - margin);
+  b.urx = Math.max(b.urx, x + rw + margin);
+  b.ury = Math.max(b.ury, y + ht / 2 + margin);
+}
+/**
+ * Expand accumulated bounds by one edge's routed spline and its labels.
+ *
+ * C's `compute_bb` walks every out-edge of every node and expands the box over
+ * each bezier's control points, then over the edge's centre/head/tail/x labels
+ * when they are `set`. Splines that bulge outside the node hull — a self-loop,
+ * a curved or ported edge, a flat edge routed around a node — therefore belong
+ * to the graph box. Omitting them truncates the graph bb (and, since the
+ * background `filled_polygon` is drawn from the bb, the drawn background too):
+ * a lone node with a self-loop reports a 54pt-wide graph instead of 72pt,
+ * because the loop bulges 18pt to the node's right.
+ *
+ * `bz.size` — never `bz.list.length` — bounds the point loop: the point lists
+ * are over-allocated, exactly as C's `ED_spl(e)->list[i].size` bounds its own.
+ *
+ * @see lib/common/utils.c:633 compute_bb (the `for (e = agfstout(g, n); ...)` arm)
+ */
+function expandBoundsByEdge(
+  b: { llx: number; lly: number; urx: number; ury: number },
+  e: Edge, flip: boolean, refineSplines: boolean,
+): void {
+  const spl = e.info.spl;
+  if (spl !== undefined && refineSplines) {
+    // Single-component neato-family final bb: native never re-runs compute_bb
+    // after routing, so the edge contribution is the curve grown by
+    // update_bb_bz in clip_and_install (emit.c:746), strictly inside the
+    // control hull. Refine each cubic to the curve so a middle control point
+    // outside the curve does not inflate the box.
+    const box: Box = { ll: { x: b.llx, y: b.lly }, ur: { x: b.urx, y: b.ury } };
+    for (let i = 0; i < spl.size; i++) {
+      const bz = spl.list[i];
+      if (bz === undefined) continue;
+      for (let j = 0; j + 3 < bz.size; j += 3) {
+        const p0 = bz.list[j];
+        const p1 = bz.list[j + 1];
+        const p2 = bz.list[j + 2];
+        const p3 = bz.list[j + 3];
+        if (p0 && p1 && p2 && p3) updateBbBz(box, [p0, p1, p2, p3]);
+      }
+    }
+    b.llx = box.ll.x;
+    b.lly = box.ll.y;
+    b.urx = box.ur.x;
+    b.ury = box.ur.y;
+  } else if (spl !== undefined) {
+    // Pack / multi-component path: native's pack re-runs compute_bb AFTER
+    // routing (pack.c:801), which unions raw control points (ED_spl). Match it.
+    for (let i = 0; i < spl.size; i++) {
+      const bz = spl.list[i];
+      if (bz === undefined) continue;
+      for (let j = 0; j < bz.size; j++) {
+        const p = bz.list[j];
+        if (p === undefined) continue;
+        b.llx = Math.min(b.llx, p.x);
+        b.lly = Math.min(b.lly, p.y);
+        b.urx = Math.max(b.urx, p.x);
+        b.ury = Math.max(b.ury, p.y);
+      }
+    }
+  }
+  for (const l of [e.info.label, e.info.head_label, e.info.tail_label, e.info.xlabel]) {
+    if (l === undefined || l.set !== true) continue;
+    // C addLabelBB: under flip (rankdir=LR/RL) the stored dimen axes swap.
+    // @see lib/common/utils.c:569 addLabelBB
+    const hw = (flip ? l.dimen.y : l.dimen.x) / 2;
+    const hh = (flip ? l.dimen.x : l.dimen.y) / 2;
+    b.llx = Math.min(b.llx, l.pos.x - hw);
+    b.lly = Math.min(b.lly, l.pos.y - hh);
+    b.urx = Math.max(b.urx, l.pos.x + hw);
+    b.ury = Math.max(b.ury, l.pos.y + hh);
+  }
+}
+
+/**
+ * Compute a graph's bounding box: node extents, plus every routed edge spline
+ * and edge label.
+ *
+ * This is the port of C's `compute_bb` — the final bb of every non-dot engine
+ * (neato/fdp/sfdp/circo/twopi/osage all reach it, and `pack` uses it for
+ * component boxes; dot sets its own bb in `set_aspect`). It was node-only until
+ * 2026-07-12, which truncated the box of any graph whose edges leave the node
+ * hull; see `expandBoundsByEdge`.
+ *
+ * DELIBERATE DEVIATION from C's `compute_bb`, which also expands over node
+ * xlabels, cluster bbs, and the graph label: the port already grows the bb for
+ * those in dedicated passes (the xlabel placement pass, `addClusters`, and
+ * `placeGraphLabel`, each of which runs after this call and expands
+ * `g.info.bb`). Folding them in here as well would double-expand rather than
+ * match C. The edge arm has no such counterpart pass — it was simply missing.
+ *
+ * @see lib/common/utils.c:633 compute_bb
+ * @see lib/neatogen/neatoinit.c:1419 (compute_bb called right after spline_edges)
+ * @see lib/pack/pack.c:801 computeBB
+ */
+export function computeSubgraphBB(g: Graph, margin: number, refineSplines = false): Box {
+  const b = { llx: Infinity, lly: Infinity, urx: -Infinity, ury: -Infinity };
+  for (const n of g.nodes.values()) expandBounds(b, n, margin);
+  const flip = g.info.flip === true;
+  for (const e of g.edges) expandBoundsByEdge(b, e, flip, refineSplines);
+  if (!isFinite(b.llx)) return { ll: { x: 0, y: 0 }, ur: { x: 0, y: 0 } };
+  return { ll: { x: b.llx, y: b.lly }, ur: { x: b.urx, y: b.ury } };
+}
+
+/** Extract bounding boxes for an array of subgraphs. */
+export function subgraphBBs(gs: Graph[], margin: number): Box[] {
+  return gs.map(g => computeSubgraphBB(g, margin));
+}
+
+// ---------------------------------------------------------------------------
+// putGraphs / packGraphs / packSubgraphs
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute packing translation deltas for ng pre-laid-out subgraphs.
+ * Bounding boxes are raw (C compute_bb has no margin; the packers add
+ * the margin themselves).
+ * @see lib/pack/pack.c:putGraphs
+ */
+export function putGraphs(ng: number, gs: Graph[], root: Graph, pinfo: PackInfo): Point[] | null {
+  if (ng <= 0) return null;
+  const bbs = gs.map((g) => {
+    const bb = computeSubgraphBB(g, 0);
+    g.info.bb = bb;
+    return bb;
+  });
+  if (pinfo.mode <= PackMode.Graph) return polyGraphs(gs, root, pinfo, bbs);
+  if (pinfo.mode === PackMode.Array) {
+    if (pinfo.flags & PK_USER_VALS) {
+      pinfo.vals = gs.map((g) => {
+        const v = parseInt(g.attrs.get('sortv') ?? '', 10);
+        return !Number.isNaN(v) && v >= 0 ? v : 0;
+      });
+    }
+    return arrayRects(ng, bbs, pinfo);
+  }
+  return null;
+}
+
+/**
+ * Pack subgraphs; returns 0 on success.
+ * @see lib/pack/pack.c:packGraphs
+ */
+export function packGraphs(ng: number, gs: Graph[], root: Graph, pinfo: PackInfo): number {
+  const pts = putGraphs(ng, gs, root, pinfo);
+  if (!pts) return -1;
+  return shiftGraphs(ng, gs, pts, root, pinfo.doSplines);
+}
+
+/**
+ * Pack subgraphs and update root bounding box.
+ * @see lib/pack/pack.c:packSubgraphs
+ */
+export function packSubgraphs(ng: number, gs: Graph[], root: Graph, pinfo: PackInfo): number {
+  const rc = packGraphs(ng, gs, root, pinfo);
+  if (rc === 0) root.info.bb = computeSubgraphBB(root, 0);
+  return rc;
+}
+
+// ---------------------------------------------------------------------------
+// shiftGraphs
+// ---------------------------------------------------------------------------
+
+/** Shift all nodes in g by (dx, dy) points. @see lib/pack/pack.c:shiftGraph */
+/**
+ * Shift a graph's bb, label position, and all nested cluster bbs.
+ * @see lib/pack/pack.c:shiftGraph
+ */
+export function shiftGraphBBs(g: Graph, dx: number, dy: number): void {
+  const bb = g.info.bb as Box | undefined;
+  if (bb !== undefined) {
+    g.info.bb = {
+      ll: { x: bb.ll.x + dx, y: bb.ll.y + dy },
+      ur: { x: bb.ur.x + dx, y: bb.ur.y + dy },
+    };
+  }
+  const lab = g.info.label as { set?: boolean; pos?: Point } | undefined;
+  if (lab?.set && lab.pos) {
+    lab.pos = { x: lab.pos.x + dx, y: lab.pos.y + dy };
+  }
+  const nClust = g.info.n_cluster ?? 0;
+  for (let c = 1; c <= nClust; c++) {
+    const sub = g.info.clust?.[c - 1];
+    if (sub) shiftGraphBBs(sub, dx, dy);
+  }
+}
+
+/** Translate an edge's spline points and all four label kinds.
+ * C shiftEdge moves ED_label, ED_xlabel, ED_head_label, ED_tail_label — every
+ * one, in that order — before the spline. Omitting the port (head/tail) or
+ * external labels leaves them behind the shift delta when normalizeGraphBB
+ * translates a label-expanded drawing to origin (twopi 144 head/tail-label
+ * x-offset). @see lib/pack/pack.c:shiftEdge */
+export function shiftEdgePoints(e: Edge, dx: number, dy: number): void {
+  const moveLabel = (raw: unknown): void => {
+    const lab = raw as { pos?: Point } | undefined;
+    if (lab?.pos) lab.pos = { x: lab.pos.x + dx, y: lab.pos.y + dy };
+  };
+  moveLabel(e.info.label);
+  moveLabel(e.info.xlabel);
+  moveLabel(e.info.head_label);
+  moveLabel(e.info.tail_label);
+  const spl = e.info.spl;
+  if (!spl) return;
+  for (const bz of spl.list) {
+    for (let k = 0; k < bz.size; k++) {
+      const p = bz.list[k]!;
+      bz.list[k] = { x: p.x + dx, y: p.y + dy };
+    }
+    if (bz.sflag) bz.sp = { x: bz.sp.x + dx, y: bz.sp.y + dy };
+    if (bz.eflag) bz.ep = { x: bz.ep.x + dx, y: bz.ep.y + dy };
+  }
+  // The port pre-computes arrowhead draw-ops during routing (C regenerates
+  // them at render time from the shifted ep/sp) — every rigid shift of the
+  // spline must carry them along or arrows lag by the shift delta.
+  const shiftOps = (ops: ArrowDrawOp[] | undefined): ArrowDrawOp[] | undefined =>
+    ops?.map((op) => mapArrowOpPoints(op, (p) => ({ x: p.x + dx, y: p.y + dy })));
+  e.info.headArrowOps = shiftOps(e.info.headArrowOps);
+  e.info.tailArrowOps = shiftOps(e.info.tailArrowOps);
+}
+
+export function shiftOneGraph(g: Graph, dx: number, dy: number): void {
+  for (const n of g.nodes.values()) {
+    const c = n.info.coord ?? { x: 0, y: 0 };
+    n.info.coord = { x: c.x + dx, y: c.y + dy };
+    if (n.info.pos) {
+      // pos is in inches — convert point delta to inches
+      n.info.pos[0] = (n.info.pos[0] ?? 0) + dx * PS2INCH;
+      n.info.pos[1] = (n.info.pos[1] ?? 0) + dy * PS2INCH;
+    }
+  }
+  // C shiftGraphs also translates routed splines (doSplines).
+  for (const e of g.edges) shiftEdgePoints(e, dx, dy);
+  // C shiftGraph also translates the graph/cluster bb tree and labels.
+  shiftGraphBBs(g, dx, dy);
+}
+
+/**
+ * Normalize bb.ll to (0,0) by shifting all nodes, edges, and the bb itself.
+ * Uses g.info.bb.ll (which includes spline extent from clipAndInstall) as the
+ * translation offset — matching C's translate_drawing which reads GD_bb(g).LL
+ * after clip_and_install has expanded it via update_bb_bz. A node-only
+ * recompute here would discard spline extent (twopi-self-loop divergence).
+ * @see lib/common/postproc.c:translate_drawing
+ * @see lib/common/splines.c:clip_and_install
+ */
+export function normalizeGraphBB(g: Graph): void {
+  const ll = g.info.bb.ll;
+  if (ll.x !== 0 || ll.y !== 0) {
+    shiftOneGraph(g, -ll.x, -ll.y);
+    // g.info.bb updated by shiftOneGraph → shiftGraphBBs; no recompute needed.
+  }
+}
+
+/**
+ * Apply packing translation DELTAS to subgraphs; shifts coords, pos,
+ * bbs, labels, and cluster bbs. Spline shifting (doSplines) is not
+ * ported — no packing caller has routed edges before packing yet.
+ * @see lib/pack/pack.c:shiftGraphs
+ */
+export function shiftGraphs(
+  ng: number, gs: Graph[], pp: Point[], _root: Graph, _doSplines: boolean,
+): number {
+  for (let i = 0; i < ng; i++) {
+    const dx = pp[i].x;
+    const dy = pp[i].y;
+    if (dx !== 0 || dy !== 0) shiftOneGraph(gs[i], dx, dy);
+  }
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Component decomposition (ccomps.c)
+// ---------------------------------------------------------------------------
+
+/** DFS to collect connected component nodes. @see lib/pack/ccomps.c */
+export function dfsCollect(g: Graph, start: Node, visited: Set<string>): Node[] {
+  const stack: Node[] = [start];
+  const comp: Node[] = [];
+  while (stack.length > 0) {
+    const n = stack.pop()!;
+    if (visited.has(n.name)) continue;
+    visited.add(n.name);
+    comp.push(n);
+    for (const e of g.edges) {
+      if (e.tail === n && !visited.has(e.head.name)) stack.push(e.head);
+      if (e.head === n && !visited.has(e.tail.name)) stack.push(e.tail);
+    }
+  }
+  return comp;
+}
+
+/** Build a subgraph containing only nodes. @see lib/pack/ccomps.c */
+export function buildSubgraph(root: Graph, nodes: Node[], name: string): Graph {
+  const sg = new (root.constructor as { new(name: string, kind: string): Graph })(name, 'directed');
+  sg.info.dotroot = root;
+  // C ccomps creates components via agsubg: sg->root is the original
+  // root graph, so root attrs (ranksep etc.) stay visible, and
+  // iteration order is the root-creation (ID) order.
+  sg.parent = root;
+  sg.root = root.root;
+  for (const n of [...nodes].sort((a, b) => a.id - b.id)) sg.nodes.set(n.name, n);
+  // Induce the component's edges (graphviz_node_induce equivalent).
+  const ns = new Set(nodes);
+  sg.edges = root.edges.filter((e) => ns.has(e.tail) && ns.has(e.head));
+  return sg;
+}
+
+/**
+ * Decompose g into connected components (nodes only, no edges).
+ * @see lib/pack/ccomps.c:ccomps
+ */
+export function ccomps(g: Graph, pfx: string): Graph[] {
+  const visited = new Set<string>();
+  const result: Graph[] = [];
+  let idx = 0;
+  for (const n of g.nodes.values()) {
+    if (visited.has(n.name)) continue;
+    const comp = dfsCollect(g, n, visited);
+    result.push(buildSubgraph(g, comp, `${pfx}_${idx++}`));
+  }
+  return result;
+}
+
+/**
+ * ccomps variant — same as ccomps for this port.
+ * @see lib/pack/ccomps.c:cccomps
+ */
+export function cccomps(g: Graph, pfx: string): Graph[] {
+  return ccomps(g, pfx);
+}
+
+/**
+ * ccomps with pinned-node detection.
+ * @see lib/pack/ccomps.c:pccomps
+ */
+export function pccomps(g: Graph, pfx: string): { graphs: Graph[]; pinned: boolean } {
+  // C first collects every component containing a pinned node into a single
+  // subgraph at index 0 (pin=true), then the remaining components in
+  // agfstnode order. Mirror that ordering so the fixed[0] flag and packing
+  // arrangement match. @see lib/pack/ccomps.c:pccomps
+  const visited = new Set<string>();
+  const result: Graph[] = [];
+  let idx = 0;
+  let pinned = false;
+
+  // Pass 1 — all pinned-node components merged into one subgraph (index 0).
+  const pinnedNodes: Node[] = [];
+  for (const n of g.nodes.values()) {
+    if (visited.has(n.name) || !n.info.pinned) continue;
+    for (const m of dfsCollect(g, n, visited)) pinnedNodes.push(m);
+    pinned = true;
+  }
+  if (pinnedNodes.length > 0) {
+    result.push(buildSubgraph(g, pinnedNodes, `${pfx}_${idx++}`));
+  }
+
+  // Pass 2 — remaining components in node order.
+  for (const n of g.nodes.values()) {
+    if (visited.has(n.name)) continue;
+    const comp = dfsCollect(g, n, visited);
+    result.push(buildSubgraph(g, comp, `${pfx}_${idx++}`));
+  }
+  return { graphs: result, pinned };
+}
+
+/** True if g has exactly one connected component. @see lib/pack/ccomps.c:isConnected */
+export function isConnected(g: Graph): boolean {
+  return ccomps(g, '__chk').length <= 1;
+}
+
+// ---------------------------------------------------------------------------
+// Attribute readers
+// ---------------------------------------------------------------------------
+
+/** Per-flag-character pinfo flag bits. @see lib/pack/pack.c:chkFlags */
+const PACK_FLAG_CHARS: Record<string, number> = {
+  c: PK_COL_MAJOR,
+  i: PK_INPUT_ORDER,
+  u: PK_USER_VALS,
+  t: PK_TOP_ALIGN,
+  b: PK_BOT_ALIGN,
+  l: PK_LEFT_ALIGN,
+  r: PK_RIGHT_ALIGN,
+};
+
+/**
+ * Consume an optional `_<flags>` suffix after "array", OR-ing flag
+ * bits into pinfo. Returns the rest of the string (possible column
+ * count). @see lib/pack/pack.c:chkFlags
+ */
+export function chkFlags(p: string, pinfo: PackInfo): string {
+  if (!p.startsWith('_')) return p;
+  let i = 1;
+  while (i < p.length) {
+    const bit = PACK_FLAG_CHARS[p[i]!];
+    if (bit === undefined) break;
+    pinfo.flags |= bit;
+    i++;
+  }
+  return p.slice(i);
+}
+
+/** Parse pack mode from string attribute. @see lib/pack/pack.c:parsePackModeInfo */
+export function parsePackModeInfo(p: string, dflt: PackMode, pinfo: PackInfo): PackMode {
+  pinfo.flags = 0;
+  pinfo.mode = dflt;
+  pinfo.sz = 0;
+  pinfo.vals = null;
+  if (p.startsWith('array')) {
+    pinfo.mode = PackMode.Array;
+    const rest = chkFlags(p.slice('array'.length), pinfo);
+    const i = parseInt(rest, 10);
+    if (!Number.isNaN(i) && i > 0) pinfo.sz = i;
+  } else if (p.startsWith('aspect')) {
+    pinfo.mode = PackMode.Aspect;
+    const v = parseFloat(p.slice('aspect'.length));
+    pinfo.aspect = !Number.isNaN(v) && v > 0 ? v : 1;
+  } else if (p === 'cluster') {
+    pinfo.mode = PackMode.Cluster;
+  } else if (p === 'graph') {
+    pinfo.mode = PackMode.Graph;
+  } else if (p === 'node') {
+    pinfo.mode = PackMode.Node;
+  }
+  return pinfo.mode;
+}
+
+/** Graph attr with root-default fallback (agget semantics for graphs). */
+function graphAttr(g: Graph, key: string): string | undefined {
+  return g.attrs.get(key) ?? (g !== g.root ? g.root.attrs.get(key) : undefined);
+}
+
+/** Read pack mode from the "packmode" graph attr. @see lib/pack/pack.c:getPackModeInfo */
+export function getPackModeInfo(g: Graph, dflt: PackMode, pinfo: PackInfo): PackMode {
+  return parsePackModeInfo(graphAttr(g, 'packmode') ?? '', dflt, pinfo);
+}
+
+/** Get pack mode from graph. @see lib/pack/pack.c:getPackMode */
+export function getPackMode(g: Graph, dflt: PackMode): PackMode {
+  const pinfo: PackInfo = { aspect: 0, sz: 0, margin: 0, doSplines: false, mode: dflt, fixed: null, vals: null, flags: 0 };
+  return getPackModeInfo(g, dflt, pinfo);
+}
+
+/**
+ * Read the "pack" graph attr: unset → notDef; non-negative int →
+ * value; true-ish ('t'/'T') → dflt; otherwise notDef.
+ * @see lib/pack/pack.c:getPack
+ */
+export function getPack(g: Graph, notDef: number, dflt: number): number {
+  const p = graphAttr(g, 'pack');
+  if (p === undefined) return notDef;
+  const i = parseInt(p, 10);
+  if (!Number.isNaN(i) && i >= 0) return i;
+  if (p[0] === 't' || p[0] === 'T') return dflt;
+  return notDef;
+}
+
+/** Populate PackInfo from graph attributes. @see lib/pack/pack.c:getPackInfo */
+export function getPackInfo(g: Graph, dflt: PackMode, dfltMargin: number, pinfo: PackInfo): PackMode {
+  pinfo.margin = getPack(g, dfltMargin, dfltMargin);
+  pinfo.doSplines = false;
+  pinfo.flags = 0;
+  pinfo.fixed = null;
+  pinfo.vals = null;
+  pinfo.sz = 0;
+  pinfo.aspect = 1;
+  return getPackModeInfo(g, dflt, pinfo);
+}
+
+/** @see lib/pack/ccomps.c:mapClust */
+export function mapClust(cl: Graph): Graph {
+  return cl;
+}