@displayxr/inline3d 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,156 @@ 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
+
+- **`./viewer` validates a frame before it clears the canvas — the dark blink under GPU load
+  (web#12).** `SceneViewer.onFrame` cleared unconditionally and then rendered whatever it could.
+  Under load the session hands the callback a **short view list** — one view, or none, a per-frame
+  mono fallback — and the old loop turned that into a cleared buffer with a single origin-camera
+  view drawn into it whose content is entirely near-plane-clipped: a fully transparent
+  side-by-side buffer, i.e. **one dark woven tile**. The blink was the viewer's, not the weave's;
+  it was reported as a compositor fault (glTF and splat tiles blinking on a busy box) with the
+  whole submit/match path provably healthy.
+
+  Now every disqualifying condition — a short view list, a `null` or degenerate
+  `layer.getViewport(view)`, a disposed viewer — is checked **while the canvas still holds the
+  last good image**, and only a frame that will draw is allowed to clear. A frame that cannot
+  draw **replays the last good one** from per-eye `Float32Array(16)` copies of
+  `projectionMatrix` / `transform.matrix` plus the viewport rects (copies, because an `XRView` is
+  valid only inside its own frame callback), rather than skipping the commit — the SDK's
+  every-frame-repaint invariant is real, and an un-redrawn canvas can drop out of the aggregated
+  frame and leave the weave reading a stale sub-rect. A one-frame-stale eye pose is
+  imperceptible; a black frame and a smear are not. Before the first good frame there is nothing
+  to replay, and the frame simply returns without clearing.
+
+  **This changes pixels only on frames that were previously black.** A frame that passed
+  validation renders byte-for-byte as it did in 1.1.0 — same clear, same viewports, same
+  matrices, same order. *(preview tier)*
+
+- **A no-op resize no longer blanks the tile (web#12).** `renderer.setSize()` writes
+  `canvas.width`/`canvas.height` unconditionally, and writing either — *including the same value*
+  — reallocates and clears the drawing buffer. `ResizeObserver` fires on things that leave the
+  buffer's dimensions exactly where they were (a sub-pixel reflow, a scrollbar coming and going, a
+  sibling settling), and its callback runs after rAF and before paint, so each one committed a
+  black frame with nothing on the way to repaint it. `_resize` now compares against
+  `renderer.domElement.width/height` and returns early when nothing moved; a real change resizes
+  and then **immediately** re-renders from the replay cache (rects scaled to the new buffer), so
+  the cleared store never reaches the compositor. Observer bursts coalesce to one animation frame,
+  matching what the core already does for its own windows. *(preview tier)*
+
+- **`SceneViewer` without `useEyeCamera()` says so instead of rendering nothing.** With no
+  `./three` glue the 3D path had no eye camera, so it cleared and drew nothing every frame,
+  forever, in silence — and this module's own header example omitted the call, making the failure
+  reachable by copy-paste. It now warns once and renders the **mono camera** into both eye
+  viewports (flat, but visible), and the example passes `EyeCamera`. `./splat` and `./model` were
+  never affected — they supply the glue for you. *(preview tier)*
+
+### Added
+
+- **`EyeCamera.setFromMatrices(projectionMatrix, transformMatrix)`** — the same two matrices an
+  `XRView` carries, handed over separately, for re-drawing a frame you have already drawn.
+  `setFromView` is now a one-line forward to it, so a replay path can never drift from the live
+  one. *(core tier — additive)*
+- **`handle.stats()` → `{ frames, monoFrames }`** on the handle every `add*()` returns. For scene
+  windows, `monoFrames` counts the deliveries that carried fewer than two views — the
+  load-induced fallback that used to be invisible from the page, since nothing throws and nothing
+  logs. A rising ratio is the machine telling you the session is degrading before it becomes a bug
+  report about "blinking"; one throttled `console.debug` (the first, then 1-in-300) names the
+  rate. The core's own contract is unchanged: the view list is passed to `onFrame` exactly as
+  reported, filtered by nothing and synthesised from nothing. *(core tier — additive)*
+- **Unit tests.** `test/*.test.mjs` under `node --test`, with the DOM and three.js stubbed by
+  hand (`test/stubs.mjs`) so the test run needs no dependency either. They pin the rules above:
+  zero `clear()` calls for an empty view list, a one-eye list, a null viewport and a missing
+  layer; a replay that renders the cached matrices and survives the UA recycling the views it
+  cached from; no `setSize` on a no-op resize; an immediate repaint after a real one. 13 of the
+  15 fail against 1.1.0. Wired into CI as a second job.
+
 ## 1.1.0 — 2026-08-19
 
 ### Added

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/index.d.ts

@@ -52,6 +52,18 @@ export interface TileHandle {
    * @deprecated See {@link TileHandle.exclude} — no-op on browsers with draw-order occlusion.
    */
   unexclude(el: Element): void;
+  /**
+   * Per-window frame counters, for diagnosing the load-induced mono fallback.
+   *
+   * `frames` counts `onFrame` deliveries; `monoFrames` counts the ones that carried fewer than
+   * two views — a session under GPU pressure reporting a single view where it normally reports
+   * two. `./viewer` replays its last good stereo frame for those rather than clearing (web#12);
+   * a rising ratio is the machine telling you the session is falling back, and is worth
+   * surfacing before it turns into a bug report about "blinking".
+   *
+   * Scene windows only — image/video windows always report `{ frames: 0, monoFrames: 0 }`.
+   */
+  stats(): { frames: number; monoFrames: number };
 }
 
 /** An open inline-3D session you add weaved windows to. Returned by {@link createInline3D}. */

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/js/inline3d-three.js

@@ -60,10 +60,31 @@ export class EyeCamera {
 
   /** Set the camera's projection + world pose from an XRView (call once per eye per frame). */
   setFromView(view) {
+    return this.setFromMatrices(view.projectionMatrix, view.transform.matrix);
+  }
+
+  /**
+   * Set the camera from RAW matrices — the same two an XRView carries, handed over
+   * separately.
+   *
+   * WHY THIS EXISTS AND NOT JUST setFromView. An `XRView` is valid only inside the frame
+   * callback that produced it: hold one and its matrices are live views onto memory the UA
+   * recycles. So a renderer that wants to re-draw a frame it has ALREADY drawn — because
+   * this frame's view list arrived short, or because the backing store was just reallocated
+   * and cleared — cannot keep the view; it has to keep a COPY of the two matrices and feed
+   * them back here. `./viewer`'s last-good replay does exactly that (see SceneViewer.onFrame).
+   *
+   * Deliberately the single implementation of both: setFromView is a one-line forward, so
+   * the replay path can never drift from the live one.
+   *
+   * @param {ArrayLike<number>} projectionMatrix  16 floats, column-major (view.projectionMatrix).
+   * @param {ArrayLike<number>} transformMatrix   16 floats, column-major (view.transform.matrix).
+   */
+  setFromMatrices(projectionMatrix, transformMatrix) {
     const cam = this.camera;
-    cam.projectionMatrix.fromArray(view.projectionMatrix);
+    cam.projectionMatrix.fromArray(projectionMatrix);
     cam.projectionMatrixInverse.copy(cam.projectionMatrix).invert();
-    cam.matrix.fromArray(view.transform.matrix);
+    cam.matrix.fromArray(transformMatrix);
     cam.matrixWorld.copy(cam.matrix);
     cam.matrixWorldInverse.copy(cam.matrixWorld).invert();
     return cam;

package/js/inline3d-viewer.js

@@ -20,9 +20,11 @@
 //
 //   import * as THREE from 'three';
 //   import { createInline3D } from '@displayxr/inline3d';
+//   import { EyeCamera } from '@displayxr/inline3d/three';
 //   import { SceneViewer } from '@displayxr/inline3d/viewer';
 //
 //   const viewer = new SceneViewer(THREE, canvas, { virtualDisplayHeight: 0.18 });
+//   viewer.useEyeCamera(EyeCamera);            // REQUIRED for stereo; ./splat and ./model do it
 //   viewer.content.add(myMesh);
 //   viewer.fitTo(center, extent);              // model-space bounds of the subject
 //   const wall = await createInline3D();
@@ -226,6 +228,12 @@ export class SceneViewer {
     this._monoRaf = 0;
     this._mode = '3d'; // drives the backing-store shape; see _resize
     this._disposed = false;
+    this._resizePending = false;
+    // Last frame this viewer actually DREW, as raw matrices + viewport rects — never XRViews,
+    // which are only valid inside their own frame callback. See _cacheGood / _replayLastGood.
+    this._lastGood = null;
+    this._vps = []; // scratch, reused per frame so validation allocates nothing
+    this._warnedNoEye = false;
 
     this._reduceMotion =
       typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
@@ -238,7 +246,10 @@ export class SceneViewer {
     // plane to be in focus at, so we just look at the framed subject from the front.
     this.monoCamera = new THREE.PerspectiveCamera(35, 1, 0.001, 1000);
 
-    this._onResize = () => this._resize();
+    // Coalesced: ResizeObserver and window resize both fire in BURSTS during a drag-resize or a
+    // zoom, and every genuine resize reallocates (and clears) the backing store. One rAF per
+    // burst, exactly as the core does for its own windows (inline3d.js _onBoxChange).
+    this._onResize = () => this._scheduleResize();
     this._ro = typeof ResizeObserver === 'function' ? new ResizeObserver(this._onResize) : null;
     if (this._ro) this._ro.observe(canvas);
     else addEventListener('resize', this._onResize);
@@ -348,6 +359,22 @@ export class SceneViewer {
   /**
    * The per-frame callback for `wall.addScene`. Renders the scene once per eye into the
    * side-by-side halves the layer reports.
+   *
+   * VALIDATE BEFORE YOU CLEAR — the dark-blink rule (web#12). `r.clear()` is the point of no
+   * return: after it the canvas is transparent-black, and if the frame then fails to draw
+   * anything over it, that empty buffer is what the weave consumes. Under GPU load the session
+   * can hand this callback a SHORT view list (one view, or none — a per-frame mono fallback),
+   * and the old loop cleared first and rendered what it could: a single origin-camera view whose
+   * content is entirely near-plane-clipped, i.e. a fully transparent side-by-side buffer, i.e.
+   * one dark woven tile. The blink was ours, not the weave's.
+   *
+   * So: everything that can disqualify a frame is checked while the canvas still holds the last
+   * good image, and only a frame that WILL draw is allowed to clear. A frame that cannot draw
+   * REPLAYS the last good one instead (see _replayLastGood) rather than skipping the commit —
+   * the SDK's every-frame-repaint invariant is real (inline3d.js `_frame`: a canvas that isn't
+   * redrawn can have its layer dropped from the aggregated frame and the weave then reads a
+   * stale sub-rect, which smears). A one-frame-stale eye pose is imperceptible; a smear and a
+   * black frame are not.
    */
   onFrame(views, layer) {
     if (this._disposed) return;
@@ -355,23 +382,62 @@ export class SceneViewer {
     // after a scroll-away/scroll-back). Take the buffer back to the SBS shape when that happens
     // — otherwise the first 3D frames render into a 1:1 store and each eye is half a subject.
     if (this._mode !== '3d') this.stopMono();
+    // Before the validation gate on purpose: a replayed frame still damps and still turns on the
+    // turntable, so only the EYE pose is one frame stale, not the whole scene.
     this._tick();
-    const r = this.renderer;
+
+    // 1. A short view list is the load-induced mono fallback. Stereo needs two.
+    if (!views || views.length < 2) {
+      this._replayLastGood();
+      return;
+    }
+
+    // 2. No ./three glue: the 3D path has no eye camera to build. This used to clear and draw
+    //    NOTHING, silently, forever — and this module's own header example omitted
+    //    useEyeCamera() until now, so the failure was reachable by copy-paste. Both ends are
+    //    fixed: the example passes it, and this says so once and renders the mono camera, which
+    //    at least shows the subject (flat, both halves the same) instead of a dark tile.
     const eye = this._ensureEye();
+    if (!eye && !this._warnedNoEye) {
+      this._warnedNoEye = true;
+      console.warn(
+        '[inline3d] SceneViewer.onFrame without useEyeCamera(): falling back to the mono camera. ' +
+          'Pass the ./three glue — viewer.useEyeCamera(EyeCamera, EdgeFeather) — for real ' +
+          'off-axis stereo. (./splat and ./model do this for you.)',
+      );
+    }
+
+    // 3. Every eye must have a viewport to render into. A missing or degenerate one means this
+    //    frame cannot fill the buffer, so it must not empty it either.
+    const vps = this._vps;
+    vps.length = 0;
+    for (const view of views) {
+      const vp = layer && typeof layer.getViewport === 'function' ? layer.getViewport(view) : null;
+      if (!vp || !(vp.width > 0) || !(vp.height > 0)) {
+        this._replayLastGood();
+        return;
+      }
+      vps.push(vp);
+    }
+
+    // Validated: this frame WILL draw over everything it clears.
+    const r = this.renderer;
     r.clear();
     r.setScissorTest(true);
-    for (const view of views) {
-      const vp = layer.getViewport(view);
-      if (!vp) continue;
+    for (let i = 0; i < views.length; i++) {
+      const vp = vps[i];
       r.setViewport(vp.x, vp.y, vp.width, vp.height);
       r.setScissor(vp.x, vp.y, vp.width, vp.height);
       if (eye) {
-        eye.setFromView(view);
+        eye.setFromView(views[i]);
         r.render(this.scene, eye.camera);
+      } else {
+        r.render(this.scene, this.monoCamera);
       }
       if (this._feather) this._feather.render(r, vp);
     }
     r.setScissorTest(false);
+    this._cacheGood(views, vps, !eye);
   }
 
   /**
@@ -418,6 +484,8 @@ export class SceneViewer {
 
   dispose() {
     this._disposed = true;
+    this._resizePending = false;
+    this._lastGood = null;
     this.stopMono();
     if (this._ro) this._ro.disconnect();
     else removeEventListener('resize', this._onResize);
@@ -432,6 +500,127 @@ export class SceneViewer {
     return this._eye;
   }
 
+  /**
+   * Remember the frame just drawn, so a frame that CANNOT draw has something to put on the
+   * canvas instead of a clear (web#12).
+   *
+   * COPIES, never references. An `XRView` — and the `projectionMatrix` / `transform.matrix`
+   * hanging off it — is valid only inside the frame callback that delivered it; the UA is free
+   * to recycle that memory afterwards. Retaining one would give a replay that reads whatever
+   * the next frame happened to write there, which is a worse bug than the blink. So each eye
+   * gets two `Float32Array(16)` copies, allocated once and overwritten in place: the cache
+   * costs 128 bytes an eye and zero allocations per frame.
+   *
+   * The buffer dimensions go in too, so a replay after a resize can scale the rects (the SBS
+   * split is proportional, so the scaling is exact).
+   */
+  _cacheGood(views, vps, mono) {
+    const el = this.renderer.domElement || this.canvas;
+    let g = this._lastGood;
+    if (!g || g.entries.length !== views.length) {
+      g = this._lastGood = { entries: [], mono, bufW: 0, bufH: 0 };
+      for (let i = 0; i < views.length; i++) {
+        g.entries.push({
+          proj: new Float32Array(16),
+          pose: new Float32Array(16),
+          x: 0,
+          y: 0,
+          width: 0,
+          height: 0,
+        });
+      }
+    }
+    g.mono = mono;
+    g.bufW = el.width || 0;
+    g.bufH = el.height || 0;
+    for (let i = 0; i < views.length; i++) {
+      const e = g.entries[i];
+      const vp = vps[i];
+      if (!mono) {
+        const view = views[i];
+        e.proj.set(view.projectionMatrix);
+        e.pose.set(view.transform.matrix);
+      }
+      e.x = vp.x;
+      e.y = vp.y;
+      e.width = vp.width;
+      e.height = vp.height;
+    }
+  }
+
+  /**
+   * Re-render the last good frame from the cached matrices. Returns false when there is no
+   * cache yet — and the caller must then do NOTHING, not clear: before the first good frame
+   * the canvas holds either the page's own initial state or the mono fallback's output, both
+   * of which are better than black.
+   */
+  _replayLastGood() {
+    const g = this._lastGood;
+    if (!g || this._disposed) return false;
+    const r = this.renderer;
+    const eye = g.mono ? null : this._ensureEye();
+    const el = this.renderer.domElement || this.canvas;
+    // A resize between the cache and the replay changes the buffer, not the split.
+    const sx = g.bufW > 0 && el.width ? el.width / g.bufW : 1;
+    const sy = g.bufH > 0 && el.height ? el.height / g.bufH : 1;
+    const scaled = sx !== 1 || sy !== 1;
+    r.clear();
+    r.setScissorTest(true);
+    for (const e of g.entries) {
+      const vp = scaled
+        ? {
+            x: Math.round(e.x * sx),
+            y: Math.round(e.y * sy),
+            width: Math.max(1, Math.round(e.width * sx)),
+            height: Math.max(1, Math.round(e.height * sy)),
+          }
+        : e;
+      r.setViewport(vp.x, vp.y, vp.width, vp.height);
+      r.setScissor(vp.x, vp.y, vp.width, vp.height);
+      if (eye) {
+        eye.setFromMatrices(e.proj, e.pose);
+        r.render(this.scene, eye.camera);
+      } else {
+        r.render(this.scene, this.monoCamera);
+      }
+      if (this._feather) this._feather.render(r, vp);
+    }
+    r.setScissorTest(false);
+    return true;
+  }
+
+  /** One rAF per burst of observer callbacks. See the _onResize comment. */
+  _scheduleResize() {
+    if (this._disposed || this._resizePending) return;
+    this._resizePending = true;
+    const run = () => {
+      if (!this._resizePending) return;
+      this._resizePending = false;
+      this._resize();
+    };
+    if (typeof requestAnimationFrame === 'function') requestAnimationFrame(run);
+    else run();
+  }
+
+  /**
+   * Put the last good frame back on a buffer that was just cleared, NOW — not on the next
+   * animation frame. A ResizeObserver callback runs after rAF and before paint, so the frame
+   * that reallocated the buffer is the frame that gets committed: without this the tile weaves
+   * one black frame per box change, with nothing on the way to repaint it. Mirrors the core's
+   * "repaint NOW: setting canvas.width cleared the buffer" (inline3d.js _onBoxChange).
+   */
+  _repaintAfterResize() {
+    if (this._disposed) return;
+    if (this._mode === 'mono') {
+      const r = this.renderer;
+      r.clear();
+      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      r.render(this.scene, this.monoCamera);
+      return;
+    }
+    this._replayLastGood();
+  }
+
   _applyTransform() {
     const s = this._fitScale * this._zoom;
     this._pivot.scale.setScalar(s);
@@ -454,6 +643,13 @@ export class SceneViewer {
    * getViewport() splits canvas.width in half for the two eyes — the browser squashing that
    * 2:1 buffer into the 1:1 CSS box IS the side-by-side squeeze, and the weave un-squeezes it.
    * In mono it must stay 1:1 or the flat render is stretched.
+   *
+   * NON-DESTRUCTIVE (web#12). `setSize` writes `canvas.width`/`canvas.height` UNCONDITIONALLY,
+   * and writing either one reallocates and CLEARS the drawing buffer even when the value does
+   * not change. Since a ResizeObserver fires on plenty of things that leave the buffer's
+   * dimensions exactly where they were (a sub-pixel reflow, a scrollbar appearing and going, a
+   * sibling settling), the old unconditional call meant a black frame for every no-op. So:
+   * compare first, and when it IS a real change, put the picture back before the frame commits.
    */
   _resize() {
     if (this._disposed) return;
@@ -462,9 +658,14 @@ export class SceneViewer {
     const dpr = Math.min(window.devicePixelRatio || 1, 2) * this.renderScale;
     const w = Math.max(1, Math.round(box.width * dpr));
     const h = Math.max(1, Math.round(box.height * dpr));
-    this.renderer.setSize(this._mode === 'mono' ? w : w * 2, h, false);
+    const bufW = this._mode === 'mono' ? w : w * 2;
+    // Cheap and always correct to refresh, whether or not the backing store moves.
     this.monoCamera.aspect = box.width / box.height;
     this.monoCamera.updateProjectionMatrix();
+    const el = this.renderer.domElement || this.canvas;
+    if (el.width === bufW && el.height === h) return; // observer fired, geometry didn't move
+    this.renderer.setSize(bufW, h, false);
+    this._repaintAfterResize();
   }
 
   /** Damping + idle turntable. Called once per rendered frame, 3D or mono. */

package/js/inline3d.js

@@ -528,6 +528,9 @@ class Inline3D {
         if (!el || !win.excluded.delete(el)) return;
         this._dropExclusion(win, el);
       },
+      // Read-only counters, for pages that want to see the load-induced mono fallback rather
+      // than wait for a bug report about "blinking". Scene windows only; 0/0 elsewhere.
+      stats: () => ({ frames: win.frames, monoFrames: win.monoFrames }),
     };
   }
 
@@ -574,6 +577,10 @@ class Inline3D {
       // Box/dpr watch, live only while the window is (see _startSizeWatch).
       sizeObserver: null,
       resizePending: false,
+      // Scene diagnostics (web#12), read back through the handle's stats(). frames counts
+      // onFrame deliveries; monoFrames counts the ones that carried fewer than two views.
+      frames: 0,
+      monoFrames: 0,
     };
     this._windows.set(canvas, win);
     if (this._lazy && this._observer) {
@@ -1020,7 +1027,32 @@ class Inline3D {
     for (const win of this._windows.values()) {
       if (!win.layer) continue;
       if (win.kind === 'scene') {
-        if (views && win.onFrame) win.onFrame(views, win.layer, f);
+        if (views && win.onFrame) {
+          // Count the SHORT view lists and hand them over unchanged. Under GPU load the session
+          // can report a single view (a per-frame mono fallback) where it normally reports two,
+          // and a renderer that clears before it validates turns that into a dark tile
+          // (web#12 — ./viewer now validates first and replays its last good frame instead).
+          //
+          // The core deliberately does NOT filter or synthesise: the contract is "here is what
+          // the frame reported", and a window that can do something sensible with one view
+          // (a mono preview, say) must be allowed to. What the core owes you is VISIBILITY —
+          // this is otherwise invisible from the page, since nothing throws and nothing logs.
+          win.frames++;
+          if (views.length < 2) {
+            win.monoFrames++;
+            // 1-in-300 so a sustained rate is reported without the log itself becoming the load;
+            // `% 300 === 1` also names the FIRST one immediately.
+            if (win.monoFrames % 300 === 1 && typeof console !== 'undefined' && console.debug) {
+              const pct = ((100 * win.monoFrames) / Math.max(1, win.frames)).toFixed(1);
+              console.debug(
+                `[inline3d] scene window: ${win.monoFrames} non-stereo view lists in ` +
+                  `${win.frames} frames (${pct}%). The viewer replays its last good stereo ` +
+                  'frame for these; a rising rate means the session is falling back under load.',
+              );
+            }
+          }
+          win.onFrame(views, win.layer, f);
+        }
       } else {
         // Repaint image AND video every frame. The weave reads each window's
         // composited canvas quad per frame; a canvas that isn't redrawn can have

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.0",
+  "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",
@@ -83,7 +83,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "npm run typecheck"
+    "test": "tsc --noEmit -p tsconfig.json && node --test \"test/*.test.mjs\""
   },
   "devDependencies": {
     "typescript": "^5.4.0",

package/three.d.ts

@@ -15,6 +15,18 @@ export class EyeCamera {
   readonly camera: unknown;
   /** Set the camera's projection + world pose straight from an XRView (call once per eye). */
   setFromView(view: XRView): void;
+  /**
+   * Set the camera from the two raw matrices an XRView carries, handed over separately.
+   *
+   * For re-drawing a frame you have already drawn: an `XRView` is valid only inside its own
+   * frame callback, so a renderer that wants to repaint (a short view list, a backing store
+   * just reallocated and cleared) must keep COPIES of these two matrices, not the view.
+   * `setFromView` forwards to this, so both paths are the same code.
+   */
+  setFromMatrices(
+    projectionMatrix: ArrayLike<number>,
+    transformMatrix: ArrayLike<number>,
+  ): void;
 }
 
 /**

package/viewer.d.ts

@@ -80,7 +80,14 @@ export declare class SceneViewer {
   setPose(pose?: OrbitPose): void;
   resetPose(): void;
 
-  /** Pass straight to `wall.addScene(canvas, viewer.onFrame, …)`. Pre-bound. */
+  /**
+   * Pass straight to `wall.addScene(canvas, viewer.onFrame, …)`. Pre-bound.
+   *
+   * Validates before it clears: a frame that cannot draw both eyes (a short view list from a
+   * session falling back under load, a missing viewport) re-renders the last good frame from
+   * cached matrices instead of clearing the canvas to black — the canvas is committed every
+   * frame either way, so the tile never goes dark and never smears (web#12).
+   */
   onFrame(views: readonly XRView[], layer: object): void;
 
   /** Supply the ./three glue so the 3D path can build its eye camera. Returns `this`. */