@woosh/meep-engine 2.156.0 → 2.157.0

package/src/engine/physics/contact/ManifoldStore.d.ts

@@ -52,7 +52,11 @@ export const SLOT_DATA_STRIDE: number;
  */
 export const MANIFOLD_SLOT_ABSENT: number;
 /**
- * Persistent contact-manifold cache keyed by canonical body-id pairs.
+ * Persistent contact-manifold cache keyed by canonical body-id pairs —
+ * canonical meaning ENTITY order: the broadphase assigns the pair's A role
+ * to the body with the smaller entity id (see generate_pairs), so the A/B
+ * roles (witness sides, normal orientation) are identical in every engine
+ * holding the same bodies, regardless of slot-allocation history.
  *
  * Owns:
  *  - the SoA `Float64Array` of contact points (per-slot stride 52),
@@ -86,12 +90,21 @@ export class ManifoldStore {
     __live_slots: Uint32Array;
     __live_pos: Int32Array;
     __live_count: number;
-    __free_heap: Uint32Array;
-    __free_count: number;
+    __free: Uint32MinHeap;
     /**
      * @returns {number} number of currently-live slots
      */
     get count(): number;
+    /**
+     * Drop every live slot: empty pair index, empty live list, all slot ids
+     * back on the free heap, high-water mark reset. Capacity is retained.
+     *
+     * For world reconstruction (remove every body, re-add from a snapshot,
+     * then import the exported contact state into the emptied store) — the
+     * import requires an empty store so slot allocation starts from a known
+     * state.
+     */
+    clear(): void;
     /**
      * @returns {number} total allocated slot capacity
      */
@@ -140,6 +153,47 @@ export class ManifoldStore {
      * @returns {boolean}
      */
     was_touched_prev(slot: number): boolean;
+    /**
+     * Whether the slot ended the PREVIOUS frame with stored contacts — the
+     * event diff's "was in contact" side. See {@link FLAG_HAD_CONTACTS}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    had_contacts_prev(slot: number): boolean;
+    /**
+     * Whether the slot was created by its most recent acquire (and not yet
+     * re-acquired). See {@link FLAG_FRESH}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_fresh(slot: number): boolean;
+    /**
+     * Whether the stage-0 swept-proximity predicate held for this pair when
+     * last evaluated. See {@link FLAG_PROX}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_prox(slot: number): boolean;
+    /**
+     * Record the stage-0 swept-proximity predicate's current value for the
+     * pair. See {@link FLAG_PROX}.
+     * @param {number} slot
+     * @param {boolean} value
+     */
+    set_prox(slot: number, value: boolean): void;
+    /**
+     * Whether the pair is DORMANT: both bodies exist and both are outside the
+     * awake set (sleeping dynamics, statics, anything not simulating). A
+     * dormant pair is frozen — {@link advance_frame} skips its grace/eviction
+     * and the event diff emits nothing for it — so a sleeping stack keeps its
+     * manifolds (contacts + warm-start impulses) and neither fires a spurious
+     * ContactEnd at sleep nor re-fires ContactBegin at wake.
+     *
+     * @param {number} slot
+     * @param {BodyStorage} storage
+     * @returns {boolean}
+     */
+    is_dormant(slot: number, storage: BodyStorage): boolean;
     /**
      * Iterate the dense list of currently-live slots without going through
      * the pair map. `i` ranges `[0, count)`.
@@ -267,6 +321,26 @@ export class ManifoldStore {
      * @returns {Float64Array}
      */
     get data_buffer(): Float64Array;
+    /**
+     * Raw per-slot lifecycle bits — `count | touched | prev_touched | grace |
+     * had_contacts | fresh | prox` — for the contact-state export. The
+     * body-id words are NOT included: they are world-instance state, the
+     * export keys slots by entity pair instead. Pair with
+     * {@link restore_meta_bits}.
+     * @param {number} slot
+     * @returns {number}
+     */
+    meta_bits(slot: number): number;
+    /**
+     * Overwrite a slot's lifecycle bits verbatim — the import half of
+     * {@link meta_bits}. The caller has just {@link acquire}d the slot;
+     * this replaces the acquire-time bits (touched, cleared grace, fresh)
+     * with the exported ones so the restored slot resumes the exact
+     * lifecycle position it was exported in.
+     * @param {number} slot
+     * @param {number} bits
+     */
+    restore_meta_bits(slot: number, bits: number): void;
     /**
      * Word offset into {@link data_buffer} where the first contact of `slot`
      * begins. Subsequent contacts within the slot are at
@@ -276,10 +350,20 @@ export class ManifoldStore {
      */
     slot_data_offset(slot: number): number;
     /**
-     * Advance touched flags by one frame and evict slots that have been
-     * untouched for {@link DEFAULT_GRACE} consecutive frames.
+     * Advance touched / had-contacts flags by one frame and evict slots that
+     * have been untouched for {@link DEFAULT_GRACE} consecutive frames.
+     *
+     * With `storage` provided, DORMANT slots ({@link is_dormant}: both bodies
+     * alive and outside the awake set) are frozen instead of advanced: no
+     * grace bump, no eviction, contacts + warm-start impulses + the
+     * had-contacts flag all preserved. Only the touched flag is cleared, so
+     * the frame the bodies wake, the broadphase re-acquires the pair and the
+     * narrowphase refreshes it immediately. Without `storage` (pure-store
+     * usage) every slot advances unconditionally.
+     *
+     * @param {BodyStorage} [storage] body table for the dormancy test
      */
-    advance_frame(): void;
+    advance_frame(storage?: BodyStorage): void;
     /**
      * @private
      * @returns {number} newly-allocated slot id
@@ -294,16 +378,7 @@ export class ManifoldStore {
      * @private
      */
     private __grow;
-    /**
-     * @private
-     * @param {number} v
-     */
-    private __heap_push;
-    /**
-     * @private
-     * @returns {number}
-     */
-    private __heap_pop;
 }
 import { PairUint32Map } from "../../../core/collection/PairUint32Map.js";
