partforge 0.52.0 → 0.54.0

package/src/framework/teardown.js

@@ -0,0 +1,29 @@
+// Shared teardown helpers: run a list of cleanup steps in isolation (one
+// step's throw must never skip the others), and capture/restore a DOM
+// element's attributes across an attach/detach cycle. Lifted out of
+// cutaway-controls.js (the original) so measure-controls.js and
+// selection/hover.js — and anything else that wraps host DOM — share one
+// implementation instead of drifting copies.
+
+export function runCleanupSteps(steps, message) {
+  const errors = [];
+  for (const step of steps) {
+    try { step(); } catch (error) { errors.push(error); }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, message);
+}
+
+export function captureAttributes(element, names) {
+  return new Map(names.map((name) => [name, {
+    present: element.hasAttribute(name),
+    value: element.getAttribute(name),
+  }]));
+}
+
+export function restoreAttributes(element, attributes) {
+  for (const [name, { present, value }] of attributes) {
+    if (present) element.setAttribute(name, value);
+    else element.removeAttribute(name);
+  }
+}

package/src/framework/viewer.js

@@ -39,13 +39,15 @@ export function srgbEncodeInPlace(data) {
 // `renderer.renderOffscreen(pose)` does the GL work (temp camera → offscreen
 // target → readback → JPEG data URL); injected so this is unit-testable without
 // a GL context. The grid is hidden for the whole synchronous pass and restored.
-export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds }) {
+export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, bounds, hidden = [] }) {
   const views = (viewNames?.length ? viewNames : ["iso", "front", "top"])
     .filter((v) => CANONICAL_VIEWS.includes(v))
     .slice(0, CANONICAL_VIEWS.length);
   const before = liveCamera.position.clone();
   const gridWasVisible = grid?.visible;
   if (grid) grid.visible = false;
+  const hiddenWas = hidden.map((o) => o.visible);
+  for (const o of hidden) o.visible = false;
   try {
     return views.map((view) => ({
       view,
@@ -53,10 +55,41 @@ export function captureViewsFromScene(viewNames, { renderer, liveCamera, grid, b
     }));
   } finally {
     if (grid) grid.visible = gridWasVisible;
+    hidden.forEach((o, i) => { o.visible = hiddenWas[i]; });
     liveCamera.position.copy(before); // belt-and-suspenders: never leak camera state
   }
 }
 
+// The off-loop thumbnail capture (renderMeshPayloads, behind the handle's
+// captureView) renders a THROWAWAY scene, so it gets no background from the
+// live scene's theme — and before this constant existed it set none at all,
+// which meant every thumbnail came back on the renderer's default opaque
+// black, in light mode as much as dark. One deliberately theme-INDEPENDENT
+// colour is the right answer rather than either THEME entry below: a thumbnail
+// is baked at capture time and displayed later under host chrome this renderer
+// cannot know (partforge-cloud's card grid draws them on both). Near the
+// perceptual midpoint of THEME.light.bg / THEME.dark.bg, so it commits to
+// neither, and clear of both the part material (0x9fb4cc, lighter) and the
+// feature-edge lines (0x1c232d, much darker).
+//
+// The near-ZERO chroma is the part that looks arbitrary and isn't: the default
+// part material is blue-grey, so a blue-grey background of the same value
+// (0x6b7280 was the first try) competes with it and the shaded side of a part
+// half-disappears into the plate. A neutral grey separates by hue as well as
+// value. Judged on real captures of demo.js and hinged-box.js — if this is
+// ever retuned, retune it the same way and not by eye on the hex.
+export const THUMBNAIL_BG = 0x6e6e73;
+
+// Resolve renderMeshPayloads' `background` option to what Scene.background
+// wants. Exported for its own sake: renderMeshPayloads needs a GL context and
+// so is untestable directly, and this is the whole of the decision. `null` is
+// a real escape hatch — the pre-existing no-background behaviour, clearing to
+// the renderer's clear colour — so it is passed through rather than treated as
+// "unset"; only `undefined` (an absent option) takes the default.
+export function thumbnailBackground(background = THUMBNAIL_BG) {
+  return background === null ? null : new THREE.Color(background);
+}
+
 // Render the LIVE camera's current framing offscreen, once, at a caller-chosen
 // resolution — the showcase capture behind the runtime handle's captureCurrent.
 // Same injected-renderer split as captureViewsFromScene so it runs without a GL
@@ -109,6 +142,10 @@ export function createViewer(container, part) {
   };
   scene.background = new THREE.Color(THEME.dark.bg);
 
+  let currentTheme = "dark";
+  const themeListeners = new Set();
+  function onThemeChange(cb) { themeListeners.add(cb); return () => themeListeners.delete(cb); }
+
   const camera = new THREE.PerspectiveCamera(45, 1, 0.1, 1000);
   camera.position.set(18, 12, 18);
 
@@ -506,6 +543,8 @@ export function createViewer(container, part) {
     for (const m of fadeLineMats.values()) m.color.set(t.line); // clones follow the theme
     cutaway.setTheme(mode, t.line);
     reassertLiveFades(); // setTheme re-clones every section's materials and reassigns them
+    currentTheme = THEME[mode] ? mode : "dark";
+    for (const cb of [...themeListeners]) cb(currentTheme);
   }
 
   function hideAssembly() {
@@ -610,6 +649,15 @@ export function createViewer(container, part) {
     return canvas.toDataURL("image/jpeg", quality);
   }
 
+  // Objects excluded from CANONICAL captures only (agent renders must stay
+  // dimension-free); captureCurrent — the user-framed showcase capture —
+  // deliberately does NOT consult this set.
+  const canonicalCaptureHidden = new Set();
+  function registerCanonicalCaptureHidden(obj) {
+    canonicalCaptureHidden.add(obj);
+    return () => canonicalCaptureHidden.delete(obj);
+  }
+
   // Render the canonical camera angles offscreen, framed to whatever is visible,
   // without disturbing the user's live view. Returns [{ view, dataUrl }].
   function captureCanonicalViews(viewNames) {
@@ -623,6 +671,7 @@ export function createViewer(container, part) {
       renderer: { renderOffscreen },
       liveCamera: camera,
       grid,
+      hidden: [...canonicalCaptureHidden],
       bounds: { center, radius },
     });
   }
@@ -646,12 +695,18 @@ export function createViewer(container, part) {
   // Offscreen render of an arbitrary mesh set (a non-active view), for thumbnails.
   // Assembles a THROWAWAY scene mirroring the live pivot convention, frames it from a
   // canonical angle, renders through the parameterized renderOffscreen, and disposes
-  // everything. Never touches the live scene, camera, subMesh, or subCache. `payloads`
-  // is the worker's [{name, positions, normals, indices, …}] array — placement is
-  // already baked into shared-frame coords, so meshes are NOT recentred.
-  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8 } = {}) {
+  // everything. Never touches the live scene, camera, subMesh, or subCache. The scene
+  // gets THUMBNAIL_BG unless `background` says otherwise (`null` = no background, the
+  // renderer's clear colour). `payloads` is the worker's [{name, positions, normals,
+  // indices, …}] array — placement is already baked into shared-frame coords, so
+  // meshes are NOT recentred.
+  function renderMeshPayloads(payloads, { angle = "iso", size = 640, quality = 0.8, background } = {}) {
     if (disposed) return null; // same guard as captureCurrent/captureCanonicalViews — never touch a torn-down renderer
     const tmpScene = new THREE.Scene();
+    // Deliberately the throwaway scene's own background, never the live one's:
+    // this must not follow the viewer theme (see THUMBNAIL_BG) and must not
+    // reach the live-scene captures, which correctly do follow it.
+    tmpScene.background = thumbnailBackground(background);
     const tmpPivot = new THREE.Group();
     tmpPivot.rotation.x = -Math.PI / 2; // model Z (CAD up) -> vertical, same as live pivot
     tmpScene.add(tmpPivot);
@@ -841,6 +896,8 @@ export function createViewer(container, part) {
     controls.removeEventListener("start", onControlsStart);
     cameraStartListeners.clear();
     frameListeners.clear();
+    themeListeners.clear();
+    canonicalCaptureHidden.clear();
     camTween.cancel();
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
@@ -894,6 +951,8 @@ export function createViewer(container, part) {
     setActive,
     onContextLost,
     setTheme,
+    onThemeChange,
+    getTheme: () => currentTheme,
     getCameraState,
     setCameraState,
     onCameraEnd,
@@ -910,6 +969,7 @@ export function createViewer(container, part) {
     resetCutaway: cutaway.reset,
     isWorldPointVisible: cutaway.isPointVisible,
     registerCutawayMaterial: cutaway.registerClippableMaterial,
+    registerCanonicalCaptureHidden,
     onCutawayHandleHover: cutaway.onHandleHoverChange,
     dispose,
   };

package/types/index.d.ts

@@ -87,6 +87,7 @@ export interface MountElements {
     reframe?: HTMLElement | null;
     theme?: HTMLElement | null;
     cutaway?: HTMLElement | null;
+    measure?: HTMLElement | null;
     railToggle?: HTMLElement | null;
   };
 }
@@ -142,6 +143,19 @@ export interface CaptureViewOptions {
   angle?: CanonicalView | string;
 }
 
+/**
+ * Measurement mode runtime controls. Dimensioned captures come straight from
+ * `captureCurrent()` while the mode is enabled — in-scene dims render into
+ * the frame natively (canonical-view captures and thumbnails never include
+ * them).
+ */
+export interface MeasureRuntime {
+  isEnabled(): boolean;
+  setEnabled(on: boolean): void;
+  clearPins(): void;
+  pinCount(): number;
+}
+
 /** Where playback is: idle, swinging the camera to an intro cue, playing, or paused. */
 export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
 
@@ -253,6 +267,8 @@ export interface PartRuntime {
    * active view has none, where `state().animation` reads `null`.
    */
   animation: AnimationRuntime | null;
+  /** Measurement mode's runtime-controls API — mode on/off, unit, and pin state; dimensioned captures come from `captureCurrent()` while enabled. Always present (a no-op stand-in outside `makeHandle` tests). */
+  measure: MeasureRuntime;
 }
 
 /** Mount a full parametric-part app from a `PartDefinition`. */