@displayxr/inline3d 1.45.0 → 1.46.0

package/CHANGELOG.md

@@ -5,6 +5,53 @@ 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.46.0 — 2026-10-14
+
+### Depth cursor: when the runtime draws the web cursor, hand it the depth (runtime ADR-046 Amendment 4)
+
+Touches `./cursor-depth`, `./three` (`DepthCursor`), the core tile handle, and the preview tier
+(`./model`, `./splat`, `./call`, `./camera`), all only under `cursor: 'depth'`.
+
+- In a DisplayXR Browser whose runtime draws the web cursor (`XRDisplayLayer.getCursorDepthSupport()`
+  → `"runtime"`: Windows, `XR_DXR_cursor_depth` spec ≥ 8), the depth cursor draws **no sprite** and
+  never hides the CSS cursor. Each frame it calls `layer.setCursorDepth({ disparityPx, u, v })` with
+  the **raw** content disparity under the footprint in **device px between the outermost views**
+  (< 0 = in front; no margin, clamp or filter: the runtime applies the one policy), `{ u, v }` with no
+  `disparityPx` over the element with nothing 3D under it, and `setCursorDepth()` once to withdraw
+  (pointer off the element, 2D, teardown). The runtime draws the browser's own cursor (`grab`,
+  `pointer`, `url(…)`), lifted, softened and late-latched.
+- `"none"`, an older browser, or any other browser: unchanged — the SDK sprite, its softening and
+  CSS-shape mirroring, exactly as before. The browser answers `"none"` until its weave session is
+  live, so a `"none"` is re-asked (below).
+- The support probe: a `"none"` is re-asked every 2 s for the first 6 asks, then every 10 s with no
+  cap (`CURSOR_RUNTIME_SLOW_RETRY_MS`), so a weave session that reports late (tens of seconds on a
+  cold GPU) still hands the cursor to the runtime. A browser without the API is never probed.
+- Covered: `DepthCursor` (pass `update(views, { layer })`; `./model`/`./splat` on three do it),
+  the PlayCanvas cursor (`./model`, `./splat`), and the stereo-pair cursor (`./call`, `./camera`,
+  through the tile handle; its matched output-px disparity → device px).
+- New: `CursorRuntimeLink`, `cursorRuntimeCapable`, `cursorDisparityPx`, `CURSOR_RUNTIME_RETRY_MS`,
+  `CURSOR_RUNTIME_PROBES`, `CURSOR_RUNTIME_SLOW_RETRY_MS` (`./cursor-depth`); `CursorPlacement.contentDisparity` /
+  `contentDisparityPx` / `runtime`; tile handle `setCursorDepth()` / `getCursorDepthSupport()`;
+  `XRDisplayLayer.setCursorDepth?` / `getCursorDepthSupport?` and `XRCursorDepthInit` in the types.
+  `DepthCursor.update`'s second argument may now be `{ nowMs, layer }` (a number still works).
+- Needs DisplayXR Browser with page API patch 0409 (browser-pvt #285) and runtime spec 8 (runtime
+  #2088); safe to ship earlier, since it only activates on `"runtime"`.
+
+
+## 1.45.1 — 2026-10-13
+
+### Fixed — `cursor: 'depth'` showed up under a finger (touch)
+
+- On a touch device, dragging a finger over a scene drew the 3D cursor, though the browser shows no
+  cursor there. Since 1.44.0 the pointer took every `pointermove` / `pointerrawupdate` whatever
+  its `pointerType`. Now only a **mouse** or a **hovering pen** places the cursor. A touch or a pen
+  in contact clears it, including a tap that never moves (so no stale mouse hover stays up), and
+  the CSS cursor is never hidden for them. This covers every backend (three.js `./model`,
+  PlayCanvas `./model` / `./splat`, the `./call` / `./camera` pair cursor). They all share
+  `CursorPointer`.
+- New `cursorPointerHovers(e)` in `./cursor-depth`. An event with no `pointerType` (synthetic)
+  counts as a mouse, as before.
+
 ## 1.45.0 — 2026-10-13
 
 ### Packaging

package/cursor-depth.d.ts

@@ -146,6 +146,47 @@ export interface CursorPlacement {
   targetDisparity: number;
   /** Hybrid: true while the pointer is still and the sprite is held world-fixed. */
   anchored?: boolean;
+  /** The RAW content disparity under the footprint (baselines, < 0 in front), before the policy; null = nothing under it. */
+  contentDisparity?: number | null;
+  /** `contentDisparity` in device px between the outermost views (what `setCursorDepth` takes); null when unknown. */
+  contentDisparityPx?: number | null;
+  /** True when the runtime drew the cursor this frame (ADR-046 Amendment 4): `active` is then false — the SDK drew nothing. */
+  runtime?: boolean;
+}
+
+// ── The runtime draws the web cursor (runtime ADR-046 Amendment 4) ───────────────────────────
+
+/** Re-ask a target that answered "none" at most this often (ms) while the cursor runs. */
+export const CURSOR_RUNTIME_RETRY_MS: number;
+/** At most this many support probes per target. */
+export const CURSOR_RUNTIME_PROBES: number;
+/** After the fast probes, a "none" is re-asked this often, without a cap (a late weave session). */
+export const CURSOR_RUNTIME_SLOW_RETRY_MS: number;
+/** Does `target` (an XRDisplayLayer, or a tile handle) have `setCursorDepth` + `getCursorDepthSupport`? */
+export function cursorRuntimeCapable(target: unknown): boolean;
+/** Baseline-unit content disparity → device px between the outermost views (`d × pxPerBaseline`); null when either is unknown. */
+export function cursorDisparityPx(contentDisparity: number | null | undefined, pxPerBaseline: number | null | undefined): number | null;
+/** Anything a depth can be handed to: an XRDisplayLayer, or a tile handle that forwards to one. */
+export interface CursorDepthTarget {
+  setCursorDepth(depth?: { disparityPx?: number | null; u: number; v: number } | null): unknown;
+  getCursorDepthSupport(): Promise<string>;
+}
+/**
+ * The page half of a runtime-drawn cursor, used by every backend: per frame `bind(target)` (true =
+ * the runtime draws: draw no sprite, leave the CSS cursor alone), then `report(u, v, disparityPx)`
+ * while the pointer is over the element, `withdraw()` when not.
+ */
+export class CursorRuntimeLink {
+  constructor();
+  readonly target: CursorDepthTarget | null;
+  /** The last depth sent (diagnostics), null after a withdrawal. */
+  readonly last: { u: number; v: number; disparityPx: number | null } | null;
+  readonly support: 'runtime' | 'none' | 'pending';
+  readonly drawing: boolean;
+  bind(target: CursorDepthTarget | null | undefined): boolean;
+  report(u: number, v: number, disparityPx: number | null): boolean;
+  withdraw(): void;
+  dispose(): void;
 }
 
 /** The whole pipeline with its filter state: one per cursor. Inactive with fewer than two views. */