@displayxr/inline3d 1.34.0 → 1.36.0

package/CHANGELOG.md

@@ -5,6 +5,63 @@ 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.36.0 — 2026-10-07
+
+Additive everywhere it touches: the **core** `./three` (new helpers, minor per
+`docs/sdk-stability.md`), the **preview-tier** `./model` and `./splat` (one new option,
+`cursor: 'depth'`), and a new dependency-free subpath `./cursor-depth`. Nothing existing changes;
+nothing runs unless a page asks for it (`cursor: 'depth'`, or constructs a `DepthCursor`).
+
+### Depth-aware cursor — `DepthCursor` (`./three`) + `./cursor-depth`
+
+- **The cursor rises to the content it hovers.** The CSS cursor is drawn on the glass (zero
+  disparity), so over content that pops out it sits *behind* what it covers: a depth violation.
+  `new DepthCursor(THREE, { canvas, hitTest: raycastHitTest(THREE, [model]) })` tracks the pointer,
+  hit-tests the cursor footprint against your content, and places a crosshair just in front of the
+  nearest hit (add `cursor.object` to the scene; call `cursor.update(views)` each frame before
+  rendering). It hides the CSS cursor exactly while the crosshair replaces it, and gives it back in
+  2D and off the canvas.
+- **Same maths as native apps.** `./cursor-depth` is a line-for-line port of the runtime's
+  `u_cursor_depth` (displayxr-runtime ADR-046, `XR_DXR_cursor_depth`): the same geometry
+  (solved from the views alone, so display and camera rigs, scale and head tracking just work),
+  the same defaults (margin, comfort clamp, fast rise / slow sink), and the same test numbers.
+- **Head motion leaves it put.** The crosshair stays under the mouse on the glass while you look
+  around; only its depth follows the content under that line of sight.
+- **`./model` and `./splat`: `cursor: 'depth'`** (preview tier, additive). This is one option on
+  both engines:
+  - **PlayCanvas:** hit-tests with the engine's own depth picker. One low-res pass covers meshes
+    and splats; it runs every other frame, only while the pointer is over the tile.
+  - **three / Spark:** raycasts the subject. On Spark that is about 8 ms a ray, so it's amortised
+    to one ray a frame; PlayCanvas is the cheaper engine for splats with the cursor.
+  - **No option, no cost:** nothing is built, and on PlayCanvas the cursor module isn't even
+    downloaded.
+  - **Samples:** `samples/model/?cursor=depth`, `samples/splat/?cursor=depth`.
+- `DepthCursor` option `raysPerFrame`, for an expensive hit test.
+- **e2e:** `npm run test:e2e:cursor` drives the real viewers (both engines, model and splat) with
+  two off-axis views and checks the crosshair sits at *content − margin* over the subject and on
+  the glass off it.
+
+## 1.35.0 — 2026-10-06
+
+Touches the **preview tier** (`./camera`, `./call`) additively. The core is unchanged (one new
+unit test pins its existing behaviour).
+
+### `./call` + `./camera` — the self view never shows a squeezed pair (web#131)
+
+- **The self view follows its tile's `firstWoven`.** Seen once in the DisplayXR Browser: a
+  call's self view showed the whole packed L|R pair in each eye under a `You · 3D` badge, the
+  look of a canvas the browser is not weaving. `addCameraView` now watches `handle.firstWoven`
+  the way a remote tile does: on `woven: false` (`'layer-failed'`, `'session-ended'`) the view
+  drops to `'flat-left'` (one eye, mirrored), re-registers a refused layer up to 4 times with
+  backoff, and re-weaves on `_reroute(true, wall)` when a wall comes back.
+- **The self badge is honest**: `3D` only while the view is on the woven route.
+- **`CameraView` additions**: `fallbackReason`, `weaveState()` and the `onRouteChange` option
+  (types: `CameraViewWeaveState` in `camera.d.ts`).
+- **`call.diagnostics().self`** = `{ route, woven, reason, firstWoven, layerRetries }`, so the
+  next occurrence can be diagnosed from devtools.
+- Hardening, not a root-cause fix: `firstWoven` is the SDK's hold timer, so a layer the browser
+  silently never joins still reads as woven.
+
 ## 1.34.0 — 2026-10-06
 
 ### `./model` — the PlayCanvas drag is a turntable again

package/camera.d.ts

