@displayxr/inline3d 1.40.2 → 1.42.0

package/CHANGELOG.md

@@ -5,6 +5,67 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.42.0 — 2026-10-11
+
+Touches the **core** `./three` (`DepthCursor`) and the **preview tier** (`./model`, `./splat`,
+`./call`, `./camera`: `cursor: 'depth'`), plus `./cursor-depth` (`CURSOR_DEFAULT_TUNING`). **One
+deliberate default change.**
+
+- **Depth-cursor margin 0.03 → 0.015 eye baselines (default change),** about 1 mm of crossed
+  on-screen disparity at a 63–65 mm IPD instead of about 2 mm. Runtime ADR-046 Amendment 2 A.2 was
+  halved after a Windows panel check, because 0.03 floated visibly off the content. The runtime
+  makes the same change (`U_CURSOR_DEPTH_DEFAULT_MARGIN`), so web and native cursors still agree.
+  Every depth cursor takes the default from `CURSOR_DEFAULT_TUNING`: `DepthCursor`,
+  `cursor: 'depth'` on both engines, and the stereo-tile pair cursor. `margin` still overrides it:
+  pass `margin: 0.03` for the 1.41.0 look.
+
+## 1.41.0 — 2026-10-11
+
+Touches the **core** `./three` (`DepthCursor`'s look and two defaults) and the **preview tier**
+(`./model`, `./splat`, `./call`, `./camera`: `cursor: 'depth'`), plus `./cursor-depth` (additive
+exports, one deprecation). **Two deliberate default changes**, per runtime ADR-046 Amendment 2
+("one cursor policy everywhere"): pages that use a depth cursor will see it sit further forward and
+stop going behind the glass.
+
+### Depth cursor: one policy everywhere, and the arrow
+
+- **Never behind the glass (default change).** The target is now `d < 0 ? max(d − margin, −0.6) : 0`:
+  the cursor only comes forward, to stay ahead of content that comes out of the screen. Over content
+  on or behind the glass it stays on the glass. The clamp is `[−0.6, 0]` (was `[−0.6, +0.6]`), and
+  `cursorTarget` never returns more than 0 whatever a tuning's `maxDisparity` says.
+- **Margin 0.005 → 0.03 eye baselines (default change),** about 2 mm of on-screen disparity at a
+  65 mm IPD: the value native apps and the runtime use. `margin` still overrides it.
+- **On the plane it is the OS cursor.** Nothing is drawn unless the filtered disparity is at or past
+  −0.005 baselines (about 0.3 mm) and at least 0.5 panel px. Off the subject the sprite is now
+  **hidden**, not drawn at zero disparity, and the CSS cursor the page set is left alone (a cursor
+  the page changes while the sprite hides it is no longer overwritten on restore).
+- **The arrow replaces the crosshair.** Every depth cursor (three, PlayCanvas, and the stereo-tile
+  cursor on `./call` / `./camera`) draws the same classic arrow: 12 × 19 px proportions, white with a
+  dark outline, its **tip** on the hotspot. Its default size is the OS cursor's, 19 CSS px of the
+  canvas, recomputed as the canvas resizes; `height` still overrides. `DepthCursor`'s `color`
+  default is now white. Mirroring a page's CSS cursor (`grab`, `url(…)`) into the sprite is future
+  work (ADR-046 Amendment 2 §C).
+- **The stereo-tile cursor runs on the shared core.** `./call` / `./camera` take the target, margin,
+  threshold, filter and arrow from `./cursor-depth` instead of their own copies. Tile pixels convert
+  to eye baselines through the tile's `displayMetrics()` (the panel's pixel pitch, × the eye
+  separation; the CSS reference px until it answers).
+  - This subsumes 1.40.2's change (#164), which already moved the stereo
+    tile's margin from ~1–2 buffer px to **2 mm** of on-screen disparity (0.3 mm hand-back),
+    converted through `displayMetrics()`. That conversion is kept. The margin and threshold are now
+    the core's 0.03 / 0.005 **eye baselines** (≈1.9 mm / 0.3 mm at the default 63 mm eye
+    separation) rather than fixed millimetres, so stereo tiles, lifted tiles (runtime #1908) and
+    scenes share one rule.
+  - The comfort cap is now the core's −0.6 baselines (it was 8 % of the eye width).
+  - The pair cursor's own constants (`PAIR_CURSOR_MARGIN_M`, `PAIR_CURSOR_SHOW_M`,
+    `PAIR_CURSOR_SHOW_MIN_PX`, `PAIR_CURSOR_CLAMP`; an internal module, not public API) are gone.
+- **`./cursor-depth`, additive:** `cursorShouldDraw`, `CURSOR_DRAW_THRESHOLD`, `CURSOR_DRAW_MIN_PX`,
+  `cursorDefaultHeight`, `CURSOR_ARROW_CSS_PX`, `CURSOR_ARROW`, `CURSOR_ARROW_FILL`,
+  `cursorArrowInset`, `cursorArrowMesh`, `cursorArrowFootprint`, `cursorFootprint` (typed now),
+  `CURSOR_FILL_COLOR` / `CURSOR_OUTLINE_COLOR`. `CursorPlacement` gains `solved` and
+  `pxPerBaseline`, and `active` now means "drawn". `CursorDepthPlacer.update` takes an optional
+  `canvasPx` for the pixel floor. **Deprecated:** `cursorCrosshairMesh` (unused by the SDK; removed
+  in 2.0).
+
 ## 1.40.2 — 2026-10-11
 
 Touches the **preview tier** (`./call`, `./camera`) only; no API change.

