partforge 0.6.0 → 0.7.0

package/src/framework/selection/hover.js

@@ -0,0 +1,128 @@
+// Always-on hover inspection: a cursor-following tooltip naming the feature +
+// sub-part under the pointer, and an overlay mesh highlighting the feature's
+// surface. Feature names come from Solid.label() in the part's build, carried
+// per-triangle in the mesh payload (geometry.userData.featureIds/features).
+import * as THREE from "three";
+import { raycastViewer } from "./raycast.js";
+
+const HIGHLIGHT = 0x4da3ff;
+
+// Extract the subset of a non-indexed geometry belonging to one feature id.
+function featureSubset(geometry, featureId) {
+  const { featureIds } = geometry.userData;
+  const pos = geometry.getAttribute("position");
+  let count = 0;
+  for (let t = 0; t < featureIds.length; t++) if (featureIds[t] === featureId) count++;
+  const out = new Float32Array(count * 9);
+  let o = 0;
+  for (let t = 0; t < featureIds.length; t++) {
+    if (featureIds[t] !== featureId) continue;
+    for (let v = 0; v < 3; v++) {
+      out[o++] = pos.getX(t * 3 + v); out[o++] = pos.getY(t * 3 + v); out[o++] = pos.getZ(t * 3 + v);
+    }
+  }
+  const g = new THREE.BufferGeometry();
+  g.setAttribute("position", new THREE.BufferAttribute(out, 3));
+  return g;
+}
+
+export function attachHoverLabels(viewer, { part, schedule = (cb) => requestAnimationFrame(cb) }) {
+  // Hover is a mouse idiom — skip entirely on touch-only devices.
+  if (globalThis.matchMedia && !matchMedia("(hover: hover)").matches) return { detach: () => {} };
+
+  const tip = document.createElement("div");
+  tip.id = "pf-hover-tip";
+  const feat = document.createElement("b");
+  const sub = document.createElement("span");
+  sub.className = "pf-hover-sub";
+  tip.append(feat, sub);
+  document.body.appendChild(tip);
+
+  const material = new THREE.MeshBasicMaterial({
+    color: HIGHLIGHT, transparent: true, opacity: 0.35,
+    polygonOffset: true, polygonOffsetFactor: -2, polygonOffsetUnits: -2,
+  });
+  const overlay = new THREE.Mesh(new THREE.BufferGeometry(), material);
+  overlay.visible = false;
+  overlay.renderOrder = 2;
+  let overlayParent = null;
+  // Subset cache per sub-part: rebuilt when the sub-part's geometry object changes
+  // (i.e. after a regenerate) — keyed on the geometry instance.
+  const subsets = new Map(); // subPart -> { geo, byId: Map(featureId -> BufferGeometry) }
+
+  const subLabel = (name) => part.parts[name]?.label ?? name;
+
+  function clearHighlight() {
+    overlay.visible = false;
+  }
+
+  function hide() {
+    tip.classList.remove("show");
+    clearHighlight();
+  }
+
+  function show(hit, x, y) {
+    if (hit.feature) {
+      feat.textContent = hit.feature.label;
+      sub.textContent = subLabel(hit.subPart);
+      const cached = subsets.get(hit.subPart);
+      let byId = cached?.geo === hit.mesh.geometry ? cached.byId : null;
+      if (!byId) {
+        for (const g of cached?.byId.values() ?? []) g.dispose();
+        byId = new Map();
+        subsets.set(hit.subPart, { geo: hit.mesh.geometry, byId });
+      }
+      let g = byId.get(hit.feature.id);
+      if (!g) { g = featureSubset(hit.mesh.geometry, hit.feature.id); byId.set(hit.feature.id, g); }
+      overlay.geometry = g;
+      if (overlayParent !== hit.mesh.parent) { hit.mesh.parent.add(overlay); overlayParent = hit.mesh.parent; }
+      overlay.visible = true;
+    } else {
+      feat.textContent = subLabel(hit.subPart);
+      sub.textContent = "";
+      clearHighlight();
+    }
+    tip.style.left = `${x + 14}px`;
+    tip.style.top = `${y + 14}px`;
+    tip.classList.add("show");
+  }
+
+  let pending = null; // latest pointer position; one raycast per scheduled frame
+  let down = false;
+
+  function onMove(ev) {
+    if (ev.pointerType === "touch") return;
+    if (down) return;
+    const had = pending;
+    pending = { x: ev.clientX, y: ev.clientY };
+    if (had) return; // a frame is already scheduled
+    schedule(() => {
+      const p = pending;
+      pending = null;
+      if (!p || down) return;
+      const hit = raycastViewer(viewer, p.x, p.y);
+      if (hit) show(hit, p.x, p.y); else hide();
+    });
+  }
+  const onDown = () => { down = true; hide(); };
+  const onUp = () => { down = false; };
+  const onLeave = () => hide();
+
+  viewer.domElement.addEventListener("pointermove", onMove);
+  viewer.domElement.addEventListener("pointerdown", onDown);
+  viewer.domElement.addEventListener("pointerup", onUp);
+  viewer.domElement.addEventListener("pointerleave", onLeave);
+
+  return {
+    detach: () => {
+      viewer.domElement.removeEventListener("pointermove", onMove);
+      viewer.domElement.removeEventListener("pointerdown", onDown);
+      viewer.domElement.removeEventListener("pointerup", onUp);
+      viewer.domElement.removeEventListener("pointerleave", onLeave);
+      tip.remove();
+      overlayParent?.remove(overlay);
+      for (const { byId } of subsets.values()) for (const g of byId.values()) g.dispose();
+      material.dispose();
+    },
+  };
+}

