@woosh/meep-engine 2.140.0 → 2.141.0

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

@@ -6,18 +6,25 @@ import { assert } from "../../../../core/assert.js";
  * {@link v3_grid_solve_pressure}, which uses the mask to skip boundary checks
  * and solid-neighbour checks entirely.
  *
- * Encoding (one byte per cell, low 6 bits):
+ * Encoding (one byte per cell):
  *
- *     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 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
  *
- * Solid cells themselves are encoded as `mask = 0` (not "their own neighbours
- * are fluid") so the SOR loop's `mask === 0 → skip` branch covers both
- * "self-solid" and "fluid but no fluid neighbours" with one comparison.
+ * The low 6 bits are the fluid-neighbour set; bit 7 flags the cell as solid.
+ * A solid cell encodes as exactly `128` — bit 7 set, every neighbour bit clear
+ * — and an isolated fluid cell (no fluid neighbours) as `0`. Both therefore
+ * satisfy `(mask & 63) === 0`, so the SOR / PCG loops' "no fluid neighbours →
+ * skip" branch is a single `(mask & 63) === 0` comparison that covers
+ * "self-solid" and "fluid but no fluid neighbours" alike. The dedicated bit 7
+ * additionally lets {@link v3_grid_subtract_pressure_gradient} tell solid cells
+ * (zero the velocity) apart from isolated fluid (leave it) without the original
+ * `solid` array.
  *
  * O(N) — one byte-write per cell, up to six byte-reads per cell. The output
  * fully replaces whatever was in `mask` before; no need to zero-init.
@@ -49,7 +56,7 @@ export function v3_grid_compute_solid_neighbour_mask(mask, solid, res_x, res_y,
             for (let x = 0; x < res_x; x++) {
                 const c = y_off + x;
                 if (solid[c] !== 0) {
-                    mask[c] = 0;
+                    mask[c] = 128; // bit 7 = this cell is solid; neighbour bits stay clear
                     continue;
                 }
                 let m = 0;

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure.d.ts

@@ -11,17 +11,20 @@
  * a Uint8Array allocated and populated by {@link FluidField} via
  * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
  *
- *     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 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 (consumed by
+ *                     {@link v3_grid_subtract_pressure_gradient}, ignored here)
  *
- * Solid cells encode as `mask = 0`, so the inner loop's `mask === 0 ? skip` covers
- * both self-solid AND fluid-with-no-fluid-neighbours in one comparison. This
- * eliminates six boundary checks plus six solid-neighbour checks per cell per
- * iteration, replacing them with a single mask read and six bit-tests on a
+ * The low 6 bits are the fluid-neighbour set. A solid cell encodes as `128` and
+ * an isolated fluid cell as `0`, so the inner loop's `(mask & 63) === 0 ? skip`
+ * covers both self-solid AND fluid-with-no-fluid-neighbours in one comparison.
+ * This eliminates six boundary checks plus six solid-neighbour checks per cell
+ * per iteration, replacing them with a single mask read and six bit-tests on a
  * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
  * implicit — the recompute step writes 0 into the boundary-facing bit, so the
  * SOR loop never reads out-of-range memory.

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QA+DpB"}
+{"version":3,"file":"v3_grid_solve_pressure.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,iDAdW,YAAY,eAAa,cAEzB,YAAY,eAAa,SAEzB,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,SACN,MAAM,kBAEN,UAAU,QAiEpB"}

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

@@ -30,17 +30,20 @@ const POPCOUNT_6 = (function () {
  * a Uint8Array allocated and populated by {@link FluidField} via
  * {@link FluidField.recomputeSolidNeighbourMask}. The encoding is:
  *
- *     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 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 (consumed by
+ *                     {@link v3_grid_subtract_pressure_gradient}, ignored here)
  *
- * Solid cells encode as `mask = 0`, so the inner loop's `mask === 0 ? skip` covers
- * both self-solid AND fluid-with-no-fluid-neighbours in one comparison. This
- * eliminates six boundary checks plus six solid-neighbour checks per cell per
- * iteration, replacing them with a single mask read and six bit-tests on a
+ * The low 6 bits are the fluid-neighbour set. A solid cell encodes as `128` and
+ * an isolated fluid cell as `0`, so the inner loop's `(mask & 63) === 0 ? skip`
+ * covers both self-solid AND fluid-with-no-fluid-neighbours in one comparison.
+ * This eliminates six boundary checks plus six solid-neighbour checks per cell
+ * per iteration, replacing them with a single mask read and six bit-tests on a
  * register-resident value. Boundary handling (cells at x=0, x=last, etc.) is
  * implicit — the recompute step writes 0 into the boundary-facing bit, so the
  * SOR loop never reads out-of-range memory.
@@ -101,9 +104,11 @@ export function v3_grid_solve_pressure(pressure, divergence, res_x, res_y, res_z
                         const c = z_off + y_off + x;
 
                         const mask = neighbour_mask[c];
-                        if (mask === 0) {
-                            // Solid cell OR isolated fluid with no fluid neighbours.
-                            // Either way, no degrees of freedom — skip.
+                        if ((mask & 63) === 0) {
+                            // No fluid neighbours: solid cell (bit 7 set) OR isolated
+                            // fluid. Either way, no degrees of freedom — skip. Cells
+                            // that reach past here have bit 7 clear, so `mask` indexes
+                            // POPCOUNT_6 (sized 64) in range.
                             continue;
                         }
 

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.d.ts

@@ -69,9 +69,10 @@
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Solid cells (mask = 0) are excluded from the system: their pressure stays at
- * whatever it was (typically 0), their entries in r, z, s, As stay 0, and they
- * contribute nothing to dot products.
+ * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
+ * fluid (mask = 0), both identified by `(mask & 63) === 0` — are excluded from
+ * the system: their pressure stays at whatever it was (typically 0), their
+ * entries in r, z, s, As stay 0, and they contribute nothing to dot products.
  *
  * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
  *     or with the previous step's solution to warm-start.

package/src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,qDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,kBAEN,UAAU,aACV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QAuNtB"}
+{"version":3,"file":"v3_grid_solve_pressure_pcg.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_solve_pressure_pcg.js"],"names":[],"mappings":"AAuCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AACH,qDAhBW,YAAY,eAAa,cAEzB,YAAY,eAAa,SACzB,MAAM,SACN,MAAM,SACN,MAAM,kBACN,MAAM,kBAEN,UAAU,aACV,YAAY,aACZ,YAAY,aACZ,YAAY,cACZ,YAAY,kBACZ,YAAY,QA0NtB"}

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

@@ -108,9 +108,10 @@ const MIC_SIGMA = 0.25;
  * the hot path that prevents MIC-PCG from parallelizing onto a GPU without
  * substantial reformulation. On single-thread JS that's not a concern.
  *
- * Solid cells (mask = 0) are excluded from the system: their pressure stays at
- * whatever it was (typically 0), their entries in r, z, s, As stay 0, and they
- * contribute nothing to dot products.
+ * Cells with no fluid neighbours — solid cells (mask bit 7 set) and isolated
+ * fluid (mask = 0), both identified by `(mask & 63) === 0` — are excluded from
+ * the system: their pressure stays at whatever it was (typically 0), their
+ * entries in r, z, s, As stay 0, and they contribute nothing to dot products.
  *
  * @param {Float32Array|Float16Array} pressure  Mutated in place. Pre-fill with 0
  *     or with the previous step's solution to warm-start.
@@ -173,9 +174,12 @@ export function v3_grid_solve_pressure_pcg(
     // (Standard fluids practice — see Bridson §5.5. The alternative is to pin
     // one cell to a Dirichlet value and exclude it from the system, but mean
     // subtraction has the same effect with simpler bookkeeping.)
+    // A cell is a degree of freedom iff it has ≥1 fluid neighbour, i.e. any of
+    // the low 6 bits set. Solid cells (bit 7) and isolated fluid (all-zero) are
+    // both excluded by masking off bit 7 with & 63.
     let fluid_count = 0;
     for (let c = 0; c < cells; c++) {
-        if (neighbour_mask[c] !== 0) fluid_count++;
+        if ((neighbour_mask[c] & 63) !== 0) fluid_count++;
     }
     if (fluid_count === 0) {
         return;
@@ -193,7 +197,7 @@ export function v3_grid_solve_pressure_pcg(
     precon.fill(0);
     for (let c = 0; c < cells; c++) {
         const mask = neighbour_mask[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             continue;
         }
         const a_diag = POPCOUNT_6[mask];
@@ -246,7 +250,7 @@ export function v3_grid_solve_pressure_pcg(
 
     for (let c = 0; c < cells; c++) {
         const mask = neighbour_mask[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             r[c] = 0;
             continue;
         }
@@ -285,7 +289,7 @@ export function v3_grid_solve_pressure_pcg(
         let s_dot_As = 0;
         for (let c = 0; c < cells; c++) {
             const mask = neighbour_mask[c];
-            if (mask === 0) {
+            if ((mask & 63) === 0) {
                 As[c] = 0;
                 continue;
             }
@@ -379,11 +383,11 @@ export function v3_grid_solve_pressure_pcg(
 function subtract_mean_fluid(v, mask_array, cells, fluid_count) {
     let sum = 0;
     for (let c = 0; c < cells; c++) {
-        if (mask_array[c] !== 0) sum += v[c];
+        if ((mask_array[c] & 63) !== 0) sum += v[c];
     }
     const mean = sum / fluid_count;
     for (let c = 0; c < cells; c++) {
-        if (mask_array[c] !== 0) v[c] -= mean;
+        if ((mask_array[c] & 63) !== 0) v[c] -= mean;
     }
 }
 
@@ -391,7 +395,7 @@ function apply_preconditioner(r, z, precon, mask_array, cells, rx, slice) {
     // Forward solve L · y = r. Store y in z (we won't read z[c'] for c' > c).
     for (let c = 0; c < cells; c++) {
         const mask = mask_array[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             z[c] = 0;
             continue;
         }
@@ -410,7 +414,7 @@ function apply_preconditioner(r, z, precon, mask_array, cells, rx, slice) {
     // indices, processed first in reverse).
     for (let c = cells - 1; c >= 0; c--) {
         const mask = mask_array[c];
-        if (mask === 0) {
+        if ((mask & 63) === 0) {
             continue;
         }
         let t = z[c]; // = y[c] from forward pass

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts

@@ -13,25 +13,28 @@
  * pressure (consistent with the Neumann condition used in the solve), which keeps the
  * flow tangent to the boundary.
  *
- * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
- * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
- * {@link FluidField.recomputeSolidNeighbourMask}). A set 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. 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
- *
- * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
- * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
- * opposite handling — 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. `solid` is what tells them apart, so it stays.
+ * 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.
@@ -40,9 +43,8 @@
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
  * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
- *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ *     pressure solve uses; MUST be recomputed whenever the solid mask changes.
  */
-export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, solid: Uint8Array, neighbour_mask: Uint8Array): void;
+export function v3_grid_subtract_pressure_gradient(vel_x: Float32Array, vel_y: Float32Array, vel_z: Float32Array, pressure: Float32Array, res_x: number, res_y: number, res_z: number, neighbour_mask: Uint8Array): void;
 //# sourceMappingURL=v3_grid_subtract_pressure_gradient.d.ts.map

package/src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,0DAXW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,SACN,UAAU,kBACV,UAAU,QA8CpB"}
+{"version":3,"file":"v3_grid_subtract_pressure_gradient.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_grid_subtract_pressure_gradient.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAgDpB"}

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

@@ -15,25 +15,28 @@ import { assert } from "../../../../core/assert.js";
  * pressure (consistent with the Neumann condition used in the solve), which keeps the
  * flow tangent to the boundary.
  *
- * Which neighbours count as fluid is read straight from `neighbour_mask`, the same
- * pre-baked per-cell bitmask {@link v3_grid_solve_pressure} consumes (populated by
- * {@link FluidField.recomputeSolidNeighbourMask}). A set 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. Encoding:
+ * 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 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
  *
- * Unlike the solve, the mask can't drive the self-cell branch: both a solid cell and
- * an isolated fluid cell (no fluid neighbours) encode as `mask = 0`, yet they need
- * opposite handling — 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. `solid` is what tells them apart, so it stays.
+ * 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.
@@ -42,11 +45,10 @@ import { assert } from "../../../../core/assert.js";
  * @param {number} res_x
  * @param {number} res_y
  * @param {number} res_z
- * @param {Uint8Array} solid            Required (zero-filled for a wall-free domain).
  * @param {Uint8Array} neighbour_mask   Length ≥ res_x*res_y*res_z. Same buffer the
- *     pressure solve uses; MUST be recomputed whenever `solid` changes.
+ *     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, solid, neighbour_mask) {
+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");
@@ -65,7 +67,10 @@ export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure
             for (let x = 0; x < res_x; x++) {
                 const c = z_off + y_off + x;
 
-                if (solid[c] !== 0) {
+                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;
@@ -75,7 +80,6 @@ export function v3_grid_subtract_pressure_gradient(vel_x, vel_y, vel_z, pressure
                 // 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 mask = neighbour_mask[c];
                 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];

package/src/engine/physics/island/IslandBuilder.d.ts

@@ -117,8 +117,11 @@ export class IslandBuilder {
      * @param {ManifoldStore} manifolds
      * @param {RigidBody[]} bodies sparse, indexed by body index
      * @param {Array[]} body_collider_lists sparse, indexed by body index
+     * @param {Joint[]} joints live joints (sparse). Jointed dynamic-dynamic
+     *   bodies are unioned into the same island so a chain / ragdoll sleeps
+     *   and wakes as a unit. Callers with no joints pass an empty array.
      */
-    build(storage: BodyStorage, manifolds: ManifoldStore, bodies: RigidBody[], body_collider_lists: any[][]): void;
+    build(storage: BodyStorage, manifolds: ManifoldStore, bodies: RigidBody[], body_collider_lists: any[][], joints: Joint[]): void;
     /**
      * Fill `body_offsets` + `body_data` with awake dynamic bodies grouped
      * by island, sorted ascending within each island.

package/src/engine/physics/island/IslandBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyFI;;;;;OAKG;IACH,gCAUC;IAtGG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAqBvC;;;;;;;;OAQG;IACH,8DAHW,WAAW,uBACX,OAAO,QAuEjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BAwCC;IAED;;;;;;;;OAQG;IACH,yBAcC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}
+{"version":3,"file":"IslandBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/island/IslandBuilder.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IAyFI;;;;;OAKG;IACH,gCAUC;IAtGG;;;;;OAKG;IACH,QAFU,WAAW,CAEY;IAEjC;;;;OAIG;IACH,gBAFU,UAAU,CAEoB;IAExC;;;OAGG;IACH,cAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,cAFU,WAAW,CAEiB;IAEtC;;;;OAIG;IACH,WAFU,WAAW,CAEe;IAEpC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;;OAKG;IACH,iBAFU,WAAW,CAEoB;IAEzC;;;;OAIG;IACH,cAFU,WAAW,CAEkB;IAEvC;;;OAGG;IACH,eAFU,MAAM,CAEM;IAEtB;;;;;OAKG;IACH,yBAA0C;IAE1C;;;;;OAKG;IACH,wBAA0C;IAE1C;;;;OAIG;IACH,kBAAmC;IAqBvC;;;;;;;;;;;OAWG;IACH,8DANW,WAAW,uBACX,OAAO,UACP,OAAO,QAgGjB;IAED;;;;OAIG;IACH,yBA+CC;IAED;;;;;;OAMG;IACH,4BAwCC;IAED;;;;;;;;OAQG;IACH,yBAcC;IAID;;;OAGG;IACH,+BAQC;IAED;;;OAGG;IACH,uCAOC;IAED;;;OAGG;IACH,oCAIC;IAED;;;OAGG;IACH,uCAIC;CACJ"}

package/src/engine/physics/island/IslandBuilder.js

@@ -1,6 +1,8 @@
+import { ceilPowerOfTwo } from "../../../core/binary/operations/ceilPowerOfTwo.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import { BodyKind } from "../ecs/BodyKind.js";
 import { ColliderFlags } from "../ecs/ColliderFlags.js";
+import { JOINT_WORLD } from "../ecs/Joint.js";
 import { RigidBodyFlags } from "../ecs/RigidBodyFlags.js";
 import { uf_find, uf_init, uf_union } from "./union_find.js";
 
@@ -149,8 +151,11 @@ export class IslandBuilder {
      * @param {ManifoldStore} manifolds
      * @param {RigidBody[]} bodies sparse, indexed by body index
      * @param {Array[]} body_collider_lists sparse, indexed by body index
+     * @param {Joint[]} joints live joints (sparse). Jointed dynamic-dynamic
+     *   bodies are unioned into the same island so a chain / ragdoll sleeps
+     *   and wakes as a unit. Callers with no joints pass an empty array.
      */
-    build(storage, manifolds, bodies, body_collider_lists) {
+    build(storage, manifolds, bodies, body_collider_lists, joints) {
         const hwm = storage.high_water_mark;
         this.__ensure_body_capacity(hwm);
 
@@ -174,6 +179,29 @@ export class IslandBuilder {
             }
         }
 
+        // --- Pass 1b: union dynamic-dynamic bodies connected by a joint, so a
+        //     chain / ragdoll forms one island (and so sleeps/wakes as a unit).
+        //     Joint-to-world and joint-to-static/kinematic anchor the island
+        //     without enlarging it — same rule as a static contact. Stale joint
+        //     references (body unlinked / slot reused) are filtered by the
+        //     generation-checked `is_valid`. (Empty when the caller has no
+        //     joints — the loop is then a no-op.)
+        const jn = joints.length;
+        for (let i = 0; i < jn; i++) {
+            const joint = joints[i];
+            if (joint === undefined || joint === null) continue;
+            if (joint._bodyIdB === JOINT_WORLD) continue;
+            if (!storage.is_valid(joint._bodyIdA) || !storage.is_valid(joint._bodyIdB)) continue;
+            const idxA = body_id_index(joint._bodyIdA);
+            const idxB = body_id_index(joint._bodyIdB);
+            const rbA = bodies[idxA];
+            const rbB = bodies[idxB];
+            if (rbA === undefined || rbB === undefined) continue;
+            if (rbA.kind === BodyKind.Dynamic && rbB.kind === BodyKind.Dynamic) {
+                uf_union(parent, idxA, idxB);
+            }
+        }
+
         // --- Pass 2: collect distinct roots over awake dynamic bodies.
         const island_of_body = this.island_of_body;
         // Cheap reset: only the indices we may write are below hwm.
@@ -357,7 +385,7 @@ export class IslandBuilder {
      */
     __ensure_body_capacity(n) {
         if (this.parent.length < n) {
-            const cap = next_pow2(n);
+            const cap = ceilPowerOfTwo(n);
             this.parent = new Uint32Array(cap);
             this.island_of_body = new Int32Array(cap);
             this.__root_to_island = new Int32Array(cap);
@@ -371,7 +399,7 @@ export class IslandBuilder {
      */
     __ensure_island_count_capacity(n) {
         if (this.body_offsets.length < n + 1) {
-            const cap = next_pow2(n + 1);
+            const cap = ceilPowerOfTwo(n + 1);
             this.body_offsets = new Uint32Array(cap);
             this.contact_offsets = new Uint32Array(cap);
             this.__cursors = new Uint32Array(cap);
@@ -384,7 +412,7 @@ export class IslandBuilder {
      */
     __ensure_body_data_capacity(n) {
         if (this.body_data.length < n) {
-            this.body_data = new Uint32Array(next_pow2(n));
+            this.body_data = new Uint32Array(ceilPowerOfTwo(n));
         }
     }
 
@@ -394,18 +422,7 @@ export class IslandBuilder {
      */
     __ensure_contact_data_capacity(n) {
         if (this.contact_data.length < n) {
-            this.contact_data = new Uint32Array(next_pow2(n));
+            this.contact_data = new Uint32Array(ceilPowerOfTwo(n));
         }
     }
 }
-
-/**
- * @param {number} n
- * @returns {number}
- */
-function next_pow2(n) {
-    if (n <= 1) return 1;
-    let p = 1;
-    while (p < n) p <<= 1;
-    return p;
-}

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA+HA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA0anB;AAvhBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AAqJA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA8anB;AA3hBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}

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

@@ -39,6 +39,28 @@ const MAX_CONTACTS = 4;
 const CONTACT_STRIDE = 7;
 const PARALLEL_EPS_SQR = 1e-8;
 
+/**
+ * Reference-axis tie-break deadband. SAT picks the minimum-overlap axis, but
+ * for aligned boxes two axes (A's face normal and B's face normal along the
+ * contact direction) have *equal* overlap, so floating-point noise from a
+ * sub-degree wobble flips which one wins frame to frame. That flips the
+ * reference/incident assignment, which reorders the contact points, which
+ * flips the solver's Gauss-Seidel sweep order — injecting an alternating
+ * bias that makes symmetric stacks creep and never sleep.
+ *
+ * The deadband makes a later axis replace the current best only if it
+ * reduces the overlap by more than `best · TIE_REL + TIE_ABS`. Axes are
+ * tested A-faces, then B-faces, then edge-crosses, so ties resolve to the
+ * earlier axis (A's face, then a face over an edge) — a stable, consistent
+ * choice. Genuine minima (overlap smaller by more than the band) still win,
+ * so SAT correctness for non-aligned boxes is unchanged; only the
+ * noise-driven flip on near-perfect alignment is suppressed. Box2D's
+ * `b2CollidePolygons` uses the same relative+absolute hysteresis.
+ * @type {number}
+ */
+const TIE_REL = 0.02;
+const TIE_ABS = 1e-5;
+
 /**
  * Length of `out` required by {@link box_box_manifold}.
  * @type {number}
@@ -182,7 +204,11 @@ export function box_box_manifold(
         const dist = proj < 0 ? -proj : proj;
         const overlap = (rA + rB) - dist;
         if (overlap < 0) return true;
-        if (overlap < best_overlap) {
+        // Deadband: the first axis always wins; a later axis replaces it only
+        // if it reduces the overlap past the hysteresis band. This biases ties
+        // toward earlier-tested axes (A faces > B faces > edges) so aligned
+        // boxes pick a stable reference instead of flip-flopping on noise.
+        if (best_source === -1 || overlap < best_overlap - (best_overlap * TIE_REL + TIE_ABS)) {
             best_overlap = overlap;
             const sign = proj > 0 ? -1 : 1; // normal points B→A
             best_nx = ux * sign;

package/src/engine/physics/narrowphase/narrowphase_step.d.ts

@@ -14,4 +14,37 @@ export function narrowphase_step(pair_list: PairList, manifolds: ManifoldStore,
     collider: Collider;
     transform: Transform;
 }>>): void;
+/**
+ * Re-detect contact GEOMETRY for one existing manifold slot at the bodies'
+ * current poses, updating the witness points / normal / depth of the slot's
+ * existing contacts in place. Does NOT change the contact count, the
+ * feature ids, or the accumulated impulses — it only refreshes geometry.
+ *
+ * This is the per-substep concave path (TGS): for a contact pair involving a
+ * concave body, the contact *feature* (which triangle is deepest, and its
+ * normal) genuinely changes as the body rocks, so the solver's cheap analytic
+ * refresh — which freezes the feature for the whole outer step — pumps energy
+ * in. Re-running the narrowphase geometry each substep gives a fresh,
+ * correct normal so the body settles instead of rocking. Convex pairs keep
+ * the analytic refresh and never call this (their feature is stable).
+ *
+ * Matching is by feature id (stable per-triangle for the decomposition path),
+ * so a contact's geometry tracks the same triangle across substeps. A contact
+ * whose triangle isn't found this substep keeps its previous geometry (a rare
+ * transient; the once-per-frame {@link narrowphase_step} re-establishes the
+ * contact set next outer step). Count never changes here, so the solver's
+ * per-contact scratch (sized once at prepare) stays aligned.
+ *
+ * @param {ManifoldStore} manifolds
+ * @param {number} slot
+ * @param {Array<{collider: Collider, transform: Transform}>} list_a
+ * @param {Array<{collider: Collider, transform: Transform}>} list_b
+ */
+export function redetect_pair_geometry(manifolds: ManifoldStore, slot: number, list_a: Array<{
+    collider: Collider;
+    transform: Transform;
+}>, list_b: Array<{
+    collider: Collider;
+    transform: Transform;
+}>): void;
 //# sourceMappingURL=narrowphase_step.d.ts.map

package/src/engine/physics/narrowphase/narrowphase_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA6uCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE"}
+{"version":3,"file":"narrowphase_step.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/narrowphase_step.js"],"names":[],"mappings":"AA6uCA;;;;;;;;;;;GAWG;AACH,uFALW,MAAM,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,CAAC,QAyJlE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,uEAJW,MAAM,UACN,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,UACjD,MAAM;IAAC,QAAQ,WAAW;IAAC,SAAS,YAAW;CAAC,CAAC,QAiD3D"}