@displayxr/inline3d 1.45.1 → 1.47.0

package/js/inline3d-cursor-depth-playcanvas.js

@@ -26,6 +26,7 @@
 import {
   CursorDepthPlacer,
   CursorPointer,
+  CursorRuntimeLink,
   CURSOR_DEFAULT_TUNING,
   cursorArrowFootprint,
   cursorDefaultHeight,
@@ -85,6 +86,8 @@ export class PlayCanvasDepthCursor {
     this._sprite = null; // { mi, node, mat } — built on first use
     /** Which sprite (CSS mirror / fixed / shapeFor); `.current` = the one drawn last. */
     this.shapes = new CursorShapeSelector(this.pointer, { shape, shapeFor });
+    /** The runtime-drawn cursor (runtime ADR-046 Amendment 4): the depth goes to the frame's layer when it says "runtime". */
+    this.runtime = new CursorRuntimeLink();
   }
 
   /** The sprite drawn last: a CURSOR_SHAPES name, 'none' or 'image'. */
@@ -96,11 +99,14 @@ export class PlayCanvasDepthCursor {
    * One 3D frame, before app.tick: schedule a pick, place the sprite, queue its lines.
    * @param {Array<{proj: ArrayLike<number>, pose: ArrayLike<number>, width: number, height: number}>} entries
    *        this frame's views, poses in RIG space (the eye cameras' parent).
+   * @param {object|null} [layer]  the frame's XRDisplayLayer: where it says "runtime" (ADR-046
+   *        Amendment 4) the raw depth goes to it and no sprite is drawn.
    */
