partforge 0.3.3 → 0.5.0

package/README.md

@@ -50,6 +50,11 @@ hide internal params, and keep the interface simple while staying deeply adjusta
 `src/parts/demo.js` is a minimal worked example; run `npm run dev` and open
 `/demo.html` to see it live.
 
+- **Agent clarification (`request-a-pick`):** an external tool can ask the user to click
+  geometry and get the `Selection` back — serve with `?pickserver`, drive with
+  `partforge pick-serve` + `partforge pick "<prompt>" …`. See
+  `skills/partforge/SKILL.md` and the authoring guide.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -8,54 +8,76 @@ import { detectBackend } from "../src/framework/geometry/probe.js";
 import { bootOcctKernel } from "../src/testing/occt.js";
 import { measure } from "../src/testing/measure.js";
 import { renderViews } from "../src/testing/render.js";
+import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 const slug = (s) => String(s).toLowerCase().replace(/\s+/g, "-");
 
-const [, , cmd, partPath, ...rest] = process.argv;
+const [, , cmd, ...args] = process.argv;
 const flags = {};
 const positional = [];
-for (let i = 0; i < rest.length; i++) {
-  if (rest[i].startsWith("--")) {
-    const key = rest[i].slice(2);
-    flags[key] = rest[i + 1] && !rest[i + 1].startsWith("--") ? rest[++i] : true;
-  } else positional.push(rest[i]);
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith("--")) {
+    const key = args[i].slice(2);
+    flags[key] = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : true;
+  } else positional.push(args[i]);
 }
-const view = positional[0];
 
-if (!["measure", "render"].includes(cmd)) die("usage: partforge <measure|render> <part-module> [view] [flags]");
-if (!partPath) die(`usage: partforge ${cmd} <part-module> [view]`);
+const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
 
