@displayxr/inline3d 1.44.0 → 1.45.1

package/js/inline3d-cursor-depth.js

@@ -53,7 +53,8 @@
 //    CURSOR_DRAW_THRESHOLD (-0.005, ~0.3 mm) or under CURSOR_DRAW_MIN_PX on the panel
 //    (cursorShouldDraw), and the CSS cursor is left alone;
 //  - the look: the classic arrow (CURSOR_ARROW, tip = hotspot), at the OS cursor's size
-//    (CURSOR_ARROW_CSS_PX tall on the page, cursorDefaultHeight);
+//    (CURSOR_ARROW_CSS_PX tall on the page, cursorDefaultHeight) — or, mirroring the page's CSS
+//    cursor: every CSS keyword and url() images (./inline3d-cursor-shape.js);
 //  - crosstalk softening (Amendment 2 §B.7): a LIFTED arrow is blurred by k × its ghost offset and
 //    faded toward alphaMin with its lift, both exactly zero on the glass (cursorSoften and below).
 
@@ -70,6 +71,43 @@ export {
   resolveCursorSoften,
 } from './inline3d-cursor-option.js';
 import { CURSOR_SOFTEN_DEFAULTS } from './inline3d-cursor-option.js';
+import { CURSOR_HIDDEN_ATTR, ensureCursorHiddenRule } from './inline3d-cursor-shape.js';
+
+// Which sprite: the page's CSS cursor mirrored (shapes, read-back) — its own module, re-exported.
+export {
+  CURSOR_CSS_KEYWORDS,
+  CURSOR_CSS_READ_MS,
+  CURSOR_HIDDEN_ATTR,
+  CURSOR_HIDDEN_RULE,
+  CURSOR_IMAGE_MAX_PX,
+  CURSOR_SHAPES,
+  CURSOR_SHAPE_OPTIONS,
+  CURSOR_SHAPE_TEXTURE_PX,
+  CursorCssReader,
+  CursorImageCache,
+  CursorShapeSelector,
+  cssCursorToShape,
+  cssKeywordToShape,
+  curFileHotspot,
+  cursorImageCache,
+  cursorPickShape,
+  cursorShape,
+  cursorShapeBox,
+  cursorShapePolys,
+  cursorShapeRaster,
+  cursorShapeSample,
+  cursorShapeTexture,
+  cursorSoftenPixels,
+  cursorSpriteBox,
+  cursorSpriteGLSL,
+  cursorSpriteRect,
+  drawCursorShape2D,
+  ensureCursorHiddenRule,
+  parseCssCursor,
+  readPageCursor,
+  resolveCursorSprite,
+  spriteForName,
+} from './inline3d-cursor-shape.js';
 
 /**
  * Fallback sprite height, as a fraction of the canvas height, when the canvas's on-page size is
@@ -413,7 +451,6 @@ export class CursorPointer {
     /** Pointer samples received so far (diagnostics). */
     this.samples = 0;
     this._hidden = false;
-    this._prev = '';
     this._cx = 0;
     this._cy = 0;
     this._pending = false; // a sample not yet resolved to uv (resolved once, on the next read)
