@displayxr/inline3d 1.6.0 → 1.7.0

package/js/inline3d-viewer.js

@@ -28,7 +28,11 @@
 //   viewer.content.add(myMesh);
 //   viewer.fitTo(center, extent);              // model-space bounds of the subject
 //   const wall = await createInline3D();
-//   if (wall.supported) wall.addScene(canvas, viewer.onFrame, { virtualDisplayHeight: 0.18 });
+//   if (wall.supported)
+//     wall.addScene(canvas, viewer.onFrame, {
+//       virtualDisplayHeight: 0.18,
+//       onLayerLost: viewer.onLayerLost,   // the session ended: go flat rather than show raw SBS
+//     });
 //   else viewer.startMono();
 //
 // WHY FRAMING IS SCENE-GRAPH WORK AND NOT A RIG FIELD. The native display rig
@@ -48,6 +52,15 @@ const DEFAULT_DEPTH_LIMIT = 4.0;
 /** Milliseconds of no interaction before the idle turntable starts. */
 const IDLE_DELAY_MS = 2500;
 
+/**
+ * Per-frame easing factor for a focus change, matching the gallery's `EASE`.
+ *
+ * Deliberately per FRAME and not per second, because that is what the reference implementation
+ * does and a focus change is a one-off gesture response rather than a continuous motion — the
+ * difference between 60 and 120 Hz here is a settle that takes half as long, not a bug.
+ */
+const FOCUS_EASE = 0.18;
+
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
 // matrix and every vertex lands undefined. Reject at the setter instead.
