@knowvah/dot-engine 0.1.0

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

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Fill, border, and rule-line helpers for HTML label emission.
+ * Ports setFill, mkPts, doSide, doBorder from lib/common/htmltable.c.
+ *
+ * @see lib/common/htmltable.c:setFill
+ * @see lib/common/htmltable.c:mkPts
+ * @see lib/common/htmltable.c:doSide
+ * @see lib/common/htmltable.c:doBorder
+ */
+
+import type { Point, Box } from '../model/geom.js';
+import type { ObjState, RenderJob } from '../gvc/job.js';
+import { ObjType, EmitState, MapShape } from '../gvc/job.js';
+import type { RendererPlugin } from '../gvc/context.js';
+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 {
+  BORDER_LEFT,
+  BORDER_TOP,
+  BORDER_RIGHT,
+  BORDER_BOTTOM,
+  BORDER_MASK,
+} from './htmltable-types.js';
+
+// ---------------------------------------------------------------------------
+// Gradient spec parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a color spec for gradient: "color1:color2" → [color1, color2].
+ * Single-color strings return null (not a gradient spec).
+ *
+ * @see lib/common/emit.c:findStopColor
+ */
+export function parseGradientSpec(color: string): [string, string] | null {
+  const idx = color.indexOf(':');
+  if (idx < 1) return null;
+  const c0 = color.slice(0, idx).trim();
+  const c1 = color.slice(idx + 1).trim();
+  if (c0.length === 0) return null;
+  return [c0, c1.length > 0 ? c1 : 'black'];
+}
+
+// ---------------------------------------------------------------------------
+// Scoped paint state — the port of C's gvrender set_fillcolor/set_pencolor
+// ---------------------------------------------------------------------------
+
+/**
+ * Reusable scoped ObjState for HTML decoration painting.
+ *
+ * The live render path keeps no persistent ObjState (job.obj is null
+ * outside the dormant emit family), so decoration drawing pushes this
+ * one for the duration of each paint call. Mirrors C's
+ * gvrender_set_fillcolor/gvrender_set_pencolor on the active obj
+ * before each drawing call in emit_html_tbl / emit_html_cell.
+ *
+ * Module-level reuse avoids per-decoration allocation (hot-loop rule).
+ *
+ * @see lib/common/htmltable.c:setFill
+ */
+const paintObj: ObjState = {
+  parent: null, type: ObjType.Node, graphObj: null,
+  emitState: EmitState.NDraw,
+  penColor: { type: 'string', s: 'black' },
+  fillColor: { type: 'none' },
+  stopColor: { type: 'none' },
+  gradientAngle: 0, gradientFrac: 0,
+  pen: PenType.Solid, fill: FillType.None, penWidth: 1.0,
+  rawStyle: [],
+  label: null, xlabel: null, tailLabel: null, headLabel: null,
+  url: null, id: null, labelUrl: null, tailUrl: null, headUrl: null,
+  tooltip: null, labelTooltip: null, tailTooltip: null, headTooltip: null,
+  target: null, labelTarget: null, tailTarget: null, headTarget: null,
+  explicitTooltip: false, explicitTailTooltip: false,
+  explicitHeadTooltip: false, explicitLabelTooltip: false,
+  explicitTailTarget: false, explicitHeadTarget: false,
+  explicitEdgeTarget: false, explicitTailUrl: false,
+  explicitHeadUrl: false, labelEdgeAligned: false,
+  urlMapShape: MapShape.Rectangle,
+  urlMapPts: [], urlBsplineMapPts: [],
+  tailEndMapPts: [], headEndMapPts: [],
+};
+
+/** Paint requested for a scoped drawing call. */
+export interface HtmlPaint {
+  /** Solid fill color, or the first stop of a gradient when `stop` is set. */
+  fill?: string;
+  /** Pen (stroke) color; absent → "none" (transparent). */
+  pen?: string;
+  /** Pen width; default 1.0 (omitted from SVG at 1.0). */
+  penWidth?: number;
+  /** Style string; "dashed"/"dotted" map to the pen type. */
+  penStyle?: string;
+  /**
+   * Second/stop color of a gradient fill. Presence switches the fill from
+   * solid to a gradient (linear, or radial when `radial` is true), mirroring
+   * C setFill's findStopColor hit. @see lib/common/htmltable.c:setFill
+   */
+  stop?: string;
+  /** Gradient angle in degrees; defaults to 0. Ignored without `stop`. */
+  gradientAngle?: number;
+  /** True → radial gradient (RGRADIENT); else linear. Ignored without `stop`. */
+  radial?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// HTML fill pen-width state — the port of gvrender's persistent penwidth
+// ---------------------------------------------------------------------------
+
+/**
+ * The live gvrender pen width during HTML emission. C never resets it before a
+ * bgcolor fill: `setFill` sets only the fill color, so a cell/table fill draws
+ * at whatever pen width the *previous* `doBorder` left (the oracle emits
+ * `stroke-width="N"` on a bordered cell's fill, leaked from the prior cell's
+ * border, even though `stroke="none"`). `doBorder` writes it; the bgcolor fill
+ * reads it. Reset to 1.0 at each top-level table — the node/cluster shape drew
+ * at pen width 1 immediately before, so the first table/cell fill carries no
+ * stroke-width. Module-level to mirror gvrender job state and to stay reset per
+ * render (multi-diagram safety).
+ * @see lib/common/htmltable.c:doBorder (gvrender_set_penwidth(job, dp->border))
+ * @see lib/common/htmltable.c:setFill (sets fill color only, not penwidth)
+ */
+let htmlFillPen = 1.0;
+
+/** Current leaked fill pen width, read by the bgcolor fill for its stroke-width. */
+export function htmlFillPenWidth(): number {
+  return htmlFillPen;
+}
+
+/** Reset the leaked fill pen width to 1.0 — call at each top-level table entry. */
+export function resetHtmlFillPenWidth(): void {
+  htmlFillPen = 1.0;
+}
+
+/** Map a style string to the C pen type. @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;
+  return PenType.Solid;
+}
+
+/**
+ * Run drawFn with a scoped ObjState carrying the given paint colors,
+ * then restore the previous (usually null) obj state.
+ *
+ * @see lib/common/htmltable.c:setFill
+ */
+export function withHtmlPaint(paint: HtmlPaint, job: RenderJob, drawFn: () => void): void {
+  paintObj.fillColor = paint.fill !== undefined
+    ? resolveRenderColor(paint.fill) : { type: 'none' };
+  paintObj.penColor = paint.pen !== undefined
+    ? resolveRenderColor(paint.pen) : { type: 'string', s: 'transparent' };
+  applyHtmlFill(paint);
+  paintObj.pen = penTypeOf(paint.penStyle);
+  paintObj.penWidth = paint.penWidth !== undefined ? paint.penWidth : 1.0;
+  // C sets the default line style ("solid") before each HTML table/cell draw,
+  // so xdot emits `S 5 -solid` per border/fill. rawStyle carries it (SVG's
+  // style emit treats "solid" as the default → no visible change).
+  paintObj.rawStyle = paintObj.pen === PenType.Solid ? ['solid'] : [];
+  // Inherit the enclosing object's emit-state (the label state during an HTML
+  // label emit) so the fill/border ops route to the same xbuf as the label
+  // (_ldraw_), not the shape draw buffer. SVG ignores emit_state, so unchanged.
+  paintObj.emitState = job.obj?.emitState ?? EmitState.NDraw;
+  job.pushObj(paintObj);
+  try { drawFn(); } finally { job.popObj(); }
+}
+
+/**
+ * Set the fill type + gradient fields on paintObj from a paint request.
+ * A `stop` color switches solid → gradient, mirroring C setFill's
+ * findStopColor hit (clrs[0] is the fill, clrs[1] the gradient stop).
+ * For the "c0:c1" form with no explicit fraction the frac is 0
+ * (findStopColor's else branch). @see lib/common/htmltable.c:setFill
+ */
+function applyHtmlFill(paint: HtmlPaint): void {
+  if (paint.stop !== undefined) {
+    paintObj.fill = paint.radial === true ? FillType.Radial : FillType.Linear;
+    paintObj.stopColor = resolveRenderColor(paint.stop);
+    paintObj.gradientAngle = paint.gradientAngle ?? 0;
+    paintObj.gradientFrac = 0;
+    return;
+  }
+  paintObj.fill = paint.fill !== undefined ? FillType.Solid : FillType.None;
+  paintObj.stopColor = { type: 'none' };
+  paintObj.gradientAngle = 0;
+  paintObj.gradientFrac = 0;
+}
+
+// ---------------------------------------------------------------------------
+// mkPts
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the four inset corner points of box b (SW, SE, NE, NW).
+ * When border > 1, insets by border/2 on each side.
+ *
+ * @see lib/common/htmltable.c:mkPts
+ */
+export function mkPts(b: Box, border: number, pos: Point): Point[] {
+  let llx = b.ll.x + pos.x;
+  let lly = b.ll.y + pos.y;
+  let urx = b.ur.x + pos.x;
+  let ury = b.ur.y + pos.y;
+  if (border > 1) {
+    const delta = border / 2.0;
+    llx += delta; lly += delta;
+    urx -= delta; ury -= delta;
+  }
+  return [
+    { x: llx, y: lly }, // SW
+    { x: urx, y: lly }, // SE
+    { x: urx, y: ury }, // NE
+    { x: llx, y: ury }, // NW
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// doSide
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit a filled rule box from point p with given width/height.
+ * wd=0 means a vertical rule; ht=0 means a horizontal rule.
+ *
+ * @see lib/common/htmltable.c:doSide
+ */
+export function doSide(
+  p: Point,
+  wd: number,
+  ht: number,
+  renderer: RendererPlugin,
+  job: RenderJob,
+): void {
+  const pts = [
+    { x: p.x,      y: p.y      },
+    { x: p.x,      y: p.y + ht },
+    { x: p.x + wd, y: p.y + ht },
+    { x: p.x + wd, y: p.y      },
+  ].map((pt) => transformPoint(pt, job));
+  renderer.polygon(pts, true, job);
+}
+
+// ---------------------------------------------------------------------------
+// doBorder — descriptor type + implementation
+// ---------------------------------------------------------------------------
+
+/** Parameters for doBorder, grouped to stay within the 5-param limit. */
+export interface BorderSpec {
+  box: Box;
+  pos: Point;
+  border: number;
+  color: string;
+  /** SIDES bitmask (0 / undefined → full box). */
+  sides?: number;
+  /** Style string: "dashed", "dotted", etc. */
+  style?: string;
+}
+
+/**
+ * Emit a rectangular border for box b, respecting SIDES bitmask.
+ * When sides is 0 or undefined, emits a full-box polygon (unfilled).
+ *
+ * @see lib/common/htmltable.c:doBorder
+ */
+export function doBorder(
+  spec: BorderSpec,
+  renderer: RendererPlugin,
+  job: RenderJob,
+): void {
+  const { box, pos, border, color, sides, style } = spec;
+  // C: gvrender_set_penwidth(job, dp->border) before drawing the border; the
+  // 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) {
+      // 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 });
+      return;
+    }
+    const effSides = (sides !== undefined) ? (sides & BORDER_MASK) : 0;
+    if (effSides !== 0) {
+      const corners = mkPts(box, border, pos).map((p) => transformPoint(p, job));
+      emitSidedPolylines(effSides, corners, renderer, job);
+    } else {
+      emitFullBoxBorder(box, pos, border, renderer, job);
+    }
+  });
+}
+
+/** Emit an inset full-box border polygon (unfilled). */
+function emitFullBoxBorder(
+  box: Box,
+  pos: Point,
+  border: number,
+  renderer: RendererPlugin,
+  job: RenderJob,
+): void {
+  const b2: Box = border > 1 ? {
+    ll: { x: box.ll.x + border / 2, y: box.ll.y + border / 2 },
+    ur: { x: box.ur.x - border / 2, y: box.ur.y - border / 2 },
+  } : box;
+  const pts = [
+    { x: b2.ll.x + pos.x, y: b2.ll.y + pos.y },
+    { x: b2.ll.x + pos.x, y: b2.ur.y + pos.y },
+    { x: b2.ur.x + pos.x, y: b2.ur.y + pos.y },
+    { x: b2.ur.x + pos.x, y: b2.ll.y + pos.y },
+  ].map((pt) => transformPoint(pt, job));
+  renderer.polygon(pts, false, job);
+}
+
+// ---------------------------------------------------------------------------
+// emitSidedPolylines — lookup table, CCN ≤ 4
+// ---------------------------------------------------------------------------
+
+// Corner index aliases: 0=SW, 1=SE, 2=NE, 3=NW
+const SW = 0, SE = 1, NE = 2, NW = 3;
+const B = BORDER_BOTTOM, R = BORDER_RIGHT, T = BORDER_TOP, L = BORDER_LEFT;
+
+/**
+ * Lookup table: sides bitmask → list of polyline sequences (each sequence is
+ * an array of corner indices into [SW, SE, NE, NW]).
+ * Matches C doBorder switch-case exactly (htmltable.c:278-330).
+ *
+ * @see lib/common/htmltable.c:doBorder
+ */
+const SIDES_TABLE: ReadonlyMap<number, ReadonlyArray<ReadonlyArray<number>>> = new Map([
+  [B|R|T|L, [[SW,SE,NE,NW,SW]]],
+  [B|R|T,   [[SW,SE,NE,NW]]   ],
+  [R|T|L,   [[SE,NE,NW,SW]]   ],
+  [T|L|B,   [[NE,NW,SW,SE]]   ],
+  [L|B|R,   [[NW,SW,SE,NE]]   ],
+  [B|R,     [[SW,SE,NE]]      ],
+  [R|T,     [[SE,NE,NW]]      ],
+  [T|L,     [[NE,NW,SW]]      ],
+  [L|B,     [[NW,SW,SE]]      ],
+  [T|B,     [[SW,SE],[NE,NW]] ],
+  [L|R,     [[NW,SW],[SE,NE]] ],
+  [B,       [[SW,SE]]         ],
+  [R,       [[SE,NE]]         ],
+  [T,       [[NE,NW]]         ],
+  [L,       [[NW,SW]]         ],
+]);
+
+/**
+ * Emit polyline segments for a SIDES bitmask via a lookup table.
+ * CCN = 2 (loop + no-match guard).
+ *
+ * @see lib/common/htmltable.c:doBorder
+ */
+function emitSidedPolylines(
+  sides: number,
+  corners: Point[],
+  renderer: RendererPlugin,
+  job: RenderJob,
+): void {
+  const seqs = SIDES_TABLE.get(sides & BORDER_MASK);
+  if (seqs === undefined) return;
+  for (const seq of seqs) {
+    renderer.polyline(seq.map((i) => corners[i]!), job);
+  }
+}

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

