@displayxr/inline3d 1.47.5 → 1.47.6

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.5",
+  "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",

package/splat.d.ts

@@ -1135,6 +1135,18 @@ export interface SplatHandle {
    * it after this resolves. Resolves the number of programs warmed. 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 Spark).
+   * 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 };
   setStereo(opts: SplatStereoOptions | null): SplatHandle;
   /**
    * The `depth` option's comfort factor in force, in (0, 1]: what the display rig's ipdFactor and