@displayxr/inline3d 1.31.0 → 1.32.0

package/index.d.ts

@@ -123,6 +123,35 @@ export interface XRDisplayInfo {
   nominalViewerPosition?: DOMPointReadOnly;
 }
 
+/** {@link TileHandle.displayMetrics}: a window in physical units. Metres throughout. */
+export interface DisplayMetrics {
+  /** The canvas's CSS box on the panel, [width, height]. */
+  canvasSizeM: [number, number];
+  /** One CSS px on the panel (physical pixel pitch × devicePixelRatio). */
+  metersPerCssPx: number;
+  displaySizeM: [number, number];
+  /** `nominalViewerPosition.z`, else the default. */
+  nominalViewerM: number;
+  /** Always the default today: no browser or runtime surface reports one. */
+  eyeSeparationM: number;
+  source: { size: 'display' | 'default'; viewer: 'display' | 'default'; eyeSeparation: 'default' };
+}
+
+/** What {@link TileHandle.displayMetrics} fills in when the display cannot say. */
+export const DISPLAY_METRICS_DEFAULTS: Readonly<{
+  displaySizeM: readonly [number, number];
+  displayPixels: readonly [number, number];
+  nominalViewerM: number;
+  eyeSeparationM: number;
+}>;
+
+/** {@link TileHandle.displayMetrics} as a pure function of an XRDisplayInfo, a client rect and devicePixelRatio. */
+export function displayMetricsFrom(
+  info: XRDisplayInfo | null,
+  rect: { width: number; height: number } | null,
+  dpr?: number,
+): DisplayMetrics;
+
 /**
  * One rendering mode the DISPLAY can be put in, as reported by the runtime.
  *
@@ -310,6 +339,13 @@ export interface TileHandle {
    * tile off screen).
    */
   getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /**
+   * This window in physical units — canvas size in metres, metres per CSS px, the panel, the
+   * nominal viewer distance, the eye separation — from {@link getDisplayInfo}, with anything not
+   * measurable filled from {@link DISPLAY_METRICS_DEFAULTS} and flagged in `source`. Never rejects.
+   * The canvas size is read at the call: call again after a resize.
+   */
+  displayMetrics(): Promise<DisplayMetrics>;
   /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
   getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
   /**

package/js/inline3d-display-metrics.js

@@ -0,0 +1,51 @@
+// inline3d-display-metrics.js — a tile in PHYSICAL units, from XRDisplayInfo.
+//
+// What TileHandle.displayMetrics() resolves, as a pure function, so ./splat's depth envelope (and
+// a page) can share it without pulling in the core. Dependency-free; re-exported by ./inline3d.js.
+
+/**
+ * The defaults displayMetrics() fills in what the display cannot report: a 15.6" 16:9 panel at
+ * 1920x1080 CSS px, the viewer at 650 mm, eyes 63 mm apart. EYE SEPARATION IS ALWAYS A DEFAULT —
+ * no browser or runtime surface reports one (the runtime tracks eye POSITIONS; a page cannot read
+ * them) — so `source.eyeSeparation` is always 'default' today.
+ */
+export const DISPLAY_METRICS_DEFAULTS = Object.freeze({
+  displaySizeM: Object.freeze([0.3456, 0.1944]),
+  displayPixels: Object.freeze([1920, 1080]),
+  nominalViewerM: 0.65,
+  eyeSeparationM: 0.063,
+});
+
+/**
+ * displayMetrics() as a pure function: `info` an XRDisplayInfo (or null), `rect` the canvas's
+ * client rect (CSS px), `dpr` window.devicePixelRatio. Physical px pitch = displayWidthMeters /
+ * displayPixelWidth (the same per axis), and one CSS px is `dpr` physical px — exact when the
+ * browser window is on the panel at its native resolution, which is the only place a woven tile
+ * draws in 3D.
+ */
+export function displayMetricsFrom(info, rect, dpr = 1) {
+  const D = DISPLAY_METRICS_DEFAULTS;
+  const ok =
+    !!info &&
+    info.displayWidthMeters > 0 &&
+    info.displayHeightMeters > 0 &&
+    info.displayPixelWidth > 0 &&
+    info.displayPixelHeight > 0;
+  const displaySizeM = ok ? [info.displayWidthMeters, info.displayHeightMeters] : [...D.displaySizeM];
+  const px = ok ? [info.displayPixelWidth, info.displayPixelHeight] : [...D.displayPixels];
+  // Per axis, then their mean: a panel's pixels are square to well under a percent, and one
+  // number per CSS px is what a page converting a DOM rect wants.
+  const pitch = ((displaySizeM[0] / px[0]) + (displaySizeM[1] / px[1])) / 2;
+  const d = dpr > 0 ? dpr : 1;
+  const metersPerCssPx = ok ? pitch * d : pitch * (px[1] / Math.max(1, globalThis.innerHeight || px[1]));
+  const z = info?.nominalViewerPosition?.z;
+  const viewerOk = Number.isFinite(z) && z > 0.1;
+  return {
+    canvasSizeM: [(rect?.width || 0) * metersPerCssPx, (rect?.height || 0) * metersPerCssPx],
+    metersPerCssPx,
+    displaySizeM,
+    nominalViewerM: viewerOk ? z : D.nominalViewerM,
+    eyeSeparationM: D.eyeSeparationM,
+    source: { size: ok ? 'display' : 'default', viewer: viewerOk ? 'display' : 'default', eyeSeparation: 'default' },
+  };
+}

