@displayxr/inline3d 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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.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
+
+- **`./viewer` wheel zoom is proportional and eased.** It scaled by the delta's SIGN only — a flat
+  8% step per wheel event — which is about right for one mouse notch and badly wrong for a
+  trackpad, where a single two-finger flick emits dozens of small events. Measured: a 20-event
+  flick reached **5.3x** and a longer swipe hit the 6x clamp, on gestures the user reads as gentle.
+
+  The handler now scales by magnitude, normalises `deltaMode` (Chrome reports pixels; Firefox
+  reports LINES for a mouse wheel, so identical hardware was ~2x more sensitive in one browser),
+  clamps per event against OS pointer-acceleration spikes, and applies the zoom as `exp()` so equal
+  deltas give equal ratios in both directions — `1 + d` and `1 - d` are not inverses, and the
+  asymmetry was felt as zooming out being weaker than zooming in. Zoom then eases toward its target
+  on the same damping curve yaw and pitch already used, so a notch glides instead of stepping.
+
+  Same gestures after: trackpad flick **1.13x**, mouse 3 notches **1.35x**, and Chrome and Firefox
+  now agree per notch. *(preview tier — no API change)*
+
 ## 1.2.0 — 2026-08-20
 
 ### Added

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,45 @@ 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;
+}
+
 /** Extra options for {@link Inline3D.addScene}. */
 export interface SceneOptions extends TileOptions {
   /**
@@ -21,6 +60,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 +100,23 @@ 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.
+   */
+  setViewRig(rig: XRViewRigInit): boolean;
   /**
    * Per-window frame counters, for diagnosing the load-induced mono fallback.
    *
@@ -194,6 +259,19 @@ 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;
+
 /** Open the page's inline-3D session and return a manager you add windows to. */
 export function createInline3D(
   opts?: CreateInline3DOptions,
@@ -229,5 +307,14 @@ 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;
   close(): void;
 }

package/js/inline3d-three.js

@@ -45,6 +45,12 @@
 // in front), 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.
+//
+// VIEW RIGS. virtualDisplayHeight is one number out of a whole descriptor. cameraRigFromCamera()
+// and displayRig() below build the full thing — a posed portal, or an app CAMERA whose frustum
+// the runtime perturbs with the viewer's eyes — for handle.setViewRig(). They fill in a
+// descriptor and nothing else: no Kooima, no off-axis math, no scale, here or anywhere in this
+// SDK. That stays in the runtime, which is the point of the extension.
 
 /**
  * A reusable three.js camera driven directly by an XRView's matrices. Construct once with
@@ -89,6 +95,188 @@ export class EyeCamera {
     cam.matrixWorldInverse.copy(cam.matrixWorld).invert();
     return cam;
   }
+
+  /** Set the camera's projection + LOCAL pose from an XRView — the attach pattern below. */
+  setLocalFromView(view) {
+    return this.setLocalFromMatrices(view.projectionMatrix, view.transform.matrix);
+  }
+
+  /**
+   * Like setFromMatrices, but the view's transform is written as the camera's LOCAL matrix and
+   * three composes `matrixWorld` from the parent — so the eye can hang off another object.
+   *
+   * WHY THIS EXISTS: the browser locates views BEFORE the page's rAF, so a view rig set during
+   * frame N drives the views delivered in frame N+1. Send a camera rig with an IDENTITY pose
+   * instead, parent both eye cameras under your app camera object, and the runtime's job shrinks
+   * to what it is uniquely good at (the eye offsets and the tracking-perturbed frustum, in rig
+   * space) while the app's own scene graph supplies the world pose — this frame's, not last
+   * frame's. A camera whipping around under the pointer then has zero rig lag.
+   *
+   * That is a SCENE-GRAPH parent and nothing more. No projection math moves into the page: the
+   * projectionMatrix is still the runtime's, untouched, and the local transform is still the eye
+   * pose the runtime reported — it is simply interpreted in rig space rather than world space,
+   * which is exactly what an identity-posed rig means.
+   *
+   *   appCamera.add(eyeL.camera); appCamera.add(eyeR.camera);   // once
+   *   handle.setViewRig(cameraRigFromCamera(THREE, appCamera, { attach: true, convergence }));
+   *   eyeL.setLocalFromView(views[0]);                          // per frame
+   *
+   * `matrixAutoUpdate` is false (the matrix is ours, not three's) but that does NOT opt out of
+   * world composition: `updateMatrixWorld` still multiplies parent × local. So the eye cameras
+   * must be reached by a normal traversal — `renderer.render(scene, eye.camera)` only
+   * auto-updates a camera whose `parent` is null, so make sure the app camera is IN the scene
+   * (or call `scene.updateMatrixWorld()` yourself) or the eyes will render at a stale pose.
+   *
+   * @param {ArrayLike<number>} projectionMatrix  16 floats, column-major (view.projectionMatrix).
+   * @param {ArrayLike<number>} transformMatrix   16 floats, column-major (view.transform.matrix),
+   *        read as a pose in the RIG's space.
+   */
+  setLocalFromMatrices(projectionMatrix, transformMatrix) {
+    const cam = this.camera;
+    cam.projectionMatrix.fromArray(projectionMatrix);
+    cam.projectionMatrixInverse.copy(cam.projectionMatrix).invert();
+    cam.matrix.fromArray(transformMatrix);
+    // Hand the world matrices back to three. Marking the flag is the whole handshake: with
+    // matrixAutoUpdate off, nothing else tells updateMatrixWorld that the local matrix moved,
+    // and a parent that happens not to move that frame would leave the eye at its old world
+    // pose (Camera.updateMatrixWorld re-derives matrixWorldInverse from matrixWorld, so both
+    // stay consistent once it runs).
+    cam.matrixWorldNeedsUpdate = true;
+    return cam;
+  }
+}
+
+// Scratch for cameraRigFromCamera's decompose. Module-scoped and lazily built from the caller's
+// THREE, so a per-frame rig costs no allocation — the values are copied straight out into the
+// descriptor before anything else can observe them, so sharing is safe.
+let _scratch = null;
+function scratch(THREE) {
+  if (!_scratch) {
+    _scratch = { p: new THREE.Vector3(), q: new THREE.Quaternion(), s: new THREE.Vector3() };
+  }
+  return _scratch;
+}
+
+/**
+ * Build a CAMERA-rig descriptor from a three.js PerspectiveCamera.
+ *
+ * A camera rig says "here is an app camera; perturb its frustum with the viewer's eyes" — the
+ * runtime keeps your vertical FOV, offsets the eyes, and skews each frustum so the convergence
+ * distance lands on the zero-disparity plane. Contrast the DISPLAY rig ({@link displayRig}),
+ * which says "the canvas is a portal onto a virtual display this tall". Neither computes
+ * 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.
+ *
+ * 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
+ * scene in front of the display and is comfortable for almost nothing.
+ *
+ * COMFORT. The runtime's rule is `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
+ * (N = nominal viewing distance, ~0.5 m): at 1 the viewer's eyes are parallel on infinitely far
+ * content, and past it they diverge, which no one can fuse. With the defaults (factors 1,
+ * metersToVirtual 1) that is `convergence >= ~0.5` world units. Nothing here enforces it — the
+ * 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.
+ *
+ * @param {object} THREE  your imported three.js module namespace.
+ * @param {object} camera  a THREE.PerspectiveCamera (`.fov` in degrees, `.matrixWorld` current).
+ * @param {object} [opts]
+ * @param {number} [opts.convergence=0]  zero-disparity distance in WORLD units (0 = infinity).
+ * @param {boolean} [opts.attach=false]  emit an IDENTITY pose, for the attach pattern above —
+ *        you parent the eye cameras under this camera and three supplies the world pose.
+ * @param {number} [opts.ipdFactor=1]  eye separation, ABSOLUTE on a camera rig (world units per
+ *        metre of real IPD); 0 collapses to mono.
+ * @param {number} [opts.parallaxFactor=1]  how far the rig tracks head motion, absolute likewise.
+ * @param {number} [opts.metersToVirtual=1]  metres → world units on the eye.
+ * @param {object} [opts.out]  a descriptor object to overwrite instead of allocating one.
+ * @returns {object} an XRViewRigInit-shaped plain object.
+ */
+export function cameraRigFromCamera(THREE, camera, opts = {}) {
+  const {
+    convergence = 0,
+    attach = false,
+    ipdFactor = 1,
+    parallaxFactor = 1,
+    metersToVirtual = 1,
+    out = {},
+  } = opts;
+  out.type = 'camera';
+  if (attach) {
+    // Identity pose: the rig IS the camera, so the runtime reports eyes in camera space and the
+    // scene graph does the rest. Deliberately not "the camera's pose from a frame ago".
+    out.position = { x: 0, y: 0, z: 0 };
+    out.orientation = { x: 0, y: 0, z: 0, w: 1 };
+  } else {
+    // World pose, decomposed from the matrix rather than read off .position/.quaternion: those
+    // are LOCAL, and an app camera parented under a rig/dolly (the usual way to build an orbit)
+    // would then send the runtime a pose in the wrong space.
+    camera.updateMatrixWorld();
+    const { p, q, s } = scratch(THREE);
+    camera.matrixWorld.decompose(p, q, s);
+    out.position = { x: p.x, y: p.y, z: p.z };
+    out.orientation = { x: q.x, y: q.y, z: q.z, w: q.w };
+  }
+  out.ipdFactor = ipdFactor;
+  out.parallaxFactor = parallaxFactor;
+  // Diopters, not distance: the wire unit is 1/distance so that "infinity" is representable as
+  // a finite 0 instead of a sentinel.
+  out.convergenceDiopters = convergence > 0 ? 1 / convergence : 0;
+  out.verticalFov = THREE.MathUtils.degToRad(camera.fov); // three's fov is the FULL angle, in degrees
+  out.metersToVirtual = metersToVirtual;
+  return out;
+}
+
+/**
+ * Build a DISPLAY-rig descriptor — the default rig, made explicit and posable.
+ *
+ * The display rig treats the canvas as a PORTAL: the element's plane is world z = 0 and the
+ * viewer looks through it at a virtual display `virtualDisplayHeight` metres tall (the m2v knob
+ * `addScene`'s scalar option sets). This adds what the scalar cannot say — a pose, so the portal
+ * can be tilted or offset, and the three factors, so eye separation, head-tracking response and
+ * perspective strength can be dialled independently.
+ *
+ * The factors are RELATIVE here (unlike a camera rig, where ipd/parallax are absolute):
+ * `ipdFactor` and `parallaxFactor` are [0,1] multipliers on what the display would naturally do
+ * — 1 is correct-by-construction, 0 is flat/frozen, and the values between are a comfort dial,
+ * not a correctness one. `perspectiveFactor` is [0.1,10] and exaggerates or flattens the
+ * off-axis skew; it is the one knob with no physical justification, so treat it as an effect.
+ * The runtime clamps anything out of range (once, with a warning) rather than refusing the rig.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.virtualDisplayHeight=0.24]  metres of virtual display (the zoom knob).
+ * @param {{x?:number,y?:number,z?:number}} [opts.position]  rig pose, app world units.
+ * @param {{x?:number,y?:number,z?:number,w?:number}} [opts.orientation]  rig orientation quat.
+ * @param {number} [opts.ipdFactor=1] [opts.parallaxFactor=1] [opts.perspectiveFactor=1]
+ * @param {object} [opts.out]  a descriptor object to overwrite instead of allocating one.
+ * @returns {object} an XRViewRigInit-shaped plain object.
+ */
+export function displayRig(opts = {}) {
+  const {
+    virtualDisplayHeight = 0.24,
+    position = { x: 0, y: 0, z: 0 },
+    orientation = { x: 0, y: 0, z: 0, w: 1 },
+    ipdFactor = 1,
+    parallaxFactor = 1,
+    perspectiveFactor = 1,
+    out = {},
+  } = opts;
+  out.type = 'display';
+  // Copied field by field, not aliased: a caller reusing `out` every frame must not end up
+  // holding a live reference to a THREE.Vector3 it is also mutating.
+  out.position = { x: position.x || 0, y: position.y || 0, z: position.z || 0 };
+  out.orientation = {
+    x: orientation.x || 0,
+    y: orientation.y || 0,
+    z: orientation.z || 0,
+    w: orientation.w === undefined ? 1 : orientation.w,
+  };
+  out.virtualDisplayHeight = virtualDisplayHeight;
+  out.ipdFactor = ipdFactor;
+  out.parallaxFactor = parallaxFactor;
+  out.perspectiveFactor = perspectiveFactor;
+  return out;
 }
 
 /**

package/js/inline3d-viewer.js

@@ -219,6 +219,7 @@ export class SceneViewer {
 
     this._fitScale = 1;
     this._zoom = 1;
+    this._targetZoom = 1;
     this._yaw = 0;
     this._pitch = 0;
     this._targetYaw = 0;
@@ -346,7 +347,7 @@ export class SceneViewer {
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
-    if (zoom !== undefined) this._zoom = clamp(zoom, 0.2, 6);
+    if (zoom !== undefined) this._targetZoom = this._zoom = clamp(zoom, ZOOM_MIN, ZOOM_MAX);
     this._applyTransform();
   }
 
@@ -682,6 +683,14 @@ export class SceneViewer {
     const k = dt > 0 ? 1 - Math.pow(0.001, dt) : 1;
     this._yaw += (this._targetYaw - this._yaw) * k;
     this._pitch += (this._targetPitch - this._pitch) * k;
+    // Zoom eases on the same curve. Multiplicatively, because zoom is a ratio: approaching 2x
+    // linearly spends most of its time near the start and then lurches, while a ratio approach
+    // covers equal PERCEPTUAL steps per frame.
+    if (Math.abs(this._targetZoom - this._zoom) > 1e-4) {
+      this._zoom *= Math.pow(this._targetZoom / this._zoom, k);
+    } else {
+      this._zoom = this._targetZoom;
+    }
     this._applyTransform();
   }
 
@@ -725,9 +734,29 @@ export class SceneViewer {
     };
     this._onWheel = (ev) => {
       ev.preventDefault();
-      this._zoom = clamp(this._zoom * (ev.deltaY > 0 ? 0.92 : 1.087), 0.2, 6);
+      // Scale by the delta's MAGNITUDE, not just its sign. The previous version applied a fixed
+      // 8% step per event, which is roughly right for one mouse notch and badly wrong for a
+      // trackpad: a two-finger flick emits dozens of small events, so an 8% step compounded per
+      // event sent the subject to the clamp on a gesture the user read as gentle.
+      //
+      // deltaMode has to be normalised first or the same code means different things per browser:
+      // Chrome reports pixels, Firefox reports LINES for a mouse wheel (deltaY 3, not 100), and
+      // a page-mode device would otherwise be ~200x more sensitive than a trackpad.
+      let px = ev.deltaY;
+      if (ev.deltaMode === 1) px *= WHEEL_LINE_PX;
+      else if (ev.deltaMode === 2) px *= WHEEL_PAGE_PX;
+      // OS pointer acceleration can spike a single event past 500px. Clamping per event keeps one
+      // hard flick from teleporting the subject while leaving the gesture's total travel intact,
+      // since the events keep coming.
+      px = clamp(px, -WHEEL_MAX_PX, WHEEL_MAX_PX);
+
+      // exp() rather than a multiply-add: zoom is a ratio, so equal deltas should give equal
+      // ratios in both directions. `1 + d` and `1 - d` are not inverses, and the asymmetry is
+      // felt as zooming out being weaker than zooming in.
+      this._targetZoom = clamp(this._targetZoom * Math.exp(-px * ZOOM_PER_PX), ZOOM_MIN, ZOOM_MAX);
       this._lastInput = now();
-      this._applyTransform();
+      // No _applyTransform() here: _tick() eases toward the target and applies it, which is what
+      // makes a wheel notch glide instead of step.
     };
 
     el.style.touchAction = 'none'; // or the browser eats the drag as a scroll
@@ -749,6 +778,24 @@ export class SceneViewer {
   }
 }
 
+/**
+ * Wheel-zoom tuning.
+ *
+ * ZOOM_PER_PX is set so one ordinary mouse notch (~100 px in Chrome) is about a 10% step, which
+ * puts a trackpad's 1-10 px events at a fraction of a percent each — small enough that the easing
+ * reads as continuous rather than as a stack of jumps.
+ */
+// A deltaMode-1 "line" is sized to match a wheel DETENT, not a line of text. Firefox reports a
+// notch as deltaY 3 in lines where Chrome reports it as ~100 in pixels, so 33 makes one physical
+// notch feel the same in both; 16 (a text line) would make Firefox roughly half as responsive as
+// Chrome for identical hardware.
+const WHEEL_LINE_PX = 33;
+const WHEEL_PAGE_PX = 400; // a "page" in deltaMode 2; rare, but it must not be unbounded
+const WHEEL_MAX_PX = 120; // per-event ceiling, against OS pointer acceleration spikes
+const ZOOM_PER_PX = 0.001;
+const ZOOM_MIN = 0.2;
+const ZOOM_MAX = 6;
+
 function now() {
   return typeof performance !== 'undefined' ? performance.now() : Date.now();
 }

