@woosh/meep-engine 2.165.5 → 2.165.7

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

@@ -1,568 +1,632 @@
-import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
-import { v3_centroid_v3_buffer } from "../../../core/geom/vec3/v3_centroid_v3_buffer.js";
-import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
-import { v3_length } from "../../../core/geom/vec3/v3_length.js";
-import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
-import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
-
-/**
- * Multi-point contact manifold between two convex polytopes with **polygon
- * faces**, computed entirely from the current poses — no cross-frame state, so
- * it preserves reset-and-resimulate (rollback) determinism.
- *
- * A piece is described by:
- *   - `vertices`     : Float32Array, flat (x,y,z) per vertex, local frame
- *   - `face_offsets` : Uint32Array length F+1, CSR offsets into `face_loops`
- *   - `face_loops`   : Uint32Array, each face's vertex indices, ordered CCW so
- *                      the face normal (from its first three loop verts) points
- *                      outward.
- * A triangle-faced piece (a tetrahedron) is just the special case where every
- * face loop has length 3; a merged/box piece has quads or larger polygons.
- * Handling polygon faces directly is what lets a flat face produce a full
- * face-on-face patch instead of mismatched triangle slivers.
- *
- * The separating axis comes from SAT (the structure mirrors Bullet's
- * `clipHullAgainstHull`, which clips around a `separatingNormal`). A GJK+EPA
- * axis source was prototyped — Bullet sources the normal from EITHER SAT OR
- * `btGjkPairDetector`, the source being orthogonal to the clip — but this
- * engine's EPA returns a non-minimal, non-scaling axis for polytopes (a 0.05 m
- * overlap reports ~0.8 m depth), so clipping around it produces a garbage
- * manifold. SAT is exact and, for the low-poly hulls authored as collision
- * proxies and the small pieces of a decomposed mesh, cheap. See memory:
- * feedback_epa_unreliable_polytopes.
- *
- * Algorithm (general form of {@link box_box_manifold}):
- *   1. SAT over every face normal of A, every face normal of B, and every
- *      edge(A)×edge(B) cross finds the minimum-translation axis `n` (B→A).
- *   2. Face-axis winner ⇒ reference face = the polygon that owns the axis;
- *      incident face = the polygon on the other piece most antiparallel to the
- *      reference outward normal. Clip the incident polygon against the reference
- *      polygon's side planes (3-D Sutherland–Hodgman) and keep penetrating points.
- *   3. Edge-axis winner ⇒ a single deepest support-pair contact.
- *   4. Reduce survivors to ≤ {@link MAX_CONTACTS} (deepest + spread).
- *
- * Output layout (matches {@link box_box_manifold}):
- *   out[0..2]            : world normal (B→A)
- *   out[3]               : contact count (0 .. MAX_CONTACTS)
- *   out[4 + k*7 + 0..2]  : world contact on A's surface
- *   out[4 + k*7 + 3..5]  : world contact on B's surface
- *   out[4 + k*7 + 6]     : penetration depth (positive)
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-const MAX_CONTACTS = 4;
-const CONTACT_STRIDE = 7;
-export const CONVEX_CONVEX_OUT_LENGTH = 4 + MAX_CONTACTS * CONTACT_STRIDE;
-
-const INITIAL_V = 256; // initial world-vertex scratch capacity (verts per piece/hull)
-const MAX_POLY = 64;   // polygon verts during clipping
-
-const TIE_REL = 0.02;
-const TIE_ABS = 1e-5;
-const PARALLEL_EPS = 1e-9;
-
-// --- scratch ----------------------------------------------------------------
-// World-vertex buffers. `let` + grow-on-demand: a convex MESH routed as a single
-// hull (get_mesh_convex_hull) can have far more than the initial capacity of
-// surface vertices (a subdivided icosphere is hundreds). Without the grow, the
-// excess writes were silently dropped and SAT/clip read NaN past the end,
-// computing a truncated (wrong) manifold against part of the hull.
-let wvA = new Float64Array(INITIAL_V * 3);
-let wvB = new Float64Array(INITIAL_V * 3);
-// Clipping scratch — `let` + grow-on-demand like wvA/wvB: a coplanar-merged
-// face (e.g. a tessellated cylinder cap routed through get_mesh_convex_hull)
-// can be wider than MAX_POLY, and each side-plane clip can add one more
-// vertex. emit_face_manifold sizes these to inc_len + ref_len before use.
-let poly_in = new Float64Array(MAX_POLY * 3);
-let poly_out = new Float64Array(MAX_POLY * 3);
-let cand = new Float64Array(MAX_POLY * 4);
-const cenA = new Float64Array(3);
-const cenB = new Float64Array(3);
-const tmp_n = new Float64Array(3);
-
-const sat = { overlap: Infinity, nx: 0, ny: 0, nz: 0, kind: -1, face: -1 };
-
-// --- per-call geometry refs (single-thread re-entrancy, like the scratch) ---
-let g_foA, g_flA, g_foB, g_flB, g_fA, g_fB, g_nA, g_nB;
-
-function set_geom(A, B) {
-    g_nA = A.vertices.length / 3; g_nB = B.vertices.length / 3;
-    g_foA = A.face_offsets; g_flA = A.face_loops; g_fA = g_foA.length - 1;
-    g_foB = B.face_offsets; g_flB = B.face_loops; g_fB = g_foB.length - 1;
-    // Grow the world-vertex scratch to fit, so large hulls aren't truncated.
-    if (wvA.length < g_nA * 3) wvA = new Float64Array(g_nA * 3);
-    if (wvB.length < g_nB * 3) wvB = new Float64Array(g_nB * 3);
-}
-
-function load_world(out, verts, n, p, q) {
-    for (let i = 0; i < n; i++) {
-        v3_quaternion_apply(out, i * 3, verts[i * 3], verts[i * 3 + 1], verts[i * 3 + 2], q.x, q.y, q.z, q.w);
-        out[i * 3] += p.x; out[i * 3 + 1] += p.y; out[i * 3 + 2] += p.z;
-    }
-}
-
-/**
- * Outward normal of a polygon face (Newell's method over the whole loop, world).
- * Robust against collinear consecutive vertices, unlike a first-three cross.
- */
-function face_normal(out, wv, loops, off, end) {
-    let nx = 0, ny = 0, nz = 0;
-    for (let i = off; i < end; i++) {
-        const p = loops[i] * 3, q = loops[i + 1 < end ? i + 1 : off] * 3;
-        nx += (wv[p + 1] - wv[q + 1]) * (wv[p + 2] + wv[q + 2]);
-        ny += (wv[p + 2] - wv[q + 2]) * (wv[p] + wv[q]);
-        nz += (wv[p] - wv[q]) * (wv[p + 1] + wv[q + 1]);
-    }
-    out[0] = nx; out[1] = ny; out[2] = nz;
-}
-
-/**
- * Unique edges of a hull piece as vertex-index pairs `(v0, v1)`, flat in a
- * Uint32Array, cached on the (immutable) piece as `__sat_edges` — built on
- * first use, like `get_mesh_convex_hull`'s cache (D4).
- *
- * The SAT edge×edge loop used to enumerate every FACE-LOOP edge of A
- * against every face-loop edge of B; an interior edge of a closed hull
- * borders exactly two faces, so each unique edge pair was tested up to 4×,
- * each test paying a full O(nA + nB) interval projection. Deduplication
- * cuts the dominant quartic term ~4×.
- *
- * Order and orientation are FIRST-OCCURRENCE (the face-loop scan order):
- * the sequence of first tests per unique pair — which is what resolves
- * near-tie axes under the deadband — is exactly the sequence the full scan
- * produced, and the duplicate tests in between were no-ops (an identical
- * axis can never beat itself past the hysteresis band; a reversed-edge
- * duplicate only flips the axis sign, which the centroid-keyed sign
- * canonicalisation in test_axis erases). Results are bit-identical.
- *
- * @param {{face_offsets: Uint32Array, face_loops: Uint32Array, __sat_edges: (Uint32Array|undefined)}} shape
- * @returns {Uint32Array}
- */
-function get_sat_edges(shape) {
-    let edges = shape.__sat_edges;
-    if (edges !== undefined) return edges;
-
-    const fo = shape.face_offsets;
-    const fl = shape.face_loops;
-    const nf = fo.length - 1;
-    const seen = new Set();
-    const list = [];
-    for (let f = 0; f < nf; f++) {
-        const s = fo[f];
-        const l = fo[f + 1] - s;
-        for (let i = 0; i < l; i++) {
-            const v0 = fl[s + i];
-            const v1 = fl[s + (i + 1) % l];
-            // Canonical undirected key; hull vertex indices stay far below
-            // 2^26, so min·2^26 + max is exact in a double.
-            const key = v0 < v1 ? v0 * 67108864 + v1 : v1 * 67108864 + v0;
-            if (seen.has(key)) continue;
-            seen.add(key);
-            list.push(v0, v1);
-        }
-    }
-    edges = Uint32Array.from(list);
-    shape.__sat_edges = edges;
-    return edges;
-}
-
-/** SAT axis test; true if the axis SEPARATES the pieces. */
-function test_axis(ux, uy, uz, nA, nB, kind, face) {
-    const len2 = ux * ux + uy * uy + uz * uz;
-    if (len2 < PARALLEL_EPS) return false;
-    const inv = 1 / Math.sqrt(len2);
-    ux *= inv; uy *= inv; uz *= inv;
-
-    let minA = Infinity, maxA = -Infinity;
-    for (let i = 0; i < nA; i++) {
-        const d = v3_dot(ux, uy, uz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
-        if (d < minA) minA = d; if (d > maxA) maxA = d;
-    }
-    let minB = Infinity, maxB = -Infinity;
-    for (let i = 0; i < nB; i++) {
-        const d = v3_dot(ux, uy, uz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
-        if (d < minB) minB = d; if (d > maxB) maxB = d;
-    }
-    if (maxA < minB || maxB < minA) return true;
-
-    const overlap = Math.min(maxA, maxB) - Math.max(minA, minB);
-    if (sat.kind === -1 || overlap < sat.overlap - (sat.overlap * TIE_REL + TIE_ABS)) {
-        sat.overlap = overlap;
-        const dcx = cenA[0] - cenB[0], dcy = cenA[1] - cenB[1], dcz = cenA[2] - cenB[2];
-        const sign = v3_dot(ux, uy, uz, dcx, dcy, dcz) >= 0 ? 1 : -1;
-        sat.nx = ux * sign; sat.ny = uy * sign; sat.nz = uz * sign;
-        sat.kind = kind; sat.face = face;
-    }
-    return false;
-}
-
-/**
- * SAT entry point — finds the minimum-translation axis itself, then clips.
- * For the SMALL convex pieces of a decomposed mesh.
- *
- * @param {Float64Array|number[]} out length ≥ CONVEX_CONVEX_OUT_LENGTH
- * @param {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array}} A
- * @param {{x,y,z}} posA @param {{x,y,z,w}} rotA
- * @param {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array}} B
- * @param {{x,y,z}} posB @param {{x,y,z,w}} rotB
- * @returns {boolean}
- */
-export function convex_convex_manifold(out, A, posA, rotA, B, posB, rotB) {
-    set_geom(A, B);
-
-    load_world(wvA, A.vertices, g_nA, posA, rotA);
-    load_world(wvB, B.vertices, g_nB, posB, rotB);
-    v3_centroid_v3_buffer(cenA, 0, wvA, 0, g_nA);
-    v3_centroid_v3_buffer(cenB, 0, wvB, 0, g_nB);
-
-    sat.kind = -1; sat.overlap = Infinity;
-
-    // A face normals.
-    for (let f = 0; f < g_fA; f++) {
-        face_normal(tmp_n, wvA, g_flA, g_foA[f], g_foA[f + 1]);
-        if (test_axis(tmp_n[0], tmp_n[1], tmp_n[2], g_nA, g_nB, 0, f)) return false;
-    }
-    // B face normals.
-    for (let f = 0; f < g_fB; f++) {
-        face_normal(tmp_n, wvB, g_flB, g_foB[f], g_foB[f + 1]);
-        if (test_axis(tmp_n[0], tmp_n[1], tmp_n[2], g_nA, g_nB, 1, f)) return false;
-    }
-    // Edge × edge crosses, over each hull's UNIQUE edges (cached per shape —
-    // see get_sat_edges; the face-loop scan retested every interior edge pair
-    // up to 4×, each paying a full interval projection).
-    const edgesA = get_sat_edges(A);
-    const edgesB = get_sat_edges(B);
-    const neA = edgesA.length;
-    const neB = edgesB.length;
-    for (let ia = 0; ia < neA; ia += 2) {
-        const a0 = edgesA[ia] * 3, a1 = edgesA[ia + 1] * 3;
-        const eax = wvA[a1] - wvA[a0], eay = wvA[a1 + 1] - wvA[a0 + 1], eaz = wvA[a1 + 2] - wvA[a0 + 2];
-        for (let ib = 0; ib < neB; ib += 2) {
-            const b0 = edgesB[ib] * 3, b1 = edgesB[ib + 1] * 3;
-            const ebx = wvB[b1] - wvB[b0], eby = wvB[b1 + 1] - wvB[b0 + 1], ebz = wvB[b1 + 2] - wvB[b0 + 2];
-            const cx = eay * ebz - eaz * eby, cy = eaz * ebx - eax * ebz, cz = eax * eby - eay * ebx;
-            if (test_axis(cx, cy, cz, g_nA, g_nB, 2, -1)) return false;
-        }
-    }
-
-    if (sat.kind === -1) return false;
-
-    const nx = sat.nx, ny = sat.ny, nz = sat.nz;
-    out[0] = nx; out[1] = ny; out[2] = nz;
-
-    // Edge-cross winner: single contact at the winning edges' closest points.
-    if (sat.kind === 2) {
-        emit_edge_pair_contact(out, nx, ny, nz, sat.overlap);
-        return true;
-    }
-
-    // Face winner: reference / incident polygon clipping.
-    emit_face_manifold(out, sat.kind === 0, sat.face, nx, ny, nz);
-    return true;
-}
-
-/**
- * Clip-only entry point — the caller supplies the separating axis `n` (B→A,
- * unit) from a robust GJK+EPA query ({@link gjk_epa_penetration}); we only build
- * the multi-point manifold. This is Bullet's `clipHullAgainstHull(sepNormal,…)`
- * with the normal sourced from GJK rather than SAT. Used for LARGE convex
- * polytopes (authored hulls, a convex mesh as one piece) where SAT's O(Fa·Fb +
- * Ea·Eb) edge term is prohibitive but GJK+EPA is O(support queries). Always
- * emits ≥ 1 contact (the caller already established penetration): if the face
- * clip empties (a vertex/edge feature) it falls back to the deepest support-pair.
- *
- * @param {Float64Array|number[]} out length ≥ CONVEX_CONVEX_OUT_LENGTH
- * @param {{vertices,face_offsets,face_loops}} A @param {{x,y,z}} posA @param {{x,y,z,w}} rotA
- * @param {{vertices,face_offsets,face_loops}} B @param {{x,y,z}} posB @param {{x,y,z,w}} rotB
- * @param {number} nx @param {number} ny @param {number} nz  unit axis as
- *   returned by {@link gjk_epa_penetration} (A→B); this function re-orients it
- *   against the geometric centres before use, so either sign convention works
- * @returns {boolean} always true
- */
-export function convex_hull_clip(out, A, posA, rotA, B, posB, rotB, nx, ny, nz) {
-    set_geom(A, B);
-    load_world(wvA, A.vertices, g_nA, posA, rotA);
-    load_world(wvB, B.vertices, g_nB, posB, rotB);
-
-    // Orient the axis B→A using the shapes' GEOMETRIC centres (centroids of the
-    // world vertices), the same robust reference the SAT path uses. A body-frame
-    // guard (transform positions) degenerates when the two origins nearly
-    // coincide — e.g. a tet resting base-to-base on another, both transforms at
-    // the contact plane — leaving the normal mis-oriented and the stack tunnels.
-    v3_centroid_v3_buffer(cenA, 0, wvA, 0, g_nA);
-    v3_centroid_v3_buffer(cenB, 0, wvB, 0, g_nB);
-    if (nx * (cenA[0] - cenB[0]) + ny * (cenA[1] - cenB[1]) + nz * (cenA[2] - cenB[2]) < 0) {
-        nx = -nx; ny = -ny; nz = -nz;
-    }
-    out[0] = nx; out[1] = ny; out[2] = nz;
-
-    // Reference face = the face (A or B) whose outward normal is most aligned
-    // with the axis pointing toward the other body. A's contact face points
-    // toward B (along −n); B's toward A (along +n). The flatter (better-aligned)
-    // one is the reference. Mirrors Bullet's "face most opposing the normal",
-    // made symmetric across A and B.
-    let bestA = -Infinity, faceA = 0;
-    for (let f = 0; f < g_fA; f++) {
-        face_normal(tmp_n, wvA, g_flA, g_foA[f], g_foA[f + 1]);
-        const l = v3_length(tmp_n[0], tmp_n[1], tmp_n[2]) || 1;
-        const d = v3_dot(tmp_n[0], tmp_n[1], tmp_n[2], -nx, -ny, -nz) / l;
-        if (d > bestA) { bestA = d; faceA = f; }
-    }
-    let bestB = -Infinity, faceB = 0;
-    for (let f = 0; f < g_fB; f++) {
-        face_normal(tmp_n, wvB, g_flB, g_foB[f], g_foB[f + 1]);
-        const l = v3_length(tmp_n[0], tmp_n[1], tmp_n[2]) || 1;
-        const d = v3_dot(tmp_n[0], tmp_n[1], tmp_n[2], nx, ny, nz) / l;
-        if (d > bestB) { bestB = d; faceB = f; }
-    }
-
-    const ref_is_A = bestA >= bestB;
-    emit_face_manifold(out, ref_is_A, ref_is_A ? faceA : faceB, nx, ny, nz);
-
-    if ((out[3] | 0) === 0) {
-        const overlap = projection_overlap(nx, ny, nz);
-        emit_single_contact(out, nx, ny, nz, overlap > 0 ? overlap : 0);
-    }
-    return true;
-}
-
-/** Overlap of the two pieces' projections onto axis `n` (B→A); A is on the +n side. */
-function projection_overlap(nx, ny, nz) {
-    let minA = Infinity, maxB = -Infinity;
-    for (let i = 0; i < g_nA; i++) {
-        const d = v3_dot(nx, ny, nz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
-        if (d < minA) minA = d;
-    }
-    for (let i = 0; i < g_nB; i++) {
-        const d = v3_dot(nx, ny, nz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
-        if (d > maxB) maxB = d;
-    }
-    return maxB - minA;
-}
-
-/** Single deepest support-pair contact along axis `n` (B→A). */
-function emit_single_contact(out, nx, ny, nz, depth) {
-    let sa = -Infinity, ai = 0;
-    for (let i = 0; i < g_nA; i++) {
-        const d = -v3_dot(nx, ny, nz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
-        if (d > sa) { sa = d; ai = i; }
-    }
-    let sb = -Infinity, bi = 0;
-    for (let i = 0; i < g_nB; i++) {
-        const d = v3_dot(nx, ny, nz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
-        if (d > sb) { sb = d; bi = i; }
-    }
-    out[3] = 1;
-    out[4] = wvA[ai * 3]; out[5] = wvA[ai * 3 + 1]; out[6] = wvA[ai * 3 + 2];
-    out[7] = wvB[bi * 3]; out[8] = wvB[bi * 3 + 1]; out[9] = wvB[bi * 3 + 2];
-    out[10] = depth;
-}
-
-const scratch_st = new Float64Array(2);
-const scratch_edge = new Int32Array(4); // [a0, a1] then [b0, b1] vertex indices
-
-/**
- * Find a piece's SUPPORTING EDGE along direction d: the face-loop edge that
- * maximises the SMALLER of its two endpoint projections. For an edge-cross
- * SAT winner the true contact edge lies perpendicular to the axis, so both
- * its endpoints project to the common maximum and its min-endpoint
- * projection beats every other edge's. (Recording the SAT loop's winning
- * pair instead does NOT work: parallel edge pairs alias one axis with equal
- * overlap, and the first-tested pair is usually not the touching one.)
- *
- * @param {Float64Array} wv world vertices
- * @param {Uint32Array} fo face offsets
- * @param {Uint32Array} fl face loops
- * @param {number} fcount face count
- * @param {number} dx @param {number} dy @param {number} dz
- * @param {Int32Array} out_pair 2 slots written at `pair_off`
- * @param {number} pair_off
- */
-function find_support_edge(wv, fo, fl, fcount, dx, dy, dz, out_pair, pair_off) {
-    let best = -Infinity;
-    for (let f = 0; f < fcount; f++) {
-        const start = fo[f], len = fo[f + 1] - start;
-        for (let i = 0; i < len; i++) {
-            const v0 = fl[start + i] * 3;
-            const v1 = fl[start + (i + 1) % len] * 3;
-            const d0 = wv[v0] * dx + wv[v0 + 1] * dy + wv[v0 + 2] * dz;
-            const d1 = wv[v1] * dx + wv[v1 + 1] * dy + wv[v1 + 2] * dz;
-            const m = d0 < d1 ? d0 : d1;
-            if (m > best) {
-                best = m;
-                out_pair[pair_off] = v0;
-                out_pair[pair_off + 1] = v1;
-            }
-        }
-    }
-}
-
-/**
- * Single contact for an edge-cross SAT winner, at the CLOSEST POINTS of the
- * two supporting edges. A support-VERTEX pick is ambiguous here: every point
- * of the contact edge projects identically onto the cross axis, so the
- * argmax lands on an arbitrary endpoint and hands the solver a lever arm up
- * to half an edge length off - resting boxes twist.
- */
-function emit_edge_pair_contact(out, nx, ny, nz, depth) {
-    // A's supporting edge faces the contact (toward B): extreme along -n;
-    // B's faces A: extreme along +n. (n is B -> A.)
-    find_support_edge(wvA, g_foA, g_flA, g_fA, -nx, -ny, -nz, scratch_edge, 0);
-    find_support_edge(wvB, g_foB, g_flB, g_fB, nx, ny, nz, scratch_edge, 2);
-    const a0 = scratch_edge[0], a1 = scratch_edge[1];
-    const b0 = scratch_edge[2], b1 = scratch_edge[3];
-
-    line3_compute_segment_segment_closest_points(
-        scratch_st,
-        wvA[a0], wvA[a0 + 1], wvA[a0 + 2],
-        wvA[a1], wvA[a1 + 1], wvA[a1 + 2],
-        wvB[b0], wvB[b0 + 1], wvB[b0 + 2],
-        wvB[b1], wvB[b1 + 1], wvB[b1 + 2]
-    );
-    const s = scratch_st[0];
-    const t = scratch_st[1];
-    out[3] = 1;
-    out[4] = wvA[a0]     + (wvA[a1]     - wvA[a0])     * s;
-    out[5] = wvA[a0 + 1] + (wvA[a1 + 1] - wvA[a0 + 1]) * s;
-    out[6] = wvA[a0 + 2] + (wvA[a1 + 2] - wvA[a0 + 2]) * s;
-    out[7] = wvB[b0]     + (wvB[b1]     - wvB[b0])     * t;
-    out[8] = wvB[b0 + 1] + (wvB[b1 + 1] - wvB[b0 + 1]) * t;
-    out[9] = wvB[b0 + 2] + (wvB[b1 + 2] - wvB[b0 + 2]) * t;
-    out[10] = depth;
-}
-
-/**
- * Reference/incident polygon clipping given the reference face. Writes the
- * manifold (count + contacts) into `out`; leaves out[0..2] (the normal) as set
- * by the caller. Shared by both the SAT and GJK+EPA entry points.
- *
- * @param {boolean} ref_is_A  reference face belongs to A (else B)
- * @param {number} ref_face   reference face index within its piece
- * @param {number} nx @param {number} ny @param {number} nz  axis (B→A), unit
- */
-function emit_face_manifold(out, ref_is_A, ref_face, nx, ny, nz) {
-    const ref_wv = ref_is_A ? wvA : wvB;
-    const ref_fo = ref_is_A ? g_foA : g_foB;
-    const ref_fl = ref_is_A ? g_flA : g_flB;
-    const inc_wv = ref_is_A ? wvB : wvA;
-    const inc_fo = ref_is_A ? g_foB : g_foA;
-    const inc_fl = ref_is_A ? g_flB : g_flA;
-    const inc_fcount = ref_is_A ? g_fB : g_fA;
-
-    // Reference outward normal points ref → incident: −n if ref is A, +n if ref is B.
-    const rmx = ref_is_A ? -nx : nx, rmy = ref_is_A ? -ny : ny, rmz = ref_is_A ? -nz : nz;
-
-    const ref_s = ref_fo[ref_face], ref_len = ref_fo[ref_face + 1] - ref_s;
-    const r0 = ref_fl[ref_s] * 3;
-    const r0x = ref_wv[r0], r0y = ref_wv[r0 + 1], r0z = ref_wv[r0 + 2];
-
-    // Incident face = the polygon on the other piece most antiparallel to rm.
-    let inc_face = 0, most_anti = Infinity;
-    for (let f = 0; f < inc_fcount; f++) {
-        face_normal(tmp_n, inc_wv, inc_fl, inc_fo[f], inc_fo[f + 1]);
-        const l = v3_length(tmp_n[0], tmp_n[1], tmp_n[2]) || 1;
-        const dot = v3_dot(tmp_n[0], tmp_n[1], tmp_n[2], rmx, rmy, rmz) / l;
-        if (dot < most_anti) { most_anti = dot; inc_face = f; }
-    }
-
-    // Incident polygon (world). Worst-case working size: the incident loop
-    // plus one extra vertex per reference side-plane clip (a convex polygon
-    // clipped by a half-space gains at most one vertex) — grow the shared
-    // scratch to fit, so wide coplanar-merged faces aren't truncated into
-    // OOB reads (NaN / stale contacts).
-    const inc_s = inc_fo[inc_face], inc_len = inc_fo[inc_face + 1] - inc_s;
-    const max_poly_verts = inc_len + ref_len;
-    if (poly_in.length < max_poly_verts * 3) {
-        poly_in = new Float64Array(max_poly_verts * 3);
-        poly_out = new Float64Array(max_poly_verts * 3);
-        cand = new Float64Array(max_poly_verts * 4);
-    }
-    let n_poly = inc_len;
-    for (let i = 0; i < inc_len; i++) {
-        const vi = inc_fl[inc_s + i] * 3;
-        poly_in[i * 3] = inc_wv[vi]; poly_in[i * 3 + 1] = inc_wv[vi + 1]; poly_in[i * 3 + 2] = inc_wv[vi + 2];
-    }
-
-    // Reference polygon centroid (orients side planes inward).
-    let rcx = 0, rcy = 0, rcz = 0;
-    for (let i = 0; i < ref_len; i++) {
-        const vi = ref_fl[ref_s + i] * 3;
-        rcx += ref_wv[vi]; rcy += ref_wv[vi + 1]; rcz += ref_wv[vi + 2];
-    }
-    rcx /= ref_len; rcy /= ref_len; rcz /= ref_len;
-
-    // Clip the incident polygon against each reference-face side plane.
-    let src = poly_in, dst = poly_out;
-    for (let e = 0; e < ref_len && n_poly > 0; e++) {
-        const va = ref_fl[ref_s + e] * 3, vb = ref_fl[ref_s + (e + 1) % ref_len] * 3;
-        const edx = ref_wv[vb] - ref_wv[va], edy = ref_wv[vb + 1] - ref_wv[va + 1], edz = ref_wv[vb + 2] - ref_wv[va + 2];
-        let sx = edy * rmz - edz * rmy, sy = edz * rmx - edx * rmz, sz = edx * rmy - edy * rmx;
-        const pax = ref_wv[va], pay = ref_wv[va + 1], paz = ref_wv[va + 2];
-        if ((rcx - pax) * sx + (rcy - pay) * sy + (rcz - paz) * sz > 0) { sx = -sx; sy = -sy; sz = -sz; }
-        n_poly = clip_poly(src, n_poly, dst, sx, sy, sz, pax, pay, paz);
-        const t = src; src = dst; dst = t;
-    }
-    if (n_poly === 0) { out[3] = 0; return; }
-
-    let nc = 0;
-    for (let i = 0; i < n_poly; i++) {
-        const px = src[i * 3], py = src[i * 3 + 1], pz = src[i * 3 + 2];
-        const sep = (px - r0x) * rmx + (py - r0y) * rmy + (pz - r0z) * rmz;
-        const depth = -sep;
-        if (depth < 0) continue;
-        cand[nc * 4] = px; cand[nc * 4 + 1] = py; cand[nc * 4 + 2] = pz; cand[nc * 4 + 3] = depth;
-        nc++;
-    }
-    if (nc === 0) { out[3] = 0; return; }
-
-    const kept = reduce_manifold_contacts(cand, nc, 4, MAX_CONTACTS, 3);
-    out[3] = kept;
-    for (let k = 0; k < kept; k++) {
-        const px = cand[k * 4], py = cand[k * 4 + 1], pz = cand[k * 4 + 2], depth = cand[k * 4 + 3];
-        const d2p = (px - r0x) * rmx + (py - r0y) * rmy + (pz - r0z) * rmz;
-        const rpx = px - rmx * d2p, rpy = py - rmy * d2p, rpz = pz - rmz * d2p;
-        const base = 4 + k * CONTACT_STRIDE;
-        if (ref_is_A) {
-            out[base] = rpx; out[base + 1] = rpy; out[base + 2] = rpz;
-            out[base + 3] = px; out[base + 4] = py; out[base + 5] = pz;
-        } else {
-            out[base] = px; out[base + 1] = py; out[base + 2] = pz;
-            out[base + 3] = rpx; out[base + 4] = rpy; out[base + 5] = rpz;
-        }
-        out[base + 6] = depth;
-    }
-}
-
-/**
- * Sutherland–Hodgman: keep polygon points where (P − a)·s ≤ 0, with crossings.
- * Capacity-guarded on BOTH emit branches: `m` must never pass `dst`'s capacity
- * or the dropped OOB writes leave stale/NaN points that later reads consume
- * (the buffers are pre-sized to inc_len + ref_len, so the guard is a backstop
- * for degenerate input, not the normal bound).
- */
-function clip_poly(src, n, dst, sx, sy, sz, ax, ay, az) {
-    const cap = (dst.length / 3) | 0;
-    let m = 0;
-    for (let i = 0; i < n && m < cap; i++) {
-        const j = (i + 1) % n;
-        const px = src[i * 3], py = src[i * 3 + 1], pz = src[i * 3 + 2];
-        const qx = src[j * 3], qy = src[j * 3 + 1], qz = src[j * 3 + 2];
-        const dp = v3_dot(px - ax, py - ay, pz - az, sx, sy, sz);
-        const dq = v3_dot(qx - ax, qy - ay, qz - az, sx, sy, sz);
-        const p_in = dp <= 0, q_in = dq <= 0;
-        if (p_in) { dst[m * 3] = px; dst[m * 3 + 1] = py; dst[m * 3 + 2] = pz; m++; }
-        if (p_in !== q_in && m < cap) {
-            const t = dp / (dp - dq);
-            dst[m * 3] = px + (qx - px) * t;
-            dst[m * 3 + 1] = py + (qy - py) * t;
-            dst[m * 3 + 2] = pz + (qz - pz) * t;
-            m++;
-        }
-    }
-    return m;
-}
-
-// Contact reduction (deepest + farthest-point spread) is shared with
-// box_box_manifold via reduce_manifold_contacts (stride 4).
+import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
+import { v3_centroid_v3_buffer } from "../../../core/geom/vec3/v3_centroid_v3_buffer.js";
+import { v3_dot } from "../../../core/geom/vec3/v3_dot.js";
+import { v3_length } from "../../../core/geom/vec3/v3_length.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
+
+/**
+ * Multi-point contact manifold between two convex polytopes with **polygon
+ * faces**, computed entirely from the current poses — no cross-frame state, so
+ * it preserves reset-and-resimulate (rollback) determinism.
+ *
+ * A piece is described by:
+ *   - `vertices`     : Float32Array, flat (x,y,z) per vertex, local frame
+ *   - `face_offsets` : Uint32Array length F+1, CSR offsets into `face_loops`
+ *   - `face_loops`   : Uint32Array, each face's vertex indices, ordered CCW so
+ *                      the face normal (from its first three loop verts) points
+ *                      outward.
+ * A triangle-faced piece (a tetrahedron) is just the special case where every
+ * face loop has length 3; a merged/box piece has quads or larger polygons.
+ * Handling polygon faces directly is what lets a flat face produce a full
+ * face-on-face patch instead of mismatched triangle slivers.
+ *
+ * The separating axis comes from SAT (the structure mirrors Bullet's
+ * `clipHullAgainstHull`, which clips around a `separatingNormal`). A GJK+EPA
+ * axis source was prototyped — Bullet sources the normal from EITHER SAT OR
+ * `btGjkPairDetector`, the source being orthogonal to the clip — but this
+ * engine's EPA returns a non-minimal, non-scaling axis for polytopes (a 0.05 m
+ * overlap reports ~0.8 m depth), so clipping around it produces a garbage
+ * manifold. SAT is exact and, for the low-poly hulls authored as collision
+ * proxies and the small pieces of a decomposed mesh, cheap. See memory:
+ * feedback_epa_unreliable_polytopes.
+ *
+ * Algorithm (general form of {@link box_box_manifold}):
+ *   1. SAT over every face normal of A, every face normal of B, and every
+ *      edge(A)×edge(B) cross finds the minimum-translation axis `n` (B→A).
+ *   2. Face-axis winner ⇒ reference face = the polygon that owns the axis;
+ *      incident face = the polygon on the other piece most antiparallel to the
+ *      reference outward normal. Clip the incident polygon against the reference
+ *      polygon's side planes (3-D Sutherland–Hodgman) and keep penetrating points.
+ *   3. Edge-axis winner ⇒ a single deepest support-pair contact.
+ *   4. Reduce survivors to ≤ {@link MAX_CONTACTS} (deepest + spread).
+ *
+ * Output layout (matches {@link box_box_manifold}):
+ *   out[0..2]            : world normal (B→A)
+ *   out[3]               : contact count (0 .. MAX_CONTACTS)
+ *   out[4 + k*7 + 0..2]  : world contact on A's surface
+ *   out[4 + k*7 + 3..5]  : world contact on B's surface
+ *   out[4 + k*7 + 6]     : penetration depth (positive)
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const MAX_CONTACTS = 4;
+const CONTACT_STRIDE = 7;
+export const CONVEX_CONVEX_OUT_LENGTH = 4 + MAX_CONTACTS * CONTACT_STRIDE;
+
+const INITIAL_V = 256; // initial world-vertex scratch capacity (verts per piece/hull)
+const MAX_POLY = 64;   // polygon verts during clipping
+
+const TIE_REL = 0.02;
+const TIE_ABS = 1e-5;
+// Scale-INVARIANT degeneracy cutoff for a candidate SAT axis. The incoming axis is unnormalised
+// (a Newell face normal of magnitude 2·area, or an edge×edge cross of magnitude |ea||eb|sinθ), so
+// its raw length is scale-dependent and must NOT be thresholded against an absolute constant —
+// doing so silently drops small faces and near-parallel short edges. Instead we threshold the
+// dimensionless ratio len² / ref², where ref² is the square of the axis's own characteristic
+// magnitude: for an edge cross that ratio is sin²θ (true parallelism), for a face it is a shape
+// "fatness" factor that only vanishes for a genuinely degenerate (collinear) loop. Matches the
+// unit-axis sin²θ cutoff box_box_manifold already uses (PARALLEL_EPS_SQR).
+const PARALLEL_EPS_REL = 1e-8;
+
+// --- scratch ----------------------------------------------------------------
+// World-vertex buffers. `let` + grow-on-demand: a convex MESH routed as a single
+// hull (get_mesh_convex_hull) can have far more than the initial capacity of
+// surface vertices (a subdivided icosphere is hundreds). Without the grow, the
+// excess writes were silently dropped and SAT/clip read NaN past the end,
+// computing a truncated (wrong) manifold against part of the hull.
+let wvA = new Float64Array(INITIAL_V * 3);
+let wvB = new Float64Array(INITIAL_V * 3);
+// Clipping scratch — `let` + grow-on-demand like wvA/wvB: a coplanar-merged
+// face (e.g. a tessellated cylinder cap routed through get_mesh_convex_hull)
+// can be wider than MAX_POLY, and each side-plane clip can add one more
+// vertex. emit_face_manifold sizes these to inc_len + ref_len before use.
+let poly_in = new Float64Array(MAX_POLY * 3);
+let poly_out = new Float64Array(MAX_POLY * 3);
+let cand = new Float64Array(MAX_POLY * 4);
+const cenA = new Float64Array(3);
+const cenB = new Float64Array(3);
+const tmp_n = new Float64Array(3);
+
+const sat = { overlap: Infinity, nx: 0, ny: 0, nz: 0, kind: -1 };
+
+/** Result of {@link select_reference_face}. */
+const ref_sel = { face: 0, score: 0 };
+
+// --- per-call geometry refs (single-thread re-entrancy, like the scratch) ---
+let g_foA, g_flA, g_foB, g_flB, g_fA, g_fB, g_nA, g_nB;
+
+function set_geom(A, B) {
+    g_nA = A.vertices.length / 3; g_nB = B.vertices.length / 3;
+    g_foA = A.face_offsets; g_flA = A.face_loops; g_fA = g_foA.length - 1;
+    g_foB = B.face_offsets; g_flB = B.face_loops; g_fB = g_foB.length - 1;
+    // Grow the world-vertex scratch to fit, so large hulls aren't truncated.
+    if (wvA.length < g_nA * 3) wvA = new Float64Array(g_nA * 3);
+    if (wvB.length < g_nB * 3) wvB = new Float64Array(g_nB * 3);
+}
+
+function load_world(out, verts, n, p, q) {
+    for (let i = 0; i < n; i++) {
+        v3_quaternion_apply(out, i * 3, verts[i * 3], verts[i * 3 + 1], verts[i * 3 + 2], q.x, q.y, q.z, q.w);
+        out[i * 3] += p.x; out[i * 3 + 1] += p.y; out[i * 3 + 2] += p.z;
+    }
+}
+
+/**
+ * Outward normal of a polygon face (Newell's method over the whole loop, world).
+ * Robust against collinear consecutive vertices, unlike a first-three cross.
+ *
+ * @returns {number} the loop's summed squared edge length Σ|eᵢ|² — a scale²-matched
+ * characteristic magnitude for the face (|normal| = 2·area ∝ this), so `|normal|² / result²`
+ * is the dimensionless "fatness" used by {@link test_axis} to reject only degenerate loops.
+ */
+function face_normal(out, wv, loops, off, end) {
+    let nx = 0, ny = 0, nz = 0, s2 = 0;
+    for (let i = off; i < end; i++) {
+        const p = loops[i] * 3, q = loops[i + 1 < end ? i + 1 : off] * 3;
+        nx += (wv[p + 1] - wv[q + 1]) * (wv[p + 2] + wv[q + 2]);
+        ny += (wv[p + 2] - wv[q + 2]) * (wv[p] + wv[q]);
+        nz += (wv[p] - wv[q]) * (wv[p + 1] + wv[q + 1]);
+        const ex = wv[p] - wv[q], ey = wv[p + 1] - wv[q + 1], ez = wv[p + 2] - wv[q + 2];
+        s2 += ex * ex + ey * ey + ez * ez;
+    }
+    out[0] = nx; out[1] = ny; out[2] = nz;
+    return s2;
+}
+
+/**
+ * Unique edges of a hull piece as vertex-index pairs `(v0, v1)`, flat in a
+ * Uint32Array, cached on the (immutable) piece as `__sat_edges` — built on
+ * first use, like `get_mesh_convex_hull`'s cache (D4).
+ *
+ * The SAT edge×edge loop used to enumerate every FACE-LOOP edge of A
+ * against every face-loop edge of B; an interior edge of a closed hull
+ * borders exactly two faces, so each unique edge pair was tested up to 4×,
+ * each test paying a full O(nA + nB) interval projection. Deduplication
+ * cuts the dominant quartic term ~4×.
+ *
+ * Order and orientation are FIRST-OCCURRENCE (the face-loop scan order):
+ * the sequence of first tests per unique pair — which is what resolves
+ * near-tie axes under the deadband — is exactly the sequence the full scan
+ * produced, and the duplicate tests in between were no-ops (an identical
+ * axis can never beat itself past the hysteresis band; a reversed-edge
+ * duplicate only flips the axis sign, which the centroid-keyed sign
+ * canonicalisation in test_axis erases). Results are bit-identical.
+ *
+ * @param {{face_offsets: Uint32Array, face_loops: Uint32Array, __sat_edges: (Uint32Array|undefined)}} shape
+ * @returns {Uint32Array}
+ */
+function get_sat_edges(shape) {
+    let edges = shape.__sat_edges;
+    if (edges !== undefined) return edges;
+
+    const fo = shape.face_offsets;
+    const fl = shape.face_loops;
+    const nf = fo.length - 1;
+    const seen = new Set();
+    const list = [];
+    for (let f = 0; f < nf; f++) {
+        const s = fo[f];
+        const l = fo[f + 1] - s;
+        for (let i = 0; i < l; i++) {
+            const v0 = fl[s + i];
+            const v1 = fl[s + (i + 1) % l];
+            // Canonical undirected key; hull vertex indices stay far below
+            // 2^26, so min·2^26 + max is exact in a double.
+            const key = v0 < v1 ? v0 * 67108864 + v1 : v1 * 67108864 + v0;
+            if (seen.has(key)) continue;
+            seen.add(key);
+            list.push(v0, v1);
+        }
+    }
+    edges = Uint32Array.from(list);
+    shape.__sat_edges = edges;
+    return edges;
+}
+
+/**
+ * Select the reference face of one piece: the face whose outward normal is most aligned with
+ * `(mx,my,mz)`, the axis pointing toward the other body (−n for A, +n for B). Writes {@link ref_sel}.
+ *
+ * A face's SAT axis is direction-agnostic — a closed hull carries both `u` and `−u` as face normals
+ * and both project to an identical overlap — so the face index that WON the SAT scan is whichever of
+ * an antipodal pair happened to be enumerated first, which is unrelated to the side the other body is
+ * on. The reference face must therefore be re-derived from the (sign-canonicalised) normal rather than
+ * taken from the SAT scan. Mirrors Bullet's "face most opposing the normal", made symmetric across A and B.
+ *
+ * @param {boolean} is_A select within piece A, otherwise piece B
+ * @param {number} mx @param {number} my @param {number} mz  axis toward the other body
+ */
+function select_reference_face(is_A, mx, my, mz) {
+    const nf = is_A ? g_fA : g_fB;
+    const wv = is_A ? wvA : wvB;
+    const fl = is_A ? g_flA : g_flB;
+    const fo = is_A ? g_foA : g_foB;
+
+    let best = -Infinity;
+    let best_face = 0;
+
+    for (let f = 0; f < nf; f++) {
+        face_normal(tmp_n, wv, fl, fo[f], fo[f + 1]);
+
+        const l = v3_length(tmp_n[0], tmp_n[1], tmp_n[2]) || 1;
+        const d = v3_dot(tmp_n[0], tmp_n[1], tmp_n[2], mx, my, mz) / l;
+
+        if (d > best) {
+            best = d;
+            best_face = f;
+        }
+    }
+
+    ref_sel.face = best_face;
+    ref_sel.score = best;
+}
+
+/**
+ * SAT axis test; true if the axis SEPARATES the pieces.
+ * @param {number} ref2 square of the axis's characteristic magnitude (Σ|edge|² for a face,
+ *   |ea|²·|eb|² for an edge cross); the axis is rejected as degenerate when `len2 / ref2` — a
+ *   scale-invariant fatness / sin²θ — falls below {@link PARALLEL_EPS_REL}. See PARALLEL_EPS_REL.
+ */
+function test_axis(ux, uy, uz, nA, nB, kind, ref2) {
+    const len2 = ux * ux + uy * uy + uz * uz;
+    if (len2 < PARALLEL_EPS_REL * ref2) return false;
+    const inv = 1 / Math.sqrt(len2);
+    ux *= inv; uy *= inv; uz *= inv;
+
+    let minA = Infinity, maxA = -Infinity;
+    for (let i = 0; i < nA; i++) {
+        const d = v3_dot(ux, uy, uz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
+        if (d < minA) minA = d; if (d > maxA) maxA = d;
+    }
+    let minB = Infinity, maxB = -Infinity;
+    for (let i = 0; i < nB; i++) {
+        const d = v3_dot(ux, uy, uz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
+        if (d < minB) minB = d; if (d > maxB) maxB = d;
+    }
+    if (maxA < minB || maxB < minA) return true;
+
+    const overlap = Math.min(maxA, maxB) - Math.max(minA, minB);
+    if (sat.kind === -1 || overlap < sat.overlap - (sat.overlap * TIE_REL + TIE_ABS)) {
+        sat.overlap = overlap;
+        const dcx = cenA[0] - cenB[0], dcy = cenA[1] - cenB[1], dcz = cenA[2] - cenB[2];
+        const sign = v3_dot(ux, uy, uz, dcx, dcy, dcz) >= 0 ? 1 : -1;
+        sat.nx = ux * sign; sat.ny = uy * sign; sat.nz = uz * sign;
+        sat.kind = kind;
+    }
+    return false;
+}
+
+/**
+ * SAT entry point — finds the minimum-translation axis itself, then clips.
+ * For the SMALL convex pieces of a decomposed mesh.
+ *
+ * @param {Float64Array|number[]} out length ≥ CONVEX_CONVEX_OUT_LENGTH
+ * @param {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array}} A
+ * @param {{x,y,z}} posA @param {{x,y,z,w}} rotA
+ * @param {{vertices:Float32Array, face_offsets:Uint32Array, face_loops:Uint32Array}} B
+ * @param {{x,y,z}} posB @param {{x,y,z,w}} rotB
+ * @returns {boolean}
+ */
+export function convex_convex_manifold(out, A, posA, rotA, B, posB, rotB) {
+    set_geom(A, B);
+
+    load_world(wvA, A.vertices, g_nA, posA, rotA);
+    load_world(wvB, B.vertices, g_nB, posB, rotB);
+    v3_centroid_v3_buffer(cenA, 0, wvA, 0, g_nA);
+    v3_centroid_v3_buffer(cenB, 0, wvB, 0, g_nB);
+
+    sat.kind = -1; sat.overlap = Infinity;
+
+    // A face normals.
+    for (let f = 0; f < g_fA; f++) {
+        const s2 = face_normal(tmp_n, wvA, g_flA, g_foA[f], g_foA[f + 1]);
+        if (test_axis(tmp_n[0], tmp_n[1], tmp_n[2], g_nA, g_nB, 0, s2 * s2)) return false;
+    }
+    // B face normals.
+    for (let f = 0; f < g_fB; f++) {
+        const s2 = face_normal(tmp_n, wvB, g_flB, g_foB[f], g_foB[f + 1]);
+        if (test_axis(tmp_n[0], tmp_n[1], tmp_n[2], g_nA, g_nB, 1, s2 * s2)) return false;
+    }
+    // Edge × edge crosses, over each hull's UNIQUE edges (cached per shape —
+    // see get_sat_edges; the face-loop scan retested every interior edge pair
+    // up to 4×, each paying a full interval projection).
+    const edgesA = get_sat_edges(A);
+    const edgesB = get_sat_edges(B);
+    const neA = edgesA.length;
+    const neB = edgesB.length;
+    for (let ia = 0; ia < neA; ia += 2) {
+        const a0 = edgesA[ia] * 3, a1 = edgesA[ia + 1] * 3;
+        const eax = wvA[a1] - wvA[a0], eay = wvA[a1 + 1] - wvA[a0 + 1], eaz = wvA[a1 + 2] - wvA[a0 + 2];
+        const ea2 = eax * eax + eay * eay + eaz * eaz;
+        for (let ib = 0; ib < neB; ib += 2) {
+            const b0 = edgesB[ib] * 3, b1 = edgesB[ib + 1] * 3;
+            const ebx = wvB[b1] - wvB[b0], eby = wvB[b1 + 1] - wvB[b0 + 1], ebz = wvB[b1 + 2] - wvB[b0 + 2];
+            const cx = eay * ebz - eaz * eby, cy = eaz * ebx - eax * ebz, cz = eax * eby - eay * ebx;
+            // ref² = |ea|²·|eb|² makes len²/ref² = sin²θ, a true (scale-invariant) parallelism test.
+            if (test_axis(cx, cy, cz, g_nA, g_nB, 2, ea2 * (ebx * ebx + eby * eby + ebz * ebz))) return false;
+        }
+    }
+
+    if (sat.kind === -1) return false;
+
+    const nx = sat.nx, ny = sat.ny, nz = sat.nz;
+    out[0] = nx; out[1] = ny; out[2] = nz;
+
+    // Edge-cross winner: single contact at the winning edges' closest points.
+    if (sat.kind === 2) {
+        emit_edge_pair_contact(out, nx, ny, nz, sat.overlap);
+        return true;
+    }
+
+    // Face winner: reference / incident polygon clipping. SAT decided WHICH piece owns the
+    // reference face, but not which of its two antipodal faces — see select_reference_face.
+    const ref_is_A = sat.kind === 0;
+    select_reference_face(
+        ref_is_A,
+        ref_is_A ? -nx : nx,
+        ref_is_A ? -ny : ny,
+        ref_is_A ? -nz : nz
+    );
+
+    emit_face_manifold(out, ref_is_A, ref_sel.face, nx, ny, nz);
+    return true;
+}
+
+/**
+ * Clip-only entry point — the caller supplies the separating axis `n` (B→A,
+ * unit) from a robust GJK+EPA query ({@link gjk_epa_penetration}); we only build
+ * the multi-point manifold. This is Bullet's `clipHullAgainstHull(sepNormal,…)`
+ * with the normal sourced from GJK rather than SAT. Used for LARGE convex
+ * polytopes (authored hulls, a convex mesh as one piece) where SAT's O(Fa·Fb +
+ * Ea·Eb) edge term is prohibitive but GJK+EPA is O(support queries). Always
+ * emits ≥ 1 contact (the caller already established penetration): if the face
+ * clip empties (a vertex/edge feature) it falls back to the deepest support-pair.
+ *
+ * @param {Float64Array|number[]} out length ≥ CONVEX_CONVEX_OUT_LENGTH
+ * @param {{vertices,face_offsets,face_loops}} A @param {{x,y,z}} posA @param {{x,y,z,w}} rotA
+ * @param {{vertices,face_offsets,face_loops}} B @param {{x,y,z}} posB @param {{x,y,z,w}} rotB
+ * @param {number} nx @param {number} ny @param {number} nz  unit axis as
+ *   returned by {@link gjk_epa_penetration} (A→B); this function re-orients it
+ *   against the geometric centres before use, so either sign convention works
+ * @returns {boolean} always true
+ */
+export function convex_hull_clip(out, A, posA, rotA, B, posB, rotB, nx, ny, nz) {
+    set_geom(A, B);
+    load_world(wvA, A.vertices, g_nA, posA, rotA);
+    load_world(wvB, B.vertices, g_nB, posB, rotB);
+
+    // Orient the axis B→A using the shapes' GEOMETRIC centres (centroids of the
+    // world vertices), the same robust reference the SAT path uses. A body-frame
+    // guard (transform positions) degenerates when the two origins nearly
+    // coincide — e.g. a tet resting base-to-base on another, both transforms at
+    // the contact plane — leaving the normal mis-oriented and the stack tunnels.
+    v3_centroid_v3_buffer(cenA, 0, wvA, 0, g_nA);
+    v3_centroid_v3_buffer(cenB, 0, wvB, 0, g_nB);
+    if (nx * (cenA[0] - cenB[0]) + ny * (cenA[1] - cenB[1]) + nz * (cenA[2] - cenB[2]) < 0) {
+        nx = -nx; ny = -ny; nz = -nz;
+    }
+    out[0] = nx; out[1] = ny; out[2] = nz;
+
+    // Reference face = the face (A or B) whose outward normal is most aligned
+    // with the axis pointing toward the other body. A's contact face points
+    // toward B (along −n); B's toward A (along +n). The flatter (better-aligned)
+    // one is the reference.
+    select_reference_face(true, -nx, -ny, -nz);
+    const bestA = ref_sel.score;
+    const faceA = ref_sel.face;
+
+    select_reference_face(false, nx, ny, nz);
+    const bestB = ref_sel.score;
+    const faceB = ref_sel.face;
+
+    const ref_is_A = bestA >= bestB;
+    emit_face_manifold(out, ref_is_A, ref_is_A ? faceA : faceB, nx, ny, nz);
+
+    if ((out[3] | 0) === 0) {
+        const overlap = projection_overlap(nx, ny, nz);
+        emit_single_contact(out, nx, ny, nz, overlap > 0 ? overlap : 0);
+    }
+    return true;
+}
+
+/** Overlap of the two pieces' projections onto axis `n` (B→A); A is on the +n side. */
+function projection_overlap(nx, ny, nz) {
+    let minA = Infinity, maxB = -Infinity;
+    for (let i = 0; i < g_nA; i++) {
+        const d = v3_dot(nx, ny, nz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
+        if (d < minA) minA = d;
+    }
+    for (let i = 0; i < g_nB; i++) {
+        const d = v3_dot(nx, ny, nz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
+        if (d > maxB) maxB = d;
+    }
+    return maxB - minA;
+}
+
+/** Single deepest support-pair contact along axis `n` (B→A). */
+function emit_single_contact(out, nx, ny, nz, depth) {
+    let sa = -Infinity, ai = 0;
+    for (let i = 0; i < g_nA; i++) {
+        const d = -v3_dot(nx, ny, nz, wvA[i * 3], wvA[i * 3 + 1], wvA[i * 3 + 2]);
+        if (d > sa) { sa = d; ai = i; }
+    }
+    let sb = -Infinity, bi = 0;
+    for (let i = 0; i < g_nB; i++) {
+        const d = v3_dot(nx, ny, nz, wvB[i * 3], wvB[i * 3 + 1], wvB[i * 3 + 2]);
+        if (d > sb) { sb = d; bi = i; }
+    }
+    out[3] = 1;
+    out[4] = wvA[ai * 3]; out[5] = wvA[ai * 3 + 1]; out[6] = wvA[ai * 3 + 2];
+    out[7] = wvB[bi * 3]; out[8] = wvB[bi * 3 + 1]; out[9] = wvB[bi * 3 + 2];
+    out[10] = depth;
+}
+
+const scratch_st = new Float64Array(2);
+const scratch_edge = new Int32Array(4); // [a0, a1] then [b0, b1] vertex indices
+
+/**
+ * Find a piece's SUPPORTING EDGE along direction d: the face-loop edge that
+ * maximises the SMALLER of its two endpoint projections. For an edge-cross
+ * SAT winner the true contact edge lies perpendicular to the axis, so both
+ * its endpoints project to the common maximum and its min-endpoint
+ * projection beats every other edge's. (Recording the SAT loop's winning
+ * pair instead does NOT work: parallel edge pairs alias one axis with equal
+ * overlap, and the first-tested pair is usually not the touching one.)
+ *
+ * @param {Float64Array} wv world vertices
+ * @param {Uint32Array} fo face offsets
+ * @param {Uint32Array} fl face loops
+ * @param {number} fcount face count
+ * @param {number} dx @param {number} dy @param {number} dz
+ * @param {Int32Array} out_pair 2 slots written at `pair_off`
+ * @param {number} pair_off
+ */
+function find_support_edge(wv, fo, fl, fcount, dx, dy, dz, out_pair, pair_off) {
+    let best = -Infinity;
+    for (let f = 0; f < fcount; f++) {
+        const start = fo[f], len = fo[f + 1] - start;
+        for (let i = 0; i < len; i++) {
+            const v0 = fl[start + i] * 3;
+            const v1 = fl[start + (i + 1) % len] * 3;
+            const d0 = wv[v0] * dx + wv[v0 + 1] * dy + wv[v0 + 2] * dz;
+            const d1 = wv[v1] * dx + wv[v1 + 1] * dy + wv[v1 + 2] * dz;
+            const m = d0 < d1 ? d0 : d1;
+            if (m > best) {
+                best = m;
+                out_pair[pair_off] = v0;
+                out_pair[pair_off + 1] = v1;
+            }
+        }
+    }
+}
+
+/**
+ * Single contact for an edge-cross SAT winner, at the CLOSEST POINTS of the
+ * two supporting edges. A support-VERTEX pick is ambiguous here: every point
+ * of the contact edge projects identically onto the cross axis, so the
+ * argmax lands on an arbitrary endpoint and hands the solver a lever arm up
+ * to half an edge length off - resting boxes twist.
+ */
+function emit_edge_pair_contact(out, nx, ny, nz, depth) {
+    // A's supporting edge faces the contact (toward B): extreme along -n;
+    // B's faces A: extreme along +n. (n is B -> A.)
+    find_support_edge(wvA, g_foA, g_flA, g_fA, -nx, -ny, -nz, scratch_edge, 0);
+    find_support_edge(wvB, g_foB, g_flB, g_fB, nx, ny, nz, scratch_edge, 2);
+    const a0 = scratch_edge[0], a1 = scratch_edge[1];
+    const b0 = scratch_edge[2], b1 = scratch_edge[3];
+
+    line3_compute_segment_segment_closest_points(
+        scratch_st,
+        wvA[a0], wvA[a0 + 1], wvA[a0 + 2],
+        wvA[a1], wvA[a1 + 1], wvA[a1 + 2],
+        wvB[b0], wvB[b0 + 1], wvB[b0 + 2],
+        wvB[b1], wvB[b1 + 1], wvB[b1 + 2]
+    );
+    const s = scratch_st[0];
+    const t = scratch_st[1];
+    out[3] = 1;
+    out[4] = wvA[a0]     + (wvA[a1]     - wvA[a0])     * s;
+    out[5] = wvA[a0 + 1] + (wvA[a1 + 1] - wvA[a0 + 1]) * s;
+    out[6] = wvA[a0 + 2] + (wvA[a1 + 2] - wvA[a0 + 2]) * s;
+    out[7] = wvB[b0]     + (wvB[b1]     - wvB[b0])     * t;
+    out[8] = wvB[b0 + 1] + (wvB[b1 + 1] - wvB[b0 + 1]) * t;
+    out[9] = wvB[b0 + 2] + (wvB[b1 + 2] - wvB[b0 + 2]) * t;
+    out[10] = depth;
+}
+
+/**
+ * Reference/incident polygon clipping given the reference face. Writes the
+ * manifold (count + contacts) into `out`; leaves out[0..2] (the normal) as set
+ * by the caller. Shared by both the SAT and GJK+EPA entry points.
+ *
+ * @param {boolean} ref_is_A  reference face belongs to A (else B)
+ * @param {number} ref_face   reference face index within its piece
+ * @param {number} nx @param {number} ny @param {number} nz  axis (B→A), unit
+ */
+function emit_face_manifold(out, ref_is_A, ref_face, nx, ny, nz) {
+    const ref_wv = ref_is_A ? wvA : wvB;
+    const ref_fo = ref_is_A ? g_foA : g_foB;
+    const ref_fl = ref_is_A ? g_flA : g_flB;
+    const inc_wv = ref_is_A ? wvB : wvA;
+    const inc_fo = ref_is_A ? g_foB : g_foA;
+    const inc_fl = ref_is_A ? g_flB : g_flA;
+    const inc_fcount = ref_is_A ? g_fB : g_fA;
+
+    // Reference outward normal points ref → incident: −n if ref is A, +n if ref is B.
+    const rmx = ref_is_A ? -nx : nx, rmy = ref_is_A ? -ny : ny, rmz = ref_is_A ? -nz : nz;
+
+    const ref_s = ref_fo[ref_face], ref_len = ref_fo[ref_face + 1] - ref_s;
+    const r0 = ref_fl[ref_s] * 3;
+    const r0x = ref_wv[r0], r0y = ref_wv[r0 + 1], r0z = ref_wv[r0 + 2];
+
+    // Incident face = the polygon on the other piece most antiparallel to rm.
+    let inc_face = 0, most_anti = Infinity;
+    for (let f = 0; f < inc_fcount; f++) {
+        face_normal(tmp_n, inc_wv, inc_fl, inc_fo[f], inc_fo[f + 1]);
+        const l = v3_length(tmp_n[0], tmp_n[1], tmp_n[2]) || 1;
+        const dot = v3_dot(tmp_n[0], tmp_n[1], tmp_n[2], rmx, rmy, rmz) / l;
+        if (dot < most_anti) { most_anti = dot; inc_face = f; }
+    }
+
+    // Incident polygon (world). Worst-case working size: the incident loop
+    // plus one extra vertex per reference side-plane clip (a convex polygon
+    // clipped by a half-space gains at most one vertex) — grow the shared
+    // scratch to fit, so wide coplanar-merged faces aren't truncated into
+    // OOB reads (NaN / stale contacts).
+    const inc_s = inc_fo[inc_face], inc_len = inc_fo[inc_face + 1] - inc_s;
+    const max_poly_verts = inc_len + ref_len;
+    if (poly_in.length < max_poly_verts * 3) {
+        poly_in = new Float64Array(max_poly_verts * 3);
+        poly_out = new Float64Array(max_poly_verts * 3);
+        cand = new Float64Array(max_poly_verts * 4);
+    }
+    let n_poly = inc_len;
+    for (let i = 0; i < inc_len; i++) {
+        const vi = inc_fl[inc_s + i] * 3;
+        poly_in[i * 3] = inc_wv[vi]; poly_in[i * 3 + 1] = inc_wv[vi + 1]; poly_in[i * 3 + 2] = inc_wv[vi + 2];
+    }
+
+    // Reference polygon centroid (orients side planes inward).
+    let rcx = 0, rcy = 0, rcz = 0;
+    for (let i = 0; i < ref_len; i++) {
+        const vi = ref_fl[ref_s + i] * 3;
+        rcx += ref_wv[vi]; rcy += ref_wv[vi + 1]; rcz += ref_wv[vi + 2];
+    }
+    rcx /= ref_len; rcy /= ref_len; rcz /= ref_len;
+
+    // Clip the incident polygon against each reference-face side plane.
+    let src = poly_in, dst = poly_out;
+    for (let e = 0; e < ref_len && n_poly > 0; e++) {
+        const va = ref_fl[ref_s + e] * 3, vb = ref_fl[ref_s + (e + 1) % ref_len] * 3;
+        const edx = ref_wv[vb] - ref_wv[va], edy = ref_wv[vb + 1] - ref_wv[va + 1], edz = ref_wv[vb + 2] - ref_wv[va + 2];
+        let sx = edy * rmz - edz * rmy, sy = edz * rmx - edx * rmz, sz = edx * rmy - edy * rmx;
+        const pax = ref_wv[va], pay = ref_wv[va + 1], paz = ref_wv[va + 2];
+        if ((rcx - pax) * sx + (rcy - pay) * sy + (rcz - paz) * sz > 0) { sx = -sx; sy = -sy; sz = -sz; }
+        n_poly = clip_poly(src, n_poly, dst, sx, sy, sz, pax, pay, paz);
+        const t = src; src = dst; dst = t;
+    }
+    if (n_poly === 0) { out[3] = 0; return; }
+
+    let nc = 0;
+    for (let i = 0; i < n_poly; i++) {
+        const px = src[i * 3], py = src[i * 3 + 1], pz = src[i * 3 + 2];
+        const sep = (px - r0x) * rmx + (py - r0y) * rmy + (pz - r0z) * rmz;
+        const depth = -sep;
+        if (depth < 0) continue;
+        cand[nc * 4] = px; cand[nc * 4 + 1] = py; cand[nc * 4 + 2] = pz; cand[nc * 4 + 3] = depth;
+        nc++;
+    }
+    if (nc === 0) { out[3] = 0; return; }
+
+    const kept = reduce_manifold_contacts(cand, nc, 4, MAX_CONTACTS, 3);
+    out[3] = kept;
+    for (let k = 0; k < kept; k++) {
+        const px = cand[k * 4], py = cand[k * 4 + 1], pz = cand[k * 4 + 2], depth = cand[k * 4 + 3];
+        const d2p = (px - r0x) * rmx + (py - r0y) * rmy + (pz - r0z) * rmz;
+        const rpx = px - rmx * d2p, rpy = py - rmy * d2p, rpz = pz - rmz * d2p;
+        const base = 4 + k * CONTACT_STRIDE;
+        if (ref_is_A) {
+            out[base] = rpx; out[base + 1] = rpy; out[base + 2] = rpz;
+            out[base + 3] = px; out[base + 4] = py; out[base + 5] = pz;
+        } else {
+            out[base] = px; out[base + 1] = py; out[base + 2] = pz;
+            out[base + 3] = rpx; out[base + 4] = rpy; out[base + 5] = rpz;
+        }
+        out[base + 6] = depth;
+    }
+}
+
+/**
+ * Sutherland–Hodgman: keep polygon points where (P − a)·s ≤ 0, with crossings.
+ * Capacity-guarded on BOTH emit branches: `m` must never pass `dst`'s capacity
+ * or the dropped OOB writes leave stale/NaN points that later reads consume
+ * (the buffers are pre-sized to inc_len + ref_len, so the guard is a backstop
+ * for degenerate input, not the normal bound).
+ */
+function clip_poly(src, n, dst, sx, sy, sz, ax, ay, az) {
+    const cap = (dst.length / 3) | 0;
+    let m = 0;
+    for (let i = 0; i < n && m < cap; i++) {
+        const j = (i + 1) % n;
+        const px = src[i * 3], py = src[i * 3 + 1], pz = src[i * 3 + 2];
+        const qx = src[j * 3], qy = src[j * 3 + 1], qz = src[j * 3 + 2];
+        const dp = v3_dot(px - ax, py - ay, pz - az, sx, sy, sz);
+        const dq = v3_dot(qx - ax, qy - ay, qz - az, sx, sy, sz);
+        const p_in = dp <= 0, q_in = dq <= 0;
+        if (p_in) { dst[m * 3] = px; dst[m * 3 + 1] = py; dst[m * 3 + 2] = pz; m++; }
+        if (p_in !== q_in && m < cap) {
+            const t = dp / (dp - dq);
+            dst[m * 3] = px + (qx - px) * t;
+            dst[m * 3 + 1] = py + (qy - py) * t;
+            dst[m * 3 + 2] = pz + (qz - pz) * t;
+            m++;
+        }
+    }
+    return m;
+}
+
+// Contact reduction (deepest + farthest-point spread) is shared with
+// box_box_manifold via reduce_manifold_contacts (stride 4).