@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/physics/fluid/FluidSimulator.js

@@ -1,7 +1,10 @@
 import { assert } from "../../../core/assert.js";
-import { optimal_sor_omega } from "./solver/optimal_sor_omega.js";
-import { v3_grid_apply_advection_forward } from "./solver/v3_grid_apply_advection_forward.js";
+import { sor_optimal_omega } from "../../../core/math/linalg/sor_optimal_omega.js";
+import { v3_grid_advect_maccormack_scalar } from "./solver/v3_grid_advect_maccormack_scalar.js";
+import { v3_grid_advect_maccormack_velocity } from "./solver/v3_grid_advect_maccormack_velocity.js";
+import { v3_grid_advect_sl_velocity } from "./solver/v3_grid_advect_sl_velocity.js";
 import { v3_grid_apply_diffusion } from "./solver/v3_grid_apply_diffusion.js";
+import { v3_grid_apply_vorticity_confinement } from "./solver/v3_grid_apply_vorticity_confinement.js";
 import { v3_grid_apply_scalar_advection } from "./solver/v3_grid_apply_scalar_advection.js";
 import { v3_grid_compute_divergence } from "./solver/v3_grid_compute_divergence.js";
 import { v3_grid_solve_pressure } from "./solver/v3_grid_solve_pressure.js";
@@ -30,6 +33,27 @@ export const PressureSolver = {
     MICPCG: "mic-pcg",
 };
 
+/**
+ * Velocity / scalar transport scheme selection.
+ *
+ *   - `"semi-lagrangian"` — first-order back-trace + trilinear gather (Stam
+ *     1999). Cheapest; strongly dissipative — a vortex loses half its kinetic
+ *     energy per second at production settings (see quality.spec.js).
+ *
+ *   - `"maccormack"` — unconditionally stable MacCormack (Selle et al. 2008):
+ *     a forward and a backward semi-Lagrangian pass with error correction and
+ *     a monotone min-max limiter. Second-order accurate in space and time at
+ *     ~2× the advection cost — and advection is the minority of step() cost
+ *     next to pressure, so the end-to-end price is small. Allocates 3
+ *     additional N-sized scratch buffers, shared with the reflection scheme.
+ *
+ * @enum {string}
+ */
+export const AdvectionScheme = {
+    SEMI_LAGRANGIAN: "semi-lagrangian",
+    MACCORMACK: "maccormack",
+};
+
 /**
  * Cell-centered 3D Stable Fluids solver (Stam, 1999/2003).
  *
@@ -41,12 +65,16 @@ export const PressureSolver = {
  * the field). Scratch is cached by cell-count so per-step allocation stays at zero.
  *
  * Per step:
- *   1. Apply external forces (effectors mutate field velocity).
+ *   1. Apply external forces (effectors mutate field velocity), then the
+ *      optional exponential velocity damping.
  *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
- *   3. Project (pressure solve + gradient subtract) to enforce ∇·v ≈ 0.
- *   4. Self-advect velocity (semi-Lagrangian back-trace).
- *   5. Project again (advection introduces small divergence).
- *   6. For each scalar attribute on the field: optionally diffuse, then advect.
+ *   3-5. Transport block — either the Stam reference sequence
+ *      project₁ → advect → project₂, or (default) the advection-reflection
+ *      form of the same two projections (see {@link advection_reflection}).
+ *      Advection itself is semi-Lagrangian or MacCormack per
+ *      {@link advection_scheme}.
+ *   6. For each scalar attribute on the field: optionally diffuse, then advect
+ *      with the same scheme.
  *
  * Pressure is warm-started from the previous step's solution (`field.pressure`),
  * which converges much faster than starting from zero once the flow reaches a
@@ -69,6 +97,25 @@ export const PressureSolver = {
  */
 export const PRESSURE_ITERATIONS_FLOOR = 8;
 
