@displayxr/inline3d 1.3.0 → 1.5.0

package/js/inline3d-mode-switch.js

@@ -0,0 +1,246 @@
+// inline3d-mode-switch.js — the eased 2D<->3D rendering-mode transition, as a state machine.
+//
+// A dependency-free port of `dxr::ModeSwitch` (displayxr-common `common/mode_switch.h/.cpp`), the
+// sequencer the native DisplayXR apps already use. It owns nothing but a scalar ramp and one
+// decision, and that decision is the whole point — the SEQUENCING ASYMMETRY that hand-rolled
+// versions get wrong:
+//
+//   3D -> 2D : ramp the disparity to 0 FIRST, and only then issue the mode request, so the panel
+//              flips on already-flat content.
+//   2D -> 3D : issue the mode request FIRST (the first 3D frame is flat), then ease the disparity
+//              up to the app's steady value.
+//
+// It is aesthetic policy, never correctness: the runtime keeps the eye set coherent whatever the
+// page does, and a browser or a page that skips this sees exactly the old snap.
+//
+// Driven by WALL-CLOCK dt, not frame counts, so the ramp takes the same time at 30 fps and 144 fps.
+// Interruptible: calling request() mid-flight retargets seamlessly from the value in force right
+// now, and a not-yet-fired ->2D that gets reversed simply ramps back up and NEVER fires.
+//
+// This module knows nothing about WebXR, the SDK, or the DOM — it is a pure state machine so it
+// can be unit-tested on its own (`test/mode-switch.test.mjs`, mirroring the C++ smoke test).
+
+/** The C++ default ramp duration (`XrSessionUpdateModeSwitch` configures 0.18 s). */
+export const MODE_SWITCH_DEFAULT_DURATION_MS = 180;
+
+/** The C++ default curve (`ModeSwitchEasing::SmoothStep`). */
+export const MODE_SWITCH_DEFAULT_EASING = 'smoothstep';
+
+/** Every easing this understands — the three of `dxr::ModeSwitchEasing`. */
+export const MODE_SWITCH_EASINGS = ['linear', 'smoothstep', 'easeoutcubic'];
+
+/**
+ * Normalise an easing name to one of {@link MODE_SWITCH_EASINGS}, or `null` when it is not one of
+ * them. Case- and separator-insensitive (`'ease-out-cubic'`, `'easeOutCubic'`), so a caller may
+ * spell it the way its own config does. Returning null rather than a default is what lets the
+ * caller decide whether an unknown name is worth a warning.
+ *
+ * @param {string} [easing]
+ * @returns {string|null}
+ */
+export function normaliseModeSwitchEasing(easing) {
+  if (typeof easing !== 'string') return null;
+  const key = easing.toLowerCase().replace(/[-_\s]/g, '');
+  return MODE_SWITCH_EASINGS.includes(key) ? key : null;
+}
+
+/** The curves themselves. `t` is already clamped to [0,1] by the caller. */
+function ease(easing, t) {
+  if (t <= 0) return 0;
+  if (t >= 1) return 1;
+  if (easing === 'linear') return t;
+  if (easing === 'easeoutcubic') {
+    const u = 1 - t;
+    return 1 - u * u * u;
+  }
+  return t * t * (3 - 2 * t); // smoothstep — Hermite 3t^2 - 2t^3
+}
+
+const IDLE = 'idle';
+const RAMP_DOWN_THEN_FIRE = 'rampDownThenFire';
+const FIRE_THEN_RAMP_UP = 'fireThenRampUp';
+
+/**
+ * The 2D<->3D mode-switch sequencer. One instance per session.
+ *
+ * The values it ramps are DIMENSIONLESS here: the SDK drives it with `steady: 1`, so `factor` is
+ * the fraction of each window's OWN configured `ipdFactor`/`parallaxFactor` to send this frame
+ * (0 = flat, 1 = exactly what the page asked for). The C++ original ramps an absolute ipdFactor
+ * instead; the state machine is identical either way, which is why `steady` is a parameter rather
+ * than a constant.
+ */
+export class ModeSwitch {
+  constructor(durationS, easing) {
+    this._phase = IDLE;
+    this._targetMode = null;
+    this._firePending = false; // fireThenRampUp: emit `fire` on the next update()
+    this._fireAtEnd = false; // rampDownThenFire: emit `fire` when the ramp lands
+    this._from = 0;
+    this._to = 0;
+    this._cur = 0; // last evaluated factor
+    this._t = 1; // normalised progress; 1 = landed/idle
+    this._dur = MODE_SWITCH_DEFAULT_DURATION_MS / 1000;
+    this._easing = MODE_SWITCH_DEFAULT_EASING;
+    if (durationS !== undefined || easing !== undefined) this.configure(durationS, easing);
+  }
+
+  /**
+   * Ramp duration in SECONDS and easing curve. `durationS <= 0` means instant — the switch fires
+   * and the value reaches its endpoint on the first `update()`, which is the honest way to say
+   * "no transition" without a second code path. An unknown easing name falls back to the default
+   * silently (the caller is the right place to warn about its own option).
+   *
+   * @param {number} [durationS] default 0.18
+   * @param {string} [easing] `'smoothstep'` (default) | `'linear'` | `'easeoutcubic'`
+   */
+  configure(durationS, easing) {
+    if (durationS !== undefined) {
+      const d = Number(durationS);
+      this._dur = Number.isFinite(d) && d > 0 ? d : 0;
+    }
+    if (easing !== undefined) {
+      this._easing = normaliseModeSwitchEasing(easing) || MODE_SWITCH_DEFAULT_EASING;
+    }
+    return this;
+  }
+
+  /** The ramp duration in seconds (0 = instant). */
+  get durationS() {
+    return this._dur;
+  }
+
+  /** The easing name in force. */
+  get easing() {
+    return this._easing;
+  }
+
+  /**
+   * Begin — or, mid-flight, seamlessly REDIRECT — a transition to `targetMode`.
+   *
+   * Safe to call on every toggle: a mid-ramp call fully resets the phase from the value in force
+   * right now, so a pending (un-fired) ->2D that the user reverses is simply dropped.
+   *
+   * @param {object} req
+   * @param {number|null} [req.targetMode] the rendering-mode index wanted (reported back by `update`)
+   * @param {number} req.targetViewCount that mode's view count (1 = 2D/mono, >1 = 3D)
+   * @param {number|null} [req.currentMode] the mode index active right now
+   * @param {number} req.currentViewCount its view count
+   * @param {number} [req.current] the value in force RIGHT NOW — the last `update()` factor while a
+   *        ramp runs, and the STEADY value when idle. Passing an internal 0 while idle is the
+   *        classic first-press snap: there is nothing to ramp down from.
+   * @param {number} [req.steady] the value to restore to (the page's own configured factors; the
+   *        SDK passes 1 because it scales each window's own numbers by the result)
+   */
+  request({
+    targetMode = null,
+    targetViewCount,
+    currentMode = null,
+    currentViewCount,
+    current,
+    steady = 1,
+  } = {}) {
+    const toMono = !(targetViewCount > 1);
+    const fromMono = !(currentViewCount > 1);
+    const steadyValue = Number.isFinite(steady) ? steady : 1;
+    const currentValue = Number.isFinite(current) ? current : steadyValue;
+
+    this._targetMode = targetMode;
+    this._from = currentValue;
+
+    if (toMono && !fromMono) {
+      // 3D -> 2D: flatten first, switch on landing, so 2D engages on already-mono content. The
+      // mode request is HELD until the ramp completes.
+      this._phase = RAMP_DOWN_THEN_FIRE;
+      this._to = 0;
+      this._fireAtEnd = true;
+      this._firePending = false;
+    } else if (!toMono && fromMono) {
+      // 2D -> 3D: switch now so the first 3D frame is flat (`from` is forced to 0 regardless of
+      // any stale value), then ease up to steady.
+      this._phase = FIRE_THEN_RAMP_UP;
+      this._from = 0;
+      this._to = steadyValue;
+      this._firePending = true;
+      this._fireAtEnd = false;
+    } else {
+      // Same dimensionality: 2D->2D, 3D->3D, or the REVERSAL of a not-yet-fired ->2D (nothing
+      // fired, so the display is still 3D and `currentViewCount` is still > 1). No flatten: switch
+      // now — skipping the fire when the target is already the current mode, which is exactly what
+      // makes a reversal never issue a stale request — and restore steady disparity for a 3D
+      // target. For a 2D target the value is irrelevant (mono), so leave it where it is.
+      this._phase = FIRE_THEN_RAMP_UP;
+      this._to = toMono ? currentValue : steadyValue;
+      this._firePending = !(targetMode !== null && targetMode === currentMode);
+      this._fireAtEnd = false;
+    }
+
+    this._t = this._dur > 0 ? 0 : 1;
+    this._cur = this._from;
+    return this;
+  }
+
+  /**
+   * Advance the ramp by `dtS` seconds and report this frame's outputs.
+   *
+   * @param {number} dtS wall-clock seconds since the last call
+   * @returns {{factor:number, fire:boolean, mode:(number|null)}} `factor` is the value to submit
+   *   this frame; `fire` is true on EXACTLY ONE update — the frame on which the caller should
+   *   issue the real mode request for `mode`.
+   */
+  update(dtS) {
+    let fire = false;
+
+    if (this._phase !== IDLE) {
+      const dt = Number.isFinite(dtS) && dtS > 0 ? dtS : 0;
+      if (this._t < 1 && this._dur > 0) {
+        this._t += dt / this._dur;
+        if (this._t > 1) this._t = 1;
+      } else {
+        this._t = 1;
+      }
+      this._cur = this._from + (this._to - this._from) * ease(this._easing, this._t);
+
+      if (this._phase === FIRE_THEN_RAMP_UP) {
+        if (this._firePending) {
+          this._firePending = false;
+          fire = true;
+        }
+        if (this._t >= 1) this._phase = IDLE;
+      } else {
+        if (this._t >= 1) {
+          if (this._fireAtEnd) {
+            this._fireAtEnd = false;
+            fire = true;
+          }
+          this._phase = IDLE;
+        }
+      }
+    }
+
+    return { factor: this._cur, fire, mode: this._targetMode };
+  }
+
+  /** True while a ramp is in flight or a held mode request has not fired yet. */
+  active() {
+    return this._phase !== IDLE;
+  }
+
+  /** The current factor, without advancing the clock. */
+  value() {
+    return this._cur;
+  }
+
+  /** True while a mode request is being HELD until the ramp lands (a ->2D that has not fired). */
+  firePending() {
+    return this._phase === RAMP_DOWN_THEN_FIRE ? this._fireAtEnd : this._firePending;
+  }
+
+  /** Drop everything in flight. The factor is left where it is — the caller owns what to do next. */
+  cancel() {
+    this._phase = IDLE;
+    this._firePending = false;
+    this._fireAtEnd = false;
+    this._t = 1;
+    return this;
+  }
+}

