@woosh/meep-engine 3.14.0 → 3.14.2

package/src/basis/BasisHuffmanTable.js

@@ -0,0 +1,263 @@
+import { BasisBitReader } from "./BasisBitReader.js";
+
+/**
+ * Longest code the format permits, from the specification's `cHuffmanMaxSupportedCodeSize`.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const HUFFMAN_MAX_CODE_SIZE = 16;
+
+/**
+ * Most symbols a table may describe, from the specification's `cHuffmanMaxSyms` — `1 << 14`.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const HUFFMAN_MAX_SYMBOLS = 1 << 14;
+
+/**
+ * Bits the fast lookup covers. A code no longer than this is decoded by one array read.
+ *
+ * Ten is the reference decoder's choice and a reasonable one: the table costs 1024 entries per
+ * Huffman table, and the codes that miss it are by construction the rare symbols.
+ *
+ * @readonly
+ * @type {number}
+ */
+const FAST_LOOKUP_BITS = 10;
+
+/**
+ * Bits of a {@link BasisHuffmanTable#fast} entry given over to the code length, which is at most
+ * {@link HUFFMAN_MAX_CODE_SIZE} and so needs five.
+ *
+ * @readonly
+ * @type {number}
+ */
+const FAST_LENGTH_BITS = 5;
+
+/**
+ * A canonical Huffman decoding table, built from per-symbol code lengths.
+ *
+ * **Canonical in the Deflate sense**, which the specification says outright: codes are assigned in
+ * order of increasing length and, within a length, increasing symbol. What differs from Deflate is
+ * only where the bits come from — {@link BasisBitReader} hands them over least significant first, so
+ * a code appears in the stream with its bits reversed, and the fast table is indexed by that
+ * reversal.
+ *
+ * **Incomplete tables are legal.** The specification calls out the single-symbol case explicitly —
+ * one symbol with a one-bit code, assigned the code zero, leaving half the code space unused. So an
+ * under-full table is built rather than refused, and only a code that actually lands in the unused
+ * space throws.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BasisHuffmanTable {
+    /**
+     * `(symbol << FAST_LENGTH_BITS) | code_length` for each of the `1 << FAST_LOOKUP_BITS` possible
+     * peeks, or `0` where no code of at most {@link FAST_LOOKUP_BITS} bits starts with those bits.
+     *
+     * Packed into one array rather than two because it is read once per symbol on the hottest path
+     * in the transcoder.
+     *
+     * @type {Int32Array}
+     */
+    #fast = null;
+
+    /**
+     * Number of codes of each length, indexed by length. Entry 0 is unused.
+     * @type {Int32Array}
+     */
+    #length_count = null;
+
+    /**
+     * Smallest canonical code of each length, most significant bit first.
+     * @type {Int32Array}
+     */
+    #first_code = null;
+
+    /**
+     * Index into {@link #sorted_symbols} of the first symbol of each length.
+     * @type {Int32Array}
+     */
+    #first_index = null;
+
+    /**
+     * Symbols with a non-zero code length, ordered by length then by symbol — which is the order
+     * canonical codes are assigned in, so a code's rank within its length indexes straight into it.
+     * @type {Int32Array}
+     */
+    #sorted_symbols = null;
+
+    /**
+     * Build the table from an array of per-symbol code lengths, `0` meaning "symbol not used".
+     *
+     * @param {Uint8Array} code_lengths
+     * @returns {BasisHuffmanTable} this
+     * @throws {Error} for a length past the format's maximum, or a set of lengths that
+     * over-subscribes the code space
+     */
+    init(code_lengths) {
+        const symbol_count = code_lengths.length;
+
+        const length_count = new Int32Array(HUFFMAN_MAX_CODE_SIZE + 1);
+
+        for (let symbol = 0; symbol < symbol_count; symbol++) {
+            const length = code_lengths[symbol];
+
+            if (length > HUFFMAN_MAX_CODE_SIZE) {
+                throw new Error(
+                    `Basis: a Huffman symbol declares a code length of ${length} bits, and the`
+                    + ` format's longest code is ${HUFFMAN_MAX_CODE_SIZE}`
+                );
+            }
+
+            length_count[length]++;
+        }
+
+        // a length of zero means "unused", not "a zero-bit code", so it takes no code space
+        length_count[0] = 0;
+
+        const first_code = new Int32Array(HUFFMAN_MAX_CODE_SIZE + 2);
+        const first_index = new Int32Array(HUFFMAN_MAX_CODE_SIZE + 2);
+
+        let code = 0;
+        let index = 0;
+
+        for (let length = 1; length <= HUFFMAN_MAX_CODE_SIZE; length++) {
+            first_code[length] = code;
+            first_index[length] = index;
+
+            code += length_count[length];
+            index += length_count[length];
+
+            /*
+             After absorbing every code of this length, `code` counts the codes that would exist if
+             the tree were full at this depth. More than that means two symbols were handed the same
+             prefix, which is a corrupt table rather than an unusual one — unlike the under-full case
+             the specification explicitly permits.
+            */
+            if (code > (1 << length)) {
+                throw new Error(
+                    `Basis: the Huffman code lengths over-subscribe the code space at length`
+                    + ` ${length}, so no canonical table can be built from them`
+                );
+            }
+
+            code <<= 1;
+        }
+
+        const sorted_symbols = new Int32Array(index);
+        const next_index = first_index.slice();
+
+        for (let symbol = 0; symbol < symbol_count; symbol++) {
+            const length = code_lengths[symbol];
+
+            if (length !== 0) {
+                sorted_symbols[next_index[length]++] = symbol;
+            }
+        }
+
+        this.#length_count = length_count;
+        this.#first_code = first_code;
+        this.#first_index = first_index;
+        this.#sorted_symbols = sorted_symbols;
+
+        this.#build_fast_lookup(code_lengths, symbol_count);
+
+        return this;
+    }
+
+    /**
+     * Fill {@link #fast} so a peek of {@link FAST_LOOKUP_BITS} bits resolves any short code without
+     * walking the tree.
+     *
+     * @param {Uint8Array} code_lengths
+     * @param {number} symbol_count
+     */
+    #build_fast_lookup(code_lengths, symbol_count) {
+        const fast = new Int32Array(1 << FAST_LOOKUP_BITS);
+
+        const next_code = this.#first_code.slice();
+
+        for (let symbol = 0; symbol < symbol_count; symbol++) {
+            const length = code_lengths[symbol];
+
+            if (length === 0) {
+                continue;
+            }
+
+            const canonical = next_code[length]++;
+
+            if (length > FAST_LOOKUP_BITS) {
+                // left to the slow path, which rebuilds the code as it reads rather than tabulating
+                continue;
+            }
+
+            /*
+             The stream hands bits over least significant first, so a code arrives reversed within
+             its own width. Every peek whose low `length` bits match that reversal decodes to this
+             symbol, whatever the bits above happen to be — which is what the stride fills in.
+            */
+            let reversed = 0;
+
+            for (let bit = 0; bit < length; bit++) {
+                reversed |= ((canonical >>> (length - 1 - bit)) & 1) << bit;
+            }
+
+            const packed = (symbol << FAST_LENGTH_BITS) | length;
+
+            for (let i = reversed; i < fast.length; i += 1 << length) {
+                fast[i] = packed;
+            }
+        }
+
+        this.#fast = fast;
+    }
+
+    /**
+     * Read one symbol.
+     *
+     * @param {BasisBitReader} reader
+     * @returns {number} the symbol
+     * @throws {Error} for a prefix that matches no code in the table
+     */
+    decode(reader) {
+        const packed = this.#fast[reader.peek(FAST_LOOKUP_BITS)];
+
+        if (packed !== 0) {
+            reader.consume(packed & ((1 << FAST_LENGTH_BITS) - 1));
+
+            return packed >>> FAST_LENGTH_BITS;
+        }
+
+        /*
+         Either a code longer than the fast lookup covers, or one that is not in the table at all.
+         Rebuild it a bit at a time, most significant first, which is the order canonical codes
+         compare in.
+        */
+        let code = 0;
+
+        for (let length = 1; length <= HUFFMAN_MAX_CODE_SIZE; length++) {
+            code = (code << 1) | ((reader.peek(length) >>> (length - 1)) & 1);
+
+            const count = this.#length_count[length];
+
+            if (count !== 0) {
+                const offset = code - this.#first_code[length];
+
+                if (offset >= 0 && offset < count) {
+                    reader.consume(length);
+
+                    return this.#sorted_symbols[this.#first_index[length] + offset];
+                }
+            }
+        }
+
+        throw new Error(
+            `Basis: a ${HUFFMAN_MAX_CODE_SIZE} bit prefix matched no code in the Huffman table,`
+            + ` which means the bitstream and the table disagree`
+        );
+    }
+}

