@displayxr/inline3d 1.46.0 → 1.47.0

package/CHANGELOG.md

@@ -5,6 +5,81 @@ 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.47.0 — 2026-10-29
+
+The look-right release: a short guide for people and coding agents (`docs/making-3d-look-right.md`,
+`llms.txt`), depth measurements and comfort-zone helpers, and opt-in `clearColor`, `setStereo` on
+`./model` and `depth: 'auto'`. Every addition is opt-in: without the new options a page renders
+exactly as on 1.46.0; the only default change is a few one-time console warnings.
+
+### Comfort depth: zone-of-comfort helpers and an opt-in `depth` option
+
+Touches the core (`.`: new pure exports), `./three` and `./depth` (the same pure exports), and the
+preview tier (`./model`, `./splat`: one new opt-in option, one read-only handle field). Without
+`depth`, every page renders exactly as before: no rig is declared that was not, nothing is measured.
+
+- **`comfortZone({ viewerM = 0.6, zone = 'shibata' })`** → `{ zone, viewerM, frontD, behindD,
+  frontMm, behindMm }`: the vergence–accommodation comfort zone at a viewing distance, in diopters
+  and on-screen mm. `'shibata'` (Shibata et al. 2011: ≈ 0.57 D in front / 0.63 D behind at 0.6 m;
+  behind unbounded once the far limit passes infinity), `'percival'` (±1/3 D), or a number.
+- **`comfortDepthFactor({ frontH, backH, tileHeightM, viewerM, zone })`** → the largest `k ≤ 1` that
+  puts a display-rig subject (depth in tile heights) inside the zone, from the exact geometry at
+  real proportions. Only ever lowers depth; 1 on missing / invalid input.
+- **`cameraRigComfortFactor({ zNear, zFar, convergence | convergenceDiopters, verticalFov, aspect,
+  tileHeightM, viewerM, zone, ipdFactor, metersToVirtual })`** → the multiplier on a camera rig's
+  eye separation that puts its nearest / farthest points at the zone's edge. A measurement, **no
+  cap**: a camera rig's ipdFactor 1 is only physical in metre-scale worlds, so this may be well
+  above 1. Infinity with nothing off the plane, NaN on bad input. No warning is added for camera
+  factors above 1.
+- **`depth: 'auto' | { zone }`** on `addModel` (both engines) and `addSplat` (Spark and
+  PlayCanvas), display rig only: the framed subject's depth (zoom 1, no orbit), the canvas's
+  physical height (`displayMetrics()`) and the display's NOMINAL viewer distance (0.6 m when it
+  reports none) give `k = comfortDepthFactor(…)`, applied to the display rig's `ipdFactor` and
+  `parallaxFactor` together, multiplied with `setStereo`'s values (Spark, which has no setStereo:
+  the whole factor). Re-measured on first framing, a canvas resize, the first weave and a display
+  event; never on zoom, orbit or per frame; re-declared only when k changes. Ignored with one
+  warning on a camera rig / `controls: 'page'`; an invalid value throws at the call.
+  `handle.depthFactor` reads the factor in force (1 without the option).
+
+### Making 3D look right: depth measurements, opt-in helpers and one-time warnings
+
+Touches the core (`.`: new pure exports, console warnings only), `./three` (re-exports, one
+warning), the new `./depth` subpath, and the preview tier (`./viewer`, `./model`, `./splat`), all
+opt-in. **Nothing clamps, refuses or overrides what a page asks for**: without the new options
+every page renders exactly as on 1.46.0; the only default change is the console warnings below.
+
+- **Depth measurements** (`./depth`, also on the root; the pure helpers on `./three`):
+  `disparityPct({ depthH, aspect, viewerM, heightM, ipdFactor })` (display rig: `e·z/(V∓z)` over
+  the tile width, the small-depth limit without `heightM`),
+  `cameraRigDisparityPct({ z, convergence, ipdFactor, metersToVirtual, verticalFov, aspect })`
+  (`100·b·(1/D − 1/z)/(2·tan(fov/2)·aspect)`, + behind, − in front), and `depthBudgetFromBounds`
+  (a `getSubjectBounds()` box → tile heights and % of the tile width). Pure; for a raw `addScene`
+  page or an agent checking its numbers. No budget tiers are built in: depth ranges measured on a
+  panel are in `docs/authoring-inline-3d.md`, as reference points.
+- **`clearColor`** on `SceneViewer` / `addModel` / `addSplat` (three and PlayCanvas):
+  `[r, g, b, a]` in 0..1 or a CSS colour. Unset = the transparent clear, as before. An opaque clear
+  avoids the stale / black pixels the weave can show where it reads alpha 0 (web#198); match the
+  page colour behind the canvas.
+- **`ModelHandle.setStereo({ ipdFactor, parallaxFactor } | null)`** (both engines), mirroring
+  `SplatHandle.setStereo`: a depth slider. RELATIVE on the display rig (1 = by construction), sticky,
+  `null` restores; `ipdScale` / `parallaxScale` accepted. Re-declares the display rig explicitly
+  from the first call (nothing is declared before it). `handle.rig` reads the values in force;
+  under `controls: 'page'` the page's camera rig takes them, absolute.
+- **One-time console warnings** (`[inline3d]`, once per handle, the rig still sent as given): a
+  camera rig with `convergenceDiopters` 0 / unset ("convergence at infinity puts the whole scene in
+  front of the glass …"; also once per page from `cameraRigFromCamera` / `cameraRigFromPose` at
+  convergence 0, not repeated by `setViewRig` for that descriptor), a display rig with
+  `ipdFactor` or `parallaxFactor` above 1, a camera rig whose `verticalFov` is above π (degrees).
+  And a layer the browser keeps `'withheld'` until `firstWoven` / `rewoven()` settles on it now
+  logs its `withheldReason` once, with a hint (`cross-pass:*` / `no-quad`: a `filter`,
+  `opacity < 1`, `mask`, `clip-path`, `mix-blend-mode` or `backdrop-filter` on the canvas or an
+  ancestor). A transient withheld (a move, a resize) says nothing. `withheldReasonHint` is exported.
+- **Docs corrected**: the camera-rig comfort note said N ≈ 0.5 m and "the runtime clamps". The
+  nominal viewer is 0.6 m on a desktop panel, and the runtime does NOT comfort-clamp an
+  app-declared rig (XR_DXR_view_rig §3); it clamps only values outside a field's sanity range.
+- Internal: `validateSetStereo` moved to `js/inline3d-splat-shared.js` (still exported from the
+  PlayCanvas splat module); new `js/inline3d-depth-budget.js` is in the published file set.
+
 ## 1.46.0 — 2026-10-14
 
 ### Depth cursor: when the runtime draws the web cursor, hand it the depth (runtime ADR-046 Amendment 4)

package/README.md

@@ -11,6 +11,9 @@ live demos.
 them in 3D; in any other browser the pages render as a normal 2D fallback, so they're safe to view
 anywhere.
 
+> **New here, or an AI coding agent? Read [Depth and comfort on a 3D display](docs/making-3d-look-right.md)
+> first:** nine rules from real panels; the SDK's defaults do the rest.
+
 ## Install
 
 The SDK is published as **[`@displayxr/inline3d`](https://www.npmjs.com/package/@displayxr/inline3d)**

package/THIRD_PARTY_NOTICES.md

@@ -107,6 +107,6 @@ package.
 | Asset | Used by | Source | Credit and licence |
 |---|---|---|---|
 | Damaged Helmet (`DamagedHelmet.glb`) | `samples/model/` (tiles A and B), loaded at run time, not vendored | [KhronosGroup/glTF-Sample-Assets](https://github.com/KhronosGroup/glTF-Sample-Assets/tree/c6a6bd13ab2b3c685c7903d03561b8a9392f38b8/Models/DamagedHelmet) at commit `c6a6bd13ab2b3c685c7903d03561b8a9392f38b8`, via jsDelivr, unmodified | © 2018 ctxwing (rebuild and conversion to glTF 2.0), [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/legalcode). Earlier version of the model ("Battle Damaged Sci-fi Helmet") © 2016 theblueturtle_, [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/legalcode). As stated in the asset's `README.md` and `LICENSE.md`. |
-| Duck, Draco variant (`samples/model/assets/glTF-Draco/`) | `samples/model/` (tile C) | Khronos glTF-Sample-Assets | © Sony, [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). |
+| Duck, Draco variant (`samples/model/assets/glTF-Draco/`); glTF-Binary variant (`samples/starter-model/assets/Duck.glb`, glTF-Sample-Assets commit `c6a6bd13ab2b3c685c7903d03561b8a9392f38b8`, unmodified) | `samples/model/` (tile C), `samples/starter-model/` | Khronos glTF-Sample-Assets | © Sony, [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). |
 | Butterfly splat (`samples/splat/assets/butterfly.sog`) | `samples/splat/`, `samples/model/` (tile B) | [Spark](https://sparkjs.dev/) `assets/splats/butterfly.spz`, converted to SOG with PlayCanvas splat-transform (177,132 gaussians, 3 SH bands kept) | Butterfly splat © World Labs (from Spark, sparkjs.dev), used with permission; converted to SOG. |
 | Draco decoder (`vendor/draco/`) | `samples/model/` | three.js `examples/jsm/libs/draco/` | © The Draco Authors, Apache-2.0. |

package/depth.d.ts

@@ -0,0 +1,184 @@
+// Type definitions for @displayxr/inline3d/depth — depth measurements (also re-exported by the
+// root entry and, minus the warning helpers, by ./three).
+//
+// Measurements and pure helpers only: nothing here changes a pixel, clamps a rig or refuses a
+// value (the opt-in `depth` option of ./model and ./splat is what applies comfortDepthFactor). The units are RELATIVE — disparity as % of the TILE's width, or depth in TILE HEIGHTS on
+// a display rig — so they hold on any panel. Depth ranges measured on a panel are in
+// docs/authoring-inline-3d.md, as reference points.
+
+/** The eye separation every estimate assumes, metres (0.063). No browser surface reports a real one. */
+export const DEPTH_EYE_SEPARATION_M: number;
+/** The viewer distance used when the display reports no nominal viewer, metres (0.6, a desktop panel). */
+export const DEPTH_DEFAULT_VIEWER_M: number;
+
+/** What a depth report measured against. */
+export interface DepthReportBasis {
+  rig: 'display';
+  /** The tile's width / height. */
+  aspect: number;
+  /** Nominal viewer distance used, metres. */
+  viewerM: number;
+  /** The tile's physical height, metres, or null (then the small-depth formula, which ignores it). */
+  heightM: number | null;
+  /** The display rig's ipdFactor in force (disparity scales with it). */
+  ipdFactor: number;
+  eyeSeparationM: number;
+}
+
+/**
+ * How deep a display-rig subject is. `frontH` / `backH` are MAGNITUDES in tile heights (0 when
+ * nothing is on that side); `frontPct` / `backPct` the matching disparity magnitudes, % of the
+ * tile width.
+ */
+export interface DepthReport {
+  frontH: number;
+  backH: number;
+  frontPct: number;
+  backPct: number;
+  basis: DepthReportBasis;
+}
+
+/**
+ * Disparity, % of the tile width, of a point `depthH` tile heights out of the glass on a DISPLAY
+ * rig: physical depth `z = depthH · heightM`, disparity `e · z / (V − z)` (e = 0.063 m × ipdFactor,
+ * V = `viewerM`) over the tile width `aspect · heightM`. Without `heightM` the small-depth limit
+ * `100 · e · depthH / (aspect · V)`. SIGNED: `depthH > 0` (in front) gives a NEGATIVE disparity,
+ * behind a positive one — as {@link cameraRigDisparityPct}. −Infinity at or past the viewer.
+ */
+export function disparityPct(o: {
+  depthH: number;
+  aspect: number;
+  /** Default 0.6. */
+  viewerM?: number;
+  heightM?: number;
+  /** Default 1. */
+  ipdFactor?: number;
+  /** Default 0.063. */
+  eyeSeparationM?: number;
+}): number;
+
+/**
+ * Disparity, % of the tile width, of a point `z` world units down a CAMERA rig's view axis:
+ * `100 · b · (1/D − 1/z) / (2 · tan(verticalFov/2) · aspect)`, `b = 0.063 · ipdFactor ·
+ * metersToVirtual`. `+` = behind the glass, `−` = in front. `convergence` 0 / unset (and no
+ * `convergenceDiopters`) is infinity: everything is in front. NaN on bad input.
+ */
+export function cameraRigDisparityPct(o: {
+  z: number;
+  /** Zero-disparity distance, world units (0 = infinity). */
+  convergence?: number;
+  /** Or the descriptor's 1 / distance; wins over `convergence`. */
+  convergenceDiopters?: number;
+  ipdFactor?: number;
+  metersToVirtual?: number;
+  /** FULL vertical angle, RADIANS. */
+  verticalFov: number;
+  aspect: number;
+}): number;
+
+/**
+ * A {@link DepthReport} from a display-rig subject box: `front` / `back` as
+ * `SceneViewer.getSubjectBounds()` reports them (display space, +z toward the viewer, glass at 0),
+ * in the units where one tile height is `virtualDisplayHeight`.
+ */
+export function depthBudgetFromBounds(o: {
+  front: number;
+  back: number;
+  virtualDisplayHeight: number;
+  aspect: number;
+  viewerM?: number;
+  heightM?: number;
+  ipdFactor?: number;
+}): DepthReport;
+
+/**
+ * A comfort zone (vergence–accommodation): `'shibata'` (Shibata et al. 2011, "The zone of
+ * comfort", J. Vision — the default), `'percival'` (±1/3 D), or a number: a symmetric |ΔD| bound,
+ * diopters (> 0).
+ */
+export type ComfortZoneName = 'shibata' | 'percival' | number;
+
+/**
+ * A comfort zone at one viewing distance: the largest comfortable vergence change in front of the
+ * glass (`frontD`) and behind it (`behindD`), diopters, and the matching on-screen disparities in
+ * mm (`e · V · ΔD`). `behindD` is Infinity when the zone's far limit is past optical infinity.
+ */
+export interface ComfortZoneReport {
+  zone: ComfortZoneName;
+  viewerM: number;
+  frontD: number;
+  behindD: number;
+  frontMm: number;
+  behindMm: number;
+}
+
+/**
+ * The comfort zone for a viewer at `viewerM` (default 0.6 m). Shibata: near vergence limit
+ * `Dv/1.035 + 0.626`, far `Dv/1.129 − 0.442` (Dv = 1/V), so 0.57 D in front / 0.63 D behind at
+ * 0.6 m; Percival: ±1/3 D. NaN fields on bad input (a distance ≤ 0, an unknown zone).
+ */
+export function comfortZone(o?: { viewerM?: number; zone?: ComfortZoneName }): ComfortZoneReport;
+
+/**
+ * How much a DISPLAY rig's depth would have to shrink for a subject to sit inside a comfort zone:
+ * the largest `k ≤ 1` such that its disparities × k (ipdFactor, parallaxFactor moved with it)
+ * stay within {@link comfortZone}. ONLY EVER LOWERS DEPTH: 1 = it already fits, never above 1.
+ *
+ * Exact geometry at real proportions: the nearest point at `V − frontH · tileHeightM` from the
+ * viewer, the farthest at `V + backH · tileHeightM`, each side's `|1/V − 1/z|` against the zone.
+ * Use the NOMINAL viewer distance (what the display is built for), not a live head distance. The
+ * same depth in tile heights asks more of a small, close screen — a tablet at 0.4 m carries more
+ * vergence per tile height than a laptop at 0.6 m — which is why the answer depends on the panel.
+ *
+ * Returns 1 (no change) for missing or invalid input, and when the front reaches the viewer.
+ */
+export function comfortDepthFactor(o: {
+  /** MAGNITUDE, tile heights in front of the glass. */
+  frontH: number;
+  /** MAGNITUDE, tile heights behind it. */
+  backH: number;
+  /** The tile's (canvas's) physical height, metres. */
+  tileHeightM: number;
+  /** NOMINAL viewer distance, metres. Default 0.6. */
+  viewerM?: number;
+  /** Default 'shibata'. */
+  zone?: ComfortZoneName;
+}): number;
+
+/**
+ * The CAMERA-rig counterpart: the multiplier on the eye separation (ipdFactor) that puts the
+ * scene's nearest (`zNear`) and farthest (`zFar`, may be Infinity) points at the edge of the
+ * comfort zone. Measurement only; the page decides whether to apply it. Unlike the display-rig
+ * factor it can EXCEED 1, because a camera rig's 1 (63 mm × metersToVirtual in scene units) is
+ * only physical in metre-scale worlds — in large scene units it renders nearly flat.
+ *
+ * Disparity `f = b · (1/D − 1/z) / (2 · tan(verticalFov/2) · aspect)` of the tile width
+ * (b = 0.063 · ipdFactor · metersToVirtual), on the glass `p = f · aspect · tileHeightM`, in
+ * diopters `p / (0.063 · viewerM)`; the result is the smallest zone side / |ΔD| over the sides
+ * with content. Convergence 0 / unset = infinity (everything in front). Infinity when nothing is
+ * off the plane, NaN on bad input.
+ */
+export function cameraRigComfortFactor(o: {
+  zNear: number;
+  zFar: number;
+  /** Zero-disparity distance, world units (0 = infinity). */
+  convergence?: number;
+  /** Or 1 / distance; wins over `convergence`. */
+  convergenceDiopters?: number;
+  /** FULL vertical angle, RADIANS. */
+  verticalFov: number;
+  aspect: number;
+  tileHeightM: number;
+  /** Default 0.6. */
+  viewerM?: number;
+  /** Default 'shibata'. */
+  zone?: ComfortZoneName;
+  /** Default 1. */
+  ipdFactor?: number;
+  /** Default 1. */
+  metersToVirtual?: number;
+}): number;
+
+/** The hint `[inline3d]` logs for a `withheldReason` token (docs/woven-canvas-rules.md §3). */
+export function withheldReasonHint(reason: string): string;
+