@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/isobmff/BoxHeader.js

@@ -0,0 +1,57 @@
+/**
+ * A parsed ISOBMFF box header.
+ *
+ * Reused across a whole parse: {@link read_box_header} fills one of these in place rather than
+ * allocating, so walking a box tree of any depth allocates nothing per box.
+ *
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxHeader {
+    /**
+     * Four character type. `uuid` here means {@link user_type} carries the real identity.
+     * @type {string}
+     */
+    type = "";
+
+    /**
+     * Absolute offset of the first byte of the box, its size field included.
+     * @type {number}
+     */
+    offset = 0;
+
+    /**
+     * Total size of the box in bytes, header included.
+     * @type {number}
+     */
+    size = 0;
+
+    /**
+     * Absolute offset of the first byte after the header.
+     * @type {number}
+     */
+    payload_offset = 0;
+
+    /**
+     * Size of the payload in bytes.
+     * @type {number}
+     */
+    payload_size = 0;
+
+    /**
+     * 16 byte extended type, present only when {@link type} is `uuid`. A view into the source
+     * buffer, not a copy.
+     * @type {Uint8Array|null}
+     */
+    user_type = null;
+
+    /**
+     * Absolute offset one past the last byte of the box.
+     * @returns {number}
+     */
+    get end() {
+        return this.offset + this.size;
+    }
+}

package/src/avif/native/isobmff/BoxWriter.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Writer for ISOBMFF box trees.
+ *
+ * Box sizes are only known once their contents are written, so {@link begin_box} reserves a 32-bit
+ * size field and {@link end_box} patches it. The stack of pending size-field offsets is a plain
+ * `Int32Array`, so nesting costs nothing.
+ *
+ * Built on `core/binary/BinaryBuffer.js`, which is the right shape for this direction: a growable
+ * stream with the big-endian accessors ISOBMFF is defined in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxWriter {
+    /**
+     * @type {BinaryBuffer}
+     */
+    buffer: BinaryBuffer;
+    /**
+     * Offsets of the size fields of the boxes currently open, outermost first.
+     * @type {Int32Array}
+     */
+    open_box_offsets: Int32Array;
+    /**
+     * Number of boxes currently open.
+     * @type {number}
+     */
+    depth: number;
+    /**
+     * Bytes written so far.
+     * @returns {number}
+     */
+    get position(): number;
+    /**
+     * Open a box, reserving space for its size.
+     *
+     * @param {string} type four character box type
+     * @returns {number} the offset of the box, for callers that need to patch it later
+     */
+    begin_box(type: string): number;
+    /**
+     * Open a `FullBox`, writing its version and flags.
+     * @param {string} type
+     * @param {number} version `0 .. 255`
+     * @param {number} flags `0 .. 2^24 - 1`
+     * @returns {number}
+     */
+    begin_full_box(type: string, version: number, flags: number): number;
+    /**
+     * Close the innermost open box and patch its size.
+     */
+    end_box(): void;
+    /**
+     * @param {number} value
+     */
+    u8(value: number): void;
+    /**
+     * @param {number} value
+     */
+    u16(value: number): void;
+    /**
+     * @param {number} value
+     */
+    u24(value: number): void;
+    /**
+     * @param {number} value
+     */
+    u32(value: number): void;
+    /**
+     * @param {number} value
+     */
+    i16(value: number): void;
+    /**
+     * @param {number} value
+     */
+    i32(value: number): void;
+    /**
+     * @param {number} value
+     */
+    u64(value: number): void;
+    /**
+     * Unsigned integer of `size` bytes, where `size` is `0`, `4` or `8`.
+     * @param {number} size
+     * @param {number} value
+     */
+    uint_of_size(size: number, value: number): void;
+    /**
+     * @param {string} type four character code
+     */
+    fourcc(type: string): void;
+    /**
+     * NUL-terminated UTF-8 string.
+     * @param {string} text
+     */
+    utf8_string(text: string): void;
+    /**
+     * @param {Uint8Array} source
+     */
+    bytes(source: Uint8Array): void;
+    /**
+     * Overwrite a previously written 32-bit field.
+     * @param {number} offset
+     * @param {number} value
+     */
+    patch_u32(offset: number, value: number): void;
+    /**
+     * The bytes written so far, as a fresh `ArrayBuffer`.
+     * @returns {ArrayBuffer}
+     */
+    to_array_buffer(): ArrayBuffer;
+    /**
+     * The bytes written so far, as a fresh `Uint8Array`.
+     * @returns {Uint8Array}
+     */
+    to_bytes(): Uint8Array;
+}
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=BoxWriter.d.ts.map