package/src/basis/basis_read_huffman_table.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Read one of the format's compressed Huffman tables.
+ *
+ * The table is described by its symbols' code lengths, and those lengths are themselves run-length
+ * and Huffman coded — the same two-level arrangement Deflate uses, which the specification says it
+ * is deliberately compatible with. So this reads a small table first, then uses it to read the
+ * lengths of the one that was asked for.
+ *
+ * @param {BasisBitReader} reader positioned at the start of the table
+ * @returns {BasisHuffmanTable}
+ * @throws {Error} naming the field, for a table whose header or code lengths are not self-consistent
+ * @see the specification, section 6.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function basis_read_huffman_table(reader: BasisBitReader): BasisHuffmanTable;
+import { BasisBitReader } from "./BasisBitReader.js";
+import { BasisHuffmanTable } from "./BasisHuffmanTable.js";
+//# sourceMappingURL=basis_read_huffman_table.d.ts.map

package/src/basis/basis_read_huffman_table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"basis_read_huffman_table.d.ts","sourceRoot":"","sources":["../../../src/basis/basis_read_huffman_table.js"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;;;GAeG;AACH,iDARW,cAAc,GACZ,iBAAiB,CAqG7B;+BA1L8B,qBAAqB;kCAK7C,wBAAwB"}

package/src/basis/basis_read_huffman_table.js

@@ -0,0 +1,187 @@
+import { BasisBitReader } from "./BasisBitReader.js";
+import {
+    BasisHuffmanTable,
+    HUFFMAN_MAX_CODE_SIZE,
+    HUFFMAN_MAX_SYMBOLS
+} from "./BasisHuffmanTable.js";
+
+/**
+ * Symbols in the little table that codes the big table's code lengths: the seventeen lengths
+ * `[0, 16]` plus four run codes. The specification's `cHuffmanTotalCodelengthCodes`.
+ *
+ * @readonly
+ * @type {number}
+ */
+const CODELENGTH_CODE_COUNT = 21;
+
+/**
+ * A run of symbols with no code, three to ten long. The specification's `cHuffmanSmallZeroRunCode`.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SMALL_ZERO_RUN_CODE = 17;
+
+/**
+ * A run of symbols with no code, eleven to a hundred and thirty-eight long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BIG_ZERO_RUN_CODE = 18;
+
+/**
+ * A run repeating the previous symbol's code length, three to six long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const SMALL_REPEAT_CODE = 19;
+
+/**
+ * A run repeating the previous symbol's code length, seven to a hundred and thirty-four long.
+ *
+ * @readonly
+ * @type {number}
+ */
+const BIG_REPEAT_CODE = 20;
+
+/**
+ * Extra bits, and the minimum the run may be, for each of the four run codes — indexed by the code
+ * itself so the decode loop reads them rather than branching four ways.
+ *
+ * @readonly
+ * @type {Object<number, {extra_bits: number, minimum: number}>}
+ */
+const RUNS = {
+    [SMALL_ZERO_RUN_CODE]: { extra_bits: 3, minimum: 3 },
+    [BIG_ZERO_RUN_CODE]: { extra_bits: 7, minimum: 11 },
+    [SMALL_REPEAT_CODE]: { extra_bits: 2, minimum: 3 },
+    [BIG_REPEAT_CODE]: { extra_bits: 7, minimum: 7 },
+};
+
+/**
+ * The order the code lengths of the little table arrive in.
+ *
+ * Not sorted, and not arbitrary: the run codes come first and the ordinary lengths radiate outward
+ * from eight, so the lengths a typical table never uses cluster at the end and can be left unsent.
+ *
+ * @readonly
+ * @type {number[]}
+ */
+const CODELENGTH_CODE_ORDER = [
+    SMALL_ZERO_RUN_CODE, BIG_ZERO_RUN_CODE, SMALL_REPEAT_CODE, BIG_REPEAT_CODE,
+    0, 8, 7, 9, 6, 0xA, 5, 0xB, 4, 0xC, 3, 0xD, 2, 0xE, 1, 0xF, 0x10,
+];
+
+/**
+ * Read one of the format's compressed Huffman tables.
+ *
+ * The table is described by its symbols' code lengths, and those lengths are themselves run-length
+ * and Huffman coded — the same two-level arrangement Deflate uses, which the specification says it
+ * is deliberately compatible with. So this reads a small table first, then uses it to read the
+ * lengths of the one that was asked for.
+ *
+ * @param {BasisBitReader} reader positioned at the start of the table
+ * @returns {BasisHuffmanTable}
+ * @throws {Error} naming the field, for a table whose header or code lengths are not self-consistent
+ * @see the specification, section 6.0
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function basis_read_huffman_table(reader) {
+    const total_used_syms = reader.bits(14);
+
+    if (total_used_syms === 0 || total_used_syms > HUFFMAN_MAX_SYMBOLS) {
+        throw new Error(
+            `Basis: a Huffman table declares ${total_used_syms} symbols, and the format allows`
+            + ` 1 to ${HUFFMAN_MAX_SYMBOLS}`
+        );
+    }
+
+    const codelength_code_count = reader.bits(5);
+
+    if (codelength_code_count === 0 || codelength_code_count > CODELENGTH_CODE_COUNT) {
+        throw new Error(
+            `Basis: a Huffman table declares ${codelength_code_count} code length codes, and the`
+            + ` format allows 1 to ${CODELENGTH_CODE_COUNT}`
+        );
+    }
+
+    const codelength_code_lengths = new Uint8Array(CODELENGTH_CODE_COUNT);
+
+    for (let i = 0; i < codelength_code_count; i++) {
+        codelength_code_lengths[CODELENGTH_CODE_ORDER[i]] = reader.bits(3);
+    }
+
+    const codelength_table = new BasisHuffmanTable().init(codelength_code_lengths);
+
+    const code_lengths = new Uint8Array(total_used_syms);
+
+    let symbol = 0;
+
+    while (symbol < total_used_syms) {
+        const code = codelength_table.decode(reader);
+
+        if (code <= HUFFMAN_MAX_CODE_SIZE) {
+            code_lengths[symbol++] = code;
+
+            continue;
+        }
+
+        const run = RUNS[code];
+
+        if (run === undefined) {
+            throw new Error(
+                `Basis: a Huffman table's code length stream used symbol ${code}, and only`
+                + ` 0 to ${BIG_REPEAT_CODE} are defined`
+            );
+        }
+
+        const count = reader.bits(run.extra_bits) + run.minimum;
+
+        if (symbol + count > total_used_syms) {
+            throw new Error(
+                `Basis: a run of ${count} code lengths starting at symbol ${symbol} overruns the`
+                + ` ${total_used_syms} symbols the Huffman table declared`
+            );
+        }
+
+        const repeats = code === SMALL_REPEAT_CODE || code === BIG_REPEAT_CODE;
+
+        if (!repeats) {
+            // a zero run; the array is already zero, so the run only has to advance past it
+            symbol += count;
+
+            continue;
+        }
+
+        /*
+         The specification forbids a repeat as the first symbol, and forbids repeating a length of
+         zero — the run says "the same as the last one" and there has to be a last one for it to
+         name. Both would otherwise read as a run of unused symbols, which is what a zero run is for.
+        */
+        if (symbol === 0) {
+            throw new Error(
+                "Basis: a Huffman table's code length stream opens with a repeat run, which has no"
+                + " previous length to repeat"
+            );
+        }
+
+        const previous = code_lengths[symbol - 1];
+
+        if (previous === 0) {
+            throw new Error(
+                `Basis: a Huffman table's code length stream repeats symbol ${symbol - 1}, which has`
+                + ` no code — a zero run is how unused symbols are spelled`
+            );
+        }
+
+        code_lengths.fill(previous, symbol, symbol + count);
+
+        symbol += count;
+    }
+
+    return new BasisHuffmanTable().init(code_lengths);
+}

