@displayxr/inline3d 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.7.1 — 2026-09-20
+
+Touches the **preview tier** (`./model`) only, and fixes exactly one thing: under a bundler, a
+compressed glTF never loaded at all. Uncompressed assets are unaffected, and so is every page that
+loads compressed ones through a bare importmap — same pixels, same timing. If your page builds with
+webpack / Turbopack / Vite / rollup and loads a Draco-, KTX2- or meshopt-compressed model, the tile
+that used to stay empty with a rejected `handle.ready` now renders the product.
+
+### Fixed
+
+- **`addModel` could not load ANY compressed asset under a bundler — all three decoders**
+  (preview tier). The decoders were resolved with `await import(spec.module)`, the specifier read
+  out of the `DECODERS` table — an *expression*, which no bundler can follow. The build printed
+
+  ```
+  Critical dependency: the request of a dependency is an expression
+  ```
+
+  and shipped a stub that throws `Cannot find module 'three/addons/…'` at runtime, which `addModel`
+  then reported honestly as a module-resolution failure in its own decoder error. Draco, KTX2/Basis
+  **and** meshopt all went through that one call, so the blast radius was the whole compressed path
+  — and a catalogue GLB out of a real pipeline is nearly always compressed, which is precisely the
+  case `/model` exists for. Each decoder now has a literal `import()` of its own
+  (`load: () => import('three/addons/loaders/DRACOLoader.js')`, and so on): that is what a build
+  tool can analyse, and it resolves unchanged under the `"three/addons/"` importmap prefix the
+  samples use.
+
+  It survived four releases because neither path that was exercised has the fault — `samples/` runs
+  on a bare importmap, which resolves specifiers at runtime and does not care, and the test suite is
+  deliberately dependency-free, so it never imported a decoder at all. The guard added with this fix
+  is therefore a source-level one: it reads `js/` the way a bundler does and fails if any `import()`
+  is handed a computed specifier again.
+
+  Nothing else moved. Injection (`{ DRACOLoader }`, `{ KTX2Loader }`, `{ meshoptDecoder }`, a class
+  or a ready instance you configured yourself), the shared ref-counted decoder cache, `decoderPath`
+  and the serve-the-decoder-files-yourself requirement are all as they were, and a decoder is still
+  imported only for an asset that declares its extension — bundlers now code-split each one into its
+  own chunk, so an uncompressed GLB downloads none of them.
+
+  Verified in Chrome against a Next.js 15 / webpack app loading an `EXT_meshopt_compression` GLB:
+  before, the build warning above plus `Cannot find module
+  'three/addons/libs/meshopt_decoder.module.js'` and an empty stage; after, no warning, the meshopt
+  decoder arriving as its own chunk, and the model on screen.
+
 ## 1.7.0 — 2026-09-19
 
 Touches the **preview tier** (`./splat`) only, and additively: `addSplat` with no new options

package/js/inline3d-model.js

@@ -63,12 +63,23 @@ async function resolveLoader(injected) {
  * 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.
+ *
+ * `load` is a thunk around a **literal** `import()` and `module` is the same specifier as a
+ * string, and the duplication is deliberate. A bundler can only follow an import whose specifier
+ * is written out at the call site: `import(spec.module)` — reading the string out of this table —
+ * is an *expression*, which webpack/Turbopack/rollup cannot resolve, so they emit
+ * "Critical dependency: the request of a dependency is an expression" at build time and a stub
+ * that throws `Cannot find module …` at runtime. That made EVERY compressed asset unloadable for
+ * every bundler consumer, while the bare-importmap path (which resolves at runtime and does not
+ * care) kept working — so it survived the samples. The string stays because the error messages
+ * quote it; the thunk is what actually loads.
  */
 const DECODERS = {
   draco: {
     ext: 'KHR_draco_mesh_compression',
     label: 'Draco mesh compression',
     module: 'three/addons/loaders/DRACOLoader.js',
+    load: () => import('three/addons/loaders/DRACOLoader.js'),
     exportName: 'DRACOLoader',
     option: 'DRACOLoader',
     pathKey: 'draco',
@@ -79,6 +90,7 @@ const DECODERS = {
     ext: 'KHR_texture_basisu',
     label: 'KTX2 / Basis Universal textures',
     module: 'three/addons/loaders/KTX2Loader.js',
+    load: () => import('three/addons/loaders/KTX2Loader.js'),
     exportName: 'KTX2Loader',
     option: 'KTX2Loader',
     pathKey: 'basis',
@@ -89,6 +101,7 @@ const DECODERS = {
     ext: 'EXT_meshopt_compression',
     label: 'meshopt compression',
     module: 'three/addons/libs/meshopt_decoder.module.js',
+    load: () => import('three/addons/libs/meshopt_decoder.module.js'),
     exportName: 'MeshoptDecoder',
     option: 'meshoptDecoder',
     pathKey: null, // pure JS + inlined wasm; nothing for the page to serve
@@ -159,7 +172,10 @@ async function buildDecoder(kind, paths, injected) {
   const spec = DECODERS[kind];
   let thing = injected;
   if (!thing) {
-    const mod = await import(spec.module);
+    // spec.load(), never `import(spec.module)` — see the note on DECODERS. One literal specifier
+    // per kind is what makes this analysable, and a bundler then code-splits each decoder into
+    // its own chunk, still fetched only for an asset that declares the extension.
+    const mod = await spec.load();
     thing = mod[spec.exportName];
     if (!thing) throw new Error(`${spec.module} has no export "${spec.exportName}"`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "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",