+import { Uint32MinHeap } from "../../../core/collection/Uint32MinHeap.js";
 //# sourceMappingURL=ManifoldStore.d.ts.map

package/src/engine/physics/contact/ManifoldStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wCAFU,MAAM,CAE2B;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,6BAFU,MAAM,CAEiB;AAEjC;;;;GAIG;AACH,wCAFU,MAAM,CAE4B;AAE5C;;;GAGG;AACH,+BAFU,MAAM,CAE2D;AAyB3E;;;GAGG;AACH,mCAFU,MAAM,CAEuB;AAIvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;OAEG;IACH,+BAFW,MAAM,EAqBhB;IAjBG,mBAA+C;IAC/C,qBAAqB;IAErB,qBAAkE;IAClE,oBAAiE;IAEjE,4BAA0D;IAG1D,0BAAoD;IACpD,uBAAiD;IAEjD,qBAAqB;IAGrB,yBAAmD;IACnD,qBAAqB;IAGzB;;OAEG;IACH,oBAEC;IAED;;OAEG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,UAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAKlB;IAED;;;;;;;;OAQG;IACH,aAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAwBlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,YAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;OAGG;IACH,uBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAFW,MAAM,QAQhB;IAED;;;;;;;;;;;;;OAaG;IACH,mBAFW,MAAM,QAKhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,kBAnBW,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,SACN,MAAM,eACN,MAAM,aAGN,MAAM,gBAEN,MAAM,QAwBhB;IAED;;;;;OAKG;IACH,kBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,qBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,MAAM,OACN,MAAM,QAOhB;IAED;;;;;OAKG;IACH,oBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,kBALW,MAAM,OACN,MAAM,OACN,MAAM,EAAE,GAAC,YAAY,cACrB,MAAM,QAOhB;IAED;;;;;;OAMG;IACH,uBAJW,MAAM,OACN,MAAM,GACJ,MAAM,CAIlB;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,uBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED,iEAAiE;IACjE,oBADY,MAAM,OAAe,MAAM,GAAgB,MAAM,CAG5D;IAED;;;;;OAKG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,uBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,sBA6BC;IAED;;;OAGG;IACH,wBAcC;IAED;;;OAGG;IACH,uBAkBC;IAED;;OAEG;IACH,eA8BC;IAED;;;OAGG;IACH,oBAaC;IAED;;;OAGG;IACH,mBAqBC;CACJ;8BA3lBqD,2CAA2C"}
+{"version":3,"file":"ManifoldStore.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/contact/ManifoldStore.js"],"names":[],"mappings":"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"}

