@woosh/meep-engine 2.138.20 → 2.139.0

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

@@ -0,0 +1,222 @@
+import { assert } from "../../../assert.js";
+import { BVH, NULL_NODE } from "../../../bvh2/bvh3/BVH.js";
+import { bvh_query_user_data_ray } from "../../../bvh2/bvh3/query/bvh_query_user_data_ray.js";
+import { SurfacePoint3 } from "../SurfacePoint3.js";
+import { computeTriangleRayIntersection } from "../triangle/computeTriangleRayIntersection.js";
+
+// Three irrational, mutually unrelated ray directions used for majority-vote
+// inside/outside classification. A single ray is fragile: when it grazes a
+// triangle edge or vertex shared between several faces, Möller-Trumbore's
+// strict inequalities can count 0 or 2 hits instead of 1, flipping parity
+// and wrongly classifying a tet. Three independent rays defang this — at
+// least two must agree, and the geometric chance of two independent
+// irrational rays both grazing shared features is vanishingly small for
+// real-world meshes (Suzanne, sphere, torus, bunny, …).
+//
+// Each row must be roughly unit-length so the AABB-vs-ray slab test in the
+// BVH query doesn't degenerate. Hand-picked rather than randomised so the
+// algorithm is fully deterministic.
+const RAY_DIRECTIONS = [
+    0.97123,  0.18927,  0.14431,
+    0.34219,  0.91283, -0.22971,
+   -0.51237,  0.27894,  0.81235,
+];
+const RAY_COUNT = RAY_DIRECTIONS.length / 3;
+
+/**
+ * Build a BVH over the surface triangles. Each leaf's user_data is the
+ * source face ID.
+ *
+ * @param {BVH} bvh
+ * @param {BinaryTopology} surface
+ */
+function build_surface_bvh(bvh, surface) {
+    bvh.release_all();
+
+    const face_count = surface.faces.size;
+    const v = [0, 0, 0];
+
+    for (let f = 0; f < face_count; f++) {
+        if (!surface.faces.is_allocated(f)) continue;
+
+        const l0 = surface.face_read_loop(f);
+        const l1 = surface.loop_read_next(l0);
+        const l2 = surface.loop_read_next(l1);
+
+        const v0 = surface.loop_read_vertex(l0);
+        const v1 = surface.loop_read_vertex(l1);
+        const v2 = surface.loop_read_vertex(l2);
+
+        surface.vertex_read_coordinate(v, 0, v0);
+        let minx = v[0], miny = v[1], minz = v[2];
+        let maxx = v[0], maxy = v[1], maxz = v[2];
+
+        surface.vertex_read_coordinate(v, 0, v1);
+        if (v[0] < minx) minx = v[0]; else if (v[0] > maxx) maxx = v[0];
+        if (v[1] < miny) miny = v[1]; else if (v[1] > maxy) maxy = v[1];
+        if (v[2] < minz) minz = v[2]; else if (v[2] > maxz) maxz = v[2];
+
+        surface.vertex_read_coordinate(v, 0, v2);
+        if (v[0] < minx) minx = v[0]; else if (v[0] > maxx) maxx = v[0];
+        if (v[1] < miny) miny = v[1]; else if (v[1] > maxy) maxy = v[1];
+        if (v[2] < minz) minz = v[2]; else if (v[2] > maxz) maxz = v[2];
+
+        const node = bvh.allocate_node();
+        bvh.node_set_user_data(node, f);
+        bvh.node_set_aabb_primitive(node, minx, miny, minz, maxx, maxy, maxz);
+        bvh.insert_leaf(node);
+    }
+}
+
+const ray_hit = new SurfacePoint3();
+const ray_candidates = [];
+const va = [0, 0, 0];
+const vb = [0, 0, 0];
+const vc = [0, 0, 0];
+
+/**
+ * Cast a single ray and return the parity of triangle-intersection count
+ * (true ⇔ odd ⇔ inside, under the assumption of a closed surface).
+ */
+function single_ray_parity_inside(bvh, root, surface, ox, oy, oz, dx, dy, dz) {
+    const candidate_count = bvh_query_user_data_ray(
+        bvh, root,
+        ray_candidates, 0,
+        ox, oy, oz,
+        dx, dy, dz
+    );
+
+    let hits = 0;
+    for (let i = 0; i < candidate_count; i++) {
+        const f = ray_candidates[i];
+        const l0 = surface.face_read_loop(f);
+        const l1 = surface.loop_read_next(l0);
+        const l2 = surface.loop_read_next(l1);
+
+        surface.vertex_read_coordinate(va, 0, surface.loop_read_vertex(l0));
+        surface.vertex_read_coordinate(vb, 0, surface.loop_read_vertex(l1));
+        surface.vertex_read_coordinate(vc, 0, surface.loop_read_vertex(l2));
+
+        const hit = computeTriangleRayIntersection(
+            ray_hit,
+            ox, oy, oz,
+            dx, dy, dz,
+            va[0], va[1], va[2],
+            vb[0], vb[1], vb[2],
+            vc[0], vc[1], vc[2]
+        );
+
+        if (hit) hits++;
+    }
+
+    return (hits & 1) === 1;
+}
+
+/**
+ * Classify a point as inside or outside the surface using a majority vote
+ * across `RAY_COUNT` independent parity ray-casts. Robust against the
+ * edge/vertex grazing pathologies that defeat single-ray parity.
+ *
+ * @param {BVH} bvh
+ * @param {BinaryTopology} surface
+ * @param {number} ox
+ * @param {number} oy
+ * @param {number} oz
+ * @returns {boolean}
+ */
+function point_is_inside_surface(bvh, surface, ox, oy, oz) {
+    const root = bvh.root;
+    if (root === NULL_NODE) {
+        return false;
+    }
+
+    let inside_votes = 0;
+
+    for (let r = 0; r < RAY_COUNT; r++) {
+        const dx = RAY_DIRECTIONS[r * 3];
+        const dy = RAY_DIRECTIONS[r * 3 + 1];
+        const dz = RAY_DIRECTIONS[r * 3 + 2];
+
+        if (single_ray_parity_inside(bvh, root, surface, ox, oy, oz, dx, dy, dz)) {
+            inside_votes++;
+        }
+    }
+
+    // Strict majority (more than half).
+    return inside_votes * 2 > RAY_COUNT;
+}
+
+/**
+ * Carve a Delaunay tetrahedralization so only the tets inside the input
+ * surface remain. Operates on a TetrahedralMesh whose vertex IDs are aligned
+ * with the surface's vertex IDs — both index into the same flat positions
+ * array used by `compute_delaunay_tetrahedral_mesh`.
+ *
+ * Algorithm: build a BVH over the surface triangles, then for every tet,
+ * classify its centroid as inside or outside via parity ray-casting against
+ * the BVH. Exterior tets are disconnected and deleted.
+ *
+ * Pure ray-cast classification is intentional. A flood-fill optimisation over
+ * tet adjacency would be cheaper but is unsafe when the Delaunay's diagonals
+ * differ from the surface's (always the case for coarse meshes like a cube,
+ * common for finer meshes): leaked surface triangles let the fill cross from
+ * interior to exterior unchecked, deleting tets that should be kept.
+ *
+ * @param {TetrahedralMesh} tet_mesh mutated in place
+ * @param {ArrayLike<number>|Float32Array} positions same flat (x,y,z) array used in the Delaunay pass
+ * @param {BinaryTopology} surface watertight surface mesh defining inside/outside
+ * @returns {{deleted: number, kept: number}}
+ */
+export function tetrahedral_mesh_carve_outside_surface(tet_mesh, positions, surface) {
+    assert.defined(tet_mesh, 'tet_mesh');
+    assert.equal(tet_mesh.isTetrahedralMesh, true, 'tet_mesh.isTetrahedralMesh !== true');
+    assert.defined(surface, 'surface');
+    assert.equal(surface.isBinaryTopology, true, 'surface.isBinaryTopology !== true');
+
+    const surface_bvh = new BVH();
+    build_surface_bvh(surface_bvh, surface);
+
+    const live_tets = tet_mesh.getLive();
+    const live_count = live_tets.length;
+
+    let deleted = 0;
+    let kept = 0;
+
+    // Classify each tet by its centroid. The centroid is guaranteed strictly
+    // interior to the tet, so the parity ray-cast against the surface gives
+    // an unambiguous answer (never on the surface itself).
+    //
+    // Face-centroid multi-sampling was considered but rejected: face
+    // centroids of large boundary tets land EXACTLY on a surface triangle,
+    // making the parity test ambiguous (the ray-triangle test reports a hit
+    // or a miss depending on rounding), which corrupted coarse-mesh results
+    // (e.g. a unit cube tetrahedralized into ~5 tets lost ~17 % of its
+    // volume). The current single-point classifier converges correctly for
+    // both coarse convex meshes (cube, sphere) and complex non-convex ones
+    // (Suzanne, torus) at the cost of a few-percent discretization gap that
+    // shrinks with resolution.
+    for (let i = 0; i < live_count; i++) {
+        const tet = live_tets[i];
+
+        let cx = 0, cy = 0, cz = 0;
+        for (let j = 0; j < 4; j++) {
+            const v3 = tet_mesh.getVertexIndex(tet, j) * 3;
+            cx += positions[v3];
+            cy += positions[v3 + 1];
+            cz += positions[v3 + 2];
+        }
+        cx *= 0.25;
+        cy *= 0.25;
+        cz *= 0.25;
+
+        if (point_is_inside_surface(surface_bvh, surface, cx, cy, cz)) {
+            kept++;
+        } else {
+            tet_mesh.disconnect(tet);
+            tet_mesh.delete(tet);
+            deleted++;
+        }
+    }
+
+    return { deleted, kept };
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Collect every tet sharing the edge (v_a, v_b), starting from a tet that's
+ * already known to contain the edge. Walks the ring of tets around the edge
+ * by following face-neighbours through the two faces of each tet that
+ * contain both endpoints.
+ *
+ * Output is written to `result[result_offset..result_offset + count - 1]`
+ * in walk order; the starting tet is first. For an INTERIOR edge (every
+ * face neighbour exists) the walk forms a closed cycle visiting each
+ * incident tet once; the function returns the count and `out_closed[0]`
+ * is set to 1. For a BOUNDARY edge (one or both walk directions hit
+ * INVALID_NEIGHBOUR) the walk continues from `start_tet` in the OTHER
+ * direction; the function still returns every tet it visited, but
+ * `out_closed[0]` is set to 0 so callers that need a proper ring (e.g.
+ * the 3-2 flip, which is only valid on closed rings) can reject the input.
+ *
+ * Cost: O(ring_size), one or two neighbour-hops per tet — much cheaper than
+ * scanning the whole mesh, which is why callers should prefer this over
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} when they already
+ * have a starting tet.
+ *
+ * @param {number[]} result
+ * @param {number} result_offset
+ * @param {TetrahedralMesh} mesh
+ * @param {number} start_tet — must contain both v_a and v_b
+ * @param {number} v_a
+ * @param {number} v_b
+ * @param {number[]} out_closed — 1-element array; set to 1 if the walk
+ *        closed (interior edge), 0 if either direction hit a boundary face.
+ *        Callers that need a closed-ring guarantee must inspect this.
+ * @returns {number} number of tets written (always ≥ 1 — the start_tet)
+ */
+export function tetrahedral_mesh_find_tets_around_edge(result: number[], result_offset: number, mesh: TetrahedralMesh, start_tet: number, v_a: number, v_b: number, out_closed: number[]): number;
+//# sourceMappingURL=tetrahedral_mesh_find_tets_around_edge.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_find_tets_around_edge.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_find_tets_around_edge.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,+DAXW,MAAM,EAAE,iBACR,MAAM,oCAEN,MAAM,OACN,MAAM,OACN,MAAM,cACN,MAAM,EAAE,GAGN,MAAM,CA+DlB"}

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

