@woosh/meep-engine 3.44.0 → 3.46.0

package/src/core/graph/csr/csr_graph_color_greedy.js

@@ -0,0 +1,83 @@
+import { assert } from "../../assert.js";
+
+/**
+ * Per-colour stamp: `MARK[c] === i + 1` while visiting the `i`-th vertex of the order means a neighbour
+ * already holds colour `c`. Module-static and grown on demand; the colouring runs synchronously start to
+ * finish, so reuse is safe.
+ * @type {Uint32Array}
+ */
+let MARK = new Uint32Array(0);
+
+/**
+ * Greedy graph colouring over a CSR adjacency: visit the vertices in `order`, and give each the lowest colour
+ * none of its already-coloured neighbours holds.
+ *
+ * Greedy colouring is order-sensitive, and the order is the caller's — Welsh–Powell's largest-degree-first
+ * is the usual choice, and the reason it is a parameter rather than a policy. For a given order the result
+ * is fully determined: the order of neighbours within a row, and duplicate entries in a row, do not change
+ * it. A vertex's colour is at most its degree, so the colour count is at most the largest degree plus one.
+ *
+ * Works on the raw CSR arrays rather than a {@link CSRGraph}, so any row-pointer/column-index pair can be
+ * coloured without being copied into one; for a `CSRGraph` pass `graph.edge_addresses, graph.adjacency`.
+ * A self-loop is ignored, since a vertex is uncoloured while its own colour is being chosen.
+ *
+ * Allocation-free per call, beyond growing the module scratch to `vertex_count + 1`; not reentrant.
+ *
+ * @param {Uint32Array|Int32Array|number[]} out_colors colour of every vertex, written for `[0, vertex_count)`
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {Uint32Array|Int32Array|ArrayLike<number>} adjacency neighbour ids, rows
+ *   `adjacency[edge_addresses[v] .. edge_addresses[v + 1])`
+ * @param {ArrayLike<number>} order a permutation of `[0, vertex_count)`, the visit order
+ * @param {number} vertex_count
+ * @returns {number} number of colours used; colours are `[0, count)`
+ */
+export function csr_graph_color_greedy(out_colors, edge_addresses, adjacency, order, vertex_count) {
+    assert.isNonNegativeInteger(vertex_count, 'vertex_count');
+    assert.greaterThanOrEqual(order.length, vertex_count, 'order shorter than vertex_count');
+    assert.greaterThanOrEqual(out_colors.length, vertex_count, 'out_colors shorter than vertex_count');
+
+    if (MARK.length < vertex_count + 1) {
+        MARK = new Uint32Array(vertex_count + 1);
+    } else {
+        MARK.fill(0, 0, vertex_count + 1);
+    }
+
+    const mark = MARK;
+
+    // No colour reaches `vertex_count`, so it stands for "not coloured yet" in whatever type the caller's
+    // array is.
+    for (let v = 0; v < vertex_count; v++) {
+        out_colors[v] = vertex_count;
+    }
+
+    let colour_count = 0;
+
+    for (let i = 0; i < vertex_count; i++) {
+        const v = order[i];
+        const stamp = i + 1;
+
+        const end = edge_addresses[v + 1];
+
+        for (let k = edge_addresses[v]; k < end; k++) {
+            const neighbour_colour = out_colors[adjacency[k]];
+
+            if (neighbour_colour < vertex_count) {
+                mark[neighbour_colour] = stamp;
+            }
+        }
+
+        let colour = 0;
+
+        while (mark[colour] === stamp) {
+            colour++;
+        }
+
+        out_colors[v] = colour;
+
+        if (colour >= colour_count) {
+            colour_count = colour + 1;
+        }
+    }
+
+    return colour_count;
+}

