@knowvah/dot-engine 0.1.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowvah/dot-engine",
-  "version": "0.1.0",
+  "version": "1.1.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",
@@ -66,13 +66,12 @@
     "survey:dashboard": "tsx test/corpus/dashboard.ts",
     "survey:baseline": "GV_TEXT_MEASURER=lut tsx test/corpus/survey.ts",
     "docs:copy-reports": "node docs-site/copy-reports.mjs",
+    "docs:copy-goldens": "node docs-site/copy-goldens.mjs",
     "docs:api": "typedoc",
-    "docs:dev": "npm run docs:copy-reports && npm run docs:api && vitepress dev docs-site",
-    "docs:build": "npm run docs:copy-reports && npm run docs:api && vitepress build docs-site",
+    "docs:dev": "npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:api && vitepress dev docs-site",
+    "docs:build": "npm run docs:copy-reports && npm run docs:copy-goldens && npm run docs:api && vitepress build docs-site",
     "docs:preview": "vitepress preview docs-site",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "npm run build && changeset publish",
+    "release": "semantic-release",
     "publish:check": "npm run typecheck && npm run build && npm pack --dry-run",
     "prepublishOnly": "npm run typecheck && npm run build"
   },
@@ -88,7 +87,10 @@
     }
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.1",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.9",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/fontkit": "^2.0.9",
     "@types/node": "^26.0.0",
     "@typescript/native-preview": "^7.0.0-dev.20260622.1",
@@ -97,14 +99,13 @@
     "canvas": "^3.2.3",
     "esbuild": "^0.28.1",
     "fontkit": "^2.0.4",
-    "mermaid": "^11.16.0",
     "peggy": "^5.0.0",
+    "semantic-release": "^25.0.8",
     "typedoc": "^0.28.20",
     "typedoc-plugin-markdown": "^4.12.0",
     "typedoc-vitepress-theme": "^1.1.3",
     "typescript": "^6.0.0",
     "vitepress": "^1.6.0",