@@ -0,0 +1,146 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * Collect every tet sharing the edge (v_a, v_b), starting from a tet that's
+ * already known to contain the edge. Walks the ring of tets around the edge
+ * by following face-neighbours through the two faces of each tet that
+ * contain both endpoints.
+ *
+ * Output is written to `result[result_offset..result_offset + count - 1]`
+ * in walk order; the starting tet is first. For an INTERIOR edge (every
+ * face neighbour exists) the walk forms a closed cycle visiting each
+ * incident tet once; the function returns the count and `out_closed[0]`
+ * is set to 1. For a BOUNDARY edge (one or both walk directions hit
+ * INVALID_NEIGHBOUR) the walk continues from `start_tet` in the OTHER
+ * direction; the function still returns every tet it visited, but
+ * `out_closed[0]` is set to 0 so callers that need a proper ring (e.g.
+ * the 3-2 flip, which is only valid on closed rings) can reject the input.
+ *
+ * Cost: O(ring_size), one or two neighbour-hops per tet — much cheaper than
+ * scanning the whole mesh, which is why callers should prefer this over
+ * {@link tetrahedral_mesh_find_tets_attached_to_vertex} when they already
+ * have a starting tet.
+ *
+ * @param {number[]} result
+ * @param {number} result_offset
+ * @param {TetrahedralMesh} mesh
+ * @param {number} start_tet — must contain both v_a and v_b
+ * @param {number} v_a
+ * @param {number} v_b
+ * @param {number[]} out_closed — 1-element array; set to 1 if the walk
+ *        closed (interior edge), 0 if either direction hit a boundary face.
+ *        Callers that need a closed-ring guarantee must inspect this.
+ * @returns {number} number of tets written (always ≥ 1 — the start_tet)
+ */
+export function tetrahedral_mesh_find_tets_around_edge(
+    result, result_offset,
+    mesh, start_tet, v_a, v_b,
+    out_closed
+) {
+    assert.defined(result, 'result');
+    assert.defined(mesh, 'mesh');
+    assert.isNonNegativeInteger(start_tet, 'start_tet');
+    assert.isNonNegativeInteger(v_a, 'v_a');
+    assert.isNonNegativeInteger(v_b, 'v_b');
+    assert.notEqual(v_a, v_b, 'v_a and v_b must be distinct');
+    assert.defined(out_closed, 'out_closed');
+
+    // Find slots of v_a and v_b in the starting tet.
+    let slot_a_start = -1;
+    let slot_b_start = -1;
+    for (let i = 0; i < 4; i++) {
+        const v = mesh.getVertexIndex(start_tet, i);
+        if (v === v_a) slot_a_start = i;
+        else if (v === v_b) slot_b_start = i;
+    }
+    if (slot_a_start < 0 || slot_b_start < 0) {
+        throw new Error(`start_tet ${start_tet} does not contain both vertices ${v_a} and ${v_b}`);
+    }
+
+    // The 2 "other" slots in start_tet are the slots of the 2 vertices that
+    // are NOT on the edge. The faces OPPOSITE these 2 slots both contain
+    // the edge (v_a, v_b); each leads to a different ring neighbour.
+    let first_step_slot = -1;
+    let second_step_slot = -1;
+    for (let i = 0; i < 4; i++) {
+        if (i === slot_a_start || i === slot_b_start) continue;
+        if (first_step_slot < 0) first_step_slot = i;
+        else second_step_slot = i;
+    }
+
+    let cursor = result_offset;
+    result[cursor++] = start_tet;
+
+    // Walk forward via first_step_slot.
+    const forward = walk(
+        mesh, v_a, v_b, start_tet, first_step_slot, result, /* state */ { cursor }
+    );
+    cursor = forward.cursor;
+
+    if (forward.closed) {
+        // Ring closed with one walk — visited every incident tet.
+        out_closed[0] = 1;
+        return cursor - result_offset;
+    }
+
+    // Forward walk hit a boundary face. The ring is open on at least one
+    // side; walk backward from start_tet via the OTHER step slot too.
+    const backward = walk(
+        mesh, v_a, v_b, start_tet, second_step_slot, result, { cursor }
+    );
+    cursor = backward.cursor;
+
+    // Two walks were needed → the edge is on the boundary, ring is open.
+    out_closed[0] = 0;
+    return cursor - result_offset;
+}
+
+/**
+ * Walk the ring of tets sharing edge (v_a, v_b), starting at `from_tet` and
+ * leaving through `from_slot`. Appends visited tets (not including
+ * `from_tet`) to `result` at `state.cursor`, updating the cursor. Returns
+ * `{ cursor, closed }` — `closed` is true if the walk returned to
+ * `from_tet` (interior edge), false if it hit a boundary face.
+ */
+function walk(mesh, v_a, v_b, from_tet, from_slot, result, state) {
+    let curr_tet = from_tet;
+    let exit_slot = from_slot;
+
+    while (true) {
+        const enc = mesh.getNeighbour(curr_tet, exit_slot);
+        if (enc === INVALID_NEIGHBOUR) {
+            return { cursor: state.cursor, closed: false };
+        }
+
+        const next_tet = enc >>> 2;
+        if (next_tet === from_tet) {
+            return { cursor: state.cursor, closed: true };
+        }
+
+        result[state.cursor++] = next_tet;
+
+        // Find slots of v_a, v_b in next_tet, and the back-slot (the face
+        // we just walked through). The next "exit" is the only remaining
+        // slot — i.e., {0,1,2,3} \ {slot_a, slot_b, back_slot}.
+        let slot_a_next = -1;
+        let slot_b_next = -1;
+        for (let i = 0; i < 4; i++) {
+            const v = mesh.getVertexIndex(next_tet, i);
+            if (v === v_a) slot_a_next = i;
+            else if (v === v_b) slot_b_next = i;
+        }
+        const back_slot = enc & 3;
+
+        let next_exit = -1;
+        for (let i = 0; i < 4; i++) {
+            if (i !== slot_a_next && i !== slot_b_next && i !== back_slot) {
+                next_exit = i;
+                break;
+            }
+        }
+
+        curr_tet = next_tet;
+        exit_slot = next_exit;
+    }
+}

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

