@woosh/meep-engine 3.30.0 → 3.31.0

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

@@ -1,97 +1,131 @@
-import { ConstructionMethod } from "./AvifFile.js";
-
-/**
- * Gather an item's bytes.
- *
- * A single-extent item stored in the file returns a view onto the file's own buffer with no copy,
- * which is the overwhelmingly common case and the one worth keeping allocation-free. Multi-extent
- * items are concatenated, because they have to be.
- *
- * Construction method 2 (offsets into another item) is resolved recursively, with a depth limit:
- * a file can point item A at item B and item B back at item A, and without the limit that is an
- * infinite recursion driven entirely by untrusted input.
- *
- * @param {AvifFile} file
- * @param {AvifItem} item
- * @param {number} [depth] internal
- * @returns {Uint8Array}
- * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export function read_item_data(file, item, depth = 0) {
-    if (depth > 4) {
-        throw new Error(`item ${item.id} is part of a construction method 2 reference cycle`);
-    }
-
-    const source = source_bytes_for(file, item, depth);
-
-    if (item.extents.length === 0) {
-        return source.subarray(0, 0);
-    }
-
-    let total = 0;
-
-    for (let i = 0; i < item.extents.length; i++) {
-        const extent = item.extents[i];
-
-        if (extent.offset < 0 || extent.length < 0 || extent.offset + extent.length > source.length) {
-            throw new Error(`item ${item.id} extent [${extent.offset}, ${extent.offset + extent.length}) is outside its ${source.length} byte source`);
-        }
-
-        total += extent.length;
-    }
-
-    if (item.extents.length === 1) {
-        const extent = item.extents[0];
-
-        return source.subarray(extent.offset, extent.offset + extent.length);
-    }
-
-    const gathered = new Uint8Array(total);
-
-    let written = 0;
-
-    for (let i = 0; i < item.extents.length; i++) {
-        const extent = item.extents[i];
-
-        gathered.set(source.subarray(extent.offset, extent.offset + extent.length), written);
-
-        written += extent.length;
-    }
-
-    return gathered;
-}
-
-/**
- * @param {AvifFile} file
- * @param {AvifItem} item
- * @param {number} depth
- * @returns {Uint8Array}
- */
-function source_bytes_for(file, item, depth) {
-    if (item.construction_method === ConstructionMethod.FILE_OFFSET) {
-        return file.bytes;
-    }
-
-    if (item.construction_method === ConstructionMethod.IDAT_OFFSET) {
-        if (file.item_data === null) {
-            throw new Error(`item ${item.id} refers to idat, but the file has no idat box`);
-        }
-
-        return file.item_data;
-    }
-
-    if (item.construction_method === ConstructionMethod.ITEM_OFFSET) {
-        const target = file.items.get(item.data_reference_index);
-
-        if (target === undefined) {
-            throw new Error(`item ${item.id} refers to item ${item.data_reference_index}, which does not exist`);
-        }
-
-        return read_item_data(file, target, depth + 1);
-    }
-
-    throw new Error(`item ${item.id} uses unsupported construction method ${item.construction_method}`);
-}
+import { ConstructionMethod } from "./AvifFile.js";
+import { find_item_references } from "./find_item_references.js";
+
+/**
+ * Gather an item's bytes.
+ *
+ * A single-extent item stored in the file returns a view onto the file's own buffer with no copy,
+ * which is the overwhelmingly common case and the one worth keeping allocation-free. Multi-extent
+ * items are concatenated, because they have to be.
+ *
+ * Construction method 2 (offsets into another item) is resolved recursively, with a depth limit:
+ * a file can point item A at item B and item B back at item A, and without the limit that is an
+ * infinite recursion driven entirely by untrusted input.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {number} [depth] internal
+ * @returns {Uint8Array}
+ * @see ISO/IEC 14496-12 section 8.11.3 "Item location box"
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function read_item_data(file, item, depth = 0) {
+    if (depth > 4) {
+        throw new Error(`item ${item.id} is part of a construction method 2 reference cycle`);
+    }
+
+    if (item.extents.length === 0) {
+        return source_bytes_for(file, item, item.extents[0], depth).subarray(0, 0);
+    }
+
+    // a source PER EXTENT: under construction method 2 each one names its own source item
+    const sources = [];
+
+    let total = 0;
+
+    for (let i = 0; i < item.extents.length; i++) {
+        const extent = item.extents[i];
+
+        const source = source_bytes_for(file, item, extent, depth);
+
+        if (extent.offset < 0 || extent.length < 0 || extent.offset + extent.length > source.length) {
+            throw new Error(`item ${item.id} extent [${extent.offset}, ${extent.offset + extent.length}) is outside its ${source.length} byte source`);
+        }
+
+        sources.push(source);
+
+        total += extent.length;
+    }
+
+    if (item.extents.length === 1) {
+        const extent = item.extents[0];
+
+        return sources[0].subarray(extent.offset, extent.offset + extent.length);
+    }
+
+    const gathered = new Uint8Array(total);
+
+    let written = 0;
+
+    for (let i = 0; i < item.extents.length; i++) {
+        const extent = item.extents[i];
+
+        gathered.set(sources[i].subarray(extent.offset, extent.offset + extent.length), written);
+
+        written += extent.length;
+    }
+
+    return gathered;
+}
+
+/**
+ * The buffer one extent's offset is measured into.
+ *
+ * @param {AvifFile} file
+ * @param {AvifItem} item
+ * @param {ItemExtent} extent
+ * @param {number} depth
+ * @returns {Uint8Array}
+ */
+function source_bytes_for(file, item, extent, depth) {
+    if (item.construction_method === ConstructionMethod.FILE_OFFSET) {
+        /*
+         `data_reference_index` indexes the `dref` box: 0 is "this file", anything else names an
+         external one. There is no `dref` support here, and reading an external item out of the
+         local buffer at whatever offset happens to be there gives another item's bytes — a
+         different picture, or a throw from the decoder, instead of a refusal.
+        */
+        if (item.data_reference_index !== 0) {
+            throw new Error(`item ${item.id} keeps its data in an external file (data reference ${item.data_reference_index}), which is not supported`);
+        }
+
+        return file.bytes;
+    }
+
+    if (item.construction_method === ConstructionMethod.IDAT_OFFSET) {
+        if (file.item_data === null) {
+            throw new Error(`item ${item.id} refers to idat, but the file has no idat box`);
+        }
+
+        return file.item_data;
+    }
+
+    if (item.construction_method === ConstructionMethod.ITEM_OFFSET) {
+        /*
+         The source is named by the extent's 1-based index into this item's `iloc` references.
+
+         It used to be `file.items.get(item.data_reference_index)` — a `dref` index used as an item
+         id. An item whose dref index happened to be a valid item id read THAT item's bytes, so a
+         structural error came back as a plausible wrong picture.
+        */
+        const referenced = find_item_references(file, item.id, "iloc");
+
+        const target_id = referenced[extent.index - 1];
+
+        if (target_id === undefined) {
+            throw new Error(`item ${item.id} extent names iloc reference ${extent.index}, and the item has ${referenced.length}`);
+        }
+
+        const target = file.items.get(target_id);
+
+        if (target === undefined) {
+            throw new Error(`item ${item.id} refers to item ${target_id}, which does not exist`);
+        }
+
+        return read_item_data(file, target, depth + 1);
+    }
+
+    throw new Error(`item ${item.id} uses unsupported construction method ${item.construction_method}`);
+}

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

