@displayxr/inline3d 1.29.0 → 1.31.0

package/call.d.ts

@@ -7,73 +7,30 @@
 // RFC 0003 C1: `mountCall(el, opts?)` (the one-line path, the wall from `sharedInline3D()`), the
 // `warning` event (`lift-not-bundled`), `key`; `<dxr-call>` is `./call/element`, and
 // `./call/full` is this entry with lift statically imported.
+// RFC 0003 C2 (§2): THIS is the public surface — what a page needs to run, observe and dress a
+// call. The test helpers that used to be exported here are internal (importable by file path
+// from `js/call/*.js`); 1.30 keeps them as `@deprecated` wrappers (the block at the end), 1.31
+// removes them. Options are grouped (`theme`, `invite`, `landing`, `liftOptions.max`), the camera
+// is `@displayxr/inline3d/camera` (`camera: cam`), and `diagnostics()` holds the debug data.
+//
+// The public surface of this file is pinned by test/api-snapshot: a change here fails `npm test`
+// until the snapshot is updated in the same change (`node tools/api-surface.mjs --update`).
 
-import type { Inline3D, Inline3DUnsupported, CreateInline3DOptions } from './index.js';
-
-/**
- * The `lift()` of `@displayxr/inline3d/lift`, as the call uses it: `lift(video, { mode: 'live',
- * wall, ui: 'none', convergence, priority, quality })` → a handle. Only the members below are
- * used; `setPriority` / `setConvergence` / `on` / `native` / `canvas` / `state` are optional.
- */
-export interface CallLiftHandle {
-  remove(): void;
-  setPriority?(p: LiftStreamPriority): boolean;
-  setConvergence?(x: 'auto' | number): void;
-  on?(type: string, cb: (d: any) => void): () => void;
-  readonly native?: boolean;
-  readonly woven?: boolean;
-  readonly state?: string;
-  readonly canvas?: HTMLCanvasElement;
-  readonly stats?: { provider?: string | null } & Record<string, unknown>;
-}
-export type CallLiftFunction = ((element: HTMLVideoElement, opts: Record<string, unknown> & {
-  mode: 'live';
-  wall: unknown;
-  ui: 'none';
-  convergence: 'auto' | number;
-  priority: LiftStreamPriority;
-}) => Promise<CallLiftHandle>) & { liftCapabilities?: (o?: { webFallback?: boolean }) => Promise<any> };
-
-/** A lifted stream's scheduling (the native provider's per-stream priority). */
-export type LiftStreamPriority = 'high' | 'normal' | 'low' | 'paused';
-
-/** Why a mono peer is not lifted (or `'lifted'`). */
-export type Mono3DReason = 'unavailable' | 'off' | 'lifted' | 'budget' | 'failed';
+import type { Inline3D, Inline3DUnsupported } from './index.js';
+import type { StereoCamera } from './camera.js';
 
 /** What a participant sends: a side-by-side pair (left eye left) or one flat picture. */
 export type CallFormat = 'sbs' | 'mono';
 
-/** How this page draws a remote participant (RFC §3). */
-export type CallRoute = 'woven-sbs' | 'flat-left' | 'flat' | 'lifted';
-
-/** A remote participant's connection state as the tile shows it. */
 /**
- * `'unreachable'`: known to exist but no connection for ~10 s — usually a network that needs a
- * relay (TURN). Sticky until it connects; retries continue in the background.
+ * A remote participant's connection state as the tile shows it. `'unreachable'`: known to exist
+ * but no connection for ~10 s — usually a network that needs a relay (TURN). Sticky until it
+ * connects; retries continue in the background.
  */
 export type PeerState = 'new' | 'connecting' | 'connected' | 'reconnecting' | 'unreachable' | 'left';
 
-/** The out-of-band 3D flag, sent on the data channel when it opens. A peer that sends none is mono. */
-export interface CallHello {
-  type: 'hello';
-  v: number;
-  format: CallFormat;
-  width: number | null;
-  height: number | null;
-  /** Camera baseline, mm. Needed (with `hfovDeg`) for automatic convergence. */
-  baselineMm: number | null;
-  /** Horizontal field of view of ONE eye, degrees. */
-  hfovDeg: number | null;
-  /** False for a raw stereo camera (the P1 default); true only after a calibrated rectify step. */
-  rectified: boolean;
-  sdk: string | null;
-}
-
-export interface CallCalibration {
-  baselineMm?: number;
-  hfovDeg?: number;
-  rectified?: boolean;
-}
+/** How THIS side shows a participant: a woven stereo pair, a mono peer lifted to 3D, or flat. */
+export type CallDisplay = '3D' | '2D→3D' | '2D';
 
 /**
  * The signalling seam. Any object with `join()` works — bring your own accounts / push service.
@@ -103,233 +60,345 @@ export interface SignalingSession {
   peers: string[];
   /** Short-lived TURN credentials minted by the server, if it has any. */
   iceServers?: RTCIceServer[];
+  /** Hosted service (RFC 0003 §5): the tier this session was admitted as. */
+  tier?: 'anon' | 'key';
+  /** Hosted service: the publishable key id this session is attributed to. */
+  key?: string;
+  /** Hosted service: why `iceServers` is (or is not) there — see {@link SignalingTurnStatus}. */
+  turn?: SignalingTurnStatus;
   send(to: string, data: unknown): void;
   leave(): void;
 }
 
