@knowvah/dot-engine 0.1.0

package/src/common/arrows-shapes.ts

@@ -0,0 +1,360 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Arrowhead geometry — pure port of the closed-shape (normal/box/diamond/dot)
+ * generators and the length/dispatch layer of lib/common/arrows.c. Complex
+ * shapes (crow/vee/tee/gap/curve) live in {@link arrows-shapes-poly}; shared
+ * primitives in {@link arrows-shapes-util}. Produces {@link ArrowDrawOp}s and
+ * clip lengths from a resolved arrow type, a tip point, and a shaft direction.
+ *
+ * Convention (from `arrow_gen`/`arrow_gen_type`): `u` is the shaft vector from
+ * the tip toward the base, length `ARROW_LENGTH * lenfact * arrowsize` per
+ * component. Each generator returns the visual start point `q` (the base),
+ * which becomes the tip of the next stacked component (compound stacking).
+ *
+ * @see lib/common/arrows.c
+ * @see plans/arrowhead-geometry/decisions.md ADR-2
+ */
+
+import type { Point } from '../model/geom.js';
+import type { ArrowDrawOp, ResolvedArrow } from './arrows-types.js';
+import {
+  vsub, vadd, vscale, miterShape, axialProjection, backwardDelta,
+  componentU, arrowFlag, type GenResult,
+} from './arrows-shapes-util.js';
+import {
+  genCrow, genTee, genGap, genCurve,
+  arrowLengthCrow, arrowLengthTee, arrowLengthCurve,
+} from './arrows-shapes-poly.js';
+import {
+  ARROW_LENGTH,
+  ARR_TYPE_MASK, ARR_TYPE_NONE, ARR_TYPE_NORM, ARR_TYPE_CROW, ARR_TYPE_TEE,
+  ARR_TYPE_BOX, ARR_TYPE_DIAMOND, ARR_TYPE_DOT, ARR_TYPE_CURVE, ARR_TYPE_GAP,
+  ARR_MOD_OPEN, ARR_MOD_INV, ARR_MOD_LEFT, ARR_MOD_RIGHT,
+} from './arrows-constants.js';
+
+// ---------------------------------------------------------------------------
+// arrow_type_normal0 / arrow_type_normal
+// @see lib/common/arrows.c:arrow_type_normal0 (:516), arrow_type_normal (:613)
+// ---------------------------------------------------------------------------
+
+const NORMAL_ARROWWIDTH = 0.35;
+
+/** The three modifier-resolved base/tip points feeding normal0's miter math. */
+interface NormalBasePoints { baseLeft: Point; baseRight: Point; P: Point }
+
+/** Resolve normal0's base_left/base_right/P honoring LEFT/RIGHT/INV flags. */
+function normalBasePoints(u: Point, v: Point, flag: number): NormalBasePoints {
+  const origin: Point = { x: 0, y: 0 };
+  const vInv: Point = { x: -v.x, y: -v.y };
+  const normalLeft = flag & ARR_MOD_RIGHT ? origin : vInv;
+  const normalRight = flag & ARR_MOD_LEFT ? origin : v;
+  return {
+    baseLeft: flag & ARR_MOD_INV ? normalRight : normalLeft,
+    baseRight: flag & ARR_MOD_INV ? normalLeft : normalRight,
+    P: flag & ARR_MOD_INV ? u : { x: -u.x, y: -u.y },
+  };
+}
+
+/** Compute `delta_tip` for normal0, honoring LEFT/RIGHT miter corrections. */
+function normalDeltaTip(bp: NormalBasePoints, 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); // delta_tip = P3 - P
+  }
+  const Pn = flag & ARR_MOD_LEFT ? ls[1] : ls[2];
+  return axialProjection(bp.P, bp.P, Pn, 1);
+}
+
+/** Base/tip overlap deltas computed for normal0. */
+interface NormalDeltas { base: Point; tip: Point }
+
+/** Assemble normal0's `a[5]` + visual start `q` from the deltas (INV branch). */
+function assembleNormal(
+  p0: Point, u: Point, v: Point, deltas: NormalDeltas, flag: number,
+): { a: Point[]; q: Point } {
+  let p: Point = { x: p0.x, y: p0.y };
+  let q: Point = { x: p0.x + u.x, y: p0.y + u.y };
+  const a: Point[] = new Array<Point>(5);
+  if (flag & ARR_MOD_INV) {
+    p = vadd(p, deltas.base);
+    q = vadd(q, deltas.base);
+    a[0] = a[4] = p;
+    a[1] = vsub(p, v);
+    a[2] = q;
+    a[3] = vadd(p, v);
+    q = vadd(q, deltas.tip);
+  } else {
+    p = vsub(p, deltas.tip);
+    q = vsub(q, deltas.tip);
+    a[0] = a[4] = q;
+    a[1] = vsub(q, v);
+    a[2] = p;
+    a[3] = vadd(q, v);
+    q = vsub(q, deltas.base);
+  }
+  return { a, q };
+}
+
+/**
+ * Compute the 5-point array `a` and visual start `q` for a normal arrowhead.
+ *
+ * @see lib/common/arrows.c:arrow_type_normal0
+ */
+function arrowTypeNormal0(p0: Point, u: Point, penwidth: number, flag: number): { a: Point[]; q: Point } {
+  let arrowwidth = NORMAL_ARROWWIDTH;
+  if (penwidth > 4) arrowwidth *= penwidth / 4;
+
+  const v: Point = { x: -u.y * arrowwidth, y: u.x * arrowwidth };
+  const bp = normalBasePoints(u, v, flag);
+
+  let deltaBase: Point = { x: 0, y: 0 };
+  let deltaTip: Point = { x: 0, y: 0 };
+  if (u.x !== 0 || u.y !== 0) {
+    const hyp = Math.hypot(bp.P.x, bp.P.y);
+    deltaTip = normalDeltaTip(bp, penwidth, flag);
+    deltaBase = { x: (penwidth / 2.0) * (bp.P.x / hyp), y: (penwidth / 2.0) * (bp.P.y / hyp) };
+  }
+  return assembleNormal(p0, u, v, { base: deltaBase, tip: deltaTip }, flag);
+}
+
+/** @see lib/common/arrows.c:arrow_type_normal */
+function genNormal(p: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const { a, q } = arrowTypeNormal0(p, u, penwidth, flag);
+  const filled = !(flag & ARR_MOD_OPEN);
+  let points: Point[];
+  if (flag & ARR_MOD_LEFT) points = [a[0], a[1], a[2]];
+  else if (flag & ARR_MOD_RIGHT) points = [a[2], a[3], a[4]];
+  else points = [a[1], a[2], a[3]];
+  return { ops: [{ kind: 'polygon', points, filled }], q };
+}
+
+// ---------------------------------------------------------------------------
+// arrow_type_box
+// @see lib/common/arrows.c:arrow_type_box (:868)
+// ---------------------------------------------------------------------------
+
+const BOX_ARROWWIDTH = 0.4;
+
+/** @see lib/common/arrows.c:arrow_type_box */
+function genBox(p0: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const v: Point = { x: -u.y * BOX_ARROWWIDTH, y: u.x * BOX_ARROWWIDTH };
+  const delta = backwardDelta(u, penwidth); // move backwards to not overlap node
+  const p = vsub(p0, delta);
+  const m = vsub({ x: p0.x + u.x * 0.8, y: p0.y + u.y * 0.8 }, delta);
+  const q = vsub({ x: p0.x + u.x, y: p0.y + u.y }, delta);
+
+  const a: Point[] = [
+    { x: p.x + v.x, y: p.y + v.y },
+    { x: p.x - v.x, y: p.y - v.y },
+    { x: m.x - v.x, y: m.y - v.y },
+    { x: m.x + v.x, y: m.y + v.y },
+  ];
+  if (flag & ARR_MOD_LEFT) { a[0] = p; a[3] = m; }
+  else if (flag & ARR_MOD_RIGHT) { a[1] = p; a[2] = m; }
+  return {
+    ops: [
+      { kind: 'polygon', points: a, filled: !(flag & ARR_MOD_OPEN) },
+      { kind: 'polyline', points: [m, q] },
+    ],
+    q,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// arrow_type_diamond0 / arrow_type_diamond
+// @see lib/common/arrows.c:arrow_type_diamond0 (:926), arrow_type_diamond (:968)
+// ---------------------------------------------------------------------------
+
+/** @see lib/common/arrows.c:arrow_type_diamond0 */
+function arrowTypeDiamond0(p0: Point, u: Point, penwidth: number, flag: number): { a: Point[]; q: Point } {
+  const v: Point = { x: -u.y / 3.0, y: u.x / 3.0 };
+  let r: Point = { x: p0.x + u.x / 2.0, y: p0.y + u.y / 2.0 };
+  let q: Point = { x: p0.x + u.x, y: p0.y + u.y };
+  let p: Point = { x: p0.x, y: p0.y };
+
+  const origin: Point = { x: 0, y: 0 };
+  const unmodLeft = vsub(vscale(-0.5, u), v);
+  const unmodRight = vadd(vscale(-0.5, u), v);
+  const baseLeft = flag & ARR_MOD_RIGHT ? origin : unmodLeft;
+  const baseRight = flag & ARR_MOD_LEFT ? origin : unmodRight;
+  const P = vscale(-1, u);
+
+  const ls = miterShape(baseLeft, P, baseRight, penwidth);
+  const delta = vsub(ls[0], P);
+
+  p = vsub(p, delta);
+  r = vsub(r, delta);
+  q = vsub(q, delta);
+
+  const a: Point[] = new Array<Point>(5);
+  a[0] = a[4] = q;
+  a[1] = { x: r.x + v.x, y: r.y + v.y };
+  a[2] = p;
+  a[3] = { x: r.x - v.x, y: r.y - v.y };
+
+  q = vsub(q, delta);
+  return { a, q };
+}
+
+/** @see lib/common/arrows.c:arrow_type_diamond */
+function genDiamond(p: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const { a, q } = arrowTypeDiamond0(p, u, penwidth, flag);
+  const filled = !(flag & ARR_MOD_OPEN);
+  let points: Point[];
+  if (flag & ARR_MOD_LEFT) points = [a[2], a[3], a[4]];
+  else if (flag & ARR_MOD_RIGHT) points = [a[0], a[1], a[2]];
+  else points = [a[0], a[1], a[2], a[3]];
+  return { ops: [{ kind: 'polygon', points, filled }], q };
+}
+
+// ---------------------------------------------------------------------------
+// arrow_type_dot
+// @see lib/common/arrows.c:arrow_type_dot (:987)
+// ---------------------------------------------------------------------------
+
+/** @see lib/common/arrows.c:arrow_type_dot */
+function genDot(p0: Point, u: Point, _arrowsize: number, penwidth: number, flag: number): GenResult {
+  const r = Math.hypot(u.x, u.y) / 2.0;
+  const delta = backwardDelta(u, penwidth);
+  const p = vsub(p0, delta);
+  const center: Point = { x: p.x + u.x / 2.0, y: p.y + u.y / 2.0 };
+  const q = vsub({ x: p.x + u.x, y: p.y + u.y }, delta);
+  return { ops: [{ kind: 'ellipse', center, rx: r, ry: r, filled: !(flag & ARR_MOD_OPEN) }], q };
+}
+
+// ---------------------------------------------------------------------------
+// Length functions
+// @see lib/common/arrows.c:arrow_length_* (:1182+)
+// ---------------------------------------------------------------------------
+
+/** @see lib/common/arrows.c:arrow_length_generic */
+const arrowLengthGeneric = (lenfact: number, arrowsize: number): number =>
+  lenfact * arrowsize * ARROW_LENGTH;
+
+/** @see lib/common/arrows.c:arrow_length_normal */
+function arrowLengthNormal(lenfact: number, arrowsize: number, penwidth: number, flag: number): number {
+  const u: Point = { x: lenfact * arrowsize * ARROW_LENGTH, y: 0 };
+  const { a, q } = arrowTypeNormal0({ x: 0, y: 0 }, u, penwidth, flag);
+  const base1 = a[1];
+  const base2 = a[3];
+  const tip = a[2];
+  const fullLength = q.x;
+  const nominalLength = Math.abs(base1.x - tip.x);
+  const nominalBaseWidth = base2.y - base1.y;
+  const fullBaseWidth = (nominalBaseWidth * fullLength) / nominalLength;
+  const overlapAtBase = penwidth / 2;
+  const overlapAtTip = (fullLength * penwidth) / fullBaseWidth;
+  const overlap = flag & ARR_MOD_INV ? overlapAtTip : overlapAtBase;
+  return fullLength - overlap;
+}
+
+/** @see lib/common/arrows.c:arrow_length_box */
+const arrowLengthBox = (lenfact: number, arrowsize: number, penwidth: number): number =>
+  lenfact * arrowsize * ARROW_LENGTH + penwidth / 2;
+
+/** @see lib/common/arrows.c:arrow_length_dot */
+const arrowLengthDot = (lenfact: number, arrowsize: number, penwidth: number): number =>
+  lenfact * arrowsize * ARROW_LENGTH + penwidth;
+
+/** @see lib/common/arrows.c:arrow_length_diamond */
+function arrowLengthDiamond(lenfact: number, arrowsize: number, penwidth: number, flag: number): number {
+  const u: Point = { x: lenfact * arrowsize * ARROW_LENGTH, y: 0 };
+  const { a, q } = arrowTypeDiamond0({ x: 0, y: 0 }, u, penwidth, flag);
+  const base1 = a[3];
+  const base2 = a[1];
+  const tip = a[2];
+  const fullLength = q.x / 2;
+  const nominalLength = Math.abs(base1.x - tip.x);
+  const nominalBaseWidth = base2.y - base1.y;
+  const fullBaseWidth = (nominalBaseWidth * fullLength) / nominalLength;
+  const overlapAtTip = (fullLength * penwidth) / fullBaseWidth;
+  return 2 * fullLength - overlapAtTip;
+}
+
+/**
+ * Length of one resolved component (the per-type length function), matching the
+ * `Arrowtypes[].len` dispatch. gap/none use `arrow_length_generic`.
+ *
+ * @see lib/common/arrows.c:arrow_length (per-type dispatch)
+ */
+export function arrowLengthOne(r: ResolvedArrow, arrowsize: number, penwidth: number): number {
+  const flag = arrowFlag(r);
+  switch (r.type & ARR_TYPE_MASK) {
+    case ARR_TYPE_NORM: return arrowLengthNormal(r.lenfact, arrowsize, penwidth, flag);
+    case ARR_TYPE_CROW: return arrowLengthCrow(r.lenfact, arrowsize, penwidth, flag);
+    case ARR_TYPE_TEE: return arrowLengthTee(r.lenfact, arrowsize, penwidth);
+    case ARR_TYPE_BOX: return arrowLengthBox(r.lenfact, arrowsize, penwidth);
+    case ARR_TYPE_DIAMOND: return arrowLengthDiamond(r.lenfact, arrowsize, penwidth, flag);
+    case ARR_TYPE_DOT: return arrowLengthDot(r.lenfact, arrowsize, penwidth);
+    case ARR_TYPE_CURVE: return arrowLengthCurve(r.lenfact, arrowsize, penwidth);
+    default: return arrowLengthGeneric(r.lenfact, arrowsize);
+  }
+}
+
+/**
+ * Total clip length over a parsed compound arrow (sum of component lengths).
+ * Returns 0 when arrowsize is 0, matching `arrow_length`.
+ *
+ * @see lib/common/arrows.c:arrow_length (:253)
+ */
+export function arrowLength(comps: ResolvedArrow[], arrowsize: number, penwidth: number): number {
+  if (arrowsize === 0) return 0;
+  let length = 0;
+  const n = Math.min(comps.length, 4); // NUMB_OF_ARROW_HEADS
+  for (let i = 0; i < n; i++) length += arrowLengthOne(comps[i], arrowsize, penwidth);
+  return length;
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch + compound stacking
+// @see lib/common/arrows.c:arrow_gen_type (:1090), arrow_gen (:1142)
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate draw ops for ONE resolved component at `tip`, with shaft direction
+ * `dir` (tip → base). Dispatches across all eight arrow types.
+ *
+ * @see lib/common/arrows.c:arrow_gen_type
+ */
+export function dispatchSimple(
+  r: ResolvedArrow, tip: Point, dir: Point, arrowsize: number, penwidth: number,
+): GenResult {
+  const flag = arrowFlag(r);
+  const u = componentU(dir, r.lenfact, arrowsize);
+  switch (r.type & ARR_TYPE_MASK) {
+    case ARR_TYPE_CROW: return genCrow(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_TEE: return genTee(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_BOX: return genBox(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_DIAMOND: return genDiamond(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_DOT: return genDot(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_CURVE: return genCurve(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_GAP: return genGap(tip, u, arrowsize, penwidth, flag);
+    case ARR_TYPE_NORM:
+    default:
+      return genNormal(tip, u, arrowsize, penwidth, flag);
+  }
+}
+
+/**
+ * Generate all draw ops for a parsed compound arrow (up to 4 stacked
+ * components). Each component is drawn at the running tip and advances the tip
+ * to its base, matching `arrow_gen`'s loop. Stops at the first NONE component.
+ *
+ * @see lib/common/arrows.c:arrow_gen
+ */
+export function arrowDrawOps(
+  comps: ResolvedArrow[], tip: Point, dir: Point, arrowsize: number, penwidth: number,
+): ArrowDrawOp[] {
+  const ops: ArrowDrawOp[] = [];
+  let p = tip;
+  const n = Math.min(comps.length, 4); // NUMB_OF_ARROW_HEADS
+  for (let i = 0; i < n; i++) {
+    const r = comps[i];
+    if ((r.type & ARR_TYPE_MASK) === ARR_TYPE_NONE) break;
+    const res = dispatchSimple(r, p, dir, arrowsize, penwidth);
+    ops.push(...res.ops);
+    p = res.q;
+  }
+  return ops;
+}

package/src/common/arrows-types.ts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EPL-2.0
+
+/**
+ * Typed arrow draw-op union and the resolved-arrow descriptor.
+ *
+ * graphviz C emits arrowheads at render time as a sequence of primitive draw
+ * calls (`gvrender_polygon` / `gvrender_ellipse` / `gvrender_polyline`). A
+ * single `Point[]` cannot represent an `<ellipse>` (dot/odot) nor a compound
+ * arrow that stacks several primitives, so this port models each emitted
+ * primitive as a discriminated-union op (ADR-1).
+ *
+ * @see lib/common/arrows.c:arrow_gen / arrow_gencode (emit sequence)
+ * @see plans/arrowhead-geometry/decisions.md ADR-1
+ */
+
+import type { Point } from '../model/geom.js';
+
+/**
+ * One primitive draw operation produced for an arrowhead. Geometry is in
+ * graphviz (y-up) space; the SVG y-flip happens later in the renderer.
+ */
+export type ArrowDrawOp =
+  | { readonly kind: 'polygon'; readonly points: Point[]; readonly filled: boolean }
+  | {
+      readonly kind: 'ellipse';
+      readonly center: Point;
+      readonly rx: number;
+      readonly ry: number;
+      readonly filled: boolean;
+    }
+  | { readonly kind: 'polyline'; readonly points: Point[] }
+  // Cubic Bézier path (control points: 1 + 3n). Emitted by the `curve`/`icurve`
+  // arrow types via gvrender_beziercurve. @see lib/common/arrows.c:arrow_type_curve
+  | { readonly kind: 'bezier'; readonly points: Point[] };
+
+/**
+ * A single parsed arrow component resolved to its dispatch info: the
+ * `ARR_TYPE_*` code (with `ARR_MOD_INV` OR'd in for inv/vee/icurve), the
+ * open/side modifiers, and the type's length factor.
+ *
+ * `type` carries the type code in its low `BITS_PER_ARROW_TYPE` bits plus the
+ * `ARR_MOD_INV` bit when the name implies inversion; `open`/`left`/`right`
+ * mirror the user-supplied `o`/`l`/`r` prefix modifiers from the parsed
+ * component.
+ *
+ * @see lib/common/arrows.c:Arrowtypes
+ */
+export interface ResolvedArrow {
+  /** ARR_TYPE_* code, optionally OR'd with ARR_MOD_INV. */
+  readonly type: number;
+  /** Open/outline-only (`o`/`e` prefix, or `empty`/`invempty`). */
+  readonly open: boolean;
+  /** Left half only (`l`/`half` prefix). */
+  readonly left: boolean;
+  /** Right half only (`r` prefix). */
+  readonly right: boolean;
+  /** Ratio of this type's length to the standard ARROW_LENGTH. */
+  readonly lenfact: number;
+}

package/src/common/arrows.ts

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Arrow type definitions, compound arrow parsing, and rendering stubs.
+ * Ported from lib/common/arrows.c and lib/common/arrows.h.
+ *
+ * @see lib/common/arrows.c
+ * @see lib/common/arrows.h
+ */
+
+import type { Point } from '../model/geom.js';
+import type { ResolvedArrow } from './arrows-types.js';
+import {
+  ARROW_NAMES_TABLE, ARROW_SYNONYMS, ARROW_MODS,
+  ARR_MOD_OPEN, ARR_MOD_INV, ARR_MOD_LEFT, ARR_MOD_RIGHT,
+  ARR_TYPE_NORM, ARR_TYPE_CROW, ARR_TYPE_TEE, ARR_TYPE_BOX,
+  ARR_TYPE_DIAMOND, ARR_TYPE_DOT, ARR_TYPE_CURVE, ARR_TYPE_GAP,
+  ARR_TYPE_MASK, ARR_LENFACT_BY_TYPE,
+} from './arrows-constants.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** One component in a parsed compound arrow string. */
+export interface ArrowComponent {
+  name: string;   // user-visible base name (e.g. 'normal', 'dot', 'open')
+  open: boolean;  // 'o' / 'e' modifier
+  left: boolean;  // 'l' / 'half' modifier
+  right: boolean; // 'r' modifier
+}
+
+/** Stub edge type; replaced by real EdgeInfo in T24+. */
+export interface ArrowEdgeStub { attr?: Record<string, string> }
+
+/** Stub port type; replaced by real Port in T24+. */
+export interface ArrowPortStub { x: number; y: number }
+
+/** Stub render job; replaced by real RenderJob in T24+. */
+export interface ArrowJobStub {}
+
+/** Bundled clip arguments — keeps arrowEndClip/arrowStartClip under 5 params. */
+export interface ArrowClipArgs {
+  e: ArrowEdgeStub;
+  psflag: number;
+  eflag: number;
+  sp: ArrowPortStub;
+  ep: ArrowPortStub;
+}
+
+// ---------------------------------------------------------------------------
+// ARROW_NAMES — user-visible names from Arrownames[] + Arrowsynonyms[]
+// Counts: 13 from Arrownames (kludge names resolved) + 1 synonym = 14 total.
+// @see lib/common/arrows.c:Arrownames, Arrowsynonyms
+// ---------------------------------------------------------------------------
+
+/** All valid user-facing arrow type names from arrows.c. */
+export const ARROW_NAMES: readonly string[] = [
+  'normal', 'crow', 'tee', 'box', 'diamond', 'dot', 'none',
+  'inv', 'vee', 'open', 'empty', 'curve', 'icurve', 'invempty',
+];
+
+// ---------------------------------------------------------------------------
+// Parsing helpers (mirrors arrow_match_name_frag / arrow_match_name in C)
+// ---------------------------------------------------------------------------
+
+/** Try synonym table first. @see lib/common/arrows.c:Arrowsynonyms */
+const matchSynonym = (s: string): { flag: number; rest: string } | null => {
+  for (const syn of ARROW_SYNONYMS) {
+    if (s.startsWith(syn.name)) return { flag: syn.type, rest: s.slice(syn.name.length) };
+  }
+  return null;
+};
+
+/** Greedily consume modifier prefixes. @see lib/common/arrows.c:Arrowmods */
+const matchMods = (s: string): { flag: number; rest: string } => {
+  let flag = 0; let rest = s; let matched = true;
+  while (matched) {
+    matched = false;
+    for (const mod of ARROW_MODS) {
+      if (rest.startsWith(mod.name)) {
+        flag |= mod.type; rest = rest.slice(mod.name.length); matched = true; break;
+      }
+    }
+  }
+  return { flag, rest };
+};
+
+/** Match one base name from Arrownames[]. @see lib/common/arrows.c:Arrownames */
+const matchBase = (s: string): { flag: number; baseName: string; rest: string } | null => {
+  for (const entry of ARROW_NAMES_TABLE) {
+    if (s.startsWith(entry.name))
+      return { flag: entry.type, baseName: entry.name, rest: s.slice(entry.name.length) };
+  }
+  return null;
+};
+
+/** Resolve internal kludge names to user-visible names. */
+const resolveBaseName = (n: string): string =>
+  n === 'pen' ? 'open' : n === 'mpty' ? 'empty' : n;
+
+/** Parse one arrow component from the front of s. */
+const parseOne = (s: string): { comp: ArrowComponent; rest: string } | null => {
+  const syn = matchSynonym(s);
+  if (syn) {
+    const f = syn.flag;
+    return { comp: { name: 'invempty', open: !!(f & ARR_MOD_OPEN), left: !!(f & ARR_MOD_LEFT), right: !!(f & ARR_MOD_RIGHT) }, rest: syn.rest };
+  }
+  const { flag: mf, rest: mr } = matchMods(s);
+  const base = matchBase(mr);
+  if (!base) return null;
+  const f = mf | base.flag;
+  return { comp: { name: resolveBaseName(base.baseName), open: !!(f & ARR_MOD_OPEN), left: !!(f & ARR_MOD_LEFT), right: !!(f & ARR_MOD_RIGHT) }, rest: base.rest };
+};
+
+// ---------------------------------------------------------------------------
+// parseArrow  (@see lib/common/arrows.c:arrow_type)
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse a compound arrow type string into its components.
+ * E.g. "odot" → [{name:'dot', open:true, left:false, right:false}]
+ *
+ * @see lib/common/arrows.c:arrow_type
+ */
+export function parseArrow(str: string): ArrowComponent[] {
+  const result: ArrowComponent[] = [];
+  let s = str;
+  while (s.length > 0) {
+    const m = parseOne(s);
+    if (!m) break;
+    result.push(m.comp);
+    s = m.rest;
+  }
+  if (result.length === 0) result.push({ name: 'normal', open: false, left: false, right: false });
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// resolveArrowType — parsed component → dispatch info
+// @see lib/common/arrows.c:Arrownames, Arrowsynonyms, Arrowtypes
+// ---------------------------------------------------------------------------
+
+/**
+ * User-visible base name → full type flag (type code + ARR_MOD_INV where the
+ * name implies inversion). Mirrors Arrownames[]/Arrowsynonyms[], but keyed by
+ * the resolved user-facing names produced by {@link parseArrow} (e.g. 'open',
+ * 'empty', 'invempty') rather than the internal kludge fragments ('pen',
+ * 'mpty'). Open/left/right modifiers are tracked on the component itself, so
+ * only the type code and INV bit are encoded here.
+ *
+ * @see lib/common/arrows.c:Arrownames
+ */
+const NAME_TO_FLAG: ReadonlyMap<string, number> = new Map([
+  ['normal', ARR_TYPE_NORM],
+  ['crow', ARR_TYPE_CROW],
+  ['tee', ARR_TYPE_TEE],
+  ['box', ARR_TYPE_BOX],
+  ['diamond', ARR_TYPE_DIAMOND],
+  ['dot', ARR_TYPE_DOT],
+  ['none', ARR_TYPE_GAP],
+  ['inv', ARR_TYPE_NORM | ARR_MOD_INV],
+  ['vee', ARR_TYPE_CROW | ARR_MOD_INV],
+  ['open', ARR_TYPE_CROW | ARR_MOD_INV], // "pen" kludge: open == vee
+  ['empty', ARR_TYPE_NORM],              // "mpty" kludge: empty == open normal
+  ['curve', ARR_TYPE_CURVE],
+  ['icurve', ARR_TYPE_CURVE | ARR_MOD_INV],
+  ['invempty', ARR_TYPE_NORM | ARR_MOD_INV], // synonym (OPEN tracked on comp)
+]);
+
+/**
+ * Resolve a parsed arrow component to its dispatch info: ARR_TYPE_* code (with
+ * ARR_MOD_INV OR'd in for inv/vee/icurve), the open/side modifiers, and the
+ * type's length factor. An unknown name resolves to ARR_TYPE_NORM, matching the
+ * C default when no name fragment matches.
+ *
+ * @see lib/common/arrows.c:Arrowtypes (lenfact column)
+ */
+export function resolveArrowType(comp: ArrowComponent): ResolvedArrow {
+  const flag = NAME_TO_FLAG.get(comp.name) ?? ARR_TYPE_NORM;
+  const typeCode = flag & ARR_TYPE_MASK;
+  const inv = (flag & ARR_MOD_INV) !== 0;
+  return {
+    type: typeCode | (inv ? ARR_MOD_INV : 0),
+    open: comp.open,
+    left: comp.left,
+    right: comp.right,
+    lenfact: ARR_LENFACT_BY_TYPE[typeCode] ?? ARR_LENFACT_BY_TYPE[ARR_TYPE_NORM],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Clip stubs (geometry implemented in T24 when RenderJob is available)
+// ---------------------------------------------------------------------------
+
+/**
+ * Clip edge spline at arrowhead end and emit drawing calls.
+ * Stub implementation; fully ported in T24.
+ *
+ * @see lib/common/arrows.c:arrowEndClip
+ */
+export function arrowEndClip(_args: ArrowClipArgs, _ps: Point[], _job: ArrowJobStub): void {}
+
+/**
+ * Clip edge spline at arrowtail start and emit drawing calls.
+ * Stub implementation; fully ported in T24.
+ *
+ * @see lib/common/arrows.c:arrowStartClip
+ */
+export function arrowStartClip(_args: ArrowClipArgs, _ps: Point[], _job: ArrowJobStub): void {}