@woosh/meep-engine 3.14.2 → 3.14.4

package/src/format/scene/usd/usd_compose_transform.js

@@ -0,0 +1,258 @@
+/**
+ * Composes a USD `xformOpOrder` stack into a single 4×4 column-major matrix.
+ *
+ * @see https://openusd.org/release/api/class_usd_geom_xformable.html#details — xformOpOrder semantics
+ * @see https://openusd.org/release/api/class_usd_geom_xform_op.html — Individual xformOp types
+ *
+ * USD transforms are specified as an ordered list of operations:
+ * ```usda
+ * uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", "xformOp:scale"]
+ * double3 xformOp:translate = (10, 0, 0)
+ * float3 xformOp:rotateXYZ = (0, 45, 0)
+ * double3 xformOp:scale = (2, 2, 2)
+ * ```
+ *
+ * These are composed left-to-right: T × R × S.
+ *
+ * @module usd_compose_transform
+ */
+
+import { array_copy } from "../../../core/collection/array/array_copy.js";
+import { M4_IDENTITY } from "../../../core/geom/3d/mat4/M4_IDENTITY.js";
+import { m4_allocate } from "../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_from_rotation_translation_scale } from "../../../core/geom/3d/mat4/m4_from_rotation_translation_scale.js";
+import { m4_make_rotation_x } from "../../../core/geom/3d/mat4/m4_make_rotation_x.js";
+import { m4_make_rotation_y } from "../../../core/geom/3d/mat4/m4_make_rotation_y.js";
+import { m4_make_rotation_z } from "../../../core/geom/3d/mat4/m4_make_rotation_z.js";
+import { m4_make_scale } from "../../../core/geom/3d/mat4/m4_make_scale.js";
+import { m4_make_translation } from "../../../core/geom/3d/mat4/m4_make_translation.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { m4_transpose } from "../../../core/geom/3d/mat4/m4_transpose.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+
+/**
+ * Reusable temporary matrix to avoid per-call allocations.
+ * @type {Float32Array}
+ */
+const _temp_mat = new Float32Array(16);
+
+/**
+ * Reusable temporary matrix holding a single axis of an euler rotation, which is multiplied into
+ * the accumulating rotation rather than replacing it.
+ * @type {Float32Array}
+ */
+const _temp_axis_mat = new Float32Array(16);
+
+/**
+ * Reusable temporary quaternion.
+ * @type {Float32Array}
+ */
+const _temp_quat = new Float32Array(4);
+
+/**
+ * An `xformOp:orient` carries rotation alone — translation and scale are separate ops with their
+ * own place in `xformOpOrder` — so the matrix it composes from a quaternion has neither.
+ * @type {number[]}
+ */
+const NO_TRANSLATION = [0, 0, 0];
+
+/**
+ * @see NO_TRANSLATION
+ * @type {number[]}
+ */
+const UNIT_SCALE = [1, 1, 1];
+
+/**
+ * Compose a USD transform from its `xformOpOrder` and associated properties.
+ *
+ * NOTE: USD stores positions as `double3` (float64). The output matrix is
+ * `Float32Array` (float32) to match the engine's transform representation.
+ * This is a **precision-loss point** — positions far from origin may lose
+ * sub-millimeter precision.
+ *
+ * @param {Object} fields - Prim fields containing xformOp:* values
+ * @param {Object} specs_by_path - Full specsByPath map for attribute lookup
+ * @param {string} prim_path - Prim path for resolving attribute paths
+ * @returns {Float32Array} 4×4 column-major transform matrix
+ */
+export function usd_compose_transform(fields, specs_by_path, prim_path) {
+
+    const xform_op_order = fields.xformOpOrder;
+
+    if (!xform_op_order || xform_op_order.length === 0) {
+        return m4_allocate();
+    }
+
+    const result = m4_allocate();
+
+    for (let i = 0; i < xform_op_order.length; i++) {
+        const op_name = xform_op_order[i];
+
+        // Resolve the operation value from the prim's attribute specs
+        const value = resolve_xform_op_value(op_name, fields, specs_by_path, prim_path);
+
+        if (value === null) {
+            continue;
+        }
+
+        apply_xform_op(result, op_name, value);
+    }
+
+    return new Float32Array(result);
+}
+
+
+/**
+ * Resolve the value of an xform operation.
+ *
+ * Values can be stored either:
+ * - Directly in the prim's fields (USDA parser may inline them)
+ * - As attribute specs at `primPath.opName`
+ *
+ * @param {string} op_name - e.g. "xformOp:translate"
+ * @param {Object} fields - Prim fields
+ * @param {Object} specs_by_path - Full specsByPath
+ * @param {string} prim_path - Prim path
+ * @returns {number[]|Float32Array|Float64Array|null}
+ */
+function resolve_xform_op_value(op_name, fields, specs_by_path, prim_path) {
+
+    // Check if directly stored as a field
+    if (fields[op_name] !== undefined) {
+        return fields[op_name];
+    }
+
+    // Look up as an attribute spec
+    const attr_path = prim_path + "." + op_name;
+    const attr_spec = specs_by_path[attr_path];
+
+    if (attr_spec && attr_spec.fields) {
+        // Prefer timeSamples first frame if present, otherwise default
+        if (attr_spec.fields.timeSamples) {
+            const ts = attr_spec.fields.timeSamples;
+            if (ts.values && ts.values.length > 0) {
+                return ts.values[0];
+            }
+        }
+
+        if (attr_spec.fields.default !== undefined) {
+            return attr_spec.fields.default;
+        }
+    }
+
+    return null;
+}
+
+
+/**
+ * Apply a single xform operation to the accumulating matrix.
+ *
+ * Supported operations:
+ * - `xformOp:translate` — vec3 translation
+ * - `xformOp:scale` — vec3 scale
+ * - `xformOp:rotateX/Y/Z` — single-axis rotation (degrees)
+ * - `xformOp:rotateXYZ/XZY/YXZ/YZX/ZXY/ZYX` — euler rotation (degrees)
+ * - `xformOp:orient` — quaternion rotation (USD format: w,x,y,z)
+ * - `xformOp:transform` — full 4×4 matrix
+ *
+ * @param {Float32Array} result - Matrix to multiply into (modified in place)
+ * @param {string} op_name - Operation name
+ * @param {number[]|Float32Array|Float64Array} value - Operation value
+ */
+function apply_xform_op(result, op_name, value) {
+
+    // Strip the "xformOp:" prefix and any namespace suffix (e.g. ":pivot")
+    const op = op_name.replace(/^xformOp:/, "");
+
+    if (op === "translate") {
+
+        // NOTE: float64 → float32 precision loss for large coordinates
+        m4_make_translation(_temp_mat, value);
+
+    } else if (op === "scale") {
+
+        m4_make_scale(_temp_mat, value);
+
+    } else if (op === "rotateX") {
+
+        m4_make_rotation_x(_temp_mat, value * DEG_TO_RAD);
+
+    } else if (op === "rotateY") {
+
+        m4_make_rotation_y(_temp_mat, value * DEG_TO_RAD);
+
+    } else if (op === "rotateZ") {
+
+        m4_make_rotation_z(_temp_mat, value * DEG_TO_RAD);
+
+    } else if (op === "rotateXYZ" || op === "rotateXZY" || op === "rotateYXZ" ||
+        op === "rotateYZX" || op === "rotateZXY" || op === "rotateZYX") {
+
+        apply_euler_rotation(_temp_mat, op, value);
+
+    } else if (op === "orient") {
+
+        // USD quaternion order: (w, x, y, z)
+        // engine quaternion order: (x, y, z, w)
+        // @see https://openusd.org/release/api/class_gf_quatf.html — GfQuatf real-part-first layout
+        _temp_quat[0] = value[1];
+        _temp_quat[1] = value[2];
+        _temp_quat[2] = value[3];
+        _temp_quat[3] = value[0];
+
+        m4_from_rotation_translation_scale(_temp_mat, _temp_quat, NO_TRANSLATION, UNIT_SCALE);
+
+    } else if (op === "transform") {
+
+        // Full 4×4 matrix — USD stores row-major, engine uses column-major
+        // NOTE: float64 → float32 precision loss for all 16 matrix elements
+        m4_transpose(_temp_mat, value);
+
+    } else {
+        console.warn(`[USD] Unknown xformOp: "${op_name}", skipping`);
+        return;
+    }
+
+    m4_multiply(result, result, _temp_mat);
+}
+
+
+/**
+ * Apply euler rotation in the specified axis order.
+ *
+ * @param {Float32Array} out - Output matrix
+ * @param {string} order - e.g. "rotateXYZ"
+ * @param {number[]} angles - [x, y, z] in degrees
+ */
+function apply_euler_rotation(out, order, angles) {
+
+    const rx = angles[0] * DEG_TO_RAD;
+    const ry = angles[1] * DEG_TO_RAD;
+    const rz = angles[2] * DEG_TO_RAD;
+
+    // Extract axis order from the op name (e.g. "rotateXYZ" → "XYZ")
+    const axis_order = order.replace("rotate", "");
+
+    const ops = {
+        "X": (m) => m4_make_rotation_x(m, rx),
+        "Y": (m) => m4_make_rotation_y(m, ry),
+        "Z": (m) => m4_make_rotation_z(m, rz),
+    };
+
+    array_copy(M4_IDENTITY, 0, out, 0, 16);
+
+    // OpenUSD applies the named axes to the point first-to-last (rotateXYZ ⇒ X
+    // first). A column-major matrix applies its rightmost factor first, so build
+    // the product in reverse: out = R_last · … · R_first.
+    // @see https://openusd.org/release/api/class_usd_geom_xform_op.html — TypeRotateXYZ
+    for (let i = axis_order.length - 1; i >= 0; i--) {
+        const axis = axis_order[i];
+        const fn = ops[axis];
+
+        if (fn) {
+            fn(_temp_axis_mat);
+
+            m4_multiply(out, out, _temp_axis_mat);
+        }
+    }
+}

