@displayxr/inline3d 1.43.0 → 1.44.0

package/CHANGELOG.md

@@ -5,6 +5,78 @@ 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.44.0 — 2026-10-13
+
+Touches the **core** `./three` (`DepthCursor`), `./cursor-depth`, and the **preview tier** (`./model`,
+`./splat`, `./call`, `./camera`: `cursor: 'depth'`). **One deliberate look change:** a LIFTED depth
+cursor is now softened by default. On the glass nothing changes (nothing is drawn there).
+
+### Depth cursor responsiveness (`./model`, three.js)
+
+- The arrow follows the **newest** pointer position every frame, and the pick is amortised (3 rays a
+  frame) instead of casting the whole footprint synchronously.
+- BVH pick: three-mesh-bvh 0.9.15 (MeshBVH only, MIT) is vendored at `js/vendor/three-mesh-bvh.js`
+  and loaded **only** with `cursor: 'depth'`. Nothing on the page is mutated. Skinned, morphing,
+  instanced and batched meshes, and partial draw ranges, keep three's own raycast.
+- The pointer comes from `pointerrawupdate` (coalesced samples) where the browser has it.
+- CarConcept, headless: `update()` 8.2 → 0.16 ms mean, 50.6 → 0.5 ms max.
+- New `cursor: { debug: true | 'both' }`: rolling cost stats; `'both'` keeps the OS cursor visible
+  beside the sprite (the latency check).
+- If you vendor the SDK, copy `js/vendor/` too. The BVH slice imports bare `three`.
+
+### Depth cursor: crosstalk softening of the lifted arrow (runtime ADR-046 Amendment 2 §B.7 parity)
+
+- On a lenticular panel a lifted, white, sharp-edged arrow ghosts: crosstalk leaks a copy one
+  disparity away, and its visibility scales with contrast × edge sharpness. The runtime softens its
+  cursor by lift; every web depth cursor now does the same, constant for constant, so web and
+  native cursors look alike: an edge blur of 0.1 × the ghost offset (the neighbouring views' split,
+  panel px), capped at 6% of the arrow's drawn height and 8 px, and an opacity easing from 1 to 0.5
+  with a smoothstep over 0.03 eye baselines of lift. Both are exactly zero on the glass, and the
+  tip (the click point) never moves. Defaults tuned on a Windows Leia panel and confirmed on a Mac.
+- **`cursor.soften`** on `./model`, `./splat`, `./call`, `./camera`, and `soften` on `DepthCursor`:
+  `'both'` (default), `'off'` (the crisp arrow, pixel-identical to 1.43), `'alpha'`, `'blur'`, or
+  `{ mode, blurK, blurMaxPx, blurMaxFrac, alphaMin, fullD }` over the defaults. Validated at the call.
+- Drawn in the cursor's own material: a quad padded by the blur radius whose fragment shader
+  evaluates the arrow analytically at the runtime's 13 blur taps (three and PlayCanvas), or the
+  same function rasterised into the woven buffer (stereo pairs). Never a CSS `filter` or `opacity`.
+  A frame with nothing to soften draws the crisp mesh as before; zero cost without `cursor: 'depth'`.
+- `./cursor-depth` exports the pieces: `cursorSoften`, `cursorGhostPx`, `cursorProjectToCanvas`,
+  `cursorPlacementSoften`, `cursorSoftArrowGLSL`, `cursorSoftArrowRaster`, `cursorSoftArrowSample`,
+  `resolveCursorSoften`, `parseCursorSoften`, `CURSOR_SOFTEN_DEFAULTS`, `CURSOR_SOFTEN_KERNEL`, and
+  more. The samples take `&soften=both|off|alpha|blur` next to `?cursor=depth`.
+- docs/authoring-inline-3d.md §A cursor that respects depth.
+
+### Fixed — `cursor: 'depth'` (PlayCanvas): no GL error storm from an app's own `ShaderMaterial`
+
+- The depth pick pass renders into two colour targets (pick id + pick depth). A mesh whose
+  `pc.ShaderMaterial` writes only one output (a custom backdrop, frame or chrome quad) had every
+  pick draw rejected with `GL_INVALID_OPERATION: Active draw buffers with missing fragment shader
+  outputs` — hundreds a second on a panel, until Chromium stopped reporting them. Such meshes are now
+  left out of the pick pass (they never reached the pick buffer anyway), so nothing the cursor sees
+  changes. Materials that handle `DEPTH_PICK_PASS`, followed through their `#include`s (the
+  engine's gsplat material included), stay in.
+
+### Fixed — the depth cursor drifted off a still pointer while the camera moved
+
+- With `cursor: 'depth'` and the default `anchor: 'hybrid'`, a still pointer's arrow was pinned in
+  the SCENE, so anything that moved the camera rig under it carried it away: `./model`'s idle
+  turntable (8°/s) put it ~0.26 of the canvas off the pointer within ~6 s, and a damped drag or a
+  scripted camera did the same. The kept line of sight now lives in the display's frame (relative
+  to the canvas, in canvas heights), as in the runtime's `u_cursor_depth`, which works in display
+  space: a rig orbit, pan or zoom leaves the arrow on the pointer, and a head move still
+  parallaxes it like content. A canvas whose shape changes under a still pointer (a resize)
+  re-anchors, as does the head pulling back past the anchor eye. `'screen'` and `'world'` are
+  unchanged (neither keeps state across frames).
+
+## 1.43.1 — 2026-10-13
+
+### Fixed — `warmEntity` on a display-rig layer
+
+- `warmEntity` warmed only through the eye camera(s). A mesh on a layer moved to the display rig
+  (`setLayerRig`, e.g. a round stage) is drawn **only** by the layer rig's cameras, with their own
+  `shaderParams`, so its real program still linked on first draw while the warm issued a variant
+  nobody draws. It now warms through the layer rig's display/post cameras too.
+
 ## 1.43.0 — 2026-10-12
 
 ### `./splat` (PlayCanvas) — `warmEffect`: no frozen frame when a reveal first plays

