@woosh/meep-engine 3.30.0 → 3.31.0

package/src/core/process/worker/WorkerBuilder.js

@@ -117,15 +117,26 @@ class WorkerBuilder {
         //api handler
         Array.prototype.push.apply(codeLines, [
             //language=js
-            `function extractTransferables(obj, result) {
+            `function pushTransferableIfUnique(result, value) {
+                // De-duplicated, matching the extractTransferables module this is a copy of.
+                // postMessage rejects a transfer list holding the same object twice with a
+                // DataCloneError, and a result carrying two views over one ArrayBuffer - a header
+                // plus a payload, an interleaved vertex buffer - is the natural shape for a worker
+                // that carves its return value out of one allocation.
+                if (result.indexOf(value) === -1) {
+                    result.push(value);
+                }
+            }
+
+            function extractTransferables(obj, result) {
                 if (obj === null || typeof obj !== "object") {
                     return; //not an object (or null, which typeof reports as "object"), skip
                 } else if (obj instanceof ArrayBuffer) {
-                    result.push(obj);
+                    pushTransferableIfUnique(result, obj);
                 } else if (obj.buffer instanceof ArrayBuffer) {
-                    result.push(obj.buffer);
+                    pushTransferableIfUnique(result, obj.buffer);
                 } else if (typeof ImageBitmap !== "undefined" && obj instanceof ImageBitmap) {
-                    result.push(obj);
+                    pushTransferableIfUnique(result, obj);
                 } else {
                     for (var i in obj) {
                         if (obj.hasOwnProperty(i)) {
@@ -169,7 +180,18 @@ class WorkerBuilder {
                         
                         if(method_result != null && typeof method_result.then === "function"){
                             // thenable
-                            method_result.then(sendResult, sendError);
+                            //
+                            // sendResult can throw - postMessage refuses a value it cannot
+                            // structured-clone - and on this path there is no enclosing try, so
+                            // the throw used to escape as an in-worker unhandled rejection and the
+                            // caller's request never settled. Report it instead.
+                            method_result.then(function (value) {
+                                try {
+                                    sendResult(value);
+                                } catch (e) {
+                                    sendError(e);
+                                }
+                            }, sendError);
                         }else{
                             // straight value
                             sendResult(method_result);

package/src/engine/Clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAIC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA/HgB,4BAA4B"}
+{"version":3,"file":"Clock.d.ts","sourceRoot":"","sources":["../../../src/engine/Clock.js"],"names":[],"mappings":";AAcA;;GAEG;AACH;IAEI;;;;OAIG;IACH,0BAAsB;IAEtB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,oBAAoB;IAGpB;;;;;;OAMG;IACH,gBAHU,IAAI,CAGM;IAMpB;;;OAGG;IACH,0BAEC;IAED;;;OAGG;IACH,yBAEC;IAED,cAIC;IAED,aAEC;IAED,cAeC;IAED;;;OAGG;IACH,YAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,qBAFa,MAAM,CAOlB;IAED;;;;OAIG;IACH,kBAFY,MAAM,CAIjB;IAED,cAGC;CACJ;iBA1IgB,4BAA4B"}

package/src/engine/Clock.js

@@ -85,6 +85,17 @@ class Clock {
     }
 
     pause() {
+        if (!this.__isRunning) {
+            // Already stopped. The free `updateElapsedTime` below has no running guard, unlike the
+            // method of the same name, so pausing a stopped clock used to add the whole interval
+            // it spent stopped to `elapsedTime` - a tab backgrounded for ten minutes and then
+            // paused again by the context-loss timer appended 600 seconds to simulation time,
+            // which `Engine.render` reads as the anchor for particle, animation and exposure
+            // stepping. It also fired at the Ticker's constructor, where pausing a fresh clock
+            // seeded elapsedTime with performance.now().
+            return;
+        }
+
         this.__isRunning = false;
         //update time
         updateElapsedTime(this);

package/src/engine/Engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAoCa,OAAO,8BAA8B,EAAE,cAAc;AA6BlE;IA4EI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OA2OjB;IAhSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IA4BF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IA6BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BAgCC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBA0EC;IAqBD;;OAEG;IACH,sBAyCC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BAzyB8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAejG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAtC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}
+{"version":3,"file":"Engine.d.ts","sourceRoot":"","sources":["../../../src/engine/Engine.js"],"names":[],"mappings":";6BAoCa,OAAO,8BAA8B,EAAE,cAAc;AAwClE;IAiGI;;;;;;;;;OASG;IACH,sBARW,cAAc;QAEU,aAAa,GAArC,aAAa;QACK,cAAc,GAAhC,OAAO;QACW,WAAW,GAA7B,OAAO;QACW,KAAK,GAAvB,OAAO;OA+OjB;IApSD;;;OAGG;IACH,UAFU,cAAc,GAAC,IAAI,CAEb;IAEhB;;;OAGG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAEb,qBAA4B;IAE5B;;;;;;;;;OASG;IACH,0BAFU,uBAAuB,CAEe;IAEhD;;;OAGG;IACH,kBAFU,mBAAmB,CAEO;IAEpC;;;;OAIG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,mBAFU,kBAAkB,CAEa;IAoBrC;;;OAGG;IACH,UAFU,cAAc,CAEA;IAKxB;;;OAGG;IACH,aAFU,gBAAgB,CAEe;IAGzC,yCAAkE;IAK9D,6BAAkC;IAMtC;;;OAGG;IACH,cAFU,aAAa,MAAM,CAAC,CAK5B;IAEF,8CAiCE;IAgCF;;;OAGG;IACH,SAFU,WAAW,CAEoB;IAEzC;;;OAGG;IACH,oCAA0C;IAE1C;;;OAGG;IACH,sCAFU,2BAA2B,CAE+B;IAEpE,yBAAoC;IAGpC;;OAEG;IACH,aAAkB;IAElB;;;OAGG;IACH,SAFU,OAAO,CAEwB;IAGzC,2BAAsC;IAuCtC;;;OAGG;IACH,KAFU,SAAS,CAEO;IAE1B;;;OAGG;IACH,uBAFU,YAAY,CAEqD;IAI3E;;;;MAIC;IA6BD;;;OAGG;IACH,kBAFU,OAAO,CAEW;IAwIhC,wBAgCC;IApBG,oBAAwB;IAsB5B,2BA8CC;IAED,oBAiBC;IAED;;;OAGG;IACH,+CAUC;IAED,eAkDC;IAED;;;OAGG;IACH,sBAuGC;IAqBD;;OAEG;IACH,sBA+DC;IAED,aAEC;IAED;;OAEG;IACH,4BAOC;IAIL;;;OAGG;IACH,mBAFU,OAAO,CAEQ;;CAPxB;+BA94B8B,+BAA+B;wBAUtC,wBAAwB;0BApBtB,0CAA0C;wCAcN,iDAAiD;oCAG3E,iCAAiC;mBAElD,wBAAwB;+BArBZ,gDAAgD;iCAO9C,+CAA+C;8BAGlD,wBAAwB;6BALzB,yBAAyB;uCAIf,6DAA6D;4BASxE,0BAA0B;+BApBvB,iCAAiC;4CAapB,qDAAqD;AAejG;;GAEG;AAGH;IACI,gDAA2D;IAC3D,0BAAkC;IAClC,iCAAyC;CAC5C;6BAtC4B,sCAAsC;sBA2B7C,mBAAmB;yBAJhB,yBAAyB;8BALpB,kCAAkC;2BADrC,mCAAmC;8BADhC,kCAAkC;sBAZ1C,+BAA+B;+BAKtB,qCAAqC;4BAPxC,kCAAkC;oBAH1C,yBAAyB"}

package/src/engine/Engine.js

@@ -44,6 +44,17 @@ class EngineSettings {
     input_mouse_sensitivity = new Vector1(5);
 }
 
+/**
+ * Where an {@link Engine} is in its start/stop cycle. See `Engine#start`.
+ * @readonly
+ * @type {number}
+ */
+const ENGINE_START_STATE_STOPPED = 0;
+/** @readonly @type {number} */
+const ENGINE_START_STATE_STARTING = 1;
+/** @readonly @type {number} */
+const ENGINE_START_STATE_STARTED = 2;
+
 const METRIC_ID_FRAME = 'frame_delay';
 const METRIC_ID_RENDER = 'render_time';
 const METRIC_ID_SIMULATION = 'simulation_time';
@@ -84,6 +95,27 @@ class Engine {
      * Handle of the pending "pause the simulation, this outage is taking a while" timer, `-1` when none
      * @type {number}
      */
+    /**
+     * The ticker subscription that drives the entity manager, held so {@link stop} can remove it.
+     * Null when an external entity manager is in use.
+     * @type {function(number)|null}
+     */
+    #simulation_tick_handler = null;
+
+    /**
+     * Undoes what {@link initializeSettings} registered on the window. Null until it has run.
+     * @type {function()|null}
+     */
+    #settings_teardown = null;
+
+    /**
+     * Where this engine is in its start/stop cycle. Guards against a second {@link start} - on a
+     * half-built engine that re-acquires the GPU device, re-subscribes the sound engine to pointer
+     * and keyboard, and arms a second performance printer on top of the first.
+     * @type {number}
+     */
+    #start_state = ENGINE_START_STATE_STOPPED;
+
     #context_loss_pause_timer = -1;
 
     /**
@@ -230,8 +262,10 @@ class Engine {
 
 
         if (!this.__using_external_entity_manager) {
-            // subscribe simulator to common ticker
-            this.ticker.onTick.add(timeDelta => {
+            // Subscribe simulator to common ticker. Held, so `stop` can take it off again -
+            // left on, it keeps the ticker pointing at a torn-down entity manager and keeps the
+            // whole engine graph reachable.
+            this.#simulation_tick_handler = timeDelta => {
                 const t0 = performance.now();
                 this.entityManager.update(timeDelta);
 
@@ -240,7 +274,9 @@ class Engine {
 
                 // record frame time
                 this.performance.get(METRIC_ID_SIMULATION).record(duration);
-            });
+            };
+
+            this.ticker.onTick.add(this.#simulation_tick_handler);
         }
 
         // initialize performance metrics
@@ -569,14 +605,28 @@ class Engine {
             engine.viewStack.size.set(parentElement.innerWidth, parentElement.innerHeight);
         }
 
-        this.settings.graphics_control_viewport_size.process(function (value) {
+        const control_viewport_size = this.settings.graphics_control_viewport_size;
+
+        function handleViewportControlSetting(value) {
             if (value) {
                 setViewportToWindowSize();
                 window.addEventListener("resize", setViewportToWindowSize, false);
             } else {
                 window.removeEventListener("resize", setViewportToWindowSize);
             }
-        });
+        }
+
+        control_viewport_size.process(handleViewportControlSetting);
+
+        // `setViewportToWindowSize` closes over the engine, so a listener left on the window holds
+        // the entity manager, the asset cache and the graphics engine unreachable for GC after
+        // `stop()` - and every resize after that drives a dead view stack. It used to come off
+        // only if the setting was flipped to false, which defaults to true.
+        this.#settings_teardown = () => {
+            control_viewport_size.onChanged.remove(handleViewportControlSetting);
+
+            window.removeEventListener("resize", setViewportToWindowSize);
+        };
 
         logger.info('Engine settings initilized.');
     }
@@ -673,6 +723,16 @@ class Engine {
      * @returns {Promise}
      */
     async start() {
+        if (this.#start_state !== ENGINE_START_STATE_STOPPED) {
+            // A second start on a half-built engine re-acquires the GPU device, re-subscribes the
+            // sound engine to pointer and keyboard, and arms a second performance printer on top
+            // of the first. The natural reaction to a failed start is to retry it, which is
+            // exactly how that compounded.
+            throw new Error(`Engine is already ${this.#start_state === ENGINE_START_STATE_STARTING ? 'starting' : 'started'}`);
+        }
+
+        this.#start_state = ENGINE_START_STATE_STARTING;
+
         // First, and awaited: systems read `graphics.viewport` and size themselves off it during
         // their own startup, so the device has to exist before the entity manager runs.
         if (this.graphics !== null) {
@@ -736,10 +796,29 @@ class Engine {
             //load options
             await this.options.attachToStorage('lazykitty.komrade.options', this.storage);
 
+            this.#start_state = ENGINE_START_STATE_STARTED;
+
             logger.info('engine started');
-        }, function (e) {
+        }, async (e) => {
             logger.error(`Engine Failed to start: ${e}`);
 
+            // Unwind what did come up. Before the Promise.all this method has already acquired the
+            // GPU device, started the asset manager, subscribed the sound engine to pointer and
+            // keyboard and armed a 15-second console printer; the four branches of the Promise.all
+            // succeed or fail independently. Leaving all of that running burned a device and a
+            // timer for the life of the page while the caller, seeing a rejection, reasonably
+            // assumed nothing came up.
+            //
+            // Best-effort: a teardown step that throws must not replace the startup failure the
+            // caller needs to see.
+            this.#start_state = ENGINE_START_STATE_STARTED;
+
+            try {
+                await this.stop();
+            } catch (teardown_error) {
+                logger.error(`Engine failed to roll back a failed start: ${teardown_error}`);
+            }
+
             // the caller awaits start() to know whether the engine came up;
             // swallowing this reported success after a failed startup
             throw e;
@@ -771,6 +850,8 @@ class Engine {
      * Shutdown the engine, disposing all relevant resources
      */
     async stop() {
+        this.#start_state = ENGINE_START_STATE_STOPPED;
+
         this.__performacne_monitor.stop();
 
         // stop the ticker. pause() throws when the loop is not currently
@@ -805,6 +886,26 @@ class Engine {
 
         await this.assetManager.shutdown();
 
+        // Everything the constructor registered outside the paths above. Left alone, each one
+        // holds the whole engine graph - including every loaded asset - reachable for GC, and a
+        // host that builds a second engine (an editor reloading a project, a test suite)
+        // accumulates one live graph per cycle.
+        if (this.#settings_teardown !== null) {
+            this.#settings_teardown();
+            this.#settings_teardown = null;
+        }
+
+        this.viewStack.on.linked.remove(this.#focusInputElement, this);
+        this.viewStack.el.removeEventListener('pointerdown', this.#focusInputElement);
+
+        if (this.#simulation_tick_handler !== null) {
+            this.ticker.onTick.remove(this.#simulation_tick_handler);
+            this.#simulation_tick_handler = null;
+        }
+
+        this.#clear_context_loss_pause_timer();
+        this.#paused_by_context_loss = false;
+
         // last, so that everything above still has a live context to release its GPU resources through
         const graphics = this.graphics;
 

package/src/engine/achievements/AchievementManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AchievementManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/achievements/AchievementManager.js"],"names":[],"mappings":"AAkDA;IAGI;;;OAGG;IACH,SAFU,qBAAmB,IAAI,CAElB;IAEf;;;OAGG;IACH,SAFU,WAAW,EAAE,CAEV;IAEb;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAEpB;;;OAGG;IACH,YAFU,aAAW,IAAI,CAEP;IAElB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAIhB;;;OAGG;IACH,oBAFU,eAAe,CAEkB;IAE3C;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,mBAFU,WAAW,CAKpB;IAUD,aAAkB;IAGtB;;;;OAIG;IACH,gCAFY,WAAW,GAAC,SAAS,CAIhC;IAGD;;;OAGG;IACH,yBA6BC;IAED;;;OAGG;IACH,sBAcC;IAED;;;OAGG;IACH,wBAUC;IAGD;;OAEG;IACH,iBAUC;IAED;;OAEG;IACH,mBAMC;IAED,uCAMC;IAED;;;OAGG;IACH,2DAaC;IAED;;;OAGG;IACH,qBAFW,WAAW,QAuFrB;IAED;;;OAGG;IACH,+CAOC;IAED,mCAoDC;IAED,yBASC;IAED,0BAEC;CACJ;6BA5Z4B,2BAA2B;4BAK5B,kBAAkB;4BA1BlB,qCAAqC;4BACrC,sDAAsD"}
+{"version":3,"file":"AchievementManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/achievements/AchievementManager.js"],"names":[],"mappings":"AAkDA;IAGI;;;OAGG;IACH,SAFU,qBAAmB,IAAI,CAElB;IAEf;;;OAGG;IACH,SAFU,WAAW,EAAE,CAEV;IAEb;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAEpB;;;OAGG;IACH,YAFU,aAAW,IAAI,CAEP;IAElB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAIhB;;;OAGG;IACH,oBAFU,eAAe,CAEkB;IAE3C;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,+BAFU,eAAe,CAE6B;IAEtD;;;OAGG;IACH,mBAFU,WAAW,CAKpB;IAUD,aAAkB;IAGtB;;;;OAIG;IACH,gCAFY,WAAW,GAAC,SAAS,CAIhC;IAGD;;;OAGG;IACH,yBA6BC;IAED;;;OAGG;IACH,sBAcC;IAED;;;OAGG;IACH,wBAUC;IAGD;;OAEG;IACH,iBAUC;IAED;;OAEG;IACH,mBAMC;IAED,uCAcC;IAED;;;OAGG;IACH,2DAaC;IAED;;;OAGG;IACH,qBAFW,WAAW,QAuFrB;IAED;;;OAGG;IACH,+CAOC;IAED,mCAoDC;IAED,yBAWC;IAED,0BAOC;CACJ;6BA3a4B,2BAA2B;4BAK5B,kBAAkB;4BA1BlB,qCAAqC;4BACrC,sDAAsD"}

package/src/engine/achievements/AchievementManager.js

@@ -236,6 +236,14 @@ export class AchievementManager extends EnginePlugin {
     }
 
     async initialize(engine) {
+        // The lifecycle overrides here used to call no super at all, so __state never left
+        // ProcessState.New - and PluginReferenceContext.navigate_to_finalized short-circuits on
+        // New, meaning EnginePluginManager.shutdown(), the only teardown Engine.stop() performs
+        // for plugins, did nothing for this one: shutdown() never ran, deactivate() never ran, and
+        // every achievement's blackboard trigger handler stayed subscribed. A restart then re-ran
+        // loadDefinitions and activate() on top of them, so each trigger fired unlock once per boot
+        // cycle. `engine` was never assigned either, since only EnginePlugin.initialize does that.
+        super.initialize(engine);
 
         this.assetManager = engine.assetManager;
         this.gateway = engine.platform.getAchievementGateway();
@@ -421,7 +429,9 @@ export class AchievementManager extends EnginePlugin {
     }
 
     async startup() {
-        assert.equal()
+        // a stray no-argument `assert.equal()` stood here - a two-argument comparison called with
+        // none, passing vacuously
+        await super.startup();
 
         //load achievement definitions
         await this.loadDefinitions(this.assetManager);
@@ -432,6 +442,11 @@ export class AchievementManager extends EnginePlugin {
     }
 
     async shutdown() {
+        // this is what moves __state to Stopped, and what lets the plugin manager reach Finalized
+        await super.shutdown();
 
+        // The `isActive` reactive that drives deactivate() is fed by `isStarted`, so the handlers
+        // registered by activateEntry are only released if this is cleared.
+        this.isStarted.set(false);
     }
 }

package/src/engine/animation/clip/ecd_bind_animation_curve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ecd_bind_animation_curve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/ecd_bind_animation_curve.js"],"names":[],"mappings":"AA6GA;;;;GAIG;AACH,sFA8BC;qCA7IoC,2BAA2B"}
+{"version":3,"file":"ecd_bind_animation_curve.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/ecd_bind_animation_curve.js"],"names":[],"mappings":"AAwHA;;;;GAIG;AACH,sFA8BC;qCAxJoC,2BAA2B"}

package/src/engine/animation/clip/ecd_bind_animation_curve.js

@@ -59,12 +59,23 @@ function convert_three_track_to_curves(track) {
     // figure out interpolation type
     const interpolation = track_to_interpolation(track);
 
-    // A quaternion track is interpolated below as four independent per-component curves; without hemisphere
-    // alignment a pair of adjacent keys with a negative dot product interpolates the long way around. Negate
-    // keys into a common hemisphere first so the component nlerp takes the short arc. (Discrete needs no
-    // interpolation; CubicTangents packs tangents per key and is handled separately / not yet aligned.)
-    if (interpolation === AnimationInterpolationKind.Linear && track.ValueTypeName === 'quaternion') {
-        values = hemisphere_align_quaternion_values(values, key_count);
+    /*
+     A quaternion track is interpolated below as four independent per-component curves; without hemisphere
+     alignment a pair of adjacent keys with a negative dot product interpolates the long way around. Negate
+     keys into a common hemisphere first so the component nlerp takes the short arc.
+
+     CubicTangents is included: its keys are 12 floats, [in_tangent, value, out_tangent], and the shared
+     walk negates the whole block so a flipped value keeps its tangents. This used to be gated to Linear
+     with a comment saying cubic was "not yet aligned", which left a CUBICSPLINE quaternion track
+     interpolating the long way between sign-mismatched keys — the one-frame snap the loader's copy of this
+     was written to eliminate. Discrete needs no interpolation at all, so it is still skipped.
+    */
+    if (track.ValueTypeName === 'quaternion' && interpolation !== AnimationInterpolationKind.Discrete) {
+        const is_cubic = interpolation === AnimationInterpolationKind.CubicTangents;
+
+        values = hemisphere_align_quaternion_values(
+            values, key_count, is_cubic ? 12 : 4, is_cubic ? 4 : 0
+        );
     }
 
     const values_per_key = values.length / key_count;

package/src/engine/animation/clip/hemisphere_align_quaternion_values.d.ts

@@ -1,20 +1,29 @@
 /**
- * Return a copy of a flat quaternion keyframe-value array (`[x0,y0,z0,w0, x1,y1,z1,w1, ...]`) in which every
- * key has been negated as needed so that consecutive keys lie in the same hemisphere (their dot product is
- * non-negative).
+ * Return a copy of a flat quaternion keyframe-value array in which every key has been negated as needed
+ * so that consecutive keys lie in the same hemisphere (their dot product is non-negative).
  *
- * A quaternion and its negation represent the same rotation, so this does not change the pose at any key. It
- * does change what happens BETWEEN keys: the animation clip pipeline interpolates a quaternion track as four
- * independent per-component curves (component-wise normalized-lerp), and without hemisphere alignment a pair of
- * adjacent keys whose dot product is negative interpolates the long way around — spinning nearly 360 degrees and
- * dipping through a near-degenerate quaternion at the midpoint. Aligning the keys first makes the component nlerp
- * take the short arc, matching what three.js does at interpolation time via Quaternion.slerpFlat's sign flip.
+ * The walk is {@link quat3_canonicalize_sign_run}; this is the copying, 4-float-stride entry point.
+ * `canonicalize_quaternion_signs` in the glTF loader is the in-place one that also handles the
+ * 12-float CUBICSPLINE stride and the rest-rotation anchor. The two used to be separate
+ * implementations, and this was the weaker: no tangent handling and no anchor, so a CUBICSPLINE track
+ * could not be aligned through it at all and two clips on one node could land in opposite hemispheres.
+ *
+ * A quaternion and its negation represent the same rotation, so this does not change the pose at any
+ * key. It changes what happens BETWEEN keys — see the shared function for why.
  *
  * The input array is not mutated.
  *
  * @param {number[]|Float32Array|Float64Array} values flat quaternion components, 4 per key
  * @param {number} key_count number of keyframes
+ * @param {number} [stride] floats per keyframe block; 12 for a CUBICSPLINE track
+ * @param {number} [val_offset] offset of the quaternion within a block; 4 for a CUBICSPLINE track
+ * @param {{x:number, y:number, z:number, w:number}} [rest_rotation] anchors the leading sign
  * @returns {number[]|Float32Array|Float64Array} a copy with hemisphere-aligned keys
  */
-export function hemisphere_align_quaternion_values(values: number[] | Float32Array | Float64Array, key_count: number): number[] | Float32Array | Float64Array;
+export function hemisphere_align_quaternion_values(values: number[] | Float32Array | Float64Array, key_count: number, stride?: number, val_offset?: number, rest_rotation?: {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}): number[] | Float32Array | Float64Array;
 //# sourceMappingURL=hemisphere_align_quaternion_values.d.ts.map

package/src/engine/animation/clip/hemisphere_align_quaternion_values.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hemisphere_align_quaternion_values.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/hemisphere_align_quaternion_values.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,2DAJW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,aAClC,MAAM,GACJ,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAoB9C"}
+{"version":3,"file":"hemisphere_align_quaternion_values.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/clip/hemisphere_align_quaternion_values.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,2DAPW,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,aAClC,MAAM,WACN,MAAM,eACN,MAAM,kBACN;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAC;IAAC,CAAC,EAAC,MAAM,CAAA;CAAC,GACtC,MAAM,EAAE,GAAC,YAAY,GAAC,YAAY,CAU9C"}

package/src/engine/animation/clip/hemisphere_align_quaternion_values.js

@@ -1,37 +1,33 @@
+import { quat3_canonicalize_sign_run } from "../../../core/geom/3d/quaternion/quat3_canonicalize_sign_run.js";
+
 /**
- * Return a copy of a flat quaternion keyframe-value array (`[x0,y0,z0,w0, x1,y1,z1,w1, ...]`) in which every
- * key has been negated as needed so that consecutive keys lie in the same hemisphere (their dot product is
- * non-negative).
+ * Return a copy of a flat quaternion keyframe-value array in which every key has been negated as needed
+ * so that consecutive keys lie in the same hemisphere (their dot product is non-negative).
+ *
+ * The walk is {@link quat3_canonicalize_sign_run}; this is the copying, 4-float-stride entry point.
+ * `canonicalize_quaternion_signs` in the glTF loader is the in-place one that also handles the
+ * 12-float CUBICSPLINE stride and the rest-rotation anchor. The two used to be separate
+ * implementations, and this was the weaker: no tangent handling and no anchor, so a CUBICSPLINE track
+ * could not be aligned through it at all and two clips on one node could land in opposite hemispheres.
  *
- * A quaternion and its negation represent the same rotation, so this does not change the pose at any key. It
- * does change what happens BETWEEN keys: the animation clip pipeline interpolates a quaternion track as four
- * independent per-component curves (component-wise normalized-lerp), and without hemisphere alignment a pair of
- * adjacent keys whose dot product is negative interpolates the long way around — spinning nearly 360 degrees and
- * dipping through a near-degenerate quaternion at the midpoint. Aligning the keys first makes the component nlerp
- * take the short arc, matching what three.js does at interpolation time via Quaternion.slerpFlat's sign flip.
+ * A quaternion and its negation represent the same rotation, so this does not change the pose at any
+ * key. It changes what happens BETWEEN keys — see the shared function for why.
  *
  * The input array is not mutated.
  *
  * @param {number[]|Float32Array|Float64Array} values flat quaternion components, 4 per key
  * @param {number} key_count number of keyframes
+ * @param {number} [stride] floats per keyframe block; 12 for a CUBICSPLINE track
+ * @param {number} [val_offset] offset of the quaternion within a block; 4 for a CUBICSPLINE track
+ * @param {{x:number, y:number, z:number, w:number}} [rest_rotation] anchors the leading sign
  * @returns {number[]|Float32Array|Float64Array} a copy with hemisphere-aligned keys
  */
-export function hemisphere_align_quaternion_values(values, key_count) {
+export function hemisphere_align_quaternion_values(
+    values, key_count, stride = 4, val_offset = 0, rest_rotation
+) {
     const out = values.slice();
 
-    for (let i = 1; i < key_count; i++) {
-        const p = (i - 1) * 4;
-        const c = i * 4;
-
-        const dot = out[p] * out[c] + out[p + 1] * out[c + 1] + out[p + 2] * out[c + 2] + out[p + 3] * out[c + 3];
-
-        if (dot < 0) {
-            out[c] = -out[c];
-            out[c + 1] = -out[c + 1];
-            out[c + 2] = -out[c + 2];
-            out[c + 3] = -out[c + 3];
-        }
-    }
+    quat3_canonicalize_sign_run(out, key_count, stride, val_offset, rest_rotation);
 
     return out;
 }

package/src/engine/animation/keyed2/AnimationTrackPlayback.d.ts

@@ -20,7 +20,6 @@ declare class AnimationTrackPlayback {
     __nextKeyTime: number;
     __loop: boolean;
     track: import("./AnimationTrack.js").default;
-    position: number;
     updateCallback: any;
     updateTraget: any;
     __valueBuffer: Float64Array;
@@ -48,6 +47,7 @@ declare class AnimationTrackPlayback {
      * @param {number} time
      */
     setPosition(time: number): void;
+    position: any;
     /**
      *
      * @returns {boolean} Indicated whenever or not a key was advanced, no advancement is possible past end of the sequence

package/src/engine/animation/keyed2/AnimationTrackPlayback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AnimationTrackPlayback.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/keyed2/AnimationTrackPlayback.js"],"names":[],"mappings":";6BAIa,OAAO,qBAAqB,EAAE,OAAO;AADlD;;GAEG;AAEH;IAOI;;;;;;;;OAQG;IACH,mBAPW,cAAc,2CAqBxB;IA7BD,uBAAmB;IACnB,8BAA0B;IAC1B,uBAAmB;IACnB,sBAAkB;IAClB,gBAAe;IAYX,6CAAkB;IAClB,iBAA+B;IAE/B,oBAAoC;IACpC,kBAAgC;IAEhC,4BAA0D;IAE1D;;MAEC;IAKL;;;OAGG;IACH,oBAEC;IAED;;;OAGG;IACH,gBAFa,QAAQ,IAAI,CAAC,CAUzB;IAED;;;OAGG;IACH,WAFW,OAAO,QAIjB;IAED,cAEC;IAED;;;OAGG;IACH,kBAFW,MAAM,QA2BhB;IAED;;;OAGG;IACH,cAFa,OAAO,CA2CnB;IAED;;;OAGG;IACH,mBAFW,MAAM,QAmChB;IAED,eAOC;IAED;;;OAGG;IACH,0BAFW,MAAM,EAAE,QA2ClB;CACJ;mBArPkB,uCAAuC"}
+{"version":3,"file":"AnimationTrackPlayback.d.ts","sourceRoot":"","sources":["../../../../../src/engine/animation/keyed2/AnimationTrackPlayback.js"],"names":[],"mappings":";6BAIa,OAAO,qBAAqB,EAAE,OAAO;AADlD;;GAEG;AAEH;IAOI;;;;;;;;OAQG;IACH,mBAPW,cAAc,2CA2BxB;IAnCD,uBAAmB;IACnB,8BAA0B;IAC1B,uBAAmB;IACnB,sBAAkB;IAClB,gBAAe;IAYX,6CAAkB;IAElB,oBAAoC;IACpC,kBAAgC;IAEhC,4BAA0D;IAE1D;;MAEC;IAYL;;;OAGG;IACH,oBAEC;IAED;;;OAGG;IACH,gBAFa,QAAQ,IAAI,CAAC,CAUzB;IAED;;;OAGG;IACH,WAFW,OAAO,QAIjB;IAED,cAEC;IAED;;;OAGG;IACH,kBAFW,MAAM,QA2BhB;IAxBG,cAAoB;IA0BxB;;;OAGG;IACH,cAFa,OAAO,CA2CnB;IAED;;;OAGG;IACH,mBAFW,MAAM,QA8ChB;IAED,eAOC;IAED;;;OAGG;IACH,0BAFW,MAAM,EAAE,QA2ClB;CACJ;mBAtQkB,uCAAuC"}

package/src/engine/animation/keyed2/AnimationTrackPlayback.js

@@ -23,7 +23,6 @@ class AnimationTrackPlayback {
      */
     constructor(track, updateCallback, updateTarget) {
         this.track = track;
-        this.position = track.timeStart;
 
         this.updateCallback = updateCallback;
         this.updateTraget = updateTarget;
@@ -34,7 +33,14 @@ class AnimationTrackPlayback {
             ended: new Signal()
         };
 
-        this.setPosition(0);
+        // A track's keys need not start at the origin; the playback's clock is the track's own, and
+        // `reset()` has always said so by seeking to `timeStart`. This used to assign `timeStart`
+        // and then immediately `setPosition(0)`, so a fresh playback of a track keyed at 10, 11, 12
+        // sat nine seconds before its first key — `keyLowerBoundIndexAt` answers -1 there and
+        // `readKeyValues` reads `keyValues[-propertyCount]`, which is `undefined` and NaN in the
+        // buffer the callback is handed. The guard that catches it is an `assert.ok`, which the
+        // consumer strips.
+        this.reset();
     }
 
     /**
@@ -168,8 +174,19 @@ class AnimationTrackPlayback {
 
             if (newPosition >= this.track.timeEnd) {
                 if (this.__loop) {
-                    //loop back
-                    newPosition %= this.track.timeEnd;
+                    // Loop back, into [timeStart, timeEnd). This was `newPosition %= timeEnd` —
+                    // modulo the absolute end of the track rather than its duration — which for a
+                    // track keyed at 10, 11, 12 wrapped 12.1 to 0.1 instead of 10.1, nine seconds
+                    // before the first key and off the front of the key array.
+                    const timeStart = this.track.timeStart;
+                    const duration = this.track.timeEnd - timeStart;
+
+                    if (duration > 0) {
+                        newPosition = timeStart + (newPosition - timeStart) % duration;
+                    } else {
+                        // a single-key track has nowhere to wrap to but its one key
+                        newPosition = timeStart;
+                    }
                 } else if (this.position < this.track.timeEnd) {
                     //fire ended only once, when we first cross the end
                     //(this.position is still the pre-advance position here)

package/src/engine/asset/AssetManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssetManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/AssetManager.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH;IAsNI;;;;;;OAMG;IACH;QAJwB,OAAO,EAApB,GAAG;QACyB,QAAQ,EAApC,kBAAkB;OAW5B;IApOD;;;;OAIG;IACH,eAEG;IAEH;;;OAGG;IACH,aAFU,YAAY,gBAAgB,EAAE,YAAY,CAAC,CAER;IAuB7C;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAFU,MAAM,CAEY;IA4B5B;;;;;;OAMG;IACH,iBAAc;IAEd;;;OAGG;IACH,mBAFU,iBAAiB,CAEiB;IAuI5C,gBAWC;IAED;;;;;;OAMG;IACH,qBALW,OAAO,GAGN,QAAQ,IAAI,CAAC,CAgBxB;IA4ED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oCAFa,OAAO,CAOnB;IAED;;OAEG;IACH,cAEC;IAED,8BAEC;IAED;;;;;;;;OAQG;IACH;QALuC,KAAK,GAAjC,iBAAiB;QACC,UAAU,GAA5B,OAAO;QAC2C,QAAQ,GAA1D,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;QACrC,wCAAc,CAc1B;IAED;;;;;;;;;;OAUG;IACH;;;mCANgC,IAAI;kBACzB,CAAC,MAAM,KAAG,KAAK,IAAI;mBACnB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;qBACvC,OAAO;gBACP,iBAAiB;aA8D3B;IAED;;;;;;;OAOG;IACH,gBAJW,MAAM,QACN,MAAM,GACL,OAAO,CAKlB;IAGD;;;;;;;OAOG;IACH,eALW,MAAM,QACN,MAAM,GACJ,OAAO,CAOnB;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACL,OAAO,CAMlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAZW,MAAM,QACN,MAAM,sBACM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,iCAwE9D;IAED;;;;;;;;;;;OAWG;IACH,kBAJW,MAAM,QACN,MAAM,oBAoChB;IAgbD;;;;;;OAMG;IACH,sBAkCC;IAGD;;;;OAIG;IACH,uBAHW,MAAM,GACL,OAAO,CAIlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,wBAAY,SAAS,CAMjC;IAaD;;;;;;;;;;OAUG;IACH,+BALW,MAAM,qBAEJ,IAAI,CAqBhB;IAED;;;;;;OAMG;IACH,iCALW,MAAM,qBAEJ,OAAO,CAyBnB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,kCAEJ,QAAQ,OAAO,CAAC,CAU5B;IAED;;;;;OAKG;IACH,0BAJW,MAAM,iEAwChB;IAED;;;OAGG;IACH,uBAFW,MAAM,iBAkBhB;IAED;;;;;;;OAOG;IACH,6CAUC;IAED;;;;OAIG;IACH,2BAHW,MAAM,gBAchB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,gBAAgB,GAAC,SAAS,CAQrC;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,QACN,MAAM,QAUhB;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;;CANpC;;;4BAz4C2B,0CAA0C;iCAOrC,uBAAuB;6BAM3B,mBAAmB;kCAFd,6BAA6B;kCAD7B,wBAAwB;4BAE9B,0BAA0B;+BARvB,mDAAmD"}
+{"version":3,"file":"AssetManager.d.ts","sourceRoot":"","sources":["../../../../src/engine/asset/AssetManager.js"],"names":[],"mappings":"AAuDA;;;;GAIG;AACH;IAsNI;;;;;;OAMG;IACH;QAJwB,OAAO,EAApB,GAAG;QACyB,QAAQ,EAApC,kBAAkB;OAW5B;IApOD;;;;OAIG;IACH,eAEG;IAEH;;;OAGG;IACH,aAFU,YAAY,gBAAgB,EAAE,YAAY,CAAC,CAER;IAuB7C;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAFU,MAAM,CAEY;IA4B5B;;;;;;OAMG;IACH,iBAAc;IAEd;;;OAGG;IACH,mBAFU,iBAAiB,CAEiB;IAuI5C,gBAWC;IAED;;;;;;OAMG;IACH,qBALW,OAAO,GAGN,QAAQ,IAAI,CAAC,CAgBxB;IA4ED;;;;;;;OAOG;IACH,yBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,oCAFa,OAAO,CAOnB;IAED;;OAEG;IACH,cAEC;IAED,8BAEC;IAED;;;;;;;;OAQG;IACH;QALuC,KAAK,GAAjC,iBAAiB;QACC,UAAU,GAA5B,OAAO;QAC2C,QAAQ,GAA1D,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;QACrC,wCAAc,CAc1B;IAED;;;;;;;;;;OAUG;IACH;;;mCANgC,IAAI;kBACzB,CAAC,MAAM,KAAG,KAAK,IAAI;mBACnB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI;qBACvC,OAAO;gBACP,iBAAiB;aAsE3B;IAED;;;;;;;OAOG;IACH,gBAJW,MAAM,QACN,MAAM,GACL,OAAO,CAKlB;IAGD;;;;;;;OAOG;IACH,eALW,MAAM,QACN,MAAM,GACJ,OAAO,CAOnB;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACL,OAAO,CAMlB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,uBAZW,MAAM,QACN,MAAM,sBACM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,iCAwE9D;IAED;;;;;;;;;;;OAWG;IACH,kBAJW,MAAM,QACN,MAAM,oBAoChB;IAgbD;;;;;;OAMG;IACH,sBAkCC;IAGD;;;;OAIG;IACH,uBAHW,MAAM,GACL,OAAO,CAIlB;IAED;;;;OAIG;IACH,sBAHW,MAAM,GACJ,wBAAY,SAAS,CAMjC;IAaD;;;;;;;;;;OAUG;IACH,+BALW,MAAM,qBAEJ,IAAI,CAqBhB;IAED;;;;;;OAMG;IACH,iCALW,MAAM,qBAEJ,OAAO,CAyBnB;IAED;;;;;;OAMG;IACH,6BAJW,MAAM,kCAEJ,QAAQ,OAAO,CAAC,CAU5B;IAED;;;;;OAKG;IACH,0BAJW,MAAM,iEAwChB;IAED;;;OAGG;IACH,uBAFW,MAAM,iBAkBhB;IAED;;;;;;;OAOG;IACH,6CAUC;IAED;;;;OAIG;IACH,2BAHW,MAAM,gBAchB;IAED;;;;OAIG;IACH,oBAHW,MAAM,GACL,gBAAgB,GAAC,SAAS,CAQrC;IAED;;;;;OAKG;IACH,mBAJW,MAAM,QACN,MAAM,QACN,MAAM,QAUhB;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;;CANpC;;;4BAj5C2B,0CAA0C;iCAOrC,uBAAuB;6BAM3B,mBAAmB;kCAFd,6BAA6B;kCAD7B,wBAAwB;4BAE9B,0BAA0B;+BARvB,mDAAmD"}

package/src/engine/asset/AssetManager.js

@@ -503,9 +503,17 @@ export class AssetManager {
         const asset = this.assets.get(assetDescription);
 
         if (asset !== undefined) {
-
-            // already exists, dispatch callback immediately
-            callback(asset);
+            // Already loaded - but scheduled like every other response, not dispatched inline.
+            //
+            // Calling back synchronously made `get` sometimes-synchronous, decided only by cache
+            // state, and `AssetPreloader` is built directly on it: with a warm cache
+            // `assetLoadSuccess` ran inside `#load_level`'s loop, `levelFinished` dispatched
+            // synchronously, `prod` recursed through every level and `#try_finish` fired
+            // `on.succeeded` - all before `load()` returned, so a caller that subscribes to the
+            // preloader it is handed attaches to a signal that has already fired and the screen
+            // never goes away. A second visit to the same screen is exactly when everything is
+            // cached, which is why it presented as intermittent.
+            this.#schedule_response(new AssetRequest(callback, failure, progress), asset, true, assetDescription);
 
             return;
         }

package/src/engine/control/first-person/FirstPersonPlayerController.d.ts

@@ -206,6 +206,7 @@ export class FirstPersonPlayerController {
                 pitchMaxDeg: number;
                 invertY: boolean;
                 maxFrameDeltaRad: number;
+                maxLookRateRadPerSecond: number;
             };
             posture: {
                 sprintForwardPitchDeg: number;

package/src/engine/control/first-person/FirstPersonPlayerController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAEhD,0CAAiD;IACjD,0BAAiC;IACjC,wBAA+B;IAC/B,sBAA6B;IAC7B,4BAAmC;IAEnC;;;;;;OAMG;IACH,SAFU,UAAU,CAEO;IAE3B;;;;;OAKG;IACH,WAFU,UAAU,CAES;IAE7B;;;;;;OAMG;IACH,WAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;qCA7FA,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA+F9E;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDAzMiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,mBAA0B;IAC1B,yEAAyE;IACzE,oBAA2B;IAC3B,kBAAkB;IAClB,mBAA0B;IAC1B,6BAA6B;IAC7B,sBAA6B;IAC7B,iDAAiD;IACjD,eAAsB;IACtB,sBAA6B;IAC7B,qBAA4B;IAC5B,sBAA6B;IAC7B,qBAA4B;IAC5B,2EAA2E;IAC3E,mBAA0B;IAC1B,2EAA2E;IAC3E,oBAA2B;IAC3B,6DAA6D;IAC7D,oBAA2B;IAC3B,+DAA+D;IAC/D,uBAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}
+{"version":3,"file":"FirstPersonPlayerController.d.ts","sourceRoot":"","sources":["../../../../../src/engine/control/first-person/FirstPersonPlayerController.js"],"names":[],"mappings":"AA8HA;;;;;;;;;;GAUG;AACH;IACI,wBAAgD;IAEhD,0CAAiD;IACjD,0BAAiC;IACjC,wBAA+B;IAC/B,sBAA6B;IAC7B,4BAAmC;IAEnC;;;;;;OAMG;IACH,SAFU,UAAU,CAEO;IAE3B;;;;;OAKG;IACH,WAFU,UAAU,CAES;IAE7B;;;;;;OAMG;IACH,WAFU,MAAM,CAED;IAEf;;;;;;;;;;;;;;;qCA7FA,+EAA+E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA+F9E;IAED,0BAIC;IAED;;OAEG;IACH,YAFW,2BAA2B,QAKrC;IAED,qCAIC;IAED,4BAGC;IAED,eAGC;CACJ;;;;;kDAzMiD,wCAAwC;AAK1F;;;;;;;;GAQG;AACH;IACI,oEAAoE;IACpE,MADyD,OAAO,CACvC;IAEzB;;;;OAIG;IACH,MAFU,OAAO,CAEQ;IAEzB,mEAAmE;IACnE,MADwD,OAAO,CAClD;IAEb,0EAA0E;IAC1E,QAD+D,OAAO,CACvD;IAEf,qEAAqE;IACrE,QAD0D,OAAO,CAClD;CAClB;AAED;;;GAGG;AACH;IACI,kBAAgB;IAChB,0BAAsB;IAEtB,4EAA4E;IAC5E,sBAAoC;IACpC,gBAAkB;IAElB,cAAU;IACV,4DAA4D;IAC5D,wBAAoB;IACpB,yEAAyE;IACzE,uBAAgD;IAEhD,sBAAkB;IAClB,qBAAiB;IACjB,qBAAiB;IAEjB,4BAAwB;IACxB,4BAA2B;IAC3B,2BAA0B;IAC1B,2EAA2E;IAC3E,qBAAoB;IAEpB,iBAAa;IACb,oBAAgB;IAChB,qBAAiB;IACjB,yBAAqB;IAErB,oBAAgB;IAChB,kBAAc;IACd,kDAAkD;IAClD,iBAAa;IAEb,kBAAiB;IAEjB,+EAA+E;IAC/E,uBAAsB;IACtB,6EAA6E;IAC7E,sBAAqB;IAErB;;;;;;;OAOG;IACH,SAFU,MAAM,CAEmB;IAEnC,oBAAgB;CACnB;gCAzFkF,2BAA2B;AA2F9G;;;GAGG;AACH;IACI,uDAAuD;IACvD,mBAA0B;IAC1B,yEAAyE;IACzE,oBAA2B;IAC3B,kBAAkB;IAClB,mBAA0B;IAC1B,6BAA6B;IAC7B,sBAA6B;IAC7B,iDAAiD;IACjD,eAAsB;IACtB,sBAA6B;IAC7B,qBAA4B;IAC5B,sBAA6B;IAC7B,qBAA4B;IAC5B,2EAA2E;IAC3E,mBAA0B;IAC1B,2EAA2E;IAC3E,oBAA2B;IAC3B,6DAA6D;IAC7D,oBAA2B;IAC3B,+DAA+D;IAC/D,uBAA8B;CACjC;2BAvH0B,yBAAyB;2BAFzB,2BAA2B;uCAG6B,2BAA2B;0CAA3B,2BAA2B;oBAL1F,+BAA+B;oBAC/B,+BAA+B;mBAFhC,uCAAuC"}

package/src/engine/control/first-person/FirstPersonPlayerControllerConfig.d.ts

@@ -522,6 +522,20 @@ export class FirstPersonPlayerControllerConfig {
          *  extremely fast flick stays well under this at render rate (~0.3 rad ≈
          *  17° in one frame would already be ~4000°/s). */
         maxFrameDeltaRad: number;
+        /** Input-spike ceiling as an angular RATE (rad/s), which is what a corrupt
+         *  `movementX` burst actually is. `maxFrameDeltaRad` above is a per-frame
+         *  AMOUNT applied to a value the controller accumulates between render
+         *  frames, so the rate it implied moved with the frame rate: ~43 rad/s at
+         *  144 Hz, 9 rad/s at 30 fps, 1.5 rad/s across a 200 ms hitch - and a
+         *  180° flick over 0.15 s (~21 rad/s) passed on a fast display and was
+         *  silently discarded on a slow one, on exactly the frames a player is
+         *  most likely to be reacting.
+         *
+         *  50 rad/s is ~2865°/s: far above any human flick, far below the
+         *  hundreds of rad/s a single-frame driver snap works out to. The excess
+         *  is now CLAMPED rather than dropped, so a turn that overshoots slows
+         *  instead of not happening. */
+        maxLookRateRadPerSecond: number;
     };
     /**
      * Postural shifts driven by intent — distinct from look (which is
@@ -998,6 +1012,20 @@ export class FirstPersonPlayerControllerConfig {
              *  extremely fast flick stays well under this at render rate (~0.3 rad ≈
              *  17° in one frame would already be ~4000°/s). */
             maxFrameDeltaRad: number;
+            /** Input-spike ceiling as an angular RATE (rad/s), which is what a corrupt
+             *  `movementX` burst actually is. `maxFrameDeltaRad` above is a per-frame
+             *  AMOUNT applied to a value the controller accumulates between render
+             *  frames, so the rate it implied moved with the frame rate: ~43 rad/s at
+             *  144 Hz, 9 rad/s at 30 fps, 1.5 rad/s across a 200 ms hitch - and a
+             *  180° flick over 0.15 s (~21 rad/s) passed on a fast display and was
+             *  silently discarded on a slow one, on exactly the frames a player is
+             *  most likely to be reacting.
+             *
+             *  50 rad/s is ~2865°/s: far above any human flick, far below the
+             *  hundreds of rad/s a single-frame driver snap works out to. The excess
+             *  is now CLAMPED rather than dropped, so a turn that overshoots slows
+             *  instead of not happening. */
+            maxLookRateRadPerSecond: number;
         };
         posture: {
             /** Forward pitch (deg) applied to the eye at full sprint. Positive = look-down. */