@knowvah/dot-engine 0.1.0

package/src/ortho/partition.ts

@@ -0,0 +1,303 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Partition free space around nodes into rectangular tiles.
+ *
+ * Faithful port of lib/ortho/partition.c.
+ * Runs Seidel trapezoidation TWICE: once normal, once with x/y swapped
+ * (via perp()). Intersection of the two decompositions yields cells
+ * bounded on all four sides.
+ *
+ * SEED is fixed at 173 — matches lib/ortho/partition.c:srand48(173).
+ *
+ * @see lib/ortho/partition.c
+ */
+
+import { srand48, drand48 } from "../common/random.js";
+import type { OrthoBox, OrthoPoint, Cell } from "./types.js";
+import {
+  constructTrapezoids, fpEqual, greaterThan, isValidTrap, C_EPS, equalTo,
+} from "./trapezoid.js";
+import type { SegmentT, TrapT } from "./trapezoid.js";
+
+/** Fixed RNG seed — matches lib/ortho/partition.c:srand48(173) */
+const SEED = 173;
+
+export { SEED };
+
+const NPOINTS = 4;
+
+/** @see lib/ortho/partition.c:#define TR_FROM_UP/TR_FROM_DN */
+const TR_FROM_UP = 1;
+const TR_FROM_DN = 2;
+
+class PartitionHelper {
+  /** @see lib/common/geomprocs.h:perp — r.x = -p.y, r.y = p.x */
+  static perp(p: OrthoPoint): OrthoPoint {
+    return { x: -p.y, y: p.x };
+  }
+
+  static rectIntersect(r0: OrthoBox, r1: OrthoBox): OrthoBox | null {
+    const llx = Math.max(r0.LL.x, r1.LL.x);
+    const urx = Math.min(r0.UR.x, r1.UR.x);
+    const lly = Math.max(r0.LL.y, r1.LL.y);
+    const ury = Math.min(r0.UR.y, r1.UR.y);
+    if (llx >= urx || lly >= ury) return null;
+    return { LL: { x: llx, y: lly }, UR: { x: urx, y: ury } };
+  }
+
+  static convert(bb: OrthoBox, flip: boolean, ccw: boolean): OrthoPoint[] {
+    const pts: OrthoPoint[] = [
+      { ...bb.LL },
+      ccw ? { x: bb.UR.x, y: bb.LL.y } : { x: bb.LL.x, y: bb.UR.y },
+      { ...bb.UR },
+      ccw ? { x: bb.LL.x, y: bb.UR.y } : { x: bb.UR.x, y: bb.LL.y },
+    ];
+    if (flip) return pts.map(PartitionHelper.perp);
+    return pts;
+  }
+
+  static store(seg: SegmentT[], first: number, pts: OrthoPoint[]): number {
+    const last = first + NPOINTS - 1;
+    for (let i = first, j = 0; i <= last; i++, j++) {
+      seg[i].next = i === first ? first + 1 : i === last ? first : i + 1;
+      seg[i].prev = i === first ? last : i - 1;
+      seg[i].isInserted = false;
+      seg[i].v0 = { ...pts[j] };
+      seg[seg[i].prev].v1 = { ...pts[j] };
+    }
+    return last + 1;
+  }
+
+  static genSegments(cells: Cell[], bb: OrthoBox, flip: boolean): SegmentT[] {
+    const nsegs = 4 * (cells.length + 1);
+    const seg: SegmentT[] = [];
+    for (let i = 0; i <= nsegs; i++) {
+      seg.push({
+        v0: { x: 0, y: 0 }, v1: { x: 0, y: 0 },
+        isInserted: false, root0: 0, root1: 0, next: 0, prev: 0,
+      });
+    }
+    let i = 1;
+    i = PartitionHelper.store(seg, i, PartitionHelper.convert(bb, flip, true));
+    for (const cell of cells) {
+      i = PartitionHelper.store(seg, i, PartitionHelper.convert(cell.bb, flip, false));
+    }
+    return seg;
+  }
+
+  /**
+   * Generate a random permutation of the segments 1..n, drawing from the
+   * process-global POSIX drand48 stream (seeded by partition's srand48).
+   * @see lib/ortho/partition.c:generateRandomOrdering
+   */
+  static generateRandomOrdering(n: number): number[] {
+    const permute: number[] = [];
+    for (let i = 0; i < n; i++) permute.push(i + 1);
+    for (let i = 0; i < n; i++) {
+      // C: j = (size_t)((double)i + drand48() * (double)(n - i));
+      const j = Math.floor(i + drand48() * (n - i));
+      if (j !== i) {
+        const tmp = permute[i]; permute[i] = permute[j]; permute[j] = tmp;
+      }
+    }
+    return permute;
+  }
+
+  /**
+   * Build the box for a rectangular trapezoid (un-flipping the perp frame
+   * for the vertical pass). Caller has already verified the rect condition.
+   * @see lib/ortho/partition.c:traverse_polygon (box block)
+   */
+  static mkTrapBox(t: TrapT, seg: SegmentT[], flip: boolean): OrthoBox {
+    if (flip) {
+      return {
+        LL: { x: t.lo.y, y: -seg[t.rseg].v0.x },
+        UR: { x: t.hi.y, y: -seg[t.lseg].v0.x },
+      };
+    }
+    return {
+      LL: { x: seg[t.lseg].v0.x, y: t.lo.y },
+      UR: { x: seg[t.rseg].v0.x, y: t.hi.y },
+    };
+  }
+
+  /**
+   * True if the (triangular) trapezoid lies inside the polygon — used to
+   * locate the traversal start trapezoid.
+   * @see lib/ortho/partition.c:inside_polygon
+   */
+  static insidePolygon(t: TrapT, seg: SegmentT[]): boolean {
+    if (!t.isValid) return false;
+    if (t.lseg <= 0 || t.rseg <= 0) return false;
+    const triangle =
+      (!isValidTrap(t.u0) && !isValidTrap(t.u1)) ||
+      (!isValidTrap(t.d0) && !isValidTrap(t.d1));
+    if (triangle) return greaterThan(seg[t.rseg].v1, seg[t.rseg].v0);
+    return false;
+  }
+
+  /**
+   * Determines the ordered list of (child trapezoid, direction) pairs that
+   * `traverse_polygon` recurses into for trapezoid `t`, given the `from`/
+   * `dir` it was entered with. This is the C function's full branch table
+   * (partition.c:400-621) minus the monotone-chain bookkeeping
+   * (`make_new_monotone_poly`/`mcur`/`mnew`/`vert`/`mon`), which is provably
+   * dead for box output — `decomp` boxes depend only on trap geometry and
+   * `flip`, never on the chain state — but the CALL ORDER of children is
+   * live: it determines maze-cell construction order downstream (mkMaze →
+   * createSEdges → snode adjEdgeList), which is the tie-break for equal-cost
+   * Dijkstra corridors in ortho edge routing.
+   * @see lib/ortho/partition.c:traverse_polygon
+   */
+  static childOrder(t: TrapT, seg: SegmentT[], from: number, dir: number): [number, number][] {
+    const UP = TR_FROM_UP; const DN = TR_FROM_DN;
+    const { u0, u1, d0, d1 } = t;
+    if (!isValidTrap(u0) && !isValidTrap(u1)) {
+      if (isValidTrap(d0) && isValidTrap(d1)) { // downward opening triangle
+        if (from === d1) return [[d1, UP], [d0, UP]];
+        return [[d0, UP], [d1, UP]];
+      }
+      return [[u0, DN], [u1, DN], [d0, UP], [d1, UP]]; // just traverse all neighbours
+    }
+    if (!isValidTrap(d0) && !isValidTrap(d1)) {
+      if (isValidTrap(u0) && isValidTrap(u1)) { // upward opening triangle
+        if (from === u1) return [[u1, DN], [u0, DN]];
+        return [[u0, DN], [u1, DN]];
+      }
+      return [[u0, DN], [u1, DN], [d0, UP], [d1, UP]]; // just traverse all neighbours
+    }
+    if (isValidTrap(u0) && isValidTrap(u1)) {
+      if (isValidTrap(d0) && isValidTrap(d1)) { // downward + upward cusps
+        if ((dir === DN && d1 === from) || (dir === UP && u1 === from)) {
+          return [[u1, DN], [d1, UP], [u0, DN], [d0, UP]];
+        }
+        return [[u0, DN], [d0, UP], [u1, DN], [d1, UP]];
+      }
+      // only downward cusp
+      if (equalTo(t.lo, seg[t.lseg].v1)) {
+        if (dir === UP && u0 === from) return [[u0, DN], [d0, UP], [u1, DN], [d1, UP]];
+        return [[u1, DN], [d0, UP], [d1, UP], [u0, DN]];
+      }
+      if (dir === UP && u1 === from) return [[u1, DN], [d1, UP], [d0, UP], [u0, DN]];
+      return [[u0, DN], [d0, UP], [d1, UP], [u1, DN]];
+    }
+    // no downward cusp (is_valid_trap(u0) || is_valid_trap(u1), always true here)
+    if (isValidTrap(d0) && isValidTrap(d1)) { // only upward cusp
+      if (equalTo(t.hi, seg[t.lseg].v0)) {
+        if (!(dir === DN && d0 === from)) return [[u1, DN], [d1, UP], [u0, DN], [d0, UP]];
+        return [[d0, UP], [u0, DN], [u1, DN], [d1, UP]];
+      }
+      if (dir === DN && d1 === from) return [[d1, UP], [u1, DN], [u0, DN], [d0, UP]];
+      return [[u0, DN], [d0, UP], [u1, DN], [d1, UP]];
+    }
+    // no cusp
+    if (equalTo(t.hi, seg[t.lseg].v0) && equalTo(t.lo, seg[t.rseg].v0)) {
+      if (dir === UP) return [[u0, DN], [u1, DN], [d1, UP], [d0, UP]];
+      return [[d1, UP], [d0, UP], [u0, DN], [u1, DN]];
+    }
+    if (equalTo(t.hi, seg[t.rseg].v1) && equalTo(t.lo, seg[t.lseg].v1)) {
+      if (dir === UP) return [[u0, DN], [u1, DN], [d1, UP], [d0, UP]];
+      return [[d1, UP], [d0, UP], [u0, DN], [u1, DN]];
+    }
+    return [[u0, DN], [d0, UP], [u1, DN], [d1, UP]]; // no split possible
+  }
+
+  /**
+   * Faithful port of monotonate_trapezoids' observable output: collect the
+   * rectangle for every trapezoid reachable from the inside-polygon start
+   * via u0/u1/d0/d1 adjacency, IN C's EXACT traverse_polygon call order.
+   *
+   * Realized as an explicit-stack DFS (not real recursion, to stay
+   * stack-safe on large polygons per
+   * .agent-notes/triangulation-recursion-stack-overflow.md) that preserves
+   * C's preorder emission sequence: children are pushed in REVERSE of
+   * `childOrder`'s call order so LIFO pop visits them in forward order,
+   * fully exploring each child's subtree (via its own pushed descendants)
+   * before returning to the next sibling — exactly mirroring recursive DFS.
+   *
+   * @see lib/ortho/partition.c:monotonate_trapezoids, traverse_polygon
+   */
+  static monotonateTrapezoids(tr: TrapT[], seg: SegmentT[], flip: boolean): OrthoBox[] {
+    const decomp: OrthoBox[] = [];
+    let trStart = -1;
+    for (let j = 0; j < tr.length; j++) {
+      if (PartitionHelper.insidePolygon(tr[j], seg)) { trStart = j; break; }
+    }
+    if (trStart < 0) return decomp;
+
+    let startFrom: number; let startDir: number;
+    if (isValidTrap(tr[trStart].u0)) { startFrom = tr[trStart].u0; startDir = TR_FROM_UP; }
+    else if (isValidTrap(tr[trStart].d0)) { startFrom = tr[trStart].d0; startDir = TR_FROM_DN; }
+    else return decomp;
+
+    const visited = new Array<boolean>(tr.length).fill(false);
+    // Stack items are [trnum, from, dir] — mirrors the recursive call's
+    // (trnum, from, dir) parameters exactly.
+    const stack: [number, number, number][] = [[trStart, startFrom, startDir]];
+    while (stack.length > 0) {
+      const [trnum, from, dir] = stack.pop()!;
+      if (!isValidTrap(trnum) || visited[trnum]) continue;
+      visited[trnum] = true;
+      const t = tr[trnum];
+      if (
+        t.hi.y > t.lo.y + C_EPS &&
+        fpEqual(seg[t.lseg].v0.x, seg[t.lseg].v1.x) &&
+        fpEqual(seg[t.rseg].v0.x, seg[t.rseg].v1.x)
+      ) {
+        decomp.push(PartitionHelper.mkTrapBox(t, seg, flip));
+      }
+      const children = PartitionHelper.childOrder(t, seg, from, dir);
+      for (let i = children.length - 1; i >= 0; i--) {
+        const [child, childDir] = children[i];
+        stack.push([child, trnum, childDir]);
+      }
+    }
+    return decomp;
+  }
+}
+
+/**
+ * Partition free space around cells into rectangular tiles.
+ * @see lib/ortho/partition.c:partition
+ */
+export function partition(cells: Cell[], bb: OrthoBox): OrthoBox[] {
+  const h = PartitionHelper;
+  const nsegs = 4 * (cells.length + 1);
+
+  // C: srand48(173) once, then two generateRandomOrdering calls share the
+  // continuing drand48 stream (partition.c:737-763).
+  srand48(SEED);
+
+  const hSeg = h.genSegments(cells, bb, false);
+  const hPerm = h.generateRandomOrdering(nsegs);
+  const hTr = constructTrapezoids(nsegs, hSeg, hPerm);
+  const hDecomp = h.monotonateTrapezoids(hTr, hSeg, false);
+
+  const vSeg = h.genSegments(cells, bb, true);
+  const vPerm = h.generateRandomOrdering(nsegs);
+  const vTr = constructTrapezoids(nsegs, vSeg, vPerm);
+  const vDecomp = h.monotonateTrapezoids(vTr, vSeg, true);
+
+  const result: OrthoBox[] = [];
+  for (const v of vDecomp) {
+    for (const hb of hDecomp) {
+      const isect = h.rectIntersect(v, hb);
+      if (isect) result.push(isect);
+    }
+  }
+  return result;
+}
+
+/**
+ * Test-only accessor for `PartitionHelper.childOrder` — exposes the
+ * traverse_polygon branch-table transcription for direct unit testing
+ * without requiring a full trapezoidation pipeline to exercise each branch.
+ * @see PartitionHelper.childOrder
+ */
+export function traverseChildOrderForTest(
+  t: TrapT, seg: SegmentT[], from: number, dir: number,
+): [number, number][] {
+  return PartitionHelper.childOrder(t, seg, from, dir);
+}
+
+export { TR_FROM_UP, TR_FROM_DN };

