@knowvah/dot-engine 0.1.0

package/src/pathplan/route.ts

@@ -0,0 +1,284 @@
+// SPDX-License-Identifier: EPL-2.0
+/** @see lib/pathplan/route.c, lib/pathplan/util.c */
+
+import type { Point, Poly, Edge } from './types.js';
+import { solve3 } from './solvers.js';
+
+const EPSILON1 = 1e-3;
+const EPSILON2 = 1e-6;
+
+interface Tna { t: number; a: [Point, Point]; }
+interface SplineEndpoints { p0: Point; v0: Point; p1: Point; v1: Point; }
+interface LineCoeff { xc0: number; xc1: number; yc0: number; yc1: number; }
+interface RootAccum { roots: number[]; n: number; }
+interface RouteState { ops: Point[]; barriers: Edge[]; }
+
+class RouteHelper {
+  static B0(t: number): number { const u = 1-t; return u*u*u; }
+  static B1(t: number): number { const u = 1-t; return 3*t*u*u; }
+  static B2(t: number): number { const u = 1-t; return 3*t*t*u; }
+  static B3(t: number): number { return t*t*t; }
+  static B01(t: number): number { const u = 1-t; return u*u*(u+3*t); }
+  static B23(t: number): number { const u = 1-t; return t*t*(3*u+t); }
+
+  static normv(v: Point): Point {
+    const d = v.x*v.x + v.y*v.y;
+    if (d > 1e-6) { const s = Math.sqrt(d); return { x: v.x/s, y: v.y/s }; }
+    return v;
+  }
+  static ptAdd(a: Point, b: Point): Point { return { x: a.x+b.x, y: a.y+b.y }; }
+  static ptSub(a: Point, b: Point): Point { return { x: a.x-b.x, y: a.y-b.y }; }
+  static ptScale(p: Point, c: number): Point { return { x: p.x*c, y: p.y*c }; }
+  static ptDot(a: Point, b: Point): number { return a.x*b.x + a.y*b.y; }
+  static ptDist(a: Point, b: Point): number { return Math.hypot(a.x-b.x, a.y-b.y); }
+  static distN(pts: Point[]): number {
+    let rv = 0;
+    for (let i = 1; i < pts.length; i++) rv += RouteHelper.ptDist(pts[i], pts[i-1]);
+    return rv;
+  }
+
+  static points2coeff(v0: number, v1: number, v2: number, v3: number, c: number[]): void {
+    c[3] = v3 + 3*v1 - (v0 + 3*v2);
+    c[2] = 3*v0 + 3*v2 - 6*v1;
+    c[1] = 3*(v1 - v0);
+    c[0] = v0;
+  }
+
+  static addRoot(root: number, acc: RootAccum): void {
+    if (root >= 0 && root <= 1) { acc.roots[acc.n] = root; acc.n++; }
+  }
+
+  static silBothZero(sps: Point[], lc: LineCoeff, acc: RootAccum): number {
+    const sc = [0,0,0,0], xr = [0,0,0], yr = [0,0,0];
+    RouteHelper.points2coeff(sps[0].x, sps[1].x, sps[2].x, sps[3].x, sc);
+    sc[0] -= lc.xc0;
+    const xn = solve3(sc, xr);
+    RouteHelper.points2coeff(sps[0].y, sps[1].y, sps[2].y, sps[3].y, sc);
+    sc[0] -= lc.yc0;
+    const yn = solve3(sc, yr);
+    if (xn === 4) {
+      if (yn === 4) return 4;
+      for (let j = 0; j < yn; j++) RouteHelper.addRoot(yr[j], acc);
+    } else if (yn === 4) {
+      for (let i = 0; i < xn; i++) RouteHelper.addRoot(xr[i], acc);
+    } else {
+      for (let i = 0; i < xn; i++)
+        for (let j = 0; j < yn; j++)
+          if (xr[i] === yr[j]) RouteHelper.addRoot(xr[i], acc);
+    }
+    return acc.n;
+  }
+
+  static silXzeroYnonzero(sps: Point[], lc: LineCoeff, acc: RootAccum): number {
+    const sc = [0,0,0,0], xr = [0,0,0];
+    RouteHelper.points2coeff(sps[0].x, sps[1].x, sps[2].x, sps[3].x, sc);
+    sc[0] -= lc.xc0;
+    const xn = solve3(sc, xr);
+    if (xn === 4) return 4;
+    for (let i = 0; i < xn; i++) {
+      const tv = xr[i];
+      if (tv >= 0 && tv <= 1) {
+        RouteHelper.points2coeff(sps[0].y, sps[1].y, sps[2].y, sps[3].y, sc);
+        const sv = (sc[0] + tv*(sc[1] + tv*(sc[2] + tv*sc[3])) - lc.yc0) / lc.yc1;
+        if (sv >= 0 && sv <= 1) RouteHelper.addRoot(tv, acc);
+      }
+    }
+    return acc.n;
+  }
+
+  static silGeneral(sps: Point[], lc: LineCoeff, acc: RootAccum): number {
+    const sc = [0,0,0,0], xr = [0,0,0];
+    const rat = lc.yc1 / lc.xc1;
+    RouteHelper.points2coeff(
+      sps[0].y - rat*sps[0].x, sps[1].y - rat*sps[1].x,
+      sps[2].y - rat*sps[2].x, sps[3].y - rat*sps[3].x, sc);
+    sc[0] += rat*lc.xc0 - lc.yc0;
+    const xn = solve3(sc, xr);
+    if (xn === 4) return 4;
+    for (let i = 0; i < xn; i++) {
+      const tv = xr[i];
+      if (tv >= 0 && tv <= 1) {
+        RouteHelper.points2coeff(sps[0].x, sps[1].x, sps[2].x, sps[3].x, sc);
+        const sv = (sc[0] + tv*(sc[1] + tv*(sc[2] + tv*sc[3])) - lc.xc0) / lc.xc1;
+        if (sv >= 0 && sv <= 1) RouteHelper.addRoot(tv, acc);
+      }
+    }
+    return acc.n;
+  }
+
+  static splineIntersectsLine(sps: Point[], lps: Point[], roots: number[]): number {
+    const lc: LineCoeff = {
+      xc0: lps[0].x, xc1: lps[1].x - lps[0].x,
+      yc0: lps[0].y, yc1: lps[1].y - lps[0].y,
+    };
+    const acc: RootAccum = { roots, n: 0 };
+    if (lc.xc1 === 0) {
+      if (lc.yc1 === 0) return RouteHelper.silBothZero(sps, lc, acc);
+      return RouteHelper.silXzeroYnonzero(sps, lc, acc);
+    }
+    return RouteHelper.silGeneral(sps, lc, acc);
+  }
+
+  static splineIsInside(barriers: Edge[], sps: Point[]): boolean {
+    const roots = [0,0,0,0];
+    for (let ei = 0; ei < barriers.length; ei++) {
+      const lps = [barriers[ei].a, barriers[ei].b];
+      const rootn = RouteHelper.splineIntersectsLine(sps, lps, roots);
+      if (rootn === 4) continue;
+      for (let ri = 0; ri < rootn; ri++) {
+        const t = roots[ri];
+        if (t < EPSILON2 || t > 1 - EPSILON2) continue;
+        const ta = (1-t)*(1-t)*(1-t), tb = 3*t*(1-t)*(1-t), tc = 3*t*t*(1-t), td = t*t*t;
+        const ix = ta*sps[0].x + tb*sps[1].x + tc*sps[2].x + td*sps[3].x;
+        const iy = ta*sps[0].y + tb*sps[1].y + tc*sps[2].y + td*sps[3].y;
+        if ((ix-lps[0].x)**2+(iy-lps[0].y)**2 < EPSILON1) continue;
+        if ((ix-lps[1].x)**2+(iy-lps[1].y)**2 < EPSILON1) continue;
+        return false;
+      }
+    }
+    return true;
+  }
+
+  static appendSps(ops: Point[], sps: Point[]): void {
+    for (let pi = 1; pi < 4; pi++) ops.push({ x: sps[pi].x, y: sps[pi].y });
+  }
+
+  static mkspline(inps: Point[], tnas: Tna[], ev0: Point, ev1: Point): SplineEndpoints {
+    const n = inps.length;
+    let scale0 = 0, scale3 = 0, c00 = 0, c01 = 0, c11 = 0, x0 = 0, x1 = 0;
+    for (let i = 0; i < n; i++) {
+      c00 += RouteHelper.ptDot(tnas[i].a[0], tnas[i].a[0]);
+      c01 += RouteHelper.ptDot(tnas[i].a[0], tnas[i].a[1]);
+      c11 += RouteHelper.ptDot(tnas[i].a[1], tnas[i].a[1]);
+      const tmp = RouteHelper.ptSub(inps[i], RouteHelper.ptAdd(
+        RouteHelper.ptScale(inps[0], RouteHelper.B01(tnas[i].t)),
+        RouteHelper.ptScale(inps[n-1], RouteHelper.B23(tnas[i].t))));
+      x0 += RouteHelper.ptDot(tnas[i].a[0], tmp);
+      x1 += RouteHelper.ptDot(tnas[i].a[1], tmp);
+    }
+    const det01 = c00*c11 - c01*c01;
+    const detX1 = x0*c11 - x1*c01, det0X = c00*x1 - c01*x0;
+    if (Math.abs(det01) >= 1e-6) { scale0 = detX1/det01; scale3 = det0X/det01; }
+    if (Math.abs(det01) < 1e-6 || scale0 <= 0 || scale3 <= 0) {
+      const d = RouteHelper.ptDist(inps[0], inps[n-1]) / 3;
+      scale0 = d; scale3 = d;
+    }
+    return { p0: inps[0], v0: RouteHelper.ptScale(ev0, scale0), p1: inps[n-1], v1: RouteHelper.ptScale(ev1, scale3) };
+  }
+
+  static initTnas(inps: Point[], ev0: Point, ev1: Point): Tna[] {
+    const n = inps.length;
+    const tnas: Tna[] = Array.from({ length: n }, () => ({ t: 0, a: [{ x:0,y:0 }, { x:0,y:0 }] as [Point,Point] }));
+    for (let i = 1; i < n; i++) tnas[i].t = tnas[i-1].t + RouteHelper.ptDist(inps[i], inps[i-1]);
+    const total = tnas[n-1].t;
+    for (let i = 1; i < n; i++) tnas[i].t /= total;
+    for (let i = 0; i < n; i++) {
+      tnas[i].a[0] = RouteHelper.ptScale(ev0, RouteHelper.B1(tnas[i].t));
+      tnas[i].a[1] = RouteHelper.ptScale(ev1, RouteHelper.B2(tnas[i].t));
+    }
+    return tnas;
+  }
+
+  static findMaxDev(inps: Point[], tnas: Tna[], ends: SplineEndpoints): number {
+    const { p0, v0, p1, v1 } = ends;
+    const cp1 = RouteHelper.ptAdd(p0, RouteHelper.ptScale(v0, 1/3));
+    const cp2 = RouteHelper.ptSub(p1, RouteHelper.ptScale(v1, 1/3));
+    let maxi = -1, maxd = -1;
+    for (let i = 1; i < inps.length - 1; i++) {
+      const t = tnas[i].t;
+      const px = RouteHelper.B0(t)*p0.x + RouteHelper.B1(t)*cp1.x + RouteHelper.B2(t)*cp2.x + RouteHelper.B3(t)*p1.x;
+      const py = RouteHelper.B0(t)*p0.y + RouteHelper.B1(t)*cp1.y + RouteHelper.B2(t)*cp2.y + RouteHelper.B3(t)*p1.y;
+      const d = RouteHelper.ptDist({ x: px, y: py }, inps[i]);
+      // C `reallyroutespline` uses strict `if (d > maxd)`. On a geometrically
+      // SYMMETRIC channel the two interior deviations are an exact tie, and the
+      // winner is then decided by ~1e-14 cancellation noise in the
+      // absolute-coordinate bezier eval above — whose sign depends on absolute
+      // position. So C is NOT consistent: it splits two translation-congruent
+      // arcs toward opposite corners (e.g. 2368 `376->76` mirrors `256->436`),
+      // because Apple's macOS libm `hypot` (which generated the oracle) is a
+      // proprietary ~1-ULP-divergent implementation that no portable hypot
+      // reproduces. We deliberately keep the tolerant tie-break: a true tie
+      // always resolves to the first index, so the port is TRANSLATION-
+      // EQUIVARIANT (same channel anywhere -> same spline). This matches C where
+      // C's noise also keeps-first (#241_0 5:ne->8:nw, and the cnt=3 oracle
+      // case) and consciously diverges where C's noise keeps-second (2368
+      // `376->76`, the lone surviving residual: structural-match, maxΔ ~10pt on
+      // one flat-edge arc). See .agent-notes/2368-residual-flat-label-ranksep.md
+      // and the pow precedent (src/common/arm-pow.ts) for the same Apple-libm
+      // boundary. @see lib/pathplan/route.c:reallyroutespline (max-deviation split)
+      if (d > maxd * (1 + 1e-10) + 1e-10) { maxd = d; maxi = i; }
+    }
+    return maxi;
+  }
+
+  static splineFits(state: RouteState, ends: SplineEndpoints, inps: Point[]): number {
+    const { p0, v0, p1, v1 } = ends;
+    const forceflag = inps.length === 2;
+    let a = 4, first = true;
+    for (;;) {
+      const sps: Point[] = [
+        p0,
+        { x: p0.x + a*v0.x/3, y: p0.y + a*v0.y/3 },
+        { x: p1.x - a*v1.x/3, y: p1.y - a*v1.y/3 },
+        p1,
+      ];
+      if (first && RouteHelper.distN(sps) < RouteHelper.distN(inps) - EPSILON1) return 0;
+      first = false;
+      if (RouteHelper.splineIsInside(state.barriers, sps)) {
+        RouteHelper.appendSps(state.ops, sps); return 1;
+      }
+      if (a < 0.005) {
+        if (forceflag) { RouteHelper.appendSps(state.ops, sps); return 1; }
+        break;
+      }
+      a = a > 0.01 ? a / 2 : 0;
+    }
+    return 0;
+  }
+
+  static reallyRoute(state: RouteState, inps: Point[], ev0: Point, ev1: Point): boolean {
+    const tnas = RouteHelper.initTnas(inps, ev0, ev1);
+    const ends = RouteHelper.mkspline(inps, tnas, ev0, ev1);
+    if (RouteHelper.splineFits(state, ends, inps)) return true;
+    const maxi = RouteHelper.findMaxDev(inps, tnas, ends);
+    const sv1 = RouteHelper.normv(RouteHelper.ptSub(inps[maxi], inps[maxi - 1]));
+    const sv2 = RouteHelper.normv(RouteHelper.ptSub(inps[maxi + 1], inps[maxi]));
+    const splitv = RouteHelper.normv(RouteHelper.ptAdd(sv1, sv2));
+    if (!RouteHelper.reallyRoute(state, inps.slice(0, maxi + 1), ev0, splitv)) return false;
+    if (!RouteHelper.reallyRoute(state, inps.slice(maxi), splitv, ev1)) return false;
+    return true;
+  }
+
+  static run(barriers: Edge[], route: Point[], slopes: [Point, Point]): Point[] {
+    const state: RouteState = { ops: [], barriers };
+    const ev0 = RouteHelper.normv(slopes[0]);
+    const ev1 = RouteHelper.normv(slopes[1]);
+    state.ops.push(route[0]);
+    RouteHelper.reallyRoute(state, route, ev0, ev1);
+    return state.ops;
+  }
+}
+
+/** @see lib/pathplan/route.c:Proutespline */
+export function routeSpline(barriers: Edge[], route: Point[], slopes: [Point, Point]): Point[] {
+  return RouteHelper.run(barriers, route, slopes);
+}
+
+/** @see lib/pathplan/util.c:Ppolybarriers */
+export function polyBarriers(polys: Poly[]): Edge[] {
+  const out: Edge[] = [];
+  for (const poly of polys) {
+    const n = poly.ps.length;
+    for (let j = 0; j < n; j++) out.push({ a: poly.ps[j], b: poly.ps[(j + 1) % n] });
+  }
+  return out;
+}
+
+/** @see lib/pathplan/util.c:make_polyline */
+export function makePolyline(pts: Point[]): Point[] {
+  const out: Point[] = [];
+  out.push(pts[0], pts[0]);
+  for (let i = 1; i + 1 < pts.length; i++) out.push(pts[i], pts[i], pts[i]);
+  out.push(pts[pts.length - 1], pts[pts.length - 1]);
+  return out;
+}

