@knowvah/dot-engine 0.1.0

package/src/api/builder.ts

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Programmatic graph builder — constructs a Graph model without emitting DOT.
+ *
+ * Exposes lightweight typed handles (GvNode, GvEdge) that wrap internal
+ * model references without leaking the mutable model classes (ADR-1, ADR-6,
+ * ADR-8).
+ *
+ * @see lib/cgraph/graph.c:agopen
+ * @see lib/cgraph/node.c:agnode
+ * @see lib/cgraph/subg.c:agsubg
+ */
+
+import { Graph, type GraphKind } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import type { Edge } from '../model/edge.js';
+import { agnode, agsubg, agsubnode } from '../model/cgraph-ops.js';
+import { addEdge as cgraphAddEdge } from './edge-ops.js';
+import { RenderError } from '../errors.js';
+import { HTML_STRING_MARK } from '../common/html-string.js';
+
+// ── Public interfaces ──────────────────────────────────────────────────────────
+
+/** Options for createGraph. */
+export interface CreateGraphOptions {
+  directed?: boolean;
+  strict?: boolean;
+  name?: string;
+}
+
+/**
+ * Opaque handle for a graph node.
+ * @see lib/cgraph/cgraph.h:Agnode_s
+ */
+export interface GvNode {
+  readonly name: string;
+  setAttr(k: string, v: string): void;
+  /**
+   * Set an attribute to an HTML-string value (e.g. `label` to an HTML-table
+   * label). Equivalent to `label=<...>` in DOT text: the value is tagged as
+   * HTML so the layout engine measures it as markup, not as literal text.
+   * @see lib/cgraph/refstr.c:aghtmlstr
+   */
+  setHtmlAttr(k: string, v: string): void;
+  getAttr(k: string): string | undefined;
+}
+
+/**
+ * Opaque handle for a graph edge.
+ * @see lib/cgraph/cgraph.h:Agedge_s
+ */
+export interface GvEdge {
+  readonly tail: string;
+  readonly head: string;
+  setAttr(k: string, v: string): void;
+  /**
+   * Set an attribute to an HTML-string value (e.g. an HTML-table edge label).
+   * @see GvNode.setHtmlAttr
+   */
+  setHtmlAttr(k: string, v: string): void;
+  getAttr(k: string): string | undefined;
+}
+
+/**
+ * Builder returned by createGraph. Provides idiomatic programmatic
+ * construction of a graph model.
+ */
+export interface GvGraphBuilder {
+  addNode(name: string, attrs?: Record<string, string>): GvNode;
+  addEdge(
+    tail: GvNode | string,
+    head: GvNode | string,
+    attrs?: Record<string, string>,
+  ): GvEdge;
+  addSubgraph(name: string, attrs?: Record<string, string>): GvGraphBuilder;
+  setAttr(k: string, v: string): void;
+  /**
+   * Set an attribute on this (sub)graph to an HTML-string value — the
+   * supported way to give a cluster an HTML-table `label` (the header-size
+   * reservation the jar drives) without hand-writing the internal marker.
+   * @see GvNode.setHtmlAttr
+   */
+  setHtmlAttr(k: string, v: string): void;
+  getAttr(k: string): string | undefined;
+  readonly graph: Graph;
+}
+
+// ── Internal handle implementations ──────────────────────────────────────────
+
+/** Internal node handle — wraps Node ref without leaking the class. */
+class NodeHandle implements GvNode {
+  /** @internal */ readonly _node: Node;
+
+  constructor(node: Node) {
+    this._node = node;
+  }
+
+  get name(): string {
+    return this._node.name;
+  }
+
+  setAttr(k: string, v: string): void {
+    this._node.attrs.set(k, v);
+  }
+
+  setHtmlAttr(k: string, v: string): void {
+    this._node.attrs.set(k, HTML_STRING_MARK + v);
+  }
+
+  getAttr(k: string): string | undefined {
+    return this._node.attrs.get(k);
+  }
+}
+
+/** Internal edge handle — wraps Edge ref without leaking the class. */
+class EdgeHandle implements GvEdge {
+  /** @internal */ readonly _edge: Edge;
+
+  constructor(edge: Edge) {
+    this._edge = edge;
+  }
+
+  get tail(): string {
+    return this._edge.tail.name;
+  }
+
+  get head(): string {
+    return this._edge.head.name;
+  }
+
+  setAttr(k: string, v: string): void {
+    this._edge.attrs.set(k, v);
+  }
+
+  setHtmlAttr(k: string, v: string): void {
+    this._edge.attrs.set(k, HTML_STRING_MARK + v);
+  }
+
+  getAttr(k: string): string | undefined {
+    return this._edge.attrs.get(k);
+  }
+}
+
+// ── Builder implementation ─────────────────────────────────────────────────────
+
+/** Resolve a GvNode handle or a name string to an internal Node. */
+function resolveNode(g: Graph, ref: GvNode | string): Node {
+  if (typeof ref === 'string') {
+    const node = agnode(g, ref, true);
+    if (node === null) {
+      throw new RenderError(`Failed to resolve node '${ref}' in graph '${g.name}'`, 'GENERIC_ERROR');
+    }
+    return node;
+  }
+  return (ref as NodeHandle)._node;
+}
+
+/** Apply an attrs Record to a Map. */
+function applyAttrs(
+  map: Map<string, string>,
+  attrs: Record<string, string> | undefined,
+): void {
+  if (attrs === undefined) return;
+  for (const [k, v] of Object.entries(attrs)) {
+    map.set(k, v);
+  }
+}
+
+/**
+ * Builder backed by a Graph + optional subgraph context.
+ * Root builder: _context === _graph (the root Graph).
+ * Subgraph builder: _context is the subgraph; _graph is always the root.
+ */
+class GraphBuilder implements GvGraphBuilder {
+  private readonly _graph: Graph;
+  private readonly _context: Graph;
+
+  constructor(graph: Graph, context: Graph) {
+    this._graph = graph;
+    this._context = context;
+  }
+
+  get graph(): Graph {
+    return this._graph;
+  }
+
+  addNode(name: string, attrs?: Record<string, string>): GvNode {
+    return addNodeToContext(this._graph, this._context, name, attrs);
+  }
+
+  addEdge(
+    tail: GvNode | string,
+    head: GvNode | string,
+    attrs?: Record<string, string>,
+  ): GvEdge {
+    const tailNode = resolveNode(this._graph, tail);
+    const headNode = resolveNode(this._graph, head);
+    const edge = cgraphAddEdge(this._graph, tailNode, headNode);
+    applyAttrs(edge.attrs, attrs);
+    return new EdgeHandle(edge);
+  }
+
+  addSubgraph(name: string, attrs?: Record<string, string>): GvGraphBuilder {
+    const sg = agsubg(this._context, name, true);
+    if (sg === null) {
+      throw new RenderError(`Failed to create subgraph '${name}'`, 'GENERIC_ERROR');
+    }
+    applyAttrs(sg.attrs, attrs);
+    return new GraphBuilder(this._graph, sg);
+  }
+
+  setAttr(k: string, v: string): void {
+    this._context.attrs.set(k, v);
+  }
+
+  setHtmlAttr(k: string, v: string): void {
+    this._context.attrs.set(k, HTML_STRING_MARK + v);
+  }
+
+  getAttr(k: string): string | undefined {
+    return this._context.attrs.get(k);
+  }
+}
+
+/**
+ * Create a node in root and, when context is a subgraph, install it there too.
+ * Extracted to keep GraphBuilder.addNode below the CCN/length threshold.
+ */
+function addNodeToContext(
+  root: Graph,
+  context: Graph,
+  name: string,
+  attrs: Record<string, string> | undefined,
+): GvNode {
+  const node = agnode(root, name, true);
+  if (node === null) throw new RenderError(`Failed to create node '${name}'`, 'GENERIC_ERROR');
+  applyAttrs(node.attrs, attrs);
+  if (context !== root) agsubnode(context, node, true);
+  return new NodeHandle(node);
+}
+
+// ── GraphKind mapping ──────────────────────────────────────────────────────────
+
+/**
+ * Lookup table: [directed][strict] → GraphKind.
+ * Per parser/builder.ts:272-274 (the canonical mapping in this codebase).
+ * @see lib/cgraph/graph.c:Agdirected / Agstrictdirected / Agundirected / Agstrictundirected
+ */
+const KIND_TABLE: Record<string, GraphKind> = {
+  'true:true': 'strict-directed',
+  'true:false': 'directed',
+  'false:true': 'strict-undirected',
+  'false:false': 'undirected',
+};
+
+/** Derive GraphKind from CreateGraphOptions. */
+function resolveKind(opts: CreateGraphOptions | undefined): GraphKind {
+  const d = String(opts?.directed ?? true);
+  const s = String(opts?.strict ?? false);
+  return KIND_TABLE[`${d}:${s}`] ?? 'directed';
+}
+
+// ── Factory ────────────────────────────────────────────────────────────────────
+
+/**
+ * Create a new programmatic graph builder.
+ *
+ * The builder's `.graph` is a fresh Graph ready for handoff to layout/render.
+ * Defaults: directed=true, strict=false, name=''.
+ *
+ * @see lib/cgraph/graph.c:agopen
+ */
+export function createGraph(opts?: CreateGraphOptions): GvGraphBuilder {
+  const g = new Graph(opts?.name ?? '', resolveKind(opts));
+  return new GraphBuilder(g, g);
+}

