@woosh/meep-engine 3.57.0 → 3.58.0

package/src/core/geom/3d/line/line3_compute_segment_closest_point_to_aabb3_t.d.ts

@@ -2,7 +2,7 @@
  * Parameter `t ∈ [0,1]` of the point on the segment `p0 → p1` nearest to an
  * axis-aligned box. The closest segment point is `p0 + t·(p1 − p0)`; the closest
  * box point is that point clamped per-axis into the box. Sibling of
- * {@link line3_compute_segment_nearest_point_to_point_t} (segment-vs-point).
+ * {@link line3_compute_segment_closest_point_t} (segment-vs-point).
  *
  * Exact and O(1). `g(t) = distanceSqr(P(t), box)` is convex and — for an AABB —
  * piecewise-quadratic, with pieces meeting only where `P(t)` crosses one of the

package/src/core/geom/3d/line/line3_compute_segment_closest_point_to_aabb3_t.js

@@ -41,7 +41,7 @@ function _consider() {
  * Parameter `t ∈ [0,1]` of the point on the segment `p0 → p1` nearest to an
  * axis-aligned box. The closest segment point is `p0 + t·(p1 − p0)`; the closest
  * box point is that point clamped per-axis into the box. Sibling of
- * {@link line3_compute_segment_nearest_point_to_point_t} (segment-vs-point).
+ * {@link line3_compute_segment_closest_point_t} (segment-vs-point).
  *
  * Exact and O(1). `g(t) = distanceSqr(P(t), box)` is convex and — for an AABB —
  * piecewise-quadratic, with pieces meeting only where `P(t)` crosses one of the

package/src/core/geom/3d/quaternion/quat3_to_matrix3.d.ts

@@ -19,10 +19,10 @@
  *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
  *
  * Computing M(q) once and reusing across many vectors is cheaper
- * than calling {@link v3_quat3_apply} per vector when the same
+ * than calling {@link v3_quaternion_apply} per vector when the same
  * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
  * corners; box-vs-triangle clips an incident face). For one-shot
- * rotation use {@link v3_quat3_apply} directly.
+ * rotation use {@link v3_quaternion_apply} directly.
  *
  * To rotate a world-space vector `v` into the local frame via the
  * matrix form, the standard `R · v` (rotate local → world) requires
@@ -32,7 +32,7 @@
  *              + out[off + 3 + i] * v[1]
  *              + out[off + 6 + i] * v[2]
  *
- * — equivalent to {@link v3_quat3_apply}(v, q).
+ * — equivalent to {@link v3_quaternion_apply}(v, q).
  *
  * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
  * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`

package/src/core/geom/3d/quaternion/quat3_to_matrix3.js

@@ -19,10 +19,10 @@
  *   project_onto(v) = out[off+0..2] · v        // ← local-X extent
  *
  * Computing M(q) once and reusing across many vectors is cheaper
- * than calling {@link v3_quat3_apply} per vector when the same
+ * than calling {@link v3_quaternion_apply} per vector when the same
  * orientation rotates ≥ 4 vectors (box-vs-box SAT projects 8
  * corners; box-vs-triangle clips an incident face). For one-shot
- * rotation use {@link v3_quat3_apply} directly.
+ * rotation use {@link v3_quaternion_apply} directly.
  *
  * To rotate a world-space vector `v` into the local frame via the
  * matrix form, the standard `R · v` (rotate local → world) requires
@@ -32,7 +32,7 @@
  *              + out[off + 3 + i] * v[1]
  *              + out[off + 6 + i] * v[2]
  *
- * — equivalent to {@link v3_quat3_apply}(v, q).
+ * — equivalent to {@link v3_quaternion_apply}(v, q).
  *
  * Sign convention: `(qx, qy, qz, qw)` — `w` last, matching
  * {@link Quaternion} and the rest of the `core/geom/3d/quaternion/`

package/src/core/geom/3d/shape/HeightMapShape3D.js

@@ -3,7 +3,7 @@ import { hash_mix2 } from "../../../math/hash/hash_mix2.js";
 import { assert } from "../../../assert.js";
 import { clamp } from "../../../math/clamp.js";
 import { clamp_index } from "../../../math/clamp_index.js";
-import { optional_equality } from "../../../model/object/optional_equality.js";
+import { objectsEqual } from "../../../function/objectsEqual.js";
 import { optional_hash } from "../../../model/object/optional_hash.js";
 import { tri3_raycast } from "../triangle/tri3_raycast.js";
 import { v3_cross } from "../../vec3/v3_cross.js";
@@ -984,7 +984,7 @@ export class HeightMapShape3D extends AbstractShape3D {
         if (!this.size.equals(other.size)) return false;
         if (this.tessellation !== other.tessellation) return false;
 
-        return optional_equality(this.sampler, other.sampler);
+        return objectsEqual(this.sampler, other.sampler);
     }
 
     hash() {

package/src/core/geom/3d/shape/MeshShape3D.d.ts

@@ -20,7 +20,7 @@
  *      traversal short-circuits cleanly when the query point is far
  *      from the mesh.
  *
- * Construct via {@link shape_mesh_from_geometry} rather than `new
+ * Construct via {@link shape3_mesh_from_geometry} rather than `new
  * MeshShape3D()` directly — the factory compacts the tet mesh, builds
  * the BVH, and caches the bbox / volume / surface area.
  *
