@displayxr/inline3d 1.43.1 → 1.44.0

package/js/inline3d-cursor-option.js

@@ -8,18 +8,129 @@
 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']);
+export const CURSOR_OPTION_KEYS = Object.freeze(['height', 'margin', 'anchor', 'pointerScope', 'debug', 'soften']);
+
+// ── 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
+// copy sits one ghost offset away, and how visible it is scales with contrast × edge sharpness; on
+// the glass the views coincide and there is no ghost. So the drawn arrow is softened with lift:
+// an edge blur of k × |ghost offset| panel px (capped) and an opacity easing to alphaMin. Both are
+// exactly zero on the glass. The numbers are the runtime's U_CURSOR_SOFTEN_DEFAULT_*, tuned by eye
+// on a Windows Leia panel and confirmed on a Mac (2026-10-11/12), so web and native match.
+
+/** `cursor.soften` presets: both effects (default), neither, or one of them (the A/B presets). */
+export const CURSOR_SOFTEN_PRESETS = Object.freeze(['both', 'off', 'alpha', 'blur']);
+
+/** The runtime's softening defaults (u_cursor_soften_params_default). */
+export const CURSOR_SOFTEN_DEFAULTS = Object.freeze({
+  /** Edge blur on. */
+  blur: true,
+  /** Opacity easing on. */
+  alpha: true,
+  /** Panel px of blur per panel px of ghost offset. */
+  blurK: 0.1,
+  /** Hard ceiling on the blur radius, panel px (the real cap is blurMaxFrac). */
+  blurMaxPx: 8,
+  /** Blur cap as a fraction of the DRAWN arrow's height (~4 px on a 64 px arrow), so it reads the same at any DPI. */
+  blurMaxFrac: 0.06,
+  /** Opacity at full lift. */
+  alphaMin: 0.5,
+  /** |disparity| (eye baselines) at which the opacity reaches alphaMin: the lift over typical content. */
+  fullD: 0.03,
+});
+
+// The numeric knobs and their legal ranges [lo, hi, loOpen] — the runtime's parse ranges.
+const SOFTEN_NUMBERS = Object.freeze({
+  blurK: [0, 1000, false],
+  blurMaxPx: [0, 8, false],
+  blurMaxFrac: [0, 0.5, false],
+  alphaMin: [0, 1, false],
+  fullD: [0, 1000, true],
+});
+
+/** The keys `cursor.soften: { … }` accepts: an optional preset `mode`, then the numbers. */
+export const CURSOR_SOFTEN_KEYS = Object.freeze(['mode', ...Object.keys(SOFTEN_NUMBERS)]);
+
+const inSoftenRange = (k, v) => {
+  const [lo, hi, loOpen] = SOFTEN_NUMBERS[k];
+  return typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi && !(loOpen && v <= lo);
+};
+
+const presetFlags = (mode) => ({ blur: mode === 'both' || mode === 'blur', alpha: mode === 'both' || mode === 'alpha' });
+
+/**
+ * `cursor.soften` as the API accepts it, resolved to the full parameter set: a preset
+ * (`'both'` — the default — `'off'`, `'alpha'`, `'blur'`), or `{ mode?, blurK?, blurMaxPx?,
+ * blurMaxFrac?, alphaMin?, fullD? }` over the defaults. `undefined` / `null` / `true` = the
+ * defaults, `false` = `'off'`. Throws on a bad value, like every other option, at the call.
+ * @returns {{blur: boolean, alpha: boolean, blurK: number, blurMaxPx: number, blurMaxFrac: number, alphaMin: number, fullD: number}}
+ */
+export function resolveCursorSoften(opt, who = '@displayxr/inline3d') {
+  if (opt === undefined || opt === null || opt === true) return { ...CURSOR_SOFTEN_DEFAULTS };
+  if (opt === false) opt = 'off';
+  const bad = () => new Error(`${who}: cursor.soften ${JSON.stringify(opt)} — expected ${CURSOR_SOFTEN_PRESETS.map((m) => `'${m}'`).join(' | ')} or { ${CURSOR_SOFTEN_KEYS.join(', ')} }.`);
+  if (typeof opt === 'string') {
+    if (!CURSOR_SOFTEN_PRESETS.includes(opt)) throw bad();
+    return { ...CURSOR_SOFTEN_DEFAULTS, ...presetFlags(opt) };
+  }
+  if (typeof opt !== 'object' || Array.isArray(opt)) throw bad();
+  const unknown = Object.keys(opt).filter((k) => !CURSOR_SOFTEN_KEYS.includes(k));
+  if (unknown.length) throw new Error(`${who}: cursor.soften — unknown option(s) ${unknown.join(', ')}; expected ${CURSOR_SOFTEN_KEYS.join(', ')}.`);
+  if (opt.mode !== undefined && !CURSOR_SOFTEN_PRESETS.includes(opt.mode)) throw bad();
+  const out = { ...CURSOR_SOFTEN_DEFAULTS, ...presetFlags(opt.mode ?? 'both') };
+  for (const k of Object.keys(SOFTEN_NUMBERS)) {
+    if (opt[k] === undefined) continue;
+    const [lo, hi, loOpen] = SOFTEN_NUMBERS[k];
+    if (!inSoftenRange(k, opt[k])) throw new Error(`${who}: cursor.soften.${k} must be a number in ${loOpen ? '(' : '['}${lo}, ${hi}].`);
+    out[k] = opt[k];
+  }
+  return out;
+}
+
+// strtod-like: optional leading whitespace, a decimal float, optional trailing spaces/tabs.
+const SOFTEN_FLOAT = /^\s*[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[ \t]*$/;
+
+/**
+ * The runtime's lenient knob parse (u_cursor_soften_params_parse), for string sources such as URL
+ * parameters: `mode` 'off' | 'alpha' | 'blur' | 'both' (its leading word; anything else = both),
+ * the numbers as strings. Each may be null/undefined (= default); a value that does not parse or
+ * is out of range keeps its default instead of throwing.
+ * @returns {{params: object, changed: boolean}}  `changed`: any knob differs from its default.
+ */
+export function parseCursorSoften(mode, blurK, blurMaxPx, blurMaxFrac, alphaMin, fullD) {
+  const params = { ...CURSOR_SOFTEN_DEFAULTS };
+  let changed = false;
+  if (mode !== null && mode !== undefined) {
+    const word = String(mode).split(/[ \t]/)[0];
+    if (word === 'off') params.blur = params.alpha = false;
+    else if (word === 'alpha') params.blur = false;
+    else if (word === 'blur') params.alpha = false;
+    changed = !params.blur || !params.alpha;
+  }
+  const raw = { blurK, blurMaxPx, blurMaxFrac, alphaMin, fullD };
+  for (const k of Object.keys(SOFTEN_NUMBERS)) {
+    const s = raw[k];
+    if (s === null || s === undefined || s === '' || !SOFTEN_FLOAT.test(String(s))) continue;
+    const v = parseFloat(String(s));
+    if (!inSoftenRange(k, v)) continue;
+    params[k] = v;
+    changed = true;
+  }
+  return { params, changed };
+}
 
 /**
  * `cursor` as ./model and ./splat accept it: `'depth'`, or an options object (which also means
  * depth). Anything falsy is OFF — the zero-cost default. Validated here, at the call.
- * @returns {null | {height?: number, margin?: number, anchor?: string, pointerScope?: string}}
+ * `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}}
  */
 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 }.`);
+    throw new Error(`${who}: cursor ${JSON.stringify(opt)} — expected 'depth' or { height, margin, anchor, pointerScope, debug, soften }.`);
   }
   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(', ')}.`);
