partforge 0.53.0 → 0.54.0

package/src/framework/measure/param-link.js

@@ -0,0 +1,32 @@
+// PURE heuristic linking a measured dimension to the schema param driving it.
+// Candidates come from the sub-part's read keys (param-deps.subPartReadKeys,
+// resolved by the caller); a candidate links when its current value matches a
+// measured value within the display quantum (0.01), or at value*2 for
+// radius-style params against measured diameters. Unique match or nothing —
+// never guess between two.
+const QUANTUM = 0.005; // half the 0.01 display quantum: |a-b| < 0.005 rounds equal
+
+// Every candidate whose current value matches a measured value (or matches
+// diameter at value*2, the radius-style rule) — the set a measurement click
+// flashes. linkParam keeps the stricter unique-or-nothing rule for focus.
+export function paramMatches(keys, params, values) {
+  const measured = Object.entries(values)
+    .filter(([k, v]) => typeof v === "number" && k !== "partial")
+    .map(([, v]) => v);
+  const hasDiameter = "diameter" in values;
+  const matches = new Set();
+  for (const key of keys) {
+    const pv = params[key];
+    if (typeof pv !== "number") continue;
+    for (const mv of measured) {
+      if (Math.abs(pv - mv) < QUANTUM) { matches.add(key); break; }
+      if (hasDiameter && Math.abs(pv * 2 - values.diameter) < QUANTUM) { matches.add(key); break; }
+    }
+  }
+  return [...matches];
+}
+
+export function linkParam(keys, params, values) {
+  const matches = paramMatches(keys, params, values);
+  return matches.length === 1 ? matches[0] : null;
+}

package/src/framework/measure/pins.js

@@ -0,0 +1,36 @@
+// PURE pin store for measurement mode. Pins are PER-VIEW and keyed on stable
+// identity — (subPart, featureLabel|null, occurrence) — not on geometry, so a
+// regenerate re-resolves them by label (dormant when the label is gone, revived
+// when it returns). `occurrence` disambiguates duplicate labels: it counts
+// same-label features earlier in the features table.
+const keyString = ({ subPart, featureLabel, occurrence }) =>
+  `${subPart}\n${featureLabel}\n${occurrence}`;
+
+export function occurrenceOf(features, featureId) {
+  const label = features[featureId - 1];
+  let n = 0;
+  for (let i = 0; i < featureId - 1; i++) if (features[i] === label) n++;
+  return n;
+}
+
+export function createPinStore() {
+  const byView = new Map(); // view -> Map(keyString -> key)
+  const viewMap = (view) => {
+    let m = byView.get(view);
+    if (!m) { m = new Map(); byView.set(view, m); }
+    return m;
+  };
+  return {
+    // -> true when the pin was added, false when it was removed
+    toggle(view, key) {
+      const m = viewMap(view), ks = keyString(key);
+      if (m.has(ks)) { m.delete(ks); return false; }
+      m.set(ks, { ...key, occurrence: key.occurrence ?? 0 });
+      return true;
+    },
+    has: (view, key) => viewMap(view).has(keyString(key)),
+    list: (view) => [...viewMap(view).values()],
+    clear: (view) => { viewMap(view).clear(); },
+    count: (view) => viewMap(view).size,
+  };
+}

package/src/framework/mount.js

@@ -26,14 +26,19 @@ import { createExportController, backendForFormat } from "./export-controller.js
 import { createCaptureBuild } from "./capture-build.js";
 import { attachAnimationControls } from "./animation-controls.js";
 import { resolveDefaultView } from "./default-view.js";
+import { createMeasureMode } from "./measure/measure-mode.js";
+import { attachMeasureControls } from "./measure/measure-controls.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
 // The default no-op tooltip binding, so a host can hold on to whatever
 // attachTooltips returned without caring whether this mount resolved one.
 const NOOP_TOOLTIP_BINDING = { sync: () => {}, hide: () => {}, detach: () => {} };