package/src/format/scene/usd/usd_lz4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usd_lz4.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/usd_lz4.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;GAcG;AACH,0CANW,UAAU,qBACV,MAAM,GAEJ,UAAU,CA2DtB;AAGD;;;;;;;;;;GAUG;AACH,2DAJW,WAAW,YACX,MAAM,GACJ,UAAU,CAStB"}

package/src/format/scene/usd/usd_lz4.js

@@ -0,0 +1,182 @@
+/**
+ * USD's TfFastCompression framing over LZ4, and the Crate integer coding that rides on it.
+ *
+ * USDC (Crate) compresses its tokens, fields and integer arrays with LZ4, wrapped by Pixar's
+ * TfFastCompression. The LZ4 block codec itself is generic and lives in core; what is USD's own is
+ * the chunk framing around it and the delta coding inside it, and that is what this module is.
+ *
+ * @see https://openusd.org/release/glossary.html#usdglossary-crate — Crate binary file format
+ * @see https://github.com/PixarAnimationStudios/OpenUSD/blob/release/pxr/base/tf/fastCompression.cpp — TfFastCompression
+ * @see https://github.com/PixarAnimationStudios/OpenUSD/blob/release/pxr/usd/sdf/integerCoding.cpp — Crate integer coding
+ *
+ * @module usd_lz4
+ */
+
+import { LZ4_MAX_INPUT_SIZE } from "../../../core/binary/lz4/LZ4_MAX_INPUT_SIZE.js";
+import { lz4_decompress_block } from "../../../core/binary/lz4/lz4_decompress_block.js";
+import { UsdParseError } from "./UsdError.js";
+
+
+/**
+ * Decompress a TfFastCompression payload.
+ *
+ * The first byte is a chunk count. Zero means the whole of the rest is one LZ4 block. Anything else
+ * is that many chunks, each one a 32-bit little-endian compressed size followed immediately by the
+ * block it measures - the sizes are interleaved with the data, not gathered into a table up front.
+ * Pixar chunks at the largest input LZ4 takes, so a payload has to exceed {@link LZ4_MAX_INPUT_SIZE}
+ * before it is chunked at all.
+ *
+ * @param {Uint8Array} input - Compressed data including the TfFastCompression header
+ * @param {number} uncompressed_size - Upper bound on the output; callers that only know a bound get
+ *                                     a buffer of that size with the tail left zeroed
+ * @returns {Uint8Array} Decompressed data
+ * @throws {UsdParseError} If the framing does not fit the data
+ */
+export function usd_lz4_decompress(input, uncompressed_size) {
+
+    if (input.length < 1) {
+        throw new UsdParseError("TfFastCompression payload is empty", { section: "lz4" });
+    }
+
+    const output = new Uint8Array(uncompressed_size);
+    const num_chunks = input[0];
+
+    if (num_chunks === 0) {
+        // Single chunk — all remaining bytes are one LZ4 block
+        lz4_decompress_block(output, 0, uncompressed_size, input, 1, input.length);
+
+        return output;
+    }
+
+    let input_cursor = 1;
+    let output_cursor = 0;
+
+    for (let i = 0; i < num_chunks; i++) {
+
+        if (input_cursor + 4 > input.length) {
+            throw new UsdParseError(
+                `TfFastCompression chunk ${i} of ${num_chunks} has no size header`,
+                { section: "lz4", offset: input_cursor }
+            );
+        }
+
+        const chunk_compressed_size = (
+            input[input_cursor]
+            | (input[input_cursor + 1] << 8)
+            | (input[input_cursor + 2] << 16)
+            | (input[input_cursor + 3] << 24)
+        ) >>> 0;
+
+        input_cursor += 4;
+
+        if (input_cursor + chunk_compressed_size > input.length) {
+            throw new UsdParseError(
+                `TfFastCompression chunk ${i} of ${num_chunks} claims ${chunk_compressed_size} bytes, past the end of the payload`,
+                { section: "lz4", offset: input_cursor }
+            );
+        }
+
+        // each chunk carries at most LZ4's largest input, and the last of them carries the remainder
+        output_cursor = lz4_decompress_block(
+            output,
+            output_cursor, Math.min(output_cursor + LZ4_MAX_INPUT_SIZE, uncompressed_size),
+            input,
+            input_cursor, input_cursor + chunk_compressed_size
+        );
+
+        input_cursor += chunk_compressed_size;
+    }
+
+    return output;
+}
+
+
+/**
+ * Decompress USD integer-compressed data.
+ *
+ * USD uses a delta + variable-width encoding for integer arrays:
+ * 1. LZ4-decompress the outer payload
+ * 2. Decode: common_value (int32) + 2-bit codes per element + variable-width deltas
+ *
+ * @param {ArrayBuffer} compressed_buffer - Raw compressed bytes
+ * @param {number} num_ints - Number of integers to decode
+ * @returns {Int32Array} Decoded integers
+ */
+export function usd_decompress_integers(compressed_buffer, num_ints) {
+
+    // Estimate encoded size: num_ints×4 bytes for values + 2 bits per code + 4 bytes for common value
+    const encoded_size = num_ints * 4 + ((num_ints * 2 + 7) >> 3) + 4;
+    const encoded = usd_lz4_decompress(new Uint8Array(compressed_buffer), encoded_size);
+
+    return decode_integers_32(encoded, num_ints);
+}
+
+
+/**
+ * Decode delta + variable-width encoded integers.
+ *
+ * Format:
+ * - int32 common_value
+ * - ceil(num_ints * 2 / 8) bytes of 2-bit codes (4 codes per byte)
+ * - Variable-width delta values following each code
+ *
+ * Code meanings:
+ * - 0: delta = common_value
+ * - 1: delta = next int8
+ * - 2: delta = next int16 (LE)
+ * - 3: delta = next int32 (LE)
+ *
+ * @param {Uint8Array} data - Decoded LZ4 payload
+ * @param {number} num_ints - Number of integers
+ * @returns {Int32Array}
+ */
+function decode_integers_32(data, num_ints) {
+
+    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    let offset = 0;
+
+    const common_value = view.getInt32(offset, true);
+    offset += 4;
+
+    const num_code_bytes = (num_ints * 2 + 7) >> 3;
+    const codes_start = offset;
+    const values_start = offset + num_code_bytes;
+
+    const result = new Int32Array(num_ints);
+    let prev_value = 0;
+    let codes_offset = codes_start;
+    let values_offset = values_start;
+
+    for (let i = 0; i < num_ints;) {
+        const code_byte = data[codes_offset++];
+
+        // Each byte holds 4 × 2-bit codes
+        for (let j = 0; j < 4 && i < num_ints; j++, i++) {
+            const code = (code_byte >> (j * 2)) & 3;
+            let delta = 0;
+
+            switch (code) {
+                case 0:
+                    delta = common_value;
+                    break;
+                case 1:
+                    delta = view.getInt8(values_offset);
+                    values_offset += 1;
+                    break;
+                case 2:
+                    delta = view.getInt16(values_offset, true);
+                    values_offset += 2;
+                    break;
+                case 3:
+                    delta = view.getInt32(values_offset, true);
+                    values_offset += 4;
+                    break;
+            }
+
+            prev_value += delta;
+            result[i] = prev_value;
+        }
+    }
+
+    return result;
+}