package/src/core/graph/csr/csr_graph_validate_coloring.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether a colouring is proper over a CSR adjacency: no vertex shares its colour with any of its neighbours.
+ * A self-loop is not a conflict.
+ *
+ * A debug check, meant to sit behind `assert.*` after a colouring is built; it reads every adjacency entry
+ * once. Works on the raw CSR arrays, like {@link csr_graph_color_greedy}.
+ *
+ * @param {ArrayLike<number>} colors colour of every vertex
+ * @param {ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {ArrayLike<number>} adjacency neighbour ids
+ * @param {number} vertex_count
+ * @returns {boolean} true when no edge joins two vertices of one colour
+ */
+export function csr_graph_validate_coloring(colors: ArrayLike<number>, edge_addresses: ArrayLike<number>, adjacency: ArrayLike<number>, vertex_count: number): boolean;
+//# sourceMappingURL=csr_graph_validate_coloring.d.ts.map

package/src/core/graph/csr/csr_graph_validate_coloring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csr_graph_validate_coloring.d.ts","sourceRoot":"","sources":["../../../../../src/core/graph/csr/csr_graph_validate_coloring.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oDANW,UAAU,MAAM,CAAC,kBACjB,UAAU,MAAM,CAAC,aACjB,UAAU,MAAM,CAAC,gBACjB,MAAM,GACJ,OAAO,CAqBnB"}

package/src/core/graph/csr/csr_graph_validate_coloring.js

@@ -0,0 +1,33 @@
+/**
+ * Whether a colouring is proper over a CSR adjacency: no vertex shares its colour with any of its neighbours.
+ * A self-loop is not a conflict.
+ *
+ * A debug check, meant to sit behind `assert.*` after a colouring is built; it reads every adjacency entry
+ * once. Works on the raw CSR arrays, like {@link csr_graph_color_greedy}.
+ *
+ * @param {ArrayLike<number>} colors colour of every vertex
+ * @param {ArrayLike<number>} edge_addresses row offsets, `vertex_count + 1` entries
+ * @param {ArrayLike<number>} adjacency neighbour ids
+ * @param {number} vertex_count
+ * @returns {boolean} true when no edge joins two vertices of one colour
+ */
+export function csr_graph_validate_coloring(colors, edge_addresses, adjacency, vertex_count) {
+    if (colors.length < vertex_count) {
+        return false;
+    }
+
+    for (let v = 0; v < vertex_count; v++) {
+        const colour = colors[v];
+        const end = edge_addresses[v + 1];
+
+        for (let k = edge_addresses[v]; k < end; k++) {
+            const neighbour = adjacency[k];
+
+            if (neighbour !== v && colors[neighbour] === colour) {
+                return false;
+            }
+        }
+    }
+
+    return true;
+}

package/src/core/math/hash/XXH128Hash.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A 128-bit xxHash3 result, kept as its two 64-bit halves because that is how the reference
+ * implementation names them and how every serialized form writes them.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class XXH128Hash {
+    /**
+     * @param {bigint} low64
+     * @param {bigint} high64
+     */
+    constructor(low64: bigint, high64: bigint);
+    /**
+     * @type {bigint}
+     */
+    low64: bigint;
+    /**
+     * @type {bigint}
+     */
+    high64: bigint;
+    /**
+     * @param {XXH128Hash} other
+     * @returns {boolean}
+     */
+    equals(other: XXH128Hash): boolean;
+    /**
+     * @returns {string} 32 lowercase hex digits, high half first
+     */
+    toString(): string;
+    /**
+     * Useful for type checking
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isXXH128Hash: boolean;
+}
+//# sourceMappingURL=XXH128Hash.d.ts.map

package/src/core/math/hash/XXH128Hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XXH128Hash.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/XXH128Hash.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH;IAWI;;;OAGG;IACH,mBAHW,MAAM,UACN,MAAM,EAQhB;IApBD;;OAEG;IACH,OAFU,MAAM,CAEL;IAEX;;OAEG;IACH,QAFU,MAAM,CAEJ;IAcZ;;;OAGG;IACH,cAHW,UAAU,GACR,OAAO,CAInB;IAED;;OAEG;IACH,YAFa,MAAM,CAIlB;IAGL;;;;OAIG;IACH,uBAFU,OAAO,CAEgB;CAPhC"}

package/src/core/math/hash/XXH128Hash.js

@@ -0,0 +1,55 @@
+import { assert } from "../../assert.js";
+import { XXH_MASK_64 } from "./xxh3_common.js";
+
+/**
+ * A 128-bit xxHash3 result, kept as its two 64-bit halves because that is how the reference
+ * implementation names them and how every serialized form writes them.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class XXH128Hash {
+    /**
+     * @type {bigint}
+     */
+    low64 = 0n;
+
+    /**
+     * @type {bigint}
+     */
+    high64 = 0n;
+
+    /**
+     * @param {bigint} low64
+     * @param {bigint} high64
+     */
+    constructor(low64, high64) {
+        assert.equal(typeof low64, 'bigint', `low64 must be a bigint, instead was '${typeof low64}'`);
+        assert.equal(typeof high64, 'bigint', `high64 must be a bigint, instead was '${typeof high64}'`);
+
+        this.low64 = low64 & XXH_MASK_64;
+        this.high64 = high64 & XXH_MASK_64;
+    }
+
+    /**
+     * @param {XXH128Hash} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return this.low64 === other.low64 && this.high64 === other.high64;
+    }
+
+    /**
+     * @returns {string} 32 lowercase hex digits, high half first
+     */
+    toString() {
+        return this.high64.toString(16).padStart(16, '0') + this.low64.toString(16).padStart(16, '0');
+    }
+}
+
+/**
+ * Useful for type checking
+ * @readonly
+ * @type {boolean}
+ */
+XXH128Hash.prototype.isXXH128Hash = true;

package/src/core/math/hash/XXH3_SECRET.d.ts

@@ -0,0 +1,13 @@
+/**
+ * xxHash3's default secret — the pseudorandom key material every unseeded hash mixes with, taken
+ * directly from FARSH by the reference implementation. Reproduced byte-for-byte; changing a single
+ * byte changes every hash this module produces.
+ *
+ * @see https://github.com/Cyan4973/xxHash/blob/dev/xxhash.h
+ * @readonly
+ * @type {Uint8Array}
+ *
+ * @copyright Company Named Limited (c) 2026
+ */
+export const XXH3_SECRET: Uint8Array;
+//# sourceMappingURL=XXH3_SECRET.d.ts.map

package/src/core/math/hash/XXH3_SECRET.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"XXH3_SECRET.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/XXH3_SECRET.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,0BAJU,UAAU,CAiBjB"}

