@displayxr/inline3d 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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.4.0 — 2026-09-06
+
+### Added
+
+- **Display modes — the page can read what the panel IS, and ask it to change.** Until now a page
+  could describe its own framing (a view rig) but knew nothing about the display it was framing
+  *for*: not its size in metres, not its pixel count, not which of the runtime's rendering modes it
+  was in, and it had no way to ask for a different one. Three pass-throughs close that:
+  **`getDisplayInfo()`** (physical size, pixel size, recommended view scale; `null` where there is
+  no glasses-free display), **`getRenderingModes()`** (every mode the runtime can put the display
+  in — view count, tile grid, per-view pixels, `hardwareDisplay3D`, `isActive`, `isRequestable`)
+  and **`requestRenderingMode(i)`**. They sit on the **`createInline3D()` result** — the panel is
+  the document's, not a tile's — and under the same names on every tile handle, routed to whichever
+  window currently holds a live layer. Gate the group with
+  **`inline3dDisplayModesSupported()`**, which requires all three methods on
+  `XRDisplayLayer.prototype` — a browser shipping half the set is one mid-implementation, and
+  calling it supported would surface as a `not a function` inside a click handler.
+  *(core tier — additive)*
+
+- **The 2D/3D hardware state is a consequence of the mode, not a control.** There is deliberately
+  **no page-facing request** for it. Asking for a mode with `viewCount === 1` puts the panel in its
+  2D state and the browser reports that mode active — the runtime carries on weaving the same fixed
+  two-view atlas — and asking for the 2-view mode puts it back. Tying the two together makes the
+  one bad state (a flat panel showing a stereo atlas, i.e. a blurry double image rather than 2D)
+  unreachable. **`requestDisplayMode('2d'|'3d')` is gone**, and so is every mention of a "lens".
+
+- **The SDK collapses the stereo rig automatically.** When a 1-view mode goes **active** every
+  window's `ipdFactor`/`parallaxFactor` is pushed to 0 (both eyes render from one place), and a
+  2-view mode going active restores them. This is driven by the `renderingmodechange` event — plus
+  the first `getRenderingModes()` read, so a page that OPENS with the panel already flat is
+  collapsed too — and **not** by the request. So it happens however the mode changed (this page,
+  another one, the shell), the page's own render loop is untouched, and **a refused request changes
+  nothing in either direction**, which is now structural rather than a rollback.
+
+  **The restore is exact, and that is a design property, not luck.** The flattening is a *copy*
+  pushed at the layer — a page driving a rig every frame reuses one descriptor object, so zeroing
+  it in place would write the flattening into the page's own state and the restore would restore
+  0. So each window keeps what the page asked for, untouched, and the flat rig is derived on the
+  way out. That latch also means a per-frame `setViewRig` loop cannot walk the page out of 2D, a
+  lazy tile that scrolls away and rebuilds its layer comes back flat rather than in 3D, and a
+  window that never set a rig at all is flattened (and restored) via the exact rig equivalent of
+  its `virtualDisplayHeight`. *(core tier — additive)*
+
+- **`setStereoEnabled(bool)` is now SUGAR, and only sugar** — `false` requests the first mode with
+  `viewCount === 1 && isRequestable`, `true` the first with `viewCount === 2 && isRequestable`. It
+  touches neither the hardware state (nothing can) nor the rig (the event does that). It rejects
+  rather than inventing a mode when the panel lists none. *(core tier — behaviour change on an
+  unreleased API)*
+
+- **`on(type, cb)` / `off(type, cb)`** — the two events, which fire on the **XRSession** and not on
+  the layer, re-emitted on the wall and on every handle: `renderingmodechange`
+  `{type, modeIndex, viewCount, mode, detail}` and `hardwaredisplaystatechange`
+  `{type, state:'2d'|'3d', detail}`. `on` returns an unsubscribe function;
+  **`onDisplayModeChange(cb)`** remains as the both-events-one-callback shape.
+  `wall.hardwareDisplayState`, `wall.activeMode` and `wall.stereoCollapsed` expose the last
+  **reported** state — never the last requested one. *(core tier — additive)*
+
+- **Undock — lift a window's asset into a floating native viewer over the desktop.**
+  **`wall.undock`** is `{model, splat}` on a browser with `XRDisplayLayer.undock` and **`null`** on
+  one without (plain Chrome, or an older DisplayXR browser) — that null is what a page branches on;
+  **`wall.refreshUndock()`** re-reads it, **`inline3dUndockSupported()`** is the sync probe. The
+  action is **`await undock(element, {src, type, env?, pose?, margin?, title?})`** (new module
+  `js/inline3d-undock.js`, re-exported from the main entry): API-first through `layer.undock()`,
+  falling back to the `displayxr-view:` OS protocol (hidden-iframe navigation, Chrome's one-time
+  "Open DisplayXR…?" prompt) where the layer method is absent. **Call it synchronously inside the
+  click** — both paths need the transient activation. Resolves to `{ended, viewer, detached}`;
+  rejects with an Error named `not-installed` | `src-not-allowed` | `no-activation` | `busy`.
+  *(core tier — additive)*
+
+- **[`samples/display-modes/`](samples/display-modes/)** — the whole surface on one page: the
+  `getDisplayInfo()` fields, the `getRenderingModes()` table with the active row marked, a request
+  button on every requestable row (`viewCount` 1 **or** 2) and the rows needing more than two views
+  greyed with the reason, one `setStereoEnabled` convenience button, a **read-only** hardware
+  display state badge fed by the event, and a live event log. Every action prints a greppable
+  `[display-modes] …` line so a harness can drive it from the console.
+
+### Notes
+
+- **Advisory scales.** `viewScaleX/Y` and `recommendedViewScaleX/Y` are what the runtime would like
+  the per-view resolution to be. The browser cannot resize a page's canvas, so nothing applies them
+  for you — a page honours them by sizing its own backing store. Ignoring them costs sharpness or
+  fill rate, never correctness.
+- **The browser is fixed at two views.** No view synthesis exists anywhere in this stack, so a mode
+  needing MORE than two is listed (the panel really can do it) and refused. Show those rows; mark
+  them. A **one**-view mode is requestable — the browser still submits two views and the runtime
+  still weaves them; it is the panel that goes flat.
+
 ## 1.3.0 — 2026-09-04
 
 ### Added

