partforge 0.1.0 → 0.4.0

package/README.md

@@ -45,7 +45,9 @@ boots with no errors. Needs Playwright: `npm i -D playwright && npx playwright i
 
 **[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
+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; run `npm run dev` and open
 `/demo.html` to see it live.
 
 ## License

package/bin/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+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 { 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";
+
+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 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]);
+}
+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 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" });
+}
+
+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}`);
+}
+
+function printMeasure(r) {
+  console.log(`${r.part} / ${r.view}`);
+  for (const s of r.subparts) {
+    const wt = s.watertight === null ? "watertight n/a" : (s.watertight ? "watertight ✓" : "NOT watertight ✗");
+    const holes = s.holes === null ? "holes n/a" : `holes ${s.holes}`;
+    console.log(`  ${s.name}  bbox ${s.bbox.map((n) => n.toFixed(1)).join("×")}  ` +
+      `vol ${(s.volume / 1000).toFixed(2)}cm³  area ${(s.surfaceArea / 100).toFixed(1)}cm²  ` +
+      `tris ${s.triangleCount}  ${wt}  ${holes}`);
+  }
+  const a = r.aggregate;
+  console.log(`  ── view  bbox ${a.bbox.map((n) => n.toFixed(1)).join("×")}  vol ${(a.volume / 1000).toFixed(2)}cm³  tris ${a.triangleCount}`);
+  console.log(`  overlaps: ${r.overlaps.length ? r.overlaps.map((o) => `${o.a}×${o.b} (${o.volume.toFixed(1)}mm³)`).join(", ") : "none"}`);
+}

package/docs/AUTHORING-PARTS.md

@@ -50,6 +50,7 @@ export default {
       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
+      display?: { color?, opacity? },      // optional viewer-only override (0xRRGGBB / 0..1) — e.g. a reference/ghost part
       export?: { name },                   // filename/object name on export; defaults to the key
     },
   },
@@ -87,7 +88,9 @@ 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) |
 | `k.union(solids[])` | boolean union |
 
@@ -105,6 +108,9 @@ 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) |
 | `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 |
@@ -112,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
@@ -151,8 +169,112 @@ slider or type an exact value (finer than `step` is allowed; typed values clamp
 }
 ```
 