+/** The hosted DisplayXR signalling server (`dxrSignaling()` with no URL). */
+export const DXR_SIGNAL_DEFAULT: string;
+/**
+ * The server's TURN decision for one session (`welcome.turn`, `dxr-signal/1`). `status` is the
+ * service-wide state of the monthly relay budget (`ok` / `degraded` / `off`); `reason` says why
+ * THIS session got no credentials: `unconfigured` (the server has no TURN — self-hosted), `budget`
+ * (anonymous session shed near the budget → `warning` `turn-shed`), `rate` (too many mints from
+ * this address → `turn-shed`), `cap` (the monthly cap → `error` `turn-cap`), `mint-failed`.
+ */
+export interface SignalingTurnStatus {
+  status: 'ok' | 'degraded' | 'off';
+  reason?: 'unconfigured' | 'budget' | 'cap' | 'rate' | 'mint-failed';
+  /** Credential lifetime, seconds, when minted. */
+  ttl?: number;
+}
+
 /**
  * The `dxr-signal/1` JSON-over-WebSocket client (protocol: signaling/README.md). `url` is your
  * server's base, e.g. `wss://signal.example.com` or `ws://localhost:8787` — the reference servers
- * are `signaling/worker.mjs` (Cloudflare) and `node signaling/dev-server.mjs`. There is no hosted
- * default yet, so the URL is required.
+ * are `signaling/worker.mjs` (Cloudflare) and `node signaling/dev-server.mjs`. No URL = the hosted
+ * server. `key`: a publishable key for the hosted service (public by design; sent on connect).
+ * The hosted server answers on more than one host (RFC 0003 §5g) and the adapter fails over
+ * between them on connect and reconnect by itself; `aliases` adds fallbacks for a self-hosted URL.
  */
-/** The hosted DisplayXR signalling server (`dxrSignaling()` with no URL). */
-export const DXR_SIGNAL_DEFAULT: string;
-export function dxrSignaling(url?: string, opts?: { WebSocket?: any; pingMs?: number; /** A publishable key for the hosted service (public by design; sent on connect). */ key?: string }): SignalingAdapter;
+export function dxrSignaling(
+  url?: string,
+  opts?: {
+    WebSocket?: any;
+    pingMs?: number;
+    /** A publishable key for the hosted service (public by design; sent on connect). */
+    key?: string;
+    /** Extra base URLs to fail over to when `url` is unreachable (the hosted default has its own). */
+    aliases?: string[];
+  }
+): SignalingAdapter;
 
+/** The eight named accents `theme.accent` takes (the same names `/player` uses). */
 export type CallAccent = 'azure' | 'violet' | 'magenta' | 'sunset' | 'amber' | 'lime' | 'mint' | 'ice';
 
