@knowvah/dot-engine 1.8.1 → 2.0.0

package/src/async/render-async.ts

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Async render entry points (async-api ADR-1, 3, 4, 5, 7).
+ *
+ * Parse, collect the fonts and images the graph will request, await them,
+ * then run the unchanged synchronous `layout → render → freeLayout` on a fresh
+ * per-call context whose image hooks are sync closures over per-call Maps.
+ *
+ * @see src/render/public.ts:render
+ * @see src/index.ts:renderSvg
+ */
+
+import type { Graph } from '../model/graph.js';
+import { parse } from '../parser/index.js';
+import { invalidArgType, rethrowAtBoundary } from '../errors.js';
+import type { EngineName } from '../gvc/context.js';
+import { createDefaultContext } from '../gvc/default-context.js';
+import { render as deviceRender } from '../gvc/device.js';
+import type { ImageSizer } from '../common/htmltable-types.js';
+import type { ImageResolver } from '../gvc/image-resolver.js';
+import type { OutputFormat, RenderOptions } from '../render/public.js';
+import { collectResources } from './collect.js';
+import { loadFonts } from './fonts.js';
+import type { FontIssue, FontSetLike } from './fonts.js';
+
+export type { FontIssue, FontSetLike } from './fonts.js';
+
+/** Default font-load deadline in milliseconds (ADR-3). */
+export const DEFAULT_FONT_TIMEOUT_MS = 3000;
+
+/** Result of an async image-size lookup; `null` is a miss. */
+export type AsyncImageSize = { w: number; h: number } | null;
+
+/** Result of an async image-bytes lookup; `null` is a miss. */
+export type AsyncImageBytes = { bytes: Uint8Array; mime?: string } | Uint8Array | null;
+
+/** Options for {@link renderAsync}. */
+export interface AsyncRenderOptions extends RenderOptions {
+  /** Async HTML `<IMG>` dimension lookup; a throw/reject counts as a miss. */
+  imageSizer?: (src: string) => Promise<AsyncImageSize>;
+  /** Async image bytes lookup for `inlineImages`; a throw/reject counts as a miss. */
+  imageResolver?: (src: string) => Promise<AsyncImageBytes>;
+  /** Font-load deadline in ms, shared by all faces. Default 3000. */
+  fontTimeoutMs?: number;
+  /** FontFaceSet-like to load faces from. Default `document.fonts` when present. */
+  fontSet?: FontSetLike;
+}
+
+/** Options for {@link renderSvgAsync}: {@link AsyncRenderOptions} minus `engine`. */
+export type AsyncSvgOptions = Omit<AsyncRenderOptions, 'engine'>;
+
+/** Resolved value of {@link renderAsync}. */
+export interface AsyncRenderResult {
+  output: string;
+  fontIssues: FontIssue[];
+}
+
+/** Resolved value of {@link renderSvgAsync}. */
+export interface AsyncSvgResult {
+  svg: string;
+  fontIssues: FontIssue[];
+}
+
+/** Reject a bad `g` / `format` / `opts` before any work starts (mirrors `render`). */
+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);
+  }
+}
+
+/** `document.fonts` when a document exposes one (absent in Node and Workers). */
+function defaultFontSet(): FontSetLike | undefined {
+  const doc: unknown = Reflect.get(globalThis, 'document');
+  if (typeof doc !== 'object' || doc === null) return undefined;
+  const fonts: unknown = Reflect.get(doc, 'fonts');
+  if (typeof fonts !== 'object' || fonts === null) return undefined;
+  return fonts as FontSetLike; // structural: FontFaceSet.load
+}
+
+/** Call `hook` once per distinct src; a throw or reject is a `null` miss. */
+async function prefetch<T>(
+  srcs: readonly string[],
+  hook: ((src: string) => Promise<T | null>) | undefined,
+): Promise<Map<string, T | null>> {
+  const out = new Map<string, T | null>();
+  if (hook === undefined) return out;
+  await Promise.all(
+    srcs.map(async (src) => {
+      try {
+        out.set(src, await hook(src));
+      } catch {
+        // ADR-5: a failing async hook is a miss, as in the sync hooks' null path.
+        out.set(src, null);
+      }
+    }),
+  );
+  return out;
+}
+
+/** Everything awaited before layout starts. */
+interface Prefetched {
+  fontIssues: FontIssue[];
+  sizes: Map<string, AsyncImageSize>;
+  bytes: Map<string, AsyncImageBytes>;
+}
+
+async function prefetchAll(g: Graph, opts: AsyncRenderOptions | undefined): Promise<Prefetched> {
+  const res = collectResources(g, { inlineImages: opts?.inlineImages ?? false });
+  const [fontIssues, sizes, bytes] = await Promise.all([
+    loadFonts(
+      opts?.fontSet ?? defaultFontSet(),
+      res.fonts,
+      opts?.fontTimeoutMs ?? DEFAULT_FONT_TIMEOUT_MS,
+    ),
+    prefetch(res.sizeSrcs, opts?.imageSizer),
+    prefetch(res.bytesSrcs, opts?.imageResolver),
+  ]);
+  return { fontIssues, sizes, bytes };
+}
+
+/**
+ * Render a (parsed or built) graph to the requested format after prefetching
+ * web fonts and image data, so layout measures real faces and sizes.
+ *
+ * Every failure, including usage `TypeError`s, is a promise rejection with the
+ * same classes and codes as {@link render}. Font problems never reject; they
+ * are returned in `fontIssues` (and `console.warn`ed).
+ *
+ * @remarks
+ * Security: for the markup formats (`svg`, `cmapx`, `imap`), treat the output
+ * as attacker-controlled when the source graph came from untrusted DOT.
+ * Attribute values are XML-escaped, but URL schemes and resource origins
+ * (`href`/`URL`/`image`/`stylesheet`) are passed through unfiltered, matching
+ * native Graphviz. Apply a Content-Security-Policy or sanitize before embedding
+ * — see the README "Security" section.
+ *
+ * @param g      - graph produced by `parse(...)` or the builder API
+ * @param format - target output format
+ * @param opts   - engine, `inlineImages`, async image hooks and font options
+ * @returns the rendered string and any font issues
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` / `ERR_INVALID_ARG_VALUE` (as rejection)
+ * @throws RenderError, InternalError (as rejection), as {@link render}
+ */
+export async function renderAsync(
+  g: Graph,
+  format: OutputFormat,
+  opts?: AsyncRenderOptions,
+): Promise<AsyncRenderResult> {
+  checkRenderArgs(g, format, opts);
+  const engine: EngineName = opts?.engine ?? 'dot';
+  try {
+    const { fontIssues, sizes, bytes } = await prefetchAll(g, opts);
+    // Created after fonts settle so the measurer sees the loaded faces.
+    const ctx = createDefaultContext();
+    if (opts?.imageSizer !== undefined) {
+      const sizer: ImageSizer = (src) => sizes.get(src) ?? null;
+      ctx.imageSizer = sizer;
+    }
+    if (opts?.imageResolver !== undefined) {
+      const resolver: ImageResolver = (src) => bytes.get(src) ?? null;
+      ctx.imageResolver = resolver;
+    }
+    ctx.layout(g, engine);
+    const output = deviceRender(ctx, g, format, opts?.inlineImages ?? false);
+    ctx.freeLayout(g, engine);
+    return { output, fontIssues };
+  } catch (err: unknown) {
+    return rethrowAtBoundary(err);
+  }
+}
+
+/**
+ * Async counterpart of `renderSvg`: parse DOT, prefetch fonts/images, render.
+ *
+ * @remarks
+ * Security: same untrusted-input caveat as `renderSvg` and {@link renderAsync}
+ * — the returned `svg` is attacker-controlled markup for untrusted `dotSource`;
+ * apply a CSP or sanitize before embedding. See the README "Security" section.
+ *
+ * @param dotSource - DOT-language graph source
+ * @param engine    - layout engine name
+ * @param opts      - `inlineImages`, async image hooks and font options
+ * @returns the SVG string and any font issues
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` / `ERR_INVALID_ARG_VALUE` (as rejection)
+ * @throws ParseError, RenderError, InternalError (as rejection), as `renderSvg`
+ */
+export async function renderSvgAsync(
+  dotSource: string,
+  engine: EngineName,
+  opts?: AsyncSvgOptions,
+): Promise<AsyncSvgResult> {
+  if (typeof dotSource !== 'string') throw invalidArgType('dotSource', 'string', dotSource);
+  if (typeof engine !== 'string') throw invalidArgType('engine', 'string', engine);
+  let g: Graph;
+  try {
+    g = parse(dotSource);
+  } catch (err: unknown) {
+    return rethrowAtBoundary(err);
+  }
+  const { output, fontIssues } = await renderAsync(g, 'svg', { ...opts, engine });
+  return { svg: output, fontIssues };
+}