package/index.d.ts

@@ -52,6 +52,114 @@ export interface XRViewRigInit {
   metersToVirtual?: number;
 }
 
+/**
+ * The panel's hardware display state, as reported by `hardwaredisplaystatechange`.
+ *
+ * There is no page-facing request for it: it is a CONSEQUENCE of the active rendering mode —
+ * a `viewCount === 1` mode puts the panel flat, the 2-view mode puts it back.
+ */
+export type XRHardwareDisplayMode = '2d' | '3d';
+
+/**
+ * What the glasses-free display physically is. Resolved by {@link TileHandle.getDisplayInfo};
+ * `null` there means the machine has no such display.
+ *
+ * `recommendedViewScaleX/Y` are **advisory**. The browser cannot resize a page's canvas, so
+ * nothing applies them for you — a page honours them by sizing its own backing store. Ignoring
+ * them costs sharpness or fill rate, never correctness.
+ */
+export interface XRDisplayInfo {
+  displayWidthMeters: number;
+  displayHeightMeters: number;
+  displayPixelWidth: number;
+  displayPixelHeight: number;
+  recommendedViewScaleX: number;
+  recommendedViewScaleY: number;
+}
+
+/**
+ * One rendering mode the DISPLAY can be put in, as reported by the runtime.
+ *
+ * The list is the display's, not the browser's. The DisplayXR Browser renders exactly **two**
+ * views — no view synthesis exists anywhere in the stack — so a mode needing MORE than two is
+ * reported with `isRequestable: false` and {@link TileHandle.requestRenderingMode} refuses it.
+ * Show such rows (they are what the panel can do) but mark them unavailable. A `viewCount === 1`
+ * mode IS requestable: the browser still submits two views and the runtime still weaves them —
+ * it is the PANEL that goes flat, which is how a page reaches the 2D hardware state.
+ */
+export interface XRDisplayRenderingMode {
+  modeIndex: number;
+  name: string;
+  /** @deprecated the browser reports `name`; kept for pages written against the earlier build. */
+  modeName?: string;
+  viewCount: number;
+  /** Per-view render scale the runtime recommends for this mode — advisory, like the display's. */
+  viewScaleX: number;
+  viewScaleY: number;
+  tileColumns: number;
+  tileRows: number;
+  viewWidthPixels: number;
+  viewHeightPixels: number;
+  /** True for a glasses-free 3D mode; false for a flat one. */
+  hardwareDisplay3D: boolean;
+  isActive: boolean;
+  /** False when the browser cannot drive it — in practice, `viewCount > 2`. */
+  isRequestable: boolean;
+}
+
+/** A rendering mode went active. Re-emitted on the wall and on every tile handle. */
+export interface RenderingModeChange {
+  type: 'renderingmodechange';
+  /** The mode now active, or -1 if the browser named none and the list could not be read. */
+  modeIndex: number;
+  /** Its view count — the thing the automatic rig collapse turns on. Null if unknown. */
+  viewCount: number | null;
+  /** The full mode row, when it could be read back. */
+  mode: XRDisplayRenderingMode | null;
+  /** The browser's own event payload, unreshaped. */
+  detail: unknown;
+}
+
+/** The panel's hardware display state changed. */
+export interface HardwareDisplayStateChange {
+  type: 'hardwaredisplaystatechange';
+  state: XRHardwareDisplayMode | null;
+  detail: unknown;
+}
+
+export type DisplayModeChange = RenderingModeChange | HardwareDisplayStateChange;
+
+/** What a page may lift into the floating native viewer. `null` = no `XRDisplayLayer.undock`. */
+export interface UndockCapabilities {
+  model: boolean;
+  splat: boolean;
+}
+
+export interface UndockOptions {
+  /** Absolute https URL (or http on loopback) of the asset the NATIVE viewer loads. */
+  src: string;
+  type: 'model' | 'splat';
+  /** Lighting the page rendered with, so the viewer can match it. */
+  env?: 'room' | 'studio' | 'sky' | 'none';
+  /** The angle the page opened the asset at, so the undocked view opens at the same one. */
+  pose?: { yaw: number; pitch?: number; zoom?: number };
+  /** The page's fit margin, when it overrides the default. */
+  margin?: number;
+  title?: string;
+}
+
+export interface UndockHandle {
+  /**
+   * Resolves when the viewer exits. On the protocol FALLBACK it resolves immediately and
+   * `detached` is true — a protocol launch is fire-and-forget and the page never hears back.
+   */
+  ended: Promise<void>;
+  viewer: 'model' | 'splat';
+  detached: boolean;
+  /** The `displayxr-view:` URL, on the fallback path only. */
+  url?: string;
+}
+
 /** Extra options for {@link Inline3D.addScene}. */
 export interface SceneOptions extends TileOptions {
   /**
@@ -115,8 +223,63 @@ export interface TileHandle {
    * identity-posed camera rig and parent your eye cameras under the app camera
    * (`cameraRigFromCamera(THREE, cam, { attach: true })` + `EyeCamera.setLocalFromView`), so the
    * scene graph supplies this frame's world pose with no lag at all.
+   *
+   * While a `viewCount === 1` mode is active the rig is stored **as given** and pushed **flat**
+   * (a copy with `ipdFactor`/`parallaxFactor` at 0), so a page driving a rig every frame cannot
+   * walk out of 2D, and the 2-view mode going active restores exactly this rig.
    */
   setViewRig(rig: XRViewRigInit): boolean;
+  /**
+   * The panel this window weaves on, or `null` where there is no glasses-free display.
+   *
+   * Rejects with an `Error` on a browser without the display-mode API
+   * ({@link inline3dDisplayModesSupported}) or while this window has no live layer (lazy mode,
+   * tile off screen).
+   */
+  getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /**
+   * Ask the runtime to switch the display to `modeIndex`. A thin pass-through — it resolves and
+   * rejects exactly as the browser does.
+   *
+   * Rejects with a `TypeError` for a mode whose `viewCount > 2` (the browser is fixed at two
+   * views) or an unknown index — the browser raises those synchronously, and this pass-through
+   * turns them into rejections so one `.catch()` covers every failure — and with a
+   * `NotSupportedError` `DOMException` when the request was not forwardable. Success is signalled
+   * by the session's `renderingmodechange` event, not by this promise.
+   *
+   * A `viewCount === 1` mode is requestable and is how a page goes flat.
+   */
+  requestRenderingMode(modeIndex: number): Promise<void>;
+  /**
+   * SUGAR over {@link TileHandle.requestRenderingMode}: `false` requests the first mode with
+   * `viewCount === 1 && isRequestable`, `true` the first with `viewCount === 2 && isRequestable`.
+   * It never touches the hardware display state directly (there is no such call) and never
+   * touches your rig.
+   *
+   * **The rig collapse is not part of this call.** When a 1-view mode actually goes ACTIVE the
+   * SDK zeroes every window's `ipdFactor`/`parallaxFactor` on the way to the layer and restores
+   * them when a 2-view mode does — driven by `renderingmodechange`, so it happens however the
+   * mode changed, and a **refused request changes nothing in either direction**. The flattening
+   * is a copy pushed at the layer, never a write into your descriptor, so the restore is literally
+   * the rig you last set — and it survives a per-frame `setViewRig` loop, a lazy tile rebuilding
+   * its layer, and a window that never set a rig at all.
+   *
+   * Rejects with an `Error` when no such mode is listed, otherwise as `requestRenderingMode` does.
+   */
+  setStereoEnabled(enabled: boolean): Promise<boolean>;
+  /** Listen for one display event, re-emitted on this handle. Returns an unsubscribe function. */
+  on(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): () => void;
+  on(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): () => void;
+  /** Drop a listener registered with {@link TileHandle.on}. */
+  off(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): void;
+  off(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): void;
+  /**
+   * Both display events through one callback — the older shape, still supported. Returns an
+   * unsubscribe function; inert (a no-op unsubscribe) on a browser without the API.
+   */
+  onDisplayModeChange(cb: (e: DisplayModeChange) => void): () => void;
   /**
    * Per-window frame counters, for diagnosing the load-induced mono fallback.
    *
@@ -141,6 +304,37 @@ export interface Inline3D {
   /** Number of currently-active (weaving) windows. */
   readonly liveCount: number;
 
+  // The panel is the DOCUMENT's, not a tile's, so the display API lives here; the same names are
+  // on every tile handle, routed to whichever window currently holds a live layer.
+
+  /** The panel, or `null` where there is no glasses-free display. See {@link TileHandle.getDisplayInfo}. */
+  getDisplayInfo(): Promise<XRDisplayInfo | null>;
+  /** Every rendering mode the display can be put in. See {@link XRDisplayRenderingMode}. */
+  getRenderingModes(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /** Switch the display to `modeIndex`. See {@link TileHandle.requestRenderingMode}. */
+  requestRenderingMode(modeIndex: number): Promise<void>;
+  /** Sugar: `false` -> a 1-view mode, `true` -> the 2-view mode. See {@link TileHandle.setStereoEnabled}. */
+  setStereoEnabled(enabled: boolean): Promise<boolean>;
+  on(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): () => void;
+  on(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): () => void;
+  off(type: 'renderingmodechange', cb: (e: RenderingModeChange) => void): void;
+  off(type: 'hardwaredisplaystatechange', cb: (e: HardwareDisplayStateChange) => void): void;
+  /** As last REPORTED by `hardwaredisplaystatechange` — never what was last requested. */
+  readonly hardwareDisplayState: XRHardwareDisplayMode | null;
+  /** The active mode as last read/reported. `viewCount: 0` means "not read yet". */
+  readonly activeMode: { modeIndex: number; viewCount: number };
+  /** True while the SDK is holding every window's rig flat because a 1-view mode is active. */
+  readonly stereoCollapsed: boolean;
+
+  /**
+   * What this build can lift into the floating native viewer, or `null` on a browser with no
+   * `XRDisplayLayer.undock` — that null is what a page branches on. Read off the first live
+   * layer (`layer.getUndockCapabilities()`); `{model:false, splat:false}` is the pre-read value.
+   */
+  readonly undock: UndockCapabilities | null;
+  /** Re-read {@link Inline3D.undock} off a live layer. */
+  refreshUndock(): Promise<UndockCapabilities | null>;
+
   /** Weave a still side-by-side 3D photo from a URL or decoded image source. */
   addImage(
     canvas: HTMLCanvasElement,
@@ -272,6 +466,48 @@ export function inline3dOcclusionByDrawOrder(): boolean;
  */
 export function inline3dViewRigSupported(): boolean;
 
+/**
+ * True when this browser exposes the DISPLAY-MODE API — {@link TileHandle.getDisplayInfo},
+ * {@link TileHandle.getRenderingModes} and {@link TileHandle.requestRenderingMode}. Sync + cheap;
+ * implies {@link inline3DAvailable}.
+ *
+ * Reads a capability (all three methods present on `XRDisplayLayer.prototype`), never a version or
+ * UA string, and demands all three: a browser shipping half the set is one mid-implementation.
+ * Everything the API drives is optional enhancement, so branch on this only to decide whether to
+ * show display controls — the handle methods reject with a clear `Error` rather than throwing at
+ * import or create time.
+ */
+export function inline3dDisplayModesSupported(): boolean;
+
+/**
+ * True when this browser can undock through `XRDisplayLayer.undock()` — i.e. without the
+ * `displayxr-view:` protocol prompt the fallback needs. A page does not have to branch on it to
+ * undock (the helper falls back on its own); it is the probe for whether {@link Inline3D.undock}
+ * carries capabilities.
+ */
+export function inline3dUndockSupported(): boolean;
+
+/**
+ * Undock `target`'s asset into the floating native viewer over the desktop.
+ *
+ * **Call it synchronously inside the click.** Both paths need the transient user activation — the
+ * API path to be allowed at all, the fallback to get Chrome's protocol dialog — and an `await`
+ * before this call spends it.
+ *
+ * Rejects with an `Error` whose `name` is `'not-installed'`, `'src-not-allowed'`,
+ * `'no-activation'` or `'busy'`.
+ */
+export function undock(target: Element, opts: UndockOptions): Promise<UndockHandle>;
+
+/** True where a native DisplayXR viewer can exist at all (the viewers are Windows-only today). */
+export function undockAvailable(): boolean;
+
+/** The `displayxr-view:` URL the fallback path navigates to — exported for logging and tests. */
+export function undockUrl(el: Element, opts: UndockOptions): string;
+
+/** An element's rect in physical screen pixels — where the native viewer places its window. */
+export function tileScreenRect(el: Element): { x: number; y: number; w: number; h: number; dpr: number };
+
 /** Open the page's inline-3D session and return a manager you add windows to. */
 export function createInline3D(
   opts?: CreateInline3DOptions,
@@ -316,5 +552,17 @@ export interface XRDisplayLayer {
    * all on the browser that has it.
    */
   setViewRig?(rig: XRViewRigInit): void;
+  /**
+   * The display-mode API. All three optional for the same reason as `setViewRig`: their presence
+   * on the prototype IS the capability signal ({@link inline3dDisplayModesSupported}), and the
+   * SDK demands all three before treating the browser as supporting any of them.
+   */
+  getDisplayInfo?(): Promise<XRDisplayInfo | null>;
+  getRenderingModes?(): Promise<ReadonlyArray<XRDisplayRenderingMode>>;
+  /** Throws `TypeError` **synchronously** for `viewCount > 2` or an unknown index. */
+  requestRenderingMode?(modeIndex: number): Promise<void>;
+  /** Undock this layer's asset into the floating native viewer. Optional; same probe rule. */
+  undock?(init: UndockOptions): Promise<unknown>;
+  getUndockCapabilities?(): Promise<UndockCapabilities>;
   close(): void;
 }

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,
+  }));
+}