@woosh/meep-engine 3.9.0 → 3.10.0

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

@@ -0,0 +1,298 @@
+import { utf8_decode } from "../../../core/binary/utf8/utf8_decode.js";
+
+/**
+ * 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 = null;
+
+    /**
+     * @type {Uint8Array}
+     */
+    bytes = null;
+
+    /**
+     * Absolute index of the next byte to read, relative to the start of the underlying buffer.
+     * @type {number}
+     */
+    position = 0;
+
+    /**
+     * Absolute index one past the last readable byte.
+     * @type {number}
+     */
+    end = 0;
+
+    /**
+     * @param {ArrayBuffer|Uint8Array} source
+     * @param {number} [byte_offset]
+     * @param {number} [byte_length]
+     * @returns {ByteCursor} this
+     */
+    init(source, byte_offset = 0, byte_length = -1) {
+        const buffer = source instanceof Uint8Array ? source.buffer : source;
+        const base = source instanceof Uint8Array ? source.byteOffset : 0;
+        const available = source instanceof Uint8Array ? source.byteLength : source.byteLength;
+
+        const length = byte_length < 0 ? available - byte_offset : byte_length;
+
+        if (byte_offset < 0 || length < 0 || byte_offset + length > available) {
+            throw new Error(`ByteCursor range [${byte_offset}, ${byte_offset + length}) is outside the ${available} byte source`);
+        }
+
+        this.view = new DataView(buffer, base, available);
+        this.bytes = new Uint8Array(buffer, base, available);
+        this.position = byte_offset;
+        this.end = byte_offset + length;
+
+        return this;
+    }
+
+    /**
+     * 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, byte_length) {
+        if (byte_offset < 0 || byte_length < 0 || byte_offset + byte_length > this.bytes.length) {
+            throw new Error(`sub-cursor range [${byte_offset}, ${byte_offset + byte_length}) is outside the source`);
+        }
+
+        const cursor = new ByteCursor();
+
+        cursor.view = this.view;
+        cursor.bytes = this.bytes;
+        cursor.position = byte_offset;
+        cursor.end = byte_offset + byte_length;
+
+        return cursor;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get remaining() {
+        return this.end - this.position;
+    }
+
+    /**
+     * @param {number} count
+     * @param {string} what named in the error, so a malformed file says which field ran out
+     */
+    require(count, what) {
+        if (count < 0 || this.remaining < count) {
+            throw new Error(`truncated ${what}: needed ${count} bytes, ${this.remaining} remain`);
+        }
+    }
+
+    /**
+     * @returns {number}
+     */
+    u8() {
+        this.require(1, "uint8");
+
+        return this.bytes[this.position++];
+    }
+
+    /**
+     * @returns {number}
+     */
+    u16() {
+        this.require(2, "uint16");
+
+        const value = this.view.getUint16(this.position, false);
+
+        this.position += 2;
+
+        return value;
+    }
+
+    /**
+     * @returns {number}
+     */
+    u24() {
+        this.require(3, "uint24");
+
+        const p = this.position;
+        const value = (this.bytes[p] << 16) | (this.bytes[p + 1] << 8) | this.bytes[p + 2];
+
+        this.position += 3;
+
+        return value;
+    }
+
+    /**
+     * @returns {number}
+     */
+    u32() {
+        this.require(4, "uint32");
+
+        const value = this.view.getUint32(this.position, false);
+
+        this.position += 4;
+
+        return value;
+    }
+
+    /**
+     * @returns {number}
+     */
+    i16() {
+        this.require(2, "int16");
+
+        const value = this.view.getInt16(this.position, false);
+
+        this.position += 2;
+
+        return value;
+    }
+
+    /**
+     * @returns {number}
+     */
+    i32() {
+        this.require(4, "int32");
+
+        const value = this.view.getInt32(this.position, false);
+
+        this.position += 4;
+
+        return value;
+    }
+
+    /**
+     * 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() {
+        this.require(8, "uint64");
+
+        const high = this.view.getUint32(this.position, false);
+        const low = this.view.getUint32(this.position + 4, false);
+
+        this.position += 8;
+
+        if (high > 0x1fffff) {
+            throw new Error("uint64 field exceeds the largest exactly representable integer");
+        }
+
+        return high * 4294967296 + low;
+    }
+
+    /**
+     * 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) {
+        if (size === 0) {
+            return 0;
+        }
+
+        if (size === 4) {
+            return this.u32();
+        }
+
+        if (size === 8) {
+            return this.u64();
+        }
+
+        if (size === 2) {
+            return this.u16();
+        }
+
+        throw new Error(`unsupported field width of ${size} bytes`);
+    }
+
+    /**
+     * Four character box type, as an ASCII string.
+     * @returns {string}
+     */
+    fourcc() {
+        this.require(4, "fourcc");
+
+        const p = this.position;
+
+        this.position += 4;
+
+        return String.fromCharCode(this.bytes[p], this.bytes[p + 1], this.bytes[p + 2], this.bytes[p + 3]);
+    }
+
+    /**
+     * 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() {
+        const start = this.position;
+
+        while (this.position < this.end && this.bytes[this.position] !== 0) {
+            this.position++;
+        }
+
+        const text = utf8_decode(this.bytes, start, this.position);
+
+        if (this.position < this.end) {
+            this.position++;
+        }
+
+        return text;
+    }
+
+    /**
+     * A view onto `length` bytes, sharing memory with the source. Does not copy.
+     * @param {number} length
+     * @returns {Uint8Array}
+     */
+    view_bytes(length) {
+        this.require(length, "byte range");
+
+        const slice = this.bytes.subarray(this.position, this.position + length);
+
+        this.position += length;
+
+        return slice;
+    }
+
+    /**
+     * @param {number} count
+     */
+    skip(count) {
+        this.require(count, "skipped range");
+
+        this.position += count;
+    }
+
+    /**
+     * @param {number} position absolute
+     */
+    seek(position) {
+        if (position < 0 || position > this.end) {
+            throw new Error(`seek to ${position} is outside [0, ${this.end}]`);
+        }
+
+        this.position = position;
+    }
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Walk the boxes contained in `cursor`'s range, calling `visit` for each.
+ *
+ * The header handed to `visit` is a single instance reused for every box in the walk, so a visitor
+ * that needs to keep a header must copy the fields it wants. In exchange, walking a whole file's
+ * box tree allocates one header per nesting level and nothing else.
+ *
+ * The cursor is positioned at the box payload when `visit` is called, and is repositioned to the
+ * next box afterwards regardless of how much of the payload the visitor consumed. A visitor that
+ * reads past its box therefore cannot corrupt the walk.
+ *
+ * Zero-size boxes cannot occur — {@link read_box_header} rejects a size below the header — so the
+ * loop always advances and cannot spin on malformed input.
+ *
+ * @param {ByteCursor} cursor
+ * @param {function(BoxHeader, ByteCursor): (boolean|void)} visit returning `false` stops the walk
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function for_each_box(cursor: ByteCursor, visit: (arg0: BoxHeader, arg1: ByteCursor) => (boolean | void)): void;
+import { BoxHeader } from "./BoxHeader.js";
+//# sourceMappingURL=for_each_box.d.ts.map

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

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

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

