@displayxr/inline3d 1.40.2 → 1.42.0

package/js/inline3d-cursor-depth.js

@@ -40,28 +40,74 @@
 //                 put; a depth change slides it along that line, so it stays on the click point
 //                 for the viewer who placed it. Continuous at the stop frame.
 //    The height is scaled by t either way, so the apparent size is constant.
+//
+// THE POLICY (ADR-046 Amendment 2, the same for every DisplayXR depth cursor — this module, ./three's
+// DepthCursor, `cursor: 'depth'` on ./model and ./splat, and the stereo-tile cursor on ./call and
+// ./camera, which calls the pieces exported here):
+//  - never behind the glass: target = d < 0 ? max(d - margin, dMin) : 0 — it only comes forward,
+//    to stay ahead of content that comes OUT of the screen (cursorTarget);
+//  - margin 0.015 eye baselines (~1 mm of crossed on-screen disparity at a 63-65 mm IPD);
+//  - on the plane it IS the OS cursor: nothing is drawn while the filtered disparity is above
+//    CURSOR_DRAW_THRESHOLD (-0.005, ~0.3 mm) or under CURSOR_DRAW_MIN_PX on the panel
+//    (cursorShouldDraw), and the CSS cursor is left alone;
+//  - the look: the classic arrow (CURSOR_ARROW, tip = hotspot), at the OS cursor's size
+//    (CURSOR_ARROW_CSS_PX tall on the page, cursorDefaultHeight).
 
 import { CURSOR_ANCHOR_MODES } from './inline3d-cursor-option.js';
 
 export { CURSOR_ANCHOR_MODES, CURSOR_OPTION_KEYS, resolveCursorOption } from './inline3d-cursor-option.js';
 
-/** Default sprite height, as a fraction of the canvas height. */
+/**
+ * Fallback sprite height, as a fraction of the canvas height, when the canvas's on-page size is
+ * unknown. With a known size the default is the OS cursor's size (cursorDefaultHeight).
+ */
 export const CURSOR_DEFAULT_HEIGHT = 0.03;
 
+/** The OS arrow's height in CSS px: the drawn arrow's default size, so the hand-over is seamless. */
+export const CURSOR_ARROW_CSS_PX = 19;
+
+/**
+ * The default sprite height for a canvas `cssHeight` CSS px tall: the OS arrow's 19 CSS px, as a
+ * fraction of it (capped at half the canvas). Recompute it when the canvas resizes.
+ */
+export function cursorDefaultHeight(cssHeight) {
+  return cssHeight > 0 && Number.isFinite(cssHeight) ? Math.min(0.5, CURSOR_ARROW_CSS_PX / cssHeight) : CURSOR_DEFAULT_HEIGHT;
+}
+
+/**
+ * The draw threshold (eye-baseline units): the sprite is drawn only while the FILTERED disparity is
+ * at or below this (~0.3 mm of on-screen disparity at a 65 mm IPD). Above it, the OS cursor is the
+ * cursor and nothing is drawn.
+ */
+export const CURSOR_DRAW_THRESHOLD = -0.005;
+/** …and never while the on-screen disparity is under this many panel pixels (where they are knowable). */
+export const CURSOR_DRAW_MIN_PX = 0.5;
+
+/**
+ * Should the sprite be drawn at filtered `disparity`? Only while it is in front of the glass by at
+ * least the draw threshold, and — when `pxPerBaseline` (panel pixels of on-screen disparity per
+ * eye-baseline unit) is known — by at least CURSOR_DRAW_MIN_PX.
+ */
+export function cursorShouldDraw(disparity, pxPerBaseline) {
+  if (!(disparity <= CURSOR_DRAW_THRESHOLD)) return false;
+  return !(pxPerBaseline > 0 && Number.isFinite(pxPerBaseline)) || -disparity * pxPerBaseline >= CURSOR_DRAW_MIN_PX;
+}
+
 /**
  * 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. 0.005 baseline is ~1.5 mm at a 60 cm
-   * viewing distance: it RESTS on what it hovers. (1.36.0 shipped 0.03, ~1–2 cm, which a tester
-   * on a panel found floated visibly off shallow content.)
+   * How far in front of out-of-screen content the cursor floats: 0.015 eye baselines, ~1 mm of
+   * crossed on-screen disparity at a 63-65 mm IPD (ADR-046 Amendment 2 A.2; halved from 0.03 on
+   * 2026-10-11 after a Windows panel check: 0.03 floated visibly off the content).
    */