package/src/framework/selection/index.js

@@ -3,3 +3,6 @@
 export { resolveSelection, quantizePoint, snapNormal } from "./resolve.js";
 export { formatSelection } from "./format.js";
 export { attachPicker, worldToSubPartLocal } from "./pick.js";
+export { attachPickToggle } from "./pick-toggle.js";
+export { raycastViewer, featureAt } from "./raycast.js";
+export { attachHoverLabels } from "./hover.js";

package/src/framework/selection/pick-toggle.js

@@ -0,0 +1,34 @@
+import { attachPicker } from "./pick.js";
+import { formatSelection } from "./format.js";
+
+// The ?pick clipboard mode: a fixed toggle button + a transient toast. Clicking the
+// button arms the picker; clicking geometry copies a selection token and flashes it.
+// Styles live in app.css (#pf-pick / #pf-pick-toast). Self-contained — dropping the
+// call in mount and this file reverts the feature exactly.
+export function attachPickToggle(viewer, { part, getContext }) {
+  const btn = document.createElement("button");
+  btn.id = "pf-pick";
+  btn.textContent = "Pick";
+  btn.title = "Click a surface to copy a selection token";
+  document.body.appendChild(btn);
+
+  const toast = document.createElement("div");
+  toast.id = "pf-pick-toast";
+  document.body.appendChild(toast);
+
+  let hideTimer;
+  const picker = attachPicker(viewer, {
+    part,
+    getContext,
+    onPick: (selection) => {
+      const token = formatSelection(selection, { style: "token" });
+      navigator.clipboard?.writeText(token);
+      toast.textContent = `copied: ${token}`;
+      toast.classList.add("show");
+      clearTimeout(hideTimer);
+      hideTimer = setTimeout(() => toast.classList.remove("show"), 4000);
+    },
+  });
+
+  btn.addEventListener("click", () => picker.setActive(btn.classList.toggle("on")));
+}

package/src/framework/selection/pick.js

@@ -1,42 +1,19 @@
-// Viewer adapter — the ONLY three.js/DOM-aware file in the selection module.
-// Raycasts a click against the visible sub-meshes, converts the hit to the
-// sub-part's local CAD frame, and hands a resolved Selection to onPick.
-import * as THREE from "three";
+// Viewer adapter for click-to-select: arms a click listener, raycasts via the shared
+// selection raycast, and hands a resolved Selection to onPick.
+import { raycastViewer, worldToSubPartLocal } from "./raycast.js";
 import { resolveSelection } from "./resolve.js";
 
-// Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
-// shared-frame CAD coords — the same frame build() models in.
-export function worldToSubPartLocal(mesh, world) {
-  const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
-  mesh.worldToLocal(v);
-  return [v.x, v.y, v.z];
-}
+export { worldToSubPartLocal };
 
 export function attachPicker(viewer, { part, getContext, onPick }) {
-  const raycaster = new THREE.Raycaster();
-  const ndc = new THREE.Vector2();
   let active = false;
 
   function onClick(ev) {
     if (!active) return;
-    const rect = viewer.domElement.getBoundingClientRect();
-    ndc.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
-    ndc.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
-    raycaster.setFromCamera(ndc, viewer.camera);
-
-    const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
-    const hit = raycaster.intersectObjects(meshes, false)[0];
+    const hit = raycastViewer(viewer, ev.clientX, ev.clientY);
     if (!hit) return;
-
-    const selection = resolveSelection(part, getContext(), {
-      subPart: hit.object.name,
-      pointLocal: worldToSubPartLocal(hit.object, hit.point),
-      // face.normal is in the geometry's local frame, which equals the CAD frame here
-      // (the mesh carries no local transform; only its parents rotate/recentre).
-      normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
-      // hit.face metadata (kind/axis/radius) is the L1 increment — not populated yet.
-    });
-    viewer.flashPoint([hit.point.x, hit.point.y, hit.point.z]);
+    const selection = resolveSelection(part, getContext(), hit);
+    viewer.flashPoint([hit.pointWorld.x, hit.pointWorld.y, hit.pointWorld.z]);
     onPick(selection);
   }
 

package/src/framework/selection/raycast.js

@@ -0,0 +1,43 @@
+// Shared raycast for the selection modules: pointer position → the sub-part mesh,
+// triangle, CAD-local point/normal, and (when the mesh carries attribution) the
+// feature under the pointer. Used by both the click-picker and the hover-labeler.
+import * as THREE from "three";
+
+const raycaster = new THREE.Raycaster();
+const ndc = new THREE.Vector2();
+
+// Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
+// shared-frame CAD coords — the same frame build() models in.
+export function worldToSubPartLocal(mesh, world) {
+  const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
+  mesh.worldToLocal(v);
+  return [v.x, v.y, v.z];
+}
+
+// The feature carried by a mesh triangle, or null (unlabeled / no attribution data).
+export function featureAt(mesh, triIndex) {
+  const { featureIds, features } = mesh.geometry.userData;
+  const id = featureIds?.[triIndex] ?? 0;
+  return id > 0 ? { id, label: features[id - 1] } : null;
+}
+
+export function raycastViewer(viewer, clientX, clientY) {
+  const rect = viewer.domElement.getBoundingClientRect();
+  ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
+  ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
+  raycaster.setFromCamera(ndc, viewer.camera);
+  const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
+  const hit = raycaster.intersectObjects(meshes, false)[0];
+  if (!hit) return null;
+  return {
+    mesh: hit.object,
+    subPart: hit.object.name,
+    triIndex: hit.faceIndex,
+    pointWorld: hit.point,
+    pointLocal: worldToSubPartLocal(hit.object, hit.point),
+    // face.normal is in the geometry's local frame, which equals the CAD frame here
+    // (the mesh carries no local transform; only its parents rotate/recentre).
+    normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
+    feature: featureAt(hit.object, hit.faceIndex),
+  };
+}

package/src/framework/selection/resolve.js

@@ -42,13 +42,8 @@ export function resolveSelection(part, ctx, hit) {
     normal: snapNormal(hit.normalLocal),
     params: scopeParams(part, ctx.view, ctx.params, hit.subPart),
   };
-  if (hit.face) {
-    // L1 — feature.selector is the author's own { dir, inPlane, at, near } vocabulary,
-    // so the LLM can drop it straight into a faces(...)/edges(...) call.
-    const feature = { kind: hit.face.kind, selector: { near: point } };
-    if (hit.face.axis != null) { feature.axis = hit.face.axis; feature.selector.dir = hit.face.axis; }
-    if (hit.face.radius != null) feature.radius = hit.face.radius;
-    selection.feature = feature;
-  }
+  // Feature attribution from the mesh payload (Solid.label() in the part's build) —
+  // the same name the hover tooltip shows, so user, agent, and viewer share vocabulary.
+  if (hit.feature) selection.feature = { label: hit.feature.label };
   return selection;
 }

