@knowvah/dot-engine 0.1.0

package/src/render/svg.ts

@@ -0,0 +1,307 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * SVG renderer plugin.
+ *
+ * Faithful TypeScript port of plugin/core/gvrender_core_svg.c.
+ * Implements RendererPlugin to produce SVG 1.1 output.
+ *
+ * Y-coordinate investigation: The C svg_bzptarray and all shape emitters
+ * negate Y with -A[i].y because they receive raw PostScript (Y-up)
+ * coordinates and must convert to SVG (Y-down). In this TypeScript port
+ * the Y-flip is applied upstream via transformPoint with devscale.y = -1
+ * (src/gvc/device.ts). Coordinates received in all renderer callbacks are
+ * therefore already in SVG Y-down space; no additional negation is needed.
+ *
+ * @see plugin/core/gvrender_core_svg.c
+ */
+
+import type { Graph } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import type { Edge } from '../model/edge.js';
+import type { Point, Box } from '../model/geom.js';
+import { boxOverlap } from '../model/geom.js';
+import type { TextlabelT } from '../common/types.js';
+import type { TextSpan } from '../common/emit-types.js';
+import type { RendererPlugin, LabelType } from '../gvc/context.js';
+import type { RenderJob } from '../gvc/job.js';
+import { renderEdgeLabels } from '../gvc/edge-labels.js';
+import { beginAnchorIf } from '../gvc/anchor.js';
+import {
+  svgBeginGraph,
+  svgEndGraph,
+  svgBeginPage,
+  svgPageBackground,
+  svgEndPage,
+  svgBeginLayer,
+  svgEndLayer,
+  svgBeginNode,
+  svgEndNode,
+  svgBeginEdge,
+  svgEndEdge,
+  svgBeginAnchor,
+  svgEndAnchor,
+  svgTextspan,
+  svgEllipse,
+  svgPolygon,
+  svgBezier,
+  svgPolyline,
+  svgComment,
+  svgEdgePath,
+  svgEdgePathOrthoRounded,
+  orthoRoundedRadius,
+  svgArrowPolygons,
+  emitParallelEdgePaths,
+  escapeXml,
+  emitPoints,
+} from './svg-helpers.js';
+import { emitArrowOps } from './svg-arrow-ops.js';
+import { resolveRenderColor, colorOpacity, colorPaint } from './color-resolve.js';
+import { svgBeginCluster, svgEndCluster } from './svg-cluster.js';
+import { emitSplitEdgePaths } from './svg-edge-split.js';
+import { edgeIsTapered, svgTaperedEdge } from './svg-tapered-edge.js';
+import { findImageBytes, toDataUri } from '../gvc/image-resolver.js';
+
+// ---------------------------------------------------------------------------
+// Multicolor arrow helpers
+// @see lib/common/emit.c:2508-2528 (tail/head arrow with headcolor/tailcolor)
+// ---------------------------------------------------------------------------
+
+/** Emit tail arrow with tailColor and head arrow with headColor (multicolor). */
+function emitMulticolorArrows(e: Edge, job: RenderJob, headColor: string, tailColor: string): void {
+  const obj = job.obj;
+  const pw = obj !== null ? obj.penWidth : 1.0;
+  const tailOps = e.info.tailArrowOps;
+  if (tailOps?.length) {
+    emitArrowOps(tailOps, tailColor, job, pw, colorOpacity(resolveRenderColor(tailColor)));
+  }
+  const headOps = e.info.headArrowOps;
+  if (headOps?.length) {
+    emitArrowOps(headOps, headColor, job, pw, colorOpacity(resolveRenderColor(headColor)));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// SvgRenderer — delegates all work to module-level helpers in svg-helpers.ts
+// @see plugin/core/gvrender_core_svg.c:svg_engine
+// ---------------------------------------------------------------------------
+
+/** overlap_label: does the label's box (pos ± dimen/2) overlap clip box b?
+ * @see lib/common/utils.c:overlap_label */
+function overlapLabel(lp: TextlabelT, b: Box): boolean {
+  const sx = lp.dimen.x / 2;
+  const sy = lp.dimen.y / 2;
+  const bb: Box = {
+    ll: { x: lp.pos.x - sx, y: lp.pos.y - sy },
+    ur: { x: lp.pos.x + sx, y: lp.pos.y + sy },
+  };
+  return boxOverlap(b, bb);
+}
+
+/**
+ * Faithful-to-outcome `edge_in_box`: true when the edge has something to draw.
+ * C's gvrender defers the `<g>` until a draw op, so an edge whose content falls
+ * entirely outside the clip emits no group (emit.c:edge_in_box tests each piece
+ * vs job->clip via boxf_overlap/overlap_label).
+ *
+ * The only piece that can legitimately fall OUTSIDE the clip on this corpus is a
+ * degenerate labeled-flat label: it is spline-less, so map_edge leaves it at its
+ * internal (un-normalized) x-frame position while the clip is the final frame.
+ * The `overlapLabel` test on the main label reproduces C's draw-iff-overlap for
+ * exactly that case — on-canvas (2368) → drawn; off-canvas (2368_1, negative
+ * un-normalized x) → suppressed. A present spline always lies within the clip
+ * (GD_bb contains it), and head/tail/xlabels are positioned at on-canvas
+ * endpoints, so those keep their existing unconditional triggers — adding an
+ * overlap test there only risks suppressing legitimately-drawn content (it
+ * regressed neato/circo edges whose spl.bb is computed differently). The `set`
+ * guard on the main label is kept: the port retains an unplaced (`pos=0,0`,
+ * `set=false`) label on merged back-edges where C has none.
+ * @see lib/common/emit.c:edge_in_box, lib/common/utils.c:overlap_label
+ */
+export function edgeHasDrawableContent(e: Edge, clip: Box): boolean {
+  const i = e.info;
+  return i.spl !== undefined
+    || (i.label !== undefined && i.label.set && overlapLabel(i.label, clip))
+    || i.xlabel !== undefined
+    || i.head_label !== undefined || i.tail_label !== undefined;
+}
+
+export class SvgRenderer implements RendererPlugin {
+  readonly type = 'svg';
+  /** @see plugin/core/gvplugin_core.c registration table */
+  readonly quality = 0;
+  /** Whether the current edge's <g> group was opened (deferred-emit state). */
+  private edgeGroupOpen = false;
+
+  beginGraph(g: Graph, job: RenderJob): void { svgBeginGraph(g, job); }
+  endGraph(_g: Graph, job: RenderJob): void { svgEndGraph(job); }
+  beginPage(g: Graph, job: RenderJob): void { svgBeginPage(g, job); }
+
+  pageBackground(g: Graph, job: RenderJob): void { svgPageBackground(g, job); }
+  endPage(_g: Graph, job: RenderJob): void { svgEndPage(job); }
+  beginLayer(name: string, job: RenderJob): void { svgBeginLayer(name, job); }
+  endLayer(job: RenderJob): void { svgEndLayer(job); }
+  beginNode(n: Node, job: RenderJob): void { svgBeginNode(n, job); }
+  endNode(_n: Node, job: RenderJob): void { svgEndNode(job); }
+  beginEdge(e: Edge, job: RenderJob): void {
+    // job.bb is the final drawing bbox (= GD_bb / job->clip); emit_edge gates
+    // all edge drawing on edge_in_box(e, job->clip). @see lib/common/emit.c:emit_edge
+    this.edgeGroupOpen = edgeHasDrawableContent(e, job.bb);
+    if (this.edgeGroupOpen) svgBeginEdge(e, job);
+  }
+
+  /**
+   * Close the edge group.  Edge graphics (path + arrowhead) are emitted here
+   * because the full spline is available on e.info.spl only after layout has
+   * run routeDotEdges.
+   *
+   * For multi-color edges (color="c1:c2:…"), emits parallel offset Béziers
+   * (one per color, SEP=2.0 apart) then arrows in headcolor/tailcolor.
+   * Single-color edges use the T4 path unchanged.
+   *
+   * @see plugin/core/gvrender_core_svg.c:svg_end_edge
+   * @see lib/common/emit.c:2442-2528 (else if numc parallel-bezier branch)
+   */
+  endEdge(e: Edge, job: RenderJob): void {
+    // No <g> opened (no spline/label) → nothing to draw or close, matching C's
+    // deferred group emission for content-less edges.
+    if (!this.edgeGroupOpen) return;
+    this.edgeGroupOpen = false;
+    // Whole-edge anchor wraps the spline + arrows only; it closes before the
+    // labels, which carry their own sub-anchors (siblings, not nested).
+    // @see lib/common/emit.c:2877 (begin) / emit_end_edge:2970 (end)
+    const anchored = beginAnchorIf(this, job);
+    const colorAttr = e.attrs.get('color') ?? '';
+    const numc = (colorAttr.match(/:/g) ?? []).length;
+    const numsemi = (colorAttr.match(/;/g) ?? []).length;
+    if (numsemi > 0 && numc > 0) {
+      // Split-along-length branch (semicolon syntax).
+      // Arrow rule is inverted: tail = first color, head = endcolor.
+      // @see lib/common/emit.c:2390 if (numsemi && numc) multicolor()
+      const { firstColor, endColor } = emitSplitEdgePaths(e, job, colorAttr);
+      emitMulticolorArrows(e, job, endColor, firstColor);
+    } else if (edgeIsTapered(e)) {
+      // Tapered edge: a filled taper polygon + arrows. Takes precedence over
+      // colon-multicolor, matching C's `if (tapered) ... else if (numc)`.
+      // @see lib/common/emit.c:2422
+      svgTaperedEdge(e, job);
+    } else if (numc > 0) {
+      // Multicolor parallel-bezier branch
+      // @see lib/common/emit.c:2443 else if (numc)
+      const { headColor, tailColor } = emitParallelEdgePaths(e, job, colorAttr);
+      emitMulticolorArrows(e, job, headColor, tailColor);
+    } else {
+      // Single-color branch. Ortho edges with rounded corners (splines=ortho +
+      // radius/style=rounded) emit polyline segments + corner arcs; all other
+      // edges keep the byte-stable bezier <path>. @see lib/common/emit.c:2553
+      const orthoRadius = orthoRoundedRadius(e, job);
+      // svgEdgePath interleaves each bezier's arrowheads per C's emit loop;
+      // the rounded-ortho variant keeps the trailing arrow pass (its arrows
+      // always sit on the single ortho bezier). @see lib/common/emit.c:2668
+      if (orthoRadius !== null) {
+        svgEdgePathOrthoRounded(e, orthoRadius, job);
+        svgArrowPolygons(e, job);
+      } else {
+        svgEdgePath(e, job);
+      }
+    }
+    if (anchored) this.endAnchor(job);
+    // Edge labels go inside the group, after path + arrows.
+    // @see lib/common/emit.c:emit_end_edge (3010-3025)
+    renderEdgeLabels(e, this, job);
+    svgEndEdge(job);
+  }
+
+  beginAnchor(
+    href: string,
+    tooltip: string,
+    target: string,
+    id: string,
+    job: RenderJob,
+  ): void {
+    svgBeginAnchor(href, tooltip, target, id, job);
+  }
+
+  endAnchor(job: RenderJob): void { svgEndAnchor(job); }
+
+  textspan(pos: Point, span: TextSpan, job: RenderJob): void {
+    svgTextspan(pos, span, job);
+  }
+
+  ellipse(
+    center: Point,
+    rx: number,
+    ry: number,
+    filled: boolean,
+    job: RenderJob,
+  ): void {
+    svgEllipse(center, rx, ry, filled, job);
+  }
+
+  polygon(pts: Point[], filled: boolean, job: RenderJob): void {
+    svgPolygon(pts, filled, job);
+  }
+
+  bezier(pts: Point[], filled: boolean, job: RenderJob): void {
+    svgBezier(pts, filled, job);
+  }
+
+  polyline(pts: Point[], job: RenderJob): void { svgPolyline(pts, job); }
+  // C resets to the default line style and the label's fontcolor before the
+  // attachment polyline (emit.c:1886-1893) — the edge's own dash/width must
+  // not leak onto it.
+  attachmentPolyline(pts: Point[], pencolor: string, job: RenderJob): void {
+    // Resolve the label fontcolor through the SVG known-color gate before
+    // emission, mirroring C's gvrender_set_pencolor in emit_attachment; a raw
+    // attribute value must never reach stroke="..." unresolved/unescaped.
+    job.write('<polyline fill="none" stroke="' + colorPaint(resolveRenderColor(pencolor)) + '" points="');
+    emitPoints(job, pts);
+    job.write('"/>\n');
+  }
+
+  /**
+   * Emit an <image> element. C formats numbers with %g here (not the
+   * svg_printdouble used elsewhere); toPrecision(6) reproduces %g.
+   * Deviation: C writes us->name raw (gvputs); the port XML-escapes the
+   * src so metacharacter paths cannot produce invalid SVG.
+   *
+   * AD-1 (image-api, additive): when job.inlineImages is set AND the
+   * registered image resolver (`setImageResolver`) resolves `src`, emit a
+   * self-contained `data:` URI instead of the raw src passthrough. This is
+   * not a C behavior — native Graphviz never inlines image bytes. Default
+   * off (job.inlineImages unset/false, or no resolver registered, or the
+   * resolver misses) reproduces the byte-identical pre-AD-1 output below.
+   * @see plugin/core/gvloadimage_core.c:core_loadimage_svg
+   * @see src/gvc/image-resolver.ts
+   */
+  usershape(src: string, b: Box, job: RenderJob): void {
+    const g = (n: number): string => String(parseFloat(n.toPrecision(6)));
+    const width = b.ur.x - b.ll.x;
+    const height = b.ur.y - b.ll.y;
+    const originx = (b.ur.x + b.ll.x - width) / 2;
+    const originy = (b.ur.y + b.ll.y + height) / 2;
+    let href = src;
+    if (job.inlineImages === true) {
+      const found = findImageBytes(src);
+      if (found !== null) href = toDataUri(found.bytes, found.mime);
+    }
+    job.write('<image xlink:href="' + escapeXml(href) + '" width="' + g(width)
+      + 'px" height="' + g(height) + 'px" preserveAspectRatio="xMinYMin meet" x="'
+      + g(originx) + '" y="' + g(-originy) + '"/>\n');
+  }
+
+  comment(text: string, job: RenderJob): void { svgComment(text, job); }
+
+  beginLabel(_type: LabelType, _job: RenderJob): void { /* no-op */ }
+  endLabel(_job: RenderJob): void { /* no-op */ }
+  beginCluster(sg: Graph, job: RenderJob): void { svgBeginCluster(sg, job); }
+  endCluster(_sg: Graph, job: RenderJob): void { svgEndCluster(job); }
+}
+
+// ---------------------------------------------------------------------------
+// Factory — @see plugin/core/gvrender_core_svg.c:gvrender_svg_types
+// ---------------------------------------------------------------------------
+
+export function createSvgRenderer(): RendererPlugin {
+  return new SvgRenderer();
+}

package/src/render/xdot-public.ts

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Public API for structured xdot draw-op access.
+ *
+ * Lays out a Graph, renders it to the xdot format, parses the xdot
+ * attribute strings back into typed XdotOp values, and returns a flat
+ * op stream the caller can feed to any drawing backend (canvas, WebGL,
+ * PDF, native UI) without touching SVG.
+ *
+ * This wrapper is a thin, faithful exposure of whatever the xdot renderer
+ * emits — it adds no draw ops of its own.
+ *
+ * KNOWN LIMITATION (xdot renderer, not this wrapper): the underlying xdot
+ * renderer (`createXdotRenderer` in `render/dot.ts`) is currently
+ * integration-incomplete relative to native `dot -Txdot`:
+ *   - edges emit no `_draw_` ops (no spline/arrowhead draw ops surface here);
+ *   - custom node pen/fill colors are not applied to the emitted ops;
+ *   - node draw-op coordinates can be mismatched between nodes.
+ * Node shape ops (ellipse/polygon), text/label ops, and font ops are
+ * emitted and surface correctly. The geometry itself is fully computed
+ * (the SVG renderer draws the same graph correctly); only the xdot
+ * emission path is incomplete. A faithful fix is tracked as a follow-on
+ * mission (see plans/expose-library-api/decision-journal.md, 2026-06-21).
+ *
+ * @see lib/xdot/xdot.h
+ * @see plugin/core/gvrender_core_dot.c (FORMAT_XDOT)
+ */
+
+import type { XdotOp } from '../xdot/types.js';
+import { Graph } from '../model/graph.js';
+import { parse } from '../parser/index.js';
+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';
+
+/**
+ * `Xdot` — the parsed result of one xdot attribute stream: `ops` (the
+ * decoded draw-op array) plus `flags` (parse status bits).
+ *
+ * `XdotOp` — a single decoded xdot drawing operation, discriminated by its
+ * `kind` field (e.g. `filled_ellipse`, `filled_polygon`, `filled_bezier`,
+ * `polyline`, `text`, `fill_color`, `pen_color`, `grad_fill_color`,
+ * `grad_pen_color`, `font`, `style`, `image`, `fontchar`). Each variant
+ * carries one payload property named for its shape (`ellipse`, `polygon`,
+ * `bezier`, `polyline`, `text`, `color`, `gradColor`, `font`, `style`,
+ * `image`, `fontchar`) — narrow on `kind` in a switch to access it safely.
+ *
+ * `XdotColor` — a resolved xdot fill/pen color: `{ type: 'none', clr }` for
+ * a solid color, or a linear/radial gradient (`{ type: 'linear', ling }` /
+ * `{ type: 'radial', ring }`).
+ *
+ * @see lib/xdot/xdot.h:xdot
+ * @see lib/xdot/xdot.h:xdot_op (`_xdot_op`)
+ * @see lib/xdot/xdot.h:xdot_color
+ */
+export type { Xdot, XdotOp, XdotColor } from '../xdot/index.js';
+
+/** Options for {@link getDrawOps}. */
+export interface DrawOpsOptions {
+  /** Layout engine to use. Defaults to `'dot'`. */
+  engine?: EngineName;
+}
+
+/** Default layout engine used by {@link getDrawOps}. */
+export const DEFAULT_DRAW_ENGINE: EngineName = 'dot';
+
+/**
+ * xdot attribute keys that carry draw-op streams.
+ * @see plugin/core/gvrender_core_dot.c xdot_obj_attr_names
+ */
+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');
+}
+
+/** Append XdotOps found in `attrs` for each xdot draw key into `out`. */
+function appendAttrsOps(attrs: Map<string, string>, out: XdotOp[]): void {
+  for (const key of XDOT_DRAW_ATTRS) {
+    const val = attrs.get(key);
+    if (val === undefined) continue;
+    const parsed = parseXDot(val);
+    if (parsed !== null) out.push(...parsed.ops);
+  }
+}
+
+function collectGraphOps(xdotGraph: Graph): XdotOp[] {
+  const ops: XdotOp[] = [];
+  appendAttrsOps(xdotGraph.attrs, ops);
+  for (const n of xdotGraph.nodes.values()) appendAttrsOps(n.attrs, ops);
+  for (const e of xdotGraph.edges) appendAttrsOps(e.attrs, ops);
+  return ops;
+}
+
+function layoutAndRenderXdot(g: Graph, engine: EngineName): string {
+  const ctx = createDefaultContext();
+  try {
+    ctx.layout(g, engine);
+    const src = gvcRender(ctx, g, 'xdot');
+    ctx.freeLayout(g, engine);
+    return src;
+  } catch (err: unknown) {
+    rethrowAsRender(err);
+  }
+}
+
+/**
+ * Lay out `g`, render to xdot, parse every draw-attribute stream, and
+ * return all ops as a flat `XdotOp[]` in paint order (graph → node → edge).
+ *
+ * Consumers discriminate on the `kind` field of the `XdotOp` union —
+ * no string parsing required.
+ *
+ * @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.
+ *
+ * @example
+ * ```ts
+ * import { parse } from '@knowvah/dot-engine';
+ * import { getDrawOps } from 'graphviz-ts/render';
+ *
+ * const g = parse('digraph { a -> b; }');
+ * for (const op of getDrawOps(g)) {
+ *   switch (op.kind) {
+ *     case 'filled_ellipse':
+ *     case 'unfilled_ellipse':
+ *       drawEllipse(op.ellipse);
+ *       break;
+ *     case 'text':
+ *       drawText(op.text);
+ *       break;
+ *     // ...handle the remaining XdotOp kinds
+ *   }
+ * }
+ * ```
+ *
+ * @see lib/xdot/xdot.h
+ * @see lib/gvc/gvc.h:gvRender
+ */
+export function getDrawOps(g: Graph, opts?: DrawOpsOptions): XdotOp[] {
+  const engine = opts?.engine ?? DEFAULT_DRAW_ENGINE;
+  return collectGraphOps(parse(layoutAndRenderXdot(g, engine)));
+}

package/src/render/xml-escape.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: EPL-2.0
+//
+// XML escaping faithful to graphviz's gv_xml_escape (lib/util/xml.c). '<', '>',
+// '"', and "'" are always escaped; '&' is escaped to &amp; only when it does
+// not begin a valid entity (&name; / &#NNN; / &#xHH;). The text/tooltip variant
+// additionally honors the {raw, dash, nbsp} flags used by the SVG plugin.
+
+// Regexes for quote chars: /"/g and /'/g break Lizard's quote-tracker.
+// Use these named patterns instead to avoid the parser bug.
+const RE_DQUOTE = new RegExp('"', 'g');
+const RE_SQUOTE = new RegExp("'", 'g');
+// A bare '&' that does NOT begin a valid entity (&name; / &#NNN; / &#xHH;).
+// Mirrors xml_isentity (lib/util/xml.c): only such '&' are escaped to &amp;.
+const RE_AMP_NONENTITY = /&(?![A-Za-z]+;|#[0-9]+;|#x[0-9A-Fa-f]+;)/g;
+
+/**
+ * Base XML escape (gv_xml_escape with flags {0}): ids, titles, hrefs.
+ * @see lib/util/xml.c gv_xml_escape / xml_core / xml_isentity
+ */
+export function escapeXml(s: string): string {
+  let r = s.replace(RE_AMP_NONENTITY, '&amp;');
+  r = r.replace(/</g, '&lt;');
+  r = r.replace(/>/g, '&gt;');
+  r = r.replace(RE_DQUOTE, '&quot;');
+  r = r.replace(RE_SQUOTE, '&#39;');
+  return r;
+}
+
+/**
+ * Title/id/class XML escape (gv_xml_escape with flags {dash, nbsp} — C's
+ * gvputs_xml): base escaping plus '-'→&#45; and 2nd+ consecutive
+ * spaces→&#160;, WITHOUT the raw flag (entity-aware '&', no \n/\r
+ * escapes). Used for <title> content and id/class attribute values.
+ * @see lib/gvc/gvdevice.c:gvputs_xml, lib/util/xml.c:xml_core
+ */
+export function escapeXmlTitle(s: string): string {
+  let r = escapeXml(s);
+  r = r.replace(/-/g, '&#45;');
+  r = r.replace(/ {2,}/g, (m) => ' ' + '&#160;'.repeat(m.length - 1));
+  return r;
+}
+
+/**
+ * Text/tooltip XML escape (gv_xml_escape with flags {raw, dash, nbsp}):
+ * additionally escapes '-'→&#45;, newline/CR→&#10;/&#13;, and 2nd+ consecutive
+ * spaces→&#160;. Used for textspans and tooltips.
+ * @see plugin/core/gvrender_core_svg.c:546 (svg_textspan flags)
+ */
+export function escapeXmlText(s: string): string {
+  let r = escapeXml(s);
+  r = r.replace(/-/g, '&#45;');
+  r = r.replace(/\n/g, '&#10;');
+  r = r.replace(/\r/g, '&#13;');
+  r = r.replace(/ {2,}/g, (m) => ' ' + '&#160;'.repeat(m.length - 1));
+  return r;
+}

package/src/util/agxbuf.ts

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * @see lib/util/agxbuf.h
+ * @see lib/util/agxbuf.c (agxbuf_trim_zeros)
+ *
+ * Dynamically expanding string buffer. SSO threshold need not be
+ * replicated — only the observable contract matters.
+ */
+
+/**
+ * Extensible string buffer, analogous to C's agxbuf.
+ *
+ * @see cgraph/agxbuf.h:agxbuf
+ */
+export class AgBuffer {
+  private _data: string = "";
+
+  /** @see cgraph/agxbuf.h:agxbput */
+  append(s: string): this {
+    this._data += s;
+    return this;
+  }
+
+  /** @see cgraph/agxbuf.h:agxbputc */
+  appendChar(c: string): this {
+    this._data += c[0] ?? "";
+    return this;
+  }
+
+  /**
+   * Append first n characters of s.
+   * @see cgraph/agxbuf.h:agxbput_n
+   */
+  appendN(s: string, n: number): this {
+    this._data += s.slice(0, n);
+    return this;
+  }
+
+  /** @see cgraph/agxbuf.h:agxbclear */
+  clear(): void {
+    this._data = "";
+  }
+
+  /**
+   * Matches agxbuse semantics: resets the buffer and returns the content.
+   * The returned string is valid only until the next write.
+   * @see cgraph/agxbuf.h:agxbuse
+   */
+  str(): string {
+    const result = this._data;
+    this._data = "";
+    return result;
+  }
+
+  /**
+   * Caller takes ownership; buffer is reset.
+   * @see cgraph/agxbuf.h:agxbdisown
+   */
+  disown(): string {
+    return this.str();
+  }
+
+  /** @see cgraph/agxbuf.h:agxblen */
+  length(): number {
+    return this._data.length;
+  }
+
+  /**
+   * Removes and returns the last character (UTF-16 charCodeAt semantics
+   * matching C char-pop), or null if empty.
+   * @see cgraph/agxbuf.h:agxbpop
+   */
+  pop(): string | null {
+    if (this._data.length === 0) {
+      return null;
+    }
+    const c = this._data[this._data.length - 1];
+    this._data = this._data.slice(0, -1);
+    return c;
+  }
+
+  /**
+   * Trim trailing fractional zeros from a printed floating-point value.
+   *
+   * Examples:
+   *   "42.00" → "42"
+   *   "42.01" → "42.01"
+   *   "42.10" → "42.1"
+   *   "-0.0"  → "0"
+   *
+   * @see cgraph/agxbuf.h:agxbuf_trim_zeros
+   */
+  trimZeros(): void {
+    const period = this._lastPeriodIndex();
+    if (period < 0) return;
+    const trimmed = this._trimFractional(period);
+    if (trimmed !== null) this._data = trimmed;
+  }
+
+  /** Return index of last '.' in _data, or -1 if none. */
+  private _lastPeriodIndex(): number {
+    for (let i = this._data.length - 1; i >= 0; i--) {
+      if (this._data[i] === ".") return i;
+    }
+    return -1;
+  }
+
+  /**
+   * Walk backwards from end; trim trailing '0' digits then the '.' if all
+   * fractional digits were zero. Returns the trimmed string, or null when
+   * no trimming is needed.
+   * @see cgraph/agxbuf.h:agxbuf_trim_zeros (truncate loop)
+   */
+  private _trimFractional(period: number): string | null {
+    const s = this._data;
+    let end = s.length;
+    while (end > period + 1 && s[end - 1] === "0") {
+      end--;
+    }
+    if (end === s.length) return null; // no trailing zeros
+    if (end === period + 1) {
+      return AgBuffer._fixNegativeZero(s.slice(0, period));
+    }
+    return s.slice(0, end);
+  }
+
+  /**
+   * Replace trailing "-0" with "0".
+   * @see cgraph/agxbuf.h:agxbuf_trim_zeros (-0 fix)
+   */
+  private static _fixNegativeZero(s: string): string {
+    const n = s.length;
+    if (n >= 2 && s[n - 2] === "-" && s[n - 1] === "0") {
+      return s.slice(0, n - 2) + "0";
+    }
+    return s;
+  }
+}