@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/color/transfer_to_linear.js

@@ -0,0 +1,171 @@
+import { PQ_MAX_NITS } from "../../../core/color/PQ/PQ_constants.js";
+import { PQ_to_linear } from "../../../core/color/PQ/PQ_to_linear.js";
+import {
+    TC_BT_1361,
+    TC_BT_2020_10_BIT,
+    TC_BT_2020_12_BIT,
+    TC_BT_470_B_G,
+    TC_BT_470_M,
+    TC_BT_601,
+    TC_BT_709,
+    TC_HLG,
+    TC_IEC_61966,
+    TC_LINEAR,
+    TC_LOG_100,
+    TC_LOG_100_SQRT10,
+    TC_SMPTE_2084,
+    TC_SMPTE_240,
+    TC_SMPTE_428,
+    TC_SRGB
+} from "../av1/tables/av1_symbols.js";
+import { convert_channel_sRGB_to_linear } from "../../../core/color/sRGB/sRGB_to_linear.js";
+
+/**
+ * Luminance that a linear value of `1.0` stands for, in nits.
+ *
+ * Every transfer function here decodes to this normalisation, so that SDR content lands at `1.0`
+ * whatever curve carried it and HDR content simply goes above it.
+ *
+ * A hundred rather than the engine's 203 deliberately, and it is not a renderer setting. The SDR
+ * curves in H.273 table 3 — BT.709, sRGB, gamma 2.2, gamma 2.8 — are defined against a hundred nit
+ * reference display, so signal `1.0` decoding to linear `1.0` is their own fixed point rather than
+ * a convention this file picks. Setting it to `SDR_WHITE_NITS` would land sRGB white at 0.4926 and
+ * make this module a statement about meep instead of a statement about the standard.
+ *
+ * 203 nits is a rendering convention (BT.2408 graphics white on an HDR display), so it lives on the
+ * renderer's side of the boundary: `sampler2d_to_avif` and `avif_to_sampler2d` each name their
+ * white to the codec through `linear_reference_nits`, and that is where the two meet.
+ * @type {number}
+ */
+export const LINEAR_REFERENCE_NITS = 100;
+
+/**
+ * Peak luminance an HLG signal is decoded against, in nits. The curve carries no absolute luminance
+ * of its own, and this is the reference display ITU-R BT.2100 defines its system gamma on.
+ * @type {number}
+ */
+export const HLG_PEAK_NITS = 1000;
+
+/** @type {number} */
+const HLG_A = 0.17883277;
+
+/** @type {number} */
+const HLG_B = 1 - 4 * HLG_A;
+
+/** @type {number} */
+const HLG_C = 0.5 - HLG_A * Math.log(4 * HLG_A);
+
+/**
+ * Decode one signal value to linear light.
+ *
+ * HLG is the exception: what comes back is *scene* linear, because its opto-optical transfer
+ * function is a function of the picture's luminance rather than of one channel. Completing it is
+ * {@link transfer_row_to_linear}'s job, which is why nothing should call this directly for HLG.
+ *
+ * @param {number} transfer_characteristics a `TC_*` code
+ * @param {number} value signal, `0 .. 1`
+ * @returns {number} linear light, `1.0` being {@link LINEAR_REFERENCE_NITS}
+ * @see ITU-T H.273 table 3 "Transfer characteristics"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function transfer_to_linear(transfer_characteristics, value) {
+    switch (transfer_characteristics) {
+        case TC_SMPTE_2084:
+            return PQ_to_linear(value) * (PQ_MAX_NITS / LINEAR_REFERENCE_NITS);
+
+        case TC_HLG:
+            return hlg_to_scene_linear(value);
+
+        case TC_LINEAR:
+            return value;
+
+        case TC_SRGB:
+        case TC_IEC_61966:
+            return convert_channel_sRGB_to_linear(value);
+
+        case TC_BT_470_M:
+            return value <= 0 ? 0 : Math.pow(value, 2.2);
+
+        case TC_BT_470_B_G:
+            return value <= 0 ? 0 : Math.pow(value, 2.8);
+
+        case TC_SMPTE_428:
+            // defined as 48 nits out of a 52.37 nit projector, and that ratio is part of the
+            // standard rather than a rounding artefact
+            return Math.pow(value, 2.6) * (52.37 / 48.0);
+
+        case TC_LOG_100:
+            return value <= 0 ? 0 : Math.pow(10, (value - 1) * 2);
+
+        case TC_LOG_100_SQRT10:
+            return value <= 0 ? 0 : Math.pow(10, (value - 1) * 2.5);
+
+        case TC_SMPTE_240:
+            return value < 0.0913 ? value / 4.0 : Math.pow((value + 0.1115) / 1.1115, 1 / 0.45);
+
+        // BT.709 and everything sharing its curve, which is also what an unspecified or reserved
+        // code is taken to mean
+        case TC_BT_709:
+        case TC_BT_601:
+        case TC_BT_2020_10_BIT:
+        case TC_BT_2020_12_BIT:
+        case TC_BT_1361:
+        default:
+            return value < 0.081 ? value / 4.5 : Math.pow((value + 0.099) / 1.099, 1 / 0.45);
+    }
+}
+
+/**
+ * Decode a row of interleaved RGB to linear light, in place.
+ *
+ * @param {number} transfer_characteristics a `TC_*` code
+ * @param {Float32Array} row interleaved, `width * 3` long
+ * @param {number} width
+ */
+export function transfer_row_to_linear(transfer_characteristics, row, width) {
+    const count = width * 3;
+
+    if (transfer_characteristics === TC_LINEAR) {
+        return;
+    }
+
+    for (let i = 0; i < count; i++) {
+        row[i] = transfer_to_linear(transfer_characteristics, row[i]);
+    }
+
+    if (transfer_characteristics !== TC_HLG) {
+        return;
+    }
+
+    // the opto-optical transfer function, which takes HLG from scene to display referred. It scales
+    // all three channels by a power of the *scene luminance*, so it cannot be folded into the
+    // per-channel curve above
+    const scale = HLG_PEAK_NITS / LINEAR_REFERENCE_NITS;
+
+    for (let i = 0; i < count; i += 3) {
+        const luminance = 0.2627 * row[i] + 0.6780 * row[i + 1] + 0.0593 * row[i + 2];
+
+        const gain = luminance <= 0 ? 0 : Math.pow(luminance, 0.2) * scale;
+
+        row[i] *= gain;
+        row[i + 1] *= gain;
+        row[i + 2] *= gain;
+    }
+}
+
+/**
+ * Hybrid log-gamma's inverse opto-electronic transfer function.
+ *
+ * @param {number} value
+ * @returns {number} scene linear, `0 .. 1`
+ * @see ITU-R BT.2100 table 5
+ */
+function hlg_to_scene_linear(value) {
+    if (value <= 0.5) {
+        return (value * value) / 3;
+    }
+
+    return (Math.exp((value - HLG_C) / HLG_A) + HLG_B) / 12;
+}

