@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,1738 +1,1738 @@
-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 { combine_friction, combine_restitution } from "../contact/combine_material.js";
-import { CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
-import { gjk_epa_penetration } from "../../../core/geom/3d/gjk/gjk_epa_penetration.js";
-import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
-import { mpr } from "../../../core/geom/3d/gjk/mpr.js";
-import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
-import { convex_hull_clip, CONVEX_CONVEX_OUT_LENGTH } from "./convex_convex_manifold.js";
-import { get_mesh_convex_hull } from "./mesh_convex_hull.js";
-import { mesh_mesh_tet_contacts } from "./mesh_mesh_tet_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_CAPSULE_CONTACT_STRIDE,
-    capsule_capsule_multi_contacts,
-    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 { aabb3_transform_oriented_inverse } from "../../../core/geom/3d/aabb/aabb3_transform_oriented_inverse.js";
-import { decompose_to_triangles } from "./decomposition/decompose_to_triangles.js";
-import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
-import { PosedShape3D } from "../../../core/geom/3d/shape/PosedShape3D.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 PosedShape3D();
-const posed_b = new PosedShape3D();
-
-// Penetration axis + depth from the robust GJK + EPA query
-// (gjk_epa_penetration writes a unit normal here; it owns its own simplex
-// internally, so the narrowphase no longer keeps a simplex buffer).
-const epa_result = new Float64Array(3);
-const sphere_result = new Float64Array(4);
-const closed_form_result = new Float64Array(10);
-
-/** Scratch for the capsule-capsule multi-contact manifold (2 contacts max). */
-const capsule_capsule_result = new Float64Array(2 * CAPSULE_CAPSULE_CONTACT_STRIDE);
-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 convex_manifold_result = new Float64Array(CONVEX_CONVEX_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, friction, restitution.
- *
- * 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".
- *
- * `friction` (offset 11) and `restitution` (offset 12) are the COMBINED
- * coefficients for the specific (colliderA, colliderB) pair that produced this
- * contact, combined here (the only place that knows the exact source collider
- * on each side) and carried into the manifold so a compound body's per-collider
- * materials are honoured per-contact.
- *
- * @type {number}
- */
-const CANDIDATE_STRIDE = 13;
-
-/**
- * Combined friction / restitution for the collider pair currently being
- * dispatched. Set once at the top of {@link dispatch_pair} (which is called
- * per collider pair) and written into every contact that call appends, so
- * each contact carries the material of its actual source colliders. Module
- * scratch rather than threaded through every `append_contact` call site.
- * @type {number}
- */
-let g_pair_friction = 0;
-let g_pair_restitution = 0;
-
-/**
- * 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;
-
-/**
- * Per-(colliderA, colliderB) feature-id salt. Each emitter numbers its
- * features in a small private range (sphere-box voronoi 1..27, capsule-box
- * 1..k, triangles 1..N, …), so two SUB-PAIRS of a compound body can produce
- * identical fids for unrelated features and warm-start impulses could be
- * inherited across collider pairs. Salting by the sub-pair index keeps every
- * fid unique across the body pair while staying exactly representable in f64
- * (sub_pair · 2³² + fid stays far below 2⁵³ for any realistic compound; no
- * single-pair emitter exceeds 2³²). Sub-pair 0 — the universal
- * single-collider case — is left unsalted, so simple bodies see unchanged
- * fids.
- * @type {number}
- */
-const FID_PAIR_SALT = 0x100000000; // 2^32
-
-/**
- * Distance ceiling for a feature-id warm-start match. A fid match may track
- * a fast-sliding contact far beyond {@link MATCH_TOL_SQR} — that is its
- * advantage over position matching — but an impulse inherited across half a
- * metre in one frame is stale by any standard (a teleported body re-deriving
- * the same voronoi bucket, or a fid collision between unrelated features).
- * The position fallback keeps its own 2 cm gate.
- * @type {number}
- */
-const FID_MATCH_MAX_D2 = 0.5 * 0.5;
-
-/**
- * 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-candidate "already claimed" flags for {@link redetect_pair_geometry}'s
- * 1:1 existing-contact → fresh-candidate matching. Sized to the candidate
- * buffer capacity (64) so it covers any per-pair candidate count. Without it,
- * several existing contacts that share one triangle's `feature_id` (the
- * box/capsule-triangle paths emit multiple contacts per triangle) would all
- * match the same first candidate, collapsing the manifold to duplicate witness
- * points.
- * @type {Uint8Array}
- */
-const redetect_claimed = new Uint8Array(64);
-
-/**
- * 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.
- *
- * For a heightmap the per-cell triangle count scales O(N²) with the
- * shape's {@link HeightMapShape3D#tessellation} (a sub-cell quad is 2
- * triangles, and there are N×N sub-cells per sampler cell). The bounded
- * query AABB keeps the cell count small, so a typical pair stays well
- * inside 1024 at moderate tessellation; the silent-drop backstop below
- * covers any overflow at extreme values.
- *
- * Enumerators return the TRUE overlap count and have no bounds check of
- * their own: writes past the scratch buffer are dropped (typed-array OOB
- * semantics), so on overflow the consume loop MUST clamp the returned
- * count to this cap or it reads `undefined` past the end and poisons the
- * manifold with NaN. The worst case after clamping 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);
-
-/**
- * Rotate + translate a triangle's three vertices from a concave body's
- * local frame into world space: writes 9 floats `(A_w, B_w, C_w)` into
- * `out`. Inlined `q · v · q*` + translate per vertex (see
- * PosedShape3D.support for the V8-inliner rationale); the operation order
- * matches the blocks this replaced bit-exactly. Per-vertex cost ~21 flops
- * × 3 — essentially free next to any narrowphase kernel it feeds.
- *
- * Shared by the sphere / box / capsule closed-form triangle fast-paths in
- * the concave dispatch, which each carried an identical inlined copy.
- */
-function triangle_vertices_to_world(out, ax, ay, az, bx, by, bz, cx, cy, cz, qx, qy, qz, qw, px, py, pz) {
-    const axi =  qw * ax + qy * az - qz * ay;
-    const ayi =  qw * ay + qz * ax - qx * az;
-    const azi =  qw * az + qx * ay - qy * ax;
-    const awi = -qx * ax - qy * ay - qz * az;
-
-    out[0] = axi * qw + awi * -qx + ayi * -qz - azi * -qy + px;
-    out[1] = ayi * qw + awi * -qy + azi * -qx - axi * -qz + py;
-    out[2] = azi * qw + awi * -qz + axi * -qy - ayi * -qx + pz;
-
-    const bxi =  qw * bx + qy * bz - qz * by;
-    const byi =  qw * by + qz * bx - qx * bz;
-    const bzi =  qw * bz + qx * by - qy * bx;
-    const bwi = -qx * bx - qy * by - qz * bz;
-
-    out[3] = bxi * qw + bwi * -qx + byi * -qz - bzi * -qy + px;
-    out[4] = byi * qw + bwi * -qy + bzi * -qx - bxi * -qz + py;
-    out[5] = bzi * qw + bwi * -qz + bxi * -qy - byi * -qx + pz;
-
-    const cxi =  qw * cx + qy * cz - qz * cy;
-    const cyi =  qw * cy + qz * cx - qx * cz;
-    const czi =  qw * cz + qx * cy - qy * cx;
-    const cwi = -qx * cx - qy * cy - qz * cz;
-
-    out[6] = cxi * qw + cwi * -qx + cyi * -qz - czi * -qy + px;
-    out[7] = cyi * qw + cwi * -qy + czi * -qx - cxi * -qz + py;
-    out[8] = czi * qw + cwi * -qz + cxi * -qy - cyi * -qx + pz;
-}
-
-/** Destination for {@link triangle_vertices_to_world}. */
-const scratch_tri_world = new Float64Array(9);
-
-/**
- * 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;
-    candidates[off + 11] = g_pair_friction;
-    candidates[off + 12] = g_pair_restitution;
-
-    return count + 1;
-}
-
-/**
- * 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 PosedShape3D.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;
-}
-
-/**
- * Multi-point contact manifold between two convex polytopes (authored
- * ConvexHullShape3D, or a convex MeshShape3D represented as one hull). Robust
- * GJK + EPA finds the separating axis in O(support queries) — face-count
- * independent, where SAT's edge-pair term is prohibitive — then
- * {@link convex_hull_clip} clips the reference/incident faces into a face-on-face
- * patch around it (Bullet's clipHullAgainstHull). A single GJK+EPA contact can't
- * resist a stack's toppling torque; the clipped patch holds it. No cross-frame
- * state → reset-and-resimulate determinism.
- *
- * @param {number} count
- * @param {{vertices,face_offsets,face_loops,support}} hullA  in A's local frame
- * @param {Transform} trA
- * @param {{vertices,face_offsets,face_loops,support}} hullB  in B's local frame
- * @param {Transform} trB
- * @param {Function} append_contact
- * @returns {number}
- */
-function hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact) {
-    posed_a.setup(hullA, trA.position, trA.rotation);
-    posed_b.setup(hullB, trB.position, trB.rotation);
-    const depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
-    if (!(depth > 0) || !Number.isFinite(depth)) return count;
-
-    // convex_hull_clip orients the axis B→A robustly (via vertex centroids) and
-    // writes the final normal into convex_manifold_result[0..2].
-    convex_hull_clip(convex_manifold_result,
-        hullA, trA.position, trA.rotation,
-        hullB, trB.position, trB.rotation,
-        epa_result[0], epa_result[1], epa_result[2]);
-    const nx = convex_manifold_result[0], ny = convex_manifold_result[1], nz = convex_manifold_result[2];
-    const cc = convex_manifold_result[3] | 0;
-    // Clipped points migrate across features as the hulls rotate, so leave
-    // fid = 0 and let the match-and-merge pass position-match (as box-box does).
-    for (let k = 0; k < cc; k++) {
-        const base = 4 + k * 7;
-        count = append_contact(count,
-            convex_manifold_result[base],     convex_manifold_result[base + 1], convex_manifold_result[base + 2],
-            convex_manifold_result[base + 3], convex_manifold_result[base + 4], convex_manifold_result[base + 5],
-            nx, ny, nz,
-            convex_manifold_result[base + 6],
-            0);
-    }
-    return count;
-}
-
-/**
- * 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.
- *
- * @param {number} count
- * @param {Collider} colA
- * @param {Transform} trA
- * @param {Collider} colB
- * @param {Transform} trB
- * @returns {number}
- */
-function dispatch_pair(count, colA, trA, colB, trB) {
-    const shapeA = colA.shape;
-    const shapeB = colB.shape;
-
-    // Per-contact materials: combine the two source colliders' coefficients
-    // once here (this is the only place that knows the exact collider on each
-    // side) and stamp them onto every contact this dispatch appends. The
-    // `deepest_pair_penetration` query passes bare `{shape}` adapters with no
-    // material fields — it never writes to a manifold, so 0 is fine there.
-    const fa = colA.friction, fb = colB.friction;
-
-    if (fa !== undefined && fb !== undefined) {
-
-        g_pair_friction = combine_friction(fa, fb);
-        g_pair_restitution = combine_restitution(colA.restitution, colB.restitution);
-
-    } else {
-        g_pair_friction = 0;
-        g_pair_restitution = 0;
-    }
-
-    // isSphereShape3D covers both UnitSphereShape3D (fixed radius 1) and
-    // SphereShape3D (arbitrary radius). Both expose `radius`.
-    const isSphereA = shapeA.isSphereShape3D === true;
-    const isSphereB = shapeB.isSphereShape3D === 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 ra = shapeA.radius, rb = shapeB.radius;
-
-        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,
-            ra, rb
-        );
-
-        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. Witnesses are the surface
-        // points along the (unit) normal, scaled by each sphere's radius.
-        return append_contact(count,
-            trA.position.x - nx * ra, trA.position.y - ny * ra, trA.position.z - nz * ra,
-            trB.position.x + nx * rb, trB.position.y + ny * rb, trB.position.z + nz * rb,
-            nx, ny, nz, sphere_result[3], 1);
-    }
-
-    // sphere ↔ box
-    if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
-        const sphereTr    = isSphereA ? trA : trB;
-        const sphereShape = isSphereA ? shapeA : shapeB;
-        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, sphereShape.radius,
-            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 (multi-point: near-parallel overlap emits both ends of
-    // the overlap interval; everything else the single closest-point contact)
-    if (isCapsuleA && isCapsuleB) {
-        const a_shape = colA.shape, b_shape = colB.shape;
-        const n_cc = capsule_capsule_multi_contacts(
-            capsule_capsule_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
-        );
-        for (let k = 0; k < n_cc; k++) {
-            const off = k * CAPSULE_CAPSULE_CONTACT_STRIDE;
-            // fid = k + 1: stable per interval end (1-based; 0 = no info).
-            count = append_contact(count,
-                capsule_capsule_result[off],     capsule_capsule_result[off + 1], capsule_capsule_result[off + 2],
-                capsule_capsule_result[off + 3], capsule_capsule_result[off + 4], capsule_capsule_result[off + 5],
-                capsule_capsule_result[off + 6], capsule_capsule_result[off + 7], capsule_capsule_result[off + 8],
-                capsule_capsule_result[off + 9], k + 1);
-        }
-        return count;
-    }
-
-    // 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 sphereShape = isCapsuleA ? colB.shape : colA.shape;
-        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, sphereShape.radius
-        );
-        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;
-    }
-
-    // convex hull ↔ convex hull (multi-point clipping via GJK + EPA + face-clip).
-    if (shapeA.isConvexHullShape3D === true && shapeB.isConvexHullShape3D === true) {
-        return hull_pair_contacts(count, shapeA, trA, shapeB, trB, append_contact);
-    }
-
-    // mesh ↔ mesh. A globally-convex mesh collides as a single cached hull
-    // (one GJK + EPA + clip) — the greedy decomposition fragments even a convex
-    // mesh, so detecting convexity and routing through the hull path is the
-    // scalable fast path. When BOTH meshes are convex, use it; otherwise fall to
-    // the per-piece decomposed path (convex pieces vs convex pieces).
-    if (shapeA.isMeshShape3D === true && shapeB.isMeshShape3D === true) {
-        const hullA = get_mesh_convex_hull(shapeA);
-        const hullB = get_mesh_convex_hull(shapeB);
-        if (hullA !== null && hullB !== null) {
-            return hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact);
-        }
-        return mesh_mesh_tet_contacts(count, shapeA, trA, shapeB, trB, append_contact);
-    }
-
-    // ── 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.
-        aabb3_transform_oriented_inverse(
-            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.
-        //    The enumerator returns the TRUE overlap count — clamp to the
-        //    scratch capacity (overflow writes were dropped; reading past the
-        //    buffer would poison the manifold with NaN).
-        let 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 > MAX_TRIANGLES_PER_PAIR) tri_count = MAX_TRIANGLES_PER_PAIR;
-        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 sphere 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.isSphereShape3D === true;
-        const sphere_radius = isSphereConvex ? convex_col.shape.radius : 0;
-
-        // 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 PosedShape3D.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
-                // via the shared helper.
-                triangle_vertices_to_world(
-                    scratch_tri_world,
-                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
-                    cqx, cqy, cqz, cqw,
-                    c_pos_x, c_pos_y, c_pos_z
-                );
-                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
-                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
-                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
-
-                const ok = sphere_triangle_contact(
-                    sphere_triangle_result,
-                    convex_wx, convex_wy, convex_wz, sphere_radius,
-                    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
-                // via the shared helper.
-                triangle_vertices_to_world(
-                    scratch_tri_world,
-                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
-                    cqx, cqy, cqz, cqw,
-                    c_pos_x, c_pos_y, c_pos_z
-                );
-                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
-                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
-                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
-
-                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
-                // via the shared helper.
-                triangle_vertices_to_world(
-                    scratch_tri_world,
-                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
-                    cqx, cqy, cqz, cqw,
-                    c_pos_x, c_pos_y, c_pos_z
-                );
-                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
-                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
-                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
-
-                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;
-            }
-
-            // Robust GJK + EPA (see gjk/gjk_epa_penetration.js): returns the
-            // penetration depth and writes a UNIT axis into epa_result. We scale
-            // it to the MTV vector (ex,ey,ez) the tuned sign-check / one-sided
-            // rejection / dedup below already consume. The old gjk_with_axis +
-            // expanding_polytope_algorithm pair was replaced because it returned
-            // a non-minimal axis on degenerate simplices (see memory:
-            // feedback_epa_unreliable_polytopes); MPR is kept as a secondary
-            // safety net for the rare case the robust query reports no overlap.
-            let ex, ey, ez, depth;
-            const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
-            if (pen_depth > 0 && Number.isFinite(pen_depth)) {
-                ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
-                depth = pen_depth;
-            } else {
-                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;
-    }
-
-    // Robust GJK + EPA fallback for any convex pair without a closed form or a
-    // dedicated branch above (e.g. a primitive vs an authored ConvexHullShape3D,
-    // a cylinder/cone). gjk_epa_penetration returns the depth and writes a UNIT
-    // axis into epa_result; we scale to the MTV vector (ex,ey,ez) the body-centre
-    // sign-guard below consumes. Replaces the old gjk_with_axis +
-    // expanding_polytope_algorithm pair, which returned a non-minimal axis on the
-    // degenerate simplices its GJK produced (see memory:
-    // feedback_epa_unreliable_polytopes). MPR is kept as a secondary safety net.
-    posed_a.setup(colA.shape, trA.position, trA.rotation);
-    posed_b.setup(colB.shape, trB.position, trB.rotation);
-
-    let ex, ey, ez, depth;
-    const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
-    if (pen_depth > 0 && Number.isFinite(pen_depth)) {
-        ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
-        depth = pen_depth;
-    } else {
-        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
-    );
-}
-
-// Reusable single-pair adapters for the penetration query below — no per-call
-// allocation. dispatch_pair only reads `.shape` off a collider and
-// `.position` / `.rotation` off a transform, so these minimal stand-ins are
-// all it needs.
-const _pp_colA = { shape: null };
-const _pp_colB = { shape: null };
-const _pp_trA = { position: null, rotation: null };
-const _pp_trB = { position: null, rotation: null };
-
-
-/**
- * Single-pair penetration query: the depth and world normal of the DEEPEST
- * contact the narrowphase would generate for one posed shape pair.
- *
- * Routes through the exact same {@link dispatch_pair} the contact solver
- * consumes — closed-form for every sphere / box / capsule pair (box-box via
- * SAT, so the true minimum-translation axis is found rather than the
- * centroid-seeded portal MPR would pick), triangle decomposition + closed-form
- * per triangle for convex-vs-concave, and GJK + EPA (+ MPR) for any other
- * convex pair. The deepest contact's depth is the minimum-translation distance
- * and its normal is the MTV axis, so the result is correct for every shape pair
- * the engine can build and agrees bit-for-bit with what the solver acts on.
- *
- * The normal follows the narrowphase's stored convention: a unit vector
- * pointing from B toward A — the direction to translate A to separate it.
- *
- * Concave-vs-concave is not dispatched (the narrowphase skips it) and returns
- * 0; callers needing to reject that case must check `is_convex` themselves.
- *
- * Not re-entrant: shares the module-level candidate / scratch buffers with
- * {@link narrowphase_step}. Intended for main-thread queries run outside a
- * step (depenetration, overlap depth, tooling) — never from inside one.
- *
- * @param {Float64Array|number[]} out_normal length ≥ 3; receives the unit B→A
- *   normal on penetration (untouched when the return value is 0)
- * @param {AbstractShape3D} shapeA
- * @param {{x:number,y:number,z:number}} posA
- * @param {{x:number,y:number,z:number,w:number}} rotA
- * @param {AbstractShape3D} shapeB
- * @param {{x:number,y:number,z:number}} posB
- * @param {{x:number,y:number,z:number,w:number}} rotB
- * @returns {number} deepest penetration depth (> 0) or 0 if separated
- */
-export function deepest_pair_penetration(out_normal, shapeA, posA, rotA, shapeB, posB, rotB) {
-    _pp_colA.shape = shapeA;
-    _pp_trA.position = posA;
-    _pp_trA.rotation = rotA;
-    _pp_colB.shape = shapeB;
-    _pp_trB.position = posB;
-    _pp_trB.rotation = rotB;
-
-    const n = dispatch_pair(0, _pp_colA, _pp_trA, _pp_colB, _pp_trB);
-    if (n === 0) {
-        return 0;
-    }
-
-    // Deepest contact = the minimum-translation depth; its stored normal is the
-    // separation axis. (For multi-point manifolds — box-box, capsule-box, a
-    // convex straddling several mesh triangles — every point shares the
-    // separating axis, so the max depth along it is the distance to separate.)
-    let best_depth = -1;
-    let best_off = 0;
-    for (let i = 0; i < n; i++) {
-        const off = i * CANDIDATE_STRIDE;
-        const d = candidates[off + 9];
-        if (d > best_depth) {
-            best_depth = d;
-            best_off = off;
-        }
-    }
-
-    if (!(best_depth > 0) || !Number.isFinite(best_depth)) {
-        return 0;
-    }
-
-    out_normal[0] = candidates[best_off + 6];
-    out_normal[1] = candidates[best_off + 7];
-    out_normal[2] = candidates[best_off + 8];
-
-    return best_depth;
-}
-
-/**
- * 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;
-
-        let sub_pair = 0;
-        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];
-
-                const before = cand_count;
-                cand_count = dispatch_pair(
-                    cand_count,
-                    ea.collider,
-                    ea.transform,
-                    eb.collider,
-                    eb.transform
-                );
-
-                // Salt this sub-pair's fids ({@link FID_PAIR_SALT}) so a
-                // compound body cannot fid-match — and inherit warm-start
-                // impulses — across different collider pairs. fid 0 stays 0.
-                if (sub_pair !== 0) {
-                    const salt = sub_pair * FID_PAIR_SALT;
-                    for (let c = before; c < cand_count; c++) {
-                        const co = c * CANDIDATE_STRIDE;
-                        if (candidates[co + 10] !== 0) candidates[co + 10] += salt;
-                    }
-                }
-                sub_pair++;
-            }
-        }
-
-        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_manifold_contacts(candidates, cand_count, CANDIDATE_STRIDE, MAX_KEPT, 9);
-
-        // ── 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"). Same-fid prev
-        //           contacts are disambiguated by NEAREST previous witness:
-        //           a fid identifies the FEATURE (e.g. a triangle), not the
-        //           contact point — the box/capsule-triangle paths emit up
-        //           to 4 contacts sharing one triangle's fid, and the
-        //           reducer reorders them frame to frame, so first-match
-        //           would shuffle warm-start impulses between a face's own
-        //           contact points. (redetect_pair_geometry documents and
-        //           fixes the same failure for the per-substep path.)
-        //   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) {
-                // Gated by FID_MATCH_MAX_D2: a fid recomputed half a metre
-                // away (teleport, fid collision) must not inherit impulses.
-                let best_d2 = FID_MATCH_MAX_D2;
-                for (let j = 0; j < prev_count; j++) {
-                    if (prev_claimed[j]) continue;
-                    if (prev_snapshot[j * 7] !== cand_fid) 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; }
-                }
-            }
-            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],
-                candidates[off + 11], candidates[off + 12]
-            );
-            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);
-            }
-        }
-    }
-}
-
-/**
- * Re-detect contact GEOMETRY for one existing manifold slot at the bodies'
- * current poses, updating the witness points / normal / depth of the slot's
- * existing contacts in place. Does NOT change the contact count, the
- * feature ids, or the accumulated impulses — it only refreshes geometry.
- *
- * This is the per-substep concave path (TGS): for a contact pair involving a
- * concave body, the contact *feature* (which triangle is deepest, and its
- * normal) genuinely changes as the body rocks, so the solver's cheap analytic
- * refresh — which freezes the feature for the whole outer step — pumps energy
- * in. Re-running the narrowphase geometry each substep gives a fresh,
- * correct normal so the body settles instead of rocking. Convex pairs keep
- * the analytic refresh and never call this (their feature is stable).
- *
- * Matching is by feature id (stable per-triangle for the decomposition path),
- * so a contact's geometry tracks the same triangle across substeps. A contact
- * whose triangle isn't found this substep keeps its previous geometry (a rare
- * transient; the once-per-frame {@link narrowphase_step} re-establishes the
- * contact set next outer step). Count never changes here, so the solver's
- * per-contact scratch (sized once at prepare) stays aligned.
- *
- * @param {ManifoldStore} manifolds
- * @param {number} slot
- * @param {Array<{collider: Collider, transform: Transform}>} list_a
- * @param {Array<{collider: Collider, transform: Transform}>} list_b
- */
-export function redetect_pair_geometry(manifolds, slot, list_a, list_b) {
-    if (list_a === undefined || list_b === undefined) return;
-    const la_len = list_a.length;
-    const lb_len = list_b.length;
-    if (la_len === 0 || lb_len === 0) return;
-
-    const count = manifolds.contact_count(slot);
-    if (count === 0) return;
-
-    let cc = 0;
-    let sub_pair = 0;
-    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];
-            const before = cc;
-            cc = dispatch_pair(cc, ea.collider, ea.transform, eb.collider, eb.transform);
-            // Stored fids are sub-pair-salted (see narrowphase_step's dispatch
-            // loop) — salt the redetected candidates identically or no fid
-            // would ever match for a compound body's non-first sub-pair.
-            if (sub_pair !== 0) {
-                const salt = sub_pair * FID_PAIR_SALT;
-                for (let c = before; c < cc; c++) {
-                    const co = c * CANDIDATE_STRIDE;
-                    if (candidates[co + 10] !== 0) candidates[co + 10] += salt;
-                }
-            }
-            sub_pair++;
-        }
-    }
-    if (cc === 0) return; // nothing re-detected this substep — keep frozen geometry
-
-    const data = manifolds.data_buffer;
-    const slot_off = manifolds.slot_data_offset(slot);
-
-    // Match each existing contact to a DISTINCT fresh candidate. feature_id
-    // identifies the TRIANGLE, not the contact point — the box/capsule-triangle
-    // paths emit several contacts for one triangle, all sharing that triangle's
-    // single fid (a flat box-on-heightmap cell yields fids like [6,6,6,7]). A
-    // plain first-match-by-fid therefore maps every same-fid existing contact
-    // onto the SAME candidate, collapsing the manifold to duplicate witness
-    // points → a degenerate support polygon the solver can't damp (the
-    // box-on-heightmap rattle). So: gate by fid, disambiguate same-fid
-    // candidates by NEAREST previous witness (world-A) position, and claim each
-    // candidate so no two existing contacts take the same one. For the common
-    // unique-fid case (sphere/mesh: one contact per triangle) this picks that
-    // single candidate exactly once — identical to the old behaviour.
-    for (let k = 0; k < cc; k++) redetect_claimed[k] = 0;
-
-    for (let j = 0; j < count; j++) {
-        const off = slot_off + j * CONTACT_STRIDE;
-        const fid = data[off + 13];
-        if (fid === 0) continue; // no feature info to match on
-
-        // Previous witness (world-A) of this existing contact — the anchor we
-        // disambiguate same-fid candidates against.
-        const pax = data[off];
-        const pay = data[off + 1];
-        const paz = data[off + 2];
-
-        let best_k = -1;
-        let best_d2 = Infinity;
-        for (let k = 0; k < cc; k++) {
-            if (redetect_claimed[k] === 1) continue;
-            const co = k * CANDIDATE_STRIDE;
-            if (candidates[co + 10] !== fid) continue;
-            const dx = candidates[co]     - pax;
-            const dy = candidates[co + 1] - pay;
-            const dz = candidates[co + 2] - paz;
-            const d2 = dx * dx + dy * dy + dz * dz;
-            if (d2 < best_d2) {
-                best_d2 = d2;
-                best_k = k;
-            }
-        }
-
-        // Position fallback (mirrors narrowphase_step's match-and-merge). A
-        // single triangle's clipped contact count is NOT stable across sub-mm
-        // pose changes — a box straddling a cell seam can have one triangle
-        // yield 4 points one substep and 3 the next — so an existing contact can
-        // outnumber this substep's same-fid candidates. Freezing its stale
-        // witness then duplicates a sibling contact's point, leaving a
-        // degenerate (sub-dimensional) manifold. Instead, claim the nearest
-        // unclaimed candidate of ANY fid: every contact keeps a DISTINCT live
-        // witness. The fid label is left intact and re-resolved by the next
-        // once-per-step narrowphase. (At a fixed pose the same-fid match always
-        // succeeds, so this never fires for the depth-equality guards or the
-        // one-contact-per-triangle sphere/mesh paths.)
-        if (best_k === -1) {
-            for (let k = 0; k < cc; k++) {
-                if (redetect_claimed[k] === 1) continue;
-                const co = k * CANDIDATE_STRIDE;
-                const dx = candidates[co]     - pax;
-                const dy = candidates[co + 1] - pay;
-                const dz = candidates[co + 2] - paz;
-                const d2 = dx * dx + dy * dy + dz * dz;
-                if (d2 < best_d2) {
-                    best_d2 = d2;
-                    best_k = k;
-                }
-            }
-        }
-
-        if (best_k === -1) continue; // no unclaimed candidate at all this substep — keep frozen geometry
-
-        redetect_claimed[best_k] = 1;
-        const co = best_k * CANDIDATE_STRIDE;
-        // Overwrite geometry only: witnesses, normal, depth. (Count, feature
-        // ids and accumulated impulses are intentionally left untouched — see
-        // the function contract.)
-        data[off]     = candidates[co];
-        data[off + 1] = candidates[co + 1];
-        data[off + 2] = candidates[co + 2];
-        data[off + 3] = candidates[co + 3];
-        data[off + 4] = candidates[co + 4];
-        data[off + 5] = candidates[co + 5];
-        data[off + 6] = candidates[co + 6];
-        data[off + 7] = candidates[co + 7];
-        data[off + 8] = candidates[co + 8];
-        data[off + 9] = candidates[co + 9];
-    }
-}
+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 { combine_friction, combine_restitution } from "../contact/combine_material.js";
+import { CONTACT_STRIDE, MAX_CONTACTS_PER_MANIFOLD } from "../contact/ManifoldStore.js";
+import { gjk_epa_penetration } from "../../../core/geom/3d/gjk/gjk_epa_penetration.js";
+import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
+import { mpr } from "../../../core/geom/3d/gjk/mpr.js";
+import { box_box_manifold, BOX_BOX_OUT_LENGTH } from "./box_box_manifold.js";
+import { convex_hull_clip, CONVEX_CONVEX_OUT_LENGTH } from "./convex_convex_manifold.js";
+import { get_mesh_convex_hull } from "./mesh_convex_hull.js";
+import { mesh_mesh_tet_contacts } from "./mesh_mesh_tet_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_CAPSULE_CONTACT_STRIDE,
+    capsule_capsule_multi_contacts,
+    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 { aabb3_transform_oriented_inverse } from "../../../core/geom/3d/aabb/aabb3_transform_oriented_inverse.js";
+import { decompose_to_triangles } from "./decomposition/decompose_to_triangles.js";
+import { TRIANGLE_FLOAT_STRIDE } from "./decomposition/triangle_buffer_layout.js";
+import { PosedShape3D } from "../../../core/geom/3d/shape/PosedShape3D.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 PosedShape3D();
+const posed_b = new PosedShape3D();
+
+// Penetration axis + depth from the robust GJK + EPA query
+// (gjk_epa_penetration writes a unit normal here; it owns its own simplex
+// internally, so the narrowphase no longer keeps a simplex buffer).
+const epa_result = new Float64Array(3);
+const sphere_result = new Float64Array(4);
+const closed_form_result = new Float64Array(10);
+
+/** Scratch for the capsule-capsule multi-contact manifold (2 contacts max). */
+const capsule_capsule_result = new Float64Array(2 * CAPSULE_CAPSULE_CONTACT_STRIDE);
+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 convex_manifold_result = new Float64Array(CONVEX_CONVEX_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, friction, restitution.
+ *
+ * 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".
+ *
+ * `friction` (offset 11) and `restitution` (offset 12) are the COMBINED
+ * coefficients for the specific (colliderA, colliderB) pair that produced this
+ * contact, combined here (the only place that knows the exact source collider
+ * on each side) and carried into the manifold so a compound body's per-collider
+ * materials are honoured per-contact.
+ *
+ * @type {number}
+ */
+const CANDIDATE_STRIDE = 13;
+
+/**
+ * Combined friction / restitution for the collider pair currently being
+ * dispatched. Set once at the top of {@link dispatch_pair} (which is called
+ * per collider pair) and written into every contact that call appends, so
+ * each contact carries the material of its actual source colliders. Module
+ * scratch rather than threaded through every `append_contact` call site.
+ * @type {number}
+ */
+let g_pair_friction = 0;
+let g_pair_restitution = 0;
+
+/**
+ * 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;
+
+/**
+ * Per-(colliderA, colliderB) feature-id salt. Each emitter numbers its
+ * features in a small private range (sphere-box voronoi 1..27, capsule-box
+ * 1..k, triangles 1..N, …), so two SUB-PAIRS of a compound body can produce
+ * identical fids for unrelated features and warm-start impulses could be
+ * inherited across collider pairs. Salting by the sub-pair index keeps every
+ * fid unique across the body pair while staying exactly representable in f64
+ * (sub_pair · 2³² + fid stays far below 2⁵³ for any realistic compound; no
+ * single-pair emitter exceeds 2³²). Sub-pair 0 — the universal
+ * single-collider case — is left unsalted, so simple bodies see unchanged
+ * fids.
+ * @type {number}
+ */
+const FID_PAIR_SALT = 0x100000000; // 2^32
+
+/**
+ * Distance ceiling for a feature-id warm-start match. A fid match may track
+ * a fast-sliding contact far beyond {@link MATCH_TOL_SQR} — that is its
+ * advantage over position matching — but an impulse inherited across half a
+ * metre in one frame is stale by any standard (a teleported body re-deriving
+ * the same voronoi bucket, or a fid collision between unrelated features).
+ * The position fallback keeps its own 2 cm gate.
+ * @type {number}
+ */
+const FID_MATCH_MAX_D2 = 0.5 * 0.5;
+
+/**
+ * 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-candidate "already claimed" flags for {@link redetect_pair_geometry}'s
+ * 1:1 existing-contact → fresh-candidate matching. Sized to the candidate
+ * buffer capacity (64) so it covers any per-pair candidate count. Without it,
+ * several existing contacts that share one triangle's `feature_id` (the
+ * box/capsule-triangle paths emit multiple contacts per triangle) would all
+ * match the same first candidate, collapsing the manifold to duplicate witness
+ * points.
+ * @type {Uint8Array}
+ */
+const redetect_claimed = new Uint8Array(64);
+
+/**
+ * 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.
+ *
+ * For a heightmap the per-cell triangle count scales O(N²) with the
+ * shape's {@link HeightMapShape3D#tessellation} (a sub-cell quad is 2
+ * triangles, and there are N×N sub-cells per sampler cell). The bounded
+ * query AABB keeps the cell count small, so a typical pair stays well
+ * inside 1024 at moderate tessellation; the silent-drop backstop below
+ * covers any overflow at extreme values.
+ *
+ * Enumerators return the TRUE overlap count and have no bounds check of
+ * their own: writes past the scratch buffer are dropped (typed-array OOB
+ * semantics), so on overflow the consume loop MUST clamp the returned
+ * count to this cap or it reads `undefined` past the end and poisons the
+ * manifold with NaN. The worst case after clamping 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);
+
+/**
+ * Rotate + translate a triangle's three vertices from a concave body's
+ * local frame into world space: writes 9 floats `(A_w, B_w, C_w)` into
+ * `out`. Inlined `q · v · q*` + translate per vertex (see
+ * PosedShape3D.support for the V8-inliner rationale); the operation order
+ * matches the blocks this replaced bit-exactly. Per-vertex cost ~21 flops
+ * × 3 — essentially free next to any narrowphase kernel it feeds.
+ *
+ * Shared by the sphere / box / capsule closed-form triangle fast-paths in
+ * the concave dispatch, which each carried an identical inlined copy.
+ */
+function triangle_vertices_to_world(out, ax, ay, az, bx, by, bz, cx, cy, cz, qx, qy, qz, qw, px, py, pz) {
+    const axi =  qw * ax + qy * az - qz * ay;
+    const ayi =  qw * ay + qz * ax - qx * az;
+    const azi =  qw * az + qx * ay - qy * ax;
+    const awi = -qx * ax - qy * ay - qz * az;
+
+    out[0] = axi * qw + awi * -qx + ayi * -qz - azi * -qy + px;
+    out[1] = ayi * qw + awi * -qy + azi * -qx - axi * -qz + py;
+    out[2] = azi * qw + awi * -qz + axi * -qy - ayi * -qx + pz;
+
+    const bxi =  qw * bx + qy * bz - qz * by;
+    const byi =  qw * by + qz * bx - qx * bz;
+    const bzi =  qw * bz + qx * by - qy * bx;
+    const bwi = -qx * bx - qy * by - qz * bz;
+
+    out[3] = bxi * qw + bwi * -qx + byi * -qz - bzi * -qy + px;
+    out[4] = byi * qw + bwi * -qy + bzi * -qx - bxi * -qz + py;
+    out[5] = bzi * qw + bwi * -qz + bxi * -qy - byi * -qx + pz;
+
+    const cxi =  qw * cx + qy * cz - qz * cy;
+    const cyi =  qw * cy + qz * cx - qx * cz;
+    const czi =  qw * cz + qx * cy - qy * cx;
+    const cwi = -qx * cx - qy * cy - qz * cz;
+
+    out[6] = cxi * qw + cwi * -qx + cyi * -qz - czi * -qy + px;
+    out[7] = cyi * qw + cwi * -qy + czi * -qx - cxi * -qz + py;
+    out[8] = czi * qw + cwi * -qz + cxi * -qy - cyi * -qx + pz;
+}
+
+/** Destination for {@link triangle_vertices_to_world}. */
+const scratch_tri_world = new Float64Array(9);
+
+/**
+ * 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;
+    candidates[off + 11] = g_pair_friction;
+    candidates[off + 12] = g_pair_restitution;
+
+    return count + 1;
+}
+
+/**
+ * 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 PosedShape3D.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;
+}
+
+/**
+ * Multi-point contact manifold between two convex polytopes (authored
+ * ConvexHullShape3D, or a convex MeshShape3D represented as one hull). Robust
+ * GJK + EPA finds the separating axis in O(support queries) — face-count
+ * independent, where SAT's edge-pair term is prohibitive — then
+ * {@link convex_hull_clip} clips the reference/incident faces into a face-on-face
+ * patch around it (Bullet's clipHullAgainstHull). A single GJK+EPA contact can't
+ * resist a stack's toppling torque; the clipped patch holds it. No cross-frame
+ * state → reset-and-resimulate determinism.
+ *
+ * @param {number} count
+ * @param {{vertices,face_offsets,face_loops,support}} hullA  in A's local frame
+ * @param {Transform} trA
+ * @param {{vertices,face_offsets,face_loops,support}} hullB  in B's local frame
+ * @param {Transform} trB
+ * @param {Function} append_contact
+ * @returns {number}
+ */
+function hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact) {
+    posed_a.setup(hullA, trA.position, trA.rotation);
+    posed_b.setup(hullB, trB.position, trB.rotation);
+    const depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+    if (!(depth > 0) || !Number.isFinite(depth)) return count;
+
+    // convex_hull_clip orients the axis B→A robustly (via vertex centroids) and
+    // writes the final normal into convex_manifold_result[0..2].
+    convex_hull_clip(convex_manifold_result,
+        hullA, trA.position, trA.rotation,
+        hullB, trB.position, trB.rotation,
+        epa_result[0], epa_result[1], epa_result[2]);
+    const nx = convex_manifold_result[0], ny = convex_manifold_result[1], nz = convex_manifold_result[2];
+    const cc = convex_manifold_result[3] | 0;
+    // Clipped points migrate across features as the hulls rotate, so leave
+    // fid = 0 and let the match-and-merge pass position-match (as box-box does).
+    for (let k = 0; k < cc; k++) {
+        const base = 4 + k * 7;
+        count = append_contact(count,
+            convex_manifold_result[base],     convex_manifold_result[base + 1], convex_manifold_result[base + 2],
+            convex_manifold_result[base + 3], convex_manifold_result[base + 4], convex_manifold_result[base + 5],
+            nx, ny, nz,
+            convex_manifold_result[base + 6],
+            0);
+    }
+    return count;
+}
+
+/**
+ * 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.
+ *
+ * @param {number} count
+ * @param {Collider} colA
+ * @param {Transform} trA
+ * @param {Collider} colB
+ * @param {Transform} trB
+ * @returns {number}
+ */
+function dispatch_pair(count, colA, trA, colB, trB) {
+    const shapeA = colA.shape;
+    const shapeB = colB.shape;
+
+    // Per-contact materials: combine the two source colliders' coefficients
+    // once here (this is the only place that knows the exact collider on each
+    // side) and stamp them onto every contact this dispatch appends. The
+    // `deepest_pair_penetration` query passes bare `{shape}` adapters with no
+    // material fields — it never writes to a manifold, so 0 is fine there.
+    const fa = colA.friction, fb = colB.friction;
+
+    if (fa !== undefined && fb !== undefined) {
+
+        g_pair_friction = combine_friction(fa, fb);
+        g_pair_restitution = combine_restitution(colA.restitution, colB.restitution);
+
+    } else {
+        g_pair_friction = 0;
+        g_pair_restitution = 0;
+    }
+
+    // isSphereShape3D covers both UnitSphereShape3D (fixed radius 1) and
+    // SphereShape3D (arbitrary radius). Both expose `radius`.
+    const isSphereA = shapeA.isSphereShape3D === true;
+    const isSphereB = shapeB.isSphereShape3D === 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 ra = shapeA.radius, rb = shapeB.radius;
+
+        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,
+            ra, rb
+        );
+
+        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. Witnesses are the surface
+        // points along the (unit) normal, scaled by each sphere's radius.
+        return append_contact(count,
+            trA.position.x - nx * ra, trA.position.y - ny * ra, trA.position.z - nz * ra,
+            trB.position.x + nx * rb, trB.position.y + ny * rb, trB.position.z + nz * rb,
+            nx, ny, nz, sphere_result[3], 1);
+    }
+
+    // sphere ↔ box
+    if ((isSphereA && isBoxB) || (isBoxA && isSphereB)) {
+        const sphereTr    = isSphereA ? trA : trB;
+        const sphereShape = isSphereA ? shapeA : shapeB;
+        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, sphereShape.radius,
+            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 (multi-point: near-parallel overlap emits both ends of
+    // the overlap interval; everything else the single closest-point contact)
+    if (isCapsuleA && isCapsuleB) {
+        const a_shape = colA.shape, b_shape = colB.shape;
+        const n_cc = capsule_capsule_multi_contacts(
+            capsule_capsule_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
+        );
+        for (let k = 0; k < n_cc; k++) {
+            const off = k * CAPSULE_CAPSULE_CONTACT_STRIDE;
+            // fid = k + 1: stable per interval end (1-based; 0 = no info).
+            count = append_contact(count,
+                capsule_capsule_result[off],     capsule_capsule_result[off + 1], capsule_capsule_result[off + 2],
+                capsule_capsule_result[off + 3], capsule_capsule_result[off + 4], capsule_capsule_result[off + 5],
+                capsule_capsule_result[off + 6], capsule_capsule_result[off + 7], capsule_capsule_result[off + 8],
+                capsule_capsule_result[off + 9], k + 1);
+        }
+        return count;
+    }
+
+    // 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 sphereShape = isCapsuleA ? colB.shape : colA.shape;
+        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, sphereShape.radius
+        );
+        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;
+    }
+
+    // convex hull ↔ convex hull (multi-point clipping via GJK + EPA + face-clip).
+    if (shapeA.isConvexHullShape3D === true && shapeB.isConvexHullShape3D === true) {
+        return hull_pair_contacts(count, shapeA, trA, shapeB, trB, append_contact);
+    }
+
+    // mesh ↔ mesh. A globally-convex mesh collides as a single cached hull
+    // (one GJK + EPA + clip) — the greedy decomposition fragments even a convex
+    // mesh, so detecting convexity and routing through the hull path is the
+    // scalable fast path. When BOTH meshes are convex, use it; otherwise fall to
+    // the per-piece decomposed path (convex pieces vs convex pieces).
+    if (shapeA.isMeshShape3D === true && shapeB.isMeshShape3D === true) {
+        const hullA = get_mesh_convex_hull(shapeA);
+        const hullB = get_mesh_convex_hull(shapeB);
+        if (hullA !== null && hullB !== null) {
+            return hull_pair_contacts(count, hullA, trA, hullB, trB, append_contact);
+        }
+        return mesh_mesh_tet_contacts(count, shapeA, trA, shapeB, trB, append_contact);
+    }
+
+    // ── 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.
+        aabb3_transform_oriented_inverse(
+            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.
+        //    The enumerator returns the TRUE overlap count — clamp to the
+        //    scratch capacity (overflow writes were dropped; reading past the
+        //    buffer would poison the manifold with NaN).
+        let 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 > MAX_TRIANGLES_PER_PAIR) tri_count = MAX_TRIANGLES_PER_PAIR;
+        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 sphere 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.isSphereShape3D === true;
+        const sphere_radius = isSphereConvex ? convex_col.shape.radius : 0;
+
+        // 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 PosedShape3D.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
+                // via the shared helper.
+                triangle_vertices_to_world(
+                    scratch_tri_world,
+                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
+                    cqx, cqy, cqz, cqw,
+                    c_pos_x, c_pos_y, c_pos_z
+                );
+                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
+                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
+                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
+
+                const ok = sphere_triangle_contact(
+                    sphere_triangle_result,
+                    convex_wx, convex_wy, convex_wz, sphere_radius,
+                    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
+                // via the shared helper.
+                triangle_vertices_to_world(
+                    scratch_tri_world,
+                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
+                    cqx, cqy, cqz, cqw,
+                    c_pos_x, c_pos_y, c_pos_z
+                );
+                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
+                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
+                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
+
+                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
+                // via the shared helper.
+                triangle_vertices_to_world(
+                    scratch_tri_world,
+                    ax, ay, az, bx, by, bz, cx_v, cy_v, cz_v,
+                    cqx, cqy, cqz, cqw,
+                    c_pos_x, c_pos_y, c_pos_z
+                );
+                const ax_w = scratch_tri_world[0], ay_w = scratch_tri_world[1], az_w = scratch_tri_world[2];
+                const bx_w = scratch_tri_world[3], by_w = scratch_tri_world[4], bz_w = scratch_tri_world[5];
+                const cx_w = scratch_tri_world[6], cy_w = scratch_tri_world[7], cz_w = scratch_tri_world[8];
+
+                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;
+            }
+
+            // Robust GJK + EPA (see gjk/gjk_epa_penetration.js): returns the
+            // penetration depth and writes a UNIT axis into epa_result. We scale
+            // it to the MTV vector (ex,ey,ez) the tuned sign-check / one-sided
+            // rejection / dedup below already consume. The old gjk_with_axis +
+            // expanding_polytope_algorithm pair was replaced because it returned
+            // a non-minimal axis on degenerate simplices (see memory:
+            // feedback_epa_unreliable_polytopes); MPR is kept as a secondary
+            // safety net for the rare case the robust query reports no overlap.
+            let ex, ey, ez, depth;
+            const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+            if (pen_depth > 0 && Number.isFinite(pen_depth)) {
+                ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
+                depth = pen_depth;
+            } else {
+                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;
+    }
+
+    // Robust GJK + EPA fallback for any convex pair without a closed form or a
+    // dedicated branch above (e.g. a primitive vs an authored ConvexHullShape3D,
+    // a cylinder/cone). gjk_epa_penetration returns the depth and writes a UNIT
+    // axis into epa_result; we scale to the MTV vector (ex,ey,ez) the body-centre
+    // sign-guard below consumes. Replaces the old gjk_with_axis +
+    // expanding_polytope_algorithm pair, which returned a non-minimal axis on the
+    // degenerate simplices its GJK produced (see memory:
+    // feedback_epa_unreliable_polytopes). MPR is kept as a secondary safety net.
+    posed_a.setup(colA.shape, trA.position, trA.rotation);
+    posed_b.setup(colB.shape, trB.position, trB.rotation);
+
+    let ex, ey, ez, depth;
+    const pen_depth = gjk_epa_penetration(epa_result, posed_a, posed_b);
+    if (pen_depth > 0 && Number.isFinite(pen_depth)) {
+        ex = epa_result[0] * pen_depth; ey = epa_result[1] * pen_depth; ez = epa_result[2] * pen_depth;
+        depth = pen_depth;
+    } else {
+        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
+    );
+}
+
+// Reusable single-pair adapters for the penetration query below — no per-call
+// allocation. dispatch_pair only reads `.shape` off a collider and
+// `.position` / `.rotation` off a transform, so these minimal stand-ins are
+// all it needs.
+const _pp_colA = { shape: null };
+const _pp_colB = { shape: null };
+const _pp_trA = { position: null, rotation: null };
+const _pp_trB = { position: null, rotation: null };
+
+
+/**
+ * Single-pair penetration query: the depth and world normal of the DEEPEST
+ * contact the narrowphase would generate for one posed shape pair.
+ *
+ * Routes through the exact same {@link dispatch_pair} the contact solver
+ * consumes — closed-form for every sphere / box / capsule pair (box-box via
+ * SAT, so the true minimum-translation axis is found rather than the
+ * centroid-seeded portal MPR would pick), triangle decomposition + closed-form
+ * per triangle for convex-vs-concave, and GJK + EPA (+ MPR) for any other
+ * convex pair. The deepest contact's depth is the minimum-translation distance
+ * and its normal is the MTV axis, so the result is correct for every shape pair
+ * the engine can build and agrees bit-for-bit with what the solver acts on.
+ *
+ * The normal follows the narrowphase's stored convention: a unit vector
+ * pointing from B toward A — the direction to translate A to separate it.
+ *
+ * Concave-vs-concave is not dispatched (the narrowphase skips it) and returns
+ * 0; callers needing to reject that case must check `is_convex` themselves.
+ *
+ * Not re-entrant: shares the module-level candidate / scratch buffers with
+ * {@link narrowphase_step}. Intended for main-thread queries run outside a
+ * step (depenetration, overlap depth, tooling) — never from inside one.
+ *
+ * @param {Float64Array|number[]} out_normal length ≥ 3; receives the unit B→A
+ *   normal on penetration (untouched when the return value is 0)
+ * @param {AbstractShape3D} shapeA
+ * @param {{x:number,y:number,z:number}} posA
+ * @param {{x:number,y:number,z:number,w:number}} rotA
+ * @param {AbstractShape3D} shapeB
+ * @param {{x:number,y:number,z:number}} posB
+ * @param {{x:number,y:number,z:number,w:number}} rotB
+ * @returns {number} deepest penetration depth (> 0) or 0 if separated
+ */
+export function deepest_pair_penetration(out_normal, shapeA, posA, rotA, shapeB, posB, rotB) {
+    _pp_colA.shape = shapeA;
+    _pp_trA.position = posA;
+    _pp_trA.rotation = rotA;
+    _pp_colB.shape = shapeB;
+    _pp_trB.position = posB;
+    _pp_trB.rotation = rotB;
+
+    const n = dispatch_pair(0, _pp_colA, _pp_trA, _pp_colB, _pp_trB);
+    if (n === 0) {
+        return 0;
+    }
+
+    // Deepest contact = the minimum-translation depth; its stored normal is the
+    // separation axis. (For multi-point manifolds — box-box, capsule-box, a
+    // convex straddling several mesh triangles — every point shares the
+    // separating axis, so the max depth along it is the distance to separate.)
+    let best_depth = -1;
+    let best_off = 0;
+    for (let i = 0; i < n; i++) {
+        const off = i * CANDIDATE_STRIDE;
+        const d = candidates[off + 9];
+        if (d > best_depth) {
+            best_depth = d;
+            best_off = off;
+        }
+    }
+
+    if (!(best_depth > 0) || !Number.isFinite(best_depth)) {
+        return 0;
+    }
+
+    out_normal[0] = candidates[best_off + 6];
+    out_normal[1] = candidates[best_off + 7];
+    out_normal[2] = candidates[best_off + 8];
+
+    return best_depth;
+}
+
+/**
+ * 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;
+
+        let sub_pair = 0;
+        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];
+
+                const before = cand_count;
+                cand_count = dispatch_pair(
+                    cand_count,
+                    ea.collider,
+                    ea.transform,
+                    eb.collider,
+                    eb.transform
+                );
+
+                // Salt this sub-pair's fids ({@link FID_PAIR_SALT}) so a
+                // compound body cannot fid-match — and inherit warm-start
+                // impulses — across different collider pairs. fid 0 stays 0.
+                if (sub_pair !== 0) {
+                    const salt = sub_pair * FID_PAIR_SALT;
+                    for (let c = before; c < cand_count; c++) {
+                        const co = c * CANDIDATE_STRIDE;
+                        if (candidates[co + 10] !== 0) candidates[co + 10] += salt;
+                    }
+                }
+                sub_pair++;
+            }
+        }
+
+        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_manifold_contacts(candidates, cand_count, CANDIDATE_STRIDE, MAX_KEPT, 9);
+
+        // ── 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"). Same-fid prev
+        //           contacts are disambiguated by NEAREST previous witness:
+        //           a fid identifies the FEATURE (e.g. a triangle), not the
+        //           contact point — the box/capsule-triangle paths emit up
+        //           to 4 contacts sharing one triangle's fid, and the
+        //           reducer reorders them frame to frame, so first-match
+        //           would shuffle warm-start impulses between a face's own
+        //           contact points. (redetect_pair_geometry documents and
+        //           fixes the same failure for the per-substep path.)
+        //   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) {
+                // Gated by FID_MATCH_MAX_D2: a fid recomputed half a metre
+                // away (teleport, fid collision) must not inherit impulses.
+                let best_d2 = FID_MATCH_MAX_D2;
+                for (let j = 0; j < prev_count; j++) {
+                    if (prev_claimed[j]) continue;
+                    if (prev_snapshot[j * 7] !== cand_fid) 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; }
+                }
+            }
+            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],
+                candidates[off + 11], candidates[off + 12]
+            );
+            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);
+            }
+        }
+    }
+}
+
+/**
+ * Re-detect contact GEOMETRY for one existing manifold slot at the bodies'
+ * current poses, updating the witness points / normal / depth of the slot's
+ * existing contacts in place. Does NOT change the contact count, the
+ * feature ids, or the accumulated impulses — it only refreshes geometry.
+ *
+ * This is the per-substep concave path (TGS): for a contact pair involving a
+ * concave body, the contact *feature* (which triangle is deepest, and its
+ * normal) genuinely changes as the body rocks, so the solver's cheap analytic
+ * refresh — which freezes the feature for the whole outer step — pumps energy
+ * in. Re-running the narrowphase geometry each substep gives a fresh,
+ * correct normal so the body settles instead of rocking. Convex pairs keep
+ * the analytic refresh and never call this (their feature is stable).
+ *
+ * Matching is by feature id (stable per-triangle for the decomposition path),
+ * so a contact's geometry tracks the same triangle across substeps. A contact
+ * whose triangle isn't found this substep keeps its previous geometry (a rare
+ * transient; the once-per-frame {@link narrowphase_step} re-establishes the
+ * contact set next outer step). Count never changes here, so the solver's
+ * per-contact scratch (sized once at prepare) stays aligned.
+ *
+ * @param {ManifoldStore} manifolds
+ * @param {number} slot
+ * @param {Array<{collider: Collider, transform: Transform}>} list_a
+ * @param {Array<{collider: Collider, transform: Transform}>} list_b
+ */
+export function redetect_pair_geometry(manifolds, slot, list_a, list_b) {
+    if (list_a === undefined || list_b === undefined) return;
+    const la_len = list_a.length;
+    const lb_len = list_b.length;
+    if (la_len === 0 || lb_len === 0) return;
+
+    const count = manifolds.contact_count(slot);
+    if (count === 0) return;
+
+    let cc = 0;
+    let sub_pair = 0;
+    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];
+            const before = cc;
+            cc = dispatch_pair(cc, ea.collider, ea.transform, eb.collider, eb.transform);
+            // Stored fids are sub-pair-salted (see narrowphase_step's dispatch
+            // loop) — salt the redetected candidates identically or no fid
+            // would ever match for a compound body's non-first sub-pair.
+            if (sub_pair !== 0) {
+                const salt = sub_pair * FID_PAIR_SALT;
+                for (let c = before; c < cc; c++) {
+                    const co = c * CANDIDATE_STRIDE;
+                    if (candidates[co + 10] !== 0) candidates[co + 10] += salt;
+                }
+            }
+            sub_pair++;
+        }
+    }
+    if (cc === 0) return; // nothing re-detected this substep — keep frozen geometry
+
+    const data = manifolds.data_buffer;
+    const slot_off = manifolds.slot_data_offset(slot);
+
+    // Match each existing contact to a DISTINCT fresh candidate. feature_id
+    // identifies the TRIANGLE, not the contact point — the box/capsule-triangle
+    // paths emit several contacts for one triangle, all sharing that triangle's
+    // single fid (a flat box-on-heightmap cell yields fids like [6,6,6,7]). A
+    // plain first-match-by-fid therefore maps every same-fid existing contact
+    // onto the SAME candidate, collapsing the manifold to duplicate witness
+    // points → a degenerate support polygon the solver can't damp (the
+    // box-on-heightmap rattle). So: gate by fid, disambiguate same-fid
+    // candidates by NEAREST previous witness (world-A) position, and claim each
+    // candidate so no two existing contacts take the same one. For the common
+    // unique-fid case (sphere/mesh: one contact per triangle) this picks that
+    // single candidate exactly once — identical to the old behaviour.
+    for (let k = 0; k < cc; k++) redetect_claimed[k] = 0;
+
+    for (let j = 0; j < count; j++) {
+        const off = slot_off + j * CONTACT_STRIDE;
+        const fid = data[off + 13];
+        if (fid === 0) continue; // no feature info to match on
+
+        // Previous witness (world-A) of this existing contact — the anchor we
+        // disambiguate same-fid candidates against.
+        const pax = data[off];
+        const pay = data[off + 1];
+        const paz = data[off + 2];
+
+        let best_k = -1;
+        let best_d2 = Infinity;
+        for (let k = 0; k < cc; k++) {
+            if (redetect_claimed[k] === 1) continue;
+            const co = k * CANDIDATE_STRIDE;
+            if (candidates[co + 10] !== fid) continue;
+            const dx = candidates[co]     - pax;
+            const dy = candidates[co + 1] - pay;
+            const dz = candidates[co + 2] - paz;
+            const d2 = dx * dx + dy * dy + dz * dz;
+            if (d2 < best_d2) {
+                best_d2 = d2;
+                best_k = k;
+            }
+        }
+
+        // Position fallback (mirrors narrowphase_step's match-and-merge). A
+        // single triangle's clipped contact count is NOT stable across sub-mm
+        // pose changes — a box straddling a cell seam can have one triangle
+        // yield 4 points one substep and 3 the next — so an existing contact can
+        // outnumber this substep's same-fid candidates. Freezing its stale
+        // witness then duplicates a sibling contact's point, leaving a
+        // degenerate (sub-dimensional) manifold. Instead, claim the nearest
+        // unclaimed candidate of ANY fid: every contact keeps a DISTINCT live
+        // witness. The fid label is left intact and re-resolved by the next
+        // once-per-step narrowphase. (At a fixed pose the same-fid match always
+        // succeeds, so this never fires for the depth-equality guards or the
+        // one-contact-per-triangle sphere/mesh paths.)
+        if (best_k === -1) {
+            for (let k = 0; k < cc; k++) {
+                if (redetect_claimed[k] === 1) continue;
+                const co = k * CANDIDATE_STRIDE;
+                const dx = candidates[co]     - pax;
+                const dy = candidates[co + 1] - pay;
+                const dz = candidates[co + 2] - paz;
+                const d2 = dx * dx + dy * dy + dz * dz;
+                if (d2 < best_d2) {
+                    best_d2 = d2;
+                    best_k = k;
+                }
+            }
+        }
+
+        if (best_k === -1) continue; // no unclaimed candidate at all this substep — keep frozen geometry
+
+        redetect_claimed[best_k] = 1;
+        const co = best_k * CANDIDATE_STRIDE;
+        // Overwrite geometry only: witnesses, normal, depth. (Count, feature
+        // ids and accumulated impulses are intentionally left untouched — see
+        // the function contract.)
+        data[off]     = candidates[co];
+        data[off + 1] = candidates[co + 1];
+        data[off + 2] = candidates[co + 2];
+        data[off + 3] = candidates[co + 3];
+        data[off + 4] = candidates[co + 4];
+        data[off + 5] = candidates[co + 5];
+        data[off + 6] = candidates[co + 6];
+        data[off + 7] = candidates[co + 7];
+        data[off + 8] = candidates[co + 8];
+        data[off + 9] = candidates[co + 9];
+    }
+}