partforge 0.138.2 → 0.140.0

package/docs/AUTHORING-PARTS.md

@@ -1793,6 +1793,14 @@ cleanly tells a facet artifact (close to 180°, barely bent) from a real corner
 away from 180°) — filter on that, or pass a coarser `segs` to the tessellated shape
 before unioning, rather than fighting the selector after the fact.
 
+**Which controls a sub-part depends on** is recorded from its real build. The worker notes every `p` and `d` key that `build()` and `place()` read:
+- a derived key expands to the params its `derive` group read. `derive` must return its values, not write them onto `p`: a key `derive` writes onto `p` isn't attributed to anything;
+- a param read by a `fonts`, `images` or `vectors` declaration counts for every sub-part.
+
+The viewer rebuilds a sub-part only when one of those values changes. The panel dims a control that no on-screen sub-part read. `verify` reuses a case's measurement only when the case agrees on the params that measurement read. Geometry-guarded branches such as `if (!pocket.isEmpty())` need no special handling.
+
+Builds must stay pure functions of `(k, p, d)`. They receive `p` and `d` through a read-recording Proxy, so use them like plain objects. Don't `structuredClone` them.
+
 **`Shape2D` methods.** Existing: `union`, `cut`, `cutAll`, `intersect`, `offset`,
 `area`, `boundingBox`, `toRegions`, `simple`, `regions`, `clone`, `extrude`, `revolve`.
 New, all delegating to the pure functions above over the shape's stored contours:
@@ -3013,12 +3021,16 @@ instead of (or in addition to) the built-in `#part` bar:
   Resolves `null` on failure rather than throwing (a build error, a part with no sub-parts
   in that view, a disposed runtime). The render happens in a throwaway scene, so it takes
   no colour from the viewer's light/dark theme. The default `style` is `"thumbnail"`, the
-  product shot: a fixed light background, soft lights, lighter edges, a contact shadow and
-  fit framing — a thumbnail is captured once and then displayed under host chrome
+  product shot: a fixed light background, soft lights, lighter edges, a contact shadow,
+  4:3 framing (`size` is the width: 640 → 640×480, the shape of the cards it is shown in;
+  `cad` stays square) and fit framing — a thumbnail is captured once and then displayed under host chrome
   partforge cannot see. `style: "cad"` gives the agent-render look instead. `style.view` is
   only a default angle; an explicit `angle` wins. Pass `background` (any
   `THREE.Color`-compatible value) to override the style's, or `background: null` for no
   background at all — which clears to opaque black unless the embedder has set a clear colour.
+- `runtime.controlsFor(selection) → string[]` — the param keys relevant to a pick
+  (`selection.subPart`): today the picked sub-part's recorded reads plus its show/hide gate
+  (`enabled()`) params.
 
 Pass `onViewChange(name)` to `mount()` to be told the active view: it fires once
 synchronously during mount with the initial resolved view (before `runtime.ready` settles),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.138.2",
+  "version": "0.140.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/assembly.js

@@ -7,8 +7,8 @@ import { viewSubParts, resolveParams, buildPosed } from "./part-model.js";
 // don't trip it. Manifold-only (needs Solid.intersect + Solid.volume); meant for
 // part tests so an author/LLM editing a part sees collisions fail.
 //   → [{ a, b, volume, location }] for each offending pair (empty = no collisions)