package/src/async/render-into.ts

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * `renderSvgInto` (async-api ADR-6): render DOT to SVG and insert it into a
+ * DOM element, sanitizing by default. Insertion goes through
+ * `DOMParser('image/svg+xml')` + `importNode` + `replaceChildren`; never
+ * `innerHTML`. DOM-coupled by design (owner decision 4); browser-safe.
+ *
+ * @see src/async/render-async.ts:renderSvgAsync
+ * @see src/async/sanitize.ts:scrubSvgDocument
+ */
+
+import { RenderError, invalidArgType, invalidArgValue, invalidState } from '../errors.js';
+import type { EngineName } from '../gvc/context.js';
+import { renderSvgAsync } from './render-async.js';
+import type { AsyncSvgOptions } from './render-async.js';
+import type { FontIssue } from './fonts.js';
+import { scrubSvgDocument } from './sanitize.js';
+import type { SvgParserLike } from './sanitize.js';
+
+const SVG_MIME = 'image/svg+xml';
+const PARSER_ERROR_NAME = 'parsererror';
+
+/** Options for {@link renderSvgInto}. */
+export interface RenderSvgIntoOptions extends AsyncSvgOptions {
+  /** Custom sanitizer: receives the SVG string, returns the markup to insert. */
+  sanitize?: (svg: string) => string;
+  /** Insert the SVG as rendered, with no sanitizing at all. Default false. */
+  trusted?: boolean;
+  /** Document to look up `id` in and insert into. Default `globalThis.document`. */
+  document?: Document;
+  /** Parser override (test seam). Default: the document window's `DOMParser`. */
+  domParser?: SvgParserLike;
+}
+
+/** Resolved value of {@link renderSvgInto}. */
+export interface RenderSvgIntoResult {
+  /** The inserted (imported) root `<svg>` element. */
+  element: SVGSVGElement;
+  fontIssues: FontIssue[];
+}
+
+function resolveDocument(opts: RenderSvgIntoOptions | undefined): Document {
+  const doc: unknown = opts?.document ?? Reflect.get(globalThis, 'document');
+  if (typeof doc !== 'object' || doc === null) {
+    throw invalidState('renderSvgInto requires a document; pass opts.document or run in a browser');
+  }
+  return doc as Document; // structural: used only via getElementById/importNode
+}
+
+function resolveParser(doc: Document, opts: RenderSvgIntoOptions | undefined): SvgParserLike {
+  if (opts?.domParser !== undefined) return opts.domParser;
+  const view: unknown = doc.defaultView ?? globalThis;
+  const ctor: unknown = typeof view === 'object' && view !== null ? Reflect.get(view, 'DOMParser') : undefined;
+  if (typeof ctor !== 'function') {
+    throw invalidState('renderSvgInto requires a DOMParser; pass opts.domParser');
+  }
+  return new (ctor as new () => SvgParserLike)(); // structural: DOMParser.parseFromString
+}
+
+function hasParserError(doc: Document): boolean {
+  const root = doc.documentElement as Element | null;
+  if (root === null || root.nodeName.toLowerCase() === PARSER_ERROR_NAME) return true;
+  return root.getElementsByTagName(PARSER_ERROR_NAME).length > 0;
+}
+
+function parseSvg(parser: SvgParserLike, svg: string): Document {
+  let doc: Document;
+  try {
+    doc = parser.parseFromString(svg, SVG_MIME);
+  } catch (err: unknown) {
+    throw new RenderError('renderSvgInto could not parse the rendered SVG', 'RENDER_ERROR', {
+      cause: err,
+    });
+  }
+  if (hasParserError(doc)) {
+    throw new RenderError('renderSvgInto could not parse the rendered SVG', 'RENDER_ERROR');
+  }
+  return doc;
+}
+
+/**
+ * Render `src` and replace the children of the element with id `id` by the
+ * resulting `<svg>`.
+ *
+ * Order (ADR-6): `trusted === true` inserts as rendered; else `sanitize(svg)`
+ * if given; else the built-in scrubber (`scrubSvgDocument`).
+ *
+ * @param id     - id of the target element in the document
+ * @param src    - DOT source
+ * @param engine - layout engine name
+ * @param opts   - async render options plus `sanitize`, `trusted`, `document`
+ * @returns the inserted `<svg>` element and any font issues
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` / `ERR_INVALID_ARG_VALUE` /
+ *   `ERR_INVALID_STATE` (as rejection); RenderError if the SVG does not parse
+ */
+export async function renderSvgInto(
+  id: string,
+  src: string,
+  engine: EngineName,
+  opts?: RenderSvgIntoOptions,
+): Promise<RenderSvgIntoResult> {
+  if (typeof id !== 'string') throw invalidArgType('id', 'string', id);
+  const doc = resolveDocument(opts);
+  const target = doc.getElementById(id);
+  if (target === null) throw invalidArgValue('id', id, ['the id of an element in the document']);
+  const parser = resolveParser(doc, opts);
+  const { svg, fontIssues } = await renderSvgAsync(src, engine, opts);
+  const custom = opts?.trusted !== true ? opts?.sanitize : undefined;
+  const parsed = parseSvg(parser, custom !== undefined ? custom(svg) : svg);
+  if (opts?.trusted !== true && custom === undefined) scrubSvgDocument(parsed);
+  const element = doc.importNode(parsed.documentElement, true) as unknown as SVGSVGElement;
+  target.replaceChildren(element);
+  return { element, fontIssues };
+}