package/src/engine/physics/contact/ManifoldStore.js

@@ -1,5 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { PAIR_UINT32_MAP_ABSENT, PairUint32Map } from "../../../core/collection/PairUint32Map.js";
+import { Uint32MinHeap } from "../../../core/collection/Uint32MinHeap.js";
+import { body_id_index } from "../body/BodyStorage.js";
 
 /**
  * Maximum contact points per manifold. Four is the universal industry choice
@@ -57,7 +59,8 @@ export const SLOT_DATA_STRIDE = CONTACT_STRIDE * MAX_CONTACTS_PER_MANIFOLD;
  * Per-slot meta stride in the Uint32 meta buffer:
  *   0 : bodyA
  *   1 : bodyB
- *   2 : packed = count(0..3) | touched(bit 4) | prev_touched(bit 5) | grace(bits 6..13)
+ *   2 : packed = count(0..3) | touched(bit 4) | prev_touched(bit 5) |
+ *       grace(bits 6..13) | had_contacts(bit 14)
  * @type {number}
  */
 const SLOT_META_STRIDE = 3;
@@ -68,6 +71,47 @@ const COUNT_MASK = 0x0F;
 const GRACE_SHIFT = 6;
 const GRACE_MASK = 0xFF; // 8 bits
 
+/**
+ * "The previous frame ended with stored contacts." Rolled from
+ * `contact_count > 0` by {@link advance_frame}; read by the event diff so
+ * Begin/Stay/End track CONTACT transitions, not broadphase proximity (the
+ * touched flag is fat-AABB overlap — up to ~10 cm of separation at rest).
+ * Preserved while a pair is dormant (both bodies asleep), so waking resumes
+ * with Stay rather than re-firing Begin.
+ * @type {number}
+ */
+const FLAG_HAD_CONTACTS = 1 << 14;
+
+/**
+ * "This slot was allocated by the most recent acquire of this pair" — set
+ * when {@link acquire} creates the slot, cleared by the pair's next acquire
+ * (i.e. the following frame's broadphase).
+ *
+ * History: this used to be the precautionary-wake trigger ("a brand-new
+ * pair means something arrived near a sleeper"). It no longer is — pair
+ * CREATION time depends on broadphase fat-box history (when leaves were
+ * last refit), which two engines holding identical body state need not
+ * share, so a creation-keyed wake breaks reconstruction determinism. The
+ * wake stage now uses the state-derived swept-proximity edge
+ * ({@link FLAG_PROX}); FRESH remains as a query for diagnostics and tests.
+ * @type {number}
+ */
+const FLAG_FRESH = 1 << 15;
+
+/**
+ * "The stage-0 swept-proximity predicate held when this pair was last
+ * evaluated" — the memory bit of the EDGE-triggered pre-contact wake
+ * (PhysicsSystem.__wake_pairs): a sleeper is woken when the predicate
+ * (mover's velocity-swept tight AABB overlaps the sleeper's tight AABB —
+ * pure body state) turns false→true, not while it merely holds, so a
+ * mover hovering inside the window doesn't re-wake the sleeper every
+ * frame. Cleared on slot allocation, preserved across re-acquire,
+ * exported/imported with the contact state so a reconstructed engine
+ * resumes with the same edge memory.
+ * @type {number}
+ */
+const FLAG_PROX = 1 << 16;
+
 /**
  * Number of consecutive frames a manifold may stay untouched before eviction.
  * Two frames of grace lets a one-frame separation survive (jitter friendly)
@@ -85,7 +129,11 @@ export const MANIFOLD_SLOT_ABSENT = -1;
 const DEFAULT_INITIAL_CAPACITY = 64;
 
 /**
- * Persistent contact-manifold cache keyed by canonical body-id pairs.
+ * Persistent contact-manifold cache keyed by canonical body-id pairs —
+ * canonical meaning ENTITY order: the broadphase assigns the pair's A role
+ * to the body with the smaller entity id (see generate_pairs), so the A/B
+ * roles (witness sides, normal orientation) are identical in every engine
+ * holding the same bodies, regardless of slot-allocation history.
  *
  * Owns:
  *  - the SoA `Float64Array` of contact points (per-slot stride 52),
@@ -127,9 +175,9 @@ export class ManifoldStore {
         this.__live_pos.fill(-1);
         this.__live_count = 0;
 
-        // Min-heap of released slot ids.
-        this.__free_heap = new Uint32Array(this.__capacity);
-        this.__free_count = 0;
+        // Min-heap of released slot ids — reuse is deterministic
+        // (lowest released slot first). Self-growing.
+        this.__free = new Uint32MinHeap(this.__capacity);
     }
 
     /**
@@ -139,6 +187,23 @@ export class ManifoldStore {
         return this.__live_count;
     }
 
+    /**
+     * Drop every live slot: empty pair index, empty live list, all slot ids
+     * back on the free heap, high-water mark reset. Capacity is retained.
+     *
+     * For world reconstruction (remove every body, re-add from a snapshot,
+     * then import the exported contact state into the emptied store) — the
+     * import requires an empty store so slot allocation starts from a known
+     * state.
+     */
+    clear() {
+        this.__pair_index.clear();
+        this.__live_pos.fill(-1);
+        this.__live_count = 0;
+        this.__free.clear();
+        this.__high_water = 0;
+    }
+
     /**
      * @returns {number} total allocated slot capacity
      */
