@knowvah/dot-engine 0.1.0

package/LICENSE

@@ -0,0 +1,277 @@
+Eclipse Public License - v 2.0
+
+    THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE
+    PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION
+    OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT.
+
+1. DEFINITIONS
+
+"Contribution" means:
+
+  a) in the case of the initial Contributor, the initial content
+     Distributed under this Agreement, and
+
+  b) in the case of each subsequent Contributor:
+     i) changes to the Program, and
+     ii) additions to the Program;
+  where such changes and/or additions to the Program originate from
+  and are Distributed by that particular Contributor. A Contribution
+  "originates" from a Contributor if it was added to the Program by
+  such Contributor itself or anyone acting on such Contributor's behalf.
+  Contributions do not include changes or additions to the Program that
+  are not Modified Works.
+
+"Contributor" means any person or entity that Distributes the Program.
+
+"Licensed Patents" mean patent claims licensable by a Contributor which
+are necessarily infringed by the use or sale of its Contribution alone
+or when combined with the Program.
+
+"Program" means the Contributions Distributed in accordance with this
+Agreement.
+
+"Recipient" means anyone who receives the Program under this Agreement
+or any Secondary License (as applicable), including Contributors.
+
+"Derivative Works" shall mean any work, whether in Source Code or other
+form, that is based on (or derived from) the Program and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship.
+
+"Modified Works" shall mean any work in Source Code or other form that
+results from an addition to, deletion from, or modification of the
+contents of the Program, including, for purposes of clarity any new file
+in Source Code form that contains any contents of the Program. Modified
+Works shall not include works that contain only declarations,
+interfaces, types, classes, structures, or files of the Program solely
+in each case in order to link to, bind by name, or subclass the Program
+or Modified Works thereof.
+
+"Distribute" means the acts of a) distributing or b) making available
+in any manner that enables the transfer of a copy.
+
+"Source Code" means the form of a Program preferred for making
+modifications, including but not limited to software source code,
+documentation source, and configuration files.
+
+"Secondary License" means either the GNU General Public License,
+Version 2.0, or any later versions of that license, including any
+exceptions or additional permissions as identified by the initial
+Contributor.
+
+2. GRANT OF RIGHTS
+
+  a) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free copyright
+  license to reproduce, prepare Derivative Works of, publicly display,
+  publicly perform, Distribute and sublicense the Contribution of such
+  Contributor, if any, and such Derivative Works.
+
+  b) Subject to the terms of this Agreement, each Contributor hereby
+  grants Recipient a non-exclusive, worldwide, royalty-free patent
+  license under Licensed Patents to make, use, sell, offer to sell,
+  import and otherwise transfer the Contribution of such Contributor,
+  if any, in Source Code or other form. This patent license shall
+  apply to the combination of the Contribution and the Program if, at
+  the time the Contribution is added by the Contributor, such addition
+  of the Contribution causes such combination to be covered by the
+  Licensed Patents. The patent license shall not apply to any other
+  combinations which include the Contribution. No hardware per se is
+  licensed hereunder.
+
+  c) Recipient understands that although each Contributor grants the
+  licenses to its Contributions set forth herein, no assurances are
+  provided by any Contributor that the Program does not infringe the
+  patent or other intellectual property rights of any other entity.
+  Each Contributor disclaims any liability to Recipient for claims
+  brought by any other entity based on infringement of intellectual
+  property rights or otherwise. As a condition to exercising the
+  rights and licenses granted hereunder, each Recipient hereby
+  assumes sole responsibility to secure any other intellectual
+  property rights needed, if any. For example, if a third party
+  patent license is required to allow Recipient to Distribute the
+  Program, it is Recipient's responsibility to acquire that license
+  before distributing the Program.
+
+  d) Each Contributor represents that to its knowledge it has
+  sufficient copyright rights in its Contribution, if any, to grant
+  the copyright license set forth in this Agreement.
+
+  e) Notwithstanding the terms of any Secondary License, no
+  Contributor makes additional grants to any Recipient (other than
+  those set forth in this Agreement) as a result of such Recipient's
+  receipt of the Program under the terms of a Secondary License
+  (if permitted under the terms of Section 3).
+
+3. REQUIREMENTS
+
+3.1 If a Contributor Distributes the Program in any form, then:
+
+  a) the Program must also be made available as Source Code, in
+  accordance with section 3.2, and the Contributor must accompany
+  the Program with a statement that the Source Code for the Program
+  is available under this Agreement, and informs Recipients how to
+  obtain it in a reasonable manner on or through a medium customarily
+  used for software exchange; and
+
+  b) the Contributor may Distribute the Program under a license
+  different than this Agreement, provided that such license:
+     i) effectively disclaims on behalf of all other Contributors all
+     warranties and conditions, express and implied, including
+     warranties or conditions of title and non-infringement, and
+     implied warranties or conditions of merchantability and fitness
+     for a particular purpose;
+
+     ii) effectively excludes on behalf of all other Contributors all
+     liability for damages, including direct, indirect, special,
+     incidental and consequential damages, such as lost profits;
+
+     iii) does not attempt to limit or alter the recipients' rights
+     in the Source Code under section 3.2; and
+
+     iv) requires any subsequent distribution of the Program by any
+     party to be under a license that satisfies the requirements
+     of this section 3.
+
+3.2 When the Program is Distributed as Source Code:
+
+  a) it must be made available under this Agreement, or if the
+  Program (i) is combined with other material in a separate file or
+  files made available under a Secondary License, and (ii) the initial
+  Contributor attached to the Source Code the notice described in
+  Exhibit A of this Agreement, then the Program may be made available
+  under the terms of such Secondary Licenses, and
+
+  b) a copy of this Agreement must be included with each copy of
+  the Program.
+
+3.3 Contributors may not remove or alter any copyright, patent,
+trademark, attribution notices, disclaimers of warranty, or limitations
+of liability ("notices") contained within the Program from any copy of
+the Program which they Distribute, provided that Contributors may add
+their own appropriate notices.
+
+4. COMMERCIAL DISTRIBUTION
+
+Commercial distributors of software may accept certain responsibilities
+with respect to end users, business partners and the like. While this
+license is intended to facilitate the commercial use of the Program,
+the Contributor who includes the Program in a commercial product
+offering should do so in a manner which does not create potential
+liability for other Contributors. Therefore, if a Contributor includes
+the Program in a commercial product offering, such Contributor
+("Commercial Contributor") hereby agrees to defend and indemnify every
+other Contributor ("Indemnified Contributor") against any losses,
+damages and costs (collectively "Losses") arising from claims, lawsuits
+and other legal actions brought by a third party against the Indemnified
+Contributor to the extent caused by the acts or omissions of such
+Commercial Contributor in connection with its distribution of the Program
+in a commercial product offering. The obligations in this section do not
+apply to any claims or Losses relating to any actual or alleged
+intellectual property infringement. In order to qualify, an Indemnified
+Contributor must: a) promptly notify the Commercial Contributor in
+writing of such claim, and b) allow the Commercial Contributor to control,
+and cooperate with the Commercial Contributor in, the defense and any
+related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial
+product offering, Product X. That Contributor is then a Commercial
+Contributor. If that Commercial Contributor then makes performance
+claims, or offers warranties related to Product X, those performance
+claims and warranties are such Commercial Contributor's responsibility
+alone. Under this section, the Commercial Contributor would have to
+defend claims against the other Contributors related to those performance
+claims and warranties, and if a court requires any other Contributor to
+pay any damages as a result, the Commercial Contributor must pay
+those damages.
+
+5. NO WARRANTY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS"
+BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF
+TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
+PURPOSE. Each Recipient is solely responsible for determining the
+appropriateness of using and distributing the Program and assumes all
+risks associated with its exercise of rights under this Agreement,
+including but not limited to the risks and costs of program errors,
+compliance with applicable laws, damage to or loss of data, programs
+or equipment, and unavailability or interruption of operations.
+
+6. DISCLAIMER OF LIABILITY
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT
+PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS
+SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE
+EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+7. GENERAL
+
+If any provision of this Agreement is invalid or unenforceable under
+applicable law, it shall not affect the validity or enforceability of
+the remainder of the terms of this Agreement, and without further
+action by the parties hereto, such provision shall be reformed to the
+minimum extent necessary to make such provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity
+(including a cross-claim or counterclaim in a lawsuit) alleging that the
+Program itself (excluding combinations of the Program with other software
+or hardware) infringes such Recipient's patent(s), then such Recipient's
+rights granted under Section 2(b) shall terminate as of the date such
+litigation is filed.
+
+All Recipient's rights under this Agreement shall terminate if it
+fails to comply with any of the material terms or conditions of this
+Agreement and does not cure such failure in a reasonable period of
+time after becoming aware of such noncompliance. If all Recipient's
+rights under this Agreement terminate, Recipient agrees to cease use
+and distribution of the Program as soon as reasonably practicable.
+However, Recipient's obligations under this Agreement and any licenses
+granted by Recipient relating to the Program shall continue and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement,
+but in order to avoid inconsistency the Agreement is copyrighted and
+may only be modified in the following manner. The Agreement Steward
+reserves the right to publish new versions (including revisions) of
+this Agreement from time to time. No one other than the Agreement
+Steward has the right to modify this Agreement. The Eclipse Foundation
+is the initial Agreement Steward. The Eclipse Foundation may assign the
+responsibility to serve as the Agreement Steward to a suitable separate
+entity. Each new version of the Agreement will be given a distinguishing
+version number. The Program (including Contributions) may always be
+Distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to Distribute the Program (including its
+Contributions) under the new version.
+
+Except as expressly stated in Sections 2(a) and 2(b) above, Recipient
+receives no rights or licenses to the intellectual property of any
+Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted
+under this Agreement are reserved. Nothing in this Agreement is intended
+to be enforceable by any entity that is not a Contributor or Recipient.
+No third-party beneficiary rights are created under this Agreement.
+
+Exhibit A - Form of Secondary Licenses Notice
+
+"This Source Code may also be made available under the following 
+Secondary Licenses when the conditions for such availability set forth 
+in the Eclipse Public License, v. 2.0 are satisfied: {name license(s),
+version(s), and exceptions or additional permissions here}."
+
+  Simply including a copy of this Agreement, including this Exhibit A
+  is not sufficient to license the Source Code under Secondary Licenses.
+
+  If it is not possible or desirable to put the notice in a particular
+  file, then You may include the notice in a location (such as a LICENSE
+  file in a relevant directory) where a recipient would be likely to
+  look for such a notice.
+
+  You may add additional accurate notices of copyright ownership.

