partforge 0.6.1 → 0.8.0

package/README.md

@@ -1,15 +1,62 @@
 # partforge
 
-Turn a declarative **part definition** into a full parametric-CAD web app — a 3-D
-viewer, a control panel, geometry workers, and STL / STEP / 3MF export. You write one
-script (geometry build functions + a parameter schema); partforge renders the app.
+**AI-built parametric CAD for 3D printing.** Describe a part to an AI agent and get a
+*forge* — a self-contained web app for that one part: a 3-D viewer, a control panel with
+just the parameters that matter, and STL / STEP / 3MF export. Share the forge and anyone
+can dial in their own version and print it.
 
-Two geometry backends run in Web Workers: [Manifold](https://github.com/elalish/manifold)
-for fast preview meshes + STL/3MF, and [Replicad](https://replicad.xyz)
-(OpenCASCADE-in-WebAssembly) for exact STEP export. The viewer is [three.js](https://threejs.org).
+A forge isn't a frozen STL. It's open-source code that renders and regenerates the model
+live, so the part stays **editable** — resize it for a different bearing, screw, or motor
+without relearning a heavy CAD tool — and anyone (or their own agent) can read the source
+and extend it.
 
-> **Requires a Vite-based app.** partforge is published as plain ESM source and relies
-> on Vite's worker / WASM / CSS import handling.
+partforge is the engine behind the forge: a small npm framework that an LLM tuned for tool
+use can drive to author, test, and measure a part, then ship it as a browser app.
+
+## See it
+
+- **Live showcase** — https://scottsykora.github.io/partforge/ — example forges (Faceted
+  Planter, Spacer, Filleted Box) you can open, adjust, and export.
+- **A real forge** — https://scottsykora.github.io/Drum-Machine/ — a parametric capstan
+  drum built with partforge for a robotics project.
+
+## Build your own forge
+
+You don't write CAD by hand. Point a tool-using AI agent (Claude Code, or the Claude /
+ChatGPT desktop apps with file access) at this repo and describe what you want:
+
+> Using the partforge framework at https://github.com/scottsykora/partforge, build me a
+> _\<your part\>_ — _\<the dimensions, fits, and features that matter\>_.
+
+Expect a few turns. The first attempt is often rough, but you refine it in plain language
+— "make the bore fit an M3", "add a 2 mm fillet", "thinner walls", "taller by 10" — until
+the part is right. You end up with a forge you can host anywhere and hand to anyone.
+
+## How it works
+
+You — or an agent — write one **part definition**: geometry *build functions* plus a
+*parameter schema*. partforge renders everything else: the 3-D viewer, the control panel,
+the geometry workers, and the export buttons. Each control can carry a description, a
+preset, or be hidden, so the interface stays simple while the part stays deeply adjustable.
+
+Two geometry backends run in Web Workers, and partforge routes each part to whichever it
+needs:
+
+- **[Manifold](https://github.com/elalish/manifold)** — fast preview meshes and STL / 3MF.
+- **[Replicad](https://replicad.xyz)** (OpenCASCADE-in-WebAssembly) — exact B-rep for STEP
+  export and native fillet / chamfer.
+
+The viewer is [three.js](https://threejs.org).
+
+Because a part is just code, an agent can build it **and check its own work**: the
+`partforge/testing` helpers measure volume and bounding box, probe geometry, detect
+self-overlap between sub-parts, and render the model so a multimodal agent can *see* what
+it made. A part can also declare a `verify` block — a manufacturing (DFM) profile plus
+design-intent assertions — that flags problems like a too-thin wall or a part that won't
+fit the print bed before anyone hits export.
+
+> **Requires a Vite-based app.** partforge is published as plain ESM source and relies on
+> Vite's worker / WASM / CSS import handling.
 
 ## Install
 
@@ -35,7 +82,7 @@ runWorker(part);
 ```
 
 Test your parts headlessly with `partforge/testing`
-(`createManifoldKernel`, `handle`, `assemblyOverlaps`, `bootOcctKernel`, `meshVolume`, `bboxSize`).
+(`bootManifoldKernel`, `bootOcctKernel`, `assemblyOverlaps`, `measure`, `verify`, `meshVolume`, `bboxSize`).
 
 **Smoke-test that an app actually boots** (real Chromium, real worker/WASM): `npm run check`
 (or `node scripts/check-app.mjs <entry>.html`) — it loads the app and verifies the kernel
@@ -44,13 +91,12 @@ boots with no errors. Needs Playwright: `npm i -D playwright && npx playwright i
 ## Authoring guide
 
 **[docs/AUTHORING-PARTS.md](docs/AUTHORING-PARTS.md)** is the full guide — the part
-contract, the geometry kernel API, the parameter schema, app wiring, testing, and
-gotchas. See **Designing the control panel** in that guide for how to write descriptions,
-hide internal params, and keep the interface simple while staying deeply adjustable.
-`src/parts/demo.js` is a minimal worked example.
+contract, the geometry kernel API, the parameter schema, app wiring, testing, and gotchas.
+See **Designing the control panel** in that guide for how to write descriptions, hide
+internal params, and keep the interface simple while staying deeply adjustable.
+`src/parts/demo.js` is a minimal worked example; `src/parts/planter.js` is a richer one
+(facets, taper, twist, even walls, an optional feature, and a `verify` block).
 
-**Live showcase:** https://scottsykora.github.io/partforge/ — the landing gallery links
-three live example apps (Faceted Planter, Spacer, Filleted Box), auto-deployed from `main`.
 Locally, `npm run dev` then open `/demo.html`, `/planter.html`, or `/filleted-box.html`.
 
 - **Agent clarification (`request-a-pick`):** an external tool can ask the user to click

package/bin/cli.js

@@ -1,93 +1,113 @@
 #!/usr/bin/env node
+// The partforge CLI — also the agent-facing surface (SKILL.md points here). One
+// async function per command, dispatched from the table at the bottom; flags are
+// parsed strictly per command with util.parseArgs, so a typo'd flag or a missing
+// option value fails loudly instead of being silently ignored.
+import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
-import { resolve } from "node:path";
-import { writeFileSync } from "node:fs";
-import Module from "manifold-3d";
-import { createManifoldKernel } from "../src/framework/geometry/manifold-backend.js";
+import { resolve, dirname } from "node:path";
+import { writeFileSync, mkdirSync } from "node:fs";
 import { detectBackend } from "../src/framework/geometry/probe.js";
 import { bootOcctKernel } from "../src/testing/occt.js";
+import { bootManifoldKernel } from "../src/testing/manifold.js";
 import { measure } from "../src/testing/measure.js";
 import { verify } from "../src/testing/verify.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, ...args] = process.argv;
-const flags = {};
-const positional = [];
-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 USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
 
-// --- 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);
-}
-
-const partPath = positional[0];
-const view = positional[1];
-if (["measure", "render"].includes(cmd) && !partPath) die(`usage: partforge ${cmd} <part-module> [view]`);
+const parse = (args, options, usage) => {
+  try {
+    return parseArgs({ args, options, strict: true, allowPositionals: true });
+  } catch (e) {
+    return die(`${e.message}\n${usage}`);
+  }
+};
 
-if (["measure", "render"].includes(cmd)) {
+async function loadPart(partPath, usage) {
+  if (!partPath) die(usage);
   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`);
+  return part;
+}
 
-  let kernel;
-  if (detectBackend(part) === "occt") {
-    kernel = await bootOcctKernel();
-  } else {
-    const wasm = await Module(); wasm.setup();
-    kernel = createManifoldKernel(wasm, { quality: "preview" });
-  }
+const bootKernel = (part) => (detectBackend(part) === "occt" ? bootOcctKernel() : bootManifoldKernel());
 
-  try {
-    if (cmd === "measure") {
+const commands = {
+  async measure(args) {
+    const usage = "usage: partforge measure <part-module> [view] [--process <profile>] [--no-verify] [--json] [--out <file>]";
+    const { values: flags, positionals: [partPath, view] } = parse(args, {
+      process: { type: "string" },
+      "no-verify": { type: "boolean" },
+      json: { type: "boolean" },
+      out: { type: "string" },
+    }, usage);
+    const part = await loadPart(partPath, usage);
+    const kernel = await bootKernel(part);
+    try {
       const report = measure(kernel, part, view);
       printMeasure(report);
       let vok = true;
-      const processFlag = typeof flags.process === "string" ? flags.process : undefined;
-      if ((part.verify || processFlag) && !flags["no-verify"]) {
-        const v = verify(kernel, part, { process: processFlag, view });
+      if ((part.verify || flags.process) && !flags["no-verify"]) {
+        const v = verify(kernel, part, { process: flags.process, view });
         printVerify(v);
         report.verify = v;
         vok = v.ok;
       }
-      const file = `measure-${slug(report.part)}-${report.view}.json`;
-      writeFileSync(file, JSON.stringify(report, null, 2));
-      console.log(`\nwrote ${file}`);
+      if (flags.out) {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+        console.log(`\nwrote ${flags.out}`);
+      }
       if (flags.json) console.log(JSON.stringify(report, null, 2));
       process.exit(report.ok && vok ? 0 : 1);
-    } else {
-      const views = typeof flags.views === "string" ? flags.views.split(",") : undefined;
+    } catch (e) {
+      die(`measure failed: ${e.message || e}`);
+    }
+  },
+
+  async render(args) {
+    const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>]";
+    const { values: flags, positionals: [partPath, view] } = parse(args, {
+      views: { type: "string" },
+      out: { type: "string" },
+    }, usage);
+    const part = await loadPart(partPath, usage);
+    const kernel = await bootKernel(part);
+    try {
+      const views = flags.views ? 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(`render failed: ${e.message || e}`);
     }
-  } catch (e) {
-    die(`${cmd} failed: ${e.message || e}`);
-  }
-}
+  },
+
+  async "pick-serve"(args) {
+    const usage = "usage: partforge pick-serve [--port N] [--timeout <seconds>]";
+    const { values: flags } = parse(args, { port: { type: "string" }, timeout: { type: "string" } }, usage);
+    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}`);
+    // no exit — the process stays alive serving requests
+  },
+
+  async pick(args) {
+    const usage = 'usage: partforge pick "<prompt>" ["<prompt>" …] [--port N]';
+    const { values: flags, positionals: prompts } = parse(args, { port: { type: "string" } }, usage);
+    if (prompts.length === 0) die(usage);
+    const port = Number(flags.port) || 4518;
+    const out = await requestPicks({ port, prompts }).catch((e) => die(e.message));
+    console.log(formatPickResult(out));
+    process.exit(out.status === "done" ? 0 : 1);
+  },
+};
 
 function printMeasure(r) {
   console.log(`${r.part} / ${r.view}`);
@@ -115,3 +135,7 @@ function printVerify(v) {
   const f = v.failures.length, w = v.warnings.length;
   console.log(`  result: ${f ? `${f} gate failure(s)` : "all gates passed"}${w ? `, ${w} warning(s)` : ""}`);
 }
+
+const [, , cmd, ...args] = process.argv;
+if (!commands[cmd]) die(USAGE);
+await commands[cmd](args);

package/docs/AUTHORING-PARTS.md

@@ -7,13 +7,15 @@ part you write **one script** — geometry build functions + a parameter schema
 the framework does the rest.
 
 - Reusable framework: `src/framework/` (knows nothing about any specific part).
-- Parts: `src/parts/` — e.g. `drum.js` (full, complex) and `demo.js` (minimal).
+- Parts: `src/parts/` — e.g. `planter.js` (full, rich) and `demo.js` (minimal).
 - A part module is **plain data + pure functions**: no DOM, no side effects (it
   loads in both the main thread and a Web Worker).
 
 Two worked examples to read alongside this guide: **`src/parts/demo.js`** (a
-parametric spacer — the smallest complete part) and **`src/parts/drum.js`** (the
-capstan drum — every feature in use).
+parametric spacer — the smallest complete part) and **`src/parts/planter.js`** (a
+faceted planter — facets, taper, twist, even walls, an optional feature, a `derive`,
+and a `verify` block). **`src/parts/filleted-box.js`** is the worked example for the
+OCCT-only fillet/chamfer/shell ops.
 
 ---
 
@@ -88,13 +90,55 @@ 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, { 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.prism(points2D, h, { twist?, scaleTop? })` | extrude a 2-D polygon (or an **arc profile** from `roundedProfile`) from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
+| `k.extrude(profile, h, { twist?, scaleTop? })` | extrude a **polygon-with-holes** region from z=0 in one op — `profile` is `{ outer, holes? }` where each contour is a points array **or an arc profile** (`roundedProfile`, for true STEP fillets), or a bare points array / arc profile for outer-only; same `twist`/`scaleTop` as `prism` (both backends) |
+| `k.loft(rings, { ruled?, closed? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls |
+| `k.sweep(profile2D, path3D, { cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested |
 | `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) |
 | `k.union(solids[])` | boolean union |
 
-2-D polygon helpers for `prism`: `import { piePolygon, hexPolygon } from "partforge/geometry"`.
+**`loft` rings** — each ring is `{ polygon:[[x,y],…] | sides+radius, z, rotate?, scale? }`
+(all rings must share the same vertex count; `rotate` is degrees about Z, `scale` is a
+number or `[sx,sy]`). Author rings CCW and ordered by ascending `z` (the `regularPolygon`
+/ `polygon.js` helpers are already CCW); loft self-corrects a fully-inverted result so
+CW-wound or descending-z rings still export a valid outward solid. (Arc profiles from
+`roundedProfile` are **not** accepted as loft rings yet — a ring must be a point array;
+use `prism`/`extrude` for true-arc STEP export.) **`sweep`** takes the same CCW
+`polygon.js` outline as its `profile2D` and a plain `[[x,y,z],…]` point list as its
+`path3D`; the profile stays perpendicular to the path (a rotation-minimizing frame), with
+sharp mitered corners by default or `cornerRadius` fillets. Worked snippets:
+
+```js
+// a square tube (extrude a region with a hole) — one op, no boolean cut
+k.extrude({ outer: roundedRectPolygon(40, 30, 4), holes: [circleProfile(6)] }, 10);
+
+// a tapered, twisting faceted vase wall (see src/parts/faceted-vase.js)
+const rings = [];
+for (let i = 0; i <= 24; i++) { const t = i / 24;
+  rings.push({ sides: 6, radius: 30 - 8 * t, z: 120 * t, rotate: 90 * t }); }
+k.loft(rings);                          // ruled walls, capped ends
+
+// a cable/hose: sweep a circle along a 3-D polyline, with rounded bends
+k.sweep(circleProfile(3), [[0, 0, 0], [0, 0, 20], [15, 0, 20]], { cornerRadius: 5 });
+
+// round every corner of any CCW outline, then extrude/loft/prism it
+k.prism(filletPolygon(bracketOutline, 3), 4);       // tessellated corners (faceted in STEP)
+k.prism(roundedProfile(bracketOutline, 3), 4);      // true CIRCLE corners in STEP export
+```
+
+2-D polygon helpers for `prism`/`extrude`/`loft`: `import { piePolygon, hexPolygon,
+regularPolygon, roundedRectPolygon, starPolygon, circleProfile, filletPolygon,
+roundedProfile } from "partforge/geometry"`. `filletPolygon(points, r, { segs? })` rounds
+every corner of a CCW polygon (per-corner radius clamped so neighbouring arcs never overlap)
+and returns points usable by `prism`/`extrude`/`loft` on both backends — but it **bakes each
+corner into line facets**, so STEP corners are faceted. `roundedProfile(points, r | r[])`
+rounds corners the same way but keeps them **mathematically true** — it carries the arc
+symbolically so STEP export gets real circular edges. Use it for `prism`/`extrude` (not yet
+`loft` — arc rings are rejected there in v1). A scalar `r` rounds every corner; a per-corner
+`r[]` (length = points) rounds selectively (a `0`, a zero-length edge, or a straight/180°
+corner stays sharp).
 **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main
 entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker
 (importing the main entry there throws `document is not defined`).
@@ -114,6 +158,7 @@ entry pulls in the DOM viewer/controls, and your build functions run in a Web Wo
 | `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.label(name)` | name this solid's surface for hover/pick feature attribution; survives transforms + booleans; same name on several solids merges into one feature |
 | `s.boundingBox()` | `{ min, max, center, size }` axis-aligned bounds (query) |
 | `s.volume()` | volume in mm³ (Manifold) |
 | `s.toMesh({ quality })` / `s.toSTL({ quality })` / `s.toIndexedMesh()` | meshes / STL / indexed mesh (3MF) — the framework calls these |
@@ -157,6 +202,31 @@ magic vectors. Three habits:
 The bare `rotate(deg, center, axis)` remains available as the low-level primitive for
 anything `rotateX/Y/Z`/`rotateAbout` can't express, but prefer the vocabulary above.
 
+### Naming features (`.label()`)
+
+Give build-step solids human-readable names — the viewer's hover tooltip, the
+highlight, and pick selections all use them, so you, the app user, and an agent
+share the same vocabulary ("Make the Drainage hole 10 mm").
+
+```js
+const body = k.prism(d.outerPts, p.height, { scaleTop: p.taper }).label("Faceted wall");
+let s = body.cut(cavity.label("Cavity"));
+if (p.drain > 0) s = s.cut(k.cylinder(d.drainR, d.drainR, p.floor + 4).at([0, 0, -2]).label("Drainage hole"));
+```
+
+- A label names the solid's **surface** wherever it survives into the final part —
+  a cutting tool's label lands on the faces it leaves behind (the hole's wall).
+- Label **after** shaping compound tools (e.g. after an `intersect` clip) and
+  either before or after transforms — labels ride through `at`/`rotate`/etc.
+- The **same label on several solids merges into one feature** — label a pattern
+  of four holes `"Mounting holes"` and they hover/highlight as one.
+- Unlabeled geometry falls back to the sub-part's `label`. Faces created by
+  `fillet`/`chamfer`/`shell` are new surfaces, so they use the fallback too.
+- Works on both backends. On OCCT each label keeps a geometry snapshot for
+  mesh-time classification — label a handful of features, not hundreds.
+- Names should describe intent ("Drainage hole", not "cylinder2"); keep them
+  unique per sub-part unless you want the merge behavior.
+
 ### Caching & determinism
 
 The preview kernel memoizes geometry by content hash, so editing a parameter only
@@ -167,7 +237,12 @@ 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.
+it hashes from its own arguments and never exposes its internals to the cache. The heavy
+primitives `loft`, `sweep`, `extrude`, `prism`, and `revolve` are cached this way too:
+their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`rotate`/`scale`,
+`sweep`'s profile points/path points/`cornerRadius`/`closed`, `extrude`'s holes, an arc
+profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so
+changing any of them is a fresh cache node while an identical rebuild is a hit.
 
 ---
 
@@ -348,13 +423,12 @@ stylesheet). `mount` looks up these element IDs:
 |---|---|
 | `#app` | viewer canvas mounts here |
 | `#controls` | control panel is built into this |
-| `#part` | view-tab bar: one `<button data-part="<view>">` per view, the active one with `class="on"` |
+| `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
 | `#viewbar` with `#pause` / `#reframe` / `#theme` | optional viewer controls (omit any you don't want) |
 
-Copy `demo.html` and change the title, the `#part` buttons (one per view), the panel
-heading, and the `<script src>`. Two workers are spawned from your one worker entry
+Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
 (`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
 
 > Production deploy builds `index.html` only. Extra `*.html` files are **dev-only**
@@ -383,12 +457,10 @@ Tests run under **Node 24** (`nvm use` first; the default shell Node is too old)
 `npx vitest run`. Build geometry directly off your part with a Manifold kernel:
 
 ```js
-import Module from "manifold-3d";
-import { createManifoldKernel } from "../../src/framework/geometry/manifold-backend.js";
-import part from "../../src/parts/<part>.js";
+import { bootManifoldKernel } from "partforge/testing";
+import part from "../src/parts/<part>.js";
 
-const w = await Module(); w.setup();
-const k = createManifoldKernel(w, { quality: "preview" });
+const k = await bootManifoldKernel();
 const solid = part.parts.<name>.build(k, part.defaults, part.derive?.(part.defaults) ?? {});
 expect(solid.toMesh().triangles).toBeGreaterThan(0);
 ```
@@ -398,20 +470,19 @@ its assembly pose and returns any interpenetrating pair with its overlap volume
 parts meant to fit (e.g. seated in a pocket) read ~0 and don't trip it:
 
 ```js
-import { assemblyOverlaps } from "../../src/framework/assembly.js";
+import { assemblyOverlaps } from "partforge/testing";
 test("assembly has no interpenetrating parts", () => {
   expect(assemblyOverlaps(k, part, "<view>", {})).toEqual([]); // [{a,b,volume}] on failure
 });
 ```
 
-See `test/parts/drum-assembly.test.js` for a real example, and `test/framework/jobs.test.js`
+See `test/framework/assembly.test.js` for a real example, and `test/framework/jobs.test.js`
 for exporting through the job loop.
 
-**OCCT tests** (STEP / B-rep parity) boot via `bootOcctKernel()` in `test/occt-kernel.js`.
+**OCCT tests** (STEP / B-rep) boot the OCCT kernel with `bootOcctKernel()` from
+`partforge/testing` (in a `beforeAll`) — see `test/occt-backend.test.js`.
 **OCCT and Manifold must not boot in the same process** — keep OCCT-booting tests in their
-own files (vitest isolates files). For Manifold↔OCCT volume parity, see `test/parity.test.js`
-+ the `test/fixtures/occt-volumes.json` fixture (regenerate with
-`node scripts/gen-occt-fixtures.mjs` after a geometry change).
+own files (vitest isolates files).
 
 ---
 
@@ -424,11 +495,12 @@ check it without opening the app:
     npx partforge measure src/parts/<part>.js [view]      # geometric facts
     npx partforge render  src/parts/<part>.js [view]       # canonical-angle PNGs
 
-`measure` prints a report and writes `measure-<part>-<view>.json`: per sub-part
-and per view it reports bounding box, volume, surface area, triangle count,
-whether the solid is watertight, and the number of through-holes (genus), plus an
-assembly overlap check. It exits non-zero if any sub-part isn't watertight or any
-parts interpenetrate — so it doubles as a CI/agent gate. (Manifold output is
+`measure` prints a report: per sub-part and per view it reports bounding box,
+volume, surface area, triangle count, whether the solid is watertight, and the
+number of through-holes (genus), plus an assembly overlap check. It exits non-zero
+if any sub-part isn't watertight or any parts interpenetrate — so it doubles as a
+CI/agent gate. Add `--json` to also dump the report as JSON on stdout, or
+`--out report.json` to write it to a file (nothing is written otherwise). (Manifold output is
 manifold by construction, so `watertight` is mainly a build-sanity check for
 empty/degenerate results; `holes` is the informative topology number.)
 
@@ -536,7 +608,7 @@ See `src/parts/filleted-box.js` for the worked example.
 
 **Automatic backend selection.** Before building, the framework runs a geometry-free *probe*
 of your `build` to see whether it uses a CAD-only op, and routes accordingly — Manifold for
-everything else (so sweep-heavy parts like the drum stay fast). Force it with
+everything else (so sweep-heavy parts, e.g. helical grooves, stay fast). Force it with
 `meta.backend: "occt" | "manifold"` if you ever need to. Because an OCCT part is built
 entirely on OCCT, its fillets are exact in the STEP **and** present in the printed STL.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.6.1",
+  "version": "0.8.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/app-faceted-vase.js

@@ -0,0 +1,10 @@
+import vasePart from "./parts/faceted-vase.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the faceted vase part. Identical wiring to app-planter.js —
+// only the imported definition and the worker entry differ per part. `npm run dev`,
+// then open /faceted-vase.html.
+mount(vasePart, {
+  createWorker: (name) =>
+    new Worker(new URL("./faceted-vase-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/faceted-vase-worker.js

@@ -0,0 +1,3 @@
+import part from "./parts/faceted-vase.js";
+import { runWorker } from "./framework/worker.js";
+runWorker(part);

package/src/framework/app.css

@@ -204,6 +204,18 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 .irrelevant:hover { opacity: 0.7; }
 .section-hidden { display: none; }
 
+/* hover feature-label tooltip (selection/hover.js) */
+#pf-hover-tip {
+  position: fixed; z-index: 30; pointer-events: none; display: none;
+  padding: 4px 9px; border-radius: 6px; max-width: 260px;
+  background: var(--surface); border: 1px solid var(--border);
+  color: var(--text-strong); font-size: 12px; line-height: 1.35;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, .25);
+}
+#pf-hover-tip.show { display: block; }
+#pf-hover-tip .pf-hover-sub { color: var(--muted); font-size: 11px; margin-left: 7px; }
+#pf-hover-tip .pf-hover-sub:empty { 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 {
@@ -238,3 +250,17 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   from { opacity: 0; transform: translateX(-50%) translateY(-10px); }
   to   { opacity: 1; transform: translateX(-50%) translateY(0); }
 }
+
+/* ?pick clipboard mode: a bottom-left toggle button + a transient token toast. */
+#pf-pick {
+  position: fixed; left: 12px; bottom: 12px; z-index: 9999;
+  font: 12px system-ui, sans-serif; padding: 6px 10px; cursor: pointer;
+}
+#pf-pick.on { outline: 2px solid #ffcc33; }
+#pf-pick-toast {
+  position: fixed; left: 12px; bottom: 48px; z-index: 9999; max-width: 60ch;
+  font: 12px ui-monospace, monospace; padding: 6px 10px; border-radius: 4px;
+  background: rgba(20,24,29,0.92); color: #d8e0ea;
+  white-space: pre-wrap; word-break: break-word; display: none;
+}
+#pf-pick-toast.show { display: block; }

package/src/framework/assembly.js

@@ -1,4 +1,4 @@
-import { viewSubParts } from "./jobs.js";
+import { viewSubParts, resolveParams, buildPosed } from "./jobs.js";
 
 // Collision check for an assembled view: build each sub-part in its display
 // (assembly) pose and return the pairs whose solid-intersection volume exceeds
@@ -8,14 +8,11 @@ import { viewSubParts } from "./jobs.js";
 // part tests so an author/LLM editing a part sees collisions fail.
 //   → [{ a, b, volume }] for each offending pair (empty = no collisions)
 export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1 } = {}) {
-  const p = { ...part.defaults, ...params };
-  const d = part.derive ? part.derive(p) : {};
-  const posed = viewSubParts(part, view, p).map((name) => {
-    const sp = part.parts[name];
-    let solid = sp.build(kernel, p, d);
-    if (sp.place) solid = sp.place(solid, { view, purpose: "display", p, d });
-    return { name, solid };
-  });
+  const { p, d } = resolveParams(part, params);
+  const posed = viewSubParts(part, view, p).map((name) => ({
+    name,
+    solid: buildPosed(kernel, part, name, { purpose: "display", view, p, d }),
+  }));
 
   const overlaps = [];
   for (let i = 0; i < posed.length; i++) {

package/src/framework/download.js

@@ -0,0 +1,23 @@
+import { zipSync } from "fflate";
+
+// Browser file-download helpers. Pure DOM/Blob utilities with no app state — the
+// worker produces the bytes; these just hand them to the browser as a download.
+
+// Trigger a download of one binary blob under `filename`.
+export function triggerDownload(data, filename, mime) {
+  const url = URL.createObjectURL(new Blob([data], { type: mime }));
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+// Download a set of built parts: a single part downloads directly; multiple parts
+// are bundled into one flat, store-only (level 0) zip named `zipName`.
+export function downloadParts({ parts, ext, mime }, zipName) {
+  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime);
+  const entries = {};
+  for (const p of parts) entries[`${p.name}.${ext}`] = new Uint8Array(p.data);
+  triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip");
+}