@displayxr/inline3d 1.46.0 → 1.47.1

package/js/inline3d-splat-playcanvas.js

@@ -119,6 +119,12 @@ import {
   normalizeCameraPose,
   coverageExponent,
   declareViewRig,
+  parseClearColor,
+  validateSetStereo,
+  stereoScalarOf,
+  attachComfortDepth,
+  resolveDepthOption,
+  framedSubjectBounds,
 } from './inline3d-splat-shared.js';
 import { resolveCursorOption } from './inline3d-cursor-option.js';
 
@@ -827,6 +833,10 @@ export class PlayCanvasSplatViewer {
       cursor = null,
     } = opts;
     this.canvas = canvas;
+    // `clearColor` (opt-in): the eye cameras' clear, [r,g,b,a] in 0..1, or null = the transparent
+    // clear every tile had before it existed. An OPAQUE clear avoids stale / black pixels where the
+    // weave reads an alpha-0 hole (web#198).
+    this.clearColor = parseClearColor(opts.clearColor, opts.logTag || '[inline3d/splat]');
     // `cursor: 'depth'` (ADR-046): the depth-aware cursor. OPT-IN AND FREE OTHERWISE — its module
     // is imported only when asked for (attachEngine), and every per-frame hook is an optional call
     // on `cursorDepth`, which stays null without it.
