@woosh/meep-engine 2.163.8 → 2.163.9

package/package.json

@@ -6,7 +6,7 @@
   "description": "Pure JavaScript game engine. Fully featured and production ready.",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "2.163.8",
+  "version": "2.163.9",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/geom/2d/line/line_segment_intersection_fraction_2d.d.ts

@@ -1,7 +1,9 @@
 /**
  * Fraction `t` in [0,1] along the segment (s0 -> s1) at which the infinite line through (l0, l1)
- * crosses it. Returns NaN when the segment lies entirely on one side of the line (no crossing within
- * the segment) or the two are parallel/collinear.
+ * crosses it. Returns -1 when the segment lies entirely on one side of the line (no crossing within
+ * the segment) or the two are parallel/collinear. -1 is a value the valid fraction can never take (a
+ * real crossing is always in [0,1]), and it is used instead of NaN so callers reject the no-crossing
+ * case with a trivial comparison (`t < 0` / `=== -1`) rather than the slower Number.isNaN.
  *
  * Unlike {@link line_segment_compute_line_segment_intersection_array_2d}, the first pair of points
  * defines an unbounded line (not a segment) and the result is the parametric position on the segment

package/src/core/geom/2d/line/line_segment_intersection_fraction_2d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"line_segment_intersection_fraction_2d.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/line/line_segment_intersection_fraction_2d.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,4DAVW,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,MAAM,CAsBlB"}
+{"version":3,"file":"line_segment_intersection_fraction_2d.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/line/line_segment_intersection_fraction_2d.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,4DAVW,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,QACN,MAAM,GACJ,MAAM,CAsBlB"}

package/src/core/geom/2d/line/line_segment_intersection_fraction_2d.js

@@ -2,8 +2,10 @@ import { v2_cross_product } from "../../vec2/v2_cross_product.js";
 
 /**
  * Fraction `t` in [0,1] along the segment (s0 -> s1) at which the infinite line through (l0, l1)
- * crosses it. Returns NaN when the segment lies entirely on one side of the line (no crossing within
- * the segment) or the two are parallel/collinear.
+ * crosses it. Returns -1 when the segment lies entirely on one side of the line (no crossing within
+ * the segment) or the two are parallel/collinear. -1 is a value the valid fraction can never take (a
+ * real crossing is always in [0,1]), and it is used instead of NaN so callers reject the no-crossing
+ * case with a trivial comparison (`t < 0` / `=== -1`) rather than the slower Number.isNaN.
  *
  * Unlike {@link line_segment_compute_line_segment_intersection_array_2d}, the first pair of points
  * defines an unbounded line (not a segment) and the result is the parametric position on the segment
@@ -30,12 +32,12 @@ export function line_segment_intersection_fraction_2d(
     const side_1 = v2_cross_product(dir_x, dir_y, s1_x - l0_x, s1_y - l0_y);
 
     if ((side_0 > 0 && side_1 > 0) || (side_0 < 0 && side_1 < 0)) {
-        return NaN; // both endpoints on the same side -> no crossing within the segment
+        return -1; // both endpoints on the same side -> no crossing within the segment
     }
 
     const denom = side_0 - side_1;
     if (denom === 0) {
-        return NaN; // parallel / collinear
+        return -1; // parallel / collinear
     }
 
     return side_0 / denom;

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

@@ -22,6 +22,12 @@ export class NavigationMesh {
      * 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

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

@@ -1 +1 @@
-{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAoCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;;;OASG;IACH,0HARW,cAAc,QA8BxB;IAGD;;;;;;;;;;;;;;OAcG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAyIlB;CAEJ;+BAxO4C,gEAAgE;oBADzF,gCAAgC"}
+{"version":3,"file":"NavigationMesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/NavigationMesh.js"],"names":[],"mappings":"AAyCA;IAEI,yBAAgC;IAEhC;;;OAGG;IACH,KAFU,GAAG,CAEG;IAEhB;;;;;;;;;OASG;IACH,0HARW,cAAc,QA8BxB;IAGD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBATW,YAAY,WACZ,MAAM,WACN,MAAM,WACN,MAAM,UACN,MAAM,UACN,MAAM,UACN,MAAM,GACJ,MAAM,CAqClB;CAEJ;+BA/I4C,gEAAgE;oBADzF,gCAAgC"}

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

@@ -81,7 +81,7 @@ two far edges; visible pieces keep `root` (observable), pieces hidden behind a *
 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** `navmesh_polyanya_find_path` (xy-plane; not yet wired into the
+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.
@@ -101,8 +101,8 @@ Built as a **standalone 2-D module** `navmesh_polyanya_find_path` (xy-plane; not
    (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 `navmesh_polyanya_find_path` (2-D). Validated by
-   `navmesh_polyanya_find_path.spec.js`: exact on analytic oracles (straight line, single hole,
+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,
@@ -120,20 +120,21 @@ Built as a **standalone 2-D module** `navmesh_polyanya_find_path` (xy-plane; not
    cost.
 
    **GC-free node storage (done):** search nodes moved out of per-node object literals into fixed
-   16-word records in a `BinaryElementPool` buffer, referenced by integer id, with the open list a
-   `Uint32Heap4` (id + f32 score) instead of an object heap. The buffer is driven by a monotonic
-   counter reset per query (nodes are never released mid-search and `is_allocated()` is never read), so
-   the pool's per-node occupancy bit and its O(capacity) `clear()` — itself a spike after a large query
-   — are bypassed; the buffer only ever grows (geometrically) and the cached `data_*` views are
-   re-read after a grow. This is a deliberate **latency**, not throughput, choice: it is a touch slower
+   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. (Two earlier pool variants were
-   measured — `allocate()`/`clear()` was slower still; pool-as-buffer is the kept one.)
+   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):** `navmesh_polyanya_find_path` takes 3-D start/goal and writes a 3-D point
+   **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
@@ -169,11 +170,54 @@ Built as a **standalone 2-D module** `navmesh_polyanya_find_path` (xy-plane; not
    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.
 
-   Remaining levers: a tighter still-admissible heuristic (the biggest win — e.g. a 3-D touch distance
-   that accounts for the next face's tilt, or a cached lower-bound field), the paper's advanced interval
-   pruning, and wiring `navmesh_polyanya_find_path` into `NavigationMesh.find_path` as an alternative
-   backend (it now matches that contract — 3-D points in, 3-D points out, no up-vector — and just needs
-   BVH start/goal snapping).
+   **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
 

package/src/engine/navigation/mesh/{navmesh_polyanya_find_path.d.ts → bt_mesh_face_find_path_polyanya.d.ts}

@@ -13,5 +13,5 @@
  * @param {number} goal_face triangle containing the goal point
  * @returns {number} number of path POINTS written (3 numbers each), 0 if no path
  */
