@displayxr/inline3d 1.47.5 → 1.48.0

package/js/inline3d-camera.js

@@ -431,7 +431,13 @@ class StereoCamera {
  * promise rejects only when NO camera opens, with `code` `'camera-busy'` (every device is held),
  * `'permission-denied'`, or `'no-camera'`, and `skipped` listing every device tried.
  *
- * @param {object|string|MediaStream} [opts]  `{ prefer, format, calibration, rectify, debug }` (or just `prefer`)
+ * A probe never opens a device whose label marks it as a sensor rather than a camera (a hand-tracking
+ * camera, an eye tracker's or depth camera's stream — capture.js CAMERA_EXCLUDE_BUILTIN), nor one
+ * matching `exclude` (strings: a label substring, case-insensitive, or an exact deviceId; RegExps:
+ * the label). `exclude: false` turns the built-in list off too. Left-out devices are in `skipped`
+ * with `excluded: true`. An explicit `deviceId` is the page's choice and is opened regardless.
+ *
+ * @param {object|string|MediaStream} [opts]  `{ prefer, format, calibration, rectify, exclude, debug }` (or just `prefer`)
  */
 export async function openCamera(opts = {}) {
   const o = typeof opts === 'string' || (opts && typeof opts.getVideoTracks === 'function') ? { prefer: opts } : opts || {};
@@ -441,7 +447,7 @@ export async function openCamera(opts = {}) {
   // `horizontalFovDeg` is the public spelling (RFC 0003 §4); the hello wire field is `hfovDeg`.
   if (cal.horizontalFovDeg > 0 && !(cal.hfovDeg > 0)) cal.hfovDeg = cal.horizontalFovDeg;
   delete cal.horizontalFovDeg;
-  const r = await openDevice(prefer, { format: o.format, calibration: cal, mediaDevices: o.mediaDevices, log: log || undefined });
+  const r = await openDevice(prefer, { format: o.format, calibration: cal, mediaDevices: o.mediaDevices, log: log || undefined, exclude: o.exclude });
   if (r.format === 'sbs' && typeof o.rectify === 'function') {
     // A calibrated rectification step (plug-in or runtime supplied): its output is a rectified
     // SBS stream, and the record then says so. A throwing hook keeps the raw pair.
@@ -498,7 +504,12 @@ function sizeFlat(canvas) {
  * pair — with `fallbackReason` saying why, and `onRouteChange(route, state)` tells the page (a
  * badge reads `route`). A refused layer is retried a few times; `_reroute(true, wall)` recovers.
  *
- * @param {{ mirror?: boolean, autoConverge?: boolean, depth?: number, aspect?: number, onRouteChange?: Function }} [opts]
+ * `aspect: 'fill'` crops each eye to the canvas's own CSS box (read every frame) instead of a fixed
+ * aspect, for a page that sizes the tile itself. `rectCover: 'auto'` is the core's rect cover
+ * (`addImage`'s `rectCover`) on the woven registration: the tile is covered across a later resize
+ * or move until it is woven again.
+ *
+ * @param {{ mirror?: boolean, autoConverge?: boolean, depth?: number, aspect?: number|'fill', rectCover?: 'auto'|'off'|object, onRouteChange?: Function }} [opts]
  */
 export function addCameraView(wall, canvas, cam, opts = {}) {
   if (!canvas || typeof canvas.getContext !== 'function') throw new TypeError(`${TAG} addCameraView(wall, canvas, cam, opts) needs a canvas`);
@@ -516,7 +527,10 @@ class CameraView {
     // A self view mirrors; a rear camera shows the world as it is. Unset: mirror unless the track
     // says it faces the environment (an unknown facing is a webcam pointed at the viewer).
     this.mirror = o.mirror === undefined ? cam.facing !== 'environment' : !!o.mirror;
-    this.aspect = typeof o.aspect === 'number' && o.aspect > 0.3 && o.aspect < 4 ? o.aspect : 16 / 9;
+    // 'fill': the canvas box's own aspect, read at paint (clamped like a number) — `_eyeAspect()`.
+    this.aspect = o.aspect === 'fill' ? 'fill' : typeof o.aspect === 'number' && o.aspect > 0.3 && o.aspect < 4 ? o.aspect : 16 / 9;
+    // The core's rect cover on the woven registration (undefined = the core's default, off).
+    this.rectCover = o.rectCover;
     this.autoConverge = !!o.autoConverge;
     this.conv = createConvergence();
     this.conv.depth = 0;
@@ -638,7 +652,7 @@ class CameraView {
   _registerWoven() {
     if (!this.buffer) this.buffer = document.createElement('canvas');
     this._paintWoven(); // the first frame exists before the layer does
-    const handle = this.wall.addImage(this.canvas, this.buffer);
+    const handle = this.rectCover === undefined ? this.wall.addImage(this.canvas, this.buffer) : this.wall.addImage(this.canvas, this.buffer, { rectCover: this.rectCover });
     this.handle = handle;
     this._fw = null;
     const fw = handle && handle.firstWoven;
@@ -749,7 +763,7 @@ class CameraView {
     const H = v.videoHeight;
     if (!W || !H || (v.readyState || 0) < 2 || !this.buffer) return;
     const eyeW = W / 2;
-    const A = this.aspect;
+    const A = this._eyeAspect();
     const { w: outW, h: outH } = eyeOutputSize(eyeW, H, A);
     const c = this.buffer;
     if (c.width !== 2 * outW || c.height !== outH) {
@@ -783,6 +797,15 @@ class CameraView {
     }
   }
 
+  /** The per-eye aspect the pair is cropped to: the number given, or (`'fill'`) the canvas box's. */
+  _eyeAspect() {
+    if (this.aspect !== 'fill') return this.aspect;
+    const w = this.canvas.clientWidth || 0;
+    const h = this.canvas.clientHeight || 0;
+    if (w > 0 && h > 0) this._fillAspect = Math.max(0.3, Math.min(4, w / h));
+    return this._fillAspect || 16 / 9;
+  }
+
   /**
    * A small grayscale copy of the SOURCE frame (before our shift): ~5 Hz for auto-convergence,
    * ~15 Hz while a depth cursor hovers (it measures the same copy under the pointer).

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

package/js/inline3d-pc-release.js

@@ -0,0 +1,107 @@
+// inline3d-pc-release.js — handle.releaseEntity: take content a page added under
+// `handle.engine.root` out of a PlayCanvas tile and give back what it held on the GPU.
+//
+// Internal. PlayCanvasSplatViewer.releaseEntity (./inline3d-splat-playcanvas.js) calls it, for
+// both ./splat (engine: 'playcanvas') and ./model. docs/content-lifecycle-rules.md has the why.
+//
+// WHY. `entity.destroy()` and `asset.unload()` free meshes, textures and materials, but NOT the
+// shader programs those materials linked: the engine's ProgramLibrary caches every variant for
+// the device's life, and `Material.destroy()` only empties `material.variants`. A page that swaps
+// glTF content in and out (a product carousel, a catalogue) therefore keeps every program it ever
+// linked, and a desktop driver keeps the linked program's compiled IR behind each one (about 5 MB
+// per program, measured on one Linux driver). `Shader.destroy()` is the engine's own explicit
+// release: it deletes the program and drops it from the ProgramLibrary cache, so a later ask for
+// the same variant compiles it again instead of getting a dead one.
+//
+// ORDER (each step needs the one before):
+//   1. collect the programs the entity's materials hold (`variants`, and each mesh instance's own
+//      shader cache) BEFORE anything is destroyed: destroying a material empties `variants`;
+//   2. destroy the entity;
+//   3. the container (`asset`, optional): unloaded and taken out of the registry when nothing
+//      left under `app.root` draws with one of its meshes or materials, after its own materials'
+//      programs are collected too;
+//   4. destroy each collected program that nothing still in the app uses: any mesh instance under
+//      `app.root` (enabled or not), any layer's mesh instances, any material asset still in the
+//      registry. ProgramLibrary returns one Shader for one key, so two materials with the same
+//      options share a program; that is why this check exists.
+
+/** Every program `materials` hold in `variants`, added to `into`. */
+export function materialShaders(materials, into = new Set()) {
+  for (const m of materials) m?.variants?.forEach?.((s) => s && into.add(s));
+  return into;
+}
+
+/** The mesh instances of every render / model component under `entity` (itself included). */
+function meshInstancesUnder(entity) {
+  const out = [];
+  if (!entity?.findComponents) return out;
+  for (const kind of ['render', 'model']) {
+    let comps = [];
+    try {
+      comps = entity.findComponents(kind) || [];
+    } catch {
+      comps = []; // a component system the app does not have
+    }
+    for (const c of comps) for (const mi of c.meshInstances || []) if (mi) out.push(mi);
+  }
+  return out;
+}
+
+/** A mesh instance's programs: its material's variants and its own shader cache. */
+function noteMeshInstance(mi, into) {
+  mi.material?.variants?.forEach?.((s) => s && into.add(s));
+  mi._shaderCache?.forEach?.((si) => si?.shader && into.add(si.shader));
+}
+
+/** Every program something still in `app` may draw with (step 4's keep set). */
+export function liveShaders(app) {
+  const live = new Set();
+  for (const mi of meshInstancesUnder(app.root)) noteMeshInstance(mi, live);
+  for (const layer of app.scene?.layers?.layerList || []) for (const mi of layer.meshInstances || []) noteMeshInstance(mi, live);
+  for (const a of app.assets?.list?.() || []) if (a?.type === 'material' && a.resource) materialShaders([a.resource], live);
+  return live;
+}
+
+/** Does anything left under `app.root` draw with one of `container`'s meshes or materials? */
+function containerInUse(app, container) {
+  const mats = new Set((container?.materials || []).map((a) => a?.resource).filter(Boolean));
+  const meshes = new Set();
+  for (const r of container?.renders || []) for (const m of r?.resource?.meshes || []) meshes.add(m);
+  if (!mats.size && !meshes.size) return false;
+  for (const mi of meshInstancesUnder(app.root)) if (mats.has(mi.material) || meshes.has(mi.mesh)) return true;
+  return false;
+}
+
+/**
+ * Destroy `entity` and release what it held. With `asset` (the container it was instantiated
+ * from), the container too, unless something else in the app still draws from it.
+ * Returns { programs, container } — programs destroyed, and 'unloaded' | 'in-use' | null.
+ */
+export function releaseEntity(app, entity, { asset = null } = {}) {
+  const result = { programs: 0, container: null };
+  if (!app || !app.root) return result;
+  const retired = new Set();
+  if (entity) {
+    for (const mi of meshInstancesUnder(entity)) noteMeshInstance(mi, retired);
+    entity.destroy?.();
+  }
+  if (asset) {
+    const container = asset.resource;
+    if (container && containerInUse(app, container)) {
+      result.container = 'in-use';
+    } else {
+      materialShaders((container?.materials || []).map((a) => a?.resource), retired);
+      app.assets?.remove?.(asset);
+      asset.unload?.();
+      result.container = 'unloaded';
+    }
+  }
+  if (!retired.size) return result;
+  const live = liveShaders(app);
+  for (const s of retired) {
+    if (live.has(s) || typeof s.destroy !== 'function') continue;
+    s.destroy();
+    result.programs++;
+  }
+  return result;
+}

package/js/inline3d-pc-shader-cache.js

@@ -0,0 +1,172 @@
+// inline3d-pc-shader-cache.js — give PlayCanvas's compiled WebGL shaders back when the last
+// program that uses them is destroyed.
+//
+// Internal. The PlayCanvas viewer (./inline3d-splat-playcanvas.js, shared by ./splat and ./model)
+// calls installShaderCacheRelease(device) on every device it creates.
+//
+// WHY. The engine (2.22.3, src/platform/graphics/webgl/webgl-shader.js) keeps every compiled
+// vertex and fragment shader in a module-private CompiledShaderCache, keyed by source, until the
+// DEVICE is destroyed: `WebglShader.destroy()` deletes the program and nothing else. A page that
+// releases what a content swap replaces (`Shader.destroy()` on the outgoing variants, see
+// docs/content-lifecycle-rules.md) therefore still keeps two compiled shaders per program it
+// ever linked, with the driver's compiled IR behind each one. Over a long-lived page that is
+// unbounded growth in the browser's GPU process.
+//
+// WHAT THIS DOES. The engine is the page's own peer dependency (an import map, a bundler, a CDN
+// build), never a file this package ships, so it cannot be patched on disk. Instead this replaces
+// two methods on the engine's WebglShader prototype, reached through the first shader the device
+// creates:
+//   _compileShaderSource — the same lookup the engine does, in a per-device cache of its own
+//                          (keyed by source, as the engine's), plus one count per program that
+//                          took the shader;
+//   destroy              — the engine's destroy (deletes the program), then one release per
+//                          shader. The last program out deletes the shader and drops the entry, so
+//                          the next ask for that source compiles it again.
+// Context loss clears the cache (the GL objects are gone; the engine recompiles on restore), and
+// device destroy deletes whatever is still cached, as the engine's own cache does. Shaders the
+// engine compiled BEFORE the patch stay in the engine's cache and are left alone.
+//
+// ACROSS ENGINE BUMPS. The patch installs only when the prototype has the 2.22.x shape (an
+// `_compileShaderSource(device, src, isVertexShader)` that reads a `.map` keyed by source, and a
+// `destroy` that does not already delete shaders), and otherwise steps aside and says why
+// (`device.__dxrShaderCache`, and the diagnostics overlay). On an engine bump: read the new
+// webgl-shader.js; if CompiledShaderCache still never deletes a shader before device destroy, keep
+// this and update the shape check if the method moved; if upstream releases shaders itself, the
+// `deleteShader` check makes this a no-op — delete the module. test/pc-shader-cache.test.mjs
+// runs this against a copy of the 2.22.3 class shape.
+
+const PATCHED = Symbol.for('@displayxr/inline3d.shaderCacheRelease');
+
+/** The per-device cache: source → shader, per stage, and a count per shader. */
+const caches = new WeakMap();
+
+function cacheFor(device) {
+  let c = caches.get(device);
+  if (!c) {
+    c = { v: new Map(), f: new Map(), refs: new Map(), compiled: 0, deleted: 0 };
+    caches.set(device, c);
+    device.on?.('devicelost', () => {
+      c.v.clear();
+      c.f.clear();
+      c.refs.clear();
+    });
+    device.on?.('destroy', () => {
+      const gl = device.gl;
+      if (gl && !gl.isContextLost?.()) for (const s of c.refs.keys()) gl.deleteShader(s);
+      c.v.clear();
+      c.f.clear();
+      c.refs.clear();
+    });
+  }
+  return c;
+}
+
+function release(device, map, src, glShader) {
+  const c = caches.get(device);
+  if (!c || !glShader || !c.refs.has(glShader)) return false; // not ours (compiled before the patch)
+  const n = c.refs.get(glShader) - 1;
+  if (n > 0) {
+    c.refs.set(glShader, n);
+    return true;
+  }
+  c.refs.delete(glShader);
+  if (map.get(src) === glShader) map.delete(src);
+  device.gl?.deleteShader(glShader);
+  c.deleted++;
+  return true;
+}
+
+/**
+ * Why `proto` cannot take the patch, or null when it can. Exported for the test.
+ * @param {object} proto  the engine's WebglShader.prototype
+ */
+export function shaderCacheShapeProblem(proto) {
+  if (!proto || typeof proto._compileShaderSource !== 'function' || typeof proto.destroy !== 'function') return 'no WebglShader._compileShaderSource/destroy';
+  if (proto._compileShaderSource.length !== 3) return 'WebglShader._compileShaderSource has a different signature';
+  const compile = Function.prototype.toString.call(proto._compileShaderSource);
+  if (!/\.map\.get\(/.test(compile) || !/createShader\(/.test(compile)) return 'WebglShader._compileShaderSource has a different body';
+  const destroy = Function.prototype.toString.call(proto.destroy);
+  if (/deleteShader/.test(destroy)) return 'the engine already releases shaders (WebglShader.destroy deletes them)';
+  return null;
+}
+
+/** Patch the engine's WebglShader prototype once (the prototype is shared by every device). */
+export function patchWebglShaderPrototype(proto) {
+  if (proto[PATCHED]) return 'already';
+  const problem = shaderCacheShapeProblem(proto);
+  if (problem) return `skipped: ${problem}`;
+  const engineDestroy = proto.destroy;
+  proto._compileShaderSource = function (device, src, isVertexShader) {
+    const gl = device.gl;
+    if (gl.isContextLost()) return null;
+    const c = cacheFor(device);
+    const map = isVertexShader ? c.v : c.f;
+    let glShader = map.get(src);
+    if (!glShader) {
+      glShader = gl.createShader(isVertexShader ? gl.VERTEX_SHADER : gl.FRAGMENT_SHADER);
+      gl.shaderSource(glShader, src);
+      gl.compileShader(glShader);
+      map.set(src, glShader);
+      c.compiled++;
+    }
+    c.refs.set(glShader, (c.refs.get(glShader) || 0) + 1);
+    return glShader;
+  };
+  proto.destroy = function (shader) {
+    engineDestroy.call(this, shader);
+    const device = shader?.device;
+    const c = device && caches.get(device);
+    if (!c) return;
+    if (release(device, c.v, this._vsource, this.glVertexShader)) this.glVertexShader = null;
+    if (release(device, c.f, this._fsource, this.glFragmentShader)) this.glFragmentShader = null;
+  };
+  Object.defineProperty(proto, PATCHED, { value: true });
+  return 'patched';
+}
+
+/**
+ * Install the release on `device`'s shader class. Idempotent; WebGL devices only. The result is
+ * also kept on `device.__dxrShaderCache` ('patched' | 'already' | 'skipped: …' | 'pending').
+ * The prototype is reached through the first shader impl the device creates (the class is not
+ * exported), so this wraps `createShaderImpl` until it has one.
+ */
+export function installShaderCacheRelease(device) {
+  if (!device || device.__dxrShaderCache) return device?.__dxrShaderCache ?? null;
+  if (!device.isWebGL2 || typeof device.createShaderImpl !== 'function') {
+    device.__dxrShaderCache = 'skipped: not a WebGL2 device';
+    return device.__dxrShaderCache;
+  }
+  const existing = device.shaders?.find?.((s) => s?.impl);
+  if (existing) {
+    device.__dxrShaderCache = patchWebglShaderPrototype(Object.getPrototypeOf(existing.impl));
+    return device.__dxrShaderCache;
+  }
+  device.__dxrShaderCache = 'pending';
+  const create = device.createShaderImpl;
+  const ownBefore = Object.hasOwn(device, 'createShaderImpl');
+  device.createShaderImpl = function (shader) {
+    // The prototype is only reachable from an impl, and the impl's constructor compiles: this
+    // first pair lands in the engine's own cache (kept for the device's life, as before); every
+    // later shader goes through the counted one.
+    if (device.__dxrShaderCache === 'pending') {
+      device.__dxrShaderCache = 'probing';
+      let impl;
+      try {
+        impl = create.call(this, shader);
+      } finally {
+        if (ownBefore) device.createShaderImpl = create;
+        else delete device.createShaderImpl; // the prototype's method again
+      }
+      device.__dxrShaderCache = patchWebglShaderPrototype(Object.getPrototypeOf(impl));
+      return impl;
+    }
+    return create.call(this, shader);
+  };
+  return device.__dxrShaderCache;
+}
+
+/** Shaders compiled / deleted through the patched cache on `device` (diagnostics), or null. */
+export function shaderCacheStats(device) {
+  const c = device && caches.get(device);
+  return c ? { compiled: c.compiled, deleted: c.deleted, cached: c.refs.size } : null;
+}

package/js/inline3d-playcanvas-engine.js

@@ -42,7 +42,8 @@ export {
   LAYERID_IMMEDIATE,
   // cursor: 'depth' (./inline3d-cursor-depth-playcanvas.js, loaded only on opt-in)
   Picker,
-  // materials / meshes (the edge feather)
+  // materials / meshes (the edge feather; Material: the program release, ./inline3d-pc-auto-release.js)
+  Material,
   Mesh,
   MeshInstance,
   ShaderMaterial,