@@ -1984,7 +1994,7 @@ export class PlayCanvasSplatViewer {
     const pc = this.pc;
     const e = new pc.Entity(name, this.app);
     e.addComponent('camera', {
-      clearColor: new pc.Color(0, 0, 0, 0),
+      clearColor: this.clearColor ? new pc.Color(this.clearColor[0], this.clearColor[1], this.clearColor[2], this.clearColor[3]) : new pc.Color(0, 0, 0, 0),
       nearClip: MONO_NEAR,
       farClip: MONO_FAR,
       fov: MONO_FOV,
@@ -3125,41 +3135,9 @@ export function validateWarmEffects(list) {
   });
 }
 
-/**
- * handle.setStereo's argument, validated and merged onto the current override (throws at the
- * call). Returns the new override, or null when nothing is overridden.
- */
-export function validateSetStereo(o, prev) {
-  if (o === null) return null;
-  if (typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setStereo takes an object or null.');
-  // Absolute (…Factor) or RELATIVE to the asset's own (…Scale); per scalar, the last one given wins.
-  const pairs = [
-    ['ipdFactor', 'ipdScale'],
-    ['parallaxFactor', 'parallaxScale'],
-  ];
-  const keys = pairs.flat();
-  const unknown = Object.keys(o).filter((k) => !keys.includes(k));
-  if (unknown.length) throw new Error(`@displayxr/inline3d/splat: setStereo — unknown option(s) ${unknown.join(', ')}.`);
-  for (const [a, b] of pairs) {
-    if (o[a] != null && o[b] != null) throw new Error(`@displayxr/inline3d/splat: setStereo — ${a} and ${b} are exclusive.`);
-  }
-  const next = { ...(prev || {}) };
-  for (const [a, b] of pairs) {
-    for (const k of [a, b]) {
-      if (!(k in o) || o[k] === undefined) continue;
-      if (o[k] === null) {
-        delete next[k];
-        continue;
-      }
-      if (typeof o[k] !== 'number' || !Number.isFinite(o[k]) || o[k] < 0) {
-        throw new RangeError(`@displayxr/inline3d/splat: setStereo — ${k} must be a finite number >= 0 (got ${o[k]}).`);
-      }
-      next[k] = o[k];
-      delete next[k === a ? b : a];
-    }
-  }
-  return Object.keys(next).length ? next : null;
-}
+// validateSetStereo lives in ./inline3d-splat-shared.js now (./model's setStereo shares it); it is
+// re-exported from here so every name this module exported before still resolves.
+export { validateSetStereo };
 
 /**
  * handle.setRig's arguments, validated and resolved (throws at the call, before anything runs).
@@ -3403,6 +3381,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // an advanced caller may reach this function directly.
   const ctl = resolveControls(opts);
   const pageMode = ctl.page;
+  const depthOption = resolveDepthOption(opts.depth);
   if (pageMode && ctl.ignored.length) {
     console.info(
       `[inline3d/splat] controls:'page' — the page owns the camera, so ${ctl.ignored.join(', ')} ` +
@@ -3434,10 +3413,27 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     sky: opts.sky,
     viewerEase: opts.viewerEase,
     cursor: opts.cursor,
+    // Opt-in; undefined = the viewer's own default (a transparent clear).
+    clearColor: opts.clearColor,
   });
 
   let handle = null;
   let unbindFocusInput = null;
+  // `depth: 'auto'` (opt-in): the comfort factor, multiplied under setStereo's on the DISPLAY rig
+  // declareDisplay sends (camera rigs and setVideo's own rig never carry it). Without the option:
+  // inert, `depthFactor` 1, nothing measured, nothing declared.
+  const depth = attachComfortDepth(out, {
+    option: depthOption,
+    canvas,
+    getTile: () => handle,
+    getBounds: () => (out.rig && out.rig.type !== 'camera' && !vid?.on ? framedSubjectBounds(viewer) : null),
+    getVH: () => viewer.vH,
+    apply: () => {
+      if (!pageMode && !vid?.on && out.rig?.type !== 'camera' && lastDisplayBase) declareDisplay(lastDisplayBase);
+    },
+    tag: '[inline3d/splat]',
+  });
+  if (pageMode) depth.ignore("controls:'page' (the page's camera rig)");
 
   // ── diagnostics (diag / ?dxrdiag — ./inline3d-splat-diag.js) ──
   const diagCfg = resolveDiag(opts.diag);
@@ -3705,6 +3701,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     effects: () => (fx ? fx.list() : []),
     remove() {
       removed = true;
+      depth.dispose();
       dropVideo(); // before the app goes: the plane's rVFC, and a <video> this handle made
       current = null;
       for (const p of [...livePrepared]) p.dispose();
@@ -3986,6 +3983,10 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // three looks down −z; convergence is the focus's distance along that axis (the PLANE).
     const fwd = [-pose[8], -pose[9], -pose[10]];
     const d = (f.x - pose[12]) * fwd[0] + (f.y - pose[13]) * fwd[1] + (f.z - pose[14]) * fwd[2];
+    // A focus at or behind the camera has no zero-disparity plane in front of it: a transient
+    // before the first focus lands, or a focus moved behind the camera. Keep the rig as declared;
+    // convergence at infinity would put the whole scene in front of the glass.
+    if (!(d > 0)) return;
     if (!force && Math.abs(d - lastConvergence) < 1e-3) return;
     lastConvergence = d;
     out.rig.convergence = d;
@@ -3999,7 +4000,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         fov: viewer.mono.fov,
       },
       {
-        convergence: d > 0 ? d : 0,
+        convergence: d,
         ipdFactor: out.rig.ipdFactor,
         parallaxFactor: out.rig.parallaxFactor,
         out: camRigObj,
@@ -4369,9 +4370,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // raw: setVideo's own display rig — not the page's rig, so neither setStereo's factors nor
     // the base setStereo re-declares from.
     if (!raw) lastDisplayBase = base;
+    // The `depth` option's comfort factor (1 without it), × setStereo's: never on setVideo's rig.
+    const kd = raw ? 1 : depth.factor;
     const f =
-      stereoOverride && !raw
-        ? { ...base, ipdFactor: stereoScalar(base.ipdFactor ?? 1, 'ipd'), parallaxFactor: stereoScalar(base.parallaxFactor ?? 1, 'parallax') }
+      (stereoOverride || kd !== 1) && !raw
+        ? { ...base, ipdFactor: stereoScalar(base.ipdFactor ?? 1, 'ipd') * kd, parallaxFactor: stereoScalar(base.parallaxFactor ?? 1, 'parallax') * kd }
         : base;
     const key = `${f.vH}|${f.ipdFactor ?? 1}|${f.parallaxFactor ?? 1}|${f.perspectiveFactor ?? 1}`;
     if (declaredDisplay === key) return;
@@ -4407,6 +4410,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       viewer.setFocus(modelToContent(resolved.focus), { snap: true, recentre: false });
       lastConvergence = Number.NaN;
       pushViewRig(true);
+      depth.ignore('a camera rig');
       return;
     }
     if (viewer.mono.capture) viewer.useDisplayCamera();
@@ -4425,6 +4429,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       resolved.focusDefaultSource = 'frame';
       resolved.frame = target;
       declareDisplay(disp);
+      depth.resume();
       return;
     }
     // The splat itself, as a display-rig addSplat frames it (the load-time path).
@@ -4437,6 +4442,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     }
     if (disp) resolved.frame = bounds ? { center: bounds.center.slice(), extent: bounds.extent.slice(), source: 'splat' } : null;
     declareDisplay(disp || { vH: bootFraming.vH });
+    if (bounds) depth.resume();
   }
 
   // ── handle.setStereo: live stereo strength on whatever rig is declared ──
@@ -4452,10 +4458,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
   /** One scalar under setStereo: its absolute value, else `base` × its scale, else `base`. */
   function stereoScalar(base, k) {
-    const o = stereoOverride;
-    if (o?.[`${k}Factor`] != null) return o[`${k}Factor`];
-    if (o?.[`${k}Scale`] != null) return base * o[`${k}Scale`];
-    return base;
+    return stereoScalarOf(stereoOverride, base, k);
   }
 
   /**
@@ -4943,6 +4946,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     lastConvergence = s.lastConvergence;
     state.on = false;
     if (stereoOverride !== state.stereoAtEnter) redeclareStereo(); // a setStereo made while the video held the rig
+    depth.refresh(); // the `depth` option holds still under a video; measure again (no-op without it)
 
   }
 

package/js/inline3d-splat-shared.js

@@ -12,6 +12,8 @@
 // apart on how a drag, a wheel notch, an idle turntable or a focus change feels. Pinned by
 // 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';
+
 /**
  * Double-attach detection around a scene subpath's public entry (`addSplat`, `addModel`).
  *
@@ -563,3 +565,312 @@ export function declareViewRig(handle, rig) {
   }
   return false;
 }
+
+/**
+ * The `clearColor` option of SceneViewer / addModel / addSplat, as `[r, g, b, a]` in 0..1 — or
+ * null when absent (the viewer then keeps its transparent clear, exactly as before). Takes
+ * `[r, g, b]` / `[r, g, b, a]` (0..1; alpha defaults to 1) or a CSS colour string: `#rgb`,
+ * `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()` / `rgba()` (comma or space syntax, `/ alpha`),
+ * `transparent`, and — where a DOM is present — any other CSS colour the browser can parse.
+ * Something it cannot read warns once per call (with `tag`) and returns null: the default clear
+ * stays.
+ */
+export function parseClearColor(v, tag = '[inline3d]') {
+  if (v === undefined || v === null) return null;
+  const bad = () => {
+    console.warn(`${tag} clearColor ${JSON.stringify(v)} is not a colour this SDK can read ([r,g,b,a] in 0..1, or a CSS colour); the default (transparent) clear is kept.`);
+    return null;
+  };
+  if (Array.isArray(v) || ArrayBuffer.isView(v)) {
+    if (v.length < 3 || v.length > 4) return bad();
+    const c = [v[0], v[1], v[2], v.length === 4 ? v[3] : 1];
+    if (!c.every((x) => typeof x === 'number' && Number.isFinite(x))) return bad();
+    return c.map((x) => clamp(x, 0, 1));
+  }
+  if (typeof v !== 'string') return bad();
+  const s = v.trim().toLowerCase();
+  if (s === 'transparent') return [0, 0, 0, 0];
+  let m = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(s);
+  if (m) {
+    let h = m[1];
+    if (h.length <= 4) h = [...h].map((ch) => ch + ch).join('');
+    const n = (i) => parseInt(h.slice(i, i + 2), 16) / 255;
+    return [n(0), n(2), n(4), h.length === 8 ? n(6) : 1];
+  }
+  m = /^rgba?\(\s*([^)]*)\)$/.exec(s);
+  if (m) {
+    const parts = m[1].split(/\s*[,/]\s*|\s+/).filter(Boolean);
+    if (parts.length < 3 || parts.length > 4) return bad();
+    const ch = (p) => (p.endsWith('%') ? parseFloat(p) / 100 : parseFloat(p) / 255);
+    const al = (p) => (p.endsWith('%') ? parseFloat(p) / 100 : parseFloat(p));
+    const c = [ch(parts[0]), ch(parts[1]), ch(parts[2]), parts.length === 4 ? al(parts[3]) : 1];
+    if (!c.every(Number.isFinite)) return bad();
+    return c.map((x) => clamp(x, 0, 1));
+  }
+  // Any other CSS colour (a name, hsl(), …): let the browser normalise it, where there is one.
+  // A 2D context's fillStyle reads back as #rrggbb or rgba(…), both handled above.
+  try {
+    const ctx = globalThis.document?.createElement?.('canvas')?.getContext?.('2d');
+    if (ctx) {
+      ctx.fillStyle = '#010203';
+      ctx.fillStyle = v;
+      const out = String(ctx.fillStyle);
+      if (out !== '#010203') return parseClearColor(out, tag);
+    }
+  } catch {
+    /* no DOM */
+  }
+  return bad();
+}
+
+/**
+ * `handle.setStereo`'s argument, validated and merged onto the current override (throws at the
+ * call). Returns the new override, or null when nothing is overridden. Shared by `./splat`
+ * (PlayCanvas) and `./model` (both engines); `tag` names the subpath in the errors.
+ */
+export function validateSetStereo(o, prev, tag = '@displayxr/inline3d/splat') {
+  if (o === null) return null;
+  if (typeof o !== 'object') throw new TypeError(`${tag}: setStereo takes an object or null.`);
+  // Absolute (…Factor) or RELATIVE to the asset's own (…Scale); per scalar, the last one given wins.
+  const pairs = [
+    ['ipdFactor', 'ipdScale'],
+    ['parallaxFactor', 'parallaxScale'],
+  ];
+  const keys = pairs.flat();
+  const unknown = Object.keys(o).filter((k) => !keys.includes(k));
+  if (unknown.length) throw new Error(`${tag}: setStereo — unknown option(s) ${unknown.join(', ')}.`);
+  for (const [a, b] of pairs) {
+    if (o[a] != null && o[b] != null) throw new Error(`${tag}: setStereo — ${a} and ${b} are exclusive.`);
+  }
+  const next = { ...(prev || {}) };
+  for (const [a, b] of pairs) {
+    for (const k of [a, b]) {
+      if (!(k in o) || o[k] === undefined) continue;
+      if (o[k] === null) {
+        delete next[k];
+        continue;
+      }
+      if (typeof o[k] !== 'number' || !Number.isFinite(o[k]) || o[k] < 0) {
+        throw new RangeError(`${tag}: setStereo — ${k} must be a finite number >= 0 (got ${o[k]}).`);
+      }
+      next[k] = o[k];
+      delete next[k === a ? b : a];
+    }
+  }
+  return Object.keys(next).length ? next : null;
+}
+
+/** One scalar under a setStereo override: its absolute value, else `base` × its scale, else `base`. */
+export function stereoScalarOf(o, base, k) {
+  if (o?.[`${k}Factor`] != null) return o[`${k}Factor`];
+  if (o?.[`${k}Scale`] != null) return base * o[`${k}Scale`];
+  return base;
+}
+
+/**
+ * `./model`'s `handle.setStereo` + `handle.rig`, for both engines: `out` the model handle,
+ * `getTile()` the core window handle (null without a session), `vH` the tile's
+ * virtualDisplayHeight, `makeDisplayRig` ./three's displayRig. A model has no stereo of its own,
+ * so the "asset's own" values are 1 and 1 — `ipdScale` and `ipdFactor` agree.
+ *
+ * The rig is the display rig addModel declared with its `virtualDisplayHeight` shorthand; a value
+ * set here re-declares it as an explicit display rig with those factors (RELATIVE: 1 = what the
+ * display shows by construction). `setStereo(null)` declares the plain rig again — the exact
+ * equivalent of the shorthand. Nothing is sent before the first call: a page that never calls it
+ * declares exactly what it did before. Under `controls: 'page'` the camera rig the page drives
+ * takes the values instead, from its next tick.
+ *
+ * `setBase(k)` is the `depth` option's comfort factor: both scalars × k, on top of setStereo's,
+ * declared like a setStereo call (and, like one, nothing until it is called with k ≠ 1).
+ */
+export function attachModelStereo(out, { getTile, vH, makeDisplayRig, page = false, tag = '@displayxr/inline3d/model' }) {
+  let override = null;
+  let declared = false;
+  // The `depth` option's comfort factor (attachComfortDepth), multiplied under setStereo's values;
+  // 1 = nothing to declare on its account.
+  let base = 1;
+  // controls:'page' declares its own camera rig every tick and reads rig.ipdFactor / parallaxFactor
+  // there (ABSOLUTE on a camera rig, as addSplat's); nothing is declared from here.
+  const rig = { type: page ? 'camera' : 'display', ipdFactor: 1, parallaxFactor: 1, stereoDefault: Object.freeze({ ipdFactor: 1, parallaxFactor: 1 }) };
+  out.rig = rig;
+  const declare = () => {
+    const tile = getTile();
+    if (page || !tile || (!override && !declared && base === 1)) return;
+    declared = true;
+    out.viewRig = makeDisplayRig({ virtualDisplayHeight: vH, ipdFactor: rig.ipdFactor, parallaxFactor: rig.parallaxFactor, out: out.viewRig || {} });
+    declareViewRig(tile, out.viewRig);
+  };
+  const factors = () => {
+    rig.ipdFactor = stereoScalarOf(override, 1, 'ipd') * base;
+    rig.parallaxFactor = stereoScalarOf(override, 1, 'parallax') * base;
+  };
+  out.setStereo = (o) => {
+    override = validateSetStereo(o, override, tag);
+    factors();
+    declare();
+    return out;
+  };
+  return {
+    redeclare: declare,
+    get override() {
+      return override;
+    },
+    /** The comfort factor (both scalars move together), × setStereo's; re-declares when it changes. */
+    setBase(k) {
+      if (k === base) return;
+      base = k;
+      factors();
+      declare();
+    },
+  };
+}
+
+// ── the `depth` option: comfort depth (./model, ./splat) ──────────────────────────────────────
+
+/**
+ * addModel / addSplat's `depth` option, validated (throws at the call, like every option check):
+ * null when absent — nothing about the tile changes — else `{ zone }`. `'auto'` is the Shibata
+ * zone; `{ zone }` takes `'shibata'`, `'percival'` or a number of diopters > 0.
+ */
+export function resolveDepthOption(v, tag = '@displayxr/inline3d/splat') {
+  if (v === undefined || v === null) return null;
+  if (v === 'auto') return { zone: 'shibata' };
+  if (typeof v !== 'object' || Array.isArray(v)) {
+    throw new TypeError(`${tag}: depth must be 'auto' or { zone } (got ${JSON.stringify(v)}).`);
+  }
+  const unknown = Object.keys(v).filter((k) => k !== 'zone');
+  if (unknown.length) throw new Error(`${tag}: depth — unknown option(s) ${unknown.join(', ')}.`);
+  const zone = v.zone === undefined ? 'shibata' : v.zone;
+  if (!isComfortZone(zone)) {
+    throw new RangeError(`${tag}: depth.zone must be 'shibata', 'percival' or a number of diopters > 0 (got ${JSON.stringify(v.zone)}).`);
+  }
+  return { zone };
+}
+
+/**
+ * The subject's depth AS FRAMED — getSubjectBounds' `front` / `back` at zoom 1 with no orbit
+ * (the fit scale, the subject's half depth, the page's depthOffset). Zoom and orbit are left out
+ * on purpose: they are framing choices the viewer (or the page) makes live, and the `depth`
+ * option's factor must not breathe with them. Either viewer (SceneViewer, PlayCanvasSplatViewer).
+ */
+export function framedSubjectBounds(viewer) {
+  const s = viewer._fitScale;
+  const hz = viewer._subjectHalf?.[2];
+  const cz = viewer._depthOffset || 0;
+  if (!(s > 0) || !Number.isFinite(hz)) return null;
+  return { front: cz + s * hz, back: cz - s * hz };
+}
+
+/**
+ * The `depth` option's live part, shared by every engine: measure the comfort factor
+ * (comfortDepthFactor) from the framed subject, the canvas's physical height and the NOMINAL viewer
+ * distance, and hand it to `apply(k)` — the engine multiplies it into the display rig it declares,
+ * on top of setStereo's values. `out.depthFactor` reads it (1 when the option is off or not in
+ * force).
+ *
+ * Re-measured when the engine calls `refresh()` (after it frames a subject), when the tile first
+ * weaves (its layer can answer getDisplayInfo from then), on a display event and when the canvas
+ * resizes — never per frame, and never on zoom or orbit (the box is framedSubjectBounds'). `apply` runs only when k changes. `ignore(why)` says once that the
+ * option does nothing on this rig (a camera rig, controls:'page') and holds the factor at 1;
+ * `resume()` measures again (a PlayCanvas splat back on a display rig).
+ * Without the option every method is a no-op: no listener, no observer, no async work.
+ *
+ * `getBounds()` → a framedSubjectBounds() box or null (null = nothing to measure now), `getVH()` →
+ * the virtualDisplayHeight that box is in, `getTile()` → the core window handle.
+ */
+export function attachComfortDepth(out, { option, canvas, getTile, getBounds, getVH, apply, tag = '[inline3d]' }) {
+  let factor = 1;
+  Object.defineProperty(out, 'depthFactor', { get: () => factor, enumerable: true, configurable: true });
+  if (!option) return { refresh() {}, ignore() {}, resume() {}, dispose() {}, get factor() { return 1; } };
+  let ignoring = false;
+  let warned = false;
+  let disposed = false;
+  let running = false;
+  let again = false;
+  let bound = null;
+  const unbind = [];
+  const bind = (tile) => {
+    if (bound === tile) return;
+    bound = tile;
+    tile.firstWoven?.then?.(() => refresh(), () => {});
+    for (const type of ['renderingmodechange', 'hardwaredisplaystatechange']) {
+      try {
+        const off = tile.on?.(type, () => refresh());
+        if (typeof off === 'function') unbind.push(off);
+      } catch {
+        /* a core without display events: resize and refresh() still re-measure */
+      }
+    }
+    if (canvas && typeof ResizeObserver === 'function') {
+      const ro = new ResizeObserver(() => refresh());
+      ro.observe(canvas);
+      unbind.push(() => ro.disconnect());
+    }
+  };
+  async function refresh() {
+    if (disposed || ignoring) return;
+    const tile = getTile();
+    if (!tile || typeof tile.displayMetrics !== 'function') return;
+    bind(tile);
+    // One measurement at a time; a request during one runs once more after it (a resize burst).
+    if (running) {
+      again = true;
+      return;
+    }
+    running = true;
+    try {
+      do {
+        again = false;
+        let m = null;
+        try {
+          m = await tile.displayMetrics(); // never rejects; guarded for an older core
+        } catch {
+          m = null;
+        }
+        if (disposed || ignoring) return;
+        const b = getBounds();
+        const vH = getVH();
+        if (!m || !b || !(vH > 0)) continue;
+        const k = comfortDepthFactor({
+          frontH: Math.max(0, b.front / vH),
+          backH: Math.max(0, -b.back / vH),
+          tileHeightM: m.canvasSizeM?.[1],
+          // The NOMINAL distance (what the display is built for), never the live head: depth that
+          // breathed with the viewer's head would be a second, unasked-for parallax.
+          viewerM: m.source?.viewer === 'display' ? m.nominalViewerM : DEPTH_DEFAULT_VIEWER_M,
+          zone: option.zone,
+        });
+        if (k !== factor) {
+          factor = k;
+          apply(k);
+        }
+      } while (again);
+    } finally {
+      running = false;
+    }
+  }
+  return {
+    refresh,
+    /** This rig takes no comfort factor: say so once, and hold 1 (refresh() idle) until resume(). */
+    ignore(why) {
+      if (!warned) {
+        warned = true;
+        console.warn(`${tag} depth: 'auto' applies to the display rig only; ignored on ${why} (the rig is sent as declared).`);
+      }
+      ignoring = true;
+      factor = 1;
+    },
+    /** A display rig again (PlayCanvas setRig / setSource): measure from here. */
+    resume() {
+      ignoring = false;
+      return refresh();
+    },
+    dispose() {
+      disposed = true;
+      while (unbind.length) unbind.pop()();
+    },
+    get factor() {
+      return factor;
+    },
+  };
+}

package/js/inline3d-splat.js

@@ -20,7 +20,7 @@
 
 import * as THREE from 'three';
 import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
-import { EyeCamera, EdgeFeather, cameraRigFromCamera, DepthCursor, raycastHitTest } from './inline3d-three.js';
+import { EyeCamera, EdgeFeather, cameraRigFromCamera, DepthCursor, raycastHitTest, displayRig } from './inline3d-three.js';
 import { resolveCursorOption } from './inline3d-cursor-depth.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
@@ -40,6 +40,9 @@ import {
   resolveControls,
   declareViewRig,
   guardedAttach,
+  attachComfortDepth,
+  resolveDepthOption,
+  framedSubjectBounds,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -178,6 +181,8 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
   // WHO OWNS THE CAMERA. Validated here, synchronously, for both engines (an unknown `controls`
   // or a comfortDepth out of range is a page bug true of every call).
   const { page: pageControls } = resolveControls(opts);
+  // Opt-in comfort depth, both engines: a bad value is a page bug, thrown at the call.
+  const depthOption = resolveDepthOption(opts.depth);
   // WHICH ENGINE. Unset (or 'spark') is everything below, untouched. 'playcanvas' goes to
   // ./inline3d-splat-playcanvas.js, imported DYNAMICALLY so a page that never asks for it never
   // resolves `playcanvas` — see addSplatDeferred.
@@ -255,6 +260,8 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
     feather,
     logTag: '[inline3d/splat]',
     viewerEase: opts.viewerEase,
+    // Opt-in; undefined = the viewer's own default (a transparent clear).
+    clearColor: opts.clearColor,
   }).useEyeCamera(EyeCamera, EdgeFeather);
   // A gaussian-splat raycast is ~8 ms a ray on Spark: one ray a frame, cycling the footprint.
   // (engine:'playcanvas' hit-tests with the engine's depth picker instead, which is far cheaper.)
