@displayxr/inline3d 1.44.0 → 1.45.1

package/CHANGELOG.md

@@ -5,6 +5,86 @@ 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.1 — 2026-10-13
+
+### Fixed — `cursor: 'depth'` showed up under a finger (touch)
+
+- On a touch device, dragging a finger over a scene drew the 3D cursor, though the browser shows no
+  cursor there. Since 1.44.0 the pointer took every `pointermove` / `pointerrawupdate` whatever
+  its `pointerType`. Now only a **mouse** or a **hovering pen** places the cursor. A touch or a pen
+  in contact clears it, including a tap that never moves (so no stale mouse hover stays up), and
+  the CSS cursor is never hidden for them. This covers every backend (three.js `./model`,
+  PlayCanvas `./model` / `./splat`, the `./call` / `./camera` pair cursor). They all share
+  `CursorPointer`.
+- New `cursorPointerHovers(e)` in `./cursor-depth`. An event with no `pointerType` (synthetic)
+  counts as a mouse, as before.
+
+## 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`,

package/camera.d.ts

@@ -12,7 +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';
+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';
@@ -196,6 +196,10 @@ export interface PairCursorOptions {
   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

@@ -96,6 +96,10 @@ export interface CursorOptions {
   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. */
@@ -164,6 +168,140 @@ export class CursorDepthPlacer {
   ): 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) ─────────────
 
 /**
@@ -275,3 +413,16 @@ export function cursorSoftArrowRaster(
   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;