+/**
+ * Relative convergence tolerance handed to the MIC-PCG pressure solve: the
+ * solver stops as soon as `max|r| <= tolerance * max|−div|`. The iteration
+ * cap from {@link FluidSimulator#resolvePressureIterations} is sized for the
+ * cold-start worst case; warm-started production frames converge much
+ * earlier, and without a tolerance exit every warm frame would pay the full
+ * cold-start budget for no quality gain.
+ *
+ * 1e-3 sits below visual-fluids noticeability and below the collocated
+ * operator-mismatch floor that dominates post-projection divergence (see
+ * quality.spec.js) — iterating past it buys nothing visible.
+ *
+ * SOR has no equivalent exit: it never computes its residual (doing so would
+ * add a pass per sweep), so its cost is governed by the iteration count alone.
+ *
+ * @type {number}
+ */
+export const PCG_RELATIVE_TOLERANCE = 1e-3;
+
 export class FluidSimulator {
 
     /**
@@ -97,6 +144,28 @@ export class FluidSimulator {
      */
     scalar_diffusion_iterations = 4;
 
+    /**
+     * Exponential velocity damping rate, per second. Each step multiplies the
+     * whole velocity field by `exp(-velocity_damping * dt)` right after
+     * effectors run. `0` (default) disables — no pass is made.
+     *
+     * Why it exists: the solver has no other dissipation mechanism that bounds
+     * energy under sustained forcing. Incompressible projection cannot oppose
+     * a uniform body force (a uniform field is divergence-free), so a constant
+     * {@link GlobalFluidEffector} accelerates the fluid without limit — there
+     * is no terminal state. A small damping rate gives constant forcing a
+     * terminal velocity of approximately `acceleration / velocity_damping`
+     * and makes transient gusts decay back to calm, which is what wind-field
+     * use cases want (drive with {@link AmbientWindFluidEffector} for a
+     * specific ambient target instead of a force).
+     *
+     * The exponential form is frame-rate independent: two half-steps damp
+     * exactly as much as one full step.
+     *
+     * @type {number}
+     */
+    velocity_damping = 0;
+
     /**
      * Which pressure solver to use. `PressureSolver.SOR` (default) is the
      * baseline red-black Successive Over-Relaxation. `PressureSolver.MICPCG`
@@ -115,6 +184,77 @@ export class FluidSimulator {
      */
     pressure_solver = PressureSolver.SOR;
 
+    /**
+     * Vorticity-confinement strength ε, per second (Fedkiw et al. 2001). Each
+     * step deposits `ε·dt·(N × ω)` as a velocity increment, sharpening vortex
+     * cores that coarse grids and dissipative transport smear away. `0`
+     * (default) disables — no pass is made.
+     *
+     * Confinement ADDS energy by design; pair non-zero values with
+     * {@link velocity_damping} so gusts still decay. Visual-smoke territory
+     * starts around `ε ≈ 5–30` at 60 Hz (epsilon_dt 0.1–0.5).
+     *
+     * Cost when enabled: two extra O(N) passes (curl + force) using existing
+     * scratch — no allocations.
+     *
+     * @type {number}
+     */
+    vorticity_confinement = 0;
+
+    /**
+     * Which transport scheme advects velocity and scalars — see
+     * {@link AdvectionScheme}.
+     *
+     * **Default semi-Lagrangian — MacCormack is gated on a MAC-staggered
+     * grid.** On the current collocated discretization the projection has an
+     * operator-mismatch floor (high-frequency divergence it cannot see, let
+     * alone remove — quality.spec.js scenario 7), and MacCormack's
+     * anti-diffusive corrector amplifies exactly that residue instead of
+     * letting first-order smearing absorb it. Measured on the sealed-vortex
+     * scenario: kinetic energy transiently grows to **1.9×** within 10 s
+     * (vs SL's monotone decay), and a passive scalar's total mass inflates
+     * **1.8×** in one second of orbiting. The kernels are correct in
+     * isolation (their specs transport clean fields sharply and monotonely) —
+     * it is the interaction with the collocated pressure floor that is
+     * unstable. Flip this on once the grid is staggered.
+     *
+     * @type {string}
+     */
+    advection_scheme = AdvectionScheme.SEMI_LAGRANGIAN;
+
+    /**
+     * Replace the plain "project → advect → project" sequence with the
+     * advection-reflection scheme (Zehnder, Narain, Thomaszewski 2018):
+     *
+     *     ũ  = advect(u, u, dt/2)        — half-step self-advection
+     *     u½ = project(ũ)
+     *     û  = 2·u½ − ũ                  — energy-preserving reflection
+     *     u′ = advect(û, u½, dt/2)       — transport the REFLECTED field
+     *                                       along the PROJECTED one
+     *     u₁ = project(u′)
+     *
+     * Same two pressure solves as the default double-projection Stam step,
+     * and two half-dt advections instead of one full-dt one — measured cost
+     * +20% of step() at 32×8×32. The reflection replaces the
+     * energy-DISSIPATING first projection with an energy-PRESERVING
+     * reflection about the divergence-free subspace.
+     *
+     * Default ON: with semi-Lagrangian advection this is measured stable
+     * (sealed-vortex kinetic energy never exceeds 0.99× its initial over
+     * 10 s) while retaining visibly more swirl — peak vorticity 0.73 vs 0.62
+     * after one second (quality.spec.js scenario 2b). With MacCormack it
+     * compounds the collocated-floor amplification (3.4× energy growth) —
+     * see {@link advection_scheme}; that combination should wait for MAC
+     * staggering.
+     *
+     * Only consulted when {@link project_before_advection} is true — the
+     * scheme is defined around the mid-step projection. With
+     * `project_before_advection = false` this flag is ignored.
+     *
+     * @type {boolean}
+     */
+    advection_reflection = true;
+
     /**
      * Run the pressure projection *before* self-advection in addition to after.
      *
@@ -200,6 +340,14 @@ export class FluidSimulator {
     /** @type {Float32Array|null} */ #pcg_As = null;
     /** @type {Float32Array|null} */ #pcg_precon = null;
 
+    // Auxiliary velocity trio (allocated lazily): MacCormack's forward-pass
+    // scratch AND the reflection scheme's ũ snapshot — the two uses never
+    // overlap in time within a step.
+    #aux_scratch_cells = 0;
+    /** @type {Float32Array|null} */ #aux_x = null;
+    /** @type {Float32Array|null} */ #aux_y = null;
+    /** @type {Float32Array|null} */ #aux_z = null;
+
     /**
      * Grow the cached scratch buffers if the requested size exceeds what's allocated.
      * Idempotent and monotonic — never shrinks. Called at the top of {@link step} and
@@ -236,6 +384,59 @@ export class FluidSimulator {
         this.#pcg_precon = new Float32Array(cell_count);
     }
 
+    /**
+     * Lazily allocate the auxiliary velocity trio (3 N-sized Float32 buffers)
+     * used by MacCormack advection and the reflection scheme. Idempotent and
+     * monotonic.
+     * @param {number} cell_count
+     */
+    #ensure_aux_scratch(cell_count) {
+        if (this.#aux_scratch_cells >= cell_count) {
+            return;
+        }
+        this.#aux_scratch_cells = cell_count;
+        this.#aux_x = new Float32Array(cell_count);
+        this.#aux_y = new Float32Array(cell_count);
+        this.#aux_z = new Float32Array(cell_count);
+    }
+
+    /**
+     * Advect the field's velocity from `sources` along the given carrier, into
+     * the field's velocity buffers, using the configured
+     * {@link advection_scheme}. The carrier may alias the field's own velocity
+     * arrays (it is point-read only); sources must not.
+     *
+     * @param {FluidField} field
+     * @param {number[]} res
+     * @param {number} dt
+     * @param {Float32Array[]} sources    `[src_x, src_y, src_z]`
+     * @param {Float32Array} carrier_x
+     * @param {Float32Array} carrier_y
+     * @param {Float32Array} carrier_z
+     */
+    #advect_velocity(field, res, dt, sources, carrier_x, carrier_y, carrier_z) {
+        const outputs = [field.velocity_x, field.velocity_y, field.velocity_z];
+        if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
+            this.#ensure_aux_scratch(field.cellCount());
+            v3_grid_advect_maccormack_velocity(
+                outputs, sources,
+                carrier_x, carrier_y, carrier_z,
+                [this.#aux_x, this.#aux_y, this.#aux_z],
+                res[0], res[1], res[2],
+                dt,
+                field.solid
+            );
+        } else {
+            v3_grid_advect_sl_velocity(
+                outputs, sources,
+                carrier_x, carrier_y, carrier_z,
+                res[0], res[1], res[2],
+                dt,
+                field.solid
+            );
+        }
+    }
+
     /**
      * Re-allocate the divergence scratch buffer if its element type doesn't match
      * the field's pressure type. Lets `half_precision_pressure` on the field carry
@@ -282,9 +483,24 @@ export class FluidSimulator {
      * because tests and external code may need to project on demand (e.g., after
      * splatting an out-of-band impulse). `field.pressure` is read as the warm-start
      * initial guess and written with the new solution.
+     *
+     * Refreshes the field's solid-neighbour mask itself, so direct callers never
+     * have to remember invalidation after mutating solids. {@link step} refreshes
+     * the mask once for the whole step and uses the private no-recompute variant
+     * for both of its projections.
+     *
      * @param {FluidField} field
      */
     project(field) {
+        field.recomputeSolidNeighbourMask();
+        this.#project_with_current_mask(field);
+    }
+
+    /**
+     * Projection body — assumes `field.solid_neighbour_mask` is already fresh.
+     * @param {FluidField} field
+     */
+    #project_with_current_mask(field) {
         this.#ensure_scratch(field.cellCount());
         this.#ensure_divergence_matches(field);
 