+/**
+ * Every string the chrome shows, by key (docs/call.md lists them with their defaults). A partial
+ * map overrides any subset — which is also how the chrome is localised. `{var}` placeholders are
+ * filled by the module.
+ */
+export type CallStrings = Partial<Record<
+  | 'lobbyStartTitle' | 'lobbyJoinTitle' | 'lobbyFullTitle' | 'lobbyLeftTitle' | 'lobbyFullText' | 'lobbyText'
+  | 'cameraDefault' | 'kindBusy' | 'kindNone' | 'kindSbs' | 'kindMono'
+  | 'liftOff' | 'liftChecking' | 'liftMissing' | 'liftNoProvider' | 'liftNative' | 'liftWeb' | 'liftProven' | 'liftUnproven'
+  | 'start' | 'join' | 'rejoin' | 'retryCamera' | 'cameraSelect' | 'joining'
+  | 'waitingTitle' | 'waitingText' | 'inviteTitle' | 'inviteText' | 'inviteLink' | 'copyLink' | 'copied' | 'pressCopy' | 'qrLabel'
+  | 'banner2D' | 'bannerLink'
+  | 'mute' | 'unmute' | 'cameraOn' | 'cameraOff' | 'cameraRetry' | 'cameraBusyRetry' | 'depth' | 'invite' | 'leave'
+  | 'connecting' | 'reconnecting' | 'leftCall' | 'cameraOffPlate' | 'noCamera' | 'unreachable' | 'cameraBusy'
+  | 'you' | 'badge3D' | 'badge2D3D' | 'badge2D' | 'badgePending',
+  string
+>>;
+
+/**
+ * Theming (RFC 0003 §2). The colour / radius / font entries are written as CSS custom properties
+ * on the host (`--dxr-accent`, `--dxr-ink`, `--dxr-shell`, `--dxr-danger`, `--dxr-radius`,
+ * `--dxr-font`), which a stylesheet can set instead; the chrome also exposes `part` names
+ * (`bar`, `invite`, `badge`, `plate`, `lobby`, `banner`, `self`, `tile`, `grid`) — reached as
+ * `dxr-call [part="bar"]`, since the chrome is light DOM. Every one of these styles chrome only:
+ * a woven tile and its ancestors stay visually bare (woven-canvas rule 7), and no theme can reach
+ * them.
+ */
+export interface CallTheme {
+  /** A named accent or any CSS colour → `--dxr-accent`. Default `'azure'`. */
+  accent?: CallAccent | (string & {});
+  /** Text on chrome → `--dxr-ink`. */
+  ink?: string;
+  /** Chrome background → `--dxr-shell` (near-solid on purpose: no blur over the weave). */
+  shell?: string;
+  /** Leave / muted → `--dxr-danger`. */
+  danger?: string;
+  /** Chrome corner radius (px, or any CSS length) → `--dxr-radius`. Never applied to a tile. */
+  radius?: number | string;
+  /** Chrome font family → `--dxr-font`. */
+  font?: string;
+  /** Tile aspect (w/h) = the woven buffer's per-eye aspect. Default 16/9. */
+  tileAspect?: number;
+  /** Overrides for the chrome's text (also localisation). */
+  strings?: CallStrings;
+}
+
 export interface CallOptions {
   /**
    * The inline-3D manager to put the tiles on. `mountCall` defaults it to the document's shared
    * one (`sharedInline3D()`); `addCall` takes it as its first argument instead.
    */
   wall?: Inline3D | Inline3DUnsupported | null;
-  /** Default `dxrSignaling()` (the hosted DisplayXR server). Or `dxrSignaling(url)` to self-host,
-   *  or your own adapter. */
+  /**
+   * `'auto'` (default): the room in this page's `#room=` fragment, else a new one on join. Or a
+   * room id / invite link. Room ids are >= 96 random bits (generated ones: 128), base64url.
+   */
+  room?: 'auto' | (string & {});
+  /** Default `dxrSignaling()` (the hosted DisplayXR server). Or `dxrSignaling(url)` to self-host, or your own adapter. */
   signaling?: SignalingAdapter;
   /**
    * A publishable key for the hosted signalling service (`pk_…`, RFC 0003 §5a). Public by design
    * — it sits in page source — and only used when `signaling` is left at the default.
    */
   key?: string;
-  /**
-   * `'auto'` (default): the room in this page's `#room=` fragment, else a new one on join. Or a
-   * room id / invite link. Room ids are >= 96 random bits (generated ones: 128), base64url.
-   */
-  room?: 'auto' | string;
   /** Overrides the server's STUN/TURN list. Default: public STUN + the server's TURN, if any. */
   iceServers?: RTCIceServer[];
   /**
-   * `'auto'` (default): a device delivering > 2.5:1 frames is a stereo pair, sent as `'sbs'`;
-   * otherwise the default webcam, `'mono'`. A camera held by another process (e.g. an eye
-   * tracker: NotReadableError) is skipped, never fatal. `'stereo'` prefers the pair (falls back
-   * to mono), `'mono'` never probes, a string is a deviceId, a MediaStream is used as given with
-   * `format` declaring what it is.
+   * `'auto'` (default): the call opens the best camera through `@displayxr/inline3d/camera`
+   * (`openCamera({ prefer: 'auto' })`): a stereo device when one is present, else the default
+   * webcam; a camera held by another process (an eye tracker) is skipped, never fatal. `'stereo'`
+   * prefers the pair (falls back to mono), `'mono'` never probes, a string is a `deviceId`, a
+   * `MediaStream` is used as given with `format` declaring what it is, and a `StereoCamera` you
+   * opened yourself is used as is (and left open when the call ends).
    */
-  camera?: 'auto' | 'stereo' | 'mono' | string | MediaStream;
-  /** The format of a page-supplied `camera` stream. Default `'mono'` — 3D-ness is never guessed. */
+  camera?: 'auto' | 'stereo' | 'mono' | (string & {}) | MediaStream | StereoCamera;
+  /** The format of a page-supplied `MediaStream`. Default `'mono'` — 3D-ness is never guessed. */
   format?: CallFormat;
-  /** Sent in `hello`; enables automatic convergence on the receivers. */
-  calibration?: CallCalibration;
-  /**
-   * P2 seam: a calibrated rectification step for a raw stereo stream (needs the camera's
-   * intrinsics/extrinsics, which come from a plug-in or the runtime). Return a rectified SBS
-   * stream; the hello then says `rectified: true`. P1 ships none: the raw pair is sent.
-   */
-  rectify?: (stream: MediaStream, info: { width: number; height: number; deviceId: string | null; label: string }) => MediaStream | Promise<MediaStream>;
   /** Microphone (echo cancellation + noise suppression). Default true. */
   audio?: boolean;
-  /**
-   * Auto-convergence (default true): measure the disparity of the point between each SBS peer's
-   * eyes on the received frames and shift the two eyes by half of it each, so the remote person sits
-   * at the display plane. No calibration needed. The depth slider stays an offset on top; a peer's
-   * `hint` is used only while no measurement has succeeded. Lifted (mono) tiles are unaffected.
-   */
-  autoConverge?: boolean;
   /**
    * Lift mono peers to 3D on a 3D display (RFC §5). `'auto'` (default): import
    * `@displayxr/inline3d/lift` lazily from this copy of the SDK, and use it when it reports a
    * native provider or a WebGPU web fallback — otherwise mono peers stay flat (one log line, no
    * error). `'off'` / `false`: flat. A function: your own `lift` (a bundled app imports
-   * `lift` from `@displayxr/inline3d/lift` and passes it here). Switch at runtime with
-   * `setMono3D()`.
+   * `lift` from `@displayxr/inline3d/lift` and passes it here, or uses `./call/full`). Switch at
+   * runtime with `setMono3D()`.
    */
-  mono3D?: 'auto' | 'off' | false | CallLiftFunction;
+  mono3D?: 'auto' | 'off' | false | LiftFunction;
   /**
    * Extra `lift()` options for lifted tiles — e.g. `models` (where the depth model is served from),
-   * `ort`, `quality`, `providers`. The call's own keys (`mode`, `wall`, `ui`, `convergence`,
-   * `priority`) always win.
+   * `ort`, `quality`, `providers` — plus `max`: concurrent lifted tiles (default 4 = the mesh
+   * maximum; further mono peers stay flat). The call's own keys (`mode`, `wall`, `ui`,
+   * `convergence`, `priority`) always win.
    */
-  liftOptions?: Record<string, unknown>;
-  /** Concurrent lifted tiles. Default 4 (= the mesh maximum); further mono peers stay flat. */
-  maxLifted?: number;
+  liftOptions?: Record<string, unknown> & { max?: number };
+  /**
+   * Auto-convergence (default true): measure the disparity of the point between each SBS peer's
+   * eyes on the received frames and shift the two eyes by half of it each, so the remote person sits
+   * at the display plane. No calibration needed. The depth slider stays an offset on top.
+   */
+  autoConverge?: boolean;
   /** Participants INCLUDING you. Default 4, clamped to 2..4 (full mesh). */
   maxPeers?: number;
-  /** `'grid'` (default) or `'speaker'` (the active speaker spans the row). */
-  layout?: 'grid' | 'speaker';
-  /** SDK chrome: lobby, invite (link + QR), bottom bar, badges, banner. Default true. */
-  ui?: boolean;
-  /** Join without the lobby. Default: `!ui`. */
+  /**
+   * `'grid'` (default), `'speaker'` (the active speaker spans the row), or `'none'`: the module
+   * creates the tiles but does not position them — each carries `data-dxr-peer="<id>"` and
+   * `tile(id)` returns it, for the page's own CSS grid on the host.
+   */
+  layout?: 'grid' | 'speaker' | 'none';
+  /**
+   * SDK chrome. `true` (default): lobby, invite (link + QR), bottom bar, badges, plates, banner.
+   * `'tiles'`: badges and state plates only — your bar, the module's correct per-tile chrome.
+   * `false`: nothing. Tiles are module-owned in every mode (they are woven canvases).
+   */
+  ui?: boolean | 'tiles';
+  /** Join without the lobby. Default: true unless `ui` is `true`. */
   autoJoin?: boolean;
-  /** The small self view (mirrored; a stereo self view is mirrored AND eye-swapped). Default true. */
+  /** The small self view (mirrored; a stereo self view is mirrored AND eye-swapped — an `addCameraView`). Default true. */
   selfView?: boolean;
-  /** Tile aspect (w/h) = the woven buffer's per-eye aspect. Default 16/9. */
-  tileAspect?: number;
-  /** A named accent or any CSS colour, written to `--dxr-accent`. */
-  accent?: CallAccent | string;
-  /** Base URL of invite links (default: this page's URL, query kept, fragment replaced). */
-  inviteBase?: string;
-  /** Write `#room=` into this page's URL on join (so a reload rejoins). Default: `ui`. */
-  updateUrl?: boolean;
-  /** Where the "View in 3D with DisplayXR Browser" banner links. */
-  browserUrl?: string;
-  /** Re-open the inline-3D session if it ends without the page closing it. Default true. */
-  recoverSession?: boolean;
-  /** Scroll the call block to the top of the viewport once, on join, so every tile (and the self
-   *  view) is on screen and woven. Default true (only with `ui`). */
-  scrollIntoView?: boolean;
-  /** `createInline3D()` options for the wall `mountCall` creates, and for a session re-open. */
-  wallOptions?: CreateInline3DOptions;
+  /** Colours, radius, font, tile aspect and strings — see {@link CallTheme}. */
+  theme?: CallTheme;
+  /** Invite links: `base` (default this page's URL, query kept, fragment replaced); `updateUrl` writes `#room=` into the page URL on join (default: `ui === true`). */
+  invite?: { base?: string; updateUrl?: boolean };
+  /** The "see it in 3D" offer for recipients on ordinary browsers: `browserUrl` (where it links), `allow2D` (false = 3D-only kiosk pages). */
+  landing?: { browserUrl?: string; allow2D?: boolean };
+  /** Verbose console logging. `diagnostics()` has the rest. */
   debug?: boolean;
-  log?: (tag: string, detail: object) => void;
 }
 
