@woosh/meep-engine 3.60.6 → 3.60.7

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

@@ -1,265 +1,267 @@
-/**
- * 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]),
-    };
-}
+import { msb_32 } from "../msb_32.js";
+
+/**
+ * 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 - msb_32(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.map

@@ -1 +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"}
+{"version":3,"file":"zstd_huffman.d.ts","sourceRoot":"","sources":["../../../../../src/core/binary/zstd/zstd_huffman.js"],"names":[],"mappings":"AAsHA;;;;;;;;;;;;;;;;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"}