-  frame(entries) {
+  frame(entries, layer = null) {
     const app = this.viewer.app;
     const rig = this.viewer.rigNode;
     const uv = this.pointer.uv;
+    const runtime = this.runtime.bind(layer);
     if (this._disposed || !app || !rig || !uv || !entries || entries.length < 2) {
       this.inactive();
       return;
@@ -122,6 +128,16 @@ export class PlayCanvasDepthCursor {
     if (this._frame++ % PICK_EVERY === 0 && !this._inFlight) this._pick(app, rig, entries[0], uv, h);
     const now = (globalThis.performance ? globalThis.performance.now() : Date.now()) / 1000;
     const p = this.placer.update(views, { u: uv[0], v: uv[1], nearestPoint: this.hit, cursorHeight: h, canvasPx: this.pointer.panelPx() }, now);
+    if (runtime) {
+      // The runtime draws the browser's own cursor at this depth: the raw content disparity in
+      // device px; no sprite, no CSS hide (the browser hides the OS cursor over what it drew).
+      this.runtime.report(uv[0], uv[1], p.solved ? p.contentDisparityPx : null);
+      this.placement = { ...p, active: false, runtime: true };
+      this.softening = null;
+      this.pointer.hideCss(false);
+      if (this._sprite) this._sprite.mi.visible = false;
+      return;
+    }
     this.placement = p;
     this.pointer.hideCss(!!p.active);
     const sprite = this._sprite || (p.active ? this._makeSprite(app) : null);
@@ -145,7 +161,8 @@ export class PlayCanvasDepthCursor {
 
   /** Mono / no pointer / no views: no sprite, the CSS cursor back. */
   inactive() {
-    if (this.placement.active) this.placement = { active: false };
+    this.runtime.withdraw();
+    if (this.placement.active || this.placement.runtime) this.placement = { active: false };
     this.softening = null;
     this.placer.update(null); // forget the hybrid anchor
     if (this._sprite) this._sprite.mi.visible = false;
@@ -356,6 +373,7 @@ export class PlayCanvasDepthCursor {
 
   dispose() {
     this._disposed = true;
+    this.runtime.dispose();
     this.pointer.dispose();
     this.shapes.dispose();
     try {

package/js/inline3d-cursor-depth.js

@@ -415,7 +415,12 @@ export class CursorDepthPlacer {
     const baseline = Math.hypot(ra[12] - rb[12], ra[13] - rb[13], ra[14] - rb[14]);
     const pxPerBaseline = hint.canvasPx > 0 ? (baseline / g.canvasHeight) * hint.canvasPx : null;
     const active = cursorShouldDraw(disparity, pxPerBaseline);
-    return { active, solved: true, position, basis: g.basis, height, disparity, targetDisparity: target, anchored, geometry: g, pxPerBaseline };
+    // The RAW content disparity, before the policy (ADR-046 Amendment 4 sends this, in device px).
+    const contentDisparityPx = cursorDisparityPx(content, pxPerBaseline);
+    return {
+      active, solved: true, position, basis: g.basis, height, disparity, targetDisparity: target, anchored, geometry: g, pxPerBaseline,
+      contentDisparity: content, contentDisparityPx,
+    };
   }
 }
 
@@ -626,6 +631,160 @@ function pageCursorHidden(hide) {
   else el.removeAttribute?.(CURSOR_HIDDEN_ATTR);
 }
 
+// ── The runtime draws the cursor (runtime ADR-046 Amendment 4) ──────────────────────────────
+//
+// In a DisplayXR Browser whose runtime can draw the web cursor (Windows, XR_DXR_cursor_depth
+// spec >= 8), the page supplies ONLY the depth under the pointer: `layer.setCursorDepth({
+// disparityPx, u, v })` per animation frame while the pointer is over the layer's element, and
+// `layer.setCursorDepth()` to withdraw. The runtime reads the pointer itself at weave time,
+// applies the one policy (margin, clamp, threshold, filter, hybrid anchor), draws the BROWSER's
+// own cursor (so `grab`, `pointer`, `url(…)` look exactly as they would) with the B.7 softening,
+// and the browser hides the OS cursor over what it drew. The SDK then draws no sprite and never
+// touches the CSS cursor. Anywhere else (`getCursorDepthSupport()` says "none", or the methods do
+// not exist) every backend keeps drawing its own sprite exactly as before — the fallback ladder.
+
+/** Re-ask a target that answered "none" at most this often (ms) while the cursor runs… */
+export const CURSOR_RUNTIME_RETRY_MS = 2000;
+/** …this many times per target. The browser answers "none" until its weave session is live. */
+export const CURSOR_RUNTIME_PROBES = 6;
+/**
+ * After those, a "none" is still re-asked this often, without a cap: the weave session can take tens
+ * of seconds to report (a cold GPU, a slow first frame), longer than the fast probes cover. Only a
+ * browser that HAS the API and says "none" is ever asked; one without it is never probed at all.
+ */
+export const CURSOR_RUNTIME_SLOW_RETRY_MS = 10000;
+
+/**
+ * Does `target` (an XRDisplayLayer, or a tile handle that forwards to one) take a cursor depth?
+ * Method presence only — never reads an attribute off a prototype (the `Illegal invocation` trap).
+ */
+export function cursorRuntimeCapable(target) {
+  return !!target && typeof target.setCursorDepth === 'function' && typeof target.getCursorDepthSupport === 'function';
+}
+
+/**
+ * Content disparity in eye-baseline units (< 0 in front) → on-screen device px between the two
+ * outermost rendered views (< 0 crossed), the unit `setCursorDepth` takes: `d × pxPerBaseline`.
+ * @returns {number|null}  null when either is unknown (nothing under the pointer, canvas size unknown).
+ */
+export function cursorDisparityPx(contentDisparity, pxPerBaseline) {
+  if (contentDisparity === null || contentDisparity === undefined || !Number.isFinite(contentDisparity)) return null;
+  if (!(pxPerBaseline > 0) || !Number.isFinite(pxPerBaseline)) return null;
+  const px = contentDisparity * pxPerBaseline;
+  return Number.isFinite(px) ? px : null;
+}
+
+// What each target answered, shared by every link (one support probe per layer, not per cursor).
+const _runtimeSupport = new WeakMap();
+
+/**
+ * The page half of a runtime-drawn cursor, shared by every backend. Per frame: `bind(target)` with
+ * the layer the cursor's element weaves through (true = the runtime draws, so draw NO sprite and
+ * leave the CSS cursor alone), then either `report(u, v, disparityPx)` while the pointer is over
+ * the element or `withdraw()` when it is not. Constructing one costs nothing; a cursor builds it
+ * only under `cursor: 'depth'` (ADR-046 §0).
+ */
+export class CursorRuntimeLink {
+  constructor() {
+    /** The target bound last (an XRDisplayLayer or a tile handle), or null. */
+    this.target = null;
+    this._sent = false;
+    /** The last depth sent (diagnostics): `{ u, v, disparityPx }`, or null after a withdrawal. */
+    this.last = null;
+  }
+
+  /** "runtime" | "none" | "pending" for the bound target. */
+  get support() {
+    const t = this.target;
+    if (!cursorRuntimeCapable(t)) return 'none';
+    const s = _runtimeSupport.get(t);
+    return s ? s.state : 'pending';
+  }
+
+  /** True while the bound target's runtime draws the cursor. */
+  get drawing() {
+    return this.support === 'runtime';
+  }
+
+  /**
+   * This frame's target. A new target withdraws the depth from the old one. Starts (or re-tries,
+   * rate-limited) the support probe. Returns `drawing`.
+   */
+  bind(target) {
+    const t = target || null;
+    if (t !== this.target) {
+      this.withdraw();
+      this.target = t;
+    }
+    if (!cursorRuntimeCapable(t)) return false;
+    let s = _runtimeSupport.get(t);
+    if (!s) _runtimeSupport.set(t, (s = { state: 'pending', probes: 0, inFlight: false, at: 0 }));
+    if (s.state === 'runtime' || s.inFlight) return s.state === 'runtime';
+    const now = globalThis.performance ? globalThis.performance.now() : Date.now();
+    const wait = s.probes < CURSOR_RUNTIME_PROBES ? CURSOR_RUNTIME_RETRY_MS : CURSOR_RUNTIME_SLOW_RETRY_MS;
+    if (s.probes === 0 || now - s.at >= wait) {
+      s.probes++;
+      s.at = now;
+      s.inFlight = true;
+      let p;
+      try {
+        p = Promise.resolve(t.getCursorDepthSupport());
+      } catch (e) {
+        p = Promise.reject(e);
+      }
+      p.then(
+        (r) => {
+          s.inFlight = false;
+          s.state = r === 'runtime' ? 'runtime' : 'none';
+        },
+        () => {
+          s.inFlight = false;
+          s.state = 'none';
+        },
+      );
+    }
+    return s.state === 'runtime';
+  }
+
+  /**
+   * The depth under the pointer at element-normalised (u, v), v down: `disparityPx` in device px
+   * between the outermost views (< 0 = in front), RAW — the runtime applies the policy — or null
+   * for "over the element, nothing 3D under it". A no-op unless the runtime draws.
+   */
+  report(u, v, disparityPx) {
+    if (!this.drawing) return false;
+    const d = { u: clamp01(u), v: clamp01(v) };
+    if (disparityPx !== null && disparityPx !== undefined && Number.isFinite(disparityPx)) d.disparityPx = disparityPx;
+    try {
+      this.target.setCursorDepth(d);
+    } catch {
+      return false;
+    }
+    this._sent = true;
+    this.last = { u: d.u, v: d.v, disparityPx: d.disparityPx ?? null };
+    return true;
+  }
+
+  /** Withdraw the depth (pointer off the element, 2D, teardown). Idempotent: one call per withdrawal. */
+  withdraw() {
+    this.last = null;
+    if (!this._sent) return;
+    this._sent = false;
+    try {
+      this.target?.setCursorDepth();
+    } catch {
+      /* a closed layer: its depth went with it */
+    }
+  }
+
+  dispose() {
+    this.withdraw();
+    this.target = null;
+  }
+}
+
+const clamp01 = (x) => (x > 0 ? (x < 1 ? x : 1) : 0);
+
 /**
  * A footprint ring: the point (u, v) plus 8 points on a circle of radius 0.75 × the sprite
  * height (canvas heights) around it.

package/js/inline3d-depth-budget.js

@@ -0,0 +1,342 @@
+// inline3d-depth-budget.js — how deep is this scene, in the units a 3D display cares about.
+//
+// Pure functions, dependency-free, re-exported by ./inline3d.js (the root), ./three and the
+// `./depth` subpath. NOTHING HERE CHANGES A PIXEL: these are measurements, plus one-time warnings.
+// The SDK never clamps, refuses or overrides a depth a page asked for. The one consumer that acts
+// on a number from here is the OPT-IN `depth` option of ./model and ./splat, which feeds
+// comfortDepthFactor's result into the display rig it declares (only ever lowering depth).
+//
+// The units are relative, which is what makes them portable across panels: disparity as a
+// percentage of the TILE's width, or depth in TILE HEIGHTS on a display rig (where the canvas is a
+// portal and world depth / virtualDisplayHeight equals physical depth / the tile's physical
+// height). Depth ranges measured on a panel are in docs/authoring-inline-3d.md; they are reference
+// points, not limits this module applies.
+//
+// The conversion on a display rig: physical depth z = depthH · h (h = the tile's physical height),
+// on-screen disparity p = e · z / (V ∓ z) (e = 0.063 m, V = the nominal viewer distance, − in
+// front, + behind), as a percentage of the tile width w = aspect · h. When h is unknown the
+// small-depth limit p ≈ e · z / V is used, in which h cancels: pct ≈ 100 · e · depthH / (aspect · V).
+//
+// Comfort zones (vergence–accommodation conflict) are in DIOPTERS of vergence away from the glass:
+// ΔD = 1/V − 1/z (> 0 behind, < 0 in front), and the on-screen disparity is p = e · V · ΔD. A zone
+// is a max |ΔD| on each side; comfortZone() states it, comfortDepthFactor() says how much a display
+// rig's depth would have to shrink for a subject to sit inside it (never more than 1: no zone here
+// ever ADDS depth).
+
+/** The eye separation every estimate here assumes (no browser surface reports a real one). */
+export const DEPTH_EYE_SEPARATION_M = 0.063;
+
+/** The viewer distance used when the display does not report its nominal viewer (desktop panel). */
+export const DEPTH_DEFAULT_VIEWER_M = 0.6;
+
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+
+/**
+ * Disparity, % of the tile width, of a point `depthH` tile heights out of the glass on a display
+ * rig. SIGNED like display space: `depthH > 0` is IN FRONT (toward the viewer) and gives a NEGATIVE
+ * (crossed) disparity; `depthH < 0` is behind and gives a positive one — the same sign as
+ * {@link cameraRigDisparityPct}.
+ *
+ * @param {object} o
+ * @param {number} o.depthH  tile heights out of the glass (+ in front, − behind).
+ * @param {number} o.aspect  the tile's width / height.
+ * @param {number} [o.viewerM=0.6]  nominal viewer distance, metres.
+ * @param {number} [o.heightM]  the tile's physical height, metres. Unset: the small-depth limit.
+ * @param {number} [o.ipdFactor=1]  a display rig's ipdFactor (disparity scales with it).
+ * @param {number} [o.eyeSeparationM=0.063]
+ * @returns {number} %, −Infinity at or past the viewer, NaN on bad input.
+ */
+export function disparityPct({ depthH, aspect, viewerM = DEPTH_DEFAULT_VIEWER_M, heightM, ipdFactor = 1, eyeSeparationM = DEPTH_EYE_SEPARATION_M } = {}) {
+  if (!num(depthH) || !num(aspect) || !(aspect > 0) || !num(viewerM) || !(viewerM > 0) || !num(ipdFactor)) return NaN;
+  const h = num(heightM) && heightM > 0 ? heightM : 0;
+  const denom = viewerM - depthH * h;
+  if (!(denom > 0)) return -Infinity;
+  if (depthH === 0) return 0;
+  return (-100 * eyeSeparationM * ipdFactor * depthH) / (aspect * denom);
+}
+
+/**
+ * Disparity, % of the tile width, of a point at distance `z` on a CAMERA rig:
+ * `100 · b · (1/D − 1/z) / (2 · tan(verticalFov/2) · aspect)`, `b = 0.063 · ipdFactor · metersToVirtual`,
+ * D the convergence distance. `+` = behind the glass, `−` = in front. Convergence 0 / unset is
+ * infinity (1/D = 0): everything is in front.
+ *
+ * @param {object} o
+ * @param {number} o.z  distance of the point along the camera's view axis, world units.
+ * @param {number} [o.convergence]  zero-disparity distance, world units (0 = infinity).
+ * @param {number} [o.convergenceDiopters]  or 1/distance, as the descriptor carries it.
+ * @param {number} [o.ipdFactor=1] [o.metersToVirtual=1]
+ * @param {number} o.verticalFov  FULL vertical angle, RADIANS (the descriptor's unit).
+ * @param {number} o.aspect  the tile's width / height.
+ * @returns {number} %, NaN on bad input.
+ */
+export function cameraRigDisparityPct({ z, convergence, convergenceDiopters, ipdFactor = 1, metersToVirtual = 1, verticalFov, aspect } = {}) {
+  if (!num(z) || !(z > 0) || !num(verticalFov) || !(verticalFov > 0) || !num(aspect) || !(aspect > 0)) return NaN;
+  if (!num(ipdFactor) || !num(metersToVirtual)) return NaN;
+  const invD = num(convergenceDiopters) ? Math.max(0, convergenceDiopters) : num(convergence) && convergence > 0 ? 1 / convergence : 0;
+  const b = DEPTH_EYE_SEPARATION_M * ipdFactor * metersToVirtual;
+  return (100 * b * (invD - 1 / z)) / (2 * Math.tan(verticalFov / 2) * aspect);
+}
+
+/**
+ * A depth report from a display-rig subject box (SceneViewer.getSubjectBounds' `front` / `back`,
+ * display space: +z toward the viewer, glass at 0, units of the virtual display).
+ *
+ * `frontH` / `backH` are MAGNITUDES in tile heights: how far the nearest point sits in front of the
+ * glass and the farthest behind it (0 when nothing is on that side). `frontPct` / `backPct` are the
+ * matching disparity magnitudes, % of the tile width.
+ *
+ * @param {object} o
+ * @param {number} o.front  z of the nearest surface.
+ * @param {number} o.back  z of the farthest surface.
+ * @param {number} o.virtualDisplayHeight  what one tile height is in those units.
+ * @param {number} o.aspect  the tile's width / height.
+ * @param {number} [o.viewerM=0.6] [o.heightM] [o.ipdFactor=1]  as {@link disparityPct}.
+ */
+export function depthBudgetFromBounds({ front, back, virtualDisplayHeight, aspect, viewerM = DEPTH_DEFAULT_VIEWER_M, heightM, ipdFactor = 1 } = {}) {
+  const vH = virtualDisplayHeight;
+  const ok = num(front) && num(back) && num(vH) && vH > 0;
+  const frontH = ok ? Math.max(0, front / vH) : NaN;
+  const backH = ok ? Math.max(0, -back / vH) : NaN;
+  const common = { aspect, viewerM, heightM, ipdFactor };
+  const frontPct = Math.abs(disparityPct({ depthH: frontH, ...common }));
+  const backPct = Math.abs(disparityPct({ depthH: -backH, ...common }));
+  return {
+    frontH,
+    backH,
+    frontPct,
+    backPct,
+    basis: {
+      rig: 'display',
+      aspect,
+      viewerM,
+      heightM: num(heightM) && heightM > 0 ? heightM : null,
+      ipdFactor,
+      eyeSeparationM: DEPTH_EYE_SEPARATION_M,
+    },
+  };
+}
+
+// ── comfort zones ─────────────────────────────────────────────────────────────────────────────
+
+/** The comfort zones comfortZone() knows by name; a positive number is a symmetric |ΔD| bound. */
+const COMFORT_ZONES = Object.freeze(['shibata', 'percival']);
+
+/** A `zone` comfortZone() accepts: a known name, or a finite number of diopters > 0. */
+export function isComfortZone(zone) {
+  return COMFORT_ZONES.includes(zone) || (num(zone) && zone > 0);
+}
+
+/**
+ * The comfort zone for a viewer at `viewerM`: the largest vergence change, in diopters, that is
+ * comfortable in front of the glass (`frontD`) and behind it (`behindD`), and the matching
+ * on-screen disparity magnitudes in mm (`e · V · ΔD`).
+ *
+ * - `'shibata'` (default): Shibata et al. 2011, "The zone of comfort" (J. Vision 11(8):11). The
+ *   near vergence limit is `Dv/1.035 + 0.626`, the far `Dv/1.129 − 0.442` (Dv = 1/V), so
+ *   `frontD = (Dv/1.035 + 0.626) − Dv` and `behindD = Dv − (Dv/1.129 − 0.442)`. A far limit at or
+ *   below 0 D (a distant viewer) leaves behind unbounded: `Infinity`. At 0.6 m: 0.57 D / 0.63 D.
+ * - `'percival'`: Percival's zone, ±1/3 D on both sides.
+ * - a number: a symmetric |ΔD| bound, diopters.
+ *
+ * @param {object} [o]
+ * @param {number} [o.viewerM=0.6]  viewing distance, metres.
+ * @param {'shibata'|'percival'|number} [o.zone='shibata']
+ * @returns {{zone:'shibata'|'percival'|number, viewerM:number, frontD:number, behindD:number,
+ *           frontMm:number, behindMm:number}}  NaN fields on bad input.
+ */
+export function comfortZone({ viewerM = DEPTH_DEFAULT_VIEWER_M, zone = 'shibata' } = {}) {
+  let frontD = NaN;
+  let behindD = NaN;
+  if (num(viewerM) && viewerM > 0 && isComfortZone(zone)) {
+    const Dv = 1 / viewerM;
+    if (zone === 'shibata') {
+      frontD = Dv / 1.035 + 0.626 - Dv;
+      const far = Dv / 1.129 - 0.442;
+      behindD = far > 0 ? Dv - far : Infinity;
+    } else if (zone === 'percival') {
+      frontD = behindD = 1 / 3;
+    } else {
+      frontD = behindD = zone;
+    }
+  }
+  const mm = (d) => DEPTH_EYE_SEPARATION_M * viewerM * d * 1000;
+  return { zone, viewerM, frontD, behindD, frontMm: mm(frontD), behindMm: mm(behindD) };
+}
+
+/**
+ * How much a DISPLAY rig's depth would have to shrink for a subject to sit inside a comfort zone:
+ * the largest `k ≤ 1` such that the subject's disparities scaled by `k` (a display rig's
+ * ipdFactor, with parallaxFactor moved with it) stay within {@link comfortZone}. 1 = it already
+ * fits; never above 1 — this only ever says "less".
+ *
+ * Exact geometry, at real proportions: the nearest point is `frontH` tile heights in front of the
+ * glass, physically `frontH · tileHeightM`, so at `z = V − frontH · tileHeightM` from the viewer;
+ * the farthest at `z = V + backH · tileHeightM`. Each side's `|ΔD| = |1/V − 1/z|` against the
+ * zone's bound on that side gives `k = min(1, frontD/|ΔD_front|, behindD/ΔD_behind)` (a side with
+ * no depth does not count). The SAME subject in tile heights asks more of a small, close screen —
+ * a tablet at 0.4 m carries more vergence per tile height than a laptop at 0.6 m — which is the
+ * whole reason this depends on the panel and not just on the scene.
+ *
+ * Returns 1 (no change) for any missing or invalid input — a non-finite depth, a height or
+ * viewer distance ≤ 0, an unknown zone — and when the front reaches the viewer (no finite
+ * disparity to scale): a measurement that cannot be made must never be read as "flatten it".
+ *
+ * @param {object} o
+ * @param {number} o.frontH  MAGNITUDE, tile heights in front of the glass (0 = nothing in front).
+ * @param {number} o.backH  MAGNITUDE, tile heights behind it.
+ * @param {number} o.tileHeightM  the tile's (canvas's) physical height, metres.
+ * @param {number} [o.viewerM=0.6]  NOMINAL viewer distance, metres.
+ * @param {'shibata'|'percival'|number} [o.zone='shibata']
+ * @returns {number} in (0, 1].
+ */
+export function comfortDepthFactor({ frontH, backH, tileHeightM, viewerM = DEPTH_DEFAULT_VIEWER_M, zone = 'shibata' } = {}) {
+  if (!num(frontH) || !num(backH) || !num(tileHeightM) || !(tileHeightM > 0)) return 1;
+  const z = comfortZone({ viewerM, zone });
+  if (!num(z.frontD) || Number.isNaN(z.behindD)) return 1;
+  const V = viewerM;
+  const zf = V - Math.max(0, frontH) * tileHeightM;
+  const zb = V + Math.max(0, backH) * tileHeightM;
+  if (!(zf > 0)) return 1;
+  const dFront = 1 / zf - 1 / V;
+  const dBehind = 1 / V - 1 / zb;
+  let k = 1;
+  if (dFront > 0) k = Math.min(k, z.frontD / dFront);
+  if (dBehind > 0) k = Math.min(k, z.behindD / dBehind);
+  return k > 0 ? k : 1;
+}
+
+/**
+ * The CAMERA-rig counterpart of {@link comfortDepthFactor}: the multiplier `m` on the eye
+ * separation (the rig's ipdFactor) that puts the scene's nearest point (`zNear`) and farthest
+ * (`zFar`, may be Infinity) at the edge of the comfort zone, at the given viewing distance.
+ *
+ * Measurement only; the page decides whether to apply it. Unlike the display-rig factor it can
+ * exceed 1, because a camera rig's 1 is only physical in metre-scale worlds: `ipdFactor` 1 is
+ * 63 mm × metersToVirtual in scene units, which is right for a real-sized room and far too little
+ * for a scene authored in large units (it renders nearly flat).
+ *
+ * Method: the on-screen disparity as a fraction of the tile width is
+ * `f = b · (1/D − 1/z) / (2 · tan(verticalFov/2) · aspect)` (b = 0.063 · ipdFactor ·
+ * metersToVirtual; {@link cameraRigDisparityPct} / 100), physically `p = f · aspect · tileHeightM`
+ * on the glass, which is `ΔD = p / (0.063 · V)` diopters of vergence. `m` = the smallest of
+ * zone side / |ΔD side| over the sides with content (in front: z < D, behind: z > D).
+ * Convergence 0 / unset is infinity: everything is in front.
+ *
+ * @param {object} o
+ * @param {number} o.zNear  nearest scene point along the view axis, world units (> 0).
+ * @param {number} o.zFar  farthest, world units (≥ zNear; Infinity allowed).
+ * @param {number} [o.convergence]  zero-disparity distance, world units (0 = infinity).
+ * @param {number} [o.convergenceDiopters]  or 1/distance; wins over `convergence`.
+ * @param {number} o.verticalFov  FULL vertical angle, RADIANS.
+ * @param {number} o.aspect  the tile's width / height.
+ * @param {number} o.tileHeightM  the tile's physical height, metres.
+ * @param {number} [o.viewerM=0.6] [o.zone='shibata'] [o.ipdFactor=1] [o.metersToVirtual=1]
+ * @returns {number} > 0, no upper bound; Infinity when nothing is off the plane; NaN on bad input.
+ */
+export function cameraRigComfortFactor({
+  zNear,
+  zFar,
+  convergence,
+  convergenceDiopters,
+  verticalFov,
+  aspect,
+  tileHeightM,
+  viewerM = DEPTH_DEFAULT_VIEWER_M,
+  zone = 'shibata',
+  ipdFactor = 1,
+  metersToVirtual = 1,
+} = {}) {
+  const farOk = num(zFar) || zFar === Infinity;
+  if (!num(zNear) || !(zNear > 0) || !farOk || !(zFar >= zNear)) return NaN;
+  if (!num(verticalFov) || !(verticalFov > 0) || !num(aspect) || !(aspect > 0) || !num(tileHeightM) || !(tileHeightM > 0)) return NaN;
+  if (!num(ipdFactor) || !(ipdFactor > 0) || !num(metersToVirtual) || !(metersToVirtual > 0)) return NaN;
+  const cz = comfortZone({ viewerM, zone });
+  if (!num(cz.frontD)) return NaN;
+  const invD = num(convergenceDiopters) ? Math.max(0, convergenceDiopters) : num(convergence) && convergence > 0 ? 1 / convergence : 0;
+  const b = DEPTH_EYE_SEPARATION_M * ipdFactor * metersToVirtual;
+  // ΔD of a point at z (+ behind, − in front): f · aspect · H / (e · V), the aspect cancelling.
+  const dD = (z) => (b * (invD - 1 / z) * tileHeightM) / (2 * Math.tan(verticalFov / 2) * DEPTH_EYE_SEPARATION_M * viewerM);
+  let m = Infinity;
+  const front = -dD(zNear);
+  const behind = dD(zFar);
+  if (front > 0) m = Math.min(m, cz.frontD / front);
+  if (behind > 0) m = Math.min(m, cz.behindD / behind);
+  return m;
+}
+
+// ── one-time warnings (never a behaviour change) ──────────────────────────────────────────────
+
+const CONVERGENCE_MSG =
+  '[inline3d] camera rig with convergenceDiopters 0: convergence at infinity puts the whole scene in front of the glass; ' +
+  'set convergence to the subject\'s distance.';
+
+/** Descriptors a rig builder already warned about, so setViewRig does not say it twice. */
+const builderWarned = new WeakSet();
+let builderWarnedOnce = false;
+
+/** cameraRigFromCamera / cameraRigFromPose: warn once per page when convergence is 0 / unset. */
+export function noteBuiltCameraRig(rig) {
+  if (rig.convergenceDiopters > 0) return;
+  if (!builderWarnedOnce) {
+    builderWarnedOnce = true;
+    console.warn(CONVERGENCE_MSG);
+  }
+  builderWarned.add(rig);
+}
+
+/**
+ * What looks wrong about a view-rig descriptor: `[key, message]` pairs (key = 'convergence' |
+ * 'factor' | 'fov'). Read only; the descriptor goes to the runtime exactly as given.
+ */
+export function viewRigWarnings(rig) {
+  const out = [];
+  if (!rig || typeof rig !== 'object') return out;
+  if (rig.type === 'camera') {
+    if (!(rig.convergenceDiopters > 0)) out.push(['convergence', CONVERGENCE_MSG]);
+    if (rig.verticalFov > Math.PI) {
+      out.push([
+        'fov',
+        `[inline3d] camera rig verticalFov ${rig.verticalFov} is more than π: it looks like DEGREES — the descriptor takes RADIANS ` +
+          '(cameraRigFromCamera / cameraRigFromPose convert three\'s degrees for you).',
+      ]);
+    }
+  } else if (rig.ipdFactor > 1 || rig.parallaxFactor > 1) {
+    out.push([
+      'factor',
+      `[inline3d] display rig ipdFactor ${rig.ipdFactor ?? 1} / parallaxFactor ${rig.parallaxFactor ?? 1}: above 1 exaggerates ` +
+        'depth past what the display shows by construction (1 = correct; below 1 = a comfort dial). Sent as given.',
+    ]);
+  }
+  return out;
+}
+
+/** Warn each of viewRigWarnings(rig) once per `seen` set (one per handle). */
+export function warnViewRigOnce(seen, rig) {
+  if (!rig || typeof rig !== 'object') return;
+  // The cheap common case first: called per frame by pages that drive a rig.
+  if (rig.type === 'camera' ? rig.convergenceDiopters > 0 && !(rig.verticalFov > Math.PI) : !(rig.ipdFactor > 1 || rig.parallaxFactor > 1)) return;
+  for (const [key, msg] of viewRigWarnings(rig)) {
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (key === 'convergence' && builderWarned.has(rig)) continue; // the builder said it already
+    console.warn(msg);
+  }
+}
+
+/**
+ * The hint for a `wovenState === 'withheld'` reason token (docs/woven-canvas-rules.md §3).
+ */
+export function withheldReasonHint(reason) {
+  const r = String(reason || '');
+  if (r.startsWith('cross-pass')) {
+    return 'the canvas is inside its own render surface: a CSS effect on it or an ancestor (filter, opacity < 1, mask, clip-path, mix-blend-mode, backdrop-filter). Remove it (woven-canvas rule 7)';
+  }
+  if (r === 'no-quad') {
+    return 'the canvas drew nothing the compositor can see: it is not drawing, is occluded, or a CSS effect on it or an ancestor (filter, opacity < 1, mask, clip-path, mix-blend-mode, backdrop-filter) hides it (woven-canvas rule 7)';
+  }
+  if (r === 'no-identity') return 'the canvas reached the browser without its identity: register it once, keep it mounted, cover it until firstWoven (woven-canvas rules 3-5)';
+  if (r === 'no-join') return 'nothing joined this rect; harmless off screen, otherwise check the canvas is drawing and on screen';
+  if (r === 'resolve-dropped') return "the browser could not resolve the canvas's GPU resource (a browser-side issue)";
+  return 'see docs/woven-canvas-rules.md §3';
+}

package/js/inline3d-model-entry.js

@@ -21,7 +21,7 @@
 // engine import fails, one warning names what to install, and the tile renders on three. With
 // neither, `ready` rejects naming both. An explicit `engine` never falls back.
 
-import { guardedAttach } from './inline3d-splat-shared.js';
+import { guardedAttach, validateSetStereo, resolveDepthOption } from './inline3d-splat-shared.js';
 /** The engines `addModel` renders with; the first is the default. */
 export const MODEL_ENGINES = Object.freeze(['playcanvas', 'three']);
 
@@ -71,6 +71,7 @@ export function validateModelCall(canvas, src, opts, route) {
   if (opts.orbitStyle !== undefined && opts.orbitStyle !== 'turntable' && opts.orbitStyle !== 'tilt') {
     throw new Error(`@displayxr/inline3d/model: orbitStyle must be 'turntable' or 'tilt' (got ${String(opts.orbitStyle)}).`);
   }
+  resolveDepthOption(opts.depth, '@displayxr/inline3d/model');
   if (route.engine === 'three' && route.explicit) {
     const bad = PLAYCANVAS_ONLY.filter((k) => opts[k] !== undefined && !(k === 'controls' && opts[k] === 'viewer'));
     if (bad.length) {
@@ -141,6 +142,15 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     remove: queue('remove'),
     exclude: queue('exclude'),
     unexclude: queue('unexclude'),
+    // Validated now (a bad argument throws at the call, as once the backend is in), replayed then.
+    setStereo(o) {
+      validateSetStereo(o, null, '@displayxr/inline3d/model');
+      pending.push(['setStereo', [o]]);
+      return out;
+    },
+    rig: null,
+    // The `depth` option's comfort factor in force (1 until measured, and always without it).
+    depthFactor: 1,
     // Before the backend lands: once it has, the backend's own (PlayCanvas); three has none (0).
     warmEntity: (entity, o) => out.ready.then(() => (out.warmEntity !== stubWarm && typeof out.warmEntity === 'function' ? out.warmEntity(entity, o) : 0)),
   };
@@ -233,6 +243,10 @@ async function attachThree(out, wall, canvas, src, opts, pending, mod) {
   }
   out.backend = 'three';
   out.engine = null;
+  for (const k of ['rig', 'viewRig', 'depthFactor']) {
+    Object.defineProperty(out, k, { get: () => inner[k], enumerable: true, configurable: true });
+  }
+  out.setStereo = (o) => (inner.setStereo(o), out);
   out.setPose = inner.setPose;
   out.resetPose = inner.resetPose;
   out.remove = inner.remove;