@displayxr/inline3d 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,198 @@
+# Changelog — `@displayxr/inline3d`
+
+Versioning follows [`docs/sdk-stability.md`](docs/sdk-stability.md). Read that first: the core
+entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (`./viewer`,
+`./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.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
+
+- **`inline3dOcclusionByDrawOrder()` — and the whole overlay-exclusion machinery turns itself off
+  where it's true.** The browser's Phase-2 compositor path composites ANY 2D content over woven
+  tiles per-pixel by draw order: a header, a badge, a dropdown, a translucent scrim, even a
+  full-tile plate occludes a tile with nothing declared. On such a browser this SDK stops working
+  around it — no auto-chrome DOM scan (a `querySelectorAll` + `getComputedStyle` sweep at every
+  layer activation), no `MutationObserver` per live tile for `data-inline3d-overlay`, and no
+  `will-change: transform` promotions written onto the page's own elements. `exclude()`,
+  `addGlobalOverlay()` and their `remove`/`unexclude` pairs still accept and store their argument
+  and simply do nothing, so ONE page runs unchanged on both browser generations; one
+  `console.info` says so the first time a page calls one.
+
+  The probe is a **capability, not a version**: the browser change is compositor-side and leaves
+  the JS API untouched, so `excludeElement` is present on both generations and only its effect
+  differs — its presence cannot tell them apart, and neither can `inline3dOverlaySupported()`,
+  whose question ("does 2D on a tile composite as crisp 2D?") is true on both. The gate is a
+  readonly capability flag the browser exposes on `XRDisplayLayer` —
+  `typeof XRDisplayLayer.occlusionByDrawOrder === 'boolean' ? XRDisplayLayer.occlusionByDrawOrder : …`,
+  falling back to the same-named per-layer attribute read off the first live layer if that is the
+  shape it lands in. **DisplayXR Browser 0.1.11 is the first build to expose it**, so on 0.1.11 and
+  newer this release stands the machinery down; on 0.1.10 and earlier the legacy path runs, byte for
+  byte as in 1.0 — verified by replaying one page against both SDK builds and diffing every
+  exclusion call, promotion, warning and registration. A user-agent or version gate was rejected: a
+  page pins an SDK for years, and a version string cannot describe a compositor behaviour that is
+  switch-gated — which is also why the flag reads `false` on a 0.1.11 launched with
+  `--disable-inline-3d-occlusion`, and the SDK correctly resumes the legacy path there.
+
+  Note what the *obvious* probe would have done.
+  `!!XRDisplayLayer.prototype.occlusionByDrawOrder` **throws** — a Blink IDL attribute getter
+  raises `TypeError: Illegal invocation` when its receiver is the prototype rather than an
+  instance — so the natural one-liner would have failed on precisely the browser it was looking
+  for. Presence is therefore probed with `in` (which calls no getter) and every value read has a
+  legal receiver: the interface object, or a real layer.
+
+  Effects on an element that overlaps a tile remain the exception on both generations: a
+  `backdrop-filter` (a function of what is behind it, and what is behind it is the woven buffer),
+  and — new small print for the Phase-2 path — a pixel-moving `filter`, a non-normal blend mode or
+  a 3D sorting context, none of which draw as the plain quad the split can lift. Plain chrome is
+  unaffected. *(core tier — additive: one new helper, no behaviour change on current browsers. The
+  exclusion APIs are deprecated-but-covered; see the stability policy.)*
+
+- **`./viewer`, `./splat` and `./model` are now published exports.** 1.0.0 shipped `exports` for
+  `.` and `./three` only, so `import { addSplat } from '@displayxr/inline3d/splat'` failed on an
+  npm install even though the modules existed in the repo — vendoring the files was the only way to
+  use a splat or a mesh tile. Additive, so nothing in 1.0.0 changes.
+  *(preview tier — see the stability policy before depending on their option shapes)*
+- `boundsFromPositions` takes `expand` (default 2.5), the width of the outlier-rejection window in
+  core extents. `expand: 0` restores the 1.0-era percentile-only box. *(preview)*
+- `addSplat` checks `THREE.REVISION` and throws a named error when three is older than 0.180,
+  Spark's floor. npm cannot express a peer range per export, so the manifest states the
+  package-wide `>=0.150` and an install on 0.16x succeeds; the failure used to surface from inside
+  a Spark worker as something unrelated to versions. *(preview)*
+- **A live window now tracks its own box and `devicePixelRatio`.** `addImage`/`addVideo` windows
+  get a `ResizeObserver` while active, plus a `(resolution: Ndppx)` media query for the changes a
+  `ResizeObserver` cannot see (browser zoom, a drag to a different-scale monitor); the
+  side-by-side buffer is re-derived and repainted on the next animation frame. `addScene`
+  canvases and windows given an explicit `{ width, height }` are box-independent and untouched.
+  *(core tier — additive; no API change)*
+- **Creating a second manager while one is live warns.** The browser's element-rect channel is a
+  whole-widget setter, so two live sessions in one document overwrite each other's rect list
+  every frame and neither one's tiles hold still. One `console.warn` says so; nothing is refused,
+  because a route change that closes one manager and opens the next is the normal case.
+  *(core tier)*
+- **A full-tile overlay is refused with an explanation instead of destroying the tile.** The
+  browser matches an excluded element to a composited quad by ≥70% area overlap, so a plate
+  congruent with its own canvas matches the **canvas** — which then leaves the weave input and
+  presents its raw side-by-side buffer. Both the imperative `exclude()` and the
+  `data-inline3d-overlay` scan now measure mutual overlap and skip such an element. The test is
+  mutual, so page-global chrome that fully covers a small tile is unaffected. Make the overlay a
+  partial region of the tile, or page chrome via `addGlobalOverlay()`. *(core tier)*
+
+### Changed — this moves existing pixels
+
+- **A splat's framing changes: subjects that were 10–15% too large now render smaller.**
+  `boundsFromPositions` returned a percentile-trimmed box as the subject's extent. Trimming is
+  essential on captured content — one floater a hundred metres out and the subject is a speck — but
+  the tail it drops on a DENSE subject is that subject's own outer shell, so the box came back
+  small and the fit faithfully turned that into a subject overflowing its tile. A uniform cube of
+  20k points measured 0.899 of its real size with no outliers present at all.
+
+  Percentiles now bound a rejection window and the returned extent is the true min/max inside it;
+  the same cube measures 1.000 and the floater is still rejected. Measured across seven scanned
+  products, rendered silhouettes went from 0.849–0.980 of the tile to 0.739–0.880, against 0.856
+  for the `./model` path whose `Box3` bounds were always exact.
+
+  If a page compensated for the old behaviour with a reduced `margin`, remove that compensation.
+  *(preview tier — `./viewer`, and `./splat` through it. `./model` is unaffected: its bounds were
+  never percentile-based.)*
+
+### Fixed
+
+- **Back-navigation left ghost 3D windows woven over the next page.** A window's rect reaches the
+  compositor from the session's own animation frames, and the only way to clear a rect is to push
+  a list without it — so a page frozen into the bfcache mid-loop leaves its last list standing and
+  its tiles keep weaving over whatever is on screen now (context:
+  [displayxr-browser#87](https://github.com/DisplayXR/displayxr-browser/issues/87)). Every live
+  window is now released on `pagehide` (and `freeze`, for a tab frozen without one) while frames
+  still run, so the outgoing frames report an empty list, and re-armed on `pageshow`/`resume`
+  through the existing lazy logic — re-observing re-delivers the current intersection state, so a
+  tile scrolled away before leaving stays dark. Page chrome is rescanned on restore. *(core tier)*
+- **A restored page could come back alive but never paint.** A bfcache restore can hand back a
+  session whose pending animation frame never arrives, leaving the manager nominally running with
+  a dead loop. A persisted `pageshow` now gives it a second to prove otherwise and then starts a
+  fresh loop; loops carry an id and only the current one re-arms, so a stalled predecessor cannot
+  double the loop if it later fires. *(core tier)*
+- `addSplat` threw a `ReferenceError` on the **URL path** — every ordinary page — because the
+  loader assigned `out.mesh` before `const out` was initialised. An async body runs synchronously
+  to its first `await`, and the URL path has none. The throw escaped into `ready` *after* the mesh
+  had joined the scene, so the splat rendered at raw model scale and never got framed: the symptom
+  was "the fit is wrong" when the fit had never run. The Blob path awaited `arrayBuffer()` and so
+  was unaffected, which is how it survived a commit about the bytes path. *(preview)*
+- A rejected splat load now detaches its mesh, so a failed tile is empty as documented rather than
+  an unframed subject spilling out of the window under the caller's error state. *(preview)*
+- `addSplat` warns when no usable bounds could be measured, instead of silently drawing at model
+  scale. *(preview)*
+
+## 1.0.0 — 2026-07-20
+
+First published release. Freezes the imperative authoring API — `createInline3D`, the `Inline3D`
+manager (`addImage` / `addVideo` / `addScene`, global overlays), the `TileHandle`, the detection
+helpers, the `data-inline3d-overlay` contract, and the side-by-side buffer contract — as the
+supported surface for 1.x. Exports `.` and `./three`.

package/README.md

@@ -23,13 +23,19 @@ npm install @displayxr/inline3d
 ```js
 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 { SceneViewer } from '@displayxr/inline3d/viewer';           // experimental: framing + orbit
 ```
 
 No build step or bundler required — it's plain ES modules. You can also import a pinned version by
 URL from a CDN (jsDelivr / unpkg) without npm. The samples in this repo import the SDK by relative
 path (`./js/inline3d.js`) so they run straight off GitHub Pages; in your own app prefer the package.
 
-`three` is an **optional peer dependency** — only the `@displayxr/inline3d/three` helpers need it.
+`three` and `@sparkjsdev/spark` are **optional peer dependencies** — the core is dependency-free
+and only the `/three`, `/viewer` and `/splat` subpaths need them. The two viewer subpaths are
+**experimental**: they turn "one object in a tile, look around it, drag to spin" into a single
+call (auto-framing on the zero-disparity plane, orbit, idle turntable, mono fallback), but their
+API is not yet covered by the semver promise below.
 
 Stability & what's covered by semver (and the deferred N-view / web-components / CSS-native roadmap
 that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stability.md).
@@ -71,10 +77,13 @@ index.html            landing (Pages entry point)
 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
 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
 docs/
   authoring-inline-3d.md   the authoring guide
 ```

package/index.d.ts

@@ -39,10 +39,31 @@ export interface TileHandle {
   /**
    * Mark a 2D element painted OVER this window so the weave leaves it crisp 2D instead of
    * garbling it (browser#18). No-op on browsers without overlay exclusion.
+   *
+   * @deprecated Legacy-browser mechanism. A browser with draw-order occlusion
+   * ({@link inline3dOcclusionByDrawOrder}) composites 2D over woven 3D per-pixel with nothing
+   * declared, so the call is accepted and ignored there — harmless everywhere, and still
+   * needed on older DisplayXR Browsers. Keep it unless you ship to Phase-2 browsers only.
    */
   exclude(el: Element): void;
-  /** Stop excluding `el` from this window's weave. */
+  /**
+   * Stop excluding `el` from this window's weave.
+   *
+   * @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}. */
@@ -84,9 +105,17 @@ export interface Inline3D {
    * Register a PAGE-GLOBAL 2D overlay (a fixed/sticky header, a floating toolbar) excluded from
    * EVERY window's weave and re-applied when a window lazily re-activates. Register once instead
    * of calling {@link TileHandle.exclude} per tile. No-op without overlay exclusion (browser#18).
+   *
+   * @deprecated Legacy-browser mechanism. Where {@link inline3dOcclusionByDrawOrder} is true,
+   * page chrome occludes every tile by itself: the element is stored and nothing is done to it
+   * (no `will-change` promotion). Harmless everywhere; still required on older browsers.
    */
   addGlobalOverlay(el: Element): void;
-  /** Stop treating `el` as a page-global overlay and drop it from every live window. */
+  /**
+   * Stop treating `el` as a page-global overlay and drop it from every live window.
+   *
+   * @deprecated See {@link Inline3D.addGlobalOverlay} — no-op with draw-order occlusion.
+   */
   removeGlobalOverlay(el: Element): void;
 
   /** Close the session and remove every window. */
@@ -111,6 +140,18 @@ export interface CreateInline3DOptions {
   lazy?: boolean;
   /** IntersectionObserver margin for lazy mode (default `"50% 0px"`). */
   rootMargin?: string;
+  /**
+   * Auto-exclude page chrome (default `true`): sticky/fixed elements near the top of
+   * the DOM (headers, toolbars) are registered as page-global overlays automatically —
+   * the bar plus its text/replaced descendants — so woven windows scroll UNDER the
+   * chrome with no per-app wiring. Opt an element (and its subtree) out with
+   * `data-inline3d-no-overlay`; set `false` to manage chrome exclusively via
+   * `addGlobalOverlay()` / `data-inline3d-overlay`.
+   *
+   * Ignored where {@link inline3dOcclusionByDrawOrder} is true: nothing is scanned and the
+   * SDK never touches your DOM's `will-change`, because the chrome already occludes the tiles.
+   */
+  autoChrome?: boolean;
 }
 
 /** The return of {@link startInline3D}. */
@@ -132,12 +173,27 @@ export interface StartInline3DResult {
 export function inline3DAvailable(): boolean;
 
 /**
- * True when this browser supports 2D-overlay exclusion (browser#18) — putting a 2D element ON a
- * woven tile so it composites as crisp 2D over the woven 3D. Implies {@link inline3DAvailable}.
- * Sync + cheap.
+ * True when a 2D element painted ON a woven tile composites as crisp 2D over the woven 3D
+ * instead of being woven — by declaration (browser#18 overlay exclusion) or automatically
+ * ({@link inline3dOcclusionByDrawOrder}). Same answer on both generations, so it stays true on
+ * a draw-order-occlusion browser. Implies {@link inline3DAvailable}. Sync + cheap.
  */
 export function inline3dOverlaySupported(): boolean;
 
+/**
+ * True when the browser occludes woven tiles with 2D content AUTOMATICALLY — anything that
+ * paints over a tile (header, badge, dropdown, translucent scrim) composites per-pixel by draw
+ * order, with nothing declared. When true this SDK's exclusion machinery is off: `autoChrome`
+ * does not scan, `data-inline3d-overlay` is not watched, and {@link TileHandle.exclude} /
+ * {@link Inline3D.addGlobalOverlay} are accepted but do nothing (no `will-change` promotion).
+ *
+ * You do not have to branch on it — the legacy calls are harmless where it is true and still
+ * required where it is false. Branch only to skip work of your own. Reads a readonly capability
+ * flag on `XRDisplayLayer`, never a version or UA string, and is `false` on any browser that
+ * does not expose the flag (the safe answer: the legacy path runs).
+ */
+export function inline3dOcclusionByDrawOrder(): boolean;
+
 /** Open the page's inline-3D session and return a manager you add windows to. */
 export function createInline3D(
   opts?: CreateInline3DOptions,
@@ -159,6 +215,19 @@ export function startInline3D(
 // XRDisplayLayer is a DisplayXR-Browser extension to WebXR; declare the minimum the SDK exposes.
 export interface XRDisplayLayer {
   getViewport(view: XRView): { x: number; y: number; width: number; height: number } | null;
+  /**
+   * @deprecated Legacy-browser overlay exclusion (browser#18). Present-but-no-op on a browser
+   * with draw-order occlusion, which is exactly why its presence cannot be used to detect the
+   * generation — use {@link inline3dOcclusionByDrawOrder} (i.e. `occlusionByDrawOrder`).
+   */
   excludeElement?(el: Element): void;
+  /** @deprecated See {@link XRDisplayLayer.excludeElement}. */
+  unexcludeElement?(el: Element): void;
+  /**
+   * Readonly capability flag: `true` when this browser composites 2D over woven 3D per-pixel by
+   * draw order, making overlay exclusion unnecessary. Optional because it is absent on every
+   * browser shipped so far — the SDK treats absent as `false` and runs the legacy path.
+   */
+  readonly occlusionByDrawOrder?: boolean;
   close(): void;
 }

package/js/inline3d-model.js

@@ -0,0 +1,169 @@
+// inline3d-model.js — a glTF/GLB model as an inline-3D window, in one call.
+//
+// EXPERIMENTAL. Not covered by the SDK's 1.x semver promise — see docs/sdk-stability.md.
+//
+//   import { createInline3D } from '@displayxr/inline3d';
+//   import { addModel } from '@displayxr/inline3d/model';
+//
+//   const wall = await createInline3D();
+//   const lamp = addModel(wall, canvas, 'lamp.glb', { virtualDisplayHeight: 0.3 });
+//   lamp.exclude(document.getElementById('buy'));
+//
+// Deliberately the same options, the same handle and the same framing behaviour as ./splat, so a
+// catalogue can switch a product between a captured splat and a vendor mesh by changing one word.
+// That symmetry is the point: retailers already hold glTF for a slice of their catalogue, and
+// rendering those unchanged is a far stronger claim than "re-capture everything".
+//
+// Requires `three` as a peer, and resolves GLTFLoader from `three/addons/`. That mapping is
+// already mandatory for anyone using ./splat (Spark reaches into three/addons internally), so
+// this adds no new requirement — but on a bare importmap it must be declared:
+//
+//   "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.
+
+import * as THREE from 'three';
+import { EyeCamera, EdgeFeather } from './inline3d-three.js';
+import { SceneViewer } from './inline3d-viewer.js';
+
+/** Cached across calls so a grid of models resolves the loader module once. */
+let _GLTFLoader = null;
+
+async function resolveLoader(injected) {
+  if (injected) return injected;
+  if (!_GLTFLoader) {
+    const mod = await import('three/addons/loaders/GLTFLoader.js');
+    _GLTFLoader = mod.GLTFLoader;
+  }
+  return _GLTFLoader;
+}
+
+/**
+ * Load a glTF/GLB into an inline-3D window.
+ *
+ * @param {object} wall  the manager from createInline3D(), supported or not.
+ * @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 {unknown} [opts.GLTFLoader]  hand in the class instead of resolving `three/addons/`.
+ * @returns {object} the same handle shape as addSplat: a TileHandle plus `viewer`, `model`,
+ *          `setPose`, `resetPose`, `frame`, and `ready`.
+ */
+export function addModel(wall, canvas, src, opts = {}) {
+  const {
+    virtualDisplayHeight = 0.24,
+    frame = null,
+    idleSpin = 8,
+    orbit = true,
+    fit = 'contain',
+    margin = 0.8,
+    depthLimit = 4.0,
+    fitSweep = true,
+    renderScale = 1,
+    feather = 0,
+    environment = 'studio',
+    envMap = null,
+    GLTFLoader: injectedLoader = null,
+    observe,
+  } = opts;
+
+  const viewer = new SceneViewer(THREE, canvas, {
+    virtualDisplayHeight,
+    fit,
+    margin,
+    depthLimit,
+    fitSweep,
+    orbit,
+    idleSpin,
+    renderScale,
+    feather,
+  }).useEyeCamera(EyeCamera, EdgeFeather);
+
+  if (envMap) viewer.scene.environment = envMap;
+  else if (environment === 'studio') addStudioLights(viewer.scene);
+
+  const out = {
+    viewer,
+    model: null,
+    frame: null,
+    setPose: (p) => viewer.setPose(p),
+    resetPose: () => viewer.resetPose(),
+    remove() {
+      handle?.remove();
+      viewer.dispose();
+      if (out.model) disposeTree(out.model);
+    },
+    exclude: (el) => handle?.exclude(el),
+    unexclude: (el) => handle?.unexclude(el),
+  };
+
+  // Window first, content when it lands — same reasoning as ./splat: a grid should not appear
+  // one tile at a time in download order.
+  let handle = null;
+  if (wall && wall.supported) {
+    handle = wall.addScene(canvas, viewer.onFrame, {
+      virtualDisplayHeight,
+      ...(observe ? { observe } : {}),
+    });
+  } else {
+    viewer.startMono();
+  }
+
+  out.ready = (async () => {
+    const Loader = await resolveLoader(injectedLoader);
+    const gltf = await new Loader().loadAsync(src);
+    out.model = gltf.scene;
+    viewer.content.add(gltf.scene);
+
+    // Meshes have exact bounds, so unlike a splat there is nothing to be robust ABOUT: no
+    // percentile trim, no flood-fill, no sidecar needed. Box3 is the whole story.
+    const bounds = frame || boundsOf(gltf.scene);
+    if (bounds) {
+      out.frame = bounds;
+      viewer.fitTo(bounds.center, bounds.extent);
+    }
+    return out;
+  })().catch((err) => {
+    console.warn('[inline3d/model] failed to load', src, err);
+    throw err;
+  });
+
+  return out;
+}
+
+/** Exact model-space bounds of an object tree. */
+function boundsOf(object3d) {
+  const box = new THREE.Box3().setFromObject(object3d);
+  if (!isFinite(box.min.x) || box.isEmpty()) return null;
+  const c = box.getCenter(new THREE.Vector3());
+  const e = box.getSize(new THREE.Vector3());
+  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)] };
+}
+
+/**
+ * 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
+ * several on a page.
+ */
+function addStudioLights(scene) {
+  const key = new THREE.DirectionalLight(0xffffff, 2.2);
+  key.position.set(1, 1.4, 1.6);
+  const fill = new THREE.DirectionalLight(0xffffff, 0.7);
+  fill.position.set(-1.4, 0.4, 0.8);
+  const rim = new THREE.DirectionalLight(0xffffff, 1.0);
+  rim.position.set(-0.4, 0.8, -1.6);
+  scene.add(key, fill, rim, new THREE.HemisphereLight(0xffffff, 0x444444, 0.6));
+}
+
+function disposeTree(root) {
+  root.traverse((o) => {
+    o.geometry?.dispose?.();
+    const m = o.material;
+    if (Array.isArray(m)) m.forEach((x) => x?.dispose?.());
+    else m?.dispose?.();
+  });
+}