partforge 0.19.0 → 0.20.0

package/src/framework/selection/hover.js

@@ -3,10 +3,23 @@
 // 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;
@@ -26,25 +39,27 @@ function featureSubset(geometry, featureId) {
   return g;
 }
 
-export function attachHoverLabels(viewer, { part, schedule = (cb) => requestAnimationFrame(cb) }) {
+export function attachHoverLabels(
+  viewer,
+  { part, schedule = (cb) => requestAnimationFrame(cb), tooltip } = {},
+) {
   // Hover is a mouse idiom — skip entirely on touch-only devices.
   if (globalThis.matchMedia && !matchMedia("(hover: hover)").matches) return { detach: () => {} };
 
-  const tip = document.createElement("div");
-  tip.id = "pf-hover-tip";
-  const feat = document.createElement("b");
-  const sub = document.createElement("span");
-  sub.className = "pf-hover-sub";
-  tip.append(feat, sub);
-  document.body.appendChild(tip);
+  const ownsTooltip = !tooltip;
+  const tooltipPresenter = tooltip ?? createTooltipPresenter();
+  let presentationToken;
+  let hasPresented = false;
 
   const material = new THREE.MeshBasicMaterial({
     color: HIGHLIGHT, transparent: true, opacity: 0.35,
     polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2,
   });
-  const overlay = new THREE.Mesh(new THREE.BufferGeometry(), material);
+  const unregisterCutaway = viewer.registerCutawayMaterial?.(material) ?? (() => {});
+  let emptyOverlayGeometry = new THREE.BufferGeometry();
+  const overlay = new THREE.Mesh(emptyOverlayGeometry, material);
   overlay.visible = false;
-  overlay.renderOrder = 2;
+  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.
@@ -56,15 +71,30 @@ export function attachHoverLabels(viewer, { part, schedule = (cb) => requestAnim
     overlay.visible = false;
   }
 
+  function showHighlight(hit, geometry) {
+    emptyOverlayGeometry?.dispose();
+    emptyOverlayGeometry = null;
+    overlay.geometry = geometry;
+    if (overlayParent !== hit.mesh.parent) {
+      hit.mesh.parent.add(overlay);
+      overlayParent = hit.mesh.parent;
+    }
+    overlay.visible = true;
+  }
+
   function hide() {
-    tip.classList.remove("show");
+    if (hasPresented) {
+      hasPresented = false;
+      tooltipPresenter.hide(presentationToken);
+      presentationToken = undefined;
+    }
     clearHighlight();
   }
 
   function show(hit, x, y) {
+    let content;
     if (hit.feature) {
-      feat.textContent = hit.feature.label;
-      sub.textContent = subLabel(hit.subPart);
+      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) {
@@ -74,39 +104,61 @@ export function attachHoverLabels(viewer, { part, schedule = (cb) => requestAnim
       }
       let g = byId.get(hit.feature.id);
       if (!g) { g = featureSubset(hit.mesh.geometry, hit.feature.id); byId.set(hit.feature.id, g); }
-      overlay.geometry = g;
-      if (overlayParent !== hit.mesh.parent) { hit.mesh.parent.add(overlay); overlayParent = hit.mesh.parent; }
-      overlay.visible = true;
+      showHighlight(hit, g);
     } else {
-      feat.textContent = subLabel(hit.subPart);
-      sub.textContent = "";
-      clearHighlight();
+      content = { title: subLabel(hit.subPart), subtitle: "" };
+      showHighlight(hit, hit.mesh.geometry);
+    }
+    if (hasPresented) {
+      hasPresented = false;
+      tooltipPresenter.hide(presentationToken);
+      presentationToken = undefined;
     }
-    tip.style.left = `${x + 14}px`;
-    tip.style.top = `${y + 14}px`;
-    tip.classList.add("show");
+    presentationToken = tooltipPresenter.showPointer(content, x, y);
+    hasPresented = true;
   }
 
   let pending = null; // latest pointer position; one raycast per scheduled frame
+  let frameScheduled = false;
+  let workVersion = 0;
   let down = false;
+  let detached = false;
+  let suppressed = false;
+
+  function invalidatePendingWork() {
+    pending = null;
+    frameScheduled = false;
+    workVersion += 1;
+  }
+
+  const unsubscribeHandleHover = viewer.onCutawayHandleHover?.((handle) => {
+    suppressed = handle != null;
+    if (!suppressed) return;
+    invalidatePendingWork();
+    hide();
+  }) ?? (() => {});
 
   function onMove(ev) {
+    if (detached) return;
     if (ev.pointerType === "touch") return;
-    if (down) return;
-    const had = pending;
+    if (down || suppressed) return;
     pending = { x: ev.clientX, y: ev.clientY };
-    if (had) return; // a frame is already scheduled
+    if (frameScheduled) return;
+    frameScheduled = true;
+    const scheduledVersion = workVersion;
     schedule(() => {
+      if (scheduledVersion !== workVersion) return;
+      frameScheduled = false;
       const p = pending;
       pending = null;
-      if (!p || down) return;
+      if (detached || !p || down || suppressed) return;
       const hit = raycastViewer(viewer, p.x, p.y);
       if (hit) show(hit, p.x, p.y); else hide();
     });
   }
-  const onDown = () => { down = true; hide(); };
+  const onDown = () => { down = true; invalidatePendingWork(); hide(); };
   const onUp = () => { down = false; };
-  const onLeave = () => hide();
+  const onLeave = () => { invalidatePendingWork(); hide(); };
 
   viewer.domElement.addEventListener("pointermove", onMove);
   viewer.domElement.addEventListener("pointerdown", onDown);
@@ -115,14 +167,28 @@ export function attachHoverLabels(viewer, { part, schedule = (cb) => requestAnim
 
   return {
     detach: () => {
-      viewer.domElement.removeEventListener("pointermove", onMove);
-      viewer.domElement.removeEventListener("pointerdown", onDown);
-      viewer.domElement.removeEventListener("pointerup", onUp);
-      viewer.domElement.removeEventListener("pointerleave", onLeave);
-      tip.remove();
-      overlayParent?.remove(overlay);
-      for (const { byId } of subsets.values()) for (const g of byId.values()) g.dispose();
-      material.dispose();
+      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),
+        () => viewer.domElement.removeEventListener("pointerdown", onDown),
+        () => 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(),
+        () => { if (ownsTooltip) tooltipPresenter.dispose(); },
+      ]);
     },
   };
 }

package/src/framework/selection/raycast.js

@@ -27,7 +27,10 @@ export function raycastViewer(viewer, clientX, clientY) {
   ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
   raycaster.setFromCamera(ndc, viewer.camera);
   const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
-  const hit = raycaster.intersectObjects(meshes, false)[0];
+  const hits = raycaster.intersectObjects(meshes, false);
+  const hit = hits.find((candidate) =>
+    viewer.isWorldPointVisible?.(candidate.point) ?? true
+  );
   if (!hit) return null;
   return {
     mesh: hit.object,

package/src/framework/tooltip.js

@@ -0,0 +1,282 @@
+const VIEWPORT_MARGIN = 8;
+const ANCHOR_GAP = 8;
+
+function throwCollected(errors, message) {
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, message);
+}
+
+export function createTooltipPresenter({ id = "pf-hover-tip" } = {}) {
+  const element = document.createElement("div");
+  if (id != null && id !== "") element.id = id;
+  element.className = "pf-hover-tip";
+
+  const title = document.createElement("b");
+  const subtitle = document.createElement("span");
+  subtitle.className = "pf-hover-sub";
+  element.append(title, subtitle);
+  document.body.appendChild(element);
+  let disposed = false;
+  const claims = [];
+
+  function setContent(content) {
+    title.textContent = content.title;
+    subtitle.textContent = content.subtitle ?? "";
+  }
+
+  function measureVisible(content, anchored) {
+    setContent(content);
+    element.style.left = `${VIEWPORT_MARGIN}px`;
+    element.style.top = `${VIEWPORT_MARGIN}px`;
+    element.classList.toggle("pf-tooltip-anchored", anchored);
+    element.classList.add("show");
+    const rect = element.getBoundingClientRect();
+    return {
+      width: Math.max(0, rect.width || 0),
+      height: Math.max(0, rect.height || 0),
+    };
+  }
+
+  function renderClaim(claim) {
+    const viewportWidth = Math.max(0, globalThis.innerWidth || 0);
+    const viewportHeight = Math.max(0, globalThis.innerHeight || 0);
+    const { width, height } = measureVisible(claim.content, claim.kind === "anchor");
+    const maxLeft = Math.max(
+      VIEWPORT_MARGIN,
+      viewportWidth - VIEWPORT_MARGIN - width,
+    );
+
+    if (claim.kind === "pointer") {
+      const maxTop = Math.max(
+        VIEWPORT_MARGIN,
+        viewportHeight - VIEWPORT_MARGIN - height,
+      );
+      element.style.left = `${Math.min(Math.max(claim.x + 14, VIEWPORT_MARGIN), maxLeft)}px`;
+      element.style.top = `${Math.min(Math.max(claim.y + 14, VIEWPORT_MARGIN), maxTop)}px`;
+      return;
+    }
+
+    const rect = claim.anchor.getBoundingClientRect();
+    const centeredLeft = (rect.left + rect.right - width) / 2;
+    element.style.left = `${Math.min(Math.max(centeredLeft, VIEWPORT_MARGIN), maxLeft)}px`;
+    const belowTop = rect.bottom + ANCHOR_GAP;
+    const fitsBelow = belowTop + height <= viewportHeight - VIEWPORT_MARGIN;
+    const top = fitsBelow
+      ? Math.max(VIEWPORT_MARGIN, belowTop)
+      : Math.max(VIEWPORT_MARGIN, rect.top - ANCHOR_GAP - height);
+    element.style.top = `${top}px`;
+  }
+
+  function addClaim(claim) {
+    const token = Symbol("tooltip presentation");
+    claims.push({ ...claim, token });
+    renderClaim(claims.at(-1));
+    return token;
+  }
+
+  return {
+    showPointer(content, x, y) {
+      if (disposed) return;
+      return addClaim({ kind: "pointer", content, x, y });
+    },
+    showAnchor(content, anchor) {
+      if (disposed) return;
+      return addClaim({ kind: "anchor", content, anchor });
+    },
+    hide(token) {
+      if (disposed) return;
+      const index = token === undefined
+        ? claims.length - 1
+        : claims.findIndex((claim) => claim.token === token);
+      if (index < 0) return;
+      const wasActive = index === claims.length - 1;
+      claims.splice(index, 1);
+      if (!wasActive) return;
+      const next = claims.at(-1);
+      if (next) renderClaim(next);
+      else element.classList.remove("show");
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      claims.length = 0;
+      element.remove();
+    },
+  };
+}
+
+export function attachButtonTooltips(tooltip, entries) {
+  const attached = [];
+
+  for (const entry of entries ?? []) {
+    const element = entry?.element;
+    if (!element) continue;
+
+    const originalTitle = {
+      present: element.hasAttribute("title"),
+      value: element.getAttribute("title"),
+    };
+    const originalAriaLabel = {
+      present: element.hasAttribute("aria-label"),
+      value: element.getAttribute("aria-label"),
+    };
+    if (!originalAriaLabel.present && originalTitle.present) {
+      element.setAttribute("aria-label", originalTitle.value);
+    }
+    element.removeAttribute("title");
+
+    let hovered = false;
+    let focused = false;
+    let touchActivation = false;
+    let dismissed = false;
+    let presentationToken;
+    let hasPresented = false;
+    const isUnavailable = () => (
+      element.disabled
+      || element.getAttribute("aria-disabled")?.toLowerCase() === "true"
+    );
+    const showIfNeeded = () => {
+      if (hasPresented || dismissed || touchActivation || isUnavailable() || (!hovered && !focused)) return;
+      const label = entry.getLabel?.()
+        ?? element.getAttribute("aria-label")
+        ?? originalTitle.value
+        ?? "";
+      presentationToken = tooltip.showAnchor({ title: label }, element);
+      hasPresented = true;
+    };
+    const onPointerEnter = (event) => {
+      if (event.pointerType === "touch") return;
+      hovered = true;
+      dismissed = false;
+      showIfNeeded();
+    };
+    const hidePresentation = () => {
+      if (!hasPresented) return;
+      const token = presentationToken;
+      hasPresented = false;
+      presentationToken = undefined;
+      tooltip.hide(token);
+    };
+    const syncVisibility = () => {
+      if (dismissed || isUnavailable() || (!hovered && !focused)) hidePresentation();
+      else showIfNeeded();
+    };
+    const onPointerLeave = (event) => {
+      if (event.pointerType === "touch") return;
+      hovered = false;
+      syncVisibility();
+    };
+    const onPointerDown = (event) => {
+      if (event.pointerType !== "touch") return;
+      touchActivation = true;
+      dismissed = true;
+      hidePresentation();
+    };
+    const onPointerCancel = (event) => {
+      if (event.pointerType !== "touch") return;
+      touchActivation = false;
+      dismissed = true;
+      hidePresentation();
+    };
+    const onFocus = () => {
+      focused = true;
+      if (touchActivation) return;
+      dismissed = false;
+      showIfNeeded();
+    };
+    const onBlur = () => {
+      focused = false;
+      touchActivation = false;
+      syncVisibility();
+    };
+    const dismiss = () => {
+      dismissed = true;
+      touchActivation = false;
+      hidePresentation();
+    };
+    element.addEventListener("pointerenter", onPointerEnter);
+    element.addEventListener("pointerleave", onPointerLeave);
+    element.addEventListener("pointerdown", onPointerDown);
+    element.addEventListener("pointercancel", onPointerCancel);
+    element.addEventListener("focus", onFocus);
+    element.addEventListener("blur", onBlur);
+    element.addEventListener("click", dismiss);
+    attached.push({
+      element,
+      originalTitle,
+      originalAriaLabel,
+      onPointerEnter,
+      onPointerLeave,
+      onPointerDown,
+      onPointerCancel,
+      onFocus,
+      onBlur,
+      dismiss,
+      syncVisibility,
+    });
+  }
+
+  let detached = false;
+  const runAll = (operation) => {
+    const errors = [];
+    for (const binding of attached) {
+      try { operation(binding); } catch (error) { errors.push(error); }
+    }
+    return errors;
+  };
+  const hide = () => {
+    if (detached) return;
+    throwCollected(
+      runAll((binding) => binding.dismiss()),
+      "button tooltip hide failed",
+    );
+  };
+  return {
+    hide,
+    sync() {
+      if (detached) return;
+      throwCollected(
+        runAll((binding) => binding.syncVisibility()),
+        "button tooltip sync failed",
+      );
+    },
+    detach() {
+      if (detached) return;
+      detached = true;
+      const errors = runAll((binding) => binding.dismiss());
+      for (const binding of attached) {
+        const {
+          element,
+          originalTitle,
+          originalAriaLabel,
+          onPointerEnter,
+          onPointerLeave,
+          onPointerDown,
+          onPointerCancel,
+          onFocus,
+          onBlur,
+          dismiss,
+        } = binding;
+        try {
+          element.removeEventListener("pointerenter", onPointerEnter);
+          element.removeEventListener("pointerleave", onPointerLeave);
+          element.removeEventListener("pointerdown", onPointerDown);
+          element.removeEventListener("pointercancel", onPointerCancel);
+          element.removeEventListener("focus", onFocus);
+          element.removeEventListener("blur", onBlur);
+          element.removeEventListener("click", dismiss);
+          if (originalTitle.present) element.setAttribute("title", originalTitle.value);
+          else element.removeAttribute("title");
+          if (originalAriaLabel.present) {
+            element.setAttribute("aria-label", originalAriaLabel.value);
+          } else {
+            element.removeAttribute("aria-label");
+          }
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      throwCollected(errors, "button tooltip detach failed");
+    },
+  };
+}

package/src/framework/viewer-controls.js

@@ -1,10 +1,19 @@
 import { loadRotating, saveRotating, saveCamera, loadTheme, saveTheme } from "./view-state.js";
+import { attachButtonTooltips } from "./tooltip.js";
 
 // Wire the optional viewer-chrome buttons (pause / reframe / theme) to the viewer,
 // plus persist the camera pose. Element refs in (mount resolves defaults); each
 // button is optional — pass nothing and its behavior is simply absent. Returns
 // { detach } removing every listener this attached.
-export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframeBtn, theme: themeBtn } = {}) {
+export function attachViewerControls(
+  viewer,
+  { pause: pauseBtn, reframe: reframeBtn, theme: themeBtn } = {},
+  { tooltip } = {},
+) {
+  const tooltipBinding = tooltip
+    ? attachButtonTooltips(tooltip, [pauseBtn, reframeBtn, themeBtn].map((element) => ({ element })))
+    : null;
+
   // Theme: toggle the page chrome (CSS vars keyed off <html data-theme>) and the
   // scene together; remember the choice across reloads.
   let theme = loadTheme();
@@ -13,7 +22,13 @@ export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframe
     document.documentElement.dataset.theme = mode;
     viewer.setTheme(mode);
     themeBtn?.classList.toggle("on", mode === "light");
+    if (themeBtn) {
+      const label = mode === "dark" ? "Switch to light mode" : "Switch to dark mode";
+      themeBtn.setAttribute("aria-label", label);
+      if (!tooltip) themeBtn.title = label;
+    }
     saveTheme(mode);
+    tooltipBinding?.sync();
   }
   applyTheme(theme);
   const onThemeClick = () => applyTheme(theme === "light" ? "dark" : "light");
@@ -25,7 +40,10 @@ export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframe
   const syncPause = () => {
     if (!pauseBtn) return;
     pauseBtn.textContent = rotating ? "⏸" : "▶";
-    pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
+    const label = rotating ? "Pause rotation" : "Resume rotation";
+    pauseBtn.setAttribute("aria-label", label);
+    if (!tooltip) pauseBtn.title = label;
+    tooltipBinding?.sync();
   };
   syncPause();
   const onPauseClick = () => {
@@ -37,6 +55,10 @@ export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframe
   pauseBtn?.addEventListener("click", onPauseClick);
 
   // Re-fit the camera to the current view.
+  if (reframeBtn) {
+    reframeBtn.setAttribute("aria-label", "Re-frame model");
+    if (!tooltip) reframeBtn.title = "Re-frame model";
+  }
   const onReframeClick = () => viewer.frame();
   reframeBtn?.addEventListener("click", onReframeClick);
 
@@ -52,6 +74,7 @@ export function attachViewerControls(viewer, { pause: pauseBtn, reframe: reframe
       pauseBtn?.removeEventListener("click", onPauseClick);
       reframeBtn?.removeEventListener("click", onReframeClick);
       window.removeEventListener("pagehide", onPageHide);
+      tooltipBinding?.detach();
       // the onCameraEnd listener lives on the OrbitControls object, which
       // viewer.dispose() destroys — nothing to remove here
     },

package/src/framework/viewer-lighting.js

@@ -0,0 +1,13 @@
+import * as THREE from "three";
+
+export function addViewerLights(scene) {
+  const hemisphere = new THREE.HemisphereLight(0xdce9ff, 0x687586, 1.35);
+  const key = new THREE.DirectionalLight(0xffffff, 1.45);
+  key.position.set(8, 14, 10);
+  const fill = new THREE.DirectionalLight(0xe5efff, 0.65);
+  fill.position.set(-10, 6, -8);
+
+  scene.add(hemisphere, key, fill);
+
+  return { hemisphere, key, fill };
+}