partforge 0.53.0 → 0.55.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/oracle/match.js

@@ -0,0 +1,263 @@
+// Mask comparison: score a candidate silhouette against a reference one. Consumes the
+// masks oracle/silhouette.js produces and answers "how close is this shape?" four ways —
+// area overlap (`iou`), rim overlap (`boundaryIoU`), a mean contour separation
+// (`contourDist`), and a per-pixel `delta` map naming what is missing versus extra. No
+// kernel, no DOM, no three, no `node:`, so it runs in the geometry worker like the rest
+// of the oracle.
+//
+// Shape is compared POSE-NORMALIZED: each mask is cropped to its tight foreground bbox,
+// scaled so its longest side fills 0.92 of a 256² frame, and centroid-aligned there. So
+// `iou`, `boundaryIoU`, and `delta` are invariant to where the part sits and how big it
+// is, which is what "does it look like the picture?" means. Absolute size is a separate
+// question and only `{scaleAware: true}` asks it — and only when BOTH masks carry a
+// finite mmPerPx: `iouScale` overlays them on the reference's own mm grid,
+// centroid-aligned and never rescaled, so a part twice too big scores 0.25, and
+// `contourDist` is then a real millimetre distance instead of a fraction of the
+// reference's bbox diagonal.
+//
+// A mask with no foreground pixels — or no mask at all — is UNSCOREABLE, not
+// zero-scoring: matchMasks returns null and matchViews leaves the view out. 0/0 is
+// never a score.
+
+import { MATCH_VIEWS } from "./silhouette.js";
+
+const S = 256;            // internal normalization frame, whatever the input mask sizes
+const FILL = 0.92;        // fraction of the frame the longest bbox side occupies
+const BAND_PX = 2;        // boundary band thickness, per the Boundary IoU definition
+const BIG = 1e20;         // "unreachable" seed for the distance transform's lower envelope
+const MAX_MM_FRAME = 2048; // px ceiling on the scale-aware grid; see mmFrame
+
+// candidate/reference: Task 1 masks. opts: {scaleAware}. → null when either is unscoreable.
+export function matchMasks(candidate, reference, opts = {}) {
+  const cs = stats(candidate), rs = stats(reference);
+  if (!cs || !rs) return null;
+
+  const nc = normalize(cs), nr = normalize(rs);
+  const iou = maskIoU(nc, nr);
+  const boundaryIoU = maskIoU(band(nc), band(nr));
+  const delta = deltaMap(nc, nr);
+
+  const scaleAware = opts.scaleAware === true && scaled(candidate) && scaled(reference);
+  let contourDist, contourUnit, iouScale;
+  if (scaleAware) {
+    const [sc, sr, pitch] = mmFrame(cs, candidate.mmPerPx, rs, reference.mmPerPx);
+    iouScale = maskIoU(sc, sr);
+    contourDist = contourDistance(sc, sr) * pitch;
+    contourUnit = "mm";
+  } else {
+    const diag = Math.hypot(nr.bw, nr.bh);
+    contourDist = (contourDistance(nc, nr) / diag) * 100;
+    contourUnit = "%bbox-diag";
+  }
+
+  const out = { iou, boundaryIoU, contourDist, contourUnit, delta };
+  if (scaleAware) out.iouScale = iouScale;
+  return out;
+}
+
+// viewMasks: {front: mask|null, ...} → {best: {view, ...scores}|null, views: {view: iou}}.
+// Views are walked in MATCH_VIEWS order, so a tie on `iou` resolves to the earlier view
+// regardless of the object's own key order.
+export function matchViews(viewMasks, reference, opts = {}) {
+  const views = {};
+  let best = null;
+  for (const view of MATCH_VIEWS) {
+    const scores = matchMasks(viewMasks?.[view], reference, opts);
+    if (!scores) continue;
+    views[view] = scores.iou;
+    if (!best || scores.iou > best.iou) best = { view, ...scores };
+  }
+  return { best, views };
+}
+
+// Squared-then-rooted Euclidean distance (in px) from every pixel to the nearest non-zero
+// pixel of `data`, by Felzenszwalb–Huttenlocher: a 1D lower-envelope pass over rows, then
+// over columns. With no non-zero pixel at all every entry comes back astronomically large
+// rather than infinite, which keeps the envelope's arithmetic finite.
+export function distanceTransform(data, width, height) {
+  const n = width * height;
+  const sq = new Float64Array(n);
+  for (let i = 0; i < n; i++) sq[i] = data[i] ? 0 : BIG;
+
+  const m = Math.max(width, height);
+  const f = new Float64Array(m), d = new Float64Array(m);
+  const v = new Int32Array(m), z = new Float64Array(m + 1);
+  for (let r = 0; r < height; r++) {
+    for (let c = 0; c < width; c++) f[c] = sq[r * width + c];
+    envelope(f, width, d, v, z);
+    for (let c = 0; c < width; c++) sq[r * width + c] = d[c];
+  }
+  for (let c = 0; c < width; c++) {
+    for (let r = 0; r < height; r++) f[r] = sq[r * width + c];
+    envelope(f, height, d, v, z);
+    for (let r = 0; r < height; r++) sq[r * width + c] = d[r];
+  }
+
+  const out = new Float32Array(n);
+  for (let i = 0; i < n; i++) out[i] = Math.sqrt(sq[i]);
+  return out;
+}
+
+// Lower envelope of the parabolas (q - x)² + f[q]: `v` holds the parabolas in the
+// envelope and `z` the boundaries between them. d[] comes back as squared distances.
+function envelope(f, n, d, v, z) {
+  let k = 0;
+  v[0] = 0; z[0] = -Infinity; z[1] = Infinity;
+  for (let q = 1; q < n; q++) {
+    let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+    while (s <= z[k]) {
+      k--;
+      s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+    }
+    k++; v[k] = q; z[k] = s; z[k + 1] = Infinity;
+  }
+  k = 0;
+  for (let q = 0; q < n; q++) {
+    while (z[k + 1] < q) k++;
+    d[q] = (q - v[k]) * (q - v[k]) + f[v[k]];
+  }
+}
+
+const scaled = (mask) => Number.isFinite(mask?.mmPerPx) && mask.mmPerPx > 0;
+
+// Foreground bbox, centroid, and pixel count — null when there is nothing to score.
+function stats(mask) {
+  const data = mask?.data, w = mask?.width | 0, h = mask?.height | 0;
+  if (!data || !(w > 0) || !(h > 0) || data.length < w * h) return null;
+  let c0 = w, c1 = -1, r0 = h, r1 = -1, n = 0, sc = 0, sr = 0;
+  for (let r = 0; r < h; r++) for (let c = 0; c < w; c++) {
+    if (!data[r * w + c]) continue;
+    n++; sc += c; sr += r;
+    if (c < c0) c0 = c;
+    if (c > c1) c1 = c;
+    if (r < r0) r0 = r;
+    if (r > r1) r1 = r;
+  }
+  return n ? { data, w, h, c0, c1, r0, r1, cx: sc / n, cy: sr / n, count: n } : null;
+}
+
+// Crop to the bbox, scale the longer side to FILL*S, centroid-align into the S² frame,
+// nearest-neighbour. Sampling is done backwards from the output so the two masks share
+// one mapping form and identical shapes at different scales land on identical pixels.
+//
+// The scale is bbox-derived while the alignment is centroid-derived, so a shape whose
+// centroid sits far from its bbox centre (an L) would run past the frame edge and be
+// silently clipped. The guard shrinks such a shape to fit; it is a function of the
+// shape's own proportions, so two copies of it at different scales still normalize
+// identically and still score 1.
+function normalize(st) {
+  const bw = st.c1 - st.c0 + 1, bh = st.r1 - st.r0 + 1;
+  let s = (FILL * S) / Math.max(bw, bh);
+  const reach = Math.max(st.cx - st.c0, st.c1 - st.cx, st.cy - st.r0, st.r1 - st.cy) + 0.5;
+  const room = (S - 2) / 2;
+  if (reach * s > room) s = room / reach;
+
+  const mid = (S - 1) / 2;
+  const data = new Uint8Array(S * S);
+  for (let R = 0; R < S; R++) {
+    const r = Math.round((R - mid) / s + st.cy);
+    if (r < st.r0 || r > st.r1) continue;
+    for (let C = 0; C < S; C++) {
+      const c = Math.round((C - mid) / s + st.cx);
+      if (c < st.c0 || c > st.c1) continue;
+      if (st.data[r * st.w + c]) data[R * S + C] = 1;
+    }
+  }
+  return { data, width: S, height: S, bw: bw * s, bh: bh * s };
+}
+
+// Both masks resampled onto ONE grid at the reference's mmPerPx, centroid-aligned and
+// never rescaled — the frame where absolute size is the question. Sized to hold both, so
+// an oversized candidate is measured rather than cropped by the reference's own extent.
+// Returns the two masks and the grid's pitch in mm/px, which is the reference's own
+// except when a wildly oversized candidate would need a frame past MAX_MM_FRAME: then the
+// grid COARSENS rather than crops, since a truncated union would flatter the candidate.
+function mmFrame(cs, cmm, rs, rmm) {
+  // Half-extents in mm from each mask's own centroid, unioned so neither is cropped.
+  const span = (st, mm) => [
+    (st.cx - st.c0) * mm + mm / 2, (st.c1 - st.cx) * mm + mm / 2,
+    (st.cy - st.r0) * mm + mm / 2, (st.r1 - st.cy) * mm + mm / 2,
+  ];
+  const other = span(rs, rmm);
+  const [left, right, up, down] = span(cs, cmm).map((v, i) => Math.max(v, other[i]));
+
+  const longest = Math.max(left + right, up + down);
+  const p = Math.max(rmm, longest / MAX_MM_FRAME);
+  const gx = Math.ceil(left / p) + 1, gy = Math.ceil(up / p) + 1;
+  const width = gx + Math.ceil(right / p) + 2, height = gy + Math.ceil(down / p) + 2;
+
+  const draw = (st, mm) => {
+    const data = new Uint8Array(width * height);
+    for (let R = 0; R < height; R++) {
+      const r = Math.round(((R - gy) * p) / mm + st.cy);
+      if (r < st.r0 || r > st.r1) continue;
+      for (let C = 0; C < width; C++) {
+        const c = Math.round(((C - gx) * p) / mm + st.cx);
+        if (c < st.c0 || c > st.c1) continue;
+        if (st.data[r * st.w + c]) data[R * width + C] = 1;
+      }
+    }
+    return { data, width, height };
+  };
+  return [draw(cs, cmm), draw(rs, rmm), p];
+}
+
+function maskIoU(a, b) {
+  let inter = 0, union = 0;
+  for (let i = 0; i < a.data.length; i++) {
+    const x = a.data[i], y = b.data[i];
+    if (x && y) inter++;
+    if (x || y) union++;
+  }
+  return union ? inter / union : 0;
+}
+
+// Boundary IoU's band: the mask minus its own erosion by BAND_PX. Erosion by a disk is
+// the distance transform of the background, so the band is "foreground within BAND_PX of
+// some background pixel".
+function band(m) {
+  const inv = new Uint8Array(m.data.length);
+  for (let i = 0; i < inv.length; i++) inv[i] = m.data[i] ? 0 : 1;
+  const dt = distanceTransform(inv, m.width, m.height);
+  const data = new Uint8Array(m.data.length);
+  for (let i = 0; i < data.length; i++) if (m.data[i] && dt[i] <= BAND_PX) data[i] = 1;
+  return { data, width: m.width, height: m.height };
+}
+
+// Contour = foreground with at least one background 4-neighbour; outside the image counts
+// as background, so a shape flush with the edge still has one.
+function contour(m) {
+  const { data, width, height } = m;
+  const out = new Uint8Array(data.length);
+  for (let r = 0; r < height; r++) for (let c = 0; c < width; c++) {
+    const i = r * width + c;
+    if (!data[i]) continue;
+    if (r === 0 || r === height - 1 || c === 0 || c === width - 1
+      || !data[i - width] || !data[i + width] || !data[i - 1] || !data[i + 1]) out[i] = 1;
+  }
+  return out;
+}
+
+// Symmetric mean contour separation in px: mean distance from each mask's contour to the
+// other's, averaged both directions so neither shape's rim length dominates.
+function contourDistance(a, b) {
+  const ca = contour(a), cb = contour(b);
+  const da = distanceTransform(ca, a.width, a.height);
+  const db = distanceTransform(cb, b.width, b.height);
+  const mean = (pts, dt) => {
+    let n = 0, sum = 0;
+    for (let i = 0; i < pts.length; i++) if (pts[i]) { n++; sum += dt[i]; }
+    return n ? sum / n : 0;
+  };
+  return (mean(cb, da) + mean(ca, db)) / 2;
+}
+
+// 0 = background, 1 = overlap, 2 = missing (reference only), 3 = excess (candidate only).
+function deltaMap(c, r) {
+  const data = new Uint8Array(c.data.length);
+  for (let i = 0; i < data.length; i++) {
+    const inC = c.data[i], inR = r.data[i];
+    data[i] = inC && inR ? 1 : inR ? 2 : inC ? 3 : 0;
+  }
+  return { width: c.width, height: c.height, data };
+}

