@woosh/meep-engine 3.30.0 → 3.31.0

package/src/engine/sound/sopra/runtime/BusGraph.d.ts

@@ -34,6 +34,23 @@ export class BusGraph {
      * @param {BusDefinition[]} definitions
      */
     build(definitions: BusDefinition[]): void;
+    /**
+     * Unwire everything this graph built and forget it.
+     *
+     * `build` connects each root bus into the engine destination, and nothing ever took them back
+     * out: {@link SopraEngine.setBuses} replaced the graph and left the old tree connected, so two
+     * mixers summed into the destination at once — the old one audible but unreachable, because
+     * every volume, duck and snapshot call then addressed the new graph's nodes — and the old tree
+     * could never be collected, because the destination still referenced it.
+     *
+     * A live {@link EventInstance} captured its bus input node once when its chain was built and
+     * goes on feeding it, so a disposed graph keeps whatever is playing alive until those instances
+     * finish — but silent, since nothing it holds reaches the destination any more. Swap the mixer
+     * between scenes, or stop what is playing first.
+     *
+     * Idempotent.
+     */
+    dispose(): void;
     /**
      * @param {string} id
      * @returns {boolean}
@@ -58,6 +75,18 @@ export class BusGraph {
      */
     getVolume(id: string): number;
     /**
+     * Move a bus's fader to `linear`, now.
+     *
+     * Cancel-then-anchor at `currentTime`, the same order {@link rampGain}
+     * uses, because Web Audio keeps a time-ORDERED automation list: a bare
+     * `setValueAtTime` stamped at 0 sorts to the head of it, ahead of the
+     * `linearRampToValueAtTime` a snapshot blend scheduled and the
+     * `setTargetAtTime` a duck scheduled, and has no effect on the audible
+     * value from `currentTime` on — while `nominal`, which {@link getVolume}
+     * and the ducker's restore read, has already moved. The node and the
+     * bookkeeping came apart in exactly the two situations a player is most
+     * likely to be moving a volume slider.
+     *
      * @param {string} id
      * @param {number} linear linear gain
      */

package/src/engine/sound/sopra/runtime/BusGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BusGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/BusGraph.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;GAIG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH;IAkBI;;;OAGG;IACH,iBAHW,gBAAgB,eAChB,SAAS,EAKnB;IAvBD;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE;QAAC,UAAU,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAEpE;IAqBlB;;;;OAIG;IACH,mBAFW,aAAa,EAAE,QAgFzB;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAoBD;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,cAHW,MAAM,UACN,MAAM,QAOhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAQhB;;CACJ;4BArOY,OAAO,gCAAgC,EAAE,aAAa"}
+{"version":3,"file":"BusGraph.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/BusGraph.js"],"names":[],"mappings":"AAIA;;GAEG;AAEH;;;;GAIG;AACH,8BAFU,MAAM,CAEkB;AAElC;;;;;GAKG;AACH;IAkBI;;;OAGG;IACH,iBAHW,gBAAgB,eAChB,SAAS,EAKnB;IAvBD;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE;QAAC,UAAU,EAAE,aAAa,CAAC;QAAC,KAAK,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,QAAQ,CAAA;KAAC,CAAC,CAEpE;IAqBlB;;;;OAIG;IACH,mBAFW,aAAa,EAAE,QA4FzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,gBAcC;IAED;;;OAGG;IACH,QAHW,MAAM,GACJ,OAAO,CAInB;IAoBD;;;;OAIG;IACH,aAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;;;OAKG;IACH,cAHW,MAAM,GACJ,SAAS,CAIrB;IAED;;;OAGG;IACH,cAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,cAHW,MAAM,UACN,MAAM,QAkBhB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,eALW,MAAM,UACN,MAAM,YACN,MAAM,eACN,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,mBAJW,MAAM,UACN,MAAM,gBACN,MAAM,QAQhB;;CACJ;4BAxSY,OAAO,gCAAgC,EAAE,aAAa"}

package/src/engine/sound/sopra/runtime/BusGraph.js

