@woosh/meep-engine 3.14.1 → 3.14.2

package/src/avif/native/heif/parse_image_grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parse_image_grid.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/parse_image_grid.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,0CAPW,UAAU,GACR,SAAS,CAmCrB;0BA9CyB,eAAe"}
+{"version":3,"file":"parse_image_grid.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/heif/parse_image_grid.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,0CAPW,UAAU,GACR,SAAS,CAmCrB;0BA9CyB,eAAe"}

package/src/avif/native/heif/parse_image_grid.js

@@ -1,48 +1,49 @@
-import { ByteCursor } from "../isobmff/ByteCursor.js";
-import { ImageGrid } from "./AvifFile.js";
-
-/**
- * Parse a `grid` derived image's payload.
- *
- * This is not a box: it is the item's own data, laid out as version, flags, the tile counts and
- * the assembled output size. Bit 0 of `flags` widens the output dimensions from 16 to 32 bits.
- *
- * The tile counts are stored minus one, so a grid always has at least one row and one column.
- *
- * @param {Uint8Array} payload
- * @returns {ImageGrid}
- * @see ISO/IEC 23008-12 section 6.6.2.3 "Image grid"
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function parse_image_grid(payload) {
-    const cursor = new ByteCursor().init(payload);
-
-    const version = cursor.u8();
-
-    if (version !== 0) {
-        throw new Error(`grid version ${version} is not supported`);
-    }
-
-    const flags = cursor.u8();
-
-    const grid = new ImageGrid();
-
-    grid.rows = cursor.u8() + 1;
-    grid.columns = cursor.u8() + 1;
-
-    if ((flags & 1) !== 0) {
-        grid.output_width = cursor.u32();
-        grid.output_height = cursor.u32();
-    } else {
-        grid.output_width = cursor.u16();
-        grid.output_height = cursor.u16();
-    }
-
-    if (grid.output_width === 0 || grid.output_height === 0) {
-        throw new Error(`grid declares a ${grid.output_width}x${grid.output_height} output`);
-    }
-
-    return grid;
-}
+import { ByteCursor } from "../../../core/binary/ByteCursor.js";
+import { EndianType } from "../../../core/binary/EndianType.js";
+import { ImageGrid } from "./AvifFile.js";
+
+/**
+ * Parse a `grid` derived image's payload.
+ *
+ * This is not a box: it is the item's own data, laid out as version, flags, the tile counts and
+ * the assembled output size. Bit 0 of `flags` widens the output dimensions from 16 to 32 bits.
+ *
+ * The tile counts are stored minus one, so a grid always has at least one row and one column.
+ *
+ * @param {Uint8Array} payload
+ * @returns {ImageGrid}
+ * @see ISO/IEC 23008-12 section 6.6.2.3 "Image grid"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_image_grid(payload) {
+    const cursor = new ByteCursor().init(payload, EndianType.BigEndian);
+
+    const version = cursor.u8();
+
+    if (version !== 0) {
+        throw new Error(`grid version ${version} is not supported`);
+    }
+
+    const flags = cursor.u8();
+
+    const grid = new ImageGrid();
+
+    grid.rows = cursor.u8() + 1;
+    grid.columns = cursor.u8() + 1;
+
+    if ((flags & 1) !== 0) {
+        grid.output_width = cursor.u32();
+        grid.output_height = cursor.u32();
+    } else {
+        grid.output_width = cursor.u16();
+        grid.output_height = cursor.u16();
+    }
+
+    if (grid.output_width === 0 || grid.output_height === 0) {
+        throw new Error(`grid declares a ${grid.output_width}x${grid.output_height} output`);
+    }
+
+    return grid;
+}

package/src/basis/BasisBitReader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * LSB-first bit cursor over a byte range, with the speculative peek a Huffman decoder needs.
+ *
+ * **Why this is not {@link BitReader}.** `avif/native/bitstream/BitReader.js` is the other bit
+ * reader in this tree and it does not fit, for two reasons that are about the format rather than
+ * about convenience:
+ *
+ * 1. **It is MSB-first, and Basis is LSB-first.** The specification is explicit — "Huffman codes are
+ *    stored in each output byte in LSB to MSB order. (This is opposite of the JPEG format)". Bit
+ *    order is not a parameter that could be added the way {@link ByteCursor} took a byte order:
+ *    a byte order is a property of a *field*, applied once per read, while a bit order changes what
+ *    the single-bit primitive means and so changes every accessor beneath it.
+ * 2. **Huffman decoding needs peek-then-consume, which a descriptor reader has no reason to offer.**
+ *    A canonical code's length is not known until it has been looked up, so the decoder reads bits
+ *    it may not consume. `BitReader`'s `f(n)` is sequential by construction.
+ *
+ * One class doing both would be a flag on every method. So this is a second bit reader,
+ * deliberately, and it stays in `basis/` rather than moving to `core/binary/` until something other
+ * than Basis wants it — the same rule `ByteCursor` moved under, applied in the direction that says
+ * "not yet".
+ *
+ * **Peeking past the end reads zeros; consuming past it throws.** The two have to differ. A Huffman
+ * peek is speculative and legitimately runs off the end of a section — the last code in a stream is
+ * rarely flush with a byte boundary — so refusing there would refuse well-formed files. Consuming is
+ * a different claim, and a stream that runs out mid-symbol is corrupt.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BasisBitReader {
+    /**
+     * Point the reader at a byte range.
+     *
+     * @param {Uint8Array} data
+     * @param {number} [byte_offset]
+     * @param {number} [byte_length]
+     * @returns {BasisBitReader} this
+     * @throws {Error} for a range outside `data`
+     */
+    init(data: Uint8Array, byte_offset?: number, byte_length?: number): BasisBitReader;
+    /**
+     * Look at the next `count` bits without consuming them. Bits past the end of the range read as
+     * zero — see the note on the class.
+     *
+     * @param {number} count `0` to 24; the Huffman decoder's longest peek is 16
+     * @returns {number}
+     */
+    peek(count: number): number;
+    /**
+     * Drop the next `count` bits.
+     *
+     * @param {number} count
+     * @throws {Error} when the bits dropped were never in the range
+     */
+    consume(count: number): void;
+    /**
+     * Read `count` bits, least significant first.
+     *
+     * @param {number} count `0` to 24
+     * @returns {number}
+     * @throws {Error} when the range does not hold them
+     */
+    bits(count: number): number;
+    /**
+     * The specification's variable-length code: `chunk_bits` of payload plus a continuation bit,
+     * repeated until the continuation bit is clear.
+     *
+     * @param {number} chunk_bits
+     * @returns {number}
+     * @throws {Error} for a code that would not fit in 32 bits, which is a corrupt stream rather
+     * than a large number
+     * @see the specification's `decode_vlc`, section 10.2
+     */
+    vlc(chunk_bits: number): number;
+    #private;
+}
+//# sourceMappingURL=BasisBitReader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BasisBitReader.d.ts","sourceRoot":"","sources":["../../../src/basis/BasisBitReader.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAyCI;;;;;;;;OAQG;IACH,WANW,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,cAAc,CAmB1B;IA6BD;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;OAKG;IACH,eAHW,MAAM,QAwBhB;IAED;;;;;;OAMG;IACH,YAJW,MAAM,GACJ,MAAM,CASlB;IAED;;;;;;;;;OASG;IACH,gBANW,MAAM,GACJ,MAAM,CA+BlB;;CACJ"}

