@woosh/meep-engine 3.49.0 → 3.50.0

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts

@@ -0,0 +1,191 @@
+/**
+ * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../wind/GPUSceneWind.js").GPUSceneWind} GPUSceneWind
+ * @typedef {import("./forcing/GPUFluidForcing.js").GPUFluidForcing} GPUFluidForcing
+ */
+/**
+ * Most cascades a stack holds (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5).
+ * @type {number}
+ */
+export const GPU_FLUID_CASCADE_STACK_LIMIT: number;
+/**
+ * The GPU fluid's nested, scrolling, two-way coupled cascades around one anchor
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7–§9): 1 to 8 {@link GPUFluidCascade}s, cascade `c` of
+ * `cell_size·2^c` at one power-of-two resolution, each the parent of the one below it; the coarsest's
+ * parent is the far field.
+ *
+ * The far field comes in as {@link FluidAtmosphere} records, world units, one a tick: the stack reads no
+ * ECS. A body force in one asserts (the GPU fluid drops it).
+ *
+ * **A tick** ({@link record_tick}), in the order of §8, all into one graph:
+ *
+ *     placement   the ruler's coarse cascade c (t mod 2^c = 2^(c−1)), then cascade 0, each by
+ *                 FluidCascadePlacement: hysteresis, the nesting clamp, a jump re-placing the whole
+ *                 stack
+ *     fills       every cascade that moved, coarsest first: what it exposed, from its parent
+ *     queries     with a GPUFluidForcing, every brick of cascade 0 and c against its cascade's LBVH
+ *     restrict    cascade c − 1 into cascade c (feedback), when c ≥ 1
+ *     forcing c   its solid flags, walls and forcing (with a GPUFluidForcing)
+ *     step c      dt·2^c, beside its parent, with the tick's vorticity confinement
+ *     forcing 0
+ *     step 0      dt, beside cascade 1
+ *
+ * so every tick steps cascade 0 and at most one other: at four cascades, 7 ticks in 8 step two.
+ *
+ * **Read records.** Each cascade keeps on the CPU the instant its velocity was last brought to and
+ * `v_far`, `Λ` then; {@link update_read} turns them into each cascade's `k = e^(−(Λ(t) − Λ(t_s)))` for
+ * the instant of the frame, so a reader takes `v_far(t) + (v − v_far(t_s))·k` with no large number on
+ * the device, across dropped ticks and ruler intervals alike.
+ *
+ * **The frame's publish** ({@link record_publish}), once after the frame's last tick: the stack's
+ * shape, every window and `k` into a `GPUSceneWind`'s table with `v_far(t)`, and a
+ * `FluidWindPublish` of every cascade whose velocity changed since its last publish (it stepped, or a
+ * placement filled it) into its tile, the skirt from its parent as its step reads it.
+ *
+ * **What a published field reads, per cascade** ({@link cascade}): `velocity` (its u, v, w views,
+ * toroidal), `corner` (world cell at window-local 0, Int32Array), `cell_size`, `faces_window(c)` and
+ * `cells_window` (corner, storage corner, size, period), `read_far_velocity` (`v_far(t_s)`) and
+ * `read_keep` (`k`). All retained: nothing is allocated to read them.
+ *
+ * Created placed around `anchor` and filled from the far field of `atmosphere` (velocity `v_far`,
+ * pressure 0); after that nothing is allocated per tick.
+ */
+export class GPUFluidCascadeStack {
+    /**
+     * @param {object} pass
+     * @param {*} _resources
+     * @param {{encoder: import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext}} context
+     */
+    static "__#265@#execute_publish"(pass: object, _resources: any, context: {
+        encoder: import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+    }): void;
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two; 32 or more when
+     *   there is more than one cascade
+     * @param {number} options.cell_size metres, cascade 0's
+     * @param {number} options.cascade_count 1 to {@link GPU_FLUID_CASCADE_STACK_LIMIT}
+     * @param {ArrayLike<number>} options.anchor world metres, what the windows centre on
+     * @param {Float64Array|number[]} options.atmosphere a {@link FluidAtmosphere} record, world units
+     * @param {number} options.atmosphere_offset
+     */
+    constructor({ device, resolution, cell_size, cascade_count, anchor, atmosphere, atmosphere_offset }: {
+        device: GPUDevice;
+        resolution: ArrayLike<number>;
+        cell_size: number;
+        cascade_count: number;
+        anchor: ArrayLike<number>;
+        atmosphere: Float64Array | number[];
+        atmosphere_offset: number;
+    });
+    /**
+     * Whether rows 2..5 of every cascade relax toward its parent (§9). On by design; off for the seam
+     * probes' A/B.
+     * @type {boolean}
+     */
+    relaxation_band: boolean;
+    /**
+     * Whether each coarse step takes its child's interior first (§9). On by design; off is the
+     * uncoupled-grid reversal the seam probes measure.
+     * @type {boolean}
+     */
+    feedback: boolean;
+    /** @returns {number} */
+    get cascade_count(): number;
+    /**
+     * Cells on each axis, every cascade's.
+     * @returns {Readonly<Int32Array>}
+     */
+    get resolution(): Readonly<Int32Array>;
+    /**
+     * The last tick recorded, -1 before the first.
+     * @returns {number}
+     */
+    get last_tick(): number;
+    /**
+     * Cascade `c`, finest first.
+     * @param {number} c
+     * @returns {GPUFluidCascade}
+     */
+    cascade(c: number): GPUFluidCascade;
+    /**
+     * The world box of the coarsest cascade's window now, `[x0, y0, z0, x1, y1, z1]` metres: what
+     * `GPUFluidForcing#record_frame` clips its leaves to, unioned over a frame's stacks.
+     *
+     * @param {Float64Array|number[]} out
+     */
+    coarsest_bounds(out: Float64Array | number[]): void;
+    /**
+     * Each cascade's read factor `k` for the instant `atmosphere` describes, once a frame; see
+     * {@link GPUFluidCascade#update_read}.
+     *
+     * @param {Float64Array|number[]} atmosphere
+     * @param {number} offset
+     */
+    update_read(atmosphere: Float64Array | number[], offset: number): void;
+    /**
+     * Record one tick into `graph`: placement, fills, feedback and the ruler's steps.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.tick the fixed-step tick, a non-negative integer above the last; ticks in
+     *   between are dropped, and the identity covers them
+     * @param {number} options.dt seconds, cascade 0's step
+     * @param {ArrayLike<number>} options.anchor world metres
+     * @param {Float64Array|number[]} options.atmosphere the far field at the end of the tick, a
+     *   {@link FluidAtmosphere} record, world units
+     * @param {number} options.atmosphere_offset
+     * @param {GPUFluidForcing|null} [options.forcing] the scene's effectors and obstacles, whose frame
+     *   was recorded into `graph` (`GPUFluidForcing#record_frame`); `null`, the default, for none
+     * @param {number} [options.vorticity_confinement] its strength ε, per second, ≥ 0, for both of the
+     *   tick's steps, each with its own cell and step (`GPUFluidCascade#record_step`); 0, the default,
+     *   records no curl pass
+     */
+    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing, vorticity_confinement }: {
+        graph: FrameGraph;
+        tick: number;
+        dt: number;
+        anchor: ArrayLike<number>;
+        atmosphere: Float64Array | number[];
+        atmosphere_offset: number;
+        forcing?: GPUFluidForcing | null;
+        vorticity_confinement?: number;
+    }): void;
+    /**
+     * Record the frame's publish into `graph`, after its last tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+     * §11): the field's table now, and one `FluidWindPublish` dispatch for each cascade whose velocity
+     * changed since it was last published, finest first. The table:
+     *
+     *     wind.set_cascades(count, resolution)
+     *     wind.set_cascade_window(c, corner, cell_size)       every cascade
+     *     wind.set_cascade_decay(c, k)                        k = e^(−(Λ(t) − Λ(t_s,c))), read_keep
+     *     wind.set_far_velocity(v_far(t))
+     *
+     * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
+     * from its old tile through its new decay. The field's own update uploads the table.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUSceneWind} options.wind the scene's wind field
+     * @param {Float64Array|number[]} options.atmosphere the far field now, a {@link FluidAtmosphere}
+     *   record, world units
+     * @param {number} options.atmosphere_offset
+     */
+    record_publish({ graph, wind, atmosphere, atmosphere_offset }: {
+        graph: FrameGraph;
+        wind: GPUSceneWind;
+        atmosphere: Float64Array | number[];
+        atmosphere_offset: number;
+    }): void;
+    /**
+     * Release every cascade. Ticks recorded into a graph that has not run yet encode nothing.
+     */
+    destroy(): void;
+    #private;
+}
+export type FrameGraph = import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GPUSceneWind = import("../wind/GPUSceneWind.js").GPUSceneWind;
+export type GPUFluidForcing = import("./forcing/GPUFluidForcing.js").GPUFluidForcing;
+import { GPUFluidCascade } from "./GPUFluidCascade.js";
+//# sourceMappingURL=GPUFluidCascadeStack.d.ts.map

