@displayxr/inline3d 1.18.0 → 1.19.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.19.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat` and `./model`, `engine: 'playcanvas'` only). The defaults
+keep the wheel's pixels. One default does change: a two-finger touch now pinch-zooms (within the
+old 0.2–6 range, with no relax) where it used to act as an erratic one-finger drag.
+
+### Added
+
+- **`zoom: { min, max, relax, ease }`** (#36), bounded zoom that relaxes back to rest.
+  - Wheel, pinch and `setPose` clamp to `[min, max]`. Defaults are 0.2 and 6, as before.
+  - `relax: true` eases back to rest (1×, or the last `setPose` zoom) once the wheel has been idle
+    150 ms or the pinch ends. It uses the orbit's τ 0.6 s, with a landing floor so 2× is exactly
+    home in about 2.9 s, and it never fights a live gesture.
+  - The zoom scales about the focus, so the focus keeps its place and its disparity in both eyes.
+  - The gallery's Spatial View passes `{ min: 1, max: 2, relax: true }`: you can't zoom out past
+    the frame's edges, and a peek comes back on its own.
+- **Two-finger pinch zoom** on the PlayCanvas viewer, with Pointer Events and the same bounds.
+- Gates, on a real GPU (1280×720):
+  - Zooming out is refused: MAE 0 against the rest render.
+  - Wheel and pinch reach the 2× cap and return to **MAE 0** against rest 3 s after release.
+  - In fake stereo, the focus's disparity is unchanged at 1×, 1.5× and 2×.
+
 ## 1.18.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive: a page that never

package/README.md

@@ -45,7 +45,8 @@ API is not yet covered by the semver promise below.
 renders the same splat window with the [PlayCanvas](https://playcanvas.com/) engine instead of
 Spark — same handle, same rig/focus/camera-block behaviour, same `perf` presets (mapped onto the
 engine's knobs) — and adds `setSource(src, { fadeMs })` (crossfading asset swaps), `feather`, a
-tilt-and-relax orbit, `handle.engine` (the engine objects, for advanced pages) and
+tilt-and-relax orbit, two-finger pinch plus bounded zoom that relaxes back to rest
+(`zoom: { min, max, relax }`, [§Zoom bounds and relax](docs/playcanvas-adapter.md#zoom-bounds-and-relax)), `handle.engine` (the engine objects, for advanced pages) and
 `handle.setRig('display' | 'camera' | 'auto')`: a live, reversible rig switch, so one persistent tile
 can show a glTF under `handle.engine.root` exactly as `addModel` would and then go back to the photo's
 capture rig ([§setRig](docs/playcanvas-adapter.md#setrig--switching-between-the-display-rig-and-the-camera-rig-36)), and

package/js/inline3d-model-entry.js

@@ -54,7 +54,7 @@ export function resolveModelEngine(opts = {}) {
 }
 
 /** Options that exist only on the PlayCanvas backend: an error on an explicit engine:'three'. */
-const PLAYCANVAS_ONLY = ['playcanvas', 'environmentRotation', 'controls', 'comfortDepth', 'onBeforeFrame', 'antialias', 'preserveDrawingBuffer', 'nearClip', 'farClip', 'orbitMaxDeg', 'orbitEase'];
+const PLAYCANVAS_ONLY = ['playcanvas', 'environmentRotation', 'controls', 'comfortDepth', 'onBeforeFrame', 'antialias', 'preserveDrawingBuffer', 'nearClip', 'farClip', 'orbitMaxDeg', 'orbitEase', 'zoom'];
 
 /**
  * Everything that can be checked before a module loads. Throws at CALL time — a page bug is true

package/js/inline3d-model-playcanvas.js

@@ -903,6 +903,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     flipY: false, // glTF is already Y-up
     orbitMaxDeg: opts.orbitMaxDeg,
     orbitEase: opts.orbitEase,
+    zoom: opts.zoom,
     feather,
     nearClip: opts.nearClip,
     farClip: opts.farClip,

package/js/inline3d-splat-playcanvas.js

@@ -84,8 +84,9 @@ import {
   WHEEL_PAGE_PX,
   WHEEL_MAX_PX,
   ZOOM_PER_PX,
-  ZOOM_MIN,
-  ZOOM_MAX,
+  ZOOM_WHEEL_IDLE_MS,
+  ZOOM_RELAX_MIN_RATE,
+  resolveZoomOption,
   MONO_FOV,
   MONO_NEAR,
   MONO_FAR,
@@ -628,6 +629,7 @@ export class PlayCanvasSplatViewer {
       pitchLimit = PITCH_LIMIT,
       orbitMaxDeg = ORBIT_MAX_DEG,
       orbitEase = {},
+      zoom,
       feather = 0,
       captureFit = 'height',
       nearClip,
@@ -665,6 +667,15 @@ export class PlayCanvasSplatViewer {
     this.orbitMaxDeg = orbitMaxDeg;
     this.orbitEase = { drag: orbitEase.drag ?? ORBIT_TAU_DRAG_S, rest: orbitEase.rest ?? ORBIT_TAU_REST_S };
     this._orbitMode = null;
+    // Zoom bounds + relax (./inline3d-splat-shared.js §ZOOM). Wheel and pinch clamp to
+    // [zoomOpts.min, zoomOpts.max]; with relax, the zoom eases back to `_restZoom` (1×, or the
+    // last setPose zoom) once the wheel is idle or the pinch ends. `_zoomMode` is 'rest' while
+    // relaxing, else null (the ordinary damping). `_pinching` holds the relax off.
+    this.zoomOpts = resolveZoomOption(zoom);
+    this._zoomMode = null;
+    this._restZoom = clamp(1, this.zoomOpts.min, this.zoomOpts.max);
+    this._lastWheel = 0;
+    this._pinching = false;
     /** handle.setVideo: orbit/zoom input ignored while a video plane is on. */
     this.inputLocked = false;
     /** handle.setVideo's plane (./inline3d-splat-video.js) while a video is on, else null. */
@@ -693,8 +704,8 @@ export class PlayCanvasSplatViewer {
     this.flipY = opts.flipY !== false;
 
     this._fitScale = 1;
-    this._zoom = 1;
-    this._targetZoom = 1;
+    this._zoom = this._restZoom;
+    this._targetZoom = this._restZoom;
     this._depthOffset = 0;
     this._subjectHalf = [0, 0, 0];
     this._yaw = 0;
@@ -815,7 +826,11 @@ export class PlayCanvasSplatViewer {
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
-    if (zoom !== undefined) this._targetZoom = this._zoom = clamp(zoom, ZOOM_MIN, ZOOM_MAX);
+    if (zoom !== undefined) {
+      // A snap, and the new rest: a relax comes home HERE, not to 1×.
+      this._targetZoom = this._zoom = this._restZoom = clamp(zoom, this.zoomOpts.min, this.zoomOpts.max);
+      this._zoomMode = null;
+    }
     if (depthOffset !== undefined) this._depthOffset = finite(depthOffset, this._depthOffset);
     this._applyTransform();
   }
@@ -1748,7 +1763,33 @@ export class PlayCanvasSplatViewer {
     ) {
       this._orbitMode = null; // at rest: the ordinary damping (and the idle turntable) take over
     }
-    if (Math.abs(this._targetZoom - this._zoom) > 1e-4) {
+    // Zoom relax: the wheel has gone idle (or the pinch ended) away from rest — head home.
+    if (
+      this.zoomOpts.relax &&
+      !this._zoomMode &&
+      !this._pinching &&
+      t - this._lastWheel > ZOOM_WHEEL_IDLE_MS &&
+      Math.abs(this._targetZoom - this._restZoom) > 1e-6
+    ) {
+      this._targetZoom = this._restZoom;
+      this._zoomMode = 'rest';
+    }
+    // Relaxing eases with τ = zoomOpts.ease (the orbit's 0.6 s by default); the wheel's own
+    // damping otherwise. Both in log space, so 2× → 1× reads like 1× → ½×.
+    if (this._zoomMode === 'rest') {
+      // The exponential (τ = zoomOpts.ease) with a landing floor: it never moves slower than
+      // ZOOM_RELAX_MIN_RATE (log-zoom per second), so it ARRIVES — 2× is home in ≈3 s — instead of
+      // creeping in forever or popping at a snap. Above ~1 % from home the floor never binds.
+      const gap = Math.log(this._targetZoom / this._zoom);
+      const ko = dt > 0 ? 1 - Math.exp(-dt / this.zoomOpts.ease) : 0;
+      const step = Math.min(Math.abs(gap), Math.max(Math.abs(gap) * ko, ZOOM_RELAX_MIN_RATE * dt));
+      if (Math.abs(gap) - step < 1e-6) {
+        this._zoom = this._targetZoom;
+        this._zoomMode = null;
+      } else {
+        this._zoom *= Math.exp(Math.sign(gap) * step);
+      }
+    } else if (Math.abs(this._targetZoom - this._zoom) > 1e-4) {
       this._zoom *= Math.pow(this._targetZoom / this._zoom, k);
     } else {
       this._zoom = this._targetZoom;
@@ -1869,8 +1910,41 @@ export class PlayCanvasSplatViewer {
     let startY = 0;
     let restYaw = 0;
     let restPitch = 0;
+    // Pinch: two pointers down zoom by the ratio of their spread, about the focus (the pivot's
+    // scale is S(fit × zoom) about it), within zoomOpts' bounds. The drag ends when the second
+    // finger lands (its tilt relaxes); the finger left after a pinch does not orbit.
+    const pointers = new Map(); // pointerId → [clientX, clientY]
+    let pinchD0 = 0;
+    let pinchZ0 = 1;
+    const spread = () => {
+      const [a, b] = [...pointers.values()];
+      return Math.hypot(a[0] - b[0], a[1] - b[1]);
+    };
+    const endDrag = () => {
+      dragging = false;
+      this._targetYaw = restYaw;
+      this._targetPitch = clamp(restPitch, this.pitchLimit[0], this.pitchLimit[1]);
+      this._orbitMode = 'rest';
+    };
     this._onDown = (ev) => {
       if (this.inputLocked) return; // handle.setVideo: a screen-locked plane has nothing to orbit
+      if (ev.pointerId !== undefined) pointers.set(ev.pointerId, [ev.clientX, ev.clientY]);
+      try {
+        el.setPointerCapture?.(ev.pointerId);
+      } catch {
+        // An inactive pointer id (a synthetic event) throws; the gesture works without capture.
+      }
+      if (pointers.size === 2) {
+        if (dragging) endDrag();
+        this._pinching = true;
+        this._zoomMode = null; // a new gesture takes over from a relax
+        pinchD0 = Math.max(spread(), 1);
+        pinchZ0 = this._zoom;
+        this._targetZoom = this._zoom;
+        this._lastInput = now();
+        return;
+      }
+      if (pointers.size > 2) return;
       dragging = true;
       startX = ev.clientX;
       startY = ev.clientY;
@@ -1879,9 +1953,16 @@ export class PlayCanvasSplatViewer {
       restPitch = this._orbitMode ? restPitch : this._targetPitch;
       this._orbitMode = 'drag';
       this._lastInput = now();
-      el.setPointerCapture?.(ev.pointerId);
     };
     this._onMove = (ev) => {
+      if (pointers.has(ev.pointerId)) pointers.set(ev.pointerId, [ev.clientX, ev.clientY]);
+      if (this._pinching) {
+        if (pointers.size < 2) return;
+        const { min, max } = this.zoomOpts;
+        this._targetZoom = clamp(pinchZ0 * (spread() / pinchD0), min, max);
+        this._lastInput = now();
+        return;
+      }
       if (!dragging) return;
       const box = el.getBoundingClientRect();
       const dx = (ev.clientX - startX) / Math.max(box.width, 1);
@@ -1896,13 +1977,21 @@ export class PlayCanvasSplatViewer {
       this._lastInput = now();
     };
     this._onUp = (ev) => {
+      const had = pointers.delete(ev.pointerId);
+      if (this._pinching && pointers.size < 2) {
+        // The pinch ends when either finger lifts: the zoom relaxes (zoomOpts.relax) from here.
+        this._pinching = false;
+        this._lastWheel = now() - ZOOM_WHEEL_IDLE_MS - 1;
+        this._lastInput = now();
+      }
+      try {
+        if (had || ev.pointerId === undefined) el.releasePointerCapture?.(ev.pointerId);
+      } catch {
+        // see pointerdown
+      }
       if (!dragging) return;
-      dragging = false;
-      this._targetYaw = restYaw;
-      this._targetPitch = clamp(restPitch, this.pitchLimit[0], this.pitchLimit[1]);
-      this._orbitMode = 'rest';
+      endDrag();
       this._lastInput = now();
-      el.releasePointerCapture?.(ev.pointerId);
     };
     this._onWheel = (ev) => {
       if (this.inputLocked) return;
@@ -1911,7 +2000,11 @@ export class PlayCanvasSplatViewer {
       if (ev.deltaMode === 1) px *= WHEEL_LINE_PX;
       else if (ev.deltaMode === 2) px *= WHEEL_PAGE_PX;
       px = clamp(px, -WHEEL_MAX_PX, WHEEL_MAX_PX);
-      this._targetZoom = clamp(this._targetZoom * Math.exp(-px * ZOOM_PER_PX), ZOOM_MIN, ZOOM_MAX);
+      // A wheel tick during a relax restarts from where the zoom IS, not from the rest target.
+      const from = this._zoomMode === 'rest' ? this._zoom : this._targetZoom;
+      this._zoomMode = null;
+      this._targetZoom = clamp(from * Math.exp(-px * ZOOM_PER_PX), this.zoomOpts.min, this.zoomOpts.max);
+      this._lastWheel = now();
       this._lastInput = now();
     };
     if (el.style) el.style.touchAction = 'none';
@@ -1933,6 +2026,7 @@ export class PlayCanvasSplatViewer {
     el.removeEventListener('pointerleave', this._onUp);
     el.removeEventListener('wheel', this._onWheel);
     this._onDown = null;
+    this._pinching = false;
   }
 
   /** The camera currently on screen: [proj, pose] of the first eye in 3D, the mono camera else. */
@@ -2425,6 +2519,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     flipY,
     orbitMaxDeg: opts.orbitMaxDeg,
     orbitEase: opts.orbitEase,
+    zoom: opts.zoom,
     feather,
     captureFit,
     nearClip: opts.nearClip,

package/js/inline3d-splat-shared.js

@@ -238,6 +238,49 @@ export const ORBIT_TAU_DRAG_S = 0.2;
 /** Time constant of the relax back to rest after release, seconds. */
 export const ORBIT_TAU_REST_S = 0.6;
 
+// ── ZOOM: bounds + relax (the PlayCanvas backend's `zoom` option) ───────────────────────────
+
+/** Wheel "release": this long with no wheel event ends the gesture and starts the relax, ms. */
+export const ZOOM_WHEEL_IDLE_MS = 150;
+/**
+ * The zoom relax's landing floor, log-zoom per second. The relax is the orbit's exponential
+ * (τ = 0.6 s), except it never moves slower than this, so it lands in finite time: from 2× the
+ * exponential carries it to 1.5 % from home in ≈2.3 s and the floor finishes in ≈0.6 s more.
+ */
+export const ZOOM_RELAX_MIN_RATE = 0.025;
+
+/**
+ * Validate + default the `zoom` option: `{ min, max, relax, ease }`.
+ *
+ * Defaults are today's behaviour — ZOOM_MIN..ZOOM_MAX, no relax. `relax: true` eases the zoom
+ * back to its rest (1×, or the last setPose zoom) once the wheel has been idle
+ * ZOOM_WHEEL_IDLE_MS or a pinch ends, with τ = `ease` (default ORBIT_TAU_REST_S, the orbit's
+ * relax — the two gestures come home together).
+ *
+ * @returns {{min:number, max:number, relax:boolean, ease:number}}
+ */
+export function resolveZoomOption(zoom) {
+  if (zoom === undefined || zoom === null) return { min: ZOOM_MIN, max: ZOOM_MAX, relax: false, ease: ORBIT_TAU_REST_S };
+  if (typeof zoom !== 'object') {
+    throw new Error(`@displayxr/inline3d/splat: zoom ${zoom} — expected { min, max, relax, ease }.`);
+  }
+  const num = (k, v, d) => {
+    if (v === undefined) return d;
+    if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) {
+      throw new Error(`@displayxr/inline3d/splat: zoom.${k} ${v} — expected a positive number.`);
+    }
+    return v;
+  };
+  const min = num('min', zoom.min, ZOOM_MIN);
+  const max = num('max', zoom.max, ZOOM_MAX);
+  if (max < min) throw new Error(`@displayxr/inline3d/splat: zoom.max ${max} is below zoom.min ${min}.`);
+  const ease = num('ease', zoom.ease, ORBIT_TAU_REST_S);
+  if (zoom.relax !== undefined && typeof zoom.relax !== 'boolean') {
+    throw new Error(`@displayxr/inline3d/splat: zoom.relax ${zoom.relax} — expected true or false.`);
+  }
+  return { min, max, relax: zoom.relax === true, ease };
+}
+
 /**
  * The capture camera's off-axis WINDOW at the near plane — the one projection both backends'
  * camera rigs draw the mono (flat) view through. Principal point honoured, so a deconverged
@@ -346,6 +389,7 @@ export const PAGE_IGNORED_OPTIONS = Object.freeze([
   'depthLimit',
   'orbitMaxDeg',
   'orbitEase',
+  'zoom',
   'captureFit',
 ]);
 

package/model.d.ts

@@ -117,6 +117,8 @@ export interface ModelOptions {
   orbitMaxDeg?: number;
   /** PlayCanvas only: the orbit's easing time constants, seconds. */
   orbitEase?: { drag?: number; rest?: number };
+  /** PlayCanvas only: zoom bounds + relax (wheel, pinch, setPose) — see the splat option. */
+  zoom?: { min?: number; max?: number; relax?: boolean; ease?: number };
   /**
    * PlayCanvas only: who owns the camera — the SDK's viewer (default) or the page, through
    * {@link ModelHandle.setCameraPose} every frame (the attach rig; converges on the model's bounds

package/package.json

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

@@ -259,6 +259,15 @@ export interface SplatOptions {
   orbitMaxDeg?: number;
   /** PlayCanvas: easing time constants, seconds — `drag` while held (0.2), `rest` after release (0.6). */
   orbitEase?: { drag?: number; rest?: number };
+  /**
+   * PlayCanvas: zoom bounds + relax, for the wheel, the two-finger pinch and `setPose`. `min` /
+   * `max` clamp the zoom (defaults 0.2 / 6, the pre-1.19 range); `relax: true` eases it back to
+   * rest — 1×, or the last `setPose` zoom — once the wheel has been idle 150 ms or the pinch ends,
+   * with the orbit's time constant (`ease`, default 0.6 s) and a landing floor so it arrives (2×
+   * is home in ≈3 s). The zoom scales the subject about the focus, which keeps its screen position
+   * and its disparity. `{ min: 1, max: 2, relax: true }` is a peek that never shows the splat's edges.
+   */
+  zoom?: { min?: number; max?: number; relax?: boolean; ease?: number };
   fit?: 'contain' | 'height' | 'cover' | 'none';
   /** Fraction of the tile the subject may occupy (default 0.8) — width AND height. */
   margin?: number;