@woosh/meep-engine 3.60.9 → 3.61.1

package/src/engine/network/sim/ActionLog.js

@@ -108,13 +108,16 @@ export class ActionLog {
 
     /**
      * Open a frame for writing after the records it already holds, rather than over them. A frame
-     * the ring does not hold is opened empty, as {@link begin_frame} opens it.
+     * the ring does not hold is opened empty, as {@link begin_frame} opens it — unless the log has
+     * moved past it, its slot holding a later frame: the later frame keeps its records, and what is
+     * written for this one is dropped at {@link end_frame}.
      *
      * For a writer adding to a frame someone else wrote: records arriving from a peer for a frame
      * this peer has already simulated. Opened with {@link begin_frame} instead, they would erase
      * this peer's own records for the frame — and with them the prior state a rewind needs to undo
      * that input, so a replay would apply it a second time, and the outbound stream, which packs
-     * from this log, would lose it before the peer it was for had confirmed it.
+     * from this log, would lose it before the peer it was for had confirmed it. A frame the log has
+     * moved past would erase the later frame's records the same way.
      *
      * @param {number} frame absolute frame number
      */
@@ -127,6 +130,34 @@ export class ActionLog {
         this.#current_frame = frame;
     }
 
+    /**
+     * Open a frame the log holds for writing from byte `offset` of what it holds: the records from
+     * there on are dropped, and what is written takes their place.
+     *
+     * For a writer that has taken records back off the world and writes them again — the frame's
+     * earlier records stay, the later ones are written over.
+     *
+     * @param {number} frame absolute frame number
+     * @param {number} offset a record boundary in the frame, at most its end
+     */
+    resume_frame_at(frame, offset) {
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.resume_frame_at: previous frame ${this.#current_frame} still open; call end_frame first`);
+        }
+        if (!this.#ring.has(frame)) {
+            throw new Error(`ActionLog.resume_frame_at: frame ${frame} is not present in the log`);
+        }
+
+        const buffer = this.#ring.resume(frame);
+        if (offset > buffer.position) {
+            throw new Error(`ActionLog.resume_frame_at: offset ${offset} is past frame ${frame}'s end ${buffer.position}`);
+        }
+        buffer.position = offset;
+
+        this.#current_buffer = buffer;
+        this.#current_frame = frame;
+    }
+
     /**
      * Drop every record the log holds, keeping each frame it holds present and empty.
      *

package/src/engine/network/sim/RewindEngine.d.ts

@@ -50,6 +50,15 @@ export class RewindEngine {
      * @param {number} frame
      */
     undo_frame(frame: number): void;
+    /**
+     * Undo the records of a frame that start at byte `from` or later, in reverse order — the ones
+     * written to the frame from there on — and leave the ones before it applied.
+     * Throws if the frame is not present in the log.
+     *
+     * @param {number} frame
+     * @param {number} from offset of a record boundary in the frame
+     */
+    undo_frame_from(frame: number, from: number): void;
     /**
      * Undo every frame in `(target_frame, current_frame]` so that the world is
      * left in start-of-`target_frame + 1` state. Equivalently: the world ends

package/src/engine/network/sim/RewindEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAeI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QA0BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAuDJ"}
+{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAeI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,uBAHW,MAAM,QACN,MAAM,QA4BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAuDJ"}

package/src/engine/network/sim/RewindEngine.js

@@ -67,9 +67,22 @@ export class RewindEngine {
      * @param {number} frame
      */
     undo_frame(frame) {
+        this.undo_frame_from(frame, 0);
+    }
+
+    /**
+     * Undo the records of a frame that start at byte `from` or later, in reverse order — the ones
+     * written to the frame from there on — and leave the ones before it applied.
+     * Throws if the frame is not present in the log.
+     *
+     * @param {number} frame
+     * @param {number} from offset of a record boundary in the frame
+     */
+    undo_frame_from(frame, from) {
         assert.isNonNegativeInteger(frame, 'frame');
+        assert.isNonNegativeInteger(from, 'from');
         if (!this.action_log.has_frame(frame)) {
-            throw new Error(`RewindEngine.undo_frame: frame ${frame} is not present in the action log`);
+            throw new Error(`RewindEngine: frame ${frame} is not present in the action log`);
         }
 
         // 1. First pass: walk forward to find record boundaries.
@@ -77,6 +90,7 @@ export class RewindEngine {
         cursor.open(this.action_log, frame);
         let record_count = 0;
         while (cursor.next()) {
+            if (cursor.record_start < from) continue;
             if (record_count >= this.#record_starts.length) {
                 this.#grow_record_starts();
             }

package/src/engine/network/state/FrameBufferRing.d.ts

@@ -21,7 +21,9 @@
  * from that moment; its recorded length is what was last committed — 0 for a
  * slot `open` claimed, the old end for a frame `resume` reopened — so a reader
  * sees none of what is still being written. Owners that allow a frame to stay
- * open across calls are responsible for saying so.
+ * open across calls are responsible for saying so. `resume` never claims a slot
+ * that holds a later frame: a frame the ring has moved past is written to a
+ * buffer the ring does not keep.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -52,8 +54,12 @@ export class FrameBufferRing {
     open(frame: number): BinaryBuffer;
     /**
      * Claim the slot for `frame` to write AFTER what it already holds: a slot holding `frame`
-     * hands back its buffer positioned at its committed end, and any other slot is claimed as
-     * {@link open} claims it. {@link commit} then fixes the longer length.
+     * hands back its buffer positioned at its committed end, and a slot holding an earlier frame,
+     * or none, is claimed as {@link open} claims it. {@link commit} then fixes the longer length.
+     *
+     * A slot holding a later frame is not claimed: the ring has moved past `frame`, and claiming
+     * the slot would erase a frame newer than the one being written. What is written for `frame`
+     * goes to a buffer the ring does not keep, and `frame` stays absent.
      *
      * @param {number} frame absolute frame number
      * @returns {BinaryBuffer} positioned at the frame's committed end, ready to be written
@@ -69,9 +75,10 @@ export class FrameBufferRing {
      */
     clear(): void;
     /**
-     * Record how far the writer got, fixing the frame's length for readers.
+     * Record how far the writer got, fixing the frame's length for readers. A frame the ring does
+     * not hold — one {@link resume} found it had moved past — keeps nothing.
      *
-     * @param {number} frame absolute frame number, previously passed to {@link open}
+     * @param {number} frame absolute frame number, previously passed to {@link open} or {@link resume}
      */
     commit(frame: number): void;
     /**

package/src/engine/network/state/FrameBufferRing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameBufferRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/FrameBufferRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAoCI;;OAEG;IACH,4DAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,EAmB9E;IA5BD;;;;;OAKG;IACH,yBAFU,MAAM,CAED;IAwBf;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,YAAY,CAkBxB;IAED;;;;;;;OAOG;IACH,cAHW,MAAM,GACJ,YAAY,CAgBxB;IAED;;;OAGG;IACH,cAEC;IAED;;OAEG;IACH,cAGC;IAED;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;;CACJ;6BAnN4B,sCAAsC"}
+{"version":3,"file":"FrameBufferRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/FrameBufferRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA2CI;;OAEG;IACH,4DAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,EAmB9E;IA5BD;;;;;OAKG;IACH,yBAFU,MAAM,CAED;IAwBf;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,YAAY,CAkBxB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,YAAY,CA0BxB;IAED;;;OAGG;IACH,cAEC;IAED;;OAEG;IACH,cAGC;IAED;;;;;OAKG;IACH,cAFW,MAAM,QAUhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;;CACJ;6BA7O4B,sCAAsC"}

package/src/engine/network/state/FrameBufferRing.js

@@ -24,7 +24,9 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
  * from that moment; its recorded length is what was last committed — 0 for a
  * slot `open` claimed, the old end for a frame `resume` reopened — so a reader
  * sees none of what is still being written. Owners that allow a frame to stay
- * open across calls are responsible for saying so.
+ * open across calls are responsible for saying so. `resume` never claims a slot
+ * that holds a later frame: a frame the ring has moved past is written to a
+ * buffer the ring does not keep.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -57,6 +59,13 @@ export class FrameBufferRing {
      */
     #write_ends;
 
+    /**
+     * What {@link resume} hands the writer of a frame the ring has moved past: rewound for each
+     * writer, never read and never kept.
+     * @type {BinaryBuffer}
+     */
+    #discard = new BinaryBuffer();
+
     /**
      * Number of frames retained. Writing frame `f` evicts frame
      * `f - frame_capacity`.
@@ -114,8 +123,12 @@ export class FrameBufferRing {
 
     /**
      * Claim the slot for `frame` to write AFTER what it already holds: a slot holding `frame`
-     * hands back its buffer positioned at its committed end, and any other slot is claimed as
-     * {@link open} claims it. {@link commit} then fixes the longer length.
+     * hands back its buffer positioned at its committed end, and a slot holding an earlier frame,
+     * or none, is claimed as {@link open} claims it. {@link commit} then fixes the longer length.
+     *
+     * A slot holding a later frame is not claimed: the ring has moved past `frame`, and claiming
+     * the slot would erase a frame newer than the one being written. What is written for `frame`
+     * goes to a buffer the ring does not keep, and `frame` stays absent.
      *
      * @param {number} frame absolute frame number
      * @returns {BinaryBuffer} positioned at the frame's committed end, ready to be written
@@ -125,7 +138,17 @@ export class FrameBufferRing {
 
         const slot = frame % this.frame_capacity;
 
-        if (this.#frame_numbers[slot] !== frame) {
+        const occupant = this.#frame_numbers[slot];
+
+        if (occupant > frame) {
+            const discard = this.#discard;
+
+            discard.position = 0;
+
+            return discard;
+        }
+
+        if (occupant !== frame) {
             return this.open(frame);
         }
 
@@ -153,15 +176,18 @@ export class FrameBufferRing {
     }
 
     /**
-     * Record how far the writer got, fixing the frame's length for readers.
+     * Record how far the writer got, fixing the frame's length for readers. A frame the ring does
+     * not hold — one {@link resume} found it had moved past — keeps nothing.
      *
-     * @param {number} frame absolute frame number, previously passed to {@link open}
+     * @param {number} frame absolute frame number, previously passed to {@link open} or {@link resume}
      */
     commit(frame) {
         assert.isNonNegativeInteger(frame, 'frame');
 
         const slot = frame % this.frame_capacity;
 
+        if (this.#frame_numbers[slot] !== frame) return;
+
         this.#write_ends[slot] = this.#buffers[slot].position;
     }
 

package/src/engine/network/time/TimeDilation.d.ts

@@ -1,20 +1,26 @@
 /**
- * Server-side computation of "tell client to run a bit faster or slower."
+ * How fast a client runs, from where its input lands at the host.
  *
- * The server maintains a target depth for its per-client input buffer. When the
- * buffer is too shallow (client's inputs aren't arriving fast enough), the
- * server tells the client to run the next few ticks at a slightly compressed
- * tick duration ("speed up"). When the buffer is too deep (client is sending
- * inputs faster than the server consumes them), the server asks for stretching.
- *
- * This is the same primitive used in Overwatch ("time dilation") and Rocket
- * League. Adjustment is bounded to a few percent so it's imperceptible.
- *
- * Output is a multiplier on tick duration:
+ * The host reports, each tick, how many frames ahead of its simulation the client's newest frame is:
+ * the depth of its input buffer for that client. The client wants it at {@link target_buffer_depth},
+ * deep enough that its input is there when the host needs it and no deeper, since every frame of it is
+ * a frame of latency. {@link compute} turns the depth into a multiplier on the client's tick duration:
  *   factor < 1.0 → run faster (smaller tick interval)
  *   factor > 1.0 → run slower (larger tick interval)
  *   factor = 1.0 → run at nominal rate
  *
+ * Behind, and up to `max_dilation × T` frames ahead, an error is steered at up to {@link max_dilation}:
+ * a few percent, too little to see, which is what jitter and clock drift need. This is the primitive
+ * Overwatch and Rocket League call time dilation. A larger lead — the host lost time: a hidden or
+ * hitched host tab — is repaid in proportion to its size: the client runs at `1 / (1 + lead / T)` of
+ * its rate, which nears a standstill and never reaches it, so it keeps stepping and reading the host's
+ * reports. The reports are a round trip old, and a response in proportion to an error that old repays
+ * it without overshooting when its time constant is at least `e` times the delay, so `T` is
+ * `e × max_round_trip_frames` — 87 frames for a 32-frame round trip, which puts the steering's reach
+ * at 4.35 frames: on every round trip up to that one, a lead is repaid to the end the steering reaches
+ * on its own. Behind, the steering is all there is: running fast costs steps, and a client a whole
+ * window behind re-takes the host's time instead (`NetworkSession`).
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -24,12 +30,18 @@ export class TimeDilation {
      *   target_buffer_depth?: number,
      *   max_dilation?: number,
      *   gain?: number,
-     * }} [options]
+     *   max_round_trip_frames: number,
+     * }} options
+     *
+     * `max_round_trip_frames`: the longest round trip, in frames, the client runs on — how old, at
+     * most, the reports this works from are. Its owners pass its action log's depth: on a longer round
+     * trip the host's frames land past the log.
      */
-    constructor({ target_buffer_depth, max_dilation, gain }?: {
+    constructor({ target_buffer_depth, max_dilation, gain, max_round_trip_frames }?: {
         target_buffer_depth?: number;
         max_dilation?: number;
         gain?: number;
+        max_round_trip_frames: number;
     });
     /** @readonly */
     readonly target_buffer_depth: number;
@@ -37,13 +49,17 @@ export class TimeDilation {
     readonly max_dilation: number;
     /** @readonly */
     readonly gain: number;
+    /** @readonly */
+    readonly max_round_trip_frames: number;
     /**
      * Compute the dilation factor for a client whose current input buffer depth
      * is `current_depth` (number of unconsumed input frames).
      *
      * @param {number} current_depth
-     * @returns {number} factor in `[1 - max_dilation, 1 + max_dilation]`
+     * @returns {number} factor in `[1 - max_dilation, ∞)`; at most `1 + max_dilation` for a lead the
+     *   steering repays
      */
     compute(current_depth: number): number;
+    #private;
 }
 //# sourceMappingURL=TimeDilation.d.ts.map

package/src/engine/network/time/TimeDilation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TimeDilation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/time/TimeDilation.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAEI;;;;;;OAMG;IACH,0DANW;QACV,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAQ,CAAC,EAAE,MAAM,CAAC;KACf,EAeH;IARG,gBAAgB;IAChB,qCAA8C;IAE9C,gBAAgB;IAChB,8BAAgC;IAEhC,gBAAgB;IAChB,sBAAgB;IAGpB;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAQlB;CACJ"}
+{"version":3,"file":"TimeDilation.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/time/TimeDilation.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAQI;;;;;;;;;;;OAWG;IACH,iFAXW;QACV,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,qBAAyB,EAAE,MAAM,CAAC;KAC/B,EA6BH;IAbG,gBAAgB;IAChB,qCAA8C;IAE9C,gBAAgB;IAChB,8BAAgC;IAEhC,gBAAgB;IAChB,sBAAgB;IAEhB,gBAAgB;IAChB,uCAAkD;IAKtD;;;;;;;OAOG;IACH,uBAJW,MAAM,GACJ,MAAM,CAWlB;;CACJ"}

package/src/engine/network/time/TimeDilation.js

@@ -2,39 +2,61 @@ import { assert } from "../../../core/assert.js";
 import { clamp } from "../../../core/math/clamp.js";
 
 /**
- * Server-side computation of "tell client to run a bit faster or slower."
+ * How fast a client runs, from where its input lands at the host.
  *
- * The server maintains a target depth for its per-client input buffer. When the
- * buffer is too shallow (client's inputs aren't arriving fast enough), the
- * server tells the client to run the next few ticks at a slightly compressed
- * tick duration ("speed up"). When the buffer is too deep (client is sending
- * inputs faster than the server consumes them), the server asks for stretching.
- *
- * This is the same primitive used in Overwatch ("time dilation") and Rocket
- * League. Adjustment is bounded to a few percent so it's imperceptible.
- *
- * Output is a multiplier on tick duration:
+ * The host reports, each tick, how many frames ahead of its simulation the client's newest frame is:
+ * the depth of its input buffer for that client. The client wants it at {@link target_buffer_depth},
+ * deep enough that its input is there when the host needs it and no deeper, since every frame of it is
+ * a frame of latency. {@link compute} turns the depth into a multiplier on the client's tick duration:
  *   factor < 1.0 → run faster (smaller tick interval)
  *   factor > 1.0 → run slower (larger tick interval)
  *   factor = 1.0 → run at nominal rate
  *
+ * Behind, and up to `max_dilation × T` frames ahead, an error is steered at up to {@link max_dilation}:
+ * a few percent, too little to see, which is what jitter and clock drift need. This is the primitive
+ * Overwatch and Rocket League call time dilation. A larger lead — the host lost time: a hidden or
+ * hitched host tab — is repaid in proportion to its size: the client runs at `1 / (1 + lead / T)` of
+ * its rate, which nears a standstill and never reaches it, so it keeps stepping and reading the host's
+ * reports. The reports are a round trip old, and a response in proportion to an error that old repays
+ * it without overshooting when its time constant is at least `e` times the delay, so `T` is
+ * `e × max_round_trip_frames` — 87 frames for a 32-frame round trip, which puts the steering's reach
+ * at 4.35 frames: on every round trip up to that one, a lead is repaid to the end the steering reaches
+ * on its own. Behind, the steering is all there is: running fast costs steps, and a client a whole
+ * window behind re-takes the host's time instead (`NetworkSession`).
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
 export class TimeDilation {
 
+    /**
+     * The time constant, in frames, at which a lead is repaid: `e` of the longest round trips.
+     * @type {number}
+     */
+    #repay_frames;
+
     /**
      * @param {{
      *   target_buffer_depth?: number,
      *   max_dilation?: number,
      *   gain?: number,
-     * }} [options]
+     *   max_round_trip_frames: number,
+     * }} options
+     *
+     * `max_round_trip_frames`: the longest round trip, in frames, the client runs on — how old, at
+     * most, the reports this works from are. Its owners pass its action log's depth: on a longer round
+     * trip the host's frames land past the log.
      */
-    constructor({ target_buffer_depth = 2, max_dilation = 0.05, gain = 0.05 } = {}) {
+    constructor({ target_buffer_depth = 2, max_dilation = 0.05, gain = 0.05, max_round_trip_frames } = {}) {
         assert.isNumber(target_buffer_depth, 'target_buffer_depth');
         assert.isNumber(max_dilation, 'max_dilation');
         assert.isNumber(gain, 'gain');
 
+        // A real check: NaN here reaches the engine's fixed-step time scale and stops the client.
+        if (!(max_round_trip_frames > 0 && Number.isFinite(max_round_trip_frames))) {
+            throw new Error(`TimeDilation: max_round_trip_frames must be a positive number of frames, got ${max_round_trip_frames}`);
+        }
+
         /** @readonly */
         this.target_buffer_depth = target_buffer_depth;
 
@@ -43,6 +65,11 @@ export class TimeDilation {
 
         /** @readonly */
         this.gain = gain;
+
+        /** @readonly */
+        this.max_round_trip_frames = max_round_trip_frames;
+
+        this.#repay_frames = Math.E * max_round_trip_frames;
     }
 
     /**
@@ -50,13 +77,16 @@ export class TimeDilation {
      * is `current_depth` (number of unconsumed input frames).
      *
      * @param {number} current_depth
-     * @returns {number} factor in `[1 - max_dilation, 1 + max_dilation]`
+     * @returns {number} factor in `[1 - max_dilation, ∞)`; at most `1 + max_dilation` for a lead the
+     *   steering repays
      */
     compute(current_depth) {
         assert.isNumber(current_depth, 'current_depth');
+
         // depth > target ⇒ slow client down (factor > 1). depth < target ⇒ speed up (factor < 1).
-        const raw = (current_depth - this.target_buffer_depth) * this.gain;
-        const clamped = clamp(raw, -this.max_dilation, this.max_dilation);
-        return 1.0 + clamped;
+        const error = current_depth - this.target_buffer_depth;
+        const steered = 1.0 + clamp(error * this.gain, -this.max_dilation, this.max_dilation);
+
+        return error > 0 ? Math.max(steered, 1.0 + error / this.#repay_frames) : steered;
     }
 }

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -66,11 +66,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#485@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#486@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#485@#clear_field"(fluid: FluidComponent): void;
+    static "__#486@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -82,7 +82,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#485@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#486@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -102,7 +102,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#485@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#486@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform64> | ResourceAccessSpecification<typeof FluidObstacle> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof FluidComponent>)[];

package/src/generation/foliage/skeleton/ShootWoodHash.d.ts

@@ -3,7 +3,7 @@
  * wood, and thinner wood that thicker wood has grown into can be found. A unit is added once, when it has grown, under
  * the cells its axis line crosses; a query reads every unit's place and radius from its axis as they are then, and
  * reaches as far round as the thickest wood ({@link max_radius}), so wood that thickens needs no re-adding. The units
- * of an axis that has died are passed over.
+ * of an axis that has died are passed over, and leave the hash at the next {@link refresh}.
  */
 export class ShootWoodHash {
     /**
@@ -69,7 +69,8 @@ export class ShootWoodHash {
     add(m: number, k: number): void;
     /**
      * Records each cell's thickest living unit, after the wood has thickened, and the thickest of all
-     * ({@link max_radius}).
+     * ({@link max_radius}). A dead axis does not live again, so its units leave their cells, in the order the rest
+     * were added, and a cell left empty leaves the hash.
      */
     refresh(): void;
     /**

package/src/generation/foliage/skeleton/ShootWoodHash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShootWoodHash.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/ShootWoodHash.js"],"names":[],"mappings":"AAwBA;;;;;;GAMG;AACH;IA8FI;;;;;;OAMG;IACH,uBALW;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,KAClC,MAAM,KACN,MAAM,GACJ,MAAM,CAMlB;IApED;;OAEG;IACH,kBAFW,MAAM;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,EAIrF;IAzCD,oCAAoC;IACpC,OADW,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC,CACd;IAElB;;;;OAIG;IACH,UAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAER;IAErB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,WAFU,MAAM,EAAE,CAEH;IAEf;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,MAFU,MAAM,EAAE,CAER;IAEV,cAAU;IAMN;eAHqB,OAAO;gBAAU,MAAM,EAAE;eAAS,MAAM,EAAE;eAAS,MAAM,EAAE;QAGhE;IAGpB;;;;OAIG;IACH,OAHW,MAAM,KACN,MAAM,QAsBhB;IAED;;;OAGG;IACH,gBAiBC;IAeD;;;;;;;;;;;OAWG;IACH,QAPW,UAAU,MAAM,CAAC,KACjB,UAAU,MAAM,CAAC,UACjB,MAAM,cACN,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,OAAO,GAC/C,MAAM,CA6ClB;CACJ"}
+{"version":3,"file":"ShootWoodHash.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/skeleton/ShootWoodHash.js"],"names":[],"mappings":"AAiCA;;;;;;GAMG;AACH;IA4GI;;;;;;OAMG;IACH,uBALW;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,KAClC,MAAM,KACN,MAAM,GACJ,MAAM,CAMlB;IAlFD;;OAEG;IACH,kBAFW,MAAM;QAAC,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC,EAIrF;IAzCD,oCAAoC;IACpC,OADW,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC,CACd;IAElB;;;;OAIG;IACH,UAFU,IAAI,MAAM,EAAE,MAAM,CAAC,CAER;IAErB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,WAFU,MAAM,EAAE,CAEH;IAEf;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEF;IAEhB;;;OAGG;IACH,MAFU,MAAM,EAAE,CAER;IAEV,cAAU;IAMN;eAHqB,OAAO;gBAAU,MAAM,EAAE;eAAS,MAAM,EAAE;eAAS,MAAM,EAAE;QAGhE;IAGpB;;;;OAIG;IACH,OAHW,MAAM,KACN,MAAM,QA2BhB;IAED;;;;OAIG;IACH,gBAyBC;IAeD;;;;;;;;;;;OAWG;IACH,QAPW,UAAU,MAAM,CAAC,KACjB,UAAU,MAAM,CAAC,UACjB,MAAM,cACN,MAAM,eACG,MAAM,QAAE,MAAM,QAAE,MAAM,QAAE,MAAM,KAAG,OAAO,GAC/C,MAAM,CA6ClB;CACJ"}

package/src/generation/foliage/skeleton/ShootWoodHash.js

@@ -1,3 +1,4 @@
+import { aabb3_intersects_segment3 } from "../../../core/geom/3d/aabb/aabb3_intersects_segment3.js";
 import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
 import { shoot_radius } from "./shoot_geometry.js";
 
@@ -20,6 +21,14 @@ const CLEARANCE = 0.001;
  */
 const KEY_SPAN = 2048;
 
+/**
+ * Margin (m) a cell is widened by when asking whether an axis line crosses it: far above the rounding of a point at
+ * the key's 205 m span, far below any wood, so a line along a cell's face or through its edge is under the cells either
+ * side of it.
+ * @type {number}
+ */
+const CROSSING_TOLERANCE = WOOD_CELL * 2 ** -20;
+
 const SCRATCH_ST = new Float64Array(2);
 
 /**
@@ -27,7 +36,7 @@ const SCRATCH_ST = new Float64Array(2);
  * wood, and thinner wood that thicker wood has grown into can be found. A unit is added once, when it has grown, under
  * the cells its axis line crosses; a query reads every unit's place and radius from its axis as they are then, and
  * reaches as far round as the thickest wood ({@link max_radius}), so wood that thickens needs no re-adding. The units
- * of an axis that has died are passed over.
+ * of an axis that has died are passed over, and leave the hash at the next {@link refresh}.
  */
 export class ShootWoodHash {
     /** @type {Map<number, number[]>} */
@@ -89,6 +98,11 @@ export class ShootWoodHash {
         const y0 = Math.floor(Math.min(p[a + 1], p[b + 1]) / WOOD_CELL), y1 = Math.floor(Math.max(p[a + 1], p[b + 1]) / WOOD_CELL);
         const z0 = Math.floor(Math.min(p[a + 2], p[b + 2]) / WOOD_CELL), z1 = Math.floor(Math.max(p[a + 2], p[b + 2]) / WOOD_CELL);
         for (let x = x0; x <= x1; x++) for (let y = y0; y <= y1; y++) for (let z = z0; z <= z1; z++) {
+            if (!aabb3_intersects_segment3(
+                x * WOOD_CELL - CROSSING_TOLERANCE, y * WOOD_CELL - CROSSING_TOLERANCE, z * WOOD_CELL - CROSSING_TOLERANCE,
+                (x + 1) * WOOD_CELL + CROSSING_TOLERANCE, (y + 1) * WOOD_CELL + CROSSING_TOLERANCE, (z + 1) * WOOD_CELL + CROSSING_TOLERANCE,
+                p[a], p[a + 1], p[a + 2], p[b], p[b + 1], p[b + 2]
+            )) continue;
             const key = ((x + KEY_SPAN / 2) * KEY_SPAN + (y + KEY_SPAN / 2)) * KEY_SPAN + (z + KEY_SPAN / 2);
             let list = this.cells.get(key);
             if (list === undefined) {
@@ -102,21 +116,30 @@ export class ShootWoodHash {
 
     /**
      * Records each cell's thickest living unit, after the wood has thickened, and the thickest of all
-     * ({@link max_radius}).
+     * ({@link max_radius}). A dead axis does not live again, so its units leave their cells, in the order the rest
+     * were added, and a cell left empty leaves the hash.
      */
     refresh() {
         const axes = this.axes;
         let most = 0;
         for (const [key, list] of this.cells) {
             let max = 0;
+            let kept = 0;
             for (let i = 0; i < list.length; i++) {
                 const id = list[i];
                 const axis = axes[this.unit_axis[id]];
                 if (!axis.alive) continue;
+                list[kept++] = id;
                 const k = this.unit_index[id];
                 const thickest = axis.radii.length > k + 1 ? Math.max(axis.radii[k], axis.radii[k + 1]) : shoot_radius(axis.units[k], 0);
                 if (thickest > max) max = thickest;
             }
+            if (kept === 0) {
+                this.cells.delete(key);
+                this.cell_max.delete(key);
+                continue;
+            }
+            list.length = kept;
             this.cell_max.set(key, max);
             if (max > most) most = max;
         }

package/src/shade/renderer/buffer/graph_read_buffer.d.ts

@@ -5,7 +5,9 @@
  * @param {number} buffer
  * @param {number} [offset=0]
  * @param {number} [size] defaults to buffer.size - offset
- * @param {number} [timeout] in milliseconds, 0 for no timeout. Timeout will start immediately, meaning that if you don't schedule the graph immediately - you might see unexpected behaviour.
+ * @param {number} [timeout] in milliseconds, 0 for no timeout: how long the read waits for its pass to run, starting
+ * now. A graph that is never run, or stops at a throwing pass before this one, rejects the read here. Once the pass has
+ * run, the read waits for the device however far behind it is, and settles when the mapping does.
  * @returns {Promise<Reference<ArrayBuffer>>} don't forget to release the reference
  */
 export function graph_read_buffer({ graph, buffer, offset, size, timeout }: FrameGraph): Promise<Reference<ArrayBuffer>>;

package/src/shade/renderer/buffer/graph_read_buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_read_buffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/graph_read_buffer.js"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,yFAFa,QAAQ,UAAU,WAAW,CAAC,CAAC,CAuH3C;0BApIyB,2CAA2C"}
+{"version":3,"file":"graph_read_buffer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/graph_read_buffer.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;GAWG;AACH,yFAFa,QAAQ,UAAU,WAAW,CAAC,CAAC,CAwH3C;0BAvIyB,2CAA2C"}

package/src/shade/renderer/buffer/graph_read_buffer.js

@@ -12,7 +12,9 @@ const scratch_buffer_descriptor = new BufferResourceDescriptor();
  * @param {number} buffer
  * @param {number} [offset=0]
  * @param {number} [size] defaults to buffer.size - offset
- * @param {number} [timeout] in milliseconds, 0 for no timeout. Timeout will start immediately, meaning that if you don't schedule the graph immediately - you might see unexpected behaviour.
+ * @param {number} [timeout] in milliseconds, 0 for no timeout: how long the read waits for its pass to run, starting
+ * now. A graph that is never run, or stops at a throwing pass before this one, rejects the read here. Once the pass has
+ * run, the read waits for the device however far behind it is, and settles when the mapping does.
  * @returns {Promise<Reference<ArrayBuffer>>} don't forget to release the reference
  */
 export function graph_read_buffer({
@@ -47,6 +49,12 @@ export function graph_read_buffer({
      * @param {GraphicsExecutionContext} context
      */
     function execute(data, resources, context) {
+        // the copy is recorded: the mapping lands, or is refused, however long the device takes
+        if (timeout_handle !== -1) {
+            clearTimeout(timeout_handle);
+            timeout_handle = -1;
+        }
+
         /**
          * @type {GPUBuffer}
          */
@@ -94,11 +102,6 @@ export function graph_read_buffer({
                 return;
             }
 
-            if (timeout_handle !== -1) {
-                clearTimeout(timeout_handle);
-                timeout_handle = -1;
-            }
-
             const data = destination.getMappedRange(0, _size);
 
             ref = new Reference();

package/src/shade/renderer/buffer/util/shader_buffer_copy_storage_to_storage.d.ts

@@ -1,6 +1,11 @@
 /**
  * Shader is useful for copying buffers where the buffers are missing `GPUBufferUsage.COPY_DST` or `GPUBufferUsage.COPY_SRC`.
  * This is a pure utility shader.
+ *
+ * Copies the first `size` words. The launch may be smaller than that — a copy longer than
+ * `maxComputeWorkgroupsPerDimension` workgroups has to be — and every lane strides through the rest
+ * by the whole grid, so a caller that clamps the launch still has every word copied.
+ *
  * @type {ComputeShader}
  */
 export const shader_buffer_copy_storage_to_storage: ComputeShader;

package/src/shade/renderer/buffer/util/shader_buffer_copy_storage_to_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_buffer_copy_storage_to_storage.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/util/shader_buffer_copy_storage_to_storage.js"],"names":[],"mappings":"AAkCA;;;;GAIG;AACH,oDAFU,aAAa,CAMpB;8BAvC2B,+BAA+B"}
+{"version":3,"file":"shader_buffer_copy_storage_to_storage.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/util/shader_buffer_copy_storage_to_storage.js"],"names":[],"mappings":"AAkCA;;;;;;;;;GASG;AACH,oDAFU,aAAa,CAMpB;8BA5C2B,+BAA+B"}