@displayxr/inline3d 0.0.1 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# 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.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

@@ -1,16 +1,108 @@
-# @displayxr/inline3d — 0.0.1 is a bootstrap placeholder
+# displayxr-web
 
-**Do not install this version.** It contains no code.
+Inline-3D **web samples** and a small JS SDK for the
+[DisplayXR Browser](https://github.com/DisplayXR/displayxr-browser) — the DisplayXR analog of
+[`immersive-web/webxr-samples`](https://github.com/immersive-web/webxr-samples). This is the canonical
+repo web developers clone to build glasses-free 3D pages, and the site the browser navigates to for the
+live demos.
 
-npm attaches a [Trusted Publisher](https://docs.npmjs.com/trusted-publishers)
-to an *existing* package, so this empty `0.0.1` exists only to reserve the name
-long enough for that link to be configured. Every real release is published
-from CI via OIDC, with provenance, and no npm token exists anywhere.
+**▶ See it live:** <https://displayxr.github.io/displayxr-web/> — open in the
+[DisplayXR Browser](https://github.com/DisplayXR/displayxr-browser/releases) on DisplayXR hardware for
+glasses-free 3D; in any other browser the pages render as a normal 2D fallback, so they're safe to view
+anywhere.
 
-Install the real SDK instead:
+## Install
+
+The SDK is published as **[`@displayxr/inline3d`](https://www.npmjs.com/package/@displayxr/inline3d)**
+(dependency-free ESM, ships its own TypeScript types):
 
 ```sh
 npm install @displayxr/inline3d
 ```
 
-Source and docs: https://github.com/DisplayXR/displayxr-web
+```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` 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).
+
+## Quick start
+
+One SDK call turns a `<canvas>` into a glasses-free-3D window. Everything degrades to plain 2D on a
+non-DisplayXR browser, so a page is safe to ship anywhere.
+
+```js
+import { createInline3D } from '@displayxr/inline3d';
+
+const wall = await createInline3D();       // opens an inline-3d session (detects support)
+if (!wall.supported) {
+  // Not the DisplayXR Browser (or no 3D display) — your page's normal 2D content shows. Done.
+} else {
+  // Woven, glasses-free 3D. Add content — one call per element:
+  wall.addImage(canvas, 'photo-sbs.png');                  // a still side-by-side 3D photo
+  wall.addVideo(canvas, videoEl);                          // an SBS 3D video
+  wall.addScene(canvas, (views, layer) => { /* render */ });// a live three.js / WebGL stereo scene
+}
+```
+
+The browser weaves each element's stereo pair at its on-screen rect; the surrounding DOM stays flat.
+The runtime batches every visible window into one weave per frame, so it scales to a wall of elements.
+
+> **Detection:** call `createInline3D()` and check `wall.supported` — do **not** gate on
+> `navigator.xr.isSessionSupported('inline-3d')`. That async probe resolves `false` if it runs before the
+> OS weave service has bound (typically at page load), a false-negative that silently drops you to 2D.
+> `createInline3D()` detects by actually acquiring a session, which is authoritative.
+
+Full API + authoring guidance: [`docs/authoring-inline-3d.md`](docs/authoring-inline-3d.md).
+Three.js glue (an off-axis `EyeCamera`) in [`js/inline3d-three.js`](js/inline3d-three.js).
+
+## What's here
+
+```
+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
+```
+
+## The inline-3D model (under the SDK)
+
+If you want the raw WebXR surface the SDK wraps, an inline-3d element:
+
+1. `const session = await navigator.xr.requestSession('inline-3d')` — a sensorless inline session
+   (feature-detect by whether this resolves; falls back to plain 2D).
+2. `const layer = new XRDisplayLayer(session, canvas)` — binds the weave to that element.
+3. Each XR frame: render the scene as a **side-by-side stereo pair** into the canvas, re-projected
+   **off-axis** (asymmetric-frustum / Kooima) from the eye positions the session reports that frame —
+   so moving your head looks *around* the 3D content.
+
+See the [WebXR inline-3D explainer](https://github.com/DisplayXR/displayxr-runtime/blob/main/docs/roadmap/webxr-displayxr-explainer.md).
+
+## Local preview
+
+Any static server, e.g. `python -m http.server 8080`, then open `http://localhost:8080/`.
+(Loading over `file://` is fine for pure-2D, but WebXR requires a **secure context** — use
+`http://localhost` or `https://`.)

package/index.d.ts

@@ -0,0 +1,221 @@
+// Type definitions for @displayxr/inline3d — the DisplayXR inline-3D SDK.
+// Public 1.0 surface. See docs/sdk-stability.md for the semver contract.
+
+/** Options shared by every add*() call. */
+export interface TileOptions {
+  /** Per-eye buffer resolution in px (defaults to the CSS box × devicePixelRatio, dpr capped at 2). */
+  width?: number;
+  /** Per-eye buffer height in px (see `width`). */
+  height?: number;
+  /** Round each eye's corners, in BUFFER px (CSS radii can't cross the packed side-by-side pair). */
+  cornerRadius?: number;
+  /** Fade each eye's outer edges to transparent over this many buffer px. */
+  feather?: number;
+}
+
+/** Extra options for {@link Inline3D.addScene}. */
+export interface SceneOptions extends TileOptions {
+  /**
+   * Metre height of the virtual display this scene is authored for (default 0.24). The runtime
+   * scales the eye poses it reports so the z=0 plane spans a display this tall — author in metres
+   * and render the reported views as-is. Halving it doubles how much of the window an object fills.
+   */
+  virtualDisplayHeight?: number;
+  /** Element whose visibility drives the lazy create/close lifecycle (defaults to the canvas). */
+  observe?: Element;
+}
+
+/** The per-frame render callback passed to {@link Inline3D.addScene}. */
+export type SceneFrameCallback = (
+  views: readonly XRView[],
+  layer: XRDisplayLayer,
+  frame: XRFrame,
+) => void;
+
+/** The handle returned by every add*() call. */
+export interface TileHandle {
+  /** Remove this window: close its weave layer and stop driving it. */
+  remove(): void;
+  /**
+   * 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.
+   *
+   * @deprecated See {@link TileHandle.exclude} — no-op on browsers with draw-order occlusion.
+   */
+  unexclude(el: Element): void;
+}
+
+/** An open inline-3D session you add weaved windows to. Returned by {@link createInline3D}. */
+export interface Inline3D {
+  readonly supported: true;
+  /** The underlying WebXR session. */
+  readonly session: XRSession;
+  /** The reference space the eye poses are reported in (may be null if none could be acquired). */
+  readonly refSpace: XRReferenceSpace | null;
+  /** Number of currently-active (weaving) windows. */
+  readonly liveCount: number;
+
+  /** Weave a still side-by-side 3D photo from a URL or decoded image source. */
+  addImage(
+    canvas: HTMLCanvasElement,
+    source: string | HTMLImageElement | ImageBitmap | HTMLCanvasElement,
+    opts?: TileOptions,
+  ): TileHandle;
+
+  /** Weave a side-by-side 3D video element (re-drawn each decoded frame). */
+  addVideo(
+    canvas: HTMLCanvasElement,
+    video: HTMLVideoElement,
+    opts?: TileOptions,
+  ): TileHandle;
+
+  /**
+   * Weave a live-rendered stereo scene. Your callback receives the two eye views + the layer;
+   * render each `layer.getViewport(view)` into the canvas's SBS backing (three.js: see the
+   * `@displayxr/inline3d/three` helpers).
+   */
+  addScene(
+    canvas: HTMLCanvasElement,
+    onFrame: SceneFrameCallback,
+    opts?: SceneOptions,
+  ): TileHandle;
+
+  /**
+   * 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.
+   *
+   * @deprecated See {@link Inline3D.addGlobalOverlay} — no-op with draw-order occlusion.
+   */
+  removeGlobalOverlay(el: Element): void;
+
+  /** Close the session and remove every window. */
+  close(): void;
+}
+
+/** The shape {@link createInline3D} resolves to when inline-3D is unavailable. */
+export interface Inline3DUnsupported {
+  supported: false;
+  error?: unknown;
+}
+
+/** Options for {@link createInline3D}. */
+export interface CreateInline3DOptions {
+  /** WebXR reference space for the eye poses (default `"viewer"`). */
+  referenceSpace?: string;
+  /**
+   * Create each window's weave layer only while it is (near-)visible and close it when it scrolls
+   * away, so a long wall only pays for what's on screen (default `true`). Set `false` for a single
+   * always-on element.
+   */
+  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}. */
+export interface StartInline3DResult {
+  supported: boolean;
+  /** The manager (present when supported). */
+  wall?: Inline3D;
+  /** The underlying WebXR session (present when supported). */
+  session?: XRSession;
+  /** Close the session (present when supported). */
+  close?: () => void;
+  error?: unknown;
+}
+
+/**
+ * Cheap, synchronous "can this browser even attempt inline-3D?" gate — true only in the DisplayXR
+ * Browser with the feature enabled. Use it to decide page UI up front.
+ */
+export function inline3DAvailable(): boolean;
+
+/**
+ * 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,
+): Promise<Inline3D | Inline3DUnsupported>;
+
+/**
+ * Back-compatible single-scene helper: open a session, weave one canvas, drive a render callback
+ * each frame. Equivalent to `createInline3D({lazy:false})` then `addScene(canvas, onFrame)`.
+ */
+export function startInline3D(
+  canvas: HTMLCanvasElement,
+  opts?: {
+    onFrame?: SceneFrameCallback;
+    referenceSpace?: string;
+    virtualDisplayHeight?: number;
+  },
+): Promise<StartInline3DResult>;
+
+// 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?.();
+  });
+}