package/src/avif/native/isobmff/BoxWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoxWriter.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/isobmff/BoxWriter.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,QAFU,YAAY,CAEM;IAE5B;;;OAGG;IACH,kBAFU,UAAU,CAE2B;IAE/C;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,uBAEC;IAED;;;;;OAKG;IACH,gBAHW,MAAM,GACJ,MAAM,CAsBlB;IAED;;;;;;OAMG;IACH,qBALW,MAAM,WACN,MAAM,SACN,MAAM,GACJ,MAAM,CASlB;IAED;;OAEG;IACH,gBAkBC;IAED;;OAEG;IACH,UAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAIhB;IAED;;OAEG;IACH,WAFW,MAAM,QAKhB;IAED;;;;OAIG;IACH,mBAHW,MAAM,SACN,MAAM,QAgBhB;IAED;;OAEG;IACH,aAFW,MAAM,QAUhB;IAED;;;OAGG;IACH,kBAFW,MAAM,QAchB;IAED;;OAEG;IACH,cAFW,UAAU,QAIpB;IAED;;;;OAIG;IACH,kBAHW,MAAM,SACN,MAAM,QAQhB;IAED;;;OAGG;IACH,mBAFa,WAAW,CAQvB;IAED;;;OAGG;IACH,YAFa,UAAU,CAQtB;CACJ;6BAvQ4B,sCAAsC"}

package/src/avif/native/isobmff/BoxWriter.js

