@displayxr/inline3d 1.45.1 → 1.47.0

package/js/inline3d.js

@@ -36,6 +36,20 @@ import { setSessionViewerEase } from './inline3d-viewer-ease.js';
 export { ViewerEase, resolveViewerEaseOption, frameTrackingState, VIEWER_EASE_DEFAULT_MS } from './inline3d-viewer-ease.js';
 export { DISPLAY_METRICS_DEFAULTS, displayMetricsFrom } from './inline3d-display-metrics.js';
 import { displayMetricsFrom } from './inline3d-display-metrics.js';
+// The depth budget: pure measurements (how deep is this scene, in % of the tile width) and the
+// one-time rig warnings. Never a behaviour change — see ./inline3d-depth-budget.js.
+export {
+  DEPTH_EYE_SEPARATION_M,
+  DEPTH_DEFAULT_VIEWER_M,
+  disparityPct,
+  cameraRigDisparityPct,
+  depthBudgetFromBounds,
+  comfortZone,
+  comfortDepthFactor,
+  cameraRigComfortFactor,
+  withheldReasonHint,
+} from './inline3d-depth-budget.js';
+import { warnViewRigOnce, withheldReasonHint } from './inline3d-depth-budget.js';
 
 // The eased 2D<->3D transition. A pure state machine (no DOM, no WebXR) ported from the native
 // `dxr::ModeSwitch`, so the browser eases the disparity around a mode switch the same way — and in
@@ -1272,8 +1286,47 @@ class Inline3D {
       },
       setViewRig: (rig) => {
         win.viewRig = rig || null;
+        // One-time console warnings for a rig that looks like a mistake (convergence at infinity,
+        // factors > 1, a FOV in degrees). Read only: the rig goes out exactly as given.
+        if (rig) warnViewRigOnce(win.rigWarned, rig);
         return this._pushViewRig(win);
       },
