partforge 0.19.0 → 0.20.1

package/docs/AUTHORING-PARTS.md

@@ -44,6 +44,7 @@ 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
+  fonts?,                                  // { name: source } — fonts a part's k.text2d() needs; framework preloads before build (see below)
   derive?,                                 // (p) => d, or { group: (p, d) => {…}, … } — dependent values computed once per build
   parts: {                                 // named sub-parts; each builds ONE solid
     <name>: {
@@ -82,6 +83,13 @@ export default {
 - `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.
+- `fonts` declares the outline fonts a part's `k.text2d()` calls need, as `{ name: source
+  }` — a source is inline bytes, a URL string, or a thunk (e.g. a Vite `import('./x.ttf')`,
+  which resolves to `{ default: url }`). The framework resolves and parses these into
+  `kernel._fonts` **before** the synchronous `build` runs, so `k.text2d(str, { font: name
+  })` can look the font up by name. See `src/framework/fonts.js` (`resolveFonts`) and
+  `k.text2d` in `docs/KERNEL-CONTRACT.md` for the full contract; fuller authoring guidance
+  (recommended font sourcing, licensing notes) lands in a follow-up pass.
 
 ---
 
@@ -498,6 +506,72 @@ const wall  = k.shape2d(outer).offset(-2, { corners: "sharp" });  // inset, mite
 
 `Shape2D.offset(delta, {corners})` grows (`delta>0`) or insets (`delta<0`) a shape with round/chamfer/sharp corners — curve-preserving on OCCT, faceted at mesh LOD on Manifold; it throws if the offset collapses the shape. (For `derive()`/main-thread clearance math on plain point lists, use the pure `offsetPolygon` helper instead.)
 
+## Text (`text2d`)
+
+`k.text2d(string, { size, font?, align?, valign?, lineHeight?, tracking?, kerning? })` renders outline-font text as a `Shape2D` — a 2-D boolean you can compose with other shapes (union / cut / offset) and extrude into 3-D geometry.
+
+**Parameters:**
+
+- `string` — the text to render
+- `size` — **cap height in mm** (the design-height of capital letters like "H"); the layout engine scales the font to this height
+- `font` — optional font name (declared in the part's `fonts` field, below); omit it to use the bundled default (Roboto)
+- `align` — horizontal alignment: `"center"` (default), `"left"`, or `"right"`
+- `valign` — vertical alignment: `"middle"` (default), `"baseline"`, `"top"`, or `"bottom"`. The defaults (`center`/`middle`) place the text block's centre at the origin, so `.at([x, y])` / `plate.cut(text)` compose without extra translation
+- `lineHeight` — distance between baselines in **mm** for multi-line text; omit for a font-metrics default (≈ `(ascender − descender)/em × size`)
+- `tracking` — letter spacing in mm (default 0); positive widens, negative tightens
+- `kerning` — boolean, enable pair-wise kerning (default true)
+
+**Shape2D composition:**
+
+Like any `Shape2D`, the result composes with booleans and offset — you can union it onto a face, cut it out as a depression, expand it with `offset()`, or combine multiple text shapes:
+
+```js
+// Emboss text onto a plate
+const baseplate = k.extrude({ profile: roundedRectPolygon(100, 60, 4), h: 5 });
+const emboss = k.text2d("v2.0", { size: 8 }).offset(0.2);  // 0.2 mm relief
+const part = baseplate.cut(k.extrude({ profile: emboss, h: 1 }));
+
+// Deboss text into a lid
+const lid = k.extrude({ profile: circleProfile(40), h: 3 });
+const deboss = k.text2d("PART-042", { size: 6 });
+const carved = lid.cut(k.extrude({ profile: deboss, h: 0.5 }));
+
+// Extrude text as a solid letters
+const raised = k.extrude({ profile: k.text2d("LOGO", { size: 10, align: "center" }), h: 2 });
+
+// Multi-line label with tight tracking
+const label = k.text2d("YEAR 2025\nSERIES A", { size: 4, align: "center", tracking: -0.1 });
+```
+
+**Font sourcing (the `fonts` PartDefinition field):**
+
+Declare fonts in your part definition's optional `fonts` object — a map of font names to sources. The framework resolves and parses these before `build()` runs, so `k.text2d(str, { font: name })` can look them up synchronously:
+
+```js
+fonts: {
+  heading: () => import("./fonts/Raleway-Bold.ttf"),    // bundle via Vite dynamic import
+  label: "https://cdn.example.com/fonts/Courier-Prime.ttf",  // URL fetch
+  default: new Uint8Array([...])                             // inline bytes (rare)
+},
+```
+
+- **Dynamic import:** `() => import("./path/to/font.ttf")` — Vite bundles the font; resolves to `{ default: url }` at runtime
+- **URL:** a string — the framework fetches it (CORS must allow it)
+- **Inline bytes:** an `ArrayBuffer` or `Uint8Array` — useful for generated or embedded fonts
+
+Reference a font by name: `k.text2d("text", { font: "heading" })`. Omit the `font` option to use the bundled **Roboto** (Regular, SIL OFL 1.1) default.
+
+**Build-time & curve semantics:**
+
+`text2d` is a **build-time operation** (not `derive()`), and **the curve representation differs by backend:**
+
+- **OCCT (B-rep):** text outlines carry **exact cubic Bézier curves** into STEP export (not tessellated)
+- **Manifold (mesh):** text outlines **facet at the mesh level-of-detail** (same as other curves in preview)
+
+Both backends produce watertight emboss/deboss geometry; the difference is export fidelity. As with any `Shape2D`, composition with booleans and offset is backend-agnostic — the same code works on both.
+
+**Overlapping / self-intersecting glyph outlines:** real font outlines aren't always simple, correctly-nested contours — counters can overlap or self-intersect. Before glyphs become curve regions, the framework resolves each glyph's raw contours with the nonzero winding rule (how all OpenType outlines — TrueType and CFF alike — are filled), so composite/overlapping outlines still produce a single correct `{outer, holes}` shape per glyph. This resolution stays curve-exact — it never flattens beziers to polygons — so the OCCT/Manifold split above still holds.
+
 ---
 
 ## Wiring a part into a runnable app
@@ -534,11 +608,33 @@ stylesheet). `mount` looks up these element IDs:
 | `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#pause` / `#reframe` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#pause` / `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
 
 Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
 (`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
 
+`#cutaway` is optional viewer chrome. When present, it toggles an interactive
+section plane whose exposed faces are hatched; changing views resets it. Cutaway
+is viewer-only and never changes STL, STEP, or 3MF exports. Hosts that omit the
+button get no cutaway UI.
+
+Programmatic hosts can provide the same optional control without relying on an
+ID by passing it beside the other chrome references:
+
+```js
+mount(part, {
+  createWorker,
+  elements: {
+    chrome: {
+      pause,
+      reframe,
+      cutaway,
+      theme,
+    },
+  },
+});
+```
+
 > Production deploy compiles only the pages listed in `build.rollupOptions.input`
 > (currently the landing gallery + the demo part pages). Other root `*.html` files are
 > **dev-only** (Vite serves any root HTML in `npm run dev`) unless added there. To also

package/docs/ERROR-PATTERNS.md

@@ -248,6 +248,12 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
   inset. Realistic clearances (fractions of a mm) and wall insets up to the
   narrowest feature never trip this.
 
+## curve-fill-resolved-hole-uncontained
+
+- **Symptom:** `curve-fill: resolved hole has no containing outer`
+- **Cause:** paper.js returned an unexpected or numerically degenerate path topology for the supplied font outline; the resolver refuses to attach the hole to an arbitrary outer.
+- **Fix:** reduce or normalize degenerate font contours, confirm the correct CFF/TrueType fill rule was selected, and add the glyph as a focused `curve-fill.test.js` regression before changing resolver tolerances.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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",
@@ -45,6 +45,8 @@
     "fflate": "^0.8.3",
     "manifold-3d": "^3.5.1",
     "marked": "^18.0.5",
+    "opentype.js": "^2.0.0",
+    "paper": "^0.12.18",
     "pngjs": "^7.0.0",
     "replicad": "^0.23.1",
     "replicad-opencascadejs": "^0.23.0",

package/src/app-bracket.js

@@ -0,0 +1,9 @@
+import part from "./parts/bracket.js";
+import { mount } from "./framework/index.js";
+
+// Dev example app for the bracket demo (src/parts/bracket.js). The
+// `new Worker(new URL(...))` call must stay inline here so Vite bundles the worker.
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./bracket-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/app-embed-test.js

@@ -0,0 +1,68 @@
+import planterPart from "./parts/planter.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only smoke harness for the 0.12.0 embedding contract (see embed-test.html).
+// Exercises: explicit `elements` refs (no legacy IDs on the page), runtime.ready,
+// runtime.dispose() (including dispose-before-first-build and rapid remount cycles),
+// onBuild outcomes, and always-on onPick with the { selection, label, prompt, token }
+// payload — i.e. exactly what partforge-cloud's chat chips will consume.
+
+const logEl = document.getElementById("log");
+function log(kind, msg) {
+  const line = document.createElement("div");
+  line.className = kind;
+  line.textContent = `${new Date().toISOString().slice(11, 19)} ${msg}`;
+  logEl.prepend(line);
+}
+
+const byId = (id) => document.getElementById(id);
+const elements = {
+  viewer: byId("pf-viewer"),
+  controls: byId("pf-controls"),
+  status: { status: byId("pf-status"), busy: byId("pf-busy"), phase: byId("pf-phase") },
+  tabs: byId("pf-tabs"),
+  exports: { stl: byId("pf-stl"), step: byId("pf-step") }, // no 3MF button on purpose (optional)
+  chrome: { pause: byId("pf-pause"), reframe: byId("pf-reframe"), theme: byId("pf-theme") },
+};
+
+let runtime = null;
+
+function doMount() {
+  if (runtime) { log("life", "already mounted — dispose first"); return; }
+  runtime = mount(planterPart, {
+    createWorker: (name) =>
+      new Worker(new URL("./planter-worker.js", import.meta.url), { type: "module", name }),
+    elements,
+    onBuild: (b) => log("build", `onBuild: ${b.status}${b.ms != null ? ` (${Math.round(b.ms)} ms)` : ""}${b.error ? ` — ${b.error}` : ""}`),
+    onPick: ({ label, prompt, token, selection }) => {
+      log("pick", `onPick label="${label}"`);
+      log("pick", `  prompt: ${prompt}`);
+      log("pick", `  token:  ${token}`);
+      console.log("onPick payload", { label, prompt, token, selection });
+    },
+  });
+  log("life", "mounted");
+  runtime.ready.then(
+    () => log("life", "ready ✓ (first build succeeded)"),
+    (e) => log("life", `ready ✗ (${e.message})`),
+  );
+}
+
+function doDispose() {
+  if (!runtime) { log("life", "not mounted"); return; }
+  runtime.dispose();
+  runtime.dispose(); // idempotence check — must be a no-op
+  runtime = null;
+  log("life", "disposed (×2 — second call must be a no-op)");
+}
+
+document.getElementById("btn-mount").addEventListener("click", doMount);
+document.getElementById("btn-dispose").addEventListener("click", doDispose);
+// The React-unmount torture test: dispose immediately after mount, repeatedly.
+// Expect five "ready ✗ (disposed before first build)" lines, then a final clean mount.
+document.getElementById("btn-cycle").addEventListener("click", () => {
+  for (let i = 0; i < 5; i++) { doDispose(); doMount(); doDispose(); }
+  doMount();
+});
+
+doMount();

package/src/app-nameplate.js

@@ -0,0 +1,9 @@
+import part from "./parts/nameplate.js";
+import { mount } from "./framework/index.js";
+
+// Dev example app for the nameplate demo (src/parts/nameplate.js). The
+// `new Worker(new URL(...))` call must stay inline here so Vite bundles the worker.
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./nameplate-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/app-text-smoke.js

@@ -0,0 +1,10 @@
+import part from "./parts/text-smoke.js";
+import { mount } from "./framework/index.js";
+
+// Dev-only example app for the text-smoke part (src/parts/text-smoke.js). Identical
+// wiring to app-demo.js — this fixture exists to run the resolved-text build through
+// the real Vite Web Worker path (see scripts/check-app.mjs text-smoke.html).
+mount(part, {
+  createWorker: (name) =>
+    new Worker(new URL("./text-smoke-worker.js", import.meta.url), { type: "module", name }),
+});

package/src/bracket-worker.js

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

package/src/framework/app.css

@@ -161,9 +161,22 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   font-size: 15px; line-height: 1;
   display: flex; align-items: center; justify-content: center;
 }
+#viewbar .pf-cutaway-actions { display: flex; gap: 4px; }
+#viewbar .pf-cutaway-actions[hidden] { display: none; }
+#viewbar .pf-cutaway-actions button { width: auto; min-width: 56px; padding: 0 8px; }
+#viewbar button:disabled { opacity: .38; cursor: not-allowed; }
+#viewbar button:disabled:hover { color: var(--pf-muted-2); background: transparent; }
 #viewbar button:hover { color: var(--pf-text); background: var(--pf-surface-2); }
 #viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); }
 
+@media (max-width: 680px) {
+  #panel { max-height: calc(100vh - 80px); }
+  #viewbar {
+    top: auto; right: auto; bottom: 12px; left: 50%;
+    transform: translateX(-50%);
+  }
+}
+
 #busy {
   position: fixed; inset: 0; z-index: 20; pointer-events: none;
   display: none; flex-direction: column; align-items: center;
@@ -206,17 +219,21 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 .irrelevant:hover { opacity: 0.7; }
 .section-hidden { display: none; }
 
-/* hover feature-label tooltip (selection/hover.js) */
-#pf-hover-tip {
+/* shared viewer tooltip */
+#pf-hover-tip,
+.pf-hover-tip {
   position: fixed; z-index: 30; pointer-events: none; display: none;
-  padding: 4px 9px; border-radius: 8px; max-width: 260px;
+  padding: 4px 9px; border-radius: 8px; max-width: min(260px, calc(100vw - 16px));
   background: var(--pf-surface); border: 1px solid var(--pf-border);
   color: var(--pf-text-strong); font-size: 12px; line-height: 1.35;
   box-shadow: 0 2px 4px -2px rgb(0 0 0 / .15);
 }
-#pf-hover-tip.show { display: block; }
-#pf-hover-tip .pf-hover-sub { color: var(--pf-muted); font-size: 11px; margin-left: 7px; }
-#pf-hover-tip .pf-hover-sub:empty { display: none; }
+#pf-hover-tip.show,
+.pf-hover-tip.show { display: block; }
+#pf-hover-tip .pf-hover-sub,
+.pf-hover-tip .pf-hover-sub { color: var(--pf-muted); font-size: 11px; margin-left: 7px; }
+#pf-hover-tip .pf-hover-sub:empty,
+.pf-hover-tip .pf-hover-sub:empty { display: none; }
 
 /* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
    laid out like a chat message (avatar + text). Slides/fades in when shown; themed. */

package/src/framework/cutaway-controls.js

@@ -0,0 +1,155 @@
+import { attachButtonTooltips } from "./tooltip.js";
+
+const UNSUPPORTED_TITLE = "Cutaway requires a stencil-capable WebGL context";
+const BUTTON_ATTRIBUTES = [
+  "type",
+  "aria-pressed",
+  "aria-label",
+  "title",
+  "disabled",
+  "aria-description",
+];
+
+const noop = () => {};
+
+function runCleanupSteps(steps) {
+  const errors = [];
+  for (const step of steps) {
+    try { step(); } catch (error) { errors.push(error); }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, "cutaway control cleanup failed");
+  }
+}
+
+function actionButton(label, title) {
+  const button = document.createElement("button");
+  button.type = "button";
+  button.textContent = label;
+  button.title = title;
+  button.setAttribute("aria-label", title);
+  return button;
+}
+
+function captureAttributes(element, names) {
+  return new Map(names.map((name) => [name, {
+    present: element.hasAttribute(name),
+    value: element.getAttribute(name),
+  }]));
+}
+
+function restoreAttributes(element, attributes) {
+  for (const [name, { present, value }] of attributes) {
+    if (present) element.setAttribute(name, value);
+    else element.removeAttribute(name);
+  }
+}
+
+// Wire the optional cutaway button to the viewer and create its contextual
+// actions. Hosts that omit the primary button opt out of all DOM behavior.
+export function attachCutawayControls(viewer, { cutaway: button } = {}, { tooltip } = {}) {
+  if (!button) return { reset: noop, detach: noop };
+
+  const canvas = viewer.domElement;
+  const addedCanvasTabIndex = !canvas.hasAttribute("tabindex");
+  const addedCanvasLabel = !canvas.hasAttribute("aria-label");
+  if (addedCanvasTabIndex) canvas.tabIndex = 0;
+  if (addedCanvasLabel) canvas.setAttribute("aria-label", "3D part viewer");
+
+  const hostButtonAttributes = captureAttributes(button, BUTTON_ATTRIBUTES);
+  const hostButtonDisabled = button.disabled;
+  const hostButtonOn = button.classList.contains("on");
+
+  const actions = document.createElement("span");
+  actions.className = "pf-cutaway-actions";
+  const flipButton = actionButton("Flip", "Flip cutaway direction");
+  const resetButton = actionButton("Reset", "Reset cutaway plane");
+  actions.append(flipButton, resetButton);
+  const tooltipBinding = tooltip
+    ? attachButtonTooltips(tooltip, [button, flipButton, resetButton].map((element) => ({ element })))
+    : null;
+
+  button.type = "button";
+  button.setAttribute("aria-pressed", "false");
+  if (!tooltip && !button.hasAttribute("title")) button.title = "Toggle cutaway view";
+
+  const supported = viewer.cutawaySupported();
+  if (!supported) {
+    button.disabled = true;
+    if (!tooltip) button.title = UNSUPPORTED_TITLE;
+    button.setAttribute("aria-description", UNSUPPORTED_TITLE);
+  }
+
+  button.after(actions);
+
+  function sync() {
+    const enabled = supported && viewer.cutawayEnabled();
+    button.setAttribute("aria-pressed", String(enabled));
+    button.setAttribute(
+      "aria-label",
+      supported ? (enabled ? "Disable cutaway" : "Enable cutaway") : UNSUPPORTED_TITLE,
+    );
+    button.classList.toggle("on", enabled);
+    actions.hidden = !enabled;
+    tooltipBinding?.sync();
+  }
+
+  let detached = false;
+  function disable() {
+    if (detached) return;
+    const restoreFocus = actions.contains(document.activeElement);
+    viewer.setCutawayEnabled(false);
+    sync();
+    tooltipBinding?.hide();
+    if (restoreFocus) button.focus({ preventScroll: true });
+  }
+
+  const onToggle = () => {
+    viewer.setCutawayEnabled(!viewer.cutawayEnabled());
+    sync();
+  };
+  const onFlip = () => viewer.flipCutaway();
+  const onReset = () => {
+    viewer.resetCutaway();
+    sync();
+  };
+  const onEscape = (event) => {
+    if (event.key !== "Escape" || !viewer.cutawayEnabled()) return;
+    event.preventDefault();
+    disable();
+  };
+  const onCanvasPointerDown = () => canvas.focus({ preventScroll: true });
+
+  button.addEventListener("click", onToggle);
+  flipButton.addEventListener("click", onFlip);
+  resetButton.addEventListener("click", onReset);
+  for (const element of [canvas, button, flipButton, resetButton]) {
+    element.addEventListener("keydown", onEscape);
+  }
+  canvas.addEventListener("pointerdown", onCanvasPointerDown);
+  sync();
+
+  return {
+    reset: disable,
+    detach() {
+      if (detached) return;
+      detached = true;
+      runCleanupSteps([
+        () => button.removeEventListener("click", onToggle),
+        () => flipButton.removeEventListener("click", onFlip),
+        () => resetButton.removeEventListener("click", onReset),
+        ...[canvas, button, flipButton, resetButton]
+          .map((element) => () => element.removeEventListener("keydown", onEscape)),
+        () => canvas.removeEventListener("pointerdown", onCanvasPointerDown),
+        () => { if (addedCanvasTabIndex) canvas.removeAttribute("tabindex"); },
+        () => { if (addedCanvasLabel) canvas.removeAttribute("aria-label"); },
+        () => tooltipBinding?.detach(),
+        () => actions.remove(),
+        () => restoreAttributes(button, hostButtonAttributes),
+        () => { button.disabled = hostButtonDisabled; },
+        () => button.classList.toggle("on", hostButtonOn),
+      ]);
+    },
+  };
+}