+/**
+ * The `lift()` of `@displayxr/inline3d/lift`, as the call uses it: `lift(video, { mode: 'live',
+ * wall, ui: 'none', convergence, priority, quality })` → a handle it can `remove()`. Only the
+ * members below are used; everything else is optional.
+ */
+export type LiftFunction = ((element: HTMLVideoElement, opts: Record<string, unknown> & {
+  mode: 'live';
+  wall: unknown;
+  ui: 'none';
+  convergence: 'auto' | number;
+  priority: 'high' | 'normal' | 'low' | 'paused';
+}) => Promise<{
+  remove(): void;
+  setPriority?(p: 'high' | 'normal' | 'low' | 'paused'): boolean;
+  setConvergence?(x: 'auto' | number): void;
+  on?(type: string, cb: (d: any) => void): () => void;
+  readonly native?: boolean;
+  readonly state?: string;
+  readonly canvas?: HTMLCanvasElement;
+}>) & { liftCapabilities?: (o?: { webFallback?: boolean }) => Promise<any> };
+
+/** The documented shape of the `quality` event's `in` / `out` (values informative, shape stable). */
 export interface CallQuality {
   in: { width: number; height: number; fps: number; codec: string | null; kbps: number | null; dropped: number; decoder: string | null } | null;
   out: { width: number; height: number; fps: number; codec: string | null; kbps: number | null; limitation: string | null; encoder: string | null } | null;
 }
 
+/** A remote participant, as a page needs it. Debug data (hello, route, convergence, lift) is in `diagnostics()`. */
 export interface CallPeer {
   readonly id: string;
   readonly format: CallFormat;
-  readonly route: CallRoute | null;
+  readonly display: CallDisplay;
   readonly state: PeerState;
   readonly muted: boolean;
   readonly cameraOff: boolean;
   readonly speaking: boolean;
-  readonly rectified: boolean;
-  readonly hello: CallHello | null;
-  readonly quality: CallQuality | null;
-  /** The per-eye convergence shift currently painted, source px. */
-  readonly convergencePx: number;
-  /** Auto-convergence: measured disparity (source px; null until a lock), mean ms per measurement, last method. */
-  readonly autoConverge: { disparityPx: number | null; ms: number | null; readMs: number | null; method: 'mode' | 'focus' | 'track' | null; via: 'videoframe' | 'canvas' | null };
-  /** A lifted tile: whether lift is showing yet, native or web, and its current priority. */
-  readonly lift: { readonly live: boolean; readonly native: boolean; readonly priority: LiftStreamPriority | null; readonly state: string | null } | null;
 }
 
