@displayxr/inline3d 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,145 @@ 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.5.0 — 2026-09-06
+
+### Added
+
+- **The 2D↔3D switch is EASED, and every page gets it for free.** 1.4.0 made the panel's mode a
+  page-facing control and collapsed the stereo rig the moment a 1-view mode went active — correct,
+  and a snap. The transition now ramps: a **page-initiated** switch walks every window's
+  `ipdFactor`/`parallaxFactor` between 0 and what the page asked for over **180 ms**, **smoothstep**
+  (Hermite `3t^2 - 2t^3`) — the defaults the native DisplayXR apps configure, because this is a port
+  of the sequencer they already use (`dxr::ModeSwitch`, displayxr-common) rather than a second
+  design. New dependency-free module `js/inline3d-mode-switch.js` holds the state machine;
+  `test/mode-switch.test.mjs` mirrors the C++ smoke test case for case. *(core tier — additive)*
+
+- **The ORDER is the feature, and it is asymmetric.** Going flat (a `viewCount === 1` target) ramps
+  the disparity **out first** and forwards the mode request only when it lands, so the panel flips
+  on already-flat content instead of snapping a stereo image flat. Coming back (a 2-view target)
+  forwards the request **first** and eases the disparity in **only once the panel REPORTS 3D** —
+  ramping up any earlier would put stereo on a still-flat panel, which is the blurry double image
+  the whole mode API exists to make unreachable. A hand-rolled tween gets exactly this wrong.
+
+- **`createInline3D({ modeSwitch: { durationMs, easing, enabled } })`** — `durationMs` default
+  `180` (`0` keeps the ordering and lands in one frame), `easing` default `'smoothstep'` (also
+  `'linear'`, `'easeoutcubic'`; an unknown name warns once and falls back), `enabled: false`
+  restores 1.4.0's snap exactly. **`wall.modeSwitch`** is the read-only live state
+  `{active, factor}` for a page that wants to move its own 2D chrome alongside the panel. The SDK
+  adds **no UI** — which key or button toggles the display stays the page's call.
+  *(core tier — additive)*
+
+- **What a page can feel, spelled out.** The restore is to the **configured** steady factors (each
+  window's own rig, never a hardcoded 1) and the ramp is a **copy** on the way to the layer, so the
+  1.4.0 guarantees hold unchanged: a per-frame `setViewRig` loop cannot walk the page out of 2D,
+  and a lazy tile that rebuilds mid-transition comes back at the current factor. The ramp is driven
+  by **wall-clock dt** from the session's frame loop (never frame counts, so it lasts the same at
+  30 fps and 144 fps), with a timer fallback so a held request still lands when frames stop.
+  Reversing mid-flight retargets from the disparity **in force** — the first press never snaps —
+  and a reversed going-flat switch **never fires**: nothing is asked of the display at all.
+
+### Changed
+
+- **`requestRenderingMode(i)` / `setStereoEnabled(false)` for a 1-view target now resolve when the
+  request has been FORWARDED**, i.e. after the ramp (~`durationMs`), not on the call. They reject
+  as before if the browser refuses — and a refusal ramps the disparity back **up**, because a
+  refused switch must leave the page in 3D rather than flat. One new failure: a request dropped by
+  a reversal before it ever fired rejects with an `Error` named **`superseded`**. Nothing changes
+  for a page that only awaits the promise it already awaited; `{ enabled: false }` restores the old
+  timing. *(core tier — behaviour change, opt-out)*
+
+- A mode change the page did **not** request (another tab, the shell, a page that opens with the
+  panel already flat) still **snaps** — there is nothing to ramp from, and the reported state stays
+  the sole authority for the rig. `wall.stereoCollapsed` continues to mean what the display last
+  **reported**, never what is mid-ramp.
+
+## 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,68 @@ 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.
+   *
+   * With the eased transition on (the default — see {@link ModeSwitchOptions}) a going-flat
+   * request is HELD while the disparity ramps out, so the promise resolves when the request has
+   * been forwarded rather than on the call; a request dropped by a reversal in that window
+   * rejects with an `Error` named `superseded`.
+   */
+  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 +309,44 @@ 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;
+  /**
+   * The eased 2D<->3D transition, live. `factor` is what every window's
+   * `ipdFactor`/`parallaxFactor` is being multiplied by on the way to the layer (`1` in 3D, `0`
+   * flat, in between mid-ramp); `active` is true while a page-initiated switch is in any of its
+   * phases. Read-only and purely informational — the SDK adds no UI of its own for this.
+   */
+  readonly modeSwitch: { active: boolean; factor: number };
+
+  /**
+   * 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,
@@ -217,6 +423,41 @@ export interface CreateInline3DOptions {
    * SDK never touches your DOM's `will-change`, because the chrome already occludes the tiles.
    */
   autoChrome?: boolean;
+  /** The eased 2D<->3D transition. On by default; see {@link ModeSwitchOptions}. */
+  modeSwitch?: ModeSwitchOptions;
+}
+
+/**
+ * The eased 2D<->3D transition — on by default, and the same sequencer (and the same defaults)
+ * the native DisplayXR apps use.
+ *
+ * Instead of snapping the stereo rig the moment the panel's mode changes, a **page-initiated**
+ * switch ramps every window's `ipdFactor`/`parallaxFactor` between 0 and what the page asked for,
+ * in the order that looks right:
+ *
+ * - **going flat** (a `viewCount === 1` target): the disparity ramps OUT first, and the mode
+ *   request is forwarded only when it lands — so the panel flips on already-flat content. That is
+ *   why `requestRenderingMode()` / `setStereoEnabled(false)` resolve a ramp later than they used
+ *   to: they resolve when the request has actually been forwarded.
+ * - **coming back** (a 2-view target): the request goes out at once, and the disparity eases in
+ *   only once the panel REPORTS 3D — disparity on a still-flat panel is the double image the
+ *   whole mode API exists to prevent.
+ *
+ * Interruptible: pressing the toggle again mid-ramp retargets from the disparity in force, and
+ * reversing a going-flat switch that has not fired yet simply ramps back up without ever asking
+ * the panel for anything (the dropped request rejects with an `Error` named `superseded`).
+ *
+ * A mode change the page did **not** request (another tab, the shell, a panel that opens flat)
+ * always snaps — there is nothing to ramp from. This is aesthetic policy only; correctness is the
+ * runtime's either way.
+ */
+export interface ModeSwitchOptions {
+  /** Ramp duration in ms (default `180`, matching the native default of 0.18 s). `0` = instant. */
+  durationMs?: number;
+  /** Easing curve (default `'smoothstep'`, Hermite `3t^2 - 2t^3`). */
+  easing?: 'smoothstep' | 'linear' | 'easeoutcubic';
+  /** `false` restores the plain snap of 1.4.0 (default `true`). */
+  enabled?: boolean;
 }
 
 /** The return of {@link startInline3D}. */
@@ -272,6 +513,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 +599,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;
 }