@woosh/meep-engine 3.39.0 → 3.40.0

package/src/shade/renderer/water/surface/GPUWaterWaveSimulation.d.ts

@@ -1,98 +1,25 @@
 /**
- * Slope variance of the waves a grid does not resolve, from the wind: the Cox-Munk total,
- * 0.003 + 5.12e-3·U for wind speed U in m/s (Ocean Optics Web Book, "Cox-Munk sea surface slope
- * statistics"). The fit's intercept is ramped in below 1 m/s, where it has no data, so still water
- * is a mirror rather than carrying the open sea's background slopes.
- *
- * @param {number} wind_speed m/s
- * @returns {number}
- */
-export function wind_unresolved_variance(wind_speed: number): number;
-/**
- * What one body holds on the GPU.
- *
- * @typedef {Object} WaterWaveBody
- * @property {number} resolution
- * @property {GPUBuffer[]} state the two alternating height buffers
- * @property {number} parity which of {@link state} holds the current heights
- * @property {GPUBuffer} vertices
- * @property {boolean} written
- */
-/**
- * The primitive surface producer (WATER_OPTICS_PLAN_2026_10_02.md §7.2): a damped linear wave
- * equation on a regular grid over each water body, written out as the surface interface — a
- * vertex buffer and a shared index buffer.
- *
- * It owns its GPU resources, keyed by device so a restart rebuilds them, and records its work at
- * the head of a frame's graph: everything that reads the surface is recorded after it, and the graph
- * runs passes in insertion order. Time advances through {@link advance}, once per tick, and is
- * consumed by the first view to record, so several views of one frame step the simulation once.
+ * A shared wave atlas, indexed by occupied water_waves rows. Calm bodies allocate no grid.
+ * Each fixed step dispatches the whole atlas once; tessellated vertices sample it in local xz.
+ * The regular grid is a displacement field, never the rendered water footprint.
  */
 export class GPUWaterWaveSimulation {
-    /**
-     * Vertices along each side of a body's grid. Changing it rebuilds every body.
-     * @type {number}
-     */
+    onInputsConsumed: Signal;
     resolution: number;
-    /**
-     * Fixed step, s. Explicit and fixed, so a frame-rate change does not change the waves.
-     * @type {number}
-     */
     step: number;
-    /**
-     * Most steps one frame takes; time beyond it is dropped rather than queued, so a stall does not
-     * turn into a burst.
-     * @type {number}
-     */
     max_steps_per_frame: number;
-    /**
-     * Damping everywhere, 1/s.
-     * @type {number}
-     */
     damping: number;
-    /**
-     * Simulated time, s.
-     * @returns {number}
-     */
     get time(): number;
-    /**
-     * @param {number} dt seconds of simulation to add
-     */
-    advance(dt: number): void;
-    /**
-     * Release every GPU resource.
-     */
+    get buffer(): any;
+    get grid_resolution(): number;
+    advance(dt: any): void;
     dispose(): void;
-    /**
-     * Record this frame's steps and surface writes, and publish each surface's interface on it as
-     * `surface.gpu_surface`.
-     *
-     * @param {Object} options
-     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
-     * @param {GPUDevice} options.device
-     * @param {Object[]} options.surfaces bodies with a terrain height texture, as the water system keeps them
-     */
-    record({ graph, device, surfaces }: {
-        graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
-        device: GPUDevice;
-        surfaces: any[];
+    record({ graph, device, scene }: {
+        graph: any;
+        device: any;
+        scene: any;
     }): void;
     #private;
 }
-/**
- * What one body holds on the GPU.
- */
-export type WaterWaveBody = {
-    resolution: number;
-    /**
-     * the two alternating height buffers
-     */
-    state: GPUBuffer[];
-    /**
-     * which of {@link state } holds the current heights
-     */
-    parity: number;
-    vertices: GPUBuffer;
-    written: boolean;
-};
+import Signal from "../../../../core/events/signal/Signal.js";
 //# sourceMappingURL=GPUWaterWaveSimulation.d.ts.map

package/src/shade/renderer/water/surface/GPUWaterWaveSimulation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUWaterWaveSimulation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/GPUWaterWaveSimulation.js"],"names":[],"mappings":"AA2YA;;;;;;;;GAQG;AACH,qDAHW,MAAM,GACJ,MAAM,CAKlB;AAhYD;;;;;;;;;GASG;AAEH;;;;;;;;;GASG;AACH;IACI;;;OAGG;IACH,YAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,MAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,SAFU,MAAM,CAED;IAwCf;;;OAGG;IACH,mBAEC;IAED;;OAEG;IACH,YAFW,MAAM,QAQhB;IAED;;OAEG;IACH,gBAaC;IAED;;;;;;;;OAQG;IACH;QAJsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;QAC9D,MAAM;QACP,QAAQ,EAA1B,KAAQ;aAiDlB;;CAgMJ;;;;;gBA9Wa,MAAM;;;;WACN,WAAW;;;;YACX,MAAM;;aAEN,OAAO"}
+{"version":3,"file":"GPUWaterWaveSimulation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/GPUWaterWaveSimulation.js"],"names":[],"mappings":"AAKA;;;;GAIG;AACH;IACI,yBAAgC;IAChC,mBAAiB;IACjB,aAAe;IACf,4BAAwB;IACxB,gBAAe;IAYf,mBAAiC;IACjC,kBAAkD;IAClD,8BAAqE;IAErE,uBAIC;IAED,gBAMC;IAED;;;;aAiFC;;CACJ;mBA/HkB,0CAA0C"}

package/src/shade/renderer/water/surface/GPUWaterWaveSimulation.js

@@ -1,408 +1,128 @@
-import { assert } from "../../../../core/assert.js";
-import { SAMPLER_LINEAR_UPSCALE } from "../../texture/SAMPLER_LINEAR_UPSCALE.js";
-import { shader_water_surface_write } from "./shader_water_surface_write.js";
-import { shader_water_wave_step } from "./shader_water_wave_step.js";
-import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_PARAMETERS_STRUCT } from "./WATER_WAVE_PARAMETERS_STRUCT.js";
-import { water_surface_grid_indices } from "./water_surface_grid_indices.js";
-
-/**
- * Bytes of one {@link WATER_SURFACE_VERTEX_STRUCT}: three vec4f.
- * @type {number}
- */
-const VERTEX_BYTES = 48;
-
-/**
- * Forcing amplitude per (m/s)² of wind, m/s² — wind stress grows as the square of its speed.
- *
- * Not calibrated to a wave spectrum: chosen so that the playground's 3 m/s breeze gives
- * centimetre-scale waves. The production simulation, not this constant, is where calibration
- * belongs.
- * @type {number}
- */
-const FORCING_PER_WIND2 = 0.02;
-
-/**
- * What one body holds on the GPU.
- *
- * @typedef {Object} WaterWaveBody
- * @property {number} resolution
- * @property {GPUBuffer[]} state the two alternating height buffers
- * @property {number} parity which of {@link state} holds the current heights
- * @property {GPUBuffer} vertices
- * @property {boolean} written
- */
-
-/**
- * The primitive surface producer (WATER_OPTICS_PLAN_2026_10_02.md §7.2): a damped linear wave
- * equation on a regular grid over each water body, written out as the surface interface — a
- * vertex buffer and a shared index buffer.
- *
- * It owns its GPU resources, keyed by device so a restart rebuilds them, and records its work at
- * the head of a frame's graph: everything that reads the surface is recorded after it, and the graph
- * runs passes in insertion order. Time advances through {@link advance}, once per tick, and is
- * consumed by the first view to record, so several views of one frame step the simulation once.
- */
-export class GPUWaterWaveSimulation {
-    /**
-     * Vertices along each side of a body's grid. Changing it rebuilds every body.
-     * @type {number}
-     */
-    resolution = 512;
-
-    /**
-     * Fixed step, s. Explicit and fixed, so a frame-rate change does not change the waves.
-     * @type {number}
-     */
-    step = 1 / 120;
-
-    /**
-     * Most steps one frame takes; time beyond it is dropped rather than queued, so a stall does not
-     * turn into a burst.
-     * @type {number}
-     */
-    max_steps_per_frame = 8;
-
-    /**
-     * Damping everywhere, 1/s.
-     * @type {number}
-     */
-    damping = 0.08;
-
-    /**
-     * @type {GPUDevice|null}
-     */
-    #device = null;
-
-    /**
-     * @type {Map<Object, WaterWaveBody>}
-     */
-    #bodies = new Map();
-
-    /**
-     * @type {GPUBuffer|null}
-     */
-    #indices = null;
-
-    #index_resolution = 0;
-
-    #index_count = 0;
-
-    /**
-     * Simulated time not yet stepped, s.
-     * @type {number}
-     */
-    #pending = 0;
-
-    /**
-     * Simulated time stepped so far, s.
-     * @type {number}
-     */
-    #time = 0;
-
-    /**
-     * Whether the next record writes the surface: once per tick, even a tick of zero, so a paused
-     * frame's previous positions settle onto its current ones.
-     * @type {boolean}
-     */
-    #write_pending = true;
-
-    /**
-     * Simulated time, s.
-     * @returns {number}
-     */
-    get time() {
-        return this.#time;
-    }
-
-    /**
-     * @param {number} dt seconds of simulation to add
-     */
-    advance(dt) {
-        assert.isFinite(dt, 'dt');
-        assert.greaterThanOrEqual(dt, 0, 'dt');
-
-        this.#pending += dt;
-        this.#write_pending = true;
-    }
-
-    /**
-     * Release every GPU resource.
-     */
-    dispose() {
-        for (const body of this.#bodies.values()) {
-            body.state[0].destroy();
-            body.state[1].destroy();
-            body.vertices.destroy();
-        }
-
-        this.#bodies.clear();
-
-        this.#indices?.destroy();
-        this.#indices = null;
-        this.#index_resolution = 0;
-        this.#device = null;
-    }
-
-    /**
-     * Record this frame's steps and surface writes, and publish each surface's interface on it as
-     * `surface.gpu_surface`.
-     *
-     * @param {Object} options
-     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
-     * @param {GPUDevice} options.device
-     * @param {Object[]} options.surfaces bodies with a terrain height texture, as the water system keeps them
-     */
-    record({ graph, device, surfaces }) {
-        assert.defined(graph, 'graph');
-        assert.defined(device, 'device');
-        assert.isArray(surfaces, 'surfaces');
-
-        if (device !== this.#device) {
-            this.dispose();
-            this.#device = device;
-        }
-
-        this.#release_unused(surfaces);
-
-        if (surfaces.length === 0) {
-            return;
-        }
-
-        this.#ensure_indices(device);
-
-        // the epsilon keeps accumulated rounding — two half steps summing to just under one — from
-        // dropping a step
-        const steps = Math.min(Math.floor(this.#pending / this.step + 1e-6), this.max_steps_per_frame);
-        // time past the frame's limit is dropped, so a stall does not come back as a burst
-        this.#pending = Math.max(0, Math.min(this.#pending - steps * this.step, this.step));
-
-        const write = this.#write_pending;
-        this.#write_pending = false;
-
-        if (steps === 0 && !write) {
-            return;
-        }
-
-        const time_start = this.#time;
-        this.#time += steps * this.step;
-
-        for (let i = 0; i < surfaces.length; i++) {
-            const surface = surfaces[i];
-            const body = this.#ensure_body(device, surface);
-
-            surface.gpu_surface = {
-                vertices: body.vertices,
-                indices: this.#indices,
-                index_count: this.#index_count,
-                resolution: body.resolution,
-            };
-
-            this.#record_body(graph, surface, body, steps, time_start);
-        }
-    }
-
-    /**
-     * @param {Object[]} surfaces
-     */
-    #release_unused(surfaces) {
-        for (const [surface, body] of this.#bodies) {
-            if (surfaces.indexOf(surface) !== -1 && body.resolution === this.resolution) {
-                continue;
-            }
-
-            body.state[0].destroy();
-            body.state[1].destroy();
-            body.vertices.destroy();
-
-            this.#bodies.delete(surface);
-
-            if (surface.gpu_surface !== undefined && surface.gpu_surface.vertices === body.vertices) {
-                surface.gpu_surface = undefined;
-            }
-        }
-    }
-
-    /**
-     * @param {GPUDevice} device
-     */
-    #ensure_indices(device) {
-        if (this.#indices !== null && this.#index_resolution === this.resolution) {
-            return;
-        }
-
-        this.#indices?.destroy();
-
-        const indices = water_surface_grid_indices({ resolution: this.resolution });
-
-        this.#indices = device.createBuffer({
-            label: "Water / surface indices",
-            size: indices.byteLength,
-            usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
-        });
-
-        device.queue.writeBuffer(this.#indices, 0, indices);
-
-        this.#index_resolution = this.resolution;
-        this.#index_count = indices.length;
-    }
-
-    /**
-     * @param {GPUDevice} device
-     * @param {Object} surface
-     * @returns {WaterWaveBody}
-     */
-    #ensure_body(device, surface) {
-        const existing = this.#bodies.get(surface);
-
-        if (existing !== undefined) {
-            return existing;
-        }
-
-        const resolution = this.resolution;
-        const vertex_count = resolution * resolution;
-
-        const state_buffer = (label) => device.createBuffer({
-            label,
-            size: vertex_count * 4,
-            usage: GPUBufferUsage.STORAGE,
-        });
-
-        /** @type {WaterWaveBody} */
-        const body = {
-            resolution,
-            state: [state_buffer("Water / wave state A"), state_buffer("Water / wave state B")],
-            parity: 0,
-            vertices: device.createBuffer({
-                label: "Water / surface vertices",
-                size: vertex_count * VERTEX_BYTES,
-                usage: GPUBufferUsage.STORAGE,
-            }),
-            written: false,
-        };
-
-        this.#bodies.set(surface, body);
-
-        return body;
-    }
-
-    /**
-     * @param {Object} surface
-     * @param {WaterWaveBody} body
-     * @param {number} time
-     * @param {number} impulse_count
-     */
-    #parameters(surface, body, time, impulse_count) {
-        const extent = surface.extent;
-        const wind = surface.wind_speed;
-        const direction = surface.wind_direction;
-        const spacing = (extent[2] - extent[0]) / (body.resolution - 1);
-
-        return {
-            extent: Array.from(extent),
-            height_uv: Array.from(surface.height_uv),
-            forcing: [Math.cos(direction), Math.sin(direction), FORCING_PER_WIND2 * wind * wind, 0.5 * wind],
-            impulses: surface.impulses,
-            level: surface.level,
-            spacing,
-            dt: this.step,
-            time,
-            damping: this.damping,
-            sponge_width: Math.max(4, Math.round(body.resolution * 0.04)),
-            sponge_strength: 4,
-            // 2-D CFL: c·dt/dx ≤ 1/√2, with a margin
-            celerity_limit: 0.6 * spacing / this.step,
-            unresolved_variance: wind_unresolved_variance(wind),
-            resolution: body.resolution,
-            impulse_count,
-            first_write: body.written ? 0 : 1,
-        };
-    }
-
-    /**
-     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
-     * @param {Object} surface
-     * @param {WaterWaveBody} body
-     * @param {number} steps
-     * @param {number} time_start
-     */
-    #record_body(graph, surface, body, steps, time_start) {
-        const groups = Math.ceil(body.resolution / 8);
-        // impulses wait for a frame that steps: a paused frame must not drop them
-        const impulses = steps > 0 ? surface.impulses.splice(0, WATER_WAVE_IMPULSE_LIMIT) : [];
-        const parameters = [];
-
-        for (let s = 0; s < steps; s++) {
-            parameters.push(this.#parameters(surface, body, time_start + s * this.step,
-                s === 0 ? impulses.length : 0));
-        }
-
-        while (impulses.length < WATER_WAVE_IMPULSE_LIMIT) {
-            impulses.push([0, 0, 0, 0]);
-        }
-
-        for (const p of parameters) { p.impulses = impulses; }
-
-        const write_parameters = this.#parameters(surface, body, time_start + steps * this.step, 0);
-        write_parameters.impulses = impulses;
-
-        const start_parity = body.parity;
-        body.parity = (start_parity + steps) % 2;
-        body.written = true;
-
-        const end_parity = body.parity;
-
-        const pass = graph.add("Water / surface update", {}, (data, resources, { encoder, graphics }) => {
-            const terrain_height = graphics.textures.obtain(surface.height_texture).obtainView();
-            const height_sampler = graphics.samplers.obtain(SAMPLER_LINEAR_UPSCALE);
-
-            let parity = start_parity;
-
-            for (let s = 0; s < parameters.length; s++) {
-                shader_water_wave_step.dispatch({
-                    encoder,
-                    bindings: {
-                        params: encoder.allocateTransientValueBuffer(WATER_WAVE_PARAMETERS_STRUCT, parameters[s]),
-                        terrain_height,
-                        height_sampler,
-                        state_current: body.state[parity],
-                        state_previous: body.state[1 - parity],
-                    },
-                    group_count_x: groups,
-                    group_count_y: groups,
-                });
-
-                parity = 1 - parity;
-            }
-
-            shader_water_surface_write.dispatch({
-                encoder,
-                bindings: {
-                    params: encoder.allocateTransientValueBuffer(WATER_WAVE_PARAMETERS_STRUCT, write_parameters),
-                    terrain_height,
-                    height_sampler,
-                    state: body.state[end_parity],
-                    vertices: body.vertices,
-                },
-                group_count_x: groups,
-                group_count_y: groups,
-            });
-        });
-
-        // writes persistent resources that later passes read directly
-        pass.make_side_effect();
-    }
-}
-
-/**
- * Slope variance of the waves a grid does not resolve, from the wind: the Cox-Munk total,
- * 0.003 + 5.12e-3·U for wind speed U in m/s (Ocean Optics Web Book, "Cox-Munk sea surface slope
- * statistics"). The fit's intercept is ramped in below 1 m/s, where it has no data, so still water
- * is a mirror rather than carrying the open sea's background slopes.
- *
- * @param {number} wind_speed m/s
- * @returns {number}
- */
-export function wind_unresolved_variance(wind_speed) {
-    const u = Math.max(wind_speed, 0);
-    return 0.003 * Math.min(u, 1) + 5.12e-3 * u;
-}
+import Signal from "../../../../core/events/signal/Signal.js";
+import { assert } from "../../../../core/assert.js";
+import { WATER_WAVE_BATCH_STRUCT, shader_water_wave_batch, shader_water_wave_batch_finish } from "./shader_water_wave_batch.js";
+import { shader_water_wave_bounds, shader_water_wave_domain } from "./shader_water_wave_domain.js";
+
+/**
+ * A shared wave atlas, indexed by occupied water_waves rows. Calm bodies allocate no grid.
+ * Each fixed step dispatches the whole atlas once; tessellated vertices sample it in local xz.
+ * The regular grid is a displacement field, never the rendered water footprint.
+ */
+export class GPUWaterWaveSimulation {
+    onInputsConsumed = new Signal();
+    resolution = 128;
+    step = 1 / 120;
+    max_steps_per_frame = 8;
+    damping = 0.08;
+    #device = null;
+    #scene = null;
+    #state = [];
+    #domain = null;
+    #capacity = 0;
+    #resolution = 0;
+    #parity = 0;
+    #pending = 0;
+    #time = 0;
+    #recorded = new WeakSet();
+    #write_pending = true;
+    get time() { return this.#time; }
+    get buffer() { return this.#state[this.#parity]; }
+    get grid_resolution() { return this.#resolution || this.resolution; }
+
+    advance(dt) {
+        assert.isFinite(dt, 'dt'); assert.greaterThanOrEqual(dt, 0, 'dt');
+        this.#pending += dt;
+        this.#write_pending = true;
+    }
+
+    dispose() {
+        for (const buffer of this.#state) { buffer.destroy(); }
+        this.#domain?.destroy(); this.#domain = null;
+        this.#state = []; this.#capacity = 0; this.#device = null; this.#scene = null;
+        this.#recorded = new WeakSet();
+        this.#write_pending = true;
+    }
+
+    record({ graph, device, scene }) {
+        if (this.#recorded.has(graph)) { return; }
+        if (device !== this.#device || scene !== this.#scene) {
+            this.dispose(); this.#device = device; this.#scene = scene;
+        }
+        this.#recorded.add(graph);
+        if (!this.#write_pending) { return; }
+        this.#write_pending = false;
+        const table = scene.scene_database.get('water_waves');
+        const capacity = table.count === 0 ? 0 : table.element_capacity;
+        assert.isInteger(this.resolution, 'resolution'); assert.greaterThanOrEqual(this.resolution, 2, 'resolution');
+        assert.greaterThan(this.step, 0, 'step');
+        const resize = capacity > this.#capacity || (capacity === 0 && this.#capacity !== 0) || this.resolution !== this.#resolution;
+        const old = this.#state;
+        const old_domain = this.#domain;
+        if (resize || old.length === 0) {
+            const size = Math.max(4, capacity * this.resolution ** 2 * 4);
+            assert.lessThanOrEqual(size, device.limits.maxStorageBufferBindingSize, 'Water wave atlas exceeds device storage limit; lower waves.resolution');
+            this.#state = [0, 1].map(i => device.createBuffer({ label: `Water / wave state ${i}`, size,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST }));
+            this.#domain = device.createBuffer({ label: 'Water / authored footprint', size,
+                usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST });
+            this.#capacity = capacity;
+        }
+        const same_resolution = this.#resolution === this.resolution;
+        this.#resolution = this.resolution;
+        const steps = Math.min(Math.floor(this.#pending / this.step + 1e-6), this.max_steps_per_frame);
+        this.#pending = Math.max(0, Math.min(this.#pending - steps * this.step, this.step));
+        const start = this.#parity, time = this.#time, state = this.#state, domain = this.#domain;
+        this.#parity = (start + steps) % 2;
+        this.#time += steps * this.step;
+        const n = this.#resolution, dt = this.step, damping = this.damping;
+        const pass = graph.add('Water / batched surface update', {}, (_d, _r, { encoder }) => {
+            if (state !== old) {
+                if (same_resolution && old.length !== 0) {
+                    for (let i = 0; i < 2; i++) { encoder.copyBufferToBuffer(old[i], 0, state[i], 0, Math.min(old[i].size, state[i].size)); }
+                    encoder.copyBufferToBuffer(old_domain, 0, domain, 0, Math.min(old_domain.size, domain.size));
+                }
+                encoder.done.then(() => { for (const buffer of old) { buffer.destroy(); } old_domain?.destroy(); });
+            }
+            if (capacity === 0) { return; }
+            const groups = Math.ceil(capacity * n * n / 128);
+            shader_water_wave_domain.dispatch({ encoder, bindings: {
+                batch: encoder.allocateTransientValueBuffer(WATER_WAVE_BATCH_STRUCT,
+                    { resolution: n, capacity, apply_impulses: same_resolution ? 0 : 1 }),
+                scene_database: scene.scene_database_buffer, domain,
+                geometries: scene.geometries.buffer_metadata,
+                blas_lookup: scene.geometries.blas.buffer_metadata, blas_data: scene.geometries.blas.buffer_data,
+                meshlet_metadata: scene.geometries.meshlets.buffer_metadata, meshlet_data: scene.geometries.meshlets.buffer_data,
+            }, group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+            const dispatch = (parity, step_dt, step_time, apply_impulses) => {
+                shader_water_wave_batch.dispatch({ encoder, bindings: {
+                    batch: encoder.allocateTransientValueBuffer(WATER_WAVE_BATCH_STRUCT,
+                        { resolution: n, capacity, dt: step_dt, time: step_time, damping, apply_impulses }),
+                    scene_database: scene.scene_database_buffer, domain, state_current: state[parity], state_previous: state[1 - parity],
+                }, group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+            };
+            // Clear both histories of new/reused slots before advancing, then release the reset flag.
+            dispatch(0, 0, time, 0); dispatch(1, 0, time, 0);
+            const finish = apply_impulses => {
+                const groups = table.dispatch_group_count(64);
+                shader_water_wave_batch_finish.dispatch({ encoder, bindings: { scene_database: scene.scene_database_buffer,
+                    batch: encoder.allocateTransientValueBuffer(WATER_WAVE_BATCH_STRUCT,
+                        { resolution: n, capacity, dt, time, damping, apply_impulses }) },
+                    group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+            };
+            finish(0);
+            for (let i = 0; i < steps; i++) { dispatch((start + i) % 2, dt, time + i * dt, i === 0 ? 1 : 0); }
+            if (steps > 0) {
+                finish(1);
+                // Submit is the ownership boundary for staged CPU inputs. Use the encoder's
+                // existing synchronous signal so a later scene/update cannot be cleared by
+                // an old promise callback.
+                encoder.onFinished.addOne(() => this.onInputsConsumed.dispatch(scene));
+            }
+            shader_water_wave_bounds.dispatch({ encoder, bindings: {
+                batch: encoder.allocateTransientValueBuffer(WATER_WAVE_BATCH_STRUCT, { resolution: n, capacity }),
+                scene_database: scene.scene_database_buffer, state: state[(start + steps) % 2],
+            }, group_count_x: Math.min(capacity, 65535), group_count_y: Math.ceil(capacity / 65535) });
+        });
+        pass.make_side_effect();
+    }
+}

package/src/shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.d.ts

@@ -0,0 +1,6 @@
+/** Most impulses one body applies in one step. */
+export const WATER_WAVE_IMPULSE_LIMIT: 16;
+/** Persistent inputs; the shared dispatch owns timestep and grid resolution. */
+export const WATER_WAVE_RECORD_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_WAVE_RECORD_STRUCT.d.ts.map