package/src/format/scene/usd/usd_triangulate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usd_triangulate.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/usd_triangulate.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH;;;;;;;;;;;;;GAaG;AACH,oDAXW,MAAM,EAAE,GAAC,UAAU,uBACnB,MAAM,EAAE,GAAC,UAAU;aAEd,WAAW;cACV,WAAW;oBACL,MAAM;EAwE5B;AAGD;;;;;;;;;;GAUG;AACH,4DALW,MAAM,EAAE,GAAC,UAAU,gBACnB,YAAY,GAAC,MAAM,EAAE,aACrB,MAAM,GACJ,YAAY,CAmDxB"}

package/src/format/texture/TexelPayload.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Texels already in a GPU format, with their mip levels — what a texture container or a transcoder
+ * hands back.
+ *
+ * A plain record rather than an engine type, because this is the whole of the texture tier's output:
+ * bytes in, this out, and no device, queue or renderer between. `ShadeTexelData` is the engine's view
+ * of the same thing, and the adapter beside it — `texel_data_from_ktx2` — is where one becomes the
+ * other, and where the engine's own constraints (one level or the whole chain) are applied. Nothing
+ * under `format/` imports the engine type; `format_tier_boundary.spec.js` holds that.
+ *
+ * Levels are tightly packed rows of blocks, base level first, each exactly the byte length its format
+ * and extent imply — a reader checks that before handing one over, a transcoder guarantees it by
+ * construction. `depth` halves per level, the way a 3D texture's does; a 2D image has a depth of 1.
+ *
+ * An array texture or a cube map is `layers` and `faces` above 1, and a level then holds
+ * `layers * faces` images back to back — layer-major, then face, no padding — which is KTX2's order
+ * and the one `writeTexture` takes for `depthOrArrayLayers`. A 3D texture has neither: the format
+ * tier refuses a file claiming both, because no GPU API has such a texture. What the *engine* can
+ * take is the adapter's question: `ShadeTexelData` models a single image today and
+ * `texel_data_from_ktx2` refuses layers and faces there, not here.
+ *
+ * The format is named in WebGPU's own vocabulary, {@link TextureFormat }. That enum lives under
+ * `shade/descriptor/` and is one of the three modules the format tier is allowed to reach for — it
+ * is a standard's strings as constants, not engine behaviour, and a second spelling of them here
+ * would only need translating back.
+ */
+type TexelPayload = {
+    format: TextureFormat;
+    /**
+     * texels, base level
+     */
+    width: number;
+    /**
+     * texels, base level
+     */
+    height: number;
+    /**
+     * base level; `1` for a 2D image
+     */
+    depth: number;
+    /**
+     * array layers; `1` for a texture that is not an array
+     */
+    layers: number;
+    /**
+     * `6` for a cube map, `1` otherwise
+     */
+    faces: number;
+    /**
+     * one entry per mip level, base first; each holds `layers * faces`
+     * images back to back
+     */
+    levels: Uint8Array[];
+};
+//# sourceMappingURL=TexelPayload.d.ts.map