@@ -222,6 +235,23 @@ export class SceneViewer {
 
     this._fitScale = 1;
     this._zoom = 1;
+    // FOCUS — the point everything turns about, eased. `_focus` is where it is now, `_target`
+    // where it is going; `_orbitCentre` is where the pivot sits afterwards, and it is what
+    // separates the two rigs: a DISPLAY rig brings the focused point to the middle of the tile
+    // (centre 0), a CAMERA rig leaves the capture exactly where it was placed and only moves
+    // what the rotation turns about (centre = the focus point). See setFocus().
+    // Plain triples, not THREE.Vector3: this module takes its THREE by injection and is tested
+    // against a stub, so every three.js type it reaches for is one more thing a consumer has to
+    // supply. Three numbers need no library.
+    this._focus = { x: 0, y: 0, z: 0 };
+    this._targetFocus = { x: 0, y: 0, z: 0 };
+    this._orbitCentre = { x: 0, y: 0, z: 0 };
+    this._focusRecentres = true;
+    this._focusSettled = true;
+    /** Called after every focus ease step, with the live focus. Set by ./splat. */
+    this.onFocusChange = null;
+    /** Called at the end of every _tick, after the transform is applied. */
+    this.onTick = null;
     this._targetZoom = 1;
     // Author-driven slide along the depth axis, display metres, +z toward the viewer. Applied
     // by _applyTransform, PRESERVED by fitTo, cleared by resetPose. Default 0 means every page
@@ -269,8 +299,23 @@ export class SceneViewer {
     if (orbit) this._bindOrbit();
     this._resize();
 
-    // Bound so it can be passed straight to addScene without a wrapper closure.
+    // Bound so they can be passed straight to addScene without a wrapper closure.
     this.onFrame = this.onFrame.bind(this);
+    this.onLayerLost = this.onLayerLost.bind(this);
+  }
+
+  /**
+   * The weave layer went away for good — pass this to `wall.addScene(canvas, viewer.onFrame,
+   * { onLayerLost: viewer.onLayerLost })` (`./splat` and `./model` do it for you).
+   *
+   * Without it the canvas keeps its last woven side-by-side frame on screen as ordinary squeezed
+   * 2D, because `_mode` stays `'3d'` and every mono fallback in this SDK is a one-shot decision
+   * made at boot (web#28). Going mono here is safe even if a tile is later re-woven: `onFrame`
+   * calls `stopMono()` on the first 3D frame it gets.
+   */
+  onLayerLost() {
+    if (this._disposed) return;
+    this.startMono();
   }
 
   /**
@@ -288,7 +333,10 @@ export class SceneViewer {
     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._centering.position.set(-c[0], -c[1], -c[2]);
+    // Through the focus, not around it: framing a subject IS pointing the viewer at its centre,
+    // and keeping the two in one place is what stops an orbit turning about somewhere the fit
+    // has since moved away from. Snapped — a refit is not a gesture.
+    this.setFocus(c, { snap: true });
     // Recorded for getSubjectBounds(). Model units; the fit scale is applied at read time so a
     // later zoom or orbit needs no re-measure.
     this._subjectHalf = [Math.abs(e[0]) / 2, Math.abs(e[1]) / 2, Math.abs(e[2]) / 2];
@@ -461,6 +509,57 @@ export class SceneViewer {
     this._applyTransform();
   }
 
+  /**
+   * Point the viewer at something — the one point that is simultaneously the orbit centre, the
+   * pivot plane and (on a camera rig) the convergence distance.
+   *
+   * Those three are the same thing and saying so is the point of this method. A viewer that lets
+   * them drift apart orbits about one place, converges at another and rotates the picture around
+   * a third, which is how "the scene swings away when I turn it" happens.
+   *
+   * The two rigs differ in what MOVES, and only in that:
+   *
+   * - **`recentre: true`** (a display rig, the default) — the focused point is brought to the
+   *   middle of the tile and onto the zero-disparity plane. That is what a portal does: you
+   *   chose a subject, so the subject is what the window shows.
+   * - **`recentre: false`** (a camera rig) — the capture stays exactly where it was placed and
+   *   only the rotation centre moves. Translating a camera-rig scene would move the viewpoint,
+   *   and the neutral view IS the photograph; nothing may move it.
+   *
+   * Eased at {@link FOCUS_EASE} per frame unless `snap`.
+   *
+   * @param {{x:number,y:number,z:number}|number[]|null} point  in CONTENT space (the space your
+   *        object sits in, i.e. `viewer.content`'s local space). Null resets to the origin.
+   * @param {object} [opts]
+   * @param {boolean} [opts.snap=false]  arrive immediately.
+   * @param {boolean} [opts.recentre]  see above. Sticky: set once when the rig is chosen.
+   */
+  setFocus(point, { snap = false, recentre } = {}) {
+    if (recentre !== undefined) this._focusRecentres = !!recentre;
+    const p = point == null ? [0, 0, 0] : Array.isArray(point) ? point : [point.x, point.y, point.z];
+    this._targetFocus = { x: finite(p[0], 0), y: finite(p[1], 0), z: finite(p[2], 0) };
+    this._focusSettled = false;
+    if (snap) {
+      this._focus = { ...this._targetFocus };
+      this._focusSettled = true;
+      this._applyFocus();
+      this._applyTransform();
+      this.onFocusChange?.(this._focus);
+    }
+    return this;
+  }
+
+  /**
+   * Where the viewer is pointed, in content space.
+   *
+   * @param {object} [opts]
+   * @param {boolean} [opts.target=false]  the value being eased TOWARD, as with getPose().
+   */
+  getFocus({ target = false } = {}) {
+    const v = target ? this._targetFocus : this._focus;
+    return { x: v.x, y: v.y, z: v.z };
+  }
+
   /** Return to the framed default pose, depth slide included. */
   resetPose() {
     this.setPose({ yaw: 0, pitch: 0, zoom: 1, depthOffset: 0 });
@@ -738,7 +837,13 @@ export class SceneViewer {
     // The depth slide lives here, not in fitTo, so it survives a refit and cannot be left
     // stale by a code path that forgets it. x/y are never written: the fit centres the subject
     // on the tile and sliding it sideways is a scene concern, not a viewer one.
-    this._pivot.position.z = this._depthOffset;
+    // The orbit centre is where the pivot SITS; the depth slide rides on top of it. Both are
+    // zero for the ordinary framed subject, so this is identity for every existing page.
+    this._pivot.position.set(
+      this._orbitCentre.x,
+      this._orbitCentre.y,
+      this._orbitCentre.z + this._depthOffset,
+    );
     // Order 'XYZ' == R = Rx(pitch) · Ry(yaw), and the order is the whole point.
     //
     // Yaw must act in the subject's OWN frame (spin it on its axis); pitch must act in the
@@ -805,7 +910,44 @@ export class SceneViewer {
     } else {
       this._zoom = this._targetZoom;
     }
+    this._easeFocus();
     this._applyTransform();
+    this.onTick?.();
+  }
+
+  /**
+   * Walk the live focus toward its target. A no-op — not even a vector compare — for every
+   * viewer that never sets one.
+   */
+  _easeFocus() {
+    if (this._focusSettled) return;
+    const f = this._focus;
+    const t = this._targetFocus;
+    const dx = t.x - f.x;
+    const dy = t.y - f.y;
+    const dz = t.z - f.z;
+    if (dx * dx + dy * dy + dz * dz < 1e-10) {
+      f.x = t.x;
+      f.y = t.y;
+      f.z = t.z;
+      this._focusSettled = true;
+    } else {
+      f.x += dx * FOCUS_EASE;
+      f.y += dy * FOCUS_EASE;
+      f.z += dz * FOCUS_EASE;
+    }
+    this._applyFocus();
+    this.onFocusChange?.(f);
+  }
+
+  /** Write the current focus into the scene graph. */
+  _applyFocus() {
+    const f = this._focus;
+    this._centering.position.set(-f.x, -f.y, -f.z);
+    const c = this._orbitCentre;
+    c.x = this._focusRecentres ? 0 : f.x;
+    c.y = this._focusRecentres ? 0 : f.y;
+    c.z = this._focusRecentres ? 0 : f.z;
   }
 
   _bindOrbit() {

package/js/inline3d.js

@@ -860,6 +860,12 @@ class Inline3D {
    *        falls back to `virtualDisplayHeight` if one was given (that pair is the one reason
    *        to pass both) — either way the window still weaves.
    * @param {Element} [opts.observe=canvas]  element whose visibility gates lazy create/close.
+   * @param {() => void} [opts.onLayerLost]  called once when this window's weave layer goes away
+   *        for good — the session ended, or the layer could not be created. YOU own a scene
+   *        canvas's pixels, so this is the SDK's only way to tell you that the side-by-side pair
+   *        in it is no longer being woven and is now just squeezed 2D on the page; take the
+   *        canvas flat here (`SceneViewer.startMono`, or your own mono path). NOT called when a
+   *        lazy tile merely scrolls off screen — that layer is coming back. Errors are caught.
    * @returns {{remove():void}}
    */
   addScene(canvas, onFrame, opts = {}) {
@@ -1746,6 +1752,12 @@ class Inline3D {
       img: null,
       video: null,
       onFrame: null,
+      // Scene windows only (addScene's `onLayerLost`): the layer went away for good. See
+      // _notifyLayerLost — `layerLostSent` keeps it one-shot per loss. Read from the options
+      // HERE rather than after `_register` returns, because a non-lazy window activates (and can
+      // therefore already fail to build its layer) inside this call.
+      onLayerLost: typeof opts.onLayerLost === 'function' ? opts.onLayerLost : null,
+      layerLostSent: false,
       ready: null,
       ownsBuffer: kind !== 'scene',
       cornerRadius: opts.cornerRadius || 0,
@@ -1844,10 +1856,27 @@ class Inline3D {
           ? { virtualDisplayHeight: win.virtualDisplayHeight }
           : {};
       win.layer = new XRDisplayLayer(this.session, win.canvas, init);
-    } catch {
+    } catch (err) {
       win.layer = null;
+      // Say so, once per window, and take the canvas flat. Swallowed silently this was
+      // undiagnosable in the field AND left a re-activated tile holding the SBS pair it wove
+      // with last time — nothing repaints it, and the IntersectionObserver does not re-fire
+      // while the tile stays intersecting. No retry: a constructor that refused this canvas will
+      // refuse it again, and a retry loop would run per frame with nothing to report (web#28).
+      if (!win.layerFailWarned) {
+        win.layerFailWarned = true;
+        console.warn(
+          '[inline3d] new XRDisplayLayer() failed for this window — it will show FLAT 2D ' +
+            'instead of woven 3D, and the SDK will not retry. The canvas has been repainted ' +
+            'mono so it cannot be left holding a raw side-by-side pair.',
+          err
+        );
+      }
+      this._paintMono(win);
+      this._notifyLayerLost(win);
       return;
     }
+    win.layerLostSent = false; // a live layer again: a future loss is worth reporting again
     // Nothing about the hardware state is re-asserted here, and that is the point: the panel's
     // mode is the DISPLAY's, it survives a tile scrolling away, and this SDK never requests it
     // behind the page's back. The rig went into the init above already flattened if a 1-view
@@ -1898,9 +1927,47 @@ class Inline3D {
       win.layer = null;
     }
     // Leave a flat (left-eye-only) frame so an off-screen image/video still shows 2D.
-    if (win.ownsBuffer && win.kind !== 'scene') {
-      this._sizeBuffer(win, /*sbs*/ false);
-      this._paint(win, null);
+    //
+    // A SCENE is deliberately NOT notified here (see _notifyLayerLost): its layer is coming
+    // back the moment the tile scrolls into view again, and `SceneViewer.onFrame` takes the
+    // backing store back to SBS by itself — collapsing on every scroll would make the lazy
+    // lifecycle visible as a mode change.
+    this._paintMono(win);
+  }
+
+  /**
+   * Take a window whose layer is gone back to the ONE state a canvas nothing weaves may be left
+   * in: a flat, left-eye-only frame in a 1:1 buffer (web#28).
+   *
+   * Shared by _deactivate, _teardown and the _activate failure path precisely so the three
+   * cannot drift — _teardown used to skip it entirely, which left every image and video tile on
+   * the page holding its last side-by-side frame, forever, the moment the session ended.
+   * Scene canvases are the page's pixels and are handled by _notifyLayerLost instead.
+   */
+  _paintMono(win) {
+    if (!win.ownsBuffer || win.kind === 'scene') return;
+    this._sizeBuffer(win, /*sbs*/ false);
+    this._paint(win, null);
+  }
+
+  /**
+   * The scene half of the same problem. The SDK does not own a scene canvas's backing store, so
+   * the most it can do is SAY the layer went away and let the owner take itself flat —
+   * `SceneViewer` wires its `startMono()` here (`addScene({ onLayerLost })`), and `./splat` and
+   * `./model` do that for you. Without it a scene tile keeps its last woven side-by-side frame
+   * on screen after the session ends, because every mono fallback in this SDK and its samples is
+   * a one-shot `!supported` branch decided at boot.
+   *
+   * One-shot per loss and never allowed to throw: this runs inside teardown, where a page
+   * callback that raises must not strand the windows behind it.
+   */
+  _notifyLayerLost(win) {
+    if (win.kind !== 'scene' || typeof win.onLayerLost !== 'function' || win.layerLostSent) return;
+    win.layerLostSent = true;
+    try {
+      win.onLayerLost();
+    } catch (err) {
+      console.warn('[inline3d] a scene window\'s onLayerLost callback threw', err);
     }
   }
 
@@ -2208,9 +2275,28 @@ class Inline3D {
 
   _paint(win, _views) {
     if (win.kind === 'scene' || !win.ctx) return;
+    // NOTHING IS WEAVING THIS CANVAS (web#28, browser-pvt#99). A dead manager or a window with
+    // no layer means the browser is not consuming this canvas as a stereo pair any more — so an
+    // SBS paint here puts the raw squeezed left|right pair on screen as ordinary 2D page
+    // content, permanently, because nothing ever repaints it. The path that makes this a FIELD
+    // bug rather than a theoretical one is a slow download: `addImage`'s load resolves after the
+    // session ended and calls `win.repaint()` straight into a canvas whose layer is gone.
+    // Forced here rather than at each call site because the call sites are the async ones.
+    // The buffer comes with it — the mono branch below stretches ONE eye across the whole
+    // backing store, so leaving a 2:1 store would show a double-width half-image.
+    const live = this._running && !!win.layer;
+    if (!live && win.sbs) this._sizeBuffer(win, /*sbs*/ false);
     const src = win.kind === 'video' ? win.video : win.img;
     if (!src) return;
-    if (win.kind === 'video' && (src.readyState || 0) < 2) return; // no frame yet
+    if (win.kind === 'video' && (src.readyState || 0) < 2) {
+      // Buffering: no new frame to draw, and drawing an unready <video> is a no-op per spec (it
+      // would leave the clearRect below as the only thing that happened, i.e. blank the tile).
+      // Skipping the paint entirely is what the old code did, and that is its own bug — see
+      // _frame: a canvas that is not redrawn can have its layer dropped from the aggregated
+      // frame. So re-commit what the canvas already holds instead.
+      if (live) this._recommitLastFrame(win);
+      return;
+    }
     const c = win.canvas;
     const ctx = win.ctx;
     const srcW = src.videoWidth || src.naturalWidth || src.width;
@@ -2234,6 +2320,30 @@ class Inline3D {
     }
   }
 
+  /**
+   * Re-commit the pixels the canvas already holds, unchanged — the cheapest "last decoded frame"
+   * there is, because the last decoded frame is already in the backing store.
+   *
+   * Drawing the canvas onto itself is one same-size blit that dirties the canvas (which is the
+   * whole point: see the every-frame-repaint note in _frame), and `globalCompositeOperation =
+   * 'copy'` is what makes it a true identity — source-over would composite a feathered buffer's
+   * transparent edges onto themselves and darken the ramp a little more every stalled frame.
+   * Only ever reached while a source has nothing new, so a healthy video never pays for it.
+   */
+  _recommitLastFrame(win) {
+    const c = win.canvas;
+    if (!c.width || !c.height) return;
+    const ctx = win.ctx;
+    try {
+      ctx.save();
+      ctx.globalCompositeOperation = 'copy';
+      ctx.drawImage(c, 0, 0);
+      ctx.restore();
+    } catch {
+      /* a context that refuses a self-blit: leave the stale pixels rather than blank the tile */
+    }
+  }
+
   /**
    * Arm the next session frame. `force` starts a NEW loop even though one is nominally
    * pending: each loop carries an id and only the current id re-arms, so a stalled
@@ -2293,7 +2403,22 @@ class Inline3D {
               );
             }
           }
-          win.onFrame(views, win.layer, f);
+          // Contained, and warned about once. A scene that throws (a texture that 404s, a
+          // decoder that gives up) used to abort this loop body for every window AFTER it in the
+          // map — and an un-redrawn canvas can have its layer dropped from the aggregated frame
+          // (see the note below), so one broken tile took its neighbours' weave with it (web#28).
+          try {
+            win.onFrame(views, win.layer, f);
+          } catch (err) {
+            if (!win.frameThrewWarned) {
+              win.frameThrewWarned = true;
+              console.warn(
+                "[inline3d] a scene window's onFrame threw; this window will keep whatever it " +
+                  'last drew, and the other windows carry on. Further throws from it are silent.',
+                err
+              );
+            }
+          }
         }
       } else {
         // Repaint image AND video every frame. The weave reads each window's
@@ -2430,6 +2555,13 @@ class Inline3D {
         }
         win.layer = null;
       }
+      // The repaint _deactivate has always done, which this path used to skip (web#28). Closing
+      // the layer also clears the browser's tracked rect, so from here nothing suppresses these
+      // canvases and nothing will ever repaint them either — whatever is in the backing store
+      // when the session ends is what the page shows from now on. A side-by-side pair is the one
+      // thing that must not be. AFTER the close, so the flat frame is the last thing committed.
+      this._paintMono(win);
+      this._notifyLayerLost(win);
     }
     this._windows.clear();
     // Page listeners go with the session that fed them: a manager whose session has ended will

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.6.0",
+  "version": "1.7.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",
@@ -40,6 +40,9 @@
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
+    "js/inline3d-sog.js",
+    "js/inline3d-splat-perf.js",
+    "js/inline3d-splat-rig.js",
     "js/inline3d-model.js",
     "index.d.ts",
     "three.d.ts",

package/splat.d.ts

@@ -3,6 +3,114 @@
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
 
+/**
+ * The knobs behind `SplatOptions.perf`. Every one is a Spark 2.1.0 setting except `alphaRadius`,
+ * which is a patch to Spark's own vertex shader (there is no option for it). Bit-exact vs lossy,
+ * and the defaults each one overrides, are tabled in `js/inline3d-splat-perf.js`.
+ */
+export interface SplatPerfOptions {
+  /** Shrink each quad to the radius where its alpha reaches `alphaFloor`. Bit-exact by default. */
+  alphaRadius?: boolean;
+  /**
+   * The alpha each splat's tail may be cut at, PER SPLAT. Defaults to `minAlpha`, which is the
+   * bit-exact cut; above it this is a lossy crop that scales with each splat's own opacity.
+   */
+  alphaFloor?: number;
+  /** Drop splats and fragments under this alpha. Spark's default is `0.5/255`. */
+  minAlpha?: number;
+  /** Quad extent in σ, globally. Spark's default is `Math.sqrt(8)`. */
+  maxStdDev?: number;
+  /** Drop splats smaller than this, in pixels. Spark's default is 0. */
+  minPixelRadius?: number;
+  /** Clamp on quad size in pixels — note it SQUASHES rather than crops. Default 512. */
+  maxPixelRadius?: number;
+  /** 1 = Gaussian falloff, 0 = flat. Not a perf knob; 0 costs MORE. */
+  falloff?: number;
+  /** Build LOD data at load, so Spark can substitute merged splats against a budget. */
+  lod?: boolean | 'quality';
+  /** LOD budget multiplier (needs `lod`). */
+  lodSplatScale?: number;
+  /** Absolute LOD budget in splats (needs `lod`). */
+  lodSplatCount?: number;
+  /** Minimum on-screen splat size multiplier (needs `lod`); up to ~5 is often invisible. */
+  lodRenderScale?: number;
+}
+
+/** Camera intrinsics for ONE eye, in pixels, OpenCV convention. */
+export interface SogIntrinsics {
+  fx: number;
+  fy: number;
+  cx: number;
+  cy: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The `camera` block of a `.sog`'s `meta.json` (v2), plus the fields this SDK derives from it.
+ * v2 is a superset of v1: everything but `convention` is optional, `intrinsics` included.
+ */
+export interface SogCamera {
+  convention: 'opencv';
+  /** Which rig the asset asks for. Null when the block does not say. */
+  rig: 'camera' | 'display' | null;
+  rest: { position: number[]; rotation: number[] };
+  /** Null when the block carried none, or none that were usable — estimate one instead. */
+  intrinsics: SogIntrinsics | null;
+  stereo: { baseline_m: number } | null;
+  /**
+   * The point that is simultaneously the orbit centre, the pivot plane and the convergence
+   * distance. In the splat's own space. The three distances are advisory.
+   */
+  focus: {
+    point: number[];
+    subject_m: number | null;
+    near_m: number | null;
+    far_m: number | null;
+    source: string | null;
+  } | null;
+  /** The camera rig's ABSOLUTE scalars. Null when unstated. */
+  dxr: { ipdFactor: number | null; parallaxFactor: number | null };
+  /** Full vertical angle of the capture in RADIANS; null without intrinsics. */
+  verticalFov: number | null;
+  /** Principal point off the frame centre, fraction of the frame, y UP; null without intrinsics. */
+  principalOffset: { x: number; y: number } | null;
+}
+
+/**
+ * What the waterfall resolved, with the step that produced each value beside it — which is the
+ * point of it. `intrinsicsSource: 'fallback-28mm'` on an asset that looks zoomed out says more
+ * than any amount of staring at the picture.
+ */
+export interface ResolvedRig {
+  type: 'camera' | 'display';
+  typeSource: 'caller' | 'block' | 'block-present' | 'default';
+  rest: { position: number[]; rotation: number[] };
+  intrinsics: SogIntrinsics;
+  intrinsicsSource: 'block' | 'caller' | 'estimated' | 'fallback-28mm';
+  /** 35 mm-equivalent focal of whatever lens was resolved. */
+  focalEqMm: number;
+  /** The live focus, in the splat's own space. */
+  focus: number[];
+  focusSource:
+    | 'caller'
+    | 'caller-convergence'
+    | 'block'
+    | 'median-disparity'
+    | 'default'
+    | 'picked'
+    | 'set';
+  /** What Space returns to. */
+  focusDefault: number[];
+  focusDefaultSource: string;
+  /** The block's advisory distances, when it carried any. */
+  focusDistances: { subject_m: number | null; near_m: number | null; far_m: number | null } | null;
+  /** Focus distance along the rest camera's view axis — the zero-disparity PLANE. */
+  convergence: number;
+  ipdFactor: number;
+  parallaxFactor: number;
+}
+
 export interface SplatOptions {
   /** Metres of world the tile's height spans (default 0.24). */
   virtualDisplayHeight?: number;
@@ -32,6 +140,41 @@ export interface SplatOptions {
   feather?: number;
   /** Minimum ms between splat sorts. Defaults to 16 so both eyes share one sort per frame. */
   sortIntervalMs?: number;
+  /**
+   * Cut overdraw. UNSET changes nothing — every Spark default stays where Spark put it, so an
+   * existing page's pixels do not move.
+   *
+   * `'exact'` is the bit-exact pair — each quad shrunk to where its own alpha reaches 1/255
+   * (those fragments were already being discarded), plus the 1/255 peak-opacity cull. It buys
+   * little on a mostly-opaque capture, which is what a lifted photograph is. `'balanced'` (or
+   * `true`, −5…−20 % measured) and `'aggressive'` (−22 %) tighten the quad extent instead, which
+   * is the axis that actually pays on the web; both move pixels.
+   */
+  perf?: true | 'exact' | 'balanced' | 'aggressive' | SplatPerfOptions;
+  /**
+   * Which view rig. `'auto'` (the default) reads it off the ASSET — a `.sog` carrying a `camera`
+   * block was lifted from a photograph and gets a camera rig that conserves the recording
+   * camera; anything else is an object and gets the display rig with the auto-frame. Only
+   * detectable when `src` is BYTES.
+   */
+  rig?: 'auto' | 'display' | 'camera';
+  /** Camera rig only: the distance in world metres that sits ON the glass. */
+  convergence?: number;
+  /**
+   * The point to converge on and orbit about, in the splat's own space — the highest step of the
+   * focus waterfall. Wins over `convergence`, which is the straight-ahead shorthand for it.
+   */
+  focus?: number[];
+  /** Override the lens, when the asset carries none and the estimate is wrong. */
+  intrinsics?: SogIntrinsics;
+  /** Camera rig scalars. ABSOLUTE, never normalised against the convergence. */
+  ipdFactor?: number;
+  parallaxFactor?: number;
+  /**
+   * Bind double-click (focus what was clicked) and Space (back to the resolved focus). Default
+   * true; pass false when the page owns those gestures itself.
+   */
+  focusInput?: boolean;
   /**
    * Disambiguates .splat from .ksplat when passing BYTES — content-sniffing cannot separate
    * those two. Unnecessary for .sog/.ply/.spz, which are identifiable by magic number.
@@ -55,11 +198,32 @@ export interface SplatHandle {
   readonly spark: object;
   /** Bounds actually used for framing; null until `ready` resolves. */
   frame: SubjectBounds | null;
+  /**
+   * The `.sog`'s `camera` block — the recording camera, when the asset carries one. Null for a
+   * URL source, a non-`.sog`, or an object splat (which is most of them).
+   */
+  camera: SogCamera | null;
+  /** What the waterfall resolved, sources included. Null until `ready` resolves. */
+  rig: ResolvedRig | null;
+  /** The view-rig descriptor sent to the runtime, on the camera path. */
+  viewRig?: object;
+  /** What `perf` actually applied, or null. */
+  perf: object | null;
   /** Resolves once the asset has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<SplatHandle>;
 
   setPose(pose?: OrbitPose): void;
   resetPose(): void;
+  /**
+   * 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`.
+   */
+  setFocus(
+    point: number[] | { x: number; y: number; z: number } | null,
+    opts?: { snap?: boolean },
+  ): SplatHandle;
+  /** What is under a point on the canvas, in the splat's own space — the double-click's raycast. */
+  pick(clientX: number, clientY: number): number[] | null;
 
   /** Close this window and release its GPU resources. */
   remove(): void;

package/viewer.d.ts

@@ -105,6 +105,22 @@ export declare class SceneViewer {
 
   /** Snap the pose. Writes the eased value and its target together. */
   setPose(pose?: OrbitPose): 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
+   * that point to the middle of the tile; `recentre: false` (a camera rig) leaves the capture
+   * where it was placed and moves only the rotation centre. Eased 0.18/frame unless `snap`.
+   */
+  setFocus(
+    point: { x: number; y: number; z: number } | number[] | null,
+    opts?: { snap?: boolean; recentre?: boolean },
+  ): SceneViewer;
+  /** Where the viewer is pointed, in content space. */
+  getFocus(opts?: { target?: boolean }): { x: number; y: number; z: number };
+  /** Called after every focus ease step, with the live focus. */
+  onFocusChange: ((focus: { x: number; y: number; z: number }) => void) | null;
+  /** Called at the end of every tick, after the transform is applied. */
+  onTick: (() => void) | null;
 
   /**
    * The pose as it is right now. `target: true` reports what it is easing TOWARD, which differs
@@ -139,6 +155,12 @@ export declare class SceneViewer {
    * frame either way, so the tile never goes dark and never smears (web#12).
    */
   onFrame(views: readonly XRView[], layer: object): void;
+  /**
+   * The weave layer went away for good — pass to `addScene(canvas, viewer.onFrame,
+   * { onLayerLost: viewer.onLayerLost })` so the tile goes flat instead of showing its last
+   * side-by-side frame as squeezed 2D. Pre-bound; `./splat` and `./model` wire it for you.
+   */
+  onLayerLost(): void;
 
   /** Supply the ./three glue so the 3D path can build its eye camera. Returns `this`. */
   useEyeCamera(EyeCameraClass: unknown, EdgeFeatherClass?: unknown): this;