partforge 0.1.0 → 0.3.3

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
     },
   },
@@ -88,6 +89,8 @@ 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.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,8 @@ 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.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 |
@@ -151,8 +156,108 @@ 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).
+
+**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 +359,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,18 @@
 {
   "name": "partforge",
-  "version": "0.1.0",
+  "version": "0.3.3",
   "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 +22,9 @@
     "./geometry": "./src/framework/geometry/polygon.js",
     "./testing": "./src/testing.js"
   },
+  "bin": {
+    "partforge": "./bin/cli.js"
+  },
   "scripts": {
     "dev": "vite",
     "build": "vite build",
@@ -27,13 +34,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; }

package/src/framework/controls.js

@@ -6,9 +6,40 @@
 // enables it and reveals those controls right below it.
 // All controls mutate the shared `params` object and call onDirty() on change.
 
+import { renderMarkdown } from "./markdown.js";
+
 // Short numeric string without float noise (4 dp max) for the value box.
 const numStr = (v) => String(Math.round(v * 1e4) / 1e4);
 
+// --- relevance (dim controls / hide sections that don't affect on-screen parts) ---
+// `relevant` is a Set of param keys, or any non-Set value (e.g. RELEVANT_ALL) → show all.
+function applyRelevance(relevant, controls, sections) {
+  const showAll = !(relevant instanceof Set);
+  for (const { key, el: node } of controls) {
+    const irrelevant = !showAll && !relevant.has(key);
+    node.classList.toggle("irrelevant", irrelevant);
+    if (irrelevant) node.title = "Doesn't affect the parts in the current view";
+    else node.removeAttribute("title");
+  }
+  for (const { el: node, keys } of sections) {
+    const anyRelevant = showAll || [...keys].some((k) => relevant.has(k));
+    node.classList.toggle("section-hidden", !anyRelevant);
+  }
+}
+
+// --- visibility (hidden controls/sections) --------------------------------
+export const visibleAdvanced = (sec) => (sec.advanced ?? []).filter((d) => !d.hidden);
+export const visibleFeatures = (sec) => (sec.features ?? []).filter((f) => !f.hidden);
+// Standalone toggle checkboxes a preset section can show (outside the Advanced fold),
+// e.g. preview switches. Each: { key, label, on?, description?, hidden? }.
+export const visibleToggles = (sec) => (sec.toggles ?? []).filter((t) => !t.hidden);
+export function sectionRenders(sec) {
+  if (sec.hidden) return false;
+  if (sec.features) return visibleFeatures(sec).length > 0;
+  const hasPresets = sec.presets && Object.keys(sec.presets).length > 0;
+  return !!hasPresets || visibleAdvanced(sec).length > 0 || visibleToggles(sec).length > 0;
+}
+
 // Parse a typed value → clamped to [min, max], or null if not a finite number.
 export function clampToRange(raw, min, max) {
   const v = parseFloat(raw);
@@ -16,6 +47,58 @@ export function clampToRange(raw, min, max) {
   return Math.min(max, Math.max(min, v));
 }
 
+// --- info glyph + shared popover ------------------------------------------
+// One popover element, reused across glyphs (only one open at a time). Global
+// dismiss listeners are registered once at module load.
+let popover = null;
+function ensurePopover() {
+  if (!popover || !popover.isConnected) {
+    popover = document.createElement("div");
+    popover.className = "popover";
+    popover.hidden = true;
+    document.body.append(popover);
+  }
+  return popover;
+}
+function closePopover() {
+  if (popover && !popover.hidden) {
+    popover.hidden = true;
+    if (popover._owner) { popover._owner.setAttribute("aria-expanded", "false"); popover._owner = null; }
+  }
+}
+if (typeof document !== "undefined") {
+  document.addEventListener("click", (e) => {
+    if (popover && !popover.hidden && !popover.contains(e.target) && !e.target.closest?.(".info")) closePopover();
+  });
+  document.addEventListener("keydown", (e) => { if (e.key === "Escape") closePopover(); });
+}
+
+// Append a focusable ⓘ glyph to `container` that toggles the shared popover with
+// `description` (Markdown). No-op when description is empty.
+function attachInfo(container, description) {
+  if (typeof description !== "string" || !description.trim()) return;
+  const glyph = document.createElement("button");
+  glyph.type = "button";
+  glyph.className = "info";
+  glyph.textContent = "ⓘ";
+  glyph.setAttribute("aria-label", "More info");
+  glyph.setAttribute("aria-expanded", "false");
+  glyph.addEventListener("click", (e) => {
+    e.stopPropagation();
+    const pop = ensurePopover();
+    if (pop._owner === glyph) { closePopover(); return; } // toggle off
+    closePopover();
+    pop.innerHTML = renderMarkdown(description);
+    pop.hidden = false;
+    pop._owner = glyph;
+    glyph.setAttribute("aria-expanded", "true");
+    const r = glyph.getBoundingClientRect();
+    pop.style.top = `${r.bottom + 6}px`;
+    pop.style.left = `${Math.max(8, r.left - 8)}px`;
+  });
+  container.append(glyph);
+}
+
 function el(tag, className, text) {
   const node = document.createElement(tag);
   if (className) node.className = className;
@@ -32,7 +115,9 @@ function makeSlider(def, params, onChange) {
   const numeric = def.control === "number";
   const wrap = el("div", "slider");
   const row = el("div", "row");
-  row.append(el("label", "", def.label));
+  const label = el("label", "", def.label);
+  attachInfo(label, def.description);
+  row.append(label);
 
   // editable value box (+ optional unit suffix)
   const val = el("div", "val");
@@ -96,70 +181,102 @@ function advancedBlock() {
 }
 
 export function buildControls(root, parameters, params, onDirty) {
+  const controls = []; // { key, el } per control element
+  const sections = []; // { el, keys:Set } per rendered section
   for (const sec of parameters) {
+    if (!sectionRenders(sec)) continue;
     const section = el("div", "section");
-    section.append(el("div", "sec-title", sec.title));
-    if (sec.features) buildFeatureSection(section, sec, params, onDirty);
-    else buildPresetSection(section, sec, params, onDirty);
+    const title = el("div", "sec-title", sec.title);
+    attachInfo(title, sec.description);
+    section.append(title);
+    const keys = new Set();
+    const register = (key, node) => { controls.push({ key, el: node }); keys.add(key); };
+    if (sec.features) buildFeatureSection(section, sec, params, onDirty, register);
+    else buildPresetSection(section, sec, params, onDirty, register);
     root.append(section);
+    sections.push({ el: section, keys });
   }
+  return { applyRelevance: (relevant) => applyRelevance(relevant, controls, sections) };
 }
 
-function buildPresetSection(section, sec, params, onDirty) {
-  // preset picker, below the title, full width
-  const preset = document.createElement("select");
-  preset.className = "preset";
-  const presetNames = Object.keys(sec.presets);
-  for (const name of [...presetNames, "Custom"]) {
-    const o = document.createElement("option");
-    o.value = name;
-    o.textContent = name;
-    preset.append(o);
+function buildPresetSection(section, sec, params, onDirty, register) {
+  // preset picker, below the title, full width (omitted when the section has no presets)
+  let preset = null;
+  const presetNames = sec.presets ? Object.keys(sec.presets) : [];
+  if (presetNames.length) {
+    preset = document.createElement("select");
+    preset.className = "preset";
+    for (const name of [...presetNames, "Custom"]) {
+      const o = document.createElement("option");
+      o.value = name; o.textContent = name; preset.append(o);
+    }
+    preset.value = presetNames[0];
+    section.append(preset);
   }
-  preset.value = presetNames[0];
-  section.append(preset);
 
-  const { adv, toggle } = advancedBlock();
+  // standalone toggle checkboxes (e.g. preview switches), shown below the preset and
+  // outside the Advanced fold so they stay visible. Independent of the preset selector.
+  for (const t of visibleToggles(sec)) {
+    const row = el("label", "feat");
+    const box = document.createElement("input");
+    box.type = "checkbox";
+    box.checked = params[t.key] > 0;
+    const lbl = el("span", "", t.label);
+    attachInfo(lbl, t.description);
+    row.append(box, lbl);
+    box.addEventListener("change", () => { params[t.key] = box.checked ? (t.on ?? 1) : 0; onDirty?.(); });
+    register(t.key, row);
+    section.append(row);
+  }
+
+  const advanced = visibleAdvanced(sec);
   const syncs = {};
-  for (const def of sec.advanced) {
-    const s = makeSlider(def, params, () => {
-      preset.value = "Custom";
-      onDirty?.();
-    });
-    adv.append(s.wrap);
-    syncs[def.key] = s.sync;
+  if (advanced.length) {
+    const { adv, toggle } = advancedBlock();
+    for (const def of advanced) {
+      const s = makeSlider(def, params, () => { if (preset) preset.value = "Custom"; onDirty?.(); });
+      adv.append(s.wrap);
+      syncs[def.key] = s.sync;
+      register(def.key, s.wrap);
+    }
+    section.append(toggle, adv);
   }
-  section.append(toggle, adv);
 
   // applying a preset overwrites its keys and refreshes this section's sliders
-  preset.addEventListener("change", () => {
-    const bundle = sec.presets[preset.value];
-    if (!bundle) return; // "Custom"
-    Object.assign(params, bundle);
-    for (const key in syncs) if (key in params) syncs[key]();
-    onDirty?.();
-  });
+  if (preset) {
+    preset.addEventListener("change", () => {
+      const bundle = sec.presets[preset.value];
+      if (!bundle) return; // "Custom"
+      Object.assign(params, bundle);
+      for (const key in syncs) if (key in params) syncs[key]();
+      onDirty?.();
+    });
+  }
 }
 
-function buildFeatureSection(section, sec, params, onDirty) {
+function buildFeatureSection(section, sec, params, onDirty, register) {
   // Everything lives under Advanced: each feature is a checkbox followed by its
   // own controls, which appear directly below it when the box is checked.
   const { adv, toggle } = advancedBlock();
   section.append(toggle, adv);
 
-  for (const feat of sec.features) {
+  for (const feat of visibleFeatures(sec)) {
     const checkRow = el("label", "feat");
     const box = document.createElement("input");
     box.type = "checkbox";
     box.checked = params[feat.key] > 0;
-    checkRow.append(box, el("span", "", feat.label));
+    const featLabel = el("span", "", feat.label);
+    attachInfo(featLabel, feat.description);
+    checkRow.append(box, featLabel);
+    register(feat.key, checkRow);
 
     const group = el("div", "feat-group");
     const syncs = [];
-    for (const def of feat.sliders) {
+    for (const def of feat.sliders.filter((d) => !d.hidden)) {
       const s = makeSlider(def, params, onDirty);
       group.append(s.wrap);
       syncs.push(s.sync);
+      register(def.key, s.wrap);
     }
     group.classList.toggle("hidden", !box.checked);
 

package/src/framework/geometry/edge-selector.js

@@ -0,0 +1,17 @@
+// Map partforge's declarative edge selector onto a replicad EdgeFinder filter.
+//   undefined          → undefined (all edges)
+//   (e) => e...         → passed through (raw replicad finder escape hatch)
+//   { dir, inPlane, at, near } → a filter applying the given criteria (AND)
+const AXIS = { X: [1, 0, 0], Y: [0, 1, 0], Z: [0, 0, 1] };
+
+export function toEdgeFinder(selector) {
+  if (selector == null) return undefined;
+  if (typeof selector === "function") return selector;
+  return (e) => {
+    let f = e;
+    if (selector.dir != null) f = f.inDirection(Array.isArray(selector.dir) ? selector.dir : AXIS[selector.dir]);
+    if (selector.inPlane != null) f = f.inPlane(selector.inPlane, selector.at);
+    if (selector.near != null) f = f.containsPoint(selector.near);
+    return f;
+  };
+}