@displayxr/inline3d 1.34.0 → 1.36.0

package/js/inline3d-cursor-depth.js

@@ -0,0 +1,311 @@
+// inline3d-cursor-depth.js — the depth-aware cursor's placement maths, dependency-free.
+//
+// The OS cursor is flat: it is drawn at zero disparity, on the glass. Hover it over content that
+// pops OUT of the glass and it is drawn on top of pixels whose disparity says they are in front
+// of it — a depth violation, and it reads as a broken image. The fix is a cursor SPRITE drawn at
+// the depth of the nearest content under it.
+//
+// This is a line-for-line port of the runtime's `u_cursor_depth` (displayxr-runtime ADR-046,
+// extension XR_DXR_cursor_depth), so a web page and a native app place their cursors
+// identically. The test file pins the same numbers as the runtime's C tests.
+//
+// Division of labour, as in the runtime: the PAGE knows its content, so it supplies the nearest
+// content point under the cursor (a raycast, a depth readback, a depth map); this module decides
+// where the sprite goes, how big it is, and how it moves over time. ./three's `DepthCursor` wires
+// both for a three.js scene. Nothing here runs unless a page calls it — opt-in, zero cost
+// otherwise.
+//
+// The geometry is solved from the VIEWS the page is about to render (projection + transform
+// matrices, column-major, as an XRView carries them), never from rig internals, so it is
+// correct for display rigs, camera rigs, any scale, and any view count >= 2:
+//
+//  - S, the canvas point under the cursor, is where the two outermost view rays through (u, v)
+//    meet (every off-axis frustum frames the same canvas);
+//  - E, the cyclopean eye, is the midpoint of those two views;
+//  - a point's depth is t = its distance in front of E along the display normal over S's
+//    (t = 1 on the canvas, t < 1 in front of it);
+//  - the policy works in DISPARITY d = 1 - 1/t, in eye-baseline units (on-screen disparity =
+//    baseline × d): 0 on the canvas, < 0 in front. The eye compares disparities, so the margin,
+//    the clamp and the slew rates live there;
+//  - the sprite goes at C = E + t (S - E) — on the cyclopean ray, so it never slides sideways
+//    as it rises — with its height scaled by t so its apparent size is constant.
+
+/** Default sprite height, as a fraction of the canvas height. */
+export const CURSOR_DEFAULT_HEIGHT = 0.03;
+
+/**
+ * The runtime's defaults (u_cursor_depth_tuning_defaults), in the same units.
+ * Disparities are in eye-baseline units; times in seconds.
+ */
+export const CURSOR_DEFAULT_TUNING = Object.freeze({
+  /** How far in front of the content the cursor floats (~2 mm on screen at 65 mm IPD). */
+  margin: 0.03,
+  /** Comfort clamp: t >= 0.625, never more than ~3/8 of the way to the eye. */
+  minDisparity: -0.6,
+  maxDisparity: 0.6,
+  /** Rising toward the viewer is fast — never lag behind content that comes forward. */
+  riseTau: 0.03,
+  /** Sinking away is slow — no flicker as the footprint crosses an edge. */
+  sinkTau: 0.25,
+  /** A gap longer than this re-primes (snaps) the filter. */
+  stale: 0.5,
+});
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+const addScaled = (a, b, s) => [a[0] + b[0] * s, a[1] + b[1] * s, a[2] + b[2] * s];
+const finite3 = (a) => Number.isFinite(a[0]) && Number.isFinite(a[1]) && Number.isFinite(a[2]);
+const rotate = (m, v) => [
+  m[0] * v[0] + m[4] * v[1] + m[8] * v[2],
+  m[1] * v[0] + m[5] * v[1] + m[9] * v[2],
+  m[2] * v[0] + m[6] * v[1] + m[10] * v[2],
+];
+
+/**
+ * The ray from a view through canvas point (u, v) — origin and (unnormalised) direction in the
+ * space of the view's transform. (u, v) is canvas-normalised: [0,1]², origin top-left, v down.
+ *
+ * Use this for the page's own hit test, so the rays it casts are exactly the rays the placement
+ * is solved from.
+ *
+ * @param {{projectionMatrix: ArrayLike<number>, transformMatrix: ArrayLike<number>}} view
+ * @param {number} u
+ * @param {number} v
+ * @returns {{origin: number[], direction: number[]}}
+ */
+export function cursorViewRay(view, u, v) {
+  const p = view.projectionMatrix;
+  const m = view.transformMatrix;
+  // Any perspective projection maps view-space (X, Y, Z) to NDC x = (a X + c Z) / -Z, so the
+  // view-space direction through NDC (x, y) is ((x + c) / a, (y + d) / b, -1).
+  const x = 2 * u - 1;
+  const y = 1 - 2 * v;
+  const d = [(x + p[8]) / p[0], (y + p[9]) / p[5], -1];
+  return { origin: [m[12], m[13], m[14]], direction: rotate(m, d) };
+}
+
+/**
+ * Solve the cursor's line of sight from two views (normally the first and the last).
+ * @returns {object|null} the geometry, or null when degenerate — coincident views (2D), parallel
+ *   rays, (u, v) off the canvas, non-finite input.
+ */
+export function solveCursorGeometry(viewA, viewB, u, v) {
+  if (!(u >= 0 && u <= 1 && v >= 0 && v <= 1)) return null;
+  const ra = cursorViewRay(viewA, u, v);
+  const rb = cursorViewRay(viewB, u, v);
+  const p1 = ra.origin, d1 = ra.direction, p2 = rb.origin, d2 = rb.direction;
+  if (!finite3(p1) || !finite3(p2) || !finite3(d1) || !finite3(d2)) return null;
+
+  // Closest points of p1 + s d1 and p2 + r d2; the midpoint absorbs float noise.
+  const w0 = sub(p1, p2);
+  const aa = dot(d1, d1), bb = dot(d1, d2), cc = dot(d2, d2);
+  const dd = dot(d1, w0), ee = dot(d2, w0);
+  const den = aa * cc - bb * bb;
+  if (dot(w0, w0) <= 0 || !(den > 1e-12 * aa * cc)) return null;
+  const s = (bb * ee - cc * dd) / den;
+  const r = (aa * ee - bb * dd) / den;
+  if (!(s > 0 && r > 0)) return null;
+  const q1 = addScaled(p1, d1, s), q2 = addScaled(p2, d2, r);
+  const canvasPoint = [(q1[0] + q2[0]) / 2, (q1[1] + q2[1]) / 2, (q1[2] + q2[2]) / 2];
+  const eye = [(p1[0] + p2[0]) / 2, (p1[1] + p2[1]) / 2, (p1[2] + p2[2]) / 2];
+
+  const ma = viewA.transformMatrix;
+  const fwd = rotate(ma, [0, 0, -1]);
+  const fl = Math.hypot(fwd[0], fwd[1], fwd[2]);
+  const forward = [fwd[0] / fl, fwd[1] / fl, fwd[2] / fl];
+  const eyeToCanvas = dot(sub(canvasPoint, eye), forward);
+  // Canvas height from view A's frustum: tan(up) - tan(down) = 2 / b.
+  const canvasHeight = dot(sub(canvasPoint, p1), forward) * (2 / viewA.projectionMatrix[5]);
+  if (!(eyeToCanvas > 0) || !(canvasHeight > 0) || !Number.isFinite(canvasHeight)) return null;
+
+  return { eye, canvasPoint, forward, eyeToCanvas, canvasHeight, basis: orthonormalBasis(ma) };
+}
+
+/** The view's rotation as unit X/Y/Z columns (a transform with parent scale still works). */
+function orthonormalBasis(m) {
+  const col = (i) => {
+    const c = [m[i], m[i + 1], m[i + 2]];
+    const l = Math.hypot(c[0], c[1], c[2]) || 1;
+    return [c[0] / l, c[1] / l, c[2] / l];
+  };
+  return { x: col(0), y: col(4), z: col(8) };
+}
+
+/**
+ * Disparity of a point (eye-baseline units; 0 on the canvas, < 0 in front).
+ * @returns {number|null} null when the point is not in front of the eye.
+ */
+export function cursorPointDisparity(g, point) {
+  if (!finite3(point)) return null;
+  const t = dot(sub(point, g.eye), g.forward) / g.eyeToCanvas;
+  if (!(t > 0) || !Number.isFinite(t)) return null;
+  return 1 - 1 / t;
+}
+
+/** Target disparity: content minus the margin, clamped; 0 (the canvas) with nothing under it. */
+export function cursorTarget(tuning, hasContent, contentDisparity) {
+  if (!hasContent || !Number.isFinite(contentDisparity)) return 0;
+  return Math.min(tuning.maxDisparity, Math.max(tuning.minDisparity, contentDisparity - tuning.margin));
+}
+
+/**
+ * Advance the filter toward `target`. `filter` is a plain object, `{}` to start (the first step
+ * snaps). A call at a time not after the previous one does not advance it.
+ * @param {number} nowSec  seconds (e.g. rAF timestamp / 1000).
+ */
+export function cursorFilterStep(filter, tuning, target, nowSec) {
+  if (!filter.primed || nowSec < filter.last || nowSec - filter.last > tuning.stale) {
+    filter.primed = true;
+    filter.disparity = target;
+    filter.last = nowSec;
+    return target;
+  }
+  if (nowSec === filter.last) return filter.disparity;
+  const dt = nowSec - filter.last;
+  const tau = target < filter.disparity ? tuning.riseTau : tuning.sinkTau;
+  const alpha = tau > 0 ? 1 - Math.exp(-dt / tau) : 1;
+  filter.disparity += alpha * (target - filter.disparity);
+  filter.last = nowSec;
+  return filter.disparity;
+}
+
+/** Where to draw a sprite at `disparity`, and how tall, for `heightFraction` of the canvas. */
+export function placeCursor(g, disparity, heightFraction) {
+  const t = 1 / (1 - disparity);
+  const hf = heightFraction > 0 && Number.isFinite(heightFraction) ? heightFraction : CURSOR_DEFAULT_HEIGHT;
+  return { position: addScaled(g.eye, sub(g.canvasPoint, g.eye), t), height: hf * g.canvasHeight * t };
+}
+
+/**
+ * The whole pipeline with its state: one per cursor.
+ *
+ *   const placer = new CursorDepthPlacer();
+ *   // per frame, with the views you are about to render:
+ *   const p = placer.update(views, { u, v, nearestPoint, cursorHeight: 0.03 }, now / 1000);
+ *   if (p.active) drawSprite(p.position, p.basis, p.height);
+ *
+ * `views` are `{projectionMatrix, transformMatrix}` (or XRViews — `transform.matrix` is read
+ * when `transformMatrix` is absent). `nearestPoint` is the content point under the cursor
+ * FOOTPRINT nearest the viewer, in the views' space, or null for "nothing under it".
+ */
+export class CursorDepthPlacer {
+  constructor(tuning = CURSOR_DEFAULT_TUNING) {
+    this.tuning = tuning;
+    this.filter = {};
+  }
+
+  update(views, hint, nowSec) {
+    const inactive = { active: false, position: null, basis: null, height: 0, disparity: 0, targetDisparity: 0 };
+    if (!views || views.length < 2 || !hint) return inactive;
+    const a = asView(views[0]);
+    const b = asView(views[views.length - 1]);
+    const g = solveCursorGeometry(a, b, hint.u, hint.v);
+    if (!g) return inactive;
+    const content = hint.nearestPoint ? cursorPointDisparity(g, hint.nearestPoint) : null;
+    const target = cursorTarget(this.tuning, content !== null, content);
+    const disparity = cursorFilterStep(this.filter, this.tuning, target, nowSec);
+    const { position, height } = placeCursor(g, disparity, hint.cursorHeight);
+    return { active: true, position, basis: g.basis, height, disparity, targetDisparity: target, geometry: g };
+  }
+}
+
+function asView(v) {
+  return v.transformMatrix ? v : { projectionMatrix: v.projectionMatrix, transformMatrix: v.transform.matrix };
+}
+
+/**
+ * The pointer half of a depth cursor, shared by every backend: tracks the pointer over the
+ * canvas (canvas-normalised, v down) and hides the CSS cursor exactly while a sprite replaces it.
+ * Constructing one adds two listeners; nothing else runs until a backend asks for `uv`.
+ */
+export class CursorPointer {
+  /** @param {HTMLElement} canvas */
+  constructor(canvas) {
+    this.canvas = canvas;
+    /** `[u, v]` while the pointer is over the canvas, else null. */
+    this.uv = null;
+    this._hidden = false;
+    this._prev = '';
+    this._onMove = (e) => {
+      const r = canvas.getBoundingClientRect();
+      this.uv = r.width > 0 && r.height > 0 ? [(e.clientX - r.left) / r.width, (e.clientY - r.top) / r.height] : null;
+    };
+    this._onLeave = () => {
+      this.uv = null;
+    };
+    canvas.addEventListener('pointermove', this._onMove);
+    canvas.addEventListener('pointerleave', this._onLeave);
+  }
+
+  /** Set the pointer directly (canvas-normalised, v down), or null — for scripted input. */
+  set(u, v) {
+    this.uv = u === null || u === undefined ? null : [u, v];
+  }
+
+  /** The canvas aspect (width / height), for a round footprint. */
+  aspect() {
+    const r = this.canvas.getBoundingClientRect();
+    return r.height > 0 ? r.width / r.height : 1;
+  }
+
+  /** Hide (true) or restore (false) the CSS cursor; idempotent. */
+  hideCss(hide) {
+    if (hide === this._hidden) return;
+    if (hide) {
+      this._prev = this.canvas.style.cursor || '';
+      this.canvas.style.cursor = 'none';
+    } else {
+      this.canvas.style.cursor = this._prev;
+    }
+    this._hidden = hide;
+  }
+
+  dispose() {
+    this.canvas.removeEventListener('pointermove', this._onMove);
+    this.canvas.removeEventListener('pointerleave', this._onLeave);
+    this.hideCss(false);
+  }
+}
+
+/**
+ * The footprint ring every backend samples: the hotspot plus 8 points on a circle of radius
+ * 0.75 × the sprite height (canvas heights), so the sprite and a margin are covered.
+ * @returns {Array<[number, number]>} canvas-normalised points, the hotspot first.
+ */
+export function cursorFootprint(u, v, height, aspect) {
+  const r = 0.75 * height;
+  const out = [[u, v]];
+  for (let k = 0; k < 8; k++) {
+    const a = (k * Math.PI) / 4;
+    out.push([u + (r * Math.cos(a)) / aspect, v + r * Math.sin(a)]);
+  }
+  return out;
+}
+
+/**
+ * The crosshair every backend draws: 8 segments in the sprite's own XY plane, unit = sprite
+ * height (a "+" with a gap and a small square at the hotspot), as [x0, y0, x1, y1] tuples.
+ */
+export const CURSOR_CROSSHAIR = Object.freeze([
+  [-0.5, 0, -0.15, 0], [0.15, 0, 0.5, 0], [0, -0.5, 0, -0.15], [0, 0.15, 0, 0.5],
+  [-0.15, -0.15, 0.15, -0.15], [0.15, -0.15, 0.15, 0.15], [0.15, 0.15, -0.15, 0.15], [-0.15, 0.15, -0.15, -0.15],
+]);
+
+/**
+ * The crosshair's segment endpoints in the views' space for a placement, as a flat
+ * [x, y, z, x, y, z, …] array (16 points) — what a line renderer takes.
+ */
+export function cursorCrosshairPoints(placement, out = []) {
+  out.length = 0;
+  const { position: p, basis: b, height: h } = placement;
+  for (const [x0, y0, x1, y1] of CURSOR_CROSSHAIR) {
+    for (const [x, y] of [[x0, y0], [x1, y1]]) {
+      out.push(
+        p[0] + (b.x[0] * x + b.y[0] * y) * h,
+        p[1] + (b.x[1] * x + b.y[1] * y) * h,
+        p[2] + (b.x[2] * x + b.y[2] * y) * h,
+      );
+    }
+  }
+  return out;
+}

