@displayxr/inline3d 1.47.5 → 1.48.0

package/docs/content-lifecycle-rules.md

@@ -0,0 +1,270 @@
+# Content lifecycle rules: release what a swap replaces
+
+Companion to [`authoring-inline-3d.md`](authoring-inline-3d.md) and
+[`woven-canvas-rules.md`](woven-canvas-rules.md). Those pages keep a woven canvas alive and
+joined. This one covers what happens to the GPU over the life of that canvas, when the page swaps
+content in and out of it: a product carousel, a catalogue, a gallery that loads glTF after glTF.
+
+The symptom is slow and silent. Nothing on the page looks wrong. The browser's **GPU process**
+grows by a few megabytes a minute for as long as the page is open, until the machine runs short
+of memory. The rules below come from a production page that grew about **8 MB/min** this way on a
+Linux laptop. They were then checked against the PlayCanvas 2.22.3 and three.js 0.180 sources, and
+measured against this SDK's own swap paths (§5).
+
+---
+
+## 1. What leaks, and why it costs so much
+
+Every distinct material set a page draws makes the engine **link a WebGL program**: one per
+material variant (lighting, skinning, maps, pass). A linked program is not just a handle. The
+driver keeps its compiled form for as long as the program exists. On one Linux driver (Mesa, integrated
+graphics) that was **about 5 MB per live program**, measured with an allocation tracer on the
+browser's GPU process: the outstanding allocations were the linked program's IR, freed only by
+`glDeleteProgram`. The production page linked about four new programs per product and deleted
+none, so each product it showed left 15–25 MB behind for the life of the page.
+
+What the page saw as "swapping a product" was, to the GPU, *adding* one. The page destroyed the
+entity and its materials, and the engine kept every program those materials had linked.
+
+## 2. Engine facts
+
+### PlayCanvas (2.22.3)
+
+- **`ProgramLibrary` caches every program for the device's life.** Its cache is keyed by the
+  variant's options. An entry leaves only when that `Shader` is destroyed (`Shader.destroy()`),
+  or when the device is.
+- **`Material.destroy()` destroys no program.** It empties `material.variants` and clears each
+  mesh instance's per-pass cache (its bind groups and uniform buffers), and that is all. Once it
+  has run, the material no longer even says which programs it had.
+- **`Asset.unload()` on a glTF container** destroys the container's textures, meshes and
+  materials (each material through `Material.destroy()`, so no program again). **The registry
+  shares one container per URL** between every caller that loads it.
+- **One `Shader` per key, shared.** Two materials with the same options get the same `Shader`
+  object from the library. Destroying it under one of them breaks the other.
+- **The compiled shaders outlive their program.** `WebglShader.destroy()` deletes the program and
+  nothing else. The vertex and fragment shaders it was linked from stay in a module-private
+  `CompiledShaderCache` (keyed by source) until the device is destroyed. So even a page that
+  destroys its programs keeps two compiled shaders per program it ever linked.
+- **`app.destroy()` frees everything.** It unloads every asset, clears the program library
+  (destroying each program) and destroys the device, which deletes the cached shaders.
+
+### three.js (0.180)
+
+- **Programs are reference-counted per material.** The renderer listens for each material's
+  `dispose` event. `material.dispose()` releases that material's programs
+  (`WebGLPrograms.releaseProgram`), and the last material out deletes the program
+  (`gl.deleteProgram`). Materials that compile to the same program share it.
+- **There is no compiled-shader cache to leak.** `WebGLProgram` deletes its two shaders right
+  after linking.
+- **Nothing is freed by taking an object out of the scene,** or by dropping the last reference to
+  it. Call `geometry.dispose()`, `material.dispose()` and `texture.dispose()` for each texture.
+  `material.dispose()` does not dispose the textures it uses.
+- **`renderer.info.programs.length`** is the live program count: the pass test of §4, for free.
+
+## 3. The rules
+
+### 1. Release everything a swap replaces, not just the entity
+
+A swap replaces five things: the **entity**, its **materials**, the **programs** those materials
+linked, their **textures**, and the **container** they came from. Destroying the entity releases
+the first. Unloading the container releases the textures, meshes and materials. The engine
+releases the programs for nobody.
+
+**On a PlayCanvas tile the SDK created, it releases the programs for you** (from the release
+after 1.47.5): when the page destroys a material, directly or through the container's
+`asset.unload()`, the SDK destroys the programs that material linked one frame later, when
+nothing still in the app uses them (rules 2 and 3, done automatically; see §6). So the page's
+part is the engine's own teardown: **destroy the entity, and destroy or unload what it drew
+with.** `entity.destroy()` alone is not enough. A container that stays loaded keeps its
+materials alive, and a live material keeps its programs on purpose, because the page may show it
+again.
+
+On a PlayCanvas tile, content you add under `handle.engine.root` is released in one call:
+
+```js
+const prev = shown;                                    // { entity, asset } of the outgoing product
+const { programs, container } = handle.releaseEntity(prev.entity, { asset: prev.asset });
+```
+
+`releaseEntity` (on `addSplat(…, { engine: 'playcanvas' })` and PlayCanvas `addModel`
+handles) does rules 2 to 4 in that call, including the container's last-user check of rule 4,
+and the SDK does rule 5 on its own devices. Without it, the page unloads the container itself
+(rule 4) and the automatic release above covers the programs. On a three.js scene, traverse and dispose (§2, three.js).
+
+### 2. Collect the programs before you destroy anything
+
+`Material.destroy()` empties `material.variants`, and the container's unload destroys its
+materials. Read `variants` of every material the entity's mesh instances use (and each mesh
+instance's own shader cache), and of the container's materials, **first**. Then destroy the entity,
+then unload the container, then destroy the programs.
+
+### 3. Destroy only a program nothing else still draws with
+
+Because the library hands one `Shader` to every material with the same key, a program you collected
+may also belong to content that stays. Before `shader.destroy()`, look at what is still in the app:
+every mesh instance under `app.root` (enabled or not), every layer's mesh instances, and every
+material asset still in the registry. Destroy only what none of them holds. `Shader.destroy()` is
+the engine's own release: it deletes the program and takes it out of the library, so the next ask
+for that variant compiles it again rather than returning a dead one.
+
+### 4. Unload a container with its last user
+
+The registry shares one container per URL, so two products loaded from the same file share
+textures and materials. Unload it (`app.assets.remove(asset); asset.unload()`) only when nothing
+left in the scene draws from it: refcount your holders, or check that no remaining mesh instance
+uses one of its meshes or materials (what `releaseEntity` does: it reports `container: 'in-use'`
+and leaves it loaded).
+
+### 5. Let the engine give compiled shaders back
+
+Rule 3 deletes the programs. The compiled shaders behind them stay in the engine's
+`CompiledShaderCache` (§2), so a page that follows rules 1–4 still keeps two compiled shaders for
+every program it ever linked (measured in §5: shaders 10 → 91 over 24 swaps, programs bounded).
+The fix counts, per cached shader, the programs that use it, and deletes the shader when the last
+one is destroyed. **The SDK applies it to every PlayCanvas device it creates** (see §6). A page that
+runs its own PlayCanvas app outside the SDK has to patch the engine itself: the change is about 20
+lines in `src/platform/graphics/webgl/webgl-shader.js` (a count in `_compileShaderSource`, a
+release in `WebglShader.destroy`, cleared on context loss). `js/inline3d-pc-shader-cache.js` is the
+reference.
+
+### 6. On three.js, dispose explicitly, and textures separately
+
+Removing a mesh from the scene frees nothing on the GPU. For each object a swap replaces, call
+`geometry.dispose()`, `material.dispose()`, and `dispose()` on every texture the material uses
+(`map`, `normalMap`, …). The renderer then deletes a program when its last material is disposed.
+Do not dispose a geometry, material or texture that content which stays still uses.
+
+### 7. Fewer variants is cheaper than releasing them
+
+Each distinct option set is a program. A catalogue whose items share one material set (the same
+maps, the same lighting) links once and swaps meshes and textures. A catalogue of hand-made
+materials links per item. Releasing keeps the second kind bounded, but every swap then compiles
+again, which costs a frame or more of main-thread time on first draw: warm the incoming content
+before you show it (`handle.warmEntity`, [PlayCanvas adapter § warmEntity](playcanvas-adapter.md#warmentity--a-gltfs-first-draw-without-the-freeze)).
+
+### 8. Removing the tile is not a content swap
+
+`handle.remove()` on a PlayCanvas tile destroys the app, and with it every program, shader,
+texture and asset (measured in §5: nothing left). But a new tile is a new canvas for the browser's
+compositor to join, with the raw side-by-side window that brings
+([woven-canvas rules 2 and 3](woven-canvas-rules.md#2-never-remount-a-woven-canvas-inside-a-screen)).
+Keep the tile and swap what is in it, with rules 1–5.
+
+## 4. The pass test: hook, swap, plateau
+
+Count program and shader creation on the context, swap content about ten times, and check that the
+live count (`created − deleted`) **plateaus**. A page that leaks climbs with every new item. A page
+that releases goes up and down around what is on screen.
+
+```js
+// Run before the page creates its WebGL context (inject at document start, e.g. with the
+// DevTools protocol's Page.addScriptToEvaluateOnNewDocument, then reload).
+const live = (globalThis.__glLive = { programs: 0, shaders: 0 });
+for (const Ctx of [WebGLRenderingContext, WebGL2RenderingContext]) {
+  const p = Ctx.prototype;
+  const count = (name, key, step) => {
+    const orig = p[name];
+    p[name] = function (...args) {
+      const r = orig.apply(this, args);
+      if (step > 0 ? r : args[0]) live[key] += step; // a create that returned an object; a delete of one
+      return r;
+    };
+  };
+  count('createProgram', 'programs', +1);
+  count('deleteProgram', 'programs', -1);
+  count('createShader', 'shaders', +1);
+  count('deleteShader', 'shaders', -1);
+}
+// Swap content ten times, reading __glLive after each swap: it must level off.
+```
+
+Two things to know when reading it:
+- **Content that repeats plateaus anyway.** The engine reuses a cached program for a variant it has
+  already linked, so a carousel of eight products stops growing after the eighth even without a
+  release. Test with more distinct items than the page will show at once, or with real catalogue
+  data.
+- **The SDK's own transitions compile once.** The first `setSource` with each transition kind
+  links its programs, and later swaps reuse them: a few rises, then flat.
+
+**`?dxrdiag` does this for you on a PlayCanvas tile.** The diagnostics overlay shows
+`gl programs N live (+created −deleted)  shaders N live (…)  cache patched`, and the dump
+(`copy(__dxrDiag.dump())`) carries the same under `glObjects`. At every content swap the SDK can
+see (a `setSource`, a glTF container loaded into the tile's registry, a `releaseEntity`), it samples
+the live program count. When the count has not dropped across the last 10 swaps of one kind and
+rose at more than 60% of them, it warns once in the console. It costs nothing when diag is off.
+`?dxrdiag=keepshaders` turns rule 5 off for an A/B (page-wide; set it on the URL before the first
+tile loads). The overlay also shows `release patched (−N)`: programs the automatic release of
+rule 1 destroyed. `?dxrdiag=keepprograms` turns that off for an A/B (per tile). Details: [PlayCanvas adapter § Diagnosing transition stalls](playcanvas-adapter.md#diagnosing-transition-stalls-diag--dxrdiag-36).
+
+## 5. Measured: the SDK's own paths
+
+DisplayXR Browser on Linux (Chromium 156, Mesa, integrated graphics), PlayCanvas 2.22.3, the hook of §4,
+Khronos glTF sample models. "Live" is `created − deleted` after each step.
+
+| path | before this release | with this release |
+|---|---|---|
+| `addModel` → `remove()` → `addModel` on the same canvas, 10–12 times over 4 models | live 0 programs / 0 shaders after every `remove()` (60 created, 60 deleted) | same: nothing leaks |
+| glTF swapped under `handle.engine.root`, page destroys the entity and unloads the container (rule 1 without the programs), 24 distinct models | programs 5 → 47, shaders 10 → 91; `deleteProgram` never called | same: the page never destroys a program, so nothing the SDK does can free it. `?dxrdiag` warns at the 10th swap |
+| the same swaps with `handle.releaseEntity(entity, { asset })` | n/a | programs between 5 and 16 (the model on screen), shaders exactly twice that; back to 5 / 10 after the last release |
+| the same, `?dxrdiag=keepshaders` (rule 5 off) | n/a | programs bounded (5–16), shaders 10 → 91: the engine's compiled-shader cache alone |
+| `setSource` × 12–16 on one splat (cut, crossfade, wavefront, flip in turn) | +6 programs over the first pass of the four transitions, then flat | same |
+| `setVideo(src)` / `setVideo(null)` × 6 | +1 program on the first, then flat | same |
+
+**The automatic program release (rule 1), measured.** DisplayXR Browser on macOS (Chromium 156,
+Apple silicon), PlayCanvas 2.22.3, the hook of §4. A PlayCanvas `addModel` tile; each swap adds a
+product with its own material options (a distinct program) under `handle.engine.root`, and
+destroys the outgoing entity and its material: the engine's own teardown, no `releaseEntity`.
+
+| 24 swaps | live programs (created) | live shaders |
+|---|---|---|
+| automatic release (default) | 2 (25 created, 23 deleted) | 4 |
+| `?dxrdiag=keepprograms` (the engine as it ships) | 25 (25 created, 0 deleted) | 50 |
+
+The same pattern in a production kiosk app (one persistent PlayCanvas stage, content swapped per
+screen, entities, materials and textures destroyed, no program ever released) went from 0 to 170
+live programs over 28 screen changes before this release.
+
+So the SDK's own swaps (`setSource`, `setVideo`, `prepareSource().dispose()`, `remove()`) release
+what they replace, and content a page adds under `handle.engine.root` is the page's, with
+`releaseEntity` to do it. On the production page, releasing the outgoing product's programs and
+container plus the shader-cache fix took the GPU process from **+9.1 MB/min to flat** over a soak,
+with live programs and shaders steady and every product still rendering when it came round again.
+
+## 6. What the SDK does for you, and what the page still owns
+
+| | SDK | page |
+|---|---|---|
+| `handle.remove()` (PlayCanvas `./splat`, `./model`) | destroys the app: every entity, asset, program, shader and texture on the tile | nothing |
+| `handle.remove()` (three.js `./model`) | disposes the model's geometries, materials and textures | anything the page added to the scene |
+| `setSource` | the outgoing asset (entity destroyed, asset unloaded a few frames later); its own transition programs are compiled once and reused | nothing |
+| `setVideo(null)`, `prepareSource().dispose()` | the plane / the prepared asset | nothing |
+| compiled shaders (rule 5) | on every PlayCanvas device the SDK creates | a PlayCanvas app the page creates itself |
+| programs of a material the page destroys (rule 1) | on every PlayCanvas app the SDK creates, a frame after the destroy, when nothing else uses them | a PlayCanvas app the page creates itself (rules 2–3 by hand) |
+| content under `handle.engine.root` | `handle.releaseEntity(entity, { asset })` when the page calls it | destroying the entity and destroying or unloading what it drew with (or calling `releaseEntity`) |
+| `addScene` (three.js or raw WebGL) | nothing: the renderer is the page's | rule 6 |
+
+**How the shader-cache fix rides along with the engine.** PlayCanvas is the page's own peer
+dependency (an import map, a bundler, a CDN build), never a file this package ships, so the SDK
+cannot patch it on disk. `js/inline3d-pc-shader-cache.js` replaces two methods on the engine's
+`WebglShader` prototype at run time, once, through the first shader the device creates. It
+installs only on the 2.22.x shape (an `_compileShaderSource(device, src, isVertexShader)` reading a
+cache keyed by source, and a `destroy` that does not delete shaders), and otherwise steps aside and
+reports why in `?dxrdiag` (`cache skipped: …`). On an engine bump: re-read `webgl-shader.js`; if it
+still never deletes a compiled shader before device destroy, keep the fix and update its shape
+check and `test/pc-shader-cache.test.mjs` (a copy of the 2.22.3 class shape). If upstream releases
+shaders itself, the check makes the fix a no-op, and it can be deleted.
+
+**How the program release rides along with the engine.** `js/inline3d-pc-auto-release.js` wraps
+two methods on the engine's `Material` prototype, once: `getShaderVariant` (the one place a
+material links a program) records the material weakly on its device, and `destroy` collects the
+material's programs before the engine empties `variants`. Both act only on devices the SDK
+created; a PlayCanvas app the page runs itself is untouched. At the app's next `frameend` (a
+timer backs that up for a stopped app) it destroys each collected program that no mesh instance
+in the app, no material asset in the registry and **no still-alive material** holds. The last
+condition is what makes it safe: the library hands one `Shader` to every material with the same
+key, and a material the page keeps off-scene to show again still has it in its `variants`.
+`Shader.destroy()` also drops the program from the library, so content shown again recompiles on
+its first draw (`handle.warmEntity` hides that). It installs only on the 2.22.x shape (a
+`getShaderVariant` and a `destroy` that clears `variants`) and otherwise reports
+`release skipped: …` in `?dxrdiag`. On an engine bump: re-read `material.js` and
+`mesh-instance.js`'s `getShaderInstance`; keep `test/pc-auto-release.test.mjs` in step.

package/docs/woven-canvas-rules.md

@@ -196,14 +196,23 @@ tile while its content keeps running (for a video: sound, no picture). To put bl
 tile, give it to an element **behind** the canvas. A cover you mean to hide the tile with (rule 5,
 rule 11) is the one deliberate exception, and it comes off on a signal.
 
-### 10. No `backdrop-filter` on anything drawn over the weave
-
-Rule 7 covers the canvas and its ancestors. This one covers the **siblings on top of it**: a
-control bar, a caption, a badge, a menu. `backdrop-filter` is defined as a function of what is
-behind the element, and behind it is the interlaced weave. A blur reads the interlaced pixels
-and smears them, and the 3D image is disturbed across the element's **whole box**, not only
-where the element is opaque (seen on the panel, 24 September). Use a plain translucent tint
-(`background: rgba(0, 0, 0, 0.55)`) instead. The SDK's own player chrome follows this rule.
+### 10. `backdrop-filter` over the weave: only on DisplayXR Browser 0.1.16+, never over a whole tile
+
+Rule 7 covers the canvas and its ancestors, and is unchanged. This one covers the **siblings on
+top of it**: a control bar, a caption, a badge, a menu. `backdrop-filter` is defined as a function
+of what is behind the element, and behind it is the interlaced weave. On browsers before
+DisplayXR Browser 0.1.16 the blur reads the interlaced pixels and smears them, and the 3D image is
+disturbed across the element's **whole box**, not only where it is opaque (seen on the panel, 24
+September). From 0.1.16 the compositor draws the tile **mono inside each frost rect**
+(displayxr-browser#120), so frosted chrome over a tile looks right: the frosted region is flat,
+the rest of the tile stays 3D. [`samples/composition`](../samples/composition/) (its sticky
+header) is the validated case.
+
+- Frost a **partial** region only (a bar, a pill). Never frost a whole tile while it is visible:
+  the whole tile goes mono under it.
+- If the page must also run on older browsers, use a plain translucent tint
+  (`background: rgba(0, 0, 0, 0.55)`) there. The SDK's own chrome (player, call) keeps its
+  near-solid tint so one build works on every generation.
 
 ### 11. Treat a resize as a fresh-canvas moment
 
@@ -331,11 +340,14 @@ for exactly that reason). It cannot check the join. On a DisplayXR display:
 Found on hardware in a production photo app after the rules above were written. Each one looked
 like a runtime or browser bug on the panel and turned out to be the page.
 
-- **No `backdrop-filter` on chrome that sits over the weave.** Rule 7 covers effects on the canvas
-  and its ancestors. A frosted bar or button placed *over* a woven tile is a different element, but
-  on a lenticular laptop panel it visibly disturbs the 3D image across that element's whole rect.
-  Use a plain translucent tint instead (a solid `rgba()` background). Keep an A/B switch for the
-  blurred variant if the design wants it back, and judge it on the panel, not on a 2D monitor.
+- **`backdrop-filter` on chrome that sits over the weave (superseded for 0.1.16+).** Rule 7 covers
+  effects on the canvas and its ancestors. A frosted bar or button placed *over* a woven tile is a
+  different element; on browsers before DisplayXR Browser 0.1.16 it visibly disturbed the 3D image
+  across that element's whole rect on a lenticular laptop panel, and the fix was a plain
+  translucent tint. Since 0.1.16 the compositor draws the tile mono inside each frost rect
+  (displayxr-browser#120), so partial frosted chrome is fine there (`samples/composition` is the
+  validated case); still never frost a whole visible tile ([rule 10](#10-backdrop-filter-over-the-weave-only-on-displayxr-browser-0116-never-over-a-whole-tile)).
+  Judge it on the panel, not on a 2D monitor.
 - **Nothing opaque above the woven canvas.** Stacking order still applies: an element with an
   opaque background painted *above* the canvas hides it, and on a draw-order browser that is
   exactly what you get. The classic case is a full-bleed video plane under a page `<main>` with

package/js/call/element.js

@@ -37,7 +37,7 @@ import { mountCall, dxrSignaling } from '../inline3d-call.js';
 
 /** Every call event is re-dispatched as `dxr-call:<type>`; `dxr-call:ready` carries the handle. */
 export const CALL_EVENT_PREFIX = 'dxr-call:';
-const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'display', 'speaker', 'quality', 'error', 'warning'];
+const CALL_EVENTS = ['joined', 'left', 'peer', 'peerleft', 'state', 'display', 'speaker', 'quality', 'error', 'warning', 'name', 'message', 'signal', 'weave', 'speaking'];
 const TAG = '[inline3d/call] <dxr-call>';
 
 /** A boolean attribute: present is true, unless its value spells "false"/"0"/"off"/"no". */
@@ -71,8 +71,10 @@ const str = (v) => (v === null || v === undefined || String(v).trim() === '' ? u
  * | `no-audio`           | `audio: false`                           |
  * | `no-self-view`       | `selfView: false`                        |
  * | `no-auto-converge`   | `autoConverge: false`                    |
+ * | `no-send-convergence`| `sendConvergence: false`                 |
  * | `cursor="depth"`     | `cursor: 'depth'`                        |
- * | `tile-aspect`        | `theme.tileAspect` (a number, or `w/h`)  |
+ * | `tile-aspect`        | `theme.tileAspect` (a number, `w/h`, or `fill`) |
+ * | `name`               | `name` (your display name)               |
  * | `invite-base`        | `invite.base`                            |
  * | `browser-url`        | `landing.browserUrl`                     |
  * | `debug`              | `debug: true`                            |
@@ -102,9 +104,11 @@ export function attrsToOpts(source) {
   if (isOn(get('no-audio'))) o.audio = false;
   if (isOn(get('no-self-view'))) o.selfView = false;
   if (isOn(get('no-auto-converge'))) o.autoConverge = false;
+  if (isOn(get('no-send-convergence'))) o.sendConvergence = false;
   if (str(get('cursor')) === 'depth') o.cursor = 'depth';
   // The C2 groups (RFC 0003 §2): the attribute names are the C1 ones, the option shapes are new.
-  const theme = { accent: str(get('accent')), tileAspect: num(get('tile-aspect')) };
+  put('name', str(get('name')));
+  const theme = { accent: str(get('accent')), tileAspect: str(get('tile-aspect')) === 'fill' ? 'fill' : num(get('tile-aspect')) };
   if (theme.accent !== undefined || theme.tileAspect !== undefined) o.theme = Object.fromEntries(Object.entries(theme).filter(([, v]) => v !== undefined));
   if (str(get('invite-base'))) o.invite = { base: str(get('invite-base')) };
   if (str(get('browser-url'))) o.landing = { browserUrl: str(get('browser-url')) };

package/js/call/options.js

@@ -3,7 +3,7 @@
 // 1.29 spellings accepted for one release with a warning. Pure (no DOM, no network) — see
 // test/call.test.mjs. Internal: importable by path, not part of the `./call` entry.
 
-import { isValidRoomId, parseInviteLink, DEFAULT_MAX_PEERS } from './wire.js';
+import { isValidRoomId, parseInviteLink, DEFAULT_MAX_PEERS, sanitizeName } from './wire.js';
 import { clampMaxPeers } from './transport.js';
 import { normalizeMono3D } from './lift.js';
 import { dxrSignaling } from './signaling.js';
@@ -53,7 +53,10 @@ export function normalizeCallOptions(opts = {}) {
   const ui = opts.ui === undefined ? true : opts.ui === 'tiles' ? 'tiles' : !!opts.ui;
   const chrome = ui === true;
   const tileAspect = theme.tileAspect !== undefined ? theme.tileAspect : opts.tileAspect;
-  const aspect = typeof tileAspect === 'number' && tileAspect > 0.3 && tileAspect < 4 ? tileAspect : 16 / 9;
+  // 'fill': each tile's per-eye aspect is its own stage box (the page sizes the tiles).
+  const aspect = tileAspect === 'fill' ? 'fill' : typeof tileAspect === 'number' && tileAspect > 0.3 && tileAspect < 4 ? tileAspect : 16 / 9;
+  const layout = opts.layout === 'speaker' ? 'speaker' : opts.layout === 'none' ? 'none' : 'grid';
+  const tileCover = opts.tileCover === 'auto' || opts.tileCover === 'off' ? opts.tileCover : layout === 'none' ? 'auto' : 'off';
   let room = opts.room === undefined || opts.room === null ? 'auto' : opts.room;
   if (room !== 'auto' && !isValidRoomId(room)) {
     const fromLink = parseInviteLink(room);
@@ -90,6 +93,10 @@ export function normalizeCallOptions(opts = {}) {
     // peer's eyes and shift the eyes so it sits at the display plane. The depth slider stays an
     // offset on top. Off = the pair as sent (plus any `hint`).
     autoConverge: opts.autoConverge === undefined ? true : !!opts.autoConverge,
+    // Sender side of auto-convergence (docs/call.md): with a stereo camera, measure that disparity
+    // on this side's own raw frames and send it to every peer (`conv` on the data channel), so
+    // receivers apply it instead of measuring the compressed frames. Off = receivers measure.
+    sendConvergence: opts.sendConvergence === undefined ? true : !!opts.sendConvergence,
     // `cursor: 'depth'` (runtime ADR-046 on a pair): the arrow comes in front of a person who pops
     // out of the screen under it, measured off each stereo tile's two halves; else the plain OS
     // arrow on the plane. Off by default (zero cost).
@@ -102,7 +109,15 @@ export function normalizeCallOptions(opts = {}) {
     // Concurrent lifted tiles (`liftOptions.max`). Default = maxPeers (4): every mono peer can be lifted.
     maxLifted: Number.isFinite(+maxLiftedRaw) && maxLiftedRaw !== null && maxLiftedRaw !== undefined ? Math.max(0, Math.min(DEFAULT_MAX_PEERS, Math.floor(+maxLiftedRaw))) : DEFAULT_MAX_PEERS,
     // 'grid' | 'speaker' | 'none' (the page lays the tiles out; handle.tile(id) finds them).
-    layout: opts.layout === 'speaker' ? 'speaker' : opts.layout === 'none' ? 'none' : 'grid',
+    layout,
+    // The core's rect cover on every woven tile (and a stereo self view): 'auto' covers a tile
+    // across a resize or move until it is woven again. Default 'auto' with layout: 'none' (the
+    // page moves and resizes the tiles), 'off' otherwise (the module's own layout).
+    tileCover,
+    // This side's display name (hello.name), sanitised; null = none.
+    name: sanitizeName(opts.name),
+    // Devices no camera probe opens (openCamera's `exclude`); false = not even the built-in list.
+    cameraExclude: opts.cameraExclude === false ? false : Array.isArray(opts.cameraExclude) ? [...opts.cameraExclude] : undefined,
     // true: full chrome | 'tiles': badges + plates only | false: nothing. `chrome` = the full set.
     ui,
     chrome,
@@ -124,6 +139,8 @@ export function normalizeCallOptions(opts = {}) {
     log: typeof opts.log === 'function' ? opts.log : opts.debug ? (tag, obj) => console.log(`${TAG} ${tag} ${JSON.stringify(obj)}`) : null,
     // Internal (tests): replaces the lift module importer behind `mono3D: 'auto'`.
     _liftImporter: typeof opts._liftImporter === 'function' ? opts._liftImporter : undefined,
+    // Internal (tests): replaces the sender's frame grab (camera/conv-meter.js grabLumaFrame).
+    _convGrab: typeof opts._convGrab === 'function' ? opts._convGrab : undefined,
   };
 }
 

package/js/call/transport.js

@@ -6,7 +6,7 @@
 //
 //   transport.start({ room, localStream, onPeer, onPeerLeft, onStream, onMessage, onPeerState })
 //   transport.send(peerId, msg) / broadcast(msg)
-//   transport.replaceVideoTrack(track) / setSendFormat(format)
+//   transport.replaceTrack(kind, track, stream) / setSendFormat(format)
 //   transport.peerConnection(peerId)   // for getStats (null on an SFU)
 //   transport.stop()
 //
@@ -501,6 +501,16 @@ export class MeshTransport {
     for (const pid of this.peers.keys()) this.send(pid, msg);
   }
 
+  /** An already-serialised message (the app channel: sized before it is sent). */
+  sendRaw(pid, json) {
+    const rec = this.peers.get(pid);
+    if (rec && rec.dc && rec.dc.readyState === 'open') {
+      rec.dc.send(json);
+      return true;
+    }
+    return false;
+  }
+
   peerConnection(pid) {
     const rec = this.peers.get(pid);
     return rec ? rec.pc : null;

package/js/call/ui.js

@@ -8,7 +8,12 @@
 //     pill, never a plate congruent with the tile (it would match the canvas's own quad on a
 //     legacy browser and take the tile out of the weave). The bottom bar and self view live in a
 //     footer BELOW the grid, over no tile at all.
-//  2. NO `backdrop-filter`. The near-solid `--dxr-shell` (rgba(16,17,22,.92)) is the substitute.
+//  2. NO `backdrop-filter` in the SDK's own chrome. The near-solid `--dxr-shell`
+//     (rgba(16,17,22,.92)) is its choice, and it stays. A frosted element OVER a tile is no longer
+//     a defect on DisplayXR Browser 0.1.16+ (browser#120: the compositor draws the tile mono
+//     inside each frost rect; samples/composition is the validated case) — a page's own chrome may
+//     use it. Never frost a WHOLE visible tile, and rule 3 (effects on the canvas or an ancestor)
+//     is unchanged.
 //  3. Promotion is `will-change: transform`. No CSS filter / opacity / border-radius / shadow on a
 //     woven canvas OR ANY ANCESTOR of one — the tile, the grid and the host stay visually bare.
 //     A speaking highlight is a separate bar UNDER the stage, not an outline around it.
@@ -147,6 +152,8 @@ const CSS = `
    aside (display:contents) so each [data-dxr-peer] tile is laid out by the PAGE's own CSS on the
    host. A tile is never moved; it is styled in place (woven-canvas rule 2). */
 .dxr-call-grid[data-layout="none"]{display:contents;}
+/* …and so do the footer and the self slot, so the page places the self tile ([data-dxr-peer="self"]). */
+.dxr-call-host--none .dxr-call-foot,.dxr-call-host--none .dxr-call-self{display:contents;}
 .dxr-call-tile{position:relative;min-width:0;}
 .dxr-call-stage{position:relative;background:#000;}
 .dxr-call-stage>canvas{display:block;width:100%;height:100%;}