@woosh/meep-engine 3.30.0 → 3.32.0

package/src/engine/network/transport/DeferredTransport.js

@@ -0,0 +1,143 @@
+import { Deque } from "../../../core/collection/queue/Deque.js";
+import { Transport } from "./Transport.js";
+
+/**
+ * A transport that holds what its underlying transport raises — packets, and a lost connection —
+ * until {@link flush}, instead of passing it on the moment it happens.
+ *
+ * A browser transport raises a packet from its own event callback, whenever the event loop gets
+ * to it. In a running game that is usually after the engine has blended a frame's poses into the
+ * live components and before that frame is drawn, and whatever the packet writes there is written
+ * over what is about to be drawn, and over what the next step will simulate from. Holding packets
+ * until a point the simulation chooses — the start of a fixed step — makes every network write
+ * land where simulation writes land.
+ *
+ * Order is kept: packets are delivered in the order they arrived, and a lost connection is
+ * reported after the packets that arrived before it (a host's parting DISCONNECT is read before
+ * its socket closes). Nothing that arrives after a lost connection is delivered.
+ *
+ * Sending, connecting, disconnecting and stats are the underlying transport's.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class DeferredTransport extends Transport {
+    /** @type {Transport} */
+    #inner;
+
+    /**
+     * Packets held, oldest first; each a copy, since the underlying buffer is reused.
+     * @type {Deque<Uint8Array>}
+     */
+    #held = new Deque();
+
+    /** @type {boolean} */
+    #lost = false;
+
+    /** @type {string} */
+    #lost_reason = '';
+
+    /** @type {(bytes: Uint8Array, length: number) => void} */
+    #on_inner_receive;
+
+    /** @type {(reason: string) => void} */
+    #on_inner_disconnect;
+
+    /**
+     * Packets the underlying transport has raised, delivered or not: how much the other end has
+     * sent, for telling a live connection from a silent one.
+     * @type {number}
+     */
+    received_count = 0;
+
+    /**
+     * @param {Transport} inner
+     */
+    constructor(inner) {
+        super();
+
+        this.#inner = inner;
+
+        this.reliable = inner.reliable;
+        this.ordered = inner.ordered;
+
+        this.#on_inner_receive = (bytes, length) => {
+            if (this.#lost) {
+                return;
+            }
+            this.#held.addLast(bytes.slice(0, length));
+            this.received_count++;
+        };
+
+        this.#on_inner_disconnect = (reason) => {
+            if (this.#lost) {
+                return;
+            }
+            this.#lost = true;
+            this.#lost_reason = reason;
+        };
+
+        inner.onReceive.add(this.#on_inner_receive);
+        inner.onDisconnect.add(this.#on_inner_disconnect);
+    }
+
+    /**
+     * @returns {Transport}
+     */
+    get inner() {
+        return this.#inner;
+    }
+
+    /**
+     * Deliver everything held: each packet on {@link onReceive}, oldest first, then a lost
+     * connection on {@link onDisconnect}. A packet that arrives while delivering is delivered in
+     * the same call.
+     *
+     * A handler may flush again: `NetworkSession.connect()` does, when an application calls it
+     * from inside the delivery of the very peer it rebinds. Each packet leaves the queue before it
+     * is delivered, so the inner call goes on from the next one and returns with the rest
+     * delivered, lost connection included, and the outer call finds nothing left: nothing is
+     * delivered twice or out of order.
+     */
+    flush() {
+        const held = this.#held;
+
+        while (!held.isEmpty()) {
+            const bytes = held.removeFirst();
+            this.onReceive.send2(bytes, bytes.length);
+        }
+
+        if (this.#lost) {
+            this.fire_disconnect_once(this.#lost_reason);
+        }
+    }
+
+    /**
+     * Stop listening to the underlying transport and drop whatever is held. The underlying
+     * transport itself is left as it is.
+     */
+    release() {
+        this.#inner.onReceive.remove(this.#on_inner_receive);
+        this.#inner.onDisconnect.remove(this.#on_inner_disconnect);
+        this.#held.clear();
+    }
+
+    send(bytes, length) {
+        this.#inner.send(bytes, length);
+    }
+
+    connect() {
+        return this.#inner.connect();
+    }
+
+    disconnect() {
+        // torn down on purpose: not news, and nothing held is for anyone any more
+        this.latch_disconnect();
+        this.#held.clear();
+        this.#inner.disconnect();
+    }
+
+    getStats() {
+        return this.#inner.getStats();
+    }
+}

package/src/engine/network/transport/LoopbackTransport.d.ts

@@ -33,6 +33,14 @@ export class LoopbackTransport extends Transport {
      * @returns {number}
      */
     deliver_all(): number;
+    /**
+     * Deliver the next `n` packets in the inbound queue to {@link onReceive}, in order — fewer if
+     * fewer are queued. Returns the number of packets delivered.
+     *
+     * @param {number} n
+     * @returns {number}
+     */
+    deliver_next(n: number): number;
     /**
      * Drop the next `n` queued inbound packets (simulates packet loss).
      * If fewer than `n` are queued, drops what's available.

package/src/engine/network/transport/LoopbackTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LoopbackTransport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/LoopbackTransport.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAqBI;;;;;OAKG;IACH,oBAHW,iBAAiB,KACjB,iBAAiB,QAO3B;IAyBD;;;;;OAKG;IACH,eAFa,MAAM,CAWlB;IAED;;;;;;OAMG;IACH,aAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;OAKG;IACH,WAHW,MAAM,KACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;;CA8BJ;0BAnKyB,gBAAgB"}
+{"version":3,"file":"LoopbackTransport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/LoopbackTransport.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAqBI;;;;;OAKG;IACH,oBAHW,iBAAiB,KACjB,iBAAiB,QAO3B;IAyBD;;;;;OAKG;IACH,eAFa,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,gBAHW,MAAM,GACJ,MAAM,CAWlB;IAED;;;;;;OAMG;IACH,aAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;OAKG;IACH,WAHW,MAAM,KACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;;CA8BJ;0BA9KyB,gBAAgB"}

package/src/engine/network/transport/LoopbackTransport.js

@@ -85,8 +85,19 @@ export class LoopbackTransport extends Transport {
      * @returns {number}
      */
     deliver_all() {
+        return this.deliver_next(Infinity);
+    }
+
+    /**
+     * Deliver the next `n` packets in the inbound queue to {@link onReceive}, in order — fewer if
+     * fewer are queued. Returns the number of packets delivered.
+     *
+     * @param {number} n
+     * @returns {number}
+     */
+    deliver_next(n) {
         let delivered = 0;
-        while (this.#in_queue.length > 0) {
+        while (delivered < n && this.#in_queue.length > 0) {
             const packet = this.#in_queue.shift();
             this.count_in(packet.length);
             this.onReceive.send2(packet, packet.length);

package/src/engine/network/transport/ReliableCommandPipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReliableCommandPipeline.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/ReliableCommandPipeline.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,iDAFU,MAAM,CAEiE;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAsBI;;;;;;;;OAQG;IACH,uFARW;QACV,OAAW,EAAE,OAAO,cAAc,EAAE,OAAO,CAAC;QAC5C,WAAe,EAAE,MAAM,CAAC;QACxB,WAAe,CAAC,EAAE,MAAM,CAAC;QACzB,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAe,CAAC,EAAE,MAAM,CAAC;KACtB,EAmFH;IAnEG,6CAA6C;IAC7C,SADW,OAAO,cAAc,EAAE,OAAO,CACnB;IACtB,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;IA2B9B;;;;;;OAMG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;OAOG;IACH,oBAFU,MAAM,CAEsB;IAS1C;;;;;;;;OAQG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CA+BlB;IAED;;;;;;;;OAQG;IACH,oBAJW,YAAY,gBACZ,MAAM,QAqBhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAMC;;CAsCJ;mBAxTkB,uCAAuC;6BAD7B,sCAAsC"}
+{"version":3,"file":"ReliableCommandPipeline.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/ReliableCommandPipeline.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,iDAFU,MAAM,CAEiE;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAsBI;;;;;;;;OAQG;IACH,uFARW;QACV,OAAW,EAAE,OAAO,cAAc,EAAE,OAAO,CAAC;QAC5C,WAAe,EAAE,MAAM,CAAC;QACxB,WAAe,CAAC,EAAE,MAAM,CAAC;QACzB,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAe,CAAC,EAAE,MAAM,CAAC;KACtB,EAmFH;IAnEG,6CAA6C;IAC7C,SADW,OAAO,cAAc,EAAE,OAAO,CACnB;IACtB,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;IA2B9B;;;;;;OAMG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;OAOG;IACH,oBAFU,MAAM,CAEsB;IAS1C;;;;;;;;OAQG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CA+BlB;IAED;;;;;;;;OAQG;IACH,oBAJW,YAAY,gBACZ,MAAM,QAwChB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAMC;;CAsCJ;mBA5UkB,uCAAuC;6BAD7B,sCAAsC"}

package/src/engine/network/transport/ReliableCommandPipeline.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
+import { MalformedPacketError } from "../core/MalformedPacketError.js";
 import { MAX_CHANNEL_PAYLOAD_BYTES } from "./fragments/packet_size.js";
 
 /**
@@ -236,8 +237,27 @@ export class ReliableCommandPipeline {
      *                                  including the consumed packet-type byte
      */
     handle_inbound(buf, total_length) {
+        // Bounds-checked before the read, like every other parse path in the dispatcher.
+        //
+        // `#recv_buffer` is a reused scratch: `writeBytes(bytes, 0, length)` overwrites only the
+        // first `length` bytes, so everything past them is the previous, longer packet's content.
+        // A truncated RELIABLE_COMMAND - just the type byte, from a peer or a truncating middlebox
+        // - let `readUintVar` walk into those leftovers and produce a bogus `logical_seq`, which
+        // was then recorded in the received set, so a genuine later command carrying that seq was
+        // silently dropped as a duplicate.
+        if (buf.position >= total_length) {
+            throw new MalformedPacketError(`ReliableCommandPipeline: RELIABLE_COMMAND truncated before its sequence number`);
+        }
+
         const logical_seq = buf.readUintVar();
 
+        // ...and after it: `readUintVar` may have consumed bytes past the packet even when one was
+        // available to start with. Subtracting gave a negative payload length and an offset into an
+        // unrelated packet's bytes, handed straight to the application.
+        if (buf.position > total_length) {
+            throw new MalformedPacketError(`ReliableCommandPipeline: RELIABLE_COMMAND sequence number runs past the packet`);
+        }
+
         if (this.#received_seqs.has(logical_seq)) {
             // Duplicate from a retransmit; ignore.
             return;

package/src/engine/network/transport/adapters/NodeUDPTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeUDPTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/NodeUDPTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IAOI;;;;;;OAMG;IACH,kDANW;QACV,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5C,EAuDH;IAhDG,0CAA0C;IAC1C,YAAkC;IAiDtC;;;;OAIG;IACH,oBAHW,MAAM,QACN,MAAM,QAMhB;IAED;;;;OAIG;IACH,qBAFa;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAQhD;IAkBD;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CA0BzB;;CA0BJ;0BAvLyB,iBAAiB"}
+{"version":3,"file":"NodeUDPTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/NodeUDPTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IAOI;;;;;;OAMG;IACH,kDANW;QACV,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5C,EAuDH;IAhDG,0CAA0C;IAC1C,YAAkC;IAiDtC;;;;OAIG;IACH,oBAHW,MAAM,QACN,MAAM,QAMhB;IAED;;;;OAIG;IACH,qBAFa;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAQhD;IA2BD;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CA0BzB;;CA0BJ;0BAhMyB,iBAAiB"}

package/src/engine/network/transport/adapters/NodeUDPTransport.js

@@ -121,8 +121,17 @@ export class NodeUDPTransport extends Transport {
             throw new Error("NodeUDPTransport.send: no remote set; pass `remote` to constructor or call set_remote()");
         }
         if (length === 0) return;
-        // dgram.send accepts a typed array; subarray to bound the length.
-        const payload = (length === bytes.byteLength) ? bytes : bytes.subarray(0, length);
+        // A COPY, not a subarray view.
+        //
+        // `Channel.send` hands over its long-lived reusable send buffer, and `dgram.send` is
+        // asynchronous - it documents that the buffer must not be modified before completion. With
+        // `max_packets_per_tick` above 1, `flush_outbound` calls `Channel.send` several times in a
+        // row, each rewriting that buffer from offset 0, so a queued view for one slice read the
+        // next slice's header and payload: the receiver saw a packet whose seq and frame range
+        // belonged to a different slice, accepted as well-formed and applied at the wrong frame.
+        // Invisible to the suite, which runs on Loopback/Simulated - both of which copy.
+        const payload = bytes.slice(0, length);
+
         this.socket.send(payload, this.#remote.port, this.#remote.address);
         this.count_out(length);
     }

package/src/engine/network/transport/adapters/WebTransportTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebTransportTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/WebTransportTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAkBI;;OAEG;IACH,mCAFW;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAmCzD;IA3BG;;;;;OAKG;IACH,IAFU,MAAM,CAEgD;IAKhE;;;;;;;;;;;;;;OAcG;IACH,eAFU,MAAM,CAEiB;IAGrC;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CASzB;;CA4FJ;0BAhMyB,iBAAiB;mBADxB,0CAA0C"}
+{"version":3,"file":"WebTransportTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/WebTransportTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAkBI;;OAEG;IACH,mCAFW;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,EAmCzD;IA3BG;;;;;OAKG;IACH,IAFU,MAAM,CAEgD;IAKhE;;;;;;;;;;;;;;OAcG;IACH,eAFU,MAAM,CAEiB;IAGrC;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CASzB;;CAmGJ;0BAvMyB,iBAAiB;mBADxB,0CAA0C"}

package/src/engine/network/transport/adapters/WebTransportTransport.js

@@ -114,7 +114,14 @@ export class WebTransportTransport extends Transport {
             // gate sends on the `connect()` promise.
             return;
         }
-        const payload = (length === bytes.byteLength) ? bytes : bytes.subarray(0, length);
+        // A COPY, not a subarray view. `Channel.send` hands over its long-lived reusable send
+        // buffer and `write()` resolves later; the implementation is free to retain or transfer
+        // the chunk. With `max_packets_per_tick` above 1, `flush_outbound` calls `Channel.send`
+        // several times in a row, each rewriting that buffer from offset 0, so under any
+        // backpressure a queued view would carry a later slice's bytes under an earlier slice's
+        // seq. See the same note in NodeUDPTransport, where this is reproducible directly.
+        const payload = bytes.slice(0, length);
+
         // Fire-and-forget at the call site, but distinguish two
         // rejection sources: backpressure / writer-queue-full (transient,
         // recoverable) vs. the transport actually closing (terminal —

package/src/engine/network/transport/fragments/FragmentAssembler.d.ts

@@ -82,7 +82,8 @@ export class FragmentAssembler {
      * is one tick, negligible vs. the 100 ms initial delay).
      *
      * `on_nack` is invoked once per eligible message with
-     * `(message_id, indices, count)`. The `indices` argument is a
+     * `(message_id, indices, count)`: the missing chunks in index order, but
+     * never more of them than the message has delivered. The `indices` argument is a
      * reused internal Uint8Array; only `indices[0..count)` is valid
      * and only for the duration of the call.
      *

package/src/engine/network/transport/fragments/FragmentAssembler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FragmentAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/FragmentAssembler.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAmBI;;;;;;;;;;;;;;OAcG;IACH,2HAdW;QACV,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,gBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,qBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,uBAA2B,CAAC,EAAE,MAAM,CAAC;QACrC,eAAmB,CAAC,EAAE,MAAM,CAAC;KAC1B,EAwDH;IAnCG,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD,+BAA+B;IAC/B,2BADW,MAAM,CACuB;IACxC,+BAA+B;IAC/B,gCADW,MAAM,CACiC;IAClD,+BAA+B;IAC/B,kCADW,MAAM,CACqC;IACtD,+BAA+B;IAC/B,0BADW,MAAM,CACqB;IA4B1C;;;;;;;;;;;OAWG;IACH,oBARW,MAAM,eACN,MAAM,gBACN,MAAM,eACN,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,UAAU,GAAC,IAAI,CAwE3B;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAHW,MAAM,kBACG,MAAM,QAAE,UAAU,QAAE,MAAM,KAAG,IAAI,QA0CpD;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;OAEG;IACH,cAGC;;CAQJ"}
+{"version":3,"file":"FragmentAssembler.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/FragmentAssembler.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAmCI;;;;;;;;;;;;;;OAcG;IACH,2HAdW;QACV,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,gBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,qBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,uBAA2B,CAAC,EAAE,MAAM,CAAC;QACrC,eAAmB,CAAC,EAAE,MAAM,CAAC;KAC1B,EAwDH;IAnCG,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD,+BAA+B;IAC/B,2BADW,MAAM,CACuB;IACxC,+BAA+B;IAC/B,gCADW,MAAM,CACiC;IAClD,+BAA+B;IAC/B,kCADW,MAAM,CACqC;IACtD,+BAA+B;IAC/B,0BADW,MAAM,CACqB;IA4B1C;;;;;;;;;;;OAWG;IACH,oBARW,MAAM,eACN,MAAM,gBACN,MAAM,eACN,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,UAAU,GAAC,IAAI,CAuF3B;IA0BD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAHW,MAAM,kBACG,MAAM,QAAE,UAAU,QAAE,MAAM,KAAG,IAAI,QA+CpD;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;OAEG;IACH,cAMC;;CAQJ"}

package/src/engine/network/transport/fragments/FragmentAssembler.js

@@ -41,6 +41,22 @@ export class FragmentAssembler {
      * @private
      */
     #order = [];
+
+    /**
+     * Message ids delivered recently, so a late or retransmitted chunk for one is dropped rather
+     * than opening a fresh reassembly slot. See the note in {@link receive}.
+     *
+     * Bounded by {@link #completed_order}, which spans the same window `#order` does.
+     *
+     * @type {Set<number>}
+     */
+    #completed = new Set();
+
+    /**
+     * Insertion order of {@link #completed}, for FIFO eviction.
+     * @type {number[]}
+     */
+    #completed_order = [];
     #nack_scratch;
     /**
      * Scratch for message_ids to drop after a {@link service} pass.
@@ -140,6 +156,18 @@ export class FragmentAssembler {
             return null;
         }
 
+        if (this.#completed.has(message_id)) {
+            // Already delivered. Without this the chunk misses the duplicate guard below - which
+            // lives INSIDE an entry, and completion erases the entry - and opens a fresh, and
+            // therefore incomplete, reassembly slot. `service()` then NACKs the sender for chunks
+            // of a message it has already delivered, the sender's retention honours the NACK, and
+            // the message completes and is dispatched a second time: STATE_BURST straight to the
+            // application handler, INITIAL_SYNC re-applying a whole snapshot. It is the ordinary
+            // NACK/late-chunk race, not an adversarial input - `packet_size.js` sizes the delay
+            // expecting the receiver to "occasionally NACK chunks still in transit".
+            return null;
+        }
+
         let entry = this.#pending.get(message_id);
         if (entry === undefined) {
             if (this.#pending.size >= this.max_pending_messages) {
@@ -197,9 +225,36 @@ export class FragmentAssembler {
             offset += c.length;
         }
         this.#delete(message_id);
+
+        this.#remember_completed(message_id);
+
         return reassembled;
     }
 
+    /**
+     * Record a delivered message id, evicting the oldest when the window is full.
+     *
+     * The window is the same size as the pending one: a chunk arriving later than that many
+     * distinct messages after its own completed is beyond anything the retransmit machinery
+     * would still be holding.
+     *
+     * @param {number} message_id
+     */
+    #remember_completed(message_id) {
+        if (this.#completed.has(message_id)) {
+            return;
+        }
+
+        this.#completed.add(message_id);
+        this.#completed_order.push(message_id);
+
+        while (this.#completed_order.length > this.max_pending_messages) {
+            const oldest = this.#completed_order.shift();
+
+            this.#completed.delete(oldest);
+        }
+    }
+
     /**
      * Per-tick maintenance: drive NACK emission for pending messages
      * whose initial delay has elapsed and whose resend interval has
@@ -212,7 +267,8 @@ export class FragmentAssembler {
      * is one tick, negligible vs. the 100 ms initial delay).
      *
      * `on_nack` is invoked once per eligible message with
-     * `(message_id, indices, count)`. The `indices` argument is a
+     * `(message_id, indices, count)`: the missing chunks in index order, but
+     * never more of them than the message has delivered. The `indices` argument is a
      * reused internal Uint8Array; only `indices[0..count)` is valid
      * and only for the duration of the call.
      *
@@ -235,9 +291,14 @@ export class FragmentAssembler {
             if (entry.last_nack_at >= 0
                 && now_ms - entry.last_nack_at < this.nack_resend_interval_ms) continue;
 
-            // Build the missing-chunk list.
+            // Build the missing-chunk list, no longer than the chunks the
+            // message has delivered. `total_chunks` is the sender's claim, so
+            // it cannot bound the list by itself: one empty fragment claiming
+            // 255 chunks drew a NACK of the other 254 each round, some fifty
+            // times its own size. A message that has lost more than it has
+            // delivered is asked for the rest over the following rounds.
             let missing_count = 0;
-            for (let i = 0; i < entry.total_chunks; i++) {
+            for (let i = 0; i < entry.total_chunks && missing_count < entry.received_count; i++) {
                 if (entry.chunks[i] === undefined) {
                     this.#nack_scratch[missing_count++] = i;
                 }
@@ -275,6 +336,9 @@ export class FragmentAssembler {
     clear() {
         this.#pending.clear();
         this.#order.length = 0;
+
+        this.#completed.clear();
+        this.#completed_order.length = 0;
     }
 
     /** @private */

package/src/engine/network/transport/fragments/fragment_send.d.ts

@@ -31,6 +31,14 @@
  *   N sends for fragmented case
  */
 export function send_fragmented(payload: Uint8Array, payload_length: number, message_id: number, fragment_packet_type: number, scratch: Uint8Array, send_fn: (arg0: Uint8Array, arg1: number) => void): void;
+/**
+ * Number of chunks {@link send_fragmented} splits a payload of `payload_length` bytes into — the
+ * chunk indices a receiver may ask to have re-sent are `[0, count)`.
+ *
+ * @param {number} payload_length
+ * @returns {number}
+ */
+export function fragment_chunk_count(payload_length: number): number;
 /**
  * Re-emit a single fragment chunk for a previously-sent fragmented
  * message. Used by the NACK retransmit path: the sender's

package/src/engine/network/transport/fragments/fragment_send.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fragment_send.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/fragment_send.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCATW,UAAU,kBACV,MAAM,cACN,MAAM,wBACN,MAAM,WACN,UAAU,kBACD,UAAU,QAAE,MAAM,KAAG,IAAI,QAkD5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,+CARW,UAAU,kBACV,MAAM,cACN,MAAM,eACN,MAAM,wBACN,MAAM,WACN,UAAU,kBACD,UAAU,QAAE,MAAM,KAAG,IAAI,QA0C5C"}
+{"version":3,"file":"fragment_send.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/fragment_send.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,yCATW,UAAU,kBACV,MAAM,cACN,MAAM,wBACN,MAAM,WACN,UAAU,kBACD,UAAU,QAAE,MAAM,KAAG,IAAI,QAkD5C;AAED;;;;;;GAMG;AACH,qDAHW,MAAM,GACJ,MAAM,CAQlB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,+CARW,UAAU,kBACV,MAAM,cACN,MAAM,eACN,MAAM,wBACN,MAAM,WACN,UAAU,kBACD,UAAU,QAAE,MAAM,KAAG,IAAI,QAqC5C"}

package/src/engine/network/transport/fragments/fragment_send.js

@@ -86,6 +86,21 @@ export function send_fragmented(
     }
 }
 
+/**
+ * Number of chunks {@link send_fragmented} splits a payload of `payload_length` bytes into — the
+ * chunk indices a receiver may ask to have re-sent are `[0, count)`.
+ *
+ * @param {number} payload_length
+ * @returns {number}
+ */
+export function fragment_chunk_count(payload_length) {
+    // Payloads short enough to not fragment in the first place are never
+    // retained, so the 1 is defensive consistency rather than a real case.
+    return payload_length <= MAX_FRAGMENT_CHUNK_BYTES
+        ? 1
+        : Math.ceil(payload_length / MAX_FRAGMENT_CHUNK_BYTES);
+}
+
 /**
  * Re-emit a single fragment chunk for a previously-sent fragmented
  * message. Used by the NACK retransmit path: the sender's
@@ -120,13 +135,8 @@ export function resend_fragment_chunk(
     assert.ok(scratch.length >= MAX_CHANNEL_PAYLOAD_BYTES,
         'scratch buffer must be at least MAX_CHANNEL_PAYLOAD_BYTES');
 
-    // Recover total_chunks from the retained payload length. Same formula
-    // as send_fragmented; payloads short enough to not fragment in the
-    // first place would never have been retained, so we still take the
-    // ceil here as defensive consistency.
-    const total_chunks = payload_length <= MAX_FRAGMENT_CHUNK_BYTES
-        ? 1
-        : Math.ceil(payload_length / MAX_FRAGMENT_CHUNK_BYTES);
+    // Recover total_chunks from the retained payload length.
+    const total_chunks = fragment_chunk_count(payload_length);
     if (chunk_index >= total_chunks) return;
 
     const chunk_offset = chunk_index * MAX_FRAGMENT_CHUNK_BYTES;

package/src/engine/network/transport/fragments/packet_size.d.ts

@@ -86,6 +86,12 @@ export const FRAGMENT_NACK_MAX_ROUNDS: 3;
  * max_message_size` bytes. With the FragmentAssembler default of 64 KiB,
  * that's 1 MiB per peer at saturation; steady-state retention is empty
  * because steady traffic fits in one packet and bypasses fragmentation.
+ *
+ * `FRAGMENT_RETENTION_MAX_RETRIES` is how many NACKs a retained message is
+ * repaired for. A NACK re-sends each chunk of the message at most once, so
+ * whatever a peer asks, repair costs at most this many copies of a message
+ * the sender chose to send. It matches the receiver's
+ * `FRAGMENT_NACK_MAX_ROUNDS`: an honest receiver never asks more often.
  */
 export const FRAGMENT_RETENTION_MAX_AGE_MS: 1500;
 export const FRAGMENT_RETENTION_MAX_MESSAGES: 16;

package/src/engine/network/transport/fragments/packet_size.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packet_size.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/packet_size.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,4BAA4B;AAC5B,6BAA8B;AAE9B,wFAAwF;AACxF,qCAAsC;AAEtC;;;GAGG;AACH,+CAA0E;AAE1E;;;;;;GAMG;AACH,sCAAuC;AAEvC,2DAA2D;AAC3D,8CAA0F;AAE1F,4FAA4F;AAC5F,yCAA0C;AAE1C,+EAA+E;AAC/E,+CAA2F;AAE3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gDAAiD;AACjD,kDAAmD;AACnD,yCAA0C;AAE1C;;;;;;;;;;GAUG;AACH,iDAAkD;AAClD,iDAAkD;AAClD,+CAAgD"}
+{"version":3,"file":"packet_size.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/packet_size.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,4BAA4B;AAC5B,6BAA8B;AAE9B,wFAAwF;AACxF,qCAAsC;AAEtC;;;GAGG;AACH,+CAA0E;AAE1E;;;;;;GAMG;AACH,sCAAuC;AAEvC,2DAA2D;AAC3D,8CAA0F;AAE1F,4FAA4F;AAC5F,yCAA0C;AAE1C,+EAA+E;AAC/E,+CAA2F;AAE3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gDAAiD;AACjD,kDAAmD;AACnD,yCAA0C;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,iDAAkD;AAClD,iDAAkD;AAClD,+CAAgD"}

package/src/engine/network/transport/fragments/packet_size.js

@@ -95,6 +95,12 @@ export const FRAGMENT_NACK_MAX_ROUNDS = 3;
  * max_message_size` bytes. With the FragmentAssembler default of 64 KiB,
  * that's 1 MiB per peer at saturation; steady-state retention is empty
  * because steady traffic fits in one packet and bypasses fragmentation.
+ *
+ * `FRAGMENT_RETENTION_MAX_RETRIES` is how many NACKs a retained message is
+ * repaired for. A NACK re-sends each chunk of the message at most once, so
+ * whatever a peer asks, repair costs at most this many copies of a message
+ * the sender chose to send. It matches the receiver's
+ * `FRAGMENT_NACK_MAX_ROUNDS`: an honest receiver never asks more often.
  */
 export const FRAGMENT_RETENTION_MAX_AGE_MS = 1500;
 export const FRAGMENT_RETENTION_MAX_MESSAGES = 16;

package/src/engine/physics/ccd/linear_sweep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"linear_sweep.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ccd/linear_sweep.js"],"names":[],"mappings":"AA+JA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAhBW,OAAO,yBAAyB,EAAE,aAAa,SAC/C,OAAO,gDAAgD,EAAE,eAAe,YACxE,UAAU,MAAM,CAAC,MAGjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,kBACN,MAAM,UAEN,mBAAmB,GACjB,MAAM,CA2ClB;AA2ID;;;;;;;;;;;;GAYG;AACH,6CAFW,OAAO,yBAAyB,EAAE,aAAa,QAezD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oCAFW,OAAO,yBAAyB,EAAE,aAAa,QAsHzD;AA5gBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qCAFU,MAAM,CAE2B;oCArDP,mCAAmC"}
+{"version":3,"file":"linear_sweep.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ccd/linear_sweep.js"],"names":[],"mappings":"AA+JA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,0CAhBW,OAAO,yBAAyB,EAAE,aAAa,SAC/C,OAAO,gDAAgD,EAAE,eAAe,YACxE,UAAU,MAAM,CAAC,MAGjB,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,kBACN,MAAM,UAEN,mBAAmB,GACjB,MAAM,CA2ClB;AA2ID;;;;;;;;;;;;GAYG;AACH,6CAFW,OAAO,yBAAyB,EAAE,aAAa,QAezD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,oCAFW,OAAO,yBAAyB,EAAE,aAAa,QAwIzD;AA9hBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,qCAFU,MAAM,CAE2B;oCArDP,mCAAmC"}

package/src/engine/physics/ccd/linear_sweep.js

@@ -506,10 +506,28 @@ export function ccd_resolve(system) {
 
         // Clamp the body to the first-contact pose (swept-shape centre at the
         // TOI), so it cannot end the step on the far side of the blocker.
+        //
+        // The sweep is of the primary COLLIDER, whose transform is the body's
+        // own only for a same-entity collider. The clamp has to land on the
+        // body — that is what integration moved and what the velocity fix
+        // below applies to — so a child collider's transform is displaced by
+        // the same delta rather than being assigned the swept centre, which
+        // would move the child out from under the body it belongs to.
         const hp = _hit.position;
-        p[0] = hp[0];
+        const body_tr = system.__transforms[idx];
+        if (body_tr === tr) {
+            p[0] = hp[0];
             p[1] = hp[1];
             p[2] = hp[2];
+        } else {
+            const bp = body_tr.translation;
+            bp[0] += hp[0] - ex;
+            bp[1] += hp[1] - ey;
+            bp[2] += hp[2] - ez;
+            p[0] = hp[0];
+            p[1] = hp[1];
+            p[2] = hp[2];
+        }
 
         // Remove the inbound normal component of velocity (inelastic stop).
         // `_hit.normal` is the blocker's outward surface normal; the body is

package/src/engine/physics/cloth/ecs/ClothWorld.d.ts

@@ -206,9 +206,13 @@ export class ClothWorld {
      * for a character spawned whole, which is the one case a spec constructs and
      * the least likely one in a scene where a model loads asynchronously.
      *
-     * Both edges re-seed. The removing edge also gives the joints back first,
-     * because the instance that knows which they were is about to stop being a
-     * rig.
+     * Both edges re-seed, and both give back first, because the instance that
+     * knows what the seeding took is about to stop describing it. On the
+     * removing edge that is the joints; on the adding edge it is a whole
+     * transform subtree, whose authored locals `cloth_write_back` has been
+     * overwriting every step and which exist nowhere else — once the rig path
+     * has seeded over them, `#release` dispatches on a rig and can never give
+     * them back.
      * @type {EntityObserver}
      * @private
      */

package/src/engine/physics/cloth/ecs/ClothWorld.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;OAgBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IA+CD;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAanC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CAgPnB;;CA8EJ;8BAn9B6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}
+{"version":3,"file":"ClothWorld.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/physics/cloth/ecs/ClothWorld.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiFG;AACH;IAEI;;;OAGG;IACH,SAFU,YAAY,CAEoB;IAE1C;;;;;;;;;;;;OAYG;IACH,WAFU,aAAa,EAAE,CAEV;IAEf;;;;;;;;;;;;;;;OAeG;IACH,QAFU;QAAC,WAAW,SAAW,MAAM,KAAG,CAAC,iBAAe,IAAI,CAAC,CAAA;KAAC,GAAC,IAAI,CAEvD;IAEd;;OAEG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;OAEG;IACH,aAFU,yBAAyB,GAAC,IAAI,CAErB;IAEnB;;;;;;OAMG;IACH,WAFU,mBAAmB,GAAC,IAAI,CAEjB;IAEjB;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAFU,oBAAkB,IAAI,CAEpB;IAEZ;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,uBAAmB;IAEnB;;;;;OAKG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,oBAAwB;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uBAKE;IAEF;;;;;OAKG;IACH,2CAiBC;IAED;;;;;OAKG;IACH,YALW,KAAK,kCAEL,MAAM,GACJ,aAAa,CAczB;IAED;;;;;;;;OAQG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,iDAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CA0BnC;IAyED;;;;;;;;;;;OAWG;IACH,eAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAanC;IAED;;;;;;;OAOG;IACH,aAHW,MAAM,GACJ,IAAI,CAShB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,aAAa,GAAC,SAAS,CAInC;IAED;;;;;OAKG;IACH,uCAFW,MAAM,QAgBhB;IAED;;;;;;;;;OASG;IACH,wBANW,aAAa,mCAEb,MAAM,GACJ,OAAO,CA8BnB;IAED;;;;;;;OAOG;IACH,iBAJW,aAAa,gCAEX,IAAI,CA4ChB;IAwFD;;;;;;;;;;;OAWG;IACH,kBAPW,aAAa,MACb,MAAM,UACN,YAAY,UACZ,MAAM,GACJ,OAAO,CAgPnB;;CA8EJ;8BAj/B6B,oBAAoB;0CAjB3C,gEAAgE;oCAcnC,0BAA0B;sBA4BxC,YAAY"}

package/src/engine/physics/cloth/ecs/ClothWorld.js

@@ -275,15 +275,19 @@ export class ClothWorld {
      * for a character spawned whole, which is the one case a spec constructs and
      * the least likely one in a scene where a model loads asynchronously.
      *
-     * Both edges re-seed. The removing edge also gives the joints back first,
-     * because the instance that knows which they were is about to stop being a
-     * rig.
+     * Both edges re-seed, and both give back first, because the instance that
+     * knows what the seeding took is about to stop describing it. On the
+     * removing edge that is the joints; on the adding edge it is a whole
+     * transform subtree, whose authored locals `cloth_write_back` has been
+     * overwriting every step and which exist nowhere else — once the rig path
+     * has seeded over them, `#release` dispatches on a rig and can never give
+     * them back.
      * @type {EntityObserver}
      * @private
      */
     __rig_observer = new EntityObserver(
         [Cloth, ClothRig],
-        (cloth, rig, entity) => this.reseed(entity),
+        (cloth, rig, entity) => this.#rig_added(entity),
         (cloth, rig, entity) => this.#rig_removed(entity),
         this
     );
@@ -408,6 +412,32 @@ export class ClothWorld {
         }
     }
 
+    /**
+     * A {@link ClothRig} has arrived at a live cloth: give back whatever the
+     * cloth had already seeded over — a transform subtree, since the instance
+     * cannot have been a rig yet — then re-seed, which with a rig is the rig
+     * path.
+     *
+     * The release has to happen here rather than inside the re-seed: by the
+     * time `#seed` runs, `cloth_seed_rig` has replaced the captured rest locals
+     * with the proxy's bind pose, and the subtree's authored pose — which
+     * `cloth_write_back` overwrote on the hierarchy itself — is gone for good.
+     *
+     * @param {number} entity
+     * @private
+     */
+    #rig_added(entity) {
+        const instance = this.__by_entity.get(entity);
+
+        if (instance === undefined) {
+            return;
+        }
+
+        this.#release(instance);
+
+        this.reseed(entity);
+    }
+
     /**
      * A {@link ClothRig} has left a live cloth: give its joints back, then
      * re-seed, which without a rig is the entity path.