partforge 0.3.3 → 0.4.0

package/docs/AUTHORING-PARTS.md

@@ -88,7 +88,7 @@ handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF
 |---|---|
 | `k.cylinder(rBottom, rTop, h, { center? })` | cylinder/cone along +Z (frustum if radii differ) |
 | `k.box(min, max)` | axis-aligned box from `[x,y,z]` min/max |
-| `k.prism(points2D, h)` | extrude a 2-D polygon (CCW `[[x,y],…]`) from z=0 |
+| `k.prism(points2D, h, { twist?, scaleTop? })` | extrude a 2-D polygon from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
 | `k.sphere(r)` | sphere centred at the origin |
 | `k.revolve(points2D, { degrees })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
 | `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove) |
@@ -108,6 +108,7 @@ entry pulls in the DOM viewer/controls, and your build functions run in a Web Wo
 | `s.translate([x,y,z])` | move |
 | `s.rotate(deg, center, axis)` | rotate `deg` about `axis` through `center` |
 | `s.mirror("XY"\|"XZ"\|"YZ")` | mirror across a plane |
+| `s.scale(factor, center?)` | uniform scale (single factor) about `center` (default origin) — scaling an off-origin part about the origin also moves it; pass a center (e.g. `s.boundingBox().center`) to resize in place |
 | `s.clone()` | independent copy (replicad consumes solids on transform) |
 | `s.boundingBox()` | `{ min, max, center, size }` axis-aligned bounds (query) |
 | `s.volume()` | volume in mm³ (Manifold) |
@@ -117,6 +118,18 @@ entry pulls in the DOM viewer/controls, and your build functions run in a Web Wo
 You normally only call the *make/combine/transform* ops; the framework handles
 `toMesh`/`toSTL`/`toIndexedMesh`/`toSTEP`. Units are millimetres.
 
+### Caching & determinism
+
+The preview kernel memoizes geometry by content hash, so editing a parameter only
+re-runs the operations that parameter actually affects. For this to be sound, a
+`build` must be a **pure function of `(k, p, d)`** — no `Math.random`, no clock, no
+module-level mutable state. An impure build will silently return stale geometry.
+
+Cache granularity follows the operations you call. Booleans and heavy primitives are
+cached; cheap transforms are recomputed. To make a multi-step shape into a single
+cache node, use (or add) a **compound op** like `k.boredCylinder({ od, h, bore })` —
+it hashes from its own arguments and never exposes its internals to the cache.
+
 ---
 
 ## Parameters: the control-panel schema
@@ -250,6 +263,10 @@ Pure helpers from `partforge/geometry` (no backend dependency):
 `slotPolygon(length,r)` (overall length = `length + 2r`), `starPolygon(points,outerR,innerR)`,
 `ringSectorPolygon(innerR,outerR,arcDeg)` (**arcDeg < 360** — a full ring is a contour-with-hole;
 cut an inner cylinder from an outer one instead).
+`circleProfile(r, center?)` — a circle of radius `r` centered at `[cx,cy]` (default origin).
+Compose it for round solids: `k.prism(circleProfile(r), h)` is a cylinder, and
+**a torus is `k.revolve(circleProfile(minorR, [majorR, 0]))`** (with `majorR > minorR`) —
+partforge has no `torus` primitive because it's just a revolved circle.
 
 **Patterns** (return `Solid[]` — feed to `k.union(...)` for features or `s.cutAll(...)` for holes):
 `linearPattern(solid, count, [dx,dy,dz])`, `circularPattern(solid, count, { center, axis, angle, rotateCopies })`.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "partforge",