-  margin: 0.005,
+  margin: 0.015,
   /** Comfort clamp: t >= 0.625, never more than ~3/8 of the way to the eye. */
   minDisparity: -0.6,
-  maxDisparity: 0.6,
+  /** Never behind the glass: 0, and cursorTarget never goes above 0 whatever this says. */
+  maxDisparity: 0,
   /** 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. */
@@ -161,10 +207,15 @@ export function cursorPointDisparity(g, point) {
   return 1 - 1 / t;
 }
 
-/** Target disparity: content minus the margin, clamped; 0 (the canvas) with nothing under it. */
+/**
+ * Target disparity — the policy: `d < 0 ? max(d - margin, dMin) : 0`. Content in front of the glass
+ * (d < 0) puts the cursor the margin in front of it (clamped); content on or behind the glass, or
+ * nothing under it, leaves it ON the glass. Never behind it: the result is never above 0.
+ */
 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));
+  if (!hasContent || !Number.isFinite(contentDisparity) || !(contentDisparity < 0)) return 0;
+  const hi = Math.min(0, Number.isFinite(tuning.maxDisparity) ? tuning.maxDisparity : 0);
+  return Math.min(hi, Math.max(tuning.minDisparity, contentDisparity - tuning.margin));
 }
 
 /**
@@ -204,12 +255,17 @@ const POINTER_STILL_EPS = 1e-4;
  *
  *   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);
+ *   const p = placer.update(views, { u, v, nearestPoint, cursorHeight, canvasPx }, now / 1000);
+ *   if (p.active) drawSprite(p.position, p.basis, p.height); // else: the OS cursor, untouched
  *
  * `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".
+ * FOOTPRINT nearest the viewer, in the views' space, or null for "nothing under it". `canvasPx`
+ * (optional) is the canvas's height in panel pixels, for the draw threshold's pixel floor.
+ *
+ * `active` is the DRAW decision (cursorShouldDraw on the filtered disparity): false on the plane,
+ * where the OS cursor is the cursor. The filter and the anchor keep running either way, and
+ * `solved` says the geometry was (position etc. are then filled for diagnostics).
  */
 export class CursorDepthPlacer {
   /**
@@ -228,7 +284,7 @@ export class CursorDepthPlacer {
   }
 
   update(views, hint, nowSec) {
-    const inactive = { active: false, position: null, basis: null, height: 0, disparity: 0, targetDisparity: 0 };
+    const inactive = { active: false, solved: false, position: null, basis: null, height: 0, disparity: 0, targetDisparity: 0 };
     if (!views || views.length < 2 || !hint) {
       this._line = null;
       this._last = null;
@@ -270,7 +326,13 @@ export class CursorDepthPlacer {
       }
     }
     this._last = [hint.u, hint.v];
-    return { active: true, position, basis: g.basis, height, disparity, targetDisparity: target, anchored, geometry: g };
+    // Panel px of on-screen disparity per baseline unit: the outer views' baseline over the canvas
+    // height, in the views' space, times the canvas height in panel px.
+    const ra = a.transformMatrix, rb = b.transformMatrix;
+    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 };
   }
 }
 
@@ -336,7 +398,24 @@ export class CursorPointer {
     return r.height > 0 ? r.width / r.height : 1;
   }
 
-  /** Hide (true) or restore (false) the CSS cursor; idempotent. */
+  /** The canvas's on-page height, CSS px (0 when unknown). */
+  cssHeight() {
+    const r = this.canvas.getBoundingClientRect();
+    return r.height > 0 ? r.height : 0;
+  }
+
+  /** The canvas's height in panel (device) pixels, or 0 when unknown. */
+  panelPx() {
+    return this.cssHeight() * (globalThis.devicePixelRatio > 0 ? globalThis.devicePixelRatio : 1);
+  }
+
+  /**
+   * Hide (true) or restore (false) the CSS cursor; idempotent. Only ever while a sprite replaces
+   * it: whatever cursor the page set (`pointer`, `grab`, a `url(…)` image) is the cursor the rest of
+   * the time, and a cursor the page changes while it is hidden is not overwritten on restore.
+   * (Mirroring the page's CSS cursor INTO the drawn sprite is future work — ADR-046 Amendment 2 C,
+   * the browser feeding the computed CSS cursor to the runtime; today the sprite is the arrow.)
+   */
   hideCss(hide) {
     if (hide === this._hidden) return;
     if (this.scope === 'window') {
@@ -344,8 +423,8 @@ export class CursorPointer {
     } else if (hide) {
       this._prev = this.canvas.style.cursor || '';
       this.canvas.style.cursor = 'none';
-    } else {
-      this.canvas.style.cursor = this._prev;
+    } else if (this.canvas.style.cursor === 'none') {
+      this.canvas.style.cursor = this._prev; // only if it is still ours
     }
     this._hidden = hide;
   }
@@ -380,9 +459,9 @@ function pageCursorHidden(hide) {
 }
 
 /**
- * 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.
+ * A footprint ring: the point (u, v) plus 8 points on a circle of radius 0.75 × the sprite
+ * height (canvas heights) around it.
+ * @returns {Array<[number, number]>} canvas-normalised points, (u, v) first.
  */
 export function cursorFootprint(u, v, height, aspect) {
   const r = 0.75 * height;
@@ -395,34 +474,98 @@ export function cursorFootprint(u, v, height, aspect) {
 }
 
 /**
- * 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.
+ * The footprint every backend samples for the ARROW: the hotspot (its tip) first, then a ring
+ * around the arrow's BODY, which hangs down-right of the tip — that is what content must not
+ * overlap. Canvas-normalised, v down.
+ * @returns {Array<[number, number]>}
  */
-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],
-]);
+export function cursorArrowFootprint(u, v, height, aspect) {
+  return [[u, v], ...cursorFootprint(u + (0.3 * height) / aspect, v + 0.5 * height, height, aspect)];
+}
+
+/**
+ * The classic pointer arrow every backend draws (ADR-046 Amendment 2: the depth cursor is the
+ * cursor the user already has; where its shape cannot be read, this). The OS arrow's outline,
+ * 12 × 19 px normalised: unit = its height, x right, y DOWN, the hotspot = the TIP at (0, 0). This
+ * is the DARK outline's polygon; the white fill is it inset by one px (CURSOR_ARROW_FILL).
+ */
+export const CURSOR_ARROW = Object.freeze(
+  [[0, 0], [0, 16], [4.2, 12.4], [6.9, 18.6], [9.5, 17.5], [6.8, 11.5], [11.7, 11.5]].map(([x, y]) => Object.freeze([x / 19, y / 19])),
+);
+
+/** Triangles over CURSOR_ARROW's vertices (indices): a fan from the tip over the head, the tail as two. */
+const ARROW_TRIS = Object.freeze([[0, 1, 2], [0, 2, 5], [0, 5, 6], [2, 3, 4], [2, 4, 5]]);
+
+/**
+ * CURSOR_ARROW inset by `d` (units of its height) — mitred, so every edge moves in by exactly d.
+ * @returns {Array<[number, number]>}
+ */
+export function cursorArrowInset(d, poly = CURSOR_ARROW) {
+  let area = 0;
+  for (let i = 0; i < poly.length; i++) {
+    const [x0, y0] = poly[i], [x1, y1] = poly[(i + 1) % poly.length];
+    area += x0 * y1 - x1 * y0;
+  }
+  const sgn = area > 0 ? 1 : -1;
+  const n = poly.map((p, i) => {
+    const q = poly[(i + 1) % poly.length];
+    const dx = q[0] - p[0], dy = q[1] - p[1];
+    const l = Math.hypot(dx, dy) || 1;
+    return [(-dy / l) * sgn, (dx / l) * sgn]; // inward normal of edge i → i+1
+  });
+  return poly.map((p, i) => {
+    const a = n[(i + poly.length - 1) % poly.length], b = n[i];
+    const k = d / (1 + a[0] * b[0] + a[1] * b[1]);
+    return [p[0] + (a[0] + b[0]) * k, p[1] + (a[1] + b[1]) * k];
+  });
+}
 