package/js/inline3d.js

@@ -41,6 +41,23 @@ const hasLayer = () =>
 // no-op — the page still works, the overlay just weaves like before.
 const hasExclusion = () =>
   hasLayer() && 'excludeElement' in window.XRDisplayLayer.prototype;
+// View rigs (XR_DXR_view_rig, browser-side `XRDisplayLayer.setViewRig`). The browser has always
+// chained a rig descriptor onto its per-frame xrLocateViews — a DISPLAY rig with an identity
+// pose whose only knob was `virtualDisplayHeight`. setViewRig opens the whole descriptor: a
+// posed display rig, or a CAMERA rig that puts the app's own camera in the runtime's hands.
+//
+// The capability signal is the METHOD's presence, and that is deliberate: a Blink IDL attribute
+// getter throws `Illegal invocation` when read off the prototype (the trap documented at length
+// under occlusionByDrawOrder below), so an attribute would be undetectable on exactly the
+// browser that has it. `'setViewRig' in prototype` calls nothing and is safe.
+const hasViewRig = () => {
+  if (!hasLayer()) return false;
+  try {
+    return 'setViewRig' in window.XRDisplayLayer.prototype;
+  } catch {
+    return false; // a prototype that refuses to be probed is not a capability
+  }
+};
 // ── draw-order occlusion (browser Phase 2, browser patches 0063/0064) ─────────────────────
 //
 // The browser composites ANY 2D content over a woven tile per-pixel BY DRAW ORDER — headers,