-export interface CallMono3DInfo {
-  readonly on: boolean;
-  readonly state: 'off' | 'idle' | 'loading' | 'ready' | 'unavailable';
-  /** Why it is unavailable: `'import-failed'`, `'no-lift-export'`, `'no-provider'`, `'no-webgpu'`. */
-  readonly reason: string | null;
-  /** From `liftCapabilities()` when the lift module has it; null when unknown. */
-  readonly native: boolean | null;
-  readonly provider: string | null;
-  readonly lifted: number;
-  readonly max: number;
-  /** A lift has gone live in this call. */
-  readonly proven: boolean;
-}
+/**
+ * `error` codes — fatal for a feature, never for the widget. `'camera-busy'` (held by another
+ * app: audio-only until `retryCamera()`), `'no-camera'`, `'permission-denied'`, `'unreachable'`
+ * (`error.peer` = the tile), `'room-full'`, `'session-ended'`, `'signaling-closed'`,
+ * `'signaling-unreachable'`, `'join-failed'`, `'camera-failed'`, `'rectify-failed'`,
+ * `'mount-failed'` (the element). From the hosted signalling service (RFC 0003 §5, C3):
+ * `'rate-limited'` / `'quota'` (a limit of the anonymous or keyed tier — the join is refused;
+ * `error.retryMs` says when a retry may work), `'bad-key'` / `'origin-not-allowed'` (the
+ * publishable key is unknown, revoked, or not allowed from this page's origin), `'blocked'`,
+ * `'expired'` (the room's lifetime is up), and `'turn-cap'` (the service's monthly relay budget
+ * is spent: the call still joins and direct connections work, but nobody gets TURN — not fatal).
+ */
+export type CallErrorCode =
+  | 'camera-busy'
+  | 'no-camera'
+  | 'permission-denied'
+  | 'unreachable'
+  | 'room-full'
+  | 'session-ended'
+  | 'signaling-closed'
+  | 'join-failed'
+  | 'camera-failed'
+  | 'rectify-failed'
+  | 'mount-failed'
+  | 'signaling-unreachable'
+  // Hosted signalling service (RFC 0003 §5, C3).
+  | 'rate-limited'
+  | 'quota'
+  | 'bad-key'
+  | 'origin-not-allowed'
+  | 'blocked'
+  | 'expired'
+  | 'turn-cap'
+  | (string & {});
+
+/** `warning` codes — degraded, not broken. */
+export type CallWarningCode = 'lift-not-bundled' | 'turn-shed' | (string & {});
 
 export interface CallEvents {
+  joined: { room: string; id: string };
+  /** `reason`: `'left'` (you called `leave()` / the element was removed) or `'pagehide'`. */
+  left: { room: string | null; reason: string };
   peer: { id: string };
   peerleft: { id: string; reason: string };
-  format: { id: string; format: CallFormat; route: CallRoute; mono3d: Mono3DReason | null; hello: CallHello | null };
+  state: { id: string; state: PeerState };
+  /** How this side shows a participant changed (a hello arrived, lift went live, the wall came back). */
+  display: { id: string; display: CallDisplay };
+  speaker: { id: string | null };
   /**
    * Per peer (`id`) every 2 s; or, with `id: null` and `lift`, when lifted tiles on the web
    * provider degrade the page's frame rate (~< 20 fps for 3 s) and when it recovers.
    */
   quality: ({ id: string } & CallQuality) | ({ id: null; in: null; out: null; lift: { degraded: boolean; frameMs: number; tiles: number } });
-  speaker: { id: string | null };
-  /** Codes include `'camera-busy'`, `'no-camera'`, `'unreachable'` (error.peer = the tile id), `'room-full'`, `'session-ended'`. */
-  error: { code: string; message: string; error: Error | null };
+  error: { code: CallErrorCode; message: string; error: Error | null };
   /**
-   * Degraded, not broken. `'lift-not-bundled'`: a 2D participant is on a 3D display, `mono3D`
-   * is `'auto'`, and the lift module could not be imported from this build (a bundler that could
-   * not follow the computed import, or a copy of the SDK without `./lift`) — they stay flat. Fix:
-   * `import { lift } from '@displayxr/inline3d/lift'` and pass `mono3D: lift`, or import
-   * `@displayxr/inline3d/call/full`. Emitted once per call, the first time such a peer routes,
-   * with one `console.warn`. A display that honestly cannot lift is NOT this: that is
-   * `handle.mono3D.reason` (`'no-provider'` / `'no-webgpu'`) and an info line.
+   * `'lift-not-bundled'`: a 2D participant is on a 3D display, `mono3D` is `'auto'`, and the lift
+   * module could not be imported from this build — they stay flat. Fix: `mono3D: lift` or
+   * `./call/full`. Emitted once per call with one `console.warn`. A display that honestly cannot
+   * lift is NOT this: that is `handle.mono3D.reason` (`'no-provider'` / `'no-webgpu'`).
+   * `'turn-shed'`: only THIS session got no TURN from the hosted service (an anonymous session
+   * while the monthly relay budget is nearly spent, or too many credential requests from this
+   * address this hour); the call runs STUN-only. A publishable key keeps TURN.
    */
-  warning: { code: 'lift-not-bundled' | string; message: string };
-  state: { id: string; state: PeerState };
-  joined: { room: string; id: string };
-  left: { room: string };
-  session: { wall: unknown };
+  warning: { code: CallWarningCode; message: string };
 }
 
 export interface CallHandle {
   readonly room: string | null;
   readonly id: string;
-  readonly state: 'idle' | 'lobby' | 'joining' | 'in-call' | 'full' | 'left';
-  readonly wall: unknown;
-  readonly format: CallFormat | null;
+  readonly state: 'lobby' | 'joining' | 'in-call' | 'full' | 'left';
+  /** `'busy'` = held by another app (e.g. eye tracking): the call runs audio-only until `retryCamera()`. */
+  readonly camera: 'ok' | 'busy' | 'none' | 'pending';
+  /** What YOU send; null before a camera opened. */
+  readonly localFormat: CallFormat | null;
   readonly muted: boolean;
+  readonly cameraOff: boolean;
   readonly depth: number;
   readonly speaker: string | null;
-  /** `'busy'` = held by another app (e.g. eye tracking): the call runs audio-only until `retryCamera()`. */
-  readonly camera: 'ok' | 'busy' | 'none' | 'pending';
-  /** mono→3D status (see {@link CallMono3DInfo}). */
-  readonly mono3D: CallMono3DInfo;
   /** Read-only snapshot of the remote participants. */
   readonly peers: ReadonlyArray<CallPeer>;
-  join(): Promise<CallHandle>;
+  /** mono→3D status. `reason` when unavailable: `'import-failed'`, `'no-lift-export'`, `'no-provider'`, `'no-webgpu'`. */
+  readonly mono3D: { readonly on: boolean; readonly state: 'off' | 'idle' | 'loading' | 'ready' | 'unavailable'; readonly reason: string | null; readonly provider: string | null; readonly lifted: number; readonly max: number };
+  join(): Promise<void>;
+  leave(): void;
   /** `…#room=<id>` — the room rides in the fragment, which never reaches a server. Null before a room exists. */
   inviteLink(): string | null;
   /** Mute (true), unmute (false) or toggle (no argument). Returns the new state. */
   mute(on?: boolean): boolean;
-  cameraOff(on?: boolean): boolean;
-  setCamera(idOrStream: string | MediaStream, opts?: { format?: CallFormat }): Promise<{ format: CallFormat; width: number; height: number; label: string }>;
+  /** Camera off (true), on (false) or toggle. Returns the new state (`cameraOff` reads it). */
+  setCameraOff(on?: boolean): boolean;
+  /** Switch cameras: a `deviceId`, a `MediaStream` (+ `format`), or a `StereoCamera`. Keeps the current one on failure. */
+  setCamera(src: string | MediaStream | StereoCamera, opts?: { format?: CallFormat }): Promise<{ format: CallFormat; width: number; height: number; label: string }>;
+  /** Try the configured camera again (e.g. after the eye tracker released it). */
+  retryCamera(): Promise<{ format: CallFormat; width: number; height: number; label: string }>;
   /**
    * The ONE depth control, [-1, 1] (+ = push back). Stereo tiles: ± 5% of the eye width added to
    * the automatic convergence. Lifted tiles: lift's convergence (0 → `'auto'`, else 0.5 + 0.5·v).
    */
   setDepth(v: number | null): number;
-  /** Try the configured camera again (e.g. after the eye tracker released it). Keeps the current one on failure. */
-  retryCamera(): Promise<{ format: CallFormat; width: number; height: number; label: string }>;
-  /** Send `hint {subjectZmm}` (rate-limited to 5 Hz) if the page can estimate the face distance. */
-  sendHint(subjectZmm: number): boolean;
   /** Turn mono→3D on/off at runtime (no argument toggles). Off releases every lift; tiles go flat. */
   setMono3D(on?: boolean): boolean;
-  leave(): void;
+  /** A participant's tile element (for `layout: 'none'`), or null. Style it in place; never move it. */
+  tile(peerId: string): HTMLElement | null;
   on<K extends keyof CallEvents>(type: K, cb: (e: CallEvents[K]) => void): () => void;
   off<K extends keyof CallEvents>(type: K, cb: (e: CallEvents[K]) => void): void;
+  /** Explicitly UNSTABLE: the wall, the transport, per-peer hello / route / convergence / lift / quality, the lift pool. For devtools. */
+  diagnostics(): Record<string, unknown>;
 }
 
