partforge 0.53.0 → 0.55.0

package/src/framework/selection/drag-tracker.js

@@ -0,0 +1,39 @@
+// Shared drag-threshold state machine: distinguishes a click from a
+// click-terminated orbit/pan gesture. Multiple pointers are tracked (a second
+// finger joining mid-gesture must not un-arm the drag flag — see
+// selection-pick.test.js's "another pointer joins" case); the drag flag only
+// resets once every pointer has lifted. Lifted out of selection/pick.js so
+// measure-mode.js shares one implementation and one threshold instead of a
+// second, divergent copy.
+export function createDragTracker({ thresholdSquared = 16 } = {}) {
+  const pointerStarts = new Map();
+  let dragged = false;
+
+  return {
+    onDown(ev) {
+      if (pointerStarts.size === 0) dragged = false;
+      pointerStarts.set(ev.pointerId, { x: ev.clientX, y: ev.clientY });
+    },
+    onMove(ev) {
+      const start = pointerStarts.get(ev.pointerId);
+      if (!start || dragged) return;
+      const dx = ev.clientX - start.x, dy = ev.clientY - start.y;
+      dragged = dx * dx + dy * dy > thresholdSquared;
+    },
+    onUp(ev) {
+      pointerStarts.delete(ev.pointerId);
+    },
+    onCancel(ev) {
+      pointerStarts.delete(ev.pointerId);
+      if (pointerStarts.size === 0) dragged = false;
+    },
+    // Reads and resets drag state for a click: call at the top of the click
+    // handler, before deciding whether to act on it.
+    consumeClick() {
+      const wasDragged = dragged;
+      pointerStarts.clear();
+      dragged = false;
+      return wasDragged;
+    },
+  };
+}

package/src/framework/selection/feature-highlight.js

@@ -0,0 +1,99 @@
+// Shared surface-highlight helper: an overlay mesh tinting one feature's
+// triangle subset (or a whole sub-part). Extracted from hover.js so the hover
+// tooltip and measurement mode share one implementation and one subset cache.
+import * as THREE from "three";
+import { CUTAWAY_OVERLAY_RENDER_ORDER } from "../cutaway-render.js";
+import { runCleanupSteps } from "../teardown.js";
+
+const HIGHLIGHT = 0x4da3ff;
+
+// Extract the subset of a geometry belonging to one feature id. Handles both
+// non-indexed (Manifold) and indexed (OCCT) payloads.
+function featureSubset(geometry, featureId) {
+  const { featureIds } = geometry.userData;
+  const pos = geometry.getAttribute("position");
+  const index = geometry.getIndex();
+  const vertAt = index ? (t, v) => index.getX(t * 3 + v) : (t, v) => t * 3 + v;
+  let count = 0;
+  for (let t = 0; t < featureIds.length; t++) if (featureIds[t] === featureId) count++;
+  const out = new Float32Array(count * 9);
+  let o = 0;
+  for (let t = 0; t < featureIds.length; t++) {
+    if (featureIds[t] !== featureId) continue;
+    for (let v = 0; v < 3; v++) {
+      const i = vertAt(t, v);
+      out[o++] = pos.getX(i); out[o++] = pos.getY(i); out[o++] = pos.getZ(i);
+    }
+  }
+  const g = new THREE.BufferGeometry();
+  g.setAttribute("position", new THREE.BufferAttribute(out, 3));
+  return g;
+}
+
+export function createFeatureHighlight(viewer) {
+  const material = new THREE.MeshBasicMaterial({
+    color: HIGHLIGHT, transparent: true, opacity: 0.35,
+    polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2,
+  });
+  const unregisterCutaway = viewer.registerCutawayMaterial?.(material) ?? (() => {});
+  let emptyOverlayGeometry = new THREE.BufferGeometry();
+  const overlay = new THREE.Mesh(emptyOverlayGeometry, material);
+  overlay.visible = false;
+  overlay.renderOrder = CUTAWAY_OVERLAY_RENDER_ORDER;
+  let overlayParent = null;
+  // Subset cache per sub-part: rebuilt when the sub-part's geometry object
+  // changes (i.e. after a regenerate) — keyed on the geometry instance.
+  const subsets = new Map(); // subPart -> { geo, byId: Map(featureId -> BufferGeometry) }
+
+  function mount(geometry, mesh) {
+    emptyOverlayGeometry?.dispose();
+    emptyOverlayGeometry = null;
+    overlay.geometry = geometry;
+    // Parent to the sub-part mesh, not the scene: the overlay geometry is a
+    // subset of the mesh's own (delivered-frame) vertices, so it must inherit
+    // whatever fast-path pose viewer.setSubPose has written onto that mesh.
+    if (overlayParent !== mesh) {
+      mesh.add(overlay);
+      overlayParent = mesh;
+    }
+    overlay.visible = true;
+  }
+
+  return {
+    show(hit) {
+      if (!hit.feature) { mount(hit.mesh.geometry, hit.mesh); return; }
+      const cached = subsets.get(hit.subPart);
+      let byId = cached?.geo === hit.mesh.geometry ? cached.byId : null;
+      if (!byId) {
+        for (const g of cached?.byId.values() ?? []) g.dispose();
+        byId = new Map();
+        subsets.set(hit.subPart, { geo: hit.mesh.geometry, byId });
+      }
+      let g = byId.get(hit.feature.id);
+      if (!g) { g = featureSubset(hit.mesh.geometry, hit.feature.id); byId.set(hit.feature.id, g); }
+      mount(g, hit.mesh);
+    },
+    clear() { overlay.visible = false; },
+    dispose() {
+      // Every step isolated: a throw disposing one cached subset (or
+      // unregistering from cutaway) must not skip the rest — same discipline
+      // as hover.js's own cleanup list, which this dispose() call is itself
+      // one step of (test/selection-hover.test.js's aggregated-failure case
+      // exercises both layers together).
+      const steps = [
+        () => { overlay.visible = false; },
+        () => { overlayParent?.remove(overlay); },
+      ];
+      for (const { byId } of subsets.values()) {
+        for (const g of byId.values()) steps.push(() => g.dispose());
+      }
+      steps.push(
+        () => subsets.clear(),
+        () => emptyOverlayGeometry?.dispose(),
+        unregisterCutaway,
+        () => material.dispose(),
+      );
+      runCleanupSteps(steps, "feature highlight cleanup failed");
+    },
+  };
+}