package/src/async/sanitize.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Built-in SVG scrubber (ADR-6). Uses only DOM Level 2 members of
+ * `Document`/`Element`/`Attr`/`Node`, so it runs on browser documents and on
+ * xmldom documents alike. This is a deny-list for the vectors the library's
+ * own output can carry (README "Security"); callers needing a stricter policy
+ * pass their own `sanitize` or a CSP.
+ */
+
+const ELEMENT_NODE = 1;
+const PROCESSING_INSTRUCTION_NODE = 7;
+
+/** Elements removed outright, with their whole subtree (local name, lowercase). */
+const BANNED_ELEMENTS: ReadonlySet<string> = new Set(['script', 'foreignobject']);
+
+/** SMIL elements that can write an attribute value (local name, lowercase). */
+const ANIMATION_ELEMENTS: ReadonlySet<string> = new Set([
+  'set',
+  'animate',
+  'animatemotion',
+  'animatetransform',
+]);
+
+const EVENT_ATTRIBUTE_PREFIX = 'on';
+const HREF_LOCAL_NAME = 'href';
+const IMAGE_ELEMENT = 'image';
+const ATTRIBUTE_NAME = 'attributeName';
+const XML_STYLESHEET_TARGET = 'xml-stylesheet';
+
+const SCRIPT_SCHEMES: readonly string[] = ['javascript:', 'vbscript:'];
+const DATA_SCHEME = 'data:';
+const DATA_IMAGE_PREFIX = 'data:image/';
+
+// ASCII whitespace plus every C0 control and DEL; browsers drop tab/CR/LF
+// anywhere in a URL and C0/space at its ends, so stripping all of them is a
+// superset that cannot let an obfuscated scheme through.
+// eslint-disable-next-line no-control-regex
+const IGNORED_URL_CHARS = /[\u0000- \u007f]/g;
+
+/** Structural subset of `DOMParser` used by {@link scrubSvgString}. */
+export interface SvgParserLike {
+  parseFromString(source: string, mimeType: 'image/svg+xml'): Document;
+}
+
+/** Structural subset of `XMLSerializer` used by {@link scrubSvgString}. */
+export interface SvgSerializerLike {
+  serializeToString(node: Node): string;
+}
+
+function localNameOf(node: { localName?: string | null; nodeName: string }): string {
+  const local = node.localName;
+  const name = typeof local === 'string' && local !== '' ? local : node.nodeName;
+  const colon = name.lastIndexOf(':');
+  return (colon >= 0 ? name.slice(colon + 1) : name).toLowerCase();
+}
+
+function normalizeUrl(value: string): string {
+  return value.replace(IGNORED_URL_CHARS, '').toLowerCase();
+}
+
+function isHostileUrl(value: string, element: Element): boolean {
+  const url = normalizeUrl(value);
+  if (SCRIPT_SCHEMES.some((scheme) => url.startsWith(scheme))) return true;
+  if (!url.startsWith(DATA_SCHEME)) return false;
+  return !(localNameOf(element) === IMAGE_ELEMENT && url.startsWith(DATA_IMAGE_PREFIX));
+}
+
+function isEventAttribute(attr: Attr): boolean {
+  return (
+    attr.name.toLowerCase().startsWith(EVENT_ATTRIBUTE_PREFIX) ||
+    localNameOf(attr).startsWith(EVENT_ATTRIBUTE_PREFIX)
+  );
+}
+
+function isHostileAttribute(attr: Attr, element: Element): boolean {
+  if (isEventAttribute(attr)) return true;
+  return localNameOf(attr) === HREF_LOCAL_NAME && isHostileUrl(attr.value, element);
+}
+
+/**
+ * An animation targeting `href` (any prefix or case) or an event handler can
+ * write a hostile value after the static attribute scrub ran.
+ */
+function isHostileAnimation(element: Element): boolean {
+  if (!ANIMATION_ELEMENTS.has(localNameOf(element))) return false;
+  const target = (element.getAttribute(ATTRIBUTE_NAME) ?? '').trim().toLowerCase();
+  const local = target.slice(target.lastIndexOf(':') + 1);
+  return local === HREF_LOCAL_NAME || local.startsWith(EVENT_ATTRIBUTE_PREFIX);
+}
+
+function scrubAttributes(element: Element): void {
+  const doomed: Attr[] = [];
+  for (let i = 0; i < element.attributes.length; i++) {
+    const attr = element.attributes.item(i);
+    if (attr !== null && isHostileAttribute(attr, element)) doomed.push(attr);
+  }
+  for (const attr of doomed) element.removeAttributeNode(attr);
+}
+
+function isDoomedNode(node: Node): boolean {
+  if (node.nodeType === PROCESSING_INSTRUCTION_NODE) {
+    return node.nodeName.toLowerCase() === XML_STYLESHEET_TARGET;
+  }
+  if (node.nodeType !== ELEMENT_NODE) return false;
+  return BANNED_ELEMENTS.has(localNameOf(node)) || isHostileAnimation(node as Element);
+}
+
+/**
+ * Scrub `doc` in place: remove `script`/`foreignObject`, `href`-targeting
+ * animations, every `on*` attribute, `javascript:`/`vbscript:` hrefs, `data:`
+ * hrefs other than `data:image/*` on `<image>`, and `xml-stylesheet`
+ * processing instructions. Element, attribute and PI matching ignores case and
+ * namespace prefix.
+ *
+ * @param doc - A document parsed from SVG; mutated.
+ */
+export function scrubSvgDocument(doc: Document): void {
+  const pending: Node[] = [doc];
+  while (pending.length > 0) {
+    const parent = pending.pop() as Node;
+    const children = Array.from(parent.childNodes);
+    for (const child of children) {
+      if (isDoomedNode(child)) {
+        parent.removeChild(child);
+      } else if (child.nodeType === ELEMENT_NODE) {
+        scrubAttributes(child as Element);
+        pending.push(child);
+      }
+    }
+  }
+}
+
+/**
+ * Parse `svg`, scrub it with {@link scrubSvgDocument} and serialize it back.
+ *
+ * @param svg - SVG source text.
+ * @param parser - A `DOMParser`-like object.
+ * @param serializer - An `XMLSerializer`-like object.
+ * @returns The scrubbed SVG text.
+ */
+export function scrubSvgString(
+  svg: string,
+  parser: SvgParserLike,
+  serializer: SvgSerializerLike,
+): string {
+  const doc = parser.parseFromString(svg, 'image/svg+xml');
+  scrubSvgDocument(doc);
+  return serializer.serializeToString(doc);
+}

