@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js

@@ -1,96 +1,108 @@
-import { assert } from "../../../../core/assert.js";
-
-/**
- * Subtract the pressure gradient from a velocity field in-place, making the velocity
- * (approximately) divergence-free:
- *
- *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
- *
- * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
- * close to zero in the bulk; residual divergence at boundaries / under-converged solves
- * is normal.
- *
- * Boundary cells use one-sided differences. Solid cells have their velocity zeroed
- * (no-slip), and neighbour gradients across a solid face reflect the cell's own
- * pressure (consistent with the Neumann condition used in the solve), which keeps the
- * flow tangent to the boundary.
- *
- * Everything this needs is read straight from `neighbour_mask`, the same pre-baked
- * per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
- * {@link FluidField.recomputeSolidNeighbourMask}). Encoding:
- *
- *     bit 0 (= 1)   : -x neighbour is fluid
- *     bit 1 (= 2)   : +x neighbour is fluid
- *     bit 2 (= 4)   : -y neighbour is fluid
- *     bit 3 (= 8)   : +y neighbour is fluid
- *     bit 4 (= 16)  : -z neighbour is fluid
- *     bit 5 (= 32)  : +z neighbour is fluid
- *     bit 7 (= 128) : this cell is itself solid
- *
- * A set neighbour bit means "that neighbour is fluid (in-bounds AND non-solid)", so a
- * clear bit reflects the cell's own pressure — folding the boundary check and the
- * solid-neighbour check into one register-resident bit-test per face.
- *
- * Bit 7 carries the self-solid flag that used to require the separate `solid` array.
- * The solve can't use the low 6 bits for this (a solid cell and an isolated fluid cell
- * both have zero fluid-neighbour bits) but needs opposite handling here — the solid
- * must be zeroed for no-slip, while the isolated fluid's gradient already nets to zero
- * (every face reflects its own pressure) and must be left alone. Bit 7 distinguishes
- * them, so a single mask read drives both the zeroing and the gradient.
- *
- * @param {Float32Array} vel_x          Mutated in place.
- * @param {Float32Array} vel_y          Mutated in place.
- * @param {Float32Array} vel_z          Mutated in place.
- * @param {Float32Array} pressure       From {@link v3_grid_solve_pressure}.
- * @param {number} res_x
- * @param {number} res_y
- * @param {number} res_z
- * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
- *     pressure solve uses; MUST be recomputed whenever the solid mask changes.
- */
-export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, neighbour_mask) {
-    const cell_count = res_x * res_y * res_z;
-    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
-    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
-    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
-    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
-    assert.greaterThanOrEqual(neighbour_mask.length, cell_count, "neighbour_mask covers grid");
-
-    const slice_size = res_x * res_y;
-
-    for (let z = 0; z < res_z; z++) {
-        const z_off = z * slice_size;
-
-        for (let y = 0; y < res_y; y++) {
-            const y_off = y * res_x;
-
-            for (let x = 0; x < res_x; x++) {
-                const c = z_off + y_off + x;
-
-                const mask = neighbour_mask[c];
-
-                if (mask & 128) {
-                    // Solid cell (bit 7): enforce no-slip.
-                    vel_x[c] = 0;
-                    vel_y[c] = 0;
-                    vel_z[c] = 0;
-                    continue;
-                }
-
-                // A clear bit means the neighbour is out-of-bounds or solid; reflect
-                // the cell's own pressure so that face contributes 0 to the gradient,
-                // consistent with ∂p/∂n = 0 at the wall.
-                const p_xm = (mask & 1)  ? pressure[c - 1]          : pressure[c];
-                const p_xp = (mask & 2)  ? pressure[c + 1]          : pressure[c];
-                const p_ym = (mask & 4)  ? pressure[c - res_x]      : pressure[c];
-                const p_yp = (mask & 8)  ? pressure[c + res_x]      : pressure[c];
-                const p_zm = (mask & 16) ? pressure[c - slice_size] : pressure[c];
-                const p_zp = (mask & 32) ? pressure[c + slice_size] : pressure[c];
-
-                vel_x[c] -= 0.5 * (p_xp - p_xm);
-                vel_y[c] -= 0.5 * (p_yp - p_ym);
-                vel_z[c] -= 0.5 * (p_zp - p_zm);
-            }
-        }
-    }
-}
+import { assert } from "../../../../core/assert.js";
+
+/**
+ * Subtract the pressure gradient from a velocity field in-place, making the velocity
+ * (approximately) divergence-free:
+ *
+ *     v(c) -= 0.5 * ( p(x+1) - p(x-1), p(y+1) - p(y-1), p(z+1) - p(z-1) )
+ *
+ * Pairs with {@link v3_grid_solve_pressure}. After this, divergence will be
+ * close to zero in the bulk; residual divergence at boundaries / under-converged solves
+ * is normal.
+ *
+ * Per-face ghost values mirror the boundary model the pressure solve uses (see
+ * {@link v3_grid_compute_solid_neighbour_mask}):
+ *
+ *   - fluid neighbour (mask bit set): read its pressure.
+ *   - SOLID neighbour (bit clear, in bounds): reflect the cell's own pressure —
+ *     ∂p/∂n = 0 at the wall, the face contributes 0 to the gradient and flow
+ *     stays tangent to the boundary.
+ *   - OPEN face (bit clear, out of bounds — the domain edge): ghost pressure 0,
+ *     matching the Dirichlet open boundary in the solve. Positive interior
+ *     pressure therefore accelerates fluid OUT through the edge — the open
+ *     boundary actually vents.
+ *
+ * Solid cells themselves have their velocity zeroed (no-slip).
+ *
+ * Everything this needs is read from `neighbour_mask` (the same pre-baked
+ * per-cell bitmask {@link v3_grid_solve_pressure} consumes, populated by
+ * {@link FluidField.recomputeSolidNeighbourMask}) plus the loop position
+ * (which face is at the domain edge is positional knowledge). Encoding:
+ *
+ *     bit 0 (= 1)   : -x neighbour is fluid
+ *     bit 1 (= 2)   : +x neighbour is fluid
+ *     bit 2 (= 4)   : -y neighbour is fluid
+ *     bit 3 (= 8)   : +y neighbour is fluid
+ *     bit 4 (= 16)  : -z neighbour is fluid
+ *     bit 5 (= 32)  : +z neighbour is fluid
+ *     bit 7 (= 128) : this cell is itself solid
+ *
+ * Bit 7 carries the self-solid flag. The solve skips no-DOF cells via
+ * `diag === 0`, but this kernel needs opposite handling for the two no-DOF
+ * flavours — a solid must be zeroed for no-slip, while a sealed fluid cell's
+ * gradient already nets to zero (every face reflects its own pressure) and
+ * must be left alone. Bit 7 distinguishes them.
+ *
+ * @param {Float32Array} vel_x          Mutated in place.
+ * @param {Float32Array} vel_y          Mutated in place.
+ * @param {Float32Array} vel_z          Mutated in place.
+ * @param {Float32Array} pressure       From {@link v3_grid_solve_pressure}.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
+ *     pressure solve uses; MUST be recomputed whenever the solid mask changes.
+ */
+export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure, res_x, res_y, res_z, neighbour_mask) {
+    const cell_count = res_x * res_y * res_z;
+    assert.greaterThanOrEqual(vel_x.length, cell_count, "vel_x covers grid");
+    assert.greaterThanOrEqual(vel_y.length, cell_count, "vel_y covers grid");
+    assert.greaterThanOrEqual(vel_z.length, cell_count, "vel_z covers grid");
+    assert.greaterThanOrEqual(pressure.length, cell_count, "pressure covers grid");
+    assert.greaterThanOrEqual(neighbour_mask.length, cell_count, "neighbour_mask covers grid");
+
+    const slice_size = res_x * res_y;
+    const last_x = res_x - 1;
+    const last_y = res_y - 1;
+    const last_z = res_z - 1;
+
+    for (let z = 0; z < res_z; z++) {
+        const z_off = z * slice_size;
+        const open_zm = z === 0;
+        const open_zp = z === last_z;
+
+        for (let y = 0; y < res_y; y++) {
+            const y_off = y * res_x;
+            const open_ym = y === 0;
+            const open_yp = y === last_y;
+
+            for (let x = 0; x < res_x; x++) {
+                const c = z_off + y_off + x;
+
+                const mask = neighbour_mask[c];
+
+                if (mask & 128) {
+                    // Solid cell (bit 7): enforce no-slip.
+                    vel_x[c] = 0;
+                    vel_y[c] = 0;
+                    vel_z[c] = 0;
+                    continue;
+                }
+
+                // Per face: fluid neighbour → its pressure; solid neighbour →
+                // reflect own pressure (Neumann); domain edge → ghost 0 (open).
+                const p_self = pressure[c];
+                const p_xm = (mask & 1)  ? pressure[c - 1]          : (x === 0      ? 0 : p_self);
+                const p_xp = (mask & 2)  ? pressure[c + 1]          : (x === last_x ? 0 : p_self);
+                const p_ym = (mask & 4)  ? pressure[c - res_x]      : (open_ym      ? 0 : p_self);
+                const p_yp = (mask & 8)  ? pressure[c + res_x]      : (open_yp      ? 0 : p_self);
+                const p_zm = (mask & 16) ? pressure[c - slice_size] : (open_zm      ? 0 : p_self);
+                const p_zp = (mask & 32) ? pressure[c + slice_size] : (open_zp      ? 0 : p_self);
+
+                vel_x[c] -= 0.5 * (p_xp - p_xm);
+                vel_y[c] -= 0.5 * (p_yp - p_ym);
+                vel_z[c] -= 0.5 * (p_zp - p_zm);
+            }
+        }
+    }
+}