package/src/ortho/rawgraph.ts

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Directed graph with DFS-based topological sort.
+ *
+ * Faithful port of lib/ortho/rawgraph.c.
+ * @see lib/ortho/rawgraph.c
+ * @see lib/ortho/rawgraph.h
+ */
+
+import type { RawGraph, RawVertex } from "./types.js";
+
+const UNSCANNED = 0;
+const SCANNING = 1;
+const SCANNED = 2;
+
+/**
+ * Allocate a graph with n vertices and no edges.
+ * @see lib/ortho/rawgraph.c:make_graph
+ */
+export function makeGraph(n: number): RawGraph {
+  const vertices: RawVertex[] = [];
+  for (let i = 0; i < n; i++) {
+    vertices.push({ color: UNSCANNED, topsortOrder: 0, adjList: [] });
+  }
+  return { nvs: n, vertices };
+}
+
+/**
+ * Release all memory associated with the graph.
+ * (No-op in TS — GC handles it; retained for API symmetry.)
+ * @see lib/ortho/rawgraph.c:free_graph
+ */
+export function freeGraph(_g: RawGraph): void {
+  // GC handled
+}
+
+/**
+ * Insert a directed edge from v1 to v2 (if it doesn't exist yet).
+ * @see lib/ortho/rawgraph.c:insert_edge
+ */
+export function insertEdge(g: RawGraph, v1: number, v2: number): void {
+  if (!edgeExists(g, v1, v2)) {
+    g.vertices[v1].adjList.push(v2);
+  }
+}
+
+/**
+ * Remove any edge between v1 and v2 (either direction).
+ * @see lib/ortho/rawgraph.c:remove_redge
+ */
+export function removeRedge(g: RawGraph, v1: number, v2: number): void {
+  g.vertices[v1].adjList = g.vertices[v1].adjList.filter((x) => x !== v2);
+  g.vertices[v2].adjList = g.vertices[v2].adjList.filter((x) => x !== v1);
+}
+
+/**
+ * Test if there is a directed edge FROM v1 TO v2.
+ * @see lib/ortho/rawgraph.c:edge_exists
+ */
+export function edgeExists(g: RawGraph, v1: number, v2: number): boolean {
+  return g.vertices[v1].adjList.includes(v2);
+}
+
+/**
+ * Recursive DFS visit used by topological sort.
+ * @see lib/ortho/rawgraph.c:DFS_visit
+ */
+function dfsVisit(
+  g: RawGraph,
+  v: number,
+  time: number,
+  sp: number[],
+): number {
+  const vp = g.vertices[v];
+  vp.color = SCANNING;
+  const adj = vp.adjList;
+  time = time + 1;
+
+  for (let i = 0; i < adj.length; i++) {
+    const id = adj[i];
+    if (g.vertices[id].color === UNSCANNED) {
+      time = dfsVisit(g, id, time, sp);
+    }
+  }
+  vp.color = SCANNED;
+  sp.push(v);
+  return time + 1;
+}
+
+/**
+ * Topologically sort the directed graph.
+ * After this call, each vertex has topsortOrder set.
+ * @see lib/ortho/rawgraph.c:top_sort
+ */
+export function topSort(g: RawGraph): void {
+  let time = 0;
+  let count = 0;
+
+  if (g.nvs === 0) return;
+  if (g.nvs === 1) {
+    g.vertices[0].topsortOrder = count;
+    return;
+  }
+
+  const sp: number[] = [];
+  sp.length = 0;
+
+  for (let i = 0; i < g.nvs; i++) {
+    if (g.vertices[i].color === UNSCANNED) {
+      time = dfsVisit(g, i, time, sp);
+    }
+  }
+
+  while (sp.length > 0) {
+    const v = sp.pop() as number;
+    g.vertices[v].topsortOrder = count;
+    count++;
+  }
+}