package/README.md

@@ -0,0 +1,292 @@
+<!-- SPDX-License-Identifier: EPL-2.0 -->
+
+# @knowvah/dot-engine
+
+A faithful TypeScript port of [Graphviz](https://gitlab.com/graphviz/graphviz) — the
+graph-visualization toolkit originally written in C at AT&T Research and Lucent
+Bell Labs. It parses the DOT language, runs Graphviz's layout engines, and emits
+SVG.
+
+The defining property: **pure TypeScript — no C.** No compiled Graphviz binary, no WASM build of it, no native dependencies.
+It runs in a browser or in Node with zero external dependencies at runtime. The
+goal is the closest achievable fidelity to the C implementation, which is treated
+as the canonical specification (see [`CLAUDE.md`](./CLAUDE.md)). In practice the
+`dot` engine is **conformant** with the C binary on the golden corpus: numeric
+coordinates agree to a tight deterministic tolerance (±0.01) and non-numeric
+content is exactly equal. This is the measured "match" bar, not a claim of
+literal byte-for-byte SVG output — see [Conformance](./docs/conformance.md) for
+the exact definition and the comparison code, and
+[known divergences](./docs/known-divergences.md) for the documented exceptions.
+
+> **Status: `0.1.x` — in active development, published to npm.** The port is
+> mature enough to lay out and render real graphs across all engines; the C
+> feature surface is not 100% covered. The `dot` engine is the primary
+> fidelity target. See [Status & coverage](#status--coverage) below.
+
+## Why this exists
+
+Existing ways to render DOT in a JS environment shell out to a Graphviz
+binary, a rendering server, or a WASM build — none of which run everywhere a
+browser does, and all of which add deployment friction. @knowvah/dot-engine removes
+that dependency entirely: the layout engine *is* TypeScript.
+
+## Install
+
+```bash
+npm i @knowvah/dot-engine
+```
+
+Ships as ESM bundles with TypeScript declarations, zero runtime dependencies.
+Entry points: `@knowvah/dot-engine` (core), `@knowvah/dot-engine/api` (graph-building API),
+`@knowvah/dot-engine/render` (renderers).
+
+To build from source instead: clone, `npm install`, `npm run build`
+(esbuild bundles + `.d.ts` declarations into `dist/`).
+
+## Quick start
+
+```ts
+import { renderSvg } from '@knowvah/dot-engine';
+
+const dot = `
+  digraph {
+    a -> b;
+    b -> c;
+    a -> c;
+  }
+`;
+
+const svg = renderSvg(dot, 'dot');
+console.log(svg); // <svg ...>...</svg>
+```
+
+`renderSvg(dotSource, engine)` parses the DOT source, runs the named layout
+engine, renders to SVG, and returns the SVG string. On failure it throws a
+structured error — see [Error handling](#error-handling).
+
+## Error handling
+
+`renderSvg` throws on any failure; for a result-style alternative that never
+throws, use `tryRenderSvg`:
+
+```ts
+import { tryRenderSvg } from '@knowvah/dot-engine';
+
+const result = tryRenderSvg('digraph { a ->', 'dot');
+if (result.svg) {
+  // success
+} else {
+  const err = result.errors[0];
+  console.error(err.code, err.friendlyMessage, err.location);
+  // 'SYNTAX_UNEXPECTED_EOF' · 'The DOT source ended unexpectedly …' · { line, column, offset }
+}
+```
+
+A `RenderResult` is `{ svg }` **or** `{ errors }` (never both); `errors` holds at
+most the first failure. Each entry is a plain, JSON-serializable `GvError`:
+
+| Field | Meaning |
+|-------|---------|
+| `type` | `'syntax'` · `'semantic'` · `'render'` |
+| `code` | Stable machine key (an i18n key) — branch on this |
+| `message` | Concise technical text |
+| `friendlyMessage` | Approachable, non-localized English for end users |
+| `location?` | `{ line, column, offset? }` — the real error position |
+| `expected?` | Parser expectation list, for syntax errors only |
+
+The `code` values are a closed union: `SYNTAX_ERROR`, `SYNTAX_UNEXPECTED_EOF`,
+`EDGE_OP_DIRECTED_IN_UNDIRECTED`, `EDGE_OP_UNDIRECTED_IN_DIRECTED`,
+`HTML_PARSE_ERROR`, `RENDER_ERROR`, `GENERIC_ERROR`.
+
+The throwing `renderSvg` raises the same structured values as real `Error`
+subclasses — `ParseError` (syntax) and `RenderError` (render) — each carrying
+`code`, `type`, `friendlyMessage`, and (for `ParseError`) `location`/`expected`.
+Branch on `.code`/`.type` rather than `instanceof` per subclass.
+
+## Layout engines
+
+All eight Graphviz layout engines are registered. Pass the name as the second
+argument to `renderSvg`:
+
+| Engine       | Layout style                                  |
+|--------------|-----------------------------------------------|
+| `dot`        | Hierarchical / layered directed graphs        |
+| `neato`      | Spring-model (Kamada–Kawai)                   |
+| `fdp`        | Force-directed                                |
+| `sfdp`       | Multiscale force-directed (large graphs)      |
+| `circo`      | Circular                                      |
+| `twopi`      | Radial                                        |
+| `osage`      | Clustered                                     |
+| `patchwork`  | Squarified treemap                            |
+
+`dot` receives the most fidelity attention because the primary consumer is
+DOT-centric. Per-engine coverage against the C source is tracked in the
+[port catalog](./plans/port-catalog/README.md).
+
+## Browser usage
+
+The library uses no Node-only APIs and is safe to bundle for the browser. One
+caller-supplied hook may be required:
+
+- **Image sizing.** When a graph references external images (e.g.
+  `node [image="foo.png"]`), Graphviz needs each image's intrinsic dimensions.
+  Because the library cannot read the filesystem, provide a sizer via
+  `setImageSizer`:
+
+  ```ts
+  import { setImageSizer } from '@knowvah/dot-engine';
+
+  setImageSizer((src) => ({ w: 64, h: 64 })); // return null if unknown
+  ```
+
+### Text measurement
+
+Layout needs to know how wide each label is. By default this uses a **built-in,
+deterministic metric model** — no font files, identical output on every platform.
+In the **browser** the library automatically measures with the page's own canvas
+(the same font the browser renders the SVG with).
+
+For **host-faithful** Node measurement (real kerning/shaping, matching the local
+fonts the SVG will be rendered with), install the optional `canvas` peer and wire
+it once via `setTextMeasurer`:
+
+```ts
+import { setTextMeasurer, CanvasTextMeasurer } from '@knowvah/dot-engine';
+import { createCanvas } from 'canvas'; // optional peer: `npm i canvas`
+
+setTextMeasurer(new CanvasTextMeasurer(createCanvas(0, 0).getContext('2d')));
+```
+
+Trade-off: the built-in model is reproducible across machines; the host-faithful
+path matches the rendering font but is platform-dependent (as native graphviz is).
+See the Text measurement guide for the full contract.
+
+## Security
+
+**Treat rendered output as attacker-controlled markup whenever the DOT source is
+untrusted.** The SVG and image-map strings this library produces embed graph
+attribute values (labels, `id`, `class`, `href`/`URL`, `image`, `stylesheet`,
+tooltips) directly. All such values are XML-escaped exactly as native Graphviz
+does, so they cannot break out of an element or attribute — but, **matching
+upstream Graphviz, the library does not filter URL schemes or validate resource
+origins.** A DOT source you did not author can therefore contain:
+
+- `href="javascript:…"` / `URL="javascript:…"` on a node or edge (executes on
+  click),
+- `image="…"` (usershape) or an image-map `href` pointing at an arbitrary
+  external origin,
+- a `stylesheet="…"` referencing an external CSS origin.
+
+This is deliberate — scheme/origin policy belongs to the page embedding the
+output, not to the layout library. If you render untrusted DOT and embed the
+result inline (`innerHTML`, `dangerouslySetInnerHTML`, an inline `<svg>`), apply
+a **Content-Security-Policy** on the host page as the control point:
+
+- `script-src` (without `'unsafe-inline'`) — neutralizes `javascript:` hrefs and
+  any inline event handlers,
+- `img-src` — constrains `<image>` / usershape origins,
+- `style-src` — constrains the `stylesheet` processing instruction.
+
+If you cannot set a CSP, sanitize the returned markup (e.g. DOMPurify with an
+SVG profile) before inserting it, or render from trusted DOT only.
+
+## Public API
+
+```ts
+// Primary entry point. Throws a structured GvError (ParseError / RenderError).
+function renderSvg(dotSource: string, engine: string): string;
+
+// Result-style entry point: returns { svg } or { errors: [GvError] }, never throws.
+function tryRenderSvg(dotSource: string, engine: string): RenderResult;
+
+// Structured error contract (see "Error handling").
+interface GvError { type; code; message; friendlyMessage; location?; expected?; }
+interface RenderResult { svg?: string; errors?: GvError[]; }
+type GvErrorType = 'syntax' | 'semantic' | 'render';
+type GvErrorCode = 'SYNTAX_ERROR' | 'SYNTAX_UNEXPECTED_EOF' | /* …7 total */ 'GENERIC_ERROR';
+class ParseError extends Error implements GvError { /* type:'syntax' */ }
+class RenderError extends Error implements GvError { /* type:'render' */ }
+
+// Parse DOT into the in-memory graph model (without laying it out).
+function parse(dotSource: string): Graph;
+
+// Supply intrinsic dimensions for external image references (browser/Node).
+function setImageSizer(sizer: ImageSizer | null): void;
+type ImageSizer = (src: string) => { w: number; h: number } | null;
+
+// Multi-format render + structured xdot draw-ops (from `@knowvah/dot-engine/render`,
+// also re-exported from the root package).
+function render(g: Graph, format: OutputFormat, opts?: { engine?: string }): string;
+function getDrawOps(g: Graph, opts?: { engine?: string }): XdotOp[];
+
+// Programmatic graph construction and computed-geometry readback (from
+// `@knowvah/dot-engine/api`, also re-exported from the root package) — build a graph
+// without writing DOT source, or read back node/edge/bbox coordinates after
+// layout.
+function createGraph(opts?: CreateGraphOptions): GvGraphBuilder;
+function addEdge(g: Graph, tail: Node, head: Node, name?: string): Edge;
+function getLayout(g: Graph, opts?: { yAxis?: 'up' | 'down' }): LayoutSnapshot;
+
+// Lower-level orchestration, for callers that need engine/render control.
+class GvcContext { /* register engines/renderers, layout, render */ }
+function renderWithContext(ctx: GvcContext, graph: Graph, format: string): string;
+```
+
+Most callers only need `renderSvg` (or `tryRenderSvg` for result-style error
+handling). `parse`, `GvcContext`, and `renderWithContext` are exposed for
+advanced use — e.g. inspecting the parsed model, or driving layout and
+rendering as separate steps. `createGraph`/`addEdge`, `getLayout`, `render`,
+and `getDrawOps` are the graph-building, geometry-readback, multi-format
+render, and structured-draw-op surfaces respectively — see the
+[API guide](https://knowvah.github.io/dot-engine/guide/api) for full
+walkthroughs of each.
+
+## Development
+
+```bash
+npm test            # run the test suite (vitest)
+npm run coverage    # run with coverage (v8)
+npm run typecheck   # tsc --noEmit, strict mode, zero errors required
+npm run build       # bundle to dist/index.js
+```
+
+The test suite verifies port fidelity by comparing generated SVG against output
+from the canonical C Graphviz. New behavior is pinned to the C source — see
+[`CLAUDE.md`](./CLAUDE.md) for the porting rules and the
+[port catalog](./plans/port-catalog/README.md) for status.
+
+## Status & coverage
+
+- **What works:** parsing, all eight layout engines, SVG output, and the
+  intermediate `json` / `xdot` / `dot` / imagemap text formats.
+- **Conformance bar:** a render is **conformant** when it matches the C oracle
+  within a ±0.01 deterministic tolerance (`dot`, `circo`, `twopi`, `osage`,
+  `patchwork`) or is characterized at a looser ±0.5 tolerance for the
+  iterative force-directed engines (`neato`, `fdp`, `sfdp`) — never literal
+  byte equality. Full definition: [Conformance](./docs/conformance.md).
+- **Current parity** (fresh corpus sweeps, dated 2026-07-11 — see
+  [`test/corpus/PARITY.md`](./test/corpus/PARITY.md) and the
+  [docs-site parity pages](https://knowvah.github.io/dot-engine/engines) for
+  live counts): `dot` SVG 762/788 conformant (+14 structural-match, 0
+  unaccepted tracked gaps — every remaining non-conformant graph is a
+  documented, accepted divergence); `dot` xdot 754/759; `circo` xdot 745/762;
+  `twopi` xdot 740/762; `osage` xdot 744/759; `patchwork` xdot 757/762
+  (all deterministic, ±0.01). `neato`/`fdp`/`sfdp` are characterized at ±0.5
+  rather than gated at the deterministic bar, per the tolerance split above.
+- **What's tracked:** every C algorithm and its port status is inventoried in
+  the [port catalog](./plans/port-catalog/README.md). Items marked `[ ]` there
+  are real gaps, not footnotes.
+- **Known behavioral divergences from C** (differences investigated,
+  root-caused, and deliberately not chased) are listed in
+  [`docs/known-divergences.md`](./docs/known-divergences.md).
+
+## Known limitations
+
+- **Feature coverage is incomplete.** The C source defines completeness; gaps
+  are tracked in the port catalog rather than hidden.
+
+## License
+
+[Eclipse Public License v2.0](https://www.eclipse.org/legal/epl-2.0/) (EPL-2.0),
+matching [upstream Graphviz](https://gitlab.com/graphviz/graphviz). Every source file carries an
+`SPDX-License-Identifier: EPL-2.0` header.

package/dist/api/builder.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 } from '../model/graph.js';
+/** 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;
+}
+/**
+ * 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 declare function createGraph(opts?: CreateGraphOptions): GvGraphBuilder;
+//# sourceMappingURL=builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/api/builder.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,EAAkB,MAAM,mBAAmB,CAAC;AAU1D,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;IAC9D,OAAO,CACL,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAAC;IACV,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC;IAC1E,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAmLD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAGrE"}