@@ -193,6 +193,24 @@ export interface CameraViewOptions {
   depth?: number;
   /** The tile's aspect (w/h) = the woven buffer's per-eye aspect. Default 16/9. */
   aspect?: number;
+  /**
+   * 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
+   * "3D" badge on `view.woven`, not on the wall.
+   */
+  onRouteChange?: (route: CameraView['route'], state: CameraViewWeaveState) => void;
+}
+
+/** What a {@link CameraView} actually shows (`view.weaveState()`), for diagnostics. */
+export interface CameraViewWeaveState {
+  route: 'woven-sbs' | 'flat-left' | 'flat' | null;
+  woven: boolean;
+  /** Why a pair on a 3D wall is flat: the tile's `firstWoven` reason (`'layer-failed'`, `'session-ended'`), else null. */
+  reason: string | null;
+  /** The current registration's settled `firstWoven`, `'pending'`, or null off the woven route. */
+  firstWoven: { woven: boolean; confirmed: boolean; reason: string | null; ms: number } | 'pending' | null;
+  /** Layer re-registrations attempted after a `'layer-failed'` (bounded; reset by a woven result). */
+  layerRetries: number;
 }
 
 /** A self view from {@link addCameraView}. */
@@ -200,7 +218,12 @@ export interface CameraView {
   readonly canvas: HTMLCanvasElement;
   /** `'woven-sbs'`: 3D on the panel; `'flat-left'`: a pair shown as its left eye; `'flat'`: mono. */
   readonly route: 'woven-sbs' | 'flat-left' | 'flat' | null;
+  /** On the woven route. A tile the wall will not weave drops the view flat, so this goes false with it. */
   readonly woven: boolean;
+  /** Why a pair on a 3D wall is shown flat (`'layer-failed'`, `'session-ended'`), else null. */
+  readonly fallbackReason: string | null;
+  /** What the view actually shows, for diagnostics. */
+  weaveState(): CameraViewWeaveState;
   /** The wall's tile handle while woven (its `firstWoven` settles when the tile is safe to reveal), else null. */
   readonly handle: TileHandle | null;
   readonly mirror: boolean;

package/cursor-depth.d.ts

@@ -0,0 +1,76 @@
+// 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.
+
+/** A view as an XRView carries it: column-major projection + transform matrices. */
+export interface CursorView {
+  projectionMatrix: ArrayLike<number>;
+  transformMatrix: ArrayLike<number>;
+}
+
+/** Placement policy. Disparities in eye-baseline units (0 = on the glass, < 0 = in front); times in seconds. */
+export interface CursorTuning {
+  margin: number;
+  minDisparity: number;
+  maxDisparity: number;
+  riseTau: number;
+  sinkTau: number;
+  stale: number;
+}
+
+/** The runtime's defaults: margin 0.03, clamp ±0.6, 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). */
+export const CURSOR_DEFAULT_HEIGHT: number;
+
+/** The cursor's line of sight for one frame. */
+export interface CursorGeometry {
+  eye: number[];
+  canvasPoint: number[];
+  forward: number[];
+  eyeToCanvas: number;
+  canvasHeight: number;
+  /** The display plane's unit axes: draw the sprite in its X/Y plane, facing +Z. */
+  basis: { x: number[]; y: number[]; z: number[] };
+}
+
+/** The ray from a view through canvas point (u, v) (`[0,1]²`, origin top-left, v down). */
+export function cursorViewRay(view: CursorView, u: number, v: number): { origin: number[]; direction: number[] };
+/** Solve the line of sight from two views (the outermost pair); null when degenerate (2D, off-canvas). */
+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. */
+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;
+/** Where to draw a sprite at `disparity`, and how tall. */
+export function placeCursor(g: CursorGeometry, disparity: number, heightFraction: number): { position: number[]; height: number };
+
+/** One frame's placement. `position`/`basis` are in the views' space; null when inactive. */
+export interface CursorPlacement {
+  active: boolean;
+  position: number[] | null;
+  basis: { x: number[]; y: number[]; z: number[] } | null;
+  height: number;
+  disparity: number;
+  targetDisparity: number;
+}
+
+/** The whole pipeline with its filter state: one per cursor. Inactive with fewer than two views. */
+export class CursorDepthPlacer {
+  constructor(tuning?: CursorTuning);
+  update(
+    views: ArrayLike<CursorView | XRView>,
+    hint: {
+      /** Canvas-normalised pointer, v down. */
+      u: number;
+      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). */
+      cursorHeight?: number;
+    },
+    nowSec: number,
+  ): CursorPlacement;
+}