@woosh/meep-engine 3.14.1 → 3.14.3

package/src/core/binary/zstd/zstd_fse.js

@@ -0,0 +1,265 @@
+/**
+ * One Finite State Entropy decoding table.
+ *
+ * Three parallel arrays rather than an array of objects: a table has up to 512 entries and every
+ * symbol decoded reads all three, so the shape that avoids an object per state is worth the noise.
+ *
+ * @typedef {object} ZstdFseTable
+ * @property {number} accuracy_log base-2 logarithm of the table size, and the width of an initial
+ * state read
+ * @property {Uint8Array} symbol what each state decodes to
+ * @property {Uint8Array} bits how many to read to reach the next state
+ * @property {Uint16Array} baseline what to add them to
+ */
+
+/**
+ * Build a decoding table from a normalised distribution.
+ *
+ * **The allocation order is the format, not a choice.** States are handed out by stepping a position
+ * through the table with a stride that visits every slot exactly once, so a symbol's states are
+ * spread rather than contiguous. Symbols with the "less than one" probability are placed first, from
+ * the end of the table backwards, and skipped over by the stepping. Getting either wrong builds a
+ * table that decodes plausible garbage rather than failing.
+ *
+ * @param {Int16Array|number[]} counts normalised probability per symbol, `-1` meaning "less than one"
+ * @param {number} symbol_count how many of `counts` are present
+ * @param {number} accuracy_log
+ * @returns {ZstdFseTable}
+ *
+ * @see RFC 8878, section 4.1.1
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function zstd_build_fse_table(counts, symbol_count, accuracy_log) {
+    const size = 1 << accuracy_log;
+
+    const symbol = new Uint8Array(size);
+    const bits = new Uint8Array(size);
+    const baseline = new Uint16Array(size);
+
+    /*
+     A "less than one" symbol gets a single state, taken from the end of the table backwards, and
+     that state resets the decoder to a full read of `accuracy_log` bits.
+    */
+    let low_slot = size;
+
+    for (let s = 0; s < symbol_count; s++) {
+        if (counts[s] === -1) {
+            low_slot--;
+
+            symbol[low_slot] = s;
+            bits[low_slot] = accuracy_log;
+            baseline[low_slot] = 0;
+        }
+    }
+
+    /*
+     The stride visits every slot of a power-of-two table exactly once — it is odd relative to the
+     table size — which is what spreads a symbol's states instead of clustering them.
+    */
+    const step = (size >> 1) + (size >> 3) + 3;
+    const mask = size - 1;
+
+    let position = 0;
+
+    for (let s = 0; s < symbol_count; s++) {
+        const count = counts[s];
+
+        for (let i = 0; i < count; i++) {
+            symbol[position] = s;
+
+            do {
+                position = (position + step) & mask;
+            } while (position >= low_slot);
+        }
+    }
+
+    if (position !== 0) {
+        throw new Error(
+            "zstd: an FSE distribution did not fill its table exactly, so its probabilities do not"
+            + " sum to the accuracy log's scale"
+        );
+    }
+
+    /*
+     Now that each state knows its symbol, the states of one symbol are numbered in their natural
+     order and given widths: the lower ones take an extra bit so the widths sum to the table size.
+    */
+    const next = new Uint16Array(symbol_count);
+
+    for (let s = 0; s < symbol_count; s++) {
+        next[s] = counts[s] === -1 ? 1 : counts[s];
+    }
+
+    /*
+     The "less than one" states need no special case here: their counter starts at one, which makes
+     the width below the full accuracy log and the baseline zero — exactly the reset they were placed
+     for. Writing that as a branch would be a second statement of the same arithmetic.
+    */
+    for (let state = 0; state < size; state++) {
+        const value = next[symbol[state]]++;
+
+        bits[state] = accuracy_log - (31 - Math.clz32(value));
+        baseline[state] = ((value << bits[state]) - size) & 0xFFFF;
+    }
+
+    return { accuracy_log, symbol, bits, baseline };
+}
+
+/**
+ * Read a normalised distribution and build its table.
+ *
+ * The distribution is read *forward* in little-endian order, unlike the streams the table then
+ * decodes — it is a header rather than an entropy-coded body.
+ *
+ * @param {Uint8Array} data
+ * @param {number} offset
+ * @param {number} end one past the last readable byte
+ * @param {number} max_symbol the largest symbol the context allows
+ * @param {number} max_accuracy_log the largest the context allows
+ * @returns {{table: ZstdFseTable, byte_length: number}}
+ * @throws {Error} for a distribution that overruns its scale or its symbol range
+ */
+export function zstd_read_fse_table(data, offset, end, max_symbol, max_accuracy_log) {
+    let bit = 0;
+
+    /**
+     * @param {number} count
+     * @returns {number}
+     */
+    const peek = count => {
+        let value = 0;
+
+        for (let i = 0; i < count; i++) {
+            const at = offset + ((bit + i) >> 3);
+
+            if (at >= end) {
+                continue;
+            }
+
+            value |= ((data[at] >> ((bit + i) & 7)) & 1) << i;
+        }
+
+        return value;
+    };
+
+    const accuracy_log = (peek(4) & 15) + 5;
+
+    bit += 4;
+
+    if (accuracy_log > max_accuracy_log) {
+        throw new Error(
+            `zstd: an FSE distribution declares an accuracy log of ${accuracy_log}, and this table`
+            + ` allows at most ${max_accuracy_log}`
+        );
+    }
+
+    const size = 1 << accuracy_log;
+
+    const counts = new Int16Array(max_symbol + 1);
+
+    /*
+     **The field width is not recomputed per symbol; it shrinks with a running threshold.** As the
+     unallocated probability falls, so does the number of values a count could take, and the format
+     tracks that with a threshold that halves — spending one bit fewer each time it does. Deriving
+     the width from `remaining` afresh looks equivalent and is not, because the halving lags: it
+     happens only once `remaining` has fallen below the current threshold, so a distribution reads
+     correctly only if the decoder shrinks in the same steps the encoder grew.
+    */
+    let remaining = size + 1;
+    let threshold = size;
+    let width = accuracy_log + 1;
+
+    let symbol = 0;
+    let previous_zero = false;
+
+    while (remaining > 1 && symbol <= max_symbol) {
+        if (previous_zero) {
+            /*
+             A zero count is followed by a two-bit run of further zeroes, and a run of three means
+             another such field follows — so a long stretch of unused symbols costs two bits per
+             three rather than a field each.
+            */
+            let run = 0;
+
+            for (; ;) {
+                const chunk = peek(2);
+
+                bit += 2;
+
+                run += chunk;
+
+                if (chunk !== 3) {
+                    break;
+                }
+            }
+
+            for (let i = 0; i < run && symbol <= max_symbol; i++) {
+                counts[symbol++] = 0;
+            }
+
+            previous_zero = false;
+
+            continue;
+        }
+
+        const max = (2 * threshold - 1) - remaining;
+
+        const value = peek(width);
+
+        let count;
+
+        if ((value & (threshold - 1)) < max) {
+            count = value & (threshold - 1);
+            bit += width - 1;
+        } else {
+            count = value & (2 * threshold - 1);
+
+            if (count >= threshold) {
+                count -= max;
+            }
+
+            bit += width;
+        }
+
+        // one is subtracted so that zero can mean the "less than one" probability
+        count--;
+
+        remaining -= count < 0 ? -count : count;
+
+        counts[symbol++] = count;
+
+        previous_zero = count === 0;
+
+        while (remaining < threshold) {
+            width--;
+            threshold >>= 1;
+        }
+    }
+
+    if (remaining !== 1) {
+        throw new Error(
+            "zstd: an FSE distribution's probabilities do not sum to its declared scale"
+        );
+    }
+
+    return {
+        table: zstd_build_fse_table(counts, symbol, accuracy_log),
+        byte_length: (bit + 7) >> 3,
+    };
+}
+
+/**
+ * A table for a stream that carries one symbol over and over.
+ *
+ * @param {number} value
+ * @returns {ZstdFseTable}
+ */
+export function zstd_rle_fse_table(value) {
+    return {
+        accuracy_log: 0,
+        symbol: Uint8Array.from([value]),
+        bits: Uint8Array.from([0]),
+        baseline: Uint16Array.from([0]),
+    };
+}

