@displayxr/inline3d 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,161 @@ 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.4.0 — 2026-09-06
+
+### Added
+
+- **Display modes — the page can read what the panel IS, and ask it to change.** Until now a page
+  could describe its own framing (a view rig) but knew nothing about the display it was framing
+  *for*: not its size in metres, not its pixel count, not which of the runtime's rendering modes it
+  was in, and it had no way to ask for a different one. Three pass-throughs close that:
+  **`getDisplayInfo()`** (physical size, pixel size, recommended view scale; `null` where there is
+  no glasses-free display), **`getRenderingModes()`** (every mode the runtime can put the display
+  in — view count, tile grid, per-view pixels, `hardwareDisplay3D`, `isActive`, `isRequestable`)
+  and **`requestRenderingMode(i)`**. They sit on the **`createInline3D()` result** — the panel is
+  the document's, not a tile's — and under the same names on every tile handle, routed to whichever
+  window currently holds a live layer. Gate the group with
+  **`inline3dDisplayModesSupported()`**, which requires all three methods on
+  `XRDisplayLayer.prototype` — a browser shipping half the set is one mid-implementation, and
+  calling it supported would surface as a `not a function` inside a click handler.
+  *(core tier — additive)*
+
+- **The 2D/3D hardware state is a consequence of the mode, not a control.** There is deliberately
+  **no page-facing request** for it. Asking for a mode with `viewCount === 1` puts the panel in its
+  2D state and the browser reports that mode active — the runtime carries on weaving the same fixed
+  two-view atlas — and asking for the 2-view mode puts it back. Tying the two together makes the
+  one bad state (a flat panel showing a stereo atlas, i.e. a blurry double image rather than 2D)
+  unreachable. **`requestDisplayMode('2d'|'3d')` is gone**, and so is every mention of a "lens".
+
+- **The SDK collapses the stereo rig automatically.** When a 1-view mode goes **active** every
+  window's `ipdFactor`/`parallaxFactor` is pushed to 0 (both eyes render from one place), and a
+  2-view mode going active restores them. This is driven by the `renderingmodechange` event — plus
+  the first `getRenderingModes()` read, so a page that OPENS with the panel already flat is
+  collapsed too — and **not** by the request. So it happens however the mode changed (this page,
+  another one, the shell), the page's own render loop is untouched, and **a refused request changes
+  nothing in either direction**, which is now structural rather than a rollback.
+
+  **The restore is exact, and that is a design property, not luck.** The flattening is a *copy*
+  pushed at the layer — a page driving a rig every frame reuses one descriptor object, so zeroing
+  it in place would write the flattening into the page's own state and the restore would restore
+  0. So each window keeps what the page asked for, untouched, and the flat rig is derived on the
+  way out. That latch also means a per-frame `setViewRig` loop cannot walk the page out of 2D, a
+  lazy tile that scrolls away and rebuilds its layer comes back flat rather than in 3D, and a
+  window that never set a rig at all is flattened (and restored) via the exact rig equivalent of
+  its `virtualDisplayHeight`. *(core tier — additive)*
+
+- **`setStereoEnabled(bool)` is now SUGAR, and only sugar** — `false` requests the first mode with
+  `viewCount === 1 && isRequestable`, `true` the first with `viewCount === 2 && isRequestable`. It
+  touches neither the hardware state (nothing can) nor the rig (the event does that). It rejects
+  rather than inventing a mode when the panel lists none. *(core tier — behaviour change on an
+  unreleased API)*
+
+- **`on(type, cb)` / `off(type, cb)`** — the two events, which fire on the **XRSession** and not on
+  the layer, re-emitted on the wall and on every handle: `renderingmodechange`
+  `{type, modeIndex, viewCount, mode, detail}` and `hardwaredisplaystatechange`
+  `{type, state:'2d'|'3d', detail}`. `on` returns an unsubscribe function;
+  **`onDisplayModeChange(cb)`** remains as the both-events-one-callback shape.
+  `wall.hardwareDisplayState`, `wall.activeMode` and `wall.stereoCollapsed` expose the last
+  **reported** state — never the last requested one. *(core tier — additive)*
+
+- **Undock — lift a window's asset into a floating native viewer over the desktop.**
+  **`wall.undock`** is `{model, splat}` on a browser with `XRDisplayLayer.undock` and **`null`** on
+  one without (plain Chrome, or an older DisplayXR browser) — that null is what a page branches on;
+  **`wall.refreshUndock()`** re-reads it, **`inline3dUndockSupported()`** is the sync probe. The
+  action is **`await undock(element, {src, type, env?, pose?, margin?, title?})`** (new module
+  `js/inline3d-undock.js`, re-exported from the main entry): API-first through `layer.undock()`,
+  falling back to the `displayxr-view:` OS protocol (hidden-iframe navigation, Chrome's one-time
+  "Open DisplayXR…?" prompt) where the layer method is absent. **Call it synchronously inside the
+  click** — both paths need the transient activation. Resolves to `{ended, viewer, detached}`;
+  rejects with an Error named `not-installed` | `src-not-allowed` | `no-activation` | `busy`.
+  *(core tier — additive)*
+
+- **[`samples/display-modes/`](samples/display-modes/)** — the whole surface on one page: the
+  `getDisplayInfo()` fields, the `getRenderingModes()` table with the active row marked, a request
+  button on every requestable row (`viewCount` 1 **or** 2) and the rows needing more than two views
+  greyed with the reason, one `setStereoEnabled` convenience button, a **read-only** hardware
+  display state badge fed by the event, and a live event log. Every action prints a greppable
+  `[display-modes] …` line so a harness can drive it from the console.
+
+### Notes
+
+- **Advisory scales.** `viewScaleX/Y` and `recommendedViewScaleX/Y` are what the runtime would like
+  the per-view resolution to be. The browser cannot resize a page's canvas, so nothing applies them
+  for you — a page honours them by sizing its own backing store. Ignoring them costs sharpness or
+  fill rate, never correctness.
+- **The browser is fixed at two views.** No view synthesis exists anywhere in this stack, so a mode
+  needing MORE than two is listed (the panel really can do it) and refused. Show those rows; mark
+  them. A **one**-view mode is requestable — the browser still submits two views and the runtime
+  still weaves them; it is the panel that goes flat.
+
+## 1.3.0 — 2026-09-04
+
+### Added
+
+- **View rigs — the page can hand the runtime its own CAMERA, not just a virtual-display height.**
+  Every inline-3D frame is located against a *view rig*, and until now there was exactly one: a
+  display rig with an identity pose whose only knob was `virtualDisplayHeight`. That is the right
+  model for a portal — the canvas is a window onto a scene authored to fit it — and the wrong one
+  for a scene that owns a camera. An orbit, a walkthrough, a game has a pose and a field of view
+  already; it does not want to be told where the eyes are, it wants its own frustum perturbed by
+  them. That could not be expressed at all, so those pages either fought the display rig or
+  re-derived stereo themselves.
+
+  `handle.setViewRig(rig)` and `addScene`'s `viewRig` option send the whole descriptor:
+  `{type:'display'|'camera', position, orientation, virtualDisplayHeight, ipdFactor,
+  parallaxFactor, perspectiveFactor, convergenceDiopters, verticalFov, metersToVirtual}`. A rig
+  applies per-locate, so animating one is just sending new values each frame — nothing to tween,
+  nothing to tear down. **No projection math lands in the SDK**: it fills in a descriptor and the
+  off-axis (Kooima) frustum stays in the runtime, which is the same code the native apps consume.
+  *(core tier — additive)*
+
+- **`inline3dViewRigSupported()`**, and a fallback that actually falls back. The gate reads a
+  capability (`XRDisplayLayer.prototype.setViewRig` being present), never a version or UA string.
+  Without it `setViewRig()` warns once and returns `false` while the window keeps weaving — so a
+  page that merely wants the extra control where it exists can call it unconditionally. And a
+  `viewRig` is only put in the layer init on a browser that *has* rigs: an older one would take
+  the init, find no member it recognised, and drop to its **own** default height, so passing a
+  camera rig alongside a `virtualDisplayHeight` now genuinely names the older browser's framing.
+  *(core tier — additive)*
+
+- **`cameraRigFromCamera(THREE, camera, opts)` and `displayRig(opts)`** in
+  `@displayxr/inline3d/three` — descriptor builders, both accepting an `out` object so a per-frame
+  call allocates nothing. `cameraRigFromCamera` decomposes the pose from `matrixWorld` rather than
+  reading `.position`/`.quaternion` (those are local, and an app camera parented under a dolly —
+  the usual way to build an orbit — would otherwise report a pose in the wrong space), converts
+  three's degrees to the descriptor's radians, and turns a convergence *distance* into diopters so
+  "infinity" is a finite `0`. *(core tier — additive)*
+
+- **`EyeCamera.setLocalFromView(view)` / `setLocalFromMatrices(proj, transform)`, for the attach
+  pattern.** The browser locates views **before** the page's rAF, so a rig set during frame N
+  drives the views delivered in frame N+1. On a slider that is invisible; on a camera moving under
+  the pointer it reads as a soft, swimming misalignment. The fix is not prediction: send an
+  identity-posed camera rig and parent the eye cameras under the app camera, and three's scene
+  graph composes *this* frame's world pose with no lag. These setters write `camera.matrix` and
+  leave `matrixWorld` to three's traversal, which is the whole of it — a scene-graph parent, not
+  projection math. `setFromView` (world) is unchanged. *(core tier — additive)*
+
+- **`samples/camera-rig/`** — an orbiting scene on a camera rig, with sliders for FOV, convergence
+  and distance, an `attach` toggle, a live comfort readout, and `C` to cut between the camera rig
+  and a display rig framed to match it at the home angle. `samples/hello-cube/?debug` gains the
+  display rig's knobs; `samples/windows/`'s live scene tile moves to a camera rig in the attach
+  pattern. The comfort rule the readout prints is the runtime's own
+  (`ipdFactor × metersToVirtual × convergenceDiopters × N`, N ≈ 0.5 m): at 1 the viewer's eyes are
+  parallel on infinitely far content and past it they diverge. The SDK documents it and never
+  enforces it — the runtime clamps its own inputs, once, with a warning.
+
+### Docs
+
+- **[`docs/porting-three-js-apps.md`](docs/porting-three-js-apps.md) — porting an existing three.js
+  app (WebXR or plain) to inline 3D.** The rig work above closed the gap that made this guide
+  possible: an app that owns a camera can now hand it over, so "port your WebXR app" stops meaning
+  "re-author it as a portal". The guide is the WebXR→inline-3d mapping table (what each of
+  `isSessionSupported`, `renderer.xr`, `setAnimationLoop`, `XRWebGLLayer`, reference spaces,
+  offset-reference-space locomotion, `ArrayCamera`, controllers and `updateRenderState` becomes, and
+  why), the whole render loop with validate-before-clear and last-good replay, the Spark
+  double-sort, DOM UI over a woven canvas, picking, a hardware checklist, and a 24-item pitfalls
+  register. Linked from the README and from the top of the authoring guide.
+
 ## 1.2.1 — 2026-08-25
 
 ### Fixed

