@woosh/meep-engine 2.139.0 → 2.140.0

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

@@ -0,0 +1,95 @@
+/**
+ * Buffer-backed flyweight triangle shape.
+ *
+ * Vertex data is NOT stored on the instance — instead the triangle binds
+ * to a region of an external Float64 buffer via {@link bind}, reading
+ * 9 consecutive floats (vA.xyz, vB.xyz, vC.xyz) at the bound offset.
+ *
+ * Pattern: the narrowphase keeps one persistent `Triangle3D` per side of
+ * a contact pair and rebinds its offset while iterating decomposed
+ * triangles from a non-convex shape's enumerator. Zero allocations per
+ * iteration step — the cost of "another triangle" is a single integer
+ * offset change.
+ *
+ * The shape is convex (a triangle is the canonical 2-simplex in 3D, and
+ * GJK handles 2-simplices natively). It's degenerate in the sense that
+ * `volume = 0` and `contains_point` is always false — a triangle is a
+ * 2D surface in 3D space, no interior.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Triangle3D extends AbstractShape3D {
+    /**
+     * Convenience constructor for tests and one-off triangles.
+     * Allocates a private 9-float buffer; for hot paths use {@link bind}
+     * against a shared buffer instead.
+     *
+     * @param {number} ax
+     * @param {number} ay
+     * @param {number} az
+     * @param {number} bx
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} cx
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {Triangle3D}
+     */
+    static from(ax: number, ay: number, az: number, bx: number, by: number, bz: number, cx: number, cy: number, cz: number): Triangle3D;
+    /**
+     * External buffer holding vertex data.
+     * @type {Float64Array | null}
+     */
+    buffer: Float64Array | null;
+    /**
+     * Float-index of vA.x in {@link buffer}. The other 8 floats
+     * (vA.yz, vB.xyz, vC.xyz) follow consecutively.
+     * @type {number}
+     */
+    offset: number;
+    /**
+     * Bind this triangle to a region of an external buffer. Reads 9
+     * consecutive floats starting at `offset`.
+     *
+     * @param {Float64Array} buffer
+     * @param {number} offset float-index of vA.x in the buffer
+     * @returns {Triangle3D} this (for chaining)
+     */
+    bind(buffer: Float64Array, offset: number): Triangle3D;
+    support(result: any, result_offset: any, direction_x: any, direction_y: any, direction_z: any): void;
+    compute_bounding_box(result: any): void;
+    /**
+     * A triangle has zero interior volume.
+     */
+    contains_point(_point: any): boolean;
+    /**
+     * Signed distance has a well-defined sign relative to the triangle's
+     * face plane: positive on the side that the face normal points to
+     * (normal = (B-A) × (C-A), CCW convention), negative on the other.
+     *
+     * Magnitude is the true point-to-triangle distance (handles vertex,
+     * edge, and face Voronoi regions correctly via
+     * {@link computeTriangleClosestPointToPointBarycentric}).
+     */
+    signed_distance_at_point(point: any): number;
+    nearest_point_on_surface(result: any, reference: any): void;
+    /**
+     * Uniform random barycentric sample within the triangle.
+     * Triangles have no interior, so the sample lies on the surface.
+     */
+    sample_random_point_in_volume(result: any, result_offset: any, random: any): void;
+    /**
+     * @param {Triangle3D} other
+     * @returns {boolean}
+     */
+    equals(other: Triangle3D): boolean;
+    /**
+     * Fast type-check marker.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isTriangle3D: boolean;
+}
+import { AbstractShape3D } from "./AbstractShape3D.js";
+//# sourceMappingURL=Triangle3D.d.ts.map

package/src/core/geom/3d/shape/Triangle3D.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Triangle3D.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/Triangle3D.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IAmCI;;;;;;;;;;;;;;;OAeG;IACH,gBAXW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,UAAU,CAWtB;IAxDG;;;OAGG;IACH,QAFU,YAAY,GAAG,IAAI,CAEX;IAElB;;;;OAIG;IACH,QAFU,MAAM,CAED;IAGnB;;;;;;;OAOG;IACH,aAJW,YAAY,UACZ,MAAM,GACJ,UAAU,CAStB;IA6BD,qGAyBC;IAED,wCAeC;IAED;;OAEG;IACH,qCAEC;IAED;;;;;;;;OAQG;IACH,6CA4CC;IAED,4DAwBC;IAED;;;OAGG;IACH,kFAsBC;IAwBD;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAenB;IAgBL;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;CAPhC;gCA1S+B,sBAAsB"}

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

@@ -0,0 +1,318 @@
+import { assert } from "../../../assert.js";
+import { computeHashFloat } from "../../../primitives/numbers/computeHashFloat.js";
+import { v3_length } from "../../vec3/v3_length.js";
+import { computeTriangleClosestPointToPointBarycentric } from "../triangle/computeTriangleClosestPointToPointBarycentric.js";
+import { AbstractShape3D } from "./AbstractShape3D.js";
+
+/**
+ * Buffer-backed flyweight triangle shape.
+ *
+ * Vertex data is NOT stored on the instance — instead the triangle binds
+ * to a region of an external Float64 buffer via {@link bind}, reading
+ * 9 consecutive floats (vA.xyz, vB.xyz, vC.xyz) at the bound offset.
+ *
+ * Pattern: the narrowphase keeps one persistent `Triangle3D` per side of
+ * a contact pair and rebinds its offset while iterating decomposed
+ * triangles from a non-convex shape's enumerator. Zero allocations per
+ * iteration step — the cost of "another triangle" is a single integer
+ * offset change.
+ *
+ * The shape is convex (a triangle is the canonical 2-simplex in 3D, and
+ * GJK handles 2-simplices natively). It's degenerate in the sense that
+ * `volume = 0` and `contains_point` is always false — a triangle is a
+ * 2D surface in 3D space, no interior.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Triangle3D extends AbstractShape3D {
+    constructor() {
+        super();
+
+        /**
+         * External buffer holding vertex data.
+         * @type {Float64Array | null}
+         */
+        this.buffer = null;
+
+        /**
+         * Float-index of vA.x in {@link buffer}. The other 8 floats
+         * (vA.yz, vB.xyz, vC.xyz) follow consecutively.
+         * @type {number}
+         */
+        this.offset = 0;
+    }
+
+    /**
+     * Bind this triangle to a region of an external buffer. Reads 9
+     * consecutive floats starting at `offset`.
+     *
+     * @param {Float64Array} buffer
+     * @param {number} offset float-index of vA.x in the buffer
+     * @returns {Triangle3D} this (for chaining)
+     */
+    bind(buffer, offset) {
+        assert.isNonNegativeInteger(offset, "offset");
+
+        this.buffer = buffer;
+        this.offset = offset;
+
+        return this;
+    }
+
+    /**
+     * Convenience constructor for tests and one-off triangles.
+     * Allocates a private 9-float buffer; for hot paths use {@link bind}
+     * against a shared buffer instead.
+     *
+     * @param {number} ax
+     * @param {number} ay
+     * @param {number} az
+     * @param {number} bx
+     * @param {number} by
+     * @param {number} bz
+     * @param {number} cx
+     * @param {number} cy
+     * @param {number} cz
+     * @returns {Triangle3D}
+     */
+    static from(ax, ay, az, bx, by, bz, cx, cy, cz) {
+        const buf = new Float64Array(9);
+        buf[0] = ax; buf[1] = ay; buf[2] = az;
+        buf[3] = bx; buf[4] = by; buf[5] = bz;
+        buf[6] = cx; buf[7] = cy; buf[8] = cz;
+
+        const t = new Triangle3D();
+        t.bind(buf, 0);
+        return t;
+    }
+
+    support(result, result_offset, direction_x, direction_y, direction_z) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const da = ax * direction_x + ay * direction_y + az * direction_z;
+        const db = bx * direction_x + by * direction_y + bz * direction_z;
+        const dc = cx * direction_x + cy * direction_y + cz * direction_z;
+
+        if (da >= db && da >= dc) {
+            result[result_offset    ] = ax;
+            result[result_offset + 1] = ay;
+            result[result_offset + 2] = az;
+        } else if (db >= dc) {
+            result[result_offset    ] = bx;
+            result[result_offset + 1] = by;
+            result[result_offset + 2] = bz;
+        } else {
+            result[result_offset    ] = cx;
+            result[result_offset + 1] = cy;
+            result[result_offset + 2] = cz;
+        }
+    }
+
+    compute_bounding_box(result) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        result[0] = ax < bx ? (ax < cx ? ax : cx) : (bx < cx ? bx : cx);
+        result[1] = ay < by ? (ay < cy ? ay : cy) : (by < cy ? by : cy);
+        result[2] = az < bz ? (az < cz ? az : cz) : (bz < cz ? bz : cz);
+
+        result[3] = ax > bx ? (ax > cx ? ax : cx) : (bx > cx ? bx : cx);
+        result[4] = ay > by ? (ay > cy ? ay : cy) : (by > cy ? by : cy);
+        result[5] = az > bz ? (az > cz ? az : cz) : (bz > cz ? bz : cz);
+    }
+
+    /**
+     * A triangle has zero interior volume.
+     */
+    contains_point(_point) {
+        return false;
+    }
+
+    /**
+     * Signed distance has a well-defined sign relative to the triangle's
+     * face plane: positive on the side that the face normal points to
+     * (normal = (B-A) × (C-A), CCW convention), negative on the other.
+     *
+     * Magnitude is the true point-to-triangle distance (handles vertex,
+     * edge, and face Voronoi regions correctly via
+     * {@link computeTriangleClosestPointToPointBarycentric}).
+     */
+    signed_distance_at_point(point) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const px = point[0]; const py = point[1]; const pz = point[2];
+
+        computeTriangleClosestPointToPointBarycentric(
+            scratch_bary, 0,
+            px, py, pz,
+            ax, ay, az,
+            bx, by, bz,
+            cx, cy, cz
+        );
+
+        // result format: [alpha_A, alpha_B]; alpha_C = 1 - alpha_A - alpha_B
+        const alpha_a = scratch_bary[0];
+        const alpha_b = scratch_bary[1];
+        const alpha_c = 1 - alpha_a - alpha_b;
+
+        const closest_x = alpha_a * ax + alpha_b * bx + alpha_c * cx;
+        const closest_y = alpha_a * ay + alpha_b * by + alpha_c * cy;
+        const closest_z = alpha_a * az + alpha_b * bz + alpha_c * cz;
+
+        const dx = px - closest_x;
+        const dy = py - closest_y;
+        const dz = pz - closest_z;
+
+        const distance = v3_length(dx, dy, dz);
+
+        // face normal = (B - A) × (C - A)  — CCW convention
+        const e1x = bx - ax; const e1y = by - ay; const e1z = bz - az;
+        const e2x = cx - ax; const e2y = cy - ay; const e2z = cz - az;
+
+        const nx = e1y * e2z - e1z * e2y;
+        const ny = e1z * e2x - e1x * e2z;
+        const nz = e1x * e2y - e1y * e2x;
+
+        const side = (px - ax) * nx + (py - ay) * ny + (pz - az) * nz;
+
+        return side >= 0 ? distance : -distance;
+    }
+
+    nearest_point_on_surface(result, reference) {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        computeTriangleClosestPointToPointBarycentric(
+            scratch_bary, 0,
+            reference[0], reference[1], reference[2],
+            ax, ay, az,
+            bx, by, bz,
+            cx, cy, cz
+        );
+
+        // result format: [alpha_A, alpha_B]; alpha_C = 1 - alpha_A - alpha_B
+        const alpha_a = scratch_bary[0];
+        const alpha_b = scratch_bary[1];
+        const alpha_c = 1 - alpha_a - alpha_b;
+
+        result[0] = alpha_a * ax + alpha_b * bx + alpha_c * cx;
+        result[1] = alpha_a * ay + alpha_b * by + alpha_c * cy;
+        result[2] = alpha_a * az + alpha_b * bz + alpha_c * cz;
+    }
+
+    /**
+     * Uniform random barycentric sample within the triangle.
+     * Triangles have no interior, so the sample lies on the surface.
+     */
+    sample_random_point_in_volume(result, result_offset, random) {
+        let r1 = random();
+        let r2 = random();
+
+        // unit-square reflection trick for uniform-barycentric sampling
+        if (r1 + r2 > 1) {
+            r1 = 1 - r1;
+            r2 = 1 - r2;
+        }
+
+        const r0 = 1 - r1 - r2;
+
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        result[result_offset    ] = r0 * ax + r1 * bx + r2 * cx;
+        result[result_offset + 1] = r0 * ay + r1 * by + r2 * cy;
+        result[result_offset + 2] = r0 * az + r1 * bz + r2 * cz;
+    }
+
+    get volume() {
+        return 0;
+    }
+
+    get surface_area() {
+        const b = this.buffer;
+        const o = this.offset;
+
+        const ax = b[o    ]; const ay = b[o + 1]; const az = b[o + 2];
+        const bx = b[o + 3]; const by = b[o + 4]; const bz = b[o + 5];
+        const cx = b[o + 6]; const cy = b[o + 7]; const cz = b[o + 8];
+
+        const e1x = bx - ax; const e1y = by - ay; const e1z = bz - az;
+        const e2x = cx - ax; const e2y = cy - ay; const e2z = cz - az;
+
+        const nx = e1y * e2z - e1z * e2y;
+        const ny = e1z * e2x - e1x * e2z;
+        const nz = e1x * e2y - e1y * e2x;
+
+        return 0.5 * v3_length(nx, ny, nz);
+    }
+
+    /**
+     * @param {Triangle3D} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (!super.equals(other)) return false;
+
+        const a = this.buffer;
+        const ao = this.offset;
+        const b = other.buffer;
+        const bo = other.offset;
+
+        for (let i = 0; i < 9; i++) {
+            if (a[ao + i] !== b[bo + i]) return false;
+        }
+
+        return true;
+    }
+
+    hash() {
+        const b = this.buffer;
+        const o = this.offset;
+
+        let h = 0;
+
+        for (let i = 0; i < 9; i++) {
+            h = ((h << 5) - h + computeHashFloat(b[o + i])) | 0;
+        }
+
+        return h;
+    }
+}
+
+/**
+ * Fast type-check marker.
+ * @readonly
+ * @type {boolean}
+ */
+Triangle3D.prototype.isTriangle3D = true;
+
+/**
+ * Scratch for barycentric output from {@link computeTriangleClosestPointToPointBarycentric}.
+ * Module-scoped because every triangle method that needs barycentric
+ * coords does it strictly inline — no nested calls that could re-enter.
+ * @type {Float64Array}
+ */
+const scratch_bary = new Float64Array(2);

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

