@knowvah/dot-engine 2.6.9 → 2.6.11

package/package.json

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

package/src/common/html-entities.ts

@@ -260,40 +260,92 @@ export const HTML_ENTITIES: Readonly<Record<string, number>> = {
   "zwnj": 8204,
 };
 
-/** The five basic XML/HTML entities → code point. */
-const BASIC_ENTITIES: Readonly<Record<string, number>> = {
-  amp: 0x26, lt: 0x3c, gt: 0x3e, quot: 0x22, apos: 0x27,
-};
+/**
+ * Longest name htmlEntity looks up: its scan for the `;` stops after this
+ * many characters.
+ * @see lib/common/entities.h:ENTITY_NAME_LENGTH_MAX
+ */
+const ENTITY_NAME_LENGTH_MAX = 8;
 
-/** Decode a numeric entity body (`#123`, `#x1F`) to its code point, or null. */
-function numericEntityValue(body: string): number | null {
-  const hex = body[1] === 'x' || body[1] === 'X';
-  const v = hex ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
-  return Number.isFinite(v) && v > 0 && v <= 0x10ffff ? v : null;
+/** htmlEntity's result: the value (0 for none) and where scanning resumes. */
+interface EntityScan {
+  value: number;
+  next: number;
+}
+
+/**
+ * The `#` branch of htmlEntity, `at` on the `#`. It reads up to six decimal
+ * or five hex digits (`x` or `X`); the `;` must come within the first eight
+ * characters, else nothing is consumed. A `;` right after the digits, even
+ * none, is consumed with value `n`, so `&#;` keeps its `&` and loses `#;`.
+ * @see lib/common/utils.c:htmlEntity
+ */
+function numericEntity(s: string, at: number): EntityScan {
+  const hex = s[at + 1] === 'x' || s[at + 1] === 'X';
+  const digit = hex ? /^[0-9A-Fa-f]$/ : /^[0-9]$/;
+  let n = 0;
+  let i = hex ? 2 : 1;
+  for (; i < 8; i++) {
+    const c = s[at + i] ?? '';
+    if (!digit.test(c)) break;
+    n = n * (hex ? 16 : 10) + parseInt(c, 16);
+  }
+  if (i < 8 && s[at + i] === ';') return { value: n, next: at + i + 1 };
+  return { value: 0, next: at };
+}
+
+/**
+ * The name branch of htmlEntity, `at` on the first name character: a `;`
+ * within ENTITY_NAME_LENGTH_MAX characters ends a name looked up in
+ * entities.h (case-sensitive; no `apos`).
+ * @see lib/common/utils.c:htmlEntity
+ */
+function namedEntity(s: string, at: number): EntityScan {
+  for (let i = 0; i < ENTITY_NAME_LENGTH_MAX; i++) {
+    const c = s[at + i];
+    if (c === undefined || c === '\0') break;
+    if (c === ';') {
+      const key = s.slice(at, at + i);
+      if (Object.hasOwn(HTML_ENTITIES, key)) return { value: HTML_ENTITIES[key]!, next: at + i + 1 };
+      break;
+    }
+  }
+  return { value: 0, next: at };
 }
 
 /**
- * Decode one entity body (`amp`, `alpha`, `#123`, `#x1F`) to its code point, or
- * null for an unknown name. Named entities cover the five basic XML entities
- * plus the full HTML 4 table (Symbol etc.). @see lib/common/utils.c:htmlEntity
+ * Check for an HTML entity at `at`, the character after an `&`.
+ * @see lib/common/utils.c:htmlEntity
  */
-function entityValue(body: string): number | null {
-  if (body[0] === '#') return numericEntityValue(body);
-  return BASIC_ENTITIES[body] ?? HTML_ENTITIES[body] ?? null;
+function htmlEntity(s: string, at: number): EntityScan {
+  return s[at] === '#' ? numericEntity(s, at) : namedEntity(s, at);
 }
 
 /**
- * Decode XML/numeric (&#NNN; / &#xHH;) and HTML 4 named (`&alpha;`) entities to
- * their characters, leaving unknown names literal — C's make_label UTF-8 branch.
- * Latin-1 inputs are decoded at the byte->string boundary by the caller (the
- * survey's render-one), so this UTF-8 branch covers them too.
- * @see lib/common/utils.c:htmlEntityUTF8 / htmlEntity
+ * Substitute entities like `&#123;` and `&amp;` with their characters: C's
+ * make_label UTF-8 branch. An `&` whose entity has no value stays (scanning
+ * resumes where htmlEntity left it). Latin-1 inputs are decoded at the
+ * byte->string boundary by the caller (the survey's render-one), so this
+ * covers them too, as does latin1ToUTF8's identical entity handling.
+ *
+ * C appends a value's bytes itself: below 0x7F one byte, below 0x7FF two,
+ * else three, truncated to `char`. For every value whose bytes are valid
+ * UTF-8 that is the character itself. 0x7F, 0x7FF, surrogates and values
+ * above 0xFFFF come out as invalid UTF-8, which a JS string cannot hold; the
+ * port keeps the character there (documented divergence).
+ * @see lib/common/utils.c:htmlEntityUTF8
+ * @see lib/common/utils.c:latin1ToUTF8
  * @see lib/common/labels.c:make_label (CHAR_LATIN1 vs default)
  */
 export function htmlEntityUTF8(s: string): string {
-  if (s.indexOf('&') < 0) return s;
-  return s.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[A-Za-z]+);/g, (m, body: string) => {
-    const v = entityValue(body);
-    return v === null ? m : String.fromCodePoint(v);
-  });
+  let amp = s.indexOf('&');
+  if (amp < 0) return s;
+  let out = '';
+  let from = 0;
+  for (; amp >= 0; amp = s.indexOf('&', from)) {
+    const e = htmlEntity(s, amp + 1);
+    out += s.slice(from, amp) + (e.value ? String.fromCodePoint(e.value) : '&');
+    from = e.next;
+  }
+  return out + s.slice(from);
 }