package/README.md

@@ -65,6 +65,19 @@ if (!wall.supported) {
 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.
 
+A scene with its own camera can hand that camera to the runtime instead of being told where the eyes
+are — a **camera rig** — and let eye tracking perturb its frustum:
+
+```js
+import { cameraRigFromCamera } from '@displayxr/inline3d/three';
+const handle = wall.addScene(canvas, onFrame, { viewRig: cameraRigFromCamera(THREE, cam, { convergence: 1.2 }) });
+handle.setViewRig(cameraRigFromCamera(THREE, cam, { convergence: 1.2, out: rig }));  // per frame
+```
+
+No projection math lands in your page or in the SDK — the off-axis frustum stays in the runtime. See
+[view rigs](docs/authoring-inline-3d.md#view-rigs-display-vs-camera) and
+[`samples/camera-rig/`](samples/camera-rig/).
+
 > **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.
@@ -78,6 +91,8 @@ Three.js glue (an off-axis `EyeCamera`) in [`js/inline3d-three.js`](js/inline3d-
 ```
 index.html            landing (Pages entry point)
 samples/
+  camera-rig/         the camera rig — an orbiting scene that sends its OWN camera each frame;
+                      convergence + comfort, the attach pattern, C to A/B a display rig
   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
@@ -95,6 +110,11 @@ js/
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/
   authoring-inline-3d.md   the authoring guide
+  authoring-motion-and-effects.md
+                           motion, transitions and per-eye effects — the half of authoring
+                           that is not the API
+  porting-three-js-apps.md porting an existing three.js app (WebXR or plain) to inline 3D —
+                           the WebXR→inline-3d mapping table and the whole render loop
 ```
 
 ## The inline-3D model (under the SDK)

package/index.d.ts

@@ -13,6 +13,153 @@ export interface TileOptions {
   feather?: number;
 }
 
+/**
+ * A view-rig descriptor — what the runtime locates the eye views against. Two rigs, one shape:
+ *
+ * - **`"display"`** — the canvas is a PORTAL. Its plane is world `z = 0` and the viewer looks
+ *   through it at a virtual display `virtualDisplayHeight` tall. This is the default rig and
+ *   what `SceneOptions.virtualDisplayHeight` is shorthand for (identity pose, all factors 1).
+ * - **`"camera"`** — an APP CAMERA whose frustum eye tracking perturbs. The runtime keeps your
+ *   `verticalFov`, offsets the eyes, and skews each frustum so `convergenceDiopters` lands on
+ *   the zero-disparity plane.
+ *
+ * Every field is optional; the runtime **clamps** an out-of-range value (once, with a warning)
+ * rather than rejecting the rig. A descriptor applies per-locate, so animating one means sending
+ * new values each frame — see {@link TileHandle.setViewRig} for the one-frame latency that
+ * implies. Build one with `cameraRigFromCamera` / `displayRig` from
+ * `@displayxr/inline3d/three`, or by hand.
+ */
+export interface XRViewRigInit {
+  /** `"display"` (portal) or `"camera"` (app camera). */
+  type?: 'display' | 'camera';
+  /** Rig pose in the app's world units (default 0,0,0). */
+  position?: DOMPointInit;
+  /** Rig orientation as a quaternion (default identity). */
+  orientation?: DOMPointInit;
+  /** **Display rig.** Metres of virtual display; `m2v = this / the element's physical height`. */
+  virtualDisplayHeight?: number;
+  /** Eye separation — display rig: relative `[0,1]`; camera rig: absolute `>= 0`. */
+  ipdFactor?: number;
+  /** Head-tracking response — display rig: `[0,1]`; camera rig: absolute `>= 0`. */
+  parallaxFactor?: number;
+  /** **Display rig only**, `[0.1,10]`: exaggerates or flattens the off-axis skew. */
+  perspectiveFactor?: number;
+  /** **Camera rig.** `1 / (convergence distance in world units)`; `0` = infinity. */
+  convergenceDiopters?: number;
+  /** **Camera rig.** The FULL vertical angle, in RADIANS (three's `camera.fov` is degrees). */
+  verticalFov?: number;
+  /** **Camera rig.** Metres → world units on the eye; `0`/unset means 1. */
+  metersToVirtual?: number;
+}
+
+/**
+ * The panel's hardware display state, as reported by `hardwaredisplaystatechange`.
+ *
+ * There is no page-facing request for it: it is a CONSEQUENCE of the active rendering mode —
+ * a `viewCount === 1` mode puts the panel flat, the 2-view mode puts it back.
+ */
+export type XRHardwareDisplayMode = '2d' | '3d';
+
+/**
+ * What the glasses-free display physically is. Resolved by {@link TileHandle.getDisplayInfo};
+ * `null` there means the machine has no such display.
+ *
+ * `recommendedViewScaleX/Y` are **advisory**. The browser cannot resize a page's canvas, so
+ * nothing applies them for you — a page honours them by sizing its own backing store. Ignoring
+ * them costs sharpness or fill rate, never correctness.
+ */
+export interface XRDisplayInfo {
+  displayWidthMeters: number;
+  displayHeightMeters: number;
+  displayPixelWidth: number;
+  displayPixelHeight: number;
+  recommendedViewScaleX: number;
+  recommendedViewScaleY: number;
+}
+
+/**
+ * One rendering mode the DISPLAY can be put in, as reported by the runtime.
+ *
+ * The list is the display's, not the browser's. The DisplayXR Browser renders exactly **two**
+ * views — no view synthesis exists anywhere in the stack — so a mode needing MORE than two is
+ * reported with `isRequestable: false` and {@link TileHandle.requestRenderingMode} refuses it.
+ * Show such rows (they are what the panel can do) but mark them unavailable. A `viewCount === 1`
+ * mode IS requestable: the browser still submits two views and the runtime still weaves them —
+ * it is the PANEL that goes flat, which is how a page reaches the 2D hardware state.
+ */
+export interface XRDisplayRenderingMode {
+  modeIndex: number;
+  name: string;
+  /** @deprecated the browser reports `name`; kept for pages written against the earlier build. */
+  modeName?: string;
+  viewCount: number;
+  /** Per-view render scale the runtime recommends for this mode — advisory, like the display's. */
+  viewScaleX: number;
+  viewScaleY: number;
+  tileColumns: number;
+  tileRows: number;
+  viewWidthPixels: number;
+  viewHeightPixels: number;
+  /** True for a glasses-free 3D mode; false for a flat one. */
+  hardwareDisplay3D: boolean;
+  isActive: boolean;
+  /** False when the browser cannot drive it — in practice, `viewCount > 2`. */
+  isRequestable: boolean;
+}
+
+/** A rendering mode went active. Re-emitted on the wall and on every tile handle. */
+export interface RenderingModeChange {
+  type: 'renderingmodechange';
+  /** The mode now active, or -1 if the browser named none and the list could not be read. */
+  modeIndex: number;
+  /** Its view count — the thing the automatic rig collapse turns on. Null if unknown. */
+  viewCount: number | null;
+  /** The full mode row, when it could be read back. */
+  mode: XRDisplayRenderingMode | null;
+  /** The browser's own event payload, unreshaped. */
+  detail: unknown;
+}
+
+/** The panel's hardware display state changed. */
+export interface HardwareDisplayStateChange {
+  type: 'hardwaredisplaystatechange';
+  state: XRHardwareDisplayMode | null;
+  detail: unknown;
+}
+
+export type DisplayModeChange = RenderingModeChange | HardwareDisplayStateChange;
+
+/** What a page may lift into the floating native viewer. `null` = no `XRDisplayLayer.undock`. */
+export interface UndockCapabilities {
+  model: boolean;
+  splat: boolean;
+}
+
+export interface UndockOptions {
+  /** Absolute https URL (or http on loopback) of the asset the NATIVE viewer loads. */
+  src: string;
+  type: 'model' | 'splat';
+  /** Lighting the page rendered with, so the viewer can match it. */
+  env?: 'room' | 'studio' | 'sky' | 'none';
+  /** The angle the page opened the asset at, so the undocked view opens at the same one. */
+  pose?: { yaw: number; pitch?: number; zoom?: number };
+  /** The page's fit margin, when it overrides the default. */
+  margin?: number;
+  title?: string;
+}
+
+export interface UndockHandle {
+  /**
+   * Resolves when the viewer exits. On the protocol FALLBACK it resolves immediately and
+   * `detached` is true — a protocol launch is fire-and-forget and the page never hears back.
+   */
+  ended: Promise<void>;
+  viewer: 'model' | 'splat';
+  detached: boolean;
+  /** The `displayxr-view:` URL, on the fallback path only. */
+  url?: string;
+}
+
 /** Extra options for {@link Inline3D.addScene}. */
 export interface SceneOptions extends TileOptions {
   /**
@@ -21,6 +168,15 @@ export interface SceneOptions extends TileOptions {
    * and render the reported views as-is. Halving it doubles how much of the window an object fills.
    */
   virtualDisplayHeight?: number;
+  /**
+   * A full {@link XRViewRigInit} instead of the scalar height — a posed display rig, or a camera
+   * rig. **Supersedes `virtualDisplayHeight`** (which is one particular display rig); passing
+   * both warns once and the rig wins **where rigs are supported** — which is the one reason to
+   * pass the pair deliberately, since a browser without {@link inline3dViewRigSupported} then
+   * falls back to the height you named rather than to its own default. The window weaves either
+   * way. Replaceable per frame with {@link TileHandle.setViewRig}.
+   */
+  viewRig?: XRViewRigInit;
   /** Element whose visibility drives the lazy create/close lifecycle (defaults to the canvas). */
   observe?: Element;
 }
@@ -52,6 +208,78 @@ export interface TileHandle {
    * @deprecated See {@link TileHandle.exclude} — no-op on browsers with draw-order occlusion.
    */
   unexclude(el: Element): void;
+  /**
+   * Replace this window's view rig. Cheap enough to call every frame — a rig applies per-locate,
+   * so animating one means sending new values, not tweening anything.
+   *
+   * Returns whether the rig reached a **live** layer. `false` means it was stored and will build
+   * the next one (a window scrolled away in lazy mode), or that the browser has no rig support
+   * ({@link inline3dViewRigSupported}) — in which case it warns once and the window keeps
+   * weaving on the runtime's default display rig.
+   *
+   * **One frame of lag, by construction.** The browser locates views *before* the page's rAF, so
+   * a rig set during frame N drives the views delivered in frame N+1. Invisible for a slider or
+   * a settled camera; not for a camera that moves with the pointer — for that, send an
+   * identity-posed camera rig and parent your eye cameras under the app camera
+   * (`cameraRigFromCamera(THREE, cam, { attach: true })` + `EyeCamera.setLocalFromView`), so the
+   * scene graph supplies this frame's world pose with no lag at all.
+   *
+   * While a `viewCount === 1` mode is active the rig is stored **as given** and pushed **flat**
+   * (a copy with `ipdFactor`/`parallaxFactor` at 0), so a page driving a rig every frame cannot
+   * walk out of 2D, and the 2-view mode going active restores exactly this rig.
+   */
+  setViewRig(rig: XRViewRigInit): boolean;
+  /**
+   * The panel this window weaves on, or `null` where there is no glasses-free display.
+   *
+   * Rejects with an `Error` on a browser without the display-mode API
+   * ({@link inline3dDisplayModesSupported}) or while this window has no live layer (lazy mode,
+   * tile off screen).
+   */
+  getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /**
+   * Ask the runtime to switch the display to `modeIndex`. A thin pass-through — it resolves and
+   * rejects exactly as the browser does.
+   *
+   * Rejects with a `TypeError` for a mode whose `viewCount > 2` (the browser is fixed at two
+   * views) or an unknown index — the browser raises those synchronously, and this pass-through
+   * turns them into rejections so one `.catch()` covers every failure — and with a
+   * `NotSupportedError` `DOMException` when the request was not forwardable. Success is signalled
+   * by the session's `renderingmodechange` event, not by this promise.
+   *
+   * A `viewCount === 1` mode is requestable and is how a page goes flat.
+   */
+  requestRenderingMode(modeIndex: number): Promise<void>;
+  /**
+   * SUGAR over {@link TileHandle.requestRenderingMode}: `false` requests the first mode with
+   * `viewCount === 1 && isRequestable`, `true` the first with `viewCount === 2 && isRequestable`.
+   * It never touches the hardware display state directly (there is no such call) and never
+   * touches your rig.
+   *
+   * **The rig collapse is not part of this call.** When a 1-view mode actually goes ACTIVE the
+   * SDK zeroes every window's `ipdFactor`/`parallaxFactor` on the way to the layer and restores
+   * them when a 2-view mode does — driven by `renderingmodechange`, so it happens however the
+   * mode changed, and a **refused request changes nothing in either direction**. The flattening
+   * is a copy pushed at the layer, never a write into your descriptor, so the restore is literally
+   * the rig you last set — and it survives a per-frame `setViewRig` loop, a lazy tile rebuilding
+   * its layer, and a window that never set a rig at all.
+   *
+   * Rejects with an `Error` when no such mode is listed, otherwise as `requestRenderingMode` does.
+   */
+  setStereoEnabled(enabled: boolean): Promise<boolean>;
+  /** Listen for one display event, re-emitted on this handle. Returns an unsubscribe function. */
+  on(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): () => void;
+  on(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): () => void;
+  /** Drop a listener registered with {@link TileHandle.on}. */
+  off(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): void;
+  off(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): void;
+  /**
+   * Both display events through one callback — the older shape, still supported. Returns an
+   * unsubscribe function; inert (a no-op unsubscribe) on a browser without the API.
+   */
+  onDisplayModeChange(cb: (e: DisplayModeChange) => void): () => void;
   /**
    * Per-window frame counters, for diagnosing the load-induced mono fallback.
    *
@@ -76,6 +304,37 @@ export interface Inline3D {
   /** Number of currently-active (weaving) windows. */
   readonly liveCount: number;
 
+  // The panel is the DOCUMENT's, not a tile's, so the display API lives here; the same names are
+  // on every tile handle, routed to whichever window currently holds a live layer.
+
+  /** The panel, or `null` where there is no glasses-free display. See {@link TileHandle.getDisplayInfo}. */
+  getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /** Switch the display to `modeIndex`. See {@link TileHandle.requestRenderingMode}. */
+  requestRenderingMode(modeIndex: number): Promise<void>;
+  /** Sugar: `false` -> a 1-view mode, `true` -> the 2-view mode. See {@link TileHandle.setStereoEnabled}. */
+  setStereoEnabled(enabled: boolean): Promise<boolean>;
+  on(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): () => void;
+  on(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): () => void;
+  off(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): void;
+  off(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): void;
+  /** As last REPORTED by `hardwaredisplaystatechange` — never what was last requested. */
+  readonly hardwareDisplayState: XRHardwareDisplayMode | null;
+  /** The active mode as last read/reported. `viewCount: 0` means "not read yet". */
+  readonly activeMode: { modeIndex: number; viewCount: number };
+  /** True while the SDK is holding every window's rig flat because a 1-view mode is active. */
+  readonly stereoCollapsed: boolean;
+
+  /**
+   * What this build can lift into the floating native viewer, or `null` on a browser with no
+   * `XRDisplayLayer.undock` — that null is what a page branches on. Read off the first live
+   * layer (`layer.getUndockCapabilities()`); `{model:false, splat:false}` is the pre-read value.
+   */
+  readonly undock: UndockCapabilities | null;
+  /** Re-read {@link Inline3D.undock} off a live layer. */
+  refreshUndock(): Promise<UndockCapabilities | null>;
+
   /** Weave a still side-by-side 3D photo from a URL or decoded image source. */
   addImage(
     canvas: HTMLCanvasElement,
@@ -194,6 +453,61 @@ export function inline3dOverlaySupported(): boolean;
  */
 export function inline3dOcclusionByDrawOrder(): boolean;
 
+/**
+ * True when this browser accepts a full {@link XRViewRigInit} — {@link TileHandle.setViewRig} and
+ * {@link SceneOptions.viewRig}, i.e. a posed display rig or a camera rig, instead of only the
+ * scalar `virtualDisplayHeight`. Sync + cheap; implies {@link inline3DAvailable}.
+ *
+ * Reads a capability (the presence of `XRDisplayLayer.setViewRig`), never a version or UA string,
+ * and is `false` on every browser that predates the rig API — where `virtualDisplayHeight` still
+ * works. Branch on it only if a camera rig is load-bearing for your page: `setViewRig` no-ops
+ * (warning once) rather than throwing, so a page that merely wants the extra control where it
+ * exists can call it unconditionally.
+ */
+export function inline3dViewRigSupported(): boolean;
+
+/**
+ * True when this browser exposes the DISPLAY-MODE API — {@link TileHandle.getDisplayInfo},
+ * {@link TileHandle.getRenderingModes} and {@link TileHandle.requestRenderingMode}. Sync + cheap;
+ * implies {@link inline3DAvailable}.
+ *
+ * Reads a capability (all three methods present on `XRDisplayLayer.prototype`), never a version or
+ * UA string, and demands all three: a browser shipping half the set is one mid-implementation.
+ * Everything the API drives is optional enhancement, so branch on this only to decide whether to
+ * show display controls — the handle methods reject with a clear `Error` rather than throwing at
+ * import or create time.
+ */
+export function inline3dDisplayModesSupported(): boolean;
+
+/**
+ * True when this browser can undock through `XRDisplayLayer.undock()` — i.e. without the
+ * `displayxr-view:` protocol prompt the fallback needs. A page does not have to branch on it to
+ * undock (the helper falls back on its own); it is the probe for whether {@link Inline3D.undock}
+ * carries capabilities.
+ */
+export function inline3dUndockSupported(): boolean;
+
+/**
+ * Undock `target`'s asset into the floating native viewer over the desktop.
+ *
+ * **Call it synchronously inside the click.** Both paths need the transient user activation — the
+ * API path to be allowed at all, the fallback to get Chrome's protocol dialog — and an `await`
+ * before this call spends it.
+ *
+ * Rejects with an `Error` whose `name` is `'not-installed'`, `'src-not-allowed'`,
+ * `'no-activation'` or `'busy'`.
+ */
+export function undock(target: Element, opts: UndockOptions): Promise<UndockHandle>;
+
+/** True where a native DisplayXR viewer can exist at all (the viewers are Windows-only today). */
+export function undockAvailable(): boolean;
+
+/** The `displayxr-view:` URL the fallback path navigates to — exported for logging and tests. */
+export function undockUrl(el: Element, opts: UndockOptions): string;
+
+/** An element's rect in physical screen pixels — where the native viewer places its window. */
+export function tileScreenRect(el: Element): { x: number; y: number; w: number; h: number; dpr: number };
+
 /** Open the page's inline-3D session and return a manager you add windows to. */
 export function createInline3D(
   opts?: CreateInline3DOptions,
@@ -229,5 +543,26 @@ export interface XRDisplayLayer {
    * browser shipped so far — the SDK treats absent as `false` and runs the legacy path.
    */
   readonly occlusionByDrawOrder?: boolean;
+  /**
+   * Replace the rig the runtime locates this layer's views against. Optional because it is
+   * absent on browsers that predate the rig API — its PRESENCE on the prototype is the
+   * capability signal ({@link inline3dViewRigSupported}), which is why the browser exposes it as
+   * a method: a Blink IDL attribute getter throws `Illegal invocation` when read off a prototype
+   * (see {@link XRDisplayLayer.occlusionByDrawOrder}), so an attribute could not be probed at
+   * all on the browser that has it.
+   */
+  setViewRig?(rig: XRViewRigInit): void;
+  /**
+   * The display-mode API. All three optional for the same reason as `setViewRig`: their presence
+   * on the prototype IS the capability signal ({@link inline3dDisplayModesSupported}), and the
+   * SDK demands all three before treating the browser as supporting any of them.
+   */
+  getDisplayInfo?(): Promise<XRDisplayInfo | null>;
+  getRenderingModes?(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /** Throws `TypeError` **synchronously** for `viewCount > 2` or an unknown index. */
+  requestRenderingMode?(modeIndex: number): Promise<void>;
+  /** Undock this layer's asset into the floating native viewer. Optional; same probe rule. */
+  undock?(init: UndockOptions): Promise<unknown>;
+  getUndockCapabilities?(): Promise<UndockCapabilities>;
   close(): void;
 }

package/js/inline3d-model.js

@@ -478,7 +478,7 @@ function boundsOf(object3d) {
  * 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
+ * a dark disc, clear-glass optics 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