+      /**
+       * Runtime ADR-046 Amendment 4: the depth under the pointer for THIS window, forwarded to its
+       * live layer's `setCursorDepth` — `{ disparityPx, u, v }` (device px between the outermost
+       * views, < 0 in front, RAW content disparity; u/v element-normalised, v down; no
+       * `disparityPx` = nothing 3D there), or nothing / null to withdraw. Returns whether a live
+       * layer took it. The depth cursors call this for you under `cursor: 'depth'`.
+       */
+      setCursorDepth: (depth) => {
+        const layer = win.layer;
+        if (!layer || typeof layer.setCursorDepth !== 'function') return false;
+        try {
+          if (depth) layer.setCursorDepth(depth);
+          else layer.setCursorDepth();
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      /**
+       * "runtime" when the browser AND the runtime draw this window's cursor (the page then supplies
+       * only the depth, setCursorDepth); "none" otherwise — including no live layer yet, so ask
+       * again later. Never rejects.
+       * @returns {Promise<'runtime'|'none'>}
+       */
+      getCursorDepthSupport: () => {
+        const layer = win.layer;
+        if (!layer || typeof layer.getCursorDepthSupport !== 'function') return Promise.resolve('none');
+        try {
+          return Promise.resolve(layer.getCursorDepthSupport()).then(
+            (s) => (s === 'runtime' ? 'runtime' : 'none'),
+            () => 'none',
+          );
+        } catch {
+          return Promise.resolve('none');
+        }
+      },
       /**
        * The panel this window is weaving on: physical size in metres, pixel size, and the view
        * scale the runtime RECOMMENDS. Resolves null on a machine with no glasses-free display.
@@ -2331,6 +2384,10 @@ class Inline3D {
       // and rebuilds layers behind the page's back: a tile that scrolls away and back would
       // otherwise silently revert to the default display rig mid-scene.
       viewRig: opts.viewRig || null,
+      // Which one-time rig warnings this window has given (setViewRig / opts.viewRig), and
+      // whether its 'withheld' reason has been logged. Diagnostics only.
+      rigWarned: new Set(),
+      warnedWithheld: false,
       // The automatic 1-view collapse (the latch itself is manager-wide — the mode is the
       // display's, not this window's). `stereoSaved` records the factors in force when the panel
       // went flat, for diagnostics; the restore just re-pushes `viewRig`, which the flattening
@@ -2397,6 +2454,7 @@ class Inline3D {
     win.fwPromise = new Promise((resolve) => {
       win.fwResolve = resolve;
     });
+    if (win.viewRig) warnViewRigOnce(win.rigWarned, win.viewRig); // as handle.setViewRig: read only
     this._windows.set(canvas, win);
     if (this._lazy && this._observer) {
       this._observer.observe(win.observeEl);
@@ -3394,7 +3452,19 @@ class Inline3D {
    * the browser's report; a confirmed `woven: false` is a capped 'withheld' level, which can still
    * recover, so it is NOT a terminal "will not weave" and leaves rewoven() usable.
    */
+  /**
+   * The browser REPORTED this layer withheld long enough to settle a firstWoven / rewoven on it:
+   * say why, once per window (the reason is otherwise only in the settled result). A console line,
+   * nothing else — the window keeps doing exactly what it did.
+   */
+  _noteWithheld(win, woven, reason, confirmed) {
+    if (woven || !confirmed || win.warnedWithheld || !reason || reason === 'pending' || reason === 'hold-capped') return;
+    win.warnedWithheld = true;
+    console.warn(`[inline3d] the browser withheld this canvas from the weave (${reason}): ${withheldReasonHint(reason)}.`, win.canvas);
+  }
+
   _settleFirstWoven(win, woven, reason, confirmed = false) {
+    this._noteWithheld(win, woven, reason, confirmed);
     // Every "will not weave" path lands here, so a pending rewoven() is released with it, and a
     // later one answers at once (firstWoven may have settled woven:true long before).
     if (!woven && !confirmed) {
@@ -3462,6 +3532,7 @@ class Inline3D {
   _settleRewoven(win, woven, reason, confirmed = false) {
     const rw = win.rw;
     if (!rw) return;
+    this._noteWithheld(win, woven, reason, confirmed);
     win.rw = null;
     rw.resolve(Object.freeze({ woven, confirmed, reason, ms: Math.round(nowMs() - rw.calledAt) }));
   }

package/llms.txt

@@ -0,0 +1,21 @@
+# @displayxr/inline3d — DisplayXR inline-3D web SDK
+
+> Glasses-free 3D for web pages on a DisplayXR spatial display: you render one image per eye into a
+> canvas, the DisplayXR Browser weaves them for the panel; an ordinary browser shows the page in 2D.
+
+Read first: docs/making-3d-look-right.md — nine depth and comfort rules from real panels
+(keep the viewers' object placement and frame the first view, lay flat arrangements back into
+depth, keep moving things' forward swing small, fixed convergence and no near geometry in worlds,
+low contrast behind the subject, text as HTML near the glass, no coplanar surfaces, no sub-pixel
+detail, a cover that always comes off). The SDK's defaults do the rest.
+
+## Samples (they show the API, not a look to copy)
+- samples/model/, samples/splat/, samples/hello-cube/, samples/camera-rig/, samples/display-modes/
+
+## Reference
+- docs/authoring-inline-3d.md — every API, both view rigs, comfort maths
+- docs/woven-canvas-rules.md — what the browser does to a woven canvas; CSS, remount and cover rules
+- docs/porting-three-js-apps.md — moving an existing three.js app over
+- docs/authoring-motion-and-effects.md, docs/splat-effects.md — motion, reveals, depth envelopes
+- index.d.ts, three.d.ts, viewer.d.ts, model.d.ts, splat.d.ts — the public API with JSDoc
+- CHANGELOG.md — what changed per release

package/model.d.ts

@@ -30,6 +30,33 @@ export interface ModelOptions {
   margin?: number;
   /** Backstop on total depth, in display heights (default 4.0). Rarely binds. */
   depthLimit?: number;
+  /**
+   * OPT-IN eye clear: `[r, g, b, a]` in 0..1 (alpha defaults to 1) or a CSS colour string (`#hex`,
+   * `rgb()`/`rgba()`, `transparent`, or any colour the browser parses). Unset: the transparent
+   * clear, exactly as before. An OPAQUE clear is recommended: where the weave reads an alpha-0
+   * pixel it can show stale or black pixels (web#198). Make the page colour behind the canvas
+   * match, so the 2D fallback and any feathered edge look the same. Unreadable → one warning,
+   * the default clear stays.
+   */
+  clearColor?: [number, number, number] | [number, number, number, number] | string;
+  /**
+   * OPT-IN comfort depth (display rig only). `'auto'` (the Shibata zone of comfort) or
+   * `{ zone: 'shibata' | 'percival' | <diopters> }`. The SDK measures the framed subject's depth
+   * (tile heights in front of / behind the glass), the canvas's physical height
+   * (`displayMetrics()`) and the display's NOMINAL viewer distance (`getDisplayInfo()`, 0.6 m when
+   * it reports none — never the live head distance), and multiplies the display rig's `ipdFactor`
+   * and `parallaxFactor` (together) by `comfortDepthFactor()` of those, on top of
+   * `setStereo`'s values. It ONLY EVER LOWERS DEPTH (the factor is ≤ 1), because the same depth in
+   * tile heights carries more vergence load on a small or close device (a tablet at 0.4 m) than on
+   * a laptop at 0.6 m: where the subject already fits, nothing changes.
+   *
+   * Measured when the subject is first framed, when the canvas resizes and when the display
+   * reports a change — NOT on zoom or orbit (those are framing choices the developer owns; the box
+   * is the framed one at zoom 1), and not per frame. Read the factor in force from `depthFactor`.
+   * Ignored, with one console warning, on a camera rig or under `controls: 'page'`. Anything else
+   * throws at the call. Unset: nothing is measured or declared — the tile is exactly as before.
+   */
+  depth?: 'auto' | { zone?: 'shibata' | 'percival' | number };
   /**
    * Fit the horizontal against the box's DIAGONAL (width and depth) rather than width alone,
    * so a long subject still fits once the turntable turns it (default true).
@@ -203,6 +230,32 @@ export interface ModelHandle {
   /** Resolves once the model has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<ModelHandle>;
 
+  /**
+   * Live stereo strength — a depth slider, mirroring `SplatHandle.setStereo`. On the display rig
+   * (the default) the values are RELATIVE: 1 = what the display shows by construction, below 1 a
+   * comfort dial, 0 flat (above 1 exaggerates; sent as given, with a one-time warning). A key given
+   * replaces, a key set to `null` returns to 1, `setStereo(null)` clears both. `ipdScale` /
+   * `parallaxScale` are accepted too (a model's own values are 1, so they agree). Sticky; applied
+   * from the next frame with no cut (pose and framing stay). Re-declares the display rig
+   * explicitly (`handle.viewRig`); nothing is declared before the first call. Under
+   * `controls: 'page'` (PlayCanvas) the page's camera rig takes them, ABSOLUTE.
+   */
+  setStereo(opts: { ipdFactor?: number | null; parallaxFactor?: number | null; ipdScale?: number | null; parallaxScale?: number | null } | null): ModelHandle;
+  /** The rig's stereo in force (read back; `setStereo` writes it). Null until the backend has loaded. */
+  readonly rig: {
+    readonly type: 'display' | 'camera';
+    readonly ipdFactor: number;
+    readonly parallaxFactor: number;
+    readonly stereoDefault: { readonly ipdFactor: number; readonly parallaxFactor: number };
+  } | null;
+  /**
+   * The `depth` option's comfort factor in force, in (0, 1]: what the display rig's ipdFactor and
+   * parallaxFactor are multiplied by (under `setStereo`'s values). 1 without the option, before
+   * the first measurement, and on a rig it does not apply to.
+   */
+  readonly depthFactor: number;
+  /** The view-rig descriptor last declared by `setStereo` (or `controls: 'page'`), if any. */
+  readonly viewRig?: object;
   /** Throws on `controls: 'page'`. */
   setPose(pose?: OrbitPose): void;
   /** Throws on `controls: 'page'`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.45.1",
+  "version": "1.47.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -19,6 +19,10 @@
       "types": "./cursor-depth.d.ts",
       "import": "./js/inline3d-cursor-depth.js"
     },
+    "./depth": {
+      "types": "./depth.d.ts",
+      "import": "./js/inline3d-depth-budget.js"
+    },
     "./viewer": {
       "types": "./viewer.d.ts",
       "import": "./js/inline3d-viewer.js"
@@ -67,9 +71,13 @@
     "./dist/*.js"
   ],
   "files": [
+    "llms.txt",
+    "docs/making-3d-look-right.md",
+    "docs/woven-canvas-rules.md",
     "js/inline3d.js",
     "js/inline3d-undock.js",
     "js/inline3d-display-metrics.js",
+    "js/inline3d-depth-budget.js",
     "js/inline3d-mode-switch.js",
     "js/inline3d-buffer-limit.js",
     "js/inline3d-viewer-ease.js",
@@ -111,6 +119,7 @@
     "dist/",
     "index.d.ts",
     "three.d.ts",
+    "depth.d.ts",
     "cursor-depth.d.ts",
     "viewer.d.ts",
     "splat.d.ts",

package/splat.d.ts

@@ -409,6 +409,33 @@ export interface SplatOptions {
   margin?: number;
   /** Backstop on total depth, in display heights (default 4.0). Rarely binds. */
   depthLimit?: number;
+  /**
+   * OPT-IN eye clear: `[r, g, b, a]` in 0..1 (alpha defaults to 1) or a CSS colour string (`#hex`,
+   * `rgb()`/`rgba()`, `transparent`, or any colour the browser parses). Unset: the transparent
+   * clear, exactly as before. An OPAQUE clear is recommended: where the weave reads an alpha-0
+   * pixel it can show stale or black pixels (web#198). Make the page colour behind the canvas
+   * match, so the 2D fallback and any feathered edge look the same. Unreadable → one warning,
+   * the default clear stays.
+   */
+  clearColor?: [number, number, number] | [number, number, number, number] | string;
+  /**
+   * OPT-IN comfort depth (display rig only). `'auto'` (the Shibata zone of comfort) or
+   * `{ zone: 'shibata' | 'percival' | <diopters> }`. The SDK measures the framed subject's depth
+   * (tile heights in front of / behind the glass), the canvas's physical height
+   * (`displayMetrics()`) and the display's NOMINAL viewer distance (`getDisplayInfo()`, 0.6 m when
+   * it reports none — never the live head distance), and multiplies the display rig's `ipdFactor`
+   * and `parallaxFactor` (together) by `comfortDepthFactor()` of those, on top of
+   * `setStereo`'s values (Spark has no setStereo: the factor is the rig's whole ipdFactor / parallaxFactor). It ONLY EVER LOWERS DEPTH (the factor is ≤ 1), because the same depth in
+   * tile heights carries more vergence load on a small or close device (a tablet at 0.4 m) than on
+   * a laptop at 0.6 m: where the subject already fits, nothing changes.
+   *
+   * Measured when the subject is first framed, when the canvas resizes and when the display
+   * reports a change — NOT on zoom or orbit (those are framing choices the developer owns; the box
+   * is the framed one at zoom 1), and not per frame. Read the factor in force from `depthFactor`.
+   * Ignored, with one console warning, on a camera rig (an asset with a capture camera, `rig: 'camera'`) or under `controls: 'page'`. Anything else
+   * throws at the call. Unset: nothing is measured or declared — the tile is exactly as before.
+   */
+  depth?: 'auto' | { zone?: 'shibata' | 'percival' | number };
   /**
    * Fit the horizontal against the box's DIAGONAL (width and depth) rather than width alone,
    * so a long subject still fits once the turntable turns it (default true).
@@ -1109,6 +1136,12 @@ export interface SplatHandle {
    */
   warmEntity(entity: unknown, opts?: { timeoutMs?: number }): Promise<number>;
   setStereo(opts: SplatStereoOptions | null): SplatHandle;
+  /**
+   * The `depth` option's comfort factor in force, in (0, 1]: what the display rig's ipdFactor and
+   * parallaxFactor are multiplied by (under `setStereo`'s values). 1 without the option, before
+   * the first measurement, and on a rig it does not apply to.
+   */
+  readonly depthFactor: number;
   /** This tile in physical units — the core `TileHandle.displayMetrics()`, on the splat handle. Never rejects. */
   displayMetrics(): Promise<DisplayMetrics>;
   /**

package/three.d.ts

@@ -3,6 +3,7 @@
 // bundles three.js (it is an optional peer dependency).
 
 import type { XRViewRigInit } from './index.js';
+export { disparityPct, cameraRigDisparityPct, depthBudgetFromBounds, comfortZone, comfortDepthFactor, cameraRigComfortFactor } from './depth.js';
 
 /**
  * A reusable three.js camera driven directly by an XRView's matrices. Construct once with your
@@ -88,8 +89,12 @@ export interface DisplayRigOptions {
  * (so a camera parented under a dolly still reports world space) unless `attach` is set, which
  * emits identity instead.
  *
- * Comfort rule, from the runtime: `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1`
- * (N ≈ 0.5 m nominal viewing distance). Nothing here enforces it; the runtime clamps.
+ * Comfort rule: `ipdFactor × metersToVirtual × convergenceDiopters × N <= 1` (N = the nominal
+ * viewer distance the display reports, 0.6 m on a desktop panel). Nothing enforces it: the
+ * runtime applies an app-declared camera rig's gain as given (XR_DXR_view_rig §3) and clamps only
+ * values outside a field's sanity range. `convergence` 0 / unset (infinity: the whole scene in
+ * front of the glass) logs one console warning per page; the descriptor is built as asked.
+ * {@link cameraRigDisparityPct} measures the disparity a rig gives.
  *
  * @param THREE your imported three.js module namespace.
  * @param camera a `THREE.PerspectiveCamera` (`.fov` degrees, `.matrixWorld`).
@@ -143,6 +148,7 @@ export class EdgeFeather {
   ): void;
 }
 
+import type { CursorRuntimeLink } from './cursor-depth.js';
 import type { CursorAnchorMode, CursorPlacement, CursorShape, CursorShapeHit, CursorShapeOption, CursorSoftenOption, CursorSoftenParams, CursorSoftening, CursorView } from './cursor-depth.js';
 
 /** One second of `debug` stats: each figure as `{ mean, p95, max, n }`. */
@@ -234,8 +240,17 @@ export class DepthCursor {
   readonly softening: CursorSoftening | null;
   /** The sprite drawn last: a name, 'none' or 'image'. */
   readonly shape: CursorShape | 'none' | 'image';
-  /** Place the sprite for this frame — call with the views you are about to render, before rendering. */
-  update(views: ArrayLike<XRView | CursorView>, nowMs?: number): CursorPlacement | { active: false };
+  /** The runtime-drawn cursor link (runtime ADR-046 Amendment 4). */
+  readonly runtime: CursorRuntimeLink;
+  /** The layer this canvas weaves through, as last passed to `update(views, { layer })`. */
+  layer: unknown;
+  /**
+   * Place the sprite for this frame — call with the views you are about to render, before rendering.
+   * Pass `{ layer }` (addScene's second callback argument): where it says "runtime" (ADR-046
+   * Amendment 4) the depth goes to the layer and the browser's own cursor is lifted by the runtime;
+   * no sprite is drawn. A number is the time in ms, as before.
+   */
+  update(views: ArrayLike<XRView | CursorView> | null, opts?: number | { nowMs?: number; layer?: unknown }): CursorPlacement | { active: false; runtime?: boolean };
   /** Set the pointer directly (canvas-normalised, v down), or null — for scripted input. */
   setPointer(u: number | null, v?: number): void;
   /** Remove listeners, restore the CSS cursor, free the sprite's GPU resources. */

package/viewer.d.ts

@@ -48,6 +48,15 @@ export interface SceneViewerOptions {
    * `createInline3D({ viewerEase })`, else on. `false` restores the snap.
    */
   viewerEase?: ViewerEaseOption;
+  /**
+   * OPT-IN eye clear: `[r, g, b, a]` in 0..1 (alpha defaults to 1) or a CSS colour string (`#hex`,
+   * `rgb()`/`rgba()`, `transparent`, or any colour the browser parses). Unset: the transparent
+   * clear, exactly as before. An OPAQUE clear is recommended: where the weave reads an alpha-0
+   * pixel it can show stale or black pixels (web#198). Make the page colour behind the canvas
+   * match, so the 2D fallback and any feathered edge look the same. Unreadable → one warning,
+   * the default clear stays.
+   */
+  clearColor?: [number, number, number] | [number, number, number, number] | string;
 }
 
 export interface OrbitPose {
@@ -117,6 +126,8 @@ export declare class SceneViewer {
    */
   readonly effectiveRenderScale: number;
 
+  /** The `clearColor` option, parsed (`[r,g,b,a]`), or null = the transparent clear. */
+  readonly clearColor: number[] | null;
   /** Centre the subject on the zero-disparity plane and scale it to the tile. */
   fitTo(
     center: number[] | { x: number; y: number; z: number },