package/src/api/edge-ops.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Safe edge-creation helper — the `agedge` equivalent for programmatic graph
+ * construction. Mirrors the parser's dual-list insertion and adds the
+ * strict-graph deduplication mandated by cgraph.
+ *
+ * @see lib/cgraph/edge.c:agedge
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import { Edge } from '../model/edge.js';
+
+/** @see lib/cgraph/cgraph.h:agisundirected */
+function isUndirected(g: Graph): boolean {
+  const k = g.root.kind;
+  return k === 'undirected' || k === 'strict-undirected';
+}
+
+/** @see lib/cgraph/cgraph.h:agisstrict */
+function isStrict(g: Graph): boolean {
+  const k = g.root.kind;
+  return k === 'strict-directed' || k === 'strict-undirected';
+}
+
+/**
+ * Probe root.edges for an existing (tail,head) pair.
+ * For undirected graphs, (h,t) matches (t,h) — mirrors the C wildcard
+ * key probe in ok_to_make_edge / agedge pre-creation check.
+ * @see lib/cgraph/edge.c:ok_to_make_edge
+ */
+function findExistingEdge(
+  root: Graph,
+  tail: Node,
+  head: Node,
+  undirected: boolean,
+): Edge | null {
+  for (const e of root.edges) {
+    if (e.tail === tail && e.head === head) return e;
+    if (undirected && e.tail === head && e.head === tail) return e;
+  }
+  return null;
+}
+
+/**
+ * Insert edge into root.edges and walk the subgraph chain toward root,
+ * adding the edge (and its endpoint nodes) to every enclosing graph.
+ * Mirrors processEdgePair's enclosing-graph loop and installedge.
+ * @see lib/cgraph/edge.c:installedge
+ * @see src/parser/builder.ts:238-246
+ */
+function insertEdge(g: Graph, root: Graph, edge: Edge): void {
+  root.edges.push(edge);
+  edge.graphSeq = root.edges.length;
+  for (let cur: Graph | null = g; cur !== null && cur !== root; cur = cur.parent) {
+    cur.nodes.set(edge.tail.name, edge.tail);
+    cur.nodes.set(edge.head.name, edge.head);
+    cur.edges.push(edge);
+  }
+}
+
+/**
+ * Create and insert an edge from `tail` to `head` in graph `g`.
+ *
+ * In a strict graph, at most one edge between any (tail, head) pair exists
+ * (symmetric for undirected). When a match is found the existing edge is
+ * returned without modification. This matches C `agedge` with `cflag=1`.
+ *
+ * Most callers building a graph programmatically should prefer
+ * `createGraph().addEdge(...)` (the `GvGraphBuilder` method), which accepts
+ * node names or handles. Use this lower-level `addEdge` when you already
+ * hold `Graph`/`Node` references — e.g. edges added onto a graph returned by
+ * `parse()`.
+ *
+ * @param g    - Owning graph or subgraph; root derived via `g.root`.
+ * @param tail - Source node (AGTAIL). @see lib/cgraph/cgraph.h:AGTAIL
+ * @param head - Destination node (AGHEAD). @see lib/cgraph/cgraph.h:AGHEAD
+ * @param name - Edge key; defaults to empty string for anonymous edges.
+ *               Ignored for strict-graph dedup (wildcard match).
+ * @returns The new (or existing, for strict graphs) edge.
+ *
+ * @example
+ * ```ts
+ * import { parse, addEdge } from '@knowvah/dot-engine';
+ *
+ * const g = parse('digraph { a; b; }');
+ * const a = g.nodes.get('a')!;
+ * const b = g.nodes.get('b')!;
+ * const edge = addEdge(g, a, b, 'ab1');
+ * // edge.tail === a, edge.head === b
+ * ```
+ *
+ * @see lib/cgraph/edge.c:agedge
+ */
+export function addEdge(
+  g: Graph,
+  tail: Node,
+  head: Node,
+  name?: string,
+): Edge {
+  const root = g.root;
+  const undirected = isUndirected(g);
+
+  if (isStrict(g)) {
+    const existing = findExistingEdge(root, tail, head, undirected);
+    if (existing !== null) return existing;
+  }
+
+  const edge = new Edge(tail, head, name ?? '');
+  insertEdge(g, root, edge);
+  return edge;
+}