package/src/avif/native/color/upsample_chroma_row.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Expand one row of a subsampled chroma plane to full width.
+ *
+ * @param {Uint16Array} plane
+ * @param {number} stride
+ * @param {number} plane_width in chroma samples
+ * @param {number} plane_height in chroma samples
+ * @param {number} sub_x
+ * @param {number} sub_y
+ * @param {number} row the *luma* row wanted
+ * @param {number} width full width, in luma samples
+ * @param {number} mode one of the `UPSAMPLE_*` constants
+ * @param {Float32Array} destination at least `width` long
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function upsample_chroma_row(plane: Uint16Array, stride: number, plane_width: number, plane_height: number, sub_x: number, sub_y: number, row: number, width: number, mode: number, destination: Float32Array): void;
+/**
+ * Repeat the nearest chroma sample. What every fast decoder does, and what the reference decoder was
+ * driven with when the fixtures were minted.
+ * @type {number}
+ */
+export const UPSAMPLE_NEAREST: number;
+/**
+ * Interpolate between chroma samples, treating each as centred on the luma samples it covers.
+ *
+ * The bitstream can signal where the chroma samples actually sit, but only for 4:2:0 and only as
+ * "left" or "top left"; in practice it is almost always left unknown. Centred is the choice that
+ * neither shifts the image nor favours one edge, which matters more here than matching any
+ * particular other decoder — nothing in the format makes one interpolation normative.
+ * @type {number}
+ */
+export const UPSAMPLE_BILINEAR: number;
+//# sourceMappingURL=upsample_chroma_row.d.ts.map