-export function addCall(wall: unknown, container: HTMLElement, opts?: CallOptions): Promise<CallHandle>;
+export function addCall(wall: Inline3D | Inline3DUnsupported | null, container: HTMLElement, opts?: CallOptions): Promise<CallHandle>;
 
 /**
  * The one-line path (RFC 0003 §1): `addCall` with every argument optional. The wall is
- * `opts.wall` if given, else the document's shared manager (`sharedInline3D(opts.wallOptions)` —
- * the page's existing session, never a second one). Hosted signalling, `camera: 'auto'` and the
- * SDK chrome by default; resolves once the lobby shows (or, with `autoJoin` / `ui: false`, once
- * joined). `<dxr-call>` (`@displayxr/inline3d/call/element`) is this as markup.
+ * `opts.wall` if given, else the document's shared manager (`sharedInline3D()` — the page's
+ * existing session, never a second one). Hosted signalling, `camera: 'auto'` and the SDK chrome
+ * by default; resolves once the lobby shows (or, with `autoJoin` / `ui: false`, once joined).
+ * `<dxr-call>` is this as markup.
  */
 export function mountCall(el: HTMLElement, opts?: CallOptions): Promise<CallHandle>;
 
+/** The room in an invite link (or a `location`), or null — for an SPA router to read the room without mounting a call. */
+export function parseInviteLink(link: string | { hash?: string; href?: string } | null | undefined): string | null;
+
 // ── <dxr-call> — the one-line path as markup ───────────────────────────────────────────────
 //
 // Importing this entry (or `./call/full`, or the CDN bundle `dist/call.js`) registers the element.
@@ -337,14 +406,14 @@ export function mountCall(el: HTMLElement, opts?: CallOptions): Promise<CallHand
 // disconnect (a DOM move IS a teardown — woven-canvas rule 2), re-dispatches every call event as
 // a bubbling, composed `CustomEvent` named `dxr-call:<event>` with the payload in `detail`, and
 // exposes the handle as `el.call`. Attributes (read once, at connect): `room`, `signaling` (a