@@ -296,12 +512,6 @@ export class FluidSimulator {
             return;
         }
 
-        // Pre-bake the per-cell neighbourhood mask consumed by the pressure SOR
-        // loop. One O(N) byte-pass amortized across `iterations` SOR sweeps;
-        // saves six boundary checks plus six solid-neighbour checks per cell per
-        // iteration. See FluidField.solid_neighbour_mask.
-        field.recomputeSolidNeighbourMask();
-
         v3_grid_compute_divergence(
             this.#divergence,
             field.velocity_x, field.velocity_y, field.velocity_z,
@@ -314,8 +524,8 @@ export class FluidSimulator {
             v3_grid_solve_pressure_pcg(
                 field.pressure, this.#divergence,
                 res[0], res[1], res[2],
-                iterations,
-                field.solid_neighbour_mask,
+                iterations, PCG_RELATIVE_TOLERANCE,
+                field.solid_neighbour_mask, field.pressure_diag,
                 this.#pcg_r, this.#pcg_z, this.#pcg_s, this.#pcg_As, this.#pcg_precon
             );
         } else {
@@ -323,8 +533,8 @@ export class FluidSimulator {
                 field.pressure, this.#divergence,
                 res[0], res[1], res[2],
                 iterations,
-                optimal_sor_omega(res[0], res[1], res[2]),
-                field.solid_neighbour_mask
+                sor_optimal_omega(res[0], res[1], res[2]),
+                field.solid_neighbour_mask, field.pressure_diag
             );
         }
 
@@ -394,6 +604,41 @@ export class FluidSimulator {
             effectors[i].apply(field, time_delta, world_to_grid);
         }
 
+        // 1b. Velocity damping — the solver's only energy sink under sustained
+        //     forcing. Solid cells are included in the multiply (their velocity
+        //     is 0, so damping them is a no-op and the loop stays branch-free).
+        if (this.velocity_damping > 0) {
+            const decay = Math.exp(-this.velocity_damping * time_delta);
+            const vx = field.velocity_x;
+            const vy = field.velocity_y;
+            const vz = field.velocity_z;
+            for (let i = 0; i < cell_count; i++) {
+                vx[i] *= decay;
+                vy[i] *= decay;
+                vz[i] *= decay;
+            }
+        }
+
+        // 1c. Vorticity confinement — an additional force term that sharpens
+        //     vortex cores (see the knob's docstring). Uses the prev trio and
+        //     the diffusion scratch as working memory; both are overwritten by
+        //     later phases anyway.
+        if (this.vorticity_confinement > 0) {
+            v3_grid_apply_vorticity_confinement(
+                field.velocity_x, field.velocity_y, field.velocity_z,
+                this.#prev_x, this.#prev_y, this.#prev_z, this.#diffusion_scratch,
+                res[0], res[1], res[2],
+                this.vorticity_confinement * time_delta,
+                field.solid
+            );
+        }
+
+        // Refresh the pre-baked solid-neighbour mask ONCE for the whole step —
+        // after effectors (a custom effector may splat solids), before anything
+        // that consumes it. Both projections below reuse it, saving an O(N)
+        // byte pass versus recomputing per projection.
+        field.recomputeSolidNeighbourMask();
+
         const solid = field.solid;
 
         // 2. Velocity diffusion (viscosity). Cheap to skip when disabled.
@@ -403,28 +648,64 @@ export class FluidSimulator {
             this.#diffuse_velocity_component(field.velocity_z, this.#prev_z, res, solid);
         }
 
-        // 3. Project to enforce incompressibility before advection. Skipping this
-        //    is a perf knob (~halves the pressure cost) at the price of advection
-        //    seeing a slightly-divergent input. See `project_before_advection`.
-        if (this.project_before_advection) {
-            this.project(field);
-        }
+        // 3-5. Transport block: project + self-advect (+ optional reflection).
+        const prev = [this.#prev_x, this.#prev_y, this.#prev_z];
+
+        if (this.project_before_advection && this.advection_reflection) {
+            // Advection-reflection (Zehnder et al. 2018), half-step form — see
+            // the `advection_reflection` docstring. Same two projections as the
+            // plain path; two half-dt advections instead of one full-dt one.
+            const half_dt = 0.5 * time_delta;
+            const n = cell_count;
+
+            // ũ = advect(u, u, dt/2)
+            this.#prev_x.set(field.velocity_x);
+            this.#prev_y.set(field.velocity_y);
+            this.#prev_z.set(field.velocity_z);
+            this.#advect_velocity(field, res, half_dt, prev, this.#prev_x, this.#prev_y, this.#prev_z);
+
+            // Snapshot ũ (after the advect — MacCormack uses the same aux trio
+            // as its forward scratch during the kernel).
+            this.#ensure_aux_scratch(n);
+            this.#aux_x.set(field.velocity_x);
+            this.#aux_y.set(field.velocity_y);
+            this.#aux_z.set(field.velocity_z);
+
+            // u½ = project(ũ)
+            this.#project_with_current_mask(field);
+
+            // û = 2·u½ − ũ — the reflection about the divergence-free subspace.
+            const ax = this.#aux_x, ay = this.#aux_y, az = this.#aux_z;
+            const fx = field.velocity_x, fy = field.velocity_y, fz = field.velocity_z;
+            const px = this.#prev_x, py = this.#prev_y, pz = this.#prev_z;
+            for (let i = 0; i < n; i++) {
+                px[i] = 2 * fx[i] - ax[i];
+                py[i] = 2 * fy[i] - ay[i];
+                pz[i] = 2 * fz[i] - az[i];
+            }
 
-        // 4. Self-advect velocity (semi-Lagrangian back-trace through the projected field).
-        this.#prev_x.set(field.velocity_x);
-        this.#prev_y.set(field.velocity_y);
-        this.#prev_z.set(field.velocity_z);
+            // u′ = advect(û, u½, dt/2). Output aliases the carrier (the field's
+            // own velocity) — allowed, the carrier is point-read only.
+            this.#advect_velocity(field, res, half_dt, prev, fx, fy, fz);
 
-        v3_grid_apply_advection_forward(
-            [field.velocity_x, field.velocity_y, field.velocity_z],
-            [this.#prev_x, this.#prev_y, this.#prev_z],
-            res[0], res[1], res[2],
-            time_delta,
-            solid
-        );
+            // u₁ = project(u′)
+            this.#project_with_current_mask(field);
+        } else {
+            // Stam reference sequence: project₁ (optional) → advect → project₂.
+            if (this.project_before_advection) {
+                this.#project_with_current_mask(field);
+            }
 
-        // 5. Re-project after advection.
-        this.project(field);
+            this.#prev_x.set(field.velocity_x);
+            this.#prev_y.set(field.velocity_y);
+            this.#prev_z.set(field.velocity_z);
+            this.#advect_velocity(field, res, time_delta, prev, this.#prev_x, this.#prev_y, this.#prev_z);
+
+            // Re-project after advection. Solids cannot have changed since the
+            // top-of-step mask refresh (only the simulator has touched the
+            // field), so the mask is still fresh.
+            this.#project_with_current_mask(field);
+        }
 
         // 6. Transport each passive scalar by the now-finalized velocity field.
         const scalars = field.getScalarAttributes();
@@ -443,13 +724,25 @@ export class FluidSimulator {
             }
 
             this.#scalar_scratch.set(attr.data);
-            v3_grid_apply_scalar_advection(
-                attr.data, this.#scalar_scratch,
-                field.velocity_x, field.velocity_y, field.velocity_z,
-                res[0], res[1], res[2],
-                time_delta,
-                solid
-            );
+            if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
+                // #diffusion_scratch is free here (the optional diffusion above
+                // has fully consumed it) — reuse it as the forward-pass buffer.
+                v3_grid_advect_maccormack_scalar(
+                    attr.data, this.#scalar_scratch, this.#diffusion_scratch,
+                    field.velocity_x, field.velocity_y, field.velocity_z,
+                    res[0], res[1], res[2],
+                    time_delta,
+                    solid
+                );
+            } else {
+                v3_grid_apply_scalar_advection(
+                    attr.data, this.#scalar_scratch,
+                    field.velocity_x, field.velocity_y, field.velocity_z,
+                    res[0], res[1], res[2],
+                    time_delta,
+                    solid
+                );
+            }
         }
     }
 }