package/src/avif/native/color/upsample_chroma_row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upsample_chroma_row.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/color/upsample_chroma_row.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;GAgBG;AACH,2CAdW,WAAW,UACX,MAAM,eACN,MAAM,gBACN,MAAM,SACN,MAAM,SACN,MAAM,OACN,MAAM,SACN,MAAM,QACN,MAAM,eACN,YAAY,QAwDtB;AAtFD;;;;GAIG;AACH,+BAFU,MAAM,CAEkB;AAElC;;;;;;;;GAQG;AACH,gCAFU,MAAM,CAEmB"}

package/src/avif/native/color/upsample_chroma_row.js

@@ -0,0 +1,89 @@
+import { clamp_index } from "../../../core/math/clamp_index.js";
+
+/**
+ * Repeat the nearest chroma sample. What every fast decoder does, and what the reference decoder was
+ * driven with when the fixtures were minted.
+ * @type {number}
+ */
+export const UPSAMPLE_NEAREST = 0;
+
+/**
+ * Interpolate between chroma samples, treating each as centred on the luma samples it covers.
+ *
+ * The bitstream can signal where the chroma samples actually sit, but only for 4:2:0 and only as
+ * "left" or "top left"; in practice it is almost always left unknown. Centred is the choice that
+ * neither shifts the image nor favours one edge, which matters more here than matching any
+ * particular other decoder — nothing in the format makes one interpolation normative.
+ * @type {number}
+ */
+export const UPSAMPLE_BILINEAR = 1;
+
+/**
+ * Expand one row of a subsampled chroma plane to full width.
+ *
+ * @param {Uint16Array} plane
+ * @param {number} stride
+ * @param {number} plane_width in chroma samples
+ * @param {number} plane_height in chroma samples
+ * @param {number} sub_x
+ * @param {number} sub_y
+ * @param {number} row the *luma* row wanted
+ * @param {number} width full width, in luma samples
+ * @param {number} mode one of the `UPSAMPLE_*` constants
+ * @param {Float32Array} destination at least `width` long
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function upsample_chroma_row(plane, stride, plane_width, plane_height, sub_x, sub_y, row, width, mode, destination) {
+    if (sub_x === 0 && sub_y === 0) {
+        const offset = row * stride;
+
+        for (let x = 0; x < width; x++) {
+            destination[x] = plane[offset + x];
+        }
+
+        return;
+    }
+
+    if (mode === UPSAMPLE_NEAREST) {
+        const offset = (row >> sub_y) * stride;
+
+        for (let x = 0; x < width; x++) {
+            const sample_x = x >> sub_x;
+
+            destination[x] = plane[offset + (sample_x < plane_width ? sample_x : plane_width - 1)];
+        }
+
+        return;
+    }
+
+    // vertical position of this luma row within the chroma grid, as a sample index plus a fraction
+    const source_y = sub_y === 0 ? row : (row - 0.5) * 0.5;
+
+    const top = Math.floor(source_y);
+    const weight_y = source_y - top;
+
+    const row_top = clamp_index(top, plane_height) * stride;
+    const row_bottom = clamp_index(top + 1, plane_height) * stride;
+
+    for (let x = 0; x < width; x++) {
+        const source_x = sub_x === 0 ? x : (x - 0.5) * 0.5;
+
+        const left = Math.floor(source_x);
+        const weight_x = source_x - left;
+
+        const column_left = clamp_index(left, plane_width);
+        const column_right = clamp_index(left + 1, plane_width);
+
+        const top_left = plane[row_top + column_left];
+        const top_right = plane[row_top + column_right];
+        const bottom_left = plane[row_bottom + column_left];
+        const bottom_right = plane[row_bottom + column_right];
+
+        const above = top_left + (top_right - top_left) * weight_x;
+        const below = bottom_left + (bottom_right - bottom_left) * weight_x;
+
+        destination[x] = above + (below - above) * weight_y;
+    }
+}

package/src/avif/native/color/ycbcr_row_to_rgb.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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: ColourTransform, luma: Uint16Array, luma_offset: number, cb: Float32Array, cr: Float32Array, width: number, destination: Float32Array): void;
+//# sourceMappingURL=ycbcr_row_to_rgb.d.ts.map

package/src/avif/native/color/ycbcr_row_to_rgb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ycbcr_row_to_rgb.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/color/ycbcr_row_to_rgb.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,mEAVW,WAAW,eACX,MAAM,MACN,YAAY,MACZ,YAAY,SACZ,MAAM,eACN,YAAY,QA0DtB"}

package/src/avif/native/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/avif/native/heif/AvifFile.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Parsed model of an AVIF file.
+ *
+ * The structs here mirror the file rather than the image: `parse_avif_file` fills them in, and
+ * everything above it — deciding which item is the picture, resolving a grid, finding the alpha
+ * plane — works from this model instead of re-walking boxes.
+ *
+ * @see ISO/IEC 23008-12 "HEIF"
+ * @see ISO/IEC 23000-22 "AVIF"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * One extent of an item's data. Items may be stored in pieces, and the pieces may be anywhere.
+ */
+export class ItemExtent {
+    /** @type {number} absolute offset, once `base_offset` and the construction method are applied */
+    offset: number;
+    /** @type {number} */
+    length: number;
+}
+/**
+ * How an item's extent offsets should be interpreted.
+ */
+export type ConstructionMethod = number;
+export namespace ConstructionMethod {
+    let FILE_OFFSET: number;
+    let IDAT_OFFSET: number;
+    let ITEM_OFFSET: number;
+}
+/**
+ * One item from `iinf` / `iloc`.
+ */
+export class AvifItem {
+    /** @type {number} */
+    id: number;
+    /** @type {string} four character item type: `av01`, `grid`, `Exif`, `mime`, `tmap`, … */
+    item_type: string;
+    /** @type {string} */
+    item_name: string;
+    /** @type {string} for `mime` items */
+    content_type: string;
+    /** @type {number} @see ConstructionMethod */
+    construction_method: number;
+    /** @type {number} */
+    data_reference_index: number;
+    /** @type {number} */
+    base_offset: number;
+    /** @type {ItemExtent[]} */
+    extents: ItemExtent[];
+    /** @type {number[]} 1-based indices into {@link AvifFile.properties} */
+    property_indices: number[];
+    /** @type {boolean[]} parallel to {@link property_indices} */
+    property_essential: boolean[];
+    /** @type {boolean} set from `iinf`'s per-entry hidden flag */
+    hidden: boolean;
+}
+/**
+ * One `iref` entry: a typed reference from one item to several others.
+ */
+export class ItemReference {
+    /** @type {string} four character reference type: `dimg`, `auxl`, `thmb`, `cdsc`, `prem`, … */
+    reference_type: string;
+    /** @type {number} */
+    from_item_id: number;
+    /** @type {number[]} */
+    to_item_ids: number[];
+}
+/**
+ * The `grid` derived-image payload. Not a box: this is the item's own data.
+ */
+export class ImageGrid {
+    /** @type {number} */
+    rows: number;
+    /** @type {number} */
+    columns: number;
+    /** @type {number} */
+    output_width: number;
+    /** @type {number} */
+    output_height: number;
+}
+/**
+ * A whole parsed file.
+ */
+export class AvifFile {
+    /** @type {string} */
+    major_brand: string;
+    /** @type {number} */
+    minor_version: number;
+    /** @type {string[]} */
+    compatible_brands: string[];
+    /** @type {number} `0` when `pitm` is absent */
+    primary_item_id: number;
+    /** @type {Map<number, AvifItem>} */
+    items: Map<number, AvifItem>;
+    /**
+     * Properties from `ipco`, in file order. `ipma` indices are 1-based, so index `0` here
+     * corresponds to property index `1`.
+     * @type {object[]}
+     */
+    properties: object[];
+    /** @type {ItemReference[]} */
+    references: ItemReference[];
+    /** @type {Uint8Array|null} the `idat` payload, for construction method 1 */
+    item_data: Uint8Array | null;
+    /** @type {Uint8Array} the whole file, so item extents can be resolved against it */
+    bytes: Uint8Array;
+    /** @type {boolean} true when a `moov` box is present, i.e. this is an image sequence */
+    has_image_sequence: boolean;
+}
+//# sourceMappingURL=AvifFile.d.ts.map

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

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