-  "version": "0.3.3",
+  "version": "0.4.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",
-  "repository": { "type": "git", "url": "git+https://github.com/scottsykora/partforge.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottsykora/partforge.git"
+  },
   "homepage": "https://github.com/scottsykora/partforge#readme",
   "bugs": "https://github.com/scottsykora/partforge/issues",
   "engines": {

package/src/framework/debug-overlay.js

@@ -0,0 +1,40 @@
+// src/framework/debug-overlay.js
+// A dev-only overlay (shown under ?debug) with a caching on/off toggle and a
+// readout of the last build's time + what the cache did. Self-contained: it
+// creates its own DOM and knows nothing about geometry — mount.js wires it in.
+export function createDebugOverlay({ initialCachingOn = true, onToggle } = {}) {
+  const box = document.createElement("div");
+  box.id = "pf-debug";
+  Object.assign(box.style, {
+    position: "fixed", bottom: "12px", right: "12px", zIndex: "9999",
+    font: "12px ui-monospace, monospace", background: "rgba(0,0,0,0.7)",
+    color: "#e6e6e6", padding: "8px 10px", borderRadius: "6px",
+    lineHeight: "1.5", whiteSpace: "pre",
+  });
+
+  const label = document.createElement("label");
+  label.style.cssText = "display:block;cursor:pointer;margin-bottom:4px";
+  const cb = document.createElement("input");
+  cb.type = "checkbox";
+  cb.checked = initialCachingOn;
+  cb.style.marginRight = "6px";
+  label.append(cb, document.createTextNode("Caching"));
+
+  const readout = document.createElement("div");
+  readout.textContent = "build: —";
+
+  box.append(label, readout);
+  document.body.appendChild(box);
+
+  cb.addEventListener("change", () => onToggle?.(cb.checked));
+
+  return {
+    update({ ms, hits = 0, misses = 0, skipped = 0, rebuilt = 0 } = {}) {
+      const l2 = cb.checked ? `${hits} hit / ${misses} miss` : "off";
+      readout.textContent =
+        `build: ${ms != null ? Math.round(ms) + " ms" : "—"}\n` +
+        `L2 ops: ${l2}\n` +
+        `L1 parts: ${skipped} skipped / ${rebuilt} rebuilt`;
+    },
+  };
+}

package/src/framework/geometry/kernel.js

@@ -3,6 +3,7 @@
 
 /**
  * @typedef {Object} Solid  An opaque handle to a backend solid.
+ * @property {string} _hash   content hash (Manifold backend only; drives the worker solid cache)
  * @property {(tool: Solid) => Solid} cut
  * @property {(tools: Solid[]) => Solid} cutAll      batch subtract (backend-optimized)
  * @property {(other: Solid) => Solid} intersect     boolean intersection (Manifold)
@@ -12,6 +13,7 @@
  * @property {(v: number[]) => Solid} translate
  * @property {(deg: number, center: number[], axis: number[]) => Solid} rotate
  * @property {(plane: "XY"|"XZ"|"YZ") => Solid} mirror
+ * @property {(factor:number, center?:number[]) => Solid} scale   uniform scale about center (default origin)
  * @property {() => number} volume                   solid volume in mm³ (Manifold; used by collision tests)
  * @property {(opts?: {quality?: "preview"|"print"}) => {positions:Float32Array, normals:Float32Array, indices:Uint32Array, triangles:number}} toMesh
  * @property {(opts?: {quality?: "preview"|"print"}) => Promise<ArrayBuffer>} toSTL
@@ -19,9 +21,10 @@
  *
  * @typedef {Object} GeometryKernel
  * @property {(rBottom:number, rTop:number, h:number, opts?:{center?:boolean}) => Solid} cylinder
+ * @property {(o:{od:number,h:number,bore:number}) => Solid} boredCylinder   compound: bored-through cylinder (one cache node)
  * @property {(r:number) => Solid} sphere   sphere centred at the origin
  * @property {(min:number[], max:number[]) => Solid} box
- * @property {(points2D:number[][], h:number) => Solid} prism   extrude polygon from z=0
+ * @property {(points2D:number[][], h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0 (optional twist° + uniform top taper)
  * @property {(points2D:number[][], opts?:{degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union

package/src/framework/geometry/manifold-backend.js

@@ -1,5 +1,7 @@
 import { helixTube } from "./helix-tube.js";
 import { KernelCapabilityError } from "./errors.js";
+import { h } from "./solid-hash.js";
+import { createSolidCache } from "./solid-cache.js";
 
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
@@ -22,6 +24,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const T = (obj) => { tracked.push(obj); return obj; };
   const unionRaw = (ms) => ms.reduce((a, b) => T(a.add(b))); // track each reduce step
 
+  const cache = createSolidCache();
+  // Boundary ops route through cache.lookup; on a miss `make` runs the WASM op,
+  // tracks the result, and returns the triple the cache needs to pin/dispose it.
+  const cached = (hash, computeM) => cache.lookup(hash, () => {
+    const m = computeM();                 // already T()-tracked by the op
+    return { value: wrap(m, hash), pin: m, dispose: () => m.delete?.() };
+  });
+
   // Copy the mesh out into JS-owned arrays (so it survives cleanup) and free the
   // transient mesh handle.
   function meshOut(m, asStl) {
@@ -48,12 +58,14 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     return { positions, indices };
   }
 
-  const wrap = (m) => ({
+  const wrap = (m, hash) => ({
     _m: m,
-    cut: (t) => wrap(T(m.subtract(t._m))),
-    cutAll: (tools) => wrap(T(m.subtract(unionRaw(tools.map((t) => t._m))))),
-    intersect: (t) => wrap(T(m.intersect(t._m))),
-    clone: () => wrap(m),
+    _hash: hash,
+    cut: (t) => cached(h("cut", hash, t._hash), () => T(m.subtract(t._m))),
+    cutAll: (tools) => cached(h("cutAll", hash, tools.map((t) => t._hash)),
+      () => T(m.subtract(unionRaw(tools.map((t) => t._m))))),
+    intersect: (t) => cached(h("intersect", hash, t._hash), () => T(m.intersect(t._m))),
+    clone: () => wrap(m, hash),
     boundingBox: () => {
       const b = m.boundingBox();           // { min: Vec3, max: Vec3 }
       const min = [...b.min], max = [...b.max];
@@ -66,14 +78,20 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     volume: () => m.volume(),
     genus: () => m.genus(),
     isEmpty: () => m.isEmpty(),
-    translate: (v) => wrap(T(m.translate(v))),
+    translate: (v) => wrap(T(m.translate(v)), h("translate", hash, v)),
     rotate: (deg, center, axis) => {
       const euler = [axis[0] * deg, axis[1] * deg, axis[2] * deg];
       const a = T(m.translate([-center[0], -center[1], -center[2]]));
       const b = T(a.rotate(euler));
-      return wrap(T(b.translate(center)));
+      return wrap(T(b.translate(center)), h("rotate", hash, deg, center, axis));
+    },
+    mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane])), h("mirror", hash, plane)),
+    scale: (factor, center = [0, 0, 0]) => {
+      if (!(factor > 0)) throw new Error("scale: factor must be > 0");
+      const a = T(m.translate([-center[0], -center[1], -center[2]]));
+      const b = T(a.scale([factor, factor, factor]));
+      return wrap(T(b.translate(center)), h("scale", hash, factor, center));
     },
-    mirror: (plane) => wrap(T(m.mirror(PLANE_NORMAL[plane]))),
     toMesh: () => meshOut(m, false),
     toSTL: () => Promise.resolve(meshOut(m, true)),
     toIndexedMesh: () => indexedMeshOut(m),
@@ -83,26 +101,45 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   });
 
   return {
-    cylinder: (rb, rt, h, { center = false } = {}) => wrap(T(Manifold.cylinder(h, rb, rt, segs, center))),
-    sphere: (r) => wrap(T(Manifold.sphere(r, segs))),
+    cylinder: (rb, rt, h2, { center = false } = {}) =>
+      wrap(T(Manifold.cylinder(h2, rb, rt, segs, center)), h("cylinder", rb, rt, h2, center, segs)),
+    // Compound op: hashed ATOMICALLY from its own args, so it is a single cache
+    // node — its internal cylinders/cut are never retained. The template for
+    // future compounds: build internals with T(), return the final tracked solid.
+    boredCylinder: ({ od, h: height, bore }) => cached(h("boredCylinder", od, height, bore, segs), () => {
+      const body = T(Manifold.cylinder(height, od / 2, od / 2, segs, false));
+      const tool0 = T(Manifold.cylinder(height + 4, bore / 2, bore / 2, segs, false));
+      const tool = T(tool0.translate([0, 0, -2])); // raw ops: track each result
+      return T(body.subtract(tool));
+    }),
+    sphere: (r) => wrap(T(Manifold.sphere(r, segs)), h("sphere", r, segs)),
     box: (min, max) => {
       const cube = T(Manifold.cube([max[0] - min[0], max[1] - min[1], max[2] - min[2]]));
-      return wrap(T(cube.translate(min)));
-    },
-    prism: (pts, h) => {
-      const cs = T(CrossSection.ofPolygons([pts]));
-      return wrap(T(cs.extrude(h)));
-    },
-    helixSweptTube: (o) => wrap(T(helixTube(wasm, { ...o, ...tube }))),
-    revolve: (pts, { degrees = 360 } = {}) => {
-      for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
-      return wrap(T(Manifold.revolve([pts], segs, degrees)));
+      return wrap(T(cube.translate(min)), h("box", min, max));
     },
-    union: (solids) => wrap(unionRaw(solids.map((s) => s._m))), // unionRaw already tracks its result
+    prism: (pts, height, { twist = 0, scaleTop = 1 } = {}) =>
+      cached(h("prism", pts, height, twist, scaleTop, segs), () => {
+        if (scaleTop < 0) throw new Error("prism: scaleTop must be ≥ 0");
+        const cs = T(CrossSection.ofPolygons([pts]));
+        if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
+        const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
+        return T(cs.extrude(height, nDiv, twist, scaleTop));
+      }),
+    helixSweptTube: (o) => cached(h("helixSweptTube", o, tube), () => T(helixTube(wasm, { ...o, ...tube }))),
+    revolve: (pts, { degrees = 360 } = {}) =>
+      cached(h("revolve", pts, degrees, segs), () => {
+        for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
+        return T(Manifold.revolve([pts], segs, degrees));
+      }),
+    union: (solids) => cached(h("union", solids.map((s) => s._hash)), () => unionRaw(solids.map((s) => s._m))),
     toSTEP: () => { throw new Error("STEP export not supported by the Manifold backend"); },
-    // Free every WASM object created since the last cleanup. Call after each job
-    // once its meshes/buffers have been copied out (meshOut already did).
-    cleanup: () => { for (const o of tracked) o.delete?.(); tracked.length = 0; },
+    beginSubPart: (name) => cache.begin(name),
+    endSubPart: () => cache.end(),
+    cacheStats: () => cache.stats(),
+    resetCacheStats: () => cache.resetStats(),
+    // Free every WASM object created since the last cleanup EXCEPT solids the cache
+    // still pins (they must survive for the next build to resume from them).
+    cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },
   };
 }
 

package/src/framework/geometry/occt-backend.js

@@ -93,6 +93,10 @@ export function createOcctKernel(replicad) {
     translate: (v) => wrap(shape.translate(v)),
     rotate: (deg, center, axis) => wrap(shape.rotate(deg, center, axis)),
     mirror: (plane) => wrap(shape.mirror(plane)),
+    scale: (factor, center = [0, 0, 0]) => {
+      if (!(factor > 0)) throw new Error("scale: factor must be > 0");
+      return wrap(shape.scale(factor, center));
+    },
     toMesh: ({ quality = "preview" } = {}) => {
       const m = shape.mesh(MESH[quality]);
       return {
@@ -127,10 +131,16 @@ export function createOcctKernel(replicad) {
   };
 
   // extrude a 2-D polygon from z=0
-  const prism = (pts, h) => {
+  const prism = (pts, h, { twist = 0, scaleTop = 1 } = {}) => {
+    if (scaleTop < 0) throw new Error("prism: scaleTop must be ≥ 0");
     let pen = draw(pts[0]);
     for (let i = 1; i < pts.length; i++) pen = pen.lineTo(pts[i]);
-    return wrap(pen.close().sketchOnPlane("XY").extrude(h));
+    const sketch = pen.close().sketchOnPlane("XY");
+    if (twist === 0 && scaleTop === 1) return wrap(sketch.extrude(h));
+    const cfg = {};
+    if (twist !== 0) cfg.twistAngle = twist;
+    if (scaleTop !== 1) cfg.extrusionProfile = { profile: "linear", endFactor: scaleTop };
+    return wrap(sketch.extrude(h, cfg));
   };
 
   // revolve a lathe profile [[r,z],…] around the Z axis (degrees defaults to 360)
@@ -152,7 +162,10 @@ export function createOcctKernel(replicad) {
   };
 
   return {
-    cylinder, box: (min, max) => wrap(makeBox(min, max)), prism, revolve, helixSweptTube,
+    cylinder,
+    boredCylinder: ({ od, h, bore }) =>
+      cylinder(od / 2, od / 2, h).cut(cylinder(bore / 2, bore / 2, h + 4).translate([0, 0, -2])),
+    box: (min, max) => wrap(makeBox(min, max)), prism, revolve, helixSweptTube,
     sphere: (r) => wrap(makeSphere(r)),
     union: (solids) => wrap(solids.map((s) => s._s).reduce((a, b) => a.fuse(b))),
     toSTEP: (named) => exportSTEP(named.map(({ name, solid }) => ({ name, shape: solid._s }))).arrayBuffer(),

package/src/framework/geometry/polygon.js

@@ -124,3 +124,17 @@ export function circularPattern(solid, count, { center = [0, 0, 0], axis = "Z",
   }
   return out;
 }
+
+// CCW circle of radius r centered at [cx, cy]. A shared 2-D profile primitive:
+// compose with the kernel's profile ops — e.g. revolve(circleProfile(minorR,
+// [majorR, 0])) is a torus, prism(circleProfile(r), h) a cylinder.
+export function circleProfile(r, center = [0, 0], segs = 48) {
+  if (!(r > 0)) throw new Error("circleProfile: r must be > 0");
+  const [cx, cy] = center;
+  const pts = [];
+  for (let i = 0; i < segs; i++) {
+    const a = (2 * Math.PI * i) / segs;
+    pts.push([cx + r * Math.cos(a), cy + r * Math.sin(a)]);
+  }
+  return pts;
+}

package/src/framework/geometry/probe.js

@@ -15,6 +15,7 @@ export function createProbeKernel() {
     translate() { note("translate"); return proxy; },
     rotate() { note("rotate"); return proxy; },
     mirror() { note("mirror"); return proxy; },
+    scale() { note("scale"); return proxy; },
     fillet() { note("fillet"); return proxy; },
     chamfer() { note("chamfer"); return proxy; },
     shell() { note("shell"); return proxy; },
@@ -25,6 +26,7 @@ export function createProbeKernel() {
   };
   const kernel = {
     cylinder() { note("cylinder"); return proxy; },
+    boredCylinder() { note("boredCylinder"); return proxy; },
     sphere() { note("sphere"); return proxy; },
     box() { note("box"); return proxy; },
     prism() { note("prism"); return proxy; },

package/src/framework/geometry/solid-cache.js

@@ -0,0 +1,39 @@
+// Worker-side cache of boundary-op solids, partitioned per sub-part. Retention is
+// bounded to the CURRENT build's graph: each begin()/end() bracket rebuilds a
+// sub-part's retained set from scratch, disposing any entry not re-used this round.
+// WASM-agnostic — it stores opaque {value, pin, dispose} triples supplied by the
+// caller (the Manifold backend), so it is unit-testable with plain objects.
+export function createSolidCache() {
+  const caches = new Map(); // name -> Map(hash -> { value, pin, dispose })
+  const pinned = new Set();  // every live `pin` across all sub-parts
+  let name = null, active = null, prev = null;
+  let hits = 0, misses = 0;
+
+  return {
+    begin(n) { name = n; prev = caches.get(n) ?? new Map(); active = new Map(); },
+
+    end() {
+      if (name == null) return;
+      for (const [hash, entry] of prev) {
+        if (!active.has(hash)) { pinned.delete(entry.pin); entry.dispose(); } // evict
+      }
+      caches.set(name, active);
+      name = null; active = prev = null;
+    },
+
+    lookup(hash, make) {
+      if (name == null) return make().value; // not bracketed → no caching
+      if (active.has(hash)) { hits++; return active.get(hash).value; }
+      if (prev.has(hash)) { hits++; const e = prev.get(hash); active.set(hash, e); return e.value; }
+      misses++;
+      const entry = make();
+      active.set(hash, entry);
+      pinned.add(entry.pin);
+      return entry.value;
+    },
+
+    isPinned: (pin) => pinned.has(pin),
+    stats: () => ({ hits, misses }),
+    resetStats: () => { hits = 0; misses = 0; },
+  };
+}

package/src/framework/geometry/solid-hash.js

@@ -0,0 +1,21 @@
+// Stable content hash for cached solids. Serializes scalar args canonically and
+// folds via FNV-1a → base36. Solid operands are passed as their own (already
+// computed) short `_hash` string, so composing two solids stays O(1) and the
+// resulting key length stays bounded no matter how deep the build graph is.
+export function h(...parts) {
+  return fnv(parts.map(canon).join("|"));
+}
+
+function canon(x) {
+  if (Array.isArray(x)) return "[" + x.map(canon).join(",") + "]";
+  if (x && typeof x === "object") return "{" + Object.keys(x).sort().map((k) => k + ":" + canon(x[k])).join(",") + "}";
+  return String(x);
+}
+
+// FNV-1a folded to 32-bit space (collision risk acceptable: retained only for one
+// sub-part's build graph ~3–15 nodes, rebuilt each round, no accumulation).
+function fnv(s) {
+  let hsh = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) { hsh ^= s.charCodeAt(i); hsh = Math.imul(hsh, 0x01000193); }
+  return (hsh >>> 0).toString(36);
+}

package/src/framework/jobs.js

@@ -42,13 +42,20 @@ export async function handle(kernel, part, msg, post) {
   try {
     if (msg.type === "generate") {
       const t0 = Date.now();
+      const useCache = msg.cache !== false; // ?debug toggle can disable caching (cache:false)
       const meshes = [];
+      kernel.resetCacheStats?.(); // count hits/misses for just this job
       for (const name of msg.subparts) {
-        const m = buildPosed(name, "display", msg.view).toMesh({ quality: "preview" });
-        meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges });
-        kernel.cleanup?.();
+        if (useCache) kernel.beginSubPart?.(name); // open the per-sub-part cache round
+        try {
+          const m = buildPosed(name, "display", msg.view).toMesh({ quality: "preview" });
+          meshes.push({ name, positions: m.positions, normals: m.normals, indices: m.indices, triangles: m.triangles, edges: m.edges });
+        } finally {
+          if (useCache) kernel.endSubPart?.(); // always close the bracket — a throw mid-build must not strand pinned solids
+          kernel.cleanup?.();                  // free this round's transients (cached/pinned solids survive)
+        }
       }
-      post({ type: "meshes", meshes, ms: Date.now() - t0 });
+      post({ type: "meshes", meshes, ms: Date.now() - t0, cache: kernel.cacheStats?.() });
     } else if (msg.type === "export-stl") {
       const out = [];
       for (const name of exportSubParts(part, msg.view, p)) {

package/src/framework/mount.js

@@ -3,10 +3,12 @@ import { zipSync } from "fflate";
 import { createViewer } from "./viewer.js";
 import { loadRotating, saveRotating, loadCamera, saveCamera, loadView, saveView } from "./view-state.js";
 import { buildControls } from "./controls.js";
-import { relevantParamKeys } from "./param-deps.js";
+import { relevantParamKeys, subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./jobs.js";
 import { detectBackend } from "./geometry/probe.js";
+import { createDebugOverlay } from "./debug-overlay.js";
+import { attachPicker, formatSelection } from "./selection/index.js";
 
 // Mount a full parametric-part app from a PartDefinition: 3-D viewer + control
 // panel + the two geometry workers + the auto-regenerating view/cache loop +
@@ -24,6 +26,15 @@ export function mount(part, { createWorker, container = document.getElementById(
   if (forcedBackend !== "occt" && forcedBackend !== "manifold") forcedBackend = null;
   const backendFor = () => forcedBackend ?? detectBackend(part, params);
 
+  // ?debug shows the cache debug overlay; ?debug&nocache starts with caching off.
+  const qs = new URLSearchParams(location.search);
+  const debug = qs.has("debug");
+  let cachingOn = !(debug && qs.has("nocache"));
+  let lastGen = { skipped: 0, rebuilt: 0 }; // Layer-1 counts for the most recent generate
+  const dbg = debug
+    ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
+    : null;
+
   const statusEl = document.getElementById("status");
   const dlBtn = document.getElementById("download");
   const dlStepBtn = document.getElementById("download-step");
@@ -56,16 +67,76 @@ export function mount(part, { createWorker, container = document.getElementById(
   const savedBtn = savedView ? [...partSeg.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === savedView) : null;
   let view = savedBtn ? savedView : defaultView;
   if (savedBtn) for (const b of partSeg.children) b.classList.toggle("on", b === savedBtn);
+
+  // ?pick enables click-to-select: a toggle button + a transient toast. Off by
+  // default — no button, no listener, no behavior change. Deleting this block and
+  // the selection/ dir reverts the app exactly.
+  if (qs.has("pick")) {
+    const btn = document.createElement("button");
+    btn.id = "pf-pick";
+    btn.textContent = "Pick";
+    btn.title = "Click a surface to copy a selection token";
+    Object.assign(btn.style, {
+      position: "fixed", left: "12px", bottom: "12px", zIndex: 9999,
+      font: "12px system-ui, sans-serif", padding: "6px 10px", cursor: "pointer",
+    });
+    document.body.appendChild(btn);
+
+    const toast = document.createElement("div");
+    Object.assign(toast.style, {
+      position: "fixed", left: "12px", bottom: "48px", zIndex: 9999, maxWidth: "60ch",
+      font: "12px ui-monospace, monospace", padding: "6px 10px", borderRadius: "4px",
+      background: "rgba(20,24,29,0.92)", color: "#d8e0ea", display: "none",
+      whiteSpace: "pre-wrap", wordBreak: "break-word",
+    });
+    document.body.appendChild(toast);
+
+    const picker = attachPicker(viewer, {
+      part,
+      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
+      onPick: (selection) => {
+        const token = formatSelection(selection, { style: "token" });
+        navigator.clipboard?.writeText(token);
+        toast.textContent = `copied: ${token}`;
+        toast.style.display = "block";
+        setTimeout(() => { toast.style.display = "none"; }, 4000);
+      },
+    });
+
+    btn.addEventListener("click", () => {
+      const isActive = btn.classList.toggle("on");
+      picker.setActive(isActive);
+      btn.style.outline = isActive ? "2px solid #ffcc33" : "";
+    });
+  }
+
   let framedView = null; // the view the camera was last framed to (null until first show)
   let cameraRestored = false; // saved camera applied once, on the first frame after load
   let generating = false;
   let paramsVersion = 0; // bumped on every settings edit
   let genVersion = -1;   // the params version the in-flight generate is building
   let genTimer = null;   // debounce timer for auto-regenerate
-  const cacheVersion = Object.fromEntries(names.map((n) => [n, -1])); // params version each was built at
+  const cacheHash = {}; // n -> relevance hash each sub-part's cached mesh was built at
+
+  // 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 = `${paramsVersion}|${view}`;
+    if (_readsKey !== key) { _readsKey = key; _readsMap = subPartReadKeys(part, view, 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 = (n) => {
+    if (!cachingOn) return `v${paramsVersion}`; // caching off: any edit invalidates every sub-part (Layer 1 off)
+    const reads = readsFor();
+    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(n) ?? Object.keys(params))];
+    return relevanceHash(keys, params);
+  };
 
-  // A cached sub-part is current only if it was built at the latest params version.
-  const isCurrent = (n) => viewer._subCache[n] && cacheVersion[n] === paramsVersion;
+  // A cached sub-part is current only if its relevance hash is unchanged.
+  const isCurrent = (n) => !!viewer._subCache[n] && cacheHash[n] === hashFor(n);
   const missingParts = () => viewSubParts(part, view, params).filter((n) => !isCurrent(n));
 
   // Reflect the active view. If every needed part is current, show it and enable
@@ -138,13 +209,14 @@ export function mount(part, { createWorker, container = document.getElementById(
         for (const m of data.meshes) {
           if (viewer._subCache[m.name]) { viewer._subCache[m.name].userData.edges?.dispose(); viewer._subCache[m.name].dispose(); }
           viewer.setSubGeometry(m.name, m);
-          cacheVersion[m.name] = genVersion;
+          cacheHash[m.name] = hashFor(m.name);
         }
         hideBusy();
         refreshView();
         if (data.ms && missingParts().length === 0) {
           setStatus(`${statusEl.textContent} · ${(data.ms / 1000).toFixed(1)} s`);
         }
+        dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt });
         maybeGenerate(); // active view may still need parts (tab switched during build)
         break;
       }
@@ -194,12 +266,22 @@ export function mount(part, { createWorker, container = document.getElementById(
   // Build whatever the active view is missing — automatic, no Generate button.
   function maybeGenerate() {
     if (!kernelReady || generating) return; // retried when the current build finishes
-    const missing = missingParts();
+    const needed = viewSubParts(part, view, params);
+    const missing = needed.filter((n) => !isCurrent(n));
     if (missing.length === 0) return;
     generating = true;
     genVersion = paramsVersion;
+    lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
     showBusy("generating");
-    service.generate({ type: "generate", subparts: missing, view, params }, backendFor());
+    service.generate({ type: "generate", subparts: missing, view, params, cache: cachingOn }, backendFor());
+  }
+
+  // Re-run the active view under the current caching setting, so toggling the
+  // ?debug switch updates the readout for the same design without a param change.
+  function forceRegen() {
+    for (const n of viewSubParts(part, view, params)) delete cacheHash[n];
+    refreshView();
+    maybeGenerate();
   }
 
   partSeg.addEventListener("click", (e) => {

package/src/framework/param-deps.js

@@ -48,3 +48,34 @@ export function relevantParamKeys(part, view, params) {
     return RELEVANT_ALL; // couldn't analyze — treat everything as relevant
   }
 }
+
+// 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
+// analysis failure (caller then treats every param as relevant — safe, just slower).
+export function subPartReadKeys(part, view, params) {
+  try {
+    const deriveInputs = new Set();
+    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
+    const { kernel } = createProbeKernel();
+    const map = new Map();
+    for (const name of viewSubParts(part, view, params)) {
+      const sp = part.parts[name];
+      const reads = new Set();
+      const dSeen = new Set();
+      if (sp.enabled) sp.enabled(recorder(params, reads)); // gate params change presence too
+      sp.build(kernel, recorder(params, reads), recorder(derived, dSeen));
+      if (dSeen.size > 0) for (const k of deriveInputs) reads.add(k);
+      map.set(name, reads);
+    }
+    return map;
+  } catch {
+    return RELEVANT_ALL;
+  }
+}
+
+// Stable string of the given param keys' current values — the cache-validity key
+// for one sub-part. Sorted so key order never affects the result.
+export function relevanceHash(keys, params) {
+  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]));
+}

package/src/framework/selection/format.js

@@ -0,0 +1,31 @@
+// Pure serializer. No three.js, no DOM. Three styles for the same Selection:
+//   token  — compact clipboard/CLI line
+//   json   — the structured object (embedded tool-call transport)
+//   prompt — one natural-language sentence an LLM ingests well
+const AXIS_LABEL = { "1,0,0": "+X", "-1,0,0": "-X", "0,1,0": "+Y", "0,-1,0": "-Y", "0,0,1": "+Z", "0,0,-1": "-Z" };
+
+const fmtNormal = (n) => AXIS_LABEL[n.join(",")] ?? n.join(",");
+const fmtParams = (p) => Object.entries(p).map(([k, v]) => `${k}:${v}`).join(",");
+
+function tokenStyle(s) {
+  const head = `@${s.subPart}`;
+  const feat = s.feature
+    ? ` · ${s.feature.kind === "cylinder"
+        ? `cyl-face r=${s.feature.radius} axis=${s.feature.axis}`
+        : `${s.feature.kind}-face`}`
+    : "";
+  return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
+}
+
+function promptStyle(s) {
+  const params = Object.entries(s.params).map(([k, v]) => `${k}: ${v}`).join(", ");
+  const feat = s.feature ? ` a ${s.feature.kind} face,` : "";
+  return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
+    + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
+}
+
+export function formatSelection(selection, { style = "token" } = {}) {
+  if (style === "json") return selection;
+  if (style === "prompt") return promptStyle(selection);
+  return tokenStyle(selection);
+}

package/src/framework/selection/index.js

@@ -0,0 +1,5 @@
+// Public surface for the click-to-select module. The future agent harness depends
+// only on attachPicker's onPick callback + the Selection contract — nothing else.
+export { resolveSelection, quantizePoint, snapNormal } from "./resolve.js";
+export { formatSelection } from "./format.js";
+export { attachPicker, worldToSubPartLocal } from "./pick.js";

package/src/framework/selection/pick.js

@@ -0,0 +1,48 @@
+// Viewer adapter — the ONLY three.js/DOM-aware file in the selection module.
+// Raycasts a click against the visible sub-meshes, converts the hit to the
+// sub-part's local CAD frame, and hands a resolved Selection to onPick.
+import * as THREE from "three";
+import { resolveSelection } from "./resolve.js";
+
+// Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
+// shared-frame CAD coords — the same frame build() models in.
+export function worldToSubPartLocal(mesh, world) {
+  const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
+  mesh.worldToLocal(v);
+  return [v.x, v.y, v.z];
+}
+
+export function attachPicker(viewer, { part, getContext, onPick }) {
+  const raycaster = new THREE.Raycaster();
+  const ndc = new THREE.Vector2();
+  let active = false;
+
+  function onClick(ev) {
+    if (!active) return;
+    const rect = viewer.domElement.getBoundingClientRect();
+    ndc.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
+    ndc.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
+    raycaster.setFromCamera(ndc, viewer.camera);
+
+    const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
+    const hit = raycaster.intersectObjects(meshes, false)[0];
+    if (!hit) return;
+
+    const selection = resolveSelection(part, getContext(), {
+      subPart: hit.object.name,
+      pointLocal: worldToSubPartLocal(hit.object, hit.point),
+      // face.normal is in the geometry's local frame, which equals the CAD frame here
+      // (the mesh carries no local transform; only its parents rotate/recentre).
+      normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
+      // hit.face metadata (kind/axis/radius) is the L1 increment — not populated yet.
+    });
+    viewer.flashPoint([hit.point.x, hit.point.y, hit.point.z]);
+    onPick(selection);
+  }
+
+  viewer.domElement.addEventListener("click", onClick);
+  return {
+    setActive: (on) => { active = !!on; },
+    detach: () => viewer.domElement.removeEventListener("click", onClick),
+  };
+}

package/src/framework/selection/resolve.js

@@ -0,0 +1,54 @@
+// 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";
+
+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
+
+export function quantizePoint(p) {
+  return [q2(p[0]), q2(p[1]), q2(p[2])];
+}
+
+export function snapNormal(n) {
+  const len = Math.hypot(n[0], n[1], n[2]) || 1;
+  const u = [n[0] / len, n[1] / len, n[2] / len];
+  let ai = 0; // index of the dominant axis
+  if (Math.abs(u[1]) > Math.abs(u[ai])) ai = 1;
+  if (Math.abs(u[2]) > Math.abs(u[ai])) ai = 2;
+  if (Math.abs(u[ai]) >= COS_3DEG) {
+    const axis = [0, 0, 0];
+    axis[ai] = u[ai] > 0 ? 1 : -1;
+    return axis;
+  }
+  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))];
+  const out = {};
+  for (const k of keys) out[k] = params[k];
+  return out;
+}
+
+export function resolveSelection(part, ctx, hit) {
+  const point = quantizePoint(hit.pointLocal);
+  const selection = {
+    subPart: hit.subPart,
+    point,
+    normal: snapNormal(hit.normalLocal),
+    params: scopeParams(part, ctx.view, ctx.params, hit.subPart),
+  };
+  if (hit.face) {
+    // L1 — feature.selector is the author's own { dir, inPlane, at, near } vocabulary,
+    // so the LLM can drop it straight into a faces(...)/edges(...) call.
+    const feature = { kind: hit.face.kind, selector: { near: point } };
+    if (hit.face.axis != null) { feature.axis = hit.face.axis; feature.selector.dir = hit.face.axis; }
+    if (hit.face.radius != null) feature.radius = hit.face.radius;
+    selection.feature = feature;
+  }
+  return selection;
+}

package/src/framework/viewer.js

@@ -76,7 +76,8 @@ export function createViewer(container, part) {
   const subMesh = Object.fromEntries(
     names.map((n) => [n, new THREE.Mesh(new THREE.BufferGeometry(), materialFor(n))])
   );
-  for (const m of Object.values(subMesh)) {
+  for (const [n, m] of Object.entries(subMesh)) {
+    m.name = n;
     m.visible = false;
     partsGroup.add(m);
   }
@@ -226,5 +227,17 @@ export function createViewer(container, part) {
     container.removeChild(renderer.domElement);
   }
 
-  return { showAssembly, hideAssembly, setSubGeometry, resize, dispose, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, _subCache: subCache };
+  // Transient marker at a world-space point — visual confirmation of a pick.
+  function flashPoint(world) {
+    const dot = new THREE.Mesh(
+      new THREE.SphereGeometry(1.2, 16, 12),
+      new THREE.MeshBasicMaterial({ color: 0xffcc33, depthTest: false })
+    );
+    dot.renderOrder = 999;
+    dot.position.set(world[0], world[1], world[2]);
+    scene.add(dot);
+    setTimeout(() => { scene.remove(dot); dot.geometry.dispose(); dot.material.dispose(); }, 1200);
+  }
+
+  return { showAssembly, hideAssembly, setSubGeometry, resize, dispose, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, _subCache: subCache, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint };
 }