@displayxr/inline3d 1.45.0 → 1.46.0

package/index.d.ts

@@ -449,6 +449,14 @@ export interface TileHandle {
    * The canvas size is read at the call: call again after a resize.
    */
   displayMetrics(): Promise<DisplayMetrics>;
+  /**
+   * Runtime ADR-046 Amendment 4: hand this window's depth under the pointer to its live layer
+   * (`XRDisplayLayer.setCursorDepth`); nothing / null withdraws. Returns whether a live layer took
+   * it. `cursor: 'depth'` calls this for you; a page drawing its own pair cursor can too.
+   */
+  setCursorDepth(depth?: XRCursorDepthInit | null): boolean;
+  /** "runtime" when the browser and the runtime draw this window's cursor; "none" otherwise (incl. no live layer yet). Never rejects. */
+  getCursorDepthSupport(): Promise<'runtime' | 'none'>;
   /**
    * Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}.
    *
@@ -992,5 +1000,28 @@ export interface XRDisplayLayer {
   /** Undock this layer's asset into the floating native viewer. Optional; same probe rule. */
   undock?(init: UndockOptions): Promise<unknown>;
   getUndockCapabilities?(): Promise<UndockCapabilities>;
+  /**
+   * Runtime ADR-046 Amendment 4: the depth under the pointer, per animation frame while it is over
+   * this layer's element; no argument / null / `{}` withdraws. Optional; same probe rule.
+   */
+  setCursorDepth?(depth?: XRCursorDepthInit | null): void;
+  /** "runtime" when the browser and the runtime draw this page's cursor; else "none". Optional; same probe rule. */
+  getCursorDepthSupport?(): Promise<'runtime' | 'none'>;
   close(): void;
 }
+
+/**
+ * What a page passes to `setCursorDepth` (runtime ADR-046 Amendment 4). The runtime does the rest:
+ * the pointer (read at draw time), the policy, the anchor, the look (the browser's own cursor).
+ */
+export interface XRCursorDepthInit {
+  /**
+   * On-screen disparity in DEVICE px between the two outermost rendered views, of the nearest
+   * content under the cursor footprint; < 0 = crossed = in front of the glass. RAW content
+   * disparity, not a target. Absent / null = over the element, nothing 3D under it.
+   */
+  disparityPx?: number | null;
+  /** Where it was sampled: element-normalised, v down. */
+  u: number;
+  v: number;
+}

package/js/camera/pair-cursor.js

@@ -26,9 +26,15 @@
 // buffer px per metre = outW / tileCssWidth / metersPerCssPx (the tile handle's displayMetrics()),
 // times the eye separation (displayMetrics' default, 63 mm). Loaded only when a page asks for
 // `cursor: 'depth'` — zero cost otherwise.
