@displayxr/inline3d 1.47.4 → 1.47.6

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/js/camera/capture.js

@@ -10,10 +10,11 @@
 //    fails with NotReadableError ("Device in use"). That device is skipped silently — a call must
 //    never fail because an optional camera is busy.
 //  - Labels are empty until one getUserMedia has succeeded. Without them, permission is primed on
-//    an environment-facing camera where there is one (a phone's front lens is the head tracker's,
-//    and opening it while the tracker holds it can reset the whole camera stack), then the list
-//    is read again and a stereo device is opened by id BEFORE the default. The default is the
-//    fallback.
+//    the DEFAULT camera with no constraints: in the DisplayXR Browser the runtime's 3D camera is
+//    listed first, so the prime opens the pair itself and no phone lens is opened at all (a plain
+//    open of one lens of the pair, or its teardown, crashes some phones' camera HAL; any facing or
+//    size constraint lets the engine pick a lens instead). Then the list is read again and a
+//    stereo device is opened by id BEFORE falling back. The primed default is the fallback.
 //
 // RECTIFICATION is not done here (P2): it needs the camera's calibration (intrinsics/extrinsics
 // for the ACTIVE device), which comes from a plug-in or the runtime. P1 sends the raw pair with
@@ -104,6 +105,17 @@ export async function openCamera(want = 'auto', o = {}) {
     log('camera-skip', { label, error: err.name });
   };
   const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
+  // Ask an open camera for another mode without a second start; keep it as it is if it refuses.
+  const withMode = async (r, constraints) => {
+    try {
+      await r.track.applyConstraints(constraints);
+      const st = r.track.getSettings();
+      if (st.width > 0 && st.height > 0) return { ...r, width: st.width, height: st.height };
+    } catch {
+      /* keep the mode it opened in */
+    }
+    return r;
+  };
   // A track that declares itself a side-by-side pair IS one, whatever its aspect (a phone's portrait
   // eyes make a 1440x1280 pair). Shape is only the guess for an unknown device, e.g. a USB pair.
   const isPair = (r) => !!r && (!!r.stereo || looksSbs(r.width, r.height));
@@ -170,15 +182,23 @@ export async function openCamera(want = 'auto', o = {}) {
   };
   let mono = null;
   if (want !== 'mono') {
-    const listed = await listCameras();
-    const pair = await tryNamedPairs(listed);
+    let listed = await listCameras();
+    let pair = await tryNamedPairs(listed);
     if (pair) return result(pair, 'sbs');
-    // No labels yet (no permission). Prime it on an environment-facing camera, so a phone does not
-    // open its front lens (the head tracker's) just to learn the names; then open a pair by id.
+    // Labels visible but no stereo-named device: a runtime 3D camera can join the list late (after
+    // a runtime restart), so read it once more before falling back.
+    if (listed.some((d) => d.label) && !listed.some((d) => stereoLabelHint(d.label))) {
+      listed = await listCameras();
+      pair = await tryNamedPairs(listed);
+      if (pair) return result(pair, 'sbs');
+    }
+    // No labels yet (no permission). Prime it on the default camera with NO constraints: in the
+    // DisplayXR Browser that is the 3D camera (listed first), so no phone lens is opened; a facing
+    // or size constraint would let the engine pick a lens instead. Then open a pair by id.
     if (listed.length && listed.every((d) => !d.label)) {
       let primed = null;
       try {
-        primed = await open({ ...MONO_CONSTRAINTS, facingMode: { ideal: 'environment' } });
+        primed = await open(true);
       } catch (err) {
         skip('default', err);
       }
@@ -188,10 +208,8 @@ export async function openCamera(want = 'auto', o = {}) {
         stop(primed);
         return result(named, 'sbs');
       }
-      // A camera that faces the user (or does not say: a desktop webcam) is the fallback as is; a
-      // rear one is not what a self view falls back to, so the default is opened below instead.
-      if (primed && primed.track?.getSettings?.().facingMode !== 'environment') mono = primed;
-      else stop(primed);
+      // The primed default is the fallback as is (one camera start); ask it for the usual mode.
+      if (primed) mono = await withMode(primed, MONO_CONSTRAINTS);
     }
   }
 

package/js/inline3d-model-entry.js

@@ -153,6 +153,9 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     depthFactor: 1,
     // Before the backend lands: once it has, the backend's own (PlayCanvas); three has none (0).
     warmEntity: (entity, o) => out.ready.then(() => (out.warmEntity !== stubWarm && typeof out.warmEntity === 'function' ? out.warmEntity(entity, o) : 0)),
