@woosh/meep-engine 3.45.0 → 3.47.0

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"}

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

@@ -0,0 +1,341 @@
+import { XXH128Hash } from "./XXH128Hash.js";
+import { XXH3_SECRET } from "./XXH3_SECRET.js";
+import {
+    add64,
+    mul64,
+    mult32to64,
+    read_u32,
+    read_u64,
+    rotl32,
+    sub64,
+    swap32,
+    swap64,
+    u64,
+    XXH3_MIDSIZE_LASTOFFSET,
+    XXH3_MIDSIZE_MAX,
+    XXH3_MIDSIZE_STARTOFFSET,
+    XXH3_SECRET_SIZE_MIN,
+    xxh3_assert_arguments,
+    xxh3_avalanche,
+    xxh3_hash_long_loop,
+    xxh3_init_acc,
+    xxh3_long_secret,
+    xxh3_merge_accs,
+    xxh3_mix16b,
+    XXH_MASK_64,
+    XXH_PRIME32_2,
+    XXH_PRIME64_1,
+    XXH_PRIME64_2,
+    XXH_PRIME64_4,
+    XXH_PRIME_MX2,
+    XXH_SECRET_MERGEACCS_START,
+    XXH_STRIPE_LEN,
+    xorshift64,
+    xxh64_avalanche,
+} from "./xxh3_common.js";
+
+/**
+ * xxHash3, 128-bit output.
+ *
+ * A direct transcription of the reference implementation, verified against its published sanity
+ * vectors — see `xxh3_128.spec.js`. The low 64 bits are *not* in general equal to
+ * {@link xxh3_64} of the same input; they only coincide for inputs longer than
+ * {@link XXH3_MIDSIZE_MAX}, where both variants share the accumulator loop.
+ *
+ * @see https://github.com/Cyan4973/xxHash
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * Full 64x64 -> 128 multiply. The halves are returned separately because every caller manipulates
+ * them independently before folding.
+ *
+ * @param {bigint} a
+ * @param {bigint} b
+ * @returns {XXH128Hash}
+ */
+function mult64to128(a, b) {
+    const product = a * b;
+
+    return new XXH128Hash(product & XXH_MASK_64, (product >> 64n) & XXH_MASK_64);
+}
+
+/**
+ * @param {Uint8Array} input 1..3 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_1to3(input, secret, seed) {
+    const len = input.length;
+
+    const c1 = input[0];
+    const c2 = input[len >> 1];
+    const c3 = input[len - 1];
+
+    const combined_lo = BigInt(((c1 << 16) | (c2 << 24) | c3 | (len << 8)) >>> 0);
+    const combined_hi = rotl32(swap32(combined_lo), 13);
+
+    const bitflip_lo = add64(read_u32(secret, 0) ^ read_u32(secret, 4), seed);
+    const bitflip_hi = sub64(read_u32(secret, 8) ^ read_u32(secret, 12), seed);
+
+    return new XXH128Hash(
+        xxh64_avalanche(combined_lo ^ bitflip_lo),
+        xxh64_avalanche(combined_hi ^ bitflip_hi)
+    );
+}
+
+/**
+ * @param {Uint8Array} input 4..8 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_4to8(input, secret, seed) {
+    const len = input.length;
+
+    const mixed_seed = seed ^ u64(swap32(seed) << 32n);
+
+    const input_lo = read_u32(input, 0);
+    const input_hi = read_u32(input, len - 4);
+
+    const input_64 = add64(input_lo, input_hi << 32n);
+    const bitflip = add64(read_u64(secret, 16) ^ read_u64(secret, 24), mixed_seed);
+    const keyed = input_64 ^ bitflip;
+
+    const m128 = mult64to128(keyed, add64(XXH_PRIME64_1, BigInt(len) << 2n));
+
+    m128.high64 = add64(m128.high64, u64(m128.low64 << 1n));
+    m128.low64 = m128.low64 ^ (m128.high64 >> 3n);
+
+    m128.low64 = xorshift64(m128.low64, 35);
+    m128.low64 = mul64(m128.low64, XXH_PRIME_MX2);
+    m128.low64 = xorshift64(m128.low64, 28);
+    m128.high64 = xxh3_avalanche(m128.high64);
+
+    return m128;
+}
+
+/**
+ * @param {Uint8Array} input 9..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_9to16(input, secret, seed) {
+    const len = input.length;
+
+    const bitflip_lo = sub64(read_u64(secret, 32) ^ read_u64(secret, 40), seed);
+    const bitflip_hi = add64(read_u64(secret, 48) ^ read_u64(secret, 56), seed);
+
+    const input_lo = read_u64(input, 0);
+
+    let input_hi = read_u64(input, len - 8);
+
+    const m128 = mult64to128(input_lo ^ input_hi ^ bitflip_lo, XXH_PRIME64_1);
+
+    m128.low64 = add64(m128.low64, BigInt(len - 1) << 54n);
+
+    input_hi ^= bitflip_hi;
+
+    m128.high64 = add64(
+        m128.high64,
+        add64(input_hi, mult32to64(input_hi, XXH_PRIME32_2 - 1n))
+    );
+
+    m128.low64 = m128.low64 ^ swap64(m128.high64);
+
+    const h128 = mult64to128(m128.low64, XXH_PRIME64_2);
+
+    h128.high64 = add64(h128.high64, mul64(m128.high64, XXH_PRIME64_2));
+
+    h128.low64 = xxh3_avalanche(h128.low64);
+    h128.high64 = xxh3_avalanche(h128.high64);
+
+    return h128;
+}
+
+/**
+ * @param {Uint8Array} input 0..16 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_0to16(input, secret, seed) {
+    const len = input.length;
+
+    if (len > 8) {
+        return len_9to16(input, secret, seed);
+    }
+
+    if (len >= 4) {
+        return len_4to8(input, secret, seed);
+    }
+
+    if (len > 0) {
+        return len_1to3(input, secret, seed);
+    }
+
+    const bitflip_lo = read_u64(secret, 64) ^ read_u64(secret, 72);
+    const bitflip_hi = read_u64(secret, 80) ^ read_u64(secret, 88);
+
+    return new XXH128Hash(
+        xxh64_avalanche(seed ^ bitflip_lo),
+        xxh64_avalanche(seed ^ bitflip_hi)
+    );
+}
+
+/**
+ * The 32-byte mixing step: two 16-byte windows, each folded into one half and cross-XOR'd into the
+ * other. Slower than the 64-bit path's `mix16B`, and better behaved when a product lands on zero.
+ *
+ * @param {XXH128Hash} acc mutated in place
+ * @param {Uint8Array} input
+ * @param {number} input_1
+ * @param {number} input_2
+ * @param {Uint8Array} secret
+ * @param {number} secret_offset
+ * @param {bigint} seed
+ */
+function mix32b(acc, input, input_1, input_2, secret, secret_offset, seed) {
+    acc.low64 = add64(acc.low64, xxh3_mix16b(input, input_1, secret, secret_offset, seed));
+    acc.low64 = acc.low64 ^ add64(read_u64(input, input_2), read_u64(input, input_2 + 8));
+
+    acc.high64 = add64(acc.high64, xxh3_mix16b(input, input_2, secret, secret_offset + 16, seed));
+    acc.high64 = acc.high64 ^ add64(read_u64(input, input_1), read_u64(input, input_1 + 8));
+}
+
+/**
+ * The shared tail of both mid-size paths.
+ *
+ * @param {XXH128Hash} acc
+ * @param {number} len
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function finalize_midsize(acc, len, seed) {
+    const low64 = xxh3_avalanche(add64(acc.low64, acc.high64));
+
+    const high64 = xxh3_avalanche(add64(
+        add64(mul64(acc.low64, XXH_PRIME64_1), mul64(acc.high64, XXH_PRIME64_4)),
+        mul64(sub64(BigInt(len), seed), XXH_PRIME64_2)
+    ));
+
+    return new XXH128Hash(low64, sub64(0n, high64));
+}
+
+/**
+ * @param {Uint8Array} input 17..128 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_17to128(input, secret, seed) {
+    const len = input.length;
+
+    const acc = new XXH128Hash(mul64(BigInt(len), XXH_PRIME64_1), 0n);
+
+    if (len > 32) {
+        if (len > 64) {
+            if (len > 96) {
+                mix32b(acc, input, 48, len - 64, secret, 96, seed);
+            }
+
+            mix32b(acc, input, 32, len - 48, secret, 64, seed);
+        }
+
+        mix32b(acc, input, 16, len - 32, secret, 32, seed);
+    }
+
+    mix32b(acc, input, 0, len - 16, secret, 0, seed);
+
+    return finalize_midsize(acc, len, seed);
+}
+
+/**
+ * @param {Uint8Array} input 129..240 bytes
+ * @param {Uint8Array} secret
+ * @param {bigint} seed
+ * @returns {XXH128Hash}
+ */
+function len_129to240(input, secret, seed) {
+    const len = input.length;
+
+    const acc = new XXH128Hash(mul64(BigInt(len), XXH_PRIME64_1), 0n);
+
+    for (let i = 32; i < 160; i += 32) {
+        mix32b(acc, input, i - 32, i - 16, secret, i - 32, seed);
+    }
+
+    acc.low64 = xxh3_avalanche(acc.low64);
+    acc.high64 = xxh3_avalanche(acc.high64);
+
+    for (let i = 160; i <= len; i += 32) {
+        mix32b(acc, input, i - 32, i - 16, secret, XXH3_MIDSIZE_STARTOFFSET + i - 160, seed);
+    }
+
+    mix32b(
+        acc,
+        input, len - 16, len - 32,
+        secret, XXH3_SECRET_SIZE_MIN - XXH3_MIDSIZE_LASTOFFSET - 16,
+        sub64(0n, seed)
+    );
+
+    return finalize_midsize(acc, len, seed);
+}
+
+/**
+ * @param {Uint8Array} input more than {@link XXH3_MIDSIZE_MAX} bytes
+ * @param {Uint8Array} secret
+ * @returns {XXH128Hash}
+ */
+function hash_long(input, secret) {
+    const acc = xxh3_init_acc();
+
+    xxh3_hash_long_loop(acc, input, secret);
+
+    const len = BigInt(input.length);
+
+    const low64 = xxh3_merge_accs(
+        acc,
+        secret, XXH_SECRET_MERGEACCS_START,
+        mul64(len, XXH_PRIME64_1)
+    );
+
+    const high64 = xxh3_merge_accs(
+        acc,
+        secret, secret.length - XXH_STRIPE_LEN - XXH_SECRET_MERGEACCS_START,
+        XXH_MASK_64 ^ mul64(len, XXH_PRIME64_2)
+    );
+
+    return new XXH128Hash(low64, high64);
+}
+
+/**
+ * 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, seed = 0n) {
+    xxh3_assert_arguments(input, seed);
+
+    const len = input.length;
+
+    if (len <= 16) {
+        return len_0to16(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= 128) {
+        return len_17to128(input, XXH3_SECRET, seed);
+    }
+
+    if (len <= XXH3_MIDSIZE_MAX) {
+        return len_129to240(input, XXH3_SECRET, seed);
+    }
+
+    return hash_long(input, xxh3_long_secret(seed));
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Hash `input` to a 64-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 {bigint} in `[0, 2^64)`
+ */
+export function xxh3_64(input: Uint8Array, seed?: bigint): bigint;
+//# sourceMappingURL=xxh3_64.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"xxh3_64.d.ts","sourceRoot":"","sources":["../../../../../src/core/math/hash/xxh3_64.js"],"names":[],"mappings":"AAuNA;;;;;;GAMG;AACH,+BAJW,UAAU,SACV,MAAM,GACJ,MAAM,CAoBlB"}