@displayxr/inline3d 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.11.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), additively. Nothing changes
+for a page that does not pass `controls: 'page'`.
+
+### Added
+
+- **`controls: 'page'`: the page owns the camera.** This is for a game, or any page with its own
+  camera (F1000's phase 1). With `addSplat(…, { engine: 'playcanvas', controls: 'page' })` the
+  adapter runs no orbit, idle spin, auto-fit or focus gestures. It keeps the eye math: the
+  `RenderView` list, the footprint fix, near/far and the mono fallback.
+  - **`handle.setCameraPose(matrixWorld, { verticalFovDeg, near?, far?, convergence? })`**, called
+    every frame. `matrixWorld` is the page camera in the splat's own space (three.js convention).
+    A uniform scale is allowed: F1000 passes `inv(splatWorld) · camera.matrixWorld`, which carries
+    0.4. The adapter applies the OpenCV → engine flip itself. The last call wins, and a page that
+    stops calling keeps its last pose. **`handle.getCameraPose()`** returns a copy of it.
+  - **`onBeforeFrame(frame)`** (`{ time, views, dt }`) runs once per adapter frame, before
+    anything renders. A pose set inside it is what that frame draws, with zero lag. A throw is
+    warned once and frames keep rendering.
+  - **Mono** renders exactly that camera: fov × canvas aspect, principal point centred.
+  - **3D** is the attach pattern. Each eye = `matrixWorld × view.transform`, with the runtime's
+    projection untouched: the page's near/far rewrite only the depth mapping. The rig is declared
+    every frame and is the auto-3D shim's, field for field: `type: 'camera'`, identity pose,
+    `verticalFov`, `convergenceDiopters = 1/d`, `metersToVirtual = comfortDepth · d / 0.5`.
+    **`comfortDepth`** is a new option, default 0.3, in (0, 1].
+  - `d` is the page's `convergence`, else the focus waterfall's. It stays fixed while the camera
+    moves and is re-estimated only on `setSource`. `setFocus(point)` sets `d` to the point's
+    distance along the view axis. `getFocus` / `onFocusChange` report the convergence point.
+  - `setPose` / `resetPose` throw, and `rig: 'display'` throws. `fit`, `virtualDisplayHeight`,
+    `orbit`, `idleSpin`, `focusInput` and the other framing/orbit knobs are ignored, named once in
+    a `console.info`.
+  - **Spark:** `controls: 'page'` throws, naming `engine: 'playcanvas'`. Spark would need
+    SceneViewer (shared with `./viewer` and `./model`) to take an external camera on both its
+    paths.
+
 ## 1.10.1 — 2026-09-23
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), and `boundsFromPositions` in

package/README.md

