@displayxr/inline3d 1.5.1 → 1.6.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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.6.0 — 2026-09-08
+
+Touches the **preview tier** (`./viewer`) and fixes a **documentation error in the core tier**.
+Purely additive to the viewer's API: no framing behaviour changes and no existing option changes
+meaning, so a page that ignores everything below renders identically to 1.5.1.
+
+### Added
+
+- **`SceneViewer` has an output surface** ([#26](https://github.com/DisplayXR/displayxr-web/issues/26)).
+  It could frame, scale and orbit a subject but never say where the subject ended up, so pages
+  that needed that — a pop-out readout, a depth-budget check, a HUD that must clear the model —
+  had to read `_pivot`, `_fitScale` and `_zoom`. Three additions replace all of it:
+  - **`getSubjectBounds()`** → `{center, extent, front, back, scale}` in **display metres**, for
+    the pose being drawn. `front` is the surface nearest the viewer (`> 0` = out of the glass),
+    `back` the far side, `scale` the model-unit → metre factor in force (fit × zoom).
+    **Call it per frame.** The orbit rotates the *subject*, so yaw swings its depth into the
+    display's `z`: a page-shaped subject 1 m × 0.02 m is 0.01 m deep face-on and 0.5 m deep
+    turned side-on. Anything measured once at load is correct at yaw 0 and wrong everywhere
+    else — and with `idleSpin` on, yaw 0 is a passing instant. The call allocates one object and
+    does no matrix work.
+  - **`depthOffset`** (get/set) — slides the subject along the depth axis in display metres,
+    `+` toward the viewer. It **translates and never rescales**, so it moves the depth budget
+    without resizing it.
+  - **`getPose({target})`** — the counterpart to `setPose`. Yaw/pitch/zoom are eased, so
+    mid-gesture "what is drawn" and "what it is settling toward" genuinely differ; the default
+    reports the drawn value, `target: true` the destination.
+  - `setPose()` now also accepts `depthOffset`.
+
+### Changed
+
+- **`fitTo()` no longer discards `depthOffset`.** It used to hardcode the pivot's z to 0, so
+  reframing a subject silently threw away where the author had placed it. `resetPose()` clears
+  it, which is where "back to default" belongs. **No effect on any 1.5.x page**: the offset is 0
+  unless something sets it, and 0 is what `fitTo` used to write.
+- `samples/model` reads `getSubjectBounds()` instead of `_fitScale`, and prints its footprint and
+  pop-out **live** — the visible disagreement between that and the static fit numbers is the
+  point, and is why the call is per-frame.
+
+### Fixed
+
+- **The depth axis was documented BACKWARDS.** `docs/authoring-inline-3d.md` and the header of
+  `inline3d-three.js` both said "`+z` behind the glass, `−z` in front". It is the other way
+  round: the runtime places the nominal viewer at `z = +0.6 m` with the glass at `z = 0`
+  (`dxr_view_math`'s `nomv`), so **`+z` is toward the viewer, out of the glass**. Every mono
+  fallback camera in this repo already sat at `+z` for that reason, so only the prose was wrong —
+  but the prose is what authors code against, and the symptom is a depth control whose labels are
+  inverted. Symmetric subjects hide it completely. New section:
+  [Which way is out](docs/authoring-inline-3d.md#which-way-is-out).
+
 ## 1.5.1 — 2026-09-06
 
 ### Fixed

package/README.md

@@ -65,8 +65,14 @@ 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:
+Most pages want the default — a **display rig**, where the canvas is a portal onto a virtual
+display and the runtime places the eyes. That includes every scene that frames a *subject* (a model
+or splat viewer, an avatar, a product hero) **even when the user orbits it**: rotate the subject,
+not the camera, and the stereo comes out the same for a figurine and an airliner.
+
+A scene whose viewpoint the user *moves through a world* — first person, a walkthrough, a game, a
+map, an editor, a ported VR app — can instead hand its own camera to the runtime and let eye
+tracking perturb that frustum. That is a **camera rig**:
 
 ```js
 import { cameraRigFromCamera } from '@displayxr/inline3d/three';
@@ -104,7 +110,8 @@ 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-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback,
+                      and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)

package/js/inline3d-three.js

@@ -41,8 +41,8 @@
 // are already scaled to your scene by the layer's `virtualDisplayHeight` (see addScene) — the
 // runtime places each eye at eye_physical × (virtualDisplayHeight / element_physical_height),
 // so the z=0 plane spans that virtual display. Author your scene in metres for a display that
-// tall (0.24 m by default), put focused content at z=0 (positive z behind the glass, negative
-// in front), and render `eye.camera` directly. No per-frame world scaling — that is the whole
+// tall (0.24 m by default), put focused content at z=0 (POSITIVE z is toward the viewer, out
+// of the glass; negative z is behind it), and render `eye.camera` directly. No per-frame world scaling — that is the whole
 // point of using the rig instead of re-deriving it in the app, and it mirrors the native
 // reference apps (cube_handle), which supply one scale number and consume render-ready views.
 //
@@ -167,10 +167,18 @@ function scratch(THREE) {
  * anything here: this function only fills in a descriptor, and every off-axis projection stays
  * in the runtime, where it is the same code the native apps use.
  *
+ * WHICH RIG. Decide by what the USER moves, not by whether you hold a camera. If the user turns
+ * a SUBJECT — a model, a splat, an avatar, a product hero, and yes, an orbit around one — use a
+ * display rig and rotate the subject under a fixed portal: a display rig is scale-invariant, so a
+ * figurine and an airframe get the same stereo. A camera rig is literal (two eyes 63 mm apart at
+ * your camera), so its disparity falls off as baseline / framing distance and a big subject framed
+ * from far away renders FLAT. Use a camera rig for a viewpoint the user moves through a world:
+ * first person, a walkthrough, a game, a map, an editor, a ported VR app.
+ *
  * CONVERGENCE IS THE ONE KNOB TO GET RIGHT. It is the distance at which content sits ON the
  * glass; everything nearer pops out, everything further recedes. Point it at whatever the viewer
- * is meant to be looking at (an orbit target, a hit-tested surface) — for an orbiting camera
- * that is usually just the orbit radius. Left at 0 it means infinity, which puts the entire
+ * is meant to be looking at (the subject's centre, a hit-tested surface) — with a moving camera
+ * that is usually just the distance to it. Left at 0 it means infinity, which puts the entire
  * scene in front of the display and is comfortable for almost nothing.
  *
  * COMFORT. The runtime's rule is `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
@@ -180,6 +188,16 @@ function scratch(THREE) {
  * runtime clamps out-of-range values itself, once, with a warning — but a scene authored in
  * centimetres with a 0.1-unit convergence is the shape of the mistake.
  *
+ * COMFORT IS NOT A DEPTH METER. It bounds where the depth budget SITS (it guards the background
+ * against divergence), not how big the budget is. The budget is
+ * `(baseline / tan(vFov/2)) * (1/z_near - 1/z_far)`, which convergence cancels out of exactly —
+ * convergence slides the scene relative to the glass and never resizes its depth, which is why
+ * ipdFactor/parallaxFactor here are ABSOLUTE rather than scaled by the convergence distance. A
+ * window that weaves but looks FLAT is a budget problem (a 63 mm baseline framing a large subject
+ * from far away) and comfort will report a healthy number while it happens. Do not rescale the
+ * baseline to paper over it: a camera rig needing a scale correction is a scene that wanted a
+ * display rig.
+ *
  * @param {object} THREE  your imported three.js module namespace.
  * @param {object} camera  a THREE.PerspectiveCamera (`.fov` in degrees, `.matrixWorld` current).
  * @param {object} [opts]

package/js/inline3d-viewer.js

@@ -49,6 +49,9 @@ const DEFAULT_DEPTH_LIMIT = 4.0;
 const IDLE_DELAY_MS = 2500;
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+// NaN/Infinity into a transform silently blanks the tile — three propagates it into the
+// matrix and every vertex lands undefined. Reject at the setter instead.
+const finite = (v, fallback) => (typeof v === 'number' && Number.isFinite(v) ? v : fallback);
 
 /**
  * Robust model-space bounds from a flat array of splat/vertex centres.
@@ -220,6 +223,14 @@ export class SceneViewer {
     this._fitScale = 1;
     this._zoom = 1;
     this._targetZoom = 1;
+    // Author-driven slide along the depth axis, display metres, +z toward the viewer. Applied
+    // by _applyTransform, PRESERVED by fitTo, cleared by resetPose. Default 0 means every page
+    // that never touches it is bit-identical to 1.5.x.
+    this._depthOffset = 0;
+    // Subject half-extents in MODEL units, from the last fitTo. getSubjectBounds turns these
+    // into a display-space box under the live pose; without them it would have to re-measure
+    // the content every call.
+    this._subjectHalf = [0, 0, 0];
     this._yaw = 0;
     this._pitch = 0;
     this._targetYaw = 0;
@@ -278,10 +289,12 @@ export class SceneViewer {
     const e = Array.isArray(extent) ? extent : [extent.x, extent.y, extent.z];
 
     this._centering.position.set(-c[0], -c[1], -c[2]);
+    // Recorded for getSubjectBounds(). Model units; the fit scale is applied at read time so a
+    // later zoom or orbit needs no re-measure.
+    this._subjectHalf = [Math.abs(e[0]) / 2, Math.abs(e[1]) / 2, Math.abs(e[2]) / 2];
 
     if (this.fit === 'none') {
       this._fitScale = 1;
-      this._pivot.position.z = 0;
     } else {
       const box = this.canvas.getBoundingClientRect();
       const aspect = box.height > 0 ? box.width / box.height : 1;
@@ -325,8 +338,9 @@ export class SceneViewer {
       //
       // A biased variant that slid the subject behind the glass was tried and dropped: on
       // hardware it read WORSE, and it moved content the wrong way besides. Do not re-add it
-      // without a hardware comparison.
-      this._pivot.position.z = 0;
+      // without a hardware comparison. `depthOffset` is NOT that variant: it is an author
+      // asking for a specific placement, and it stays 0 unless someone sets it — so the
+      // default framing this comment defends is unchanged.
 
       // Backstop only: something pathologically deep still gets scaled down.
       const sz = (this.depthLimit * vH) / ez;
@@ -341,19 +355,115 @@ export class SceneViewer {
     this.monoCamera.lookAt(0, 0, 0);
   }
 
-  /** Set the orbit pose directly. Angles in degrees; zoom is a multiplier on the fit scale. */
-  setPose({ yaw, pitch, zoom } = {}) {
+  /**
+   * Set the pose directly. Angles in degrees; zoom is a multiplier on the fit scale;
+   * depthOffset is display metres along the depth axis (+ toward the viewer).
+   *
+   * This SNAPS — it writes the eased value and its target together. The easing in _tick exists
+   * for input, not for programmatic placement.
+   */
+  setPose({ yaw, pitch, zoom, depthOffset } = {}) {
     if (yaw !== undefined) this._targetYaw = this._yaw = yaw;
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
     if (zoom !== undefined) this._targetZoom = this._zoom = clamp(zoom, ZOOM_MIN, ZOOM_MAX);
+    if (depthOffset !== undefined) this._depthOffset = finite(depthOffset, this._depthOffset);
+    this._applyTransform();
+  }
+
+  /**
+   * What the pose IS right now — the counterpart to setPose, and the reason an app no longer
+   * has to read `_zoom` to know where its subject sits.
+   *
+   * `_tick` eases yaw/pitch/zoom toward their targets, so during an orbit or a wheel-zoom the
+   * two answers genuinely differ and consumers want different ones: a readout that describes
+   * what is ON SCREEN wants the eased value (the default), while "remember this view" wants
+   * the target it is settling on. depthOffset never eases, so both agree.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.target=false]  report the values being eased TOWARD.
+   * @returns {{yaw:number, pitch:number, zoom:number, depthOffset:number}} degrees / multiplier
+   *          / metres.
+   */
+  getPose({ target = false } = {}) {
+    return {
+      yaw: target ? this._targetYaw : this._yaw,
+      pitch: target ? this._targetPitch : this._pitch,
+      zoom: target ? this._targetZoom : this._zoom,
+      depthOffset: this._depthOffset,
+    };
+  }
+
+  /**
+   * Where the subject actually IS, in display metres, under the pose being drawn.
+   *
+   * This is the viewer's output surface. Everything a page needs in order to reason about
+   * depth — a pop-out readout, a depth-budget check, a HUD that must clear the subject — is a
+   * function of this box, and none of it is derivable from the outside: the fit scale, the
+   * live zoom and the orbit are all viewer state.
+   *
+   * THE ORBIT IS WHY THIS CANNOT BE CACHED. The pivot rotates about Y (and X), so yaw swings
+   * the subject's DEPTH into the display's z and its width out of it. A page that measures its
+   * model once at load and scales by zoom is correct at yaw 0 and wrong everywhere else — and
+   * with `idleSpin` on, yaw 0 is a passing instant. Call this per frame; it allocates one
+   * object and does no matrix work.
+   *
+   * SIGNS. Display space puts the viewer at +z and the glass at z = 0, so `front` (the surface
+   * nearest the viewer) is the LARGER z and a positive `front` means the subject pops out of
+   * the glass. `back` is the far side; a negative `back` is depth behind the glass. See
+   * docs/authoring-inline-3d.md § "Which way is out".
+   *
+   * The box is axis-aligned in display space and encloses the oriented subject — the standard
+   * conservative bound, so it never under-reports pop-out.
+   *
+   * @returns {{center:{x:number,y:number,z:number}, extent:{x:number,y:number,z:number},
+   *           front:number, back:number, scale:number}} metres, except `scale` which is the
+   *          model-unit → metre factor currently in force (fit x zoom).
+   */
+  getSubjectBounds() {
+    const s = this._fitScale * this._zoom;
+    const [hx, hy, hz] = this._subjectHalf;
+    const p = (this._pitch * Math.PI) / 180;
+    const y = (this._yaw * Math.PI) / 180;
+    // Rows of R = Rx(pitch) . Ry(yaw) — the same product _applyTransform builds, and the same
+    // order, which is the part that matters (see its comment on why 'XYZ' and not 'YXZ').
+    // |row| . half gives the AABB half-extent along that world axis.
+    const cp = Math.cos(p);
+    const sp = Math.sin(p);
+    const cy = Math.cos(y);
+    const sy = Math.sin(y);
+    const ex = s * (Math.abs(cy) * hx + Math.abs(sy) * hz);
+    const ey = s * (Math.abs(sp * sy) * hx + Math.abs(cp) * hy + Math.abs(sp * cy) * hz);
+    const ez = s * (Math.abs(cp * sy) * hx + Math.abs(sp) * hy + Math.abs(cp * cy) * hz);
+    const cz = this._depthOffset;
+    return {
+      center: { x: 0, y: 0, z: cz },
+      extent: { x: 2 * ex, y: 2 * ey, z: 2 * ez },
+      front: cz + ez,
+      back: cz - ez,
+      scale: s,
+    };
+  }
+
+  /**
+   * Slide the whole subject along the depth axis, display metres, + toward the viewer.
+   *
+   * Survives `fitTo` — a refit reframes the subject without discarding where the author put
+   * it — and is cleared by `resetPose`, which is where "back to default" belongs.
+   */
+  get depthOffset() {
+    return this._depthOffset;
+  }
+
+  set depthOffset(m) {
+    this._depthOffset = finite(m, this._depthOffset);
     this._applyTransform();
   }
 
-  /** Return to the framed default pose. */
+  /** Return to the framed default pose, depth slide included. */
   resetPose() {
-    this.setPose({ yaw: 0, pitch: 0, zoom: 1 });
+    this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
     this._lastInput = now();
   }
 
@@ -625,6 +735,10 @@ export class SceneViewer {
   _applyTransform() {
     const s = this._fitScale * this._zoom;
     this._pivot.scale.setScalar(s);
+    // The depth slide lives here, not in fitTo, so it survives a refit and cannot be left
+    // stale by a code path that forgets it. x/y are never written: the fit centres the subject
+    // on the tile and sliding it sideways is a scene concern, not a viewer one.
+    this._pivot.position.z = this._depthOffset;
     // Order 'XYZ' == R = Rx(pitch) · Ry(yaw), and the order is the whole point.
     //
     // Yaw must act in the subject's OWN frame (spin it on its axis); pitch must act in the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/viewer.d.ts

@@ -38,9 +38,35 @@ export interface SceneViewerOptions {
 }
 
 export interface OrbitPose {
+  /** Degrees about Y. */
   yaw?: number;
+  /** Degrees about X, clamped to `pitchLimit`. */
   pitch?: number;
+  /** Multiplier on the fit scale. */
   zoom?: number;
+  /** Display metres along the depth axis, `+` toward the viewer (out of the glass). */
+  depthOffset?: number;
+}
+
+/**
+ * Where the subject sits in DISPLAY METRES under the pose currently being drawn — an
+ * axis-aligned box enclosing the oriented subject.
+ *
+ * Display space puts the viewer at `+z` and the glass at `z = 0`, so `front` is the larger z:
+ * a positive `front` means the subject pops OUT of the glass, a negative `back` means depth
+ * behind it.
+ */
+export interface SubjectPlacement {
+  /** Box centre. x and y are always 0 — the fit centres the subject on the tile. */
+  center: { x: number; y: number; z: number };
+  /** Full box size (not half-extents). */
+  extent: { x: number; y: number; z: number };
+  /** z of the surface nearest the viewer. `> 0` = in front of the glass. */
+  front: number;
+  /** z of the surface furthest from the viewer. `< 0` = behind the glass. */
+  back: number;
+  /** Model units → display metres currently in force (fit scale × zoom). */
+  scale: number;
 }
 
 /**
@@ -77,7 +103,31 @@ export declare class SceneViewer {
     extent: number[] | { x: number; y: number; z: number },
   ): void;
 
+  /** Snap the pose. Writes the eased value and its target together. */
   setPose(pose?: OrbitPose): void;
+
+  /**
+   * The pose as it is right now. `target: true` reports what it is easing TOWARD, which differs
+   * mid-orbit — a readout wants the default (eased), "save this view" wants the target.
+   */
+  getPose(opts?: { target?: boolean }): Required<OrbitPose>;
+
+  /**
+   * Where the subject is, in display metres, under the live pose. Safe and cheap to call every
+   * frame; allocates one object and does no matrix work.
+   *
+   * Recompute per frame rather than caching: orbit swings the subject's depth into the
+   * display's z, so a value measured at load is only correct at yaw 0.
+   */
+  getSubjectBounds(): SubjectPlacement;
+
+  /**
+   * Slide the subject along the depth axis, display metres, `+` toward the viewer. Survives
+   * `fitTo`; cleared by `resetPose`.
+   */
+  depthOffset: number;
+
+  /** Return to the framed default pose, depth slide included. */
   resetPose(): void;
 
   /**