+//
+// Where the browser and the runtime draw the web cursor (runtime ADR-046 Amendment 4: the tile's
+// layer answers getCursorDepthSupport() "runtime"), nothing is drawn into the buffer: the matched
+// content disparity goes to the layer RAW, in device px (−contentPx × device px per output px), and
+// the runtime draws the browser's own cursor with the one policy. Elsewhere: the arrow, as above.
 
 import {
   CursorPointer,
+  CursorRuntimeLink,
   CursorShapeSelector,
   cursorArrowFootprint,
   cursorShapePolys,
@@ -357,6 +363,8 @@ export class PairCursor {
     this.eyeSeparationM = DISPLAY_METRICS_DEFAULTS.eyeSeparationM;
     /** The last frame's placement, for diagnostics: `{ contentPx, targetPx, disparityPx, filteredPx, drawn, pxPerBaseline, soften }` (output px, + = in front) or null. */
     this.last = null;
+    /** The runtime-drawn cursor (ADR-046 Amendment 4), bound to the tile's handle each frame. */
+    this.runtime = new CursorRuntimeLink();
   }
 
   get hovering() {
@@ -373,6 +381,7 @@ export class PairCursor {
    * @param {number} nowSec
    */
   draw(g, luma, geo, nowSec) {
+    const runtime = this.runtime.bind(geo && geo.handle);
     const uv = this.pointer.uv;
     if (!uv) return this.idle();
     const [u, v] = uv;
@@ -383,8 +392,9 @@ export class PairCursor {
       this._luma = luma;
       this._uv = uv;
     }
-    this._askMetrics(geo.handle);
     const r = this.pointer.canvas.getBoundingClientRect?.();
+    if (runtime) return this._drawRuntime(u, v, r, geo);
+    this._askMetrics(geo.handle);
     const pxPerBaseline = pairPxPerBaseline(geo.outW, r && r.width, this.metersPerCssPx, this.eyeSeparationM);
     // The core's policy and filter, in its units (eye baselines, < 0 = in front).
     const content = this._content === null ? null : -this._content / pxPerBaseline;
@@ -416,6 +426,20 @@ export class PairCursor {
     return this.last;
   }
 
+  // The runtime draws (ADR-046 Amendment 4): the matched content disparity, RAW, in device px
+  // between the two views (the two halves), < 0 crossed: one output px of an eye spans
+  // (tile CSS width × dpr) / outW device px. Nothing drawn into the buffer, the CSS cursor alone.
+  _drawRuntime(u, v, r, geo) {
+    this.pointer.hideCss(false);
+    this.filter = {};
+    const dpr = globalThis.devicePixelRatio > 0 ? globalThis.devicePixelRatio : 1;
+    const k = r && r.width > 0 && geo.outW > 0 ? (r.width * dpr) / geo.outW : null;
+    const px = this._content === null || k === null ? null : -this._content * k;
+    this.runtime.report(u, v, px);
+    this.last = { contentPx: this._content, targetPx: 0, disparityPx: 0, filteredPx: 0, drawn: false, runtime: true, runtimeDisparityPx: px, pxPerBaseline: null, soften: null, shape: null };
+    return this.last;
+  }
+
   /** Ask the tile's handle once for the panel's pixel pitch; until it answers, the CSS reference px. */
   _askMetrics(handle) {
     if (!handle || handle === this._metricsFor || typeof handle.displayMetrics !== 'function') return;
@@ -438,6 +462,7 @@ export class PairCursor {
 
   /** Not drawing this frame (pointer away, tile not woven): the CSS cursor comes back. */
   idle() {
+    this.runtime.withdraw();
     this.pointer.hideCss(false);
     this.filter = {};
     this._uv = null;
@@ -446,6 +471,7 @@ export class PairCursor {
   }
 
   dispose() {
+    this.runtime.dispose();
     this.pointer.dispose();
     this.shapes.dispose();
   }

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,
+    };
   }
 }
 
@@ -458,6 +463,11 @@ export class CursorPointer {
     this._onLeave = () => {
       this.uv = null;
     };
+    // A touch (or a pen in contact) shows no cursor in the browser, so it must never drive the
+    // sprite: clear it on contact too, so a tap without a move cannot leave the last mouse hover up.
+    this._onDown = (e) => {
+      if (!cursorPointerHovers(e)) this.uv = null;
+    };
     this._target = scope === 'window' ? globalThis : canvas;
     // Freshest pointer: `pointerrawupdate` (Chromium, secure contexts) fires as each input arrives,
     // not once per frame, so the frame reads the newest position instead of one up to a frame old.
@@ -467,6 +477,7 @@ export class CursorPointer {
     this.source = supportsRawUpdate(this._target) ? 'pointerrawupdate' : 'pointermove';
     this._target.addEventListener('pointermove', this._onMove);
     if (this.source === 'pointerrawupdate') this._target.addEventListener('pointerrawupdate', this._onMove);
+    this._target.addEventListener('pointerdown', this._onDown);
     if (scope === 'window') {
       // Leaving the window (relatedTarget null) or losing focus mid-hover: nothing to hover.
       this._onOut = (e) => {
@@ -503,6 +514,12 @@ export class CursorPointer {
   // One pointer event: keep its NEWEST coalesced sample (getCoalescedEvents(), last entry), unless
   // a newer one is already held. No layout read here — uv resolves on the next read, once a frame.
   _sample(e) {
+    // Only a pointer the browser draws a cursor for: a mouse, or a pen hovering. A touch drag (or a
+    // pen stroke) clears the sprite — the browser shows no cursor there, so neither do we.
+    if (!cursorPointerHovers(e)) {
+      this.uv = null;
+      return;
+    }
     const list = typeof e.getCoalescedEvents === 'function' ? e.getCoalescedEvents() : null;
     const s = list && list.length ? list[list.length - 1] : e;
     const t = s.timeStamp > 0 ? s.timeStamp : e.timeStamp > 0 ? e.timeStamp : globalThis.performance ? globalThis.performance.now() : Date.now();
@@ -570,6 +587,7 @@ export class CursorPointer {
   dispose() {
     this._target.removeEventListener('pointermove', this._onMove);
     if (this.source === 'pointerrawupdate') this._target.removeEventListener('pointerrawupdate', this._onMove);
+    this._target.removeEventListener('pointerdown', this._onDown);
     if (this.scope === 'window') {
       globalThis.removeEventListener('pointerout', this._onOut);
       globalThis.removeEventListener('blur', this._onLeave);
@@ -580,6 +598,20 @@ export class CursorPointer {
   }
 }
 
+/**
+ * Does this pointer event come from a pointer the browser shows a cursor for? A mouse, or a pen
+ * hovering in range (no buttons pressed). A touch never; a pen in contact neither. An event with
+ * no `pointerType` (a synthetic `new PointerEvent('pointermove')`, an old engine) counts as a mouse.
+ * Coalesced samples belong to their parent event, so the parent is what is tested.
+ * @param {{pointerType?: string, buttons?: number}} e
+ */
+export function cursorPointerHovers(e) {
+  const t = e && e.pointerType;
+  if (!t || t === 'mouse') return true;
+  if (t === 'pen') return !(e.buttons > 0);
+  return false;
+}
+
 /** Does `target` dispatch `pointerrawupdate`? (Chromium; only in a secure context.) */
 export function supportsRawUpdate(target) {
   return !!target && 'onpointerrawupdate' in target && globalThis.isSecureContext !== false;
@@ -599,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-splat-playcanvas.js

@@ -1306,6 +1306,8 @@ export class PlayCanvasSplatViewer {
   onFrame(views, layer, frame) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
+    // cursor: 'depth' hands its depth to this layer where the runtime draws the web cursor (ADR-046 Amendment 4).
+    this._frameLayer = layer || null;
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
     // and the tick below may declare a new one (a focus ease) for the NEXT locate.
     if (this.layerRigs?.active) {
@@ -1348,6 +1350,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._frameLayer = null;
       this.cursorDepth?.inactive(); // 2D: the normal cursor
       this._tick();
       this._drawMono();
@@ -2221,7 +2224,7 @@ 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);
+    this.cursorDepth?.frame(entries, this._frameLayer);
     app.tick(now());
     this._afterTick();
     return true;

package/js/inline3d-three.js

@@ -55,6 +55,7 @@
 import {
   CursorDepthPlacer,
   CursorPointer,
+  CursorRuntimeLink,
   cursorArrowFootprint,
   cursorDefaultHeight,
   cursorModelMatrix,
@@ -569,6 +570,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 +614,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 +651,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 +682,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 +846,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

@@ -740,7 +740,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

package/js/inline3d.js

@@ -1274,6 +1274,42 @@ class Inline3D {
         win.viewRig = rig || null;
         return this._pushViewRig(win);
       },
+      /**
+       * Runtime ADR-046 Amendment 4: the depth under the pointer for THIS window, forwarded to its
+       * live layer's `setCursorDepth` — `{ disparityPx, u, v }` (device px between the outermost
+       * views, < 0 in front, RAW content disparity; u/v element-normalised, v down; no
+       * `disparityPx` = nothing 3D there), or nothing / null to withdraw. Returns whether a live
+       * layer took it. The depth cursors call this for you under `cursor: 'depth'`.
+       */
+      setCursorDepth: (depth) => {
+        const layer = win.layer;
+        if (!layer || typeof layer.setCursorDepth !== 'function') return false;
+        try {
+          if (depth) layer.setCursorDepth(depth);
+          else layer.setCursorDepth();
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      /**
+       * "runtime" when the browser AND the runtime draw this window's cursor (the page then supplies
+       * only the depth, setCursorDepth); "none" otherwise — including no live layer yet, so ask
+       * again later. Never rejects.
+       * @returns {Promise<'runtime'|'none'>}
+       */
+      getCursorDepthSupport: () => {
+        const layer = win.layer;
+        if (!layer || typeof layer.getCursorDepthSupport !== 'function') return Promise.resolve('none');
+        try {
+          return Promise.resolve(layer.getCursorDepthSupport()).then(
+            (s) => (s === 'runtime' ? 'runtime' : 'none'),
+            () => 'none',
+          );
+        } catch {
+          return Promise.resolve('none');
+        }
+      },
       /**
        * The panel this window is weaving on: physical size in metres, pixel size, and the view
        * scale the runtime RECOMMENDS. Resolves null on a machine with no glasses-free display.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.45.0",
+  "version": "1.46.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/three.d.ts

@@ -143,6 +143,7 @@ export class EdgeFeather {
   ): void;
 }
 
+import type { CursorRuntimeLink } from './cursor-depth.js';
 import type { CursorAnchorMode, CursorPlacement, CursorShape, CursorShapeHit, CursorShapeOption, CursorSoftenOption, CursorSoftenParams, CursorSoftening, CursorView } from './cursor-depth.js';
 
 /** One second of `debug` stats: each figure as `{ mean, p95, max, n }`. */
@@ -234,8 +235,17 @@ export class DepthCursor {
   readonly softening: CursorSoftening | null;
   /** The sprite drawn last: a name, 'none' or 'image'. */
   readonly shape: CursorShape | 'none' | 'image';
-  /** Place the sprite for this frame — call with the views you are about to render, before rendering. */
-  update(views: ArrayLike<XRView | CursorView>, nowMs?: number): CursorPlacement | { active: false };
+  /** The runtime-drawn cursor link (runtime ADR-046 Amendment 4). */
+  readonly runtime: CursorRuntimeLink;
+  /** The layer this canvas weaves through, as last passed to `update(views, { layer })`. */
+  layer: unknown;
+  /**
+   * Place the sprite for this frame — call with the views you are about to render, before rendering.
+   * Pass `{ layer }` (addScene's second callback argument): where it says "runtime" (ADR-046
+   * Amendment 4) the depth goes to the layer and the browser's own cursor is lifted by the runtime;
+   * no sprite is drawn. A number is the time in ms, as before.
+   */
+  update(views: ArrayLike<XRView | CursorView> | null, opts?: number | { nowMs?: number; layer?: unknown }): CursorPlacement | { active: false; runtime?: boolean };
   /** Set the pointer directly (canvas-normalised, v down), or null — for scripted input. */
   setPointer(u: number | null, v?: number): void;
   /** Remove listeners, restore the CSS cursor, free the sprite's GPU resources. */