@plasius/gpu-shared 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -16,6 +16,25 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.1.3] - 2026-03-26
+
+- **Added**
+  - Public-contract tests that lock the package export surface for the shared
+    runtime and bundled brigantine asset.
+  - Public `destroy()` teardown hook on `mountGpuShowcase()` so browser consumers can clean up the shared runtime safely on route/page unmount.
+
+- **Changed**
+  - Documented the import-map pattern for browser demos so consumers stay on the
+    published `@plasius/gpu-shared` package surface instead of deep internal
+    paths.
+  - README usage now documents the shared teardown contract for public consumers.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.1.2] - 2026-03-23
 
 - **Added**
@@ -65,3 +84,4 @@ All notable changes to this project will be documented in this file.
 [0.1.0]: https://github.com/Plasius-LTD/gpu-shared/releases/tag/v0.1.0
 [0.1.1]: https://github.com/Plasius-LTD/gpu-shared/releases/tag/v0.1.1
 [0.1.2]: https://github.com/Plasius-LTD/gpu-shared/releases/tag/v0.1.2
+[0.1.3]: https://github.com/Plasius-LTD/gpu-shared/releases/tag/v0.1.3

package/README.md

@@ -34,12 +34,29 @@ npm install @plasius/gpu-shared
 ```js
 import { mountGpuShowcase } from "@plasius/gpu-shared";
 
-await mountGpuShowcase({
+const showcase = await mountGpuShowcase({
   root: document.getElementById("app"),
   packageName: "@plasius/gpu-demo-viewer",
   title: "Flag by the Sea",
   subtitle: "Shared 3D validation scene for the gpu-* family.",
 });
+
+// Teardown is safe to call repeatedly from a route/page cleanup.
+showcase.destroy();
+```
+
+For browser-only demos served without a bundler, keep the import surface on the
+published package name and resolve it with an import map rather than importing a
+viewer-private or workspace-private source file:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "@plasius/gpu-shared": "../node_modules/@plasius/gpu-shared/dist/index.js"
+    }
+  }
+</script>
 ```
 
 ## Asset Helpers
@@ -80,6 +97,7 @@ surface for these family demos.
 ## API
 
 - `mountGpuShowcase(options)`
+  - Returns `{ state, shipModel, canvas, destroy() }`
 - `loadGltfModel(url)`
 - `resolveShowcaseAssetUrl(baseUrl?)`
 - `showcaseFocusModes`

package/dist/index.cjs

@@ -7802,6 +7802,9 @@ function syncTextState(state, shipModel) {
 async function mountGpuShowcase(options = {}) {
   injectStyles();
   const root = options.root ?? document.body;
+  const previousMarkup = root.innerHTML;
+  const previousRenderGameToText = window.render_game_to_text;
+  const previousAdvanceTime = window.advanceTime;
   const focus = options.focus ?? new URLSearchParams(window.location.search).get("focus") ?? "integrated";
   const dom = buildDemoDom(root, {
     packageName: options.packageName ?? "@plasius/gpu-demo-viewer",
@@ -7818,7 +7821,12 @@ async function mountGpuShowcase(options = {}) {
   state.demoDescription = resolveSceneDescription(state, options, shipModel).description;
   syncTextState(state, shipModel);
   const ctx = dom.canvas.getContext("2d");
+  let destroyed = false;
+  let frameHandle = null;
   const renderFrame = (nowMs) => {
+    if (destroyed) {
+      return;
+    }
     if (!state.paused) {
       if (state.lastTimeMs == null) {
         state.lastTimeMs = nowMs;
@@ -7835,27 +7843,53 @@ async function mountGpuShowcase(options = {}) {
     state.demoDescription = resolveSceneDescription(state, options, shipModel).description;
     renderScene(ctx, dom.canvas, state, shipModel, dom);
     syncTextState(state, shipModel);
-    requestAnimationFrame(renderFrame);
+    frameHandle = requestAnimationFrame(renderFrame);
   };
-  dom.pauseButton.addEventListener("click", () => {
+  const handlePauseClick = () => {
     state.paused = !state.paused;
     dom.pauseButton.textContent = state.paused ? "Resume" : "Pause";
-  });
-  dom.stressToggle.addEventListener("change", () => {
+  };
+  const handleStressChange = () => {
     state.stress = dom.stressToggle.checked;
-  });
-  dom.focusMode.addEventListener("change", () => {
+  };
+  const handleFocusChange = () => {
     state.focus = dom.focusMode.value;
     Object.assign(state.camera, {
       ...CAMERA_PRESETS[state.focus],
       target: vec3(...CAMERA_PRESETS[state.focus].target)
     });
-  });
-  requestAnimationFrame(renderFrame);
+  };
+  dom.pauseButton.addEventListener("click", handlePauseClick);
+  dom.stressToggle.addEventListener("change", handleStressChange);
+  dom.focusMode.addEventListener("change", handleFocusChange);
+  frameHandle = requestAnimationFrame(renderFrame);
   return {
     state,
     shipModel,
-    canvas: dom.canvas
+    canvas: dom.canvas,
+    destroy() {
+      if (destroyed) {
+        return;
+      }
+      destroyed = true;
+      if (frameHandle != null) {
+        cancelAnimationFrame(frameHandle);
+      }
+      dom.pauseButton.removeEventListener("click", handlePauseClick);
+      dom.stressToggle.removeEventListener("change", handleStressChange);
+      dom.focusMode.removeEventListener("change", handleFocusChange);
+      root.innerHTML = previousMarkup;
+      if (typeof previousRenderGameToText === "function") {
+        window.render_game_to_text = previousRenderGameToText;
+      } else {
+        delete window.render_game_to_text;
+      }
+      if (typeof previousAdvanceTime === "function") {
+        window.advanceTime = previousAdvanceTime;
+      } else {
+        delete window.advanceTime;
+      }
+    }
   };
 }
 function updatePhysicsSnapshot(state, shipModel) {