@knowvah/dot-engine 1.8.1 → 2.0.0

package/README.md

@@ -77,42 +77,114 @@ structured error — see [Error handling](#error-handling).
 
 ## Error handling
 
-`renderSvg` throws on any failure; for a result-style alternative that never
-throws, use `tryRenderSvg`:
+dot-engine raises two kinds of error:
+
+- `err instanceof DotEngineError` — dot-engine failed on this input: bad DOT
+  (`ParseError`), a layout/render failure (`RenderError`, including
+  `UNKNOWN_LAYOUT` and `UNSUPPORTED_FEATURE`), or a dot-engine bug
+  (`InternalError`).
+- A standard `TypeError` / `RangeError` / `Error` with `code: 'ERR_…'` — the call
+  was wrong (bad argument type, unregistered engine, wrong call order).
+
+Branch on `.code`, not on message text. For a result-style alternative that does
+not throw for bad DOT, use `tryRenderSvg`:
 
 ```ts
 import { tryRenderSvg } from '@knowvah/dot-engine';
 
 const result = tryRenderSvg('digraph { a ->', 'dot');
-if (result.svg) {
+if (result.svg !== undefined) {
   // success
 } else {
-  const err = result.errors[0];
-  console.error(err.code, err.friendlyMessage, err.location);
+  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.
+`tryRenderSvg` returns for any DOT input and throws only for invalid arguments.
+Each entry in `errors` is plain data (`type`, `code`, `message`,
+`friendlyMessage`, plus `location` / `expected` when present) with no `cause` and
+no stack.
+
+Every code, class, and the exceptions each public function can throw:
+[Errors and exceptions](https://dot-engine.knowvah.com/guide/errors).
+
+## Migrating to 2.0
+
+2.0 changes which errors are thrown. Code that branches on `.code` keeps working
+for DOT errors; the changes below are the ones that can affect callers.
+
+| Situation | Before | After |
+|-----------|--------|-------|
+| `parse(non-string)` / `renderSvg(non-string, …)` | `ParseError` `GENERIC_ERROR` | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| Engine argument not registered | `RenderError` `RENDER_ERROR` | `TypeError` `ERR_INVALID_ARG_VALUE` |
+| `tryRenderSvg` with invalid arguments (non-string source, unregistered engine) | Returned `{ errors: [...] }` (`GENERIC_ERROR` / `RENDER_ERROR`) | Throws `TypeError` (`ERR_INVALID_ARG_TYPE` / `ERR_INVALID_ARG_VALUE`) |
+| Engine argument not registered, but the DOT sets a valid `layout=` | Rendered with the attribute's engine | `TypeError` `ERR_INVALID_ARG_VALUE` (the argument is checked first) |
+| Format argument not registered (`render(g, 'pdf')`) | `RenderError` `RENDER_ERROR` | `TypeError` `ERR_INVALID_ARG_VALUE` |
+| DOT `layout="foo"` unknown | `RenderError` `RENDER_ERROR` | `RenderError` `UNKNOWN_LAYOUT` (`type: 'semantic'`) |
+| `render(null)` / `getDrawOps(null)` | `RenderError` ("Cannot read properties of null") | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| `getLayout(null)` / `addEdge(null, …)` | Raw `TypeError` (no code) | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| `getLayout` before layout | `RenderError` `GENERIC_ERROR` | `Error` `ERR_INVALID_STATE` |
+| Builder fails to create a node or subgraph | `RenderError` `GENERIC_ERROR` | `InternalError` `INTERNAL_ERROR` |
+| `ctx.layout` / `freeLayout` with a non-object `g` or non-string engine; `bestRenderer` with a non-string format | Incidental `TypeError` / generic `Error` | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| `getLayout(g, { yAxis: 'other' })` | Silently treated as y-up | `TypeError` `ERR_INVALID_ARG_VALUE` |
+| `createGraph`, builder methods and handles with wrong argument types; `addEdge` with a non-string `name` | Accepted or coerced | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| `setImageSizer` / `setImageResolver` / `setTextMeasurer` with a wrong value | Accepted; failed later inside layout | `TypeError` `ERR_INVALID_ARG_TYPE` |
+| Foreign throw inside layout or render (a bug) | `RenderError` `RENDER_ERROR`, original stack lost | `InternalError` `INTERNAL_ERROR`, `cause` is the original error |
+
+Internal throw sites ported from Graphviz C keep the same condition and message;
+only the class changes:
+
+| Group | Before | After |
+|-------|--------|-------|
+| C `assert` / uncaught C++ `throw` sites (neato gts triangulation and multispline router, vpsc solver, ortho, label index, pack-components, fdp ports, twopi circle, gvc job) | `Error` | `InternalError` `INTERNAL_ERROR` |
+| C `agerr` + `exit` sites (label rectangle-tree overflow, XML escape of malformed UTF-8) | `Error` | `RenderError` `RENDER_ERROR` |
+| Graphviz features the port has not implemented (fdp overlap modes, sfdp `smoothing=` / `rotation=`, special shapes) | `Error` | `RenderError` `UNSUPPORTED_FEATURE` (`type: 'semantic'`) |
+| gts constrained-Delaunay paths where C continues instead of failing | `Error` | No throw; behaviour now matches C |
+
+Attributes that rendered an approximation in 1.x and now throw
+`RenderError` `UNSUPPORTED_FEATURE`. The conditions are exact; the full list,
+with every message, is the table in
+[Errors and exceptions](./docs-site/guide/errors.md#unsupported-feature-reference):
+
+| Engine | Attribute | Throws when |
+|--------|-----------|-------------|
+| neato | `mode=hier` | Always |
+| neato | `mode=ipsep` | Only when Graphviz builds constraints (`diredgeconstraints`, `overlap=ipsep`, or a top-level cluster); otherwise unchanged |
+| neato | `start=self` | `mode` is `major` or `ipsep` |
+| neato | `model=subset` | `mode` is `major` or `KK` |
+| neato | `model=circuit` | `mode` is `major`, or `KK` on a connected graph |
+| neato, twopi, circo, sfdp | `overlap=voronoi` | 2+ nodes and Graphviz's own overlap count (node polygons, not bounding boxes) is above 0. circo: single-component graphs; sfdp: new in 2.0 (the mode was previously ignored); only when `overlap` is not a prism mode |
+| fdp | `splines=compound` | Always |
+| fdp | `overlap=` `voronoi`, `oscale`, `vpsc`, `ipsep`, `ortho*`, `portho*` | The mode is reached after the force-iteration tries |
+| sfdp | `label_scheme=1`..`4` | A `\|edgelabel\|` node exists and Graphviz takes the edge-label path |
+| sfdp | `quadtree=none` or `quadtree=fast` | Always |
+
+Behaviour fixes. These render differently from 1.x because 1.x did not match
+Graphviz; no code change is needed:
+
+| Area | Before | After |
+|------|--------|-------|
+| dot `nslimit` | Ignored; network simplex ran to convergence | Caps the x-coordinate iterations, as Graphviz does |
+| neato `start=regular` | Treated as random | Nodes start on a regular polygon, as Graphviz does |
+| neato `start=randomN` | Only digit-led values were seeded | `N` seeds the generator, as Graphviz does |
+| neato and fdp `inputscale` | Ignored | Divides user `pos` values (and fdp cluster `coords`); `0` or a negative value means 72, absent means no scaling |
+| neato `mode=KK` | Ran stress majorization | Runs Kamada-Kawai, as Graphviz. A disconnected graph without `pack` or `packmode` is laid out whole, not packed |
+| neato `mode=sgd` | Ran stress majorization | Runs stochastic gradient descent, as Graphviz; honours edge `len` and seeds from `start`. Graphviz seeds from the clock when `start` is unset, so set `start=<n>` for reproducible output |
+| neato unknown `mode` value | Ignored without a message | Warns `Illegal value X for attribute "mode" in graph G - ignored` and runs `major`, as Graphviz |
+| neato, twopi, circo, sfdp `overlap=oscale`, `ortho*`, `portho*` | Ignored; overlaps left in place | Removed, as Graphviz (`oscale` scales, the others run constraint-based removal) |
+| neato `overlap=vpsc` | Gap of `nodesep/2` between nodes | Gap of `2*sep` (additive) or 2 x 4 pt, as Graphviz; output changes on every graph using this mode |
+| sfdp `overlap=` any non-prism mode other than `voronoi` | Ignored except `scale` | Runs Graphviz's removal after layout (`voronoi` with overlapping nodes is now an error; see above) |
+| fdp cluster `coords` set only on a subgraph | Ignored | Honoured, as Graphviz |
+| `overlap=voronoi` with nodes that only touch by bounding box | `UNSUPPORTED_FEATURE` | Renders: the overlap test now uses node polygons, as Graphviz |
+| `ctx.freeLayout(g, engine)` | Cleaned up with the engine argument | Cleans up with the engine that ran the layout |
+| XML escaping in UTF-8 mode (no public API sets this mode) | Decoded UTF-16 units as UTF-8 bytes, so a character such as U+00FF raised `RENDER_ERROR` | Escapes by code point (`&#x1f600;`), matching Graphviz; a lone surrogate still raises `RENDER_ERROR` |
+| fdp edges to cluster endpoints under spline routing (for example `splines=true`) | Drew line segments silently | Also prints the Graphviz warning (`splines and cluster edges not supported - using line segments`) |
+
+New exports: `DotEngineError`, `InternalError`, `isGvError`, and the type
+`UsageErrorCode`. `GvErrorCode` gains `INTERNAL_ERROR`, `UNKNOWN_LAYOUT` and
+`UNSUPPORTED_FEATURE`.
 
 ## Layout engines
 
@@ -150,6 +222,55 @@ caller-supplied hook may be required:
   setImageSizer((src) => ({ w: 64, h: 64 })); // return null if unknown
   ```
 
+### Rendering into a page
+
+`renderSvgInto` renders DOT, **waits for the web fonts the graph uses**, and
+replaces the children of an element with the resulting `<svg>`. Insertion goes
+through `DOMParser` + `importNode` (never `innerHTML`) and the SVG is scrubbed by
+default (see [Security](#security)).
+
+```html
+<div id="graph"></div>
+<script type="module">
+  import { renderSvgInto } from '@knowvah/dot-engine';
+
+  const dot = 'digraph { node [fontname="JetBrains Mono"]; a -> b }';
+  const { element, fontIssues } = await renderSvgInto('graph', dot, 'dot');
+
+  for (const { face, reason } of fontIssues) {
+    // reason is 'failed' (the face errored) or 'timeout' (not loaded within
+    // fontTimeoutMs, default 3000). Layout used a fallback font for this face.
+    console.warn(`font ${face}: ${reason}`);
+  }
+</script>
+```
+
+Fonts only need prefetching when they are declared with `@font-face`; an unloaded
+face is measured as the fallback font and the labels come out the wrong size.
+`fontIssues` never causes a rejection — it reports what could not be loaded.
+
+To get the SVG string instead of inserting it, use `renderSvgAsync`. It also
+accepts an **async** `imageSizer` (and `imageResolver`), awaited once per distinct
+image before layout:
+
+```ts
+import { renderSvgAsync } from '@knowvah/dot-engine';
+
+const { svg, fontIssues } = await renderSvgAsync(
+  'digraph { a [label=<<TABLE><TR><TD><IMG SRC="logo.png"/></TD></TR></TABLE>>] }',
+  'dot',
+  {
+    imageSizer: async (src) => {
+      const img = new Image();
+      img.src = src;
+      await img.decode(); // a rejection counts as "unknown size" (a miss)
+      return { w: img.naturalWidth, h: img.naturalHeight };
+    },
+    fontTimeoutMs: 5000,
+  },
+);
+```
+
 ### Text measurement
 
 Layout needs to know how wide each label is. By default this uses a **built-in,
@@ -216,22 +337,67 @@ a **Content-Security-Policy** on the host page as the control point:
 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.
 
+### `renderSvgInto` and the built-in scrubber
+
+`renderSvgInto` sanitizes by default, so inserting untrusted DOT does not need
+extra work for the common vectors. The built-in scrubber **removes**:
+
+- `<script>` and `<foreignObject>` elements (with their subtrees),
+- every `on*` event-handler attribute,
+- `href` / `xlink:href` values using `javascript:` or `vbscript:`, and `data:`
+  hrefs other than `data:image/*` on `<image>`,
+- SMIL animations (`set`, `animate`, `animateMotion`, `animateTransform`) that
+  target `href` or an event handler,
+- `xml-stylesheet` processing instructions.
+
+It **keeps** `http(s)` hrefs and image origins (they are normal, working links
+and images) and `data:image/*` on `<image>`. Origin policy is therefore still
+yours: it is a deny-list for the vectors this library's own output can carry,
+**not** a replacement for a Content-Security-Policy, which remains recommended.
+
+Options, in precedence order:
+
+- `trusted: true` — insert exactly as rendered, no sanitizing. Only for DOT you
+  authored.
+- `sanitize: (svg: string) => string` — replace the built-in scrubber with your
+  own, e.g. DOMPurify:
+
+  ```ts
+  import DOMPurify from 'dompurify';
+  import { renderSvgInto } from '@knowvah/dot-engine';
+
+  await renderSvgInto('graph', dot, 'dot', {
+    sanitize: (svg) => DOMPurify.sanitize(svg, { USE_PROFILES: { svg: true } }),
+  });
+  ```
+
+- neither — the built-in scrubber runs.
+
+`renderSvgAsync` and `renderAsync` return raw markup and do **not** sanitize;
+the caveats above apply to their output exactly as for `renderSvg`.
+
 ## Public API
 
 ```ts
-// Primary entry point. Throws a structured GvError (ParseError / RenderError).
+// Primary entry point. Throws a DotEngineError (ParseError / RenderError /
+// InternalError) for bad input, or a TypeError with a code for a bad call.
 function renderSvg(dotSource: string, engine: string): string;
 
-// Result-style entry point: returns { svg } or { errors: [GvError] }, never throws.
+// Result-style entry point: returns { svg } or { errors: [GvError] } for any DOT
+// input; throws only for invalid arguments.
 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' */ }
