@knowvah/dot-engine 1.8.1 → 2.0.0

package/dist/util/xml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/util/xml.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAE9D"}
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../src/util/xml.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAIH,sFAAsF;AACtF,MAAM,WAAW,QAAQ;IACvB,uDAAuD;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,2BAA2B;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,oCAAoC;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAE9D"}

package/dist/vpsc/Solver.d.ts

@@ -57,6 +57,7 @@ export declare 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;
     /**

package/dist/vpsc/Solver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Solver.d.ts","sourceRoot":"","sources":["../../src/vpsc/Solver.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAOrC;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAOtD,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,UAAU,IAAI,MAAM;IACpB,UAAU,IAAI,MAAM;IACpB,KAAK,IAAI,MAAM;IACf,MAAM,IAAI,MAAM;IAEhB,sFAAsF;IACtF,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM;IAQ9B,sFAAsF;IACtF,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM;CAO/B;AAQD;;;;;GAKG;AACH,qBAAa,IAAI;IACf,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC;IAE3B,oDAAoD;gBACxC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE;IAK5C;;;;OAIG;IACH,OAAO,IAAI,IAAI;IASf,mDAAmD;IACnD,OAAO,CAAC,MAAM;IAoBd;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACH,KAAK,IAAI,IAAI;CAId;AAQD;;;;;GAKG;AACH,qBAAa,OAAQ,SAAQ,IAAI;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,QAAQ,CAAe;IAE/B,0DAA0D;gBAC9C,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE;IAO5C;;;;OAIG;IACM,OAAO,IAAI,IAAI;IAwBxB;;;OAGG;IACH,UAAU,IAAI,IAAI;IAOlB;;;OAGG;IACH,WAAW,IAAI,IAAI;IAqBnB;;;OAGG;IACM,KAAK,IAAI,IAAI;IAWtB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAkBrB;AAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"Solver.d.ts","sourceRoot":"","sources":["../../src/vpsc/Solver.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,IAAI,CAAS;gBAET,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM;IAOtD,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,OAAO,IAAI,MAAM;IACjB,UAAU,IAAI,MAAM;IACpB,UAAU,IAAI,MAAM;IACpB,KAAK,IAAI,MAAM;IACf,MAAM,IAAI,MAAM;IAEhB,sFAAsF;IACtF,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM;IAQ9B,sFAAsF;IACtF,QAAQ,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM;CAO/B;AAQD;;;;;GAKG;AACH,qBAAa,IAAI;IACf,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC;IAE3B,oDAAoD;gBACxC,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE;IAK5C;;;;OAIG;IACH,OAAO,IAAI,IAAI;IASf,mDAAmD;IACnD,OAAO,CAAC,MAAM;IAoBd;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACH,KAAK,IAAI,IAAI;CAId;AAQD;;;;;GAKG;AACH,qBAAa,OAAQ,SAAQ,IAAI;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,QAAQ,CAAe;IAE/B,0DAA0D;gBAC9C,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE;IAO5C;;;;OAIG;IACM,OAAO,IAAI,IAAI;IAwBxB;;;OAGG;IACH,UAAU,IAAI,IAAI;IAOlB;;;OAGG;IACH,WAAW,IAAI,IAAI;IAqBnB;;;OAGG;IACM,KAAK,IAAI,IAAI;IAWtB;;;OAGG;IACH,OAAO,CAAC,YAAY;CAkBrB;AAED,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "1.8.1",
+  "version": "2.0.0",
   "description": "Faithful TypeScript port of Graphviz (dot, neato, fdp, sfdp, circo, twopi, osage, patchwork) — no C: no native binary, no WASM. Oracle-verified against the C implementation, runs in the browser.",
   "keywords": [
     "graphviz",

package/src/api/builder.ts

@@ -16,8 +16,8 @@ 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 { addEdge as cgraphAddEdge, requireObject } from './edge-ops.js';
+import { InternalError, invalidArgType } from '../errors.js';
 import { HTML_STRING_MARK } from '../common/html-string.js';
 
 // ── Public interfaces ──────────────────────────────────────────────────────────
@@ -101,14 +101,17 @@ class NodeHandle implements GvNode {
   }
 
   setAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._node.attrs.set(k, v);
   }
 
   setHtmlAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._node.attrs.set(k, HTML_STRING_MARK + v);
   }
 
   getAttr(k: string): string | undefined {
+    requireString('k', k);
     return this._node.attrs.get(k);
   }
 }
@@ -130,18 +133,67 @@ class EdgeHandle implements GvEdge {
   }
 
   setAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._edge.attrs.set(k, v);
   }
 
   setHtmlAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._edge.attrs.set(k, HTML_STRING_MARK + v);
   }
 
   getAttr(k: string): string | undefined {
+    requireString('k', k);
     return this._edge.attrs.get(k);
   }
 }
 
+// ── Argument checks (ADR-3: typeof / null only) ───────────────────────────────
+
+/** `name`, `k`, `v`: must be a string. */
+function requireString(param: string, v: unknown): void {
+  if (typeof v !== 'string') throw invalidArgType(param, 'string', v);
+}
+
+/** `attrs`: `undefined` or a plain object whose values are strings. */
+function requireAttrs(param: string, attrs: unknown): void {
+  if (attrs === undefined) return;
+  requireObject(param, attrs);
+  if (Array.isArray(attrs)) throw invalidArgType(param, 'plain object', attrs);
+  for (const [k, v] of Object.entries(attrs as Record<string, unknown>)) {
+    if (typeof v !== 'string') {
+      throw invalidArgType(`${param}.${k}`, 'string', v);
+    }
+  }
+}
+
+/** Node ref: a string or a handle created by this library. */
+function requireNodeRef(param: string, ref: unknown): void {
+  if (typeof ref === 'string' || ref instanceof NodeHandle) return;
+  throw invalidArgType(param, 'string or GvNode', ref);
+}
+
+/** Key/value pair of setAttr/setHtmlAttr. */
+function requireKeyValue(k: unknown, v: unknown): void {
+  requireString('k', k);
+  requireString('v', v);
+}
+
+/** `createGraph` options: `undefined` or an object with typed fields. */
+function requireGraphOptions(opts: unknown): void {
+  if (opts === undefined) return;
+  requireObject('opts', opts);
+  const o = opts as Record<string, unknown>;
+  for (const key of ['directed', 'strict'] as const) {
+    if (o[key] !== undefined && typeof o[key] !== 'boolean') {
+      throw invalidArgType(`opts.${key}`, 'boolean or undefined', o[key]);
+    }
+  }
+  if (o['name'] !== undefined && typeof o['name'] !== 'string') {
+    throw invalidArgType('opts.name', 'string or undefined', o['name']);
+  }
+}
+
 // ── Builder implementation ─────────────────────────────────────────────────────
 
 /** Resolve a GvNode handle or a name string to an internal Node. */