package/src/basis/etc1s/Etc1sSelectorHistory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The recently used selector indices, as an approximate move-to-front list.
+ *
+ * A slice refers to a selector either by its codebook index or by its position in this list, and the
+ * second is cheaper whenever a block reuses something a nearby block used — which most blocks do.
+ * What makes it *approximate* is the two shortcuts it takes over a real move-to-front transform, and
+ * both matter to a decoder because they define the state exactly:
+ *
+ * - **A used entry swaps with the one at half its index** rather than moving to the front and
+ *   shifting everything after it along. So a repeatedly used entry walks toward the front
+ *   geometrically instead of arriving in one step, and the list is never actually re-ordered.
+ * - **A new entry overwrites at a rover** that sweeps the back half of the list and wraps, rather
+ *   than pushing the oldest entry off the end.
+ *
+ * Both make the encoder's and decoder's work constant per block instead of linear in the list, which
+ * for a list of up to several thousand entries is the whole reason it is affordable at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Etc1sSelectorHistory {
+    /**
+     * @param {number} size from the slice tables section; may be zero, for a file whose blocks never
+     * refer to the history
+     */
+    constructor(size: number);
+    /**
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * @param {number} index
+     * @returns {number} the selector codebook index remembered there
+     */
+    at(index: number): number;
+    /**
+     * Remember a selector index that was referred to by its codebook index.
+     *
+     * @param {number} value
+     */
+    add(value: number): void;
+    /**
+     * Promote the entry at `index`, having just referred to it.
+     *
+     * @param {number} index
+     */
+    use(index: number): void;
+    #private;
+}
+//# sourceMappingURL=Etc1sSelectorHistory.d.ts.map