package/src/basis/BasisBitReader.js

@@ -0,0 +1,231 @@
+/**
+ * Bits are consumed into a 32-bit accumulator; this is how many it may hold.
+ *
+ * @readonly
+ * @type {number}
+ */
+const ACCUMULATOR_CAPACITY = 32;
+
+/**
+ * LSB-first bit cursor over a byte range, with the speculative peek a Huffman decoder needs.
+ *
+ * **Why this is not {@link BitReader}.** `avif/native/bitstream/BitReader.js` is the other bit
+ * reader in this tree and it does not fit, for two reasons that are about the format rather than
+ * about convenience:
+ *
+ * 1. **It is MSB-first, and Basis is LSB-first.** The specification is explicit — "Huffman codes are
+ *    stored in each output byte in LSB to MSB order. (This is opposite of the JPEG format)". Bit
+ *    order is not a parameter that could be added the way {@link ByteCursor} took a byte order:
+ *    a byte order is a property of a *field*, applied once per read, while a bit order changes what
+ *    the single-bit primitive means and so changes every accessor beneath it.
+ * 2. **Huffman decoding needs peek-then-consume, which a descriptor reader has no reason to offer.**
+ *    A canonical code's length is not known until it has been looked up, so the decoder reads bits
+ *    it may not consume. `BitReader`'s `f(n)` is sequential by construction.
+ *
+ * One class doing both would be a flag on every method. So this is a second bit reader,
+ * deliberately, and it stays in `basis/` rather than moving to `core/binary/` until something other
+ * than Basis wants it — the same rule `ByteCursor` moved under, applied in the direction that says
+ * "not yet".
+ *
+ * **Peeking past the end reads zeros; consuming past it throws.** The two have to differ. A Huffman
+ * peek is speculative and legitimately runs off the end of a section — the last code in a stream is
+ * rarely flush with a byte boundary — so refusing there would refuse well-formed files. Consuming is
+ * a different claim, and a stream that runs out mid-symbol is corrupt.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BasisBitReader {
+    /**
+     * Bytes being read. Not owned.
+     * @type {Uint8Array}
+     */
+    #data = null;
+
+    /**
+     * Index into {@link #data} of the next byte to pull into {@link #accumulator}.
+     * @type {number}
+     */
+    #byte_position = 0;
+
+    /**
+     * Index into {@link #data} one past the last readable byte.
+     * @type {number}
+     */
+    #end = 0;
+
+    /**
+     * Buffered bits, least significant first. Only the low {@link #bit_count} are meaningful.
+     * @type {number}
+     */
+    #accumulator = 0;
+
+    /**
+     * How many of {@link #accumulator}'s bits are meaningful.
+     * @type {number}
+     */
+    #bit_count = 0;
+
+    /**
+     * Bits of {@link #accumulator} that were manufactured past {@link #end} rather than read.
+     *
+     * They sit at the most significant end, since that is where a refill puts them. Consuming far
+     * enough to reach them is the overrun that throws.
+     *
+     * @type {number}
+     */
+    #phantom_bits = 0;
+
+    /**
+     * Point the reader at a byte range.
+     *
+     * @param {Uint8Array} data
+     * @param {number} [byte_offset]
+     * @param {number} [byte_length]
+     * @returns {BasisBitReader} this
+     * @throws {Error} for a range outside `data`
+     */
+    init(data, byte_offset = 0, byte_length = data.length - byte_offset) {
+        if (byte_offset < 0 || byte_length < 0 || byte_offset + byte_length > data.length) {
+            throw new Error(
+                `Basis: a bit reader range of [${byte_offset}, ${byte_offset + byte_length}) is`
+                + ` outside the ${data.length} byte buffer it was given`
+            );
+        }
+
+        this.#data = data;
+        this.#byte_position = byte_offset;
+        this.#end = byte_offset + byte_length;
+        this.#accumulator = 0;
+        this.#bit_count = 0;
+        this.#phantom_bits = 0;
+
+        return this;
+    }
+
+    /**
+     * Fill {@link #accumulator} to at least `count` meaningful bits, manufacturing zeros past the
+     * end of the range.
+     *
+     * @param {number} count
+     */
+    #fill(count) {
+        while (this.#bit_count < count) {
+            const past_end = this.#byte_position >= this.#end;
+
+            const byte = past_end ? 0 : this.#data[this.#byte_position];
+
+            if (past_end) {
+                this.#phantom_bits += 8;
+            }
+
+            this.#byte_position++;
+
+            /*
+             `<<` is a signed 32-bit shift, so a byte landing on bits 24..31 would make the
+             accumulator negative; `>>> 0` puts it back in the unsigned range the masks assume.
+            */
+            this.#accumulator = (this.#accumulator | (byte << this.#bit_count)) >>> 0;
+            this.#bit_count += 8;
+        }
+    }
+
+    /**
+     * Look at the next `count` bits without consuming them. Bits past the end of the range read as
+     * zero — see the note on the class.
+     *
+     * @param {number} count `0` to 24; the Huffman decoder's longest peek is 16
+     * @returns {number}
+     */
+    peek(count) {
+        if (count === 0) {
+            return 0;
+        }
+
+        this.#fill(count);
+
+        return this.#accumulator & ((1 << count) - 1);
+    }
+
+    /**
+     * Drop the next `count` bits.
+     *
+     * @param {number} count
+     * @throws {Error} when the bits dropped were never in the range
+     */
+    consume(count) {
+        if (count === 0) {
+            return;
+        }
+
+        this.#fill(count);
+
+        /*
+         The phantom bits sit at the top of the accumulator, so the bits being consumed are real
+         exactly when the meaningful ones below them outnumber the request.
+        */
+        if (this.#bit_count - this.#phantom_bits < count) {
+            throw new Error(
+                `Basis: the bitstream ended mid-symbol — ${count} bits were asked for and only`
+                + ` ${Math.max(this.#bit_count - this.#phantom_bits, 0)} remain in the section`
+            );
+        }
+
+        this.#accumulator = count === ACCUMULATOR_CAPACITY ? 0 : this.#accumulator >>> count;
+
+        this.#bit_count -= count;
+    }
+
+    /**
+     * Read `count` bits, least significant first.
+     *
+     * @param {number} count `0` to 24
+     * @returns {number}
+     * @throws {Error} when the range does not hold them
+     */
+    bits(count) {
+        const value = this.peek(count);
+
+        this.consume(count);
+
+        return value;
+    }
+
+    /**
+     * The specification's variable-length code: `chunk_bits` of payload plus a continuation bit,
+     * repeated until the continuation bit is clear.
+     *
+     * @param {number} chunk_bits
+     * @returns {number}
+     * @throws {Error} for a code that would not fit in 32 bits, which is a corrupt stream rather
+     * than a large number
+     * @see the specification's `decode_vlc`, section 10.2
+     */
+    vlc(chunk_bits) {
+        const chunk_size = 1 << chunk_bits;
+        const chunk_mask = chunk_size - 1;
+
+        let value = 0;
+        let offset = 0;
+
+        for (; ;) {
+            const chunk = this.bits(chunk_bits + 1);
+
+            value |= (chunk & chunk_mask) << offset;
+            offset += chunk_bits;
+
+            if ((chunk & chunk_size) === 0) {
+                break;
+            }
+
+            if (offset >= ACCUMULATOR_CAPACITY) {
+                throw new Error(
+                    `Basis: a variable-length code ran past ${ACCUMULATOR_CAPACITY} bits without`
+                    + ` terminating, which no valid stream does`
+                );
+            }
+        }
+
+        return value >>> 0;
+    }
+}

