@displayxr/inline3d 1.35.0 → 1.36.0

package/js/inline3d-viewer.js

@@ -737,6 +737,11 @@ export class SceneViewer {
     this._cacheGood(views, vps, !eye);
     const g = this._lastGood;
     if (eye) (this.viewerEase ||= viewerEaseFor(frame, this._viewerEaseOpt)).apply(g.entries, frameTrackingState(frame));
+    // cursor: 'depth' (ADR-046) — only when a page opted in; null otherwise.
+    if (this.cursorDepth) {
+      this.scene.updateMatrixWorld(); // the hit test reads THIS frame's subject pose
+      this.cursorDepth.update(g.entries.map((e) => ({ projectionMatrix: e.proj, transformMatrix: e.pose })));
+    }
     const r = this.renderer;
     // getViewport() splits canvas.width; a drawing buffer the browser clamped behind our back
     // (bufferScale().mismatch) gets the same split mapped onto its real size, never canvas.width/2.
@@ -771,6 +776,22 @@ export class SceneViewer {
     return this;
   }
 
+  /**
+   * `cursor: 'depth'` (ADR-046): a cursor that rises to the subject under it instead of being
+   * drawn on the glass behind content that pops out. Called by ./model and ./splat on opt-in
+   * only — without it nothing is built and every hook below is skipped. Injected, like
+   * useEyeCamera, so this module never imports three.js itself.
+   * @param {Function} DepthCursorClass  ./three's DepthCursor.
+   * @param {(content: object) => Function} hitTestFor  builds the hit test over the subject group.
+   * @param {object} [opts]  extra DepthCursor options (./splat passes `raysPerFrame`).
+   */
+  useDepthCursor(DepthCursorClass, hitTestFor, opts = {}) {
+    if (this.cursorDepth) return this;
+    this.cursorDepth = new DepthCursorClass(this._THREE, { ...opts, canvas: this.canvas, hitTest: hitTestFor(this.content) });
+    this.scene.add(this.cursorDepth.object);
+    return this;
+  }
+
   /** Drive a flat, single-camera render loop for browsers without inline-3D. */
   startMono() {
     if (this._monoRaf || this._disposed) return;
@@ -780,6 +801,7 @@ export class SceneViewer {
       if (this._disposed) return;
       this._monoRaf = requestAnimationFrame(loop);
       this._tick();
+      this.cursorDepth?.update(null); // 2D: no sprite, the normal cursor
       const r = this.renderer;
       r.clear();
       const b = this._bufScale();
@@ -809,6 +831,8 @@ export class SceneViewer {
     if (this._ro) this._ro.disconnect();
     else removeEventListener('resize', this._onResize);
     this._unbindOrbit();
+    this.cursorDepth?.dispose();
+    this.cursorDepth = null;
     this.renderer.dispose();
   }
 

package/model.d.ts

@@ -48,6 +48,16 @@ export interface ModelOptions {
    * `createInline3D({ viewerEase })`, else on. `false` restores the snap.
    */
   viewerEase?: ViewerEaseOption;
+  /**
+   * `'depth'`: a cursor that rises to the subject under it instead of being drawn on the glass,
+   * behind content that pops out (ADR-046, same maths as native `XR_DXR_cursor_depth`). A
+   * crosshair just in front of the nearest content under the pointer's footprint; the CSS cursor
+   * is hidden while it shows and comes back in 2D and off the canvas. OPT-IN: without it nothing
+   * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,
+   * one low-res pass every other frame while the pointer is over the tile). three: a raycast
+   * against the subject.
+   */
+  cursor?: 'depth';
   /**
    * How the mesh is lit.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -15,6 +15,10 @@
       "types": "./three.d.ts",
       "import": "./js/inline3d-three.js"
     },
+    "./cursor-depth": {
+      "types": "./cursor-depth.d.ts",
+      "import": "./js/inline3d-cursor-depth.js"
+    },
     "./viewer": {
       "types": "./viewer.d.ts",
       "import": "./js/inline3d-viewer.js"
@@ -70,6 +74,8 @@
     "js/inline3d-buffer-limit.js",
     "js/inline3d-viewer-ease.js",
     "js/inline3d-three.js",
+    "js/inline3d-cursor-depth.js",
+    "js/inline3d-cursor-depth-playcanvas.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
     "js/inline3d-splat-pc-entry.js",
@@ -100,6 +106,7 @@
     "dist/",
     "index.d.ts",
     "three.d.ts",
+    "cursor-depth.d.ts",
     "viewer.d.ts",
     "splat.d.ts",
     "splat-playcanvas.d.ts",
@@ -167,6 +174,7 @@
     "prepack": "node tools/dist/build.mjs",
     "test:e2e": "node test/e2e/call-element.e2e.mjs",
     "test:e2e:camera": "node test/e2e/camera.e2e.mjs",
+    "test:e2e:cursor": "node test/e2e/cursor-depth.e2e.mjs",
     "api:check": "node tools/api-surface.mjs --check",
     "api:update": "node tools/api-surface.mjs --update",
     "check:snippets": "node tools/check-snippets.mjs",

package/splat.d.ts

@@ -472,6 +472,16 @@ export interface SplatOptions {
    * `createInline3D({ viewerEase })`, else on. `false` restores the snap.
    */
   viewerEase?: ViewerEaseOption;
+  /**
+   * `'depth'`: a cursor that rises to the subject under it instead of being drawn on the glass,
+   * behind content that pops out (ADR-046, same maths as native `XR_DXR_cursor_depth`). A
+   * crosshair just in front of the nearest content under the pointer's footprint; the CSS cursor
+   * is hidden while it shows and comes back in 2D and off the canvas. OPT-IN: without it nothing
+   * is loaded or run. PlayCanvas: hit-tested with the engine's depth picker (meshes and splats,
+   * one low-res pass every other frame while the pointer is over the tile). three: a raycast
+   * against the subject.
+   */
+  cursor?: 'depth';
   /** Camera rig only: the distance in world metres that sits ON the glass. */
   convergence?: number;
   /**

package/three.d.ts

@@ -142,3 +142,52 @@ export class EdgeFeather {
     vp: { x: number; y: number; width: number; height: number },
   ): void;
 }
+
+import type { CursorPlacement, CursorView } from './cursor-depth.js';
+
+/**
+ * A hit test for {@link DepthCursor} that raycasts three.js objects (recursively): the first hit
+ * along the ray as a world point, or null.
+ */
+export function raycastHitTest(
+  THREE: unknown,
+  targets: unknown[],
+): (origin: number[], direction: number[]) => number[] | null;
+
+/**
+ * A cursor that rises to the depth of the content under it, so it is never drawn behind something
+ * that pops out of the glass. Same maths and defaults as the runtime's XR_DXR_cursor_depth
+ * (ADR-046). Tracks the pointer over `canvas`, hit-tests the cursor FOOTPRINT, places a crosshair
+ * (`object`, add it to your scene) and hides the CSS cursor exactly while the crosshair replaces it.
+ * Opt-in: nothing runs unless you construct one and call `update(views)` each frame.
+ *
+ * Head motion leaves the crosshair's image on the glass where it is (it stays under the mouse like
+ * the OS cursor); only its depth follows the content under that line of sight.
+ */
+export class DepthCursor {
+  constructor(
+    THREE: unknown,
+    opts: {
+      /** The woven canvas; the pointer is tracked over it. */
+      canvas: HTMLElement;
+      /** Nearest content point along a WORLD ray, or null. For splats return the expected depth along the ray. */
+      hitTest: (origin: number[], direction: number[]) => number[] | null;
+      /** Sprite height as a fraction of the canvas height (default 0.03). */
+      height?: number;
+      /** Crosshair colour (default 0xffd419). */
+      color?: number;
+      /** Attach pattern: the Object3D the eye cameras hang off; its world matrix carries the views to world. */
+      viewSpace?: unknown;
+    },
+  );
+  /** The crosshair (a `THREE.LineSegments`, depth test off, drawn last). Add it to the scene root. */
+  readonly object: unknown;
+  /** The last placement, for diagnostics. */
+  readonly placement: CursorPlacement | { active: false };
+  /** Place the sprite for this frame — call with the views you are about to render, before rendering. */
+  update(views: ArrayLike<XRView | CursorView>, nowMs?: number): CursorPlacement | { active: false };
+  /** Set the pointer directly (canvas-normalised, v down), or null — for scripted input. */
+  setPointer(u: number | null, v?: number): void;
+  /** Remove listeners, restore the CSS cursor, free the sprite's GPU resources. */
+  dispose(): void;
+}