@@ -352,3 +352,16 @@ export class UnionShape3D extends AbstractShape3D {
         return hash;
     }
 }
+
+/**
+ * The set-union of convex shapes is convex only in the trivial cases (one
+ * child, or fully overlapping children). The general case is non-convex,
+ * so the narrowphase must decompose the union into its children and run
+ * per-child GJK against the other body, then merge the resulting contact
+ * manifolds. Treating the union as a single convex blob via GJK on a
+ * combined support would conflate distinct children into a fake hull.
+ *
+ * @readonly
+ * @type {boolean}
+ */
+UnionShape3D.prototype.is_convex = false;

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

@@ -0,0 +1,30 @@
+/**
+ * Build a {@link MeshShape3D} from a Three-style indexed triangle buffer.
+ *
+ * Pipeline:
+ *  1. {@link bt_mesh_from_indexed_geometry} reconstructs a
+ *     {@link BinaryTopology} (vertex / edge / loop / face cycles).
+ *  2. {@link compute_tetrahedral_mesh_from_surface} tetrahedralises the
+ *     volume enclosed by the surface, carving away exterior tets.
+ *  3. The tet mesh is **compacted** — the carving pass leaves the free
+ *     list populated with low-index slots, and downstream consumers
+ *     (`tetrahedral_mesh_to_bvh` iterates by index, the shape's
+ *     `recompute_cached` does the same) expect a hole-free range.
+ *     Compaction relocates live tets so indices `[0, count)` are dense.
+ *  4. The flat positions + indices are kept verbatim on the shape for
+ *     fast support-function and triangle-distance queries.
+ *  5. A {@link BVH} is built over the tet AABBs, used by
+ *     {@link MeshShape3D#contains_point} for O(log N) point-in-mesh
+ *     queries that correctly handle disconnected meshes (which the
+ *     previous tet-walker did not).
+ *
+ * The caller's buffers are NOT cloned — they're attached to the shape
+ * directly. Don't mutate them after handing them in.
+ *
+ * @param {Float32Array} positions flat `(x, y, z)` per vertex
+ * @param {Uint32Array}  indices  three uint32 per triangle (CCW winding)
+ * @returns {MeshShape3D}
+ */
+export function shape_mesh_from_geometry(positions: Float32Array, indices: Uint32Array): MeshShape3D;
+import { MeshShape3D } from "./MeshShape3D.js";
+//# sourceMappingURL=shape_mesh_from_geometry.d.ts.map

