@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/renderer/water/shader_water_avboit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_water_avboit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water_avboit.js"],"names":[],"mappings":";AAiCA,mDAwBG;AAQH,+CAqCG;AAUH,4CAwBG;AAQH,uDAuBG;AAyBH,oDAA2E;AAC3E,oDAA0E;AAM1E,uDAYG;AAOH,6CAuCG;8BAlP2B,4BAA4B;4BAC9B,0BAA0B"}
+{"version":3,"file":"shader_water_avboit.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/water/shader_water_avboit.js"],"names":[],"mappings":";AAqCA,mDAwBG;AAQH,+CAqCG;AAUH,4CA4BG;AAQH,uDAuBG;AAyBH,oDAA2E;AAC3E,oDAA0E;AAM1E,uDAYG;AAOH,6CAyCG;8BAxP2B,4BAA4B;4BAC9B,0BAA0B"}

package/src/shade/renderer/water/shader_water_avboit.js

@@ -3,6 +3,7 @@ import { chunk_sample_volumetrics } from "../deferred/chunk_sample_volumetrics.j
 import { AVBOIT_OCCUPANCY_WORDS, AVBOIT_VOXEL_DOWNSCALE } from "../rasterize/native/avboit/AVBOIT_CONSTANTS.js";
 import { AVBOIT_WARP_STRUCT } from "../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
 import { AVBOIT_DRAW_TARGETS } from "../rasterize/native/avboit/avboit_draw_fragment_body.js";
+import { chunk_avboit_footprint_bias } from "../rasterize/native/avboit/chunk_avboit_footprint_bias.js";
 import { chunk_avboit_occupancy_mark } from "../rasterize/native/avboit/chunk_avboit_occupancy_mark.js";
 import { chunk_avboit_rgb_contribution } from "../rasterize/native/avboit/chunk_avboit_rgb_contribution.js";
 import { chunk_avboit_sample_transmittance } from "../rasterize/native/avboit/chunk_avboit_sample_transmittance.js";
@@ -10,8 +11,11 @@ import { chunk_avboit_splat_slice } from "../rasterize/native/avboit/chunk_avboi
 import { chunk_avboit_split_counts } from "../rasterize/native/avboit/chunk_avboit_split_counts.js";
 import { chunk_avboit_transmittance_to_extinction } from "../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
 import { chunk_avboit_view_depth_to_physical } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
+import { chunk_avboit_view_depth_to_virtual } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_virtual.js";
 import { AVBOIT_OCCUPANCY_SETTINGS_STRUCT } from "../rasterize/native/avboit/shader_avboit_occupancy.js";
 import { chunk_get_view_space_depth } from "../shader/chunk/depth/chunk_get_view_space_depth.js";
+import { chunk_is_background } from "../shader/chunk/depth/chunk_is_background.js";
+import { chunk_is_on_screen_i32 } from "../shader/chunk/texture/chunk_is_on_screen_i32.js";
 import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 import { ComputeShader } from "../shader/ComputeShader.js";
 import { ImageShader } from "../shader/ImageShader.js";
@@ -121,18 +125,22 @@ struct WaterContribution {
 fn main(@builtin(position) coord: vec4f) -> WaterContribution {
     let pixel = vec2u(coord.xy);
     let d = textureLoad(interface_depth, pixel, 0).r;
-    if (d <= 0.0) { discard; }
     let z = get_view_space_depth(d, camera);
+    // the water splats into the volume too, and a plane seen at an angle runs through depth across a
+    // voxel (avboit_footprint_bias). Taken before the discard, in uniform control flow; a dry pixel's
+    // virtual coordinate clamps, so the derivative at the shore stays finite and the cap holds it
+    let footprint = avboit_footprint_bias(&warp, fwidth(avboit_view_depth_to_virtual(&warp, z)));
+    if (d <= 0.0) { discard; }
     let uv = coord.xy / vec2f(textureDimensions(interface_depth, 0));
-    let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z);
+    let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z, footprint);
     let t = textureLoad(transmission, pixel, 0).rgb;
     let w = textureLoad(radiance, pixel, 0).rgb;
     let fog = sample_volumetrics(z, uv, coord.xy);
     let c = avboit_rgb_contribution(w, t, front, fog);
     return WaterContribution(c.color, c.norm, c.extinction, c.emission);
 }
-`, [chunk_get_view_space_depth, chunk_avboit_sample_transmittance,
-            chunk_avboit_rgb_contribution, chunk_sample_volumetrics]),
+`, [chunk_get_view_space_depth, chunk_avboit_view_depth_to_virtual, chunk_avboit_footprint_bias,
+            chunk_avboit_sample_transmittance, chunk_avboit_rgb_contribution, chunk_sample_volumetrics]),
     }), targets: AVBOIT_DRAW_TARGETS,
 });
 
