partforge 0.6.1 → 0.7.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.
 
 ---
 
@@ -114,6 +116,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 +160,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
@@ -348,13 +376,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 +410,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 +423,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 +448,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 +561,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.7.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/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");
+}

package/src/framework/geometry/feature-attribution.js

@@ -0,0 +1,102 @@
+// Pure classification math for OCCT feature labels. The OCCT backend meshes each
+// labeled solid snapshot into a triangle soup; a face of the RESULT mesh belongs to
+// a label when its sampled triangle centroids all lie on that soup's surface (a cut
+// face lies exactly on its tool's surface, up to the two meshes' tolerances).
+// No OCCT, no three.js — unit-testable with hand-built soups.
+
+// Result mesh (preview) tolerance 0.1 + snapshot mesh tolerance 0.1 + slack.
+const DEFAULT_TOL = 0.35; // mm — surfaces closer than this to another labeled surface can misattribute
+const SAMPLES_PER_FACE = 4;
+
+// Distance from point p to triangle (a,b,c) — the classic region-based projection.
+export function pointTriDist(p, a, b, c) {
+  const sub = (u, v) => [u[0] - v[0], u[1] - v[1], u[2] - v[2]];
+  const dot = (u, v) => u[0] * v[0] + u[1] * v[1] + u[2] * v[2];
+  const ab = sub(b, a), ac = sub(c, a), ap = sub(p, a);
+  const d1 = dot(ab, ap), d2 = dot(ac, ap);
+  if (d1 <= 0 && d2 <= 0) return Math.hypot(...ap);                 // vertex a
+  const bp = sub(p, b);
+  const d3 = dot(ab, bp), d4 = dot(ac, bp);
+  if (d3 >= 0 && d4 <= d3) return Math.hypot(...bp);                // vertex b
+  const vc = d1 * d4 - d3 * d2;
+  if (vc <= 0 && d1 >= 0 && d3 <= 0) {                              // edge ab
+    const t = d1 / (d1 - d3);
+    return Math.hypot(...sub(p, [a[0] + ab[0] * t, a[1] + ab[1] * t, a[2] + ab[2] * t]));
+  }
+  const cp = sub(p, c);
+  const d5 = dot(ab, cp), d6 = dot(ac, cp);
+  if (d6 >= 0 && d5 <= d6) return Math.hypot(...cp);                // vertex c
+  const vb = d5 * d2 - d1 * d6;
+  if (vb <= 0 && d2 >= 0 && d6 <= 0) {                              // edge ac
+    const t = d2 / (d2 - d6);
+    return Math.hypot(...sub(p, [a[0] + ac[0] * t, a[1] + ac[1] * t, a[2] + ac[2] * t]));
+  }
+  const va = d3 * d6 - d5 * d4;
+  if (va <= 0 && d4 - d3 >= 0 && d5 - d6 >= 0) {                    // edge bc
+    const t = (d4 - d3) / (d4 - d3 + (d5 - d6));
+    const bc = sub(c, b);
+    return Math.hypot(...sub(p, [b[0] + bc[0] * t, b[1] + bc[1] * t, b[2] + bc[2] * t]));
+  }
+  const denom = 1 / (va + vb + vc);                                  // interior
+  const v = vb * denom, w = vc * denom;
+  return Math.hypot(...sub(p, [a[0] + ab[0] * v + ac[0] * w, a[1] + ab[1] * v + ac[1] * w, a[2] + ab[2] * v + ac[2] * w]));
+}
+
+const centroid = (V, T, t) => {
+  const i = T[t * 3] * 3, j = T[t * 3 + 1] * 3, k = T[t * 3 + 2] * 3;
+  return [(V[i] + V[j] + V[k]) / 3, (V[i + 1] + V[j + 1] + V[k + 1]) / 3, (V[i + 2] + V[j + 2] + V[k + 2]) / 3];
+};
+
+function distToSoup(p, soup) {
+  const V = soup.vertices, T = soup.triangles;
+  let best = Infinity;
+  for (let t = 0; t < T.length / 3; t++) {
+    const a = [V[T[t * 3] * 3], V[T[t * 3] * 3 + 1], V[T[t * 3] * 3 + 2]];
+    const b = [V[T[t * 3 + 1] * 3], V[T[t * 3 + 1] * 3 + 1], V[T[t * 3 + 1] * 3 + 2]];
+    const c = [V[T[t * 3 + 2] * 3], V[T[t * 3 + 2] * 3 + 1], V[T[t * 3 + 2] * 3 + 2]];
+    const d = pointTriDist(p, a, b, c);
+    if (d < best) best = d;
+  }
+  return best;
+}
+
+// resultMesh: replicad ShapeMesh {vertices, triangles, faceGroups}; soups: labeled
+// snapshots meshed by the caller. Returns {} when attribution isn't possible.
+export function classifyFaceGroups(resultMesh, soups, tol = DEFAULT_TOL) {
+  const groups = resultMesh.faceGroups;
+  const nTri = resultMesh.triangles.length / 3;
+  if (!groups?.length || !soups.length) return {};
+
+  // faceGroups start/count units differ across replicad versions: triangle counts
+  // sum to nTri, index counts to nTri*3. Detect which this is.
+  const total = groups.reduce((s, g) => s + g.count, 0);
+  const div = total === nTri * 3 ? 3 : 1;
+
+  const indexOf = new Map(); // label -> 1-based feature index (same-label merge)
+  const features = [];
+  const featureIds = new Uint16Array(nTri);
+
+  for (const g of groups) {
+    const start = g.start / div, count = g.count / div;
+    if (count <= 0) continue; // degenerate group: no triangles, nothing to attribute
+    // sample a few spread triangles of the face
+    const picks = [];
+    const denom = Math.max(1, Math.min(SAMPLES_PER_FACE, count) - 1);
+    for (let s = 0; s < Math.min(SAMPLES_PER_FACE, count); s++) {
+      picks.push(start + Math.floor((s * (count - 1)) / denom));
+    }
+    // last matching soup wins (most recently applied label)
+    let winner = null;
+    for (const soup of soups) {
+      const onSurface = picks.every(
+        (t) => distToSoup(centroid(resultMesh.vertices, resultMesh.triangles, t), soup) <= tol
+      );
+      if (onSurface) winner = soup.label;
+    }
+    if (winner == null) continue;
+    let fi = indexOf.get(winner);
+    if (fi === undefined) { features.push(winner); fi = features.length; indexOf.set(winner, fi); }
+    for (let t = start; t < start + count; t++) featureIds[t] = fi;
+  }
+  return features.length ? { featureIds, features } : {};
+}