@displayxr/inline3d 1.46.0 → 1.47.0

package/js/inline3d-viewer.js

@@ -73,6 +73,7 @@ import {
   mismatchWarning,
 } from './inline3d-buffer-limit.js';
 import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
+import { parseClearColor } from './inline3d-splat-shared.js';
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
@@ -269,6 +270,10 @@ export class SceneViewer {
    * @param {number} [opts.feather=0]  edge fade in buffer px (needs ./three's EdgeFeather).
    * @param {number[]} [opts.pitchLimit=[-60,60]]  degrees; stops the viewer rolling under the
    *        subject, which reads as broken rather than as a feature.
+   * @param {number[]|string} [opts.clearColor]  OPT-IN eye clear, `[r,g,b,a]` in 0..1 or a CSS
+   *        colour. Unset: the transparent clear (0,0,0,0), exactly as before. An opaque clear
+   *        avoids stale / black pixels on the weave (web#198); match the page colour behind the
+   *        canvas.
    */
   constructor(THREE, canvas, opts = {}) {
     const {
@@ -307,11 +312,19 @@ export class SceneViewer {
     this.logTag = opts.logTag || '[inline3d/viewer]';
     this.pitchLimit = pitchLimit;
     this.idleSpin = idleSpin;
+    // Opt-in (null = off, and then nothing below differs from before it existed).
+    this.clearColor = parseClearColor(opts.clearColor, this.logTag);
 
     // alpha + a zero-alpha clear so the tile can dissolve into the page rather than ending at
     // a hard rectangle. An opaque scene.background would defeat both this and the feather.
     this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
     this.renderer.setClearColor(0x000000, 0);
+    // clearColor (opt-in) replaces that clear. three reads a hex as sRGB, as a CSS colour is.
+    if (this.clearColor) {
+      const [r, g, b, a] = this.clearColor;
+      const hex = (Math.round(r * 255) << 16) | (Math.round(g * 255) << 8) | Math.round(b * 255);
+      this.renderer.setClearColor(hex, a);
+    }
     // MUST be 1. layer.getViewport() reports BACKING-STORE px, but three.js multiplies whatever
     // you pass setViewport()/setScissor() by the renderer's pixelRatio — so any other value
     // silently scales every eye viewport (at dpr 2 the left eye covers the whole canvas). It

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,6 +1286,9 @@ 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);
       },
       /**
@@ -2367,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
@@ -2433,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);
@@ -3430,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) {
@@ -3498,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.46.0",
+  "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`).

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 },