@@ -0,0 +1,39 @@
+import { BoxHeader } from "./BoxHeader.js";
+import { read_box_header } from "./read_box_header.js";
+
+/**
+ * Walk the boxes contained in `cursor`'s range, calling `visit` for each.
+ *
+ * The header handed to `visit` is a single instance reused for every box in the walk, so a visitor
+ * that needs to keep a header must copy the fields it wants. In exchange, walking a whole file's
+ * box tree allocates one header per nesting level and nothing else.
+ *
+ * The cursor is positioned at the box payload when `visit` is called, and is repositioned to the
+ * next box afterwards regardless of how much of the payload the visitor consumed. A visitor that
+ * reads past its box therefore cannot corrupt the walk.
+ *
+ * Zero-size boxes cannot occur — {@link read_box_header} rejects a size below the header — so the
+ * loop always advances and cannot spin on malformed input.
+ *
+ * @param {ByteCursor} cursor
+ * @param {function(BoxHeader, ByteCursor): (boolean|void)} visit returning `false` stops the walk
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function for_each_box(cursor, visit) {
+    const header = new BoxHeader();
+
+    // eight bytes is the smallest a box can be: size plus type
+    while (cursor.remaining >= 8) {
+        read_box_header(cursor, header);
+
+        const next = header.end;
+
+        if (visit(header, cursor) === false) {
+            return;
+        }
+
+        cursor.seek(next);
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Read one box header from `cursor` into `header`, leaving the cursor at the first payload byte.
+ *
+ * Handles all three size encodings: an explicit 32-bit size, `1` meaning a 64-bit `largesize`
+ * follows, and `0` meaning the box runs to the end of the enclosing range. The last form is legal
+ * only for the outermost box in a file but appears in the wild inside `mdat`, so it is accepted
+ * anywhere and resolved against the cursor's end.
+ *
+ * A box whose declared size is smaller than its own header, or which claims to extend past the
+ * enclosing range, is corruption: both throw rather than being clamped, because a clamped size
+ * turns into a silently truncated payload much later.
+ *
+ * @param {ByteCursor} cursor
+ * @param {BoxHeader} header filled in place
+ * @returns {BoxHeader} `header`
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_box_header(cursor: ByteCursor, header: BoxHeader): BoxHeader;
+//# sourceMappingURL=read_box_header.d.ts.map

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * Read one box header from `cursor` into `header`, leaving the cursor at the first payload byte.
+ *
+ * Handles all three size encodings: an explicit 32-bit size, `1` meaning a 64-bit `largesize`
+ * follows, and `0` meaning the box runs to the end of the enclosing range. The last form is legal
+ * only for the outermost box in a file but appears in the wild inside `mdat`, so it is accepted
+ * anywhere and resolved against the cursor's end.
+ *
+ * A box whose declared size is smaller than its own header, or which claims to extend past the
+ * enclosing range, is corruption: both throw rather than being clamped, because a clamped size
+ * turns into a silently truncated payload much later.
+ *
+ * @param {ByteCursor} cursor
+ * @param {BoxHeader} header filled in place
+ * @returns {BoxHeader} `header`
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_box_header(cursor, header) {
+    const offset = cursor.position;
+
+    const size_field = cursor.u32();
+    const type = cursor.fourcc();
+
+    let size = size_field;
+
+    if (size_field === 1) {
+        size = cursor.u64();
+    } else if (size_field === 0) {
+        size = cursor.end - offset;
+    }
+
+    let user_type = null;
+
+    if (type === "uuid") {
+        user_type = cursor.view_bytes(16);
+    }
+
+    const header_size = cursor.position - offset;
+
+    if (size < header_size) {
+        throw new Error(`box '${type}' at ${offset} declares a size of ${size}, smaller than its ${header_size} byte header`);
+    }
+
+    if (offset + size > cursor.end) {
+        throw new Error(`box '${type}' at ${offset} extends ${offset + size - cursor.end} bytes past the end of its container`);
+    }
+
+    header.type = type;
+    header.offset = offset;
+    header.size = size;
+    header.payload_offset = cursor.position;
+    header.payload_size = size - header_size;
+    header.user_type = user_type;
+
+    return header;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Read the version and flags that begin a `FullBox` payload, packed into one number.
+ *
+ * Version and flags are returned together because almost every caller wants both and the pair is
+ * exactly a 32-bit field in the file. Unpack with {@link full_box_version} and
+ * {@link full_box_flags}; keeping them packed avoids allocating a pair per box.
+ *
+ * @param {ByteCursor} cursor
+ * @returns {number} `(version << 24) | flags`
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_full_box_header(cursor: ByteCursor): number;
+/**
+ * @param {number} version_and_flags
+ * @returns {number} `0 .. 255`
+ */
+export function full_box_version(version_and_flags: number): number;
+/**
+ * @param {number} version_and_flags
+ * @returns {number} `0 .. 2^24 - 1`
+ */
+export function full_box_flags(version_and_flags: number): number;
+//# sourceMappingURL=read_full_box_header.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"read_full_box_header.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/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/avif/native/isobmff/read_full_box_header.js

