@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/image/avif/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/format/image/avif/isobmff/BoxWriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoxWriter.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/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,yCAAyC"}

package/src/format/image/avif/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/format/image/avif/isobmff/for_each_box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"for_each_box.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/isobmff/for_each_box.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,+DALoB,SAAS,uBAAe,CAAC,OAAO,GAAC,IAAI,CAAC,QAoBzD;0BAtCyB,gBAAgB"}

package/src/format/image/avif/isobmff/read_box_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_box_header.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/isobmff/read_box_header.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,kFAsCC"}

package/src/format/image/avif/isobmff/read_full_box_header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_full_box_header.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/isobmff/read_full_box_header.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,0DANa,MAAM,CAQlB;AAED;;;GAGG;AACH,oDAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;GAGG;AACH,kDAHW,MAAM,GACJ,MAAM,CAIlB"}

package/src/format/image/jpeg/JpegFrame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JpegFrame.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/jpeg/JpegFrame.js"],"names":[],"mappings":"AAAA;IACI;;;OAGG;IACH,UAFU,OAAO,CAEA;IACjB;;;OAGG;IACH,aAFU,OAAO,CAEG;IACpB;;;OAGG;IACH,WAFU,MAAM,CAEF;IACd;;;OAGG;IACH,WAFU,MAAM,CAEF;IACd;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB,aAAS;IACT,aAAS;IAET,oBAAgB;IAChB,sBAAkB;IAElB;;;;;OAKG;IACH,YAFU,IAAI,MAAM,qBAAqB,CAElB;IAEvB;;;OAGG;IACH,iBAFU,MAAM,EAAE,CAEG;CACxB"}

package/src/format/image/jpeg/JpegFrameComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JpegFrameComponent.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/jpeg/JpegFrameComponent.js"],"names":[],"mappings":"AAAA;IACI;;;OAGG;IACH,GAFU,MAAM,CAEX;IACL;;;OAGG;IACH,GAFU,MAAM,CAEX;IAEL;;OAEG;IACH,MAFU,MAAM,CAER;IAER;;OAEG;IACH,QAFU,UAAU,EAAE,EAAE,CAElB;IAEN,sBAAiB;IACjB,wBAAmB;IAEnB;;;;OAIG;IACH,iBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,mBAFU,UAAU,CAEF;IAElB;;;OAGG;IACH,gBAFU,EAAE,CAEE;IAEd;;;OAGG;IACH,gBAFU,EAAE,CAEE;CACjB"}

package/src/format/image/jpeg/JpegImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JpegImage.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/jpeg/JpegImage.js"],"names":[],"mappings":"AA6IA;IAEI;;;OAGG;IACH,YAFW,UAAU,QAyWpB;IAvRG;;;OAGG;IACH,UAFU,MAAM,EAAE,CAEA;IA0DE,uBAAqD;IAsMzE,cAAiC;IACjC,eAA6B;IAC7B;;;;;;;;;;;MAAgB;IAChB;;;;;MAAkB;IAElB;;;OAGG;IACH,YAFU;QAAC,KAAK,EAAC,UAAU,EAAE,CAAC;QAAC,MAAM,EAAC,MAAM,CAAC;QAAC,MAAM,EAAC,MAAM,CAAA;KAAC,EAAE,CAE1C;IAYxB;;;;;;;;;;OAUG;IACH,0BAUC;IAED;;;;;;;;;;OAUG;IACH,eAJW,MAAM,UACN,MAAM,GACL,UAAU,CAqDrB;IAED;;;;OAIG;IACH;cAHiB,UAAU;eAAQ,MAAM;gBAAS,MAAM;sBAC7C,OAAO,QA+DjB;CACJ"}