@knowvah/dot-engine 0.1.0

package/src/common/htmltable-pos.ts

@@ -0,0 +1,601 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * HTML label positioning: converts a sized HtmlLabel into a placed
+ * structure with cell boxes and text baselines relative to the label
+ * center, mirroring pos_html_tbl / pos_html_cell / emit_htextspans
+ * geometry.
+ *
+ * Decoration metadata (bgcolor, color, sides, href, title, target, id,
+ * style, vruled, hruled, col, row, colspan, rowspan) is carried directly
+ * on PlacedCell/PlacedHtml — matching C's htmlcell_t/htmltbl_t layout.
+ *
+ * @see lib/common/htmltable.c:pos_html_tbl
+ * @see lib/common/htmltable.c:pos_html_cell
+ * @see lib/common/htmltable.c:emit_htextspans
+ */
+
+import type { Box } from '../model/geom.js';
+import type { TextlabelT } from './types.js';
+import type { TextMeasurer } from './textmeasure.js';
+import type { HtmlCell, HtmlImage, HtmlLabel, HtmlTable, HtmlText, ImageSizer } from './htmltable-types.js';
+import { layoutHtmlTable, cellPad, cellBorder, sizeHtmlLabel, parseHtmlLabel } from './htmltable.js';
+import { makeLabel } from './make-label.js';
+import { TOP, BOTTOM, LEFT, RIGHT } from './splines-constants.js';
+import type { PlacedLine, HtmlFontInfo } from './htmltable-pos-runs.js';
+import {
+  itemFontFlags, buildLineRuns, runsAreSimple, placeRunItems, placeTextRuns,
+} from './htmltable-pos-runs.js';
+
+// Re-export the text-run layout API (moved to htmltable-pos-runs.ts) so existing
+// importers of './htmltable-pos.js' keep working unchanged.
+export type { PlacedLine, HtmlFontInfo };
+export { itemFontFlags, buildLineRuns, runsAreSimple, placeRunItems, placeTextRuns };
+
+/**
+ * A placed IMG element inside a cell.
+ * Carries the sized box (relative to label center) and scale attribute.
+ *
+ * Geometry: emit_html_img centers the image in the cell box, applying scale.
+ * @see lib/common/htmltable.c:emit_html_img (line 597)
+ */
+export interface PlacedImage {
+  src: string;
+  /** Scale attribute from <IMG SCALE="..."/>. */
+  scale?: string;
+  /** Intrinsic image width (from the ImageSizer), pre-scale. */
+  iw: number;
+  /** Intrinsic image height (from the ImageSizer), pre-scale. */
+  ih: number;
+  /** Target box for the image (alignment-adjusted cell content area). */
+  box: Box;
+}
+
+/**
+ * A positioned cell: border box plus its text runs and optional image.
+ * Carries decoration metadata from htmlcell_t so the emitter can apply
+ * bgcolor fill, per-side borders, anchors, and rules without a separate
+ * decorated type.
+ *
+ * @see lib/common/htmltable.h:htmlcell_t
+ */
+export interface PlacedCell {
+  box: Box;
+  border: number;
+  lines: PlacedLine[];
+  /** Placed image, present when the cell contains an <IMG> element. */
+  image?: PlacedImage;
+  /**
+   * Placed nested table, present when the cell's child is a <TABLE>.
+   * @see lib/common/htmltable.h:htmlcell_t.child (HTML_TBL)
+   */
+  nested?: PlacedHtml;
+  /** PORT name on this cell, for html_port edge resolution. */
+  port?: string;
+  /** Boundary mask (C `sides & mask`): which node sides this cell touches. */
+  sidesMask?: number;
+  /** BGCOLOR attribute (solid color or "color1:color2" gradient spec). */
+  bgcolor?: string;
+  /** Pen (border) color override. */
+  color?: string;
+  /** SIDES bitmask (BORDER_LEFT|TOP|RIGHT|BOTTOM). */
+  sides?: number;
+  /** HREF for this cell's anchor. */
+  href?: string;
+  /** TOOLTIP for this cell's anchor. */
+  title?: string;
+  /** TARGET for this cell's anchor. */
+  target?: string;
+  /** ID attribute. */
+  id?: string;
+  /** Style string (dashed, dotted, rounded, …). */
+  style?: string;
+  /** Gradient angle (deg) for a gradient bgcolor. @see htmltable.h:htmlcell_t */
+  gradientangle?: number;
+  /** Column index (0-based). @see lib/common/htmltable.h:htmlcell_t.col */
+  col: number;
+  /** Row index (0-based). @see lib/common/htmltable.h:htmlcell_t.row */
+  row: number;
+  /** Column span (≥1). */
+  colspan: number;
+  /** Row span (≥1). */
+  rowspan: number;
+  /**
+   * True when this cell has a vertical rule to its right.
+   * Set by table vrule (COLUMNS="*") or explicit <VR/> in the row.
+   * @see lib/common/htmltable.h:htmlcell_t.vruled
+   */
+  vruled?: boolean;
+  /**
+   * True when this cell has a horizontal rule below it.
+   * Set by table hrule (ROWS="*") propagated via row_t.ruled.
+   * @see lib/common/htmltable.h:htmlcell_t.hruled
+   */
+  hruled?: boolean;
+}
+
+/**
+ * A fully positioned HTML label (table).
+ * Carries table-level decoration metadata from htmltbl_t.
+ *
+ * @see lib/common/htmltable.h:htmltbl_t
+ */
+export interface PlacedHtml {
+  box: Box;
+  border: number;
+  cells: PlacedCell[];
+  /** PORT name on this table, for html_port edge resolution. */
+  port?: string;
+  /** Boundary mask placed with (ALL top-level; parent cell mask if nested). */
+  boundarySides?: number;
+  /** BGCOLOR attribute for the table background. */
+  bgcolor?: string;
+  /** Pen color for the table border. */
+  color?: string;
+  /** SIDES bitmask. */
+  sides?: number;
+  /** Table HREF anchor. */
+  href?: string;
+  /** Table TOOLTIP. */
+  title?: string;
+  /** Table TARGET. */
+  target?: string;
+  /** Table ID. */
+  id?: string;
+  /** Table style string. */
+  style?: string;
+  /** Gradient angle (deg) for a gradient bgcolor. @see htmltable.h:htmltbl_t */
+  gradientangle?: number;
+  /**
+   * Total number of columns (used for vruled boundary check).
+   * @see lib/common/htmltable.h:htmltbl_t.column_count
+   */
+  columnCount: number;
+  /**
+   * Total number of rows (used for hruled boundary check).
+   * @see lib/common/htmltable.h:htmltbl_t.row_count
+   */
+  rowCount: number;
+  /**
+   * Cell spacing (cellspacing attribute or default).
+   * @see lib/common/htmltable.h:htmldata_t.space
+   */
+  spacing: number;
+}
+
+/**
+ * Shrink `box` to (w,h) per the cell's HALIGN/VALIGN, mirroring C's text branch
+ * of pos_html_cell: LEFT flushes the box right edge in (`ur.x -= delx`), RIGHT
+ * flushes the left edge in, default splits (center); VALIGN BOTTOM/TOP flush,
+ * default centers on BOTH axes. Parallels the existing `alignImageBox`, but
+ * text default-centers vertically where an image does not.
+ * (`parseAlign` never yields HALIGN_TEXT, so the cell box always shrinks here —
+ * exactly what C does for every non-TEXT cell.)
+ * @see lib/common/htmltable.c:pos_html_cell (text branch, :1487-1526)
+ */
+export function alignContentBox(box: Box, cell: HtmlCell, w: number, h: number): Box {
+  const out: Box = { ll: { ...box.ll }, ur: { ...box.ur } };
+  const delx = out.ur.x - out.ll.x - w;
+  if (delx > 0) {
+    if (cell.align === 'left') out.ur.x -= delx;
+    else if (cell.align === 'right') out.ll.x += delx;
+    else { out.ll.x += delx / 2; out.ur.x -= delx / 2; }
+  }
+  const dely = out.ur.y - out.ll.y - h;
+  if (dely > 0) {
+    if (cell.valign === 'bottom') out.ur.y -= dely;
+    else if (cell.valign === 'top') out.ll.y += dely;
+    else { out.ll.y += dely / 2; out.ur.y -= dely / 2; }
+  }
+  return out;
+}
+
+/** All four boundary sides — the top-level table's placement mask. */
+export const HTML_ALL_SIDES = TOP | BOTTOM | LEFT | RIGHT;
+
+/** Cell placement context: geometry + grid position, used by placeCell. */
+export interface CellPlaceCtx {
+  cell: HtmlCell;
+  tbl: HtmlTable;
+  box: Box;
+  finfo: HtmlFontInfo;
+  measurer: TextMeasurer;
+  col: number;
+  row: number;
+  colspan: number;
+  rowspan: number;
+  /** Boundary mask for this cell (C `sides & mask`). */
+  sidesMask: number;
+}
+
+/** Place text runs for a cell, returning the inset content box. */
+function placeCellRuns(
+  ctx: CellPlaceCtx,
+): PlacedLine[] {
+  const { cell, tbl, box, finfo, measurer } = ctx;
+  const border = cellBorder(cell, tbl);
+  const inset = border + cellPad(cell, tbl);
+  const cbox: Box = {
+    ll: { x: box.ll.x + inset, y: box.ll.y + inset },
+    ur: { x: box.ur.x - inset, y: box.ur.y - inset },
+  };
+  const texts = cell.content.filter((c): c is HtmlText => c.kind === 'text');
+  const runs = buildLineRuns(texts, finfo, measurer);
+  // pos_html_txt (htmltable.c:1541): each line whose justification is still
+  // UNSET_ALIGN inherits the cell's BALIGN default (BALIGN_MASK →
+  // 'l'/'r'/'n'). A BR with an explicit ALIGN already set run.just; only the
+  // unset ones fall through here. BALIGN center/absent is 'n' (leave centered),
+  // so only left/right override — matching balignfn (htmllex.c:350), which
+  // sets the flag for LEFT/RIGHT only. Without this a BALIGN="LEFT" cell's
+  // multi-line text centered each line instead of flushing left (2619_1/2).
+  if (cell.balign === 'left' || cell.balign === 'right') {
+    for (const r of runs) if (r.just === undefined) r.just = cell.balign;
+  }
+  const w = Math.max(...runs.map(r => r.width), 0);
+  // Block height for vertical centering must equal size_html_txt's box.UR.y:
+  // a single line uses its measured height (mxysize); a multi-line block sums
+  // lsize, which is the measured height for a "simple" block but the raw max
+  // font size (mxfsize) for a non-simple one (any line with >1 item, font
+  // flags, or mixed faces/sizes). placeComplexRuns already advances baselines
+  // by fontSize, so centering must use the same height or the block is
+  // mis-centered — e.g. 2619 I63's card, whose "Male" line carries a trailing
+  // 14pt space, was centered 1.5pt too high.
+  // @see lib/common/htmltable.c:size_html_txt (lsize = simple ? mxysize : mxfsize)
+  const simple = runs.length === 1 || runsAreSimple(runs, finfo);
+  const h = runs.reduce((a, r) => a + (simple ? r.height : r.fontSize), 0);
+  return placeTextRuns(runs, alignContentBox(cbox, cell, w, h), finfo, measurer);
+}
+
+/**
+ * Build the placed image for a cell containing an <IMG> element.
+ *
+ * The target box is the inset content area, shrunk per the cell's
+ * halign/valign exactly as pos_html_cell's image branch does
+ * ("alignment trumps scaling"); the default alignment leaves the full
+ * content box, and emission centers/scales the intrinsic image within
+ * it (gvrender_usershape with imagepos "mc").
+ *
+ * @see lib/common/htmltable.c:pos_html_cell (image branch, :1456-1486)
+ */
+function placeCellImage(cell: HtmlCell, tbl: HtmlTable, box: Box): PlacedImage | undefined {
+  const img = cell.content.find((c): c is HtmlImage => c.kind === 'image');
+  if (img === undefined) return undefined;
+  const inset = cellBorder(cell, tbl) + cellPad(cell, tbl);
+  const iw = img.width ?? 0;
+  const ih = img.height ?? 0;
+  const cbox: Box = {
+    ll: { x: box.ll.x + inset, y: box.ll.y + inset },
+    ur: { x: box.ur.x - inset, y: box.ur.y - inset },
+  };
+  alignImageBox(cbox, cell, iw, ih);
+  return { src: img.src, scale: img.scale, iw, ih, box: cbox };
+}
+
+/**
+ * Shrink the content box per the cell's halign/valign so the intrinsic
+ * image sits flush ("alignment trumps scaling"); default alignment is a
+ * no-op. @see lib/common/htmltable.c:pos_html_cell (image branch)
+ */
+function alignImageBox(cbox: Box, cell: HtmlCell, iw: number, ih: number): void {
+  const delx = cbox.ur.x - cbox.ll.x - iw;
+  if (delx > 0) {
+    if (cell.align === 'left') cbox.ur.x -= delx;
+    else if (cell.align === 'right') cbox.ll.x += delx;
+  }
+  const dely = cbox.ur.y - cbox.ll.y - ih;
+  if (dely > 0) {
+    if (cell.valign === 'bottom') cbox.ur.y -= dely;
+    else if (cell.valign === 'top') cbox.ll.y += dely;
+  }
+}
+
+/** Position a nested <TABLE> child inside the cell's inset content box.
+ * @see lib/common/htmltable.c:pos_html_cell (HTML_TBL branch) */
+function placeCellNested(ctx: CellPlaceCtx): PlacedHtml | undefined {
+  const { cell, tbl, box, finfo, measurer, sidesMask } = ctx;
+  const nested = cell.content.find((c): c is HtmlTable => c.kind === 'table');
+  if (nested === undefined) return undefined;
+  const inset = cellBorder(cell, tbl) + cellPad(cell, tbl);
+  const cbox: Box = {
+    ll: { x: box.ll.x + inset, y: box.ll.y + inset },
+    ur: { x: box.ur.x - inset, y: box.ur.y - inset },
+  };
+  return posHtmlTable(nested, finfo, measurer, cbox, sidesMask);
+}
+
+/** Position one cell's text inside its box, copying decoration metadata. @see pos_html_cell */
+export function placeCell(ctx: CellPlaceCtx): PlacedCell {
+  const { cell, tbl, box, col, row, colspan, rowspan } = ctx;
+  const border = cellBorder(cell, tbl);
+  // vruled is fully resolved at parse time (setCell for COLUMNS="*",
+  // "cells VR cell" for explicit <VR>); copy it through.
+  // @see lib/common/htmlparse.y:329,434-435
+  const vruled = cell.vruled;
+  const nested = placeCellNested(ctx);
+  const image = nested === undefined ? placeCellImage(cell, tbl, box) : undefined;
+  return {
+    box, border,
+    lines: nested === undefined ? placeCellRuns(ctx) : [],
+    image,
+    nested,
+    port: cell.port,
+    sidesMask: ctx.sidesMask,
+    bgcolor: cell.bgcolor,
+    color: cell.color,
+    sides: cell.sides,
+    href: cell.href,
+    title: cell.title,
+    target: cell.target,
+    id: cell.id,
+    style: cell.style,
+    gradientangle: cell.gradientangle,
+    col, row, colspan, rowspan,
+    vruled,
+    // hruled set post-construction in posHtmlTable from hrule propagation
+  };
+}
+
+/**
+ * Distribute extra box space evenly across the column/row sizes, mirroring
+ * C's literal arithmetic: `extra = del / count` (fractional) plus a ROUND()ed
+ * remainder handed out 1pt to the first `plus` slots (≈0 under double
+ * division; kept for bit-fidelity). @see lib/common/htmltable.c:1602-1617
+ */
+function distributeExtra(sizes: number[], del: number, count: number): number[] {
+  if (del <= 0 || count <= 0) return sizes;
+  const extra = del / count;
+  const r = del - extra * count;
+  const plus = r >= 0 ? Math.floor(r + 0.5) : Math.ceil(r - 0.5); // C ROUND
+  return sizes.map((w, i) => w + extra + (i < plus ? 1 : 0));
+}
+
+/** Compute column X-offsets from layout widths. */
+function buildColX(pos: Box, border: number, spacing: number, widths: number[]): number[] {
+  const colX: number[] = [];
+  let x = pos.ll.x + border + spacing;
+  for (let i = 0; i < widths.length; i++) { colX[i] = x; x += widths[i] + spacing; }
+  return colX;
+}
+
+/** Compute row Y-offsets from layout heights. */
+function buildRowY(pos: Box, border: number, spacing: number, heights: number[]): number[] {
+  const rowY: number[] = [];
+  let y = pos.ur.y - border - spacing;
+  for (let i = 0; i < heights.length; i++) { rowY[i] = y; y -= heights[i] + spacing; }
+  return rowY;
+}
+
+/** Build table-level decoration fields from htmltbl_t. */
+function tblDecoration(tbl: HtmlTable): Partial<PlacedHtml> {
+  return {
+    bgcolor: tbl.bgcolor,
+    color: tbl.color,
+    sides: tbl.sides,
+    href: tbl.href,
+    title: tbl.title,
+    target: tbl.target,
+    id: tbl.id,
+    style: tbl.style,
+    gradientangle: tbl.gradientangle,
+  };
+}
+
+/** Context for placeCells, grouping grid and font state. */
+interface PlaceCellsCtx {
+  tbl: HtmlTable;
+  entries: ReturnType<typeof layoutHtmlTable>['entries'];
+  colX: number[];
+  rowY: number[];
+  spacing: number;
+  ncols: number;
+  nrows: number;
+  sides: number;
+  finfo: HtmlFontInfo;
+  measurer: TextMeasurer;
+}
+
+/** Cell boundary mask: outer sides it touches AND inherited `sides`. */
+function cellSidesMask(
+  e: { col: number; row: number; colspan: number; rowspan: number },
+  ncols: number, nrows: number, sides: number,
+): number {
+  if (sides === 0) return 0;
+  let mask = 0;
+  if (e.col === 0) mask |= LEFT;
+  if (e.row === 0) mask |= TOP;
+  if (e.col + e.colspan === ncols) mask |= RIGHT;
+  if (e.row + e.rowspan === nrows) mask |= BOTTOM;
+  return sides & mask;
+}
+
+/**
+ * Mark hruled cells: C processTbl sets bit r+1 for each row with
+ * ruled=true, then any cell whose bottom edge (row + rowspan) lands on
+ * a set bit becomes hruled. The bottom-boundary draw guard lives at
+ * emit time (htmltable.c:488), as in C.
+ * @see lib/common/htmltable.c:processTbl (bitarray, :1199-1224)
+ */
+function ruledBoundaries(tbl: HtmlTable): Set<number> {
+  const bits = new Set<number>();
+  tbl.rows.forEach((row, r) => { if (row.ruled === true) bits.add(r + 1); });
+  return bits;
+}
+
+/** Place all cells for a table, marking ruled cells per C processTbl. */
+function placeCells(ctx: PlaceCellsCtx): PlacedCell[] {
+  const { tbl, entries, colX, rowY, spacing, ncols, nrows, sides, finfo, measurer } = ctx;
+  const boundaries = ruledBoundaries(tbl);
+  return entries.map((e) => {
+    const box: Box = {
+      ll: { x: colX[e.col], y: rowY[e.row + e.rowspan] + spacing },
+      ur: { x: colX[e.col + e.colspan] - spacing, y: rowY[e.row] },
+    };
+    const placed = placeCell({
+      cell: e.cell, tbl, box, finfo, measurer,
+      col: e.col, row: e.row, colspan: e.colspan, rowspan: e.rowspan,
+      sidesMask: cellSidesMask(e, ncols, nrows, sides),
+    });
+    if (boundaries.has(e.row + e.rowspan)) placed.hruled = true;
+    return placed;
+  });
+}
+
+/**
+ * Position the table and all cells within `pos`. The top-level caller omits
+ * `pos` (the table is centered on its own dimen); a nested table is positioned
+ * into its parent cell's inset content box. @see pos_html_tbl
+ */
+export function posHtmlTable(
+  tbl: HtmlTable,
+  finfo: HtmlFontInfo,
+  measurer: TextMeasurer,
+  pos?: Box,
+  sides: number = HTML_ALL_SIDES,
+): PlacedHtml {
+  const dim = tbl.dimen ?? { w: 0, h: 0 };
+  const box: Box = pos !== undefined
+    ? { ll: { ...pos.ll }, ur: { ...pos.ur } } // clone: the align step below mutates
+    : {
+        ll: { x: -dim.w / 2, y: -dim.h / 2 },
+        ur: { x: dim.w / 2, y: dim.h / 2 },
+      };
+  const { entries, widths, heights, spacing, border } = layoutHtmlTable(tbl, measurer, {
+    fontsize: finfo.fontsize, fontname: finfo.fontname,
+  });
+  const ncols = widths.length > 0 ? Math.max(...entries.map(e => e.col + e.colspan)) : 0;
+  const nrows = heights.length > 0 ? Math.max(...entries.map(e => e.row + e.rowspan)) : 0;
+  // C pos_html_tbl:1557-1618 — when the assigned box is larger than the
+  // table's own size: a FIXEDSIZE table first aligns ITSELF within the box
+  // per its HALIGN/VALIGN (consuming delx/dely); any remaining extra space
+  // is then distributed evenly across the columns/rows.
+  let delx = Math.max(box.ur.x - box.ll.x - dim.w, 0);
+  let dely = Math.max(box.ur.y - box.ll.y - dim.h, 0);
+  if (tbl.fixedsize === true) {
+    if (delx > 0) {
+      if (tbl.align === 'left') box.ur.x = box.ll.x + dim.w;
+      else if (tbl.align === 'right') { box.ur.x += delx; box.ll.x += delx; }
+      else { box.ll.x += delx / 2; box.ur.x -= delx / 2; }
+      delx = 0;
+    }
+    if (dely > 0) {
+      if (tbl.valign === 'bottom') box.ur.y = box.ll.y + dim.h;
+      else if (tbl.valign === 'top') { box.ll.y += dely; box.ur.y = box.ll.y + dim.h; }
+      else { box.ll.y += dely / 2; box.ur.y -= dely / 2; }
+      dely = 0;
+    }
+  }
+  const colX = buildColX(box, border, spacing, distributeExtra(widths, delx, ncols));
+  const rowY = buildRowY(box, border, spacing, distributeExtra(heights, dely, nrows));
+  const cells = placeCells({ tbl, entries, colX, rowY, spacing, ncols, nrows, sides, finfo, measurer });
+  return { box, border, cells, spacing, columnCount: ncols, rowCount: nrows, port: tbl.port, boundarySides: sides, ...tblDecoration(tbl) };
+}
+
+/** Build a single-cell PlacedHtml for a plain text label. */
+function posTextLabel(label: Extract<HtmlLabel, { kind: 'text' }>, finfo: HtmlFontInfo, measurer: TextMeasurer): PlacedHtml {
+  const dim = label.dimen ?? { w: 0, h: 0 };
+  const box: Box = {
+    ll: { x: -dim.w / 2, y: -dim.h / 2 },
+    ur: { x: dim.w / 2, y: dim.h / 2 },
+  };
+  const runs = buildLineRuns(label.texts, finfo, measurer);
+  return {
+    box, border: 0, columnCount: 1, rowCount: 1, spacing: 0,
+    cells: [{
+      box, border: 0, col: 0, row: 0, colspan: 1, rowspan: 1,
+      lines: placeTextRuns(runs, box, finfo, measurer),
+    }],
+  };
+}
+
+/** Position a sized HtmlLabel relative to its center. */
+export function posHtmlLabel(
+  label: HtmlLabel,
+  finfo: HtmlFontInfo,
+  measurer: TextMeasurer,
+): PlacedHtml {
+  if (label.kind === 'table') return posHtmlTable(label.table, finfo, measurer);
+  return posTextLabel(label, finfo, measurer);
+}
+
+/**
+ * Build a TextlabelT for an HTML label string: parse, size, position.
+ * Falls back to a plain-text label on parse failure (C reverts to the
+ * object name; we keep the markup text).
+ *
+ * The optional `imageSizer` on `finfo` resolves `<IMG SRC="..."/>` dims.
+ * Absent → C missing-image behavior (zero size + warning).
+ *
+ * @see lib/common/htmltable.c:make_html_label
+ */
+/**
+ * Propagate pen (border) color down the table tree. A table with no explicit
+ * COLOR inherits `parentColor`; each cell inherits the (possibly inherited)
+ * table color; each nested table inherits its enclosing cell's color. Mirrors
+ * C, which defaults the top table's pencolor to getPenColor(obj) then copies
+ * parent->child during processTbl.
+ * @see lib/common/htmltable.c:1911 (top table), :1406-1407 (cell), :1556-1557
+ */
+function inheritTablePenColor(tbl: HtmlTable, parentColor: string | undefined): void {
+  if (tbl.color === undefined) tbl.color = parentColor;
+  const tblColor = tbl.color;
+  for (const row of tbl.rows) {
+    for (const cell of row.cells) {
+      if (cell.color === undefined) cell.color = tblColor;
+      for (const item of cell.content) {
+        if (item.kind === 'table') inheritTablePenColor(item, cell.color);
+      }
+    }
+  }
+}
+
+export function makeHtmlLabel(
+  content: string,
+  finfo: HtmlFontInfo & { imageSizer?: ImageSizer; pencolor?: string },
+  measurer: TextMeasurer,
+): TextlabelT {
+  const { fontname, fontsize, fontcolor, imageSizer, pencolor } = finfo;
+  let lbl: HtmlLabel;
+  try {
+    lbl = parseHtmlLabel(content);
+  } catch {
+    // C aborts the HTML parse on a syntax error (YYABORT) and leaves the label
+    // EMPTY — it does not fall back to rendering the raw markup as plain text.
+    // @see lib/common/htmlparse.y (cleanup + YYABORT), htmllex.c htmlerror
+    return makeLabel('', fontname, fontsize, fontcolor, measurer);
+  }
+  // A top-level table with no explicit COLOR inherits the object's pen color,
+  // which then flows table->cell->nested-table.
+  // @see lib/common/htmltable.c:1911 (getPenColor), :1406/:1556 (inheritance)
+  if (lbl.kind === 'table') inheritTablePenColor(lbl.table, pencolor);
+  sizeHtmlLabel(lbl, measurer, {
+    fontsize, fontname, imageSizer,
+  });
+  const placed = posHtmlLabel(lbl, { fontname, fontsize, fontcolor }, measurer);
+  const dim = lbl.dimen ?? { w: 0, h: 0 };
+  // C replaces table-label text: "this may be used for the title and
+  // alt fields in image maps" — anchors inherit it as default tooltip.
+  // @see lib/common/htmltable.c:make_html_label (line 1935)
+  const text = lbl.kind === 'table' ? '<TABLE>' : content;
+  return htmlTextLabel(text, { fontname, fontsize, fontcolor }, placed, dim);
+}
+
+/** Build the TextlabelT wrapper around a positioned HTML label. */
+function htmlTextLabel(
+  text: string,
+  finfo: HtmlFontInfo,
+  placed: PlacedHtml,
+  dim: { w: number; h: number },
+): TextlabelT {
+  return {
+    text,
+    fontname: finfo.fontname, fontcolor: finfo.fontcolor, charset: 0,
+    fontsize: finfo.fontsize,
+    dimen: { x: dim.w, y: dim.h },
+    space: { x: dim.w, y: dim.h },
+    pos: { x: 0, y: 0 },
+    u: { kind: 'html', html: placed },
+    valign: 'c'.charCodeAt(0),
+    set: false,
+    html: true,
+  };
+}