@knowvah/dot-engine 2.6.11 → 2.7.0

package/src/common/htmltable-lex-expat.ts

@@ -270,12 +270,36 @@ function scanCdata(text: string, p: number, base: number, dataOf: CdataText, tok
   return close < 0 ? -1 : close + CDATA_CLOSE.length;
 }
 
-/** Character data at `p` up to the next `<`: one `text` token, then the index it ends at. */
-function scanText(text: string, p: number, base: number, tokens: ExpatToken[]): number {
+/**
+ * A character expat's tokenizer rejects in character data (BT_NONXML in the
+ * UTF-8 table): controls other than tab, LF and CR, U+FFFE and U+FFFF, and a
+ * lone surrogate (the UTF-8 form of one is invalid). DEL is BT_OTHER, valid.
+ * @see expat lib/asciitab.h
+ * @see expat lib/xmltok_impl.c:PREFIX(contentTok) (BT_NONXML)
+ */
+const CONTENT_NON_XML = /[\x00-\x08\x0b\x0c\x0e-\x1f\ufffe\uffff]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+
+/**
+ * Character data at `p` up to the next `<`: one `text` token, then the index it
+ * ends at. A reference cut off by the end of the data is not part of the token
+ * (`held`): expat waits for the characters that settle it. A BT_NONXML character
+ * ends the data token; the next call finds it an invalid token (`invalid`).
+ * @see expat lib/xmltok_impl.c:PREFIX(contentTok) (XML_TOK_PARTIAL, BT_NONXML)
+ */
+function scanText(
+  text: string, p: number, base: number, tokens: ExpatToken[],
+): { at: number; held: boolean; invalid?: number } {
   const e = text.indexOf('<', p);
-  const end = e < 0 ? text.length : e;
-  tokens.push({ kind: 'text', start: base + p, end: base + end });
-  return end;
+  const slice = text.slice(p, e < 0 ? text.length : e);
+  const bad = CONTENT_NON_XML.exec(slice)?.index;
+  if (bad !== undefined) {
+    if (bad > 0) tokens.push({ kind: 'text', start: base + p, end: base + p + bad });
+    return { at: p + bad, held: false, invalid: p + bad };
+  }
+  const from = e < 0 ? heldRefStart(slice) : undefined;
+  const end = from === undefined ? p + slice.length : p + from;
+  if (end > p) tokens.push({ kind: 'text', start: base + p, end: base + end });
+  return { at: end, held: from !== undefined };
 }
 
 /** The fed text of the label source between two offsets. */
@@ -295,7 +319,10 @@ function scanContent(text: string, base: number, inCdata: boolean, dataOf: Cdata
       continue;
     }
     if (text[p] !== '<') {
-      p = scanText(text, p, base, tokens);
+      const scanned = scanText(text, p, base, tokens);
+      if (scanned.invalid !== undefined) return { tokens, consumed: scanned.at, invalid: base + scanned.invalid, inCdata: false };
+      if (scanned.held) return { tokens, consumed: scanned.at, inCdata: false };
+      p = scanned.at;
       continue;
     }
     const { scan, kind } = scanMarkup(text, p);
@@ -408,33 +435,79 @@ export class ExpatFeed {
 /** Entities expat knows without a DTD; `scanEntity` leaves them as written. */
 const XML_PREDEFINED_ENTITIES = new Set(['lt', 'gt', 'amp', 'quot', 'apos']);
 
-const ENTITY_NAME = /^[A-Za-z_:][\w.:-]*$/;
+/** An `&name;` that `scanEntity` rewrites: 2 to 8 characters (alphanumeric) that name an HTML entity. */
+const SCANNED_ENTITY = /^&([^;&<]*);/;
 
-const CHAR_REF = /^&#(?:x[0-9A-Fa-f]+|[0-9]+);/;
+/**
+ * The reference the content tokenizer reads at the `&` at `t`: the index after
+ * its `;`, or the index of the character that makes it an invalid token (the
+ * end of `text` when the reference runs out: `</HTML>` or another tag follows).
+ * Runs the attribute value scanner over the reference alone, closed by a quote,
+ * which is scanRef on the same bytes.
+ * @see expat lib/xmltok_impl.c:PREFIX(contentTok) (BT_AMP)
+ * @see expat lib/xmltok_impl.c:PREFIX(scanRef)
+ * @see expat lib/xmltok_impl.c:PREFIX(scanCharRef)
+ * @see expat lib/xmltok_impl.c:PREFIX(scanHexCharRef)
+ */
+function contentRef(text: string, t: number): { end: number } | { invalid: number } {
+  const semi = text.indexOf(';', t);
+  const ref = text.slice(t, semi < 0 ? text.length : semi + 1);
+  const scan = scanAttValue(`"${ref}"`, 0);
+  if ('close' in scan) return { end: t + scan.close - 1 };
+  return { invalid: 'invalid' in scan ? t + scan.invalid - 1 : text.length };
+}
+
+/** A reference problem of character data: expat's error, where its event pointer is, and the `&` it began at. */
+interface RefProblem {
+  message: string;
+  offset: number;
+  from: number;
+}
 
 /**
- * The first reference of character data that expat rejects, at its offset: a
- * `&name;` scanEntity leaves alone (neither an HTML entity nor predefined), or
- * a character reference XML does not allow.
- * @see expat lib/xmlparse.c:doContent (XML_TOK_ENTITY_REF, XML_TOK_CHAR_REF)
+ * The first reference of character data that expat rejects: an invalid token
+ * (a bare `&`, `&#;`, `&#X41;`, `&#65q`, ..), a `&name;` scanEntity leaves
+ * alone (neither an HTML entity nor predefined), or a character reference XML
+ * does not allow. An invalid token at the very end of `text` is a reference
+ * expat is still waiting on.
+ * @see lib/common/utils.c:scanEntity
+ * @see expat lib/xmlparse.c:doContent (XML_TOK_INVALID, XML_TOK_ENTITY_REF, XML_TOK_CHAR_REF)
  */
-export function textRefError(text: string): { message: string; offset: number } | undefined {
-  for (let t = text.indexOf('&'); t >= 0; t = text.indexOf('&', t + 1)) {
-    if (text[t + 1] === '#') {
-      const ref = CHAR_REF.exec(text.slice(t))?.[0];
-      if (ref !== undefined && charRefNumber(ref) < 0) return { message: XML_ERROR_BAD_CHAR_REF, offset: t };
-      continue;
+function firstRefProblem(text: string): RefProblem | undefined {
+  let t = text.indexOf('&');
+  while (t >= 0) {
+    if (text[t + 1] !== '#') {
+      const name = SCANNED_ENTITY.exec(text.slice(t))?.[1];
+      if (name !== undefined && name.length >= 2 && Object.hasOwn(HTML_ENTITIES, name)) {
+        t = text.indexOf('&', t + name.length + 2);
+        continue;
+      }
     }
-    const semi = text.indexOf(';', t + 1);
-    if (semi < 0) continue;
-    const key = text.slice(t + 1, semi);
-    if (ENTITY_NAME.test(key) && !Object.hasOwn(HTML_ENTITIES, key) && !XML_PREDEFINED_ENTITIES.has(key)) {
-      return { message: XML_ERROR_UNDEFINED_ENTITY, offset: t };
+    const ref = contentRef(text, t);
+    if ('invalid' in ref) return { message: XML_ERROR_INVALID_TOKEN, offset: ref.invalid, from: t };
+    const key = text.slice(t + 1, ref.end - 1);
+    if (text[t + 1] === '#') {
+      if (charRefNumber(`&${key};`) < 0) return { message: XML_ERROR_BAD_CHAR_REF, offset: t, from: t };
+    } else if (!XML_PREDEFINED_ENTITIES.has(key)) {
+      return { message: XML_ERROR_UNDEFINED_ENTITY, offset: t, from: t };
     }
+    t = text.indexOf('&', ref.end);
   }
   return undefined;
 }
 
+/** The first reference of character data that expat rejects, and the offset of its event pointer. */
+export function textRefError(text: string): { message: string; offset: number } | undefined {
+  const problem = firstRefProblem(text);
+  return problem === undefined ? undefined : { message: problem.message, offset: problem.offset };
+}
+
+/** Where a reference that runs to the end of `text` begins: expat holds it until more data arrives. */
+function heldRefStart(text: string): number | undefined {
+  const problem = firstRefProblem(text);
+  return problem?.message === XML_ERROR_INVALID_TOKEN && problem.offset === text.length ? problem.from : undefined;
+}
+
 export interface TagChunk {
   close: boolean;
   selfClose: boolean;

package/src/common/htmltable-pos-runs.ts

@@ -48,7 +48,10 @@ export interface HtmlFontInfo {
   fontcolor: string;
 }
 
-interface LineRun {
+/** The label font defaults the line builder needs (sizing env or placement finfo). */
+export type LabelFont = Pick<HtmlFontInfo, 'fontname' | 'fontsize'>;
+
+export interface LineRun {
   items: HtmlTextItem[];
   width: number;
   /** Max raw font size over items (C mxfsize). */
@@ -84,7 +87,7 @@ export function itemFontFlags(item: HtmlTextItem): number {
 }
 
 /** Resolved face/size for an item, defaulting to the inherited finfo. */
-function itemFace(item: HtmlTextItem, finfo: HtmlFontInfo): { fs: number; face: string } {
+function itemFace(item: HtmlTextItem, finfo: LabelFont): { fs: number; face: string } {
   return {
     fs: item.fontSize !== undefined ? item.fontSize : finfo.fontsize,
     face: item.fontFace !== undefined ? item.fontFace : finfo.fontname,
@@ -95,7 +98,7 @@ function itemFace(item: HtmlTextItem, finfo: HtmlFontInfo): { fs: number; face:
 interface ItemMetric { w: number; h: number; fs: number; yoffsetCenterline?: number; yoffsetLayout?: number; }
 
 /** Measure one text item; null when the item carries no text. */
-function measureItem(item: HtmlTextItem, finfo: HtmlFontInfo, measurer: TextMeasurer): ItemMetric | null {
+function measureItem(item: HtmlTextItem, finfo: LabelFont, measurer: TextMeasurer): ItemMetric | null {
   if (item.text === undefined) return null;
   const { fs, face } = itemFace(item, finfo);
   const flags = itemFontFlags(item);
@@ -142,11 +145,13 @@ function accumulateItem(cur: LineRun, item: HtmlTextItem, m: ItemMetric): void {
  *   in the current font (consecutive BRs = a real blank line with height);
  * - at end of text a line is added ONLY if items remain — a trailing BR does
  *   NOT create a phantom empty line (this over-sized e.g. html2's node c).
+ * The single builder: size_html_txt (sizing) and emit_htextspans (placement)
+ * both read these runs, as C reads one htextspan_t list.
  * @see lib/common/htmlparse.y:appendFLineList / mkText
  */
 export function buildLineRuns(
   texts: HtmlText[],
-  finfo: HtmlFontInfo,
+  finfo: LabelFont,
   measurer: TextMeasurer,
 ): LineRun[] {
   const runs: LineRun[] = [];
@@ -181,7 +186,7 @@ export function buildLineRuns(
  */
 function runSimpleKey(
   run: LineRun,
-  finfo: HtmlFontInfo,
+  finfo: LabelFont,
 ): { fs: number; face: string } | null | undefined {
   if (run.items.length > 1) return null;
   const item = run.items[0];
@@ -195,7 +200,7 @@ function runSimpleKey(
  * uniform resolved face/size across lines.
  * @see lib/common/htmltable.c:size_html_txt (lines 946-986)
  */
-export function runsAreSimple(runs: LineRun[], finfo: HtmlFontInfo): boolean {
+export function runsAreSimple(runs: LineRun[], finfo: LabelFont): boolean {
   let prevFs = -1;
   let prevFace: string | null = null;
   for (const run of runs) {

package/src/common/htmltable.ts

@@ -20,11 +20,13 @@ export type { TextMeasurer } from './textmeasure.js';
 
 import type {
   HtmlCell, HtmlCellContent, HtmlImage, HtmlLabel, HtmlTable, HtmlText,
-  HtmlTextItem, ImageSizer,
+  ImageSizer,
 } from './htmltable-types.js';
-import { findImageSize } from '../gvc/usershape.js';
+import { findImageSize, imageIsSupplied, imageOpenWarning } from '../gvc/usershape.js';
+import { registerRenderState } from './render-state.js';
 import { PointSet } from './pointset.js';
 import type { TextMeasurer } from './textmeasure.js';
+import { buildLineRuns, runsAreSimple } from './htmltable-pos-runs.js';
 import { withTableFont } from './htmltable-fontinfo.js';
 import { agerrLine, type StderrLines } from './htmltable-attr-warn.js';
 
@@ -90,108 +92,6 @@ export interface HtmlSizeEnv {
 
 const defaultSizeEnv = (): HtmlSizeEnv => ({ fontsize: DEFAULT_FONTSIZE, fontname: '' });
 
-/** One measured text line (a C "span"). @see size_html_txt */
-interface SizedLine {
-  items: HtmlTextItem[];
-  width: number;
-  /** Max metric line height over items (C mxysize). */
-  mxysize: number;
-  /** Max raw font size over items (C mxfsize). */
-  mxfsize: number;
-}
-
-const itemFont = (item: HtmlTextItem, env: HtmlSizeEnv): { fs: number; face: string } => ({
-  fs: item.fontSize !== undefined ? item.fontSize : env.fontsize,
-  face: item.fontFace !== undefined ? item.fontFace : env.fontname,
-});
-
-const measureItem = (
-  item: HtmlTextItem,
-  measurer: TextMeasurer,
-  env: HtmlSizeEnv,
-): { w: number; h: number } => {
-  const { fs, face } = itemFont(item, env);
-  // Variant widths per run flags. @see lib/common/htmltable.c:size_html_txt
-  const flags = (item.bold === true || item.italic === true)
-    ? { bold: item.bold === true, italic: item.italic === true }
-    : undefined;
-  return measurer.measure(item.text ?? '', face, fs, flags);
-};
-
-/**
- * Split items into measured lines at <BR/>, mirroring C's parser exactly
- * (htmlparse.y appendFLineList/mkText): a BR with no accumulated items yields
- * a line with one empty-string item in the current font (consecutive BRs = a
- * real blank line with height); at end of text a line is added ONLY if items
- * remain — a trailing BR does NOT create a phantom empty line. Must stay in
- * lockstep with buildLineRuns (htmltable-pos-runs.ts), the placement twin.
- * @see lib/common/htmlparse.y:appendFLineList / mkText
- * @see lib/common/htmltable.c:size_html_txt
- */
-const splitSizedLines = (
-  texts: HtmlText[],
-  measurer: TextMeasurer,
-  env: HtmlSizeEnv,
-): SizedLine[] => {
-  const lines: SizedLine[] = [];
-  let cur: SizedLine = { items: [], width: 0, mxysize: 0, mxfsize: 0 };
-  const accumulate = (item: HtmlTextItem): void => {
-    const sz = measureItem(item, measurer, env);
-    cur.items.push(item);
-    cur.width += sz.w;
-    cur.mxysize = Math.max(cur.mxysize, sz.h);
-    cur.mxfsize = Math.max(cur.mxfsize, itemFont(item, env).fs);
-  };
-  const flush = (br?: HtmlTextItem): void => {
-    if (cur.items.length === 0 && br !== undefined) {
-      // C: empty fitemList on a BR → one ""-item span in the current font.
-      const { br: _b, brAlign: _a, ...fontProps } = br;
-      accumulate({ text: '', ...fontProps });
-    }
-    lines.push(cur);
-    cur = { items: [], width: 0, mxysize: 0, mxfsize: 0 };
-  };
-  for (const txt of texts) {
-    for (const item of txt.items) {
-      if (item.br) { flush(item); continue; }
-      if (item.text === undefined) continue;
-      accumulate(item);
-    }
-    if (cur.items.length > 0) flush(); // C mkText: only when items remain
-  }
-  return lines;
-};
-
-/** Does an item carry any font flag (C textfont_t.flags)? */
-const itemHasFlags = (i: HtmlTextItem): boolean =>
-  i.bold === true || i.italic === true || i.underline === true ||
-  i.strikethrough === true || i.overline === true ||
-  i.subscript === true || i.superscript === true;
-
-/**
- * C's "simple" test: one item per line, no font flags, uniform
- * resolved face and size across all lines.
- * @see lib/common/htmltable.c:size_html_txt (lines 946-986)
- */
-export const htmlTextIsSimple = (texts: HtmlText[], env: HtmlSizeEnv): boolean => {
-  let prevFs = -1;
-  let prevFace: string | null = null;
-  let count = 0;
-  for (const txt of texts) {
-    for (const item of txt.items) {
-      if (item.br) { count = 0; continue; }
-      if (item.text === undefined) continue;
-      if (++count > 1 || itemHasFlags(item)) return false;
-      const { fs, face } = itemFont(item, env);
-      if (prevFs < 0) prevFs = fs;
-      else if (fs !== prevFs) return false;
-      if (prevFace === null) prevFace = face;
-      else if (face !== prevFace) return false;
-    }
-  }
-  return true;
-};
-
 /**
  * Size a text block. C: per line lsize = mxysize when simple, else the
  * raw max font size (mxfsize); a single-line block always uses mxysize.
@@ -202,16 +102,17 @@ const sizeTextContent = (
   measurer: TextMeasurer,
   env: HtmlSizeEnv = defaultSizeEnv(),
 ): { w: number; h: number } => {
-  const lines = splitSizedLines(texts, measurer, env);
-  const simple = htmlTextIsSimple(texts, env);
+  // The one line builder, shared with placement (htmltable-pos-runs.ts).
+  const lines = buildLineRuns(texts, env, measurer);
+  const simple = runsAreSimple(lines, env);
   let w = 0;
   let h = 0;
   for (const ln of lines) {
     w = Math.max(w, ln.width);
-    const lsize = simple ? ln.mxysize : ln.mxfsize;
+    const lsize = simple ? ln.height : ln.fontSize;
     h += ln.items.length > 0 ? lsize : DEFAULT_FONTSIZE;
   }
-  if (lines.length === 1) h = lines[0]!.items.length > 0 ? lines[0]!.mxysize : DEFAULT_FONTSIZE;
+  if (lines.length === 1) h = lines[0]!.items.length > 0 ? lines[0]!.height : DEFAULT_FONTSIZE;
   return { w, h };
 };
 
@@ -229,25 +130,28 @@ const sizeTextContent = (
  * @see lib/common/htmltable.c:size_html_img (line 1080)
  */
 /** Images whose sizing failed: size_html_img's rv = 1 on every later call. */
-const missingImages = new WeakSet<HtmlImage>();
+const missingImages = { set: new WeakSet<HtmlImage>() };
 
 const sizeHtmlImg = (img: HtmlImage, { imageSizer, stderr }: HtmlSizeEnv): number => {
   // C sizes each image once (processTbl); the port's size and pos passes
   // share layoutHtmlTable, so guard against re-sizing (and re-warning). The
   // returned rv still follows C on every call.
-  if (img.width !== undefined && img.height !== undefined) return missingImages.has(img) ? 1 : 0;
+  if (img.width !== undefined && img.height !== undefined) return missingImages.set.has(img) ? 1 : 0;
   const sz = imageSizer !== undefined ? imageSizer(img.src) : findImageSize(img.src);
   if (sz !== null) {
     img.width = sz.w; img.height = sz.h;
     return 0;
   }
-  // Missing-image: zero size + warning.
+  // Missing-image: gvusershape_open's warning (unless bytes are supplied),
+  // then zero size + the Error.
+  // @see lib/gvc/gvusershape.c:gvusershape_file_access
+  if (!imageIsSupplied(img.src, imageSizer)) agerrLine(stderr, `Warning: ${imageOpenWarning(img.src)}`);
   // C: agerrorf("No or improper image file=\"%s\"\n", img->src) — agerr
   // prefixes "Error: " on stderr.
   agerrLine(stderr, `Error: No or improper image file="${img.src}"`);
   img.width = 0;
   img.height = 0;
-  missingImages.add(img);
+  missingImages.set.add(img);
   return 1;
 };
 
@@ -318,7 +222,14 @@ const WARN_TABLE_UNSPECIFIED = 'Warning: fixed table size with unspecified width
  * C sizes each cell/table exactly once; the port's size and pos passes both
  * run layoutHtmlTable, so the size warnings are emitted on first sight only.
  */
-const sizeWarned = new WeakSet<object>();
+const sizeWarned = { set: new WeakSet<object>() };
+
+// Native re-parses per run, so each render starts with both sets empty (AD-7);
+// a WeakSet cannot be cleared, so the holder's field is swapped.
+registerRenderState(() => {
+  missingImages.set = new WeakSet<HtmlImage>();
+  sizeWarned.set = new WeakSet<object>();
+});
 
 /**
  * FIXED_FLAG branch of size_html_cell: C's rv (set at the warning sites; the
@@ -358,8 +269,8 @@ const getCellSize = (
   // @see lib/common/htmltable.c:size_html_cell (FIXED_FLAG branch + box.UR MAX)
   let szx = cw + margin;
   let szy = ch + margin;
-  const warn = !sizeWarned.has(cell);
-  sizeWarned.add(cell);
+  const warn = !sizeWarned.set.has(cell);
+  sizeWarned.set.add(cell);
   const fixed = fixedCellCheck(cell, { w: szx, h: szy }, warn, env.stderr);
   rv |= fixed.rv;
   if (fixed.zero) { szx = 0; szy = 0; }
@@ -505,8 +416,8 @@ export const layoutHtmlTable = (
  * @see lib/common/htmltable.c:size_html_tbl (:1683, :1689)
  */
 const warnFixedTable = (tbl: HtmlTable, dims: { wd: number; ht: number }, out: StderrLines | undefined): number => {
-  const warn = !sizeWarned.has(tbl);
-  sizeWarned.add(tbl);
+  const warn = !sizeWarned.set.has(tbl);
+  sizeWarned.set.add(tbl);
   if (tbl.fixedsize !== true) return 0;
   if (tbl.width && tbl.height) {
     if (tbl.width >= dims.wd && tbl.height >= dims.ht) return 0;

package/src/common/libm-trig.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * `cos`/`sin` as the native build host's libm computes them, at the only
+ * inputs Graphviz feeds with constant arguments: the corner angles
+ * 2π·(i ∓ 0.5)/8 of neatosplines.c's circumscribed ellipse 8-gon.
+ *
+ * V8's Math.sin/Math.cos are not correctly rounded everywhere, and the
+ * result depends on the CPU: at 9π/8 Node 22-26 on arm64 return
+ * -0.3826834323650896 (x64 and Node 20 return the correctly rounded value)
+ * where the reference libm (macOS arm64 libSystem) returns -0.38268343236508967.
+ * The ulp moves an obstacle corner off its node's centre line, which flips
+ * knife-edge triangulations in the multispline router. The table holds the
+ * host values for those nine angles (printed with `%a` by a clang -O2
+ * harness of the same expression, which also reproduces the oracle's
+ * makeObstacle vertices); any other input falls back to Math.cos/Math.sin.
+ *
+ * @see lib/neatogen/neatosplines.c:circumscribed_polygon_corner_about_ellipse
+ * @see docs/known-divergences.md (host libm)
+ */
+
+/** angle → [cos, sin] from the host libm, angles 2π·(k + 0.5)/8, k = -1..7. */
+const OCTAGON_TRIG: ReadonlyMap<number, readonly [number, number]> = new Map([
+  [-0.39269908169872414, [0.9238795325112867, -0.3826834323650898]],
+  [0.39269908169872414, [0.9238795325112867, 0.3826834323650898]],
+  [1.1780972450961724, [0.38268343236508984, 0.9238795325112867]],
+  [1.9634954084936207, [-0.3826834323650897, 0.9238795325112867]],
+  [2.748893571891069, [-0.9238795325112867, 0.3826834323650899]],
+  [3.5342917352885173, [-0.9238795325112868, -0.38268343236508967]],
+  [4.319689898685965, [-0.38268343236509034, -0.9238795325112865]],
+  [5.105088062083414, [0.38268343236509, -0.9238795325112866]],
+  [5.890486225480862, [0.9238795325112865, -0.3826834323650904]],
+] as const);
+
+/** libm `cos(x)` of the native build host (table above, else Math.cos). */
+export function libmCos(x: number): number {
+  return OCTAGON_TRIG.get(x)?.[0] ?? Math.cos(x);
+}
+
+/** libm `sin(x)` of the native build host (table above, else Math.sin). */
+export function libmSin(x: number): number {
+  return OCTAGON_TRIG.get(x)?.[1] ?? Math.sin(x);
+}

package/src/common/multicolor.ts

@@ -13,6 +13,10 @@
  * @see lib/common/emit.c:470 parseSegs
  */
 
+import { agerr, agerrorf, agwarningf } from './agerr.js';
+import type { Edge } from '../model/edge.js';
+import { registerRenderState } from './render-state.js';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -38,6 +42,28 @@ export interface ColorSeg {
 // Constants
 // ---------------------------------------------------------------------------
 
+/**
+ * C's `static atomic_flag warned` in parseSegs: set by the first Total-size
+ * warning or Illegal-value error in the process, silencing both afterwards.
+ * Reset per render (AD-4).
+ * @see lib/common/emit.c:470 parseSegs
+ */
+const parseSegsState = { warned: false };
+
+registerRenderState(() => {
+  parseSegsState.warned = false;
+});
+
+/** `atomic_flag_test_and_set(&warned)` negated: true when this call claimed it. */
+function claimWarned(): boolean {
+  if (parseSegsState.warned) return false;
+  parseSegsState.warned = true;
+  return true;
+}
+
+/** A claim that never fires: parses without touching or consuming the flag. */
+const claimNever = (): boolean => false;
+
 /** @see lib/common/emit.c:451 EPS */
 const EPS = 1e-5;
 
@@ -76,7 +102,7 @@ function appendSeg(
   token: string,
   left: number,
   segs: ColorSeg[],
-  warnedExceeded: { v: boolean },
+  claim: () => boolean,
 ): { left: number; rval: 0 | 3 } | null {
   const { color, v } = getSegLen(token);
   if (v < 0) return null;
@@ -85,10 +111,7 @@ function appendSeg(
   let rval: 0 | 3 = 0;
   const del = t - left;
   if (del > 0) {
-    if (!aeq0(del) && !warnedExceeded.v) {
-      warnedExceeded.v = true;
-      rval = 3;
-    }
+    if (!aeq0(del) && claim()) rval = 3;
     t = left;
   }
   left -= t;
@@ -128,34 +151,20 @@ function trimTrailing(segs: ColorSeg[]): void {
 // ---------------------------------------------------------------------------
 
 /**
- * Parse `"c1;f1:c2;f2:…"` into segments.
- *
- * Fractions are optional and non-negative; their sum must not exceed 1.
- * Segments without an explicit fraction share the remaining weight equally;
- * if none exist the remainder is added to the last segment.
- *
- * Return codes (mirror C):
- *   0 → ok; 1 → silent error; 2 → error with message; 3 → warning (sum > 1).
- * On rv 1 or 2 the returned segs array is empty.
- *
+ * The parse of `parseSegs` with the once-per-process flag abstracted as `claim`.
  * @see lib/common/emit.c:470 parseSegs
  */
-export function parseSegs(
+function scanSegs(
   colorlist: string,
+  claim: () => boolean,
 ): { segs: ColorSeg[]; error: 0 | 1 | 2 | 3 } {
   const segs: ColorSeg[] = [];
   let left = 1;
   let rval: 0 | 3 = 0;
-  let badFloatCount = 0;
-  const warnedExceeded = { v: false };
 
   for (const token of colorlist.split(':')) {
-    const result = appendSeg(token, left, segs, warnedExceeded);
-    if (result === null) {
-      const errCode: 1 | 2 = badFloatCount === 0 ? 2 : 1;
-      badFloatCount++;
-      return { segs: [], error: errCode };
-    }
+    const result = appendSeg(token, left, segs, claim);
+    if (result === null) return { segs: [], error: claim() ? 2 : 1 };
     if (result.rval === 3) rval = 3;
     left = result.left;
     if (aeq0(left)) { left = 0; break; }
@@ -165,3 +174,58 @@ export function parseSegs(
   trimTrailing(segs);
   return { segs, error: rval };
 }
+
+/**
+ * Parse `"c1;f1:c2;f2:…"` into segments.
+ *
+ * Fractions are optional and non-negative; their sum must not exceed 1.
+ * Segments without an explicit fraction share the remaining weight equally;
+ * if none exist the remainder is added to the last segment.
+ *
+ * Return codes (mirror C):
+ *   0 → ok; 1 → silent error; 2 → error with message; 3 → warning (sum > 1).
+ * On rv 1 or 2 the returned segs array is empty.
+ *
+ * The rv 2 error and rv 3 warning are printed here, once per process (the
+ * shared `warned` flag). C's callers then append an AGPREV line for rv > 1;
+ * `context` supplies it (e.g. `in edge a -> b`): the warning continues the
+ * same line as C's AGPREV does, the error's context follows on its own line.
+ *
+ * @see lib/common/emit.c:470 parseSegs
+ */
+export function parseSegs(
+  colorlist: string,
+  context?: () => string,
+): { segs: ColorSeg[]; error: 0 | 1 | 2 | 3 } {
+  const result = scanSegs(colorlist, claimWarned);
+  if (result.error === 3) {
+    const tail = context === undefined ? '' : context();
+    agwarningf(`Total size > 1 in "${colorlist}" color spec ${tail}`);
+  } else if (result.error === 2) {
+    agerrorf(`Illegal value in "${colorlist}" color attribute; float expected after ';'`);
+    if (context !== undefined) agerr('prev', context());
+  }
+  return result;
+}
+
+/**
+ * {@link parseSegs} for port-internal re-parses that have no C counterpart
+ * call (pre-passes, parallel edges): same segments and error class, but never
+ * prints and never consumes the once-per-process flag.
+ */
+export function parseSegsSilent(
+  colorlist: string,
+): { segs: ColorSeg[]; error: 0 | 1 | 2 | 3 } {
+  return scanSegs(colorlist, claimNever);
+}
+
+/**
+ * The AGPREV line C's `multicolor` appends for an rv > 1 parseSegs.
+ * @see lib/common/emit.c:1985 multicolor
+ */
+export function edgeSegsContext(e: Edge): () => string {
+  return () => {
+    const directed = !e.tail.root.kind.endsWith('undirected');
+    return `in edge ${e.tail.name}${directed ? ' -> ' : ' -- '}${e.head.name}`;
+  };
+}