@@ -421,6 +458,11 @@ export class CursorPointer {
     this._onLeave = () => {
       this.uv = null;
     };
+    // A touch (or a pen in contact) shows no cursor in the browser, so it must never drive the
+    // sprite: clear it on contact too, so a tap without a move cannot leave the last mouse hover up.
+    this._onDown = (e) => {
+      if (!cursorPointerHovers(e)) this.uv = null;
+    };
     this._target = scope === 'window' ? globalThis : canvas;
     // Freshest pointer: `pointerrawupdate` (Chromium, secure contexts) fires as each input arrives,
     // not once per frame, so the frame reads the newest position instead of one up to a frame old.
@@ -430,6 +472,7 @@ export class CursorPointer {
     this.source = supportsRawUpdate(this._target) ? 'pointerrawupdate' : 'pointermove';
     this._target.addEventListener('pointermove', this._onMove);
     if (this.source === 'pointerrawupdate') this._target.addEventListener('pointerrawupdate', this._onMove);
+    this._target.addEventListener('pointerdown', this._onDown);
     if (scope === 'window') {
       // Leaving the window (relatedTarget null) or losing focus mid-hover: nothing to hover.
       this._onOut = (e) => {
@@ -466,6 +509,12 @@ export class CursorPointer {
   // One pointer event: keep its NEWEST coalesced sample (getCoalescedEvents(), last entry), unless
   // a newer one is already held. No layout read here — uv resolves on the next read, once a frame.
   _sample(e) {
+    // Only a pointer the browser draws a cursor for: a mouse, or a pen hovering. A touch drag (or a
+    // pen stroke) clears the sprite — the browser shows no cursor there, so neither do we.
+    if (!cursorPointerHovers(e)) {
+      this.uv = null;
+      return;
+    }
     const list = typeof e.getCoalescedEvents === 'function' ? e.getCoalescedEvents() : null;
     const s = list && list.length ? list[list.length - 1] : e;
     const t = s.timeStamp > 0 ? s.timeStamp : e.timeStamp > 0 ? e.timeStamp : globalThis.performance ? globalThis.performance.now() : Date.now();
@@ -508,21 +557,24 @@ export class CursorPointer {
 
   /**
    * Hide (true) or restore (false) the CSS cursor; idempotent. Only ever while a sprite replaces
-   * it: whatever cursor the page set (`pointer`, `grab`, a `url(…)` image) is the cursor the rest of
-   * the time, and a cursor the page changes while it is hidden is not overwritten on restore.
-   * (Mirroring the page's CSS cursor INTO the drawn sprite is future work — ADR-046 Amendment 2 C,
-   * the browser feeding the computed CSS cursor to the runtime; today the sprite is the arrow.)
+   * it. The hide is a data attribute (CURSOR_HIDDEN_ATTR) on the canvas — on <html> for
+   * pointerScope 'window' — plus one injected `cursor: none !important` rule for it: the page's
+   * own cursor (`pointer`, `grab`, a `url(…)` image, inline or from a stylesheet) is never
+   * written, so it is what shows the rest of the time, and what the sprite mirrors (CursorCssReader
+   * lifts the attribute for its read).
    */
   hideCss(hide) {
     if (this.keepCss) hide = false;
     if (hide === this._hidden) return;
     if (this.scope === 'window') {
       pageCursorHidden(hide);
-    } else if (hide) {
-      this._prev = this.canvas.style.cursor || '';
-      this.canvas.style.cursor = 'none';
-    } else if (this.canvas.style.cursor === 'none') {
-      this.canvas.style.cursor = this._prev; // only if it is still ours
+    } else if (this.canvas.setAttribute) {
+      if (hide) {
+        ensureCursorHiddenRule();
+        this.canvas.setAttribute(CURSOR_HIDDEN_ATTR, '');
+      } else {
+        this.canvas.removeAttribute(CURSOR_HIDDEN_ATTR);
+      }
     }
     this._hidden = hide;
   }
@@ -530,6 +582,7 @@ export class CursorPointer {
   dispose() {
     this._target.removeEventListener('pointermove', this._onMove);
     if (this.source === 'pointerrawupdate') this._target.removeEventListener('pointerrawupdate', this._onMove);
+    this._target.removeEventListener('pointerdown', this._onDown);
     if (this.scope === 'window') {
       globalThis.removeEventListener('pointerout', this._onOut);
       globalThis.removeEventListener('blur', this._onLeave);
@@ -540,26 +593,37 @@ export class CursorPointer {
   }
 }
 
+/**
+ * Does this pointer event come from a pointer the browser shows a cursor for? A mouse, or a pen
+ * hovering in range (no buttons pressed). A touch never; a pen in contact neither. An event with
+ * no `pointerType` (a synthetic `new PointerEvent('pointermove')`, an old engine) counts as a mouse.
+ * Coalesced samples belong to their parent event, so the parent is what is tested.
+ * @param {{pointerType?: string, buttons?: number}} e
+ */
+export function cursorPointerHovers(e) {
+  const t = e && e.pointerType;
+  if (!t || t === 'mouse') return true;
+  if (t === 'pen') return !(e.buttons > 0);
+  return false;
+}
+
 /** Does `target` dispatch `pointerrawupdate`? (Chromium; only in a secure context.) */
 export function supportsRawUpdate(target) {
   return !!target && 'onpointerrawupdate' in target && globalThis.isSecureContext !== false;
 }
 
 // pointerScope 'window': the overlay DOM has its own cursor, so hiding it on the canvas alone is
-// not enough. A class on <html> plus one injected rule hides it everywhere while any depth cursor
-// shows; a count keeps two tiles from un-hiding each other.
+// not enough. The attribute on <html> (the injected rule covers its descendants) hides it
+// everywhere while any depth cursor shows; a count keeps two tiles from un-hiding each other.
 let _pageHides = 0;
 function pageCursorHidden(hide) {
   const doc = globalThis.document;
   if (!doc || !doc.documentElement) return;
-  if (hide && !doc.getElementById('inline3d-cursor-style')) {
-    const st = doc.createElement('style');
-    st.id = 'inline3d-cursor-style';
-    st.textContent = 'html.inline3d-cursor-hidden, html.inline3d-cursor-hidden * { cursor: none !important; }';
-    (doc.head || doc.documentElement).appendChild(st);
-  }
+  if (hide) ensureCursorHiddenRule(doc);
   _pageHides = Math.max(0, _pageHides + (hide ? 1 : -1));
-  doc.documentElement.classList.toggle('inline3d-cursor-hidden', _pageHides > 0);
+  const el = doc.documentElement;
+  if (_pageHides > 0) el.setAttribute?.(CURSOR_HIDDEN_ATTR, '');
+  else el.removeAttribute?.(CURSOR_HIDDEN_ATTR);
 }
 
 /**
@@ -975,3 +1039,37 @@ export function cursorSoftArrowRaster(cx, cy, sizePx, radius, alpha, fill = CURS
   }
   return { x0, y0, width, height, data };
 }
+
+/**
+ * PlayCanvas `pc.ShaderMaterial` opt-in to the depth cursor's pick (`cursor: 'depth'` on ./model
+ * and ./splat). The pick pass draws into TWO colour targets — the pick id, then the pick depth — and
+ * leaves out any ShaderMaterial whose fragment code does not write the second under
+ * DEPTH_PICK_PASS (WebGL would reject the draw), so such a mesh is never under the cursor. Paste
+ * `declarations` above `main` and `output` inside `#ifdef PICK_PASS … #else <your colour> #endif`:
+ *
+ *   fragmentGLSL: `${CURSOR_DEPTH_PICK_GLSL.declarations}
+ *     void main() {
+ *       #ifdef PICK_PASS
+ *         ${CURSOR_DEPTH_PICK_GLSL.output}
+ *       #else
+ *         gl_FragColor = vec4(0.2, 0.3, 0.4, 1.0);
+ *       #endif
+ *     }`
+ *
+ * The engine's own `pickPS` chunk does the work (getPickOutput / getPickDepth), so the id and the
+ * linear depth match its lit and gsplat materials exactly. Discard where your shader discards.
+ */
+export const CURSOR_DEPTH_PICK_GLSL = Object.freeze({
+  declarations: '#ifdef PICK_PASS\n#include "pickPS"\n#endif\n',
+  output: 'pcFragColor0 = getPickOutput();\n#ifdef DEPTH_PICK_PASS\npcFragColor1 = getPickDepth();\n#endif\n',
+});
+
+/**
+ * The WGSL twin of CURSOR_DEPTH_PICK_GLSL (a ShaderMaterial with `fragmentWGSL`, WebGPU): `output`
+ * writes `output.color` / `output.color1` of the engine's `FragmentOutput`, inside
+ * `#ifdef PICK_PASS … #else … #endif` in `fragmentMain`.
+ */
+export const CURSOR_DEPTH_PICK_WGSL = Object.freeze({
+  declarations: '#ifdef PICK_PASS\n#include "pickPS"\n#endif\n',
+  output: 'output.color = getPickOutput();\n#ifdef DEPTH_PICK_PASS\noutput.color1 = getPickDepth();\n#endif\n',
+});

package/js/inline3d-cursor-option.js

@@ -8,7 +8,20 @@
 export const CURSOR_ANCHOR_MODES = Object.freeze(['hybrid', 'screen', 'world']);
 
 /** The keys `cursor: { … }` accepts on ./model and ./splat. */
-export const CURSOR_OPTION_KEYS = Object.freeze(['height', 'margin', 'anchor', 'pointerScope', 'debug', 'soften']);
+export const CURSOR_OPTION_KEYS = Object.freeze(['height', 'margin', 'anchor', 'pointerScope', 'debug', 'soften', 'shape', 'shapeFor']);
+
+/**
+ * The procedural sprites the depth cursor can draw (see ./inline3d-cursor-shape.js): one per
+ * standard CSS cursor keyword (aliases such as `n-resize` → `ns-resize` share one).
+ */
+export const CURSOR_SHAPES = Object.freeze([
+  'arrow', 'pointer', 'grab', 'grabbing', 'move', 'text', 'vertical-text', 'crosshair', 'not-allowed',
+  'help', 'wait', 'progress', 'copy', 'alias', 'context-menu', 'cell', 'ns-resize', 'ew-resize',
+  'nesw-resize', 'nwse-resize', 'col-resize', 'row-resize', 'zoom-in', 'zoom-out',
+]);
+
+/** `cursor.shape` values: a sprite, `'none'` (draw nothing), or `'auto'` (default) — mirror the page's CSS cursor. */
+export const CURSOR_SHAPE_OPTIONS = Object.freeze(['auto', 'none', ...CURSOR_SHAPES]);
 
 // ── Crosstalk softening (runtime ADR-046 Amendment 2 §B.7) ─────────────────────────────────────
 // On a lenticular panel a little of every view leaks into its neighbours. A LIFTED cursor's leaked
@@ -124,13 +137,13 @@ export function parseCursorSoften(mode, blurK, blurMaxPx, blurMaxFrac, alphaMin,
  * depth). Anything falsy is OFF — the zero-cost default. Validated here, at the call.
  * `debug`: true logs the cursor's per-frame cost (rolling stats, at most once a second); 'both' also
  * keeps the OS cursor visible beside the sprite (the latency check). Off by default, and free.
- * @returns {null | {height?: number, margin?: number, anchor?: string, pointerScope?: string, debug?: boolean|'both', soften?: string | object}}
+ * @returns {null | {height?: number, margin?: number, anchor?: string, pointerScope?: string, debug?: boolean|'both', soften?: string | object, shape?: string, shapeFor?: Function}}
  */
 export function resolveCursorOption(opt, who = '@displayxr/inline3d') {
   if (opt === undefined || opt === null || opt === false) return null;
   if (opt === 'depth' || opt === true) return {};
   if (typeof opt !== 'object') {
-    throw new Error(`${who}: cursor ${JSON.stringify(opt)} — expected 'depth' or { height, margin, anchor, pointerScope, debug, soften }.`);
+    throw new Error(`${who}: cursor ${JSON.stringify(opt)} — expected 'depth' or { ${CURSOR_OPTION_KEYS.join(', ')} }.`);
   }
   const unknown = Object.keys(opt).filter((k) => !CURSOR_OPTION_KEYS.includes(k));
   if (unknown.length) throw new Error(`${who}: cursor — unknown option(s) ${unknown.join(', ')}; expected ${CURSOR_OPTION_KEYS.join(', ')}.`);
@@ -149,14 +162,20 @@ export function resolveCursorOption(opt, who = '@displayxr/inline3d') {
     }
   }
   if (opt.soften !== undefined) resolveCursorSoften(opt.soften, who); // validate at the call
+  if (opt.shape !== undefined && !CURSOR_SHAPE_OPTIONS.includes(opt.shape)) {
+    throw new Error(`${who}: cursor.shape ${JSON.stringify(opt.shape)} — expected ${CURSOR_SHAPE_OPTIONS.map((m) => `'${m}'`).join(' | ')}.`);
+  }
+  if (opt.shapeFor !== undefined && opt.shapeFor !== null && typeof opt.shapeFor !== 'function') {
+    throw new Error(`${who}: cursor.shapeFor must be a function (hit) => shape.`);
+  }
   return { ...opt };
 }
 
 /** The keys `cursor: { … }` accepts on a stereo PAIR (./camera's addCameraView, ./call's tiles). */
-export const PAIR_CURSOR_OPTION_KEYS = Object.freeze(['height', 'pointerScope', 'soften']);
+export const PAIR_CURSOR_OPTION_KEYS = Object.freeze(['height', 'pointerScope', 'soften', 'shape', 'shapeFor']);
 
 /**
- * `cursor` on a stereo pair — a camera view or a call tile: `'depth'`, or `{ height, pointerScope, soften }`.
+ * `cursor` on a stereo pair — a camera view or a call tile: `'depth'`, or `{ height, pointerScope, soften, shape, shapeFor }`.
  * A pair has no scene: its depth is MEASURED off the two halves, and the sprite is drawn into them,
  * so there is no anchor mode (it is always on the line of sight) and the margin is the SDK's. Falsy
  * is OFF, the zero-cost default.