@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -1,3 +1,4 @@
+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";
@@ -8,6 +9,7 @@ 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";
@@ -20,6 +22,7 @@ import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PART
 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(
@@ -49,11 +52,46 @@ export const WATER_PARTICLE_CORNERS = 4;
 export const WATER_PARTICLE_RANK_LIMIT = 64;
 
 /**
- * Packets a crowded cell keeps: where more crowd a cell, each is drawn by its share of the cell's summed steepness
- * times this, so about this many stay, the steepest whole. Well under the surface sampler's gather budget and the rank
- * limit, so a point reads all of its cell and every bucket keeps the particles' order.
+ * 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_CELL_SHARE = 16;
+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;
@@ -62,6 +100,9 @@ export const WATER_PARTICLE_THINNING_RAMP = 0.25;
 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');
@@ -74,6 +115,7 @@ 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))
@@ -83,47 +125,91 @@ update_resources.createGroup()
     .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 or 3. A paused
+ * 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.
  */
-export const shader_water_particles_update = ComputeShader.from({ label: 'Water / particles update', resources: update_resources,
-    body: CodeChunk.from(/* language=WGSL */ `
+const update_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;
+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);
-    if (i >= count) { return; }
-    var particle = particles.elements[i];
-    var left = 0u;
+    // 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);
-    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) {
-        left = 1u;
-    } else if (node != 0u && node != ~0u) {
+    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;
-        let scale = max(vec2<f32>(length(global[0].xyz), length(global[2].xyz)), vec2<f32>(1e-20));
+        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, ${waves.marshalling_method_read_field('geometry')}(&scene_database, particle.body),
-            scale, ${waves.marshalling_method_read_field('wind')}(&scene_database, particle.body).w, threshold);
+        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]) });
+    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: a split particle's
- * three at θ − β/3, θ, θ + β/3 with β/3 each. Past capacity, the tail is dropped.
+ * 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 */ `
@@ -140,10 +226,16 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
         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;
-        child.dispersion = particle.dispersion / 3.0;
-        child.angle = particle.angle + (f32(k - start) - 1.0) * child.dispersion;
+        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;
     }
 }
@@ -178,7 +270,7 @@ emit_resources.createGroup()
 /**
  * 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,
- * a front's width apart, ridge height strength·r/c (a vertical velocity over the time a crest takes to cross the
+ * 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.
  */
@@ -200,8 +292,9 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
         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 = 2.0 * radius;
-        let count = u32(ceil(WATER_TAU * reach / (2.0 * 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);
@@ -210,7 +303,7 @@ fn main(@builtin(workgroup_id) group: vec3u, @builtin(local_invocation_index) la
         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);
+            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);
     }
@@ -228,11 +321,13 @@ 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('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}.
+ * 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 */ `
@@ -241,10 +336,38 @@ 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);
-    offsets.count = min(1u << (32u - countLeadingZeros(wanted - 1u)), limits.table_limit);
+    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).
@@ -261,14 +384,16 @@ fn water_particle_cells(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, source: u32
     var cells: WaterParticleCells;
     let position = water_particle_position(particle);
     let width = water_particle_width(particle);
-    let support = water_particle_support(particle.radius, width);
+    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,
-        width, water_particle_phase(particle), (particle.body << 4u) | cells.level, source, 0u);
+        particle.dispersion, water_particle_phase(particle), water_particle_key(particle.body, cells.level), source, distance, half_length);
     return cells;
 }
 
@@ -285,30 +410,135 @@ 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);
 }
 
-// A number in [0, 1) that stays with a packet while it travels: from its front's centre and direction.
+// 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 {
-    let bits = pcg3d(vec3<u32>(bitcast<u32>(particle.origin.x), bitcast<u32>(particle.origin.y), bitcast<u32>(particle.angle)));
-    return f32(bits.x >> 8u) * (1.0 / 16777216.0);
+    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. So a
-// cell keeps about its share whatever its crowd.
+// 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('bucket_weight', WebGPUArray.from(atomic_u32), true);
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('bucket_weight', WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true);
 
 /**
- * Each particle of a body simulated this frame adds its steepness to every cell its support overlaps: how crowded a
- * cell is, for the bin pass to thin it by.
+ * 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 */ `
@@ -316,14 +546,154 @@ export const shader_water_particles_weigh = ComputeShader.from({ label: 'Water /
 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 particle = next.elements[i];
+    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; }
-        atomicAdd(&bucket_weight[water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), offsets.count)], weight);
+        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]) });
 
@@ -335,44 +705,37 @@ bin_resources.createGroup()
     .addStorageBuffer('slots', WebGPUArray.u32, true)
     .addStorageBuffer('bucket_amplitude', WebGPUArray.from(atomic_u32), true)
     .addStorageBuffer('body_bounds', WebGPUArray.from(atomic_u32), true)
-    .addStorageBuffer('bucket_weight', WebGPUArray.u32)
+    .addStorageBuffer('draw', WebGPUArray.u32)
+    .addStorageBuffer('runs', WebGPUArray.u32)
     .addStorageBuffer('visible', WebGPUArray.from(f32), true);
 
 /**
- * Enter each particle 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.
+ * 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 weigh pass), a particle is drawn by how much its most crowded cell leaves it
- * ({@link WATER_PARTICLE_CELL_SHARE}): one decision for all its cells, so the surface stays continuous across them, and
- * from its own lot, so it does not change with the order particles arrive in. One left out takes no slot.
+ * 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 particle = next.elements[i];
-    if ((activity[particle.body] & ${WaterActivity.Active}u) == 0u) {
-        for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) { slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = ~0u; }
-        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 weight = f32(water_particle_weight(particle));
-    var share = 1e30;
-    for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) {
-        if (!water_particle_has_corner(cells, corner)) { continue; }
-        let total = f32(bucket_weight[water_particle_bucket(particle.body, cells.level, water_particle_corner_cell(cells, corner), buckets.count)]);
-        if (total > 0.0) { share = min(share, ${WATER_PARTICLE_CELL_SHARE}.0 * weight / total); }
-    }
-    let visibility = water_particle_visibility(share, water_particle_lot(particle));
+    let visibility = water_particle_visibility(bitcast<f32>(runs[2u * draw[2u * i] + 1u]), water_particle_lot(particle));
     visible[i] = visibility;
-    if (!(visibility > 0.0)) {
-        for (var corner = 0u; corner < ${WATER_PARTICLE_CORNERS}u; corner++) { slots[i * ${WATER_PARTICLE_CORNERS}u + corner] = ~0u; }
-        return;
-    }
+    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;
@@ -393,6 +756,7 @@ scatter_resources.createGroup()
     .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. */
@@ -402,7 +766,9 @@ export const shader_water_particles_scatter = ComputeShader.from({ label: 'Water
 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 particle = next.elements[i];
+    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];
@@ -424,6 +790,7 @@ 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);
 
@@ -444,7 +811,9 @@ fn water_entry_before(a: ${WATER_PARTICLE_ENTRY_STRUCT.wgsl_ref}, b: ${WATER_PAR
 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 particle = next.elements[i];
+    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];
@@ -470,6 +839,7 @@ bounds_resources.createGroup()
     .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);
 
 /**
@@ -484,7 +854,9 @@ export const shader_water_particles_bounds = ComputeShader.from({ label: 'Water
 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 particle = next.elements[i];
+    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);