-export function navmesh_polyanya_find_path(output: number[] | Float64Array | Float32Array, topology: BinaryTopology, sx: number, sy: number, sz: number, start_face: number, gx: number, gy: number, gz: number, goal_face: number): number;
-//# sourceMappingURL=navmesh_polyanya_find_path.d.ts.map
+export function bt_mesh_face_find_path_polyanya(output: number[] | Float64Array | Float32Array, topology: BinaryTopology, sx: number, sy: number, sz: number, start_face: number, gx: number, gy: number, gz: number, goal_face: number): number;
+//# sourceMappingURL=bt_mesh_face_find_path_polyanya.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_face_find_path_polyanya.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bt_mesh_face_find_path_polyanya.js"],"names":[],"mappings":"AA2TA;;;;;;;;;;;;;;GAcG;AACH,wDAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gCAElC,MAAM,MACN,MAAM,MACN,MAAM,cACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,aACN,MAAM,GACJ,MAAM,CA+HlB"}

package/src/engine/navigation/mesh/{navmesh_polyanya_find_path.js → bt_mesh_face_find_path_polyanya.js}

@@ -1,7 +1,6 @@
 import { Uint32Heap4 } from "../../../core/collection/heap/Uint32Heap4.js";
 import { line_segment_intersection_fraction_2d } from "../../../core/geom/2d/line/line_segment_intersection_fraction_2d.js";
 import { triangle2d_compute_area } from "../../../core/geom/2d/triangle2d_compute_area.js";
