@woosh/meep-engine 3.56.0 → 3.57.0

package/src/engine/simulation/Ticker.js

@@ -1,391 +1,394 @@
-import { assert } from "../../core/assert.js";
-import Signal from "../../core/events/signal/Signal.js";
-import { current_time_in_seconds } from "../../core/time/current_time_in_seconds.js";
-import Clock from '../Clock.js';
-
-/**
- * Simulation tick generator
- * Dispatches "tick" every animation frame or "maxDelay" time, whichever happens to be soonest
- * This is essentially the timing bus that all the simulation systems subscribe to for their step advancement
- *
- * A tick taken in an animation frame runs inside that frame and is measured to the frame's timestamp,
- * and {@link Ticker#onFrame} follows it, so whatever draws from `onFrame` draws the simulation as of
- * that frame.
- *
- *
- * @example
- *      ticker.onTick.add(delta_s => {
- *          //do something every tick
- *       });
- *       ticker.start();
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-class Ticker {
-    /**
-     * @readonly
-     * @type {Clock}
-     */
-    clock = new Clock();
-
-    /**
-     * When `true`, ticking is suspended while the host document/tab is in the
-     * background (hidden, or stored in the back/forward cache) and resumes from
-     * the current moment once it returns to the foreground.
-     *
-     * This avoids dispatching a flood of catch-up ticks (or one huge delta) for
-     * the time spent suspended, which would otherwise destabilise the simulation.
-     *
-     * Has no effect in environments without document/visibility support (e.g.
-     * Node.js), where the relevant lifecycle events simply never fire.
-     *
-     * @type {boolean}
-     */
-    suspend_in_background = true;
-
-    /**
-     * @private
-     * @type {boolean}
-     */
-    #isRunning = false;
-
-    /**
-     * Whether ticking is currently suspended because the host page is in the background
-     * @private
-     * @type {boolean}
-     */
-    #isSuspended = false;
-
-    #animationFrameHandle = -1;
-    #timeoutHandle = -1;
-
-    /**
-     * Incremented by {@link Ticker#stop}. The loop closures capture the value they were started
-     * with and refuse to schedule anything once it moves, so a callback already in flight when
-     * stop() ran cannot re-arm the loop behind it. Deliberately not keyed on #isRunning: pause()
-     * clears that while the loop is meant to keep cycling.
-     * @private
-     * @type {number}
-     */
-    #generation = 0;
-
-    /**
-     * Time delta in seconds dispatched by the last tick
-     * @type {number}
-     */
-    #last_tick_delta_s = 0;
-
-    /**
-     * Dispatches time delta in seconds since last tick
-     * @readonly
-     * @type {Signal<number>}
-     */
-    onTick = new Signal();
-
-    /**
-     * Dispatched once per animation frame, after that frame's tick - or with none, while paused or
-     * suspended. The place to draw: the simulation is at the frame's timestamp here.
-     * Not dispatched for the {@link start}'s `maxTimeout` fallback ticks, which are not frames.
-     * @readonly
-     * @type {Signal}
-     */
-    onFrame = new Signal();
-
-    constructor() {
-        this.clock.pause();
-    }
-
-    /**
-     * Owned by {@link start} and {@link stop}; the two handles stay purely for cancellation.
-     *
-     * This used to be `#timeoutHandle !== -1 && #animationFrameHandle !== -1`, but `start()` only
-     * assigns the animation-frame handle - the timeout handle stays -1 until the first frame
-     * callback runs - so for the whole first frame the ticker reported itself inactive. `start()`'s
-     * own "Already running" guard therefore did not fire, and `pause()`/`resume()`, which throw
-     * when the loop is NOT active, did. A second `start()` inside that window installed a second
-     * rAF/timeout chain, and a graphics context lost and restored inside it left the simulation
-     * paused for ever, because Engine's restore path gates `resume()` on this.
-     *
-     * Unlike `#isRunning`, which `pause()` clears, this stays true across a pause.
-     *
-     * @type {boolean}
-     */
-    #loop_started = false;
-
-    #isUpdateLoopActive() {
-        return this.#loop_started;
-    }
-
-    /**
-     * Whether the update loop is cycling. {@link Ticker#pause} and {@link Ticker#resume} require this,
-     * they throw otherwise.
-     * @returns {boolean}
-     */
-    get is_active() {
-        return this.#isUpdateLoopActive();
-    }
-
-    /**
-     * Whether tick dispatch is currently stopped via {@link Ticker#pause}. Suspension caused by the host
-     * page going into the background is not reported here, see {@link Ticker#suspend_in_background}.
-     * @returns {boolean}
-     */
-    get is_paused() {
-        return !this.#isRunning;
-    }
-
-    /**
-     * Stop dispatching ticks because the host page moved to the background.
-     * The clock is paused so no simulation time accrues while suspended. The
-     * update loop itself keeps cycling so it can pick back up cleanly, but
-     * {@link Ticker#onTick} stays silent until the page returns to the foreground.
-     * @private
-     */
-    #suspend() {
-        if (!this.suspend_in_background) {
-            return;
-        }
-
-        if (!this.#isRunning) {
-            // not actively ticking, nothing to suspend
-            return;
-        }
-
-        if (this.#isSuspended) {
-            return;
-        }
-
-        this.#isSuspended = true;
-
-        this.clock.pause();
-    }
-
-    /**
-     * Resume after the host page returned to the foreground.
-     *
-     * The clock is always restarted here (it was paused while suspended), with the
-     * delta accumulated for the suspended period discarded so that time continues
-     * from the current moment rather than catching up all at once. Whether ticks
-     * actually flow afterwards is still governed by the running flag, so a manual
-     * {@link Ticker#pause} taken during suspension is preserved.
-     * @private
-     */
-    #resume() {
-        if (!this.#isSuspended) {
-            return;
-        }
-
-        this.#isSuspended = false;
-
-        this.clock.getDelta(); //discard time spent suspended
-        this.clock.start();
-    }
-
-    #handleVisibilityChange = () => {
-        const doc = globalThis.document;
-
-        if (doc === undefined) {
-            return;
-        }
-
-        if (doc.visibilityState === 'hidden') {
-            this.#suspend();
-        } else {
-            this.#resume();
-        }
-    };
-
-    #handlePageHide = () => {
-        this.#suspend();
-    };
-
-    #handlePageShow = () => {
-        this.#resume();
-    };
-
-    /**
-     * Subscribe to page lifecycle events where the host environment provides them.
-     * Degrades gracefully where there is no DOM event target (e.g. Node.js).
-     * @private
-     */
-    #addLifecycleListeners() {
-        const doc = globalThis.document;
-        if (doc !== undefined && typeof doc.addEventListener === 'function') {
-            doc.addEventListener('visibilitychange', this.#handleVisibilityChange);
-        }
-
-        if (typeof globalThis.addEventListener === 'function') {
-            globalThis.addEventListener('pagehide', this.#handlePageHide);
-            globalThis.addEventListener('pageshow', this.#handlePageShow);
-        }
-    }
-
-    /**
-     * @private
-     */
-    #removeLifecycleListeners() {
-        const doc = globalThis.document;
-        if (doc !== undefined && typeof doc.removeEventListener === 'function') {
-            doc.removeEventListener('visibilitychange', this.#handleVisibilityChange);
-        }
-
-        if (typeof globalThis.removeEventListener === 'function') {
-            globalThis.removeEventListener('pagehide', this.#handlePageHide);
-            globalThis.removeEventListener('pageshow', this.#handlePageShow);
-        }
-    }
-
-    /**
-     *
-     * @param {Object} [options]
-     * @param {number} [options.maxTimeout]
-     */
-    start({ maxTimeout = 100 } = {}) {
-        assert.isNumber(maxTimeout, 'maxTimeout');
-        assert.greaterThan(maxTimeout, 0);
-
-        if (this.#isUpdateLoopActive()) {
-            throw new Error("Already running");
-        }
-
-        this.#loop_started = true;
-        this.#isRunning = true;
-        this.#isSuspended = false;
-
-        const generation = this.#generation;
-        const is_current = () => this.#generation === generation;
-
-        /**
-         * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
-         */
-        const update = (time) => {
-            if (!this.#isRunning || this.#isSuspended) {
-                return;
-            }
-
-            const delta = this.clock.getDeltaAt(time);
-
-            this.#last_tick_delta_s = delta;
-
-            this.onTick.send1(delta);
-        }
-
-        const timeoutCallback = () => {
-            cancelAnimationFrame(this.#animationFrameHandle);
-
-            if (!is_current()) {
-                return;
-            }
-
-            animate(current_time_in_seconds());
-        }
-
-        /**
-         * @param {number} timestamp the frame's, in milliseconds
-         */
-        const animationFrameCallback = (timestamp) => {
-            clearTimeout(this.#timeoutHandle);
-
-            if (!is_current()) {
-                return;
-            }
-
-            /*
-             Ticked here, on the frame's own timestamp, and before the frame is announced. This used to
-             be pushed to a setTimeout(0) "allowing draw to happen" first, which made every frame draw
-             the simulation as of the previous frame's timeout - and that fired whenever the previous
-             draw finished, so a steady motion was drawn at a different speed every frame.
-            */
-            animate(timestamp * 1e-3);
-
-            //a tick listener is allowed to stop us
-            if (!is_current()) {
-                return;
-            }
-
-            this.onFrame.send0();
-        }
-
-        /**
-         * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
-         */
-        const animate = (time) => {
-            if (!is_current()) {
-                return;
-            }
-
-            this.#animationFrameHandle = requestAnimationFrame(animationFrameCallback);
-
-            update(time);
-
-            //update() dispatches onTick, and a listener is allowed to stop us from inside it
-            if (!is_current()) {
-                return;
-            }
-
-            this.#timeoutHandle = setTimeout(timeoutCallback, maxTimeout);
-        }
-
-        this.clock.getDelta(); //purge delta
-        this.clock.start();
-
-        this.#addLifecycleListeners();
-
-        //recorded, so a stop() taken before the first frame lands can cancel it. The generation guard
-        //already makes the callback a no-op, but an uncancelled frame request keeps the closures (and
-        //everything the tick listeners hold) alive until it fires
-        this.#animationFrameHandle = requestAnimationFrame(animationFrameCallback);
-
-        //if we are starting while the page is already in the background, suspend right away
-        const doc = globalThis.document;
-        if (doc !== undefined && doc.visibilityState === 'hidden') {
-            this.#suspend();
-        }
-    }
-
-    pause() {
-
-        if (!this.#isUpdateLoopActive()) {
-            throw new Error("Not currently running");
-        }
-
-        this.#isRunning = false;
-
-        //freeze the clock so no simulation time accrues while paused; without this
-        //the first getDelta() after resume() returns the whole paused duration
-        this.clock.pause();
-    }
-
-    resume() {
-
-        if (!this.#isUpdateLoopActive()) {
-            throw new Error("Not currently running");
-        }
-
-
-        this.#isRunning = true;
-
-        //discard the time spent paused and restart from the current moment,
-        //mirroring #resume() for the background-suspend path
-        this.clock.getDelta();
-        this.clock.start();
-    }
-
-    stop() {
-        this.#generation++;
-
-        this.#removeLifecycleListeners();
-
-        clearTimeout(this.#timeoutHandle);
-        cancelAnimationFrame(this.#animationFrameHandle);
-        this.#loop_started = false;
-        this.#isRunning = false;
-        this.#isSuspended = false;
-
-        this.#timeoutHandle = -1;
-        this.#animationFrameHandle = -1;
-    }
-}
-
-export default Ticker;
+import { assert } from "../../core/assert.js";
+import Signal from "../../core/events/signal/Signal.js";
+import { current_time_in_seconds } from "../../core/time/current_time_in_seconds.js";
+import Clock from '../Clock.js';
+
+/**
+ * Simulation tick generator
+ * Dispatches "tick" every animation frame or "maxDelay" time, whichever happens to be soonest
+ * This is essentially the timing bus that all the simulation systems subscribe to for their step advancement
+ *
+ * A tick taken in an animation frame runs inside that frame and is measured to the frame's timestamp,
+ * and {@link Ticker#onFrame} follows it, so whatever draws from `onFrame` draws the simulation as of
+ * that frame.
+ *
+ *
+ * @example
+ *      ticker.onTick.add(delta_s => {
+ *          //do something every tick
+ *       });
+ *       ticker.start();
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+class Ticker {
+    /**
+     * @readonly
+     * @type {Clock}
+     */
+    clock = new Clock();
+
+    /**
+     * When `true`, ticking is suspended while the host document/tab is in the
+     * background (hidden, or stored in the back/forward cache) and resumes from
+     * the current moment once it returns to the foreground.
+     *
+     * This avoids dispatching a flood of catch-up ticks (or one huge delta) for
+     * the time spent suspended, which would otherwise destabilise the simulation.
+     *
+     * Has no effect in environments without document/visibility support (e.g.
+     * Node.js), where the relevant lifecycle events simply never fire.
+     *
+     * @type {boolean}
+     */
+    suspend_in_background = true;
+
+    /**
+     * @private
+     * @type {boolean}
+     */
+    #isRunning = false;
+
+    /**
+     * Whether ticking is currently suspended because the host page is in the background
+     * @private
+     * @type {boolean}
+     */
+    #isSuspended = false;
+
+    #animationFrameHandle = -1;
+    #timeoutHandle = -1;
+
+    /**
+     * Incremented by {@link Ticker#stop}. The loop closures capture the value they were started
+     * with and refuse to schedule anything once it moves, so a callback already in flight when
+     * stop() ran cannot re-arm the loop behind it. Deliberately not keyed on #isRunning: pause()
+     * clears that while the loop is meant to keep cycling.
+     * @private
+     * @type {number}
+     */
+    #generation = 0;
+
+    /**
+     * Time delta in seconds dispatched by the last tick
+     * @type {number}
+     */
+    #last_tick_delta_s = 0;
+
+    /**
+     * Dispatches time delta in seconds since last tick
+     * @readonly
+     * @type {Signal<number>}
+     */
+    onTick = new Signal();
+
+    /**
+     * Dispatched once per animation frame, after that frame's tick - or with none, while paused or
+     * suspended. The place to draw: the simulation is at the frame's timestamp here.
+     * Not dispatched for the {@link start}'s `maxTimeout` fallback ticks, which are not frames.
+     * @readonly
+     * @type {Signal}
+     */
+    onFrame = new Signal();
+
+    constructor() {
+        this.clock.pause();
+    }
+
+    /**
+     * Owned by {@link start} and {@link stop}; the two handles stay purely for cancellation.
+     *
+     * This used to be `#timeoutHandle !== -1 && #animationFrameHandle !== -1`, but `start()` only
+     * assigns the animation-frame handle - the timeout handle stays -1 until the first frame
+     * callback runs - so for the whole first frame the ticker reported itself inactive. `start()`'s
+     * own "Already running" guard therefore did not fire, and `pause()`/`resume()`, which throw
+     * when the loop is NOT active, did. A second `start()` inside that window installed a second
+     * rAF/timeout chain, and a graphics context lost and restored inside it left the simulation
+     * paused for ever, because Engine's restore path gates `resume()` on this.
+     *
+     * Unlike `#isRunning`, which `pause()` clears, this stays true across a pause.
+     *
+     * @type {boolean}
+     */
+    #loop_started = false;
+
+    #isUpdateLoopActive() {
+        return this.#loop_started;
+    }
+
+    /**
+     * Whether the update loop is cycling. {@link Ticker#pause} and {@link Ticker#resume} require this,
+     * they throw otherwise.
+     * @returns {boolean}
+     */
+    get is_active() {
+        return this.#isUpdateLoopActive();
+    }
+
+    /**
+     * Whether tick dispatch is currently stopped via {@link Ticker#pause}. Suspension caused by the host
+     * page going into the background is not reported here, see {@link Ticker#suspend_in_background}.
+     * @returns {boolean}
+     */
+    get is_paused() {
+        return !this.#isRunning;
+    }
+
+    /**
+     * Stop dispatching ticks because the host page moved to the background.
+     * The clock is paused so no simulation time accrues while suspended. The
+     * update loop itself keeps cycling so it can pick back up cleanly, but
+     * {@link Ticker#onTick} stays silent until the page returns to the foreground.
+     * @private
+     */
+    #suspend() {
+        if (!this.suspend_in_background) {
+            return;
+        }
+
+        if (!this.#isRunning) {
+            // not actively ticking, nothing to suspend
+            return;
+        }
+
+        if (this.#isSuspended) {
+            return;
+        }
+
+        this.#isSuspended = true;
+
+        this.clock.pause();
+    }
+
+    /**
+     * Resume after the host page returned to the foreground.
+     *
+     * The clock is restarted here when not manually paused, with the
+     * delta accumulated for the suspended period discarded so that time continues
+     * from the current moment rather than catching up all at once. Whether ticks
+     * actually flow afterwards is still governed by the running flag, so a manual
+     * {@link Ticker#pause} taken during suspension is preserved.
+     * @private
+     */
+    #resume() {
+        if (!this.#isSuspended) {
+            return;
+        }
+
+        this.#isSuspended = false;
+
+        this.clock.getDelta(); //discard time spent suspended
+
+        if (this.#isRunning) {
+            this.clock.start();
+        }
+    }
+
+    #handleVisibilityChange = () => {
+        const doc = globalThis.document;
+
+        if (doc === undefined) {
+            return;
+        }
+
+        if (doc.visibilityState === 'hidden') {
+            this.#suspend();
+        } else {
+            this.#resume();
+        }
+    };
+
+    #handlePageHide = () => {
+        this.#suspend();
+    };
+
+    #handlePageShow = () => {
+        this.#resume();
+    };
+
+    /**
+     * Subscribe to page lifecycle events where the host environment provides them.
+     * Degrades gracefully where there is no DOM event target (e.g. Node.js).
+     * @private
+     */
+    #addLifecycleListeners() {
+        const doc = globalThis.document;
+        if (doc !== undefined && typeof doc.addEventListener === 'function') {
+            doc.addEventListener('visibilitychange', this.#handleVisibilityChange);
+        }
+
+        if (typeof globalThis.addEventListener === 'function') {
+            globalThis.addEventListener('pagehide', this.#handlePageHide);
+            globalThis.addEventListener('pageshow', this.#handlePageShow);
+        }
+    }
+
+    /**
+     * @private
+     */
+    #removeLifecycleListeners() {
+        const doc = globalThis.document;
+        if (doc !== undefined && typeof doc.removeEventListener === 'function') {
+            doc.removeEventListener('visibilitychange', this.#handleVisibilityChange);
+        }
+
+        if (typeof globalThis.removeEventListener === 'function') {
+            globalThis.removeEventListener('pagehide', this.#handlePageHide);
+            globalThis.removeEventListener('pageshow', this.#handlePageShow);
+        }
+    }
+
+    /**
+     *
+     * @param {Object} [options]
+     * @param {number} [options.maxTimeout]
+     */
+    start({ maxTimeout = 100 } = {}) {
+        assert.isNumber(maxTimeout, 'maxTimeout');
+        assert.greaterThan(maxTimeout, 0);
+
+        if (this.#isUpdateLoopActive()) {
+            throw new Error("Already running");
+        }
+
+        this.#loop_started = true;
+        this.#isRunning = true;
+        this.#isSuspended = false;
+
+        const generation = this.#generation;
+        const is_current = () => this.#generation === generation;
+
+        /**
+         * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+         */
+        const update = (time) => {
+            if (!this.#isRunning || this.#isSuspended) {
+                return;
+            }
+
+            const delta = this.clock.getDeltaAt(time);
+
+            this.#last_tick_delta_s = delta;
+
+            this.onTick.send1(delta);
+        }
+
+        const timeoutCallback = () => {
+            cancelAnimationFrame(this.#animationFrameHandle);
+
+            if (!is_current()) {
+                return;
+            }
+
+            animate(current_time_in_seconds());
+        }
+
+        /**
+         * @param {number} timestamp the frame's, in milliseconds
+         */
+        const animationFrameCallback = (timestamp) => {
+            clearTimeout(this.#timeoutHandle);
+
+            if (!is_current()) {
+                return;
+            }
+
+            /*
+             Ticked here, on the frame's own timestamp, and before the frame is announced. This used to
+             be pushed to a setTimeout(0) "allowing draw to happen" first, which made every frame draw
+             the simulation as of the previous frame's timeout - and that fired whenever the previous
+             draw finished, so a steady motion was drawn at a different speed every frame.
+            */
+            animate(timestamp * 1e-3);
+
+            //a tick listener is allowed to stop us
+            if (!is_current()) {
+                return;
+            }
+
+            this.onFrame.send0();
+        }
+
+        /**
+         * @param {number} time in seconds, on the {@link current_time_in_seconds} timeline
+         */
+        const animate = (time) => {
+            if (!is_current()) {
+                return;
+            }
+
+            this.#animationFrameHandle = requestAnimationFrame(animationFrameCallback);
+
+            update(time);
+
+            //update() dispatches onTick, and a listener is allowed to stop us from inside it
+            if (!is_current()) {
+                return;
+            }
+
+            this.#timeoutHandle = setTimeout(timeoutCallback, maxTimeout);
+        }
+
+        this.clock.getDelta(); //purge delta
+        this.clock.start();
+
+        this.#addLifecycleListeners();
+
+        //recorded, so a stop() taken before the first frame lands can cancel it. The generation guard
+        //already makes the callback a no-op, but an uncancelled frame request keeps the closures (and
+        //everything the tick listeners hold) alive until it fires
+        this.#animationFrameHandle = requestAnimationFrame(animationFrameCallback);
+
+        //if we are starting while the page is already in the background, suspend right away
+        const doc = globalThis.document;
+        if (doc !== undefined && doc.visibilityState === 'hidden') {
+            this.#suspend();
+        }
+    }
+
+    pause() {
+
+        if (!this.#isUpdateLoopActive()) {
+            throw new Error("Not currently running");
+        }
+
+        this.#isRunning = false;
+
+        //freeze the clock so no simulation time accrues while paused; without this
+        //the first getDelta() after resume() returns the whole paused duration
+        this.clock.pause();
+    }
+
+    resume() {
+
+        if (!this.#isUpdateLoopActive()) {
+            throw new Error("Not currently running");
+        }
+
+
+        this.#isRunning = true;
+
+        //discard the time spent paused and restart from the current moment,
+        //mirroring #resume() for the background-suspend path
+        this.clock.getDelta();
+        this.clock.start();
+    }
+
+    stop() {
+        this.#generation++;
+
+        this.#removeLifecycleListeners();
+
+        clearTimeout(this.#timeoutHandle);
+        cancelAnimationFrame(this.#animationFrameHandle);
+        this.#loop_started = false;
+        this.#isRunning = false;
+        this.#isSuspended = false;
+
+        this.#timeoutHandle = -1;
+        this.#animationFrameHandle = -1;
+    }
+}
+
+export default Ticker;