package/src/shade/renderer/fluid/GPUFluidCascadeStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUFluidCascadeStack.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fluid/GPUFluidCascadeStack.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;;GAGG;AACH,4CAFU,MAAM,CAE+B;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IA0VI;;;;OAIG;IACH,uCAJW,MAAM,4BAEN;QAAC,OAAO,EAAE,OAAO,wCAAwC,EAAE,sBAAsB,CAAA;KAAC,QAkC5F;IAhVD;;;;;;;;;;OAUG;IACH;QAT8B,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;QAED,SAAS,EAAzB,MAAM;QACU,aAAa,EAA7B,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QACL,iBAAiB,EAAjC,MAAM;OAwChB;IA/DD;;;;OAIG;IACH,iBAFU,OAAO,CAEM;IAEvB;;;;OAIG;IACH,UAFU,OAAO,CAED;IAqDhB,wBAAwB;IACxB,4BAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,eAAe,CAI3B;IAED;;;;;OAKG;IACH,qBAFW,YAAY,GAAC,MAAM,EAAE,QAY/B;IAED;;;;;;OAMG;IACH,wBAHW,YAAY,GAAC,MAAM,EAAE,UACrB,MAAM,QAMhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAd+B,KAAK,EAAzB,UAAU;QACM,IAAI,EAApB,MAAM;QAEU,EAAE,EAAlB,MAAM;QACqB,MAAM,EAAjC,UAAU,MAAM,CAAC;QACc,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;QACyB,OAAO,GAAtC,eAAe,GAAC,IAAI;QAEH,qBAAqB,GAAtC,MAAM;aA8FhB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACY,IAAI,EAA1B,YAAY;QACmB,UAAU,EAAzC,YAAY,GAAC,MAAM,EAAE;QAEL,iBAAiB,EAAjC,MAAM;aAsDhB;IA4CD;;OAEG;IACH,gBAUC;;CACJ;yBApcY,OAAO,2DAA2D,EAAE,UAAU;2BAC9E,OAAO,yBAAyB,EAAE,YAAY;8BAC9C,OAAO,8BAA8B,EAAE,eAAe;gCARnC,sBAAsB"}