package/src/core/geom/3d/shape/shape_mesh_from_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape_mesh_from_geometry.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/shape/shape_mesh_from_geometry.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,oDAJW,YAAY,WACZ,WAAW,GACT,WAAW,CAgCvB;4BA3D2B,kBAAkB"}

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

@@ -0,0 +1,64 @@
+import { tetrahedral_mesh_to_bvh } from "../tetrahedra/bvh/tetrahedral_mesh_to_bvh.js";
+import { compute_tetrahedral_mesh_from_surface } from "../tetrahedra/compute_tetrahedral_mesh_from_surface.js";
+import { BinaryTopology } from "../topology/struct/binary/BinaryTopology.js";
+import { bt_mesh_from_indexed_geometry } from "../topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { MeshShape3D } from "./MeshShape3D.js";
+
+/**
+ * Build a {@link MeshShape3D} from a Three-style indexed triangle buffer.
+ *
+ * Pipeline:
+ *  1. {@link bt_mesh_from_indexed_geometry} reconstructs a
+ *     {@link BinaryTopology} (vertex / edge / loop / face cycles).
+ *  2. {@link compute_tetrahedral_mesh_from_surface} tetrahedralises the
+ *     volume enclosed by the surface, carving away exterior tets.
+ *  3. The tet mesh is **compacted** — the carving pass leaves the free
+ *     list populated with low-index slots, and downstream consumers
+ *     (`tetrahedral_mesh_to_bvh` iterates by index, the shape's
+ *     `recompute_cached` does the same) expect a hole-free range.
+ *     Compaction relocates live tets so indices `[0, count)` are dense.
+ *  4. The flat positions + indices are kept verbatim on the shape for
+ *     fast support-function and triangle-distance queries.
+ *  5. A {@link BVH} is built over the tet AABBs, used by
+ *     {@link MeshShape3D#contains_point} for O(log N) point-in-mesh
+ *     queries that correctly handle disconnected meshes (which the
+ *     previous tet-walker did not).
+ *
+ * The caller's buffers are NOT cloned — they're attached to the shape
+ * directly. Don't mutate them after handing them in.
+ *
+ * @param {Float32Array} positions flat `(x, y, z)` per vertex
+ * @param {Uint32Array}  indices  three uint32 per triangle (CCW winding)
+ * @returns {MeshShape3D}
+ */
+export function shape_mesh_from_geometry(positions, indices) {
+    const shape = new MeshShape3D();
+    shape.positions = positions;
+    shape.indices = indices;
+
+    // 1. BinaryTopology from the indexed buffer.
+    const topology = new BinaryTopology();
+    bt_mesh_from_indexed_geometry(topology, indices, positions);
+
+    // 2. Tetrahedralise. interior_steiner_cells_per_dim = 0 — for
+    //    collision queries the inside/outside oracle only needs
+    //    surface-vertex tets; interior Steiner points add cost without
+    //    changing the contains_point result.
+    shape.tet_positions = compute_tetrahedral_mesh_from_surface(shape.tet_mesh, topology, 0);
+
+    // 3. Compact. The carve pass freed slots in the tet mesh's
+    //    allocator; compaction repacks live tets into a dense
+    //    [0, count) range. Without this, `tetrahedral_mesh_to_bvh`
+    //    iterates "tet index 0..count" and treats freed indices as if
+    //    they were live tets — produces phantom BVH leaves with stale
+    //    vertex data.
+    shape.tet_mesh.compact();
+
+    // 4. BVH over tet AABBs for the point-in-mesh query path.
+    tetrahedral_mesh_to_bvh(shape.tet_bvh, shape.tet_mesh, shape.tet_positions);
+
+    // 5. Refresh cached bbox / volume / surface area.
+    shape.recompute_cached();
+
+    return shape;
+}

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

