@woosh/meep-engine 3.40.0 → 3.42.0

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

@@ -0,0 +1,199 @@
+import Signal from "../../../../core/events/signal/Signal.js";
+import { assert } from "../../../../core/assert.js";
+import { SamplerDescriptor } from "../../../descriptor/texture/SamplerDescriptor.js";
+import { GPUWaterSpectrum } from "./spectrum/GPUWaterSpectrum.js";
+import { GPUWaterParticles } from "./particles/GPUWaterParticles.js";
+import { shader_water_waves_combine } from "./shader_water_waves_combine.js";
+import {
+    shader_water_cull,
+    shader_water_cull_finalize,
+    WATER_CULL_STRUCT,
+    WATER_CULL_WORKGROUP_SIZE,
+    WATER_LIST_HEADER_BYTES,
+    WATER_SURFACE_COMMAND_COUNT,
+    WATER_SURFACE_COMMAND_STRIDE,
+    WaterSurfaceCommand
+} from "./shader_water_cull.js";
+import { water_lod_view, WATER_LOD_VIEW_STRUCT } from "./lod/WATER_LOD.js";
+import { WATER_SPECTRUM_LOOP_SECONDS } from "./spectrum/WATER_SPECTRUM.js";
+
+/** Times of its loop the bands are evaluated at once, on a device's first frame with wind, to seed their envelopes. */
+export const WATER_ENVELOPE_SEED_TIMES = 32;
+
+/** How the surface sampler reads the band tiles: filtered, and periodic. */
+export const WATER_BAND_SAMPLER = Object.freeze(SamplerDescriptor.from({
+    magFilter: "linear",
+    minFilter: "linear",
+    addressModeU: "repeat",
+    addressModeV: "repeat",
+}));
+
+/**
+ * The water surface producer (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §3), scheduled by what the frame's view
+ * sees (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3): a culling pass over every body, then the shared
+ * spectral bands the visible bodies can draw, the wave particles of the bodies simulated this frame, and their
+ * bounds. Recorded once a frame at the head of the frame. What the surface passes bind of it is the surface
+ * interface: the band textures, the particle hash, and the rows.
+ */
+export class GPUWaterSurface {
+    /** Dispatched with the scene when a frame that emitted the queued splashes is submitted. */
+    onInputsConsumed = new Signal();
+    /** Most wave particles alive at once over every body of a scene. */
+    particle_capacity = 65536;
+    /** Whether any body has wind; without it the band tiles are not animated. */
+    windy = false;
+    /**
+     * Whether any splash was ever queued. Until one is, the pool is empty and no particle pass is recorded; set by
+     * whoever queues splashes.
+     */
+    splashed = false;
+    #spectrum = new GPUWaterSpectrum();
+    #particles = new GPUWaterParticles();
+    #device = null;
+    #scene = null;
+    #rows = 0;
+    #steep = null;
+    #activity = null;
+    #lists = null;
+    #commands = null;
+    #pending = 0;
+    #spectrum_time = NaN;
+    #seeded = false;
+    #recorded = new WeakSet();
+
+    get displacement() { return this.#spectrum.displacement; }
+    get derivatives() { return this.#spectrum.derivatives; }
+    get particle_offsets() { return this.#particles.offsets; }
+    get particle_entries() { return this.#particles.entries; }
+    /** @returns {GPUBuffer} per wave row, set by the tessellation when a body has a triangle too steep to displace */
+    get steep() { return this.#steep; }
+    /** @returns {GPUBuffer} per wave row, the culling pass's {@link WaterActivity} bits for the frame */
+    get activity() { return this.#activity; }
+    /** @returns {GPUBuffer} the water_bodies rows the frame's culling pass found visible: a count, then the rows */
+    get visible_rows() { return this.#lists?.visible ?? null; }
+    get particles() { return this.#particles; }
+
+    /**
+     * Seconds of water time to step at the next recorded frame.
+     * @param {number} dt
+     */
+    advance(dt) {
+        assert.isFinite(dt, 'dt'); assert.greaterThanOrEqual(dt, 0, 'dt');
+        this.#pending += dt;
+    }
+
+    dispose() {
+        this.#spectrum.dispose();
+        this.#particles.dispose();
+        for (const buffer of [this.#steep, this.#activity, this.#commands, ...Object.values(this.#lists ?? {})]) { buffer?.destroy(); }
+        this.#steep = this.#activity = this.#commands = this.#lists = null;
+        this.#rows = 0;
+        this.#device = null;
+        this.#scene = null;
+        this.#spectrum_time = NaN;
+        this.#seeded = false;
+        this.#recorded = new WeakSet();
+    }
+
+    /** Per wave row buffers for this many rows, carrying the steep flags of the rows that were. */
+    #allocate(device, rows) {
+        if (this.#steep !== null && rows <= this.#rows) { return null; }
+        const previous = this.#steep, previous_rows = this.#rows;
+        for (const buffer of [this.#activity, ...Object.values(this.#lists ?? {})]) { buffer?.destroy(); }
+        const buffer = (label, size, usage = 0) => device.createBuffer({ label: `Water / ${label}`, size,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | usage });
+        this.#steep = buffer('steep bodies', rows * 4);
+        this.#activity = buffer('activity', rows * 4);
+        const list = label => buffer(label, WATER_LIST_HEADER_BYTES + rows * 4);
+        this.#lists = { visible: list('visible rows'), active: list('active rows'), emit: list('emit rows') };
+        this.#commands ??= buffer('surface commands', WATER_SURFACE_COMMAND_COUNT * WATER_SURFACE_COMMAND_STRIDE, GPUBufferUsage.INDIRECT);
+        this.#rows = rows;
+        if (previous === null) { return null; }
+        return encoder => {
+            encoder.copyBufferToBuffer(previous, 0, this.#steep, 0, previous_rows * 4);
+            encoder.done.then(() => previous.destroy());
+        };
+    }
+
+    /**
+     * @param {object} options
+     * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+     * @param {GPUDevice} options.device
+     * @param {object} options.scene GPU scene context
+     * @param {number} options.time water time, seconds
+     * @param {object} options.view the view the frame is recorded for
+     * @param {GPUBuffer} options.view.camera its camera uniforms
+     * @param {ArrayLike<number>} options.view.projection its projection, column-major
+     * @param {number} options.view.height its render target's height, pixels
+     * @param {number} options.pixels the smallest a lattice cell is drawn on screen
+     */
+    record({ graph, device, scene, time, view, pixels }) {
+        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);
+        const bodies = scene.scene_database.get('water_bodies');
+        const waves = scene.scene_database.get('water_waves');
+        const rows = Math.max(waves.element_capacity, 1);
+        this.#spectrum.prepare(device);
+        const carry_steep = this.#allocate(device, rows);
+        const carry_bounds = this.#particles.prepare(device, this.particle_capacity, rows);
+        const dt = this.#pending;
+        this.#pending = 0;
+        const stepping = dt > 0;
+        const binning = this.splashed;
+        const fresh = time !== this.#spectrum_time;
+        this.#spectrum_time = time;
+        const seed = this.windy && !this.#seeded;
+        if (seed) { this.#seeded = true; }
+        const windy = this.windy;
+        const lod = water_lod_view(view.projection, view.height, pixels);
+        const groups = bodies.dispatch_group_count(WATER_CULL_WORKGROUP_SIZE);
+        const lists = this.#lists, commands = this.#commands, steep = this.#steep, activity = this.#activity;
+        const band_state = this.#spectrum.band_state, band_requests = this.#spectrum.band_requests;
+        const particle_bounds = this.#particles.body_bounds;
+        const command = index => index * WATER_SURFACE_COMMAND_STRIDE;
+        const finalize = (encoder, frame) => shader_water_cull_finalize.dispatch({ encoder, bindings: { frame,
+            band_state, band_requests, active_rows: lists.active, emit_rows: lists.emit, commands } });
+        const spectrum = encoder => this.#spectrum.encode(encoder, time, commands,
+            command(WaterSurfaceCommand.SpectrumRows), command(WaterSurfaceCommand.SpectrumColumns));
+        const head = graph.add('Water / cull', {}, (_d, _r, { encoder }) => {
+            carry_steep?.(encoder);
+            carry_bounds?.(encoder);
+            for (const list of Object.values(lists)) { encoder.clearBuffer(list, 0, WATER_LIST_HEADER_BYTES); }
+            if (seed) {
+                // every band at times spread over its loop, so the culling pass has envelopes to bound hidden bodies'
+                // waves by: one time's extrema fall short of the loop's by up to half (measured over 2,000 times)
+                finalize(encoder, { fresh: 1, seed: 1 });
+                for (let i = 0; i < WATER_ENVELOPE_SEED_TIMES; i++) {
+                    this.#spectrum.encode(encoder, (i + 0.5) / WATER_ENVELOPE_SEED_TIMES * WATER_SPECTRUM_LOOP_SECONDS, commands,
+                        command(WaterSurfaceCommand.SpectrumRows), command(WaterSurfaceCommand.SpectrumColumns));
+                }
+            }
+            if (groups > 0) {
+                shader_water_cull.dispatch({ encoder, bindings: {
+                    cull: encoder.allocateTransientValueBuffer(WATER_CULL_STRUCT, { dt, stepping: stepping ? 1 : 0, binning: binning ? 1 : 0 }),
+                    lod: encoder.allocateTransientValueBuffer(WATER_LOD_VIEW_STRUCT, lod), camera: view.camera, scene_database: scene.scene_database_buffer, geometries: scene.geometries.buffer_metadata,
+                    band_state, band_requests, particle_bounds, steep, activity, visible_rows: lists.visible, active_rows: lists.active,
+                    emit_rows: lists.emit }, group_count_x: Math.min(groups, 65535), group_count_y: Math.ceil(groups / 65535) });
+            }
+            finalize(encoder, { fresh: fresh && !seed ? 1 : 0, seed: 0 });
+            if (windy) { spectrum(encoder); }
+        });
+        head.make_side_effect();
+        if (binning) {
+            this.#particles.record({ graph, scene, steep, activity, emit_rows: lists.emit, commands,
+                emit_command: command(WaterSurfaceCommand.Emit), dt: stepping ? dt : 0 });
+        }
+        const tail = graph.add('Water / surface bounds', {}, (_d, _r, { encoder }) => {
+            shader_water_waves_combine.dispatchIndirect({ encoder, command: commands, command_offset: command(WaterSurfaceCommand.Active),
+                bindings: { scene_database: scene.scene_database_buffer, active_rows: lists.active, band_state, particle_bounds, steep } });
+            if (stepping && binning) {
+                // Submit is the ownership boundary for staged CPU inputs.
+                encoder.onFinished.addOne(() => this.onInputsConsumed.dispatch(scene));
+            }
+        });
+        tail.make_side_effect();
+    }
+}

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

@@ -1,6 +1,9 @@
-/** Most impulses one body applies in one step. */
+/** Most impulses one body applies in one frame. */
 export const WATER_WAVE_IMPULSE_LIMIT: 16;
-/** Persistent inputs; the shared dispatch owns timestep and grid resolution. */
+/**
+ * The surface state of one water body, one row per body (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
+ * The CPU writes what is authored and queued; the GPU writes what it derives each frame.
+ */
 export const WATER_WAVE_RECORD_STRUCT: WebGPUStruct;
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 //# sourceMappingURL=WATER_WAVE_RECORD_STRUCT.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"WATER_WAVE_RECORD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js"],"names":[],"mappings":"AAIA,kDAAkD;AAClD,0CAA2C;AAE3C,gFAAgF;AAChF,oDAcsB;6BApBO,mCAAmC"}
+{"version":3,"file":"WATER_WAVE_RECORD_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js"],"names":[],"mappings":"AAKA,mDAAmD;AACnD,0CAA2C;AAE3C;;;GAGG;AACH,oDA8BsB;6BAxCO,mCAAmC"}

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

@@ -1,23 +1,43 @@
 import { f32, u32, vec2f, vec4f } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { WATER_SPECTRUM_BAND_COUNT } from "./spectrum/WATER_SPECTRUM.js";
 
-/** Most impulses one body applies in one step. */
+/** Most impulses one body applies in one frame. */
 export const WATER_WAVE_IMPULSE_LIMIT = 16;
 
-/** Persistent inputs; the shared dispatch owns timestep and grid resolution. */
+/**
+ * The surface state of one water body, one row per body (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1).
+ * The CPU writes what is authored and queued; the GPU writes what it derives each frame.
+ */
 export const WATER_WAVE_RECORD_STRUCT = WebGPUStruct.from({
-    /** Local xz bounds; these describe the displacement field, not the water outline. */
-    extent: vec4f,
-    /** Local wind direction, world acceleration and drift speed. */
-    forcing: vec4f,
-    /** Local xz centre, world radius and velocity kick. */
+    /**
+     * Wind direction in the body's metric local xz (cos, sin), wind speed at 10 m in m/s, and the amplitude
+     * reflection coefficient of the mesh's outline.
+     */
+    wind: vec4f,
+    /** Open water upwind of the mesh, metres, added to the mesh's own extent along the wind. */
+    upwind_fetch: f32,
+    /** Queued splashes: local xz centre, world radius, velocity kick (m/s). */
     impulses: WebGPUArray.from(vec4f, WATER_WAVE_IMPULSE_LIMIT),
-    node: u32,
-    unresolved_variance: f32,
     impulse_count: u32,
-    first_write: u32,
+    node: u32,
     geometry: u32,
-    /** GPU-owned signed local-y displacement bounds, reduced after simulation. */
-    displacement_bounds: vec2f,
+    /** Non-zero to step the body while no view sees it (`Water.simulateWhenHidden`). */
+    simulate_hidden: u32,
+    /** GPU: the wind speed and fetch the weights were derived for; the culling pass re-derives when they change. */
+    derived_for: vec2f,
+    /** GPU: amplitude weight of each spectral band, from the wind and the fetch. */
+    weights: WebGPUArray.from(f32, WATER_SPECTRUM_BAND_COUNT),
+    /** GPU: slope variance of all of the body's ambient waves. */
+    slope_variance: f32,
+    /** GPU: the wind direction a turn started from and the one it is going to, metric local xz. */
+    wind_from: vec2f,
+    wind_to: vec2f,
+    /** GPU: progress of the turn from wind_from to wind_to, 0 … 1. */
+    wind_blend: f32,
+    /** GPU: signed local-y displacement bounds and the horizontal bound, local units, as the body's last simulated frame left them. */
+    displacement_bounds: vec4f,
+    /** GPU: bit l set when the body has wave particles at hash level l this frame. */
+    particle_levels: u32,
 }, "WaterWaveRecord");

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

@@ -0,0 +1,22 @@
+/**
+ * Most particle entries one point reads, over every level. The bin pass thins a crowded cell to about
+ * WATER_PARTICLE_CELL_SHARE packets, the same ones in every cell they reach, so a point reads all of its cells
+ * unless several levels are crowded there at once.
+ */
+export const WATER_PARTICLE_GATHER_BUDGET: 64;
+/**
+ * The surface interface (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §3): the displaced water surface at one
+ * rest point of one body, from the shared spectral bands and the body's wave particles, filtered by the
+ * point's footprint.
+ *
+ * A pure function of its arguments and the frame's resources. Callers pass the rest point and a footprint
+ * computed from the rest point alone, so two cells sharing a vertex displace it identically.
+ *
+ * Bindings it reads: `scene_database`, `water_band_displacement`, `water_band_derivatives`,
+ * `water_band_sampler` (linear, repeat), `water_particle_offsets`, `water_particle_entries`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_surface_sample: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_water_surface_sample.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_water_surface_sample.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/chunk_water_surface_sample.js"],"names":[],"mappings":"AAMA;;;;GAIG;AACH,8CAA+C;AAE/C;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAgMyC;0BAxNlC,oCAAoC"}

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

@@ -0,0 +1,217 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { chunk_pcg3d } from "../../shader/chunk/random/pcg/chunk_pcg3d.js";
+import { WATER_WAVES_TABLE } from "../medium/chunk_water_bodies.js";
+import { chunk_water_spectrum } from "./spectrum/chunk_water_spectrum.js";
+import { chunk_water_particle } from "./particles/chunk_water_particle.js";
+
+/**
+ * Most particle entries one point reads, over every level. The bin pass thins a crowded cell to about
+ * WATER_PARTICLE_CELL_SHARE packets, the same ones in every cell they reach, so a point reads all of its cells
+ * unless several levels are crowded there at once.
+ */
+export const WATER_PARTICLE_GATHER_BUDGET = 64;
+
+/**
+ * The surface interface (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §3): the displaced water surface at one
+ * rest point of one body, from the shared spectral bands and the body's wave particles, filtered by the
+ * point's footprint.
+ *
+ * A pure function of its arguments and the frame's resources. Callers pass the rest point and a footprint
+ * computed from the rest point alone, so two cells sharing a vertex displace it identically.
+ *
+ * Bindings it reads: `scene_database`, `water_band_displacement`, `water_band_derivatives`,
+ * `water_band_sampler` (linear, repeat), `water_particle_offsets`, `water_particle_entries`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_water_surface_sample = CodeChunk.from(/* language=WGSL */ `
+const WATER_PARTICLE_GATHER_BUDGET: u32 = ${WATER_PARTICLE_GATHER_BUDGET}u;
+const WATER_LN2: f32 = 0.69314718;
+
+struct WaterSurfaceSample {
+    // metric local frame: (Dx, h, Dz)
+    offset: vec3<f32>,
+    // unit normal of the displaced surface, metric local frame
+    normal: vec3<f32>,
+    // slope variance of the waves too short for the footprint
+    unresolved_variance: f32,
+}
+
+// Everything at a point before the horizontal displacement is limited: metric local frame.
+struct WaterSurfaceSum {
+    height: f32,
+    slope: vec2<f32>,
+    displacement: vec2<f32>,
+    jacobian: mat2x2<f32>,
+    // slope variance of the bands and packets too short for the footprint
+    variance: f32,
+    // ... of which the packets'
+    particle_variance: f32,
+}
+
+// What geometry at this footprint carries of a band: all of it while its shortest waves (half the node wavelength)
+// span eight samples, fading over the octave below.
+fn water_band_vertex_fraction(band: u32, footprint: f32) -> f32 {
+    return clamp(log2(water_band_wavelength(band) / (8.0 * footprint)), 0.0, 1.0);
+}
+
+// What a pixel of this footprint shades of a band: all of it while its shortest waves span four pixels, none once they
+// span two.
+fn water_band_pixel_fraction(band: u32, footprint: f32) -> f32 {
+    return clamp(log2(water_band_wavelength(band) / (4.0 * footprint)), 0.0, 1.0);
+}
+
+// Where in its tile a body's band starts, for one orientation of its waves: per body, so two bodies with one
+// wind do not show the same waves, and per orientation, so the two a turn of the wind blends are independent
+// however small the turn. An orientation is the exact bits of its direction, which the turn hands on unchanged.
+fn water_band_offset(wave: u32, band: u32, wind: vec2<f32>) -> vec2<f32> {
+    let bits = pcg3d(vec3<u32>(wave, band, pcg3d(vec3<u32>(bitcast<u32>(wind.x), bitcast<u32>(wind.y), 0x5eau)).x));
+    return vec2<f32>(f32(bits.x >> 8u), f32(bits.y >> 8u)) * (1.0 / 16777216.0);
+}
+
+// Band j's waves at p, turned so the tile's own wind angle points along wind, scaled by weight.
+fn water_band_add(sum: ptr<function, WaterSurfaceSum>, wave: u32, band: u32, p: vec2<f32>, wind: vec2<f32>, weight: f32) {
+    let angle = water_band_wind_angle(band);
+    let band_wind = vec2<f32>(cos(angle), sin(angle));
+    // body frame → tile frame turns by (band angle − wind angle); back by its inverse
+    let c = dot(band_wind, wind);
+    let s = band_wind.y * wind.x - band_wind.x * wind.y;
+    let to_tile = mat2x2<f32>(c, s, -s, c);
+    let to_body = mat2x2<f32>(c, -s, s, c);
+    let uv = (to_tile * p) / water_band_period(band) + water_band_offset(wave, band, wind);
+    let a = textureSampleLevel(water_band_displacement, water_band_sampler, uv, band, 0.0);
+    let b = textureSampleLevel(water_band_derivatives, water_band_sampler, uv, band, 0.0);
+    (*sum).height += weight * a.y;
+    (*sum).displacement += weight * (to_body * a.xz);
+    // a gradient turns as a vector does; the Jacobian as R J Rᵀ
+    (*sum).slope += weight * (to_body * b.xy);
+    (*sum).jacobian += weight * (to_body * mat2x2<f32>(b.z, a.w, a.w, b.w) * to_tile);
+}
+
+// The bands and particles at metric local point p of wave row wave, filtered to footprint metres between samples.
+fn water_surface_sum(wave: u32, p: vec2<f32>, footprint: f32) -> WaterSurfaceSum {
+    let weights = ${WATER_WAVES_TABLE.marshalling_method_read_field('weights')}(&scene_database, wave);
+    let wind_from = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_from')}(&scene_database, wave);
+    let wind_to = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_to')}(&scene_database, wave);
+    let blend = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_blend')}(&scene_database, wave);
+    let levels = ${WATER_WAVES_TABLE.marshalling_method_read_field('particle_levels')}(&scene_database, wave);
+    var sum: WaterSurfaceSum;
+    var variance = 0.0;
+    // during a turn of the wind both orientations show, independent, with weights whose squares sum to one
+    let turning = blend < 1.0;
+    let weight_to = select(1.0, sin(1.57079633 * blend), turning);
+    let weight_from = select(0.0, cos(1.57079633 * blend), turning);
+    for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+        let w = weights[band];
+        if (!(w > 0.0)) { continue; }
+        // what geometry does not carry is slope variance
+        let f = water_band_vertex_fraction(band, footprint);
+        variance += w * w * WATER_LN2 * (1.0 - f * f);
+        if (f <= 0.0) { continue; }
+        water_band_add(&sum, wave, band, p, wind_to, w * f * weight_to);
+        if (weight_from > 0.0) { water_band_add(&sum, wave, band, p, wind_from, w * f * weight_from); }
+    }
+    let table = water_particle_offsets.count;
+    var visited = 0u;
+    var particle_variance = 0.0;
+    // coarsest first: the budget goes to packets the footprint can draw before those it can only roughen
+    for (var from_top = 0u; from_top < WATER_PARTICLE_LEVELS && table != 0u; from_top++) {
+        let level = WATER_PARTICLE_LEVELS - 1u - from_top;
+        if ((levels & (1u << level)) == 0u) { continue; }
+        let size = water_particle_cell_size(level);
+        let cell = vec2<i32>(floor(p / size));
+        let key = (wave << 4u) | level;
+        let bucket = water_particle_bucket(wave, level, cell, table);
+        var start = 0u;
+        if (bucket > 0u) { start = water_particle_offsets.elements[bucket - 1u]; }
+        let end = water_particle_offsets.elements[bucket];
+        for (var i = start; i < end && visited < WATER_PARTICLE_GATHER_BUDGET; i++) {
+            visited++;
+            let entry = water_particle_entries[i];
+            if (entry.key != key || any(entry.cell != cell)) { continue; }
+            let field = water_particle_field(p - entry.position, entry.angle, entry.amplitude, entry.radius, entry.width, entry.phase);
+            // a packet is geometry while its wavelength spans eight samples, fading out by four
+            let f = clamp(log2(entry.radius / (2.0 * footprint)), 0.0, 1.0);
+            particle_variance += (1.0 - f * f) * dot(field.slope, field.slope);
+            sum.height += f * field.height;
+            sum.slope += f * field.slope;
+            sum.displacement += f * field.displacement;
+            sum.jacobian += f * field.jacobian;
+        }
+    }
+    sum.variance = variance + particle_variance;
+    sum.particle_variance = particle_variance;
+    return sum;
+}
+
+// Band j's slope at p, turned as water_band_add turns it: the derivatives tile alone.
+fn water_band_slope(wave: u32, band: u32, p: vec2<f32>, wind: vec2<f32>) -> vec2<f32> {
+    let angle = water_band_wind_angle(band);
+    let band_wind = vec2<f32>(cos(angle), sin(angle));
+    let c = dot(band_wind, wind);
+    let s = band_wind.y * wind.x - band_wind.x * wind.y;
+    let to_tile = mat2x2<f32>(c, s, -s, c);
+    let to_body = mat2x2<f32>(c, -s, s, c);
+    let uv = (to_tile * p) / water_band_period(band) + water_band_offset(wave, band, wind);
+    return to_body * textureSampleLevel(water_band_derivatives, water_band_sampler, uv, band, 0.0).xy;
+}
+
+// What a pixel sees of the bands at rest point p that its vertices, footprint apart, could not carry: their slope,
+// metric local frame, to tilt the vertices' normal by; and the slope variance of the bands neither resolves.
+struct WaterSurfaceDetail {
+    slope: vec2<f32>,
+    variance: f32,
+}
+
+fn water_surface_detail(wave: u32, p: vec2<f32>, vertex_footprint: f32, pixel_footprint: f32) -> WaterSurfaceDetail {
+    let weights = ${WATER_WAVES_TABLE.marshalling_method_read_field('weights')}(&scene_database, wave);
+    let wind_from = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_from')}(&scene_database, wave);
+    let wind_to = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_to')}(&scene_database, wave);
+    let blend = ${WATER_WAVES_TABLE.marshalling_method_read_field('wind_blend')}(&scene_database, wave);
+    let turning = blend < 1.0;
+    let weight_to = select(1.0, sin(1.57079633 * blend), turning);
+    let weight_from = select(0.0, cos(1.57079633 * blend), turning);
+    var detail: WaterSurfaceDetail;
+    for (var band = 0u; band < WATER_SPECTRUM_BANDS; band++) {
+        let w = weights[band];
+        if (!(w > 0.0)) { continue; }
+        let carried = water_band_vertex_fraction(band, vertex_footprint);
+        let shaded = max(water_band_pixel_fraction(band, pixel_footprint), carried);
+        detail.variance += w * w * WATER_LN2 * (1.0 - shaded * shaded);
+        let extra = shaded - carried;
+        if (!(extra > 0.0)) { continue; }
+        detail.slope += w * extra * weight_to * water_band_slope(wave, band, p, wind_to);
+        if (weight_from > 0.0) { detail.slope += w * extra * weight_from * water_band_slope(wave, band, p, wind_from); }
+    }
+    return detail;
+}
+
+// The surface from its sum, with the horizontal displacement scaled by at most horizontal (a caller's
+// near-plane allowance), and folded back where it would turn the surface inside out: the largest scale
+// λ ≤ horizontal for which det(I + λJ) stays at least 0.2.
+fn water_surface_finish(sum: WaterSurfaceSum, horizontal: f32) -> WaterSurfaceSample {
+    let trace = sum.jacobian[0][0] + sum.jacobian[1][1];
+    let det = determinant(sum.jacobian);
+    var lambda = clamp(horizontal, 0.0, 1.0);
+    if (1.0 + lambda * trace + lambda * lambda * det < 0.2) {
+        // the first root of det λ² + trace λ + 0.8 = 0 in (0, λ): the polynomial is 1 > 0.2 at 0
+        // the cancellation-free pair of roots: q / det and 0.8 / q, either of which may be the one
+        let q = -0.5 * (trace + select(-1.0, 1.0, trace >= 0.0) * sqrt(max(trace * trace - 3.2 * det, 0.0)));
+        let r1 = select(-1.0, q / det, abs(det) > 1e-20);
+        let r2 = select(-1.0, 0.8 / q, abs(q) > 1e-20);
+        lambda = min(select(lambda, r1, r1 > 0.0 && r1 < lambda), select(lambda, r2, r2 > 0.0 && r2 < lambda));
+    }
+    let j = lambda * sum.jacobian;
+    let tangent_x = vec3<f32>(1.0 + j[0][0], sum.slope.x, j[0][1]);
+    let tangent_z = vec3<f32>(j[1][0], sum.slope.y, 1.0 + j[1][1]);
+    return WaterSurfaceSample(vec3<f32>(lambda * sum.displacement.x, sum.height, lambda * sum.displacement.y),
+        normalize(cross(tangent_z, tangent_x)), sum.variance);
+}
+
+fn water_surface_sample(wave: u32, p: vec2<f32>, footprint: f32, horizontal: f32) -> WaterSurfaceSample {
+    return water_surface_finish(water_surface_sum(wave, p, footprint), horizontal);
+}
+`, [chunk_water_spectrum, chunk_water_particle, chunk_pcg3d,
+    WATER_WAVES_TABLE.chunk_read_field('weights'), WATER_WAVES_TABLE.chunk_read_field('wind_from'),
+    WATER_WAVES_TABLE.chunk_read_field('wind_to'), WATER_WAVES_TABLE.chunk_read_field('wind_blend'),
+    WATER_WAVES_TABLE.chunk_read_field('particle_levels')]);

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

@@ -1,14 +1,68 @@
-/** Storage grows with source primitives; patch instances are expanded by the vertex shader. */
-export function graph_water_tessellation({ graph, scene, camera, meshlets, meshlet_capacity, tessellation }: {
-    graph: any;
-    scene: any;
-    camera: any;
-    meshlets: any;
-    meshlet_capacity: any;
-    tessellation: any;
+/**
+ * Where each list's records start in the cell buffer, and the buffer's words: interior and boundary cells a word each,
+ * triangles drawn as themselves two words each, patches a word each, then each boundary cell's clipped polygon. The
+ * vertex stage finds them by the same arithmetic over the limits (chunk_water_lod_layout).
+ *
+ * @param {{interior: number, boundary: number, triangles: number, patches: number}} limits
+ * @returns {{interior: number, boundary: number, triangles: number, patches: number, polygons: number, words: number}}
+ */
+export function water_lod_cell_layout(limits: {
+    interior: number;
+    boundary: number;
+    triangles: number;
+    patches: number;
 }): {
-    tiles: any;
-    sums: number;
-    count: any;
+    interior: number;
+    boundary: number;
+    triangles: number;
+    patches: number;
+    polygons: number;
+    words: number;
+};
+/**
+ * The view's lattice cut by the drawn bodies' authored triangles (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md
+ * §4.3): per triangle, either itself on the triangle list or its candidates; per candidate, its quadrants and rows;
+ * and the patch, interior cell and boundary cell lists, each compacted by an ordered scan so equal-depth ownership
+ * between bodies stays deterministic. Candidates and cells are cut to `limits`; the totals before the cut land in `statistics`, for
+ * the caller to grow its budgets by.
+ *
+ * @param {object} options
+ * @param {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} options.graph
+ * @param {object} options.scene GPU scene context
+ * @param {number} options.camera the view's camera uniform resource
+ * @param {number} options.meshlets the drawn bodies' meshlets resource, from {@link GPUWaterBodies#meshlets}
+ * @param {number} options.lod_bodies the view's per-body lattice frames resource, from the same
+ * @param {number} options.meshlet_capacity every water meshlet the scene holds: the triangle slots there can be
+ * @param {{ranges: number, orthographic: number, level: number, distance: number}} options.lod the view's lattice choice
+ * @param {{candidates: number, interior: number, boundary: number, triangles: number, patches: number}} options.limits budgets
+ * @param {GPUBuffer} options.steep per wave row: set for a body with a triangle too steep for the lattice
+ * @returns {{candidates: number, cells: number, commands: number, statistics: number}} resources
+ */
+export function graph_water_tessellation({ graph, scene, camera, meshlets, lod_bodies, meshlet_capacity, lod, limits, steep }: {
+    graph: import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+    scene: object;
+    camera: number;
+    meshlets: number;
+    lod_bodies: number;
+    meshlet_capacity: number;
+    lod: {
+        ranges: number;
+        orthographic: number;
+        level: number;
+        distance: number;
+    };
+    limits: {
+        candidates: number;
+        interior: number;
+        boundary: number;
+        triangles: number;
+        patches: number;
+    };
+    steep: GPUBuffer;
+}): {
+    candidates: number;
+    cells: number;
+    commands: number;
+    statistics: number;
 };
 //# sourceMappingURL=graph_water_tessellation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"graph_water_tessellation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/graph_water_tessellation.js"],"names":[],"mappings":"AAQA,+FAA+F;AAC/F;;;;;;;;;;;EAwBC"}
+{"version":3,"file":"graph_water_tessellation.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/water/surface/graph_water_tessellation.js"],"names":[],"mappings":"AAiCA;;;;;;;GAOG;AACH,8CAHW;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,GACtE;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,CAQrH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAXsG,KAAK,EAAhG,OAAO,8DAA8D,EAAE,UAAU;IACjE,KAAK,EAArB,MAAM;IACU,MAAM,EAAtB,MAAM;IACU,QAAQ,EAAxB,MAAM;IACU,UAAU,EAA1B,MAAM;IACU,gBAAgB,EAAhC,MAAM;IAC2E,GAAG,EAApF;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC;IAC+B,MAAM,EAA5G;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC;IACzE,KAAK;IACtB;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAC,CAsGrF"}