partforge 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# 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.
+
+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).
+
+> **Requires a Vite-based app.** partforge is published as plain ESM source and relies
+> on Vite's worker / WASM / CSS import handling.
+
+## Install
+
+```bash
+npm install partforge
+```
+
+## Use
+
+```js
+// app.js
+import { mount } from "partforge";
+import part from "./parts/my-part.js";
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./part-worker.js", import.meta.url), { type: "module", name }),
+});
+
+// part-worker.js
+import { runWorker } from "partforge/worker";
+import part from "./parts/my-part.js";
+runWorker(part);
+```
+
+Test your parts headlessly with `partforge/testing`
+(`createManifoldKernel`, `handle`, `assemblyOverlaps`, `bootOcctKernel`, `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
+boots with no errors. Needs Playwright: `npm i -D playwright && npx playwright install chromium`.
+
+## 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. `src/parts/demo.js` is a minimal worked example; run `npm run dev` and open
+`/demo.html` to see it live.
+
+## License
+
+MIT

package/docs/AUTHORING-PARTS.md

@@ -0,0 +1,272 @@
+# Authoring parts
+
+This app is a small **framework** that turns a declarative **`PartDefinition`** into
+a full parametric-CAD web app: a 3-D viewer, a control panel built from your
+parameter schema, two geometry workers, and STL / STEP / 3MF export. To make a new
+part you write **one script** — geometry build functions + a parameter schema — and
+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).
+- 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).
+
+---
+
+## Quickstart
+
+1. Copy `src/parts/demo.js` to `src/parts/<your-part>.js` and edit it.
+2. Copy the three glue files, repointing them at your part:
+   - `demo.html` → `<your-part>.html`
+   - `src/app-demo.js` → `src/app-<your-part>.js`
+   - `src/demo-worker.js` → `src/<your-part>-worker.js`
+3. `nvm use && npm install` (Node 24), then `npm run dev` and open
+   `http://localhost:5173/<your-part>.html`.
+
+That's the whole loop. The chrome (panel, tabs, viewer, export buttons) is shared —
+your HTML is ~30 lines of structural markup and carries no CSS (the framework
+supplies it via `framework/app.css`, imported by `mount`).
+
+---
+
+## The `PartDefinition` contract
+
+A part is a default-exported object. Full shape (optional fields marked `?`):
+
+```js
+export default {
+  meta: { title, units, background? },     // title string; units e.g. "mm"; background = 0xRRGGBB scene colour
+  parameters,                              // the control-panel schema (array of sections — see below)
+  defaults,                                // flat { paramKey: value } — seeds params + control values
+  derive?,                                 // (p) => d   optional dependent values computed once per build
+  parts: {                                 // named sub-parts; each builds ONE solid
+    <name>: {
+      label?,                              // display name (tabs/progress); defaults to the key
+      build: (k, p, d, onProgress?) => Solid,   // REQUIRED — see kernel API
+      place?: (solid, { view, purpose, p, d }) => Solid,   // optional reposition; default identity
+      views,                               // string[] — which views show this sub-part
+      enabled?: (p) => boolean,            // optional — gate a conditional sub-part
+      export?: { name },                   // filename/object name on export; defaults to the key
+    },
+  },
+  views: { <name>: { label } },            // the view tabs (a view = a set of sub-parts)
+};
+```
+
+**Rules:**
+
+- `build(k, p, d, onProgress?)` returns the **canonical** solid (e.g. at the origin).
+  It is the only required function per sub-part. `p` is `{ ...defaults, ...userParams }`;
+  `d` is `derive(p)` (or `{}`). `onProgress?.("phase")` is optional per-feature progress
+  shown during export — call it before expensive steps.
+- `place(solid, ctx)` is an optional escape hatch for parts whose **display pose differs
+  from their export pose** (e.g. positioning a sub-part in an assembly). `ctx.purpose` is
+  `"display"` or `"export"`; `ctx.view` is the active view. Default is identity, so simple
+  parts omit it. **Display placement must not depend on `view`** — display meshes are built
+  once per sub-part and cached across views (the viewer re-centres per view).
+- `enabled(p)` gates a conditional sub-part (e.g. only present when a feature is on).
+- A view's sub-parts are derived, never hard-coded: those whose `views` include the view
+  and whose `enabled(p)` is true.
+
+---
+
+## Geometry: the kernel / `Solid` API
+
+`build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid`
+handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF) and
+**OCCT/replicad** (exact B-rep — STEP). Contract lives in
+`src/framework/geometry/kernel.js`.
+
+**Kernel — make solids:**
+
+| Call | Result |
+|---|---|
+| `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.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"`.
+**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`).
+
+**`Solid` — combine / transform / export:**
+
+| Call | Result |
+|---|---|
+| `s.cut(tool)` / `s.cutAll(tools[])` | boolean subtract (one / batch) |
+| `s.intersect(other)` | boolean intersection (Manifold; used by collision tests) |
+| `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.volume()` | volume in mm³ (Manifold) |
+| `s.toMesh({ quality })` / `s.toSTL({ quality })` / `s.toIndexedMesh()` | meshes / STL / indexed mesh (3MF) — the framework calls these |
+| `k.toSTEP(named[])` | STEP bytes (OCCT only) — the framework calls this |
+
+You normally only call the *make/combine/transform* ops; the framework handles
+`toMesh`/`toSTL`/`toIndexedMesh`/`toSTEP`. Units are millimetres.
+
+---
+
+## Parameters: the control-panel schema
+
+`parameters` is an **array of sections**; the framework builds the panel from it and
+binds each control to a key in `defaults`. Two section kinds:
+
+**Preset + sliders section:**
+
+```js
+{
+  id: "body",
+  title: "Body",
+  presets: { M3: { od: 8, bore: 3.4, h: 10 }, M5: { od: 12, bore: 5.4, h: 16 } }, // name → param overrides
+  advanced: [                                  // sliders revealed under "Advanced"
+    { key: "od",   label: "Outer diameter", unit: "mm", min: 4, max: 40, step: 0.5 },
+    { key: "bore", label: "Bore",           unit: "mm", min: 1, max: 30, step: 0.1, control: "number" },
+  ],
+}
+```
+
+Each slider/feature control shows an **editable number box** beside it — drag the
+slider or type an exact value (finer than `step` is allowed; typed values clamp to
+`[min, max]`). Optional `control` per parameter: omit it (or `"slider"`) for a slider
++ box; `"number"` for a box only (no slider — handy for precise or wide-range values).
+
+**Feature-toggle section** (checkbox enables a feature + reveals its sliders; `0` = off):
+
+```js
+{
+  id: "flange",
+  title: "Flange",
+  features: [
+    { label: "Base flange", key: "flange_d", on: 16,    // checked → set key to `on`; unchecked → 0
+      sliders: [{ key: "flange_d", label: "Flange diameter", unit: "mm", min: 8, max: 50, step: 1 }] },
+  ],
+}
+```
+
+Every `key` used must exist in `defaults`. (The drum's schema is exported as `SECTIONS`
+in `src/parts/drum/params.js` if you want a large reference.)
+
+---
+
+## Wiring a part into a runnable app
+
+Three tiny glue files per part (copy from the demo). The worker statically imports
+your part, so it can't be injected at runtime — hence the per-part entries.
+
+`src/app-<part>.js`:
+
+```js
+import part from "./parts/<part>.js";
+import { mount } from "partforge";
+mount(part, {
+  // NB: the `new Worker(new URL(...))` MUST stay inline here or Vite won't bundle the worker.
+  createWorker: (name) => new Worker(new URL("./<part>-worker.js", import.meta.url), { type: "module", name }),
+});
+```
+
+`src/<part>-worker.js`:
+
+```js
+import part from "./parts/<part>.js";
+import { runWorker } from "partforge/worker";
+runWorker(part);
+```
+
+`<part>.html` — structural markup only (no CSS; `mount` pulls in partforge's
+stylesheet). `mount` looks up these element IDs:
+
+| ID | Purpose |
+|---|---|
+| `#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"` |
+| `#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
+(`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
+
+> Production deploy builds `index.html` only. Extra `*.html` files are **dev-only**
+> (Vite serves any root HTML in `npm run dev`). To also ship one, add it to
+> `build.rollupOptions.input` in `vite.config.js`.
+
+### Developing against a local (linked) partforge
+
+A normal `npm install partforge` needs no extra config. But if you `npm link` a local
+partforge checkout (to co-develop the framework), it lives **outside your project root**,
+so Vite refuses to serve its files — including the Manifold/OCCT WASM, which fails with a
+403 and the kernel never boots. Allow-list it in your `vite.config.js`:
+
+```js
+server: { fs: { allow: ["./", "../partforge"] } } // path to your linked checkout
+```
+
+(Geometry/asset imports are already worker-safe; this is purely Vite's dev-server file
+access. It's harmless to leave in when partforge is a normal install.)
+
+---
+
+## Testing a part
+
+Tests run under **Node 24** (`nvm use` first; the default shell Node is too old) via
+`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";
+
+const w = await Module(); w.setup();
+const k = createManifoldKernel(w, { quality: "preview" });
+const solid = part.parts.<name>.build(k, part.defaults, part.derive?.(part.defaults) ?? {});
+expect(solid.toMesh().triangles).toBeGreaterThan(0);
+```
+
+**Collision check (assemblies).** `assemblyOverlaps` builds every sub-part of a view in
+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";
+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`
+for exporting through the job loop.
+
+**OCCT tests** (STEP / B-rep parity) boot via `bootOcctKernel()` in `test/occt-kernel.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).
+
+---
+
+## Conventions & gotchas
+
+- **replicad (OCCT) transforms consume their input.** `s.translate/.rotate/.mirror/.cut`
+  delete the operand and return a new solid; never reuse a solid after transforming it.
+  The framework rebuilds each sub-part fresh per job and applies `place` once, which
+  avoids this — follow the same pattern in your own code.
+- **Part modules are DOM-free and side-effect-free** — they import into both the main
+  thread (schema → controls) and the worker (build → kernel).
+- **Units are millimetres** throughout.
+- **Preview vs print quality.** Manifold bakes segment counts in at primitive creation,
+  so the export path uses a separate high-res "print" kernel — your `build` is quality-
+  agnostic; just build the geometry.
+- **Display placement is view-independent** (so meshes cache across views); only
+  `place(..., { purpose: "export" })` may depend on `view`.
+- Keep geometry backend-agnostic (kernel calls only) so it works in both backends; only
+  STEP requires OCCT.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "partforge",
+  "version": "0.1.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",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "src",
+    "docs/AUTHORING-PARTS.md",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.js",
+    "./worker": "./src/framework/worker.js",
+    "./geometry": "./src/framework/geometry/polygon.js",
+    "./testing": "./src/testing.js"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "node scripts/check-app.mjs"
+  },
+  "dependencies": {
+    "fflate": "^0.8.3",
+    "manifold-3d": "^3.5.1",
+    "replicad": "^0.23.1",
+    "replicad-opencascadejs": "^0.23.0",
+    "three": "^0.184.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.49.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

package/src/app-demo.js

@@ -0,0 +1,10 @@
+import demoPart from "./parts/demo.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the demo part (a parametric spacer). Identical wiring to
+// app.js — the only thing that differs per part is which definition you import and
+// which worker entry you point at. `npm run dev`, then open /demo.html.
+mount(demoPart, {
+  createWorker: (name) =>
+    new Worker(new URL("./demo-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/demo-worker.js

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

package/src/framework/app.css

@@ -0,0 +1,141 @@
+/* Shared chrome styles for any part app (panel, tabs, viewbar, download row,
+   busy overlay) + the light/dark palettes. Imported by framework/mount.js, so
+   every part-app gets it; each part's HTML only carries structural markup.
+   See docs/AUTHORING-PARTS.md. */
+
+:root {
+  color-scheme: dark;
+  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
+  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
+  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
+  --accent: #3b82f6; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
+}
+:root[data-theme="light"] {
+  color-scheme: light;
+  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
+  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
+  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
+  --accent: #3b82f6; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
+}
+* { box-sizing: border-box; }
+html, body { margin: 0; height: 100%; overflow: hidden;
+  font: 13px/1.4 -apple-system, system-ui, sans-serif; }
+#app { position: fixed; inset: 0; background: var(--bg); }
+canvas { display: block; }
+
+#panel {
+  position: fixed; top: 12px; left: 12px; width: 252px;
+  max-height: calc(100vh - 24px); overflow-y: auto; z-index: 10;
+  background: var(--surface); border: 1px solid var(--border); border-radius: 10px;
+  padding: 14px; color: var(--text); box-shadow: 0 6px 24px rgba(0,0,0,.35);
+}
+#panel h1 { font-size: 14px; margin: 0 0 2px; }
+#panel .sub { color: var(--muted); font-size: 11px; margin: 0 0 12px; }
+
+.seg { display: flex; gap: 4px; margin-bottom: 12px; }
+.seg button {
+  flex: 1; padding: 7px 0; border: 1px solid var(--border); border-radius: 7px;
+  background: var(--surface-2); color: var(--muted-2); cursor: pointer; font-size: 12px;
+}
+.seg button.on { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+
+.section {
+  border: 1px solid var(--border); border-radius: 8px; padding: 9px 10px;
+  margin-bottom: 8px; background: var(--surface-2);
+}
+.sec-title { font-weight: 600; color: var(--text-strong); margin-bottom: 7px; }
+select.preset {
+  width: 100%; background: var(--input-bg); color: var(--text-2);
+  border: 1px solid var(--border); border-radius: 6px; padding: 5px 7px; font-size: 11px;
+}
+.feat { display: flex; align-items: center; gap: 8px; margin: 6px 0;
+  color: var(--text-2); cursor: pointer; }
+.feat input { cursor: pointer; }
+.feat-group { margin: 2px 0 8px; padding-left: 9px; border-left: 2px solid var(--border); }
+.feat-group.hidden { display: none; }
+.adv-toggle {
+  margin-top: 8px; padding: 3px 0; width: 100%; border: 0; border-radius: 5px;
+  background: transparent; color: var(--muted); cursor: pointer; font-size: 11px;
+  text-align: left;
+}
+.adv-toggle:hover { color: var(--muted-2); }
+.adv.hidden { display: none; }
+.adv { margin-top: 4px; }
+
+.slider { margin: 7px 0; }
+.row { display: flex; justify-content: space-between; align-items: center;
+  margin: 0 0 3px; gap: 8px; }
+.row label { color: var(--muted-2); }
+.row .val { display: flex; align-items: baseline; gap: 4px; flex: none; }
+.row .num {
+  width: 52px; text-align: right; font: inherit; font-variant-numeric: tabular-nums;
+  background: var(--input-bg); color: var(--text-strong);
+  border: 1px solid var(--border); border-radius: 5px; padding: 2px 5px;
+}
+.row .num:focus { outline: none; border-color: var(--accent); }
+.row .num::-webkit-outer-spin-button, .row .num::-webkit-inner-spin-button { -webkit-appearance: none; margin: 0; }
+.row .num { -moz-appearance: textfield; }
+.row .unit { color: var(--muted); font-size: 11px; }
+input[type="range"] { width: 100%; }
+
+button.action {
+  width: 100%; margin-top: 8px; padding: 9px; border: 0; border-radius: 7px;
+  background: var(--accent); color: var(--on-accent); font-weight: 600; cursor: pointer;
+}
+button.ghost { background: var(--border); color: var(--text-2); font-weight: 500; }
+button.action:disabled { opacity: .5; cursor: default; }
+
+.dl { margin-top: 12px; }
+.dl-head { font-weight: 600; color: var(--text-strong); margin-bottom: 6px; }
+.dl-row { display: flex; gap: 6px; }
+.dl-row button {
+  flex: 1; padding: 8px 0; border: 1px solid var(--border); border-radius: 7px;
+  background: var(--surface-2); color: var(--text-2); font-weight: 600;
+  font-size: 12px; cursor: pointer;
+}
+.dl-row button:hover:not(:disabled) { border-color: var(--accent); color: var(--text-strong); }
+.dl-row button:disabled { opacity: .45; cursor: default; }
+#status { margin-top: 10px; min-height: 16px; color: var(--status); font-size: 11px; }
+#status.err { color: var(--err); }
+.hint { margin-top: 8px; color: var(--hint); font-size: 10px; }
+
+/* part tabs, floated top-centre over the viewport */
+#topbar {
+  position: fixed; top: 12px; left: 50%; transform: translateX(-50%);
+  z-index: 15;
+}
+#topbar .seg {
+  margin: 0; padding: 4px; background: var(--surface); border: 1px solid var(--border);
+  border-radius: 9px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
+}
+#topbar .seg button { min-width: 70px; padding: 7px 10px; }
+
+/* viewer controls, top-right */
+#viewbar {
+  position: fixed; top: 12px; right: 12px; z-index: 15;
+  display: flex; gap: 4px; padding: 4px;
+  background: var(--surface); border: 1px solid var(--border);
+  border-radius: 9px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
+}
+#viewbar button {
+  width: 34px; height: 34px; border: 1px solid var(--border); border-radius: 7px;
+  background: var(--surface-2); color: var(--muted-2); cursor: pointer;
+  font-size: 15px; line-height: 1;
+  display: flex; align-items: center; justify-content: center;
+}
+#viewbar button:hover { color: var(--text); }
+#viewbar button.on { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+
+#busy {
+  position: fixed; inset: 0; z-index: 20; pointer-events: none;
+  display: none; flex-direction: column; align-items: center;
+  justify-content: center; gap: 14px;
+}
+#busy.show { display: flex; }
+#busy .ring {
+  width: 46px; height: 46px; border-radius: 50%;
+  border: 4px solid var(--border); border-top-color: var(--accent);
+  animation: spin 0.9s linear infinite;
+}
+#busy .phase { color: var(--text); font-size: 13px; text-shadow: 0 1px 6px rgba(0,0,0,.6); }
+@keyframes spin { to { transform: rotate(360deg); } }

package/src/framework/assembly.js

@@ -0,0 +1,29 @@
+import { viewSubParts } 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
+// `tolerance` (mm³) — i.e. parts that interpenetrate rather than merely touch.
+// Parts meant to fit together (e.g. a block seated in a pocket void) read ~0 and
+// don't trip it. Manifold-only (needs Solid.intersect + Solid.volume); meant for
+// part tests so an author/LLM editing a part sees collisions fail.
+//   → [{ a, b, volume }] 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 overlaps = [];
+  for (let i = 0; i < posed.length; i++) {
+    for (let j = i + 1; j < posed.length; j++) {
+      const volume = posed[i].solid.intersect(posed[j].solid).volume();
+      if (volume > tolerance) overlaps.push({ a: posed[i].name, b: posed[j].name, volume });
+    }
+  }
+  kernel.cleanup?.(); // free the per-check WASM objects
+  return overlaps;
+}