-/** Fill and outline stroke widths, in sprite heights; and their colours (RGBA, 0..1). */
-const STROKE_FILL = 0.07;
-const STROKE_OUTLINE = 0.15;
-export const CURSOR_FILL_COLOR = Object.freeze([1, 0.84, 0.1, 1]);
-export const CURSOR_OUTLINE_COLOR = Object.freeze([0.04, 0.04, 0.06, 0.85]);
+/** The white fill: the arrow inset by one px of its 19. */
+export const CURSOR_ARROW_FILL = Object.freeze(cursorArrowInset(1 / 19).map((p) => Object.freeze(p)));
+
+/** The arrow's colours (RGBA, 0..1): white fill, dark outline — the OS arrow. */
+export const CURSOR_FILL_COLOR = Object.freeze([1, 1, 1, 1]);
+export const CURSOR_OUTLINE_COLOR = Object.freeze([0.02, 0.02, 0.03, 1]);
 
 /**
- * The crosshair as FILLED strokes in its own XY plane (unit = sprite height): a dark outline
- * pass first, the coloured fill over it — the order a depth-test-off draw needs. A 1 px line
- * reads too thin through a lenticular panel. Triangles, non-indexed.
+ * The arrow as a filled 3D mesh in its own XY plane (unit = sprite height, x right, y UP, the tip
+ * = the hotspot at the origin, so cursorModelMatrix puts the tip on the placement): the dark
+ * outline polygon first, the white fill over it — the order a depth-test-off draw needs.
+ * Triangles, non-indexed. Shared by three, PlayCanvas and (in 2D) the stereo-tile cursor.
  * @returns {{positions: Float32Array, colors: Float32Array, count: number}}
  */
