@displayxr/inline3d 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,90 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.2.0 — 2026-08-20
+
+### Added
+
+- **`./model` lights meshes with an image-based environment by default (`environment: 'room'`).**
+  The previous default, `studio`, is three punctual lights and nothing else. A punctual light
+  contributes a specular highlight but does not fill a metallic BRDF, so a `metalness: 1` surface
+  sampled an empty environment and resolved to **black** — chrome rendering as a dark disc, glass
+  lenses as opaque holes. The failure reads as a corrupt asset rather than a lighting choice, and
+  it cost real debugging time: two perfectly good models were discarded as broken before the cause
+  was found.
+
+  `environment` now takes `'room' | 'studio' | 'none'` and defaults to `'room'`, which bakes a
+  PMREM from three's procedural `RoomEnvironment` — generated in memory, so this buys IBL with no
+  HDRI to fetch and keeps an offline or kiosk build free of a CDN in its critical path. `'studio'`
+  remains for wholly dielectric matte content, and an explicit `envMap` still overrides both. Only
+  meshes are affected: splats carry their own baked radiance and never enter this path.
+
+  **This moves your pixels.** Metal and glass gain reflections they should always have had, and
+  dielectric surfaces pick up a softer ambient. Pass `environment: 'studio'` to keep 1.1.1's look.
+  *(preview tier — changed default)*
+
+- **`./model` loads compressed glTF — Draco, meshopt and KTX2/Basis.** `addModel()` resolved
+  `GLTFLoader` and called a bare `new Loader().loadAsync(src)`, so any asset carrying a compression
+  extension threw outright: `"No DRACOLoader instance provided."` for
+  `KHR_draco_mesh_compression`, `"setMeshoptDecoder must be called before loading compressed
+  files"` for `EXT_meshopt_compression`, and a failed texture for `KHR_texture_basisu`. These are
+  hard failures, not degraded loads, and Draco is close to universal in catalogue GLBs — so the
+  module's own premise, that a retailer's existing glTF renders unchanged, was false for most real
+  files.
+
+  `addModel` now reads the asset's `extensionsUsed` / `extensionsRequired` **before** parsing and
+  attaches exactly the decoders it declares. The inspection is a single `fetch` whose bytes go
+  straight to `loader.parse()`, so it replaces the loader's own request rather than adding one, and
+  an asset that declares no compression imports nothing, constructs nothing and costs exactly what
+  it did in 1.1.1 (measured: zero decoder requests, one request for the asset). Decoders are shared
+  across tiles and ref-counted by configuration, so a grid of twelve products stands up one Draco
+  worker pool and one tile's `remove()` cannot tear down the pool the other eleven are decoding on.
+  *(preview tier — additive)*
+
+- **`decoderPath`, and the reason it is not a CDN.** three ships the Draco decoder and the Basis
+  transcoder as *runtime* files that `DRACOLoader` / `KTX2Loader` fetch at decode time, so
+  something has to say where they are. The default is **your own origin** —
+  `{draco:'/draco/', basis:'/basis/'}`, the layout `cp -r node_modules/three/examples/jsm/libs/…`
+  produces — and there is deliberately **no CDN fallback**: pages built on this SDK include offline
+  kiosk builds, and a default that reached for `cdn.jsdelivr.net` the first time someone opened a
+  compressed product would make the page's offline story depend on one asset's compression setting.
+  A string is a parent directory holding both; an object overrides either key.
+  `EXT_meshopt_compression` needs nothing served — its decoder is pure JS. *(preview tier —
+  additive)*
+
+- **`DRACOLoader` / `KTX2Loader` / `meshoptDecoder` injection**, mirroring the existing
+  `GLTFLoader` escape. A **class** is constructed for you and pointed at `decoderPath`; an
+  **instance** is used exactly as you configured it and its decoder path is left alone — rewriting
+  it would defeat the one thing people inject for. `KTX2Loader.detectSupport()` is called for you
+  with the tile's own `WebGLRenderer` (`SceneViewer` owns it, and it exists synchronously by the
+  time the asset lands), and re-called per tile on a shared instance. *(preview tier — additive)*
+
+- **A failure message aimed at the page author.** A missing or mis-served decoder rejects
+  `handle.ready` with an error naming the **glTF extension**, the **option that fixes it** and the
+  **path it actually looked in** — plus `err.gltfExtension` / `err.decoder` for programmatic
+  handling. three's own message names a class the page never mentions and says nothing about the
+  two things that resolve it. The 404 case reads: *needs the "KHR_draco_mesh_compression" decoder
+  (Draco mesh compression) and it could not be used … Currently looking in "/draco/" — check that
+  it is actually served … Underlying error: fetch for ".../draco_wasm_wrapper.js" responded with
+  404*. *(preview tier — additive)*
+
+- **KTX2's silent failure is now loud.** `GLTFLoader` swallows a texture-load rejection, so a
+  mis-served Basis transcoder resolved a model with **zero textures and no error** — seven
+  compressed textures became none and `ready` resolved (measured on three r180). `addModel` now
+  loads the transcoder eagerly via `KTX2Loader.init()` once an asset declares
+  `KHR_texture_basisu`, which converts that into the named rejection above. *(preview tier)*
+
+- **`samples/model/` gains a Draco tile**, with three's Draco decoder served out of this repo at
+  `vendor/draco/` and the sample passing `decoderPath` — because the site is hosted under a path
+  prefix, which is exactly the case where the absolute default 404s. The tile is the same
+  `addModel` call as the others; only the asset differs. Duck (CC0, Khronos glTF-Sample-Assets).
+
+### Fixed
+
+- **`remove()` releases compressed textures.** `disposeTree` disposed geometries and materials but
+  not the materials' texture maps, which is real GPU memory as soon as KTX2 is in play and a
+  catalogue churns through it. *(preview tier)*
+
 ## 1.1.1 — 2026-08-20
 
 ### Fixed

