partforge 0.39.0 → 0.41.0

package/src/framework/mount.js

@@ -31,6 +31,15 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     ready, dispose, setParams,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
+    // Park/unpark the viewer: stops the render loop and frees the drawing
+    // buffer and the cached capture target. For an embedder that hides the
+    // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
+    // where nothing collapses the container and the loop would otherwise run
+    // forever. See the setActive comment in viewer.js for what it costs.
+    setActive: (active) => viewer.setActive(active),
+    // Subscribe to WebGL context loss (returns an unsubscribe), so a host can
+    // say "the 3D view ran out of memory" instead of showing a dead canvas.
+    onContextLost: (listener) => viewer.onContextLost(listener),
     listExportableParts,
     exportParts,
     // Narrow-layout pane selection, for a host that draws its own tab bar
@@ -69,7 +78,7 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.39.0):
+// Embedding contract (0.41.0):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
@@ -86,6 +95,17 @@ function createCleanupStack() {
 //   runtime.setHostPane("rail");  // narrow layout only: show just the controls
 //                                 // rail ('stage' | 'rail'), suppressing the
 //                                 // built-in tab bar. null hands selection back.
+//   runtime.setActive(false);     // park the viewer: stop the render loop and release
+//                                 // both large GPU allocations (the drawing buffer and
+//                                 // the cached capture target). For a host that hides the
+//                                 // canvas WITHOUT unmounting it (`visibility: hidden`, an
+//                                 // inactive tab) — nothing else can detect that, and the
+//                                 // loop would otherwise render a hidden pane forever.
+//                                 // Captures still work while parked (they re-allocate).
+//                                 // setActive(true) restores it. Safe after dispose().
+//   const off = runtime.onContextLost(() => …);  // WebGL context loss, i.e. the GPU or the
+//                                 // OS gave up — surface it rather than showing a dead
+//                                 // canvas. Returns an unsubscribe.
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.

package/src/framework/verify-metrics.js

@@ -2,7 +2,9 @@
 // is a hard gate or a warning, and the diagnostics attached to a non-pass check:
 // `hint` (required — the report contract promises one on every fail/warn),
 // `pattern` (optional stable ERROR-PATTERNS.md#<id>), `locate` (optional
-// [x,y,z] source). `manifoldOnly` facts are null on OCCT parts.
+// [x,y,z] source), `note` (optional caveat about HOW the value was measured,
+// attached whatever the status — a passing-but-sampled reading is exactly the
+// case a reader needs told about). `manifoldOnly` facts are null on OCCT parts.
 //
 // This lives in framework/ rather than testing/ deliberately: the set of legal
 // `verify.expect` metrics is part of the PartDefinition CONTRACT, which both the
@@ -32,7 +34,18 @@ export const SUBPART_METRICS = {
   minWall: { kind: "warn", extract: (s) => s.minWall,
     hint: "thinnest wall is at the reported location — increase the governing wall/thickness parameter or reduce the intersecting feature's depth",
     pattern: "minwall-sliver-triangles",
-    locate: (s) => s.minWallAt },
+    locate: (s) => s.minWallAt,
+    // Two sampled outcomes, and the second is the one that most needs saying: a
+    // sampled run that found NO wall reports minWall null, which without this note
+    // is indistinguishable from a part nobody measured. `sampled` counts triangles
+    // the walk selected, not rays cast — degenerate triangles are skipped.
+    note: (s) => {
+      if (!s.minWallSampled || !s.minWallSamples) return null;
+      const { sampled, total } = s.minWallSamples;
+      return s.minWall == null
+        ? `no reading from the ${sampled} of ${total} triangles sampled — not a clean bill of health; a thin spot may exist between samples`
+        : `sampled ${sampled} of ${total} triangles — an upper bound; a thinner spot may exist between samples`;
+    } },
 };
 export const VIEW_METRICS = {
   bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,

package/src/framework/viewer.js

@@ -94,6 +94,10 @@ export function createViewer(container, part) {
   renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
   container.appendChild(renderer.domElement);
 
+  // Declared up here, not beside setActive() below, because the initial resize()
+  // runs during construction and reads it.
+  let active = true;
+
   const scene = new THREE.Scene();
 
   // Light/dark scene palettes (the page chrome is themed separately, via CSS on the
@@ -175,14 +179,24 @@ export function createViewer(container, part) {
   }
 
   // The cutaway plane lives in world space, so its initial/reset bounds must
-  // include the pivot rotation and the per-view recentering transform.
+  // include the pivot rotation and the per-view recentering transform —
+  // mesh.matrixWorld carries both. Union each visible mesh's own
+  // geometry.boundingBox rather than `Box3.expandByObject`, which recurses into
+  // children: the two stencil-pass meshes share `mesh.geometry` so that
+  // recursion is harmless for them, but the cut-face outline child carries its
+  // own independent geometry that only re-slices while the cutaway is enabled
+  // and visible — while hidden it can keep segments from an older, larger part
+  // and inflate these bounds. A subpart's initial placeholder BufferGeometry
+  // has no boundingBox computed (only buildGeometry computes one), so skip it.
   const _worldBounds = new THREE.Box3();
+  const _meshBounds = new THREE.Box3();
   function getVisibleWorldBounds() {
     _worldBounds.makeEmpty();
     for (const mesh of Object.values(subMesh)) {
-      if (!mesh.visible || !mesh.geometry) continue;
+      if (!mesh.visible || !mesh.geometry?.boundingBox) continue;
       mesh.updateWorldMatrix(true, false);
-      _worldBounds.expandByObject(mesh);
+      _meshBounds.copy(mesh.geometry.boundingBox).applyMatrix4(mesh.matrixWorld);
+      _worldBounds.union(_meshBounds);
     }
     return _worldBounds;
   }
@@ -351,6 +365,10 @@ export function createViewer(container, part) {
   // --- resize ---------------------------------------------------------------
   // Size from the host container (not the window) so embedders control the pane.
   function resize() {
+    // Parked (see setActive): the buffer is deliberately 1x1 and must stay that
+    // way. iOS fires resizes constantly as the URL bar collapses, and every one
+    // of them would otherwise re-allocate a full MSAA buffer for a hidden pane.
+    if (!active) return;
     const w = container.clientWidth || 300, h = container.clientHeight || 150;
     renderer.setSize(w, h);
     camera.aspect = w / h;
@@ -471,12 +489,66 @@ export function createViewer(container, part) {
   }
 
   // --- render loop ----------------------------------------------------------
-  renderer.setAnimationLoop(() => {
+  function renderFrame() {
     controls.update();
     if (cutaway.isEnabled) cutaway.updateForCamera();
     renderer.render(scene, camera);
     cutaway.renderOverlay(renderer, camera);
-  });
+  }
+  renderer.setAnimationLoop(renderFrame);
+
+  // --- active / parked ------------------------------------------------------
+  // For a host that HIDES the viewer without unmounting it. partforge's own
+  // narrow layout uses `display: none` on the stage, which zeroes clientWidth
+  // and lets the ResizeObserver above collapse the buffer for free. An embedder
+  // that cannot do that — partforge-cloud's phone tab bar uses
+  // `visibility: hidden`, because the canvas has to keep its size for build
+  // screenshots — gets no such signal: the full-resolution MSAA drawing buffer
+  // stays resident and this loop keeps rendering an auto-rotating scene at
+  // 60fps behind an invisible pane. On an iPhone that is tens of megabytes and
+  // continuous GPU work nobody can see, so the host has to say so explicitly.
+  //
+  // Parking stops the loop and releases the drawing buffer. `setSize(1, 1,
+  // false)` leaves the canvas element's CSS box alone, so the host's layout
+  // does not move and the pane can be revealed again without a reflow.
+  function setActive(next) {
+    const want = next !== false;
+    if (disposed || want === active) return;
+    active = want;
+    if (!active) {
+      renderer.setAnimationLoop(null);
+      renderer.setSize(1, 1, false);
+      // The cached 1024² 4x-MSAA + stencil capture target is the other large
+      // allocation here — on a phone it is comparable to the canvas itself, so
+      // parking that kept it would leave half the memory behind. Dropping it
+      // costs one re-allocation on the next capture, which a parked viewer
+      // barely notices: the cache only ever hits on an exactly-square request,
+      // and a phone's capture aspect is not square, so those captures were
+      // allocating per call regardless.
+      _rt?.dispose();
+      _rt = null;
+      return;
+    }
+    resize(); // rebuild the buffer at whatever size the container is now
+    renderer.setAnimationLoop(renderFrame);
+  }
+
+  // --- context loss ---------------------------------------------------------
+  // Losing the WebGL context is how a memory-starved phone tells you it gave
+  // up. With no handler the canvas just freezes, indistinguishable from a hang,
+  // and three never re-initialises. preventDefault() is what makes the loss
+  // recoverable (three's own listener re-uploads on restore); the subscribers
+  // let an embedder surface it instead of showing a dead rectangle.
+  const contextLostListeners = new Set();
+  const onContextLostEvent = (event) => {
+    event.preventDefault();
+    for (const listener of [...contextLostListeners]) listener();
+  };
+  renderer.domElement.addEventListener("webglcontextlost", onContextLostEvent);
+  function onContextLost(listener) {
+    contextLostListeners.add(listener);
+    return () => contextLostListeners.delete(listener);
+  }
 
   // --- camera state (read/write for persistence; mount.js owns storage) -------
   function getCameraState() {
@@ -518,6 +590,11 @@ export function createViewer(container, part) {
     disposed = true;
     ro.disconnect();
     renderer.setAnimationLoop(null);
+    // Embedder callbacks must not outlive teardown — a disposed viewer has no
+    // context left to lose, and a surviving listener would keep the embedder's
+    // closure (and whatever it captured) alive.
+    renderer.domElement.removeEventListener("webglcontextlost", onContextLostEvent);
+    contextLostListeners.clear();
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
@@ -548,6 +625,8 @@ export function createViewer(container, part) {
     captureCanonicalViews,
     captureCurrent,
     setAutoRotate,
+    setActive,
+    onContextLost,
     setTheme,
     getCameraState,
     setCameraState,