@displayxr/inline3d 1.39.0 → 1.40.1

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.1 — 2026-10-11
+
+Touches the **preview tier** (`./call`, `./camera`) only: how `cursor: 'depth'` looks and moves. No
+API change.
+
+### Stereo-tile depth cursor: the normal arrow, and only ever in front of the screen
+
+- **It never goes inside the display.** 1.40.0 put the cursor at the depth of whatever was under
+  it, so over a background behind the glass it sank behind the glass too. Now the depth only moves
+  to keep content that comes OUT of the screen from overlapping it; over anything on or behind the
+  glass it stays on the screen plane.
+- **It is the normal arrow, not a crosshair.** On the plane nothing is drawn: it is the OS cursor,
+  untouched. Only while the person under it pops out is the arrow drawn into both halves, just in
+  front of them, at the OS arrow's size (19 CSS px; `height` still overrides it), with the OS
+  cursor hidden exactly then. The footprint now covers the arrow's body, not a ring round its tip.
+- Same filter as before: it comes forward fast and hands back to the OS arrow smoothly as the
+  content sinks. Matches the native lifted-content cursor (runtime #1908).
+
+## 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,15 @@ 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 — the cursor is never
+   * overlapped by what comes out of the screen: where the person under the pointer pops out, the
+   * normal arrow is drawn just in front of them (runtime ADR-046; the depth is measured off each
+   * tile's two halves). Everywhere else it is the plain OS arrow on the screen plane — it never goes
+   * inside the display. 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 {
+  /** Arrow height as a fraction of the tile height (default: the OS arrow's size, 19 CSS px). */
+  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,13 @@ 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 and what is under it comes out of the
+   * screen, the normal arrow is drawn just in front of it (runtime ADR-046, measured off the pair's
+   * two halves), so it is never drawn on the glass behind a face that pops out. Otherwise it is the
+   * plain OS arrow on the screen plane; it never goes inside the display. 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