@@ -0,0 +1,33 @@
+/**
+ * Read the version and flags that begin a `FullBox` payload, packed into one number.
+ *
+ * Version and flags are returned together because almost every caller wants both and the pair is
+ * exactly a 32-bit field in the file. Unpack with {@link full_box_version} and
+ * {@link full_box_flags}; keeping them packed avoids allocating a pair per box.
+ *
+ * @param {ByteCursor} cursor
+ * @returns {number} `(version << 24) | flags`
+ * @see ISO/IEC 14496-12 section 4.2 "Object structure"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_full_box_header(cursor) {
+    return cursor.u32();
+}
+
+/**
+ * @param {number} version_and_flags
+ * @returns {number} `0 .. 255`
+ */
+export function full_box_version(version_and_flags) {
+    return (version_and_flags >>> 24) & 0xff;
+}
+
+/**
+ * @param {number} version_and_flags
+ * @returns {number} `0 .. 2^24 - 1`
+ */
+export function full_box_flags(version_and_flags) {
+    return version_and_flags & 0xffffff;
+}

package/src/avif/threaded_image_encoder.d.ts

@@ -16,8 +16,12 @@ export class ThreadedImageEncoder {
     slots: WorkerSlot[] | null;
     id_counter: number;
     pending_termination: number;
+    /** @type {boolean} set once it is known that this environment has no workers to give */
+    inline: boolean;
+    /** @type {Av1EncodeContext|null} used only on the inline path */
+    encoder: Av1EncodeContext | null;
     /**
-     * @param {ImageBitmap} bitmap — transferred to the worker; do not use after this call
+     * @param {ImageBitmap} bitmap — consumed; do not use after this call
      * @param {number} quality — 0..1
      * @param {number} [speed] — 0 (slowest, best) .. 10 (fastest)
      * @returns {Promise<ArrayBuffer>}
@@ -25,7 +29,8 @@ export class ThreadedImageEncoder {
     encode_bitmap(bitmap: ImageBitmap, quality: number, speed?: number): Promise<ArrayBuffer>;
     /**
      * @param {{ data: TypedArray, width: number, height: number, itemSize: number }} sampler2d
-     *   — sampler2d.data buffer is transferred to the worker; do not use after this call
+     *   — consumed; do not use after this call. The pool transfers the buffer to a worker, and the
+     *   inline path is entitled to the same freedom even though it does not take it
      * @param {number} quality — 0..1
      * @param {number} [speed] — 0 (slowest, best) .. 10 (fastest)
      * @returns {Promise<ArrayBuffer>}

package/src/avif/threaded_image_encoder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"threaded_image_encoder.d.ts","sourceRoot":"","sources":["../../../src/avif/threaded_image_encoder.js"],"names":[],"mappings":"AAgMA;;GAEG;AACH,8CAFa,oBAAoB,CAOhC;AA1ID;IACI;;OAEG;IACH,gDAFW;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAa7D;IAPG,qBAAgC;IAChC,wBAAsC;IAEtC,kCAAkC;IAClC,OADW,UAAU,EAAE,GAAG,IAAI,CACb;IACjB,mBAAmB;IACnB,4BAA6B;IA6DjC;;;;;OAKG;IACH,sBALW,WAAW,WACX,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAOhC;IAED;;;;;;OAMG;IACH;;eANsC,MAAM;gBAAU,MAAM;kBAAY,MAAM;gBAEnE,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAqBhC;IAED,iBASC;;CACJ;AAhLD;IACI,0CAcC;IAbG,YAAoB;IACpB,yBAA0B;IAC1B,gBAA4B;IA8BhC,2EAKC;IAED,4BAEC;IAED,kBAEC;;CACJ"}
+{"version":3,"file":"threaded_image_encoder.d.ts","sourceRoot":"","sources":["../../../src/avif/threaded_image_encoder.js"],"names":[],"mappings":"AAsRA;;GAEG;AACH,8CAFa,oBAAoB,CAOhC;AA1ND;IACI;;OAEG;IACH,gDAFW;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,EAmB7D;IAbG,qBAAgC;IAChC,wBAAsC;IAEtC,kCAAkC;IAClC,OADW,UAAU,EAAE,GAAG,IAAI,CACb;IACjB,mBAAmB;IACnB,4BAA6B;IAE7B,wFAAwF;IACxF,QADW,OAAO,CACC;IAEnB,iEAAiE;IACjE,SADW,mBAAiB,IAAI,CACb;IA6GvB;;;;;OAKG;IACH,sBALW,WAAW,WACX,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAYhC;IAED;;;;;;;OAOG;IACH;;eAPsC,MAAM;gBAAU,MAAM;kBAAY,MAAM;gBAGnE,MAAM,UACN,MAAM,GACJ,QAAQ,WAAW,CAAC,CAuBhC;IAED,iBASC;;CACJ;AA9OD;IACI,0CAcC;IAbG,YAAoB;IACpB,yBAA0B;IAC1B,gBAA4B;IA8BhC,2EAKC;IAED,4BAEC;IAED,kBAEC;;CACJ"}