+// Same no-op-default stance as attachTooltips/setHostPane below, for a
+// makeHandle caller (or a direct test) that doesn't wire measure mode.
+const NOOP_MEASURE = { isEnabled: () => false, setEnabled: () => {}, clearPins: () => {}, pinCount: () => 0 };
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -70,6 +75,11 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // title/aria-label); returns { sync, hide, detach }. Same no-op default
     // stance as setHostPane above.
     attachTooltips: attachTooltips ?? (() => NOOP_TOOLTIP_BINDING),
+    // Measurement-mode API (spec Goal 3): { isEnabled, setEnabled, clearPins,
+    // pinCount } — an embedder drives the mode without the built-in ruler
+    // button. Dimensions render in the scene, so a dimensioned capture is just
+    // captureCurrent() taken while the mode is on.
+    measure: measure ?? NOOP_MEASURE,
   };
 }
 
@@ -206,6 +216,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       reframe: elements.chrome?.reframe ?? byId("reframe"),
       theme: elements.chrome?.theme ?? byId("theme"),
       cutaway: elements.chrome?.cutaway ?? byId("cutaway"),
+      measure: elements.chrome?.measure ?? byId("measure"),
       railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
     },
   };
@@ -216,10 +227,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     cleanup.defer(() => viewer.dispose());
     const tooltip = createTooltipPresenter({ id: null });
     cleanup.defer(() => tooltip.dispose());
-    const cutawayChrome = attachCutawayControls(viewer, {
-      cutaway: els.chrome.cutaway,
-    }, { tooltip });
-    cleanup.defer(() => cutawayChrome.detach());
+    // cutawayChrome + measureMode/measureChrome are attached further down (just
+    // after `params` exists — measure's getContext needs both `view()` and
+    // `params`, and cutaway needs measureMode for its escapeGuard). Nothing
+    // between here and there depends on cutawayChrome except the view-tabs
+    // onChange closure below, which only runs on a later user/programmatic tab
+    // change, never during this synchronous setup.
     // Resizable/collapsible controls rail. No-ops when the host lays out the
     // framework itself (no #panel / no elements.rail).
     const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell, tooltip });
@@ -283,6 +296,39 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     onViewChange?.(tabsCtl.current());
     const params = { ...part.defaults };
 
+    // Measurement mode: in-scene dims + pins + dimension->controls reveal
+    // (clicking a measurement flashes every control that can drive it). The
+    // panel is built later in this function, so revealParams is a late-bound
+    // thunk — same idiom for getParamsVersion, which needs `loop` (created
+    // further below); readsFor's memo keys on it instead of hashing the whole
+    // params object per call, mirroring createMeshCache/createPoseFastPath.
+    let panelRef = null;
+    const measureMode = createMeasureMode(viewer, {
+      part,
+      getContext: () => ({ view: view(), params }),
+      revealParams: (keys, focusKey) => panelRef?.revealParams(keys, focusKey),
+      getParamsVersion: () => loop.version(),
+    });
+    cleanup.defer(() => measureMode.detach());
+    // escapeScope: cutaway's Flip/Reset buttons are canvas SIBLINGS inside
+    // #viewbar, not descendants of the canvas — attaching Escape to
+    // viewer.domElement alone would leave a guarded Escape from those buttons
+    // dead. els.viewer (the stage) is a shared ancestor of both, so Escape
+    // bubbles up from either.
+    const measureChrome = attachMeasureControls(viewer, measureMode, {
+      measure: els.chrome.measure,
+    }, { tooltip, escapeScope: els.viewer });
+    cleanup.defer(() => measureChrome.detach());
+    const cutawayChrome = attachCutawayControls(viewer, {
+      cutaway: els.chrome.cutaway,
+    }, { tooltip, escapeGuard: () => measureMode.isEnabled() });
+    cleanup.defer(() => cutawayChrome.detach());
+    // Suppress the always-on hover tooltip while measure mode is active — its
+    // own feature highlight + dims take over the pointer.
+    const offMeasureHover = measureMode.onModeChange(() =>
+      hover.setSuppressed(measureMode.isEnabled()));
+    cleanup.defer(offMeasureHover);
+
     // Current selection context for the pickers: the active view + live params +
     // derived values. Shared by every pick mode below.
     const getContext = () => {
@@ -530,6 +576,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined);
     cleanup.defer(() => panel.dispose());