@@ -0,0 +1,264 @@
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { utf8_encode_into } from "../../../core/binary/utf8/utf8_encode_into.js";
+import { utf8_encoded_length } from "../../../core/binary/utf8/utf8_encoded_length.js";
+
+/**
+ * Depth limit for nested boxes. AVIF's deepest legitimate nesting is
+ * `meta > iprp > ipco > property`, so anything approaching this is a bug in the writer rather than
+ * a legitimate file.
+ * @type {number}
+ */
+const MAX_NESTING = 16;
+
+/**
+ * Writer for ISOBMFF box trees.
+ *
+ * Box sizes are only known once their contents are written, so {@link begin_box} reserves a 32-bit
+ * size field and {@link end_box} patches it. The stack of pending size-field offsets is a plain
+ * `Int32Array`, so nesting costs nothing.
+ *
+ * Built on `core/binary/BinaryBuffer.js`, which is the right shape for this direction: a growable
+ * stream with the big-endian accessors ISOBMFF is defined in.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BoxWriter {
+    /**
+     * @type {BinaryBuffer}
+     */
+    buffer = new BinaryBuffer();
+
+    /**
+     * Offsets of the size fields of the boxes currently open, outermost first.
+     * @type {Int32Array}
+     */
+    open_box_offsets = new Int32Array(MAX_NESTING);
+
+    /**
+     * Number of boxes currently open.
+     * @type {number}
+     */
+    depth = 0;
+
+    /**
+     * Bytes written so far.
+     * @returns {number}
+     */
+    get position() {
+        return this.buffer.position;
+    }
+
+    /**
+     * Open a box, reserving space for its size.
+     *
+     * @param {string} type four character box type
+     * @returns {number} the offset of the box, for callers that need to patch it later
+     */
+    begin_box(type) {
+        if (this.depth >= MAX_NESTING) {
+            throw new Error(`box nesting exceeded ${MAX_NESTING} levels`);
+        }
+
+        if (type.length !== 4) {
+            throw new Error(`box type '${type}' is not four characters`);
+        }
+
+        const offset = this.buffer.position;
+
+        this.open_box_offsets[this.depth++] = offset;
+
+        this.buffer.writeUint32BE(0);
+
+        for (let i = 0; i < 4; i++) {
+            this.buffer.writeUint8(type.charCodeAt(i));
+        }
+
+        return offset;
+    }
+
+    /**
+     * Open a `FullBox`, writing its version and flags.
+     * @param {string} type
+     * @param {number} version `0 .. 255`
+     * @param {number} flags `0 .. 2^24 - 1`
+     * @returns {number}
+     */
+    begin_full_box(type, version, flags) {
+        const offset = this.begin_box(type);
+
+        this.buffer.writeUint8(version);
+        this.buffer.writeUint24BE(flags);
+
+        return offset;
+    }
+
+    /**
+     * Close the innermost open box and patch its size.
+     */
+    end_box() {
+        if (this.depth === 0) {
+            throw new Error("end_box() with no box open");
+        }
+
+        const offset = this.open_box_offsets[--this.depth];
+        const end = this.buffer.position;
+        const size = end - offset;
+
+        // 32-bit sizes only. A box above 4 GiB would need the `largesize` form, whose extra eight
+        // bytes would move everything after it — and nothing this writer produces comes close.
+        if (size > 4294967295) {
+            throw new Error(`box at ${offset} is ${size} bytes, beyond the 32-bit size field`);
+        }
+
+        this.buffer.position = offset;
+        this.buffer.writeUint32BE(size);
+        this.buffer.position = end;
+    }
+
+    /**
+     * @param {number} value
+     */
+    u8(value) {
+        this.buffer.writeUint8(value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    u16(value) {
+        this.buffer.writeUint16BE(value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    u24(value) {
+        this.buffer.writeUint24BE(value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    u32(value) {
+        this.buffer.writeUint32BE(value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    i16(value) {
+        this.buffer.writeUint16BE(value < 0 ? value + 65536 : value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    i32(value) {
+        this.buffer.writeUint32BE(value < 0 ? value + 4294967296 : value);
+    }
+
+    /**
+     * @param {number} value
+     */
+    u64(value) {
+        this.buffer.writeUint32BE(Math.floor(value / 4294967296));
+        this.buffer.writeUint32BE(value >>> 0);
+    }
+
+    /**
+     * Unsigned integer of `size` bytes, where `size` is `0`, `4` or `8`.
+     * @param {number} size
+     * @param {number} value
+     */
+    uint_of_size(size, value) {
+        if (size === 0) {
+            return;
+        }
+
+        if (size === 4) {
+            this.u32(value);
+        } else if (size === 8) {
+            this.u64(value);
+        } else if (size === 2) {
+            this.u16(value);
+        } else {
+            throw new Error(`unsupported field width of ${size} bytes`);
+        }
+    }
+
+    /**
+     * @param {string} type four character code
+     */
+    fourcc(type) {
+        if (type.length !== 4) {
+            throw new Error(`'${type}' is not a four character code`);
+        }
+
+        for (let i = 0; i < 4; i++) {
+            this.buffer.writeUint8(type.charCodeAt(i));
+        }
+    }
+
+    /**
+     * NUL-terminated UTF-8 string.
+     * @param {string} text
+     */
+    utf8_string(text) {
+        const buffer = this.buffer;
+
+        const length = utf8_encoded_length(text);
+
+        // grow once, for the string and its terminator together; `raw_bytes` has to be read after
+        // that, because growing replaces the array
+        buffer.ensureCapacity(buffer.position + length + 1);
+
+        buffer.position += utf8_encode_into(text, buffer.raw_bytes, buffer.position);
+
+        buffer.writeUint8(0);
+    }
+
+    /**
+     * @param {Uint8Array} source
+     */
+    bytes(source) {
+        this.buffer.writeBytes(source, 0, source.length);
+    }
+
+    /**
+     * Overwrite a previously written 32-bit field.
+     * @param {number} offset
+     * @param {number} value
+     */
+    patch_u32(offset, value) {
+        const end = this.buffer.position;
+
+        this.buffer.position = offset;
+        this.buffer.writeUint32BE(value);
+        this.buffer.position = end;
+    }
+
+    /**
+     * The bytes written so far, as a fresh `ArrayBuffer`.
+     * @returns {ArrayBuffer}
+     */
+    to_array_buffer() {
+        if (this.depth !== 0) {
+            throw new Error(`${this.depth} box(es) left open`);
+        }
+
+        return this.to_bytes().buffer;
+    }
+
+    /**
+     * The bytes written so far, as a fresh `Uint8Array`.
+     * @returns {Uint8Array}
+     */
+    to_bytes() {
+        if (this.depth !== 0) {
+            throw new Error(`${this.depth} box(es) left open`);
+        }
+
+        return this.buffer.raw_bytes.slice(0, this.buffer.position);
+    }
+}

package/src/avif/native/isobmff/ByteCursor.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Big-endian byte cursor over an `ArrayBuffer`, bounds-checked on every read.
+ *
+ * ISOBMFF parsing wants cheap random access into a buffer that already exists — box sizes point
+ * forwards, item offsets point anywhere — and it never wants a copy. `core/binary/BinaryBuffer.js`
+ * is a growable stream built for the opposite job; using it here would mean carrying its growth
+ * machinery through a parser that never grows anything. This is the read half; writing goes through
+ * {@link BoxWriter}, which does use `BinaryBuffer`.
+ *
+ * Every accessor validates against {@link end} before touching memory. A truncated or hostile file
+ * must throw a named error, not read whatever happens to follow in the buffer.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ByteCursor {
+    /**
+     * @type {DataView}
+     */
+    view: DataView;
+    /**
+     * @type {Uint8Array}
+     */
+    bytes: Uint8Array;
+    /**
+     * Absolute index of the next byte to read, relative to the start of the underlying buffer.
+     * @type {number}
+     */
+    position: number;
+    /**
+     * Absolute index one past the last readable byte.
+     * @type {number}
+     */
+    end: number;
+    /**
+     * @param {ArrayBuffer|Uint8Array} source
+     * @param {number} [byte_offset]
+     * @param {number} [byte_length]
+     * @returns {ByteCursor} this
+     */
+    init(source: ArrayBuffer | Uint8Array, byte_offset?: number, byte_length?: number): ByteCursor;
+    /**
+     * Create an independent cursor over a sub-range of this one, sharing the same memory.
+     * @param {number} byte_offset absolute offset
+     * @param {number} byte_length
+     * @returns {ByteCursor}
+     */
+    sub_cursor(byte_offset: number, byte_length: number): ByteCursor;
+    /**
+     * @returns {number}
+     */
+    get remaining(): number;
+    /**
+     * @param {number} count
+     * @param {string} what named in the error, so a malformed file says which field ran out
+     */
+    require(count: number, what: string): void;
+    /**
+     * @returns {number}
+     */
+    u8(): number;
+    /**
+     * @returns {number}
+     */
+    u16(): number;
+    /**
+     * @returns {number}
+     */
+    u24(): number;
+    /**
+     * @returns {number}
+     */
+    u32(): number;
+    /**
+     * @returns {number}
+     */
+    i16(): number;
+    /**
+     * @returns {number}
+     */
+    i32(): number;
+    /**
+     * 64-bit unsigned, returned as a `Number`.
+     *
+     * Sizes and offsets beyond 2^53 cannot occur in a file that fits in memory, so a value above
+     * that is corruption rather than a precision problem, and is rejected as such.
+     *
+     * @returns {number}
+     */
+    u64(): number;
+    /**
+     * Unsigned integer of `size` bytes, where `size` is one of `0`, `4` or `8`. ISOBMFF uses this
+     * shape throughout `iloc`, where field widths are declared in the box header.
+     *
+     * @param {number} size
+     * @returns {number}
+     */
+    uint_of_size(size: number): number;
+    /**
+     * Four character box type, as an ASCII string.
+     * @returns {string}
+     */
+    fourcc(): string;
+    /**
+     * NUL-terminated UTF-8 string. Stops at {@link end} if the terminator is missing, which real
+     * files do get wrong, rather than throwing.
+     * @returns {string}
+     */
+    utf8_string(): string;
+    /**
+     * A view onto `length` bytes, sharing memory with the source. Does not copy.
+     * @param {number} length
+     * @returns {Uint8Array}
+     */
+    view_bytes(length: number): Uint8Array;
+    /**
+     * @param {number} count
+     */
+    skip(count: number): void;
+    /**
+     * @param {number} position absolute
+     */
+    seek(position: number): void;
+}
+//# sourceMappingURL=ByteCursor.d.ts.map

package/src/avif/native/isobmff/ByteCursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ByteCursor.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/isobmff/ByteCursor.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH;IACI;;OAEG;IACH,MAFU,QAAQ,CAEN;IAEZ;;OAEG;IACH,OAFU,UAAU,CAEP;IAEb;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;;;;OAKG;IACH,aALW,WAAW,GAAC,UAAU,gBACtB,MAAM,gBACN,MAAM,GACJ,UAAU,CAmBtB;IAED;;;;;OAKG;IACH,wBAJW,MAAM,eACN,MAAM,GACJ,UAAU,CAetB;IAED;;OAEG;IACH,wBAEC;IAED;;;OAGG;IACH,eAHW,MAAM,QACN,MAAM,QAMhB;IAED;;OAEG;IACH,MAFa,MAAM,CAMlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAWlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,OAFa,MAAM,CAelB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;OAGG;IACH,UAFa,MAAM,CAUlB;IAED;;;;OAIG;IACH,eAFa,MAAM,CAgBlB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,UAAU,CAUtB;IAED;;OAEG;IACH,YAFW,MAAM,QAMhB;IAED;;OAEG;IACH,eAFW,MAAM,QAQhB;CACJ"}