@displayxr/inline3d 1.45.1 → 1.47.0

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

@@ -55,6 +55,7 @@
 import {
   CursorDepthPlacer,
   CursorPointer,
+  CursorRuntimeLink,
   cursorArrowFootprint,
   cursorDefaultHeight,
   cursorModelMatrix,
@@ -73,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
@@ -201,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
@@ -299,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;
 }
 
@@ -314,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).
@@ -569,6 +590,13 @@ export class DepthCursor {
     this.shapes = new CursorShapeSelector(this.pointer, { shape, shapeFor });
     this._tex = null; // { geometry, material } — the textured quad, built on the first non-arrow sprite
     this._textures = new Map(); // sprite key → THREE texture
+    /**
+     * The runtime-drawn cursor (runtime ADR-046 Amendment 4): when the frame's layer says
+     * "runtime", the depth goes to the browser and no sprite is drawn. Inert without a layer.
+     */
+    this.runtime = new CursorRuntimeLink();
+    /** The XRDisplayLayer this canvas weaves through; `update(views, { layer })` sets it per frame. */
+    this.layer = null;
 
     // The arrow: a dark outline polygon, the fill inset over it; tip at the origin (the hotspot).
     const fill = [((color >> 16) & 255) / 255, ((color >> 8) & 255) / 255, (color & 255) / 255, 1];
@@ -606,10 +634,22 @@ export class DepthCursor {
 
   /**
    * Place the sprite for this frame. Call with the views you are about to render.
+   *
+   * Pass the frame's `layer` (the second argument of wall.addScene's callback) as
+   * `update(views, { layer })`: where the browser and the runtime draw the web cursor
+   * (`layer.getCursorDepthSupport()` → "runtime", runtime ADR-046 Amendment 4) the depth under the
+   * pointer is handed to the layer and no sprite is drawn — the browser's own cursor, lifted by
+   * the runtime. Without a layer, or where it says "none", the sprite is drawn as always.
    * @param {ArrayLike<XRView|{projectionMatrix:ArrayLike<number>,transformMatrix:ArrayLike<number>}>} views
-   * @param {number} [nowMs=performance.now()]
+   * @param {number|{nowMs?: number, layer?: object|null}} [opts]  the time (ms), or `{ nowMs, layer }`.
    */
-  update(views, nowMs = globalThis.performance ? globalThis.performance.now() : Date.now()) {
+  update(views, opts) {
+    let nowMs = opts;
+    if (opts && typeof opts === 'object') {
+      if ('layer' in opts) this.layer = opts.layer || null;
+      nowMs = opts.nowMs;
+    }
+    if (!(typeof nowMs === 'number' && Number.isFinite(nowMs))) nowMs = globalThis.performance ? globalThis.performance.now() : Date.now();
     if (this.debugStats) return this._updateMeasured(views, nowMs);
     return this._update(views, nowMs);
   }
@@ -631,6 +671,7 @@ export class DepthCursor {
   }
 
   _update(views, nowMs) {
+    if (this.runtime.bind(this.layer)) return this._updateRuntime(views, nowMs);
     const vs = this._worldViews(views);
     const uv = this.pointer.uv;
     let p = { active: false };
@@ -661,6 +702,27 @@ export class DepthCursor {
     return p;
   }
 
+  // The runtime draws (ADR-046 Amendment 4): the same pick and the same placement maths, but the
+  // RAW content disparity goes to the layer in device px, and nothing is drawn or hidden here.
+  _updateRuntime(views, nowMs) {
+    this.object.visible = false;
+    this.softening = null;
+    this.pointer.hideCss(false);
+    const uv = this.pointer.uv;
+    const vs = uv && views && views.length >= 2 ? this._worldViews(views) : null;
+    if (!vs) {
+      this.placer.update(null); // forget the hybrid anchor
+      this.runtime.withdraw();
+      return (this.placement = { active: false, runtime: true });
+    }
+    const [u, v] = uv;
+    const h = this.height ?? cursorDefaultHeight(this.pointer.cssHeight());
+    const nearestPoint = this._footprintHit(vs, u, v, h);
+    const p = this.placer.update(vs, { u, v, nearestPoint, cursorHeight: h, canvasPx: this.pointer.panelPx() }, nowMs / 1000);
+    this.runtime.report(u, v, p.solved ? p.contentDisparityPx : null);
+    return (this.placement = { ...p, active: false, runtime: true });
+  }
+
   // Crisp frames draw the arrow mesh exactly as without softening; softened ones swap in a quad
   // whose shader evaluates the arrow at the runtime's 13 blur taps, times the opacity.
   _useSoft(s) {
@@ -804,6 +866,7 @@ export class DepthCursor {
 
   /** Remove listeners, give the CSS cursor back, free the sprite's GPU resources. */
   dispose() {
+    this.runtime.dispose();
     this.pointer.dispose();
     this.shapes.dispose();
     this.object.visible = false;

package/js/inline3d-viewer.js

@@ -73,6 +73,7 @@ import {
   mismatchWarning,
 } from './inline3d-buffer-limit.js';
 import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
+import { parseClearColor } from './inline3d-splat-shared.js';
 
 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
@@ -269,6 +270,10 @@ export class SceneViewer {
    * @param {number} [opts.feather=0]  edge fade in buffer px (needs ./three's EdgeFeather).
    * @param {number[]} [opts.pitchLimit=[-60,60]]  degrees; stops the viewer rolling under the
    *        subject, which reads as broken rather than as a feature.
+   * @param {number[]|string} [opts.clearColor]  OPT-IN eye clear, `[r,g,b,a]` in 0..1 or a CSS
+   *        colour. Unset: the transparent clear (0,0,0,0), exactly as before. An opaque clear
+   *        avoids stale / black pixels on the weave (web#198); match the page colour behind the
+   *        canvas.
    */
   constructor(THREE, canvas, opts = {}) {
     const {
@@ -307,11 +312,19 @@ export class SceneViewer {
     this.logTag = opts.logTag || '[inline3d/viewer]';
     this.pitchLimit = pitchLimit;
     this.idleSpin = idleSpin;
+    // Opt-in (null = off, and then nothing below differs from before it existed).
+    this.clearColor = parseClearColor(opts.clearColor, this.logTag);
 
     // alpha + a zero-alpha clear so the tile can dissolve into the page rather than ending at
     // a hard rectangle. An opaque scene.background would defeat both this and the feather.
     this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
     this.renderer.setClearColor(0x000000, 0);
+    // clearColor (opt-in) replaces that clear. three reads a hex as sRGB, as a CSS colour is.
+    if (this.clearColor) {
+      const [r, g, b, a] = this.clearColor;
+      const hex = (Math.round(r * 255) << 16) | (Math.round(g * 255) << 8) | Math.round(b * 255);
+      this.renderer.setClearColor(hex, a);
+    }
     // MUST be 1. layer.getViewport() reports BACKING-STORE px, but three.js multiplies whatever
     // you pass setViewport()/setScissor() by the renderer's pixelRatio — so any other value
     // silently scales every eye viewport (at dpr 2 the left eye covers the whole canvas). It
@@ -740,7 +753,8 @@ export class SceneViewer {
     // cursor: 'depth' (ADR-046) — only when a page opted in; null otherwise.
     if (this.cursorDepth) {
       this.scene.updateMatrixWorld(); // the hit test reads THIS frame's subject pose
-      this.cursorDepth.update(g.entries.map((e) => ({ projectionMatrix: e.proj, transformMatrix: e.pose })));
+      // The layer too: where the runtime draws the web cursor (ADR-046 Amendment 4) the depth goes to it.
+      this.cursorDepth.update(g.entries.map((e) => ({ projectionMatrix: e.proj, transformMatrix: e.pose })), { layer });
     }
     const r = this.renderer;
     // getViewport() splits canvas.width; a drawing buffer the browser clamped behind our back