@woosh/meep-engine 3.40.0 → 3.42.0

package/src/engine/sound/sopra/definition/clip/RandomContainerAudioClip.js

@@ -25,10 +25,7 @@ export class RandomContainerAudioClip extends ContainerAudioClip {
      * container picks uniformly). A weight of `0` (or any non-positive value) means the child is
      * NEVER picked.
      *
-     * Degenerate-but-accepted: if EVERY weight is 0 the container still resolves — deterministically —
-     * to a single child (there is simply nothing to weight, so the pick collapses to a fixed index).
-     * That is a content-authoring mistake, not an engine fault; the engine stays well-defined. In
-     * other words, ten children all weighted 0 will "work", but you get the dog food.
+     * If every child is disabled, the container resolves to an empty timeline.
      * @type {number[]}
      */
     weights = [];
@@ -181,29 +178,41 @@ export class RandomContainerAudioClip extends ContainerAudioClip {
      * this clip) rather than on this shared, immutable definition; this method owns both the selection
      * algorithm and the maintenance of that history ring.
      * @param {SopraPlaybackContext} playback
-     * @returns {number} chosen child index
+     * @returns {number|undefined} chosen child index, or undefined when no child has positive weight
      */
     pickChildIndex(playback) {
         const children = this.children;
         const n = children.length;
 
-        // can't avoid every option — cap so at least one candidate remains
-        const avoid = Math.min(this.avoid_repeating_last, n - 1);
+        const weights = this.weights;
+        let eligibleCount = 0;
+        for (let i = 0; i < n; i++) {
+            if (weights[i] > 0) eligibleCount++;
+        }
+
+        // Disabled children cannot keep an enabled choice out of contention.
+        const avoid = Math.max(0, Math.min(this.avoid_repeating_last, eligibleCount - 1));
 
         const recent = playback.getState(this, () => []);
+        while (recent.length > avoid) {
+            recent.shift();
+        }
 
         const candidates = [];
         for (let i = 0; i < n; i++) {
-            if (recent.indexOf(i) === -1) {
+            if (weights[i] > 0 && recent.indexOf(i) === -1) {
                 candidates.push(i);
             }
         }
 
         // weighted pick among the surviving candidates (weight looked up by child index). With the
         // default all-1 weights this is a uniform draw; a 0 weight removes that child from contention.
-        const weights = this.weights;
         const index = weightedRandomFromArray(candidates, playback.random, i => weights[i]);
 
+        if (index === undefined) {
+            return undefined;
+        }
+
         recent.push(index);
         while (recent.length > avoid) {
             recent.shift();
@@ -219,6 +228,10 @@ export class RandomContainerAudioClip extends ContainerAudioClip {
 
         const index = this.pickChildIndex(env.playback);
 
+        if (index === undefined) {
+            return { plays: [], duration: 0 };
+        }
+
         return this.children[index].planTimeline(env, gainDb + this.gain, pitchCents + this.pitch, offset);
     }
 }

package/src/engine/ui/DraggableAspect.d.ts

@@ -20,13 +20,16 @@ export class DraggableAspect {
      * @param {(position:Vector2, event:Event)=>*} [options.dragStart=noop]
      * @param {(position:Vector2, origin:Vector2, delta:Vector2, event:Event)=>*} [options.drag=noop]
      * @param {(position:Vector2, origin:Vector2, event:Event)=>*} [options.dragEnd=noop]
+     * @param {(event:Event|undefined)=>*} [options.dragCancel=noop] called for a cancelled press or drag;
+     *   pointercancel/blur carries its event, while stop() carries undefined. Cancellation never commits dragEnd.
      * @param {boolean} [options.stopPropagation=true] prevent propagation of pointer events up the DOM tree
      */
-    constructor({ el, dragStart, drag, dragEnd, stopPropagation }: {
+    constructor({ el, dragStart, drag, dragEnd, dragCancel, stopPropagation }: {
         el: EventTarget;
         dragStart?: (position: Vector2, event: Event) => any;
         drag?: (position: Vector2, origin: Vector2, delta: Vector2, event: Event) => any;
         dragEnd?: (position: Vector2, origin: Vector2, event: Event) => any;
+        dragCancel?: (event: Event | undefined) => any;
         stopPropagation?: boolean;
     });
     /**
@@ -44,6 +47,7 @@ export class DraggableAspect {
     getPointer(): PointerDevice;
     start(): void;
     stop(): void;
+    #private;
 }
 import { PointerDevice } from "../input/devices/PointerDevice.js";
 import Vector2 from "../../core/geom/Vector2.js";

package/src/engine/ui/DraggableAspect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DraggableAspect.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/DraggableAspect.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IACI;;;;;;;;OAQG;IACH;QANgC,EAAE,EAAvB,WAAW;QACkC,SAAS,GAAtD,CAAC,QAAQ,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QAC0C,IAAI,GAAhF,CAAC,QAAQ,EAAC,OAAO,EAAE,MAAM,EAAC,OAAO,EAAE,KAAK,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QACJ,OAAO,GAApE,CAAC,QAAQ,EAAC,OAAO,EAAE,MAAM,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QAChC,eAAe,GAAjC,OAAO;OAuEjB;IApEG;;;;;OAKG;IACH,8BAAyC;IAQnB,+BAA8C;IAwDxE;;;OAGG;IACH,cAFa,aAAa,CAIzB;IAED,cAEC;IAED,aAGC;CACJ;8BAjHyD,mCAAmC;oBADzE,4BAA4B"}
+{"version":3,"file":"DraggableAspect.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/DraggableAspect.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH;IAKI;;;;;;;;;;OAUG;IACH;QARgC,EAAE,EAAvB,WAAW;QACkC,SAAS,GAAtD,CAAC,QAAQ,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QAC0C,IAAI,GAAhF,CAAC,QAAQ,EAAC,OAAO,EAAE,MAAM,EAAC,OAAO,EAAE,KAAK,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QACJ,OAAO,GAApE,CAAC,QAAQ,EAAC,OAAO,EAAE,MAAM,EAAC,OAAO,EAAE,KAAK,EAAC,KAAK,QAAI;QACb,UAAU,GAA/C,CAAC,KAAK,EAAC,KAAK,GAAC,SAAS,QAAI;QAER,eAAe,GAAjC,OAAO;OAkHjB;IA/GG;;;;;OAKG;IACH,8BAAyC;IAQnB,+BAA8C;IAmGxE;;;OAGG;IACH,cAFa,aAAa,CAIzB;IAED,cAMC;IAED,aAOC;;CACJ;8BA1KyD,mCAAmC;oBADzE,4BAA4B"}

package/src/engine/ui/DraggableAspect.js

@@ -17,6 +17,10 @@ import { PointerDevice, readPositionFromMouseEvent } from "../input/devices/Poin
  * @copyright Company Named Limited (c) 2026
  */
 export class DraggableAspect {
+    #started = false;
+    #cancelGesture = noop;
+    #handleCancel = event => this.#cancelGesture(event);
+
     /**
      *
      * @param {Object} options
@@ -24,9 +28,11 @@ export class DraggableAspect {
      * @param {(position:Vector2, event:Event)=>*} [options.dragStart=noop]
      * @param {(position:Vector2, origin:Vector2, delta:Vector2, event:Event)=>*} [options.drag=noop]
      * @param {(position:Vector2, origin:Vector2, event:Event)=>*} [options.dragEnd=noop]
+     * @param {(event:Event|undefined)=>*} [options.dragCancel=noop] called for a cancelled press or drag;
+     *   pointercancel/blur carries its event, while stop() carries undefined. Cancellation never commits dragEnd.
      * @param {boolean} [options.stopPropagation=true] prevent propagation of pointer events up the DOM tree
      */
-    constructor({ el, dragStart = noop, drag = noop, dragEnd = noop, stopPropagation = true }) {
+    constructor({ el, dragStart = noop, drag = noop, dragEnd = noop, dragCancel = noop, stopPropagation = true }) {
         /**
          *
          * @type {PointerDevice}
@@ -48,6 +54,41 @@ export class DraggableAspect {
 
         // top-left corner of `el` in client space, sampled when a drag gesture begins
         const frameOrigin = new Vector2();
+        let pressed = false;
+        let dragging = false;
+        let pointerId = null;
+        let stopDrag = null;
+
+        this.#cancelGesture = event => {
+            if (event?.type === 'pointercancel' && event.pointerId !== pointerId) return;
+            const pending = pressed || dragging;
+            pressed = dragging = false;
+            pointerId = null;
+            if (stopDrag !== null) {
+                pointerGlobal.on.up.remove(stopDrag);
+                stopDrag = null;
+            }
+            pointerGlobal.stop();
+            // An uncaptured pointer can be cancelled outside the local element. Clear its
+            // pending detector before the caller can stop the aspect in dragCancel.
+            if (pending && event?.type === 'pointercancel' && this.#started) {
+                this.pointerLocal.stop();
+                if (this.#started) this.pointerLocal.start();
+            }
+            if (pending) dragCancel(event);
+        };
+
+        this.pointerLocal.on.down.add((p, event) => {
+            if (pressed || dragging) return;
+            pressed = true;
+            pointerId = event.pointerId;
+        });
+        this.pointerLocal.on.globalUp.add((p, event) => {
+            if (!dragging && event.pointerId === pointerId) {
+                pressed = false;
+                pointerId = null;
+            }
+        });
 
         if (stopPropagation) {
             this.pointerLocal.on.down.add((p, e) => {
@@ -56,6 +97,8 @@ export class DraggableAspect {
         }
 
         this.pointerLocal.on.dragStart.add((p, event) => {
+            if (!pressed || dragging || event.pointerId !== pointerId) return;
+            dragging = true;
             // freeze the coordinate frame of `el` for the duration of the gesture
             if (typeof el.getBoundingClientRect === "function") {
                 const rect = el.getBoundingClientRect();
@@ -70,9 +113,14 @@ export class DraggableAspect {
             pointerGlobal.start();
 
             dragStart(p, event);
+            if (!dragging) return;
 
-            function stopDrag(endClientPosition, endEvent) {
+            stopDrag = (endClientPosition, endEvent) => {
+                if (endEvent.pointerId !== pointerId) return;
                 pointerGlobal.on.up.remove(stopDrag);
+                stopDrag = null;
+                pressed = dragging = false;
+                pointerId = null;
                 pointerGlobal.stop();
 
                 position.set(
@@ -81,12 +129,13 @@ export class DraggableAspect {
                 );
 
                 dragEnd(position, dragOriginalPosition, endEvent);
-            }
+            };
 
             pointerGlobal.on.up.add(stopDrag);
         });
 
         this.pointerGlobal.on.move.add((clientPosition, event, delta) => {
+            if (!dragging || event.pointerId !== pointerId) return;
             // the global device reports client coordinates, convert into the frozen frame of `el`
             position.set(
                 clientPosition.x - frameOrigin.x,
@@ -106,11 +155,19 @@ export class DraggableAspect {
     }
 
     start() {
+        this.#started = true;
         this.pointerLocal.start();
+        this.pointerLocal.domElement.addEventListener('pointercancel', this.#handleCancel);
+        window.addEventListener('pointercancel', this.#handleCancel);
+        window.addEventListener('blur', this.#handleCancel);
     }
 
     stop() {
+        this.#started = false;
+        this.pointerLocal.domElement.removeEventListener('pointercancel', this.#handleCancel);
+        window.removeEventListener('pointercancel', this.#handleCancel);
+        window.removeEventListener('blur', this.#handleCancel);
         this.pointerLocal.stop();
-        this.pointerGlobal.stop();
+        this.#cancelGesture();
     }
 }

package/src/format/image/avif/heif/ItemProperty.d.ts

@@ -137,7 +137,7 @@ export class ImageRotation {
     angle: number;
 }
 /**
- * `imir` — mirroring, applied after `clap` and before `irot`.
+ * `imir` — mirroring, applied after `clap` and `irot` in MIAF.
  */
 export class ImageMirror {
     static TYPE: string;

package/src/format/image/avif/heif/ItemProperty.js

@@ -184,7 +184,7 @@ export class ImageRotation {
 }
 
 /**
- * `imir` — mirroring, applied after `clap` and before `irot`.
+ * `imir` — mirroring, applied after `clap` and `irot` in MIAF.
  */
 export class ImageMirror {
     static TYPE = "imir";

package/src/format/image/png/chunk/png_chunk_decode_iTXt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"png_chunk_decode_iTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_iTXt.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,6CAHW,UAAU,GACR,QAAQ;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,CA8CtG"}
+{"version":3,"file":"png_chunk_decode_iTXt.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/png/chunk/png_chunk_decode_iTXt.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,6CAHW,UAAU,GACR,QAAQ;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,CAwDtG"}

package/src/format/image/png/chunk/png_chunk_decode_iTXt.js

@@ -1,4 +1,5 @@
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
+import { utf8_decode } from "../../../../core/binary/utf8/utf8_decode.js";
 import { png_inflate } from "../png_inflate.js";
 
 /**
@@ -16,20 +17,32 @@ export async function png_chunk_decode_iTXt(chunk) {
     const buffer = BinaryBuffer.fromArrayBuffer(chunk_buffer);
     buffer.position = chunk_byte_offset;
 
-    const keyword = buffer.readASCIICharacters(79, true);
+    const keyword = buffer.readASCIICharacters(80, true);
+    if (keyword.length > 79) {
+        throw new Error('iTXt keyword exceeds 79 bytes');
+    }
     const compression_flag = buffer.readUint8();
     const compression_method = buffer.readUint8();
 
 
     const language_tag = buffer.readASCIICharacters(Number.MAX_SAFE_INTEGER, true);
-    const translated_keyword = buffer.readASCIICharacters(Number.MAX_SAFE_INTEGER, true);
+    const translated_start = buffer.position - chunk_byte_offset;
+    let translated_end = translated_start;
+    while (translated_end < chunk_size && chunk[translated_end] !== 0) {
+        translated_end++;
+    }
+    if (translated_end >= chunk_size) {
+        throw new Error('iTXt translated keyword is not terminated');
+    }
+    const translated_keyword = utf8_decode(chunk, translated_start, translated_end);
+    buffer.position = chunk_byte_offset + translated_end + 1;
 
     const remaining_bytes = chunk_byte_end - buffer.position;
 
     let text;
 
     if (compression_flag === 0) {
-        text = buffer.readASCIICharacters(remaining_bytes);
+        text = utf8_decode(chunk, buffer.position - chunk_byte_offset, chunk_size);
     } else if (compression_flag === 1) {
 
         if (compression_method !== 0) {
@@ -38,9 +51,7 @@ export async function png_chunk_decode_iTXt(chunk) {
 
         const decoded = await png_inflate([new Uint8Array(buffer.data, buffer.position, remaining_bytes)]);
 
-        buffer.fromArrayBuffer(decoded.buffer);
-
-        text = buffer.readASCIICharacters(decoded.byteLength);
+        text = utf8_decode(decoded);
     } else {
         throw new Error(`Invalid compression flag value '${compression_flag}'`);
     }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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