package/src/core/binary/zstd/zstd_huffman.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Read a Huffman tree description and build its table.
+ *
+ * The weights are themselves either written out at four bits each or FSE-coded — and the FSE case
+ * runs *two interleaved states over one distribution*, one taking the even-indexed weights and one
+ * the odd, which is the only place in the format that does so.
+ *
+ * @param {Uint8Array} data
+ * @param {number} offset
+ * @param {number} end one past the last readable byte
+ * @returns {{table: ZstdHuffmanTable, byte_length: number}}
+ * @throws {Error} for a description that runs past `end` or does not describe a valid tree
+ *
+ * @see RFC 8878, section 4.2.1
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function zstd_read_huffman_table(data: Uint8Array, offset: number, end: number): {
+    table: ZstdHuffmanTable;
+    byte_length: number;
+};
+/**
+ * Decode one Huffman-coded stream into `out`.
+ *
+ * @param {ZstdHuffmanTable} table
+ * @param {Uint8Array} data
+ * @param {number} offset
+ * @param {number} byte_length
+ * @param {Uint8Array} out
+ * @param {number} out_offset
+ * @param {number} count symbols to produce
+ * @throws {Error} for a stream that does not end exactly where its symbols run out
+ */
+export function zstd_decode_huffman_stream(table: ZstdHuffmanTable, data: Uint8Array, offset: number, byte_length: number, out: Uint8Array, out_offset: number, count: number): void;
+/**
+ * A Huffman decoding table for literals, as a flat lookup over the widest code.
+ *
+ * Every code is padded out to {@link MAX_CODE_BITS } and every padding of it points at the same
+ * symbol, so decoding is one array read and a subtraction rather than a walk. A table is 2048 entries
+ * and is built once per block at most.
+ */
+export type ZstdHuffmanTable = {
+    /**
+     * the widest code actually present
+     */
+    max_bits: number;
+    /**
+     * indexed by the next `max_bits` bits
+     */
+    symbol: Uint8Array;
+    /**
+     * how many of them the code actually used
+     */
+    bits: Uint8Array;
+};
+//# sourceMappingURL=zstd_huffman.d.ts.map