package/src/core/math/hash/XXH3_SECRET.js

@@ -0,0 +1,25 @@
+/**
+ * xxHash3's default secret — the pseudorandom key material every unseeded hash mixes with, taken
+ * directly from FARSH by the reference implementation. Reproduced byte-for-byte; changing a single
+ * byte changes every hash this module produces.
+ *
+ * @see https://github.com/Cyan4973/xxHash/blob/dev/xxhash.h
+ * @readonly
+ * @type {Uint8Array}
+ *
+ * @copyright Company Named Limited (c) 2026
+ */
+export const XXH3_SECRET = new Uint8Array([
+    0xb8, 0xfe, 0x6c, 0x39, 0x23, 0xa4, 0x4b, 0xbe, 0x7c, 0x01, 0x81, 0x2c, 0xf7, 0x21, 0xad, 0x1c,
+    0xde, 0xd4, 0x6d, 0xe9, 0x83, 0x90, 0x97, 0xdb, 0x72, 0x40, 0xa4, 0xa4, 0xb7, 0xb3, 0x67, 0x1f,
+    0xcb, 0x79, 0xe6, 0x4e, 0xcc, 0xc0, 0xe5, 0x78, 0x82, 0x5a, 0xd0, 0x7d, 0xcc, 0xff, 0x72, 0x21,
+    0xb8, 0x08, 0x46, 0x74, 0xf7, 0x43, 0x24, 0x8e, 0xe0, 0x35, 0x90, 0xe6, 0x81, 0x3a, 0x26, 0x4c,
+    0x3c, 0x28, 0x52, 0xbb, 0x91, 0xc3, 0x00, 0xcb, 0x88, 0xd0, 0x65, 0x8b, 0x1b, 0x53, 0x2e, 0xa3,
+    0x71, 0x64, 0x48, 0x97, 0xa2, 0x0d, 0xf9, 0x4e, 0x38, 0x19, 0xef, 0x46, 0xa9, 0xde, 0xac, 0xd8,
+    0xa8, 0xfa, 0x76, 0x3f, 0xe3, 0x9c, 0x34, 0x3f, 0xf9, 0xdc, 0xbb, 0xc7, 0xc7, 0x0b, 0x4f, 0x1d,
+    0x8a, 0x51, 0xe0, 0x4b, 0xcd, 0xb4, 0x59, 0x31, 0xc8, 0x9f, 0x7e, 0xc9, 0xd9, 0x78, 0x73, 0x64,
+    0xea, 0xc5, 0xac, 0x83, 0x34, 0xd3, 0xeb, 0xc3, 0xc5, 0x81, 0xa0, 0xff, 0xfa, 0x13, 0x63, 0xeb,
+    0x17, 0x0d, 0xdd, 0x51, 0xb7, 0xf0, 0xda, 0x49, 0xd3, 0x16, 0x55, 0x26, 0x29, 0xd4, 0x68, 0x9e,
+    0x2b, 0x16, 0xbe, 0x58, 0x7d, 0x47, 0xa1, 0xfc, 0x8f, 0xf8, 0xb8, 0xd1, 0x7a, 0xd0, 0x31, 0xce,
+    0x45, 0xcb, 0x3a, 0x8f, 0x95, 0x16, 0x04, 0x28, 0xaf, 0xd7, 0xfb, 0xca, 0xbb, 0x4b, 0x40, 0x7e,
+]);

