@woosh/meep-engine 2.138.20 → 2.139.0

package/src/core/collection/Uint32Map.js

@@ -0,0 +1,345 @@
+import { assert } from "../assert.js";
+
+const UINT32_MAX = 4294967295;
+
+/**
+ * Returned by {@link Uint32Map#get} when the key is absent. Chosen so that any uint32 (0 .. UINT32_MAX) is
+ * unambiguously a valid value. As a JS Number this is a Smi on all V8 builds, so the return doesn't allocate.
+ * @type {number}
+ */
+export const UINT32_MAP_ABSENT = -1;
+
+/**
+ * 2^32 / phi, rounded to nearest integer. Multiplier for Fibonacci hashing — scatters sequential integer
+ * keys across the index space with one multiply and one shift.
+ * @type {number}
+ */
+const FIB_HASH_MULTIPLIER = 2654435769;
+
+/**
+ * @type {number}
+ */
+const DEFAULT_CAPACITY = 16;
+
+/**
+ * Smallest table we ever create. Capacity is always a power of two, so the actual minimum is 2.
+ * @type {number}
+ */
+const MIN_CAPACITY = 2;
+
+/**
+ * Grow when `size > capacity * 3/4`. Slater ("Optimizing Open Addressing", thenumb.at/Hashtables) puts
+ * the sweet-spot load factor for Robin Hood at ~0.75; past that, max probe length climbs fast even though
+ * mean stays low.
+ * @type {number}
+ */
+const LOAD_FACTOR_NUMERATOR = 3;
+const LOAD_FACTOR_SHIFT = 2; // divide by 4
+
+/**
+ * Non-allocating Map<uint32, uint32> backed by a single Uint32Array.
+ *
+ * Layout: one slot occupies two consecutive words — `data[2*slot] = key + 1`, `data[2*slot + 1] = value`.
+ * Keys are stored offset by +1 so that 0 is unambiguously "empty slot"; this also keeps every stored value
+ * inside the V8 Smi range (under pointer compression, Smi is 31-bit signed = max 2^30 − 1), which means
+ * reading any non-empty slot does not allocate a HeapNumber. Without the shift, a sentinel of 0xFFFFFFFF
+ * would box on every read of an empty slot — the exact opposite of what we want.
+ *
+ * Collision resolution: Robin Hood linear probing with backward-shift deletion (Knuth Algorithm R). Hash
+ * is Fibonacci multiplicative (see Skarupke 2018, "Fibonacci Hashing"), indexing from the high bits of
+ * the product. Table capacity is always a power of two; index is computed by right-shift, not by mask of
+ * the low bits — the high bits of a multiplicative hash have more entropy.
+ *
+ * Allowed key range: 0 .. UINT32_MAX - 1 (because we store key + 1). Allowed value range: full uint32.
+ * Values are returned via {@link UINT32_MAP_ABSENT} when not found — callers check `=== -1` rather than
+ * `=== undefined`, which is the Map API but is allocation-incompatible with typed-array storage.
+ */
+export class Uint32Map {
+
+    /**
+     *
+     * @param {number} [initial_capacity] minimum number of slots to reserve. Rounded up to next power of two.
+     */
+    constructor(initial_capacity = DEFAULT_CAPACITY) {
+        assert.isNonNegativeInteger(initial_capacity, 'initial_capacity');
+
+        let cap = MIN_CAPACITY;
+        while (cap < initial_capacity) {
+            cap <<= 1;
+        }
+
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__capacity = cap;
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__mask = cap - 1;
+        /**
+         * Right-shift amount that extracts log2(cap) high bits from a 32-bit hash.
+         * @type {number}
+         * @private
+         */
+        this.__shift = Math.clz32(cap - 1);
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__grow_threshold = (cap * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__size = 0;
+        /**
+         * Packed (key+1, value) pairs. Length is 2 * capacity. Zero-initialized so every slot starts empty.
+         * @type {Uint32Array}
+         * @private
+         */
+        this.__data = new Uint32Array(cap << 1);
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get size() {
+        return this.__size;
+    }
+
+    /**
+     *
+     * @returns {number}
+     */
+    get capacity() {
+        return this.__capacity;
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @returns {number} value associated with `id`, or {@link UINT32_MAP_ABSENT} (-1) if not present.
+     */
+    get(id) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const key_shifted = id + 1;
+
+        let slot = Math.imul(key_shifted, FIB_HASH_MULTIPLIER) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const slot2 = slot << 1;
+            const k = data[slot2];
+
+            if (k === 0) {
+                return UINT32_MAP_ABSENT;
+            }
+            if (k === key_shifted) {
+                return data[slot2 + 1];
+            }
+
+            // Robin Hood early-exit: if our displacement exceeds the occupant's, we would have stolen this
+            // slot during insert — so the key cannot be further down the probe chain.
+            const slot_home = Math.imul(k, FIB_HASH_MULTIPLIER) >>> shift;
+            const slot_dist = (slot - slot_home) & mask;
+            if (dist > slot_dist) {
+                return UINT32_MAP_ABSENT;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    has(id) {
+        return this.get(id) !== UINT32_MAP_ABSENT;
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @param {number} value
+     */
+    set(id, value) {
+        // hot path — asserts commented per codebase convention. Pre-conditions:
+        //   id    must be a non-negative integer <= UINT32_MAX - 1
+        //   value must be a non-negative integer (full uint32 range)
+        // assert.isNonNegativeInteger(id, 'id');
+        // assert.lessThanOrEqual(id, UINT32_MAX - 1, 'id must be <= (2^32 - 2)');
+        // assert.isNonNegativeInteger(value, 'value');
+
+        if (this.__size >= this.__grow_threshold) {
+            this.__resize(this.__capacity << 1);
+        }
+
+        this.__insert_no_grow(id + 1, value);
+    }
+
+    /**
+     * Insert a (already key+1 shifted) entry assuming there is at least one empty slot. Performs Robin Hood
+     * swapping: when the new entry has been displaced further than the current occupant, swap them and
+     * continue placing the displaced occupant.
+     *
+     * @private
+     * @param {number} key_shifted
+     * @param {number} value
+     */
+    __insert_no_grow(key_shifted, value) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        let ks = key_shifted;
+        let v = value;
+        let slot = Math.imul(ks, FIB_HASH_MULTIPLIER) >>> shift;
+        let dist = 0;
+
+        while (true) {
+            const slot2 = slot << 1;
+            const k = data[slot2];
+
+            if (k === 0) {
+                data[slot2] = ks;
+                data[slot2 + 1] = v;
+                this.__size++;
+                return;
+            }
+
+            if (k === ks) {
+                // existing entry — overwrite value, do not change size
+                data[slot2 + 1] = v;
+                return;
+            }
+
+            const slot_home = Math.imul(k, FIB_HASH_MULTIPLIER) >>> shift;
+            const slot_dist = (slot - slot_home) & mask;
+
+            if (slot_dist < dist) {
+                // steal: occupant is closer to home than the entry we are carrying. Swap.
+                const tmp_k = k;
+                const tmp_v = data[slot2 + 1];
+                data[slot2] = ks;
+                data[slot2 + 1] = v;
+                ks = tmp_k;
+                v = tmp_v;
+                dist = slot_dist;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean} true if the entry existed and was removed.
+     */
+    delete(id) {
+        const data = this.__data;
+        const mask = this.__mask;
+        const shift = this.__shift;
+
+        const key_shifted = id + 1;
+
+        let slot = Math.imul(key_shifted, FIB_HASH_MULTIPLIER) >>> shift;
+        let dist = 0;
+
+        // locate the slot, applying the same Robin Hood early-exit as `get`
+        while (true) {
+            const slot2 = slot << 1;
+            const k = data[slot2];
+
+            if (k === 0) {
+                return false;
+            }
+            if (k === key_shifted) {
+                break;
+            }
+
+            const slot_home = Math.imul(k, FIB_HASH_MULTIPLIER) >>> shift;
+            const slot_dist = (slot - slot_home) & mask;
+            if (dist > slot_dist) {
+                return false;
+            }
+
+            slot = (slot + 1) & mask;
+            dist++;
+        }
+
+        // backward-shift deletion: walk forward, pulling each displaced successor into the freed slot,
+        // until we hit an empty slot or an occupant already at its home.
+        while (true) {
+            const next = (slot + 1) & mask;
+            const next2 = next << 1;
+            const next_k = data[next2];
+
+            if (next_k === 0) {
+                break;
+            }
+
+            const next_home = Math.imul(next_k, FIB_HASH_MULTIPLIER) >>> shift;
+            const next_dist = (next - next_home) & mask;
+            if (next_dist === 0) {
+                // successor is at its home — moving it back would break its lookup
+                break;
+            }
+
+            const slot2 = slot << 1;
+            data[slot2] = next_k;
+            data[slot2 + 1] = data[next2 + 1];
+            slot = next;
+        }
+
+        // clear the final emptied slot
+        data[slot << 1] = 0;
+
+        this.__size--;
+        return true;
+    }
+
+    /**
+     * Remove all entries. Capacity is unchanged.
+     */
+    clear() {
+        this.__data.fill(0);
+        this.__size = 0;
+    }
+
+    /**
+     * Grow the table and rehash every entry.
+     *
+     * @private
+     * @param {number} new_capacity power of two
+     */
+    __resize(new_capacity) {
+        const old_data = this.__data;
+        const old_capacity = this.__capacity;
+
+        this.__capacity = new_capacity;
+        this.__mask = new_capacity - 1;
+        this.__shift = Math.clz32(new_capacity - 1);
+        this.__grow_threshold = (new_capacity * LOAD_FACTOR_NUMERATOR) >>> LOAD_FACTOR_SHIFT;
+        this.__data = new Uint32Array(new_capacity << 1);
+        this.__size = 0;
+
+        for (let i = 0; i < old_capacity; i++) {
+            const i2 = i << 1;
+            const k = old_data[i2];
+            if (k !== 0) {
+                this.__insert_no_grow(k, old_data[i2 + 1]);
+            }
+        }
+    }
+}

package/src/core/collection/array/array_shuffle.d.ts

@@ -1,8 +1,15 @@
 /**
- * Randomly re-orders items in-place
+ * Randomly re-orders items in-place using Fisher–Yates.
+ *
+ * Pass `length` when shuffling a prefix of a larger buffer (e.g. a scratch
+ * typed array sized for a worst-case but containing only a smaller active
+ * range). Elements beyond `length` are untouched. Default is `array.length`,
+ * which gives the natural "shuffle the whole thing" behaviour.
+ *
  * @template T
  * @param {function():number} random random number generator; can use Math.random. Must return a value between 0 and 1
- * @param {T[]} array what to shuffle
+ * @param {T[]|TypedArray} array what to shuffle (mutated in place)
+ * @param {number} [length] how many leading entries of `array` to shuffle; defaults to `array.length`
  */
-export function array_shuffle<T>(random: () => number, array: T[]): void;
+export function array_shuffle<T>(random: () => number, array: any, length?: number): void;
 //# sourceMappingURL=array_shuffle.d.ts.map

package/src/core/collection/array/array_shuffle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array_shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_shuffle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,+CAHsB,MAAM,oBAe3B"}
+{"version":3,"file":"array_shuffle.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/array/array_shuffle.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,+CAJsB,MAAM,uBAEjB,MAAM,QAYhB"}

package/src/core/collection/array/array_shuffle.js

@@ -1,22 +1,27 @@
-import { randomIntegerBetween } from "../../math/random/randomIntegerBetween.js";
-import { array_swap_one } from "./array_swap_one.js";
-
-/**
- * Randomly re-orders items in-place
- * @template T
- * @param {function():number} random random number generator; can use Math.random. Must return a value between 0 and 1
- * @param {T[]} array what to shuffle
- */
-export function array_shuffle(random, array) {
-    const n = array.length;
-
-    for (let source_index = 0; source_index < n; ++source_index) {
-        const target_index = randomIntegerBetween(random, 0, n - (source_index + 1));
-
-        if (target_index === source_index) {
-            continue;
-        }
-
-        array_swap_one(array, source_index, target_index);
-    }
-}
+import { randomIntegerBetween } from "../../math/random/randomIntegerBetween.js";
+import { array_swap_one } from "./array_swap_one.js";
+
+/**
+ * Randomly re-orders items in-place using Fisher–Yates.
+ *
+ * Pass `length` when shuffling a prefix of a larger buffer (e.g. a scratch
+ * typed array sized for a worst-case but containing only a smaller active
+ * range). Elements beyond `length` are untouched. Default is `array.length`,
+ * which gives the natural "shuffle the whole thing" behaviour.
+ *
+ * @template T
+ * @param {function():number} random random number generator; can use Math.random. Must return a value between 0 and 1
+ * @param {T[]|TypedArray} array what to shuffle (mutated in place)
+ * @param {number} [length] how many leading entries of `array` to shuffle; defaults to `array.length`
+ */
+export function array_shuffle(random, array, length = array.length) {
+    for (let source_index = 0; source_index < length; ++source_index) {
+        const target_index = randomIntegerBetween(random, 0, length - (source_index + 1));
+
+        if (target_index === source_index) {
+            continue;
+        }
+
+        array_swap_one(array, source_index, target_index);
+    }
+}

package/src/core/collection/heap/FibonacciHeap.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Fibonacci heap implementation that stores uint32 ID along with a floating point score value, intended to be
+ * API-compatible with {@link Uint32Heap}.
+ *
+ * Storage is struct-of-arrays on top of a single {@link BinaryElementPool} — each "node" is a 32-byte
+ * record in a contiguous ArrayBuffer, and "node references" are uint32 handles rather than object pointers.
+ * This keeps all per-node state in continuous memory, avoiding the per-element allocation and pointer chasing
+ * of an object-graph implementation.
+ *
+ * Fibonacci heaps have theoretically excellent asymptotic bounds:
+ *   - insert, find-min, decrease-key: amortized O(1)
+ *   - extract-min, delete: amortized O(log n)
+ *
+ * In practice they often lose to a simple binary or 4-ary heap on graph-search workloads because of poor
+ * cache behavior; this layout closes most of that gap by removing the indirection. See Larkin, Sen & Tarjan
+ * (2014), "A Back-to-Basics Empirical Study of Priority Queues" (arXiv:1403.0252) for the empirical context.
+ *
+ * Reference: Cormen, Leiserson, Rivest, Stein, "Introduction to Algorithms", 3rd ed., chapter 19.
+ *
+ * @see Uint32Heap
+ * @see Uint32Heap4
+ */
+export class FibonacciHeap {
+    /**
+     *
+     * @param {number} [initial_capacity] reserves space for this many nodes up front. The pool grows on demand.
+     */
+    constructor(initial_capacity?: number);
+    /**
+     * @type {BinaryElementPool}
+     * @private
+     */
+    private __pool;
+    /**
+     * Handle of the node with the smallest key, or NULL_HANDLE if empty.
+     * @type {number}
+     * @private
+     */
+    private __min;
+    /**
+     * Number of nodes currently in the heap.
+     * @type {number}
+     * @private
+     */
+    private __size;
+    /**
+     * Id -> handle lookup, allows update_score / remove / contains / get_score in O(1) expected.
+     *
+     * Empirically (see the bench tests in FibonacciHeap.spec.js), V8's built-in Map beats a hand-rolled
+     * Uint32Array-backed Robin Hood hash table for this workload by 20-90 % on hot paths. Reason: every
+     * key and value here is SMI (ids and handles are both small), so V8 Map's native C++ SMI fast path
+     * never boxes; meanwhile a JS-side flat-array implementation pays per-probe Math.imul + bounds-checks
+     * that V8's compiled Map sidesteps. The Uint32Map primitive lives at core/collection/Uint32Map.js
+     * and is the right choice when keys/values exceed 2^30 (V8 Map boxes) or when delete churn is
+     * extreme (V8 Map tombstone-rots until rehash) — but not here.
+     *
+     * @type {Map<number, number>}
+     * @private
+     */
+    private __handles;
+    /**
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Node with the lowest score
+     * @returns {number}
+     */
+    get top_id(): number;
+    /**
+     *
+     * @returns {boolean}
+     */
+    is_empty(): boolean;
+    /**
+     * Returns the score of the node with the lowest score
+     * @returns {number}
+     */
+    peek_score(): number;
+    /**
+     * Returns the ID of the node with the lowest score
+     * @returns {number}
+     */
+    peek_min(): number;
+    /**
+     * Splice `handle` (a single-element circular list) into the root list to the right of `__min`. The caller
+     * is responsible for setting parent and degree on `handle`.
+     *
+     * @private
+     * @param {number} handle
+     */
+    private __root_insert;
+    /**
+     * Remove `handle` from its sibling list (root list or child list of some parent). Sibling pointers of
+     * `handle` are left dangling; the caller is expected to re-link it immediately.
+     *
+     * @private
+     * @param {number} handle
+     */
+    private __unlink_from_siblings;
+    /**
+     *
+     * @param {number} id
+     * @param {number} score
+     */
+    insert(id: number, score: number): void;
+    /**
+     * Removed and returns the ID of the node with the lowest score.
+     *
+     * @returns {number}
+     */
+    pop_min(): number;
+    /**
+     * Merge trees of equal degree until every degree is unique among the roots. Sets `__min` to the true
+     * minimum.
+     *
+     * @private
+     */
+    private __consolidate;
+    /**
+     * Make `y` (currently in the root list) a child of `x`.
+     *
+     * @private
+     * @param {number} y
+     * @param {number} x
+     */
+    private __link;
+    /**
+     * Decrease the key of `handle` to `new_key`. `new_key` must be <= current key.
+     *
+     * @private
+     * @param {number} handle
+     * @param {number} new_key
+     */
+    private __decrease_key;
+    /**
+     * Cut `x` from `y`'s child list and promote it to the root list.
+     *
+     * @private
+     * @param {number} x child being cut
+     * @param {number} y parent of x
+     */
+    private __cut;
+    /**
+     * Walk up from `y`, cutting marked ancestors and marking unmarked ones.
+     *
+     * @private
+     * @param {number} y
+     */
+    private __cascading_cut;
+    /**
+     * Delete the node referenced by `handle` by decreasing its key to -Infinity and popping the min.
+     *
+     * @private
+     * @param {number} handle
+     */
+    private __delete_handle;
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    contains(id: number): boolean;
+    /**
+     *
+     * @param {number} id
+     * @returns {number} score of the element with the given id, NaN if not found
+     */
+    get_score(id: number): number;
+    /**
+     *
+     * @param {number} id
+     * @param {number} score
+     */
+    update_score(id: number, score: number): void;
+    /**
+     * Insert or update an element, if the element already exists, its score will be updated.
+     *
+     * @param {number} id
+     * @param {number} score
+     */
+    insert_or_update(id: number, score: number): void;
+    /**
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    remove(id: number): boolean;
+    /**
+     * Clear out all the data, heap will be made empty
+     */
+    clear(): void;
+}
+//# sourceMappingURL=FibonacciHeap.d.ts.map

package/src/core/collection/heap/FibonacciHeap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FibonacciHeap.d.ts","sourceRoot":"","sources":["../../../../../src/core/collection/heap/FibonacciHeap.js"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAEI;;;OAGG;IACH,+BAFW,MAAM,EAwChB;IAnCG;;;OAGG;IACH,eAAuE;IAEvE;;;;OAIG;IACH,cAAwB;IAExB;;;;OAIG;IACH,eAAe;IAEf;;;;;;;;;;;;;OAaG;IACH,kBAA0B;IAG9B;;;OAGG;IACH,mBAEC;IAED;;;OAGG;IACH,qBAKC;IAED;;;OAGG;IACH,YAFa,OAAO,CAInB;IAED;;;OAGG;IACH,cAFa,MAAM,CAOlB;IAED;;;OAGG;IACH,YAFa,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAyBC;IAED;;;;;;OAMG;IACH,+BASC;IAED;;;;OAIG;IACH,WAHW,MAAM,SACN,MAAM,QA4BhB;IAED;;;;OAIG;IACH,WAFa,MAAM,CAwDlB;IAED;;;;;OAKG;IACH,sBAwDC;IAED;;;;;;OAMG;IACH,eA4BC;IAED;;;;;;OAMG;IACH,uBAkBC;IAED;;;;;;OAMG;IACH,cA2BC;IAED;;;;;OAKG;IACH,wBAaC;IAED;;;;;OAKG;IACH,wBAGC;IAED;;;;OAIG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;OAIG;IACH,cAHW,MAAM,GACJ,MAAM,CAQlB;IAED;;;;OAIG;IACH,iBAHW,MAAM,SACN,MAAM,QAsBhB;IAED;;;;;OAKG;IACH,qBAHW,MAAM,SACN,MAAM,QAQhB;IAED;;;;OAIG;IACH,WAHW,MAAM,GACJ,OAAO,CAYnB;IAED;;OAEG;IACH,cAKC;CACJ"}