package/src/framework/status-ui.js

@@ -0,0 +1,18 @@
+// The status line, busy overlay, and export-button enabling — mount's host-page
+// chrome, as one small adapter. #status/#busy/#phase are required page elements;
+// export buttons are looked up by id and any that are absent are simply skipped.
+export function createStatusUi(doc = document) {
+  const statusEl = doc.getElementById("status");
+  const busyEl = doc.getElementById("busy");
+  const phaseEl = doc.getElementById("phase");
+  const exportBtns = ["download", "download-step", "download-3mf"]
+    .map((id) => doc.getElementById(id)).filter(Boolean);
+
+  return {
+    setStatus(msg, isErr = false) { statusEl.textContent = msg; statusEl.classList.toggle("err", isErr); },
+    showBusy(phase) { phaseEl.textContent = `${phase}…`; busyEl.classList.add("show"); },
+    hideBusy() { busyEl.classList.remove("show"); },
+    setExportEnabled(on) { exportBtns.forEach((b) => { b.disabled = !on; }); },
+    statusText: () => statusEl.textContent,
+  };
+}

package/src/framework/view-state.js

@@ -2,12 +2,13 @@
 // auto-refresh) in localStorage. All keys are global. Reads/writes are guarded:
 // if localStorage is unavailable (private mode, disabled) or a value is corrupt,
 // reads return the documented default and writes are no-ops — persistence never