-// URL), `key`, `camera`, `layout`, `accent`, `max-peers`, `no-ui`, `auto-join`, `mono3d="off"`,
-// `no-audio`, `no-self-view`, `no-auto-converge`, `tile-aspect`, `invite-base`, `browser-url`,
-// `debug`. Everything else is `el.options`, set before connect; options win over attributes.
+// URL), `key`, `camera`, `layout`, `accent`, `max-peers`, `no-ui`, `ui="tiles"`, `auto-join`,
+// `mono3d="off"`, `no-audio`, `no-self-view`, `no-auto-converge`, `tile-aspect`, `invite-base`,
+// `browser-url`, `debug`. Everything else is `el.options`, set before connect; options win.
 
 export class DxrCallElement extends HTMLElement {
   /** The mount seam: null = `mountCall` of `./call`; `./call/full` sets its own. */
   static mount: ((el: HTMLElement, opts?: CallOptions) => Promise<CallHandle>) | null;
-  /** Non-string options (a `MediaStream`, an adapter, `lift`, a `wall`) — set BEFORE connecting. */
+  /** Non-string options (a `MediaStream`, an adapter, `lift`, a `wall`, a `theme`) — set BEFORE connecting. */
   options: CallOptions | null;
   /** The handle once mounted; null before, and again after disconnect. */
   readonly call: CallHandle | null;
@@ -378,77 +447,88 @@ declare global {
   interface HTMLElementEventMap extends DxrCallEventMap {}
 }
 
-// ── pure helpers (exported for tests and advanced pages) ──────────────────────────────────
+// ── DEPRECATED (1.30 only) — the 1.29 exports that left the public surface in C2 ─────────
+//
+// Each is INTERNAL (RFC 0003 §2): still importable by file path from `js/call/*.js` /
+// `js/camera/*.js`, kept on this entry for one release as a wrapper that `console.warn`s once,
+// removed in 1.31. Do not write new code against them.
+
+/** @deprecated internal — js/call/options.js; removed from this entry in 1.31 */
 export function normalizeCallOptions(opts?: Partial<CallOptions>): Record<string, unknown>;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export function newRoomId(getRandomValues?: (a: Uint8Array) => Uint8Array): string;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export function isValidRoomId(room: unknown): boolean;
-export function parseInviteLink(link: string | { hash?: string; href?: string } | null | undefined): string | null;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 (`handle.inviteLink()` is the API) */
 export function buildInviteLink(base: string, room: string): string;
-export function normalizeHello(msg: unknown): CallHello | null;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 (the wire is a protocol: docs/call-wire.md) */
+export function normalizeHello(msg: unknown): { type: 'hello'; v: number; format: CallFormat; width: number | null; height: number | null; baselineMm: number | null; hfovDeg: number | null; rectified: boolean; sdk: string | null } | null;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export function makeHello(o?: { format?: CallFormat; width?: number; height?: number; baselineMm?: number; hfovDeg?: number; rectified?: boolean }): object;
-export function routeFor(p: { format?: string | null; woven: boolean; mono3D?: 'auto' | 'off' | false | CallLiftFunction; lift?: boolean; overBudget?: boolean; failed?: boolean }): { route: CallRoute; mono3d?: Mono3DReason };
-export function badgeFor(route: CallRoute | null): '3D' | '2D→3D' | '2D';
-export function normalizeMono3D(v: unknown): 'auto' | 'off' | CallLiftFunction;
-export function resolveLift(
-  mono3D: 'auto' | 'off' | false | CallLiftFunction,
-  o?: { importer?: () => Promise<any>; nav?: any; log?: (tag: string, o: object) => void; capsOpts?: object },
-): Promise<{ lift: CallLiftFunction | null; capabilities: ((o?: object) => Promise<any>) | null; caps: any; source: 'injected' | 'module' | 'none'; reason: string | null }>;
-export function liftConvergenceFor(depth: number | null | undefined): 'auto' | number;
-export function liftPriorityFor(p: { id: string | null; speakerId: string | null; visible?: boolean }): LiftStreamPriority;
-/** The hook for the native provider's per-stream priority: forwards to `handle.setPriority` (no-op without one). */
-export function setLiftPriority(handle: CallLiftHandle | null | undefined, level: LiftStreamPriority): boolean;
-export function defaultLiftSpecifier(base?: string): string;
-export const LIFT_PRIORITY: Readonly<{ speaker: 'high'; other: 'normal'; hidden: 'paused' }>;
-export function createFrameWatch(o?: { degradedMs?: number; recoveredMs?: number; holdMs?: number; alpha?: number }): {
-  feed(dtMs: number): 'degraded' | 'recovered' | null;
-  reset(): void;
-  readonly frameMs: number | null;
-  readonly degraded: boolean;
-};
-export interface CallLiftPool {
-  readonly size: number;
-  max: number;
-  has(id: string): boolean;
-  handle(id: string): CallLiftHandle | null;
-  priority(id: string): LiftStreamPriority | null;
-  canAcquire(id: string): boolean;
-  acquire(id: string, element: HTMLVideoElement, o?: { wall?: unknown; visible?: boolean; onError?: (e: unknown) => void }): Promise<CallLiftHandle | null>;
-  release(id: string): void;
-  releaseAll(): void;
-  setSpeaker(id: string | null): void;
-  setVisible(id: string, visible: boolean): void;
-  setDepth(v: number): 'auto' | number;
-  readonly anyWeb: boolean;
-  list(): Array<{ id: string; priority: LiftStreamPriority | null; pending: boolean; native: boolean }>;
-}
-export function createLiftPool(o: { lift: CallLiftFunction; max?: number; log?: (tag: string, o: object) => void; options?: Record<string, unknown> }): CallLiftPool;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 (`CallPeer.display` is the API) */
+export function routeFor(p: { format?: string | null; woven: boolean; mono3D?: 'auto' | 'off' | false | LiftFunction; lift?: boolean; overBudget?: boolean; failed?: boolean }): { route: 'woven-sbs' | 'flat-left' | 'flat' | 'lifted'; mono3d?: string };
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
+export function badgeFor(route: 'woven-sbs' | 'flat-left' | 'flat' | 'lifted' | null): CallDisplay;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
+export function createLiveGate(o?: { need?: number; needNoPose?: number }): { feed(viewCount: number | null): boolean; readonly live: boolean };
+/** @deprecated internal — js/camera/converge.js; removed in 1.31 */
 export function convergenceShiftPx(p: { eyeWidthPx: number; hfovDeg?: number | null; baselineMm?: number | null; subjectZmm?: number | null }): number;
+/** @deprecated internal — js/camera/converge.js; removed in 1.31 */
 export function lowPass(prev: number, target: number, alpha?: number): number;
-/** The disparity (left x − right x, input px) of the point between the eyes in a grayscale SBS frame. */
-export function measureFocusDisparity(
-  img: ArrayLike<number>,
-  W: number,
-  H: number,
-  o?: { focus?: { x: number; y: number }; block?: number; dMin?: number; dMax?: number; dyMax?: number; minNcc?: number },
-): { d: number; x: number; y: number; c: number; method: 'focus' | 'mode'; blocks: number } | null;
+/** @deprecated internal — js/camera/converge.js; removed in 1.31 */
 export function clampShift(px: number, eyeWidthPx: number, maxFraction?: number): number;
+/** @deprecated internal — js/camera/geometry.js; removed in 1.31 */
 export function eyeCropRect(eyeW: number, eyeH: number, aspect: number, shift: number, eye: 0 | 1): { sx: number; sy: number; sw: number; sh: number };
+/** @deprecated internal — js/camera/geometry.js; removed in 1.31 (`addCameraView` of `/camera` mirrors a self view) */
 export function mirrorSwapOps(W: number, H: number): Array<{ src: 'L' | 'R'; sx: number; sw: number; sy: number; sh: number; dx: number; dw: number; mirror: true }>;
+/** @deprecated internal — js/camera/geometry.js; removed in 1.31 */
 export function mirrorSwapPixels<T extends ArrayLike<number>>(px: T, W: number, H: number): T;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export function maxBitrateKbps(format: CallFormat, remotePeers: number): number;
+/** @deprecated internal — js/camera/disparity.js; removed in 1.31 (`autoConverge` is the behaviour) */
+export function measureFocusDisparity(img: ArrayLike<number>, W: number, H: number, o?: { focus?: { x: number; y: number }; block?: number; dMin?: number; dMax?: number; dyMax?: number; minNcc?: number }): { d: number; x: number; y: number; c: number; method: 'focus' | 'mode'; blocks: number } | null;
+/** @deprecated internal — js/call/sdp.js; removed in 1.31 */
 export function preferVideoCodecs(sdp: string, order?: readonly string[]): string;
+/** @deprecated internal — js/call/sdp.js; removed in 1.31 */
 export function sortCodecCapabilities<T extends { mimeType?: string }>(codecs: T[], order?: readonly string[]): T[];
+/** @deprecated internal — js/call/sdp.js; removed in 1.31 */
 export const VIDEO_CODEC_ORDER: readonly string[];
+/** @deprecated internal — js/call/transport.js; removed in 1.31 (an SFU adapter will get a designed Transport seam) */
+export class MeshTransport {
+  constructor(o: { signaling: SignalingAdapter; id: string; maxPeers?: number; iceServers?: RTCIceServer[]; RTCPeerConnection?: any; log?: (tag: string, obj: object) => void });
+  readonly size: number;
+}
+/** @deprecated internal — js/call/transport.js; removed in 1.31 */
 export function clampMaxPeers(n?: number): number;
+/** @deprecated internal — js/call/qr.js; removed in 1.31 */
 export function qrEncode(text: string, opts?: { ecl?: 'L' | 'M'; mask?: number }): { version: number; size: number; mask: number; modules: boolean[][] };
+/** @deprecated internal — js/call/signaling.js; removed in 1.31 (documented in signaling/README.md) */
 export function roomKey(room: string): Promise<string>;
+/** @deprecated internal — js/call/signaling.js; removed in 1.31 */
 export const SIGNAL_PROTOCOL: string;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export const WIRE_VERSION: number;
+/** @deprecated internal — js/call/wire.js; removed in 1.31 */
 export const CALL_SDK: string;
+/** @deprecated replaced by `theme.strings`; removed in 1.31 */
 export const PLATE_TEXT: Readonly<{ unreachable: string; cameraBusy: string }>;
-export function createLiveGate(o?: { need?: number; needNoPose?: number }): { feed(viewCount: number | null): boolean; readonly live: boolean };
+/** @deprecated folded into `theme.accent` (which takes the names); removed in 1.31 */
 export const CALL_ACCENTS: Readonly<Record<CallAccent, string>>;
-export class MeshTransport {
-  constructor(o: { signaling: SignalingAdapter; id: string; maxPeers?: number; iceServers?: RTCIceServer[]; RTCPeerConnection?: any; log?: (tag: string, obj: object) => void });
-  readonly size: number;
-}
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function normalizeMono3D(v: unknown): 'auto' | 'off' | LiftFunction;
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function resolveLift(mono3D: 'auto' | 'off' | false | LiftFunction, o?: { importer?: () => Promise<any>; nav?: any; log?: (tag: string, o: object) => void; capsOpts?: object }): Promise<{ lift: LiftFunction | null; capabilities: ((o?: object) => Promise<any>) | null; caps: any; source: 'injected' | 'module' | 'none'; reason: string | null }>;
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function createLiftPool(o: { lift: LiftFunction; max?: number; log?: (tag: string, o: object) => void; options?: Record<string, unknown> }): { readonly size: number; max: number; has(id: string): boolean; release(id: string): void; releaseAll(): void; [k: string]: unknown };
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function createFrameWatch(o?: { degradedMs?: number; recoveredMs?: number; holdMs?: number; alpha?: number }): { feed(dtMs: number): 'degraded' | 'recovered' | null; reset(): void; readonly frameMs: number | null; readonly degraded: boolean };
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function liftConvergenceFor(depth: number | null | undefined): 'auto' | number;
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function liftPriorityFor(p: { id: string | null; speakerId: string | null; visible?: boolean }): 'high' | 'normal' | 'low' | 'paused';
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function setLiftPriority(handle: { setPriority?(p: 'high' | 'normal' | 'low' | 'paused'): boolean } | null | undefined, level: 'high' | 'normal' | 'low' | 'paused'): boolean;
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export function defaultLiftSpecifier(base?: string): string;
+/** @deprecated internal — js/call/lift.js; removed in 1.31 */
+export const LIFT_PRIORITY: Readonly<{ speaker: 'high'; other: 'normal'; hidden: 'paused' }>;