package/src/engine/physics/inertia/world_inverse_inertia.d.ts

@@ -63,5 +63,34 @@ export function world_inverse_inertia_apply(result: number[] | Float64Array, res
  * @param {number} vy
  * @param {number} vz
  */
-export function world_inverse_inertia_apply_raw(result: number[] | Float64Array, result_offset: number, ix: number, iy: number, iz: number, qx: number, qy: number, qz: number, qw: number, vx: number, vy: number, vz: number): void;
+/**
+ * Quadratic-form contribution of one body to a unit-axis velocity
+ * constraint's effective mass: `(r × axis)ᵀ · I_w⁻¹ · (r × axis)`, where `r`
+ * is the body-relative application point. The full constraint denominator is
+ * `invM_A + invM_B + contribution_A + contribution_B`.
+ *
+ * The shared kernel behind the contact/joint solver's SoA path and the
+ * raycast-vehicle's component path — each previously inlined the cross
+ * product + {@link world_inverse_inertia_apply_raw} + dot themselves.
+ * Identical operation order in every caller keeps the paths bit-identical
+ * (the determinism contract).
+ *
+ * @param {number} ix
+ * @param {number} iy
+ * @param {number} iz Body-frame inverse inertia diagonal.
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw Body orientation as a unit quaternion.
+ * @param {number} rx
+ * @param {number} ry
+ * @param {number} rz Body-relative application point.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az Unit constraint axis.
+ * @param {number[]|Float64Array} scratch length >= 3, clobbered
+ * @returns {number}
+ */
+export function angular_effective_mass_raw(ix: number, iy: number, iz: number, qx: number, qy: number, qz: number, qw: number, rx: number, ry: number, rz: number, ax: number, ay: number, az: number, scratch: number[] | Float64Array): number;
+export function world_inverse_inertia_apply_raw(result: any, result_offset: any, ix: any, iy: any, iz: any, qx: any, qy: any, qz: any, qw: any, vx: any, vy: any, vz: any): void;
 //# sourceMappingURL=world_inverse_inertia.d.ts.map

package/src/engine/physics/inertia/world_inverse_inertia.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oDAVW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,YAEjC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,MAE5C,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wDAbW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QA4ChB"}
+{"version":3,"file":"world_inverse_inertia.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/inertia/world_inverse_inertia.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,oDAVW,MAAM,EAAE,GAAC,YAAY,iBACrB,MAAM,qBACN;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,YAEjC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAC,MAE5C,MAAM,MACN,MAAM,MACN,MAAM,QAkBhB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,+CAhBW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,WACN,MAAM,EAAE,GAAC,YAAY,GACnB,MAAM,CAgBlB;AAED,iLA0CC"}

package/src/engine/physics/inertia/world_inverse_inertia.js

@@ -1,116 +1,160 @@
-/**
- * Apply the world-frame inverse inertia tensor of a rigid body to a world-space
- * vector and write the result.
- *
- * Body-frame inverse inertia is supplied as a diagonal in principal axes
- * (a Vector3-like with `.x .y .z`). World inverse inertia is
- * `I_w⁻¹ = R · diag · R^T` where `R` is the body's orientation. We compute
- * `result = R · diag · R^T · v` without materialising the full 3x3 matrix:
- *
- *   1. `v_body = R^T · v`   (rotate v into body frame)
- *   2. scale component-wise by the diagonal
- *   3. `result = R · v_body_scaled`
- *
- * Quaternion-rotate-vector uses the standard `q · v · q*` identity. Inverse
- * rotation uses the conjugate quaternion.
- *
- * Sphere short-circuit: if the inverse inertia is isotropic (ix === iy === iz),
- * the rotation cancels and `result = ix * v`. Skip the trig and save the work.
- *
- * Decoupled from RigidBody / Transform on purpose — callers pass only what
- * is actually read. Lets `compute_penetration` and other standalone
- * geometry helpers reuse this without manufacturing a body.
- *
- * @param {number[]|Float64Array} result length >= 3
- * @param {number} result_offset
- * @param {{x: number, y: number, z: number}} inv_inertia_local
- *        Body-frame inverse inertia diagonal (typically `rb.inverseInertiaLocal`).
- * @param {{x: number, y: number, z: number, w: number}} rotation
- *        Body orientation as a unit quaternion (typically `transform.rotation`).
- * @param {number} vx
- * @param {number} vy
- * @param {number} vz
- */
-export function world_inverse_inertia_apply(
-    result, result_offset,
-    inv_inertia_local, rotation,
-    vx, vy, vz
-) {
-    // Thin object-reading wrapper over the raw-float kernel. Reads the
-    // quaternion fields eagerly (harmless in the isotropic short-circuit,
-    // where they're ignored) so the kernel is the single source of the math —
-    // keeping object callers and the data-oriented (SoA) solver path
-    // bit-identical.
-    world_inverse_inertia_apply_raw(
-        result, result_offset,
-        inv_inertia_local.x, inv_inertia_local.y, inv_inertia_local.z,
-        rotation.x, rotation.y, rotation.z, rotation.w,
-        vx, vy, vz
-    );
-}
-
-/**
- * Raw-float counterpart of {@link world_inverse_inertia_apply}: the same
- * `I_w⁻¹ = R · diag · R^T` application, with the inverse-inertia diagonal and
- * orientation quaternion passed as scalars rather than read off
- * `{x,y,z}` / `{x,y,z,w}` objects. The data-oriented contact / joint solver
- * reads these straight out of its `SolverBodyState` typed array, avoiding the
- * per-impulse object dereference on the hot path. The arithmetic is identical
- * to the object version (same operation order), so results are bit-identical.
- *
- * @param {number[]|Float64Array} result length >= 3
- * @param {number} result_offset
- * @param {number} ix
- * @param {number} iy
- * @param {number} iz Body-frame inverse inertia diagonal.
- * @param {number} qx
- * @param {number} qy
- * @param {number} qz
- * @param {number} qw Body orientation as a unit quaternion.
- * @param {number} vx
- * @param {number} vy
- * @param {number} vz
- */
-export function world_inverse_inertia_apply_raw(
-    result, result_offset,
-    ix, iy, iz,
-    qx, qy, qz, qw,
-    vx, vy, vz
-) {
-
-    if (ix === iy && iy === iz) {
-        // Isotropic — rotation cancels.
-        result[result_offset] = vx * ix;
-        result[result_offset + 1] = vy * ix;
-        result[result_offset + 2] = vz * ix;
-        return;
-    }
-
-    // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
-    // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
-    // PosedShape.support and core/geom/vec3/v3_quat3_apply_inverse.js
-    // for the canonical form.
-    const tx = qw * vx - qy * vz + qz * vy;
-    const ty = qw * vy - qz * vx + qx * vz;
-    const tz = qw * vz - qx * vy + qy * vx;
-    const tw = qx * vx + qy * vy + qz * vz;
-
-    const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
-    const vby = ty * qw + tw * qy + tz * qx - tx * qz;
-    const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
-
-    // Step 2: scale by the principal-frame diagonal.
-    const sx = vbx * ix;
-    const sy = vby * iy;
-    const sz = vbz * iz;
-
-    // Step 3: result = R · scaled = q · scaled · q*. Inlined likewise.
-    const ux = qw * sx + qy * sz - qz * sy;
-    const uy = qw * sy + qz * sx - qx * sz;
-    const uz = qw * sz + qx * sy - qy * sx;
-    const uw = -qx * sx - qy * sy - qz * sz;
-
-    result[result_offset] = ux * qw - uw * qx - uy * qz + uz * qy;
-    result[result_offset + 1] = uy * qw - uw * qy - uz * qx + ux * qz;
-    result[result_offset + 2] = uz * qw - uw * qz - ux * qy + uy * qx;
-}
+/**
+ * Apply the world-frame inverse inertia tensor of a rigid body to a world-space
+ * vector and write the result.
+ *
+ * Body-frame inverse inertia is supplied as a diagonal in principal axes
+ * (a Vector3-like with `.x .y .z`). World inverse inertia is
+ * `I_w⁻¹ = R · diag · R^T` where `R` is the body's orientation. We compute
+ * `result = R · diag · R^T · v` without materialising the full 3x3 matrix:
+ *
+ *   1. `v_body = R^T · v`   (rotate v into body frame)
+ *   2. scale component-wise by the diagonal
+ *   3. `result = R · v_body_scaled`
+ *
+ * Quaternion-rotate-vector uses the standard `q · v · q*` identity. Inverse
+ * rotation uses the conjugate quaternion.
+ *
+ * Sphere short-circuit: if the inverse inertia is isotropic (ix === iy === iz),
+ * the rotation cancels and `result = ix * v`. Skip the trig and save the work.
+ *
+ * Decoupled from RigidBody / Transform on purpose — callers pass only what
+ * is actually read. Lets `compute_penetration` and other standalone
+ * geometry helpers reuse this without manufacturing a body.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {{x: number, y: number, z: number}} inv_inertia_local
+ *        Body-frame inverse inertia diagonal (typically `rb.inverseInertiaLocal`).
+ * @param {{x: number, y: number, z: number, w: number}} rotation
+ *        Body orientation as a unit quaternion (typically `transform.rotation`).
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
+export function world_inverse_inertia_apply(
+    result, result_offset,
+    inv_inertia_local, rotation,
+    vx, vy, vz
+) {
+    // Thin object-reading wrapper over the raw-float kernel. Reads the
+    // quaternion fields eagerly (harmless in the isotropic short-circuit,
+    // where they're ignored) so the kernel is the single source of the math —
+    // keeping object callers and the data-oriented (SoA) solver path
+    // bit-identical.
+    world_inverse_inertia_apply_raw(
+        result, result_offset,
+        inv_inertia_local.x, inv_inertia_local.y, inv_inertia_local.z,
+        rotation.x, rotation.y, rotation.z, rotation.w,
+        vx, vy, vz
+    );
+}
+
+/**
+ * Raw-float counterpart of {@link world_inverse_inertia_apply}: the same
+ * `I_w⁻¹ = R · diag · R^T` application, with the inverse-inertia diagonal and
+ * orientation quaternion passed as scalars rather than read off
+ * `{x,y,z}` / `{x,y,z,w}` objects. The data-oriented contact / joint solver
+ * reads these straight out of its `SolverBodyState` typed array, avoiding the
+ * per-impulse object dereference on the hot path. The arithmetic is identical
+ * to the object version (same operation order), so results are bit-identical.
+ *
+ * @param {number[]|Float64Array} result length >= 3
+ * @param {number} result_offset
+ * @param {number} ix
+ * @param {number} iy
+ * @param {number} iz Body-frame inverse inertia diagonal.
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw Body orientation as a unit quaternion.
+ * @param {number} vx
+ * @param {number} vy
+ * @param {number} vz
+ */
+/**
+ * Quadratic-form contribution of one body to a unit-axis velocity
+ * constraint's effective mass: `(r × axis)ᵀ · I_w⁻¹ · (r × axis)`, where `r`
+ * is the body-relative application point. The full constraint denominator is
+ * `invM_A + invM_B + contribution_A + contribution_B`.
+ *
+ * The shared kernel behind the contact/joint solver's SoA path and the
+ * raycast-vehicle's component path — each previously inlined the cross
+ * product + {@link world_inverse_inertia_apply_raw} + dot themselves.
+ * Identical operation order in every caller keeps the paths bit-identical
+ * (the determinism contract).
+ *
+ * @param {number} ix
+ * @param {number} iy
+ * @param {number} iz Body-frame inverse inertia diagonal.
+ * @param {number} qx
+ * @param {number} qy
+ * @param {number} qz
+ * @param {number} qw Body orientation as a unit quaternion.
+ * @param {number} rx
+ * @param {number} ry
+ * @param {number} rz Body-relative application point.
+ * @param {number} ax
+ * @param {number} ay
+ * @param {number} az Unit constraint axis.
+ * @param {number[]|Float64Array} scratch length >= 3, clobbered
+ * @returns {number}
+ */
+export function angular_effective_mass_raw(
+    ix, iy, iz,
+    qx, qy, qz, qw,
+    rx, ry, rz,
+    ax, ay, az,
+    scratch
+) {
+    const cx = ry * az - rz * ay;
+    const cy = rz * ax - rx * az;
+    const cz = rx * ay - ry * ax;
+
+    world_inverse_inertia_apply_raw(scratch, 0, ix, iy, iz, qx, qy, qz, qw, cx, cy, cz);
+
+    return cx * scratch[0] + cy * scratch[1] + cz * scratch[2];
+}
+
+export function world_inverse_inertia_apply_raw(
+    result, result_offset,
+    ix, iy, iz,
+    qx, qy, qz, qw,
+    vx, vy, vz
+) {
+
+    if (ix === iy && iy === iz) {
+        // Isotropic — rotation cancels.
+        result[result_offset] = vx * ix;
+        result[result_offset + 1] = vy * ix;
+        result[result_offset + 2] = vz * ix;
+        return;
+    }
+
+    // Step 1: v_body = R^T · v.  R^T corresponds to applying the conjugate
+    // quaternion (-qx, -qy, -qz, qw). Inlined for V8 inliner — see
+    // PosedShape3D.support and core/geom/vec3/v3_quat3_apply_inverse.js
+    // for the canonical form.
+    const tx = qw * vx - qy * vz + qz * vy;
+    const ty = qw * vy - qz * vx + qx * vz;
+    const tz = qw * vz - qx * vy + qy * vx;
+    const tw = qx * vx + qy * vy + qz * vz;
+
+    const vbx = tx * qw + tw * qx + ty * qz - tz * qy;
+    const vby = ty * qw + tw * qy + tz * qx - tx * qz;
+    const vbz = tz * qw + tw * qz + tx * qy - ty * qx;
+
+    // Step 2: scale by the principal-frame diagonal.
+    const sx = vbx * ix;
+    const sy = vby * iy;
+    const sz = vbz * iz;
+
+    // Step 3: result = R · scaled = q · scaled · q*. Inlined likewise.
+    const ux = qw * sx + qy * sz - qz * sy;
+    const uy = qw * sy + qz * sx - qx * sz;
+    const uz = qw * sz + qx * sy - qy * sx;
+    const uw = -qx * sx - qy * sy - qz * sz;
+
+    result[result_offset] = ux * qw - uw * qx - uy * qz + uz * qy;
+    result[result_offset + 1] = uy * qw - uw * qy - uz * qx + ux * qz;
+    result[result_offset + 2] = uz * qw - uw * qz - ux * qy + uy * qx;
+}