package/js/inline3d-model-playcanvas.js

@@ -467,6 +467,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     farClip: opts.farClip,
     sky: false,
     viewerEase: opts.viewerEase,
+    cursor: opts.cursor,
     // Each environment's own look: 'room' is three's (untonemapped), the rest the Sample Viewer's.
     toneMapping: envMap ? 'neutral' : ENVIRONMENT_TONE_MAPPING[environment] || 'neutral',
   });

package/js/inline3d-model.js

@@ -39,7 +39,7 @@
 // docs/authoring-inline-3d.md#compressed-gltf.
 
 import * as THREE from 'three';
-import { EyeCamera, EdgeFeather } from './inline3d-three.js';
+import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest } from './inline3d-three.js';
 import { SceneViewer } from './inline3d-viewer.js';
 // Procedural — built in memory, no asset to serve. Imported eagerly rather than lazily because it
 // is the default lighting path, so deferring it would only add a frame of unlit content.
@@ -382,6 +382,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     logTag: '[inline3d/model]',
     viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
+  if (opts.cursor === 'depth') viewer.useDepthCursor(DepthCursor, (content) => raycastHitTest(THREE, [content]));
 
   if (envMap) viewer.scene.environment = envMap;
   else if (environment === 'room') addRoomEnvironment(viewer);