@@ -0,0 +1,36 @@
+/**
+ * Perform a 2-3 flip on two tetrahedra that share a face.
+ *
+ * Input two tets t1, t2 sharing a triangle face. The flip removes that face
+ * and replaces it with a new edge connecting the two "apex" vertices (the
+ * vertex of each tet that's NOT on the shared face). The shared bipyramid is
+ * re-tetrahedralised into three new tets, each containing the new edge plus
+ * one edge of the original shared face.
+ *
+ * Counts go from (2 tets, 5 vertices total, 1 internal face) to (3 tets, 5
+ * vertices, 3 internal faces). No vertex IDs change; the operation is purely
+ * topological — it doesn't touch the points array.
+ *
+ * Geometric validity (positive volume of each new tet under any specific
+ * embedding) is the caller's responsibility. The flip preserves orientation
+ * — if t1 was positively wound the new tets are too — but the new edge
+ * (d, e) must actually lie inside the convex region formed by the original
+ * two tets for the result to be a valid embedding. Outside Delaunay /
+ * constraint-recovery contexts this is the caller's domain knowledge.
+ *
+ * Implementation notes:
+ *   - t1's storage slot is reused for one of the new tets ("T_alpha")
+ *   - t2's slot for another ("T_beta")
+ *   - one fresh slot is allocated for the third ("T_gamma")
+ *   - all four external neighbour back-pointers around each of t1 and t2
+ *     are rewritten to point at the right new tet/slot
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} t1
+ * @param {number} t2 must share a face with t1
+ * @param {Uint32Array|number[]} out output storage; out[0..2] receive the 3
+ *        new tet IDs. Caller provides — the function performs no allocation.
+ *        Must have length ≥ 3.
+ */
+export function tetrahedral_mesh_flip_23(mesh: TetrahedralMesh, t1: number, t2: number, out: Uint32Array | number[]): void;
+//# sourceMappingURL=tetrahedral_mesh_flip_23.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tetrahedral_mesh_flip_23.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/3d/tetrahedra/tetrahedral_mesh_flip_23.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,oEANW,MAAM,MACN,MAAM,OACN,WAAW,GAAC,MAAM,EAAE,QAmK9B"}

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

