@woosh/meep-engine 3.38.0 → 3.40.0

package/src/engine/physics/constraint/solve_constraints.js

@@ -1,7 +1,9 @@
+import { assert } from "../../../core/assert.js";
 import { apply_impulse_to_body } from "../solver/apply_impulse_to_body.js";
-import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
-import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
-import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { quat3_multiply_array } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
+import { quat3_to_matrix3_array } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
+import { v3_quaternion_apply_array } from "../../../core/geom/vec3/v3_quaternion_apply.js";
+import { TRANSFORM64_ROTATION_OFFSET } from "../../ecs/transform/Transform64.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import {
     SBS_AV_X,
@@ -22,17 +24,48 @@ import {
 } from "../body/SolverBodyState.js";
 import { JOINT_WORLD } from "../ecs/Joint.js";
 import { SleepState } from "../ecs/SleepState.js";
-import { angular_effective_mass_raw, world_inverse_inertia_apply_raw } from "../inertia/world_inverse_inertia.js";
+import { angular_effective_mass_array, world_inverse_inertia_apply_array } from "../inertia/world_inverse_inertia.js";
 import { DofMode } from "./DofMode.js";
 
 /**
  * # 6-DOF constraint (joint) solver
  *
- * Runs alongside the contact solver inside the same TGS substep loop: each
- * substep the joints are warm-started and their velocity rows solved, sharing
- * the contact solver's per-substep / warm-start / SPOOK-bias model so the two
- * constraint families converge together (a body touched by both a contact and
- * a joint sees a single coupled Gauss-Seidel sweep across the substep loop).
+ * Runs alongside the contact solver inside the same TGS substep loop, sharing
+ * its per-substep / warm-start / SPOOK-bias model so the two constraint
+ * families converge together (a body touched by both a contact and a joint
+ * sees a single coupled Gauss-Seidel sweep across the substep loop). Each
+ * substep, after the contact velocity solve, {@link solve_joints} prepares
+ * every joint's rows at the current poses, warm-starts them and runs
+ * `iters` passes over ALL the joints; after the position integrate,
+ * {@link relax_joints} re-solves the one-sided and driven rows without their
+ * position-correction bias (Box3D's substep order: solve → integrate → relax).
+ *
+ * ## An iteration is a pass over every joint
+ *
+ * The joints of a chain load each other: each one carries the links below it,
+ * so a joint's impulse is only right once its neighbours have answered it.
+ * Gauss-Seidel converges that only when an iteration sweeps the whole joint
+ * set and the sweep repeats. Iterating one joint to completion before moving
+ * to the next buys nothing (a fully locked point is solved exactly in one
+ * step) and leaves every joint blind to the load the later ones put on it — a
+ * heavy-tipped chain tears open by metres. The rows' constant parts are
+ * prepared once per substep into retained typed arrays, so a pass is row
+ * arithmetic only.
+ *
+ * ## The relax pass
+ *
+ * The position-correction bias of the biased passes is a velocity. A one-sided
+ * LIMITED row that pushed its DOF out of violation can never take that push
+ * back — its clamp forbids the opposite impulse — so the DOF coasts across its
+ * range onto the far stop. After the pose has taken the correction, the relax
+ * pass re-solves the LIMITED rows against their velocity target alone (the
+ * speculative, in-range term), which removes the push. Motors and springs are
+ * drives, not corrections, and solve the same in both. LOCKED rows are not
+ * relaxed: they are bilateral, so the next substep's biased solve re-targets
+ * their velocity outright and their correction never accumulates — and
+ * relaxing them, unlike Box3D (whose rows are soft), widened the settle tail of
+ * a jointed assembly (see {@link relax_joints}). The relax reuses the
+ * substep's prepared rows.
  *
  * A joint is a configurable 6-DOF constraint ({@link Joint}); each relative
  * degree of freedom is independently locked / free / limited / springy /
@@ -58,10 +91,11 @@ import { DofMode } from "./DofMode.js";
  *     it a unilateral push-out-of-violation constraint, exactly like a contact
  *     normal — the limit can only resist crossing the stop, never pull the DOF
  *     back into range.
- * The warm-start and the iteration loop are mode-agnostic; they read the
- * per-DOF `(active, effMass, bias, clampLo, clampHi)` filled by the mode-aware
- * setup. Geometry (anchors / lever arms / position error) is recomputed from
- * the current pose every substep, so the joint tracks the bodies as they move.
+ * The warm-start, the passes and the relax are mode-agnostic; they read the
+ * per-DOF `(active, relaxes, effMass, bias, relaxBias, clampLo, clampHi, γ)`
+ * the mode-aware setup prepared. Geometry (anchors / lever arms / position error)
+ * is recomputed from the current pose every substep, so the joint tracks the
+ * bodies as they move.
  *
  * The "position" along a DOF is `C · axis` for linear (signed anchor offset in
  * metres) and `e · axis` for angular, where `e = 2·sign(qD.w)·qD.xyz` is the
@@ -100,29 +134,87 @@ const MAX_JOINT_BIAS = 4;
 const JOINT_BAUMGARTE = 0.2;
 
 const scratch_inertia = new Float64Array(3);
-const scratch_anchor = new Float64Array(3);
+/**
+ * The impulse a row applies, for {@link apply_impulse_to_body} and {@link apply_angular_impulse}, which
+ * take it in an array.
+ */
+const scratch_impulse = new Float64Array(3);
 /** Frame-A world basis (rows = A's frame axes in world), from quat3_to_matrix3. */
 const scratch_frame_a = new Float64Array(9);
-/** Scratch quaternion for frame composition / relative rotation. */
+/** Scratch quaternion: frame A's world rotation, then the relative rotation `qD`. */
 const scratch_q = new Float64Array(4);
+/** The operands of `qD = conj(qA) ⊗ qB`: `conj(qA)` at 0, `qB` at 4. */
+const scratch_rel = new Float64Array(8);
 /** Angular position error `e` per frame axis (frame-A-local small-angle vector). */
 const scratch_ang_err = new Float64Array(3);
+/** One row's effective-mass denominator, body A's part at 0 and body B's at 1. */
+const scratch_keff = new Float64Array(2);
+
+// The numbers {@link fill_row} is given for one DOF, at these offsets in `scratch_dof`. They are computed
+// per row, and a computed number handed to a call that is not inlined (fill_row is past V8's inlining
+// limit) is boxed into a new heap object; read from an array, it is not.
+const DOF_KEFF = 0;          // raw effective-mass denominator K
+const DOF_POS = 1;           // signed DOF position
+const DOF_VEL = 2;           // signed DOF velocity
+const scratch_dof = new Float64Array(3);
+
+// ── Prepared rows ────────────────────────────────────────────────────────────
+// solve_joints prepares each joint once per substep — geometry at the
+// substep's start pose plus the mode-derived row parameters — into a slot
+// (the joint's index in the solve-order array); every pass after that, and
+// relax_joints, reads the slot back. Retained and grown geometrically, so a
+// steady joint count allocates nothing per step.
+
+// Per-slot doubles.
+const PREP_R_A = 0;          // lever arm rA = R_A·localAnchorA (3)
+const PREP_R_B = 3;          // lever arm rB (3; zero for a world anchor)
+const PREP_FRAME = 6;        // frame-A world basis, rows = axes (9)
+const PREP_K_INV = 15;       // inverse point block [00,01,02,11,12,22] (6)
+const PREP_ROWS = 21;        // 6 rows × ROW_STRIDE: linear axes 0..2, angular axes 3..5
+
+// Per-row doubles, at PREP_ROWS + row·ROW_STRIDE. The linear rows drive
+// dofImpulse[0..2], the angular rows dofImpulse[3..5].
+const ROW_EFF = 0;           // effective mass 1/K (1/(K+γ) for a spring)
+const ROW_BIAS = 1;          // velocity bias of the biased passes
+const ROW_RELAX_BIAS = 2;    // velocity bias of the relax pass
+const ROW_CLAMP_LO = 3;      // accumulated-impulse clamp
+const ROW_CLAMP_HI = 4;
+const ROW_GAMMA = 5;         // spring regularisation γ (0 for every other mode)
+const ROW_STRIDE = 6;
+
+const PREP_STRIDE = PREP_ROWS + 6 * ROW_STRIDE;
 
-// Per-DOF row parameters, filled per joint by the mode-aware setup and consumed
-// by the mode-agnostic warm-start + iteration. Indexed 0..2 (the three frame
-// axes); the linear set drives imp[0..2], the angular set drives imp[3..5].
-const lin_active = new Uint8Array(3);
-const lin_eff = new Float64Array(3);
-const lin_bias = new Float64Array(3);
-const lin_clo = new Float64Array(3);
-const lin_chi = new Float64Array(3);
-const lin_gamma = new Float64Array(3);
-const ang_active = new Uint8Array(3);
-const ang_eff = new Float64Array(3);
-const ang_bias = new Float64Array(3);
-const ang_clo = new Float64Array(3);
-const ang_chi = new Float64Array(3);
-const ang_gamma = new Float64Array(3);
+// Per-slot flags.
+const PREP_LIVE = 1;          // prepared, with at least one active row
+const PREP_TO_WORLD = 2;      // B is a fixed world anchor
+const PREP_POINT_BLOCK = 4;   // linear triple solved as one 3×3 block (A2)
+const PREP_ROW_ACTIVE = 8;    // row r is active: PREP_ROW_ACTIVE << r
+const PREP_LINEAR_ROWS = PREP_ROW_ACTIVE | (PREP_ROW_ACTIVE << 1) | (PREP_ROW_ACTIVE << 2);
+const PREP_ANY_ROW = PREP_LINEAR_ROWS | (PREP_LINEAR_ROWS << 3);
+const PREP_ROW_RELAX = PREP_ROW_ACTIVE << 6; // active row r takes part in the relax: PREP_ROW_RELAX << r
+const PREP_ANY_RELAX = PREP_ANY_ROW << 6;
+
+let prep_capacity = 0;
+let prep_data = new Float64Array(0);
+/** Per slot `[idxA, idxB]`: the bodies' indices (idxB −1 for a world anchor). */
+let prep_body = new Int32Array(0);
+let prep_flags = new Uint16Array(0);
+/** Slots prepared by the last {@link solve_joints}; {@link relax_joints} sweeps them. */
+let prep_count = 0;
+
+/**
+ * Make room for `n` prepared slots. Contents are not kept: every slot is
+ * re-prepared at the start of the substep that needs it.
+ * @param {number} n
+ */
+function ensure_prep_capacity(n) {
+    if (n <= prep_capacity) return;
+    const capacity = Math.max(n, prep_capacity * 2, 16);
+    prep_data = new Float64Array(capacity * PREP_STRIDE);
+    prep_body = new Int32Array(capacity * 2);
+    prep_flags = new Uint16Array(capacity);
+    prep_capacity = capacity;
+}
 
 // A2 (block solve) scratch: the coupled 3×3 effective-mass of a fully-LOCKED
 // linear point constraint and its inverse, stored as the 6 symmetric entries