package/src/core/math/hash/crc32.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 32-bit Cyclic Redundancy Checksum.
+ * @see https://en.wikipedia.org/wiki/Cyclic_redundancy_check
+ * @param {Uint8Array} buffer byte buffer
+ * @param {number} [offset=0] where to start in the input buffer
+ * @param {number} [length=buffer.length] how many bytes to include in checksum calculation
+ * @return {number} Unsigned 32-bit integer value
+ * @copyright Company Named Limited (c) 2026
+ *
+ * @example
+ *      const buffer = new BinaryBuffer();
+ *      buffer.writeASCIIString("Hello World");
+ *      const checksum = crc32(buffer.raw_bytes, 0, buffer.position);
+ */
+export function crc32(buffer: Uint8Array, offset?: number, length?: number): number;
+//# sourceMappingURL=crc32.d.ts.map

package/src/core/math/hash/crc32.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crc32.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/crc32.js"],"names":[],"mappings":"AA2EA;;;;;;;;;;;;;GAaG;AACH,8BAXW,UAAU,WACV,MAAM,WACN,MAAM,GACL,MAAM,CAcjB"}

package/src/core/math/hash/crc32.js

@@ -0,0 +1,96 @@
+import { assert } from "../../assert.js";
+
+/*
+ * CRC-32/ISO-3309, the reflected 0xEDB88320 variant. The same checksum PNG chunks, ZIP local file
+ * headers and gzip trailers all carry, which is why this lives in core rather than beside any one
+ * of them.
+ *
+ * Ported from C source at https://www.w3.org/TR/PNG-CRCAppendix.html
+ * See also ISO 3309 [ISO-3309] or ITU-T V.42 [ITU-V42] for a formal specification
+ */
+
+/**
+ *
+ * @type {Uint32Array}
+ */
+const crc_table = new Uint32Array(256);
+
+// Precompute checksum table
+for (let n = 0; n < 256; n++) {
+    let c = n;
+
+    for (let k = 0; k < 8; k++) {
+
+        if ((c & 1) !== 0) {
+            // CRC32b polynomial
+            c = 0xedb88320 ^ (c >>> 1);
+        } else {
+            c = c >>> 1;
+        }
+
+    }
+
+    crc_table[n] = c;
+}
+
+const INITIAL = 0xffffffff;
+
+/**
+ * Update a running CRC with the bytes buf[0..len-1]--the CRC
+ * should be initialized to all 1's, and the transmitted value
+ * is the 1's complement of the final running CRC (see the crc32() routine below)).
+ * @param {number} input_crc starting CRC value
+ * @param {Uint8Array} buffer
+ * @param {number} offset
+ * @param {number} length
+ * @return {number}
+ */
+function update_crc(
+    input_crc,
+    buffer,
+    offset,
+    length,
+) {
+    assert.isNonNegativeInteger(input_crc, 'input_crc');
+    assert.defined(buffer, 'buffer');
+    assert.isNonNegativeInteger(offset, 'offset');
+    assert.isNonNegativeInteger(length, 'length');
+
+    let crc = input_crc;
+
+    const end = offset + length;
+
+    for (let n = offset; n < end; n++) {
+
+        const byte = buffer[n];
+
+        const lookup_index = (crc ^ byte) & 0xff;
+
+        crc = crc_table[lookup_index] ^ (crc >>> 8);
+
+    }
+
+    return crc;
+}
+
+/**
+ * 32-bit Cyclic Redundancy Checksum.
+ * @see https://en.wikipedia.org/wiki/Cyclic_redundancy_check
+ * @param {Uint8Array} buffer byte buffer
+ * @param {number} [offset=0] where to start in the input buffer
+ * @param {number} [length=buffer.length] how many bytes to include in checksum calculation
+ * @return {number} Unsigned 32-bit integer value
+ * @copyright Company Named Limited (c) 2026
+ *
+ * @example
+ *      const buffer = new BinaryBuffer();
+ *      buffer.writeASCIIString("Hello World");
+ *      const checksum = crc32(buffer.raw_bytes, 0, buffer.position);
+ */
+export function crc32(
+    buffer,
+    offset=0,
+    length=buffer.length,
+) {
+    return (update_crc(INITIAL, buffer, offset, length) ^ INITIAL) >>> 0;
+}

package/src/core/math/hash/xxh3_128.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Hash `input` to a 128-bit value.
+ *
+ * @param {Uint8Array} input bytes to hash; an empty array is valid
+ * @param {bigint} [seed] alters the whole hash; 0 selects the reference's unseeded behaviour
+ * @returns {XXH128Hash}
+ */
+export function xxh3_128(input: Uint8Array, seed?: bigint): XXH128Hash;
+import { XXH128Hash } from "./XXH128Hash.js";
+//# sourceMappingURL=xxh3_128.d.ts.map

package/src/core/math/hash/xxh3_128.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xxh3_128.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/xxh3_128.js"],"names":[],"mappings":"AA2TA;;;;;;GAMG;AACH,gCAJW,UAAU,SACV,MAAM,GACJ,UAAU,CAoBtB;2BApV0B,iBAAiB"}