package/js/inline3d-splat-deferred.js

@@ -91,6 +91,18 @@ export function addSplatDeferred(wall, canvas, src, opts) {
           validateSetRigArgs(type, o);
           return out.ready.then(() => out.setRig(type, o));
         },
+    // Stereo strength / the depth envelope before the adapter has loaded: queued, replayed in
+    // order once it has (both are sticky handle state, applied to the first asset from its first
+    // frame). Validated by the adapter at replay.
+    setStereo: (...args) => {
+      pending.push(['setStereo', args]);
+      return out;
+    },
+    setDepthEnvelope: (...args) => {
+      pending.push(['setDepthEnvelope', args]);
+      return out;
+    },
+    displayMetrics: () => out.ready.then(() => out.displayMetrics()),
     // A video before the first asset has landed: controls:'page' throws at the call's own line,
     // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
     setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),

package/js/inline3d-splat-effects.js

@@ -23,7 +23,7 @@
 //
 // The SDK owns the chunk: every active effect of a scope is ONE function body with its own
 // uniform prefix, and the chunk calls them in a FIXED order, STAGE_ORDER: grade → clip → reveal →
-// pulse → custom. Removing the last effect deletes the chunk (tile) or the modifier (entity),
+// pulse → custom → envelope (→ cull). Removing the last effect deletes the chunk (tile) or the modifier (entity),
 // which restores the engine's own default — the exact baseline, not a no-op look-alike.
 //
 // Adding an effect = one GLSL body + one registry entry in EFFECTS below: `glsl(P, opts)` defines
@@ -47,7 +47,16 @@
 import { coverageExponent, FADE_TRANSMITTANCE_FLOOR } from './inline3d-splat-shared.js';
 
 /** The fixed composition order of a generated chunk. */
-export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom', 'cull']);
+export const STAGE_ORDER = Object.freeze(['grade', 'clip', 'reveal', 'pulse', 'custom', 'envelope', 'cull']);
+
+/** handle.setDepthEnvelope's flat rects the shader takes (the largest-weight first beyond it). */
+export const ENVELOPE_MAX_RECTS = 8;
+const ENVELOPE_NO_RECT = Object.freeze([1, -1, 1, -1]);
+const ENVELOPE_OFF = (() => {
+  const o = { on: 0, O: [0, 0, 0], A: [0, 0, -1], R: [1, 0, 0], U: [0, 1, 0], T: [1, 1, 1, 1], K: [0, 1, 1, 0], S: [-1, 1, -1, 1], E: [1, 0, 0, 0], W0: [0, 0, 0, 0], W1: [0, 0, 0, 0] };
+  for (let i = 0; i < ENVELOPE_MAX_RECTS; i++) o['F' + i] = ENVELOPE_NO_RECT;
+  return Object.freeze(o);
+})();
 
 /** The most eye views setSource's wavefront culls for (more: every gaussian is drawn). */
 export const WIPE_CULL_MAX_VIEWS = 4;
@@ -603,6 +612,87 @@ void ${P}color(vec3 c, inout vec4 col) { if (${P}cut) col.a = 0.0; }
     },
   },
 