package/src/common/htmltable-emit-fill.ts

@@ -18,7 +18,7 @@ import { FillType, PenType } from '../gvc/context.js';
 import { transformPoint } from '../gvc/device.js';
 import { resolveRenderColor } from '../render/color-resolve.js';
 import { emitRoundedBezier } from './poly-shapes.js';
-import { parseStyleFlags } from './style-resolve.js';
+import { htmlStyle } from './htmltable-style.js';
 import {
   BORDER_LEFT,
   BORDER_TOP,
@@ -94,7 +94,7 @@ export interface HtmlPaint {
   pen?: string;
   /** Pen width; default 1.0 (omitted from SVG at 1.0). */
   penWidth?: number;
-  /** Style string; "dashed"/"dotted" map to the pen type. */
+  /** HTML STYLE string; its dashed/dotted flags map to the pen type. */
   penStyle?: string;
   /**
    * Second/stop color of a gradient fill. Presence switches the fill from
@@ -137,10 +137,11 @@ export function resetHtmlFillPenWidth(): void {
   htmlFillPen = 1.0;
 }
 
-/** Map a style string to the C pen type. @see lib/common/htmltable.c:doBorder */
+/** Map an HTML STYLE to the C pen type: dashed wins over dotted. @see lib/common/htmltable.c:doBorder */
 function penTypeOf(style: string | undefined): PenType {
-  if (style !== undefined && style.includes('dashed')) return PenType.Dashed;
-  if (style !== undefined && style.includes('dotted')) return PenType.Dotted;
+  const st = htmlStyle(style);
+  if (st.dashed) return PenType.Dashed;
+  if (st.dotted) return PenType.Dotted;
   return PenType.Solid;
 }
 
@@ -277,7 +278,7 @@ export function doBorder(
   // value persists and leaks into the next bgcolor fill's stroke-width.
   htmlFillPen = border;
   withHtmlPaint({ pen: color, penWidth: border, penStyle: style }, job, () => {
-    if (parseStyleFlags(style).rounded) {
+    if (htmlStyle(style).rounded) {
       // C: round_corners(job, mkPts(AF,b,border), 4, {rounded}, 0) — unfilled
       // rounded border path; emitRoundedBezier transforms the AF ring itself.
       emitRoundedBezier(mkPts(box, border, pos), { x: 0, y: 0 }, false, { renderer, job });

package/src/common/htmltable-emit.ts

@@ -35,7 +35,7 @@ import {
   htmlFillPenWidth, resetHtmlFillPenWidth, type HtmlPaint,
 } from './htmltable-emit-fill.js';
 import { emitRoundedBezier } from './poly-shapes.js';
-import { parseStyleFlags } from './style-resolve.js';
+import { htmlStyle } from './htmltable-style.js';
 import { emitHtmlRules, initHtmlAnchor, endHtmlAnchor, htmlObjImgscale } from './htmltable-emit-rules.js';
 
 export type { PlacedHtml, PlacedCell, PlacedLine, PlacedImage };
@@ -125,7 +125,7 @@ function bgFillPaint(ctx: BgFillCtx): HtmlPaint {
   if (spec === null) return { fill: ctx.bgcolor, penWidth };
   return {
     fill: spec[0], stop: spec[1], gradientAngle: ctx.gradientangle ?? 0,
-    radial: ctx.style !== undefined && ctx.style.includes('radial'), penWidth,
+    radial: htmlStyle(ctx.style).radial, penWidth,
   };
 }
 
@@ -139,7 +139,7 @@ function bgFillPaint(ctx: BgFillCtx): HtmlPaint {
 function emitBgFill(ctx: BgFillCtx): void {
   const { box, pos, border, renderer, job } = ctx;
   withHtmlPaint(bgFillPaint(ctx), job, () => {
-    if (parseStyleFlags(ctx.style).rounded) {
+    if (htmlStyle(ctx.style).rounded) {
       emitRoundedBezier(mkPts(box, border, pos), { x: 0, y: 0 }, true, { renderer, job });
       return;
     }
@@ -258,23 +258,6 @@ export function emitHtmlImg(
  *
  * @see lib/common/htmltable.c:emit_html_cell
  */
-/**
- * True when an HTML element's STYLE declares it invisible.
- *
- * HTML STYLE is lexed by its OWN parser, not the node/edge one: tokens are
- * split on space or comma, compared case-insensitively, and BOTH "INVIS" and
- * "INVISIBLE" set the flag. (The node/edge parser splits on comma only and
- * matches exact-case, so it cannot be reused here.)
- * @see lib/common/htmllex.c:168 (DELIM " ,", strview_case_str_eq)
- */
-function htmlStyleInvisible(style: string | undefined): boolean {
-  if (style === undefined) return false;
-  return style.split(/[ ,]+/).some((tok) => {
-    const t = tok.toUpperCase();
-    return t === 'INVIS' || t === 'INVISIBLE';
-  });
-}
-
 export function emitHtmlCell(
   cell: PlacedCell,
   pos: Point,
@@ -287,7 +270,7 @@ export function emitHtmlCell(
   );
   // An invisible cell emits no fill, no border and no content — only the
   // anchor, which C opens before the gate. @see htmltable.c:emit_html_cell:643
-  if (htmlStyleInvisible(cell.style)) {
+  if (htmlStyle(cell.style).invisible) {
     if (inAnchor) endHtmlAnchor(renderer, job);
     return;
   }
@@ -354,7 +337,7 @@ export function emitHtmlLabel(
   const inAnchor = clustersLast ? false : initHtmlAnchor(anchorData, tblBox, renderer, job);
   // An invisible TABLE suppresses its fill, ALL its cells, and its rules and
   // border — the whole block C guards at emit_html_tbl:542.
-  const tblInvisible = htmlStyleInvisible(placed.style);
+  const tblInvisible = htmlStyle(placed.style).invisible;
   if (!tblInvisible) {
     if (placed.bgcolor !== undefined) {
       emitBgFill({ bgcolor: placed.bgcolor, box: placed.box, pos, border: placed.border,

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

@@ -12,7 +12,8 @@
  * @see lib/common/htmllex.c:characterData
  */
 
-import { htmlEntityUTF8 } from './html-entities.js';
+import { HTML_ENTITIES } from './html-entities.js';
+import { charRefNumber } from './htmltable-lex-attvalue.js';
 import type { TagChunk } from './htmltable-lex-expat.js';
 import type { Token } from './htmltable-types.js';
 
@@ -77,15 +78,48 @@ function cleanText(decoded: string) {
   return decoded.replace(/[\x00-\x1f]/g, '');
 }
 
+/** expat's predefined entities: no DTD declares others. */
+const XML_PREDEFINED: Readonly<Record<string, string>> = { lt: '<', gt: '>', amp: '&', quot: '"', apos: "'" };
+
+/** Shortest and longest name scanEntity looks up. @see lib/common/utils.c:scanEntity */
+const SCAN_ENTITY_MIN = 2;
+const SCAN_ENTITY_MAX = 8;
+
+const TEXT_REF = /&(#x[0-9A-Fa-f]+|#[0-9]+|[^&;]+);/g;
+
+/** One reference of a text run, as scanEntity then expat leave it. */
+function textRefValue(ref: string, body: string): string {
+  if (body[0] === '#') {
+    const v = charRefNumber(ref);
+    return v < 0 ? ref : String.fromCodePoint(v);
+  }
+  const n = body.length;
+  if (n >= SCAN_ENTITY_MIN && n <= SCAN_ENTITY_MAX && Object.hasOwn(HTML_ENTITIES, body)) {
+    return String.fromCodePoint(HTML_ENTITIES[body]!);
+  }
+  return Object.hasOwn(XML_PREDEFINED, body) ? XML_PREDEFINED[body]! : ref;
+}
+
+/**
+ * The characters expat hands characterData for a text run: scanEntity first
+ * rewrites each entities.h name to `&#N;` (its `&` only when no `#` follows),
+ * then expat decodes character references, of any length, and its five
+ * predefined entities. Runs expat rejects never get here (textRefError).
+ * @see lib/common/htmllex.c:findNext
+ * @see lib/common/utils.c:scanEntity
+ */
+export function decodeTextRefs(raw: string): string {
+  return raw.indexOf('&') < 0 ? raw : raw.replace(TEXT_REF, textRefValue);
+}
+
 /** The text token of a text run, if anything is left after cleaning. */
 export function textTokens(raw: string): Token[] {
-  // Decode XML/HTML entities in the text run. C's HTML lexer resolves entities
-  // via expat during tokenization (htmllex.c), so both sizing and emit see the
-  // decoded UTF-8 text. Skipping this measured the raw "&#91;el..." (9-10 chars)
-  // instead of "[el..." (6 chars), inflating edge-label vnodes and shifting
-  // layout (corpus 1949: +18.7px). Plain-string labels already decode via the
-  // make_label path, so only HTML-delimited labels diverged.
-  return charDataTokens(htmlEntityUTF8(raw));
+  // C's HTML lexer resolves entities via scanEntity and expat during
+  // tokenization (htmllex.c), so both sizing and emit see the decoded text.
+  // Skipping this measured the raw "&#91;el..." (9-10 chars) instead of
+  // "[el..." (6 chars), inflating edge-label vnodes and shifting layout
+  // (corpus 1949: +18.7px).
+  return charDataTokens(decodeTextRefs(raw));
 }
 
 /** characterData on what expat decoded: a T_string when any character survives. */

package/src/common/htmltable-style.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * The HTML STYLE flags. C's stylefn sets an htmlstyle_t bitfield at lex time;
+ * the port keeps the legal tokens as a string (htmltable-attr-warn.ts joins
+ * them with ' ') and reads the flags back here, token by token in order, so
+ * SOLID still clears only the DOTTED/DASHED before it. HTML STYLE is not the
+ * node/edge style: tokens split on space or comma and compare
+ * case-insensitively, so `parseStyleFlags` cannot read it.
+ *
+ * @see lib/common/htmltable.h:htmlstyle_t
+ * @see lib/common/htmllex.c:stylefn (DELIM " ,", strview_case_str_eq)
+ */
+
+/** @see lib/common/htmltable.h:htmlstyle_t */
+export interface HtmlStyle {
+  radial: boolean;
+  rounded: boolean;
+  invisible: boolean;
+  dotted: boolean;
+  dashed: boolean;
+}
+
+/** Read the htmlstyle_t flags from a kept HTML STYLE string. */
+export function htmlStyle(style: string | undefined): HtmlStyle {
+  const s: HtmlStyle = { radial: false, rounded: false, invisible: false, dotted: false, dashed: false };
+  if (style === undefined) return s;
+  for (const tk of style.split(/[ ,]+/)) {
+    switch (tk.toUpperCase()) {
+      case 'ROUNDED': s.rounded = true; break;
+      case 'RADIAL': s.radial = true; break;
+      case 'SOLID': s.dotted = false; s.dashed = false; break;
+      case 'INVISIBLE': case 'INVIS': s.invisible = true; break;
+      case 'DOTTED': s.dotted = true; break;
+      case 'DASHED': s.dashed = true; break;
+    }
+  }
+  return s;
+}