@displayxr/inline3d 1.43.1 → 1.45.0

package/CHANGELOG.md

@@ -5,6 +5,135 @@ 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.45.0 — 2026-10-13
+
+### Packaging
+
+- `js/inline3d-cursor-shape.js` (new in this release, imported by `./cursor-depth` and so by
+  `./three`) is now in the published file set. A new unit test fails whenever a published module
+  imports a file the package does not ship.
+
+### Depth cursor: the sprite is the page's CSS cursor — any keyword, and `url()` images (ADR-046 §C, page side)
+
+Touches `./cursor-depth`, `./three` (`DepthCursor`) and the preview tier (`./model`, `./splat`,
+`./call`, `./camera`), all only under `cursor: 'depth'`.
+
+- The lifted cursor was always the arrow, so over a model whose page cursor is `grab` it showed an
+  arrow. It now draws what the browser would show: the page's computed CSS cursor under the pointer.
+  - **Every standard keyword** has a procedural sprite in the arrow's style (white fill, dark
+    outline, the OS cursor's 19 CSS px, its hotspot at its natural point): `pointer`, `grab`,
+    `grabbing`, `move` / `all-scroll`, `text` / `vertical-text`, `crosshair`, `not-allowed` /
+    `no-drop`, `help`, `wait`, `progress`, `copy`, `alias`, `context-menu`, `cell`, every resize
+    cursor (`n/s/e/w/ne/nw/se/sw-resize`, `ns/ew/nesw/nwse-resize`, `col-resize`, `row-resize`),
+    `zoom-in`, `zoom-out`; `auto` / `default` and anything unknown → the arrow.
+  - **`none`** draws nothing and keeps the OS cursor hidden: a page that hides its cursor on purpose
+    stays that way.
+  - **`url(a) x y, url(b), fallback`**: the first url that loads as an image (crossOrigin
+    'anonymous' — same-origin and `data:` always do; cross-origin without CORS falls to the next
+    item), at its natural CSS size capped at 128 px; hotspot = the explicit `x y`, else a `.cur`
+    file's own, else 0 0. Loaded async and cached per URL; the keyword fallback is drawn until it is
+    ready.
+  - All of it softened like the arrow, in the cursor's own material (keyword sprites and images are
+    textures on one soft quad: one shader program, the same 13-tap blur and opacity). No CSS filter,
+    no CSS opacity.
+- **`cursor: { shape }`**: `'auto'` (default, mirror the CSS), `'none'`, or a sprite name
+  (`CURSOR_SHAPES`) to fix it. **`cursor: { shapeFor(hit) }`**: decide per drawn frame
+  (`{ u, v, point, css, cssValue }` → a name, or nothing for `shape`'s answer).
+- **Behaviour change — the CSS hide.** The cursor no longer writes `canvas.style.cursor = 'none'`
+  while it draws: it sets a `data-inline3d-cursor-hidden` attribute (on the canvas, or on `<html>`
+  for `pointerScope: 'window'`, replacing the `inline3d-cursor-hidden` class) plus one injected
+  `cursor: none !important` rule. The page's own cursor value is never touched, so it can be read
+  back (the attribute is lifted for the read and put back in the same task, so nothing paints).
+  Reads happen only on frames that draw the sprite, after pointer moves (at most every 100 ms) and
+  at once on pointerdown / pointerup. A page that checked `style.cursor === 'none'` should check
+  the attribute (or `getComputedStyle(canvas).cursor`).
+- `tools/cursor-shape-capture/run.mjs`: headless per-sprite captures over the lifted model sample
+  (keywords, a `data:` url() image, `none`), hotspot stability and the Shop grab → grabbing → grab
+  sequence, failing on any GL error; the samples take `&shape=`.
+
+### Fixed — `cursor: 'depth'` (PlayCanvas) over a layer on the display rig (#185)
+
+- A layer moved with `handle.setLayerRig(name, 'display')` is drawn by the layer rig's cameras, not
+  the eye camera, so the pick never saw it and the cursor stayed on the glass over it (a round
+  stage, a map tile under a camera-rig photo). The layer rig's post run, and its display run when
+  it is not rounded, now join the eye pick. A ROUNDED display run (a camera rig, gain ≠ 1) gets a
+  second low-res pick pass through the same round views, and each hit becomes the point the photo
+  views show at the same pixels in both eyes, so the placement (unchanged) puts the arrow in front
+  of the stage as the panel shows it. The two passes merge by the nearest point. Same cadence and
+  readback as before (every other frame, asynchronous); the second pass exists only while a layer
+  is on the display rig, and nothing at all without `cursor: 'depth'`.
+
+### Added — a `pc.ShaderMaterial` can take part in the depth pick
+
+- `CURSOR_DEPTH_PICK_GLSL` and `CURSOR_DEPTH_PICK_WGSL` (`./cursor-depth`): `{ declarations, output }`
+  snippets that write the pick id and, under `DEPTH_PICK_PASS`, the pick depth with the engine's own
+  `pickPS` chunk. Since 1.44.0 the pick pass leaves out a ShaderMaterial that does not write the
+  depth target; with these it is hit like any engine material. docs/authoring-inline-3d.md §A cursor
+  that respects depth.
+
+## 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

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 { CursorShape, CursorShapeHit, CursorShapeOption, 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,12 @@ 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;
+  /** The sprite. Default `'auto'`: the page's CSS cursor over the tile (any keyword, url() images, `none`). */
+  shape?: CursorShapeOption;
+  /** Per-frame override while the sprite draws (`point` is null on a pair): a shape name, or nothing for `shape`'s. */
+  shapeFor?: (hit: CursorShapeHit) => CursorShape | 'none' | 'auto' | null | undefined;
 }
 
 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,19 @@ 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;
+  /** The sprite. Default `'auto'`: mirror the page's CSS cursor under the pointer (`grab` → the open hand, …). */
+  shape?: CursorShapeOption;
+  /** Per-frame override while the sprite draws: a shape name, or nothing for `shape`'s answer. */
+  shapeFor?: (hit: CursorShapeHit) => CursorShape | 'none' | 'auto' | null | undefined;
 }
 export const CURSOR_OPTION_KEYS: readonly (keyof CursorOptions)[];
 /** `cursor` as ./model and ./splat accept it: null = off; throws on a bad value. */