@@ -170,6 +235,7 @@ export class ManifoldStore {
      */
     acquire(idA, idB) {
         let slot = this.find(idA, idB);
+        let fresh;
         if (slot === MANIFOLD_SLOT_ABSENT) {
             slot = this.__allocate_slot();
             const meta_off = slot * SLOT_META_STRIDE;
@@ -182,11 +248,15 @@ export class ManifoldStore {
             this.__data.fill(0, data_off, data_off + SLOT_DATA_STRIDE);
 
             this.__pair_index.set(idA, idB, slot);
+            fresh = FLAG_FRESH;
+        } else {
+            fresh = 0; // a re-acquire ends the slot's "just created" window
         }
         const meta_off = slot * SLOT_META_STRIDE;
-        // Set touched bit, clear grace.
+        // Set touched bit, set/clear fresh, clear grace.
         let packed = this.__meta[meta_off + 2];
         packed |= FLAG_TOUCHED;
+        packed = (packed & ~FLAG_FRESH) | fresh;
         packed &= ~(GRACE_MASK << GRACE_SHIFT);
         this.__meta[meta_off + 2] = packed;
         return slot;
@@ -232,6 +302,73 @@ export class ManifoldStore {
         return (this.__meta[slot * SLOT_META_STRIDE + 2] & FLAG_PREV_TOUCHED) !== 0;
     }
 
+    /**
+     * Whether the slot ended the PREVIOUS frame with stored contacts — the
+     * event diff's "was in contact" side. See {@link FLAG_HAD_CONTACTS}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    had_contacts_prev(slot) {
+        return (this.__meta[slot * SLOT_META_STRIDE + 2] & FLAG_HAD_CONTACTS) !== 0;
+    }
+
+    /**
+     * Whether the slot was created by its most recent acquire (and not yet
+     * re-acquired). See {@link FLAG_FRESH}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_fresh(slot) {
+        return (this.__meta[slot * SLOT_META_STRIDE + 2] & FLAG_FRESH) !== 0;
+    }
+
+    /**
+     * Whether the stage-0 swept-proximity predicate held for this pair when
+     * last evaluated. See {@link FLAG_PROX}.
+     * @param {number} slot
+     * @returns {boolean}
+     */
+    is_prox(slot) {
+        return (this.__meta[slot * SLOT_META_STRIDE + 2] & FLAG_PROX) !== 0;
+    }
+
+    /**
+     * Record the stage-0 swept-proximity predicate's current value for the
+     * pair. See {@link FLAG_PROX}.
+     * @param {number} slot
+     * @param {boolean} value
+     */
+    set_prox(slot, value) {
+        const meta_off = slot * SLOT_META_STRIDE + 2;
+        if (value) {
+            this.__meta[meta_off] |= FLAG_PROX;
+        } else {
+            this.__meta[meta_off] &= ~FLAG_PROX;
+        }
+    }
+
+    /**
+     * Whether the pair is DORMANT: both bodies exist and both are outside the
+     * awake set (sleeping dynamics, statics, anything not simulating). A
+     * dormant pair is frozen — {@link advance_frame} skips its grace/eviction
+     * and the event diff emits nothing for it — so a sleeping stack keeps its
+     * manifolds (contacts + warm-start impulses) and neither fires a spurious
+     * ContactEnd at sleep nor re-fires ContactBegin at wake.
+     *
+     * @param {number} slot
+     * @param {BodyStorage} storage
+     * @returns {boolean}
+     */
+    is_dormant(slot, storage) {
+        const meta_off = slot * SLOT_META_STRIDE;
+        const idA = this.__meta[meta_off];
+        const idB = this.__meta[meta_off + 1];
+        if (!storage.is_valid(idA) || !storage.is_valid(idB)) {
+            return false; // a freed body is gone, not asleep — let the slot lapse
+        }
+        return !storage.is_awake(body_id_index(idA)) && !storage.is_awake(body_id_index(idB));
+    }
+
     /**
      * Iterate the dense list of currently-live slots without going through
      * the pair map. `i` ranges `[0, count)`.
@@ -432,6 +569,32 @@ export class ManifoldStore {
         return this.__data;
     }
 
+    /**
+     * Raw per-slot lifecycle bits — `count | touched | prev_touched | grace |
+     * had_contacts | fresh | prox` — for the contact-state export. The
+     * body-id words are NOT included: they are world-instance state, the
+     * export keys slots by entity pair instead. Pair with
+     * {@link restore_meta_bits}.
+     * @param {number} slot
+     * @returns {number}
+     */
+    meta_bits(slot) {
+        return this.__meta[slot * SLOT_META_STRIDE + 2];
+    }
+
+    /**
+     * Overwrite a slot's lifecycle bits verbatim — the import half of
+     * {@link meta_bits}. The caller has just {@link acquire}d the slot;
+     * this replaces the acquire-time bits (touched, cleared grace, fresh)
+     * with the exported ones so the restored slot resumes the exact
+     * lifecycle position it was exported in.
+     * @param {number} slot
+     * @param {number} bits
+     */
+    restore_meta_bits(slot, bits) {
+        this.__meta[slot * SLOT_META_STRIDE + 2] = bits;
+    }
+
     /**
      * Word offset into {@link data_buffer} where the first contact of `slot`
      * begins. Subsequent contacts within the slot are at
@@ -444,10 +607,20 @@ export class ManifoldStore {
     }
 
     /**
-     * Advance touched flags by one frame and evict slots that have been
-     * untouched for {@link DEFAULT_GRACE} consecutive frames.
+     * Advance touched / had-contacts flags by one frame and evict slots that
+     * have been untouched for {@link DEFAULT_GRACE} consecutive frames.
+     *
+     * With `storage` provided, DORMANT slots ({@link is_dormant}: both bodies
+     * alive and outside the awake set) are frozen instead of advanced: no
+     * grace bump, no eviction, contacts + warm-start impulses + the
+     * had-contacts flag all preserved. Only the touched flag is cleared, so
+     * the frame the bodies wake, the broadphase re-acquires the pair and the
+     * narrowphase refreshes it immediately. Without `storage` (pure-store
+     * usage) every slot advances unconditionally.
+     *
+     * @param {BodyStorage} [storage] body table for the dormancy test
      */
-    advance_frame() {
+    advance_frame(storage = null) {
         // Iterate live slots backwards so swap-with-last during release doesn't
         // skip indices.
         for (let i = this.__live_count - 1; i >= 0; i--) {
@@ -455,11 +628,26 @@ export class ManifoldStore {
             const meta_off = slot * SLOT_META_STRIDE;
             let packed = this.__meta[meta_off + 2];
 
+            if (storage !== null && this.is_dormant(slot, storage)) {
+                // Freeze the sleeping pair. Clearing only `touched` keeps
+                // generate_pairs' dedup from suppressing the pair on the wake
+                // frame; everything else (grace, had_contacts, contact data)
+                // stays exactly as it was when the bodies fell asleep.
+                this.__meta[meta_off + 2] = packed & ~FLAG_TOUCHED;
+                continue;
+            }
+
             const was_touched = (packed & FLAG_TOUCHED) !== 0;
             // Roll touched → prev_touched, clear touched.
             if (was_touched) {
                 packed |= FLAG_PREV_TOUCHED; // single-bit mask: clear-then-set is just set
                 packed &= ~FLAG_TOUCHED;
+                // Roll "ended the frame with contacts" for the event diff.
+                if ((packed & COUNT_MASK) !== 0) {
+                    packed |= FLAG_HAD_CONTACTS;
+                } else {
+                    packed &= ~FLAG_HAD_CONTACTS;
+                }
                 // Reset grace.
                 packed &= ~(GRACE_MASK << GRACE_SHIFT);
                 this.__meta[meta_off + 2] = packed;
@@ -467,6 +655,10 @@ export class ManifoldStore {
                 // Bump grace.
                 const grace = ((packed >>> GRACE_SHIFT) & GRACE_MASK) + 1;
                 packed &= ~FLAG_PREV_TOUCHED;
+                // Proximity lapsed: the stored contacts are stale leftovers
+                // from the last narrowphased frame (the End event for them
+                // fired in this frame's diff).
+                packed &= ~FLAG_HAD_CONTACTS;
                 packed &= ~(GRACE_MASK << GRACE_SHIFT);
                 packed |= (grace & GRACE_MASK) << GRACE_SHIFT;
                 this.__meta[meta_off + 2] = packed;
@@ -484,8 +676,8 @@ export class ManifoldStore {
      */
     __allocate_slot() {
         let slot;
-        if (this.__free_count > 0) {
-            slot = this.__heap_pop();
+        if (this.__free.size > 0) {
+            slot = this.__free.pop();
         } else {
             if (this.__high_water === this.__capacity) {
                 this.__grow();
@@ -519,7 +711,7 @@ export class ManifoldStore {
         }
         this.__live_pos[slot] = -1;
 
-        this.__heap_push(slot);
+        this.__free.push(slot);
     }
 
     /**
@@ -552,54 +744,6 @@ export class ManifoldStore {
         next_live_pos.fill(-1, this.__live_pos.length);
         this.__live_pos = next_live_pos;
 
-        const next_free = new Uint32Array(new_capacity);
-        next_free.set(this.__free_heap);
-        this.__free_heap = next_free;
     }
 
-    /**
-     * @private
-     * @param {number} v
-     */
-    __heap_push(v) {
-        const heap = this.__free_heap;
-        let i = this.__free_count++;
-        heap[i] = v;
-        while (i > 0) {
-            const parent = (i - 1) >>> 1;
-            if (heap[parent] > heap[i]) {
-                const tmp = heap[parent];
-                heap[parent] = heap[i];
-                heap[i] = tmp;
-                i = parent;
-            } else break;
-        }
-    }
-
-    /**
-     * @private
-     * @returns {number}
-     */
-    __heap_pop() {
-        const heap = this.__free_heap;
-        const result = heap[0];
-        const new_count = --this.__free_count;
-        if (new_count > 0) {
-            heap[0] = heap[new_count];
-            let i = 0;
-            while (true) {
-                const l = (i << 1) + 1;
-                const r = l + 1;
-                let smallest = i;
-                if (l < new_count && heap[l] < heap[smallest]) smallest = l;
-                if (r < new_count && heap[r] < heap[smallest]) smallest = r;
-                if (smallest === i) break;
-                const tmp = heap[i];
-                heap[i] = heap[smallest];
-                heap[smallest] = tmp;
-                i = smallest;
-            }
-        }
-        return result;
-    }
 }

package/src/engine/physics/ecs/BodyKind.d.ts

@@ -6,9 +6,13 @@
  *      common case for game-play objects.
  *  - {@link BodyKind.KinematicVelocity }: driven externally by velocity. Pushes Dynamic
  *      bodies but is not pushed back. Mass effectively infinite for the solver.
- *  - {@link BodyKind.KinematicPosition }: driven externally by direct pose writes. Velocity
- *      is derived by the system from the per-step delta so dynamic neighbours respond
- *      correctly.
+ *  - {@link BodyKind.KinematicPosition }: driven externally by direct pose writes.
+ *      RESERVED, not yet implemented: per-step velocity derivation is NOT
+ *      performed, so pose-driven movers currently present to the solver as
+ *      stationary walls that teleport. (Deriving velocity implicitly from
+ *      Transform deltas is deliberately deferred — without a separate
+ *      move/teleport API a spawn snap would read as an enormous velocity and
+ *      explode contacts. Prefer KinematicVelocity for movers until then.)
  *
  * These are plain enum ordinals compared by identity (`=== BodyKind.Dynamic`),
  * NOT a bitmask: Static is 0 (can't participate in a mask) and the values are

package/src/engine/physics/ecs/BodyKind.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BodyKind.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/BodyKind.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;uBAiBU,MAAM"}
+{"version":3,"file":"BodyKind.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/BodyKind.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;uBAqBU,MAAM"}

package/src/engine/physics/ecs/BodyKind.js

@@ -1,25 +1,29 @@
-/**
- * Kind of a rigid body. Determines how the body participates in the simulation:
- *  - {@link BodyKind.Static}: never moves. Has infinite mass. Ideal for level geometry.
- *      Stored in the static broadphase tree.
- *  - {@link BodyKind.Dynamic}: integrated under forces, gravity and contact impulses. The
- *      common case for game-play objects.
- *  - {@link BodyKind.KinematicVelocity}: driven externally by velocity. Pushes Dynamic
- *      bodies but is not pushed back. Mass effectively infinite for the solver.
- *  - {@link BodyKind.KinematicPosition}: driven externally by direct pose writes. Velocity
- *      is derived by the system from the per-step delta so dynamic neighbours respond
- *      correctly.
- *
- * These are plain enum ordinals compared by identity (`=== BodyKind.Dynamic`),
- * NOT a bitmask: Static is 0 (can't participate in a mask) and the values are
- * not bit-distinct (KinematicPosition 3 === Dynamic 1 | KinematicVelocity 2).
- *
- * @readonly
- * @enum {number}
- */
-export const BodyKind = {
-    Static: 0,
-    Dynamic: 1,
-    KinematicVelocity: 2,
-    KinematicPosition: 3,
-};
+/**
+ * Kind of a rigid body. Determines how the body participates in the simulation:
+ *  - {@link BodyKind.Static}: never moves. Has infinite mass. Ideal for level geometry.
+ *      Stored in the static broadphase tree.
+ *  - {@link BodyKind.Dynamic}: integrated under forces, gravity and contact impulses. The
+ *      common case for game-play objects.
+ *  - {@link BodyKind.KinematicVelocity}: driven externally by velocity. Pushes Dynamic
+ *      bodies but is not pushed back. Mass effectively infinite for the solver.
+ *  - {@link BodyKind.KinematicPosition}: driven externally by direct pose writes.
+ *      RESERVED, not yet implemented: per-step velocity derivation is NOT
+ *      performed, so pose-driven movers currently present to the solver as
+ *      stationary walls that teleport. (Deriving velocity implicitly from
+ *      Transform deltas is deliberately deferred — without a separate
+ *      move/teleport API a spawn snap would read as an enormous velocity and
+ *      explode contacts. Prefer KinematicVelocity for movers until then.)
+ *
+ * These are plain enum ordinals compared by identity (`=== BodyKind.Dynamic`),
+ * NOT a bitmask: Static is 0 (can't participate in a mask) and the values are
+ * not bit-distinct (KinematicPosition 3 === Dynamic 1 | KinematicVelocity 2).
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const BodyKind = {
+    Static: 0,
+    Dynamic: 1,
+    KinematicVelocity: 2,
+    KinematicPosition: 3,
+};

package/src/engine/physics/ecs/Collider.d.ts

@@ -77,6 +77,13 @@ export class Collider {
      * @param {boolean} value
      */
     writeFlag(flag: number | ColliderFlags, value: boolean): void;
+    /**
+     * Surface material + flags only. `shape` is deliberately NOT serialised —
+     * shapes are shared, immutable assets wired up by the asset pipeline,
+     * exactly as the binary {@link ColliderSerializationAdapter} documents.
+     * ({@link equals} DOES compare shapes: value equality and serialisation
+     * answer different questions.)
+     */
     toJSON(): {
         friction: number;
         restitution: number;

package/src/engine/physics/ecs/Collider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;MAOC;IAED,0BAKC;IAED;;;;;;;;OAQG;IACH,cAHW,QAAQ,GACN,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCAhKgB,gDAAgD;8BAElD,oBAAoB"}
+{"version":3,"file":"Collider.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/ecs/Collider.js"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,+BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH;IAEI;;;OAGG;IACH,OAFU,eAAe,CAEU;IAEnC;;;;OAIG;IACH,UAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;OAEG;IACH,OAFU,aAAa,GAAC,MAAM,CAEH;IAE3B;;;OAGG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,SAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,cAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;OAGG;IACH,gBAFW,MAAM,GAAC,aAAa,QAI9B;IAED;;;;OAIG;IACH,cAHW,MAAM,GAAC,aAAa,GAClB,OAAO,CAInB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GAAC,aAAa,SACpB,OAAO,QAQjB;IAED;;;;;;OAMG;IACH;;;;;MAOC;IAED,0BAKC;IAED;;;;;;;;OAQG;IACH,cAHW,QAAQ,GACN,OAAO,CAWnB;IAED;;;OAGG;IACH,QAFa,MAAM,CASlB;IASL;;;OAGG;IACH,qBAFU,OAAO,CAEY;CAZ5B;;kBAIS,MAAM;;gCAvKgB,gDAAgD;8BAElD,oBAAoB"}

package/src/engine/physics/ecs/Collider.js

@@ -107,6 +107,13 @@ export class Collider {
         }
     }
 
+    /**
+     * Surface material + flags only. `shape` is deliberately NOT serialised —
+     * shapes are shared, immutable assets wired up by the asset pipeline,
+     * exactly as the binary {@link ColliderSerializationAdapter} documents.
+     * ({@link equals} DOES compare shapes: value equality and serialisation
+     * answer different questions.)
+     */
     toJSON() {
         return {
             friction: this.friction,

package/src/engine/physics/ecs/ColliderSerializationAdapter.js

@@ -32,6 +32,6 @@ export class ColliderSerializationAdapter extends BinaryClassSerializationAdapte
         value.friction = buffer.readFloat64();
         value.restitution = buffer.readFloat64();
         value.density = buffer.readFloat64();
-        value.flags = buffer.readUint32();
+        value.flags = buffer.readUint32() | 0; // normalise signedness like the RigidBody adapter
     }
 }