@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,229 +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: `bt_mesh_segment_penetrates_surface` 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.
+# 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: `bt_mesh_segment_penetrates_surface` 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/build/clip_soup_against_overhangs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clip_soup_against_overhangs.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/clip_soup_against_overhangs.js"],"names":[],"mappings":"AA+PA;;;;;;;;GAQG;AACH,kDARW,MAAM,EAAE,kBACR,MAAM,wCAEN,MAAM,gBACN,MAAM,gBAEJ,MAAM,EAAE,CAkOpB"}
+{"version":3,"file":"clip_soup_against_overhangs.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/clip_soup_against_overhangs.js"],"names":[],"mappings":"AA4TA;;;;;;;;GAQG;AACH,kDARW,MAAM,EAAE,kBACR,MAAM,wCAEN,MAAM,gBACN,MAAM,gBAEJ,MAAM,EAAE,CAiRpB"}