@woosh/meep-engine 3.38.0 → 3.39.0

package/src/engine/physics/narrowphase/box_triangle_contact.js

@@ -1,5 +1,5 @@
 import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
-import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
+import { quat3_to_matrix3_array } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
 import { polygon2_clip_axis_halfplane } from "../../../core/geom/2d/polygon/polygon2_clip_axis_halfplane.js";
 import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
 import { box3_projected_half_extent } from "../../../core/geom/3d/box/box3_projected_half_extent.js";
@@ -51,6 +51,10 @@ import { box3_projected_half_extent } from "../../../core/geom/3d/box/box3_proje
  *   out[4 + k*7 + 0..2]     : world contact on triangle surface
  *   out[4 + k*7 + 3..5]     : world contact on box surface
  *   out[4 + k*7 + 6]        : penetration depth (positive)
+ *   out[BOX_TRIANGLE_AXIS_OFFSET] : which kind of axis won —
+ *                             {@link BOX_TRIANGLE_AXIS_BOX_FACE},
+ *                             {@link BOX_TRIANGLE_AXIS_TRIANGLE_FACE} or
+ *                             {@link BOX_TRIANGLE_AXIS_EDGES}
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -75,11 +79,60 @@ const PARALLEL_EPS_SQR = 1e-8;
  */
 const PARALLEL_COS_EPS = 1e-4;
 
+/**
+ * How far to the outside of the reference plane a recovered point may lie and still be taken as on it.
+ * A point on the plane is a contact, at no depth: a box set down exactly on a triangle touches it with
+ * its whole base, as a box floor holds it at the base's four corners. Taken for none, every such point
+ * went to the single-contact fallback, and a 0.2 m box set down on a triangulated floor came to rest
+ * tipped up to 10 mrad, where on a box floor it stays within 0.03 mrad. Rounding puts a point lying on
+ * the plane a hair to either side of it.
+ * @type {number}
+ */
+const ON_PLANE_EPS = 1e-9;
+
+/**
+ * Index in `out` of the kind of axis the contact was built on (written on overlap only).
+ *
+ * The kind is the axis's, not the SAT test's that found it: an edge pair whose cross product lies
+ * within {@link AXIS_FACE_ALIGNMENT} of a face normal is that face's axis met a second time — a box
+ * edge lying in the plane of a triangle crossed with a triangle edge is the triangle's normal — and
+ * which copy wins is rounding. The contacts are then that face's too: its clipped manifold, on its
+ * normal.
+ * @type {number}
+ */
+export const BOX_TRIANGLE_AXIS_OFFSET = 4 + MAX_CONTACTS * CONTACT_STRIDE;
+
+/**
+ * A face of the box is the axis.
+ * @type {number}
+ */
+export const BOX_TRIANGLE_AXIS_BOX_FACE = 0;
+
+/**
+ * The triangle's face is the axis.
+ * @type {number}
+ */
+export const BOX_TRIANGLE_AXIS_TRIANGLE_FACE = 1;
+
+/**
+ * An edge of the box crossed with an edge of the triangle, along no face's normal, is the axis: one
+ * contact, between the two edges.
+ * @type {number}
+ */
+export const BOX_TRIANGLE_AXIS_EDGES = 2;
+
+/**
+ * Cosine within which an edge-pair axis counts as a face's: about 3.6°, the face alignment the support
+ * features use (support_feature_manifold.js).
+ * @type {number}
+ */
+const AXIS_FACE_ALIGNMENT = 0.998;
+
 /**
  * Length of `out` required by {@link box_triangle_contact}.
  * @type {number}
  */
-export const BOX_TRIANGLE_OUT_LENGTH = 4 + MAX_CONTACTS * CONTACT_STRIDE;
+export const BOX_TRIANGLE_OUT_LENGTH = BOX_TRIANGLE_AXIS_OFFSET + 1;
 
 // --- scratch storage (allocation-free across calls) ----------------------------
 
@@ -90,6 +143,10 @@ const scratch_axes = new Float64Array(9);
 const tri_uv_in  = new Float64Array(8 * 2);
 const tri_uv_out = new Float64Array(8 * 2);
 
+// The same, with each point's depth past the face as a third coordinate: (u, v, w).
+const tri_uvw_in  = new Float64Array(8 * 3);
+const tri_uvw_out = new Float64Array(8 * 3);
+
 // Box face corners (for the triangle-axis-winner branch).
 const box_face_corners_uv_in  = new Float64Array(8 * 2);
 const box_face_corners_uv_out = new Float64Array(8 * 2);
@@ -143,6 +200,53 @@ function clip_against_half_plane_uv(points_in, point_count, points_out, line_ox,
     return out_count;
 }
 
