@woosh/meep-engine 3.41.0 → 3.42.0

package/src/shade/device/mock/SoftwareGPUDevice.d.ts

@@ -38,10 +38,8 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase implements GPUDevic
      * @param {GPUFeatureName[]} [descriptor.requiredFeatures] optional features to enable, from
      * {@link SUPPORTED_OPTIONAL_FEATURES}. Asking for one this device cannot emulate throws, as
      * `requestDevice` rejects for one the adapter does not have.
-     * @param {Partial<GPUSupportedLimits>} [descriptor.requiredLimits] limits to report instead of
-     * the defaults. Only *worse* values are accepted — see {@link build_limits}. Lowering one is how
-     * a test reaches the clamping paths the renderer takes on a small device without allocating
-     * anything large.
+     * @param {Partial<GPUSupportedLimits>} [descriptor.requiredLimits] requested limits; worse-than-default
+     * requests preserve the defaults, and unsupported better requests are refused
      */
     constructor(descriptor?: {
         label?: string;

package/src/shade/device/mock/SoftwareGPUDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AAsQA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;;;OAUG;IACH;QAT+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAyBrC;IAzDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAmCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WA/sBa,mBAAiB,IAAI;;sCArQG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}
+{"version":3,"file":"SoftwareGPUDevice.d.ts","sourceRoot":"","sources":["../../../../../src/shade/device/mock/SoftwareGPUDevice.js"],"names":[],"mappings":"AA+QA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wEAFgB,SAAS;IAkCrB;;;;;;;;OAQG;IACH;QAP+B,KAAK,GAAzB,MAAM;QACwB,gBAAgB,GAA9C,gBAAgB;QAGyB,cAAc,GAAvD,2BAA2B;OAuBrC;IAvDD;;;;;OAKG;IACH,qCAEC;IAOD;;;;;;OAMG;IACH,iCAEC;IAiCD;;OAEG;IACH,kCAEC;IAID;;OAEG;IACH,sBAEC;IAaD;;;;;;;;OAQG;IACH,iEAUC;IAwBD;;;;;OAKG;IACH,uCAEC;IAID;;;;OAIG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,gBAcC;IAID;;;;;;;;;OASG;IACH,uBALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,uBAAuB,GAC7B,IAAI,CAIhB;IAED;;;;;OAKG;IACH,0BALW,MAAM,YACN,kCAAkC,YAClC,OAAO,GAAC,oBAAoB,GAC1B,IAAI,CAIhB;IAED;;;OAGG;IACH,qBAHW,KAAK,GACH,OAAO,CAInB;IASD;;;;;;;OAOG;IACH,wCAFa,IAAI,CAUhB;IAED;;;;;;;;;OASG;IACH,iBAHa,QAAQ,mBAAiB,IAAI,CAAC,CAc1C;IAED;;;;;;;;;;;;;;OAcG;IACH,yCAFa,IAAI,CA4BhB;IAED;;;;;;;;;OASG;IACH,yDAcC;IAmJD;;;;;;OAMG;IACH,4DAcC;IAED;;;;;;OAMG;IACH,6DAEC;IAED;;;OAGG;IACH,oFAEC;IAED;;;;;;;OAOG;IACH,kEAUC;IAkCD;;;OAGG;IACH,iFAcC;IAED;;;;;;;OAOG;IACH,2EAEC;IAED;;;;;;OAMG;IACH,iFAEC;IAED;;;;;OAKG;IACH,oFAEC;IAUD;;;;;OAKG;IACH,kBAFa,MAAM,CAMlB;IAED;;;OAGG;IACH,+DAQC;IA4BD;;;OAGG;IACH,kFAEC;IAGL;;;OAGG;IACH,8BAFU,OAAO,CAE8B;;CAN9C;;;;;;;;;;;;WA7sBa,mBAAiB,IAAI;;sCA9QG,4BAA4B;kCAHhC,wBAAwB;mCASvB,yBAAyB"}

package/src/shade/device/mock/SoftwareGPUDevice.js

@@ -87,11 +87,11 @@ const LIMIT_NAMES = Object.keys(DEFAULT_LIMITS);
 /**
  * Build the limits one device reports.
  *
- * An override may only make a limit *worse*, which is the direction `requestDevice` allows to
- * succeed: asking for a limit better than the adapter supports rejects there, and granting one here
- * would let a test pass against a device no hardware offers. "Better" is larger for a `max*` limit
- * and smaller for a `min*` one — the alignment limits are minimums, and a device that permitted a
- * *smaller* alignment would hide exactly the misalignment bugs those limits exist to catch.
+ * Like `requestDevice`, requests worse than the defaults leave those defaults in place.
+ * This software device supports the default capabilities, so a better request is refused.
+ * "Better" means larger for maximum limits and smaller for minimum alignment limits.
+ *
+ * @see https://gpuweb.github.io/gpuweb/#dom-gpuadapter-requestdevice
  *
  * @param {Partial<GPUSupportedLimits>} [overrides]
  * @returns {GPUSupportedLimits} frozen, as a real one is read-only
@@ -100,13 +100,23 @@ function build_limits(overrides = {}) {
     const limits = { ...DEFAULT_LIMITS };
 
     for (const [name, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            continue;
+        }
         if (!LIMIT_NAMES.includes(name)) {
-            throw new TypeError(
-                `SoftwareGPUDevice: '${name}' is not a GPUSupportedLimits member`
+            throw new DOMException(
+                `SoftwareGPUDevice: '${name}' is not a GPUSupportedLimits member`,
+                'OperationError'
             );
         }
 
         const is_minimum = name.startsWith('min');
+        if (is_minimum && (!Number.isInteger(Math.log2(value)) || value >= 2 ** 32)) {
+            throw new DOMException(
+                `SoftwareGPUDevice: required alignment limit ${name}=${value} must be a power of two less than 2^32`,
+                'OperationError'
+            );
+        }
         const better = is_minimum
             ? value < DEFAULT_LIMITS[name]
             : value > DEFAULT_LIMITS[name];
@@ -118,7 +128,6 @@ function build_limits(overrides = {}) {
             );
         }
 
-        limits[name] = value;
     }
 
     return Object.freeze(limits);
@@ -332,10 +341,8 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
      * @param {GPUFeatureName[]} [descriptor.requiredFeatures] optional features to enable, from
      * {@link SUPPORTED_OPTIONAL_FEATURES}. Asking for one this device cannot emulate throws, as
      * `requestDevice` rejects for one the adapter does not have.
-     * @param {Partial<GPUSupportedLimits>} [descriptor.requiredLimits] limits to report instead of
-     * the defaults. Only *worse* values are accepted — see {@link build_limits}. Lowering one is how
-     * a test reaches the clamping paths the renderer takes on a small device without allocating
-     * anything large.
+     * @param {Partial<GPUSupportedLimits>} [descriptor.requiredLimits] requested limits; worse-than-default
+     * requests preserve the defaults, and unsupported better requests are refused
      */
     constructor(descriptor = {}) {
         super(descriptor);
@@ -990,4 +997,4 @@ export class SoftwareGPUDevice extends SoftwareGPUObjectBase {
  * @readonly
  * @type {boolean}
  */
-SoftwareGPUDevice.prototype.isSoftwareGPUDevice = true;
+SoftwareGPUDevice.prototype.isSoftwareGPUDevice = true;

package/src/shade/playground/skinned_blas_refit/sweep_views.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sweep_views.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/sweep_views.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AACH;IAX6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IAC4B,OAAO,UAAhC,OAAO,KAAG,IAAI;IACN,QAAQ,GAAzB,MAAM;IACa,UAAU,GAA7B,MAAM,EAAE;IACS,QAAQ,GAAzB,MAAM;IACW,OAAO,GAAxB,MAAM;IACJ,QAAQ,MAAM,CAAC,CAwG3B"}
+{"version":3,"file":"sweep_views.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/skinned_blas_refit/sweep_views.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AACH;IAX6B,QAAQ;IACC,MAAM;IAClB,KAAK;IACJ,MAAM,EAAtB,MAAM;IAC4B,OAAO,UAAhC,OAAO,KAAG,IAAI;IACN,QAAQ,GAAzB,MAAM;IACa,UAAU,GAA7B,MAAM,EAAE;IACS,QAAQ,GAAzB,MAAM;IACW,OAAO,GAAxB,MAAM;IACJ,QAAQ,MAAM,CAAC,CAyG3B"}

package/src/shade/playground/skinned_blas_refit/sweep_views.js

@@ -61,6 +61,7 @@ export async function sweep_views({
 
     const kept = {
         position: [...camera.transform.translation],
+        rotation: [...camera.transform.rotation],
         near: camera.near,
         far: camera.far,
     };
@@ -108,7 +109,7 @@ export async function sweep_views({
     }
 
     camera.transform.setTranslation(...kept.position);
-    camera.transform.lookAt(centre);
+    camera.transform.setRotation(...kept.rotation);
     camera.near = kept.near;
     camera.far = kept.far;
 

package/src/shade/playground/water_refraction/README.md

@@ -23,14 +23,12 @@ below-interface view. The grazing camera stays over the submerged floor.
 
 Water is an entity with `Water`, `MeshletGeometry` and `Transform64`. The mesh authors the outline
 and elevations, and the transform places it; Level edits the transform's height. This fixture
-has a curved, coarse authored outline. Optical controls edit Water. Optional WaterWaves supplies wind
-forcing to a persistent shared GPU displacement atlas, with 128² samples per active body. The existing
-geometry BLAS bakes the authored footprint into a simulation mask when a wave row is created;
-dry samples remain zero, including holes and gaps. Vertices sample the field in local xz and move
-along local y. This primitive simulation therefore expects a surface that can be represented as a
-height field in local xz; multiple stacked surfaces sharing that domain also share its displacement.
-Calm meshes allocate no grid. The simulation uses a one-metre reference depth and
-does not infer bathymetry from the mesh. Screen reflections can be disabled while retaining the
+has a curved, coarse authored outline. Optical controls edit Water. Optional WaterWaves sets the wind:
+the body's waves are a fetch-limited JONSWAP sea over its own extent along the wind, drawn from 18
+spectral bands every body shares, plus the wave particles of its splashes, which reflect off the mesh's
+outline (`WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md`). Vertices sample both in the body's metric local
+frame and move in it; deep water is assumed, and nothing is inferred from bathymetry. A body with a
+triangle too steep to flatten onto a reference plane stays calm. Screen reflections can be disabled while retaining the
 fallback to the renderer's indirect lighting (IBL, or Brick4 when it is the active mode).
 The Newton, bounded HZB traversal, and undisplaced control modes all use the same AVBOIT path.
 The Medium select picks one of the water presets (`shade/renderer/medium/water/water_presets.js`):
@@ -162,8 +160,8 @@ tiny-loss resolve guard; existing particle, mesh and ribbon APIs remain intact.
 Water bodies occupy persistent rows in the existing scene database. Optical and component edits
 queue CPU writes; idle updates do not enumerate bodies. GPU page iteration, the existing prefix
 scan, ordered meshlet expansion and indirect draws cover the scene. A GPU reduction supplies signed
-local-y displacement bounds after each simulation update. Body frustum culling expands the authored
-bounds by those extrema before applying the GPU world transform.
+local-y and horizontal displacement bounds every frame. Body frustum culling expands the authored
+bounds by them before applying the GPU world transform.
 
 Following Far Cry 5's view-tile approach, each candidate triangle classifies its swept footprint into
 view tiles. A tile contains 16×16 cells; `settings.tessellation_pixels` sets their reference-view spacing
@@ -181,7 +179,8 @@ against the view planes. Calm bodies project the authored triangles directly. Re
 when displacement can bring them into view. Opaque depth is tested after displacement, so an
 undisplaced depth rejection cannot hide a crest. Both surface passes share the same patch counts
 and reconstruction inputs. Simulation is independent of camera position and render resolution;
-wave dispatch count depends on fixed steps, not the number of bodies. Device buffer and indirect
+the spectral bands cost the same for any number of bodies, and particles are dispatched from their
+GPU count. Device buffer and indirect
 draw limits still bound scene complexity. If the reference is coplanar with the camera, it moves
 farther beyond the displacement envelope to retain a projectable surface. The body's conservative
 swept span sets one shared grid spacing, at least the requested pixel spacing. This bounds each

package/src/shade/playground/water_refraction/main.js

@@ -25,11 +25,12 @@ import { ParticipatingMediaVolume } from "../../renderer/volumetrics/Participati
 import { water_medium_preset } from "../../renderer/medium/water/water_presets.js";
 import { water_finalize_shader_brick4, water_finalize_shader_ibl, water_shader } from "../../renderer/water/shader_water.js";
 import * as water_shaders from "../../renderer/water/shader_water_avboit.js";
-import { shader_water_bodies_derive } from "../../renderer/water/medium/shader_water_bodies_derive.js";
-import { shader_water_meshlet_counts, shader_water_meshlets_expand } from "../../renderer/water/medium/shader_water_meshlets.js";
-import { shader_water_wave_batch, shader_water_wave_batch_finish } from "../../renderer/water/surface/shader_water_wave_batch.js";
-import { shader_water_wave_domain, shader_water_wave_bounds } from "../../renderer/water/surface/shader_water_wave_domain.js";
-import { shader_water_tiles } from "../../renderer/water/surface/shader_water_tiles.js";
+import { shader_water_meshlets_expand } from "../../renderer/water/medium/shader_water_meshlets.js";
+import * as spectrum_shaders from "../../renderer/water/surface/spectrum/shader_water_spectrum.js";
+import * as particle_shaders from "../../renderer/water/surface/particles/shader_water_particles.js";
+import * as cull_shaders from "../../renderer/water/surface/shader_water_cull.js";
+import * as lod_shaders from "../../renderer/water/surface/lod/shader_water_lod.js";
+import { shader_water_waves_combine } from "../../renderer/water/surface/shader_water_waves_combine.js";
 import { install_profile_hotkey } from "../profile_hotkey.js";
 import { build_world } from "./world.js";
 
@@ -164,9 +165,9 @@ async function main() {
         if(!ready)return;
         const device=graphics.renderer.graphics.device,errors=[];
         for(const shader of [water_shader,water_finalize_shader_ibl,water_finalize_shader_brick4,
-            ...[shader_water_bodies_derive,shader_water_meshlet_counts,shader_water_meshlets_expand,
-                shader_water_wave_batch,shader_water_wave_batch_finish,shader_water_wave_domain,shader_water_wave_bounds,
-                shader_water_tiles,...Object.values(water_shaders)].map(s=>s.descriptor)]){
+            ...[shader_water_meshlets_expand,shader_water_waves_combine,...Object.values(spectrum_shaders),
+                ...Object.values(particle_shaders),...Object.values(cull_shaders),...Object.values(lod_shaders),
+                ...Object.values(water_shaders)].map(s=>s?.descriptor)]){
             if(typeof shader?.source!=="string")continue;
             const module=device.createShaderModule({code:shader.source});const info=await module.getCompilationInfo();
             errors.push(...info.messages.filter(m=>m.type==="error").map(m=>`${m.lineNum}: ${m.message}`));

package/src/shade/playground/water_refraction/world.js

@@ -93,7 +93,7 @@ export async function build_world(dataset) {
         water_normals[i]=0;water_normals[i+1]=1;water_normals[i+2]=0;
     }
     const water_geometry=meshlets(water_plane),water_transform=pose(16,0,16);
-    // the primitive wave simulation's forcing; the overlapping second body below has none and stays calm
+    // the wind that raises its waves; the overlapping second body below has none and stays calm
     const waves=new WaterWaves();
     const water_entity=build(new Entity().add(water).add(waves).add(water_geometry).add(water_transform));
     const add_mesh=(geo,m,x,y,z,rotation)=>{

package/src/shade/playground/water_surface/README.md

@@ -0,0 +1,43 @@
+# Water / surface
+
+One scene, four bodies of water, from a cup to an ocean: the surface simulation of
+`WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md` at every scale it has to work at.
+
+| Stop | Body | Mesh | Wind | What to look for |
+|---|---|---|---|---|
+| Cup | 4 cm of tea on a table | a 32-segment disk | 2 m/s | centimetre ripples at most; a click rings the cup and the wall sends it back |
+| Puddle | 2 m across, 1 cm deep | a wobbly disk | 4 m/s | rain (the checkbox) is the point here: rings of a few millimetres that die within a second |
+| Lake | 120 × 60 m in a basin | its outline only | 6 m/s | short wind waves over the checkered bed; splashes reflect off the shore at 0.3 |
+| Ocean | 5 km disk round an island hole | an annulus | 10 m/s, 200 km of sea upwind | swell; the island's outline reflects particles |
+
+Every body is an ordinary entity: `Water` + `WaterWaves` + `MeshletGeometry` + `Transform64`. The meshes
+author outlines; the surface's detail comes from the waves. Nothing in the scene is specific to its scale: the
+wind and the fetch set each body's spectrum (fetch-limited JONSWAP over the body's extent along the wind,
+plus `upwindFetch`), and all four share the same 18 spectral bands and one wave-particle pool.
+
+## Controls
+
+- **Scale** buttons move the camera and set its near and far planes for the stop.
+- **Wind ×** scales every body's own wind speed; **Direction** turns all of them. A change of direction
+  turns the waves over four seconds.
+- **Click** the water to splash it, with a radius suited to the stop and the **Kick** speed. **Rain** drops
+  splashes on the current stop's body at the chosen rate.
+- **Measure GPU** records 2.5 s of frames and lists the surface passes in µs per frame. **Profile (T)**
+  saves a full `.sgpt` capture.
+
+## What it shows and what it does not
+
+The floors under the water are checkered so refraction shows the slopes without a sky. The page asks for the
+default octahedral sky (`/test_assets/environments/octahedral/rustig_koppie_puresky_2k.hdr`); without it,
+reflections show the procedural sky only, and the ocean, seen from above its deep water, reads dark and flat
+except where it refracts the island's slope.
+
+The ocean stop puts the camera 9 m above the sea; at the wind slider's top (20 m/s) the camera is among the waves.
+The surface is cut from a distance-LOD lattice (`WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md`), so the waves
+near the camera keep their cells however tall they are.
+
+Measured on an RTX 4090, 1058 × 746 (headless Chrome, 2026-10-06), the ocean at 20 m/s from 9 m, with a fixed load
+holding the GPU's clocks: culling 17 µs, band spectrum 30 µs (the bands the view can draw), bounds 7 µs, lattice passes
+232 µs and scans 61 µs for 2,820 patches, 176,000 interior and 146,000 boundary cells; the two surface passes 1.06 and
+1.50 ms, of which ~0.25 ms each shades the waves too short for the cells per pixel. Bodies out of view cost one culling thread each: 4,000 added under 2 µs. The GPU lowers its clocks on a light
+frame, so time a pass against another setting in the same capture, or with a fixed load beside it.

package/src/shade/playground/water_surface/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Water · surface at every scale</title>
+<style>
+:root{color-scheme:dark;font:14px/1.45 system-ui,sans-serif;color:#d6e4ea;background:#10161b}*{box-sizing:border-box}
+body{margin:0;display:grid;grid-template-columns:minmax(0,1fr) 320px;grid-template-rows:minmax(0,1fr);height:100vh;overflow:hidden}
+#viewport{min-width:0;min-height:0;overflow:hidden;position:relative;outline:none}#viewport canvas{width:100%;height:100%}
+aside{padding:20px;overflow:auto;border-left:1px solid #2d3a42;background:#151e25}h1{font-size:20px;margin:0 0 6px}h2{font-size:13px;color:#8cb9bf;text-transform:uppercase;letter-spacing:.07em;margin:22px 0 9px}
+p{margin:8px 0;color:#9faeb9;font-size:12px}label{display:flex;align-items:center;justify-content:space-between;gap:8px;margin:8px 0}
+input[type=range]{width:130px}input,select,button{font:inherit;background:#202d36;border:1px solid #3c505e;border-radius:5px;color:#e2edf0;padding:5px}button{cursor:pointer}button:hover{background:#304753}
+.row{display:flex;gap:6px;flex-wrap:wrap}pre{white-space:pre-wrap;overflow-wrap:anywhere;font:11px/1.5 monospace;color:#8bd3d5;background:#0c151b;padding:10px;border-radius:5px}
+#status{border-left:3px solid #70b8b5;padding:10px;font-size:12px;background:#1d2c32}#badge{position:absolute;top:16px;left:16px;pointer-events:none;background:#13242cd9;padding:8px 12px;border-radius:5px;color:#c7eff0;font-size:12px}
+</style></head>
+<body tabindex="0"><div id="viewport" tabindex="0"><div id="badge">Drag to orbit · wheel to zoom · click the water to splash</div></div>
+<aside><h1>Water / surface</h1><p>One spectrum and one particle pool for a cup, a puddle, a lake and an ocean.</p><div id="status">Starting renderer…</div>
+<h2>Scale</h2>
+<div class="row"><button class="stop" data-stop="cup">Cup</button><button class="stop" data-stop="puddle">Puddle</button><button class="stop" data-stop="lake">Lake</button><button class="stop" data-stop="ocean">Ocean</button><button class="stop" data-stop="aerial">Ocean, aerial</button></div>
+<h2>Wind</h2>
+<label>Wind × each body's own<input id="wind" type="range" min="0" max="2" step=".05" value="1"></label>
+<label>Direction °<input id="direction" type="range" min="0" max="360" step="1" value="30"></label>
+<pre id="winds"></pre>
+<h2>Splashes</h2>
+<label>Kick m/s<input id="kick" type="range" min="0.1" max="4" step=".1" value="1.5"></label>
+<label>Rain on this body<input id="rain" type="checkbox"></label>
+<label>Drops per second<input id="rate" type="range" min="1" max="200" step="1" value="40"></label>
+<div class="row"><button id="pause">Pause</button><button id="measure">Measure GPU</button><button id="profile">Profile (T)</button></div>
+<pre id="report">Measure records 2.5 s of frames and lists the surface passes, µs per frame.</pre>
+</aside>
+<script type="module" src="./main.js"></script>
+</body></html>

package/src/shade/playground/water_surface/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/src/shade/playground/water_surface/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_surface/main.js"],"names":[],"mappings":""}

package/src/shade/playground/water_surface/main.js

@@ -0,0 +1,154 @@
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { Entity } from "../../../engine/ecs/Entity.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+import { GraphicsEngine } from "../../../engine/graphics3/GraphicsEngine.js";
+import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
+import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
+import { WaterSystem } from "../../../engine/graphics3/WaterSystem.js";
+import { GPUProfileLevel } from "../../device/timing/profile/GPUProfileLevel.js";
+import { GPUProfileSession } from "../../device/timing/profile/GPUProfileSession.js";
+import { sgpt_read_capture } from "../../device/timing/profile/sgpt_read_capture.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { load_default_environment } from "../load_default_environment.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { build_world } from "./world.js";
+
+const element = id => document.getElementById(id);
+const number = id => Number(element(id).value);
+
+/** Where each stop looks from, its near and far planes, and the splash and raindrop radii there. */
+const STOPS = {
+    cup: { body: 'cup', eye: [0.16, 0.98, 0.16], target: [0, 0.83, 0], near: 0.003, far: 400, splash: 0.005, drop: 0.002 },
+    puddle: { body: 'puddle', eye: [5.0, 0.9, 2.3], target: [4, 0, 1], near: 0.02, far: 2000, splash: 0.03, drop: 0.004 },
+    lake: { body: 'lake', eye: [22, 4, 188], target: [0, -1, 166], near: 0.1, far: 6000, splash: 0.3, drop: 0.01 },
+    ocean: { body: 'ocean', eye: [0, 9, 5000 + 150], target: [25, 0, 5000 + 230], near: 0.2, far: 12000, splash: 3, drop: 0.02 },
+    aerial: { body: 'ocean', eye: [700, 320, 4300], target: [0, 0, 5000], near: 0.5, far: 12000, splash: 3, drop: 0.02 },
+};
+
+async function main() {
+    const viewport = element("viewport"), graphics = new GraphicsEngine(), scene = new Scene();
+    viewport.appendChild(graphics.viewport.el);
+    const dataset = new EntityComponentDataset(), entities = new EntityManager();
+    const water_system = new WaterSystem(graphics, scene);
+    entities.addSystem(new ShadedGeometrySystem(graphics, scene));
+    entities.addSystem(new LightSystem(graphics, scene));
+    entities.addSystem(water_system);
+    entities.attachDataset(dataset);
+    await new Promise((resolve, reject) => entities.startup(resolve, reject));
+    const world = await build_world(dataset);
+    load_default_environment(scene);
+
+    const sun = new Light(); sun.intensity.set(2.4);
+    const sun_pose = new Transform64(), rotation = new Quaternion();
+    // low and ahead of the views, so its glitter path shows the slopes
+    rotation.fromUnitVectors(Vector3.forward, new Vector3(-0.15, -0.3, -0.94).normalize());
+    sun_pose.setRotation(rotation.x, rotation.y, rotation.z, rotation.w); sun_pose.updateMatrix();
+    new Entity().add(sun).add(sun_pose).build(dataset);
+
+    const camera = graphics.camera.camera, controller = new OrbitalCameraController(camera, viewport);
+    camera.fov = Math.PI / 3;
+    let stop = STOPS.cup;
+    function go(name) {
+        stop = STOPS[name];
+        camera.near = stop.near; camera.far = stop.far;
+        controller.look(new Vector3(...stop.eye), new Vector3(...stop.target));
+        for (const button of document.querySelectorAll("button.stop")) { button.style.borderColor = button.dataset.stop === name ? "#8dd3db" : ""; }
+    }
+    function configure() {
+        const lines = [];
+        for (const [name, body] of Object.entries(world.bodies)) {
+            body.waves.windSpeed.set(body.base_wind * number("wind"));
+            body.waves.windDirection.set(number("direction") * Math.PI / 180);
+            lines.push(`${name.padEnd(7)} ${(body.base_wind * number("wind")).toFixed(1)} m/s${body.waves.upwindFetch.getValue() > 0 ? `, ${body.waves.upwindFetch.getValue() / 1000} km of sea upwind` : ''}`);
+        }
+        element("winds").textContent = lines.join("\n");
+    }
+    const report = message => { element("status").textContent = message; };
+    for (const id of ["wind", "direction"]) { element(id).addEventListener("input", configure); }
+    for (const button of document.querySelectorAll("button.stop")) { button.onclick = () => go(button.dataset.stop); }
+    configure(); go("cup");
+
+    // a click splashes where its ray meets the stop's body at rest
+    const inverse = new Float64Array(16);
+    function splash_at(u, v, radius) {
+        const body = world.bodies[stop.body];
+        if (!m4_invert(inverse, camera.view_projection_matrix)) { return; }
+        const unproject = z => {
+            const x = 2 * u - 1, y = 1 - 2 * v;
+            const w = inverse[3] * x + inverse[7] * y + inverse[11] * z + inverse[15];
+            return [0, 1, 2].map(i => (inverse[i] * x + inverse[4 + i] * y + inverse[8 + i] * z + inverse[12 + i]) / w);
+        };
+        const near = unproject(1), far = unproject(0.5);
+        const direction = far.map((value, i) => value - near[i]);
+        if (Math.abs(direction[1]) < 1e-9) { return; }
+        const t = (body.level - near[1]) / direction[1];
+        if (!(t > 0)) { return; }
+        water_system.splash(body.entity, near.map((value, i) => value + direction[i] * t), radius, number("kick"));
+    }
+    viewport.addEventListener("click", event => {
+        const rect = viewport.getBoundingClientRect();
+        splash_at((event.clientX - rect.left) / rect.width, (event.clientY - rect.top) / rect.height, stop.splash);
+    });
+
+    let paused = false, ready = false, rain_debt = 0;
+    element("pause").onclick = () => { paused = !paused; element("pause").textContent = paused ? "Resume" : "Pause"; };
+    graphics.on.contextFailed.add(error => report(error.message));
+    graphics.on.contextLost.add(error => { ready = false; report(`GPU device lost · ${error.message}`); });
+    await graphics.start();
+    const renderer = graphics.renderer;
+    renderer.graphics.device.addEventListener("uncapturederror", event => { ready = false; report(event.error.message); console.error(event.error.message); });
+    const profile = install_profile_hotkey({ renderer, name: "water_surface", status: element("status"), target: viewport,
+        settings: () => [stop.body, `wind × ${number("wind")}`, element("rain").checked ? `rain ${number("rate")}/s` : 'no rain'] });
+    element("profile").onclick = () => profile.toggle().catch(error => report(error.message));
+
+    element("measure").onclick = async () => {
+        element("report").textContent = "recording…";
+        const session = new GPUProfileSession({ level: GPUProfileLevel.WORKLOAD, note: 'water_surface measure' });
+        renderer.profile_session = session; session.start();
+        await new Promise(resolve => setTimeout(resolve, 2500));
+        renderer.profile_session = null;
+        const bytes = await session.stop();
+        const capture = sgpt_read_capture(bytes instanceof ArrayBuffer ? bytes : bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+        const sums = new Map();
+        let frames = 0, total = 0;
+        for (const frame of capture.frames) {
+            if (!frame.spans || frame.spans.length === 0) { continue; }
+            frames++;
+            for (const span of frame.spans) {
+                total += span.duration_ns;
+                if (!/^Water \/ (spectrum|waves|particles|classify)/.test(span.label)) { continue; }
+                sums.set(span.label, (sums.get(span.label) ?? 0) + span.duration_ns);
+            }
+        }
+        const rows = [...sums.entries()].sort((a, b) => b[1] - a[1]);
+        const surface = rows.reduce((sum, [, ns]) => sum + ns, 0);
+        element("report").textContent = [`${frames} frames · every pass ${(total / frames / 1000).toFixed(0)} µs · surface ${(surface / frames / 1000).toFixed(1)} µs`,
+            ...rows.map(([label, ns]) => `${(ns / frames / 1000).toFixed(1).padStart(7)}  ${label.replace('Water / ', '')}`)].join("\n");
+    };
+
+    ready = true; report("Ready · click the water to splash");
+    Object.assign(globalThis, { graphics, scene, dataset, entities, world, water_system, camera, controller,
+        water_surface_playground: { go, splash_at, get ready() { return ready; } } });
+
+    create_frame_loop(raw_dt => {
+        if (!ready) { return; }
+        const dt = paused ? 0 : Math.min(raw_dt, 0.05);
+        if (element("rain").checked && dt > 0) {
+            rain_debt += number("rate") * dt;
+            for (; rain_debt >= 1; rain_debt--) { splash_at(Math.random(), 0.3 + 0.7 * Math.random(), stop.drop); }
+        }
+        graphics.viewport.size.set(Math.max(1, viewport.clientWidth), Math.max(1, viewport.clientHeight));
+        controller.update();
+        entities.update(dt);
+        graphics.render(dt);
+    }, 60);
+}
+
+main().catch(error => { console.error(error); element("status").textContent = error.message; });

package/src/shade/playground/water_surface/world.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Four bodies of water, from a cup to an ocean, each a `Water` + `WaterWaves` entity whose mesh authors
+ * only its outline: the surface's detail comes from the waves, at any scale.
+ */
+export function build_world(dataset: any): Promise<{
+    bodies: {
+        cup: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        puddle: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        lake: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+        ocean: {
+            entity: any;
+            water: Water;
+            waves: WaterWaves;
+            transform: Transform64;
+            level: any;
+            base_wind: any;
+        };
+    };
+}>;
+import Water from "../../../engine/graphics/ecs/water/Water.js";
+import WaterWaves from "../../../engine/graphics/ecs/water/WaterWaves.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+//# sourceMappingURL=world.d.ts.map

package/src/shade/playground/water_surface/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/water_surface/world.js"],"names":[],"mappings":"AAsGA;;;GAGG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDC;kBA3JiB,6CAA6C;uBACxC,kDAAkD;4BAH7C,8CAA8C"}