package/js/inline3d-playcanvas-engine.js

@@ -38,6 +38,9 @@ export {
   Quat,
   LAYERID_SKYBOX,
   LAYERID_UI,
+  LAYERID_IMMEDIATE,
+  // cursor: 'depth' (./inline3d-cursor-depth-playcanvas.js, loaded only on opt-in)
+  Picker,
   // materials / meshes (the edge feather)
   Mesh,
   MeshInstance,

package/js/inline3d-splat-playcanvas.js

@@ -823,8 +823,14 @@ export class PlayCanvasSplatViewer {
       pageCamera = false,
       toneMapping = 'none',
       viewerEase,
+      cursor = null,
     } = opts;
     this.canvas = canvas;
+    // `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.
+    this._cursorOpt = cursor;
+    this.cursorDepth = null;
     // The tracking-acquisition ease (./inline3d-viewer-ease.js): undefined = the session's
     // createInline3D({ viewerEase }) default. Built on the first 3D frame, which knows the session.
     this._viewerEaseOpt = viewerEase;
@@ -1253,6 +1259,7 @@ export class PlayCanvasSplatViewer {
       this._monoRaf = requestAnimationFrame(loop);
       this._beforeFrame?.(null);
       if (this._disposed || this._mode !== 'mono') return; // the callback removed or re-wove us
+      this.cursorDepth?.inactive(); // 2D: the normal cursor
       this._tick();
       this._drawMono();
     };
@@ -1283,6 +1290,8 @@ export class PlayCanvasSplatViewer {
     this._live = null;
     this._videoPlane?.destroy();
     this._videoPlane = null;
+    this.cursorDepth?.dispose();
+    this.cursorDepth = null;
     this.layerRigs = null; // its cameras go with the app
     try {
       this.app?.destroy();
@@ -1405,6 +1414,13 @@ export class PlayCanvasSplatViewer {
     if (this.featherPx > 0) this._makeFeather();
     this._applyTransform();
     app.start();
+    if (this._cursorOpt === 'depth') {
+      import('./inline3d-cursor-depth-playcanvas.js')
+        .then(({ PlayCanvasDepthCursor }) => {
+          if (!this._disposed) this.cursorDepth = new PlayCanvasDepthCursor(pc, this, { canvas: this.canvas });
+        })
+        .catch((err) => console.warn(`${this.logTag || '[inline3d/splat]'} cursor: 'depth' could not load; the normal cursor stays.`, err));
+    }
     return app;
   }
 
@@ -2103,6 +2119,8 @@ export class PlayCanvasSplatViewer {
     }
     // handle.setVideo's plane: size, eye split, and a new frame's upload (./inline3d-splat-video.js).
     this._videoPlane?.beforeDraw(entries, rect);
+    // cursor: 'depth' — place the sprite and queue its lines for the tick below (no-op unless opted in).
+    this.cursorDepth?.frame(entries);
     app.tick(now());
     this._afterTick();
     return true;
@@ -3216,6 +3234,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     farClip: opts.farClip,
     sky: opts.sky,
     viewerEase: opts.viewerEase,
+    cursor: opts.cursor,
   });
 
   let handle = null;

package/js/inline3d-splat.js

@@ -20,7 +20,7 @@
 
 import * as THREE from 'three';
 import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
-import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
+import { EyeCamera, EdgeFeather, cameraRigFromCamera, DepthCursor, raycastHitTest } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
 import { resolveRevealOption, effectsNotOnSpark } from './inline3d-splat-effects.js';
@@ -248,6 +248,9 @@ export function addSplat(wall, canvas, src, opts = {}) {
     logTag: '[inline3d/splat]',
     viewerEase: opts.viewerEase,
   }).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.)
