@woosh/meep-engine 2.163.7 → 2.163.9

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

@@ -1,82 +1,564 @@
 import { assert } from "../../../core/assert.js";
 import { Uint32Heap } from "../../../core/collection/heap/Uint32Heap.js";
-import { bt_face_get_centroid } from "../../../core/geom/3d/topology/struct/binary/query/bt_face_get_centroid.js";
+import { NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import {
     bt_face_get_neighbour_faces
 } from "../../../core/geom/3d/topology/struct/binary/query/bt_face_get_neighbour_faces.js";
+import {
+    bt_mesh_compute_edge_distance_eikonal
+} from "../../../core/geom/3d/topology/struct/binary/query/bt_mesh_compute_edge_distance_eikonal.js";
 
-const open = new Uint32Heap();
+/**
+ * Note that we limit the supported number of neighbors, a reasonable mesh will fit this criteria
+ * @type {Uint32Array}
+ */
+const neighbors = new Uint32Array(256);
+
+/**
+ * Geodesic distance (along the surface) from the goal face to every reached vertex. Rebuilt per
+ * query; reused to avoid re-allocation.
+ * @type {Map<number, number>}
+ */
+const geodesic_distance = new Map();
 
 /**
+ * Vertices whose geodesic distance has been finalised by the Fast Marching pass.
  * @type {Set<number>}
  */
-const closed = new Set();
+const frozen_vertices = new Set();
 
 /**
- * Least known traversal cost (sum of centroid-to-centroid distances) from start to each face.
- * @type {Map<number, number>}
+ * Faces already settled by the corridor trace / fallback search. Reused across passes.
+ * @type {Set<number>}
+ */
+const visited_faces = new Set();
+
+/**
+ * Priority queue, reused by the Fast Marching fill (ordered by f = distance + heuristic) and by the
+ * fallback corridor search (ordered by distance to goal).
+ * @type {Uint32Heap}
  */
-const g_score = new Map();
+const open = new Uint32Heap();
 
 /**
- * Reconstruction parent pointers: face -> the face we reached it from on the best path.
+ * Reconstruction parent pointers for the fallback search: face -> the face we reached it from.
  * @type {Map<number, number>}
  */
 const came_from = new Map();
 
+const scratch_face_vertices = [0, 0, 0];
+
+// scratch vertex position used by the Fast Marching pass (kept apart from the trace's pos_* scratch)
+const scratch_vertex_pos = new Float64Array(3);
+
+// the three vertex positions of the face currently being traced
+const pos_a = new Float64Array(3);
+const pos_b = new Float64Array(3);
+const pos_c = new Float64Array(3);
+
+// in-plane orthonormal basis of the current face (origin at vertex A)
+const basis_u = new Float64Array(3);
+const basis_v = new Float64Array(3);
+
+// the goal-distance field value at each vertex of the current face
+const scratch_field = new Float64Array(3);
+
+const scratch_centroid = new Float64Array(3);
+
+// communicates the ray parameter of the chosen exit edge out of pick_exit_edge (avoids allocation)
+let last_exit_t = 0;
+
+// number of vertices the last Fast Marching pass froze; bounds the corridor trace's iteration count
+let frozen_count = 0;
+
 /**
- * Note that we limit the supported number of neighbors, a reasonable mesh will fit this criteria
- * @type {Uint32Array}
+ * Read the three vertex IDs of a triangular face into `out` (length 3). Faces are assumed triangular.
+ *
+ * @param {number[]} out
+ * @param {BinaryTopology} topology
+ * @param {number} face
+ * @returns {boolean} false if the face has no loop (uninitialised / out of bounds)
  */
-const neighbors = new Uint32Array(256);
+function face_read_vertices(out, topology, face) {
+    const loop_a = topology.face_read_loop(face);
+
+    if (loop_a === NULL_POINTER) {
+        return false;
+    }
 
-const scratch_array_f32 = new Float32Array(6);
+    const loop_b = topology.loop_read_next(loop_a);
+    const loop_c = topology.loop_read_next(loop_b);
+
+    out[0] = topology.loop_read_vertex(loop_a);
+    out[1] = topology.loop_read_vertex(loop_b);
+    out[2] = topology.loop_read_vertex(loop_c);
+
+    return true;
+}
+
+/**
+ * Straight-line distance between two vertices.
+ */
+function vertex_distance(topology, a, b) {
+    topology.vertex_read_coordinate(scratch_vertex_pos, 0, a);
+    const ax = scratch_vertex_pos[0], ay = scratch_vertex_pos[1], az = scratch_vertex_pos[2];
+
+    topology.vertex_read_coordinate(scratch_vertex_pos, 0, b);
+    const dx = ax - scratch_vertex_pos[0], dy = ay - scratch_vertex_pos[1], dz = az - scratch_vertex_pos[2];
+
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/**
+ * Straight-line distance from a vertex to a point. Admissible/consistent heuristic for the geodesic
+ * (true geodesic distance is never shorter than the straight line), used to make the fill goal-directed.
+ */
+function vertex_distance_to_point(topology, vertex, px, py, pz) {
+    topology.vertex_read_coordinate(scratch_vertex_pos, 0, vertex);
+    const dx = scratch_vertex_pos[0] - px, dy = scratch_vertex_pos[1] - py, dz = scratch_vertex_pos[2] - pz;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+}
+
+/**
+ * The vertex of `face` that is neither `a` nor `b`, or -1 if the face does not have one.
+ */
+function third_vertex(topology, face, a, b) {
+    let loop = topology.face_read_loop(face);
+
+    for (let i = 0; i < 3; i++) {
+        const v = topology.loop_read_vertex(loop);
+
+        if (v !== a && v !== b) {
+            return v;
+        }
+
+        loop = topology.loop_read_next(loop);
+    }
+
+    return -1;
+}
 
 /**
- * Straight-line distance between the centroids of two faces.
+ * Solve the geodesic distance field outward from the goal face using Fast Marching (the exact Eikonal
+ * triangle update). The field is goal-directed: the heap is ordered by `distance + h`, where `h` is the
+ * straight-line distance to the start centroid, so the wavefront sweeps toward the start (exploring the
+ * start<->goal "ellipse" rather than the whole component). With `early_terminate` it stops the instant
+ * all three start-face vertices are finalised -- by then every vertex on the geodesic corridor (all of
+ * which are nearer the goal, hence finalised earlier) is resolved.
  *
- * This is used both as the step cost (between adjacent faces) and as the heuristic (from a face to
- * the goal). Because, by the triangle inequality, the straight-line distance from any face to the
- * goal is never greater than the summed centroid-to-centroid distance of an actual face path between
- * them, the heuristic is admissible AND consistent. A* therefore returns a shortest-distance corridor
- * (under the centroid metric) rather than a fewest-faces one.
+ * The heap uses lazy deletion (stale entries are skipped on pop) instead of an O(n) decrease-key.
  *
- * @param {number} a
- * @param {number} b
  * @param {BinaryTopology} topology
- * @returns {number}
+ * @param {number} goal_face seed of the wavefront (distance 0)
+ * @param {number} start_face heuristic target / early-termination target
+ * @param {boolean} early_terminate
+ * @returns {boolean} true if the start face was reached (a path exists), false otherwise
  */
-function face_centroid_distance(a, b, topology) {
-    bt_face_get_centroid(scratch_array_f32, 0, topology, a);
-    bt_face_get_centroid(scratch_array_f32, 3, topology, b);
+function solve_geodesic_field(topology, goal_face, start_face, early_terminate) {
+    geodesic_distance.clear();
+    frozen_vertices.clear();
+    open.clear();
+
+    // start-face vertices (early-termination target) and centroid (heuristic target)
+    face_read_vertices(scratch_face_vertices, topology, start_face);
+    const start_v0 = scratch_face_vertices[0];
+    const start_v1 = scratch_face_vertices[1];
+    const start_v2 = scratch_face_vertices[2];
+
+    topology.vertex_read_coordinate(pos_a, 0, start_v0);
+    topology.vertex_read_coordinate(pos_b, 0, start_v1);
+    topology.vertex_read_coordinate(pos_c, 0, start_v2);
+    const start_x = (pos_a[0] + pos_b[0] + pos_c[0]) / 3;
+    const start_y = (pos_a[1] + pos_b[1] + pos_c[1]) / 3;
+    const start_z = (pos_a[2] + pos_b[2] + pos_c[2]) / 3;
+
+    // seed the goal-face vertices at distance 0
+    face_read_vertices(scratch_face_vertices, topology, goal_face);
+    for (let i = 0; i < 3; i++) {
+        const gv = scratch_face_vertices[i];
+        if (!geodesic_distance.has(gv)) {
+            geodesic_distance.set(gv, 0);
+            open.insert(gv, vertex_distance_to_point(topology, gv, start_x, start_y, start_z));
+        }
+    }
 
-    const dx = scratch_array_f32[0] - scratch_array_f32[3];
-    const dy = scratch_array_f32[1] - scratch_array_f32[4];
-    const dz = scratch_array_f32[2] - scratch_array_f32[5];
+    frozen_count = 0;
 
-    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    while (!open.is_empty()) {
+        const v = open.pop_min();
+
+        if (frozen_vertices.has(v)) {
+            continue; // stale heap entry (lazy deletion)
+        }
+
+        frozen_vertices.add(v);
+        frozen_count++;
+
+        if (early_terminate
+            && (v === start_v0 || v === start_v1 || v === start_v2)
+            && frozen_vertices.has(start_v0) && frozen_vertices.has(start_v1) && frozen_vertices.has(start_v2)
+        ) {
+            return true; // start face fully resolved; the whole corridor is finalised
+        }
+
+        const g_v = geodesic_distance.get(v);
+
+        // walk v's disk cycle (every edge incident to v)
+        const edge_first = topology.vertex_read_edge(v);
+        if (edge_first === NULL_POINTER) {
+            continue;
+        }
+
+        let edge = edge_first;
+        do {
+            const ev1 = topology.edge_read_vertex1(edge);
+            const ev2 = topology.edge_read_vertex2(edge);
+            const v_is_first = ev1 === v;
+            const w = v_is_first ? ev2 : ev1;
+
+            if (frozen_vertices.has(w)) {
+                // both ends of this edge are finalised -> propagate the wavefront across each incident
+                // triangle to its third vertex with the exact Eikonal update
+                const g_w = geodesic_distance.get(w);
+
+                const loop_first = topology.edge_read_loop(edge);
+                if (loop_first !== NULL_POINTER) {
+                    let loop = loop_first;
+                    do {
+                        const face = topology.loop_read_face(loop);
+                        const t = third_vertex(topology, face, ev1, ev2);
+
+                        if (t !== -1 && !frozen_vertices.has(t)) {
+                            const d = bt_mesh_compute_edge_distance_eikonal(topology, v, w, g_v, g_w, t);
+                            const existing = geodesic_distance.get(t);
+
+                            if (existing === undefined || d < existing) {
+                                geodesic_distance.set(t, d);
+                                open.insert(t, d + vertex_distance_to_point(topology, t, start_x, start_y, start_z));
+                            }
+                        }
+
+                        loop = topology.loop_read_radial_next(loop);
+                    } while (loop !== loop_first && loop !== NULL_POINTER);
+                }
+            } else {
+                // graph-distance relaxation, so w gets a value even before a finalised front forms across
+                // it; a later Eikonal update lowers it to the true geodesic before w itself is frozen
+                const d = g_v + vertex_distance(topology, v, w);
+                const existing = geodesic_distance.get(w);
+
+                if (existing === undefined || d < existing) {
+                    geodesic_distance.set(w, d);
+                    open.insert(w, d + vertex_distance_to_point(topology, w, start_x, start_y, start_z));
+                }
+            }
+
+            edge = v_is_first ? topology.edge_read_v1_disk_next(edge) : topology.edge_read_v2_disk_next(edge);
+        } while (edge !== edge_first && edge !== NULL_POINTER);
+    }
+
+    // the heap drained: if we were early-terminating, the start was never reached. Either way, report
+    // whether the start face's vertices ended up finalised (a full solve still answers reachability).
+    return frozen_vertices.has(start_v0) && frozen_vertices.has(start_v1) && frozen_vertices.has(start_v2);
 }
 
 /**
- * Walk parent pointers from goal back to start, writing the face sequence into `output` in
- * START -> GOAL order. Never writes more than `max_path_length` entries: if the corridor is longer
- * than that it does not fit the caller's buffer and 0 is returned (no partial/garbage result is used).
+ * The face on the far side of `loop`'s edge, or {@link NULL_POINTER} if the edge is a boundary.
+ */
+function loop_opposite_face(topology, loop, face) {
+    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;
+}
+
+/**
+ * Average of a face's three vertices' distances to the goal. The average (rather than the minimum)
+ * keeps a single near-goal vertex of an oversized triangle from making the whole face look close.
+ * Returns Infinity if any vertex was not reached by the fill.
+ */
+function face_geodesic_distance(topology, face) {
+    if (!face_read_vertices(scratch_face_vertices, topology, face)) {
+        return Infinity;
+    }
+
+    const da = geodesic_distance.get(scratch_face_vertices[0]);
+    const db = geodesic_distance.get(scratch_face_vertices[1]);
+    const dc = geodesic_distance.get(scratch_face_vertices[2]);
+
+    if (da === undefined || db === undefined || dc === undefined) {
+        return Infinity;
+    }
+
+    return (da + db + dc) / 3;
+}
+
+/**
+ * Load the geometry of `face` into module scratch: the three vertex positions, the goal-distance field
+ * value at each vertex, and an in-plane orthonormal basis (origin at vertex A, x-axis along A->B).
+ */
+function load_face_geometry(topology, face) {
+    face_read_vertices(scratch_face_vertices, topology, face);
+
+    topology.vertex_read_coordinate(pos_a, 0, scratch_face_vertices[0]);
+    topology.vertex_read_coordinate(pos_b, 0, scratch_face_vertices[1]);
+    topology.vertex_read_coordinate(pos_c, 0, scratch_face_vertices[2]);
+
+    scratch_field[0] = geodesic_distance.get(scratch_face_vertices[0]);
+    scratch_field[1] = geodesic_distance.get(scratch_face_vertices[1]);
+    scratch_field[2] = geodesic_distance.get(scratch_face_vertices[2]);
+
+    const e1x = pos_b[0] - pos_a[0], e1y = pos_b[1] - pos_a[1], e1z = pos_b[2] - pos_a[2];
+    const e2x = pos_c[0] - pos_a[0], e2y = pos_c[1] - pos_a[1], e2z = pos_c[2] - pos_a[2];
+
+    const e1_len = Math.hypot(e1x, e1y, e1z);
+    basis_u[0] = e1x / e1_len;
+    basis_u[1] = e1y / e1_len;
+    basis_u[2] = e1z / e1_len;
+
+    // n = e1 x e2 (face normal); v = normalize(n x u) completes the in-plane right-handed basis
+    const nx = e1y * e2z - e1z * e2y;
+    const ny = e1z * e2x - e1x * e2z;
+    const nz = e1x * e2y - e1y * e2x;
+
+    const vx = ny * basis_u[2] - nz * basis_u[1];
+    const vy = nz * basis_u[0] - nx * basis_u[2];
+    const vz = nx * basis_u[1] - ny * basis_u[0];
+    const v_len = Math.hypot(vx, vy, vz);
+    basis_v[0] = vx / v_len;
+    basis_v[1] = vy / v_len;
+    basis_v[2] = vz / v_len;
+}
+
+/** Project a world point onto the current face basis x-axis (origin = vertex A). */
+function project_x(px, py, pz) {
+    return (px - pos_a[0]) * basis_u[0] + (py - pos_a[1]) * basis_u[1] + (pz - pos_a[2]) * basis_u[2];
+}
+
+/** Project a world point onto the current face basis y-axis (origin = vertex A). */
+function project_y(px, py, pz) {
+    return (px - pos_a[0]) * basis_v[0] + (py - pos_a[1]) * basis_v[1] + (pz - pos_a[2]) * basis_v[2];
+}
+
+/**
+ * Parameter `t` at which ray (ox,oy)+t*(dx,dy) crosses segment (e0)->(e1) within the segment, or
+ * Infinity if it does not cross ahead of the origin.
+ */
+function ray_segment_t(ox, oy, dx, dy, e0x, e0y, e1x, e1y) {
+    const sx = e1x - e0x;
+    const sy = e1y - e0y;
+
+    const denom = dx * sy - dy * sx;
+
+    if (denom === 0) {
+        return Infinity; // parallel
+    }
+
+    const wx = e0x - ox;
+    const wy = e0y - oy;
+
+    const t = (wx * sy - wy * sx) / denom; // distance along the ray
+    const u = (wx * dy - wy * dx) / denom; // position along the segment
+
+    if (t > 1e-9 && u >= -1e-9 && u <= 1 + 1e-9) {
+        return t;
+    }
+
+    return Infinity;
+}
+
+/**
+ * Among the three edges of a triangle (in the face's 2D basis), find the one the ray (ox,oy)+t*(dx,dy)
+ * exits through (smallest t > 0), and return the face on its far side. Stores the chosen t in
+ * {@link last_exit_t}.
+ */
+function pick_exit_edge(
+    ox, oy, dx, dy,
+    bx, cx, cy,
+    topology, face, loop_ab, loop_bc, loop_ca
+) {
+    let best_t = Infinity;
+    let best_face = NULL_POINTER;
+
+    let t = ray_segment_t(ox, oy, dx, dy, 0, 0, bx, 0); // edge AB
+    if (t < best_t) { best_t = t; best_face = loop_opposite_face(topology, loop_ab, face); }
+
+    t = ray_segment_t(ox, oy, dx, dy, bx, 0, cx, cy); // edge BC
+    if (t < best_t) { best_t = t; best_face = loop_opposite_face(topology, loop_bc, face); }
+
+    t = ray_segment_t(ox, oy, dx, dy, cx, cy, 0, 0); // edge CA
+    if (t < best_t) { best_t = t; best_face = loop_opposite_face(topology, loop_ca, face); }
+
+    last_exit_t = best_t;
+    return best_face;
+}
+
+/**
+ * The unvisited neighbour face with the smallest average goal-distance. Used as a robust fallback when
+ * the gradient march cannot pick a forward exit edge.
+ */
+function lowest_unvisited_neighbour(topology, face) {
+    const count = bt_face_get_neighbour_faces(neighbors, 0, topology, face);
+
+    let best_face = NULL_POINTER;
+    let best_distance = Infinity;
+
+    for (let i = 0; i < count; i++) {
+        const neighbor = neighbors[i];
+
+        if (visited_faces.has(neighbor)) {
+            continue;
+        }
+
+        const distance = face_geodesic_distance(topology, neighbor);
+
+        if (distance < best_distance) {
+            best_distance = distance;
+            best_face = neighbor;
+        }
+    }
+
+    return best_face;
+}
+
+/** Write the centroid of a triangular face into {@link scratch_centroid}. */
+function face_centroid(topology, face) {
+    face_read_vertices(scratch_face_vertices, topology, face);
+
+    topology.vertex_read_coordinate(pos_a, 0, scratch_face_vertices[0]);
+    topology.vertex_read_coordinate(pos_b, 0, scratch_face_vertices[1]);
+    topology.vertex_read_coordinate(pos_c, 0, scratch_face_vertices[2]);
+
+    scratch_centroid[0] = (pos_a[0] + pos_b[0] + pos_c[0]) / 3;
+    scratch_centroid[1] = (pos_a[1] + pos_b[1] + pos_c[1]) / 3;
+    scratch_centroid[2] = (pos_a[2] + pos_b[2] + pos_c[2]) / 3;
+}
+
+/**
+ * Trace the steepest descent of the geodesic field from the start face to the goal face, writing the
+ * face corridor into `output` in START -> GOAL order. Following the in-plane gradient downhill crosses
+ * exactly the faces the true geodesic does, so the corridor admits the shortest path. Returns 0 if the
+ * descent cannot complete (e.g. it has to wind around a hole, where the field's gradient is no longer
+ * a reliable guide) -- the caller then falls back to a graph search.
  *
- * @param {number[]|Uint32Array} output
- * @param {number} start_face
- * @param {number} goal_face
- * @param {Map<number, number>} came_from
- * @param {number} max_path_length
- * @returns {number} number of faces written, or 0 if the corridor exceeds `max_path_length`
- */
-function construct_path(output, start_face, goal_face, came_from, max_path_length) {
+ * @returns {number} faces written, or 0 on failure / if the corridor exceeds `max_path_length`
+ */
+function trace_corridor(output, topology, start_face, goal_face, max_path_length) {
+    visited_faces.clear();
+
+    face_centroid(topology, start_face);
+    let world_x = scratch_centroid[0];
+    let world_y = scratch_centroid[1];
+    let world_z = scratch_centroid[2];
+
+    let current = start_face;
+    let previous = NULL_POINTER;
+    let length = 0;
+
+    // each step adds a fresh face; the count of finalised vertices bounds the reachable faces
+    const iteration_cap = frozen_count * 2 + 8;
+
+    for (let iteration = 0; iteration < iteration_cap; iteration++) {
+        if (length >= max_path_length) {
+            return 0;
+        }
+
+        output[length] = current;
+        length++;
+
+        if (current === goal_face) {
+            return length;
+        }
+
+        visited_faces.add(current);
+
+        load_face_geometry(topology, current);
+
+        const ga = scratch_field[0], gb = scratch_field[1], gc = scratch_field[2];
+
+        const px = project_x(world_x, world_y, world_z);
+        const py = project_y(world_x, world_y, world_z);
+
+        const bx = project_x(pos_b[0], pos_b[1], pos_b[2]); // B.y == 0 by construction
+        const cx = project_x(pos_c[0], pos_c[1], pos_c[2]);
+        const cy = project_y(pos_c[0], pos_c[1], pos_c[2]);
+
+        // in-plane gradient of the (linear) field; descend it (negative gradient points at the goal)
+        const grad_x = (gb - ga) / bx;
+        const grad_y = (gc - ga - grad_x * cx) / cy;
+
+        let dir_x = -grad_x;
+        let dir_y = -grad_y;
+        const dir_len = Math.hypot(dir_x, dir_y);
+
+        let next = NULL_POINTER;
+
+        if (dir_len > 1e-12) {
+            dir_x /= dir_len;
+            dir_y /= dir_len;
+
+            const loop_a = topology.face_read_loop(current);
+            const loop_b = topology.loop_read_next(loop_a);
+            const loop_c = topology.loop_read_next(loop_b);
+
+            next = pick_exit_edge(px, py, dir_x, dir_y, bx, cx, cy, topology, current, loop_a, loop_b, loop_c);
+
+            if (next !== NULL_POINTER && next !== previous && !visited_faces.has(next)) {
+                // follow the gradient: re-enter the next face at the exit point (on the shared edge)
+                const exit_x = px + dir_x * last_exit_t;
+                const exit_y = py + dir_y * last_exit_t;
+
+                world_x = pos_a[0] + exit_x * basis_u[0] + exit_y * basis_v[0];
+                world_y = pos_a[1] + exit_x * basis_u[1] + exit_y * basis_v[1];
+                world_z = pos_a[2] + exit_x * basis_u[2] + exit_y * basis_v[2];
+
+                previous = current;
+                current = next;
+                continue;
+            }
+        }
+
+        // the gradient gave no usable forward edge (a boundary/hole, a vertex hit, or it pointed into
+        // an already-traced face). Fall back to the lowest-field unvisited neighbour, re-entering at
+        // its centroid. If that happens we are near a hole, so the caller will likely re-run as a
+        // graph search; here we just keep the corridor connected.
+        next = lowest_unvisited_neighbour(topology, current);
+
+        if (next === NULL_POINTER) {
+            return 0;
+        }
+
+        face_centroid(topology, next);
+        world_x = scratch_centroid[0];
+        world_y = scratch_centroid[1];
+        world_z = scratch_centroid[2];
+
+        previous = current;
+        current = next;
+    }
+
+    return 0;
+}
+
+/**
+ * Walk parent pointers from goal back to start, writing the face sequence into `output` in
+ * START -> GOAL order, or 0 if the corridor exceeds `max_path_length`.
+ */
+function construct_path(output, start_face, goal_face, max_path_length) {
     let length = 0;
     let current = goal_face;
 
-    // walk back to the start, writing in reverse (goal -> start)
     while (true) {
         if (length >= max_path_length) {
-            // corridor does not fit the output buffer; refuse rather than writing out of bounds
             return 0;
         }
 
@@ -90,7 +572,6 @@ function construct_path(output, start_face, goal_face, came_from, max_path_lengt
         current = came_from.get(current);
     }
 
-    // reverse in place to get START -> GOAL order
     const half_length = length >> 1;
 
     for (let i = 0; i < half_length; i++) {
@@ -104,11 +585,84 @@ function construct_path(output, start_face, goal_face, came_from, max_path_lengt
     return length;
 }
 
+/**
+ * Fallback corridor finder: a best-first walk over faces, always expanding the one currently closest
+ * to the goal on the geodesic field. Always finds a corridor when one exists within the resolved field
+ * (it routes around holes the gradient trace could not), at the cost of not necessarily hugging the
+ * exact geodesic.
+ *
+ * @returns {number} faces written, or 0 if no path / it exceeds `max_path_length`
+ */
+function search_corridor(output, topology, start_face, goal_face, max_path_length) {
+    open.clear();
+    came_from.clear();
+    visited_faces.clear();
+
+    open.insert(start_face, face_geodesic_distance(topology, start_face));
+    visited_faces.add(start_face);
+
+    while (!open.is_empty()) {
+        const current = open.pop_min();
+
+        if (current === goal_face) {
+            return construct_path(output, start_face, goal_face, max_path_length);
+        }
+
+        const count = bt_face_get_neighbour_faces(neighbors, 0, topology, current);
+
+        for (let i = 0; i < count; i++) {
+            const neighbor = neighbors[i];
+
+            if (visited_faces.has(neighbor)) {
+                continue;
+            }
+
+            const distance = face_geodesic_distance(topology, neighbor);
+
+            if (distance === Infinity) {
+                continue; // outside the resolved field
+            }
+
+            visited_faces.add(neighbor);
+            came_from.set(neighbor, current);
+            open.insert(neighbor, distance);
+        }
+    }
+
+    return 0;
+}
+
+/**
+ * Extract the corridor from the resolved field: gradient trace first (hugs the geodesic), graph-walk
+ * fallback for winding around holes.
+ *
+ * @returns {number} faces written, or 0 if neither method produced a corridor
+ */
+function extract_corridor(output, topology, start_face, goal_face, max_path_length) {
+    const traced = trace_corridor(output, topology, start_face, goal_face, max_path_length);
+
+    if (traced !== 0) {
+        return traced;
+    }
+
+    return search_corridor(output, topology, start_face, goal_face, max_path_length);
+}
 
 /**
  * Find a shortest path through topology faces.
  * If a path is found - the result will contain start and goal faces.
  *
+ * The corridor is steered by an exact-geodesic distance field rather than a face-graph metric. A
+ * goal-directed Fast Marching pass (exact Eikonal triangle update) solves the true along-surface
+ * distance-to-goal at each vertex, sweeping toward the start and stopping as soon as the start face is
+ * resolved. Because the field measures the real walked distance (not centroid-to-centroid hops), the
+ * corridor heads straight at the goal and crosses a finely tessellated patch instead of skirting around
+ * it. The corridor is then extracted by descending the field's gradient from the start (which hugs the
+ * geodesic, so the downstream funnel/string-pull recovers the exact shortest path); where the gradient
+ * is an unreliable guide -- winding around a hole -- a best-first graph walk on the same field takes
+ * over. A full (non-early-terminated) solve is used as a backstop for the rare case the bounded fill
+ * left the corridor under-resolved.
+ *
  * NOTE: if either start or goal faces are not part of the topology - an empty path will be produced.
  *
  * @param {number[]|Uint32Array} output path will be written here as a sequence of face IDs
@@ -135,73 +689,42 @@ export function bt_mesh_face_find_path(
     assert.defined(topology, 'topology');
     assert.equal(topology.isBinaryTopology, true, 'topology.isBinaryTopology !== true');
 
-    open.clear();
-    closed.clear();
-    g_score.clear();
-    came_from.clear();
-
-    g_score.set(start_face_id, 0);
-
-    open.insert(start_face_id, face_centroid_distance(start_face_id, goal_face_id, topology));
-
-    while (!open.is_empty()) {
-
-        const current_node = open.pop_min();
-
-        // Lazy deletion: a face may sit in the heap multiple times if its g-score improved after an
-        // earlier push. The lowest-f entry is popped first; later popped duplicates land on an
-        // already-closed face and must be skipped.
-        if (closed.has(current_node)) {
-            continue;
+    if (start_face_id === goal_face_id) {
+        // trivial path; still validate the face actually exists
+        if (!topology.faces.is_allocated(start_face_id)) {
+            return 0;
         }
 
-        if (current_node === goal_face_id) {
-            // Reached the goal
-            return construct_path(output, start_face_id, goal_face_id, came_from, max_path_length);
+        if (max_path_length < 1) {
+            return 0;
         }
 
-        closed.add(current_node);
-
-        const current_g_score = g_score.get(current_node);
-
-        const neighbor_count = bt_face_get_neighbour_faces(neighbors, 0, topology, current_node);
-
-        for (let i = 0; i < neighbor_count; i++) {
-
-            const neighbor = neighbors[i];
-
-            if (closed.has(neighbor)) {
-                // already closed
-                continue;
-            }
-
-            // step cost is the real geometric distance between adjacent face centroids, so the
-            // search minimises corridor length rather than the number of triangles crossed
-            const traversal_cost = face_centroid_distance(current_node, neighbor, topology);
-
-            const cost_so_far = current_g_score + traversal_cost;
-
-            if (!g_score.has(neighbor) || cost_so_far < g_score.get(neighbor)) {
-                // better path to this neighbour
-
-                g_score.set(neighbor, cost_so_far);
-                came_from.set(neighbor, current_node);
-
-                const remaining_heuristic = face_centroid_distance(neighbor, goal_face_id, topology);
-
-                const f_score = cost_so_far + remaining_heuristic;
+        output[0] = start_face_id;
+        return 1;
+    }
 
-                // Lazy push: always insert. If neighbor was already on the open list, the older
-                // (worse-f) entry will be skipped when popped (see closed-check at the top of the
-                // loop). This avoids an O(n) find_index_by_id scan per relaxation.
-                open.insert(neighbor, f_score);
+    // both faces must be part of the topology
+    if (!topology.faces.is_allocated(start_face_id) || !topology.faces.is_allocated(goal_face_id)) {
+        return 0;
+    }
 
-            }
+    // Fast path: goal-directed fill bounded to the start<->goal region. When the start is unreachable
+    // this drains exhaustively (it never early-exits), so a false return is a definitive "no path" --
+    // no second solve needed.
+    if (!solve_geodesic_field(topology, goal_face_id, start_face_id, true)) {
+        return 0; // no path between the two faces
+    }
 
-        }
+    const corridor = extract_corridor(output, topology, start_face_id, goal_face_id, max_path_length);
 
+    if (corridor !== 0) {
+        return corridor;
     }
 
-    // No result found
-    return 0;
+    // Backstop: the bounded fill resolved enough to reach the start but left the corridor
+    // under-resolved for the extractor (rare; a corridor that winds far around a hole). A full solve
+    // resolves the whole reachable component, then the extractor cannot fail for a connected pair.
+    solve_geodesic_field(topology, goal_face_id, start_face_id, false);
+
+    return extract_corridor(output, topology, start_face_id, goal_face_id, max_path_length);
 }