package/src/api/geometry.ts

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Geometry snapshot API — reads computed layout geometry from an
+ * internal Graph after ctx.layout() has run, and returns a plain,
+ * JSON-serializable snapshot.
+ *
+ * Coordinate systems
+ * ------------------
+ * Native graphviz coordinates are y-up (origin at lower-left).
+ * Most screen consumers want y-down (origin at upper-left).
+ *
+ * With the default `yAxis: 'down'`, every y coordinate is flipped:
+ *   y' = bbHeight - y
+ * where bbHeight = graph bb.ur.y - graph bb.ll.y.
+ * The `bounds` origin is normalised to (0, 0) at the top-left corner.
+ *
+ * With `yAxis: 'up'`, values are returned unchanged (native y-up frame).
+ *
+ * Units
+ * -----
+ * The internal model stores node `width` and `height` in inches
+ * (matching C ND_width / ND_height in lib/common/types.h).
+ * `NodeGeometry.width` and `NodeGeometry.height` are converted to
+ * **points** (1 inch = 72 points) before being returned.
+ *
+ * All other coordinates (x, y, bbox dimensions, spline points,
+ * label positions) are in the native graphviz point unit.
+ *
+ * @see lib/common/types.h
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import type { Edge } from '../model/edge.js';
+import { RenderError } from '../errors.js';
+
+// ---------------------------------------------------------------------------
+// Public coordinate types (canonical home — T5 imports GeometryOptions here)
+// ---------------------------------------------------------------------------
+
+/** Coordinate system for returned geometry. */
+export type YAxis = 'up' | 'down';
+
+/**
+ * Options for {@link getLayout}.
+ *
+ * @property yAxis - Coordinate direction. Default `'down'` (origin top-left,
+ *   y increases downward — screen convention). Use `'up'` to get native
+ *   graphviz coordinates (origin bottom-left, y increases upward).
+ */
+export type GeometryOptions = { yAxis?: YAxis };
+
+/**
+ * Overall bounding box of the graph, in points.
+ *
+ * With `yAxis:'down'`, x and y are 0 (normalised to top-left origin)
+ * and width/height are the natural dimensions.
+ * With `yAxis:'up'`, x and y match the raw lower-left corner of the
+ * graph bounding box.
+ */
+export interface BoundsGeometry {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Per-node geometry extracted after layout, in points.
+ *
+ * `x` and `y` are the node centre coordinates.
+ * `width` and `height` are in **points** (converted from the inches
+ * stored on the model: `NodeInfo.width * 72`, `NodeInfo.height * 72`).
+ *
+ * @see lib/common/types.h:ND_coord, ND_width, ND_height
+ */
+export interface NodeGeometry {
+  name: string;
+  x: number;
+  y: number;
+  /**
+   * Node width in **points** (model stores inches; multiplied by 72 here).
+   * @see lib/common/types.h:ND_width
+   */
+  width: number;
+  /**
+   * Node height in **points** (model stores inches; multiplied by 72 here).
+   * @see lib/common/types.h:ND_height
+   */
+  height: number;
+}
+
+/**
+ * Per-edge geometry extracted after spline routing, in points.
+ *
+ * `points` concatenates all bezier control points from the edge spline,
+ * in order. An edge with no routed spline produces an empty `points` array.
+ * `label` is present only when the edge carries a centre label.
+ *
+ * @see lib/common/types.h:ED_spl, ED_label
+ */
+export interface EdgeGeometry {
+  tail: string;
+  head: string;
+  /** Bezier control points for the edge spline, in points. */
+  points: { x: number; y: number }[];
+  /** Centre edge label position, if present. @see lib/common/types.h:ED_label */
+  label?: { x: number; y: number };
+}
+
+/**
+ * Per-cluster geometry extracted after layout, in points.
+ *
+ * `name` is the cluster subgraph's name (e.g. `cluster6`); for nested
+ * clusters the name encodes the hierarchy, so no explicit parent link is
+ * exposed. `x`/`y`/`width`/`height` describe the cluster's bounding box,
+ * following the same frame convention as {@link BoundsGeometry}: with
+ * `yAxis:'down'` (x, y) is the top-left corner; with `yAxis:'up'` (x, y) is
+ * the lower-left corner (native graphviz frame). These are the raw box
+ * corners graphviz computed — the same values `render()` rounds to emit the
+ * `class="cluster"` polygon, so a consumer quantizing to SVG precision gets
+ * byte-conformant geometry.
+ *
+ * @see lib/common/types.h:GD_bb (of a cluster subgraph)
+ */
+export interface ClusterGeometry {
+  /** Cluster subgraph name (e.g. `cluster6`); encodes nesting. */
+  name: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Plain, JSON-serializable snapshot of the graph's computed geometry.
+ *
+ * `clusters` lists every cluster subgraph (recursively, nested clusters each
+ * get their own entry) with a computed bounding box; it is empty for graphs
+ * without clusters.
+ *
+ * @see lib/common/types.h:GD_bb, ND_coord, ED_spl, GD_clust
+ */
+export interface LayoutSnapshot {
+  bounds: BoundsGeometry;
+  nodes: NodeGeometry[];
+  edges: EdgeGeometry[];
+  clusters: ClusterGeometry[];
+}
+
+// ---------------------------------------------------------------------------
+// Internal constants
+// ---------------------------------------------------------------------------
+
+/** Points per inch — matches graphviz's DPI constant. @see lib/common/geom.h */
+const INCHES_TO_POINTS = 72;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Build a y-flip function bound to a specific graph bounding-box height. */
+function makeFlipY(bbHeight: number, yAxis: YAxis): (y: number) => number {
+  if (yAxis === 'up') return (y) => y;
+  return (y) => bbHeight - y;
+}
+
+/**
+ * Snapshot one node's geometry.
+ * @see lib/common/types.h:ND_coord, ND_width, ND_height
+ */
+function snapshotNode(node: Node, flipY: (y: number) => number): NodeGeometry {
+  const coord = node.info.coord;
+  return {
+    name: node.name,
+    x: coord.x,
+    y: flipY(coord.y),
+    width: node.info.width * INCHES_TO_POINTS,
+    height: node.info.height * INCHES_TO_POINTS,
+  };
+}
+
+/**
+ * Collect bezier control points from an edge's spline.
+ * Uses `.size` (not `.list.length`) because C over-allocates `list`
+ * and `size` holds the actual count after clip_and_install.
+ * @see lib/common/splines.c:clip_and_install
+ */
+function collectEdgePoints(
+  edge: Edge,
+  flipY: (y: number) => number,
+): { x: number; y: number }[] {
+  const spl = edge.info.spl;
+  if (spl === undefined) return [];
+  const pts: { x: number; y: number }[] = [];
+  for (const bz of spl.list) {
+    for (let k = 0; k < bz.size; k++) {
+      const pt = bz.list[k];
+      pts.push({ x: pt.x, y: flipY(pt.y) });
+    }
+  }
+  return pts;
+}
+
+/**
+ * Snapshot one edge's geometry.
+ * @see lib/common/types.h:ED_spl, ED_label (textlabel_t.pos)
+ */
+function snapshotEdge(edge: Edge, flipY: (y: number) => number): EdgeGeometry {
+  const geom: EdgeGeometry = {
+    tail: edge.tail.name,
+    head: edge.head.name,
+    points: collectEdgePoints(edge, flipY),
+  };
+  const lbl = edge.info.label;
+  if (lbl !== undefined) {
+    geom.label = { x: lbl.pos.x, y: flipY(lbl.pos.y) };
+  }
+  return geom;
+}
+
+/**
+ * Snapshot one cluster's bounding box, in the requested frame.
+ *
+ * Mirrors the {@link BoundsGeometry} convention: `yAxis:'up'` returns the
+ * native lower-left corner (ll); `yAxis:'down'` returns the top-left corner
+ * (ll.x, flipped ur.y). `width`/`height` are frame-independent (ur - ll).
+ *
+ * @see lib/common/types.h:GD_bb (cluster subgraph)
+ */
+function snapshotCluster(
+  sg: Graph, yAxis: YAxis, flipY: (y: number) => number,
+): ClusterGeometry {
+  const bb = sg.info.bb;
+  return {
+    name: sg.name,
+    x: bb.ll.x,
+    // 'up' keeps the lower-left y; 'down' flips the upper-right y to the
+    // top-left of the box (flipY is monotonic-decreasing there).
+    y: yAxis === 'up' ? bb.ll.y : flipY(bb.ur.y),
+    width: bb.ur.x - bb.ll.x,
+    height: bb.ur.y - bb.ll.y,
+  };
+}
+
+/**
+ * Collect every cluster subgraph (depth-first, nested clusters included).
+ * C stores clusters 1-indexed in GD_clust; the TS model exposes a 0-indexed
+ * `info.clust` array on each (sub)graph. A cluster without a computed bb
+ * (never laid out) is skipped.
+ * @see lib/common/types.h:GD_clust, GD_n_cluster
+ */
+function collectClusters(
+  sg: Graph, yAxis: YAxis, flipY: (y: number) => number,
+  out: ClusterGeometry[],
+): void {
+  for (const c of sg.info.clust ?? []) {
+    if (c.info.bb !== undefined) out.push(snapshotCluster(c, yAxis, flipY));
+    collectClusters(c, yAxis, flipY, out);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns a plain, JSON-serializable snapshot of the computed geometry for
+ * all nodes and edges in graph `g`.
+ *
+ * Must be called **after** `ctx.layout(g, engine)` (or `render`) has run.
+ * Before layout the geometry fields hold calloc-zero defaults (every node at
+ * the origin, an empty bounding box), so a not-yet-laid-out graph is rejected
+ * with a `RenderError` rather than returning that all-zero snapshot as if it
+ * were real geometry.
+ *
+ * @param g    - Laid-out graph (internal model; not mutated by this function).
+ * @param opts - Coordinate options; defaults to `{ yAxis: 'down' }`.
+ * @throws RenderError if `g` has not been laid out.
+ *
+ * @see lib/common/types.h:GD_bb, ND_coord, ED_spl
+ */
+export function getLayout(g: Graph, opts?: GeometryOptions): LayoutSnapshot {
+  if (g.info?.laidOut !== true) {
+    throw new RenderError(
+      'getLayout requires a laid-out graph; run ctx.layout(g, engine) or render() first',
+      'GENERIC_ERROR',
+    );
+  }
+  const yAxis: YAxis = opts?.yAxis ?? 'down';
+  const bb = g.info.bb;
+  const bbWidth = bb.ur.x - bb.ll.x;
+  const bbHeight = bb.ur.y - bb.ll.y;
+  const flipY = makeFlipY(bbHeight, yAxis);
+
+  const bounds: BoundsGeometry = yAxis === 'down'
+    ? { x: 0, y: 0, width: bbWidth, height: bbHeight }
+    : { x: bb.ll.x, y: bb.ll.y, width: bbWidth, height: bbHeight };
+
+  const nodes = Array.from(g.nodes.values()).map((n) => snapshotNode(n, flipY));
+  const edges = g.edges.map((e) => snapshotEdge(e, flipY));
+  const clusters: ClusterGeometry[] = [];
+  collectClusters(g, yAxis, flipY, clusters);
+
+  return { bounds, nodes, edges, clusters };
+}