@woosh/meep-engine 2.157.0 → 2.159.0

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

@@ -1,600 +1,684 @@
-import { assert } from "../../../core/assert.js";
-import { combine_hash } from "../../../core/collection/array/combine_hash.js";
-import { is_typed_array_equals } from "../../../core/collection/array/typed/is_typed_array_equals.js";
-import { sparse_typed_array_hash } from "../../../core/collection/array/typed/sparse_typed_array_hash.js";
-import { scs3d_sample_linear } from "../../graphics/texture/3d/scs3d_sample_linear.js";
-import { v3_grid_compute_solid_neighbour_mask } from "./solver/v3_grid_compute_solid_neighbour_mask.js";
-import { v3_grid_patch_edges_constant } from "./solver/v3_grid_patch_edges_constant.js";
-import { v3_grid_patch_edges_uniform } from "./solver/v3_grid_patch_edges_uniform.js";
-import { v3_grid_shift_in_place } from "./solver/v3_grid_shift_in_place.js";
-
-/**
- * Cell-centered 3D Eulerian grid for the fluid simulator.
- *
- * Holds three velocity components (x, y, z), an optional per-cell `solid` mask, and any
- * number of user-defined passive scalar attributes that get transported by the flow.
- *
- * Holds only state whose value carries information across step boundaries. The
- * simulator's transient working memory (per-step velocity snapshots, divergence,
- * diffusion / scalar ping-pong scratch) lives on the simulator. `pressure` is the
- * one exception: it's warm-started each step from the previous solve, so its value
- * is genuine cross-step state and belongs here.
- *
- * All typed array references are STABLE for the lifetime of the field. External
- * consumers can safely cache references returned from {@link getScalarData},
- * {@link velocity_x}, etc.
- *
- * @see "Real-Time Fluid Dynamics for Games" (Stam, 2003)
- * @see GDC 2019 talk "Wind Simulation in God of War" (Rupert Renard) for the wider
- *      effector-driven design pattern this package is moving toward.
- */
-export class FluidField {
-
-    /**
-     * Grid dimensions in cells, `[x, y, z]`.
-     * @type {[number, number, number]}
-     */
-    #resolution = [0, 0, 0];
-
-    /**
-     * Velocity X component, length = cell count. Cell-centered, indexed by
-     * `z * res_x * res_y + y * res_x + x`.
-     * @type {Float32Array|null}
-     */
-    velocity_x = null;
-
-    /**
-     * @type {Float32Array|null}
-     */
-    velocity_y = null;
-
-    /**
-     * @type {Float32Array|null}
-     */
-    velocity_z = null;
-
-    /**
-     * Per-cell solid flag. `0` = fluid, non-zero = solid (wall). Always allocated by
-     * {@link build} (zero-filled — every cell defaults to fluid). The solver and every
-     * effector read this unconditionally, so the array is part of the field's
-     * uniform shape, not an optional add-on.
-     * @type {Uint8Array|null}
-     */
-    solid = null;
-
-    /**
-     * Per-cell pre-baked neighbourhood mask consumed by the pressure SOR loop.
-     * One byte per cell encoding which of the 6 cardinal neighbours are fluid:
-     *
-     *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
-     *     bit 1 (= 2)   : +x neighbour is fluid
-     *     bit 2 (= 4)   : -y neighbour is fluid
-     *     bit 3 (= 8)   : +y neighbour is fluid
-     *     bit 4 (= 16)  : -z neighbour is fluid
-     *     bit 5 (= 32)  : +z neighbour is fluid
-     *     bit 7 (= 128) : this cell is itself solid
-     *
-     * A solid cell encodes as `128` (bit 7 set, neighbour bits clear) and an
-     * isolated fluid cell as `0`, so the SOR / PCG loops' `if ((mask & 63) === 0)
-     * continue` skip handles both "this cell is solid" and "this fluid cell is
-     * isolated" with a single comparison instead of one solid-self-check plus six
-     * solid-neighbour-checks plus six boundary checks. Bit 7 additionally lets
-     * {@link v3_grid_subtract_pressure_gradient} zero solid-cell velocity without
-     * consulting the {@link solid} array.
-     *
-     * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
-     * mutation. The simulator runs that recompute once per step (after effectors,
-     * which may splat solids) and at the top of every direct project() call, so
-     * callers never have to remember to invalidate it; the per-step cost is one
-     * O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
-     * iterations per call. {@link shift} also refreshes it after migrating the
-     * solid mask.
-     *
-     * @type {Uint8Array|null}
-     */
-    solid_neighbour_mask = null;
-
-    /**
-     * Per-cell pressure-Laplacian diagonal, baked alongside
-     * {@link solid_neighbour_mask} by the same kernel pass:
-     *
-     *     diag = (# fluid neighbours) + (# open faces)
-     *
-     * where an open face is one on the domain edge (out-of-bounds neighbour).
-     * The domain edge is an OPEN boundary — ghost pressure 0 — so flow can
-     * vent through it; solid faces are reflecting (Neumann) and drop out of
-     * the diagonal. A solid cell, or a fluid cell sealed on all six faces,
-     * has `diag = 0`, which is the solvers' single skip test. Sealed domains
-     * are built explicitly by lining the boundary with solid cells.
-     *
-     * Same freshness contract as {@link solid_neighbour_mask}.
-     *
-     * @type {Uint8Array|null}
-     */
-    pressure_diag = null;
-
-    /**
-     * Pressure field from the most recent projection. Owned by the field rather than
-     * the simulator because the simulator warm-starts each solve from the previous
-     * result — step N+1 depends on the value step N wrote here. If this lived on the
-     * simulator, replacing the simulator instance between steps would silently degrade
-     * convergence at the same iteration count.
-     *
-     * Storage type is {@link Float32Array} by default, or {@link Float16Array} when
-     * {@link half_precision_pressure} is enabled before build — see that field for
-     * the bandwidth-vs-quality trade-off.
-     *
-     * Safe to read for debug visualisation. Don't mutate.
-     * @type {Float32Array|Float16Array|null}
-     */
-    pressure = null;
-
-    /**
-     * Allocate {@link pressure} as {@link Float16Array} instead of {@link Float32Array}.
-     *
-     * **Currently slower in V8 — keep `false`.** The intent of this option is to
-     * halve the memory bandwidth on the pressure SOR sweep (the simulator's
-     * hottest, bandwidth-bound loop). On hardware with F16C the per-cell f16↔f32
-     * conversion is ~1 cycle and the bandwidth saving wins. In V8 as of Node 24
-     * the conversion path is not yet specialized — each read of `pressure[i]`
-     * goes through a slow generic Float16 unboxing routine, and the result is
-     * the opposite of what you'd expect: bench at 64³ shows **49% slower** with
-     * f16, at 128³ **28% slower** (see `bench: half_precision_pressure on/off`
-     * in bench.spec.js). The bandwidth-savings story still holds in principle;
-     * it'll likely become a real win once V8 adds inline support for
-     * Float16Array access (the typed array landed in Node 24 / TC39 Stage 4 only
-     * recently).
-     *
-     * Cost when it does win: Float16 has ~3 decimal digits of precision. The SOR
-     * iterate rounds to f16 on every write, so iteration error can't fall below
-     * ~10⁻³ relative. Bench currently shows max|div| within 8% of the f32
-     * baseline at 64³ and 128³ — acceptable for visual sim but not for
-     * quantitative pressure use.
-     *
-     * Must be set before {@link build}.
-     *
-     * The simulator's internal divergence scratch follows this type automatically
-     * (re-allocated to match `pressure.constructor` on each project call).
-     *
-     * @type {boolean}
-     */
-    half_precision_pressure = false;
-
-    /**
-     * @type {{ name: string, data: Float32Array }[]}
-     */
-    #scalar_attributes = [];
-
-    #built = false;
-
-    /**
-     * Set the grid dimensions in cells. Must be called before {@link build}; throws if
-     * the field is already built.
-     * @param {number} res_x positive integer
-     * @param {number} res_y positive integer
-     * @param {number} res_z positive integer
-     */
-    setResolution(res_x, res_y, res_z) {
-        assert.notOk(this.#built, "resolution cannot be changed after build()");
-        assert.isPositiveInteger(res_x, "res_x");
-        assert.isPositiveInteger(res_y, "res_y");
-        assert.isPositiveInteger(res_z, "res_z");
-
-        this.#resolution[0] = res_x;
-        this.#resolution[1] = res_y;
-        this.#resolution[2] = res_z;
-    }
-
-    /**
-     * @return {[number, number, number]} A reference to the internal resolution array.
-     *                                    Do not mutate.
-     */
-    getResolution() {
-        return this.#resolution;
-    }
-
-    /**
-     * @return {number} `res_x * res_y * res_z`. Zero until {@link setResolution} is
-     *                  called.
-     */
-    cellCount() {
-        return this.#resolution[0] * this.#resolution[1] * this.#resolution[2];
-    }
-
-    /**
-     * Register a passive scalar attribute (density, temperature, dye, etc.) that will be
-     * advected by the velocity field each step. Idempotent — re-adding an existing name
-     * returns the existing index.
-     *
-     * Must be called before {@link build}.
-     *
-     * @param {string} name
-     * @return {number} index of the attribute (use with {@link setScalarAtIndex})
-     */
-    addScalar(name) {
-        assert.notOk(this.#built, "addScalar cannot be called after build()");
-        assert.isString(name, "name");
-        assert.greaterThan(name.length, 0, "name must be non-empty");
-
-        const existing = this.#scalar_attributes.findIndex(a => a.name === name);
-        if (existing !== -1) {
-            return existing;
-        }
-
-        const index = this.#scalar_attributes.length;
-        this.#scalar_attributes.push({ name, data: null });
-        return index;
-    }
-
-    /**
-     * @param {string} name
-     * @return {number} index the attribute was registered with, or -1 if not present.
-     */
-    scalarIndex(name) {
-        return this.#scalar_attributes.findIndex(a => a.name === name);
-    }
-
-    /**
-     * @param {string} name
-     * @return {Float32Array|null} live buffer for the named scalar, or null if not
-     *                             registered.
-     */
-    getScalarData(name) {
-        const a = this.#scalar_attributes.find(a => a.name === name);
-        return a === undefined ? null : a.data;
-    }
-
-    /**
-     * @return {{ name: string, data: Float32Array }[]} Live reference; do not mutate.
-     */
-    getScalarAttributes() {
-        return this.#scalar_attributes;
-    }
-
-    /**
-     * Allocate all buffers. Must be called before any read/write. After this point,
-     * resolution and attribute set are frozen.
-     */
-    build() {
-        assert.notOk(this.#built, "build() called twice");
-        assert.greaterThanOrEqual(this.#resolution[0], 1, "setResolution(...) must be called before build()");
-
-        const cell_count = this.cellCount();
-
-        this.velocity_x = new Float32Array(cell_count);
-        this.velocity_y = new Float32Array(cell_count);
-        this.velocity_z = new Float32Array(cell_count);
-        this.solid = new Uint8Array(cell_count);
-        this.solid_neighbour_mask = new Uint8Array(cell_count);
-        this.pressure_diag = new Uint8Array(cell_count);
-        const PressureCtor = this.half_precision_pressure ? Float16Array : Float32Array;
-        this.pressure = new PressureCtor(cell_count);
-
-        for (const attr of this.#scalar_attributes) {
-            attr.data = new Float32Array(cell_count);
-        }
-
-        this.#built = true;
-    }
-
-    /**
-     * Linear cell index for integer grid coordinates.
-     * @param {number} x integer in [0, res_x)
-     * @param {number} y integer in [0, res_y)
-     * @param {number} z integer in [0, res_z)
-     * @return {number} flat index `z * res_x * res_y + y * res_x + x`
-     */
-    cellIndex(x, y, z) {
-        const res_x = this.#resolution[0];
-        const res_y = this.#resolution[1];
-        const res_z = this.#resolution[2];
-        assert.greaterThanOrEqual(x, 0, "x");
-        assert.lessThan(x, res_x, "x");
-        assert.greaterThanOrEqual(y, 0, "y");
-        assert.lessThan(y, res_y, "y");
-        assert.greaterThanOrEqual(z, 0, "z");
-        assert.lessThan(z, res_z, "z");
-        return z * res_x * res_y + y * res_x + x;
-    }
-
-    /**
-     * Set the velocity at an integer grid cell.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} vx
-     * @param {number} vy
-     * @param {number} vz
-     */
-    setVelocityAt(x, y, z, vx, vy, vz) {
-        const c = this.cellIndex(x, y, z);
-        this.velocity_x[c] = vx;
-        this.velocity_y[c] = vy;
-        this.velocity_z[c] = vz;
-    }
-
-    /**
-     * Add to the velocity at an integer grid cell (impulse).
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} dvx
-     * @param {number} dvy
-     * @param {number} dvz
-     */
-    addVelocityAt(x, y, z, dvx, dvy, dvz) {
-        const c = this.cellIndex(x, y, z);
-        this.velocity_x[c] += dvx;
-        this.velocity_y[c] += dvy;
-        this.velocity_z[c] += dvz;
-    }
-
-    /**
-     * @param {number} attribute_index
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {number} value
-     */
-    setScalarAtIndex(attribute_index, x, y, z, value) {
-        assert.greaterThanOrEqual(attribute_index, 0, "attribute_index");
-        assert.lessThan(attribute_index, this.#scalar_attributes.length, "attribute_index");
-        const c = this.cellIndex(x, y, z);
-        this.#scalar_attributes[attribute_index].data[c] = value;
-    }
-
-    /**
-     * Mark a cell as solid (wall) or fluid.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @param {boolean} is_solid
-     */
-    setSolidAt(x, y, z, is_solid) {
-        this.solid[this.cellIndex(x, y, z)] = is_solid ? 1 : 0;
-    }
-
-    /**
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @return {boolean} true if the cell is marked solid.
-     */
-    isSolidAt(x, y, z) {
-        return this.solid[this.cellIndex(x, y, z)] !== 0;
-    }
-
-    /**
-     * Sample velocity at a fractional grid position (positions outside the grid are
-     * clamped). Writes into `out` and returns it.
-     * @param {Float32Array|number[]} out  Length-3 destination.
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @return {Float32Array|number[]} `out`, for chaining.
-     */
-    sampleVelocity(out, x, y, z) {
-        const res_x = this.#resolution[0];
-        const res_y = this.#resolution[1];
-        const res_z = this.#resolution[2];
-        out[0] = scs3d_sample_linear(this.velocity_x, res_x, res_y, res_z, x, y, z);
-        out[1] = scs3d_sample_linear(this.velocity_y, res_x, res_y, res_z, x, y, z);
-        out[2] = scs3d_sample_linear(this.velocity_z, res_x, res_y, res_z, x, y, z);
-        return out;
-    }
-
-    /**
-     * Sample a scalar attribute at a fractional grid position.
-     * @param {string} name
-     * @param {number} x
-     * @param {number} y
-     * @param {number} z
-     * @return {number} trilinearly-interpolated value at `(x, y, z)`.
-     */
-    sampleScalar(name, x, y, z) {
-        const data = this.getScalarData(name);
-        assert.notNull(data, `scalar attribute '${name}'`);
-        return scs3d_sample_linear(data, this.#resolution[0], this.#resolution[1], this.#resolution[2], x, y, z);
-    }
-
-    /**
-     * Strict value equality. Two fields are equal iff they have the same resolution,
-     * the same set of scalar attributes (matched by name AND index), and the same
-     * buffer contents in `velocity_*`, `solid`, `pressure`, and each scalar. Pre-build
-     * fields compare by resolution + attribute names only (their buffers are null).
-     *
-     * O(N) — walks every cell. Use {@link hash} for change-detection on hot paths.
-     *
-     * @param {FluidField} other
-     * @return {boolean}
-     */
-    equals(other) {
-        if (other === this) {
-            return true;
-        }
-        if (!(other instanceof FluidField)) {
-            return false;
-        }
-
-        if (this.#resolution[0] !== other.#resolution[0]
-            || this.#resolution[1] !== other.#resolution[1]
-            || this.#resolution[2] !== other.#resolution[2]) {
-            return false;
-        }
-
-        if (this.#built !== other.#built) {
-            return false;
-        }
-
-        const my_attrs = this.#scalar_attributes;
-        const other_attrs = other.#scalar_attributes;
-        if (my_attrs.length !== other_attrs.length) {
-            return false;
-        }
-        for (let i = 0; i < my_attrs.length; i++) {
-            if (my_attrs[i].name !== other_attrs[i].name) {
-                return false;
-            }
-        }
-
-        if (!this.#built) {
-            // Buffers are null on both sides; resolution + names already matched.
-            return true;
-        }
-
-        if (!is_typed_array_equals(this.velocity_x, other.velocity_x)
-            || !is_typed_array_equals(this.velocity_y, other.velocity_y)
-            || !is_typed_array_equals(this.velocity_z, other.velocity_z)) {
-            return false;
-        }
-        if (!is_typed_array_equals(this.solid, other.solid)) {
-            return false;
-        }
-        if (!is_typed_array_equals(this.pressure, other.pressure)) {
-            return false;
-        }
-        for (let i = 0; i < my_attrs.length; i++) {
-            if (!is_typed_array_equals(my_attrs[i].data, other_attrs[i].data)) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-    /**
-     * Fast hash suitable for change-detection. Combines the resolution and a *sparse*
-     * sample of the velocity_x buffer — {@link sparse_typed_array_hash} only inspects
-     * the first ~1024 cells with stride enough to take ~31 samples, regardless of how
-     * large the field is. The hash will catch most local edits to the velocity field
-     * but is not a content-perfect fingerprint; for that, fall through to
-     * {@link equals}.
-     *
-     * Constant-time relative to grid size in the common case.
-     *
-     * @return {number}
-     */
-    hash() {
-        const velocity_sample = this.#built
-            ? sparse_typed_array_hash(this.velocity_x, 0, this.velocity_x.length)
-            : 0;
-        return combine_hash(
-            this.#resolution[0],
-            this.#resolution[1],
-            this.#resolution[2],
-            this.#scalar_attributes.length,
-            velocity_sample
-        );
-    }
-
-    /**
-     * Rebuild {@link solid_neighbour_mask} and {@link pressure_diag} from the
-     * current {@link solid} buffer.
-     *
-     * O(N) — two byte-writes per cell, six byte-reads per cell. Called by the
-     * simulator once per step and at the top of each direct project() call, so
-     * callers never have to remember to invalidate the mask after mutating
-     * solids; the cost is amortized across the SOR sweep's many iterations.
-     *
-     * Encoding: see {@link solid_neighbour_mask} and {@link pressure_diag}.
-     */
-    recomputeSolidNeighbourMask() {
-        if (!this.#built) {
-            return;
-        }
-        v3_grid_compute_solid_neighbour_mask(
-            this.solid_neighbour_mask,
-            this.pressure_diag,
-            this.solid,
-            this.#resolution[0], this.#resolution[1], this.#resolution[2]
-        );
-    }
-
-    /**
-     * Translate the field's contents by `(shift_x, shift_y, shift_z)` grid cells —
-     * called when the field's world-space origin moves, so the fluid data (anchored
-     * to world space) follows. Every owned buffer (velocity_x/y/z, solid, pressure,
-     * each scalar attribute) is shifted, then the newly-exposed edges are patched
-     * via {@link v3_grid_patch_edges_uniform} (zero-gradient Neumann extrapolation —
-     * "the field is locally uniform").
-     *
-     * Direction convention matches the primitive: positive shift means the grid's
-     * world origin moved in that direction, so each cell takes the value previously
-     * at its `+shift` neighbour.
-     *
-     * `(0, 0, 0)` is a no-op; |shift| ≥ res on any axis zero-fills (no valid source
-     * left to replicate from). Pre-build fields (buffers null) are no-op'd.
-     *
-     * The solid mask is migrated like every other buffer — solids are anchored to
-     * world space exactly like the fluid they bound, so a wall must stay where the
-     * world says it is when the grid hops a cell. Newly scrolled-in cells become
-     * fluid (`0`): the field knows nothing about un-simulated space, and "empty
-     * until a voxelizer says otherwise" is the only honest default. Callers that
-     * voxelize scene geometry can keep overwriting the mask each tick — the
-     * migrated values are then simply replaced. (Earlier behaviour cleared the
-     * whole mask on shift, which made every grid hop simulate one tick with no
-     * walls anywhere — fluid leaked through geometry until the caller re-splatted.)
-     *
-     * The derived {@link solid_neighbour_mask} is refreshed here too, so the field
-     * stays self-consistent for direct kernel users; the simulator's per-step
-     * refresh makes this redundant in the ECS path but shifts are rare (once per
-     * cell crossing) and the pass is one byte-write per cell.
-     *
-     * @param {number} shift_x  integer
-     * @param {number} shift_y  integer
-     * @param {number} shift_z  integer
-     */
-    shift(shift_x, shift_y, shift_z) {
-        if (!this.#built) {
-            return;
-        }
-        if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
-            return;
-        }
-
-        const rx = this.#resolution[0];
-        const ry = this.#resolution[1];
-        const rz = this.#resolution[2];
-
-        // Velocity components.
-        v3_grid_shift_in_place(this.velocity_x, rx, ry, rz, shift_x, shift_y, shift_z);
-        v3_grid_patch_edges_uniform(this.velocity_x, rx, ry, rz, shift_x, shift_y, shift_z);
-
-        v3_grid_shift_in_place(this.velocity_y, rx, ry, rz, shift_x, shift_y, shift_z);
-        v3_grid_patch_edges_uniform(this.velocity_y, rx, ry, rz, shift_x, shift_y, shift_z);
-
-        v3_grid_shift_in_place(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
-        v3_grid_patch_edges_uniform(this.velocity_z, rx, ry, rz, shift_x, shift_y, shift_z);
-
-        // Solid mask — world-anchored like the fluid; scrolled-in cells are fluid.
-        v3_grid_shift_in_place(this.solid, rx, ry, rz, shift_x, shift_y, shift_z);
-        v3_grid_patch_edges_constant(this.solid, rx, ry, rz, shift_x, shift_y, shift_z, 0);
-        v3_grid_compute_solid_neighbour_mask(this.solid_neighbour_mask, this.pressure_diag, this.solid, rx, ry, rz);
-
-        // Pressure (warm-start state, carried across steps).
-        v3_grid_shift_in_place(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
-        v3_grid_patch_edges_uniform(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
-
-        // Scalar attributes.
-        for (let i = 0; i < this.#scalar_attributes.length; i++) {
-            const data = this.#scalar_attributes[i].data;
-            v3_grid_shift_in_place(data, rx, ry, rz, shift_x, shift_y, shift_z);
-            v3_grid_patch_edges_uniform(data, rx, ry, rz, shift_x, shift_y, shift_z);
-        }
-    }
-
-    /**
-     * Zero velocity, pressure, and all scalar attributes. Solid mask is preserved.
-     * Pressure is cleared to drop the warm-start (otherwise the next step's solve
-     * begins from a stale solution that no longer matches the zero velocity).
-     */
-    clear() {
-        assert.ok(this.#built, "build() must be called before clear()");
-        this.velocity_x.fill(0);
-        this.velocity_y.fill(0);
-        this.velocity_z.fill(0);
-        this.pressure.fill(0);
-        for (const attr of this.#scalar_attributes) {
-            attr.data.fill(0);
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { combine_hash } from "../../../core/collection/array/combine_hash.js";
+import { is_typed_array_equals } from "../../../core/collection/array/typed/is_typed_array_equals.js";
+import { sparse_typed_array_hash } from "../../../core/collection/array/typed/sparse_typed_array_hash.js";
+import { scs3d_sample_linear } from "../../graphics/texture/3d/scs3d_sample_linear.js";
+import { v3_grid_compute_solid_neighbour_mask } from "./solver/v3_grid_compute_solid_neighbour_mask.js";
+import { v3_grid_patch_edges_constant } from "./solver/v3_grid_patch_edges_constant.js";
+import { v3_grid_patch_edges_uniform } from "./solver/v3_grid_patch_edges_uniform.js";
+import { v3_grid_shift_in_place } from "./solver/v3_grid_shift_in_place.js";
+import { v3_mac_compute_face_solid } from "./solver/v3_mac_compute_face_solid.js";
+
+/**
+ * 3D Eulerian grid for the fluid simulator — MAC (marker-and-cell) staggered
+ * layout: pressure, solids and scalars live at cell centers; each velocity
+ * component lives on the cell FACES normal to it (Harlow & Welch 1965).
+ *
+ * Staggering makes the discrete divergence and pressure gradient exact
+ * adjoints, so projection drives divergence to actual zero (no collocated
+ * operator-mismatch floor, no projection-invisible checkerboard modes) and
+ * solid boundaries pin the exact normal face velocity (true no-penetration).
+ *
+ * Holds three face-centered velocity components, a per-cell `solid` mask, and any
+ * number of user-defined cell-centered passive scalar attributes transported by
+ * the flow.
+ *
+ * Holds only state whose value carries information across step boundaries. The
+ * simulator's transient working memory (per-step velocity snapshots, divergence,
+ * diffusion / scalar ping-pong scratch) lives on the simulator. `pressure` is the
+ * one exception: it's warm-started each step from the previous solve, so its value
+ * is genuine cross-step state and belongs here.
+ *
+ * All typed array references are STABLE for the lifetime of the field. External
+ * consumers can safely cache references returned from {@link getScalarData},
+ * {@link velocity_x}, etc.
+ *
+ * @see "Real-Time Fluid Dynamics for Games" (Stam, 2003)
+ * @see GDC 2019 talk "Wind Simulation in God of War" (Rupert Renard) for the wider
+ *      effector-driven design pattern this package is moving toward.
+ */
+export class FluidField {
+
+    /**
+     * Grid dimensions in cells, `[x, y, z]`.
+     * @type {[number, number, number]}
+     */
+    #resolution = [0, 0, 0];
+
+    /**
+     * Velocity X component on x-faces. Length `(res_x+1) * res_y * res_z`,
+     * indexed by `z * (res_x+1) * res_y + y * (res_x+1) + x` with
+     * `x ∈ [0, res_x]`. Face `(x, y, z)` sits between cells `(x−1, y, z)` and
+     * `(x, y, z)` — at grid-space position `(x − 0.5, y, z)` in the
+     * cell-center coordinate frame.
+     * @type {Float32Array|null}
+     */
+    velocity_x = null;
+
+    /**
+     * Velocity Y component on y-faces. Length `res_x * (res_y+1) * res_z`,
+     * indexed by `z * res_x * (res_y+1) + y * res_x + x` with `y ∈ [0, res_y]`.
+     * @type {Float32Array|null}
+     */
+    velocity_y = null;
+
+    /**
+     * Velocity Z component on z-faces. Length `res_x * res_y * (res_z+1)`,
+     * indexed by `z * res_x * res_y + y * res_x + x` with `z ∈ [0, res_z]`
+     * (the face slice size equals the cell slice size).
+     * @type {Float32Array|null}
+     */
+    velocity_z = null;
+
+    /**
+     * Per-cell solid flag. `0` = fluid, non-zero = solid (wall). Always allocated by
+     * {@link build} (zero-filled — every cell defaults to fluid). The solver and every
+     * effector read this unconditionally, so the array is part of the field's
+     * uniform shape, not an optional add-on.
+     * @type {Uint8Array|null}
+     */
+    solid = null;
+
+    /**
+     * Per-cell pre-baked neighbourhood mask consumed by the pressure SOR loop.
+     * One byte per cell encoding which of the 6 cardinal neighbours are fluid:
+     *
+     *     bit 0 (= 1)   : -x neighbour is fluid (in-bounds AND non-solid)
+     *     bit 1 (= 2)   : +x neighbour is fluid
+     *     bit 2 (= 4)   : -y neighbour is fluid
+     *     bit 3 (= 8)   : +y neighbour is fluid
+     *     bit 4 (= 16)  : -z neighbour is fluid
+     *     bit 5 (= 32)  : +z neighbour is fluid
+     *     bit 7 (= 128) : this cell is itself solid
+     *
+     * A solid cell encodes as `128` (bit 7 set, neighbour bits clear) and an
+     * isolated fluid cell as `0`, so the SOR / PCG loops' `if ((mask & 63) === 0)
+     * continue` skip handles both "this cell is solid" and "this fluid cell is
+     * isolated" with a single comparison instead of one solid-self-check plus six
+     * solid-neighbour-checks plus six boundary checks. Bit 7 additionally lets
+     * {@link v3_grid_subtract_pressure_gradient} zero solid-cell velocity without
+     * consulting the {@link solid} array.
+     *
+     * Computed once by {@link recomputeSolidNeighbourMask} after every solid-mask
+     * mutation. The simulator runs that recompute once per step (after effectors,
+     * which may splat solids) and at the top of every direct project() call, so
+     * callers never have to remember to invalidate it; the per-step cost is one
+     * O(N) byte-pass against the bandwidth-bound SOR sweep that runs many
+     * iterations per call. {@link shift} also refreshes it after migrating the
+     * solid mask.
+     *
+     * @type {Uint8Array|null}
+     */
+    solid_neighbour_mask = null;
+
+    /**
+     * Per-face "pinned" mask for x-faces: `1` where either adjacent cell is
+     * solid — the face's normal velocity is a boundary condition (0 for
+     * static solids), not a degree of freedom. Same length and indexing as
+     * {@link velocity_x}. Baked by {@link recomputeSolidNeighbourMask} via
+     * {@link v3_mac_compute_face_solid}; domain-edge faces stay 0 (open).
+     * @type {Uint8Array|null}
+     */
+    face_solid_x = null;
+
+    /**
+     * y-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_y = null;
+
+    /**
+     * z-face pinned mask — see {@link face_solid_x}.
+     * @type {Uint8Array|null}
+     */
+    face_solid_z = null;
+
+    /**
+     * Per-cell pressure-Laplacian diagonal, baked alongside
+     * {@link solid_neighbour_mask} by the same kernel pass:
+     *
+     *     diag = (# fluid neighbours) + (# open faces)
+     *
+     * where an open face is one on the domain edge (out-of-bounds neighbour).
+     * The domain edge is an OPEN boundary — ghost pressure 0 — so flow can
+     * vent through it; solid faces are reflecting (Neumann) and drop out of
+     * the diagonal. A solid cell, or a fluid cell sealed on all six faces,
+     * has `diag = 0`, which is the solvers' single skip test. Sealed domains
+     * are built explicitly by lining the boundary with solid cells.
+     *
+     * Same freshness contract as {@link solid_neighbour_mask}.
+     *
+     * @type {Uint8Array|null}
+     */
+    pressure_diag = null;
+
+    /**
+     * Pressure field from the most recent projection. Owned by the field rather than
+     * the simulator because the simulator warm-starts each solve from the previous
+     * result — step N+1 depends on the value step N wrote here. If this lived on the
+     * simulator, replacing the simulator instance between steps would silently degrade
+     * convergence at the same iteration count.
+     *
+     * Storage type is {@link Float32Array} by default, or {@link Float16Array} when
+     * {@link half_precision_pressure} is enabled before build — see that field for
+     * the bandwidth-vs-quality trade-off.
+     *
+     * Safe to read for debug visualisation. Don't mutate.
+     * @type {Float32Array|Float16Array|null}
+     */
+    pressure = null;
+
+    /**
+     * Allocate {@link pressure} as {@link Float16Array} instead of {@link Float32Array}.
+     *
+     * **Currently slower in V8 — keep `false`.** The intent of this option is to
+     * halve the memory bandwidth on the pressure SOR sweep (the simulator's
+     * hottest, bandwidth-bound loop). On hardware with F16C the per-cell f16↔f32
+     * conversion is ~1 cycle and the bandwidth saving wins. In V8 as of Node 24
+     * the conversion path is not yet specialized — each read of `pressure[i]`
+     * goes through a slow generic Float16 unboxing routine, and the result is
+     * the opposite of what you'd expect: bench at 64³ shows **49% slower** with
+     * f16, at 128³ **28% slower** (see `bench: half_precision_pressure on/off`
+     * in bench.spec.js). The bandwidth-savings story still holds in principle;
+     * it'll likely become a real win once V8 adds inline support for
+     * Float16Array access (the typed array landed in Node 24 / TC39 Stage 4 only
+     * recently).
+     *
+     * Cost when it does win: Float16 has ~3 decimal digits of precision. The SOR
+     * iterate rounds to f16 on every write, so iteration error can't fall below
+     * ~10⁻³ relative. Bench currently shows max|div| within 8% of the f32
+     * baseline at 64³ and 128³ — acceptable for visual sim but not for
+     * quantitative pressure use.
+     *
+     * Must be set before {@link build}.
+     *
+     * The simulator's internal divergence scratch follows this type automatically
+     * (re-allocated to match `pressure.constructor` on each project call).
+     *
+     * @type {boolean}
+     */
+    half_precision_pressure = false;
+
+    /**
+     * @type {{ name: string, data: Float32Array }[]}
+     */
+    #scalar_attributes = [];
+
+    #built = false;
+
+    /**
+     * Set the grid dimensions in cells. Must be called before {@link build}; throws if
+     * the field is already built.
+     * @param {number} res_x positive integer
+     * @param {number} res_y positive integer
+     * @param {number} res_z positive integer
+     */
+    setResolution(res_x, res_y, res_z) {
+        assert.notOk(this.#built, "resolution cannot be changed after build()");
+        assert.isPositiveInteger(res_x, "res_x");
+        assert.isPositiveInteger(res_y, "res_y");
+        assert.isPositiveInteger(res_z, "res_z");
+
+        this.#resolution[0] = res_x;
+        this.#resolution[1] = res_y;
+        this.#resolution[2] = res_z;
+    }
+
+    /**
+     * @return {[number, number, number]} A reference to the internal resolution array.
+     *                                    Do not mutate.
+     */
+    getResolution() {
+        return this.#resolution;
+    }
+
+    /**
+     * @return {number} `res_x * res_y * res_z`. Zero until {@link setResolution} is
+     *                  called.
+     */
+    cellCount() {
+        return this.#resolution[0] * this.#resolution[1] * this.#resolution[2];
+    }
+
+    /**
+     * Register a passive scalar attribute (density, temperature, dye, etc.) that will be
+     * advected by the velocity field each step. Idempotent — re-adding an existing name
+     * returns the existing index.
+     *
+     * Must be called before {@link build}.
+     *
+     * @param {string} name
+     * @return {number} index of the attribute (use with {@link setScalarAtIndex})
+     */
+    addScalar(name) {
+        assert.notOk(this.#built, "addScalar cannot be called after build()");
+        assert.isString(name, "name");
+        assert.greaterThan(name.length, 0, "name must be non-empty");
+
+        const existing = this.#scalar_attributes.findIndex(a => a.name === name);
+        if (existing !== -1) {
+            return existing;
+        }
+
+        const index = this.#scalar_attributes.length;
+        this.#scalar_attributes.push({ name, data: null });
+        return index;
+    }
+
+    /**
+     * @param {string} name
+     * @return {number} index the attribute was registered with, or -1 if not present.
+     */
+    scalarIndex(name) {
+        return this.#scalar_attributes.findIndex(a => a.name === name);
+    }
+
+    /**
+     * @param {string} name
+     * @return {Float32Array|null} live buffer for the named scalar, or null if not
+     *                             registered.
+     */
+    getScalarData(name) {
+        const a = this.#scalar_attributes.find(a => a.name === name);
+        return a === undefined ? null : a.data;
+    }
+
+    /**
+     * @return {{ name: string, data: Float32Array }[]} Live reference; do not mutate.
+     */
+    getScalarAttributes() {
+        return this.#scalar_attributes;
+    }
+
+    /**
+     * Allocate all buffers. Must be called before any read/write. After this point,
+     * resolution and attribute set are frozen.
+     */
+    build() {
+        assert.notOk(this.#built, "build() called twice");
+        assert.greaterThanOrEqual(this.#resolution[0], 1, "setResolution(...) must be called before build()");
+
+        const cell_count = this.cellCount();
+        const rx = this.#resolution[0];
+        const ry = this.#resolution[1];
+        const rz = this.#resolution[2];
+        const face_count_x = (rx + 1) * ry * rz;
+        const face_count_y = rx * (ry + 1) * rz;
+        const face_count_z = rx * ry * (rz + 1);
+
+        this.velocity_x = new Float32Array(face_count_x);
+        this.velocity_y = new Float32Array(face_count_y);
+        this.velocity_z = new Float32Array(face_count_z);
+        this.face_solid_x = new Uint8Array(face_count_x);
+        this.face_solid_y = new Uint8Array(face_count_y);
+        this.face_solid_z = new Uint8Array(face_count_z);
+        this.solid = new Uint8Array(cell_count);
+        this.solid_neighbour_mask = new Uint8Array(cell_count);
+        this.pressure_diag = new Uint8Array(cell_count);
+        const PressureCtor = this.half_precision_pressure ? Float16Array : Float32Array;
+        this.pressure = new PressureCtor(cell_count);
+
+        for (const attr of this.#scalar_attributes) {
+            attr.data = new Float32Array(cell_count);
+        }
+
+        this.#built = true;
+    }
+
+    /**
+     * Linear cell index for integer grid coordinates.
+     * @param {number} x integer in [0, res_x)
+     * @param {number} y integer in [0, res_y)
+     * @param {number} z integer in [0, res_z)
+     * @return {number} flat index `z * res_x * res_y + y * res_x + x`
+     */
+    cellIndex(x, y, z) {
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+        assert.greaterThanOrEqual(x, 0, "x");
+        assert.lessThan(x, res_x, "x");
+        assert.greaterThanOrEqual(y, 0, "y");
+        assert.lessThan(y, res_y, "y");
+        assert.greaterThanOrEqual(z, 0, "z");
+        assert.lessThan(z, res_z, "z");
+        return z * res_x * res_y + y * res_x + x;
+    }
+
+    /**
+     * Set the velocity of an integer grid cell: each component is written to
+     * BOTH faces of the cell along its axis, so sampling at the cell centre
+     * reads back exactly `(vx, vy, vz)`. Adjacent cells share faces — the
+     * later write wins on a shared face, exactly like overlapping
+     * cell-centered writes used to.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} vx
+     * @param {number} vy
+     * @param {number} vz
+     */
+    setVelocityAt(x, y, z, vx, vy, vz) {
+        this.cellIndex(x, y, z); // asserts bounds
+        const rx = this.#resolution[0];
+        const ry = this.#resolution[1];
+        const sx = rx + 1;
+        const u = z * sx * ry + y * sx + x;
+        this.velocity_x[u] = vx;
+        this.velocity_x[u + 1] = vx;
+        const v = z * rx * (ry + 1) + y * rx + x;
+        this.velocity_y[v] = vy;
+        this.velocity_y[v + rx] = vy;
+        const w = z * rx * ry + y * rx + x;
+        this.velocity_z[w] = vz;
+        this.velocity_z[w + rx * ry] = vz;
+    }
+
+    /**
+     * Add to the velocity of an integer grid cell (impulse). Deposits each
+     * component onto BOTH faces of the cell along its axis; the centre-sampled
+     * velocity increases by exactly `(dvx, dvy, dvz)`.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} dvx
+     * @param {number} dvy
+     * @param {number} dvz
+     */
+    addVelocityAt(x, y, z, dvx, dvy, dvz) {
+        this.cellIndex(x, y, z); // asserts bounds
+        const rx = this.#resolution[0];
+        const ry = this.#resolution[1];
+        const sx = rx + 1;
+        const u = z * sx * ry + y * sx + x;
+        this.velocity_x[u] += dvx;
+        this.velocity_x[u + 1] += dvx;
+        const v = z * rx * (ry + 1) + y * rx + x;
+        this.velocity_y[v] += dvy;
+        this.velocity_y[v + rx] += dvy;
+        const w = z * rx * ry + y * rx + x;
+        this.velocity_z[w] += dvz;
+        this.velocity_z[w + rx * ry] += dvz;
+    }
+
+    /**
+     * @param {number} attribute_index
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {number} value
+     */
+    setScalarAtIndex(attribute_index, x, y, z, value) {
+        assert.greaterThanOrEqual(attribute_index, 0, "attribute_index");
+        assert.lessThan(attribute_index, this.#scalar_attributes.length, "attribute_index");
+        const c = this.cellIndex(x, y, z);
+        this.#scalar_attributes[attribute_index].data[c] = value;
+    }
+
+    /**
+     * Mark a cell as solid (wall) or fluid.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @param {boolean} is_solid
+     */
+    setSolidAt(x, y, z, is_solid) {
+        this.solid[this.cellIndex(x, y, z)] = is_solid ? 1 : 0;
+    }
+
+    /**
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {boolean} true if the cell is marked solid.
+     */
+    isSolidAt(x, y, z) {
+        return this.solid[this.cellIndex(x, y, z)] !== 0;
+    }
+
+    /**
+     * Sample velocity at a fractional grid position in CELL-CENTER coordinates
+     * (positions outside the grid are clamped). Each component is trilinearly
+     * interpolated on its own staggered face lattice — x-face `i` sits at
+     * `x = i − 0.5`, so the component is sampled at `x + 0.5` in face-index
+     * space, and likewise per axis. Writes into `out` and returns it.
+     * @param {Float32Array|number[]} out  Length-3 destination.
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {Float32Array|number[]} `out`, for chaining.
+     */
+    sampleVelocity(out, x, y, z) {
+        const res_x = this.#resolution[0];
+        const res_y = this.#resolution[1];
+        const res_z = this.#resolution[2];
+        out[0] = scs3d_sample_linear(this.velocity_x, res_x + 1, res_y, res_z, x + 0.5, y, z);
+        out[1] = scs3d_sample_linear(this.velocity_y, res_x, res_y + 1, res_z, x, y + 0.5, z);
+        out[2] = scs3d_sample_linear(this.velocity_z, res_x, res_y, res_z + 1, x, y, z + 0.5);
+        return out;
+    }
+
+    /**
+     * Sample a scalar attribute at a fractional grid position.
+     * @param {string} name
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     * @return {number} trilinearly-interpolated value at `(x, y, z)`.
+     */
+    sampleScalar(name, x, y, z) {
+        const data = this.getScalarData(name);
+        assert.notNull(data, `scalar attribute '${name}'`);
+        return scs3d_sample_linear(data, this.#resolution[0], this.#resolution[1], this.#resolution[2], x, y, z);
+    }
+
+    /**
+     * Strict value equality. Two fields are equal iff they have the same resolution,
+     * the same set of scalar attributes (matched by name AND index), and the same
+     * buffer contents in `velocity_*`, `solid`, `pressure`, and each scalar. Pre-build
+     * fields compare by resolution + attribute names only (their buffers are null).
+     *
+     * O(N) — walks every cell. Use {@link hash} for change-detection on hot paths.
+     *
+     * @param {FluidField} other
+     * @return {boolean}
+     */
+    equals(other) {
+        if (other === this) {
+            return true;
+        }
+        if (!(other instanceof FluidField)) {
+            return false;
+        }
+
+        if (this.#resolution[0] !== other.#resolution[0]
+            || this.#resolution[1] !== other.#resolution[1]
+            || this.#resolution[2] !== other.#resolution[2]) {
+            return false;
+        }
+
+        if (this.#built !== other.#built) {
+            return false;
+        }
+
+        const my_attrs = this.#scalar_attributes;
+        const other_attrs = other.#scalar_attributes;
+        if (my_attrs.length !== other_attrs.length) {
+            return false;
+        }
+        for (let i = 0; i < my_attrs.length; i++) {
+            if (my_attrs[i].name !== other_attrs[i].name) {
+                return false;
+            }
+        }
+
+        if (!this.#built) {
+            // Buffers are null on both sides; resolution + names already matched.
+            return true;
+        }
+
+        if (!is_typed_array_equals(this.velocity_x, other.velocity_x)
+            || !is_typed_array_equals(this.velocity_y, other.velocity_y)
+            || !is_typed_array_equals(this.velocity_z, other.velocity_z)) {
+            return false;
+        }
+        if (!is_typed_array_equals(this.solid, other.solid)) {
+            return false;
+        }
+        if (!is_typed_array_equals(this.pressure, other.pressure)) {
+            return false;
+        }
+        for (let i = 0; i < my_attrs.length; i++) {
+            if (!is_typed_array_equals(my_attrs[i].data, other_attrs[i].data)) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * Fast hash suitable for change-detection. Combines the resolution and a *sparse*
+     * sample of the velocity_x buffer — {@link sparse_typed_array_hash} only inspects
+     * the first ~1024 cells with stride enough to take ~31 samples, regardless of how
+     * large the field is. The hash will catch most local edits to the velocity field
+     * but is not a content-perfect fingerprint; for that, fall through to
+     * {@link equals}.
+     *
+     * Constant-time relative to grid size in the common case.
+     *
+     * @return {number}
+     */
+    hash() {
+        const velocity_sample = this.#built
+            ? sparse_typed_array_hash(this.velocity_x, 0, this.velocity_x.length)
+            : 0;
+        return combine_hash(
+            this.#resolution[0],
+            this.#resolution[1],
+            this.#resolution[2],
+            this.#scalar_attributes.length,
+            velocity_sample
+        );
+    }
+
+    /**
+     * Rebuild {@link solid_neighbour_mask} and {@link pressure_diag} from the
+     * current {@link solid} buffer.
+     *
+     * O(N) — two byte-writes per cell, six byte-reads per cell. Called by the
+     * simulator once per step and at the top of each direct project() call, so
+     * callers never have to remember to invalidate the mask after mutating
+     * solids; the cost is amortized across the SOR sweep's many iterations.
+     *
+     * Encoding: see {@link solid_neighbour_mask} and {@link pressure_diag}.
+     */
+    recomputeSolidNeighbourMask() {
+        if (!this.#built) {
+            return;
+        }
+        v3_grid_compute_solid_neighbour_mask(
+            this.solid_neighbour_mask,
+            this.pressure_diag,
+            this.solid,
+            this.#resolution[0], this.#resolution[1], this.#resolution[2]
+        );
+        v3_mac_compute_face_solid(
+            this.face_solid_x, this.face_solid_y, this.face_solid_z,
+            this.velocity_x, this.velocity_y, this.velocity_z,
+            this.solid,
+            this.#resolution[0], this.#resolution[1], this.#resolution[2]
+        );
+    }
+
+    /**
+     * Translate the field's contents by `(shift_x, shift_y, shift_z)` grid cells —
+     * called when the field's world-space origin moves, so the fluid data (anchored
+     * to world space) follows. Every owned buffer (velocity_x/y/z, solid, pressure,
+     * each scalar attribute) is shifted, then the newly-exposed edges are patched
+     * via {@link v3_grid_patch_edges_uniform} (zero-gradient Neumann extrapolation —
+     * "the field is locally uniform").
+     *
+     * Direction convention matches the primitive: positive shift means the grid's
+     * world origin moved in that direction, so each cell takes the value previously
+     * at its `+shift` neighbour.
+     *
+     * `(0, 0, 0)` is a no-op; |shift| ≥ res on any axis zero-fills (no valid source
+     * left to replicate from). Pre-build fields (buffers null) are no-op'd.
+     *
+     * The solid mask is migrated like every other buffer — solids are anchored to
+     * world space exactly like the fluid they bound, so a wall must stay where the
+     * world says it is when the grid hops a cell. Newly scrolled-in cells become
+     * fluid (`0`): the field knows nothing about un-simulated space, and "empty
+     * until a voxelizer says otherwise" is the only honest default. Callers that
+     * voxelize scene geometry can keep overwriting the mask each tick — the
+     * migrated values are then simply replaced. (Earlier behaviour cleared the
+     * whole mask on shift, which made every grid hop simulate one tick with no
+     * walls anywhere — fluid leaked through geometry until the caller re-splatted.)
+     *
+     * The derived {@link solid_neighbour_mask} is refreshed here too, so the field
+     * stays self-consistent for direct kernel users; the simulator's per-step
+     * refresh makes this redundant in the ECS path but shifts are rare (once per
+     * cell crossing) and the pass is one byte-write per cell.
+     *
+     * @param {number} shift_x  integer
+     * @param {number} shift_y  integer
+     * @param {number} shift_z  integer
+     */
+    shift(shift_x, shift_y, shift_z) {
+        if (!this.#built) {
+            return;
+        }
+        if (shift_x === 0 && shift_y === 0 && shift_z === 0) {
+            return;
+        }
+
+        const rx = this.#resolution[0];
+        const ry = this.#resolution[1];
+        const rz = this.#resolution[2];
+
+        // Velocity components — each face grid shifts with its own dimensions.
+        // Faces ride along with the cells (face i sits between cells i−1 and
+        // i), so the integer cell shift applies unchanged on the face lattice.
+        v3_grid_shift_in_place(this.velocity_x, rx + 1, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_x, rx + 1, ry, rz, shift_x, shift_y, shift_z);
+
+        v3_grid_shift_in_place(this.velocity_y, rx, ry + 1, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_y, rx, ry + 1, rz, shift_x, shift_y, shift_z);
+
+        v3_grid_shift_in_place(this.velocity_z, rx, ry, rz + 1, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.velocity_z, rx, ry, rz + 1, shift_x, shift_y, shift_z);
+
+        // Solid mask — world-anchored like the fluid; scrolled-in cells are fluid.
+        // recomputeSolidNeighbourMask refreshes every derived mask (cell + face).
+        v3_grid_shift_in_place(this.solid, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_constant(this.solid, rx, ry, rz, shift_x, shift_y, shift_z, 0);
+        this.recomputeSolidNeighbourMask();
+
+        // Pressure (warm-start state, carried across steps).
+        v3_grid_shift_in_place(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
+        v3_grid_patch_edges_uniform(this.pressure, rx, ry, rz, shift_x, shift_y, shift_z);
+
+        // Scalar attributes.
+        for (let i = 0; i < this.#scalar_attributes.length; i++) {
+            const data = this.#scalar_attributes[i].data;
+            v3_grid_shift_in_place(data, rx, ry, rz, shift_x, shift_y, shift_z);
+            v3_grid_patch_edges_uniform(data, rx, ry, rz, shift_x, shift_y, shift_z);
+        }
+    }
+
+    /**
+     * Zero velocity, pressure, and all scalar attributes. Solid mask is preserved.
+     * Pressure is cleared to drop the warm-start (otherwise the next step's solve
+     * begins from a stale solution that no longer matches the zero velocity).
+     */
+    clear() {
+        assert.ok(this.#built, "build() must be called before clear()");
+        this.velocity_x.fill(0);
+        this.velocity_y.fill(0);
+        this.velocity_z.fill(0);
+        this.pressure.fill(0);
+        for (const attr of this.#scalar_attributes) {
+            attr.data.fill(0);
+        }
+    }
+}