@knowvah/dot-engine 1.9.0 → 2.0.0

package/src/layout/sfdp/spring-driver.ts

@@ -11,6 +11,7 @@
  * @see lib/neatogen/overlap.c:remove_overlap (15.0.0)
  */
 
+import { RenderError } from '../../errors.js';
 import { fma } from '../../common/fma.js';
 import { cdrand } from '../../common/crand.js';
 import {
@@ -30,10 +31,38 @@ import {
 import {
   type SpringElectricalControl,
   AUTOP,
+  QUAD_TREE_NONE,
+  QUAD_TREE_FAST,
   springElectricalEmbedding,
 } from './spring-electrical.js';
 import { removeOverlapPrism } from '../neato/overlap-prism.js';
 
+// ---------------------------------------------------------------------------
+// Quadtree scheme dispatch (loud for the unported embeddings)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mirror of the per-level dispatch: NONE -> _slow, FAST (or HYBRID above
+ * QUAD_TREE_HYBRID_SIZE) -> _fast, else the NORMAL embedding. The first two
+ * are not ported. HYBRID is unreachable here: sfdp's quadtree parser only
+ * yields NONE/NORMAL/FAST (sfdpinit.c:late_quadtree_scheme).
+ * @see lib/sfdpgen/spring_electrical.c:multilevel_spring_electrical_embedding (1140-1148)
+ */
+function embedLevel(
+  dim: number, A: SpMatrix, ctrl: SpringElectricalControl, xc: number[],
+): void {
+  if (ctrl.tscheme === QUAD_TREE_NONE || ctrl.tscheme === QUAD_TREE_FAST) {
+    // Name the resolved scheme: "0"/"false" select none, "2" selects fast.
+    const [value, what] = ctrl.tscheme === QUAD_TREE_NONE
+      ? ['none', 'spring_electrical_embedding_slow']
+      : ['fast', 'spring_electrical_embedding_fast'];
+    throw new RenderError(
+      `quadtree=${value}: ${what} is not supported yet`,
+      'UNSUPPORTED_FEATURE');
+  }
+  springElectricalEmbedding(dim, A, ctrl, xc);
+}
+
 // ---------------------------------------------------------------------------
 // Multilevel driver helpers
 // ---------------------------------------------------------------------------
@@ -178,7 +207,7 @@ export function multilevelSpringElectricalEmbedding(
   }
 
   for (;;) {
-    springElectricalEmbedding(dim, grid!.A, ctrl, xc);
+    embedLevel(dim, grid!.A, ctrl, xc);
     if (multilevelIsFinest(grid!)) break;
     const P = grid!.P!;
     grid = grid!.prev;

package/src/layout/twopi/circle.ts

@@ -8,6 +8,7 @@
  * @see lib/twopigen/circle.h
  */
 
+import { InternalError } from '../../errors.js';
 import type { Graph } from '../../model/graph.js';
 import type { Node } from '../../model/node.js';
 import type { Edge } from '../../model/edge.js';
@@ -23,7 +24,7 @@ export const MIN_RANKSEP = 0.02;
 /** Get the TwopiAlgData record for a node; throws if absent. */
 function rdata(n: Node): TwopiAlgData {
   const d = n.info.alg;
-  if (!d || d.kind !== 'twopi') throw new Error(`twopi: missing rdata on node ${n.name}`);
+  if (!d || d.kind !== 'twopi') throw new InternalError(`twopi: missing rdata on node ${n.name}`);
   return d;
 }
 

package/src/ortho/ortho-parallel.ts

@@ -27,6 +27,7 @@ import { Bend } from "./types.js";
 import { chanSearch, chansInOrder } from "./maze-channels.js";
 import { insertEdge, edgeExists, removeRedge } from "./rawgraph.js";
 import { segCmp } from "./ortho-route.js";
+import { InternalError } from "../errors.js";
 
 /** @see lib/ortho/ortho.c:next_seg */
 function nextSeg(seg: OrthoSegment, dir: number): OrthoSegment | null {
@@ -81,7 +82,7 @@ function decidePoint(
     sj = np2; // eslint-disable-line no-param-reassign
   }
   if (np1 === null) prec = 0;
-  else if (np2 === null) throw new Error("decide_point: np2 null (C assert(0))");
+  else if (np2 === null) throw new InternalError("decide_point: np2 null (C assert(0))");
   else {
     const temp = segCmp(np1, np2);
     if (temp === -2) return -1;

package/src/ortho/trap-query.ts

@@ -13,6 +13,7 @@ import {
   cross, TRAP_MAX,
 } from "./trap-types.js";
 import type { SegPoint, SegmentT, TrapT, QNode } from "./trap-types.js";
+import { InternalError } from "../errors.js";
 
 /**
  * Test whether point v is to the left of segment segnum.
@@ -96,7 +97,7 @@ export function locateEndpoint(
       }
       return locateEndpoint(v, vo, rptr.left, seg, qs);
     case T_X: return locateX(v, vo, rptr, seg, qs);
-    default: throw new Error("locateEndpoint: unreachable");
+    default: throw new InternalError("locateEndpoint: unreachable");
   }
 }
 

package/src/parser/index.ts

@@ -14,18 +14,18 @@ import type { Edge } from '../model/edge.js';
 import { isHtmlValue, htmlValueContent } from '../common/html-string.js';
 import { buildFromAst } from './builder.js';
 import type { ParsedGraph } from './ast.js';
-import type { GvError, GvErrorCode, GvExpectation } from '../errors.js';
-import { friendlyMessageFor } from '../errors.js';
+import type { GvErrorCode, GvExpectation } from '../errors.js';
+import { DotEngineError, friendlyMessageFor, invalidArgType } from '../errors.js';
 
 // ── ParseError ────────────────────────────────────────────────────────────────
 
 /**
  * Thrown for syntax errors or edge-direction violations.
  *
- * Implements the structured {@link GvError} contract: `location` is primary;
+ * Implements the structured {@link DotEngineError} / `GvError` contract: `location` is primary;
  * `line`/`column` are convenience getters that delegate to it.
  */
-export class ParseError extends Error implements GvError {
+export class ParseError extends DotEngineError {
   readonly type = 'syntax';
   readonly code: GvErrorCode;
   readonly friendlyMessage: string;
@@ -37,8 +37,9 @@ export class ParseError extends Error implements GvError {
     code: GvErrorCode,
     location: { line: number; column: number; offset?: number },
     expected?: GvExpectation[],
+    options?: ErrorOptions,
   ) {
-    super(message);
+    super(message, options);
     this.name = 'ParseError';
     this.code = code;
     this.location = location;
@@ -217,17 +218,16 @@ export function isPeggyError(err: unknown): err is {
 
 /**
  * Parse a DOT-language string and return a Graph model.
- * @throws ParseError for syntax errors or edge-direction violations.
+ * @throws ParseError `SYNTAX_ERROR`, `SYNTAX_UNEXPECTED_EOF`, `EDGE_OP_*` for
+ *   syntax errors or edge-direction violations; `GENERIC_ERROR` when nesting
+ *   is too deep
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `src` is not a string
  */
 export function parse(src: string): Graph {
   if (typeof src !== 'string') {
     // Runtime guard for JS callers (the TS signature already forbids this):
     // a non-string argument must not surface as an opaque internal TypeError.
-    throw new ParseError('DOT source must be a string', 'GENERIC_ERROR', {
-      line: 1,
-      column: 1,
-      offset: 0,
-    });
+    throw invalidArgType('dotSource', 'string', src);
   }
   let ast: ParsedGraph;
   try {

package/src/render/index.ts

@@ -22,6 +22,11 @@
 // --- Multi-format render entry (T5) ---------------------------------------
 export { render } from './public.js';
 export type { OutputFormat, RenderOptions } from './public.js';
+export { renderAsync } from '../async/render-async.js';
+export type {
+  AsyncRenderOptions, AsyncRenderResult, AsyncImageSize, AsyncImageBytes,
+  FontIssue, FontSetLike,
+} from '../async/render-async.js';
 
 // --- Structured xdot draw-ops (T6) ----------------------------------------
 export { getDrawOps, DEFAULT_DRAW_ENGINE } from './xdot-public.js';

package/src/render/public.ts

@@ -13,8 +13,7 @@
 import type { Graph } from '../model/graph.js';
 import { createDefaultContext } from '../gvc/default-context.js';
 import { render as deviceRender } from '../gvc/device.js';
-import { RenderError } from '../errors.js';
-import type { GvError } from '../errors.js';
+import { invalidArgType, rethrowAtBoundary } from '../errors.js';
 import type { EngineName } from '../gvc/context.js';
 
 // ---------------------------------------------------------------------------
@@ -64,23 +63,19 @@ export interface RenderOptions {
 // Private helpers (mirrors index.ts)
 // ---------------------------------------------------------------------------
 
-/**
- * Duck-type a thrown value as a {@link GvError}: object with string `type`
- * and string `code`. Re-implemented here (not imported) so this module has
- * no circular dependency on `src/index.ts`.
- */
-function isGvErrorLike(err: unknown): err is GvError {
-  return (
-    typeof err === 'object' &&
-    err !== null &&
-    typeof (err as { type?: unknown }).type === 'string' &&
-    typeof (err as { code?: unknown }).code === 'string'
-  );
-}
 
-/* v8 ignore next -- defensive normalizer; unreachable via public API */
-function messageOf(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
+
+/** Reject a bad `g` / `format` / `opts` before any work starts. */
+function checkRenderArgs(g: unknown, format: unknown, opts: unknown): void {
+  if (typeof g !== 'object' || g === null) {
+    throw invalidArgType('g', 'object', g);
+  }
+  if (typeof format !== 'string') {
+    throw invalidArgType('format', 'string', format);
+  }
+  if (opts !== undefined && (typeof opts !== 'object' || opts === null)) {
+    throw invalidArgType('opts', 'object or undefined', opts);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -91,8 +86,8 @@ function messageOf(err: unknown): string {
  * Render a (parsed or built) graph to the requested format string.
  *
  * Lifecycle: createDefaultContext → layout → deviceRender → freeLayout.
- * Error handling mirrors `renderSvg`: GvError-like throws re-surface
- * unchanged; unknown throws become `RenderError('RENDER_ERROR')`.
+ * Error handling mirrors `renderSvg`: usage errors and GvErrors re-surface
+ * unchanged; any other throw becomes an `InternalError` with `cause` set.
  *
  * @remarks
  * Security: for the markup formats (`svg`, `cmapx`, `imap`), treat the output
@@ -106,7 +101,13 @@ function messageOf(err: unknown): string {
  * @param format - target output format
  * @param opts   - optional engine override (default: `'dot'`)
  * @returns rendered string in the requested format
- * @throws RenderError on layout or render failure
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `g` is not an object, `format`
+ *   is not a string, or `opts` is neither undefined nor an object
+ * @throws TypeError `ERR_INVALID_ARG_VALUE` if the engine or format is not
+ *   registered
+ * @throws RenderError `RENDER_ERROR`, `UNKNOWN_LAYOUT` or `UNSUPPORTED_FEATURE`
+ *   on layout or render failure
+ * @throws InternalError `INTERNAL_ERROR` on a dot-engine bug
  *
  * @see lib/gvc/gvc.c:gvRender
  */
@@ -115,6 +116,7 @@ export function render(
   format: OutputFormat,
   opts?: RenderOptions,
 ): string {
+  checkRenderArgs(g, format, opts);
   const engine: EngineName = opts?.engine ?? 'dot';
   const inlineImages = opts?.inlineImages ?? false;
   const ctx = createDefaultContext();
@@ -124,8 +126,6 @@ export function render(
     ctx.freeLayout(g, engine);
     return result;
   } catch (err: unknown) {
-    /* v8 ignore next -- current engines don't throw a GvError-like value here */
-    if (isGvErrorLike(err)) throw err;
-    throw new RenderError(messageOf(err), 'RENDER_ERROR');
+    return rethrowAtBoundary(err);
   }
 }

package/src/render/svg.ts

@@ -282,7 +282,7 @@ export class SvgRenderer implements RendererPlugin {
     const originy = (b.ur.y + b.ll.y + height) / 2;
     let href = src;
     if (job.inlineImages === true) {
-      const found = findImageBytes(src);
+      const found = findImageBytes(src, job.imageResolver);
       if (found !== null) href = toDataUri(found.bytes, found.mime);
     }
     job.write('<image xlink:href="' + escapeXml(href) + '" width="' + g(width)

package/src/render/xdot-public.ts

@@ -34,8 +34,7 @@ import { render as gvcRender } from '../gvc/device.js';
 import { createDefaultContext } from '../gvc/default-context.js';
 import { parseXDot } from '../xdot/index.js';
 import type { EngineName } from '../gvc/context.js';
-import { RenderError } from '../errors.js';
-import type { GvError } from '../errors.js';
+import { invalidArgType, rethrowAtBoundary } from '../errors.js';
 
 /**
  * `Xdot` — the parsed result of one xdot attribute stream: `ops` (the
@@ -76,20 +75,16 @@ const XDOT_DRAW_ATTRS = [
   '_draw_', '_ldraw_', '_hdraw_', '_tdraw_', '_hldraw_', '_tldraw_',
 ] as const;
 
-function isGvErrorLike(err: unknown): err is GvError {
-  return (
-    typeof err === 'object' &&
-    err !== null &&
-    typeof (err as { type?: unknown }).type === 'string' &&
-    typeof (err as { code?: unknown }).code === 'string'
-  );
-}
 
-/** Re-throw GvError-like values; otherwise wrap as RENDER_ERROR. */
-function rethrowAsRender(err: unknown): never {
-  if (isGvErrorLike(err)) throw err;
-  const msg = err instanceof Error ? err.message : String(err);
-  throw new RenderError(msg, 'RENDER_ERROR');
+
+/** Reject a bad `g` / `opts` before any work starts. */
+function checkDrawOpsArgs(g: unknown, opts: unknown): void {
+  if (typeof g !== 'object' || g === null) {
+    throw invalidArgType('g', 'object', g);
+  }
+  if (opts !== undefined && (typeof opts !== 'object' || opts === null)) {
+    throw invalidArgType('opts', 'object or undefined', opts);
+  }
 }
 
 /** Append XdotOps found in `attrs` for each xdot draw key into `out`. */
@@ -118,7 +113,7 @@ function layoutAndRenderXdot(g: Graph, engine: EngineName): string {
     ctx.freeLayout(g, engine);
     return src;
   } catch (err: unknown) {
-    rethrowAsRender(err);
+    return rethrowAtBoundary(err);
   }
 }
 
@@ -132,8 +127,13 @@ function layoutAndRenderXdot(g: Graph, engine: EngineName): string {
  * @param g    - A Graph from `parse()` or the builder API.
  * @param opts - Optional: `{ engine }` overrides the default `'dot'`.
  * @returns Flat typed draw-op array covering the full graph.
- * @throws ParseError  if the xdot DOT output cannot be re-parsed.
- * @throws RenderError if layout or rendering fails.
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `g` is not an object or `opts`
+ *   is neither undefined nor an object
+ * @throws TypeError `ERR_INVALID_ARG_VALUE` if `opts.engine` is not registered
+ * @throws RenderError `RENDER_ERROR`, `UNKNOWN_LAYOUT` or `UNSUPPORTED_FEATURE`
+ *   if layout or rendering fails
+ * @throws ParseError if the xdot output cannot be re-parsed (a dot-engine bug)
+ * @throws InternalError `INTERNAL_ERROR` on any other dot-engine bug
  *
  * @example
  * ```ts
@@ -159,6 +159,7 @@ function layoutAndRenderXdot(g: Graph, engine: EngineName): string {
  * @see lib/gvc/gvc.h:gvRender
  */
 export function getDrawOps(g: Graph, opts?: DrawOpsOptions): XdotOp[] {
+  checkDrawOpsArgs(g, opts);
   const engine = opts?.engine ?? DEFAULT_DRAW_ENGINE;
   return collectGraphOps(parse(layoutAndRenderXdot(g, engine)));
 }

package/src/util/xml.ts

@@ -6,6 +6,8 @@
  * @see lib/util/xml.c
  */
 
+import { RenderError } from '../errors.js';
+
 /** Options to tweak the behaviour of XML escaping. @see lib/util/xml.h:xml_flags_t */
 export interface XmlFlags {
   /** Escape & unconditionally; also escape \n and \r. */
@@ -125,45 +127,37 @@ class XmlEscaper {
   }
 
   /**
-   * Decode a multi-byte UTF-8 sequence at s[pos] and emit &#xNNNN;.
+   * Emit &#xNNNN; for the Unicode code point at s[pos]. JS strings are
+   * UTF-16, so the code point (what C decodes from UTF-8) comes from
+   * codePointAt, and an astral character consumes two units.
    * @see lib/util/xml.c:xml_core (UTF-8 block)
    */
   static utf8Entity(s: string, pos: number): [string, number] {
-    const b0 = s.charCodeAt(pos) & 0xff;
-    const cp = XmlEscaper.decodeUtf8(s, pos, b0);
-    const consumed = XmlEscaper.utf8ByteLen(b0);
+    const cp = XmlEscaper.decodeUtf8(s, pos);
+    const consumed = XmlEscaper.utf8ByteLen(cp);
     return [`&#x${cp.toString(16)};`, consumed];
   }
 
-  /** Decode the codepoint value from a multi-byte UTF-8 sequence. */
-  static decodeUtf8(s: string, pos: number, b0: number): number {
-    if ((b0 >> 5) === 6) {
-      return ((b0 & 0x1f) << 6) | (s.charCodeAt(pos + 1) & 0x3f);
-    }
-    if ((b0 >> 4) === 14) {
-      return (
-        ((b0 & 0x0f) << 12) |
-        ((s.charCodeAt(pos + 1) & 0x3f) << 6) |
-        (s.charCodeAt(pos + 2) & 0x3f)
-      );
-    }
-    if ((b0 >> 3) === 30) {
-      return (
-        ((b0 & 0x07) << 18) |
-        ((s.charCodeAt(pos + 1) & 0x3f) << 12) |
-        ((s.charCodeAt(pos + 2) & 0x3f) << 6) |
-        (s.charCodeAt(pos + 3) & 0x3f)
-      );
+  /**
+   * Return the code point at s[pos]. A lone surrogate is the analogue of
+   * malformed UTF-8, where C reports an error and exits (xml.c:135).
+   * @see lib/util/xml.c:xml_core (fprintf + graphviz_exit at xml.c:135)
+   */
+  static decodeUtf8(s: string, pos: number): number {
+    const cp = s.codePointAt(pos)!; // caller: pos < s.length
+    if (cp >= 0xd800 && cp <= 0xdfff) {
+      throw new RenderError(`gvXmlEscape: malformed UTF-8 at position ${pos}`, 'RENDER_ERROR');
     }
-    throw new Error(`gvXmlEscape: malformed UTF-8 at position ${pos}`);
+    return cp;
   }
 
-  /** Return the byte-length of a UTF-8 sequence from its leading byte. */
-  static utf8ByteLen(b0: number): number {
-    if ((b0 >> 5) === 6) return 2;
-    if ((b0 >> 4) === 14) return 3;
-    if ((b0 >> 3) === 30) return 4;
-    throw new Error(`gvXmlEscape: invalid UTF-8 leading byte 0x${b0.toString(16)}`);
+  /**
+   * Return how many UTF-16 units encode the code point (C: the UTF-8 byte
+   * length from the leading byte).
+   * @see lib/util/xml.c:xml_core (length computation)
+   */
+  static utf8ByteLen(cp: number): number {
+    return cp > 0xffff ? 2 : 1;
   }
 
   static isDecDigit(c: string): boolean {

package/src/vpsc/Solver.ts

@@ -13,6 +13,7 @@ import { Variable } from "./Variable.js";
 import { Constraint } from "./Constraint.js";
 import { Block } from "./Block.js";
 import { Blocks } from "./Blocks.js";
+import { InternalError } from "../errors.js";
 
 // ---------------------------------------------------------------------------
 // Rectangle
@@ -126,10 +127,11 @@ export class VPSC {
   /**
    * Throw if any constraint has slack < -1e-7.
    * Shared between satisfy() and refine().
+   * @see lib/vpsc/solve_VPSC.cpp:VPSC::satisfy (uncaught std::runtime_error)
    */
   private verifyConstraints(): void {
     for (const c of this.cs) {
-      if (c.slack() < -0.0000001) throw new Error("Unsatisfied constraint");
+      if (c.slack() < -0.0000001) throw new InternalError("Unsatisfied constraint");
     }
   }
 
@@ -183,7 +185,7 @@ export class IncVPSC extends VPSC {
       if (lb !== rb) {
         lb.mergeTwoArg(rb, vc);
       } else {
-        if (++splitCtr > 10000) throw new Error("Cycle Error!");
+        if (++splitCtr > 10000) throw new InternalError("Cycle Error!");
         const [splitC, newLb, newRb] = lb.splitBetween(vc.left, vc.right);
         this.inactive.push(splitC);
         newLb.mergeTwoArg(newRb, vc);
@@ -192,7 +194,7 @@ export class IncVPSC extends VPSC {
     }
     this.bs.cleanup();
     for (const c of this.cs) {
-      if (c.slack() < -0.0000001) throw new Error("Unsatisfied constraint");
+      if (c.slack() < -0.0000001) throw new InternalError("Unsatisfied constraint");
     }
   }