@@ -192,7 +192,7 @@ export class MeshShape3D extends AbstractShape3D {
     /**
      * Refresh the cached bounding box, volume, surface area, and the lazy
      * raycast BLAS from the current `positions` / `indices` / `tet_mesh`.
-     * Called by {@link shape_mesh_from_geometry} at construction; call again
+     * Called by {@link shape3_mesh_from_geometry} at construction; call again
      * after mutating the underlying data so every cached derivative — the
      * raycast acceleration structure included — is rebuilt against the new
      * surface rather than silently serving stale results.

package/src/core/geom/3d/shape/MeshShape3D.js

@@ -36,7 +36,7 @@ const MESH_QUERY_OUT = [0, 0, 0, 0];
  *      traversal short-circuits cleanly when the query point is far
  *      from the mesh.
  *
- * Construct via {@link shape_mesh_from_geometry} rather than `new
+ * Construct via {@link shape3_mesh_from_geometry} rather than `new
  * MeshShape3D()` directly — the factory compacts the tet mesh, builds
  * the BVH, and caches the bbox / volume / surface area.
  *
@@ -309,7 +309,7 @@ export class MeshShape3D extends AbstractShape3D {
     /**
      * Refresh the cached bounding box, volume, surface area, and the lazy
      * raycast BLAS from the current `positions` / `indices` / `tet_mesh`.
-     * Called by {@link shape_mesh_from_geometry} at construction; call again
+     * Called by {@link shape3_mesh_from_geometry} at construction; call again
      * after mutating the underlying data so every cached derivative — the
      * raycast acceleration structure included — is rebuilt against the new
      * surface rather than silently serving stale results.

package/src/core/geom/3d/shape/PosedShape3D.js

@@ -153,9 +153,9 @@ export class PosedShape3D extends AbstractShape3D {
         // Inline q·v·q* math: PosedShape3D.support is the hottest GJK call
         // (twice per iteration of the body-level fallback, once per
         // triangle for concave dispatch). V8 declines to inline
-        // v3_quat3_apply at 9-arg call sites, so the math is repeated
+        // v3_quaternion_apply at 9-arg call sites, so the math is repeated
         // inline here at the cost of ~7 extra lines per direction.
-        // See core/geom/vec3/v3_quat3_apply.js for the canonical form
+        // See core/geom/vec3/v3_quaternion_apply.js for the canonical form
         // — this is a literal expansion of it.
         const dx = direction[direction_offset];
         const dy = direction[direction_offset + 1];

package/src/core/geom/3d/sphere/sphere_matrix4_transform.d.ts

@@ -5,11 +5,4 @@
  * @param {number[]|Float32Array} mat4
  */
 export function sphere_matrix4_transform(result: number[] | Float32Array, sphere: number[] | Float32Array, mat4: number[] | Float32Array): void;
-/**
- *
- * @param {number[]|Float32Array} result
- * @param {number[]|Float32Array} sphere
- * @param {number[]|Float32Array} mat4
- */
-export function sphere_matrix4_project(result: number[] | Float32Array, sphere: number[] | Float32Array, mat4: number[] | Float32Array): void;
 //# sourceMappingURL=sphere_matrix4_transform.d.ts.map

package/src/core/geom/3d/sphere/sphere_matrix4_transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sphere_matrix4_transform.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/sphere/sphere_matrix4_transform.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,iDAJW,MAAM,EAAE,GAAC,YAAY,UACrB,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,EAAE,GAAC,YAAY,QAqB/B;AAzBD;;;;;GAKG;AACH,+CAJW,MAAM,EAAE,GAAC,YAAY,UACrB,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,EAAE,GAAC,YAAY,QAqB/B"}
+{"version":3,"file":"sphere_matrix4_transform.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/sphere/sphere_matrix4_transform.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,iDAJW,MAAM,EAAE,GAAC,YAAY,UACrB,MAAM,EAAE,GAAC,YAAY,QACrB,MAAM,EAAE,GAAC,YAAY,QAqB/B"}

package/src/core/geom/3d/sphere/sphere_matrix4_transform.js

@@ -26,7 +26,3 @@ export function sphere_matrix4_transform(
     result[3] = sphere[3] * max_scale;
 
 }
-/**
- * @deprecated Renamed to {@link sphere_matrix4_transform} ("project" was a misnomer; it transforms centre + radius).
- */
-export const sphere_matrix4_project = sphere_matrix4_transform;

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_compute_tet_quality.d.ts

@@ -2,7 +2,7 @@
  * Mesh-form wrapper for {@link tetrahedron_compute_quality}: fetches the 4
  * vertex IDs of `tet` and forwards to the indexed primitive.
  *
- * Sibling of {@link compute_tetrahedron_volume}; same convention (the
+ * Sibling of {@link tetrahedral_mesh_compute_tet_volume}; same convention (the
  * `compute_*` prefix marks the mesh-bound form, the `tetrahedron_compute_*`
  * prefix marks the indexed primitive).
  *

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_compute_tet_quality.js

@@ -4,7 +4,7 @@ import { tetrahedron_compute_quality } from "./tetrahedron_compute_quality.js";
  * Mesh-form wrapper for {@link tetrahedron_compute_quality}: fetches the 4
  * vertex IDs of `tet` and forwards to the indexed primitive.
  *
- * Sibling of {@link compute_tetrahedron_volume}; same convention (the
+ * Sibling of {@link tetrahedral_mesh_compute_tet_volume}; same convention (the
  * `compute_*` prefix marks the mesh-bound form, the `tetrahedron_compute_*`
  * prefix marks the indexed primitive).
  *

package/src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.d.ts

@@ -18,7 +18,7 @@
  *
  * Indexed form (not mesh-bound) so callers can score hypothetical tets
  * during a flip-candidate search without committing the flip first. The
- * existing mesh-form wrapper {@link compute_tetrahedron_quality} fetches
+ * existing mesh-form wrapper {@link tetrahedral_mesh_compute_tet_quality} fetches
  * the four vertex IDs and forwards here.
  *
  * @param {ArrayLike<number>} points flat (x,y,z) positions

package/src/core/geom/3d/tetrahedra/tetrahedron_compute_quality.js

@@ -24,7 +24,7 @@ const circ_scratch = new Float64Array(4);
  *
  * Indexed form (not mesh-bound) so callers can score hypothetical tets
  * during a flip-candidate search without committing the flip first. The
- * existing mesh-form wrapper {@link compute_tetrahedron_quality} fetches
+ * existing mesh-form wrapper {@link tetrahedral_mesh_compute_tet_quality} fetches
  * the four vertex IDs and forwards here.
  *
  * @param {ArrayLike<number>} points flat (x,y,z) positions

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

@@ -7,7 +7,7 @@
  * @param {BinaryTopology} mesh
  * @param {number} face0_id
  * @param {number} face1_id
- * @see bt_merge_verts_by_distance
+ * @see bt_merge_vertices_by_distance
  */
 export function bt_mesh_face_decouple(mesh: BinaryTopology, face0_id: number, face1_id: number): void;
 //# sourceMappingURL=bt_mesh_face_decouple.d.ts.map

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

@@ -15,7 +15,7 @@ import { bt_edge_create } from "./edge/bt_edge_create.js";
  * @param {BinaryTopology} mesh
  * @param {number} face0_id
  * @param {number} face1_id
- * @see bt_merge_verts_by_distance
+ * @see bt_merge_vertices_by_distance
  */
 export function bt_mesh_face_decouple(
     mesh,

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

@@ -9,7 +9,7 @@
  * Degenerate edges (v1 === v2) are left alone; callers that want those removed should run a
  * dedicated pass.
  *
- * Typically used after {@link bt_merge_verts_by_distance}, which re-points vertex references but
+ * Typically used after {@link bt_merge_vertices_by_distance}, which re-points vertex references but
  * can leave behind multiple edges sharing the same endpoint pair.
  *
  * @param {BinaryTopology} mesh

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

@@ -15,7 +15,7 @@ import { bt_kill_only_edge } from "./bt_kill_only_edge.js";
  * Degenerate edges (v1 === v2) are left alone; callers that want those removed should run a
  * dedicated pass.
  *
- * Typically used after {@link bt_merge_verts_by_distance}, which re-points vertex references but
+ * Typically used after {@link bt_merge_vertices_by_distance}, which re-points vertex references but
  * can leave behind multiple edges sharing the same endpoint pair.
  *
  * @param {BinaryTopology} mesh

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

@@ -5,7 +5,7 @@
  * edge, two longer ones) loses the short edge and its face here, and the
  * other two edges are left orphan for the standard cleanup pass to remove.
  *
- * The intended pre-pass before {@link bt_merge_verts_by_distance}. The merge
+ * The intended pre-pass before {@link bt_merge_vertices_by_distance}. The merge
  * uses `bt_vertex_replace` internally, which produces a self-loop edge if
  * the two vertices it's collapsing are directly edge-connected — and
  * self-loops corrupt the disk cycle in ways that hang the downstream
@@ -27,7 +27,7 @@
  *
  * @param {BinaryTopology} mesh
  * @param {number} [max_distance] inclusive endpoint distance; defaults match
- *                                {@link bt_merge_verts_by_distance}
+ *                                {@link bt_merge_vertices_by_distance}
  * @returns {number} number of edges killed
  */
 export function bt_mesh_kill_short_edges(mesh: BinaryTopology, max_distance?: number): number;

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

@@ -15,7 +15,7 @@ const scratch_b = [0, 0, 0];
  * edge, two longer ones) loses the short edge and its face here, and the
  * other two edges are left orphan for the standard cleanup pass to remove.
  *
- * The intended pre-pass before {@link bt_merge_verts_by_distance}. The merge
+ * The intended pre-pass before {@link bt_merge_vertices_by_distance}. The merge
  * uses `bt_vertex_replace` internally, which produces a self-loop edge if
  * the two vertices it's collapsing are directly edge-connected — and
  * self-loops corrupt the disk cycle in ways that hang the downstream
@@ -37,7 +37,7 @@ const scratch_b = [0, 0, 0];
  *
  * @param {BinaryTopology} mesh
  * @param {number} [max_distance] inclusive endpoint distance; defaults match
- *                                {@link bt_merge_verts_by_distance}
+ *                                {@link bt_merge_vertices_by_distance}
  * @returns {number} number of edges killed
  */
 export function bt_mesh_kill_short_edges(mesh, max_distance = 0.0001) {

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

@@ -12,18 +12,4 @@
  * @returns {number} vertex ID of the new center vertex, NULL_POINTER if face is degenerate or does not exist.
  */
 export function bt_face_poke(mesh: BinaryTopology, face_id: number, x: number, y: number, z: number): number;
-/**
- * Pokes a face by adding a vertex at the specified coordinates and fan-tessellating the face.
- * Reuses bt_edge_create to handle the complex vertex-disk linking automatically.
- *
- * Coordinates of the new vertex must be co-planar with the face.
- *
- * @param {BinaryTopology} mesh
- * @param {number} face_id
- * @param {number} x
- * @param {number} y
- * @param {number} z
- * @returns {number} vertex ID of the new center vertex, NULL_POINTER if face is degenerate or does not exist.
- */
-export function bt_mesh_face_poke(mesh: BinaryTopology, face_id: number, x: number, y: number, z: number): number;
 //# sourceMappingURL=bt_face_poke.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"bt_face_poke.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,4DANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAuGlB;AAlHD;;;;;;;;;;;;GAYG;AACH,iEANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAuGlB"}
+{"version":3,"file":"bt_face_poke.d.ts","sourceRoot":"","sources":["../../../../../../../../../../src/core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,4DANW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,GACJ,MAAM,CAuGlB"}

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

@@ -120,8 +120,3 @@ export function bt_face_poke(
 
     return v_center;
 }
-
-/**
- * @deprecated Renamed to {@link bt_face_poke} (operates on a single face, not the whole mesh).
- */
-export const bt_mesh_face_poke = bt_face_poke;

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

@@ -1,151 +1,151 @@
-import { NULL_POINTER } from "../../BinaryTopology.js";
-import { bt_disk_edge_add } from "../bt_disk_edge_add.js";
-import { bt_disk_edge_remove } from "../bt_disk_edge_remove.js";
-
-/**
- * The victim's incident edges, collected before its disk cycles are mutated.
- *
- * Grown on demand, the way bt_mesh_append grows its corner buffer. It used to be a fixed 1024
- * bounded only by an assert, which the consumer strips: past 1024 the typed-array write is
- * silently dropped while the count keeps rising, so the second loop reads `undefined`,
- * `element_address(undefined)` is NaN, and `DataView.getUint32(NaN)` coerces the offset to 0 —
- * every overflow iteration then reads and rewrites the head of the edge pool and leaves the real
- * edges dangling on a killed vertex. Silent topology corruption in the pass whose output is baked
- * into a shipped .vgeo, and bt_mesh_simplify has no valence cap to keep a greedy collapse in a
- * flat region from funnelling that much valence into one star vertex.
- *
- * @type {Uint32Array}
- */
-let scratch_edges = new Uint32Array(1024);
-
-/**
- * Patch mesh structure to make all loops/edges/faces point to this new replacement vertex instead of the victim.
- * This effectively removes any usage of the victim from the mesh enabling us to safely remove it.
- *
- * Note: both victim and replacement vertices must be part of the mesh.
- * Note: does not actually remove the victim vertex from the mesh, only links that point to it that will now point to `replacement` instead.
- * Note: may create degenerate edges if victim and replacement are a part of the same edge originally.
- * @param {BinaryTopology} mesh
- * @param {number} victim
- * @param {number} replacement
- */
-export function bt_vertex_replace(
-    mesh,
-    victim,
-    replacement
-) {
-
-    if (victim === replacement) {
-        // special case
-        return;
-    }
-
-    // 1. Traverse and collect all edges attached to the victim vertex.
-    // We collect them into an array first because we will be mutating their disk cycles
-    // during the loop, which would break an inline traversal.
-    let edges_to_move_count = 0;
-    let curr_e = mesh.vertex_read_edge(victim);
-
-    if (curr_e !== NULL_POINTER) {
-        let start_e = curr_e;
-        do {
-
-            if (edges_to_move_count === scratch_edges.length) {
-                const grown = new Uint32Array(scratch_edges.length * 2);
-
-                grown.set(scratch_edges);
-
-                scratch_edges = grown;
-            }
-
-            scratch_edges[edges_to_move_count++] = curr_e;
-
-            // Move to the next edge in the victim's disk cycle
-            if (mesh.edge_read_vertex1(curr_e) === victim) {
-                curr_e = mesh.edge_read_v1_disk_next(curr_e);
-            } else {
-                curr_e = mesh.edge_read_v2_disk_next(curr_e);
-            }
-        } while (curr_e !== start_e && curr_e !== NULL_POINTER);
-    }
-
-    // 2. Unlink the victim vertex by clearing its edge pointer.
-    mesh.vertex_write_edge(victim, NULL_POINTER);
-
-    // 3. Process each edge: update loops, update vertices, and insert into replacement's disk cycle.
-    for (let i = 0; i < edges_to_move_count; i++) {
-        const e = scratch_edges[i];
-
-        // --- Update Loops ---
-        // Loops are corner representations; we must check the radial cycle of loops around this edge
-        let curr_l = mesh.edge_read_loop(e);
-        if (curr_l !== NULL_POINTER) {
-            let start_l = curr_l;
-            do {
-                if (mesh.loop_read_vertex(curr_l) === victim) {
-                    mesh.loop_write_vertex(curr_l, replacement);
-                }
-                curr_l = mesh.loop_read_radial_next(curr_l);
-            } while (curr_l !== start_l && curr_l !== NULL_POINTER);
-        }
-
-        // --- Update Edge Vertices ---
-        // Three cases. Per the disk-cycle convention (see BinaryTopology.js
-        // __edge_pool comment), every edge occupies exactly one slot in each of
-        // its endpoints' cycles -- for self-loops that means one slot total, in
-        // the v1 slot of the unique endpoint's cycle.
-        //
-        //   (a) Normal: e was attached to victim only. Move the victim endpoint
-        //       onto replacement and splice e into replacement's cycle.
-        //   (b) Direct parallel: e connects victim and replacement. Becomes a
-        //       self-loop on replacement. e is already in replacement's disk on
-        //       the OTHER side; remove it there, update the vertex, then re-add
-        //       on the v1 side per convention.
-        //   (c) Self-loop on victim: e was a self-loop on victim. Becomes a
-        //       self-loop on replacement. Update BOTH vertex fields (the legacy
-        //       single-write path would have left vertex2 = victim, dangling
-        //       after bt_vert_kill(victim) runs upstream), then add to
-        //       replacement's cycle from scratch.
-        const e_v1 = mesh.edge_read_vertex1(e);
-        const e_v2 = mesh.edge_read_vertex2(e);
-        const is_v1 = e_v1 === victim;
-        const other_endpoint = is_v1 ? e_v2 : e_v1;
-
-        if (other_endpoint === victim) {
-            // case (c): self-loop on victim -> self-loop on replacement
-            mesh.edge_write_vertex1(e, replacement);
-            mesh.edge_write_vertex2(e, replacement);
-            bt_disk_edge_add(mesh, e, replacement);
-            continue;
-        }
-
-        if (other_endpoint === replacement) {
-            // case (b): direct parallel becoming a self-loop on replacement.
-            // e is currently in replacement's disk on the side OPPOSITE the
-            // victim side; remove it there before rewriting the vertex slot.
-            bt_disk_edge_remove(mesh, e, replacement);
-
-            if (is_v1) {
-                mesh.edge_write_vertex1(e, replacement);
-            } else {
-                mesh.edge_write_vertex2(e, replacement);
-            }
-
-            // Now e is a self-loop; bt_disk_edge_add will write the v1 slot
-            // per the convention.
-            bt_disk_edge_add(mesh, e, replacement);
-            continue;
-        }
-
-        // case (a): normal path. Move the victim endpoint onto replacement and
-        // splice e into replacement's cycle.
-        if (is_v1) {
-            mesh.edge_write_vertex1(e, replacement);
-        } else {
-            mesh.edge_write_vertex2(e, replacement);
-        }
-
-        // --- Insert Edge into Replacement's Disk Cycle ---
-        bt_disk_edge_add(mesh, e, replacement);
-    }
-}
+import { NULL_POINTER } from "../../BinaryTopology.js";
+import { bt_disk_edge_add } from "../bt_disk_edge_add.js";
+import { bt_disk_edge_remove } from "../bt_disk_edge_remove.js";
+
+/**
+ * The victim's incident edges, collected before its disk cycles are mutated.
+ *
+ * Grown on demand, the way bt_mesh_append grows its corner buffer. It used to be a fixed 1024
+ * bounded only by an assert, which the consumer strips: past 1024 the typed-array write is
+ * silently dropped while the count keeps rising, so the second loop reads `undefined`,
+ * `element_address(undefined)` is NaN, and `DataView.getUint32(NaN)` coerces the offset to 0 —
+ * every overflow iteration then reads and rewrites the head of the edge pool and leaves the real
+ * edges dangling on a killed vertex. Silent topology corruption in the pass whose output is baked
+ * into a shipped .vgeo, and bt_mesh_simplify has no valence cap to keep a greedy collapse in a
+ * flat region from funnelling that much valence into one star vertex.
+ *
+ * @type {Uint32Array}
+ */
+let scratch_edges = new Uint32Array(1024);
+
+/**
+ * Patch mesh structure to make all loops/edges/faces point to this new replacement vertex instead of the victim.
+ * This effectively removes any usage of the victim from the mesh enabling us to safely remove it.
+ *
+ * Note: both victim and replacement vertices must be part of the mesh.
+ * Note: does not actually remove the victim vertex from the mesh, only links that point to it that will now point to `replacement` instead.
+ * Note: may create degenerate edges if victim and replacement are a part of the same edge originally.
+ * @param {BinaryTopology} mesh
+ * @param {number} victim
+ * @param {number} replacement
+ */
+export function bt_vertex_replace(
+    mesh,
+    victim,
+    replacement
+) {
+
+    if (victim === replacement) {
+        // special case
+        return;
+    }
+
+    // 1. Traverse and collect all edges attached to the victim vertex.
+    // We collect them into an array first because we will be mutating their disk cycles
+    // during the loop, which would break an inline traversal.
+    let edges_to_move_count = 0;
+    let curr_e = mesh.vertex_read_edge(victim);
+
+    if (curr_e !== NULL_POINTER) {
+        let start_e = curr_e;
+        do {
+
+            if (edges_to_move_count === scratch_edges.length) {
+                const grown = new Uint32Array(scratch_edges.length * 2);
+
+                grown.set(scratch_edges);
+
+                scratch_edges = grown;
+            }
+
+            scratch_edges[edges_to_move_count++] = curr_e;
+
+            // Move to the next edge in the victim's disk cycle
+            if (mesh.edge_read_vertex1(curr_e) === victim) {
+                curr_e = mesh.edge_read_v1_disk_next(curr_e);
+            } else {
+                curr_e = mesh.edge_read_v2_disk_next(curr_e);
+            }
+        } while (curr_e !== start_e && curr_e !== NULL_POINTER);
+    }
+
+    // 2. Unlink the victim vertex by clearing its edge pointer.
+    mesh.vertex_write_edge(victim, NULL_POINTER);
+
+    // 3. Process each edge: update loops, update vertices, and insert into replacement's disk cycle.
+    for (let i = 0; i < edges_to_move_count; i++) {
+        const e = scratch_edges[i];
+
+        // --- Update Loops ---
+        // Loops are corner representations; we must check the radial cycle of loops around this edge
+        let curr_l = mesh.edge_read_loop(e);
+        if (curr_l !== NULL_POINTER) {
+            let start_l = curr_l;
+            do {
+                if (mesh.loop_read_vertex(curr_l) === victim) {
+                    mesh.loop_write_vertex(curr_l, replacement);
+                }
+                curr_l = mesh.loop_read_radial_next(curr_l);
+            } while (curr_l !== start_l && curr_l !== NULL_POINTER);
+        }
+
+        // --- Update Edge Vertices ---
+        // Three cases. Per the disk-cycle convention (see BinaryTopology.js
+        // __edge_pool comment), every edge occupies exactly one slot in each of
+        // its endpoints' cycles -- for self-loops that means one slot total, in
+        // the v1 slot of the unique endpoint's cycle.
+        //
+        //   (a) Normal: e was attached to victim only. Move the victim endpoint
+        //       onto replacement and splice e into replacement's cycle.
+        //   (b) Direct parallel: e connects victim and replacement. Becomes a
+        //       self-loop on replacement. e is already in replacement's disk on
+        //       the OTHER side; remove it there, update the vertex, then re-add
+        //       on the v1 side per convention.
+        //   (c) Self-loop on victim: e was a self-loop on victim. Becomes a
+        //       self-loop on replacement. Update BOTH vertex fields (the legacy
+        //       single-write path would have left vertex2 = victim, dangling
+        //       after bt_vertex_kill(victim) runs upstream), then add to
+        //       replacement's cycle from scratch.
+        const e_v1 = mesh.edge_read_vertex1(e);
+        const e_v2 = mesh.edge_read_vertex2(e);
+        const is_v1 = e_v1 === victim;
+        const other_endpoint = is_v1 ? e_v2 : e_v1;
+
+        if (other_endpoint === victim) {
+            // case (c): self-loop on victim -> self-loop on replacement
+            mesh.edge_write_vertex1(e, replacement);
+            mesh.edge_write_vertex2(e, replacement);
+            bt_disk_edge_add(mesh, e, replacement);
+            continue;
+        }
+
+        if (other_endpoint === replacement) {
+            // case (b): direct parallel becoming a self-loop on replacement.
+            // e is currently in replacement's disk on the side OPPOSITE the
+            // victim side; remove it there before rewriting the vertex slot.
+            bt_disk_edge_remove(mesh, e, replacement);
+
+            if (is_v1) {
+                mesh.edge_write_vertex1(e, replacement);
+            } else {
+                mesh.edge_write_vertex2(e, replacement);
+            }
+
+            // Now e is a self-loop; bt_disk_edge_add will write the v1 slot
+            // per the convention.
+            bt_disk_edge_add(mesh, e, replacement);
+            continue;
+        }
+
+        // case (a): normal path. Move the victim endpoint onto replacement and
+        // splice e into replacement's cycle.
+        if (is_v1) {
+            mesh.edge_write_vertex1(e, replacement);
+        } else {
+            mesh.edge_write_vertex2(e, replacement);
+        }
+
+        // --- Insert Edge into Replacement's Disk Cycle ---
+        bt_disk_edge_add(mesh, e, replacement);
+    }
+}

package/src/core/geom/3d/topology/struct/binary/query/bt_edge_collapse_fold_limit.js

@@ -44,7 +44,7 @@ const scratch_at_to = new Float32Array(3);
 /**
  * Unnormalised triangle normal `(b - a) x (c - a)`, written into `out`.
  *
- * Deliberately not `v3_compute_triangle_normal`: this needs the raw cross product, because a
+ * Deliberately not `tri3_compute_normal`: this needs the raw cross product, because a
  * vanishing magnitude is what says the result is a zero-area sliver and the `dot <= 0` test below is
  * what rejects it. Normalising discards that magnitude, and that function answers `(0, 1, 0)` for a
  * degenerate triangle -- which would let a collapse-to-sliver walk straight past the guard.