package/src/framework/oracle/measure.js

@@ -19,7 +19,11 @@ const unionBounds = (list) => list.reduce(
 //   → { part, view, measuredMinWall, subparts[], aggregate, overlaps[], gaps[],
 //       nearMisses[], ok }
 export function measure(kernel, part, view = Object.keys(part.views)[0], params = {}, opts = {}) {
-  const built = buildView(kernel, part, view, params);
+  // `opts.built` is a build of this view the caller already has. The inspect job
+  // needs those meshes anyway — it rasterizes them for silhouette match scoring —
+  // and a second buildView here would be a whole duplicate build of the part for
+  // nothing. Absent, this measures its own build exactly as it always did.
+  const built = opts.built ?? buildView(kernel, part, view, params);
   // ONE BVH per sub-part mesh for this call, shared by the two passes that need
   // one: min-wall (inward rays per triangle) and meshGaps (pair distances). They
   // used to index the same mesh objects independently, so every sub-part of a

package/src/framework/oracle/silhouette.js

@@ -0,0 +1,146 @@
+// Orthographic silhouette masks: project a part (or a set of 2D rings) onto one of the
+// six canonical views and scanline-fill it into a binary image. The foundation of
+// silhouette match scoring — no kernel, no DOM, no three, no `node:`, so it runs in the
+// geometry worker alongside the rest of the oracle.
+//
+// Contract: {data: Uint8Array of 0|255, width, height, mmPerPx, minX, minY}. Row 0 is
+// the TOP of the image; minX/minY are the projected-plane coordinates of the image's
+// BOTTOM-LEFT corner, so a caller maps a pixel back with
+//   x = minX + (col + 0.5) * mmPerPx,  y = minY + (height - 0.5 - row) * mmPerPx
+// Nothing to draw, or a projection with zero extent, returns null.
+
+export const MATCH_VIEWS = ["front", "back", "top", "bottom", "left", "right"];
+
+// Image axes per view as [modelAxisIndex, sign] in MODEL space (x,y,z) — the third axis
+// is dropped. Derived from the viewer's single pivot rotation (`pivot.rotation.x =
+// -Math.PI/2` in viewer.js, taking model Z-up to world Y-up) composed with each view's
+// camera basis in view-angles.js. A wrong sign here mirrors every downstream match
+// score without failing anything else, so the table is written out rather than derived.
+const VIEW_AXES = {
+  front:  { x: [0,  1], y: [2,  1] }, // drops Y
+  back:   { x: [0, -1], y: [2,  1] }, // drops Y
+  right:  { x: [1,  1], y: [2,  1] }, // drops X
+  left:   { x: [1, -1], y: [2,  1] }, // drops X
+  top:    { x: [0,  1], y: [1,  1] }, // drops Z
+  bottom: { x: [0,  1], y: [1, -1] }, // drops Z
+};
+
+const PAD = 0.04;            // blank fraction of the frame on each side
+const FILL = 1 - 2 * PAD;    // 0.92 — the fraction the content's longest extent occupies
+
+// meshes: [{positions: Float32Array|number[], indices?: Uint32Array|number[]}] — `indices`
+// optional, flat triangle soup when absent (3 verts per triangle), same as oracle/mesh.js.
+export function rasterizeMeshMask(meshes, view, size = 256) {
+  const axes = VIEW_AXES[view];
+  if (!axes) throw new Error(`unknown match view "${view}"`);
+  const [ax, sx] = axes.x, [ay, sy] = axes.y;
+  const groups = [];
+  for (const mesh of meshes || []) {
+    const P = mesh?.positions;
+    if (!P || P.length < 9) continue;
+    const idx = mesh.indices;
+    const n = idx ? idx.length : P.length / 3;
+    for (let i = 0; i + 3 <= n; i += 3) {
+      const tri = new Float64Array(6);
+      let ok = true;
+      for (let k = 0; k < 3 && ok; k++) {
+        const base = (idx ? idx[i + k] : i + k) * 3;
+        const x = P[base + ax] * sx, y = P[base + ay] * sy;
+        if (Number.isFinite(x) && Number.isFinite(y)) { tri[k * 2] = x; tri[k * 2 + 1] = y; }
+        else ok = false;
+      }
+      if (ok) groups.push([tri]); // one triangle = one even-odd group; see fillPolygons
+    }
+  }
+  return fillPolygons(groups, size);
+}
+
+// rings: [[[x,y], ...], ...] in mm. All rings share ONE even-odd group, so a ring inside
+// another is a hole.
+export function rasterizeRingsMask(rings, size = 256) {
+  const group = [];
+  for (const ring of rings || []) {
+    if (!ring || ring.length < 3) continue;
+    const flat = new Float64Array(ring.length * 2);
+    let ok = true;
+    for (let i = 0; i < ring.length && ok; i++) {
+      const x = ring[i]?.[0], y = ring[i]?.[1];
+      if (Number.isFinite(x) && Number.isFinite(y)) { flat[i * 2] = x; flat[i * 2 + 1] = y; }
+      else ok = false;
+    }
+    if (ok) group.push(flat);
+  }
+  return group.length ? fillPolygons([group], size) : null;
+}
+
+// A GROUP is one even-odd polygon set, given as rings of flat [x0,y0,x1,y1,...] pairs.
+// Groups UNION with each other, which is the whole reason for the grouping: a closed mesh
+// projects its front and back faces onto the same pixels, and even-odd across the whole
+// soup would cancel them into background. So each triangle is its own group and a ring
+// set is one group, and holes still subtract.
+function fillPolygons(groups, size) {
+  if (!groups.length) return null;
+  let loX = Infinity, loY = Infinity, hiX = -Infinity, hiY = -Infinity;
+  for (const g of groups) for (const ring of g) for (let i = 0; i < ring.length; i += 2) {
+    if (ring[i] < loX) loX = ring[i];
+    if (ring[i] > hiX) hiX = ring[i];
+    if (ring[i + 1] < loY) loY = ring[i + 1];
+    if (ring[i + 1] > hiY) hiY = ring[i + 1];
+  }
+  const extent = Math.max(hiX - loX, hiY - loY);
+  if (!(extent > 0)) return null;
+
+  // Uniform scale, tight bbox, PAD on each side, centred in a square frame.
+  const mmPerPx = extent / (FILL * size);
+  const span = size * mmPerPx;
+  const minX = (loX + hiX) / 2 - span / 2, minY = (loY + hiY) / 2 - span / 2;
+  const rowOf = (y) => size - 0.5 - (y - minY) / mmPerPx; // row 0 = top: y is flipped here
+
+  // Bucket each group by its first row and drop it once past its last, so a scanline only
+  // walks the groups that can cross it (a mesh soup is thousands of tiny groups).
+  const starts = Array.from({ length: size }, () => []);
+  const lastRow = new Int32Array(groups.length);
+  for (let g = 0; g < groups.length; g++) {
+    let gLo = Infinity, gHi = -Infinity;
+    for (const ring of groups[g]) for (let i = 1; i < ring.length; i += 2) {
+      if (ring[i] < gLo) gLo = ring[i];
+      if (ring[i] > gHi) gHi = ring[i];
+    }
+    const r0 = Math.min(size - 1, Math.max(0, Math.floor(rowOf(gHi))));
+    lastRow[g] = Math.min(size - 1, Math.max(0, Math.ceil(rowOf(gLo))));
+    starts[r0].push(g);
+  }
+
+  const data = new Uint8Array(size * size);
+  const xs = [];
+  let active = [];
+  for (let r = 0; r < size; r++) {
+    if (starts[r].length) active = active.concat(starts[r]);
+    if (!active.length) continue;
+    active = active.filter((g) => lastRow[g] >= r);
+    const y = minY + (size - 0.5 - r) * mmPerPx;
+    for (const g of active) {
+      xs.length = 0;
+      for (const ring of groups[g]) {
+        const n = ring.length;
+        // Half-open crossing test (y0 <= y) !== (y1 <= y): a vertex sitting exactly on the
+        // scanline is counted once, not twice, so parity stays sane.
+        for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+          const y0 = ring[j + 1], y1 = ring[i + 1];
+          if ((y0 <= y) === (y1 <= y)) continue;
+          xs.push(ring[j] + ((y - y0) * (ring[i] - ring[j])) / (y1 - y0));
+        }
+      }
+      if (xs.length < 2) continue;
+      xs.sort((a, b) => a - b);
+      for (let k = 0; k + 1 < xs.length; k += 2) {
+        let c0 = Math.ceil((xs[k] - minX) / mmPerPx - 0.5);      // first pixel CENTRE inside
+        let c1 = Math.floor((xs[k + 1] - minX) / mmPerPx - 0.5); // last pixel centre inside
+        if (c0 < 0) c0 = 0;
+        if (c1 > size - 1) c1 = size - 1;
+        for (let c = c0; c <= c1; c++) data[r * size + c] = 255;
+      }
+    }
+  }
+  return { data, width: size, height: size, mmPerPx, minX, minY };
+}

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(); },
   };
 }