@woosh/meep-engine 2.163.7 → 2.163.9

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

@@ -1,234 +1,145 @@
-import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
-import { BinaryTopology, NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
-import { bt_faces_shared_loop } from "../../../core/geom/3d/topology/struct/binary/query/bt_faces_shared_loop.js";
-import Vector3 from "../../../core/geom/Vector3.js";
-import { bt_mesh_face_find_path } from "./bt_mesh_face_find_path.js";
-import { navmesh_build_topology } from "./build/navmesh_build_topology.js";
-import { bvh_build_from_bt_mesh } from "./bvh_build_from_bt_mesh.js";
-import { bvh_query_nearest_face } from "./bvh_query_nearest_face.js";
-import { funnel_string_pull } from "./funnel_string_pull.js";
-
-/**
- * Hard cap on the number of faces we traverse in a single path query.
- * Limits scratch buffer sizes; paths longer than this are truncated by the A* search.
- * @type {number}
- */
-const MAX_FACE_PATH_LENGTH = 1024;
-
-// face path IDs or (later) final path vertex indices
-const scratch_array_u32 = new Uint32Array(MAX_FACE_PATH_LENGTH);
-
-// one more portal than face-path length (start portal + one between each consecutive pair of faces + goal portal)
-const MAX_PORTAL_COUNT = MAX_FACE_PATH_LENGTH + 1;
-
-// [left0, right0, left1, right1, ...]
-const scratch_portal_vertices = new Uint32Array(MAX_PORTAL_COUNT * 2);
-
-// flat XYZ triples, one per portal
-const scratch_portal_normals = new Float32Array(MAX_PORTAL_COUNT * 3);
-
-// flat XYZ triples; indices 0 and 1 are start/goal, then 2 vertices per intermediate portal
-const scratch_vertices = new Float32Array((2 + (MAX_PORTAL_COUNT - 2) * 2) * 3);
-
-// snapped (on-mesh) start/goal positions, reused across queries
-const scratch_start_point = new Float32Array(3);
-const scratch_goal_point = new Float32Array(3);
-
-export class NavigationMesh {
-
-    topology = new BinaryTopology();
-
-    /**
-     * Used for raycasts and neighborhood search.
-     * @type {BVH}
-     */
-    bvh = new BVH();
-
-    /**
-     * Build from given scene geometry
-     * @param {BinaryTopology} source
-     * @param {number} [agent_radius]
-     * @param {number} [agent_height]
-     * @param {number} [agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
-     * @param {number} [agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
-     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
-     * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
-     */
-    build({
-              source,
-              agent_radius = 0,
-              agent_height = 0,
-              agent_max_step_height = 0,
-              agent_max_step_distance = 0,
-              agent_max_climb_angle = Math.PI / 4,
-              up = Vector3.up,
-          }) {
-
-        navmesh_build_topology({
-            destination: this.topology,
-            source,
-            agent_radius,
-            agent_height,
-            agent_max_step_height,
-            agent_max_step_distance,
-            agent_max_climb_angle,
-            up,
-        });
-
-        bvh_build_from_bt_mesh(this.bvh, this.topology);
-    }
-
-
-    /**
-     * Compute a walkable path between the two points.
-     * The result is a sequence of 3d points written into `output`. The first and last points are the
-     * start and goal snapped onto the mesh surface (the closest walkable point to each query position),
-     * so they may differ from the raw `start_*`/`goal_*` inputs when those lie off the mesh.
-     *
-     * @param {Float32Array} output packed XYZ triples
-     * @param {number} start_x
-     * @param {number} start_y
-     * @param {number} start_z
-     * @param {number} goal_x
-     * @param {number} goal_y
-     * @param {number} goal_z
-     * @returns {number} number of 3d points written to `output` (0 if no path was found)
-     */
-    find_path(
-        output,
-        start_x, start_y, start_z,
-        goal_x, goal_y, goal_z
-    ) {
-
-        const mesh = this.topology;
-        const bvh = this.bvh;
-
-        const start_face_id = bvh_query_nearest_face(bvh, mesh, start_x, start_y, start_z, scratch_start_point);
-
-        if (start_face_id === NULL_POINTER) {
-            // probably topology is empty
-            return 0;
-        }
-
-        const goal_face_id = bvh_query_nearest_face(bvh, mesh, goal_x, goal_y, goal_z, scratch_goal_point);
-
-        if (goal_face_id === NULL_POINTER) {
-            // should never happen if we got the start face
-            return 0;
-        }
-
-        // snap the query points onto the mesh surface; the path begins/ends on the walkable surface,
-        // not at the (possibly off-mesh) raw query coordinates
-        const snapped_start_x = scratch_start_point[0];
-        const snapped_start_y = scratch_start_point[1];
-        const snapped_start_z = scratch_start_point[2];
-
-        const snapped_goal_x = scratch_goal_point[0];
-        const snapped_goal_y = scratch_goal_point[1];
-        const snapped_goal_z = scratch_goal_point[2];
-
-        if (goal_face_id === start_face_id) {
-            // path within the same triangle
-
-            output[0] = snapped_start_x;
-            output[1] = snapped_start_y;
-            output[2] = snapped_start_z;
-
-            output[3] = snapped_goal_x;
-            output[4] = snapped_goal_y;
-            output[5] = snapped_goal_z;
-
-            return 2;
-        }
-
-        const face_path_length = bt_mesh_face_find_path(scratch_array_u32, start_face_id, goal_face_id, mesh, MAX_FACE_PATH_LENGTH);
-
-        if (face_path_length === 0) {
-            // no face path exists (disconnected topology)
-            return 0;
-        }
-
-        // build portals
-        // ==================
-
-        // initialize vertex data pool, vertex index 0 = start, vertex index 1 = goal (snapped on-mesh)
-        scratch_vertices[0] = snapped_start_x;
-        scratch_vertices[1] = snapped_start_y;
-        scratch_vertices[2] = snapped_start_z;
-
-        scratch_vertices[3] = snapped_goal_x;
-        scratch_vertices[4] = snapped_goal_y;
-        scratch_vertices[5] = snapped_goal_z;
-
-        let next_vertex_index = 2;
-
-        // start portal, degenerate portal at the start point, exiting the start face
-        scratch_portal_vertices[0] = 0;
-        scratch_portal_vertices[1] = 0;
-
-        mesh.face_read_normal(scratch_portal_normals, 0, start_face_id);
-
-        let portal_index = 1;
-
-        // intermediate portals sit on the shared edge between two consecutive faces along the path;
-        // the edge is read in the winding order of the face we are exiting, giving a directed (left, right) pair
-        for (let i = 1; i < face_path_length; i++) {
-
-            const face_from = scratch_array_u32[i - 1];
-            const face_to = scratch_array_u32[i];
-
-            const loop = bt_faces_shared_loop(mesh, face_from, face_to);
-
-            const left_vertex = mesh.loop_read_vertex(loop);
-            const right_vertex = mesh.loop_read_vertex(mesh.loop_read_next(loop));
-
-            const left_index = next_vertex_index++;
-            const right_index = next_vertex_index++;
-
-            mesh.vertex_read_coordinate(scratch_vertices, left_index * 3, left_vertex);
-            mesh.vertex_read_coordinate(scratch_vertices, right_index * 3, right_vertex);
-
-            const portal_address = portal_index * 2;
-            scratch_portal_vertices[portal_address] = left_index;
-            scratch_portal_vertices[portal_address + 1] = right_index;
-
-            mesh.face_read_normal(scratch_portal_normals, portal_index * 3, face_from);
-
-            portal_index++;
-        }
-
-        // goal portal, degenerate at the goal point, uses the normal of the face containing the goal
-        const goal_portal_address = portal_index * 2;
-
-        scratch_portal_vertices[goal_portal_address] = 1;
-        scratch_portal_vertices[goal_portal_address + 1] = 1;
-
-        mesh.face_read_normal(scratch_portal_normals, portal_index * 3, goal_face_id);
-
-        portal_index++;
-
-        // execute string pulling
-        const path_vertex_count = funnel_string_pull(
-            scratch_array_u32,
-            0,
-            scratch_portal_vertices,
-            scratch_portal_normals,
-            portal_index,
-            scratch_vertices,
-        );
-
-        // build the final path
-        for (let i = 0; i < path_vertex_count; i++) {
-            const vertex_index = scratch_array_u32[i];
-
-            output[i * 3] = scratch_vertices[vertex_index * 3];
-            output[i * 3 + 1] = scratch_vertices[vertex_index * 3 + 1];
-            output[i * 3 + 2] = scratch_vertices[vertex_index * 3 + 2];
-
-        }
-
-        return path_vertex_count;
-
-    }
-
-}
+import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
+import { BinaryTopology, NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { navmesh_build_topology } from "./build/navmesh_build_topology.js";
+import { bt_mesh_face_find_path_polyanya } from "./bt_mesh_face_find_path_polyanya.js";
+import { bvh_build_from_bt_mesh } from "./bvh_build_from_bt_mesh.js";
+import { bvh_query_nearest_face } from "./bvh_query_nearest_face.js";
+
+// snapped (on-mesh) start/goal positions, reused across queries
+const scratch_start_point = new Float32Array(3);
+const scratch_goal_point = new Float32Array(3);
+
+const scratch_v0 = new Float32Array(3);
+const scratch_v1 = new Float32Array(3);
+const scratch_v2 = new Float32Array(3);
+
+// Fraction of the way toward the face centroid to pull a query point. The Polyanya cone search
+// degenerates when a root (the start) or the goal lies exactly on a triangle edge -- and snapped,
+// grid-aligned queries frequently do. Nudging the point strictly into the face interior conditions the
+// search; 1e-3 is far enough off any edge for the search tolerances yet visually still "the same point".
+const FACE_INTERIOR_PULL = 1e-3;
+
+/** Move `point` a small fraction toward the centroid of `face`, so it sits strictly inside the triangle. */
+function nudge_into_face(mesh, face, point) {
+    const l0 = mesh.face_read_loop(face);
+    const l1 = mesh.loop_read_next(l0);
+    const l2 = mesh.loop_read_next(l1);
+
+    mesh.vertex_read_coordinate(scratch_v0, 0, mesh.loop_read_vertex(l0));
+    mesh.vertex_read_coordinate(scratch_v1, 0, mesh.loop_read_vertex(l1));
+    mesh.vertex_read_coordinate(scratch_v2, 0, mesh.loop_read_vertex(l2));
+
+    const cx = (scratch_v0[0] + scratch_v1[0] + scratch_v2[0]) / 3;
+    const cy = (scratch_v0[1] + scratch_v1[1] + scratch_v2[1]) / 3;
+    const cz = (scratch_v0[2] + scratch_v1[2] + scratch_v2[2]) / 3;
+
+    point[0] += (cx - point[0]) * FACE_INTERIOR_PULL;
+    point[1] += (cy - point[1]) * FACE_INTERIOR_PULL;
+    point[2] += (cz - point[2]) * FACE_INTERIOR_PULL;
+}
+
+export class NavigationMesh {
+
+    topology = new BinaryTopology();
+
+    /**
+     * Used for raycasts and neighborhood search.
+     * @type {BVH}
+     */
+    bvh = new BVH();
+
+    /**
+     * Build from given scene geometry
+     * @param {BinaryTopology} source
+     * @param {number} [agent_radius]
+     * @param {number} [agent_height]
+     * @param {number} [agent_max_step_height] agent can bridge vertical gaps in topology, such as stepping up a stair
+     * @param {number} [agent_max_step_distance] agent can bridge lateral gaps in topology, such as stepping over a hole in the floor
+     * @param {number} [agent_max_climb_angle] In radians, how steep of an angle can the agent go up by
+     * @param {Vector3} [up] Defines world's "UP" direction, this is what the agent will respect for climbing constraint
+     */
+    build({
+              source,
+              agent_radius = 0,
+              agent_height = 0,
+              agent_max_step_height = 0,
+              agent_max_step_distance = 0,
+              agent_max_climb_angle = Math.PI / 4,
+              up = Vector3.up,
+          }) {
+
+        navmesh_build_topology({
+            destination: this.topology,
+            source,
+            agent_radius,
+            agent_height,
+            agent_max_step_height,
+            agent_max_step_distance,
+            agent_max_climb_angle,
+            up,
+        });
+
+        bvh_build_from_bt_mesh(this.bvh, this.topology);
+    }
+
+
+    /**
+     * Compute a walkable path between the two points.
+     * The result is a sequence of 3d points written into `output`. The first and last points are the
+     * start and goal snapped onto the mesh surface (the closest walkable point to each query position),
+     * so they may differ from the raw `start_*`/`goal_*` inputs when those lie off the mesh.
+     *
+     * The path itself is the exact any-angle geodesic on the navmesh surface (Polyanya). It turns at
+     * obstacle corners and is subdivided wherever it crosses a face boundary, so every segment lies on a
+     * single triangle — it follows the surface exactly rather than flying over creases or tunnelling
+     * through folds. It is intrinsic to the surface — no global "up" is assumed — so it is correct on
+     * sloped and folded navmeshes as well as flat ones.
+     *
+     * @param {Float32Array} output packed XYZ triples
+     * @param {number} start_x
+     * @param {number} start_y
+     * @param {number} start_z
+     * @param {number} goal_x
+     * @param {number} goal_y
+     * @param {number} goal_z
+     * @returns {number} number of 3d points written to `output` (0 if no path was found)
+     */
+    find_path(
+        output,
+        start_x, start_y, start_z,
+        goal_x, goal_y, goal_z
+    ) {
+
+        const mesh = this.topology;
+        const bvh = this.bvh;
+
+        const start_face_id = bvh_query_nearest_face(bvh, mesh, start_x, start_y, start_z, scratch_start_point);
+
+        if (start_face_id === NULL_POINTER) {
+            // probably topology is empty
+            return 0;
+        }
+
+        const goal_face_id = bvh_query_nearest_face(bvh, mesh, goal_x, goal_y, goal_z, scratch_goal_point);
+
+        if (goal_face_id === NULL_POINTER) {
+            // should never happen if we got the start face
+            return 0;
+        }
+
+        // pull the snapped endpoints strictly inside their faces (see nudge_into_face)
+        nudge_into_face(mesh, start_face_id, scratch_start_point);
+        nudge_into_face(mesh, goal_face_id, scratch_goal_point);
+
+        // exact any-angle path between the query points snapped onto the walkable surface; returns 0 when
+        // the start and goal faces are in different connected components
+        return bt_mesh_face_find_path_polyanya(
+            output, mesh,
+            scratch_start_point[0], scratch_start_point[1], scratch_start_point[2], start_face_id,
+            scratch_goal_point[0], scratch_goal_point[1], scratch_goal_point[2], goal_face_id,
+        );
+
+    }
+
+}

package/src/engine/navigation/mesh/PATHFINDING_PLAN.md

@@ -0,0 +1,229 @@
+# Navmesh shortest-path: goal-directed, early-terminating, edge-based Eikonal A*
+
+## Where we are
+
+`bt_mesh_face_find_path` returns the face **corridor** that
+`NavigationMesh.find_path` feeds to `funnel_string_pull`. The funnel produces the exact
+shortest path *inside* the corridor, so the corridor must **contain the true geodesic** or the final
+path is permanently too long.
+
+The original implementation ran A* on the face dual graph using **centroid-to-centroid distance**.
+That metric is shape-sensitive: across thin/sliver triangles the centroid path zig-zags so hard that a
+dense patch looks more expensive than detouring around large skirt triangles, so it routed *around*
+finely-tessellated regions (measured 1.2–1.55× the straight line). `bt_mesh_face_find_path.shortest_path.spec.js`
+locks this down (flat convex mesh ⇒ straight line is the true shortest path; every pair must be within
+1% of it).
+
+The current implementation fixes correctness with an **exact geodesic field**:
+
+1. `collect_island` — BFS the whole connected component from the start (reachability + vertex set).
+2. `bt_mesh_build_boundary_distance_field` — Fast Marching (Eikonal, Kimmel–Sethian) over **every**
+   island vertex, seeded at the goal face ⇒ true along-surface distance-to-goal at each vertex.
+3. `trace_corridor` — descend the field's in-plane gradient from the start (hugs the geodesic), with a
+   `search_corridor` best-first fallback for the cases the gradient can't follow cleanly (winding
+   around a hole).
+
+This is correct (all 92 navigation tests pass) but **per query it touches the entire connected
+component**: O(component) flood-fill + O(component · log) full Eikonal solve, regardless of how close
+start and goal are. On a large navmesh that is a real regression versus the old localized A*. The
+benchmark (`bt_mesh_face_find_path.bench.spec.js`, behind `.skip`) measures exactly this.
+
+## Target design
+
+A single **goal-directed, early-terminating** Eikonal search, with the corridor reconstructed from
+**edge/portal** parents rather than the fragile gradient trace.
+
+### Phase 1 — goal-directed, early-terminating fill (the big perf win, low risk)
+
+Replace `collect_island` + full `bt_mesh_build_boundary_distance_field` with one Fast Marching pass
+that is ordered as **A*** and stops as soon as it has resolved the start:
+
+- Seed the Eikonal wavefront at the **goal** face's three vertices (distance 0).
+- Order the heap by `f = g + h`, where `g` is the tentative geodesic distance-to-goal and
+  `h(v) = ‖v − start_centroid‖` (straight-line distance to the start). Euclidean `h` is **admissible
+  and consistent** for geodesic distance (geodesic ≥ Euclidean, and Euclidean obeys the triangle
+  inequality), so a popped vertex has its **final** `g` — exactly what the Eikonal update needs from
+  its inputs. The heuristic only changes *pop order*, pulling the front toward the start so we explore
+  the start↔goal "ellipse" instead of the whole component.
+- **Early termination:** stop once all three vertices of the **start** face have been popped (frozen).
+  Every vertex on the geodesic corridor has `g ≤ g(start)` and `f ≤ g(start)` (consistent `h` ⇒ on an
+  optimal path `f` is constant `= total`), so when the start is frozen the whole corridor is already
+  frozen. Reachability falls out for free: if the heap drains without freezing the start face, there is
+  no path ⇒ return 0 (drops the separate `collect_island` BFS entirely).
+
+Keep `trace_corridor` + `search_corridor` unchanged. Both only ever move *downhill* (toward smaller
+distance-to-goal), and the downhill region is exactly what the early-terminated fill computed, so they
+operate entirely within the resolved ellipse — including the around-a-hole geodesic, whose faces all
+satisfy `g ≤ g(start)` and are therefore frozen.
+
+**Causality / correctness note to honour:** the popped-is-final guarantee holds only if Eikonal
+updates use **frozen** inputs. Pure-`g` (and consistent `g + h`) ordering already makes
+*popped ⇒ final* because every update produces a value `≥` the popping vertex's `g` and the heap pops
+non-decreasing. The Dijkstra edge-relaxation fallback (for not-yet-fronted / obtuse cases) only ever
+supplies an upper bound that a later Eikonal update lowers *before* the vertex is popped, so it does
+not violate finality. This must be verified, not assumed, when the fill is split out from
+`bt_mesh_build_boundary_distance_field` (whose label-correcting full solve never relied on early-stop
+finality).
+
+### Phase 2 — exact any-angle (Polyanya), standalone
+
+The original sketch here was "swap the corridor extractor for a portal-based search." That was tried
+(descend the lowest-field portal, re-enter at its midpoint) and **did not move the ~2% around-obstacle
+gap** — see `_diag` runs: the corridor `touchesCornerL=true touchesCornerR=false`, i.e. it cuts one
+reflex corner on the descending side. The root cause is structural: the corner-*cutting* corridor is
+shorter by *every* corridor metric (centroid, portal-midpoint, field); only the funnel knows the
+corner-*touching* corridor yields a shorter final path. So no corridor-extraction swap can be exact —
+you must run the funnel *inside* the search.
+
+That is **Polyanya** (Cui/Harabor/Grastien, IJCAI 2017): A* over (root, interval-on-edge) search nodes.
+The cone from `root` through an interval is projected into the next triangle and clipped against its
+two far edges; visible pieces keep `root` (observable), pieces hidden behind a **reflex corner** at an
+interval endpoint turn there (the corner becomes the new root, non-observable). It returns the exact
+point path, turning only at obstacle corners — no corridor, no funnel post-pass.
+
+Built as a **standalone 2-D module** `bt_mesh_face_find_path_polyanya` (xy-plane; not yet wired into the
+3-D `NavigationMesh`). Two things were essential to get it correct *and* terminating:
+- **Reflex-corner restriction:** only boundary vertices whose incident-triangle angles sum to > 180°
+  are turning roots. Admitting flat/convex boundary vertices makes the search blow up combinatorially.
+- **Per-(edge, root) interval dedup:** 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. Without
+  this the wavefront re-floods every edge at the same `f` (the straight-line heuristic ignores
+  obstacles) and never terminates.
+
+## Sequencing
+
+1. **[done]** Land this plan + the benchmark (behind `.skip`) + the geodesic implementation. Baseline
+   (full-island `bt_mesh_build_boundary_distance_field`, ~100k-face mesh): **mean 2714 ms/search**,
+   ~0.4 searches/s. A large part of that was `insert_or_update`'s **O(n) linear-scan decrease-key**,
+   making the fill O(V²).
+2. **[done]** Phase 1. Self-contained goal-directed fill with **lazy-deletion** heap (kills the O(V²))
+   and early termination, replacing `collect_island` + the full solve. Same mesh: **mean 42.5 ms/search**
+   (p50 36, p99 126, min 0.17 for local queries), ~24 searches/s — **~64× faster**. `shortest_path.spec`
+   and all 92 navigation tests stay green; the gradient trace + graph-walk fallback are kept, with a
+   full-field re-solve as the backstop for under-resolved hole-winding corridors.
+3. **[done]** Phase 2. Standalone exact `bt_mesh_face_find_path_polyanya` (2-D). Validated by
+   `bt_mesh_face_find_path_polyanya.spec.js`: exact on analytic oracles (straight line, single hole,
+   U-barrier, asymmetric wall — all corner-hugging to 4 decimals) and, over 60 random pairs on a holed
+   mesh, never longer than the FMM+funnel path and never shorter than the straight line (strictly
+   shorter on detours). Benchmark on the same ~100k-face mesh: **mean 7.1 ms/search** (p50 3.3, p90 5.5,
+   p99 9.5), ~141 searches/s — faster *typical* than Phase 1 because most pairs have line-of-sight (avg
+   2.0 path points) and Polyanya short-circuits, where the FMM fills the whole ellipse regardless.
+   **Caveat:** a heavy tail (originally max ~6.2 s) on rare far pairs that force long, corner-rich
+   detours.
+
+   **Optimisation pass (done):** made the hot path allocation-light — `reserve` rewritten to flat,
+   in-place range arrays writing into a scratch buffer (no per-call uncovered/merged/`[lo,hi]` arrays,
+   no sort), and the string dedup key replaced by nested numeric-keyed Maps (the crossed edge is
+   uniquely `(from_face, neighbour)`). Same ~100k-face mesh: **mean 4.7 ms** (p50 2.0, p99 6.8), tail
+   **6.2 s → 3.35 s** (~33% faster mean, ~46% lower tail); `spec` stays green. The residual tail is now
+   dominated by node *count* (the Euclidean heuristic is weak on long forced detours), not per-node
+   cost.
+
+   **GC-free node storage (done):** search nodes moved out of per-node object literals into fixed
+   16-word records in a flat `ArrayBuffer` (uint32 + float32 views overlaid), referenced by integer id,
+   with the open list a `Uint32Heap4` (id + f32 score) instead of an object heap. Allocation is a
+   monotonic bump counter reset per query; nodes are never released mid-search, so there is no free list
+   and no occupancy bookkeeping — the buffer only ever grows (by doubling, copying the records over) and
+   the two cached views are re-read after a grow. This is a deliberate **latency**, not throughput, choice: it is a touch slower
+   on mean throughput (**~4.7 → ~6.0 ms**, p99 6.8 → 18.3 on the bench — object literals are cheap and
+   the typical query is tiny, avg ~2 points, so there was little GC to remove and the typed-array
+   bookkeeping costs more than it saves *in aggregate*), but pathfinding is a hot path and the point is
+   to emit **zero garbage** so it never triggers a GC pause that jitters the rest of the engine's frame.
+   Unpredictable pauses are worse than a predictable constant cost here. (Storage was first prototyped on
+   `BinaryElementPool`, but the never-free, bump-allocated access pattern reads none of its allocator —
+   no `allocate()`/`release()`/`is_allocated()`/`clear()` — so it was reduced to the raw `ArrayBuffer` it
+   degenerates to; the `allocate()`/`clear()` pool variants measured slower still.)
+
+   **3-D / intrinsic (done):** `bt_mesh_face_find_path_polyanya` takes 3-D start/goal and writes a 3-D point
+   path. It assumes **no global "up"** — the search follows the surface by UNFOLDING. Each node carries the
+   2-D positions of its entry edge in a frame accumulated along its own corridor; expanding flattens the
+   next triangle into that frame by placing the apex from its two 3-D edge lengths (an isometry of the
+   triangle), on the side fixed by the face winding. So frame distances are true geodesic distances and `g`
+   is **exact on a curved/folded surface**, not just a planar one. Corners are detected from the 3-D
+   incident-angle sum (also intrinsic). The goal has no fixed position across frames, so the A* heuristic is
+   the exact straight-3-D-chord shortest root→interval→goal (a lower bound on the geodesic, hence
+   admissible); a terminal's *exact* cost unfolds the goal into that node's frame (barycentric). Waypoints
+   lift back to 3-D from vertex ids — turning corners are mesh vertices (exact), start/goal are the given
+   points, a goal-edge bend is the exact point on that edge. Validated: flat oracles still exact; a
+   rigidly-rotated holed mesh reproduces the flat path R-for-R (rotation-invariance, no up passed); and a
+   developable curved strip's straight geodesic crosses every crease with **no spurious turn** (the
+   unfolding flattens several non-coplanar faces into one frame). `e1 = up × …` and any per-face/per-region
+   up decision are gone.
+
+   **Precision fix (with the 3-D work):** the rotation test surfaced a latent bug — the search's `1e-9`
+   tolerances assume exact coordinates, but vertices are stored **float32**, so once a mesh is *not*
+   axis-aligned its edge fractions carry ~`coord·2^-23` quantisation noise, far above `1e-9`. Coverage
+   intervals then fail to merge, the same edge stretches re-cover as slivers, and the wavefront floods
+   without converging. Fix: a parameter-space tolerance `PEPS = 1e-4` (edge fractions, interval coverage,
+   vertex snapping) sized to float32 precision, kept separate from the tight area-sign `EPS`. Never moves a
+   waypoint (corners are exact vertex positions). The old axis-aligned integer-grid tests never exposed this
+   because integers are exact in float32; the standing rotation test now jitters the lattice off the grid (a
+   perfectly integer lattice rotated exactly onto an axis is a measure-zero collinearity degeneracy that
+   does not occur on real navmeshes).
+
+   **Cost of going intrinsic (measured):** full ~100k-face bench, intrinsic — **mean 9.1 ms/search**
+   (p50 3.9, p90 14.2, p99 40.9, max 4.47 s), 100 % found, ~110 searches/s. Versus the previous
+   single-plane-projection build on the same mesh: object-heap **4.7 ms** (p50 2.0, p99 6.8) and GC-free
+   pool **~6.0 ms** (p99 18.3). So intrinsic is ~1.5–2× slower in the mean and markedly heavier in the
+   tail (p99 6.8 → 40.9). The whole gap is the **heuristic**: the straight-3-D-chord lower bound ignores
+   on-surface curvature, so it is weaker than the old in-plane touch distance and expands more nodes. The
+   per-node work (an extra unfold + a 3-D touch) is minor by comparison. This is the price of "follow face
+   normals" with no up assumption, and it buys exactness on curved surfaces.
+
+   **Intermediate-node pruning — tried, does NOT pay off (two benches).** Implemented the Anya/Polyanya
+   pruning (collapse single-observable-successor "pass-through" nodes inline: no heap, no heuristic, no
+   alloc), exact and `spec`-green. On the open Eden-blob bench it was flat in the bulk (mean/p50/throughput
+   unchanged) with only a tail improvement (max 4.47 → 2.38 s); on a deliberately corridor-heavy mesh
+   (`bt_mesh_face_find_path_polyanya_rooms.bench.spec.js`, below) a deterministic same-queries measure was **identical**
+   (40 queries: 4261 ms baseline vs 4246 ms pruned). Root cause: the weak heuristic floods the *open
+   rooms*, where the cone fans into many successors; the narrow corridors where chaining fires are a small
+   fraction. Pruning attacks per-node overhead, but the bottleneck is the *node count* the heuristic
+   forces. Not committed.
+
+   **Rooms-and-corridors bench (`bt_mesh_face_find_path_polyanya_rooms.bench.spec.js`, `.skip`).** 25×25 square rooms,
+   each at one of 5 random heights, connected N/S/E/W by narrow ramped corridors (~99k faces, genuinely
+   non-planar). It dramatises the heuristic weakness: **mean ~2.4 s/search** (vs 9 ms on the open blob),
+   ~0.4 searches/s, because the straight-3-D-chord estimate cuts through walls and across levels, so A*
+   explores most of the mesh. This is the standing stress case for any heuristic work.
+
+   **Wired into `NavigationMesh.find_path` (done).** It replaces the face-corridor + funnel string-pull:
+   snap start/goal via the BVH, then run Polyanya. One robustness measure was needed — the snapped points
+   are pulled a hair (1e-3) toward their face centroid, because the cone search degenerates when a root or
+   the goal lies exactly on a triangle edge, which snapped grid-aligned queries frequently do (the funnel
+   sidestepped it by orienting on face normals, not a cone). Full `navigation/mesh` suite stays green.
+
+   **Path validation + a finding (done).** Both benches keep their paths and validate them against a
+   BVH: `bvh_segment_penetrates_mesh` flags any piece that crosses a triangle interior transversally, and
+   sampling reports how far each piece strays off the surface. The finding: a **corner-only** waypoint path
+   is correct only AT its turning corners, so the straight chord between two corners on different levels
+   flew over / cut through the ramped geometry between them (the funnel had the same property) — on the
+   multi-level rooms bench ≈4 % of pieces penetrated, maxOff up to the full height range.
+
+   **Surface-following output (done — fixes the above).** The reconstruction no longer emits bare corner
+   waypoints; it emits the point where the geodesic crosses each face-boundary edge (`line(root→next) ∩
+   edge`, lifted to 3-D by lerping the edge endpoints), plus the turning corner at each root change. Every
+   emitted segment therefore lies within a single triangle, so the path neither flies over a convex crease
+   nor tunnels through a concave fold. Two subtleties: (1) the geodesic often grazes a shared grid vertex,
+   where `line ∩ edge` reports no crossing (-1, both endpoints on one side of the line) — snapped to the nearer endpoint;
+   (2) flat stretches would otherwise gain a point at every interior edge, so **collinear runs are collapsed
+   to their endpoints** (perpendicular offset / span < `COLLINEAR_EPS = 1e-4`). The flat-mesh output is thus
+   unchanged (minimal corner polyline — the sparse-output specs still hold); subdivision only adds points
+   where the surface actually folds. **Both benches now ASSERT `penetrating === 0 && offSurface === 0`**
+   (the rooms bench flipped from report to assert), and `bt_mesh_face_find_path_polyanya.spec.js` adds
+   minimal surface oracles: two triangles folded into a convex ridge and a concave valley, and a 3-triangle
+   folded strip — each asserts the path sticks to the surface (`maxOffSurface < 1e-3`) and bends over the
+   crease rather than chording across it.
+
+   Remaining lever: a tighter still-admissible heuristic is now clearly **the** win — the rooms bench shows
+   the chord heuristic is catastrophic on walled/multi-level meshes; candidates are a cached lower-bound
+   distance-to-goal field (one FMM-style sweep per query, like `bt_mesh_face_find_path`) or an
+   obstacle-aware estimate.
+
+## Gates
+
+- **Correctness:** `bt_mesh_face_find_path.shortest_path.spec.js` (true shortest path on a flat convex
+  mesh) + the existing `bt_mesh_face_find_path.spec.js` + the `NavigationMesh` / `navmesh_*` suites
+  (holes, gaps, erosion — the fallback's job).
+- **Performance:** `bt_mesh_face_find_path.bench.spec.js` — random searches on a ~100k-face seeded
+  mesh for a fixed wall-clock budget; reports throughput and per-search timing percentiles. `.skip` by
+  default (not a quality gate); run on demand.

package/src/engine/navigation/mesh/bt_mesh_face_find_path.d.ts

@@ -2,6 +2,17 @@
  * 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

package/src/engine/navigation/mesh/bt_mesh_face_find_path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AA2GA;;;;;;;;;;;;;;;GAeG;AACH,+CAVW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,8CAEN,MAAM,GAGJ,MAAM,CAsFlB"}
+{"version":3,"file":"bt_mesh_face_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path.js"],"names":[],"mappings":"AA0oBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,+CAVW,MAAM,EAAE,GAAC,WAAW,iBACpB,MAAM,gBACN,MAAM,8CAEN,MAAM,GAGJ,MAAM,CAuDlB"}