@woosh/meep-engine 3.1.0 → 3.2.0

package/src/core/geom/3d/topology/struct/binary/query/bt_mesh_face_find_path.js

@@ -1,703 +1,703 @@
-import { bt_face_read_triangle_vertices } from "./bt_face_read_triangle.js";
-import { v3_distance } from "../../../../../vec3/v3_distance.js";
-import { bt_vertex_distance_to_vertex } from "./bt_vertex_distance_to_vertex.js";
-import { assert } from "../../../../../../assert.js";
-import { Uint32Heap } from "../../../../../../collection/heap/Uint32Heap.js";
-import { NULL_POINTER } from "../BinaryTopology.js";
-import { bt_face_get_edge_adjacent_faces } from "./bt_face_get_edge_adjacent_faces.js";
-import {
-    bt_mesh_compute_edge_distance_eikonal
-} from "./bt_mesh_compute_edge_distance_eikonal.js";
-
-/**
- * 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 frozen_vertices = new Set();
-
-/**
- * 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 open = new Uint32Heap();
-
-/**
- * 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;
-
-/**
- * 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)
- */
-
-
-
-/**
- * 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);
-    return v3_distance(scratch_vertex_pos[0], scratch_vertex_pos[1], scratch_vertex_pos[2], px, py, pz);
-}
-
-/**
- * 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;
-}
-
-/**
- * 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.
- *
- * The heap uses lazy deletion (stale entries are skipped on pop) instead of an O(n) decrease-key.
- *
- * @param {BinaryTopology} topology
- * @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 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)
-    bt_face_read_triangle_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
-    bt_face_read_triangle_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));
-        }
-    }
-
-    frozen_count = 0;
-
-    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 + bt_vertex_distance_to_vertex(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);
-}
-
-/**
- * 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 (!bt_face_read_triangle_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) {
-    bt_face_read_triangle_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_edge_adjacent_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) {
-    bt_face_read_triangle_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.
- *
- * @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;
-
-    while (true) {
-        if (length >= max_path_length) {
-            return 0;
-        }
-
-        output[length] = current;
-        length++;
-
-        if (current === start_face) {
-            break;
-        }
-
-        current = came_from.get(current);
-    }
-
-    const half_length = length >> 1;
-
-    for (let i = 0; i < half_length; i++) {
-        const mirror_i = length - 1 - i;
-        const temp = output[i];
-
-        output[i] = output[mirror_i];
-        output[mirror_i] = temp;
-    }
-
-    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_edge_adjacent_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
- * @param {number} start_face_id
- * @param {number} goal_face_id
- * @param {BinaryTopology} topology
- * @param {number} [max_path_length=Infinity] cap on the number of faces written to `output`. If the
- *        shortest corridor is longer than this it does not fit the buffer and 0 is returned. Pass the
- *        capacity of `output` to guarantee no out-of-bounds writes.
- * @returns {number} number of faces that make up the path. This will be 0 if no path is found (or the
- *        path does not fit `max_path_length`).
- */
-export function bt_mesh_face_find_path(
-    output,
-    start_face_id,
-    goal_face_id,
-    topology,
-    max_path_length = Infinity,
-) {
-    assert.isArrayLike(output, 'output');
-    assert.isNonNegativeInteger(start_face_id, 'start_face_id');
-    assert.isNonNegativeInteger(goal_face_id, 'goal_face_id');
-    assert.notNull(topology, 'topology');
-    assert.defined(topology, 'topology');
-    assert.equal(topology.isBinaryTopology, true, 'topology.isBinaryTopology !== true');
-
-    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 (max_path_length < 1) {
-            return 0;
-        }
-
-        output[0] = start_face_id;
-        return 1;
-    }
-
-    // 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;
-    }
-
-    // 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);
-}
+import { bt_face_read_triangle_vertices } from "./bt_face_read_triangle.js";
+import { v3_distance } from "../../../../../vec3/v3_distance.js";
+import { bt_vertex_distance_to_vertex } from "./bt_vertex_distance_to_vertex.js";
+import { assert } from "../../../../../../assert.js";
+import { Uint32Heap } from "../../../../../../collection/heap/Uint32Heap.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_face_get_edge_adjacent_faces } from "./bt_face_get_edge_adjacent_faces.js";
+import {
+    bt_mesh_compute_edge_distance_eikonal
+} from "./bt_mesh_compute_edge_distance_eikonal.js";
+
+/**
+ * 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 frozen_vertices = new Set();
+
+/**
+ * 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 open = new Uint32Heap();
+
+/**
+ * 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;
+
+/**
+ * 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)
+ */
+
+
+
+/**
+ * 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);
+    return v3_distance(scratch_vertex_pos[0], scratch_vertex_pos[1], scratch_vertex_pos[2], px, py, pz);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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.
+ *
+ * The heap uses lazy deletion (stale entries are skipped on pop) instead of an O(n) decrease-key.
+ *
+ * @param {BinaryTopology} topology
+ * @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 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)
+    bt_face_read_triangle_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
+    bt_face_read_triangle_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));
+        }
+    }
+
+    frozen_count = 0;
+
+    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 + bt_vertex_distance_to_vertex(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);
+}
+
+/**
+ * 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 (!bt_face_read_triangle_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) {
+    bt_face_read_triangle_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_edge_adjacent_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) {
+    bt_face_read_triangle_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.
+ *
+ * @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;
+
+    while (true) {
+        if (length >= max_path_length) {
+            return 0;
+        }
+
+        output[length] = current;
+        length++;
+
+        if (current === start_face) {
+            break;
+        }
+
+        current = came_from.get(current);
+    }
+
+    const half_length = length >> 1;
+
+    for (let i = 0; i < half_length; i++) {
+        const mirror_i = length - 1 - i;
+        const temp = output[i];
+
+        output[i] = output[mirror_i];
+        output[mirror_i] = temp;
+    }
+
+    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_edge_adjacent_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
+ * @param {number} start_face_id
+ * @param {number} goal_face_id
+ * @param {BinaryTopology} topology
+ * @param {number} [max_path_length=Infinity] cap on the number of faces written to `output`. If the
+ *        shortest corridor is longer than this it does not fit the buffer and 0 is returned. Pass the
+ *        capacity of `output` to guarantee no out-of-bounds writes.
+ * @returns {number} number of faces that make up the path. This will be 0 if no path is found (or the
+ *        path does not fit `max_path_length`).
+ */
+export function bt_mesh_face_find_path(
+    output,
+    start_face_id,
+    goal_face_id,
+    topology,
+    max_path_length = Infinity,
+) {
+    assert.isArrayLike(output, 'output');
+    assert.isNonNegativeInteger(start_face_id, 'start_face_id');
+    assert.isNonNegativeInteger(goal_face_id, 'goal_face_id');
+    assert.notNull(topology, 'topology');
+    assert.defined(topology, 'topology');
+    assert.equal(topology.isBinaryTopology, true, 'topology.isBinaryTopology !== true');
+
+    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 (max_path_length < 1) {
+            return 0;
+        }
+
+        output[0] = start_face_id;
+        return 1;
+    }
+
+    // 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;
+    }
+
+    // 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);
+}