-const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
-  .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
-const part = mod.default;
-if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
-
-let kernel;
-if (detectBackend(part) === "occt") {
-  kernel = await bootOcctKernel();
-} else {
-  const wasm = await Module(); wasm.setup();
-  kernel = createManifoldKernel(wasm, { quality: "preview" });
+// --- pick-serve / pick: no part module, no kernel boot --------------------------
+if (cmd === "pick-serve") {
+  const port = Number(flags.port) || 4518;
+  const timeoutMs = (Number(flags.timeout) || 120) * 1000;
+  const { port: bound } = await createPickServer({ port, timeoutMs }).start();
+  console.log(`partforge pick-server listening on http://127.0.0.1:${bound}`);
+  // keep the process alive serving requests
+} else if (cmd === "pick") {
+  if (positional.length === 0) die('usage: partforge pick "<prompt>" ["<prompt>" …] [--port N]');
+  const port = Number(flags.port) || 4518;
+  const out = await requestPicks({ port, prompts: positional }).catch((e) => die(e.message));
+  console.log(formatPickResult(out));
+  process.exit(out.status === "done" ? 0 : 1);
+} else if (!["measure", "render"].includes(cmd)) {
+  die(USAGE);
 }
 
-try {
-  if (cmd === "measure") {
-    const report = measure(kernel, part, view);
-    printMeasure(report);
-    const file = `measure-${slug(report.part)}-${report.view}.json`;
-    writeFileSync(file, JSON.stringify(report, null, 2));
-    console.log(`\nwrote ${file}`);
-    if (flags.json) console.log(JSON.stringify(report, null, 2));
-    process.exit(report.ok ? 0 : 1);
+const partPath = positional[0];
+const view = positional[1];
+if (["measure", "render"].includes(cmd) && !partPath) die(`usage: partforge ${cmd} <part-module> [view]`);
+
+if (["measure", "render"].includes(cmd)) {
+  const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
+    .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
+  const part = mod.default;
+  if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
+
+  let kernel;
+  if (detectBackend(part) === "occt") {
+    kernel = await bootOcctKernel();
   } else {
-    const views = typeof flags.views === "string" ? flags.views.split(",") : undefined;
-    const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
-    for (const f of files) console.log(`wrote ${f}`);
-    process.exit(0);
+    const wasm = await Module(); wasm.setup();
+    kernel = createManifoldKernel(wasm, { quality: "preview" });
+  }
+
+  try {
+    if (cmd === "measure") {
+      const report = measure(kernel, part, view);
+      printMeasure(report);
+      const file = `measure-${slug(report.part)}-${report.view}.json`;
+      writeFileSync(file, JSON.stringify(report, null, 2));
+      console.log(`\nwrote ${file}`);
+      if (flags.json) console.log(JSON.stringify(report, null, 2));
+      process.exit(report.ok ? 0 : 1);
+    } else {
+      const views = typeof flags.views === "string" ? flags.views.split(",") : undefined;
+      const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
+      for (const f of files) console.log(`wrote ${f}`);
+      process.exit(0);
+    }
+  } catch (e) {
+    die(`${cmd} failed: ${e.message || e}`);
   }
-} catch (e) {
-  die(`${cmd} failed: ${e.message || e}`);
 }
 
 function printMeasure(r) {

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 })`.
@@ -450,3 +467,21 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
   `place(..., { purpose: "export" })` may depend on `view`.
 - Keep geometry backend-agnostic (kernel calls only) so it works in both backends; only
   STEP requires OCCT.
+
+---
+
+## Interactive clarification: request-a-pick
+
+An external tool (e.g. an AI agent editing your part) can ask the *user* to click
+geometry and receive the `Selection` back, closing the loop in the other direction
+from `?pick`.
+
+- Serve your app with **`?pickserver`** (or `?pickserver=http://host:port`) to enable
+  it. While idle nothing changes; when the local pick-server requests a click, a banner
+  appears ("🤖 Claude needs you to click …") and the picker arms for one click.
+- The agent side runs `partforge pick-serve` once, then `partforge pick "<prompt>" …`
+  for one or more clicks (collected in order, returned together). The CLI blocks until
+  the user clicks, then prints the `Selection`(s) as JSON.
+
+See the bundled skill `skills/partforge/SKILL.md` for the agent workflow. This is plain
+click-routing — no LLM logic lives in partforge.

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "partforge",
-  "version": "0.3.3",
+  "version": "0.5.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": {
@@ -13,6 +16,7 @@
   "files": [
     "src",
     "bin",
+    "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
     "README.md"
   ],

package/skills/partforge/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: partforge-request-pick
+description: Use when editing a partforge part for a user who has the live app open and you need them to point at geometry — ask for one or more clicks and get the Selection(s) back.
+---
+
+# partforge: request-a-pick
+
+When you're editing a partforge part and you're unsure *which* face, edge, hole, or
+sub-part the user means, don't guess — ask them to click it in the live app. Their
+click comes back to you as a structured `Selection` (sub-part, local CAD point,
+surface normal, the parameters they were viewing).
+
+## When to use
+
+- The user's request is geometrically ambiguous ("make this thicker", "fillet that
+  edge", "move the hole") and more than one feature could match.
+- You need a concrete location/normal to drive an edit.
+
+## One-time setup (per session)
+
+Start the pick-server (it bridges the app and this CLI). The user must have the app
+open with `?pickserver` (e.g. `http://localhost:5173/?pickserver`).
+
+```bash
+partforge pick-serve &     # default http://127.0.0.1:4518
+```
+
+## Requesting clicks
+
+Ask for one or many — they're collected in order and returned together:
+
+```bash
+partforge pick "click the face you want filleted"
+partforge pick "click the mounting hole" "click the top edge" "click the boss"
+```
+
+Tell the user out loud to check their browser ("I've put a prompt in your browser —
+click the face you want filleted"). The command **blocks** until they click (or
+timeout), then prints a summary plus JSON:
+
+```json
+{ "status": "done", "picks": [ { "prompt": "...", "selection": { "subPart": "...", "point": [...], "normal": [...], "params": {...} } } ] }
+```
+
+Picks come back **in request order**, each echoing its prompt, so you can map them.
+
+## Handling outcomes
+
+- `done` — proceed with the returned `selection`(s).
+- `timeout` — the user didn't click in time; `picks` holds any collected so far. Ask
+  again or fall back to asking in words.
+- `cancelled` — the user clicked "Can't find it"; reconsider what you're asking for.
+- `busy` (exit non-zero) — a request is already in flight; wait and retry.
+
+## Notes
+
+- This only *reads* a click — it never edits files. You make the edits yourself after.
+- The server is localhost-only and holds one request at a time.

package/src/framework/app.css

@@ -163,4 +163,48 @@ button.action:disabled { opacity: .5; cursor: default; }
 /* relevance: controls/sections that don't affect the on-screen parts */
 .irrelevant { opacity: 0.45; }
 .irrelevant:hover { opacity: 0.7; }
-.section-hidden { display: none; }
+.section-hidden { display: none; }
+
+/* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
+   laid out like a chat message (avatar + text). Slides/fades in when shown; themed. */
+#pf-pick-banner {
+  position: fixed; top: 78px; left: 50%; transform: translateX(-50%);
+  z-index: 30; max-width: min(56ch, calc(100vw - 24px));
+  padding: 10px 36px 10px 12px;
+  background: var(--surface); color: var(--text);
+  border: 1px solid var(--border); border-radius: 10px;
+  box-shadow: 0 6px 24px rgba(0,0,0,.35);
+  font-size: 12px; line-height: 1.45;
+  animation: pf-pick-in .18s ease;
+}
+#pf-pick-banner .pf-pick-row { display: flex; align-items: center; gap: 10px; }
+#pf-pick-banner .pf-pick-avatar {
+  flex: none; width: 30px; height: 30px; border-radius: 50%; font-size: 17px;
+  display: flex; align-items: center; justify-content: center;
+  background: var(--surface-2); border: 1px solid var(--border);
+}
+#pf-pick-banner .pf-pick-msg { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+#pf-pick-banner .pf-pick-label { color: var(--muted); font-size: 11px; }
+#pf-pick-banner .pf-pick-prompt { color: var(--text-strong); font-weight: 600; }
+#pf-pick-close {
+  position: absolute; top: 6px; right: 6px; appearance: none;
+  width: 20px; height: 20px; padding: 0;
+  border: 1px solid var(--border); border-radius: 6px;
+  background: var(--surface-2); color: var(--muted);
+  cursor: pointer; font-size: 13px; line-height: 1;
+  display: flex; align-items: center; justify-content: center;
+}
+#pf-pick-close:hover { color: var(--text-strong); border-color: var(--accent); }
+@keyframes pf-pick-in {
+  from { opacity: 0; transform: translateX(-50%) translateY(-10px); }
+  to   { opacity: 1; transform: translateX(-50%) translateY(0); }
+}
+/* dev aid (request-a-pick mode): preview the prompt banner without an agent */
+#pf-pick-test {
+  position: fixed; left: 12px; bottom: 12px; z-index: 30; appearance: none;
+  padding: 6px 10px; border: 1px solid var(--border); border-radius: 8px;
+  background: var(--surface); color: var(--muted-2); cursor: pointer;
+  font: 12px/1 -apple-system, system-ui, sans-serif;
+  box-shadow: 0 6px 24px rgba(0,0,0,.35);
+}
+#pf-pick-test:hover { color: var(--text); border-color: var(--accent); }

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; },
+  };
+}