+/**
+ * {@link polygon2_clip_axis_halfplane} over points of three coordinates (u, v, w), the third carried
+ * along: clipped against `coord_idx ≤ bound` (`≥` when `keep_below` is false), `coord_idx` 0 or 1. The u
+ * and v of every point are computed as that function computes them, so the same points survive.
+ *
+ * @param {Float64Array} points_in stride 3
+ * @param {number} point_count
+ * @param {Float64Array} points_out stride 3
+ * @param {number} coord_idx 0 = u, 1 = v
+ * @param {number} bound
+ * @param {boolean} keep_below
+ * @returns {number} surviving point count
+ */
+function clip_uvw_axis_halfplane(points_in, point_count, points_out, coord_idx, bound, keep_below) {
+    let out_count = 0;
+
+    for (let i = 0; i < point_count; i++) {
+        const a = i * 3;
+        const b = ((i + 1) % point_count) * 3;
+
+        const av = points_in[a + coord_idx];
+        const bv = points_in[b + coord_idx];
+
+        const a_inside = keep_below ? (av <= bound) : (av >= bound);
+        const b_inside = keep_below ? (bv <= bound) : (bv >= bound);
+
+        if (a_inside) {
+            const o = out_count * 3;
+            points_out[o] = points_in[a];
+            points_out[o + 1] = points_in[a + 1];
+            points_out[o + 2] = points_in[a + 2];
+            out_count++;
+        }
+
+        if (a_inside !== b_inside) {
+            const t = (bound - av) / (bv - av);
+            const o = out_count * 3;
+            points_out[o] = points_in[a] + (points_in[b] - points_in[a]) * t;
+            points_out[o + 1] = points_in[a + 1] + (points_in[b + 1] - points_in[a + 1]) * t;
+            points_out[o + 2] = points_in[a + 2] + (points_in[b + 2] - points_in[a + 2]) * t;
+            out_count++;
+        }
+    }
+
+    return out_count;
+}
+
 /**
  * In-place reduction of `candidates` (stride 7: x, y, z on triangle,
  * x, y, z on box, depth) to at most {@link MAX_CONTACTS} entries.
@@ -163,48 +267,70 @@ function reduce_contacts(n) {
 // `test_axis` used to be a per-call closure — allocated for every
 // box-triangle candidate because it captures and MUTATES the running
 // best-axis accumulator. Hoisted to module scope; the per-call inputs are
-// staged in the g_bt_* slots (written once per call, read by all 13 axis
-// tests). Same arithmetic, same order — bit-identical results.
-
-let g_bt_bcx = 0, g_bt_bcy = 0, g_bt_bcz = 0;
-let g_bt_bhx = 0, g_bt_bhy = 0, g_bt_bhz = 0;
-let g_bt_ax = 0, g_bt_ay = 0, g_bt_az = 0;
-let g_bt_bx = 0, g_bt_by = 0, g_bt_bz = 0;
-let g_bt_cx = 0, g_bt_cy = 0, g_bt_cz = 0;
-let g_bt_d_t2b_x = 0, g_bt_d_t2b_y = 0, g_bt_d_t2b_z = 0;
-let g_bt_best_overlap = Infinity;
-let g_bt_best_nx = 0, g_bt_best_ny = 0, g_bt_best_nz = 0;
+// staged in `bt` (written once per call, read by all 13 axis tests). Same
+// arithmetic, same order — bit-identical results.
+//
+// Staged in a Float64Array, not in module `let`s: a number written to a module
+// `let` is boxed into a new heap object on every write, 21 of them per call.
+// The manifold builders read the same staging, rather than being passed two
+// dozen numbers each: none of them is inlined, and a call that is not inlined
+// boxes every number passed to it.
+
+const BT_BOX_CENTRE = 0;    // x, y, z (world)
+const BT_BOX_HALF = 3;      // x, y, z (body frame)
+const BT_TRI_A = 6;         // x, y, z (world)
+const BT_TRI_B = 9;
+const BT_TRI_C = 12;
+const BT_D_T2B = 15;        // triangle centroid → box centre
+const BT_TRI_NORMAL = 18;   // unit
+const BT_BEST_OVERLAP = 21;
+const BT_BEST_NORMAL = 24;  // unit, triangle → box
+const BT_EDGE_AXIS = 27;    // an edge-pair candidate axis for test_axis
+const BT_FACE_NORMAL = 30;  // the manifold builders' normal, triangle → box
+const BT_FACE_OVERLAP = 33; // and the overlap along it
+const BT_LENGTH = 34;
+
+const bt = new Float64Array(BT_LENGTH);
+
 let g_bt_best_source = -1;
 let g_bt_best_box_edge_idx = -1;
 let g_bt_best_tri_edge_idx = -1;
 
 /**
- * Test a candidate separating axis `(lx, ly, lz)` (need not be unit-length).
+ * Test a candidate separating axis, `axis[axis_offset ..+2]` (need not be unit-length).
  * Returns true if a separating axis is found (overlap < 0); otherwise
- * updates the g_bt_best_* slots if this axis has the smallest overlap so far.
+ * updates the best-axis slots if this axis has the smallest overlap so far.
  *
  * Source:
  *   0..2  : box face normal (axis index 0..2)
  *   3     : triangle face normal
  *   4..12 : edge-cross (box_edge_idx * 3 + tri_edge_idx, offset +4)
+ *
+ * @param {Float64Array} axis
+ * @param {number} axis_offset
+ * @param {number} source
+ * @param {number} box_e_idx
+ * @param {number} tri_e_idx
+ * @returns {boolean}
  */