+  // Internal: handle.setDepthEnvelope — THE FRAME ENVELOPE. Content may come OUT of the glass only
+  // well inside the frame: a gaussian whose panel depth would exceed the cap at its screen spot
+  //   F(x, y) = edge + (maxFront − edge) · e,  e = smoothstep(0, band, distance to the stage edge or
+  //             to a flat rect (weighted)), in metres on the panel,
+  // slides back ALONG ITS OWN RAY from the declared camera rig's centre (centre and scale × λ), so
+  // the rig's mono picture is unchanged and the engine's sort order stays valid. On a camera rig a
+  // point at depth d has panel disparity  k·e·f_p·(1/D − 1/d)  (k = ipdFactor·metersToVirtual per
+  // world unit, f_p = canvas height / (2·tan(vfov/2)), D the convergence), and F metres out needs
+  // −e·F/(n − F) — so the deepest-out allowed depth is  1/d_env = 1/D + F / (k·f_p·(n − F)); the
+  // viewer's eye separation e cancels. Behind the glass is never touched. Keyed on world position
+  // and the RIG (not the tracked eyes), so both eyes and every head position agree. The adapter
+  // supplies everything per tick through opts.state() (null = off); world space throughout.
+  envelope: {
+    stage: 'envelope',
+    kind: 'persistent',
+    internal: true,
+    defaults: {},
+    glsl: (P) => `
+uniform float ${P}on;
+uniform vec3 ${P}O;
+uniform vec3 ${P}A;
+uniform vec3 ${P}R;
+uniform vec3 ${P}U;
+uniform vec4 ${P}T;   // tan half-fov x, y; canvas half-size x, y (m)
+uniform vec4 ${P}K;   // 1/D (world), k·f_p (world·m), viewer n (m), maxFront (m)
+uniform vec4 ${P}S;   // stage l, r, b, t (canvas-normalised, y up)
+uniform vec4 ${P}E;   // band (m), edge (m), rect count, -
+${[0, 1, 2, 3, 4, 5, 6, 7].map((i) => `uniform vec4 ${P}F${i};`).join('\n')}
+uniform vec4 ${P}W0;
+uniform vec4 ${P}W1;
+float ${P}lambda;
+float ${P}flat(vec2 f, vec4 C, float w) {
+  if (w <= 0.0 || C.x >= C.y || C.z >= C.w) return 1.0;
+  vec2 o = max(vec2(max(C.x - f.x, f.x - C.y) * ${P}T.z, max(C.z - f.y, f.y - C.w) * ${P}T.w), vec2(0.0));
+  return mix(1.0, smoothstep(0.0, ${P}E.x, length(o)), w);
+}
+void ${P}center(inout vec3 c) {
+  ${P}lambda = 1.0;
+  if (${P}on < 0.5) return;
+  vec3 v = c - ${P}O;
+  float d = dot(v, ${P}A);
+  if (d <= 1e-4) return;
+  vec2 f = vec2(dot(v, ${P}R) / (d * ${P}T.x), dot(v, ${P}U) / (d * ${P}T.y));
+  vec4 S = ${P}S;
+  float inside = min(min(f.x - S.x, S.y - f.x) * ${P}T.z, min(f.y - S.z, S.w - f.y) * ${P}T.w);
+  float e = smoothstep(0.0, ${P}E.x, inside);
+${[0, 1, 2, 3, 4, 5, 6, 7].map((i) => `  e = min(e, ${P}flat(f, ${P}F${i}, ${P}W${i >> 2}.${'xyzw'[i & 3]}));`).join('\n')}
+  float F = ${P}E.y + max(${P}K.w - ${P}E.y, 0.0) * e;
+  float invEnv = ${P}K.x + F / (${P}K.y * max(${P}K.z - F, 1e-3));
+  if (1.0 / d <= invEnv) return;
+  ${P}lambda = 1.0 / (invEnv * d);
+  c = ${P}O + v * ${P}lambda;
+}
+void ${P}rs(vec3 oc, vec3 mc, inout vec4 r, inout vec3 sc) { sc *= ${P}lambda; }
+void ${P}color(vec3 c, inout vec4 col) {}
+`,
+    uniforms: (ctx, inst) => {
+      const st = typeof inst.opts.state === 'function' ? inst.opts.state() : null;
+      if (!st) return ENVELOPE_OFF;
+      const out = {
+        on: 1,
+        O: st.origin,
+        A: st.axis,
+        R: st.right,
+        U: st.up,
+        T: [st.tanX, st.tanY, st.halfW, st.halfH],
+        K: [st.invD, st.kfp, st.viewer, st.maxFront],
+        S: st.stage,
+        E: [st.band, st.edge, st.rects.length, 0],
+        W0: [0, 0, 0, 0],
+        W1: [0, 0, 0, 0],
+      };
+      for (let i = 0; i < ENVELOPE_MAX_RECTS; i++) {
+        const r = st.rects[i];
+        out['F' + i] = r ? r.f : ENVELOPE_NO_RECT;
+        if (r) out[i < 4 ? 'W0' : 'W1'][i & 3] = r.weight;
+      }
+      return out;
+    },
+  },
+
   // Internal: setSource's crossfade FALLBACK (no frame snapshot) — the coverage remap on one
   // entity, driven by the adapter.
   xfade: {

package/js/inline3d-splat-playcanvas.js

@@ -51,8 +51,10 @@ import {
 } from './inline3d-splat-perf.js';
 import { boundsFromPositions, boundsFromPositionsAsync } from './inline3d-viewer.js';
 import { cameraRigFromPose, displayRig } from './inline3d-three.js';
+import { displayMetricsFrom } from './inline3d-display-metrics.js';
 import {
   SplatEffects,
+  ENVELOPE_MAX_RECTS,
   EFFECTS,
   EASINGS,
   resolveRevealOption,
@@ -2312,6 +2314,26 @@ export class PlayCanvasSplatViewer {
     };
   }
 
+  /**
+   * The MONO camera's frame in WORLD (content) space — the rig the page declared, not the tracked
+   * eyes: `origin`, unit `axis`/`right`/`up`, and `scale` = world units per rig unit (the rig
+   * node's uniform scale). The depth envelope keys on it, so it holds still under head motion.
+   */
+  monoFrame() {
+    const M = mat4Mul(this.rigMatrix(), this.mono.pose);
+    const len = (x, y, z) => Math.hypot(x, y, z) || 1;
+    const sx = len(M[0], M[1], M[2]);
+    const sy = len(M[4], M[5], M[6]);
+    const sz = len(M[8], M[9], M[10]);
+    return {
+      origin: [M[12], M[13], M[14]],
+      axis: [-M[8] / sz, -M[9] / sz, -M[10] / sz],
+      right: [M[0] / sx, M[1] / sx, M[2] / sx],
+      up: [M[4] / sy, M[5] / sy, M[6] / sy],
+      scale: Math.cbrt(sx * sy * sz),
+    };
+  }
+
   _easeFocus() {
     if (this._focusSettled) return;
     const f = this._focus;
@@ -2811,6 +2833,95 @@ const PAGE_SETRIG_ERROR =
   "@displayxr/inline3d/splat: setRig() is not available with controls:'page' — the page owns the " +
   'camera (its camera IS the rig). Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).';
 
+/** handle.setDepthEnvelope's defaults, metres on the panel (Ride Spatial's depth rules v2). */
+export const DEPTH_ENVELOPE_DEFAULTS = Object.freeze({ maxFrontM: 0.02, edgeM: 0.001, bandM: 0.016 });
+
+/**
+ * handle.setDepthEnvelope's argument, validated and merged onto the current one (throws at the
+ * call). A key given replaces; `null` (the whole argument) turns the envelope off. Rects are kept
+ * as given (canvas fractions, y DOWN) plus `f` — [l, r, b, t] canvas-normalised, y UP — for the
+ * shader; more than ENVELOPE_MAX_RECTS keeps the heaviest (then largest) ones.
+ */
+export function validateDepthEnvelope(o, prev) {
+  if (o === null) return null;
+  const E = '@displayxr/inline3d/splat: setDepthEnvelope';
+  if (typeof o !== 'object' || Array.isArray(o)) throw new TypeError(`${E} takes an object or null.`);
+  const keys = ['maxFrontM', 'edgeM', 'bandM', 'stage', 'rects', 'viewerM', 'canvasSizeM'];
+  const unknown = Object.keys(o).filter((k) => !keys.includes(k));
+  if (unknown.length) throw new Error(`${E} — unknown option(s) ${unknown.join(', ')}.`);
+  const next = { ...DEPTH_ENVELOPE_DEFAULTS, stage: { x: 0, y: 0, w: 1, h: 1 }, rects: [], viewerM: null, canvasSizeM: null, ...(prev || {}) };
+  const num = (k, v, min, max = Infinity) => {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max) throw new RangeError(`${E} — ${k} must be a finite number in [${min}, ${max}] (got ${v}).`);
+    return v;
+  };
+  const rect = (r, what) => {
+    if (!r || typeof r !== 'object') throw new TypeError(`${E} — ${what} must be { x, y, w, h }.`);
+    const x = num(`${what}.x`, r.x, -10, 10);
+    const y = num(`${what}.y`, r.y, -10, 10);
+    const w = num(`${what}.w`, r.w, 0, 20);
+    const h = num(`${what}.h`, r.h, 0, 20);
+    return { x, y, w, h, f: [2 * x - 1, 2 * (x + w) - 1, 1 - 2 * (y + h), 1 - 2 * y] };
+  };
+  for (const k of ['maxFrontM', 'edgeM', 'bandM']) if (k in o && o[k] !== undefined) next[k] = num(k, o[k], k === 'bandM' ? 1e-5 : 0, 1);
+  if ('viewerM' in o && o.viewerM !== undefined) next.viewerM = o.viewerM === null ? null : num('viewerM', o.viewerM, 0.05, 10);
+  if ('canvasSizeM' in o && o.canvasSizeM !== undefined) {
+    const c = o.canvasSizeM;
+    if (c === null) next.canvasSizeM = null;
+    else {
+      if (!Array.isArray(c) || c.length !== 2) throw new TypeError(`${E} — canvasSizeM must be [width, height] in metres, or null.`);
+      next.canvasSizeM = [num('canvasSizeM[0]', c[0], 1e-4, 10), num('canvasSizeM[1]', c[1], 1e-4, 10)];
+    }
+  }
+  if ('stage' in o && o.stage !== undefined) next.stage = o.stage === null ? { x: 0, y: 0, w: 1, h: 1 } : rect(o.stage, 'stage');
+  next.stage = next.stage.f ? next.stage : rect(next.stage, 'stage');
+  if ('rects' in o && o.rects !== undefined) {
+    if (o.rects !== null && !Array.isArray(o.rects)) throw new TypeError(`${E} — rects must be an array.`);
+    next.rects = (o.rects || [])
+      .map((r, i) => ({ ...rect(r, `rects[${i}]`), weight: r.weight === undefined ? 1 : num(`rects[${i}].weight`, r.weight, 0, 1) }))
+      .filter((r) => r.weight > 0 && r.w > 0 && r.h > 0)
+      .sort((a, b) => b.weight - a.weight || b.w * b.h - a.w * a.h)
+      .slice(0, ENVELOPE_MAX_RECTS);
+  }
+  if (next.edgeM > next.maxFrontM) next.edgeM = next.maxFrontM;
+  return next;
+}
+
+/**
+ * handle.setStereo's argument, validated and merged onto the current override (throws at the
+ * call). Returns the new override, or null when nothing is overridden.
+ */
+export function validateSetStereo(o, prev) {
+  if (o === null) return null;
+  if (typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setStereo takes an object or null.');
+  // Absolute (…Factor) or RELATIVE to the asset's own (…Scale); per scalar, the last one given wins.
+  const pairs = [
+    ['ipdFactor', 'ipdScale'],
+    ['parallaxFactor', 'parallaxScale'],
+  ];
+  const keys = pairs.flat();
+  const unknown = Object.keys(o).filter((k) => !keys.includes(k));
+  if (unknown.length) throw new Error(`@displayxr/inline3d/splat: setStereo — unknown option(s) ${unknown.join(', ')}.`);
+  for (const [a, b] of pairs) {
+    if (o[a] != null && o[b] != null) throw new Error(`@displayxr/inline3d/splat: setStereo — ${a} and ${b} are exclusive.`);
+  }
+  const next = { ...(prev || {}) };
+  for (const [a, b] of pairs) {
+    for (const k of [a, b]) {
+      if (!(k in o) || o[k] === undefined) continue;
+      if (o[k] === null) {
+        delete next[k];
+        continue;
+      }
+      if (typeof o[k] !== 'number' || !Number.isFinite(o[k]) || o[k] < 0) {
+        throw new RangeError(`@displayxr/inline3d/splat: setStereo — ${k} must be a finite number >= 0 (got ${o[k]}).`);
+      }
+      next[k] = o[k];
+      delete next[k === a ? b : a];
+    }
+  }
+  return Object.keys(next).length ? next : null;
+}
+
 /**
  * handle.setRig's arguments, validated and resolved (throws at the call, before anything runs).
  * @returns {{type:'display'|'camera'|'auto', o?:object}}
@@ -3218,6 +3329,21 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     setSource,
     prepareSource,
     setRig,
+    setStereo,
+    setDepthEnvelope,
+    /**
+     * This tile in physical units (core TileHandle.displayMetrics, from getDisplayInfo()). Never
+     * rejects: defaults, flagged in `source`, where the display cannot say.
+     */
+    async displayMetrics() {
+      let info = null;
+      try {
+        info = (await handle?.getDisplayInfo?.()) ?? null;
+      } catch {
+        /* no display API / no live layer: the defaults */
+      }
+      return displayMetricsFrom(info, canvas.getBoundingClientRect(), globalThis.devicePixelRatio || 1);
+    },
     setVideo,
     /**
      * Draw a layer of this tile's engine through the DISPLAY rig (round, physical-depth stage
@@ -3950,6 +4076,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       canvasAspect: box.height > 0 ? box.width / box.height : 4 / 3,
     });
     if (type !== 'auto') resolved.typeSource = 'setRig';
+    // What the asset (or addSplat's options) asked for, kept so setStereo(null) can go back to it.
+    resolved.stereoDefault = { ipdFactor: resolved.ipdFactor, parallaxFactor: resolved.parallaxFactor };
+    applyStereoTo(resolved);
     resolved.focusDefault = resolved.focus.slice();
     resolved.focusDefaultSource = resolved.focusSource;
     return resolved;
@@ -3966,7 +4095,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
 
   /** Declare a DISPLAY rig to the runtime, unless that exact one is already declared. */
-  function declareDisplay(f) {
+  function declareDisplay(base, { raw = false } = {}) {
+    // raw: setVideo's own display rig — not the page's rig, so neither setStereo's factors nor
+    // the base setStereo re-declares from.
+    if (!raw) lastDisplayBase = base;
+    const f =
+      stereoOverride && !raw
+        ? { ...base, ipdFactor: stereoScalar(base.ipdFactor ?? 1, 'ipd'), parallaxFactor: stereoScalar(base.parallaxFactor ?? 1, 'parallax') }
+        : base;
     const key = `${f.vH}|${f.ipdFactor ?? 1}|${f.parallaxFactor ?? 1}|${f.perspectiveFactor ?? 1}`;
     if (declaredDisplay === key) return;
     // Back at the boot rig from the shorthand it was built with: nothing to say.
@@ -4033,6 +4169,132 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     declareDisplay(disp || { vH: bootFraming.vH });
   }
 
+  // ── handle.setStereo: live stereo strength on whatever rig is declared ──
+  /** { ipdFactor?, parallaxFactor? } set by handle.setStereo — sticky across setSource; null = none. */
+  let stereoOverride = null;
+  /** The display rig declareDisplay was last asked for, BEFORE setStereo's factors (to re-declare). */
+  let lastDisplayBase = null;
+  /** setStereo's factors onto a resolved rig, over the asset's own (stereoDefault). */
+  function applyStereoTo(r) {
+    const d = r.stereoDefault;
+    r.ipdFactor = stereoScalar(d.ipdFactor, 'ipd');
+    r.parallaxFactor = stereoScalar(d.parallaxFactor, 'parallax');
+  }
+  /** One scalar under setStereo: its absolute value, else `base` × its scale, else `base`. */
+  function stereoScalar(base, k) {
+    const o = stereoOverride;
+    if (o?.[`${k}Factor`] != null) return o[`${k}Factor`];
+    if (o?.[`${k}Scale`] != null) return base * o[`${k}Scale`];
+    return base;
+  }
+
+  /**
+   * handle.setStereo({ ipdFactor, parallaxFactor }) — re-declare the rig in force with new stereo
+   * scalars, next frame, with no cut: the pose, focus and framing stay. A key given replaces, a key
+   * set to null goes back to the asset's own value, `null` clears both. Sticky across setSource and
+   * setRig. On a camera rig the values are ABSOLUTE (like addSplat's options); on a display rig
+   * they replace the declared display rig's factors.
+   */
+  function setStereo(o) {
+    const next = validateSetStereo(o, stereoOverride);
+    stereoOverride = next;
+    if (out.rig?.stereoDefault) applyStereoTo(out.rig);
+    redeclareStereo();
+    return out;
+  }
+  /** Re-declare the rig in force with setStereo's factors (deduplicated on a display rig). */
+  function redeclareStereo() {
+    if (pageMode || vid?.on || !out.rig) return; // pageTick reads out.rig; video exit calls this
+    if (out.rig.type === 'camera') pushViewRig(true);
+    else if (lastDisplayBase) declareDisplay(lastDisplayBase);
+  }
+
+  // ── handle.setDepthEnvelope: the frame envelope (./inline3d-splat-effects.js EFFECTS.envelope) ──
+  /** validateDepthEnvelope's result, or null (off). */
+  let envelope = null;
+  /** displayMetricsFrom(getDisplayInfo()) — metres per CSS px and the viewer; defaults until it lands. */
+  let envMetrics = null;
+  let envMetricsSeq = 0;
+  function refreshEnvelopeMetrics() {
+    const seq = ++envMetricsSeq;
+    const done = (info) => {
+      if (seq === envMetricsSeq) envMetrics = displayMetricsFrom(info ?? null, null, globalThis.devicePixelRatio || 1);
+    };
+    let p = null;
+    try {
+      p = handle?.getDisplayInfo?.();
+    } catch {
+      /* no display API: the defaults */
+    }
+    if (p && typeof p.then === 'function') p.then(done, () => done(null));
+    else done(null);
+  }
+  /**
+   * The envelope's inputs for this frame, all from the DECLARED rig (never the tracked eyes): null
+   * = off — no envelope, not a camera rig (a display rig is a portal; its depth is the page's), a
+   * stereo video holding the rig, no disparity to cap (ipdFactor 0), or no canvas box.
+   */
+  function envelopeState() {
+    const E = envelope;
+    const r = out.viewRig;
+    if (!E || !r || r.type !== 'camera' || vid?.on) return null;
+    const k = (r.ipdFactor ?? 1) * (r.metersToVirtual ?? 1);
+    if (!(k > 0) || !(r.verticalFov > 0)) return null;
+    // clientWidth/Height: no layout flush on a clean frame (a real canvas always has them)
+    const box = canvas.clientWidth === undefined ? canvas.getBoundingClientRect() : null;
+    const cw = box ? box.width : canvas.clientWidth;
+    const ch = box ? box.height : canvas.clientHeight;
+    if (!(cw > 0 && ch > 0)) return null;
+    const m = envMetrics || displayMetricsFrom(null, null, 1);
+    const W = E.canvasSizeM ? E.canvasSizeM[0] : cw * m.metersPerCssPx;
+    const H = E.canvasSizeM ? E.canvasSizeM[1] : ch * m.metersPerCssPx;
+    const tanY = Math.tan(r.verticalFov / 2);
+    const fr = viewer.monoFrame();
+    return {
+      origin: fr.origin,
+      axis: fr.axis,
+      right: fr.right,
+      up: fr.up,
+      tanX: tanY * (cw / ch),
+      tanY,
+      halfW: W / 2,
+      halfH: H / 2,
+      // world units = rig units × fr.scale: the convergence and the eye baseline both scale with it
+      invD: (r.convergenceDiopters || 0) / fr.scale,
+      kfp: fr.scale * k * (H / (2 * tanY)),
+      viewer: E.viewerM ?? m.nominalViewerM,
+      maxFront: E.maxFrontM,
+      stage: E.stage.f,
+      band: E.bandM,
+      edge: E.edgeM,
+      rects: E.rects,
+    };
+  }
+  /** Install / update / remove the tile-scope envelope effect (no-op until the effects exist). */
+  function syncEnvelope() {
+    if (!fx) return;
+    fx.setInternal('tile', 'envelope', envelope ? { state: envelopeState } : null);
+    const inst = fx.scopes.get('tile')?.get('envelope');
+    if (inst) inst.hidden = true; // the SDK's, not the page's: never in effects(), never stopEffect()ed
+  }
+  /**
+   * handle.setDepthEnvelope(opts | null) — cap how far the splat may come OUT of the glass by where
+   * it lands on the canvas (docs/splat-effects.md §Depth envelope). Tile-wide and LIVE: every asset
+   * shown — an incoming one included, from its first frame, and both sides of a crossfade — is
+   * judged through the rig declared right now. A key given replaces; null turns it off.
+   */
+  function setDepthEnvelope(o) {
+    const next = validateDepthEnvelope(o, envelope);
+    if (next && !envelope) {
+      refreshEnvelopeMetrics();
+      // a lazy layer may not answer getDisplayInfo yet: ask again once the tile is woven
+      Promise.resolve(out.firstWoven).then(() => envelope && refreshEnvelopeMetrics());
+    }
+    envelope = next;
+    syncEnvelope();
+    return out;
+  }
+
   // ── handle.setRig: a live, reversible rig switch (docs/playcanvas-adapter.md §setRig) ──
   /** null = 'auto' (the per-asset waterfall); else { type: 'camera' } | { type: 'display', o }. */
   let rigOverride = null;
@@ -4241,6 +4503,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const kept = applyLoaded(loaded);
     current = { asset: loaded.asset, entity, res: loaded.res, kind: loaded.desc.kind, ...kept };
     fx = makeEffects(pcModule);
+    syncEnvelope(); // a setDepthEnvelope before the first asset
     // `reveal`: installed at its START state before the asset's first frame, played once the
     // tile is woven (handle.firstWoven — which is immediate in 2D) and the first frames are built.
     if (revealSpec) {
@@ -4374,7 +4637,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       v._placeMonoForFit();
       v._updateMonoProjection();
     }
-    declareDisplay({ vH: state.vH });
+    declareDisplay({ vH: state.vH }, { raw: true });
+    state.stereoAtEnter = stereoOverride;
     state.on = true;
   }
 
@@ -4408,6 +4672,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     } else out.viewRig = s.viewRig;
     lastConvergence = s.lastConvergence;
     state.on = false;
+    if (stereoOverride !== state.stereoAtEnter) redeclareStereo(); // a setStereo made while the video held the rig
+
   }
 
   /** Tear the video down now (setVideo(null) / remove()). */
