@series-inc/rundot-syncplay 5.23.0-beta.7 → 5.23.0

package/dist/physics3d-solver.js

@@ -0,0 +1,1346 @@
+/**
+ * Deterministic rigid-body solver core (geometry half): SAT + face-clipping
+ * manifolds for boxes, closed-form manifolds for sphere/capsule pairs,
+ * one-sided triangle contacts for dynamic-shape-vs-static-mesh, and compound
+ * decomposition. The velocity/position solver, contact cache matching, islands
+ * and sleeping live alongside in this module (see solveRigidStep).
+ *
+ * Numeric regime: unquantized solver math via the shared kernel; every constant
+ * here is load-bearing (each was earned by a failure mode in the validated
+ * spike) — do not "simplify" them without re-running the stack/tumble/
+ * determinism scenarios.
+ */
+import { addVec3, clampNumber as clamp, crossVec3, dotVec3, integrateQuat, mulMat3Vec, quatMultiply, quatToMat3, rotatePointByQuat, rotatePointByQuatInverse, scaleVec3, solverSqrt, subVec3, worldInvInertia, } from './physics3d-shared.js';
+const ZERO = { x: 0, y: 0, z: 0 };
+/** Expand a compound body into primitive sub-bodies in world space. */
+function primitiveViews(body) {
+    const shape = body.shape;
+    if (shape.kind === 'compound') {
+        return shape.children.map((child) => ({
+            index: body.index,
+            p: addVec3(body.p, rotatePointByQuat(body.q, child.offset)),
+            q: quatMultiply(body.q, child.q),
+            shape: child.shape,
+        }));
+    }
+    /* istanbul ignore next -- mesh bodies are routed to meshManifold before primitiveViews is ever reached; this branch only satisfies the SolverShape union. */
+    if (shape.kind === 'mesh') {
+        return [];
+    }
+    return [{ index: body.index, p: body.p, q: body.q, shape }];
+}
+// ---------- public entry ----------
+/**
+ * Generate a contact manifold between two bodies. Normal points from `a` to `b`.
+ * Returns undefined when the shapes are separated. `speculativeMargin` keeps
+ * contact points with `penetration >= -speculativeMargin` (CCD, Task 6);
+ * default 0 keeps only real (penetrating) points.
+ */
+function asPrimitive(shape) {
+    /* istanbul ignore next -- callers guard compound, and mesh bodies are routed to meshManifold first; type guard only. */
+    if (shape.kind === 'compound' || shape.kind === 'mesh') {
+        throw new Error('asPrimitive requires a primitive shape');
+    }
+    return shape;
+}
+export function generateManifold(a, b, speculativeMargin = 0) {
+    // mesh is one-sided static geometry; the other shape's primitives collide
+    // against each triangle.
+    if (a.shape.kind === 'mesh' || b.shape.kind === 'mesh') {
+        return meshManifold(a, b, speculativeMargin);
+    }
+    if (a.shape.kind !== 'compound' && b.shape.kind !== 'compound') {
+        // single primitive pair — no view arrays, no union accumulation
+        const sub = collidePrimitives({ index: a.index, p: a.p, q: a.q, shape: asPrimitive(a.shape) }, { index: b.index, p: b.p, q: b.q, shape: asPrimitive(b.shape) }, a.p, b.p, speculativeMargin, 0);
+        if (sub === undefined) {
+            return undefined;
+        }
+        return { a: a.index, b: b.index, normal: sub.normal, points: reducePoints([...sub.points]) };
+    }
+    const primsA = primitiveViews(a);
+    const primsB = primitiveViews(b);
+    const points = [];
+    let normalAccum;
+    let deepest = -Infinity;
+    let childOffset = 0;
+    for (const pa of primsA) {
+        for (const pb of primsB) {
+            const sub = collidePrimitives(pa, pb, a.p, b.p, speculativeMargin, childOffset);
+            childOffset += 64;
+            if (sub === undefined) {
+                continue;
+            }
+            for (const point of sub.points) {
+                points.push(point);
+            }
+            // adopt the normal from the deepest sub-manifold for a stable union normal
+            const subDeepest = Math.max(...sub.points.map((point) => point.penetration));
+            if (subDeepest > deepest) {
+                deepest = subDeepest;
+                normalAccum = sub.normal;
+            }
+        }
+    }
+    if (points.length === 0 || normalAccum === undefined) {
+        return undefined;
+    }
+    const reduced = reducePoints(points);
+    return { a: a.index, b: b.index, normal: normalAccum, points: reduced };
+}
+function reducePoints(points) {
+    if (points.length <= 4) {
+        return [...points].sort((l, r) => l.feature - r.feature);
+    }
+    const byDepth = [...points].sort((l, r) => r.penetration - l.penetration || l.feature - r.feature);
+    const kept = byDepth.slice(0, 4);
+    return kept.sort((l, r) => l.feature - r.feature);
+}
+// ---------- primitive dispatch ----------
+function collidePrimitives(a, b, centerA, centerB, speculativeMargin, featureBase) {
+    const ka = a.shape.kind;
+    const kb = b.shape.kind;
+    if (ka === 'box' && kb === 'box') {
+        return collideBoxes(a, b, centerA, centerB, speculativeMargin, featureBase);
+    }
+    if (ka === 'sphere' && kb === 'sphere') {
+        return sphereSphere(a, b, centerA, centerB, speculativeMargin, featureBase, false);
+    }
+    if (ka === 'sphere' && kb === 'box') {
+        return sphereBox(a, b, centerA, centerB, speculativeMargin, featureBase, false);
+    }
+    if (ka === 'box' && kb === 'sphere') {
+        return sphereBox(b, a, centerB, centerA, speculativeMargin, featureBase, true);
+    }
+    if (ka === 'sphere' && kb === 'capsule') {
+        return sphereCapsule(a, b, centerA, centerB, speculativeMargin, featureBase, false);
+    }
+    if (ka === 'capsule' && kb === 'sphere') {
+        return sphereCapsule(b, a, centerB, centerA, speculativeMargin, featureBase, true);
+    }
+    if (ka === 'capsule' && kb === 'capsule') {
+        return capsuleCapsule(a, b, centerA, centerB, speculativeMargin, featureBase);
+    }
+    if (ka === 'capsule' && kb === 'box') {
+        return capsuleBox(a, b, centerA, centerB, speculativeMargin, featureBase, false);
+    }
+    /* istanbul ignore next -- when a box operand reaches this point kb is necessarily 'capsule' (box-box/box-sphere returned earlier), so the second condition is always true. */
+    if (ka === 'box' && kb === 'capsule') {
+        return capsuleBox(b, a, centerB, centerA, speculativeMargin, featureBase, true);
+    }
+    /* istanbul ignore next -- every primitive shape pairing is enumerated above; this is an exhaustiveness guard. */
+    return undefined;
+}
+// ---------- sphere / capsule closed forms ----------
+function radiusOf(shape) {
+    /* istanbul ignore next -- radiusOf is only called for sphere/capsule operands; the box arm is defensive. */
+    return shape.kind === 'box' ? 0 : shape.radius;
+}
+/**
+ * Build a single contact point from two world points on the surfaces of two
+ * spheres of the given radii, with normal from centerA-sphere to centerB-sphere.
+ * `flip` swaps which passed body is A vs B relative to the caller's frame.
+ */
+function pointContact(posA, posB, radiusA, radiusB, centerA, centerB, speculativeMargin, feature, flip) {
+    const delta = subVec3(posB, posA);
+    const distSq = dotVec3(delta, delta);
+    const dist = solverSqrt(distSq);
+    const sumR = radiusA + radiusB;
+    const penetration = sumR - dist;
+    if (penetration < -speculativeMargin) {
+        return undefined;
+    }
+    let normal;
+    if (dist > 1e-9) {
+        normal = scaleVec3(delta, 1 / dist);
+    }
+    else {
+        normal = { x: 0, y: 1, z: 0 };
+    }
+    // contact point midway between the two surfaces
+    const surfaceA = addVec3(posA, scaleVec3(normal, radiusA));
+    const surfaceB = subVec3(posB, scaleVec3(normal, radiusB));
+    const mid = scaleVec3(addVec3(surfaceA, surfaceB), 0.5);
+    const outNormal = flip ? scaleVec3(normal, -1) : normal;
+    const aCenter = flip ? centerB : centerA;
+    const bCenter = flip ? centerA : centerB;
+    return {
+        a: 0,
+        b: 0,
+        normal: outNormal,
+        points: [{ rA: subVec3(mid, aCenter), rB: subVec3(mid, bCenter), penetration, feature }],
+    };
+}
+function sphereSphere(a, b, ca, cb, margin, feature, flip) {
+    return pointContact(a.p, b.p, radiusOf(a.shape), radiusOf(b.shape), ca, cb, margin, feature, flip);
+}
+function closestPointOnBox(box, worldPoint) {
+    /* istanbul ignore next -- callers always pass a box; type guard only. */
+    if (box.shape.kind !== 'box') {
+        throw new Error('closestPointOnBox requires a box');
+    }
+    const half = box.shape.half;
+    const local = rotatePointByQuatInverse(box.q, subVec3(worldPoint, box.p));
+    const clampedLocal = {
+        x: clamp(local.x, -half.x, half.x),
+        y: clamp(local.y, -half.y, half.y),
+        z: clamp(local.z, -half.z, half.z),
+    };
+    const inside = clampedLocal.x === local.x && clampedLocal.y === local.y && clampedLocal.z === local.z;
+    return { point: addVec3(box.p, rotatePointByQuat(box.q, clampedLocal)), inside, localClamped: clampedLocal };
+}
+function sphereBox(sphere, box, cSphere, cBox, margin, feature, flip) {
+    /* istanbul ignore next -- the dispatch only calls sphereBox with a (sphere, box) pair; type guard only. */
+    if (box.shape.kind !== 'box' || sphere.shape.kind !== 'sphere') {
+        return undefined;
+    }
+    const radius = sphere.shape.radius;
+    const closest = closestPointOnBox(box, sphere.p);
+    const half = box.shape.half;
+    if (closest.inside) {
+        // sphere center inside the box: push out along the least-penetrating local axis
+        const local = closest.localClamped;
+        const distances = [half.x - Math.abs(local.x), half.y - Math.abs(local.y), half.z - Math.abs(local.z)];
+        let axis = 0;
+        if (distances[1] < distances[axis])
+            axis = 1;
+        if (distances[2] < distances[axis])
+            axis = 2;
+        const localAxes = [{ x: 1, y: 0, z: 0 }, { x: 0, y: 1, z: 0 }, { x: 0, y: 0, z: 1 }];
+        const localComponent = axis === 0 ? local.x : axis === 1 ? local.y : local.z;
+        const localNormal = scaleVec3(localAxes[axis], localComponent >= 0 ? 1 : -1);
+        const worldNormal = rotatePointByQuat(box.q, localNormal); // sphere is A here → normal box->sphere below
+        const penetration = distances[axis] + radius;
+        // caller frame: sphere==first arg. When !flip, sphere is A: normal A->B = sphere->box = -worldNormal
+        const nSphereToBox = scaleVec3(worldNormal, -1);
+        const mid = sphere.p;
+        return emitSingle(nSphereToBox, mid, penetration, cSphere, cBox, feature, flip);
+    }
+    const delta = subVec3(sphere.p, closest.point);
+    const dist = solverSqrt(dotVec3(delta, delta));
+    const penetration = radius - dist;
+    if (penetration < -margin) {
+        return undefined;
+    }
+    /* istanbul ignore next -- the fallback fires only when the sphere centre lies exactly on the box surface (dist === 0), which quantised inputs do not produce. */
+    const nBoxToSphere = dist > 1e-9 ? scaleVec3(delta, 1 / dist) : { x: 0, y: 1, z: 0 };
+    const nSphereToBox = scaleVec3(nBoxToSphere, -1);
+    const mid = scaleVec3(addVec3(closest.point, subVec3(sphere.p, scaleVec3(nBoxToSphere, radius))), 0.5);
+    return emitSingle(nSphereToBox, mid, penetration, cSphere, cBox, feature, flip);
+}
+/** Emit a single-point manifold with normal (sphere->box) in the caller's A->B frame. */
+function emitSingle(nSphereToBox, mid, penetration, cSphere, cBox, feature, flip) {
+    // caller frame: when !flip, first arg (sphere) is A -> normal A->B = sphere->box
+    const normal = flip ? scaleVec3(nSphereToBox, -1) : nSphereToBox;
+    const aCenter = flip ? cBox : cSphere;
+    const bCenter = flip ? cSphere : cBox;
+    return {
+        a: 0,
+        b: 0,
+        normal,
+        points: [{ rA: subVec3(mid, aCenter), rB: subVec3(mid, bCenter), penetration, feature }],
+    };
+}
+function capsuleSegment(capsule) {
+    /* istanbul ignore next -- callers always pass a capsule; type guard only. */
+    if (capsule.shape.kind !== 'capsule') {
+        throw new Error('capsuleSegment requires a capsule');
+    }
+    const axis = rotatePointByQuat(capsule.q, { x: 0, y: capsule.shape.halfHeight, z: 0 });
+    return { start: subVec3(capsule.p, axis), end: addVec3(capsule.p, axis), radius: capsule.shape.radius };
+}
+function closestPointOnSegment(point, start, end) {
+    const ab = subVec3(end, start);
+    const denom = dotVec3(ab, ab);
+    if (denom === 0) {
+        return start;
+    }
+    const t = clamp(dotVec3(subVec3(point, start), ab) / denom, 0, 1);
+    return addVec3(start, scaleVec3(ab, t));
+}
+function sphereCapsule(sphere, capsule, cSphere, cCapsule, margin, feature, flip) {
+    const seg = capsuleSegment(capsule);
+    const closest = closestPointOnSegment(sphere.p, seg.start, seg.end);
+    return pointContact(sphere.p, closest, radiusOf(sphere.shape), seg.radius, cSphere, cCapsule, margin, feature, flip);
+}
+function closestSegmentSegment(p1, q1, p2, q2) {
+    const d1 = subVec3(q1, p1);
+    const d2 = subVec3(q2, p2);
+    const r = subVec3(p1, p2);
+    const a = dotVec3(d1, d1);
+    const e = dotVec3(d2, d2);
+    const f = dotVec3(d2, r);
+    let s = 0;
+    let t = 0;
+    if (a <= 1e-12 && e <= 1e-12) {
+        return { c1: p1, c2: p2 };
+    }
+    if (a <= 1e-12) {
+        t = clamp(f / e, 0, 1);
+    }
+    else {
+        const c = dotVec3(d1, r);
+        if (e <= 1e-12) {
+            s = clamp(-c / a, 0, 1);
+        }
+        else {
+            const b = dotVec3(d1, d2);
+            const denom = a * e - b * b;
+            s = denom !== 0 ? clamp((b * f - c * e) / denom, 0, 1) : 0;
+            t = (b * s + f) / e;
+            if (t < 0) {
+                t = 0;
+                s = clamp(-c / a, 0, 1);
+            }
+            else if (t > 1) {
+                t = 1;
+                s = clamp((b - c) / a, 0, 1);
+            }
+        }
+    }
+    return { c1: addVec3(p1, scaleVec3(d1, s)), c2: addVec3(p2, scaleVec3(d2, t)) };
+}
+function capsuleCapsule(a, b, ca, cb, margin, feature) {
+    const sa = capsuleSegment(a);
+    const sb = capsuleSegment(b);
+    const closest = closestSegmentSegment(sa.start, sa.end, sb.start, sb.end);
+    return pointContact(closest.c1, closest.c2, sa.radius, sb.radius, ca, cb, margin, feature, false);
+}
+function capsuleBox(capsule, box, cCapsule, cBox, margin, feature, flip) {
+    // Sample the capsule's two endpoints and center as spheres against the box.
+    const seg = capsuleSegment(capsule);
+    const samples = [seg.start, seg.end, scaleVec3(addVec3(seg.start, seg.end), 0.5)];
+    const points = [];
+    let normal;
+    let deepest = -Infinity;
+    samples.forEach((sample, i) => {
+        const sphere = { index: capsule.index, p: sample, q: capsule.q, shape: { kind: 'sphere', radius: seg.radius } };
+        const sub = sphereBox(sphere, box, cCapsule, cBox, margin, feature + i, flip);
+        if (sub === undefined) {
+            return;
+        }
+        for (const point of sub.points) {
+            points.push(point);
+        }
+        const d = sub.points[0].penetration;
+        if (d > deepest) {
+            deepest = d;
+            normal = sub.normal;
+        }
+    });
+    if (points.length === 0 || normal === undefined) {
+        return undefined;
+    }
+    return { a: 0, b: 0, normal, points };
+}
+// ---------- box-box SAT + face clipping (spike port) ----------
+// Rotation matrices are pure functions of the quaternion, and quaternion
+// objects are never mutated in place (integration reassigns b.q), so identity
+// memoization is value-identical; entries die with their quats.
+const quatMat3Cache = new WeakMap();
+function quatToMat3Cached(q) {
+    let m = quatMat3Cache.get(q);
+    if (m === undefined) {
+        m = quatToMat3(q);
+        quatMat3Cache.set(q, m);
+    }
+    return m;
+}
+function boxAxes(rot) {
+    return [
+        { x: rot[0], y: rot[3], z: rot[6] },
+        { x: rot[1], y: rot[4], z: rot[7] },
+        { x: rot[2], y: rot[5], z: rot[8] },
+    ];
+}
+function halfArr(shape) {
+    /* istanbul ignore next -- halfArr is only called for box shapes; type guard only. */
+    if (shape.kind !== 'box') {
+        throw new Error('halfArr requires a box');
+    }
+    return [shape.half.x, shape.half.y, shape.half.z];
+}
+function supportPoint(center, axes, half, dir) {
+    let p = center;
+    p = addVec3(p, scaleVec3(axes[0], dotVec3(axes[0], dir) >= 0 ? half[0] : -half[0]));
+    p = addVec3(p, scaleVec3(axes[1], dotVec3(axes[1], dir) >= 0 ? half[1] : -half[1]));
+    p = addVec3(p, scaleVec3(axes[2], dotVec3(axes[2], dir) >= 0 ? half[2] : -half[2]));
+    return p;
+}
+// Step-scoped ping-pong scratch for face clipping. Slots are fully overwritten
+// before every read (counts are threaded explicitly), so no value survives
+// into any later step's output.
+// rdm-ignore-next-line determinism/no-module-mutable-state: step-scoped clip scratch, fully overwritten before every read
+const clipScratch = { a: [], b: [] };
+// Incident-face corner sign pattern (hoisted — the literal allocated per call).
+const BOX_FACE_CORNERS = [[-1, -1], [-1, 1], [1, 1], [1, -1]];
+function ensureClipSlots(buffer, count) {
+    while (buffer.length < count) {
+        buffer.push({ x: 0, y: 0, z: 0, id: 0 });
+    }
+}
+/**
+ * Sutherland–Hodgman half-space clip, scalarized in the exact IEEE operation
+ * order of the previous vector-helper form. Reads `input[0..inCount)`, writes
+ * `output`, returns the output count.
+ */
+function clipPlaneScratch(input, inCount, nx, ny, nz, offset, planeId, output) {
+    ensureClipSlots(output, inCount + 1);
+    let outCount = 0;
+    for (let i = 0; i < inCount; i += 1) {
+        const cur = input[i];
+        const nxt = input[(i + 1) % inCount];
+        const dc = nx * cur.x + ny * cur.y + nz * cur.z - offset;
+        const dn = nx * nxt.x + ny * nxt.y + nz * nxt.z - offset;
+        if (dc <= 0) {
+            const keep = output[outCount];
+            keep.x = cur.x;
+            keep.y = cur.y;
+            keep.z = cur.z;
+            keep.id = cur.id;
+            outCount += 1;
+        }
+        if ((dc < 0 && dn > 0) || (dc > 0 && dn < 0)) {
+            const t = dc / (dc - dn);
+            const cross = output[outCount];
+            cross.x = cur.x + (nxt.x - cur.x) * t;
+            cross.y = cur.y + (nxt.y - cur.y) * t;
+            cross.z = cur.z + (nxt.z - cur.z) * t;
+            cross.id = cur.id * 16 + planeId + 4;
+            outCount += 1;
+        }
+    }
+    return outCount;
+}
+function collideBoxes(A, B, centerA, centerB, speculativeMargin, featureBase) {
+    const rotA = quatToMat3Cached(A.q);
+    const rotB = quatToMat3Cached(B.q);
+    const halfA = halfArr(A.shape);
+    const halfB = halfArr(B.shape);
+    const hA0 = halfA[0];
+    const hA1 = halfA[1];
+    const hA2 = halfA[2];
+    const hB0 = halfB[0];
+    const hB1 = halfB[1];
+    const hB2 = halfB[2];
+    const dx = B.p.x - A.p.x;
+    const dy = B.p.y - A.p.y;
+    const dz = B.p.z - A.p.z;
+    // Scalarized SAT: the 15-axis loop is the narrow-phase hot path, so the
+    // vector helpers are expanded component-wise in the exact same IEEE
+    // operation order (axis i of a rotation matrix is (rot[i], rot[3+i], rot[6+i])).
+    let facePen = Infinity;
+    let faceIndex = -1;
+    let faceFound = false;
+    let faceNx = 0;
+    let faceNy = 0;
+    let faceNz = 0;
+    let edgePen = Infinity;
+    let edgeIndex = -1;
+    let edgeFound = false;
+    let edgeNx = 0;
+    let edgeNy = 0;
+    let edgeNz = 0;
+    const tryAxis = (ax, ay, az, index, isEdge) => {
+        const l2 = ax * ax + ay * ay + az * az;
+        if (l2 < 1e-8) {
+            return true;
+        }
+        const inv = 1 / solverSqrt(l2);
+        const nx = ax * inv;
+        const ny = ay * inv;
+        const nz = az * inv;
+        const sep = Math.abs(dx * nx + dy * ny + dz * nz)
+            - ((Math.abs(rotA[0] * nx + rotA[3] * ny + rotA[6] * nz) * hA0
+                + Math.abs(rotA[1] * nx + rotA[4] * ny + rotA[7] * nz) * hA1
+                + Math.abs(rotA[2] * nx + rotA[5] * ny + rotA[8] * nz) * hA2)
+                + (Math.abs(rotB[0] * nx + rotB[3] * ny + rotB[6] * nz) * hB0
+                    + Math.abs(rotB[1] * nx + rotB[4] * ny + rotB[7] * nz) * hB1
+                    + Math.abs(rotB[2] * nx + rotB[5] * ny + rotB[8] * nz) * hB2));
+        if (sep > speculativeMargin) {
+            return false;
+        }
+        const pen = -sep;
+        if (isEdge) {
+            if (pen < edgePen - 1e-9) {
+                edgePen = pen;
+                edgeNx = nx;
+                edgeNy = ny;
+                edgeNz = nz;
+                edgeIndex = index;
+                edgeFound = true;
+            }
+        }
+        else if (pen < facePen - 1e-9) {
+            facePen = pen;
+            faceNx = nx;
+            faceNy = ny;
+            faceNz = nz;
+            faceIndex = index;
+            faceFound = true;
+        }
+        return true;
+    };
+    for (let i = 0; i < 3; i += 1) {
+        if (!tryAxis(rotA[i], rotA[3 + i], rotA[6 + i], i, false)) {
+            return undefined;
+        }
+    }
+    for (let i = 0; i < 3; i += 1) {
+        if (!tryAxis(rotB[i], rotB[3 + i], rotB[6 + i], 3 + i, false)) {
+            return undefined;
+        }
+    }
+    for (let i = 0; i < 3; i += 1) {
+        const aix = rotA[i];
+        const aiy = rotA[3 + i];
+        const aiz = rotA[6 + i];
+        for (let j = 0; j < 3; j += 1) {
+            const bjx = rotB[j];
+            const bjy = rotB[3 + j];
+            const bjz = rotB[6 + j];
+            if (!tryAxis(aiy * bjz - aiz * bjy, aiz * bjx - aix * bjz, aix * bjy - aiy * bjx, 6 + i * 3 + j, true)) {
+                return undefined;
+            }
+        }
+    }
+    /* istanbul ignore next -- box face axes are unit vectors and never degenerate, so at least one separating axis is always recorded. */
+    if (!faceFound && !edgeFound) {
+        return undefined;
+    }
+    // qu3e-style hysteresis: use the edge axis only when decisively shallower.
+    // Only for real (positive-penetration) overlaps — for speculative/separated
+    // pairs (negative pen) the face manifold gives correct near-body anchors,
+    // while the edge path would place a single point far from the bodies.
+    const edgePreferred = edgeFound && facePen > 0 && edgePen < facePen * 0.9 - 5e-3;
+    /* istanbul ignore next -- a face axis is always recorded here (see the guard above), so the !faceFound arm is unreachable. */
+    const bestIsEdge = !faceFound ? edgeFound : edgePreferred;
+    const bestIndex = bestIsEdge ? edgeIndex : faceIndex;
+    const minPen = bestIsEdge ? edgePen : facePen;
+    let normal = bestIsEdge ? { x: edgeNx, y: edgeNy, z: edgeNz } : { x: faceNx, y: faceNy, z: faceNz };
+    if (normal.x * dx + normal.y * dy + normal.z * dz < 0) {
+        normal = scaleVec3(normal, -1);
+    }
+    if (bestIsEdge) {
+        const axesA = boxAxes(rotA);
+        const axesB = boxAxes(rotB);
+        const i = Math.trunc((bestIndex - 6) / 3);
+        const j = (bestIndex - 6) % 3;
+        const pA = supportPoint(A.p, axesA, halfA, normal);
+        const pB = supportPoint(B.p, axesB, halfB, scaleVec3(normal, -1));
+        const eA = axesA[i];
+        const eB = axesB[j];
+        const r = subVec3(pB, pA);
+        const aa = dotVec3(eA, eA);
+        const ee = dotVec3(eB, eB);
+        const ff = dotVec3(eB, r);
+        const cc = dotVec3(eA, r);
+        const bd = dotVec3(eA, eB);
+        const denom = aa * ee - bd * bd;
+        /* istanbul ignore next -- the edge axis is a normalised cross product of two non-parallel edges, so its denominator is non-zero. */
+        const s = denom !== 0 ? clamp((bd * ff - cc * ee) / denom, -halfA[i], halfA[i]) : 0;
+        const t = clamp((bd * s + ff) / ee, -halfB[j], halfB[j]);
+        const cA = addVec3(pA, scaleVec3(eA, s));
+        const cB = addVec3(pB, scaleVec3(eB, t));
+        const mid = scaleVec3(addVec3(cA, cB), 0.5);
+        return { a: 0, b: 0, normal, points: [{ rA: subVec3(mid, centerA), rB: subVec3(mid, centerB), penetration: minPen, feature: featureBase + 1000 + bestIndex }] };
+    }
+    const refIsA = bestIndex < 3;
+    const refCenter = refIsA ? A.p : B.p;
+    const refRot = refIsA ? rotA : rotB;
+    const refHalf = refIsA ? halfA : halfB;
+    const incCenter = refIsA ? B.p : A.p;
+    const incRot = refIsA ? rotB : rotA;
+    const incHalf = refIsA ? halfB : halfA;
+    const rnx = refIsA ? normal.x : normal.x * -1;
+    const rny = refIsA ? normal.y : normal.y * -1;
+    const rnz = refIsA ? normal.z : normal.z * -1;
+    let incFace = 0;
+    let minDot = Infinity;
+    for (let i = 0; i < 3; i += 1) {
+        const dd = incRot[i] * rnx + incRot[3 + i] * rny + incRot[6 + i] * rnz;
+        if (dd < minDot) {
+            minDot = dd;
+            incFace = i * 2;
+        }
+        if (-dd < minDot) {
+            minDot = -dd;
+            incFace = i * 2 + 1;
+        }
+    }
+    // incident-face corners into scratch (scalar form of faceVertices)
+    const incAxis = Math.trunc(incFace / 2);
+    const incSign = incFace % 2 === 0 ? 1 : -1;
+    const u = (incAxis + 1) % 3;
+    const w = (incAxis + 2) % 3;
+    const sAxis = incSign * incHalf[incAxis];
+    const fcx = incCenter.x + incRot[incAxis] * sAxis;
+    const fcy = incCenter.y + incRot[3 + incAxis] * sAxis;
+    const fcz = incCenter.z + incRot[6 + incAxis] * sAxis;
+    ensureClipSlots(clipScratch.a, 4);
+    let poly = clipScratch.a;
+    let spare = clipScratch.b;
+    let polyCount = 0;
+    for (const [su, sw] of BOX_FACE_CORNERS) {
+        const suh = su * incHalf[u];
+        const swh = sw * incHalf[w];
+        const slot = poly[polyCount];
+        slot.x = fcx + (incRot[u] * suh + incRot[w] * swh);
+        slot.y = fcy + (incRot[3 + u] * suh + incRot[3 + w] * swh);
+        slot.z = fcz + (incRot[6 + u] * suh + incRot[6 + w] * swh);
+        slot.id = featureBase + polyCount + 1;
+        polyCount += 1;
+    }
+    const refFaceAxis = bestIndex % 3;
+    let planeIdx = 0;
+    for (let i = 0; i < 3; i += 1) {
+        if (i === refFaceAxis) {
+            continue;
+        }
+        planeIdx += 1;
+        const h = refHalf[i];
+        const ax = refRot[i];
+        const ay = refRot[3 + i];
+        const az = refRot[6 + i];
+        const negAx = ax * -1;
+        const negAy = ay * -1;
+        const negAz = az * -1;
+        polyCount = clipPlaneScratch(poly, polyCount, negAx, negAy, negAz, negAx * refCenter.x + negAy * refCenter.y + negAz * refCenter.z + h, planeIdx * 2 - 1, spare);
+        let swap = poly;
+        poly = spare;
+        spare = swap;
+        polyCount = clipPlaneScratch(poly, polyCount, ax, ay, az, ax * refCenter.x + ay * refCenter.y + az * refCenter.z + h, planeIdx * 2, spare);
+        swap = poly;
+        poly = spare;
+        spare = swap;
+        if (polyCount === 0) {
+            return undefined;
+        }
+    }
+    const refH = refHalf[refFaceAxis];
+    const refFaceDist = rnx * refCenter.x + rny * refCenter.y + rnz * refCenter.z + refH;
+    const points = [];
+    for (let i = 0; i < polyCount; i += 1) {
+        const vert = poly[i];
+        const depth = refFaceDist - (rnx * vert.x + rny * vert.y + rnz * vert.z);
+        if (depth >= -speculativeMargin) {
+            const onRefX = vert.x + rnx * depth;
+            const onRefY = vert.y + rny * depth;
+            const onRefZ = vert.z + rnz * depth;
+            const midX = (vert.x + onRefX) * 0.5;
+            const midY = (vert.y + onRefY) * 0.5;
+            const midZ = (vert.z + onRefZ) * 0.5;
+            points.push({
+                rA: { x: midX - centerA.x, y: midY - centerA.y, z: midZ - centerA.z },
+                rB: { x: midX - centerB.x, y: midY - centerB.y, z: midZ - centerB.z },
+                penetration: depth,
+                feature: vert.id,
+            });
+        }
+    }
+    /* istanbul ignore next -- a face manifold that passes the SAT overlap test always retains at least one clipped point above the speculative margin. */
+    if (points.length === 0) {
+        return undefined;
+    }
+    return { a: 0, b: 0, normal, points };
+}
+// ---------- mesh (one-sided static triangle) ----------
+function meshManifold(a, b, speculativeMargin) {
+    const meshIsA = a.shape.kind === 'mesh';
+    const meshBody = meshIsA ? a : b;
+    const otherBody = meshIsA ? b : a;
+    if (meshBody.shape.kind !== 'mesh' || otherBody.shape.kind === 'mesh') {
+        return undefined;
+    }
+    const prims = primitiveViews(otherBody);
+    const points = [];
+    let normal;
+    let deepest = -Infinity;
+    let feature = 0;
+    const triangles = meshBody.shape.triangles.map((tri) => [
+        addVec3(meshBody.p, rotatePointByQuat(meshBody.q, tri[0])),
+        addVec3(meshBody.p, rotatePointByQuat(meshBody.q, tri[1])),
+        addVec3(meshBody.p, rotatePointByQuat(meshBody.q, tri[2])),
+    ]);
+    for (const prim of prims) {
+        /* istanbul ignore next -- primitiveViews only yields box/sphere/capsule sub-bodies (compound children are primitives); this skip is unreachable. */
+        if (prim.shape.kind !== 'sphere' && prim.shape.kind !== 'capsule' && prim.shape.kind !== 'box') {
+            continue;
+        }
+        const radius = prim.shape.kind === 'box'
+            ? 0
+            : prim.shape.radius;
+        // Represent boxes by their center as a fallback point-sphere against triangles
+        // (dynamic box-vs-mesh uses the box's support samples).
+        const samplePoints = prim.shape.kind === 'box'
+            ? boxSupportSamples(prim)
+            : prim.shape.kind === 'capsule'
+                ? capsuleSamples(prim)
+                : [prim.p];
+        for (const triangle of triangles) {
+            for (const sample of samplePoints) {
+                const closest = closestPointOnTriangle(sample, triangle[0], triangle[1], triangle[2]);
+                const delta = subVec3(sample, closest);
+                const dist = solverSqrt(dotVec3(delta, delta));
+                const triNormal = triangleNormal(triangle[0], triangle[1], triangle[2]);
+                const side = dotVec3(delta, triNormal);
+                const penetration = radius - dist;
+                if (penetration < -speculativeMargin || side < 0) {
+                    continue;
+                }
+                const contactNormal = triNormal; // one-sided: mesh -> other
+                const mid = closest;
+                // caller frame normal A->B
+                const nAtoB = meshIsA ? contactNormal : scaleVec3(contactNormal, -1);
+                points.push({
+                    rA: subVec3(mid, a.p),
+                    rB: subVec3(mid, b.p),
+                    penetration,
+                    feature: feature,
+                });
+                feature += 1;
+                if (penetration > deepest) {
+                    deepest = penetration;
+                    normal = nAtoB;
+                }
+            }
+        }
+    }
+    if (points.length === 0 || normal === undefined) {
+        return undefined;
+    }
+    return { a: a.index, b: b.index, normal, points: reducePoints(points) };
+}
+function triangleNormal(a, b, c) {
+    const n = crossVec3(subVec3(b, a), subVec3(c, a));
+    const len = solverSqrt(dotVec3(n, n));
+    return len === 0 ? { x: 0, y: 1, z: 0 } : scaleVec3(n, 1 / len);
+}
+function boxSupportSamples(box) {
+    /* istanbul ignore next -- boxSupportSamples is only called for box operands; type guard only. */
+    if (box.shape.kind !== 'box') {
+        return [box.p];
+    }
+    const rot = quatToMat3Cached(box.q);
+    const axes = boxAxes(rot);
+    const h = halfArr(box.shape);
+    const out = [];
+    for (const sx of [-1, 1]) {
+        for (const sy of [-1, 1]) {
+            for (const sz of [-1, 1]) {
+                out.push(addVec3(box.p, addVec3(scaleVec3(axes[0], sx * h[0]), addVec3(scaleVec3(axes[1], sy * h[1]), scaleVec3(axes[2], sz * h[2])))));
+            }
+        }
+    }
+    return out;
+}
+function capsuleSamples(capsule) {
+    const seg = capsuleSegment(capsule);
+    return [seg.start, seg.end, scaleVec3(addVec3(seg.start, seg.end), 0.5)];
+}
+function closestPointOnTriangle(p, a, b, c) {
+    const ab = subVec3(b, a);
+    const ac = subVec3(c, a);
+    const ap = subVec3(p, a);
+    const d1 = dotVec3(ab, ap);
+    const d2 = dotVec3(ac, ap);
+    if (d1 <= 0 && d2 <= 0) {
+        return a;
+    }
+    const bp = subVec3(p, b);
+    const d3 = dotVec3(ab, bp);
+    const d4 = dotVec3(ac, bp);
+    if (d3 >= 0 && d4 <= d3) {
+        return b;
+    }
+    const vc = d1 * d4 - d3 * d2;
+    if (vc <= 0 && d1 >= 0 && d3 <= 0) {
+        const v = d1 / (d1 - d3);
+        return addVec3(a, scaleVec3(ab, v));
+    }
+    const cp = subVec3(p, c);
+    const d5 = dotVec3(ab, cp);
+    const d6 = dotVec3(ac, cp);
+    if (d6 >= 0 && d5 <= d6) {
+        return c;
+    }
+    const vb = d5 * d2 - d1 * d6;
+    if (vb <= 0 && d2 >= 0 && d6 <= 0) {
+        const w = d2 / (d2 - d6);
+        return addVec3(a, scaleVec3(ac, w));
+    }
+    const va = d3 * d6 - d5 * d4;
+    if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) {
+        const w = (d4 - d3) / ((d4 - d3) + (d5 - d6));
+        return addVec3(b, scaleVec3(subVec3(c, b), w));
+    }
+    const denom = 1 / (va + vb + vc);
+    const v = vb * denom;
+    const w = vc * denom;
+    return addVec3(a, addVec3(scaleVec3(ab, v), scaleVec3(ac, w)));
+}
+// ============================================================================
+// Sequential-impulse velocity solver + split impulse + islands + sleep
+// ============================================================================
+export const SOLVER_CONSTANTS = {
+    BAUMGARTE: 0.2,
+    SLOP: 0.005,
+    WAKE_VEL2: 0.005,
+    SLEEP_VEL2: 0.005,
+    SLEEP_FRAMES: 20,
+    RESTITUTION_THRESHOLD: 1.0,
+    WARM_MATCH_TOL2: 0.01,
+    LINEAR_DAMPING: 0.995,
+    ANGULAR_DAMPING: 0.98,
+};
+/**
+ * Warm-cache maps pack the canonical index pair (a<b) into one exact integer
+ * `a * WARM_KEY_BASE + b` — string pair keys were measurable churn on large piles.
+ */
+export const WARM_KEY_BASE = 2 ** 20;
+function solid(b) {
+    return b.isDynamic && !b.sleeping;
+}
+function worldInvInertiaLocked(b) {
+    if (!solid(b)) {
+        return [0, 0, 0, 0, 0, 0, 0, 0, 0];
+    }
+    const base = worldInvInertia(quatToMat3Cached(b.q), b.invInertiaLocal);
+    const lock = b.angularLock;
+    const lockArr = [lock.x, lock.y, lock.z];
+    const out = new Array(9).fill(0);
+    for (let row = 0; row < 3; row += 1) {
+        for (let col = 0; col < 3; col += 1) {
+            out[row * 3 + col] = base[row * 3 + col] * lockArr[row] * lockArr[col];
+        }
+    }
+    return out;
+}
+function invMassOf(b) {
+    return solid(b) ? b.invMassVec : ZERO;
+}
+function effectiveMass(axis, rA, rB, imA, imB, iiA, iiB) {
+    const linA = axis.x * axis.x * imA.x + axis.y * axis.y * imA.y + axis.z * axis.z * imA.z;
+    const linB = axis.x * axis.x * imB.x + axis.y * axis.y * imB.y + axis.z * axis.z * imB.z;
+    const raxn = crossVec3(rA, axis);
+    const rbxn = crossVec3(rB, axis);
+    const denom = linA + linB + dotVec3(raxn, mulMat3Vec(iiA, raxn)) + dotVec3(rbxn, mulMat3Vec(iiB, rbxn));
+    return denom === 0 ? 0 : 1 / denom;
+}
+function tangentBasis(n) {
+    const t1 = Math.abs(n.x) >= 0.57735
+        ? normalizeVec3Local({ x: n.y, y: -n.x, z: 0 })
+        : normalizeVec3Local({ x: 0, y: n.z, z: -n.y });
+    const t2 = crossVec3(n, t1);
+    return [t1, t2];
+}
+function normalizeVec3Local(a) {
+    const l = solverSqrt(dotVec3(a, a));
+    /* istanbul ignore next -- called only on the tangent-basis vectors of a unit contact normal, which are never zero-length. */
+    return l === 0 ? { x: 0, y: 0, z: 0 } : scaleVec3(a, 1 / l);
+}
+function matchWarm(points, rA) {
+    if (points === undefined) {
+        return undefined;
+    }
+    let best;
+    let bestD = SOLVER_CONSTANTS.WARM_MATCH_TOL2;
+    for (const p of points) {
+        const dx = p.anchor.x - rA.x;
+        const dy = p.anchor.y - rA.y;
+        const dz = p.anchor.z - rA.z;
+        const d2 = dx * dx + dy * dy + dz * dz;
+        if (d2 < bestD) {
+            bestD = d2;
+            best = p;
+        }
+    }
+    return best;
+}
+// Step-scoped pool: the cursor resets at solveRigidStep entry and every field
+// is overwritten on take, so no value crosses steps. Constraints never escape
+// the step (warm-cache entries copy rA by reference from the manifold points,
+// which are freshly allocated).
+// rdm-ignore-next-line determinism/no-module-mutable-state: step-scoped constraint pool, fully overwritten before every read
+const constraintPool = { slots: [], high: 0 };
+function takeConstraint() {
+    if (constraintPool.high === constraintPool.slots.length) {
+        constraintPool.slots.push({
+            manifoldIndex: 0, a: 0, b: 0,
+            normal: ZERO, t1: ZERO, t2: ZERO, rA: ZERO, rB: ZERO,
+            penetration: 0, speculative: false,
+            massN: 0, massT1: 0, massT2: 0, bias: 0,
+            accN: 0, accT1: 0, accT2: 0, accNb: 0,
+            mu: 0, restitution: 0,
+        });
+    }
+    const slot = constraintPool.slots[constraintPool.high];
+    constraintPool.high += 1;
+    return slot;
+}
+/** Runs one deterministic rigid-body step in place over `bodies`. */
+export function solveRigidStep(bodies, options) {
+    /* istanbul ignore next -- worlds are validated far below this bound; guards the packed warm-cache key from silent index collisions. */
+    if (bodies.length > WARM_KEY_BASE) {
+        throw new Error(`solveRigidStep supports at most ${WARM_KEY_BASE} bodies`);
+    }
+    constraintPool.high = 0;
+    const dt = options.dt;
+    // 1. reset pseudo-velocities; apply gravity + damping to awake dynamics.
+    // v/w are copied so the solver owns them: callers may pass aliased vectors
+    // (canonical angularVel, shared zero constants) and the hot scalar impulse
+    // path mutates these objects in place.
+    for (const b of bodies) {
+        b.vb = { x: 0, y: 0, z: 0 };
+        b.wb = { x: 0, y: 0, z: 0 };
+        b.v = { x: b.v.x, y: b.v.y, z: b.v.z };
+        b.w = { x: b.w.x, y: b.w.y, z: b.w.z };
+        if (!solid(b)) {
+            continue;
+        }
+        b.v.y = b.v.y + options.gravityY * b.gravityScale * dt;
+    }
+    // 2. narrow-phase manifolds (canonical order i<j).
+    const manifolds = [];
+    const emitPair = (i, j) => {
+        const A = bodies[i];
+        const B = bodies[j];
+        if (!A.isDynamic && !B.isDynamic) {
+            return;
+        }
+        if (A.noCollide || B.noCollide) {
+            return;
+        }
+        if (options.noCollidePairs !== undefined && options.noCollidePairs.has(i * WARM_KEY_BASE + j)) {
+            return;
+        }
+        if ((A.mask & B.layer) === 0 || (B.mask & A.layer) === 0) {
+            return;
+        }
+        const margin = A.ccd || B.ccd ? speculativeMarginFor(A, B, dt) : 0;
+        const manifold = generateManifold(toGeom(A), toGeom(B), margin);
+        if (manifold !== undefined) {
+            manifolds.push(manifold);
+        }
+    };
+    if (options.pairs !== undefined) {
+        for (const [i, j] of options.pairs) {
+            emitPair(Math.min(i, j), Math.max(i, j));
+        }
+    }
+    else {
+        // Sort-and-sweep broadphase over swept world AABBs (indexed by canonical
+        // body order) — replaces the naive O(n²) pair scan for large piles.
+        const aabbs = bodies.map((body) => solverBodyAabb(body, dt));
+        const order = bodies.map((_, index) => index).sort((l, r) => aabbs[l].minX - aabbs[r].minX || l - r);
+        for (let sweepA = 0; sweepA < order.length; sweepA += 1) {
+            const i = order[sweepA];
+            const boundsI = aabbs[i];
+            for (let sweepB = sweepA + 1; sweepB < order.length; sweepB += 1) {
+                const j = order[sweepB];
+                const boundsJ = aabbs[j];
+                if (boundsJ.minX > boundsI.maxX) {
+                    break;
+                }
+                if (boundsJ.minY > boundsI.maxY || boundsJ.maxY < boundsI.minY || boundsJ.minZ > boundsI.maxZ || boundsJ.maxZ < boundsI.minZ) {
+                    continue;
+                }
+                emitPair(Math.min(i, j), Math.max(i, j));
+            }
+        }
+    }
+    manifolds.sort((l, r) => l.a - r.a || l.b - r.b);
+    // Bodies coupled to an active joint this step. Joints are step inputs (not
+    // world state), so any joint member — including one that fell asleep before
+    // the joint was attached — must wake and stay awake for the joint to drive it.
+    const joints = options.joints ?? [];
+    const jointBodies = new Set();
+    for (const joint of joints) {
+        for (const index of joint.bodyIndices) {
+            jointBodies.add(index);
+        }
+    }
+    // 3. wake pass: sleeping body forced awake, contacted by an awake mover, or
+    // coupled to an active joint.
+    for (const b of bodies) {
+        if ((b.wakeForced || jointBodies.has(b.index)) && b.sleeping) {
+            b.sleeping = false;
+            b.lowVelFrames = 0;
+        }
+    }
+    for (const m of manifolds) {
+        wakeIfContacted(bodies[m.a], bodies[m.b]);
+        wakeIfContacted(bodies[m.b], bodies[m.a]);
+    }
+    // 4. build contact constraints + warm start.
+    const invMass = bodies.map(invMassOf);
+    const invInertia = bodies.map(worldInvInertiaLocked);
+    const constraints = [];
+    manifolds.forEach((m, manifoldIndex) => {
+        const A = bodies[m.a];
+        const B = bodies[m.b];
+        const [t1, t2] = tangentBasis(m.normal);
+        const combinedMu = Math.floor((toInt10(A.matFriction) + toInt10(B.matFriction)) / 2) / 10;
+        const combinedRest = Math.max(toInt10(A.matRestitution), toInt10(B.matRestitution)) / 10;
+        const warmPts = options.warm.get(m.a * WARM_KEY_BASE + m.b);
+        for (const pt of m.points) {
+            const matched = matchWarm(warmPts, pt.rA);
+            const constraint = takeConstraint();
+            constraint.manifoldIndex = manifoldIndex;
+            constraint.a = m.a;
+            constraint.b = m.b;
+            constraint.normal = m.normal;
+            constraint.t1 = t1;
+            constraint.t2 = t2;
+            constraint.rA = pt.rA;
+            constraint.rB = pt.rB;
+            constraint.penetration = pt.penetration;
+            constraint.speculative = pt.penetration < 0;
+            constraint.massN = effectiveMass(m.normal, pt.rA, pt.rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+            constraint.massT1 = effectiveMass(t1, pt.rA, pt.rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+            constraint.massT2 = effectiveMass(t2, pt.rA, pt.rB, invMass[m.a], invMass[m.b], invInertia[m.a], invInertia[m.b]);
+            constraint.bias = (SOLVER_CONSTANTS.BAUMGARTE / dt) * Math.max(0, pt.penetration - SOLVER_CONSTANTS.SLOP);
+            constraint.accN = matched?.normalImpulse ?? 0;
+            constraint.accT1 = matched?.tangentImpulse1 ?? 0;
+            constraint.accT2 = matched?.tangentImpulse2 ?? 0;
+            constraint.accNb = 0;
+            constraint.mu = combinedMu;
+            constraint.restitution = combinedRest;
+            // warm-start impulse, scalar form of normal*accN + (t1*accT1 + t2*accT2)
+            applyImpulseScalar(bodies, invMass, invInertia, constraint.a, constraint.b, constraint.rA, constraint.rB, m.normal.x * constraint.accN + (t1.x * constraint.accT1 + t2.x * constraint.accT2), m.normal.y * constraint.accN + (t1.y * constraint.accT1 + t2.y * constraint.accT2), m.normal.z * constraint.accN + (t1.z * constraint.accT1 + t2.z * constraint.accT2), false);
+            constraints.push(constraint);
+        }
+    });
+    // 5. joint warm start + iterations interleaved with contacts.
+    const jointCtx = {
+        bodies,
+        invMass,
+        invInertia,
+        dt,
+        apply: (a, b, rA, rB, impulse) => applyImpulse(bodies, invMass, invInertia, a, b, rA, rB, impulse),
+        applyAngular: (a, b, angularImpulse) => {
+            const A = bodies[a];
+            const B = bodies[b];
+            if (solid(A)) {
+                A.w = subVec3(A.w, mulMat3Vec(invInertia[a], angularImpulse));
+            }
+            if (solid(B)) {
+                B.w = addVec3(B.w, mulMat3Vec(invInertia[b], angularImpulse));
+            }
+        },
+        applyToBody: (index, r, impulse) => {
+            const body = bodies[index];
+            if (!solid(body)) {
+                return;
+            }
+            body.v = addVec3(body.v, mulComponents(impulse, invMass[index]));
+            body.w = addVec3(body.w, mulMat3Vec(invInertia[index], crossVec3(r, impulse)));
+        },
+        applyBias: (a, b, rA, rB, impulse) => applyBiasImpulseAt(bodies, invMass, invInertia, a, b, rA, rB, impulse),
+        biasRelativeVelocity: (a, b, rA, rB) => relativeBiasVelocity(bodies[a], bodies[b], rA, rB),
+    };
+    for (const joint of joints) {
+        joint.prepare(jointCtx);
+    }
+    for (let iter = 0; iter < options.velocityIterations; iter += 1) {
+        for (const joint of joints) {
+            joint.iterate(jointCtx);
+        }
+        for (const c of constraints) {
+            solveContactConstraint(bodies, invMass, invInertia, c, dt);
+        }
+    }
+    // 6. store warm cache (index-pair keyed, deterministic order).
+    const warm = new Map();
+    for (const c of constraints) {
+        const key = c.a * WARM_KEY_BASE + c.b;
+        let list = warm.get(key);
+        if (list === undefined) {
+            list = [];
+            warm.set(key, list);
+        }
+        list.push({ anchor: c.rA, normalImpulse: c.accN, tangentImpulse1: c.accT1, tangentImpulse2: c.accT2 });
+    }
+    // `jointBodies` (built at the wake pass) keeps joint members awake — a motor or
+    // grab can drive them below the sleep velocity threshold, and joints are step
+    // inputs the sleeper can't see.
+    // 7. damping + integrate (real + pseudo velocity).
+    for (const b of bodies) {
+        if (!solid(b)) {
+            continue;
+        }
+        b.v = scaleVec3(b.v, b.linearDamping);
+        b.w = scaleVec3(b.w, b.angularDamping);
+        // Axis locks: a locked linear/angular axis holds zero velocity so the body
+        // can neither be pushed along it nor drift from residual velocity.
+        b.v = {
+            x: b.invMassVec.x === 0 ? 0 : b.v.x,
+            y: b.invMassVec.y === 0 ? 0 : b.v.y,
+            z: b.invMassVec.z === 0 ? 0 : b.v.z,
+        };
+        b.w = {
+            x: b.angularLock.x === 0 ? 0 : b.w.x,
+            y: b.angularLock.y === 0 ? 0 : b.w.y,
+            z: b.angularLock.z === 0 ? 0 : b.w.z,
+        };
+        b.p = addVec3(b.p, scaleVec3(addVec3(b.v, b.vb), dt));
+        if (b.hasOrientation) {
+            b.q = integrateQuat(b.q, addVec3(b.w, b.wb), dt);
+        }
+        const speed2 = dotVec3(b.v, b.v) + dotVec3(b.w, b.w);
+        b.lowVelFrames = jointBodies.has(b.index) || speed2 >= SOLVER_CONSTANTS.SLEEP_VEL2 ? 0 : b.lowVelFrames + 1;
+    }
+    // 8. island sleep over contacts + joints.
+    islandSleep(bodies, manifolds, joints);
+    // 9. per-manifold accumulated normal impulse for contact events.
+    const impulseByManifold = new Array(manifolds.length).fill(0);
+    for (const c of constraints) {
+        impulseByManifold[c.manifoldIndex] += c.accN;
+    }
+    const contactImpulses = manifolds.map((m, index) => ({
+        a: m.a,
+        b: m.b,
+        normalImpulse: impulseByManifold[index],
+        pair: `${bodies[m.a].id}|${bodies[m.b].id}`,
+    }));
+    const jointCache = joints.map((joint) => joint.emitCache());
+    return { manifolds, contactImpulses, warm, jointCache };
+}
+function toInt10(unit) {
+    return Math.round(unit * 10);
+}
+/** World AABB of a solver body's shape (orientation-aware), swept by v·dt when ccd. */
+function solverBodyAabb(body, dt) {
+    const half = shapeHalfExtent(body.shape, body.q);
+    let minX = body.p.x - half.x;
+    let maxX = body.p.x + half.x;
+    let minY = body.p.y - half.y;
+    let maxY = body.p.y + half.y;
+    let minZ = body.p.z - half.z;
+    let maxZ = body.p.z + half.z;
+    if (body.ccd) {
+        const dx = body.v.x * dt;
+        const dy = body.v.y * dt;
+        const dz = body.v.z * dt;
+        minX = Math.min(minX, minX + dx);
+        maxX = Math.max(maxX, maxX + dx);
+        minY = Math.min(minY, minY + dy);
+        maxY = Math.max(maxY, maxY + dy);
+        minZ = Math.min(minZ, minZ + dz);
+        maxZ = Math.max(maxZ, maxZ + dz);
+    }
+    return { minX, maxX, minY, maxY, minZ, maxZ };
+}
+function shapeHalfExtent(shape, q) {
+    if (shape.kind === 'box') {
+        const rot = quatToMat3Cached(q);
+        return {
+            x: Math.abs(rot[0]) * shape.half.x + Math.abs(rot[1]) * shape.half.y + Math.abs(rot[2]) * shape.half.z,
+            y: Math.abs(rot[3]) * shape.half.x + Math.abs(rot[4]) * shape.half.y + Math.abs(rot[5]) * shape.half.z,
+            z: Math.abs(rot[6]) * shape.half.x + Math.abs(rot[7]) * shape.half.y + Math.abs(rot[8]) * shape.half.z,
+        };
+    }
+    if (shape.kind === 'sphere') {
+        return { x: shape.radius, y: shape.radius, z: shape.radius };
+    }
+    if (shape.kind === 'capsule') {
+        const reach = shape.radius + shape.halfHeight;
+        return { x: reach, y: reach, z: reach };
+    }
+    if (shape.kind === 'mesh') {
+        let ext = { x: 0, y: 0, z: 0 };
+        for (const tri of shape.triangles) {
+            for (const vertex of tri) {
+                const rotated = rotatePointByQuat(q, vertex);
+                ext = { x: Math.max(ext.x, Math.abs(rotated.x)), y: Math.max(ext.y, Math.abs(rotated.y)), z: Math.max(ext.z, Math.abs(rotated.z)) };
+            }
+        }
+        return ext;
+    }
+    // compound: union of child extents about the body center.
+    let ext = { x: 0, y: 0, z: 0 };
+    for (const child of shape.children) {
+        const childCenter = rotatePointByQuat(q, child.offset);
+        const childHalf = shapeHalfExtent(child.shape, quatMultiply(q, child.q));
+        ext = {
+            x: Math.max(ext.x, Math.abs(childCenter.x) + childHalf.x),
+            y: Math.max(ext.y, Math.abs(childCenter.y) + childHalf.y),
+            z: Math.max(ext.z, Math.abs(childCenter.z) + childHalf.z),
+        };
+    }
+    return ext;
+}
+function speculativeMarginFor(a, b, dt) {
+    const relSpeed = solverSqrt(Math.max(dotVec3(a.v, a.v), dotVec3(b.v, b.v)));
+    return relSpeed * dt + SOLVER_CONSTANTS.SLOP;
+}
+function toGeom(b) {
+    return { index: b.index, p: b.p, q: b.q, shape: b.shape };
+}
+function wakeIfContacted(sleeper, other) {
+    if (sleeper.isDynamic && sleeper.sleeping && other.isDynamic && !other.sleeping
+        && dotVec3(other.v, other.v) + dotVec3(other.w, other.w) > SOLVER_CONSTANTS.WAKE_VEL2) {
+        sleeper.sleeping = false;
+        sleeper.lowVelFrames = 0;
+    }
+}
+function applyImpulse(bodies, invMass, invInertia, a, b, rA, rB, P) {
+    const A = bodies[a];
+    const B = bodies[b];
+    if (solid(A)) {
+        A.v = subVec3(A.v, mulComponents(P, invMass[a]));
+        A.w = subVec3(A.w, mulMat3Vec(invInertia[a], crossVec3(rA, P)));
+    }
+    if (solid(B)) {
+        B.v = addVec3(B.v, mulComponents(P, invMass[b]));
+        B.w = addVec3(B.w, mulMat3Vec(invInertia[b], crossVec3(rB, P)));
+    }
+}
+function applyBiasImpulseAt(bodies, invMass, invInertia, a, b, rA, rB, P) {
+    const A = bodies[a];
+    const B = bodies[b];
+    if (solid(A)) {
+        A.vb = subVec3(A.vb, mulComponents(P, invMass[a]));
+        A.wb = subVec3(A.wb, mulMat3Vec(invInertia[a], crossVec3(rA, P)));
+    }
+    if (solid(B)) {
+        B.vb = addVec3(B.vb, mulComponents(P, invMass[b]));
+        B.wb = addVec3(B.wb, mulMat3Vec(invInertia[b], crossVec3(rB, P)));
+    }
+}
+function mulComponents(a, b) {
+    return { x: a.x * b.x, y: a.y * b.y, z: a.z * b.z };
+}
+function relativeBiasVelocity(A, B, rA, rB) {
+    return subVec3(addVec3(B.vb, crossVec3(B.wb, rB)), addVec3(A.vb, crossVec3(A.wb, rA)));
+}
+/**
+ * Scalar apply of impulse (px,py,pz) at rA/rB — same operations in the same
+ * order as the vector-helper form (bit-identical results), with zero
+ * intermediate allocations. This runs per contact per velocity iteration.
+ */
+function applyImpulseScalar(bodies, invMass, invInertia, a, b, rA, rB, px, py, pz, bias) {
+    const A = bodies[a];
+    const B = bodies[b];
+    if (solid(A)) {
+        const cx = rA.y * pz - rA.z * py;
+        const cy = rA.z * px - rA.x * pz;
+        const cz = rA.x * py - rA.y * px;
+        const m = invInertia[a];
+        const inv = invMass[a];
+        const lin = bias ? A.vb : A.v;
+        const ang = bias ? A.wb : A.w;
+        lin.x = lin.x - px * inv.x;
+        lin.y = lin.y - py * inv.y;
+        lin.z = lin.z - pz * inv.z;
+        ang.x = ang.x - (m[0] * cx + m[1] * cy + m[2] * cz);
+        ang.y = ang.y - (m[3] * cx + m[4] * cy + m[5] * cz);
+        ang.z = ang.z - (m[6] * cx + m[7] * cy + m[8] * cz);
+    }
+    if (solid(B)) {
+        const cx = rB.y * pz - rB.z * py;
+        const cy = rB.z * px - rB.x * pz;
+        const cz = rB.x * py - rB.y * px;
+        const m = invInertia[b];
+        const inv = invMass[b];
+        const lin = bias ? B.vb : B.v;
+        const ang = bias ? B.wb : B.w;
+        lin.x = lin.x + px * inv.x;
+        lin.y = lin.y + py * inv.y;
+        lin.z = lin.z + pz * inv.z;
+        ang.x = ang.x + (m[0] * cx + m[1] * cy + m[2] * cz);
+        ang.y = ang.y + (m[3] * cx + m[4] * cy + m[5] * cz);
+        ang.z = ang.z + (m[6] * cx + m[7] * cy + m[8] * cz);
+    }
+}
+/** Relative velocity at the contact along direction (dx,dy,dz) — scalar form of dot(relativeVelocity, d). */
+function relativeVelocityAlong(A, B, rA, rB, dx, dy, dz) {
+    const relX = (B.v.x + (B.w.y * rB.z - B.w.z * rB.y)) - (A.v.x + (A.w.y * rA.z - A.w.z * rA.y));
+    const relY = (B.v.y + (B.w.z * rB.x - B.w.x * rB.z)) - (A.v.y + (A.w.z * rA.x - A.w.x * rA.z));
+    const relZ = (B.v.z + (B.w.x * rB.y - B.w.y * rB.x)) - (A.v.z + (A.w.x * rA.y - A.w.y * rA.x));
+    return relX * dx + relY * dy + relZ * dz;
+}
+function solveTangentImpulse(bodies, invMass, invInertia, c, A, B, t, mass, acc, maxF) {
+    const vt = relativeVelocityAlong(A, B, c.rA, c.rB, t.x, t.y, t.z);
+    let dF = mass * -vt;
+    const clamped = clamp(acc + dF, -maxF, maxF);
+    dF = clamped - acc;
+    applyImpulseScalar(bodies, invMass, invInertia, c.a, c.b, c.rA, c.rB, t.x * dF, t.y * dF, t.z * dF, false);
+    return clamped;
+}
+function solveContactConstraint(bodies, invMass, invInertia, c, dt) {
+    const A = bodies[c.a];
+    const B = bodies[c.b];
+    // normal (no Baumgarte — position error handled by split impulse)
+    const vn = relativeVelocityAlong(A, B, c.rA, c.rB, c.normal.x, c.normal.y, c.normal.z);
+    const restThreshold = SOLVER_CONSTANTS.RESTITUTION_THRESHOLD;
+    const restBias = vn < -restThreshold ? -c.restitution * vn : 0;
+    // speculative points: allow closing up to the gap, never push apart.
+    const speculativeBias = c.speculative ? c.penetration / dt : 0;
+    let dLambda = c.massN * (-(vn) + restBias + speculativeBias);
+    const newAcc = Math.max(0, c.accN + dLambda);
+    dLambda = newAcc - c.accN;
+    c.accN = newAcc;
+    applyImpulseScalar(bodies, invMass, invInertia, c.a, c.b, c.rA, c.rB, c.normal.x * dLambda, c.normal.y * dLambda, c.normal.z * dLambda, false);
+    // split-impulse position bias (skip speculative points).
+    if (!c.speculative) {
+        const relbX = (B.vb.x + (B.wb.y * c.rB.z - B.wb.z * c.rB.y)) - (A.vb.x + (A.wb.y * c.rA.z - A.wb.z * c.rA.y));
+        const relbY = (B.vb.y + (B.wb.z * c.rB.x - B.wb.x * c.rB.z)) - (A.vb.y + (A.wb.z * c.rA.x - A.wb.x * c.rA.z));
+        const relbZ = (B.vb.z + (B.wb.x * c.rB.y - B.wb.y * c.rB.x)) - (A.vb.z + (A.wb.x * c.rA.y - A.wb.y * c.rA.x));
+        const vnb = relbX * c.normal.x + relbY * c.normal.y + relbZ * c.normal.z;
+        let dLb = c.massN * (c.bias - vnb);
+        const newAccNb = Math.max(0, c.accNb + dLb);
+        dLb = newAccNb - c.accNb;
+        c.accNb = newAccNb;
+        applyImpulseScalar(bodies, invMass, invInertia, c.a, c.b, c.rA, c.rB, c.normal.x * dLb, c.normal.y * dLb, c.normal.z * dLb, true);
+    }
+    // friction (skip for pure speculative points).
+    if (c.speculative) {
+        return;
+    }
+    const maxF = c.mu * c.accN;
+    c.accT1 = solveTangentImpulse(bodies, invMass, invInertia, c, A, B, c.t1, c.massT1, c.accT1, maxF);
+    c.accT2 = solveTangentImpulse(bodies, invMass, invInertia, c, A, B, c.t2, c.massT2, c.accT2, maxF);
+}
+function islandSleep(bodies, manifolds, joints) {
+    const parent = new Map();
+    const find = (i) => {
+        let r = i;
+        while (parent.get(r) !== r) {
+            r = parent.get(r);
+        }
+        return r;
+    };
+    for (let i = 0; i < bodies.length; i += 1) {
+        if (solid(bodies[i])) {
+            parent.set(i, i);
+        }
+    }
+    const link = (a, b) => {
+        if (solid(bodies[a]) && solid(bodies[b])) {
+            parent.set(find(a), find(b));
+        }
+    };
+    for (const m of manifolds) {
+        link(m.a, m.b);
+    }
+    for (const joint of joints) {
+        for (let i = 1; i < joint.bodyIndices.length; i += 1) {
+            link(joint.bodyIndices[0], joint.bodyIndices[i]);
+        }
+    }
+    const islandReady = new Map();
+    for (const i of [...parent.keys()].sort((l, r) => l - r)) {
+        const root = find(i);
+        const ready = bodies[i].lowVelFrames >= SOLVER_CONSTANTS.SLEEP_FRAMES;
+        islandReady.set(root, (islandReady.get(root) ?? true) && ready);
+    }
+    for (const i of [...parent.keys()].sort((l, r) => l - r)) {
+        if (islandReady.get(find(i)) === true) {
+            const b = bodies[i];
+            b.sleeping = true;
+            b.v = { x: 0, y: 0, z: 0 };
+            b.w = { x: 0, y: 0, z: 0 };
+        }
+    }
+}
+export const __solverInternals = { closestPointOnSegment, closestSegmentSegment, closestPointOnTriangle, triangleNormal };