+    panelRef = panel;
     const updateRelevance = () => {
       // A throwing derive() must not break every slider drag — mount's pick
       // flow already guards its own resolveDerived call the same way
@@ -681,6 +728,12 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),
       animation: animCtl?.runtime ?? null,
+      measure: {
+        isEnabled: measureMode.isEnabled,
+        setEnabled: measureMode.setEnabled,
+        clearPins: measureMode.clearPins,
+        pinCount: measureMode.pinCount,
+      },
     });
   } catch (error) {
     try {

package/src/framework/panel/render.js

@@ -37,6 +37,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
   const nodeById = new Map();     // id -> node, for the reveal re-sync
   const lastVisible = new Map();  // id -> previous `visible`, to detect a reveal
   const lastDisabled = new Map(); // id -> previous `disabled`, to skip a no-op input pass
+  const keyToId = new Map();      // param key -> node id, for revealParam
   // Containers that own a disclosure: sections, and titled inner groups (the
   // legacy "Advanced" fold). Both share the same anatomy — a header row with
   // the aria-carrying button and a text-free chevron span — so `el` (the
@@ -226,6 +227,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
       info,
     });
     nodeEls.set(node.id, widget.el);
+    if (node.key && !keyToId.has(node.key)) keyToId.set(node.key, node.id);
     widgetSyncs.set(node.id, widget.sync);
     container.append(widget.el);
 
@@ -310,6 +312,45 @@ export function buildControls(root, parameters, params, onDirty, onCommit) {
       for (const { key, sync } of syncFns) if (!only || only.has(key)) sync();
       applyState();
     },
+    // Measurement mode's dimension->control link: open whatever encloses the
+    // control, bring it on screen, hand it keyboard focus, and pulse the flash
+    // so the eye lands on it. DOM-containment (not tree walking) finds the
+    // enclosing disclosures, so section vs fold nesting needs no special case.
+    revealParam(key) {
+      return this.revealParams([key], key);
+    },
+    // Multi-control reveal: a measurement is usually a FUNCTION of several
+    // params, so clicking one flashes every control that can drive it.
+    // `focusKey` (when given and present) is the one whose value exactly
+    // matches the clicked dimension — it gets keyboard focus; otherwise the
+    // first flashed control is only scrolled to, no focus steal.
+    revealParams(keys, focusKey = null) {
+      const targets = [];
+      for (const key of keys) {
+        const id = keyToId.get(key);
+        const el = id && nodeEls.get(id);
+        if (el) targets.push([key, el]);
+      }
+      if (!targets.length) return false;
+      for (const [, target] of targets) {
+        for (const [, d] of disclosures) {
+          if (!d.body.contains(target) || !d.body.classList.contains("hidden")) continue;
+          d.body.classList.remove("hidden");
+          d.button.setAttribute("aria-expanded", "true");
+          d.el.classList.remove("collapsed");
+        }
+        target.classList.remove("pf-param-flash");
+        void target.offsetWidth; // restart the animation on repeat reveals
+        target.classList.add("pf-param-flash");
+        target.addEventListener("animationend", () => target.classList.remove("pf-param-flash"), { once: true });
+      }
+      const [primaryKey, primary] = targets.find(([k]) => k === focusKey) ?? targets[0];
+      primary.scrollIntoView?.({ block: "center" });
+      if (primaryKey === focusKey) {
+        primary.querySelector("input, select, textarea, .seg button")?.focus({ preventScroll: true });
+      }
+      return true;
+    },
     dispose: () => { info.dispose(); root.replaceChildren(); },
   };
 }

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);
+  }
+}