@@ -50,18 +50,16 @@ import { TetrahedralMesh } from "./TetrahedralMesh.js";
 // radius-ratio metric.
 const SLIVER_QUALITY_THRESHOLD = 0.05;
 
-// Sliver-removal driver config. Currently OFF by default because the
-// driver isn't optimised for interactive use yet: on a 6,500-tet Suzanne
-// (and similar) it takes ~50 seconds per pass, which would freeze the UI
-// on every drop. The main hotspot is `tetrahedral_mesh_vertex_is_boundary`
-// inside the smoothing pass — it scans every tet in the mesh per vertex.
-// Builds a vertex→tet adjacency cache once per pass to replace it.
+// Sliver-removal driver config. The driver now builds a vertex→tet
+// adjacency cache once per pass and shares it with the boundary check,
+// the local quality eval, and the smoothing primitive — bringing per-pass
+// cost from O(N²) down to O(N·deg). On a 3,242-tet densified cube the
+// driver dropped from ~23 s to ~3 s; on closed-surface meshes (Suzanne,
+// Teapot) where every vertex is boundary, smoothing is a near no-op and
+// the pass should finish in well under a second.
 //
-// When enabled, the driver halves the sliver count on Suzanne and
-// commits ~200 3-2 flips; smoothing is a no-op on closed-surface meshes
-// because every vertex is on the boundary. Toggle this to true if you
-// want the BEFORE → AFTER numbers logged in the per-mesh console line.
-const ENABLE_IMPROVE_QUALITY = false;
+// BEFORE → AFTER numbers are logged in the per-mesh console line.
+const ENABLE_IMPROVE_QUALITY = true;
 const IMPROVE_TARGET_QUALITY = 0.05; // sliver cutoff only — keep the workload small
 const IMPROVE_MAX_PASSES = 1;
 

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