package/src/common/css-font.ts

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: EPL-2.0
+//
+// CSS `font` shorthand for canvas text measurement. C graphviz has no canvas
+// measurer; its text-layout plugin measures through the PostScript alias
+// (plugin/pango/gvtextlayout_pango.c:112), and the SVG emitter renders through
+// the same alias (svg_textspan). This builder yields the face the SVG renders
+// with, so browser measurement and rendering agree. Selection follows the
+// NATIVEFONTS branch of svg_textspan (plans/canvas-font-mapping ADR-1).
+
+import { translatePostscriptFontname, type PostscriptAlias } from './ps-fontalias.js';
+import type { TextVariantFlags } from './textmeasure.js';
+
+/** svg_textspan's family when a span has no font name. */
+const DEFAULT_FAMILIES: readonly string[] = ['Times', 'serif'];
+
+const CSS_GENERIC_FAMILIES: ReadonlySet<string> = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+]);
+
+const CSS_WEIGHT_KEYWORDS: ReadonlySet<string> = new Set([
+  'normal', 'bold', 'bolder', 'lighter',
+]);
+
+const DQ = '\u0022';
+const SQ = '\u0027';
+const BACKSLASH = '\\';
+
+/**
+ * True when `w` is a value CSS accepts for font-weight (ADR-2). Alias weights
+ * are a fixed keyword set (ps_font_equiv.h), never numeric, so only the
+ * keywords are checked.
+ */
+function isCssWeight(w: string): boolean {
+  return CSS_WEIGHT_KEYWORDS.has(w.toLowerCase());
+}
+
+/** Remove one pair of matching surrounding quotes. */
+function stripQuotes(f: string): string {
+  const q = f.charAt(0);
+  if (f.length >= 2 && (q === DQ || q === SQ) && f.endsWith(q)) return f.slice(1, -1);
+  return f;
+}
+
+/** Quote a family name unless it is a CSS generic family (ADR-4). */
+function quoteFamily(f: string): string {
+  if (CSS_GENERIC_FAMILIES.has(f.toLowerCase())) return f;
+  const escaped = f.split(BACKSLASH).join(BACKSLASH + BACKSLASH)
+    .split(DQ).join(BACKSLASH + DQ);
+  return DQ + escaped + DQ;
+}
+
+/** Split a non-alias fontname into its family entries (ADR-4). */
+function splitFamilies(fontname: string | null): readonly string[] {
+  const entries = (fontname ?? '').split(',')
+    .map((f) => stripQuotes(f.trim()).trim())
+    .filter((f) => f !== '');
+  return entries.length > 0 ? entries : DEFAULT_FAMILIES;
+}
+
+/**
+ * NATIVEFONTS family list: family, plus svg_font_family when it differs.
+ * @see plugin/core/gvrender_core_svg.c:487-489
+ */
+function aliasFamilies(a: PostscriptAlias): readonly string[] {
+  return a.svgFontFamily !== a.family ? [a.family, a.svgFontFamily] : [a.family];
+}
+
+/** Style token: the alias style, else italic from the HTML_IF flag. */
+function styleToken(a: PostscriptAlias | null, flags?: TextVariantFlags): string | null {
+  if (a?.style != null) return a.style;
+  return flags?.italic === true ? 'italic' : null;
+}
+
+/**
+ * Weight token. The bold flag applies only when the alias set no weight —
+ * tested on the alias value BEFORE the ADR-2 drop, as C's HTML_BF guard tests
+ * the raw alias weight (so `demi` + bold renders, and measures, normal).
+ */
+function weightToken(a: PostscriptAlias | null, flags?: TextVariantFlags): string | null {
+  if (a?.weight != null) return isCssWeight(a.weight) ? a.weight : null;
+  return flags?.bold === true ? 'bold' : null;
+}
+
+/**
+ * style/weight/stretch tokens in shorthand order.
+ * @see plugin/core/gvrender_core_svg.c:490-500
+ */
+function variantTokens(a: PostscriptAlias | null, flags?: TextVariantFlags): string[] {
+  const tokens = [styleToken(a, flags), weightToken(a, flags), a?.stretch ?? null];
+  return tokens.filter((t): t is string => t !== null);
+}
+
+/**
+ * CSS `font` shorthand (`[style] [weight] [stretch] <size>px <families>`)
+ * naming the face svg_textspan renders `fontname` with. Pure; always
+ * syntactically valid CSS.
+ * @see plugin/core/gvrender_core_svg.c:462-500 svg_textspan (family/weight/style selection)
+ */
+export function canvasFont(
+  fontname: string | null,
+  fontsize: number,
+  flags?: TextVariantFlags,
+): string {
+  // C translate_postscript_fontname matches the whole name only.
+  const a = fontname !== null ? translatePostscriptFontname(fontname) : null;
+  const families = a !== null ? aliasFamilies(a) : splitFamilies(fontname);
+  const tokens = [...variantTokens(a, flags), `${fontsize}px`];
+  return `${tokens.join(' ')} ${families.map(quoteFamily).join(', ')}`;
+}