package/src/basis/etc1s/Etc1sSelectorHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Etc1sSelectorHistory.d.ts","sourceRoot":"","sources":["../../../../src/basis/etc1s/Etc1sSelectorHistory.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAaI;;;OAGG;IACH,kBAHW,MAAM,EAMhB;IAED;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,UAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;OAIG;IACH,WAFW,MAAM,QAQhB;IAED;;;;OAIG;IACH,WAFW,MAAM,QAchB;;CACJ"}

package/src/basis/etc1s/Etc1sSelectorHistory.js

@@ -0,0 +1,89 @@
+/**
+ * The recently used selector indices, as an approximate move-to-front list.
+ *
+ * A slice refers to a selector either by its codebook index or by its position in this list, and the
+ * second is cheaper whenever a block reuses something a nearby block used — which most blocks do.
+ * What makes it *approximate* is the two shortcuts it takes over a real move-to-front transform, and
+ * both matter to a decoder because they define the state exactly:
+ *
+ * - **A used entry swaps with the one at half its index** rather than moving to the front and
+ *   shifting everything after it along. So a repeatedly used entry walks toward the front
+ *   geometrically instead of arriving in one step, and the list is never actually re-ordered.
+ * - **A new entry overwrites at a rover** that sweeps the back half of the list and wraps, rather
+ *   than pushing the oldest entry off the end.
+ *
+ * Both make the encoder's and decoder's work constant per block instead of linear in the list, which
+ * for a list of up to several thousand entries is the whole reason it is affordable at all.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Etc1sSelectorHistory {
+    /**
+     * @type {Int32Array}
+     */
+    #values = null;
+
+    /**
+     * Where {@link add} writes next. Sweeps the back half of {@link #values} and wraps to its
+     * middle, so the front half is only ever reached by {@link use} promoting something into it.
+     * @type {number}
+     */
+    #rover = 0;
+
+    /**
+     * @param {number} size from the slice tables section; may be zero, for a file whose blocks never
+     * refer to the history
+     */
+    constructor(size) {
+        this.#values = new Int32Array(size);
+        this.#rover = size >> 1;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get size() {
+        return this.#values.length;
+    }
+
+    /**
+     * @param {number} index
+     * @returns {number} the selector codebook index remembered there
+     */
+    at(index) {
+        return this.#values[index];
+    }
+
+    /**
+     * Remember a selector index that was referred to by its codebook index.
+     *
+     * @param {number} value
+     */
+    add(value) {
+        this.#values[this.#rover++] = value;
+
+        if (this.#rover === this.#values.length) {
+            this.#rover = this.#values.length >> 1;
+        }
+    }
+
+    /**
+     * Promote the entry at `index`, having just referred to it.
+     *
+     * @param {number} index
+     */
+    use(index) {
+        if (index === 0) {
+            // already as far forward as the list goes, and halving would swap it with itself
+            return;
+        }
+
+        const half = index >> 1;
+
+        const promoted = this.#values[index];
+
+        this.#values[index] = this.#values[half];
+        this.#values[half] = promoted;
+    }
+}

package/src/basis/etc1s/etc1s_block_colors.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The four colours a block's endpoint entry defines, which its selectors choose between.
+ *
+ * @param {Uint8Array} out receives twelve bytes, four `[r, g, b]` triples darkest first
+ * @param {number} out_offset
+ * @param {Uint8Array} color5 the endpoint codebook's channel array
+ * @param {Uint8Array} intensity the endpoint codebook's intensity array
+ * @param {number} endpoint_index
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function etc1s_block_colors(out: Uint8Array, out_offset: number, color5: Uint8Array, intensity: Uint8Array, endpoint_index: number): void;
+//# sourceMappingURL=etc1s_block_colors.d.ts.map

package/src/basis/etc1s/etc1s_block_colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"etc1s_block_colors.d.ts","sourceRoot":"","sources":["../../../../src/basis/etc1s/etc1s_block_colors.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;GAWG;AACH,wCATW,UAAU,cACV,MAAM,UACN,UAAU,aACV,UAAU,kBACV,MAAM,QAmBhB"}