@@ -0,0 +1,28 @@
+/**
+ * Build a `Map<vertex_id, tet_id[]>` enumerating every live tet that
+ * contains each vertex. One full pass over the mesh; the result lets
+ * subsequent per-vertex queries run in O(deg) instead of O(N).
+ *
+ * Useful when the caller is about to perform many per-vertex queries —
+ * e.g. boundary-status checks or 1-ring quality evaluations across a whole
+ * mesh during a quality-improvement pass. Without the cache, each query
+ * has to scan every live tet (see
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} and
+ * {@link tetrahedral_mesh_vertex_is_boundary}), which compounds to O(N²)
+ * over a full pass.
+ *
+ * The map is a SNAPSHOT: it reflects mesh state at build time. Any flips,
+ * deletions or appends that happen afterwards will leave it stale. Callers
+ * must either rebuild after each mutation or accept the staleness (for
+ * boundary checks the cache is flip-invariant, so a once-per-pass rebuild
+ * is safe; for queries that need the exact current 1-ring, the caller
+ * should filter through `mesh.exists` and rebuild after mutations they
+ * care about).
+ *
+ * Cost: O(N) where N is `mesh.count`.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @returns {Map<number, number[]>}
+ */
+export function tetrahedral_mesh_build_vertex_to_tets_map(mesh: TetrahedralMesh): Map<number, number[]>;
+//# sourceMappingURL=tetrahedral_mesh_build_vertex_to_tets_map.d.ts.map

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_build_vertex_to_tets_map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_build_vertex_to_tets_map.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_build_vertex_to_tets_map.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,kFAFa,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC,CAqBjC"}

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

