@woosh/meep-engine 2.163.7 → 2.163.8

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

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

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ *
+ * 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
+ * rather than the intersection point.
+ *
+ * @param {number} l0_x line point A x
+ * @param {number} l0_y line point A y
+ * @param {number} l1_x line point B x
+ * @param {number} l1_y line point B y
+ * @param {number} s0_x segment start x
+ * @param {number} s0_y segment start y
+ * @param {number} s1_x segment end x
+ * @param {number} s1_y segment end y
+ * @returns {number}
+ */
+export function line_segment_intersection_fraction_2d(l0_x: number, l0_y: number, l1_x: number, l1_y: number, s0_x: number, s0_y: number, s1_x: number, s1_y: number): number;
+//# sourceMappingURL=line_segment_intersection_fraction_2d.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,42 @@
+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.
+ *
+ * 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
+ * rather than the intersection point.
+ *
+ * @param {number} l0_x line point A x
+ * @param {number} l0_y line point A y
+ * @param {number} l1_x line point B x
+ * @param {number} l1_y line point B y
+ * @param {number} s0_x segment start x
+ * @param {number} s0_y segment start y
+ * @param {number} s1_x segment end x
+ * @param {number} s1_y segment end y
+ * @returns {number}
+ */
+export function line_segment_intersection_fraction_2d(
+    l0_x, l0_y, l1_x, l1_y,
+    s0_x, s0_y, s1_x, s1_y
+) {
+    const dir_x = l1_x - l0_x;
+    const dir_y = l1_y - l0_y;
+
+    const side_0 = v2_cross_product(dir_x, dir_y, s0_x - l0_x, s0_y - l0_y);
+    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
+    }
+
+    const denom = side_0 - side_1;
+    if (denom === 0) {
+        return NaN; // parallel / collinear
+    }
+
+    return side_0 / denom;
+}

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

@@ -8,8 +8,8 @@
  * The erosion distance may be smaller than the smallest triangle height in the island, or it may be significantly larger - there is no restriction.
  *
  * @param {BinaryTopology} mesh
- * @param {number[]} faces
- * @param {number} erode_distance
+ * @param {number[]} faces seed faces of the island to erode
+ * @param {number} erode_distance distance to move the outline inwards by
  */
 export function bt_mesh_face_island_erode(mesh: BinaryTopology, faces: number[], erode_distance: number): void;
 //# sourceMappingURL=bt_mesh_face_island_erode.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_face_island_erode.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;GAYG;AACH,uEAHW,MAAM,EAAE,kBACR,MAAM,QAgehB"}
+{"version":3,"file":"bt_mesh_face_island_erode.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;GAYG;AACH,uEAHW,MAAM,EAAE,kBACR,MAAM,QAqbhB"}

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

@@ -5,34 +5,18 @@ import {
     line3_compute_segment_point_distance_eikonal
 } from "../../../../line/line3_compute_segment_point_distance_eikonal.js";
 import { NULL_POINTER } from "../BinaryTopology.js";
+import { BitSet } from "../../../../../../binary/BitSet.js";
 import { bt_face_get_incenter } from "../query/bt_face_get_incenter.js";
+import { bt_face_island_flood_fill } from "../query/bt_face_island_flood_fill.js";
+import {
+    bt_collect_boundary_segments,
+    bt_point_distance_to_segments,
+    bt_mesh_build_boundary_euclidean_distance_field
+} from "../query/bt_mesh_build_boundary_euclidean_distance_field.js";
 import { bt_mesh_cleanup_faceless_references } from "./bt_mesh_cleanup_faceless_references.js";
 import { bt_edge_split } from "./edge/bt_edge_split.js";
 import { bt_face_kill } from "./face/bt_face_kill.js";
 import { bt_mesh_face_poke } from "./face/bt_face_poke.js";