package/README.md

@@ -24,6 +24,9 @@ npm install @displayxr/inline3d
 import { createInline3D } from '@displayxr/inline3d';
 import { EyeCamera, EdgeFeather } from '@displayxr/inline3d/three'; // optional three.js glue
 import { addSplat } from '@displayxr/inline3d/splat';               // experimental: 3DGS in a tile
+import { addModel } from '@displayxr/inline3d/model';               // experimental: glTF/GLB in a tile
+                                                                    //   (Draco / meshopt / KTX2 too —
+                                                                    //    you serve the decoder files)
 import { SceneViewer } from '@displayxr/inline3d/viewer';           // experimental: framing + orbit
 ```
 
@@ -78,12 +81,18 @@ samples/
   windows/            mixed 3D windows — still photos + a live video + a real-time three.js scene,
                       each woven with one SDK call, all on one session
   splat/              a 3D Gaussian splat in a tile, auto-framed, with a 2D price plate over it
+  model/              a glTF mesh, a mesh+splat scene, and a Draco-COMPRESSED glTF in three tiles
+  composition/        the 14-case 2D/3D overlap matrix — demo AND standing hardware regression
+                      surface; red cases ship red (see samples/README.md)
+vendor/draco/         three's Draco decoder, served for samples/model (compressed glTF needs it)
 js/
   inline3d.js         the SDK: createInline3D() → { addImage, addVideo, addScene }, feature-detect,
                       SBS buffer management, and a lazy create/close lifecycle for many windows
   inline3d-three.js   optional three.js helper (EyeCamera: off-axis projection from the session's eyes)
   inline3d-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
+  inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
+                      from what the asset declares (you serve the decoder files — see the guide)
 docs/
   authoring-inline-3d.md   the authoring guide
 ```

package/js/inline3d-model.js

@@ -21,10 +21,29 @@
 //   "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/"
 //
 // You can also hand the class in directly (`opts.GLTFLoader`) and skip the specifier entirely.