package/src/core/binary/zstd/zstd_huffman.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd_huffman.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/zstd/zstd_huffman.js"],"names":[],"mappings":"AAoHA;;;;;;;;;;;;;;;;GAgBG;AACH,8CAVW,UAAU,UACV,MAAM,OACN,MAAM,GACJ;IAAC,KAAK,EAAE,gBAAgB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAC,CAuF1D;AAED;;;;;;;;;;;GAWG;AACH,kDATW,gBAAgB,QAChB,UAAU,UACV,MAAM,eACN,MAAM,OACN,UAAU,cACV,MAAM,SACN,MAAM,QAmBhB;;;;;;;;;;;;cAxNa,MAAM;;;;YACN,UAAU;;;;UACV,UAAU"}

package/src/core/binary/zstd/zstd_huffman.js

@@ -0,0 +1,244 @@
+import { ZstdReverseBitReader } from "./ZstdReverseBitReader.js";
+import { zstd_read_fse_table } from "./zstd_fse.js";
+
+/**
+ * The widest Huffman code Zstandard allows for literals.
+ *
+ * @readonly
+ * @type {number}
+ */
+const MAX_CODE_BITS = 11;
+
+/**
+ * The widest accuracy log an FSE table coding Huffman weights may declare.
+ *
+ * @readonly
+ * @type {number}
+ */
+const WEIGHT_MAX_ACCURACY_LOG = 6;
+
+/**
+ * A Huffman decoding table for literals, as a flat lookup over the widest code.
+ *
+ * Every code is padded out to {@link MAX_CODE_BITS} and every padding of it points at the same
+ * symbol, so decoding is one array read and a subtraction rather than a walk. A table is 2048 entries
+ * and is built once per block at most.
+ *
+ * @typedef {object} ZstdHuffmanTable
+ * @property {number} max_bits the widest code actually present
+ * @property {Uint8Array} symbol indexed by the next `max_bits` bits
+ * @property {Uint8Array} bits how many of them the code actually used
+ */
+
+/**
+ * Turn a set of per-symbol weights into a decoding table.
+ *
+ * A weight is a *rank*, not a code length: a symbol of weight `w` gets a code of
+ * `max_weight + 1 - w` bits, so the largest weight is the shortest code. Codes are then handed out
+ * shortest-last — sorted by weight, and by symbol within a weight — which is what makes the
+ * assignment canonical and the encoder's and decoder's agree.
+ *
+ * @param {Uint8Array} weights one per symbol
+ * @param {number} count how many symbols `weights` describes
+ * @returns {ZstdHuffmanTable}
+ * @throws {Error} for weights whose implied code space is not exactly filled
+ */
+function table_from_weights(weights, count) {
+    let total = 0;
+
+    for (let i = 0; i < count; i++) {
+        if (weights[i] > 0) {
+            total += 1 << (weights[i] - 1);
+        }
+    }
+
+    if (total === 0) {
+        throw new Error("zstd: a Huffman table describes no symbols");
+    }
+
+    /*
+     The last symbol's weight is not transmitted. It is whatever fills the code space to the next
+     power of two — which is why the encoder can leave it out, and why a corrupt weight set shows up
+     here as a total that is already past that power.
+    */
+    const max_bits = 32 - Math.clz32(total);
+    const last = (1 << max_bits) - total;
+
+    if (last === 0 || (last & (last - 1)) !== 0) {
+        throw new Error(
+            "zstd: a Huffman weight set leaves a code space the final symbol cannot fill"
+        );
+    }
+
+    const all = new Uint8Array(count + 1);
+
+    all.set(weights.subarray(0, count));
+
+    all[count] = 32 - Math.clz32(last);
+
+    const symbol_count = count + 1;
+
+    const size = 1 << max_bits;
+
+    const symbol = new Uint8Array(size);
+    const bits = new Uint8Array(size);
+
+    /*
+     Codes are assigned by ascending weight — so descending code length — and by symbol within a
+     weight. Filling the table means writing every padding of a code, which is what turns the decode
+     into a single lookup.
+    */
+    let position = 0;
+
+    for (let weight = 1; weight <= max_bits; weight++) {
+        const length = max_bits + 1 - weight;
+
+        for (let s = 0; s < symbol_count; s++) {
+            if (all[s] !== weight) {
+                continue;
+            }
+
+            const span = 1 << (max_bits - length);
+
+            symbol.fill(s, position, position + span);
+            bits.fill(length, position, position + span);
+
+            position += span;
+        }
+    }
+
+    if (position !== size) {
+        throw new Error("zstd: a Huffman weight set does not fill its code space exactly");
+    }
+
+    return { max_bits, symbol, bits };
+}
+
+/**
+ * Read a Huffman tree description and build its table.
+ *
+ * The weights are themselves either written out at four bits each or FSE-coded — and the FSE case
+ * runs *two interleaved states over one distribution*, one taking the even-indexed weights and one
+ * the odd, which is the only place in the format that does so.
+ *
+ * @param {Uint8Array} data
+ * @param {number} offset
+ * @param {number} end one past the last readable byte
+ * @returns {{table: ZstdHuffmanTable, byte_length: number}}
+ * @throws {Error} for a description that runs past `end` or does not describe a valid tree
+ *
+ * @see RFC 8878, section 4.2.1
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function zstd_read_huffman_table(data, offset, end) {
+    const header = data[offset];
+
+    const weights = new Uint8Array(255);
+
+    if (header >= 128) {
+        // written out, two weights to a byte, the first in the high nibble
+        const count = header - 127;
+
+        for (let i = 0; i < count; i++) {
+            const byte = data[offset + 1 + (i >> 1)];
+
+            weights[i] = (i & 1) === 0 ? (byte >> 4) : (byte & 15);
+        }
+
+        return {
+            table: table_from_weights(weights, count),
+            byte_length: 1 + ((count + 1) >> 1),
+        };
+    }
+
+    const compressed_end = offset + 1 + header;
+
+    if (compressed_end > end) {
+        throw new Error(
+            `zstd: a Huffman tree description claims ${header} bytes and only`
+            + ` ${end - offset - 1} remain in the block`
+        );
+    }
+
+    const { table: fse, byte_length: fse_bytes } = zstd_read_fse_table(
+        data, offset + 1, compressed_end, 255, WEIGHT_MAX_ACCURACY_LOG
+    );
+
+    const reader = new ZstdReverseBitReader().init(
+        data, offset + 1 + fse_bytes, header - fse_bytes
+    );
+
+    let state1 = reader.read(fse.accuracy_log);
+    let state2 = reader.read(fse.accuracy_log);
+
+    let count = 0;
+
+    /*
+     **The number of weights is not transmitted; running out of bits is what ends the stream.** Each
+     turn takes the symbol the state currently names and *then* advances that state, which is the
+     order every FSE decode uses — and the advance is allowed to read past the start of the stream,
+     where the reader supplies zeros. Once it has, the other state's pending symbol is taken and the
+     description is complete.
+
+     Checking before the advance instead, or checking whether the *other* state could advance, both
+     produce a weight set that is right for most of its length and wrong near the end.
+    */
+    for (; ;) {
+        if (count >= 254) {
+            throw new Error("zstd: a Huffman tree description codes more than 255 weights");
+        }
+
+        weights[count++] = fse.symbol[state1];
+
+        state1 = fse.baseline[state1] + reader.read(fse.bits[state1]);
+
+        if (reader.remaining < 0) {
+            weights[count++] = fse.symbol[state2];
+
+            break;
+        }
+
+        weights[count++] = fse.symbol[state2];
+
+        state2 = fse.baseline[state2] + reader.read(fse.bits[state2]);
+
+        if (reader.remaining < 0) {
+            weights[count++] = fse.symbol[state1];
+
+            break;
+        }
+    }
+
+    return { table: table_from_weights(weights, count), byte_length: 1 + header };
+}
+
+/**
+ * Decode one Huffman-coded stream into `out`.
+ *
+ * @param {ZstdHuffmanTable} table
+ * @param {Uint8Array} data
+ * @param {number} offset
+ * @param {number} byte_length
+ * @param {Uint8Array} out
+ * @param {number} out_offset
+ * @param {number} count symbols to produce
+ * @throws {Error} for a stream that does not end exactly where its symbols run out
+ */
+export function zstd_decode_huffman_stream(
+    table, data, offset, byte_length, out, out_offset, count
+) {
+    const reader = new ZstdReverseBitReader().init(data, offset, byte_length);
+
+    for (let i = 0; i < count; i++) {
+        /*
+         The lookup is over the widest code, so what is peeked is a code plus whatever followed it.
+         The table says how many of those bits the code actually was, and only those are consumed.
+        */
+        const index = reader.peek(table.max_bits);
+
+        out[out_offset + i] = table.symbol[index];
+
+        reader.consume(table.bits[index]);
+    }
+}