+    // PlayCanvas replaces this once it has loaded; before that (and on three) there is nothing of
+    // the engine's to release.
+    releaseEntity: () => ({ programs: 0, container: null }),
   };
   const stubWarm = out.warmEntity;
   out.firstWoven = new Promise((resolve) => {

package/js/inline3d-model-playcanvas.js

@@ -40,6 +40,7 @@
 import { PlayCanvasSplatViewer, pageRigTRS, pageViewAxis, pageViewRig } from './inline3d-splat-playcanvas.js';
 import { resolveControls, normalizeCameraPose, now, MAX_DT_S, declareViewRig, attachModelStereo, attachComfortDepth, resolveDepthOption, framedSubjectBounds } from './inline3d-splat-shared.js';
 import { displayRig } from './inline3d-three.js';
+import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, watchContent } from './inline3d-splat-diag.js';
 import {
   NEUTRAL_STUDIO,
   neutralStudioRadiance,
@@ -479,6 +480,11 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
   let handle = null;
   let removed = false;
   let lastPagePose = null;
+  // `?dxrdiag` (or `diag`): the splat handle's recorder, for what a model tile can show — frame
+  // cadence, and the live GL objects + content-swap leak watch (./inline3d-splat-diag.js).
+  const diagCfg = resolveDiag(opts.diag);
+  const diag = diagCfg.on ? new DiagRecorder({ switches: diagCfg.switches, label: 'model' }) : null;
+  let diagLoop = null;
 
   Object.assign(out, {
     backend: 'playcanvas',
@@ -514,6 +520,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     },
     remove() {
       removed = true;
+      diagLoop?.remove();
+      diag?.dispose();
       depth.dispose();
       handle?.remove();
       viewer.dispose(); // app.destroy(): the model, its textures and any page entities go with it
@@ -528,6 +536,14 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
       await out.ready?.catch?.(() => null);
       return removed ? 0 : viewer.warmEntity(entity ?? out.model, o);
     },
+    /**
+     * Destroy `entity` (content a page added under handle.engine.root) and release the programs
+     * its materials linked, and its container `asset` when nothing else draws from it —
+     * PlayCanvasSplatViewer.releaseEntity. Returns { programs, container }.
+     */
+    releaseEntity(entity, o) {
+      return removed ? { programs: 0, container: null } : viewer.releaseEntity(entity, o);
+    },
   });
 
   // The per-eye buffer scale in force (the request times the device-limit clamp,
@@ -550,8 +566,15 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
   });
   if (pageMode) depth.ignore("controls:'page' (the page's camera rig)");
 