@@ -149,7 +201,9 @@ 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');
+      throw new InternalError(
+        `Failed to resolve node '${ref}' in graph '${g.name}'`,
+      );
     }
     return node;
   }
@@ -194,6 +248,9 @@ class GraphBuilder implements GvGraphBuilder {
     head: GvNode | string,
     attrs?: Record<string, string>,
   ): GvEdge {
+    requireNodeRef('tail', tail);
+    requireNodeRef('head', head);
+    requireAttrs('attrs', attrs);
     const tailNode = resolveNode(this._graph, tail);
     const headNode = resolveNode(this._graph, head);
     const edge = cgraphAddEdge(this._graph, tailNode, headNode);
@@ -202,23 +259,28 @@ class GraphBuilder implements GvGraphBuilder {
   }
 
   addSubgraph(name: string, attrs?: Record<string, string>): GvGraphBuilder {
+    requireString('name', name);
+    requireAttrs('attrs', attrs);
     const sg = agsubg(this._context, name, true);
     if (sg === null) {
-      throw new RenderError(`Failed to create subgraph '${name}'`, 'GENERIC_ERROR');
+      throw new InternalError(`Failed to create subgraph '${name}'`);
     }
     applyAttrs(sg.attrs, attrs);
     return new GraphBuilder(this._graph, sg);
   }
 
   setAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._context.attrs.set(k, v);
   }
 
   setHtmlAttr(k: string, v: string): void {
+    requireKeyValue(k, v);
     this._context.attrs.set(k, HTML_STRING_MARK + v);
   }
 
   getAttr(k: string): string | undefined {
+    requireString('k', k);
     return this._context.attrs.get(k);
   }
 }
