@woosh/meep-engine 3.14.2 → 3.14.4

package/src/shade/renderer/loader/gltf/tiny-gltf.js

@@ -1,646 +1,837 @@
-import { gltf_apply_buffer_view_extensions } from "./ext/gltf_apply_buffer_view_extensions.js";
-import { GLTF_BUFFER_VIEW_EXTENSIONS } from "./ext/gltf_buffer_view_extensions.js";
-import { gltf_node_world_matrices, gltf_root_nodes } from "./gltf_node_world_matrices.js";
-import { gltf_parse_container, gltf_require_supported_version } from "./gltf_parse_container.js";
-import { gltf_used_image_indices } from "./gltf_used_image_indices.js";
-/**
- * TinyGltf
- * Loads glTF 2.0 file, resolves buffer and image dependencies, and computes node world transforms and aabbs.
- * This is a VERY simplified glTF loader that avoids doing too much work for you.
- * It should generally not be used outside of simple tutorials or examples.
- *
- * What it adds over the container-level readers beside it is **resolution**: buffers and images are
- * fetched through the {@link AssetManager}, decoded, and written back into the document. Splitting
- * the container, reading an accessor and walking the node graph are all questions of the format
- * rather than of where the bytes come from, and live in their own modules so that a caller with no
- * asset framework - the virtual-geometry builder, running under node - can use them too.
- */
-
-import { assert } from "../../../../core/assert.js";
-import { aabb3_array_combine } from "../../../../core/geom/3d/aabb/aabb3_array_combine.js";
-import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
-import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
-import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
-import { GameAssetType } from "../../../../engine/asset/GameAssetType.js";
-
-/**
- * glTF's default texture wrap mode, by its own number.
- * @type {number}
- */
-const GLTF_WRAP_REPEAT = 10497;
-
-/**
- * What a buffer the file never wrote resolves to - a placeholder some extension declares.
- * Zero length rather than the declared one: a well-formed file reads none of it, and a malformed one
- * fails loudly on the first accessor instead of quietly rendering a megabyte of zeroes.
- * @type {Uint8Array}
- */
-const EMPTY_BUFFER = new Uint8Array(0);
-
-const DEFAULT_TRANSLATION = [0, 0, 0];
-const DEFAULT_ROTATION = [0, 0, 0, 1];
-const DEFAULT_SCALE = [1, 1, 1];
-
-/**
- * A URI that names its own scheme, by RFC 3986's rule for one.
- *
- * Every scheme rather than the page's: built from `window.location.protocol`, this called an
- * `https:` asset on an `http:` page relative — and a `blob:` or a `data:` likewise — and answered it
- * with the model's own directory glued to the front.
- *
- * @type {RegExp}
- */
-const ABSOLUTE_URI = /^[a-z][a-z0-9+.-]*:/i;
-
-/**
- * Protocol-relative, which names no scheme and is absolute all the same.
- * @type {RegExp}
- */
-const PROTOCOL_RELATIVE_URI = /^\/\//;
-
-function resolveUri(uri, baseUrl) {
-    if (ABSOLUTE_URI.test(uri) || PROTOCOL_RELATIVE_URI.test(uri)) {
-        return uri;
-    }
-    return baseUrl + uri;
-}
-
-/**
- * A resolved buffer, in the form the document exposes it.
- *
- * `Uint8Array` rather than `ArrayBuffer` throughout: a buffer is a *range* of bytes, and a `.glb`'s
- * binary chunk is a range of the file it arrived in. Carrying the offset with the bytes is what lets
- * that chunk be handed on without copying it, and it is the only form an accessor can be read out of
- * without caring how the container happened to be aligned.
- *
- * @param {ArrayBuffer} array_buffer
- * @returns {Uint8Array}
- */
-function as_bytes(array_buffer) {
-    return new Uint8Array(array_buffer);
-}
-
-/*
- Very simple AABB tracking so that we can position cameras sensibly.
-
- A box is six numbers — `[x0, y0, z0, x1, y1, z1]`, min before max — which is the layout every
- `aabb3_*` function in `core/geom/3d/aabb` reads and writes. There is no box object because nothing
- downstream asks for one: a mesh, a node and a scene each carry their bounds so that a camera can
- be pointed at the model, and the six numbers are the whole of that.
-*/
-
-/**
- * Scratch for one accessor's authored bounds, read as a box.
- *
- * Module scope rather than per primitive: it is filled and consumed by two adjacent statements
- * of a walk that never awaits, so no second accessor can be in flight while one is being read.
- *
- * @type {Float64Array}
- */
-const ACCESSOR_BOUNDS_SCRATCH = new Float64Array(6);
-
-/**
- * A box that bounds nothing, so that the first union with it yields the other operand whole.
- *
- * The bounds are inverted for that: `+Infinity` min against `-Infinity` max. The class this replaced
- * seeded its max with `Number.MIN_VALUE`, which is the smallest *positive* double rather than the most
- * negative one — a mesh living entirely below the origin came out of it with a max pinned near zero,
- * and a box that did not contain the mesh.
- *
- * `Float64Array` because glTF authors accessor bounds as JSON doubles, and these are combined and
- * transformed all the way up the node graph before anyone reads them.
- *
- * @returns {Float64Array} six numbers, `[x0, y0, z0, x1, y1, z1]`
- */
-function aabb3_allocate_empty() {
-    const result = new Float64Array(6);
-
-    aabb3_array_set(
-        result, 0,
-        Infinity, Infinity, Infinity,
-        -Infinity, -Infinity, -Infinity
-    );
-
-    return result;
-}
-
-/**
- * Whether a box bounds anything at all, as opposed to being the empty one {@link aabb3_allocate_empty}
- * hands out.
- *
- * Worth asking before transforming one: the empty box's bounds are infinite, and an infinity met
- * by one of the matrix's zeroes is a NaN, which then spreads into every box above it in the graph.
- *
- * @param {Float64Array|number[]} box six numbers
- * @returns {boolean}
- */
-function aabb3_is_bounded(box) {
-    return box[0] <= box[3] && box[1] <= box[4] && box[2] <= box[5];
-}
-
-
-/**
- * Give every node the graph reaches its world matrix and its normal matrix.
- *
- * @param {{nodes?:object[], scenes?:object[]}} gltf
- */
-function set_node_matrices(gltf) {
-    const world_matrices = gltf_node_world_matrices(gltf);
-
-    const nodes = gltf.nodes ?? [];
-
-    for (let index = 0; index < nodes.length; index++) {
-        const world = world_matrices[index];
-
-        if (world === undefined) {
-            // a node no root reaches is placed by nothing, and has no world transform to speak of
-            continue;
-        }
-
-        const node = nodes[index];
-
-        node.worldMatrix = world;
-
-        /*
-         The normal matrix — the one that carries a *normal* rather than a point, since a normal does
-         not ride the transform itself wherever that transform is not a similarity: a non-uniform
-         scale tilts a surface one way and its normal the other.
-
-         Meep's own primitive, and a 3x3: the cofactor of the linear part, which points where the
-         inverse transpose points without inverting anything. So it reads no translation (a direction
-         has no position) and it has an answer for a transform with an axis scaled to nothing, where
-         an inverse does not exist — the gl-matrix code this replaced handed that case's `null`
-         straight on to `mat4.transpose` and threw. Vectors come out of it unnormalized; that is the
-         method, not a defect.
-        */
-        node.normalMatrix = new Float32Array(9);
-
-        m4_normal_matrix3(node.normalMatrix, world);
-    }
-}
-
-/**
- * The box a mesh's own vertices occupy, in model space, computed once and kept on the mesh.
- *
- * Read off the accessors' authored bounds rather than the vertex data: the spec requires them on a
- * POSITION accessor, and this runs before a single buffer has resolved.
- *
- * @param {{accessors?:object[]}} gltf
- * @param {{primitives:object[], aabb?:Float64Array}} mesh
- * @returns {Float64Array} six numbers, and unbounded when no primitive declared any
- */
-function mesh_bounds(gltf, mesh) {
-    if (mesh.aabb !== undefined) {
-        return mesh.aabb;
-    }
-
-    const result = aabb3_allocate_empty();
-
-    mesh.aabb = result;
-
-    for (const primitive of mesh.primitives) {
-        const accessor = gltf.accessors[primitive.attributes.POSITION];
-
-        const min = accessor?.min;
-        const max = accessor?.max;
-
-        /*
-         The spec requires bounds on a POSITION accessor, and a file that omits them is one this can
-         say nothing about. A primitive contributing no bounds is a better answer than six NaNs
-         poisoning every box above it.
-        */
-        if (min === undefined || max === undefined || min.length < 3 || max.length < 3) {
-            continue;
-        }
-
-        aabb3_array_set(
-            ACCESSOR_BOUNDS_SCRATCH, 0,
-            min[0], min[1], min[2],
-            max[0], max[1], max[2]
-        );
-
-        aabb3_array_combine(result, 0, result, 0, ACCESSOR_BOUNDS_SCRATCH, 0);
-    }
-
-    return result;
-}
-
-/**
- * Grow whatever box `holder` carries so that it also holds `addition`, giving it one if it had none.
- *
- * @param {{aabb?:Float64Array}} holder a node or a scene
- * @param {Float64Array} addition six numbers
- */
-function absorb_bounds(holder, addition) {
-    if (holder.aabb === undefined) {
-        // a copy: a box aliased to a child's would grow with it
-        holder.aabb = new Float64Array(addition);
-
-        return;
-    }
-
-    aabb3_array_combine(holder.aabb, 0, holder.aabb, 0, addition, 0);
-}
-
-/**
- * Bound a node in world space by what it places, and by everything below it.
- *
- * A node reached twice keeps the box of its first visit, the same rule the world matrices follow —
- * so the second parent still spans the child, but does not re-walk the subtree under it.
- *
- * @param {{nodes:object[], meshes?:object[]}} gltf
- * @param {number} index
- * @param {Set<number>} visited
- */
-function set_node_bounds(gltf, index, visited) {
-    if (visited.has(index)) {
-        return;
-    }
-
-    visited.add(index);
-
-    const node = gltf.nodes[index];
-
-    if ('mesh' in node) {
-        const bounds = mesh_bounds(gltf, gltf.meshes[node.mesh]);
-
-        // a mesh whose primitives all declined to declare bounds leaves the node without any
-        if (aabb3_is_bounded(bounds)) {
-            // a fresh box, which is also what `aabb3_matrix4_project` requires: it may not alias its input
-            node.aabb = new Float64Array(6);
-
-            aabb3_matrix4_project(node.aabb, bounds, node.worldMatrix);
-        }
-    }
-
-    for (const child_index of node.children ?? []) {
-        set_node_bounds(gltf, child_index, visited);
-
-        const child = gltf.nodes[child_index];
-
-        if (child.aabb !== undefined) {
-            absorb_bounds(node, child.aabb);
-        }
-    }
-}
-
-/**
- * Place every node, and bound every mesh, node and scene.
- *
- * @param {{nodes?:object[], meshes?:object[], scenes?:object[]}} gltf
- */
-function place_nodes(gltf) {
-    set_node_matrices(gltf);
-
-    const visited = new Set();
-
-    // shared across the scenes, so a node two of them list is measured once and spans both
-    for (const root of gltf_root_nodes(gltf)) {
-        set_node_bounds(gltf, root, visited);
-    }
-
-    for (const scene of gltf.scenes ?? []) {
-        for (const node_index of scene.nodes ?? []) {
-            const node = gltf.nodes[node_index];
-
-            if (node.aabb !== undefined) {
-                absorb_bounds(scene, node.aabb);
-            }
-        }
-    }
-}
-
-export class TinyGltf {
-    loadImageSlots = undefined;
-
-    /**
-     * The bufferView extensions this parser will honour.
-     *
-     * Replaceable so that a caller can add a codec, or take one away, without a loader learning any
-     * extension's name. The default is shared across the process; assign a
-     * {@link GltfBufferViewExtensionSet} of your own rather than adding to it if that matters.
-     *
-     * @type {GltfBufferViewExtensionSet}
-     */
-    bufferViewExtensions = GLTF_BUFFER_VIEW_EXTENSIONS;
-
-    /**
-     * Optional map of relative file paths to Blob/File/ArrayBuffer objects.
-     * When set, buffer and image URIs in the GLTF JSON are resolved from this map
-     * before the asset framework is asked. Enables loading multi-file GLTF bundles from
-     * drag-and-drop or other in-memory sources.
-     *
-     * Keys should match the URI strings in the GLTF JSON (e.g. "scene.bin", "textures/albedo.png").
-     *
-     * @type {Map<string, File|Blob|ArrayBuffer>|undefined}
-     */
-    fileMap = undefined;
-
-    /**
-     * Where every byte this parser reads comes from.
-     *
-     * A glTF is not one file: the container names buffers and images that live beside it, and a
-     * level places models that share them. Asking the framework rather than the network is what
-     * makes a texture two models use one download and one decode, records each request against the
-     * load that caused it, and cancels the lot when the scene that asked goes away.
-     *
-     * @type {AssetManager}
-     */
-    #assetManager;
-
-    /**
-     * The load these requests belong to, or `null` for a caller that is not itself an asset load.
-     *
-     * @type {AssetRequestScope|null}
-     */
-    #scope;
-
-    /**
-     * @param {AssetManager} assetManager
-     * @param {AssetRequestScope} [scope]
-     */
-    constructor(assetManager, scope = null) {
-        assert.defined(assetManager, 'assetManager');
-
-        this.#assetManager = assetManager;
-        this.#scope = scope;
-    }
-
-    /**
-     * The bytes of a file this asset needs, through the framework.
-     *
-     * @param {string} path un-resolved, as the manager takes it
-     * @param {string} type see {@link GameAssetType}
-     * @returns {Promise<*>}
-     */
-    async #read(path, type) {
-        const asset = await this.#assetManager.promise(path, type, { scope: this.#scope });
-
-        return asset.create();
-    }
-
-    /**
-     * @param {string} url `.gltf` or `.glb`, un-resolved — the manager resolves network paths
-     * @returns {Promise<TinyGltf>}
-     */
-    async loadFromUrl(url) {
-        assert.isString(url, 'url');
-
-        const i = url.lastIndexOf('/');
-        const baseUrl = (i !== 0) ? url.substring(0, i + 1) : './';
-
-        /*
-         The container is read as bytes whatever it is called and told apart by its magic number,
-         rather than by an extension. One path instead of three, and it is the only one that was ever
-         correct for a `blob:` url — which is what drag-and-drop produces.
-        */
-        const buffer = await this.#read(url, GameAssetType.ArrayBuffer);
-
-        return this.loadFromBinary(buffer, baseUrl);
-    }
-
-    /**
-     * Load a container that is already in memory, whichever of the two forms it is in.
-     *
-     * @param {ArrayBuffer} arrayBuffer a `.glb`, or the bytes of a `.gltf`
-     * @param {string} baseUrl
-     * @return {Promise<{asset}|*>}
-     */
-    async loadFromBinary(arrayBuffer, baseUrl) {
-        const container = gltf_parse_container(new Uint8Array(arrayBuffer));
-
-        return this.loadFromJson(container.json, baseUrl, container.binary_chunk);
-    }
-
-    /**
-     *
-     * @param {{bufferViews,asset,accessors:[],nodes:[],samplers?:[],buffers:[],materials:[], textures:[], images:[],scenes:[]}} json
-     * @param {string} baseUrl
-     * @param {Uint8Array} [binaryChunk]
-     * @return {Promise<{asset}|*>}
-     */
-    async loadFromJson(json, baseUrl, binaryChunk = null) {
-        if (!baseUrl) {
-            throw new Error('baseUrl must be specified.');
-        }
-
-        gltf_require_supported_version(json);
-
-        // Resolve defaults for as many properties as we can.
-        for (const accessor of json.accessors) {
-            accessor.byteOffset = accessor.byteOffset ?? 0;
-            accessor.normalized = accessor.normalized ?? false;
-        }
-
-        for (const bufferView of json.bufferViews) {
-            bufferView.byteOffset = bufferView.byteOffset ?? 0;
-        }
-
-        for (const node of json.nodes) {
-            if (!node.matrix) {
-                node.rotation = node.rotation ?? DEFAULT_ROTATION;
-                node.scale = node.scale ?? DEFAULT_SCALE;
-                node.translation = node.translation ?? DEFAULT_TRANSLATION;
-            }
-        }
-
-        if (json.samplers) {
-            for (const sampler of json.samplers) {
-                sampler.wrapS = sampler.wrapS ?? GLTF_WRAP_REPEAT;
-                sampler.wrapT = sampler.wrapT ?? GLTF_WRAP_REPEAT;
-            }
-        }
-
-        // Resolve buffers and images first, since these are the only external resources that the file
-        // might reference.
-        // Buffers will be exposed as Uint8Arrays.
-        // Images will be exposed as ImageBitmaps.
-
-        /**
-         * Buffers
-         * @type {Promise<Uint8Array>[]}
-         */
-        const pendingBuffers = [];
-
-        const declaredBuffers = json.buffers ?? [];
-
-        /*
-         A .glb's buffer 0 is its binary chunk and names no URI. The buffers after it are ordinary,
-         and are where an extension that produces its own bufferView bytes puts the placeholder those
-         views point at - so the chunk is a special case of buffer 0, not a reason to stop looking at
-         the rest.
-        */
-        const bufferCount = Math.max(declaredBuffers.length, binaryChunk ? 1 : 0);
-
-        for (let index = 0; index < bufferCount; index++) {
-            if (binaryChunk && index === 0) {
-                pendingBuffers[index] = Promise.resolve(binaryChunk);
-                continue;
-            }
-
-            const buffer = declaredBuffers[index];
-
-            /*
-             A buffer with no URI was never written. Asking for one produced a request for
-             "<baseUrl>undefined", which is how a compressed .gltf with a fallback buffer - the shape
-             gltfpack writes - failed before it read a single accessor.
-            */
-            if (buffer.uri === undefined || this.bufferViewExtensions.is_placeholder_buffer(buffer)) {
-                pendingBuffers[index] = Promise.resolve(EMPTY_BUFFER);
-                continue;
-            }
-
-            // Check fileMap first (enables loading from dropped files)
-            if (this.fileMap) {
-                const file = this.fileMap.get(buffer.uri);
-
-                if (file !== undefined) {
-                    // File or Blob
-                    pendingBuffers[index] = (file instanceof ArrayBuffer)
-                        ? Promise.resolve(new Uint8Array(file))
-                        : file.arrayBuffer().then(as_bytes);
-
-                    continue;
-                }
-            }
-
-            pendingBuffers[index] = this.#read(
-                resolveUri(buffer.uri, baseUrl),
-                GameAssetType.ArrayBuffer
-            ).then(as_bytes);
-        }
-
-        // If the loader has been instructed to only load certain images (such as just baseColorTexture)
-        // then scan through all the materials first and gather the image IDs for only those images.
-        // (This feature really only makes sense for this specific set of samples.)
-        let activeImageSet;
-        if (this.loadImageSlots) {
-            activeImageSet = new Set();
-            for (const material of json.materials) {
-                for (const imageChannel of this.loadImageSlots) {
-                    const texture = material[imageChannel] ?? material.pbrMetallicRoughness[imageChannel];
-                    if (texture !== undefined) {
-                        activeImageSet.add(json.textures[texture.index].source);
-                    }
-                }
-            }
-        } else {
-            /*
-             Only the images something will actually sample. A texture may offer the same picture in
-             several containers — `source` plus an extension — and fetching the ones this loader has
-             already decided against is not merely wasted: `createImageBitmap` rejects on a container
-             the browser cannot decode, and an image nothing was going to sample takes the whole model
-             down with it. The game's level models each carry a DDS beside their PNG for exactly that
-             reason, and not one of them loaded.
-             */
-            activeImageSet = gltf_used_image_indices(json);
-        }
-
-        /**
-         * Images
-         * @type {Promise<ImageBitmap>[]}
-         */
-        const pendingImages = [];
-        for (let index = 0; index < json.images?.length || 0; ++index) {
-            if (activeImageSet && !activeImageSet.has(index)) {
-                continue;
-            }
-            const image = json.images[index];
-
-            /**
-             *
-             * @param {Blob} blob
-             * @return {Promise<ImageBitmap>}
-             */
-            function blob_to_bitmap(blob) {
-                return createImageBitmap(blob, {
-                    // premultiplication is done during texture upload
-                    premultiplyAlpha: "none",
-                })
-            }
-
-            if (image.uri) {
-
-                // Check fileMap first (enables loading from dropped files)
-                if (this.fileMap) {
-                    const file = this.fileMap.get(image.uri);
-
-                    if (file !== undefined) {
-                        const blob = (file instanceof Blob) ? file : new Blob([file]);
-                        pendingImages[index] = blob_to_bitmap(blob);
-                        continue;
-                    }
-                }
-
-                /*
-                 Decoded by the framework rather than here, which is what makes one texture shared
-                 by two models one decode instead of two — the expensive half of loading a model is
-                 its images, and a level places the same handful of them hundreds of times.
-                */
-                pendingImages[index] = this.#read(
-                    resolveUri(image.uri, baseUrl),
-                    GameAssetType.ImageBitmap
-                );
-
-            } else {
-
-                const bufferView = json.bufferViews[image.bufferView];
-
-                const claimed = this.bufferViewExtensions.claim(bufferView, image.bufferView);
-
-                if (claimed !== null) {
-                    /*
-                     Legal to write and pointless to: the payload is a PNG or a JPEG, already
-                     compressed. Decoding it is not implemented, and the alternative to saying so is
-                     handing the image decoder a placeholder buffer's bytes.
-                    */
-                    throw new Error(
-                        `images[${index}] is sourced from a bufferView '${claimed.name}' produces,`
-                        + ` which is not supported`
-                    );
-                }
-
-                pendingImages[index] = pendingBuffers[bufferView.buffer].then((buffer) => {
-
-                    const blob = new Blob(
-                        [buffer.subarray(
-                            bufferView.byteOffset,
-                            bufferView.byteOffset + bufferView.byteLength
-                        )],
-                        { type: image.mimeType }
-                    );
-
-                    return blob_to_bitmap(blob);
-                });
-
-            }
-        }
-
-        // Place every node, and bound every mesh, node and scene, starting at the roots.
-        place_nodes(json);
-
-        // Replace the resolved resources in the JSON structure.
-        const buffers = await Promise.all(pendingBuffers);
-
-        /*
-         Views that some extension produces the bytes for become ordinary ones here, over decoded
-         buffers appended to the list, so that nothing downstream - accessors, sparse accessors, the
-         mesh reader - has to know any of those extensions exist. Nor does this parser: it asks the
-         set what claims a view, and the set is the one place that knows what is implemented.
-
-         Per view, and guarded per view. A file nothing claims - which is nearly all of them - gets
-         its own view objects back by identity and appends no buffer.
-        */
-        json.bufferViews = gltf_apply_buffer_view_extensions(
-            json.bufferViews, buffers, this.bufferViewExtensions
-        );
-
-        json.buffers = buffers;
-        json.images = await Promise.all(pendingImages);
-
-        return json;
-    }
-
-
-}
-
+import { gltf_apply_buffer_view_extensions } from "../../../../format/scene/gltf/ext/gltf_apply_buffer_view_extensions.js";
+import { GLTF_BUFFER_VIEW_EXTENSIONS } from "../../../../format/scene/gltf/ext/gltf_buffer_view_extensions.js";
+import { gltf_node_world_matrices, gltf_root_nodes } from "../../../../format/scene/gltf/gltf_node_world_matrices.js";
+import { gltf_parse_container, gltf_require_supported_version } from "../../../../format/scene/gltf/gltf_parse_container.js";
+import { gltf_basisu_image_indices, gltf_used_image_indices } from "../../../../format/scene/gltf/gltf_used_image_indices.js";
+/**
+ * TinyGltf
+ * Loads glTF 2.0 file, resolves buffer and image dependencies, and computes node world transforms and aabbs.
+ * This is a VERY simplified glTF loader that avoids doing too much work for you.
+ * It should generally not be used outside of simple tutorials or examples.
+ *
+ * What it adds over the container-level readers beside it is **resolution**: buffers and images are
+ * fetched through the {@link AssetManager}, decoded, and written back into the document. Splitting
+ * the container, reading an accessor and walking the node graph are all questions of the format
+ * rather than of where the bytes come from, and live in their own modules so that a caller with no
+ * asset framework - the virtual-geometry builder, running under node - can use them too.
+ */
+
+import { assert } from "../../../../core/assert.js";
+import { aabb3_array_combine } from "../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { aabb3_array_set } from "../../../../core/geom/3d/aabb/aabb3_array_set.js";
+import { aabb3_matrix4_project } from "../../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
+import { GameAssetType } from "../../../../engine/asset/GameAssetType.js";
+import { transcode_basis_formats } from "../../../../format/texture/basis/transcode_basis.js";
+import { transcode_uastc_formats } from "../../../../format/texture/basis/transcode_uastc.js";
+import { texture_format_preference } from "../../texture/format/texture_format_preference.js";
+import { gltf_image_roles } from "./gltf_image_roles.js";
+import { texel_data_from_ktx2 } from "../../texture/source/texel_data_from_ktx2.js";
+import { TextureFormat } from "../../../descriptor/texture/format/TextureFormat.js";
+
+/**
+ * glTF's default texture wrap mode, by its own number.
+ * @type {number}
+ */
+const GLTF_WRAP_REPEAT = 10497;
+
+/**
+ * The MIME type a KTX2 image declares.
+ *
+ * **A supplementary signal, not the authority.** `KHR_texture_basisu` requires it only inside a GLB,
+ * where the image comes from a bufferView; an image referenced by URI is merely permitted to declare
+ * it. So {@link gltf_basisu_image_indices} is what says which images are KTX2, and this catches an
+ * image that declares itself without an extension naming it. Neither is the uri, which a `blob:` url
+ * from a drag-and-drop has no extension on.
+ *
+ * @readonly
+ * @type {string}
+ */
+const KTX2_MIME_TYPE = "image/ktx2";
+
+/**
+ * What a buffer the file never wrote resolves to - a placeholder some extension declares.
+ * Zero length rather than the declared one: a well-formed file reads none of it, and a malformed one
+ * fails loudly on the first accessor instead of quietly rendering a megabyte of zeroes.
+ * @type {Uint8Array}
+ */
+const EMPTY_BUFFER = new Uint8Array(0);
+
+const DEFAULT_TRANSLATION = [0, 0, 0];
+const DEFAULT_ROTATION = [0, 0, 0, 1];
+const DEFAULT_SCALE = [1, 1, 1];
+
+/**
+ * A URI that names its own scheme, by RFC 3986's rule for one.
+ *
+ * Every scheme rather than the page's: built from `window.location.protocol`, this called an
+ * `https:` asset on an `http:` page relative — and a `blob:` or a `data:` likewise — and answered it
+ * with the model's own directory glued to the front.
+ *
+ * @type {RegExp}
+ */
+const ABSOLUTE_URI = /^[a-z][a-z0-9+.-]*:/i;
+
+/**
+ * Protocol-relative, which names no scheme and is absolute all the same.
+ * @type {RegExp}
+ */
+const PROTOCOL_RELATIVE_URI = /^\/\//;
+
+function resolveUri(uri, baseUrl) {
+    if (ABSOLUTE_URI.test(uri) || PROTOCOL_RELATIVE_URI.test(uri)) {
+        return uri;
+    }
+    return baseUrl + uri;
+}
+
+/**
+ * A resolved buffer, in the form the document exposes it.
+ *
+ * `Uint8Array` rather than `ArrayBuffer` throughout: a buffer is a *range* of bytes, and a `.glb`'s
+ * binary chunk is a range of the file it arrived in. Carrying the offset with the bytes is what lets
+ * that chunk be handed on without copying it, and it is the only form an accessor can be read out of
+ * without caring how the container happened to be aligned.
+ *
+ * @param {ArrayBuffer} array_buffer
+ * @returns {Uint8Array}
+ */
+function as_bytes(array_buffer) {
+    return new Uint8Array(array_buffer);
+}
+
+/*
+ Very simple AABB tracking so that we can position cameras sensibly.
+
+ A box is six numbers — `[x0, y0, z0, x1, y1, z1]`, min before max — which is the layout every
+ `aabb3_*` function in `core/geom/3d/aabb` reads and writes. There is no box object because nothing
+ downstream asks for one: a mesh, a node and a scene each carry their bounds so that a camera can
+ be pointed at the model, and the six numbers are the whole of that.
+*/
+
+/**
+ * Scratch for one accessor's authored bounds, read as a box.
+ *
+ * Module scope rather than per primitive: it is filled and consumed by two adjacent statements
+ * of a walk that never awaits, so no second accessor can be in flight while one is being read.
+ *
+ * @type {Float64Array}
+ */
+const ACCESSOR_BOUNDS_SCRATCH = new Float64Array(6);
+
+/**
+ * A box that bounds nothing, so that the first union with it yields the other operand whole.
+ *
+ * The bounds are inverted for that: `+Infinity` min against `-Infinity` max. The class this replaced
+ * seeded its max with `Number.MIN_VALUE`, which is the smallest *positive* double rather than the most
+ * negative one — a mesh living entirely below the origin came out of it with a max pinned near zero,
+ * and a box that did not contain the mesh.
+ *
+ * `Float64Array` because glTF authors accessor bounds as JSON doubles, and these are combined and
+ * transformed all the way up the node graph before anyone reads them.
+ *
+ * @returns {Float64Array} six numbers, `[x0, y0, z0, x1, y1, z1]`
+ */
+function aabb3_allocate_empty() {
+    const result = new Float64Array(6);
+
+    aabb3_array_set(
+        result, 0,
+        Infinity, Infinity, Infinity,
+        -Infinity, -Infinity, -Infinity
+    );
+
+    return result;
+}
+
+/**
+ * Whether a box bounds anything at all, as opposed to being the empty one {@link aabb3_allocate_empty}
+ * hands out.
+ *
+ * Worth asking before transforming one: the empty box's bounds are infinite, and an infinity met
+ * by one of the matrix's zeroes is a NaN, which then spreads into every box above it in the graph.
+ *
+ * @param {Float64Array|number[]} box six numbers
+ * @returns {boolean}
+ */
+function aabb3_is_bounded(box) {
+    return box[0] <= box[3] && box[1] <= box[4] && box[2] <= box[5];
+}
+
+
+/**
+ * Give every node the graph reaches its world matrix and its normal matrix.
+ *
+ * @param {{nodes?:object[], scenes?:object[]}} gltf
+ */
+function set_node_matrices(gltf) {
+    const world_matrices = gltf_node_world_matrices(gltf);
+
+    const nodes = gltf.nodes ?? [];
+
+    for (let index = 0; index < nodes.length; index++) {
+        const world = world_matrices[index];
+
+        if (world === undefined) {
+            // a node no root reaches is placed by nothing, and has no world transform to speak of
+            continue;
+        }
+
+        const node = nodes[index];
+
+        node.worldMatrix = world;
+
+        /*
+         The normal matrix — the one that carries a *normal* rather than a point, since a normal does
+         not ride the transform itself wherever that transform is not a similarity: a non-uniform
+         scale tilts a surface one way and its normal the other.
+
+         Meep's own primitive, and a 3x3: the cofactor of the linear part, which points where the
+         inverse transpose points without inverting anything. So it reads no translation (a direction
+         has no position) and it has an answer for a transform with an axis scaled to nothing, where
+         an inverse does not exist — the gl-matrix code this replaced handed that case's `null`
+         straight on to `mat4.transpose` and threw. Vectors come out of it unnormalized; that is the
+         method, not a defect.
+        */
+        node.normalMatrix = new Float32Array(9);
+
+        m4_normal_matrix3(node.normalMatrix, world);
+    }
+}
+
+/**
+ * The box a mesh's own vertices occupy, in model space, computed once and kept on the mesh.
+ *
+ * Read off the accessors' authored bounds rather than the vertex data: the spec requires them on a
+ * POSITION accessor, and this runs before a single buffer has resolved.
+ *
+ * @param {{accessors?:object[]}} gltf
+ * @param {{primitives:object[], aabb?:Float64Array}} mesh
+ * @returns {Float64Array} six numbers, and unbounded when no primitive declared any
+ */
+function mesh_bounds(gltf, mesh) {
+    if (mesh.aabb !== undefined) {
+        return mesh.aabb;
+    }
+
+    const result = aabb3_allocate_empty();
+
+    mesh.aabb = result;
+
+    for (const primitive of mesh.primitives) {
+        const accessor = gltf.accessors[primitive.attributes.POSITION];
+
+        const min = accessor?.min;
+        const max = accessor?.max;
+
+        /*
+         The spec requires bounds on a POSITION accessor, and a file that omits them is one this can
+         say nothing about. A primitive contributing no bounds is a better answer than six NaNs
+         poisoning every box above it.
+        */
+        if (min === undefined || max === undefined || min.length < 3 || max.length < 3) {
+            continue;
+        }
+
+        aabb3_array_set(
+            ACCESSOR_BOUNDS_SCRATCH, 0,
+            min[0], min[1], min[2],
+            max[0], max[1], max[2]
+        );
+
+        aabb3_array_combine(result, 0, result, 0, ACCESSOR_BOUNDS_SCRATCH, 0);
+    }
+
+    return result;
+}
+
+/**
+ * Grow whatever box `holder` carries so that it also holds `addition`, giving it one if it had none.
+ *
+ * @param {{aabb?:Float64Array}} holder a node or a scene
+ * @param {Float64Array} addition six numbers
+ */
+function absorb_bounds(holder, addition) {
+    if (holder.aabb === undefined) {
+        // a copy: a box aliased to a child's would grow with it
+        holder.aabb = new Float64Array(addition);
+
+        return;
+    }
+
+    aabb3_array_combine(holder.aabb, 0, holder.aabb, 0, addition, 0);
+}
+
+/**
+ * Bound a node in world space by what it places, and by everything below it.
+ *
+ * A node reached twice keeps the box of its first visit, the same rule the world matrices follow —
+ * so the second parent still spans the child, but does not re-walk the subtree under it.
+ *
+ * @param {{nodes:object[], meshes?:object[]}} gltf
+ * @param {number} index
+ * @param {Set<number>} visited
+ */
+function set_node_bounds(gltf, index, visited) {
+    if (visited.has(index)) {
+        return;
+    }
+
+    visited.add(index);
+
+    const node = gltf.nodes[index];
+
+    if ('mesh' in node) {
+        const bounds = mesh_bounds(gltf, gltf.meshes[node.mesh]);
+
+        // a mesh whose primitives all declined to declare bounds leaves the node without any
+        if (aabb3_is_bounded(bounds)) {
+            // a fresh box, which is also what `aabb3_matrix4_project` requires: it may not alias its input
+            node.aabb = new Float64Array(6);
+
+            aabb3_matrix4_project(node.aabb, bounds, node.worldMatrix);
+        }
+    }
+
+    for (const child_index of node.children ?? []) {
+        set_node_bounds(gltf, child_index, visited);
+
+        const child = gltf.nodes[child_index];
+
+        if (child.aabb !== undefined) {
+            absorb_bounds(node, child.aabb);
+        }
+    }
+}
+
+/**
+ * Place every node, and bound every mesh, node and scene.
+ *
+ * @param {{nodes?:object[], meshes?:object[], scenes?:object[]}} gltf
+ */
+function place_nodes(gltf) {
+    set_node_matrices(gltf);
+
+    const visited = new Set();
+
+    // shared across the scenes, so a node two of them list is measured once and spans both
+    for (const root of gltf_root_nodes(gltf)) {
+        set_node_bounds(gltf, root, visited);
+    }
+
+    for (const scene of gltf.scenes ?? []) {
+        for (const node_index of scene.nodes ?? []) {
+            const node = gltf.nodes[node_index];
+
+            if (node.aabb !== undefined) {
+                absorb_bounds(scene, node.aabb);
+            }
+        }
+    }
+}
+
+export class TinyGltf {
+    loadImageSlots = undefined;
+
+    /**
+     * The bufferView extensions this parser will honour.
+     *
+     * Replaceable so that a caller can add a codec, or take one away, without a loader learning any
+     * extension's name. The default is shared across the process; assign a
+     * {@link GltfBufferViewExtensionSet} of your own rather than adding to it if that matters.
+     *
+     * @type {GltfBufferViewExtensionSet}
+     */
+    bufferViewExtensions = GLTF_BUFFER_VIEW_EXTENSIONS;
+
+    /**
+     * Optional map of relative file paths to Blob/File/ArrayBuffer objects.
+     * When set, buffer and image URIs in the GLTF JSON are resolved from this map
+     * before the asset framework is asked. Enables loading multi-file GLTF bundles from
+     * drag-and-drop or other in-memory sources.
+     *
+     * Keys should match the URI strings in the GLTF JSON (e.g. "scene.bin", "textures/albedo.png").
+     *
+     * @type {Map<string, File|Blob|ArrayBuffer>|undefined}
+     */
+    fileMap = undefined;
+
+    /**
+     * Where every byte this parser reads comes from.
+     *
+     * A glTF is not one file: the container names buffers and images that live beside it, and a
+     * level places models that share them. Asking the framework rather than the network is what
+     * makes a texture two models use one download and one decode, records each request against the
+     * load that caused it, and cancels the lot when the scene that asked goes away.
+     *
+     * @type {AssetManager}
+     */
+    #assetManager;
+
+    /**
+     * The load these requests belong to, or `null` for a caller that is not itself an asset load.
+     *
+     * @type {AssetRequestScope|null}
+     */
+    #scope;
+
+    /**
+     * Which compressed formats the device this model is being loaded for can sample, or `undefined`
+     * where the caller did not say.
+     *
+     * Only a `KHR_texture_basisu` image reads it — see {@link #basis_transcode_target}.
+     *
+     * @type {Set<GPUTextureFormat>|undefined}
+     */
+    #texture_support = undefined;
+
+    /**
+     * @param {AssetManager} assetManager
+     * @param {AssetRequestScope} [scope]
+     * @param {Set<GPUTextureFormat>} [texture_support] from `gpu_texture_compression_support(device)`
+     */
+    constructor(assetManager, scope = null, texture_support = undefined) {
+        assert.defined(assetManager, 'assetManager');
+
+        this.#assetManager = assetManager;
+        this.#scope = scope;
+        this.#texture_support = texture_support;
+    }
+
+    /**
+     * What a `KHR_texture_basisu` image is transcoded into when the device can sample no compressed
+     * format at all.
+     *
+     * `rgba8unorm` is the one format WebGPU makes mandatory, so it is the floor beneath every
+     * choice below — four bytes a texel where BC7 spends one, and the reason a model still loads on
+     * a device with no compression features rather than being refused.
+     *
+     * Not sRGB: the two spellings are the same bytes, and which one a texture is created with is
+     * decided from the image's colour space by `texture_format_from_shade_image`.
+     *
+     * @readonly
+     * @type {TextureFormat}
+     */
+    static #UNCOMPRESSED_TARGET = TextureFormat.RGBA8UNORM;
+
+    /**
+     * The format a `KHR_texture_basisu` image should be transcoded into.
+     *
+     * **The best one the transcoder writes that the device can sample.** That is the asset layer's
+     * job as §3.5 divides it: `texture_format_preference` says what would be good, and choosing from
+     * what is actually available is the caller's — here, "available" means a format
+     * {@link transcode_basis} can produce.
+     *
+     * **The texture's role does not enter yet, and saying so is more honest than pretending it
+     * does.** Every format the transcoder writes today is a four-channel BC colour format, so a
+     * normal map and an albedo map get the same answer and asking the role would be ceremony. It
+     * stops being ceremony the moment an ETC1S-to-BC5 or ETC1S-to-ASTC path lands, and that is where
+     * the role belongs.
+     *
+     * **A device that can sample nothing compressed still gets a picture.** Every compressed format
+     * is an optional WebGPU feature — `texture-compression-bc`, `-etc2` and `-astc` alike — so a
+     * device exposing none of them is allowed, and used to get a refusal. `rgba8unorm` is not
+     * optional, so it is the floor: four bytes a texel instead of one, and the model loads.
+     *
+     * @returns {TextureFormat[]} acceptable targets, best first, ending in the uncompressed floor
+     */
+    #basis_transcode_target(role) {
+        /*
+         Every *compressed* format either transcoder writes, which is what there is a choice between.
+         Which of the two transcoders will run is not known here — the encoding is in the file, and
+         the reader is what looks — so the list is the union, and the reader refuses a format its
+         encoding cannot produce.
+
+         The uncompressed target is held out rather than left in the list. It is not a candidate to
+         be ranked against the others: it is what happens when none of them can be had, and leaving
+         it in would make the answer depend on where it landed in the union's order.
+        */
+        const writable = [...new Set([...transcode_basis_formats(), ...transcode_uastc_formats()])]
+            .filter(format => format !== TinyGltf.#UNCOMPRESSED_TARGET);
+
+        /*
+         **What the engine would like for this role, put first — not used as a filter.** That is
+         §3.5's division: `texture_format_preference` answers what would be good and knows nothing
+         about transcoders, and choosing from what is available is the asset layer's. For a normal
+         map it answers BC5 first, which only the UASTC path writes, so a UASTC normal map gets BC5
+         and an ETC1S one falls through.
+
+         Ordering rather than filtering, because the preference for a role lists what is *good* and
+         not what is *acceptable*: BC1 is in no role's list, and a device that can sample only BC1
+         should still get a texture rather than a refusal.
+        */
+        const by_role = role === undefined
+            ? []
+            : texture_format_preference(role, new Set(writable));
+
+        const candidates = [...by_role, ...writable.filter(format => !by_role.includes(format))];
+
+        if (this.#texture_support === undefined) {
+            /*
+             No support set was given. Targeting the best available format is the assumption meep
+             already makes elsewhere — it targets desktop-grade hardware, where
+             `texture-compression-bc` is universal — and it is an assumption rather than a default:
+             a caller that knows better passes its device's support and gets what that device can
+             actually hold.
+            */
+            return [candidates[0], TinyGltf.#UNCOMPRESSED_TARGET];
+        }
+
+        /*
+         `#texture_support` holds what `gpu_texture_compression_support` found, which is only ever
+         compressed formats — so the uncompressed floor is appended outright rather than looked up in
+         it. Asking whether the device supports `rgba8unorm` would be asking a question WebGPU
+         already answers: it is mandatory.
+
+         The whole ordered list goes back, not just its head. Whether this particular file carries
+         alpha is knowable only once something reads its descriptor, which happens inside
+         `ktx2_read` — so the reader picks from these, and a three-channel target like ASTC or BC1
+         is passed over for a file that has alpha instead of being committed to and then refused.
+        */
+        return [
+            ...candidates.filter(format => this.#texture_support.has(format)),
+            TinyGltf.#UNCOMPRESSED_TARGET,
+        ];
+    }
+
+    /**
+     * Read a KTX2 image into texels, transcoding it where its payload is Basis.
+     *
+     * @param {ArrayBuffer|Uint8Array} bytes the whole file
+     * @returns {ShadeTexelData}
+     * @param {TextureRole} [role] what the image is for, which orders the candidate targets
+     * @throws {Error} naming the feature, for a container this reader does not read
+     */
+    #read_ktx2(bytes, role) {
+        return texel_data_from_ktx2(bytes, this.#basis_transcode_target(role));
+    }
+
+    /**
+     * The bytes of a file this asset needs, through the framework.
+     *
+     * @param {string} path un-resolved, as the manager takes it
+     * @param {string} type see {@link GameAssetType}
+     * @returns {Promise<*>}
+     */
+    async #read(path, type) {
+        const asset = await this.#assetManager.promise(path, type, { scope: this.#scope });
+
+        return asset.create();
+    }
+
+    /**
+     * @param {string} url `.gltf` or `.glb`, un-resolved — the manager resolves network paths
+     * @returns {Promise<TinyGltf>}
+     */
+    async loadFromUrl(url) {
+        assert.isString(url, 'url');
+
+        const i = url.lastIndexOf('/');
+        const baseUrl = (i !== 0) ? url.substring(0, i + 1) : './';
+
+        /*
+         The container is read as bytes whatever it is called and told apart by its magic number,
+         rather than by an extension. One path instead of three, and it is the only one that was ever
+         correct for a `blob:` url — which is what drag-and-drop produces.
+        */
+        const buffer = await this.#read(url, GameAssetType.ArrayBuffer);
+
+        return this.loadFromBinary(buffer, baseUrl);
+    }
+
+    /**
+     * Load a container that is already in memory, whichever of the two forms it is in.
+     *
+     * @param {ArrayBuffer} arrayBuffer a `.glb`, or the bytes of a `.gltf`
+     * @param {string} baseUrl
+     * @return {Promise<{asset}|*>}
+     */
+    async loadFromBinary(arrayBuffer, baseUrl) {
+        const container = gltf_parse_container(new Uint8Array(arrayBuffer));
+
+        return this.loadFromJson(container.json, baseUrl, container.binary_chunk);
+    }
+
+    /**
+     *
+     * @param {{bufferViews,asset,accessors:[],nodes:[],samplers?:[],buffers:[],materials:[], textures:[], images:[],scenes:[]}} json
+     * @param {string} baseUrl
+     * @param {Uint8Array} [binaryChunk]
+     * @return {Promise<{asset}|*>}
+     */
+    async loadFromJson(json, baseUrl, binaryChunk = null) {
+        if (!baseUrl) {
+            throw new Error('baseUrl must be specified.');
+        }
+
+        gltf_require_supported_version(json);
+
+        // Resolve defaults for as many properties as we can.
+        for (const accessor of json.accessors) {
+            accessor.byteOffset = accessor.byteOffset ?? 0;
+            accessor.normalized = accessor.normalized ?? false;
+        }
+
+        for (const bufferView of json.bufferViews) {
+            bufferView.byteOffset = bufferView.byteOffset ?? 0;
+        }
+
+        for (const node of json.nodes) {
+            if (!node.matrix) {
+                node.rotation = node.rotation ?? DEFAULT_ROTATION;
+                node.scale = node.scale ?? DEFAULT_SCALE;
+                node.translation = node.translation ?? DEFAULT_TRANSLATION;
+            }
+        }
+
+        if (json.samplers) {
+            for (const sampler of json.samplers) {
+                sampler.wrapS = sampler.wrapS ?? GLTF_WRAP_REPEAT;
+                sampler.wrapT = sampler.wrapT ?? GLTF_WRAP_REPEAT;
+            }
+        }
+
+        // Resolve buffers and images first, since these are the only external resources that the file
+        // might reference.
+        // Buffers will be exposed as Uint8Arrays.
+        // Images will be exposed as ImageBitmaps.
+
+        /**
+         * Buffers
+         * @type {Promise<Uint8Array>[]}
+         */
+        const pendingBuffers = [];
+
+        const declaredBuffers = json.buffers ?? [];
+
+        /*
+         A .glb's buffer 0 is its binary chunk and names no URI. The buffers after it are ordinary,
+         and are where an extension that produces its own bufferView bytes puts the placeholder those
+         views point at - so the chunk is a special case of buffer 0, not a reason to stop looking at
+         the rest.
+        */
+        const bufferCount = Math.max(declaredBuffers.length, binaryChunk ? 1 : 0);
+
+        for (let index = 0; index < bufferCount; index++) {
+            if (binaryChunk && index === 0) {
+                pendingBuffers[index] = Promise.resolve(binaryChunk);
+                continue;
+            }
+
+            const buffer = declaredBuffers[index];
+
+            /*
+             A buffer with no URI was never written. Asking for one produced a request for
+             "<baseUrl>undefined", which is how a compressed .gltf with a fallback buffer - the shape
+             gltfpack writes - failed before it read a single accessor.
+            */
+            if (buffer.uri === undefined || this.bufferViewExtensions.is_placeholder_buffer(buffer)) {
+                pendingBuffers[index] = Promise.resolve(EMPTY_BUFFER);
+                continue;
+            }
+
+            // Check fileMap first (enables loading from dropped files)
+            if (this.fileMap) {
+                const file = this.fileMap.get(buffer.uri);
+
+                if (file !== undefined) {
+                    // File or Blob
+                    pendingBuffers[index] = (file instanceof ArrayBuffer)
+                        ? Promise.resolve(new Uint8Array(file))
+                        : file.arrayBuffer().then(as_bytes);
+
+                    continue;
+                }
+            }
+
+            pendingBuffers[index] = this.#read(
+                resolveUri(buffer.uri, baseUrl),
+                GameAssetType.ArrayBuffer
+            ).then(as_bytes);
+        }
+
+        // If the loader has been instructed to only load certain images (such as just baseColorTexture)
+        // then scan through all the materials first and gather the image IDs for only those images.
+        // (This feature really only makes sense for this specific set of samples.)
+        let activeImageSet;
+        if (this.loadImageSlots) {
+            activeImageSet = new Set();
+            for (const material of json.materials) {
+                for (const imageChannel of this.loadImageSlots) {
+                    const texture = material[imageChannel] ?? material.pbrMetallicRoughness[imageChannel];
+                    if (texture !== undefined) {
+                        activeImageSet.add(json.textures[texture.index].source);
+                    }
+                }
+            }
+        } else {
+            /*
+             Only the images something will actually sample. A texture may offer the same picture in
+             several containers — `source` plus an extension — and fetching the ones this loader has
+             already decided against is not merely wasted: `createImageBitmap` rejects on a container
+             the browser cannot decode, and an image nothing was going to sample takes the whole model
+             down with it. The game's level models each carry a DDS beside their PNG for exactly that
+             reason, and not one of them loaded.
+             */
+            activeImageSet = gltf_used_image_indices(json);
+        }
+
+        /**
+         * The images `KHR_texture_basisu` names, which are KTX2 containers whatever else the file
+         * says about them.
+         *
+         * @type {Set<number>}
+         */
+        const basisu_images = gltf_basisu_image_indices(json);
+
+        /**
+         * What each image is for, which is what picks its transcode target.
+         *
+         * @type {Map<number, TextureRole>}
+         */
+        const image_roles = gltf_image_roles(json);
+
+        /**
+         * Images
+         * @type {Promise<ImageBitmap|ShadeTexelData>[]}
+         */
+        const pendingImages = [];
+        for (let index = 0; index < json.images?.length || 0; ++index) {
+            if (activeImageSet && !activeImageSet.has(index)) {
+                continue;
+            }
+            const image = json.images[index];
+
+            /**
+             *
+             * @param {Blob} blob
+             * @return {Promise<ImageBitmap>}
+             */
+            function blob_to_bitmap(blob) {
+                return createImageBitmap(blob, {
+                    // premultiplication is done during texture upload
+                    premultiplyAlpha: "none",
+                })
+            }
+
+            /**
+             * A dropped file's bytes. `fileMap` holds whatever the drop handler put there.
+             *
+             * @param {File|Blob|ArrayBuffer} file
+             * @return {Promise<ArrayBuffer>}
+             */
+            function file_to_bytes(file) {
+                return file instanceof Blob ? file.arrayBuffer() : Promise.resolve(file);
+            }
+
+            /*
+             **A KTX2 image cannot go through `createImageBitmap`** — no browser decodes the
+             container, and handing it one is how an unsupported container took a whole level down
+             before. It is read here instead, into texels already in a device format, and what comes
+             out is a `ShadeTexelData` rather than an `ImageBitmap`. `load_gltf` tells the two apart
+             and wraps each in a `ShadeImage`, below which nothing knows the difference.
+
+             **Which images those are comes from the extension, not from the MIME type.**
+             `KHR_texture_basisu` only *requires* `image/ktx2` inside a GLB, where the image comes
+             from a bufferView; an image referenced by URI is merely *permitted* to declare it. So a
+             legal `.gltf` may say nothing but `{"uri": "wood.ktx2"}`, and going by MIME type alone
+             would send exactly that file to `createImageBitmap`. The type is still honoured where it
+             is present, since a GLB is required to carry it and an image may be reached by an
+             extension this loader does not read.
+            */
+            const ktx2 = basisu_images.has(index) || image.mimeType === KTX2_MIME_TYPE;
+
+            // which material slot this image fills, so a normal map can be asked for as BC5
+            const image_role = image_roles.get(index);
+
+            if (image.uri) {
+
+                // Check fileMap first (enables loading from dropped files)
+                if (this.fileMap) {
+                    const file = this.fileMap.get(image.uri);
+
+                    if (file !== undefined) {
+                        pendingImages[index] = ktx2
+                            ? file_to_bytes(file).then(bytes => this.#read_ktx2(bytes, image_role))
+                            : blob_to_bitmap((file instanceof Blob) ? file : new Blob([file]));
+                        continue;
+                    }
+                }
+
+                /*
+                 Decoded by the framework rather than here, which is what makes one texture shared
+                 by two models one decode instead of two — the expensive half of loading a model is
+                 its images, and a level places the same handful of them hundreds of times.
+
+                 A KTX2 image asks for bytes instead. The framework has no decoder for the container
+                 and would have nowhere to cache the result of one, since what a transcode produces
+                 depends on the device it was chosen for.
+                */
+                pendingImages[index] = ktx2
+                    ? this.#read(resolveUri(image.uri, baseUrl), GameAssetType.ArrayBuffer)
+                        .then(buffer => this.#read_ktx2(buffer, image_role))
+                    : this.#read(resolveUri(image.uri, baseUrl), GameAssetType.ImageBitmap);
+
+            } else {
+
+                const bufferView = json.bufferViews[image.bufferView];
+
+                const claimed = this.bufferViewExtensions.claim(bufferView, image.bufferView);
+
+                if (claimed !== null) {
+                    /*
+                     Legal to write and pointless to: the payload is a PNG or a JPEG, already
+                     compressed. Decoding it is not implemented, and the alternative to saying so is
+                     handing the image decoder a placeholder buffer's bytes.
+                    */
+                    throw new Error(
+                        `images[${index}] is sourced from a bufferView '${claimed.name}' produces,`
+                        + ` which is not supported`
+                    );
+                }
+
+                pendingImages[index] = pendingBuffers[bufferView.buffer].then((buffer) => {
+
+                    const bytes = buffer.subarray(
+                        bufferView.byteOffset,
+                        bufferView.byteOffset + bufferView.byteLength
+                    );
+
+                    if (ktx2) {
+                        return this.#read_ktx2(bytes, image_role);
+                    }
+
+                    return blob_to_bitmap(new Blob([bytes], { type: image.mimeType }));
+                });
+
+            }
+        }
+
+        // Place every node, and bound every mesh, node and scene, starting at the roots.
+        place_nodes(json);
+
+        // Replace the resolved resources in the JSON structure.
+        const buffers = await Promise.all(pendingBuffers);
+
+        /*
+         Views that some extension produces the bytes for become ordinary ones here, over decoded
+         buffers appended to the list, so that nothing downstream - accessors, sparse accessors, the
+         mesh reader - has to know any of those extensions exist. Nor does this parser: it asks the
+         set what claims a view, and the set is the one place that knows what is implemented.
+
+         Per view, and guarded per view. A file nothing claims - which is nearly all of them - gets
+         its own view objects back by identity and appends no buffer.
+        */
+        json.bufferViews = gltf_apply_buffer_view_extensions(
+            json.bufferViews, buffers, this.bufferViewExtensions
+        );
+
+        json.buffers = buffers;
+        json.images = await Promise.all(pendingImages);
+
+        return json;
+    }
+
+
+}
+