@displayxr/inline3d 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.40.0 — 2026-10-10
+
+Touches the **preview tier** (`./call`, `./camera`) only: one new option, off by default. New type
+`PairCursorOptions`; nothing removed, no default changes.
+
+### `./call` + `./camera` — a depth cursor on stereo tiles (`cursor: 'depth'`)
+
+- The scene cursor of 1.36.0 (runtime ADR-046) comes to the call and the camera view. Over a 3D
+  tile — a stereo peer, or your own stereo self view — a crosshair just in front of the person
+  under the pointer replaces the CSS cursor. Before, the flat cursor sat on the glass, drawn over a
+  face whose disparity says it is in front: the depth violation ADR-046 is about.
+- A pair has no scene and no depth buffer, so the depth is **measured**: the cursor's footprint is
+  block-matched between the two halves of the tile's own frames (the same matcher auto-convergence
+  uses), the nearest confident match wins, and the crosshair is drawn into both halves with that
+  disparity plus a small margin. Nothing matched → the display plane. Same fast-rise / slow-sink
+  filter as the scene cursor. A mirrored self view flips the pointer, never the disparity.
+- Zero cost when off: the option is validated at the call, and the cursor module is a dynamic
+  import made only on opt-in. When on, it costs nothing until the pointer is over a woven tile,
+  then a ~15 Hz grayscale copy of that tile's source (it shares the auto-convergence copy) and a
+  9-block match when the pointer or the copy changes.
+- `addCall(…, { cursor: 'depth' })`, `<dxr-call cursor="depth">`, `addCameraView(…, { cursor:
+  'depth' })`; `{ height, pointerScope }` tune it (`margin` / `anchor` are scene-only and refused).
+  Lifted (2D→3D) and flat tiles keep the normal cursor. `diagnostics().peers[i].cursor` reads the
+  last placement. The `call`, `call-embed` and `camera` samples turn it on (`?cursor=0` turns it off).
+
 ## 1.39.0 — 2026-10-09
 
 Core (`.`) changes are **additive**, with every existing default unchanged: `firstWoven` and

package/call.d.ts

@@ -17,7 +17,7 @@
 // until the snapshot is updated in the same change (`node tools/api-surface.mjs --update`).
 
 import type { Inline3D, Inline3DUnsupported } from './index.js';
-import type { StereoCamera } from './camera.js';
+import type { StereoCamera, PairCursorOptions } from './camera.js';
 
 /** What a participant sends: a side-by-side pair (left eye left) or one flat picture. */
 export type CallFormat = 'sbs' | 'mono';
@@ -215,6 +215,14 @@ export interface CallOptions {
    * at the display plane. No calibration needed. The depth slider stays an offset on top.
    */
   autoConverge?: boolean;
+  /**
+   * `'depth'`: over a 3D (stereo) tile — a peer's or your self view — a crosshair just in front of
+   * the person under the pointer replaces the CSS cursor, instead of the flat cursor drawn on the
+   * glass behind them (runtime ADR-046; the depth is measured off each tile's two halves). Lifted
+   * (2D→3D) and flat tiles keep the normal cursor. Off by default (zero cost).
+   * `<dxr-call cursor="depth">`.
+   */
+  cursor?: 'depth' | PairCursorOptions;
   /** Participants INCLUDING you. Default 4, clamped to 2..4 (full mesh). */
   maxPeers?: number;
   /**

package/camera.d.ts

@@ -184,6 +184,17 @@ export function openCamera(opts?: CameraOptions | CameraPreference): Promise<Ste
 /** Is `x` a {@link StereoCamera}? Duck-typed, so two copies of the SDK interoperate. */
 export function isStereoCamera(x: unknown): x is StereoCamera;
 
+/**
+ * `cursor: { … }` on a stereo pair (an object also means `'depth'`). A pair has no scene: the
+ * depth under the pointer is MEASURED off its two halves, so there is no anchor mode or margin.
+ */
+export interface PairCursorOptions {
+  /** Sprite height as a fraction of the tile height (default 0.06). */
+  height?: number;
+  /** `'window'` (default): the cursor stays while the pointer is over DOM on the tile (a badge). `'canvas'`: only over the canvas itself. */
+  pointerScope?: 'canvas' | 'window';
+}
+
 export interface CameraViewOptions {
   /** Selfie mirroring, done right for a pair (each half mirrored AND swapped). Default true. */
   mirror?: boolean;
@@ -193,6 +204,12 @@ export interface CameraViewOptions {
   depth?: number;
   /** The tile's aspect (w/h) = the woven buffer's per-eye aspect. Default 16/9. */
   aspect?: number;
+  /**
+   * `'depth'`: while the pointer is over the woven view, a crosshair just in front of whatever is
+   * under it (runtime ADR-046, measured off the pair's two halves) replaces the CSS cursor, so it
+   * is never drawn on the glass behind a face that sits in front of it. Off by default (zero cost).
+   */
+  cursor?: 'depth' | PairCursorOptions;
   /**
    * Called when the view's route changes — including when the wall says the tile will not weave
    * and the view drops to its flat left eye by itself — and when its `firstWoven` settles. Keep a