+//
+// ── COMPRESSED ASSETS ───────────────────────────────────────────────────────────────────────
+// "Render the catalogue unchanged" is only true if the catalogue's actual files load, and a real
+// e-commerce GLB is nearly always Draco-compressed. A bare GLTFLoader cannot decode any of the
+// three compression extensions — it throws, it does not degrade — so this module inspects the
+// asset's `extensionsUsed` before parsing and attaches exactly the decoders it declares:
+//
+//   KHR_draco_mesh_compression  → DRACOLoader   (needs decoder files SERVED by your page)
+//   KHR_texture_basisu          → KTX2Loader    (needs transcoder files SERVED by your page)
+//   EXT_meshopt_compression     → MeshoptDecoder (pure JS, nothing to serve)
+//
+// Nothing is imported or instantiated for an asset that declares none of them — an uncompressed
+// GLB costs exactly what it did before. The decoder BINARIES are deliberately not fetched from a
+// CDN: pages that ship this SDK include offline kiosk builds, so the default looks for them on
+// your own origin (`/draco/`, `/basis/`) and `opts.decoderPath` moves that. See
+// docs/authoring-inline-3d.md#compressed-gltf.
 
 import * as THREE from 'three';
 import { EyeCamera, EdgeFeather } from './inline3d-three.js';
 import { SceneViewer } from './inline3d-viewer.js';
+// Procedural — built in memory, no asset to serve. Imported eagerly rather than lazily because it
+// is the default lighting path, so deferring it would only add a frame of unlit content.
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
 
 /** Cached across calls so a grid of models resolves the loader module once. */
 let _GLTFLoader = null;
@@ -38,6 +57,246 @@ async function resolveLoader(injected) {
   return _GLTFLoader;
 }
 