+  const onFrame = diag
+    ? (views, layer, frame) => {
+        const t = performance.now();
+        viewer.onFrame(views, layer, frame);
+        diag.frame(views, t);
+      }
+    : viewer.onFrame;
   if (wall && wall.supported) {
-    handle = wall.addScene(canvas, viewer.onFrame, {
+    handle = wall.addScene(canvas, onFrame, {
       ...(pageMode
         ? { viewRig: pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth }) }
         : { virtualDisplayHeight }),
@@ -575,6 +598,12 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     delete out._resolveFirstWoven;
   }
 
+  if (diag) {
+    diagLoop = startDiagLoop(diag, { overlay: !diag.has('nooverlay') && !!handle });
+    if (diagLoop?.el) handle?.exclude?.(diagLoop.el);
+    registerDiag(diag);
+  }
+
   for (const [name, args] of pending) {
     if (name === 'remove') {
       out.remove();
@@ -637,8 +666,13 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     }
     const wanted = PC_DECODER_KINDS.filter((k) => (k === 'meshopt' && meshoptDecoder) || (declared ? declared.has(PC_DECODERS[k].ext) : false));
 
-    const app = await viewer.attachEngine(pc, { preserveDrawingBuffer, antialias, patchSplats: false });
+    // `?dxrdiag=keepshaders`: the engine's shader cache as it ships (A/B; see ./inline3d-pc-shader-cache.js).
+    const shaderCacheRelease = !diag?.has('keepshaders');
+    // `?dxrdiag=keepprograms`: destroyed materials keep their programs (A/B; ./inline3d-pc-auto-release.js).
+    const programRelease = !diag?.has('keepprograms');
+    const app = await viewer.attachEngine(pc, { preserveDrawingBuffer, antialias, patchSplats: false, shaderCacheRelease, programRelease });
     if (!app || removed) return out;
+    if (diag) watchContent(diag, app, viewer);
     out.engine = Object.freeze({ app, root: viewer.content, camera: viewer.eye || null });
 
     // Lighting before the model, so the first frame the model is in is lit.

package/js/inline3d-pc-auto-release.js

@@ -0,0 +1,191 @@
+// inline3d-pc-auto-release.js — when a page destroys a material on one of the SDK's PlayCanvas
+// devices, release the programs it linked, without the page asking.
+//
+// Internal. PlayCanvasSplatViewer.attachEngine (./inline3d-splat-playcanvas.js) installs it on
+// every app it creates, for ./splat (engine: 'playcanvas') and ./model. docs/content-lifecycle-rules.md
+// § rule 1 has the why; `?dxrdiag=keepprograms` turns it off (A/B).
+//
+// WHY. `Material.destroy()` empties `material.variants` and destroys no program, and the engine's
+// ProgramLibrary keeps every program it linked for the device's life. A page that swaps content
+// under one live app (`entity.destroy()`, `asset.unload()`, which destroys the container's
+// materials) therefore keeps every program it ever linked: measured 0 → 170 live programs over 28
+// screen changes on a kiosk app, none deleted. `handle.releaseEntity` releases them on request;
+// this does the same for every material the page destroys, so a page that follows the engine's
+// own teardown is bounded too.
+//
+// HOW. Two methods on the engine's Material prototype, wrapped once (the prototype is shared by
+// every app on the page, so both wrappers act only on devices registered here):
+//   - getShaderVariant: the one place a material links a program. Records the material (weakly)
+//     on its device, so a live material that holds a program keeps it (step 3);
+//   - destroy: BEFORE the engine empties `variants`, collects the programs the material and its
+//     mesh instances hold, and marks the material destroyed.
+// The sweep runs once per frame that had a destroy, at the app's `frameend` (after render, so
+// content added in the same frame has drawn and holds its programs), with a timer as backup for a
+// stopped app. It destroys each collected program that nothing still uses:
+//   1. no mesh instance under `app.root` or in a layer, and no material asset in the registry
+//      (the keep set of ./inline3d-pc-release.js);
+//   2. still registered on the device (not already destroyed, e.g. by releaseEntity);
+//   3. no material that linked it is still alive. ProgramLibrary hands one Shader to every material
+//      with the same key, and a material a page keeps off-scene to show again still has it in its
+//      `variants`; destroying it under that material would leave a dead program there.
+// `Shader.destroy()` also takes the program out of the library, so a later ask for that variant
+// compiles it again. Cost: content shown again after release recompiles on its first draw
+// (`handle.warmEntity` hides that).
+
+import { liveShaders } from './inline3d-pc-release.js';
+
+const states = new WeakMap(); // device -> { app, materials:Set<WeakRef>, pending:Set, scheduled, stats }
+let patchedProto = null;
+
+const deref = (r) => (typeof r?.deref === 'function' ? r.deref() : r);
+const weak = (x) => (typeof WeakRef === 'function' ? new WeakRef(x) : x);
+
+function collect(material) {
+  const into = (s) => {
+    const st = s && states.get(s.device);
+    if (!st) return;
+    st.pending.add(s);
+    schedule(st);
+  };
+  material.variants?.forEach?.(into);
+  material.meshInstances?.forEach?.((mi) => mi?._shaderCache?.forEach?.((si) => into(si?.shader)));
+}
+
+/** Programs some still-alive material on `st`'s device has linked. Prunes dead entries. */
+function heldByLiveMaterials(st) {
+  const held = new Set();
+  for (const r of st.materials) {
+    const m = deref(r);
+    if (!m || m.__dxrDestroyed) {
+      st.materials.delete(r);
+      continue;
+    }
+    m.variants?.forEach?.((s) => s && held.add(s));
+  }
+  return held;
+}
+
+function schedule(st) {
+  if (st.scheduled) return;
+  st.scheduled = true;
+  const run = (st.run ||= () => sweep(st));
+  try {
+    st.app.once?.('frameend', run);
+  } catch {
+    /* no event system: the timer below */
+  }
+  st.timer = setTimeout(run, 1000);
+}
+
+/** Destroy every collected program nothing still uses. Returns how many. Exported for tests. */
+export function sweep(st) {
+  if (!st || !st.scheduled) return 0;
+  st.scheduled = false;
+  clearTimeout(st.timer);
+  if (st.run) st.app.off?.('frameend', st.run); // only ours: the page may listen to frameend too
+  if (!st.pending.size || st.off) {
+    st.pending.clear();
+    return 0;
+  }
+  let keep;
+  try {
+    keep = liveShaders(st.app);
+  } catch {
+    st.pending.clear(); // an app mid-teardown: it frees everything itself
+    return 0;
+  }
+  const held = heldByLiveMaterials(st);
+  let n = 0;
+  for (const s of st.pending) {
+    if (keep.has(s) || held.has(s) || typeof s.destroy !== 'function') continue;
+    const registered = s.device?.shaders;
+    if (Array.isArray(registered) && !registered.includes(s)) continue; // already destroyed
+    try {
+      s.destroy();
+      n++;
+    } catch {
+      /* a program the engine already tore down */
+    }
+  }
+  st.pending.clear();
+  st.stats.released += n;
+  st.stats.sweeps++;
+  st.onSweep?.(n);
+  return n;
+}
+
+/**
+ * The prototype has the shape this relies on (2.22.x): `getShaderVariant(params)` with
+ * `params.device`, and a `destroy()` that clears `variants`. Returns a reason string, or null.
+ */
+export function materialShapeProblem(proto) {
+  if (!proto || typeof proto.getShaderVariant !== 'function' || typeof proto.destroy !== 'function') return 'no Material.getShaderVariant/destroy';
+  const d = Function.prototype.toString.call(proto.destroy);
+  if (!/variants/.test(d)) return 'Material.destroy no longer clears variants';
+  return null;
+}
+
+/** Wrap the engine's Material prototype once. Returns 'patched' | 'already' | 'skipped: …'. */
+export function patchMaterialPrototype(proto) {
+  if (patchedProto === proto || proto?.__dxrAutoRelease) return 'already';
+  const problem = materialShapeProblem(proto);
+  if (problem) return `skipped: ${problem}`;
+  const getShaderVariant = proto.getShaderVariant;
+  const destroy = proto.destroy;
+  proto.getShaderVariant = function (params) {
+    const s = getShaderVariant.apply(this, arguments);
+    const st = states.get(params?.device ?? s?.device);
+    if (st && !this.__dxrTracked) {
+      this.__dxrTracked = true;
+      st.materials.add(weak(this));
+    }
+    return s;
+  };
+  proto.destroy = function () {
+    try {
+      collect(this);
+    } catch {
+      /* never let the release break the engine's own teardown */
+    }
+    this.__dxrDestroyed = true;
+    return destroy.apply(this, arguments);
+  };
+  proto.__dxrAutoRelease = true;
+  patchedProto = proto;
+  return 'patched';
+}
+
+/**
+ * Release the programs of destroyed materials on `app`'s device. `Material` is the engine's
+ * Material class (the one the page's own `import … from 'playcanvas'` also resolves to).
+ * The result is kept on `device.__dxrAutoRelease`.
+ */
+export function installAutoProgramRelease(app, Material) {
+  const device = app?.graphicsDevice;
+  if (!device) return null;
+  if (states.has(device)) return device.__dxrAutoRelease;
+  const patched = patchMaterialPrototype(Material?.prototype);
+  const result = patched === 'already' ? 'patched' : patched; // one prototype for every app on the page
+  device.__dxrAutoRelease = result;
+  if (result.startsWith('skipped')) return result;
+  const st = { app, materials: new Set(), pending: new Set(), scheduled: false, timer: 0, off: false, stats: { released: 0, sweeps: 0 } };
+  states.set(device, st);
+  app.once?.('destroy', () => {
+    st.off = true;
+    clearTimeout(st.timer);
+    st.pending.clear();
+    st.materials.clear();
+  });
+  return result;
+}
+
+/** Programs released on `app`'s device so far (diagnostics), or null. */
+export function autoReleaseStats(app) {
+  const st = app?.graphicsDevice && states.get(app.graphicsDevice);
+  return st ? { ...st.stats, pending: st.pending.size, materials: st.materials.size } : null;
+}
+
+/** The state for `app` (tests, and diag's per-sweep hook). */
+export function autoReleaseState(app) {
+  return (app?.graphicsDevice && states.get(app.graphicsDevice)) || null;
+}