@inweb/viewer-three 27.4.7 → 27.6.0

package/src/Viewer/helpers/WCSHelper.ts

@@ -1,3 +1,26 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2002-2026, Open Design Alliance (the "Alliance").
+// All rights reserved.
+//
+// This software and its documentation and related materials are owned by
+// the Alliance. The software may only be incorporated into application
+// programs owned by members of the Alliance, subject to a signed
+// Membership Agreement and Supplemental Software License Agreement with the
+// Alliance. The structure and organization of this software are the valuable
+// trade secrets of the Alliance and its suppliers. The software is also
+// protected by copyright law and international treaty provisions. Application
+// programs incorporating this software must include the following statement
+// with their copyright notices:
+//
+//   This application incorporates Open Design Alliance software pursuant to a
+//   license agreement with Open Design Alliance.
+//   Open Design Alliance Copyright (C) 2002-2026 by Open Design Alliance.
+//   All rights reserved.
+//
+// By use of this software, its documentation or related materials, you
+// acknowledge and accept the above terms.
+///////////////////////////////////////////////////////////////////////////////
+
 import {
   Camera,
   CylinderGeometry,
@@ -22,6 +45,7 @@ export class WCSHelper extends Object3D {
   constructor(camera: Camera) {
     super();
 
+    (this as any).type = "WCSHelper";
     this.camera = camera;
     this.size = 160;
 
@@ -89,11 +113,13 @@ export class WCSHelper extends Object3D {
     canvas.height = 64;
 
     const context = canvas.getContext("2d");
-    context.clearRect(0, 0, 64, 64);
-    context.font = "24px Arial";
-    context.textAlign = "center";
-    context.fillStyle = color.getStyle();
-    context.fillText(text, 32, 41);
+    if (context) {
+      context.clearRect(0, 0, 64, 64);
+      context.font = "24px Arial";
+      context.textAlign = "center";
+      context.fillStyle = color.getStyle();
+      context.fillText(text, 32, 41);
+    }
 
     const texture = new CanvasTexture(canvas);
     texture.colorSpace = SRGBColorSpace;

package/src/Viewer/loaders/DynamicGltfLoader/DynamicGltfLoader.js

@@ -30,6 +30,8 @@ import {
 import { GL_CONSTANTS } from "./GltfStructure.js";
 import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
 
+const DRACO_EXTENSION_NAME = "KHR_draco_mesh_compression";
+
 const STRUCTURE_ID_SEPARATOR = ":";
 
 //#AI-GENERATED using Gemini 2.5 Pro, Claude-4-sonnet
@@ -138,6 +140,278 @@ export class DynamicGltfLoader {
     this.transformData = null;
     this.identityTransformData = null;
     this.visibilityMaterials = new Set(); // Keep track of materials to update uniforms
+
+    // KHR_draco_mesh_compression support — DRACOLoader is injected from
+    // the outside via setDracoLoader() so this module doesn't carry a hard
+    // dependency on three/examples/jsm/loaders/DRACOLoader.js (which has no
+    // CommonJS build and is awkward to consume in non-ESM environments).
+    this._dracoLoader = null;
+  }
+
+  // Inject an externally-configured DRACOLoader instance. The caller is
+  // responsible for setting the decoder path / decoder config / worker pool
+  // size before passing it in. Pass `null` to detach.
+  //
+  // Usage:
+  //   import { DRACOLoader } from "three/examples/jsm/loaders/DRACOLoader.js";
+  //   const draco = new DRACOLoader();
+  //   draco.setDecoderPath("https://www.gstatic.com/draco/v1/decoders/");
+  //   loader.setDracoLoader(draco);
+  setDracoLoader(loader = null) {
+    this._dracoLoader = loader || null;
+  }
+
+  // Decode a Draco-compressed primitive into a BufferGeometry. The caller
+  // (loadNode) guarantees this._dracoLoader is set — see the early check at
+  // the top of loadNode().
+  //
+  // Important detail: DRACOLoader.decodeGeometry() uses the *keys* of
+  // taskConfig.attributeIDs verbatim as attribute names on the resulting
+  // BufferGeometry. So if we pass dracoExt.attributes directly (POSITION,
+  // NORMAL, TEXCOORD_0…) the geometry ends up with those uppercase names
+  // and downstream code that expects three.js conventions (position,
+  // normal, uv) breaks. We pre-translate the keys here.
+  async _decodeDracoPrimitive(structure, primitive, dracoBufferData) {
+    const dracoExt = primitive.extensions[DRACO_EXTENSION_NAME];
+    const loader = this._dracoLoader;
+
+    const attributeIDs = {};
+    const attributeTypes = {};
+    // glTF attribute name → three.js name, used both for re-keying the
+    // DRACOLoader config and for re-mapping bounds afterwards.
+    const gltfNameToThreeName = new Map();
+    // three.js attribute name → glTF accessor index (for normalized flag,
+    // bounds, and post-decode dequantization).
+    const threeNameToAccessor = new Map();
+
+    for (const [gltfAttrName, dracoUniqueId] of Object.entries(dracoExt.attributes)) {
+      const threeName = this._gltfAttributeNameToThreeName(gltfAttrName);
+      attributeIDs[threeName] = dracoUniqueId;
+      gltfNameToThreeName.set(gltfAttrName, threeName);
+
+      const accessorIdx = primitive.attributes[gltfAttrName];
+      if (accessorIdx !== undefined) {
+        const accessor = structure.json.accessors[accessorIdx];
+        attributeTypes[threeName] = this._gltfComponentTypeToTypedArrayName(accessor.componentType);
+        threeNameToAccessor.set(threeName, accessor);
+      }
+    }
+
+    const geometry = await loader.decodeGeometry(dracoBufferData, {
+      attributeIDs,
+      attributeTypes,
+      useUniqueIDs: true,
+    });
+
+    // DRACOLoader doesn't carry the accessor.normalized flag through, so
+    // we apply it manually. This also matters for KHR_mesh_quantization +
+    // Draco combined files (rare, but spec-compliant).
+    for (const [threeName, accessor] of threeNameToAccessor) {
+      const attribute = geometry.getAttribute(threeName);
+      if (!attribute) continue;
+      if (accessor.normalized === true) {
+        attribute.normalized = true;
+      }
+      // Min/max bounds — used by computeBoundingBox/Sphere fast-path.
+      if (accessor.min) attribute.min = accessor.min;
+      if (accessor.max) attribute.max = accessor.max;
+    }
+
+    // Mirror the dequantization done in _createGeometryAttribute() for
+    // ordinary glTF attributes: convert any normalized integer attributes
+    // into a tightly-packed Float32Array so that BufferGeometryUtils
+    // .mergeGeometries() (used by this loader for batched draw calls) sees
+    // a consistent layout across all primitives.
+    for (const [threeName, accessor] of threeNameToAccessor) {
+      const attribute = geometry.getAttribute(threeName);
+      if (!attribute || !attribute.normalized) continue;
+      const denom = this._normalizedDenominator(accessor.componentType);
+      if (denom <= 0) continue;
+      const src = attribute.array;
+      const inv = 1 / denom;
+      const isSigned = accessor.componentType === 5120 || accessor.componentType === 5122;
+      const out = new Float32Array(src.length);
+      for (let i = 0; i < src.length; i++) {
+        let v = src[i] * inv;
+        if (isSigned && v < -1) v = -1;
+        out[i] = v;
+      }
+      const newAttr = new BufferAttribute(out, attribute.itemSize, false);
+      if (accessor.min) newAttr.min = accessor.min;
+      if (accessor.max) newAttr.max = accessor.max;
+      geometry.setAttribute(threeName, newAttr);
+    }
+
+    return geometry;
+  }
+
+  _gltfComponentTypeToTypedArrayName(componentType) {
+    switch (componentType) {
+      case 5120:
+        return "Int8Array";
+      case 5121:
+        return "Uint8Array";
+      case 5122:
+        return "Int16Array";
+      case 5123:
+        return "Uint16Array";
+      case 5125:
+        return "Uint32Array";
+      case 5126:
+        return "Float32Array";
+      default:
+        return "Float32Array";
+    }
+  }
+
+  // glTF normalization denominators (per glTF 2.0 spec, accessor.normalized).
+  _normalizedDenominator(componentType) {
+    switch (componentType) {
+      case 5120:
+        return 127; // BYTE
+      case 5121:
+        return 255; // UBYTE
+      case 5122:
+        return 32767; // SHORT
+      case 5123:
+        return 65535; // USHORT
+      default:
+        return 0; // not normalizable
+    }
+  }
+
+  // Map glTF attribute names to three.js BufferGeometry attribute names.
+  _gltfAttributeNameToThreeName(name) {
+    switch (name) {
+      case "POSITION":
+        return "position";
+      case "NORMAL":
+        return "normal";
+      case "TANGENT":
+        return "tangent";
+      case "TEXCOORD_0":
+        return "uv";
+      case "TEXCOORD_1":
+        return "uv2";
+      case "COLOR_0":
+        return "color";
+      case "JOINTS_0":
+        return "skinIndex";
+      case "WEIGHTS_0":
+        return "skinWeight";
+      default:
+        return name.toLowerCase();
+    }
+  }
+
+  // Build a buffer request for an accessor that correctly accounts for
+  // bufferView.byteStride (interleaved attributes — common in quantized models
+  // produced via KHR_mesh_quantization / gltfpack).
+  _buildAccessorRequest(structure, accessorIndex, type, primIdx) {
+    const accessor = structure.json.accessors[accessorIndex];
+    const bufferView = structure.json.bufferViews[accessor.bufferView];
+    const components = structure.getNumComponents(accessor.type);
+    const componentSize = structure.getComponentSize(accessor.componentType);
+    const itemBytes = components * componentSize;
+    const accessorByteOffset = accessor.byteOffset || 0;
+    const bvByteOffset = bufferView.byteOffset || 0;
+    const byteStride = bufferView.byteStride || 0;
+    const interleaved = byteStride !== 0 && byteStride !== itemBytes;
+
+    const offset = bvByteOffset + accessorByteOffset;
+    let length;
+    if (interleaved) {
+      // For interleaved data the last element begins at (count-1)*stride
+      // and spans itemBytes from there. Fetch only that tight extent.
+      length = (accessor.count - 1) * byteStride + itemBytes;
+    } else {
+      length = accessor.count * itemBytes;
+    }
+
+    return {
+      offset,
+      length,
+      componentType: accessor.componentType,
+      accessorIndex,
+      type,
+      primIdx,
+      // Metadata used by the geometry-assembly pass below.
+      _accessor: accessor,
+      _components: components,
+      _componentSize: componentSize,
+      _itemBytes: itemBytes,
+      _byteStride: byteStride,
+      _interleaved: interleaved,
+    };
+  }
+
+  // Create a plain BufferAttribute, handling two transformations that
+  // KHR_mesh_quantization-encoded glTF files commonly require:
+  //   1. Deinterleave when the accessor lives inside a strided bufferView.
+  //   2. Dequantize (integer typed array + accessor.normalized=true) into
+  //      a tightly-packed Float32Array in [-1,1] / [0,1] range.
+  //
+  // Reasons for always emitting a non-strided, non-normalized Float32Array
+  // attribute:
+  //   * BufferGeometryUtils.mergeGeometries() (used heavily in this loader
+  //     to batch draw calls) refuses to merge InterleavedBufferAttribute
+  //     and requires identical TypedArray + `normalized` across primitives.
+  //     Eagerly dequantizing here lets us mix quantized and non-quantized
+  //     primitives in the same merged buffer.
+  //   * Geometry-local bounds (boundingBox, processNodeHierarchy extents)
+  //     and per-vertex CPU-side traversal can then assume float values.
+  //
+  // The trade-off is some extra CPU memory (4 bytes per component instead of
+  // 1/2). The download size benefit of quantization is preserved.
+  _createGeometryAttribute(req) {
+    const accessor = req._accessor;
+    const components = req._components;
+    const count = accessor.count;
+    const stride = req._interleaved ? req._byteStride / req._componentSize : components;
+    const normalized = accessor.normalized === true;
+    const componentType = req.componentType;
+    const src = req.data;
+
+    // Fast path: tightly-packed, non-normalized data — no copy needed.
+    // Covers the common cases: non-quantized FLOAT attributes and integer
+    // indices. The `req.data` view already has the correct length & type.
+    if (!req._interleaved && !normalized) {
+      return new BufferAttribute(src, components, false);
+    }
+
+    // Normalized integer attribute (KHR_mesh_quantization) → dequantize to
+    // Float32 in [-1,1] / [0,1] range. This keeps merge/bounds simple.
+    if (normalized) {
+      const denom = this._normalizedDenominator(componentType);
+      if (denom > 0) {
+        const out = new Float32Array(count * components);
+        const inv = 1 / denom;
+        const isSignedNormalized = componentType === 5120 || componentType === 5122;
+        for (let i = 0; i < count; i++) {
+          const srcBase = i * stride;
+          const dstBase = i * components;
+          for (let c = 0; c < components; c++) {
+            let v = src[srcBase + c] * inv;
+            if (isSignedNormalized && v < -1) v = -1; // glTF spec clamp
+            out[dstBase + c] = v;
+          }
+        }
+        return new BufferAttribute(out, components, false);
+      }
+    }
+
+    // Interleaved + non-normalized: deinterleave but preserve original
+    // typed-array type (rare, but handle it for completeness).
+    const TypedArrayCtor = src.constructor;
+    const out = new TypedArrayCtor(count * components);
+    for (let i = 0; i < count; i++) {
+      const srcBase = i * stride;
+      const dstBase = i * components;
+      for (let c = 0; c < components; c++) {
+        out[dstBase + c] = src[srcBase + c];
+      }
+    }
+    return new BufferAttribute(out, components, false);
   }
 
   createDummyTexture() {
@@ -241,7 +515,7 @@ export class DynamicGltfLoader {
     this.transformTexture.needsUpdate = true;
   }
 
-  setVisibleEdges(visible) {
+  setVisibleEdges(visible = true) {
     this.visibleEdges = visible;
   }
 
@@ -538,83 +812,66 @@ export class DynamicGltfLoader {
     const meshDef = node.structure.getJson().meshes[node.meshIndex];
 
     try {
+      // Fail fast: if any primitive in this mesh requires Draco but no
+      // DRACOLoader was injected, abort with a single descriptive error
+      // *before* we fetch any buffers. Otherwise downstream code
+      // (estimateGeometrySize, mesh assembly, etc.) would hit secondary
+      // null-deref crashes that mask the real cause. The throw is caught
+      // by the surrounding try/catch and logged once via the standard
+      // "Error loading node N" channel.
+      if (
+        !this._dracoLoader &&
+        meshDef.primitives &&
+        meshDef.primitives.some((p) => p.extensions && p.extensions[DRACO_EXTENSION_NAME])
+      ) {
+        throw new Error(
+          "primitive uses KHR_draco_mesh_compression but no DRACOLoader is configured. " +
+            "Inject one via dynamicLoader.setDracoLoader(new DRACOLoader()) before opening the file."
+        );
+      }
+
       const bufferRequests = [];
       const primitiveReqMap = new Map();
+      const dracoPrimitives = new Map(); // primIdx -> { req: {offset, length}, primitive }
+
       for (let primIdx = 0; primIdx < meshDef.primitives.length; primIdx++) {
         const primitive = meshDef.primitives[primIdx];
         const reqs = [];
 
-        if (primitive.attributes.POSITION !== undefined) {
-          const accessorIndex = primitive.attributes.POSITION;
-          const accessor = node.structure.json.accessors[accessorIndex];
-          const bufferView = node.structure.json.bufferViews[accessor.bufferView];
-          const byteOffset = (bufferView.byteOffset || 0) + (accessor.byteOffset || 0);
-          const components = node.structure.getNumComponents(accessor.type);
-          const count = accessor.count;
-          const byteLength = count * components * node.structure.getComponentSize(accessor.componentType);
-          reqs.push({
+        // KHR_draco_mesh_compression: load the entire compressed bufferView
+        // and skip the per-attribute requests below.
+        const dracoExt = primitive.extensions && primitive.extensions[DRACO_EXTENSION_NAME];
+        if (dracoExt) {
+          const bufferView = node.structure.json.bufferViews[dracoExt.bufferView];
+          const byteOffset = bufferView.byteOffset || 0;
+          const byteLength = bufferView.byteLength;
+          const dracoReq = {
             offset: byteOffset,
             length: byteLength,
-            componentType: accessor.componentType,
-            accessorIndex,
-            type: "position",
+            componentType: 5121, // raw bytes
+            type: "draco",
             primIdx,
-          });
+          };
+          reqs.push(dracoReq);
+          dracoPrimitives.set(primIdx, { req: dracoReq, primitive });
+          primitiveReqMap.set(primIdx, reqs);
+          bufferRequests.push(...reqs);
+          continue;
         }
 
+        if (primitive.attributes.POSITION !== undefined) {
+          reqs.push(this._buildAccessorRequest(node.structure, primitive.attributes.POSITION, "position", primIdx));
+        }
         if (primitive.attributes.NORMAL !== undefined) {
-          const accessorIndex = primitive.attributes.NORMAL;
-          const accessor = node.structure.json.accessors[accessorIndex];
-          const bufferView = node.structure.json.bufferViews[accessor.bufferView];
-          const byteOffset = (bufferView.byteOffset || 0) + (accessor.byteOffset || 0);
-          const components = node.structure.getNumComponents(accessor.type);
-          const count = accessor.count;
-          const byteLength = count * components * node.structure.getComponentSize(accessor.componentType);
-          reqs.push({
-            offset: byteOffset,
-            length: byteLength,
-            componentType: accessor.componentType,
-            accessorIndex,
-            type: "normal",
-            primIdx,
-          });
+          reqs.push(this._buildAccessorRequest(node.structure, primitive.attributes.NORMAL, "normal", primIdx));
         }
-
         if (primitive.attributes.TEXCOORD_0 !== undefined) {
-          const accessorIndex = primitive.attributes.TEXCOORD_0;
-          const accessor = node.structure.json.accessors[accessorIndex];
-          const bufferView = node.structure.json.bufferViews[accessor.bufferView];
-          const byteOffset = (bufferView.byteOffset || 0) + (accessor.byteOffset || 0);
-          const components = node.structure.getNumComponents(accessor.type);
-          const count = accessor.count;
-          const byteLength = count * components * node.structure.getComponentSize(accessor.componentType);
-          reqs.push({
-            offset: byteOffset,
-            length: byteLength,
-            componentType: accessor.componentType,
-            accessorIndex,
-            type: "uv",
-            primIdx,
-          });
+          reqs.push(this._buildAccessorRequest(node.structure, primitive.attributes.TEXCOORD_0, "uv", primIdx));
         }
-
         if (primitive.indices !== undefined) {
-          const accessorIndex = primitive.indices;
-          const accessor = node.structure.json.accessors[accessorIndex];
-          const bufferView = node.structure.json.bufferViews[accessor.bufferView];
-          const byteOffset = (bufferView.byteOffset || 0) + (accessor.byteOffset || 0);
-          const components = node.structure.getNumComponents(accessor.type);
-          const count = accessor.count;
-          const byteLength = count * components * node.structure.getComponentSize(accessor.componentType);
-          reqs.push({
-            offset: byteOffset,
-            length: byteLength,
-            componentType: accessor.componentType,
-            accessorIndex,
-            type: "index",
-            primIdx,
-          });
+          reqs.push(this._buildAccessorRequest(node.structure, primitive.indices, "index", primIdx));
         }
+
         primitiveReqMap.set(primIdx, reqs);
         bufferRequests.push(...reqs);
       }
@@ -643,33 +900,45 @@ export class DynamicGltfLoader {
 
       for (let primIdx = 0; primIdx < meshDef.primitives.length; primIdx++) {
         const primitive = meshDef.primitives[primIdx];
-        const geometry = new BufferGeometry();
         const reqs = primitiveReqMap.get(primIdx);
+        let geometry;
+
+        // Handle Draco-compressed primitives
+        if (dracoPrimitives.has(primIdx)) {
+          const dracoReq = reqs.find((r) => r.type === "draco");
+          // Build a clean ArrayBuffer for the DRACO decoder.
+          // dracoReq.data is a Uint8Array view into the larger shared buffer.
+          const dracoBytes = new Uint8Array(dracoReq.data.buffer, dracoReq.data.byteOffset, dracoReq.data.byteLength);
+          const dracoBuffer = dracoBytes.slice().buffer; // copy to standalone ArrayBuffer
+          // Any decode failure (e.g. corrupted compressed data) will bubble
+          // up to the outer try/catch and be reported once via the standard
+          // "Error loading node N" channel rather than a misleading
+          // "skipping primitive" warning followed by a downstream null deref.
+          geometry = await this._decodeDracoPrimitive(node.structure, primitive, dracoBuffer);
+        } else {
+          geometry = new BufferGeometry();
 
-        if (primitive.attributes.POSITION !== undefined) {
-          const req = reqs.find((r) => r.type === "position" && r.accessorIndex === primitive.attributes.POSITION);
-          const accessor = node.structure.json.accessors[primitive.attributes.POSITION];
-          const components = node.structure.getNumComponents(accessor.type);
-          geometry.setAttribute("position", new BufferAttribute(req.data, components));
-        }
+          if (primitive.attributes.POSITION !== undefined) {
+            const req = reqs.find((r) => r.type === "position" && r.accessorIndex === primitive.attributes.POSITION);
+            geometry.setAttribute("position", this._createGeometryAttribute(req));
+          }
 
-        if (primitive.attributes.NORMAL !== undefined) {
-          const req = reqs.find((r) => r.type === "normal" && r.accessorIndex === primitive.attributes.NORMAL);
-          const accessor = node.structure.json.accessors[primitive.attributes.NORMAL];
-          const components = node.structure.getNumComponents(accessor.type);
-          geometry.setAttribute("normal", new BufferAttribute(req.data, components));
-        }
+          if (primitive.attributes.NORMAL !== undefined) {
+            const req = reqs.find((r) => r.type === "normal" && r.accessorIndex === primitive.attributes.NORMAL);
+            geometry.setAttribute("normal", this._createGeometryAttribute(req));
+          }
 
-        if (primitive.attributes.TEXCOORD_0 !== undefined) {
-          const req = reqs.find((r) => r.type === "uv" && r.accessorIndex === primitive.attributes.TEXCOORD_0);
-          const accessor = node.structure.json.accessors[primitive.attributes.TEXCOORD_0];
-          const components = node.structure.getNumComponents(accessor.type);
-          geometry.setAttribute("uv", new BufferAttribute(req.data, components));
-        }
+          if (primitive.attributes.TEXCOORD_0 !== undefined) {
+            const req = reqs.find((r) => r.type === "uv" && r.accessorIndex === primitive.attributes.TEXCOORD_0);
+            geometry.setAttribute("uv", this._createGeometryAttribute(req));
+          }
 
-        if (primitive.indices !== undefined) {
-          const req = reqs.find((r) => r.type === "index" && r.accessorIndex === primitive.indices);
-          geometry.setIndex(new BufferAttribute(req.data, 1));
+          if (primitive.indices !== undefined) {
+            const req = reqs.find((r) => r.type === "index" && r.accessorIndex === primitive.indices);
+            // Indices are never interleaved per glTF spec, but use the same
+            // helper for consistency (it falls back to BufferAttribute).
+            geometry.setIndex(this._createGeometryAttribute(req));
+          }
         }
 
         let material;
@@ -957,22 +1226,56 @@ export class DynamicGltfLoader {
       const nodeMatrix = new Matrix4();
       const uniqueNodeId = `${structure.id}_${nodeId}`;
       const meshDef = structure.json.meshes[nodeDef.mesh];
+
+      // Some glTF files may reference a mesh index that has no primitives
+      // (or no mesh at all). Skip this mesh node gracefully.
+      if (!meshDef || !meshDef.primitives || meshDef.primitives.length === 0) {
+        if (nodeDef.children) {
+          for (const childId of nodeDef.children) {
+            await this.processNodeHierarchy(structure, childId, nodeGroup || parentGroup);
+          }
+        }
+        return nodeGroup;
+      }
+
       const geometryExtents = new Box3();
 
       for (const primitive of meshDef.primitives) {
+        if (!primitive.attributes) continue;
         const positionAccessor = structure.json.accessors[primitive.attributes.POSITION];
         if (positionAccessor && positionAccessor.min && positionAccessor.max) {
-          const primitiveBox = new Box3(
-            new Vector3().fromArray(positionAccessor.min),
-            new Vector3().fromArray(positionAccessor.max)
-          );
-          geometryExtents.union(primitiveBox);
+          // For KHR_mesh_quantization (normalized integer accessors) min/max
+          // are stored in quantized integer space (e.g. -32767..32767). The
+          // BufferGeometry's local space, however, is the *normalized* range
+          // (-1..1 or 0..1) because the GPU performs dequantization via the
+          // `normalized` attribute flag. Convert here so geometryExtents is
+          // in geometry-local (post-normalization) space.
+          const minVec = new Vector3().fromArray(positionAccessor.min);
+          const maxVec = new Vector3().fromArray(positionAccessor.max);
+          if (positionAccessor.normalized === true) {
+            const denom = this._normalizedDenominator(positionAccessor.componentType);
+            if (denom > 0) {
+              minVec.divideScalar(denom);
+              maxVec.divideScalar(denom);
+              // For signed types the result is clamped to [-1, 1] per spec.
+              if (positionAccessor.componentType === 5120 || positionAccessor.componentType === 5122) {
+                minVec.x = Math.max(minVec.x, -1);
+                minVec.y = Math.max(minVec.y, -1);
+                minVec.z = Math.max(minVec.z, -1);
+                maxVec.x = Math.max(maxVec.x, -1);
+                maxVec.y = Math.max(maxVec.y, -1);
+                maxVec.z = Math.max(maxVec.z, -1);
+              }
+            }
+          }
+          geometryExtents.union(new Box3(minVec, maxVec));
         }
       }
 
       let isEdge = false;
-      if (meshDef.primitives[0].material !== undefined) {
-        const material = structure.json.materials[meshDef.primitives[0].material];
+      const firstPrimitive = meshDef.primitives[0];
+      if (firstPrimitive && firstPrimitive.material !== undefined) {
+        const material = structure.json.materials[firstPrimitive.material];
         if (material?.name === "edges") {
           isEdge = true;
         }
@@ -1332,7 +1635,20 @@ export class DynamicGltfLoader {
         `
       );
 
-      // 3. Transform Normal
+      // 3. Transform Normal (and Tangent, when present).
+      //
+      // We replace the standard `beginnormal_vertex` chunk because we need
+      // to apply the per-object batching matrix to the normal. The original
+      // three.js chunk also conditionally declares `objectTangent` under
+      // `#ifdef USE_TANGENT` — that define is enabled automatically by
+      // three.js whenever the material uses a normalMap (or clearcoat
+      // normalMap) AND the geometry has a `tangent` attribute (e.g.
+      // Avocado/BoomBox glTF samples). If our replacement omits that
+      // declaration, downstream chunks (`defaultnormal_vertex`, etc.) fail
+      // to compile with "objectTangent: undeclared identifier".
+      //
+      // We mirror three.js' own `skinnormal_vertex` convention: the same
+      // per-vertex matrix that rotates the normal also rotates the tangent.
       if (shader.vertexShader.includes("#include <beginnormal_vertex>")) {
         shader.vertexShader = shader.vertexShader.replace(
           "#include <beginnormal_vertex>",
@@ -1340,6 +1656,10 @@ export class DynamicGltfLoader {
             vec3 objectNormal = vec3( normal );
             mat3 bm = mat3( batchingMatrix );
             objectNormal = bm * objectNormal;
+            #ifdef USE_TANGENT
+                vec3 objectTangent = vec3( tangent.xyz );
+                objectTangent = bm * objectTangent;
+            #endif
             `
         );
       }
@@ -1504,6 +1824,11 @@ export class DynamicGltfLoader {
     this.objectVisibility = new Float32Array();
     this.meshToNodeMap = null;
     this.visibilityMaterials.clear();
+
+    // NOTE: do *not* drop this._dracoLoader here. The DRACOLoader is owned
+    // by the caller (injected via setDracoLoader) and should survive across
+    // clear()/reload cycles — the loader keeps its worker pool warm and is
+    // typically configured once at app startup.
   }
 
   setStructureTransform(structureId, matrix) {
@@ -2820,7 +3145,7 @@ export class DynamicGltfLoader {
     return extent;
   }
 
-  setMaxConcurrentChunks(maxChunks) {
+  setMaxConcurrentChunks(maxChunks = 6) {
     if (maxChunks < 1) {
       console.warn("Max concurrent chunks must be at least 1");
       return;