@woosh/meep-engine 3.42.0 → 3.44.0

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

@@ -1,5 +1,8 @@
 import { assert } from "../../../../../core/assert.js";
-import { graph_prefix_scan_csdldf } from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
 import {
     build_indirect_compute_dispatch_command,
     INDIRECT_COMPUTE_COMMAND_DESCRIPTOR
@@ -10,15 +13,23 @@ import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PART
 import {
     shader_water_particles_bin,
     shader_water_particles_bounds,
+    shader_water_particles_clear,
     shader_water_particles_emit,
     shader_water_particles_finalize,
+    shader_water_particles_fronts,
+    shader_water_particles_groups,
+    shader_water_particles_nest,
     shader_water_particles_rank,
+    shader_water_particles_runs,
     shader_water_particles_scatter,
+    shader_water_particles_share,
     shader_water_particles_split,
     shader_water_particles_total,
     shader_water_particles_update,
     shader_water_particles_weigh,
-    WATER_PARTICLE_CORNERS
+    WATER_PARTICLE_CORNERS,
+    WATER_PARTICLE_CROWD_WORDS,
+    WATER_PARTICLE_NEST_WORDS
 } from "./shader_water_particles.js";
 
 /** The longest step a particle takes in one frame, seconds: a stalled tab does not fling fronts across a lake. */
@@ -45,10 +56,18 @@ export class GPUWaterParticles {
     #parity = 0;
     #particles = [];
     #children = null;
+    #child_sums = null;
+    #images = null;
+    #fronts = null;
+    #front_sums = null;
+    #runs = null;
+    #draw = null;
     #buckets = null;
+    #offsets = null;
     #slots = null;
     #bucket_amplitude = null;
     #bucket_weight = null;
+    #bucket_nest = null;
     #visible = null;
     #staging = null;
     #entries = null;
@@ -56,7 +75,7 @@ export class GPUWaterParticles {
     #commands = null;
 
     /** @returns {GPUBuffer} the frame's hash: table size, then inclusive bucket offsets */
-    get offsets() { return this.#buckets; }
+    get offsets() { return this.#offsets; }
     /** @returns {GPUBuffer} the frame's entries, bucket by bucket, each bucket ordered by particle */
     get entries() { return this.#entries; }
     /** @returns {GPUBuffer} per wave row: occupied-level mask, then a height bound per level (f32 bits) */
@@ -89,16 +108,33 @@ export class GPUWaterParticles {
                 size: Math.max(16, size), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | usage });
             const array_size = 16 + capacity * WATER_PARTICLE_STRUCT.size;
             this.#particles = [buffer('a', array_size), buffer('b', array_size)];
+            // a scan reads one buffer and writes another: per particle how many it leaves, then where they end
+            const sums = elements => prefix_scan_csdldf_output_descriptor(elements).size;
             this.#children = buffer('children', 16 + capacity * 4);
+            this.#child_sums = buffer('child sums', sums(capacity));
+            // per particle the mirror image the step left beside it at the outline
+            this.#images = buffer('images', capacity * WATER_PARTICLE_STRUCT.size);
+            // per particle whether it starts a run, then the scanned run it is in; per run its first particle and its
+            // share; per particle its run and how it is drawn
+            this.#fronts = buffer('fronts', 16 + capacity * 4);
+            this.#front_sums = buffer('front sums', sums(capacity));
+            this.#runs = buffer('runs', capacity * 8);
+            this.#draw = buffer('draw', capacity * 8);
+            // per bucket its entries, then the hash: table size and inclusive offsets
             this.#buckets = buffer('buckets', 16 + this.#table_limit * 4);
+            this.#offsets = buffer('offsets', sums(this.#table_limit));
             this.#slots = buffer('slots', capacity * WATER_PARTICLE_CORNERS * 4);
             this.#bucket_amplitude = buffer('bucket amplitude', this.#table_limit * 4);
-            this.#bucket_weight = buffer('bucket weight', this.#table_limit * 4);
+            // the summed steepness, the largest front and front complement entered, and the entries; then the most a point
+            // under it reads, and its entries by key
+            this.#bucket_weight = buffer('bucket weight', this.#table_limit * WATER_PARTICLE_CROWD_WORDS * 4);
+            this.#bucket_nest = buffer('bucket nest', this.#table_limit * WATER_PARTICLE_NEST_WORDS * 4);
             this.#visible = buffer('visible', capacity * 4);
             const entries = capacity * WATER_PARTICLE_CORNERS * WATER_PARTICLE_ENTRY_STRUCT.size;
             this.#staging = buffer('staging', entries);
             this.#entries = buffer('entries', entries);
-            this.#commands = [0, 1].map(i => device.createBuffer({ label: `Water / particles command ${i}`,
+            // the particles' this frame and next, and the clear of the frame's table
+            this.#commands = [0, 1, 2].map(i => device.createBuffer({ label: `Water / particles command ${i}`,
                 size: INDIRECT_COMPUTE_COMMAND_DESCRIPTOR.size, usage: INDIRECT_COMPUTE_COMMAND_DESCRIPTOR.usage }));
             this.#rows = 0;
             this.#parity = 0;
@@ -121,11 +157,16 @@ export class GPUWaterParticles {
     }
 
     dispose() {
-        for (const buffer of [...this.#particles, this.#children, this.#buckets, this.#slots, this.#bucket_amplitude,
-            this.#bucket_weight, this.#visible, this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) { buffer?.destroy(); }
+        for (const buffer of [...this.#particles, this.#children, this.#child_sums, this.#images, this.#fronts, this.#front_sums, this.#runs,
+            this.#draw, this.#buckets, this.#offsets, this.#slots, this.#bucket_amplitude, this.#bucket_weight, this.#bucket_nest, this.#visible,
+            this.#staging, this.#entries, this.#body_bounds, ...(this.#commands ?? [])]) {
+            buffer?.destroy();
+        }
         this.#particles = [];
-        this.#children = this.#buckets = this.#slots = this.#bucket_amplitude = this.#staging = this.#entries = null;
-        this.#bucket_weight = this.#visible = null;
+        this.#children = this.#child_sums = this.#images = this.#buckets = this.#offsets = this.#slots = this.#bucket_amplitude = null;
+        this.#staging = this.#entries = null;
+        this.#fronts = this.#front_sums = this.#runs = this.#draw = null;
+        this.#bucket_weight = this.#bucket_nest = this.#visible = null;
         this.#body_bounds = null;
         this.#commands = null;
         this.#device = null;
@@ -158,10 +199,14 @@ export class GPUWaterParticles {
         // a frame that does not step bins the particles where they are
         const next = stepping ? this.#particles[1 - this.#parity] : current;
         if (stepping) { this.#parity = 1 - this.#parity; }
-        const [command_current, command_next] = this.#commands;
+        const [command_current, command_next, command_table] = this.#commands;
         const geometries = scene.geometries;
         let children = graph_import_buffer(graph, this.#children, 'Water / particle children');
+        let child_sums = graph_import_buffer(graph, this.#child_sums, 'Water / particle child sums');
         let buckets = graph_import_buffer(graph, this.#buckets, 'Water / particle buckets');
+        let offsets = graph_import_buffer(graph, this.#offsets, 'Water / particle offsets');
+        let fronts = graph_import_buffer(graph, this.#fronts, 'Water / particle fronts');
+        let front_sums = graph_import_buffer(graph, this.#front_sums, 'Water / particle front sums');
         const node = (name, execute, reads, writes) => {
             const data = {};
             const pass = graph.add(name, data, (d, resources, context) => execute(resources, context, d));
@@ -177,52 +222,70 @@ export class GPUWaterParticles {
                 encoder.copyBufferToBuffer(current, 0, this.#children, 0, 4);
                 build_indirect_compute_dispatch_command(64, encoder, current, 0, command_current, 0, true);
                 shader_water_particles_update.dispatchIndirect({ encoder, command: command_current, bindings: {
-                    frame: { dt: step, capacity }, particles: current, children: this.#children, activity,
+                    frame: { dt: step, capacity }, particles: current, children: this.#children, images: this.#images, activity,
                     scene_database: scene.scene_database_buffer, geometries: geometries.buffer_metadata,
                     blas_lookup: geometries.blas.buffer_metadata, blas_data: geometries.blas.buffer_data,
                     meshlet_metadata: geometries.meshlets.buffer_metadata, meshlet_data: geometries.meshlets.buffer_data,
                 } });
             }, {}, { children }).children;
-            children = graph_prefix_scan_csdldf({ graph, data: children, element_max_count: capacity });
+            child_sums = graph_prefix_scan_csdldf({ graph, input: children, output: child_sums, element_max_count: capacity });
 
             // What they leave into the next array, then the frame's splashes after them.
             node('Water / particles split and emit', (resources, { encoder }) => {
                 shader_water_particles_split.dispatchIndirect({ encoder, command: command_current, bindings: {
-                    capacity, particles: current, children: this.#children, next } });
-                shader_water_particles_total.dispatch({ encoder, bindings: { capacity, children: this.#children, next } });
+                    capacity, particles: current, children: this.#child_sums, images: this.#images, next } });
+                shader_water_particles_total.dispatch({ encoder, bindings: { capacity, children: this.#child_sums, next } });
                 shader_water_particles_emit.dispatchIndirect({ encoder, command: commands, command_offset: emit_command,
                     bindings: { capacity, scene_database: scene.scene_database_buffer, emit_rows, steep, activity,
                         particle_bounds: this.#body_bounds, next } });
-                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets } });
-            }, { children }, {});
+                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets,
+                    table_command: command_table } });
+            }, { child_sums }, {});
         }
 
-        // The frame's hash: how crowded each cell is, then each particle into the cells its support overlaps as far as
-        // its crowd leaves it drawn, offsets, entries in order.
-        buckets = node('Water / particles bin', (resources, { encoder }) => {
+        // Each front's run of particles, so that a whole one is drawn as the seven it was emitted as.
+        fronts = node('Water / particles fronts', (resources, { encoder }) => {
             if (!stepping) {
                 // the table size the last stepping frame chose for these particles
-                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets } });
+                shader_water_particles_finalize.dispatch({ encoder, bindings: { limits: { capacity, table_limit }, next, offsets: this.#buckets,
+                    table_command: command_table } });
             }
             build_indirect_compute_dispatch_command(64, encoder, next, 0, command_next, 0, true);
-            encoder.clearBuffer(this.#buckets, 16, table_limit * 4);
-            encoder.clearBuffer(this.#bucket_amplitude);
-            encoder.clearBuffer(this.#bucket_weight);
+            encoder.copyBufferToBuffer(next, 0, this.#fronts, 0, 4);
+            shader_water_particles_fronts.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#fronts } });
+        }, {}, { fronts }).fronts;
+        front_sums = graph_prefix_scan_csdldf({ graph, input: fronts, output: front_sums, element_max_count: capacity });
+
+        // The frame's hash: how each particle is drawn, how crowded each cell is and so how much of each run its crowd
+        // leaves drawn, then each packet drawn into the cells its support overlaps, offsets, entries in order.
+        buckets = node('Water / particles bin', (resources, { encoder }) => {
+            const draw = this.#draw, runs = this.#runs;
+            shader_water_particles_runs.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#front_sums, runs } });
+            shader_water_particles_groups.dispatchIndirect({ encoder, command: command_next, bindings: { next, fronts: this.#front_sums, runs, draw } });
+            shader_water_particles_clear.dispatchIndirect({ encoder, command: command_table, bindings: {
+                buckets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, bucket_weight: this.#bucket_weight,
+                bucket_nest: this.#bucket_nest } });
             shader_water_particles_weigh.dispatchIndirect({ encoder, command: command_next, bindings: {
-                next, activity, offsets: this.#buckets, bucket_weight: this.#bucket_weight } });
+                next, activity, offsets: this.#buckets, draw, bucket_weight: this.#bucket_weight, body_bounds: this.#body_bounds } });
+            shader_water_particles_nest.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, draw, body_bounds: this.#body_bounds, bucket_weight: this.#bucket_weight,
+                bucket_nest: this.#bucket_nest } });
+            shader_water_particles_share.dispatchIndirect({ encoder, command: command_next, bindings: {
+                next, activity, offsets: this.#buckets, bucket_weight: this.#bucket_weight, bucket_nest: this.#bucket_nest,
+                body_bounds: this.#body_bounds, draw, runs } });
             shader_water_particles_bin.dispatchIndirect({ encoder, command: command_next, bindings: {
                 next, activity, buckets: this.#buckets, slots: this.#slots, bucket_amplitude: this.#bucket_amplitude,
-                body_bounds: this.#body_bounds, bucket_weight: this.#bucket_weight, visible: this.#visible } });
-        }, {}, { buckets }).buckets;
-        buckets = graph_prefix_scan_csdldf({ graph, data: buckets, element_max_count: table_limit });
+                body_bounds: this.#body_bounds, draw, runs, visible: this.#visible } });
+        }, { front_sums }, { buckets }).buckets;
+        offsets = graph_prefix_scan_csdldf({ graph, input: buckets, output: offsets, element_max_count: table_limit });
         node('Water / particles order and bound', (resources, { encoder }) => {
-            const bindings = { next, offsets: this.#buckets, slots: this.#slots };
+            const bindings = { next, offsets: this.#offsets, slots: this.#slots, draw: this.#draw };
             shader_water_particles_scatter.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
                 visible: this.#visible, staging: this.#staging } });
             shader_water_particles_rank.dispatchIndirect({ encoder, command: command_next, bindings: { ...bindings,
                 staging: this.#staging, entries: this.#entries } });
             shader_water_particles_bounds.dispatchIndirect({ encoder, command: command_next, bindings: { next, activity,
-                offsets: this.#buckets, bucket_amplitude: this.#bucket_amplitude, body_bounds: this.#body_bounds } });
-        }, { buckets }, {});
+                offsets: this.#offsets, bucket_amplitude: this.#bucket_amplitude, draw: this.#draw, body_bounds: this.#body_bounds } });
+        }, { offsets }, {});
     }
 }

package/src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WATER_PARTICLE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iDAeoB;AAEpB;;;;GAIG;AACH,uDAeyB;6BA/CI,sCAAsC"}
+{"version":3,"file":"WATER_PARTICLE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/WATER_PARTICLE_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,iDAoBoB;AAEpB;;;;GAIG;AACH,uDAkByB;6BAvDI,sCAAsC"}

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

@@ -10,7 +10,7 @@ import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
  * without integration error and every particle of one front shares the origin and the age.
  */
 export const WATER_PARTICLE_STRUCT = WebGPUStruct.from({
-    /** Centre of the front, or its mirror image after a reflection; metric local xz. */
+    /** Centre of the front, or the mirror image of it for a reflection; metric local xz. */
     origin: vec2f,
     /** Propagation direction, radians from local +x towards +z. */
     angle: f32,
@@ -24,6 +24,11 @@ export const WATER_PARTICLE_STRUCT = WebGPUStruct.from({
     dispersion: f32,
     /** The water_waves row of the body it lives on. */
     body: u32,
+    /**
+     * 1 once the first of its support has left its body's outline, or that of the particle it split from: its mirror
+     * image was emitted then, and it dies once the last of it has left too. 0 from emission.
+     */
+    reflected: u32,
 }, 'WaterParticle');
 
 /**
@@ -37,13 +42,16 @@ export const WATER_PARTICLE_ENTRY_STRUCT = WebGPUStruct.from({
     angle: f32,
     amplitude: f32,
     radius: f32,
-    /** Tangential window: the distance to the front's neighbouring particle. */
-    width: f32,
+    /** Half-angle of the window around the front's centre: the angle to the front's neighbouring particle. */
+    dispersion: f32,
     /** Carrier phase lag of the crests behind the envelope, radians. */
     phase: f32,
-    /** water_waves row << 4 | level */
+    /** water_waves row and level, as water_particle_key packs them */
     key: u32,
     /** Index of the particle, which orders a bucket. */
     source: u32,
-    reserved: u32,
+    /** How far the particle stands from its front's centre, metres. */
+    distance: f32,
+    /** Half the length of its envelope across its front, metres. */
+    half_length: f32,
 }, 'WaterParticleEntry');

package/src/shade/renderer/water/surface/particles/chunk_water_particle.d.ts

@@ -1,19 +1,40 @@
-/** Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 64 m. */
-export const WATER_PARTICLE_LEVELS: 16;
+/**
+ * Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 256 m, which a 2 m splash's stretched
+ * packets reach before they die.
+ */
+export const WATER_PARTICLE_LEVELS: 18;
 /** Cell size of level 0, metres. A particle sits at the smallest level whose cell is at least its support's diameter. */
 export const WATER_PARTICLE_LEVEL0_CELL: number;
+/**
+ * How fast a packet's envelope stretches as it disperses, as a fraction κ of its group speed, by its wavenumber k against
+ * k_m = √(g/(σ/ρ)), the wavenumber of the slowest crests (λ = 1.71 cm): from x = log₂(k/k_m) = -7 in steps of a quarter,
+ * held at both ends.
+ *
+ * Its half-length h, 2r when emitted, grows as h² = (2r)² + (κD/2)² over the distance D its front has travelled since:
+ * the spread of an unchirped packet's energy grows as the spread of its group speeds times time, in quadrature with
+ * where it began (Jeschke & Wojtan 2017 grow it linearly, eq. 14, its far limit). Each κ is the one whose peak
+ * √(2r/h) best matches exact linear theory, ω² = gk + (σ/ρ)k³, for the emitted packet at 5 to 225 wavelengths (FFT,
+ * worst ratio minimised): within 2% for capillary waves up to r = 8.5 mm and gravity waves from r = 6 cm, where κ
+ * tends to 1 and 0.9, and 5% from 4 cm. Between, around the slowest group speed (λ = 4.4 cm), a broad band's energy
+ * gathers at that speed and the peak falls as t^(−1/3), which no κ draws: up to 16% below r = 12 mm, 27% at 3 cm.
+ */
+export const WATER_PARTICLE_STRETCH: number[];
 /**
  * The physics of one wave particle as pure functions (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
  *
  * A particle of radius r carries a packet of wavelength 2r, k = π/r. Under the gravity–capillary
  * dispersion relation the packet's envelope travels at the group speed and its crests at the phase speed
- * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). It loses
- * amplitude at the clean-surface viscous rate 2νk² plus the surface-film rate k√(νω)/(2√2) of natural
- * water — so a raindrop's ripple is gone in a fraction of a second while a big splash crosses a bay.
+ * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). The packet holds a
+ * band of wavelengths around 2r, which the same relation moves apart: its envelope, two radii either side when emitted,
+ * stretches as it travels and its height falls to keep its energy (WATER_PARTICLE_STRETCH), as a splash's single ring
+ * becomes a widening train of ripples. It loses amplitude at the clean-surface viscous rate 2νk² plus the surface-film
+ * rate k√(νω)/(2√2) of natural water — so a raindrop's ripple is gone in a fraction of a second while a big splash
+ * crosses a bay.
  *
- * The particles of a front are W apart, W the front's arc between them; a cosine window of half-width W
- * along the front is a partition of unity over them, so the front's height is the packet's amplitude
- * whatever the spacing, and one front adds at most two particles at any point.
+ * The particles of a front are β apart in angle around its centre, and a packet's crests are arcs around that
+ * centre; a cosine window of half-angle β is a partition of unity over them at every radius, so the front's
+ * height is the packet's amplitude whatever the spacing, splitting a front changes none of it, and one front
+ * adds at most two particles at any point.
  *
  * @type {CodeChunk}
  */

package/src/shade/renderer/water/surface/particles/chunk_water_particle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_water_particle.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle.js"],"names":[],"mappings":"AAKA,sFAAsF;AACtF,uCAAwC;AAExC,yHAAyH;AACzH,gDAAkD;AAElD;;;;;;;;;;;;;;GAcG;AACH,mCAFU,SAAS,CAsH6G;0BA9ItG,uCAAuC"}
+{"version":3,"file":"chunk_water_particle.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,uCAAwC;AAKxC,yHAAyH;AACzH,gDAAkD;AAElD;;;;;;;;;;;;GAYG;AACH,8CAIE;AAKF;;;;;;;;;;;;;;;;;;GAkBG;AACH,mCAFU,SAAS,CAmN6G;0BA3QtG,uCAAuC"}

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

@@ -3,30 +3,65 @@ import { chunk_pcg3d } from "../../../shader/chunk/random/pcg/chunk_pcg3d.js";
 import { WATER_PARTICLE_ENTRY_STRUCT, WATER_PARTICLE_STRUCT } from "./WATER_PARTICLE_STRUCT.js";
 import { chunk_water_spectrum } from "../spectrum/chunk_water_spectrum.js";
 
-/** Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 64 m. */
-export const WATER_PARTICLE_LEVELS = 16;
+/**
+ * Levels of the particle hash: cell sizes 4 mm · 2^level, so supports up to 256 m, which a 2 m splash's stretched
+ * packets reach before they die.
+ */
+export const WATER_PARTICLE_LEVELS = 18;
+
+/** Bits of a hash key that hold the level, below the body's row. */
+const WATER_PARTICLE_LEVEL_BITS = Math.ceil(Math.log2(WATER_PARTICLE_LEVELS));
 
 /** Cell size of level 0, metres. A particle sits at the smallest level whose cell is at least its support's diameter. */
 export const WATER_PARTICLE_LEVEL0_CELL = 1 / 256;
 
+/**
+ * How fast a packet's envelope stretches as it disperses, as a fraction κ of its group speed, by its wavenumber k against
+ * k_m = √(g/(σ/ρ)), the wavenumber of the slowest crests (λ = 1.71 cm): from x = log₂(k/k_m) = -7 in steps of a quarter,
+ * held at both ends.
+ *
+ * Its half-length h, 2r when emitted, grows as h² = (2r)² + (κD/2)² over the distance D its front has travelled since:
+ * the spread of an unchirped packet's energy grows as the spread of its group speeds times time, in quadrature with
+ * where it began (Jeschke & Wojtan 2017 grow it linearly, eq. 14, its far limit). Each κ is the one whose peak
+ * √(2r/h) best matches exact linear theory, ω² = gk + (σ/ρ)k³, for the emitted packet at 5 to 225 wavelengths (FFT,
+ * worst ratio minimised): within 2% for capillary waves up to r = 8.5 mm and gravity waves from r = 6 cm, where κ
+ * tends to 1 and 0.9, and 5% from 4 cm. Between, around the slowest group speed (λ = 4.4 cm), a broad band's energy
+ * gathers at that speed and the peak falls as t^(−1/3), which no κ draws: up to 16% below r = 12 mm, 27% at 3 cm.
+ */
+export const WATER_PARTICLE_STRETCH = [
+    0.9002, 0.9002, 0.8998, 0.8993, 0.8984, 0.8971, 0.8957, 0.8935, 0.8904, 0.8859, 0.8798, 0.8706, 0.8585, 0.8411, 0.8166,
+    0.7819, 0.7323, 0.6669, 0.5795, 0.461, 0.216, 0.0922, 0.064, 0.0723, 0.1089, 0.1877, 0.3427, 0.6145, 0.9295, 1.0417,
+    1.0734, 1.0739, 1.0622, 1.0469, 1.0313, 1.0175, 1.0059, 0.9969, 0.9899,
+];
+
+/** log₂(k/k_m) of the stretch table's first entry; entries are a quarter apart. */
+const WATER_PARTICLE_STRETCH_FIRST = -7;
+
 /**
  * The physics of one wave particle as pure functions (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5).
  *
  * A particle of radius r carries a packet of wavelength 2r, k = π/r. Under the gravity–capillary
  * dispersion relation the packet's envelope travels at the group speed and its crests at the phase speed
- * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). It loses
- * amplitude at the clean-surface viscous rate 2νk² plus the surface-film rate k√(νω)/(2√2) of natural
- * water — so a raindrop's ripple is gone in a fraction of a second while a big splash crosses a bay.
+ * (Jeschke & Wojtan 2017; Xue et al. 2025 give wave particles their own wavelength's dispersion). The packet holds a
+ * band of wavelengths around 2r, which the same relation moves apart: its envelope, two radii either side when emitted,
+ * stretches as it travels and its height falls to keep its energy (WATER_PARTICLE_STRETCH), as a splash's single ring
+ * becomes a widening train of ripples. It loses amplitude at the clean-surface viscous rate 2νk² plus the surface-film
+ * rate k√(νω)/(2√2) of natural water — so a raindrop's ripple is gone in a fraction of a second while a big splash
+ * crosses a bay.
  *
- * The particles of a front are W apart, W the front's arc between them; a cosine window of half-width W
- * along the front is a partition of unity over them, so the front's height is the packet's amplitude
- * whatever the spacing, and one front adds at most two particles at any point.
+ * The particles of a front are β apart in angle around its centre, and a packet's crests are arcs around that
+ * centre; a cosine window of half-angle β is a partition of unity over them at every radius, so the front's
+ * height is the packet's amplitude whatever the spacing, splitting a front changes none of it, and one front
+ * adds at most two particles at any point.
  *
  * @type {CodeChunk}
  */
 export const chunk_water_particle = CodeChunk.from(/* language=WGSL */ `
 const WATER_PARTICLE_LEVELS: u32 = ${WATER_PARTICLE_LEVELS}u;
+const WATER_PARTICLE_LEVEL_BITS: u32 = ${WATER_PARTICLE_LEVEL_BITS}u;
 const WATER_PARTICLE_LEVEL0_CELL: f32 = ${WATER_PARTICLE_LEVEL0_CELL};
+const WATER_PARTICLE_STRETCH = array<f32, ${WATER_PARTICLE_STRETCH.length}>(${WATER_PARTICLE_STRETCH.join(', ')});
+const WATER_PARTICLE_STRETCH_FIRST: f32 = ${WATER_PARTICLE_STRETCH_FIRST}.0;
 // kinematic viscosity of water, m²/s
 const WATER_VISCOSITY: f32 = 1e-6;
 const WATER_PI: f32 = 3.14159265358979;
@@ -66,7 +101,7 @@ fn water_particle_position(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> vec2<
     return particle.origin + water_particle_direction(particle.angle) * water_particle_distance(particle);
 }
 
-// The front's arc between neighbouring particles: the half-width of the tangential window.
+// The front's arc between neighbouring particles, at the particle's own radius: what the window spans there.
 fn water_particle_width(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
     return max(particle.dispersion * water_particle_distance(particle), 1e-3 * particle.radius);
 }
@@ -77,9 +112,79 @@ fn water_particle_phase(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
     return water_particle_wavenumber(particle.radius) * lag;
 }
 
-// Radius of a circle around the particle holding its whole kernel: two radii across the front, the window along it.
-fn water_particle_support(radius: f32, width: f32) -> f32 {
-    return length(vec2<f32>(2.0 * radius, width));
+// How far from a splash's centre its ring starts: two radii, the packet's half-length, so it starts clear of the centre.
+fn water_particle_launch_distance(radius: f32) -> f32 {
+    return 2.0 * radius;
+}
+
+// How fast the packet's envelope stretches, as a fraction of its group speed (WATER_PARTICLE_STRETCH): interpolated in
+// log κ between quarter octaves of k against the wavenumber of the slowest crests.
+fn water_particle_stretch(radius: f32) -> f32 {
+    let octave = log2(water_particle_wavenumber(radius) * sqrt(WATER_SURFACE_TENSION / WATER_GRAVITY));
+    let last = f32(${WATER_PARTICLE_STRETCH.length}u - 1u);
+    let t = clamp(4.0 * (octave - WATER_PARTICLE_STRETCH_FIRST), 0.0, last);
+    let i = u32(min(floor(t), last - 1.0));
+    return exp2(mix(log2(WATER_PARTICLE_STRETCH[i]), log2(WATER_PARTICLE_STRETCH[i + 1u]), t - f32(i)));
+}
+
+// Half the length of the packet's envelope across its front, for a front that stands distance from its centre: 2r when
+// emitted, growing in quadrature with half the stretch over the distance travelled since. Held to half the largest support
+// the hash holds, so a window no wider keeps the packet within the coarsest cells.
+fn water_particle_half_length_at(radius: f32, distance: f32) -> f32 {
+    let travelled = max(distance - water_particle_launch_distance(radius), 0.0);
+    let stretched = length(vec2<f32>(2.0 * radius, 0.5 * water_particle_stretch(radius) * travelled));
+    return min(stretched, 0.5 * water_particle_support_limit());
+}
+
+fn water_particle_half_length(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> f32 {
+    return water_particle_half_length_at(particle.radius, water_particle_distance(particle));
+}
+
+// Radius of a circle around the particle holding its whole kernel: the envelope's half-length h across the front, and
+// along it the front's arc of half-angle β plus its outer edge's overhang. A point at radius ρ = D + u and angle ψ from
+// a particle at distance D lies |d|² = u² + 4ρD·sin²(ψ/2) ≤ h² + (D + h)Dβ² ≤ h² + ((D + h/2)β)² from it, and
+// width ≥ Dβ.
+fn water_particle_support(half_length: f32, width: f32, dispersion: f32) -> f32 {
+    return length(vec2<f32>(half_length, width + 0.5 * half_length * dispersion));
+}
+
+// The largest support the hash holds: half its coarsest cell.
+fn water_particle_support_limit() -> f32 {
+    return 0.5 * water_particle_cell_size(WATER_PARTICLE_LEVELS - 1u);
+}
+
+// Whether two particles are of one front: one splash's, neither reflected or faded apart, alike in all but angle.
+fn water_particle_same_front(a: ${WATER_PARTICLE_STRUCT.wgsl_ref}, b: ${WATER_PARTICLE_STRUCT.wgsl_ref}) -> bool {
+    return a.body == b.body && all(a.origin == b.origin) && a.age == b.age && a.amplitude == b.amplitude
+        && a.radius == b.radius && a.dispersion == b.dispersion;
+}
+
+// How a particle is drawn, given its front's run of particles in the array and its place in it: 1 as itself; 0 not at
+// all, or a group of 3^g as one packet with 3^g times its window, when its front is whole. Whole is every particle
+// the front split into still there, in order and alike: as many as fill its circle. The step puts a particle's three
+// in its place, the middle at its own angle, so a group of 3^g is 3^g in a row and its middle stands at the angle
+// the group was emitted at; with curved crests the groups draw what the particles do. The largest group whose packet
+// the hash holds: the seven a front was emitted as, until their windows outgrow the coarsest cell.
+fn water_particle_group(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, members: u32, offset: u32) -> u32 {
+    if (members != u32(round(WATER_TAU / particle.dispersion))) { return 1u; }
+    var group = 1u;
+    for (var g = 0u; g < 20u && members % (3u * group) == 0u; g++) { group *= 3u; }
+    let distance = water_particle_distance(particle);
+    let half_length = water_particle_half_length_at(particle.radius, distance);
+    for (var g = 0u; g < 20u && group > 1u; g++) {
+        let dispersion = particle.dispersion * f32(group);
+        let width = max(dispersion * distance, 1e-3 * particle.radius);
+        if (water_particle_support(half_length, width, dispersion) <= water_particle_support_limit()) { break; }
+        group /= 3u;
+    }
+    return select(0u, group, offset % group == group / 2u);
+}
+
+// The particle as its group draws it: one packet with the group's window.
+fn water_particle_drawn(particle: ${WATER_PARTICLE_STRUCT.wgsl_ref}, group: u32) -> ${WATER_PARTICLE_STRUCT.wgsl_ref} {
+    var drawn = particle;
+    drawn.dispersion *= f32(group);
+    return drawn;
 }
 
 // The smallest hash level whose cell is at least the support's diameter, so the support overlaps at most
@@ -93,8 +198,13 @@ fn water_particle_cell_size(level: u32) -> f32 {
     return WATER_PARTICLE_LEVEL0_CELL * exp2(f32(level));
 }
 
+// A hash entry's body and level in one word.
+fn water_particle_key(body: u32, level: u32) -> u32 {
+    return (body << WATER_PARTICLE_LEVEL_BITS) | level;
+}
+
 fn water_particle_bucket(body: u32, level: u32, cell: vec2<i32>, table_size: u32) -> u32 {
-    let bits = pcg3d(vec3<u32>((body << 4u) | level, bitcast<u32>(cell.x), bitcast<u32>(cell.y)));
+    let bits = pcg3d(vec3<u32>(water_particle_key(body, level), bitcast<u32>(cell.x), bitcast<u32>(cell.y)));
     return bits.x & (table_size - 1u);
 }
 
@@ -105,39 +215,54 @@ struct WaterParticleField {
     displacement: vec2<f32>,
     // columns ∂D/∂x and ∂D/∂z: (∂Dx/∂x, ∂Dz/∂x), (∂Dx/∂z, ∂Dz/∂z)
     jacobian: mat2x2<f32>,
+    // the gradient of the displacement's signed length along the radius: the slope a quarter carrier cycle on, so that
+    // ½(|slope|² + |this|²) is the slope's mean square over a cycle
+    displacement_gradient: vec2<f32>,
 }
 
-// The packet at offset d from its particle. u across the front, v along it: envelope E(u) over two radii,
-// window T(v) over the width, carrier phase φ = πu/r − phase. Height a·E·T·cos φ; horizontal displacement
-// −a·E·T·sin φ along the direction (Gerstner-like orbits, Yuksel's longitudinal sign); with derivatives.
-fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, width: f32, phase: f32) -> WaterParticleField {
+// The packet at offset d from its particle, which stands distance from its front's centre. ρ the radius from the
+// centre and u = ρ − distance across the front, ψ the angle around the centre from the particle's direction:
+// envelope E(u) over half_length either side, window T(ψ) over the dispersion β either side, carrier phase πu/r − phase.
+// Height a·E·T·cos; horizontal displacement −a·E·T·sin along the radius (Gerstner-like orbits, Yuksel's longitudinal
+// sign); with derivatives, ∇ψ = e_ψ/ρ.
+fn water_particle_field(d: vec2<f32>, angle: f32, amplitude: f32, radius: f32, half_length: f32, dispersion: f32, distance: f32,
+    phase: f32) -> WaterParticleField {
     var field: WaterParticleField;
     let direction = water_particle_direction(angle);
     let tangent = vec2<f32>(-direction.y, direction.x);
-    let u = dot(d, direction);
-    let v = dot(d, tangent);
-    if (abs(u) >= 2.0 * radius || abs(v) >= width) { return field; }
-    let eu = 0.5 * WATER_PI * u / radius;
+    let q = d + direction * distance;
+    let rho = length(q);
+    // ρ − distance, without the cancellation
+    let u = (dot(d, d) + 2.0 * distance * dot(d, direction)) / max(rho + distance, 1e-30);
+    if (abs(u) >= half_length || !(rho > 0.0)) { return field; }
+    let psi = atan2(dot(d, tangent), distance + dot(d, direction));
+    if (abs(psi) >= dispersion) { return field; }
+    let radial = q / rho;
+    let around = vec2<f32>(-radial.y, radial.x);
+    let eu = WATER_PI * u / half_length;
     let envelope = 0.5 * (1.0 + cos(eu));
-    let envelope_du = -0.25 * WATER_PI / radius * sin(eu);
-    let tv = WATER_PI * v / width;
+    let envelope_du = -0.5 * WATER_PI / half_length * sin(eu);
+    let tv = WATER_PI * psi / dispersion;
     let window = 0.5 * (1.0 + cos(tv));
-    let window_dv = -0.5 * WATER_PI / width * sin(tv);
+    let window_dpsi = -0.5 * WATER_PI / dispersion * sin(tv);
     let carrier = WATER_PI * u / radius - phase;
     let c = cos(carrier);
     let s = sin(carrier);
     let k = WATER_PI / radius;
     let z = amplitude * envelope * window * c;
     let z_u = amplitude * window * (envelope_du * c - envelope * s * k);
-    let z_v = amplitude * envelope * window_dv * c;
+    let z_psi = amplitude * envelope * window_dpsi * c;
     let h = -amplitude * envelope * window * s;
     let h_u = -amplitude * window * (envelope_du * s + envelope * c * k);
-    let h_v = -amplitude * envelope * window_dv * s;
-    let gradient_h = h_u * direction + h_v * tangent;
+    let h_psi = -amplitude * envelope * window_dpsi * s;
+    let gradient_h = h_u * radial + (h_psi / rho) * around;
+    // the radius turns as the point moves around the centre: ∂e_ρ/∂x_j = e_ψ (e_ψ)_j / ρ
+    let turn = (h / rho) * around;
     field.height = z;
-    field.slope = z_u * direction + z_v * tangent;
-    field.displacement = h * direction;
-    field.jacobian = mat2x2<f32>(direction * gradient_h.x, direction * gradient_h.y);
+    field.slope = z_u * radial + (z_psi / rho) * around;
+    field.displacement = h * radial;
+    field.jacobian = mat2x2<f32>(radial * gradient_h.x + turn * around.x, radial * gradient_h.y + turn * around.y);
+    field.displacement_gradient = gradient_h;
     return field;
 }
 `, [chunk_water_spectrum, chunk_pcg3d, WATER_PARTICLE_STRUCT.declaration_chunk, WATER_PARTICLE_ENTRY_STRUCT.declaration_chunk]);

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.d.ts

@@ -2,7 +2,12 @@
 export const WATER_PARTICLE_FADE_SECONDS: 0.15;
 /**
  * One frame of one wave particle (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §5.1): it ages, spreads over its
- * widening front, damps, reflects off its body's authored outline, and dies or splits.
+ * widening front, damps, meets its body's authored outline, and dies or splits.
+ *
+ * At the outline the water shows the packet plus the shore's share of its mirror image in the outline (the image
+ * method, as Jeschke & Wojtan 2017 §4.4 keep a "ghost" of a reflected packet): the image is emitted the step the first
+ * of the packet's support leaves the body, and the packet carries on until the last of it has left it too. The body's
+ * outline clips what of either lies beyond it, so the water changes only as the two move.
  *
  * Whether a point is over the body is a down-ray into the body's own BLAS, so the outline is exactly the
  * authored mesh's, holes for islands included. Bindings: `geometries`, `blas_lookup`, `blas_data`,

package/src/shade/renderer/water/surface/particles/chunk_water_particle_step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAOA,qHAAqH;AACrH,+CAAgD;AAEhD;;;;;;;;;GASG;AACH,wCAFU,SAAS,CAsGsC;0BAxH/B,uCAAuC"}
+{"version":3,"file":"chunk_water_particle_step.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/water/surface/particles/chunk_water_particle_step.js"],"names":[],"mappings":"AAQA,qHAAqH;AACrH,+CAAgD;AAEhD;;;;;;;;;;;;;;GAcG;AACH,wCAFU,SAAS,CAsN8E;0BA9OvE,uCAAuC"}