@woosh/meep-engine 3.40.0 → 3.42.0

package/src/engine/graphics3/WaterSystem.d.ts

@@ -2,6 +2,11 @@
  * 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 wind 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).
  */
 export class WaterSystem extends System<any> {
     constructor(graphics: any, scene: any);
@@ -19,7 +24,7 @@ export class WaterSystem extends System<any> {
         inscatter_segments: number;
         tessellation_pixels: number;
     };
-    get waves(): GPUWaterWaveSimulation;
+    get waves(): GPUWaterSurface;
     get transparency_channel(): GPUWaterRenderer;
     get scene(): any;
     request_probe(uv: any): Promise<any>;
@@ -30,7 +35,11 @@ export class WaterSystem extends System<any> {
     link(water: any, geometry: any, transform: any, entity: any): void;
     unlink(water: any, geometry: any, transform: any, entity: any): void;
     update(dt: any): void;
-    /** World-space radius and velocity kick; position is interpreted in the CPU-owned pose. */
+    /**
+     * 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: any, position: any, radius: any, strength: any): void;
     record_surface(frame: any): void;
     record(frame: any): void;
@@ -52,7 +61,7 @@ import { MeshletGeometry } from "../../shade/renderer/geometry/MeshletGeometry.j
 import Water from "../graphics/ecs/water/Water.js";
 import WaterWaves from "../graphics/ecs/water/WaterWaves.js";
 import { ResourceAccessSpecification } from "../../core/model/ResourceAccessSpecification.js";
-import { GPUWaterWaveSimulation } from "../../shade/renderer/water/surface/GPUWaterWaveSimulation.js";
+import { GPUWaterSurface } from "../../shade/renderer/water/surface/GPUWaterSurface.js";
 import { GPUWaterRenderer } from "../../shade/renderer/water/GPUWaterRenderer.js";
 import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
 //# sourceMappingURL=WaterSystem.d.ts.map

package/src/engine/graphics3/WaterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH;IAyBI,uCAcC;IAtCD,6EAAqD;IACrD,kEAA0F;IAY1F;;;;;;;;;;;MAAkD;IAClD,oCAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAsBjC,2CAOC;IAED,0BAMC;IAED,mEAoBC;IAUD,qEAkBC;IAED,sBAgBC;IA0CD,2FAA2F;IAC3F,qEASC;IAED,iCAKC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAlOsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBAC3B,qCAAqC;4CAShB,iDAAiD;uCAGtD,8DAA8D;iCAFpE,gDAAgD;gCAIjD,mDAAmD"}
+{"version":3,"file":"WaterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/WaterSystem.js"],"names":[],"mappings":"AA+BA;;;;;;;;;GASG;AACH;IA2BI,uCAaC;IAvCD,6EAAqD;IACrD,kEAA0F;IAc1F;;;;;;;;;;;MAAkD;IAClD,6BAAmC;IACnC,6CAAqD;IACrD,iBAAmC;IACnC,qCAA8D;IAE9D,0BAGC;IAJD,mBAAiC;IAqBjC,2CAOC;IAED,0BAMC;IAED,mEAsBC;IAQD,qEAkBC;IAED,sBAoBC;IAqDD;;;;OAIG;IACH,qEASC;IAED,iCAMC;IACD,yBAGC;;CACJ;AAED;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAA4C;CAC/C;AACD;IAEI,yBAAsD;IAAvB,YAAoB;IACnD,yBAAoD;CACvD;uBAlQsB,kBAAkB;4BAEb,iCAAiC;gCAI7B,kDAAkD;kBARhE,gCAAgC;uBACe,qCAAqC;4CAS1D,iDAAiD;gCAG7D,uDAAuD;iCAFtD,gDAAgD;gCAIjD,mDAAmD"}

package/src/engine/graphics3/WaterSystem.js

@@ -1,6 +1,6 @@
 import { assert } from "../../core/assert.js";
 import Water from "../graphics/ecs/water/Water.js";
-import WaterWaves from "../graphics/ecs/water/WaterWaves.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";
@@ -12,21 +12,32 @@ 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 { GPUWaterWaveSimulation } from "../../shade/renderer/water/surface/GPUWaterWaveSimulation.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 { 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";
 
-const WIND_WRITER = generate_record_writer(WATER_WAVE_RECORD_STRUCT, ['forcing', 'unresolved_variance']);
+// 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, ['wind', 'upwind_fetch', '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 = ['windSpeed', 'windDirection', 'upwindFetch', 'shoreReflection'];
+/** A splash's world-to-local matrix: rain can splash hundreds of times a second. */
+const SPLASH_INVERSE = new Float64Array(16);
 
 /**
  * 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 wind 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).
  */
 export class WaterSystem extends System {
     dependencies = [Water, MeshletGeometry, Transform64];
@@ -35,11 +46,13 @@ export class WaterSystem extends System {
     #scene;
     #context = null;
     #renderer = new GPUWaterRenderer();
-    #waves = new GPUWaterWaveSimulation();
+    #waves = new GPUWaterSurface();
     #bodies = new GPUWaterBodies();
     #entries = new Map();
     #dirty = new Set();
     #impulses = new Set();
+    // bodies with wind: while there is none, the shared band tiles are not animated
+    #windy = new Set();
     #extensions = [];
     #time = 0;
     get settings() { return this.#renderer.settings; }
@@ -60,9 +73,8 @@ export class WaterSystem extends System {
         this.#waves.onInputsConsumed.add(context => {
             if (context !== this.#context) { return; }
             for (const entry of this.#impulses) {
-                entry.staged.length = 0;
-                if (entry.impulses.length !== 0) { this.#dirty.add(entry); }
-                else { this.#impulses.delete(entry); }
+                entry.staged.impulse_count = 0;
+                if (entry.queue.length === 0) { this.#impulses.delete(entry); }
             }
         });
         this.#renderer.bodies = this.#bodies;
@@ -87,8 +99,10 @@ export class WaterSystem extends System {
     }
 
     link(water, geometry, transform, entity) {
-        const entry = { water, geometry, transform, entity, context: null, row: -1, wave: -1, waves: null,
-            impulses: [], staged: [], wave_record: null };
+        // 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);
@@ -109,11 +123,9 @@ export class WaterSystem extends System {
     }
 
     #watch_waves(entry) {
-        entry.waves?.windSpeed.onChanged.remove(entry.changed);
-        entry.waves?.windDirection.onChanged.remove(entry.changed);
+        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);
-        entry.waves?.windSpeed.onChanged.add(entry.changed);
-        entry.waves?.windDirection.onChanged.add(entry.changed);
+        if (entry.waves != null) { for (const field of WAVE_FIELDS) { entry.waves[field].onChanged.add(entry.changed); } }
     }
 
     unlink(water, geometry, transform, entity) {
@@ -121,8 +133,7 @@ export class WaterSystem extends System {
         if (entry === undefined) { return; }
         const dataset = this.entityManager.dataset;
         water.onChanged.remove(entry.changed);
-        entry.waves?.windSpeed.onChanged.remove(entry.changed);
-        entry.waves?.windDirection.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);
@@ -132,6 +143,7 @@ export class WaterSystem extends System {
             entry.context.rows.release(entity);
         }
         this.#entries.delete(entity); this.#dirty.delete(entry); this.#impulses.delete(entry);
+        this.#windy.delete(entry); this.#waves.windy = this.#windy.size > 0;
         this.#renderer.body_count--;
         if (entry.context !== null) { this.#renderer.meshlet_capacity -= entry.geometry.meshlets.count; }
     }
@@ -144,14 +156,34 @@ export class WaterSystem extends System {
             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; entry.wave_record = null;
-                entry.impulses.unshift(...entry.staged); entry.staged.length = 0;
+                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); }
+    }
+
+    /** 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) {
@@ -163,54 +195,54 @@ export class WaterSystem extends System {
             entry.context = context;
             this.#renderer.meshlet_capacity += entry.geometry.meshlets.count;
         }
-        if (entry.wave !== -1 || entry.waves != null || entry.impulses.length !== 0) {
-            const bounds = entry.geometry.bounding_box;
-            if (entry.wave === -1) {
-                entry.wave_record = { extent: [bounds[0], bounds[2], bounds[3], bounds[5]],
-                    forcing: [1, 0, 0, 0], impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]),
-                    node: entry.entity + 1, geometry: context.geometries.getAddress(entry.geometry),
-                    unresolved_variance: 0, impulse_count: 0, first_write: 1, displacement_bounds: [0, 0] };
-                entry.wave = waves.add(entry.wave_record);
-            }
-            const wind = Math.max(0, entry.waves?.windSpeed.getValue() ?? 0);
-            const direction = entry.waves?.windDirection.getValue() ?? 0;
-            // Patch only authored fields: a full write would restore GPU-consumed impulses/reset flags.
-            waves.set_fields(entry.wave, { forcing: [Math.cos(direction), Math.sin(direction), 0.02 * wind * wind, 0.5 * wind],
-                unresolved_variance: wind > 0 ? 0.003 + 0.00512 * wind : 0 }, WIND_WRITER);
-            if (entry.impulses.length !== 0) {
-                entry.staged.push(...entry.impulses.splice(0, WATER_WAVE_IMPULSE_LIMIT - entry.staged.length));
-                const impulses = entry.staged.slice();
-                const count = impulses.length;
-                while (impulses.length < WATER_WAVE_IMPULSE_LIMIT) { impulses.push([0, 0, 0, 0]); }
-                waves.set_fields(entry.wave, { impulses, impulse_count: count }, IMPULSE_WRITER);
-            }
+        const geometry = context.geometries.getAddress(entry.geometry);
+        if (entry.wave === -1) {
+            entry.wave = waves.add({ wind: [1, 0, 0, WATER_WAVES_SHORE_REFLECTION_DEFAULT], upwind_fetch: 0,
+                impulses: Array.from({ length: WATER_WAVE_IMPULSE_LIMIT }, () => [0, 0, 0, 0]), impulse_count: 0,
+                node: entry.entity + 1, geometry, simulate_hidden: 0, derived_for: [-1, -1],
+                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 speed = Math.max(0, waves_component?.windSpeed.getValue() ?? 0);
+        const direction = waves_component?.windDirection.getValue() ?? 0;
+        const reflection = Math.min(1, Math.max(0, waves_component?.shoreReflection.getValue() ?? WATER_WAVES_SHORE_REFLECTION_DEFAULT));
+        waves.set_fields(entry.wave, { wind: [Math.cos(direction), Math.sin(direction), speed, reflection],
+            upwind_fetch: Math.max(0, waves_component?.upwindFetch.getValue() ?? 0), node: entry.entity + 1, geometry,
+            simulate_hidden: entry.water.simulateWhenHidden.getValue() ? 1 : 0 }, AUTHORED_WRITER);
+        if (speed > 0) { this.#windy.add(entry); } else { this.#windy.delete(entry); }
+        this.#waves.windy = this.#windy.size > 0;
         const water = entry.water;
-        const record = { geometry: context.geometries.getAddress(entry.geometry), node: entry.entity + 1,
+        const record = { geometry, node: entry.entity + 1,
             dirty: 1,
-            wave: entry.wave === -1 ? 0xffffffff : entry.wave, ior: Math.max(1, water.ior.getValue()),
+            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); }
     }
 
-    /** World-space radius and velocity kick; position is interpreted in the CPU-owned pose. */
+    /**
+     * 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 = new Float64Array(16);
+        const inverse = SPLASH_INVERSE;
         assert.ok(m4_invert(inverse, entry.transform), '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.impulses.push([x, z, radius, strength]); this.#impulses.add(entry); this.#dirty.add(entry);
+        entry.queue.push(x, z, radius, strength); this.#impulses.add(entry);
     }
 
     record_surface(frame) {
-        const scene = frame.view.scene;
+        const view = frame.view, scene = view.scene;
         if (scene.scene !== this.#scene) { return; }
-        this.#waves.record({ graph: frame.graph, device: this.#graphics.renderer.graphics.device, scene });
-        this.#bodies.record({ graph: frame.graph, scene });
+        this.#waves.record({ graph: frame.graph, device: this.#graphics.renderer.graphics.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 });
     }
     record(frame) {
         const inspection = this.#renderer.inspect(frame.graph, frame.view, frame.resolution);

package/src/engine/input/devices/PointerDevice.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PointerDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/PointerDevice.js"],"names":[],"mappings":"AA2NA;;;;;GAKG;AACH,mDAJW,OAAO,SACP,UAAU,GAAC,KAAK,WAChB,OAAO,QAejB;AAED;;;;;GAKG;AACH;IAuFI;;;;OAIG;IACH,wBAHW,WAAW,EA+BrB;IAtHD;;;;OAIG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;OAEG;IACH;;;QAGI;;;;;;WAMG;;;QAGH;;WAEG;;;;;;;;;MASL;IAeF;;;OAGG;IACH,kBAAkB;IAElB;;;;OAIG;IACH,kBAFU,iBAAiB,EAAE,CAEL;IAExB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,2CAEC;IAyID;;;OAGG;IACH,oBAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,4BAsBC;IAED,0BAEC;IAED;;;;OAIG;IACH,qCAHW,OAAO,SACP,UAAU,GAAC,KAAK,QAI1B;IAED,cAiCC;IAED,aA4BC;;CACJ;oBAnkBmB,+BAA+B;mBADhC,uCAAuC;kCAOxB,wBAAwB"}
+{"version":3,"file":"PointerDevice.d.ts","sourceRoot":"","sources":["../../../../../src/engine/input/devices/PointerDevice.js"],"names":[],"mappings":"AAgPA;;;;;GAKG;AACH,mDAJW,OAAO,SACP,UAAU,GAAC,KAAK,WAChB,OAAO,QAejB;AAED;;;;;GAKG;AACH;IAyFI;;;;OAIG;IACH,wBAHW,WAAW,EA+BrB;IAtHD;;;;OAIG;IACH,mBAFU,OAAO,CAEQ;IAEzB;;OAEG;IACH;;;QAGI;;;;;;WAMG;;;QAGH;;WAEG;;;;;;;;;MASL;IAeF;;;OAGG;IACH,kBAAkB;IAElB;;;;OAIG;IACH,kBAFU,iBAAiB,EAAE,CAEL;IAExB;;;OAGG;IACH,yCAEC;IAED;;;OAGG;IACH,0CAEC;IAED;;;OAGG;IACH,2CAEC;IA2ID;;;OAGG;IACH,oBAFY,OAAO,CAIlB;IAED;;;OAGG;IACH,4BAsBC;IAED,0BAEC;IAED;;;;OAIG;IACH,qCAHW,OAAO,SACP,UAAU,GAAC,KAAK,QAI1B;IAED,cAiCC;IAED,aA4BC;;CACJ;oBA5lBmB,+BAA+B;mBADhC,uCAAuC;kCAOxB,wBAAwB"}

package/src/engine/input/devices/PointerDevice.js

@@ -20,6 +20,7 @@ import { suppressContextMenu } from "./mouse/suppressContextMenu.js";
  * @param {number} [options.maxDistance] in pixels
  * @param {number} [options.maxDelay] Maximum delay between down and up events in seconds
  * @param {Signal} options.signal
+ * @returns {(id?:number)=>void} clears pending candidates without emitting a tap
  */
 function observeTap({
                         up,
@@ -139,6 +140,16 @@ function observeTap({
     }
 
     down.add(handleDown);
+
+    return id => {
+        if (id !== undefined) {
+            reset(id);
+            return;
+        }
+        active.clear();
+        up.remove(handleUp);
+        move.remove(handleMove);
+    };
 }
 
 /**
@@ -149,6 +160,7 @@ function observeTap({
  * @param {Signal} dragStart
  * @param {Signal} dragEnd
  * @param {Signal} drag
+ * @returns {()=>void} removes pending gesture observations without emitting a drag end
  */
 function observeDrag(up, down, move, dragStart, dragEnd, drag) {
     const origin = new Vector2();
@@ -188,7 +200,8 @@ function observeDrag(up, down, move, dragStart, dragEnd, drag) {
 
         lastDragPosition.copy(origin);
         dragStart.send2(origin, event);
-        handleDrag(position, event);
+        // A start consumer can stop the device and remove this gesture before motion is delivered.
+        if (up.contains(handleDragEnd)) handleDrag(position, event);
     }
 
     const lastDragPosition = new Vector2();
@@ -214,6 +227,14 @@ function observeDrag(up, down, move, dragStart, dragEnd, drag) {
     }
 
     down.add(handleDown);
+
+    return () => {
+        // Overlapping presses can register these owned observations more than once.
+        while (up.remove(noDrag)) {}
+        while (up.remove(handleDragEnd)) {}
+        while (move.remove(handleDragStart)) {}
+        while (move.remove(handleDrag)) {}
+    };
 }
 
 
@@ -245,6 +266,8 @@ export function readPositionFromMouseEvent(result, event, source = event.target)
  * @copyright Company Named Limited (c) 2026
  */
 export class PointerDevice {
+    #resetTap;
+    #resetDrag;
 
     /**
      * Current live position of the pointer
@@ -355,14 +378,14 @@ export class PointerDevice {
         // `globalUp`, not `up`, for the same reason observeDrag below uses it: `up` only fires for
         // a release over the element, so a press that lifted one pixel outside the canvas was
         // never resolved and never reset - the candidate simply sat in the map.
-        observeTap({
+        this.#resetTap = observeTap({
             up: this.on.globalUp,
             down: this.on.down,
             move: this.on.move,
             maxDistance: 10,
             signal: this.on.tap
         });
-        observeDrag(this.on.globalUp, this.on.down, this.on.move, this.on.dragStart, this.on.dragEnd, this.on.drag);
+        this.#resetDrag = observeDrag(this.on.globalUp, this.on.down, this.on.move, this.on.dragStart, this.on.dragEnd, this.on.drag);
 
     }
 
@@ -424,7 +447,9 @@ export class PointerDevice {
      * every button for the same reason. The pointer was the one device of the three that did not,
      * with `PointerEvents.Cancel` sitting unused in the event table as the tell.
      */
-    #releaseAllButtons = () => {
+    #releaseAllButtons = event => {
+        this.#resetTap(event?.type === PointerEvents.Cancel ? event.pointerId : undefined);
+        this.#resetDrag();
         const buttons = this.buttons;
 
         for (let i = 0; i < buttons.length; i++) {

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.d.ts

@@ -2,6 +2,7 @@
  * Picks a random behavior to execute.
  * The selection is done during initialization, and that selected behavior will then run to completion.
  * NOTE: Weights are relative, so they don't need to add up to any specific value.
+ * If every weight is zero, no child runs and the selector fails.
  *
  * @example
  *  const behavior = WeightedRandomBehavior.from([

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WeightedRandomBehavior.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAkEI;;;;OAIG;IACH,sBAHW,8BAAyB,EAAE,GACzB,sBAAsB,CAUlC;;IA7ED;;;;OAIG;IACH,mBAAgB;IAEhB;;;;OAIG;IACH,iBAA+B;IAE/B;;;;OAIG;IACH,mBAAuB;IAEvB;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,sBAFW,8BAAyB,EAAE,QAcrC;IAED;;;OAGG;IACH,cAFW,8BAAyB,QAanC;IAiBD,iBAYC;IAkBD,6BAEC;CACJ;yBAnIwB,gBAAgB;gCACT,sBAAsB"}
+{"version":3,"file":"WeightedRandomBehavior.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;GAcG;AACH;IAkEI;;;;OAIG;IACH,sBAHW,8BAAyB,EAAE,GACzB,sBAAsB,CAUlC;;IA7ED;;;;OAIG;IACH,mBAAgB;IAEhB;;;;OAIG;IACH,iBAA+B;IAE/B;;;;OAIG;IACH,mBAAuB;IAEvB;;;OAGG;IACH,iBAFW,MAAM,QAIhB;IAED;;;OAGG;IACH,sBAFW,8BAAyB,EAAE,QAcrC;IAED;;;OAGG;IACH,cAFW,8BAAyB,QAanC;IAiBD,iBAiBC;IAsBD,6BAEC;CACJ;yBA9IwB,gBAAgB;gCAET,sBAAsB"}

package/src/engine/intelligence/behavior/selector/WeightedRandomBehavior.js

@@ -2,12 +2,14 @@ import { assert } from "../../../../core/assert.js";
 import { weightedRandomFromArray } from "../../../../core/collection/array/weightedRandomFromArray.js";
 import { seededRandom } from "../../../../core/math/random/seededRandom.js";
 import { Behavior } from "../Behavior.js";
+import { BehaviorStatus } from "../BehaviorStatus.js";
 import { WeightedElement } from "./WeightedElement.js";
 
 /**
  * Picks a random behavior to execute.
  * The selection is done during initialization, and that selected behavior will then run to completion.
  * NOTE: Weights are relative, so they don't need to add up to any specific value.
+ * If every weight is zero, no child runs and the selector fails.
  *
  * @example
  *  const behavior = WeightedRandomBehavior.from([
@@ -106,6 +108,11 @@ export class WeightedRandomBehavior extends Behavior {
          */
         const weightedElement = weightedRandomFromArray(this.__elements, this.__random, WeightedElement.getWeight);
 
+        if (weightedElement === undefined) {
+            this.__selected = undefined;
+            return;
+        }
+
         const selected = weightedElement.data;
 
         assert.equal(selected.isBehavior, true, 'selected.isBehavior !== true');
@@ -118,18 +125,22 @@ export class WeightedRandomBehavior extends Behavior {
 
         this.__select();
 
-        this.__selected.initialize(context);
+        if (this.__selected !== undefined) {
+            this.__selected.initialize(context);
+        }
     }
 
     finalize() {
         super.finalize();
 
-        this.__selected.finalize();
+        if (this.__selected !== undefined) {
+            this.__selected.finalize();
+        }
 
         this.__selected = undefined;
     }
 
     tick(timeDelta) {
-        return this.__selected.tick(timeDelta);
+        return this.__selected === undefined ? BehaviorStatus.Failed : this.__selected.tick(timeDelta);
     }
 }

package/src/engine/physics/cloth/MEASUREMENTS.md

@@ -3984,3 +3984,133 @@ colliding readings have a median of 0.90 and the twelve idle ones 0.95.
 
 **No library entry is re-sized.** Its bench cannot see a collider (§58), and a
 garment on a body is the colliding half of the tables above.
+
+## 61. A rig's joints were claimed with a bit the GPU never reads, by two parties at once
+
+Found reading code in the 2026-10-05 IK design review, and measured here before
+anything changed. Every reading below is a spec that registers a real clip
+through `GPUAnimationManager` on a `SoftwareGPUDevice` scene over the garment's
+own dataset (`cloth_rig.spec.js`), or runs the real apply pass under the WGSL
+emulator (`shader_animation_apply.spec.js`). The specs it replaced granted the
+bit by hand on joints no clip bound, so none of this was visible to them.
+
+```
+  what                                        before                                      after
+  clip unregistered while cloth held it,      bit 2 (GPU), and a CPU write of             bit 0; the row holds
+    then the garment removed                    (0.25, -0.5, 0.125) left the row at         (0.25, -0.5, 0.125)
+                                                0.0020000000949949026, for good
+  rig re-seeded while seeded, then removed    bit 0 with the clip still bound             bit 2
+  clip binding a joint cloth already holds    bit 2; the row stayed 0.0020000000949949026 bit 0; the row is
+                                                while cloth wrote 0.0011062223929911852     cloth's write
+  last clip leaving a held joint              offset (5, -0.10000382363796234, 0):        cloth's offset,
+                                                the clip's pose over cloth's 0.00173…       untouched
+  bindings of clips over a held cape          rows 3, 4, 5, 6, 7 (shoulder + cape)        3, then NULL ×4
+  apply pass over two held targets            8 accumulator words written                 none
+  cache / exact walk over a held level        cache off by 0.98 in a translation lane;    within 1e-12
+                                                the walk off in lane 12 (world x)
+```
+
+**Why the bit could not have worked.** The apply pass adds every bound clip into
+its target's accumulator slot whatever the clip's weight, the resolve writes the
+row, and both run in `tick`, after `build`'s flush. `GPUStateAuthority` gates
+only that flush. A cape joint whose clip still named its row was the clip's on
+screen, bit or no bit.
+
+**What changed.** A CPU writer *holds* a component (`gpu_authority_hold`):
+`GPUStateAuthority#held` records it, the bit clears, and `gpu_authority_grant`
+will not set a held bit. The animation manager hears the hold through an entity
+event on every joint it drives. It points that joint's bindings at
+`GPU_DATABASE_NULL`, whose type bits `write_object_property` ignores, and it
+skips the seed when the last clip leaves. When the hold ends it points them back
+and grants, if a clip is still bound. The exact evaluators read a held level as
+its offset (`t64_evaluate_local`). Cloth holds every joint it drives and never
+touches the bit.
+
+**Not measured:** a device run. The WGSL is unchanged; what changed is what the
+bindings name, and the emulator runs the real apply pass over it.
+
+### Found in review
+
+An adversarial pass over those six commits. Every candidate was measured before it
+was believed.
+
+- **A re-seeded rig leaked its holds** when it was taken away, or refused, before
+  the next seeding. `reseed` cleared `seeded`, the release asks `seeded`, and the
+  joints stayed held: their clips muted and nothing writing them. Before the hold
+  this was a bit that lied while the clip still won on the GPU; muting made it a
+  frozen joint. `reseed` now gives the holds back, and the seed asserts it
+  starts from none. Red first: bits `[0, 0, 0, 0]` against `[2, 2, 2, 2]`, the
+  bindings all NULL, after removing `Cloth`, after removing `ClothRig`, and after
+  a refused proxy.
+- **One line was pinned by nothing.** Of twelve mutants over the fixes, eleven
+  were killed. The survivor was the row mark a hold makes, which carries an offset
+  the holder wrote before it held. It is pinned now.
+- Measured and kept: the bind-time bookkeeping costs 129 ns a driven entity
+  (2.5 ms for 19,440, at registration only). The hold check costs the exact
+  evaluation 2.3% a level (64.0 to 65.8 µs over 70 levels, two clips of 210
+  channels, paired median).
+- Measured and dismissed: a muted rotation binding writes nothing to its slot,
+  rest rotation included (now in the emulator spec). A hold queues one word, the
+  binding's `instance`, and its end queues the row back. A renderer restart
+  reaches `GPUAnimationManager#destroy`, which removes every listener.
+
+### What a hold's end hands over
+
+Found reading code in the 2026-10-06 IK design review: two things the end of a
+hold did not hand to a clip still bound. Cloth's release is a plain unhold that
+leaves each joint's offset at cloth's last write-back, so both reached it. Real
+clips through the manager in `cloth_rig.spec.js`, and the apply and resolve
+passes under the WGSL emulator in `animation_pose_pipeline.spec.js`.
+
+The rest rows below read the rest each binding carries, which is what the resolve
+writes at weight zero (shown under the emulator, not on the cape).
+
+```
+  what                                        before                             after
+  rest a clip keying the cape carries         the rest from before the seed,     the offset cloth
+    once the garment goes                       [0, 0, 0, 1]                       left, z -0.00243
+  the same, the clip bound while cloth held   cloth's pose when it bound,        the offset cloth
+                                                z -0.000102                        left, z -0.00243
+  row y of a cape joint under a clip keying   -0.0999996, cloth's flush before   -0.1000130, cloth's
+    x alone, the garment removed between        its last five steps                last write-back
+    a step and the flush
+```
+
+**What changed.** The end of a hold, with a clip still bound, writes every
+binding's rest from the offset as the holder left it, with the unmute, and marks
+the row as a hand-over (`GPUSceneRows#mark_handover`): the flush writes it past
+the bit, once, and the resolve writes the axes the clip keys after it.
+
+**Decided, not changed:** a joint whose last clip left while it was held keeps
+the holder's offset when the hold ends, not the clip's last pose (2d67be636).
+The clip had been muted since the hold began, or since it bound, so its last pose
+is one the joint has not shown since; the seed's own rule, carry on from what is
+on screen, gives the holder's offset.
+
+**Open, not decided:** cloth's rig path leaves its last pose on the joints when it
+lets go, where the entity path puts the locals it captured back
+(`cloth_release_subtree`). The rig path never captured the joints' own offsets,
+but the instance holds the proxy's bind pose (`rest_local_*`), which it could put
+back. Measured: after the garment goes, a cape joint's offset rotation has z up
+to -0.00243 where that bind pose (identity, for the spec's skeleton) has 0, and a
+clip keying the cape carries it as its rest.
+
+**Found in review** of these two fixes:
+
+- **Two lines were pinned by nothing.** Of ten mutants over the fixes, eight were
+  killed. The survivors: the `MARK_LOCAL` inside the hand-over mark, since both
+  gap-2 specs had the holder announce its last write and so mark the row
+  themselves; and the rest read off the wrong component, since the emulator
+  spec's left rotation was `[0.5, 0.5, 0.5, 0.5]` and the cape turns about z
+  alone. Both are pinned now.
+- **The first bind had the same hole.** A clip that first binds a joint grants
+  the bit at once, so an offset announced earlier in that frame never reached the
+  row: `[0, 0, 0, 1]` against the `[0.1, 0.3, 0.5, 0.806]` announced. Binding
+  marks the hand-over too now. No engine path was found that triggers it today: the
+  drivers re-register a whole clip set in one call, whose outgoing seed is such an
+  announcement, but they set time from the CPU, so that seed equals what the GPU
+  last resolved.
+- Measured and dismissed: the binding writer over `instance` and `rest_rotation`
+  is two disjoint ranges of one row, which the partial upload shader spec already
+  lands under the emulator; and the worker path writes nothing after a release,
+  because a join for a cloth unlinked or reseeded since its dispatch is dropped.

package/src/engine/physics/cloth/PLAN.md

@@ -368,7 +368,8 @@ said cloth reuses `PhysicsSystem`'s producer/`__interp_restore` contract; M5 mea
 that contract is entity-keyed and a rigged garment's joints are not entities — and §13.1 and §18 carry
 what the cloth-shaped version would be and what it would cost. What keeps a cloth-driven bone from
 fighting an animation-driven one is not interpolation but `TransformAuthority`, which `cloth_seed_rig`
-claims (§11.2, `MEASUREMENTS.md` §25).
+claims (§11.2, `MEASUREMENTS.md` §25) — as a hold since §61, because the bit alone never stopped a
+clip on the GPU.
 
 ### 4.1 Ordering, and why the answer is not to be ordered
 
@@ -1430,6 +1431,20 @@ with no component left anywhere naming which joints those were. The seed now rec
 joints its revoke *changed*, and `cloth_release_rig` hands those back when the `Cloth` is removed or
 the `ClothRig` is taken away; a joint that was already the CPU's before cloth arrived stays the CPU's.
 
+**2026-10-06: the claim never stopped a clip, and the loan was handed back to whoever asked last.**
+No GPU pass reads `GPUStateAuthority`. A bound clip's bindings write a joint's row through the pose
+accumulator every frame, after the CPU's flush, whatever the bit says, so clearing the bit only let
+cloth's flush and the clip race for one row, and the clip won. And cloth and `GPUAnimationManager`
+each flipped the same bit without the other: a clip that left during the loan was answered by
+cloth's re-grant with a joint nothing wrote again, and a clip that arrived during it took the bit
+from under cloth's write-back. The rule now is a **hold**. `GPUStateAuthority#held` records that a CPU
+writer has the offset, the bit stays clear while it does, and the animation manager — the only
+writer of the bit — mutes every binding that names a held joint and leaves its offset alone when the
+last clip goes. Ending the hold grants nothing; a clip still bound takes the joint back. So **"a joint
+cloth simulates stops being animatable by a clip" is true now, and a garment whose joints are also
+keyed is not an authoring error**: exporters often bake every bone, and the cape simulates anyway.
+`MEASUREMENTS.md` §61.
+
 **The anchor's world pose is computed, never read back.** A joint of an animated skeleton has no
 CPU-side `transform_global` — nothing maintains it — so the rig path evaluates the anchor with
 `pose_evaluate_world` over the clips the entity is playing, which is the engine's own sanctioned

package/src/engine/physics/cloth/ecs/ClothColliderSystem.d.ts

@@ -12,12 +12,11 @@
  * ## It has no `fixedUpdate`, and that is §4.1 applied a second time
  *
  * The index has to be refreshed from the world's transforms **before** any
- * cloth reads it, and the engine's two ordering mechanisms cannot express that:
- * `updateExecutionOrder` scores a system as a sum over the components it
- * references and sorts descending, so a system can only be moved *earlier* by
- * touching more, and `ClothSystem` — which reads and writes `Transform64` and
- * `TransformAttachment` — outscores a system that only reads. Registration
- * order does not break a non-tie.
+ * cloth reads it, and the derived order says the opposite: `updateExecutionOrder`
+ * runs a writer of a component before its readers, `ClothSystem` writes
+ * `Transform64`, and the index is not a component, so a system that steps only
+ * to read transforms into it would run after cloth. Registration order breaks
+ * only the ties that leaves.
  *
  * §4.1's conclusion applies unchanged: the answer is not a third mechanism, it
  * is not needing one. So this system does not step at all. {@link refresh} is