package/src/pathplan/shortest.ts

@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: EPL-2.0
+/** @see lib/pathplan/shortest.c */
+
+import type { Point, Poly } from './types.js';
+import { ccw, isdiagonal, ISCCW, ISCW } from './triang.js';
+
+const NO_TRI = -1;
+const DQ_FRONT = 1;
+const DQ_BACK = 2;
+
+interface PNL { pp: Point; link: PNL | null; }
+interface TEdge { pnl0: PNL; pnl1: PNL; rightIndex: number; }
+interface Triangle { mark: number; e: [TEdge, TEdge, TEdge]; }
+interface Deque { pnlps: PNL[]; pnlpn: number; fpnlpi: number; lpnlpi: number; apex: number; }
+
+class ShortestHelper {
+  static buildTri(a: PNL, b: PNL, c: PNL): Triangle {
+    const mk = (p0: PNL, p1: PNL): TEdge => ({ pnl0: p0, pnl1: p1, rightIndex: NO_TRI });
+    return { mark: 0, e: [mk(a, b), mk(b, c), mk(c, a)] };
+  }
+
+  static triInner(pnlps: PNL[], tris: Triangle[]): boolean {
+    // C triangulate() is tail-recursive: `return triangulate(points, n-1)` after
+    // storing one ear triangle (shortest.c). The recursion depth equals the
+    // polygon vertex count, so a large routing polygon (a long edge spanning many
+    // ranks) overflows V8's stack, which has no TCO. Faithful loop form per the
+    // AD-3 recursion->iteration pattern: same ear per pass, same store order,
+    // same return value.
+    let pts = pnlps;
+    while (pts.length > 3) {
+      const n = pts.length;
+      let cut = -1;
+      for (let i = 0; i < n; i++) {
+        const ip2 = (i + 2) % n;
+        if (isdiagonal(i, ip2, k => pts[k].pp, n)) {
+          tris.push(ShortestHelper.buildTri(pts[i], pts[(i+1)%n], pts[ip2]));
+          cut = (i + 1) % n;
+          break;
+        }
+      }
+      if (cut === -1) return false; // C: prerror("triangulation failed"); return 0
+      pts = pts.filter((_, j) => j !== cut);
+    }
+    tris.push(ShortestHelper.buildTri(pts[0], pts[1], pts[2]));
+    return true;
+  }
+
+  static connectTri(i: number, j: number, tris: Triangle[]): void {
+    const t1 = tris[i], t2 = tris[j];
+    for (let ei = 0; ei < 3; ei++) {
+      for (let ej = 0; ej < 3; ej++) {
+        const e1 = t1.e[ei], e2 = t2.e[ej];
+        if ((e1.pnl0 === e2.pnl0 && e1.pnl1 === e2.pnl1) ||
+            (e1.pnl0 === e2.pnl1 && e1.pnl1 === e2.pnl0))
+          e1.rightIndex = j, e2.rightIndex = i;
+      }
+    }
+  }
+
+  static connectAll(tris: Triangle[]): void {
+    for (let i = 0; i < tris.length; i++)
+      for (let j = i + 1; j < tris.length; j++)
+        ShortestHelper.connectTri(i, j, tris);
+  }
+
+  static pointInTri(tri: Triangle, p: Point): boolean {
+    let sum = 0;
+    for (let ei = 0; ei < 3; ei++)
+      if (ccw(tri.e[ei].pnl0.pp, tri.e[ei].pnl1.pp, p) !== ISCW) sum++;
+    return sum === 3 || sum === 0;
+  }
+
+  static markPath(tris: Triangle[], trii: number, trij: number): boolean {
+    if (tris[trii].mark) return false;
+    tris[trii].mark = 1;
+    if (trii === trij) return true;
+    for (let ei = 0; ei < 3; ei++) {
+      const ri = tris[trii].e[ei].rightIndex;
+      if (ri !== NO_TRI && ShortestHelper.markPath(tris, ri, trij)) return true;
+    }
+    tris[trii].mark = 0;
+    return false;
+  }
+
+  static findTri(tris: Triangle[], p: Point): number {
+    for (let i = 0; i < tris.length; i++)
+      if (ShortestHelper.pointInTri(tris[i], p)) return i;
+    return NO_TRI;
+  }
+
+  static findMinX(ps: Point[]): number {
+    let minx = Infinity, minpi = 0;
+    for (let i = 0; i < ps.length; i++)
+      if (ps[i].x < minx) { minx = ps[i].x; minpi = i; }
+    return minpi;
+  }
+
+  static isPolyCW(ps: Point[], minpi: number): boolean {
+    const pn = ps.length;
+    const p2 = ps[minpi];
+    const p1 = ps[minpi === 0 ? pn - 1 : minpi - 1];
+    const p3 = ps[(minpi + 1) % pn];
+    if (p1.x === p2.x && p2.x === p3.x && p3.y > p2.y) return true;
+    return ccw(p1, p2, p3) !== ISCCW;
+  }
+
+  static loadForward(ps: Point[]): PNL[] {
+    const r: PNL[] = [];
+    for (let i = 0; i < ps.length; i++) {
+      if (i > 0 && ps[i].x === ps[i-1].x && ps[i].y === ps[i-1].y) continue;
+      r.push({ pp: ps[i], link: null });
+    }
+    return r;
+  }
+
+  static loadReverse(ps: Point[]): PNL[] {
+    const r: PNL[] = [];
+    for (let i = ps.length - 1; i >= 0; i--) {
+      if (i < ps.length-1 && ps[i].x === ps[i+1].x && ps[i].y === ps[i+1].y) continue;
+      r.push({ pp: ps[i], link: null });
+    }
+    return r;
+  }
+
+  static loadPoints(poly: Poly): PNL[] {
+    const ps = poly.ps;
+    return ShortestHelper.isPolyCW(ps, ShortestHelper.findMinX(ps))
+      ? ShortestHelper.loadReverse(ps)
+      : ShortestHelper.loadForward(ps);
+  }
+
+  static initDeque(pnll: number): Deque {
+    const pnlpn = pnll * 2;
+    const pnlps = new Array<PNL>(pnlpn).fill(null as unknown as PNL);
+    const fpnlpi = Math.floor(pnlpn / 2);
+    return { pnlps, pnlpn, fpnlpi, lpnlpi: fpnlpi - 1, apex: 0 };
+  }
+
+  static add2dq(dq: Deque, side: number, pnl: PNL): void {
+    if (side === DQ_FRONT) {
+      if (dq.lpnlpi >= dq.fpnlpi) pnl.link = dq.pnlps[dq.fpnlpi];
+      dq.fpnlpi--;
+      dq.pnlps[dq.fpnlpi] = pnl;
+    } else {
+      if (dq.lpnlpi >= dq.fpnlpi) pnl.link = dq.pnlps[dq.lpnlpi];
+      dq.lpnlpi++;
+      dq.pnlps[dq.lpnlpi] = pnl;
+    }
+  }
+
+  static splitdq(dq: Deque, side: number, index: number): void {
+    if (side === DQ_FRONT) dq.lpnlpi = index;
+    else dq.fpnlpi = index;
+  }
+
+  static finddqsplit(dq: Deque, pnl: PNL): number {
+    for (let idx = dq.fpnlpi; idx < dq.apex; idx++)
+      if (ccw(dq.pnlps[idx+1].pp, dq.pnlps[idx].pp, pnl.pp) === ISCCW) return idx;
+    for (let idx = dq.lpnlpi; idx > dq.apex; idx--)
+      if (ccw(dq.pnlps[idx-1].pp, dq.pnlps[idx].pp, pnl.pp) === ISCW) return idx;
+    return dq.apex;
+  }
+
+  static fuFindEi(trip: Triangle, tris: Triangle[]): number {
+    for (let ei = 0; ei < 3; ei++) {
+      const ri = trip.e[ei].rightIndex;
+      if (ri !== NO_TRI && tris[ri].mark === 1) return ei;
+    }
+    return 3;
+  }
+
+  static fuNextTri(trip: Triangle, tris: Triangle[]): number {
+    for (let ei = 0; ei < 3; ei++) {
+      const ri = trip.e[ei].rightIndex;
+      if (ri !== NO_TRI && tris[ri].mark === 1) return ri;
+    }
+    return NO_TRI;
+  }
+
+  static fuGetPairLast(epnl1: PNL, dq: Deque): [PNL, PNL] {
+    if (ccw(epnl1.pp, dq.pnlps[dq.fpnlpi].pp, dq.pnlps[dq.lpnlpi].pp) === ISCCW)
+      return [dq.pnlps[dq.lpnlpi], epnl1];
+    return [epnl1, dq.pnlps[dq.lpnlpi]];
+  }
+
+  static fuGetPairNormal(trip: Triangle, ei: number): [PNL, PNL] {
+    const e = trip.e[ei];
+    const pnl = trip.e[(ei + 1) % 3].pnl1;
+    if (ccw(e.pnl0.pp, pnl.pp, e.pnl1.pp) === ISCCW) return [e.pnl1, e.pnl0];
+    return [e.pnl0, e.pnl1];
+  }
+
+  static fuUpdateRight(dq: Deque, r: PNL): void {
+    const si = ShortestHelper.finddqsplit(dq, r);
+    ShortestHelper.splitdq(dq, DQ_BACK, si);
+    ShortestHelper.add2dq(dq, DQ_FRONT, r);
+    if (si > dq.apex) dq.apex = si;
+  }
+
+  static fuUpdateLeft(dq: Deque, l: PNL): void {
+    const si = ShortestHelper.finddqsplit(dq, l);
+    ShortestHelper.splitdq(dq, DQ_FRONT, si);
+    ShortestHelper.add2dq(dq, DQ_BACK, l);
+    if (si < dq.apex) dq.apex = si;
+  }
+
+  static fuUpdate(dq: Deque, l: PNL, r: PNL, isFirst: boolean): void {
+    if (isFirst) {
+      ShortestHelper.add2dq(dq, DQ_BACK, l);
+      ShortestHelper.add2dq(dq, DQ_FRONT, r);
+      return;
+    }
+    if (dq.pnlps[dq.fpnlpi] !== r && dq.pnlps[dq.lpnlpi] !== r)
+      ShortestHelper.fuUpdateRight(dq, r);
+    else
+      ShortestHelper.fuUpdateLeft(dq, l);
+  }
+
+  static fuLoop(tris: Triangle[], dq: Deque, epnls: [PNL, PNL], ftrii: number): void {
+    let trii: number = ftrii;
+    while (trii !== NO_TRI) {
+      const trip = tris[trii]; trip.mark = 2;
+      const ei = ShortestHelper.fuFindEi(trip, tris);
+      const [l, r] = ei === 3
+        ? ShortestHelper.fuGetPairLast(epnls[1], dq)
+        : ShortestHelper.fuGetPairNormal(trip, ei);
+      ShortestHelper.fuUpdate(dq, l, r, trii === ftrii);
+      trii = ShortestHelper.fuNextTri(trip, tris);
+    }
+  }
+
+  static extractPath(epnl1: PNL): Point[] {
+    const pts: Point[] = [];
+    for (let p: PNL | null = epnl1; p !== null; p = p.link) pts.push(p.pp);
+    pts.reverse();
+    return pts;
+  }
+
+  static run(poly: Poly, eps: [Point, Point]): Point[] | null {
+    const pnlps = ShortestHelper.loadPoints(poly);
+    const tris: Triangle[] = [];
+    // C's triangulate() treats an ear-clip dead end as a WARNING and returns
+    // success with the triangles loaded so far; Pshortestpath continues on the
+    // partial triangulation (and typically ends in marktripath's straight-line
+    // fallback below). Treating it as fatal loses edges C keeps (corpus 1435,
+    // edge 8->10). @see lib/pathplan/shortest.c:333
+    if (!ShortestHelper.triInner(pnlps.slice(), tris)) {
+      console.warn('triangulation failed');
+    }
+    ShortestHelper.connectAll(tris);
+    const ftrii = ShortestHelper.findTri(tris, eps[0]);
+    const ltrii = ShortestHelper.findTri(tris, eps[1]);
+    if (ftrii === NO_TRI || ltrii === NO_TRI) return null;
+    if (ftrii === ltrii) return [eps[0], eps[1]];
+    if (!ShortestHelper.markPath(tris, ftrii, ltrii)) return [eps[0], eps[1]];
+    const epnls: [PNL, PNL] = [{ pp: eps[0], link: null }, { pp: eps[1], link: null }];
+    const dq = ShortestHelper.initDeque(pnlps.length);
+    ShortestHelper.add2dq(dq, DQ_FRONT, epnls[0]);
+    dq.apex = dq.fpnlpi;
+    ShortestHelper.fuLoop(tris, dq, epnls, ftrii);
+    return ShortestHelper.extractPath(epnls[1]);
+  }
+}
+
+/** @see lib/pathplan/shortest.c:Pshortestpath */
+export function shortestPath(poly: Poly, eps: [Point, Point]): Point[] | null {
+  return ShortestHelper.run(poly, eps);
+}

