@woosh/meep-engine 2.138.20 → 2.140.0

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

@@ -0,0 +1,1422 @@
+import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
+import { Triangle3D } from "../../../core/geom/3d/shape/Triangle3D.js";
+import { body_id_index } from "../body/BodyStorage.js";
+import { CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
+import { expanding_polytope_algorithm } from "../gjk/expanding_polytope_algorithm.js";
+import { gjk_with_axis } from "../gjk/gjk.js";
+import { mpr } from "../gjk/mpr.js";
+import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
+import { box_triangle_contact, BOX_TRIANGLE_OUT_LENGTH } from "./box_triangle_contact.js";
+import {
+    CAPSULE_BOX_CONTACT_STRIDE,
+    CAPSULE_BOX_MAX_CONTACTS,
+    capsule_box_multi_contacts,
+    capsule_capsule_contact,
+    capsule_sphere_contact,
+} from "./capsule_contacts.js";
+import {
+    capsule_triangle_contact,
+    CAPSULE_TRIANGLE_CONTACT_STRIDE,
+    CAPSULE_TRIANGLE_MAX_CONTACTS,
+} from "./capsule_triangle_contact.js";
+import { aabb_world_to_local } from "./decomposition/aabb_world_to_local.js";
+import { decompose_to_triangles } from "./decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
+import { PosedShape } from "./PosedShape.js";
+import { sphere_box_contact } from "./sphere_box_contact.js";
+import { sphere_sphere_contact } from "./sphere_sphere_contact.js";
+import { sphere_triangle_contact } from "./sphere_triangle_contact.js";
+
+const posed_a = new PosedShape();
+const posed_b = new PosedShape();
+
+// Float64 simplex buffer. The simplex stores Minkowski-difference
+// support points that GJK accumulates across up to 64 iterations and
+// then hands to EPA for further refinement; precision loss here
+// compounds through every subsequent dot / cross / normal calculation
+// in the polytope expansion, so keep the full 53-bit mantissa.
+const simplex_buf = new Float64Array(12);
+const simplex_a = simplex_buf.subarray(0, 3);
+const simplex_b = simplex_buf.subarray(3, 6);
+const simplex_c = simplex_buf.subarray(6, 9);
+const simplex_d = simplex_buf.subarray(9, 12);
+
+const epa_result = new Float64Array(3);
+const sphere_result = new Float64Array(4);
+const closed_form_result = new Float64Array(10);
+const sphere_triangle_result = new Float64Array(10);
+const box_triangle_result = new Float64Array(BOX_TRIANGLE_OUT_LENGTH);
+const capsule_triangle_result = new Float64Array(CAPSULE_TRIANGLE_MAX_CONTACTS * CAPSULE_TRIANGLE_CONTACT_STRIDE);
+const box_manifold_result = new Float64Array(BOX_BOX_OUT_LENGTH);
+const capsule_box_multi_result = new Float64Array(CAPSULE_BOX_MAX_CONTACTS * CAPSULE_BOX_CONTACT_STRIDE);
+
+/**
+ * Candidate-contact stride: wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth,
+ * feature_id.
+ *
+ * The `feature_id` (offset 10) is a stable cross-frame identifier of the
+ * geometric feature pair that produced this contact — used by the
+ * match-and-merge pass in {@link narrowphase_step} to carry warm-start
+ * impulses from the previous frame's manifold to the slot index that
+ * corresponds to the same physical contact. A value of 0 means
+ * "no feature info, fall back to position matching".
+ *
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 11;
+
+/**
+ * Maximum number of contacts emitted into the per-pair manifold after the
+ * reduction step. Mirrors {@link MAX_CONTACTS_PER_MANIFOLD} in ManifoldStore.
+ * @type {number}
+ */
+const MAX_KEPT = MAX_CONTACTS_PER_MANIFOLD;
+
+/**
+ * Position-fallback tolerance for warm-start matching: when a candidate
+ * contact has no feature id (or none of the previous-frame contacts shares
+ * its id), match by closest world_a within this 3-D distance.
+ *
+ * 2 cm matches the original PLAN.md spec for "Persistent manifold cache"
+ * — generous enough to follow small inter-frame contact migration on
+ * curved surfaces, tight enough that distinct contacts on a single
+ * manifold (typically >5 cm apart) don't get confused with each other.
+ *
+ * @type {number}
+ */
+const MATCH_TOL_SQR = 0.02 * 0.02;
+
+/**
+ * Scratch for the previous-frame contact snapshot taken at the top of the
+ * match-and-merge pass. Sized for {@link MAX_CONTACTS_PER_MANIFOLD}
+ * contacts, 7 floats per contact:
+ *   0       : feature_id
+ *   1, 2, 3 : world_a x, y, z  (for position-fallback matching)
+ *   4, 5, 6 : j_n, j_t1, j_t2  (carried forward to the matched candidate)
+ *
+ * Snapshotting upfront decouples the read (from the slot's previous state)
+ * from the write (the new contact data + impulse copy), avoiding the
+ * read-after-write hazard when the matching mapping shuffles indices.
+ *
+ * @type {Float64Array}
+ */
+const prev_snapshot = new Float64Array(MAX_CONTACTS_PER_MANIFOLD * 7);
+
+/**
+ * Per-prev-contact "already claimed by a candidate" flag.
+ * @type {Uint8Array}
+ */
+const prev_claimed = new Uint8Array(MAX_CONTACTS_PER_MANIFOLD);
+
+/**
+ * For each kept candidate, the matched prev-contact index in
+ * `[0, prev_count)` or `-1` if no match.
+ * @type {Int32Array}
+ */
+const cand_to_prev = new Int32Array(MAX_KEPT);
+
+/**
+ * Per body-pair scratch buffer for candidate contacts produced by the
+ * cross-product of A's colliders × B's colliders. Sized generously for
+ * typical compound bodies (each collider-pair contributes 1..4 contacts;
+ * 64 covers up to 4 colliders per body × 4 colliders × 4 contacts = 64).
+ * @type {Float64Array}
+ */
+const candidates = new Float64Array(64 * CANDIDATE_STRIDE);
+
+/**
+ * Maximum triangles a concave-side enumerator can produce per pair.
+ * The query AABB is bounded by the broadphase's fattened envelope of
+ * the convex-side body, so a single concave-vs-convex pair typically
+ * yields tens of triangles, not thousands. 1024 is the safety cap.
+ *
+ * If an enumerator's output would exceed this, the extra triangles are
+ * silently dropped by the enumerator's bounds-check on the output
+ * array — the worst case is a missed contact on a far edge of the
+ * filtered region, which the next-step rebroadphase corrects.
+ *
+ * @type {number}
+ */
+const MAX_TRIANGLES_PER_PAIR = 1024;
+
+/**
+ * Per-pair scratch for the concave-side triangle decomposition.
+ * @type {Float64Array}
+ */
+const triangle_buffer = new Float64Array(MAX_TRIANGLES_PER_PAIR * TRIANGLE_FLOAT_STRIDE);
+
+/**
+ * Flyweight triangle shape — rebound to each successive triangle slice
+ * of `triangle_buffer` during the concave-side dispatch loop. Zero
+ * allocation per triangle.
+ * @type {Triangle3D}
+ */
+const triangle_shape = new Triangle3D();
+
+/**
+ * Scratch AABB buffers used only by the concave-side dispatch:
+ *   - `concave_local_aabb`  : convex shape's local AABB (input to oriented transform)
+ *   - `concave_world_aabb`  : convex shape's world AABB
+ *   - `concave_query_aabb`  : convex shape's AABB projected into concave's body-local frame
+ *                             (what the triangle enumerator filters against)
+ */
+const concave_local_aabb = new Float64Array(6);
+const concave_world_aabb = new Float64Array(6);
+const concave_query_aabb = new Float64Array(6);
+
+/**
+ * Append one contact to the candidate buffer. Returns the new count.
+ *
+ * @param {number} count
+ * @param {number} wax
+ * @param {number} way
+ * @param {number} waz
+ * @param {number} wbx
+ * @param {number} wby
+ * @param {number} wbz
+ * @param {number} nx
+ * @param {number} ny
+ * @param {number} nz
+ * @param {number} depth
+ * @param {number} feature_id stable cross-frame ID for warm-start matching;
+ *   `0` means no info — match-and-merge will fall back to position.
+ * @returns {number}
+ */
+function append_contact(count, wax, way, waz, wbx, wby, wbz, nx, ny, nz, depth, feature_id) {
+    if (count * CANDIDATE_STRIDE >= candidates.length){
+        return count;
+    }
+
+    const off = count * CANDIDATE_STRIDE;
+
+    candidates[off]     = wax; candidates[off + 1] = way; candidates[off + 2] = waz;
+    candidates[off + 3] = wbx; candidates[off + 4] = wby; candidates[off + 5] = wbz;
+    candidates[off + 6] = nx;  candidates[off + 7] = ny;  candidates[off + 8] = nz;
+    candidates[off + 9] = depth;
+    candidates[off + 10] = feature_id;
+
+    return count + 1;
+}
+
+function swap_candidate(i, j) {
+    if (i === j){
+        return;
+    }
+
+    const oi = i * CANDIDATE_STRIDE;
+    const oj = j * CANDIDATE_STRIDE;
+
+    for (let k = 0; k < CANDIDATE_STRIDE; k++) {
+        const t = candidates[oi + k];
+        candidates[oi + k] = candidates[oj + k];
+        candidates[oj + k] = t;
+    }
+}
+
+/**
+ * Compute a stable voronoi-region feature id for a sphere-vs-box contact.
+ * Returns one of 27 values in `[1, 27]` based on which of the 27 voronoi
+ * regions of the box the sphere centre lies in (8 corners + 12 edges + 6
+ * faces + 1 interior). Stable across frames as long as the sphere stays
+ * in the same region — the typical case in steady-state contact.
+ *
+ * Encodes:
+ *   bucket_x ∈ {0, 1, 2} = sign(lx) bucket in box-local frame
+ *   bucket_y, bucket_z similarly
+ *   fid = 1 + bucket_x + 3·bucket_y + 9·bucket_z   →   1..27
+ *
+ * The "+1" offset ensures the result is never 0, since 0 is reserved
+ * for "no feature info, use position-fallback".
+ *
+ * @param {number} sx sphere centre x
+ * @param {number} sy
+ * @param {number} sz
+ * @param {number} bx box centre x
+ * @param {number} by
+ * @param {number} bz
+ * @param {number} bqx box quaternion x
+ * @param {number} bqy
+ * @param {number} bqz
+ * @param {number} bqw
+ * @param {number} hx box half-extent x
+ * @param {number} hy
+ * @param {number} hz
+ * @returns {number}
+ */
+function sphere_box_voronoi_fid(sx, sy, sz, bx, by, bz, bqx, bqy, bqz, bqw, hx, hy, hz) {
+    // Inverse-rotate (sx - bx, sy - by, sz - bz) by the box's quaternion
+    // to get the sphere centre in box-local frame. Inlined for the same
+    // V8-inliner reason described in PosedShape.support — see
+    // core/geom/vec3/v3_quat3_apply_inverse.js for the canonical form.
+    const dx = sx - bx;
+    const dy = sy - by;
+    const dz = sz - bz;
+
+    const tx0 = bqw * dx - bqy * dz + bqz * dy;
+    const ty0 = bqw * dy - bqz * dx + bqx * dz;
+    const tz0 = bqw * dz - bqx * dy + bqy * dx;
+    const tw0 = bqx * dx + bqy * dy + bqz * dz;
+
+    const lx = tx0 * bqw + tw0 * bqx + ty0 * bqz - tz0 * bqy;
+    const ly = ty0 * bqw + tw0 * bqy + tz0 * bqx - tx0 * bqz;
+    const lz = tz0 * bqw + tw0 * bqz + tx0 * bqy - ty0 * bqx;
+
+    const bx_b = lx <= -hx ? 0 : (lx >= hx ? 2 : 1);
+    const by_b = ly <= -hy ? 0 : (ly >= hy ? 2 : 1);
+    const bz_b = lz <= -hz ? 0 : (lz >= hz ? 2 : 1);
+
+    return 1 + bx_b + 3 * by_b + 9 * bz_b;
+}
+
+/**
+ * Reduce an in-place candidate list to at most {@link MAX_KEPT} entries:
+ *   1. Move the deepest to slot 0.
+ *   2. For each subsequent slot, pick the remaining candidate whose minimum
+ *      distance to the already-kept set is largest (approximates max-area).
+ *
+ * @param {number} n
+ * @returns {number} kept count, in [0, min(n, MAX_KEPT)]
+ */
+function reduce_candidates(n) {
+    if (n <= MAX_KEPT){
+        return n;
+    }
+
+    // Move deepest to slot 0.
+    let deepest_idx = 0;
+    let deepest_val = candidates[9];
+
+    for (let i = 1; i < n; i++) {
+
+        const d = candidates[i * CANDIDATE_STRIDE + 9];
+
+        if (d > deepest_val) {
+            deepest_val = d; deepest_idx = i;
+        }
+    }
+
+    swap_candidate(0, deepest_idx);
+
+    for (let k = 1; k < MAX_KEPT; k++) {
+
+        let best_score = -1;
+        let best_i = -1;
+
+        for (let i = k; i < n; i++) {
+            let min_d2 = Infinity;
+
+            for (let j = 0; j < k; j++) {
+
+                const dx = candidates[i * CANDIDATE_STRIDE]     - candidates[j * CANDIDATE_STRIDE];
+                const dy = candidates[i * CANDIDATE_STRIDE + 1] - candidates[j * CANDIDATE_STRIDE + 1];
+                const dz = candidates[i * CANDIDATE_STRIDE + 2] - candidates[j * CANDIDATE_STRIDE + 2];
+                const d2 = dx * dx + dy * dy + dz * dz;
+
+                if (d2 < min_d2){
+                    min_d2 = d2;
+                }
+            }
+
+            if (min_d2 > best_score) {
+                best_score = min_d2;
+                best_i = i;
+            }
+
+        }
+
+        swap_candidate(k, best_i);
+    }
+
+    return MAX_KEPT;
+}
+
+/**
+ * Run pairwise narrowphase for one (colliderA, colliderB) tuple — dispatches
+ * by shape type and appends 0..K contacts to the candidate buffer. Returns
+ * the new candidate count.
+ *
+ * The optional `gjk_axis_buf` + `gjk_axis_off` arguments thread the
+ * manifold's cached separating axis through to the GJK + EPA fallback
+ * paths. Closed-form paths (sphere/box/capsule × sphere/box/capsule
+ * and the three concave fast-paths) don't use GJK and ignore them. As
+ * of P2.1 step 4 these are plumbed but not yet activated — the GJK
+ * call sites still use the cache-less `gjk(simplex, A, B)`; step 5
+ * flips one of them.
+ *
+ * @param {number} count
+ * @param {Collider} colA
+ * @param {Transform} trA
+ * @param {Collider} colB
+ * @param {Transform} trB
+ * @param {Float64Array|null} [gjk_axis_buf] per-slot cached-axis buffer
+ *   (`manifolds.slot_axis_buffer`) or `null` for cold-start every call.
+ * @param {number} [gjk_axis_off] offset into the buffer; pass
+ *   `manifolds.slot_axis_offset(slot)`.
+ * @returns {number}
+ */
+function dispatch_pair(count, colA, trA, colB, trB, gjk_axis_buf = null, gjk_axis_off = 0) {
+    const shapeA = colA.shape;
+    const shapeB = colB.shape;
+
+    const isSphereA = shapeA.isUnitSphereShape3D === true;
+    const isSphereB = shapeB.isUnitSphereShape3D === true;
+    // isBoxShape3D covers both UnitCubeShape3D (fixed 0.5) and BoxShape3D
+    // (arbitrary half-extents). Both expose `half_extents` as a Vector3.
+    const isBoxA    = shapeA.isBoxShape3D        === true;
+    const isBoxB    = shapeB.isBoxShape3D        === true;
+    const isCapsuleA = shapeA.isCapsuleShape3D   === true;
+    const isCapsuleB = shapeB.isCapsuleShape3D   === true;
+
+    // sphere-sphere
+    if (isSphereA && isSphereB) {
+
+        const ok = sphere_sphere_contact(
+            sphere_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trB.position.x, trB.position.y, trB.position.z,
+            1, 1
+        );
+
+        if (!ok) return count;
+
+        const nx = sphere_result[0], ny = sphere_result[1], nz = sphere_result[2];
+
+        // Sphere-sphere produces exactly one contact per pair; fid = 1
+        // identifies it as a real feature (distinguishes from "no info" = 0)
+        // and is trivially stable across frames.
+        return append_contact(count,
+            trA.position.x - nx, trA.position.y - ny, trA.position.z - nz,
+            trB.position.x + nx, trB.position.y + ny, trB.position.z + nz,
+            nx, ny, nz, sphere_result[3], 1);
+    }
+
+    // sphere ↔ box
+    if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
+        const sphereTr = isSphereA ? trA : trB;
+        const boxTr    = isSphereA ? trB : trA;
+        const boxShape = isSphereA ? shapeB : shapeA;
+        const bh = boxShape.half_extents;
+
+        const ok = sphere_box_contact(
+            closed_form_result,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1,
+            boxTr.position.x, boxTr.position.y, boxTr.position.z,
+            boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+
+        if (!ok) return count;
+
+        let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
+
+        const depth = closed_form_result[3];
+        const wsx = closed_form_result[4], wsy = closed_form_result[5], wsz = closed_form_result[6];
+        const wbx = closed_form_result[7], wby = closed_form_result[8], wbz = closed_form_result[9];
+        // Feature id from the box-local voronoi region (1..27) — stable
+        // while the sphere stays on the same face / edge / vertex of the
+        // box, which is the steady-state case for resting / sliding contact.
+
+        const fid = sphere_box_voronoi_fid(
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z,
+            boxTr.position.x, boxTr.position.y, boxTr.position.z,
+            boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+
+        if (isSphereA) {
+            return append_contact(count, wsx, wsy, wsz, wbx, wby, wbz, nx, ny, nz, depth, fid);
+        } else {
+            return append_contact(count, wbx, wby, wbz, wsx, wsy, wsz, -nx, -ny, -nz, depth, fid);
+        }
+    }
+
+    // box-box multi-point
+    if (isBoxA && isBoxB) {
+        const ah = shapeA.half_extents;
+        const bh = shapeB.half_extents;
+        const ok = box_box_manifold(
+            box_manifold_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w,
+            ah.x, ah.y, ah.z,
+            trB.position.x, trB.position.y, trB.position.z,
+            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+        if (!ok) return count;
+        const nx = box_manifold_result[0], ny = box_manifold_result[1], nz = box_manifold_result[2];
+        const cc = box_manifold_result[3] | 0;
+        // Box-box manifolds: closed-form clipping doesn't expose stable
+        // per-contact feature ids (a contact migrates from "incident-vertex k"
+        // to "clip-intersection on edge j" as the boxes rotate). Leave
+        // fid = 0 so the match-and-merge pass uses position-fallback —
+        // the per-contact clipped points are spread by face geometry and
+        // typically stay >>MATCH_TOL apart, so position matching is
+        // unambiguous frame-to-frame.
+        for (let k = 0; k < cc; k++) {
+            const base = 4 + k * 7;
+            count = append_contact(count,
+                box_manifold_result[base],     box_manifold_result[base + 1], box_manifold_result[base + 2],
+                box_manifold_result[base + 3], box_manifold_result[base + 4], box_manifold_result[base + 5],
+                nx, ny, nz,
+                box_manifold_result[base + 6],
+                0);
+        }
+        return count;
+    }
+
+    // capsule-capsule
+    if (isCapsuleA && isCapsuleB) {
+        const a_shape = colA.shape, b_shape = colB.shape;
+        const ok = capsule_capsule_contact(
+            closed_form_result,
+            trA.position.x, trA.position.y, trA.position.z,
+            trA.rotation.x, trA.rotation.y, trA.rotation.z, trA.rotation.w,
+            a_shape.radius, a_shape.height * 0.5,
+            trB.position.x, trB.position.y, trB.position.z,
+            trB.rotation.x, trB.rotation.y, trB.rotation.z, trB.rotation.w,
+            b_shape.radius, b_shape.height * 0.5
+        );
+        if (!ok) return count;
+        // Single contact per capsule-capsule pair; fid = 1 (stable, real feature).
+        return append_contact(count,
+            closed_form_result[4], closed_form_result[5], closed_form_result[6],
+            closed_form_result[7], closed_form_result[8], closed_form_result[9],
+            closed_form_result[0], closed_form_result[1], closed_form_result[2],
+            closed_form_result[3], 1);
+    }
+
+    // capsule ↔ sphere
+    if ((isCapsuleA && isSphereB) || (isSphereA && isCapsuleB)) {
+        const capsuleTr = isCapsuleA ? trA : trB;
+        const capsuleShape = isCapsuleA ? colA.shape : colB.shape;
+        const sphereTr    = isCapsuleA ? trB : trA;
+        const ok = capsule_sphere_contact(
+            closed_form_result,
+            capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
+            capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
+            capsuleShape.radius, capsuleShape.height * 0.5,
+            sphereTr.position.x, sphereTr.position.y, sphereTr.position.z, 1
+        );
+        if (!ok) return count;
+        let nx = closed_form_result[0], ny = closed_form_result[1], nz = closed_form_result[2];
+        const depth = closed_form_result[3];
+        const cap_x = closed_form_result[4], cap_y = closed_form_result[5], cap_z = closed_form_result[6];
+        const sph_x = closed_form_result[7], sph_y = closed_form_result[8], sph_z = closed_form_result[9];
+        // Single contact per capsule-sphere pair; fid = 1.
+        if (isCapsuleA) {
+            return append_contact(count, cap_x, cap_y, cap_z, sph_x, sph_y, sph_z, nx, ny, nz, depth, 1);
+        } else {
+            return append_contact(count, sph_x, sph_y, sph_z, cap_x, cap_y, cap_z, -nx, -ny, -nz, depth, 1);
+        }
+    }
+
+    // capsule ↔ box (multi-point — 1 closest-segment + up to 2 cap-centres)
+    if ((isCapsuleA && isBoxB) || (isBoxA && isCapsuleB)) {
+        const capsuleTr = isCapsuleA ? trA : trB;
+        const capsuleShape = isCapsuleA ? shapeA : shapeB;
+        const boxTr       = isCapsuleA ? trB : trA;
+        const boxShape    = isCapsuleA ? shapeB : shapeA;
+        const bh = boxShape.half_extents;
+        const cc = capsule_box_multi_contacts(
+            capsule_box_multi_result,
+            capsuleTr.position.x, capsuleTr.position.y, capsuleTr.position.z,
+            capsuleTr.rotation.x, capsuleTr.rotation.y, capsuleTr.rotation.z, capsuleTr.rotation.w,
+            capsuleShape.radius, capsuleShape.height * 0.5,
+            boxTr.position.x, boxTr.position.y, boxTr.position.z,
+            boxTr.rotation.x, boxTr.rotation.y, boxTr.rotation.z, boxTr.rotation.w,
+            bh.x, bh.y, bh.z
+        );
+        if (cc === 0) return count;
+        // multi_result layout per contact: cap_x/y/z (A side), box_x/y/z (B side), nx/ny/nz, depth.
+        // Feature id per sub-contact: 1 = closest-segment, 2/3 = caps. The
+        // emission order from capsule_box_multi_contacts is stable across
+        // frames for the same geometric configuration.
+        for (let k = 0; k < cc; k++) {
+            const o = k * CAPSULE_BOX_CONTACT_STRIDE;
+            const cap_x = capsule_box_multi_result[o];
+            const cap_y = capsule_box_multi_result[o + 1];
+            const cap_z = capsule_box_multi_result[o + 2];
+            const box_x = capsule_box_multi_result[o + 3];
+            const box_y = capsule_box_multi_result[o + 4];
+            const box_z = capsule_box_multi_result[o + 5];
+            const nx    = capsule_box_multi_result[o + 6];
+            const ny    = capsule_box_multi_result[o + 7];
+            const nz    = capsule_box_multi_result[o + 8];
+            const depth = capsule_box_multi_result[o + 9];
+            const sub_fid = k + 1;
+            if (isCapsuleA) {
+                count = append_contact(count, cap_x, cap_y, cap_z, box_x, box_y, box_z, nx, ny, nz, depth, sub_fid);
+            } else {
+                count = append_contact(count, box_x, box_y, box_z, cap_x, cap_y, cap_z, -nx, -ny, -nz, depth, sub_fid);
+            }
+        }
+        return count;
+    }
+
+    // ── Concave (non-convex) path ───────────────────────────────────────
+    //
+    // If either shape has `is_convex === false`, GJK on the whole shape
+    // produces incorrect results (Minkowski difference is not convex).
+    // We decompose the concave side into triangles overlapping the
+    // convex side's AABB, then run convex per-triangle GJK + EPA.
+    //
+    // Concave-vs-concave is intentionally NOT supported in v1: the
+    // M×N triangle pairs would dominate runtime, and the physics
+    // engine's design contract requires at least one side to be
+    // static / kinematic for concave shapes anyway (the broadphase +
+    // filter should keep such pairs out of the narrowphase entirely).
+    // If one slips through, we skip rather than burn cycles.
+    const isConcaveA = shapeA.is_convex === false;
+    const isConcaveB = shapeB.is_convex === false;
+    if (isConcaveA && isConcaveB) return count;
+    if (isConcaveA || isConcaveB) {
+        const concave_col = isConcaveA ? colA : colB;
+        const concave_tr  = isConcaveA ? trA : trB;
+        const convex_col  = isConcaveA ? colB : colA;
+        const convex_tr   = isConcaveA ? trB : trA;
+
+        // 1. Convex shape's world AABB.
+        convex_col.shape.compute_bounding_box(concave_local_aabb);
+        aabb3_transform_oriented(
+            concave_world_aabb, 0,
+            concave_local_aabb[0], concave_local_aabb[1], concave_local_aabb[2],
+            concave_local_aabb[3], concave_local_aabb[4], concave_local_aabb[5],
+            convex_tr.position.x, convex_tr.position.y, convex_tr.position.z,
+            convex_tr.rotation.x, convex_tr.rotation.y, convex_tr.rotation.z, convex_tr.rotation.w
+        );
+
+        // 2. Project into concave's body-local frame.
+        aabb_world_to_local(
+            concave_query_aabb, 0,
+            concave_world_aabb,
+            concave_tr.position.x, concave_tr.position.y, concave_tr.position.z,
+            concave_tr.rotation.x, concave_tr.rotation.y, concave_tr.rotation.z, concave_tr.rotation.w
+        );
+
+        // 3. Decompose concave shape into triangles overlapping the query.
+        const tri_count = decompose_to_triangles(
+            triangle_buffer, 0, concave_col.shape,
+            concave_query_aabb[0], concave_query_aabb[1], concave_query_aabb[2],
+            concave_query_aabb[3], concave_query_aabb[4], concave_query_aabb[5]
+        );
+        if (tri_count === 0) return count;
+
+        // 4. Set up the convex side once; the concave side gets a
+        //    Triangle3D rebound to each triangle in the loop. We keep
+        //    the concave side as our internal "A" so EPA's sign-check
+        //    convention matches the convex fallback below; the final
+        //    append_contact() swaps if the original A was the convex one.
+        posed_b.setup(convex_col.shape, convex_tr.position, convex_tr.rotation);
+        posed_a.shape = triangle_shape;
+        posed_a.px = concave_tr.position.x;
+        posed_a.py = concave_tr.position.y;
+        posed_a.pz = concave_tr.position.z;
+        posed_a.qx = concave_tr.rotation.x;
+        posed_a.qy = concave_tr.rotation.y;
+        posed_a.qz = concave_tr.rotation.z;
+        posed_a.qw = concave_tr.rotation.w;
+
+        // Pre-compute the centre-axis used by EPA's sign-check loop.
+        // For convex-vs-convex this is `(B - A) = convex_centre − concave_centre`.
+        const convex_wx = convex_tr.position.x;
+        const convex_wy = convex_tr.position.y;
+        const convex_wz = convex_tr.position.z;
+
+        // Track the candidate-buffer index at the start of this
+        // concave dispatch — the per-triangle dedup pass scans from
+        // here to the current count, ignoring contacts from earlier
+        // collider pairs in the same body pair.
+        const pair_start_count = count;
+
+        // Pre-compute concave's rotation components for the q · v · q⁻¹
+        // rotations done per-triangle below (face normal + centroid).
+        const cqx = concave_tr.rotation.x;
+        const cqy = concave_tr.rotation.y;
+        const cqz = concave_tr.rotation.z;
+        const cqw = concave_tr.rotation.w;
+        const c_pos_x = concave_tr.position.x;
+        const c_pos_y = concave_tr.position.y;
+        const c_pos_z = concave_tr.position.z;
+
+        // Sphere fast-path: when the convex side is a UnitSphereShape3D we
+        // bypass GJK+EPA entirely per triangle and use the closed-form
+        // {@link sphere_triangle_contact}. This avoids the EPA precision
+        // wall on Triangle3D (whose support function is degenerate along
+        // the face normal — all 3 vertices project to the same value),
+        // which was producing noisy depths at small penetrations and
+        // letting dropped spheres tunnel through heightmaps / meshes.
+        const isSphereConvex = convex_col.shape.isUnitSphereShape3D === true;
+
+        // Box fast-path: closed-form {@link box_triangle_contact} via SAT
+        // over 13 axes + polygon clipping for face-vs-face contacts.
+        // Same motivation as the sphere path — Triangle3D's degenerate
+        // face-normal support kills EPA precision and produces noisy
+        // depths. The box path uses world-space triangle vertices.
+        const isBoxConvex = convex_col.shape.isBoxShape3D === true;
+        const box_half_extents = isBoxConvex ? convex_col.shape.half_extents : null;
+
+        // Capsule fast-path: closed-form {@link capsule_triangle_contact}
+        // via segment-vs-triangle closest-point + cap-centre sphere
+        // queries for a multi-point manifold. Same motivation as the
+        // sphere and box paths.
+        const isCapsuleConvex = convex_col.shape.isCapsuleShape3D === true;
+        const capsule_shape = isCapsuleConvex ? convex_col.shape : null;
+
+        for (let i = 0; i < tri_count; i++) {
+            const tri_offset = i * TRIANGLE_FLOAT_STRIDE;
+            triangle_shape.bind(triangle_buffer, tri_offset);
+
+            const ax = triangle_buffer[tri_offset    ];
+            const ay = triangle_buffer[tri_offset + 1];
+            const az = triangle_buffer[tri_offset + 2];
+
+            const bx = triangle_buffer[tri_offset + 3];
+            const by = triangle_buffer[tri_offset + 4];
+            const bz = triangle_buffer[tri_offset + 5];
+
+            const cx_v = triangle_buffer[tri_offset + 6];
+            const cy_v = triangle_buffer[tri_offset + 7];
+            const cz_v = triangle_buffer[tri_offset + 8];
+
+            // Triangle decomposition emits a stable per-triangle feature_id
+            // at offset 9 (TRIANGLE_FEATURE_ID_OFFSET) — same triangle of
+            // the same shape gets the same id across frames. This is the
+            // gold-standard fid for the match-and-merge pass.
+            const tri_fid = triangle_buffer[tri_offset + 9];
+
+            // Triangle face normal in body-local frame: (B − A) × (C − A).
+            // Winding convention (CCW from outside) gives an outward face
+            // normal — the heightmap / mesh enumerators both promise this.
+            const e1x_l = bx - ax, e1y_l = by - ay, e1z_l = bz - az;
+            const e2x_l = cx_v - ax, e2y_l = cy_v - ay, e2z_l = cz_v - az;
+
+            const fnx_l = e1y_l * e2z_l - e1z_l * e2y_l;
+            const fny_l = e1z_l * e2x_l - e1x_l * e2z_l;
+            const fnz_l = e1x_l * e2y_l - e1y_l * e2x_l;
+
+            // Rotate face normal to world via concave's quaternion
+            // (q · v · q⁻¹). Inlined for V8 inliner — see PosedShape.support.
+            const fnix =  cqw * fnx_l + cqy * fnz_l - cqz * fny_l;
+            const fniy =  cqw * fny_l + cqz * fnx_l - cqx * fnz_l;
+            const fniz =  cqw * fnz_l + cqx * fny_l - cqy * fnx_l;
+            const fniw = -cqx * fnx_l - cqy * fny_l - cqz * fnz_l;
+
+            const fnx_w = fnix * cqw - fniw * cqx - fniy * cqz + fniz * cqy;
+            const fny_w = fniy * cqw - fniw * cqy - fniz * cqx + fnix * cqz;
+            const fnz_w = fniz * cqw - fniw * cqz - fnix * cqy + fniy * cqx;
+
+            // Sphere-vs-triangle closed-form fast-path.
+            if (isSphereConvex) {
+
+                // Rotate each triangle vertex from concave-local to world.
+                // Per-vertex cost: ~21 flops × 3 vertices = 63 flops; vs.
+                // the GJK + EPA cost we're replacing, this is essentially
+                // free.
+                // Inlined q · v · q* + translate per vertex — see PosedShape.support.
+                const axi =  cqw * ax + cqy * az - cqz * ay;
+                const ayi =  cqw * ay + cqz * ax - cqx * az;
+                const azi =  cqw * az + cqx * ay - cqy * ax;
+                const awi = -cqx * ax - cqy * ay - cqz * az;
+
+                const ax_w = axi * cqw + awi * -cqx + ayi * -cqz - azi * -cqy + c_pos_x;
+                const ay_w = ayi * cqw + awi * -cqy + azi * -cqx - axi * -cqz + c_pos_y;
+                const az_w = azi * cqw + awi * -cqz + axi * -cqy - ayi * -cqx + c_pos_z;
+
+                const bxi =  cqw * bx + cqy * bz - cqz * by;
+                const byi =  cqw * by + cqz * bx - cqx * bz;
+                const bzi =  cqw * bz + cqx * by - cqy * bx;
+                const bwi = -cqx * bx - cqy * by - cqz * bz;
+
+                const bx_w = bxi * cqw + bwi * -cqx + byi * -cqz - bzi * -cqy + c_pos_x;
+                const by_w = byi * cqw + bwi * -cqy + bzi * -cqx - bxi * -cqz + c_pos_y;
+                const bz_w = bzi * cqw + bwi * -cqz + bxi * -cqy - byi * -cqx + c_pos_z;
+
+                const cxi =  cqw * cx_v + cqy * cz_v - cqz * cy_v;
+                const cyi =  cqw * cy_v + cqz * cx_v - cqx * cz_v;
+                const czi =  cqw * cz_v + cqx * cy_v - cqy * cx_v;
+                const cwi = -cqx * cx_v - cqy * cy_v - cqz * cz_v;
+
+                const cx_w = cxi * cqw + cwi * -cqx + cyi * -cqz - czi * -cqy + c_pos_x;
+                const cy_w = cyi * cqw + cwi * -cqy + czi * -cqx - cxi * -cqz + c_pos_y;
+                const cz_w = czi * cqw + cwi * -cqz + cxi * -cqy - cyi * -cqx + c_pos_z;
+
+                const ok = sphere_triangle_contact(
+                    sphere_triangle_result,
+                    convex_wx, convex_wy, convex_wz, 1,
+                    ax_w, ay_w, az_w,
+                    bx_w, by_w, bz_w,
+                    cx_w, cy_w, cz_w
+                );
+
+                if (!ok) continue;
+
+                // sphere_triangle_contact's normal points from the
+                // triangle surface toward the sphere centre — same
+                // direction as the post-sign-check EPA MTV in the
+                // fallback path below (concave A → convex B).
+                const sd = sphere_triangle_result[3];
+                const n_t2s_x = sphere_triangle_result[0];
+                const n_t2s_y = sphere_triangle_result[1];
+                const n_t2s_z = sphere_triangle_result[2];
+
+                // One-sided rejection: the sphere must lie on the
+                // outward side of the triangle. If the contact normal
+                // opposes the face normal, the sphere is behind /
+                // inside the solid — skip rather than push it deeper.
+                if (n_t2s_x * fnx_w + n_t2s_y * fny_w + n_t2s_z * fnz_w <= 0) continue;
+
+                // Stored normal convention is "B → A". `nx, ny, nz` here
+                // points convex → concave (which the existing EPA branch
+                // also produces just before append). Dedup uses the
+                // post-swap stored_n so adjacent-triangle duplicates
+                // collapse the same way regardless of code path.
+                const nx_s = -n_t2s_x;
+                const ny_s = -n_t2s_y;
+                const nz_s = -n_t2s_z;
+
+                const stored_nx_s = isConcaveA ? nx_s : -nx_s;
+                const stored_ny_s = isConcaveA ? ny_s : -ny_s;
+                const stored_nz_s = isConcaveA ? nz_s : -nz_s;
+                let is_duplicate_s = false;
+                for (let k = pair_start_count; k < count; k++) {
+                    const ko = k * CANDIDATE_STRIDE;
+                    const dnx = candidates[ko + 6] - stored_nx_s;
+                    const dny = candidates[ko + 7] - stored_ny_s;
+                    const dnz = candidates[ko + 8] - stored_nz_s;
+                    if (dnx * dnx + dny * dny + dnz * dnz < 0.001) {
+                        is_duplicate_s = true;
+                        break;
+                    }
+                }
+                if (is_duplicate_s) continue;
+
+                // Surface witnesses from the closed-form solver:
+                //   result[4..6] = sphere surface point (convex side)
+                //   result[7..9] = triangle closest point (concave side)
+                // Use the actual witnesses rather than body centres —
+                // unlike the EPA fallback (which uses body centres
+                // because flat-faced support witnesses can be arbitrarily
+                // far from the contact patch), closest-point-on-triangle
+                // is exact and lies on the contact patch.
+                const sphere_wx = sphere_triangle_result[4];
+                const sphere_wy = sphere_triangle_result[5];
+                const sphere_wz = sphere_triangle_result[6];
+                const tri_wx = sphere_triangle_result[7];
+                const tri_wy = sphere_triangle_result[8];
+                const tri_wz = sphere_triangle_result[9];
+                if (isConcaveA) {
+                    count = append_contact(count,
+                        tri_wx, tri_wy, tri_wz,
+                        sphere_wx, sphere_wy, sphere_wz,
+                        nx_s, ny_s, nz_s, sd, tri_fid);
+                } else {
+                    count = append_contact(count,
+                        sphere_wx, sphere_wy, sphere_wz,
+                        tri_wx, tri_wy, tri_wz,
+                        -nx_s, -ny_s, -nz_s, sd, tri_fid);
+                }
+                continue;
+            }
+
+            // Box-vs-triangle closed-form fast-path.
+            if (isBoxConvex) {
+                // Rotate each triangle vertex from concave-local to world.
+                // Inlined q · v · q* + translate per vertex — see PosedShape.support.
+                const axi =  cqw * ax + cqy * az - cqz * ay;
+                const ayi =  cqw * ay + cqz * ax - cqx * az;
+                const azi =  cqw * az + cqx * ay - cqy * ax;
+                const awi = -cqx * ax - cqy * ay - cqz * az;
+
+                const ax_w = axi * cqw + awi * -cqx + ayi * -cqz - azi * -cqy + c_pos_x;
+                const ay_w = ayi * cqw + awi * -cqy + azi * -cqx - axi * -cqz + c_pos_y;
+                const az_w = azi * cqw + awi * -cqz + axi * -cqy - ayi * -cqx + c_pos_z;
+
+                const bxi =  cqw * bx + cqy * bz - cqz * by;
+                const byi =  cqw * by + cqz * bx - cqx * bz;
+                const bzi =  cqw * bz + cqx * by - cqy * bx;
+                const bwi = -cqx * bx - cqy * by - cqz * bz;
+
+                const bx_w = bxi * cqw + bwi * -cqx + byi * -cqz - bzi * -cqy + c_pos_x;
+                const by_w = byi * cqw + bwi * -cqy + bzi * -cqx - bxi * -cqz + c_pos_y;
+                const bz_w = bzi * cqw + bwi * -cqz + bxi * -cqy - byi * -cqx + c_pos_z;
+
+                const cxi =  cqw * cx_v + cqy * cz_v - cqz * cy_v;
+                const cyi =  cqw * cy_v + cqz * cx_v - cqx * cz_v;
+                const czi =  cqw * cz_v + cqx * cy_v - cqy * cx_v;
+                const cwi = -cqx * cx_v - cqy * cy_v - cqz * cz_v;
+                const cx_w = cxi * cqw + cwi * -cqx + cyi * -cqz - czi * -cqy + c_pos_x;
+                const cy_w = cyi * cqw + cwi * -cqy + czi * -cqx - cxi * -cqz + c_pos_y;
+                const cz_w = czi * cqw + cwi * -cqz + cxi * -cqy - cyi * -cqx + c_pos_z;
+
+                const ok = box_triangle_contact(
+                    box_triangle_result,
+                    convex_tr.position.x, convex_tr.position.y, convex_tr.position.z,
+                    convex_tr.rotation.x, convex_tr.rotation.y, convex_tr.rotation.z, convex_tr.rotation.w,
+                    box_half_extents.x, box_half_extents.y, box_half_extents.z,
+                    ax_w, ay_w, az_w,
+                    bx_w, by_w, bz_w,
+                    cx_w, cy_w, cz_w
+                );
+                if (!ok) continue;
+
+                // Same convention as sphere_triangle: result normal points
+                // from triangle surface toward box centre. To match the
+                // EPA branch's `nx, ny, nz` (which points convex →
+                // concave = box → triangle), negate.
+                const n_t2box_x = box_triangle_result[0];
+                const n_t2box_y = box_triangle_result[1];
+                const n_t2box_z = box_triangle_result[2];
+
+                // One-sided rejection: the box must lie on the outward
+                // side of the triangle. If the contact normal opposes
+                // the face normal, the box is inside the solid → skip.
+                if (n_t2box_x * fnx_w + n_t2box_y * fny_w + n_t2box_z * fnz_w <= 0) continue;
+
+                const nx_b = -n_t2box_x;
+                const ny_b = -n_t2box_y;
+                const nz_b = -n_t2box_z;
+                const stored_nx_b = isConcaveA ? nx_b : -nx_b;
+                const stored_ny_b = isConcaveA ? ny_b : -ny_b;
+                const stored_nz_b = isConcaveA ? nz_b : -nz_b;
+
+                // Emit each clipped contact. The contact count from
+                // box_triangle_contact is at most 4; combined with the
+                // existing per-pair candidate cap (64 entries), tens of
+                // overlapping triangles per pair are safely accommodated.
+                const cc = box_triangle_result[3] | 0;
+                for (let k = 0; k < cc; k++) {
+                    const base = 4 + k * 7;
+                    const t_wx = box_triangle_result[base];
+                    const t_wy = box_triangle_result[base + 1];
+                    const t_wz = box_triangle_result[base + 2];
+                    const b_wx = box_triangle_result[base + 3];
+                    const b_wy = box_triangle_result[base + 4];
+                    const b_wz = box_triangle_result[base + 5];
+                    const d_k = box_triangle_result[base + 6];
+
+                    // Dedup against earlier candidates in THIS dispatch
+                    // (adjacent triangles can produce coincident contacts
+                    // — same as the sphere and EPA paths).
+                    let is_duplicate_k = false;
+                    for (let q = pair_start_count; q < count; q++) {
+                        const qo = q * CANDIDATE_STRIDE;
+                        const dnx = candidates[qo + 6] - stored_nx_b;
+                        const dny = candidates[qo + 7] - stored_ny_b;
+                        const dnz = candidates[qo + 8] - stored_nz_b;
+                        if (dnx * dnx + dny * dny + dnz * dnz < 0.001) {
+                            // Same normal; check positions too (a
+                            // multi-point manifold has distinct points
+                            // with the same normal — those should NOT
+                            // be deduped). Compare the world-A side
+                            // (triangle surface or box surface depending
+                            // on dispatcher swap).
+                            const pa_x = isConcaveA ? t_wx : b_wx;
+                            const pa_y = isConcaveA ? t_wy : b_wy;
+                            const pa_z = isConcaveA ? t_wz : b_wz;
+                            const dpx = candidates[qo]     - pa_x;
+                            const dpy = candidates[qo + 1] - pa_y;
+                            const dpz = candidates[qo + 2] - pa_z;
+                            if (dpx * dpx + dpy * dpy + dpz * dpz < 1e-6) {
+                                is_duplicate_k = true;
+                                break;
+                            }
+                        }
+                    }
+                    if (is_duplicate_k) continue;
+
+                    if (isConcaveA) {
+                        count = append_contact(count,
+                            t_wx, t_wy, t_wz,
+                            b_wx, b_wy, b_wz,
+                            nx_b, ny_b, nz_b, d_k, tri_fid);
+                    } else {
+                        count = append_contact(count,
+                            b_wx, b_wy, b_wz,
+                            t_wx, t_wy, t_wz,
+                            -nx_b, -ny_b, -nz_b, d_k, tri_fid);
+                    }
+                }
+                continue;
+            }
+
+            // Capsule-vs-triangle closed-form fast-path.
+            if (isCapsuleConvex) {
+                // Rotate each triangle vertex from concave-local to world.
+                // Inlined q · v · q* + translate per vertex — see PosedShape.support.
+                const axi =  cqw * ax + cqy * az - cqz * ay;
+                const ayi =  cqw * ay + cqz * ax - cqx * az;
+                const azi =  cqw * az + cqx * ay - cqy * ax;
+                const awi = -cqx * ax - cqy * ay - cqz * az;
+                const ax_w = axi * cqw + awi * -cqx + ayi * -cqz - azi * -cqy + c_pos_x;
+                const ay_w = ayi * cqw + awi * -cqy + azi * -cqx - axi * -cqz + c_pos_y;
+                const az_w = azi * cqw + awi * -cqz + axi * -cqy - ayi * -cqx + c_pos_z;
+
+                const bxi =  cqw * bx + cqy * bz - cqz * by;
+                const byi =  cqw * by + cqz * bx - cqx * bz;
+                const bzi =  cqw * bz + cqx * by - cqy * bx;
+                const bwi = -cqx * bx - cqy * by - cqz * bz;
+                const bx_w = bxi * cqw + bwi * -cqx + byi * -cqz - bzi * -cqy + c_pos_x;
+                const by_w = byi * cqw + bwi * -cqy + bzi * -cqx - bxi * -cqz + c_pos_y;
+                const bz_w = bzi * cqw + bwi * -cqz + bxi * -cqy - byi * -cqx + c_pos_z;
+
+                const cxi =  cqw * cx_v + cqy * cz_v - cqz * cy_v;
+                const cyi =  cqw * cy_v + cqz * cx_v - cqx * cz_v;
+                const czi =  cqw * cz_v + cqx * cy_v - cqy * cx_v;
+                const cwi = -cqx * cx_v - cqy * cy_v - cqz * cz_v;
+                const cx_w = cxi * cqw + cwi * -cqx + cyi * -cqz - czi * -cqy + c_pos_x;
+                const cy_w = cyi * cqw + cwi * -cqy + czi * -cqx - cxi * -cqz + c_pos_y;
+                const cz_w = czi * cqw + cwi * -cqz + cxi * -cqy - cyi * -cqx + c_pos_z;
+
+                const cap_cc = capsule_triangle_contact(
+                    capsule_triangle_result,
+                    convex_tr.position.x, convex_tr.position.y, convex_tr.position.z,
+                    convex_tr.rotation.x, convex_tr.rotation.y, convex_tr.rotation.z, convex_tr.rotation.w,
+                    capsule_shape.radius, capsule_shape.height * 0.5,
+                    ax_w, ay_w, az_w,
+                    bx_w, by_w, bz_w,
+                    cx_w, cy_w, cz_w
+                );
+                if (cap_cc === 0) continue;
+
+                // Each sub-contact's normal can be distinct (a flat
+                // capsule produces primary + endpoint contacts whose
+                // normals all point ≈ same direction, but an edge or
+                // vertex contact at a cap can deviate). Apply
+                // face-normal rejection per-contact.
+                for (let k = 0; k < cap_cc; k++) {
+                    const base = k * CAPSULE_TRIANGLE_CONTACT_STRIDE;
+                    const cap_x = capsule_triangle_result[base];
+                    const cap_y = capsule_triangle_result[base + 1];
+                    const cap_z = capsule_triangle_result[base + 2];
+                    const ct_x = capsule_triangle_result[base + 3];
+                    const ct_y = capsule_triangle_result[base + 4];
+                    const ct_z = capsule_triangle_result[base + 5];
+                    const n_t2cap_x = capsule_triangle_result[base + 6];
+                    const n_t2cap_y = capsule_triangle_result[base + 7];
+                    const n_t2cap_z = capsule_triangle_result[base + 8];
+                    const d_c = capsule_triangle_result[base + 9];
+
+                    // One-sided face-normal rejection: capsule must be
+                    // on the outward side of the triangle.
+                    if (n_t2cap_x * fnx_w + n_t2cap_y * fny_w + n_t2cap_z * fnz_w <= 0) continue;
+
+                    // Stored normal "convex → concave" = "capsule →
+                    // triangle" = negated t2cap.
+                    const nx_c = -n_t2cap_x;
+                    const ny_c = -n_t2cap_y;
+                    const nz_c = -n_t2cap_z;
+                    const stored_nx_c = isConcaveA ? nx_c : -nx_c;
+                    const stored_ny_c = isConcaveA ? ny_c : -ny_c;
+                    const stored_nz_c = isConcaveA ? nz_c : -nz_c;
+
+                    // Dedup against earlier candidates in THIS dispatch.
+                    let is_duplicate_c = false;
+                    for (let q = pair_start_count; q < count; q++) {
+                        const qo = q * CANDIDATE_STRIDE;
+                        const dnx = candidates[qo + 6] - stored_nx_c;
+                        const dny = candidates[qo + 7] - stored_ny_c;
+                        const dnz = candidates[qo + 8] - stored_nz_c;
+                        if (dnx * dnx + dny * dny + dnz * dnz < 0.001) {
+                            const pa_x = isConcaveA ? ct_x : cap_x;
+                            const pa_y = isConcaveA ? ct_y : cap_y;
+                            const pa_z = isConcaveA ? ct_z : cap_z;
+                            const dpx = candidates[qo]     - pa_x;
+                            const dpy = candidates[qo + 1] - pa_y;
+                            const dpz = candidates[qo + 2] - pa_z;
+                            if (dpx * dpx + dpy * dpy + dpz * dpz < 1e-6) {
+                                is_duplicate_c = true;
+                                break;
+                            }
+                        }
+                    }
+                    if (is_duplicate_c) continue;
+
+                    if (isConcaveA) {
+                        count = append_contact(count,
+                            ct_x, ct_y, ct_z,
+                            cap_x, cap_y, cap_z,
+                            nx_c, ny_c, nz_c, d_c, tri_fid);
+                    } else {
+                        count = append_contact(count,
+                            cap_x, cap_y, cap_z,
+                            ct_x, ct_y, ct_z,
+                            -nx_c, -ny_c, -nz_c, d_c, tri_fid);
+                    }
+                }
+                continue;
+            }
+
+            // P2.1 step 6: pass the manifold's cached separating axis
+            // here too. Per-triangle iteration means the cache gets
+            // written multiple times per body-pair per frame (one per
+            // overlapping triangle); the final state reflects the
+            // last triangle's converged direction. Still a useful
+            // seed for next frame's first triangle.
+            if (!gjk_with_axis(simplex_buf, posed_a, posed_b, gjk_axis_buf, gjk_axis_off)) continue;
+            expanding_polytope_algorithm(
+                epa_result, 0,
+                simplex_a, simplex_b, simplex_c, simplex_d,
+                posed_a, posed_b
+            );
+
+            let ex = epa_result[0], ey = epa_result[1], ez = epa_result[2];
+            let depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+            // P3.1: MPR fallback. EPA can return zero/negative/NaN
+            // depth on Triangle3D's degenerate face-normal support
+            // (the same precision pit the closed-form sphere/box/
+            // capsule paths above were added to dodge). MPR has
+            // different convergence properties and often succeeds
+            // here. Only kicks in for non-(sphere/box/capsule) convex
+            // shapes against the concave side — a narrow path now
+            // that closed-form covers the common cases.
+            if (!(depth > 0) || !Number.isFinite(depth)) {
+                if (!mpr(epa_result, 0, posed_a, posed_b)) continue;
+                ex = epa_result[0]; ey = epa_result[1]; ez = epa_result[2];
+                depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+                if (!(depth > 0) || !Number.isFinite(depth)) continue;
+            }
+
+            // Sign-check: validate MTV direction against (convex −
+            // triangle_centroid). EPA's polytope-closest-face normal
+            // can come out on the wrong side of the origin; this flip
+            // canonicalises MTV to point from triangle (A) toward the
+            // convex shape (B).
+            const cent_lx = (ax + bx + cx_v) / 3;
+            const cent_ly = (ay + by + cy_v) / 3;
+            const cent_lz = (az + bz + cz_v) / 3;
+            // Inlined q · v · q* + translate.
+            const cix =  cqw * cent_lx + cqy * cent_lz - cqz * cent_ly;
+            const ciy =  cqw * cent_ly + cqz * cent_lx - cqx * cent_lz;
+            const ciz =  cqw * cent_lz + cqx * cent_ly - cqy * cent_lx;
+            const ciw = -cqx * cent_lx - cqy * cent_ly - cqz * cent_lz;
+            const cent_wx = cix * cqw + ciw * -cqx + ciy * -cqz - ciz * -cqy + c_pos_x;
+            const cent_wy = ciy * cqw + ciw * -cqy + ciz * -cqx - cix * -cqz + c_pos_y;
+            const cent_wz = ciz * cqw + ciw * -cqz + cix * -cqy - ciy * -cqx + c_pos_z;
+
+            const tri_ab_x = convex_wx - cent_wx;
+            const tri_ab_y = convex_wy - cent_wy;
+            const tri_ab_z = convex_wz - cent_wz;
+            if (ex * tri_ab_x + ey * tri_ab_y + ez * tri_ab_z < 0) {
+                ex = -ex; ey = -ey; ez = -ez;
+            }
+
+            // One-sided rejection (post-sign-check). MTV now points
+            // from triangle (A) toward convex shape (B). For a CCW
+            // outward-wound triangle, the convex shape is on the
+            // OUTWARD side iff MTV aligns with the face normal. If it
+            // opposes the face normal, the convex shape is on the
+            // back / inward side — invalid for heightmap/mesh (it's
+            // inside the solid). Skip the triangle rather than push
+            // the body deeper into the solid through the opposite
+            // face on the next step.
+            if (ex * fnx_w + ey * fny_w + ez * fnz_w <= 0) continue;
+
+            // After the validated flip, MTV points from triangle
+            // (concave-side A) into convex (B). Stored normal is
+            // "B → A" so we negate. Final A/B order matches
+            // append_contact's contract: original A first, original B
+            // second, normal "from original B toward original A".
+            const inv = 1 / depth;
+            const nx = -ex * inv;
+            const ny = -ey * inv;
+            const nz = -ez * inv;
+
+            // Dedup against earlier contacts emitted in THIS dispatch.
+            // Adjacent triangles (heightmap cells sharing a diagonal;
+            // mesh triangles sharing an edge or vertex) often report
+            // identical contacts (same normal, same body-centre
+            // application points), and feeding duplicates to the
+            // sequential-impulse solver makes it escalate the impulse
+            // across iterations without bound. We deduplicate by
+            // contact normal within a small angular threshold: same
+            // body pair + same normal + same body-centre positions =
+            // the same physical contact, only one copy belongs in the
+            // manifold.
+            const stored_nx = isConcaveA ? nx : -nx;
+            const stored_ny = isConcaveA ? ny : -ny;
+            const stored_nz = isConcaveA ? nz : -nz;
+            let is_duplicate = false;
+            for (let k = pair_start_count; k < count; k++) {
+                const ko = k * CANDIDATE_STRIDE;
+                const dnx = candidates[ko + 6] - stored_nx;
+                const dny = candidates[ko + 7] - stored_ny;
+                const dnz = candidates[ko + 8] - stored_nz;
+                if (dnx * dnx + dny * dny + dnz * dnz < 0.001) {
+                    is_duplicate = true;
+                    break;
+                }
+            }
+            if (is_duplicate) continue;
+
+            // Contact application points: body centres rather than
+            // the triangle's centroid. The existing GJK+EPA fallback
+            // (below) uses the same convention — for vertical contacts
+            // (sphere/box on a flat surface, the common case), the
+            // lever arm r × n vanishes and the impulse resolves
+            // cleanly.
+            if (isConcaveA) {
+                count = append_contact(count,
+                    c_pos_x, c_pos_y, c_pos_z,
+                    convex_wx, convex_wy, convex_wz,
+                    nx, ny, nz, depth, tri_fid);
+            } else {
+                count = append_contact(count,
+                    convex_wx, convex_wy, convex_wz,
+                    c_pos_x, c_pos_y, c_pos_z,
+                    -nx, -ny, -nz, depth, tri_fid);
+            }
+        }
+
+        return count;
+    }
+
+    // GJK + EPA fallback for everything else. P2.1 step 5: pass the
+    // manifold's cached separating axis as GJK's initial search
+    // direction. Cold start (zero-axis) on first contact; subsequent
+    // frames reuse the converged direction, typically converging in
+    // 1–2 iterations instead of the ~6–10 cold-start cost.
+    posed_a.setup(colA.shape, trA.position, trA.rotation);
+    posed_b.setup(colB.shape, trB.position, trB.rotation);
+
+    if (!gjk_with_axis(simplex_buf, posed_a, posed_b, gjk_axis_buf, gjk_axis_off)){
+        return count;
+    }
+
+    expanding_polytope_algorithm(
+        epa_result, 0,
+        simplex_a, simplex_b, simplex_c, simplex_d,
+        posed_a, posed_b
+    );
+
+    let ex = epa_result[0], ey = epa_result[1], ez = epa_result[2];
+    let depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+    // EPA can return zero-depth (touching), negative (impossible) or
+    // NaN/Inf (degenerate iteration-cap exit on smooth high-poly
+    // colliders). P3.1: fall back to MPR — different convergence
+    // properties (works portal-based rather than face-expansion), often
+    // succeeds where EPA fails on the same geometry. `shape_cast` and
+    // `compute_penetration` already use MPR for the same reason.
+    if (!(depth > 0) || !Number.isFinite(depth)) {
+        if (!mpr(epa_result, 0, posed_a, posed_b)) return count;
+        ex = epa_result[0]; ey = epa_result[1]; ez = epa_result[2];
+        depth = Math.sqrt(ex * ex + ey * ey + ez * ez);
+        if (!(depth > 0) || !Number.isFinite(depth)) return count;
+    }
+
+    // EPA's output vector should point along the minimum-translation
+    // axis from A into B (the direction you'd push B by to separate).
+    // On non-convergent EPA — common on smooth high-poly colliders like
+    // a torus knot, where the polytope can't tighten onto the true
+    // closest face within the iteration cap — the fallback returns
+    // *some* face's normal, and that face can be on either side of the
+    // origin. Resulting MTV occasionally points B *into* A instead of
+    // *away from* A; the solver then sees a "separating" relative
+    // velocity, clamps the normal impulse to zero, and the bodies pass
+    // straight through each other.
+    //
+    // Validate against the vector from body A's centre to body B's
+    // centre — EPA's direction must correlate positively with it. Flip
+    // if not. For convex bodies whose origin is inside the geometry,
+    // body-centre-to-body-centre is a strong proxy for the correct
+    // separation direction. For pathological cases (deeply
+    // interpenetrating bodies with coincident centres) the dot product
+    // is near zero and we leave EPA's guess intact.
+    const ab_x = trB.position.x - trA.position.x;
+    const ab_y = trB.position.y - trA.position.y;
+    const ab_z = trB.position.z - trA.position.z;
+    if (ex * ab_x + ey * ab_y + ez * ab_z < 0) {
+        ex = -ex; ey = -ey; ez = -ez;
+    }
+
+    const inv = 1 / depth;
+    const nx = -ex * inv, ny = -ey * inv, nz = -ez * inv; // stored normal, B → A
+
+    // Contact application points: body centres rather than support-function
+    // witnesses. The natural-sounding alternative — `posed_a.support(+EPA_dir)`
+    // and `posed_b.support(-EPA_dir)` — interacts badly with flat-faced
+    // supports: a large floor's support in `+Y` returns a *corner* (the box
+    // support is multi-valued along an axis-aligned direction and picks the
+    // sign-tied corner), which can be tens of metres from the actual
+    // contact patch. That blows up the solver's lever arm `r × n` and
+    // collapses `m_eff` to ~0, leaving the impulse vanishingly small.
+    //
+    // Body centres give `r ‖ n` for vertical contacts (sphere/knot landing
+    // on a floor — the common case), so `r × n = 0` and `m_eff = invM`
+    // resolves the impact cleanly. For oblique contacts the application
+    // point lies on the line between centres, which is the right-ish lever
+    // arm for translational impulse and degrades gracefully on angular
+    // response. A future closed-form mesh-vs-box path will compute a
+    // proper face-projected witness; until then, body centres are the
+    // robust fallback for the GJK+EPA route.
+    // GJK+EPA fallback has no stable per-frame feature info; emit fid = 0
+    // so match-and-merge uses position-fallback. Single contact per pair.
+    return append_contact(count,
+        trA.position.x, trA.position.y, trA.position.z,
+        trB.position.x, trB.position.y, trB.position.z,
+        nx, ny, nz,
+        depth, 0
+    );
+}
+
+/**
+ * For every pair in `pair_list`, do a cross-product over A's collider list ×
+ * B's collider list, accumulate candidate contacts, reduce to ≤4, and write
+ * to the manifold slot.
+ *
+ * @param {PairList} pair_list
+ * @param {ManifoldStore} manifolds
+ * @param {Array<Array<{collider: Collider, transform: Transform}>>} lists
+ *   per-body collider lists, indexed by body-storage slot index. Typically
+ *   `system.__body_collider_lists` — passed in directly so this helper
+ *   has no dependency on `PhysicsSystem`.
+ */
+export function narrowphase_step(pair_list, manifolds, lists) {
+    const count = pair_list.count;
+
+    for (let i = 0; i < count; i++) {
+        const idA = pair_list.get_a(i);
+        const idB = pair_list.get_b(i);
+        const idxA = body_id_index(idA);
+        const idxB = body_id_index(idB);
+
+        const list_a = lists[idxA];
+        const list_b = lists[idxB];
+        const slot = manifolds.find(idA, idB);
+
+        if (list_a === undefined || list_b === undefined
+            || list_a.length === 0 || list_b.length === 0) {
+            manifolds.clear_contacts(slot);
+            continue;
+        }
+
+        let cand_count = 0;
+        const la_len = list_a.length;
+        const lb_len = list_b.length;
+        // Per-manifold cached GJK separating-axis seed. Threaded into
+        // dispatch_pair for the GJK fallback paths. For single-collider
+        // bodies (the common case) there's no contention across the
+        // inner loop; for compound bodies the cache reflects whichever
+        // collider-pair invoked GJK last, which is a noisy-but-useful
+        // seed (better than a cold (1, 0, 0) restart every frame).
+        const gjk_axis_buf = manifolds.slot_axis_buffer;
+        const gjk_axis_off = manifolds.slot_axis_offset(slot);
+        for (let a = 0; a < la_len; a++) {
+            const ea = list_a[a];
+            for (let b = 0; b < lb_len; b++) {
+                const eb = list_b[b];
+                cand_count = dispatch_pair(cand_count, ea.collider, ea.transform, eb.collider, eb.transform,
+                    gjk_axis_buf, gjk_axis_off);
+            }
+        }
+
+        if (cand_count === 0) {
+            // No contacts this frame for an existing manifold. Keep the
+            // slot in the cache (the grace window in advance_frame() will
+            // evict it if this persists), but zero out impulses and
+            // contact count — there's nothing for the solver to act on
+            // and stale impulses would mislead next frame's warm-start
+            // if contact re-establishes at a different feature.
+            manifolds.clear_contacts(slot);
+            continue;
+        }
+
+        const kept = reduce_candidates(cand_count);
+
+        // ── Match-and-merge: feature-id (with position fallback) ──────
+        //
+        // Snapshot prev-frame state for matching + impulse carry-over.
+        const data = manifolds.data_buffer;
+        const slot_off = manifolds.slot_data_offset(slot);
+        const prev_count_raw = manifolds.contact_count(slot);
+        const prev_count = prev_count_raw > MAX_CONTACTS_PER_MANIFOLD
+            ? MAX_CONTACTS_PER_MANIFOLD
+            : prev_count_raw;
+        for (let j = 0; j < prev_count; j++) {
+            const off = slot_off + j * CONTACT_STRIDE;
+            const snap_off = j * 7;
+            prev_snapshot[snap_off]     = data[off + 13]; // feature_id
+            prev_snapshot[snap_off + 1] = data[off];      // world_a x
+            prev_snapshot[snap_off + 2] = data[off + 1];  // world_a y
+            prev_snapshot[snap_off + 3] = data[off + 2];  // world_a z
+            prev_snapshot[snap_off + 4] = data[off + 10]; // j_n
+            prev_snapshot[snap_off + 5] = data[off + 11]; // j_t1
+            prev_snapshot[snap_off + 6] = data[off + 12]; // j_t2
+            prev_claimed[j] = 0;
+        }
+
+        // For each new candidate, find a matching prev contact.
+        //   Step 1: feature-id match (only if BOTH sides have a non-zero
+        //           feature_id — fid = 0 means "no info").
+        //   Step 2: position-fallback within MATCH_TOL_SQR.
+        for (let k = 0; k < kept; k++) {
+            const cand_off = k * CANDIDATE_STRIDE;
+            const cand_fid = candidates[cand_off + 10];
+            const cand_ax = candidates[cand_off];
+            const cand_ay = candidates[cand_off + 1];
+            const cand_az = candidates[cand_off + 2];
+
+            let best_prev = -1;
+            if (cand_fid !== 0) {
+                for (let j = 0; j < prev_count; j++) {
+                    if (prev_claimed[j]) continue;
+                    if (prev_snapshot[j * 7] === cand_fid) {
+                        best_prev = j;
+                        break;
+                    }
+                }
+            }
+            if (best_prev === -1) {
+                let best_d2 = MATCH_TOL_SQR;
+                for (let j = 0; j < prev_count; j++) {
+                    if (prev_claimed[j]) continue;
+                    const snap_off = j * 7;
+                    const dx = prev_snapshot[snap_off + 1] - cand_ax;
+                    const dy = prev_snapshot[snap_off + 2] - cand_ay;
+                    const dz = prev_snapshot[snap_off + 3] - cand_az;
+                    const d2 = dx * dx + dy * dy + dz * dz;
+                    if (d2 < best_d2) { best_d2 = d2; best_prev = j; }
+                }
+            }
+            cand_to_prev[k] = best_prev;
+            if (best_prev !== -1) prev_claimed[best_prev] = 1;
+        }
+
+        // Reset count without zeroing the data slab — set_contact below
+        // will overwrite geometry, and matched candidates will inherit
+        // the impulses we snapshotted above (written back at the new
+        // slot index after set_contact).
+        manifolds.begin_refill(slot);
+
+        for (let k = 0; k < kept; k++) {
+            const off = k * CANDIDATE_STRIDE;
+            // Target slot index = k (we write candidates 0..kept-1 into
+            // slot indices 0..kept-1). The impulse carry-over below
+            // copies the matched prev contact's impulses into THIS k,
+            // so the geometric and warm-start state stay correlated
+            // even if the matching mapping permuted the order.
+            manifolds.set_contact(
+                slot, k,
+                candidates[off],     candidates[off + 1], candidates[off + 2],
+                candidates[off + 3], candidates[off + 4], candidates[off + 5],
+                candidates[off + 6], candidates[off + 7], candidates[off + 8],
+                candidates[off + 9],
+                candidates[off + 10]
+            );
+            const prev_j = cand_to_prev[k];
+            if (prev_j !== -1) {
+                // Copy prev_j's impulse to this slot index.
+                const dst_off = slot_off + k * CONTACT_STRIDE;
+                const src_off = prev_j * 7;
+                data[dst_off + 10] = prev_snapshot[src_off + 4];
+                data[dst_off + 11] = prev_snapshot[src_off + 5];
+                data[dst_off + 12] = prev_snapshot[src_off + 6];
+            } else {
+                // No match — explicitly zero the impulses, since this
+                // slot index may have stale data from an earlier frame's
+                // contact at the same index.
+                manifolds.clear_impulses(slot, k);
+            }
+        }
+    }
+}