@knowvah/dot-engine 0.1.0

package/src/common/arrows-geometry.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Pure geometry helpers for arrow rendering.
+ * Ported from the internal static functions in lib/common/arrows.c.
+ *
+ * @see lib/common/arrows.c
+ */
+
+import type { Point } from '../model/geom.js';
+import { miterShapeImpl } from './arrows-miter.js';
+
+// ---------------------------------------------------------------------------
+// Small vector helpers
+// ---------------------------------------------------------------------------
+
+/** @see lib/common/geomprocs.h:add_pointf */
+export function addPoint(a: Point, b: Point): Point {
+  return { x: a.x + b.x, y: a.y + b.y };
+}
+
+/** @see lib/common/geomprocs.h:sub_pointf */
+export function subPoint(a: Point, b: Point): Point {
+  return { x: a.x - b.x, y: a.y - b.y };
+}
+
+/** @see lib/common/geomprocs.h:scale */
+export function scalePoint(s: number, p: Point): Point {
+  return { x: s * p.x, y: s * p.y };
+}
+
+/** Euclidean distance between two points. @see lib/common/arrows.c:DIST macro */
+export function dist(a: Point, b: Point): number {
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+// ---------------------------------------------------------------------------
+// Angle helpers
+// ---------------------------------------------------------------------------
+
+/** Signed angle in radians from direction vector (dx, dy). */
+export function signedAngle(dx: number, dy: number): number {
+  return dy > 0
+    ? Math.acos(dx / Math.hypot(dx, dy))
+    : -Math.acos(dx / Math.hypot(dx, dy));
+}
+
+// ---------------------------------------------------------------------------
+// Triangle (line-join shape) — re-exported from arrows-miter.ts
+// ---------------------------------------------------------------------------
+
+export type { Triangle } from './arrows-miter.js';
+
+/**
+ * Miter (or bevel fallback) line-join shape for a stroke corner at P.
+ * @see lib/common/arrows.c:miter_shape
+ */
+export function miterShape(
+  baseLeft: Point, P: Point, baseRight: Point, penwidth: number,
+): import('./arrows-miter.js').Triangle {
+  return miterShapeImpl(baseLeft, P, baseRight, penwidth);
+}

package/src/common/arrows-miter.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Miter line-join shape computation, split from arrows-geometry.ts to
+ * satisfy per-function line-length limits.
+ *
+ * @see lib/common/arrows.c:miter_shape
+ */
+
+import type { Point } from '../model/geom.js';
+
+/**
+ * Three points describing a line-join shape at a stroke corner.
+ * points[0] = miter tip P3 (or bevel midpoint)
+ * points[1] = P1 (left penwidth offset)
+ * points[2] = P2 (right penwidth offset)
+ *
+ * @see lib/common/arrows.c:triangle
+ */
+export type Triangle = { readonly points: readonly [Point, Point, Point] };
+
+/** Signed angle in radians from direction vector (dx, dy). */
+const ang = (dx: number, dy: number): number =>
+  dy > 0
+    ? Math.acos(dx / Math.hypot(dx, dy))
+    : -Math.acos(dx / Math.hypot(dx, dy));
+
+/** Left penwidth-offset at corner P for incoming direction from→P. */
+const p1Off = (from: Point, P: Point, half: number): Point => {
+  const dx = P.x - from.x;
+  const dy = P.y - from.y;
+  const h = Math.hypot(dx, dy);
+  return { x: P.x - half * dy / h, y: P.y + half * dx / h };
+};
+
+/** Right penwidth-offset at corner P for outgoing direction P→to. */
+const p2Off = (P: Point, to: Point, half: number): Point => {
+  const dx = to.x - P.x;
+  const dy = to.y - P.y;
+  const h = Math.hypot(dx, dy);
+  return { x: P.x - half * dy / h, y: P.y + half * dx / h };
+};
+
+/** Miter theta: interior angle at P clamped to (−π, π]. */
+const mTheta = (from: Point, P: Point, to: Point): number => {
+  const raw = ang(to.x - P.x, to.y - P.y)
+    - Math.PI
+    - ang(P.x - from.x, P.y - from.y);
+  return raw <= -Math.PI ? raw + 2 * Math.PI : raw;
+};
+
+/** Miter tip P3: P1 extended along incoming segment by arm l. */
+const p3Tip = (from: Point, P: Point, P1: Point, l: number): Point => {
+  const dx = P.x - from.x;
+  const dy = P.y - from.y;
+  const h = Math.hypot(dx, dy);
+  return { x: P1.x + l * dx / h, y: P1.y + l * dy / h };
+};
+
+/**
+ * Miter (or bevel fallback) line-join shape for a stroke corner at P.
+ * @see lib/common/arrows.c:miter_shape
+ */
+export function miterShapeImpl(
+  baseLeft: Point,
+  P: Point,
+  baseRight: Point,
+  penwidth: number,
+): Triangle {
+  if (
+    (baseLeft.x === P.x && baseLeft.y === P.y) ||
+    (baseRight.x === P.x && baseRight.y === P.y)
+  ) {
+    return { points: [P, P, P] };
+  }
+  const half = penwidth / 2.0;
+  const P1 = p1Off(baseLeft, P, half);
+  const P2 = p2Off(P, baseRight, half);
+  const t = mTheta(baseLeft, P, baseRight);
+  if (1.0 / Math.sin(t / 2.0) > 4.0) {
+    return { points: [{ x: (P1.x + P2.x) / 2, y: (P1.y + P2.y) / 2 }, P1, P2] };
+  }
+  return { points: [p3Tip(baseLeft, P, P1, half / Math.tan(t / 2.0)), P1, P2] };
+}

package/src/common/arrows-shapes-poly.ts

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Complex arrowhead shape/length generators (crow/vee, tee, gap, curve) ported
+ * from lib/common/arrows.c. Split from {@link arrows-shapes} to keep each
+ * module under the size/complexity bar. Pure geometry; no layout/render deps.
+ *
+ * @see lib/common/arrows.c
+ */
+
+import type { Point } from '../model/geom.js';
+import type { GenResult } from './arrows-shapes-util.js';
+import {
+  vsub, vadd, miterShape, negUnit, backwardDelta, axialProjection,
+} from './arrows-shapes-util.js';
+import {
+  ARROW_LENGTH, ARR_MOD_INV, ARR_MOD_LEFT, ARR_MOD_RIGHT,
+} from './arrows-constants.js';
+
+// ===========================================================================
+// crow / vee  (G2 target: the 9-point polygon)
+// @see lib/common/arrows.c:arrow_type_crow0 (:632), arrow_type_crow (:774)
+// ===========================================================================
+
+const CROW_ARROWWIDTH = 0.45;
+
+/** crow0 locals bundled to keep helper signatures within the parameter bar. */
+interface CrowGeom {
+  p0: Point; u: Point; v: Point; w: Point; m: Point; q0: Point; P: Point;
+}
+interface CrowBase { baseLeft: Point; baseRight: Point; P: Point }
+
+/** Resolve crow0's base_left/base_right/P (note: arms are v/v_inv, tip is +u). */
+function crowBasePoints(u: Point, v: Point, flag: number): CrowBase {
+  const origin: Point = { x: 0, y: 0 };
+  const vInv: Point = { x: -v.x, y: -v.y };
+  const normalLeft = flag & ARR_MOD_RIGHT ? origin : v;
+  const normalRight = flag & ARR_MOD_LEFT ? origin : vInv;
+  return {
+    baseLeft: flag & ARR_MOD_INV ? normalRight : normalLeft,
+    baseRight: flag & ARR_MOD_INV ? normalLeft : normalRight,
+    P: flag & ARR_MOD_INV ? { x: -u.x, y: -u.y } : u,
+  };
+}
+
+/** crow0's delta_tip (miter point P1/P2/P3 selected by LEFT/RIGHT/INV). */
+function crowDeltaTip(bp: CrowBase, penwidth: number, flag: number): Point {
+  const ls = miterShape(bp.baseLeft, bp.P, bp.baseRight, penwidth);
+  if (!(flag & ARR_MOD_LEFT) && !(flag & ARR_MOD_RIGHT)) return vsub(ls[0], bp.P);
+  const useP2 = !!(flag & ARR_MOD_LEFT) === !!(flag & ARR_MOD_INV);
+  return axialProjection(bp.P, bp.P, useP2 ? ls[2] : ls[1], 1);
+}
+
+/** crow0's delta_base: penwidth offset for vee, or the toe miter for crow. */
+function crowDeltaBase(g: CrowGeom, penwidth: number, flag: number): Point {
+  if (flag & ARR_MOD_INV) return negUnit(g.P, -penwidth / 2.0); // vee: +pw/2 along P
+  // crow: the toes extend by the right-toe miter projection (negated).
+  const toeBaseLeft = vadd(vsub(g.m, g.q0), g.w);
+  const toeP = vsub(g.v, g.u);
+  const ls = miterShape(toeBaseLeft, toeP, { x: 0, y: 0 }, penwidth);
+  return axialProjection(g.P, toeP, ls[1], -1);
+}
+
+/** Assemble crow0's a[9] + visual start q for the vee (INV) branch. */
+function assembleVee(g: CrowGeom, base: Point, tip: Point): { a: Point[]; q: Point } {
+  const p = vsub(g.p0, tip);
+  const qs = vsub(g.q0, tip);
+  const a: Point[] = [
+    p, vsub(qs, g.v), vsub(g.m, g.w), vsub(qs, g.w), qs,
+    vadd(qs, g.w), vadd(g.m, g.w), vadd(qs, g.v), p,
+  ];
+  return { a, q: vsub(qs, base) };
+}
+
+/** Assemble crow0's a[9] + visual start q for the crow branch. */
+function assembleCrowHead(g: CrowGeom, base: Point, tip: Point): { a: Point[]; q: Point } {
+  const ps = vadd(g.p0, base);
+  const qs = vadd(g.q0, base);
+  const toeTip = vadd(ps, base); // C: a[3..5] = p (already shifted) + delta_base
+  const a: Point[] = [
+    qs, vsub(ps, g.v), vsub(g.m, g.w), toeTip, toeTip,
+    toeTip, vadd(g.m, g.w), vadd(ps, g.v), qs,
+  ];
+  return { a, q: vadd(qs, tip) };
+}
+
+/** @see lib/common/arrows.c:arrow_type_crow0 */
+function arrowTypeCrow0(p0: Point, u: Point, arrowsize: number, penwidth: number, flag: number): { a: Point[]; q: Point } {
+  let arrowwidth = CROW_ARROWWIDTH;
+  if (penwidth > 4 * arrowsize && flag & ARR_MOD_INV) arrowwidth *= penwidth / (4 * arrowsize);
+  let shaftwidth = 0;
+  if (penwidth > 1 && flag & ARR_MOD_INV) shaftwidth = (0.05 * (penwidth - 1)) / arrowsize;
+
+  const v: Point = { x: -u.y * arrowwidth, y: u.x * arrowwidth };
+  const w: Point = { x: -u.y * shaftwidth, y: u.x * shaftwidth };
+  const q0: Point = { x: p0.x + u.x, y: p0.y + u.y };
+  const m: Point = { x: p0.x + u.x * 0.5, y: p0.y + u.y * 0.5 };
+  const P: Point = flag & ARR_MOD_INV ? { x: -u.x, y: -u.y } : u;
+  const g: CrowGeom = { p0, u, v, w, m, q0, P };
+
+  let base: Point = { x: 0, y: 0 };
+  let tip: Point = { x: 0, y: 0 };
+  if (u.x !== 0 || u.y !== 0) {
+    tip = crowDeltaTip(crowBasePoints(u, v, flag), penwidth, flag);
+    base = crowDeltaBase(g, penwidth, flag);
+  }
+  return flag & ARR_MOD_INV ? assembleVee(g, base, tip) : assembleCrowHead(g, base, tip);
+}
+
+/** @see lib/common/arrows.c:arrow_type_crow (always filled; OPEN has no effect) */
+export function genCrow(p: Point, u: Point, arrowsize: number, penwidth: number, flag: number): GenResult {
+  const { a, q } = arrowTypeCrow0(p, u, arrowsize, penwidth, flag);
+  let points: Point[];
+  if (flag & ARR_MOD_LEFT) points = a.slice(0, 5);
+  else if (flag & ARR_MOD_RIGHT) points = a.slice(4, 9);
+  else points = a.slice(0, 8);
+  return { ops: [{ kind: 'polygon', points, filled: true }], q };
+}
+
+/** @see lib/common/arrows.c:arrow_length_crow */
+export function arrowLengthCrow(lenfact: number, arrowsize: number, penwidth: number, flag: number): number {
+  const u: Point = { x: lenfact * arrowsize * ARROW_LENGTH, y: 0 };
+  const { a, q } = arrowTypeCrow0({ x: 0, y: 0 }, u, arrowsize, penwidth, flag);
+  const base1 = a[1];
+  const fullLength = q.x;
+  const fullLengthWithoutShaft = fullLength - (base1.x - a[3].x);
+  const nominalLength = Math.abs(base1.x - a[0].x);
+  const nominalBaseWidth = a[7].y - base1.y;
+  const fullBaseWidth = (nominalBaseWidth * fullLengthWithoutShaft) / nominalLength;
+  const overlapAtBase = penwidth / 2;
+  const overlapAtTip = (fullLengthWithoutShaft * penwidth) / fullBaseWidth;
+  const overlap = flag & ARR_MOD_INV ? overlapAtBase : overlapAtTip;
+  return fullLength - overlap;
+}
+
+// ===========================================================================
+// gap (none) — a polyline with no fill
+// @see lib/common/arrows.c:arrow_type_gap (:791)
+// ===========================================================================
+
+/** @see lib/common/arrows.c:arrow_type_gap */
+export function genGap(p0: Point, u: Point, _arrowsize: number, _penwidth: number, _flag: number): GenResult {
+  const q: Point = { x: p0.x + u.x, y: p0.y + u.y };
+  return { ops: [{ kind: 'polyline', points: [p0, q] }], q };
+}
+
+// ===========================================================================
+// tee — a thick bar (polygon) + a shaft polyline
+// @see lib/common/arrows.c:arrow_type_tee (:808)
+// ===========================================================================
+
+/** @see lib/common/arrows.c:arrow_type_tee */
+export function genTee(p0: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const v: Point = { x: -u.y, y: u.x };
+  const length = Math.hypot(u.x, u.y);
+  const extend = penwidth / 2 - 0.2 * length;
+  const delta = length > 0 && extend > 0 ? negUnit(u, extend) : { x: 0, y: 0 };
+  const p = vsub(p0, delta);
+  const m = vsub({ x: p0.x + u.x * 0.2, y: p0.y + u.y * 0.2 }, delta);
+  const n = vsub({ x: p0.x + u.x * 0.6, y: p0.y + u.y * 0.6 }, delta);
+  const q = vsub({ x: p0.x + u.x, y: p0.y + u.y }, delta);
+
+  const a: Point[] = [
+    { x: m.x + v.x, y: m.y + v.y },
+    { x: m.x - v.x, y: m.y - v.y },
+    { x: n.x - v.x, y: n.y - v.y },
+    { x: n.x + v.x, y: n.y + v.y },
+  ];
+  if (flag & ARR_MOD_LEFT) { a[0] = m; a[3] = n; }
+  else if (flag & ARR_MOD_RIGHT) { a[1] = m; a[2] = n; }
+  return {
+    ops: [
+      { kind: 'polygon', points: a, filled: true },
+      { kind: 'polyline', points: [p, q] },
+    ],
+    q,
+  };
+}
+
+/** @see lib/common/arrows.c:arrow_length_tee (preserves the C `_at_start` reuse) */
+export function arrowLengthTee(lenfact: number, arrowsize: number, penwidth: number): number {
+  const nominal = lenfact * arrowsize * ARROW_LENGTH;
+  let length = nominal;
+  const extendStart = penwidth / 2 - (1 - 0.6) * nominal;
+  if (extendStart > 0) length += extendStart;
+  const extendEnd = penwidth / 2 - 0.2 * nominal;
+  if (extendStart > 0) length += extendEnd; // C checks `_at_start` here too; preserved
+  return length;
+}
+
+// ===========================================================================
+// curve / icurve — a shaft polyline + a concave Bézier
+// @see lib/common/arrows.c:arrow_type_curve (:1031)
+// ===========================================================================
+
+const lerp = (a: Point, b: Point): Point => ({ x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 });
+
+/** Split a cubic at t=0.5 (de Casteljau); return the left or right half. */
+function cubicHalf(c: Point[], rightHalf: boolean): Point[] {
+  const A = lerp(c[0], c[1]);
+  const B = lerp(c[1], c[2]);
+  const C = lerp(c[2], c[3]);
+  const D = lerp(A, B);
+  const E = lerp(B, C);
+  const M = lerp(D, E);
+  return rightHalf ? [M, E, C, c[3]] : [c[0], A, D, M];
+}
+
+/** Build the four Bézier control points for the curve arms. */
+function curveControlPoints(p: Point, v: Point, w: Point, flag: number): Point[] {
+  const AF0: Point = { x: p.x + v.x + w.x, y: p.y + v.y + w.y };
+  const AF3: Point = { x: p.x - v.x + w.x, y: p.y - v.y + w.y };
+  const s = flag & ARR_MOD_INV ? 1 : -1; // inv bulges the curve the other way
+  const AF1: Point = { x: p.x + 0.95 * v.x + w.x + s * w.x * (4.0 / 3.0), y: AF0.y + s * w.y * (4.0 / 3.0) };
+  const AF2: Point = { x: p.x - 0.95 * v.x + w.x + s * w.x * (4.0 / 3.0), y: AF3.y + s * w.y * (4.0 / 3.0) };
+  return [AF0, AF1, AF2, AF3];
+}
+
+/** @see lib/common/arrows.c:arrow_type_curve */
+export function genCurve(p0: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const arrowwidth = penwidth > 4 ? (0.5 * penwidth) / 4 : 0.5;
+  const noShift = (flag & ARR_MOD_INV) || (u.x === 0 && u.y === 0);
+  const p = noShift ? p0 : vsub(p0, backwardDelta(u, penwidth));
+  const q: Point = { x: p.x + u.x, y: p.y + u.y };
+  const v: Point = { x: -u.y * arrowwidth, y: u.x * arrowwidth };
+  const w: Point = { x: v.y, y: -v.x };
+  let af = curveControlPoints(p, v, w, flag);
+  if (flag & ARR_MOD_LEFT) af = cubicHalf(af, true);
+  else if (flag & ARR_MOD_RIGHT) af = cubicHalf(af, false);
+  return {
+    ops: [
+      { kind: 'polyline', points: [p0, q] },
+      { kind: 'bezier', points: af },
+    ],
+    q,
+  };
+}
+
+/** @see lib/common/arrows.c:arrow_length_curve */
+export const arrowLengthCurve = (lenfact: number, arrowsize: number, penwidth: number): number =>
+  lenfact * arrowsize * ARROW_LENGTH + penwidth / 2;

package/src/common/arrows-shapes-util.ts

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Shared geometry primitives for the arrowhead shape/length generators
+ * ({@link arrows-shapes} closed shapes + {@link arrows-shapes-poly} complex
+ * shapes). Pure helpers ported from lib/common/arrows.c + geomprocs.h.
+ *
+ * @see lib/common/arrows.c
+ */
+
+import type { Point } from '../model/geom.js';
+import type { ArrowDrawOp, ResolvedArrow } from './arrows-types.js';
+import {
+  ARROW_LENGTH,
+  ARR_MOD_OPEN, ARR_MOD_LEFT, ARR_MOD_RIGHT,
+} from './arrows-constants.js';
+
+/** @see lib/common/arrows.c:#define EPSILON .0001 */
+const ARROW_EPSILON = 0.0001;
+
+// ---------------------------------------------------------------------------
+// pointf helpers (geomprocs.h add_pointf/sub_pointf/scale)
+// ---------------------------------------------------------------------------
+
+export const vsub = (p: Point, q: Point): Point => ({ x: p.x - q.x, y: p.y - q.y });
+export const vadd = (p: Point, q: Point): Point => ({ x: p.x + q.x, y: p.y + q.y });
+export const vscale = (c: number, p: Point): Point => ({ x: c * p.x, y: c * p.y });
+
+/** A vector of length `dist` pointing along `-u` (zero for degenerate `u`). */
+export const negUnit = (u: Point, dist: number): Point => {
+  if (u.x === 0 && u.y === 0) return { x: 0, y: 0 };
+  const h = Math.hypot(u.x, u.y);
+  return { x: dist * (-u.x / h), y: dist * (-u.y / h) };
+};
+
+/**
+ * The `penwidth/2` shift along `-u` that box/dot/curve/gap apply to pull the
+ * arrow off the node boundary (`delta` in those generators).
+ *
+ * @see lib/common/arrows.c:arrow_type_box / arrow_type_dot (delta computation)
+ */
+export const backwardDelta = (u: Point, penwidth: number): Point => negUnit(u, penwidth / 2.0);
+
+/**
+ * Project the segment `from`→`to` onto the arrow axis defined by `phiSrc`,
+ * returning a vector of the projected length (× `sign`) along that axis. This
+ * is the `delta_tip`/`delta_base` miter projection shared by normal0/crow0.
+ *
+ * @see lib/common/arrows.c:arrow_type_normal0 / arrow_type_crow0 (delta math)
+ */
+export function axialProjection(phiSrc: Point, from: Point, to: Point, sign: number): Point {
+  const hp = Math.hypot(phiSrc.x, phiSrc.y);
+  const cosPhi = phiSrc.x / hp;
+  const sinPhi = phiSrc.y / hp;
+  const phi = phiSrc.y > 0 ? Math.acos(cosPhi) : -Math.acos(cosPhi);
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const h = Math.hypot(dx, dy);
+  const cosAlpha = dx / h;
+  const alpha = dy > 0 ? Math.acos(cosAlpha) : -Math.acos(cosAlpha);
+  const len = sign * h * Math.cos(alpha - phi);
+  return { x: len * cosPhi, y: len * sinPhi };
+}
+
+/**
+ * Shaft vector for one component, reproducing `arrow_gen`'s normalization of the
+ * RAW shaft vector exactly: `s = ARROW_LENGTH / (hypot(u) + EPSILON)`, then nudge
+ * each component by `±EPSILON`, then `arrow_gen_type` scales by `lenfact *
+ * arrowsize`. `dir` MUST be the raw (un-normalized) tip→base vector — its
+ * magnitude is load-bearing because the EPSILON terms are relative to it.
+ * Pre-normalizing `dir` to a unit vector shifts the result by ~one ULP at the
+ * 2-decimal output and breaks byte parity on arrowhead polygons.
+ *
+ * @see lib/common/arrows.c:arrow_gen, arrow_gen_type (EPSILON .0001)
+ */
+export const componentU = (dir: Point, lenfact: number, arrowsize: number): Point => {
+  const s = ARROW_LENGTH / (Math.hypot(dir.x, dir.y) + ARROW_EPSILON);
+  const ux = (dir.x + (dir.x >= 0 ? ARROW_EPSILON : -ARROW_EPSILON)) * s;
+  const uy = (dir.y + (dir.y >= 0 ? ARROW_EPSILON : -ARROW_EPSILON)) * s;
+  return { x: ux * lenfact * arrowsize, y: uy * lenfact * arrowsize };
+};
+
+/**
+ * Reconstruct the C arrow flag word (type code + INV + open/side modifiers)
+ * from a resolved component. `type` already carries the type code and INV bit.
+ */
+export const arrowFlag = (r: ResolvedArrow): number =>
+  r.type |
+  (r.open ? ARR_MOD_OPEN : 0) |
+  (r.left ? ARR_MOD_LEFT : 0) |
+  (r.right ? ARR_MOD_RIGHT : 0);
+
+/** Result of one shape generator: its draw ops + the next tip (base point). */
+export interface GenResult {
+  readonly ops: ArrowDrawOp[];
+  readonly q: Point;
+}
+
+/**
+ * Map every point of an arrow draw-op through `fn` (and the ellipse center).
+ * Used to translate/rotate stored ops in postproc and flat-edge copy. rx/ry are
+ * left unchanged — arrow ellipses are circles (dot/odot), so a 90° rankdir
+ * rotation that would swap them is a no-op.
+ */
+export function mapArrowOpPoints(op: ArrowDrawOp, fn: (p: Point) => Point): ArrowDrawOp {
+  switch (op.kind) {
+    case 'ellipse': return { ...op, center: fn(op.center) };
+    case 'polygon': return { ...op, points: op.points.map(fn) };
+    case 'polyline': return { kind: 'polyline', points: op.points.map(fn) };
+    case 'bezier': return { kind: 'bezier', points: op.points.map(fn) };
+  }
+}
+
+/** Signature shared by every per-type shape generator. */
+export type ArrowGen = (
+  p: Point, u: Point, arrowsize: number, penwidth: number, flag: number,
+) => GenResult;
+
+// ---------------------------------------------------------------------------
+// miter_shape (SVG line-join shape at the tip vertex)
+// @see lib/common/arrows.c:miter_shape
+// ---------------------------------------------------------------------------
+
+const STROKE_MITERLIMIT = 4.0;
+
+/** Unit direction + signed angle of a segment `from`→`to` (miter_shape arm). */
+export interface Arm { cos: number; sin: number; angle: number }
+export function arm(from: Point, to: Point): Arm {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const h = Math.hypot(dx, dy);
+  const cos = dx / h;
+  const sin = dy / h;
+  return { cos, sin, angle: dy > 0 ? Math.acos(cos) : -Math.acos(cos) };
+}
+
+/**
+ * Line-join shape (3-point triangle [apex, P1, P2]) at vertex `P` between the
+ * `base_left`→P and P→`base_right` segments, for a stroke of width `penwidth`.
+ * P1/P2 are the penwidth/2 perpendicular offsets of P along each arm.
+ *
+ * @see lib/common/arrows.c:miter_shape
+ * @see https://www.w3.org/TR/SVG2/painting.html#TermLineJoinShape
+ */
+export function miterShape(baseLeft: Point, P: Point, baseRight: Point, penwidth: number): Point[] {
+  if ((baseLeft.x === P.x && baseLeft.y === P.y) || (baseRight.x === P.x && baseRight.y === P.y)) {
+    return [P, P, P]; // the stroke shape is really a point; do not extend it
+  }
+  const a = arm(baseLeft, P);
+  const b = arm(P, baseRight);
+  const hpw = penwidth / 2.0;
+  const P1: Point = { x: P.x - hpw * a.sin, y: P.y + hpw * a.cos };
+  const P2: Point = { x: P.x - hpw * b.sin, y: P.y + hpw * b.cos };
+  const raw = b.angle - Math.PI - a.angle;
+  const theta = raw + (raw <= -Math.PI ? 2 * Math.PI : 0);
+  if (1.0 / Math.sin(theta / 2.0) > STROKE_MITERLIMIT) {
+    // Miter limit exceeded → bevel: approximate the apex by the P1/P2 midpoint.
+    return [{ x: (P1.x + P2.x) / 2, y: (P1.y + P2.y) / 2 }, P1, P2];
+  }
+  const l = hpw / Math.tan(theta / 2.0);
+  return [{ x: P1.x + l * a.cos, y: P1.y + l * a.sin }, P1, P2];
+}