@@ -60,6 +60,15 @@ one dense sheet that is fully on screen, so it gains nothing from streaming. How
 and budget one, with measurements:
 [`docs/playcanvas-adapter.md` §Streamed SOG](docs/playcanvas-adapter.md#streamed-sog-p2).
 
+**A game owns its camera (preview).** `addSplat(wall, canvas, src, { engine: 'playcanvas',
+controls: 'page', onBeforeFrame })` hands the camera to the page. Call
+`handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far, convergence? })` inside
+`onBeforeFrame` and that frame renders it. The SDK runs no orbit, idle spin, fit or focus
+gestures. It keeps the eye math: the attach-pattern camera rig (the auto-3D shim's, with
+`comfortDepth` 0.3 by default), the runtime's projections, and the mono fallback. Spark refuses
+this mode. Contract and numbers:
+[`docs/playcanvas-adapter.md` §controls:'page'](docs/playcanvas-adapter.md#controlspage--the-page-owns-the-camera).
+
 Stability & what's covered by semver (and the deferred N-view / web-components / CSS-native roadmap
 that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stability.md).
 

package/js/inline3d-splat-playcanvas.js

@@ -82,6 +82,8 @@ import {
   engineFormatFor,
   pathOf,
   streamedBytesError,
+  resolveControls,
+  normalizeCameraPose,
 } from './inline3d-splat-shared.js';
 
 /**
@@ -137,6 +139,10 @@ export const PLAYCANVAS_TESTED = '2.22.3';
 
 const PICK_CONE_RAD = 0.02;
 
+const PAGE_POSE_ERROR =
+  "@displayxr/inline3d/splat: setPose()/resetPose() are not available with controls:'page' — the " +
+  'page owns the camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).';
+
 const DEG = Math.PI / 180;
 
 // ── pure matrix arithmetic (column-major, the layout XRView, three and the engine all use) ──
@@ -362,6 +368,69 @@ export function pivotInverseTRS({ yaw = 0, pitch = 0, scale = 1, focus = [0, 0,
   };
 }
 
+/**
+ * controls:'page' — the rig node's TRS from the page's camera matrix.
+ *
+ * `matrixWorld` is the page camera's world matrix in the SPLAT's model space (the space of the
+ * `.sog` camera block's `rest`), a three.js-convention camera (looks down −Z, +Y up). The splat
+ * entity carries the OpenCV → GL half-turn about X under `flipY`, so the camera rides the same
+ * turn: rig = F · M, F = Rx(180°) (or the identity without the flip). A uniform scale in M is
+ * kept — it is how a page whose world scales the splat (F1000: S(2.5)) expresses "page units",
+ * and it puts the runtime's eye offsets (metres) and the page's near/far into page units for free.
+ *
+ * @returns {{position:number[], rotation:number[], scale:number, uniform:boolean}}
+ */
+export function pageRigTRS(M, flipY = true) {
+  const m = Float64Array.from(M);
+  if (flipY) {
+    for (const c of [0, 4, 8, 12]) {
+      m[c + 1] = -m[c + 1];
+      m[c + 2] = -m[c + 2];
+    }
+  }
+  const len = (c) => Math.hypot(m[c], m[c + 1], m[c + 2]);
+  const lx = len(0), ly = len(4), lz = len(8);
+  const s = Math.cbrt(lx * ly * lz);
+  const uniform = Math.abs(lx - s) < 1e-4 * s && Math.abs(ly - s) < 1e-4 * s && Math.abs(lz - s) < 1e-4 * s;
+  const R = new Float64Array(16);
+  R[0] = m[0] / lx; R[1] = m[1] / lx; R[2] = m[2] / lx;
+  R[4] = m[4] / ly; R[5] = m[5] / ly; R[6] = m[6] / ly;
+  R[8] = m[8] / lz; R[9] = m[9] / lz; R[10] = m[10] / lz;
+  R[15] = 1;
+  return { position: [m[12], m[13], m[14]], rotation: quatFromMatrix(R), scale: s, uniform };
+}
+
+/** pageRigTRS as a column-major matrix (the pick ray and the tests read it this way). */
+export function pageRigMatrix(M, flipY = true) {
+  const t = pageRigTRS(M, flipY);
+  const out = poseMatrix(t.position, t.rotation);
+  for (let i = 0; i < 12; i++) if (i % 4 !== 3) out[i] *= t.scale;
+  return out;
+}
+
+/**
+ * The page camera's view axis in MODEL space: its position and unit forward (−Z of the matrix),
+ * plus the matrix's uniform scale (model units per page unit).
+ */
+export function pageViewAxis(M) {
+  const s = Math.cbrt(Math.hypot(M[0], M[1], M[2]) * Math.hypot(M[4], M[5], M[6]) * Math.hypot(M[8], M[9], M[10]));
+  const fl = Math.hypot(M[8], M[9], M[10]) || 1;
+  return { origin: [M[12], M[13], M[14]], forward: [-M[8] / fl, -M[9] / fl, -M[10] / fl], scale: s };
+}
+
+/**
+ * The attach-pattern camera rig for controls:'page' — the auto-3D shim's buildRig, field for
+ * field: identity pose, the page's vertical FOV, convergence d, metersToVirtual = depth · d / 0.5
+ * (so comfort = ipd × m2v × (1/d) × 0.5 = depth by construction).
+ */
+export function pageViewRig({ verticalFovDeg, convergence, comfortDepth, ipdFactor = 1, parallaxFactor = 1 }, out = {}) {
+  const d = Math.max(1e-6, convergence);
+  return cameraRigFromPose(
+    { fov: verticalFovDeg },
+    { attach: true, convergence: d, ipdFactor, parallaxFactor, metersToVirtual: (comfortDepth * d) / 0.5, out },
+  );
+}
+
 /**
  * SceneViewer.fitTo's scale, as a function. Same arithmetic, same order, same clamps — see the
  * reasoning there (swept width, 'height' guard, depth backstop).
@@ -536,8 +605,15 @@ export class PlayCanvasSplatViewer {
       nearClip,
       farClip,
       sky = false,
+      pageCamera = false,
     } = opts;
     this.canvas = canvas;
+    // controls:'page': the PAGE owns the camera (setPageCamera). No orbit, no idle, no fit; the
+    // rig node carries the page's matrix instead of the inverse pivot.
+    this.pageCamera = pageCamera === true;
+    this.page = this.pageCamera
+      ? { matrix: poseMatrix([0, 0, 0], [0, 0, 0, 1]), fov: MONO_FOV, near: MONO_NEAR, far: CAPTURE_FAR, set: false }
+      : null;
     // The engine draws a sky box whenever the scene has something to draw it from — and
     // `scene.envAtlas` counts: a page that sets one to light its own meshes under
     // handle.engine.root got a grey gradient box behind the splat the instant the splat was
@@ -568,7 +644,7 @@ export class PlayCanvasSplatViewer {
     this.fitSweep = fitSweep;
     this.renderScale = renderScale;
     this.pitchLimit = pitchLimit;
-    this.idleSpin = idleSpin;
+    this.idleSpin = this.pageCamera ? 0 : idleSpin;
     this.flipY = opts.flipY !== false;
 
     this._fitScale = 1;
@@ -587,6 +663,8 @@ export class PlayCanvasSplatViewer {
     this._focusSettled = true;
     this.onFocusChange = null;
     this.onTick = null;
+    /** controls:'page' — `(views|null) => void`, run once per frame before anything else. */
+    this._beforeFrame = null;
     this._lastInput = now();
     this._lastTick = 0;
     this._monoRaf = 0;
@@ -608,6 +686,13 @@ export class PlayCanvasSplatViewer {
       proj: new Float64Array(16),
       capture: null, // intrinsics when on a camera rig
     };
+    if (this.pageCamera) {
+      // The mono camera IS the page camera: identity under the rig node, the page's lens.
+      this.mono.fov = this.page.fov;
+      this.mono.near = this.page.near;
+      this.mono.far = this.page.far;
+      this.mono.pose = poseMatrix([0, 0, 0], [0, 0, 0, 1]);
+    }
     this._placeMonoForFit();
 
     // Engine objects — null until attachEngine().
@@ -635,7 +720,7 @@ export class PlayCanvasSplatViewer {
     if (this._ro) this._ro.observe(canvas);
     else if (typeof addEventListener === 'function') addEventListener('resize', this._onResize);
 
-    if (orbit) this._bindOrbit();
+    if (orbit && !this.pageCamera) this._bindOrbit();
     this._resize();
 
     this.onFrame = this.onFrame.bind(this);
@@ -658,6 +743,7 @@ export class PlayCanvasSplatViewer {
   }
 
   fitTo(center, extent) {
+    if (this.pageCamera) return; // the page frames its own camera
     const c = Array.isArray(center) ? center : [center.x, center.y, center.z];
     const e = Array.isArray(extent) ? extent : [extent.x, extent.y, extent.z];
     this.setFocus(c, { snap: true });
@@ -677,6 +763,7 @@ export class PlayCanvasSplatViewer {
   }
 
   setPose({ yaw, pitch, zoom, depthOffset } = {}) {
+    if (this.pageCamera) throw new Error(PAGE_POSE_ERROR);
     // A snap, as on SceneViewer; it also ends an orbit relax (the page is driving now).
     if (yaw !== undefined || pitch !== undefined) this._orbitMode = null;
     if (yaw !== undefined) this._targetYaw = this._yaw = yaw;
@@ -698,6 +785,7 @@ export class PlayCanvasSplatViewer {
   }
 
   resetPose() {
+    if (this.pageCamera) throw new Error(PAGE_POSE_ERROR);
     this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
     this._lastInput = now();
   }
@@ -744,8 +832,40 @@ export class PlayCanvasSplatViewer {
     return { x: v.x, y: v.y, z: v.z };
   }
 
+  /**
+   * controls:'page' — take the page's camera for the next frame drawn (last call wins; no call
+   * keeps the last pose). `pose` is normalizeCameraPose()'s output. The rig node is written here
+   * and by the tick, through _applyTransform (still its only writer).
+   */
+  setPageCamera(pose) {
+    if (!this.pageCamera) throw new Error("setPageCamera needs controls:'page'");
+    const p = this.page;
+    p.matrix.set(pose.matrixWorld);
+    p.set = true;
+    if (pose.verticalFovDeg !== p.fov || pose.near !== p.near || pose.far !== p.far) {
+      p.fov = pose.verticalFovDeg;
+      p.near = pose.near;
+      p.far = pose.far;
+      this.mono.fov = p.fov;
+      this.mono.near = p.near;
+      this.mono.far = p.far;
+      this._updateMonoProjection();
+    }
+    this._applyTransform();
+  }
+
+  /**
+   * The rig node's matrix (eye space → content space): the inverse pivot on the viewer's own
+   * controls, F · matrixWorld on controls:'page'.
+   */
+  rigMatrix() {
+    if (this.pageCamera) return pageRigMatrix(this.page.matrix, this.flipY);
+    return mat4Invert(pivotMatrix(this.pivotState()));
+  }
+
   /** Pose + lens the mono camera as the recording camera (applyCaptureCamera's counterpart). */
   useCaptureCamera(rig) {
+    if (this.pageCamera) return; // the page's lens, not the recording's
     const pose = capturePose(rig.rest, this.flipY);
     this.mono.pose = pose.matrix;
     this.mono.capture = rig.intrinsics;
@@ -763,6 +883,7 @@ export class PlayCanvasSplatViewer {
 
   /** Back to the display rig's mono camera (setSource from a photo lift to an object). */
   useDisplayCamera() {
+    if (this.pageCamera) return;
     this.mono.capture = null;
     this.mono.fov = MONO_FOV;
     this.mono.far = MONO_FAR;
@@ -779,6 +900,8 @@ export class PlayCanvasSplatViewer {
   onFrame(views, layer) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
+    // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
+    this._beforeFrame?.(views || null);
     this._tick();
     if (!views || views.length < 2) {
       this._replayLastGood();
@@ -805,6 +928,8 @@ export class PlayCanvasSplatViewer {
     const loop = () => {
       if (this._disposed) return;
       this._monoRaf = requestAnimationFrame(loop);
+      this._beforeFrame?.(null);
+      if (this._disposed || this._mode !== 'mono') return; // the callback removed or re-wove us
       this._tick();
       this._drawMono();
     };
@@ -1092,7 +1217,7 @@ export class PlayCanvasSplatViewer {
 
   _placeMonoForFit() {
     // SceneViewer.fitTo: distance to make the frustum exactly vH tall at z = 0, looking down −z.
-    if (this.mono.capture) return;
+    if (this.mono.capture || this.pageCamera) return;
     const d = (0.5 * this.vH) / Math.tan((this.mono.fov * DEG) / 2);
     this.mono.pose = poseMatrix([0, 0, d], [0, 0, 0, 1]);
   }
@@ -1134,7 +1259,14 @@ export class PlayCanvasSplatViewer {
     const el = this.canvas;
     const sx = cache && cache.bufW > 0 && el.width ? el.width / cache.bufW : 1;
     const sy = cache && cache.bufH > 0 && el.height ? el.height / cache.bufH : 1;
-    if (this.nearClip !== null || this.farClip !== null) {
+    if (this.pageCamera) {
+      // The page's near/far join the caller's nearClip/farClip as a floor and a cap: only the
+      // depth mapping moves, the runtime's frustum (fov, skew, principal point) stays untouched.
+      const p = this.page;
+      const nf = this.nearClip !== null ? Math.max(this.nearClip, p.near) : p.near;
+      const fc = this.farClip !== null ? Math.min(this.farClip, p.far) : p.far;
+      for (const e of entries) clampProjectionDepth(e.proj, nf, fc);
+    } else if (this.nearClip !== null || this.farClip !== null) {
       for (const e of entries) clampProjectionDepth(e.proj, this.nearClip, this.farClip);
     }
     const rect = (e) =>
@@ -1344,7 +1476,7 @@ export class PlayCanvasSplatViewer {
    */
   _applyTransform() {
     if (!this.rigNode) return;
-    const trs = pivotInverseTRS(this.pivotState());
+    const trs = this.pageCamera ? pageRigTRS(this.page.matrix, this.flipY) : pivotInverseTRS(this.pivotState());
     this.rigNode.setLocalPosition(trs.position[0], trs.position[1], trs.position[2]);
     this.rigNode.setLocalRotation(trs.rotation[0], trs.rotation[1], trs.rotation[2], trs.rotation[3]);
     this.rigNode.setLocalScale(trs.scale, trs.scale, trs.scale);
@@ -1736,8 +1868,22 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // `sortIntervalMs` is accepted and has no effect here: the engine re-sorts when the camera
   // ROTATES (one directional sort serves every view), not on a timer — docs/playcanvas-adapter.md.
 
+  // controls:'page' — validated again here (./splat already did, at call time) because a test or
+  // an advanced caller may reach this function directly.
+  const ctl = resolveControls(opts);
+  const pageMode = ctl.page;
+  if (pageMode && ctl.ignored.length) {
+    console.info(
+      `[inline3d/splat] controls:'page' — the page owns the camera, so ${ctl.ignored.join(', ')} ` +
+        `${ctl.ignored.length === 1 ? 'is' : 'are'} ignored.`,
+    );
+  }
+  // The rig question is answered by the page: its camera IS the rig.
+  const rigOpts = pageMode ? { ...opts, rig: 'camera' } : opts;
+
   const perfResolved = playcanvasPerfSettings(perf);
   const viewer = new PlayCanvasSplatViewer(canvas, {
+    pageCamera: pageMode,
     virtualDisplayHeight,
     fit,
     margin,
@@ -1773,13 +1919,49 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     perf: perfResolved.applied,
     setPose: (p) => viewer.setPose(p),
     resetPose: () => viewer.resetPose(),
+    /**
+     * controls:'page' — the page's camera for the next frame drawn. See normalizeCameraPose for
+     * the arguments; last call wins; a page that stops calling keeps its last pose.
+     */
+    setCameraPose(matrixWorld, o) {
+      if (!pageMode) {
+        throw new Error(
+          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
+            'with the default controls the SDK owns the camera (use setPose).',
+        );
+      }
+      const pose = normalizeCameraPose(matrixWorld, o);
+      if (!warnedNonUniform && !pageRigTRS(pose.matrixWorld, flipY).uniform) {
+        warnedNonUniform = true;
+        console.warn(
+          "[inline3d/splat] controls:'page' — matrixWorld has a NON-uniform scale; the adapter uses " +
+            'its geometric mean. A camera pose is rotation + translation + at most a uniform scale.',
+        );
+      }
+      lastPagePose = pose;
+      viewer.setPageCamera(pose);
+      return out;
+    },
+    /** The last pose the page set (a copy), or null before the first setCameraPose. */
+    getCameraPose() {
+      if (!lastPagePose) return null;
+      return {
+        matrixWorld: Float32Array.from(lastPagePose.matrixWorld),
+        verticalFovDeg: lastPagePose.verticalFovDeg,
+        near: lastPagePose.near,
+        far: lastPagePose.far,
+        convergence: lastPagePose.convergence,
+      };
+    },
     getFocus: (o) => {
+      if (pageMode) return pageFocusPoint();
       // In MODEL space, like setFocus takes it.
       const f = viewer.getFocus(o);
       return contentToModel([f.x, f.y, f.z]);
     },
     setFocus(point, o = {}) {
       if (!out.mesh || !out.rig) return out;
+      if (pageMode) return pageSetFocus(point, o);
       const model = point == null ? out.rig.focusDefault : toArray3(point);
       out.rig.focus = model;
       out.rig.focusSource = point == null ? out.rig.focusDefaultSource : 'set';
@@ -1815,9 +1997,21 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return flipY ? [c[0], -c[1], -c[2]] : [c[0], c[1], c[2]];
   }
 
+  // ── controls:'page' state (null/unused on the viewer's own controls) ──
+  let lastPagePose = null; // what the page last handed setCameraPose, validated
+  let warnedNonUniform = false;
+  // The convergence the adapter owns when the page gives none, in MODEL units (so it is stable
+  // while the camera moves): the waterfall's on load / setSource, a setFocus after that. Eased
+  // toward `target` at the viewer's FOCUS_EASE unless snapped.
+  const pageFocus = { d: Number.NaN, target: Number.NaN, fired: Number.NaN, source: null };
+
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
-      virtualDisplayHeight,
+      // controls:'page' starts on a camera rig (attach, provisional FOV/convergence until the page
+      // and the waterfall say otherwise); the display rig's height means nothing there.
+      ...(pageMode
+        ? { viewRig: pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth }) }
+        : { virtualDisplayHeight }),
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
       ...(firstWovenHoldMs !== undefined ? { firstWovenHoldMs } : {}),
@@ -1841,9 +2035,100 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     out[name]?.(...args);
   }
 
+  // ── controls:'page': focus = the convergence point on the page camera's view axis ──
+  /** The convergence distance for THIS frame, in page units, and where it came from. */
+  function pageConvergence() {
+    const ax = pageViewAxis(viewer.page.matrix);
+    if (lastPagePose && lastPagePose.convergence !== null) {
+      return { d: lastPagePose.convergence, ax, source: 'page' };
+    }
+    const dm = Number.isFinite(pageFocus.d) ? pageFocus.d : 2;
+    return { d: dm / (ax.scale || 1), ax, source: out.rig?.focusSource ?? 'default' };
+  }
+  function pageFocusPoint() {
+    if (!out.rig) return null;
+    const { d, ax } = pageConvergence();
+    const dm = d * ax.scale;
+    return [ax.origin[0] + ax.forward[0] * dm, ax.origin[1] + ax.forward[1] * dm, ax.origin[2] + ax.forward[2] * dm];
+  }
+  function pageSetFocus(point, { snap = false } = {}) {
+    let dm;
+    if (point == null) {
+      dm = out.rig.convergenceDefault;
+      out.rig.focus = out.rig.focusDefault;
+      out.rig.focusSource = out.rig.focusDefaultSource;
+    } else {
+      const m = toArray3(point);
+      const ax = pageViewAxis(viewer.page.matrix);
+      dm = (m[0] - ax.origin[0]) * ax.forward[0] + (m[1] - ax.origin[1]) * ax.forward[1] + (m[2] - ax.origin[2]) * ax.forward[2];
+      if (!(dm > 0)) {
+        console.warn('[inline3d/splat] setFocus: that point is behind the page camera — focus unchanged');
+        return out;
+      }
+      out.rig.focus = m;
+      out.rig.focusSource = 'set';
+    }
+    pageFocus.target = dm;
+    if (snap || !Number.isFinite(pageFocus.d)) pageFocus.d = dm;
+    return out;
+  }
+  /** Per tick (before the draw, so the rig drives the next locate): ease, declare, notify. */
+  function pageTick() {
+    if (Number.isFinite(pageFocus.target) && pageFocus.d !== pageFocus.target) {
+      const dd = pageFocus.target - pageFocus.d;
+      pageFocus.d = Math.abs(dd) < 1e-6 ? pageFocus.target : pageFocus.d + dd * FOCUS_EASE;
+    }
+    const { d, source } = pageConvergence();
+    out.viewRig = pageViewRig(
+      {
+        verticalFovDeg: viewer.page.fov,
+        convergence: d,
+        comfortDepth: ctl.comfortDepth,
+        ipdFactor: out.rig ? out.rig.ipdFactor : Number.isFinite(opts.ipdFactor) ? opts.ipdFactor : 1,
+        parallaxFactor: out.rig ? out.rig.parallaxFactor : Number.isFinite(opts.parallaxFactor) ? opts.parallaxFactor : 1,
+      },
+      out.viewRig || {},
+    );
+    handle?.setViewRig?.(out.viewRig);
+    if (!out.rig) return;
+    out.rig.convergence = d;
+    if (Math.abs(d - pageFocus.fired) > 1e-3 || source !== pageFocus.source) {
+      pageFocus.fired = d;
+      pageFocus.source = source;
+      const cb = out.onFocusChange;
+      if (typeof cb === 'function') cb(pageFocusPoint(), { focusSource: source });
+    }
+  }
+  if (pageMode) viewer.onTick = pageTick;
+
+  // onBeforeFrame: the page's game step INSIDE this adapter's frame, before the tick and the
+  // draw — so a setCameraPose made in it is what this frame renders (zero lag, the attach
+  // pattern). The session rAF (3D) and the window rAF have no guaranteed order, so a pose set
+  // from the page's own rAF may be one frame late. A throw is the page's bug: warned once, and
+  // the frame still renders (with whatever pose it had).
+  if (pageMode && typeof opts.onBeforeFrame === 'function') {
+    const cb = opts.onBeforeFrame;
+    let lastT = 0;
+    let warned = false;
+    viewer._beforeFrame = (views) => {
+      const t = now();
+      const dt = lastT ? Math.min((t - lastT) / 1000, MAX_DT_S) : 0;
+      lastT = t;
+      try {
+        cb({ time: t, views, dt });
+      } catch (err) {
+        if (!warned) {
+          warned = true;
+          console.warn('[inline3d/splat] onBeforeFrame threw (warned once; frames keep rendering)', err);
+        }
+      }
+    };
+  }
+
   // ── focus → view rig ──
   let lastConvergence = Number.NaN;
   function pushViewRig(force) {
+    if (pageMode) return; // pageTick declares the rig every frame
     if (!out.rig || out.rig.type !== 'camera') return;
     const pose = viewer.mono.pose;
     const f = viewer.getFocus();
@@ -1905,8 +2190,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const v = viewer.currentView();
     const invP = mat4Invert(v.proj);
     if (!invP) return null;
-    const Minv = mat4Invert(pivotMatrix(viewer.pivotState()));
-    const toContent = mat4Mul(Minv, v.pose);
+    const toContent = mat4Mul(viewer.rigMatrix(), v.pose);
     const a = transformPoint(invP, ndc.x, ndc.y, -1);
     const b = transformPoint(invP, ndc.x, ndc.y, 1);
     const o = contentToModel(transformPoint(toContent, a[0], a[1], a[2]));
@@ -1953,7 +2237,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
 
   function bindFocusInput() {
-    if (focusInput === false || unbindFocusInput) return;
+    // controls:'page' binds no input at all: gestures are the page's (pick + setFocus remain).
+    if (pageMode || focusInput === false || unbindFocusInput) return;
     unbindFocusInput = bindFocusGestures(canvas, {
       onDoubleClick: (e) => {
         const m = pickModel(e.clientX, e.clientY);
@@ -1993,7 +2278,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // The camera block off the SAME bytes, before the engine takes them (as the Spark path).
     let camera = null;
     let t0 = performance.now();
-    if (bytes && rig !== 'display') camera = sogCameraFromMeta(await readSogMeta(bytes));
+    if (bytes && rigOpts.rig !== 'display') camera = sogCameraFromMeta(await readSogMeta(bytes));
     perfSpan('readSogMeta(async)', t0);
 
     const url = bytes
@@ -2017,7 +2302,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const desc = describeResource(res);
     // A URL `.sog` carries its meta in the resource (the engine keeps unknown keys); a Streamed
     // SOG carries it at the top level of lod-meta.json. Both validated by the same reader.
-    if (!bytes && rig !== 'display') camera = sogCameraFromMeta(desc.meta);
+    if (!bytes && rigOpts.rig !== 'display') camera = sogCameraFromMeta(desc.meta);
     const cloud = desc.kind === 'flat' ? await readCloud(res) : null;
     // The cloud passes, each in its OWN task: framing, the rest-space sample and the pick set
     // were one ~60 ms main-thread block on a 1.18M-gaussian swap — pointer input waited on it.
@@ -2071,7 +2356,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const box = canvas.getBoundingClientRect();
     const resolved = resolveRig({
       camera: loaded.camera,
-      opts,
+      opts: rigOpts,
       cloud: sample,
       canvasAspect: box.height > 0 ? box.width / box.height : 4 / 3,
     });
@@ -2092,7 +2377,23 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // The strided pick fallback (used only if the engine releases its full centre set).
     const pickCentres = loaded.pre?.pickCentres || null;
 
-    if (resolved.type === 'camera') {
+    if (pageMode) {
+      // The page owns the pose; the waterfall only supplies the convergence (re-estimated here,
+      // on load and on setSource, never per frame). Until the page's first setCameraPose the
+      // camera sits at the asset's rest pose (the block's, else the origin looking down +z) with
+      // the resolved lens, so the first frame is not an empty tile.
+      resolved.convergenceDefault = resolved.convergence;
+      pageFocus.target = pageFocus.d = resolved.convergence;
+      pageFocus.fired = Number.NaN;
+      if (!lastPagePose) {
+        const r = resolved.rest;
+        viewer.setPageCamera(
+          normalizeCameraPose(poseMatrix(r.position, qmul(r.rotation, FLIP_Q)), {
+            verticalFovDeg: captureVerticalFovDeg(resolved.intrinsics, NaN, MONO_NEAR, 'height'),
+          }),
+        );
+      }
+    } else if (resolved.type === 'camera') {
       if (!('idleSpin' in opts)) viewer.idleSpin = 0;
       // The camera rig never auto-fits (the capture IS the framing): a scale left by a previous
       // display-rig asset (setSource) must not shrink this one.
@@ -2184,7 +2485,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     };
     const kept = applyLoaded(loaded);
     current = { asset: loaded.asset, entity, res: loaded.res, kind: loaded.desc.kind, ...kept };
-    if (resetPose) viewer.resetPose();
+    if (resetPose && !pageMode) viewer.resetPose(); // the page owns the pose on controls:'page'
 
     const release = () => {
       if (!prev) return;

package/js/inline3d-splat-shared.js

@@ -316,3 +316,124 @@ export function playcanvasCannotRead(src, { fileType, fileName } = {}) {
     `${what}. Pass engine:'spark' for .spz / .splat / .ksplat / .rad.`
   );
 }
+
+// ── controls:'page' — the page drives the camera (docs/playcanvas-adapter.md §controls:'page') ──
+
+/** Who owns the camera: the SDK's viewer (orbit, idle, fit, focus gestures) or the page. */
+export const SPLAT_CONTROLS = Object.freeze(['viewer', 'page']);
+
+/**
+ * `comfortDepth` default — the auto-3D shim's `depth`, so a game on `controls:'page'` gets the
+ * same stereo as the same game under the shim. It is the runtime's comfort number
+ * `ipd × metersToVirtual × convergenceDiopters × 0.5`, which the rig below makes equal to it by
+ * construction (`metersToVirtual = comfortDepth · d / 0.5`, `convergenceDiopters = 1 / d`).
+ */
+export const PAGE_COMFORT_DEPTH = 0.3;
+
+/**
+ * Options that mean nothing when the page owns the camera. Passing one is not an error (a page
+ * switching an existing call site over should not have to prune it first); it is named ONCE in a
+ * console.info line and ignored.
+ */
+export const PAGE_IGNORED_OPTIONS = Object.freeze([
+  'fit',
+  'virtualDisplayHeight',
+  'orbit',
+  'idleSpin',
+  'focusInput',
+  'margin',
+  'fitSweep',
+  'depthLimit',
+  'orbitMaxDeg',
+  'orbitEase',
+  'captureFit',
+]);
+
+/**
+ * Validate the `controls` family at CALL time (both engines call this before anything loads).
+ *
+ * @returns {{page:boolean, comfortDepth:number, ignored:string[]}}
+ * @throws on an unknown `controls`, a `comfortDepth` outside (0, 1], or `rig:'display'` with
+ *         `controls:'page'` (the page's camera IS the rig; a display rig has no camera).
+ */
+export function resolveControls(opts = {}) {
+  const controls = opts.controls ?? 'viewer';
+  if (!SPLAT_CONTROLS.includes(controls)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: controls "${controls}" — expected ` +
+        `${SPLAT_CONTROLS.map((c) => `'${c}'`).join(' or ')} (default 'viewer').`,
+    );
+  }
+  const page = controls === 'page';
+  let comfortDepth = PAGE_COMFORT_DEPTH;
+  if (opts.comfortDepth !== undefined) {
+    const c = opts.comfortDepth;
+    if (typeof c !== 'number' || !Number.isFinite(c) || c <= 0 || c > 1) {
+      throw new Error(
+        `@displayxr/inline3d/splat: comfortDepth ${c} — expected a number in (0, 1] ` +
+          `(the runtime's comfort rule caps it at 1; the default is ${PAGE_COMFORT_DEPTH}).`,
+      );
+    }
+    comfortDepth = c;
+  }
+  if (page && opts.rig === 'display') {
+    throw new Error(
+      "@displayxr/inline3d/splat: controls:'page' with rig:'display' — the page's camera IS the " +
+        "rig, so it is always a camera rig. Drop `rig`, or use the default controls for a display rig.",
+    );
+  }
+  if (opts.onBeforeFrame !== undefined) {
+    if (typeof opts.onBeforeFrame !== 'function') {
+      throw new Error('@displayxr/inline3d/splat: onBeforeFrame must be a function (frame) => void.');
+    }
+    if (!page) {
+      throw new Error(
+        "@displayxr/inline3d/splat: onBeforeFrame needs controls:'page' — with the default controls " +
+          'the SDK owns the camera and there is no page pose to set before the draw.',
+      );
+    }
+  }
+  const ignored = page ? PAGE_IGNORED_OPTIONS.filter((k) => opts[k] !== undefined) : [];
+  return { page, comfortDepth, ignored };
+}
+
+/**
+ * Validate one `setCameraPose(matrixWorld, o)` call and return a private copy (the page may
+ * reuse its arrays). Throws synchronously on a malformed call: a NaN in a camera matrix is a page
+ * bug that would otherwise render nothing, silently.
+ *
+ * @returns {{matrixWorld:Float64Array, verticalFovDeg:number, near:number, far:number,
+ *            convergence:number|null}}
+ */
+export function normalizeCameraPose(matrixWorld, o = {}) {
+  const bad = (why) => new Error(`@displayxr/inline3d/splat: setCameraPose — ${why}`);
+  if (!matrixWorld || typeof matrixWorld.length !== 'number' || matrixWorld.length !== 16) {
+    throw bad('matrixWorld must be 16 numbers, column-major (a Float32Array(16) or an array).');
+  }
+  const m = new Float64Array(16);
+  for (let i = 0; i < 16; i++) {
+    const v = matrixWorld[i];
+    if (typeof v !== 'number' || !Number.isFinite(v)) throw bad(`matrixWorld[${i}] is ${v}, not a finite number.`);
+    m[i] = v;
+  }
+  const det =
+    m[0] * (m[5] * m[10] - m[9] * m[6]) - m[4] * (m[1] * m[10] - m[9] * m[2]) + m[8] * (m[1] * m[6] - m[5] * m[2]);
+  if (!(det > 1e-12)) {
+    throw bad(`matrixWorld is singular or mirrored (det ${det.toPrecision(3)}); a camera pose is a rotation, a translation and at most a uniform scale.`);
+  }
+  const fov = o.verticalFovDeg;
+  if (typeof fov !== 'number' || !(fov > 0 && fov < 180)) {
+    throw bad(`verticalFovDeg ${fov} — the FULL vertical angle in degrees, in (0, 180).`);
+  }
+  const near = o.near === undefined ? MONO_NEAR : o.near;
+  const far = o.far === undefined ? CAPTURE_FAR : o.far;
+  if (typeof near !== 'number' || !(near > 0) || !Number.isFinite(near)) throw bad(`near ${near} — expected a finite number > 0.`);
+  if (typeof far !== 'number' || !(far > near) || !Number.isFinite(far)) throw bad(`far ${far} — expected a finite number > near.`);
+  let convergence = null;
+  if (o.convergence !== undefined && o.convergence !== null) {
+    const c = o.convergence;
+    if (typeof c !== 'number' || !(c > 0) || !Number.isFinite(c)) throw bad(`convergence ${c} — metres along the view axis, > 0 (omit it for the adapter's own).`);
+    convergence = c;
+  }
+  return { matrixWorld: m, verticalFovDeg: fov, near, far, convergence };
+}

package/js/inline3d-splat.js

@@ -34,6 +34,8 @@ import {
   playcanvasCannotRead,
   isStreamedUrl,
   STREAMED_NEEDS_PLAYCANVAS,
+  resolveControls,
+  normalizeCameraPose,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -163,6 +165,9 @@ export function addSplat(wall, canvas, src, opts = {}) {
         `${CAPTURE_FITS.map((f) => `'${f}'`).join(' or ')}.`,
     );
   }
+  // WHO OWNS THE CAMERA. Validated here, synchronously, for both engines (an unknown `controls`
+  // or a comfortDepth out of range is a page bug true of every call).
+  const { page: pageControls } = resolveControls(opts);
   // WHICH ENGINE. Unset (or 'spark') is everything below, untouched. 'playcanvas' goes to
   // ./inline3d-splat-playcanvas.js, imported DYNAMICALLY so a page that never asks for it never
   // resolves `playcanvas` — see addSplatDeferred.
@@ -174,6 +179,16 @@ export function addSplat(wall, canvas, src, opts = {}) {
     return addSplatDeferred(wall, canvas, src, opts);
   }
 
+  // controls:'page' is a PlayCanvas-backend feature (docs/playcanvas-adapter.md §controls:'page'):
+  // on Spark it would need SceneViewer — which ./viewer and ./model share — to take an external
+  // camera in both its mono and eye paths. Refused by name rather than half-supported.
+  if (pageControls) {
+    throw new Error(
+      "@displayxr/inline3d/splat: controls:'page' is not supported on Spark (the default engine) — " +
+        "pass engine:'playcanvas'. Spark's viewer owns its camera; see docs/playcanvas-adapter.md.",
+    );
+  }
+
   // A Streamed SOG on Spark is a page bug (Spark has no lod-meta.json reader): say so now, by
   // name, rather than let Spark fail on an "unknown file type" that reads like a corrupt asset.
   if (isStreamedUrl(src)) throw new Error(`@displayxr/inline3d/splat: ${STREAMED_NEEDS_PLAYCANVAS}`);
@@ -336,6 +351,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
     },
     /** Called with the live focus, in the splat's own space, whenever it moves. */
     onFocusChange: null,
+    /** Not on this backend: controls:'page' is a PlayCanvas-backend feature. */
+    setCameraPose() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { engine:'playcanvas', controls:'page' }).",
+      );
+    },
+    getCameraPose: () => null,
     /** Not on this backend: the crossfading asset swap is a PlayCanvas-backend feature. */
     setSource() {
       throw new Error(
@@ -622,6 +644,16 @@ function addSplatDeferred(wall, canvas, src, opts) {
     pending.push([name, args]);
     return name === 'setFocus' ? out : undefined;
   };
+  const page = opts.controls === 'page';
+  const pageOnly = (name) => () => {
+    throw new Error(
+      `@displayxr/inline3d/splat: ${name}() is not available with controls:'page' — the page owns the ` +
+        'camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).',
+    );
+  };
+  // Before the adapter lands, a page calling setCameraPose every frame keeps ONE pending pose
+  // (validated now, so a bad call throws at its own line): last call wins, as it will after.
+  let pendingPose = null;
   const out = {
     backend: 'playcanvas',
     engine: null,
@@ -631,8 +663,30 @@ function addSplatDeferred(wall, canvas, src, opts) {
     camera: null,
     rig: null,
     perf: null,
-    setPose: queue('setPose'),
-    resetPose: queue('resetPose'),
+    setPose: page ? pageOnly('setPose') : queue('setPose'),
+    resetPose: page ? pageOnly('resetPose') : queue('resetPose'),
+    setCameraPose(matrixWorld, o) {
+      if (!page) {
+        throw new Error(
+          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
+            'with the default controls the SDK owns the camera (use setPose).',
+        );
+      }
+      const pose = normalizeCameraPose(matrixWorld, o);
+      if (pendingPose) pendingPose[1] = [pose.matrixWorld, pose];
+      else pending.push((pendingPose = ['setCameraPose', [pose.matrixWorld, pose]]));
+      return out;
+    },
+    getCameraPose: () =>
+      pendingPose
+        ? {
+            matrixWorld: Float32Array.from(pendingPose[1][1].matrixWorld),
+            verticalFovDeg: pendingPose[1][1].verticalFovDeg,
+            near: pendingPose[1][1].near,
+            far: pendingPose[1][1].far,
+            convergence: pendingPose[1][1].convergence,
+          }
+        : null,
     setFocus: queue('setFocus'),
     // A swap requested before the first asset has landed runs once it has (the adapter's own
     // setSource replaces this stub on the same object by then).

package/package.json

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

@@ -304,6 +304,61 @@ export interface SplatOptions {
   observe?: Element;
   /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
   firstWovenHoldMs?: number;
+  /**
+   * Who owns the camera. `'viewer'` (the default): the SDK's orbit, idle spin, auto-fit and focus
+   * gestures. `'page'` (`engine: 'playcanvas'` only; throws on Spark): the page drives the camera
+   * every frame through {@link SplatHandle.setCameraPose} and the adapter keeps only the eye math —
+   * the attach-pattern camera rig, the runtime's projections, the mono fallback. `fit`,
+   * `virtualDisplayHeight`, `orbit`, `idleSpin`, `focusInput` (and the other framing/orbit knobs)
+   * are ignored, named once in a `console.info`; `rig: 'display'` throws.
+   */
+  controls?: 'viewer' | 'page';
+  /**
+   * `controls: 'page'`: the comfort number `ipd × metersToVirtual × convergenceDiopters × 0.5` the
+   * rig is built to, in (0, 1]. Default 0.3, the auto-3D shim's. `metersToVirtual = comfortDepth ·
+   * d / 0.5`, so the depth budget is the same for a 10 cm subject and a 150 m castle.
+   */
+  comfortDepth?: number;
+  /**
+   * `controls: 'page'` only: called once per adapter frame — the wall's session frame in 3D, the
+   * mono rAF in 2D — BEFORE anything renders. Call `handle.setCameraPose(…)` synchronously in
+   * here and THIS frame renders that pose (zero lag, the attach pattern); a pose set from the
+   * page's own rAF may be one frame late, since the two rAFs have no guaranteed order. A throw is
+   * caught and warned once; frames keep rendering.
+   */
+  onBeforeFrame?: (frame: SplatFrameInfo) => void;
+}
+
+/** What `onBeforeFrame` receives. */
+export interface SplatFrameInfo {
+  /** `performance.now()` at the call. */
+  time: number;
+  /** The runtime's view list in 3D (valid only inside the call — copy what you keep); null in mono. */
+  views: readonly XRView[] | null;
+  /** Seconds since the previous call (0 on the first; capped at 0.1). */
+  dt: number;
+}
+
+/** A page camera, as `setCameraPose` takes it and `getCameraPose` returns it. */
+export interface SplatCameraPose {
+  /**
+   * Column-major world matrix of the page camera in the SPLAT's own space (the space of the camera
+   * block's `rest`), three.js convention: looks down −Z, +Y up. Rotation + translation + at most a
+   * UNIFORM scale (a page whose world scales the splat passes `inv(splatWorld) · camera.matrixWorld`;
+   * the scale is how page units reach the adapter). The adapter applies its own OpenCV → engine flip.
+   */
+  matrixWorld: Float32Array;
+  /** Full vertical field of view, degrees. */
+  verticalFovDeg: number;
+  /** Page units. Default 0.001. A floor on every projection's near (depth mapping only). */
+  near: number;
+  /** Page units. Default 5000. A cap on every projection's far. */
+  far: number;
+  /**
+   * Zero-disparity distance along the view axis, page units; null = the adapter's own (the focus
+   * waterfall's, fixed until `setFocus` / `setSource`).
+   */
+  convergence: number | null;
 }
 
 /** `handle.stats()` on `engine: 'playcanvas'`. */
@@ -384,8 +439,21 @@ export interface SplatHandle {
   /** Resolves once the asset has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<SplatHandle>;
 
+  /** Throws on `controls: 'page'` (the page owns the camera). */
   setPose(pose?: OrbitPose): void;
+  /** Throws on `controls: 'page'`. */
   resetPose(): void;
+  /**
+   * `controls: 'page'` only (throws otherwise): the camera for the next frame drawn — call it every
+   * frame you render, ideally inside `onBeforeFrame`. Last call wins; a page that stops calling
+   * keeps its last pose. Throws synchronously on a malformed matrix or lens.
+   */
+  setCameraPose(
+    matrixWorld: ArrayLike<number>,
+    opts: { verticalFovDeg: number; near?: number; far?: number; convergence?: number },
+  ): SplatHandle;
+  /** The last pose the page set (a copy), or null before the first `setCameraPose`. */
+  getCameraPose(): SplatCameraPose | null;
   /**
    * Point the window at something, in the SPLAT's own space (the space the `camera` block's
    * `focus.point` is in). Null returns to whatever the waterfall resolved. Eased unless `snap`.