package/THIRD_PARTY_NOTICES.md

@@ -1,13 +1,15 @@
 # Third-party notices — `@displayxr/inline3d`
 
-`@displayxr/inline3d` is Apache-2.0 (see `LICENSE`). It bundles no third-party code, but parts of
-it are adapted from, or run on, the MIT-licensed projects below. Their notices follow.
+`@displayxr/inline3d` is Apache-2.0 (see `LICENSE`). It bundles one piece of third-party code —
+a slice of three-mesh-bvh, below — and parts of it are adapted from, or run on, the MIT-licensed
+projects below. Their notices follow.
 
 | Project | Version | How it is used |
 |---|---|---|
 | [PlayCanvas engine](https://github.com/playcanvas/engine) | 2.22.3 | Optional peer (`playcanvas`): the default splat backend and the `./model` backend. Shader code in this package is **adapted** from it: the non-square-pixel footprint rewrite of `src/scene/shader-lib/glsl/chunks/gsplat/vert/gsplatCorner.js` (`js/inline3d-splat-playcanvas.js`), the quad-extent cap in `gsplatCommon.js` (`js/inline3d-splat-perf.js`), and the dissolve effect and its hash/noise/fbm helpers from `scripts/esm/gsplat/shader-effect-dissolve.mjs` (`js/inline3d-splat-effects.js`). Each adapted site carries a provenance comment. |
 | [three.js](https://github.com/mrdoob/three.js) | ≥ 0.150 | Optional peer (`three`): the `./three` helpers, the Spark splat path, `./model`'s `engine: 'three'`. The PlayCanvas backend's `environment: 'room'` is **adapted** from `examples/jsm/environments/RoomEnvironment.js` (its scene numbers, re-rendered by ray casting in `js/inline3d-model-playcanvas.js`, `ROOM_ENVIRONMENT`). |
 | [Spark](https://github.com/sparkjsdev/spark) | ≥ 2.0 | Optional peer (`@sparkjsdev/spark`): the Spark splat backend. |
+| [three-mesh-bvh](https://github.com/gkjohnson/three-mesh-bvh) | 0.9.15 | **Bundled**: `js/vendor/three-mesh-bvh.js` is its `MeshBVH`, minified by `tools/vendor/three-mesh-bvh.mjs` (three stays external). Loaded only when a page opts into `cursor: 'depth'` on `./model`'s three.js engine, for the cursor's BVH pick (`js/inline3d-cursor-bvh.js`). |
 
 ## PlayCanvas engine — MIT
 
@@ -75,6 +77,28 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+## three-mesh-bvh — MIT
+
+Copyright (c) 2018 Garrett Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 ## Sample assets (repo samples only, not in the npm package)
 
 The pages under `samples/` show these assets. None is in the published `@displayxr/inline3d`

package/camera.d.ts

@@ -12,6 +12,7 @@
 // until the snapshot is updated in the same change (`node tools/api-surface.mjs --update`).
 
 import type { Inline3D, Inline3DUnsupported, TileHandle } from './index.js';
+import type { CursorSoftenOption } from './cursor-depth.js';
 
 /** What the camera delivers: a side-by-side pair (left eye left) or one flat picture. */
 export type CameraFormat = 'sbs' | 'mono';
@@ -193,6 +194,8 @@ export interface PairCursorOptions {
   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';
+  /** Crosstalk softening of the lifted arrow (runtime ADR-046 Amendment 2 §B.7), drawn into the woven pixels. Default `'both'`. */
+  soften?: CursorSoftenOption;
 }
 
 export interface CameraViewOptions {

package/cursor-depth.d.ts

@@ -66,7 +66,9 @@ export function placeCursor(g: CursorGeometry, disparity: number, heightFraction
 /**
  * Where along the cursor's depth the sprite goes.
  * - `'hybrid'` (default): on the line of sight while the pointer MOVES (exactly over it), and
- *   world-FIXED while it is still, so it parallaxes with the content as the head moves.
+ *   fixed relative to the DISPLAY while it is still, so it parallaxes with the content as the head
+ *   moves. Anchored in the display's frame, not the scene's: a rig that orbits, pans or zooms
+ *   (an idle spin, a damped drag, a scripted camera) does not move a still cursor off the pointer.
  * - `'screen'`: always on the line of sight. Never parallaxes; on a head-tracked display it can
  *   read as "at the glass".
  * - `'world'`: always straight in front of the pointer's canvas point. Parallaxes; drifts ~mm off
@@ -85,6 +87,15 @@ export interface CursorOptions {
   anchor?: CursorAnchorMode;
   /** `'window'`: keep the cursor over DOM layered on the canvas, and hide the CSS cursor page-wide meanwhile. Default `'canvas'`. */
   pointerScope?: 'canvas' | 'window';
+  /**
+   * Diagnostics, off by default and free when off. `true`: log the cursor's per-frame cost
+   * (update ms, rays a frame, frame interval, pointer-sample age) as rolling stats, at most once a
+   * second. `'both'`: that, and the OS cursor stays visible beside the sprite, for filming the lag
+   * between them on a panel. three.js backend (./model `engine: 'three'`, ./splat on Spark).
+   */
+  debug?: boolean | 'both';
+  /** Crosstalk softening of the lifted arrow (runtime ADR-046 Amendment 2 §B.7). Default `'both'`. */
+  soften?: CursorSoftenOption;
 }
 export const CURSOR_OPTION_KEYS: readonly (keyof CursorOptions)[];
 /** `cursor` as ./model and ./splat accept it: null = off; throws on a bad value. */
@@ -152,3 +163,115 @@ export class CursorDepthPlacer {
     nowSec: number,
   ): CursorPlacement;
 }
+
+// ── Crosstalk softening of the lifted cursor (runtime ADR-046 Amendment 2 §B.7) ─────────────
+
+/**
+ * `'both'` (default): edge blur AND opacity easing; `'off'`: neither (the crisp arrow, exactly as
+ * before 1.44); `'alpha'` / `'blur'`: one of them (A/B presets).
+ */
+export type CursorSoftenPreset = 'both' | 'off' | 'alpha' | 'blur';
+/** The tuning knobs, each over the runtime's default (U_CURSOR_SOFTEN_DEFAULT_*). */
+export interface CursorSoftenTuning {
+  /** Which effects; default `'both'`. */
+  mode?: CursorSoftenPreset;
+  /** Panel px of blur per panel px of ghost offset (the views' on-screen split). Default 0.1; >= 0. */
+  blurK?: number;
+  /** Hard ceiling on the blur radius, panel px. Default 8; [0, 8]. */
+  blurMaxPx?: number;
+  /** Blur cap as a fraction of the drawn arrow's height. Default 0.06; [0, 0.5] (0 = off). */
+  blurMaxFrac?: number;
+  /** Opacity at full lift. Default 0.5; [0, 1]. */
+  alphaMin?: number;
+  /** |disparity| (eye baselines) at which the opacity reaches alphaMin. Default 0.03; > 0. */
+  fullD?: number;
+}
+/** `cursor.soften`: a preset, a tuning object, `true` (= default) or `false` (= `'off'`). */
+export type CursorSoftenOption = CursorSoftenPreset | CursorSoftenTuning | boolean;
+/** The resolved parameter set. */
+export interface CursorSoftenParams {
+  blur: boolean;
+  alpha: boolean;
+  blurK: number;
+  blurMaxPx: number;
+  blurMaxFrac: number;
+  alphaMin: number;
+  fullD: number;
+}
+export const CURSOR_SOFTEN_PRESETS: readonly CursorSoftenPreset[];
+export const CURSOR_SOFTEN_DEFAULTS: Readonly<CursorSoftenParams>;
+export const CURSOR_SOFTEN_KEYS: readonly (keyof CursorSoftenTuning)[];
+/** `cursor.soften` resolved over the defaults; throws on a bad value. */
+export function resolveCursorSoften(opt: unknown, who?: string): CursorSoftenParams;
+/**
+ * The runtime's lenient string parse (u_cursor_soften_params_parse), e.g. for URL parameters: a
+ * value that does not parse or is out of range keeps its default. `changed`: any knob was set.
+ */
+export function parseCursorSoften(
+  mode?: string | null,
+  blurK?: string | null,
+  blurMaxPx?: string | null,
+  blurMaxFrac?: string | null,
+  alphaMin?: string | null,
+  fullD?: string | null,
+): { params: CursorSoftenParams; changed: boolean };
+/**
+ * One frame's softening (u_cursor_draw_soften_sized): blur radius (panel px) = blurK × |ghostPx|,
+ * capped at blurMaxPx and blurMaxFrac × `spritePx`; opacity eases 1 → alphaMin by a smoothstep
+ * over |d| up to fullD. (0, 1) on the glass.
+ */
+export function cursorSoften(d: number, ghostPx: number, spritePx?: number, params?: CursorSoftenParams | null): { blurPx: number; alpha: number };
+/** Largest panel-px distance between the hotspot in NEIGHBOURING views (canvas-normalised origins). */
+export function cursorGhostPx(origins: ArrayLike<ArrayLike<number> | null> | null, pxW: number, pxH: number): number;
+/** Canvas-normalised [u, v] (v down) of a point seen from a view, or null when not in front of it. */
+export function cursorProjectToCanvas(view: CursorView | XRView, point: ArrayLike<number>): [number, number] | null;
+/** A placement's softening; `radius` / `aa` in arrow heights; `soft` false = draw the crisp arrow. */
+export interface CursorSoftening {
+  blurPx: number;
+  alpha: number;
+  ghostPx: number;
+  spritePx: number;
+  radius: number;
+  aa: number;
+  soft: boolean;
+}
+/** The softening for a placement drawn with `views` on a `panelW` × `panelH` px canvas, the arrow `heightFraction` of it tall. */
+export function cursorPlacementSoften(
+  placement: CursorPlacement | { active: false } | null,
+  views: ArrayLike<CursorView | XRView>,
+  panelW: number,
+  panelH: number,
+  heightFraction: number,
+  params?: CursorSoftenParams,
+): CursorSoftening;
+/** The runtime's 13-tap blur kernel, `[dx, dy, weight]` in units of the radius. */
+export const CURSOR_SOFTEN_KERNEL: ReadonlyArray<readonly [number, number, number]>;
+/** The arrow's [width, height] in its own units (height 1). */
+export const CURSOR_ARROW_SIZE: readonly [number, number];
+/** The arrow's box padded by `radius` (+ `aa`), arrow units, y down, tip at the origin: [x0, y0, x1, y1]. */
+export function cursorSoftArrowBox(radius: number, aa?: number): [number, number, number, number];
+/** Signed distance to a polygon (negative inside). */
+export function cursorPolygonSd(poly: ReadonlyArray<readonly [number, number]>, x: number, y: number): number;
+/** The softened arrow at (x, y) of arrow units: straight RGB + alpha (before opacity). The shader's reference. */
+export function cursorSoftArrowSample(
+  x: number,
+  y: number,
+  radius: number,
+  aa: number,
+  fill?: readonly number[],
+  outline?: readonly number[],
+  polys?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>,
+): [number, number, number, number];
+/** GLSL defining `vec4 inline3dSoftArrow(vec2 p, float radius, float aa, vec3 fill, vec3 outline)`. */
+export function cursorSoftArrowGLSL(polys?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>): string;
+/** The softened arrow rasterised for a 2D canvas, its tip at (cx, cy), `sizePx` tall: straight-alpha RGBA bytes. */
+export function cursorSoftArrowRaster(
+  cx: number,
+  cy: number,
+  sizePx: number,
+  radius: number,
+  alpha: number,
+  fill?: readonly number[],
+  outline?: readonly number[],
+  polys?: ReadonlyArray<ReadonlyArray<readonly [number, number]>>,
+): { x0: number; y0: number; width: number; height: number; data: Uint8ClampedArray };