@@ -133,76 +225,89 @@ const lin_Kinv = new Float64Array(6);
 const block_c = new Float64Array(9);
 const block_w = new Float64Array(9);
 
+// The helpers below take the axis, lever and impulse vectors in arrays and write any number they
+// produce into one: none of them is inlined everywhere it is called, and a number that crosses a call
+// that is not inlined, in or out, is boxed into a new heap object.
+
 /**
  * Angular effective-mass contribution of one body about a unit world axis:
- * `a · Iw⁻¹ · a`. Zero for non-dynamic / rotation-locked bodies (whose
+ * `a · Iw⁻¹ · a`, written to `out[out_offset]`. Zero for non-dynamic / rotation-locked bodies (whose
  * {@link SolverBodyState} inverse-inertia diagonal is zero).
+ * @param {Float64Array} out
+ * @param {number} out_offset
  * @param {Float64Array} ss solver-body-state data array
  * @param {number} base `body_index * SBS_STRIDE`
- * @param {number} ax  unit world axis x
- * @param {number} ay  unit world axis y
- * @param {number} az  unit world axis z
- * @returns {number}
+ * @param {Float64Array} axis unit world axis
+ * @param {number} axis_offset
  */
-function angular_axis_effective_mass(ss, base, ax, ay, az) {
+function angular_axis_effective_mass(out, out_offset, ss, base, axis, axis_offset) {
     const iix = ss[base + SBS_INV_I_X], iiy = ss[base + SBS_INV_I_Y], iiz = ss[base + SBS_INV_I_Z];
-    if (iix === 0 && iiy === 0 && iiz === 0) return 0;
-    world_inverse_inertia_apply_raw(scratch_inertia, 0, iix, iiy, iiz,
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW], ax, ay, az);
-    return ax * scratch_inertia[0] + ay * scratch_inertia[1] + az * scratch_inertia[2];
+    if (iix === 0 && iiy === 0 && iiz === 0) {
+        out[out_offset] = 0;
+        return;
+    }
+    world_inverse_inertia_apply_array(scratch_inertia, 0, ss, base + SBS_INV_I_X, ss, base + SBS_QX, axis, axis_offset);
+    out[out_offset] = axis[axis_offset] * scratch_inertia[0]
+        + axis[axis_offset + 1] * scratch_inertia[1]
+        + axis[axis_offset + 2] * scratch_inertia[2];
 }
 
 /**
- * Apply a pure angular impulse `sign·λ·axis`: Δω = Iw⁻¹·(sign·λ·axis).
+ * Apply a pure angular impulse `sign·L`: Δω = Iw⁻¹·(sign·L).
  * @param {Float64Array} ss solver-body-state data array
  * @param {number} base `body_index * SBS_STRIDE`
- * @param {number} ax
- * @param {number} ay
- * @param {number} az
- * @param {number} lambda
- * @param {number} sign
+ * @param {Float64Array} impulse the angular impulse `L`
+ * @param {number} impulse_offset
+ * @param {number} sign +1 or −1
  */
-function apply_angular_impulse(ss, base, ax, ay, az, lambda, sign) {
+function apply_angular_impulse(ss, base, impulse, impulse_offset, sign) {
     const iix = ss[base + SBS_INV_I_X], iiy = ss[base + SBS_INV_I_Y], iiz = ss[base + SBS_INV_I_Z];
     if (iix === 0 && iiy === 0 && iiz === 0) return;
-    const L = sign * lambda;
-    world_inverse_inertia_apply_raw(scratch_inertia, 0, iix, iiy, iiz,
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW], ax * L, ay * L, az * L);
-    ss[base + SBS_AV_X] += scratch_inertia[0];
-    ss[base + SBS_AV_Y] += scratch_inertia[1];
-    ss[base + SBS_AV_Z] += scratch_inertia[2];
+    const w = scratch_inertia;
+    w[0] = sign * impulse[impulse_offset];
+    w[1] = sign * impulse[impulse_offset + 1];
+    w[2] = sign * impulse[impulse_offset + 2];
+    world_inverse_inertia_apply_array(w, 0, ss, base + SBS_INV_I_X, ss, base + SBS_QX, w, 0);
+    ss[base + SBS_AV_X] += w[0];
+    ss[base + SBS_AV_Y] += w[1];
+    ss[base + SBS_AV_Z] += w[2];
 }
 
 /**
  * Effective-mass denominator contribution of one body along a unit axis:
- * `invM + (r×d)·Iw⁻¹·(r×d)`. Static / kinematic bodies (invM === 0) contribute
- * nothing.
+ * `invM + (r×d)·Iw⁻¹·(r×d)`, written to `out[out_offset]`. Static / kinematic bodies (invM === 0)
+ * contribute nothing.
  *
+ * @param {Float64Array} out
+ * @param {number} out_offset
  * @param {Float64Array} ss solver-body-state data array
  * @param {number} base `body_index * SBS_STRIDE`
- * @param {number} invM
- * @param {number} rx
- * @param {number} ry
- * @param {number} rz
- * @param {number} dx
- * @param {number} dy
- * @param {number} dz
- * @returns {number}
+ * @param {Float64Array} lever the lever arm `r`
+ * @param {number} lever_offset
+ * @param {Float64Array} axis the unit axis `d`
+ * @param {number} axis_offset
  */