+type GvErrorCode = 'SYNTAX_ERROR' | 'SYNTAX_UNEXPECTED_EOF' | /* …10 total */ 'GENERIC_ERROR';
+type UsageErrorCode = 'ERR_INVALID_ARG_TYPE' | 'ERR_INVALID_ARG_VALUE' | 'ERR_OUT_OF_RANGE' | 'ERR_INVALID_STATE';
+abstract class DotEngineError extends Error implements GvError {}
+class ParseError extends DotEngineError { /* type:'syntax' */ }
+class RenderError extends DotEngineError { /* type:'render' | 'semantic' */ }
+class InternalError extends DotEngineError { /* type:'render' */ }
+function isGvError(e: unknown): e is GvError;
 
 // Parse DOT into the in-memory graph model (without laying it out).
 function parse(dotSource: string): Graph;
@@ -240,6 +406,42 @@ function parse(dotSource: string): Graph;
 function setImageSizer(sizer: ImageSizer | null): void;
 type ImageSizer = (src: string) => { w: number; h: number } | null;
 
+// Async counterparts: prefetch web fonts and image data, then render. Font
+// problems never reject; they are returned in `fontIssues`.
+function renderSvgAsync(
+  dotSource: string,
+  engine: EngineName,
+  opts?: AsyncSvgOptions,
+): Promise<{ svg: string; fontIssues: FontIssue[] }>;
+function renderAsync(
+  g: Graph,
+  format: OutputFormat,
+  opts?: AsyncRenderOptions,
+): Promise<{ output: string; fontIssues: FontIssue[] }>;
+
+// Render and insert into the element with the given id (browser; sanitizes by
+// default).
+function renderSvgInto(
+  id: string,
+  src: string,
+  engine: EngineName,
+  opts?: RenderSvgIntoOptions,
+): Promise<{ element: SVGSVGElement; fontIssues: FontIssue[] }>;
+
+type FontIssue = { face: string; reason: 'failed' | 'timeout' };
+interface AsyncRenderOptions extends RenderOptions {
+  imageSizer?: (src: string) => Promise<{ w: number; h: number } | null>;
+  imageResolver?: (src: string) => Promise<{ bytes: Uint8Array; mime?: string } | Uint8Array | null>;
+  fontTimeoutMs?: number; // default 3000
+  fontSet?: FontSetLike;  // default document.fonts
+}
+type AsyncSvgOptions = Omit<AsyncRenderOptions, 'engine'>;
+interface RenderSvgIntoOptions extends AsyncSvgOptions {
+  sanitize?: (svg: string) => string;
+  trusted?: boolean;
+  document?: Document;
+}
+
 // 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;