@@ -233,8 +295,10 @@ function addNodeToContext(
   name: string,
   attrs: Record<string, string> | undefined,
 ): GvNode {
+  requireString('name', name);
+  requireAttrs('attrs', attrs);
   const node = agnode(root, name, true);
-  if (node === null) throw new RenderError(`Failed to create node '${name}'`, 'GENERIC_ERROR');
+  if (node === null) throw new InternalError(`Failed to create node '${name}'`);
   applyAttrs(node.attrs, attrs);
   if (context !== root) agsubnode(context, node, true);
   return new NodeHandle(node);
@@ -269,9 +333,13 @@ function resolveKind(opts: CreateGraphOptions | undefined): GraphKind {
  * 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 function createGraph(opts?: CreateGraphOptions): GvGraphBuilder {
+  requireGraphOptions(opts);
   const g = new Graph(opts?.name ?? '', resolveKind(opts));
   return new GraphBuilder(g, g);
 }

package/src/api/edge-ops.ts

@@ -11,6 +11,17 @@
 import type { Graph } from '../model/graph.js';
 import type { Node } from '../model/node.js';
 import { Edge } from '../model/edge.js';
+import { invalidArgType } from '../errors.js';
+
+/**
+ * Argument check shared by the /api entry points: a non-null object.
+ * @internal
+ */
+export function requireObject(param: string, v: unknown): void {
+  if (typeof v !== 'object' || v === null) {
+    throw invalidArgType(param, 'object', v);
+  }
+}
 
 /** @see lib/cgraph/cgraph.h:agisundirected */
 function isUndirected(g: Graph): boolean {
@@ -91,6 +102,8 @@ function insertEdge(g: Graph, root: Graph, edge: Edge): void {
  * // 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 function addEdge(
@@ -99,6 +112,12 @@ export function addEdge(
   head: Node,
   name?: string,
 ): Edge {
+  requireObject('g', g);
+  requireObject('tail', tail);
+  requireObject('head', head);
+  if (name !== undefined && typeof name !== 'string') {
+    throw invalidArgType('name', 'string or undefined', name);
+  }
   const root = g.root;
   const undirected = isUndirected(g);
 

package/src/api/geometry.ts

@@ -34,7 +34,8 @@ import type { Graph } from '../model/graph.js';
 import type { Node } from '../model/node.js';
 import type { Edge } from '../model/edge.js';
 import type { TextlabelT } from '../common/types.js';
-import { RenderError } from '../errors.js';
+import { invalidArgValue, invalidState } from '../errors.js';
+import { requireObject } from './edge-ops.js';
 
 // ---------------------------------------------------------------------------
 // Public coordinate types (canonical home — T5 imports GeometryOptions here)
@@ -399,6 +400,18 @@ function collectClusters(
 // Public API
 // ---------------------------------------------------------------------------
 
+const Y_AXES: readonly YAxis[] = ['up', 'down'];
+
+/** Argument check for getLayout's options (cheap typeof checks only). */
+function checkGeometryOptions(opts: GeometryOptions | undefined): void {
+  if (opts === undefined) return;
+  requireObject('opts', opts);
+  const y: unknown = opts.yAxis;
+  if (y !== undefined && y !== 'up' && y !== 'down') {
+    throw invalidArgValue('opts.yAxis', y, Y_AXES);
+  }
+}
+
 /**
  * Returns a plain, JSON-serializable snapshot of the computed geometry for
  * all nodes and edges in graph `g`.
@@ -406,20 +419,24 @@ function collectClusters(
  * 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
  */
 export function getLayout(g: Graph, opts?: GeometryOptions): LayoutSnapshot {
+  requireObject('g', g);
+  checkGeometryOptions(opts);
   if (g.info?.laidOut !== true) {
-    throw new RenderError(
+    throw invalidState(
       'getLayout requires a laid-out graph; run ctx.layout(g, engine) or render() first',
-      'GENERIC_ERROR',
     );
   }
   const yAxis: YAxis = opts?.yAxis ?? 'down';

package/src/async/collect.ts

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Resource collector: the fonts and image sources the synchronous pipeline
+ * will ask for, gathered from the parsed graph before any layout runs.
+ *
+ * Each font request mirrors a measurer call site exactly (same attribute
+ * lookup, same defaults and fallbacks), so a prefetch loads the faces the
+ * measurer will actually measure.
+ *
+ * @see src/common/nodeinit.ts:initNodeXLabel / src/common/poly-init.ts:buildNodeLabel
+ * @see src/common/edge-label-init.ts (edge, xlabel, head/tail labels)
+ * @see src/layout/dot/graph-label.ts:doGraphLabel (root and cluster labels)
+ * @see src/common/htmltable.ts / htmltable-pos-runs.ts (HTML item fonts)
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Edge } from '../model/edge.js';
+import type { Node } from '../model/node.js';
+import type { TextVariantFlags } from '../common/textmeasure.js';
+import { canvasFont } from '../common/css-font.js';
+import { DEFAULT_FONTNAME, DEFAULT_FONTSIZE } from '../common/make-label.js';
+import { isHtmlValue, htmlValueContent } from '../common/html-string.js';
+import { nodeAttr, readFontAttrs } from '../common/poly-init.js';
+import { initFontEdgeAttr, initFontLabelEdgeAttr } from '../common/edge-label-init.js';
+import { parseHtmlLabel } from '../common/htmltable-parse.js';
+import { isACluster } from '../layout/dot/rank.js';
+import type {
+  HtmlCellContent, HtmlLabel, HtmlTable, HtmlTextItem,
+} from '../common/htmltable-types.js';
+
+/** One font face the measurer will be asked for. */
+export interface FontRequest {
+  /** Graphviz `fontname` as the measurer receives it. */
+  readonly fontname: string | null;
+  /** Font size in points. */
+  readonly fontsize: number;
+  /** Bold/italic variant flags; absent for the regular face. */
+  readonly flags?: TextVariantFlags;
+}
+
+/** Everything the sync pipeline needs prefetched. */
+export interface Resources {
+  /** Distinct font requests, deduped by their `canvasFont` string. */
+  readonly fonts: FontRequest[];
+  /** Distinct HTML `<IMG SRC>` values (dimension lookups). */
+  readonly sizeSrcs: string[];
+  /** Distinct image sources to fetch as bytes; empty unless `inlineImages`. */
+  readonly bytesSrcs: string[];
+}
+
+/** Options for {@link collectResources}. */
+export interface CollectOptions {
+  /** Also collect `image=` and HTML `<IMG SRC>` values as bytes sources. */
+  readonly inlineImages: boolean;
+}
+
+interface Acc {
+  readonly fonts: Map<string, FontRequest>;
+  readonly sizeSrcs: Set<string>;
+  readonly bytesSrcs: Set<string>;
+  readonly inlineImages: boolean;
+}
+
+interface LabelFont { readonly fontname: string; readonly fontsize: number }
+
+function addFont(acc: Acc, fontname: string | null, fontsize: number, flags?: TextVariantFlags): void {
+  const key = canvasFont(fontname, fontsize, flags);
+  if (acc.fonts.has(key)) return;
+  const req: FontRequest = flags === undefined
+    ? { fontname, fontsize }
+    : { fontname, fontsize, flags };
+  acc.fonts.set(key, req);
+}
+
+function addImage(acc: Acc, src: string | undefined, sized: boolean): void {
+  if (src === undefined || src === '') return;
+  if (sized) acc.sizeSrcs.add(src);
+  if (acc.inlineImages) acc.bytesSrcs.add(src);
+}
+
+/** Variant flags as the measurer receives them (undefined when regular). */
+function variantFlags(item: HtmlTextItem): TextVariantFlags | undefined {
+  if (item.bold !== true && item.italic !== true) return undefined;
+  return { bold: item.bold === true, italic: item.italic === true };
+}
+
+function addItemFont(acc: Acc, item: HtmlTextItem, font: LabelFont): void {
+  if (item.text === undefined && item.br !== true) return;
+  addFont(acc, item.fontFace ?? font.fontname, item.fontSize ?? font.fontsize, variantFlags(item));
+}
+
+function walkContent(acc: Acc, c: HtmlCellContent, font: LabelFont): void {
+  switch (c.kind) {
+    case 'text':
+      for (const item of c.items) addItemFont(acc, item, font);
+      break;
+    case 'table':
+      walkTable(acc, c, font);
+      break;
+    case 'image':
+      addImage(acc, c.src, true);
+      break;
+    case 'hr':
+      break;
+  }
+}
+
+function walkTable(acc: Acc, t: HtmlTable, font: LabelFont): void {
+  for (const row of t.rows) {
+    for (const cell of row.cells) {
+      for (const c of cell.content) walkContent(acc, c, font);
+    }
+  }
+}
+
+function walkHtmlLabel(acc: Acc, label: HtmlLabel, font: LabelFont): void {
+  if (label.kind === 'table') {
+    walkTable(acc, label.table, font);
+    return;
+  }
+  for (const t of label.texts) walkContent(acc, t, font);
+}
+
+/** Collect the fonts/images one label string leads the sync pipeline to use. */
+function addLabel(acc: Acc, str: string | undefined, font: LabelFont): void {
+  if (!str) return;
+  if (!isHtmlValue(str)) {
+    addFont(acc, font.fontname, font.fontsize);
+    return;
+  }
+  const content = htmlValueContent(str);
+  if (content === '') return; // labels.c:119 — empty HTML is no label
+  let label: HtmlLabel;
+  try {
+    label = parseHtmlLabel(content);
+  } catch {
+    // Parse failure: the sync path reverts to a plain-text label (htmltable.c:1892).
+    addFont(acc, font.fontname, font.fontsize);
+    return;
+  }
+  walkHtmlLabel(acc, label, font);
+}
+
+function collectNode(acc: Acc, n: Node, root: Graph): void {
+  const { fontname, fontsize } = readFontAttrs(n, root);
+  const label = nodeAttr(n, root, 'label');
+  if (label === undefined) addFont(acc, fontname, fontsize); // label defaults to \N
+  else addLabel(acc, label, { fontname, fontsize });
+  addLabel(acc, nodeAttr(n, root, 'xlabel'), { fontname, fontsize });
+  addImage(acc, nodeAttr(n, root, 'image'), false);
+}
+
+function collectEdge(acc: Acc, e: Edge): void {
+  const fi = initFontEdgeAttr(e);
+  const lfi = initFontLabelEdgeAttr(e, fi);
+  addLabel(acc, e.attrs.get('label'), fi);
+  addLabel(acc, e.attrs.get('xlabel'), fi);
+  addLabel(acc, e.attrs.get('headlabel'), lfi);
+  addLabel(acc, e.attrs.get('taillabel'), lfi);
+}
+
+/**
+ * Root/cluster label font. A subgraph reads through its parse-time defaults
+ * snapshot, as doGraphLabel does. @see src/layout/dot/graph-label.ts:readFontParams
+ */
+function graphLabelFont(sg: Graph): LabelFont {
+  const get = (k: string): string | undefined => sg.attrs.get(k) ?? sg.graphDefaultsSnapshot?.get(k);
+  return {
+    fontname: get('fontname') ?? DEFAULT_FONTNAME,
+    fontsize: parseFloat(get('fontsize') ?? '') || DEFAULT_FONTSIZE,
+  };
+}
+
+function collectGraphLabels(acc: Acc, sg: Graph, root: Graph): void {
+  if (isACluster(sg)) {
+    addLabel(acc, sg.attrs.get('label') ?? sg.graphDefaultsSnapshot?.get('label'), graphLabelFont(sg));
+  }
+  for (const child of sg.subgraphs.values()) collectGraphLabels(acc, child, root);
+}
+
+/**
+ * Gather every font face and image source the synchronous pipeline will ask
+ * for. Pure: reads the parsed graph only; a malformed HTML label is skipped
+ * (the sync path falls back to plain text).
+ *
+ * @param g - A parsed graph (before layout).
+ * @param opts - Collection options.
+ * @returns The deduped fonts, size sources and bytes sources.
+ */
+export function collectResources(g: Graph, opts: CollectOptions): Resources {
+  const acc: Acc = {
+    fonts: new Map(), sizeSrcs: new Set(), bytesSrcs: new Set(), inlineImages: opts.inlineImages,
+  };
+  const root = g.root;
+  collectGraphLabels(acc, root, root);
+  for (const n of root.nodes.values()) collectNode(acc, n, root);
+  for (const e of root.edges) collectEdge(acc, e);
+  return {
+    fonts: [...acc.fonts.values()],
+    sizeSrcs: [...acc.sizeSrcs],
+    bytesSrcs: [...acc.bytesSrcs],
+  };
+}

package/src/async/fonts.ts

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EPL-2.0
+import { canvasFont } from '../common/css-font.js';
+import type { FontRequest } from './collect.js';
+
+/** A font that could not be made available before measuring. */
+export type FontIssue = { face: string; reason: 'failed' | 'timeout' };
+
+/** Structural subset of `FontFaceSet`; the real object satisfies it. */
+export interface FontSetLike {
+  load(font: string): Promise<readonly { status?: string }[]>;
+}
+
+type Outcome = FontIssue['reason'] | 'ok';
+
+async function settle(set: FontSetLike, face: string): Promise<Outcome> {
+  try {
+    const faces = await set.load(face);
+    return faces.some((f) => f.status === 'error') ? 'failed' : 'ok';
+  } catch {
+    // A rejected load is reported as a `failed` issue, not rethrown.
+    return 'failed';
+  }
+}
+
+function toIssues(faces: readonly string[], outcomes: readonly Outcome[]): FontIssue[] {
+  const issues: FontIssue[] = [];
+  faces.forEach((face, i) => {
+    const reason = outcomes[i];
+    if (reason === undefined || reason === 'ok') return;
+    console.warn(`dot-engine: font "${face}" ${reason}`);
+    issues.push({ face, reason });
+  });
+  return issues;
+}
+
+/**
+ * Loads every distinct CSS font the requests map to (in parallel, sharing one
+ * deadline) so canvas measurement sees real faces rather than fallbacks.
+ * Resolves with one {@link FontIssue} per face that failed or timed out;
+ * never rejects. An undefined `fontSet` yields `[]` immediately.
+ */
+export async function loadFonts(
+  fontSet: FontSetLike | undefined,
+  fonts: readonly FontRequest[],
+  timeoutMs: number,
+): Promise<FontIssue[]> {
+  if (fontSet === undefined) return [];
+  const faces = [...new Set(fonts.map((f) => canvasFont(f.fontname, f.fontsize, f.flags)))];
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<Outcome>((resolve) => {
+    timer = setTimeout(() => resolve('timeout'), timeoutMs);
+  });
+  try {
+    const outcomes = await Promise.all(
+      faces.map((face) => Promise.race([settle(fontSet, face), deadline])),
+    );
+    return toIssues(faces, outcomes);
+  } finally {
+    clearTimeout(timer);
+  }
+}