-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.)
+Every `key` used must exist in `defaults`. `src/parts/demo.js` is the worked example for
+everything below.
+
+**Control metadata (optional — on any control def, feature, or section):**
+
+- `description` — a CommonMark string shown in a click-open **ⓘ** popover beside the
+  label. Supports **bold/italic**, lists, `code`, links, and images (for diagrams);
+  links open in a new tab and the rendered HTML is sanitized. Write one for every
+  control — see "A description for every control" below.
+- `hidden: true` — omits the control/feature/section from the panel. Its `key` must still
+  exist in `defaults` and still drives the geometry: use it for internal constants the
+  end user shouldn't edit (it is *no UI*, not *no parameter*). A section left with no
+  presets and no visible controls doesn't render at all.
+
+```js
+advanced: [
+  { key: "od", label: "Outer diameter", unit: "mm", min: 4, max: 40, step: 0.5,
+    description: "Barrel OD. Keep it larger than the bore so a wall remains. See the [guide](https://example.com)." },
+  { key: "wall_seg", min: 8, max: 256, step: 1, hidden: true,   // internal constant; no UI, still in defaults
+    description: "Facet count — fixed by the design." },
+],
+```
+
+---
+
+## Designing the control panel
+
+A good part exposes a **simple** interface — a handful of controls most users will
+touch — while still giving deep, correct adjustability underneath. `src/parts/demo.js`
+is the worked example for the patterns below.
+
+### Procedural & parametric parts
+
+Drive many features from a few controls, so tweaking one control reshapes the part
+coherently:
+
+- **`derive(p) => d`** computes shared/dependent values once per build; sub-part `build`
+  functions read `d`. Put the "design intent" math here — clearances, ratios, wall
+  thicknesses — so a single input feeds everything downstream. In the demo, `derive`
+  turns the nominal `bore` into `boreR` (with a fixed print clearance) and `h` into the
+  cut-tool height `cutH`; `build(k, p, d)` reads those.
+- **Reuse a param `key`** across sub-parts/features so one slider moves all of them.
+- **`enabled(p)`** gates a whole sub-part on a toggle param (the part appears/disappears
+  with the control).
+
+### Progressive disclosure (simple, but deep)
+
+Tier the controls so the default view is uncluttered:
+
+1. **Presets** for the common cases — the first thing most users pick.
+2. A **few primary sliders** for the dimensions users change most.
+3. **`Advanced`** (the collapsible block) for the rest.
+4. **`hidden`** for internal constants the end user shouldn't edit.
+
+Aim for a panel with a few visible controls that still exposes the full design when
+someone opens Advanced.
+
+### A description for every control
+
+Give every section and control a `description`. Keep each one short and make it cover:
+
+- **what** the control does,
+- its **units**,
+- a **sensible range** (and what's typical),
+- **when it matters** (what it interacts with).
+
+Use Markdown links or images for diagrams and deeper reference. These are the popovers
+end users rely on — treat writing them as part of authoring the control, not an
+afterthought.
+
+### The relevance-aware panel
+
+The panel updates itself to match what's on screen: a **section is hidden** when none of
+its controls affect the active view's visible parts, and a **control is dimmed** (but
+still usable) when it doesn't currently affect them — recomputed as the view and the
+parameters change. You don't wire this up; it's automatic. To get the most from it:
+
+- Group controls into **sections by the sub-parts they affect**, so whole sections drop
+  away in views that don't use them.
+- Scope a parameter to the **views/sub-parts that read it** — a control read by no
+  on-screen part shows dimmed, which is a useful signal that it's vestigial or
+  misplaced.
+
+---
+
+## Profiles & patterns
+
+Pure helpers from `partforge/geometry` (no backend dependency):
+
+**2-D profiles** (CCW point arrays for `k.prism` / `k.revolve`):
+`roundedRectPolygon(w,h,r)`, `regularPolygon(n,r,{flat})`, `ellipsePolygon(rx,ry)`,
+`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 })`.
+
+```js
+const hole = k.cylinder(2, 2, 20).translate([20, 0, 0]);
+body = body.cutAll(circularPattern(hole, 8, { axis: "Z" }));   // 8 bolt holes on a 40mm circle
+```
 
 ---
 
