@woosh/meep-engine 2.156.0 → 2.158.0

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

@@ -8,14 +8,24 @@
  * 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.
+ * Per-face ghost values mirror the boundary model the pressure solve uses (see
+ * {@link v3_grid_compute_solid_neighbour_mask}):
  *
- * 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:
+ *   - 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
@@ -25,16 +35,11 @@
  *     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.
+ * 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.

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAgDpB"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,0DAVW,YAAY,SACZ,YAAY,SACZ,YAAY,YACZ,YAAY,SACZ,MAAM,SACN,MAAM,SACN,MAAM,kBACN,UAAU,QAuDpB"}

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/fluid/solver/v3_mac_advect_maccormack_velocity.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Unconditionally stable MacCormack advection of a MAC (face-centered)
+ * velocity field — the staggered counterpart of
+ * {@link v3_grid_advect_maccormack_velocity}. Per component lattice:
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src faces around the back-traced
+ *                  position (Selle et al. 2008 monotone limiter; pinned faces
+ *                  participate — they hold valid boundary values)
+ *
+ * Solid handling matches {@link v3_mac_advect_sl_velocity}: PINNED faces pass
+ * their source value through (the projection owns them as boundary
+ * conditions), and every trace — backward in both passes, forward in the
+ * corrector — is CLIPPED against solid cells so momentum is never sampled
+ * from inside a wall or through one.
+ *
+ * The cross-component carrier reconstruction uses the exact fixed 4-tap MAC
+ * averages (face positions are grid-aligned in the cross axes — see the SL
+ * kernel), recomputed per pass; the carrier does not change between passes
+ * so both passes see identical trace vectors.
+ *
+ * Aliasing: per component, `out`, `src` and `fwd` must be distinct, and
+ * outputs must not alias any carrier lattice (cross-component carrier
+ * sampling — see {@link v3_mac_advect_sl_velocity}).
+ *
+ * @param {Float32Array[]} outputs         `[out_u, out_v, out_w]`. Mutated.
+ * @param {Float32Array[]} sources         `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier         `[car_u, car_v, car_w]`.
+ * @param {Float32Array[]} forward_scratch `[fwd_u, fwd_v, fwd_w]`. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid  Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_maccormack_velocity(outputs: Float32Array[], sources: Float32Array[], carrier: Float32Array[], forward_scratch: Float32Array[], res_x: number, res_y: number, res_z: number, time_delta: number, face_solid_x: Uint8Array, face_solid_y: Uint8Array, face_solid_z: Uint8Array, solid: Uint8Array): void;
+//# sourceMappingURL=v3_mac_advect_maccormack_velocity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"v3_mac_advect_maccormack_velocity.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/solver/v3_mac_advect_maccormack_velocity.js"],"names":[],"mappings":"AAiCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,2DAbW,YAAY,EAAE,WACd,YAAY,EAAE,WACd,YAAY,EAAE,mBACd,YAAY,EAAE,SACd,MAAM,SACN,MAAM,SACN,MAAM,cACN,MAAM,gBACN,UAAU,gBACV,UAAU,gBACV,UAAU,SACV,UAAU,QA0MpB"}

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

@@ -0,0 +1,319 @@
+import { assert } from "../../../../core/assert.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { scs3d_sample_linear } from "../../../graphics/texture/3d/scs3d_sample_linear.js";
+import { v3_mac_clip_trace } from "./v3_mac_clip_trace.js";
+
+const scratch_clip = new Float32Array(3);
+
+/**
+ * Straight-line (loop-free, inlinable) test: is the cell containing the
+ * point solid? Same rounding/clamping as v3_mac_clip_trace. Kernels use this
+ * inline per trace and call the loop-bearing clip helper only on a hit — see
+ * the performance contract on {@link v3_mac_clip_trace}.
+ *
+ * @param {Uint8Array} solid
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} px
+ * @param {number} py
+ * @param {number} pz
+ * @return {boolean}
+ */
+function end_in_solid(solid, res_x, res_y, res_z, px, py, pz) {
+    let x = (px + 0.5) | 0;
+    let y = (py + 0.5) | 0;
+    let z = (pz + 0.5) | 0;
+    if (x < 0) x = 0; else if (x >= res_x) x = res_x - 1;
+    if (y < 0) y = 0; else if (y >= res_y) y = res_y - 1;
+    if (z < 0) z = 0; else if (z >= res_z) z = res_z - 1;
+    return solid[z * res_x * res_y + y * res_x + x] !== 0;
+}
+
+
+/**
+ * Unconditionally stable MacCormack advection of a MAC (face-centered)
+ * velocity field — the staggered counterpart of
+ * {@link v3_grid_advect_maccormack_velocity}. Per component lattice:
+ *
+ *     1. forward:  û  = SL(src, back-trace by carrier·dt)
+ *     2. backward: ū  = SL(û, trace by +carrier·dt)
+ *     3. correct:  u* = û + ½·(src − ū)
+ *     4. limit:    clamp to min/max of the 8 src faces around the back-traced
+ *                  position (Selle et al. 2008 monotone limiter; pinned faces
+ *                  participate — they hold valid boundary values)
+ *
+ * Solid handling matches {@link v3_mac_advect_sl_velocity}: PINNED faces pass
+ * their source value through (the projection owns them as boundary
+ * conditions), and every trace — backward in both passes, forward in the
+ * corrector — is CLIPPED against solid cells so momentum is never sampled
+ * from inside a wall or through one.
+ *
+ * The cross-component carrier reconstruction uses the exact fixed 4-tap MAC
+ * averages (face positions are grid-aligned in the cross axes — see the SL
+ * kernel), recomputed per pass; the carrier does not change between passes
+ * so both passes see identical trace vectors.
+ *
+ * Aliasing: per component, `out`, `src` and `fwd` must be distinct, and
+ * outputs must not alias any carrier lattice (cross-component carrier
+ * sampling — see {@link v3_mac_advect_sl_velocity}).
+ *
+ * @param {Float32Array[]} outputs         `[out_u, out_v, out_w]`. Mutated.
+ * @param {Float32Array[]} sources         `[src_u, src_v, src_w]`. Read.
+ * @param {Float32Array[]} carrier         `[car_u, car_v, car_w]`.
+ * @param {Float32Array[]} forward_scratch `[fwd_u, fwd_v, fwd_w]`. Mutated.
+ * @param {number} res_x
+ * @param {number} res_y
+ * @param {number} res_z
+ * @param {number} time_delta
+ * @param {Uint8Array} face_solid_x
+ * @param {Uint8Array} face_solid_y
+ * @param {Uint8Array} face_solid_z
+ * @param {Uint8Array} solid  Cell-centered solid flags (trace clipping).
+ */
+export function v3_mac_advect_maccormack_velocity(outputs, sources, carrier, forward_scratch, res_x, res_y, res_z, time_delta, face_solid_x, face_solid_y, face_solid_z, solid) {
+    assert.equal(outputs.length, 3, "outputs is a 3-component array");
+    assert.equal(sources.length, 3, "sources is a 3-component array");
+    assert.equal(carrier.length, 3, "carrier is a 3-component array");
+    assert.equal(forward_scratch.length, 3, "forward_scratch is a 3-component array");
+
+    const out_u = outputs[0], out_v = outputs[1], out_w = outputs[2];
+    const src_u = sources[0], src_v = sources[1], src_w = sources[2];
+    const car_u = carrier[0], car_v = carrier[1], car_w = carrier[2];
+    const fwd_u = forward_scratch[0], fwd_v = forward_scratch[1], fwd_w = forward_scratch[2];
+
+    assert.notEqual(out_u, src_u, "out_u must not alias src_u");
+    assert.notEqual(out_u, fwd_u, "out_u must not alias fwd_u");
+    assert.notEqual(src_u, fwd_u, "src_u must not alias fwd_u");
+
+    const sx = res_x + 1;
+    const sy = res_y + 1;
+    const sz = res_z + 1;
+    const cell_slice = res_x * res_y;
+    const u_slice = sx * res_y;
+    const v_slice = res_x * sy;
+    const last_cx = res_x - 1;
+    const last_cy = res_y - 1;
+    const last_cz = res_z - 1;
+    const dt = time_delta;
+
+    // ─── u (x-faces): face (x,y,z) sits at (x − 0.5, y, z) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z < res_z; z++) {
+            const f_z = z * u_slice;
+            const v_z = z * v_slice;
+            const w_z = z * cell_slice;
+            for (let y = 0; y < res_y; y++) {
+                const f_y = f_z + y * sx;
+                const v_lo = v_z + y * res_x;
+                const v_hi = v_lo + res_x;
+                const w_lo = w_z + y * res_x;
+                const w_hi = w_lo + cell_slice;
+                for (let x = 0; x <= res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_x[f] !== 0) {
+                        if (pass === 0) fwd_u[f] = src_u[f];
+                        else out_u[f] = src_u[f];
+                        continue;
+                    }
+                    const xa = x > 0 ? x - 1 : 0;
+                    const xb = x < res_x ? x : last_cx;
+                    const cu = car_u[f];
+                    const cv = 0.25 * (car_v[v_lo + xa] + car_v[v_lo + xb] + car_v[v_hi + xa] + car_v[v_hi + xb]);
+                    const cw = 0.25 * (car_w[w_lo + xa] + car_w[w_lo + xb] + car_w[w_hi + xa] + car_w[w_hi + xb]);
+                    const px = x - 0.5;
+
+                    // Back-trace end (shared by pass A and the limiter).
+                    let bx = px - cu * dt;
+                    let by = y - cv * dt;
+                    let bz = z - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, px, y, z, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_u[f] = scs3d_sample_linear(src_u, sx, res_y, res_z, bx + 0.5, by, bz);
+                        continue;
+                    }
+
+                    // Forward probe through the forward result.
+                    let qx = px + cu * dt;
+                    let qy = y + cv * dt;
+                    let qz = z + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, px, y, z, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_u, sx, res_y, res_z, qx + 0.5, qy, qz);
+                    const corrected = fwd_u[f] + 0.5 * (src_u[f] - backward);
+
+                    out_u[f] = limit8(corrected, src_u,
+                        bx + 0.5, by, bz,
+                        sx, res_y, res_z, sx, u_slice);
+                }
+            }
+        }
+    }
+
+    // ─── v (y-faces): face (x,y,z) sits at (x, y − 0.5, z) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z < res_z; z++) {
+            const f_z = z * v_slice;
+            const u_z = z * u_slice;
+            const w_z = z * cell_slice;
+            for (let y = 0; y <= res_y; y++) {
+                const f_y = f_z + y * res_x;
+                const ya = y > 0 ? y - 1 : 0;
+                const yb = y < res_y ? y : last_cy;
+                const u_lo = u_z + ya * sx;
+                const u_hi = u_z + yb * sx;
+                const w_lo = w_z + ya * res_x;
+                const w_hi = w_z + yb * res_x;
+                for (let x = 0; x < res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_y[f] !== 0) {
+                        if (pass === 0) fwd_v[f] = src_v[f];
+                        else out_v[f] = src_v[f];
+                        continue;
+                    }
+                    const cu = 0.25 * (car_u[u_lo + x] + car_u[u_lo + x + 1] + car_u[u_hi + x] + car_u[u_hi + x + 1]);
+                    const cv = car_v[f];
+                    const cw = 0.25 * (car_w[w_lo + x] + car_w[w_lo + x + cell_slice] + car_w[w_hi + x] + car_w[w_hi + x + cell_slice]);
+                    const py = y - 0.5;
+
+                    let bx = x - cu * dt;
+                    let by = py - cv * dt;
+                    let bz = z - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, py, z, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_v[f] = scs3d_sample_linear(src_v, res_x, sy, res_z, bx, by + 0.5, bz);
+                        continue;
+                    }
+
+                    let qx = x + cu * dt;
+                    let qy = py + cv * dt;
+                    let qz = z + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, py, z, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_v, res_x, sy, res_z, qx, qy + 0.5, qz);
+                    const corrected = fwd_v[f] + 0.5 * (src_v[f] - backward);
+
+                    out_v[f] = limit8(corrected, src_v,
+                        bx, by + 0.5, bz,
+                        res_x, sy, res_z, res_x, v_slice);
+                }
+            }
+        }
+    }
+
+    // ─── w (z-faces): face (x,y,z) sits at (x, y, z − 0.5) ──────────────────
+    for (let pass = 0; pass < 2; pass++) {
+        for (let z = 0; z <= res_z; z++) {
+            const f_z = z * cell_slice;
+            const za = z > 0 ? z - 1 : 0;
+            const zb = z < res_z ? z : last_cz;
+            const u_lo = za * u_slice;
+            const u_hi = zb * u_slice;
+            const v_lo = za * v_slice;
+            const v_hi = zb * v_slice;
+            for (let y = 0; y < res_y; y++) {
+                const f_y = f_z + y * res_x;
+                const u_row_lo = u_lo + y * sx;
+                const u_row_hi = u_hi + y * sx;
+                const v_row_lo = v_lo + y * res_x;
+                const v_row_hi = v_hi + y * res_x;
+                for (let x = 0; x < res_x; x++) {
+                    const f = f_y + x;
+                    if (face_solid_z[f] !== 0) {
+                        if (pass === 0) fwd_w[f] = src_w[f];
+                        else out_w[f] = src_w[f];
+                        continue;
+                    }
+                    const cu = 0.25 * (car_u[u_row_lo + x] + car_u[u_row_lo + x + 1] + car_u[u_row_hi + x] + car_u[u_row_hi + x + 1]);
+                    const cv = 0.25 * (car_v[v_row_lo + x] + car_v[v_row_lo + x + res_x] + car_v[v_row_hi + x] + car_v[v_row_hi + x + res_x]);
+                    const cw = car_w[f];
+                    const pz = z - 0.5;
+
+                    let bx = x - cu * dt;
+                    let by = y - cv * dt;
+                    let bz = pz - cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, bx, by, bz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, pz, bx, by, bz);
+                        bx = scratch_clip[0]; by = scratch_clip[1]; bz = scratch_clip[2];
+                    }
+
+                    if (pass === 0) {
+                        fwd_w[f] = scs3d_sample_linear(src_w, res_x, res_y, sz, bx, by, bz + 0.5);
+                        continue;
+                    }
+
+                    let qx = x + cu * dt;
+                    let qy = y + cv * dt;
+                    let qz = pz + cw * dt;
+                    if (end_in_solid(solid, res_x, res_y, res_z, qx, qy, qz)) {
+                        v3_mac_clip_trace(scratch_clip, solid, res_x, res_y, res_z, x, y, pz, qx, qy, qz);
+                        qx = scratch_clip[0]; qy = scratch_clip[1]; qz = scratch_clip[2];
+                    }
+                    const backward = scs3d_sample_linear(fwd_w, res_x, res_y, sz, qx, qy, qz + 0.5);
+                    const corrected = fwd_w[f] + 0.5 * (src_w[f] - backward);
+
+                    out_w[f] = limit8(corrected, src_w,
+                        bx, by, bz + 0.5,
+                        res_x, res_y, sz, res_x, cell_slice);
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Clamp `value` to the min/max of the 8 lattice taps around the fractional
+ * position `(lx, ly, lz)` in the lattice's own index space (clamped to its
+ * bounds — the same corner set the trilinear sampler interpolates from).
+ *
+ * @param {number} value
+ * @param {Float32Array} data
+ * @param {number} lx
+ * @param {number} ly
+ * @param {number} lz
+ * @param {number} dim_x
+ * @param {number} dim_y
+ * @param {number} dim_z
+ * @param {number} row    lattice row stride
+ * @param {number} slice  lattice slice stride
+ * @return {number}
+ */
+function limit8(value, data, lx, ly, lz, dim_x, dim_y, dim_z, row, slice) {
+    const bx = clamp(lx, 0, dim_x - 1);
+    const by = clamp(ly, 0, dim_y - 1);
+    const bz = clamp(lz, 0, dim_z - 1);
+    const x0 = bx | 0;
+    const y0 = by | 0;
+    const z0 = bz | 0;
+    const x1 = bx === x0 ? x0 : x0 + 1;
+    const y1 = by === y0 ? y0 : y0 + 1;
+    const z1 = bz === z0 ? z0 : z0 + 1;
+
+    const z0_off = z0 * slice;
+    const z1_off = z1 * slice;
+    const y0_off = y0 * row;
+    const y1_off = y1 * row;
+
+    let mn = data[z0_off + y0_off + x0];
+    let mx = mn;
+    let v = data[z0_off + y0_off + x1]; if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z0_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z0_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y0_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y0_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y1_off + x0];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    v = data[z1_off + y1_off + x1];     if (v < mn) mn = v; else if (v > mx) mx = v;
+    return value < mn ? mn : (value > mx ? mx : value);
+}