package/js/inline3d-model.js

@@ -478,7 +478,7 @@ function boundsOf(object3d) {
  * This is the default because the alternative is silently wrong. `addStudioLights` is punctual
  * only, and a punctual light contributes a specular highlight without filling a metallic BRDF —
  * so a `metalness: 1` surface has nothing to reflect and resolves to BLACK. Chrome bells render as
- * a dark disc, glass lenses as opaque holes, and the result reads as a corrupt asset rather than a
+ * a dark disc, clear-glass optics as opaque holes, and the result reads as a corrupt asset rather than a
  * lighting choice. It has cost real debugging time more than once.
  *
  * RoomEnvironment is generated in memory — a small box of emissive panels — so this buys IBL with

package/js/inline3d-undock.js

@@ -0,0 +1,251 @@
+// inline3d-undock.js — lift a window's 3D asset OUT of the page into a floating, transparent,
+// click-through native viewer over the desktop. Dependency-free, and usable on its own.
+//
+// TWO PATHS, ONE CONTRACT. Where the browser exposes `XRDisplayLayer.undock()` the request goes
+// straight through it: the layer already knows its element's rect, and the viewer opens with no
+// prompt. Everywhere else the page spawns the same viewer through the `displayxr-view:` OS
+// protocol — the spawn primitive every browser hands a page (Chrome asks once, "Open DisplayXR
+// …?", with an "Always allow" tick). The URL grammar below is the contract both paths share, and
+// it is the one parsed by displayxr-common's `launch_args.h`.
+//
+// WHY A NATIVE PROCESS AND NOT A WINDOW. The browser's inline-3D weave is bound to ONE window per
+// process and hands back opaque pixels into the page's own compositing, so no browser window can
+// be the transparent floating one. The floating window is a native process; the page's only job
+// is to spawn it with the asset URL and the tile's screen rect.
+//
+// NOTHING HERE TOUCHES THE TILE. Undock READS an element's rect and never writes to it, so it
+// cannot disturb a woven window — the button that calls it lives in the page's own chrome.
+
+/** @typedef {'model'|'splat'} UndockType */
+
+/**
+ * How the API-first path finds the live `XRDisplayLayer` behind an element. `inline3d.js`
+ * registers one when it is imported (only it knows the canvas -> layer map); with no resolver —
+ * this module used standalone — every call takes the protocol fallback, which is the correct
+ * degradation rather than a failure.
+ *
+ * @param {(el: Element) => object|null} fn
+ */
+let layerResolver = null;
+export function setUndockLayerResolver(fn) {
+  layerResolver = typeof fn === 'function' ? fn : null;
+}
+
+/**
+ * True where a native DisplayXR viewer can exist at all. The viewers are Windows-only today, so
+ * this is a PLATFORM probe, not a capability one — a page uses it to decide whether to show an
+ * undock affordance. It says nothing about whether the viewer is installed: that is only knowable
+ * when the launch is attempted (a `not-installed` Error on the API path; silently nothing on the
+ * protocol path, which is exactly why the API path is worth having).
+ */
+export function undockAvailable() {
+  if (typeof navigator === 'undefined') return false;
+  const uad = navigator.userAgentData;
+  if (uad && uad.platform) return uad.platform === 'Windows';
+  return /Windows/i.test(navigator.userAgent);
+}
+
+/**
+ * The element's rect in PHYSICAL SCREEN pixels — the space the viewer places its window in.
+ *
+ * `screenX/Y` and `outerWidth/Height` are CSS px in the browser's own DIP space; `devicePixelRatio`
+ * folds the OS scale AND the page zoom together. At 100 % zoom the arithmetic is exact; with page
+ * zoom it drifts by the zoom factor, and the viewer clamps the rect into the panel anyway. `dpr`
+ * travels along so a calibration session can read both numbers from the viewer's log instead of
+ * reverse-engineering the DIP space.
+ *
+ * @param {Element} el
+ * @returns {{x:number, y:number, w:number, h:number, dpr:number}}
+ */
+export function tileScreenRect(el) {
+  const r = el.getBoundingClientRect();
+  const dpr = window.devicePixelRatio || 1;
+  const chromeX = Math.max(0, (window.outerWidth - window.innerWidth) / 2);
+  const chromeY = Math.max(0, window.outerHeight - window.innerHeight);
+  return {
+    x: Math.round((window.screenX + chromeX + r.left) * dpr),
+    y: Math.round((window.screenY + chromeY + r.top) * dpr),
+    w: Math.max(64, Math.round(r.width * dpr)),
+    h: Math.max(64, Math.round(r.height * dpr)),
+    dpr,
+  };
+}
+
+/**
+ * The `displayxr-view:` URL for undocking `opts` at `el`'s screen rect — the fallback path's
+ * whole payload, exported so a page can log or test it without launching anything.
+ *
+ *   displayxr-view://open?src=<pct>&type=model|splat&rect=X,Y,W,H&dpr=<f>&title=<pct>
+ *                        &env=room&pose=<yaw>,<pitch>&margin=<f>&transparent=1&v=1
+ *
+ * `src` is resolved to an ABSOLUTE url here and must be https (or http on loopback): the viewer
+ * refuses file:/UNC/local paths from a protocol launch by design.
+ *
+ * NO `vh`. The grammar has one, and sending it is wrong: it is a raw pin that DISABLES the
+ * viewer's auto-fit, so an asset authored at 0.2 m arrives at native scale in a small window (far
+ * too zoomed in). Left unpinned the viewer auto-fits to ~80 % of the window height — the same
+ * rule a page's own fit applies to the same pixel box — so the apparent size matches. Apparent
+ * size is a property of the window rect, not of vH.
+ *
+ * @param {Element} el
+ * @param {object} opts  {src, type, env?, pose?, margin?, title?}
+ * @returns {string}
+ */
+export function undockUrl(el, opts) {
+  const src = new URL(opts.src, window.location.href).href;
+  const rect = tileScreenRect(el);
+  const pairs = [];
+  const put = (k, v) => pairs.push(`${k}=${encodeURIComponent(v)}`);
+  put('src', src);
+  put('type', opts.type);
+  put('rect', `${rect.x},${rect.y},${rect.w},${rect.h}`);
+  put('dpr', rect.dpr.toFixed(3));
+  if (opts.title) put('title', String(opts.title).slice(0, 64));
+  if (opts.env) put('env', opts.env);
+  // The page's opening angle: a model seen at yaw -40 has a very different silhouette from the
+  // same model face-on, and "it looks bigger undocked" is usually exactly that (the fit rules
+  // agree; the pose did not). Same convention as the SDK's setPose({yaw, pitch, zoom}).
+  if (opts.pose) {
+    const z = opts.pose.zoom !== undefined && opts.pose.zoom !== 1 ? `,${opts.pose.zoom}` : '';
+    put('pose', `${opts.pose.yaw},${opts.pose.pitch ?? 0}${z}`);
+  }
+  if (opts.margin !== undefined) put('margin', String(opts.margin));
+  // Transparent is the protocol's default; stated explicitly so the intent is visible in the URL.
+  put('transparent', '1');
+  put('v', '1');
+  // Built by hand rather than with URLSearchParams, which encodes a space as '+' — a form the
+  // viewer deliberately does NOT decode. encodeURIComponent is the spec form and never emits '+'.
+  return `displayxr-view://open?${pairs.join('&')}`;
+}
+
+/**
+ * Fire the protocol from a user gesture. A hidden iframe rather than `location.href`: the page
+ * never unloads mid-demo, and a "no handler installed" outcome is contained in the frame — which
+ * is also why this path can never REPORT that outcome. Chrome only shows the external-protocol
+ * dialog under a transient user activation, so it has to run synchronously in the click.
+ */
+function launchProtocol(url) {
+  const frame = document.createElement('iframe');
+  frame.setAttribute('aria-hidden', 'true');
+  frame.style.display = 'none';
+  frame.src = url;
+  document.body.appendChild(frame);
+  window.setTimeout(() => frame.remove(), 1500);
+}
+
+const UNDOCK_ERRORS = ['not-installed', 'src-not-allowed', 'no-activation', 'busy'];
+
+/** Give a rejection one of the four contract names, keeping the browser's own where it has one. */
+function undockError(e, fallbackName, message) {
+  const name = e && UNDOCK_ERRORS.includes(e.name) ? e.name : fallbackName;
+  const err = new Error(message || (e && e.message) || `[inline3d] undock failed (${name}).`);
+  err.name = name;
+  if (e) err.cause = e;
+  return err;
+}
+
+// ONE LIVE UNDOCK AT A TIME. The viewer is a single floating window and the browser refuses a
+// second request while one is in flight ('busy'); the fallback path has no such guard, so the
+// module keeps its own — two protocol launches from one click would spawn two viewers.
+let inFlight = false;
+
+/**
+ * Undock `target`'s asset into the floating native viewer.
+ *
+ * CALL IT SYNCHRONOUSLY INSIDE THE CLICK. Both paths need the transient user activation — the
+ * API path to be allowed at all (`no-activation`), the fallback to get Chrome's protocol dialog —
+ * and an `await` before this call spends it. Nothing here awaits before the launch, so the
+ * activation is intact when it matters.
+ *
+ * @param {Element} target  the element whose SCREEN RECT the viewer opens over (the tile).
+ * @param {object} opts
+ * @param {string} opts.src   absolute https URL (or http on loopback) of the asset.
+ * @param {UndockType} opts.type
+ * @param {'room'|'studio'|'sky'|'none'} [opts.env]  lighting the page rendered with.
+ * @param {{yaw:number, pitch?:number, zoom?:number}} [opts.pose]  the angle the page opened at.
+ * @param {number} [opts.margin]  the page's fit margin, when it overrides the default.
+ * @param {string} [opts.title]
+ * @returns {Promise<{ended:Promise<void>, viewer:UndockType, detached?:boolean}>}
+ *   `ended` resolves when the viewer exits (fallback path: immediately, with
+ *   `detached === true` — a protocol launch is fire-and-forget and the page never hears back).
+ *   Rejects with an Error named `not-installed` | `src-not-allowed` | `no-activation` | `busy`.
+ */
+export function undock(target, opts) {
+  if (!target || typeof target.getBoundingClientRect !== 'function') {
+    return Promise.reject(new TypeError('[inline3d] undock() takes an Element and options.'));
+  }
+  if (!opts || typeof opts.src !== 'string' || !opts.src) {
+    return Promise.reject(new TypeError('[inline3d] undock() needs opts.src (an absolute URL).'));
+  }
+  if (opts.type !== 'model' && opts.type !== 'splat') {
+    return Promise.reject(
+      new TypeError(`[inline3d] undock() opts.type is 'model' or 'splat', got ${JSON.stringify(opts.type)}.`)
+    );
+  }
+  if (inFlight) return Promise.reject(undockError(null, 'busy', '[inline3d] an undock is already in flight.'));
+
+  const layer = layerResolver ? layerResolver(target) : null;
+  const viewer = opts.type;
+
+  // ── fallback: the OS protocol ──────────────────────────────────────────────────────────
+  if (!layer || typeof layer.undock !== 'function') {
+    let url;
+    try {
+      url = undockUrl(target, opts);
+    } catch (e) {
+      return Promise.reject(undockError(e, 'src-not-allowed'));
+    }
+    launchProtocol(url);
+    // Fire-and-forget by construction: the iframe swallows "no handler installed" and nothing
+    // comes back from a spawned process, so `ended` is honest only about THIS page's part being
+    // over. `detached` is how a caller tells the two paths apart.
+    return Promise.resolve({ ended: Promise.resolve(), viewer, detached: true, url });
+  }
+
+  // ── API path ───────────────────────────────────────────────────────────────────────────
+  // Synchronous, first thing, activation intact. The layer knows its own element rect, so only
+  // the content half of the contract travels.
+  const init = { src: opts.src, type: opts.type };
+  if (opts.env) init.env = opts.env;
+  if (opts.pose) init.pose = opts.pose;
+  if (opts.margin !== undefined) init.margin = opts.margin;
+  if (opts.title) init.title = opts.title;
+
+  let call;
+  try {
+    call = Promise.resolve(layer.undock(init));
+  } catch (e) {
+    // A synchronous throw is the same failure as a rejection; one .catch() should cover both.
+    return Promise.reject(undockError(e, 'src-not-allowed'));
+  }
+  inFlight = true;
+  const settled = call.finally(() => {
+    inFlight = false;
+  });
+
+  // TWO PROMISE SHAPES, ONE ANSWER. `undock()` either rejects PROMPTLY — every refusal
+  // (not-installed / src-not-allowed / no-activation / busy) is decided before any window
+  // exists — or it stays pending until the viewer exits. A short race tells them apart without
+  // inventing an event: whatever has not rejected by then launched. The launch has already
+  // happened synchronously above, so this wait costs the user nothing.
+  const LAUNCH_MS = 150;
+  const launchProbe = settled.then(
+    () => 'launched',
+    (e) => {
+      throw undockError(e, 'not-installed');
+    }
+  );
+  // The probe LOSES the race whenever the viewer stays open, and a rejection arriving after that
+  // would otherwise be an unhandled one. Marked handled here; the same rejection still reaches
+  // the caller through `ended`, which is where a late failure belongs.
+  launchProbe.catch(() => {});
+  return Promise.race([
+    launchProbe,
+    new Promise((resolve) => window.setTimeout(() => resolve('launched'), LAUNCH_MS)),
+  ]).then(() => ({
+    // A rejection AFTER the launch window is the viewer failing later, and it belongs on `ended`.
+    ended: settled.then(() => undefined),
+    viewer,
+    detached: false,
+  }));
+}