@@ -0,0 +1,293 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * HTML rule-line emission and anchor helpers.
+ * Ports emit_html_rules, initAnchor, endAnchor from lib/common/htmltable.c.
+ *
+ * @see lib/common/htmltable.c:emit_html_rules
+ * @see lib/common/htmltable.c:initAnchor
+ * @see lib/common/htmltable.c:endAnchor
+ */
+
+import type { Point, Box } from '../model/geom.js';
+import type { RenderJob } from '../gvc/job.js';
+import type { RendererPlugin } from '../gvc/context.js';
+import type { PlacedCell, PlacedHtml } from './htmltable-pos.js';
+import { doSide, withHtmlPaint } from './htmltable-emit-fill.js';
+
+// ---------------------------------------------------------------------------
+// Rule context
+// ---------------------------------------------------------------------------
+
+/** Shared context for rule-line helpers, grouping all inputs. */
+export interface RuleCtx {
+  cell:  PlacedCell;
+  tbl:   PlacedHtml;
+  pos:   Point;
+  color: string;
+  /** Next cell in row-major order; C passes *cells after increment. */
+  nextCell?: PlacedCell;
+  renderer: RendererPlugin;
+  job:   RenderJob;
+}
+
+// ---------------------------------------------------------------------------
+// emitHtmlRules
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit vertical/horizontal rule lines for a cell that has vruled/hruled set.
+ * Pen width forced to 1.0 per C (emit_html_tbl:576 comment); rules draw
+ * as filled boxes with fill = pen = rule color.
+ *
+ * @see lib/common/htmltable.c:emit_html_rules
+ */
+export function emitHtmlRules(ctx: RuleCtx): void {
+  withHtmlPaint({ fill: ctx.color, pen: ctx.color, penWidth: 1 }, ctx.job, () => {
+    if (ctx.cell.vruled === true) emitVRuleIfNeeded(ctx);
+    if (ctx.cell.hruled === true) emitHRuleIfNeeded(ctx);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Vertical rule
+// ---------------------------------------------------------------------------
+
+/** Cell position summary used by rule param helpers. */
+interface CellPos {
+  idx: number;   // row or col index
+  span: number;  // rowspan or colspan
+  count: number; // rowCount or columnCount
+  border: number;
+  sp: number;
+}
+
+/** Base extension and start coordinate for a vertical rule. */
+function vRuleCoords(lly: number, p: CellPos): { ruleY: number; base: number } {
+  if (p.idx === 0) {
+    return { ruleY: lly - p.sp / 2, base: p.border + p.sp / 2 };
+  }
+  if (p.idx + p.span === p.count) {
+    const base = p.border + p.sp / 2;
+    return { ruleY: lly - p.sp / 2 - base, base };
+  }
+  return { ruleY: lly - p.sp / 2, base: 0 };
+}
+
+/** Emit vertical rule if cell does not span to the last column. */
+function emitVRuleIfNeeded(ctx: RuleCtx): void {
+  const { cell, tbl, pos, renderer, job } = ctx;
+  if (cell.col + cell.colspan >= tbl.columnCount) return;
+  const sp  = tbl.spacing;
+  const lly = cell.box.ll.y + pos.y;
+  const ury = cell.box.ur.y + pos.y;
+  const urx = cell.box.ur.x + pos.x;
+  const p: CellPos = { idx: cell.row, span: cell.rowspan, count: tbl.rowCount, border: tbl.border, sp };
+  const { ruleY, base } = vRuleCoords(lly, p);
+  doSide({ x: urx + sp / 2, y: ruleY }, 0, base + (ury - lly) + sp, renderer, job);
+}
+
+// ---------------------------------------------------------------------------
+// Horizontal rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Base extension and start coordinate for a horizontal rule.
+ * Mirrors the C first/last-column branches, including the base
+ * doubling when a col-0 cell is also the last column and the
+ * incomplete-row extension to the table edge.
+ * @see lib/common/htmltable.c:emit_html_rules (:488-512)
+ */
+function hRuleCoords(ctx: RuleCtx, llx: number, urx: number): { ruleX: number; base: number } {
+  const { cell, tbl, pos, nextCell } = ctx;
+  const sp = tbl.spacing;
+  const lastCol = cell.col + cell.colspan === tbl.columnCount;
+  // C: nextc && nextc->row != cp->row — incomplete row of cells
+  const extend = nextCell !== undefined && nextCell.row !== cell.row
+    ? tbl.box.ur.x + pos.x - (urx + sp / 2) : 0;
+  if (cell.col === 0) {
+    let base = tbl.border + sp / 2;
+    const ruleX = llx - base - sp / 2;
+    if (lastCol) base *= 2;
+    else if (extend !== 0) base += extend;
+    return { ruleX, base };
+  }
+  if (lastCol) {
+    return { ruleX: llx - sp / 2, base: tbl.border + sp / 2 };
+  }
+  return { ruleX: llx - sp / 2, base: extend };
+}
+
+/** Emit horizontal rule if cell does not span to the last row. */
+function emitHRuleIfNeeded(ctx: RuleCtx): void {
+  const { cell, tbl, pos, renderer, job } = ctx;
+  if (cell.row + cell.rowspan >= tbl.rowCount) return;
+  const sp  = tbl.spacing;
+  const llx = cell.box.ll.x + pos.x;
+  const urx = cell.box.ur.x + pos.x;
+  const lly = cell.box.ll.y + pos.y;
+  const { ruleX, base } = hRuleCoords(ctx, llx, urx);
+  doSide({ x: ruleX, y: lly - sp / 2 }, base + (urx - llx) + sp, 0, renderer, job);
+}
+
+// ---------------------------------------------------------------------------
+// Anchor data + helpers
+// ---------------------------------------------------------------------------
+
+/** Anchor metadata extracted from cell/table HTML attributes. */
+export interface AnchorData {
+  href?:   string;
+  title?:  string;
+  target?: string;
+  id?:     string;
+}
+
+/**
+ * Current object context for html anchors. C keeps this on job->obj
+ * (set by emit_begin_node/edge/graph); the port's live path has no
+ * persistent obj state, so the device walk sets it here before
+ * emitting each object's labels.
+ * objLabel feeds the C default tooltip (initMapData: tooltip falls
+ * back to obj->label — "<TABLE>" for table labels).
+ * @see lib/common/emit.c:initMapData (line 163)
+ */
+const anchorEnv: { objId: string; objLabel: string | null; imgscale: string } =
+  { objId: '', objLabel: null, imgscale: 'false' };
+
+/**
+ * Effective anchor obj-state, mirroring C's job->obj url/tooltip/target
+ * fields as saved/overlaid by initAnchor + initMapData: a cell that declares
+ * only TARGET (or only TITLE) still anchors, inheriting url/tooltip from the
+ * enclosing table/cell/object scope. Each initHtmlAnchor pushes an overlaid
+ * frame; endHtmlAnchor pops (C's htmlmap_data_t save/RESET).
+ * @see lib/common/htmltable.c:initAnchor/endAnchor, lib/common/emit.c:initMapData
+ */
+interface AnchorFrame {
+  url: string | null;
+  tooltip: string | null;
+  explicitTooltip: boolean;
+  target: string | null;
+  opened: boolean;
+}
+const anchorBase: AnchorFrame = { url: null, tooltip: null, explicitTooltip: false, target: null, opened: false };
+const anchorStack: AnchorFrame[] = [];
+function anchorTop(): AnchorFrame {
+  return anchorStack.length > 0 ? anchorStack[anchorStack.length - 1] : anchorBase;
+}
+
+/** Anchor id counter — C's `static int anchorId` in initAnchor, reset per render job (each dot invocation is one process). */
+let anchorSeq = 0;
+
+/** Set the current object context for anchor id/tooltip resolution.
+ *  base seeds the inherited url/tooltip scope from the object's own
+ *  attributes (C: job->obj populated at emit_begin_node/edge/cluster). */
+export function setHtmlAnchorObj(
+  objId: string, objLabel: string | null,
+  base?: { url: string | null; tooltip: string | null; explicitTooltip?: boolean; target: string | null },
+): void {
+  anchorEnv.objId = objId;
+  anchorEnv.objLabel = objLabel;
+  anchorEnv.imgscale = 'false';
+  anchorStack.length = 0;
+  anchorBase.url = base?.url ?? null;
+  anchorBase.tooltip = base?.tooltip ?? null;
+  anchorBase.explicitTooltip = base?.explicitTooltip ?? false;
+  anchorBase.target = base?.target ?? null;
+  anchorBase.opened = false;
+}
+
+/**
+ * Record the current object's imagescale attribute — C's
+ * env.imgscale = agget(obj, "imagescale"), defaulting to "false".
+ * @see lib/common/htmltable.c:emit_html_label (lines 768-772)
+ */
+export function setHtmlObjImgscale(imgscale: string | undefined): void {
+  anchorEnv.imgscale = imgscale !== undefined && imgscale !== '' ? imgscale : 'false';
+}
+
+/** The IMG SCALE fallback for the object being emitted. @see setHtmlObjImgscale */
+export function htmlObjImgscale(): string {
+  return anchorEnv.imgscale;
+}
+
+/** Reset the per-render anchor id counter. Call at render start. */
+export function resetHtmlAnchorIds(): void {
+  anchorSeq = 0;
+  anchorEnv.objId = '';
+  anchorEnv.objLabel = null;
+  anchorEnv.imgscale = 'false';
+}
+
+/** Normalise AnchorData to plain strings (empty when absent). */
+function normaliseAnchor(data: AnchorData): { h: string; t: string; tg: string; i: string } {
+  return {
+    h:  data.href   !== undefined ? data.href   : '',
+    t:  data.title  !== undefined ? data.title  : '',
+    tg: data.target !== undefined ? data.target : '',
+    i:  data.id     !== undefined ? data.id     : '',
+  };
+}
+
+/**
+ * Open an anchor when the data carries href/title/target.
+ *
+ * Mirrors C initAnchor exactly: an internal id `<objId>_<n>` is
+ * generated (consuming the counter) whenever the call is made without
+ * an explicit ID attr, but the anchor element only opens when there is
+ * a URL or an explicit tooltip (initMapData: obj->url ||
+ * obj->explicit_tooltip). A missing TITLE inherits the object label
+ * as tooltip.
+ * Returns true when an anchor was opened (caller must endHtmlAnchor).
+ *
+ * @see lib/common/htmltable.c:initAnchor (line 381)
+ * @see lib/common/emit.c:initMapData (line 163)
+ */
+export function initHtmlAnchor(
+  data: AnchorData,
+  box: Box,
+  renderer: RendererPlugin,
+  job: RenderJob,
+): boolean {
+  // C's emit_html_cell/tbl gate: the element declares href, target or title
+  // (htmltable.c:630 doAnchor); the anchor's URL and tooltip then come from
+  // the OVERLAID obj state — a TARGET-only cell inherits the enclosing
+  // table's HREF (2619's dat TDs). initMapData overlays only non-empty
+  // fields; the <a> element opens iff effective url || explicit tooltip.
+  if (data.href === undefined && data.title === undefined && data.target === undefined) {
+    return false;
+  }
+  const id = data.id !== undefined && data.id !== ''
+    ? data.id
+    : `${anchorEnv.objId}_${anchorSeq++}`;
+  const parent = anchorTop();
+  const frame: AnchorFrame = { ...parent, opened: false };
+  if (data.href !== undefined && data.href !== '') frame.url = data.href;
+  if (data.title !== undefined && data.title !== '') {
+    frame.tooltip = data.title;
+    frame.explicitTooltip = true;
+  } else if (frame.tooltip === null && anchorEnv.objLabel !== null) {
+    // C initMapData: tooltip falls back to obj->label (not explicit).
+    frame.tooltip = anchorEnv.objLabel;
+  }
+  if (data.target !== undefined && data.target !== '') frame.target = data.target;
+  if (frame.url !== null || frame.explicitTooltip) {
+    // C initAnchor: emit_map_rect(job, b) then gvrender_begin_anchor — the
+    // rectangle seeds obj.urlMapPts so the map device emits this cell/table's
+    // <area>. @see lib/common/htmltable.c:410
+    renderer.emitMapRect?.(box, job);
+    renderer.beginAnchor?.(frame.url ?? '', frame.tooltip ?? '', frame.target ?? '', id, job);
+    frame.opened = true;
+  }
+  anchorStack.push(frame);
+  return true;
+}
+
+/**
+ * Close anchor opened by initHtmlAnchor.
+ *
+ * @see lib/common/htmltable.c:endAnchor
+ */
+export function endHtmlAnchor(renderer: RendererPlugin, job: RenderJob): void {
+  const frame = anchorStack.pop();
+  if (frame?.opened) renderer.endAnchor?.(job);
+}