@displayxr/inline3d 1.47.4 → 1.47.6

package/CHANGELOG.md

@@ -7,6 +7,81 @@ which tier they touch, because that is what tells you whether an upgrade can mov
 
 ## Unreleased
 
+## 1.47.6 — 2026-11-03
+
+### Fixed — a page that destroys PlayCanvas materials no longer keeps their programs (`./splat`, `./model`)
+
+Preview tier. When a page destroys a material on a PlayCanvas tile the SDK created, either
+directly or through a glTF container's `asset.unload()`, the SDK now destroys the programs that
+material linked, one frame later, when no mesh instance in the app, no material asset in the
+registry and no still-alive material holds them. A page that follows the engine's own teardown
+(`entity.destroy()` plus destroying or unloading what it drew with) is bounded without calling
+`handle.releaseEntity`. Measured on macOS, 24 swaps of distinct products under one tile: 2 live
+programs (25 created, 23 deleted), against 25 (none deleted) before. A kiosk app with one
+persistent stage had reached 170 live programs over 28 screen changes.
+
+Content shown again after its material was destroyed recompiles on its first draw
+(`handle.warmEntity` hides that). A material the page keeps alive keeps its programs.
+`?dxrdiag=keepprograms` turns the release off for an A/B, and the overlay shows
+`release patched (−N)`. It installs only on PlayCanvas 2.22.x's `Material` shape and otherwise
+reports `release skipped: …`. `docs/content-lifecycle-rules.md` rule 1 and §6 are updated.
+
+### Added — `handle.releaseEntity`: swap content in a PlayCanvas tile without leaking its programs (`./splat`, `./model`)
+
+Preview tier. PlayCanvas never frees a shader program by itself: its `ProgramLibrary` caches every
+variant for the device's life, and `Material.destroy()` (which `entity.destroy()` and a container's
+`asset.unload()` reach) only empties `material.variants`. A page that swaps glTFs under
+`handle.engine.root` (a carousel, a catalogue) therefore kept every program it ever showed, and a
+desktop driver keeps each linked program's compiled form (about 5 MB per program, measured on one
+Linux driver): a production page's GPU process grew about 8 MB/min for as long as it was open.
+
+- `handle.releaseEntity(entity, { asset })` on `addSplat(…, { engine: 'playcanvas' })` and
+  PlayCanvas `addModel` handles: collects the programs the entity's materials linked, destroys the
+  entity, unloads its glTF container `asset` unless something else in the tile still draws from it,
+  then destroys each collected program nothing left uses (`Shader.destroy()`, the engine's own
+  release). Returns `{ programs, container }`. A no-op on Spark and three.
+  Measured over 24 distinct models: live programs 5 → 47 without it, bounded at 5–16 (the model on
+  screen) with it.
+
+### Fixed — the engine kept every compiled shader until the device died (`./splat`, `./model`)
+
+Preview tier. PlayCanvas 2.22.3 keeps every compiled vertex and fragment shader in a
+module-private cache keyed by source, and `WebglShader.destroy()` deletes only the program. So
+even with the programs destroyed, two compiled shaders per program stayed (10 → 91 over the same 24
+swaps). The SDK now counts, per cached shader, the programs that use it and deletes it with the last
+one, on every PlayCanvas device it creates (`js/inline3d-pc-shader-cache.js`: a run-time patch of the
+engine's `WebglShader` prototype, since the engine is the page's own dependency; it installs only on
+the 2.22.x shape and otherwise steps aside). With `releaseEntity`, shaders stay at exactly twice the
+live programs. `?dxrdiag=keepshaders` turns it off for an A/B.
+
+### Added — live GL object counts and a leak warning in `?dxrdiag` (`./splat`, `./model`)
+
+The diagnostics overlay shows live programs and shaders on the tile's context (created and deleted
+since diag attached) and the shader-cache fix's state; the dump carries them under `glObjects`. At
+each content swap the SDK sees (`setSource`, a glTF container loaded into the tile's registry,
+`releaseEntity`) it samples the live program count, and warns once when it has not dropped across
+10 swaps of one kind and rose at more than 60% of them. `addModel`'s PlayCanvas tile now honours
+`?dxrdiag` too. Nothing runs when diag is off.
+
+### Docs
+
+- New [`docs/content-lifecycle-rules.md`](docs/content-lifecycle-rules.md): what a swap must release,
+  PlayCanvas and three.js engine facts, the hook-and-plateau pass test, the SDK's own swap paths
+  measured, and what the SDK does vs what the page owns.
+
+## 1.47.5 — 2026-11-01
+
+### Fixed — the camera permission prime could open a phone lens and crash its camera (`./camera`, `./call`)
+
+Before camera permission, `openCamera('auto')` primed on `{1280x720, facingMode: 'environment'}`.
+On a phone whose lenses all report the same facing, that picked camera 0, one lens of the 3D
+camera's pair, and on some phones a plain open of that lens, or its teardown, crashes the camera
+service. The prime now asks for the default camera with no constraints. The DisplayXR Browser lists
+its 3D camera first, so the prime opens the pair directly and no lens is opened. A desktop webcam is
+still opened once and kept, and is then asked for the usual 1280x720 mode without a second start.
+With labels visible but no 3D camera listed, the list is read once more before the fallback, since
+a runtime 3D camera can appear late after a runtime restart.
+
 ## 1.47.4 — 2026-10-31
 
 ### Fixed — a declared 3D camera with portrait eyes was dropped for a plain one (`./camera`, `./call`)

