@woosh/meep-engine 3.14.1 → 3.14.3

package/src/format/image/avif/color/ycbcr_row_to_rgb.js

@@ -0,0 +1,78 @@
+import { clamp01 } from "../../../../core/math/clamp01.js";
+import { CONVERSION_IDENTITY, CONVERSION_YCGCO } from "./ColourTransform.js";
+
+/**
+ * Convert one row of coded samples to normalised R, G and B.
+ *
+ * The chroma rows are already at full width — subsampling is the upsampler's problem, not this
+ * one's — and are floats because interpolation puts chroma between coded values.
+ *
+ * Output is clamped to `0 .. 1`. Chroma is coded independently of luma, so a lossy stream can ask
+ * for colours outside the cube; a display cannot show them and every later stage assumes it is in
+ * range.
+ *
+ * @param {ColourTransform} transform
+ * @param {Uint16Array} luma
+ * @param {number} luma_offset index of the first sample of the row
+ * @param {Float32Array} cb full width, in sample units
+ * @param {Float32Array} cr
+ * @param {number} width
+ * @param {Float32Array} destination `width * 3` long, interleaved
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function ycbcr_row_to_rgb(transform, luma, luma_offset, cb, cr, width, destination) {
+    const y_offset = transform.y_offset;
+    const y_scale = transform.y_scale;
+    const c_offset = transform.c_offset;
+    const c_scale = transform.c_scale;
+
+    if (transform.kind === CONVERSION_IDENTITY) {
+        // the planes are G, B and R already, and share the luma normalisation
+        for (let x = 0; x < width; x++) {
+            const i = x * 3;
+
+            destination[i] = clamp01((cr[x] - y_offset) * y_scale);
+            destination[i + 1] = clamp01((luma[luma_offset + x] - y_offset) * y_scale);
+            destination[i + 2] = clamp01((cb[x] - y_offset) * y_scale);
+        }
+
+        return;
+    }
+
+    if (transform.kind === CONVERSION_YCGCO) {
+        for (let x = 0; x < width; x++) {
+            const y = (luma[luma_offset + x] - y_offset) * y_scale;
+            const cg = (cb[x] - c_offset) * c_scale;
+            const co = (cr[x] - c_offset) * c_scale;
+
+            const t = y - cg;
+
+            const i = x * 3;
+
+            destination[i] = clamp01(t + co);
+            destination[i + 1] = clamp01(y + cg);
+            destination[i + 2] = clamp01(t - co);
+        }
+
+        return;
+    }
+
+    const cr_to_r = transform.cr_to_r;
+    const cb_to_g = transform.cb_to_g;
+    const cr_to_g = transform.cr_to_g;
+    const cb_to_b = transform.cb_to_b;
+
+    for (let x = 0; x < width; x++) {
+        const y = (luma[luma_offset + x] - y_offset) * y_scale;
+        const u = (cb[x] - c_offset) * c_scale;
+        const v = (cr[x] - c_offset) * c_scale;
+
+        const i = x * 3;
+
+        destination[i] = clamp01(y + cr_to_r * v);
+        destination[i + 1] = clamp01(y + cb_to_g * u + cr_to_g * v);
+        destination[i + 2] = clamp01(y + cb_to_b * u);
+    }
+}

package/src/format/image/avif/heif/AvifFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AvifFile.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/AvifFile.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH;IACI,iGAAiG;IACjG,QADW,MAAM,CACN;IAEX,qBAAqB;IACrB,QADW,MAAM,CACN;CACd;;;;iCAIS,MAAM;;;;;;AAQhB;;GAEG;AACH;IACI,qBAAqB;IACrB,IADW,MAAM,CACV;IAEP,yFAAyF;IACzF,WADW,MAAM,CACF;IAEf,qBAAqB;IACrB,WADW,MAAM,CACF;IAEf,sCAAsC;IACtC,cADW,MAAM,CACC;IAElB,6CAA6C;IAC7C,qBADW,MAAM,CACoC;IAErD,qBAAqB;IACrB,sBADW,MAAM,CACQ;IAEzB,qBAAqB;IACrB,aADW,MAAM,CACD;IAEhB,2BAA2B;IAC3B,SADW,UAAU,EAAE,CACV;IAEb,wEAAwE;IACxE,kBADW,MAAM,EAAE,CACG;IAEtB,6DAA6D;IAC7D,oBADW,OAAO,EAAE,CACI;IAExB,8DAA8D;IAC9D,QADW,OAAO,CACH;CAClB;AAED;;GAEG;AACH;IACI,8FAA8F;IAC9F,gBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,cADW,MAAM,CACA;IAEjB,uBAAuB;IACvB,aADW,MAAM,EAAE,CACF;CACpB;AAED;;GAEG;AACH;IACI,qBAAqB;IACrB,MADW,MAAM,CACR;IAET,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,cADW,MAAM,CACA;IAEjB,qBAAqB;IACrB,eADW,MAAM,CACC;CACrB;AAED;;GAEG;AACH;IACI,qBAAqB;IACrB,aADW,MAAM,CACA;IAEjB,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,uBAAuB;IACvB,mBADW,MAAM,EAAE,CACI;IAEvB,+CAA+C;IAC/C,iBADW,MAAM,CACG;IAEpB,oCAAoC;IACpC,OADW,IAAI,MAAM,EAAE,QAAQ,CAAC,CACd;IAElB;;;;OAIG;IACH,YAFU,MAAM,EAAE,CAEF;IAEhB,8BAA8B;IAC9B,YADW,aAAa,EAAE,CACV;IAEhB,4EAA4E;IAC5E,WADW,UAAU,GAAC,IAAI,CACT;IAEjB,oFAAoF;IACpF,OADW,UAAU,CACK;IAE1B,wFAAwF;IACxF,oBADW,OAAO,CACS;CAC9B"}

package/src/format/image/avif/heif/ItemProperty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ItemProperty.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/ItemProperty.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,OADW,MAAM,CACP;IAEV,qBAAqB;IACrB,QADW,MAAM,CACN;CACd;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,yBAAyB;IACzB,kBADW,UAAU,CACgB;CACxC;AAED;;;GAGG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,SADW,MAAM,CACL;IAEZ,qBAAqB;IACrB,aADW,MAAM,CACD;IAEhB,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,YADW,MAAM,CACF;IAEf,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,YADW,MAAM,CACF;IAEf,qBAAqB;IACrB,YADW,MAAM,CACF;IAEf,qBAAqB;IACrB,sBADW,MAAM,CACQ;IAEzB,qBAAqB;IACrB,sBADW,MAAM,CACQ;IAEzB,qBAAqB;IACrB,wBADW,MAAM,CACU;IAE3B,sCAAsC;IACtC,sCADW,MAAM,CACyB;IAE1C,yBAAyB;IACzB,aADW,UAAU,CACW;CACnC;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,8CAA8C;IAC9C,aADW,MAAM,CACI;IAErB,2CAA2C;IAC3C,kBADW,MAAM,CACI;IAErB,mDAAmD;IACnD,0BADW,MAAM,CACY;IAE7B,8CAA8C;IAC9C,qBADW,MAAM,CACO;IAExB,gEAAgE;IAChE,iBADW,MAAM,CACG;IAEpB,uEAAuE;IACvE,aADW,UAAU,GAAC,IAAI,CACP;CACtB;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,WADW,MAAM,CACH;IAEd,qBAAqB;IACrB,WADW,MAAM,CACH;CACjB;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,iBADW,MAAM,CACG;IAEpB,qBAAqB;IACrB,mBADW,MAAM,CACK;IAEtB,qBAAqB;IACrB,kBADW,MAAM,CACI;IAErB,qBAAqB;IACrB,oBADW,MAAM,CACM;IAEvB,qBAAqB;IACrB,6BADW,MAAM,CACe;IAEhC,qBAAqB;IACrB,+BADW,MAAM,CACiB;IAElC,qBAAqB;IACrB,2BADW,MAAM,CACa;IAE9B,qBAAqB;IACrB,6BADW,MAAM,CACe;CACnC;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,oEAAoE;IACpE,OADW,MAAM,CACP;CACb;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,gGAAgG;IAChG,MADW,MAAM,CACR;CACZ;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,UADW,MAAM,CACH;IAEd,yBAAyB;IACzB,aADW,UAAU,CACW;CACnC;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,yBADW,MAAM,CACW;IAE5B,qBAAqB;IACrB,6BADW,MAAM,CACe;CACnC;AAED;;;GAGG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,+DAA+D;IAC/D,mBADW,WAAW,CACiB;IAEvC,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,iCADW,MAAM,CACmB;IAEpC,qBAAqB;IACrB,iCADW,MAAM,CACmB;CACvC;AAED;;;GAGG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,yBAAyB;IACzB,SADW,UAAU,CACO;CAC/B;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,UADW,MAAM,CACJ;CAChB;AAED;;GAEG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,qBAAqB;IACrB,UADW,MAAM,CACJ;CAChB;AAED;;;GAGG;AACH;IACI,oBAAqB;IAErB,qBAAqB;IACrB,MADW,MAAM,CACH;IAEd,0BAA0B;IAC1B,YADW,WAAW,CACU;CACnC;AAED;;;GAGG;AACH;IACI,qBAAqB;IACrB,MADW,MAAM,CACP;IAEV,yBAAyB;IACzB,SADW,UAAU,CACO;CAC/B"}

package/src/format/image/avif/heif/find_item_property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find_item_property.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/find_item_property.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,yEANW,MAAM,GACJ,MAAM,GAAC,IAAI,CAiBvB"}

package/src/format/image/avif/heif/find_item_references.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find_item_references.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/find_item_references.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,mEAPW,MAAM,kBACN,MAAM,GACJ,MAAM,EAAE,CAmBpB"}

package/src/format/image/avif/heif/find_items_referencing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find_items_referencing.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/find_items_referencing.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,mEAPW,MAAM,kBACN,MAAM,GACJ,MAAM,EAAE,CAyBpB"}

package/src/format/image/avif/heif/parse_avif_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_avif_file.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/parse_avif_file.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;GAWG;AACH,wCANW,WAAW,GAAC,UAAU,GACpB,QAAQ,CAwCpB;yBA1D6D,eAAe"}

package/src/format/image/avif/heif/parse_avif_file.js

@@ -0,0 +1,384 @@
+import { for_each_box } from "../isobmff/for_each_box.js";
+import { ByteCursor } from "../../../../core/binary/ByteCursor.js";
+import { EndianType } from "../../../../core/binary/EndianType.js";
+import { full_box_flags, full_box_version, read_full_box_header } from "../isobmff/read_full_box_header.js";
+import { AvifFile, AvifItem, ItemExtent, ItemReference } from "./AvifFile.js";
+import { parse_item_property } from "./parse_item_property.js";
+
+/**
+ * Ceiling on counts read from the file before they are used to size anything. A real AVIF has a
+ * handful of items and properties; a count in the millions is corruption, and without a ceiling it
+ * becomes a multi-gigabyte allocation or a loop that never ends.
+ * @type {number}
+ */
+const MAX_ENTRIES = 65536;
+
+/**
+ * Parse an AVIF file into its item model.
+ *
+ * Only structure is read: item payloads are located, not decoded, and their bytes are left in
+ * place. Nothing is copied out of `buffer`.
+ *
+ * @param {ArrayBuffer|Uint8Array} buffer
+ * @returns {AvifFile}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function parse_avif_file(buffer) {
+    const file = new AvifFile();
+
+    const cursor = new ByteCursor().init(buffer, EndianType.BigEndian);
+
+    file.bytes = cursor.bytes.subarray(0, cursor.end);
+
+    let saw_ftyp = false;
+    let saw_meta = false;
+
+    for_each_box(cursor, (header, box_cursor) => {
+        if (header.type === "ftyp") {
+            read_ftyp(file, box_cursor, header.end);
+
+            saw_ftyp = true;
+        } else if (header.type === "meta") {
+            read_meta(file, box_cursor, header.end);
+
+            saw_meta = true;
+        } else if (header.type === "moov") {
+            file.has_image_sequence = true;
+        }
+    });
+
+    if (!saw_ftyp) {
+        throw new Error("not an ISOBMFF file: no ftyp box");
+    }
+
+    if (!saw_meta) {
+        throw new Error("not an AVIF file: no meta box");
+    }
+
+    resolve_item_offsets(file);
+
+    return file;
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ftyp(file, cursor, end) {
+    file.major_brand = cursor.fourcc();
+    file.minor_version = cursor.u32();
+
+    while (cursor.position + 4 <= end) {
+        file.compatible_brands.push(cursor.fourcc());
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_meta(file, cursor, end) {
+    read_full_box_header(cursor);
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        switch (header.type) {
+            case "pitm":
+                read_pitm(file, box_cursor);
+                break;
+            case "iloc":
+                read_iloc(file, box_cursor);
+                break;
+            case "iinf":
+                read_iinf(file, box_cursor, header.end);
+                break;
+            case "iref":
+                read_iref(file, box_cursor, header.end);
+                break;
+            case "iprp":
+                read_iprp(file, box_cursor, header.end);
+                break;
+            case "idat":
+                file.item_data = box_cursor.view_bytes(header.payload_size);
+                break;
+            default:
+                break;
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_pitm(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    file.primary_item_id = version === 0 ? cursor.u16() : cursor.u32();
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {number} id
+ * @returns {AvifItem}
+ */
+function item_for_id(file, id) {
+    let item = file.items.get(id);
+
+    if (item === undefined) {
+        item = new AvifItem();
+        item.id = id;
+
+        file.items.set(id, item);
+    }
+
+    return item;
+}
+
+/**
+ * @param {number} count
+ * @param {string} what
+ */
+function check_count(count, what) {
+    if (count > MAX_ENTRIES) {
+        throw new Error(`${what} declares ${count} entries, beyond the ${MAX_ENTRIES} supported`);
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ */
+function read_iloc(file, cursor) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const sizes = cursor.u8();
+    const offset_size = (sizes >> 4) & 0xf;
+    const length_size = sizes & 0xf;
+
+    const base_and_index = cursor.u8();
+    const base_offset_size = (base_and_index >> 4) & 0xf;
+    const index_size = version === 1 || version === 2 ? base_and_index & 0xf : 0;
+
+    const item_count = version < 2 ? cursor.u16() : cursor.u32();
+
+    check_count(item_count, "iloc");
+
+    for (let i = 0; i < item_count; i++) {
+        const id = version < 2 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        if (version === 1 || version === 2) {
+            item.construction_method = cursor.u16() & 0xf;
+        }
+
+        item.data_reference_index = cursor.u16();
+        item.base_offset = cursor.uint_of_size(base_offset_size);
+
+        const extent_count = cursor.u16();
+
+        check_count(extent_count, "iloc extents");
+
+        for (let j = 0; j < extent_count; j++) {
+            if (index_size > 0) {
+                cursor.uint_of_size(index_size);
+            }
+
+            const extent = new ItemExtent();
+
+            extent.offset = cursor.uint_of_size(offset_size);
+            extent.length = cursor.uint_of_size(length_size);
+
+            item.extents.push(extent);
+        }
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.6 "Item information box"
+ */
+function read_iinf(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const entry_count = version === 0 ? cursor.u16() : cursor.u32();
+
+    check_count(entry_count, "iinf");
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type !== "infe") {
+            return;
+        }
+
+        read_infe(file, box_cursor, header.end);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_infe(file, cursor, end) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const flags = full_box_flags(version_and_flags);
+
+    if (version < 2) {
+        // versions 0 and 1 have no item_type field at all, so an item's nature can only be guessed
+        // from its name. No AVIF writer emits them; refusing is better than guessing.
+        throw new Error(`infe version ${version} is not supported by AVIF`);
+    }
+
+    const id = version === 2 ? cursor.u16() : cursor.u32();
+
+    const item = item_for_id(file, id);
+
+    cursor.u16();
+
+    item.item_type = cursor.fourcc();
+    item.item_name = cursor.utf8_string();
+    item.hidden = (flags & 1) !== 0;
+
+    if (item.item_type === "mime" && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    } else if (item.item_type === "uri " && cursor.position < end) {
+        item.content_type = cursor.utf8_string();
+    }
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 14496-12 section 8.11.12 "Item reference box"
+ */
+function read_iref(file, cursor, end) {
+    const version = full_box_version(read_full_box_header(cursor));
+
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        const reference = new ItemReference();
+
+        reference.reference_type = header.type;
+        reference.from_item_id = version === 0 ? box_cursor.u16() : box_cursor.u32();
+
+        const count = box_cursor.u16();
+
+        check_count(count, "iref");
+
+        for (let i = 0; i < count; i++) {
+            reference.to_item_ids.push(version === 0 ? box_cursor.u16() : box_cursor.u32());
+        }
+
+        file.references.push(reference);
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ * @see ISO/IEC 23008-12 section 9.3 "Item properties"
+ */
+function read_iprp(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        if (header.type === "ipco") {
+            read_ipco(file, box_cursor, header.end);
+        } else if (header.type === "ipma") {
+            read_ipma(file, box_cursor);
+        }
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ * @param {number} end
+ */
+function read_ipco(file, cursor, end) {
+    const children = cursor.sub_cursor(cursor.position, end - cursor.position);
+
+    for_each_box(children, (header, box_cursor) => {
+        file.properties.push(parse_item_property(header.type, box_cursor, header.payload_size));
+    });
+}
+
+/**
+ * @param {AvifFile} file
+ * @param {ByteCursor} cursor
+ */
+function read_ipma(file, cursor) {
+    const version_and_flags = read_full_box_header(cursor);
+    const version = full_box_version(version_and_flags);
+    const wide_indices = (full_box_flags(version_and_flags) & 1) !== 0;
+
+    const entry_count = cursor.u32();
+
+    check_count(entry_count, "ipma");
+
+    for (let i = 0; i < entry_count; i++) {
+        const id = version < 1 ? cursor.u16() : cursor.u32();
+
+        const item = item_for_id(file, id);
+
+        const association_count = cursor.u8();
+
+        for (let j = 0; j < association_count; j++) {
+            let essential;
+            let index;
+
+            if (wide_indices) {
+                const packed = cursor.u16();
+
+                essential = (packed & 0x8000) !== 0;
+                index = packed & 0x7fff;
+            } else {
+                const packed = cursor.u8();
+
+                essential = (packed & 0x80) !== 0;
+                index = packed & 0x7f;
+            }
+
+            // index 0 means "no property"; the specification allows it and it must not be treated
+            // as a reference to the first property
+            if (index === 0) {
+                continue;
+            }
+
+            item.property_indices.push(index);
+            item.property_essential.push(essential);
+        }
+    }
+}
+
+/**
+ * Fold `base_offset` into each extent, so consumers see absolute offsets and never have to know
+ * which of the three construction methods produced them.
+ *
+ * Method 1 offsets are relative to `idat` and method 2 to another item; both are left in their own
+ * space and resolved by {@link read_item_data}, which is the only place that can see the target.
+ *
+ * @param {AvifFile} file
+ */
+function resolve_item_offsets(file) {
+    for (const item of file.items.values()) {
+        for (let i = 0; i < item.extents.length; i++) {
+            item.extents[i].offset += item.base_offset;
+        }
+    }
+}

package/src/format/image/avif/heif/parse_image_grid.d.ts.map

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

package/src/format/image/avif/heif/parse_image_grid.js

@@ -0,0 +1,49 @@
+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/format/image/avif/heif/parse_item_property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse_item_property.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/parse_item_property.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;GAeG;AACH,0CATW,MAAM,oCAEN,MAAM,GACJ,MAAM,CAoNlB"}

package/src/format/image/avif/heif/read_item_data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read_item_data.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/read_item_data.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,uEAPW,MAAM,GACJ,UAAU,CAgDtB"}

package/src/format/image/avif/heif/write_avif_file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_avif_file.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/write_avif_file.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;kBAZW,MAAM;oBACN,MAAM;wBACN,MAAM,EAAE;qBACR,MAAM;;YACK,MAAM;mBAAa,MAAM;oBAAc,MAAM;uBAAiB,MAAM;iBAAW,OAAO;qBAAe,MAAM,EAAE;oBAAc,OAAO,EAAE;cAAQ,UAAU;;iBACjK,MAAM;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,EAAE,CAAA;KAAC,CAAC;IAC1E,WAAW,CA0CvB"}

package/src/format/image/avif/heif/write_item_property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write_item_property.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/heif/write_item_property.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,iEANW,MAAM,QA6KhB"}

package/src/format/image/avif/index.d.ts

@@ -0,0 +1,12 @@
+export { AvifDecoder } from "./api/AvifDecoder.js";
+export { Av1EncodeContext } from "./av1/encode/Av1EncodeContext.js";
+export { decode_avif } from "./api/decode_avif.js";
+export { LINEAR_REFERENCE_NITS } from "./color/transfer_to_linear.js";
+export { YuvImage } from "./color/YuvImage.js";
+export { parse_avif_file } from "./heif/parse_avif_file.js";
+export { write_avif_file } from "./heif/write_avif_file.js";
+export { encode_avif, SUBSAMPLING_400, SUBSAMPLING_420, SUBSAMPLING_422, SUBSAMPLING_444 } from "./api/encode_avif.js";
+export { CHROMA_UPSAMPLING_AUTOMATIC, CHROMA_UPSAMPLING_BEST, CHROMA_UPSAMPLING_FASTEST, COLOUR_SPACE_LINEAR, COLOUR_SPACE_SIGNAL, convert_to_rgba } from "./api/convert_to_rgba.js";
+export { EFFORT_BALANCED, EFFORT_FAST, EFFORT_THOROUGH } from "./av1/encode/encode_effort.js";
+export { DECODE_BALANCED, DECODE_FAST, DECODE_THOROUGH } from "./av1/encode/decode_effort.js";
+//# sourceMappingURL=index.d.ts.map

package/src/format/image/avif/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/avif/index.js"],"names":[],"mappings":""}

package/src/format/image/avif/index.js

@@ -0,0 +1,58 @@
+/**
+ * A pure JavaScript AVIF codec: the ISOBMFF container, the AV1 still picture coding tools that
+ * AVIF uses, and the colour handling between them.
+ *
+ * Nothing here touches the filesystem, a worker, a canvas or WebAssembly, so the same code runs in
+ * a browser, in node and in whatever else has a JavaScript engine. Everything is synchronous.
+ *
+ * Nothing here touches the engine either — `format_tier_boundary.spec.js` holds that. The two
+ * `Sampler2D` adapters, `avif_to_sampler2d` and `sampler2d_to_avif`, live beside the type they
+ * serve in `engine/graphics/texture/sampler/`, and the worker pool that encodes off the main thread
+ * is `engine/asset/loaders/image/avif/`.
+ *
+ * The decoder reads what libavif writes, sample for sample. The encoder writes what libavif reads,
+ * sample for sample. Both claims are checked rather than asserted — see `tools/` for how.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+export { AvifDecoder } from "./api/AvifDecoder.js";
+export { Av1EncodeContext } from "./av1/encode/Av1EncodeContext.js";
+
+export { decode_avif } from "./api/decode_avif.js";
+export { encode_avif } from "./api/encode_avif.js";
+
+export {
+    CHROMA_UPSAMPLING_AUTOMATIC,
+    CHROMA_UPSAMPLING_BEST,
+    CHROMA_UPSAMPLING_FASTEST,
+    COLOUR_SPACE_LINEAR,
+    COLOUR_SPACE_SIGNAL,
+    convert_to_rgba
+} from "./api/convert_to_rgba.js";
+
+export {
+    SUBSAMPLING_400,
+    SUBSAMPLING_420,
+    SUBSAMPLING_422,
+    SUBSAMPLING_444
+} from "./api/encode_avif.js";
+
+export {
+    EFFORT_BALANCED,
+    EFFORT_FAST,
+    EFFORT_THOROUGH
+} from "./av1/encode/encode_effort.js";
+
+export {
+    DECODE_BALANCED,
+    DECODE_FAST,
+    DECODE_THOROUGH
+} from "./av1/encode/decode_effort.js";
+
+export { LINEAR_REFERENCE_NITS } from "./color/transfer_to_linear.js";
+export { YuvImage } from "./color/YuvImage.js";
+
+export { parse_avif_file } from "./heif/parse_avif_file.js";
+export { write_avif_file } from "./heif/write_avif_file.js";

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

@@ -0,0 +1 @@
+{"version":3,"file":"BoxHeader.d.ts","sourceRoot":"","sources":["../../../../../../src/format/image/avif/isobmff/BoxHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;OAIG;IACH,WAFU,UAAU,GAAC,IAAI,CAER;IAEjB;;;OAGG;IACH,kBAEC;CACJ"}