@@ -152,3 +167,262 @@ export class CursorDepthPlacer {
     nowSec: number,
   ): CursorPlacement;
 }
+
+// ── The sprite: the page's CSS cursor, mirrored (ADR-046 Amendment 2 §C, page side) ─────────
+
+/** The procedural sprites: one per standard CSS cursor keyword (aliases share one). */
+export type CursorShape =
+  | '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`: `'auto'` (default — the page's computed CSS cursor, url() images included), `'none'`, or a sprite. */
+export type CursorShapeOption = 'auto' | 'none' | CursorShape;
+/** What `shapeFor` is handed each drawn frame. */
+export interface CursorShapeHit {
+  /** Canvas-normalised pointer, v down. */
+  u: number;
+  v: number;
+  /** The nearest content point under the footprint (the views' / world space), null on a pair or a miss. */
+  point: number[] | null;
+  /** What `'auto'` would draw: a sprite name, `'none'` or `'image'` (null unless `shape: 'auto'`). */
+  css: CursorShape | 'none' | 'image' | null;
+  /** The page's computed CSS `cursor` value (null unless `shape: 'auto'`). */
+  cssValue: string | null;
+}
+/** What a cursor draws: nothing, a keyword sprite, or a loaded url() image. */
+export type CursorSprite =
+  | { kind: 'none' }
+  | { kind: 'shape'; name: CursorShape; key: string }
+  | { kind: 'image'; key: string; entry: CursorImageEntry; width: number; height: number; hotspot: [number, number] };
+export interface CursorImageEntry {
+  url: string;
+  state: 'loading' | 'ready' | 'failed';
+  image: HTMLImageElement | null;
+  /** Natural size, CSS px. */
+  width: number;
+  height: number;
+  /** A .cur file's own hotspot, once read. */
+  curHotspot: [number, number] | null;
+}
+export const CURSOR_SHAPES: readonly CursorShape[];
+export const CURSOR_SHAPE_OPTIONS: readonly CursorShapeOption[];
+/** Every CSS cursor keyword the map knows. */
+export const CURSOR_CSS_KEYWORDS: readonly string[];
+/** The data attribute that hides the CSS cursor while the sprite draws (on the canvas; on <html> for pointerScope 'window'). */
+export const CURSOR_HIDDEN_ATTR: string;
+/** The one rule injected for it: `cursor: none !important` on the attribute's element and its descendants. */
+export const CURSOR_HIDDEN_RULE: string;
+/** Pointer moves re-read the CSS cursor at most this often, ms (100); press/release re-read at once. */
+export const CURSOR_CSS_READ_MS: number;
+/** Image cursors larger than this (CSS px) are scaled down to it (128). */
+export const CURSOR_IMAGE_MAX_PX: number;
+/** Texels per sprite unit of the keyword textures (64). */
+export const CURSOR_SHAPE_TEXTURE_PX: number;
+/** One keyword → its sprite, `'none'`, or the arrow for anything unknown. */
+export function cssKeywordToShape(keyword: string): CursorShape | 'none';
+/** A computed CSS `cursor` value's keyword fallback → its sprite (images ignored). */
+export function cssCursorToShape(css: string | null | undefined): CursorShape | 'none';
+/** A computed CSS `cursor` value: its url() images in order (explicit hotspot or null) and the keyword fallback. */
+export function parseCssCursor(css: string | null | undefined): { images: ReadonlyArray<{ url: string; hotspot: [number, number] | null }>; keyword: string };
+/** `shapeFor`'s answer if it names a sprite (or 'none'), else the fixed `shape`, else the CSS one, else the arrow. */
+export function cursorPickShape(shape: CursorShapeOption | undefined, fromShapeFor: unknown, css: string | null | undefined): CursorShape | 'none';
+/** A .cur file's hotspot (the entry `w` px wide, else the first), or null when not a cursor file. */
+export function curFileHotspot(buf: ArrayBuffer | null, w?: number): [number, number] | null;
+/** Cursor images by URL (crossOrigin 'anonymous'), loaded once. */
+export class CursorImageCache {
+  constructor(opts?: { ImageCtor?: unknown; fetchFn?: unknown });
+  get(url: string): CursorImageEntry;
+}
+/** The page-wide cache the cursors share. */
+export const cursorImageCache: CursorImageCache;
+/** What to draw for a computed CSS cursor value: the first READY image (failed → next, loading → the fallback), else the keyword. */
+export function resolveCursorSprite(css: string, images?: Pick<CursorImageCache, 'get'>): CursorSprite;
+export function spriteForName(name: CursorShape | 'none' | string): CursorSprite;
+/** The sprite's area in sprite units (arrow heights; y down, hotspot at the origin). */
+export function cursorSpriteRect(sprite: CursorSprite): [number, number, number, number];
+/** That area padded by `radius` (+ `aa`). */
+export function cursorSpriteBox(sprite: CursorSprite, radius: number, aa?: number): [number, number, number, number];
+/** A sprite's geometry (sprite units, y down, hotspot at the origin). */
+export interface CursorShapeGeometry {
+  readonly name: CursorShape;
+  /** The dark outline: a union of polygons. */
+  readonly parts: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
+  /** Each part inset by 1/19: the white fill. */
+  readonly fill: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
+  /** Dark marks over the fill (the ? of help, the + of copy). */
+  readonly detail: ReadonlyArray<ReadonlyArray<readonly [number, number]>>;
+  readonly box: readonly [number, number, number, number];
+}
+export function cursorShape(name: CursorShape | string): CursorShapeGeometry;
+type CursorPolys = { outline: ReadonlyArray<ReadonlyArray<readonly [number, number]>>; fill: ReadonlyArray<ReadonlyArray<readonly [number, number]>>; detail?: ReadonlyArray<ReadonlyArray<readonly [number, number]>> };
+/** The outline, the fill inset by `d` sprite units (default 1/19), the detail. */
+export function cursorShapePolys(name: CursorShape | string, d?: number): CursorPolys;
+/** The shape's box padded by `radius` (+ `aa`). */
+export function cursorShapeBox(name: CursorShape | string, radius: number, aa?: number): [number, number, number, number];
+/** The softened shape at (x, y) of sprite units (straight RGB + alpha); for the arrow, exactly cursorSoftArrowSample. */
+export function cursorShapeSample(name: CursorShape | string, x: number, y: number, radius: number, aa: number, fill?: readonly number[], outline?: readonly number[], polys?: CursorPolys): [number, number, number, number];
+/** The softened shape rasterised for a 2D canvas, the hotspot at (cx, cy), one sprite unit = `sizePx`. */
+export function cursorShapeRaster(name: CursorShape | string, cx: number, cy: number, sizePx: number, radius: number, alpha: number, fill?: readonly number[], outline?: readonly number[], polys?: CursorPolys): { x0: number; y0: number; width: number; height: number; data: Uint8ClampedArray };
+/** A keyword sprite as a crisp straight-alpha RGBA texture (row 0 = the top) and the sprite-unit rect it covers. */
+export function cursorShapeTexture(name: CursorShape | string): { width: number; height: number; data: Uint8ClampedArray; rect: readonly [number, number, number, number] };
+/** RGBA pixels softened with the same 13-tap kernel and opacity, padded by the radius. */
+export function cursorSoftenPixels(src: ArrayLike<number>, w: number, h: number, radiusPx: number, alpha: number): { pad: number; width: number; height: number; data: Uint8ClampedArray };
+/** The crisp shape drawn with a 2D context (outline dark, fill white, detail dark), the hotspot at (cx, cy). */
+export function drawCursorShape2D(g: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, name: CursorShape | string, cx: number, cy: number, sizePx: number, polys?: CursorPolys, fillStyle?: string, outlineStyle?: string): void;
+/** GLSL defining `vec4 inline3dSoftSprite(sampler2D tex, vec2 p, vec4 rect, float radius)` — every non-arrow sprite, one program. */
+export function cursorSpriteGLSL(): string;
+/** Inject CURSOR_HIDDEN_RULE once; false without a document. */
+export function ensureCursorHiddenRule(doc?: Document): boolean;
+/** The page's computed cursor at `el` with the depth cursor's hide lifted (synchronously) off `holders`; null if unreadable. */
+export function readPageCursor(el: Element, holders: ReadonlyArray<Element | null | undefined>): string | null;
+/** Tracks the page's CSS cursor under the pointer: listeners mark it stale; `value()` re-reads (moves throttled, press/release at once). */
+export class CursorCssReader {
+  constructor(pointer: { canvas: Element; scope: 'canvas' | 'window' }, opts?: { throttleMs?: number });
+  /** The last computed CSS cursor read, or null. */
+  readonly css: string | null;
+  /** Reads performed (diagnostics). */
+  readonly reads: number;
+  throttleMs: number;
+  value(nowMs?: number): string;
+  shape(nowMs?: number): CursorShape | 'none';
+  read(nowMs?: number): string;
+  dispose(): void;
+}
+/** Per-cursor sprite state: the option, `shapeFor`, and a reader only for `'auto'`. */
+export class CursorShapeSelector {
+  constructor(pointer: { canvas: Element; scope: 'canvas' | 'window' }, opts?: { shape?: CursorShapeOption; shapeFor?: ((hit: CursorShapeHit) => unknown) | null; images?: Pick<CursorImageCache, 'get'> });
+  readonly option: CursorShapeOption;
+  readonly reader: CursorCssReader | null;
+  /** The sprite picked last. */
+  readonly sprite: CursorSprite;
+  /** …as a label: a sprite name, 'none' or 'image'. */
+  readonly current: CursorShape | 'none' | 'image';
+  pick(hit: { u: number; v: number; point: number[] | null }, nowMs?: number): CursorSprite;
+  dispose(): void;
+}
+
+// ── 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 };
+
+/** A shader snippet pair for a PlayCanvas `pc.ShaderMaterial`: `declarations` above `main`, `output` inside `#ifdef PICK_PASS`. */
+export interface CursorDepthPickSnippet {
+  readonly declarations: string;
+  readonly output: string;
+}
+/**
+ * PlayCanvas ShaderMaterial opt-in to `cursor: 'depth'`'s pick (GLSL): writes the pick id to
+ * `pcFragColor0` and, under `DEPTH_PICK_PASS`, the pick depth to `pcFragColor1` (the engine's `pickPS`).
+ */
+export const CURSOR_DEPTH_PICK_GLSL: CursorDepthPickSnippet;
+/** The WGSL twin of CURSOR_DEPTH_PICK_GLSL: writes `output.color` / `output.color1`. */
+export const CURSOR_DEPTH_PICK_WGSL: CursorDepthPickSnippet;