@@ -0,0 +1,142 @@
+/**
+ * Parsed model of an AVIF file.
+ *
+ * The structs here mirror the file rather than the image: `parse_avif_file` fills them in, and
+ * everything above it — deciding which item is the picture, resolving a grid, finding the alpha
+ * plane — works from this model instead of re-walking boxes.
+ *
+ * @see ISO/IEC 23008-12 "HEIF"
+ * @see ISO/IEC 23000-22 "AVIF"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * One extent of an item's data. Items may be stored in pieces, and the pieces may be anywhere.
+ */
+export class ItemExtent {
+    /** @type {number} absolute offset, once `base_offset` and the construction method are applied */
+    offset = 0;
+
+    /** @type {number} */
+    length = 0;
+}
+
+/**
+ * How an item's extent offsets should be interpreted.
+ * @enum {number}
+ */
+export const ConstructionMethod = {
+    FILE_OFFSET: 0,
+    IDAT_OFFSET: 1,
+    ITEM_OFFSET: 2
+};
+
+/**
+ * One item from `iinf` / `iloc`.
+ */
+export class AvifItem {
+    /** @type {number} */
+    id = 0;
+
+    /** @type {string} four character item type: `av01`, `grid`, `Exif`, `mime`, `tmap`, … */
+    item_type = "";
+
+    /** @type {string} */
+    item_name = "";
+
+    /** @type {string} for `mime` items */
+    content_type = "";
+
+    /** @type {number} @see ConstructionMethod */
+    construction_method = ConstructionMethod.FILE_OFFSET;
+
+    /** @type {number} */
+    data_reference_index = 0;
+
+    /** @type {number} */
+    base_offset = 0;
+
+    /** @type {ItemExtent[]} */
+    extents = [];
+
+    /** @type {number[]} 1-based indices into {@link AvifFile.properties} */
+    property_indices = [];
+
+    /** @type {boolean[]} parallel to {@link property_indices} */
+    property_essential = [];
+
+    /** @type {boolean} set from `iinf`'s per-entry hidden flag */
+    hidden = false;
+}
+
+/**
+ * One `iref` entry: a typed reference from one item to several others.
+ */
+export class ItemReference {
+    /** @type {string} four character reference type: `dimg`, `auxl`, `thmb`, `cdsc`, `prem`, … */
+    reference_type = "";
+
+    /** @type {number} */
+    from_item_id = 0;
+
+    /** @type {number[]} */
+    to_item_ids = [];
+}
+
+/**
+ * The `grid` derived-image payload. Not a box: this is the item's own data.
+ */
+export class ImageGrid {
+    /** @type {number} */
+    rows = 1;
+
+    /** @type {number} */
+    columns = 1;
+
+    /** @type {number} */
+    output_width = 0;
+
+    /** @type {number} */
+    output_height = 0;
+}
+
+/**
+ * A whole parsed file.
+ */
+export class AvifFile {
+    /** @type {string} */
+    major_brand = "";
+
+    /** @type {number} */
+    minor_version = 0;
+
+    /** @type {string[]} */
+    compatible_brands = [];
+
+    /** @type {number} `0` when `pitm` is absent */
+    primary_item_id = 0;
+
+    /** @type {Map<number, AvifItem>} */
+    items = new Map();
+
+    /**
+     * Properties from `ipco`, in file order. `ipma` indices are 1-based, so index `0` here
+     * corresponds to property index `1`.
+     * @type {object[]}
+     */
+    properties = [];
+
+    /** @type {ItemReference[]} */
+    references = [];
+
+    /** @type {Uint8Array|null} the `idat` payload, for construction method 1 */
+    item_data = null;
+
+    /** @type {Uint8Array} the whole file, so item extents can be resolved against it */
+    bytes = new Uint8Array(0);
+
+    /** @type {boolean} true when a `moov` box is present, i.e. this is an image sequence */
+    has_image_sequence = false;
+}