-import { BinaryElementPool } from "../../../core/geom/3d/topology/struct/binary/BinaryElementPool.js";
 import { NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import { v2_distance } from "../../../core/geom/vec2/v2_distance.js";
 
@@ -28,13 +27,18 @@ import { v2_distance } from "../../../core/geom/vec2/v2_distance.js";
  * shortest root->interval->goal measured with straight 3D chords (a lower bound on the geodesic, hence
  * admissible); the terminal node's *exact* cost unfolds the goal into the node's frame instead.
  *
- * The output path is lifted back to 3D from vertex ids: turning corners are mesh vertices (exact
- * positions), the start/goal are the given 3D points, and a goal-edge bend is the exact point on that
- * edge. Standalone -- does not (yet) replace the bt_mesh_face_find_path + funnel pipeline in NavigationMesh.
+ * The output path FOLLOWS THE SURFACE: it is subdivided at every face-boundary edge the geodesic
+ * crosses, so each emitted segment lies within a single triangle -- it never flies over a convex crease
+ * nor tunnels through a concave fold. Turning corners are mesh vertices (exact positions); each edge
+ * crossing is the exact line-vs-edge intersection lifted to 3D by lerping the edge's two endpoints; the
+ * start/goal are the given 3D points. Collinear runs (a flat stretch with no real bend) are collapsed to
+ * their endpoints, so on a planar mesh the output is just the minimal corner polyline -- the subdivision
+ * only adds points where the surface actually folds. Wired into NavigationMesh.find_path.
  */
 
 const EPS = 1e-9;            // area-sign slack (cone inside/outside tests)
 const DEDUP_EPS = 1e-7;      // merge consecutive output points equal to within f32 reconstruction error
+const COLLINEAR_EPS = 1e-4;  // drop a path point whose perpendicular offset from its neighbours / span is below this
 
 // Parameter-space tolerance for edge fractions, interval coverage and vertex snapping. Vertices are
 // stored as float32, so a point that is geometrically on an edge endpoint or already-covered carries
@@ -66,7 +70,7 @@ function touch_distance(rx, ry, i0x, i0y, i1x, i1y, gx, gy) {
         tx = _reflect[0]; ty = _reflect[1];
     }
     const t = line_segment_intersection_fraction_2d(rx, ry, tx, ty, i0x, i0y, i1x, i1y);
-    if (!Number.isNaN(t) && t >= -PEPS && t <= 1 + PEPS) {
+    if (t >= -PEPS && t <= 1 + PEPS) { // -1 (no crossing) falls below -PEPS, so the range test rejects it
         return v2_distance(rx, ry, tx, ty);
     }
     return Math.min(
@@ -248,19 +252,20 @@ function is_corner(topology, vid) {
 
 // ---- node storage ----------------------------------------------------------------------------------
 
-// Search nodes live as fixed 16-word records in a BinaryElementPool's buffer, referenced by integer id,
+// Search nodes are fixed 16-word records packed into one flat ArrayBuffer, addressed by id*NODE_WORDS,
 // so the open list is a Uint32Heap4 (id + score) rather than an object heap -- NO per-node object
 // allocation, so the hot path produces no garbage and never triggers a GC pause (which would otherwise
-// jitter the rest of the engine). We drive the buffer with our own monotonic counter rather than the
-// pool's allocate()/clear(): nodes are never released mid-query and is_allocated() is never read, so the
-// pool's per-node occupancy bit and O(capacity) clear() would be pure overhead. The buffer reallocates
-// on grow, so the cached data_* views (and the node being expanded) are refreshed accordingly.
+// jitter the rest of the engine). Allocation is a monotonic bump counter reset per query; nodes are
+// never released mid-query, so there is no free list and no occupancy bookkeeping. The buffer only ever
+// grows (by doubling, copying the existing records over) and the two typed-array views are re-cached
+// after a grow. (A pooled allocator with a free list + occupancy bitset degenerates to exactly this
+// under a never-free, bump-allocated access pattern, so a raw buffer is the honest, lighter shape.)
 //
 // A node stores its entry edge as vertex ids (E0V,E1V) AND its 2D positions in the node's unfolded frame
 // (E0X,E0Y,E1X,E1Y), the root (ROOTVID + RX,RY in the frame; ROOTVID==NULL_ID is the start point), and
 // the interval as the fractions [T0,T1] along the edge. 3D is recovered at reconstruction from vertex
 // ids; a terminal node stores the goal edge (E0V,E1V) and the final bend's fraction along it (N_FCT,
-// NaN == a straight shot).
+// -1 == a straight shot, since a real bend fraction is in [0,1]).
 const N_FACE = 0, N_E0V = 1, N_E1V = 2;
 const N_E0X = 3, N_E0Y = 4, N_E1X = 5, N_E1Y = 6;
 const N_ROOTVID = 7, N_RX = 8, N_RY = 9;
@@ -269,22 +274,23 @@ const N_G = 12, N_PARENT = 13, N_TERMINAL = 14, N_FCT = 15;
 const NODE_WORDS = 16;
 const NULL_ID = 0xFFFFFFFF;
 
-const _node_pool = new BinaryElementPool(NODE_WORDS * 4, 1024);
 const _open = new Uint32Heap4();
 
+// node records: uint32 and float32 views overlaid on one ArrayBuffer (_node_df aliases _node_du's bytes)
+let _node_capacity = 1024;                            // capacity in nodes; grows by doubling
+let _node_du = new Uint32Array(_node_capacity * NODE_WORDS);
+let _node_df = new Float32Array(_node_du.buffer);
 let _node_count = 0;
-let _node_capacity = _node_pool.capacity;
-let _node_du = _node_pool.data_uint32;
-let _node_df = _node_pool.data_float32;
 
 /** Reserve the next node slot, growing (and re-caching the views) only when the buffer is full. */
 function alloc_node() {
     const id = _node_count++;
     if (id >= _node_capacity) {
-        _node_pool.ensure_capacity(id + 1);
-        _node_capacity = _node_pool.capacity;
-        _node_du = _node_pool.data_uint32;
-        _node_df = _node_pool.data_float32;
+        _node_capacity *= 2;
+        const grown = new Uint32Array(_node_capacity * NODE_WORDS);
+        grown.set(_node_du); // copy the existing records into the larger buffer
+        _node_du = grown;
+        _node_df = new Float32Array(grown.buffer);
     }
     return id;
 }
@@ -298,8 +304,8 @@ let _goal_v0 = 0, _goal_v1 = 0, _goal_v2 = 0;
 let _goal_w0 = 0, _goal_w1 = 0, _goal_w2 = 0;
 const _bw = new Float64Array(3);
 
-// root vertex ids gathered along the parent chain during reconstruction (reused, never shrinks)
-const _recon_roots = [];
+// edge-crossing points (flat x,y,z triples) gathered along the parent chain during reconstruction
+const _recon = [];
 
 function goal_weight(vid) {
     return vid === _goal_v0 ? _goal_w0 : (vid === _goal_v1 ? _goal_w1 : _goal_w2);
@@ -322,7 +328,7 @@ function goal_weight(vid) {
  * @param {number} goal_face triangle containing the goal point
  * @returns {number} number of path POINTS written (3 numbers each), 0 if no path
  */
-export function navmesh_polyanya_find_path(output, topology, sx, sy, sz, start_face, gx, gy, gz, goal_face) {
+export function bt_mesh_face_find_path_polyanya(output, topology, sx, sy, sz, start_face, gx, gy, gz, goal_face) {
     _sx = sx; _sy = sy; _sz = sz;
     _gx = gx; _gy = gy; _gz = gz;
 
@@ -373,41 +379,101 @@ export function navmesh_polyanya_find_path(output, topology, sx, sy, sz, start_f
 
     if (best === NULL_ID) return 0;
 
-    // reconstruct in 3D: distinct roots (start .. last turning corner), final goal-edge bend, goal
+    // Reconstruct a SURFACE-FOLLOWING path. Every node in the parent chain shares one continuous unfolded
+    // frame (each node's frame extends its parent's), so the whole route -- start, turning corners, goal --
+    // lays out as a single 2D polyline in that frame, and the point where the route crosses each face's
+    // entry edge is just the intersection of that polyline with the edge. Lifting each crossing back onto
+    // its 3D edge keeps every output segment inside one face (i.e. on the surface). Crossings that fall on
+    // a straight (flat) stretch collapse away in push_point, so flat meshes still yield minimal paths.
     const du = _node_du, df = _node_df;
-    _recon_roots.length = 0;
+    const bb = best * NODE_WORDS;
+
+    // the goal's position in the shared frame: unfold the goal-face apex from the terminal's entry edge
+    const t_e0v = du[bb + N_E0V], t_e1v = du[bb + N_E1V];
+    const t_e0x = df[bb + N_E0X], t_e0y = df[bb + N_E0Y], t_e1x = df[bb + N_E1X], t_e1y = df[bb + N_E1Y];
+    const g_apex = unfold_apex(topology, goal_face, t_e0v, t_e1v, t_e0x, t_e0y, t_e1x, t_e1y);
+    const goal_u = goal_weight(t_e0v) * t_e0x + goal_weight(t_e1v) * t_e1x + goal_weight(g_apex) * _apex[0];
+    const goal_v = goal_weight(t_e0v) * t_e0y + goal_weight(t_e1v) * t_e1y + goal_weight(g_apex) * _apex[1];
+    const t_fct = df[bb + N_FCT];
+
+    // walk the chain (goal end -> start), recording each entry-edge crossing in reverse path order
+    _recon.length = 0;
+    let next_u = goal_u, next_v = goal_v;     // the next waypoint toward the goal, in the shared frame
+    let prev_root = du[bb + N_ROOTVID];
+    let prev_rx = df[bb + N_RX], prev_ry = df[bb + N_RY];
+
     for (let n = best; n !== NULL_ID; n = du[n * NODE_WORDS + N_PARENT]) {
-        _recon_roots.push(du[n * NODE_WORDS + N_ROOTVID]);
-    }
+        const base = n * NODE_WORDS;
+        const rootVid = du[base + N_ROOTVID];
+        const rx = df[base + N_RX], ry = df[base + N_RY];
+
+        // a change of root means the route turned at the previous corridor's root: emit that corner
+        // (an exact mesh vertex -- the turning point) and aim subsequent crossings at it
+        if (rootVid !== prev_root) {
+            if (prev_root !== NULL_ID) {
+                topology.vertex_read_coordinate(_va, 0, prev_root);
+                _recon.push(_va[0], _va[1], _va[2]);
+            }
+            next_u = prev_rx; next_v = prev_ry;
+            prev_root = rootVid;
+        }
 
-    let count = 0;
-    for (let i = _recon_roots.length - 1; i >= 0; i--) {
-        const vid = _recon_roots[i];
-        if (vid === NULL_ID) {
-            count = push_point(output, count, _sx, _sy, _sz);
+        const e0v = du[base + N_E0V], e1v = du[base + N_E1V];
+        const e0x = df[base + N_E0X], e0y = df[base + N_E0Y], e1x = df[base + N_E1X], e1y = df[base + N_E1Y];
+
+        // fraction along the entry edge where the route root->next crosses it (the terminal's goal-edge
+        // bend is exact and pre-computed as N_FCT)
+        let u;
+        if (n === best && t_fct !== -1) {
+            u = t_fct;
         } else {
-            topology.vertex_read_coordinate(_va, 0, vid);
-            count = push_point(output, count, _va[0], _va[1], _va[2]);
+            u = line_segment_intersection_fraction_2d(rx, ry, next_u, next_v, e0x, e0y, e1x, e1y);
+            if (u === -1) {
+                // the route line grazes a shared vertex (passes through / just outside an edge endpoint,
+                // common when the geodesic runs along a row of grid vertices): snap to the nearer endpoint
+                const dx = next_u - rx, dy = next_v - ry;
+                const s0 = Math.abs(dx * (e0y - ry) - dy * (e0x - rx));
+                const s1 = Math.abs(dx * (e1y - ry) - dy * (e1x - rx));
+                u = s0 <= s1 ? 0 : 1;
+            }
         }
+
+        topology.vertex_read_coordinate(_va, 0, e0v);
+        topology.vertex_read_coordinate(_vb, 0, e1v);
+        _recon.push(_va[0] + (_vb[0] - _va[0]) * u, _va[1] + (_vb[1] - _va[1]) * u, _va[2] + (_vb[2] - _va[2]) * u);
+
+        prev_rx = rx; prev_ry = ry;
     }
 
-    const bb = best * NODE_WORDS;
-    const fct = df[bb + N_FCT];
-    if (!Number.isNaN(fct)) {
-        topology.vertex_read_coordinate(_va, 0, du[bb + N_E0V]);
-        topology.vertex_read_coordinate(_vb, 0, du[bb + N_E1V]);
-        count = push_point(output, count,
-            _va[0] + (_vb[0] - _va[0]) * fct,
-            _va[1] + (_vb[1] - _va[1]) * fct,
-            _va[2] + (_vb[2] - _va[2]) * fct);
+    // start, the crossings in path order (reverse of how they were collected), goal
+    let count = 0;
+    count = push_point(output, count, _sx, _sy, _sz);
+    for (let i = _recon.length - 3; i >= 0; i -= 3) {
+        count = push_point(output, count, _recon[i], _recon[i + 1], _recon[i + 2]);
     }
     count = push_point(output, count, _gx, _gy, _gz);
     return count / 3;
 }
 
-/** Append a 3D point unless it duplicates the previous one (within f32 reconstruction error). */
+/**
+ * Append a 3D point, collapsing collinear runs: if the previous point lies (within tolerance) on the
+ * segment between the one before it and the new point, it is redundant and gets replaced rather than
+ * kept. Flat stretches of a surface-following path thus reduce to their endpoints; genuine bends (turning
+ * corners, folds in the surface) survive.
+ */
 function push_point(output, count, x, y, z) {
-    if (count >= 3 &&
+    if (count >= 6) {
+        const ax = output[count - 6], ay = output[count - 5], az = output[count - 4];
+        const bx = output[count - 3], by = output[count - 2], bz = output[count - 1];
+        const abx = bx - ax, aby = by - ay, abz = bz - az;
+        const acx = x - ax, acy = y - ay, acz = z - az;
+        const cross_x = aby * acz - abz * acy, cross_y = abz * acx - abx * acz, cross_z = abx * acy - aby * acx;
+        const ac_len = Math.hypot(acx, acy, acz);
+        if (ac_len < DEDUP_EPS || Math.hypot(cross_x, cross_y, cross_z) <= COLLINEAR_EPS * ac_len) {
+            output[count - 3] = x; output[count - 2] = y; output[count - 1] = z;
+            return count;
+        }
+    } else if (count >= 3 &&
         Math.abs(output[count - 3] - x) <= DEDUP_EPS &&
         Math.abs(output[count - 2] - y) <= DEDUP_EPS &&
         Math.abs(output[count - 1] - z) <= DEDUP_EPS) {
@@ -459,8 +525,9 @@ function process_far_edge(topology, from_face, Pv, Px, Py, Qv, Qx, Qy, rx, ry, r
     let m = 0;
     const tR = line_segment_intersection_fraction_2d(rx, ry, i0x, i0y, Px, Py, Qx, Qy);
     const tL = line_segment_intersection_fraction_2d(rx, ry, i1x, i1y, Px, Py, Qx, Qy);
-    if (!Number.isNaN(tR) && tR > PEPS && tR < 1 - PEPS) _split[m++] = tR;
-    if (!Number.isNaN(tL) && tL > PEPS && tL < 1 - PEPS) _split[m++] = tL;
+    // -1 (no crossing) fails `> PEPS`, so the interior-fraction test rejects it without a NaN check
+    if (tR > PEPS && tR < 1 - PEPS) _split[m++] = tR;
+    if (tL > PEPS && tL < 1 - PEPS) _split[m++] = tL;
     if (m === 2 && _split[0] > _split[1]) { const t = _split[0]; _split[0] = _split[1]; _split[1] = t; }
 
     let prev = 0;
@@ -561,13 +628,13 @@ function emit_node(topology, neighbour, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid,
 
         const fcost = g + touch_distance(rx, ry, i0x, i0y, i1x, i1y, ggx, ggy);
 
-        let fct = NaN;
+        let fct = -1; // -1 = straight shot (no forced bend at an interval endpoint); a real bend is in [0,1]
         let tx = ggx, ty = ggy;
         if (triangle2d_compute_area(i0x, i0y, i1x, i1y, rx, ry) * triangle2d_compute_area(i0x, i0y, i1x, i1y, ggx, ggy) > 0) {
             reflect(ggx, ggy, i0x, i0y, i1x, i1y); tx = _reflect[0]; ty = _reflect[1];
         }
         const t = line_segment_intersection_fraction_2d(rx, ry, tx, ty, i0x, i0y, i1x, i1y);
-        if (Number.isNaN(t) || t < -PEPS || t > 1 + PEPS) {
+        if (t < -PEPS || t > 1 + PEPS) { // -1 (no crossing) is caught by `< -PEPS`
             const d0 = v2_distance(rx, ry, i0x, i0y) + v2_distance(i0x, i0y, ggx, ggy);
             const d1 = v2_distance(rx, ry, i1x, i1y) + v2_distance(i1x, i1y, ggx, ggy);
             fct = d0 <= d1 ? i0p : i1p;
@@ -579,6 +646,8 @@ function emit_node(topology, neighbour, Pv, Qv, Px, Py, Qx, Qy, rx, ry, rootVid,
         du[b + N_TERMINAL] = 1;
         du[b + N_ROOTVID] = rootVid === -1 ? NULL_ID : rootVid;
         du[b + N_E0V] = Pv; du[b + N_E1V] = Qv;
+        df[b + N_E0X] = Px; df[b + N_E0Y] = Py; df[b + N_E1X] = Qx; df[b + N_E1Y] = Qy;
+        df[b + N_RX] = rx; df[b + N_RY] = ry;
         du[b + N_PARENT] = parent;
         df[b + N_FCT] = fct;
         _open.insert(id, fcost);

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

@@ -0,0 +1,21 @@
+/**
+ * Does the segment (ax,ay,az)->(bx,by,bz) pass THROUGH the mesh surface -- cross the interior of any
+ * triangle transversally (entering one side, exiting the other) strictly between its endpoints?
+ *
+ * This is the "penetration" test for a navmesh path piece. A piece that hugs the surface (coplanar with
+ * it) or flies over / under it -- a corner-only waypoint chord on a non-planar surface -- does NOT
+ * penetrate; a piece that tunnels through a wall or floor does. Endpoints lying on the surface (every
+ * path waypoint) are not penetrations.
+ *
+ * @param {BVH} bvh built by bvh_build_from_bt_mesh over `mesh`
+ * @param {BinaryTopology} mesh triangle mesh
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @returns {boolean}
+ */
+export function bvh_segment_penetrates_mesh(bvh: BVH, mesh: BinaryTopology, ax: number, ay: number, az: number, bx: number, by: number, bz: number): boolean;
+//# sourceMappingURL=bvh_segment_penetrates_mesh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bvh_segment_penetrates_mesh.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/bvh_segment_penetrates_mesh.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,gFARW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAmDnB"}

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

@@ -0,0 +1,133 @@
+import {
+    COLUMN_CHILD_1,
+    COLUMN_CHILD_2,
+    COLUMN_USER_DATA,
+    ELEMENT_WORD_COUNT,
+    NULL_NODE
+} from "../../../core/bvh2/bvh3/BVH.js";
+import { NULL_POINTER } from "../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+
+// Plane-side slack and barycentric slack. Mesh vertices are float32, so a segment endpoint that lies ON
+// a triangle sits within ~coord*2^-23 of its plane; PLANE_EPS keeps those (and grazing/coplanar pieces)
+// from registering as a crossing. Only a genuinely transversal piece -- strictly on opposite sides of a
+// triangle's plane and crossing its interior away from its own endpoints -- counts as a penetration.
+const PLANE_EPS = 1e-3;
+const BARY_EPS = 1e-6;
+
+const _coords = new Float32Array(3);
+const _stack = new Uint32Array(1024); // DFS node stack; navmesh BVHs are shallow (depth ~ log2(faces))
+
+/** Standard slab test: does the segment p + t*d, t in [0,1], intersect the AABB [min,max]? */
+function segment_intersects_aabb(minx, miny, minz, maxx, maxy, maxz, px, py, pz, dx, dy, dz) {
+    let tmin = 0, tmax = 1;
+
+    if (dx > -1e-12 && dx < 1e-12) { if (px < minx || px > maxx) return false; }
+    else { let t1 = (minx - px) / dx, t2 = (maxx - px) / dx; if (t1 > t2) { const t = t1; t1 = t2; t2 = t; } if (t1 > tmin) tmin = t1; if (t2 < tmax) tmax = t2; if (tmin > tmax) return false; }
+
+    if (dy > -1e-12 && dy < 1e-12) { if (py < miny || py > maxy) return false; }
+    else { let t1 = (miny - py) / dy, t2 = (maxy - py) / dy; if (t1 > t2) { const t = t1; t1 = t2; t2 = t; } if (t1 > tmin) tmin = t1; if (t2 < tmax) tmax = t2; if (tmin > tmax) return false; }
+
+    if (dz > -1e-12 && dz < 1e-12) { if (pz < minz || pz > maxz) return false; }
+    else { let t1 = (minz - pz) / dz, t2 = (maxz - pz) / dz; if (t1 > t2) { const t = t1; t1 = t2; t2 = t; } if (t1 > tmin) tmin = t1; if (t2 < tmax) tmax = t2; if (tmin > tmax) return false; }
+
+    return true;
+}
+
+/** True if segment (px,py,pz)->(qx,qy,qz) crosses the interior of triangle (a,b,c) transversally. */
+function segment_crosses_triangle(px, py, pz, qx, qy, qz, ax, ay, az, bx, by, bz, cx, cy, cz) {
+    const ux = bx - ax, uy = by - ay, uz = bz - az;
+    const vx = cx - ax, vy = cy - ay, vz = cz - az;
+    const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+    const nlen = Math.hypot(nx, ny, nz);
+    if (nlen < 1e-12) return false; // degenerate triangle
+
+    const dP = ((px - ax) * nx + (py - ay) * ny + (pz - az) * nz) / nlen;
+    const dQ = ((qx - ax) * nx + (qy - ay) * ny + (qz - az) * nz) / nlen;
+
+    // must cross the plane strictly (not coplanar, not endpoint-on-plane)
+    if (!((dP > PLANE_EPS && dQ < -PLANE_EPS) || (dP < -PLANE_EPS && dQ > PLANE_EPS))) return false;
+
+    const t = dP / (dP - dQ);
+    if (t <= PLANE_EPS || t >= 1 - PLANE_EPS) return false; // crossing at/near an endpoint (on the surface)
+
+    // crossing point, tested for containment via barycentric coordinates in the triangle plane
+    const wx = px + (qx - px) * t - ax, wy = py + (qy - py) * t - ay, wz = pz + (qz - pz) * t - az;
+    const d00 = ux * ux + uy * uy + uz * uz, d01 = ux * vx + uy * vy + uz * vz, d11 = vx * vx + vy * vy + vz * vz;
+    const d20 = wx * ux + wy * uy + wz * uz, d21 = wx * vx + wy * vy + wz * vz;
+    const denom = d00 * d11 - d01 * d01;
+    if (denom > -1e-18 && denom < 1e-18) return false;
+    const s = (d11 * d20 - d01 * d21) / denom;
+    const w = (d00 * d21 - d01 * d20) / denom;
+
+    return s >= -BARY_EPS && w >= -BARY_EPS && s + w <= 1 + BARY_EPS;
+}
+
+/**
+ * Does the segment (ax,ay,az)->(bx,by,bz) pass THROUGH the mesh surface -- cross the interior of any
+ * triangle transversally (entering one side, exiting the other) strictly between its endpoints?
+ *
+ * This is the "penetration" test for a navmesh path piece. A piece that hugs the surface (coplanar with
+ * it) or flies over / under it -- a corner-only waypoint chord on a non-planar surface -- does NOT
+ * penetrate; a piece that tunnels through a wall or floor does. Endpoints lying on the surface (every
+ * path waypoint) are not penetrations.
+ *
+ * @param {BVH} bvh built by bvh_build_from_bt_mesh over `mesh`
+ * @param {BinaryTopology} mesh triangle mesh
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az
+ * @param {number} bx
+ * @param {number} by
+ * @param {number} bz
+ * @returns {boolean}
+ */
+export function bvh_segment_penetrates_mesh(bvh, mesh, ax, ay, az, bx, by, bz) {
+    const root = bvh.root;
+    if (root === NULL_NODE) return false;
+
+    const float32 = bvh.__data_float32;
+    const uint32 = bvh.__data_uint32;
+    const dx = bx - ax, dy = by - ay, dz = bz - az;
+
+    let sp = 0;
+    _stack[sp++] = root;
+
+    while (sp > 0) {
+        const node = _stack[--sp];
+        const address = node * ELEMENT_WORD_COUNT;
+
+        if (!segment_intersects_aabb(
+            float32[address], float32[address + 1], float32[address + 2],
+            float32[address + 3], float32[address + 4], float32[address + 5],
+            ax, ay, az, dx, dy, dz
+        )) {
+            continue;
+        }
+
+        const child_1 = uint32[address + COLUMN_CHILD_1];
+        if (child_1 !== NULL_NODE) {
+            _stack[sp++] = child_1;
+            _stack[sp++] = uint32[address + COLUMN_CHILD_2];
+            continue;
+        }
+
+        const face_id = uint32[address + COLUMN_USER_DATA];
+        const loop_a = mesh.face_read_loop(face_id);
+        if (loop_a === NULL_POINTER) continue;
+        const loop_b = mesh.loop_read_next(loop_a);
+        const loop_c = mesh.loop_read_next(loop_b);
+
+        mesh.vertex_read_coordinate(_coords, 0, mesh.loop_read_vertex(loop_a));
+        const tax = _coords[0], tay = _coords[1], taz = _coords[2];
+        mesh.vertex_read_coordinate(_coords, 0, mesh.loop_read_vertex(loop_b));
+        const tbx = _coords[0], tby = _coords[1], tbz = _coords[2];
+        mesh.vertex_read_coordinate(_coords, 0, mesh.loop_read_vertex(loop_c));
+        const tcx = _coords[0], tcy = _coords[1], tcz = _coords[2];
+
+        if (segment_crosses_triangle(ax, ay, az, bx, by, bz, tax, tay, taz, tbx, tby, tbz, tcx, tcy, tcz)) {
+            return true;
+        }
+    }
+
+    return false;
+}

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

@@ -1 +0,0 @@
-{"version":3,"file":"navmesh_polyanya_find_path.d.ts","sourceRoot":"","sources":["../../../../../src/engine/navigation/mesh/navmesh_polyanya_find_path.js"],"names":[],"mappings":"AAqTA;;;;;;;;;;;;;;GAcG;AACH,mDAZW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,gCAElC,MAAM,MACN,MAAM,MACN,MAAM,cACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,aACN,MAAM,GACJ,MAAM,CAmFlB"}