@woosh/meep-engine 3.60.3 → 3.60.5

package/src/engine/graphics3/WaterSystem.js

@@ -1,734 +1,731 @@
-import { assert } from "../../core/assert.js";
-import Water from "../graphics/ecs/water/Water.js";
-import WaterWaves, { WATER_WAVES_SHORE_REFLECTION_DEFAULT } from "../graphics/ecs/water/WaterWaves.js";
-import { System } from "../ecs/System.js";
-import { EventType } from "../ecs/EventType.js";
-import { Transform64 } from "../ecs/transform/Transform64.js";
-import { TransformAttachment } from "../ecs/transform-attachment/TransformAttachment.js";
-import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
-import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
-import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.js";
-import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
-import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
-import { GPUWaterBodies } from "../../shade/renderer/water/medium/GPUWaterBodies.js";
-import { GPUWaterQueries, WATER_QUERY_SAMPLE_FLOATS } from "../../shade/renderer/water/query/GPUWaterQueries.js";
-import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
-import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
-import { GPUReadbackStatus } from "../../shade/renderer/buffer/table/GPUReadbackStatus.js";
-import { generate_record_writer } from "../../shade/renderer/buffer/table/serde/generate_record_writer.js";
-import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_RECORD_STRUCT } from "../../shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js";
-import { WATER_SPECTRUM_BAND_COUNT } from "../../shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js";
-import { GPUFluidComponent } from "../physics/fluid/ecs/GPUFluidComponent.js";
-import { GPUFluidSystem } from "./GPUFluidSystem.js";
-
-// Only the authored fields: a whole-record write would undo what the GPU derives into the row.
-const AUTHORED_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['upwind_fetch', 'shore_reflection', 'node', 'geometry', 'simulate_hidden']);
-const IMPULSE_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['impulses', 'impulse_count']);
-/** The WaterWaves fields a body's row follows. */
-const WAVE_FIELDS = ['upwindFetch', 'shoreReflection'];
-/** A splash's or query's world-to-local matrix: rain can splash hundreds of times a second. */
-const SPLASH_INVERSE = new Float64Array(16);
-
-const REQUEST_INITIAL_CAPACITY = 16;
-
-/**
- * @param {Int32Array|Uint32Array|Float32Array|Float64Array|Uint8Array} array
- * @param {number} length
- * @returns {any} `array`, or a copy of it at least `length` long
- */
-function fit(array, length) {
-    if (array.length >= length) {
-        return array;
-    }
-
-    const grown = new array.constructor(Math.max(length, 2 * array.length));
-
-    grown.set(array);
-
-    return grown;
-}
-
-/**
- * Registers [Water, MeshletGeometry, Transform64] in the scene's existing GPU database. Authored
- * edits queue writes; idle frames never walk bodies. Transform rows follow the same change events
- * and GPU hierarchy as shaded geometry. Water does not enter the opaque mesh table or its TLAS.
- *
- * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its fetch and shore from an
- * optional {@link WaterWaves}, its queued splashes, and what the GPU derives from them each frame. The GPU culls
- * every body against the frame's view before simulating; a hidden body is paused unless
- * {@link Water#simulateWhenHidden} (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3).
- *
- * **The wind is the scene's** (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row): the culling pass
- * samples the published wind field 10 m above each body's origin and low-passes it per body, on the GPU. What the
- * system decides on the CPU is only whether that field can hold wind at all ({@link GPUWaterSurface#windy}, which
- * animates the shared bands): while any enabled {@link GPUFluidComponent} steps a fluid, or the far field
- * ({@link GPUFluidSystem#far_field}) is not still. Asked every update, allocating nothing.
- */
-export class WaterSystem extends System {
-
-    /**
-     * Offer the compute pipelines the water surface query API dispatches.
-     *
-     * @param {import("../../shade/device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
-     */
-    static enquirePipelines(enquiry) {
-        GPUWaterQueries.enquirePipelines(enquiry);
-    }
-
-    dependencies = [Water, MeshletGeometry, Transform64];
-    components_used = [ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read),
-        // whether the scene's wind field has a fluid behind it
-        ResourceAccessSpecification.from(GPUFluidComponent, ResourceAccessKind.Read)];
-    #graphics;
-    #scene;
-    #context = null;
-    #renderer = new GPUWaterRenderer();
-    #waves = new GPUWaterSurface();
-    #bodies = new GPUWaterBodies();
-    #entries = new Map();
-    #dirty = new Set();
-    #impulses = new Set();
-    /** @type {GPUFluidSystem|null} the far field's source, once found */
-    #fluid = null;
-    #far = new Float64Array(3);
-    /** Whether {@link #visit_domain} met an enabled component. */
-    #enabled_found = false;
-    #visit_domain = component => {
-        if (component.enabled) { this.#enabled_found = true; return false; }
-        return true;
-    };
-    #extensions = [];
-    #time = 0;
-
-    /*
-     The surface read API: per handle, the request's entity, local xz points, count, footprint,
-     target, and status.
-    */
-    #request_entities = new Int32Array(REQUEST_INITIAL_CAPACITY);
-    #request_point_offsets = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    #request_counts = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    #request_footprints = new Float32Array(REQUEST_INITIAL_CAPACITY);
-    #request_offsets = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    /** @type {(Float32Array|null)[]} */
-    #request_targets = new Array(REQUEST_INITIAL_CAPACITY).fill(null);
-    #request_points = new Float64Array(2 * REQUEST_INITIAL_CAPACITY);
-    #request_point_count = 0;
-    #world_to_local_xz = new Float64Array(2 * REQUEST_INITIAL_CAPACITY);
-    #status = new Uint8Array(REQUEST_INITIAL_CAPACITY);
-
-    /** Recycled handles. */
-    #free_handles = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    #free_count = 0;
-
-    /** Handles below this have been handed out at least once. */
-    #fresh = 0;
-
-    /** Handles asked for and not yet answered headless or handed to the device. */
-    #asked = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    #asked_count = 0;
-
-    /** Handles that settled at the last apply point, recycled at the next. */
-    #settled = new Uint32Array(REQUEST_INITIAL_CAPACITY);
-    #settled_count = 0;
-
-    /**
-     * The read API on the device: its database, gather and readback. Made by the first frame with a
-     * request, dropped with the device.
-     *
-     * @type {GPUWaterQueries|null}
-     */
-    #queries = null;
-
-    get settings() { return this.#renderer.settings; }
-    get waves() { return this.#waves; }
-    get transparency_channel() { return this.#renderer; }
-    get scene() { return this.#scene; }
-    request_probe(uv) { return this.#renderer.request_probe(uv); }
-    get time() { return this.#time; }
-    set time(seconds) {
-        assert.ok(Number.isFinite(seconds) && seconds >= 0, 'water time must be finite and non-negative');
-        this.#time = seconds;
-    }
-
-    /**
-     * What became of each surface query request, by handle: a `GPUReadbackStatus`. `Pending` from
-     * {@link request_local} / {@link request_world} until the apply point ({@link update}) that
-     * answers it, `Delivered` (the samples are unpacked in `target`) or `Dropped` (the target is as
-     * it was) from there until the next apply point, then `None`, the handle recycled.
-     *
-     * Read it fresh each time rather than keeping a reference: the array is replaced when the
-     * handle space grows.
-     *
-     * @returns {Uint8Array}
-     */
-    get status() {
-        return this.#status;
-    }
-
-    /**
-     * The surface read API's device half, or null before the first frame with a request on a
-     * device. For inspection.
-     *
-     * @returns {GPUWaterQueries|null}
-     */
-    get queries() {
-        return this.#queries;
-    }
-
-    constructor(graphics, scene) {
-        super(); assert.defined(graphics, 'graphics'); assert.defined(scene, 'scene');
-        this.#graphics = graphics; this.#scene = scene;
-        this.#renderer.scene = scene;
-        this.#waves.onInputsConsumed.add(context => {
-            if (context !== this.#context) { return; }
-            for (const entry of this.#impulses) {
-                entry.staged.impulse_count = 0;
-                if (entry.queue.length === 0) { this.#impulses.delete(entry); }
-            }
-        });
-        this.#renderer.bodies = this.#bodies;
-        this.#renderer.waves = this.#waves;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-        assert.ok(this.#scene.dataset == null || this.#scene.dataset === entityManager.dataset, 'scene belongs to another dataset');
-        this.#scene.dataset = entityManager.dataset;
-        this.#graphics.add_transparency_channel(this.#renderer);
-        this.#extensions = [this.#graphics.add_extension(new WaterExtension(this)),
-            this.#graphics.add_extension(new WaterSurfaceExtension(this))];
-    }
-
-    async shutdown() {
-        for (const entry of Array.from(this.#entries.values())) { this.unlink(entry.water, entry.geometry, entry.transform, entry.entity); }
-        this.#drop_queries();
-        this.#graphics.remove_transparency_channel(this.#renderer);
-        for (const extension of this.#extensions) { this.#graphics.remove_extension(extension); }
-        this.#extensions.length = 0;
-        this.#renderer.dispose(); this.#waves.dispose(); this.#context = null;
-    }
-
-    link(water, geometry, transform, entity) {
-        // queue: splashes not yet staged, four numbers each (local x, z, radius, kick); staged: the batch on the
-        // GPU row until a submitted frame spends it
-        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null, queue: [],
-            staged: { impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => new Float64Array(4)), impulse_count: 0 } };
-        const dataset = this.entityManager.dataset;
-        entry.changed = () => this.#dirty.add(entry);
-        entry.world = () => entry.context?.rows.mark_world(entity);
-        entry.local = () => entry.context?.rows.mark_local(entity);
-        entry.components = ({ klass }) => {
-            if (klass === WaterWaves) { this.#watch_waves(entry); entry.changed(); }
-            if (klass === TransformAttachment) { entry.local(); }
-        };
-        water.onChanged.add(entry.changed);
-        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
-        dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
-        dataset.addEntityEventListener(entity, EventType.ComponentAdded, entry.components);
-        dataset.addEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
-        this.#entries.set(entity, entry);
-        this.#watch_waves(entry);
-        this.#dirty.add(entry);
-        this.#renderer.body_count++;
-    }
-
-    #watch_waves(entry) {
-        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
-        entry.waves = this.entityManager.dataset.getComponent(entry.entity, WaterWaves);
-        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.add(entry.changed); } }
-    }
-
-    unlink(water, geometry, transform, entity) {
-        const entry = this.#entries.get(entity);
-        if (entry === undefined) { return; }
-        const dataset = this.entityManager.dataset;
-        water.onChanged.remove(entry.changed);
-        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
-        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
-        dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
-        dataset.removeEntityEventListener(entity, EventType.ComponentAdded, entry.components);
-        dataset.removeEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
-        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
-            entry.context.scene_database.get('water_bodies').remove(entry.row);
-            entry.context.rows.release(entity);
-        }
-        this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
-        this.#renderer.body_count--;
-        if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
-    }
-
-    update(dt) {
-        this.#recycle_requests();
-        this.#time += dt; this.#renderer.time = this.#time; this.#waves.advance(dt);
-        this.#waves.windy = this.#wind_can_blow();
-        const context = this.#graphics.scene_context(this.#scene);
-        if (context === null) {
-            if (this.#context !== null || this.#queries !== null) {
-                this.#drop_queries();
-                this.#context = null;
-            }
-            this.#answer_requests(null);
-            return;
-        }
-        if (context !== this.#context) {
-            this.#drop_queries();
-            this.#context = context;
-            // Device replacement is the only whole-scene rebuild; ordinary frames drain edits.
-            for (const entry of this.#entries.values()) {
-                entry.context = null; entry.row = -1; entry.wave = -1;
-                // a batch the old context never spent goes back to the front of the queue
-                const staged = [];
-                for (let i = 0; i < entry.staged.impulse_count; i++) { staged.push(...entry.staged.impulses[i]); }
-                entry.queue.unshift(...staged); entry.staged.impulse_count = 0;
-                this.#dirty.add(entry);
-            }
-            this.#renderer.meshlet_capacity = 0;
-        }
-        for (const entry of this.#dirty) { this.#write(entry, context); }
-        this.#dirty.clear();
-        for (const entry of this.#impulses) { this.#stage(entry, context); }
-        this.#answer_requests(context);
-    }
-
-    /**
-     * Whether the scene's wind field can hold wind: an enabled {@link GPUFluidComponent} on any entity, or a far
-     * field that is not still. The lowest holder of the component answers without a walk; only when it is disabled
-     * are the others visited.
-     * @returns {boolean}
-     */
-    #wind_can_blow() {
-        const em = this.entityManager, dataset = em.dataset;
-        if (dataset !== null) {
-            const lowest = dataset.getAnyComponentInstance(GPUFluidComponent);
-            if (lowest !== null) {
-                if (lowest.enabled) { return true; }
-                this.#enabled_found = false;
-                dataset.traverseComponents(GPUFluidComponent, this.#visit_domain);
-                if (this.#enabled_found) { return true; }
-            }
-        }
-        // registered later than this system, or never
-        const fluid = this.#fluid ??= em.getSystem(GPUFluidSystem);
-        if (fluid === null) { return false; }
-        const far = this.#far;
-        fluid.far_field(far);
-        return far[0] !== 0 || far[1] !== 0 || far[2] !== 0;
-    }
-
-    /** Top up a body's batch on its surface row from its queue, up to the row's limit. */
-    #stage(entry, context) {
-        const staged = entry.staged, queue = entry.queue;
-        if (entry.wave === -1 || queue.length === 0 || staged.impulse_count === WATER_WAVE_IMPULSE_LIMIT) { return; }
-        const taken = Math.min(queue.length / 4, WATER_WAVE_IMPULSE_LIMIT - staged.impulse_count);
-        for (let i = 0; i < taken; i++) {
-            const impulse = staged.impulses[staged.impulse_count++];
-            for (let c = 0; c < 4; c++) { impulse[c] = queue[4 * i + c]; }
-        }
-        queue.copyWithin(0, 4 * taken);
-        queue.length -= 4 * taken;
-        this.#waves.splashed = true;
-        for (let i = staged.impulse_count; i < WATER_WAVE_IMPULSE_LIMIT; i++) { staged.impulses[i].fill(0); }
-        context.scene_database.get('water_waves').set_fields(entry.wave, staged, IMPULSE_WRITER);
-    }
-
-    #write(entry, context) {
-        const bodies = context.scene_database.get('water_bodies');
-        const waves = context.scene_database.get('water_waves');
-        if (entry.context === null) {
-            context.rows.acquire(entry.entity);
-            context.geometries.add(entry.geometry);
-            entry.context = context;
-            this.#renderer.meshlet_capacity += entry.geometry.meshlets.count;
-        }
-        const geometry = context.geometries.getAddress(entry.geometry);
-        if (entry.wave === -1) {
-            // the GPU seeds the wind from its first sample, and derives the weights for it
-            entry.wave = waves.add({ upwind_fetch: 0, shore_reflection: WATER_WAVES_SHORE_REFLECTION_DEFAULT,
-                impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]), impulse_count: 0,
-                node: entry.entity + 1, geometry, simulate_hidden: 0, wind: [0, 0, 0], wind_seeded: 0, derived_for: [-1, -1, 0, 0],
-                weights: new Array(WATER_SPECTRUM_BAND_COUNT).fill(0), slope_variance: 0,
-                wind_from: [0, 0], wind_to: [0, 0], wind_blend: 1, displacement_bounds: [0, 0, 0, 0], particle_levels: 0 });
-        }
-        const waves_component = entry.waves;
-        const reflection = Math.min(1, Math.max(0, waves_component?.shoreReflection.getValue() ?? WATER_WAVES_SHORE_REFLECTION_DEFAULT));
-        waves.set_fields(entry.wave, { upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), shore_reflection: reflection, node: entry.entity + 1, geometry,
-            simulate_hidden: entry.water.simulateWhenHidden.getValue() ? 1 : 0 }, AUTHORED_WRITER);
-        const water = entry.water;
-        const record = { geometry, node: entry.entity + 1,
-            dirty: 1,
-            wave: entry.wave, ior: Math.max(1, water.ior.getValue()),
-            roughness: Math.min(1, Math.max(0, water.roughness.getValue())), medium: water.medium.to_gpu_record(),
-            backscattering: [0, 0, 0, 0], extinction: [0, 0, 0, 0], diffuse_transmittance: 0 };
-        if (entry.row === -1) { entry.row = bodies.add(record); } else { bodies.set(entry.row, record); }
-    }
-
-    /**
-     * A splash at a world position: rings of wave particles of the given world radius (half their wavelength)
-     * whose height is the given vertical velocity kick, m/s, over the time a crest takes to cross them. The
-     * position is interpreted in the CPU-owned pose; queued on the CPU and spent on the GPU, sixteen a body a frame.
-     */
-    splash(entity, position, radius, strength) {
-        const entry = this.#entries.get(entity); assert.defined(entry, 'water entity');
-        assert.greaterThan(radius, 0, 'radius'); assert.isFinite(radius, 'radius'); assert.isFinite(strength, 'strength');
-        for (let i = 0; i < 3; i++) { assert.isFinite(position[i], `position[${i}]`); }
-        const inverse = SPLASH_INVERSE;
-        const inverted = m4_invert(inverse, entry.transform);
-        assert.ok(inverted, 'water transform is singular');
-        const x = inverse[0] * position[0] + inverse[4] * position[1] + inverse[8] * position[2] + inverse[12];
-        const z = inverse[2] * position[0] + inverse[6] * position[1] + inverse[10] * position[2] + inverse[14];
-        entry.queue.push(x, z, radius, strength); this.#impulses.add(entry);
-    }
-
-    /**
-     * Ask for the water surface height and world-space unit normal at `count` points in the water
-     * body's local `(x, z)` plane: `local_xz` holds `[x0, z0, x1, z1, ...]`, and each sample lands
-     * in `target` from `target_offset` as {@link WATER_QUERY_SAMPLE_FLOATS} (4) floats,
-     * `[world_height, nx, ny, nz]`, unpacked on the CPU when the request settles `Delivered` at a
-     * later apply point ({@link update}); see {@link status}.
-     *
-     * Points outside the body's authored outline or inside island holes are clamped continuously to
-     * the nearest point on the mesh's triangles so no `NaN`s are ever produced.
-     *
-     * @param {number} entity water entity
-     * @param {ArrayLike<number>} local_xz interleaved `[x0, z0, x1, z1, ...]` in local body coordinates
-     * @param {number} count number of `(x, z)` points, at least 1
-     * @param {number} footprint spatial filter footprint in metres, at least 0 (0 resolves all wavelengths)
-     * @param {Float32Array} target memory the caller owns and keeps until the request settles
-     * @param {number} target_offset in floats
-     * @returns {number} a handle into {@link status}
-     */
-    request_local(entity, local_xz, count, footprint, target, target_offset) {
-        const entry = this.#entries.get(entity);
-        assert.defined(entry, 'water entity');
-        assert.isArrayLike(local_xz, 'local_xz');
-        assert.isPositiveInteger(count, 'count');
-        assert.greaterThanOrEqual(local_xz.length, 2 * count, 'local_xz');
-        for (let i = 0; i < 2 * count; i++) {
-            assert.isFinite(local_xz[i], `local_xz[${i}]`);
-        }
-        assert.isFinite(footprint, 'footprint');
-        assert.greaterThanOrEqual(footprint, 0, 'footprint');
-        assert.ok(target instanceof Float32Array, 'target must be a Float32Array');
-        assert.isNonNegativeInteger(target_offset, 'target_offset');
-        assert.lessThanOrEqual(target_offset + WATER_QUERY_SAMPLE_FLOATS * count, target.length, 'the query samples reach past the target');
-
-        const h = this.#allocate_handle();
-        const point_start = this.#request_point_count;
-        const next_point_count = point_start + count;
-
-        if (2 * next_point_count > this.#request_points.length) {
-            this.#request_points = fit(this.#request_points, 2 * next_point_count);
-        }
-
-        const points = this.#request_points;
-
-        for (let i = 0; i < 2 * count; i++) {
-            points[2 * point_start + i] = local_xz[i];
-        }
-
-        this.#request_point_count = next_point_count;
-        this.#request_entities[h] = entity;
-        this.#request_point_offsets[h] = point_start;
-        this.#request_counts[h] = count;
-        this.#request_footprints[h] = footprint;
-        this.#request_offsets[h] = target_offset;
-        this.#request_targets[h] = target;
-        this.#status[h] = GPUReadbackStatus.Pending;
-
-        if (this.#asked_count === this.#asked.length) {
-            this.#asked = fit(this.#asked, this.#asked_count + 1);
-        }
-
-        this.#asked[this.#asked_count++] = h;
-
-        return h;
-    }
-
-    /**
-     * Ask for the water surface height and world-space unit normal at `count` points in world
-     * space: `world_xyz` holds `[x0, y0, z0, x1, y1, z1, ...]`. Internally transforms each world
-     * point into the water body's local `(x, z)` plane via the inverse of its CPU-owned
-     * `Transform64` and delegates to {@link request_local}.
-     *
-     * @param {number} entity water entity
-     * @param {ArrayLike<number>} world_xyz interleaved `[x0, y0, z0, ...]` in world metres
-     * @param {number} count number of `(x, y, z)` points, at least 1
-     * @param {number} footprint spatial filter footprint in metres, at least 0 (0 resolves all wavelengths)
-     * @param {Float32Array} target memory the caller owns and keeps until the request settles
-     * @param {number} target_offset in floats
-     * @returns {number} a handle into {@link status}
-     */
-    request_world(entity, world_xyz, count, footprint, target, target_offset) {
-        const entry = this.#entries.get(entity);
-        assert.defined(entry, 'water entity');
-        assert.isArrayLike(world_xyz, 'world_xyz');
-        assert.isPositiveInteger(count, 'count');
-        assert.greaterThanOrEqual(world_xyz.length, 3 * count, 'world_xyz');
-        for (let i = 0; i < 3 * count; i++) {
-            assert.isFinite(world_xyz[i], `world_xyz[${i}]`);
-        }
-
-        const inverse = SPLASH_INVERSE;
-        const inverted = m4_invert(inverse, entry.transform);
-        assert.ok(inverted, 'water transform is singular');
-
-        if (2 * count > this.#world_to_local_xz.length) {
-            this.#world_to_local_xz = fit(this.#world_to_local_xz, 2 * count);
-        }
-
-        const local_xz = this.#world_to_local_xz;
-
-        for (let i = 0; i < count; i++) {
-            const wx = world_xyz[3 * i];
-            const wy = world_xyz[3 * i + 1];
-            const wz = world_xyz[3 * i + 2];
-
-            local_xz[2 * i] = inverse[0] * wx + inverse[4] * wy + inverse[8] * wz + inverse[12];
-            local_xz[2 * i + 1] = inverse[2] * wx + inverse[6] * wy + inverse[10] * wz + inverse[14];
-        }
-
-        return this.request_local(entity, local_xz, count, footprint, target, target_offset);
-    }
-
-    /**
-     * @returns {number}
-     */
-    #allocate_handle() {
-        if (this.#free_count > 0) {
-            return this.#free_handles[--this.#free_count];
-        }
-
-        const h = this.#fresh++;
-
-        if (h === this.#status.length) {
-            const capacity = 2 * h;
-
-            this.#request_entities = fit(this.#request_entities, capacity);
-            this.#request_point_offsets = fit(this.#request_point_offsets, capacity);
-            this.#request_counts = fit(this.#request_counts, capacity);
-            this.#request_footprints = fit(this.#request_footprints, capacity);
-            this.#request_offsets = fit(this.#request_offsets, capacity);
-            this.#status = fit(this.#status, capacity);
-            this.#free_handles = fit(this.#free_handles, capacity);
-            this.#settled = fit(this.#settled, capacity);
-
-            for (let i = this.#request_targets.length; i < capacity; i++) {
-                this.#request_targets.push(null);
-            }
-        }
-
-        return h;
-    }
-
-    /**
-     * A request answered: its status set, readable until the next apply point.
-     *
-     * @param {number} h
-     * @param {number} status
-     */
-    #settle(h, status) {
-        this.#status[h] = status;
-        this.#request_targets[h] = null;
-        this.#settled[this.#settled_count++] = h;
-    }
-
-    /**
-     * The apply point's first half: the handles answered at the last one go back to the free list.
-     */
-    #recycle_requests() {
-        const settled = this.#settled;
-        const status = this.#status;
-        const free = this.#free_handles;
-
-        for (let i = 0; i < this.#settled_count; i++) {
-            const h = settled[i];
-
-            status[h] = GPUReadbackStatus.None;
-            free[this.#free_count++] = h;
-        }
-
-        this.#settled_count = 0;
-    }
-
-    /**
-     * The apply point's second half: what the device delivered or dropped, and, headless, every
-     * request asked since from the body's rest surface.
-     *
-     * @param {object|null} context
-     */
-    #answer_requests(context) {
-        const queries = this.#queries;
-
-        if (queries !== null) {
-            queries.apply();
-            this.#take_settled(queries);
-        }
-
-        if (context !== null || this.#asked_count === 0) {
-            return;
-        }
-
-        const asked = this.#asked;
-        const points = this.#request_points;
-
-        for (let i = 0; i < this.#asked_count; i++) {
-            const h = asked[i];
-            const entry = this.#entries.get(this.#request_entities[h]);
-
-            if (entry === undefined) {
-                this.#settle(h, GPUReadbackStatus.Dropped);
-                continue;
-            }
-
-            const m = entry.transform;
-            const inverse = SPLASH_INVERSE;
-            const inverted = m4_invert(inverse, m);
-            let nx = 0, ny = 1, nz = 0;
-            if (inverted) {
-                const rx = inverse[1], ry = inverse[5], rz = inverse[9];
-                const len = Math.hypot(rx, ry, rz);
-                if (len > 1e-20) {
-                    nx = rx / len;
-                    ny = ry / len;
-                    nz = rz / len;
-                }
-            }
-
-            const box = entry.geometry.bounding_box;
-            const mid_y = 0.5 * (box[1] + box[4]);
-            const count = this.#request_counts[h];
-            const point_base = 2 * this.#request_point_offsets[h];
-            const target = this.#request_targets[h];
-            let at = this.#request_offsets[h];
-
-            for (let k = 0; k < count; k++, at += WATER_QUERY_SAMPLE_FLOATS) {
-                const lx = Math.min(Math.max(points[point_base + 2 * k], box[0]), box[3]);
-                const lz = Math.min(Math.max(points[point_base + 2 * k + 1], box[2]), box[5]);
-                const world_y = m[1] * lx + m[5] * mid_y + m[9] * lz + m[13];
-
-                target[at] = world_y;
-                target[at + 1] = nx;
-                target[at + 2] = ny;
-                target[at + 3] = nz;
-            }
-
-            this.#settle(h, GPUReadbackStatus.Delivered);
-        }
-
-        this.#request_point_count = 0;
-        this.#asked_count = 0;
-    }
-
-    /**
-     * @param {GPUWaterQueries} queries after an apply or a destroy
-     */
-    #take_settled(queries) {
-        for (let i = 0; i < queries.settled_count; i++) {
-            this.#settle(queries.settled_tag(i), queries.settled_status(i));
-        }
-    }
-
-    /**
-     * Let go of the read API's device half: whatever it had in flight is dropped, its status set now.
-     */
-    #drop_queries() {
-        const queries = this.#queries;
-
-        if (queries === null) {
-            return;
-        }
-
-        queries.destroy();
-
-        this.#take_settled(queries);
-
-        this.#queries = null;
-    }
-
-    /**
-     * Hand the frame's requests to the device, after the frame's surface simulation passes.
-     *
-     * @param {import("../graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
-     * @param {object} scene
-     * @param {GPUDevice} device
-     */
-    #record_requests(graph, scene, device) {
-        const count = this.#asked_count;
-
-        if (count === 0) {
-            return;
-        }
-
-        let queries = this.#queries;
-
-        if (queries === null) {
-            const graphics = this.#graphics.renderer?.graphics;
-            if (graphics?.compute_pipelines !== undefined) {
-                const enquiry = { device, render: [], compute: [] };
-                WaterSystem.enquirePipelines(enquiry);
-                for (let i = 0; i < enquiry.compute.length; i++) {
-                    graphics.compute_pipelines.prepare(enquiry.compute[i]);
-                }
-            }
-            queries = this.#queries = new GPUWaterQueries({ device });
-        }
-
-        const asked = this.#asked;
-        const points = this.#request_points;
-
-        for (let i = 0; i < count; i++) {
-            const h = asked[i];
-            const entry = this.#entries.get(this.#request_entities[h]);
-
-            if (entry === undefined || entry.row === -1) {
-                this.#settle(h, GPUReadbackStatus.Dropped);
-                continue;
-            }
-
-            queries.request(
-                entry.row,
-                points,
-                2 * this.#request_point_offsets[h],
-                this.#request_counts[h],
-                this.#request_footprints[h],
-                this.#request_targets[h],
-                this.#request_offsets[h],
-                h
-            );
-        }
-
-        this.#request_point_count = 0;
-        this.#asked_count = 0;
-
-        queries.record({ graph, scene, surface: this.#waves });
-    }
-
-    record_surface(frame) {
-        const view = frame.view, scene = view.scene;
-        if (scene.scene !== this.#scene) { return; }
-        const device = this.#graphics.renderer.graphics.device;
-        this.#waves.record({ graph: frame.graph, device, scene, time: this.#time,
-            view: { camera: view.camera.gpu_buffer, projection: view.camera.camera.projection_matrix, height: view.resolution[1] },
-            pixels: this.#renderer.settings.tessellation_pixels });
-        this.#record_requests(frame.graph, scene, device);
-    }
-    record(frame) {
-        const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);
-        if (inspection !== undefined) { frame.get(SceneColor).color = inspection; }
-    }
-}
-
-export class WaterExtension extends RenderExtension {
-    name = 'water'; phase = FramePhase.BeforePresent;
-    constructor(system) { super(); this.system = system; }
-    record(frame) { this.system.record(frame); }
-}
-export class WaterSurfaceExtension extends RenderExtension {
-    name = 'water surface'; phase = FramePhase.FrameStart;
-    constructor(system) { super(); this.system = system; }
-    record(frame) { this.system.record_surface(frame); }
-}
+import { assert } from "../../core/assert.js";
+import Water from "../graphics/ecs/water/Water.js";
+import WaterWaves, { WATER_WAVES_SHORE_REFLECTION_DEFAULT } from "../graphics/ecs/water/WaterWaves.js";
+import { System } from "../ecs/System.js";
+import { EventType } from "../ecs/EventType.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { TransformAttachment } from "../ecs/transform-attachment/TransformAttachment.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
+import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.js";
+import { ResourceAccessKind } from "../../core/model/ResourceAccessKind.js";
+import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
+import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
+import { GPUWaterQueries, WATER_QUERY_SAMPLE_FLOATS } from "../../shade/renderer/water/query/GPUWaterQueries.js";
+import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
+import { m4_invert } from "../../core/geom/3d/mat4/m4_invert.js";
+import { GPUReadbackStatus } from "../../shade/renderer/buffer/table/GPUReadbackStatus.js";
+import { generate_record_writer } from "../../shade/renderer/buffer/table/serde/generate_record_writer.js";
+import { WATER_WAVE_IMPULSE_LIMIT, WATER_WAVE_RECORD_STRUCT } from "../../shade/renderer/water/surface/WATER_WAVE_RECORD_STRUCT.js";
+import { WATER_SPECTRUM_BAND_COUNT } from "../../shade/renderer/water/surface/spectrum/WATER_SPECTRUM.js";
+import { GPUFluidComponent } from "../physics/fluid/ecs/GPUFluidComponent.js";
+import { GPUFluidSystem } from "./GPUFluidSystem.js";
+
+// Only the authored fields: a whole-record write would undo what the GPU derives into the row.
+const AUTHORED_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['upwind_fetch', 'shore_reflection', 'node', 'geometry', 'simulate_hidden']);
+const IMPULSE_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['impulses', 'impulse_count']);
+/** The WaterWaves fields a body's row follows. */
+const WAVE_FIELDS = ['upwindFetch', 'shoreReflection'];
+/** A splash's or query's world-to-local matrix: rain can splash hundreds of times a second. */
+const SPLASH_INVERSE = new Float64Array(16);
+
+const REQUEST_INITIAL_CAPACITY = 16;
+
+/**
+ * @param {Int32Array|Uint32Array|Float32Array|Float64Array|Uint8Array} array
+ * @param {number} length
+ * @returns {any} `array`, or a copy of it at least `length` long
+ */
+function fit(array, length) {
+    if (array.length >= length) {
+        return array;
+    }
+
+    const grown = new array.constructor(Math.max(length, 2 * array.length));
+
+    grown.set(array);
+
+    return grown;
+}
+
+/**
+ * Registers [Water, MeshletGeometry, Transform64] in the scene's existing GPU database. Authored
+ * edits queue writes; idle frames never walk bodies. Transform rows follow the same change events
+ * and GPU hierarchy as shaded geometry. Water does not enter the opaque mesh table or its TLAS.
+ *
+ * Every body has a surface row (WATER_SURFACE_SIMULATION_PLAN_2026_10_06.md §6.1): its fetch and shore from an
+ * optional {@link WaterWaves}, its queued splashes, and what the GPU derives from them each frame. The GPU culls
+ * every body against the frame's view before simulating; a hidden body is paused unless
+ * {@link Water#simulateWhenHidden} (WATER_SURFACE_DISTANCE_LOD_PROPOSAL_2026_10_06.md §3).
+ *
+ * **The wind is the scene's** (GPU_FLUID_CASCADES_PROPOSAL_2026_10_16.md §6, the Water row): the culling pass
+ * samples the published wind field 10 m above each body's origin and low-passes it per body, on the GPU. What the
+ * system decides on the CPU is only whether that field can hold wind at all ({@link GPUWaterSurface#windy}, which
+ * animates the shared bands): while any enabled {@link GPUFluidComponent} steps a fluid, or the far field
+ * ({@link GPUFluidSystem#far_field}) is not still. Asked every update, allocating nothing.
+ */
+export class WaterSystem extends System {
+
+    /**
+     * Offer the compute pipelines the water surface query API dispatches.
+     *
+     * @param {import("../../shade/device/pipeline/PipelineEnquiry.js").PipelineEnquiry} enquiry
+     */
+    static enquirePipelines(enquiry) {
+        GPUWaterQueries.enquirePipelines(enquiry);
+    }
+
+    dependencies = [Water, MeshletGeometry, Transform64];
+    components_used = [ResourceAccessSpecification.from(WaterWaves, ResourceAccessKind.Read),
+        // whether the scene's wind field has a fluid behind it
+        ResourceAccessSpecification.from(GPUFluidComponent, ResourceAccessKind.Read)];
+    #graphics;
+    #scene;
+    #context = null;
+    #renderer = new GPUWaterRenderer();
+    #waves = new GPUWaterSurface();
+    #entries = new Map();
+    #dirty = new Set();
+    #impulses = new Set();
+    /** @type {GPUFluidSystem|null} the far field's source, once found */
+    #fluid = null;
+    #far = new Float64Array(3);
+    /** Whether {@link #visit_domain} met an enabled component. */
+    #enabled_found = false;
+    #visit_domain = component => {
+        if (component.enabled) { this.#enabled_found = true; return false; }
+        return true;
+    };
+    #extensions = [];
+    #time = 0;
+
+    /*
+     The surface read API: per handle, the request's entity, local xz points, count, footprint,
+     target, and status.
+    */
+    #request_entities = new Int32Array(REQUEST_INITIAL_CAPACITY);
+    #request_point_offsets = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #request_counts = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #request_footprints = new Float32Array(REQUEST_INITIAL_CAPACITY);
+    #request_offsets = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    /** @type {(Float32Array|null)[]} */
+    #request_targets = new Array(REQUEST_INITIAL_CAPACITY).fill(null);
+    #request_points = new Float64Array(2 * REQUEST_INITIAL_CAPACITY);
+    #request_point_count = 0;
+    #world_to_local_xz = new Float64Array(2 * REQUEST_INITIAL_CAPACITY);
+    #status = new Uint8Array(REQUEST_INITIAL_CAPACITY);
+
+    /** Recycled handles. */
+    #free_handles = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #free_count = 0;
+
+    /** Handles below this have been handed out at least once. */
+    #fresh = 0;
+
+    /** Handles asked for and not yet answered headless or handed to the device. */
+    #asked = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #asked_count = 0;
+
+    /** Handles that settled at the last apply point, recycled at the next. */
+    #settled = new Uint32Array(REQUEST_INITIAL_CAPACITY);
+    #settled_count = 0;
+
+    /**
+     * The read API on the device: its database, gather and readback. Made by the first frame with a
+     * request, dropped with the device.
+     *
+     * @type {GPUWaterQueries|null}
+     */
+    #queries = null;
+
+    get settings() { return this.#renderer.settings; }
+    get waves() { return this.#waves; }
+    get transparency_channel() { return this.#renderer; }
+    get scene() { return this.#scene; }
+    request_probe(uv) { return this.#renderer.request_probe(uv); }
+    get time() { return this.#time; }
+    set time(seconds) {
+        assert.ok(Number.isFinite(seconds) && seconds >= 0, 'water time must be finite and non-negative');
+        this.#time = seconds;
+    }
+
+    /**
+     * What became of each surface query request, by handle: a `GPUReadbackStatus`. `Pending` from
+     * {@link request_local} / {@link request_world} until the apply point ({@link update}) that
+     * answers it, `Delivered` (the samples are unpacked in `target`) or `Dropped` (the target is as
+     * it was) from there until the next apply point, then `None`, the handle recycled.
+     *
+     * Read it fresh each time rather than keeping a reference: the array is replaced when the
+     * handle space grows.
+     *
+     * @returns {Uint8Array}
+     */
+    get status() {
+        return this.#status;
+    }
+
+    /**
+     * The surface read API's device half, or null before the first frame with a request on a
+     * device. For inspection.
+     *
+     * @returns {GPUWaterQueries|null}
+     */
+    get queries() {
+        return this.#queries;
+    }
+
+    constructor(graphics, scene) {
+        super(); assert.defined(graphics, 'graphics'); assert.defined(scene, 'scene');
+        this.#graphics = graphics; this.#scene = scene;
+        this.#renderer.scene = scene;
+        this.#waves.onInputsConsumed.add(context => {
+            if (context !== this.#context) { return; }
+            for (const entry of this.#impulses) {
+                entry.staged.impulse_count = 0;
+                if (entry.queue.length === 0) { this.#impulses.delete(entry); }
+            }
+        });
+        this.#renderer.waves = this.#waves;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+        assert.ok(this.#scene.dataset == null || this.#scene.dataset === entityManager.dataset, 'scene belongs to another dataset');
+        this.#scene.dataset = entityManager.dataset;
+        this.#graphics.add_transparency_channel(this.#renderer);
+        this.#extensions = [this.#graphics.add_extension(new WaterExtension(this)),
+            this.#graphics.add_extension(new WaterSurfaceExtension(this))];
+    }
+
+    async shutdown() {
+        for (const entry of Array.from(this.#entries.values())) { this.unlink(entry.water, entry.geometry, entry.transform, entry.entity); }
+        this.#drop_queries();
+        this.#graphics.remove_transparency_channel(this.#renderer);
+        for (const extension of this.#extensions) { this.#graphics.remove_extension(extension); }
+        this.#extensions.length = 0;
+        this.#renderer.dispose(); this.#waves.dispose(); this.#context = null;
+    }
+
+    link(water, geometry, transform, entity) {
+        // queue: splashes not yet staged, four numbers each (local x, z, radius, kick); staged: the batch on the
+        // GPU row until a submitted frame spends it
+        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null, queue: [],
+            staged: { impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => new Float64Array(4)), impulse_count: 0 } };
+        const dataset = this.entityManager.dataset;
+        entry.changed = () => this.#dirty.add(entry);
+        entry.world = () => entry.context?.rows.mark_world(entity);
+        entry.local = () => entry.context?.rows.mark_local(entity);
+        entry.components = ({ klass }) => {
+            if (klass === WaterWaves) { this.#watch_waves(entry); entry.changed(); }
+            if (klass === TransformAttachment) { entry.local(); }
+        };
+        water.onChanged.add(entry.changed);
+        dataset.addEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
+        dataset.addEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
+        dataset.addEntityEventListener(entity, EventType.ComponentAdded, entry.components);
+        dataset.addEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
+        this.#entries.set(entity, entry);
+        this.#watch_waves(entry);
+        this.#dirty.add(entry);
+        this.#renderer.body_count++;
+    }
+
+    #watch_waves(entry) {
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
+        entry.waves = this.entityManager.dataset.getComponent(entry.entity, WaterWaves);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.add(entry.changed); } }
+    }
+
+    unlink(water, geometry, transform, entity) {
+        const entry = this.#entries.get(entity);
+        if (entry === undefined) { return; }
+        const dataset = this.entityManager.dataset;
+        water.onChanged.remove(entry.changed);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.remove(entry.changed); } }
+        dataset.removeEntityEventListener(entity, TRANSFORM64_EVENT_CHANGE, entry.world);
+        dataset.removeEntityEventListener(entity, TRANSFORM_ATTACHMENT_EVENT_CHANGE, entry.local);
+        dataset.removeEntityEventListener(entity, EventType.ComponentAdded, entry.components);
+        dataset.removeEntityEventListener(entity, EventType.ComponentRemoved, entry.components);
+        if (entry.context !== null && entry.context === this.#graphics.scene_context(this.#scene)) {
+            entry.context.scene_database.get('water_bodies').remove(entry.row);
+            entry.context.rows.release(entity);
+        }
+        this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
+        this.#renderer.body_count--;
+        if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
+    }
+
+    update(dt) {
+        this.#recycle_requests();
+        this.#time += dt; this.#renderer.time = this.#time; this.#waves.advance(dt);
+        this.#waves.windy = this.#wind_can_blow();
+        const context = this.#graphics.scene_context(this.#scene);
+        if (context === null) {
+            if (this.#context !== null || this.#queries !== null) {
+                this.#drop_queries();
+                this.#context = null;
+            }
+            this.#answer_requests(null);
+            return;
+        }
+        if (context !== this.#context) {
+            this.#drop_queries();
+            this.#context = context;
+            // Device replacement is the only whole-scene rebuild; ordinary frames drain edits.
+            for (const entry of this.#entries.values()) {
+                entry.context = null; entry.row = -1; entry.wave = -1;
+                // a batch the old context never spent goes back to the front of the queue
+                const staged = [];
+                for (let i = 0; i < entry.staged.impulse_count; i++) { staged.push(...entry.staged.impulses[i]); }
+                entry.queue.unshift(...staged); entry.staged.impulse_count = 0;
+                this.#dirty.add(entry);
+            }
+            this.#renderer.meshlet_capacity = 0;
+        }
+        for (const entry of this.#dirty) { this.#write(entry, context); }
+        this.#dirty.clear();
+        for (const entry of this.#impulses) { this.#stage(entry, context); }
+        this.#answer_requests(context);
+    }
+
+    /**
+     * Whether the scene's wind field can hold wind: an enabled {@link GPUFluidComponent} on any entity, or a far
+     * field that is not still. The lowest holder of the component answers without a walk; only when it is disabled
+     * are the others visited.
+     * @returns {boolean}
+     */
+    #wind_can_blow() {
+        const em = this.entityManager, dataset = em.dataset;
+        if (dataset !== null) {
+            const lowest = dataset.getAnyComponentInstance(GPUFluidComponent);
+            if (lowest !== null) {
+                if (lowest.enabled) { return true; }
+                this.#enabled_found = false;
+                dataset.traverseComponents(GPUFluidComponent, this.#visit_domain);
+                if (this.#enabled_found) { return true; }
+            }
+        }
+        // registered later than this system, or never
+        const fluid = this.#fluid ??= em.getSystem(GPUFluidSystem);
+        if (fluid === null) { return false; }
+        const far = this.#far;
+        fluid.far_field(far);
+        return far[0] !== 0 || far[1] !== 0 || far[2] !== 0;
+    }
+
+    /** Top up a body's batch on its surface row from its queue, up to the row's limit. */
+    #stage(entry, context) {
+        const staged = entry.staged, queue = entry.queue;
+        if (entry.wave === -1 || queue.length === 0 || staged.impulse_count === WATER_WAVE_IMPULSE_LIMIT) { return; }
+        const taken = Math.min(queue.length / 4, WATER_WAVE_IMPULSE_LIMIT - staged.impulse_count);
+        for (let i = 0; i < taken; i++) {
+            const impulse = staged.impulses[staged.impulse_count++];
+            for (let c = 0; c < 4; c++) { impulse[c] = queue[4 * i + c]; }
+        }
+        queue.copyWithin(0, 4 * taken);
+        queue.length -= 4 * taken;
+        this.#waves.splashed = true;
+        for (let i = staged.impulse_count; i < WATER_WAVE_IMPULSE_LIMIT; i++) { staged.impulses[i].fill(0); }
+        context.scene_database.get('water_waves').set_fields(entry.wave, staged, IMPULSE_WRITER);
+    }
+
+    #write(entry, context) {
+        const bodies = context.scene_database.get('water_bodies');
+        const waves = context.scene_database.get('water_waves');
+        if (entry.context === null) {
+            context.rows.acquire(entry.entity);
+            context.geometries.add(entry.geometry);
+            entry.context = context;
+            this.#renderer.meshlet_capacity += entry.geometry.meshlets.count;
+        }
+        const geometry = context.geometries.getAddress(entry.geometry);
+        if (entry.wave === -1) {
+            // the GPU seeds the wind from its first sample, and derives the weights for it
+            entry.wave = waves.add({ upwind_fetch: 0, shore_reflection: WATER_WAVES_SHORE_REFLECTION_DEFAULT,
+                impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]), impulse_count: 0,
+                node: entry.entity + 1, geometry, simulate_hidden: 0, wind: [0, 0, 0], wind_seeded: 0, derived_for: [-1, -1, 0, 0],
+                weights: new Array(WATER_SPECTRUM_BAND_COUNT).fill(0), slope_variance: 0,
+                wind_from: [0, 0], wind_to: [0, 0], wind_blend: 1, displacement_bounds: [0, 0, 0, 0], particle_levels: 0 });
+        }
+        const waves_component = entry.waves;
+        const reflection = Math.min(1, Math.max(0, waves_component?.shoreReflection.getValue() ?? WATER_WAVES_SHORE_REFLECTION_DEFAULT));
+        waves.set_fields(entry.wave, { upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), shore_reflection: reflection, node: entry.entity + 1, geometry,
+            simulate_hidden: entry.water.simulateWhenHidden.getValue() ? 1 : 0 }, AUTHORED_WRITER);
+        const water = entry.water;
+        const record = { geometry, node: entry.entity + 1,
+            dirty: 1,
+            wave: entry.wave, ior: Math.max(1, water.ior.getValue()),
+            roughness: Math.min(1, Math.max(0, water.roughness.getValue())), medium: water.medium.to_gpu_record(),
+            backscattering: [0, 0, 0, 0], extinction: [0, 0, 0, 0], diffuse_transmittance: 0 };
+        if (entry.row === -1) { entry.row = bodies.add(record); } else { bodies.set(entry.row, record); }
+    }
+
+    /**
+     * A splash at a world position: rings of wave particles of the given world radius (half their wavelength)
+     * whose height is the given vertical velocity kick, m/s, over the time a crest takes to cross them. The
+     * position is interpreted in the CPU-owned pose; queued on the CPU and spent on the GPU, sixteen a body a frame.
+     */
+    splash(entity, position, radius, strength) {
+        const entry = this.#entries.get(entity); assert.defined(entry, 'water entity');
+        assert.greaterThan(radius, 0, 'radius'); assert.isFinite(radius, 'radius'); assert.isFinite(strength, 'strength');
+        for (let i = 0; i < 3; i++) { assert.isFinite(position[i], `position[${i}]`); }
+        const inverse = SPLASH_INVERSE;
+        const inverted = m4_invert(inverse, entry.transform);
+        assert.ok(inverted, 'water transform is singular');
+        const x = inverse[0] * position[0] + inverse[4] * position[1] + inverse[8] * position[2] + inverse[12];
+        const z = inverse[2] * position[0] + inverse[6] * position[1] + inverse[10] * position[2] + inverse[14];
+        entry.queue.push(x, z, radius, strength); this.#impulses.add(entry);
+    }
+
+    /**
+     * Ask for the water surface height and world-space unit normal at `count` points in the water
+     * body's local `(x, z)` plane: `local_xz` holds `[x0, z0, x1, z1, ...]`, and each sample lands
+     * in `target` from `target_offset` as {@link WATER_QUERY_SAMPLE_FLOATS} (4) floats,
+     * `[world_height, nx, ny, nz]`, unpacked on the CPU when the request settles `Delivered` at a
+     * later apply point ({@link update}); see {@link status}.
+     *
+     * Points outside the body's authored outline or inside island holes are clamped continuously to
+     * the nearest point on the mesh's triangles so no `NaN`s are ever produced.
+     *
+     * @param {number} entity water entity
+     * @param {ArrayLike<number>} local_xz interleaved `[x0, z0, x1, z1, ...]` in local body coordinates
+     * @param {number} count number of `(x, z)` points, at least 1
+     * @param {number} footprint spatial filter footprint in metres, at least 0 (0 resolves all wavelengths)
+     * @param {Float32Array} target memory the caller owns and keeps until the request settles
+     * @param {number} target_offset in floats
+     * @returns {number} a handle into {@link status}
+     */
+    request_local(entity, local_xz, count, footprint, target, target_offset) {
+        const entry = this.#entries.get(entity);
+        assert.defined(entry, 'water entity');
+        assert.isArrayLike(local_xz, 'local_xz');
+        assert.isPositiveInteger(count, 'count');
+        assert.greaterThanOrEqual(local_xz.length, 2 * count, 'local_xz');
+        for (let i = 0; i < 2 * count; i++) {
+            assert.isFinite(local_xz[i], `local_xz[${i}]`);
+        }
+        assert.isFinite(footprint, 'footprint');
+        assert.greaterThanOrEqual(footprint, 0, 'footprint');
+        assert.ok(target instanceof Float32Array, 'target must be a Float32Array');
+        assert.isNonNegativeInteger(target_offset, 'target_offset');
+        assert.lessThanOrEqual(target_offset + WATER_QUERY_SAMPLE_FLOATS * count, target.length, 'the query samples reach past the target');
+
+        const h = this.#allocate_handle();
+        const point_start = this.#request_point_count;
+        const next_point_count = point_start + count;
+
+        if (2 * next_point_count > this.#request_points.length) {
+            this.#request_points = fit(this.#request_points, 2 * next_point_count);
+        }
+
+        const points = this.#request_points;
+
+        for (let i = 0; i < 2 * count; i++) {
+            points[2 * point_start + i] = local_xz[i];
+        }
+
+        this.#request_point_count = next_point_count;
+        this.#request_entities[h] = entity;
+        this.#request_point_offsets[h] = point_start;
+        this.#request_counts[h] = count;
+        this.#request_footprints[h] = footprint;
+        this.#request_offsets[h] = target_offset;
+        this.#request_targets[h] = target;
+        this.#status[h] = GPUReadbackStatus.Pending;
+
+        if (this.#asked_count === this.#asked.length) {
+            this.#asked = fit(this.#asked, this.#asked_count + 1);
+        }
+
+        this.#asked[this.#asked_count++] = h;
+
+        return h;
+    }
+
+    /**
+     * Ask for the water surface height and world-space unit normal at `count` points in world
+     * space: `world_xyz` holds `[x0, y0, z0, x1, y1, z1, ...]`. Internally transforms each world
+     * point into the water body's local `(x, z)` plane via the inverse of its CPU-owned
+     * `Transform64` and delegates to {@link request_local}.
+     *
+     * @param {number} entity water entity
+     * @param {ArrayLike<number>} world_xyz interleaved `[x0, y0, z0, ...]` in world metres
+     * @param {number} count number of `(x, y, z)` points, at least 1
+     * @param {number} footprint spatial filter footprint in metres, at least 0 (0 resolves all wavelengths)
+     * @param {Float32Array} target memory the caller owns and keeps until the request settles
+     * @param {number} target_offset in floats
+     * @returns {number} a handle into {@link status}
+     */
+    request_world(entity, world_xyz, count, footprint, target, target_offset) {
+        const entry = this.#entries.get(entity);
+        assert.defined(entry, 'water entity');
+        assert.isArrayLike(world_xyz, 'world_xyz');
+        assert.isPositiveInteger(count, 'count');
+        assert.greaterThanOrEqual(world_xyz.length, 3 * count, 'world_xyz');
+        for (let i = 0; i < 3 * count; i++) {
+            assert.isFinite(world_xyz[i], `world_xyz[${i}]`);
+        }
+
+        const inverse = SPLASH_INVERSE;
+        const inverted = m4_invert(inverse, entry.transform);
+        assert.ok(inverted, 'water transform is singular');
+
+        if (2 * count > this.#world_to_local_xz.length) {
+            this.#world_to_local_xz = fit(this.#world_to_local_xz, 2 * count);
+        }
+
+        const local_xz = this.#world_to_local_xz;
+
+        for (let i = 0; i < count; i++) {
+            const wx = world_xyz[3 * i];
+            const wy = world_xyz[3 * i + 1];
+            const wz = world_xyz[3 * i + 2];
+
+            local_xz[2 * i] = inverse[0] * wx + inverse[4] * wy + inverse[8] * wz + inverse[12];
+            local_xz[2 * i + 1] = inverse[2] * wx + inverse[6] * wy + inverse[10] * wz + inverse[14];
+        }
+
+        return this.request_local(entity, local_xz, count, footprint, target, target_offset);
+    }
+
+    /**
+     * @returns {number}
+     */
+    #allocate_handle() {
+        if (this.#free_count > 0) {
+            return this.#free_handles[--this.#free_count];
+        }
+
+        const h = this.#fresh++;
+
+        if (h === this.#status.length) {
+            const capacity = 2 * h;
+
+            this.#request_entities = fit(this.#request_entities, capacity);
+            this.#request_point_offsets = fit(this.#request_point_offsets, capacity);
+            this.#request_counts = fit(this.#request_counts, capacity);
+            this.#request_footprints = fit(this.#request_footprints, capacity);
+            this.#request_offsets = fit(this.#request_offsets, capacity);
+            this.#status = fit(this.#status, capacity);
+            this.#free_handles = fit(this.#free_handles, capacity);
+            this.#settled = fit(this.#settled, capacity);
+
+            for (let i = this.#request_targets.length; i < capacity; i++) {
+                this.#request_targets.push(null);
+            }
+        }
+
+        return h;
+    }
+
+    /**
+     * A request answered: its status set, readable until the next apply point.
+     *
+     * @param {number} h
+     * @param {number} status
+     */
+    #settle(h, status) {
+        this.#status[h] = status;
+        this.#request_targets[h] = null;
+        this.#settled[this.#settled_count++] = h;
+    }
+
+    /**
+     * The apply point's first half: the handles answered at the last one go back to the free list.
+     */
+    #recycle_requests() {
+        const settled = this.#settled;
+        const status = this.#status;
+        const free = this.#free_handles;
+
+        for (let i = 0; i < this.#settled_count; i++) {
+            const h = settled[i];
+
+            status[h] = GPUReadbackStatus.None;
+            free[this.#free_count++] = h;
+        }
+
+        this.#settled_count = 0;
+    }
+
+    /**
+     * The apply point's second half: what the device delivered or dropped, and, headless, every
+     * request asked since from the body's rest surface.
+     *
+     * @param {object|null} context
+     */
+    #answer_requests(context) {
+        const queries = this.#queries;
+
+        if (queries !== null) {
+            queries.apply();
+            this.#take_settled(queries);
+        }
+
+        if (context !== null || this.#asked_count === 0) {
+            return;
+        }
+
+        const asked = this.#asked;
+        const points = this.#request_points;
+
+        for (let i = 0; i < this.#asked_count; i++) {
+            const h = asked[i];
+            const entry = this.#entries.get(this.#request_entities[h]);
+
+            if (entry === undefined) {
+                this.#settle(h, GPUReadbackStatus.Dropped);
+                continue;
+            }
+
+            const m = entry.transform;
+            const inverse = SPLASH_INVERSE;
+            const inverted = m4_invert(inverse, m);
+            let nx = 0, ny = 1, nz = 0;
+            if (inverted) {
+                const rx = inverse[1], ry = inverse[5], rz = inverse[9];
+                const len = Math.hypot(rx, ry, rz);
+                if (len > 1e-20) {
+                    nx = rx / len;
+                    ny = ry / len;
+                    nz = rz / len;
+                }
+            }
+
+            const box = entry.geometry.bounding_box;
+            const mid_y = 0.5 * (box[1] + box[4]);
+            const count = this.#request_counts[h];
+            const point_base = 2 * this.#request_point_offsets[h];
+            const target = this.#request_targets[h];
+            let at = this.#request_offsets[h];
+
+            for (let k = 0; k < count; k++, at += WATER_QUERY_SAMPLE_FLOATS) {
+                const lx = Math.min(Math.max(points[point_base + 2 * k], box[0]), box[3]);
+                const lz = Math.min(Math.max(points[point_base + 2 * k + 1], box[2]), box[5]);
+                const world_y = m[1] * lx + m[5] * mid_y + m[9] * lz + m[13];
+
+                target[at] = world_y;
+                target[at + 1] = nx;
+                target[at + 2] = ny;
+                target[at + 3] = nz;
+            }
+
+            this.#settle(h, GPUReadbackStatus.Delivered);
+        }
+
+        this.#request_point_count = 0;
+        this.#asked_count = 0;
+    }
+
+    /**
+     * @param {GPUWaterQueries} queries after an apply or a destroy
+     */
+    #take_settled(queries) {
+        for (let i = 0; i < queries.settled_count; i++) {
+            this.#settle(queries.settled_tag(i), queries.settled_status(i));
+        }
+    }
+
+    /**
+     * Let go of the read API's device half: whatever it had in flight is dropped, its status set now.
+     */
+    #drop_queries() {
+        const queries = this.#queries;
+
+        if (queries === null) {
+            return;
+        }
+
+        queries.destroy();
+
+        this.#take_settled(queries);
+
+        this.#queries = null;
+    }
+
+    /**
+     * Hand the frame's requests to the device, after the frame's surface simulation passes.
+     *
+     * @param {import("../graphics/render/frame_graph/FrameGraph.js").FrameGraph} graph
+     * @param {object} scene
+     * @param {GPUDevice} device
+     */
+    #record_requests(graph, scene, device) {
+        const count = this.#asked_count;
+
+        if (count === 0) {
+            return;
+        }
+
+        let queries = this.#queries;
+
+        if (queries === null) {
+            const graphics = this.#graphics.renderer?.graphics;
+            if (graphics?.compute_pipelines !== undefined) {
+                const enquiry = { device, render: [], compute: [] };
+                WaterSystem.enquirePipelines(enquiry);
+                for (let i = 0; i < enquiry.compute.length; i++) {
+                    graphics.compute_pipelines.prepare(enquiry.compute[i]);
+                }
+            }
+            queries = this.#queries = new GPUWaterQueries({ device });
+        }
+
+        const asked = this.#asked;
+        const points = this.#request_points;
+
+        for (let i = 0; i < count; i++) {
+            const h = asked[i];
+            const entry = this.#entries.get(this.#request_entities[h]);
+
+            if (entry === undefined || entry.row === -1) {
+                this.#settle(h, GPUReadbackStatus.Dropped);
+                continue;
+            }
+
+            queries.request(
+                entry.row,
+                points,
+                2 * this.#request_point_offsets[h],
+                this.#request_counts[h],
+                this.#request_footprints[h],
+                this.#request_targets[h],
+                this.#request_offsets[h],
+                h
+            );
+        }
+
+        this.#request_point_count = 0;
+        this.#asked_count = 0;
+
+        queries.record({ graph, scene, surface: this.#waves });
+    }
+
+    record_surface(frame) {
+        const view = frame.view, scene = view.scene;
+        if (scene.scene !== this.#scene) { return; }
+        const device = this.#graphics.renderer.graphics.device;
+        this.#waves.record({ graph: frame.graph, device, scene, time: this.#time,
+            view: { camera: view.camera.gpu_buffer, projection: view.camera.camera.projection_matrix, height: view.resolution[1] },
+            pixels: this.#renderer.settings.tessellation_pixels });
+        this.#record_requests(frame.graph, scene, device);
+    }
+    record(frame) {
+        const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);
+        if (inspection !== undefined) { frame.get(SceneColor).color = inspection; }
+    }
+}
+
+export class WaterExtension extends RenderExtension {
+    name = 'water'; phase = FramePhase.BeforePresent;
+    constructor(system) { super(); this.system = system; }
+    record(frame) { this.system.record(frame); }
+}
+export class WaterSurfaceExtension extends RenderExtension {
+    name = 'water surface'; phase = FramePhase.FrameStart;
+    constructor(system) { super(); this.system = system; }
+    record(frame) { this.system.record_surface(frame); }
+}