package/src/basis/BasisHuffmanTable.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Longest code the format permits, from the specification's `cHuffmanMaxSupportedCodeSize`.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const HUFFMAN_MAX_CODE_SIZE: number;
+/**
+ * Most symbols a table may describe, from the specification's `cHuffmanMaxSyms` — `1 << 14`.
+ *
+ * @readonly
+ * @type {number}
+ */
+export const HUFFMAN_MAX_SYMBOLS: number;
+/**
+ * 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 {
+    /**
+     * 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: Uint8Array): BasisHuffmanTable;
+    /**
+     * Read one symbol.
+     *
+     * @param {BasisBitReader} reader
+     * @returns {number} the symbol
+     * @throws {Error} for a prefix that matches no code in the table
+     */
+    decode(reader: BasisBitReader): number;
+    #private;
+}
+import { BasisBitReader } from "./BasisBitReader.js";
+//# sourceMappingURL=BasisHuffmanTable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BasisHuffmanTable.d.ts","sourceRoot":"","sources":["../../../src/basis/BasisHuffmanTable.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;GAKG;AACH,kCAFU,MAAM,CAE2B;AAsB3C;;;;;;;;;;;;;;;;GAgBG;AACH;IAqCI;;;;;;;OAOG;IACH,mBALW,UAAU,GACR,iBAAiB,CAyE7B;IAiDD;;;;;;OAMG;IACH,eAJW,cAAc,GACZ,MAAM,CAuClB;;CACJ;+BAtQ8B,qBAAqB"}