@@ -29,23 +140,27 @@ export function resolveCursorOption(opt, who = '@displayxr/inline3d') {
   if (opt.pointerScope !== undefined && opt.pointerScope !== 'canvas' && opt.pointerScope !== 'window') {
     throw new Error(`${who}: cursor.pointerScope "${opt.pointerScope}" — expected 'canvas' or 'window'.`);
   }
+  if (opt.debug !== undefined && typeof opt.debug !== 'boolean' && opt.debug !== 'both') {
+    throw new Error(`${who}: cursor.debug ${JSON.stringify(opt.debug)} — expected true, false or 'both'.`);
+  }
   for (const k of ['height', 'margin']) {
     if (opt[k] !== undefined && !(typeof opt[k] === 'number' && opt[k] > 0 && Number.isFinite(opt[k]))) {
       throw new Error(`${who}: cursor.${k} must be a positive number.`);
     }
   }
+  if (opt.soften !== undefined) resolveCursorSoften(opt.soften, who); // validate at the call
   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']);
+export const PAIR_CURSOR_OPTION_KEYS = Object.freeze(['height', 'pointerScope', 'soften']);
 
 /**
- * `cursor` on a stereo pair — a camera view or a call tile: `'depth'`, or `{ height, pointerScope }`.
+ * `cursor` on a stereo pair — a camera view or a call tile: `'depth'`, or `{ height, pointerScope, soften }`.
  * 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.
- * @returns {null | {height?: number, pointerScope?: string}}
+ * @returns {null | {height?: number, pointerScope?: string, soften?: string | object}}
  */
 export function resolvePairCursorOption(opt, who = '@displayxr/inline3d') {
   const o = resolveCursorOption(opt, who);

package/js/inline3d-cursor-perf.js

@@ -0,0 +1,199 @@
+// inline3d-cursor-perf.js — what keeps the depth cursor responsive, dependency-free and internal
+// (not a package subpath; ./three's DepthCursor is its only user):
+//
+//  - CursorAmortisedPick: the footprint pick spread over frames. The sprite is placed every frame
+//    at the NEWEST pointer position with the last known depth; the pick only refreshes that depth,
+//    a few rays a frame, so it never stretches the frame it runs in. The depth filter (rise 30 ms,
+//    sink 250 ms) absorbs the cadence.
+//  - CursorDebugStats: `cursor: { debug: true }` — per-frame cost, rays and frame interval as
+//    rolling stats, printed at most once a second. Nothing is built without the option.
+//
+// The policy (ADR-046 Amendment 2: never behind the glass, the OS cursor on it, the hybrid anchor
+// exact while moving) is untouched: it lives in CursorDepthPlacer, downstream of the pick.
+
+/** Rays a frame ./model's three.js cursor casts (with a BVH, a ray costs a few microseconds). */
+export const CURSOR_MODEL_RAYS_PER_FRAME = 3;
+
+/**
+ * The footprint pick, amortised: `raysPerFrame` rays a frame, cycling every (footprint point, eye)
+ * slot. The slot order covers every footprint point once (alternating eyes) before it repeats a
+ * point, so a full spatial sweep takes ceil(points / N) frames and both eyes twice that.
+ *
+ * Each slot keeps its last hit (a world point, or null for a miss) and the hotspot it was cast
+ * from. A slot cast from a hotspot more than `reach` away (canvas heights) is stale — the pointer
+ * has moved on — and is ignored, so a fast-moving pointer is judged on its freshest rays only and
+ * a still one on the whole footprint.
+ */
+export class CursorAmortisedPick {
+  /** @param {number} raysPerFrame  >= 1. */
+  constructor(raysPerFrame) {
+    this.raysPerFrame = Math.max(1, Math.floor(raysPerFrame) || 1);
+    this._slots = []; // { point, u, v } | undefined (never cast)
+    this._next = 0;
+    this._n = 0; // slot count the ring was sized for
+    /** Rays cast by the last step (diagnostics). */
+    this.lastRays = 0;
+  }
+
+  /** Forget every slot (the next step starts a fresh sweep). */
+  reset() {
+    this._slots.length = 0;
+    this._next = 0;
+    this._n = 0;
+  }
+
+  /**
+   * The (point, eye) of slot `k` among `points` × `eyes`: eye = (point + sweep) mod eyes, so each
+   * sweep of `points` slots alternates eyes and the next sweep takes the other ones.
+   */
+  static slot(k, points, eyes) {
+    const p = k % points;
+    return [p, (p + Math.floor(k / points)) % eyes];
+  }
+
+  /**
+   * Cast this frame's rays and return the nearest live hit, or null.
+   * @param {Array<[number, number]>} footprint  canvas-normalised points, the hotspot first.
+   * @param {number} eyes  how many views to cast from (1 or 2).
+   * @param {(eye: number, u: number, v: number) => number[]|null} cast  one ray → its hit.
+   * @param {number[]} forward  the viewing direction (unit): smaller dot = nearer the viewer.
+   * @param {number} aspect  canvas width / height (u distances are scaled by it).
+   * @param {number} reach  how far (canvas heights) the hotspot may have moved since a slot was cast.
+   */
+  step(footprint, eyes, cast, forward, aspect, reach) {
+    const P = footprint.length;
+    const E = Math.max(1, eyes | 0);
+    const n = P * E;
+    if (n !== this._n) {
+      this.reset();
+      this._n = n;
+    }
+    const [u0, v0] = footprint[0];
+    const rays = Math.min(this.raysPerFrame, n);
+    for (let i = 0; i < rays; i++) {
+      const k = this._next;
+      this._next = (k + 1) % n;
+      const [p, e] = CursorAmortisedPick.slot(k, P, E);
+      this._slots[k] = { point: cast(e, footprint[p][0], footprint[p][1]), u: u0, v: v0 };
+    }
+    this.lastRays = rays;
+    const r2 = reach * reach;
+    let best = Infinity, nearest = null;
+    for (let k = 0; k < n; k++) {
+      const s = this._slots[k];
+      if (!s || !s.point) continue;
+      const du = (s.u - u0) * aspect, dv = s.v - v0;
+      if (du * du + dv * dv > r2) continue; // cast from where the pointer no longer is
+      const q = s.point;
+      const depth = q[0] * forward[0] + q[1] * forward[1] + q[2] * forward[2];
+      if (depth < best) {
+        best = depth;
+        nearest = q;
+      }
+    }
+    return nearest;
+  }
+}
+
+/** `cursor.debug` → the stats mode: false (off), 'stats', or 'both' (stats + the OS cursor kept visible). */
+export function cursorDebugMode(debug) {
+  if (debug === 'both') return 'both';
+  return debug ? 'stats' : false;
+}
+
+const mean = (a) => (a.length ? a.reduce((s, x) => s + x, 0) / a.length : 0);
+const quantile = (a, q) => {
+  if (!a.length) return 0;
+  const s = Float64Array.from(a).sort();
+  return s[Math.min(s.length - 1, Math.floor(q * s.length))];
+};
+const max = (a) => (a.length ? Math.max(...a) : 0);
+const stat = (a) => ({ mean: mean(a), p95: quantile(a, 0.95), max: max(a), n: a.length });
+const f = (x, d = 2) => x.toFixed(d);
+
+function describePick(p) {
+  if (p.mode !== 'bvh') return p.mode;
+  return `bvh (${p.built} built in ${f(p.buildMs, 1)} ms${p.refits ? `, ${p.refits} refits` : ''}${p.failed ? `, ${p.failed} failed` : ''}, ${p.plainCasts} plain casts)`;
+}
+
+/**
+ * Rolling per-frame stats for `cursor: { debug }`, summarised and logged at most once per
+ * `periodMs` — never per frame. `history` keeps the last 120 summaries (two minutes) for a
+ * harness to read; `last` is the newest.
+ */
+export class CursorDebugStats {
+  /**
+   * @param {{tag?: string, periodMs?: number, log?: (line: string) => void, info?: (() => object)|null}} [opts]
+   *        `info`: the hit test's own diagnostics (which pick answers), copied into each summary as `pick`.
+   */
+  constructor({ tag = '[inline3d] cursor', periodMs = 1000, log, info = null } = {}) {
+    this.tag = tag;
+    this.info = info;
+    /** Which event feeds the pointer ('pointerrawupdate' / 'pointermove'), when the owner knows. */
+    this.source = null;
+    this.periodMs = periodMs;
+    this.log = log || ((line) => console.info(line));
+    /** @type {object|null} */
+    this.last = null;
+    /** @type {object[]} */
+    this.history = [];
+    this._start = null;
+    this._prev = null;
+    this._clear();
+  }
+
+  _clear() {
+    this._update = [];
+    this._rays = [];
+    this._frame = [];
+    this._age = [];
+    this._samples = 0;
+  }
+
+  /**
+   * One frame.
+   * @param {number} updateMs  what DepthCursor.update() took.
+   * @param {number} rays  rays it cast.
+   * @param {number} nowMs  the frame time (performance.now()).
+   * @param {number|null} pointerAgeMs  age of the pointer sample this frame used, when it is NEW
+   *        this frame (null when the pointer has not moved since the last frame).
+   * @param {number} [samples=0]  pointer samples received since the last frame.
+   * @returns {object|null}  the summary when one was emitted this frame.
+   */
+  frame(updateMs, rays, nowMs, pointerAgeMs = null, samples = 0) {
+    if (this._start === null) this._start = nowMs;
+    if (this._prev !== null && nowMs > this._prev) this._frame.push(nowMs - this._prev);
+    this._prev = nowMs;
+    this._update.push(updateMs);
+    this._rays.push(rays);
+    if (Number.isFinite(pointerAgeMs) && pointerAgeMs >= 0) this._age.push(pointerAgeMs); // null (no new sample) is not finite
+    this._samples += samples;
+    if (nowMs - this._start < this.periodMs) return null;
+    const s = {
+      frames: this._update.length,
+      seconds: (nowMs - this._start) / 1000,
+      updateMs: stat(this._update),
+      rays: stat(this._rays),
+      frameMs: stat(this._frame),
+      pointerAgeMs: stat(this._age),
+      samplesPerFrame: this._update.length ? this._samples / this._update.length : 0,
+      pointerSource: this.source,
+      pick: this.info ? this.info() : null,
+    };
+    this.last = s;
+    this.history.push(s);
+    if (this.history.length > 120) this.history.shift();
+    this._start = nowMs;
+    this._clear();
+    this.log(
+      `${this.tag} debug: ${s.frames} frames` +
+        ` · update ${f(s.updateMs.mean)} ms avg / ${f(s.updateMs.p95)} p95 / ${f(s.updateMs.max)} max` +
+        ` · rays ${f(s.rays.mean, 1)}/frame (max ${s.rays.max})` +
+        ` · frame ${f(s.frameMs.mean, 1)} ms avg / ${f(s.frameMs.p95, 1)} p95 / ${f(s.frameMs.max, 1)} max` +
+        (s.pointerAgeMs.n ? ` · pointer age ${f(s.pointerAgeMs.mean, 1)} ms avg / ${f(s.pointerAgeMs.max, 1)} max` : '') +
+        ` · ${f(s.samplesPerFrame, 1)} pointer samples/frame${s.pointerSource ? ` (${s.pointerSource})` : ''}` +
+        (s.pick ? ` · pick ${describePick(s.pick)}` : ''),
+    );
+    return s;
+  }
+}

package/js/inline3d-model.js

@@ -42,11 +42,38 @@ import { guardedAttach } from './inline3d-splat-shared.js';
 import * as THREE from 'three';
 import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest } from './inline3d-three.js';
 import { resolveCursorOption } from './inline3d-cursor-depth.js';
+import { CURSOR_MODEL_RAYS_PER_FRAME } from './inline3d-cursor-perf.js';
 import { SceneViewer } from './inline3d-viewer.js';
 // Procedural — built in memory, no asset to serve. Imported eagerly rather than lazily because it
 // is the default lighting path, so deferring it would only add a frame of unlit content.
 import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
 
+/**
+ * `cursor: 'depth'`'s hit test over the model: three's plain raycast at once, then the
+ * BVH-accelerated one (./inline3d-cursor-bvh.js, with its vendored three-mesh-bvh slice) as soon as
+ * that module arrives. Called on opt-in ONLY — the one place the module is imported, dynamically,
+ * so a page without the cursor never downloads it (ADR-046 §0). If it cannot load, the plain
+ * raycast simply stays.
+ */
+function cursorHitTest(content) {
+  const plain = raycastHitTest(THREE, [content]);
+  let fast = null;
+  let failed = false;
+  import('./inline3d-cursor-bvh.js').then(
+    (m) => {
+      fast = m.bvhHitTest(THREE, [content]);
+    },
+    (err) => {
+      failed = true;
+      console.warn('[inline3d/model] cursor: depth: the BVH pick could not load; using the plain raycast.', err);
+    },
+  );
+  const hitTest = (origin, direction) => (fast ? fast(origin, direction) : plain(origin, direction));
+  /** Diagnostics (`cursor: { debug }`): which pick is answering. */
+  hitTest.info = () => (fast ? fast.info() : { mode: failed ? 'plain (bvh failed to load)' : 'plain (bvh loading)' });
+  return hitTest;
+}
+
 /** Cached across calls so a grid of models resolves the loader module once. */
 let _GLTFLoader = null;
 
@@ -391,7 +418,9 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
   const cursorOpts = resolveCursorOption(opts.cursor, '@displayxr/inline3d/model');
-  if (cursorOpts) viewer.useDepthCursor(DepthCursor, (content) => raycastHitTest(THREE, [content]), cursorOpts);
+  // Amortised pick (a few rays a frame): the sprite follows the newest pointer position every
+  // frame and the pick only refreshes its depth, so a heavy mesh never stretches the frame.
+  if (cursorOpts) viewer.useDepthCursor(DepthCursor, cursorHitTest, { raysPerFrame: CURSOR_MODEL_RAYS_PER_FRAME, ...cursorOpts });
 
   if (envMap) viewer.scene.environment = envMap;
   else if (environment === 'room') addRoomEnvironment(viewer);

package/js/inline3d-playcanvas-engine.js

@@ -58,6 +58,7 @@ export {
   SEMANTIC_COLOR,
   ShaderChunks,
   SHADERLANGUAGE_GLSL,
+  SHADERLANGUAGE_WGSL,
   SHADER_FORWARD,
   CHUNKAPI_2_8,
   // setSource's frame snapshot