@displayxr/inline3d 1.25.1 → 1.27.0

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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.27.0 — 2026-09-26
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only) and adds one optional field
+to the core `XRDisplayInfo` type. A page on a browser that does not report the new field sees no
+change.
+
+- **`setLayerRig`'s default `viewerDistance` now comes from the browser.** Where
+  `XRDisplayInfo.nominalViewerPosition` is reported (DisplayXR Browser patch 0221, Windows and
+  Android), the layer rig's n is its **z** — the runtime's nominal viewer distance for the panel,
+  the value its camera rig is calibrated to — instead of the fixed 0.6 m. The tile asks the frame's
+  `XRDisplayLayer.getDisplayInfo()` once, asynchronously; frames drawn before it answers use 0.6 m.
+  A page's `viewerDistance` still wins, and clearing it (`null`) falls back to the browser's value,
+  then 0.6 m. **Pixels move** on a panel whose nominal distance is not 0.6 m: display-rig objects'
+  pop-out scales by 0.6/n (that was the bug); the contact plane and the 2D picture do not move.
+- **`layerRigState().viewerDistanceSource`** — `'page'` | `'browser'` | `'default'` — says where
+  `viewerDistance` came from, and the WARN line prints it: `viewerDistance=0.45m(browser)`.
+- **Types:** `XRDisplayInfo.nominalViewerPosition?: DOMPointReadOnly` (metres, display space, +z
+  out of the glass; absent when unreported), `SplatLayerRigState.viewerDistanceSource`.
+
+## 1.26.0 — 2026-09-25
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive; nothing changes
+for a page that does not call it.
+
+- **`handle.setViewOffset({x, y})`** moves the 2D tier's mono EYE in its own plane, off-axis with
+  the focus plane pinned — a head-parallax analogue for a flat screen with no tracked eyes (a
+  phone's tilt). Normalised and clamped to the unit disc; |offset| = 1 swings the line of sight to
+  the focus by `orbitMaxDeg` (15°), the drag orbit's cone. It moves the eye, not the scene, so it
+  composes with the orbit instead of fighting its relax. A snap (ease it in the page); `null`
+  resets. Mono only: a no-op for the pixels in woven 3D, where the head tracker owns the eyes, and
+  ignored on `controls: 'page'`. **`handle.viewOffset`** reads it back. `pick()` and the effects'
+  eye frame follow the offset camera.
+
 ## 1.25.1 — 2026-09-25
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive; nothing changes

package/index.d.ts

@@ -103,6 +103,16 @@ export interface XRDisplayInfo {
   displayPixelHeight: number;
   recommendedViewScaleX: number;
   recommendedViewScaleY: number;
+  /**
+   * The runtime's NOMINAL viewer position, metres, in display space: origin at the panel
+   * centre, +x right, +y up, +z out of the glass toward the viewer (w = 1). A constant of the
+   * panel — where the runtime seats the viewer when nobody is tracked, and the distance its
+   * camera rig is calibrated to (`z` is that rig's n) — NOT the live eye position.
+   *
+   * Absent on browsers that predate it (DisplayXR Browser patch 0221) and when the runtime
+   * reports nothing usable, so read it as `info.nominalViewerPosition?.z ?? fallback`.
+   */
+  nominalViewerPosition?: DOMPointReadOnly;
 }
 
 /**

package/js/inline3d-splat-layer-rig.js

@@ -16,8 +16,10 @@
 //       view_round_i = view_photo_i · M_i,     proj_round_i = proj_photo_i
 //
 // k = D / (m·n): D the declared convergence (world units), m the declared metersToVirtual, n the
-// nominal viewer distance in metres — the one quantity the browser does not expose (see the
-// design note §5). Everything here is PLAIN ARITHMETIC on arrays, unit-testable without a GPU.
+// nominal viewer distance in metres. n comes from the page's `viewerDistance` if it passed one,
+// else from the browser (XRDisplayInfo.nominalViewerPosition.z, DisplayXR Browser 0221+), else
+// 0.6 m (design note §5, (c)1). Everything here is PLAIN ARITHMETIC on arrays, unit-testable
+// without a GPU.
 
 import { invertAffine } from './inline3d-splat-rig-map.js';
 
@@ -27,6 +29,32 @@ export const LAYER_RIGS = Object.freeze(['display', 'camera']);
 /** Nominal viewer distance (m) when neither the page nor the platform says: the browser's own. */
 export const DEFAULT_VIEWER_DISTANCE_M = 0.6;
 
+/** How many times a tile asks the layer for its display info before giving up (rejections only). */
+const MAX_DISPLAY_INFO_ASKS = 3;
+
+/**
+ * The runtime's nominal viewer DISTANCE n (m) from an XRDisplayInfo, or null when the browser does
+ * not report one. It is the position's **z** — the distance out of the glass along the display
+ * normal — not its length: the runtime's camera rig reads only `nominal_viewer->z`
+ * (displayxr-common dxr_view_math.c, `eye_local.z = m2v·(eye.z − nominal_z)`), and z is what
+ * D/n undoes. A browser without the field, a null info, or a z that is not finite and > 0 → null.
+ */
+export function nominalViewerDistanceFromInfo(info) {
+  const z = info && info.nominalViewerPosition ? info.nominalViewerPosition.z : undefined;
+  return typeof z === 'number' && Number.isFinite(z) && z > 0 ? z : null;
+}
+
+/**
+ * The n the layer rig uses, and where it came from: the page's `viewerDistance` wins ('page'),
+ * then the browser's nominal viewer ('browser'), then DEFAULT_VIEWER_DISTANCE_M ('default').
+ * @returns {{ value: number, source: 'page'|'browser'|'default' }}
+ */
+export function resolveViewerDistance(pageViewerDistance, browserViewerDistance) {
+  if (pageViewerDistance !== null && pageViewerDistance !== undefined) return { value: pageViewerDistance, source: 'page' };
+  if (browserViewerDistance !== null && browserViewerDistance !== undefined) return { value: browserViewerDistance, source: 'browser' };
+  return { value: DEFAULT_VIEWER_DISTANCE_M, source: 'default' };
+}
+
 /** A round eye may not reach the window plane: h(E') is floored at this fraction of D. */
 const MIN_EYE_HEIGHT_FRAC = 1e-3;
 
@@ -45,7 +73,8 @@ export const LAYER_RIG_OPTION_KEYS = Object.freeze(['viewerDistance', 'gain', 'p
 /**
  * setLayerRig / setLayerRigOptions options, validated (throws at the call). Only the keys given
  * are returned: they MERGE into the tile's options. `null` clears a key (back to its default).
- *   viewerDistance  m, > 0     the nominal viewer distance n (default 0.6)
+ *   viewerDistance  m, > 0     the nominal viewer distance n (default: the browser's
+ *                              XRDisplayInfo.nominalViewerPosition.z, else 0.6)
  *   gain            > 0        an explicit rounding gain k instead of D/(m·n)
  *   planeOffset     m, finite  moves the stage TOWARD the viewer by this much on the panel (display
  *                              space): the plane that lands on the glass moves back by offset·D/n
@@ -330,6 +359,11 @@ export class LayerRigCameras {
     this.layers = new Map();
     /** The tile's options: merged across setLayerRig / setLayerRigOptions calls. */
     this.opts = { viewerDistance: null, gain: null, planeOffset: null, planeDistance: null };
+    /** n as the browser reports it (XRDisplayInfo.nominalViewerPosition.z), once known; else null. */
+    this.browserViewerDistance = null;
+    this._infoAsks = 0;
+    this._infoPending = false;
+    this._infoSettled = false;
     this.disabled = false; // the kill switch (diag 'nolayerrig')
     this.cams = { display: [], post: [] };
     this.moved = { display: [], post: [] };
@@ -369,6 +403,41 @@ export class LayerRigCameras {
     for (const [k, v] of Object.entries(o)) this.opts[k] = v;
   }
 
+  /** The n this tile uses right now, and its source ('page' | 'browser' | 'default'). */
+  viewerDistance() {
+    return resolveViewerDistance(this.opts.viewerDistance, this.browserViewerDistance);
+  }
+
+  /**
+   * Called with the frame's XRDisplayLayer: ask it ONCE for the display info and keep the
+   * browser's nominal viewer distance. Asynchronous — frames drawn before it resolves use the
+   * page's value or 0.6 m, and the state's `viewerDistanceSource` says which. A browser without
+   * getDisplayInfo (or without the field) leaves the default in place; a REJECTED ask (e.g. no live
+   * layer yet) is retried on later frames, up to MAX_DISPLAY_INFO_ASKS times.
+   */
+  noteLayer(layer) {
+    if (this._infoSettled || this._infoPending || this._infoAsks >= MAX_DISPLAY_INFO_ASKS) return;
+    if (!layer || typeof layer.getDisplayInfo !== 'function') return;
+    this._infoAsks++;
+    this._infoPending = true;
+    let p;
+    try {
+      p = Promise.resolve(layer.getDisplayInfo());
+    } catch (e) {
+      p = Promise.reject(e);
+    }
+    return p.then(
+      (info) => {
+        this._infoPending = false;
+        this._infoSettled = true;
+        this.browserViewerDistance = nominalViewerDistanceFromInfo(info);
+      },
+      () => {
+        this._infoPending = false;
+      }
+    );
+  }
+
   /** The eye camera entities of the current view path. */
   _eyeCams() {
     const v = this.viewer;
@@ -494,8 +563,9 @@ export class LayerRigCameras {
     L.residual = residual;
     const hasRun = this.sync();
     const frame = cameraRigFrame(rig);
-    const k = frame ? layerRigGain(frame, this.opts) : null;
-    const plane = frame ? layerRigPlane(frame, this.opts) : null;
+    const opts = { ...this.opts, viewerDistance: this.viewerDistance().value };
+    const k = frame ? layerRigGain(frame, opts) : null;
+    const plane = frame ? layerRigPlane(frame, opts) : null;
     L.gain = k;
     L.planeM = plane;
     L.photoConvergenceM = frame ? frame.D : null;
@@ -606,6 +676,7 @@ export class LayerRigCameras {
   /** The public state (handle.layerRigState). */
   state() {
     const L = this.last;
+    const n = this.viewerDistance();
     return {
       display: [...this.requests.keys()],
       disabled: this.disabled,
@@ -613,7 +684,8 @@ export class LayerRigCameras {
       engaged: !!L.engaged,
       rounded: !!L.engaged,
       reason: this.disabled ? 'kill switch (?dxrdiag=nolayerrig)' : L.reason,
-      viewerDistance: this.opts.viewerDistance ?? DEFAULT_VIEWER_DISTANCE_M,
+      viewerDistance: n.value,
+      viewerDistanceSource: n.source,
       gain: L.gain,
       planeM: L.planeM,
       photoConvergenceM: L.photoConvergenceM ?? null,
@@ -634,7 +706,7 @@ export function layerRigLine(st) {
   const n = (x, d = 3) => (x === null || x === undefined ? '-' : Number(x).toFixed(d));
   return (
     `path=${st.path ?? '-'} engaged=${st.engaged} layers=[${st.display.join(', ')}] ` +
-    `viewerDistance=${n(st.viewerDistance, 2)}m gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
+    `viewerDistance=${n(st.viewerDistance, 2)}m(${st.viewerDistanceSource ?? '-'}) gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
     `photoConvergenceM=${n(st.photoConvergenceM)} planeOffset=${n(st.planeOffset)}m ` +
     `located=${st.located === null || st.located === undefined ? '-' : st.located} reason=${st.reason ?? '-'}`
   );

package/js/inline3d-splat-playcanvas.js

@@ -452,6 +452,40 @@ export function pageViewAxis(M) {
   return { origin: [M[12], M[13], M[14]], forward: [-M[8] / fl, -M[9] / fl, -M[10] / fl], scale: s };
 }
 
+/**
+ * handle.setViewOffset — the mono camera moved IN ITS OWN PLANE, off-axis, with the focus plane
+ * pinned. A head-parallax analogue for the 2D tier (a phone's tilt), where there are no tracked
+ * eyes: the eye slides sideways/up, the window through the focus plane stays where it was, so the
+ * focus stays put on screen while nearer content moves against the farther. Not a rotation — the
+ * orbit (setPose / the drag) turns the SCENE about the focus; this moves the EYE, and the two
+ * compose.
+ *
+ *   e = (ox, oy) · c · tan(maxDeg)          camera-plane displacement, display units
+ *   pose' = pose · T(e.x, e.y, 0)
+ *   P'[8] = P[8] − P[0]·e.x / c,  P'[9] = P[9] − P[5]·e.y / c    (the window shifted by −e·n/c)
+ *
+ * `c` is the focus's distance along the camera's view axis, so |offset| = 1 swings the line of
+ * sight to the focus by `maxDeg` — the same comfort cone as the drag orbit (orbitMaxDeg, 15°).
+ * Being an ANGLE it is scale-free: zoom scales the scene about the focus, and c does not move.
+ * Writes into outPose/outProj and returns true; false (outputs untouched) when the offset is zero
+ * or the focus is not in front of the camera — the caller then draws the unshifted camera.
+ */
+export function offsetMonoView(pose, proj, ox, oy, c, maxDeg, outPose, outProj) {
+  if ((!ox && !oy) || !(c > 1e-6) || !Number.isFinite(c)) return false;
+  const k = c * Math.tan(maxDeg * DEG);
+  const ex = ox * k;
+  const ey = oy * k;
+  outPose.set(pose);
+  // pose · T(e): translate along the camera's own x/y axes (columns 0 and 1).
+  outPose[12] = pose[12] + pose[0] * ex + pose[4] * ey;
+  outPose[13] = pose[13] + pose[1] * ex + pose[5] * ey;
+  outPose[14] = pose[14] + pose[2] * ex + pose[6] * ey;
+  outProj.set(proj);
+  outProj[8] = proj[8] - (proj[0] * ex) / c;
+  outProj[9] = proj[9] - (proj[5] * ey) / c;
+  return true;
+}
+
 /**
  * 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
@@ -874,6 +908,10 @@ export class PlayCanvasSplatViewer {
     this._orbitCentre = { x: 0, y: 0, z: 0 };
     this._focusRecentres = true;
     this._focusSettled = true;
+    // handle.setViewOffset: normalised camera-plane eye offset, mono only (offsetMonoView).
+    this._viewOffset = [0, 0];
+    this._offPose = new Float64Array(16);
+    this._offProj = new Float64Array(16);
     this.onFocusChange = null;
     this.onTick = null;
     /** controls:'page' — `(views|null) => void`, run once per frame before anything else. */
@@ -1146,7 +1184,11 @@ export class PlayCanvasSplatViewer {
     if (this._mode !== '3d') this.stopMono();
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
     // and the tick below may declare a new one (a focus ease) for the NEXT locate.
-    if (this.layerRigs?.active) this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+    if (this.layerRigs?.active) {
+      this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+      // n for the layer rig: the browser's nominal viewer, asked once (async; no-op after).
+      this.layerRigs.noteLayer(layer);
+    }
     // Same moment, for the rig map: the rig these views were most likely located for (a tie-break).
     this._rigAtPull = this.rigTrack ? this.rigTrack.latest : null;
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
@@ -1867,12 +1909,40 @@ export class PlayCanvasSplatViewer {
     } else perspectiveFov(this.mono.fov, aspect, this.mono.near, this.mono.far, this.mono.proj);
   }
 
+  /**
+   * handle.setViewOffset — a normalised eye offset in the mono camera's plane (see offsetMonoView),
+   * clamped to the unit disc. Mono only: in woven 3D the head tracker owns the eyes and this is
+   * stored but not drawn; on controls:'page' the page owns the camera and it is ignored. A snap,
+   * like setPose, so the page eases it (and the frame loop draws it next frame).
+   */
+  setViewOffset(x, y) {
+    const r = Math.hypot(x, y);
+    const k = r > 1 ? 1 / r : 1;
+    this._viewOffset[0] = x * k;
+    this._viewOffset[1] = y * k;
+  }
+
+  /** The mono camera as drawn: the offset one when setViewOffset is engaged, else mono itself. */
+  _monoView() {
+    const m = this.mono;
+    const [ox, oy] = this._viewOffset;
+    if (this.pageCamera || (!ox && !oy)) return { proj: m.proj, pose: m.pose };
+    const o = this._orbitCentre;
+    const p = m.pose;
+    // The focus's distance along the view axis (−z): the pivot puts it at the orbit centre.
+    const c = -((o.x - p[12]) * p[8] + (o.y - p[13]) * p[9] + (o.z + this._depthOffset - p[14]) * p[10]);
+    return offsetMonoView(p, m.proj, ox, oy, c, this.orbitMaxDeg, this._offPose, this._offProj)
+      ? { proj: this._offProj, pose: this._offPose }
+      : { proj: m.proj, pose: m.pose };
+  }
+
   _drawMono() {
     const c = this.canvas;
     this._monoEntry ||= [{ proj: this.mono.proj, pose: this.mono.pose, x: 0, y: 0, width: 0, height: 0 }];
     const e = this._monoEntry[0];
-    e.proj = this.mono.proj;
-    e.pose = this.mono.pose;
+    const v = this._monoView();
+    e.proj = v.proj;
+    e.pose = v.pose;
     e.width = c.width;
     e.height = c.height;
     this._drawEntries(this._monoEntry, null);
@@ -2135,7 +2205,7 @@ export class PlayCanvasSplatViewer {
    */
   eyeFrame() {
     const R = this.rigMatrix();
-    const es = this._mode === '3d' && this._lastGood ? this._lastGood.entries : [{ pose: this.mono.pose, proj: this.mono.proj }];
+    const es = this._mode === '3d' && this._lastGood ? this._lastGood.entries : [this._monoView()];
     const o = [0, 0, 0];
     for (const e of es) {
       const M = mat4Mul(R, e.pose);
@@ -2352,7 +2422,7 @@ export class PlayCanvasSplatViewer {
   /** The camera currently on screen: [proj, pose] of the first eye in 3D, the mono camera else. */
   currentView() {
     if (this._mode === '3d' && this._lastGood) return this._lastGood.entries[0];
-    return { proj: this.mono.proj, pose: this.mono.pose };
+    return this._monoView();
   }
 }
 
@@ -2984,6 +3054,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // The current per-eye buffer scale (the `renderScale` option, or the last setRenderScale). A
   // real accessor: Object.assign below would copy a getter's value once.
   Object.defineProperty(out, 'renderScale', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+  // The current eye offset (after the unit-disc clamp), a fresh object per read.
+  Object.defineProperty(out, 'viewOffset', {
+    get: () => ({ x: viewer._viewOffset[0], y: viewer._viewOffset[1] }),
+    enumerable: true,
+    configurable: true,
+  });
   Object.assign(out, {
     backend: 'playcanvas',
     engine: null, // { app, root, camera } once the engine has booted — see below
@@ -3083,6 +3159,23 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       }
       return out;
     },
+    /**
+     * The 2D tier's eye offset: `{x, y}` normalised in the mono camera's plane (+x right, +y up),
+     * clamped to the unit disc; |offset| = 1 swings the line of sight to the focus by orbitMaxDeg
+     * (15°), off-axis so the focus plane stays put — a head-parallax analogue (a phone's tilt)
+     * where there are no tracked eyes. Composes with the orbit. A snap: ease it in the page.
+     * `null` = {0, 0}. Mono only — a no-op for the pixels in woven 3D (the head tracker owns the
+     * eyes; the value is kept for a later fall back to 2D) and on controls:'page'.
+     */
+    setViewOffset(o) {
+      const x = o == null ? 0 : o.x ?? 0;
+      const y = o == null ? 0 : o.y ?? 0;
+      if (typeof x !== 'number' || typeof y !== 'number' || !Number.isFinite(x) || !Number.isFinite(y)) {
+        throw new TypeError('@displayxr/inline3d/splat: setViewOffset takes {x, y} finite numbers (or null).');
+      }
+      viewer.setViewOffset(x, y);
+      return out;
+    },
     /** Change the layer rig's tile-wide options live (no layer change): merge, `null` clears. */
     setLayerRigOptions(o = {}) {
       layerRigs().setOptions(validateLayerRigOptions(o, 'setLayerRigOptions'));
@@ -3097,7 +3190,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     layerRigState() {
       const lr = viewer.layerRigs;
       if (lr) return lr.state();
-      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
+      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, viewerDistanceSource: 'default', gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
     },
     /**
      * An unlit material showing the left half of `texture` to left-eye views and the right half to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.25.1",
+  "version": "1.27.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

@@ -185,7 +185,11 @@ export interface ResolvedRig {
  * viewer's. docs/proposals/layer-display-rig.md.
  */
 export interface SplatLayerRigOptions {
-  /** Nominal viewer distance in metres (default 0.6, the browser's own nominal). */
+  /**
+   * Nominal viewer distance n in metres. Default: the browser's
+   * `XRDisplayInfo.nominalViewerPosition.z` where it reports one, else 0.6. Passing it pins n
+   * (see {@link SplatLayerRigState.viewerDistanceSource}).
+   */
   viewerDistance?: number | null;
   /** An explicit gain k instead (1 = exactly the photo rig; larger = rounder). */
   gain?: number | null;
@@ -216,7 +220,14 @@ export interface SplatLayerRigState {
   rounded: boolean;
   /** Why not engaged (or what is wrong with some layers while engaged); null when all is well. */
   reason: string | null;
+  /** The n in use (metres). */
   viewerDistance: number;
+  /**
+   * Where `viewerDistance` came from: the page's option, the browser's reported nominal viewer
+   * (`XRDisplayInfo.nominalViewerPosition.z`, asked once per tile, asynchronously — early frames
+   * may read 'default' before it lands), or the 0.6 m fallback.
+   */
+  viewerDistanceSource: 'page' | 'browser' | 'default';
   /** The gain the last frame used (null off a camera rig). */
   gain: number | null;
   /** The plane that lands on the glass, as a distance from the photo's camera (world units). */
@@ -1002,6 +1013,21 @@ export interface SplatHandle {
   setRenderScale(scale: number): SplatHandle;
   /** `engine: 'playcanvas'` only. The current per-eye buffer scale. */
   readonly renderScale: number;
+  /**
+   * `engine: 'playcanvas'` only. The 2D tier's EYE offset — a head-parallax analogue for a flat
+   * screen with no tracked eyes (e.g. a phone's tilt). `{x, y}` is normalised in the mono camera's
+   * plane (+x right, +y up) and clamped to the unit disc; |offset| = 1 moves the eye far enough to
+   * swing its line of sight to the focus by `orbitMaxDeg` (15° by default), the drag orbit's comfort
+   * cone. Off-axis: the focus plane stays put on screen while nearer content moves against the
+   * farther. It moves the eye, not the scene, so it composes with the orbit (`setPose`, the drag)
+   * rather than fighting it. A snap, like `setPose` — ease it in the page. `null` resets to
+   * `{0, 0}`. Mono only: in woven 3D the head tracker owns the eyes, so the value is kept (it applies
+   * again if the tile falls back to 2D) but draws nothing; ignored on `controls: 'page'`. Throws a
+   * TypeError on a non-finite component.
+   */
+  setViewOffset(offset: { x?: number; y?: number } | null): SplatHandle;
+  /** `engine: 'playcanvas'` only. The current eye offset (after the unit-disc clamp). */
+  readonly viewOffset: { x: number; y: number };
   /** `engine: 'playcanvas'` only. Change the layer rig's tile-wide options live (merge; `null` clears). */
   setLayerRigOptions(opts: SplatLayerRigOptions): SplatHandle;
   /**