@@ -4466,6 +4732,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
           // Another video on screen: keep ITS snapshot (the pre-video state), swap the source.
           state.saved = live.saved;
           state.on = true;
+          state.stereoAtEnter = live.stereoAtEnter;
           // S2: the plane outlives this swap; the replaced video's rect subscriptions go with it.
           for (const off of live.rectOffs) off();
           live.rectOffs.clear();
@@ -4474,7 +4741,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
             viewer.vH = state.vH;
             viewer._placeMonoForFit();
             viewer._updateMonoProjection();
-            declareDisplay({ vH: state.vH });
+            declareDisplay({ vH: state.vH }, { raw: true });
           }
         } else enterVideo(state);
         vid = state;

package/js/inline3d-splat.js

@@ -401,6 +401,20 @@ export function addSplat(wall, canvas, src, opts = {}) {
           "(addSplat(…, { engine:'playcanvas' })).",
       );
     },
+    /** Not on this backend: the depth envelope is a PlayCanvas-backend feature. */
+    setDepthEnvelope() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setDepthEnvelope() is implemented on the PlayCanvas backend only " +
+          "(addSplat(…, { engine:'playcanvas' })).",
+      );
+    },
+    /** Not on this backend: live stereo strength is a PlayCanvas-backend feature. */
+    setStereo() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setStereo() is implemented on the PlayCanvas backend only " +
+          "(addSplat(…, { engine:'playcanvas' })).",
+      );
+    },
     /** Not on this backend (splat effects are PlayCanvas-only in this version). */
     playEffect() {
       throw effectsNotOnSpark('playEffect()');

package/js/inline3d.js

@@ -34,6 +34,8 @@ export { undock, undockAvailable, undockUrl, tileScreenRect };
 import { setSessionViewerEase } from './inline3d-viewer-ease.js';
 // The tracking-acquisition ease, for pages that render their own addScene from the views.
 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 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
@@ -133,6 +135,7 @@ const hasViewRig = () => {
 // required — a browser with a partial set is a browser mid-implementation, and treating it as
 // supported would hand a page a `requestRenderingMode is not a function` at the worst moment.
 const DISPLAY_MODE_METHODS = ['getDisplayInfo', 'getRenderingModes', 'requestRenderingMode'];
+
 // The two display events, fired on the XRSession rather than the layer — so a page hears about a
 // mode or hardware-state change even while its tile's layer is closed (lazy mode), and one
 // subscription covers every window in the document.
@@ -1088,6 +1091,24 @@ class Inline3D {
        * @returns {Promise<object|null>}
        */
       getDisplayInfo: () => this._layerCall(win, 'getDisplayInfo', 'getDisplayInfo()'),
+      /**
+       * This window in PHYSICAL units: the canvas's size in metres, metres per CSS px, the panel,
+       * the nominal viewer distance and the eye separation — from getDisplayInfo(), with every
+       * value that could not be measured filled from a stated default (see `source`). Never
+       * rejects: no display API, no live layer, no glasses-free display all resolve the defaults.
+       * The canvas size is re-read at each call (call it again after a resize).
+       *
+       * @returns {Promise<object>}
+       */
+      displayMetrics: async () => {
+        let info = null;
+        try {
+          info = await this._layerCall(win, 'getDisplayInfo', 'getDisplayInfo()');
+        } catch {
+          /* no display API / no live layer: the defaults */
+        }
+        return displayMetricsFrom(info, canvas.getBoundingClientRect(), globalThis.devicePixelRatio || 1);
+      },
       /**
        * Every rendering mode the runtime can put this display in, as reported by the runtime:
        * `{modeIndex, modeName, viewCount, viewScaleX, viewScaleY, tileColumns, tileRows,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.31.0",
+  "version": "1.32.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",
@@ -65,6 +65,7 @@
   "files": [
     "js/inline3d.js",
     "js/inline3d-undock.js",
+    "js/inline3d-display-metrics.js",
     "js/inline3d-mode-switch.js",
     "js/inline3d-buffer-limit.js",
     "js/inline3d-viewer-ease.js",