@woosh/meep-engine 3.14.2 → 3.14.3

package/src/shade/renderer/loader/gltf/load_gltf.js

@@ -1,1253 +1,1179 @@
-import { assert } from "../../../../core/assert.js";
-import { HashMap } from "../../../../core/collection/map/HashMap.js";
-import { HashSet } from "../../../../core/collection/set/HashSet.js";
-import { Color } from "../../../../core/color/Color.js";
-import { Quaternion } from "../../../../core/geom/Quaternion.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { clamp } from "../../../../core/math/clamp.js";
-import { clamp01 } from "../../../../core/math/clamp01.js";
-import { computeObjectHash } from "../../../../core/math/hash/computeObjectHash.js";
-import { inverseLerp } from "../../../../core/math/inverseLerp.js";
-import { objectDeepEquals } from "../../../../core/model/object/objectDeepEquals.js";
-import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
-import { AnimationInterpolationKind } from "../../../../engine/animation/clip/AnimationInterpolationKind.js";
-import { curve_from_track_data } from "../../../../engine/animation/clip/curve_from_track_data.js";
-import { AnimationCurve } from "../../../../engine/animation/curve/AnimationCurve.js";
-import { t64_look_rotation } from "../../../../engine/ecs/transform/t64_look_rotation.js";
-import { t64_transform_direction } from "../../../../engine/ecs/transform/t64_transform_direction.js";
-import { meshopt_optimizeVertexCache } from "../../../../engine/graphics/geometry/optimization/VertexCacheOptimizer.js";
-import { ShadeAnimationChannel } from "../../animation/ShadeAnimationChannel.js";
-import { ShadeAnimationClip } from "../../animation/ShadeAnimationClip.js";
-import { Skin } from "../../animation/Skin.js";
-import { Attribute } from "../../geometry/Attribute.js";
-import { Geometry, GeometryFlags } from "../../geometry/Geometry.js";
-import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
-import { StandardAttributes } from "../../geometry/StandardAttributes.js";
-import { normalize_attribute } from "../../geometry/util/normalize_attribute.js";
-import { DirectionalLight } from "../../light/model/DirectionalLight.js";
-import { PointLight } from "../../light/model/PointLight.js";
-import { SpotLight } from "../../light/model/SpotLight.js";
-
-import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
-import { Node3DProperty } from "../../object_property/Node3DProperty.js";
-import { Mesh } from "../../scene/Mesh.js";
-import { Node3D } from "../../scene/Node3D.js";
-import { SkinnedMesh } from "../../scene/SkinnedMesh.js";
-import { ShadeTexture } from "../../texture/ShadeTexture.js";
-import { ShadeImage } from "../../texture/source/ShadeImage.js";
-import { TextureFilterType } from "../../texture/TextureFilterType.js";
-import { TextureWrapType } from "../../texture/TextureWrapType.js";
-import { SceneBundle } from "../SceneBundle.js";
-import { coalesce_array_duplicates } from "./coalesce_array_duplicates.js";
-import { fix_up_material_sides } from "./fix_up_material_sides.js";
-import { GLTF_COMPONENT_TYPE } from "./gltf_component_type.js";
-import { gltf_create_material } from "./gltf_create_material.js";
-import { GLTF_PRIMITIVE_MODE, GLTF_PRIMITIVE_MODE_DEFAULT } from "./GLTF_PRIMITIVE_MODE.js";
-import { gltf_read_accessor } from "./gltf_read_accessor.js";
-import { gltf_used_image_indices } from "./gltf_used_image_indices.js";
-import { TinyGltf } from "./tiny-gltf.js";
-
-
-/**
- * Somewhere to hand `canonicalize_quaternion_signs` a rest rotation it can read by component name —
- * a `Transform64` addresses its rotation by index, and the function's contract is named components.
- *
- * @type {Quaternion}
- */
-const SCRATCH_REST_ROTATION = new Quaternion();
-
-/**
- * Somewhere to read a light's facing before flipping it.
- *
- * @type {Vector3}
- */
-const SCRATCH_DIRECTION = new Vector3();
-const OPTIMIZE_GEOMETRIES = false;
-
-const WEBGL_FILTER_NEAREST = 9728;
-const WEBGL_FILTER_LINEAR = 9729;
-const WEBGL_FILTER_NEAREST_MIPMAP_NEAREST = 9984;
-const WEBGL_FILTER_LINEAR_MIPMAP_NEAREST = 9985;
-const WEBGL_FILTER_NEAREST_MIPMAP_LINEAR = 9986;
-const WEBGL_FILTER_LINEAR_MIPMAP_LINEAR = 9987;
-
-const WEBGL_FILTERS = {
-    [WEBGL_FILTER_NEAREST]: TextureFilterType.Nearest,
-    [WEBGL_FILTER_LINEAR]: TextureFilterType.Linear,
-    [WEBGL_FILTER_NEAREST_MIPMAP_NEAREST]: TextureFilterType.Nearest,
-    [WEBGL_FILTER_LINEAR_MIPMAP_NEAREST]: TextureFilterType.Nearest,
-    [WEBGL_FILTER_NEAREST_MIPMAP_LINEAR]: TextureFilterType.Linear,
-    [WEBGL_FILTER_LINEAR_MIPMAP_LINEAR]: TextureFilterType.Linear
-};
-
-
-/**
- *
- * @param {number} filter
- * @returns {boolean}
- */
-function webgl_filter_mipmap_linear(filter) {
-    switch (filter) {
-        case WEBGL_FILTER_LINEAR_MIPMAP_NEAREST:
-        case WEBGL_FILTER_LINEAR_MIPMAP_LINEAR:
-            return true;
-    }
-
-    return false;
-}
-
-/**
- *
- * @param {number} minFilter
- * @returns {TextureFilterType}
- */
-function webgl_filter_mipmap(minFilter) {
-    if (minFilter === undefined || webgl_filter_mipmap_linear(minFilter)) {
-        return TextureFilterType.Linear;
-    }
-
-    return TextureFilterType.Nearest;
-}
-
-const WEBGL_WRAPPINGS = {
-    33071: TextureWrapType.ClampToEdge,
-    33648: TextureWrapType.MirroredRepeat,
-    10497: TextureWrapType.Repeat
-};
-
-/**
- * @see https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
- * @param {string} id
- */
-function gltf_attribute_id_to_standard(id) {
-    switch (id) {
-        case "POSITION":
-            return StandardAttributes.Position;
-        case "NORMAL":
-            return StandardAttributes.Normal;
-        case "TEXCOORD_0":
-            return StandardAttributes.TextureCoordinates0;
-        case "TEXCOORD_1":
-            return StandardAttributes.TextureCoordinates1;
-        case "TANGENT":
-            return StandardAttributes.Tangent;
-        case "COLOR_0":
-            return StandardAttributes.Color;
-        case "JOINTS_0":
-            return StandardAttributes.SkinningJoints;
-        case "WEIGHTS_0":
-            return StandardAttributes.SkinningWeights;
-        default:
-            return id;
-    }
-}
-
-/**
- * Map glTF `animation.channels[].target.path` to {@link Node3DProperty}.
- * Returns `-1` for paths we don't yet drive (morph-target `weights`),
- * so the caller can skip those channels without throwing.
- *
- * @param {string} path
- * @returns {number}
- */
-function gltf_animation_path_to_property(path) {
-    switch (path) {
-        case "translation":
-            return Node3DProperty.Translation;
-        case "rotation":
-            return Node3DProperty.Rotation;
-        case "scale":
-            return Node3DProperty.Scale;
-        default:
-            // "weights" (morph targets) lands here; we don't yet have
-            // morph-target support in the renderer.
-            return -1;
-    }
-}
-
-/**
- * Number of scalar components per keyframe value for a given Node3D
- * property — translation/scale = 3 (vec3), rotation = 4 (quaternion
- * x/y/z/w).
- *
- * @param {number} property one of {@link Node3DProperty}
- * @returns {number}
- */
-function node3d_property_component_count(property) {
-    switch (property) {
-        case Node3DProperty.Translation:
-        case Node3DProperty.Scale:
-            return 3;
-        case Node3DProperty.Rotation:
-            return 4;
-        default:
-            throw new Error(`Unsupported animated property ${property}`);
-    }
-}
-
-/**
- * Walk a flat keyframe-values buffer for a rotation channel and flip
- * the sign of any keyframe whose val-quaternion has negative dot
- * product with the previous keyframe's val-quaternion. The same flip
- * is applied to that keyframe's in/out tangents in CUBICSPLINE mode
- * so the cubic remains internally consistent.
- *
- * The flip preserves the rotation (q and -q encode the same
- * orientation) while ensuring per-component interpolation between
- * consecutive keyframes follows the short arc instead of passing
- * through a near-zero quaternion mid-segment.
- *
- * The curve's leading sign is anchored against `rest_rotation` —
- * the target node's authored local rest rotation: when the first
- * keyframe's val-quat has negative dot product with the rest
- * quaternion, the whole first keyframe block is negated (and the
- * consecutive-keyframe pass propagates that sign down the curve).
- * Every rotation curve targeting one node aligns against the same
- * reference, so weighted multi-clip blends accumulate
- * hemisphere-consistent contributions instead of cancelling toward
- * a near-zero quaternion. Residual limitation: the anchor is the
- * FIRST keyframe only — a curve that swings more than 90° away
- * from the rest rotation mid-clip can still contribute opposite
- * signs to another clip at those times; fixing that would need
- * apply-time alignment, which the atomic pose accumulator cannot
- * do order-independently.
- *
- * Mutates `values` in place. Safe to call on an output array that's
- * a fresh copy of the source accessor (which is what
- * {@link read_accessor_as_float32_array} produces).
- *
- * Exported for spec coverage; not part of the loader's public API.
- *
- * @param {Float32Array} values flat values: STEP/LINEAR uses 4
- *     floats/keyframe (x, y, z, w); CUBICSPLINE uses 12 (inX, inY,
- *     inZ, inW, valX, valY, valZ, valW, outX, outY, outZ, outW).
- * @param {number} key_count
- * @param {number} interpolation one of {@link AnimationInterpolationKind}
- * @param {{x:number, y:number, z:number, w:number}} [rest_rotation]
- *     target node's authored local rest rotation; omitted → the
- *     leading sign is kept as authored.
- */
-export function canonicalize_quaternion_signs(values, key_count, interpolation, rest_rotation) {
-    const is_cubic = interpolation === AnimationInterpolationKind.CubicTangents;
-    const stride = is_cubic ? 12 : 4;
-    // Offset into a keyframe block at which the val-quat sits.
-    // CUBICSPLINE has [in, val, out]; the val starts at offset 4 (i.e.
-    // after the 4-float in-tangent). STEP/LINEAR has just val at 0.
-    const val_offset = is_cubic ? 4 : 0;
-
-    if (key_count >= 1 && rest_rotation !== undefined) {
-        const rest_dot =
-            values[val_offset + 0] * rest_rotation.x +
-            values[val_offset + 1] * rest_rotation.y +
-            values[val_offset + 2] * rest_rotation.z +
-            values[val_offset + 3] * rest_rotation.w;
-
-        if (rest_dot < 0) {
-            // Negate the whole first keyframe block (value +
-            // tangents); the loop below carries the flip through
-            // the remaining keyframes.
-            for (let i = 0; i < stride; i++) {
-                values[i] = -values[i];
-            }
-        }
-    }
-
-    for (let k = 1; k < key_count; k++) {
-        const prev_base = (k - 1) * stride + val_offset;
-        const cur_base = k * stride + val_offset;
-
-        const dot =
-            values[prev_base + 0] * values[cur_base + 0] +
-            values[prev_base + 1] * values[cur_base + 1] +
-            values[prev_base + 2] * values[cur_base + 2] +
-            values[prev_base + 3] * values[cur_base + 3];
-
-        if (dot < 0) {
-            // Flip the whole keyframe block (value + tangents).
-            const start = k * stride;
-            const end = start + stride;
-            for (let i = start; i < end; i++) {
-                values[i] = -values[i];
-            }
-        }
-    }
-}
-
-/**
- * Map glTF interpolation strings to the engine's enum. Defaults to
- * LINEAR when missing — the glTF spec's default.
- *
- * @param {string|undefined} interpolation
- * @returns {number} one of {@link AnimationInterpolationKind}
- */
-function gltf_interpolation_to_kind(interpolation) {
-    switch (interpolation) {
-        case "STEP":
-            return AnimationInterpolationKind.Discrete;
-        case "CUBICSPLINE":
-            return AnimationInterpolationKind.CubicTangents;
-        case "LINEAR":
-        case undefined:
-            return AnimationInterpolationKind.Linear;
-        default:
-            throw new Error(`Unsupported interpolation '${interpolation}'`);
-    }
-}
-
-/**
- * Input can be a .glb or .gltf file.
- *
- * Does not support most compression GLTF extensions such as draco, basis etc.
- *
- * Returns a {@link SceneBundle} that groups the parsed scene roots
- * with any skins and animation clips extracted from the same asset.
- * Callers add `bundle.scenes` to their scene, then pass the bundle's
- * `skins` / `clips` to the scene's animation manager (e.g. via
- * {@link GPUAnimationManager#register_skin} and
- * {@link GPUAnimationManager#register_clip}) once `scene.build` has
- * populated `id_mapping` for the joint and target nodes.
- *
- * @param {string} url un-resolved — the asset manager resolves network paths
- * @param {Object} options
- * @param {AssetManager} options.assetManager where the container, its buffers and its images come
- *   from. Required: a glTF is several files, and which of them are already in memory is not this
- *   parser's business to know.
- * @param {AssetRequestScope} [options.scope] the load these requests belong to
- * @param {Map<string, File|Blob|ArrayBuffer>} [options.fileMap] Map of relative paths to file data.
- *   When provided, buffer and image URIs in the GLTF are resolved from this map before the asset
- *   framework is asked. Enables multi-file GLTF loading from drag-and-drop.
- * @return {Promise<SceneBundle>}
- */
-export function load_gltf(url, { assetManager, scope, fileMap } = {}) {
-    // TODO
-    //  apply some checks to the model, things like non-uniform scales, that can be fixed potentially
-    //  see https://www.youtube.com/watch?v=FJRO5wFTEc8 for common ideas
-    //  check for inverted normals
-    //  check for duplicated vertices
-    //  check for overlapping faces
-
-    async function process(gltf) {
-        // console.log(gltf);
-
-        /**
-         * @type {{type:string, componentType:number, count:number, bufferView:number, byteOffset:number, normalized:boolean, min?:number[], max?:number}[]}
-         */
-        const accessors = gltf.accessors;
-
-        /**
-         * `aabb` is six numbers, `[x0, y0, z0, x1, y1, z1]`, in world space — and is absent on a node
-         * that bounds nothing, meaning neither it nor anything below it declared any.
-         *
-         * {{aabb?:Float64Array, mesh:number, worldMatrix:Float32Array}[]}
-         */
-        const nodes = gltf.nodes;
-
-        /**
-         *
-         * @type {{aabb:Float64Array, primitives:({attributes:Object<number>,indices:number, material:number, mode:number}[])}[]}
-         */
-        const meshes = gltf.meshes;
-
-        /**
-         *
-         * @type {{}[]}
-         */
-        const scenes = gltf.scenes;
-
-        /**
-         * Engine Node3Ds indexed by glTF node index — populated lazily
-         * by {@link process_node} as the scene-graph recursion visits
-         * each node. Used afterwards to resolve skin joint references
-         * and animation channel targets (both of which point at glTF
-         * node indices, not at any in-memory object).
-         *
-         * @type {Node3D[]}
-         */
-        const node3d_by_index = new Array((gltf.nodes ?? []).length);
-
-        /**
-         * Queue of pending `skin.meshes` pushes. process_node() can't
-         * resolve `node.skin → Skin` directly because skins[] is built
-         * *after* the recursion completes (the joint lookup needs
-         * node3d_by_index fully populated). So we enqueue the produced
-         * SkinnedMeshes here and drain into the matching skin once the
-         * walk finishes.
-         *
-         * @type {{ skin_index: number, meshes: Mesh[] }[]}
-         */
-        const skin_mesh_pushes = [];
-
-        /**
-         * Primitive converted to JSON string serves as key
-         * @type {Map<string, MeshletGeometry>}
-         */
-        const geometry_cache = new Map();
-
-        /**
-         *
-         * @type {HashSet<MeshletGeometry>}
-         */
-        const geometry_cache_secondary = new HashSet();
-
-        /**
-         * Indexed as `gltf.images` is, and populated only where an image was actually fetched.
-         *
-         * Built from {@link gltf_used_image_indices} rather than by mapping the whole list, because
-         * that is the same function the fetch is filtered by: the two cannot drift into decoding one
-         * set and sampling another, and there is no slot here for an image that was never brought in.
-         *
-         * @type {ShadeImage[]}
-         */
-        const mapped_images = [];
-
-        for (const index of gltf_used_image_indices(gltf)) {
-            mapped_images[index] = ShadeImage.fromImageBitmap(gltf.images[index]);
-        }
-
-        /**
-         * used when no material is specified
-         * @type {StandardShadeMaterial}
-         */
-        const default_material = new StandardShadeMaterial();
-
-        /**
-         * Used when no sampler is present
-         * @type {{}}
-         */
-        const default_sampler_description = {};
-
-        /**
-         *
-         * @type {ShadeTexture[]}
-         */
-        const mapped_textures = (gltf.textures ?? []).map(gltf_texture => {
-
-            const sampler = gltf_texture.sampler;
-
-            let source;
-
-            const extensions = gltf_texture.extensions;
-            if (extensions !== undefined) {
-
-                source = extensions.EXT_texture_webp?.source;
-
-            }
-
-            if (source === undefined) {
-                source = gltf_texture.source;
-            }
-
-            const image = mapped_images[source];
-
-
-            /**
-             * @type {{magFilter:number, minFilter:number, wrapS:number, wrapT:number}}
-             */
-            let sampler_descriptor;
-
-            if (gltf.samplers !== undefined && gltf.samplers[sampler] !== undefined) {
-                sampler_descriptor = gltf.samplers[sampler]
-            } else {
-                sampler_descriptor = default_sampler_description;
-            }
-
-            const texture = ShadeTexture.from(image);
-
-            texture.magFilter = WEBGL_FILTERS[sampler_descriptor.magFilter] ?? TextureFilterType.Linear;
-            texture.minFilter = WEBGL_FILTERS[sampler_descriptor.minFilter] ?? TextureFilterType.Linear;
-            texture.mipmapFilter = webgl_filter_mipmap(sampler_descriptor.minFilter);
-
-            texture.wrapS = WEBGL_WRAPPINGS[sampler_descriptor.wrapS] ?? TextureWrapType.Repeat;
-            texture.wrapT = WEBGL_WRAPPINGS[sampler_descriptor.wrapT] ?? TextureWrapType.Repeat;
-
-            return texture;
-        });
-
-        coalesce_array_duplicates(mapped_textures);
-
-        // account for materials missing
-        const gltf_materials = gltf.materials ?? [];
-
-        const mapped_materials = gltf_materials.map(gltf_mat => gltf_create_material(gltf_mat, mapped_textures));
-
-        // dedupe materials
-        coalesce_array_duplicates(mapped_materials);
-
-
-        /**
-         * One accessor as an attribute in the shape the renderer stores it.
-         *
-         * The read itself — stride, sparse overlay, a view-less accessor's zeroes — belongs to the
-         * format and is done by {@link gltf_read_accessor}; what is left here is the engine's own
-         * question of which storage type an attribute of this name is kept in.
-         *
-         * @param {number} accessor_index
-         * @param {string} name
-         * @returns {Attribute}
-         */
-        function buffer_to_attribute(accessor_index, name) {
-            const data = gltf_read_accessor(gltf, accessor_index);
-
-            const raw_attribute = Attribute.from(data.values, data.components, name);
-
-            raw_attribute.spec.normalized = data.normalized;
-
-            return normalize_attribute(raw_attribute);
-        }
-
-        /**
-         *
-         * @type {HashMap<Object, Attribute>}
-         */
-        const attribute_cache = new HashMap({
-            keyEqualityFunction: objectDeepEquals,
-            keyHashFunction: computeObjectHash
-        });
-
-        /**
-         *
-         * @param {number} attribute_accessor
-         * @param {string} name
-         * @returns {Attribute}
-         */
-        function obtain_attribute(attribute_accessor, name) {
-            const key = {
-                attribute_accessor, name
-            };
-
-            let attribute = attribute_cache.get(key);
-
-            if (attribute === undefined) {
-                attribute = buffer_to_attribute(attribute_accessor, name);
-                attribute_cache.set(key, attribute);
-            } else {
-                // console.warn('attribute reuse')
-            }
-
-            return attribute;
-        }
-
-        /**
-         * A FLOAT-componentType accessor's values as a flat `Float32Array`. Used for animation
-         * sampler inputs/outputs (times, values) and the skin inverse-bind matrices, where
-         * downstream code wants a stride-free flat buffer.
-         *
-         * @param {number} accessor_index
-         * @returns {Float32Array}
-         */
-        function read_accessor_as_float32_array(accessor_index) {
-            const accessor = accessors[accessor_index];
-
-            assert.equal(
-                accessor.componentType, GLTF_COMPONENT_TYPE.FLOAT,
-                `accessor[${accessor_index}].componentType must be FLOAT for read_accessor_as_float32_array`
-            );
-
-            return gltf_read_accessor(gltf, accessor_index).values;
-        }
-
-        /**
-         *
-         * @returns {MeshletGeometry}
-         */
-        function primitive_to_geometry(primitive) {
-            const geometry = new Geometry();
-
-            const mode = primitive.mode ?? GLTF_PRIMITIVE_MODE_DEFAULT;
-
-            if (mode !== GLTF_PRIMITIVE_MODE.TRIANGLES) {
-                throw new Error('Unsupported draw method');
-            }
-
-            for (const attribute_key in primitive.attributes) {
-
-                const name = gltf_attribute_id_to_standard(attribute_key);
-
-                if (geometry.getAttribute(name) !== undefined) {
-                    console.warn(`attribute '${name}' already exists, skipping. Primitive.attributes = ${JSON.stringify(primitive.attributes)}`)
-                }
-
-                /**
-                 * @type {number}
-                 */
-                const attribute_accessor = primitive.attributes[attribute_key];
-
-                let attribute;
-                try {
-                    attribute = obtain_attribute(attribute_accessor, name);
-                } catch (e) {
-                    console.warn(`Failed to parse attribute '${name}'. Skipping`, e);
-                    continue;
-                }
-
-                geometry.addAttribute(attribute);
-
-
-                if (attribute_key === "POSITION") {
-                    // The spec mandates POSITION accessors carry min/max,
-                    // so we can adopt them as the bounding box without
-                    // walking the vertex data. The sphere is derived from
-                    // the box inside meshlet_geometry_build_from_geometry,
-                    // so we just clear the dirty flag here.
-                    const accessor = accessors[attribute_accessor];
-
-                    if (accessor.min !== undefined && accessor.max !== undefined) {
-                        geometry.bounding_box.set([
-                            ...accessor.min,
-                            ...accessor.max
-                        ]);
-
-                        geometry.clearFlag(GeometryFlags.BoundsNeedUpdate);
-                    }
-                }
-            }
-
-            if (primitive.indices !== undefined) {
-
-                geometry.index = obtain_attribute(primitive.indices, 'index');
-
-                // geometry_fix_index(geometry.index, geometry.getVertexCount());
-            }
-
-
-            // vertex optimize
-            if (geometry.index !== null && OPTIMIZE_GEOMETRIES) {
-                meshopt_optimizeVertexCache(geometry.index.data, geometry.index.data, geometry.index.count, geometry.getVertexCount());
-            }
-
-            return meshlet_geometry_build_from_geometry(geometry);
-        }
-
-        function obtain_geometry_by_primitive(primitive) {
-            const key = JSON.stringify(primitive);
-
-            let geometry = geometry_cache.get(key);
-
-            if (geometry === undefined) {
-                geometry = primitive_to_geometry(primitive)
-
-                const secondary_cached = geometry_cache_secondary.get(geometry);
-
-                if (secondary_cached !== undefined) {
-                    // found an equivalent geometry in the secondary cache, use it instead
-                    geometry = secondary_cached;
-                    // console.warn("secondary reuse");
-                } else {
-                    geometry_cache_secondary.add(geometry);
-                }
-
-                geometry_cache.set(key, geometry);
-            } else {
-                // console.warn('geometry reuse');
-            }
-
-            return geometry;
-        }
-
-
-        /**
-         * Build the renderable mesh(es) for one glTF node.
-         *
-         * A glTF mesh is a list of primitives sharing a name and an
-         * `aabb`, and each primitive becomes one engine-side {@link Mesh}.
-         * When the owning glTF node references a skin, every primitive is
-         * instead constructed as a {@link SkinnedMesh} so the renderer
-         * routes it through a per-instance geometry clone for deformation.
-         *
-         * @param {number} mesh_index
-         * @param {{}} node
-         * @param {boolean} is_skinned
-         * @returns {Mesh[]}
-         */
-        function process_mesh(mesh_index, node, is_skinned) {
-
-            const mesh = meshes[mesh_index];
-
-            const primitives = mesh.primitives;
-
-            const primitive_count = primitives.length;
-
-            /**
-             *
-             * @type {Mesh[]}
-             */
-            const result = [];
-
-            for (let i = 0; i < primitive_count; i++) {
-                const primitive = primitives[i];
-
-                // build geometry
-
-                /**
-                 * @type {MeshletGeometry}
-                 */
-                let geometry;
-
-                try {
-                    geometry = obtain_geometry_by_primitive(primitive);
-                } catch (e) {
-                    console.error(`Failed to obtain geometry for primitive [${i}] ${primitive}. `, e);
-                    console.log('Ignoring mesh');
-                    continue;
-                }
-
-                if (primitive_count === 1 && mesh.name !== undefined) {
-                    geometry.name = mesh.name;
-                }
-
-                const material_id = primitive.material;
-
-                let material;
-
-                if (material_id !== undefined) {
-                    material = mapped_materials[material_id];
-
-                    if (material === undefined) {
-                        console.warn(`specified material ${material_id} does not exist. Using default.`);
-
-                        material = default_material;
-                    }
-
-                } else {
-                    // no material specified, use default
-                    material = default_material;
-                }
-
-                const engine_mesh = is_skinned ? new SkinnedMesh() : new Mesh();
-                engine_mesh.geometry = geometry;
-                engine_mesh.material = material;
-                engine_mesh.transform_global.fromMatrix(node.worldMatrix);
-
-
-                if (mesh.name !== undefined) {
-                    engine_mesh.name = mesh.name;
-                }
-
-                result.push(engine_mesh);
-            }
-
-            return result;
-        }
-
-        /**
-         *
-         * @param {number} light_index
-         * @param {{}} node
-         * @returns {AbstractLight}
-         */
-        function process_light(light_index, node) {
-
-            // SPEC: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_lights_punctual/README.md
-
-            const gltf_light = gltf.extensions.KHR_lights_punctual.lights[light_index];
-
-            // parse color
-            const color = new Color();
-
-            if (gltf_light.color !== undefined) {
-                color.fromArray(gltf_light.color);
-            } else {
-                color.setRGB(1, 1, 1);
-            }
-
-            const intensity = gltf_light.intensity ?? 1;
-
-            const name = gltf_light.name ?? "";
-
-            let light;
-
-            const type = gltf_light.type;
-
-            switch (type) {
-                case "directional":
-                    light = new DirectionalLight();
-                    break;
-                case "point":
-                    light = new PointLight();
-                    light.distance = gltf_light.range ?? 1e20; // default light radius
-                    break;
-                case "spot":
-                    light = new SpotLight();
-
-                    const gltf_spot = gltf_light.spot;
-
-                    const outerCone = gltf_spot?.outerConeAngle ?? (Math.PI / 4); // default PI/4
-                    const innerCone = gltf_spot?.innerConeAngle ?? 0;
-
-                    light.angle = clamp(
-                        outerCone,
-                        0,
-                        Math.PI / 2
-                    );
-
-                    light.penumbra = clamp01(
-                        inverseLerp(light.angle, 0, innerCone)
-                    );
-
-                    light.distance = gltf_light.range ?? 1e20;
-                    // TODO rotation is messed up?
-                    break;
-                default:
-                    throw new Error(`Unsupported light type ${type}`);
-            }
-
-            light.color.copy(color);
-            light.intensity = intensity;
-            light.name = name;
-
-            // check for light radius
-            light.radius = gltf_light.extras?.radius ?? 0;
-
-            light.near_clip_distance = gltf_light.extras?.near_clip_distance ?? light.radius;
-
-            light.casts_shadow = true;
-
-            return light;
-        }
-
-        /**
-         *
-         * @param {Node3D} parent
-         * @param {number} node_index
-         */
-        function process_node(parent, node_index) {
-
-            const node = nodes[node_index];
-
-            // glTF "skin" attaches at the node, not the mesh: every
-            // primitive of the referenced mesh becomes a SkinnedMesh
-            // bound to this skin. Resolved later (after the recursion
-            // is done) against `skins[]`, which we've already built
-            // — the joint Node3Ds may be visited *after* this node,
-            // so we just record the produced SkinnedMeshes here and
-            // push them into `skin.meshes` once the walk finishes.
-            const skin_index = typeof node.skin === "number" ? node.skin : -1;
-
-            let node3d;
-            let produced_skinned_meshes = null;
-
-            if (node.extensions !== undefined && node.extensions.KHR_lights_punctual !== undefined) {
-                const light_index = node.extensions.KHR_lights_punctual.light;
-
-                try {
-                    node3d = process_light(light_index, node);
-                } catch (e) {
-                    console.error("Failed to process light ", light_index, " ", e);
-                }
-            }
-
-
-            if (typeof node.mesh === "number") {
-                const meshes = process_mesh(node.mesh, node, skin_index !== -1);
-
-                if (meshes.length === 1) {
-                    node3d = meshes[0];
-                } else if (meshes.length > 1) {
-                    node3d = new Node3D();
-
-                    node3d.addChildren(meshes)
-                }
-
-                if (skin_index !== -1) {
-                    produced_skinned_meshes = meshes;
-                }
-            }
-
-            if (node3d === undefined) {
-                node3d = new Node3D();
-            }
-
-            // Stash by glTF index — joint refs and animation channel
-            // targets resolve through this lookup once the recursion
-            // unwinds.
-            node3d_by_index[node_index] = node3d;
-
-            if (node.name !== undefined) {
-                node3d.name = node.name;
-            }
-
-            if (node.matrix !== undefined) {
-
-                node3d.transform_local.fromMatrix(node.matrix);
-
-            } else {
-
-                const t = node3d.transform_local;
-
-                if (node.translation !== undefined) {
-                    const v = node.translation;
-
-                    t.setTranslation(v[0], v[1], v[2]);
-                }
-
-                if (node.rotation !== undefined) {
-                    const q = node.rotation;
-
-                    t.setRotation(q[0], q[1], q[2], q[3]);
-                }
-
-                if (node.scale !== undefined) {
-                    const v = node.scale;
-
-                    t.setScale(v[0], v[1], v[2]);
-                }
-            }
-
-
-            if (node3d.isDirectionalLight || node3d.isSpotLight) {
-                // glTF lights shine along their local -Z; engine convention is forward = shining direction
-                const t = node3d.transform_local;
-
-                // the direction is read off the matrix, and a Transform64 does not maintain its own
-                t.updateMatrix();
-
-                t64_transform_direction(SCRATCH_DIRECTION, t, 0, 0, 1);
-
-                t64_look_rotation(
-                    t,
-                    -SCRATCH_DIRECTION.x, -SCRATCH_DIRECTION.y, -SCRATCH_DIRECTION.z,
-                    0, 1, 0
-                );
-            }
-
-            parent.addChild(node3d);
-
-            if (produced_skinned_meshes !== null) {
-                // Defer the `skin.meshes` push to after `skins[]` is
-                // built — we collect into a queue here and process it
-                // at the end of process().
-                skin_mesh_pushes.push({
-                    skin_index,
-                    meshes: produced_skinned_meshes,
-                });
-            }
-
-
-            if (node.children !== undefined) {
-
-                for (let i = 0; i < node.children.length; i++) {
-                    const node_index = node.children[i];
-
-                    process_node(node3d, node_index);
-                }
-            }
-        }
-
-        // console.time('parse-gltf');
-        // console.profile('parse-gltf');
-
-        /**
-         *
-         * @type {Node3D[]}
-         */
-        const scene_nodes3d = [];
-
-        for (let i = 0; i < scenes.length; i++) {
-            const scene = scenes[i];
-
-            const scene_node3d = new Node3D();
-
-            scene_nodes3d.push(scene_node3d);
-
-            /**
-             * @type {number[]}
-             */
-            const scene_nodes = scene.nodes;
-
-            const node_count = scene_nodes.length;
-
-            for (let i = 0; i < node_count; i++) {
-                const node_index = scene_nodes[i];
-                process_node(scene_node3d, node_index);
-            }
-
-            scene_node3d.updateMatrices();
-        }
-
-        // ── Skins ──────────────────────────────────────────────────
-        //
-        // Build {@link Skin} objects from `gltf.skins[]`. Joints
-        // resolve to Node3D refs through `node3d_by_index` (fully
-        // populated by the recursion above). Inverse-bind matrices
-        // come from a single MAT4 accessor — `joint_count * 16` f32s
-        // laid out column-major, copied into a flat Float32Array that
-        // the manager can subarray-view at registration time.
-        const skins = (gltf.skins ?? []).map((gltf_skin, skin_index) => {
-            const joint_indices = gltf_skin.joints;
-            const joint_count = joint_indices.length;
-
-            const joint_nodes = new Array(joint_count);
-            for (let i = 0; i < joint_count; i++) {
-                const joint_node_index = joint_indices[i];
-                const joint_node = node3d_by_index[joint_node_index];
-
-                assert.defined(
-                    joint_node,
-                    `skin[${skin_index}].joints[${i}] references unknown node index ${joint_node_index}`
-                );
-
-                joint_nodes[i] = joint_node;
-            }
-
-            // Inverse-bind matrices: glTF stores them MAT4-typed
-            // (column-major, 16 f32s per joint). When the accessor is
-            // omitted, the spec says every joint's IBM is identity —
-            // we materialise that here so the manager always sees a
-            // ready-to-use flat array.
-            let inverse_bind_matrices;
-            if (gltf_skin.inverseBindMatrices !== undefined) {
-                inverse_bind_matrices = read_accessor_as_float32_array(gltf_skin.inverseBindMatrices);
-            } else {
-                inverse_bind_matrices = new Float32Array(joint_count * 16);
-                for (let i = 0; i < joint_count; i++) {
-                    inverse_bind_matrices[i * 16 + 0] = 1;
-                    inverse_bind_matrices[i * 16 + 5] = 1;
-                    inverse_bind_matrices[i * 16 + 10] = 1;
-                    inverse_bind_matrices[i * 16 + 15] = 1;
-                }
-            }
-
-            return Skin.from({
-                name: gltf_skin.name ?? "",
-                joints: joint_nodes,
-                inverse_bind_matrices,
-                meshes: [],
-            });
-        });
-
-        // Drain the deferred skin.meshes pushes captured during the
-        // node walk.
-        for (let i = 0; i < skin_mesh_pushes.length; i++) {
-            const { skin_index, meshes: skin_meshes } = skin_mesh_pushes[i];
-            skins[skin_index].meshes.push(...skin_meshes);
-        }
-
-        // ── Animation clips ───────────────────────────────────────
-        //
-        // One glTF animation → one {@link ShadeAnimationClip}. Each
-        // channel becomes a {@link ShadeAnimationChannel}; per-component
-        // curves are built from the sampler's input (times) / output
-        // (values) accessors via the engine's curve_from_track_data
-        // helpers, which already handle STEP / LINEAR / CUBICSPLINE.
-        const clips = [];
-        const gltf_animations = gltf.animations ?? [];
-        for (let a = 0; a < gltf_animations.length; a++) {
-            const gltf_animation = gltf_animations[a];
-
-            const channels = [];
-
-            for (let c = 0; c < gltf_animation.channels.length; c++) {
-                const gltf_channel = gltf_animation.channels[c];
-                const target = gltf_channel.target;
-
-                const property = gltf_animation_path_to_property(target.path);
-                if (property === -1) {
-                    // Morph-target weights or other unsupported paths.
-                    continue;
-                }
-
-                if (target.node === undefined) {
-                    // Channels without a node target are a glTF
-                    // extension hook and not actionable here.
-                    continue;
-                }
-
-                const target_node = node3d_by_index[target.node];
-
-                assert.defined(
-                    target_node,
-                    `animations[${a}].channels[${c}].target.node ${target.node} not resolved`
-                );
-
-                const sampler = gltf_animation.samplers[gltf_channel.sampler];
-                const times = read_accessor_as_float32_array(sampler.input);
-                const values = read_accessor_as_float32_array(sampler.output);
-                const interpolation = gltf_interpolation_to_kind(sampler.interpolation);
-                const component_count = node3d_property_component_count(property);
-
-                // Canonicalize quaternion signs on rotation channels.
-                //
-                // glTF stores rotation keyframes as raw (x, y, z, w)
-                // quaternions, but `q` and `-q` represent the same
-                // orientation. Authoring tools (notably Mixamo) often
-                // alternate signs across consecutive keyframes when a
-                // bone passes through 180°. Per-component interpolation
-                // between sign-mismatched keyframes — especially
-                // CUBICSPLINE — passes through near-zero quaternions
-                // mid-segment; the apply shader's `normalize(value)`
-                // call then produces an effectively-identity quaternion
-                // for one frame, which reads as a one-frame snap to
-                // bind pose.
-                //
-                // Fix: flip the sign of every keyframe whose val-quat
-                // has negative dot product with the prior keyframe's
-                // val-quat. For CUBICSPLINE, flip the in/out tangents
-                // alongside the value so the cubic stays consistent.
-                // The leading sign is anchored against the target
-                // node's authored rest rotation so all clips driving
-                // one node land in the same hemisphere — required
-                // for weighted multi-clip blends, where the pose
-                // accumulator sums raw components across clips.
-                // No-op when the property isn't Rotation, or when the
-                // data was already canonicalized at export time.
-                if (property === Node3DProperty.Rotation && times.length >= 1) {
-                    // `canonicalize_quaternion_signs` reads the rest rotation by component name,
-                    // which a `Transform64` does not offer — hand it a quaternion instead
-                    const rest = target_node.transform_local;
-
-                    SCRATCH_REST_ROTATION.set(
-                        rest.rotation_x,
-                        rest.rotation_y,
-                        rest.rotation_z,
-                        rest.rotation_w
-                    );
-
-                    canonicalize_quaternion_signs(
-                        values, times.length, interpolation,
-                        SCRATCH_REST_ROTATION
-                    );
-                }
-
-                // Build the per-axis curves object. component_count
-                // is property-driven (3 for Translation/Scale, 4 for
-                // Rotation); slots beyond what the property uses are
-                // omitted. The keys align with the GPU track's
-                // (x, y, z, w) vec4f output — see ShadeAnimationChannel.
-                const axis_keys = ['x', 'y', 'z', 'w'];
-                const curves = {};
-                for (let comp = 0; comp < component_count; comp++) {
-                    const curve = new AnimationCurve();
-                    curve_from_track_data(curve, interpolation, values, times, component_count, comp);
-                    curves[axis_keys[comp]] = curve;
-                }
-
-                channels.push(ShadeAnimationChannel.from({
-                    target: target_node,
-                    property,
-                    curves,
-                }));
-            }
-
-            if (channels.length === 0) {
-                // All channels were unsupported / unresolved — skip
-                // the clip entirely so we don't emit a zero-channel
-                // record the manager would reject.
-                continue;
-            }
-
-            const clip = ShadeAnimationClip.from({
-                name: gltf_animation.name ?? "",
-                channels,
-            });
-
-            // Default optimization pass: strip channels that
-            // evaluate to the identity transform and individual
-            // per-axis curves that are constant at identity, then
-            // key-reduce the survivors. glTF exporters often emit
-            // redundant bind-pose channels (every joint gets a
-            // translation channel even when only rotation is
-            // animated), so this typically trims a sizeable
-            // fraction of the channel + curve count. Behaviour
-            // unchanged — applying the optimised clip produces
-            // the same poses.
-            //
-            // Stats are computed by diffing channel + total-curve
-            // counts before and after; the methods don't carry
-            // them in their return values.
-            const before_channels = clip.channels.length;
-            let before_curves = 0;
-            for (let i = 0; i < clip.channels.length; i++) {
-                before_curves += clip.channels[i].curve_count;
-            }
-
-            clip.optimize();
-
-            const after_channels = clip.channels.length;
-            let after_curves = 0;
-            for (let i = 0; i < clip.channels.length; i++) {
-                after_curves += clip.channels[i].curve_count;
-            }
-
-            const removed_channels = before_channels - after_channels;
-            const removed_curves = before_curves - after_curves;
-            if (removed_channels > 0 || removed_curves > 0) {
-                // console.log(
-                //     `[load_gltf] optimised clip '${clip.name}': ` +
-                //     `removed ${removed_channels} track(s), ` +
-                //     `${removed_curves} curve(s)`
-                // );
-            }
-
-            clips.push(clip);
-        }
-
-        // console.profileEnd('parse-gltf');
-        // console.timeEnd('parse-gltf');
-
-        const bundle = new SceneBundle();
-        bundle.scenes = scene_nodes3d;
-        bundle.skins = skins;
-        bundle.clips = clips;
-        return bundle;
-    }
-
-    /**
-     *
-     * @param {Node3D[]} scenes
-     */
-    function fix_scene_material_sidedness(scenes) {
-        const meshes = new Set();
-
-        for (const s of scenes) {
-            s.traverse(node => {
-                if (node.isMesh) {
-                    meshes.add(node);
-                }
-            });
-        }
-
-        const { geometries_modified: fixed_count, primitives_delta } = fix_up_material_sides(Array.from(meshes));
-
-        if (fixed_count > 0) {
-            console.warn(`Fixed ${fixed_count} geometries in accordance with material sidedness. Primitives added: ${number_format_by_thousands(primitives_delta)}`);
-        }
-
-        return scenes;
-    }
-
-
-    return load_gltf_document(url, { assetManager, scope, fileMap })
-        .then(process)
-        // .then(fix_scene_material_sidedness)
-        // .then(prepare_lightmap)
-        ;
-}
-
-/**
- * The same file, parsed and with its dependencies in memory, **without** being turned into anything
- * a renderer draws: the glTF's own JSON alongside `buffers` as `Uint8Array`s and `images` as
- * `ImageBitmap`s.
- *
- * The half of {@link load_gltf} that is not about pictures. A glTF carries more than a scene to draw
- * — collision hulls, navigation surfaces, spawn markers, whatever a tool reads accessors for — and
- * those consumers want the accessors and the bytes behind them, not a {@link SceneBundle} they would
- * have to take apart again.
- *
- * @param {string} url un-resolved — the asset manager resolves network paths
- * @param {Object} options
- * @param {AssetManager} options.assetManager
- * @param {AssetRequestScope} [options.scope]
- * @param {Map<string, File|Blob|ArrayBuffer>} [options.fileMap]
- * @returns {Promise<TinyGltf>}
- */
-export function load_gltf_document(url, { assetManager, scope, fileMap } = {}) {
-    const gltf = new TinyGltf(assetManager, scope);
-
-    if (fileMap) {
-        gltf.fileMap = fileMap;
-    }
-
-    return gltf.loadFromUrl(url);
-}
-
-
+import { assert } from "../../../../core/assert.js";
+import { HashMap } from "../../../../core/collection/map/HashMap.js";
+import { HashSet } from "../../../../core/collection/set/HashSet.js";
+import { Color } from "../../../../core/color/Color.js";
+import { Quaternion } from "../../../../core/geom/Quaternion.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { clamp } from "../../../../core/math/clamp.js";
+import { clamp01 } from "../../../../core/math/clamp01.js";
+import { computeObjectHash } from "../../../../core/math/hash/computeObjectHash.js";
+import { inverseLerp } from "../../../../core/math/inverseLerp.js";
+import { objectDeepEquals } from "../../../../core/model/object/objectDeepEquals.js";
+import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
+import { AnimationInterpolationKind } from "../../../../engine/animation/clip/AnimationInterpolationKind.js";
+import { curve_from_track_data } from "../../../../engine/animation/clip/curve_from_track_data.js";
+import { AnimationCurve } from "../../../../engine/animation/curve/AnimationCurve.js";
+import { t64_look_rotation } from "../../../../engine/ecs/transform/t64_look_rotation.js";
+import { t64_transform_direction } from "../../../../engine/ecs/transform/t64_transform_direction.js";
+import { meshopt_optimizeVertexCache } from "../../../../engine/graphics/geometry/optimization/VertexCacheOptimizer.js";
+import { ShadeAnimationChannel } from "../../animation/ShadeAnimationChannel.js";
+import { ShadeAnimationClip } from "../../animation/ShadeAnimationClip.js";
+import { Skin } from "../../animation/Skin.js";
+import { Attribute } from "../../geometry/Attribute.js";
+import { Geometry, GeometryFlags } from "../../geometry/Geometry.js";
+import { meshlet_geometry_build_from_geometry } from "../../geometry/meshlet_geometry_build_from_geometry.js";
+import { StandardAttributes } from "../../geometry/StandardAttributes.js";
+import { normalize_attribute } from "../../geometry/util/normalize_attribute.js";
+import { DirectionalLight } from "../../light/model/DirectionalLight.js";
+import { PointLight } from "../../light/model/PointLight.js";
+import { SpotLight } from "../../light/model/SpotLight.js";
+
+import { StandardShadeMaterial } from "../../material/StandardShadeMaterial.js";
+import { Node3DProperty } from "../../object_property/Node3DProperty.js";
+import { Mesh } from "../../scene/Mesh.js";
+import { Node3D } from "../../scene/Node3D.js";
+import { SkinnedMesh } from "../../scene/SkinnedMesh.js";
+import { ShadeTexture } from "../../texture/ShadeTexture.js";
+import { ShadeImage } from "../../texture/source/ShadeImage.js";
+import { SceneBundle } from "../SceneBundle.js";
+import { coalesce_array_duplicates } from "../../../../format/scene/gltf/coalesce_array_duplicates.js";
+import { fix_up_material_sides } from "./fix_up_material_sides.js";
+import { GLTF_COMPONENT_TYPE } from "../../../../format/scene/gltf/gltf_component_type.js";
+import { gltf_create_material } from "./gltf_create_material.js";
+import { gltf_create_texture } from "./gltf_create_texture.js";
+import { GLTF_PRIMITIVE_MODE, GLTF_PRIMITIVE_MODE_DEFAULT } from "../../../../format/scene/gltf/GLTF_PRIMITIVE_MODE.js";
+import { gltf_read_accessor } from "../../../../format/scene/gltf/gltf_read_accessor.js";
+import { gltf_texture_image_index, gltf_used_image_indices } from "../../../../format/scene/gltf/gltf_used_image_indices.js";
+import { TinyGltf } from "./tiny-gltf.js";
+
+
+/**
+ * Somewhere to hand `canonicalize_quaternion_signs` a rest rotation it can read by component name —
+ * a `Transform64` addresses its rotation by index, and the function's contract is named components.
+ *
+ * @type {Quaternion}
+ */
+const SCRATCH_REST_ROTATION = new Quaternion();
+
+/**
+ * Somewhere to read a light's facing before flipping it.
+ *
+ * @type {Vector3}
+ */
+const SCRATCH_DIRECTION = new Vector3();
+const OPTIMIZE_GEOMETRIES = false;
+
+/**
+ * @see https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html
+ * @param {string} id
+ */
+function gltf_attribute_id_to_standard(id) {
+    switch (id) {
+        case "POSITION":
+            return StandardAttributes.Position;
+        case "NORMAL":
+            return StandardAttributes.Normal;
+        case "TEXCOORD_0":
+            return StandardAttributes.TextureCoordinates0;
+        case "TEXCOORD_1":
+            return StandardAttributes.TextureCoordinates1;
+        case "TANGENT":
+            return StandardAttributes.Tangent;
+        case "COLOR_0":
+            return StandardAttributes.Color;
+        case "JOINTS_0":
+            return StandardAttributes.SkinningJoints;
+        case "WEIGHTS_0":
+            return StandardAttributes.SkinningWeights;
+        default:
+            return id;
+    }
+}
+
+/**
+ * Map glTF `animation.channels[].target.path` to {@link Node3DProperty}.
+ * Returns `-1` for paths we don't yet drive (morph-target `weights`),
+ * so the caller can skip those channels without throwing.
+ *
+ * @param {string} path
+ * @returns {number}
+ */
+function gltf_animation_path_to_property(path) {
+    switch (path) {
+        case "translation":
+            return Node3DProperty.Translation;
+        case "rotation":
+            return Node3DProperty.Rotation;
+        case "scale":
+            return Node3DProperty.Scale;
+        default:
+            // "weights" (morph targets) lands here; we don't yet have
+            // morph-target support in the renderer.
+            return -1;
+    }
+}
+
+/**
+ * Number of scalar components per keyframe value for a given Node3D
+ * property — translation/scale = 3 (vec3), rotation = 4 (quaternion
+ * x/y/z/w).
+ *
+ * @param {number} property one of {@link Node3DProperty}
+ * @returns {number}
+ */
+function node3d_property_component_count(property) {
+    switch (property) {
+        case Node3DProperty.Translation:
+        case Node3DProperty.Scale:
+            return 3;
+        case Node3DProperty.Rotation:
+            return 4;
+        default:
+            throw new Error(`Unsupported animated property ${property}`);
+    }
+}
+
+/**
+ * Walk a flat keyframe-values buffer for a rotation channel and flip
+ * the sign of any keyframe whose val-quaternion has negative dot
+ * product with the previous keyframe's val-quaternion. The same flip
+ * is applied to that keyframe's in/out tangents in CUBICSPLINE mode
+ * so the cubic remains internally consistent.
+ *
+ * The flip preserves the rotation (q and -q encode the same
+ * orientation) while ensuring per-component interpolation between
+ * consecutive keyframes follows the short arc instead of passing
+ * through a near-zero quaternion mid-segment.
+ *
+ * The curve's leading sign is anchored against `rest_rotation` —
+ * the target node's authored local rest rotation: when the first
+ * keyframe's val-quat has negative dot product with the rest
+ * quaternion, the whole first keyframe block is negated (and the
+ * consecutive-keyframe pass propagates that sign down the curve).
+ * Every rotation curve targeting one node aligns against the same
+ * reference, so weighted multi-clip blends accumulate
+ * hemisphere-consistent contributions instead of cancelling toward
+ * a near-zero quaternion. Residual limitation: the anchor is the
+ * FIRST keyframe only — a curve that swings more than 90° away
+ * from the rest rotation mid-clip can still contribute opposite
+ * signs to another clip at those times; fixing that would need
+ * apply-time alignment, which the atomic pose accumulator cannot
+ * do order-independently.
+ *
+ * Mutates `values` in place. Safe to call on an output array that's
+ * a fresh copy of the source accessor (which is what
+ * {@link read_accessor_as_float32_array} produces).
+ *
+ * Exported for spec coverage; not part of the loader's public API.
+ *
+ * @param {Float32Array} values flat values: STEP/LINEAR uses 4
+ *     floats/keyframe (x, y, z, w); CUBICSPLINE uses 12 (inX, inY,
+ *     inZ, inW, valX, valY, valZ, valW, outX, outY, outZ, outW).
+ * @param {number} key_count
+ * @param {number} interpolation one of {@link AnimationInterpolationKind}
+ * @param {{x:number, y:number, z:number, w:number}} [rest_rotation]
+ *     target node's authored local rest rotation; omitted → the
+ *     leading sign is kept as authored.
+ */
+export function canonicalize_quaternion_signs(values, key_count, interpolation, rest_rotation) {
+    const is_cubic = interpolation === AnimationInterpolationKind.CubicTangents;
+    const stride = is_cubic ? 12 : 4;
+    // Offset into a keyframe block at which the val-quat sits.
+    // CUBICSPLINE has [in, val, out]; the val starts at offset 4 (i.e.
+    // after the 4-float in-tangent). STEP/LINEAR has just val at 0.
+    const val_offset = is_cubic ? 4 : 0;
+
+    if (key_count >= 1 && rest_rotation !== undefined) {
+        const rest_dot =
+            values[val_offset + 0] * rest_rotation.x +
+            values[val_offset + 1] * rest_rotation.y +
+            values[val_offset + 2] * rest_rotation.z +
+            values[val_offset + 3] * rest_rotation.w;
+
+        if (rest_dot < 0) {
+            // Negate the whole first keyframe block (value +
+            // tangents); the loop below carries the flip through
+            // the remaining keyframes.
+            for (let i = 0; i < stride; i++) {
+                values[i] = -values[i];
+            }
+        }
+    }
+
+    for (let k = 1; k < key_count; k++) {
+        const prev_base = (k - 1) * stride + val_offset;
+        const cur_base = k * stride + val_offset;
+
+        const dot =
+            values[prev_base + 0] * values[cur_base + 0] +
+            values[prev_base + 1] * values[cur_base + 1] +
+            values[prev_base + 2] * values[cur_base + 2] +
+            values[prev_base + 3] * values[cur_base + 3];
+
+        if (dot < 0) {
+            // Flip the whole keyframe block (value + tangents).
+            const start = k * stride;
+            const end = start + stride;
+            for (let i = start; i < end; i++) {
+                values[i] = -values[i];
+            }
+        }
+    }
+}
+
+/**
+ * Map glTF interpolation strings to the engine's enum. Defaults to
+ * LINEAR when missing — the glTF spec's default.
+ *
+ * @param {string|undefined} interpolation
+ * @returns {number} one of {@link AnimationInterpolationKind}
+ */
+function gltf_interpolation_to_kind(interpolation) {
+    switch (interpolation) {
+        case "STEP":
+            return AnimationInterpolationKind.Discrete;
+        case "CUBICSPLINE":
+            return AnimationInterpolationKind.CubicTangents;
+        case "LINEAR":
+        case undefined:
+            return AnimationInterpolationKind.Linear;
+        default:
+            throw new Error(`Unsupported interpolation '${interpolation}'`);
+    }
+}
+
+/**
+ * Input can be a .glb or .gltf file.
+ *
+ * Does not support most compression GLTF extensions such as draco, basis etc.
+ *
+ * Returns a {@link SceneBundle} that groups the parsed scene roots
+ * with any skins and animation clips extracted from the same asset.
+ * Callers add `bundle.scenes` to their scene, then pass the bundle's
+ * `skins` / `clips` to the scene's animation manager (e.g. via
+ * {@link GPUAnimationManager#register_skin} and
+ * {@link GPUAnimationManager#register_clip}) once `scene.build` has
+ * populated `id_mapping` for the joint and target nodes.
+ *
+ * @param {string} url un-resolved — the asset manager resolves network paths
+ * @param {Object} options
+ * @param {AssetManager} options.assetManager where the container, its buffers and its images come
+ *   from. Required: a glTF is several files, and which of them are already in memory is not this
+ *   parser's business to know.
+ * @param {AssetRequestScope} [options.scope] the load these requests belong to
+ * @param {Map<string, File|Blob|ArrayBuffer>} [options.fileMap] Map of relative paths to file data.
+ *   When provided, buffer and image URIs in the GLTF are resolved from this map before the asset
+ *   framework is asked. Enables multi-file GLTF loading from drag-and-drop.
+ * @param {Set<GPUTextureFormat>} [options.texture_support] what the device can sample, from
+ *   `gpu_texture_compression_support(device)`. Only a `KHR_texture_basisu` image reads it, to choose
+ *   what to transcode into; omitted, the loader targets the best format the transcoder writes.
+ * @return {Promise<SceneBundle>}
+ */
+export function load_gltf(url, { assetManager, scope, fileMap, texture_support } = {}) {
+    // TODO
+    //  apply some checks to the model, things like non-uniform scales, that can be fixed potentially
+    //  see https://www.youtube.com/watch?v=FJRO5wFTEc8 for common ideas
+    //  check for inverted normals
+    //  check for duplicated vertices
+    //  check for overlapping faces
+
+    async function process(gltf) {
+        // console.log(gltf);
+
+        /**
+         * @type {{type:string, componentType:number, count:number, bufferView:number, byteOffset:number, normalized:boolean, min?:number[], max?:number}[]}
+         */
+        const accessors = gltf.accessors;
+
+        /**
+         * `aabb` is six numbers, `[x0, y0, z0, x1, y1, z1]`, in world space — and is absent on a node
+         * that bounds nothing, meaning neither it nor anything below it declared any.
+         *
+         * {{aabb?:Float64Array, mesh:number, worldMatrix:Float32Array}[]}
+         */
+        const nodes = gltf.nodes;
+
+        /**
+         *
+         * @type {{aabb:Float64Array, primitives:({attributes:Object<number>,indices:number, material:number, mode:number}[])}[]}
+         */
+        const meshes = gltf.meshes;
+
+        /**
+         *
+         * @type {{}[]}
+         */
+        const scenes = gltf.scenes;
+
+        /**
+         * Engine Node3Ds indexed by glTF node index — populated lazily
+         * by {@link process_node} as the scene-graph recursion visits
+         * each node. Used afterwards to resolve skin joint references
+         * and animation channel targets (both of which point at glTF
+         * node indices, not at any in-memory object).
+         *
+         * @type {Node3D[]}
+         */
+        const node3d_by_index = new Array((gltf.nodes ?? []).length);
+
+        /**
+         * Queue of pending `skin.meshes` pushes. process_node() can't
+         * resolve `node.skin → Skin` directly because skins[] is built
+         * *after* the recursion completes (the joint lookup needs
+         * node3d_by_index fully populated). So we enqueue the produced
+         * SkinnedMeshes here and drain into the matching skin once the
+         * walk finishes.
+         *
+         * @type {{ skin_index: number, meshes: Mesh[] }[]}
+         */
+        const skin_mesh_pushes = [];
+
+        /**
+         * Primitive converted to JSON string serves as key
+         * @type {Map<string, MeshletGeometry>}
+         */
+        const geometry_cache = new Map();
+
+        /**
+         *
+         * @type {HashSet<MeshletGeometry>}
+         */
+        const geometry_cache_secondary = new HashSet();
+
+        /**
+         * Indexed as `gltf.images` is, and populated only where an image was actually fetched.
+         *
+         * Built from {@link gltf_used_image_indices} rather than by mapping the whole list, because
+         * that is the same function the fetch is filtered by: the two cannot drift into decoding one
+         * set and sampling another, and there is no slot here for an image that was never brought in.
+         *
+         * @type {ShadeImage[]}
+         */
+        const mapped_images = [];
+
+        for (const index of gltf_used_image_indices(gltf)) {
+            const source = gltf.images[index];
+
+            /*
+             A `KHR_texture_basisu` image arrives already transcoded — the container reader ran in
+             the parser, where the bytes were, and what came back is texels in a device format. Every
+             other image is an `ImageBitmap` the browser decoded. Below this line the two are the same
+             thing: a `ShadeImage`, which is what §3.1 bought.
+            */
+            mapped_images[index] = source.isShadeTexelData === true
+                ? ShadeImage.fromTexelData(source)
+                : ShadeImage.fromImageBitmap(source);
+        }
+
+        /**
+         * used when no material is specified
+         * @type {StandardShadeMaterial}
+         */
+        const default_material = new StandardShadeMaterial();
+
+        /**
+         *
+         * @type {ShadeTexture[]}
+         */
+        const mapped_textures = (gltf.textures ?? []).map(gltf_texture => gltf_create_texture(
+            gltf_texture,
+            /*
+             The same function the fetch was filtered by. Asking it twice is the point: this is the
+             half that decides what to *sample*, and the half in `gltf_used_image_indices` decides
+             what to *fetch*. When those two disagreed, every model in the game's level failed to
+             load — see the note at the top of that file.
+            */
+            mapped_images[gltf_texture_image_index(gltf_texture)],
+            gltf.samplers
+        ));
+
+        coalesce_array_duplicates(mapped_textures);
+
+        // account for materials missing
+        const gltf_materials = gltf.materials ?? [];
+
+        const mapped_materials = gltf_materials.map(gltf_mat => gltf_create_material(gltf_mat, mapped_textures));
+
+        // dedupe materials
+        coalesce_array_duplicates(mapped_materials);
+
+
+        /**
+         * One accessor as an attribute in the shape the renderer stores it.
+         *
+         * The read itself — stride, sparse overlay, a view-less accessor's zeroes — belongs to the
+         * format and is done by {@link gltf_read_accessor}; what is left here is the engine's own
+         * question of which storage type an attribute of this name is kept in.
+         *
+         * @param {number} accessor_index
+         * @param {string} name
+         * @returns {Attribute}
+         */
+        function buffer_to_attribute(accessor_index, name) {
+            const data = gltf_read_accessor(gltf, accessor_index);
+
+            const raw_attribute = Attribute.from(data.values, data.components, name);
+
+            raw_attribute.spec.normalized = data.normalized;
+
+            return normalize_attribute(raw_attribute);
+        }
+
+        /**
+         *
+         * @type {HashMap<Object, Attribute>}
+         */
+        const attribute_cache = new HashMap({
+            keyEqualityFunction: objectDeepEquals,
+            keyHashFunction: computeObjectHash
+        });
+
+        /**
+         *
+         * @param {number} attribute_accessor
+         * @param {string} name
+         * @returns {Attribute}
+         */
+        function obtain_attribute(attribute_accessor, name) {
+            const key = {
+                attribute_accessor, name
+            };
+
+            let attribute = attribute_cache.get(key);
+
+            if (attribute === undefined) {
+                attribute = buffer_to_attribute(attribute_accessor, name);
+                attribute_cache.set(key, attribute);
+            } else {
+                // console.warn('attribute reuse')
+            }
+
+            return attribute;
+        }
+
+        /**
+         * A FLOAT-componentType accessor's values as a flat `Float32Array`. Used for animation
+         * sampler inputs/outputs (times, values) and the skin inverse-bind matrices, where
+         * downstream code wants a stride-free flat buffer.
+         *
+         * @param {number} accessor_index
+         * @returns {Float32Array}
+         */
+        function read_accessor_as_float32_array(accessor_index) {
+            const accessor = accessors[accessor_index];
+
+            assert.equal(
+                accessor.componentType, GLTF_COMPONENT_TYPE.FLOAT,
+                `accessor[${accessor_index}].componentType must be FLOAT for read_accessor_as_float32_array`
+            );
+
+            return gltf_read_accessor(gltf, accessor_index).values;
+        }
+
+        /**
+         *
+         * @returns {MeshletGeometry}
+         */
+        function primitive_to_geometry(primitive) {
+            const geometry = new Geometry();
+
+            const mode = primitive.mode ?? GLTF_PRIMITIVE_MODE_DEFAULT;
+
+            if (mode !== GLTF_PRIMITIVE_MODE.TRIANGLES) {
+                throw new Error('Unsupported draw method');
+            }
+
+            for (const attribute_key in primitive.attributes) {
+
+                const name = gltf_attribute_id_to_standard(attribute_key);
+
+                if (geometry.getAttribute(name) !== undefined) {
+                    console.warn(`attribute '${name}' already exists, skipping. Primitive.attributes = ${JSON.stringify(primitive.attributes)}`)
+                }
+
+                /**
+                 * @type {number}
+                 */
+                const attribute_accessor = primitive.attributes[attribute_key];
+
+                let attribute;
+                try {
+                    attribute = obtain_attribute(attribute_accessor, name);
+                } catch (e) {
+                    console.warn(`Failed to parse attribute '${name}'. Skipping`, e);
+                    continue;
+                }
+
+                geometry.addAttribute(attribute);
+
+
+                if (attribute_key === "POSITION") {
+                    // The spec mandates POSITION accessors carry min/max,
+                    // so we can adopt them as the bounding box without
+                    // walking the vertex data. The sphere is derived from
+                    // the box inside meshlet_geometry_build_from_geometry,
+                    // so we just clear the dirty flag here.
+                    const accessor = accessors[attribute_accessor];
+
+                    if (accessor.min !== undefined && accessor.max !== undefined) {
+                        geometry.bounding_box.set([
+                            ...accessor.min,
+                            ...accessor.max
+                        ]);
+
+                        geometry.clearFlag(GeometryFlags.BoundsNeedUpdate);
+                    }
+                }
+            }
+
+            if (primitive.indices !== undefined) {
+
+                geometry.index = obtain_attribute(primitive.indices, 'index');
+
+                // geometry_fix_index(geometry.index, geometry.getVertexCount());
+            }
+
+
+            // vertex optimize
+            if (geometry.index !== null && OPTIMIZE_GEOMETRIES) {
+                meshopt_optimizeVertexCache(geometry.index.data, geometry.index.data, geometry.index.count, geometry.getVertexCount());
+            }
+
+            return meshlet_geometry_build_from_geometry(geometry);
+        }
+
+        function obtain_geometry_by_primitive(primitive) {
+            const key = JSON.stringify(primitive);
+
+            let geometry = geometry_cache.get(key);
+
+            if (geometry === undefined) {
+                geometry = primitive_to_geometry(primitive)
+
+                const secondary_cached = geometry_cache_secondary.get(geometry);
+
+                if (secondary_cached !== undefined) {
+                    // found an equivalent geometry in the secondary cache, use it instead
+                    geometry = secondary_cached;
+                    // console.warn("secondary reuse");
+                } else {
+                    geometry_cache_secondary.add(geometry);
+                }
+
+                geometry_cache.set(key, geometry);
+            } else {
+                // console.warn('geometry reuse');
+            }
+
+            return geometry;
+        }
+
+
+        /**
+         * Build the renderable mesh(es) for one glTF node.
+         *
+         * A glTF mesh is a list of primitives sharing a name and an
+         * `aabb`, and each primitive becomes one engine-side {@link Mesh}.
+         * When the owning glTF node references a skin, every primitive is
+         * instead constructed as a {@link SkinnedMesh} so the renderer
+         * routes it through a per-instance geometry clone for deformation.
+         *
+         * @param {number} mesh_index
+         * @param {{}} node
+         * @param {boolean} is_skinned
+         * @returns {Mesh[]}
+         */
+        function process_mesh(mesh_index, node, is_skinned) {
+
+            const mesh = meshes[mesh_index];
+
+            const primitives = mesh.primitives;
+
+            const primitive_count = primitives.length;
+
+            /**
+             *
+             * @type {Mesh[]}
+             */
+            const result = [];
+
+            for (let i = 0; i < primitive_count; i++) {
+                const primitive = primitives[i];
+
+                // build geometry
+
+                /**
+                 * @type {MeshletGeometry}
+                 */
+                let geometry;
+
+                try {
+                    geometry = obtain_geometry_by_primitive(primitive);
+                } catch (e) {
+                    console.error(`Failed to obtain geometry for primitive [${i}] ${primitive}. `, e);
+                    console.log('Ignoring mesh');
+                    continue;
+                }
+
+                if (primitive_count === 1 && mesh.name !== undefined) {
+                    geometry.name = mesh.name;
+                }
+
+                const material_id = primitive.material;
+
+                let material;
+
+                if (material_id !== undefined) {
+                    material = mapped_materials[material_id];
+
+                    if (material === undefined) {
+                        console.warn(`specified material ${material_id} does not exist. Using default.`);
+
+                        material = default_material;
+                    }
+
+                } else {
+                    // no material specified, use default
+                    material = default_material;
+                }
+
+                const engine_mesh = is_skinned ? new SkinnedMesh() : new Mesh();
+                engine_mesh.geometry = geometry;
+                engine_mesh.material = material;
+                engine_mesh.transform_global.fromMatrix(node.worldMatrix);
+
+
+                if (mesh.name !== undefined) {
+                    engine_mesh.name = mesh.name;
+                }
+
+                result.push(engine_mesh);
+            }
+
+            return result;
+        }
+
+        /**
+         *
+         * @param {number} light_index
+         * @param {{}} node
+         * @returns {AbstractLight}
+         */
+        function process_light(light_index, node) {
+
+            // SPEC: https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_lights_punctual/README.md
+
+            const gltf_light = gltf.extensions.KHR_lights_punctual.lights[light_index];
+
+            // parse color
+            const color = new Color();
+
+            if (gltf_light.color !== undefined) {
+                color.fromArray(gltf_light.color);
+            } else {
+                color.setRGB(1, 1, 1);
+            }
+
+            const intensity = gltf_light.intensity ?? 1;
+
+            const name = gltf_light.name ?? "";
+
+            let light;
+
+            const type = gltf_light.type;
+
+            switch (type) {
+                case "directional":
+                    light = new DirectionalLight();
+                    break;
+                case "point":
+                    light = new PointLight();
+                    light.distance = gltf_light.range ?? 1e20; // default light radius
+                    break;
+                case "spot":
+                    light = new SpotLight();
+
+                    const gltf_spot = gltf_light.spot;
+
+                    const outerCone = gltf_spot?.outerConeAngle ?? (Math.PI / 4); // default PI/4
+                    const innerCone = gltf_spot?.innerConeAngle ?? 0;
+
+                    light.angle = clamp(
+                        outerCone,
+                        0,
+                        Math.PI / 2
+                    );
+
+                    light.penumbra = clamp01(
+                        inverseLerp(light.angle, 0, innerCone)
+                    );
+
+                    light.distance = gltf_light.range ?? 1e20;
+                    // TODO rotation is messed up?
+                    break;
+                default:
+                    throw new Error(`Unsupported light type ${type}`);
+            }
+
+            light.color.copy(color);
+            light.intensity = intensity;
+            light.name = name;
+
+            // check for light radius
+            light.radius = gltf_light.extras?.radius ?? 0;
+
+            light.near_clip_distance = gltf_light.extras?.near_clip_distance ?? light.radius;
+
+            light.casts_shadow = true;
+
+            return light;
+        }
+
+        /**
+         *
+         * @param {Node3D} parent
+         * @param {number} node_index
+         */
+        function process_node(parent, node_index) {
+
+            const node = nodes[node_index];
+
+            // glTF "skin" attaches at the node, not the mesh: every
+            // primitive of the referenced mesh becomes a SkinnedMesh
+            // bound to this skin. Resolved later (after the recursion
+            // is done) against `skins[]`, which we've already built
+            // — the joint Node3Ds may be visited *after* this node,
+            // so we just record the produced SkinnedMeshes here and
+            // push them into `skin.meshes` once the walk finishes.
+            const skin_index = typeof node.skin === "number" ? node.skin : -1;
+
+            let node3d;
+            let produced_skinned_meshes = null;
+
+            if (node.extensions !== undefined && node.extensions.KHR_lights_punctual !== undefined) {
+                const light_index = node.extensions.KHR_lights_punctual.light;
+
+                try {
+                    node3d = process_light(light_index, node);
+                } catch (e) {
+                    console.error("Failed to process light ", light_index, " ", e);
+                }
+            }
+
+
+            if (typeof node.mesh === "number") {
+                const meshes = process_mesh(node.mesh, node, skin_index !== -1);
+
+                if (meshes.length === 1) {
+                    node3d = meshes[0];
+                } else if (meshes.length > 1) {
+                    node3d = new Node3D();
+
+                    node3d.addChildren(meshes)
+                }
+
+                if (skin_index !== -1) {
+                    produced_skinned_meshes = meshes;
+                }
+            }
+
+            if (node3d === undefined) {
+                node3d = new Node3D();
+            }
+
+            // Stash by glTF index — joint refs and animation channel
+            // targets resolve through this lookup once the recursion
+            // unwinds.
+            node3d_by_index[node_index] = node3d;
+
+            if (node.name !== undefined) {
+                node3d.name = node.name;
+            }
+
+            if (node.matrix !== undefined) {
+
+                node3d.transform_local.fromMatrix(node.matrix);
+
+            } else {
+
+                const t = node3d.transform_local;
+
+                if (node.translation !== undefined) {
+                    const v = node.translation;
+
+                    t.setTranslation(v[0], v[1], v[2]);
+                }
+
+                if (node.rotation !== undefined) {
+                    const q = node.rotation;
+
+                    t.setRotation(q[0], q[1], q[2], q[3]);
+                }
+
+                if (node.scale !== undefined) {
+                    const v = node.scale;
+
+                    t.setScale(v[0], v[1], v[2]);
+                }
+            }
+
+
+            if (node3d.isDirectionalLight || node3d.isSpotLight) {
+                // glTF lights shine along their local -Z; engine convention is forward = shining direction
+                const t = node3d.transform_local;
+
+                // the direction is read off the matrix, and a Transform64 does not maintain its own
+                t.updateMatrix();
+
+                t64_transform_direction(SCRATCH_DIRECTION, t, 0, 0, 1);
+
+                t64_look_rotation(
+                    t,
+                    -SCRATCH_DIRECTION.x, -SCRATCH_DIRECTION.y, -SCRATCH_DIRECTION.z,
+                    0, 1, 0
+                );
+            }
+
+            parent.addChild(node3d);
+
+            if (produced_skinned_meshes !== null) {
+                // Defer the `skin.meshes` push to after `skins[]` is
+                // built — we collect into a queue here and process it
+                // at the end of process().
+                skin_mesh_pushes.push({
+                    skin_index,
+                    meshes: produced_skinned_meshes,
+                });
+            }
+
+
+            if (node.children !== undefined) {
+
+                for (let i = 0; i < node.children.length; i++) {
+                    const node_index = node.children[i];
+
+                    process_node(node3d, node_index);
+                }
+            }
+        }
+
+        // console.time('parse-gltf');
+        // console.profile('parse-gltf');
+
+        /**
+         *
+         * @type {Node3D[]}
+         */
+        const scene_nodes3d = [];
+
+        for (let i = 0; i < scenes.length; i++) {
+            const scene = scenes[i];
+
+            const scene_node3d = new Node3D();
+
+            scene_nodes3d.push(scene_node3d);
+
+            /**
+             * @type {number[]}
+             */
+            const scene_nodes = scene.nodes;
+
+            const node_count = scene_nodes.length;
+
+            for (let i = 0; i < node_count; i++) {
+                const node_index = scene_nodes[i];
+                process_node(scene_node3d, node_index);
+            }
+
+            scene_node3d.updateMatrices();
+        }
+
+        // ── Skins ──────────────────────────────────────────────────
+        //
+        // Build {@link Skin} objects from `gltf.skins[]`. Joints
+        // resolve to Node3D refs through `node3d_by_index` (fully
+        // populated by the recursion above). Inverse-bind matrices
+        // come from a single MAT4 accessor — `joint_count * 16` f32s
+        // laid out column-major, copied into a flat Float32Array that
+        // the manager can subarray-view at registration time.
+        const skins = (gltf.skins ?? []).map((gltf_skin, skin_index) => {
+            const joint_indices = gltf_skin.joints;
+            const joint_count = joint_indices.length;
+
+            const joint_nodes = new Array(joint_count);
+            for (let i = 0; i < joint_count; i++) {
+                const joint_node_index = joint_indices[i];
+                const joint_node = node3d_by_index[joint_node_index];
+
+                assert.defined(
+                    joint_node,
+                    `skin[${skin_index}].joints[${i}] references unknown node index ${joint_node_index}`
+                );
+
+                joint_nodes[i] = joint_node;
+            }
+
+            // Inverse-bind matrices: glTF stores them MAT4-typed
+            // (column-major, 16 f32s per joint). When the accessor is
+            // omitted, the spec says every joint's IBM is identity —
+            // we materialise that here so the manager always sees a
+            // ready-to-use flat array.
+            let inverse_bind_matrices;
+            if (gltf_skin.inverseBindMatrices !== undefined) {
+                inverse_bind_matrices = read_accessor_as_float32_array(gltf_skin.inverseBindMatrices);
+            } else {
+                inverse_bind_matrices = new Float32Array(joint_count * 16);
+                for (let i = 0; i < joint_count; i++) {
+                    inverse_bind_matrices[i * 16 + 0] = 1;
+                    inverse_bind_matrices[i * 16 + 5] = 1;
+                    inverse_bind_matrices[i * 16 + 10] = 1;
+                    inverse_bind_matrices[i * 16 + 15] = 1;
+                }
+            }
+
+            return Skin.from({
+                name: gltf_skin.name ?? "",
+                joints: joint_nodes,
+                inverse_bind_matrices,
+                meshes: [],
+            });
+        });
+
+        // Drain the deferred skin.meshes pushes captured during the
+        // node walk.
+        for (let i = 0; i < skin_mesh_pushes.length; i++) {
+            const { skin_index, meshes: skin_meshes } = skin_mesh_pushes[i];
+            skins[skin_index].meshes.push(...skin_meshes);
+        }
+
+        // ── Animation clips ───────────────────────────────────────
+        //
+        // One glTF animation → one {@link ShadeAnimationClip}. Each
+        // channel becomes a {@link ShadeAnimationChannel}; per-component
+        // curves are built from the sampler's input (times) / output
+        // (values) accessors via the engine's curve_from_track_data
+        // helpers, which already handle STEP / LINEAR / CUBICSPLINE.
+        const clips = [];
+        const gltf_animations = gltf.animations ?? [];
+        for (let a = 0; a < gltf_animations.length; a++) {
+            const gltf_animation = gltf_animations[a];
+
+            const channels = [];
+
+            for (let c = 0; c < gltf_animation.channels.length; c++) {
+                const gltf_channel = gltf_animation.channels[c];
+                const target = gltf_channel.target;
+
+                const property = gltf_animation_path_to_property(target.path);
+                if (property === -1) {
+                    // Morph-target weights or other unsupported paths.
+                    continue;
+                }
+
+                if (target.node === undefined) {
+                    // Channels without a node target are a glTF
+                    // extension hook and not actionable here.
+                    continue;
+                }
+
+                const target_node = node3d_by_index[target.node];
+
+                assert.defined(
+                    target_node,
+                    `animations[${a}].channels[${c}].target.node ${target.node} not resolved`
+                );
+
+                const sampler = gltf_animation.samplers[gltf_channel.sampler];
+                const times = read_accessor_as_float32_array(sampler.input);
+                const values = read_accessor_as_float32_array(sampler.output);
+                const interpolation = gltf_interpolation_to_kind(sampler.interpolation);
+                const component_count = node3d_property_component_count(property);
+
+                // Canonicalize quaternion signs on rotation channels.
+                //
+                // glTF stores rotation keyframes as raw (x, y, z, w)
+                // quaternions, but `q` and `-q` represent the same
+                // orientation. Authoring tools (notably Mixamo) often
+                // alternate signs across consecutive keyframes when a
+                // bone passes through 180°. Per-component interpolation
+                // between sign-mismatched keyframes — especially
+                // CUBICSPLINE — passes through near-zero quaternions
+                // mid-segment; the apply shader's `normalize(value)`
+                // call then produces an effectively-identity quaternion
+                // for one frame, which reads as a one-frame snap to
+                // bind pose.
+                //
+                // Fix: flip the sign of every keyframe whose val-quat
+                // has negative dot product with the prior keyframe's
+                // val-quat. For CUBICSPLINE, flip the in/out tangents
+                // alongside the value so the cubic stays consistent.
+                // The leading sign is anchored against the target
+                // node's authored rest rotation so all clips driving
+                // one node land in the same hemisphere — required
+                // for weighted multi-clip blends, where the pose
+                // accumulator sums raw components across clips.
+                // No-op when the property isn't Rotation, or when the
+                // data was already canonicalized at export time.
+                if (property === Node3DProperty.Rotation && times.length >= 1) {
+                    // `canonicalize_quaternion_signs` reads the rest rotation by component name,
+                    // which a `Transform64` does not offer — hand it a quaternion instead
+                    const rest = target_node.transform_local;
+
+                    SCRATCH_REST_ROTATION.set(
+                        rest.rotation_x,
+                        rest.rotation_y,
+                        rest.rotation_z,
+                        rest.rotation_w
+                    );
+
+                    canonicalize_quaternion_signs(
+                        values, times.length, interpolation,
+                        SCRATCH_REST_ROTATION
+                    );
+                }
+
+                // Build the per-axis curves object. component_count
+                // is property-driven (3 for Translation/Scale, 4 for
+                // Rotation); slots beyond what the property uses are
+                // omitted. The keys align with the GPU track's
+                // (x, y, z, w) vec4f output — see ShadeAnimationChannel.
+                const axis_keys = ['x', 'y', 'z', 'w'];
+                const curves = {};
+                for (let comp = 0; comp < component_count; comp++) {
+                    const curve = new AnimationCurve();
+                    curve_from_track_data(curve, interpolation, values, times, component_count, comp);
+                    curves[axis_keys[comp]] = curve;
+                }
+
+                channels.push(ShadeAnimationChannel.from({
+                    target: target_node,
+                    property,
+                    curves,
+                }));
+            }
+
+            if (channels.length === 0) {
+                // All channels were unsupported / unresolved — skip
+                // the clip entirely so we don't emit a zero-channel
+                // record the manager would reject.
+                continue;
+            }
+
+            const clip = ShadeAnimationClip.from({
+                name: gltf_animation.name ?? "",
+                channels,
+            });
+
+            // Default optimization pass: strip channels that
+            // evaluate to the identity transform and individual
+            // per-axis curves that are constant at identity, then
+            // key-reduce the survivors. glTF exporters often emit
+            // redundant bind-pose channels (every joint gets a
+            // translation channel even when only rotation is
+            // animated), so this typically trims a sizeable
+            // fraction of the channel + curve count. Behaviour
+            // unchanged — applying the optimised clip produces
+            // the same poses.
+            //
+            // Stats are computed by diffing channel + total-curve
+            // counts before and after; the methods don't carry
+            // them in their return values.
+            const before_channels = clip.channels.length;
+            let before_curves = 0;
+            for (let i = 0; i < clip.channels.length; i++) {
+                before_curves += clip.channels[i].curve_count;
+            }
+
+            clip.optimize();
+
+            const after_channels = clip.channels.length;
+            let after_curves = 0;
+            for (let i = 0; i < clip.channels.length; i++) {
+                after_curves += clip.channels[i].curve_count;
+            }
+
+            const removed_channels = before_channels - after_channels;
+            const removed_curves = before_curves - after_curves;
+            if (removed_channels > 0 || removed_curves > 0) {
+                // console.log(
+                //     `[load_gltf] optimised clip '${clip.name}': ` +
+                //     `removed ${removed_channels} track(s), ` +
+                //     `${removed_curves} curve(s)`
+                // );
+            }
+
+            clips.push(clip);
+        }
+
+        // console.profileEnd('parse-gltf');
+        // console.timeEnd('parse-gltf');
+
+        const bundle = new SceneBundle();
+        bundle.scenes = scene_nodes3d;
+        bundle.skins = skins;
+        bundle.clips = clips;
+        return bundle;
+    }
+
+    /**
+     *
+     * @param {Node3D[]} scenes
+     */
+    function fix_scene_material_sidedness(scenes) {
+        const meshes = new Set();
+
+        for (const s of scenes) {
+            s.traverse(node => {
+                if (node.isMesh) {
+                    meshes.add(node);
+                }
+            });
+        }
+
+        const { geometries_modified: fixed_count, primitives_delta } = fix_up_material_sides(Array.from(meshes));
+
+        if (fixed_count > 0) {
+            console.warn(`Fixed ${fixed_count} geometries in accordance with material sidedness. Primitives added: ${number_format_by_thousands(primitives_delta)}`);
+        }
+
+        return scenes;
+    }
+
+
+    return load_gltf_document(url, { assetManager, scope, fileMap, texture_support })
+        .then(process)
+        // .then(fix_scene_material_sidedness)
+        // .then(prepare_lightmap)
+        ;
+}
+
+/**
+ * The same file, parsed and with its dependencies in memory, **without** being turned into anything
+ * a renderer draws: the glTF's own JSON alongside `buffers` as `Uint8Array`s and `images` as
+ * `ImageBitmap`s — or, for a `KHR_texture_basisu` image, as a `ShadeTexelData` already in a device
+ * format, because no browser decodes a KTX2 container into a bitmap.
+ *
+ * The half of {@link load_gltf} that is not about pictures. A glTF carries more than a scene to draw
+ * — collision hulls, navigation surfaces, spawn markers, whatever a tool reads accessors for — and
+ * those consumers want the accessors and the bytes behind them, not a {@link SceneBundle} they would
+ * have to take apart again.
+ *
+ * @param {string} url un-resolved — the asset manager resolves network paths
+ * @param {Object} options
+ * @param {AssetManager} options.assetManager
+ * @param {AssetRequestScope} [options.scope]
+ * @param {Map<string, File|Blob|ArrayBuffer>} [options.fileMap]
+ * @param {Set<GPUTextureFormat>} [options.texture_support] see {@link load_gltf}
+ * @returns {Promise<TinyGltf>}
+ */
+export function load_gltf_document(url, { assetManager, scope, fileMap, texture_support } = {}) {
+    const gltf = new TinyGltf(assetManager, scope, texture_support);
+
+    if (fileMap) {
+        gltf.fileMap = fileMap;
+    }
+
+    return gltf.loadFromUrl(url);
+}
+
+