-export function cursorCrosshairMesh(fill = CURSOR_FILL_COLOR, outline = CURSOR_OUTLINE_COLOR) {
+export function cursorArrowMesh(fill = CURSOR_FILL_COLOR, outline = CURSOR_OUTLINE_COLOR) {
+  const pos = [];
+  const col = [];
+  for (const [poly, c] of [[CURSOR_ARROW, outline], [CURSOR_ARROW_FILL, fill]]) {
+    for (const tri of ARROW_TRIS) {
+      for (const k of tri) {
+        pos.push(poly[k][0], -poly[k][1], 0);
+        col.push(c[0], c[1], c[2], c[3]);
+      }
+    }
+  }
+  return { positions: new Float32Array(pos), colors: new Float32Array(col), count: pos.length / 3 };
+}
+
+// The retired crosshair (1.36–1.40), kept only behind the deprecated cursorCrosshairMesh.
+const CROSSHAIR = [
+  [-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],
+];
+
+/**
+ * @deprecated The crosshair is retired (ADR-046 Amendment 2): every depth cursor draws the arrow,
+ * cursorArrowMesh(). Kept for pages that built their own sprite from it; removed in 2.0.
+ */
+export function cursorCrosshairMesh(fill = [1, 0.84, 0.1, 1], outline = [0.04, 0.04, 0.06, 0.85]) {
   const pos = [];
   const col = [];
   const quad = ([x0, y0, x1, y1], w, ext, c) => {
     const dx = x1 - x0, dy = y1 - y0;
     const l = Math.hypot(dx, dy) || 1;
-    const ux = dx / l, uy = dy / l; // along
-    const nx = -uy * (w / 2), ny = ux * (w / 2); // across
+    const ux = dx / l, uy = dy / l;
+    const nx = -uy * (w / 2), ny = ux * (w / 2);
     const ax = x0 - ux * ext, ay = y0 - uy * ext, bx = x1 + ux * ext, by = y1 + uy * ext;
     const v = [[ax - nx, ay - ny], [bx - nx, by - ny], [bx + nx, by + ny], [ax - nx, ay - ny], [bx + nx, by + ny], [ax + nx, ay + ny]];
     for (const [x, y] of v) {
@@ -430,14 +573,14 @@ export function cursorCrosshairMesh(fill = CURSOR_FILL_COLOR, outline = CURSOR_O
       col.push(c[0], c[1], c[2], c[3]);
     }
   };
-  for (const seg of CURSOR_CROSSHAIR) quad(seg, STROKE_OUTLINE, (STROKE_OUTLINE - STROKE_FILL) / 2, outline);
-  for (const seg of CURSOR_CROSSHAIR) quad(seg, STROKE_FILL, 0, fill);
+  for (const seg of CROSSHAIR) quad(seg, 0.15, 0.04, outline);
+  for (const seg of CROSSHAIR) quad(seg, 0.07, 0, fill);
   return { positions: new Float32Array(pos), colors: new Float32Array(col), count: pos.length / 3 };
 }
 
 /**
- * A column-major model matrix placing the unit crosshair for a placement: the sprite's basis
- * scaled by its height, at its position.
+ * A column-major model matrix placing the unit sprite (the arrow, tip at its origin) for a
+ * placement: the sprite's basis scaled by its height, its origin (the hotspot) at its position.
  */
 export function cursorModelMatrix(placement, out = new Array(16)) {
   const { x, y, z } = placement.basis;
@@ -449,23 +592,3 @@ export function cursorModelMatrix(placement, out = new Array(16)) {
   out[12] = e[0]; out[13] = e[1]; out[14] = e[2]; out[15] = 1;
   return out;
 }
-
-/**
- * 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-three.js

@@ -55,12 +55,13 @@
 import {
   CursorDepthPlacer,
   CursorPointer,
-  cursorCrosshairMesh,
-  cursorFootprint,
+  cursorArrowMesh,
+  cursorArrowFootprint,
+  cursorDefaultHeight,
   cursorModelMatrix,
   cursorViewRay,
-  CURSOR_DEFAULT_HEIGHT,
   CURSOR_DEFAULT_TUNING,
+  CURSOR_OUTLINE_COLOR,
 } from './inline3d-cursor-depth.js';
 
 /**
@@ -451,9 +452,13 @@ export function raycastHitTest(THREE, targets) {
  * 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.
+ * cursor FOOTPRINT (not just the hotspot), places the arrow sprite with the same maths and
+ * policy as the runtime's XR_DXR_cursor_depth (ADR-046 Amendment 2), and hides the CSS cursor
+ * exactly while the sprite replaces it.
+ *
+ * Front-only: the sprite is drawn only while content under it comes OUT of the glass, the margin
+ * in front of it. Over content on or behind the glass nothing is drawn — the CSS/OS cursor is the
+ * cursor, untouched. The sprite is the classic arrow at the OS cursor's size, tip on the hotspot.
  *
  * 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.
@@ -481,10 +486,11 @@ export class DepthCursor {
    * @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=0xffd61a]  fill colour (the outline is always dark).
-   * @param {number} [opts.margin=0.005]  how far in front of the content it floats, in eye-baseline
-   *        units (0.005 ≈ 1.5 mm at 60 cm: it rests on the content).
+   * @param {number} [opts.height]  sprite height as a fraction of the canvas height. Default: the
+   *        OS arrow's size, 19 CSS px of the canvas's on-page height (re-read every frame).
+   * @param {number} [opts.color=0xffffff]  the arrow's fill colour (the outline is always dark).
+   * @param {number} [opts.margin=0.015]  how far in front of out-of-screen content it floats, in
+   *        eye-baseline units (0.015 ≈ 1 mm of on-screen disparity at a 63-65 mm IPD).
    * @param {'hybrid'|'screen'|'world'} [opts.anchor='hybrid']  where along that depth: 'hybrid'
    *        follows the pointer exactly while it moves and stays world-fixed (parallaxes with the
    *        content) while it is still; 'screen' never parallaxes; 'world' always does.
@@ -498,12 +504,13 @@ export class DepthCursor {
    */
   constructor(
     THREE,
-    { canvas, hitTest, height = CURSOR_DEFAULT_HEIGHT, color = 0xffd61a, viewSpace = null, raysPerFrame = 0, margin, anchor = 'hybrid', pointerScope = 'canvas' },
+    { canvas, hitTest, height = null, color = 0xffffff, viewSpace = null, raysPerFrame = 0, margin, anchor = 'hybrid', pointerScope = 'canvas' },
   ) {
     this._THREE = THREE;
     this.canvas = canvas;
     this.hitTest = hitTest;
-    this.height = height;
+    /** Sprite height (canvas heights) when set; null = the OS arrow's size, from the canvas's on-page height. */
+    this.height = height > 0 && Number.isFinite(height) ? height : null;
     this.viewSpace = viewSpace;
     this.raysPerFrame = raysPerFrame;
     this._ring = []; // amortised mode: the last hit per footprint point (null = a miss)
@@ -514,9 +521,9 @@ export class DepthCursor {
     /** The last placement (diagnostics): `{active, position, height, disparity, targetDisparity, anchored}`. */
     this.placement = { active: false };
 
-    // Filled strokes with a dark outline (a 1 px line reads too thin through the lens).
+    // 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];
-    const m = cursorCrosshairMesh(fill);
+    const m = cursorArrowMesh(fill, CURSOR_OUTLINE_COLOR);
     const geom = new THREE.BufferGeometry();
     geom.setAttribute('position', new THREE.Float32BufferAttribute(m.positions, 3));
     geom.setAttribute('color', new THREE.Float32BufferAttribute(m.colors, 4));
@@ -552,8 +559,9 @@ export class DepthCursor {
     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);
+      const h = this.height ?? cursorDefaultHeight(this.pointer.cssHeight());
+      const nearestPoint = this._footprintHit(vs, u, v, h);
+      p = this.placer.update(vs, { u, v, nearestPoint, cursorHeight: h, canvasPx: this.pointer.panelPx() }, nowMs / 1000);
     }
     this.placement = p;
     this.object.visible = !!p.active;
@@ -575,12 +583,12 @@ export class DepthCursor {
 
   // 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) {
+  _footprintHit(views, u, v, height) {
     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());
+    const fp = cursorArrowFootprint(u, v, height, this.pointer.aspect());
     let candidates;
     if (this.raysPerFrame > 0) {
       const ring = this._ring;

package/model.d.ts

@@ -50,10 +50,12 @@ export interface ModelOptions {
    */
   viewerEase?: ViewerEaseOption;
   /**
-   * `'depth'`: a cursor that rises to the subject under it instead of being drawn on the glass,
-   * behind content that pops out (ADR-046, same maths as native `XR_DXR_cursor_depth`). A
-   * crosshair just in front of the nearest content under the pointer's footprint; the CSS cursor
-   * is hidden while it shows and comes back in 2D and off the canvas. OPT-IN: without it nothing
+   * `'depth'`: a cursor that is never drawn on the glass behind content that pops out (ADR-046 +
+   * Amendment 2, the same policy as native `XR_DXR_cursor_depth`). While the subject under the
+   * pointer's footprint comes OUT of the screen, the classic arrow (the OS cursor's size, tip on
+   * the hotspot) is drawn the margin (0.015 eye baselines, ~1 mm) in front of it and the CSS cursor
+   * is hidden; over anything on or behind the glass nothing is drawn and the CSS cursor is the
+   * cursor, untouched. Never behind the glass. OPT-IN: without it nothing
    * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,
    * one low-res pass every other frame while the pointer is over the tile). three: a raycast
    * against the subject. Pass an object to tune it: `{ margin, anchor, height, pointerScope }`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.40.2",
+  "version": "1.42.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/splat.d.ts

@@ -474,10 +474,12 @@ export interface SplatOptions {
    */
   viewerEase?: ViewerEaseOption;
   /**
-   * `'depth'`: a cursor that rises to the subject under it instead of being drawn on the glass,
-   * behind content that pops out (ADR-046, same maths as native `XR_DXR_cursor_depth`). A
-   * crosshair just in front of the nearest content under the pointer's footprint; the CSS cursor
-   * is hidden while it shows and comes back in 2D and off the canvas. OPT-IN: without it nothing
+   * `'depth'`: a cursor that is never drawn on the glass behind content that pops out (ADR-046 +
+   * Amendment 2, the same policy as native `XR_DXR_cursor_depth`). While the subject under the
+   * pointer's footprint comes OUT of the screen, the classic arrow (the OS cursor's size, tip on
+   * the hotspot) is drawn the margin (0.015 eye baselines, ~1 mm) in front of it and the CSS cursor
+   * is hidden; over anything on or behind the glass nothing is drawn and the CSS cursor is the
+   * cursor, untouched. Never behind the glass. OPT-IN: without it nothing
    * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,
    * one low-res pass every other frame while the pointer is over the tile). three: a raycast
    * against the subject. Pass an object to tune it: `{ margin, anchor, height, pointerScope }`

package/three.d.ts

@@ -157,12 +157,15 @@ export function raycastHitTest(
 /**
  * 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. Same maths and defaults as the runtime's XR_DXR_cursor_depth
- * (ADR-046). Tracks the pointer over `canvas`, hit-tests the cursor FOOTPRINT, places a crosshair
- * (`object`, add it to your scene) and hides the CSS cursor exactly while the crosshair replaces it.
+ * (ADR-046, Amendment 2's policy). Tracks the pointer over `canvas`, hit-tests the cursor FOOTPRINT,
+ * and — only while content under it comes OUT of the glass — draws the classic arrow (`object`, add
+ * it to your scene; tip on the hotspot, the OS cursor's size) the margin in front of it, hiding the
+ * CSS cursor exactly then. Over content on or behind the glass nothing is drawn: the CSS cursor is
+ * the cursor, untouched. Never behind the glass.
  * Opt-in: nothing runs unless you construct one and call `update(views)` each frame.
  *
- * Head motion leaves the crosshair's image on the glass where it is (it stays under the mouse like
- * the OS cursor); only its depth follows the content under that line of sight.
+ * Head motion: while the pointer moves the arrow sits on the line of sight through it; while it is
+ * still, it is held world-fixed (default `anchor: 'hybrid'`), so it parallaxes like content.
  */
 export class DepthCursor {
   constructor(
@@ -172,11 +175,11 @@ export class DepthCursor {
       canvas: HTMLElement;
       /** Nearest content point along a WORLD ray, or null. For splats return the expected depth along the ray. */
       hitTest: (origin: number[], direction: number[]) => number[] | null;
-      /** Sprite height as a fraction of the canvas height (default 0.03). */
+      /** Sprite height as a fraction of the canvas height (default: the OS arrow's 19 CSS px of the canvas, re-read each frame). */
       height?: number;
-      /** Fill colour of the crosshair (default 0xffd61a; the outline is always dark). */
+      /** Fill colour of the arrow (default 0xffffff; the outline is always dark). */
       color?: number;
-      /** How far in front of the content it floats, in eye-baseline units (default 0.005 ≈ 1.5 mm at 60 cm). */
+      /** How far in front of out-of-screen content it floats, in eye-baseline units (default 0.03 ≈ 2 mm at a 65 mm IPD). */
       margin?: number;
       /** Default `'hybrid'`: exact while the pointer moves, world-fixed (parallaxing) while it is still. */
       anchor?: CursorAnchorMode;
@@ -188,7 +191,7 @@ export class DepthCursor {
       viewSpace?: unknown;
     },
   );
-  /** The crosshair (a `THREE.Mesh` of filled, outlined strokes; depth test off, drawn last). Add it to the scene root. */
+  /** The arrow (a `THREE.Mesh`: dark outline, white fill, tip at its origin; depth test off, drawn last). Add it to the scene root. */
   readonly object: unknown;
   /** The last placement, for diagnostics. */
   readonly placement: CursorPlacement | { active: false };