package/src/format/texture/TexelPayload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TexelPayload.d.ts","sourceRoot":"","sources":["../../../../src/format/texture/TexelPayload.js"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WA4Bc,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;;YACN,MAAM;;;;WACN,MAAM;;;;;YACN,UAAU,EAAE"}

package/src/format/texture/TexelPayload.js

@@ -0,0 +1,39 @@
+/**
+ * Texels already in a GPU format, with their mip levels — what a texture container or a transcoder
+ * hands back.
+ *
+ * A plain record rather than an engine type, because this is the whole of the texture tier's output:
+ * bytes in, this out, and no device, queue or renderer between. `ShadeTexelData` is the engine's view
+ * of the same thing, and the adapter beside it — `texel_data_from_ktx2` — is where one becomes the
+ * other, and where the engine's own constraints (one level or the whole chain) are applied. Nothing
+ * under `format/` imports the engine type; `format_tier_boundary.spec.js` holds that.
+ *
+ * Levels are tightly packed rows of blocks, base level first, each exactly the byte length its format
+ * and extent imply — a reader checks that before handing one over, a transcoder guarantees it by
+ * construction. `depth` halves per level, the way a 3D texture's does; a 2D image has a depth of 1.
+ *
+ * An array texture or a cube map is `layers` and `faces` above 1, and a level then holds
+ * `layers * faces` images back to back — layer-major, then face, no padding — which is KTX2's order
+ * and the one `writeTexture` takes for `depthOrArrayLayers`. A 3D texture has neither: the format
+ * tier refuses a file claiming both, because no GPU API has such a texture. What the *engine* can
+ * take is the adapter's question: `ShadeTexelData` models a single image today and
+ * `texel_data_from_ktx2` refuses layers and faces there, not here.
+ *
+ * The format is named in WebGPU's own vocabulary, {@link TextureFormat}. That enum lives under
+ * `shade/descriptor/` and is one of the three modules the format tier is allowed to reach for — it
+ * is a standard's strings as constants, not engine behaviour, and a second spelling of them here
+ * would only need translating back.
+ *
+ * @typedef {object} TexelPayload
+ * @property {TextureFormat} format
+ * @property {number} width texels, base level
+ * @property {number} height texels, base level
+ * @property {number} depth base level; `1` for a 2D image
+ * @property {number} layers array layers; `1` for a texture that is not an array
+ * @property {number} faces `6` for a cube map, `1` otherwise
+ * @property {Uint8Array[]} levels one entry per mip level, base first; each holds `layers * faces`
+ * images back to back
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */

package/src/format/texture/basis/BasisBitReader.d.ts

@@ -0,0 +1,77 @@
+/**
+ * LSB-first bit cursor over a byte range, with the speculative peek a Huffman decoder needs.
+ *
+ * **Why this is not {@link BitReader}.** `format/image/avif/bitstream/BitReader.js` is the other bit
+ * reader in this tree and it does not fit, for two reasons that are about the format rather than
+ * about convenience:
+ *
+ * 1. **It is MSB-first, and Basis is LSB-first.** The specification is explicit — "Huffman codes are
+ *    stored in each output byte in LSB to MSB order. (This is opposite of the JPEG format)". Bit
+ *    order is not a parameter that could be added the way {@link ByteCursor} took a byte order:
+ *    a byte order is a property of a *field*, applied once per read, while a bit order changes what
+ *    the single-bit primitive means and so changes every accessor beneath it.
+ * 2. **Huffman decoding needs peek-then-consume, which a descriptor reader has no reason to offer.**
+ *    A canonical code's length is not known until it has been looked up, so the decoder reads bits
+ *    it may not consume. `BitReader`'s `f(n)` is sequential by construction.
+ *
+ * One class doing both would be a flag on every method. So this is a second bit reader,
+ * deliberately, and it stays in `basis/` rather than moving to `core/binary/` until something other
+ * than Basis wants it — the same rule `ByteCursor` moved under, applied in the direction that says
+ * "not yet".
+ *
+ * **Peeking past the end reads zeros; consuming past it throws.** The two have to differ. A Huffman
+ * peek is speculative and legitimately runs off the end of a section — the last code in a stream is
+ * rarely flush with a byte boundary — so refusing there would refuse well-formed files. Consuming is
+ * a different claim, and a stream that runs out mid-symbol is corrupt.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class BasisBitReader {
+    /**
+     * Point the reader at a byte range.
+     *
+     * @param {Uint8Array} data
+     * @param {number} [byte_offset]
+     * @param {number} [byte_length]
+     * @returns {BasisBitReader} this
+     * @throws {Error} for a range outside `data`
+     */
+    init(data: Uint8Array, byte_offset?: number, byte_length?: number): BasisBitReader;
+    /**
+     * Look at the next `count` bits without consuming them. Bits past the end of the range read as
+     * zero — see the note on the class.
+     *
+     * @param {number} count `0` to 24; the Huffman decoder's longest peek is 16
+     * @returns {number}
+     */
+    peek(count: number): number;
+    /**
+     * Drop the next `count` bits.
+     *
+     * @param {number} count
+     * @throws {Error} when the bits dropped were never in the range
+     */
+    consume(count: number): void;
+    /**
+     * Read `count` bits, least significant first.
+     *
+     * @param {number} count `0` to 24
+     * @returns {number}
+     * @throws {Error} when the range does not hold them
+     */
+    bits(count: number): number;
+    /**
+     * The specification's variable-length code: `chunk_bits` of payload plus a continuation bit,
+     * repeated until the continuation bit is clear.
+     *
+     * @param {number} chunk_bits
+     * @returns {number}
+     * @throws {Error} for a code that would not fit in 32 bits, which is a corrupt stream rather
+     * than a large number
+     * @see the specification's `decode_vlc`, section 10.2
+     */
+    vlc(chunk_bits: number): number;
+    #private;
+}
+//# sourceMappingURL=BasisBitReader.d.ts.map

package/src/format/texture/basis/BasisBitReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasisBitReader.d.ts","sourceRoot":"","sources":["../../../../../src/format/texture/basis/BasisBitReader.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAyCI;;;;;;;;OAQG;IACH,WANW,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,cAAc,CAmB1B;IA6BD;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,MAAM,CAUlB;IAED;;;;;OAKG;IACH,eAHW,MAAM,QAwBhB;IAED;;;;;;OAMG;IACH,YAJW,MAAM,GACJ,MAAM,CASlB;IAED;;;;;;;;;OASG;IACH,gBANW,MAAM,GACJ,MAAM,CA+BlB;;CACJ"}