@@ -356,6 +363,7 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
     remove() {
       unbindFocusInput?.();
       viewer.onFocusChange = null;
+      depth.dispose();
       handle?.remove();
       viewer.dispose();
       out.mesh?.dispose?.();
@@ -511,6 +519,23 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
   // The core handle's `firstWoven`, forwarded; a page with no session is told so at once.
   out.firstWoven = handle ? handle.firstWoven : Promise.resolve(Object.freeze({ woven: false, confirmed: false, reason: 'unsupported', ms: 0 }));
 
+  // `depth: 'auto'` (opt-in, display rig only): Spark has no setStereo, so the comfort factor is
+  // the display rig's whole ipdFactor / parallaxFactor, declared explicitly when it moves off 1
+  // (and back to the plain rig — the shorthand's exact equivalent — if it returns to 1).
+  // Without the option: inert, `depthFactor` 1, the shorthand stays the only declaration.
+  const depth = attachComfortDepth(out, {
+    option: depthOption,
+    canvas,
+    getTile: () => handle,
+    getBounds: () => (out.frame && out.rig?.type === 'display' ? framedSubjectBounds(viewer) : null),
+    getVH: () => virtualDisplayHeight,
+    apply: (k) => {
+      out.viewRig = displayRig({ virtualDisplayHeight, ipdFactor: k, parallaxFactor: k, out: out.viewRig || {} });
+      declareViewRig(handle, out.viewRig);
+    },
+    tag: '[inline3d/splat]',
+  });
+
 
   // ── focus: declaring it, and the two gestures that change it ──────────────────────────
   //
@@ -667,6 +692,7 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
       out.frame = bounds;
 
       if (resolved.type === 'camera') {
+        depth.ignore('a camera rig (this asset carries a capture camera)');
         // A turntable on a photograph is nonsense, so the default spin stops here — but only the
         // DEFAULT: a page that asked for one still gets it.
         if (!('idleSpin' in opts)) viewer.idleSpin = 0;
@@ -679,8 +705,10 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
         });
         pushViewRig(true);
       } else {
-        if (bounds) viewer.fitTo(bounds.center, bounds.extent);
-        else {
+        if (bounds) {
+          viewer.fitTo(bounds.center, bounds.extent);
+          depth.refresh();
+        } else {
           // Unframed means drawn at raw MODEL scale, which for a typical capture is several
           // times the tile. Say so: silence here is what made the same condition read as a fit
           // bug.

package/js/inline3d-three.js

@@ -74,6 +74,17 @@ import {
   CURSOR_OUTLINE_COLOR,
 } from './inline3d-cursor-depth.js';
 import { CursorAmortisedPick, CursorDebugStats, cursorDebugMode } from './inline3d-cursor-perf.js';
+import { noteBuiltCameraRig } from './inline3d-depth-budget.js';
+// The depth-budget helpers, for a page that renders its own scene with these rigs: what disparity
+// a camera rig or a display-rig depth gives, as % of the tile width. Pure; see the module.
+export {
+  disparityPct,
+  cameraRigDisparityPct,
+  depthBudgetFromBounds,
+  comfortZone,
+  comfortDepthFactor,
+  cameraRigComfortFactor,
+} from './inline3d-depth-budget.js';
 
 /**
  * A reusable three.js camera driven directly by an XRView's matrices. Construct once with
@@ -202,14 +213,19 @@ function scratch(THREE) {
  * glass; everything nearer pops out, everything further recedes. Point it at whatever the viewer
  * is meant to be looking at (the subject's centre, a hit-tested surface) — with a moving camera
  * that is usually just the distance to it. Left at 0 it means infinity, which puts the entire
- * scene in front of the display and is comfortable for almost nothing.
+ * scene in front of the display and is comfortable for almost nothing — so a 0 / unset
+ * convergence logs one console warning per page (the descriptor is still built as asked).
  *
- * COMFORT. The runtime's rule is `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
- * (N = nominal viewing distance, ~0.5 m): at 1 the viewer's eyes are parallel on infinitely far
- * content, and past it they diverge, which no one can fuse. With the defaults (factors 1,
- * metersToVirtual 1) that is `convergence >= ~0.5` world units. Nothing here enforces it — the
- * runtime clamps out-of-range values itself, once, with a warning — but a scene authored in
- * centimetres with a 0.1-unit convergence is the shape of the mistake.
+ * COMFORT. The rule is `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1` (N = the
+ * nominal viewer distance the display reports — 0.6 m on a desktop panel): at 1 the viewer's
+ * eyes are parallel on infinitely far content, and past it they diverge, which no one can fuse.
+ * With the defaults (factors 1, metersToVirtual 1) that is `convergence >= ~0.6` world units.
+ * NOTHING ENFORCES IT for a rig the app declares: the runtime takes the gain
+ * `metersToVirtual × convergenceDiopters × N` as given (XR_DXR_view_rig §3 — only a legacy
+ * camera profile is comfort-clamped) and clamps only values outside a field's sanity range
+ * (e.g. convergenceDiopters to [0, 20], verticalFov to [0.01, 3.13] rad), once, with a warning.
+ * A scene authored in centimetres with a 0.1-unit convergence is the shape of the mistake;
+ * `cameraRigDisparityPct` measures what a rig gives.
  *
  * COMFORT IS NOT A DEPTH METER. It bounds where the depth budget SITS (it guards the background
  * against divergence), not how big the budget is. The budget is
@@ -300,6 +316,8 @@ function fillCameraRig(out, verticalFovRad, opts) {
   out.convergenceDiopters = convergence > 0 ? 1 / convergence : 0;
   out.verticalFov = verticalFovRad;
   out.metersToVirtual = metersToVirtual;
+  // Infinity is almost never what was meant: say so once per page. The descriptor is unchanged.
+  if (!(out.convergenceDiopters > 0)) noteBuiltCameraRig(out);
   return out;
 }
 
@@ -315,9 +333,11 @@ function fillCameraRig(out, verticalFovRad, opts) {
  * The factors are RELATIVE here (unlike a camera rig, where ipd/parallax are absolute):
  * `ipdFactor` and `parallaxFactor` are [0,1] multipliers on what the display would naturally do
  * — 1 is correct-by-construction, 0 is flat/frozen, and the values between are a comfort dial,
- * not a correctness one. `perspectiveFactor` is [0.1,10] and exaggerates or flattens the
- * off-axis skew; it is the one knob with no physical justification, so treat it as an effect.
- * The runtime clamps anything out of range (once, with a warning) rather than refusing the rig.
+ * not a correctness one. Above 1 exaggerates depth past what the display shows by construction:
+ * the runtime accepts it (it clamps ipd/parallax only to [0, 10000]) and `handle.setViewRig` logs
+ * one console warning. `perspectiveFactor` is [0.1,10] (the runtime clamps it there, once, with a
+ * warning) and exaggerates or flattens the off-axis skew; it is the one knob with no physical
+ * justification, so treat it as an effect.
  *
  * @param {object} [opts]
  * @param {number} [opts.virtualDisplayHeight=0.24]  metres of virtual display (the zoom knob).