@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,490 +1,490 @@
-import { assert } from "../../../../../../assert.js";
-import { clamp01 } from "../../../../../../math/clamp01.js";
-import { inverseLerp } from "../../../../../../math/inverseLerp.js";
-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 } from "../query/bt_collect_boundary_segments.js";
-import { segment3_point_distance_to_segments } from "../../../../line/segment3_point_distance_to_segments.js";
-import { 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_face_poke } from "./face/bt_face_poke.js";
-
-/**
- * Shrinks an island of faces by a given distance.
- * Conceptually, this moves the outline of the island inwards.
- * Assumes the input mesh is triangulated, see {@link bt_mesh_triangulate}.
- *
- * It is assumed that the island does not share any edges/vertices with any other part of the mesh. If this assumption is violated - expect undefined behavior.
- * An island is not restricted to all faces being co-planar, it may curve.
- * 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 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,
-    faces,
-    erode_distance
-) {
-
-    if (faces.length === 0 || erode_distance <= 0) {
-        // no work to do
-        return;
-    }
-
-    // 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) {
-        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];
-            const l_first = mesh.face_read_loop(f);
-            if (l_first === NULL_POINTER) continue;
-
-            let l_curr = l_first;
-            do {
-                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);
-        }
-
-        for (const e of island_edges) {
-            const l = mesh.edge_read_loop(e);
-            if (mesh.loop_read_radial_next(l) === l) {
-                boundary_vertices.add(mesh.edge_read_vertex1(e));
-                boundary_vertices.add(mesh.edge_read_vertex2(e));
-                boundary_edges.add(e);
-            }
-        }
-    }
-
-    // Reused buffers for re-deriving the island's faces after edge splits.
-    const flood_visited = new BitSet();
-    const island_faces_scratch = [];
-
-    /**
-     * 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;
-    collect_island_sets(island_faces);
-
-    if (boundary_vertices.size === 0) {
-        // no boundary vertices found
-        // should never happen if the mesh is valid
-        return;
-    }
-
-    // ---------------------------------------------------------
-    // CONNECTIVITY PRE-PASS (fix for erosion fragmentation)
-    // ---------------------------------------------------------
-    // 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 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.has(e)) {
-                // a true boundary edge defines the outline - never split it
-                continue;
-            }
-
-            const v1 = mesh.edge_read_vertex1(e);
-            const v2 = mesh.edge_read_vertex2(e);
-
-            if (boundary_vertices.has(v1) && boundary_vertices.has(v2)) {
-                split_targets.push(e);
-            }
-        }
-
-        if (split_targets.length > 0) {
-            for (let i = 0; i < split_targets.length; i++) {
-                bt_edge_split(mesh, split_targets[i], 0.5);
-            }
-
-            island_faces = recompute_island_faces(faces);
-            collect_island_sets(island_faces);
-
-            if (boundary_vertices.size === 0) {
-                return;
-            }
-        }
-    }
-
-    // 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, 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.
-     * @type {Map<number, number>}
-     */
-    const vertex_boundary_distances = new Map();
-
-    // 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 and boundary.
-    function compute_field() {
-        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();
-
-    // 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 the chord really lies at the
-    // erode distance; only refine (split the longest edge) when it deviates. Already-accurate cuts
-    // (e.g. a plain quad's straight sides) are left coarse, so detail is added only where needed.
-    {
-        const fine = Math.max(erode_distance * 0.5, 0.1);
-        const fine_sq = fine * fine;
-        const tol = Math.max(erode_distance * 0.15, 0.04);
-        let rounds = 0;
-
-        const ca = new Float32Array(3), cb = new Float32Array(3), cc = new Float32Array(3);
-
-        // the two points where the threshold crosses the current face's edges
-        const cut_a = new Float32Array(3), cut_b = new Float32Array(3);
-
-        /** Does this point sit further than `tol` from the true erosion offset? */
-        function deviates(x, y, z) {
-            return Math.abs(segment3_point_distance_to_segments(boundary_segments, x, y, z) - erode_distance) > tol;
-        }
-
-        // reused across rounds: edges whose longest side should be split this round
-        const refine_targets = new Set();
-
-        while (rounds < 48) {
-            rounds++;
-
-            refine_targets.clear();
-
-            for (let i = 0; i < island_faces.length; i++) {
-                const f = island_faces[i];
-                if (!mesh.faces.is_allocated(f)) continue;
-
-                const la = mesh.face_read_loop(f);
-                const lb = mesh.loop_read_next(la);
-                const lc = mesh.loop_read_next(lb);
-                const v1 = mesh.loop_read_vertex(la);
-                const v2 = mesh.loop_read_vertex(lb);
-                const v3 = mesh.loop_read_vertex(lc);
-
-                const d1 = vertex_boundary_distances.get(v1);
-                const d2 = vertex_boundary_distances.get(v2);
-                const d3 = vertex_boundary_distances.get(v3);
-
-                const dmin = Math.min(d1, d2, d3);
-                const dmax = Math.max(d1, d2, d3);
-
-                // does the erode threshold pass through this face?
-                if (!(dmin < erode_distance && dmax > erode_distance)) continue;
-
-                mesh.vertex_read_coordinate(ca, 0, v1);
-                mesh.vertex_read_coordinate(cb, 0, v2);
-                mesh.vertex_read_coordinate(cc, 0, v3);
-
-                const e_ab = (ca[0] - cb[0]) ** 2 + (ca[1] - cb[1]) ** 2 + (ca[2] - cb[2]) ** 2;
-                const e_bc = (cb[0] - cc[0]) ** 2 + (cb[1] - cc[1]) ** 2 + (cb[2] - cc[2]) ** 2;
-                const e_ca = (cc[0] - ca[0]) ** 2 + (cc[1] - ca[1]) ** 2 + (cc[2] - ca[2]) ** 2;
-                const longest = Math.max(e_ab, e_bc, e_ca);
-
-                if (longest <= fine_sq) continue;
-
-                // the two cut points where the threshold crosses this face's edges
-                let crossings = 0;
-                // edge (v1,v2)
-                if ((d1 < erode_distance) !== (d2 < erode_distance)) {
-                    const t = (erode_distance - d1) / (d2 - d1);
-                    const c = crossings === 0 ? cut_a : cut_b;
-                    c[0] = ca[0] + t * (cb[0] - ca[0]); c[1] = ca[1] + t * (cb[1] - ca[1]); c[2] = ca[2] + t * (cb[2] - ca[2]); crossings++;
-                }
-                // edge (v2,v3)
-                if ((d2 < erode_distance) !== (d3 < erode_distance)) {
-                    const t = (erode_distance - d2) / (d3 - d2);
-                    const c = crossings === 0 ? cut_a : cut_b;
-                    c[0] = cb[0] + t * (cc[0] - cb[0]); c[1] = cb[1] + t * (cc[1] - cb[1]); c[2] = cb[2] + t * (cc[2] - cb[2]); crossings++;
-                }
-                // edge (v3,v1)
-                if ((d3 < erode_distance) !== (d1 < erode_distance)) {
-                    const t = (erode_distance - d3) / (d1 - d3);
-                    const c = crossings === 0 ? cut_a : cut_b;
-                    c[0] = cc[0] + t * (ca[0] - cc[0]); c[1] = cc[1] + t * (ca[1] - cc[1]); c[2] = cc[2] + t * (ca[2] - cc[2]); crossings++;
-                }
-
-                // A triangle's vertices give an even number of sign changes around its cycle, so the
-                // threshold crosses either no edges or exactly two - never one or three.
-                assert.ok(crossings === 0 || crossings === 2, 'expected 0 or 2 threshold crossings');
-
-                // Accuracy is judged at BOTH ends of the cut chord as well as at its middle. The chord's
-                // endpoints are the vertices the eroded outline is actually built from, and the distance
-                // field is only piecewise-linear along an edge (it kinks wherever the nearest boundary
-                // feature changes), so an endpoint can sit far off the true offset while the midpoint
-                // still reads correct - one end too deep and the other too shallow cancel out at the
-                // centre. Judging by the midpoint alone accepted those chords, and the misplaced
-                // endpoint survived into the navmesh as a visible kink. The midpoint is still checked
-                // too: a chord across a rounded corner can have both ends on the offset and bulge away
-                // from it in between.
-                if (crossings === 2
-                    && !deviates(cut_a[0], cut_a[1], cut_a[2])
-                    && !deviates(cut_b[0], cut_b[1], cut_b[2])
-                    && !deviates((cut_a[0] + cut_b[0]) * 0.5, (cut_a[1] + cut_b[1]) * 0.5, (cut_a[2] + cut_b[2]) * 0.5)) {
-                    // the straight cut here is already accurate - leave this face coarse
-                    continue;
-                }
-
-                const sl = (longest === e_ab) ? la : (longest === e_bc) ? lb : lc;
-                refine_targets.add(mesh.loop_read_edge(sl));
-            }
-
-            if (refine_targets.size === 0) break;
-
-            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);
-            collect_island_sets(island_faces);
-
-            compute_field();
-
-            if (mesh.faces.size > 200000) break;
-        }
-    }
-
-    // ---------------------------------------------------------
-    // 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).
-    // ---------------------------------------------------------
-
-    // 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".
-        let l_curr = mesh.face_read_loop(f);
-        const l_end = l_curr;
-        let all_dead = true;
-
-        do {
-            const v = mesh.loop_read_vertex(l_curr);
-            if ((vertex_boundary_distances.get(v) || 0) >= erode_distance) {
-                all_dead = false;
-            }
-            l_curr = mesh.loop_read_next(l_curr);
-        } while (l_curr !== l_end);
-
-        if (all_dead) {
-            // This face is slated for total deletion. Check whether we should rescue it by adding a peak
-            // vertex at the incenter.
-
-            // 1. Incenter (for a triangle; falls back to centroid for other n-gons).
-            bt_face_get_incenter(centroid, 0, mesh, f);
-
-            // 2. Incenter distance to boundary (min over this face's own boundary-crossing edges).
-            let min_dist = Infinity;
-            l_curr = mesh.face_read_loop(f);
-            do {
-                const e = mesh.loop_read_edge(l_curr);
-
-                const v1 = mesh.edge_read_vertex1(e);
-                const v2 = mesh.edge_read_vertex2(e);
-
-                if (island_vertices.has(v1) && island_vertices.has(v2)) {
-
-                    mesh.vertex_read_coordinate(scratch_v1, 0, v1);
-                    mesh.vertex_read_coordinate(scratch_v2, 0, v2);
-
-                    const d1 = vertex_boundary_distances.get(v1);
-                    const d2 = vertex_boundary_distances.get(v2);
-
-                    if (d1 < erode_distance || d2 < erode_distance) {
-                        // only consider edges that could cross the erosion threshold
-
-                        const d = line3_compute_segment_point_distance_eikonal(
-                            d1, d2,
-                            scratch_v1[0], scratch_v1[1], scratch_v1[2],
-                            scratch_v2[0], scratch_v2[1], scratch_v2[2],
-                            centroid[0], centroid[1], centroid[2]
-                        );
-
-                        if (d < min_dist) {
-                            min_dist = d;
-                        }
-                    }
-                }
-
-                l_curr = mesh.loop_read_next(l_curr);
-            } while (l_curr !== l_end);
-
-            // 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 incenter.
-                const new_vert = bt_face_poke(mesh, f, centroid[0], centroid[1], centroid[2]);
-
-                island_vertices.add(new_vert);
-                vertex_boundary_distances.set(new_vert, min_dist);
-
-                // 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 {
-                    island_edges.add(e_scan);
-
-                    const v1 = mesh.edge_read_vertex1(e_scan);
-                    const is_v1 = v1 === new_vert;
-
-                    // 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');
-                        assert.notEqual(v2, new_vert, 'edge vertex does not match new vertex');
-                    } else {
-                        assert.equal(v2, new_vert, 'edge vertex does not match new vertex');
-                        assert.notEqual(v1, new_vert, 'edge vertex does not match new vertex');
-                    }
-
-                    e_scan = is_v1 ? mesh.edge_read_v1_disk_next(e_scan) : mesh.edge_read_v2_disk_next(e_scan);
-                } while (e_scan !== e_first);
-            }
-        }
-    }
-
-    // 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) {
-
-        assert.equal(mesh.edges.is_allocated(e), true, 'edge is not allocated');
-
-        const v1 = mesh.edge_read_vertex1(e);
-        const v2 = mesh.edge_read_vertex2(e);
-
-        const d1 = vertex_boundary_distances.get(v1);
-        const d2 = vertex_boundary_distances.get(v2);
-
-        // 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) {
-            const t = clamp01(inverseLerp(d1, d2, erode_distance));
-            split_edges.push(e);
-            split_ts.push(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 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();
-
-    const EPSILON = 1e-17;
-
-    for (const [vertex, distance] of vertex_boundary_distances.entries()) {
-        if (distance >= erode_distance - EPSILON) {
-            // too far, survives
-            continue;
-        }
-
-        const e_first = mesh.vertex_read_edge(vertex);
-
-        if (e_first === NULL_POINTER) {
-            continue;
-        }
-
-        let e_curr = e_first;
-        do {
-            // 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;
-                do {
-                    faces_to_kill.add(mesh.loop_read_face(l_curr));
-                    l_curr = mesh.loop_read_radial_next(l_curr);
-                } while (l_curr !== l_first);
-            }
-
-            // 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);
-    }
-
-    for (const f of faces_to_kill) {
-        bt_face_kill(mesh, f);
-    }
-
-    // Cleanup floating vertices and edges.
-    if (faces_to_kill.size > 0) {
-        bt_mesh_cleanup_faceless_references(mesh);
-    }
-}
+import { assert } from "../../../../../../assert.js";
+import { clamp01 } from "../../../../../../math/clamp01.js";
+import { inverseLerp } from "../../../../../../math/inverseLerp.js";
+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 } from "../query/bt_collect_boundary_segments.js";
+import { segment3_point_distance_to_segments } from "../../../../line/segment3_point_distance_to_segments.js";
+import { 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_face_poke } from "./face/bt_face_poke.js";
+
+/**
+ * Shrinks an island of faces by a given distance.
+ * Conceptually, this moves the outline of the island inwards.
+ * Assumes the input mesh is triangulated, see {@link bt_mesh_triangulate}.
+ *
+ * It is assumed that the island does not share any edges/vertices with any other part of the mesh. If this assumption is violated - expect undefined behavior.
+ * An island is not restricted to all faces being co-planar, it may curve.
+ * 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 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,
+    faces,
+    erode_distance
+) {
+
+    if (faces.length === 0 || erode_distance <= 0) {
+        // no work to do
+        return;
+    }
+
+    // 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) {
+        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];
+            const l_first = mesh.face_read_loop(f);
+            if (l_first === NULL_POINTER) continue;
+
+            let l_curr = l_first;
+            do {
+                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);
+        }
+
+        for (const e of island_edges) {
+            const l = mesh.edge_read_loop(e);
+            if (mesh.loop_read_radial_next(l) === l) {
+                boundary_vertices.add(mesh.edge_read_vertex1(e));
+                boundary_vertices.add(mesh.edge_read_vertex2(e));
+                boundary_edges.add(e);
+            }
+        }
+    }
+
+    // Reused buffers for re-deriving the island's faces after edge splits.
+    const flood_visited = new BitSet();
+    const island_faces_scratch = [];
+
+    /**
+     * 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;
+    collect_island_sets(island_faces);
+
+    if (boundary_vertices.size === 0) {
+        // no boundary vertices found
+        // should never happen if the mesh is valid
+        return;
+    }
+
+    // ---------------------------------------------------------
+    // CONNECTIVITY PRE-PASS (fix for erosion fragmentation)
+    // ---------------------------------------------------------
+    // 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 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.has(e)) {
+                // a true boundary edge defines the outline - never split it
+                continue;
+            }
+
+            const v1 = mesh.edge_read_vertex1(e);
+            const v2 = mesh.edge_read_vertex2(e);
+
+            if (boundary_vertices.has(v1) && boundary_vertices.has(v2)) {
+                split_targets.push(e);
+            }
+        }
+
+        if (split_targets.length > 0) {
+            for (let i = 0; i < split_targets.length; i++) {
+                bt_edge_split(mesh, split_targets[i], 0.5);
+            }
+
+            island_faces = recompute_island_faces(faces);
+            collect_island_sets(island_faces);
+
+            if (boundary_vertices.size === 0) {
+                return;
+            }
+        }
+    }
+
+    // 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, 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.
+     * @type {Map<number, number>}
+     */
+    const vertex_boundary_distances = new Map();
+
+    // 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 and boundary.
+    function compute_field() {
+        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();
+
+    // 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 the chord really lies at the
+    // erode distance; only refine (split the longest edge) when it deviates. Already-accurate cuts
+    // (e.g. a plain quad's straight sides) are left coarse, so detail is added only where needed.
+    {
+        const fine = Math.max(erode_distance * 0.5, 0.1);
+        const fine_sq = fine * fine;
+        const tol = Math.max(erode_distance * 0.15, 0.04);
+        let rounds = 0;
+
+        const ca = new Float32Array(3), cb = new Float32Array(3), cc = new Float32Array(3);
+
+        // the two points where the threshold crosses the current face's edges
+        const cut_a = new Float32Array(3), cut_b = new Float32Array(3);
+
+        /** Does this point sit further than `tol` from the true erosion offset? */
+        function deviates(x, y, z) {
+            return Math.abs(segment3_point_distance_to_segments(boundary_segments, x, y, z) - erode_distance) > tol;
+        }
+
+        // reused across rounds: edges whose longest side should be split this round
+        const refine_targets = new Set();
+
+        while (rounds < 48) {
+            rounds++;
+
+            refine_targets.clear();
+
+            for (let i = 0; i < island_faces.length; i++) {
+                const f = island_faces[i];
+                if (!mesh.faces.is_allocated(f)) continue;
+
+                const la = mesh.face_read_loop(f);
+                const lb = mesh.loop_read_next(la);
+                const lc = mesh.loop_read_next(lb);
+                const v1 = mesh.loop_read_vertex(la);
+                const v2 = mesh.loop_read_vertex(lb);
+                const v3 = mesh.loop_read_vertex(lc);
+
+                const d1 = vertex_boundary_distances.get(v1);
+                const d2 = vertex_boundary_distances.get(v2);
+                const d3 = vertex_boundary_distances.get(v3);
+
+                const dmin = Math.min(d1, d2, d3);
+                const dmax = Math.max(d1, d2, d3);
+
+                // does the erode threshold pass through this face?
+                if (!(dmin < erode_distance && dmax > erode_distance)) continue;
+
+                mesh.vertex_read_coordinate(ca, 0, v1);
+                mesh.vertex_read_coordinate(cb, 0, v2);
+                mesh.vertex_read_coordinate(cc, 0, v3);
+
+                const e_ab = (ca[0] - cb[0]) ** 2 + (ca[1] - cb[1]) ** 2 + (ca[2] - cb[2]) ** 2;
+                const e_bc = (cb[0] - cc[0]) ** 2 + (cb[1] - cc[1]) ** 2 + (cb[2] - cc[2]) ** 2;
+                const e_ca = (cc[0] - ca[0]) ** 2 + (cc[1] - ca[1]) ** 2 + (cc[2] - ca[2]) ** 2;
+                const longest = Math.max(e_ab, e_bc, e_ca);
+
+                if (longest <= fine_sq) continue;
+
+                // the two cut points where the threshold crosses this face's edges
+                let crossings = 0;
+                // edge (v1,v2)
+                if ((d1 < erode_distance) !== (d2 < erode_distance)) {
+                    const t = (erode_distance - d1) / (d2 - d1);
+                    const c = crossings === 0 ? cut_a : cut_b;
+                    c[0] = ca[0] + t * (cb[0] - ca[0]); c[1] = ca[1] + t * (cb[1] - ca[1]); c[2] = ca[2] + t * (cb[2] - ca[2]); crossings++;
+                }
+                // edge (v2,v3)
+                if ((d2 < erode_distance) !== (d3 < erode_distance)) {
+                    const t = (erode_distance - d2) / (d3 - d2);
+                    const c = crossings === 0 ? cut_a : cut_b;
+                    c[0] = cb[0] + t * (cc[0] - cb[0]); c[1] = cb[1] + t * (cc[1] - cb[1]); c[2] = cb[2] + t * (cc[2] - cb[2]); crossings++;
+                }
+                // edge (v3,v1)
+                if ((d3 < erode_distance) !== (d1 < erode_distance)) {
+                    const t = (erode_distance - d3) / (d1 - d3);
+                    const c = crossings === 0 ? cut_a : cut_b;
+                    c[0] = cc[0] + t * (ca[0] - cc[0]); c[1] = cc[1] + t * (ca[1] - cc[1]); c[2] = cc[2] + t * (ca[2] - cc[2]); crossings++;
+                }
+
+                // A triangle's vertices give an even number of sign changes around its cycle, so the
+                // threshold crosses either no edges or exactly two - never one or three.
+                assert.ok(crossings === 0 || crossings === 2, 'expected 0 or 2 threshold crossings');
+
+                // Accuracy is judged at BOTH ends of the cut chord as well as at its middle. The chord's
+                // endpoints are the vertices the eroded outline is actually built from, and the distance
+                // field is only piecewise-linear along an edge (it kinks wherever the nearest boundary
+                // feature changes), so an endpoint can sit far off the true offset while the midpoint
+                // still reads correct - one end too deep and the other too shallow cancel out at the
+                // centre. Judging by the midpoint alone accepted those chords, and the misplaced
+                // endpoint survived into the navmesh as a visible kink. The midpoint is still checked
+                // too: a chord across a rounded corner can have both ends on the offset and bulge away
+                // from it in between.
+                if (crossings === 2
+                    && !deviates(cut_a[0], cut_a[1], cut_a[2])
+                    && !deviates(cut_b[0], cut_b[1], cut_b[2])
+                    && !deviates((cut_a[0] + cut_b[0]) * 0.5, (cut_a[1] + cut_b[1]) * 0.5, (cut_a[2] + cut_b[2]) * 0.5)) {
+                    // the straight cut here is already accurate - leave this face coarse
+                    continue;
+                }
+
+                const sl = (longest === e_ab) ? la : (longest === e_bc) ? lb : lc;
+                refine_targets.add(mesh.loop_read_edge(sl));
+            }
+
+            if (refine_targets.size === 0) break;
+
+            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);
+            collect_island_sets(island_faces);
+
+            compute_field();
+
+            if (mesh.faces.size > 200000) break;
+        }
+    }
+
+    // ---------------------------------------------------------
+    // 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).
+    // ---------------------------------------------------------
+
+    // 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".
+        let l_curr = mesh.face_read_loop(f);
+        const l_end = l_curr;
+        let all_dead = true;
+
+        do {
+            const v = mesh.loop_read_vertex(l_curr);
+            if ((vertex_boundary_distances.get(v) || 0) >= erode_distance) {
+                all_dead = false;
+            }
+            l_curr = mesh.loop_read_next(l_curr);
+        } while (l_curr !== l_end);
+
+        if (all_dead) {
+            // This face is slated for total deletion. Check whether we should rescue it by adding a peak
+            // vertex at the incenter.
+
+            // 1. Incenter (for a triangle; falls back to centroid for other n-gons).
+            bt_face_get_incenter(centroid, 0, mesh, f);
+
+            // 2. Incenter distance to boundary (min over this face's own boundary-crossing edges).
+            let min_dist = Infinity;
+            l_curr = mesh.face_read_loop(f);
+            do {
+                const e = mesh.loop_read_edge(l_curr);
+
+                const v1 = mesh.edge_read_vertex1(e);
+                const v2 = mesh.edge_read_vertex2(e);
+
+                if (island_vertices.has(v1) && island_vertices.has(v2)) {
+
+                    mesh.vertex_read_coordinate(scratch_v1, 0, v1);
+                    mesh.vertex_read_coordinate(scratch_v2, 0, v2);
+
+                    const d1 = vertex_boundary_distances.get(v1);
+                    const d2 = vertex_boundary_distances.get(v2);
+
+                    if (d1 < erode_distance || d2 < erode_distance) {
+                        // only consider edges that could cross the erosion threshold
+
+                        const d = line3_compute_segment_point_distance_eikonal(
+                            d1, d2,
+                            scratch_v1[0], scratch_v1[1], scratch_v1[2],
+                            scratch_v2[0], scratch_v2[1], scratch_v2[2],
+                            centroid[0], centroid[1], centroid[2]
+                        );
+
+                        if (d < min_dist) {
+                            min_dist = d;
+                        }
+                    }
+                }
+
+                l_curr = mesh.loop_read_next(l_curr);
+            } while (l_curr !== l_end);
+
+            // 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 incenter.
+                const new_vert = bt_face_poke(mesh, f, centroid[0], centroid[1], centroid[2]);
+
+                island_vertices.add(new_vert);
+                vertex_boundary_distances.set(new_vert, min_dist);
+
+                // 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 {
+                    island_edges.add(e_scan);
+
+                    const v1 = mesh.edge_read_vertex1(e_scan);
+                    const is_v1 = v1 === new_vert;
+
+                    // 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');
+                        assert.notEqual(v2, new_vert, 'edge vertex does not match new vertex');
+                    } else {
+                        assert.equal(v2, new_vert, 'edge vertex does not match new vertex');
+                        assert.notEqual(v1, new_vert, 'edge vertex does not match new vertex');
+                    }
+
+                    e_scan = is_v1 ? mesh.edge_read_v1_disk_next(e_scan) : mesh.edge_read_v2_disk_next(e_scan);
+                } while (e_scan !== e_first);
+            }
+        }
+    }
+
+    // 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) {
+
+        assert.equal(mesh.edges.is_allocated(e), true, 'edge is not allocated');
+
+        const v1 = mesh.edge_read_vertex1(e);
+        const v2 = mesh.edge_read_vertex2(e);
+
+        const d1 = vertex_boundary_distances.get(v1);
+        const d2 = vertex_boundary_distances.get(v2);
+
+        // 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) {
+            const t = clamp01(inverseLerp(d1, d2, erode_distance));
+            split_edges.push(e);
+            split_ts.push(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 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();
+
+    const EPSILON = 1e-17;
+
+    for (const [vertex, distance] of vertex_boundary_distances.entries()) {
+        if (distance >= erode_distance - EPSILON) {
+            // too far, survives
+            continue;
+        }
+
+        const e_first = mesh.vertex_read_edge(vertex);
+
+        if (e_first === NULL_POINTER) {
+            continue;
+        }
+
+        let e_curr = e_first;
+        do {
+            // 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;
+                do {
+                    faces_to_kill.add(mesh.loop_read_face(l_curr));
+                    l_curr = mesh.loop_read_radial_next(l_curr);
+                } while (l_curr !== l_first);
+            }
+
+            // 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);
+    }
+
+    for (const f of faces_to_kill) {
+        bt_face_kill(mesh, f);
+    }
+
+    // Cleanup floating vertices and edges.
+    if (faces_to_kill.size > 0) {
+        bt_mesh_cleanup_faceless_references(mesh);
+    }
+}