package/dist/api/builder.d.ts

@@ -72,6 +72,9 @@ export interface GvGraphBuilder {
  * The builder's `.graph` is a fresh Graph ready for handoff to layout/render.
  * Defaults: directed=true, strict=false, name=''.
  *
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `opts` or one of its fields has
+ *   the wrong type. Builder and handle methods throw the same for wrong
+ *   argument types, and `InternalError` if node/subgraph creation fails.
  * @see lib/cgraph/graph.c:agopen
  */
 export declare function createGraph(opts?: CreateGraphOptions): GvGraphBuilder;

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

@@ -1 +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"}
+{"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;AAmPD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAIrE"}

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

@@ -8,6 +8,11 @@
 import type { Graph } from '../model/graph.js';
 import type { Node } from '../model/node.js';
 import { Edge } from '../model/edge.js';
+/**
+ * Argument check shared by the /api entry points: a non-null object.
+ * @internal
+ */
+export declare function requireObject(param: string, v: unknown): void;
 /**
  * Create and insert an edge from `tail` to `head` in graph `g`.
  *
@@ -39,6 +44,8 @@ import { Edge } from '../model/edge.js';
  * // edge.tail === a, edge.head === b
  * ```
  *
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `g`, `tail` or `head` is not an
+ *   object, or `name` is neither undefined nor a string
  * @see lib/cgraph/edge.c:agedge
  */
 export declare function addEdge(g: Graph, tail: Node, head: Node, name?: string): Edge;

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

@@ -1 +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"}
+{"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;AAGxC;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAG,IAAI,CAI7D;AAkDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,OAAO,CACrB,CAAC,EAAE,KAAK,EACR,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,IAAI,EACV,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAkBN"}

package/dist/api/geometry.d.ts

@@ -237,12 +237,15 @@ export interface LayoutSnapshot {
  * 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
+ * with an `ERR_INVALID_STATE` error 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.
+ * @throws TypeError (`ERR_INVALID_ARG_TYPE`) if `g` is not an object or `opts`
+ *   is not an object; (`ERR_INVALID_ARG_VALUE`) if `opts.yAxis` is not
+ *   `'up'` or `'down'`.
+ * @throws Error (`ERR_INVALID_STATE`) if `g` has not been laid out.
  *
  * @see lib/common/types.h:GD_bb, ND_coord, ED_spl
  */

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

@@ -1 +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;AAU/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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;;;OAGG;IACH,EAAE,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B;;;OAGG;IACH,EAAE,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,8EAA8E;IAC9E,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;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;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;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;AAoLD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,cAAc,CAuB1E"}
+{"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;AAW/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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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;;;OAGG;IACH,EAAE,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B;;;OAGG;IACH,EAAE,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,8EAA8E;IAC9E,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;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;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;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;AAgMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,eAAe,GAAG,cAAc,CAwB1E"}