@woosh/meep-engine 2.163.9 → 2.163.10

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.9",
+  "version": "2.163.10",
   "main": "build/meep.module.js",
   "module": "build/meep.module.js",
   "exports": {

package/src/core/collection/heap/IndexedFloatMaxHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedFloatMaxHeap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/heap/IndexedFloatMaxHeap.js"],"names":[],"mappings":"AA6BA;IACI;;;OAGG;IACH,yBAHW,MAAM,0BACN,MAAM,EAsBhB;IAbG,wBAA4C;IAC5C,eAAe;IAEf,2BAA4E;IAC5E,2BAAwD;IACxD,6BAA0D;IAE1D;;;OAGG;IACH,cAFU,WAAW,CAE2B;IAIpD,mBAEC;IAED;;;OAGG;IACH,cAQC;IAED,2BAEC;IAED;;;OAGG;IACH,qBAkBC;IAED;;;;OAIG;IACH,oBAsBC;IAED;;;;OAIG;IACH,kBAYC;IAED,wBAUC;IAED;;;OAGG;IACH,WAHW,MAAM,SACN,MAAM,QAehB;IAED;;OAEG;IACH,WAFa,MAAM,CAuBlB;IAED;;;OAGG;IACH,WAHW,MAAM,aACN,MAAM,QAehB;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CA+BnB;CACJ"}

package/src/core/{graph/metis/native/refine → collection/heap}/IndexedFloatMaxHeap.js

@@ -1,4 +1,4 @@
-import { assert } from "../../../../assert.js";
+import { assert } from "../../assert.js";
 
 /**
  * Max-heap of (uint32 id, float32 score) entries with an external id→slot index

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_simplify.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js"],"names":[],"mappings":"AAqLA;;;;;;;;;;;;;;GAcG;AACH,0EAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QA6HrB"}
+{"version":3,"file":"bt_mesh_simplify.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;GAcG;AACH,0EAHW,MAAM,wBACN,IAAI,MAAM,CAAC,QA6HrB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify.js

@@ -7,6 +7,7 @@ import { bt_mesh_compute_vertex_quadratics } from "./bt_mesh_compute_vertex_quad
 import { bt_edge_collapse } from "./edge/bt_edge_collapse.js";
 import { bt_edge_kill } from "./edge/bt_edge_kill.js";
 import { bt_edge_kill_parallels } from "./edge/bt_edge_kill_parallels.js";
+import { bt_edge_swap_vertex_slots } from "./edge/bt_edge_swap_vertex_slots.js";
 import { bt_vert_fuse_duplicate_edges } from "./vertex/bt_vert_fuse_duplicate_edges.js";
 import { bt_vert_kill } from "./vertex/bt_vert_kill.js";
 
@@ -50,31 +51,6 @@ function count_edge_faces(mesh, edge_id) {
     return count;
 }
 
-/**
- * Swap the v1/v2 slots of an edge. Disk cycle pointers for the two slots are swapped
- * alongside so that the disk cycles on both attached vertices remain valid.
- *
- * @param {BinaryTopology} mesh
- * @param {number} edge_id
- */
-function swap_edge_vertex_slots(mesh, edge_id) {
-    const v1 = mesh.edge_read_vertex1(edge_id);
-    const v2 = mesh.edge_read_vertex2(edge_id);
-
-    const v1_next = mesh.edge_read_v1_disk_next(edge_id);
-    const v1_prev = mesh.edge_read_v1_disk_prev(edge_id);
-    const v2_next = mesh.edge_read_v2_disk_next(edge_id);
-    const v2_prev = mesh.edge_read_v2_disk_prev(edge_id);
-
-    mesh.edge_write_vertex1(edge_id, v2);
-    mesh.edge_write_vertex2(edge_id, v1);
-
-    mesh.edge_write_v1_disk_next(edge_id, v2_next);
-    mesh.edge_write_v1_disk_prev(edge_id, v2_prev);
-    mesh.edge_write_v2_disk_next(edge_id, v1_next);
-    mesh.edge_write_v2_disk_prev(edge_id, v1_prev);
-}
-
 /**
  * Evaluate a potential edge collapse: choose the optimal surviving vertex position
  * and return the quadric-based cost. Returns Infinity if the edge cannot be collapsed.
@@ -285,7 +261,7 @@ export function bt_mesh_simplify(
         // bt_edge_collapse keeps v1 as the survivor. If v2 is the pinned endpoint,
         // swap the edge's slots so the pinned vertex ends up in the v1 position.
         if (v2_restricted) {
-            swap_edge_vertex_slots(mesh, edge_id);
+            bt_edge_swap_vertex_slots(mesh, edge_id);
         }
 
         const pre_survivor = mesh.edge_read_vertex1(edge_id);

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify_by_error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Clean up a triangle mesh in place by removing only geometrically redundant vertices, so the
+ * surface and its boundary are preserved to within `max_error`. Unlike {@link bt_mesh_simplify}
+ * (quadric LoD decimation driven to a face-count target, free to relocate vertices), this is a
+ * conservative half-edge cleanup: it never moves a surviving vertex and never changes the
+ * boundary outline or hole topology by more than `max_error`. It removes the dense interior of
+ * flat/near-coplanar regions and collinear runs of boundary vertices, and stops once the
+ * cheapest remaining collapse would exceed the tolerance.
+ *
+ * Intended for navmesh post-processing, where the input is a walkable surface whose outline and
+ * holes (obstacle footprints) carry meaning and must not drift, but whose interior inherits far
+ * more triangles than navigation needs.
+ *
+ * @param {BinaryTopology} mesh Mesh to clean up in-place.
+ * @param {number} max_error Maximum world-space deviation allowed for any removed vertex and for
+ *     the boundary polyline. A no-op when <= 0.
+ */
+export function bt_mesh_simplify_by_error(mesh: BinaryTopology, max_error: number): void;
+//# sourceMappingURL=bt_mesh_simplify_by_error.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify_by_error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_mesh_simplify_by_error.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify_by_error.js"],"names":[],"mappings":"AA4aA;;;;;;;;;;;;;;;;GAgBG;AACH,2EAHW,MAAM,QAgHhB"}

package/src/core/geom/3d/topology/struct/binary/io/bt_mesh_simplify_by_error.js

@@ -0,0 +1,555 @@
+import { assert } from "../../../../../../assert.js";
+import { FibonacciHeap } from "../../../../../../collection/heap/FibonacciHeap.js";
+import {
+    line3_compute_segment_point_distance_sqr
+} from "../../../../line/line3_compute_segment_point_distance_sqr.js";
+import { NULL_POINTER } from "../BinaryTopology.js";
+import { bt_query_edge_is_boundary } from "../query/bt_query_edge_is_boundary.js";
+import { bt_mesh_cleanup_faceless_references } from "./bt_mesh_cleanup_faceless_references.js";
+import { bt_mesh_compute_vertex_quadratics } from "./bt_mesh_compute_vertex_quadratics.js";
+import { bt_edge_collapse } from "./edge/bt_edge_collapse.js";
+import { bt_edge_kill_parallels } from "./edge/bt_edge_kill_parallels.js";
+import { bt_edge_swap_vertex_slots } from "./edge/bt_edge_swap_vertex_slots.js";
+import { bt_vert_fuse_duplicate_edges } from "./vertex/bt_vert_fuse_duplicate_edges.js";
+
+// Module-level scratch to keep the hot loop allocation-free.
+const _pos_a = new Float32Array(3);
+const _pos_b = new Float32Array(3);
+const _pos_c = new Float32Array(3);
+const _pos_s = new Float32Array(3);
+const _pos_v = new Float32Array(3);
+const _pos_target = new Float32Array(3);
+const _n_before = new Float32Array(3);
+const _n_after = new Float32Array(3);
+
+// Cap on the merged valence (deg(v1) + deg(v2)) of a collapse. A flat region otherwise lets the
+// greedy order funnel every triangle into a single high-valence "star" vertex, which makes each
+// subsequent disk walk / requeue O(degree) and the whole pass O(n^2). Bounding the merged
+// neighbourhood keeps every per-vertex walk O(1), so the pass is O(n log n). It can leave a few
+// extra triangles in a large flat region versus the theoretical minimum -- a good trade for
+// navigation, where a balanced low-valence mesh also searches better than a sliver fan.
+const DEGREE_SUM_CAP = 24;
+
+// Per-vertex degree and boundary-membership caches, kept in plain typed arrays so choose_collapse
+// reads them in O(1) instead of disk-walking on every call (BinaryTopology accessors go through a
+// DataView, which is comparatively slow, and choose_collapse runs far more often than collapses do).
+// They are refreshed for the survivor and its neighbours after each collapse -- the only vertices a
+// collapse can change. Assigned per call to bt_mesh_simplify_by_error (the pass is not re-entrant).
+let _degree = null;
+let _vboundary = null;
+
+// Result of the most recent choose_collapse: the kept and removed endpoints of the best
+// (cheapest, in-tolerance) collapse direction. Only meaningful when it returned a finite cost.
+let _choice_survivor = NULL_POINTER;
+let _choice_victim = NULL_POINTER;
+
+/**
+ * Refresh `_degree[v]` and `_vboundary[v]` from the mesh in a single disk-cycle walk: the degree is
+ * the cycle length and the vertex is on a boundary when any incident edge is a boundary edge.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v
+ */
+function recompute_vertex_cache(mesh, v) {
+    let e = mesh.vertex_read_edge(v);
+
+    if (e === NULL_POINTER) {
+        _degree[v] = 0;
+        _vboundary[v] = 0;
+        return;
+    }
+
+    const start_e = e;
+    let n = 0;
+    let bnd = 0;
+
+    do {
+        n++;
+
+        if (bnd === 0 && bt_query_edge_is_boundary(mesh, e)) {
+            bnd = 1;
+        }
+
+        e = (mesh.edge_read_vertex1(e) === v)
+            ? mesh.edge_read_v1_disk_next(e)
+            : mesh.edge_read_v2_disk_next(e);
+    } while (e !== start_e && e !== NULL_POINTER);
+
+    _degree[v] = n;
+    _vboundary[v] = bnd;
+}
+
+/**
+ * For a boundary vertex `v`, return the far endpoint of its boundary edge other than
+ * `exclude_edge` -- i.e. `v`'s neighbour along the boundary polyline on the far side.
+ *
+ * Returns NULL_POINTER unless `v` has exactly one such other boundary edge (a clean
+ * 2-manifold boundary vertex). Dead-ends and pinch/junction vertices are declined so the
+ * caller conservatively skips simplifying there rather than mis-stepping the polyline.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} v
+ * @param {number} exclude_edge
+ * @returns {number}
+ */
+function other_boundary_neighbor(mesh, v, exclude_edge) {
+    let e = mesh.vertex_read_edge(v);
+
+    if (e === NULL_POINTER) {
+        return NULL_POINTER;
+    }
+
+    const start_e = e;
+
+    let found = NULL_POINTER;
+    let count = 0;
+
+    do {
+        if (e !== exclude_edge && bt_query_edge_is_boundary(mesh, e)) {
+            count++;
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+            found = (v1 === v) ? v2 : v1;
+        }
+
+        e = (mesh.edge_read_vertex1(e) === v)
+            ? mesh.edge_read_v1_disk_next(e)
+            : mesh.edge_read_v2_disk_next(e);
+    } while (e !== start_e && e !== NULL_POINTER);
+
+    if (count !== 1) {
+        return NULL_POINTER;
+    }
+
+    return found;
+}
+
+/**
+ * Unnormalised triangle normal (b-a) x (c-a) written into `out`.
+ *
+ * Deliberately NOT v3_compute_triangle_normal: the flip guard needs the raw cross product. Its
+ * magnitude vanishing signals a degenerate (zero-area) result, which the caller's `dot <= 0` test
+ * then rejects. v3_compute_triangle_normal normalises (discarding that magnitude) and returns a
+ * fixed (0,1,0) for degenerate triangles, which would let a collapse-to-sliver slip the guard.
+ */
+function triangle_cross(out, 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;
+
+    out[0] = uy * vz - uz * vy;
+    out[1] = uz * vx - ux * vz;
+    out[2] = ux * vy - uy * vx;
+}
+
+/**
+ * Quadric-error cost of relocating both endpoints' supporting planes to `(tx,ty,tz)`.
+ * For a half-edge collapse the target is the (stationary) survivor's own position, so this
+ * measures how far the removed vertex's surface would deviate -- zero on a flat region.
+ */
+function quadric_cost_at(q_survivor, q_victim, tx, ty, tz) {
+    return q_survivor.evaluate(tx, ty, tz) + q_victim.evaluate(tx, ty, tz);
+}
+
+/**
+ * Pick the best allowed collapse for edge `e` and return its quadric error. Writes the kept
+ * and removed vertices into `_choice_survivor` / `_choice_victim`. Returns POSITIVE_INFINITY
+ * when no direction is allowed.
+ *
+ * Allowability rules (cleanup, not decimation -- nothing moves, the boundary shape is kept):
+ *  - the survivor is always an existing vertex and never relocates;
+ *  - a *boundary* edge may collapse only by removing an endpoint that is collinear within
+ *    `eps` with its two boundary neighbours, so the outline polyline shifts by <= eps;
+ *  - an *interior* edge may remove only a non-boundary endpoint (the boundary endpoint, if
+ *    any, survives), and is forbidden outright when *both* endpoints are boundary vertices
+ *    (collapsing it would pinch a thin neck or weld two boundary loops -- a topology change).
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} e
+ * @param {Quadric3[]} quadratics
+ * @param {number} eps
+ * @returns {number}
+ */
+function choose_collapse(mesh, e, quadratics, eps) {
+    const v1 = mesh.edge_read_vertex1(e);
+    const v2 = mesh.edge_read_vertex2(e);
+
+    if (v1 === v2) {
+        return Number.POSITIVE_INFINITY;
+    }
+
+    if (mesh.edge_read_loop(e) === NULL_POINTER) {
+        // wire edge with no incident face -- nothing to clean up
+        return Number.POSITIVE_INFINITY;
+    }
+
+    const q1 = quadratics[v1];
+    const q2 = quadratics[v2];
+
+    if (q1 == null || q2 == null) {
+        return Number.POSITIVE_INFINITY;
+    }
+
+    // Valence cap (see DEGREE_SUM_CAP). The merged neighbourhood size is the same whichever
+    // endpoint survives, so this gates the edge regardless of collapse direction.
+    if (_degree[v1] + _degree[v2] > DEGREE_SUM_CAP) {
+        return Number.POSITIVE_INFINITY;
+    }
+
+    mesh.vertex_read_coordinate(_pos_a, 0, v1);
+    mesh.vertex_read_coordinate(_pos_b, 0, v2);
+
+    let best = Number.POSITIVE_INFINITY;
+    let best_survivor = NULL_POINTER;
+    let best_victim = NULL_POINTER;
+
+    if (bt_query_edge_is_boundary(mesh, e)) {
+        // Boundary edge: both endpoints are boundary vertices. Removing a vertex replaces the two
+        // boundary edges meeting at it with the single segment between its two boundary neighbours,
+        // so the outline shifts by the removed vertex's distance to that *segment*. Allow the
+        // removal only when that shift is within eps. Distance must be to the segment, not the
+        // infinite line: a near-collinear spike whose tip projects beyond its neighbours sits on
+        // their line yet is far from the segment between them, and cutting it would move the
+        // boundary by the whole spike length.
+        const eps_sq = eps * eps;
+
+        // remove v2, keep v1
+        const w2 = other_boundary_neighbor(mesh, v2, e);
+        if (w2 !== NULL_POINTER) {
+            mesh.vertex_read_coordinate(_pos_c, 0, w2);
+            const dev_sqr = line3_compute_segment_point_distance_sqr(
+                _pos_a[0], _pos_a[1], _pos_a[2],
+                _pos_c[0], _pos_c[1], _pos_c[2],
+                _pos_b[0], _pos_b[1], _pos_b[2]
+            );
+            if (dev_sqr <= eps_sq) {
+                const cost = quadric_cost_at(q1, q2, _pos_a[0], _pos_a[1], _pos_a[2]);
+                if (cost < best) {
+                    best = cost;
+                    best_survivor = v1;
+                    best_victim = v2;
+                }
+            }
+        }
+
+        // remove v1, keep v2
+        const w1 = other_boundary_neighbor(mesh, v1, e);
+        if (w1 !== NULL_POINTER) {
+            mesh.vertex_read_coordinate(_pos_c, 0, w1);
+            const dev_sqr = line3_compute_segment_point_distance_sqr(
+                _pos_b[0], _pos_b[1], _pos_b[2],
+                _pos_c[0], _pos_c[1], _pos_c[2],
+                _pos_a[0], _pos_a[1], _pos_a[2]
+            );
+            if (dev_sqr <= eps_sq) {
+                const cost = quadric_cost_at(q1, q2, _pos_b[0], _pos_b[1], _pos_b[2]);
+                if (cost < best) {
+                    best = cost;
+                    best_survivor = v2;
+                    best_victim = v1;
+                }
+            }
+        }
+    } else {
+        // Interior edge.
+        const b1 = _vboundary[v1] === 1;
+        const b2 = _vboundary[v2] === 1;
+
+        if (b1 && b2) {
+            // both on the boundary, edge interior -> pinching / loop-welding, forbidden
+            return Number.POSITIVE_INFINITY;
+        }
+
+        if (!b2) {
+            // remove v2, keep v1
+            const cost = quadric_cost_at(q1, q2, _pos_a[0], _pos_a[1], _pos_a[2]);
+            if (cost < best) {
+                best = cost;
+                best_survivor = v1;
+                best_victim = v2;
+            }
+        }
+
+        if (!b1) {
+            // remove v1, keep v2
+            const cost = quadric_cost_at(q1, q2, _pos_b[0], _pos_b[1], _pos_b[2]);
+            if (cost < best) {
+                best = cost;
+                best_survivor = v2;
+                best_victim = v1;
+            }
+        }
+    }
+
+    _choice_survivor = best_survivor;
+    _choice_victim = best_victim;
+
+    return best;
+}
+
+/**
+ * Would removing `victim` (folding it onto the stationary `survivor`) invert or degenerate
+ * any of the faces it reshapes? Checks every face incident to `victim` that does not also
+ * touch `survivor` (those are the collapse faces, which die) by comparing each triangle's
+ * normal before and after the substitution. A non-positive dot means a flip or a collapse to
+ * zero area -- both reject the collapse.
+ *
+ * This guards the in-plane fold that the quadric error cannot see: on a flat region every
+ * candidate scores ~0, but a non-star-shaped one-ring would still overlap if collapsed.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} victim
+ * @param {number} survivor
+ * @returns {boolean}
+ */
+function collapse_would_fold(mesh, victim, survivor) {
+    mesh.vertex_read_coordinate(_pos_s, 0, survivor);
+    mesh.vertex_read_coordinate(_pos_v, 0, victim);
+
+    const face_pool = mesh.faces;
+
+    let e = mesh.vertex_read_edge(victim);
+
+    if (e === NULL_POINTER) {
+        return false;
+    }
+
+    const start_e = e;
+
+    do {
+        const l0 = mesh.edge_read_loop(e);
+
+        if (l0 !== NULL_POINTER) {
+            let l = l0;
+
+            do {
+                // each face incident to `victim` is reached exactly once via its victim-anchored loop
+                if (mesh.loop_read_vertex(l) === victim) {
+                    const f = mesh.loop_read_face(l);
+
+                    if (f !== NULL_POINTER && face_pool.is_allocated(f)) {
+                        const lb = mesh.loop_read_next(l);
+                        const lc = mesh.loop_read_next(lb);
+
+                        // triangle faces only
+                        if (mesh.loop_read_next(lc) === l) {
+                            const vb = mesh.loop_read_vertex(lb);
+                            const vc = mesh.loop_read_vertex(lc);
+
+                            // skip the faces that die in the collapse (they touch the survivor)
+                            if (vb !== survivor && vc !== survivor) {
+                                mesh.vertex_read_coordinate(_pos_b, 0, vb);
+                                mesh.vertex_read_coordinate(_pos_c, 0, vc);
+
+                                triangle_cross(
+                                    _n_before,
+                                    _pos_v[0], _pos_v[1], _pos_v[2],
+                                    _pos_b[0], _pos_b[1], _pos_b[2],
+                                    _pos_c[0], _pos_c[1], _pos_c[2]
+                                );
+                                triangle_cross(
+                                    _n_after,
+                                    _pos_s[0], _pos_s[1], _pos_s[2],
+                                    _pos_b[0], _pos_b[1], _pos_b[2],
+                                    _pos_c[0], _pos_c[1], _pos_c[2]
+                                );
+
+                                const dot = _n_before[0] * _n_after[0]
+                                    + _n_before[1] * _n_after[1]
+                                    + _n_before[2] * _n_after[2];
+
+                                if (dot <= 0) {
+                                    return true;
+                                }
+                            }
+                        }
+                    }
+                }
+
+                l = mesh.loop_read_radial_next(l);
+            } while (l !== l0 && l !== NULL_POINTER);
+        }
+
+        e = (mesh.edge_read_vertex1(e) === victim)
+            ? mesh.edge_read_v1_disk_next(e)
+            : mesh.edge_read_v2_disk_next(e);
+    } while (e !== start_e && e !== NULL_POINTER);
+
+    return false;
+}
+
+/**
+ * Re-cost the collapses affected by a collapse that produced survivor `s`. Re-evaluates `s`'s
+ * incident edges (their endpoints' valence, quadric, and -- for the boundary ones -- the outline
+ * shape all moved) and updates the heap in place: still-collapsible edges are inserted/updated,
+ * edges that left the tolerance are removed. Edges further out keep their old heap score; this only
+ * affects pop *order*, never correctness, because every collapse is re-validated against the live
+ * mesh when it is finally popped.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} s
+ * @param {Quadric3[]} quadratics
+ * @param {number} eps
+ * @param {number} eps_sq
+ * @param {FibonacciHeap} heap
+ */
+function requeue_ring(mesh, s, quadratics, eps, eps_sq, heap) {
+    // The survivor and its neighbours are exactly the vertices whose degree/boundary status a
+    // collapse can change, so refresh their cache here (before choose_collapse reads it) rather
+    // than walking the disk inside every choose_collapse.
+    recompute_vertex_cache(mesh, s);
+
+    let e = mesh.vertex_read_edge(s);
+
+    if (e === NULL_POINTER) {
+        return;
+    }
+
+    const start_e = e;
+
+    do {
+        const v1 = mesh.edge_read_vertex1(e);
+        const w = (v1 === s) ? mesh.edge_read_vertex2(e) : v1;
+
+        recompute_vertex_cache(mesh, w);
+
+        const cost = choose_collapse(mesh, e, quadratics, eps);
+
+        if (cost <= eps_sq) {
+            heap.insert_or_update(e, cost);
+        } else {
+            heap.remove(e);
+        }
+
+        e = (v1 === s)
+            ? mesh.edge_read_v1_disk_next(e)
+            : mesh.edge_read_v2_disk_next(e);
+    } while (e !== start_e && e !== NULL_POINTER);
+}
+
+/**
+ * Clean up a triangle mesh in place by removing only geometrically redundant vertices, so the
+ * surface and its boundary are preserved to within `max_error`. Unlike {@link bt_mesh_simplify}
+ * (quadric LoD decimation driven to a face-count target, free to relocate vertices), this is a
+ * conservative half-edge cleanup: it never moves a surviving vertex and never changes the
+ * boundary outline or hole topology by more than `max_error`. It removes the dense interior of
+ * flat/near-coplanar regions and collinear runs of boundary vertices, and stops once the
+ * cheapest remaining collapse would exceed the tolerance.
+ *
+ * Intended for navmesh post-processing, where the input is a walkable surface whose outline and
+ * holes (obstacle footprints) carry meaning and must not drift, but whose interior inherits far
+ * more triangles than navigation needs.
+ *
+ * @param {BinaryTopology} mesh Mesh to clean up in-place.
+ * @param {number} max_error Maximum world-space deviation allowed for any removed vertex and for
+ *     the boundary polyline. A no-op when <= 0.
+ */
+export function bt_mesh_simplify_by_error(mesh, max_error) {
+    assert.defined(mesh, 'mesh');
+    assert.notNull(mesh, 'mesh');
+    assert.equal(mesh.isBinaryTopology, true, 'mesh.isBinaryTopology !== true');
+    assert.isNumber(max_error, 'max_error');
+
+    if (!(max_error > 0)) {
+        return;
+    }
+
+    const eps = max_error;
+    const eps_sq = eps * eps;
+
+    const edge_pool = mesh.edges;
+    const edge_count = edge_pool.size;
+
+    if (edge_count === 0) {
+        return;
+    }
+
+    const quadratics = bt_mesh_compute_vertex_quadratics(mesh);
+
+    // O(1) degree/boundary caches for choose_collapse, seeded once and kept current per collapse.
+    const vertex_count = mesh.vertices.size;
+    _degree = new Int32Array(vertex_count);
+    _vboundary = new Uint8Array(vertex_count);
+    for (let v = 0; v < vertex_count; v++) {
+        if (mesh.vertices.is_allocated(v)) {
+            recompute_vertex_cache(mesh, v);
+        }
+    }
+
+    // Indexed min priority queue keyed by edge id: re-costs are in-place insert_or_update / remove
+    // (O(1) expected via its internal id->handle map), so there are no duplicate or stale entries to
+    // track -- the queue always holds exactly the currently-collapsible edges. Edges are only ever
+    // killed, never created, so ids stay < edge_count for the whole run.
+    const heap = new FibonacciHeap(edge_count);
+
+    for (let e = 0; e < edge_count; e++) {
+        if (!edge_pool.is_allocated(e)) {
+            continue;
+        }
+
+        const cost = choose_collapse(mesh, e, quadratics, eps);
+
+        if (cost <= eps_sq) {
+            heap.insert(e, cost);
+        }
+    }
+
+    // Safety bound against an unforeseen non-terminating re-queue cycle. Every accepted collapse
+    // removes >= 1 face; collapsed-edge and over-tolerance/fold pops also burn iterations.
+    let guard = (edge_count + heap.size) * 8 + 16;
+
+    while (!heap.is_empty()) {
+        if (--guard < 0) {
+            break;
+        }
+
+        const e = heap.pop_min();
+
+        if (!edge_pool.is_allocated(e)) {
+            // edge already collapsed away (its queue entry was never removed; drop it now)
+            continue;
+        }
+
+        // Re-validate against the live mesh: a 2-ring change may have raised this edge's cost
+        // without re-queueing it (requeue only touches the 1-ring). This also fills in the chosen
+        // collapse direction (_choice_survivor / _choice_victim).
+        const cost = choose_collapse(mesh, e, quadratics, eps);
+
+        if (cost > eps_sq) {
+            // no longer within tolerance; a neighbouring collapse may re-queue it later
+            continue;
+        }
+
+        const survivor = _choice_survivor;
+        const victim = _choice_victim;
+
+        if (survivor === NULL_POINTER || victim === NULL_POINTER) {
+            continue;
+        }
+
+        if (collapse_would_fold(mesh, victim, survivor)) {
+            // a neighbouring collapse may re-queue it later
+            continue;
+        }
+
+        // bt_edge_collapse keeps v1; make the survivor v1 so it is the one that stays.
+        if (mesh.edge_read_vertex1(e) !== survivor) {
+            bt_edge_swap_vertex_slots(mesh, e);
+        }
+
+        // The survivor keeps its exact coordinate -- nothing in the mesh moves.
+        mesh.vertex_read_coordinate(_pos_target, 0, survivor);
+
+        // Fold the victim's accumulated planes into the survivor before the topology changes,
+        // so the survivor's quadric keeps measuring deviation from the original surface.
+        quadratics[survivor].add(quadratics[victim]);
+        quadratics[victim] = null;
+
+        bt_edge_kill_parallels(mesh, e);
+        const s = bt_edge_collapse(mesh, e, _pos_target, 0);
+        bt_vert_fuse_duplicate_edges(mesh, s);
+
+        requeue_ring(mesh, s, quadratics, eps, eps_sq, heap);
+    }
+
+    bt_mesh_cleanup_faceless_references(mesh);
+}

package/src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_swap_vertex_slots.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Swap the v1/v2 slots of an edge. Disk cycle pointers for the two slots are swapped
+ * alongside so that the disk cycles on both attached vertices remain valid.
+ *
+ * Useful before a half-edge collapse (e.g. {@link bt_edge_collapse}, which keeps v1 as
+ * the survivor) when the caller needs a specific endpoint to survive: swap first so the
+ * desired survivor sits in the v1 slot.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ */
+export function bt_edge_swap_vertex_slots(mesh: BinaryTopology, edge_id: number): void;
+//# sourceMappingURL=bt_edge_swap_vertex_slots.d.ts.map

package/src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_swap_vertex_slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bt_edge_swap_vertex_slots.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_swap_vertex_slots.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,yEAFW,MAAM,QAkBhB"}

package/src/core/geom/3d/topology/struct/binary/io/edge/bt_edge_swap_vertex_slots.js

@@ -0,0 +1,28 @@
+/**
+ * Swap the v1/v2 slots of an edge. Disk cycle pointers for the two slots are swapped
+ * alongside so that the disk cycles on both attached vertices remain valid.
+ *
+ * Useful before a half-edge collapse (e.g. {@link bt_edge_collapse}, which keeps v1 as
+ * the survivor) when the caller needs a specific endpoint to survive: swap first so the
+ * desired survivor sits in the v1 slot.
+ *
+ * @param {BinaryTopology} mesh
+ * @param {number} edge_id
+ */
+export function bt_edge_swap_vertex_slots(mesh, edge_id) {
+    const v1 = mesh.edge_read_vertex1(edge_id);
+    const v2 = mesh.edge_read_vertex2(edge_id);
+
+    const v1_next = mesh.edge_read_v1_disk_next(edge_id);
+    const v1_prev = mesh.edge_read_v1_disk_prev(edge_id);
+    const v2_next = mesh.edge_read_v2_disk_next(edge_id);
+    const v2_prev = mesh.edge_read_v2_disk_prev(edge_id);
+
+    mesh.edge_write_vertex1(edge_id, v2);
+    mesh.edge_write_vertex2(edge_id, v1);
+
+    mesh.edge_write_v1_disk_next(edge_id, v2_next);
+    mesh.edge_write_v1_disk_prev(edge_id, v2_prev);
+    mesh.edge_write_v2_disk_next(edge_id, v1_next);
+    mesh.edge_write_v2_disk_prev(edge_id, v1_prev);
+}

package/src/core/graph/metis/native/bisection/BisectionScratch.d.ts

@@ -68,5 +68,5 @@ export class BisectionScratch {
      */
     release_vertex_partition_slot(): void;
 }
-import { IndexedFloatMaxHeap } from "../refine/IndexedFloatMaxHeap.js";
+import { IndexedFloatMaxHeap } from "../../../../collection/heap/IndexedFloatMaxHeap.js";
 //# sourceMappingURL=BisectionScratch.d.ts.map

package/src/core/graph/metis/native/bisection/BisectionScratch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BisectionScratch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/BisectionScratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IACI;;OAEG;IACH,8BAFW,MAAM,EA8BhB;IA3BG,yBAAwC;IAIxC,+BAA0D;IAC1D,wCAAmE;IACnE,6BAAwD;IACxD,6BAAwD;IACxD,+BAA2C;IAC3C,qCAAgE;IAIhE,gCAGC;IACD,gCAA2D;IAE3D,6BAAwD;IACxD,gCAA2D;IAI3D,4BAA4B;IAC5B,uBADW,WAAW,EAAE,CACO;IAC/B,kCAAkC;IAGtC;;;;;;;;;;OAUG;IACH,yCAHW,MAAM,GACJ,WAAW,CAavB;IAED;;;OAGG;IACH,sCAEC;CACJ;oCApGmC,kCAAkC"}
+{"version":3,"file":"BisectionScratch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/bisection/BisectionScratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH;IACI;;OAEG;IACH,8BAFW,MAAM,EA8BhB;IA3BG,yBAAwC;IAIxC,+BAA0D;IAC1D,wCAAmE;IACnE,6BAAwD;IACxD,6BAAwD;IACxD,+BAA2C;IAC3C,qCAAgE;IAIhE,gCAGC;IACD,gCAA2D;IAE3D,6BAAwD;IACxD,gCAA2D;IAI3D,4BAA4B;IAC5B,uBADW,WAAW,EAAE,CACO;IAC/B,kCAAkC;IAGtC;;;;;;;;;;OAUG;IACH,yCAHW,MAAM,GACJ,WAAW,CAavB;IAED;;;OAGG;IACH,sCAEC;CACJ;oCApGmC,oDAAoD"}

package/src/core/graph/metis/native/bisection/BisectionScratch.js

@@ -1,4 +1,4 @@
-import { IndexedFloatMaxHeap } from "../refine/IndexedFloatMaxHeap.js";
+import { IndexedFloatMaxHeap } from "../../../../collection/heap/IndexedFloatMaxHeap.js";
 
 /**
  * Pre-allocated scratch reused by every recursive `bisect_graph` call during

package/src/core/graph/metis/native/refine/RefinementScratch.d.ts

@@ -41,5 +41,5 @@ export class RefinementScratch {
     partition_weight_min: Uint32Array;
     partition_weight_max: Uint32Array;
 }
-import { IndexedFloatMaxHeap } from "./IndexedFloatMaxHeap.js";
+import { IndexedFloatMaxHeap } from "../../../../collection/heap/IndexedFloatMaxHeap.js";
 //# sourceMappingURL=RefinementScratch.d.ts.map

package/src/core/graph/metis/native/refine/RefinementScratch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefinementScratch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/RefinementScratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;OAGG;IACH,8BAHW,MAAM,mBACN,MAAM,EAkBhB;IAfG,yBAAwC;IACxC,wBAAsC;IAEtC,gCAGC;IAED,yBAAoD;IACpD,8BAAyD;IACzD,uCAAkE;IAGlE,kCAA4D;IAC5D,kCAA4D;CAEnE;oCApDmC,0BAA0B"}
+{"version":3,"file":"RefinementScratch.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/RefinementScratch.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;OAGG;IACH,8BAHW,MAAM,mBACN,MAAM,EAkBhB;IAfG,yBAAwC;IACxC,wBAAsC;IAEtC,gCAGC;IAED,yBAAoD;IACpD,8BAAyD;IACzD,uCAAkE;IAGlE,kCAA4D;IAC5D,kCAA4D;CAEnE;oCApDmC,oDAAoD"}

package/src/core/graph/metis/native/refine/RefinementScratch.js

@@ -1,4 +1,4 @@
-import { IndexedFloatMaxHeap } from "./IndexedFloatMaxHeap.js";
+import { IndexedFloatMaxHeap } from "../../../../collection/heap/IndexedFloatMaxHeap.js";
 
 /**
  * Pre-allocated scratch reused across every `fm_kway` call during the

package/src/engine/navigation/mesh/build/navmesh_build_topology.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navmesh_build_topology.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/navmesh_build_topology.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;GAUG;AACH,wKATW,cAAc,QAmMxB;+BAlP8B,mEAAmE"}
+{"version":3,"file":"navmesh_build_topology.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/navigation/mesh/build/navmesh_build_topology.js"],"names":[],"mappings":"AAuDA;;;;;;;;;;GAUG;AACH,wKATW,cAAc,QAmNxB;+BA3Q8B,mEAAmE"}

package/src/engine/navigation/mesh/build/navmesh_build_topology.js

@@ -41,8 +41,17 @@ import {
 import {
     bt_mesh_fill_small_holes
 } from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js";
+import {
+    bt_mesh_simplify_by_error
+} from "../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_simplify_by_error.js";
 import { clip_soup_against_overhangs } from "./clip_soup_against_overhangs.js";
 
+// Fraction of the agent radius used as the navmesh cleanup error budget (see the cleanup pass in
+// navmesh_build_topology). A larger agent cannot resolve fine surface detail and the walkable
+// surface was already inset by agent_radius during erosion, so a small fraction of it is a safe,
+// navigation-imperceptible bound on how far cleanup may move the surface or the walkable outline.
+const NAVMESH_SIMPLIFY_ERROR_FRACTION = 0.05;
+
 
 /**
  * Build from given scene geometry
@@ -98,6 +107,11 @@ export function navmesh_build_topology({
     let raw_triangles = [];
     let triangle_count = 0;
 
+    // NOTE: the inherited source tessellation is cleaned up at the end of this function by
+    // bt_mesh_simplify_by_error (interior coplanar fans + collinear boundary runs collapsed). A
+    // further win -- re-triangulating large flat regions to a minimal polygon set -- is left as a
+    // possible follow-up.
+
     for (let face_id = 0; face_id < source_face_count; face_id++) {
 
         source.face_read_normal(scratch_normal, 0, face_id);
@@ -234,6 +248,17 @@ export function navmesh_build_topology({
             }
         }
 
+        // --- Clean up the dense triangulation inherited from the source render geometry ---
+        // The navmesh arrives with far more triangles than navigation needs (a flat floor comes in
+        // as many coplanar triangles). Collapse only the geometrically redundant ones -- interior
+        // near-coplanar fans and collinear runs of boundary vertices -- without moving the surface
+        // or the walkable outline (and obstacle holes) by more than a small fraction of the agent
+        // radius. With agent_radius 0 the tolerance is 0 and this is a no-op.
+        if (agent_radius > 0) {
+            bt_mesh_simplify_by_error(mesh, agent_radius * NAVMESH_SIMPLIFY_ERROR_FRACTION);
+            bt_mesh_compact(mesh);
+        }
+
         // face normals are consumed by navigation queries (string-pulling portal normals), populate them now
         bt_mesh_compute_face_normals(mesh);
 

package/src/core/graph/metis/native/refine/IndexedFloatMaxHeap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"IndexedFloatMaxHeap.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/graph/metis/native/refine/IndexedFloatMaxHeap.js"],"names":[],"mappings":"AA6BA;IACI;;;OAGG;IACH,yBAHW,MAAM,0BACN,MAAM,EAsBhB;IAbG,wBAA4C;IAC5C,eAAe;IAEf,2BAA4E;IAC5E,2BAAwD;IACxD,6BAA0D;IAE1D;;;OAGG;IACH,cAFU,WAAW,CAE2B;IAIpD,mBAEC;IAED;;;OAGG;IACH,cAQC;IAED,2BAEC;IAED;;;OAGG;IACH,qBAkBC;IAED;;;;OAIG;IACH,oBAsBC;IAED;;;;OAIG;IACH,kBAYC;IAED,wBAUC;IAED;;;OAGG;IACH,WAHW,MAAM,SACN,MAAM,QAehB;IAED;;OAEG;IACH,WAFa,MAAM,CAuBlB;IAED;;;OAGG;IACH,WAHW,MAAM,aACN,MAAM,QAehB;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CA+BnB;CACJ"}