+// ── the three compression extensions, and everything needed to talk about them ───────────────
+
+/**
+ * One entry per decoder: the glTF extension that demands it, where its class lives, where its
+ * runtime files live, and which option overrides each. The error messages are generated from
+ * this table, so a message can never name an option that does not exist.
+ */
+const DECODERS = {
+  draco: {
+    ext: 'KHR_draco_mesh_compression',
+    label: 'Draco mesh compression',
+    module: 'three/addons/loaders/DRACOLoader.js',
+    exportName: 'DRACOLoader',
+    option: 'DRACOLoader',
+    pathKey: 'draco',
+    files: 'three/examples/jsm/libs/draco/',
+    attach: (loader, d) => loader.setDRACOLoader(d),
+  },
+  ktx2: {
+    ext: 'KHR_texture_basisu',
+    label: 'KTX2 / Basis Universal textures',
+    module: 'three/addons/loaders/KTX2Loader.js',
+    exportName: 'KTX2Loader',
+    option: 'KTX2Loader',
+    pathKey: 'basis',
+    files: 'three/examples/jsm/libs/basis/',
+    attach: (loader, d) => loader.setKTX2Loader(d),
+  },
+  meshopt: {
+    ext: 'EXT_meshopt_compression',
+    label: 'meshopt compression',
+    module: 'three/addons/libs/meshopt_decoder.module.js',
+    exportName: 'MeshoptDecoder',
+    option: 'meshoptDecoder',
+    pathKey: null, // pure JS + inlined wasm; nothing for the page to serve
+    files: null,
+    attach: (loader, d) => loader.setMeshoptDecoder(d),
+  },
+};
+
+const DECODER_KINDS = /** @type {const} */ (['draco', 'ktx2', 'meshopt']);
+
+/**
+ * Where the decoder binaries are expected on YOUR origin. Not a CDN, on purpose — see the header.
+ * `/draco/` and `/basis/` are the paths three's own examples use, and the ones every "copy these
+ * two folders into public/" recipe on the web produces.
+ */
+const DEFAULT_DECODER_PATH = { draco: '/draco/', basis: '/basis/' };
+
+/** `'/vendor/'` → `{draco:'/vendor/draco/', basis:'/vendor/basis/'}`; an object overrides per-key. */
+function normalizeDecoderPath(v) {
+  if (!v) return { ...DEFAULT_DECODER_PATH };
+  if (typeof v === 'string') {
+    const base = v.endsWith('/') ? v : `${v}/`;
+    return { draco: `${base}draco/`, basis: `${base}basis/` };
+  }
+  return {
+    draco: v.draco || DEFAULT_DECODER_PATH.draco,
+    basis: v.basis || v.ktx2 || DEFAULT_DECODER_PATH.basis,
+  };
+}
+
+/**
+ * Decoders are SHARED across tiles, ref-counted by configuration key. A DRACOLoader owns a worker
+ * pool; a catalogue grid of twelve products must not stand up twelve of them, and one tile's
+ * `remove()` must not tear down the pool the other eleven are decoding on. Injected decoders never
+ * enter this map — they belong to the caller, who disposes them.
+ */
+const _shared = new Map(); // key -> { refs, p: Promise<decoder> }
+
+function acquireShared(key, make) {
+  let e = _shared.get(key);
+  if (!e) {
+    e = { refs: 0, p: make() };
+    // A failed build must not poison every later attempt with a rejected promise.
+    e.p.catch(() => _shared.delete(key));
+    _shared.set(key, e);
+  }
+  e.refs++;
+  return e.p;
+}
+
+function releaseShared(key) {
+  const e = _shared.get(key);
+  if (!e || --e.refs > 0) return;
+  _shared.delete(key);
+  e.p.then((d) => d?.dispose?.()).catch(() => {});
+}
+
+/**
+ * Import (or accept) a decoder and configure it. `injected` may be a class OR a ready instance —
+ * MeshoptDecoder is a namespace object rather than a class, and a caller who already holds a
+ * configured DRACOLoader should be able to hand THAT in rather than a constructor.
+ *
+ * `decoderPath` is applied only to instances WE construct. An instance you hand in is used exactly
+ * as you configured it: silently rewriting its decoder path would make injection useless for the
+ * one thing people inject for, which is pointing it somewhere unusual.
+ */
+async function buildDecoder(kind, paths, injected) {
+  const spec = DECODERS[kind];
+  let thing = injected;
+  if (!thing) {
+    const mod = await import(spec.module);
+    thing = mod[spec.exportName];
+    if (!thing) throw new Error(`${spec.module} has no export "${spec.exportName}"`);
+  }
+  if (typeof thing !== 'function') return thing; // already an instance (or the meshopt namespace)
+  const d = new thing();
+  if (kind === 'draco') d.setDecoderPath?.(paths.draco);
+  if (kind === 'ktx2') d.setTranscoderPath?.(paths.basis);
+  return d;
+}
+
+/** @returns {Promise<{decoder:object, key:string|null}>} `key` is set when the tile took a share. */
+async function getDecoder(kind, paths, injected, renderer) {
+  let decoder;
+  let key = null;
+  if (injected) {
+    decoder = await buildDecoder(kind, paths, injected);
+  } else {
+    const p = DECODERS[kind].pathKey;
+    key = `${kind}|${p ? paths[p] : ''}`;
+    decoder = await acquireShared(key, () => buildDecoder(kind, paths, null));
+  }
+  if (kind === 'ktx2') {
+    // MUST run with the renderer that will sample the texture: detectSupport reads the context's
+    // compressed-texture extensions to pick a transcode target. Re-run per tile because the shared
+    // instance may have been built against a sibling's context; it is a cheap flag assignment.
+    decoder.detectSupport?.(renderer);
+    // And then force the transcoder to load NOW, because KTX2 is the one decoder that fails
+    // SILENTLY: GLTFLoader swallows a texture-load rejection, so a mis-served transcoder resolves
+    // a model with ZERO textures and no error at all (measured on three r180 — 7 textures became
+    // 0, `ready` resolved). init() turns that into a rejection naming the URL it could not fetch.
+    await decoder.init?.();
+  }
+  return { decoder, key };
+}
+
+// ── asset inspection ─────────────────────────────────────────────────────────────────────────
+
+const GLB_MAGIC = 0x46546c67; // 'glTF', little-endian
+const GLB_CHUNK_JSON = 0x4e4f534a; // 'JSON'
+
+/**
+ * Fetch the asset ONCE and read its glTF JSON header. The bytes are handed to `loader.parse()`
+ * afterwards, so inspecting costs no extra request — this replaces the loader's own fetch rather
+ * than adding to it.
+ */
+async function fetchAndInspect(src) {
+  const res = await fetch(src);
+  if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText} for ${src}`);
+  const buffer = await res.arrayBuffer();
+  return { buffer, json: gltfJsonOf(buffer) };
+}
+
+function gltfJsonOf(buffer) {
+  const view = new DataView(buffer);
+  const text = new TextDecoder();
+  if (buffer.byteLength >= 20 && view.getUint32(0, true) === GLB_MAGIC) {
+    const len = view.getUint32(12, true);
+    if (view.getUint32(16, true) !== GLB_CHUNK_JSON) return null;
+    return JSON.parse(text.decode(new Uint8Array(buffer, 20, len)));
+  }
+  return JSON.parse(text.decode(new Uint8Array(buffer))); // a .gltf is plain JSON
+}
+
+/** `extensionsUsed` ∪ `extensionsRequired`. Draco appears in both; meshopt sometimes only in one. */
+function declaredExtensions(json) {
+  const out = new Set();
+  for (const key of ['extensionsUsed', 'extensionsRequired']) {
+    const list = json?.[key];
+    if (Array.isArray(list)) for (const name of list) out.add(name);
+  }
+  return out;
+}
+
+function urlBaseOf(src) {
+  const extract = THREE.LoaderUtils?.extractUrlBase;
+  if (extract) return extract(src);
+  const i = src.lastIndexOf('/');
+  return i < 0 ? './' : src.slice(0, i + 1);
+}
+
+// ── errors that tell a page author what to do ────────────────────────────────────────────────
+
+/**
+ * three's own messages for these failures ("No DRACOLoader instance provided.") name a class the
+ * page never mentions and say nothing about the two things that actually fix it: which option to
+ * pass, and which files to serve. This builds the message that does.
+ *
+ * @param {string} kind  a key of DECODERS
+ * @param {string} src
+ * @param {{draco:string,basis:string}} paths
+ * @param {unknown} cause
+ * @param {boolean} inspected  whether we managed to read the asset's extension list
+ */
+function decoderError(kind, src, paths, cause, inspected) {
+  const spec = DECODERS[kind];
+  const lines = [
+    `[inline3d/model] ${src} needs the "${spec.ext}" decoder (${spec.label}) and it could not be used.`,
+  ];
+  if (spec.files) {
+    const dir = spec.pathKey;
+    const where = paths[dir];
+    lines.push(
+      `Serve three's decoder files from your own origin and point addModel at them:`,
+      `    cp -r node_modules/${spec.files} <web-root>${where.startsWith('/') ? where : `/${dir}/`}`,
+      `    addModel(wall, canvas, src, { decoderPath: { ${dir}: '${where}' } })`,
+      `Currently looking in "${where}" — check that it is actually served (a 404 there fails exactly like this).`,
+    );
+  } else {
+    lines.push(
+      `Nothing to serve for this one — the meshopt decoder is pure JS, so this is a module-resolution failure.`,
+    );
+  }
+  lines.push(
+    `Or hand the decoder in: addModel(…, { ${spec.option}: X }) where X is ${spec.exportName} from '${spec.module}' (a class or a ready instance).`,
+    `On a bare importmap, '${spec.module}' additionally needs a "three/addons/" prefix mapping.`,
+  );
+  if (!inspected) {
+    lines.push(
+      `(The asset's extension list could not be read up front, so the decoder was not attached automatically.)`,
+    );
+  }
+  lines.push(`Underlying error: ${cause?.message || cause}`);
+  const err = new Error(lines.join('\n'));
+  err.cause = cause;
+  err.decoder = kind;
+  err.gltfExtension = spec.ext;
+  return err;
+}
+
+/** Which decoder is a raw three.js failure about? Used when inspection failed and three threw. */
+function kindFromMessage(msg) {
+  if (/DRACOLoader|draco/i.test(msg)) return 'draco';
+  if (/KTX2Loader|basisu|basis/i.test(msg)) return 'ktx2';
+  if (/MeshoptDecoder|meshopt/i.test(msg)) return 'meshopt';
+  return null;
+}
+
 /**
  * Load a glTF/GLB into an inline-3D window.
  *
@@ -45,11 +304,26 @@ async function resolveLoader(injected) {
  * @param {HTMLCanvasElement} canvas
  * @param {string} src  URL of a .glb / .gltf.
  * @param {object} [opts]  every option ./splat takes, plus:
- * @param {'studio'|'none'} [opts.environment='studio']  built-in three-point lighting. Meshes
- *        arrive unlit otherwise — unlike splats, which carry their own baked appearance.
- * @param {object} [opts.envMap]  a PMREM-processed environment texture, if you have one. Better
- *        than `environment` for metal and glass; overrides it.
+ * @param {'room'|'studio'|'none'} [opts.environment='room']  how the mesh is lit. Meshes arrive
+ *        unlit otherwise — unlike splats, which carry their own baked appearance.
+ *        - `room` (default) bakes an image-based environment from three's procedural
+ *          RoomEnvironment. Metal and glass NEED this: a punctual light contributes a specular
+ *          dot but does not fill a metallic BRDF, so under `studio` a `metalness: 1` surface
+ *          samples an empty environment and resolves to black. Procedural, so it costs no HDRI
+ *          fetch and an offline build stays offline.
+ *        - `studio` is the older three-point punctual rig. Cheaper, and fine for wholly dielectric
+ *          matte content, but it is what makes chrome render as a dark hole.
+ * @param {object} [opts.envMap]  a PMREM-processed environment texture of your own. Overrides
+ *        `environment` entirely — pass this when you want the product lit by a specific room.
  * @param {unknown} [opts.GLTFLoader]  hand in the class instead of resolving `three/addons/`.
+ * @param {string|{draco?:string,basis?:string}} [opts.decoderPath]  where YOUR PAGE serves three's
+ *        Draco decoder and Basis transcoder (default `{draco:'/draco/', basis:'/basis/'}`). A
+ *        string is treated as a parent directory holding `draco/` and `basis/`. Never a CDN by
+ *        default: an offline build must not depend on one.
+ * @param {unknown} [opts.DRACOLoader]  DRACOLoader class or instance, instead of `three/addons/`.
+ * @param {unknown} [opts.KTX2Loader]  KTX2Loader class or instance. `detectSupport()` is called
+ *        for you with this tile's renderer.
+ * @param {unknown} [opts.meshoptDecoder]  MeshoptDecoder namespace, instead of `three/addons/`.
  * @returns {object} the same handle shape as addSplat: a TileHandle plus `viewer`, `model`,
  *          `setPose`, `resetPose`, `frame`, and `ready`.
  */