@@ -64,6 +64,10 @@ export class BusGraph {
 
             let input = gain;
 
+            // every node this bus owns, so {@link dispose} can unwire the lot rather than only the
+            // ends of the chain
+            const chain = [];
+
             const effects = def.effects;
 
             if (effects.length > 0) {
@@ -72,6 +76,12 @@ export class BusGraph {
                 for (let e = 0; e < effects.length; e++) {
                     const built = effects[e].build(ctx);
 
+                    chain.push(built.input);
+
+                    if (built.output !== built.input) {
+                        chain.push(built.output);
+                    }
+
                     if (previousOutput === null) {
                         // first effect is the chain head
                         input = built.input;
@@ -90,7 +100,7 @@ export class BusGraph {
             // node's instantaneous `.value` — which WebAudio does NOT update under ramps/setTargetAtTime.
             // get/setVolume read/write `nominal`; ducking (approachVolume) is a transient modulation that
             // deliberately does NOT touch it, so the duck can capture + restore the true nominal.
-            this.buses.set(def.id, { definition: def, input, output: gain, nominal });
+            this.buses.set(def.id, { definition: def, input, output: gain, nominal, chain, sends: [] });
         }
 
         // pass 2: route each bus output to its parent's input (or the engine destination)
@@ -127,10 +137,44 @@ export class BusGraph {
 
                 bus.output.connect(sendGain);
                 sendGain.connect(target.input);
+
+                bus.sends.push(sendGain);
             }
         }
     }
 
+    /**
+     * Unwire everything this graph built and forget it.
+     *
+     * `build` connects each root bus into the engine destination, and nothing ever took them back
+     * out: {@link SopraEngine.setBuses} replaced the graph and left the old tree connected, so two
+     * mixers summed into the destination at once — the old one audible but unreachable, because
+     * every volume, duck and snapshot call then addressed the new graph's nodes — and the old tree
+     * could never be collected, because the destination still referenced it.
+     *
+     * A live {@link EventInstance} captured its bus input node once when its chain was built and
+     * goes on feeding it, so a disposed graph keeps whatever is playing alive until those instances
+     * finish — but silent, since nothing it holds reaches the destination any more. Swap the mixer
+     * between scenes, or stop what is playing first.
+     *
+     * Idempotent.
+     */
+    dispose() {
+        for (const bus of this.buses.values()) {
+            bus.output.disconnect();
+
+            for (let i = 0; i < bus.chain.length; i++) {
+                bus.chain[i].disconnect();
+            }
+
+            for (let i = 0; i < bus.sends.length; i++) {
+                bus.sends[i].disconnect();
+            }
+        }
+
+        this.buses.clear();
+    }
+
     /**
      * @param {string} id
      * @returns {boolean}
@@ -185,6 +229,18 @@ export class BusGraph {
     }
 
     /**
+     * Move a bus's fader to `linear`, now.
+     *
+     * Cancel-then-anchor at `currentTime`, the same order {@link rampGain}
+     * uses, because Web Audio keeps a time-ORDERED automation list: a bare
+     * `setValueAtTime` stamped at 0 sorts to the head of it, ahead of the
+     * `linearRampToValueAtTime` a snapshot blend scheduled and the
+     * `setTargetAtTime` a duck scheduled, and has no effect on the audible
+     * value from `currentTime` on — while `nominal`, which {@link getVolume}
+     * and the ducker's restore read, has already moved. The node and the
+     * bookkeeping came apart in exactly the two situations a player is most
+     * likely to be moving a volume slider.
+     *
      * @param {string} id
      * @param {number} linear linear gain
      */
@@ -192,7 +248,18 @@ export class BusGraph {
         const bus = this.#bus(id);
 
         bus.nominal = linear;
-        bus.output.gain.setValueAtTime(linear, 0);
+
+        const param = bus.output.gain;
+        const now = this.#ctx.currentTime;
+
+        if (typeof param.cancelAndHoldAtTime === "function") {
+            param.cancelAndHoldAtTime(now);
+        } else {
+            // portable fallback (Firefox), as in `rampGain`
+            param.cancelScheduledValues(now);
+        }
+
+        param.setValueAtTime(linear, now);
     }
 
     /**

package/src/engine/sound/sopra/runtime/EventInstance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EventInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/EventInstance.js"],"names":[],"mappings":";;;iCAqBU,MAAM;;;;;;AAoFhB;;;;;;;;;GASG;AACH;IAqII;;;;OAIG;IACH,oBAJW,WAAW,eACX,gBAAgB,qIAChB;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,EAAC,oBAAoB,CAAC;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,WAAW,CAAC,EAAC,UAAU,CAAC;QAAC,WAAW,CAAC,EAAC,mBAAmB,CAAA;KAAC,EA0EnQ;IAhND;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,OAFU,kBAAkB,GAAC,MAAM,CAEA;IAEnC;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAAuB;IAyHnB;;OAEG;IACH,QAFU,WAAW,CAED;IAEpB;;OAEG;IACH,aAFU,gBAAgB,CAEI;IAE9B;;OAEG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,OAAO,GAAC,IAAI,CAEE;IAExB;;;;;OAKG;IACH,aAFU,UAAU,GAAC,IAAI,CAEK;IAE9B;;;;;OAKG;IACH,aAFU,mBAAmB,GAAC,IAAI,CAEJ;IAE9B;;OAEG;IACH,SAFU,OAAO,CAEK;IAEtB;;OAEG;IACH,oBAFU,MAAM,CAEqB;IAErC;;OAEG;IACH,iBAFU,oBAAoB,CAEQ;IAW1C;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,2CAeC;IAED;;;OAGG;IACH,WAFW,MAAM,QAyChB;IAoID;;;OAGG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;;;;;;;OAWG;IACH,sBAFW,gBAAgB,QA8C1B;IAED;;;;;OAKG;IACH,uBAJW,MAAM,YACN,MAAM,eACN,MAAM,QAQhB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,eACN,MAAM,QAYhB;IAED;;;;OAIG;IACH,cAFW,MAAM,QAehB;IAED;;OAEG;IACH,gBAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,oBACN,OAAO,GAAC,IAAI,QAkDtB;IAmGD;;OAEG;IACH,aAsCC;;CACJ;yBA91BY,OAAO,qCAAqC,EAAE,UAAU;sBACxD,OAAO,kCAAkC,EAAE,OAAO;+BAClD,OAAO,2CAA2C,EAAE,gBAAgB;kCACpE,OAAO,oDAAoD,EAAE,mBAAmB;0BAChF,OAAO,mBAAmB,EAAE,WAAW;+BACvC,OAAO,mCAAmC,EAAE,gBAAgB;mCAC5D,OAAO,2BAA2B,EAAE,oBAAoB;oBACxD,OAAO,YAAY,EAAE,KAAK"}
+{"version":3,"file":"EventInstance.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/sound/sopra/runtime/EventInstance.js"],"names":[],"mappings":";;;iCAqBU,MAAM;;;;;;AAoFhB;;;;;;;;;GASG;AACH;IAkLI;;;;OAIG;IACH,oBAJW,WAAW,eACX,gBAAgB,qIAChB;QAAC,KAAK,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,WAAW,CAAC,EAAC,MAAM,CAAC;QAAC,eAAe,CAAC,EAAC,oBAAoB,CAAC;QAAC,SAAS,CAAC,EAAC,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAC,OAAO,CAAC;QAAC,OAAO,CAAC,EAAC,OAAO,CAAC;QAAC,YAAY,CAAC,EAAC,MAAM,CAAC;QAAC,WAAW,CAAC,EAAC,UAAU,CAAC;QAAC,WAAW,CAAC,EAAC,mBAAmB,CAAA;KAAC,EA0EnQ;IA7PD;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;OAEG;IACH,OAFU,kBAAkB,GAAC,MAAM,CAEA;IAEnC;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;;OAKG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAAuB;IAsKnB;;OAEG;IACH,QAFU,WAAW,CAED;IAEpB;;OAEG;IACH,aAFU,gBAAgB,CAEI;IAE9B;;OAEG;IACH,OAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,UAFU,OAAO,GAAC,IAAI,CAEE;IAExB;;;;;OAKG;IACH,aAFU,UAAU,GAAC,IAAI,CAEK;IAE9B;;;;;OAKG;IACH,aAFU,mBAAmB,GAAC,IAAI,CAEJ;IAE9B;;OAEG;IACH,SAFU,OAAO,CAEK;IAEtB;;OAEG;IACH,oBAFU,MAAM,CAEqB;IAErC;;OAEG;IACH,iBAFU,oBAAoB,CAEQ;IAW1C;;;OAGG;IACH,uBAEC;IAED;;;OAGG;IACH,2CAeC;IAED;;;OAGG;IACH,WAFW,MAAM,QAyChB;IAwJD;;;OAGG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;;;;;;;OAWG;IACH,sBAFW,gBAAgB,QAgE1B;IAED;;;;;OAKG;IACH,uBAJW,MAAM,YACN,MAAM,eACN,MAAM,QAqBhB;IAED;;;;;OAKG;IACH,yBAHW,MAAM,eACN,MAAM,QAqBhB;IAED;;;;OAIG;IACH,cAFW,MAAM,QAehB;IAED;;OAEG;IACH,gBAEC;IAED;;;;;OAKG;IACH,YAHW,MAAM,oBACN,OAAO,GAAC,IAAI,QA8DtB;IAuGD;;OAEG;IACH,aAsCC;;CACJ;yBAv9BY,OAAO,qCAAqC,EAAE,UAAU;sBACxD,OAAO,kCAAkC,EAAE,OAAO;+BAClD,OAAO,2CAA2C,EAAE,gBAAgB;kCACpE,OAAO,oDAAoD,EAAE,mBAAmB;0BAChF,OAAO,mBAAmB,EAAE,WAAW;+BACvC,OAAO,mCAAmC,EAAE,gBAAgB;mCAC5D,OAAO,2BAA2B,EAAE,oBAAoB;oBACxD,OAAO,YAAY,EAAE,KAAK"}

package/src/engine/sound/sopra/runtime/EventInstance.js

@@ -162,6 +162,28 @@ export class EventInstance {
      */
     #totalDuration = 0;
 
+    /**
+     * Whether this instance releases itself once its timeline is exhausted.
+     *
+     * A one-shot always does. A NON-one-shot does too when it was only marked
+     * persistent by a clip that merely *can* loop: `loops()` is conservative —
+     * true if ANY reachable child loops — while the pick is made per instance
+     * by `planTimeline`. A random container over a looping wind bed and a
+     * short gust is ordinary layered ambience, and an instance that drew the
+     * gust would otherwise retire its leaves as their windows passed and then
+     * sit in `Playing` with zero voices and no `onEnded` forever, holding one
+     * of the live set's budget slots and one `maxInstances` slot.
+     *
+     * A caller that asked for a non-one-shot over statically FINITE content
+     * still owns that instance's lifetime, which is the documented contract
+     * and what `eventInstanceControl.spec.js` calls the deliberate foot-gun.
+     *
+     * Decided in {@link #resolve}, because the resolved timeline is the only
+     * thing that knows which child was drawn.
+     * @type {boolean}
+     */
+    #selfReleases = false;
+
     /**
      * Node that voices route into: the instance's attenuation gain (3D) or the bus input (2D).
      * @type {AudioNode|null}
@@ -191,6 +213,29 @@ export class EventInstance {
      */
     #gainDb = 0;
 
+    /**
+     * A fade asked for before the output chain existed, replayed by
+     * {@link #buildOutputChain}.
+     *
+     * `#instanceGain` does not exist until {@link #resolve}, which for a buffer
+     * that is not already decoded is one or more microtasks after `playEvent`
+     * returns — the normal case on a level load. Both fades used to guard on
+     * the node and quietly skip the ramp, while `fadeToGainDb` had already
+     * recorded its TARGET: the chain was then built AT the target with no ramp
+     * at all, so `crossfade`'s `setGainDb(nominal - 60)` + `fadeToGainDb(
+     * nominal, duration)` brought the new track in at full volume instantly,
+     * on precisely the transitions the API exists to smooth.
+     *
+     * `fromLinear` is the gain the chain is built at, so the ramp has an
+     * origin. `untilDeadline` marks a fade-OUT, whose end is already fixed in
+     * {@link #stopDeadline} and so is measured against that rather than
+     * restarted; a fade-IN takes the duration the caller asked for, counted
+     * from the moment the sound actually starts.
+     *
+     * @type {{fromLinear:number, targetLinear:number, duration:number, startAfter:number, untilDeadline:boolean}|null}
+     */
+    #pendingFade = null;
+
     /**
      * Audio-clock time at which a scheduled fade-out stops the instance; Infinity = none.
      * @type {number}
@@ -433,6 +478,7 @@ export class EventInstance {
 
         this.#timeline = timeline;
         this.#totalDuration = duration;
+        this.#selfReleases = this.oneShot || this.description.rootClip.loops();
 
         this.#buildOutputChain();
 
@@ -447,8 +493,27 @@ export class EventInstance {
         const description = this.description;
 
         // the instance gain is the uniform chain head (2D and 3D), so live volume/fades have one home
+        const pending = this.#pendingFade;
+
         this.#instanceGain = ctx.createGain();
-        this.#instanceGain.gain.setValueAtTime(dB2Volume(this.#gainDb), 0);
+        // a fade asked for while loading is built at its ORIGIN, not its target
+        this.#instanceGain.gain.setValueAtTime(
+            pending === null ? dB2Volume(this.#gainDb) : pending.fromLinear, 0
+        );
+
+        if (pending !== null) {
+            this.#pendingFade = null;
+
+            // a fade-out's end is already fixed; a fade-in takes the duration
+            // the caller asked for, from the moment the sound starts
+            const duration = pending.untilDeadline
+                ? Math.max(0, this.#stopDeadline - engine.currentTime)
+                : pending.duration;
+
+            const startAfter = pending.untilDeadline ? 0 : pending.startAfter;
+
+            rampGain(this.#instanceGain.gain, pending.targetLinear, duration, ctx, startAfter);
+        }
 
         if (description.is3D) {
             this.#attenuationGain = ctx.createGain();
@@ -582,9 +647,21 @@ export class EventInstance {
             // × the band's LOW-ANCHORED air tilt (only the high-vs-low excess darkens — a uniform loss is the
             // distance curve's job). So transmission [1,0,0] passes lows and cuts mid/high; a distant source
             // loses its top end. Low is the anchor (no air tilt).
-            const gLow = dir * ((1 - occlusion) + occlusion * transmission[0]);
-            const gMid = dir * ((1 - occlusion) + occlusion * transmission[1]) * dbTiltToGain(airLoss[1] - airLoss[0]);
-            const gHigh = dir * ((1 - occlusion) + occlusion * transmission[2]) * dbTiltToGain(airLoss[2] - airLoss[0]);
+            //
+            // `transmission` is a fraction of ENERGY — AcousticMaterial's whole set is, its sibling
+            // `absorption` being consumed as `energy *= 1 - absorption` in the reflection trace — and a
+            // GainNode takes AMPLITUDE. This is the one seam between the two domains, so the square root
+            // lives here. Written straight in, an energy ratio used as an amplitude ratio is off by a
+            // factor of two in decibels: a wall authored at [0.01, 0.001, 0.0001], a plausible 20/30/40 dB
+            // of transmission loss, rendered at 40/60/80 and a source behind it was inaudible where the
+            // author asked for muffled.
+            const aLow = Math.sqrt(transmission[0]);
+            const aMid = Math.sqrt(transmission[1]);
+            const aHigh = Math.sqrt(transmission[2]);
+
+            const gLow = dir * ((1 - occlusion) + occlusion * aLow);
+            const gMid = dir * ((1 - occlusion) + occlusion * aMid) * dbTiltToGain(airLoss[1] - airLoss[0]);
+            const gHigh = dir * ((1 - occlusion) + occlusion * aHigh) * dbTiltToGain(airLoss[2] - airLoss[0]);
 
             set3BandGains(this.#acoustic3Band, gLow, gMid, gHigh, now);
         }
@@ -602,12 +679,18 @@ export class EventInstance {
                 // per-band leak gain = the BROADBAND geometric leak strength (solution.pathGain = occlusion ×
                 // falloff × directivity-toward-the-leak × turn gates) × (1 − that band's transmission: the energy
                 // NOT through the wall goes around) × the LOW-ANCHORED air tilt over the longer leaked route.
+                //
+                // Square-rooted for the same reason as the direct path: `1 - transmission` is the ENERGY that
+                // did not get through, and this is a gain. It is also what makes the split exact — the direct
+                // send carries `transmission` of the energy and this one carries the rest, and the two
+                // amplitudes square back to 1. Written linearly they summed to one in AMPLITUDE instead, so a
+                // wall at 0.25 sent 0.25 + 0.5625 of the energy on and the remainder simply vanished.
                 const transmission = solution.transmission;
                 const pathAir = solution.pathAirLoss;
                 const p = solution.pathGain;
-                const lLow = p * (1 - transmission[0]);
-                const lMid = p * (1 - transmission[1]) * dbTiltToGain(pathAir[1] - pathAir[0]);
-                const lHigh = p * (1 - transmission[2]) * dbTiltToGain(pathAir[2] - pathAir[0]);
+                const lLow = p * Math.sqrt(1 - transmission[0]);
+                const lMid = p * Math.sqrt(1 - transmission[1]) * dbTiltToGain(pathAir[1] - pathAir[0]);
+                const lHigh = p * Math.sqrt(1 - transmission[2]) * dbTiltToGain(pathAir[2] - pathAir[0]);
                 set3BandGains(this.#leak3Band, lLow, lMid, lHigh, now);
             } else {
                 set3BandGains(this.#leak3Band, 0, 0, 0, now);
@@ -622,11 +705,24 @@ export class EventInstance {
      * @param {number} [startAfter=0] seconds
      */
     fadeToGainDb(targetDb, duration, startAfter = 0) {
+        const fromLinear = dB2Volume(this.#gainDb);
+
         this.#gainDb = targetDb;
 
         if (this.#instanceGain !== null) {
             rampGain(this.#instanceGain.gain, dB2Volume(targetDb), duration, this.engine.audioContext, startAfter);
+
+            return;
         }
+
+        // still loading — see {@link #pendingFade}
+        this.#pendingFade = {
+            fromLinear,
+            targetLinear: dB2Volume(targetDb),
+            duration,
+            startAfter,
+            untilDeadline: false
+        };
     }
 
     /**
@@ -642,6 +738,15 @@ export class EventInstance {
 
         if (this.#instanceGain !== null) {
             rampGain(this.#instanceGain.gain, FADE_EPSILON, duration, this.engine.audioContext, startAfter);
+        } else {
+            // still loading — see {@link #pendingFade}
+            this.#pendingFade = {
+                fromLinear: dB2Volume(this.#gainDb),
+                targetLinear: FADE_EPSILON,
+                duration,
+                startAfter,
+                untilDeadline: true
+            };
         }
 
         this.#stopDeadline = this.engine.currentTime + startAfter + duration;
@@ -686,10 +791,22 @@ export class EventInstance {
         }
 
         if (this.#timeline === null) {
-            // still loading — only the lifetime backstop applies
+            // Still loading. The fade-out deadline applies all the same: it was
+            // set when the fade was asked for, and returning before looking at
+            // it meant an instance told to fade out and stop before its buffer
+            // arrived was built at full gain, sounded for a frame and was then
+            // cut.
+            if (now >= this.#stopDeadline) {
+                this.stop();
+
+                return;
+            }
+
+            // and the lifetime backstop
             if (this.oneShot && (now - this.startedAt) > this.maxLifetimeSeconds) {
                 this.stop();
             }
+
             return;
         }
 
@@ -759,7 +876,11 @@ export class EventInstance {
             }
         }
 
-        if (this.oneShot && this.#totalDuration !== Infinity && playhead >= this.#totalDuration) {
+        // See {@link #selfReleases}: a genuinely looping pick has
+        // `#totalDuration === Infinity` and never reaches this, and the
+        // `maxLifetimeSeconds` backstop stays gated on `oneShot`, because a
+        // persistent emitter is supposed to outlive it.
+        if (this.#selfReleases && this.#totalDuration !== Infinity && playhead >= this.#totalDuration) {
             this.stop();
         }
     }

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

@@ -27,6 +27,20 @@ declare class GUIEngine {
      * @type {Engine}
      */
     engine: Engine;
+    /**
+     * The closure `startup` subscribes to `engine.gameView.size`, held so
+     * `shutdown` can take it off again.
+     * @type {((x:number, y:number) => void)|null}
+     * @private
+     */
+    private __game_view_size_handler;
+    /**
+     * The closure `startup` subscribes to {@link cursor}; it captures the
+     * engine, so it is dropped on shutdown too.
+     * @type {((newValue:string, oldValue:string) => void)|null}
+     * @private
+     */
+    private __cursor_handler;
     /**
      *
      * @type {WeakMap<Scene, SceneGUIContext>}

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

@@ -1 +1 @@
-{"version":3,"file":"GUIEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/GUIEngine.js"],"names":[],"mappings":";8BA4Ba,OAAO,qCAAqC,EAAE,OAAO;;2BAKrD,OAAO,yCAAyC,EAAE,YAAY;qBAC9D,OAAO,cAAc,EAAE,OAAO;4BAC9B,OAAO,yBAAyB,EAAE,aAAa;oBAC/C,OAAO,mBAAmB,EAAE,OAAO;AAThD;;;GAGG;AAEH;;;;;GAKG;AAGH;IACI,mBAAqB;IAErB;;;OAGG;IACH,eAFU,aAAa,GAAC,IAAI,CAEP;IAErB;;;OAGG;IACH,QAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,eAFU,QAAQ,KAAK,EAAE,eAAe,CAAC,CAEX;IAE9B;;;OAGG;IACH,UAFU,cAAc,CAEQ;IAEhC;;;OAGG;IACH,cAFU,iBAAiB,CAEyB;IAGpD;;;OAGG;IACH,QAFU,MAAM,CAEM;IAEtB,gBAOG;IAEH;;;OAGG;IACH,KAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,QAFU,cAAc,CAEuB;IAG/C;;;OAGG;IACH,cAFU,YAAY,GAAC,IAAI,CAEP;IAqBpB;;;;;;;OAOG;IACH;QAN4B,SAAS,EAA1B,OAAO;QACO,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACS,OAAO,GAAtB,IAAI;QACF,MAAM,CAoClB;IAED;;;;;;;OAOG;IACH;QALyB,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACU,QAAQ,EAAxB,MAAM;QACJ,eAAe,CA+D3B;IAED;;;;;;;OAOG;IACH;QAL2B,KAAK,EAArB,MAAM;QACQ,OAAO,EAArB,IAAI;QACyC,mBAAmB,GAAhE,eAAe,0FAAmB;QAChC,QAAQ,GAAG,CAAC,CA0DxB;IAED;;;;;OAKG;IACH;QAJ2B,IAAI,EAApB,MAAM;QACU,KAAK,EAArB,MAAM;qBAUhB;IAED;;;;;;OAMG;IACH;QAJ2B,IAAI,EAApB,MAAM;QACU,KAAK,EAArB,MAAM;qBAShB;IAED;;;;;;;;;OASG;IACH;QAPyB,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACW,KAAK,GAAtB,IAAI,EAAE;QACU,QAAQ,EAAxB,MAAM;QAC8B,aAAa,UAAxC,eAAe;qBAsDlC;IAED;;;;OAIG;IACH,0BAHW,KAAK,GACJ,eAAe,CAgB1B;IAED;;OAEG;IACH,yBAFa,eAAe,GAAC,IAAI,CAkBhC;IAED;;;OAGG;IACH,8BAKC;IAED;;;OAGG;IACH,gBAFW,MAAM,kBAmEhB;IAED,2BAkBC;CACJ;iBAhiBgB,oCAAoC;gCAyBrB,4BAA4B;+BAf7B,sCAAsC;kCAFnC,yCAAyC;mBAexD,yBAAyB;sBAjBtB,kCAAkC;0BAG9B,qCAAqC;2BAPpC,oCAAoC;iBAU9C,oBAAoB;mBAOlB,kBAAkB;gCAhBqB,uCAAuC"}
+{"version":3,"file":"GUIEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/GUIEngine.js"],"names":[],"mappings":";8BA4Ba,OAAO,qCAAqC,EAAE,OAAO;;2BAKrD,OAAO,yCAAyC,EAAE,YAAY;qBAC9D,OAAO,cAAc,EAAE,OAAO;4BAC9B,OAAO,yBAAyB,EAAE,aAAa;oBAC/C,OAAO,mBAAmB,EAAE,OAAO;AAThD;;;GAGG;AAEH;;;;;GAKG;AAGH;IACI,mBAAqB;IAErB;;;OAGG;IACH,eAFU,aAAa,GAAC,IAAI,CAEP;IAErB;;;OAGG;IACH,QAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,iCAAgC;IAEhC;;;;;OAKG;IACH,yBAAwB;IAExB;;;OAGG;IACH,eAFU,QAAQ,KAAK,EAAE,eAAe,CAAC,CAEX;IAE9B;;;OAGG;IACH,UAFU,cAAc,CAEQ;IAEhC;;;OAGG;IACH,cAFU,iBAAiB,CAEyB;IAGpD;;;OAGG;IACH,QAFU,MAAM,CAEM;IAEtB,gBAOG;IAEH;;;OAGG;IACH,KAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,QAFU,cAAc,CAEuB;IAG/C;;;OAGG;IACH,cAFU,YAAY,GAAC,IAAI,CAEP;IAqBpB;;;;;;;OAOG;IACH;QAN4B,SAAS,EAA1B,OAAO;QACO,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACS,OAAO,GAAtB,IAAI;QACF,MAAM,CAoClB;IAED;;;;;;;OAOG;IACH;QALyB,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACU,QAAQ,EAAxB,MAAM;QACJ,eAAe,CA+D3B;IAED;;;;;;;OAOG;IACH;QAL2B,KAAK,EAArB,MAAM;QACQ,OAAO,EAArB,IAAI;QACyC,mBAAmB,GAAhE,eAAe,0FAAmB;QAChC,QAAQ,GAAG,CAAC,CA0DxB;IAED;;;;;OAKG;IACH;QAJ2B,IAAI,EAApB,MAAM;QACU,KAAK,EAArB,MAAM;qBAUhB;IAED;;;;;;OAMG;IACH;QAJ2B,IAAI,EAApB,MAAM;QACU,KAAK,EAArB,MAAM;qBAShB;IAED;;;;;;;;;OASG;IACH;QAPyB,OAAO,EAArB,IAAI;QACY,KAAK,EAArB,MAAM;QACW,KAAK,GAAtB,IAAI,EAAE;QACU,QAAQ,EAAxB,MAAM;QAC8B,aAAa,UAAxC,eAAe;qBAsDlC;IAED;;;;OAIG;IACH,0BAHW,KAAK,GACJ,eAAe,CAgB1B;IAED;;OAEG;IACH,yBAFa,eAAe,GAAC,IAAI,CAkBhC;IAED;;;OAGG;IACH,8BAKC;IAED;;;OAGG;IACH,gBAFW,MAAM,kBA6EhB;IAED,2BAwCC;CACJ;iBAhlBgB,oCAAoC;gCAyBrB,4BAA4B;+BAf7B,sCAAsC;kCAFnC,yCAAyC;mBAexD,yBAAyB;sBAjBtB,kCAAkC;0BAG9B,qCAAqC;2BAPpC,oCAAoC;iBAU9C,oBAAoB;mBAOlB,kBAAkB;gCAhBqB,uCAAuC"}

package/src/engine/ui/GUIEngine.js

@@ -53,6 +53,22 @@ class GUIEngine {
      */
     engine = null;
 
+    /**
+     * The closure `startup` subscribes to `engine.gameView.size`, held so
+     * `shutdown` can take it off again.
+     * @type {((x:number, y:number) => void)|null}
+     * @private
+     */
+    __game_view_size_handler = null;
+
+    /**
+     * The closure `startup` subscribes to {@link cursor}; it captures the
+     * engine, so it is dropped on shutdown too.
+     * @type {((newValue:string, oldValue:string) => void)|null}
+     * @private
+     */
+    __cursor_handler = null;
+
     /**
      *
      * @type {WeakMap<Scene, SceneGUIContext>}
@@ -479,11 +495,19 @@ class GUIEngine {
 
         engine.gameView.addChild(this.view);
 
-        engine.gameView.size.process(function (x, y) {
+        // Kept so `shutdown` can drop it. `gameView` belongs to the engine and
+        // is built once in its constructor, while restart is a supported flow
+        // — a subscription left behind on it outlives the GUI it belonged to,
+        // and this closure holds the whole GUIEngine: its tooltip manager, its
+        // GML engine, its view tree. Every restart would add another, and every
+        // resize would write every torn-down view tree.
+        this.__game_view_size_handler = function (x, y) {
             self.view.size.set(x, y);
 
             self.tooltips.contextView.size.set(x, y);
-        });
+        };
+
+        engine.gameView.size.process(this.__game_view_size_handler);
 
         this.ticker.start();
 
@@ -491,7 +515,7 @@ class GUIEngine {
 
 
         //register cursor propagation
-        this.cursor.process(function (newValue, oldValue) {
+        this.__cursor_handler = function (newValue, oldValue) {
             function className(cursorName) {
                 return `cursor-${cursorName}`;
             }
@@ -512,7 +536,9 @@ class GUIEngine {
             if (typeof newValue === 'string') {
                 classList.add(className(newValue));
             }
-        });
+        };
+
+        this.cursor.process(this.__cursor_handler);
 
         // subscribe to localization changes
         this.localization.locale.onChanged.add(this.__update_localization, this);
@@ -531,7 +557,29 @@ class GUIEngine {
         this.ticker.stop();
 
         this.windows.reset();
+
+        // The same rule as the ticker, for the other three things `startup`
+        // armed. The root and the resize subscription live on `engine.gameView`,
+        // which the engine builds once and keeps; the cursor subscription holds
+        // a closure over the engine.
+        const engine = this.engine;
+
+        if (engine !== null) {
+            engine.gameView.size.onChanged.remove(this.__game_view_size_handler);
+            engine.gameView.removeChild(this.view);
+        }
+
+        this.__game_view_size_handler = null;
+
+        this.cursor.onChanged.remove(this.__cursor_handler);
+        this.__cursor_handler = null;
+
+        // added by `startup`, so a restart would nest a second copy under the
+        // same root and leave the previous session's tooltips in the document
+        this.view.removeChild(this.tooltips.contextView);
+
         this.entityManager = null;
+        this.engine = null;
 
         const pTooltips = this.tooltips.shutdown()
 

package/src/format/image/avif/api/apply_transformations.d.ts

@@ -13,7 +13,8 @@
  * @param {AvifItem} item
  * @param {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}} image
  * @returns {{data: (Uint8ClampedArray|Uint16Array), width: number, height: number}}
- * @see ISO/IEC 23008-12 section 6.5.10 "Image rotation" and 6.5.12 "Image mirroring"
+ * @see ISO/IEC 23008-12 section 6.5.10 "Image rotation" and 6.5.12 "Image mirroring", which also
+ * fix the order the transformative properties apply in: clean aperture, then rotation, then mirror
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026

package/src/format/image/avif/api/apply_transformations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply_transformations.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/apply_transformations.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6EAPW;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GACpE;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAuBlF"}
+{"version":3,"file":"apply_transformations.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/api/apply_transformations.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,6EARW;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GACpE;IAAC,IAAI,EAAE,CAAC,iBAAiB,GAAC,WAAW,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAgClF"}