@woosh/meep-engine 3.1.0 → 3.2.0

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

@@ -1,832 +1,832 @@
-import { assert } from "../../../core/assert.js";
-import { sor_optimal_omega } from "../../../core/math/linalg/sor_optimal_omega.js";
-import { v3_grid_apply_diffusion } from "./solver/v3_grid_apply_diffusion.js";
-import { v3_grid_solve_pressure } from "./solver/v3_grid_solve_pressure.js";
-import { v3_grid_solve_pressure_pcg } from "./solver/v3_grid_solve_pressure_pcg.js";
-import { v3_mac_advect_maccormack_velocity } from "./solver/v3_mac_advect_maccormack_velocity.js";
-import { v3_mac_advect_sl_velocity } from "./solver/v3_mac_advect_sl_velocity.js";
-import { v3_mac_advect_sl_scalar } from "./solver/v3_mac_advect_scalar.js";
-import { v3_mac_apply_vorticity_confinement } from "./solver/v3_mac_apply_vorticity_confinement.js";
-import { v3_mac_compute_divergence } from "./solver/v3_mac_compute_divergence.js";
-import { v3_mac_subtract_pressure_gradient } from "./solver/v3_mac_subtract_pressure_gradient.js";
-
-/**
- * Pressure solver selection. Both solve the same A·p = -div system over the
- * same neighbour-mask topology; the difference is convergence rate and per-iter
- * cost.
- *
- *   - `"sor"` — red-black Successive Over-Relaxation, our long-standing
- *     default. One sweep is cheap (~3-5 µs/cell at 128³), convergence is
- *     O(N) iterations for fixed accuracy.
- *
- *   - `"mic-pcg"` — Modified Incomplete Cholesky preconditioned Conjugate
- *     Gradient. ~2× the per-iter cost of SOR, but converges in O(√N) iters
- *     (typically 8-12 vs SOR's 30+ at 128³), so a net 1.5-2× speedup at
- *     quality parity for production grids. Allocates 5 additional N-sized
- *     scratch buffers (r, z, s, As, precon).
- *
- * @enum {string}
- */
-export const PressureSolver = {
-    SOR: "sor",
-    MICPCG: "mic-pcg",
-};
-
-/**
- * VELOCITY transport scheme selection. Passive scalars always use
- * semi-Lagrangian transport regardless of this setting — gather-form
- * MacCormack is non-conservative (the corrector re-adds roughly double the
- * gather bias; measured 1.7x total dye mass in one second of a sealed
- * vortex, independent of wall handling), and scalar conservation is a hard
- * requirement, not a preference.
- *
- *   - `"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.
- *     Allocates 3 additional face-lattice scratch buffers.
- *
- * @enum {string}
- */
-export const AdvectionScheme = {
-    SEMI_LAGRANGIAN: "semi-lagrangian",
-    MACCORMACK: "maccormack",
-};
-
-/**
- * 3D incompressible-flow solver on a MAC (staggered) grid — Stam's stable-
- * fluids step structure (1999/2003) with face-centered velocity (Harlow &
- * Welch 1965), an exact discrete Helmholtz projection, and optional
- * advection-reflection / MacCormack transport.
- *
- * Holds tuning knobs plus transient working memory (per-step velocity snapshots,
- * divergence, ping-pong scratch). None of that working memory carries information
- * across step boundaries — its value is overwritten before being read on the next
- * step. Replacing the simulator instance between two steps of the same field
- * produces an identical result (the only cross-step state, `pressure`, lives on
- * 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), then the
- *      optional exponential velocity damping.
- *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
- *   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 (always semi-Lagrangian — see {@link AdvectionScheme}).
- *
- * 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
- * quasi-steady state.
- *
- * Compute model: synchronous, main-thread. Cost scales linearly with cell count and
- * with iteration counts. The pressure SOR sweep count is auto-scaled to grid size
- * (see {@link pressure_iteration_scale}) so the per-cell budget stays roughly flat
- * across resolutions instead of over-spending at 32³ and under-spending at 256³.
- */
-/**
- * Minimum iteration count when `pressure_iteration_scale > 0`. Picked so very
- * small grids (8³, 16³) still get enough sweeps to converge — at those sizes
- * `scale * max_res` underflows the practical "useful work" zone. For grids
- * larger than `floor / scale` the scale formula dominates and this constant
- * stops mattering. Caller may inspect / override if a per-deployment minimum
- * makes sense.
- *
- * @type {number}
- */
-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 {
-
-    /**
-     * Implicit-diffusion coefficient (= viscosity * dt-like scaling). 0 disables.
-     * @type {number}
-     */
-    velocity_diffusion_rate = 0;
-
-    /**
-     * Jacobi iterations for the velocity diffusion solve. Only consulted when
-     * `velocity_diffusion_rate > 0`.
-     * @type {number}
-     */
-    velocity_diffusion_iterations = 4;
-
-    /**
-     * Implicit-diffusion coefficient applied uniformly to all scalar attributes. 0
-     * disables. Semi-Lagrangian advection already introduces visible numerical
-     * diffusion, so leaving this at 0 is usually fine.
-     * @type {number}
-     */
-    scalar_diffusion_rate = 0;
-
-    /**
-     * @type {number}
-     */
-    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 bare
-     * `force` on a {@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.
-     *
-     * Relationship to {@link GlobalFluidEffector#drag}: the effector's drag
-     * is the same operation expressed as SCENE CONTENT — it relaxes toward a
-     * configurable ambient wind and travels with the effector entity. This
-     * knob is the SOLVER-level stability primitive: it exists even when no
-     * effectors are wired, and always relaxes toward zero. Use the effector
-     * for atmosphere design; use this to guarantee boundedness.
-     *
-     * 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`
-     * switches to Modified Incomplete Cholesky preconditioned Conjugate
-     * Gradient, which typically converges in 1/3 the iterations at 2× per-iter
-     * cost (net ~1.5-2× faster wall time at quality parity on production
-     * grids). MIC-PCG allocates an additional 5 N-sized scratch buffers, so
-     * peak memory is higher.
-     *
-     * Switching at runtime is supported but flushes the warm-started pressure
-     * meaning for one step (both solvers warm-start from `field.pressure`,
-     * but the convergence trajectory is different — first frame after a
-     * switch will look "fresh", not warm).
-     *
-     * @type {string}
-     */
-    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 — see {@link AdvectionScheme}
-     * (scalars are always semi-Lagrangian; see the enum docstring for why).
-     *
-     * **Default MacCormack.** On the MAC grid with solid-clipped traces it is
-     * measured long-horizon stable (sealed-vortex energy peaks at 0.96x its
-     * initial over 10 s, monotone decay thereafter) and retains dramatically
-     * more energy than first-order transport: 0.80 vs 0.53 KE after one
-     * second (quality.spec.js scenario 2b).
-     *
-     * Do NOT combine with {@link advection_reflection}: the energy-preserving
-     * reflection re-injects the corrector overshoots and the pair pumps
-     * energy without bound (10 s peak 3.7x — measured both with and without
-     * trace clipping). Reflection is the companion for SEMI_LAGRANGIAN.
-     *
-     * @type {string}
-     */
-    advection_scheme = AdvectionScheme.MACCORMACK;
-
-    /**
-     * 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
-     * ~+70% of step() at 32×8×32 on the MAC lattices (each half-step pays the
-     * cross-component carrier sampling). The reflection replaces the
-     * energy-DISSIPATING first projection with an energy-PRESERVING
-     * reflection about the divergence-free subspace.
-     *
-     * With semi-Lagrangian advection this is measured stable (sealed-vortex
-     * kinetic energy never exceeds its initial over 10 s) while retaining
-     * visibly more swirl — peak vorticity 0.74 vs 0.68 after one second
-     * (quality.spec.js scenario 2b). Do NOT combine with MacCormack — the
-     * reflection re-injects the corrector overshoots (10 s energy peak
-     * 3.7x); see {@link advection_scheme}.
-     *
-     * 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.
-     *
-     * Default OFF: the default velocity scheme is MacCormack, with which the
-     * reflection is unstable (see {@link advection_scheme}). Enable it when
-     * running SEMI_LAGRANGIAN velocity transport — that pairing is measured
-     * stable and retains visibly more swirl than plain SL.
-     *
-     * @type {boolean}
-     */
-    advection_reflection = false;
-
-    /**
-     * Run the pressure projection *before* self-advection in addition to after.
-     *
-     * The Stam (1999/2003) reference solver projects twice per step:
-     *
-     *     [forces] → [diffuse] → **project₁** → [advect] → **project₂** → [scalars]
-     *
-     * `project₁` ensures the velocity field that's *fed into* semi-Lagrangian
-     * advection is divergence-free, so back-traced trajectories follow a physical
-     * flow. `project₂` cleans up the small divergence advection re-introduces.
-     *
-     * Skipping `project₁` (this flag = false) cuts the pressure-solve cost roughly
-     * in half — at default settings, pressure is ~80% of step() time, and the two
-     * projections share that ~evenly. The cost is that effectors' splatted
-     * impulses (which inject divergence) and any post-diffusion residual get
-     * carried into advection un-projected, then have to be cleaned up by the
-     * single post-advection projection.
-     *
-     * In practice:
-     *   - If diffusion is OFF (rate=0) and effectors are gentle (gentle wind, no
-     *     big impulses), the visual quality cost is small. The post-advection
-     *     project handles everything in roughly the same number of iterations.
-     *   - If diffusion is ON, or you have strong impulses (explosions, large
-     *     wakes), the second-only solver is asked to fix everything in one pass
-     *     and may visibly under-converge — flicker, "pumping", or divergent
-     *     vortices.
-     *
-     * Default `true` (= Stam reference behavior) for correctness; flip to `false`
-     * if profiling shows pressure as a bottleneck and quality A/B looks acceptable.
-     *
-     * @type {boolean}
-     */
-    project_before_advection = true;
-
-    /**
-     * Adaptive scaling factor for the pressure Poisson SOR sweep count. The actual
-     * iteration count per `project()` call is
-     *
-     *     iters = max(PRESSURE_ITERATIONS_FLOOR, ceil(pressure_iteration_scale * max(rx, ry, rz)))
-     *
-     * unless `pressure_iteration_scale <= 0`, in which case projection is skipped
-     * entirely (useful for tests that need to inspect un-projected velocity or
-     * tear-down scenarios).
-     *
-     * Why scaled by resolution? Red-black SOR with the optimal omega converges
-     * geometrically with a rate that depends on grid size — the iterations needed
-     * to reach a given residual scale roughly as `O(N)` where N is the max grid
-     * extent. A fixed iteration count therefore over-spends at small grids and
-     * under-spends at large ones; the default value of 30 (from the pre-adaptive
-     * era) was right for ~128³ but wasteful at 32³ and marginal at 256³.
-     *
-     * Default scale `0.25` plus floor `8` chosen empirically against the bench
-     * sweep in `bench.spec.js` (`pressure_iterations convergence + step() cost`)
-     * — it's the smallest setting that keeps a stress-test divergent velocity
-     * field stable under continuous stepping across the 32³ → 128³ range. For a
-     * gentler real-world flow you can drop the scale further; for cold-start
-     * spawn frames or scenes with heavy impulses, bump it up.
-     *
-     * @type {number}
-     */
-    pressure_iteration_scale = 0.25;
-
-    // ────────────────────────────────────────────────────────────────────────────
-    // Transient scratch — overwritten before read on every step. Cached and
-    // grown monotonically so we don't allocate per step. Their value never
-    // crosses a step boundary; if it did it would belong on the field (see
-    // `field.pressure`). Velocity-shaped buffers are sized per face lattice.
-    // ────────────────────────────────────────────────────────────────────────────
-
-    /** @type {Float32Array|null} */ #prev_x = null;
-    /** @type {Float32Array|null} */ #prev_y = null;
-    /** @type {Float32Array|null} */ #prev_z = null;
-    /** @type {Float32Array|null} */ #divergence = null;
-    /** @type {Float32Array|null} */ #diffusion_scratch = null;
-    /** @type {Float32Array|null} */ #scalar_scratch = null;
-
-    // PCG-only scratch (allocated lazily on first MICPCG-enabled project call).
-    #pcg_scratch_cells = 0;
-    /** @type {Float32Array|null} */ #pcg_r = null;
-    /** @type {Float32Array|null} */ #pcg_z = null;
-    /** @type {Float32Array|null} */ #pcg_s = null;
-    /** @type {Float32Array|null} */ #pcg_As = null;
-    /** @type {Float32Array|null} */ #pcg_precon = null;
-
-    // Auxiliary velocity trio (allocated lazily, face-lattice sized): the
-    // reflection scheme's ũ snapshot / carrier copy, and vorticity
-    // confinement's curl scratch — the uses never overlap in time.
-    /** @type {Float32Array|null} */ #aux_x = null;
-    /** @type {Float32Array|null} */ #aux_y = null;
-    /** @type {Float32Array|null} */ #aux_z = null;
-
-    // MacCormack forward-pass trio (allocated lazily, face-lattice sized).
-    // Deliberately separate from #aux: in the reflection path #aux holds the
-    // carrier during the very advection that needs this scratch.
-    /** @type {Float32Array|null} */ #mc_x = null;
-    /** @type {Float32Array|null} */ #mc_y = null;
-    /** @type {Float32Array|null} */ #mc_z = null;
-
-    /**
-     * Grow the cached scratch buffers to fit the field's lattices. The prev
-     * trio and the diffusion scratch are sized per FACE grid (the largest of
-     * which also covers every cell-count use); divergence and scalar scratch
-     * are cell-count. Idempotent and monotonic — never shrinks. Called at the
-     * top of {@link step} so user code never has to think about it.
-     * @param {FluidField} field
-     */
-    #ensure_scratch(field) {
-        const res = field.getResolution();
-        const n_u = (res[0] + 1) * res[1] * res[2];
-        const n_v = res[0] * (res[1] + 1) * res[2];
-        const n_w = res[0] * res[1] * (res[2] + 1);
-        const n_cell = field.cellCount();
-        const n_face_max = Math.max(n_u, n_v, n_w);
-
-        if (this.#prev_x === null || this.#prev_x.length < n_u) this.#prev_x = new Float32Array(n_u);
-        if (this.#prev_y === null || this.#prev_y.length < n_v) this.#prev_y = new Float32Array(n_v);
-        if (this.#prev_z === null || this.#prev_z.length < n_w) this.#prev_z = new Float32Array(n_w);
-        if (this.#diffusion_scratch === null || this.#diffusion_scratch.length < n_face_max) {
-            this.#diffusion_scratch = new Float32Array(n_face_max);
-        }
-        if (this.#scalar_scratch === null || this.#scalar_scratch.length < n_cell) {
-            this.#scalar_scratch = new Float32Array(n_cell);
-        }
-        // #divergence is dtype-tracked separately by #ensure_divergence_matches.
-    }
-
-    /**
-     * Lazily allocate the PCG-specific scratch (5 N-sized Float32 buffers).
-     * Idempotent and monotonic.
-     * @param {number} cell_count
-     */
-    #ensure_pcg_scratch(cell_count) {
-        if (this.#pcg_scratch_cells >= cell_count) {
-            return;
-        }
-        this.#pcg_scratch_cells = cell_count;
-        this.#pcg_r = new Float32Array(cell_count);
-        this.#pcg_z = new Float32Array(cell_count);
-        this.#pcg_s = new Float32Array(cell_count);
-        this.#pcg_As = new Float32Array(cell_count);
-        this.#pcg_precon = new Float32Array(cell_count);
-    }
-
-    /**
-     * Lazily allocate the auxiliary velocity trio (face-lattice sized) used by
-     * the reflection scheme and vorticity confinement. Idempotent and
-     * monotonic.
-     * @param {FluidField} field
-     */
-    #ensure_aux_scratch(field) {
-        const res = field.getResolution();
-        const n_u = (res[0] + 1) * res[1] * res[2];
-        const n_v = res[0] * (res[1] + 1) * res[2];
-        const n_w = res[0] * res[1] * (res[2] + 1);
-        if (this.#aux_x === null || this.#aux_x.length < n_u) this.#aux_x = new Float32Array(n_u);
-        if (this.#aux_y === null || this.#aux_y.length < n_v) this.#aux_y = new Float32Array(n_v);
-        if (this.#aux_z === null || this.#aux_z.length < n_w) this.#aux_z = new Float32Array(n_w);
-    }
-
-    /**
-     * Lazily allocate the MacCormack forward-pass trio (face-lattice sized).
-     * Idempotent and monotonic.
-     * @param {FluidField} field
-     */
-    #ensure_mc_scratch(field) {
-        const res = field.getResolution();
-        const n_u = (res[0] + 1) * res[1] * res[2];
-        const n_v = res[0] * (res[1] + 1) * res[2];
-        const n_w = res[0] * res[1] * (res[2] + 1);
-        if (this.#mc_x === null || this.#mc_x.length < n_u) this.#mc_x = new Float32Array(n_u);
-        if (this.#mc_y === null || this.#mc_y.length < n_v) this.#mc_y = new Float32Array(n_v);
-        if (this.#mc_z === null || this.#mc_z.length < n_w) this.#mc_z = new Float32Array(n_w);
-    }
-
-    /**
-     * 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; sources must not.
-     *
-     * @param {FluidField} field
-     * @param {number[]} res
-     * @param {number} dt
-     * @param {Float32Array[]} sources  `[src_u, src_v, src_w]` face grids
-     * @param {Float32Array[]} carrier  `[car_u, car_v, car_w]` face grids
-     */
-    #advect_velocity(field, res, dt, sources, carrier) {
-        const outputs = [field.velocity_x, field.velocity_y, field.velocity_z];
-        if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
-            this.#ensure_mc_scratch(field);
-            v3_mac_advect_maccormack_velocity(
-                outputs, sources, carrier,
-                [this.#mc_x, this.#mc_y, this.#mc_z],
-                res[0], res[1], res[2],
-                dt,
-                field.face_solid_x, field.face_solid_y, field.face_solid_z,
-                field.solid
-            );
-        } else {
-            v3_mac_advect_sl_velocity(
-                outputs, sources, carrier,
-                res[0], res[1], res[2],
-                dt,
-                field.face_solid_x, field.face_solid_y, field.face_solid_z,
-                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
-     * through into the SOR inner-loop bandwidth (the solver reads divergence and
-     * writes pressure of the same dtype).
-     *
-     * @param {FluidField} field
-     */
-    #ensure_divergence_matches(field) {
-        const desired_ctor = field.pressure.constructor;
-        const cell_count = field.cellCount();
-        if (this.#divergence === null
-            || this.#divergence.constructor !== desired_ctor
-            || this.#divergence.length < cell_count) {
-            this.#divergence = new desired_ctor(cell_count);
-        }
-    }
-
-    /**
-     * Resolve the per-call SOR iteration count from {@link pressure_iteration_scale}
-     * and the field's resolution. Public so callers can budget frame time or query
-     * the actual cost in advance.
-     *
-     *   - `scale <= 0` → 0 (projection disabled).
-     *   - `scale > 0`  → `max(PRESSURE_ITERATIONS_FLOOR, ceil(scale * max(rx, ry, rz)))`.
-     *
-     * @param {number} res_x
-     * @param {number} res_y
-     * @param {number} res_z
-     * @return {number} non-negative integer iteration count.
-     */
-    resolvePressureIterations(res_x, res_y, res_z) {
-        const scale = this.pressure_iteration_scale;
-        if (scale <= 0) {
-            return 0;
-        }
-        const max_res = res_x > res_y ? (res_x > res_z ? res_x : res_z) : (res_y > res_z ? res_y : res_z);
-        const scaled = Math.ceil(scale * max_res);
-        return scaled > PRESSURE_ITERATIONS_FLOOR ? scaled : PRESSURE_ITERATIONS_FLOOR;
-    }
-
-    /**
-     * Project the field's velocity to be (approximately) divergence-free. Exposed
-     * 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 the field's derived masks (cell neighbour
-     * mask, pressure diagonal, face pins) are already fresh.
-     *
-     * On the MAC layout this is an exact discrete Helmholtz projection: the
-     * face-difference divergence and the face gradient compose to exactly the
-     * 7-point Laplacian the solvers invert, so post-projection divergence is
-     * zero up to solver residual — including beside walls.
-     *
-     * @param {FluidField} field
-     */
-    #project_with_current_mask(field) {
-        this.#ensure_divergence_matches(field);
-
-        const res = field.getResolution();
-        const iterations = this.resolvePressureIterations(res[0], res[1], res[2]);
-
-        if (iterations === 0) {
-            return;
-        }
-
-        v3_mac_compute_divergence(
-            this.#divergence,
-            field.velocity_x, field.velocity_y, field.velocity_z,
-            res[0], res[1], res[2],
-            field.solid
-        );
-
-        if (this.pressure_solver === PressureSolver.MICPCG) {
-            this.#ensure_pcg_scratch(field.cellCount());
-            v3_grid_solve_pressure_pcg(
-                field.pressure, this.#divergence,
-                res[0], res[1], res[2],
-                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 {
-            v3_grid_solve_pressure(
-                field.pressure, this.#divergence,
-                res[0], res[1], res[2],
-                iterations,
-                sor_optimal_omega(res[0], res[1], res[2]),
-                field.solid_neighbour_mask, field.pressure_diag
-            );
-        }
-
-        v3_mac_subtract_pressure_gradient(
-            field.velocity_x, field.velocity_y, field.velocity_z,
-            field.pressure,
-            field.face_solid_x, field.face_solid_y, field.face_solid_z,
-            res[0], res[1], res[2]
-        );
-    }
-
-    /**
-     * Diffuse a single velocity component (one face lattice) in-place, using
-     * `source_copy_buf` as the "before" snapshot and `#diffusion_scratch` as
-     * the ping-pong scratch. The face-pin mask plays the diffusion kernel's
-     * "solid" role: pinned faces are frozen and act as no-flux neighbours.
-     *
-     * The shared scratch buffers can be larger than this lattice (they are
-     * sized to the largest one); the kernel's internal whole-buffer copies
-     * require exact-length views.
-     *
-     * @param {Float32Array} component  Face lattice, exact length.
-     * @param {Float32Array} source_copy_buf
-     * @param {number} dim_x
-     * @param {number} dim_y
-     * @param {number} dim_z
-     * @param {Uint8Array} face_solid
-     */
-    #diffuse_velocity_component(component, source_copy_buf, dim_x, dim_y, dim_z, face_solid) {
-        const n = component.length;
-        const copy = source_copy_buf.length === n ? source_copy_buf : source_copy_buf.subarray(0, n);
-        const scratch = this.#diffusion_scratch.length === n ? this.#diffusion_scratch : this.#diffusion_scratch.subarray(0, n);
-        copy.set(component);
-        v3_grid_apply_diffusion(
-            component, copy, scratch,
-            dim_x, dim_y, dim_z,
-            this.velocity_diffusion_rate,
-            this.velocity_diffusion_iterations,
-            face_solid
-        );
-    }
-
-    /**
-     * Advance the simulation by one timestep.
-     *
-     * @param {FluidField} field
-     * @param {number} time_delta            seconds (or grid-cells-per-velocity-unit;
-     *                                       caller defines the convention)
-     * @param {AbstractFluidEffector[]} effectors    Pass `[]` for no external forces.
-     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine sending
-     *                                               world-space points into this
-     *                                               field's grid space. Passed through
-     *                                               to each effector's `apply`. Pass
-     *                                               `M4_IDENTITY` when effectors are
-     *                                               already configured in grid space.
-     */
-    step(field, time_delta, effectors, world_to_grid) {
-        assert.defined(field, "field");
-        assert.notNull(field, "field");
-        assert.isNumber(time_delta, "time_delta");
-        assert.greaterThanOrEqual(time_delta, 0, "time_delta");
-        assert.isArray(effectors, "effectors");
-        assert.defined(world_to_grid, "world_to_grid");
-        assert.notNull(world_to_grid, "world_to_grid");
-
-        if (time_delta === 0) {
-            return;
-        }
-
-        const cell_count = field.cellCount();
-        assert.greaterThan(cell_count, 0, "field has not been built");
-
-        this.#ensure_scratch(field);
-
-        const res = field.getResolution();
-        const n_u = field.velocity_x.length;
-        const n_v = field.velocity_y.length;
-        const n_w = field.velocity_z.length;
-
-        // 1. External forces.
-        for (let i = 0; i < effectors.length; i++) {
-            effectors[i].apply(field, time_delta, world_to_grid);
-        }
-
-        // Refresh the pre-baked derived masks (cell neighbour mask, pressure
-        // diagonal, face pins) ONCE for the whole step — after effectors (a
-        // custom effector may splat solids), before anything that consumes
-        // them. Both projections below reuse them. Faces that just became
-        // pinned have their velocity zeroed here (static-wall default);
-        // already-pinned faces keep whatever boundary condition their solid's
-        // owner wrote (FluidObstacleSystem writes moving-wall velocities).
-        field.recomputeSolidNeighbourMask();
-
-        const solid = field.solid;
-
-        // 1b. Velocity damping — the solver's only energy sink under sustained
-        //     forcing. Pinned faces are SKIPPED: their value is the wall's
-        //     boundary condition, not fluid momentum.
-        if (this.velocity_damping > 0) {
-            const decay = Math.exp(-this.velocity_damping * time_delta);
-            const vu = field.velocity_x;
-            const vv = field.velocity_y;
-            const vw = field.velocity_z;
-            const pin_u = field.face_solid_x;
-            const pin_v = field.face_solid_y;
-            const pin_w = field.face_solid_z;
-            for (let i = 0; i < n_u; i++) {
-                if (pin_u[i] === 0) vu[i] *= decay;
-            }
-            for (let i = 0; i < n_v; i++) {
-                if (pin_v[i] === 0) vv[i] *= decay;
-            }
-            for (let i = 0; i < n_w; i++) {
-                if (pin_w[i] === 0) vw[i] *= decay;
-            }
-        }
-
-        // 1c. Vorticity confinement — an additional force term that sharpens
-        //     vortex cores (see the knob's docstring). Needs the fresh face
-        //     pins; uses the prev + aux trios and the diffusion scratch as
-        //     working memory, all overwritten by later phases anyway.
-        if (this.vorticity_confinement > 0) {
-            this.#ensure_aux_scratch(field);
-            v3_mac_apply_vorticity_confinement(
-                field.velocity_x, field.velocity_y, field.velocity_z,
-                field.face_solid_x, field.face_solid_y, field.face_solid_z,
-                this.#prev_x, this.#prev_y, this.#prev_z,
-                this.#aux_x, this.#aux_y, this.#aux_z, this.#diffusion_scratch,
-                res[0], res[1], res[2],
-                this.vorticity_confinement * time_delta,
-                solid
-            );
-        }
-
-        // 2. Velocity diffusion (viscosity). Cheap to skip when disabled. Each
-        //    face lattice diffuses with its own dimensions; the face-pin masks
-        //    make walls no-flux exactly like solid cells used to.
-        if (this.velocity_diffusion_rate > 0 && this.velocity_diffusion_iterations > 0) {
-            this.#diffuse_velocity_component(field.velocity_x, this.#prev_x, res[0] + 1, res[1], res[2], field.face_solid_x);
-            this.#diffuse_velocity_component(field.velocity_y, this.#prev_y, res[0], res[1] + 1, res[2], field.face_solid_y);
-            this.#diffuse_velocity_component(field.velocity_z, this.#prev_z, res[0], res[1], res[2] + 1, field.face_solid_z);
-        }
-
-        // 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;
-
-            // ũ = 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, prev);
-
-            // Snapshot ũ.
-            this.#ensure_aux_scratch(field);
-            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,
-            // per face lattice.
-            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_u; i++) px[i] = 2 * fx[i] - ax[i];
-            for (let i = 0; i < n_v; i++) py[i] = 2 * fy[i] - ay[i];
-            for (let i = 0; i < n_w; i++) pz[i] = 2 * fz[i] - az[i];
-
-            // u′ = advect(û, u½, dt/2). The advection kernels sample the
-            // carrier's OTHER lattices spatially, so the carrier must not
-            // alias the outputs — copy u½ into the aux trio (ũ there is dead,
-            // already folded into û).
-            this.#aux_x.set(fx);
-            this.#aux_y.set(fy);
-            this.#aux_z.set(fz);
-            this.#advect_velocity(field, res, half_dt, prev, [ax, ay, az]);
-
-            // 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);
-            }
-
-            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, prev);
-
-            // Re-project after advection. Solids cannot have changed since the
-            // top-of-step mask refresh (only the simulator has touched the
-            // field), so the masks are still fresh.
-            this.#project_with_current_mask(field);
-        }
-
-        // 6. Transport each passive scalar by the now-finalized velocity field.
-        const scalars = field.getScalarAttributes();
-
-        // Scratch is grown to the LARGEST field this simulator has stepped and
-        // never shrinks, so on a smaller field it is longer than a cell buffer.
-        // The kernels accept oversized inputs, but their whole-buffer seeding
-        // copies (`output.set(source)`) do not — a longer source overflows the
-        // destination. Both scratch views therefore have to be exact-length.
-        const scalar_source = this.#scalar_scratch.length === cell_count
-            ? this.#scalar_scratch
-            : this.#scalar_scratch.subarray(0, cell_count);
-
-        for (let i = 0; i < scalars.length; i++) {
-            const attr = scalars[i];
-
-            if (this.scalar_diffusion_rate > 0 && this.scalar_diffusion_iterations > 0) {
-                scalar_source.set(attr.data);
-                // The diffusion scratch is face-lattice sized; the kernel's
-                // internal whole-buffer copies need an exact cell-count view.
-                const ping_pong = this.#diffusion_scratch.length === cell_count
-                    ? this.#diffusion_scratch
-                    : this.#diffusion_scratch.subarray(0, cell_count);
-                v3_grid_apply_diffusion(
-                    attr.data, scalar_source, ping_pong,
-                    res[0], res[1], res[2],
-                    this.scalar_diffusion_rate,
-                    this.scalar_diffusion_iterations,
-                    solid
-                );
-            }
-
-            scalar_source.set(attr.data);
-            // Scalars are ALWAYS semi-Lagrangian, independent of
-            // advection_scheme — gather-MacCormack is non-conservative (see
-            // the AdvectionScheme docstring).
-            v3_mac_advect_sl_scalar(
-                attr.data, scalar_source,
-                field.velocity_x, field.velocity_y, field.velocity_z,
-                res[0], res[1], res[2],
-                time_delta,
-                solid
-            );
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { sor_optimal_omega } from "../../../core/math/linalg/sor_optimal_omega.js";
+import { v3_grid_apply_diffusion } from "./solver/v3_grid_apply_diffusion.js";
+import { v3_grid_solve_pressure } from "./solver/v3_grid_solve_pressure.js";
+import { v3_grid_solve_pressure_pcg } from "./solver/v3_grid_solve_pressure_pcg.js";
+import { v3_mac_advect_maccormack_velocity } from "./solver/v3_mac_advect_maccormack_velocity.js";
+import { v3_mac_advect_sl_velocity } from "./solver/v3_mac_advect_sl_velocity.js";
+import { v3_mac_advect_sl_scalar } from "./solver/v3_mac_advect_scalar.js";
+import { v3_mac_apply_vorticity_confinement } from "./solver/v3_mac_apply_vorticity_confinement.js";
+import { v3_mac_compute_divergence } from "./solver/v3_mac_compute_divergence.js";
+import { v3_mac_subtract_pressure_gradient } from "./solver/v3_mac_subtract_pressure_gradient.js";
+
+/**
+ * Pressure solver selection. Both solve the same A·p = -div system over the
+ * same neighbour-mask topology; the difference is convergence rate and per-iter
+ * cost.
+ *
+ *   - `"sor"` — red-black Successive Over-Relaxation, our long-standing
+ *     default. One sweep is cheap (~3-5 µs/cell at 128³), convergence is
+ *     O(N) iterations for fixed accuracy.
+ *
+ *   - `"mic-pcg"` — Modified Incomplete Cholesky preconditioned Conjugate
+ *     Gradient. ~2× the per-iter cost of SOR, but converges in O(√N) iters
+ *     (typically 8-12 vs SOR's 30+ at 128³), so a net 1.5-2× speedup at
+ *     quality parity for production grids. Allocates 5 additional N-sized
+ *     scratch buffers (r, z, s, As, precon).
+ *
+ * @enum {string}
+ */
+export const PressureSolver = {
+    SOR: "sor",
+    MICPCG: "mic-pcg",
+};
+
+/**
+ * VELOCITY transport scheme selection. Passive scalars always use
+ * semi-Lagrangian transport regardless of this setting — gather-form
+ * MacCormack is non-conservative (the corrector re-adds roughly double the
+ * gather bias; measured 1.7x total dye mass in one second of a sealed
+ * vortex, independent of wall handling), and scalar conservation is a hard
+ * requirement, not a preference.
+ *
+ *   - `"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.
+ *     Allocates 3 additional face-lattice scratch buffers.
+ *
+ * @enum {string}
+ */
+export const AdvectionScheme = {
+    SEMI_LAGRANGIAN: "semi-lagrangian",
+    MACCORMACK: "maccormack",
+};
+
+/**
+ * 3D incompressible-flow solver on a MAC (staggered) grid — Stam's stable-
+ * fluids step structure (1999/2003) with face-centered velocity (Harlow &
+ * Welch 1965), an exact discrete Helmholtz projection, and optional
+ * advection-reflection / MacCormack transport.
+ *
+ * Holds tuning knobs plus transient working memory (per-step velocity snapshots,
+ * divergence, ping-pong scratch). None of that working memory carries information
+ * across step boundaries — its value is overwritten before being read on the next
+ * step. Replacing the simulator instance between two steps of the same field
+ * produces an identical result (the only cross-step state, `pressure`, lives on
+ * 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), then the
+ *      optional exponential velocity damping.
+ *   2. Diffuse velocity (viscosity; skipped when `velocity_diffusion_rate == 0`).
+ *   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 (always semi-Lagrangian — see {@link AdvectionScheme}).
+ *
+ * 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
+ * quasi-steady state.
+ *
+ * Compute model: synchronous, main-thread. Cost scales linearly with cell count and
+ * with iteration counts. The pressure SOR sweep count is auto-scaled to grid size
+ * (see {@link pressure_iteration_scale}) so the per-cell budget stays roughly flat
+ * across resolutions instead of over-spending at 32³ and under-spending at 256³.
+ */
+/**
+ * Minimum iteration count when `pressure_iteration_scale > 0`. Picked so very
+ * small grids (8³, 16³) still get enough sweeps to converge — at those sizes
+ * `scale * max_res` underflows the practical "useful work" zone. For grids
+ * larger than `floor / scale` the scale formula dominates and this constant
+ * stops mattering. Caller may inspect / override if a per-deployment minimum
+ * makes sense.
+ *
+ * @type {number}
+ */
+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 {
+
+    /**
+     * Implicit-diffusion coefficient (= viscosity * dt-like scaling). 0 disables.
+     * @type {number}
+     */
+    velocity_diffusion_rate = 0;
+
+    /**
+     * Jacobi iterations for the velocity diffusion solve. Only consulted when
+     * `velocity_diffusion_rate > 0`.
+     * @type {number}
+     */
+    velocity_diffusion_iterations = 4;
+
+    /**
+     * Implicit-diffusion coefficient applied uniformly to all scalar attributes. 0
+     * disables. Semi-Lagrangian advection already introduces visible numerical
+     * diffusion, so leaving this at 0 is usually fine.
+     * @type {number}
+     */
+    scalar_diffusion_rate = 0;
+
+    /**
+     * @type {number}
+     */
+    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 bare
+     * `force` on a {@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.
+     *
+     * Relationship to {@link GlobalFluidEffector#drag}: the effector's drag
+     * is the same operation expressed as SCENE CONTENT — it relaxes toward a
+     * configurable ambient wind and travels with the effector entity. This
+     * knob is the SOLVER-level stability primitive: it exists even when no
+     * effectors are wired, and always relaxes toward zero. Use the effector
+     * for atmosphere design; use this to guarantee boundedness.
+     *
+     * 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`
+     * switches to Modified Incomplete Cholesky preconditioned Conjugate
+     * Gradient, which typically converges in 1/3 the iterations at 2× per-iter
+     * cost (net ~1.5-2× faster wall time at quality parity on production
+     * grids). MIC-PCG allocates an additional 5 N-sized scratch buffers, so
+     * peak memory is higher.
+     *
+     * Switching at runtime is supported but flushes the warm-started pressure
+     * meaning for one step (both solvers warm-start from `field.pressure`,
+     * but the convergence trajectory is different — first frame after a
+     * switch will look "fresh", not warm).
+     *
+     * @type {string}
+     */
+    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 — see {@link AdvectionScheme}
+     * (scalars are always semi-Lagrangian; see the enum docstring for why).
+     *
+     * **Default MacCormack.** On the MAC grid with solid-clipped traces it is
+     * measured long-horizon stable (sealed-vortex energy peaks at 0.96x its
+     * initial over 10 s, monotone decay thereafter) and retains dramatically
+     * more energy than first-order transport: 0.80 vs 0.53 KE after one
+     * second (quality.spec.js scenario 2b).
+     *
+     * Do NOT combine with {@link advection_reflection}: the energy-preserving
+     * reflection re-injects the corrector overshoots and the pair pumps
+     * energy without bound (10 s peak 3.7x — measured both with and without
+     * trace clipping). Reflection is the companion for SEMI_LAGRANGIAN.
+     *
+     * @type {string}
+     */
+    advection_scheme = AdvectionScheme.MACCORMACK;
+
+    /**
+     * 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
+     * ~+70% of step() at 32×8×32 on the MAC lattices (each half-step pays the
+     * cross-component carrier sampling). The reflection replaces the
+     * energy-DISSIPATING first projection with an energy-PRESERVING
+     * reflection about the divergence-free subspace.
+     *
+     * With semi-Lagrangian advection this is measured stable (sealed-vortex
+     * kinetic energy never exceeds its initial over 10 s) while retaining
+     * visibly more swirl — peak vorticity 0.74 vs 0.68 after one second
+     * (quality.spec.js scenario 2b). Do NOT combine with MacCormack — the
+     * reflection re-injects the corrector overshoots (10 s energy peak
+     * 3.7x); see {@link advection_scheme}.
+     *
+     * 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.
+     *
+     * Default OFF: the default velocity scheme is MacCormack, with which the
+     * reflection is unstable (see {@link advection_scheme}). Enable it when
+     * running SEMI_LAGRANGIAN velocity transport — that pairing is measured
+     * stable and retains visibly more swirl than plain SL.
+     *
+     * @type {boolean}
+     */
+    advection_reflection = false;
+
+    /**
+     * Run the pressure projection *before* self-advection in addition to after.
+     *
+     * The Stam (1999/2003) reference solver projects twice per step:
+     *
+     *     [forces] → [diffuse] → **project₁** → [advect] → **project₂** → [scalars]
+     *
+     * `project₁` ensures the velocity field that's *fed into* semi-Lagrangian
+     * advection is divergence-free, so back-traced trajectories follow a physical
+     * flow. `project₂` cleans up the small divergence advection re-introduces.
+     *
+     * Skipping `project₁` (this flag = false) cuts the pressure-solve cost roughly
+     * in half — at default settings, pressure is ~80% of step() time, and the two
+     * projections share that ~evenly. The cost is that effectors' splatted
+     * impulses (which inject divergence) and any post-diffusion residual get
+     * carried into advection un-projected, then have to be cleaned up by the
+     * single post-advection projection.
+     *
+     * In practice:
+     *   - If diffusion is OFF (rate=0) and effectors are gentle (gentle wind, no
+     *     big impulses), the visual quality cost is small. The post-advection
+     *     project handles everything in roughly the same number of iterations.
+     *   - If diffusion is ON, or you have strong impulses (explosions, large
+     *     wakes), the second-only solver is asked to fix everything in one pass
+     *     and may visibly under-converge — flicker, "pumping", or divergent
+     *     vortices.
+     *
+     * Default `true` (= Stam reference behavior) for correctness; flip to `false`
+     * if profiling shows pressure as a bottleneck and quality A/B looks acceptable.
+     *
+     * @type {boolean}
+     */
+    project_before_advection = true;
+
+    /**
+     * Adaptive scaling factor for the pressure Poisson SOR sweep count. The actual
+     * iteration count per `project()` call is
+     *
+     *     iters = max(PRESSURE_ITERATIONS_FLOOR, ceil(pressure_iteration_scale * max(rx, ry, rz)))
+     *
+     * unless `pressure_iteration_scale <= 0`, in which case projection is skipped
+     * entirely (useful for tests that need to inspect un-projected velocity or
+     * tear-down scenarios).
+     *
+     * Why scaled by resolution? Red-black SOR with the optimal omega converges
+     * geometrically with a rate that depends on grid size — the iterations needed
+     * to reach a given residual scale roughly as `O(N)` where N is the max grid
+     * extent. A fixed iteration count therefore over-spends at small grids and
+     * under-spends at large ones; the default value of 30 (from the pre-adaptive
+     * era) was right for ~128³ but wasteful at 32³ and marginal at 256³.
+     *
+     * Default scale `0.25` plus floor `8` chosen empirically against the bench
+     * sweep in `bench.spec.js` (`pressure_iterations convergence + step() cost`)
+     * — it's the smallest setting that keeps a stress-test divergent velocity
+     * field stable under continuous stepping across the 32³ → 128³ range. For a
+     * gentler real-world flow you can drop the scale further; for cold-start
+     * spawn frames or scenes with heavy impulses, bump it up.
+     *
+     * @type {number}
+     */
+    pressure_iteration_scale = 0.25;
+
+    // ────────────────────────────────────────────────────────────────────────────
+    // Transient scratch — overwritten before read on every step. Cached and
+    // grown monotonically so we don't allocate per step. Their value never
+    // crosses a step boundary; if it did it would belong on the field (see
+    // `field.pressure`). Velocity-shaped buffers are sized per face lattice.
+    // ────────────────────────────────────────────────────────────────────────────
+
+    /** @type {Float32Array|null} */ #prev_x = null;
+    /** @type {Float32Array|null} */ #prev_y = null;
+    /** @type {Float32Array|null} */ #prev_z = null;
+    /** @type {Float32Array|null} */ #divergence = null;
+    /** @type {Float32Array|null} */ #diffusion_scratch = null;
+    /** @type {Float32Array|null} */ #scalar_scratch = null;
+
+    // PCG-only scratch (allocated lazily on first MICPCG-enabled project call).
+    #pcg_scratch_cells = 0;
+    /** @type {Float32Array|null} */ #pcg_r = null;
+    /** @type {Float32Array|null} */ #pcg_z = null;
+    /** @type {Float32Array|null} */ #pcg_s = null;
+    /** @type {Float32Array|null} */ #pcg_As = null;
+    /** @type {Float32Array|null} */ #pcg_precon = null;
+
+    // Auxiliary velocity trio (allocated lazily, face-lattice sized): the
+    // reflection scheme's ũ snapshot / carrier copy, and vorticity
+    // confinement's curl scratch — the uses never overlap in time.
+    /** @type {Float32Array|null} */ #aux_x = null;
+    /** @type {Float32Array|null} */ #aux_y = null;
+    /** @type {Float32Array|null} */ #aux_z = null;
+
+    // MacCormack forward-pass trio (allocated lazily, face-lattice sized).
+    // Deliberately separate from #aux: in the reflection path #aux holds the
+    // carrier during the very advection that needs this scratch.
+    /** @type {Float32Array|null} */ #mc_x = null;
+    /** @type {Float32Array|null} */ #mc_y = null;
+    /** @type {Float32Array|null} */ #mc_z = null;
+
+    /**
+     * Grow the cached scratch buffers to fit the field's lattices. The prev
+     * trio and the diffusion scratch are sized per FACE grid (the largest of
+     * which also covers every cell-count use); divergence and scalar scratch
+     * are cell-count. Idempotent and monotonic — never shrinks. Called at the
+     * top of {@link step} so user code never has to think about it.
+     * @param {FluidField} field
+     */
+    #ensure_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        const n_cell = field.cellCount();
+        const n_face_max = Math.max(n_u, n_v, n_w);
+
+        if (this.#prev_x === null || this.#prev_x.length < n_u) this.#prev_x = new Float32Array(n_u);
+        if (this.#prev_y === null || this.#prev_y.length < n_v) this.#prev_y = new Float32Array(n_v);
+        if (this.#prev_z === null || this.#prev_z.length < n_w) this.#prev_z = new Float32Array(n_w);
+        if (this.#diffusion_scratch === null || this.#diffusion_scratch.length < n_face_max) {
+            this.#diffusion_scratch = new Float32Array(n_face_max);
+        }
+        if (this.#scalar_scratch === null || this.#scalar_scratch.length < n_cell) {
+            this.#scalar_scratch = new Float32Array(n_cell);
+        }
+        // #divergence is dtype-tracked separately by #ensure_divergence_matches.
+    }
+
+    /**
+     * Lazily allocate the PCG-specific scratch (5 N-sized Float32 buffers).
+     * Idempotent and monotonic.
+     * @param {number} cell_count
+     */
+    #ensure_pcg_scratch(cell_count) {
+        if (this.#pcg_scratch_cells >= cell_count) {
+            return;
+        }
+        this.#pcg_scratch_cells = cell_count;
+        this.#pcg_r = new Float32Array(cell_count);
+        this.#pcg_z = new Float32Array(cell_count);
+        this.#pcg_s = new Float32Array(cell_count);
+        this.#pcg_As = new Float32Array(cell_count);
+        this.#pcg_precon = new Float32Array(cell_count);
+    }
+
+    /**
+     * Lazily allocate the auxiliary velocity trio (face-lattice sized) used by
+     * the reflection scheme and vorticity confinement. Idempotent and
+     * monotonic.
+     * @param {FluidField} field
+     */
+    #ensure_aux_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        if (this.#aux_x === null || this.#aux_x.length < n_u) this.#aux_x = new Float32Array(n_u);
+        if (this.#aux_y === null || this.#aux_y.length < n_v) this.#aux_y = new Float32Array(n_v);
+        if (this.#aux_z === null || this.#aux_z.length < n_w) this.#aux_z = new Float32Array(n_w);
+    }
+
+    /**
+     * Lazily allocate the MacCormack forward-pass trio (face-lattice sized).
+     * Idempotent and monotonic.
+     * @param {FluidField} field
+     */
+    #ensure_mc_scratch(field) {
+        const res = field.getResolution();
+        const n_u = (res[0] + 1) * res[1] * res[2];
+        const n_v = res[0] * (res[1] + 1) * res[2];
+        const n_w = res[0] * res[1] * (res[2] + 1);
+        if (this.#mc_x === null || this.#mc_x.length < n_u) this.#mc_x = new Float32Array(n_u);
+        if (this.#mc_y === null || this.#mc_y.length < n_v) this.#mc_y = new Float32Array(n_v);
+        if (this.#mc_z === null || this.#mc_z.length < n_w) this.#mc_z = new Float32Array(n_w);
+    }
+
+    /**
+     * 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; sources must not.
+     *
+     * @param {FluidField} field
+     * @param {number[]} res
+     * @param {number} dt
+     * @param {Float32Array[]} sources  `[src_u, src_v, src_w]` face grids
+     * @param {Float32Array[]} carrier  `[car_u, car_v, car_w]` face grids
+     */
+    #advect_velocity(field, res, dt, sources, carrier) {
+        const outputs = [field.velocity_x, field.velocity_y, field.velocity_z];
+        if (this.advection_scheme === AdvectionScheme.MACCORMACK) {
+            this.#ensure_mc_scratch(field);
+            v3_mac_advect_maccormack_velocity(
+                outputs, sources, carrier,
+                [this.#mc_x, this.#mc_y, this.#mc_z],
+                res[0], res[1], res[2],
+                dt,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                field.solid
+            );
+        } else {
+            v3_mac_advect_sl_velocity(
+                outputs, sources, carrier,
+                res[0], res[1], res[2],
+                dt,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                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
+     * through into the SOR inner-loop bandwidth (the solver reads divergence and
+     * writes pressure of the same dtype).
+     *
+     * @param {FluidField} field
+     */
+    #ensure_divergence_matches(field) {
+        const desired_ctor = field.pressure.constructor;
+        const cell_count = field.cellCount();
+        if (this.#divergence === null
+            || this.#divergence.constructor !== desired_ctor
+            || this.#divergence.length < cell_count) {
+            this.#divergence = new desired_ctor(cell_count);
+        }
+    }
+
+    /**
+     * Resolve the per-call SOR iteration count from {@link pressure_iteration_scale}
+     * and the field's resolution. Public so callers can budget frame time or query
+     * the actual cost in advance.
+     *
+     *   - `scale <= 0` → 0 (projection disabled).
+     *   - `scale > 0`  → `max(PRESSURE_ITERATIONS_FLOOR, ceil(scale * max(rx, ry, rz)))`.
+     *
+     * @param {number} res_x
+     * @param {number} res_y
+     * @param {number} res_z
+     * @return {number} non-negative integer iteration count.
+     */
+    resolvePressureIterations(res_x, res_y, res_z) {
+        const scale = this.pressure_iteration_scale;
+        if (scale <= 0) {
+            return 0;
+        }
+        const max_res = res_x > res_y ? (res_x > res_z ? res_x : res_z) : (res_y > res_z ? res_y : res_z);
+        const scaled = Math.ceil(scale * max_res);
+        return scaled > PRESSURE_ITERATIONS_FLOOR ? scaled : PRESSURE_ITERATIONS_FLOOR;
+    }
+
+    /**
+     * Project the field's velocity to be (approximately) divergence-free. Exposed
+     * 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 the field's derived masks (cell neighbour
+     * mask, pressure diagonal, face pins) are already fresh.
+     *
+     * On the MAC layout this is an exact discrete Helmholtz projection: the
+     * face-difference divergence and the face gradient compose to exactly the
+     * 7-point Laplacian the solvers invert, so post-projection divergence is
+     * zero up to solver residual — including beside walls.
+     *
+     * @param {FluidField} field
+     */
+    #project_with_current_mask(field) {
+        this.#ensure_divergence_matches(field);
+
+        const res = field.getResolution();
+        const iterations = this.resolvePressureIterations(res[0], res[1], res[2]);
+
+        if (iterations === 0) {
+            return;
+        }
+
+        v3_mac_compute_divergence(
+            this.#divergence,
+            field.velocity_x, field.velocity_y, field.velocity_z,
+            res[0], res[1], res[2],
+            field.solid
+        );
+
+        if (this.pressure_solver === PressureSolver.MICPCG) {
+            this.#ensure_pcg_scratch(field.cellCount());
+            v3_grid_solve_pressure_pcg(
+                field.pressure, this.#divergence,
+                res[0], res[1], res[2],
+                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 {
+            v3_grid_solve_pressure(
+                field.pressure, this.#divergence,
+                res[0], res[1], res[2],
+                iterations,
+                sor_optimal_omega(res[0], res[1], res[2]),
+                field.solid_neighbour_mask, field.pressure_diag
+            );
+        }
+
+        v3_mac_subtract_pressure_gradient(
+            field.velocity_x, field.velocity_y, field.velocity_z,
+            field.pressure,
+            field.face_solid_x, field.face_solid_y, field.face_solid_z,
+            res[0], res[1], res[2]
+        );
+    }
+
+    /**
+     * Diffuse a single velocity component (one face lattice) in-place, using
+     * `source_copy_buf` as the "before" snapshot and `#diffusion_scratch` as
+     * the ping-pong scratch. The face-pin mask plays the diffusion kernel's
+     * "solid" role: pinned faces are frozen and act as no-flux neighbours.
+     *
+     * The shared scratch buffers can be larger than this lattice (they are
+     * sized to the largest one); the kernel's internal whole-buffer copies
+     * require exact-length views.
+     *
+     * @param {Float32Array} component  Face lattice, exact length.
+     * @param {Float32Array} source_copy_buf
+     * @param {number} dim_x
+     * @param {number} dim_y
+     * @param {number} dim_z
+     * @param {Uint8Array} face_solid
+     */
+    #diffuse_velocity_component(component, source_copy_buf, dim_x, dim_y, dim_z, face_solid) {
+        const n = component.length;
+        const copy = source_copy_buf.length === n ? source_copy_buf : source_copy_buf.subarray(0, n);
+        const scratch = this.#diffusion_scratch.length === n ? this.#diffusion_scratch : this.#diffusion_scratch.subarray(0, n);
+        copy.set(component);
+        v3_grid_apply_diffusion(
+            component, copy, scratch,
+            dim_x, dim_y, dim_z,
+            this.velocity_diffusion_rate,
+            this.velocity_diffusion_iterations,
+            face_solid
+        );
+    }
+
+    /**
+     * Advance the simulation by one timestep.
+     *
+     * @param {FluidField} field
+     * @param {number} time_delta            seconds (or grid-cells-per-velocity-unit;
+     *                                       caller defines the convention)
+     * @param {AbstractFluidEffector[]} effectors    Pass `[]` for no external forces.
+     * @param {Float32Array|number[]} world_to_grid  Column-major 4×4 affine sending
+     *                                               world-space points into this
+     *                                               field's grid space. Passed through
+     *                                               to each effector's `apply`. Pass
+     *                                               `M4_IDENTITY` when effectors are
+     *                                               already configured in grid space.
+     */
+    step(field, time_delta, effectors, world_to_grid) {
+        assert.defined(field, "field");
+        assert.notNull(field, "field");
+        assert.isNumber(time_delta, "time_delta");
+        assert.greaterThanOrEqual(time_delta, 0, "time_delta");
+        assert.isArray(effectors, "effectors");
+        assert.defined(world_to_grid, "world_to_grid");
+        assert.notNull(world_to_grid, "world_to_grid");
+
+        if (time_delta === 0) {
+            return;
+        }
+
+        const cell_count = field.cellCount();
+        assert.greaterThan(cell_count, 0, "field has not been built");
+
+        this.#ensure_scratch(field);
+
+        const res = field.getResolution();
+        const n_u = field.velocity_x.length;
+        const n_v = field.velocity_y.length;
+        const n_w = field.velocity_z.length;
+
+        // 1. External forces.
+        for (let i = 0; i < effectors.length; i++) {
+            effectors[i].apply(field, time_delta, world_to_grid);
+        }
+
+        // Refresh the pre-baked derived masks (cell neighbour mask, pressure
+        // diagonal, face pins) ONCE for the whole step — after effectors (a
+        // custom effector may splat solids), before anything that consumes
+        // them. Both projections below reuse them. Faces that just became
+        // pinned have their velocity zeroed here (static-wall default);
+        // already-pinned faces keep whatever boundary condition their solid's
+        // owner wrote (FluidObstacleSystem writes moving-wall velocities).
+        field.recomputeSolidNeighbourMask();
+
+        const solid = field.solid;
+
+        // 1b. Velocity damping — the solver's only energy sink under sustained
+        //     forcing. Pinned faces are SKIPPED: their value is the wall's
+        //     boundary condition, not fluid momentum.
+        if (this.velocity_damping > 0) {
+            const decay = Math.exp(-this.velocity_damping * time_delta);
+            const vu = field.velocity_x;
+            const vv = field.velocity_y;
+            const vw = field.velocity_z;
+            const pin_u = field.face_solid_x;
+            const pin_v = field.face_solid_y;
+            const pin_w = field.face_solid_z;
+            for (let i = 0; i < n_u; i++) {
+                if (pin_u[i] === 0) vu[i] *= decay;
+            }
+            for (let i = 0; i < n_v; i++) {
+                if (pin_v[i] === 0) vv[i] *= decay;
+            }
+            for (let i = 0; i < n_w; i++) {
+                if (pin_w[i] === 0) vw[i] *= decay;
+            }
+        }
+
+        // 1c. Vorticity confinement — an additional force term that sharpens
+        //     vortex cores (see the knob's docstring). Needs the fresh face
+        //     pins; uses the prev + aux trios and the diffusion scratch as
+        //     working memory, all overwritten by later phases anyway.
+        if (this.vorticity_confinement > 0) {
+            this.#ensure_aux_scratch(field);
+            v3_mac_apply_vorticity_confinement(
+                field.velocity_x, field.velocity_y, field.velocity_z,
+                field.face_solid_x, field.face_solid_y, field.face_solid_z,
+                this.#prev_x, this.#prev_y, this.#prev_z,
+                this.#aux_x, this.#aux_y, this.#aux_z, this.#diffusion_scratch,
+                res[0], res[1], res[2],
+                this.vorticity_confinement * time_delta,
+                solid
+            );
+        }
+
+        // 2. Velocity diffusion (viscosity). Cheap to skip when disabled. Each
+        //    face lattice diffuses with its own dimensions; the face-pin masks
+        //    make walls no-flux exactly like solid cells used to.
+        if (this.velocity_diffusion_rate > 0 && this.velocity_diffusion_iterations > 0) {
+            this.#diffuse_velocity_component(field.velocity_x, this.#prev_x, res[0] + 1, res[1], res[2], field.face_solid_x);
+            this.#diffuse_velocity_component(field.velocity_y, this.#prev_y, res[0], res[1] + 1, res[2], field.face_solid_y);
+            this.#diffuse_velocity_component(field.velocity_z, this.#prev_z, res[0], res[1], res[2] + 1, field.face_solid_z);
+        }
+
+        // 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;
+
+            // ũ = 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, prev);
+
+            // Snapshot ũ.
+            this.#ensure_aux_scratch(field);
+            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,
+            // per face lattice.
+            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_u; i++) px[i] = 2 * fx[i] - ax[i];
+            for (let i = 0; i < n_v; i++) py[i] = 2 * fy[i] - ay[i];
+            for (let i = 0; i < n_w; i++) pz[i] = 2 * fz[i] - az[i];
+
+            // u′ = advect(û, u½, dt/2). The advection kernels sample the
+            // carrier's OTHER lattices spatially, so the carrier must not
+            // alias the outputs — copy u½ into the aux trio (ũ there is dead,
+            // already folded into û).
+            this.#aux_x.set(fx);
+            this.#aux_y.set(fy);
+            this.#aux_z.set(fz);
+            this.#advect_velocity(field, res, half_dt, prev, [ax, ay, az]);
+
+            // 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);
+            }
+
+            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, prev);
+
+            // Re-project after advection. Solids cannot have changed since the
+            // top-of-step mask refresh (only the simulator has touched the
+            // field), so the masks are still fresh.
+            this.#project_with_current_mask(field);
+        }
+
+        // 6. Transport each passive scalar by the now-finalized velocity field.
+        const scalars = field.getScalarAttributes();
+
+        // Scratch is grown to the LARGEST field this simulator has stepped and
+        // never shrinks, so on a smaller field it is longer than a cell buffer.
+        // The kernels accept oversized inputs, but their whole-buffer seeding
+        // copies (`output.set(source)`) do not — a longer source overflows the
+        // destination. Both scratch views therefore have to be exact-length.
+        const scalar_source = this.#scalar_scratch.length === cell_count
+            ? this.#scalar_scratch
+            : this.#scalar_scratch.subarray(0, cell_count);
+
+        for (let i = 0; i < scalars.length; i++) {
+            const attr = scalars[i];
+
+            if (this.scalar_diffusion_rate > 0 && this.scalar_diffusion_iterations > 0) {
+                scalar_source.set(attr.data);
+                // The diffusion scratch is face-lattice sized; the kernel's
+                // internal whole-buffer copies need an exact cell-count view.
+                const ping_pong = this.#diffusion_scratch.length === cell_count
+                    ? this.#diffusion_scratch
+                    : this.#diffusion_scratch.subarray(0, cell_count);
+                v3_grid_apply_diffusion(
+                    attr.data, scalar_source, ping_pong,
+                    res[0], res[1], res[2],
+                    this.scalar_diffusion_rate,
+                    this.scalar_diffusion_iterations,
+                    solid
+                );
+            }
+
+            scalar_source.set(attr.data);
+            // Scalars are ALWAYS semi-Lagrangian, independent of
+            // advection_scheme — gather-MacCormack is non-conservative (see
+            // the AdvectionScheme docstring).
+            v3_mac_advect_sl_scalar(
+                attr.data, scalar_source,
+                field.velocity_x, field.velocity_y, field.velocity_z,
+                res[0], res[1], res[2],
+                time_delta,
+                solid
+            );
+        }
+    }
+}