-function test_axis(lx, ly, lz, source, box_e_idx, tri_e_idx) {
+function test_axis(axis, axis_offset, source, box_e_idx, tri_e_idx) {
+    const lx = axis[axis_offset], ly = axis[axis_offset + 1], lz = axis[axis_offset + 2];
     const len_sqr = lx * lx + ly * ly + lz * lz;
     if (len_sqr <= PARALLEL_EPS_SQR) return false;
     const inv_len = 1 / Math.sqrt(len_sqr);
     const ux = lx * inv_len, uy = ly * inv_len, uz = lz * inv_len;
 
     // Box projection.
-    const box_centre_proj = ux * g_bt_bcx + uy * g_bt_bcy + uz * g_bt_bcz;
-    const r_box = box3_projected_half_extent(scratch_axes, 0, g_bt_bhx, g_bt_bhy, g_bt_bhz, ux, uy, uz);
+    const box_centre_proj = ux * bt[BT_BOX_CENTRE] + uy * bt[BT_BOX_CENTRE + 1] + uz * bt[BT_BOX_CENTRE + 2];
+    const r_box = box3_projected_half_extent(scratch_axes, 0, bt[BT_BOX_HALF], bt[BT_BOX_HALF + 1], bt[BT_BOX_HALF + 2], ux, uy, uz);
     const bmin = box_centre_proj - r_box;
     const bmax = box_centre_proj + r_box;
 
     // Triangle projection — NOT symmetric around centroid, so we take
     // the per-vertex extreme values.
-    const da = ux * g_bt_ax + uy * g_bt_ay + uz * g_bt_az;
-    const db = ux * g_bt_bx + uy * g_bt_by + uz * g_bt_bz;
-    const dc = ux * g_bt_cx + uy * g_bt_cy + uz * g_bt_cz;
+    const da = ux * bt[BT_TRI_A] + uy * bt[BT_TRI_A + 1] + uz * bt[BT_TRI_A + 2];
+    const db = ux * bt[BT_TRI_B] + uy * bt[BT_TRI_B + 1] + uz * bt[BT_TRI_B + 2];
+    const dc = ux * bt[BT_TRI_C] + uy * bt[BT_TRI_C + 1] + uz * bt[BT_TRI_C + 2];
     const tmin = da < db ? (da < dc ? da : dc) : (db < dc ? db : dc);
     const tmax = da > db ? (da > dc ? da : dc) : (db > dc ? db : dc);
 
@@ -219,16 +345,16 @@ function test_axis(lx, ly, lz, source, box_e_idx, tri_e_idx) {
     const push_neg = tmax - bmin;
     const overlap = push_pos < push_neg ? push_pos : push_neg;
 
-    if (overlap < g_bt_best_overlap) {
-        g_bt_best_overlap = overlap;
+    if (overlap < bt[BT_BEST_OVERLAP]) {
+        bt[BT_BEST_OVERLAP] = overlap;
         // Canonical normal direction: triangle -> box. Use the
         // box-centre-vs-triangle-centroid sign as the tiebreaker so
         // the SAT axis is canonically oriented before we negate.
-        const center_dot = g_bt_d_t2b_x * ux + g_bt_d_t2b_y * uy + g_bt_d_t2b_z * uz;
+        const center_dot = bt[BT_D_T2B] * ux + bt[BT_D_T2B + 1] * uy + bt[BT_D_T2B + 2] * uz;
         const sign = center_dot >= 0 ? 1 : -1;
-        g_bt_best_nx = ux * sign;
-        g_bt_best_ny = uy * sign;
-        g_bt_best_nz = uz * sign;
+        bt[BT_BEST_NORMAL] = ux * sign;
+        bt[BT_BEST_NORMAL + 1] = uy * sign;
+        bt[BT_BEST_NORMAL + 2] = uz * sign;
         g_bt_best_source = source;
         g_bt_best_box_edge_idx = box_e_idx;
         g_bt_best_tri_edge_idx = tri_e_idx;
@@ -264,7 +390,45 @@ export function box_triangle_contact(
     bcx, bcy, bcz, bqx, bqy, bqz, bqw, bhx, bhy, bhz,
     ax, ay, az, bx, by, bz, cx, cy, cz
 ) {
-    quat3_to_matrix3(scratch_axes, 0, bqx, bqy, bqz, bqw);
+    const box = scratch_box;
+    const triangle = scratch_triangle;
+
+    box[0] = bcx; box[1] = bcy; box[2] = bcz;
+    box[3] = bqx; box[4] = bqy; box[5] = bqz; box[6] = bqw;
+    box[7] = bhx; box[8] = bhy; box[9] = bhz;
+
+    triangle[0] = ax; triangle[1] = ay; triangle[2] = az;
+    triangle[3] = bx; triangle[4] = by; triangle[5] = bz;
+    triangle[6] = cx; triangle[7] = cy; triangle[8] = cz;
+
+    return box_triangle_contact_array(out, box, 0, triangle, 0);
+}
+
+/** Where {@link box_triangle_contact} packs its box and its triangle. */
+const scratch_box = new Float64Array(10);
+const scratch_triangle = new Float64Array(9);
+
+/**
+ * {@link box_triangle_contact} with the box and the triangle read from arrays: a call V8 does not
+ * inline boxes each number passed to it, nineteen here, once per triangle under a box.
+ *
+ * @param {number[]|Float64Array} out length >= {@link BOX_TRIANGLE_OUT_LENGTH}
+ * @param {Float64Array} box the box: centre (world), orientation (unit quaternion), half-extents (body
+ *   frame) — ten numbers
+ * @param {number} box_offset
+ * @param {Float64Array} triangle vertices A, B, C (world) — nine numbers
+ * @param {number} triangle_offset
+ * @returns {boolean} true if box and triangle overlap
+ */
+export function box_triangle_contact_array(out, box, box_offset, triangle, triangle_offset) {
+    const bcx = box[box_offset], bcy = box[box_offset + 1], bcz = box[box_offset + 2];
+    const bhx = box[box_offset + 7], bhy = box[box_offset + 8], bhz = box[box_offset + 9];
+
+    const ax = triangle[triangle_offset], ay = triangle[triangle_offset + 1], az = triangle[triangle_offset + 2];
+    const bx = triangle[triangle_offset + 3], by = triangle[triangle_offset + 4], bz = triangle[triangle_offset + 5];
+    const cx = triangle[triangle_offset + 6], cy = triangle[triangle_offset + 7], cz = triangle[triangle_offset + 8];
+
+    quat3_to_matrix3_array(scratch_axes, 0, box, box_offset + 3);
     const axes = scratch_axes;
 
     // Triangle edges in world.
@@ -300,25 +464,26 @@ export function box_triangle_contact(
 
     // Stage the per-call inputs + reset the best-axis accumulator for the
     // hoisted test_axis (see the D3 note above it).
-    g_bt_bcx = bcx; g_bt_bcy = bcy; g_bt_bcz = bcz;
-    g_bt_bhx = bhx; g_bt_bhy = bhy; g_bt_bhz = bhz;
-    g_bt_ax = ax; g_bt_ay = ay; g_bt_az = az;
-    g_bt_bx = bx; g_bt_by = by; g_bt_bz = bz;
-    g_bt_cx = cx; g_bt_cy = cy; g_bt_cz = cz;
-    g_bt_d_t2b_x = d_t2b_x; g_bt_d_t2b_y = d_t2b_y; g_bt_d_t2b_z = d_t2b_z;
-    g_bt_best_overlap = Infinity;
-    g_bt_best_nx = 0; g_bt_best_ny = 0; g_bt_best_nz = 0;
+    bt[BT_BOX_CENTRE] = bcx; bt[BT_BOX_CENTRE + 1] = bcy; bt[BT_BOX_CENTRE + 2] = bcz;
+    bt[BT_BOX_HALF] = bhx; bt[BT_BOX_HALF + 1] = bhy; bt[BT_BOX_HALF + 2] = bhz;
+    bt[BT_TRI_A] = ax; bt[BT_TRI_A + 1] = ay; bt[BT_TRI_A + 2] = az;
+    bt[BT_TRI_B] = bx; bt[BT_TRI_B + 1] = by; bt[BT_TRI_B + 2] = bz;
+    bt[BT_TRI_C] = cx; bt[BT_TRI_C + 1] = cy; bt[BT_TRI_C + 2] = cz;
+    bt[BT_D_T2B] = d_t2b_x; bt[BT_D_T2B + 1] = d_t2b_y; bt[BT_D_T2B + 2] = d_t2b_z;
+    bt[BT_TRI_NORMAL] = tnx; bt[BT_TRI_NORMAL + 1] = tny; bt[BT_TRI_NORMAL + 2] = tnz;
+    bt[BT_BEST_OVERLAP] = Infinity;
+    bt[BT_BEST_NORMAL] = 0; bt[BT_BEST_NORMAL + 1] = 0; bt[BT_BEST_NORMAL + 2] = 0;
     g_bt_best_source = -1;
     g_bt_best_box_edge_idx = -1;
     g_bt_best_tri_edge_idx = -1;
 
     // 1. Box face normals (3 axes).
-    if (test_axis(axes[0], axes[1], axes[2], 0, -1, -1)) { out[3] = 0; return false; }
-    if (test_axis(axes[3], axes[4], axes[5], 1, -1, -1)) { out[3] = 0; return false; }
-    if (test_axis(axes[6], axes[7], axes[8], 2, -1, -1)) { out[3] = 0; return false; }
+    if (test_axis(axes, 0, 0, -1, -1)) { out[3] = 0; return false; }
+    if (test_axis(axes, 3, 1, -1, -1)) { out[3] = 0; return false; }
+    if (test_axis(axes, 6, 2, -1, -1)) { out[3] = 0; return false; }
 
     // 2. Triangle face normal (1 axis).
-    if (test_axis(tnx, tny, tnz, 3, -1, -1)) { out[3] = 0; return false; }
+    if (test_axis(bt, BT_TRI_NORMAL, 3, -1, -1)) { out[3] = 0; return false; }
 
     // 3. Edge-edge cross products (9 axes).
     for (let i = 0; i < 3; i++) {
@@ -328,38 +493,129 @@ export function box_triangle_contact(
             if (j === 0)      { ex = ab_x; ey = ab_y; ez = ab_z; }
             else if (j === 1) { ex = bc_x; ey = bc_y; ez = bc_z; }
             else              { ex = ca_x; ey = ca_y; ez = ca_z; }
-            const cx_ax = aiy * ez - aiz * ey;
-            const cy_ax = aiz * ex - aix * ez;
-            const cz_ax = aix * ey - aiy * ex;
-            if (test_axis(cx_ax, cy_ax, cz_ax, 4 + i * 3 + j, i, j)) { out[3] = 0; return false; }
+            bt[BT_EDGE_AXIS] = aiy * ez - aiz * ey;
+            bt[BT_EDGE_AXIS + 1] = aiz * ex - aix * ez;
+            bt[BT_EDGE_AXIS + 2] = aix * ey - aiy * ex;
+            if (test_axis(bt, BT_EDGE_AXIS, 4 + i * 3 + j, i, j)) { out[3] = 0; return false; }
         }
     }
 
     // We have overlap. Output the contact normal (triangle → box).
-    const best_overlap = g_bt_best_overlap;
+    const best_overlap = bt[BT_BEST_OVERLAP];
     const best_source = g_bt_best_source;
     const best_box_edge_idx = g_bt_best_box_edge_idx;
     const best_tri_edge_idx = g_bt_best_tri_edge_idx;
-    const nx = g_bt_best_nx, ny = g_bt_best_ny, nz = g_bt_best_nz;
+    const nx = bt[BT_BEST_NORMAL], ny = bt[BT_BEST_NORMAL + 1], nz = bt[BT_BEST_NORMAL + 2];
     out[0] = nx; out[1] = ny; out[2] = nz;
 
+    // Built on the face the axis is, whichever copy of it won: an edge pair that is a face's axis
+    // again comes out a hair shallower by rounding (or within the alignment), and its two edges'
+    // closest points need not be anywhere near the overlap — a long box's short edge and the
+    // triangle's far edge, metres apart, made one contact that bounced and spun the box.
+    const manifold_source = face_source(best_source, axes);
+
+    out[BOX_TRIANGLE_AXIS_OFFSET] = axis_kind(manifold_source);
+
     // --- Contact manifold construction ---
 
-    if (best_source < 3) {
-        // Box face axis winner: reference = box face, incident = triangle.
-        return emit_box_face_manifold(out, best_source, axes, bcx, bcy, bcz, bhx, bhy, bhz,
-            ax, ay, az, bx, by, bz, cx, cy, cz, tnx, tny, tnz, nx, ny, nz, best_overlap);
-    } else if (best_source === 3) {
+    if (manifold_source < 4) {
+        // On that face's own normal, turned toward the box, and with its own overlap: an edge pair
+        // standing in for it has a normal up to 3.6° off the face's, and a box resting or sliding on a
+        // flat triangulated floor kept landing on that copy — tilted contacts that rocked and kicked it.
+        if (manifold_source !== best_source) {
+            const ux = manifold_source === 3 ? tnx : axes[manifold_source * 3];
+            const uy = manifold_source === 3 ? tny : axes[manifold_source * 3 + 1];
+            const uz = manifold_source === 3 ? tnz : axes[manifold_source * 3 + 2];
+            const s = d_t2b_x * ux + d_t2b_y * uy + d_t2b_z * uz >= 0 ? 1 : -1;
+
+            const fx = ux * s, fy = uy * s, fz = uz * s;
+
+            bt[BT_FACE_NORMAL] = fx; bt[BT_FACE_NORMAL + 1] = fy; bt[BT_FACE_NORMAL + 2] = fz;
+            stage_face_overlap();
+
+            out[0] = fx; out[1] = fy; out[2] = fz;
+        } else {
+            bt[BT_FACE_NORMAL] = nx; bt[BT_FACE_NORMAL + 1] = ny; bt[BT_FACE_NORMAL + 2] = nz;
+            bt[BT_FACE_OVERLAP] = best_overlap;
+        }
+
+        if (manifold_source < 3) {
+            // Box face axis winner: reference = box face, incident = triangle.
+            return emit_box_face_manifold(out, manifold_source, axes);
+        }
+
         // Triangle face axis winner: reference = triangle, incident = box face.
-        return emit_triangle_face_manifold(out, axes, bcx, bcy, bcz, bhx, bhy, bhz,
-            ax, ay, az, bx, by, bz, cx, cy, cz, tnx, tny, tnz, nx, ny, nz, best_overlap);
+        return emit_triangle_face_manifold(out, axes);
     } else {
         // Edge-cross winner: single contact at closest pair on the two edges.
-        return emit_edge_cross_contact(out, axes, bcx, bcy, bcz, bhx, bhy, bhz,
-            ax, ay, az, bx, by, bz, cx, cy, cz,
-            best_box_edge_idx, best_tri_edge_idx,
-            nx, ny, nz, best_overlap);
+        return emit_edge_cross_contact(out, axes, best_box_edge_idx, best_tri_edge_idx);
+    }
+}
+
+/**
+ * Overlap of the staged box and triangle along the unit axis staged at BT_FACE_NORMAL — the amount
+ * {@link test_axis} measures, without touching the running best — written to BT_FACE_OVERLAP. Read
+ * and written there rather than passed and returned: the call is not inlined, and the three numbers
+ * passed and the one returned were each boxed into a new heap object.
+ */
+function stage_face_overlap() {
+    const ux = bt[BT_FACE_NORMAL], uy = bt[BT_FACE_NORMAL + 1], uz = bt[BT_FACE_NORMAL + 2];
+    const box_centre_proj = ux * bt[BT_BOX_CENTRE] + uy * bt[BT_BOX_CENTRE + 1] + uz * bt[BT_BOX_CENTRE + 2];
+    const r_box = box3_projected_half_extent(scratch_axes, 0, bt[BT_BOX_HALF], bt[BT_BOX_HALF + 1], bt[BT_BOX_HALF + 2], ux, uy, uz);
+
+    const da = ux * bt[BT_TRI_A] + uy * bt[BT_TRI_A + 1] + uz * bt[BT_TRI_A + 2];
+    const db = ux * bt[BT_TRI_B] + uy * bt[BT_TRI_B + 1] + uz * bt[BT_TRI_B + 2];
+    const dc = ux * bt[BT_TRI_C] + uy * bt[BT_TRI_C + 1] + uz * bt[BT_TRI_C + 2];
+    const tmin = da < db ? (da < dc ? da : dc) : (db < dc ? db : dc);
+    const tmax = da > db ? (da > dc ? da : dc) : (db > dc ? db : dc);
+
+    const push_pos = box_centre_proj + r_box - tmin;
+    const push_neg = tmax - (box_centre_proj - r_box);
+
+    bt[BT_FACE_OVERLAP] = push_pos < push_neg ? push_pos : push_neg;
+}
+
+/**
+ * Kind of the winning axis, for {@link BOX_TRIANGLE_AXIS_OFFSET}, from the face it is ({@link face_source}).
+ *
+ * @param {number} face SAT source the winning axis really is: 0..2 box face, 3 triangle face, 4..12 edge pair
+ * @returns {number}
+ */
+function axis_kind(face) {
+    if (face < 3) return BOX_TRIANGLE_AXIS_BOX_FACE;
+    if (face === 3) return BOX_TRIANGLE_AXIS_TRIANGLE_FACE;
+
+    return BOX_TRIANGLE_AXIS_EDGES;
+}
+
+/**
+ * The SAT source the winning axis really is. An edge pair (sources 4..12) whose cross product lies
+ * within {@link AXIS_FACE_ALIGNMENT} of the triangle's normal or of a box face's is that face's axis
+ * met a second time: source 3, or the box axis 0..2. Any other source is returned as it is.
+ *
+ * The winning axis and the triangle's normal are the staged ones (`bt`).
+ *
+ * @param {number} source SAT source: 0..2 box face, 3 triangle face, 4..12 edge pair
+ * @param {Float64Array} axes the box's axes, rows
+ * @returns {number}
+ */
+function face_source(source, axes) {
+    if (source < 4) return source;
+
+    const nx = bt[BT_BEST_NORMAL], ny = bt[BT_BEST_NORMAL + 1], nz = bt[BT_BEST_NORMAL + 2];
+    const tnx = bt[BT_TRI_NORMAL], tny = bt[BT_TRI_NORMAL + 1], tnz = bt[BT_TRI_NORMAL + 2];
+
+    if (Math.abs(nx * tnx + ny * tny + nz * tnz) >= AXIS_FACE_ALIGNMENT) {
+        return 3;
+    }
+
+    for (let k = 0; k < 3; k++) {
+        if (Math.abs(nx * axes[k * 3] + ny * axes[k * 3 + 1] + nz * axes[k * 3 + 2]) >= AXIS_FACE_ALIGNMENT) {
+            return k;
+        }
     }
+
+    return source;
 }
 
 // --- Manifold builders ------------------------------------------------------
@@ -368,15 +624,19 @@ export function box_triangle_contact(
  * Box-face SAT winner: clip the triangle against the box's reference face
  * rectangle, then for each surviving (u, v) recover the world contact on
  * the triangle plane.
+ *
+ * Box, triangle, triangle normal, and the face's normal and overlap are the staged ones (`bt`).
  */
-function emit_box_face_manifold(
-    out, ref_axis_idx, axes,
-    bcx, bcy, bcz, bhx, bhy, bhz,
-    ax, ay, az, bx, by, bz, cx, cy, cz,
-    tnx, tny, tnz,
-    nx, ny, nz,
-    best_overlap
-) {
+function emit_box_face_manifold(out, ref_axis_idx, axes) {
+    const bcx = bt[BT_BOX_CENTRE], bcy = bt[BT_BOX_CENTRE + 1], bcz = bt[BT_BOX_CENTRE + 2];
+    const bhx = bt[BT_BOX_HALF], bhy = bt[BT_BOX_HALF + 1], bhz = bt[BT_BOX_HALF + 2];
+    const ax = bt[BT_TRI_A], ay = bt[BT_TRI_A + 1], az = bt[BT_TRI_A + 2];
+    const bx = bt[BT_TRI_B], by = bt[BT_TRI_B + 1], bz = bt[BT_TRI_B + 2];
+    const cx = bt[BT_TRI_C], cy = bt[BT_TRI_C + 1], cz = bt[BT_TRI_C + 2];
+    const tnx = bt[BT_TRI_NORMAL], tny = bt[BT_TRI_NORMAL + 1], tnz = bt[BT_TRI_NORMAL + 2];
+    const nx = bt[BT_FACE_NORMAL], ny = bt[BT_FACE_NORMAL + 1], nz = bt[BT_FACE_NORMAL + 2];
+    const best_overlap = bt[BT_FACE_OVERLAP];
+
     // The contact normal `n` points triangle → box. The box's outward
     // face normal at the reference face points box → triangle = -n.
     const face_out_nx = -nx;
@@ -441,17 +701,16 @@ function emit_box_face_manifold(
     // along the WINNING SAT axis no contact can be deeper than the SAT
     // overlap itself, so candidates past that cap are rejected, and a
     // near-parallel plane (or an emptied candidate set) falls back to the
-    // deepest triangle vertex with the exact SAT depth - a SAT-proven
-    // overlap must never be dropped.
+    // deepest point of the triangle over the face - a SAT-proven overlap
+    // must never be dropped.
     const depth_cap = best_overlap * 1.0001 + 1e-9;
     const denom = face_out_nx * tnx + face_out_ny * tny + face_out_nz * tnz;
     if (Math.abs(denom) < PARALLEL_COS_EPS) {
-        return emit_box_face_deepest_vertex(out,
+        return emit_box_face_deepest_point(out,
             ref_face_ox, ref_face_oy, ref_face_oz,
             face_out_nx, face_out_ny, face_out_nz,
             ux, uy, uz, vx, vy, vz, half_u, half_v,
-            ax, ay, az, bx, by, bz, cx, cy, cz,
-            best_overlap);
+            ax, ay, az, bx, by, bz, cx, cy, cz);
     }
     const clipped_uv = tri_uv_in;
 
@@ -468,7 +727,7 @@ function emit_box_face_manifold(
         const world_tri_y = xpy + face_out_ny * t;
         const world_tri_z = xpz + face_out_nz * t;
         const depth = -t;
-        if (depth <= 0 || depth > depth_cap) continue;
+        if (depth < -ON_PLANE_EPS || depth > depth_cap) continue;
 
         const off = cand_count * 7;
         candidates[off]     = world_tri_x;
@@ -478,17 +737,16 @@ function emit_box_face_manifold(
         candidates[off + 3] = xpx;
         candidates[off + 4] = xpy;
         candidates[off + 5] = xpz;
-        candidates[off + 6] = depth;
+        candidates[off + 6] = depth > 0 ? depth : 0;
         cand_count++;
     }
 
     if (cand_count === 0) {
-        return emit_box_face_deepest_vertex(out,
+        return emit_box_face_deepest_point(out,
             ref_face_ox, ref_face_oy, ref_face_oz,
             face_out_nx, face_out_ny, face_out_nz,
             ux, uy, uz, vx, vy, vz, half_u, half_v,
-            ax, ay, az, bx, by, bz, cx, cy, cz,
-            best_overlap);
+            ax, ay, az, bx, by, bz, cx, cy, cz);
     }
     const kept = reduce_contacts(cand_count);
     out[3] = kept;
@@ -507,41 +765,72 @@ function emit_box_face_manifold(
 }
 
 /**
- * Box-face fallback for configurations the plane recovery cannot serve (the
- * triangle plane near-parallel to the projection direction, or every clipped
- * candidate rejected): one contact at the triangle vertex deepest below the
- * reference face, with the exact SAT overlap as depth. The box witness is
- * the vertex projected onto the face and clamped into the face rectangle.
+ * Box-face fallback for configurations the plane recovery cannot serve (the triangle plane near-parallel
+ * to the projection direction, or every clipped candidate rejected): one contact, at the deepest point
+ * of the triangle over the reference face — the triangle clipped to the face's rectangle as the caller
+ * clipped it, each point carrying its depth past the face — and the point of the face under it. The
+ * depth is that point's, at least 0: the SAT has found the two overlapping, so some point of the
+ * triangle over the face lies on the box's side of it.
+ *
+ * The deepest vertex of the whole triangle can lie anywhere past the rectangle: on a floor triangle
+ * metres long, metres from the box. Clamped into the rectangle, the box's witness then sat that far
+ * from the triangle's, which the manifold took for one contact.
+ *
+ * Only after the caller's clip of the same triangle to the same rectangle kept a point: the clip here
+ * computes u and v as that one does, so it keeps one too.
  */
-function emit_box_face_deepest_vertex(
+function emit_box_face_deepest_point(
     out,
     ref_face_ox, ref_face_oy, ref_face_oz,
     face_out_nx, face_out_ny, face_out_nz,
     ux, uy, uz, vx, vy, vz, half_u, half_v,
-    ax, ay, az, bx, by, bz, cx, cy, cz,
-    best_overlap
+    ax, ay, az, bx, by, bz, cx, cy, cz
 ) {
-    let px = ax, py = ay, pz = az;
-    let best_d = (ref_face_ox - ax) * face_out_nx + (ref_face_oy - ay) * face_out_ny + (ref_face_oz - az) * face_out_nz;
-    const d_b = (ref_face_ox - bx) * face_out_nx + (ref_face_oy - by) * face_out_ny + (ref_face_oz - bz) * face_out_nz;
-    if (d_b > best_d) { best_d = d_b; px = bx; py = by; pz = bz; }
-    const d_c = (ref_face_ox - cx) * face_out_nx + (ref_face_oy - cy) * face_out_ny + (ref_face_oz - cz) * face_out_nz;
-    if (d_c > best_d) { best_d = d_c; px = cx; py = cy; pz = cz; }
-
-    // Project onto the face plane, clamped into the face rectangle.
-    let u = (px - ref_face_ox) * ux + (py - ref_face_oy) * uy + (pz - ref_face_oz) * uz;
-    let v = (px - ref_face_ox) * vx + (py - ref_face_oy) * vy + (pz - ref_face_oz) * vz;
-    u = u < -half_u ? -half_u : (u > half_u ? half_u : u);
-    v = v < -half_v ? -half_v : (v > half_v ? half_v : v);
+    // each corner over the face, (u, v), and its depth past it, w = (face origin - corner) · face_out
+    const da_x = ax - ref_face_ox, da_y = ay - ref_face_oy, da_z = az - ref_face_oz;
+    const db_x = bx - ref_face_ox, db_y = by - ref_face_oy, db_z = bz - ref_face_oz;
+    const dc_x = cx - ref_face_ox, dc_y = cy - ref_face_oy, dc_z = cz - ref_face_oz;
+    tri_uvw_in[0] = da_x * ux + da_y * uy + da_z * uz;
+    tri_uvw_in[1] = da_x * vx + da_y * vy + da_z * vz;
+    tri_uvw_in[2] = -(da_x * face_out_nx + da_y * face_out_ny + da_z * face_out_nz);
+    tri_uvw_in[3] = db_x * ux + db_y * uy + db_z * uz;
+    tri_uvw_in[4] = db_x * vx + db_y * vy + db_z * vz;
+    tri_uvw_in[5] = -(db_x * face_out_nx + db_y * face_out_ny + db_z * face_out_nz);
+    tri_uvw_in[6] = dc_x * ux + dc_y * uy + dc_z * uz;
+    tri_uvw_in[7] = dc_x * vx + dc_y * vy + dc_z * vz;
+    tri_uvw_in[8] = -(dc_x * face_out_nx + dc_y * face_out_ny + dc_z * face_out_nz);
+
+    let n = 3;
+    n = clip_uvw_axis_halfplane(tri_uvw_in, n, tri_uvw_out, 0, half_u, true);
+    n = clip_uvw_axis_halfplane(tri_uvw_out, n, tri_uvw_in, 0, -half_u, false);
+    n = clip_uvw_axis_halfplane(tri_uvw_in, n, tri_uvw_out, 1, half_v, true);
+    n = clip_uvw_axis_halfplane(tri_uvw_out, n, tri_uvw_in, 1, -half_v, false);
+
+    let deepest = 0;
+
+    for (let i = 1; i < n; i++) {
+        if (tri_uvw_in[i * 3 + 2] > tri_uvw_in[deepest * 3 + 2]) {
+            deepest = i;
+        }
+    }
+
+    const u = tri_uvw_in[deepest * 3];
+    const v = tri_uvw_in[deepest * 3 + 1];
+    const w = tri_uvw_in[deepest * 3 + 2];
+
+    // the face's point, and the triangle's: w past it, along the face's outward normal
+    const fx = ref_face_ox + u * ux + v * vx;
+    const fy = ref_face_oy + u * uy + v * vy;
+    const fz = ref_face_oz + u * uz + v * vz;
 
     out[3] = 1;
-    out[4] = px;
-    out[5] = py;
-    out[6] = pz;
-    out[7] = ref_face_ox + u * ux + v * vx;
-    out[8] = ref_face_oy + u * uy + v * vy;
-    out[9] = ref_face_oz + u * uz + v * vz;
-    out[10] = best_overlap;
+    out[4] = fx - face_out_nx * w;
+    out[5] = fy - face_out_ny * w;
+    out[6] = fz - face_out_nz * w;
+    out[7] = fx;
+    out[8] = fy;
+    out[9] = fz;
+    out[10] = w > 0 ? w : 0;
     return true;
 }
 
@@ -549,15 +838,19 @@ function emit_box_face_deepest_vertex(
  * Triangle-face SAT winner: reference = triangle, incident = the box face
  * most antiparallel to the contact normal. Clip the box face quad against
  * the triangle's 3 edges, then recover world contacts on the box face plane.
+ *
+ * Box, triangle, triangle normal, and the face's normal and overlap are the staged ones (`bt`).
  */
-function emit_triangle_face_manifold(
-    out, axes,
-    bcx, bcy, bcz, bhx, bhy, bhz,
-    ax, ay, az, bx, by, bz, cx, cy, cz,
-    tnx, tny, tnz,
-    nx, ny, nz,
-    best_overlap
-) {
+function emit_triangle_face_manifold(out, axes) {
+    const bcx = bt[BT_BOX_CENTRE], bcy = bt[BT_BOX_CENTRE + 1], bcz = bt[BT_BOX_CENTRE + 2];
+    const bhx = bt[BT_BOX_HALF], bhy = bt[BT_BOX_HALF + 1], bhz = bt[BT_BOX_HALF + 2];
+    const ax = bt[BT_TRI_A], ay = bt[BT_TRI_A + 1], az = bt[BT_TRI_A + 2];
+    const bx = bt[BT_TRI_B], by = bt[BT_TRI_B + 1], bz = bt[BT_TRI_B + 2];
+    const cx = bt[BT_TRI_C], cy = bt[BT_TRI_C + 1], cz = bt[BT_TRI_C + 2];
+    const tnx = bt[BT_TRI_NORMAL], tny = bt[BT_TRI_NORMAL + 1], tnz = bt[BT_TRI_NORMAL + 2];
+    const nx = bt[BT_FACE_NORMAL], ny = bt[BT_FACE_NORMAL + 1], nz = bt[BT_FACE_NORMAL + 2];
+    const best_overlap = bt[BT_FACE_OVERLAP];
+
     // Reference = triangle. Its outward face normal points from the triangle
     // surface toward the box — i.e. the contact normal `n` (triangle → box),
     // which the SAT already sign-canonicalised. The incident box face is then
@@ -725,7 +1018,7 @@ function emit_triangle_face_manifold(
         // Depth: how far the box face has penetrated past the triangle
         // plane, measured along ref_out. depth = -t.
         const depth = -t;
-        if (depth <= 0 || depth > depth_cap) continue;
+        if (depth < -ON_PLANE_EPS || depth > depth_cap) continue;
 
         const off = cand_count * 7;
         // Triangle-side contact: the clipped (u, v) point on the
@@ -736,7 +1029,7 @@ function emit_triangle_face_manifold(
         candidates[off + 3] = world_box_x;
         candidates[off + 4] = world_box_y;
         candidates[off + 5] = world_box_z;
-        candidates[off + 6] = depth;
+        candidates[off + 6] = depth > 0 ? depth : 0;
         cand_count++;
     }
 
@@ -824,14 +1117,16 @@ function emit_triangle_face_deepest_corner(
     return true;
 }
 
-function emit_edge_cross_contact(
-    out, axes,
-    bcx, bcy, bcz, bhx, bhy, bhz,
-    ax, ay, az, bx, by, bz, cx, cy, cz,
-    box_edge_idx, tri_edge_idx,
-    nx, ny, nz,
-    overlap
-) {
+function emit_edge_cross_contact(out, axes, box_edge_idx, tri_edge_idx) {
+    // box, triangle, and the winning normal and overlap: the staged ones
+    const bcx = bt[BT_BOX_CENTRE], bcy = bt[BT_BOX_CENTRE + 1], bcz = bt[BT_BOX_CENTRE + 2];
+    const bhx = bt[BT_BOX_HALF], bhy = bt[BT_BOX_HALF + 1], bhz = bt[BT_BOX_HALF + 2];
+    const ax = bt[BT_TRI_A], ay = bt[BT_TRI_A + 1], az = bt[BT_TRI_A + 2];
+    const bx = bt[BT_TRI_B], by = bt[BT_TRI_B + 1], bz = bt[BT_TRI_B + 2];
+    const cx = bt[BT_TRI_C], cy = bt[BT_TRI_C + 1], cz = bt[BT_TRI_C + 2];
+    const nx = bt[BT_BEST_NORMAL], ny = bt[BT_BEST_NORMAL + 1], nz = bt[BT_BEST_NORMAL + 2];
+    const overlap = bt[BT_BEST_OVERLAP];
+
     // Box edge direction: axis index `box_edge_idx`.
     const edx = axes[box_edge_idx * 3];
     const edy = axes[box_edge_idx * 3 + 1];