partforge 0.53.0 → 0.55.0

package/docs/AUTHORING-PARTS.md

@@ -487,6 +487,12 @@ if (p.drain > 0) s = s.cut(k.cylinder({ r: d.drainR, h: p.floor + 4 }).at([0, 0,
 - Names should describe intent ("Drainage hole", not "cylinder2"); make them
   unique per sub-part unless you specifically want the merge behavior.
 
+Labels do double duty in the viewer: the hover tooltip names the feature, and
+**measurement mode** (the ruler button in the viewbar) measures it — a labeled
+hole reads ⌀ + depth, a labeled face reads its extents, and a click pins that
+dimension so it tracks parameter changes live. Label the features a user would
+want to measure; unlabeled geometry still measures as its bounding box.
+
 ### Caching & determinism
 
 The preview kernel memoizes geometry by content hash, so editing a parameter only
@@ -1230,7 +1236,7 @@ stylesheet). `mount` looks up these element IDs:
 | `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` and opens the resolved default (see the "Which view the viewer opens on" rule above) |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#reframe` / `#cutaway` / `#measure` / `#theme` | optional viewer controls (omit any you don't want) |
 | `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
 | `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#reframe`/`#theme` |
 
@@ -1296,7 +1302,10 @@ pane's pixel size:
   `null` when the runtime is disposed or nothing is built/visible yet — it never throws.
   `hideGrid: false` keeps the floor grid so the capture matches the on-screen look
   exactly. The live view is untouched: the camera never moves, and lights/grid/render
-  target are restored after the render.
+  target are restored after the render. Measurement-mode dimensions render directly
+  in the scene, so a dimensioned capture needs no special handling — enable measure
+  mode (`runtime.measure.setEnabled(true)`) and call `captureCurrent()`; the dims are
+  just part of the rendered frame.
 - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle
   counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.
@@ -1370,6 +1379,7 @@ mount(part, {
     chrome: {
       reframe,
       cutaway,
+      measure,
       theme,
       railToggle,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.53.0",
+  "version": "0.55.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/app.css

@@ -313,6 +313,9 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 #viewbar .pf-cutaway-actions { display: flex; gap: 4px; }
 #viewbar .pf-cutaway-actions[hidden] { display: none; }
 #viewbar .pf-cutaway-actions button { width: auto; min-width: 56px; padding: 0 8px; }
+#viewbar .pf-measure-actions { display: flex; gap: 4px; }
+#viewbar .pf-measure-actions[hidden] { display: none; }
+#viewbar .pf-measure-actions button { width: auto; min-width: 56px; padding: 0 8px; }
 #viewbar button:disabled { opacity: .38; cursor: not-allowed; }
 #viewbar button:disabled:hover { color: var(--pf-muted-2); background: transparent; }
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
@@ -327,10 +330,21 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 @media (max-width: 360px) {
   #viewbar { gap: 3px; }
   #viewbar button { width: 30px; height: 30px; font-size: 13px; }
-  #viewbar .pf-cutaway-actions { gap: 3px; }
-  #viewbar .pf-cutaway-actions button { min-width: 44px; padding: 0 6px; }
+  #viewbar .pf-cutaway-actions, #viewbar .pf-measure-actions { gap: 3px; }
+  #viewbar .pf-cutaway-actions button, #viewbar .pf-measure-actions button { min-width: 44px; padding: 0 6px; }
 }
 
+/* ---- measurement mode -----------------------------------------------------
+   Dimensions render in-scene — three.js objects placed alongside the part in
+   the viewer, not a DOM/SVG overlay. This CSS block only styles the viewbar
+   chrome: the unit tag shown next to the measure controls. */
+.pf-measure-unit {
+  font-family: var(--pf-mono); font-size: 10px; color: var(--pf-muted);
+  align-self: center; user-select: none; cursor: pointer;
+}
+#viewbar .pf-measure-actions button.pf-measure-unit { min-width: auto; padding: 0 6px; }
+.pf-measure-unit:hover { color: var(--pf-text-2); }
+
 /* animation transport bar (placement: chrome.css's .pf-anim-bar). APPEARANCE
    is ungated for the same reason as #viewbar above. */
 .pf-anim-bar {
@@ -582,3 +596,14 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
   white-space: pre-wrap; word-break: break-word; display: none;
 }
 #pf-pick-toast.show { display: block; }
+
+/* dimension->control reveal: a decaying accent pulse that hands off to the
+   focused control's own focus ring */
+/* outline (not box-shadow) so outline-offset can space the ring away from
+   the control without touching layout */
+.pf-param-flash { animation: pf-param-flash 900ms ease-out; outline-offset: 5px; border-radius: 6px; }
+@keyframes pf-param-flash {
+  0% { outline: 3px solid color-mix(in oklab, var(--pf-accent) 70%, transparent); }
+  100% { outline: 3px solid transparent; }
+}
+@media (prefers-reduced-motion: reduce) { .pf-param-flash { animation: none; } }

package/src/framework/cutaway-controls.js

@@ -1,4 +1,5 @@
 import { attachButtonTooltips } from "./tooltip.js";
+import { runCleanupSteps, captureAttributes, restoreAttributes } from "./teardown.js";
 
 const UNSUPPORTED_TITLE = "Cutaway requires a stencil-capable WebGL context";
 const BUTTON_ATTRIBUTES = [
@@ -12,17 +13,6 @@ const BUTTON_ATTRIBUTES = [
 
 const noop = () => {};
 
-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, "cutaway control cleanup failed");
-  }
-}
-
 function actionButton(label, title) {
   const button = document.createElement("button");
   button.type = "button";
@@ -32,23 +22,9 @@ function actionButton(label, title) {
   return button;
 }
 
-function captureAttributes(element, names) {
-  return new Map(names.map((name) => [name, {
-    present: element.hasAttribute(name),
-    value: element.getAttribute(name),
-  }]));
-}
-
-function restoreAttributes(element, attributes) {
-  for (const [name, { present, value }] of attributes) {
-    if (present) element.setAttribute(name, value);
-    else element.removeAttribute(name);
-  }
-}
-
 // Wire the optional cutaway button to the viewer and create its contextual
 // actions. Hosts that omit the primary button opt out of all DOM behavior.
-export function attachCutawayControls(viewer, { cutaway: button } = {}, { tooltip } = {}) {
+export function attachCutawayControls(viewer, { cutaway: button } = {}, { tooltip, escapeGuard } = {}) {
   if (!button) return { reset: noop, detach: noop };
 
   const canvas = viewer.domElement;
@@ -116,6 +92,7 @@ export function attachCutawayControls(viewer, { cutaway: button } = {}, { toolti
   };
   const onEscape = (event) => {
     if (event.key !== "Escape" || !viewer.cutawayEnabled()) return;
+    if (escapeGuard?.()) return; // an inner lens (measure mode) claims this Escape
     event.preventDefault();
     disable();
   };
@@ -149,7 +126,7 @@ export function attachCutawayControls(viewer, { cutaway: button } = {}, { toolti
         () => restoreAttributes(button, hostButtonAttributes),
         () => { button.disabled = hostButtonDisabled; },
         () => button.classList.toggle("on", hostButtonOn),
-      ]);
+      ], "cutaway control cleanup failed");
     },
   };
 }

package/src/framework/cutaway-gizmo-scene.js

@@ -1,7 +1,9 @@
 import * as THREE from "three";
 import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
 
-const GIZMO_RENDER_ORDER = CUTAWAY_OVERLAY_RENDER_ORDER + 1;
+// +10: above the caps/highlight tier AND above measure mode's dims
+// (dim3-scene renders at +2/+3) — an actively-dragged control outranks ink.
+const GIZMO_RENDER_ORDER = CUTAWAY_OVERLAY_RENDER_ORDER + 10;
 const HANDLE_HOVER_THICKNESS = 1.6;
 
 /**

package/src/framework/jobs.js

@@ -9,6 +9,9 @@ import { safeName } from "./safe-name.js";
 import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
 import { measure } from "./oracle/measure.js";
 import { verify } from "./oracle/verify.js";
+import { buildView } from "./oracle/build.js";
+import { MATCH_VIEWS, rasterizeMeshMask, rasterizeRingsMask } from "./oracle/silhouette.js";
+import { matchViews } from "./oracle/match.js";
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -26,6 +29,67 @@ import { verify } from "./oracle/verify.js";
 // preview generates stay quiet (no callback) to avoid flicker during slider drags.
 const bufferOf = (data) => (ArrayBuffer.isView(data) ? data.buffer : data);
 
+// One caller-supplied match target as a reference mask, or null when it is not one we
+// can score. Every field here is untrusted wire data, so shape is checked rather than
+// assumed — a target the caller got wrong is skipped, never thrown, so one bad entry
+// cannot cost the others their scores (or the caller their geometry report).
+//   {kind: "profile", rings: [[[x,y], ...], ...]}  — millimetres, so it carries scale
+//   {kind: "image",   mask: {data, width, height}} — a photo, so it carries none
+function referenceMask(target) {
+  if (target?.kind === "profile") return Array.isArray(target.rings) ? rasterizeRingsMask(target.rings) : null;
+  if (target?.kind === "image") {
+    const m = target.mask;
+    if (!m?.data || !(m.width > 0) || !(m.height > 0)) return null;
+    // mmPerPx is deliberately absent: a photograph has no millimetres, which is what
+    // keeps the scale-aware comparison off for an image target no matter what is asked.
+    return { data: m.data, width: m.width, height: m.height };
+  }
+  return null;
+}
+
+// Score the part's six canonical silhouettes against each match target.
+// `built` is the view's already-built sub-parts — the meshes are JS-owned, so this
+// reads correctly after the kernel has been cleaned up.
+//
+// Total by construction: match scoring is an EXTRA on top of the geometric report, so
+// any failure here omits `match` and leaves the report itself intact. A caller who
+// asked for a score and got none can ask again; a caller who lost their measurement
+// because a mask blew up has lost the thing they actually came for.
+//
+// The six mesh masks are rasterized ONCE and shared across every target — the targets
+// are the cheap side of this (a couple of reference masks), the part is not.
+function scoreMatchTargets(built, targets, onProgress) {
+  if (!targets?.length) return null;
+  try {
+    const meshes = built.map((b) => b.mesh);
+    const viewMasks = {};
+    for (const view of MATCH_VIEWS) viewMasks[view] = rasterizeMeshMask(meshes, view);
+
+    const out = [];
+    for (const target of targets) {
+      try {
+        const reference = referenceMask(target);
+        if (!reference) continue;
+        // scaleAware is the CALLER's promise that both sides are in millimetres, and
+        // this is the caller: rings are mm and the mesh masks carry mmPerPx, so a
+        // profile target gets the absolute-size score (`iouScale`, contourDist in mm)
+        // while an image target gets the pose-normalized one.
+        const scoreOpts = { scaleAware: target.kind === "profile" };
+        const { best, views } = matchViews(viewMasks, reference, scoreOpts);
+        if (!best) continue; // nothing scoreable — a dropped target, never a zero score
+        const { delta, ...scores } = best;
+        out.push({ kind: target.kind, best: scores, views, delta: { view: best.view, ...delta } });
+      } catch (err) {
+        onProgress(`match target skipped: ${String(err?.message || err)}`);
+      }
+    }
+    return out.length ? out : null;
+  } catch (err) {
+    onProgress(`match scoring skipped: ${String(err?.message || err)}`);
+    return null;
+  }
+}
+
 export async function handle(kernel, part, msg, post, opts = {}) {
   const isStale = opts.isStale ?? (() => false);
   const onProgress = (phase) => post({ type: "progress", phase, jobId: msg.jobId });
@@ -147,7 +211,12 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       // true }` here is what makes the seed usable by any verify run, min-wall
       // gated or not — the result says so itself (`measuredMinWall`), so this
       // call and the seed cannot drift apart.
-      const measured = measure(kernel, part, msg.view, msg.params ?? {}, { minWall: true });
+      //
+      // The view is built HERE rather than inside measure, and handed down through
+      // `opts.built`, because optional match scoring needs the same meshes: one build
+      // feeds the measurement and the six silhouette rasterizations both.
+      const built = buildView(kernel, part, msg.view, msg.params ?? {});
+      const measured = measure(kernel, part, msg.view, msg.params ?? {}, { minWall: true, built });
       const report = {
         measure: measured,
         verify: verify(kernel, part, {
@@ -155,7 +224,11 @@ export async function handle(kernel, part, msg, post, opts = {}) {
           seed: { params: msg.params ?? {}, result: measured },
         }),
       };
-      post({ type: "report", ...report });
+      // `match` is present only when the caller asked for it AND something scored, so
+      // an inspect with no `matchTargets` answers on exactly the shape it always has.
+      const match = scoreMatchTargets(built, msg.matchTargets, onProgress);
+      if (match) report.match = match;
+      post({ type: "report", ...report }, match?.map((m) => m.delta.data.buffer) ?? []);
     }
   } catch (err) {
     if (err?.code === "NEEDS_OCCT") post({ type: "needs-occt", jobId: msg.jobId });