@woosh/meep-engine 3.41.0 → 3.43.0

package/src/shade/renderer/water/surface/particles/shader_water_particles.js

@@ -0,0 +1,874 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+import { WGSLAttribute } from "../../../shader/type/WGSLAttribute.js";
+import { WGSLAttributes } from "../../../shader/type/WGSLAttributes.js";
+import { WGSLStructField } from "../../../shader/type/WGSLStructField.js";
+import { atomic_u32, f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { STRUCT_DISPATCH_COMPUTE_COMMAND } from "../../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { MESHLET_METADATA_STRUCT } from "../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { BVH2_NODE_STRUCT } from "../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { chunk_folded_workgroup_index } from "../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { chunk_scene_database_access, chunk_scene_database_access_rw } from "../../../scene/chunk_scene_database_access.js";
+import { WaterActivity } from "../shader_water_cull.js";
+import { WATER_WAVES_TABLE as waves } from "../../medium/chunk_water_bodies.js";
+import { WATER_PARTICLE_BODY_BOUNDS_STRIDE } from "../shader_water_waves_combine.js";
+import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
+import { WATER_WAVE_IMPULSE_LIMIT } from "../WATER_WAVE_RECORD_STRUCT.js";
+import { chunk_water_particle } from "./chunk_water_particle.js";
+import { chunk_water_particle_step } from "./chunk_water_particle_step.js";
+import { WATER_PARTICLE_GATHER_BUDGET } from "../chunk_water_surface_sample.js";
+
+/** A particle array with its live count in front, as the indirect commands read it. */
+export const WATER_PARTICLE_ARRAY_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", u32),
+    WGSLStructField.from("elements", WebGPUArray.from(WATER_PARTICLE_STRUCT), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** The same array where emitters append by an atomic count. */
+export const WATER_PARTICLE_ARRAY_APPEND_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", atomic_u32),
+    WGSLStructField.from("elements", WebGPUArray.from(WATER_PARTICLE_STRUCT), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** Bucket counts while binning: the table size in front, atomic counters behind. */
+export const WATER_PARTICLE_BUCKETS_STRUCT = WebGPUStruct.fromFields(
+    WGSLStructField.from("count", u32),
+    WGSLStructField.from("elements", WebGPUArray.from(atomic_u32), WGSLAttribute.from(WGSLAttributes.Align, 16)),
+);
+
+/** Smallest hash table, so an idle frame scans little. */
+export const WATER_PARTICLE_TABLE_MIN = 1024;
+
+/** Bucket entries one particle can take: the 2×2 cells its support overlaps. */
+export const WATER_PARTICLE_CORNERS = 4;
+
+/** Buckets ordered by particle; a crowded bucket past this keeps its arrival order. */
+export const WATER_PARTICLE_RANK_LIMIT = 64;
+
+/**
+ * Packets a crowded point keeps. A point reads a cell of every level its body has, and a cell is crowded where its most
+ * crowded point reads more than this: a point of it at its level and the coarser ones, or one under it where finer
+ * levels hold packets too. Then each run of a front in it is drawn by its packets' least share of their cells: this
+ * many times the packet's steepness over the summed steepness that point reads, whatever the levels it is read at. So
+ * about this many stay at a point, the steepest whole wherever they sit, and a front stays whole or goes. What is
+ * elsewhere on the body does not count, so a splash far off, or a front moving to a coarser level, changes nothing here.
+ *
+ * A front's lot is its own for life and the same in every cell it reaches, so the fronts of the lowest lots are kept in
+ * every crowd they are in, whatever their size: the count at a point varies by fronts' worth around this, and a front
+ * the outline broke is drawn particle by particle, ~20 entries in one cell. Where a point would read more than the
+ * gather budget, its cells keep no more of it than their steepness's part, the lowest keys first
+ * ({@link WATER_PARTICLE_CROWD_BINS}), so no point reads past the budget. A whole front is drawn as the seven it was
+ * emitted as (water_particle_group), so three fresh splashes cross whole, whatever their steepness and levels; a fourth
+ * over them thins one.
+ *
+ * A cell only one front reaches is not crowded, however many of its packets it holds: one front puts at most ~40 in
+ * a cell, within the gather budget.
+ */
+export const WATER_PARTICLE_CELL_SHARE = 24;
+
+/**
+ * Octaves a crowded cell counts its entries in, by the key its lottery keeps them by (a front's lot over its
+ * steepness; the lowest kept first), below the most it can keep: bin j holds keys from 2^-(j+1) of that reach to
+ * 2^-j of it, the last everything below. A cell whose point could read past the gather budget drops its octaves from
+ * the top until the rest fit its part of the budget, so it may keep up to an octave's worth fewer than would fit.
+ */
+export const WATER_PARTICLE_CROWD_BINS = 4;
+
+/**
+ * Words a bucket's crowd takes, as the weigh pass sums it: its summed steepness, its largest front and complement of a
+ * front entered, and its entries.
+ */
+export const WATER_PARTICLE_CROWD_WORDS = 4;
+
+/**
+ * Words the nest pass adds to a bucket's crowd, in a buffer of their own so that it reads weigh's sums as plain loads:
+ * the most entries and the most summed steepness a point under it reads where finer levels hold packets, and its
+ * entries by key, {@link WATER_PARTICLE_CROWD_BINS} octaves.
+ */
+export const WATER_PARTICLE_NEST_WORDS = 2 + WATER_PARTICLE_CROWD_BINS;
+
+/** Width of the ramp a thinned packet fades over, a fraction of its share. */
+export const WATER_PARTICLE_THINNING_RAMP = 0.25;
+
+/** Fixed-point scale of a packet's steepness in its cells' sums. */
+const WATER_PARTICLE_WEIGHT_SCALE = 1 << 20;
+
+const STRIDE = WATER_PARTICLE_BODY_BOUNDS_STRIDE;
+const WORDS = WATER_PARTICLE_CROWD_WORDS;
+const NEST = WATER_PARTICLE_NEST_WORDS;
+const BINS = WATER_PARTICLE_CROWD_BINS;
+
+/** The step's settings: one immediate per entry point. */
+export const WATER_PARTICLE_STEP_STRUCT = WebGPUStruct.from({ dt: f32, capacity: u32 }, 'WaterParticleStepSettings');
+
+/** The pool's limits for the frame's finalize. */
+export const WATER_PARTICLE_LIMITS_STRUCT = WebGPUStruct.from({ capacity: u32, table_limit: u32 }, 'WaterParticleLimits');
+
+const update_resources = new ShaderResourceSetDescriptor();
+update_resources.setImmediate('frame', WATER_PARTICLE_STEP_STRUCT);
+update_resources.createGroup()
+    .addStorageBuffer('particles', WATER_PARTICLE_ARRAY_STRUCT, true)
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ, true)
+    .addStorageBuffer('images', WebGPUArray.from(WATER_PARTICLE_STRUCT), true)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('scene_database', WebGPUArray.u32)
+    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer('blas_lookup', WebGPUArray.u32)
+    .addStorageBuffer('blas_data', WebGPUArray.from(BVH2_NODE_STRUCT))
+    .addStorageBuffer('meshlet_metadata', WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer('meshlet_data', WebGPUArray.from(f32));
+
+/**
+ * Advance every live particle of a body simulated this frame in place and count what it leaves: 0, 1, 2 (it and the
+ * mirror image it left at the outline, which goes to `images` at its index), 3 or 6 (each split into three). A paused
+ * body's particles stand still and leave themselves.
+ */
+const update_body = CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) index: u32,
+    @builtin(subgroup_invocation_id) lane: u32, @builtin(subgroup_size) lanes: u32) {
+    let i = folded_workgroup_index(group) * 64u + index;
+    let count = min(particles.count, frame.capacity);
+    // every lane reaches the shuffles below: one past the count reads the last particle and writes nothing
+    let live = i < count;
+    var particle = particles.elements[min(i, max(count, 1u) - 1u)];
+    let node = ${waves.marshalling_method_read_field('node')}(&scene_database, particle.body);
+    let paused = (activity[particle.body] & ${WaterActivity.Active}u) == 0u;
+    let stepping = live && !paused && node != 0u && node != ~0u;
+    var scale = vec2<f32>(1.0);
+    var geometry = 0u;
+    // the axis point of its leading arc a step on, and whether it is over the body
+    var axis = vec2<f32>(0.0);
+    var hint = WaterParticleArcHint(0u, 0u, 0u);
+    if (stepping) {
+        let global = scene_read_node(&scene_database, node).global;
+        scale = max(vec2<f32>(length(global[0].xyz), length(global[2].xyz)), vec2<f32>(1e-20));
+        geometry = ${waves.marshalling_method_read_field('geometry')}(&scene_database, particle.body);
+        if (particle.reflected == 0u) {
+            axis = water_particle_leading_point(particle, frame.dt, 0u);
+            let hit = water_particle_over_body(geometry, axis / scale);
+            hint = WaterParticleArcHint(1u, select(0u, 1u, hit.t >= 0.0), hit.triangle);
+        }
+    }
+    // A front's particles stand in a row β apart, so the ends of one's window are its neighbours' axis points: each
+    // takes what the lanes either side found there rather than casting its own down-rays.
+    let state = hint.known | (hint.over << 1u) | (particle.body << 2u);
+    let below = max(lane, 1u) - 1u;
+    let above = min(lane + 1u, lanes - 1u);
+    let below_axis = subgroupShuffle(axis, below);
+    let below_state = subgroupShuffle(state, below);
+    let above_axis = subgroupShuffle(axis, above);
+    let above_state = subgroupShuffle(state, above);
+    if (!live) { return; }
+    var left = 1u;
+    if (stepping) {
+        if (particle.reflected == 0u) {
+            let tolerance = 2e-3 * particle.radius;
+            for (var k = 1u; k < 3u; k++) {
+                let end = water_particle_leading_point(particle, frame.dt, k);
+                var neighbour = 0u;
+                if ((below_state >> 2u) == particle.body && distance(end, below_axis) <= tolerance) { neighbour = below_state; }
+                if ((above_state >> 2u) == particle.body && distance(end, above_axis) <= tolerance) { neighbour = above_state; }
+                hint.known |= (neighbour & 1u) << k;
+                hint.over |= ((neighbour >> 1u) & 1u) << k;
+            }
+        }
+        let threshold = water_particle_threshold(${waves.marshalling_method_read_field('slope_variance')}(&scene_database, particle.body),
+            count, frame.capacity);
+        let advanced = water_particle_advance(particle, frame.dt, geometry, scale,
+            ${waves.marshalling_method_read_field('wind')}(&scene_database, particle.body).w, threshold, hint);
+        particle = advanced.particle;
+        left = advanced.children;
+        if (left == 2u || left == 6u) { images[i] = advanced.image; }
+    } else if (!paused) {
+        left = 0u;
+    }
+    particles.elements[i] = particle;
+    children.elements[i] = left;
+}
+`, [chunk_water_particle_step, chunk_scene_database_access, waves.chunk_read_field('node'), waves.chunk_read_field('slope_variance'),
+    waves.chunk_read_field('geometry'), waves.chunk_read_field('wind'), chunk_folded_workgroup_index]);
+update_body.addExtension(WebGPUExtensionType.Subgroups);
+export const shader_water_particles_update = ComputeShader.from({ label: 'Water / particles update', resources: update_resources,
+    body: update_body });
+
+const split_resources = new ShaderResourceSetDescriptor();
+split_resources.setImmediate('capacity', u32);
+split_resources.createGroup()
+    .addStorageBuffer('particles', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('images', WebGPUArray.from(WATER_PARTICLE_STRUCT))
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true);
+
+/**
+ * Write what each particle leaves into the next array at its scanned offset, in order: the particle, then the mirror
+ * image it left; each split one's three at θ − β/3, θ, θ + β/3 with β/3 each. So a front's particles stay in a row
+ * and in order, and an image follows its packet as a front of its own. Past capacity, the tail is dropped.
+ */
+export const shader_water_particles_split = ComputeShader.from({ label: 'Water / particles split', resources: split_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    let count = min(particles.count, capacity);
+    if (i >= count) { return; }
+    let end = children.elements[i];
+    var start = 0u;
+    if (i > 0u) { start = children.elements[i - 1u]; }
+    let particle = particles.elements[i];
+    if (end - start == 1u) {
+        if (start < capacity) { next.elements[start] = particle; }
+        return;
+    }
+    // three of each when they split
+    let split = (end - start) % 3u == 0u;
+    let each = select(1u, 3u, split);
+    for (var k = start; k < end && k < capacity; k++) {
+        var child = particle;
+        if (k - start >= each) { child = images[i]; }
+        if (split) {
+            child.dispersion = child.dispersion / 3.0;
+            child.angle += (f32((k - start) % 3u) - 1.0) * child.dispersion;
+        }
+        next.elements[k] = child;
+    }
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk, chunk_folded_workgroup_index]) });
+
+const total_resources = new ShaderResourceSetDescriptor();
+total_resources.setImmediate('capacity', u32);
+total_resources.createGroup()
+    .addStorageBuffer('children', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true);
+
+/** The next array's count: everything the scan placed, up to capacity. */
+export const shader_water_particles_total = ComputeShader.from({ label: 'Water / particles total', resources: total_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(1)
+fn main() {
+    let total = select(0u, children.elements[max(children.count, 1u) - 1u], children.count > 0u);
+    next.count = min(total, capacity);
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk]) });
+
+const emit_resources = new ShaderResourceSetDescriptor();
+emit_resources.setImmediate('capacity', u32);
+emit_resources.createGroup()
+    .addStorageBuffer('scene_database', WebGPUArray.u32, true)
+    .addStorageBuffer('emit_rows', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('steep', WebGPUArray.from(u32))
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('particle_bounds', WebGPUArray.u32, true)
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_APPEND_STRUCT, true);
+
+/**
+ * Each queued splash of a row on the culling pass's emit list becomes a ring
+ * (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.3): packets of the splash's radius r, two radii out from its centre,
+ * their windows' arcs no longer than their envelopes, ridge height strength·r/c (a vertical velocity over the time a crest takes to cross the
+ * packet), no steeper than 0.1. The row's queue is spent. A paused body's ring stands still with its other particles,
+ * which this frame's binning does not visit, so the ring's bound is added to the body's own here.
+ */
+export const shader_water_particles_emit = ComputeShader.from({ label: 'Water / particles emit', resources: emit_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let index = folded_workgroup_index(group) * 64u + lane;
+    if (index >= emit_rows.count) { return; }
+    let row = emit_rows.elements[index];
+    let wave = ${waves.marshalling_method_read_rw}(&scene_database, row);
+    ${waves.marshalling_method_write_field('impulse_count')}(&scene_database, row, 0u);
+    if (wave.node == 0u || wave.node == ~0u || steep[row] != 0u) { return; }
+    let global = scene_read_node_rw(&scene_database, wave.node).global;
+    let scale = vec2<f32>(length(global[0].xyz), length(global[2].xyz));
+    let paused = (activity[row] & ${WaterActivity.Active}u) == 0u;
+    var held = 0.0;
+    for (var j = 0u; j < min(wave.impulse_count, ${WATER_WAVE_IMPULSE_LIMIT}u); j++) {
+        let impulse = wave.impulses[j];
+        let radius = clamp(impulse.z, 1e-3, 16.0);
+        let height = clamp(impulse.w * radius / water_particle_phase_speed(radius), -0.1 * radius, 0.1 * radius);
+        let reach = water_particle_launch_distance(radius);
+        // as many as keep each window's arc within the envelope's half-length, as the step splits them
+        let count = u32(ceil(WATER_TAU * reach / water_particle_half_length_at(radius, reach)));
+        let dispersion = WATER_TAU / f32(count);
+        let age = reach / water_particle_group_speed(radius);
+        let base = atomicAdd(&next.count, count);
+        // a ring that does not fit whole is not emitted: an arc of it would break its front's partition of unity.
+        // The slots it took up to capacity hold flat packets, which the next step drops.
+        let ridge = select(0.0, height, base + count <= capacity);
+        for (var k = 0u; k < count; k++) {
+            if (base + k >= capacity) { break; }
+            next.elements[base + k] = ${WATER_PARTICLE_STRUCT.wgsl_ref}(impulse.xy * scale, f32(k) * dispersion, age, ridge, radius, dispersion, row, 0u);
+        }
+        held += f32(count) * abs(ridge);
+    }
+    if (paused && held > 0.0) {
+        // level 0's slot, and its bit, so that the culling pass, which reads the slots only of the levels set, counts it
+        let at = row * ${STRIDE}u;
+        particle_bounds[at] |= 1u;
+        particle_bounds[at + 1u] = bitcast<u32>(bitcast<f32>(particle_bounds[at + 1u]) + held);
+    }
+}
+`, [waves.chunk_read_rw, waves.wgsl_gen_write_field_code('impulse_count'), chunk_water_particle, chunk_scene_database_access_rw,
+        chunk_folded_workgroup_index]) });
+
+const finalize_resources = new ShaderResourceSetDescriptor();
+finalize_resources.setImmediate('limits', WATER_PARTICLE_LIMITS_STRUCT);
+finalize_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT, true)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ, true)
+    .addStorageBuffer('table_command', STRUCT_DISPATCH_COMPUTE_COMMAND, true);
+
+/**
+ * The live count, clamped to capacity (emitters append past it), and the frame's hash table size: twice the
+ * entries the particles can take, a power of two, at least ${WATER_PARTICLE_TABLE_MIN}; and the command that clears
+ * that much of the table, a thread a bucket.
+ */
+export const shader_water_particles_finalize = ComputeShader.from({ label: 'Water / particles finalize', resources: finalize_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(1)
+fn main() {
+    let live = min(next.count, limits.capacity);
+    next.count = live;
+    let wanted = max(2u * ${WATER_PARTICLE_CORNERS}u * live, ${WATER_PARTICLE_TABLE_MIN}u);
+    let table = min(1u << (32u - countLeadingZeros(wanted - 1u)), limits.table_limit);
+    offsets.count = table;
+    table_command.workgroupCountX = (table + 63u) / 64u;
+    table_command.workgroupCountY = 1u;
+    table_command.workgroupCountZ = 1u;
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk]) });
+
+const clear_resources = new ShaderResourceSetDescriptor();
+clear_resources.createGroup()
+    .addStorageBuffer('buckets', WATER_PARTICLE_BUCKETS_STRUCT, true)
+    .addStorageBuffer('bucket_amplitude', WebGPUArray.u32, true)
+    .addStorageBuffer('bucket_weight', WebGPUArray.u32, true)
+    .addStorageBuffer('bucket_nest', WebGPUArray.u32, true);
+
+/**
+ * Zero the frame's table, as far as finalize sized it: each bucket's count, largest |a| and crowd. A frame pays for the
+ * table its particles take, not for the pool's capacity; the buckets past it are never read.
+ */
+export const shader_water_particles_clear = ComputeShader.from({ label: 'Water / particles clear', resources: clear_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let b = folded_workgroup_index(group) * 64u + lane;
+    if (b >= buckets.count) { return; }
+    atomicStore(&buckets.elements[b], 0u);
+    bucket_amplitude[b] = 0u;
+    for (var word = 0u; word < ${WORDS}u; word++) { bucket_weight[${WORDS}u * b + word] = 0u; }
+    for (var word = 0u; word < ${NEST}u; word++) { bucket_nest[${NEST}u * b + word] = 0u; }
+}
+`, [chunk_folded_workgroup_index]) });
+
+/**
+ * A live particle's place in the hash this frame: its kernel at this time, its level and the cells its
+ * support overlaps (one or two a side, the level's cell being at least the support's diameter).
+ */
+const chunk_water_particle_cells = CodeChunk.from(/* language=WGSL */ `
+struct WaterParticleCells {
+    entry: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref},
+    level: u32,
+    first: vec2<i32>,
+    span: vec2<u32>,
+}
+
+fn water_particle_cells(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, source: u32) -> WaterParticleCells {
+    var cells: WaterParticleCells;
+    let position = water_particle_position(particle);
+    let width = water_particle_width(particle);
+    let distance = water_particle_distance(particle);
+    let half_length = water_particle_half_length_at(particle.radius, distance);
+    let support = water_particle_support(half_length, width, particle.dispersion);
+    cells.level = water_particle_level(support);
+    let size = water_particle_cell_size(cells.level);
+    cells.first = vec2<i32>(floor((position - vec2<f32>(support)) / size));
+    let last = vec2<i32>(floor((position + vec2<f32>(support)) / size));
+    cells.span = vec2<u32>(clamp(last - cells.first, vec2<i32>(0), vec2<i32>(1))) + vec2<u32>(1u);
+    cells.entry = ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}(position, cells.first, particle.angle, particle.amplitude, particle.radius,
+        particle.dispersion, water_particle_phase(particle), water_particle_key(particle.body, cells.level), source, distance, half_length);
+    return cells;
+}
+
+fn water_particle_corner_cell(cells: WaterParticleCells, corner: u32) -> vec2<i32> {
+    return cells.first + vec2<i32>(i32(corner & 1u), i32(corner >> 1u));
+}
+
+fn water_particle_has_corner(cells: WaterParticleCells, corner: u32) -> bool {
+    return all(vec2<u32>(corner & 1u, corner >> 1u) < cells.span);
+}
+
+// A packet's claim on its cells: its steepness, fixed point.
+fn water_particle_weight(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> u32 {
+    return u32(min(abs(particle.amplitude) / max(particle.radius, 1e-6), 1.0) * ${WATER_PARTICLE_WEIGHT_SCALE}.0);
+}
+
+// The front a packet belongs to: from its centre, the same for every packet of the front.
+fn water_particle_front(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> u32 {
+    return pcg3d(vec3<u32>(bitcast<u32>(particle.origin.x), bitcast<u32>(particle.origin.y), particle.body)).x;
+}
+
+// A number in [0, 1) that stays with a front while it travels, the same for all its packets.
+fn water_particle_lot(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return f32(water_particle_front(particle) >> 8u) * (1.0 / 16777216.0);
+}
+
+// The bucket of the cell holding a cell's points at a level as coarse as its own or coarser, as the sampler finds it.
+fn water_particle_bucket_over(body: u32, level: u32, cell: vec2<i32>, over: u32, table_size: u32) -> u32 {
+    return water_particle_bucket(body, over, cell >> vec2<u32>(over - level), table_size);
+}
+
+// The key a crowd keeps a packet by: its front's lot over its steepness. A packet is drawn while its lot is under its
+// share, which is its steepness times its cell's, so a crowd keeps the packets of its lowest keys, the steepest first.
+fn water_particle_precedence(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return water_particle_lot(particle) / f32(water_particle_weight(particle));
+}
+
+// The largest key a crowded cell's lottery can keep, from the summed steepness a point of it reads at its level and
+// the coarser ones: its most crowded point reads at least that, and the ramp draws a lot up to its share above it.
+fn water_particle_crowd_reach(steepness: u32) -> f32 {
+    return ${1 + WATER_PARTICLE_THINNING_RAMP} * ${WATER_PARTICLE_CELL_SHARE}.0 / f32(steepness);
+}
+
+// The octave of a cell's reach a key falls in, from the exponent of their ratio: [2^-(j+1), 2^-j) is bin j, the last
+// takes everything below, and one past the reach is not counted (${BINS}u).
+fn water_particle_crowd_bin(precedence: f32, reach: f32) -> u32 {
+    let ratio = precedence / reach;
+    if (!(ratio < 1.0)) { return ${BINS}u; }
+    return min(126u - ((bitcast<u32>(ratio) >> 23u) & 0xffu), ${BINS - 1}u);
+}
+
+// How much of a packet its crowd leaves drawn, from its share of the most crowded of its cells: all of it from a share
+// of one, and below that, all of it while its lot is under its share, fading to none a ramp of that share above, and
+// none from a share of none. So a cell keeps about its share whatever its crowd.
+fn water_particle_visibility(share: f32, lot: f32) -> f32 {
+    if (!(share > 0.0)) { return 0.0; }
+    return clamp((share - lot) / (${WATER_PARTICLE_THINNING_RAMP} * share) + 1.0, 0.0, 1.0);
+}
+`, [chunk_water_particle]);
+
+const fronts_resources = new ShaderResourceSetDescriptor();
+fronts_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('fronts', COLLECTION_U32_STRUCT_READ, true);
+
+/**
+ * Where each front's run of particles begins: 1 at a particle not of the front before it, else 0. A front keeps its
+ * particles in a row and in order — a ring is emitted whole, a split puts its three in its place, the dead leave no
+ * gap — so the inclusive scan of these numbers each run from 1. A mirror image follows its packet in the row: it
+ * breaks its front's run there, as a death does, and is a front of its own.
+ */
+export const shader_water_particles_fronts = ComputeShader.from({ label: 'Water / particles fronts', resources: fronts_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    fronts.elements[i] = select(1u, 0u, i > 0u && water_particle_same_front(next.elements[i - 1u], next.elements[i]));
+}
+`, [chunk_water_particle, chunk_folded_workgroup_index]) });
+
+const runs_resources = new ShaderResourceSetDescriptor();
+runs_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('fronts', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('runs', WebGPUArray.u32, true);
+
+/**
+ * Two words a run: its first particle, and the share its crowd leaves it, none yet (the share pass lowers it).
+ */
+export const shader_water_particles_runs = ComputeShader.from({ label: 'Water / particles runs', resources: runs_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let run = fronts.elements[i];
+    if (i == 0u || fronts.elements[i - 1u] != run) {
+        runs[2u * (run - 1u)] = i;
+        runs[2u * (run - 1u) + 1u] = bitcast<u32>(1e30);
+    }
+}
+`, [WATER_PARTICLE_STRUCT.declaration_chunk, chunk_folded_workgroup_index]) });
+
+const groups_resources = new ShaderResourceSetDescriptor();
+groups_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('fronts', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('runs', WebGPUArray.u32)
+    .addStorageBuffer('draw', WebGPUArray.u32, true);
+
+/**
+ * Two words a particle: its run, and how the frame draws it ({@link chunk_water_particle}'s water_particle_group): 1 as
+ * itself, 0 not at all, 3^g for the middle of a whole front's group of 3^g, drawn as one packet.
+ */
+export const shader_water_particles_groups = ComputeShader.from({ label: 'Water / particles groups', resources: groups_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    let count = next.count;
+    if (i >= count) { return; }
+    let run = fronts.elements[i] - 1u;
+    let start = runs[2u * run];
+    var end = count;
+    if (run + 1u < fronts.elements[count - 1u]) { end = runs[2u * (run + 1u)]; }
+    draw[2u * i] = run;
+    draw[2u * i + 1u] = water_particle_group(next.elements[i], end - start, i - start);
+}
+`, [chunk_water_particle, chunk_folded_workgroup_index]) });
+
+const weigh_resources = new ShaderResourceSetDescriptor();
+weigh_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('bucket_weight', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each packet drawn of a body simulated this frame adds its steepness to every cell its support overlaps: how crowded
+ * a cell is, for the share pass to thin it by. Per bucket ({@link WATER_PARTICLE_CROWD_WORDS}) the sum, the largest
+ * front and complement of a front entered, which are each other's complements only where one front alone was, and the
+ * entries. And its level to its body's: a point reads a cell of every level its body has.
+ */
+export const shader_water_particles_weigh = ComputeShader.from({ label: 'Water / particles weigh', resources: weigh_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    let weight = water_particle_weight(particle);
+    let front = water_particle_front(particle);
+    atomicOr(&body_bounds[particle.body * ${STRIDE}u], 1u << cells.level);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let at = ${WATER_PARTICLE_CROWD_WORDS}u * water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count);
+        atomicAdd(&bucket_weight[at], weight);
+        atomicMax(&bucket_weight[at + 1u], front);
+        atomicMax(&bucket_weight[at + 2u], ~front);
+        atomicAdd(&bucket_weight[at + 3u], 1u);
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const nest_resources = new ShaderResourceSetDescriptor();
+nest_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('body_bounds', WebGPUArray.u32)
+    .addStorageBuffer('bucket_weight', WebGPUArray.u32)
+    .addStorageBuffer('bucket_nest', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each packet drawn of a body simulated this frame, its cells weighed: what a point of each of its cells reads at its
+ * level and the coarser ones, entries and summed steepness, raised onto the cell over it at every coarser level its
+ * body has, so a cell knows its most crowded point where finer levels hold packets under it; and its entry counted
+ * among its cell's by its key (water_particle_crowd_bin), for the share pass to cap a crowd by.
+ */
+export const shader_water_particles_nest = ComputeShader.from({ label: 'Water / particles nest', resources: nest_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    let precedence = water_particle_precedence(particle);
+    // its body's levels coarser than its own
+    let coarser = body_bounds[particle.body * ${STRIDE}u] & ~((2u << cells.level) - 1u);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let cell = water_particle_corner_cell(cells, corner);
+        let bucket = water_particle_bucket(particle.body, cells.level, cell, offsets.count);
+        // what a point of the cell reads at its level and the coarser ones
+        var entries = bucket_weight[${WORDS}u * bucket + 3u];
+        var steepness = bucket_weight[${WORDS}u * bucket];
+        var above = coarser;
+        for (var n = 0u; n < WATER_PARTICLE_LEVELS && above != 0u; n++) {
+            let over = ${WORDS}u * water_particle_bucket_over(particle.body, cells.level, cell, firstTrailingBit(above), offsets.count);
+            above &= above - 1u;
+            entries += bucket_weight[over + 3u];
+            steepness += bucket_weight[over];
+        }
+        // onto every cell over it
+        above = coarser;
+        for (var n = 0u; n < WATER_PARTICLE_LEVELS && above != 0u; n++) {
+            let over = ${NEST}u * water_particle_bucket_over(particle.body, cells.level, cell, firstTrailingBit(above), offsets.count);
+            above &= above - 1u;
+            atomicMax(&bucket_nest[over], entries);
+            atomicMax(&bucket_nest[over + 1u], steepness);
+        }
+        let octave = water_particle_crowd_bin(precedence, water_particle_crowd_reach(steepness));
+        if (octave < ${BINS}u) { atomicAdd(&bucket_nest[${NEST}u * bucket + 2u + octave], 1u); }
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const share_resources = new ShaderResourceSetDescriptor();
+share_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('bucket_weight', WebGPUArray.u32)
+    .addStorageBuffer('bucket_nest', WebGPUArray.u32)
+    .addStorageBuffer('body_bounds', WebGPUArray.u32)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('runs', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each packet drawn its share of the most crowded of its cells, lowered onto its run: a run is thinned whole, by the most
+ * crowded cell any of its packets is in, so a front is never holed. A cell is crowded where its most crowded point (one
+ * of it at its level and the coarser ones, or one under it the nest pass raised) reads more than
+ * {@link WATER_PARTICLE_CELL_SHARE} entries, and a packet's share there is that many times its steepness over the summed
+ * steepness that point reads. Where that point would read more than the gather budget, the cell keeps no more of it
+ * than its own steepness's part: its keys' octaves dropped from the top until the rest fit
+ * ({@link WATER_PARTICLE_CROWD_BINS}). A cell only one front reaches does not count.
+ */
+export const shader_water_particles_share = ComputeShader.from({ label: 'Water / particles share', resources: share_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    let weight = f32(water_particle_weight(particle));
+    let coarser = body_bounds[particle.body * ${STRIDE}u] & ~((2u << cells.level) - 1u);
+    var share = 1e30;
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let cell = water_particle_corner_cell(cells, corner);
+        let bucket = water_particle_bucket(particle.body, cells.level, cell, offsets.count);
+        let at = ${WORDS}u * bucket;
+        let nested = ${NEST}u * bucket;
+        if (bucket_weight[at + 1u] == ~bucket_weight[at + 2u]) { continue; }
+        // what a point of the cell reads at its level and the coarser ones
+        var entries = bucket_weight[at + 3u];
+        var steepness = bucket_weight[at];
+        var above = coarser;
+        for (var n = 0u; n < WATER_PARTICLE_LEVELS && above != 0u; n++) {
+            let over = ${WORDS}u * water_particle_bucket_over(particle.body, cells.level, cell, firstTrailingBit(above), offsets.count);
+            above &= above - 1u;
+            entries += bucket_weight[over + 3u];
+            steepness += bucket_weight[over];
+        }
+        // and what its most crowded point reads
+        let crowd = max(entries, bucket_nest[nested]);
+        let total = max(steepness, bucket_nest[nested + 1u]);
+        if (crowd <= ${WATER_PARTICLE_CELL_SHARE}u || total == 0u) { continue; }
+        share = min(share, ${WATER_PARTICLE_CELL_SHARE}.0 * weight / f32(total));
+        if (crowd <= ${WATER_PARTICLE_GATHER_BUDGET}u) { continue; }
+        // no more kept than its part of the budget: the octaves of its keys dropped from the top until the rest fit
+        let quota = ${WATER_PARTICLE_GATHER_BUDGET}.0 * f32(bucket_weight[at]) / f32(total);
+        var below = 0u;
+        for (var octave = 0u; octave < ${BINS}u; octave++) { below += bucket_nest[nested + 2u + octave]; }
+        var reach = water_particle_crowd_reach(steepness);
+        for (var octave = 0u; octave < ${BINS}u && f32(below) > quota; octave++) {
+            below -= bucket_nest[nested + 2u + octave];
+            reach = select(0.0, 0.5 * reach, octave + 1u < ${BINS}u);
+        }
+        // drawn while its lot is under the ramp above its share: while its key is under the reach left
+        share = min(share, reach * weight / ${1 + WATER_PARTICLE_THINNING_RAMP});
+    }
+    // non-negative floats order as their bits do
+    atomicMin(&runs[2u * draw[2u * i] + 1u], bitcast<u32>(share));
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const bin_resources = new ShaderResourceSetDescriptor();
+bin_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('buckets', WATER_PARTICLE_BUCKETS_STRUCT, true)
+    .addStorageBuffer('slots', WebGPUArray.u32, true)
+    .addStorageBuffer('bucket_amplitude', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('runs', WebGPUArray.u32)
+    .addStorageBuffer('visible', WebGPUArray.from(f32), true);
+
+/**
+ * Enter each packet drawn of a body simulated this frame in every hash cell its support overlaps: count it into the
+ * cell's bucket, keep its slot there, raise the bucket's largest |a| to its own, and mark its level on its body. One
+ * atomic each: no compare-exchange loop a crowded bucket would serialize. A paused body's particles take no slot:
+ * nothing draws them this frame.
+ *
+ * Where cells are crowded (the share pass), a run is drawn by the share its most crowded cell leaves it and its
+ * front's lot: one decision for all its packets and all their cells, so neither a front nor the surface across cells
+ * is holed, and it does not change with the order particles arrive in. One left out takes no slot.
+ */
+export const shader_water_particles_bin = ComputeShader.from({ label: 'Water / particles bin', resources: bin_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+fn water_particle_unslotted(i: u32) {
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) { slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = ~0u; }
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    let particle = water_particle_drawn(next.elements[i], max(drawn, 1u));
+    if (drawn == 0u || (activity[particle.body] & ${WaterActivity.Active}u) == 0u) { water_particle_unslotted(i); return; }
+    let cells = water_particle_cells(particle, i);
+    let visibility = water_particle_visibility(bitcast<f32>(runs[2u * draw[2u * i] + 1u]), water_particle_lot(particle));
+    visible[i] = visibility;
+    if (!(visibility > 0.0)) { water_particle_unslotted(i); return; }
+    atomicOr(&body_bounds[particle.body * ${STRIDE}u], 1u << cells.level);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        var slot = ~0u;
+        if (water_particle_has_corner(cells, corner)) {
+            let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), buckets.count);
+            slot = atomicAdd(&buckets.elements[bucket], 1u);
+            // non-negative floats order as their bits do
+            atomicMax(&bucket_amplitude[bucket], bitcast<u32>(abs(particle.amplitude) * visibility));
+        }
+        slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = slot;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const scatter_resources = new ShaderResourceSetDescriptor();
+scatter_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('slots', WebGPUArray.u32)
+    .addStorageBuffer('visible', WebGPUArray.from(f32))
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('staging', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT), true);
+
+/** Each entry to its bucket's range, in arrival order, at the height its crowd leaves it; the rank pass orders it. */
+export const shader_water_particles_scatter = ComputeShader.from({ label: 'Water / particles scatter', resources: scatter_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    let cells = water_particle_cells(particle, i);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        let slot = slots[i * ${WATER_PARTICLE_CORNERS}u + corner];
+        if (slot == ~0u) { continue; }
+        let cell = water_particle_corner_cell(cells, corner);
+        let bucket = water_particle_bucket(particle.body, cells.level, cell, offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        var entry = cells.entry;
+        entry.cell = cell;
+        entry.amplitude *= visible[i];
+        staging[start + slot] = entry;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const rank_resources = new ShaderResourceSetDescriptor();
+rank_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('slots', WebGPUArray.u32)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('staging', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT))
+    .addStorageBuffer('entries', WebGPUArray.from(WATER_PARTICLE_ENTRY_STRUCT), true);
+
+/**
+ * Order every bucket by particle index then cell, so a gather that runs out of budget drops the same
+ * entries every frame (the particle array keeps its order from frame to frame). A bucket of more than
+ * ${WATER_PARTICLE_RANK_LIMIT} keeps its arrival order: a fixed budget of comparisons per entry.
+ */
+export const shader_water_particles_rank = ComputeShader.from({ label: 'Water / particles rank', resources: rank_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+fn water_entry_before(a: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}) -> bool {
+    if (a.source != b.source) { return a.source < b.source; }
+    if (a.cell.x != b.cell.x) { return a.cell.x < b.cell.x; }
+    return a.cell.y < b.cell.y;
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    let cells = water_particle_cells(particle, i);
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        let slot = slots[i * ${WATER_PARTICLE_CORNERS}u + corner];
+        if (slot == ~0u) { continue; }
+        let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        let end = offsets.elements[bucket];
+        let entry = staging[start + slot];
+        var rank = slot;
+        if (end - start <= ${WATER_PARTICLE_RANK_LIMIT}u) {
+            rank = 0u;
+            for (var j = start; j < end; j++) { rank += select(0u, 1u, water_entry_before(staging[j], entry)); }
+        }
+        entries[start + rank] = entry;
+    }
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });
+
+const bounds_resources = new ShaderResourceSetDescriptor();
+bounds_resources.createGroup()
+    .addStorageBuffer('next', WATER_PARTICLE_ARRAY_STRUCT)
+    .addStorageBuffer('activity', WebGPUArray.u32)
+    .addStorageBuffer('offsets', COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer('bucket_amplitude', WebGPUArray.u32)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true);
+
+/**
+ * Each body's bound per level: the largest of count × max |a| over the buckets its particles are in, which is
+ * at least the bucket's Σ|a|. Every particle that reaches a point is in that point's cell's bucket, and neither
+ * its height nor its horizontal displacement exceeds |a|, so the bound holds everywhere; a hash collision only
+ * adds to it.
+ */
+export const shader_water_particles_bounds = ComputeShader.from({ label: 'Water / particles bounds', resources: bounds_resources,
+    body: CodeChunk.from(/* language=WGSL */ `
+@compute @workgroup_size(64)
+fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) lane: u32) {
+    let i = folded_workgroup_index(group) * 64u + lane;
+    if (i >= next.count) { return; }
+    let drawn = draw[2u * i + 1u];
+    if (drawn == 0u) { return; }
+    let particle = water_particle_drawn(next.elements[i], drawn);
+    // a paused body keeps the bounds its particles last had
+    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) { return; }
+    let cells = water_particle_cells(particle, i);
+    var largest = 0.0;
+    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
+        if (!water_particle_has_corner(cells, corner)) { continue; }
+        let bucket = water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count);
+        var start = 0u;
+        if (bucket > 0u) { start = offsets.elements[bucket - 1u]; }
+        largest = max(largest, f32(offsets.elements[bucket] - start) * bitcast<f32>(bucket_amplitude[bucket]));
+    }
+    // non-negative floats order as their bits do
+    atomicMax(&body_bounds[particle.body * ${STRIDE}u + 1u + cells.level], bitcast<u32>(largest));
+}
+`, [chunk_water_particle_cells, chunk_folded_workgroup_index]) });