-    "vitepress-plugin-mermaid": "^2.0.17",
     "vitest": "^4.1.9"
   },
   "volta": {

package/src/api/index.ts

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: EPL-2.0
 
 /**
- * `graphviz-ts/api` — the build + inspect + geometry entry point (ADR-2).
+ * `@knowvah/dot-engine/api` — the build + inspect + geometry entry point (ADR-2).
  *
  * Pure re-export barrel for the api layer: programmatic graph construction
  * (the builder), the safe edge helper, and the computed-geometry snapshot.
  *
  * Typical flow: call {@link createGraph} to build nodes/edges/subgraphs
  * without hand-writing DOT text, hand the builder's `.graph` (or a
- * `parse()` result) to `render()` from `graphviz-ts/render` (or the root
+ * `parse()` result) to `render()` from `@knowvah/dot-engine/render` (or the root
  * package) to lay out and emit an output format, then optionally call
  * {@link getLayout} here to read back computed node/edge/cluster geometry
  * from the laid-out graph.

package/src/common/textmeasure-factory.ts

@@ -59,7 +59,7 @@ function adviseHostFaithful(): void {
   if (process.env?.GV_FONT_QUIET || !process.stderr?.isTTY) return;
   adviceShown = true;
   process.stderr.write(
-    'graphviz-ts: measuring text with built-in metrics (kerning/shaping not applied). '
+    '@knowvah/dot-engine: measuring text with built-in metrics (kerning/shaping not applied). '
     + 'For host-faithful sizing matching the rendering font, install `canvas` and call '
     + "setTextMeasurer(new CanvasTextMeasurer(createCanvas(0,0).getContext('2d'))). "
     + 'Silence with GV_FONT_QUIET=1.\n',

package/src/errors.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EPL-2.0
 
 /**
- * Public structured-error contract for graphviz-ts.
+ * Public structured-error contract for @knowvah/dot-engine.
  *
  * Consumers branch on the stable `code` / `type` fields; the
  * `code -> friendlyMessage` map is the single seam a future i18n library

package/src/gvc/anchor.ts

@@ -392,8 +392,16 @@ export function computeNodeUrlMap(n: Node, obj: ObjState, ctx: MapCtx): void {
  * @see lib/common/emit.c:emit_page (3623-3642)
  */
 export function computeGraphUrlMap(obj: ObjState, ctx: MapCtx): void {
-  const ll = { x: ctx.bb.ll.x - ctx.pad.x, y: ctx.bb.ll.y - ctx.pad.y };
-  const ur = { x: ctx.bb.ur.x + ctx.pad.x, y: ctx.bb.ur.y + ctx.pad.y };
+  // C uses job->clip — the 0-BASED page window ([-pad, (UR-LL)+pad] in graph
+  // coords), not bb±pad. Identical when bb.LL is the origin, but engines that
+  // keep a negative bb.LL (fdp graph labels: bb "0,-24.8,...") shift the root
+  // rect: native url.gv fdp emits 0,-33,539,374 where bb±pad would give
+  // 0,0,539,407. @see lib/common/emit.c:3652 emit_map_rect(job, job->clip)
+  const ll = { x: -ctx.pad.x, y: -ctx.pad.y };
+  const ur = {
+    x: ctx.bb.ur.x - ctx.bb.ll.x + ctx.pad.x,
+    y: ctx.bb.ur.y - ctx.bb.ll.y + ctx.pad.y,
+  };
   obj.urlMapShape = MapShape.Rectangle;
   obj.urlMapPts = [mapTransform(ll, ctx), mapTransform(ur, ctx)];
 }

package/src/gvc/device.ts

@@ -50,7 +50,7 @@ import { emitRoundedBezier } from '../common/poly-shapes.js';
 import { applyClusterObjState, clusterStyle, clusterPeripheries } from './device-cluster.js';
 /** Cluster labels go through the single emit_label port. @see labels.c:emit_label */
 export function renderClusterLabel(sg: Graph, renderer: RendererPlugin, job: RenderJob): void {
-  renderOneLabel(sg.info.label as TextlabelT | undefined, renderer, job);
+  renderOneLabel(sg.info.label as TextlabelT | undefined, renderer, job, false);
 }
 import { svgNodeId, svgEdgeId, svgClusterId, svgGraphId } from '../render/svg-id.js';
 
@@ -302,8 +302,15 @@ export function renderOneLabel(
   lp: TextlabelT | undefined,
   renderer: RendererPlugin,
   job: RenderJob,
+  requireSet = true,
 ): void {
-  if (!lp?.set) return; // emit_label: lbl == NULL || !lbl->set
+  // C gates `->set` at the xlabel/edge-label CALL SITES (emit.c:1829,
+  // emit_edge_label:2891), but draws root-graph and cluster labels on
+  // existence alone (emit.c:3656, 3920) — an unplaced label (e.g. fdp's
+  // non-comparable-clusters abort skips gv_postprocess) still renders at its
+  // default pos. Callers mirroring the existence-only sites pass false.
+  if (!lp) return;
+  if (requireSet && !lp.set) return;
   // HTML branch: @see lib/common/labels.c:emit_label (226-230)
   // C routes to emit_html_label(job, lp->u.html, lp) using lp->pos as anchor.
   if (lp.html) {
@@ -346,7 +353,7 @@ export function renderNodeXLabel(n: Node, renderer: RendererPlugin, job: RenderJ
 export function renderGraphLabel(g: Graph, renderer: RendererPlugin, job: RenderJob): void {
   // @see lib/common/emit.c:emit_begin_graph / getObjId (root graph → graph0)
   setHtmlAnchorObj(svgGraphId(g, job), labelTextOf(g.info.label), job.obj ?? undefined);
-  renderOneLabel(g.info.label as TextlabelT | undefined, renderer, job);
+  renderOneLabel(g.info.label as TextlabelT | undefined, renderer, job, false);
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EPL-2.0
 
 /**
- * Public entry point for the graphviz-ts library.
+ * Public entry point for the @knowvah/dot-engine library.
  *
  * Wires together the parser, layout engines, SVG renderer, and GVC
  * orchestration layer into a single renderSvg function.
@@ -154,8 +154,8 @@ export type { BuiltinEngine, EngineName } from './gvc/context.js';
 export { render as renderWithContext } from './gvc/device.js';
 
 // Discoverable root re-exports of the api + render surfaces (ADR-2): root
-// `graphviz-ts` exposes everything from `graphviz-ts/api` and
-// `graphviz-ts/render` for one-import discoverability.
+// `@knowvah/dot-engine` exposes everything from `@knowvah/dot-engine/api` and
+// `@knowvah/dot-engine/render` for one-import discoverability.
 //
 // Collision resolution: the root `render` is the new public
 // `render(g, format, opts?)` from `./render`. The low-level

package/src/layout/neato/init.ts

@@ -9,6 +9,7 @@
  * @see lib/neatogen/neatoprocs.h
  */
 
+import type { ShapeDesc } from '../../common/types.js';
 import type { Graph } from '../../model/graph.js';
 import type { Node } from '../../model/node.js';
 import type { Edge } from '../../model/edge.js';
@@ -85,8 +86,18 @@ export function neatoInitNode(n: Node, dim = DFLT_DIM): void {
     n.info.pos = pos;
   }
   if (n.info.UF_size === undefined) n.info.UF_size = 1;
-  if (!n.info.width) n.info.width = 0.75;
-  if (!n.info.height) n.info.height = 0.5;
+  // C neato_init_node has NO size defaulting (neatoinit.c:60-66) — after
+  // common_init_node, ND_width is always written (late_double clamps a 0
+  // attr to the 0.75 default; every initfn assigns). The port's NodeInfo
+  // zero-initializes width/height (calloc mirror) and two port-only paths
+  // leave them at that unset-0 (no-measurer initNodeDefaults; poly-null
+  // custom/epsf shapes — C gives customs box geometry, a modeling gap
+  // flagged in the journal), so a fallback is still needed. The ONE case
+  // where 0 is a legitimate post-init size is shape=plain (poly_init
+  // IS_PLAIN, shapes.c:1962) — never clobber it.
+  const plainShaped = (n.info.shape as ShapeDesc | undefined)?.name === 'plain';
+  if (!n.info.width && !plainShaped) n.info.width = 0.75;
+  if (!n.info.height && !plainShaped) n.info.height = 0.5;
 }
 
 // ---------------------------------------------------------------------------

package/src/layout/twopi/init.ts

@@ -8,6 +8,7 @@
  * @see lib/twopigen/twopiinit.c
  */
 
+import type { ShapeDesc } from '../../common/types.js';
 import type { Graph } from '../../model/graph.js';
 import type { Node } from '../../model/node.js';
 import type { Edge } from '../../model/edge.js';
@@ -47,8 +48,12 @@ function makeRdata(INF: number): TwopiAlgData {
  */
 export function twopiInitNode(n: Node): void {
   if (!n.info.pos || n.info.pos.length < 2) n.info.pos = [0, 0];
-  if (!n.info.width) n.info.width = 0.75;
-  if (!n.info.height) n.info.height = 0.5;
+  // shape=plain legitimately sizes 0×0 (poly_init IS_PLAIN) — never clobber
+  // it; all other zero widths are the port's unset-0. See neatoInitNode's
+  // note for the full rationale. @see lib/neatogen/neatoinit.c:60-66
+  const plainShaped = (n.info.shape as ShapeDesc | undefined)?.name === 'plain';
+  if (!n.info.width && !plainShaped) n.info.width = 0.75;
+  if (!n.info.height && !plainShaped) n.info.height = 0.5;
 }
 
 /**

package/src/render/index.ts

@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: EPL-2.0
 
 /**
- * `graphviz-ts/render` — the output-formats + draw-ops entry point (ADR-2).
+ * `@knowvah/dot-engine/render` — the output-formats + draw-ops entry point (ADR-2).
  *
  * Pure re-export barrel for the public render surface: the multi-format
  * `render()` entry and the structured xdot draw-op access.
  *
- * Typical flow: build or `parse()` a graph (see `graphviz-ts/api`), then
+ * Typical flow: build or `parse()` a graph (see `@knowvah/dot-engine/api`), then
  * either call `render(g, format, opts?)` for a serialized output string —
  * `format` is one of {@link OutputFormat} (`'svg'`, `'dot'`, `'xdot'`,
  * `'json'`, `'plain'`, ...) — or call {@link getDrawOps} to skip string

package/src/render/map.ts

@@ -16,8 +16,11 @@ import type { Edge } from '../model/edge.js';
 import type { Point, Box } from '../model/geom.js';
 import { POINTS_PER_INCH } from '../model/geom.js';
 import type { TextSpan } from '../common/emit-types.js';
-import type { TextlabelT } from '../common/types.js';
+import { ShapeKind, type ShapeDesc, type TextlabelT } from '../common/types.js';
 import { lateDouble } from '../common/nodeinit.js';
+import { nodeAttr } from '../common/poly-init.js';
+import { htmlValueContent, isHtmlValue } from '../common/html-string.js';
+import { nodesInSeq } from '../layout/dot/decomp.js';
 import { substObjAnchor } from '../common/subst.js';
 import type { RendererPlugin } from '../gvc/context.js';
 import type { ObjState, RenderJob } from '../gvc/job.js';
@@ -58,13 +61,74 @@ export interface AnchorCtx {
 // printG5 — @see lib/common/output.c:printdouble (%.5g)
 // ---------------------------------------------------------------------------
 
-/** Format with 5 significant figures, trailing zeros stripped. */
+/** Exact decimal digits of a finite double: doubles are binary rationals, so
+ * the expansion terminates. Returns significant digits and the base-10
+ * exponent of the first digit (value = 0.d₁d₂… × 10^(exp10+1)). */
+function exactDecimalDigits(v: number): { digits: string; exp10: number } {
+  const dv = new DataView(new ArrayBuffer(8));
+  dv.setFloat64(0, Math.abs(v));
+  const bits = dv.getBigUint64(0);
+  const expBits = Number((bits >> 52n) & 0x7ffn);
+  const mant = bits & 0xfffffffffffffn;
+  const m = expBits === 0 ? mant : mant | (1n << 52n);
+  const e = (expBits === 0 ? 1 : expBits) - 1075;
+  let intDigits: string;
+  let fracLen = 0;
+  if (e >= 0) {
+    intDigits = (m << BigInt(e)).toString();
+  } else {
+    intDigits = (m * 5n ** BigInt(-e)).toString();
+    fracLen = -e;
+  }
+  if (intDigits.length <= fracLen) {
+    intDigits = '0'.repeat(fracLen - intDigits.length + 1) + intDigits;
+  }
+  const pointPos = intDigits.length - fracLen; // digits before the decimal point
+  const firstSig = intDigits.search(/[1-9]/);
+  return { digits: intDigits.slice(firstSig), exp10: pointPos - firstSig - 1 };
+}
+
+/** Format with 5 significant figures, trailing zeros stripped — C snprintf
+ * `%.5g`. JS toPrecision rounds exact decimal ties away from zero, but C
+ * (round-to-nearest-even FP mode) rounds them to even, and integer point
+ * coordinates land on exact .x5 inch ties (e.g. 78498pt/72 = 1090.25 →
+ * "1090.2", not "1090.3"). Round from the exact expansion instead.
+ * @see lib/common/output.c:printdouble */
 export function printG5(v: number): string {
-  const s = v.toPrecision(5);
-  if (s.includes('.') && !s.includes('e')) {
-    return s.replace(/\.?0+$/, '');
+  if (v === 0 || !Number.isFinite(v)) return String(v);
+  const P = 5;
+  const { digits, exp10 } = exactDecimalDigits(v);
+  let sig = digits.slice(0, P);
+  if (sig.length < P) sig += '0'.repeat(P - sig.length);
+  const rest = digits.slice(P);
+  const restNonzeroAfterFirst = /[1-9]/.test(rest.slice(1));
+  const roundUp = rest.length > 0 && (
+    rest[0]! > '5'
+    || (rest[0] === '5' && restNonzeroAfterFirst)
+    || (rest[0] === '5' && !restNonzeroAfterFirst
+        && (sig.charCodeAt(P - 1) - 0x30) % 2 === 1));
+  let exp = exp10;
+  if (roundUp) {
+    const n = String(BigInt(sig) + 1n);
+    sig = n.length > P ? (exp++, n.slice(0, P)) : n;
+  }
+  const sign = v < 0 ? '-' : '';
+  // %g style selection: exponential when exp < -4 or exp >= precision.
+  if (exp < -4 || exp >= P) {
+    const mant = (sig[0]! + '.' + sig.slice(1)).replace(/\.?0+$/, '');
+    const as = Math.abs(exp);
+    return sign + mant + 'e' + (exp < 0 ? '-' : '+') + (as < 10 ? '0' : '') + String(as);
+  }
+  let s: string;
+  if (exp >= sig.length - 1) {
+    s = sig + '0'.repeat(exp - sig.length + 1);
+  } else if (exp >= 0) {
+    s = sig.slice(0, exp + 1) + '.' + sig.slice(exp + 1);
+  } else {
+    s = '0.' + '0'.repeat(-exp - 1) + sig;
   }
-  return s;
+  if (s.includes('.')) s = s.replace(/\.?0+$/, '');
+  return sign + s;
 }
 
 /** Convert points → inches (PS2INCH = 1/72) and format as %.5g. */
@@ -72,44 +136,207 @@ export function plainCoord(v: number): string {
   return printG5(v / 72);
 }
 
+// ---------------------------------------------------------------------------
+// agstrcanon — DOT-canonical string form for plain names/labels/ports.
+// @see lib/cgraph/write.c:_agstrcanon / agstrcanon / agcanonhtmlstr
+// ---------------------------------------------------------------------------
+
+/** must agree with scan.l @see lib/cgraph/write.c:120 tokenlist */
+const CANON_KEYWORDS = ['node', 'edge', 'strict', 'graph', 'digraph', 'subgraph'];
+
+/** Line-break threshold. agwrite may override via `linelength` but always
+ * restores this value, so the plain path (direct agstrcanon, no agwrite)
+ * observes the default. @see lib/cgraph/write.c:44,676,692 */
+const MAX_OUTPUTLINE = 128;
+
+function isDigitByte(b: number): boolean { return b >= 0x30 && b <= 0x39; }
+
+function isAlnumByte(b: number): boolean {
+  return isDigitByte(b) || (b >= 0x41 && b <= 0x5a) || (b >= 0x61 && b <= 0x7a);
+}
+
+/** alphanumeric, '.', '-', or non-ascii byte. @see lib/cgraph/write.c:is_id_char */
+function isIdCharByte(b: number): boolean {
+  return isAlnumByte(b) || b === 0x2e || b === 0x2d || b >= 0x80;
+}
+
+/** Recognized escString escape starting at bytes[i]. @see lib/cgraph/write.c:is_escape */
+function isEscapeAt(bytes: Uint8Array, i: number): boolean {
+  if (bytes[i] !== 0x5c) return false;
+  const c = bytes[i + 1];
+  return c !== undefined && 'EGHLNTlnr\\"'.includes(String.fromCharCode(c));
+}
+
+/** The needs-quotes / numeral / escape state scan of `_agstrcanon`, over UTF-8
+ * BYTES (C iterates bytes: cnt counts bytes for line breaking, and non-ascii
+ * bytes are id chars). Returns the quoted buffer or the untouched input.
+ * @see lib/cgraph/write.c:_agstrcanon */
+export function agstrcanonText(arg: string): string {
+  if (arg.length === 0) return '""';
+  const bytes = new TextEncoder().encode(arg);
+  const out: number[] = [0x22];
+  let needsQuotes = false;
+  let partOfEscape = false;
+  let backslashPending = false;
+  let cnt = 0;
+  let dotcnt = 0;
+  let maybeNum = isDigitByte(bytes[0]!) || bytes[0] === 0x2e || bytes[0] === 0x2d;
+  for (let i = 0; i < bytes.length; i++) {
+    const uc = bytes[i]!;
+    if (uc === 0x22 && !partOfEscape) { // '"' not already part of an escape
+      out.push(0x5c);
+      needsQuotes = true;
+    } else if (!partOfEscape && isEscapeAt(bytes, i)) {
+      needsQuotes = true;
+      partOfEscape = true;
+    } else if (maybeNum) {
+      if (uc === 0x2d) { // '-' legal only as the first char of a numeral
+        if (cnt) { maybeNum = false; needsQuotes = true; }
+      } else if (uc === 0x2e) { // one '.' allowed
+        if (dotcnt++) { maybeNum = false; needsQuotes = true; }
+      } else if (!isDigitByte(uc)) {
+        maybeNum = false;
+        needsQuotes = true;
+      }
+      partOfEscape = false;
+    } else if (!(isAlnumByte(uc) || uc === 0x5f || uc >= 0x80)) {
+      needsQuotes = true;
+      partOfEscape = false;
+    } else {
+      partOfEscape = false;
+    }
+    out.push(uc);
+    cnt++;
+    const next = bytes[i + 1];
+    // Long-string line breaking: only after a non-id, non-backslash output
+    // char where the next input char is an id char. @see write.c:170-190
+    if (next !== undefined) {
+      const last = out[out.length - 1]!;
+      const canBreak = !(isIdCharByte(last) || last === 0x5c) && isIdCharByte(next);
+      if (backslashPending && canBreak) {
+        out.push(0x5c, 0x0a);
+        needsQuotes = true;
+        backslashPending = false;
+        cnt = 0;
+      } else if (cnt >= MAX_OUTPUTLINE) {
+        if (canBreak) {
+          out.push(0x5c, 0x0a);
+          needsQuotes = true;
+          cnt = 0;
+        } else {
+          backslashPending = true;
+        }
+      }
+    }
+  }
+  out.push(0x22);
+  const first = bytes[0]!;
+  if (needsQuotes || (cnt === 1 && (first === 0x2e || first === 0x2d))) {
+    return new TextDecoder().decode(new Uint8Array(out));
+  }
+  // Quotes protect DOT keywords (e.g. a node named "node"). @see write.c:199-203
+  const lower = arg.toLowerCase();
+  for (const tok of CANON_KEYWORDS) {
+    if (tok === lower) return new TextDecoder().decode(new Uint8Array(out));
+  }
+  return arg;
+}
+
+/** late_nnstring: default when the attr is missing OR empty.
+ * @see lib/common/utils.c:late_nnstring */
+function lateNN(v: string | undefined, def: string): string {
+  return v !== undefined && v !== '' ? v : def;
+}
+
 /** Resolve fill color: fillcolor attr, then color attr, then lightgrey. */
-export function plainNodeFill(n: Node): string {
-  const color = n.attrs.get('color') ?? 'black';
-  return n.attrs.get('fillcolor') || color || 'lightgrey';
+export function plainNodeFill(n: Node, g: Graph): string {
+  // @see lib/common/output.c:write_plain (167-169): fillcolor attr if non-empty,
+  // else the color attr, else DEFAULT_FILL ("lightgrey"). Note the fallback is
+  // DEFAULT_FILL, not DEFAULT_COLOR — an unfilled node's plain fill field is
+  // "lightgrey", not "black".
+  const fillcolor = lateNN(nodeAttr(n, g, 'fillcolor'), '');
+  if (fillcolor !== '') return fillcolor;
+  return lateNN(nodeAttr(n, g, 'color'), 'lightgrey');
 }
 
 // ---------------------------------------------------------------------------
 // Plain format helpers — @see lib/common/output.c:write_plain
 // ---------------------------------------------------------------------------
 
+/** The label field of a plain node line: HTML labels re-wrap the ORIGINAL
+ * label attr in `<...>` (agstrcanon's aghtmlstr branch on agxget(n, N_label));
+ * everything else — including record labels, whose textlabel keeps the raw
+ * unsubstituted source — canonicalizes ND_label(n)->text.
+ * @see lib/common/output.c:write_plain (152-158) */
+function plainNodeLabel(n: Node, g: Graph): string {
+  const lbl = n.info.label as TextlabelT | undefined;
+  const attr = nodeAttr(n, g, 'label');
+  if (lbl !== undefined && lbl.u.kind === 'html') {
+    const a = attr ?? '';
+    return '<' + (isHtmlValue(a) ? htmlValueContent(a) : a) + '>';
+  }
+  // An html-valued attr with a NON-html label object = the HTML parse failed:
+  // the port's fallback label is empty (matching C's drawn spans), but C's
+  // ND_label->text still holds the raw markup, which plain prints quoted.
+  // @see lib/common/labels.c:make_label (html branch gv_strdup before parse)
+  if (attr !== undefined && isHtmlValue(attr) && lbl !== undefined && lbl.u.kind === 'txt') {
+    return agstrcanonText(htmlValueContent(attr));
+  }
+  // C record textlabels keep the raw UNSUBSTITUTED label source (make_label's
+  // is_record branch gv_strdup's it; substitution happens per-field at record
+  // parse). The port's record label resolves the default to the node name, so
+  // reconstruct C's text: the label attr, or cgraph's always-present N_label
+  // default "\N". @see lib/common/labels.c:make_label ; lib/common/input.c:468
+  const shape = n.info.shape as ShapeDesc | undefined;
+  if (shape !== undefined && shape.kind === ShapeKind.SH_RECORD) {
+    return agstrcanonText(nodeAttr(n, g, 'label') ?? '\\N');
+  }
+  const text = lbl !== undefined ? lbl.text : (n.attrs.get('label') ?? n.name);
+  return agstrcanonText(text);
+}
+
 /** Read the five style attrs needed for a plain node line. */
-export function plainNodeAttrs(n: Node): PlainNodeAttrs {
+export function plainNodeAttrs(n: Node, g: Graph): PlainNodeAttrs {
+  // style/shape/color resolve through the node-defaults chain (C agxget sees
+  // `node [...]` defaults). C prints ND_shape(n)->name, which bind_shape
+  // derives purely from attrs: a non-epsf shapefile forces "custom", unknown
+  // names keep the user's name (user_shape), default is "ellipse" — so the
+  // port's resolved-fallback ShapeDesc name must NOT be used here.
+  // @see lib/common/output.c:write_plain (163-166)
+  // @see lib/common/shapes.c:bind_shape / user_shape
+  const shapeAttr = lateNN(nodeAttr(n, g, 'shape'), 'ellipse');
+  const shapefile = nodeAttr(n, g, 'shapefile');
+  const shapeName =
+    shapefile !== undefined && shapefile !== '' && shapeAttr !== 'epsf' ? 'custom' : shapeAttr;
   return {
-    label: n.attrs.get('label') ?? n.name,
-    style: n.attrs.get('style') ?? 'solid',
-    shape: n.attrs.get('shape') ?? 'ellipse',
-    color: n.attrs.get('color') ?? 'black',
-    fill: plainNodeFill(n),
+    label: plainNodeLabel(n, g),
+    style: lateNN(nodeAttr(n, g, 'style'), 'solid'),
+    shape: shapeName,
+    color: lateNN(nodeAttr(n, g, 'color'), 'black'),
+    fill: plainNodeFill(n, g),
   };
 }
 
 /** Write one node line: `node name x y w h label style shape color fill\n` */
-export function writePlainNode(n: Node, out: string[]): void {
+export function writePlainNode(n: Node, g: Graph, out: string[]): void {
   const x = plainCoord(n.info.coord.x);
   const y = plainCoord(n.info.coord.y);
   const w = printG5(n.info.width);
   const h = printG5(n.info.height);
-  const a = plainNodeAttrs(n);
-  out.push('node ' + n.name + ' ' + x + ' ' + y + ' ' + w + ' ' + h
+  const a = plainNodeAttrs(n, g);
+  out.push('node ' + agstrcanonText(n.name) + ' ' + x + ' ' + y + ' ' + w + ' ' + h
     + ' ' + a.label + ' ' + a.style + ' ' + a.shape + ' ' + a.color + ' ' + a.fill + '\n');
 }
 
-/** Flatten all Bezier curves in an edge spline into a point array. */
+/** Flatten all Bezier curves in an edge spline into a point array. Reads
+ * exactly bz.size points — routing can leave over-allocated scratch entries
+ * past size in bz.list (C sums ED_spl sizes, never the allocation).
+ * @see lib/common/output.c:write_plain (183-195) */
 export function collectSplinePts(e: Edge): Point[] {
   if (!e.info.spl) return [];
   const pts: Point[] = [];
   for (const bz of e.info.spl.list) {
-    for (const pt of bz.list) pts.push(pt);
+    for (let i = 0; i < bz.size; i++) pts.push(bz.list[i]!);
   }
   return pts;
 }
@@ -119,39 +346,75 @@ export function portSuffix(name: string | null): string {
   return name ? ':' + name : '';
 }
 
+/** Write ` name[:port]`, both parts DOT-canonicalized. A cluster proxy node's
+ * synthetic `__i:<cluster>` id is written as the cluster name it stands for
+ * (C: strchr(agnameof(node), ':') + 1).
+ * @see lib/common/output.c:writenodeandport */
+function writeNodeAndPort(n: Node, portname: string, out: string[]): void {
+  let name = n.name;
+  if (n.info.clustnode) {
+    const i = name.indexOf(':');
+    if (i >= 0) name = name.slice(i + 1);
+  }
+  out.push(' ' + agstrcanonText(name));
+  if (portname !== '') out.push(':' + agstrcanonText(portname));
+}
+
 /** Write the `edge tail head n pt...` prefix when spline data exists. */
 export function writePlainEdgeHead(
   e: Edge, tport: string, hport: string, pts: Point[], out: string[],
 ): void {
-  out.push('edge ' + e.tail.name + tport + ' ' + e.head.name + hport
-    + ' ' + String(pts.length));
+  out.push('edge');
+  writeNodeAndPort(e.tail, tport, out);
+  writeNodeAndPort(e.head, hport, out);
+  out.push(' ' + String(pts.length));
   for (const pt of pts) {
     out.push(' ' + plainCoord(pt.x) + ' ' + plainCoord(pt.y));
   }
 }
 
-/** Write one edge — spline prefix if available, always appends `style color\n`. */
+/** Write one edge — spline prefix if available, then the edge label (when
+ * present), always appends `style color\n`. plain-ext ports come from the
+ * tailport/headport ATTRS (C agget), which keep any `:compass` suffix the
+ * resolved port objects have already split off.
+ * @see lib/common/output.c:write_plain (200-208) */
 export function writePlainEdge(e: Edge, extend: boolean, out: string[]): void {
-  const tport = extend ? portSuffix(e.info.tail_port.name) : '';
-  const hport = extend ? portSuffix(e.info.head_port.name) : '';
+  const tport = extend ? (e.attrs.get('tailport') ?? '') : '';
+  const hport = extend ? (e.attrs.get('headport') ?? '') : '';
   const pts = collectSplinePts(e);
   if (pts.length > 0) writePlainEdgeHead(e, tport, hport, pts, out);
-  const style = e.attrs.get('style') ?? 'solid';
-  const color = e.attrs.get('color') ?? 'black';
+  // Edge label: canon(text) then position, mirroring `if (ED_label(e)) {
+  // printstring(canon(...)); printpoint(pos) }`.
+  const lbl = e.info.label;
+  if (lbl !== undefined) {
+    out.push(' ' + agstrcanonText(lbl.text)
+      + ' ' + plainCoord(lbl.pos.x) + ' ' + plainCoord(lbl.pos.y));
+  }
+  const style = lateNN(e.attrs.get('style'), 'solid');
+  const color = lateNN(e.attrs.get('color'), 'black');
   out.push(' ' + style + ' ' + color + '\n');
 }
 
-/** Write the full plain output: graph header, nodes, edges, stop. */
+/** Write the full plain output: graph header, nodes, edges, stop.
+ * Node iteration is agfstnode/agnxtnode (AGSEQ) order, not insertion-Map
+ * order; the graph line's scale is job->zoom — the size= fit factor, computed
+ * with the dot renderer's pad of 0 (render_features_dot).
+ * @see lib/common/output.c:write_plain
+ * @see plugin/core/gvrender_core_dot.c:render_features_dot */
 export function writePlain(g: Graph, job: RenderJob, extend: boolean): void {
   const w = plainCoord(g.info.bb.ur.x);
   const h = plainCoord(g.info.bb.ur.y);
-  job.write('graph ' + printG5(job.zoom) + ' ' + w + ' ' + h + '\n');
-  for (const [, n] of g.nodes) {
+  const zoom = initJobViewportZoom(
+    job.bb, parseDrawingSize(g.attrs.get('size')), { x: 0, y: 0 });
+  job.write('graph ' + printG5(zoom) + ' ' + w + ' ' + h + '\n');
+  const nodes = nodesInSeq(g);
+  for (const n of nodes) {
+    if (n.info.clustnode) continue; // IS_CLUST_NODE — cluster proxies get no node line
     const buf: string[] = [];
-    writePlainNode(n, buf);
+    writePlainNode(n, g, buf);
     job.write(buf.join(''));
   }
-  for (const [, n] of g.nodes) {
+  for (const n of nodes) {
     for (const e of n.outEdges(g)) {
       const buf: string[] = [];
       writePlainEdge(e, extend, buf);

package/src/render/public.ts

@@ -53,7 +53,7 @@ export interface RenderOptions {
    * `false` — unset reproduces the pre-AD-1 raw `xlink:href="src"`
    * passthrough byte-for-byte. When `true`, the SVG emitter consults the
    * process-global resolver registered via `setImageResolver` (from
-   * `graphviz-ts`) for each `image=`/HTML `<IMG>` source; a hit is inlined
+   * `@knowvah/dot-engine`) for each `image=`/HTML `<IMG>` source; a hit is inlined
    * as `data:<mime>;base64,<...>`, a miss (or no resolver registered) falls
    * back to the raw src passthrough. Has no effect on non-SVG formats.
    */