package/cursor-depth.d.ts

@@ -1,6 +1,11 @@
 // Type definitions for @displayxr/inline3d/cursor-depth — the depth-aware cursor's placement
 // maths, dependency-free. A port of the runtime's u_cursor_depth (ADR-046, XR_DXR_cursor_depth):
 // same geometry, same defaults, same numbers. For three.js, ./three's `DepthCursor` wires it up.
+//
+// The policy (ADR-046 Amendment 2), the same for every DisplayXR depth cursor: never behind the
+// glass (`cursorTarget`), margin 0.015 eye baselines, drawn only past the draw threshold
+// (`cursorShouldDraw`; otherwise the OS cursor is the cursor), the classic arrow at the OS cursor's
+// size (`CURSOR_ARROW`, `cursorArrowMesh`, `cursorDefaultHeight`).
 
 /** A view as an XRView carries it: column-major projection + transform matrices. */
 export interface CursorView {
@@ -12,16 +17,27 @@ export interface CursorView {
 export interface CursorTuning {
   margin: number;
   minDisparity: number;
+  /** Never above 0 in effect: `cursorTarget` never puts the cursor behind the glass, whatever this says. */
   maxDisparity: number;
   riseTau: number;
   sinkTau: number;
   stale: number;
 }
 
-/** The runtime's defaults: margin 0.005 (~1.5 mm at 60 cm), clamp ±0.6, rise 30 ms, sink 250 ms, stale 0.5 s. */
+/** The defaults: margin 0.015 (~1 mm at a 63–65 mm IPD), clamp [−0.6, 0], rise 30 ms, sink 250 ms, stale 0.5 s. */
 export const CURSOR_DEFAULT_TUNING: Readonly<CursorTuning>;
-/** Default sprite height, as a fraction of the canvas height (0.03). */
+/** Fallback sprite height, as a fraction of the canvas height (0.03), when the canvas's on-page size is unknown. */
 export const CURSOR_DEFAULT_HEIGHT: number;
+/** The OS arrow's height in CSS px (19): the drawn arrow's default size. */
+export const CURSOR_ARROW_CSS_PX: number;
+/** The default sprite height for a canvas `cssHeight` CSS px tall: 19 CSS px of it (capped at 0.5); the fallback when unknown. */
+export function cursorDefaultHeight(cssHeight: number): number;
+/** The draw threshold, eye-baseline units (−0.005): drawn only at or below it. */
+export const CURSOR_DRAW_THRESHOLD: number;
+/** …and only at ≥ this many panel pixels of on-screen disparity (0.5), where pixels are knowable. */
+export const CURSOR_DRAW_MIN_PX: number;
+/** Draw at this filtered disparity? `pxPerBaseline`: panel px of on-screen disparity per baseline unit, when known. */
+export function cursorShouldDraw(disparity: number, pxPerBaseline?: number | null): boolean;
 
 /** The cursor's line of sight for one frame. */
 export interface CursorGeometry {
@@ -40,7 +56,7 @@ export function cursorViewRay(view: CursorView, u: number, v: number): { origin:
 export function solveCursorGeometry(viewA: CursorView, viewB: CursorView, u: number, v: number): CursorGeometry | null;
 /** A point's disparity; null when it is not in front of the eye. */
 export function cursorPointDisparity(g: CursorGeometry, point: ArrayLike<number>): number | null;
-/** Content minus the margin, clamped; 0 when nothing is under the cursor. */
+/** The policy: `d < 0 ? max(d − margin, minDisparity) : 0` — never behind the glass; 0 with nothing under the cursor. */
 export function cursorTarget(tuning: CursorTuning, hasContent: boolean, contentDisparity: number): number;
 /** Advance a filter (`{}` to start; the first step snaps) toward `target` at `nowSec`. */
 export function cursorFilterStep(filter: object, tuning: CursorTuning, target: number, nowSec: number): number;
@@ -61,9 +77,9 @@ export const CURSOR_ANCHOR_MODES: readonly CursorAnchorMode[];
 
 /** `cursor: { … }` on ./model and ./splat (an object also means `'depth'`). */
 export interface CursorOptions {
-  /** 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). */
   height?: number;
-  /** How far in front of the content it floats, in eye-baseline units (default 0.005). */
+  /** How far in front of out-of-screen content it floats, in eye-baseline units (default 0.015). */
   margin?: number;
   /** Default `'hybrid'`. */
   anchor?: CursorAnchorMode;
@@ -74,17 +90,40 @@ export const CURSOR_OPTION_KEYS: readonly (keyof CursorOptions)[];
 /** `cursor` as ./model and ./splat accept it: null = off; throws on a bad value. */
 export function resolveCursorOption(opt: unknown, who?: string): CursorOptions | null;
 
-/** The crosshair as filled, outlined strokes in its own XY plane (unit = sprite height), non-indexed triangles. */
+/** A ring of 9 canvas-normalised points: (u, v) and 8 around it at 0.75 × height. */
+export function cursorFootprint(u: number, v: number, height: number, aspect: number): Array<[number, number]>;
+/** What the arrow covers: its tip (the hotspot) first, then a ring around its body (down-right of the tip). */
+export function cursorArrowFootprint(u: number, v: number, height: number, aspect: number): Array<[number, number]>;
+/** The classic arrow's outline polygon (12 × 19 px normalised): unit = its height, x right, y DOWN, the tip = the hotspot at (0, 0). */
+export const CURSOR_ARROW: ReadonlyArray<readonly [number, number]>;
+/** Its white fill: the outline inset by one px of 19. */
+export const CURSOR_ARROW_FILL: ReadonlyArray<readonly [number, number]>;
+/** CURSOR_ARROW (or `poly`) inset by `d`, in units of its height. */
+export function cursorArrowInset(d: number, poly?: ReadonlyArray<readonly [number, number]>): Array<[number, number]>;
+/** White, and the dark outline (RGBA, 0..1). */
+export const CURSOR_FILL_COLOR: readonly number[];
+export const CURSOR_OUTLINE_COLOR: readonly number[];
+/** The arrow as a 3D mesh in its XY plane (y UP, tip at the origin, unit = sprite height): outline then fill, non-indexed triangles. */
+export function cursorArrowMesh(
+  fill?: readonly number[],
+  outline?: readonly number[],
+): { positions: Float32Array; colors: Float32Array; count: number };
+/** @deprecated The crosshair is retired (ADR-046 Amendment 2); use `cursorArrowMesh`. Removed in 2.0. */
 export function cursorCrosshairMesh(
   fill?: readonly number[],
   outline?: readonly number[],
 ): { positions: Float32Array; colors: Float32Array; count: number };
-/** Column-major model matrix placing the unit crosshair for a placement. */
+/** Column-major model matrix placing the unit sprite (tip at its origin) for a placement. */
 export function cursorModelMatrix(placement: CursorPlacement, out?: number[]): number[];
 
-/** One frame's placement. `position`/`basis` are in the views' space; null when inactive. */
+/** One frame's placement. `position`/`basis` are in the views' space; null when not solved. */
 export interface CursorPlacement {
+  /** Draw the sprite this frame (the policy's draw threshold). False on the plane: the OS cursor is the cursor. */
   active: boolean;
+  /** The geometry solved (two views, pointer on the canvas): position/basis/height are filled even when not drawn. */
+  solved?: boolean;
+  /** Panel px of on-screen disparity per baseline unit, when `canvasPx` was given. */
+  pxPerBaseline?: number | null;
   position: number[] | null;
   basis: { x: number[]; y: number[]; z: number[] } | null;
   height: number;
@@ -105,8 +144,10 @@ export class CursorDepthPlacer {
       v: number;
       /** Nearest content point under the cursor FOOTPRINT, in the views' space; null = nothing. */
       nearestPoint: ArrayLike<number> | null;
-      /** Sprite height as a fraction of the canvas height (default 0.03). */
+      /** Sprite height as a fraction of the canvas height (default 0.03; see `cursorDefaultHeight`). */
       cursorHeight?: number;
+      /** The canvas's height in panel pixels, for the draw threshold's pixel floor. */
+      canvasPx?: number;
     },
     nowSec: number,
   ): CursorPlacement;