package/src/framework/selection/hover.js

@@ -2,42 +2,10 @@
 // sub-part under the pointer, and an overlay mesh highlighting the feature's
 // surface. Feature names come from Solid.label() in the part's build, carried
 // per-triangle in the mesh payload (geometry.userData.featureIds/features).
-import * as THREE from "three";
-import { CUTAWAY_OVERLAY_RENDER_ORDER } from "../cutaway-render.js";
 import { createTooltipPresenter } from "../tooltip.js";
 import { raycastViewer } from "./raycast.js";
-
-const HIGHLIGHT = 0x4da3ff;
-
-function runCleanupSteps(steps) {
-  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, "feature hover cleanup failed");
-  }
-}
-
-// Extract the subset of a non-indexed geometry belonging to one feature id.
-function featureSubset(geometry, featureId) {
-  const { featureIds } = geometry.userData;
-  const pos = geometry.getAttribute("position");
-  let count = 0;
-  for (let t = 0; t < featureIds.length; t++) if (featureIds[t] === featureId) count++;
-  const out = new Float32Array(count * 9);
-  let o = 0;
-  for (let t = 0; t < featureIds.length; t++) {
-    if (featureIds[t] !== featureId) continue;
-    for (let v = 0; v < 3; v++) {
-      out[o++] = pos.getX(t * 3 + v); out[o++] = pos.getY(t * 3 + v); out[o++] = pos.getZ(t * 3 + v);
-    }
-  }
-  const g = new THREE.BufferGeometry();
-  g.setAttribute("position", new THREE.BufferAttribute(out, 3));
-  return g;
-}
+import { createFeatureHighlight } from "./feature-highlight.js";
+import { runCleanupSteps } from "../teardown.js";
 
 export function attachHoverLabels(
   viewer,
@@ -51,67 +19,27 @@ export function attachHoverLabels(
   let presentationToken;
   let hasPresented = false;
 
-  const material = new THREE.MeshBasicMaterial({
-    color: HIGHLIGHT, transparent: true, opacity: 0.35,
-    polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2,
-  });
-  const unregisterCutaway = viewer.registerCutawayMaterial?.(material) ?? (() => {});
-  let emptyOverlayGeometry = new THREE.BufferGeometry();
-  const overlay = new THREE.Mesh(emptyOverlayGeometry, material);
-  overlay.visible = false;
-  overlay.renderOrder = CUTAWAY_OVERLAY_RENDER_ORDER;
-  let overlayParent = null;
-  // Subset cache per sub-part: rebuilt when the sub-part's geometry object changes
-  // (i.e. after a regenerate) — keyed on the geometry instance.
-  const subsets = new Map(); // subPart -> { geo, byId: Map(featureId -> BufferGeometry) }
+  const highlight = createFeatureHighlight(viewer);
 
   const subLabel = (name) => part.parts[name]?.label ?? name;
 
-  function clearHighlight() {
-    overlay.visible = false;
-  }
-
-  function showHighlight(hit, geometry) {
-    emptyOverlayGeometry?.dispose();
-    emptyOverlayGeometry = null;
-    overlay.geometry = geometry;
-    // Parent to the sub-part mesh, not to the group: the overlay geometry is a
-    // subset of the mesh's own (delivered-frame) vertices, so it must inherit
-    // whatever fast-path pose viewer.setSubPose has written onto that mesh.
-    if (overlayParent !== hit.mesh) {
-      hit.mesh.add(overlay);
-      overlayParent = hit.mesh;
-    }
-    overlay.visible = true;
-  }
-
   function hide() {
     if (hasPresented) {
       hasPresented = false;
       tooltipPresenter.hide(presentationToken);
       presentationToken = undefined;
     }
-    clearHighlight();
+    highlight.clear();
   }
 
   function show(hit, x, y) {
     let content;
     if (hit.feature) {
       content = { title: hit.feature.label, subtitle: subLabel(hit.subPart) };
-      const cached = subsets.get(hit.subPart);
-      let byId = cached?.geo === hit.mesh.geometry ? cached.byId : null;
-      if (!byId) {
-        for (const g of cached?.byId.values() ?? []) g.dispose();
-        byId = new Map();
-        subsets.set(hit.subPart, { geo: hit.mesh.geometry, byId });
-      }
-      let g = byId.get(hit.feature.id);
-      if (!g) { g = featureSubset(hit.mesh.geometry, hit.feature.id); byId.set(hit.feature.id, g); }
-      showHighlight(hit, g);
     } else {
       content = { title: subLabel(hit.subPart), subtitle: "" };
-      showHighlight(hit, hit.mesh.geometry);
     }
+    highlight.show(hit);
     if (hasPresented) {
       hasPresented = false;
       tooltipPresenter.hide(presentationToken);
@@ -127,6 +55,7 @@ export function attachHoverLabels(
   let down = false;
   let detached = false;
   let suppressed = false;
+  let externallySuppressed = false;
 
   function invalidatePendingWork() {
     pending = null;
@@ -144,7 +73,7 @@ export function attachHoverLabels(
   function onMove(ev) {
     if (detached) return;
     if (ev.pointerType === "touch") return;
-    if (down || suppressed) return;
+    if (down || suppressed || externallySuppressed) return;
     pending = { x: ev.clientX, y: ev.clientY };
     if (frameScheduled) return;
     frameScheduled = true;
@@ -154,7 +83,7 @@ export function attachHoverLabels(
       frameScheduled = false;
       const p = pending;
       pending = null;
-      if (detached || !p || down || suppressed) return;
+      if (detached || !p || down || suppressed || externallySuppressed) return;
       const hit = raycastViewer(viewer, p.x, p.y);
       if (hit) show(hit, p.x, p.y); else hide();
     });
@@ -169,14 +98,14 @@ export function attachHoverLabels(
   viewer.domElement.addEventListener("pointerleave", onLeave);
 
   return {
+    setSuppressed(on) {
+      externallySuppressed = !!on;
+      if (externallySuppressed) { invalidatePendingWork(); hide(); }
+    },
     detach: () => {
       if (detached) return;
       detached = true;
       invalidatePendingWork();
-      const subsetGeometries = [...subsets.values()]
-        .flatMap(({ byId }) => [...byId.values()]);
-      const initialGeometry = emptyOverlayGeometry;
-      emptyOverlayGeometry = null;
       runCleanupSteps([
         unsubscribeHandleHover,
         () => viewer.domElement.removeEventListener("pointermove", onMove),
@@ -184,14 +113,9 @@ export function attachHoverLabels(
         () => viewer.domElement.removeEventListener("pointerup", onUp),
         () => viewer.domElement.removeEventListener("pointerleave", onLeave),
         hide,
-        () => overlayParent?.remove(overlay),
-        ...subsetGeometries.map((geometry) => () => geometry.dispose()),
-        () => subsets.clear(),
-        () => initialGeometry?.dispose(),
-        unregisterCutaway,
-        () => material.dispose(),
+        () => highlight.dispose(),
         () => { if (ownsTooltip) tooltipPresenter.dispose(); },
-      ]);
+      ], "feature hover cleanup failed");
     },
   };
 }

package/src/framework/selection/index.js

@@ -6,3 +6,4 @@ export { attachPicker, worldToSubPartLocal } from "./pick.js";
 export { attachPickToggle } from "./pick-toggle.js";
 export { raycastViewer, featureAt } from "./raycast.js";
 export { attachHoverLabels } from "./hover.js";
+export { createFeatureHighlight } from "./feature-highlight.js";

package/src/framework/selection/pick.js

@@ -2,42 +2,16 @@
 // selection raycast, and hands a resolved Selection to onPick.
 import { raycastViewer, worldToSubPartLocal } from "./raycast.js";
 import { resolveSelection } from "./resolve.js";
+import { createDragTracker } from "./drag-tracker.js";
 
 export { worldToSubPartLocal };
 
-const DRAG_THRESHOLD_SQUARED = 4 ** 2;
-
 export function attachPicker(viewer, { part, getContext, onPick }) {
   let active = false;
-  const pointerStarts = new Map();
-  let dragged = false;
-
-  function onPointerDown(ev) {
-    if (pointerStarts.size === 0) dragged = false;
-    pointerStarts.set(ev.pointerId, { x: ev.clientX, y: ev.clientY });
-  }
-
-  function onPointerMove(ev) {
-    const pointerStart = pointerStarts.get(ev.pointerId);
-    if (!pointerStart || dragged) return;
-    const dx = ev.clientX - pointerStart.x;
-    const dy = ev.clientY - pointerStart.y;
-    dragged = dx * dx + dy * dy > DRAG_THRESHOLD_SQUARED;
-  }
-
-  function onPointerUp(ev) {
-    pointerStarts.delete(ev.pointerId);
-  }
-
-  function onPointerCancel(ev) {
-    pointerStarts.delete(ev.pointerId);
-    if (pointerStarts.size === 0) dragged = false;
-  }
+  const drag = createDragTracker();
 
   function onClick(ev) {
-    const wasDragged = dragged;
-    pointerStarts.clear();
-    dragged = false;
+    const wasDragged = drag.consumeClick();
     if (!active || wasDragged) return;
     const hit = raycastViewer(viewer, ev.clientX, ev.clientY);
     if (!hit) return;
@@ -46,18 +20,18 @@ export function attachPicker(viewer, { part, getContext, onPick }) {
     onPick(selection);
   }
 
-  viewer.domElement.addEventListener("pointerdown", onPointerDown);
-  viewer.domElement.addEventListener("pointermove", onPointerMove);
-  viewer.domElement.addEventListener("pointerup", onPointerUp);
-  viewer.domElement.addEventListener("pointercancel", onPointerCancel);
+  viewer.domElement.addEventListener("pointerdown", drag.onDown);
+  viewer.domElement.addEventListener("pointermove", drag.onMove);
+  viewer.domElement.addEventListener("pointerup", drag.onUp);
+  viewer.domElement.addEventListener("pointercancel", drag.onCancel);
   viewer.domElement.addEventListener("click", onClick);
   return {
     setActive: (on) => { active = !!on; },
     detach: () => {
-      viewer.domElement.removeEventListener("pointerdown", onPointerDown);
-      viewer.domElement.removeEventListener("pointermove", onPointerMove);
-      viewer.domElement.removeEventListener("pointerup", onPointerUp);
-      viewer.domElement.removeEventListener("pointercancel", onPointerCancel);
+      viewer.domElement.removeEventListener("pointerdown", drag.onDown);
+      viewer.domElement.removeEventListener("pointermove", drag.onMove);
+      viewer.domElement.removeEventListener("pointerup", drag.onUp);
+      viewer.domElement.removeEventListener("pointercancel", drag.onCancel);
       viewer.domElement.removeEventListener("click", onClick);
     },
   };

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,6 +55,7 @@ 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
   }
 }
@@ -139,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);
 
@@ -536,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() {
@@ -640,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) {
@@ -653,6 +671,7 @@ export function createViewer(container, part) {
       renderer: { renderOffscreen },
       liveCamera: camera,
       grid,
+      hidden: [...canonicalCaptureHidden],
       bounds: { center, radius },
     });
   }
@@ -877,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);
@@ -930,6 +951,8 @@ export function createViewer(container, part) {
     setActive,
     onContextLost,
     setTheme,
+    onThemeChange,
+    getTheme: () => currentTheme,
     getCameraState,
     setCameraState,
     onCameraEnd,
@@ -946,6 +969,7 @@ export function createViewer(container, part) {
     resetCutaway: cutaway.reset,
     isWorldPointVisible: cutaway.isPointVisible,
     registerCutawayMaterial: cutaway.registerClippableMaterial,
+    registerCanonicalCaptureHidden,
     onCutawayHandleHover: cutaway.onHandleHoverChange,
     dispose,
   };

package/src/testing.js

@@ -23,3 +23,8 @@ export { renderViews, RENDER_VIEWS } from "./testing/render.js";
 export { verify } from "./framework/oracle/verify.js";
 export { buildBVH } from "./framework/oracle/bvh.js";
 export { minWall } from "./framework/oracle/min-wall.js";
+// Silhouette match scoring — also worker-reachable (the `inspect` job scores
+// `matchTargets` with exactly these), re-exported so a downstream harness can build
+// the same masks and reproduce a score outside the job loop.
+export { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./framework/oracle/silhouette.js";
+export { matchMasks, matchViews } from "./framework/oracle/match.js";

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`. */