-function axis_effective_mass(ss, base, invM, rx, ry, rz, dx, dy, dz) {
-    if (invM === 0) return 0;
+function axis_effective_mass(out, out_offset, ss, base, lever, lever_offset, axis, axis_offset) {
+    const invM = ss[base + SBS_INV_MASS];
+    if (invM === 0) {
+        out[out_offset] = 0;
+        return;
+    }
     const iix = ss[base + SBS_INV_I_X], iiy = ss[base + SBS_INV_I_Y], iiz = ss[base + SBS_INV_I_Z];
     if (iix === 0 && iiy === 0 && iiz === 0) {
         // no rotational response, so the lever arm contributes nothing
-        return invM;
+        out[out_offset] = invM;
+        return;
     }
-    return invM + angular_effective_mass_raw(
-        iix, iiy, iiz,
-        ss[base + SBS_QX], ss[base + SBS_QY], ss[base + SBS_QZ], ss[base + SBS_QW],
-        rx, ry, rz,
-        dx, dy, dz,
+    angular_effective_mass_array(
+        out, out_offset,
+        ss, base + SBS_INV_I_X,
+        ss, base + SBS_QX,
+        lever, lever_offset,
+        axis, axis_offset,
         scratch_inertia
     );
+    out[out_offset] = invM + out[out_offset];
 }
 
 /**
@@ -216,16 +321,16 @@ function axis_effective_mass(ss, base, invM, rx, ry, rz, dx, dy, dz) {
  * @param {Float64Array} out length >= 3
  * @param {Float64Array} ss solver-body-state data
  * @param {number} baseA
- * @param {number} rAx
- * @param {number} rAy
- * @param {number} rAz anchor lever on A
+ * @param {Float64Array} lever_a anchor lever on A
+ * @param {number} lever_a_offset
  * @param {number} baseB
- * @param {number} rBx
- * @param {number} rBy
- * @param {number} rBz anchor lever on B
+ * @param {Float64Array} lever_b anchor lever on B, read even for a world anchor
+ * @param {number} lever_b_offset
  * @param {boolean} to_world B is a fixed world anchor (no B term)
  */
-function relative_anchor_velocity(out, ss, baseA, rAx, rAy, rAz, baseB, rBx, rBy, rBz, to_world) {
+function relative_anchor_velocity(out, ss, baseA, lever_a, lever_a_offset, baseB, lever_b, lever_b_offset, to_world) {
+    const rAx = lever_a[lever_a_offset], rAy = lever_a[lever_a_offset + 1], rAz = lever_a[lever_a_offset + 2];
+    const rBx = lever_b[lever_b_offset], rBy = lever_b[lever_b_offset + 1], rBz = lever_b[lever_b_offset + 2];
     out[0] = (ss[baseA + SBS_LV_X] + ss[baseA + SBS_AV_Y] * rAz - ss[baseA + SBS_AV_Z] * rAy) - (to_world ? 0 : (ss[baseB + SBS_LV_X] + ss[baseB + SBS_AV_Y] * rBz - ss[baseB + SBS_AV_Z] * rBy));
     out[1] = (ss[baseA + SBS_LV_Y] + ss[baseA + SBS_AV_Z] * rAx - ss[baseA + SBS_AV_X] * rAz) - (to_world ? 0 : (ss[baseB + SBS_LV_Y] + ss[baseB + SBS_AV_Z] * rBx - ss[baseB + SBS_AV_X] * rBz));
     out[2] = (ss[baseA + SBS_LV_Z] + ss[baseA + SBS_AV_X] * rAy - ss[baseA + SBS_AV_Y] * rAx) - (to_world ? 0 : (ss[baseB + SBS_LV_Z] + ss[baseB + SBS_AV_X] * rBy - ss[baseB + SBS_AV_Y] * rBx));
@@ -255,21 +360,20 @@ function clamp_bias(b) {
  *
  * @param {Float64Array} ss
  * @param {number} base
- * @param {number} rx  lever arm x
- * @param {number} ry  lever arm y
- * @param {number} rz  lever arm z
+ * @param {Float64Array} lever  lever arm `r`
+ * @param {number} lever_offset
  * @param {Float64Array} fa  frame-A world basis (rows = axes)
  * @param {Float64Array} K   length-6 symmetric accumulator [00,01,02,11,12,22]
  */
-function accumulate_point_block(ss, base, rx, ry, rz, fa, K) {
+function accumulate_point_block(ss, base, lever, lever_offset, fa, K) {
     const iix = ss[base + SBS_INV_I_X], iiy = ss[base + SBS_INV_I_Y], iiz = ss[base + SBS_INV_I_Z];
     if (iix === 0 && iiy === 0 && iiz === 0) return;
-    const qx = ss[base + SBS_QX], qy = ss[base + SBS_QY], qz = ss[base + SBS_QZ], qw = ss[base + SBS_QW];
+    const rx = lever[lever_offset], ry = lever[lever_offset + 1], rz = lever[lever_offset + 2];
     for (let k = 0; k < 3; k++) {
         const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
         const cx = ry * az - rz * ay, cy = rz * ax - rx * az, cz = rx * ay - ry * ax;
         block_c[3 * k] = cx; block_c[3 * k + 1] = cy; block_c[3 * k + 2] = cz;
-        world_inverse_inertia_apply_raw(block_w, 3 * k, iix, iiy, iiz, qx, qy, qz, qw, cx, cy, cz);
+        world_inverse_inertia_apply_array(block_w, 3 * k, ss, base + SBS_INV_I_X, ss, base + SBS_QX, block_c, 3 * k);
     }
     K[0] += block_c[0] * block_w[0] + block_c[1] * block_w[1] + block_c[2] * block_w[2];
     K[1] += block_c[0] * block_w[3] + block_c[1] * block_w[4] + block_c[2] * block_w[5];
@@ -281,24 +385,25 @@ function accumulate_point_block(ss, base, rx, ry, rz, fa, K) {
 
 /**
  * Invert a symmetric positive-definite 3×3 (6-entry form) in closed form,
- * writing the inverse (same 6-entry form) to `out`. Returns the determinant; a
- * near-singular block (|det| < 1e-12) returns 0 and leaves `out` untouched so
- * the caller falls back to the per-axis solve.
+ * writing the inverse (same 6-entry form) to `out`. A near-singular block
+ * (|det| < 1e-12) returns false and leaves `out` untouched so the caller falls
+ * back to the per-axis solve. (It returns no determinant: the caller has no use
+ * for it, and a number returned from a call that is not inlined is boxed.)
  *
  * @param {Float64Array} K  [00,01,02,11,12,22]
  * @param {Float64Array} out
- * @returns {number} determinant
+ * @returns {boolean} whether `out` holds the inverse
  */
 function invert_sym3(K, out) {
     const a = K[0], b = K[1], c = K[2], d = K[3], e = K[4], f = K[5];
     const A00 = d * f - e * e, A01 = c * e - b * f, A02 = b * e - c * d;
     const A11 = a * f - c * c, A12 = b * c - a * e, A22 = a * d - b * b;
     const det = a * A00 + b * A01 + c * A02;
-    if (det < 1e-12 && det > -1e-12) return 0;
+    if (det < 1e-12 && det > -1e-12) return false;
     const inv = 1 / det;
     out[0] = A00 * inv; out[1] = A01 * inv; out[2] = A02 * inv;
     out[3] = A11 * inv; out[4] = A12 * inv; out[5] = A22 * inv;
-    return det;
+    return true;
 }
 
 /**
@@ -326,6 +431,31 @@ function invert_sym3(K, out) {
  * @param {Float64Array} out  length-3 destination (frame-axis positions)
  */
 export function swing_twist_error(dx, dy, dz, dw, out) {
+    const q = swing_twist_inputs;
+
+    q[0] = dx;
+    q[1] = dy;
+    q[2] = dz;
+    q[3] = dw;
+
+    swing_twist_error_array(q, 0, out);
+}
+
+/** Where {@link swing_twist_error} packs its quaternion. */
+const swing_twist_inputs = new Float64Array(4);
+
+/**
+ * {@link swing_twist_error} with `qD` read from `q[q_offset ..+3]`, `[x, y, z, w]`: the one place the
+ * arithmetic lives. For a caller whose inlining budget is spent, where a call taking the four numbers
+ * would box each into a new heap object.
+ *
+ * @param {Float64Array} q
+ * @param {number} q_offset
+ * @param {Float64Array} out  length-3 destination (frame-axis positions)
+ */
+export function swing_twist_error_array(q, q_offset, out) {
+    let dx = q[q_offset], dy = q[q_offset + 1], dz = q[q_offset + 2], dw = q[q_offset + 3];
+
     // Shortest arc: work with the hemisphere where dw ≥ 0.
     if (dw < 0) { dx = -dx; dy = -dy; dz = -dz; dw = -dw; }
 
@@ -363,9 +493,11 @@ export function swing_twist_error(dx, dy, dz, dw, out) {
  * Fill the row parameters for one DOF given its mode, signed position and
  * signed velocity.
  *
- * Writes `active / eff / bias / clampLo / clampHi` at index `k` of the supplied
- * arrays and, for LIMITED, resets the warm-start impulse when the active bound
- * flipped (a stale opposite-side impulse must not warm-start).
+ * Writes `eff / bias / clampLo / clampHi / γ` — and `relaxBias`, for every mode
+ * but LOCKED — into the prepared row at `out[o …]`, returns whether the row is
+ * active and, for LIMITED,
+ * resets the warm-start impulse when the active bound flipped (a stale
+ * opposite-side impulse must not warm-start).
  *
  * ## LIMITED is a speculative (β = 1) one-sided velocity constraint
  *
@@ -385,15 +517,11 @@ export function swing_twist_error(dx, dy, dz, dw, out) {
  * so a body teleported deep past a stop is eased out rather than yanked; the
  * gating side is left unbounded.
  *
- * KNOWN BUG (deferred — see Joint.spec.js "linear limit recovery", test.skip): the
- * push-out clamp caps the recovery bias to a CONSTANT velocity, which a one-sided
- * row cannot later remove (warm-start re-injects it, the clamp blocks removal), so
- * a DOF that starts OUTSIDE its range coasts across the whole travel and pins on the
- * OPPOSITE stop rather than easing onto the near one (the classic ragdoll-kicks-itself-
- * on-spawn). A scalar bias cannot fix this — the trace shows the injected velocity is
- * constant regardless of magnitude. The correct fix routes limit-penetration recovery
- * through a split-impulse / pseudo-velocity channel (as the contact solver's
- * solve_position does), which the joint solver does not yet have.
+ * The push-out velocity is the one part of the row the relax pass drops (its
+ * relax bias keeps only the speculative, in-range side): a one-sided row can
+ * never remove the velocity it pushed with — its clamp forbids the opposite
+ * impulse — so without the relax a DOF that starts OUTSIDE its range coasts
+ * across the whole travel and pins itself on the OPPOSITE stop.
  *
  * The active bound is the violated one, else — within range — the one the DOF
  * is moving toward (`vel` sign). LOCKED is unchanged: a bilateral row with a
@@ -427,42 +555,44 @@ export function swing_twist_error(dx, dy, dz, dw, out) {
  * element, and the soft basis for cone-twist later. The angular position uses
  * the same small-angle measure as LIMITED (good for modest ranges).
  *
+ * A motor or a spring is a drive, not a position correction, so its relax
+ * bias is its bias. A LOCKED row has none: it does not take part in the relax
+ * (see the module doc).
+ *
+ * The DOF's own numbers come in `dof`, at:
+ *   - `DOF_KEFF`, the raw effective-mass denominator `K` (0 ⇒ no row); the
+ *     row's effective mass is `1/K`, or `1/(K+γ)` softened for a spring;
+ *   - `DOF_POS`, the signed DOF position (`C·axis` linear / `e·axis` angular);
+ *   - `DOF_VEL`, the signed DOF velocity along the same axis (selects the
+ *     approached bound for an in-range LIMITED DOF).
+ *
  * @param {Joint} joint   the joint (per-DOF config + warm-start impulse read here)
  * @param {number} dofIndex  DOF 0..5 (selects mode / limits / motor / imp slot)
- * @param {number} k      axis index 0..2 (output-array slot for this DOF group)
- * @param {number} keff   raw effective-mass denominator `K` (0 ⇒ no row); the
- *   row's effective mass is `1/K`, or `1/(K+γ)` softened for a spring.
- * @param {number} pos    signed DOF position (`C·axis` linear / `e·axis` angular)
- * @param {number} vel    signed DOF velocity along the same axis (selects the
- *   approached bound for an in-range LIMITED DOF)
+ * @param {Float64Array} dof  the DOF's `K`, position and velocity
  * @param {number} spook_locked  Baumgarte gain `β / dt_sub` (LOCKED)
  * @param {number} spook_spec    speculative gain `1 / dt_sub` (LIMITED)
  * @param {number} dt_sub  substep size (MOTOR impulse cap = `maxForce·dt_sub`;
  *   SPRING compliance derives from it)
- * @param {Uint8Array} active
- * @param {Float64Array} effOut
- * @param {Float64Array} biasOut
- * @param {Float64Array} cloOut
- * @param {Float64Array} chiOut
- * @param {Float64Array} gammaOut  per-row regularisation (0 for non-spring rows)
+ * @param {Float64Array} out  prepared-row storage
+ * @param {number} o  offset of this DOF's row in `out` (ROW_* fields follow it)
+ * @returns {boolean} whether the row is active this substep
  */
-function fill_row(joint, dofIndex, k, keff, pos, vel, spook_locked, spook_spec, dt_sub,
-                  active, effOut, biasOut, cloOut, chiOut, gammaOut) {
+function fill_row(joint, dofIndex, dof, spook_locked, spook_spec, dt_sub, out, o) {
+    const keff = dof[DOF_KEFF], pos = dof[DOF_POS], vel = dof[DOF_VEL];
     const mode = joint.dofMode[dofIndex];
     const imp = joint.dofImpulse;
 
     if (mode === DofMode.LOCKED) {
-        if (keff === 0) { active[k] = 0; return; }
-        effOut[k] = 1 / keff;
-        biasOut[k] = clamp_bias(spook_locked * pos);
-        cloOut[k] = -Infinity;
-        chiOut[k] = Infinity;
-        gammaOut[k] = 0;
-        active[k] = 1;
-        return;
+        if (keff === 0) return false;
+        out[o + ROW_EFF] = 1 / keff;
+        out[o + ROW_BIAS] = clamp_bias(spook_locked * pos);
+        out[o + ROW_CLAMP_LO] = -Infinity;
+        out[o + ROW_CLAMP_HI] = Infinity;
+        out[o + ROW_GAMMA] = 0;
+        return true;
     }
     if (mode === DofMode.LIMITED) {
-        if (keff === 0) { imp[dofIndex] = 0; active[k] = 0; return; }
+        if (keff === 0) { imp[dofIndex] = 0; return false; }
         const lower = joint.dofLowerLimit[dofIndex];
         const upper = joint.dofUpperLimit[dofIndex];
         // Select the bound: the violated one, else the one being approached.
@@ -475,361 +605,505 @@ function fill_row(joint, dofIndex, k, keff, pos, vel, spook_locked, spook_spec,
         if (lower_side) {
             // Lower stop: impulse pushes the DOF up (+), clamp [0, +∞). The
             // push-out side of the bias is the negative one — bound it.
-            cloOut[k] = 0; chiOut[k] = Infinity;
+            out[o + ROW_CLAMP_LO] = 0; out[o + ROW_CLAMP_HI] = Infinity;
             if (imp[dofIndex] < 0) imp[dofIndex] = 0; // drop stale upper-side impulse
             if (b < -MAX_JOINT_BIAS) b = -MAX_JOINT_BIAS;
+            out[o + ROW_RELAX_BIAS] = b > 0 ? b : 0; // relax keeps the speculative side only
         } else {
             // Upper stop: impulse pushes the DOF down (−), clamp (−∞, 0]. The
             // push-out side of the bias is the positive one — bound it.
-            cloOut[k] = -Infinity; chiOut[k] = 0;
+            out[o + ROW_CLAMP_LO] = -Infinity; out[o + ROW_CLAMP_HI] = 0;
             if (imp[dofIndex] > 0) imp[dofIndex] = 0; // drop stale lower-side impulse
             if (b > MAX_JOINT_BIAS) b = MAX_JOINT_BIAS;
+            out[o + ROW_RELAX_BIAS] = b < 0 ? b : 0;
         }
-        effOut[k] = 1 / keff;
-        biasOut[k] = b;
-        gammaOut[k] = 0;
-        active[k] = 1;
-        return;
+        out[o + ROW_EFF] = 1 / keff;
+        out[o + ROW_BIAS] = b;
+        out[o + ROW_GAMMA] = 0;
+        return true;
     }
     if (mode === DofMode.MOTOR) {
-        if (keff === 0) { imp[dofIndex] = 0; active[k] = 0; return; }
+        if (keff === 0) { imp[dofIndex] = 0; return false; }
         const maxImpulse = joint.dofMotorMaxForce[dofIndex] * dt_sub;
-        if (maxImpulse <= 0) { imp[dofIndex] = 0; active[k] = 0; return; }
-        effOut[k] = 1 / keff;
+        if (maxImpulse <= 0) { imp[dofIndex] = 0; return false; }
+        out[o + ROW_EFF] = 1 / keff;
         // Drive the relative velocity to the target: λ = −eff·(vrel − target).
-        biasOut[k] = -joint.dofMotorTargetVelocity[dofIndex];
-        cloOut[k] = -maxImpulse;
-        chiOut[k] = maxImpulse;
-        gammaOut[k] = 0;
-        active[k] = 1;
-        return;
+        out[o + ROW_BIAS] = out[o + ROW_RELAX_BIAS] = -joint.dofMotorTargetVelocity[dofIndex];
+        out[o + ROW_CLAMP_LO] = -maxImpulse;
+        out[o + ROW_CLAMP_HI] = maxImpulse;
+        out[o + ROW_GAMMA] = 0;
+        return true;
     }
     if (mode === DofMode.SPRING) {
-        if (keff === 0) { imp[dofIndex] = 0; active[k] = 0; return; }
+        if (keff === 0) { imp[dofIndex] = 0; return false; }
         const ks = joint.dofStiffness[dofIndex];
         const cs = joint.dofDamping[dofIndex];
         const denom = cs + dt_sub * ks;
-        if (denom <= 0) { imp[dofIndex] = 0; active[k] = 0; return; } // inert (no k, no c)
+        if (denom <= 0) { imp[dofIndex] = 0; return false; } // inert (no k, no c)
         const gamma = 1 / (dt_sub * denom);
-        effOut[k] = 1 / (keff + gamma);
-        biasOut[k] = (ks / denom) * pos; // restoring velocity toward pos = 0
-        cloOut[k] = -Infinity;
-        chiOut[k] = Infinity;
-        gammaOut[k] = gamma;
-        active[k] = 1;
-        return;
+        out[o + ROW_EFF] = 1 / (keff + gamma);
+        // restoring velocity toward pos = 0
+        out[o + ROW_BIAS] = out[o + ROW_RELAX_BIAS] = (ks / denom) * pos;
+        out[o + ROW_CLAMP_LO] = -Infinity;
+        out[o + ROW_CLAMP_HI] = Infinity;
+        out[o + ROW_GAMMA] = gamma;
+        return true;
     }
     // FREE: no row this substep.
     imp[dofIndex] = 0;
-    active[k] = 0;
+    return false;
 }
 
 /**
- * Solve every joint for one substep: recompute geometry at the current poses,
- * derive each DOF's row parameters from its mode, replay the per-substep
- * warm-start, and run `iters` velocity iterations.
- *
- * Called once per substep from `PhysicsSystem.fixedUpdate`, after the contact
- * solve so the two share the substep / warm-start cadence.
+ * Prepare one joint into slot `slot` for this substep: resolve its bodies,
+ * recompute anchors / lever arms / frame / position error at the current
+ * poses, and derive every DOF's row from its mode. The slot stays dead (the
+ * joint does nothing this substep) when a body is gone or asleep, neither
+ * body can move, or no row is active.
  *
- * @param {Joint[]} joints  live joints (sparse array; holes skipped)
+ * @param {number} slot  the joint's index in the solve-order array
+ * @param {Joint|undefined} joint
  * @param {PhysicsSystem} system  reads `__bodies` / `__transforms` / index map
- * @param {number} dt_sub  substep size in seconds (the SPOOK gain is derived
- *   from it, matching the contact solver's per-substep position stiffness)
- * @param {number} iters  velocity iterations
- * @param {boolean} [reverse]  A2: traverse the joint array tip→root this call
- *   (the caller alternates it per substep for a symmetric Gauss-Seidel sweep, so
- *   chain impulses propagate both ways). Default false ⇒ original root→tip order.
+ * @param {Float64Array} ss  solver-body-state data
+ * @param {number} dt_sub  substep size in seconds
+ * @param {number} spook_locked  Baumgarte gain `β / dt_sub` (LOCKED)
+ * @param {number} spook_spec  speculative gain `1 / dt_sub` (LIMITED)
+ * @returns {boolean} whether the slot is live
  */
-export function solve_joints(joints, system, dt_sub, iters, reverse) {
-    const n = joints.length;
-    if (n === 0 || dt_sub <= 0) return;
-
-    const spook_locked = JOINT_BAUMGARTE / dt_sub;
-    const spook_spec = 1 / dt_sub;
+function prepare_joint(slot, joint, system, ss, dt_sub, spook_locked, spook_spec) {
+    prep_flags[slot] = 0;
+    if (joint === undefined || joint === null) return false;
 
     const storage = system.storage;
-    const ss = system.__solver_state.data;
 
-    for (let jj = 0; jj < n; jj++) {
-        const ji = reverse ? (n - 1 - jj) : jj;
-        const joint = joints[ji];
-        if (joint === undefined || joint === null) continue;
-
-        // Generation-checked validity: if A's body was unlinked (and its slot
-        // possibly reused by a different body), the stored packed id no longer
-        // validates — skip the stale joint rather than attach to the wrong body.
-        if (!storage.is_valid(joint._bodyIdA)) continue;
-        const idxA = body_id_index(joint._bodyIdA);
-        const baseA = idxA * SBS_STRIDE;
-        const rbA = system.__bodies[idxA];
-        if (rbA === undefined) continue;
-        const trA = system.__transforms[idxA];
-
-        const to_world = joint._bodyIdB === JOINT_WORLD;
-        let rbB = null, trB = null, idxB = -1, baseB = -1;
-        if (!to_world) {
-            if (!storage.is_valid(joint._bodyIdB)) continue;
-            idxB = body_id_index(joint._bodyIdB);
-            baseB = idxB * SBS_STRIDE;
-            rbB = system.__bodies[idxB];
-            if (rbB === undefined) continue;
-            trB = system.__transforms[idxB];
-        }
+    // Generation-checked validity: if A's body was unlinked (and its slot
+    // possibly reused by a different body), the stored packed id no longer
+    // validates — skip the stale joint rather than attach to the wrong body.
+    if (!storage.is_valid(joint._bodyIdA)) return false;
+    const idxA = body_id_index(joint._bodyIdA);
+    const baseA = idxA * SBS_STRIDE;
+    const rbA = system.__bodies[idxA];
+    if (rbA === undefined) return false;
+    const trA = system.__transforms[idxA];
 
-        // Skip while a participating dynamic body sleeps — its velocity must
-        // stay zero until woken. (Island-aware joint sleep is a follow-up; for
-        // now jointed bodies that should stay coupled use DisableSleep.)
-        if (rbA.sleepState === SleepState.Sleeping) continue;
-        if (!to_world && rbB.sleepState === SleepState.Sleeping) continue;
-
-        // Both bodies static/kinematic → nothing to solve.
-        const invMA = ss[baseA + SBS_INV_MASS];
-        const invMB = to_world ? 0 : ss[baseB + SBS_INV_MASS];
-        if (invMA === 0 && invMB === 0) continue;
-
-        const mode = joint.dofMode;
-        const linConstrained = mode[0] !== DofMode.FREE || mode[1] !== DofMode.FREE || mode[2] !== DofMode.FREE;
-        const angConstrained = mode[3] !== DofMode.FREE || mode[4] !== DofMode.FREE || mode[5] !== DofMode.FREE;
-        if (!linConstrained && !angConstrained) continue;
-
-        // World anchor A and its lever arm rA = R_A · localAnchorA.
-        const la = joint.localAnchorA;
-        v3_quaternion_apply(scratch_anchor, 0, la[0], la[1], la[2],
-            trA.rotation_x, trA.rotation_y, trA.rotation_z, trA.rotation_w);
-        const rAx = scratch_anchor[0], rAy = scratch_anchor[1], rAz = scratch_anchor[2];
-        const anchorAx = trA.translation_x + rAx;
-        const anchorAy = trA.translation_y + rAy;
-        const anchorAz = trA.translation_z + rAz;
-
-        // World anchor B + lever arm rB. For a world anchor, localAnchorB is a
-        // fixed world point and there is no body B lever.
-        let rBx = 0, rBy = 0, rBz = 0;
-        let anchorBx, anchorBy, anchorBz;
-        const lb = joint.localAnchorB;
-        if (to_world) {
-            anchorBx = lb[0]; anchorBy = lb[1]; anchorBz = lb[2];
-        } else {
-            v3_quaternion_apply(scratch_anchor, 0, lb[0], lb[1], lb[2],
-                trB.rotation_x, trB.rotation_y, trB.rotation_z, trB.rotation_w);
-            rBx = scratch_anchor[0]; rBy = scratch_anchor[1]; rBz = scratch_anchor[2];
-            anchorBx = trB.translation_x + rBx;
-            anchorBy = trB.translation_y + rBy;
-            anchorBz = trB.translation_z + rBz;
-        }
+    const to_world = joint._bodyIdB === JOINT_WORLD;
+    let rbB = null, trB = null, idxB = -1, baseB = -1;
+    if (!to_world) {
+        if (!storage.is_valid(joint._bodyIdB)) return false;
+        idxB = body_id_index(joint._bodyIdB);
+        baseB = idxB * SBS_STRIDE;
+        rbB = system.__bodies[idxB];
+        if (rbB === undefined) return false;
+        trB = system.__transforms[idxB];
+    }
 
-        // Position error C = anchorA − anchorB (its projection on a frame axis
-        // is the signed DOF offset; locked axes drive it to zero, limited axes
-        // bound it).
-        const Cx = anchorAx - anchorBx;
-        const Cy = anchorAy - anchorBy;
-        const Cz = anchorAz - anchorBz;
-
-        const imp = joint.dofImpulse;
-
-        // === Frame A world axes — shared by the linear AND angular rows ===
-        // Every DOF is expressed in the joint's frame on body A. Frame A =
-        // body-A rotation ⊗ localBasisA; the rows of its matrix are the frame
-        // axes in world (see quat3_to_matrix3).
-        const lba = joint.localBasisA;
-        quat3_multiply(scratch_q, 0, trA.rotation_x, trA.rotation_y, trA.rotation_z, trA.rotation_w, lba[0], lba[1], lba[2], lba[3]);
-        const qAx = scratch_q[0], qAy = scratch_q[1], qAz = scratch_q[2], qAw = scratch_q[3];
-        quat3_to_matrix3(scratch_frame_a, 0, qAx, qAy, qAz, qAw);
-        const fa = scratch_frame_a;
-
-        // --- Linear DOF row setup (frame axes). Position along axis k is
-        //     `C · axis_k`; convention is A−B (impulse +to A / −to B). ---
-        let useLinBlock = false;
-        if (linConstrained) {
-            // A2: a fully-LOCKED linear triple is a ball-socket point — solve it
-            // as one coupled 3×3 block (frame axes) instead of axis-by-axis,
-            // removing the intra-joint coupling error the sequential per-axis
-            // Gauss-Seidel leaves behind. Falls back to per-axis if the block is
-            // near-singular.
-            if (mode[0] === DofMode.LOCKED && mode[1] === DofMode.LOCKED && mode[2] === DofMode.LOCKED) {
-                lin_K[0] = lin_K[3] = lin_K[5] = invMA + invMB;
-                lin_K[1] = lin_K[2] = lin_K[4] = 0;
-                accumulate_point_block(ss, baseA, rAx, rAy, rAz, fa, lin_K);
-                if (!to_world) accumulate_point_block(ss, baseB, rBx, rBy, rBz, fa, lin_K);
-                if (invert_sym3(lin_K, lin_Kinv) !== 0) {
-                    for (let k = 0; k < 3; k++) {
-                        const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
-                        lin_bias[k] = clamp_bias(spook_locked * (Cx * ax + Cy * ay + Cz * az));
-                        lin_active[k] = 1;
-                    }
-                    useLinBlock = true;
-                }
-            }
-            if (!useLinBlock) {
+    // Skip while a participating dynamic body sleeps — its velocity must
+    // stay zero until woken. (Island-aware joint sleep is a follow-up; for
+    // now jointed bodies that should stay coupled use DisableSleep.)
+    if (rbA.sleepState === SleepState.Sleeping) return false;
+    if (!to_world && rbB.sleepState === SleepState.Sleeping) return false;
+
+    // Both bodies static/kinematic → nothing to solve.
+    const invMA = ss[baseA + SBS_INV_MASS];
+    const invMB = to_world ? 0 : ss[baseB + SBS_INV_MASS];
+    if (invMA === 0 && invMB === 0) return false;
+
+    const mode = joint.dofMode;
+    const linConstrained = mode[0] !== DofMode.FREE || mode[1] !== DofMode.FREE || mode[2] !== DofMode.FREE;
+    const angConstrained = mode[3] !== DofMode.FREE || mode[4] !== DofMode.FREE || mode[5] !== DofMode.FREE;
+    if (!linConstrained && !angConstrained) return false;
+
+    const p = slot * PREP_STRIDE;
+    const pd = prep_data;
+    let flags = to_world ? PREP_TO_WORLD : 0;
+
+    // World anchor A and its lever arm rA = R_A · localAnchorA, written straight
+    // into the slot, where the rows read it (a slot left dead is never read).
+    const rA = p + PREP_R_A;
+    v3_quaternion_apply_array(pd, rA, joint.localAnchorA, 0, trA, TRANSFORM64_ROTATION_OFFSET);
+    const anchorAx = trA.translation_x + pd[rA];
+    const anchorAy = trA.translation_y + pd[rA + 1];
+    const anchorAz = trA.translation_z + pd[rA + 2];
+
+    // World anchor B + lever arm rB. For a world anchor, localAnchorB is a
+    // fixed world point and there is no body B lever.
+    const rB = p + PREP_R_B;
+    let anchorBx, anchorBy, anchorBz;
+    const lb = joint.localAnchorB;
+    if (to_world) {
+        pd[rB] = 0; pd[rB + 1] = 0; pd[rB + 2] = 0;
+        anchorBx = lb[0]; anchorBy = lb[1]; anchorBz = lb[2];
+    } else {
+        v3_quaternion_apply_array(pd, rB, lb, 0, trB, TRANSFORM64_ROTATION_OFFSET);
+        anchorBx = trB.translation_x + pd[rB];
+        anchorBy = trB.translation_y + pd[rB + 1];
+        anchorBz = trB.translation_z + pd[rB + 2];
+    }
+
+    // Position error C = anchorA − anchorB (its projection on a frame axis
+    // is the signed DOF offset; locked axes drive it to zero, limited axes
+    // bound it).
+    const Cx = anchorAx - anchorBx;
+    const Cy = anchorAy - anchorBy;
+    const Cz = anchorAz - anchorBz;
+
+    const imp = joint.dofImpulse;
+
+    // === Frame A world axes — shared by the linear AND angular rows ===
+    // Every DOF is expressed in the joint's frame on body A. Frame A =
+    // body-A rotation ⊗ localBasisA; the rows of its matrix are the frame
+    // axes in world (see quat3_to_matrix3).
+    quat3_multiply_array(scratch_q, 0, trA, TRANSFORM64_ROTATION_OFFSET, joint.localBasisA, 0);
+    quat3_to_matrix3_array(scratch_frame_a, 0, scratch_q, 0);
+    const fa = scratch_frame_a;
+    const dof = scratch_dof;
+    const keff = scratch_keff;
+
+    // --- Linear DOF row setup (frame axes). Position along axis k is
+    //     `C · axis_k`; convention is A−B (impulse +to A / −to B). ---
+    if (linConstrained) {
+        // A2: a fully-LOCKED linear triple is a ball-socket point — solve it
+        // as one coupled 3×3 block (frame axes) instead of axis-by-axis,
+        // removing the intra-joint coupling error the sequential per-axis
+        // Gauss-Seidel leaves behind. Falls back to per-axis if the block is
+        // near-singular.
+        if (mode[0] === DofMode.LOCKED && mode[1] === DofMode.LOCKED && mode[2] === DofMode.LOCKED) {
+            lin_K[0] = lin_K[3] = lin_K[5] = invMA + invMB;
+            lin_K[1] = lin_K[2] = lin_K[4] = 0;
+            accumulate_point_block(ss, baseA, pd, rA, fa, lin_K);
+            if (!to_world) accumulate_point_block(ss, baseB, pd, rB, fa, lin_K);
+            if (invert_sym3(lin_K, lin_Kinv)) {
                 for (let k = 0; k < 3; k++) {
-                    lin_active[k] = 0;
-                    const m = mode[k];
-                    if (m === DofMode.FREE) { imp[k] = 0; continue; }
                     const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
-                    const keff = axis_effective_mass(ss, baseA, invMA, rAx, rAy, rAz, ax, ay, az)
-                        + (to_world ? 0 : axis_effective_mass(ss, baseB, invMB, rBx, rBy, rBz, ax, ay, az));
-                    const pos = Cx * ax + Cy * ay + Cz * az;
-                    // Relative anchor velocity along the axis (A−B), for LIMITED
-                    // bound selection. Cheap; only the projection is used.
-                    let vel = 0;
-                    if (m === DofMode.LIMITED) {
-                        relative_anchor_velocity(scratch_rv, ss, baseA, rAx, rAy, rAz, baseB, rBx, rBy, rBz, to_world);
-                        vel = scratch_rv[0] * ax + scratch_rv[1] * ay + scratch_rv[2] * az;
-                    }
-                    fill_row(joint, k, k, keff, pos, vel, spook_locked, spook_spec, dt_sub,
-                        lin_active, lin_eff, lin_bias, lin_clo, lin_chi, lin_gamma);
+                    const o = p + PREP_ROWS + k * ROW_STRIDE;
+                    pd[o + ROW_BIAS] = clamp_bias(spook_locked * (Cx * ax + Cy * ay + Cz * az));
                 }
+                for (let i = 0; i < 6; i++) pd[p + PREP_K_INV + i] = lin_Kinv[i];
+                flags |= PREP_POINT_BLOCK | PREP_LINEAR_ROWS;
             }
-        } else {
-            lin_active[0] = lin_active[1] = lin_active[2] = 0;
         }
-
-        // --- Angular DOF row setup (frame axes). Position along axis k is the
-        //     k-th component of the frame-local small-angle error vector `e`;
-        //     convention is B−A (impulse +to B / −to A). ---
-        if (angConstrained) {
-            // Frame B world rotation (identity for a world anchor → locks A's
-            // frame to world axes).
-            let qBx = 0, qBy = 0, qBz = 0, qBw = 1;
-            if (!to_world) {
-                const lbb = joint.localBasisB;
-                quat3_multiply(scratch_q, 0, trB.rotation_x, trB.rotation_y, trB.rotation_z, trB.rotation_w, lbb[0], lbb[1], lbb[2], lbb[3]);
-                qBx = scratch_q[0]; qBy = scratch_q[1]; qBz = scratch_q[2]; qBw = scratch_q[3];
-            }
-            // qD = conj(qA) ⊗ qB → the per-axis angular position in frame-A
-            // coords. Two measures: the cheap small-angle rotation vector
-            // (default — exact at the origin, fine for welds / hinges / modest
-            // limits) or, when the joint opts into `swingTwist`, the swing-twist
-            // decomposition (X = twist, Y/Z = swing) with *exact* angles, for
-            // wide cone-twist range-of-motion (ragdoll shoulders) where the
-            // small-angle measure under-reports.
-            quat3_multiply(scratch_q, 0, -qAx, -qAy, -qAz, qAw, qBx, qBy, qBz, qBw);
-            if (joint.swingTwist) {
-                swing_twist_error(scratch_q[0], scratch_q[1], scratch_q[2], scratch_q[3], scratch_ang_err);
-            } else {
-                const es = scratch_q[3] < 0 ? -2 : 2;
-                scratch_ang_err[0] = es * scratch_q[0];
-                scratch_ang_err[1] = es * scratch_q[1];
-                scratch_ang_err[2] = es * scratch_q[2];
-            }
-
+        if ((flags & PREP_POINT_BLOCK) === 0) {
             for (let k = 0; k < 3; k++) {
-                ang_active[k] = 0;
-                const m = mode[3 + k];
-                if (m === DofMode.FREE) { imp[3 + k] = 0; continue; }
+                const m = mode[k];
+                if (m === DofMode.FREE) { imp[k] = 0; continue; }
                 const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
-                const keff = angular_axis_effective_mass(ss, baseA, ax, ay, az)
-                    + (to_world ? 0 : angular_axis_effective_mass(ss, baseB, ax, ay, az));
-                const pos = scratch_ang_err[k];
-                // Relative angular velocity about the axis (B−A), for LIMITED
-                // bound selection.
-                let vel = 0;
+                axis_effective_mass(keff, 0, ss, baseA, pd, rA, fa, 3 * k);
+                if (!to_world) axis_effective_mass(keff, 1, ss, baseB, pd, rB, fa, 3 * k);
+                dof[DOF_KEFF] = keff[0] + (to_world ? 0 : keff[1]);
+                dof[DOF_POS] = Cx * ax + Cy * ay + Cz * az;
+                // Relative anchor velocity along the axis (A−B), for LIMITED
+                // bound selection. Cheap; only the projection is used.
+                dof[DOF_VEL] = 0;
                 if (m === DofMode.LIMITED) {
-                    vel = -(ss[baseA + SBS_AV_X] * ax + ss[baseA + SBS_AV_Y] * ay + ss[baseA + SBS_AV_Z] * az);
-                    if (!to_world) vel += ss[baseB + SBS_AV_X] * ax + ss[baseB + SBS_AV_Y] * ay + ss[baseB + SBS_AV_Z] * az;
+                    relative_anchor_velocity(scratch_rv, ss, baseA, pd, rA, baseB, pd, rB, to_world);
+                    dof[DOF_VEL] = scratch_rv[0] * ax + scratch_rv[1] * ay + scratch_rv[2] * az;
+                }
+                if (fill_row(joint, k, dof, spook_locked, spook_spec, dt_sub,
+                    pd, p + PREP_ROWS + k * ROW_STRIDE)) {
+                    flags |= PREP_ROW_ACTIVE << k;
+                    if (m !== DofMode.LOCKED) flags |= PREP_ROW_RELAX << k;
                 }
-                fill_row(joint, 3 + k, k, keff, pos, vel, spook_locked, spook_spec, dt_sub,
-                    ang_active, ang_eff, ang_bias, ang_clo, ang_chi, ang_gamma);
             }
-        } else {
-            ang_active[0] = ang_active[1] = ang_active[2] = 0;
         }
+    }
 
-        if (!lin_active[0] && !lin_active[1] && !lin_active[2]
-            && !ang_active[0] && !ang_active[1] && !ang_active[2]) continue;
+    // --- Angular DOF row setup (frame axes). Position along axis k is the
+    //     k-th component of the frame-local small-angle error vector `e`;
+    //     convention is B−A (impulse +to B / −to A). ---
+    if (angConstrained) {
+        // Frame B world rotation (identity for a world anchor → locks A's
+        // frame to world axes), beside conj(qA).
+        const rel = scratch_rel;
+        rel[0] = -scratch_q[0]; rel[1] = -scratch_q[1]; rel[2] = -scratch_q[2]; rel[3] = scratch_q[3];
+        if (to_world) {
+            rel[4] = 0; rel[5] = 0; rel[6] = 0; rel[7] = 1;
+        } else {
+            quat3_multiply_array(rel, 4, trB, TRANSFORM64_ROTATION_OFFSET, joint.localBasisB, 0);
+        }
+        // qD = conj(qA) ⊗ qB → the per-axis angular position in frame-A
+        // coords. Two measures: the cheap small-angle rotation vector
+        // (default — exact at the origin, fine for welds / hinges / modest
+        // limits) or, when the joint opts into `swingTwist`, the swing-twist
+        // decomposition (X = twist, Y/Z = swing) with *exact* angles, for
+        // wide cone-twist range-of-motion (ragdoll shoulders) where the
+        // small-angle measure under-reports.
+        quat3_multiply_array(scratch_q, 0, rel, 0, rel, 4);
+        if (joint.swingTwist) {
+            swing_twist_error_array(scratch_q, 0, scratch_ang_err);
+        } else {
+            const es = scratch_q[3] < 0 ? -2 : 2;
+            scratch_ang_err[0] = es * scratch_q[0];
+            scratch_ang_err[1] = es * scratch_q[1];
+            scratch_ang_err[2] = es * scratch_q[2];
+        }
 
-        // --- Per-substep warm-start (frame axes): linear impulse `Σ imp[k]·aₖ`
-        //     applied at the anchors, angular impulse `Σ imp[3+k]·aₖ` about the
-        //     frame axes (+to B / −to A). ---
-        {
-            let Px = 0, Py = 0, Pz = 0;
-            for (let k = 0; k < 3; k++) {
-                if (!lin_active[k]) continue;
-                const w = imp[k];
-                Px += w * fa[3 * k]; Py += w * fa[3 * k + 1]; Pz += w * fa[3 * k + 2];
-            }
-            if (Px !== 0 || Py !== 0 || Pz !== 0) {
-                apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1, scratch_inertia);
-                if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1, scratch_inertia);
+        for (let k = 0; k < 3; k++) {
+            const m = mode[3 + k];
+            if (m === DofMode.FREE) { imp[3 + k] = 0; continue; }
+            const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
+            angular_axis_effective_mass(keff, 0, ss, baseA, fa, 3 * k);
+            if (!to_world) angular_axis_effective_mass(keff, 1, ss, baseB, fa, 3 * k);
+            dof[DOF_KEFF] = keff[0] + (to_world ? 0 : keff[1]);
+            dof[DOF_POS] = scratch_ang_err[k];
+            // Relative angular velocity about the axis (B−A), for LIMITED
+            // bound selection.
+            let vel = 0;
+            if (m === DofMode.LIMITED) {
+                vel = -(ss[baseA + SBS_AV_X] * ax + ss[baseA + SBS_AV_Y] * ay + ss[baseA + SBS_AV_Z] * az);
+                if (!to_world) vel += ss[baseB + SBS_AV_X] * ax + ss[baseB + SBS_AV_Y] * ay + ss[baseB + SBS_AV_Z] * az;
             }
-            let Lx = 0, Ly = 0, Lz = 0;
-            for (let k = 0; k < 3; k++) {
-                if (!ang_active[k]) continue;
-                const w = imp[3 + k];
-                Lx += w * fa[3 * k]; Ly += w * fa[3 * k + 1]; Lz += w * fa[3 * k + 2];
-            }
-            if (Lx !== 0 || Ly !== 0 || Lz !== 0) {
-                if (!to_world) apply_angular_impulse(ss, baseB, Lx, Ly, Lz, 1, +1);
-                apply_angular_impulse(ss, baseA, Lx, Ly, Lz, 1, -1);
+            dof[DOF_VEL] = vel;
+            if (fill_row(joint, 3 + k, dof, spook_locked, spook_spec, dt_sub,
+                pd, p + PREP_ROWS + (3 + k) * ROW_STRIDE)) {
+                flags |= PREP_ROW_ACTIVE << (3 + k);
+                if (m !== DofMode.LOCKED) flags |= PREP_ROW_RELAX << (3 + k);
             }
         }
+    }
 
-        for (let it = 0; it < iters; it++) {
-            // Linear rows (frame axes). The relative anchor velocity is
-            // recomputed before each row so successive rows see the prior
-            // impulses (Gauss-Seidel coupling).
-            if (useLinBlock) {
-                // A2: coupled 3×3 point solve — one relative anchor velocity,
-                // projected onto the frame axes, solved against Kⁱⁿᵛ in a single
-                // Newton step (bilateral, no clamp). The point constraint is
-                // satisfied exactly each iteration; only its coupling with the
-                // angular rows remains to iterate.
-                relative_anchor_velocity(scratch_rv, ss, baseA, rAx, rAy, rAz, baseB, rBx, rBy, rBz, to_world);
-                const rvx = scratch_rv[0], rvy = scratch_rv[1], rvz = scratch_rv[2];
-                const a0x = fa[0], a0y = fa[1], a0z = fa[2];
-                const a1x = fa[3], a1y = fa[4], a1z = fa[5];
-                const a2x = fa[6], a2y = fa[7], a2z = fa[8];
-                const b0 = rvx * a0x + rvy * a0y + rvz * a0z + lin_bias[0];
-                const b1 = rvx * a1x + rvy * a1y + rvz * a1z + lin_bias[1];
-                const b2 = rvx * a2x + rvy * a2y + rvz * a2z + lin_bias[2];
-                const d0 = -(lin_Kinv[0] * b0 + lin_Kinv[1] * b1 + lin_Kinv[2] * b2);
-                const d1 = -(lin_Kinv[1] * b0 + lin_Kinv[3] * b1 + lin_Kinv[4] * b2);
-                const d2 = -(lin_Kinv[2] * b0 + lin_Kinv[4] * b1 + lin_Kinv[5] * b2);
-                imp[0] += d0; imp[1] += d1; imp[2] += d2;
-                const Px = d0 * a0x + d1 * a1x + d2 * a2x;
-                const Py = d0 * a0y + d1 * a1y + d2 * a2y;
-                const Pz = d0 * a0z + d1 * a1z + d2 * a2z;
-                if (Px !== 0 || Py !== 0 || Pz !== 0) {
-                    apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, Px, Py, Pz, +1, scratch_inertia);
-                    if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, Px, Py, Pz, -1, scratch_inertia);
-                }
-            } else {
-                for (let k = 0; k < 3; k++) {
-                    if (!lin_active[k]) continue;
-                    const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
-                    relative_anchor_velocity(scratch_rv, ss, baseA, rAx, rAy, rAz, baseB, rBx, rBy, rBz, to_world);
-                    const rvx = scratch_rv[0], rvy = scratch_rv[1], rvz = scratch_rv[2];
-                    const vrel = rvx * ax + rvy * ay + rvz * az;
-                    const old = imp[k];
-                    // `+ γ·old` regularises a spring row (γ = 0 otherwise → exact).
-                    let nv = old - lin_eff[k] * (vrel + lin_bias[k] + lin_gamma[k] * old);
-                    if (nv < lin_clo[k]) nv = lin_clo[k]; else if (nv > lin_chi[k]) nv = lin_chi[k];
-                    imp[k] = nv;
-                    const d = nv - old;
-                    if (d !== 0) {
-                        apply_impulse_to_body(ss, baseA, invMA, rAx, rAy, rAz, d * ax, d * ay, d * az, +1, scratch_inertia);
-                        if (!to_world) apply_impulse_to_body(ss, baseB, invMB, rBx, rBy, rBz, d * ax, d * ay, d * az, -1, scratch_inertia);
-                    }
-                }
-            }
+    if ((flags & PREP_ANY_ROW) === 0) return false;
 
-            // Angular rows (frame axes): drive ωB−ωA about each axis toward the
-            // bias target, clamped per the row's bound.
-            for (let k = 0; k < 3; k++) {
-                if (!ang_active[k]) continue;
-                const ax = fa[3 * k], ay = fa[3 * k + 1], az = fa[3 * k + 2];
-                let wrel = -(ss[baseA + SBS_AV_X] * ax + ss[baseA + SBS_AV_Y] * ay + ss[baseA + SBS_AV_Z] * az);
-                if (!to_world) wrel += ss[baseB + SBS_AV_X] * ax + ss[baseB + SBS_AV_Y] * ay + ss[baseB + SBS_AV_Z] * az;
-                const old = imp[3 + k];
-                let nv = old - ang_eff[k] * (wrel + ang_bias[k] + ang_gamma[k] * old);
-                if (nv < ang_clo[k]) nv = ang_clo[k]; else if (nv > ang_chi[k]) nv = ang_chi[k];
-                imp[3 + k] = nv;
-                const d = nv - old;
-                if (d !== 0) {
-                    if (!to_world) apply_angular_impulse(ss, baseB, ax, ay, az, d, +1);
-                    apply_angular_impulse(ss, baseA, ax, ay, az, d, -1);
-                }
+    for (let i = 0; i < 9; i++) pd[p + PREP_FRAME + i] = fa[i];
+    prep_body[2 * slot] = idxA;
+    prep_body[2 * slot + 1] = idxB;
+    prep_flags[slot] = flags | PREP_LIVE;
+    return true;
+}
+
+/**
+ * Per-substep warm-start of a prepared joint (frame axes): linear impulse
+ * `Σ imp[k]·aₖ` applied at the anchors, angular impulse `Σ imp[3+k]·aₖ` about
+ * the frame axes (+to B / −to A), over the active rows.
+ *
+ * @param {Float64Array} ss  solver-body-state data
+ * @param {number} slot  a live prepared slot
+ * @param {Float64Array} imp  the joint's `dofImpulse`
+ */
+function warm_start_joint(ss, slot, imp) {
+    const flags = prep_flags[slot];
+    const pd = prep_data;
+    const p = slot * PREP_STRIDE;
+    const f = p + PREP_FRAME;
+    const baseA = prep_body[2 * slot] * SBS_STRIDE, baseB = prep_body[2 * slot + 1] * SBS_STRIDE;
+    const to_world = (flags & PREP_TO_WORLD) !== 0;
+
+    let Px = 0, Py = 0, Pz = 0;
+    for (let k = 0; k < 3; k++) {
+        if ((flags & (PREP_ROW_ACTIVE << k)) === 0) continue;
+        const w = imp[k];
+        Px += w * pd[f + 3 * k]; Py += w * pd[f + 3 * k + 1]; Pz += w * pd[f + 3 * k + 2];
+    }
+    if (Px !== 0 || Py !== 0 || Pz !== 0) {
+        const impulse = scratch_impulse;
+        impulse[0] = Px; impulse[1] = Py; impulse[2] = Pz;
+        apply_impulse_to_body(ss, baseA, pd, p + PREP_R_A, impulse, 0, +1, scratch_inertia);
+        if (!to_world) apply_impulse_to_body(ss, baseB, pd, p + PREP_R_B, impulse, 0, -1, scratch_inertia);
+    }
+
+    let Lx = 0, Ly = 0, Lz = 0;
+    for (let k = 0; k < 3; k++) {
+        if ((flags & (PREP_ROW_ACTIVE << (3 + k))) === 0) continue;
+        const w = imp[3 + k];
+        Lx += w * pd[f + 3 * k]; Ly += w * pd[f + 3 * k + 1]; Lz += w * pd[f + 3 * k + 2];
+    }
+    if (Lx !== 0 || Ly !== 0 || Lz !== 0) {
+        const impulse = scratch_impulse;
+        impulse[0] = Lx; impulse[1] = Ly; impulse[2] = Lz;
+        if (!to_world) apply_angular_impulse(ss, baseB, impulse, 0, +1);
+        apply_angular_impulse(ss, baseA, impulse, 0, -1);
+    }
+}
+
+/**
+ * One Gauss-Seidel iteration of a prepared joint's rows against the current
+ * body velocities, accumulating into `imp`.
+ *
+ * @param {Float64Array} ss  solver-body-state data
+ * @param {number} slot  a live prepared slot
+ * @param {Float64Array} imp  the joint's `dofImpulse`
+ * @param {boolean} relax  false: every active row, against its bias (the
+ *   biased passes); true: only the rows that relax, against their relax bias
+ *   (never a LOCKED row, so never the point block)
+ */
+function solve_joint_rows(ss, slot, imp, relax) {
+    const flags = prep_flags[slot];
+    const row_bit = relax ? PREP_ROW_RELAX : PREP_ROW_ACTIVE;
+    const bias_field = relax ? ROW_RELAX_BIAS : ROW_BIAS;
+    const pd = prep_data;
+    const p = slot * PREP_STRIDE;
+    const f = p + PREP_FRAME;
+    const rows = p + PREP_ROWS;
+    const baseA = prep_body[2 * slot] * SBS_STRIDE, baseB = prep_body[2 * slot + 1] * SBS_STRIDE;
+    const to_world = (flags & PREP_TO_WORLD) !== 0;
+    const rA = p + PREP_R_A, rB = p + PREP_R_B;
+
+    // Linear rows (frame axes). The relative anchor velocity is recomputed
+    // before each row so successive rows see the prior impulses (Gauss-Seidel
+    // coupling).
+    const block = (flags & PREP_POINT_BLOCK) !== 0;
+    if (block && !relax) {
+        // A2: coupled 3×3 point solve — one relative anchor velocity,
+        // projected onto the frame axes, solved against Kⁱⁿᵛ in a single
+        // Newton step (bilateral, no clamp). The point constraint is
+        // satisfied exactly each iteration; only its coupling with the
+        // angular rows (and the other joints) remains to iterate. LOCKED, so
+        // it sits out the relax.
+        relative_anchor_velocity(scratch_rv, ss, baseA, pd, rA, baseB, pd, rB, to_world);
+        const rvx = scratch_rv[0], rvy = scratch_rv[1], rvz = scratch_rv[2];
+        const a0x = pd[f], a0y = pd[f + 1], a0z = pd[f + 2];
+        const a1x = pd[f + 3], a1y = pd[f + 4], a1z = pd[f + 5];
+        const a2x = pd[f + 6], a2y = pd[f + 7], a2z = pd[f + 8];
+        const b0 = rvx * a0x + rvy * a0y + rvz * a0z + pd[rows + ROW_BIAS];
+        const b1 = rvx * a1x + rvy * a1y + rvz * a1z + pd[rows + ROW_STRIDE + ROW_BIAS];
+        const b2 = rvx * a2x + rvy * a2y + rvz * a2z + pd[rows + 2 * ROW_STRIDE + ROW_BIAS];
+        const ki = p + PREP_K_INV;
+        const d0 = -(pd[ki] * b0 + pd[ki + 1] * b1 + pd[ki + 2] * b2);
+        const d1 = -(pd[ki + 1] * b0 + pd[ki + 3] * b1 + pd[ki + 4] * b2);
+        const d2 = -(pd[ki + 2] * b0 + pd[ki + 4] * b1 + pd[ki + 5] * b2);
+        imp[0] += d0; imp[1] += d1; imp[2] += d2;
+        const Px = d0 * a0x + d1 * a1x + d2 * a2x;
+        const Py = d0 * a0y + d1 * a1y + d2 * a2y;
+        const Pz = d0 * a0z + d1 * a1z + d2 * a2z;
+        if (Px !== 0 || Py !== 0 || Pz !== 0) {
+            const impulse = scratch_impulse;
+            impulse[0] = Px; impulse[1] = Py; impulse[2] = Pz;
+            apply_impulse_to_body(ss, baseA, pd, rA, impulse, 0, +1, scratch_inertia);
+            if (!to_world) apply_impulse_to_body(ss, baseB, pd, rB, impulse, 0, -1, scratch_inertia);
+        }
+    } else if (!block) {
+        for (let k = 0; k < 3; k++) {
+            if ((flags & (row_bit << k)) === 0) continue;
+            const o = rows + k * ROW_STRIDE;
+            const ax = pd[f + 3 * k], ay = pd[f + 3 * k + 1], az = pd[f + 3 * k + 2];
+            relative_anchor_velocity(scratch_rv, ss, baseA, pd, rA, baseB, pd, rB, to_world);
+            const vrel = scratch_rv[0] * ax + scratch_rv[1] * ay + scratch_rv[2] * az;
+            const old = imp[k];
+            // `+ γ·old` regularises a spring row (γ = 0 otherwise → exact).
+            let nv = old - pd[o + ROW_EFF] * (vrel + pd[o + bias_field] + pd[o + ROW_GAMMA] * old);
+            if (nv < pd[o + ROW_CLAMP_LO]) nv = pd[o + ROW_CLAMP_LO]; else if (nv > pd[o + ROW_CLAMP_HI]) nv = pd[o + ROW_CLAMP_HI];
+            imp[k] = nv;
+            const d = nv - old;
+            if (d !== 0) {
+                const impulse = scratch_impulse;
+                impulse[0] = d * ax; impulse[1] = d * ay; impulse[2] = d * az;
+                apply_impulse_to_body(ss, baseA, pd, rA, impulse, 0, +1, scratch_inertia);
+                if (!to_world) apply_impulse_to_body(ss, baseB, pd, rB, impulse, 0, -1, scratch_inertia);
             }
         }
     }
+
+    // Angular rows (frame axes): drive ωB−ωA about each axis toward the bias
+    // target, clamped per the row's bound.
+    for (let k = 0; k < 3; k++) {
+        if ((flags & (row_bit << (3 + k))) === 0) continue;
+        const o = rows + (3 + k) * ROW_STRIDE;
+        const ax = pd[f + 3 * k], ay = pd[f + 3 * k + 1], az = pd[f + 3 * k + 2];
+        let wrel = -(ss[baseA + SBS_AV_X] * ax + ss[baseA + SBS_AV_Y] * ay + ss[baseA + SBS_AV_Z] * az);
+        if (!to_world) wrel += ss[baseB + SBS_AV_X] * ax + ss[baseB + SBS_AV_Y] * ay + ss[baseB + SBS_AV_Z] * az;
+        const old = imp[3 + k];
+        let nv = old - pd[o + ROW_EFF] * (wrel + pd[o + bias_field] + pd[o + ROW_GAMMA] * old);
+        if (nv < pd[o + ROW_CLAMP_LO]) nv = pd[o + ROW_CLAMP_LO]; else if (nv > pd[o + ROW_CLAMP_HI]) nv = pd[o + ROW_CLAMP_HI];
+        imp[3 + k] = nv;
+        const d = nv - old;
+        if (d !== 0) {
+            const impulse = scratch_impulse;
+            impulse[0] = d * ax; impulse[1] = d * ay; impulse[2] = d * az;
+            if (!to_world) apply_angular_impulse(ss, baseB, impulse, 0, +1);
+            apply_angular_impulse(ss, baseA, impulse, 0, -1);
+        }
+    }
+}
+
+/**
+ * Solve every joint for one substep: prepare each joint's rows at the current
+ * poses, then run `iters` Gauss-Seidel passes over all of them. The first pass
+ * prepares, warm-starts and solves each joint in turn; passes 2..iters
+ * re-solve every live joint from its prepared rows, in the same order. The
+ * prepared rows stay for this substep's {@link relax_joints}.
+ *
+ * The warm start stays inside the first pass, interleaved with the solve, on
+ * purpose: replaying every joint's impulse before solving any (Box3D's order)
+ * is unstable on these hard Baumgarte rows — measured, a hanging 10-link
+ * chain at one pass opens by ~99 m, and a hanging 20-link chain at eight
+ * passes diverges from rest. Box3D gets away with it on soft rows.
+ *
+ * Called once per substep from `PhysicsSystem.fixedUpdate`, after the contact
+ * solve so the two share the substep / warm-start cadence.
+ *
+ * @param {Joint[]} joints  live joints in solve order (holes skipped)
+ * @param {PhysicsSystem} system  reads `__bodies` / `__transforms` / index map
+ * @param {number} dt_sub  substep size in seconds (the SPOOK gain is derived
+ *   from it, matching the contact solver's per-substep position stiffness)
+ * @param {number} iters  passes over the joint set. 0 turns the joints off for
+ *   the substep: nothing is prepared, warm-started or solved, and so nothing
+ *   is relaxed either — the solver leaves the jointed bodies' velocities alone.
+ * @param {boolean} [reverse]  A2: sweep the joint array tip→root this substep
+ *   (the caller alternates it per substep for a symmetric Gauss-Seidel sweep,
+ *   so chain impulses propagate both ways). Default false ⇒ root→tip.
+ */
+export function solve_joints(joints, system, dt_sub, iters, reverse) {
+    const n = joints.length;
+    prep_count = 0;
+    if (n === 0 || dt_sub <= 0 || iters <= 0) return;
+
+    ensure_prep_capacity(n);
+    prep_count = n;
+
+    const spook_locked = JOINT_BAUMGARTE / dt_sub;
+    const spook_spec = 1 / dt_sub;
+
+    const ss = system.__solver_state.data;
+
+    for (let jj = 0; jj < n; jj++) {
+        const slot = reverse ? (n - 1 - jj) : jj;
+        const joint = joints[slot];
+        if (!prepare_joint(slot, joint, system, ss, dt_sub, spook_locked, spook_spec)) continue;
+        warm_start_joint(ss, slot, joint.dofImpulse);
+        solve_joint_rows(ss, slot, joint.dofImpulse, false);
+    }
+
+    for (let it = 1; it < iters; it++) {
+        for (let jj = 0; jj < n; jj++) {
+            const slot = reverse ? (n - 1 - jj) : jj;
+            if ((prep_flags[slot] & PREP_LIVE) === 0) continue;
+            solve_joint_rows(ss, slot, joints[slot].dofImpulse, false);
+        }
+    }
+}
+
+/**
+ * The relax pass: one more sweep over the joints the last
+ * {@link solve_joints} prepared, re-solving their LIMITED, MOTOR and SPRING
+ * rows against the relax bias — the velocity target without the position
+ * correction (see the module doc) — from the prepared rows. Called once per
+ * substep from `PhysicsSystem.fixedUpdate`, after the position integrate,
+ * with the joints and sweep direction of that substep's solve.
+ *
+ * LOCKED rows sit it out, where Box3D relaxes every row. Its rows are soft;
+ * on these hard Baumgarte rows relaxing the LOCKED ones as well widened the
+ * ragdoll drop's settle tail. Per-twin settled limb speed, median / 94th
+ * percentile over 401 twins: 0.31 / 1.65 m/s with this relax, 0.27 / 3.55
+ * with none, 0.49 / 5.6 relaxing every row. Re-deriving the lever arms at the
+ * integrated pose while keeping the prepared K⁻¹ and frame made the full relax
+ * worse still, 4.2 / 7.9 (101 twins). LOCKED rows need no relax: the next
+ * substep's biased solve sets their velocity outright.
+ *
+ * @param {Joint[]} joints  the array the last solve_joints was given
+ * @param {PhysicsSystem} system  reads `__solver_state`
+ * @param {boolean} [reverse]  the sweep direction of that solve
+ */
+export function relax_joints(joints, system, reverse) {
+    const n = prep_count;
+    if (n === 0) return;
+
+    assert.equal(joints.length, n, 'relax_joints: not the joints the last solve_joints prepared');
+
+    const ss = system.__solver_state.data;
+
+    for (let jj = 0; jj < n; jj++) {
+        const slot = reverse ? (n - 1 - jj) : jj;
+        const flags = prep_flags[slot];
+        if ((flags & PREP_LIVE) === 0 || (flags & PREP_ANY_RELAX) === 0) continue;
+        solve_joint_rows(ss, slot, joints[slot].dofImpulse, true);
+    }
 }