@@ -254,6 +376,81 @@ own files (vitest isolates files). For Manifold↔OCCT volume parity, see `test/
 
 ---
 
+## Verifying a part headlessly (render + measure)
+
+Once the package is installed you get two CLI commands that build your part in
+pure Node (no dev server, no browser) so you — or an LLM authoring the part — can
+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
+manifold by construction, so `watertight` is mainly a build-sanity check for
+empty/degenerate results; `holes` is the informative topology number.)
+
+`render` writes one PNG per angle (`iso`, `front`, `top` by default; choose with
+`--views iso,front`, output dir with `--out`) to `render/`. The view defaults to
+the part's first declared view.
+
+The `measure` function is also exported for vitest (boot a Manifold kernel as in
+"Testing a part", then `measure(kernel, part, "<view>")`):
+
+    import { measure } from "partforge/testing";
+    test("part is sound", () => {
+      const r = measure(kernel, part, "<view>");
+      expect(r.ok).toBe(true);
+      expect(r.subparts[0].holes).toBe(1);   // e.g. expects one bore
+    });
+
+---
+
+## Fillet & chamfer (automatic OCCT backend)
+
+Two backends build your part: **Manifold** (fast meshes — preview, STL, 3MF) and
+**OCCT/replicad** (exact B-rep — STEP). Most parts run on Manifold. But Manifold has no
+fillet, so if your `build` calls a **CAD-only op** the framework automatically routes the
+whole part to OCCT — no declaration needed:
+
+| Op | Meaning |
+|---|---|
+| `s.fillet(radius, selector?)` | round edges (curve-following, exact) |
+| `s.chamfer(distance, selector?)` | bevel edges |
+| `s.shell(thickness, openFaces)` | hollow inward, wall = `thickness`; `openFaces` selector (`{inPlane,at}`/`{dir}`/`{near}`) chooses which face(s) to open. Closed (no-open-face) hollows are not supported. |
+
+`selector` chooses which edges (omit it for **all** edges):
+
+- `{ dir: "X"｜"Y"｜"Z" }` — edges running along an axis (e.g. `{dir:"Z"}` = the vertical edges)
+- `{ inPlane: "XY"｜"XZ"｜"YZ", at }` — edges lying in a plane (e.g. base edges: `{inPlane:"XY", at:0}`)
+- `{ near: [x,y,z] }` — edges passing through a point
+- a raw `(edgeFinder) => edgeFinder` replicad finder, for anything fancier
+
+```js
+let s = k.box([0,0,0],[40,30,16]);
+s = s.fillet(3, { dir: "Z" });            // round the 4 vertical edges
+s = s.chamfer(1, { inPlane: "XY", at: 0 }); // bevel the base
+```
+
+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
+`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.
+
+> Trade-off: OCCT is much slower on heavy swept geometry (helical grooves), so don't reach for
+> `fillet`/`chamfer` on a sweep-heavy part — design those edges in, or keep the part on Manifold.
+
+> `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT parts (Manifold-only
+> topology); `render` works on both.
+
+---
+
 ## Conventions & gotchas
 
 - **replicad (OCCT) transforms consume their input.** `s.translate/.rotate/.mirror/.cut`

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "partforge",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scottsykora/partforge.git"
+  },
+  "homepage": "https://github.com/scottsykora/partforge#readme",
+  "bugs": "https://github.com/scottsykora/partforge/issues",
   "engines": {
     "node": ">=24"
   },
   "files": [
     "src",
+    "bin",
     "docs/AUTHORING-PARTS.md",
     "README.md"
   ],
@@ -18,6 +25,9 @@
     "./geometry": "./src/framework/geometry/polygon.js",
     "./testing": "./src/testing.js"
   },
+  "bin": {
+    "partforge": "./bin/cli.js"
+  },
   "scripts": {
     "dev": "vite",
     "build": "vite build",
@@ -27,13 +37,17 @@
     "check": "node scripts/check-app.mjs"
   },
   "dependencies": {
+    "dompurify": "^3.4.11",
     "fflate": "^0.8.3",
     "manifold-3d": "^3.5.1",
+    "marked": "^18.0.5",
+    "pngjs": "^7.0.0",
     "replicad": "^0.23.1",
     "replicad-opencascadejs": "^0.23.0",
     "three": "^0.184.0"
   },
   "devDependencies": {
+    "happy-dom": "^20.10.6",
     "playwright": "^1.49.0",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"

package/src/app-filleted-box.js

@@ -0,0 +1,7 @@
+import part from "./parts/filleted-box.js";
+import { mount } from "./framework/index.js";
+
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./filleted-box-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/filleted-box-worker.js

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

package/src/framework/app.css

@@ -138,4 +138,29 @@ button.action:disabled { opacity: .5; cursor: default; }
   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); } }
+@keyframes spin { to { transform: rotate(360deg); } }
+
+/* info glyph + description popover */
+.info {
+  appearance: none; border: none; background: none; cursor: pointer;
+  color: var(--muted); font-size: 12px; line-height: 1; padding: 0 0 0 5px;
+  vertical-align: middle;
+}
+.info:hover { color: var(--text-2); }
+.info:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+.popover {
+  position: fixed; z-index: 50; max-width: 280px; max-height: 50vh; overflow: auto;
+  background: var(--surface); color: var(--text); border: 1px solid var(--border);
+  border-radius: 8px; padding: 10px 12px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
+  font-size: 12px; line-height: 1.5;
+}
+.popover[hidden] { display: none; }
+.popover img { max-width: 100%; height: auto; border-radius: 4px; }
+.popover a { color: var(--accent); }
+.popover p:first-child { margin-top: 0; }
+.popover p:last-child { margin-bottom: 0; }
+
+/* relevance: controls/sections that don't affect the on-screen parts */
+.irrelevant { opacity: 0.45; }
+.irrelevant:hover { opacity: 0.7; }
+.section-hidden { display: none; }