package/src/engine/physics/fluid/REVIEW_02_PLAN.md

@@ -0,0 +1,114 @@
+# Fluid review 02 — quality-gated solver upgrades
+
+Working doc for the staged execution of the 2026-06-12 fluid review. Each stage
+must leave `quality.spec.js` green; when a stage improves a metric its baseline
+is tightened in the same change. Constraints: single-core JS, real-time ECS,
+public API of effectors + `FluidField` frozen (state shape may change).
+
+## Quality gate baselines (quality.spec.js)
+
+| metric | stage 0 (baseline) | stage 1 | stage 2 | stage 3 | notes |
+|---|---|---|---|---|---|
+| projection linear residual, SOR | 1.21 | 1.21 | 0.67 | | RHS max\|div\| ≈ 14.5, 16³, 8 sweeps |
+| projection linear residual, PCG | 3.34e-2 | 3.34e-2 | 1.16e-2 | | iteration-capped, not noise |
+| cold post-div (operator floor) | 11.2 | 11.2 | 9.1 | | collocated floor — the MAC metric |
+| warm post-div, SOR | 9.22 | 9.22 | **0.70** | **0.35** | open edges vent + reflection projects cleaner |
+| warm post-div, PCG | 1.84 | 1.84 | **0.70** | **0.35** | tolerance exit: same quality, fewer iters |
+| vortex KE retention (60 steps) | 0.498 | 0.498 | 0.495 | **0.527** | sealed-box scenario, default scheme |
+| vortex peak-ω retention | 0.606 | 0.606 | 0.624 | **0.725** | reflection keeps swirl alive |
+| wall penetration (seed 8) | 5.72 | 5.72 | 6.96 | 6.65 | collocated solid BC weakness — the MAC metric |
+| scalar mass retention | 0.231 | 0.231 | **0.849** | 0.837 | real walls project consistently near boundary |
+| diffusion wall leak | 16.9 | **0** | 0 | 0 | fixed: no-flux on both wall sides |
+| sealed-box gravity max\|vy\| | 1.24 | 1.24 | 1.24 | **0.97** | semi-hydrostatic |
+| checkerboard residual (10 steps) | 0.593 | 0.593 | 0.627 | 0.587 | projection-invisible null mode |
+| damped gravity terminal \|v\| | — | — | 4.92 = analytic | 4.92 | bounded forcing (was unbounded growth) |
+| ambient wind target tracking | — | — | 8.00/8 | 8.00/8 | AmbientWindFluidEffector holds target |
+| step() 32×8×32 (ms) | 1.16 | | 1.44 | 1.10* | *SL+refl after stage-3 sampler fusion; stage-4 still owes SOR work |
+
+Perf reference (review probe, this machine): step() 32×8×32 = 1.16 ms,
+32³ = 4.4 ms, 64³ = 54 ms. Division→reciprocal-table in SOR measured 14%
+SLOWER in V8 — do not do it.
+
+## Stages
+
+- [x] **Stage 0 — quality gate.** `quality.spec.js`: 8 deterministic scenarios,
+  baselines baked, runs by default (no timing). Deep sweeps stay in
+  `bench.spec.js`.
+- [x] **Stage 1 — bug fixes.** (183 fluid tests green; quality gate unchanged
+  except the leak metric dropping to exactly 0.)
+  - Wake effector: trail advance moves out of `apply()` for transform-managed
+    effectors (multi-field contract).
+  - Diffusion: no-flux at solid neighbours (walls stop acting as
+    sources/sinks); neighbour mask recomputed once at top of `step()`.
+  - `FluidField.shift`: migrate the solid mask (zero-fill exposed cells)
+    instead of clearing it — removes the one-tick wall-less window after every
+    re-anchor shift.
+  - PCG: relative-tolerance early exit (cap unchanged).
+- [x] **Stage 2 — boundary semantics + forcing stability.** (195 fluid tests
+  green. New `FluidField.pressure_diag` derived buffer carries the per-cell
+  Laplacian diagonal; mask kernel bakes both in one pass.)
+  - Domain edges are OPEN (ghost p = 0): out-of-bounds faces count in the
+    Laplacian diagonal and read zero pressure; solid faces stay reflecting
+    (Neumann). Sealed boxes are built explicitly with solid cells (see
+    `seal_box` in quality.spec.js).
+  - PCG null-space mean-subtraction made conditional — only for fully sealed
+    fields (open systems are non-singular; subtracting the mean there would
+    solve a different RHS). Disconnected sealed pockets remain a documented
+    limitation.
+  - `velocity_damping` knob on the simulator (exponential, default 0) — the
+    solver's only energy sink under sustained forcing; gives constant forces
+    a terminal velocity.
+  - New `AmbientWindFluidEffector` — relaxes toward a target wind velocity
+    instead of integrating constant acceleration (no unbounded accumulation;
+    frame-rate independent).
+- [x] **Stage 3 — transport quality.** (213 tests green.)
+  - Fused 3-channel trilinear sampler (`scs3d_sample_linear3`); generalized
+    SL velocity kernel with separate carrier; MacCormack velocity + scalar
+    kernels with Selle's monotone limiter; `AdvectionScheme` enum;
+    `advection_reflection` step structure (Zehnder 2018, half-step form).
+  - **Measured scheme matrix** (sealed vortex, ke / peak-ω retention @ 1 s;
+    step ms @ 32×8×32):
+    | combo | ke | ω | ms | 10 s stability |
+    |---|---|---|---|---|
+    | SL (Stam baseline) | 0.495 | 0.624 | 0.92 | stable |
+    | **SL + reflection (DEFAULT)** | 0.527 | 0.725 | 1.10 | stable (peak 0.99) |
+    | MacCormack | 0.773 | 0.640 | 1.35 | **unstable** (peak 1.91) |
+    | MacCormack + reflection | 1.016 | 1.081 | 2.49 | **unstable** (peak 3.44) |
+  - **Key negative finding:** on the collocated grid, MacCormack's
+    anti-diffusive corrector amplifies the projection's operator-floor
+    residue — transient energy growth ×1.9–3.4 within 10 s, and passive
+    scalar total mass inflates ×1.8 in one second. Damping 0.2 does not tame
+    it. The kernels are correct in isolation (specs); the INTERACTION with
+    the collocated pressure floor is the problem. **MacCormack is therefore
+    default-off and gated on MAC staggering** — this is the strongest
+    argument yet for stage 5.
+  - Defaults: `advection_scheme = SEMI_LAGRANGIAN`,
+    `advection_reflection = true`. Reflection alone is a clean win: stable,
+    +20% step cost, warm steady-state divergence halves again (0.71 → 0.35),
+    sealed-gravity settles better (1.24 → 0.97).
+- [ ] **Stage 4 — perf polish (bench-gated).**
+  - SOR interior fast path (mask == 63 branchless) — keep only if measured win.
+  - Optional vorticity-confinement knob (Fedkiw 2001), default off.
+- [ ] **Stage 5 — MAC staggering decision.** Present quality deltas (operator
+  floor, wall penetration, checkerboard) + consumer impact; **user decides**
+  before any layout change (it alters how `velocity_*` arrays are interpreted
+  by external readers).
+
+## Review findings driving this (2026-06-12 session)
+
+1. WakeFluidEffector mutates trail state in `apply()` → second field in the
+   same step sees a zero segment (confirmed: A=240, B=0).
+2. `v3_grid_apply_diffusion` gathers from solid neighbours → dye leak 16.9/100
+   through a wall in one step (confirmed).
+3. `FluidSystem` re-anchor shifts clear solids, then step runs immediately —
+   one tick with no walls per cell crossing.
+4. Closed Neumann edges + one-sided boundary divergence: uniform body force
+   produces zero discrete divergence → projection never opposes it → velocity
+   grows without bound (confirmed: −5/−10/−15 over 30/60/90 steps). No damping
+   term exists anywhere.
+5. Collocated grid: compact Laplacian ≠ div∘grad → checkerboard null mode
+   (interior div exactly 0 for ±1 mode, confirmed) + operator floor (cold
+   post-div 11.2 of 14.5 even with exact linear solve).
+6. Advection backtrace samples through/inside solids.
+7. PCG always runs the full SOR-scaled iteration budget (no tolerance exit);
+   mean-subtraction assumes a single connected fluid component.

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts

@@ -56,9 +56,10 @@ export class FluidComponent {
     /**
      * Half-cell extra margin (in cells) the Transform must cross before the field
      * re-quantizes to the next cell. Without it, a Transform jittering right on the
-     * boundary between two cells would re-shift every frame, repeatedly clearing the
-     * solid mask and patching velocity edges — visible as flicker in the fluid and
-     * thrashing in any solid-voxelizer downstream of the shift.
+     * boundary between two cells would re-shift every frame, sloshing every buffer
+     * back and forth and re-extrapolating the exposed edges each time — visible as
+     * flicker in the fluid and thrashing in any solid-voxelizer downstream of the
+     * shift.
      *
      * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
      * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the

package/src/engine/physics/fluid/ecs/FluidComponent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BAzO0B,kBAAkB"}
+{"version":3,"file":"FluidComponent.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/fluid/ecs/FluidComponent.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;OAEG;IACH,OAFU,UAAU,CAEK;IAEzB;;;;;;;OAOG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;;;;;;OAQG;IACH,QAFU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAEf;IAEnB;;;OAGG;IACH,WAFU,MAAM,CAEF;IAEd;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;OAKG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,iBANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAOhC;IAED;;;;;;;;;;;;;;OAcG;IACH,2BANW,YAAY,GAAC,MAAM,EAAE,MACrB,MAAM,MACN,MAAM,MACN,MAAM,GACL,YAAY,GAAC,MAAM,EAAE,CAQhC;IAED;;;;;;;OAOG;IACH,0BANW,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACL,MAAM,CAQjB;IAED;;;OAGG;IACH,cAHW,cAAc,GACb,OAAO,CAoBlB;IAED;;OAEG;IACH,QAFY,MAAM,CAgBjB;IAED;;;;;;;;OAQG;IACH,iCAYC;IAGL,0BAAyC;CAFxC;2BA1O0B,kBAAkB"}

package/src/engine/physics/fluid/ecs/FluidComponent.js

@@ -65,9 +65,10 @@ export class FluidComponent {
     /**
      * Half-cell extra margin (in cells) the Transform must cross before the field
      * re-quantizes to the next cell. Without it, a Transform jittering right on the
-     * boundary between two cells would re-shift every frame, repeatedly clearing the
-     * solid mask and patching velocity edges — visible as flicker in the fluid and
-     * thrashing in any solid-voxelizer downstream of the shift.
+     * boundary between two cells would re-shift every frame, sloshing every buffer
+     * back and forth and re-extrapolating the exposed edges each time — visible as
+     * flicker in the fluid and thrashing in any solid-voxelizer downstream of the
+     * shift.
      *
      * Mechanism: the system keeps the current quantized cell `q` and only re-quantizes
      * when `|transform.position / cell_size - q| > 0.5 + hysteresis`. Crossing the

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts

@@ -38,7 +38,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidEffectorsComponent} effectors_component
      * @param {Transform} transform
      */
-    static "__#139@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
+    static "__#141@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
     /**
      * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
      * grid origin locked to a cell-aligned position near the transform.
@@ -61,7 +61,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidComponent} component
      * @param {Transform} transform
      */
-    static "__#139@#reanchor_field"(component: FluidComponent, transform: Transform): void;
+    static "__#141@#reanchor_field"(component: FluidComponent, transform: Transform): void;
     /**
      * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
      * uniform-scale, so the matrix is sparse:
@@ -76,7 +76,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {Float32Array} out  length-16
      * @param {FluidComponent} component
      */
-    static "__#139@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    static "__#141@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**