@@ -170,6 +187,49 @@ export function inline3dOcclusionByDrawOrder() {
   return hasDrawOrderOcclusion();
 }
 
+/**
+ * True when this browser accepts a full VIEW RIG descriptor — `handle.setViewRig(rig)` and
+ * `addScene`'s `viewRig` option, 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.prototype.setViewRig`), never a version or
+ * UA string. False on every browser that predates the rig API — where `virtualDisplayHeight`
+ * still works, which is why a page needs to branch on this only if a camera rig is load-bearing
+ * for it: `setViewRig` no-ops loudly-once rather than throwing, so a page that just wants the
+ * extra control when it is there can call it unconditionally.
+ */
+export function inline3dViewRigSupported() {
+  return inline3DAvailable() && hasViewRig();
+}
+
+// One-shot notices about view rigs. Both are per-document, and both describe a situation that is
+// identical on every frame — so warning per call would bury the page's own logs in a rAF loop.
+let notedNoViewRig = false;
+function noteNoViewRig() {
+  if (notedNoViewRig) return;
+  notedNoViewRig = true;
+  console.warn(
+    '[inline3d] This browser has no XRDisplayLayer.setViewRig, so the view rig was ignored ' +
+      '(the window still weaves — the runtime keeps the default display rig, scaled by ' +
+      "virtualDisplayHeight). Gate on inline3dViewRigSupported() if your page's framing " +
+      'depends on the rig; further calls are silent.'
+  );
+}
+
+let notedRigWinsOverHeight = false;
+function noteRigWinsOverHeight() {
+  if (notedRigWinsOverHeight) return;
+  notedRigWinsOverHeight = true;
+  console.warn(
+    '[inline3d] addScene got BOTH viewRig and virtualDisplayHeight; on a browser with rig ' +
+      'support the rig wins and the height is dropped. They describe the same slot — ' +
+      'virtualDisplayHeight is shorthand for exactly one rig (display, identity pose, all ' +
+      'factors 1) — so there is no merge. This is only worth passing as a PAIR deliberately: ' +
+      'the height is what a browser without setViewRig will use, so a camera-rig scene can ' +
+      'name its own fallback framing. Otherwise say it once, inside the rig.'
+  );
+}
+
 /**
  * Open the page's inline-3D session and return a manager you add windows to.
  *
@@ -491,10 +551,21 @@ class Inline3D {
    * @param {object} [opts]
    * @param {number} [opts.virtualDisplayHeight=0.24]  metres of virtual display the scene is
    *        composed for. Larger = the element shows a bigger slice of the world.
+   * @param {object} [opts.viewRig]  a full view-rig descriptor (XRViewRigInit) instead of the
+   *        scalar height: a POSED display rig, or a CAMERA rig that hands the runtime your app
+   *        camera's pose/FOV/convergence and lets eye tracking perturb its frustum. Supersedes
+   *        virtualDisplayHeight (which is one particular display rig), and can be replaced per
+   *        frame with `handle.setViewRig()`. Ignored on a browser without rig support, which
+   *        falls back to `virtualDisplayHeight` if one was given (that pair is the one reason
+   *        to pass both) — either way the window still weaves.
    * @param {Element} [opts.observe=canvas]  element whose visibility gates lazy create/close.
    * @returns {{remove():void}}
    */
   addScene(canvas, onFrame, opts = {}) {
+    // The rig and the height describe the same one slot in the layer init, so warn where a
+    // caller has said it twice — silently dropping one of two things the page explicitly asked
+    // for is how a scene ends up framed at a scale nobody chose.
+    if (opts.viewRig && opts.virtualDisplayHeight !== undefined) noteRigWinsOverHeight();
     const win = this._register(canvas, 'scene', { virtualDisplayHeight: 0.24, ...opts });
     win.onFrame = onFrame;
     win.ownsBuffer = false; // the app sizes a scene canvas; we never touch canvas.width/height
@@ -528,6 +599,40 @@ class Inline3D {
         if (!el || !win.excluded.delete(el)) return;
         this._dropExclusion(win, el);
       },
+      /**
+       * Replace this window's VIEW RIG — the descriptor the runtime locates views against.
+       * Cheap enough to call every frame (that is the intended use: a rig is per-locate, so
+       * animating one means sending new values, not tweening anything).
+       *
+       * Remembered on the window as well as pushed at the layer, so the lazy lifecycle cannot
+       * quietly lose it (see `viewRig` in _register). Returns whether it reached a LIVE layer:
+       * false also means "stored, and it will build the next layer" for a window that is
+       * currently scrolled away — which is the honest answer for a page driving this per frame,
+       * and the reason it is a boolean rather than void.
+       *
+       * ONE FRAME OF LAG, by construction. The browser locates views BEFORE the page's rAF, so
+       * the rig you set during frame N drives the views delivered in frame N+1. For a slow
+       * knob (a slider, a settled camera) that is invisible; for a camera that moves with the
+       * pointer it is not, and the fix is not to fight it — send an IDENTITY-posed camera rig
+       * and parent your eye cameras under the app camera, so three composes the world pose with
+       * zero lag (see `cameraRigFromCamera(..., {attach:true})` + `EyeCamera.setLocalFromView`).
+       */
+      setViewRig: (rig) => {
+        win.viewRig = rig || null;
+        if (!hasViewRig()) {
+          noteNoViewRig();
+          return false;
+        }
+        if (!win.layer) return false;
+        try {
+          win.layer.setViewRig(rig);
+          return true;
+        } catch {
+          // A closed layer or a descriptor the browser refused. Neither is worth throwing over
+          // in a per-frame call — the window keeps weaving on the rig it already has.
+          return false;
+        }
+      },
       // Read-only counters, for pages that want to see the load-induced mono fallback rather
       // than wait for a bug report about "blinking". Scene windows only; 0/0 elsewhere.
       stats: () => ({ frames: win.frames, monoFrames: win.monoFrames }),
@@ -565,6 +670,11 @@ class Inline3D {
       reqW: opts.width || 0,
       reqH: opts.height || 0,
       virtualDisplayHeight: opts.virtualDisplayHeight || 0,
+      // The rig this window's NEXT layer is built with. Latest wins, and it is kept on the
+      // window rather than only pushed at the live layer because the lazy lifecycle destroys
+      // and rebuilds layers behind the page's back: a tile that scrolls away and back would
+      // otherwise silently revert to the default display rig mid-scene.
+      viewRig: opts.viewRig || null,
       observeEl: opts.observe || canvas,
       ctx: kind === 'scene' ? null : canvas.getContext('2d'),
       repaint: () => this._paint(win, null),
@@ -621,10 +731,23 @@ class Inline3D {
     // layers churn with scroll, so activations double as cheap rescan points.
     this._scanChrome();
     try {
-      // virtualDisplayHeight (display-rig m2v) tells the runtime what scale this
-      // window's scene is authored at, so it returns render-ready scaled views.
+      // What scale/pose the runtime should report views at. virtualDisplayHeight (display-rig
+      // m2v) is the scalar shorthand; a viewRig is the whole descriptor and therefore replaces
+      // it rather than combining with it. Building the layer WITH the rig (instead of
+      // constructing then calling setViewRig) matters for a re-activated window: the layer's
+      // very first located frame is already on the page's rig, so a tile scrolling back into
+      // view never shows one frame of default framing.
+      //
+      // The rig is only offered to a browser that HAS rigs. An older one would take the init
+      // object, find no member it knows, and fall back to its own default height — so a page
+      // that passed both (a camera rig plus the height an older browser should use) would get
+      // neither. Gating here is what makes that fallback pair actually work.
       const init =
-        win.virtualDisplayHeight > 0 ? { virtualDisplayHeight: win.virtualDisplayHeight } : {};
+        win.viewRig && hasViewRig()
+          ? { viewRig: win.viewRig }
+          : win.virtualDisplayHeight > 0
+            ? { virtualDisplayHeight: win.virtualDisplayHeight }
+            : {};
       win.layer = new XRDisplayLayer(this.session, win.canvas, init);
     } catch {
       win.layer = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.2.0",
+  "version": "1.3.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/three.d.ts

@@ -2,6 +2,8 @@
 // These take your imported THREE namespace as a constructor arg, so the SDK never
 // bundles three.js (it is an optional peer dependency).
 
+import type { XRViewRigInit } from './index.js';
+
 /**
  * A reusable three.js camera driven directly by an XRView's matrices. Construct once with your
  * THREE namespace and reuse across frames/windows. Read `.camera` and render it as-is — author
@@ -27,8 +29,84 @@ export class EyeCamera {
     projectionMatrix: ArrayLike<number>,
     transformMatrix: ArrayLike<number>,
   ): void;
+  /** Set the projection + LOCAL pose from an XRView — the attach pattern (see below). */
+  setLocalFromView(view: XRView): void;
+  /**
+   * Like {@link EyeCamera.setFromMatrices}, but the transform becomes the camera's **local**
+   * matrix and three composes `matrixWorld` from the parent — for the attach pattern: send an
+   * identity-posed camera rig, parent the eye cameras under your app camera, and the scene graph
+   * supplies this frame's world pose instead of the rig's one-frame-old one.
+   *
+   * `matrixAutoUpdate` is false but world composition still runs, so the eyes must be reached by
+   * a normal traversal: `renderer.render(scene, eye.camera)` auto-updates a camera only when its
+   * `parent` is null, so keep the app camera IN the scene (or call `scene.updateMatrixWorld()`).
+   */
+  setLocalFromMatrices(
+    projectionMatrix: ArrayLike<number>,
+    transformMatrix: ArrayLike<number>,
+  ): void;
+}
+
+/** Options for {@link cameraRigFromCamera}. */
+export interface CameraRigOptions {
+  /** Zero-disparity distance in WORLD units — content there sits on the glass. 0 = infinity. */
+  convergence?: number;
+  /** Emit an IDENTITY pose for the attach pattern ({@link EyeCamera.setLocalFromMatrices}). */
+  attach?: boolean;
+  /** Eye separation, ABSOLUTE on a camera rig (default 1); 0 collapses to mono. */
+  ipdFactor?: number;
+  /** Head-tracking response, absolute likewise (default 1). */
+  parallaxFactor?: number;
+  /** Metres → world units on the eye (default 1). */
+  metersToVirtual?: number;
+  /** A descriptor to overwrite instead of allocating one (for a per-frame call). */
+  out?: XRViewRigInit;
 }
 
+/** Options for {@link displayRig}. */
+export interface DisplayRigOptions {
+  /** Metres of virtual display — the zoom knob (default 0.24). */
+  virtualDisplayHeight?: number;
+  /** Rig pose in app world units (default 0,0,0). */
+  position?: { x?: number; y?: number; z?: number };
+  /** Rig orientation quaternion (default identity). */
+  orientation?: { x?: number; y?: number; z?: number; w?: number };
+  /** Eye separation as a RELATIVE `[0,1]` multiplier (default 1). */
+  ipdFactor?: number;
+  /** Head-tracking response, `[0,1]` (default 1). */
+  parallaxFactor?: number;
+  /** Off-axis skew strength, `[0.1,10]` (default 1) — an effect, not a correctness knob. */
+  perspectiveFactor?: number;
+  /** A descriptor to overwrite instead of allocating one. */
+  out?: XRViewRigInit;
+}
+
+/**
+ * Build a CAMERA-rig descriptor from a `THREE.PerspectiveCamera` for `handle.setViewRig()`: the
+ * runtime keeps the camera's vertical FOV, offsets the eyes and skews each frustum so
+ * `convergence` lands on the zero-disparity plane. The pose is decomposed from `matrixWorld`
+ * (so a camera parented under a dolly still reports world space) unless `attach` is set, which
+ * emits identity instead.
+ *
+ * Comfort rule, from the runtime: `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
+ * (N ≈ 0.5 m nominal viewing distance). Nothing here enforces it; the runtime clamps.
+ *
+ * @param THREE your imported three.js module namespace.
+ * @param camera a `THREE.PerspectiveCamera` (`.fov` degrees, `.matrixWorld`).
+ */
+export function cameraRigFromCamera(
+  THREE: unknown,
+  camera: unknown,
+  opts?: CameraRigOptions,
+): XRViewRigInit;
+
+/**
+ * Build a DISPLAY-rig descriptor — the default rig, made explicit and posable: the canvas is a
+ * portal onto a virtual display `virtualDisplayHeight` metres tall. Adds what the scalar
+ * `SceneOptions.virtualDisplayHeight` cannot say: a pose, and the three factors.
+ */
+export function displayRig(opts?: DisplayRigOptions): XRViewRigInit;
+
 /**
  * Fade a rendered eye's edges to transparent, so a 3D window dissolves into the page instead of
  * ending at a hard rectangle. Call once per eye, straight after `renderer.render(scene, eye.camera)`,