-import { bt_face_get_neighbour_faces } from "../query/bt_face_get_neighbour_faces.js";
-
-const _eb_a = new Float32Array(3);
-const _eb_b = new Float32Array(3);
-const _eb_p = new Float32Array(3);
-
-/**
- * Squared straight-line distance from point p to segment a-b in 3D.
- */
-function point_segment_distance_sq(px, py, pz, ax, ay, az, bx, by, bz) {
-    const abx = bx - ax, aby = by - ay, abz = bz - az;
-    const apx = px - ax, apy = py - ay, apz = pz - az;
-    const ab_len_sq = abx * abx + aby * aby + abz * abz;
-
-    let t = ab_len_sq > 0 ? (apx * abx + apy * aby + apz * abz) / ab_len_sq : 0;
-    if (t < 0) t = 0; else if (t > 1) t = 1;
-
-    const cx = ax + t * abx - px;
-    const cy = ay + t * aby - py;
-    const cz = az + t * abz - pz;
-
-    return cx * cx + cy * cy + cz * cz;
-}
 
 /**
  * Shrinks an island of faces by a given distance.
@@ -44,8 +28,8 @@ function point_segment_distance_sq(px, py, pz, ax, ay, az, bx, by, bz) {
  * The erosion distance may be smaller than the smallest triangle height in the island, or it may be significantly larger - there is no restriction.
  *
  * @param {BinaryTopology} mesh
- * @param {number[]} faces
- * @param {number} erode_distance
+ * @param {number[]} faces seed faces of the island to erode
+ * @param {number} erode_distance distance to move the outline inwards by
  */
 export function bt_mesh_face_island_erode(
     mesh,
@@ -58,11 +42,25 @@ export function bt_mesh_face_island_erode(
         return;
     }
 
-    // 1. + 2. Map the island's vertices/edges and detect boundary (single radial loop) edges/vertices.
-    // Extracted into a helper so it can be recomputed after the connectivity pre-pass mutates the mesh.
+    // Reused island working sets. collect_island_sets clears and refills these in place, so the same
+    // four Set objects serve the whole erosion (which re-derives them many times) without allocating.
+    const island_vertices = new Set();
+    const island_edges = new Set();
+    const boundary_vertices = new Set();
+    const boundary_edges = new Set();
+
+    /**
+     * Refill the four island working sets for `island_faces`: every vertex and edge the island touches,
+     * plus the subset of each that lies on the boundary (an edge whose radial cycle is a single loop).
+     * Clears the sets first so their backing storage is reused across calls.
+     *
+     * @param {number[]} island_faces allocated face IDs making up the island
+     */
     function collect_island_sets(island_faces) {
-        const iv = new Set();
-        const ie = new Set();
+        island_vertices.clear();
+        island_edges.clear();
+        boundary_vertices.clear();
+        boundary_edges.clear();
 
         for (let i = 0; i < island_faces.length; i++) {
             const f = island_faces[i];
@@ -71,64 +69,44 @@ export function bt_mesh_face_island_erode(
 
             let l_curr = l_first;
             do {
-                iv.add(mesh.loop_read_vertex(l_curr));
-                ie.add(mesh.loop_read_edge(l_curr));
+                island_vertices.add(mesh.loop_read_vertex(l_curr));
+                island_edges.add(mesh.loop_read_edge(l_curr));
                 l_curr = mesh.loop_read_next(l_curr);
             } while (l_curr !== l_first);
         }
 
-        const bv = new Set();
-        const be = new Set();
-
-        for (const e of ie) {
+        for (const e of island_edges) {
             const l = mesh.edge_read_loop(e);
             if (mesh.loop_read_radial_next(l) === l) {
-                bv.add(mesh.edge_read_vertex1(e));
-                bv.add(mesh.edge_read_vertex2(e));
-                be.add(e);
+                boundary_vertices.add(mesh.edge_read_vertex1(e));
+                boundary_vertices.add(mesh.edge_read_vertex2(e));
+                boundary_edges.add(e);
             }
         }
-
-        return { island_vertices: iv, island_edges: ie, boundary_vertices: bv, boundary_edges_set: be };
     }
 
-    // Re-derive the (now larger) face list of this island after edge splits by flood-filling
-    // edge-adjacency from the original faces. bt_edge_split reuses the original face ids for one half
-    // of each split, so they remain valid, allocated seeds.
-    function recompute_island_faces(seed_faces) {
-        const seen = new Set();
-        const stack = [];
-        const result = [];
-        const nbr = [];
-
-        for (let i = 0; i < seed_faces.length; i++) {
-            const f = seed_faces[i];
-            if (mesh.faces.is_allocated(f)) {
-                stack.push(f);
-            }
-        }
-
-        while (stack.length > 0) {
-            const f = stack.pop();
-            if (seen.has(f)) continue;
-            seen.add(f);
-            result.push(f);
-
-            const n = bt_face_get_neighbour_faces(nbr, 0, mesh, f);
-            for (let i = 0; i < n; i++) {
-                const g = nbr[i];
-                if (!seen.has(g)) {
-                    stack.push(g);
-                }
-            }
-        }
+    // Reused buffers for re-deriving the island's faces after edge splits.
+    const flood_visited = new BitSet();
+    const island_faces_scratch = [];
 
-        return result;
+    /**
+     * Re-derive the (now larger) face list of this island after edge splits, by flood-filling
+     * edge-adjacency from the original seed faces. {@link bt_edge_split} reuses the original face IDs
+     * for one half of each split, so the seeds stay allocated and edge-connected to the new fragments.
+     * Returns a reused buffer - the caller must not retain it across calls.
+     *
+     * @param {number[]} seed_faces original island face IDs
+     * @returns {number[]} the island's current faces (reused buffer)
+     */
+    function recompute_island_faces(seed_faces) {
+        flood_visited.reset();
+        island_faces_scratch.length = 0;
+        bt_face_island_flood_fill(mesh, seed_faces, island_faces_scratch, flood_visited);
+        return island_faces_scratch;
     }
 
     let island_faces = faces;
-
-    let { island_vertices, island_edges, boundary_vertices, boundary_edges_set } = collect_island_sets(island_faces);
+    collect_island_sets(island_faces);
 
     if (boundary_vertices.size === 0) {
         // no boundary vertices found
@@ -137,23 +115,23 @@ export function bt_mesh_face_island_erode(
     }
 
     // ---------------------------------------------------------
-    // 2.5. CONNECTIVITY PRE-PASS (fix for erosion fragmentation)
+    // CONNECTIVITY PRE-PASS (fix for erosion fragmentation)
     // ---------------------------------------------------------
-    // The boundary distance field is sampled only at vertices and interpolated linearly along edges.
-    // An *interior* edge whose BOTH endpoints lie on the boundary therefore reads as ~0 along its
-    // entire length, even where its middle sits deep inside the island (the shared diagonal of a coarse
-    // quad, or the seam between two large coplanar tiles). Erosion then culls a band straddling that
-    // edge and severs one connected island into disconnected pieces.
+    // The distance field is sampled only at vertices and interpolated linearly along edges. An
+    // *interior* edge whose BOTH endpoints lie on the boundary therefore reads as ~0 along its entire
+    // length, even where its middle sits deep inside the island (the shared diagonal of a coarse quad,
+    // or the seam between two large coplanar tiles). Erosion then culls a band straddling that edge and
+    // severs one connected island into disconnected pieces.
     //
     // Fix: insert an interior vertex at the midpoint of every such edge. The new vertex is genuinely
-    // interior, so the eikonal field gives it the correct (large) clearance and the contour keeps the
-    // deep interior alive, preserving connectivity. A single pass suffices: splitting a
-    // boundary-boundary interior edge yields only boundary-interior edges, creating no new offenders.
+    // interior, so it gets the correct (large) clearance and the contour keeps the deep interior alive,
+    // preserving connectivity. A single pass suffices: splitting a boundary-boundary interior edge
+    // yields only boundary-interior edges, creating no new offenders.
     {
         const split_targets = [];
 
         for (const e of island_edges) {
-            if (boundary_edges_set.has(e)) {
+            if (boundary_edges.has(e)) {
                 // a true boundary edge defines the outline - never split it
                 continue;
             }
@@ -172,8 +150,7 @@ export function bt_mesh_face_island_erode(
             }
 
             island_faces = recompute_island_faces(faces);
-
-            ({ island_vertices, island_edges, boundary_vertices, boundary_edges_set } = collect_island_sets(island_faces));
+            collect_island_sets(island_faces);
 
             if (boundary_vertices.size === 0) {
                 return;
@@ -181,57 +158,34 @@ export function bt_mesh_face_island_erode(
         }
     }
 
-    // 3. Distance field: EXACT straight-line distance from each island vertex to the nearest boundary
+    // Distance field: EXACT straight-line distance from each island vertex to the nearest boundary
     // edge. Agent clearance is a Euclidean (line-of-sight) distance to the nearest wall, NOT a geodesic
-    // distance measured along the surface. The previous eikonal field was both semantically wrong and
-    // sensitive to the triangulation - it produced a lumpy, non-uniform inset (e.g. a 14x14 platform
-    // built from strips eroded by 0.45-0.65 instead of a uniform 0.4). Exact distance is uniform.
+    // distance measured along the surface, so the eikonal field would be both semantically wrong here
+    // and sensitive to the triangulation (a lumpy, non-uniform inset). See
+    // bt_mesh_build_boundary_euclidean_distance_field.
     /**
-     * Vertex -> Distance from boundary
+     * Vertex -> distance from boundary.
      * @type {Map<number, number>}
      */
     const vertex_boundary_distances = new Map();
 
-    // boundary edge segments, cached by compute_field for reuse in the deviation test below
-    let boundary_segments = [];
+    // Flat boundary segment buffer (6 numbers per segment), reused across every field rebuild.
+    const boundary_segments = [];
 
-    // (re)compute the exact distance field for the current island vertices/boundary
+    // (Re)compute the exact distance field for the current island vertices and boundary.
     function compute_field() {
-        vertex_boundary_distances.clear();
-
-        boundary_segments = [];
-        for (const e of boundary_edges_set) {
-            const bv1 = mesh.edge_read_vertex1(e);
-            const bv2 = mesh.edge_read_vertex2(e);
-            mesh.vertex_read_coordinate(_eb_a, 0, bv1);
-            mesh.vertex_read_coordinate(_eb_b, 0, bv2);
-            boundary_segments.push(_eb_a[0], _eb_a[1], _eb_a[2], _eb_b[0], _eb_b[1], _eb_b[2]);
-        }
-
-        for (const v of island_vertices) {
-            mesh.vertex_read_coordinate(_eb_p, 0, v);
-            vertex_boundary_distances.set(v, dist_to_boundary(_eb_p[0], _eb_p[1], _eb_p[2]));
-        }
-    }
-
-    // exact straight-line distance from a point to the nearest boundary edge
-    function dist_to_boundary(px, py, pz) {
-        const seg = boundary_segments;
-        let best_sq = Infinity;
-        for (let i = 0; i < seg.length; i += 6) {
-            const d_sq = point_segment_distance_sq(
-                px, py, pz,
-                seg[i], seg[i + 1], seg[i + 2],
-                seg[i + 3], seg[i + 4], seg[i + 5]
-            );
-            if (d_sq < best_sq) best_sq = d_sq;
-        }
-        return best_sq === Infinity ? Infinity : Math.sqrt(best_sq);
+        bt_collect_boundary_segments(mesh, boundary_edges, boundary_segments);
+        bt_mesh_build_boundary_euclidean_distance_field(
+            vertex_boundary_distances,
+            mesh,
+            island_vertices,
+            boundary_segments
+        );
     }
 
     compute_field();
 
-    // 3a. CUT-BAND REFINEMENT. The inset contour is reconstructed piecewise-linearly from the faces the
+    // CUT-BAND REFINEMENT. The inset contour is reconstructed piecewise-linearly from the faces the
     // erosion threshold passes through, so on a coarse/skewed triangulation the cut chord deviates from
     // the true offset (a strip-built platform eroded unevenly, 0.4 on one side and 0.6 on another). For
     // each straddling face, place the two cut points and test whether their midpoint really lies at the
@@ -245,10 +199,13 @@ export function bt_mesh_face_island_erode(
 
         const ca = new Float32Array(3), cb = new Float32Array(3), cc = new Float32Array(3);
 
+        // reused across rounds: edges whose longest side should be split this round
+        const refine_targets = new Set();
+
         while (rounds < 48) {
             rounds++;
 
-            const targets = new Set();
+            refine_targets.clear();
 
             for (let i = 0; i < island_faces.length; i++) {
                 const f = island_faces[i];
@@ -302,7 +259,7 @@ export function bt_mesh_face_island_erode(
 
                 if (crossings === 2) {
                     mx *= 0.5; my *= 0.5; mz *= 0.5;
-                    const true_d = dist_to_boundary(mx, my, mz);
+                    const true_d = bt_point_distance_to_segments(boundary_segments, mx, my, mz);
                     if (Math.abs(true_d - erode_distance) <= tol) {
                         // the straight cut here is already accurate - leave this face coarse
                         continue;
@@ -310,37 +267,38 @@ export function bt_mesh_face_island_erode(
                 }
 
                 const sl = (longest === e_ab) ? la : (longest === e_bc) ? lb : lc;
-                targets.add(mesh.loop_read_edge(sl));
+                refine_targets.add(mesh.loop_read_edge(sl));
             }
 
-            if (targets.size === 0) break;
+            if (refine_targets.size === 0) break;
 
-            for (const e of targets) {
+            for (const e of refine_targets) {
                 if (mesh.edges.is_allocated(e)) bt_edge_split(mesh, e, 0.5);
             }
 
             island_faces = recompute_island_faces(faces);
-            ({ island_vertices, island_edges, boundary_vertices, boundary_edges_set } = collect_island_sets(island_faces));
+            collect_island_sets(island_faces);
 
             compute_field();
 
             if (mesh.faces.size > 200000) break;
         }
     }
+
     // ---------------------------------------------------------
-    // 3.5. PEAK RESCUE PASS (The Fix)
-    // Handle cases where a face is "submerged" by vertex values
-    // but geometrically contains a safe zone (e.g. single triangle).
+    // PEAK RESCUE PASS
+    // Handle cases where a face is "submerged" by its vertex values but geometrically contains a safe
+    // zone (e.g. a single triangle whose corners are all on the boundary, but whose incenter is not).
     // ---------------------------------------------------------
 
-    // We snapshot the faces list because we might modify topology (poke)
+    // Snapshot the face list because we may modify topology (poke) while iterating.
     const faces_to_check = [...island_faces];
     const centroid = [];
     const scratch_v1 = [];
     const scratch_v2 = [];
 
     for (const f of faces_to_check) {
-        // Collect face vertices and check if they are all "dead"
+        // Collect face vertices and check if they are all "dead".
         let l_curr = mesh.face_read_loop(f);
         const l_end = l_curr;
         let all_dead = true;
@@ -354,16 +312,14 @@ export function bt_mesh_face_island_erode(
         } while (l_curr !== l_end);
 
         if (all_dead) {
-            // This face is slated for total deletion.
-            // Check if we should rescue it by adding a peak vertex.
+            // This face is slated for total deletion. Check whether we should rescue it by adding a peak
+            // vertex at the incenter.
 
-            // 1. Calculate Centroid (incenter only for triangle, falls back to centroid for other N-gons)
+            // 1. Incenter (for a triangle; falls back to centroid for other n-gons).
             bt_face_get_incenter(centroid, 0, mesh, f);
 
-            // 2. Calculate Centroid Distance to Boundary
-            // (For a single island face, min dist to its own boundary edges)
+            // 2. Incenter distance to boundary (min over this face's own boundary-crossing edges).
             let min_dist = Infinity;
-            // Iterate edges of this face
             l_curr = mesh.face_read_loop(f);
             do {
                 const e = mesh.loop_read_edge(l_curr);
@@ -392,30 +348,23 @@ export function bt_mesh_face_island_erode(
                         if (d < min_dist) {
                             min_dist = d;
                         }
-
                     }
-
                 }
 
                 l_curr = mesh.loop_read_next(l_curr);
             } while (l_curr !== l_end);
 
-            // If min_dist is Infinity, it means this face has NO boundary edges
-            // (it's internal). It should have inherited values from neighbors.
-            // We ignore it, or assume linear interpolation was correct.
-            // We only rescue faces touching the boundary that collapsed.
-
+            // min_dist === Infinity means this face has no boundary edges (it's internal); leave it to
+            // the interpolated field. We only rescue faces touching the boundary that collapsed.
             if (min_dist !== Infinity && min_dist > erode_distance) {
-                // RESCUE: The center is safe!
-                // Poke the face to create a vertex at the centroid.
+                // RESCUE: the center is safe - poke the face to create a vertex at the incenter.
                 const new_vert = bt_mesh_face_poke(mesh, f, centroid[0], centroid[1], centroid[2]);
 
-                // Update Data
                 island_vertices.add(new_vert);
                 vertex_boundary_distances.set(new_vert, min_dist);
 
-                // Read the new edges connected to the center and add to processing set
-                let e_first = mesh.vertex_read_edge(new_vert);
+                // Register the new edges fanning from the centre into the working edge set.
+                const e_first = mesh.vertex_read_edge(new_vert);
 
                 let e_scan = e_first;
                 do {
@@ -424,7 +373,7 @@ export function bt_mesh_face_island_erode(
                     const v1 = mesh.edge_read_vertex1(e_scan);
                     const is_v1 = v1 === new_vert;
 
-                    // DEBUG checks
+                    // sanity: exactly one endpoint is the new vertex
                     const v2 = mesh.edge_read_vertex2(e_scan);
                     if (is_v1) {
                         assert.equal(v1, new_vert, 'edge vertex does not match new vertex');
@@ -439,15 +388,11 @@ export function bt_mesh_face_island_erode(
             }
         }
     }
-    // ---------------------------------------------------------
-
-    // 4. Trace the Contour & Split Edges
 
-    /**
-     *
-     * @type {{e: number, t: number}[]}
-     */
-    const edges_to_split = [];
+    // Trace the contour: split every island edge that strictly crosses the erosion threshold, exactly at
+    // the crossing. Parallel arrays (edge id + parameter) avoid one small object per crossing edge.
+    const split_edges = [];
+    const split_ts = [];
 
     for (const e of island_edges) {
 
@@ -459,34 +404,31 @@ export function bt_mesh_face_island_erode(
         const d1 = vertex_boundary_distances.get(v1);
         const d2 = vertex_boundary_distances.get(v2);
 
-        // If the edge strictly crosses the erosion threshold
+        // does the edge strictly cross the erosion threshold?
         const crosses_erosion_boundary = (d1 < erode_distance && d2 > erode_distance) || (d2 < erode_distance && d1 > erode_distance);
 
         if (crosses_erosion_boundary) {
-            // Calculate exact interpolation parameter
             const t = clamp01(inverseLerp(d1, d2, erode_distance));
-            edges_to_split.push({ e, t });
+            split_edges.push(e);
+            split_ts.push(t);
         }
     }
 
-    // Execute splits
-    for (const { e, t } of edges_to_split) {
-        // splits the edge as well as adjacent faces.
-        bt_edge_split(mesh, e, t);
+    for (let i = 0; i < split_edges.length; i++) {
+        // splits the edge as well as the adjacent faces
+        bt_edge_split(mesh, split_edges[i], split_ts[i]);
     }
 
-    // Cull Dead Geometry
-    // Any vertex that had a distance < erode_distance is dead.
-    // Any face connected to a dead vertex must be destroyed.
+    // Cull dead geometry: any vertex whose distance is < erode_distance is dead, and every face touching
+    // a dead vertex must be destroyed.
     /**
-     *
      * @type {Set<number>}
      */
     const faces_to_kill = new Set();
 
-    for (const [vertex, distance] of vertex_boundary_distances.entries()) {
-        const EPSILON = 1e-17;
+    const EPSILON = 1e-17;
 
+    for (const [vertex, distance] of vertex_boundary_distances.entries()) {
         if (distance >= erode_distance - EPSILON) {
             // too far, survives
             continue;
@@ -500,7 +442,7 @@ export function bt_mesh_face_island_erode(
 
         let e_curr = e_first;
         do {
-            // Traverse radial loops to get all connected faces
+            // traverse radial loops to gather all faces connected to this edge
             const l_first = mesh.edge_read_loop(e_curr);
             if (l_first !== NULL_POINTER) {
                 let l_curr = l_first;
@@ -510,18 +452,17 @@ export function bt_mesh_face_island_erode(
                 } while (l_curr !== l_first);
             }
 
-            // Move around disk cycle
+            // move around the disk cycle
             const v1 = mesh.edge_read_vertex1(e_curr);
             e_curr = (v1 === vertex) ? mesh.edge_read_v1_disk_next(e_curr) : mesh.edge_read_v2_disk_next(e_curr);
         } while (e_curr !== e_first && e_curr !== NULL_POINTER);
     }
 
-    // Eradicate the dead faces
     for (const f of faces_to_kill) {
         bt_face_kill(mesh, f);
     }
 
-    // 6. Cleanup floating vertices and edges
+    // Cleanup floating vertices and edges.
     if (faces_to_kill.size > 0) {
         bt_mesh_cleanup_faceless_references(mesh);
     }

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

@@ -1,16 +1,15 @@
 /**
- * Fill boundary holes that are too thin for the agent to occupy.
+ * Fill inner boundary holes whose mean width falls below `min_width`.
  *
- * Erosion/clearance can leave a hair-thin sliver hole hugging an obstacle's offset edge (a strip of
- * cells that are actually clear but get pinched off into their own tiny loop). Such a hole is narrower
- * than the agent, so it can never be a real navigation obstacle - it is numerical noise that inflates
- * the boundary, the face count, and the loop count. This fills any inner loop whose mean width
- * (2*area/perimeter, the inradius of an equivalent disc) is below the agent radius. The single
- * largest-area loop (the outer boundary) is never filled.
+ * A mesh can contain hair-thin sliver holes - a strip of degenerate faces pinched off into its own
+ * tiny boundary loop - that are numerical noise rather than meaningful openings. Such slivers inflate
+ * the boundary length, the face count, and the loop count. This measures every boundary loop's mean
+ * width (2*area/perimeter, the inradius of the area-equivalent disc) and fills each inner loop narrower
+ * than `min_width`. The single largest-area loop is treated as the outer boundary and is never filled.
  *
- * @param {BinaryTopology} mesh
- * @param {number} agent_radius
+ * @param {BinaryTopology} mesh mesh whose boundary loops are inspected and (where too thin) filled in place
+ * @param {number} min_width minimum mean width an inner loop must have to be kept; thinner loops are filled
  * @returns {number} number of holes filled
  */
-export function bt_mesh_fill_small_holes(mesh: BinaryTopology, agent_radius: number): number;
+export function bt_mesh_fill_small_holes(mesh: BinaryTopology, min_width: number): number;
 //# sourceMappingURL=bt_mesh_fill_small_holes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bt_mesh_fill_small_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js"],"names":[],"mappings":"AA+FA;;;;;;;;;;;;;GAaG;AACH,6EAHW,MAAM,GACJ,MAAM,CA2ClB"}
+{"version":3,"file":"bt_mesh_fill_small_holes.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js"],"names":[],"mappings":"AA+FA;;;;;;;;;;;;GAYG;AACH,0EAHW,MAAM,GACJ,MAAM,CA2ClB"}