+  if (opts.cursor === 'depth') viewer.useDepthCursor(DepthCursor, (content) => raycastHitTest(THREE, [content]), { raysPerFrame: 1 });
 
   // Spark renders through the ordinary three.js pipeline, so splats and meshes co-exist and
   // sort against each other — which is what lets a product page mix a captured hero with a

package/js/inline3d-three.js

@@ -52,6 +52,8 @@
 // descriptor and nothing else: no Kooima, no off-axis math, no scale, here or anywhere in this
 // SDK. That stays in the runtime, which is the point of the extension.
 
+import { CursorDepthPlacer, CursorPointer, cursorFootprint, cursorViewRay, CURSOR_CROSSHAIR, CURSOR_DEFAULT_HEIGHT } from './inline3d-cursor-depth.js';
+
 /**
  * A reusable three.js camera driven directly by an XRView's matrices. Construct once with
  * your THREE namespace and reuse across frames/windows.
@@ -413,3 +415,202 @@ export class EdgeFeather {
     renderer.autoClear = prevAutoClear;
   }
 }
+
+// ── Depth-aware cursor ─────────────────────────────────────────────────────────────────────
+
+/**
+ * A hit test for {@link DepthCursor} that raycasts three.js objects: the first hit along the
+ * ray, as a world point, or null.
+ *
+ * @param {object} THREE  your imported three.js module namespace.
+ * @param {object[]} targets  the Object3Ds that count as content (searched recursively).
+ */
+export function raycastHitTest(THREE, targets) {
+  const raycaster = new THREE.Raycaster();
+  const o = new THREE.Vector3();
+  const d = new THREE.Vector3();
+  return (origin, direction) => {
+    o.set(origin[0], origin[1], origin[2]);
+    d.set(direction[0], direction[1], direction[2]).normalize();
+    raycaster.set(o, d);
+    const hit = raycaster.intersectObjects(targets, true)[0];
+    return hit ? [hit.point.x, hit.point.y, hit.point.z] : null;
+  };
+}
+
+/**
+ * A cursor that rises to the depth of the content under it, so it is never drawn behind
+ * something that pops out of the glass (a depth violation). The page supplies the content —
+ * a hit test — and this does the rest: tracks the pointer over the canvas, hit-tests the
+ * cursor FOOTPRINT (not just the hotspot), places a crosshair sprite with the same maths and
+ * defaults as the runtime's XR_DXR_cursor_depth (ADR-046), and hides the CSS cursor exactly
+ * while the sprite replaces it.
+ *
+ * Opt-in: nothing runs unless you construct one and call update(). In 2D (one view) or with the
+ * pointer off the canvas it is inactive, the sprite is hidden and the CSS cursor is back.
+ *
+ *   const cursor = new DepthCursor(THREE, { canvas, hitTest: raycastHitTest(THREE, [model]) });
+ *   scene.add(cursor.object);
+ *   wall.addScene(canvas, (views, layer) => {
+ *     cursor.update(views);            // first, with THIS frame's views
+ *     // ... render every view as usual; the sprite draws last, depth test off ...
+ *   });
+ *
+ * Head motion: the sprite sits on the line from the viewer through the pointer's point on the
+ * canvas, so its image on the glass does not move when the head does — it stays under the
+ * mouse like the OS cursor, and only its depth follows the content under that line of sight.
+ *
+ * The attach pattern (eye cameras parented under an app camera): pass `viewSpace` = that
+ * parent, so the views' local transforms are carried into world space; keep `cursor.object` at
+ * the scene root.
+ */
+export class DepthCursor {
+  /**
+   * @param {object} THREE  your imported three.js module namespace.
+   * @param {object} opts
+   * @param {HTMLElement} opts.canvas  the woven canvas (pointer is tracked over it).
+   * @param {(origin:number[], direction:number[]) => number[]|null} opts.hitTest  nearest
+   *        content point along a ray in WORLD space, or null. {@link raycastHitTest} for meshes;
+   *        for splats return the renderer's expected depth along the ray (never raycast splats).
+   * @param {number} [opts.height=0.03]  sprite height as a fraction of the canvas height.
+   * @param {number} [opts.color=0xffd419]
+   * @param {object} [opts.viewSpace]  Object3D whose world matrix maps view transforms to world.
+   * @param {number} [opts.raysPerFrame=0]  0 = the whole footprint every frame (two eyes × 9
+   *        points). N > 0 = an EXPENSIVE hit test (e.g. a gaussian-splat raycast, ~8 ms a ray):
+   *        cast N rays a frame from the first eye, cycling through the footprint, and take the
+   *        nearest of the most recent full cycle.
+   */
+  constructor(THREE, { canvas, hitTest, height = CURSOR_DEFAULT_HEIGHT, color = 0xffd419, viewSpace = null, raysPerFrame = 0 }) {
+    this._THREE = THREE;
+    this.canvas = canvas;
+    this.hitTest = hitTest;
+    this.height = height;
+    this.viewSpace = viewSpace;
+    this.raysPerFrame = raysPerFrame;
+    this._ring = []; // amortised mode: the last hit per footprint point (null = a miss)
+    this._next = 0;
+    this.placer = new CursorDepthPlacer();
+    this.pointer = new CursorPointer(canvas);
+    /** The last placement (diagnostics): `{active, position, height, disparity, targetDisparity}`. */
+    this.placement = { active: false };
+
+    const pos = [];
+    for (const [x0, y0, x1, y1] of CURSOR_CROSSHAIR) pos.push(x0, y0, 0, x1, y1, 0);
+    const geom = new THREE.BufferGeometry();
+    geom.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3));
+    const mat = new THREE.LineBasicMaterial({ color, depthTest: false, depthWrite: false, transparent: true });
+    this.object = new THREE.LineSegments(geom, mat);
+    this.object.matrixAutoUpdate = false;
+    this.object.frustumCulled = false;
+    this.object.renderOrder = 1e9; // last: never occluded, it is in front by construction
+    this.object.visible = false;
+  }
+
+  /** Set the pointer position directly (canvas-normalised, v down), or null — for scripted input. */
+  setPointer(u, v) {
+    this.pointer.set(u, v);
+  }
+
+  /**
+   * Place the sprite for this frame. Call with the views you are about to render.
+   * @param {ArrayLike<XRView|{projectionMatrix:ArrayLike<number>,transformMatrix:ArrayLike<number>}>} views
+   * @param {number} [nowMs=performance.now()]
+   */
+  update(views, nowMs = globalThis.performance ? globalThis.performance.now() : Date.now()) {
+    const vs = this._worldViews(views);
+    const uv = this.pointer.uv;
+    let p = { active: false };
+    if (uv && vs.length >= 2) {
+      const [u, v] = uv;
+      const nearestPoint = this._footprintHit(vs, u, v);
+      p = this.placer.update(vs, { u, v, nearestPoint, cursorHeight: this.height }, nowMs / 1000);
+    }
+    this.placement = p;
+    this.object.visible = !!p.active;
+    if (p.active) {
+      const { x, y, z } = p.basis;
+      const h = p.height;
+      const e = p.position;
+      this.object.matrix.fromArray([
+        x[0] * h, x[1] * h, x[2] * h, 0,
+        y[0] * h, y[1] * h, y[2] * h, 0,
+        z[0] * h, z[1] * h, z[2] * h, 0,
+        e[0], e[1], e[2], 1,
+      ]);
+      this.object.matrixWorldNeedsUpdate = true;
+    }
+    this.pointer.hideCss(!!p.active);
+    return p;
+  }
+
+  /** Remove listeners, give the CSS cursor back, free the sprite's GPU resources. */
+  dispose() {
+    this.pointer.dispose();
+    this.object.visible = false;
+    this.object.geometry.dispose();
+    this.object.material.dispose();
+  }
+
+  // Nearest content point under the footprint, from the two outer views (or, amortised, from
+  // the first eye over the last cycle of footprint points).
+  _footprintHit(views, u, v) {
+    const a = views[0], b = views[views.length - 1];
+    const m = a.transformMatrix;
+    const fl = Math.hypot(m[8], m[9], m[10]) || 1;
+    const f = [-m[8] / fl, -m[9] / fl, -m[10] / fl];
+    const fp = cursorFootprint(u, v, this.height, this.pointer.aspect());
+    let candidates;
+    if (this.raysPerFrame > 0) {
+      const ring = this._ring;
+      ring.length = fp.length;
+      for (let i = 0; i < this.raysPerFrame; i++) {
+        const k = this._next++ % fp.length;
+        const ray = cursorViewRay(a, fp[k][0], fp[k][1]);
+        ring[k] = this.hitTest(ray.origin, ray.direction);
+      }
+      candidates = ring;
+    } else {
+      candidates = [];
+      for (const [su, sv] of fp) {
+        for (const view of [a, b]) {
+          const ray = cursorViewRay(view, su, sv);
+          candidates.push(this.hitTest(ray.origin, ray.direction));
+        }
+      }
+    }
+    let best = Infinity, nearest = null;
+    for (const p of candidates) {
+      if (!p) continue;
+      const depth = p[0] * f[0] + p[1] * f[1] + p[2] * f[2]; // smaller = nearer the viewer
+      if (depth < best) {
+        best = depth;
+        nearest = p;
+      }
+    }
+    return nearest;
+  }
+
+  _worldViews(views) {
+    const out = [];
+    if (!views) return out;
+    const parent = this.viewSpace ? this.viewSpace.matrixWorld.elements : null;
+    for (const v of views) {
+      const t = v.transformMatrix || v.transform.matrix;
+      out.push({ projectionMatrix: v.projectionMatrix, transformMatrix: parent ? mul4(parent, t) : t });
+    }
+    return out;
+  }
+}
+
+/** Column-major 4x4 multiply, a × b. */
+function mul4(a, b) {
+  const o = new Array(16);
+  for (let c = 0; c < 4; c++) {
+    for (let r = 0; r < 4; r++) {
+      let s = 0;
+      for (let k = 0; k < 4; k++) s += a[k * 4 + r] * b[c * 4 + k];
+      o[c * 4 + r] = s;
+    }
+  }
+  return o;
+}