@@ -157,13 +165,13 @@ fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
                 let t = textureLoad(trace_metadata, pixel, 0);
                 // Only actual geometry/sky boundaries seed the spatial fade. Trace budget
                 // or numerical failures must not create moving 64-pixel holes around themselves.
-                if (t.b <= 0.0 || textureLoad(scene_depth, pixel, 0).r == 0.0) { distance = 0.0; }
+                if (t.b <= 0.0 || is_background(textureLoad(scene_depth, pixel, 0).r)) { distance = 0.0; }
             }
         }
     }
     return vec4f(distance, 0.0, 0.0, 1.0);
 }
-`),
+`, [chunk_is_background]),
     }), targets: [{ format: "r16float" }],
 });
 
@@ -180,14 +188,14 @@ fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
     var distance = 16.0;
     for (var offset = -16; offset <= 16; offset++) {
         let sample = pixel + ${vertical ? "vec2i(0, offset)" : "vec2i(offset, 0)"};
-        if (all(sample >= vec2i(0)) && all(sample < size)) {
+        if (is_on_screen_i32(sample, size)) {
             let d = textureLoad(distance_field, sample, 0).r;
             distance = min(distance, ${vertical ? "length(vec2f(d, f32(offset)))" : "d + abs(f32(offset))"});
         }
     }
     return vec4f(distance, 0.0, 0.0, 1.0);
 }
-`),
+`, [chunk_is_on_screen_i32]),
     }), targets: [{ format: "r16float" }] });
 }
 export const shader_water_confidence_x = confidence_distance_shader(false);
@@ -246,7 +254,9 @@ fn main(@builtin(position) coord: vec4f) -> @location(0) vec4f {
         }
         case 8u, 9u: {
             let z = get_view_space_depth(textureLoad(interface_depth, pixel, 0).r, camera);
-            let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z);
+            // without the draw's footprint (a derivative this switch cannot take): where the water is
+            // seen at an angle this also shows it occluding itself, which the draw looks past
+            let front = avboit_sample_transmittance(&warp, tIntegral, sLinear, uv, z, 0.0);
             color = select(front, (1.0 - t.rgb) * front, inspection.mode == 9u);
         }
         default: {}

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

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+export class GPUWaterWaveSimulation {
+    /**
+     * Vertices along each side of a body's grid. Changing it rebuilds every body.
+     * @type {number}
+     */
+    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.
+     */
+    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[];
+    }): 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;
+};
+//# sourceMappingURL=GPUWaterWaveSimulation.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,408 @@
+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;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * One vertex of a water surface: what every surface producer writes and the water draws read.
+ *
+ * This and a producer-owned index buffer are the whole surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2). A producer that is not a height field writes the same
+ * record, so the draws never learn which producer ran.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_SURFACE_VERTEX_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_SURFACE_VERTEX_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_SURFACE_VERTEX_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_SURFACE_VERTEX_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,0CAFU,YAAY,CAgBG;6BAzBI,mCAAmC"}

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

@@ -0,0 +1,27 @@
+import { vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+
+/**
+ * One vertex of a water surface: what every surface producer writes and the water draws read.
+ *
+ * This and a producer-owned index buffer are the whole surface interface
+ * (WATER_OPTICS_PLAN_2026_10_02.md §7.2). A producer that is not a height field writes the same
+ * record, so the draws never learn which producer ran.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_SURFACE_VERTEX_STRUCT = WebGPUStruct.from({
+    /**
+     * World position in `xyz`. `w` is the slope variance of the waves this mesh does not resolve,
+     * which the shading adds to its roughness.
+     */
+    position: vec4f,
+    /**
+     * Last frame's world position in `xyz`, for motion vectors. `w` is unused.
+     */
+    previous: vec4f,
+    /**
+     * Unit world normal in `xyz`. `w` is unused.
+     */
+    normal: vec4f,
+}, "WaterSurfaceVertex");

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

@@ -0,0 +1,14 @@
+/**
+ * Most impulses one body applies in one step.
+ * @type {number}
+ */
+export const WATER_WAVE_IMPULSE_LIMIT: number;
+/**
+ * Per-body, per-step inputs of the primitive wave producer: its grid, the terrain it floods, the
+ * step and the forcing.
+ *
+ * @type {WebGPUStruct}
+ */
+export const WATER_WAVE_PARAMETERS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=WATER_WAVE_PARAMETERS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WATER_WAVE_PARAMETERS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_WAVE_PARAMETERS_STRUCT.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,uCAFU,MAAM,CAE2B;AAE3C;;;;;GAKG;AACH,2CAFU,YAAY,CAkCI;6BA9CG,mCAAmC"}