@@ -1 +1 @@
-{"version":3,"file":"decodeScan.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/jpeg/decodeScan.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AACH,iCAZW,UAAU,UACV,MAAM,gCAEN,oBAAoB,iBACpB,MAAM,iBACN,MAAM,eACN,MAAM,kBACN,MAAM,cACN,MAAM,qBACN,OAAO,GACN,MAAM,CAgUjB;AA9VD,mCAgBG"}
+{"version":3,"file":"decodeScan.d.ts","sourceRoot":"","sources":["../../../../../src/format/image/jpeg/decodeScan.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;GAaG;AACH,iCAZW,UAAU,UACV,MAAM,gCAEN,oBAAoB,iBACpB,MAAM,iBACN,MAAM,eACN,MAAM,kBACN,MAAM,cACN,MAAM,qBACN,OAAO,GACN,MAAM,CAiVjB;AA/WD,mCAgBG"}

package/src/format/image/jpeg/decodeScan.js

@@ -302,6 +302,23 @@ export function decodeScan(
             for (n = 0; n < resetInterval; n++) {
                 decodeBlock(component, decodeFn, mcu);
                 mcu++;
+
+                /*
+                 The bound the multi-component arm below has always had, and this one did not.
+
+                 When mcuExpected is not a multiple of resetInterval the last interval used to run
+                 past the end of the component. The overshoot blocks are missing from
+                 component.blocks, so under tolerantDecoding they are skipped and consume nothing —
+                 but mcu ends past mcuExpected, so the trailing-byte skip that walks to the next
+                 marker does not run and the marker is read from wherever the bit reader stopped. If
+                 that is not a marker the scan throws and the whole picture is lost; with
+                 tolerantDecoding off it is a TypeError on the missing block instead. Restart
+                 intervals in progressive JPEGs are ordinary camera output, and every progressive
+                 scan is non-interleaved, so every one of them takes this arm.
+                */
+                if (mcu === mcuExpected) {
+                    break;
+                }
             }
         } else {
             for (n = 0; n < resetInterval; n++) {

package/src/format/scene/gltf/gltf_parse_container.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gltf_parse_container.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/gltf/gltf_parse_container.js"],"names":[],"mappings":"AAgDA;;;GAGG;AACH,gDAHW,UAAU,GACR,OAAO,CAQnB;AAED;;;;;;GAMG;AACH,4CAJW,UAAU,GACR,aAAa,CAyDzB;AA0BD;;;;;;;;;;;GAWG;AACH,wDALoB,MAAM,QAAE,MAAM,KAAG,UAAU,eACpC,MAAM,GACJ,mBAAmB,CA6D/B;AAED;;;;;;;;GAQG;AACH,qDAHW,MAAM,QAehB;AArND;;GAEG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;;;;;OAOG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;CACvB;AA6ED;;GAEG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,qBAFU,MAAM,CAES;IAEzB;;OAEG;IACH,qBAFU,MAAM,CAEQ;CAC3B"}
+{"version":3,"file":"gltf_parse_container.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/gltf/gltf_parse_container.js"],"names":[],"mappings":"AAgDA;;;GAGG;AACH,gDAHW,UAAU,GACR,OAAO,CAQnB;AAkCD;;;;;;GAMG;AACH,4CAJW,UAAU,GACR,aAAa,CAoDzB;AA0BD;;;;;;;;;;;GAWG;AACH,wDALoB,MAAM,QAAE,MAAM,KAAG,UAAU,eACpC,MAAM,GACJ,mBAAmB,CAsD/B;AAED;;;;;;;;GAQG;AACH,qDAHW,MAAM,QAehB;AAzOD;;GAEG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;;;;;OAOG;IACH,cAFU,UAAU,GAAC,IAAI,CAEL;CACvB;AAwGD;;GAEG;AACH;IACI;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,qBAFU,MAAM,CAES;IAEzB;;OAEG;IACH,qBAFU,MAAM,CAEQ;CAC3B"}

package/src/format/scene/gltf/gltf_parse_container.js

@@ -58,6 +58,38 @@ export function gltf_is_binary_container(bytes) {
     return new DataView(bytes.buffer, bytes.byteOffset, 4).getUint32(0, true) === GLB_MAGIC;
 }
 
+/**
+ * Walk a `.glb`'s chunk list, calling `on_chunk` for each one.
+ *
+ * Both container entry points run this. They used to carry a copy each — the same
+ * `while (offset + GLB_CHUNK_HEADER_SIZE <= length)` loop, keyed on the same two type constants, with
+ * the same "chunks it does not name are skipped whole" behaviour — differing only in whether the bytes
+ * were in hand or fetched by a range reader, and in one thing that was not deliberate: only the layout
+ * reader clamped a chunk to the container's declared length. The clamp lives here now, so both get it.
+ *
+ * A chunk header is read through `read_u32` and the body is described rather than produced, because the
+ * two callers want different things from it — one a `subarray`, the other an offset and a length.
+ *
+ * @param {function(number): number} read_u32 little-endian u32 at a byte offset in the container
+ * @param {number} length the container's own declared length, already clamped to what is available
+ * @param {function(number, number, number): void} on_chunk `(type, start, length)`, the length already
+ * clamped so a chunk that over-declares cannot describe bytes past `length`
+ */
+function gltf_walk_chunks(read_u32, length, on_chunk) {
+    let offset = GLB_HEADER_SIZE;
+
+    while (offset + GLB_CHUNK_HEADER_SIZE <= length) {
+        const chunk_length = read_u32(offset);
+        const chunk_type = read_u32(offset + 4);
+
+        const chunk_start = offset + GLB_CHUNK_HEADER_SIZE;
+
+        on_chunk(chunk_type, chunk_start, Math.min(chunk_length, length - chunk_start));
+
+        offset = chunk_start + chunk_length;
+    }
+}
+
 /**
  * Split a `.gltf` or `.glb` into its JSON and its binary chunk, told apart by magic.
  *
@@ -95,24 +127,19 @@ export function gltf_parse_container(bytes) {
     */
     const length = Math.min(view.getUint32(8, true), bytes.byteLength);
 
-    let offset = GLB_HEADER_SIZE;
-
-    while (offset + GLB_CHUNK_HEADER_SIZE <= length) {
-        const chunk_length = view.getUint32(offset, true);
-        const chunk_type = view.getUint32(offset + 4, true);
-
-        const chunk_start = offset + GLB_CHUNK_HEADER_SIZE;
-
-        const chunk = bytes.subarray(chunk_start, chunk_start + chunk_length);
-
-        if (chunk_type === GLB_CHUNK_JSON) {
-            result.json = JSON.parse(new TextDecoder('utf-8').decode(chunk));
-        } else if (chunk_type === GLB_CHUNK_BIN) {
-            result.binary_chunk = chunk;
+    gltf_walk_chunks(
+        (at) => view.getUint32(at, true),
+        length,
+        (chunk_type, chunk_start, chunk_length) => {
+            const chunk = bytes.subarray(chunk_start, chunk_start + chunk_length);
+
+            if (chunk_type === GLB_CHUNK_JSON) {
+                result.json = JSON.parse(new TextDecoder('utf-8').decode(chunk));
+            } else if (chunk_type === GLB_CHUNK_BIN) {
+                result.binary_chunk = chunk;
+            }
         }
-
-        offset = chunk_start + chunk_length;
-    }
+    );
 
     if (result.json === null) {
         throw new Error('the glTF binary contains no JSON chunk');
@@ -184,31 +211,24 @@ export function gltf_read_container_layout(read, byte_length) {
 
     const length = Math.min(header_view.getUint32(8, true), byte_length);
 
-    let offset = GLB_HEADER_SIZE;
-
-    while (offset + GLB_CHUNK_HEADER_SIZE <= length) {
-        const chunk_header = read(offset, GLB_CHUNK_HEADER_SIZE);
-
-        const chunk_view = new DataView(
-            chunk_header.buffer, chunk_header.byteOffset, chunk_header.byteLength
-        );
-
-        const chunk_length = chunk_view.getUint32(0, true);
-        const chunk_type = chunk_view.getUint32(4, true);
-
-        const chunk_start = offset + GLB_CHUNK_HEADER_SIZE;
-
-        if (chunk_type === GLB_CHUNK_JSON) {
-            result.json = JSON.parse(
-                new TextDecoder('utf-8').decode(read(chunk_start, Math.min(chunk_length, length - chunk_start)))
-            );
-        } else if (chunk_type === GLB_CHUNK_BIN) {
-            result.binary_chunk_offset = chunk_start;
-            result.binary_chunk_length = Math.min(chunk_length, length - chunk_start);
+    gltf_walk_chunks(
+        (at) => {
+            const four = read(at, 4);
+
+            return new DataView(four.buffer, four.byteOffset, four.byteLength).getUint32(0, true);
+        },
+        length,
+        (chunk_type, chunk_start, chunk_length) => {
+            if (chunk_type === GLB_CHUNK_JSON) {
+                result.json = JSON.parse(
+                    new TextDecoder('utf-8').decode(read(chunk_start, chunk_length))
+                );
+            } else if (chunk_type === GLB_CHUNK_BIN) {
+                result.binary_chunk_offset = chunk_start;
+                result.binary_chunk_length = chunk_length;
+            }
         }
-
-        offset = chunk_start + chunk_length;
-    }
+    );
 
     if (result.json === null) {
         throw new Error('the glTF binary contains no JSON chunk');

package/src/format/scene/gltf/gltf_read_accessor.d.ts

@@ -6,6 +6,27 @@
  * @returns {GltfAccessorData}
  */
 export function gltf_read_accessor(gltf: object, accessor_index: number): GltfAccessorData;
+/**
+ * One accessor's values as a flat `Float32Array`, dequantised if it is stored as a normalized
+ * integer.
+ *
+ * What an animation sampler and a set of inverse-bind matrices want: numbers, stride-free, in the
+ * units the format says they mean rather than the units they were stored in. glTF 2.0 §5.5 lets an
+ * animation sampler's OUTPUT be float or a normalized byte, ubyte, short or ushort when the channel
+ * targets `rotation` or `weights` — core spec, not an extension, and what gltfpack and several
+ * exporters emit by default. A caller that asserts FLOAT and hands back the storage array is wrong
+ * two different ways at once, because the assert is stripped by the consumer: the development build
+ * refuses the model and the shipped build reads a keyframe quaternion (0, 0, 0, 32767) as four
+ * orders of magnitude out of range.
+ *
+ * A float accessor is passed straight through — {@link gltf_read_accessor} already returns a fresh,
+ * tightly packed array, so there is nothing for a copy to buy.
+ *
+ * @param {object} gltf resolved
+ * @param {number} accessor_index
+ * @returns {Float32Array}
+ */
+export function gltf_read_accessor_as_float32_array(gltf: object, accessor_index: number): Float32Array;
 /**
  * The same values as float32, decoding glTF's fixed-point rule for a normalized integer accessor.
  *

package/src/format/scene/gltf/gltf_read_accessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gltf_read_accessor.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/gltf/gltf_read_accessor.js"],"names":[],"mappings":"AAoMA;;;;;;GAMG;AACH,yCAJW,MAAM,kBACN,MAAM,GACJ,gBAAgB,CAoD5B;AAED;;;;;;GAMG;AACH,mDAJW,gBAAgB,GACd,YAAY,CAkCxB;AAvRD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;GAEG;AACH;IACI;;;;OAIG;IACH,mBAA6B;IAE7B;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,gBAFU,mBAAmB,CAEc;IAE3C;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,YAFU,OAAO,CAEE;CACtB;oCA3DM,0BAA0B"}
+{"version":3,"file":"gltf_read_accessor.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/gltf/gltf_read_accessor.js"],"names":[],"mappings":"AAoMA;;;;;;GAMG;AACH,yCAJW,MAAM,kBACN,MAAM,GACJ,gBAAgB,CAoD5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,0DAJW,MAAM,kBACN,MAAM,GACJ,YAAY,CAiBxB;AAED;;;;;;GAMG;AACH,mDAJW,gBAAgB,GACd,YAAY,CAkCxB;AA5TD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;GAEG;AACH;IACI;;;;OAIG;IACH,mBAA6B;IAE7B;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,gBAFU,mBAAmB,CAEc;IAE3C;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,YAFU,OAAO,CAEE;CACtB;oCA3DM,0BAA0B"}

package/src/format/scene/gltf/gltf_read_accessor.js

@@ -253,6 +253,43 @@ export function gltf_read_accessor(gltf, accessor_index) {
     return result;
 }
 
+/**
+ * One accessor's values as a flat `Float32Array`, dequantised if it is stored as a normalized
+ * integer.
+ *
+ * What an animation sampler and a set of inverse-bind matrices want: numbers, stride-free, in the
+ * units the format says they mean rather than the units they were stored in. glTF 2.0 §5.5 lets an
+ * animation sampler's OUTPUT be float or a normalized byte, ubyte, short or ushort when the channel
+ * targets `rotation` or `weights` — core spec, not an extension, and what gltfpack and several
+ * exporters emit by default. A caller that asserts FLOAT and hands back the storage array is wrong
+ * two different ways at once, because the assert is stripped by the consumer: the development build
+ * refuses the model and the shipped build reads a keyframe quaternion (0, 0, 0, 32767) as four
+ * orders of magnitude out of range.
+ *
+ * A float accessor is passed straight through — {@link gltf_read_accessor} already returns a fresh,
+ * tightly packed array, so there is nothing for a copy to buy.
+ *
+ * @param {object} gltf resolved
+ * @param {number} accessor_index
+ * @returns {Float32Array}
+ */
+export function gltf_read_accessor_as_float32_array(gltf, accessor_index) {
+    const accessor = gltf.accessors[accessor_index];
+
+    assert.ok(
+        accessor.componentType === GLTF_COMPONENT_TYPE.FLOAT || accessor.normalized === true,
+        `accessor[${accessor_index}] must be FLOAT or a normalized integer to read as float32, was componentType ${accessor.componentType}`
+    );
+
+    const data = gltf_read_accessor(gltf, accessor_index);
+
+    if (accessor.normalized !== true && data.values instanceof Float32Array) {
+        return data.values;
+    }
+
+    return gltf_accessor_to_float32(data);
+}
+
 /**
  * The same values as float32, decoding glTF's fixed-point rule for a normalized integer accessor.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"usd_compose_transform.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/usd_compose_transform.js"],"names":[],"mappings":"AAgEA;;;;;;;;;;;;GAYG;AACH,kFAHW,MAAM,GACJ,YAAY,CA0BxB"}
+{"version":3,"file":"usd_compose_transform.d.ts","sourceRoot":"","sources":["../../../../../src/format/scene/usd/usd_compose_transform.js"],"names":[],"mappings":"AAoFA;;;;;;;;;;;;GAYG;AACH,kFAHW,MAAM,GACJ,YAAY,CAsCxB"}

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

@@ -21,6 +21,7 @@ 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_invert } from "../../../core/geom/3d/mat4/m4_invert.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";
@@ -43,6 +44,25 @@ const _temp_mat = new Float32Array(16);
  */
 const _temp_axis_mat = new Float32Array(16);
 
+/**
+ * Reusable temporary matrix holding the inverse of an op marked `!invert!`.
+ * @type {Float32Array}
+ */
+const _temp_inverse_mat = new Float32Array(16);
+
+/**
+ * What an `xformOpOrder` entry carries in front of the op name when the op is to be applied
+ * inverted.
+ *
+ * The canonical rotate-about-a-pivot idiom is the triple
+ * `[xformOp:translate:pivot, xformOp:rotateXYZ, !invert!xformOp:translate:pivot]` — Maya and
+ * Houdini emit it as a matter of course — so a reader that does not know this prefix composes R
+ * where T·R·T⁻¹ was authored, and the prim lands at the pivot's distance from where it belongs.
+ *
+ * @type {string}
+ */
+const XFORM_OP_INVERT_PREFIX = "!invert!";
+
 /**
  * Reusable temporary quaternion.
  * @type {Float32Array}
@@ -88,14 +108,26 @@ export function usd_compose_transform(fields, specs_by_path, prim_path) {
     for (let i = 0; i < xform_op_order.length; i++) {
         const op_name = xform_op_order[i];
 
+        /*
+         The `!invert!` marker is on the ORDER entry, not on the attribute: the value is authored
+         once, under the plain name, and named twice in the order. Resolving the marked entry
+         verbatim finds no attribute at all, which is why the inverse half of a pivot pair used to
+         vanish without even reaching the op dispatch.
+        */
+        const inverted = op_name.startsWith(XFORM_OP_INVERT_PREFIX);
+
+        const attribute_name = inverted
+            ? op_name.slice(XFORM_OP_INVERT_PREFIX.length)
+            : op_name;
+
         // Resolve the operation value from the prim's attribute specs
-        const value = resolve_xform_op_value(op_name, fields, specs_by_path, prim_path);
+        const value = resolve_xform_op_value(attribute_name, fields, specs_by_path, prim_path);
 
         if (value === null) {
             continue;
         }
 
-        apply_xform_op(result, op_name, value);
+        apply_xform_op(result, attribute_name, value, inverted);
     }
 
     return new Float32Array(result);
@@ -156,13 +188,23 @@ function resolve_xform_op_value(op_name, fields, specs_by_path, prim_path) {
  * - `xformOp:transform` — full 4×4 matrix
  *
  * @param {Float32Array} result - Matrix to multiply into (modified in place)
- * @param {string} op_name - Operation name
+ * @param {string} op_name - Operation name, without any `!invert!` marker
  * @param {number[]|Float32Array|Float64Array} value - Operation value
+ * @param {boolean} [inverted] - apply the inverse of this op, as `!invert!` asks
  */
-function apply_xform_op(result, op_name, value) {
+function apply_xform_op(result, op_name, value, inverted = false) {
 
-    // Strip the "xformOp:" prefix and any namespace suffix (e.g. ":pivot")
-    const op = op_name.replace(/^xformOp:/, "");
+    /*
+     An op name is `xformOp`, the op, and then any number of namespace suffixes the author chose:
+     `xformOp:translate:pivot`, `xformOp:scale:unitsScale`. The suffix names WHICH translate this
+     is among several on the prim and says nothing about what the op does, so the op is the second
+     token and the rest is not ours to read.
+
+     This used to strip the prefix alone, under a comment saying it stripped the suffix too, so
+     every suffixed op fell through to the warning below and returned without multiplying anything
+     into the result — the op was not unknown, it was just not looked up properly.
+    */
+    const op = op_name.split(":")[1];
 
     if (op === "translate") {
 
@@ -213,6 +255,14 @@ function apply_xform_op(result, op_name, value) {
         return;
     }
 
+    if (inverted) {
+        m4_invert(_temp_inverse_mat, _temp_mat);
+
+        m4_multiply(result, result, _temp_inverse_mat);
+
+        return;
+    }
+
     m4_multiply(result, result, _temp_mat);
 }
 

package/src/format/texture/basis/transcode/fit_endpoints.d.ts

@@ -26,6 +26,12 @@
  * It stays because it is cheap beside the template build and because those levels are real, not
  * because it is what closes the gap to the reference transcoder.
  *
+ * The normal-equations solve itself is {@link solve_endpoints}; this is the assign-and-resolve loop
+ * around it. The two used to carry the same solve character for character — the same `sum_aa`/`sum_ab`/
+ * `sum_bb` accumulation, the same determinant, the same `1e-6` singularity threshold and the same two
+ * closed-form expressions per channel — with one caller each, so a change to the conditioning, the
+ * threshold or the clamping was two edits that no fixture would have noticed only half of.
+ *
  * @param {Uint8Array} low three channels, seeded with a guess and overwritten with the fit
  * @param {Uint8Array} high three channels, likewise
  * @param {Uint8Array} colors twelve bytes, the block's four `[r, g, b]` colours

package/src/format/texture/basis/transcode/fit_endpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fit_endpoints.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/fit_endpoints.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,mCAVW,UAAU,QACV,UAAU,UACV,UAAU,WACV,UAAU,gBACV,MAAM,gBACN,MAAM,QA+EhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qCATW,UAAU,QACV,UAAU,UACV,UAAU,sBACV,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,OAAO,CAyCnB;AA+CD;;;;;GAKG;AACH,4EAFa,UAAU,CAyBtB;AA1RD;;;;;;;;;GASG;AACH,8BAFU,MAAM,EAAE,EAAE,CAOlB"}
+{"version":3,"file":"fit_endpoints.d.ts","sourceRoot":"","sources":["../../../../../../src/format/texture/basis/transcode/fit_endpoints.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,mCAVW,UAAU,QACV,UAAU,UACV,UAAU,WACV,UAAU,gBACV,MAAM,gBACN,MAAM,QAwDhB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qCATW,UAAU,QACV,UAAU,UACV,UAAU,sBACV,UAAU,gBACV,MAAM,gBACN,MAAM,GACJ,OAAO,CAyCnB;AA+CD;;;;;GAKG;AACH,4EAFa,UAAU,CAyBtB;AAzQD;;;;;;;;;GASG;AACH,8BAFU,MAAM,EAAE,EAAE,CAOlB"}