package/src/core/binary/zstd/zstd_sequence_tables.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The baselines and extra-bit widths a literals-length code stands for.
+ *
+ * Codes 0 to 15 are the length itself; past that the lengths grow geometrically with the extra bits
+ * making up the difference.
+ *
+ * @readonly
+ * @type {{baseline: Uint32Array, bits: Uint8Array}}
+ */
+export const LITERALS_LENGTH_CODE: {
+    baseline: Uint32Array;
+    bits: Uint8Array;
+};
+/**
+ * The same for match lengths, whose codes 0 to 31 are the length less three — a match is never
+ * shorter than three bytes, so the format does not spend codes saying so.
+ *
+ * @readonly
+ * @type {{baseline: Uint32Array, bits: Uint8Array}}
+ */
+export const MATCH_LENGTH_CODE: {
+    baseline: Uint32Array;
+    bits: Uint8Array;
+};
+/**
+ * The distribution used when a block says its literals lengths are coded the predefined way.
+ *
+ * A `-1` is the format's "less than one" probability: the symbol is possible but rare enough that a
+ * normalised count of zero would have removed it.
+ *
+ * @readonly
+ * @type {number[]}
+ */
+export const LITERALS_LENGTH_DEFAULT: number[];
+/**
+ * @readonly
+ * @type {number[]}
+ */
+export const MATCH_LENGTH_DEFAULT: number[];
+/**
+ * @readonly
+ * @type {number[]}
+ */
+export const OFFSET_DEFAULT: number[];
+/**
+ * Accuracy logs the predefined distributions are defined at.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const LITERALS_LENGTH_DEFAULT_LOG: number;
+/**
+ * @readonly
+ * @type {number}
+ */
+export const MATCH_LENGTH_DEFAULT_LOG: number;
+/**
+ * @readonly
+ * @type {number}
+ */
+export const OFFSET_DEFAULT_LOG: number;
+//# sourceMappingURL=zstd_sequence_tables.d.ts.map

package/src/core/binary/zstd/zstd_sequence_tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd_sequence_tables.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/zstd/zstd_sequence_tables.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,mCAFU;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAajD;AAEF;;;;;;GAMG;AACH,gCAFU;IAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAC,CAejD;AAEF;;;;;;;;GAQG;AACH,sCAFU,MAAM,EAAE,CAMhB;AAEF;;;GAGG;AACH,mCAFU,MAAM,EAAE,CAOhB;AAEF;;;GAGG;AACH,6BAFU,MAAM,EAAE,CAKhB;AAEF;;;;;GAKG;AACH,0CAFU,MAAM,CAE6B;AAE7C;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,iCAFU,MAAM,CAEoB"}