package/src/pathplan/solvers.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: EPL-2.0
+/** @see lib/pathplan/solvers.c */
+
+const EPS = 1e-7;
+
+class Solver {
+  static aeq0(x: number): boolean {
+    return x < EPS && x > -EPS;
+  }
+
+  static solve1(c: number[], r: number[]): number {
+    if (Solver.aeq0(c[1])) return Solver.aeq0(c[0]) ? 4 : 0;
+    r[0] = -c[0] / c[1];
+    return 1;
+  }
+
+  static solve2(c: number[], r: number[]): number {
+    if (Solver.aeq0(c[2])) return Solver.solve1(c, r);
+    const b2a = c[1] / (2 * c[2]);
+    const disc = b2a * b2a - c[0] / c[2];
+    if (disc < 0) return 0;
+    if (disc > 0) {
+      r[0] = -b2a + Math.sqrt(disc);
+      r[1] = -2 * b2a - r[0];
+      return 2;
+    }
+    r[0] = -b2a;
+    return 1;
+  }
+
+  static solve3neg(disc: number, q: number, b3a: number, r: number[]): number {
+    const rr = 0.5 * Math.sqrt(-disc + q * q);
+    const theta = Math.atan2(Math.sqrt(-disc), -q);
+    const temp = 2 * Math.cbrt(rr);
+    r[0] = temp * Math.cos(theta / 3) - b3a;
+    r[1] = temp * Math.cos((theta + 2 * Math.PI) / 3) - b3a;
+    r[2] = temp * Math.cos((theta - 2 * Math.PI) / 3) - b3a;
+    return 3;
+  }
+
+  static solve3pos(disc: number, q: number, b3a: number, r: number[]): number {
+    const al = 0.5 * (Math.sqrt(disc) - q);
+    r[0] = Math.cbrt(al) + Math.cbrt(-q - al) - b3a;
+    if (disc > 0) return 1;
+    r[1] = r[2] = -0.5 * (r[0] + b3a) - b3a;
+    return 3;
+  }
+
+  static solve3(c: number[], r: number[]): number {
+    const a = c[3], b = c[2], cv = c[1], d = c[0];
+    if (Solver.aeq0(a)) return Solver.solve2(c, r);
+    const b3a = b / (3 * a), p0 = b3a * b3a;
+    const q = 2 * b3a * p0 - b3a * cv / a + d / a;
+    const p = cv / (3 * a) - p0;
+    const disc = q * q + 4 * p * p * p;
+    return disc < 0 ? Solver.solve3neg(disc, q, b3a, r)
+                    : Solver.solve3pos(disc, q, b3a, r);
+  }
+}
+
+/** Solve cubic c[3]*x^3 + c[2]*x^2 + c[1]*x + c[0] = 0.
+ *  Returns root count; 4 means all x satisfy. @see lib/pathplan/solvers.c:solve3 */
+export function solve3(coeff: number[], roots: number[]): number {
+  return Solver.solve3(coeff, roots);
+}