package/README.md

@@ -166,7 +166,8 @@ No projection math lands in your page or in the SDK — the off-axis frustum sta
 Full API + authoring guidance: [`docs/authoring-inline-3d.md`](docs/authoring-inline-3d.md).
 Before you ship a page that navigates or remounts, read
 [`docs/woven-canvas-rules.md`](docs/woven-canvas-rules.md): how to avoid a raw side-by-side
-flash, and releasing a poster on `handle.firstWoven`.
+flash, and releasing a poster on `handle.firstWoven`. A page that swaps content in a window (a
+carousel, a catalogue): [`docs/content-lifecycle-rules.md`](docs/content-lifecycle-rules.md).
 Three.js glue (an off-axis `EyeCamera`) in [`js/inline3d-three.js`](js/inline3d-three.js).
 
 ## What's here
@@ -198,6 +199,8 @@ js/
   inline3d-model-entry.js       experimental: addModel() — picks the engine (PlayCanvas default)
   inline3d-model-playcanvas.js  the PlayCanvas model backend (Sample-Viewer lighting, engine decoders)
   inline3d-pc-look.js           PlayCanvas look helpers for both adapters (environments, transmission)
+  inline3d-pc-release.js        handle.releaseEntity: content under engine.root out, its programs + container released
+  inline3d-pc-shader-cache.js   engine fix: a compiled shader is deleted with the last program using it
   inline3d-model.js             the three.js model backend (engine:'three'; ./model/three)
   inline3d-playcanvas-engine.js named playcanvas imports for both PlayCanvas adapters (tree-shaking)
   inline3d-splat-effects.js     splat shader effects: the runner, the effect registry (PlayCanvas)
@@ -215,6 +218,9 @@ docs/
                            the WebXR→inline-3d mapping table and the whole render loop
   woven-canvas-rules.md    never show a raw side-by-side frame: the join, the rules,
                            handle.firstWoven / rewoven(), reading the browser's `withheld` log line
+  content-lifecycle-rules.md
+                           release what a content swap replaces (programs included):
+                           handle.releaseEntity, engine facts, the hook-and-plateau pass test
   camera.md                The 3D camera primitive (/camera): openCamera, the mirrored self view,
                            capturePhoto / record with the stereo record inside the file.
   call.md                  3D video calls: the <dxr-call> / mountCall() one-line embed, options,