-// throws. Theme is persisted separately (in mount.js) and is not handled here.
+// throws.
 
 const KEY = {
   rotating: "partforge:rotating",
   camera: "partforge:camera",
   view: "partforge:view",
+  theme: "partforge:theme",
 };
 
 function read(key) {
@@ -46,6 +47,15 @@ export function saveCamera(state) {
   write(KEY.camera, JSON.stringify({ pos: state.pos, target: state.target }));
 }
 
+export function loadTheme() {
+  const raw = read(KEY.theme);
+  return raw === "light" ? "light" : "dark"; // default: dark (matches the viewer's default)
+}
+
+export function saveTheme(mode) {
+  if (mode === "light" || mode === "dark") write(KEY.theme, mode);
+}
+
 export function loadView() {
   return read(KEY.view); // raw string or null; caller validates against available tabs
 }

package/src/framework/view-tabs.js

@@ -0,0 +1,33 @@
+import { loadView, saveView } from "./view-state.js";
+
+// The view-tab segmented control. When the part declares `views`, the buttons are
+// generated from it (part.views is the single source of truth — host pages leave
+// the #part div empty); a part without `views` keeps whatever buttons the page
+// hand-wrote. The active view persists across reloads via view-state.
+export function createViewTabs(el, part, { onChange }) {
+  if (el && part.views) {
+    el.innerHTML = Object.entries(part.views)
+      .map(([key, v], i) => `<button data-part="${key}"${i === 0 ? ' class="on"' : ""}>${v?.label ?? key}</button>`)
+      .join("");
+  }
+
+  const setActive = (btn) => { for (const b of el.children) b.classList.toggle("on", b === btn); };
+
+  // Initial view: the saved one if it still matches a tab, else the active (first) tab.
+  const defaultView = el.querySelector("button.on")?.dataset.part ?? el.querySelector("button")?.dataset.part;
+  const saved = loadView();
+  const savedBtn = saved ? [...el.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === saved) : null;
+  let view = savedBtn ? saved : defaultView;
+  if (savedBtn) setActive(savedBtn);
+
+  el.addEventListener("click", (e) => {
+    const btn = e.target.closest("button[data-part]");
+    if (!btn) return;
+    view = btn.dataset.part;
+    saveView(view);
+    setActive(btn);
+    onChange(view);
+  });
+
+  return { current: () => view };
+}

package/src/framework/viewer-controls.js

@@ -0,0 +1,48 @@
+import { loadRotating, saveRotating, saveCamera, loadTheme, saveTheme } from "./view-state.js";
+
+// Wire the optional viewer-chrome buttons on the host page (#pause / #reframe /
+// #theme) to the viewer, plus persist the camera pose. Each button is optional —
+// omit it from the page and its behavior is simply absent. Self-contained: touches
+// only the viewer and the DOM, none of the part/params/regenerate state.
+export function attachViewerControls(viewer) {
+  const pauseBtn = document.getElementById("pause");
+  const reframeBtn = document.getElementById("reframe");
+  const themeBtn = document.getElementById("theme");
+
+  // Theme: toggle the page chrome (CSS vars keyed off <html data-theme>) and the
+  // scene together; remember the choice across reloads.
+  let theme = loadTheme();
+  function applyTheme(mode) {
+    theme = mode;
+    document.documentElement.dataset.theme = mode;
+    viewer.setTheme(mode);
+    themeBtn?.classList.toggle("on", mode === "light");
+    saveTheme(mode);
+  }
+  applyTheme(theme);
+  themeBtn?.addEventListener("click", () => applyTheme(theme === "light" ? "dark" : "light"));
+
+  // Pause/resume the idle auto-rotation.
+  let rotating = loadRotating();
+  viewer.setAutoRotate(rotating);
+  const syncPause = () => {
+    if (!pauseBtn) return;
+    pauseBtn.textContent = rotating ? "⏸" : "▶";
+    pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
+  };
+  syncPause();
+  pauseBtn?.addEventListener("click", () => {
+    rotating = !rotating;
+    viewer.setAutoRotate(rotating);
+    syncPause();
+    saveRotating(rotating);
+  });
+
+  // Re-fit the camera to the current view.
+  reframeBtn?.addEventListener("click", () => viewer.frame());
+
+  // Persist the camera when the user finishes an orbit/zoom, and right before a
+  // reload (captures the latest pose, including auto-rotation drift).
+  viewer.onCameraEnd(() => saveCamera(viewer.getCameraState()));
+  window.addEventListener("pagehide", () => saveCamera(viewer.getCameraState()));
+}

package/src/framework/viewer.js

@@ -105,7 +105,7 @@ export function createViewer(container, part) {
   // --- geometry builder -----------------------------------------------------
   // BufferGeometry from a worker mesh payload — kept in its shared-frame coords
   // (NOT recentred) so the pieces assemble in the right relative positions.
-  function buildGeometry({ positions, normals, indices, triangles, edges }) {
+  function buildGeometry({ positions, normals, indices, triangles, edges, featureIds, features }) {
     const geo = new THREE.BufferGeometry();
     geo.setAttribute("position", new THREE.BufferAttribute(positions, 3));
     if (indices?.length) geo.setIndex(new THREE.BufferAttribute(indices, 1)); // Manifold is non-indexed
@@ -122,6 +122,7 @@ export function createViewer(container, part) {
       out.computeBoundingBox();
     }
     out.userData.triangles = triCount;
+    if (featureIds) { out.userData.featureIds = featureIds; out.userData.features = features; }
     // feature edge lines: Manifold supplies seam-aware segments; else derive by angle
     const lg = new LineSegmentsGeometry();
     if (edges?.length) lg.setPositions(edges);
@@ -134,9 +135,15 @@ export function createViewer(container, part) {
   const subCache = Object.fromEntries(names.map((n) => [n, null]));
 
   function setSubGeometry(name, payload) {
+    const prev = subCache[name]; // free the geometry this replaces (its own buffers + edge lines)
+    if (prev) { prev.userData.edges?.dispose(); prev.dispose(); }
     subCache[name] = buildGeometry(payload);
   }
 
+  // Cache queries for the app's regenerate loop (so it never reaches into subCache).
+  const hasSubMesh = (name) => !!subCache[name];
+  const subTriangles = (name) => subCache[name]?.userData.triangles ?? 0;
+
   // --- show / hide assembly -------------------------------------------------
   const _box = new THREE.Box3();
 
@@ -227,13 +234,6 @@ export function createViewer(container, part) {
   }
   function onCameraEnd(cb) { controls.addEventListener("end", cb); }
 
-  // --- dispose --------------------------------------------------------------
-  function dispose() {
-    renderer.setAnimationLoop(null);
-    renderer.dispose();
-    container.removeChild(renderer.domElement);
-  }
-
   // Transient marker at a world-space point — visual confirmation of a pick.
   function flashPoint(world) {
     const dot = new THREE.Mesh(
@@ -246,5 +246,5 @@ export function createViewer(container, part) {
     setTimeout(() => { scene.remove(dot); dot.geometry.dispose(); dot.material.dispose(); }, 1200);
   }
 
-  return { showAssembly, hideAssembly, setSubGeometry, resize, dispose, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, _subCache: subCache, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint };
+  return { showAssembly, hideAssembly, setSubGeometry, hasSubMesh, subTriangles, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint };
 }

package/src/framework/worker.js

@@ -29,23 +29,6 @@ async function occtKernel() {
   return createOcctKernel(replicad);
 }
 
-// Transfer the big binary buffers (zero-copy) instead of structured-cloning them.
-function transferOf(m) {
-  if (m.type === "meshes") {
-    const t = [];
-    for (const x of m.meshes) {
-      t.push(x.positions.buffer);
-      if (x.normals?.buffer) t.push(x.normals.buffer);
-      if (x.indices?.buffer) t.push(x.indices.buffer);
-      if (x.edges?.buffer) t.push(x.edges.buffer);
-    }
-    return t;
-  }
-  if (m.type === "download-parts") return m.parts.map((p) => (ArrayBuffer.isView(p.data) ? p.data.buffer : p.data));
-  if (m.type === "download") return [m.data];
-  return [];
-}
-
 export function runWorker(part) {
   const backend = self.name === "occt" ? "occt" : "manifold";
   let manifold = null; // { preview, print }
@@ -55,14 +38,22 @@ export function runWorker(part) {
   // Manifold is cheap to boot — bring it up eagerly and signal readiness.
   if (backend === "manifold") {
     booting = manifoldKernels().then((m) => { manifold = m; postMessage({ type: "ready" }); });
+  } else {
+    // OCCT boots lazily (its ~11 MB WASM loads on the first job), but the worker can
+    // accept jobs as soon as its module graph is up — messages queue in the port.
+    // EVERY worker must post ready: mount gates the first generate on it, so if only
+    // the manifold worker signalled, boot would silently depend on the manifold
+    // worker always being spawned alongside this one.
+    postMessage({ type: "ready" });
   }
 
   self.onmessage = async (e) => {
     let kernel;
     if (backend === "manifold") {
       await booting;
-      const printJob = e.data.type === "export-stl" || e.data.type === "export-3mf"; // high-res mesh exports
-      kernel = printJob ? manifold.print : manifold.preview;
+      // The sender declares the job's mesh quality; the worker knows nothing about
+      // job-type semantics (mount marks STL/3MF exports quality:"print").
+      kernel = e.data.quality === "print" ? manifold.print : manifold.preview;
     } else {
       if (!occt) {
         postMessage({ type: "progress", phase: "loading exact kernel" }); // feedback during cold boot
@@ -71,6 +62,7 @@ export function runWorker(part) {
       }
       kernel = occt;
     }
-    await handle(kernel, part, e.data, (m) => postMessage(m, transferOf(m)));
+    // handle() declares each message's transferables (the big binary buffers).
+    await handle(kernel, part, e.data, (m, transfer = []) => postMessage(m, transfer));
   };
 }

package/src/parts/filleted-box.js

@@ -37,7 +37,7 @@ export default {
         // the shortest edge it touches (here the fillets' bottom arcs), so it stops at
         // its valid maximum instead of mangling the bottom face.
         if (p.chamfer > 0) s = s.chamfer(p.chamfer, { inPlane: "XY", at: 0 });    // base edges
-        if (p.bore > 0) s = s.cut(k.cylinder(p.bore / 2, p.bore / 2, p.h + 2).at([p.w / 2, p.d / 2, -1]));
+        if (p.bore > 0) s = s.cut(k.cylinder(p.bore / 2, p.bore / 2, p.h + 2).at([p.w / 2, p.d / 2, -1]).label("Bore"));
         return s;
       },
     },

package/src/parts/planter.js

@@ -0,0 +1,120 @@
+// Example PartDefinition — a faceted planter / cup / vase. A second worked example
+// alongside parts/demo.js (the Spacer): it shows a prism-based body (Manifold backend,
+// so it stays fast — no OCCT), per-control descriptions, presets, an optional feature
+// (drainage), a hidden internal constant (floor), and a derive() that turns raw inputs
+// into the n-gon point lists and dependent dimensions the build consumes.
+//
+// Why it's a good demo: every control has an obvious reason to touch it before
+// printing. Facets/twist are pure fun, height/diameter/taper fit it to your plant or
+// pens, the drainage hole is a real functional choice (planter vs. cup), and dropping
+// Wall below the fdm-pla 1.2 mm minimum trips partforge's min-wall warning.
+
+// A regular n-gon of circumradius R, in the XY plane, as [[x,y],…] for k.prism.
+// A small rotation seats a flat edge toward the viewer so even-sided shapes read right.
+const ngon = (R, n) => {
+  const pts = [];
+  const offset = Math.PI / n - Math.PI / 2; // flat side facing -Y
+  for (let i = 0; i < n; i++) {
+    const a = (2 * Math.PI * i) / n + offset;
+    pts.push([R * Math.cos(a), R * Math.sin(a)]);
+  }
+  return pts;
+};
+
+export default {
+  meta: { title: "Faceted Planter", units: "mm", background: 0x15181d },
+  parameters: [
+    {
+      id: "body",
+      title: "Body",
+      description:
+        "The faceted vessel. Pick a preset to start, or open **Advanced** for exact dimensions. " +
+        "**Facets** and **Twist** are pure styling; **Wall** is the one that decides whether it prints cleanly.",
+      presets: {
+        "Pen cup": { facets: 6, dia: 80, height: 100, taper: 1.0, twist: 0, drain: 0 },
+        Planter: { facets: 8, dia: 90, height: 80, taper: 0.9, twist: 0, drain: 8 },
+        Vase: { facets: 5, dia: 70, height: 150, taper: 1.12, twist: 40, drain: 0 },
+      },
+      advanced: [
+        { key: "facets", label: "Facets", min: 3, max: 12, step: 1,
+          description: "Number of flat sides around the body. Low counts read as crystalline; high counts approach a smooth cylinder." },
+        { key: "dia", label: "Diameter", unit: "mm", min: 30, max: 150, step: 1,
+          description: "Across-corners diameter at the base. Size it to the plant, pens, or shelf it has to fit." },
+        { key: "height", label: "Height", unit: "mm", min: 20, max: 200, step: 1,
+          description: "Overall height along the axis." },
+        { key: "taper", label: "Top taper", min: 0.6, max: 1.4, step: 0.02,
+          description: "Rim size relative to the base: below 1 tapers inward (planter), 1 is straight (cup), above 1 flares out (vase)." },
+        { key: "wall", label: "Wall thickness", unit: "mm", min: 0.8, max: 4, step: 0.1,
+          description: "Side-wall thickness. The fdm-pla profile wants **≥ 1.2 mm** — go thinner and partforge flags a min-wall warning." },
+        { key: "twist", label: "Twist", unit: "°", min: 0, max: 180, step: 5,
+          description: "Rotates the facets from base to rim for a spiral look. 0 keeps the facets vertical." },
+        { key: "floor", label: "Floor thickness", unit: "mm", min: 1, max: 6, step: 0.5, hidden: true,
+          description: "Internal: solid base thickness, fixed by the design. Hidden from the end user but still drives the geometry." },
+      ],
+    },
+    {
+      id: "drainage",
+      title: "Drainage",
+      description: "Optional drainage hole through the base — turn it on for a planter, off to hold water like a cup or vase.",
+      features: [
+        { label: "Drainage hole", key: "drain", on: 8,
+          description: "Drills a centered hole of this diameter through the floor.",
+          sliders: [{ key: "drain", label: "Hole diameter", unit: "mm", min: 3, max: 30, step: 1,
+            description: "Diameter of the centered drainage hole." }] },
+      ],
+    },
+  ],
+  defaults: { facets: 6, dia: 70, height: 90, taper: 1.2, wall: 1.6, twist: 30, drain: 8, floor: 3 },
+  // derive(): turn raw inputs into the n-gon point lists and dependent dimensions the
+  // build needs, sized so the wall stays even (see build()).
+  derive: (p) => {
+    const Rout = p.dia / 2;
+    // Offset the inner polygon inward by `wall` along the FACE normals, not the radius:
+    // for a regular n-gon an edge offset of `wall` shrinks the circumradius by
+    // wall / cos(π/n). This keeps the perpendicular wall = `wall` on every flat.
+    // clamp only matters if wall is set past the slider bounds via the API
+    const Rin = Math.max(Rout - p.wall / Math.cos(Math.PI / p.facets), 1);
+    return {
+      outerPts: ngon(Rout, p.facets),
+      innerPts: ngon(Rin, p.facets),
+      // Inner taper that holds the wall constant top-to-bottom even as the body flares:
+      // pick it so inner_radius(top) = outer_radius(top) − wall.
+      innerTaper: 1 + (Rout * (p.taper - 1)) / Rin,
+      drainR: (p.drain + 0.2) / 2, // nominal hole + 0.2 mm print clearance, as a radius
+    };
+  },
+  parts: {
+    planter: {
+      label: "Planter",
+      views: ["planter"],
+      export: { name: "planter" },
+      build: (k, p, d) => {
+        const body = k.prism(d.outerPts, p.height, { scaleTop: p.taper, twist: p.twist }).label("Faceted wall");
+        // Hollow it. The cavity is built from z=0 sharing the body's exact twist RATE and
+        // taper slope (f rescales the ~4 mm overshoot so the rates still match), so the
+        // inner and outer facets stay radially aligned at every height — the wall can't
+        // pinch when twisted. Then clip the cavity to z ≥ floor so the base stays solid.
+        const f = (p.height + 4) / p.height;
+        const cavity = k
+          .prism(d.innerPts, p.height + 4, { scaleTop: 1 + (d.innerTaper - 1) * f, twist: p.twist * f })
+          .intersect(k.box([-1e4, -1e4, p.floor], [1e4, 1e4, p.height + 10]))
+          .label("Cavity");
+        let s = body.cut(cavity);
+        // Optional drainage hole straight through the base.
+        if (p.drain > 0) s = s.cut(k.cylinder(d.drainR, d.drainR, p.floor + 4).at([0, 0, -2]).label("Drainage hole"));
+        return s;
+      },
+    },
+  },
+  views: { planter: { label: "Planter" } },
+  // Self-verification (see docs/AUTHORING-PARTS.md "Self-verification"): opt into the
+  // FDM-PLA process profile (bed-fit gate + min-wall warning) and pin the design intent
+  // — one drainage hole through the base, fits the bed, no interpenetration.
+  verify: {
+    process: "fdm-pla",
+    expect: {
+      planter: { holes: 1 /* drain=8 at defaults → 1 hole; adjust if running verify with a non-default drain */, bbox: "<=[220,220,250]" },
+      _view: { overlaps: 0 } /* _view = whole-model composite (not a named part) */,
+    },
+  },
+};