@woosh/meep-engine 2.163.7 → 2.163.9

package/src/engine/navigation/mesh/bt_mesh_face_find_path_polyanya.js

@@ -0,0 +1,682 @@
+import { Uint32Heap4 } from "../../../core/collection/heap/Uint32Heap4.js";
+import { line_segment_intersection_fraction_2d } from "../../../core/geom/2d/line/line_segment_intersection_fraction_2d.js";
+import { triangle2d_compute_area } from "../../../core/geom/2d/triangle2d_compute_area.js";
+import { NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { v2_distance } from "../../../core/geom/vec2/v2_distance.js";
+
+/*
+ * Polyanya: exact any-angle shortest path on a triangle navmesh.
+ *
+ * Cui, Harabor, Grastien -- "Compromise-free Pathfinding on a Navigation Mesh" (IJCAI 2017).
+ *
+ * Search nodes are (root, interval) pairs: an interval [i0, i1] on a mesh edge, seen from a `root`
+ * point such that the start->root sub-path is already taut/optimal and the whole interval is visible
+ * from root. Expanding a node projects the visibility cone (root through the interval) into the
+ * triangle on the far side of the edge and clips it against that triangle's two far edges. Parts still
+ * visible from root keep `root` (observable); parts hidden behind a boundary CORNER at an interval
+ * endpoint are reached by turning at that corner, which becomes the new root (non-observable). The
+ * result is the exact shortest path, turning only at obstacle corners.
+ *
+ * 3D / intrinsic: the search is planar, but it does NOT assume any global "up" -- it follows the surface
+ * by UNFOLDING. Each node carries the 2D positions of its entry edge in a frame accumulated along its
+ * own corridor; expanding a node flattens the next triangle into that frame by placing the apex from the
+ * two 3D edge lengths |edge-vertex .. apex| (an isometry of the triangle), on the side fixed by the
+ * face's winding. So distances in the frame are true geodesic distances and the cost `g` is exact on a
+ * curved/folded surface, not just a planar one. Turning corners are detected from the 3D incident-angle
+ * sum (also intrinsic). The goal has no fixed position across frames, so the A* heuristic is the exact
+ * shortest root->interval->goal measured with straight 3D chords (a lower bound on the geodesic, hence
+ * admissible); the terminal node's *exact* cost unfolds the goal into the node's frame instead.
+ *
+ * The output path FOLLOWS THE SURFACE: it is subdivided at every face-boundary edge the geodesic
+ * crosses, so each emitted segment lies within a single triangle -- it never flies over a convex crease
+ * nor tunnels through a concave fold. Turning corners are mesh vertices (exact positions); each edge
+ * crossing is the exact line-vs-edge intersection lifted to 3D by lerping the edge's two endpoints; the
+ * start/goal are the given 3D points. Collinear runs (a flat stretch with no real bend) are collapsed to
+ * their endpoints, so on a planar mesh the output is just the minimal corner polyline -- the subdivision
+ * only adds points where the surface actually folds. Wired into NavigationMesh.find_path.
+ */
+
+const EPS = 1e-9;            // area-sign slack (cone inside/outside tests)
+const DEDUP_EPS = 1e-7;      // merge consecutive output points equal to within f32 reconstruction error
+const COLLINEAR_EPS = 1e-4;  // drop a path point whose perpendicular offset from its neighbours / span is below this
+
+// Parameter-space tolerance for edge fractions, interval coverage and vertex snapping. Vertices are
+// stored as float32, so a point that is geometrically on an edge endpoint or already-covered carries
+// ~coord*2^-23 quantization noise in its edge fraction -- far above 1e-9. Tolerating less re-covers the
+// same edge stretches as slivers and the wavefront floods without converging. 1e-4 covers coordinates
+// into the thousands while staying far below any real feature size, and never moves a waypoint (corners
+// are exact vertex positions).
+const PEPS = 1e-4;
+
+// ---- 2D primitives in the unfolded frame -----------------------------------------------------------
+
+const _reflect = new Float64Array(2);
+
+/** Reflect (px,py) across the line through (ax,ay),(bx,by) into {@link _reflect}. */
+function reflect(px, py, ax, ay, bx, by) {
+    const abx = bx - ax, aby = by - ay;
+    const len2 = abx * abx + aby * aby;
+    if (len2 < 1e-18) { _reflect[0] = px; _reflect[1] = py; return; }
+    const t = ((px - ax) * abx + (py - ay) * aby) / len2;
+    _reflect[0] = 2 * (ax + t * abx) - px;
+    _reflect[1] = 2 * (ay + t * aby) - py;
+}
+
+/** Exact root->interval->goal distance in the unfolded frame (the terminal node's true final cost). */
+function touch_distance(rx, ry, i0x, i0y, i1x, i1y, gx, gy) {
+    let tx = gx, ty = gy;
+    if (triangle2d_compute_area(i0x, i0y, i1x, i1y, rx, ry) * triangle2d_compute_area(i0x, i0y, i1x, i1y, gx, gy) > 0) {
+        reflect(gx, gy, i0x, i0y, i1x, i1y);
+        tx = _reflect[0]; ty = _reflect[1];
+    }
+    const t = line_segment_intersection_fraction_2d(rx, ry, tx, ty, i0x, i0y, i1x, i1y);
+    if (t >= -PEPS && t <= 1 + PEPS) { // -1 (no crossing) falls below -PEPS, so the range test rejects it
+        return v2_distance(rx, ry, tx, ty);
+    }
+    return Math.min(
+        v2_distance(rx, ry, i0x, i0y) + v2_distance(i0x, i0y, gx, gy),
+        v2_distance(rx, ry, i1x, i1y) + v2_distance(i1x, i1y, gx, gy)
+    );
+}
+
+/**
+ * Shortest root->interval->goal measured with straight 3D chords (admissible heuristic: it is the
+ * 3D-space unfolding of the two segments across the interval's line, always <= the on-surface geodesic).
+ */
+function touch_distance_3d(rx, ry, rz, i0x, i0y, i0z, i1x, i1y, i1z, gx, gy, gz) {
+    const dx = i1x - i0x, dy = i1y - i0y, dz = i1z - i0z;
+    const dlen2 = dx * dx + dy * dy + dz * dz;
+    const viaI0 = Math.hypot(rx - i0x, ry - i0y, rz - i0z) + Math.hypot(gx - i0x, gy - i0y, gz - i0z);
+    if (dlen2 < 1e-18) return viaI0;
+
+    const dlen = Math.sqrt(dlen2), ux = dx / dlen, uy = dy / dlen, uz = dz / dlen;
+    const rt = (rx - i0x) * ux + (ry - i0y) * uy + (rz - i0z) * uz;
+    const rperp = Math.hypot(rx - i0x - rt * ux, ry - i0y - rt * uy, rz - i0z - rt * uz);
+    const gt = (gx - i0x) * ux + (gy - i0y) * uy + (gz - i0z) * uz;
+    const gperp = Math.hypot(gx - i0x - gt * ux, gy - i0y - gt * uy, gz - i0z - gt * uz);
+
+    const denom = rperp + gperp;
+    const xs = denom < 1e-12 ? rt : rt + (gt - rt) * rperp / denom; // edge crossing of the unfolded line
+    if (xs >= 0 && xs <= dlen) return Math.hypot(gt - rt, denom);
+
+    const viaI1 = Math.hypot(rx - i1x, ry - i1y, rz - i1z) + Math.hypot(gx - i1x, gy - i1y, gz - i1z);
+    return Math.min(viaI0, viaI1);
+}
+
+// ---- mesh helpers ----------------------------------------------------------------------------------
+
+const _va = new Float64Array(3), _vb = new Float64Array(3), _vc = new Float64Array(3);
+const _qa = new Float64Array(3), _qb = new Float64Array(3); // distance reads, kept off _va/_vb/_vc
+
+const _tri = [0, 0, 0];
+function triangle_vertices(topology, face) {
+    const l0 = topology.face_read_loop(face);
+    const l1 = topology.loop_read_next(l0);
+    const l2 = topology.loop_read_next(l1);
+    _tri[0] = topology.loop_read_vertex(l0);
+    _tri[1] = topology.loop_read_vertex(l1);
+    _tri[2] = topology.loop_read_vertex(l2);
+}
+
+/** 3D distance between two vertices. */
+function vid_distance_3d(topology, va, vb) {
+    topology.vertex_read_coordinate(_qa, 0, va);
+    topology.vertex_read_coordinate(_qb, 0, vb);
+    return Math.hypot(_qa[0] - _qb[0], _qa[1] - _qb[1], _qa[2] - _qb[2]);
+}
+
+/** The face across edge (va,vb) other than `face`, or NULL_POINTER if that edge is a boundary. */
+function neighbour_across(topology, face, va, vb) {
+    let loop = topology.face_read_loop(face);
+    for (let i = 0; i < 3; i++) {
+        const a = topology.loop_read_vertex(loop);
+        const b = topology.loop_read_vertex(topology.loop_read_next(loop));
+        if ((a === va && b === vb) || (a === vb && b === va)) {
+            let radial = topology.loop_read_radial_next(loop);
+            while (radial !== loop) {
+                const f = topology.loop_read_face(radial);
+                if (f !== face) return f;
+                radial = topology.loop_read_radial_next(radial);
+            }
+            return NULL_POINTER;
+        }
+        loop = topology.loop_read_next(loop);
+    }
+    return NULL_POINTER;
+}
+
+/**
+ * Unfold the apex of `face` into the 2D frame, given the entry edge (e0v,e1v) already placed at
+ * (e0x,e0y)-(e1x,e1y). The apex sits at its true 3D distances from the two edge vertices (an isometry of
+ * the triangle); the side is fixed by the face winding -- left of the edge as the loop traverses it, so
+ * the unfolded frame stays consistently oriented across faces with no reference to any global up. Writes
+ * the 2D apex into {@link _apex} and returns the apex vertex id.
+ */
+const _apex = new Float64Array(2);
+function unfold_apex(topology, face, e0v, e1v, e0x, e0y, e1x, e1y) {
+    triangle_vertices(topology, face);
+    let apex = -1, e0_before_e1 = false;
+    for (let i = 0; i < 3; i++) {
+        if (_tri[i] === e0v && _tri[(i + 1) % 3] === e1v) e0_before_e1 = true;
+        if (_tri[i] !== e0v && _tri[i] !== e1v) apex = _tri[i];
+    }
+
+    const dac = vid_distance_3d(topology, e0v, apex);
+    const dbc = vid_distance_3d(topology, e1v, apex);
+    const ex = e1x - e0x, ey = e1y - e0y;
+    const d = Math.hypot(ex, ey);
+    const a = (dac * dac - dbc * dbc + d * d) / (2 * d); // foot of the apex along the edge
+    let h2 = dac * dac - a * a; if (h2 < 0) h2 = 0;
+    const h = Math.sqrt(h2);
+    const ux = ex / d, uy = ey / d;
+    const sign = e0_before_e1 ? 1 : -1; // apex left of e0->e1 when the loop runs e0->e1
+    _apex[0] = e0x + a * ux + h * (-uy) * sign; // (-uy,ux) is the left normal of (ux,uy)
+    _apex[1] = e0y + a * uy + h * ux * sign;
+    return apex;
+}
+
+/** Barycentric weights (for va,vb,vc, in order) of a 3D point projected onto their plane, into `out`. */
+function barycentric_3d(topology, va, vb, vc, px, py, pz, out) {
+    topology.vertex_read_coordinate(_va, 0, va);
+    topology.vertex_read_coordinate(_vb, 0, vb);
+    topology.vertex_read_coordinate(_vc, 0, vc);
+    const e0x = _vb[0] - _va[0], e0y = _vb[1] - _va[1], e0z = _vb[2] - _va[2];
+    const e1x = _vc[0] - _va[0], e1y = _vc[1] - _va[1], e1z = _vc[2] - _va[2];
+    const v2x = px - _va[0], v2y = py - _va[1], v2z = pz - _va[2];
+    const d00 = e0x * e0x + e0y * e0y + e0z * e0z, d01 = e0x * e1x + e0y * e1y + e0z * e1z, d11 = e1x * e1x + e1y * e1y + e1z * e1z;
+    const d20 = v2x * e0x + v2y * e0y + v2z * e0z, d21 = v2x * e1x + v2y * e1y + v2z * e1z;
+    const denom = d00 * d11 - d01 * d01;
+    if (Math.abs(denom) < 1e-18) { out[0] = 1; out[1] = 0; out[2] = 0; return; }
+    const v = (d11 * d20 - d01 * d21) / denom, w = (d00 * d21 - d01 * d20) / denom;
+    out[0] = 1 - v - w; out[1] = v; out[2] = w;
+}
+
+/**
+ * True if `vid` is a turning corner: a boundary vertex where the *free space* is reflex (incident
+ * triangle angles, measured intrinsically in 3D, sum to > 180deg). The path only ever bends around these
+ * -- flat boundary vertices (180deg) and convex outer corners (<180deg) are not turning points, and
+ * admitting them as roots makes the search blow up combinatorially.
+ */
+const _corner_cache = new Map();
+const _corner_faces = new Set();
+function is_corner(topology, vid) {
+    const cached = _corner_cache.get(vid);
+    if (cached !== undefined) return cached;
+
+    let boundary = false;
+    _corner_faces.clear();
+
+    const e_first = topology.vertex_read_edge(vid);
+    if (e_first !== NULL_POINTER) {
+        let e = e_first;
+        do {
+            const loop = topology.edge_read_loop(e);
+            if (loop === NULL_POINTER || topology.loop_read_radial_next(loop) === loop) {
+                boundary = true;
+            }
+            if (loop !== NULL_POINTER) {
+                let rl = loop;
+                do { _corner_faces.add(topology.loop_read_face(rl)); rl = topology.loop_read_radial_next(rl); }
+                while (rl !== loop);
+            }
+            e = topology.edge_read_vertex1(e) === vid
+                ? topology.edge_read_v1_disk_next(e)
+                : topology.edge_read_v2_disk_next(e);
+        } while (e !== e_first && e !== NULL_POINTER);
+    }
+
+    let result = false;
+    if (boundary) {
+        topology.vertex_read_coordinate(_va, 0, vid);
+        const ox = _va[0], oy = _va[1], oz = _va[2];
+        let angle = 0;
+        for (const f of _corner_faces) {
+            triangle_vertices(topology, f);
+            let a = -1, b = -1;
+            for (let i = 0; i < 3; i++) {
+                if (_tri[i] !== vid) { if (a === -1) a = _tri[i]; else b = _tri[i]; }
+            }
+            topology.vertex_read_coordinate(_vb, 0, a);
+            topology.vertex_read_coordinate(_vc, 0, b);
+            const ax = _vb[0] - ox, ay = _vb[1] - oy, az = _vb[2] - oz;
+            const bx = _vc[0] - ox, by = _vc[1] - oy, bz = _vc[2] - oz;
+            const cx = ay * bz - az * by, cy = az * bx - ax * bz, cz = ax * by - ay * bx;
+            angle += Math.atan2(Math.hypot(cx, cy, cz), ax * bx + ay * by + az * bz);
+        }
+        result = angle > Math.PI + 1e-6;
+    }
+
+    _corner_cache.set(vid, result);
+    return result;
+}
+
+// ---- node storage ----------------------------------------------------------------------------------
+
+// Search nodes are fixed 16-word records packed into one flat ArrayBuffer, addressed by id*NODE_WORDS,
+// so the open list is a Uint32Heap4 (id + score) rather than an object heap -- NO per-node object
+// allocation, so the hot path produces no garbage and never triggers a GC pause (which would otherwise
+// jitter the rest of the engine). Allocation is a monotonic bump counter reset per query; nodes are
+// never released mid-query, so there is no free list and no occupancy bookkeeping. The buffer only ever
+// grows (by doubling, copying the existing records over) and the two typed-array views are re-cached
+// after a grow. (A pooled allocator with a free list + occupancy bitset degenerates to exactly this
+// under a never-free, bump-allocated access pattern, so a raw buffer is the honest, lighter shape.)
+//
+// A node stores its entry edge as vertex ids (E0V,E1V) AND its 2D positions in the node's unfolded frame
+// (E0X,E0Y,E1X,E1Y), the root (ROOTVID + RX,RY in the frame; ROOTVID==NULL_ID is the start point), and
+// the interval as the fractions [T0,T1] along the edge. 3D is recovered at reconstruction from vertex
+// ids; a terminal node stores the goal edge (E0V,E1V) and the final bend's fraction along it (N_FCT,
+// -1 == a straight shot, since a real bend fraction is in [0,1]).
+const N_FACE = 0, N_E0V = 1, N_E1V = 2;
+const N_E0X = 3, N_E0Y = 4, N_E1X = 5, N_E1Y = 6;
+const N_ROOTVID = 7, N_RX = 8, N_RY = 9;
+const N_T0 = 10, N_T1 = 11;
+const N_G = 12, N_PARENT = 13, N_TERMINAL = 14, N_FCT = 15;
+const NODE_WORDS = 16;
+const NULL_ID = 0xFFFFFFFF;
+
+const _open = new Uint32Heap4();
+
+// node records: uint32 and float32 views overlaid on one ArrayBuffer (_node_df aliases _node_du's bytes)
+let _node_capacity = 1024;                            // capacity in nodes; grows by doubling
+let _node_du = new Uint32Array(_node_capacity * NODE_WORDS);
+let _node_df = new Float32Array(_node_du.buffer);
+let _node_count = 0;
+
+/** Reserve the next node slot, growing (and re-caching the views) only when the buffer is full. */
+function alloc_node() {
+    const id = _node_count++;
+    if (id >= _node_capacity) {
+        _node_capacity *= 2;
+        const grown = new Uint32Array(_node_capacity * NODE_WORDS);
+        grown.set(_node_du); // copy the existing records into the larger buffer
+        _node_du = grown;
+        _node_df = new Float32Array(grown.buffer);
+    }
+    return id;
+}
+
+// the start/goal 3D points (for the heuristic and for lifting the path back to 3D)
+let _sx = 0, _sy = 0, _sz = 0;
+let _gx = 0, _gy = 0, _gz = 0;
+
+// goal-face vertices + barycentric weights of the goal point (to place the goal in any node's frame)
+let _goal_v0 = 0, _goal_v1 = 0, _goal_v2 = 0;
+let _goal_w0 = 0, _goal_w1 = 0, _goal_w2 = 0;
+const _bw = new Float64Array(3);
+
+// edge-crossing points (flat x,y,z triples) gathered along the parent chain during reconstruction
+const _recon = [];
+
+function goal_weight(vid) {
+    return vid === _goal_v0 ? _goal_w0 : (vid === _goal_v1 ? _goal_w1 : _goal_w2);
+}
+
+// ---- search ----------------------------------------------------------------------------------------
+
+/**
+ * Find the exact shortest path from (sx,sy,sz) in `start_face` to (gx,gy,gz) in `goal_face`.
+ *
+ * @param {number[]|Float64Array|Float32Array} output path written as flat [x0,y0,z0, x1,y1,z1, ...]
+ * @param {BinaryTopology} topology triangle mesh (3D vertex coordinates)
+ * @param {number} sx
+ * @param {number} sy
+ * @param {number} sz start point (assumed on/near `start_face`)
+ * @param {number} start_face triangle containing the start point
+ * @param {number} gx
+ * @param {number} gy
+ * @param {number} gz goal point (assumed on/near `goal_face`)
+ * @param {number} goal_face triangle containing the goal point
+ * @returns {number} number of path POINTS written (3 numbers each), 0 if no path
+ */
+export function bt_mesh_face_find_path_polyanya(output, topology, sx, sy, sz, start_face, gx, gy, gz, goal_face) {
+    _sx = sx; _sy = sy; _sz = sz;
+    _gx = gx; _gy = gy; _gz = gz;
+
+    _corner_cache.clear();
+    _covered.clear();
+    _node_count = 0;
+    _open.clear();
+
+    if (start_face === goal_face) {
+        output[0] = sx; output[1] = sy; output[2] = sz;
+        output[3] = gx; output[4] = gy; output[5] = gz;
+        return 2;
+    }
+
+    // goal barycentric, so the goal can be unfolded into any frame that reaches the goal face
+    triangle_vertices(topology, goal_face);
+    _goal_v0 = _tri[0]; _goal_v1 = _tri[1]; _goal_v2 = _tri[2];
+    barycentric_3d(topology, _goal_v0, _goal_v1, _goal_v2, gx, gy, gz, _bw);
+    _goal_w0 = _bw[0]; _goal_w1 = _bw[1]; _goal_w2 = _bw[2];
+
+    // lay the start face out in 2D (CCW: apex on the +y/left side of edge a->b) and place the start point
+    triangle_vertices(topology, start_face);
+    const a = _tri[0], b = _tri[1], c = _tri[2];
+    const dab = vid_distance_3d(topology, a, b);
+    const dac = vid_distance_3d(topology, a, c);
+    const dbc = vid_distance_3d(topology, b, c);
+    const cx = (dac * dac - dbc * dbc + dab * dab) / (2 * dab);
+    let ch2 = dac * dac - cx * cx; if (ch2 < 0) ch2 = 0;
+    const cy = Math.sqrt(ch2); // p_a=(0,0), p_b=(dab,0), p_c=(cx,cy)
+
+    barycentric_3d(topology, a, b, c, sx, sy, sz, _bw);
+    const su = _bw[1] * dab + _bw[2] * cx;
+    const sv = _bw[2] * cy;
+
+    // the start point sees all three edges of its triangle in full
+    start_edge(topology, su, sv, start_face, a, b, 0, 0, dab, 0, goal_face);
+    start_edge(topology, su, sv, start_face, b, c, dab, 0, cx, cy, goal_face);
+    start_edge(topology, su, sv, start_face, c, a, cx, cy, 0, 0, goal_face);
+
+    let best = NULL_ID;
+    let guard = 0;
+    while (!_open.is_empty()) {
+        const id = _open.pop_min();
+        if (_node_du[id * NODE_WORDS + N_TERMINAL] === 1) { best = id; break; }
+        if (++guard > 5_000_000) break;
+        expand(topology, id, goal_face);
+    }
+
+    if (best === NULL_ID) return 0;
+
+    // Reconstruct a SURFACE-FOLLOWING path. Every node in the parent chain shares one continuous unfolded
+    // frame (each node's frame extends its parent's), so the whole route -- start, turning corners, goal --
+    // lays out as a single 2D polyline in that frame, and the point where the route crosses each face's
+    // entry edge is just the intersection of that polyline with the edge. Lifting each crossing back onto
+    // its 3D edge keeps every output segment inside one face (i.e. on the surface). Crossings that fall on
+    // a straight (flat) stretch collapse away in push_point, so flat meshes still yield minimal paths.
+    const du = _node_du, df = _node_df;
+    const bb = best * NODE_WORDS;
+
+    // the goal's position in the shared frame: unfold the goal-face apex from the terminal's entry edge
+    const t_e0v = du[bb + N_E0V], t_e1v = du[bb + N_E1V];
+    const t_e0x = df[bb + N_E0X], t_e0y = df[bb + N_E0Y], t_e1x = df[bb + N_E1X], t_e1y = df[bb + N_E1Y];
+    const g_apex = unfold_apex(topology, goal_face, t_e0v, t_e1v, t_e0x, t_e0y, t_e1x, t_e1y);
+    const goal_u = goal_weight(t_e0v) * t_e0x + goal_weight(t_e1v) * t_e1x + goal_weight(g_apex) * _apex[0];
+    const goal_v = goal_weight(t_e0v) * t_e0y + goal_weight(t_e1v) * t_e1y + goal_weight(g_apex) * _apex[1];
+    const t_fct = df[bb + N_FCT];
+
+    // walk the chain (goal end -> start), recording each entry-edge crossing in reverse path order
+    _recon.length = 0;
+    let next_u = goal_u, next_v = goal_v;     // the next waypoint toward the goal, in the shared frame
+    let prev_root = du[bb + N_ROOTVID];
+    let prev_rx = df[bb + N_RX], prev_ry = df[bb + N_RY];
+
+    for (let n = best; n !== NULL_ID; n = du[n * NODE_WORDS + N_PARENT]) {
+        const base = n * NODE_WORDS;
+        const rootVid = du[base + N_ROOTVID];
+        const rx = df[base + N_RX], ry = df[base + N_RY];
+
+        // a change of root means the route turned at the previous corridor's root: emit that corner
+        // (an exact mesh vertex -- the turning point) and aim subsequent crossings at it
+        if (rootVid !== prev_root) {
+            if (prev_root !== NULL_ID) {
+                topology.vertex_read_coordinate(_va, 0, prev_root);
+                _recon.push(_va[0], _va[1], _va[2]);
+            }
+            next_u = prev_rx; next_v = prev_ry;
+            prev_root = rootVid;
+        }
+
+        const e0v = du[base + N_E0V], e1v = du[base + N_E1V];
+        const e0x = df[base + N_E0X], e0y = df[base + N_E0Y], e1x = df[base + N_E1X], e1y = df[base + N_E1Y];
+
+        // fraction along the entry edge where the route root->next crosses it (the terminal's goal-edge
+        // bend is exact and pre-computed as N_FCT)
+        let u;
+        if (n === best && t_fct !== -1) {
+            u = t_fct;
+        } else {
+            u = line_segment_intersection_fraction_2d(rx, ry, next_u, next_v, e0x, e0y, e1x, e1y);
+            if (u === -1) {
+                // the route line grazes a shared vertex (passes through / just outside an edge endpoint,
+                // common when the geodesic runs along a row of grid vertices): snap to the nearer endpoint
+                const dx = next_u - rx, dy = next_v - ry;
+                const s0 = Math.abs(dx * (e0y - ry) - dy * (e0x - rx));
+                const s1 = Math.abs(dx * (e1y - ry) - dy * (e1x - rx));
+                u = s0 <= s1 ? 0 : 1;
+            }
+        }
+
+        topology.vertex_read_coordinate(_va, 0, e0v);
+        topology.vertex_read_coordinate(_vb, 0, e1v);
+        _recon.push(_va[0] + (_vb[0] - _va[0]) * u, _va[1] + (_vb[1] - _va[1]) * u, _va[2] + (_vb[2] - _va[2]) * u);
+
+        prev_rx = rx; prev_ry = ry;
+    }
+
+    // start, the crossings in path order (reverse of how they were collected), goal
+    let count = 0;
+    count = push_point(output, count, _sx, _sy, _sz);
+    for (let i = _recon.length - 3; i >= 0; i -= 3) {
+        count = push_point(output, count, _recon[i], _recon[i + 1], _recon[i + 2]);
+    }
+    count = push_point(output, count, _gx, _gy, _gz);
+    return count / 3;
+}
+
+/**
+ * Append a 3D point, collapsing collinear runs: if the previous point lies (within tolerance) on the
+ * segment between the one before it and the new point, it is redundant and gets replaced rather than
+ * kept. Flat stretches of a surface-following path thus reduce to their endpoints; genuine bends (turning
+ * corners, folds in the surface) survive.
+ */
+function push_point(output, count, x, y, z) {
+    if (count >= 6) {
+        const ax = output[count - 6], ay = output[count - 5], az = output[count - 4];
+        const bx = output[count - 3], by = output[count - 2], bz = output[count - 1];
+        const abx = bx - ax, aby = by - ay, abz = bz - az;
+        const acx = x - ax, acy = y - ay, acz = z - az;
+        const cross_x = aby * acz - abz * acy, cross_y = abz * acx - abx * acz, cross_z = abx * acy - aby * acx;
+        const ac_len = Math.hypot(acx, acy, acz);
+        if (ac_len < DEDUP_EPS || Math.hypot(cross_x, cross_y, cross_z) <= COLLINEAR_EPS * ac_len) {
+            output[count - 3] = x; output[count - 2] = y; output[count - 1] = z;
+            return count;
+        }
+    } else if (count >= 3 &&
+        Math.abs(output[count - 3] - x) <= DEDUP_EPS &&
+        Math.abs(output[count - 2] - y) <= DEDUP_EPS &&
+        Math.abs(output[count - 1] - z) <= DEDUP_EPS) {
+        return count;
+    }
+    output[count] = x; output[count + 1] = y; output[count + 2] = z;
+    return count + 3;
+}
+
+function start_edge(topology, su, sv, start_face, ea, eb, eax, eay, ebx, eby, goal_face) {
+    const neighbour = neighbour_across(topology, start_face, ea, eb);
+    add_successor(topology, neighbour, start_face, ea, eb, eax, eay, ebx, eby, su, sv, -1, 0, NULL_ID, 0, 1, goal_face);
+}
+
+function expand(topology, id, goal_face) {
+    const du = _node_du, df = _node_df;
+    const base = id * NODE_WORDS;
+
+    const face = du[base + N_FACE];
+    const e0v = du[base + N_E0V], e1v = du[base + N_E1V];
+    const e0x = df[base + N_E0X], e0y = df[base + N_E0Y];
+    const e1x = df[base + N_E1X], e1y = df[base + N_E1Y];
+    const rv = du[base + N_ROOTVID]; const rootVid = rv === NULL_ID ? -1 : rv;
+    const rx = df[base + N_RX], ry = df[base + N_RY];
+    const t0 = df[base + N_T0], t1 = df[base + N_T1];
+    const g = df[base + N_G];
+
+    // interval endpoints + their edge vertex ids, ordered so i1 is left of the ray root->i0
+    let i0x = e0x + t0 * (e1x - e0x), i0y = e0y + t0 * (e1y - e0y), i0v = t0 <= PEPS ? e0v : (t0 >= 1 - PEPS ? e1v : -1);
+    let i1x = e0x + t1 * (e1x - e0x), i1y = e0y + t1 * (e1y - e0y), i1v = t1 <= PEPS ? e0v : (t1 >= 1 - PEPS ? e1v : -1);
+    if (triangle2d_compute_area(rx, ry, i0x, i0y, i1x, i1y) < 0) {
+        const sxx = i0x, syy = i0y, svv = i0v;
+        i0x = i1x; i0y = i1y; i0v = i1v; i1x = sxx; i1y = syy; i1v = svv;
+    }
+
+    // unfold the apex into this node's frame, giving the two far edges (e0v,apex) and (apex,e1v)
+    const apex = unfold_apex(topology, face, e0v, e1v, e0x, e0y, e1x, e1y);
+    const apx = _apex[0], apy = _apex[1];
+
+    process_far_edge(topology, face, e0v, e0x, e0y, apex, apx, apy, rx, ry, rootVid, g, id, i0x, i0y, i0v, i1x, i1y, i1v, goal_face);
+    process_far_edge(topology, face, apex, apx, apy, e1v, e1x, e1y, rx, ry, rootVid, g, id, i0x, i0y, i0v, i1x, i1y, i1v, goal_face);
+}
+
+const _split = new Float64Array(2);
+
+function process_far_edge(topology, from_face, Pv, Px, Py, Qv, Qx, Qy, rx, ry, rootVid, g, parent, i0x, i0y, i0v, i1x, i1y, i1v, goal_face) {
+    const neighbour = neighbour_across(topology, from_face, Pv, Qv);
+
+    let m = 0;
+    const tR = line_segment_intersection_fraction_2d(rx, ry, i0x, i0y, Px, Py, Qx, Qy);
+    const tL = line_segment_intersection_fraction_2d(rx, ry, i1x, i1y, Px, Py, Qx, Qy);
+    // -1 (no crossing) fails `> PEPS`, so the interior-fraction test rejects it without a NaN check
+    if (tR > PEPS && tR < 1 - PEPS) _split[m++] = tR;
+    if (tL > PEPS && tL < 1 - PEPS) _split[m++] = tL;
+    if (m === 2 && _split[0] > _split[1]) { const t = _split[0]; _split[0] = _split[1]; _split[1] = t; }
+
+    let prev = 0;
+    for (let k = 0; k <= m; k++) {
+        const next = k < m ? _split[k] : 1;
+        if (next - prev < PEPS) { prev = next; continue; }
+
+        const mx = Px + (Qx - Px) * (prev + next) * 0.5, my = Py + (Qy - Py) * (prev + next) * 0.5;
+        const sR = triangle2d_compute_area(rx, ry, i0x, i0y, mx, my); // >=0: left of right-ray (inside cone)
+        const sL = triangle2d_compute_area(rx, ry, i1x, i1y, mx, my); // <=0: right of left-ray (inside cone)
+
+        if (sR >= -EPS && sL <= EPS) {
+            add_successor(topology, neighbour, from_face, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid, g, parent, prev, next, goal_face);
+        } else if (sR < -EPS) {
+            if (i0v !== -1 && is_corner(topology, i0v)) {
+                add_successor(topology, neighbour, from_face, Pv, Qv, Px, Py, Qx, Qy, i0x, i0y, i0v, g + v2_distance(rx, ry, i0x, i0y), parent, prev, next, goal_face);
+            }
+        } else {
+            if (i1v !== -1 && is_corner(topology, i1v)) {
+                add_successor(topology, neighbour, from_face, Pv, Qv, Px, Py, Qx, Qy, i1x, i1y, i1v, g + v2_distance(rx, ry, i1x, i1y), parent, prev, next, goal_face);
+            }
+        }
+        prev = next;
+    }
+}
+
+/**
+ * Per (entered edge, root) interval coverage. A fixed root implies a fixed g, so the first node to
+ * cover a stretch of an edge is optimal there -- later nodes are clipped to the still-uncovered part
+ * (or dropped). This is what makes the wavefront terminate instead of re-flooding the same edges.
+ */
+const _covered = new Map();
+const ROOT_STRIDE = 0x1000000;
+const _uncovered = new Float64Array(256);
+
+function reserve(from_face, neighbour, root_vid, lo, hi) {
+    let by_root = _covered.get(from_face);
+    if (by_root === undefined) { by_root = new Map(); _covered.set(from_face, by_root); }
+
+    const inner_key = neighbour * ROOT_STRIDE + (root_vid + 1);
+    let ranges = by_root.get(inner_key);
+    if (ranges === undefined) { ranges = []; by_root.set(inner_key, ranges); }
+
+    let out = 0;
+    let cur = lo;
+    for (let i = 0; i < ranges.length; i += 2) {
+        const r_lo = ranges[i], r_hi = ranges[i + 1];
+        if (r_hi <= cur) continue;
+        if (r_lo >= hi) break;
+        if (r_lo > cur) { _uncovered[out++] = cur; _uncovered[out++] = r_lo < hi ? r_lo : hi; }
+        if (r_hi > cur) cur = r_hi;
+        if (cur >= hi) break;
+    }
+    if (cur < hi) { _uncovered[out++] = cur; _uncovered[out++] = hi; }
+
+    let i = 0;
+    while (i < ranges.length && ranges[i + 1] < lo - PEPS) i += 2;
+    let merge_lo = lo, merge_hi = hi, j = i;
+    while (j < ranges.length && ranges[j] <= hi + PEPS) {
+        if (ranges[j] < merge_lo) merge_lo = ranges[j];
+        if (ranges[j + 1] > merge_hi) merge_hi = ranges[j + 1];
+        j += 2;
+    }
+    ranges.splice(i, j - i, merge_lo, merge_hi);
+
+    return out;
+}
+
+/**
+ * Clip the interval (edge fractions [lo,hi] along Pv->Qv) against what has already been reached on this
+ * edge from `rootVid`, then emit a search node (or terminal, if the entered face holds the goal) for
+ * each still-uncovered piece.
+ */
+function add_successor(topology, neighbour, from_face, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid, g, parent, lo, hi, goal_face) {
+    if (neighbour === NULL_POINTER) return; // boundary far edge -- nothing to enter
+    if (hi - lo < PEPS) return;
+
+    const out = reserve(from_face, neighbour, rootVid, lo, hi);
+    for (let i = 0; i < out; i += 2) {
+        const ulo = _uncovered[i], uhi = _uncovered[i + 1];
+        if (uhi - ulo < PEPS) continue;
+        emit_node(topology, neighbour, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid, g, parent, ulo, uhi, goal_face);
+    }
+}
+
+function emit_node(topology, neighbour, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid, g, parent, t0, t1, goal_face) {
+    if (neighbour === goal_face) {
+        // unfold the goal into this frame for the exact final cost: place the apex, then barycentric
+        const apex = unfold_apex(topology, goal_face, Pv, Qv, Px, Py, Qx, Qy);
+        const ggx = goal_weight(Pv) * Px + goal_weight(Qv) * Qx + goal_weight(apex) * _apex[0];
+        const ggy = goal_weight(Pv) * Py + goal_weight(Qv) * Qy + goal_weight(apex) * _apex[1];
+
+        let i0x = Px + t0 * (Qx - Px), i0y = Py + t0 * (Qy - Py), i0p = t0;
+        let i1x = Px + t1 * (Qx - Px), i1y = Py + t1 * (Qy - Py), i1p = t1;
+        if (triangle2d_compute_area(rx, ry, i0x, i0y, i1x, i1y) < 0) {
+            const sxx = i0x, syy = i0y, sp = i0p; i0x = i1x; i0y = i1y; i0p = i1p; i1x = sxx; i1y = syy; i1p = sp;
+        }
+
+        const fcost = g + touch_distance(rx, ry, i0x, i0y, i1x, i1y, ggx, ggy);
+
+        let fct = -1; // -1 = straight shot (no forced bend at an interval endpoint); a real bend is in [0,1]
+        let tx = ggx, ty = ggy;
+        if (triangle2d_compute_area(i0x, i0y, i1x, i1y, rx, ry) * triangle2d_compute_area(i0x, i0y, i1x, i1y, ggx, ggy) > 0) {
+            reflect(ggx, ggy, i0x, i0y, i1x, i1y); tx = _reflect[0]; ty = _reflect[1];
+        }
+        const t = line_segment_intersection_fraction_2d(rx, ry, tx, ty, i0x, i0y, i1x, i1y);
+        if (t < -PEPS || t > 1 + PEPS) { // -1 (no crossing) is caught by `< -PEPS`
+            const d0 = v2_distance(rx, ry, i0x, i0y) + v2_distance(i0x, i0y, ggx, ggy);
+            const d1 = v2_distance(rx, ry, i1x, i1y) + v2_distance(i1x, i1y, ggx, ggy);
+            fct = d0 <= d1 ? i0p : i1p;
+        }
+
+        const id = alloc_node();
+        const du = _node_du, df = _node_df;
+        const b = id * NODE_WORDS;
+        du[b + N_TERMINAL] = 1;
+        du[b + N_ROOTVID] = rootVid === -1 ? NULL_ID : rootVid;
+        du[b + N_E0V] = Pv; du[b + N_E1V] = Qv;
+        df[b + N_E0X] = Px; df[b + N_E0Y] = Py; df[b + N_E1X] = Qx; df[b + N_E1Y] = Qy;
+        df[b + N_RX] = rx; df[b + N_RY] = ry;
+        du[b + N_PARENT] = parent;
+        df[b + N_FCT] = fct;
+        _open.insert(id, fcost);
+        return;
+    }
+
+    // admissible heuristic in 3D: exact straight-chord root -> interval -> goal
+    let r3x, r3y, r3z;
+    if (rootVid === -1) { r3x = _sx; r3y = _sy; r3z = _sz; }
+    else { topology.vertex_read_coordinate(_qa, 0, rootVid); r3x = _qa[0]; r3y = _qa[1]; r3z = _qa[2]; }
+    topology.vertex_read_coordinate(_va, 0, Pv);
+    topology.vertex_read_coordinate(_vb, 0, Qv);
+    const h = touch_distance_3d(
+        r3x, r3y, r3z,
+        _va[0] + t0 * (_vb[0] - _va[0]), _va[1] + t0 * (_vb[1] - _va[1]), _va[2] + t0 * (_vb[2] - _va[2]),
+        _va[0] + t1 * (_vb[0] - _va[0]), _va[1] + t1 * (_vb[1] - _va[1]), _va[2] + t1 * (_vb[2] - _va[2]),
+        _gx, _gy, _gz);
+
+    const id = alloc_node();
+    const du = _node_du, df = _node_df;
+    const b = id * NODE_WORDS;
+    du[b + N_TERMINAL] = 0;
+    du[b + N_FACE] = neighbour;
+    du[b + N_E0V] = Pv; du[b + N_E1V] = Qv;
+    df[b + N_E0X] = Px; df[b + N_E0Y] = Py; df[b + N_E1X] = Qx; df[b + N_E1Y] = Qy;
+    du[b + N_ROOTVID] = rootVid === -1 ? NULL_ID : rootVid;
+    df[b + N_RX] = rx; df[b + N_RY] = ry;
+    df[b + N_T0] = t0; df[b + N_T1] = t1;
+    df[b + N_G] = g;
+    du[b + N_PARENT] = parent;
+    _open.insert(id, g + h);
+}