package/src/common/htmltable-types.ts

@@ -9,8 +9,7 @@
 // Error
 // ---------------------------------------------------------------------------
 
-import type { GvError } from '../errors.js';
-import { friendlyMessageFor } from '../errors.js';
+import { DotEngineError, friendlyMessageFor } from '../errors.js';
 
 /**
  * Thrown when an unrecognized HTML tag is encountered during parsing.
@@ -21,14 +20,14 @@ import { friendlyMessageFor } from '../errors.js';
  *
  * @see lib/common/htmllex.c:lexerror
  */
-export class HtmlParseError extends Error implements GvError {
+export class HtmlParseError extends DotEngineError {
   readonly type = 'semantic';
   readonly code = 'HTML_PARSE_ERROR';
   readonly friendlyMessage = friendlyMessageFor('HTML_PARSE_ERROR');
   readonly tag: string;
 
-  constructor(tag: string) {
-    super(`Unknown HTML element <${tag}>`);
+  constructor(tag: string, options?: ErrorOptions) {
+    super(`Unknown HTML element <${tag}>`, options);
     this.tag = tag;
     this.name = 'HtmlParseError';
   }

package/src/common/make-label.ts

@@ -14,6 +14,8 @@ import type { TextMeasurer, TextSize } from './textmeasure.js';
 import type { TextSpan } from './emit-types.js';
 import { makeHtmlLabel } from './htmltable-pos.js';
 import { substObj, type GraphObj } from './subst.js';
+import { Edge } from '../model/edge.js';
+import type { Graph } from '../model/graph.js';
 import { htmlEntityUTF8 } from './html-entities.js';
 
 export const DEFAULT_FONTSIZE = 14.0;
@@ -39,6 +41,11 @@ function getPenColor(obj?: GraphObj): string | undefined {
   return undefined;
 }
 
+/** The root graph owning `obj` (edges resolve through their tail node). */
+function rootOf(obj: GraphObj): Graph {
+  return obj instanceof Edge ? obj.tail.root : obj.root;
+}
+
 /** Font attributes bundle — mirrors C fontinfo_t fields used in label init. */
 export interface FontInfo {
   fontname: string;
@@ -180,7 +187,9 @@ export function makeAnyLabel(
     // plain text (html=false) per htmltable.c:1892. Thread the owning object's
     // pen color so an HTML table/cell border with no explicit COLOR inherits
     // it (htmltable.c:1911 getPenColor). @see getPenColor
-    return makeHtmlLabel(content, { ...font, pencolor: getPenColor(obj) }, measurer);
+    // ADR-2: a per-context sizer (when set) wins over the global one.
+    const imageSizer = obj !== undefined ? rootOf(obj).info.gvc?.imageSizer : undefined;
+    return makeHtmlLabel(content, { ...font, pencolor: getPenColor(obj), imageSizer }, measurer);
   }
   // Plain path: resolve \G \N \E \T \H \L against the owning object
   // BEFORE measuring, as C does (labels.c:169, escBackslash=0; the

package/src/common/poly-shapes.ts

@@ -9,6 +9,7 @@
 // poly-shapes-util.ts and the per-shape vertex generators in
 // poly-shapes-cases.ts.
 
+import { RenderError } from '../errors.js';
 import type { Point } from '../model/geom.js';
 import {
   type ShapeCtx, interpolationPoints, renderShapeBezier,
@@ -73,7 +74,9 @@ export function drawSpecialShape(
   }
   const draw = CASES.get(shape);
   if (draw === undefined) {
-    throw new Error('special shape ' + String(shape) + ' not yet ported');
+    throw new RenderError(
+      'special shape ' + String(shape) + ' not yet ported', 'UNSUPPORTED_FEATURE',
+    );
   }
   const b = interpolationPoints(ring, ring.length, shape);
   draw(ring, b, coord, filled, ctx);

package/src/common/textmeasure-factory.ts

@@ -23,6 +23,8 @@ import {
   LutTextMeasurer, CanvasTextMeasurer, EstimateTextMeasurer, type TextMeasurer,
 } from './textmeasure.js';
 
+import { invalidArgType } from '../errors.js';
+
 let override: TextMeasurer | undefined;
 
 /**
@@ -31,8 +33,17 @@ let override: TextMeasurer | undefined;
  * render (renderSvg resolves the measurer per call). Use for deterministic
  * tests or to wire a host-faithful Node measurer (e.g. node-canvas) — see the
  * resolution note above.
+ * @throws TypeError `ERR_INVALID_ARG_TYPE` if `m` is neither undefined nor an
+ *   object with a `measure` function
  */
 export function setTextMeasurer(m: TextMeasurer | undefined): void {
+  if (
+    m !== undefined
+    && (typeof m !== 'object' || m === null
+      || typeof (m as { measure?: unknown }).measure !== 'function')
+  ) {
+    throw invalidArgType('measurer', 'TextMeasurer or undefined', m);
+  }
   override = m;
 }