-export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1 } = {}) {
-  const { p, d } = resolveParams(part, params);
+export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1, reads } = {}) {
+  const { p, d } = resolveParams(part, params, undefined, reads);
   // Same posed solids buildView builds, so this round is almost entirely hits off
   // that one; only the pairwise intersects below are new. Its own oracle partition,
   // for the reason buildView's comment gives.

package/src/framework/derive.js

@@ -1,3 +1,5 @@
+import { recorder } from "./read-recorder.js";
+
 // Resolve a part's `derive` into the derived-values object `d` that builds receive.
 //
 // Two authoring forms:
@@ -26,3 +28,46 @@ export function resolveDerived(part, p) {
   for (const fn of Object.values(derive)) Object.assign(d, fn(p, guard) ?? {});
   return d;
 }
+
+// resolveDerived plus attribution: which raw params each derived key came from.
+// MUST produce resolveDerived's `d`, throw its errors, and (with through) leave
+// its writes on p — tests pin all three; the worker builds with this `d`.
+// Grouped form: depsOf maps each key to its own group's raw reads, transitively
+// through the earlier groups it read. Single-function form: depsOf is null.
+export function resolveDerivedAttributed(part, p, { through = false } = {}) {
+  const allInputs = new Set();
+  const derive = part.derive;
+  if (!derive) return { d: {}, depsOf: null, allInputs };
+  if (typeof derive === "function") {
+    return { d: derive(recorder(p, allInputs, { through })) ?? {}, depsOf: null, allInputs };
+  }
+  const d = {};
+  const depsOf = new Map();
+  for (const fn of Object.values(derive)) {
+    const raw = new Set();
+    const fromEarlier = new Set();
+    const written = new Set();
+    const dProxy = new Proxy(d, {
+      get(t, key) {
+        if (typeof key === "string" && key !== "then") {
+          if (!(key in t)) throw new Error(`derive: group read "${key}" before any earlier group produced it`);
+          fromEarlier.add(key);
+        }
+        return Reflect.get(t, key);
+      },
+      set(t, key, v) {
+        if (typeof key === "string") written.add(key);
+        return Reflect.set(t, key, v);
+      },
+    });
+    const out = fn(recorder(p, raw, { through }), dProxy) ?? {};
+    const deps = new Set(raw);
+    for (const k of fromEarlier) for (const dep of depsOf.get(k) ?? []) deps.add(dep);
+    for (const r of raw) allInputs.add(r);
+    for (const key of [...Object.keys(out), ...written]) {
+      depsOf.set(key, deps);
+      if (Object.hasOwn(out, key)) d[key] = out[key];
+    }
+  }
+  return { d, depsOf, allInputs };
+}

package/src/framework/jobs.js

@@ -14,7 +14,8 @@ import { ensureImports, resolveImports } from "./imports.js";
 import { safeName } from "./safe-name.js";
 import { vectorControlAllows, vectorSourceAllowed, isNoVectorSource } from "./vector-source.js";
 import { vectorsFor, ensureVectors } from "./vectors.js";
-import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
+import { exportSubParts, resolveParamsAttributed, recordedParams, buildPosed } from "./part-model.js";
+import { newReadSink, expandReads } from "./read-recorder.js";
 
 export const FONT_SOURCE_CACHE_MAX = 4;
 
@@ -173,7 +174,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // rewriting p[key] afterwards would leave derive() — and therefore `d`, and
     // therefore the geometry — holding the refused value while build() saw the
     // default.
-    const { p, d } = resolveParams(part, msg.params, (params) => {
+    const { p, d, attribution } = resolveParamsAttributed(part, msg.params, (params) => {
       // A param bound to a `type: "font"` control is user input — on a shared
       // link a STRING value is arbitrary attacker-supplied text that
       // `fonts: (p) => …` would turn into a fetch URL. A BYTE value
@@ -234,12 +235,17 @@ export async function handle(kernel, part, msg, post, opts = {}) {
         params[key] = part.defaults?.[key];
       }
     });
+    // Params the ASSET declarations read (fonts/images/vectors may be functions
+    // of p). A build names an asset, never the param that chose it, so these are
+    // attributed to every sub-part this job builds — coarse, sound (spec §1).
+    const assetSink = newReadSink();
+    const assetP = recordedParams({ p, d }, assetSink).p;
     // Preload any part-declared fonts into the kernel before building. A lazy
     // dynamic import because this is async context (unlike the synchronous
     // kernel-front), so it doesn't cost sync callers anything. The namespace
     // shape differs between bundler and Node resolution (a bare `.default`
     // here is undefined in every browser bundle) — normalize it.
-    const fontsDecl = fontsFor(part, p);
+    const fontsDecl = fontsFor(part, assetP);
     // A nullish/empty source means "no font declared" for that name, not an
     // error — e.g. `fonts: (p) => ({ face: p.face })` when p.face ended up
     // undefined because the refusal above had no default to fall back to, or
@@ -339,7 +345,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // the kernel's image map (a host or test harness may have seeded it
     // directly via _registerImage).
     if (part.images && typeof kernel._registerImage === "function") {
-      const imagesDecl = imagesFor(part, p) ?? {};
+      const imagesDecl = imagesFor(part, assetP) ?? {};
       const declared = Object.fromEntries(
         Object.entries(imagesDecl).filter(([name, src]) => {
           if (!isNoImageSource(src)) return true;
@@ -380,7 +386,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     // on. An unset source declares NO artwork for that name; a build that
     // still calls k.vector2d on it gets the ordinary unknown-vector throw, and
     // the progress note keeps a genuine typo visible rather than swallowed.
-    const vectorsDecl = vectorsFor(part, p) ?? {};
+    const vectorsDecl = vectorsFor(part, assetP) ?? {};
     const declaredVectors = Object.fromEntries(
       Object.entries(vectorsDecl).filter(([name, src]) => {
         if (!isNoVectorSource(src)) return true;
@@ -391,6 +397,16 @@ export async function handle(kernel, part, msg, post, opts = {}) {
     await ensureVectors(kernel, declaredVectors);
     // Local shorthand over the shared helper: kernel/part/view/p/d are fixed per job.
     const posed = (name, purpose, prog) => buildPosed(kernel, part, name, { purpose, view: msg.view, p, d, onProgress: prog });
+    // A display build plus the sorted raw keys it read (spec §1): its own p/d
+    // reads, derive-expanded, plus the job's asset-declaration reads.
+    const posedWithReads = (name) => {
+      const sink = newReadSink();
+      sink.attribution = attribution;
+      const rec = recordedParams({ p, d }, sink);
+      const solid = buildPosed(kernel, part, name, { purpose: "display", view: msg.view, p: rec.p, d: rec.d });
+      for (const key of assetSink.raw) sink.raw.add(key);
+      return { solid, reads: expandReads(sink) };
+    };
     // Explicit selection (headless exportParts) overrides view-derived selection.
     const selected = () =>
       msg.parts
@@ -413,8 +429,9 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       for (const [i, name] of msg.subparts.entries()) {
         if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
         try {
-          const m = posed(name, "display").toMesh({ quality: "preview" });
-          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges, featureIds: m.featureIds, features: m.features });
+          const { solid, reads } = posedWithReads(name);
+          const m = solid.toMesh({ quality: "preview" });
+          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges, featureIds: m.featureIds, features: m.features, reads });
         } finally {
           for (const message of kernel.takeBuildWarnings?.() ?? []) warnings.push({ part: name, message });
           if (useCache) kernel.endSubPart?.(); // always close the bracket — a throw mid-build must not strand pinned solids
@@ -563,9 +580,10 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       const quick = msg.checks === "quick";
       const [{ buildView }, { measure }, { verify }] = await loadInspect();
       const view = msg.view ?? Object.keys(part.views)[0];
-      const built = buildView(kernel, part, view, msg.params ?? {});
+      const reads = newReadSink();
+      const built = buildView(kernel, part, view, msg.params ?? {}, { reads });
       const measured = measure(kernel, part, view, msg.params ?? {},
-        { minWall: !quick, gaps: !quick, built });
+        { minWall: !quick, gaps: !quick, built, reads });
       const report = {
         measure: measured,
         verify: verify(kernel, part, {

package/src/framework/measure/measure-mode.js

@@ -12,8 +12,7 @@ import * as THREE from "three";
 import { raycastViewer } from "../selection/raycast.js";
 import { createFeatureHighlight } from "../selection/feature-highlight.js";
 import { createDragTracker } from "../selection/drag-tracker.js";
-import { subPartReadKeys, RELEVANT_ALL } from "../param-deps.js";
-import { byteAwareReplacer } from "../geometry/solid-hash.js";
+import { subPartParamKeys } from "../param-deps.js";
 import { classifyFeature, bboxSpec, unionBounds } from "./feature-dims.js";
 import { paramMatches } from "./param-link.js";
 import { createPinStore, occurrenceOf } from "./pins.js";
@@ -49,7 +48,7 @@ function keyedCache(limit) {
   };
 }
 
-export function createMeasureMode(viewer, { part, getContext, revealParams, getParamsVersion, schedule = (cb) => requestAnimationFrame(cb) }) {
+export function createMeasureMode(viewer, { part, getContext, revealParams, getReads, schedule = (cb) => requestAnimationFrame(cb) }) {
   const pins = createPinStore();
   const pinListeners = new Set();
   const notifyPins = () => { for (const cb of [...pinListeners]) cb(); };
@@ -133,32 +132,9 @@ export function createMeasureMode(viewer, { part, getContext, revealParams, getP
     .filter(([, m]) => m.visible && m.geometry.getAttribute("position")?.count);
 
   // ---- param linking (scoped like selection/resolve.js scopeParams) --------
-  // Memoize the per-sub-part read-key map: subPartReadKeys runs probe builds
-  // (see mesh-cache.js's readsFor), so it must run once per (view, params)
-  // change, not once per pinned item per frame. mount's getContext() returns
-  // the SAME live params object every call (mutated in place on every edit),
-  // so identity is stable across edits and can't key the memo the way
-  // mesh-cache.js's paramsVersion getter does. mount hands in the SAME
-  // late-bound version thunk it gives createMeshCache/createPoseFastPath
-  // (`() => loop.version()`) so this keys on the cheap integer instead of
-  // hashing the whole params object every call; a caller that omits it (or a
-  // direct test) falls back to the content hash.
-  let readsKey = null, readsMap = null;
-  function readsFor(view, params) {
-    const key = `${view}|${getParamsVersion ? getParamsVersion() : JSON.stringify(params, byteAwareReplacer)}`;
-    if (readsKey !== key) {
-      readsKey = key;
-      try { readsMap = subPartReadKeys(part, view, params); } catch { readsMap = null; }
-    }
-    return readsMap;
-  }
   function readKeysFor(subPart) {
     const { view, params } = getContext();
-    const reads = readsFor(view, params);
-    if (!reads) return Object.keys(params);
-    return reads === RELEVANT_ALL
-      ? Object.keys(params)
-      : [...(reads.get(subPart) ?? Object.keys(params))];
+    return subPartParamKeys(part, view, params, getReads, subPart);
   }
   // Clicking a measurement flashes the controls whose value ACTUALLY matches
   // it (within the display quantum; radius-style params match a diameter at

package/src/framework/mesh-cache.js

@@ -1,41 +1,37 @@
-import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
+import { relevanceHash } from "./param-deps.js";
 
-// Tracks whether each sub-part's cached display mesh is still valid for the current
-// params ("Layer 1" of the cache — skipping regeneration of sub-parts whose inputs
-// didn't change). A sub-part's mesh is stamped with a relevance hash over just the
-// params that sub-part reads; it's current while that hash is unchanged and the mesh
-// is still in the viewer.
-//
-// The view/paramsVersion/caching state lives in mount and changes over time, so it's
-// passed as getters. `params` is a stable object mutated in place, so it's passed by
-// reference.
-export function createMeshCache(part, viewer, { params, getView, getParamsVersion, isCaching }) {
-  const cacheHash = {}; // name -> relevance hash the cached mesh was built at
+// Whether each sub-part's cached display mesh is still valid ("Layer 1": skip
+// regenerating sub-parts whose inputs didn't change). Each delivered mesh is
+// stamped with the params its REAL build read (recorded in the worker, jobs.js),
+// their values, and the view it was built for. It stays current while those are
+// unchanged — sound for a deterministic build: unchanged reads replay the same
+// path (spec 2026-10-03). Nothing is predicted; a sub-part with no stamp is not
+// current. `params` is a stable object mutated in place; the rest are getters.
+export function createMeshCache(viewer, { params, getView, getParamsVersion, isCaching }) {
+  const stamps = {}; // name -> { keys: string[] | null (null = every param), hash, view }
 
-  // Memoize the per-sub-part read-key map per (paramsVersion, view): subPartReadKeys
-  // runs probe builds, so we compute it once per change, not per sub-part.
-  let readsKey = null, readsMap = null;
-  const readsFor = () => {
-    const key = `${getParamsVersion()}|${getView()}`;
-    if (readsKey !== key) { readsKey = key; readsMap = subPartReadKeys(part, getView(), params); }
-    return readsMap;
-  };
-
-  // The relevance hash for one sub-part at the current params (RELEVANT_ALL → hash
-  // over ALL params, so any edit invalidates it — the safe fallback).
-  const hashFor = (name) => {
-    if (!isCaching()) return `v${getParamsVersion()}`; // caching off: any edit invalidates every sub-part
-    const reads = readsFor();
-    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(name) ?? Object.keys(params))];
-    return relevanceHash(keys, params);
+  const hashOf = (keys) => {
+    if (!isCaching()) return `v${getParamsVersion()}`; // caching off: any edit invalidates
+    return relevanceHash(keys ?? Object.keys(params), params);
   };
 
   return {
-    // A cached sub-part is current only if its relevance hash is unchanged.
-    isCurrent: (name) => viewer.hasSubMesh(name) && cacheHash[name] === hashFor(name),
-    // Stamp a freshly built mesh with the hash it was built at.
-    record: (name) => { cacheHash[name] = hashFor(name); },
-    // Drop a sub-part's stamp so it rebuilds next generate.
-    forget: (name) => { delete cacheHash[name]; },
+    isCurrent: (name) => {
+      const s = stamps[name];
+      return viewer.hasSubMesh(name) && s != null && s.view === getView() && s.hash === hashOf(s.keys);
+    },
+    // Stamp a mesh built at the LIVE params (mount's fresh branch, or the pose
+    // fast path's in-place repair). `reads` undefined = unknown → every param.
+    // `view` is the view the build was DISPATCHED for: a tab switch doesn't bump
+    // the params version, so a reply can land fresh after the live view moved.
+    record: (name, reads, view = getView()) => {
+      const keys = reads == null ? null : [...new Set(reads)].sort();
+      stamps[name] = { keys, hash: hashOf(keys), view };
+    },
+    // The recorded keys, or null for BOTH "no stamp" and "every-param stamp" —
+    // the pose fast path relies on null meaning unknown. hasStamp tells them apart.
+    readsOf: (name) => (stamps[name]?.keys ? new Set(stamps[name].keys) : null),
+    hasStamp: (name) => stamps[name] != null,
+    forget: (name) => { delete stamps[name]; },
   };
 }

package/src/framework/mount.js

@@ -15,7 +15,7 @@ import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
 import { printFrameMatrix } from "./materials/print-frame.js";
 import { burnsFor, realisticDisplay, sheetFrameFor } from "./materials/sheet-look.js";
 import { buildControls } from "./controls.js";
-import { relevantParamKeys } from "./param-deps.js";
+import { recordedRelevantKeys, subPartParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts, resolveParams } from "./part-model.js";
@@ -69,7 +69,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, renderMode, environment, declaresMaterials, renderViews }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, controlsFor, renderMode, environment, declaresMaterials, renderViews }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -129,6 +129,7 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // it back as mount()'s `panelState` and a remount comes up with the same
     // tile selected. {} when the mount resolved no panel.
     getPanelState: getPanelState ?? (() => ({})),
+    controlsFor: controlsFor ?? (() => []),
     // What custom controls reported failing this mount ({key, label, phase,
     // message}), for a host to relay to whoever authored the part.
     getPanelErrors: getPanelErrors ?? (() => []),
@@ -589,15 +590,13 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // 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.
+    // thunk. getReads reads the mesh cache (created further below) lazily.
     let panelRef = null;
     const measureMode = createMeasureMode(viewer, {
       part,
       getContext: () => ({ view: view(), params }),
       revealParams: (keys, focusKey) => panelRef?.revealParams(keys, focusKey),
-      getParamsVersion: () => loop.version(),
+      getReads: (name) => displayReadsOf(name),
     });
     cleanup.defer(() => measureMode.detach());
     // Annotation mode (spec 2026-08-18): freehand ink over the frozen view,
@@ -794,7 +793,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       let derived = {};
       // A throwing derive must not crash the pick flow — proceed without derived context.
       try { derived = resolveDerived(part, { ...part.defaults, ...params }); } catch { /* derived stays {} */ }
-      return { view: view(), params, derived };
+      return { view: view(), params, derived, readsOf: (name) => displayReadsOf(name) };
     };
 
     // Click-to-select. Precedence (one click listener is ever live): the programmatic
@@ -850,13 +849,19 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     // Per-sub-part cache-validity tracker (Layer 1): view/version/caching change over
     // time, so they're passed as getters; params is a stable in-place-mutated object.
-    const cache = createMeshCache(part, viewer, {
+    const cache = createMeshCache(viewer, {
       params,
       getView: view,
       getParamsVersion: () => loop.version(),
       isCaching: () => cachingOn,
     });
     const isCurrent = cache.isCurrent;
+    // Recorded reads for DISPLAY consumers (panel dimming, pickers, measure,
+    // controlsFor). A mesh the cache stamped every-param (its reply carried no
+    // reads) answers every param key, so the ladder never falls back to the
+    // probe for it; only a sub-part with no stamp at all gets the prediction.
+    // (cache.readsOf itself keeps null for both — the pose fast path needs that.)
+    const displayReadsOf = (name) => cache.readsOf(name) ?? (cache.hasStamp(name) ? new Set(Object.keys(params)) : null);
     const missingParts = () => viewSubParts(part, view(), params).filter((n) => !isCurrent(n));
 
     // The regenerate state machine (ready gating / debounce / stale-redo) lives in
@@ -871,6 +876,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // live ones have already left (see recordFrames). One cycle is in flight at a time,
     // so a sub-part's entry is its in-flight job's until the cycle's last reply.
     const dispatched = new Map(); // sub-part -> { view, params } its latest job was sent with
+    let updateRelevance = () => {}; // assigned once the panel exists; message handlers call it
     const loop = createRegenLoop({
       missingParts,
       send: (missing) => {
@@ -1062,7 +1068,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
           if (fresh) { // stale results (params changed mid-build) are discarded
             for (const m of data.meshes) {
               viewer.setSubGeometry(m.name, m); // disposes any previous mesh for this name
-              cache.record(m.name);
+              cache.record(m.name, m.reads, dispatched.get(m.name)?.view ?? view()); // the view its job was SENT for
               // A sub-part that built into NOTHING. Manifold booleans return an
               // empty solid rather than throwing (a bore wider than its body),
               // and typed values may sit outside the authored range, so a
@@ -1081,6 +1087,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
             // still be running — often OCCT, the slow one).
             if (missingParts().length === 0) ui.hideBusy();
             refreshView();
+            updateRelevance(); // dimming follows each delivery's recorded reads
             // After refreshView, like the error case: its all-current branch
             // clears the status line, and this message has to outlive that.
             if (missingParts().length === 0) {
@@ -1120,6 +1127,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
             for (const m of data.meshes) {
               viewer.setSubGeometry(m.name, m);
               fastPath.forget(m.name);
+              cache.forget(m.name); // the stamp described the last FRESH delivery; this mesh was built at other params, so no stamp may describe it (spec §2)
             }
             recordFrames(data.meshes.map((m) => m.name));
             ui.hideBusy();
@@ -1249,13 +1257,13 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         files, panelState });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
-    const updateRelevance = () => {
+    updateRelevance = () => {
       // A throwing derive() must not break every slider drag — mount's pick
       // flow already guards its own resolveDerived call the same way
       // (mount.js ~:250). Readouts simply stay em-dashed.
       let derived = {};
       try { derived = resolveDerived(part, params); } catch { /* diagnosed by lint/build */ }
-      panel.refresh({ relevant: relevantParamKeys(part, view(), params), derived });
+      panel.refresh({ relevant: recordedRelevantKeys(part, view(), params, displayReadsOf), derived });
     };
     updateRelevance(); // initial view
 
@@ -1426,6 +1434,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       captureView,
       getPanelState: () => panelRef?.getState() ?? {},
       getPanelErrors: () => panelRef?.errors() ?? [],
+      // The param keys relevant to a pick — today the clicked sub-part's recorded
+      // reads (spec §5). The one place a host asks "which controls shape this?".
+      controlsFor: (selection) => subPartParamKeys(part, view(), params, displayReadsOf, selection?.subPart),
       // A sheet part's row carries its stock, evaluated here on the main thread at the
       // live params the way enabled() is, and omitted when it cannot be (export-rows.js).
       listExportableParts: () => exportableRows(part, params),

package/src/framework/oracle/build.js

@@ -5,8 +5,8 @@ import { viewSubParts, resolveParams, buildPosed } from "../part-model.js";
 // `generate` path in jobs.js, but keeps solids LIVE (does NOT call
 // kernel.cleanup()) so callers can read exact solid facts (volume/genus/empty)
 // before they free the kernel. Meshes are JS-owned arrays and survive cleanup.
-export function buildView(kernel, part, view, params = {}) {
-  const { p, d } = resolveParams(part, params);
+export function buildView(kernel, part, view, params = {}, { reads } = {}) {
+  const { p, d } = resolveParams(part, params, undefined, reads);
   // Cache round for the whole view. The name is the ORACLE's, deliberately not the
   // display sub-part names the generate path brackets under: a distinct partition
   // still reuses those solids (the cache indexes entries by content hash across

package/src/framework/oracle/gates.js

@@ -87,12 +87,12 @@ export function partHasBed(part, { process } = {}) {
 // spec and already lets that throw surface from `verify()` — reporting it a second
 // time here, mid-measure, would be a confusing duplicate. Swallow it and answer "no
 // bands", the same as a part that declares none.
-export function partWallBands(part, params = {}) {
+export function partWallBands(part, params = {}, reads) {
   const spec = part?.verify?.expect;
   if (!spec) return {};
   let expect;
   if (typeof spec === "function") {
-    const { p, d } = resolveParams(part, params);
+    const { p, d } = resolveParams(part, params, undefined, reads);
     try { expect = spec(p, d) ?? {}; } catch { return {}; }
   } else {
     expect = spec;

package/src/framework/oracle/measure.js

@@ -2,6 +2,7 @@ import { buildView } from "./build.js";
 import { cachedBVH } from "./bvh.js";
 import { assemblyOverlaps } from "../assembly.js";
 import { resolveParams, buildPosed } from "../part-model.js";
+import { newReadSink, expandReads } from "../read-recorder.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { composePose } from "../geometry/pose.js";
 import { isSheetPart, sheetMeta, SHEET_CHECK_BUDGET_MS, MARK_DEPTH } from "../sheet/constants.js";
@@ -95,8 +96,8 @@ function resolveProbeValue(v, depth = 0) {
 // Evaluate every declared probe with resolved (p, d). Reads all solid facts
 // eagerly, so the caller may free the kernel's objects afterwards. Never
 // throws: each probe's failure is its own `{ error }` entry.
-function evaluateProbes(kernel, part, params) {
-  const { p, d } = resolveParams(part, params);
+function evaluateProbes(kernel, part, params, reads) {
+  const { p, d } = resolveParams(part, params, undefined, reads);
   // Oracle-owned cache round, same reasoning as buildView's: probe geometry must
   // not evict what the viewer is showing, and the next round evicts this one.
   kernel.beginSubPart?.("oracle:probes");
@@ -220,7 +221,14 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // 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);
+  // Every param this measurement depends on (spec §4): one sink through every
+  // place it resolves params. A caller-supplied view (`opts.built`) is only
+  // covered when the caller recorded its build into the same sink (opts.reads);
+  // otherwise the result claims no reads and verify reuses it only on identical
+  // params.
+  const reads = opts.reads ?? newReadSink();
+  const readsKnown = !opts.built || !!opts.reads;
+  const built = opts.built ?? buildView(kernel, part, view, params, { reads });
   // 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
@@ -242,7 +250,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   const minWallSamples = partGatesMinWall(part) ? undefined : DIAGNOSTIC_SAMPLES;
   // Declared wall bands, per sub-part, for exactly these params (Task 5). Resolved
   // once per measure; a bad declaration throws here, which is a measure error.
-  const wallBands = opts.minWall ? partWallBands(part, params) : {};
+  const wallBands = opts.minWall ? partWallBands(part, params, reads) : {};
   // Overhang is measured only for a part that opted in (dfm-profiles.js
   // overhangAngleFor) — everything else reads null. verify hands the angle it
   // resolved in (a `process` override changes it); `null` there is an explicit
@@ -259,7 +267,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // row's min-wall rays between two sheets spend it (the verdict used to depend on
   // declaration order). A view without a sheet part measures exactly as it always has.
   const sheetView = built.some(({ name }) => isSheetPart(part.parts[name]));
-  const sheetParams = sheetView ? resolveParams(part, params) : null;
+  const sheetParams = sheetView ? resolveParams(part, params, undefined, reads) : null;
   // The print-pose sizes are read by one check, the process bed (verify passes whether
   // its profile has one; alone, measure asks the part's own profile), and each costs a
   // second build of the part — so they are built only for a bed.
@@ -353,7 +361,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // false` skips them: verify's per-case re-measures pass it because no gate
   // reads probe values, so re-running their booleans per case buys nothing.
   const probes = opts.probes !== false && part.probes && Object.keys(part.probes).length
-    ? evaluateProbes(kernel, part, params)
+    ? evaluateProbes(kernel, part, params, reads)
     : undefined;
 
   // Pair surface distances from the meshes already built — no kernel dependency,
@@ -371,7 +379,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   // Rebuilds with the same kernel and cleans up at its end — every solid fact
   // above is already read, so this is safe.
   const canIntersect = built.length > 0 && typeof built[0].solid.intersect === "function";
-  const overlaps = canIntersect ? assemblyOverlaps(kernel, part, view, params) : [];
+  const overlaps = canIntersect ? assemblyOverlaps(kernel, part, view, params, { reads }) : [];
   kernel.cleanup?.();
 
   const overlapping = new Set(overlaps.map((o) => pairKey(o.a, o.b)));
@@ -403,6 +411,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
     // nothing measured it, which reads identically to "no reading available";
     // verify's seeding rule turns on exactly this distinction (see verify.js).
     measuredMinWall: !!opts.minWall,
+    // Params this measurement read (undefined = unknown: a caller-built view).
+    reads: readsKnown ? expandReads(reads) : undefined,
     // The overhang angle every sub-part's `overhangArea` was measured against,
     // or null when the pass did not run — read by verify's seed gate, never a
     // caller's claim.

package/src/framework/oracle/verify.js

@@ -3,8 +3,7 @@ import { measure as defaultMeasure } from "./measure.js";
 import { pairKey, CONTACT_EPS } from "./gaps.js";
 import { resolveProfile, overhangAngleFor } from "./dfm-profiles.js";
 import { expandExpectations, partGatesMinWall } from "./gates.js";
-import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../param-deps.js";
-import { byteAwareReplacer } from "../geometry/solid-hash.js";
+import { relevanceHash } from "../param-deps.js";
 import { SUBPART_METRICS, VIEW_METRICS } from "../verify-metrics.js";
 import { processById } from "../process/registry.js";
 import { SHEET_DOC_ID, SHEET_CHECKS_NOTICE, SHEET_READ_ERROR_HINT } from "../sheet/constants.js";
@@ -338,17 +337,20 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   const needMinWall = partGatesMinWall(part, { process, expanded });
   // Throws on a bad `verify.orientation`, the same loudness as a bad profile name.
   const overhangAngle = overhangAngleFor(part, process, { expanded });
-  const readKeys = subPartReadKeys(part, view, part.defaults);
-  // byteAwareReplacer on the RELEVANT_ALL branch too: an unattributable derive()
-  // still might read a byte-valued image param, and this memo key gates whether
-  // a case's geometry gets rebuilt or an earlier result reused (see the seeding
-  // block below) — the same collision the relevanceHash branch guards against.
-  const signature = (params) =>
-    readKeys === RELEVANT_ALL
-      ? JSON.stringify(params, byteAwareReplacer)
-      : [...readKeys.entries()].map(([name, keys]) => `${name}:${relevanceHash([...keys], params)}`).join("|");
-
-  const memo = new Map();
+  // Reuse rule (spec §4): case B may reuse a measurement taken at params A when
+  // B agrees with A on every param that measurement READ (recorded by measure()
+  // itself). Sound for the same reason the mesh cache is: a deterministic build
+  // whose reads are unchanged replays the same path. A result with no recorded
+  // reads (a stub measureFn, or a caller-built view) is reused on identical
+  // params only.
+  const full = (params) => ({ ...part.defaults, ...(params ?? {}) });
+  const entries = []; // { params: full params, result }
+  const findEntry = (params) => entries.find((e) => {
+    // A key the entry was never measured with can't be judged by its reads.
+    if (Object.keys(params).some((k) => !(k in e.params))) return false;
+    const keys = e.result?.reads ?? Object.keys({ ...e.params, ...params });
+    return relevanceHash(keys, params) === relevanceHash(keys, e.params);
+  });
 
   // SEEDING. expandCases always yields a "defaults" case, and the inspect job
   // (framework/jobs.js) measures those exact params immediately before calling
@@ -377,10 +379,9 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   // mutates facts (evaluateCase only reads), and that is what makes the sharing
   // safe; a future check that wants to annotate a fact must copy first.
   //
-  // Keyed through the SAME signature() the memo uses, never a JSON compare of the
-  // raw params — a separate compare would miss cases that share a signature (a
-  // preset touching only params the build never reads) and, worse, could hit on
-  // params that merely look equal. The seed's params are layered over
+  // Matched through the SAME reads rule every case uses, never a JSON compare of the
+  // raw params — a separate compare would miss cases that agree on everything the
+  // measurement read (a preset touching only unread params). The seed's params are layered over
   // part.defaults first because a caller's `{}` and the defaults case's
   // `{...part.defaults}` build identical geometry but hash differently
   // (JSON.stringify({}) is not JSON.stringify(defaults), and relevanceHash reads
@@ -405,19 +406,21 @@ export function verify(kernel, part, { process, view, measureFn = defaultMeasure
   const printBboxesMatch = !needPrintBboxes || seed?.result?.measuredPrintBboxes !== false;
   if (seed?.result && (quick || seed.result.measuredMinWall || !needMinWall) && (quick || overhangMatches) && printBboxesMatch
     && seed.result.view === view) {
-    memo.set(signature({ ...part.defaults, ...(seed.params ?? {}) }), seed.result);
+    entries.push({ params: full(seed.params), result: seed.result });
   }
 
   const measureCase = (params) => {
-    const key = signature(params);
-    if (memo.has(key)) return memo.get(key);
+    const fp = full(params);
+    const hit = findEntry(fp);
+    if (hit) return hit.result;
     if (quick) return null;   // a case the seed does not cover — reported, never built
     // `probes: false` — no gate reads probe values, so re-running their booleans
     // for every case buys nothing. (A seed measured WITH probes is a superset in
     // the same way a min-wall seed is: the extra key is simply never read here.)
-    memo.set(key, measureFn(kernel, part, view, params,
-      { minWall: needMinWall, probes: false, overhang: overhangAngle, printBboxes: needPrintBboxes }));
-    return memo.get(key);
+    const result = measureFn(kernel, part, view, params,
+      { minWall: needMinWall, probes: false, overhang: overhangAngle, printBboxes: needPrintBboxes });
+    entries.push({ params: fp, result });
+    return result;
   };
 
   const subPartNames = Object.keys(part.parts);

package/src/framework/param-deps.js

@@ -1,72 +1,13 @@
-// Which raw parameters affect the parts on screen in the active view. A removable
-// relevance layer: the panel uses this to dim controls / hide sections that don't
-// affect what's visible. Pure — no DOM, no real geometry (reuses the geometry-free
-// probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
+// Pure — no DOM, no real geometry.
+// PREDICTED param dependencies — computed before building, against the geometry-free probe kernel. The mesh cache, panel, pickers and oracle use the reads RECORDED from the real build and fall back to this only for sub-parts not yet built. It is wrong whenever a build branches on a geometry query (isEmpty, volume, …), which the probe answers with stand-ins.
+import { recorder, expandDerivedReads } from "./read-recorder.js";
+import { resolveDerivedAttributed } from "./derive.js";
 import { createProbeKernel } from "./geometry/probe.js";
 import { byteAwareReplacer } from "./geometry/solid-hash.js";
 import { viewSubParts } from "./part-model.js";
 
 export const RELEVANT_ALL = Symbol("relevant-all");
 
-// A read-recording Proxy over a shallow clone of `obj`: records each top-level
-// property key read into `seen`, returns the real value so the build's conditionals
-// evaluate correctly, and never mutates the original `obj` (writes hit the clone).
-function recorder(obj, seen) {
-  return new Proxy({ ...obj }, {
-    get(target, key) {
-      if (typeof key === "string") seen.add(key);
-      return Reflect.get(target, key);
-    },
-  });
-}
-
-// Run derive with recorders. `allInputs` is every raw param derive reads.
-// For the grouped form (derive as an object of group functions — see derive.js),
-// `depsOf` maps each derived key to the raw params of just its own group,
-// transitively including the groups whose outputs it read. For the single-function
-// form there is no per-key attribution, so depsOf is null and callers fall back to
-// treating every derive input as feeding every derived key.
-function analyzeDerive(part, params) {
-  const allInputs = new Set();
-  if (!part.derive) return { derived: {}, allInputs, depsOf: null };
-  if (typeof part.derive === "function") {
-    const derived = part.derive(recorder(params, allInputs)) ?? {};
-    return { derived, allInputs, depsOf: null };
-  }
-  const derived = {};
-  const depsOf = new Map();
-  for (const fn of Object.values(part.derive)) {
-    const raw = new Set();
-    const fromEarlier = new Set();
-    const written = new Set();
-    // Reads are recorded (and guarded against not-yet-produced keys, matching
-    // resolveDerived); writes pass THROUGH to the real accumulator so a group
-    // that mutates `d` in place analyzes exactly like it runs in production.
-    const dProxy = new Proxy(derived, {
-      get(t, key) {
-        if (typeof key === "string" && key !== "then") {
-          if (!(key in t)) throw new Error(`derive: group read "${key}" before any earlier group produced it`);
-          fromEarlier.add(key);
-        }
-        return Reflect.get(t, key);
-      },
-      set(t, key, v) {
-        if (typeof key === "string") written.add(key);
-        return Reflect.set(t, key, v);
-      },
-    });
-    const out = fn(recorder(params, raw), dProxy) ?? {};
-    const deps = new Set(raw);
-    for (const k of fromEarlier) for (const dep of depsOf.get(k) ?? []) deps.add(dep);
-    for (const r of raw) allInputs.add(r);
-    for (const key of [...Object.keys(out), ...written]) {
-      depsOf.set(key, deps);
-      if (Object.hasOwn(out, key)) derived[key] = out[key];
-    }
-  }
-  return { derived, allInputs, depsOf };
-}
-
 export function relevantParamKeys(part, view, params) {
   // The union of every on-screen sub-part's read set (that's exactly what
   // subPartReadKeys computes, derive attribution included)...
@@ -89,12 +30,13 @@ export function relevantParamKeys(part, view, params) {
 }
 
 // Per-sub-part version of relevantParamKeys: which raw params each ON-SCREEN
-// sub-part of the active view reads. Used by Layer 1 (mount.js) to skip
-// regenerating sub-parts whose inputs are unchanged. Errs to RELEVANT_ALL on any
+// sub-part of the active view reads. This is a PREDICTION: display consumers
+// (selection, measure) and the oracle use it until they move to recorded reads;
+// the mesh cache no longer does. Errs to RELEVANT_ALL on any
 // analysis failure (caller then treats every param as relevant — safe, just slower).
 export function subPartReadKeys(part, view, params) {
   try {
-    const { derived, allInputs, depsOf } = analyzeDerive(part, params);
+    const { d: derived, depsOf, allInputs } = resolveDerivedAttributed(part, params);
     const { kernel } = createProbeKernel();
     const map = new Map();
     for (const name of viewSubParts(part, view, params)) {
@@ -107,16 +49,7 @@ export function subPartReadKeys(part, view, params) {
       // mesh), so its reads count — without this, a param consumed only by place()
       // would let the mesh cache skip a rebuild and leave the sub-part misplaced.
       if (sp.place) sp.place(built, { view, purpose: "display", p: recorder(params, reads), d: recorder(derived, dSeen) });
-      if (dSeen.size > 0) {
-        if (depsOf && [...dSeen].every((k) => depsOf.has(k))) {
-          for (const k of dSeen) for (const dep of depsOf.get(k)) reads.add(dep);
-        } else {
-          // single-function derive, or a derived key no group produced: no
-          // attribution possible — fold every derive input in (safe, coarser).
-          for (const dep of allInputs) reads.add(dep);
-        }
-      }
-      map.set(name, reads);
+      map.set(name, expandDerivedReads(reads, dSeen, { depsOf, allInputs }));
     }
     return map;
   } catch {
@@ -133,3 +66,46 @@ export function subPartReadKeys(part, view, params) {
 export function relevanceHash(keys, params) {
   return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]), byteAwareReplacer);
 }
+
+// Which params one sub-part depends on, for DISPLAY consumers (pick scoping,
+// measure flash, runtime.controlsFor): its last real build's recorded reads
+// when there are any, else the prediction, else every param. The one ladder —
+// feature-level precision lands here later (spec §5).
+export function subPartParamKeys(part, view, params, readsOf, name) {
+  const rec = readsOf?.(name);
+  if (rec) {
+    // The worker records the BUILD's reads; the sub-part's own show/hide gate
+    // is added here, as the prediction rung does (subPartReadKeys runs enabled()).
+    const out = new Set(rec);
+    const sp = part.parts[name];
+    if (sp?.enabled) sp.enabled(recorder(params, out));
+    return [...out].sort();
+  }
+  const reads = subPartReadKeys(part, view, params);
+  const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(name) ?? Object.keys(params))];
+  return keys.sort();
+}
+
+// Panel relevance from RECORDED reads: the union over on-screen sub-parts (a
+// not-yet-built one contributes its prediction — display only, so a wrong guess
+// costs one build's dimming), plus the gate params of every in-view sub-part.
+export function recordedRelevantKeys(part, view, params, readsOf) {
+  try {
+    const relevant = new Set();
+    let predicted = null;
+    for (const name of viewSubParts(part, view, params)) {
+      const rec = readsOf(name);
+      if (rec) { for (const k of rec) relevant.add(k); continue; }
+      predicted ??= subPartReadKeys(part, view, params);
+      if (predicted === RELEVANT_ALL) return RELEVANT_ALL;
+      for (const k of predicted.get(name) ?? []) relevant.add(k);
+    }
+    for (const name of Object.keys(part.parts)) {
+      const sp = part.parts[name];
+      if (sp.views.includes(view) && sp.enabled) sp.enabled(recorder(params, relevant));
+    }
+    return relevant;
+  } catch {
+    return RELEVANT_ALL;
+  }
+}

package/src/framework/part-model.js

@@ -9,7 +9,8 @@
 // (oracle/) all call it. Keeping those four functions out of jobs.js — which is
 // async, imports the kernels, and pulls in the whole export stack — is what lets the
 // oracle depend on the part model without an import cycle back through the job loop.
-import { resolveDerived } from "./derive.js";
+import { resolveDerived, resolveDerivedAttributed } from "./derive.js";
+import { recorder } from "./read-recorder.js";
 
 // Names of the sub-parts a view shows: declared in the view and enabled for these
 // params. Order follows Object.keys(part.parts) (definition order).
@@ -39,10 +40,34 @@ export function exportSubParts(part, view, params) {
 // build() will see, or a refused value still reaches the geometry through `d`.
 // A hook rather than a second copy of this function in the caller, so "resolve a
 // part's params" keeps one definition.
-export function resolveParams(part, params, sanitize) {
+// resolveParams plus derive attribution, plain objects. `p` is passed to derive
+// itself (through), so a derive that writes p behaves exactly as unrecorded.
+export function resolveParamsAttributed(part, params, sanitize) {
   const p = { ...part.defaults, ...params };
   sanitize?.(p);
-  return { p, d: resolveDerived(part, p) };
+  const { d, depsOf, allInputs } = resolveDerivedAttributed(part, p, { through: true });
+  return { p, d, attribution: { depsOf, allInputs } };
+}
+
+// Record-through views of a resolved (p, d) into one read sink. Everything that
+// reads them — viewSubParts' enabled(), build(), place(), expect(p, d) — lands in
+// the sink with no change to the reader.
+export function recordedParams({ p, d }, sink) {
+  return { p: recorder(p, sink.raw, { through: true }), d: recorder(d, sink.dSeen, { through: true }) };
+}
+
+// `reads` (optional): a newReadSink() (read-recorder.js). When given, the returned
+// p/d record every key read into it, and the sink keeps the derive attribution
+// expandReads needs. The single seam the oracle threads its sink through.
+export function resolveParams(part, params, sanitize, reads) {
+  if (!reads) {
+    const p = { ...part.defaults, ...params };
+    sanitize?.(p);
+    return { p, d: resolveDerived(part, p) };
+  }
+  const resolved = resolveParamsAttributed(part, params, sanitize);
+  reads.attribution ??= resolved.attribution;
+  return recordedParams(resolved, reads);
 }
 
 // Build one sub-part and apply its optional place() for the given purpose/view.

package/src/framework/pose-fast-path.js

@@ -11,8 +11,8 @@ import { poseDelta } from "./geometry/pose.js";
 export function createPoseFastPath(part, viewer, cache, { params, getView, getParamsVersion }) {
   const stamps = {}; // name -> probe entry captured when that subpart's mesh was delivered
 
-  // Memoize the probe per (paramsVersion, view) — same discipline as
-  // createMeshCache's readsFor; params is the live in-place-mutated object.
+  // Memoize the probe per (paramsVersion, view), so it runs once per change
+  // rather than per sub-part; params is the live in-place-mutated object.
   let probeKey = null, probeMap = null;
   const probeFor = () => {
     const key = `${getParamsVersion()}|${getView()}`;
@@ -51,7 +51,11 @@ export function createPoseFastPath(part, viewer, cache, { params, getView, getPa
         const now = poses.get(name), was = stamps[name];
         if (!now?.trusted || !was?.trusted || now.baseHash !== was.baseHash) continue;
         viewer.setSubPose(name, poseDelta(now.pose, was.pose));
-        cache.record(name); // current again at these params — regen loop sees nothing missing
+        // Same geometry, new pose: the delivered build's reads plus whatever
+        // place() read at THIS pose, re-hashed at the live params (spec §2).
+        // An unknown stamp stays unknown.
+        const had = cache.readsOf(name);
+        cache.record(name, had ? [...had, ...(now.reads ?? [])] : undefined); // current again — regen loop sees nothing missing
         posed.push(name);
       }
       return posed;

package/src/framework/pose-probe.js

@@ -3,7 +3,8 @@
 // walks the view's sub-parts; it stays separate so lint can import the core
 // without dragging in the part-model/jobs layer (purity).
 import { probeSubPartPose } from "./pose-probe-core.js";
-import { viewSubParts, resolveParams } from "./part-model.js";
+import { viewSubParts, resolveParamsAttributed, recordedParams } from "./part-model.js";
+import { newReadSink, expandReads } from "./read-recorder.js";
 // From the import-free leaf, never fonts/images/vectors.js: vectors.js reaches paper
 // (test/mount-no-paper.test.js).
 import { fontsFor, imagesFor, vectorsFor } from "./asset-decls.js";
@@ -30,16 +31,20 @@ export function probePoses(part, view, params) {
   const out = new Map();
   let resolved, assets;
   try {
-    resolved = resolveParams(part, params);
+    resolved = resolveParamsAttributed(part, params);
     assets = h("assets", JSON.stringify(assetSources(part, resolved.p), byteAwareReplacer));
   } catch {
     for (const name of viewSubParts(part, view, params)) out.set(name, { trusted: false });
     return out;
   }
-  const { p, d } = resolved;
   for (const name of viewSubParts(part, view, params)) {
-    const entry = probeSubPartPose(part.parts[name], { view, purpose: "display", p, d });
-    out.set(name, entry.trusted ? { ...entry, baseHash: h("with-assets", entry.baseHash, assets) } : entry);
+    const sink = newReadSink();
+    sink.attribution = resolved.attribution;
+    const rec = recordedParams(resolved, sink);
+    const entry = probeSubPartPose(part.parts[name], { view, purpose: "display", p: rec.p, d: rec.d });
+    out.set(name, entry.trusted
+      ? { ...entry, baseHash: h("with-assets", entry.baseHash, assets), reads: expandReads(sink) }
+      : entry);
   }
   return out;
 }

package/src/framework/read-recorder.js

@@ -0,0 +1,50 @@
+// Read recording shared by the relevance PREDICTION (param-deps.js, against the
+// probe kernel) and the REAL build path (part-model.js resolveParams, jobs.js,
+// the oracle). A LEAF: no imports, so part-model.js may depend on it.
+//
+// Three traps record: get (p.x), has ("x" in p), ownKeys (Object.keys / spread /
+// entries / JSON.stringify — enumerating p makes the result depend on every key).
+// Default: a shallow CLONE, so a probe build can't mutate the caller's params.
+// `through: true` wraps the object itself — the real path, where derive() and
+// build() must see each other's writes exactly as they did unrecorded.
+export function recorder(obj, seen, { through = false } = {}) {
+  return new Proxy(through ? obj : { ...obj }, {
+    get(target, key) {
+      if (typeof key === "string" && key !== "then" && key !== "toJSON") seen.add(key);
+      return Reflect.get(target, key);
+    },
+    has(target, key) {
+      if (typeof key === "string" && key !== "then" && key !== "toJSON") seen.add(key);
+      return Reflect.has(target, key);
+    },
+    ownKeys(target) {
+      const keys = Reflect.ownKeys(target);
+      for (const k of keys) if (typeof k === "string") seen.add(k);
+      return keys;
+    },
+  });
+}
+
+// One build's reads: raw param keys, derived keys, and the derive attribution
+// that maps the second onto the first (set by resolveParams).
+export function newReadSink() {
+  return { raw: new Set(), dSeen: new Set(), attribution: null };
+}
+
+// Raw params behind a build's reads. With no per-key attribution (single-function
+// derive, or a key no group produced) every derive input counts — coarser, sound.
+export function expandDerivedReads(raw, dSeen, attribution) {
+  const out = new Set(raw);
+  if (dSeen.size === 0) return out;
+  const depsOf = attribution?.depsOf;
+  if (depsOf && [...dSeen].every((k) => depsOf.has(k))) {
+    for (const k of dSeen) for (const dep of depsOf.get(k)) out.add(dep);
+  } else {
+    for (const dep of attribution?.allInputs ?? []) out.add(dep);
+  }
+  return out;
+}
+
+export function expandReads(sink) {
+  return [...expandDerivedReads(sink.raw, sink.dSeen, sink.attribution)].sort();
+}

package/src/framework/renderStyles.js

@@ -45,7 +45,11 @@ const STYLES = {
     view: null,
   },
   thumbnail: {
-    camera: { projection: "perspective", fov: 45, framing: "fit", fill: 0.88 },
+    // aspect (width / height) is the shape of the card the product shot is
+    // shown in: 4:3 across the cloud's dashboard and library, so the shape-fitted
+    // framing fills the card exactly instead of being cropped by object-cover.
+    // A style without one (cad) is square.
+    camera: { projection: "perspective", fov: 45, framing: "fit", fill: 0.88, aspect: 4 / 3 },
     lights: {
       hemisphere: { ...CAD_LIGHTS.hemisphere, intensity: 1.65 },
       key: { ...CAD_LIGHTS.key, intensity: 1.25 },
@@ -71,6 +75,7 @@ export function validateRenderStyle(s) {
   check(inRange(s.camera.fov, 1, 120), "camera.fov");
   check(s.camera.framing === "canonical" || s.camera.framing === "fit", "camera.framing");
   if (s.camera.framing === "fit") check(inRange(s.camera.fill, 0.05, 1), "camera.fill");
+  if (s.camera.aspect !== undefined) check(inRange(s.camera.aspect, 0.25, 4), "camera.aspect");
   const h = s.lights?.hemisphere;
   check(isHex(h?.sky) && isHex(h?.ground) && inRange(h?.intensity, 0, 20), "lights.hemisphere");
   for (const k of ["key", "fill"]) {

package/src/framework/selection/resolve.js

@@ -1,6 +1,6 @@
 // Pure core: turn a backend-agnostic raycast hit into a semantic Selection.
 // No three.js, no DOM, no kernel — only the param-deps read-key analysis.
-import { subPartReadKeys, RELEVANT_ALL } from "../param-deps.js";
+import { subPartParamKeys } from "../param-deps.js";
 
 const COS_3DEG = 0.99863; // a normal within 3° of an axis snaps to that axis
 const q2 = (x) => { const r = Math.round(x * 100) / 100; return r === 0 ? 0 : r; }; // 0.01mm, kill -0
@@ -23,14 +23,12 @@ export function snapNormal(n) {
   return [q2(u[0]), q2(u[1]), q2(u[2])];
 }
 
-// Only the params the clicked sub-part actually reads — "this geometry, at these inputs".
-function scopeParams(part, view, params, subPart) {
-  const reads = subPartReadKeys(part, view, params);
-  const keys = reads === RELEVANT_ALL
-    ? Object.keys(params)
-    : [...(reads.get(subPart) ?? Object.keys(params))];
+// Only the params the clicked sub-part reads — "this geometry, at these inputs".
+// Recorded from its last real build when the host passes ctx.readsOf (mount's
+// mesh cache), else predicted (param-deps.subPartParamKeys).
+function scopeParams(part, ctx, subPart) {
   const out = {};
-  for (const k of keys) out[k] = params[k];
+  for (const k of subPartParamKeys(part, ctx.view, ctx.params, ctx.readsOf, subPart)) out[k] = ctx.params[k];
   return out;
 }
 
@@ -40,7 +38,7 @@ export function resolveSelection(part, ctx, hit) {
     subPart: hit.subPart,
     point,
     normal: snapNormal(hit.normalLocal),
-    params: scopeParams(part, ctx.view, ctx.params, hit.subPart),
+    params: scopeParams(part, ctx, hit.subPart),
   };
   // Feature attribution from the mesh payload (Solid.label() in the part's build) —
   // the same name the hover tooltip shows, so user, agent, and viewer share vocabulary.

package/src/framework/viewer.js

@@ -2228,7 +2228,11 @@ export function createViewer(container, part) {
     const worldPositions = payloads.map((p) => modelToWorld(p.positions));
     const points = new Float32Array(worldPositions.reduce((n, a) => n + a.length, 0));
     worldPositions.reduce((o, a) => { points.set(a, o); return o + a.length; }, 0);
-    const { pose, fov, sceneBounds } = stylePose(st, angle, box, { aspect: 1, points });
+    // `size` is the long (width) edge; the style's aspect (the thumbnail's 4:3
+    // card shape) sets the height, and the fit frames for that same aspect.
+    const width = size;
+    const height = Math.max(1, Math.round(size / (st.camera.aspect ?? 1)));
+    const { pose, fov, sceneBounds } = stylePose(st, angle, box, { aspect: width / height, points });
 
     // Light the throwaway scene ourselves: renderOffscreen's own key/fill (and the
     // persistent hemisphere) live in the LIVE scene, which is never rendered here — so
@@ -2272,7 +2276,7 @@ export function createViewer(container, part) {
         pose,
         // The throwaway scene holds these meshes and nothing else — no grid, no
         // gizmo — so its own bounds are the whole of what the planes must hold.
-        { width: size, height: size, fov, quality, sceneBounds },
+        { width, height, fov, quality, sceneBounds },
         tmpScene,
       );
     } finally {

package/src/testing/render.js

@@ -50,11 +50,15 @@ export function renderAngle(name) {
 // part still occludes what is behind it (real transparency needs a depth sort
 // this renderer does not do; stills only need to read as faded).
 export async function renderViewImages(kernel, part, view = Object.keys(part.views)[0], {
-  views = ["iso", "front", "top"], size = [800, 600], edges = true, params = {}, opacity = {},
+  views = ["iso", "front", "top"], size, edges = true, params = {}, opacity = {},
   style = "cad", supersample = 2,
 } = {}) {
   const { PNG } = await import("pngjs");
-  getRenderStyle(style); // a bad style fails here, before the kernel build
+  const resolved = getRenderStyle(style); // a bad style fails here, before the kernel build
+  // No size given: a style with its own aspect (the thumbnail's 4:3) sets the
+  // shape — 640 wide, the viewer's thumbnail size — else the 800×600 default.
+  // An explicit size is the caller's choice and is honoured as given.
+  if (!size) size = resolved.camera.aspect ? [640, Math.round(640 / resolved.camera.aspect)] : [800, 600];
   for (const angle of views) {
     if (!renderAngle(angle)) throw new Error(`unknown angle "${angle}" (use: ${RENDER_VIEWS.join(", ")}, or a view-cube orientation such as top-front-left)`);
   }

package/types/derive.d.ts

@@ -12,3 +12,17 @@ import type { Derived, PartDefinition, ResolvedParams } from "./part.js";
  * Returns `{}` when the part declares no `derive`.
  */
 export function resolveDerived(part: Pick<PartDefinition, "derive">, p: ResolvedParams): Derived;
+
+/**
+ * Resolve a part's `derive` plus attribution: which raw params each derived key came from.
+ *
+ * Produces the same `d` as `resolveDerived`, throws its errors, and (with `through`)
+ * leaves its writes on `p`. For grouped forms, `depsOf` maps each key to its group's
+ * raw reads, transitively through earlier groups it read. For single-function form,
+ * `depsOf` is null.
+ */
+export function resolveDerivedAttributed(
+  part: Pick<PartDefinition, "derive">,
+  p: ResolvedParams,
+  options?: { through?: boolean }
+): { d: Derived; depsOf: Map<string, Set<string>> | null; allInputs: Set<string> };

package/types/index.d.ts

@@ -420,7 +420,7 @@ export interface CaptureCurrentOptions {
 }
 
 export interface CaptureViewOptions {
-  /** Square render resolution in px. Default 640. */
+  /** Render width in px (the long edge). The style's aspect sets the height: `"thumbnail"` is 4:3 (640 → 640×480), `"cad"` is square. Default 640. */
   size?: number;
   /** JPEG quality, 0..1. Default 0.8. */
   quality?: number;
@@ -617,6 +617,8 @@ export interface PartRuntime {
   getPanelState(): PanelState;
   /** What custom controls reported failing this mount, in order. */
   getPanelErrors(): PanelError[];
+  /** The param keys that shape a pick: the clicked sub-part's recorded build reads (else predicted, else all). */
+  controlsFor(selection: { subPart: string }): string[];
   /**
    * Subscribe to WebGL context loss — i.e. the GPU or the OS gave up — so a host
    * can say so rather than showing a dead canvas. The listener takes no

package/types/testing.d.ts

@@ -678,6 +678,7 @@ export function renderViews(
   opts?: {
     views?: string[];
     out?: string;
+    /** [width, height] px. Default: 800×600, or 640 wide at the style's aspect when it has one (thumbnail → 640×480). */
     size?: [number, number];
     edges?: boolean;
     params?: ResolvedParams;
@@ -708,6 +709,7 @@ export function renderViewImages(
   view?: string,
   opts?: {
     views?: string[];
+    /** [width, height] px. Default: 800×600, or 640 wide at the style's aspect when it has one (thumbnail → 640×480). */
     size?: [number, number];
     edges?: boolean;
     params?: ResolvedParams;