@@ -0,0 +1,232 @@
+import { assert } from "../../../assert.js";
+import { INVALID_NEIGHBOUR } from "./TetrahedralMesh.js";
+
+/**
+ * For a tet stored as (v0, v1, v2, v3), the vertices of the face opposite
+ * vertex i, in counter-clockwise order viewed from outside the tet (i.e. the
+ * standard outward-facing winding for a positively-oriented tet whose signed
+ * volume is positive under the engine's `compute_tetrahedron_volume`).
+ *
+ * Derived from the volume formula vol = (1/6)·det[v0-v3, v1-v3, v2-v3]:
+ *   - Face opposite v3 is the canonical case (v0, v1, v2).
+ *   - Other faces follow by even-permutation parity to keep the implied tet
+ *     (face, opposite_vertex) positively wound.
+ */
+const FACE_VERTICES_BY_OPPOSITE = [
+    [1, 3, 2], // opposite v0
+    [0, 2, 3], // opposite v1
+    [0, 3, 1], // opposite v2
+    [0, 1, 2], // opposite v3
+];
+
+/**
+ * Perform a 2-3 flip on two tetrahedra that share a face.
+ *
+ * Input two tets t1, t2 sharing a triangle face. The flip removes that face
+ * and replaces it with a new edge connecting the two "apex" vertices (the
+ * vertex of each tet that's NOT on the shared face). The shared bipyramid is
+ * re-tetrahedralised into three new tets, each containing the new edge plus
+ * one edge of the original shared face.
+ *
+ * Counts go from (2 tets, 5 vertices total, 1 internal face) to (3 tets, 5
+ * vertices, 3 internal faces). No vertex IDs change; the operation is purely
+ * topological — it doesn't touch the points array.
+ *
+ * Geometric validity (positive volume of each new tet under any specific
+ * embedding) is the caller's responsibility. The flip preserves orientation
+ * — if t1 was positively wound the new tets are too — but the new edge
+ * (d, e) must actually lie inside the convex region formed by the original
+ * two tets for the result to be a valid embedding. Outside Delaunay /
+ * constraint-recovery contexts this is the caller's domain knowledge.
+ *
+ * Implementation notes:
+ *   - t1's storage slot is reused for one of the new tets ("T_alpha")
+ *   - t2's slot for another ("T_beta")
+ *   - one fresh slot is allocated for the third ("T_gamma")
+ *   - all four external neighbour back-pointers around each of t1 and t2
+ *     are rewritten to point at the right new tet/slot
+ *
+ * @param {TetrahedralMesh} mesh
+ * @param {number} t1
+ * @param {number} t2 must share a face with t1
+ * @param {Uint32Array|number[]} out output storage; out[0..2] receive the 3
+ *        new tet IDs. Caller provides — the function performs no allocation.
+ *        Must have length ≥ 3.
+ */
+export function tetrahedral_mesh_flip_23(mesh, t1, t2, out) {
+    assert.defined(mesh, 'mesh');
+    assert.equal(mesh.isTetrahedralMesh, true, 'mesh.isTetrahedralMesh !== true');
+    assert.isNonNegativeInteger(t1, 't1');
+    assert.isNonNegativeInteger(t2, 't2');
+    assert.notEqual(t1, t2, 't1 must not equal t2');
+    assert.defined(out, 'out');
+
+    // -----------------------------------------------------------------
+    // Step 1: locate the shared face.
+    // -----------------------------------------------------------------
+    let shared_i1 = -1;
+    let shared_i2 = -1;
+    for (let i = 0; i < 4; i++) {
+        const enc = mesh.getNeighbour(t1, i);
+        if (enc === INVALID_NEIGHBOUR) continue;
+        if ((enc >>> 2) === t2) {
+            shared_i1 = i;
+            shared_i2 = enc & 3;
+            break;
+        }
+    }
+    if (shared_i1 < 0) {
+        throw new Error(`tets ${t1} and ${t2} do not share a face`);
+    }
+
+    // -----------------------------------------------------------------
+    // Step 2: identify the 5 distinct vertices.
+    //   d = apex of t1 (opposite the shared face)
+    //   e = apex of t2
+    //   (p, q, r) = shared face vertices, in CCW order seen from outside t1
+    //               (i.e. the standard "outward face" ordering)
+    // -----------------------------------------------------------------
+    const d = mesh.getVertexIndex(t1, shared_i1);
+    const e = mesh.getVertexIndex(t2, shared_i2);
+
+    const face_t1 = FACE_VERTICES_BY_OPPOSITE[shared_i1];
+    const pos_p_in_t1 = face_t1[0];
+    const pos_q_in_t1 = face_t1[1];
+    const pos_r_in_t1 = face_t1[2];
+
+    const p = mesh.getVertexIndex(t1, pos_p_in_t1);
+    const q = mesh.getVertexIndex(t1, pos_q_in_t1);
+    const r = mesh.getVertexIndex(t1, pos_r_in_t1);
+
+    // Find where p, q, r live in t2's vertex array. Needed to look up which
+    // of t2's external neighbours sits opposite each of p, q, r.
+    let pos_p_in_t2 = -1, pos_q_in_t2 = -1, pos_r_in_t2 = -1;
+    for (let i = 0; i < 4; i++) {
+        const v = mesh.getVertexIndex(t2, i);
+        if (v === p) pos_p_in_t2 = i;
+        else if (v === q) pos_q_in_t2 = i;
+        else if (v === r) pos_r_in_t2 = i;
+    }
+    if (pos_p_in_t2 < 0 || pos_q_in_t2 < 0 || pos_r_in_t2 < 0) {
+        throw new Error(
+            `tets ${t1} and ${t2} are recorded as neighbours but their shared face vertices don't match — mesh integrity broken`
+        );
+    }
+
+    // -----------------------------------------------------------------
+    // Step 3: snapshot external neighbours BEFORE we start writing.
+    //   t1's faces opposite p, q, r are external (the face opposite d is t2).
+    //   Same for t2.
+    // -----------------------------------------------------------------
+    const ext_p_t1 = mesh.getNeighbour(t1, pos_p_in_t1);
+    const ext_q_t1 = mesh.getNeighbour(t1, pos_q_in_t1);
+    const ext_r_t1 = mesh.getNeighbour(t1, pos_r_in_t1);
+    const ext_p_t2 = mesh.getNeighbour(t2, pos_p_in_t2);
+    const ext_q_t2 = mesh.getNeighbour(t2, pos_q_in_t2);
+    const ext_r_t2 = mesh.getNeighbour(t2, pos_r_in_t2);
+
+    // -----------------------------------------------------------------
+    // Step 4: allocate the third slot. Reuse t1 → T_alpha, t2 → T_beta.
+    // -----------------------------------------------------------------
+    const T_alpha = t1;
+    const T_beta = t2;
+    const T_gamma = mesh.allocate();
+
+    // -----------------------------------------------------------------
+    // Step 5: write vertices in canonical positive-volume order.
+    //   T_alpha = (r, q, d, e)  — covers edge (q, r), missing p
+    //   T_beta  = (p, r, d, e)  — covers edge (r, p), missing q
+    //   T_gamma = (q, p, d, e)  — covers edge (p, q), missing r
+    // Each ordering was derived (and verified) to keep the new tet's signed
+    // volume the same sign as the original t1/t2 under the engine's
+    // convention.
+    // -----------------------------------------------------------------
+    mesh.setVertexIndex(T_alpha, 0, r);
+    mesh.setVertexIndex(T_alpha, 1, q);
+    mesh.setVertexIndex(T_alpha, 2, d);
+    mesh.setVertexIndex(T_alpha, 3, e);
+
+    mesh.setVertexIndex(T_beta, 0, p);
+    mesh.setVertexIndex(T_beta, 1, r);
+    mesh.setVertexIndex(T_beta, 2, d);
+    mesh.setVertexIndex(T_beta, 3, e);
+
+    mesh.setVertexIndex(T_gamma, 0, q);
+    mesh.setVertexIndex(T_gamma, 1, p);
+    mesh.setVertexIndex(T_gamma, 2, d);
+    mesh.setVertexIndex(T_gamma, 3, e);
+
+    // -----------------------------------------------------------------
+    // Step 6: internal neighbour links between the three new tets.
+    //
+    // Walking each new tet's faces:
+    //   T_alpha = (r, q, d, e):
+    //     slot 0 (opp r) face {q,d,e} — shared with T_gamma's slot 1 (opp p)
+    //     slot 1 (opp q) face {r,d,e} — shared with T_beta's slot 0 (opp p)
+    //     slot 2 (opp d) face {r,q,e} — external, was opposite p in t2
+    //     slot 3 (opp e) face {r,q,d} — external, was opposite p in t1
+    //
+    //   T_beta = (p, r, d, e):
+    //     slot 0 (opp p) face {r,d,e} — shared with T_alpha's slot 1 (opp q)
+    //     slot 1 (opp r) face {p,d,e} — shared with T_gamma's slot 0 (opp q)
+    //     slot 2 (opp d) face {p,r,e} — external, was opposite q in t2
+    //     slot 3 (opp e) face {p,r,d} — external, was opposite q in t1
+    //
+    //   T_gamma = (q, p, d, e):
+    //     slot 0 (opp q) face {p,d,e} — shared with T_beta's slot 1 (opp r)
+    //     slot 1 (opp p) face {q,d,e} — shared with T_alpha's slot 0 (opp r)
+    //     slot 2 (opp d) face {q,p,e} — external, was opposite r in t2
+    //     slot 3 (opp e) face {q,p,d} — external, was opposite r in t1
+    // -----------------------------------------------------------------
+    mesh.setNeighbour(T_alpha, 0, (T_gamma << 2) | 1);
+    mesh.setNeighbour(T_alpha, 1, (T_beta  << 2) | 0);
+    mesh.setNeighbour(T_beta,  0, (T_alpha << 2) | 1);
+    mesh.setNeighbour(T_beta,  1, (T_gamma << 2) | 0);
+    mesh.setNeighbour(T_gamma, 0, (T_beta  << 2) | 1);
+    mesh.setNeighbour(T_gamma, 1, (T_alpha << 2) | 0);
+
+    // -----------------------------------------------------------------
+    // Step 7: external neighbour links. The new tet inherits the SAME
+    // encoded value the old tet held — the neighbour tet ID and its
+    // back-slot don't change. Only the new tet's own slot needs the value.
+    // -----------------------------------------------------------------
+    mesh.setNeighbour(T_alpha, 2, ext_p_t2);
+    mesh.setNeighbour(T_alpha, 3, ext_p_t1);
+    mesh.setNeighbour(T_beta,  2, ext_q_t2);
+    mesh.setNeighbour(T_beta,  3, ext_q_t1);
+    mesh.setNeighbour(T_gamma, 2, ext_r_t2);
+    mesh.setNeighbour(T_gamma, 3, ext_r_t1);
+
+    // -----------------------------------------------------------------
+    // Step 8: rewrite the external neighbours' back-pointers. Each one
+    // currently points at t1 or t2; now they should point at the
+    // corresponding new tet and slot.
+    // -----------------------------------------------------------------
+    rewrite_back_pointer(mesh, ext_p_t2, T_alpha, 2);
+    rewrite_back_pointer(mesh, ext_p_t1, T_alpha, 3);
+    rewrite_back_pointer(mesh, ext_q_t2, T_beta,  2);
+    rewrite_back_pointer(mesh, ext_q_t1, T_beta,  3);
+    rewrite_back_pointer(mesh, ext_r_t2, T_gamma, 2);
+    rewrite_back_pointer(mesh, ext_r_t1, T_gamma, 3);
+
+    out[0] = T_alpha;
+    out[1] = T_beta;
+    out[2] = T_gamma;
+}
+
+/**
+ * Given an encoded neighbour reference (as stored in a tet's neighbour slot)
+ * that used to point at some old tet, rewrite the OTHER end of that link so
+ * it points at `new_tet` at `new_slot` instead. The low 2 bits of the
+ * encoded value tell us the slot in the external tet that holds the
+ * back-pointer.
+ *
+ * No-op if the encoded reference is INVALID_NEIGHBOUR (the old tet had no
+ * neighbour on that face).
+ */
+function rewrite_back_pointer(mesh, encoded, new_tet, new_slot) {
+    if (encoded === INVALID_NEIGHBOUR) return;
+    const ext_tet = encoded >>> 2;
+    const back_slot = encoded & 3;
+    mesh.setNeighbour(ext_tet, back_slot, (new_tet << 2) | new_slot);
+}