@displayxr/inline3d 1.47.4 → 1.47.6

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,

package/js/inline3d-splat-deferred.js

@@ -126,6 +126,8 @@ export function addSplatDeferred(wall, canvas, src, opts) {
     },
     // Mesh-program warm before the adapter has loaded: runs once it has (it needs the engine).
     warmEntity: (entity, o) => out.ready.then(() => out.warmEntity(entity, o)),
+    // Nothing a page added can exist before the engine has: nothing to release yet.
+    releaseEntity: () => ({ programs: 0, container: null }),
     setEffect: (name, params) => {
       validateEffectCall(name, params, 'set');
       pending.push(['setEffect', [name, params]]);

package/js/inline3d-splat-diag.js

@@ -34,6 +34,19 @@
 //              located them, and a live outgoing photo goes back on the pre-1.24 node chain (which
 //              scales its disparity by the two rigs' window ratio at the swap). A/B for "the
 //              outgoing photo jumps when the incoming rig is declared".
+//   keepshaders — leave the engine's compiled-shader cache as it ships (no per-program release,
+//              ./inline3d-pc-shader-cache.js). Page-wide: the engine's shader class is shared.
+//   keepprograms — a material the page destroys keeps the programs it linked, as the engine ships
+//              (./inline3d-pc-auto-release.js). Per tile.
+//
+// LIVE GL OBJECTS (docs/content-lifecycle-rules.md): programs and shaders created / deleted on the
+// tile's context since diag attached, and the live difference, on the overlay and in the dump.
+// Sampled at every content swap the SDK can see: each setSource, each glTF container the tile's
+// asset registry loads (a page swapping meshes under handle.engine.root), each
+// handle.releaseEntity. When the live program count has not dropped across the last LEAK_SWAPS
+// swaps of one kind and rose at more than 60% of them, one console warning says so. A page that
+// releases what a swap replaces goes up and down, or plateaus once its own transitions are
+// compiled (a few rises, then flat); one that leaks climbs.
 //
 // Per frame, `rigAt` / `rigIn` / `rigOut` say which declared rig the views were located for
 // (the tracker's id; null = none matched), which rig the current photo was drawn through
@@ -52,8 +65,28 @@
 //   - the settle itself: the SDK's settle work in ms, then how long the SAME task kept running
 //     after it (the page's continuation of `await setSource`).
 
+import { autoReleaseStats, autoReleaseState } from './inline3d-pc-auto-release.js';
+
 /** The switches `diag` / `?dxrdiag` understand, besides the plain on values. */
-export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig', 'oldrig']);
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig', 'oldrig', 'keepshaders', 'keepprograms']);
+/**
+ * The leak watch's window: content swaps of one kind with no drop in live programs, more than 60%
+ * of them a rise. Wide enough that a first pass through the transitions (each compiles its own
+ * programs once: four rises for cut / crossfade / wavefront / flip) does not trip it.
+ */
+export const LEAK_SWAPS = 10;
+
+/** The leak watch's rule on one kind's samples (oldest first): the warning's condition. */
+export function looksLikeLeak(samples, n = LEAK_SWAPS) {
+  if (samples.length < n + 1) return false;
+  const w = samples.slice(-(n + 1));
+  let rises = 0;
+  for (let i = 1; i < w.length; i++) {
+    if (w[i] < w[i - 1]) return false;
+    if (w[i] > w[i - 1]) rises++;
+  }
+  return rises > n * 0.6;
+}
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**
@@ -207,6 +240,12 @@ export class DiagRecorder {
     this._listeners = new Set();
     this._lafo = null;
     this._gl = null; // the wrapped context + its originals, for dispose()
+    /** GL object counts on the tile's context (instrumentGl): programs / shaders created + deleted. */
+    this.glObjects = { programs: { created: 0, deleted: 0 }, shaders: { created: 0, deleted: 0 } };
+    this.shaderCacheState = null; // () => the engine shader-cache patch state (./inline3d-pc-shader-cache.js)
+    this.programReleaseState = null; // () => { state, released, … } (./inline3d-pc-auto-release.js)
+    this._swapLive = new Map(); // kind → live programs at each content swap of that kind (the leak watch)
+    this._leakWarned = false;
     this._burst = null; // the pick burst of the current task
   }
 
@@ -266,6 +305,25 @@ export class DiagRecorder {
    */
   instrumentGl(gl) {
     if (!gl || this._gl) return;
+    // Object counts first (no timing): what a content swap leaves behind.
+    const objs = this.glObjects;
+    const counters = {
+      createProgram: (r) => r && objs.programs.created++,
+      deleteProgram: (r, a) => a[0] && objs.programs.deleted++,
+      createShader: (r) => r && objs.shaders.created++,
+      deleteShader: (r, a) => a[0] && objs.shaders.deleted++,
+    };
+    const counted = [];
+    for (const [name, count] of Object.entries(counters)) {
+      const orig = gl[name];
+      if (typeof orig !== 'function') continue;
+      gl[name] = function (...a) {
+        const r = orig.apply(this, a);
+        count(r, a);
+        return r;
+      };
+      counted.push(name);
+    }
     const LINK = 0x8b82;
     const COMPLETION = 0x91b1;
     const kinds = {
@@ -294,7 +352,37 @@ export class DiagRecorder {
       };
       saved.push(name);
     }
-    this._gl = { gl, saved };
+    this._gl = { gl, saved: [...counted, ...saved] };
+  }
+
+  /** Live programs / shaders on the tile's context since instrumentGl (created − deleted). */
+  liveGl() {
+    const { programs: p, shaders: s } = this.glObjects;
+    return { programs: p.created - p.deleted, shaders: s.created - s.deleted };
+  }
+
+  /**
+   * A content swap happened (`kind`: 'setSource' at its start, 'container' at a glTF load,
+   * 'release' after a releaseEntity): sample the live program count, and warn once when the
+   * samples of that kind look like a leak (looksLikeLeak).
+   */
+  contentSwap(kind) {
+    if (!this._gl) return null;
+    const live = this.liveGl();
+    let w = this._swapLive.get(kind);
+    if (!w) this._swapLive.set(kind, (w = []));
+    w.push(live.programs);
+    if (w.length > LEAK_SWAPS + 1) w.shift();
+    this._event('swap', { kind, ...live }, this.now());
+    if (!this._leakWarned && looksLikeLeak(w)) {
+      this._leakWarned = true;
+      console.warn(
+        `[inline3d/${this.label.split('#')[0]}] diag: live WebGL programs never dropped across the last ${LEAK_SWAPS} content swaps ` +
+          `and rose at most of them (${kind}: ${w.join(' → ')}). Something each swap replaces is not released — see docs/content-lifecycle-rules.md ` +
+          '(handle.releaseEntity for content under handle.engine.root). Warned once.',
+      );
+    }
+    return live;
   }
 
   /** One GL call of `kind` that took `ms`, at `t` (instrumentGl's wrappers; tests call it directly). */
@@ -578,6 +666,7 @@ export class DiagRecorder {
       label: this.label,
       switches: [...this.switches],
       rigLocked: this.rigLocked,
+      glObjects: { ...this.glObjects, live: this.liveGl(), shaderCache: safe(() => this.shaderCacheState?.()) ?? null, programRelease: safe(() => this.programReleaseState?.()) ?? null },
       transitions: this.transitions,
       events: this.events,
       frames: this.frames,
@@ -794,7 +883,8 @@ export function startDiagLoop(rec, { overlay = true, doc = typeof document !== '
       `dxr-diag ${rec.label}  phase ${rec.phase}` +
       (Number.isFinite(rec.callAt) ? `  +${Math.round(now - rec.callAt)} ms since setSource` : '') +
       (rec.switches.size ? `  [${[...rec.switches].join(',')}]` : '') +
-      (last ? `\nframe dt ${last.dt} ms  held ${last.held ? 'YES' : 'no'}  img ${last.img}${last.img !== 'none' ? ' ' + last.imgW : ''}` : '');
+      (last ? `\nframe dt ${last.dt} ms  held ${last.held ? 'YES' : 'no'}  img ${last.img}${last.img !== 'none' ? ' ' + last.imgW : ''}` : '') +
+      (rec._gl ? `\n${glObjectsLine(rec)}` : '');
     strip(rec.frames, 0, now - WINDOW_MS, now, rec.callAt);
     if (frozen && g) {
       strip(frozen.window.map((f) => ({ ...f })), STRIP_H + 18, -PRE_MS, WINDOW_MS - PRE_MS, 0);
@@ -818,6 +908,37 @@ export function startDiagLoop(rec, { overlay = true, doc = typeof document !== '
   };
 }
 
+/**
+ * The live-GL-object watch on a PlayCanvas tile: count the context's programs and shaders, show
+ * the engine shader-cache patch state, and sample at the content swaps the SDK can see (a
+ * container load in the tile's registry, a releaseEntity). setSource samples itself.
+ */
+export function watchContent(rec, app, viewer) {
+  rec.instrumentGl(app?.graphicsDevice?.gl);
+  rec.shaderCacheState = () => app?.graphicsDevice?.__dxrShaderCache ?? null;
+  rec.programReleaseState = () => {
+    const state = app?.graphicsDevice?.__dxrAutoRelease ?? null;
+    const st = autoReleaseStats(app);
+    return state ? { state, ...(st || {}) } : null;
+  };
+  const ar = autoReleaseState(app);
+  if (ar) ar.onSweep = (n) => n && rec.contentSwap('auto-release');
+  if (viewer) viewer.onContentReleased = () => rec.contentSwap('release');
+  app?.assets?.on?.('load', (a) => a?.type === 'container' && rec.contentSwap('container'));
+}
+
+/** The overlay's GL objects line: live programs and shaders (created / deleted), the cache patch. */
+export function glObjectsLine(rec) {
+  const { programs: p, shaders: s } = rec.glObjects;
+  const cache = safe(() => rec.shaderCacheState?.());
+  const rel = safe(() => rec.programReleaseState?.());
+  return (
+    `gl programs ${p.created - p.deleted} live (+${p.created} −${p.deleted})  shaders ${s.created - s.deleted} live (+${s.created} −${s.deleted})` +
+    (cache ? `  cache ${cache}` : '') +
+    (rel ? `  release ${rel.state}${rel.released !== undefined ? ` (−${rel.released})` : ''}` : '')
+  );
+}
+
 /**
  * `window.__dxrDiag`: every diag tile on the page. `dump()` is the JSON to paste back;
  * `last` the most recent tile's recorder; `transitions` every tile's transition summaries.
@@ -839,7 +960,7 @@ export function registerDiag(rec) {
       },
     };
   }
-  rec.label = `splat#${g.tiles.length + 1}`;
+  rec.label = `${rec.label || 'splat'}#${g.tiles.length + 1}`;
   g.tiles.push(rec);
   const dispose = rec.dispose.bind(rec);
   rec.dispose = () => {

package/js/inline3d-splat-playcanvas.js

@@ -73,7 +73,7 @@ import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
 import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNIFORM, makeSbsMaterial } from './inline3d-splat-video.js';
 import { LayerRigCameras, validateLayerRig, validateLayerRigOptions, DEFAULT_VIEWER_DISTANCE_M } from './inline3d-splat-layer-rig.js';
 import { RigTracker, remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
-import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, DIAG_SWITCHES } from './inline3d-splat-diag.js';
+import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, watchContent, DIAG_SWITCHES } from './inline3d-splat-diag.js';
 import {
   glBufferLimits,
   probeBufferLimits,
@@ -127,6 +127,9 @@ import {
   framedSubjectBounds,
 } from './inline3d-splat-shared.js';
 import { resolveCursorOption } from './inline3d-cursor-option.js';
+import { installShaderCacheRelease } from './inline3d-pc-shader-cache.js';
+import { installAutoProgramRelease } from './inline3d-pc-auto-release.js';
+import { releaseEntity as releaseEntityIn } from './inline3d-pc-release.js';
 
 /**
  * The component systems the tile's `AppBase` registers. Camera + GSplat draw the splat; Render,
@@ -1284,6 +1287,18 @@ export class PlayCanvasSplatViewer {
     return shaders.size;
   }
 
+  /**
+   * Destroy `entity` (content a page added under `engine.root`) and release the programs its
+   * materials linked, plus its glTF container (`asset`) when nothing else draws from it —
+   * ./inline3d-pc-release.js, docs/content-lifecycle-rules.md. Returns { programs, container }.
+   */
+  releaseEntity(entity, { asset = null } = {}) {
+    if (!this.app || this._disposed) return { programs: 0, container: null };
+    const r = releaseEntityIn(this.app, entity, { asset });
+    this.onContentReleased?.(r);
+    return r;
+  }
+
   useSceneColor(on = true) {
     this.sceneColor = !!on;
     const cams = [this.eye, ...(this._viewPath === 'cameras' ? this._views : [])];
@@ -1415,7 +1430,7 @@ export class PlayCanvasSplatViewer {
    * @param {object} o.perf  the resolved playcanvasPerfSettings().
    * @param {string} [o.viewPath]  force 'cameras' | 'renderview' (diagnostics).
    */
-  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath, antialias = false, patchSplats = true } = {}) {
+  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath, antialias = false, patchSplats = true, shaderCacheRelease = true, programRelease = true } = {}) {
     this.pc = pc;
     const device = await pc.createGraphicsDevice(this.canvas, {
       deviceTypes: [pc.DEVICETYPE_WEBGL2],
@@ -1431,6 +1446,11 @@ export class PlayCanvasSplatViewer {
       device.destroy?.();
       return null;
     }
+    // The engine keeps every compiled shader until the device dies, even once its program is
+    // destroyed: count them per program and free the last one out (./inline3d-pc-shader-cache.js).
+    // `?dxrdiag=keepshaders` leaves the engine's cache as it ships (A/B; page-wide, first tile wins).
+    if (shaderCacheRelease) installShaderCacheRelease(device);
+    else device.__dxrShaderCache ??= 'off (keepshaders)';
     const opts = new pc.AppOptions();
     opts.graphicsDevice = device;
     // No xr (AppBase constructs XrManager only when asked, and XrManager is what probes and
@@ -1442,6 +1462,11 @@ export class PlayCanvasSplatViewer {
     const app = new pc.AppBase(this.canvas);
     app.init(opts);
     guardDuplicateSystems(app);
+    // A material the page destroys (entity.destroy, a container's unload) keeps every program it
+    // linked for the device's life: release them a frame later, when nothing else uses them
+    // (./inline3d-pc-auto-release.js). `?dxrdiag=keepprograms` leaves the engine as it ships (A/B).
+    if (programRelease) installAutoProgramRelease(app, pc.Material);
+    else device.__dxrAutoRelease ??= 'off (keepprograms)';
     // The SDK sizes the buffer (double-width in 3D, 1:1 in mono), so the engine must never
     // resize it. RESOLUTION_FIXED is AppBase's DEFAULT, and with it `updateCanvasSize()` is a
     // no-op. Deliberately NOT calling setCanvasResolution/setCanvasFillMode: without explicit
@@ -3583,6 +3608,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       await first.catch(() => null);
       return removed ? 0 : viewer.warmEntity(entity, o);
     },
+    /**
+     * Destroy `entity` (content under handle.engine.root) and release the programs its materials
+     * linked, and its container `asset` when nothing else draws from it — viewer.releaseEntity.
+     * Returns { programs, container }.
+     */
+    releaseEntity(entity, o) {
+      return removed ? { programs: 0, container: null } : viewer.releaseEntity(entity, o);
+    },
     setStereo,
     setDepthEnvelope,
     /**
@@ -4745,12 +4778,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       perf: perfResolved,
       viewPath: opts.playcanvasViewPath,
       antialias: antialias === true,
+      shaderCacheRelease: !diag?.has('keepshaders'),
+      programRelease: !diag?.has('keepprograms'),
     });
     if (!app || removed) return null;
     pcModule = pc;
     // diag: count the GL calls that can block (compile, link, status queries, readbacks, syncs),
     // from before the first asset's compile on
-    if (diag) diag.instrumentGl(app.graphicsDevice?.gl);
+    // + the live program / shader counts and the content-swap leak watch
+    if (diag) watchContent(diag, app, viewer);
     /**
      * ADVANCED, not covered by the semver promise: the engine objects behind this window.
      * `app` is the tile's `pc.AppBase`; `root` the content root, in the splat's content space
@@ -5335,6 +5371,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const gen = ++sourceGen;
     if (diag) {
       rigLockArmed = true;
+      diag.contentSwap('setSource'); // the previous swap's outgoing asset is released by now
       diag.setPhase('swap', {
         transition: plan.sequence ? `${plan.sequence.name}(${plan.sequence.out.effect}>${plan.sequence.in.effect})` : plan.transition,
         outgoing: plan.sequence ? 'none (one splat)' : plan.outgoing || 'default',

package/js/inline3d-splat.js

@@ -447,6 +447,8 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
     },
     /** PlayCanvas-backend feature (its renderer links synchronously); nothing to warm here. */
     warmEntity: () => Promise.resolve(0),
+    /** PlayCanvas-backend feature: three.js content is the page's to dispose (docs/content-lifecycle-rules.md). */
+    releaseEntity: () => ({ programs: 0, container: null }),
     stopEffect() {
       throw effectsNotOnSpark('stopEffect()');
     },

package/llms.txt

@@ -15,6 +15,7 @@ detail, a cover that always comes off). The SDK's defaults do the rest.
 ## Reference
 - docs/authoring-inline-3d.md — every API, both view rigs, comfort maths
 - docs/woven-canvas-rules.md — what the browser does to a woven canvas; CSS, remount and cover rules
+- docs/content-lifecycle-rules.md — swapping content in a window: release programs, textures, containers (handle.releaseEntity)
 - docs/porting-three-js-apps.md — moving an existing three.js app over
 - docs/authoring-motion-and-effects.md, docs/splat-effects.md — motion, reveals, depth envelopes
 - index.d.ts, three.d.ts, viewer.d.ts, model.d.ts, splat.d.ts — the public API with JSDoc

package/model.d.ts

@@ -283,6 +283,18 @@ export interface ModelHandle {
    * docs/playcanvas-adapter.md §warmEntity.
    */
   warmEntity(entity?: unknown, opts?: { timeoutMs?: number }): Promise<number>;
+  /**
+   * `engine: 'playcanvas'` only (a no-op returning `{ programs: 0, container: null }` on three).
+   * Destroy `entity` — content you added under `handle.engine.root` — and release what it held on
+   * the GPU: the shader programs its materials linked (PlayCanvas never frees a program by itself:
+   * its ProgramLibrary caches every variant for the device's life, and `Material.destroy()` does
+   * not destroy them), and, with `asset`, the glTF container it was instantiated from (unloaded
+   * and taken out of the registry unless something else in the tile still draws from it). A
+   * program another material still uses is kept. Call it for whatever a content swap replaces.
+   * Returns the number of programs destroyed and what happened to the container.
+   * docs/content-lifecycle-rules.md.
+   */
+  releaseEntity(entity: unknown, opts?: { asset?: unknown }): { programs: number; container: 'unloaded' | 'in-use' | null };
   unexclude(el: Element): void;
   /**
    * The core window's `TileHandle.firstWoven`: when it is safe to reveal the canvas. Resolves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.47.4",
+  "version": "1.47.6",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -74,6 +74,7 @@
     "llms.txt",
     "docs/making-3d-look-right.md",
     "docs/woven-canvas-rules.md",
+    "docs/content-lifecycle-rules.md",
     "js/inline3d.js",
     "js/inline3d-undock.js",
     "js/inline3d-display-metrics.js",
@@ -108,6 +109,9 @@
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",
     "js/inline3d-pc-look.js",
+    "js/inline3d-pc-auto-release.js",
+    "js/inline3d-pc-release.js",
+    "js/inline3d-pc-shader-cache.js",
     "js/inline3d-playcanvas-engine.js",
     "js/inline3d-player.js",
     "js/inline3d-camera.js",