@@ -65,12 +339,19 @@ export function addModel(wall, canvas, src, opts = {}) {
     fitSweep = true,
     renderScale = 1,
     feather = 0,
-    environment = 'studio',
+    environment = 'room',
     envMap = null,
     GLTFLoader: injectedLoader = null,
+    decoderPath = null,
+    DRACOLoader: injectedDraco = null,
+    KTX2Loader: injectedKtx2 = null,
+    meshoptDecoder: injectedMeshopt = null,
     observe,
   } = opts;
 
+  const paths = normalizeDecoderPath(decoderPath);
+  const injected = { draco: injectedDraco, ktx2: injectedKtx2, meshopt: injectedMeshopt };
+
   const viewer = new SceneViewer(THREE, canvas, {
     virtualDisplayHeight,
     fit,
@@ -84,8 +365,12 @@ export function addModel(wall, canvas, src, opts = {}) {
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   if (envMap) viewer.scene.environment = envMap;
+  else if (environment === 'room') addRoomEnvironment(viewer);
   else if (environment === 'studio') addStudioLights(viewer.scene);
 
+  /** Shared-decoder keys this tile holds a reference to, released in remove(). */
+  const held = [];
+
   const out = {
     viewer,
     model: null,
@@ -96,6 +381,7 @@ export function addModel(wall, canvas, src, opts = {}) {
       handle?.remove();
       viewer.dispose();
       if (out.model) disposeTree(out.model);
+      while (held.length) releaseShared(held.pop());
     },
     exclude: (el) => handle?.exclude(el),
     unexclude: (el) => handle?.unexclude(el),
@@ -115,7 +401,49 @@ export function addModel(wall, canvas, src, opts = {}) {
 
   out.ready = (async () => {
     const Loader = await resolveLoader(injectedLoader);
-    const gltf = await new Loader().loadAsync(src);
+    const loader = new Loader();
+
+    // Read the header before parsing, so decoders are attached from what the asset DECLARES
+    // rather than from a guess or from a failure. If this can't be done (an exotic URL scheme,
+    // a CORS setup fetch dislikes) we fall back to the loader's own fetch and rely on the
+    // message-sniffing catch below — the guidance survives, the laziness does not.
+    let inspected = null;
+    try {
+      inspected = await fetchAndInspect(src);
+    } catch (err) {
+      console.debug('[inline3d/model] could not inspect', src, '— falling back to loadAsync', err);
+    }
+
+    const declared = inspected?.json ? declaredExtensions(inspected.json) : null;
+    const wanted = DECODER_KINDS.filter(
+      (k) => injected[k] || (declared ? declared.has(DECODERS[k].ext) : false),
+    );
+
+    for (const kind of wanted) {
+      let got;
+      try {
+        got = await getDecoder(kind, paths, injected[kind], viewer.renderer);
+      } catch (err) {
+        throw decoderError(kind, src, paths, err, !!declared);
+      }
+      if (got.key) held.push(got.key);
+      DECODERS[kind].attach(loader, got.decoder);
+    }
+
+    let gltf;
+    try {
+      gltf = inspected
+        ? await new Promise((res, rej) => loader.parse(inspected.buffer, urlBaseOf(src), res, rej))
+        : await loader.loadAsync(src);
+    } catch (err) {
+      // A decoder that was attached can still fail at decode time — almost always because its
+      // files 404 at `decoderPath`, and three's message then carries the URL it could not fetch,
+      // which is why the message is asked first. Attributing by elimination is only safe with a
+      // single candidate; with none or several, the original error is the honest answer.
+      const kind = kindFromMessage(String(err?.message || err)) || (wanted.length === 1 ? wanted[0] : null);
+      throw kind ? decoderError(kind, src, paths, err, !!declared) : err;
+    }
+
     out.model = gltf.scene;
     viewer.content.add(gltf.scene);
 
@@ -144,6 +472,43 @@ function boundsOf(object3d) {
   return { center: [c.x, c.y, c.z], extent: [Math.max(e.x, 1e-6), Math.max(e.y, 1e-6), Math.max(e.z, 1e-6)] };
 }
 
+/**
+ * Bake an image-based environment from three's procedural RoomEnvironment.
+ *
+ * This is the default because the alternative is silently wrong. `addStudioLights` is punctual
+ * only, and a punctual light contributes a specular highlight without filling a metallic BRDF —
+ * so a `metalness: 1` surface has nothing to reflect and resolves to BLACK. Chrome bells render as
+ * a dark disc, glass lenses as opaque holes, and the result reads as a corrupt asset rather than a
+ * lighting choice. It has cost real debugging time more than once.
+ *
+ * RoomEnvironment is generated in memory — a small box of emissive panels — so this buys IBL with
+ * no HDRI to fetch and no CDN in the critical path, which an offline or kiosk build depends on.
+ *
+ * Deliberately deferred behind the viewer: a PMREM is baked against one renderer's GL context and
+ * cannot be shared across renderers, so this cannot be hoisted into a module-level constant even
+ * though every tile bakes an identical one. The generator is disposed immediately; the resulting
+ * texture is owned by the scene and released with it.
+ *
+ * Splats never come through here — they carry baked radiance and no PBR material, and an
+ * environment would only wash them out.
+ */
+function addRoomEnvironment(viewer) {
+  const renderer = viewer?.renderer;
+  // No renderer means no context to bake against (a headless or not-yet-realised viewer). Fall
+  // back rather than throw: unlit-but-visible beats a tile that fails to appear at all.
+  if (!renderer) return addStudioLights(viewer.scene);
+
+  const pmrem = new THREE.PMREMGenerator(renderer);
+  try {
+    // Low blur on purpose. These are product shots, so a tighter environment keeps the highlight a
+    // travelling band rather than a broad wash — and a highlight that travels as the viewer moves
+    // is most of what separates an object from a picture of one on a head-tracked display.
+    viewer.scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+  } finally {
+    pmrem.dispose();
+  }
+}
+
 /**
  * A neutral three-point rig. Not a substitute for a real environment map on metal or glass, but
  * it has no external dependency and no download, which matters for a tile that may be one of
@@ -160,10 +525,19 @@ function addStudioLights(scene) {
 }
 
 function disposeTree(root) {
+  const seen = new Set();
+  const dropTextures = (mat) => {
+    if (!mat || seen.has(mat)) return;
+    seen.add(mat);
+    // Compressed (KTX2/Basis) textures are real GPU memory and a catalogue churns through them,
+    // so a tile's remove() has to give them back — the material's own dispose() does not.
+    for (const v of Object.values(mat)) if (v && v.isTexture) v.dispose?.();
+    mat.dispose?.();
+  };
   root.traverse((o) => {
     o.geometry?.dispose?.();
     const m = o.material;
-    if (Array.isArray(m)) m.forEach((x) => x?.dispose?.());
-    else m?.dispose?.();
+    if (Array.isArray(m)) m.forEach(dropTextures);
+    else dropTextures(m);
   });
 }

package/model.d.ts

@@ -25,11 +25,51 @@ export interface ModelOptions {
   renderScale?: number;
   feather?: number;
   /** Built-in three-point lighting. Meshes arrive unlit; splats do not need this. */
-  environment?: 'studio' | 'none';
+  /**
+   * How the mesh is lit. `room` (default) bakes IBL from three's procedural RoomEnvironment —
+   * metal and glass need it, because a punctual rig leaves a `metalness: 1` surface with nothing
+   * to reflect and it renders black. `studio` is the older three-point punctual rig.
+   */
+  environment?: 'room' | 'studio' | 'none';
   /** A PMREM-processed environment texture. Better than `environment` for metal; overrides it. */
   envMap?: object;
   /** Hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
   GLTFLoader?: unknown;
+
+  /**
+   * Where **your page** serves three's Draco decoder and Basis (KTX2) transcoder.
+   *
+   * `addModel` reads the asset's `extensionsUsed` before parsing and attaches only the decoders it
+   * declares, so an uncompressed model never touches any of this. But a decoder that IS needed has
+   * to come from somewhere, and the default is deliberately **not a CDN** — a page shipping an
+   * offline build must not acquire a network dependency by loading a compressed file. Copy the
+   * files out of `three` and serve them yourself:
+   *
+   * ```sh
+   * cp -r node_modules/three/examples/jsm/libs/draco/ public/draco/
+   * cp -r node_modules/three/examples/jsm/libs/basis/ public/basis/
+   * ```
+   *
+   * A string is a parent directory holding `draco/` and `basis/`; an object overrides either key.
+   * `EXT_meshopt_compression` needs nothing served — its decoder is pure JS.
+   *
+   * @default {draco:'/draco/', basis:'/basis/'}
+   */
+  decoderPath?: string | { draco?: string; basis?: string };
+  /**
+   * DRACOLoader class **or** a ready instance, instead of resolving `three/addons/`. A class is
+   * constructed and pointed at `decoderPath`; an instance is used exactly as you configured it.
+   */
+  DRACOLoader?: unknown;
+  /**
+   * KTX2Loader class or instance. `detectSupport()` is called for you with this tile's renderer,
+   * and the transcoder is loaded eagerly so a mis-served path throws instead of silently
+   * resolving a model with no textures.
+   */
+  KTX2Loader?: unknown;
+  /** The `MeshoptDecoder` namespace, instead of resolving `three/addons/`. Nothing to serve. */
+  meshoptDecoder?: unknown;
+
   /** Element whose visibility gates the lazy create/close lifecycle. */
   observe?: Element;
 }
@@ -55,6 +95,13 @@ export interface ModelHandle {
 /**
  * Load a glTF/GLB into an inline-3D window. Safe to call with an unsupported wall — it renders a
  * flat, orbitable view instead, so pages need no branch.
+ *
+ * Compressed assets (Draco, meshopt, KTX2/Basis) load too: the asset's declared extensions decide
+ * which decoders are imported, and nothing is imported for an asset that declares none. Draco and
+ * KTX2 additionally need their runtime files served by your page — see {@link ModelOptions.decoderPath}.
+ * When a decoder is needed and unavailable, `ready` rejects with an Error naming the glTF
+ * extension, the option that fixes it and the path it looked in; the extension is also on the
+ * error as `gltfExtension`.
  */
 export function addModel(
   wall: object | null | undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",