package/src/ortho/sgraph.ts

@@ -0,0 +1,283 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * Search graph and Dijkstra shortest path for ortho edge routing.
+ *
+ * Faithful port of lib/ortho/sgraph.c.
+ * Distance values stored NEGATED in nVal while in the priority queue.
+ * When a node is finalized (popped), nVal is flipped positive.
+ * UNSEEN = Number.MIN_SAFE_INTEGER (mirrors C INT_MIN).
+ *
+ * @see lib/ortho/sgraph.c
+ * @see lib/ortho/sgraph.h
+ */
+
+import type { SGraph, SNode, SEdge, Cell } from "./types.js";
+import { pqGen, pqFree, pqInit, pqInsert, pqRemove, pqUpdate } from "./fpq.js";
+import type { Pq } from "./fpq.js";
+
+/** Sentinel value for unseen nodes. @see lib/ortho/sgraph.c:UNSEEN */
+export const UNSEEN = Number.MIN_SAFE_INTEGER;
+
+// ─── Graph lifecycle ─────────────────────────────────────────────────────────
+
+/**
+ * Allocate a search graph with capacity for nnodes nodes (+2 dummy slots).
+ * @see lib/ortho/sgraph.c:createSGraph
+ */
+export function createSGraph(nnodes: number): SGraph {
+  const nodes: SNode[] = [];
+  for (let i = 0; i < nnodes; i++) {
+    nodes.push(makeSNode(i));
+  }
+  return {
+    nnodes: 0,
+    nedges: 0,
+    saveNnodes: 0,
+    saveNedges: 0,
+    nodes,
+    edges: [],
+  };
+}
+
+/** Allocate a blank SNode at the given index. */
+function makeSNode(index: number): SNode {
+  return {
+    nVal: UNSEEN,
+    nIdx: 0,
+    nDad: null,
+    nEdge: null,
+    nAdj: 0,
+    saveNAdj: 0,
+    cells: [null, null],
+    adjEdgeList: [],
+    index,
+    isVert: false,
+    x: 0,
+    y: 0,
+  };
+}
+
+/**
+ * Free the graph. (No-op in TS — GC handles it.)
+ * @see lib/ortho/sgraph.c:freeSGraph
+ */
+export function freeSGraph(_g: SGraph): void {
+  // GC handled
+}
+
+/**
+ * Initialize per-node adjacency list storage.
+ * Regular nodes get 6 slots; the two dummy nodes get maxdeg slots each.
+ * @see lib/ortho/sgraph.c:initSEdges
+ */
+export function initSEdges(g: SGraph, maxdeg: number): void {
+  // The two extra dummy nodes at indices nnodes and nnodes+1 need maxdeg slots
+  const total = g.nnodes + 2;
+  while (g.nodes.length < total) {
+    g.nodes.push(makeSNode(g.nodes.length));
+  }
+  // ONE contiguous buffer, exactly as C (sgraph.c:initSEdges): 6 int slots per
+  // regular node, `maxdeg` per dummy. Each node's adjEdgeList is a subarray view
+  // from its offset to the buffer END — so addEdgeToNode writing past a node's
+  // region spills forward into the next node's slots (and persists across reset),
+  // matching C's unbounded addEdgeToNode into the shared allocation.
+  const buf = new Int32Array(6 * g.nnodes + 2 * maxdeg);
+  g.adjBuf = buf;
+  let off = 0;
+  for (let i = 0; i < g.nnodes; i++) {
+    g.nodes[i].adjEdgeList = buf.subarray(off);
+    off += 6;
+  }
+  for (let i = g.nnodes; i < g.nnodes + 2; i++) {
+    g.nodes[i].adjEdgeList = buf.subarray(off);
+    off += maxdeg;
+  }
+  // pre-allocate edge array capacity
+  g.edges = new Array<SEdge>(3 * g.nnodes + maxdeg);
+  g.nedges = 0;
+}
+
+// ─── Node / edge creation ────────────────────────────────────────────────────
+
+/**
+ * Append a new node to the graph and return it.
+ * @see lib/ortho/sgraph.c:createSNode
+ */
+export function createSNode(g: SGraph): SNode {
+  const np = g.nodes[g.nnodes];
+  np.index = g.nnodes;
+  g.nnodes++;
+  return np;
+}
+
+/**
+ * Create an edge between v1 and v2 with the given weight.
+ * @see lib/ortho/sgraph.c:createSEdge
+ */
+export function createSEdge(
+  g: SGraph,
+  v1: SNode,
+  v2: SNode,
+  wt: number,
+): SEdge {
+  const idx = g.nedges++;
+  const e: SEdge = { weight: wt, cnt: 0, v1: v1.index, v2: v2.index };
+  g.edges[idx] = e;
+  // C addEdgeToNode (sgraph.c:45) writes at index n_adj then increments, so
+  // after reset() restores n_adj to save_n_adj the next createSEdge OVERWRITES
+  // the stale temp-edge slot. Using push() here would instead append beyond
+  // nAdj, leaving the stale edge at index nAdj for the next edge's shortPath to
+  // follow (corrupts the 2nd+ edge sharing a boundary node). Index-assign.
+  v1.adjEdgeList[v1.nAdj] = idx;
+  v1.nAdj++;
+  v2.adjEdgeList[v2.nAdj] = idx;
+  v2.nAdj++;
+  return e;
+}
+
+// ─── State save / restore ────────────────────────────────────────────────────
+
+/**
+ * Save the current graph state (node/edge counts + adjacency counts).
+ * @see lib/ortho/sgraph.c:gsave
+ */
+export function gsave(g: SGraph): void {
+  g.saveNnodes = g.nnodes;
+  g.saveNedges = g.nedges;
+  for (let i = 0; i < g.nnodes; i++) {
+    g.nodes[i].saveNAdj = g.nodes[i].nAdj;
+  }
+}
+
+/**
+ * Restore the graph to the last saved state and clear the two dummy nodes.
+ * @see lib/ortho/sgraph.c:reset
+ */
+export function reset(g: SGraph): void {
+  g.nnodes = g.saveNnodes;
+  g.nedges = g.saveNedges;
+  for (let i = 0; i < g.nnodes; i++) {
+    g.nodes[i].nAdj = g.nodes[i].saveNAdj;
+  }
+  // Zero the two dummy nodes' adjacency. createSEdge index-assigns at nAdj
+  // (like C addEdgeToNode), so the next addNodeEdges overwrites stale slots —
+  // no adjEdgeList truncation needed (matches sgraph.c:reset exactly).
+  for (let i = g.nnodes; i < g.nnodes + 2; i++) {
+    if (g.nodes[i]) g.nodes[i].nAdj = 0;
+  }
+}
+
+// ─── Dijkstra ────────────────────────────────────────────────────────────────
+
+/** Return the other endpoint of edge e from node n. */
+function adjacentNode(g: SGraph, e: SEdge, n: SNode): SNode {
+  return e.v1 === n.index ? g.nodes[e.v2] : g.nodes[e.v1];
+}
+
+/** shortPath inner adjacency loop; true on PQ overflow. Extracted only for the
+ * CCN cap — side-effect order preserved. @see lib/ortho/sgraph.c:shortPath */
+function relaxNeighbors(pq: Pq, g: SGraph, n: SNode): boolean {
+  for (let y = 0; y < n.nAdj; y++) {
+    const e = g.edges[n.adjEdgeList[y]];
+    const adjn = adjacentNode(g, e, n);
+    // C uses `< 0` exactly (sgraph.c:164): skips finalized nodes (nVal >= 0).
+    if (adjn.nVal < 0) {
+      // C sgraph.h:27 n_val is `int`; sgraph.c:142 `int d` truncates the sum
+      // toward zero on assignment every relax step (not just the final total).
+      // d is always <= 0 here, so Math.trunc matches C's toward-zero int cast
+      // exactly (unlike Math.floor, which rounds negatives away from zero).
+      const d = Math.trunc(-(n.nVal + e.weight));
+      if (adjn.nVal === UNSEEN) {
+        adjn.nVal = d;
+        if (pqInsert(pq, adjn) !== 0) return true;
+        adjn.nDad = n;
+        adjn.nEdge = e;
+      } else if (adjn.nVal < d) {
+        pqUpdate(pq, adjn, d);
+        adjn.nDad = n;
+        adjn.nEdge = e;
+      }
+    }
+  }
+  return false;
+}
+
+/** Dijkstra shortest path from `from` to `to`; 0 on success, 1 on PQ overflow.
+ * Distances stored NEGATED while pending, flipped positive when finalized.
+ * @see lib/ortho/sgraph.c:shortPath */
+export function shortPath(pq: Pq, g: SGraph, from: SNode, to: SNode): number {
+  // mark all nodes unseen
+  for (let x = 0; x < g.nnodes; x++) {
+    g.nodes[x].nVal = UNSEEN;
+  }
+
+  pqInit(pq);
+  if (pqInsert(pq, from) !== 0) return 1;
+  from.nDad = null;
+  from.nVal = 0;
+
+  let n: SNode | null;
+  while ((n = pqRemove(pq)) !== null) {
+    n.nVal *= -1; // finalize: flip to positive
+    if (n === to) break;
+    if (relaxNeighbors(pq, g, n)) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Generate a fresh priority queue sized for the search graph.
+ * @see lib/ortho/sgraph.c shortPath preamble
+ */
+export function pqGenForGraph(g: SGraph): Pq {
+  return pqGen(g.nnodes + 2);
+}
+
+export { pqFree };
+
+// ─── Node/edge helpers used by maze.ts / ortho/index.ts ──────────────────────
+
+/**
+ * Add temporary edges from a node cell to the search graph.
+ * Used to attach source/dest nodes before each Dijkstra call.
+ * @see lib/ortho/ortho.c:addNodeEdges
+ */
+export function addNodeEdges(
+  sg: SGraph,
+  cp: Cell,
+  np: SNode,
+): void {
+  for (let i = 0; i < cp.nsides; i++) {
+    const onp = cp.sides[i];
+    if (onp !== null) {
+      createSEdge(sg, np, onp, 0);
+    }
+  }
+  sg.nnodes++;
+  np.cells[0] = cp;
+  np.cells[1] = cp;
+}
+
+/**
+ * Add temporary loop edges (self-loop at a single cell).
+ * @see lib/ortho/ortho.c:addLoop
+ */
+export function addLoop(
+  sg: SGraph,
+  cp: Cell,
+  dp: SNode,
+  sp: SNode,
+): void {
+  for (let i = 0; i < cp.nsides; i++) {
+    const onp = cp.sides[i];
+    if (onp === null) continue;
+    if (onp.isVert) continue;
+    const onTop = onp.cells[0] === cp;
+    if (onTop) {
+      createSEdge(sg, sp, onp, 0);
+    } else {
+      createSEdge(sg, dp, onp, 0);
+    }
+  }
+  sg.nnodes += 2;
+}