package/src/shade/renderer/fluid/GPUFluidCascadeStack.js

@@ -0,0 +1,463 @@
+import { assert } from "../../../core/assert.js";
+import { window_scroll_regions } from "../../../core/geom/clipmap/window_scroll_regions.js";
+import { fluid_cascade_ruler } from "./fluid_cascade_ruler.js";
+import { FluidCascadePlacement } from "./FluidCascadePlacement.js";
+import { GPUFluidCascade } from "./GPUFluidCascade.js";
+import { FluidAtmosphere } from "../../../engine/physics/fluid/FluidAtmosphere.js";
+import { fluid_cascade_parent_value } from "./coupling/FLUID_CASCADE_PARENT_STRUCT.js";
+import { FluidWindPublish } from "./publish/FluidWindPublish.js";
+
+/**
+ * @typedef {import("../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../wind/GPUSceneWind.js").GPUSceneWind} GPUSceneWind
+ * @typedef {import("./forcing/GPUFluidForcing.js").GPUFluidForcing} GPUFluidForcing
+ */
+
+/**
+ * Most cascades a stack holds (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §5).
+ * @type {number}
+ */
+export const GPU_FLUID_CASCADE_STACK_LIMIT = 8;
+
+/**
+ * The GPU fluid's nested, scrolling, two-way coupled cascades around one anchor
+ * (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7–§9): 1 to 8 {@link GPUFluidCascade}s, cascade `c` of
+ * `cell_size·2^c` at one power-of-two resolution, each the parent of the one below it; the coarsest's
+ * parent is the far field.
+ *
+ * The far field comes in as {@link FluidAtmosphere} records, world units, one a tick: the stack reads no
+ * ECS. A body force in one asserts (the GPU fluid drops it).
+ *
+ * **A tick** ({@link record_tick}), in the order of §8, all into one graph:
+ *
+ *     placement   the ruler's coarse cascade c (t mod 2^c = 2^(c−1)), then cascade 0, each by
+ *                 FluidCascadePlacement: hysteresis, the nesting clamp, a jump re-placing the whole
+ *                 stack
+ *     fills       every cascade that moved, coarsest first: what it exposed, from its parent
+ *     queries     with a GPUFluidForcing, every brick of cascade 0 and c against its cascade's LBVH
+ *     restrict    cascade c − 1 into cascade c (feedback), when c ≥ 1
+ *     forcing c   its solid flags, walls and forcing (with a GPUFluidForcing)
+ *     step c      dt·2^c, beside its parent, with the tick's vorticity confinement
+ *     forcing 0
+ *     step 0      dt, beside cascade 1
+ *
+ * so every tick steps cascade 0 and at most one other: at four cascades, 7 ticks in 8 step two.
+ *
+ * **Read records.** Each cascade keeps on the CPU the instant its velocity was last brought to and
+ * `v_far`, `Λ` then; {@link update_read} turns them into each cascade's `k = e^(−(Λ(t) − Λ(t_s)))` for
+ * the instant of the frame, so a reader takes `v_far(t) + (v − v_far(t_s))·k` with no large number on
+ * the device, across dropped ticks and ruler intervals alike.
+ *
+ * **The frame's publish** ({@link record_publish}), once after the frame's last tick: the stack's
+ * shape, every window and `k` into a `GPUSceneWind`'s table with `v_far(t)`, and a
+ * `FluidWindPublish` of every cascade whose velocity changed since its last publish (it stepped, or a
+ * placement filled it) into its tile, the skirt from its parent as its step reads it.
+ *
+ * **What a published field reads, per cascade** ({@link cascade}): `velocity` (its u, v, w views,
+ * toroidal), `corner` (world cell at window-local 0, Int32Array), `cell_size`, `faces_window(c)` and
+ * `cells_window` (corner, storage corner, size, period), `read_far_velocity` (`v_far(t_s)`) and
+ * `read_keep` (`k`). All retained: nothing is allocated to read them.
+ *
+ * Created placed around `anchor` and filled from the far field of `atmosphere` (velocity `v_far`,
+ * pressure 0); after that nothing is allocated per tick.
+ */
+export class GPUFluidCascadeStack {
+    /** @type {GPUFluidCascade[]} */
+    #cascades = [];
+
+    /** @type {FluidCascadePlacement} */
+    #placement;
+
+    /** @type {Int32Array} */
+    #resolution = new Int32Array(3);
+
+    /** Scratch for a move's exposed boxes, six integers each. */
+    #boxes = new Int32Array(18);
+    #old_corner = new Int32Array(3);
+    #new_corner = new Int32Array(3);
+
+    /** The last tick recorded, -1 before the first. */
+    #last_tick = -1;
+
+    /** Per cascade, 1 while its velocity has changed since its last publish; all at creation. @type {Uint8Array} */
+    #unpublished;
+
+    #publish = new FluidWindPublish();
+
+    /** Per cascade, what its publish reads, snapshot when the publish is recorded. */
+    #publish_records = [];
+
+    /** The publish pass's data: the field, and how many of {@link #publish_order} it publishes. */
+    #publish_pass = { stack: null, wind: null, count: 0, order: null };
+
+    #far_scratch = new Float32Array(3);
+
+    #destroyed = false;
+
+    /**
+     * Whether rows 2..5 of every cascade relax toward its parent (§9). On by design; off for the seam
+     * probes' A/B.
+     * @type {boolean}
+     */
+    relaxation_band = true;
+
+    /**
+     * Whether each coarse step takes its child's interior first (§9). On by design; off is the
+     * uncoupled-grid reversal the seam probes measure.
+     * @type {boolean}
+     */
+    feedback = true;
+
+    /**
+     * @param {object} options
+     * @param {GPUDevice} options.device
+     * @param {ArrayLike<number>} options.resolution cells on each axis, powers of two; 32 or more when
+     *   there is more than one cascade
+     * @param {number} options.cell_size metres, cascade 0's
+     * @param {number} options.cascade_count 1 to {@link GPU_FLUID_CASCADE_STACK_LIMIT}
+     * @param {ArrayLike<number>} options.anchor world metres, what the windows centre on
+     * @param {Float64Array|number[]} options.atmosphere a {@link FluidAtmosphere} record, world units
+     * @param {number} options.atmosphere_offset
+     */
+    constructor({ device, resolution, cell_size, cascade_count, anchor, atmosphere, atmosphere_offset }) {
+        assert.defined(device, 'device');
+        assert.isPositiveInteger(cascade_count, 'cascade_count');
+        assert.lessThanOrEqual(cascade_count, GPU_FLUID_CASCADE_STACK_LIMIT, 'cascade_count');
+
+        this.#resolution.set(resolution);
+
+        const placement = this.#placement = new FluidCascadePlacement({ cascade_count, resolution, cell_size });
+
+        placement.place_all(anchor[0], anchor[1], anchor[2]);
+
+        const corner = new Int32Array(3);
+
+        for (let c = 0; c < cascade_count; c++) {
+            for (let axis = 0; axis < 3; axis++) {
+                corner[axis] = placement.corner(c, axis);
+            }
+
+            this.#cascades.push(new GPUFluidCascade({
+                device,
+                resolution,
+                cell_size: placement.cell_size(c),
+                corner,
+                atmosphere,
+                atmosphere_offset,
+            }));
+
+            this.#publish_records.push({
+                corner: new Int32Array(3),
+                far_velocity: new Float32Array(3),
+                parent: fluid_cascade_parent_value(),
+                parent_faces: { u: null, v: null, w: null, pressure: null },
+            });
+        }
+
+        this.#unpublished = new Uint8Array(cascade_count).fill(1);
+        this.#publish_pass.stack = this;
+        this.#publish_pass.order = new Int32Array(cascade_count);
+    }
+
+    /** @returns {number} */
+    get cascade_count() {
+        return this.#cascades.length;
+    }
+
+    /**
+     * Cells on each axis, every cascade's.
+     * @returns {Readonly<Int32Array>}
+     */
+    get resolution() {
+        return this.#resolution;
+    }
+
+    /**
+     * The last tick recorded, -1 before the first.
+     * @returns {number}
+     */
+    get last_tick() {
+        return this.#last_tick;
+    }
+
+    /**
+     * Cascade `c`, finest first.
+     * @param {number} c
+     * @returns {GPUFluidCascade}
+     */
+    cascade(c) {
+        return this.#cascades[c];
+    }
+
+    /**
+     * The world box of the coarsest cascade's window now, `[x0, y0, z0, x1, y1, z1]` metres: what
+     * `GPUFluidForcing#record_frame` clips its leaves to, unioned over a frame's stacks.
+     *
+     * @param {Float64Array|number[]} out
+     */
+    coarsest_bounds(out) {
+        const coarsest = this.#cascades[this.#cascades.length - 1];
+        const corner = coarsest.corner;
+        const h = coarsest.cell_size;
+        const resolution = this.#resolution;
+
+        for (let axis = 0; axis < 3; axis++) {
+            out[axis] = corner[axis] * h;
+            out[axis + 3] = (corner[axis] + resolution[axis]) * h;
+        }
+    }
+
+    /**
+     * Each cascade's read factor `k` for the instant `atmosphere` describes, once a frame; see
+     * {@link GPUFluidCascade#update_read}.
+     *
+     * @param {Float64Array|number[]} atmosphere
+     * @param {number} offset
+     */
+    update_read(atmosphere, offset) {
+        for (const cascade of this.#cascades) {
+            cascade.update_read(atmosphere, offset);
+        }
+    }
+
+    /**
+     * Record one tick into `graph`: placement, fills, feedback and the ruler's steps.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.tick the fixed-step tick, a non-negative integer above the last; ticks in
+     *   between are dropped, and the identity covers them
+     * @param {number} options.dt seconds, cascade 0's step
+     * @param {ArrayLike<number>} options.anchor world metres
+     * @param {Float64Array|number[]} options.atmosphere the far field at the end of the tick, a
+     *   {@link FluidAtmosphere} record, world units
+     * @param {number} options.atmosphere_offset
+     * @param {GPUFluidForcing|null} [options.forcing] the scene's effectors and obstacles, whose frame
+     *   was recorded into `graph` (`GPUFluidForcing#record_frame`); `null`, the default, for none
+     * @param {number} [options.vorticity_confinement] its strength ε, per second, ≥ 0, for both of the
+     *   tick's steps, each with its own cell and step (`GPUFluidCascade#record_step`); 0, the default,
+     *   records no curl pass
+     */
+    record_tick({ graph, tick, dt, anchor, atmosphere, atmosphere_offset, forcing = null, vorticity_confinement = 0 }) {
+        assert.notOk(this.#destroyed, 'the stack is destroyed');
+        assert.defined(graph, 'graph');
+        assert.isNonNegativeInteger(tick, 'tick');
+        assert.greaterThan(tick, this.#last_tick, 'ticks rise');
+        assert.isFinite(dt, 'dt');
+        assert.greaterThan(dt, 0, 'dt');
+
+        const cascades = this.#cascades;
+        const count = cascades.length;
+        const placement = this.#placement;
+        const x = anchor[0], y = anchor[1], z = anchor[2];
+
+        const coarse = fluid_cascade_ruler(tick, count);
+
+        // placement on the stepping cascades' own tick, coarsest first; a jump re-places them all
+        placement.begin();
+
+        if (coarse >= 0) {
+            placement.place(coarse, x, y, z);
+        }
+
+        placement.place(0, x, y, z);
+
+        // fills, coarsest first, so a child fills from its parent's new window
+        for (let c = count - 1; c >= 0; c--) {
+            if (!placement.moved(c)) {
+                continue;
+            }
+
+            for (let axis = 0; axis < 3; axis++) {
+                this.#old_corner[axis] = placement.previous_corner(c, axis);
+                this.#new_corner[axis] = placement.corner(c, axis);
+            }
+
+            const cascade = cascades[c];
+            const box_count = window_scroll_regions(this.#old_corner, this.#new_corner, this.#resolution, 3, this.#boxes);
+
+            cascade.place(this.#new_corner);
+            cascade.record_fill({ graph, boxes: this.#boxes, box_count, parent: c + 1 < count ? cascades[c + 1] : null });
+            this.#unpublished[c] = 1;
+        }
+
+        const band = this.relaxation_band;
+
+        // the brick queries of both stepping cascades, against the windows they step in
+        if (forcing !== null) {
+            forcing.record_queries({ graph, first: cascades[0], second: coarse >= 0 ? cascades[coarse] : null });
+        }
+
+        if (coarse >= 0) {
+            const cascade = cascades[coarse];
+            const coarse_dt = dt * 2 ** coarse;
+
+            this.#unpublished[coarse] = 1;
+
+            if (this.feedback) {
+                cascade.record_restrict({ graph, child: cascades[coarse - 1] });
+            }
+
+            // after the restriction, which would overwrite the walls it pins
+            const coarse_forcing = forcing === null ? null : forcing.record_forcing({ graph, cascade, dt: coarse_dt });
+
+            cascade.record_step({
+                graph,
+                dt: coarse_dt,
+                atmosphere,
+                atmosphere_offset,
+                parent: coarse + 1 < count ? cascades[coarse + 1] : null,
+                relaxation_band: band,
+                forcing: coarse_forcing,
+                vorticity_confinement,
+            });
+        }
+
+        const fine_forcing = forcing === null ? null : forcing.record_forcing({ graph, cascade: cascades[0], dt });
+
+        cascades[0].record_step({
+            graph,
+            dt,
+            atmosphere,
+            atmosphere_offset,
+            parent: count > 1 ? cascades[1] : null,
+            relaxation_band: band,
+            forcing: fine_forcing,
+            vorticity_confinement,
+        });
+
+        this.#unpublished[0] = 1;
+        this.#last_tick = tick;
+    }
+
+    /**
+     * Record the frame's publish into `graph`, after its last tick (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md
+     * §11): the field's table now, and one `FluidWindPublish` dispatch for each cascade whose velocity
+     * changed since it was last published, finest first. The table:
+     *
+     *     wind.set_cascades(count, resolution)
+     *     wind.set_cascade_window(c, corner, cell_size)       every cascade
+     *     wind.set_cascade_decay(c, k)                        k = e^(−(Λ(t) − Λ(t_s,c))), read_keep
+     *     wind.set_far_velocity(v_far(t))
+     *
+     * A tile holds `v − v_far(t_s,c)` and `k` is taken for `t`, so a cascade that did not step reads
+     * from its old tile through its new decay. The field's own update uploads the table.
+     *
+     * @param {object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUSceneWind} options.wind the scene's wind field
+     * @param {Float64Array|number[]} options.atmosphere the far field now, a {@link FluidAtmosphere}
+     *   record, world units
+     * @param {number} options.atmosphere_offset
+     */
+    record_publish({ graph, wind, atmosphere, atmosphere_offset }) {
+        assert.notOk(this.#destroyed, 'the stack is destroyed');
+        assert.defined(graph, 'graph');
+        assert.defined(wind, 'wind');
+        assert.isNonNegativeInteger(atmosphere_offset, 'atmosphere_offset');
+
+        const cascades = this.#cascades;
+        const count = cascades.length;
+
+        wind.set_cascades(count, this.#resolution);
+
+        const pass = this.#publish_pass;
+        let pending = 0;
+
+        for (let c = 0; c < count; c++) {
+            const cascade = cascades[c];
+
+            cascade.update_read(atmosphere, atmosphere_offset);
+
+            wind.set_cascade_window(c, cascade.corner, cascade.cell_size);
+            wind.set_cascade_decay(c, cascade.read_keep);
+
+            if (this.#unpublished[c] === 0) {
+                continue;
+            }
+
+            // what the publish reads, as it is now: the frame's ticks are recorded
+            const record = this.#publish_records[c];
+
+            record.corner.set(cascade.corner);
+            record.far_velocity.set(cascade.read_far_velocity);
+            cascade.describe_parent(record.parent, record.parent_faces, c + 1 < count ? cascades[c + 1] : null);
+
+            pass.order[pending++] = c;
+            this.#unpublished[c] = 0;
+        }
+
+        const far = this.#far_scratch;
+        far[0] = atmosphere[atmosphere_offset + FluidAtmosphere.VELOCITY_X];
+        far[1] = atmosphere[atmosphere_offset + FluidAtmosphere.VELOCITY_Y];
+        far[2] = atmosphere[atmosphere_offset + FluidAtmosphere.VELOCITY_Z];
+
+        wind.set_far_velocity(far);
+
+        if (pending === 0) {
+            return;
+        }
+
+        pass.wind = wind;
+        pass.count = pending;
+
+        graph.add('Fluid / wind publish', pass, GPUFluidCascadeStack.#execute_publish).make_side_effect();
+    }
+
+    /** The options {@link FluidWindPublish#record} takes, rewritten for every cascade. */
+    #publish_options = { encoder: null, velocity: null, corner: null, far_velocity: null, parent: null, parent_faces: null, atlas: null, slot: 0 };
+
+    /**
+     * @param {object} pass
+     * @param {*} _resources
+     * @param {{encoder: import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext}} context
+     */
+    static #execute_publish(pass, _resources, context) {
+        const stack = pass.stack;
+
+        if (stack.#destroyed) {
+            return;
+        }
+
+        const options = stack.#publish_options;
+        const wind = pass.wind;
+
+        options.encoder = context.encoder;
+        options.atlas = wind.atlas;
+
+        try {
+            for (let i = 0; i < pass.count; i++) {
+                const c = pass.order[i];
+                const record = stack.#publish_records[c];
+
+                options.velocity = stack.#cascades[c].velocity;
+                options.corner = record.corner;
+                options.far_velocity = record.far_velocity;
+                options.parent = record.parent;
+                options.parent_faces = record.parent_faces;
+                options.slot = wind.slot(c);
+
+                stack.#publish.record(options);
+            }
+        } finally {
+            options.encoder = options.atlas = options.velocity = options.corner = options.far_velocity = null;
+            options.parent = options.parent_faces = null;
+            pass.wind = null;
+        }
+    }
+
+    /**
+     * Release every cascade. Ticks recorded into a graph that has not run yet encode nothing.
+     */
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        for (const cascade of this.#cascades) {
+            cascade.destroy();
+        }
+    }
+}

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_FILL_STRUCT.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bricks of a cascade's fill: cells 4 on a side, the unit corners move in.
+ * @type {number}
+ */
+export const FLUID_CASCADE_FILL_BRICK: number;
+/**
+ * Boxes one fill writes at most: a move exposes one slab per axis it moved along
+ * (`window_scroll_regions`).
+ * @type {number}
+ */
+export const FLUID_CASCADE_FILL_BOX_LIMIT: number;
+/**
+ * What a cascade's fill writes (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §7), as the uniform `fill`.
+ *
+ * - `cells`, `faces_u`, `faces_v`, `faces_w`: where the cascade's pressure and faces are stored,
+ *   as `FLUID_MAC_STEP_STRUCT` has them; `cells.corner` is the cascade's corner.
+ * - `box0`, `box1`, `box2`: each box's smallest window-local cell, a multiple of
+ *   {@link FLUID_CASCADE_FILL_BRICK};
+ * - `box0_bricks`, `box1_bricks`, `box2_bricks`: bricks along each axis of each box;
+ * - `box_end`: bricks through the end of box 0, 1 and 2, so `box_end.z` is the dispatch's live count.
+ *   An unused box has no bricks.
+ *
+ * @type {WebGPUStruct}
+ */
+export const FLUID_CASCADE_FILL_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=FLUID_CASCADE_FILL_STRUCT.d.ts.map

package/src/shade/renderer/fluid/coupling/FLUID_CASCADE_FILL_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FLUID_CASCADE_FILL_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/fluid/coupling/FLUID_CASCADE_FILL_STRUCT.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;;GAIG;AACH,2CAFU,MAAM,CAE8B;AAE9C;;;;;;;;;;;;GAYG;AACH,wCAFU,YAAY,CAcC;6BAxCM,mCAAmC"}