@@ -0,0 +1,48 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Build a `Map<vertex_id, tet_id[]>` enumerating every live tet that
+ * contains each vertex. One full pass over the mesh; the result lets
+ * subsequent per-vertex queries run in O(deg) instead of O(N).
+ *
+ * Useful when the caller is about to perform many per-vertex queries —
+ * e.g. boundary-status checks or 1-ring quality evaluations across a whole
+ * mesh during a quality-improvement pass. Without the cache, each query
+ * has to scan every live tet (see
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} and
+ * {@link tetrahedral_mesh_vertex_is_boundary}), which compounds to O(N²)
+ * over a full pass.
+ *
+ * The map is a SNAPSHOT: it reflects mesh state at build time. Any flips,
+ * deletions or appends that happen afterwards will leave it stale. Callers
+ * must either rebuild after each mutation or accept the staleness (for
+ * boundary checks the cache is flip-invariant, so a once-per-pass rebuild
+ * is safe; for queries that need the exact current 1-ring, the caller
+ * should filter through `mesh.exists` and rebuild after mutations they
+ * care about).
+ *
+ * Cost: O(N) where N is `mesh.count`.
+ *
+ * @param {TetrahedralMesh} mesh
+ * @returns {Map<number, number[]>}
+ */
+export function tetrahedral_mesh_build_vertex_to_tets_map(mesh) {
+    assert.defined(mesh, 'mesh');
+
+    /** @type {Map<number, number[]>} */
+    const map = new Map();
+
+    mesh.forEach((tet, m) => {
+        for (let i = 0; i < 4; i++) {
+            const v = m.getVertexIndex(tet, i);
+            let bucket = map.get(v);
+            if (bucket === undefined) {
+                bucket = [];
+                map.set(v, bucket);
+            }
+            bucket.push(tet);
+        }
+    });
+
+    return map;
+}

