@knowvah/dot-engine 0.1.0

package/src/common/edge-label-init.ts

@@ -0,0 +1,310 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Head/tail edge-label creation: port of the initFontLabelEdgeAttr +
+ * head/tail-label blocks inside common_init_edge (lib/common/utils.c:533-545).
+ *
+ * Called from dotInitNodeEdge after the regular edge-weight fields are set,
+ * mirroring the C call order in dot_init_node_edge → common_init_edge.
+ *
+ * @see lib/common/utils.c:common_init_edge
+ * @see lib/common/utils.c:initFontEdgeAttr
+ * @see lib/common/utils.c:initFontLabelEdgeAttr
+ */
+
+import type { Edge } from '../model/edge.js';
+import type { Graph } from '../model/graph.js';
+import type { Node } from '../model/node.js';
+import type { Port } from '../model/geom.js';
+import { makePort } from '../model/edgeInfo.js';
+import type { TextMeasurer } from './textmeasure.js';
+import { makeAnyLabel, DEFAULT_FONTNAME, DEFAULT_COLOR, DEFAULT_FONTSIZE } from './make-label.js';
+import { isHtmlValue, htmlValueContent } from './html-string.js';
+import { lateDouble } from '../common/nodeinit.js';
+import { EDGE_LABEL, EDGE_XLABEL, HEAD_LABEL, TAIL_LABEL } from '../layout/dot/rank.js';
+
+// ---------------------------------------------------------------------------
+// Constants — @see lib/common/const.h
+// ---------------------------------------------------------------------------
+
+/** Default fontsize for head/tail labels. @see lib/common/const.h:DEFAULT_LABEL_FONTSIZE */
+export const DEFAULT_LABEL_FONTSIZE = 11.0;
+
+/** Minimum fontsize (shared across all label types). @see lib/common/const.h:MIN_FONTSIZE */
+export const MIN_FONTSIZE = 1.0;
+
+// ---------------------------------------------------------------------------
+// FontInfo — mirrors C's struct fontinfo in utils.c
+// ---------------------------------------------------------------------------
+
+interface FontInfo {
+  fontsize: number;
+  fontname: string;
+  fontcolor: string;
+}
+
+// ---------------------------------------------------------------------------
+// mapbool — @see lib/common/utils.c:mapbool
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps a string attribute value to boolean, mirroring mapbool() in utils.c.
+ * "false"/"no"/empty → false; "true"/"yes"/non-zero integer → true.
+ *
+ * @see lib/common/utils.c:mapbool
+ */
+function mapbool(s: string | undefined): boolean {
+  if (!s || s.toLowerCase() === 'false' || s.toLowerCase() === 'no') return false;
+  if (s.toLowerCase() === 'true' || s.toLowerCase() === 'yes') return true;
+  const n = parseInt(s, 10);
+  return !Number.isNaN(n) && n !== 0;
+}
+
+// ---------------------------------------------------------------------------
+// initFontEdgeAttr — @see lib/common/utils.c:456-461
+// ---------------------------------------------------------------------------
+
+/**
+ * Reads the per-edge font attrs (fontname/fontsize/fontcolor) with fallback
+ * to the global defaults.  Mirrors initFontEdgeAttr in utils.c.
+ *
+ * @see lib/common/utils.c:initFontEdgeAttr
+ */
+export function initFontEdgeAttr(e: Edge): FontInfo {
+  return {
+    fontsize:  lateDouble(e.attrs.get('fontsize'),  DEFAULT_FONTSIZE,  MIN_FONTSIZE),
+    fontname:  e.attrs.get('fontname')  || DEFAULT_FONTNAME,
+    fontcolor: e.attrs.get('fontcolor') || DEFAULT_COLOR,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// initFontLabelEdgeAttr — @see lib/common/utils.c:463-471
+// ---------------------------------------------------------------------------
+
+/**
+ * Reads labelfontname / labelfontsize / labelfontcolor with fallback to fi
+ * (the regular edge font attrs).  Mirrors initFontLabelEdgeAttr in utils.c.
+ *
+ * The fallback chain for each attribute:
+ *   labelfontsize  → fi.fontsize  → DEFAULT_FONTSIZE
+ *   labelfontname  → fi.fontname  → DEFAULT_FONTNAME
+ *   labelfontcolor → fi.fontcolor → DEFAULT_COLOR
+ *
+ * @see lib/common/utils.c:initFontLabelEdgeAttr
+ */
+export function initFontLabelEdgeAttr(e: Edge, fi: FontInfo): FontInfo {
+  return {
+    fontsize:  lateDouble(e.attrs.get('labelfontsize'),  fi.fontsize,  MIN_FONTSIZE),
+    fontname:  e.attrs.get('labelfontname')  || fi.fontname,
+    fontcolor: e.attrs.get('labelfontcolor') || fi.fontcolor,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// getLabelFontInfo — lazy FontInfo pair computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazily compute (fi, lfi) the first time either is needed, mirroring the
+ * C NULL-guard pattern: fi.fontname starts NULL, lfi.fontname starts NULL.
+ *
+ * @see lib/common/utils.c:common_init_edge (fi/lfi NULL guards at 534, 541)
+ */
+function getLabelFontInfo(e: Edge): FontInfo {
+  const fi = initFontEdgeAttr(e);
+  return initFontLabelEdgeAttr(e, fi);
+}
+
+// ---------------------------------------------------------------------------
+// applyLabel — @see lib/common/utils.c:517-523
+// ---------------------------------------------------------------------------
+
+/**
+ * Create center edge label and set EDGE_LABEL bit when label attr is non-empty.
+ *
+ * The flag goes on `g.root` — C's `graph_t *sg = agraphof(agtail(e))`, i.e. the
+ * TRUE cgraph root, never the graph currently being initialized. This matters
+ * under `pack`: each connected component is init'd and laid out as its own graph,
+ * but C still ORs the flags onto the shared root, and the dot layout reads them
+ * back via `GD_has_labels(g->root)` (position.c:234 make_LR_constraints,
+ * dotsplines.c:243/1552/1650/1776). Setting them on the component left the root's
+ * flags clear, so every `g->root` reader took the no-edge-label branch — e.g.
+ * make_LR_constraints used the full nodesep on odd ranks instead of C's `sep[1]=5`.
+ * (`GD_has_labels(g)` on the component stays 0, which is what `edgelabel_ranks`
+ * — rank.c:170, the one reader C scopes to the layout graph — requires.)
+ *
+ * @see lib/common/utils.c:common_init_edge (graph_t *sg = agraphof(agtail(e)))
+ * @see lib/common/utils.c:519 — make_label(e, str, aghtmlstr(str), false, ...)
+ */
+function applyLabel(e: Edge, g: Graph, fi: FontInfo, measurer: TextMeasurer): void {
+  const str = e.attrs.get('label');
+  if (!str) return;
+  const isHtml = isHtmlValue(str);
+  const content = isHtml ? htmlValueContent(str) : str;
+  e.info.label = makeAnyLabel(content, isHtml, fi, measurer, e);
+  g.root.info.has_labels |= EDGE_LABEL;
+  // ED_label_ontop: mapbool(late_string(e, E_label_float, "false"))
+  // @see lib/common/utils.c:522
+  e.info.label_ontop = mapbool(e.attrs.get('label_float')) ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// applyXLabel — @see lib/common/utils.c:525-531
+// ---------------------------------------------------------------------------
+
+/**
+ * Create external edge label and set EDGE_XLABEL bit when xlabel attr is
+ * non-empty. Reuses fi if already initialized by applyLabel (C laziness).
+ *
+ * @see lib/common/utils.c:common_init_edge (lines 525-531)
+ * @see lib/common/utils.c:528 — make_label(e, str, aghtmlstr(str), false, ...)
+ */
+function applyXLabel(e: Edge, g: Graph, fi: FontInfo, measurer: TextMeasurer): void {
+  const str = e.attrs.get('xlabel');
+  if (!str) return;
+  const isHtml = isHtmlValue(str);
+  const content = isHtml ? htmlValueContent(str) : str;
+  e.info.xlabel = makeAnyLabel(content, isHtml, fi, measurer, e);
+  // C: GD_has_labels(sg) where sg = agraphof(agtail(e)) — the true root.
+  g.root.info.has_labels |= EDGE_XLABEL;
+}
+
+// ---------------------------------------------------------------------------
+// applyHeadLabel — @see lib/common/utils.c:533-538
+// ---------------------------------------------------------------------------
+
+/**
+ * Create head_label and set HEAD_LABEL bit when headlabel attr is non-empty.
+ * @see lib/common/utils.c:533-538
+ * @see lib/common/utils.c:535 — make_label(e, str, aghtmlstr(str), false, ...)
+ */
+function applyHeadLabel(e: Edge, g: Graph, lfi: FontInfo, measurer: TextMeasurer): void {
+  const str = e.attrs.get('headlabel');
+  if (!str) return;
+  const isHtml = isHtmlValue(str);
+  const content = isHtml ? htmlValueContent(str) : str;
+  e.info.head_label = makeAnyLabel(content, isHtml, lfi, measurer, e);
+  // C: GD_has_labels(sg) where sg = agraphof(agtail(e)) — the true root.
+  g.root.info.has_labels = (g.root.info.has_labels ?? 0) | HEAD_LABEL;
+}
+
+// ---------------------------------------------------------------------------
+// applyTailLabel — @see lib/common/utils.c:539-545
+// ---------------------------------------------------------------------------
+
+/**
+ * Create tail_label and set TAIL_LABEL bit when taillabel attr is non-empty.
+ * @see lib/common/utils.c:539-545
+ * @see lib/common/utils.c:542 — make_label(e, str, aghtmlstr(str), false, ...)
+ */
+function applyTailLabel(e: Edge, g: Graph, lfi: FontInfo, measurer: TextMeasurer): void {
+  const str = e.attrs.get('taillabel');
+  if (!str) return;
+  const isHtml = isHtmlValue(str);
+  const content = isHtml ? htmlValueContent(str) : str;
+  e.info.tail_label = makeAnyLabel(content, isHtml, lfi, measurer, e);
+  // C: GD_has_labels(sg) where sg = agraphof(agtail(e)) — the true root.
+  g.root.info.has_labels = (g.root.info.has_labels ?? 0) | TAIL_LABEL;
+}
+
+// ---------------------------------------------------------------------------
+// initEdgeLabels — full label block of common_init_edge
+// @see lib/common/utils.c:509-545
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply label and xlabel with lazy fi init mirroring C's NULL-guard pattern.
+ * fi is initialized at most once and reused for xlabel.
+ * @see lib/common/utils.c:common_init_edge (lines 515-531)
+ */
+function applyMainLabels(e: Edge, g: Graph, measurer: TextMeasurer): void {
+  // C: fi.fontname = NULL; init on first need, reuse for xlabel.
+  let fi: FontInfo | null = null;
+  const labelStr = e.attrs.get('label');
+  if (labelStr) {
+    fi = initFontEdgeAttr(e);
+    applyLabel(e, g, fi, measurer);
+  }
+  const xlabelStr = e.attrs.get('xlabel');
+  if (xlabelStr) {
+    applyXLabel(e, g, fi ?? initFontEdgeAttr(e), measurer);
+  }
+}
+
+/**
+ * Apply headlabel and taillabel using the labelfont* chain.
+ * @see lib/common/utils.c:common_init_edge (lines 533-545)
+ */
+function applyEndLabels(e: Edge, g: Graph, measurer: TextMeasurer): void {
+  const lfi = getLabelFontInfo(e);
+  applyHeadLabel(e, g, lfi, measurer);
+  applyTailLabel(e, g, lfi, measurer);
+}
+
+/**
+ * Creates label, xlabel, head_label, and tail_label TextlabelT objects on the
+ * edge, mirroring common_init_edge in C. C statement order is preserved:
+ * label → xlabel → headlabel → taillabel.
+ *
+ * @see lib/common/utils.c:common_init_edge (lines 509-545)
+ */
+/** Shape portfn: aiming point + slope for a named/compass port. */
+type PortFn = (n: unknown, portname: string, compass: string) => Port;
+
+/**
+ * Resolve a "name" or "name:compass" port string. pt.name is the compass
+ * suffix (or the whole string when there is no colon). A null portfn (the
+ * default for shapes without one) yields a zero-init Center port. C passes
+ * the no-colon compass as NULL; the TS portfn type is `string`, so we pass
+ * "" — compassPort treats "" and NULL alike.
+ * @see lib/common/utils.c:489 chkPort
+ */
+function chkPort(pf: PortFn | null, n: Node, s: string): Port {
+  const cp = s.indexOf(':');
+  if (cp >= 0) {
+    const compass = s.slice(cp + 1);
+    const pt = pf ? pf(n, s.slice(0, cp), compass) : makePort();
+    pt.name = compass;
+    return pt;
+  }
+  const pt = pf ? pf(n, s, '') : makePort();
+  pt.name = s;
+  return pt;
+}
+
+/** A clip attr explicitly set false (C noClip / !late_bool(...,true)). */
+function isClipDisabled(v: string | undefined): boolean {
+  return v !== undefined && /^(false|no|0)$/i.test(v.trim());
+}
+
+/** The node shape's portfn, or null. @see lib/common/types.h:shape_functions.portfn */
+function portfnOf(n: Node): PortFn | null {
+  const shape = n.info.shape as { fns?: { portfn?: PortFn | null } } | undefined;
+  return shape?.fns?.portfn ?? null;
+}
+
+/**
+ * Port block of common_init_edge: populate tail_port/head_port from the
+ * tailport/headport attrs (DOT syntax or explicit), honoring tail/headclip.
+ * @see lib/common/utils.c:548-566
+ */
+export function initEdgePorts(e: Edge): void {
+  const tailStr = e.attrs.get('tailport') ?? '';
+  if (tailStr.length > 0) e.tail.info.has_port = true;
+  e.info.tail_port = chkPort(portfnOf(e.tail), e.tail, tailStr);
+  if (isClipDisabled(e.attrs.get('tailclip'))) e.info.tail_port.clip = false;
+  const headStr = e.attrs.get('headport') ?? '';
+  if (headStr.length > 0) e.head.info.has_port = true;
+  e.info.head_port = chkPort(portfnOf(e.head), e.head, headStr);
+  if (isClipDisabled(e.attrs.get('headclip'))) e.info.head_port.clip = false;
+}
+
+export function initEdgeLabels(e: Edge, g: Graph, measurer: TextMeasurer): void {
+  initEdgePorts(e); // port block runs for every edge, before the label short-circuit
+  const hasMain = e.attrs.has('label') || e.attrs.has('xlabel');
+  const hasEnd  = e.attrs.has('headlabel') || e.attrs.has('taillabel');
+  if (!hasMain && !hasEnd) return;
+  if (hasMain) applyMainLabels(e, g, measurer);
+  if (hasEnd)  applyEndLabels(e, g, measurer);
+}

package/src/common/edge-offset.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Perpendicular-offset geometry for parallel multi-color edge rendering.
+ *
+ * Ports computeoffset_p and computeoffset_qr from lib/common/emit.c.
+ * Pure data-in / data-out; no rendering or ObjState mutation.
+ * Consumed by the M1 parallel-bezier branch in src/gvc/device.ts.
+ *
+ * @see lib/common/emit.c:1836 computeoffset_p
+ * @see lib/common/emit.c:1849 computeoffset_qr
+ * @see lib/common/emit.c:55   #define EPSILON 0.0001
+ * @see lib/common/emit.c:2364 #define SEP 2.0
+ */
+
+import type { Point } from '../model/geom.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Epsilon guard used in the offset vector computation to keep the result
+ * finite as the line-segment length approaches zero.
+ * @see lib/common/emit.c:55
+ */
+export const OFFSET_EPSILON = 0.0001;
+
+/**
+ * Perpendicular separation between parallel color curves (in graph units).
+ * @see lib/common/emit.c:2364
+ */
+export const PARALLEL_SEP = 2.0;
+
+// ---------------------------------------------------------------------------
+// Offset helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Calculate an offset vector, length d, perpendicular to line p→q.
+ * The result vector points 90° counter-clockwise from the direction p→q.
+ * Formula: res = { (p.y-q.y)*d/len, -(p.x-q.x)*d/len }
+ *
+ * @see lib/common/emit.c:1836 computeoffset_p
+ */
+export function computeOffsetP(p: Point, q: Point, d: number): Point {
+  const x = p.x - q.x;
+  const y = p.y - q.y;
+  // keep d finite as line length approaches 0
+  const scale = d / Math.sqrt(x * x + y * y + OFFSET_EPSILON);
+  return { x: y * scale, y: -x * scale };
+}
+
+/**
+ * Calculate an offset vector, length d, perpendicular to spline p,q,r,s
+ * at the middle control points q and r.  When q and r coincide (len < ε),
+ * falls back to the p→s direction.
+ *
+ * @see lib/common/emit.c:1849 computeoffset_qr
+ */
+export function computeOffsetQR(p: Point, q: Point, r: Point, s: Point, d: number): Point {
+  const x = q.x - r.x;
+  const y = q.y - r.y;
+  let len = Math.hypot(x, y);
+  let cx = x;
+  let cy = y;
+  if (len < OFFSET_EPSILON) {
+    // control points on top of each other — use slope between endpoints
+    cx = p.x - s.x;
+    cy = p.y - s.y;
+    len = Math.sqrt(cx * cx + cy * cy + OFFSET_EPSILON);
+  }
+  const scale = d / len;
+  return { x: cy * scale, y: -cx * scale };
+}
+
+// ---------------------------------------------------------------------------
+// Build parallel-offset spline data
+// ---------------------------------------------------------------------------
+
+/**
+ * One parallel-offset bezier: a clone of the bezier's control-point array
+ * with every point offset by offVec × d (in-place via the tmp array).
+ *
+ * Returns { offlist, tmplist } for a SINGLE bezier segment with `size`
+ * control points (must be 4k+1 for k cubic segments).
+ *
+ * Algorithm:
+ *   - offlist[j]     = computeOffsetP(pf[j-1 or pf2_prev], pf[j+1], SEP)   at j=0 or next segment start
+ *   - offlist[j+1/2] = computeOffsetQR(pf0,pf1,pf2,pf3, SEP)               for the two middle CPs
+ *   - offlist[last]  = computeOffsetP(pf2, pf3, SEP)
+ *   - tmplist[j]     = pf[j] - numc2 * offlist[j]                           (outermost lane)
+ *
+ * @see lib/common/emit.c:2449-2480
+ */
+export function buildOffsetLists(
+  pts: Point[],
+  numc2: number,
+): { offlist: Point[]; tmplist: Point[] } {
+  const size = pts.length;
+  const offlist: Point[] = new Array<Point>(size).fill({ x: 0, y: 0 });
+  const tmplist: Point[] = new Array<Point>(size).fill({ x: 0, y: 0 });
+
+  let pf3 = pts[0]!;
+  let pf2: Point = { x: 0, y: 0 };
+  let j = 0;
+  for (j = 0; j < size - 1; j += 3) {
+    const pf0 = pf3;
+    const pf1 = pts[j + 1]!;
+    if (j === 0) {
+      offlist[j] = computeOffsetP(pf0, pf1, PARALLEL_SEP);
+    } else {
+      offlist[j] = computeOffsetP(pf2, pf1, PARALLEL_SEP);
+    }
+    pf2 = pts[j + 2]!;
+    pf3 = pts[j + 3]!;
+    const mid = computeOffsetQR(pf0, pf1, pf2, pf3, PARALLEL_SEP);
+    offlist[j + 1] = mid;
+    offlist[j + 2] = mid;
+    tmplist[j]     = { x: pf0.x - numc2 * offlist[j]!.x,     y: pf0.y - numc2 * offlist[j]!.y };
+    tmplist[j + 1] = { x: pf1.x - numc2 * offlist[j + 1]!.x, y: pf1.y - numc2 * offlist[j + 1]!.y };
+    tmplist[j + 2] = { x: pf2.x - numc2 * offlist[j + 2]!.x, y: pf2.y - numc2 * offlist[j + 2]!.y };
+  }
+  // last segment — no next pf1; use pf2→pf3 direction
+  offlist[j] = computeOffsetP(pf2, pf3, PARALLEL_SEP);
+  tmplist[j] = { x: pf3.x - numc2 * offlist[j]!.x, y: pf3.y - numc2 * offlist[j]!.y };
+
+  return { offlist, tmplist };
+}
+
+/**
+ * Advance every tmp point by one offset step (add offlist[i] to tmplist[i]).
+ * Called once per color before drawing that color's curve.
+ * @see lib/common/emit.c:2501-2504
+ */
+export function advanceTmpList(tmplist: Point[], offlist: Point[]): void {
+  for (let i = 0; i < tmplist.length; i++) {
+    tmplist[i] = { x: tmplist[i]!.x + offlist[i]!.x, y: tmplist[i]!.y + offlist[i]!.y };
+  }
+}

package/src/common/ellipse-wedge.ts

@@ -0,0 +1,189 @@
+// SPDX-License-Identifier: EPL-2.0
+//
+// Elliptic-wedge bezier tessellation — faithful port of lib/common/ellipse.c.
+//
+// Returns a cubic-Bézier approximation of an elliptical wedge (an arc plus the
+// two line segments to the ellipse center), as an ordered list of control
+// points matching C's `Ppolyline_t.ps` / `pn`. Used by the ortho rounded-corner
+// edge emit, which slices out just the arc portion and draws it as a polyline.
+//
+// Derived (via C) from Luc Maisonobe's Java EllipticalArc implementation.
+//
+// @see lib/common/ellipse.c:ellipticWedge / genEllipticPath / initEllipse
+
+import type { Point } from '../model/geom.js';
+
+const TWOPI = 2 * Math.PI;
+
+interface Ellipse {
+  cx: number; cy: number; // center
+  a: number; b: number;   // semi-major and -minor axes
+  eta1: number; eta2: number; // start/end angles of the arc
+}
+
+/** @see lib/common/ellipse.c:initEllipse */
+function initEllipse(
+  cx: number, cy: number, a: number, b: number, lambda1: number, lambda2: number,
+): Ellipse {
+  let eta1 = Math.atan2(Math.sin(lambda1) / b, Math.cos(lambda1) / a);
+  let eta2 = Math.atan2(Math.sin(lambda2) / b, Math.cos(lambda2) / a);
+  // make sure we have eta1 <= eta2 <= eta1 + 2*PI
+  eta2 -= TWOPI * Math.floor((eta2 - eta1) / TWOPI);
+  // the preceding correction fails if we have exactly eta2 - eta1 = 2*PI;
+  // it reduces the interval to zero length
+  if (lambda2 - lambda1 > Math.PI && eta2 - eta1 < Math.PI) {
+    eta2 += TWOPI;
+  }
+  return { cx, cy, a, b, eta1, eta2 };
+}
+
+// coefficients for error estimation while using cubic Bézier curves for
+// approximation. erray_t = [2][4][4]. @see lib/common/ellipse.c
+const coeffs3Low: number[][][] = [
+  [[3.85268, -21.229, -0.330434, 0.0127842],
+   [-1.61486, 0.706564, 0.225945, 0.263682],
+   [-0.910164, 0.388383, 0.00551445, 0.00671814],
+   [-0.630184, 0.192402, 0.0098871, 0.0102527]],
+  [[-0.162211, 9.94329, 0.13723, 0.0124084],
+   [-0.253135, 0.00187735, 0.0230286, 0.01264],
+   [-0.0695069, -0.0437594, 0.0120636, 0.0163087],
+   [-0.0328856, -0.00926032, -0.00173573, 0.00527385]],
+];
+const coeffs3High: number[][][] = [
+  [[0.0899116, -19.2349, -4.11711, 0.183362],
+   [0.138148, -1.45804, 1.32044, 1.38474],
+   [0.230903, -0.450262, 0.219963, 0.414038],
+   [0.0590565, -0.101062, 0.0430592, 0.0204699]],
+  [[0.0164649, 9.89394, 0.0919496, 0.00760802],
+   [0.0191603, -0.0322058, 0.0134667, -0.0825018],
+   [0.0156192, -0.017535, 0.00326508, -0.228157],
+   [-0.0236752, 0.0405821, -0.0173086, 0.176187]],
+];
+// safety factor to convert the "best" error approximation into a "max bound"
+const safety3 = [0.001, 4.98, 0.207, 0.0067];
+
+/** Rational function: quadratic numerator over linear denominator.
+ *  @see lib/common/ellipse.c:RationalFunction */
+function rationalFunction(x: number, c: readonly number[]): number {
+  return (x * (x * c[0] + c[1]) + c[2]) / (x + c[3]);
+}
+
+/** Upper bound of the Bézier-vs-ellipse approximation error for a sub-arc.
+ *  @see lib/common/ellipse.c:estimateError */
+function estimateError(ep: Ellipse, etaA: number, etaB: number): number {
+  const eta = 0.5 * (etaA + etaB);
+  const x = ep.b / ep.a;
+  const dEta = etaB - etaA;
+  const cos2 = Math.cos(2 * eta);
+  const cos4 = Math.cos(4 * eta);
+  const cos6 = Math.cos(6 * eta);
+  const coeffs = x < 0.25 ? coeffs3Low : coeffs3High;
+
+  const c0 = rationalFunction(x, coeffs[0][0]) +
+    cos2 * rationalFunction(x, coeffs[0][1]) +
+    cos4 * rationalFunction(x, coeffs[0][2]) +
+    cos6 * rationalFunction(x, coeffs[0][3]);
+  const c1 = rationalFunction(x, coeffs[1][0]) +
+    cos2 * rationalFunction(x, coeffs[1][1]) +
+    cos4 * rationalFunction(x, coeffs[1][2]) +
+    cos6 * rationalFunction(x, coeffs[1][3]);
+
+  return rationalFunction(x, safety3) * ep.a * Math.exp(c0 + c1 * dEta);
+}
+
+// Bézier path builder — moveTo/lineTo/curveTo/endPath append control points,
+// matching the C bezier_path_t (a flat list of pointf). @see ellipse.c
+function curveTo(
+  path: Point[], x1: number, y1: number, x2: number, y2: number, x3: number, y3: number,
+): void {
+  path.push({ x: x1, y: y1 }, { x: x2, y: y2 }, { x: x3, y: y3 });
+}
+function lineTo(path: Point[], x: number, y: number): void {
+  const cur = path[path.length - 1];
+  curveTo(path, cur.x, cur.y, x, y, x, y);
+}
+
+/** Approximate an elliptical arc via degree-3 Béziers; path begins and ends
+ *  with line segments to the ellipse center. @see lib/common/ellipse.c:genEllipticPath */
+function genEllipticPath(ep: Ellipse): Point[] {
+  const THRESHOLD = 0.00001; // quality of approximation
+
+  // find the number of Bézier curves needed
+  let found = false;
+  let n = 1;
+  while (!found && n < 1024) {
+    const diffEta = (ep.eta2 - ep.eta1) / n;
+    if (diffEta <= 0.5 * Math.PI) {
+      let etaOne = ep.eta1;
+      found = true;
+      for (let i = 0; found && i < n; ++i) {
+        const etaA = etaOne;
+        etaOne += diffEta;
+        found = estimateError(ep, etaA, etaOne) <= THRESHOLD;
+      }
+    }
+    n = n << 1;
+  }
+
+  const dEta = (ep.eta2 - ep.eta1) / n;
+  let etaB = ep.eta1;
+
+  let cosEtaB = Math.cos(etaB);
+  let sinEtaB = Math.sin(etaB);
+  let aCosEtaB = ep.a * cosEtaB;
+  let bSinEtaB = ep.b * sinEtaB;
+  let aSinEtaB = ep.a * sinEtaB;
+  let bCosEtaB = ep.b * cosEtaB;
+  let xB = ep.cx + aCosEtaB;
+  let yB = ep.cy + bSinEtaB;
+  let xBDot = -aSinEtaB;
+  let yBDot = bCosEtaB;
+
+  const path: Point[] = [];
+  // moveTo(center); lineTo(arc start)
+  path.push({ x: ep.cx, y: ep.cy });
+  lineTo(path, xB, yB);
+
+  const t = Math.tan(0.5 * dEta);
+  const alpha = Math.sin(dEta) * (Math.sqrt(4 + 3 * t * t) - 1) / 3;
+
+  for (let i = 0; i < n; ++i) {
+    const xA = xB;
+    const yA = yB;
+    const xADot = xBDot;
+    const yADot = yBDot;
+
+    etaB += dEta;
+    cosEtaB = Math.cos(etaB);
+    sinEtaB = Math.sin(etaB);
+    aCosEtaB = ep.a * cosEtaB;
+    bSinEtaB = ep.b * sinEtaB;
+    aSinEtaB = ep.a * sinEtaB;
+    bCosEtaB = ep.b * cosEtaB;
+    xB = ep.cx + aCosEtaB;
+    yB = ep.cy + bSinEtaB;
+    xBDot = -aSinEtaB;
+    yBDot = bCosEtaB;
+
+    curveTo(path, xA + alpha * xADot, yA + alpha * yADot,
+      xB - alpha * xBDot, yB - alpha * yBDot, xB, yB);
+  }
+
+  // endPath: lineTo back to the first point (the center)
+  lineTo(path, path[0].x, path[0].y);
+  return path;
+}
+
+/**
+ * Return a cubic-Bézier control-point list for an elliptical wedge, center
+ * `ctr`, x/y semi-axes `xsemi`/`ysemi`, start angle `angle0`, end angle
+ * `angle1`. Includes the beginning and ending line segments to the center.
+ * Point order and count match C's `Ppolyline_t.ps` / `pn`.
+ * @see lib/common/ellipse.c:ellipticWedge
+ */
+export function ellipticWedge(
+  ctr: Point, xsemi: number, ysemi: number, angle0: number, angle1: number,
+): Point[] {
+  const ell = initEllipse(ctr.x, ctr.y, xsemi, ysemi, angle0, angle1);
+  return genEllipticPath(ell);
+}