@knowvah/dot-engine 0.1.0

package/dist/api/edge-ops.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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';
+/**
+ * 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 declare function addEdge(g: Graph, tail: Node, head: Node, name?: string): Edge;
+//# sourceMappingURL=edge-ops.d.ts.map

package/dist/api/edge-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-ops.d.ts","sourceRoot":"","sources":["../../src/api/edge-ops.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAkDxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,KAAK,EACR,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAYN"}

package/dist/api/geometry.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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';
+/** 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[];
+}
+/**
+ * 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 declare function getLayout(g: Graph, opts?: GeometryOptions): LayoutSnapshot;
+//# sourceMappingURL=geometry.d.ts.map

package/dist/api/geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/api/geometry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAS/C,+CAA+C;AAC/C,MAAM,MAAM,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;AAElC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnC,+EAA+E;IAC/E,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAsHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,cAAc,CAuB1E"}

package/dist/api/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `graphviz-ts/api` — the build + inspect + geometry entry point (ADR-2).
+ *
+ * Pure re-export barrel for the api layer: programmatic graph construction
+ * (the builder), the safe edge helper, and the computed-geometry snapshot.
+ *
+ * Typical flow: call {@link createGraph} to build nodes/edges/subgraphs
+ * without hand-writing DOT text, hand the builder's `.graph` (or a
+ * `parse()` result) to `render()` from `graphviz-ts/render` (or the root
+ * package) to lay out and emit an output format, then optionally call
+ * {@link getLayout} here to read back computed node/edge/cluster geometry
+ * from the laid-out graph.
+ *
+ * The internal mutable `Graph`/`Node`/`Edge` classes are NOT re-exported as
+ * values (ADR-1); only the opaque `Graph` *type* is surfaced so consumers can
+ * annotate variables holding a builder's `.graph` or a `parse()` result.
+ */
+export { createGraph } from './builder.js';
+export type { GvGraphBuilder, GvNode, GvEdge, CreateGraphOptions, } from './builder.js';
+export { getLayout } from './geometry.js';
+export type { LayoutSnapshot, NodeGeometry, EdgeGeometry, BoundsGeometry, ClusterGeometry, YAxis, GeometryOptions, } from './geometry.js';
+export { addEdge } from './edge-ops.js';
+export type { Graph } from '../model/graph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EACV,cAAc,EACd,MAAM,EACN,MAAM,EACN,kBAAkB,GACnB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC1C,YAAY,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,eAAe,EACf,KAAK,EACL,eAAe,GAChB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAGxC,YAAY,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC"}