package/src/core/geom/3d/tetrahedra/tetrahedral_mesh_improve_quality.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tetrahedral_mesh_improve_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_improve_quality.js"],"names":[],"mappings":"AA6CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,gFApBW,YAAY,GAAC,MAAM,EAAE;qBAEV,MAAM;iBACV,MAAM;uBACA,MAAM;mBACV,OAAO;uBACH,OAAO;IAElB;IACZ,UAAc,EAAE,MAAM,CAAC;IACvB,oBAAwB,EAAE,MAAM,CAAC;IACjC,mBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAqB,EAAE,MAAM,CAAC;CAC3B,CAuOH"}
+{"version":3,"file":"tetrahedral_mesh_improve_quality.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_improve_quality.js"],"names":[],"mappings":"AA2CA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,gFApBW,YAAY,GAAC,MAAM,EAAE;qBAEV,MAAM;iBACV,MAAM;uBACA,MAAM;mBACV,OAAO;uBACH,OAAO;IAElB;IACZ,UAAc,EAAE,MAAM,CAAC;IACvB,oBAAwB,EAAE,MAAM,CAAC;IACjC,mBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAqB,EAAE,MAAM,CAAC;IAC9B,mBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAqB,EAAE,MAAM,CAAC;CAC3B,CA8OH"}