@displayxr/inline3d 1.49.3 → 1.51.0

package/js/inline3d-splat-playcanvas.js

@@ -380,13 +380,15 @@ const FLIP_Q = [1, 0, 0, 0];
 /**
  * SceneViewer's pivot as ONE matrix: content space → display space.
  *
- *   M = T(orbitCentre + (0,0,depthOffset)) · Rx(pitch) · Ry(yaw) · S(fit × zoom) · T(−focus)
+ *   M = T(orbitCentre + (0,0,depthOffset)) · Rz(roll) · Rx(pitch) · Ry(yaw) · S(fit × zoom) · T(−focus)
  *
- * which is exactly the product of its `_pivot` (position, 'XYZ' rotation, scale) and
+ * which is exactly the product of its `_pivot` (position, 'ZXY' rotation, scale) and
  * `_centering` (−focus) groups. Kept as a pure function so a test can hold the two together.
+ * Roll (the two-hand twist) is about the VIEW axis, so it sits outside yaw and pitch; at roll 0
+ * this is the old Rx · Ry product bit for bit.
  */
-export function pivotMatrix({ yaw = 0, pitch = 0, scale = 1, focus = [0, 0, 0], orbitCentre = [0, 0, 0], depthOffset = 0 }) {
-  const q = pivotQuat(yaw, pitch);
+export function pivotMatrix({ yaw = 0, pitch = 0, roll = 0, scale = 1, focus = [0, 0, 0], orbitCentre = [0, 0, 0], depthOffset = 0 }) {
+  const q = pivotQuat(yaw, pitch, roll);
   const R = poseMatrix([0, 0, 0], q);
   const out = new Float64Array(16);
   // columns of R·S
@@ -400,19 +402,25 @@ export function pivotMatrix({ yaw = 0, pitch = 0, scale = 1, focus = [0, 0, 0],
   return out;
 }
 
-/** R = Rx(pitch)·Ry(yaw) — three's Euler order 'XYZ' — as a quaternion. */
-function pivotQuat(yawDeg, pitchDeg) {
+/**
+ * R = Rz(roll)·Rx(pitch)·Ry(yaw) — three's Euler order 'ZXY', SceneViewer's — as a quaternion.
+ * With roll 0 the Rz factor is the identity quaternion and the product is exactly Rx·Ry.
+ */
+function pivotQuat(yawDeg, pitchDeg, rollDeg = 0) {
   const a = (pitchDeg * DEG) / 2;
   const b = (yawDeg * DEG) / 2;
-  return qmul([Math.sin(a), 0, 0, Math.cos(a)], [0, Math.sin(b), 0, Math.cos(b)]);
+  const q = qmul([Math.sin(a), 0, 0, Math.cos(a)], [0, Math.sin(b), 0, Math.cos(b)]);
+  if (!rollDeg) return q;
+  const c = (rollDeg * DEG) / 2;
+  return qmul([0, 0, Math.sin(c), Math.cos(c)], q);
 }
 
 /**
  * The INVERSE pivot, as the TRS the engine's rig node takes. M⁻¹ = T(f)·S(1/s)·Rᵀ·T(−t), and a
  * uniform scale commutes with a rotation, so it is position f − Rᵀt/s, rotation Rᵀ, scale 1/s.
  */
-export function pivotInverseTRS({ yaw = 0, pitch = 0, scale = 1, focus = [0, 0, 0], orbitCentre = [0, 0, 0], depthOffset = 0 }) {
-  const q = pivotQuat(yaw, pitch);
+export function pivotInverseTRS({ yaw = 0, pitch = 0, roll = 0, scale = 1, focus = [0, 0, 0], orbitCentre = [0, 0, 0], depthOffset = 0 }) {
+  const q = pivotQuat(yaw, pitch, roll);
   const qi = [-q[0], -q[1], -q[2], q[3]];
   const t = [orbitCentre[0], orbitCentre[1], orbitCentre[2] + depthOffset];
   const rt = qrot(qi, t);
@@ -579,14 +587,22 @@ export function capturePose(rest, flipY) {
  * (epic #36, P4d); until then the anchors are regexes (the npm build re-indents chunks with
  * tabs) and a miss warns once and renders unpatched rather than failing.
  *
+ * PlayCanvas 2.23 fixed it upstream: its perspective branch takes the focal length per axis
+ * (`vec2 focal = viewport_size.xy * vec2(center.projMat00, center.projMat11)`). That chunk is
+ * returned untouched with `native: true` and counts as fixed — it is not a miss, and must not
+ * warn that splats will draw at half height.
+ *
  * The rewritten lines are adapted from PlayCanvas engine src/scene/shader-lib/glsl/chunks/gsplat/vert/
  * gsplatCorner.js (the `gsplatCornerVS` chunk) @ v2.22.3, MIT (THIRD_PARTY_NOTICES.md).
  *
- * @returns {{src:string, ok:boolean}}
+ * @returns {{src:string, ok:boolean, native?:boolean}}
  */
 export function patchGsplatFootprint(src) {
   if (typeof src !== 'string') return { src, ok: false };
   if (src.includes('dxrFocalY')) return { src, ok: true };
+  if (/vec2\s+focal\s*=\s*viewport_size\.xy\s*\*\s*vec2\s*\(\s*center\.projMat00\s*,\s*center\.projMat11\s*\)/.test(src)) {
+    return { src, ok: true, native: true };
+  }
   const r1 = /vec2\s+J2\s*=\s*-J1\s*\/\s*vp\.z\s*\*\s*vp\.xy\s*;/;
   const r2 = /0\.0\s*,\s*J1\s*,\s*J2\.y\s*,/;
   if (!r1.test(src) || !r2.test(src)) return { src, ok: false };
@@ -952,6 +968,11 @@ export class PlayCanvasSplatViewer {
     this._pitch = 0;
     this._targetYaw = 0;
     this._targetPitch = 0;
+    // Roll about the VIEW axis, degrees — SceneViewer's. Only the two-hand gesture
+    // (./inline3d-hands.js) and an explicit setPose({ roll }) write it, so every existing page is
+    // bit-identical at 0.
+    this._roll = 0;
+    this._targetRoll = 0;
     this._focus = { x: 0, y: 0, z: 0 };
     this._targetFocus = { x: 0, y: 0, z: 0 };
     this._orbitCentre = { x: 0, y: 0, z: 0 };
@@ -1066,7 +1087,7 @@ export class PlayCanvasSplatViewer {
     this._placeMonoForFit();
   }
 
-  setPose({ yaw, pitch, zoom, depthOffset } = {}) {
+  setPose({ yaw, pitch, zoom, roll, 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;
@@ -1074,6 +1095,7 @@ export class PlayCanvasSplatViewer {
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
+    if (roll !== undefined) this._targetRoll = this._roll = roll;
     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);
@@ -1088,13 +1110,35 @@ export class PlayCanvasSplatViewer {
       yaw: target ? this._targetYaw : this._yaw,
       pitch: target ? this._targetPitch : this._pitch,
       zoom: target ? this._targetZoom : this._zoom,
+      roll: target ? this._targetRoll : this._roll,
       depthOffset: this._depthOffset,
     };
   }
 
+  /**
+   * Move the pose by a delta, eased — SceneViewer.nudgePose's twin, what the hands
+   * (`@displayxr/inline3d/hands`) drive. Degrees to add, zoom a ratio to multiply (within
+   * `zoomOpts`, and it becomes the new REST, as a setPose zoom does, so a relax does not undo a
+   * two-hand zoom). Roll (the two-hand twist) is degrees about the view axis, as on SceneViewer.
+   * Counts as interaction for the idle turntable and ends an orbit relax, like a drag.
+   */
+  nudgePose({ yaw = 0, pitch = 0, zoom = 1, roll = 0 } = {}) {
+    if (this.pageCamera) throw new Error(PAGE_POSE_ERROR);
+    if (yaw || pitch) this._orbitMode = null;
+    if (yaw) this._targetYaw += yaw;
+    if (pitch) this._targetPitch = clamp(this._targetPitch + pitch, this.pitchLimit[0], this.pitchLimit[1]);
+    if (roll) this._targetRoll += roll;
+    if (zoom && zoom !== 1) {
+      const from = this._zoomMode === 'rest' ? this._zoom : this._targetZoom;
+      this._targetZoom = this._restZoom = clamp(from * zoom, this.zoomOpts.min, this.zoomOpts.max);
+      this._zoomMode = null;
+    }
+    this._lastInput = now();
+  }
+
   resetPose() {
     if (this.pageCamera) throw new Error(PAGE_POSE_ERROR);
-    this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
+    this.setPose({ yaw: 0, pitch: 0, zoom: 1, roll: 0, depthOffset: 0 });
     this._lastInput = now();
   }
 
@@ -1103,12 +1147,19 @@ export class PlayCanvasSplatViewer {
     const s = this._fitScale * this._zoom;
     const [hx, hy, hz] = this._subjectHalf;
     // SceneViewer's exact arithmetic (degrees → radians as `(d * Math.PI) / 180`), so the two
-    // viewers report bit-identical boxes (pinned by the behavioural-trace test).
+    // viewers report bit-identical boxes (pinned by the behavioural-trace test). Rows of
+    // R = Rz(roll) · Rx(pitch) · Ry(yaw), |row| · half = the AABB half-extent along that axis;
+    // at roll 0 the first two rows are the old Rx · Ry rows exactly.
     const p = (this._pitch * Math.PI) / 180;
     const y = (this._yaw * Math.PI) / 180;
+    const r = (this._roll * Math.PI) / 180;
     const cp = Math.cos(p), sp = Math.sin(p), cy = Math.cos(y), sy = Math.sin(y);
-    const ex = s * (Math.abs(cy) * hx + Math.abs(sy) * hz);
-    const ey = s * (Math.abs(sp * sy) * hx + Math.abs(cp) * hy + Math.abs(sp * cy) * hz);
+    const cr = Math.cos(r), sr = Math.sin(r);
+    // Rx . Ry rows
+    const a0 = cy, a1 = 0, a2 = sy;
+    const b0 = sp * sy, b1 = cp, b2 = -sp * cy;
+    const ex = s * (Math.abs(cr * a0 - sr * b0) * hx + Math.abs(cr * a1 - sr * b1) * hy + Math.abs(cr * a2 - sr * b2) * hz);
+    const ey = s * (Math.abs(sr * a0 + cr * b0) * hx + Math.abs(sr * a1 + cr * b1) * hy + Math.abs(sr * a2 + cr * b2) * hz);
     const ez = s * (Math.abs(cp * sy) * hx + Math.abs(sp) * hy + Math.abs(cp * cy) * hz);
     const cz = this._depthOffset;
     return {
@@ -1499,7 +1550,7 @@ export class PlayCanvasSplatViewer {
     // handle.engine.root on a model tile gets the engine's stock footprint (documented).
     const chunks = patchSplats ? pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL) : null;
     const corner = chunks ? patchGsplatFootprint(chunks.get('gsplatCornerVS')) : { ok: false, skipped: true };
-    if (corner.ok) chunks.set('gsplatCornerVS', corner.src);
+    if (corner.ok && !corner.native) chunks.set('gsplatCornerVS', corner.src);
     else if (!corner.skipped && !warnedFootprint) {
       warnedFootprint = true;
       console.warn(
@@ -2472,6 +2523,8 @@ export class PlayCanvasSplatViewer {
     const ko = tau > 0 ? (dt > 0 ? 1 - Math.exp(-dt / tau) : 0) : k;
     this._yaw += (this._targetYaw - this._yaw) * ko;
     this._pitch += (this._targetPitch - this._pitch) * ko;
+    // Roll has no drag / relax phase (only the hands and setPose write it): the ordinary damping.
+    if (this._roll !== this._targetRoll) this._roll += (this._targetRoll - this._roll) * k;
     if (
       this._orbitMode === 'rest' &&
       Math.abs(this._targetYaw - this._yaw) < 0.01 &&
@@ -2608,6 +2661,7 @@ export class PlayCanvasSplatViewer {
     return {
       yaw: this._yaw,
       pitch: this._pitch,
+      roll: this._roll,
       scale: this._fitScale * this._zoom,
       focus: [f.x, f.y, f.z],
       orbitCentre: [o.x, o.y, o.z],
@@ -4922,6 +4976,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       mono: { fov: v.mono.fov, near: v.mono.near, far: v.mono.far, pose: Float64Array.from(v.mono.pose), capture: v.mono.capture },
       pose: {
         _yaw: v._yaw, _pitch: v._pitch, _targetYaw: v._targetYaw, _targetPitch: v._targetPitch,
+        _roll: v._roll, _targetRoll: v._targetRoll,
         _zoom: v._zoom, _targetZoom: v._targetZoom, _depthOffset: v._depthOffset,
         _focusSettled: v._focusSettled, _focusRecentres: v._focusRecentres, _orbitMode: v._orbitMode, _lastInput: v._lastInput,
       },

package/js/inline3d-splat-shared.js

@@ -13,6 +13,7 @@
 // test/splat-playcanvas.test.mjs (values, and a behavioural trace of both viewers side by side).
 
 import { comfortDepthFactor, isComfortZone, DEPTH_DEFAULT_VIEWER_M } from './inline3d-depth-budget.js';
+import { attachHandsOption } from './inline3d-hands.js';
 
 /**
  * Double-attach detection around a scene subpath's public entry (`addSplat`, `addModel`).
@@ -25,9 +26,19 @@ import { comfortDepthFactor, isComfortZone, DEPTH_DEFAULT_VIEWER_M } from './inl
  */
 export function guardedAttach(wall, canvas, method, opts, attach) {
   const g = wall && typeof wall._attachGuard === 'function' ? wall._attachGuard(canvas, method, opts) : null;
-  if (!g) return attach(opts);
+  if (!g) return withHands(wall, attach(opts), opts);
   const out = attach(g.opts);
   g.own(out);
+  return withHands(wall, out, opts);
+}
+
+/**
+ * The `hands` option (`./inline3d-hands.js`): pinch to orbit, two pinches to zoom. Wired here so
+ * every addModel / addSplat entry, on either engine, gets it from one place, after the core has
+ * claimed the handle (the hands' stop rides the same `remove` accessor).
+ */
+function withHands(wall, out, opts) {
+  if (opts && opts.hands) attachHandsOption(wall, out, opts);
   return out;
 }
 

package/js/inline3d-viewer.js

@@ -379,6 +379,10 @@ export class SceneViewer {
     this._pitch = 0;
     this._targetYaw = 0;
     this._targetPitch = 0;
+    // Roll about the VIEW axis, degrees. Only the two-hand gesture (./inline3d-hands.js) and an
+    // explicit setPose({ roll }) ever write it, so every existing page is bit-identical at 0.
+    this._roll = 0;
+    this._targetRoll = 0;
     this._lastInput = now(); // so the turntable waits out the load-in rather than starting mid-pop
     this._lastTick = 0;
     this._monoRaf = 0;
@@ -524,12 +528,13 @@ export class SceneViewer {
    * This SNAPS — it writes the eased value and its target together. The easing in _tick exists
    * for input, not for programmatic placement.
    */
-  setPose({ yaw, pitch, zoom, depthOffset } = {}) {
+  setPose({ yaw, pitch, zoom, roll, depthOffset } = {}) {
     if (yaw !== undefined) this._targetYaw = this._yaw = yaw;
     if (pitch !== undefined) {
       this._targetPitch = this._pitch = clamp(pitch, this.pitchLimit[0], this.pitchLimit[1]);
     }
     if (zoom !== undefined) this._targetZoom = this._zoom = clamp(zoom, ZOOM_MIN, ZOOM_MAX);
+    if (roll !== undefined) this._targetRoll = this._roll = roll;
     if (depthOffset !== undefined) this._depthOffset = finite(depthOffset, this._depthOffset);
     this._applyTransform();
   }
@@ -553,6 +558,7 @@ export class SceneViewer {
       yaw: target ? this._targetYaw : this._yaw,
       pitch: target ? this._targetPitch : this._pitch,
       zoom: target ? this._targetZoom : this._zoom,
+      roll: target ? this._targetRoll : this._roll,
       depthOffset: this._depthOffset,
     };
   }
@@ -588,15 +594,22 @@ export class SceneViewer {
     const [hx, hy, hz] = this._subjectHalf;
     const p = (this._pitch * Math.PI) / 180;
     const y = (this._yaw * Math.PI) / 180;
-    // Rows of R = Rx(pitch) . Ry(yaw) — the same product _applyTransform builds, and the same
-    // order, which is the part that matters (see its comment on why 'XYZ' and not 'YXZ').
-    // |row| . half gives the AABB half-extent along that world axis.
+    const r = (this._roll * Math.PI) / 180;
+    // Rows of R = Rz(roll) . Rx(pitch) . Ry(yaw) — the same product _applyTransform builds, and
+    // the same order, which is the part that matters (see its comment on why pitch is outside
+    // yaw, and roll outside both). |row| . half gives the AABB half-extent along that world axis.
+    // At roll 0 the first two rows reduce to the old Rx . Ry rows exactly.
     const cp = Math.cos(p);
     const sp = Math.sin(p);
     const cy = Math.cos(y);
     const sy = Math.sin(y);
-    const ex = s * (Math.abs(cy) * hx + Math.abs(sy) * hz);
-    const ey = s * (Math.abs(sp * sy) * hx + Math.abs(cp) * hy + Math.abs(sp * cy) * hz);
+    const cr = Math.cos(r);
+    const sr = Math.sin(r);
+    // Rx . Ry rows
+    const a0 = cy, a1 = 0, a2 = sy;
+    const b0 = sp * sy, b1 = cp, b2 = -sp * cy;
+    const ex = s * (Math.abs(cr * a0 - sr * b0) * hx + Math.abs(cr * a1 - sr * b1) * hy + Math.abs(cr * a2 - sr * b2) * hz);
+    const ey = s * (Math.abs(sr * a0 + cr * b0) * hx + Math.abs(sr * a1 + cr * b1) * hy + Math.abs(sr * a2 + cr * b2) * hz);
     const ez = s * (Math.abs(cp * sy) * hx + Math.abs(sp) * hy + Math.abs(cp * cy) * hz);
     const cz = this._depthOffset;
     return {
@@ -675,8 +688,22 @@ export class SceneViewer {
   }
 
   /** Return to the framed default pose, depth slide included. */
+  /**
+   * Move the pose by a delta, EASED — what an input device does, as opposed to `setPose`'s snap.
+   * Angles in degrees to add, `zoom` a ratio to multiply; pitch is clamped, zoom bounded. Counts
+   * as interaction for the idle turntable, exactly like a pointer drag. The hands
+   * (`@displayxr/inline3d/hands`) drive the viewer through this; a page may too.
+   */
+  nudgePose({ yaw = 0, pitch = 0, zoom = 1, roll = 0 } = {}) {
+    if (yaw) this._targetYaw += yaw;
+    if (pitch) this._targetPitch = clamp(this._targetPitch + pitch, this.pitchLimit[0], this.pitchLimit[1]);
+    if (zoom && zoom !== 1) this._targetZoom = clamp(this._targetZoom * zoom, ZOOM_MIN, ZOOM_MAX);
+    if (roll) this._targetRoll += roll;
+    this._lastInput = now();
+  }
+
   resetPose() {
-    this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
+    this.setPose({ yaw: 0, pitch: 0, zoom: 1, roll: 0, depthOffset: 0 });
     this._lastInput = now();
   }
 
@@ -1035,7 +1062,10 @@ export class SceneViewer {
     // axis is itself yawed. At yaw 90° that axis has swung onto world Z and dragging up/down
     // rolls the subject instead of tilting it. Correct head-on, wrong the moment you turn it —
     // which is why it survived review and only showed up when two controls were combined.
-    this._pivot.rotation.set((this._pitch * Math.PI) / 180, (this._yaw * Math.PI) / 180, 0, 'XYZ');
+    //
+    // Roll (the two-hand twist) is about the VIEW axis, so it goes OUTSIDE both: 'ZXY' == R =
+    // Rz(roll) · Rx(pitch) · Ry(yaw). At roll 0 that is the 'XYZ' product above, bit for bit.
+    this._pivot.rotation.set((this._pitch * Math.PI) / 180, (this._yaw * Math.PI) / 180, (this._roll * Math.PI) / 180, 'ZXY');
   }
 
   /**
@@ -1136,6 +1166,7 @@ export class SceneViewer {
     const k = dt > 0 ? 1 - Math.pow(DAMP_BASE, dt) : 1;
     this._yaw += (this._targetYaw - this._yaw) * k;
     this._pitch += (this._targetPitch - this._pitch) * k;
+    if (this._roll !== this._targetRoll) this._roll += (this._targetRoll - this._roll) * 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.

package/llms.txt

@@ -4,8 +4,8 @@
 > canvas, the DisplayXR Browser weaves them for the panel; an ordinary browser shows the page in 2D.
 
 Read first: docs/making-3d-look-right.md — nine depth and comfort rules from real panels
-(keep the viewers' object placement and frame the first view, lay flat arrangements back into
-depth, keep moving things' forward swing small, fixed convergence and no near geometry in worlds,
+(the default depth is the glass: centre the subject on z = 0 and frame the first view; tilt flat
+arrangements about an axis through the glass, don't push them back; keep moving things' forward swing small, fixed convergence and no near geometry in worlds,
 low contrast behind the subject, text as HTML near the glass, no coplanar surfaces, no sub-pixel
 detail, a cover that always comes off). The SDK's defaults do the rest.
 

package/model.d.ts

@@ -3,6 +3,7 @@
 
 import type { CursorOptions } from './cursor-depth.js';
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+import type { HandControlOptions, HandControls } from './hands.js';
 import type { FirstWovenResult, RectCoverOption, ViewerEaseOption } from './index.js';
 import type { PlayCanvasSplatViewer, SplatCameraPose, SplatFrameInfo } from './splat.js';
 
@@ -25,6 +26,13 @@ export interface ModelOptions {
   /** Degrees/second of turntable once idle (default 8). */
   idleSpin?: number;
   orbit?: boolean;
+  /**
+   * Tracked-hand controls (`@displayxr/inline3d/hands`): one pinch dragged turns the model, two
+   * pinches spread / dragged / twisted zoom / turn / roll it (either engine). Needs the
+   * DisplayXR Browser 1.8.0+ with a hand provider; inert elsewhere, and pointer / wheel keep
+   * working alongside. `true` or the controller options; exposed as `handle.hands`. Default off.
+   */
+  hands?: boolean | HandControlOptions;
   fit?: 'contain' | 'height' | 'cover' | 'none';
   /** Fraction of the tile the subject may occupy (default 0.8) — width AND height. */
   margin?: number;
@@ -212,6 +220,8 @@ export interface ModelHandle {
    * returns (1.11 returned it synchronously; `@displayxr/inline3d/model/three` still does).
    */
   readonly viewer: SceneViewer | PlayCanvasSplatViewer | null;
+  /** The hand controls, when the `hands` option asked for them (`stop()`, `state.gate`, `controller`). */
+  readonly hands?: HandControls;
   /**
    * The loaded glTF root — a three `Object3D`, or on PlayCanvas the render `pc.Entity`
    * (`instantiateRenderEntity()`). Null until `ready` resolves.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.49.3",
+  "version": "1.51.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -27,6 +27,10 @@
       "types": "./viewer.d.ts",
       "import": "./js/inline3d-viewer.js"
     },
+    "./hands": {
+      "types": "./hands.d.ts",
+      "import": "./js/inline3d-hands.js"
+    },
     "./splat": {
       "types": "./splat.d.ts",
       "import": "./js/inline3d-splat.js"
@@ -91,6 +95,7 @@
     "js/inline3d-cursor-shape.js",
     "js/vendor/",
     "js/inline3d-viewer.js",
+    "js/inline3d-hands.js",
     "js/inline3d-splat.js",
     "js/inline3d-splat-pc-entry.js",
     "js/inline3d-splat-deferred.js",
@@ -133,6 +138,7 @@
     "depth.d.ts",
     "cursor-depth.d.ts",
     "viewer.d.ts",
+    "hands.d.ts",
     "splat.d.ts",
     "splat-playcanvas.d.ts",
     "model.d.ts",

package/splat.d.ts

@@ -3,6 +3,7 @@
 
 import type { CursorOptions } from './cursor-depth.js';
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
+import type { HandControlOptions, HandControls } from './hands.js';
 import type { FirstWovenResult, RectCoverOption, ViewerEaseOption, DisplayMetrics } from './index.js';
 
 /**
@@ -78,6 +79,12 @@ export interface PlayCanvasSplatViewer {
   fitTo(center: number[], extent: number[]): void;
   setPose(pose?: OrbitPose): void;
   getPose(opts?: { target?: boolean }): Required<OrbitPose>;
+  /**
+   * Move the pose by a delta, eased (SceneViewer.nudgePose's twin): degrees to add (`roll` about
+   * the view axis), zoom a ratio to multiply within `zoomOpts` (it becomes the new rest, as a
+   * `setPose` zoom does). Counts as interaction for the idle turntable and ends an orbit relax.
+   */
+  nudgePose(delta?: { yaw?: number; pitch?: number; zoom?: number; roll?: number }): void;
   resetPose(): void;
   getSubjectBounds(): SubjectBounds & { front: number; back: number; scale: number };
   setFocus(point: number[] | { x: number; y: number; z: number } | null, opts?: { snap?: boolean; recentre?: boolean }): PlayCanvasSplatViewer;
@@ -391,6 +398,13 @@ export interface SplatOptions {
    * it is still the cumulative turntable (a full-width drag = 180°).
    */
   orbit?: boolean;
+  /**
+   * Tracked-hand controls (`@displayxr/inline3d/hands`): one pinch dragged turns the splat, two
+   * pinches spread / dragged zoom / turn it (and twist rolls it on Spark). Needs the DisplayXR
+   * Browser 1.8.0+ with a hand provider; inert elsewhere. `true` or the controller options;
+   * exposed as `handle.hands`. Default off.
+   */
+  hands?: boolean | HandControlOptions;
   /** PlayCanvas: the largest drag tilt, degrees, either axis (default 15). */
   orbitMaxDeg?: number;
   /** PlayCanvas: easing time constants, seconds — `drag` while held (0.2), `rest` after release (0.6). */
@@ -1007,6 +1021,8 @@ export interface SplatHandle {
    * there until the backend module has loaded — one module fetch after addSplat returns).
    */
   readonly viewer: SceneViewer | PlayCanvasSplatViewer;
+  /** The hand controls, when the `hands` option asked for them (`stop()`, `state.gate`, `controller`). */
+  readonly hands?: HandControls;
   /**
    * Spark's SplatMesh; on `engine: 'playcanvas'` a `{ numSplats, entity, asset, resource }`
    * record of the engine objects. Null until the asset is loaded.

package/viewer.d.ts

@@ -66,6 +66,12 @@ export interface OrbitPose {
   pitch?: number;
   /** Multiplier on the fit scale. */
   zoom?: number;
+  /**
+   * Degrees about the VIEW axis (counter-clockwise as the viewer sees it), applied outside yaw and
+   * pitch. Written only by the two-hand gesture (`@displayxr/inline3d/hands`) or an explicit call;
+   * 0 for every page that never touches it. Both viewers (three.js and PlayCanvas) carry it.
+   */
+  roll?: number;
   /** Display metres along the depth axis, `+` toward the viewer (out of the glass). */
   depthOffset?: number;
 }
@@ -136,6 +142,12 @@ export declare class SceneViewer {
 
   /** Snap the pose. Writes the eased value and its target together. */
   setPose(pose?: OrbitPose): void;
+  /**
+   * Move the pose by a delta, EASED — what an input device does. Degrees to add, `zoom` a ratio
+   * to multiply (pitch clamped, zoom bounded). Counts as interaction for the idle turntable, like
+   * a pointer drag. `@displayxr/inline3d/hands` drives the viewer through this.
+   */
+  nudgePose(delta?: { yaw?: number; pitch?: number; zoom?: number; roll?: number }): void;
   /**
    * Point the viewer at something: the orbit centre, the pivot plane and (on a camera rig) the
    * convergence distance are ONE point, and this is it. `recentre: true` (a display rig) brings