-kit.zip`: `README.txt` (the thickness each material assumes, the kerf applied, a scale check per piece, the colour or DXF-layer legend, every 2-D check that warned), `parts.csv`, `sheets/-mm/sheet--of-.svg` (the pieces laid out on the user's stock), `parts/[-xN].svg` (one per distinct piece; identical pieces merge) and `print/[-xN].stl` or `.3mf` (the printed parts, in their export pose). With `destination: "service"` each piece is a cut-only `.dxf` plus a `-marks.dxf` for its score and engrave lines, and the DXF sheets are for reference. Every `options` key is optional: `destination` (`"own-laser"`, the default, or `"service"`), `kerf` (0–0.5 mm, applied to the cut lines only), `stock: [{ group, size: [w, h] }]` (a row's `sheet.group`; a `"*"` entry sizes every group that has no entry of its own; 300 × 300 mm when `stock` is omitted), `margin` (5 mm), `spacing` (3 mm), `printFormat` (`"stl"` or `"3mf"`) and `sets` (1–20). The main entry exports `EXPORT_FORMATS`, `KIT_DEFAULTS`, `validateKitOptions` and `KIT_OPTIONS_ERROR` for a host that draws its own options screen. An option the kit cannot honour — an unknown key, a kerf that closes a slot, a piece bigger than an own laser's sheet, a margin that leaves no room on the sheet, a stock entry naming no group, more than 200 pieces or 50 sheets of one material — rejects with a message starting `cut kit options:`: the user's setting to change, not the part's code. - `runtime.warmExportKernel() → Promise` — pay OCCT's cold boot *before* an export needs it. Because STEP is pinned to OCCT and OCCT's ~11 MB WASM loads on its first job, a part whose preview ran on Manifold pays that whole boot inside its first STEP export — the user waits having just asked for a file, and a host with an export timeout can trip it. Call this when an export becomes likely (your download dialog opening) and the wait lands somewhere harmless instead. Best-effort: resolves `true` once the kernel is up, `false` on any failure or teardown, never rejects, and is a cheap no-op once warm. It costs a speculative ~11 MB download, so fire it on a real signal of intent rather than on mount. Pass `onDownload({ data, filename, mime })` to `mount()` to receive the exported bytes yourself (e.g. to download from a different origin) instead of partforge's own DOM download. - `fontCatalog` — a provider backing every `type: "font"` control in the part: - `search(query, { limit }) → Promise`, where a `FontFamily` is `{ id, family, category, variants: [{ variant, label, url, bytes }], menuUrl }`. `url` is what the picker writes into `params`; `menuUrl` is a name-only subset used to draw the list row. - `describe(source) → { family, variant } | null` — optional reverse lookup so the closed control can name a face whose URL carries a hashed filename. partforge ships no provider — a host supplies one, and without it every font control renders as a URL field. - `imageCatalog` — a provider backing every `type: "image"` control in the part: `{ search(query, { limit }) → Promise, describe?(source) → { label, width, height } | null }`, where `ImageAsset` is `{ id, label, url, width, height, thumbUrl }`. With no provider a `type: "image"` control degrades to a URL field. - `onAssetUpload(blob, { kind, key, filename }) → Promise` — the drop target shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files into a part", below) calls this with the converted artifact after a drop, paste, or file-picker choice, and writes whatever it resolves to into the param. `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob, or the original file for a font — never the user's raw drop; `kind` is `"image"`, `"vector"`, or `"font"`; `key` is the param the drop landed on, which is what lets a host give each control a stable destination of its own rather than reconciling uploads against the part afterwards. Must resolve to a non-empty source string (an `https:` URL, or a host-defined `pfc-asset:` or `pfc-tree:` token); anything else is treated as a contract violation and reported through the control's own error line, not written into the param. Omit it and the converted bytes land straight in the param instead — the path a host that cannot fetch URLs (the partforge-cloud sandbox) needs, not a degraded fallback. A rejection is likewise reported through the control's error line, and the widget keeps the converted artifact so a retry costs a network call, not a re-decode/re-parse. **Showcase capture (the mount handle).** The handle can also render the user's *current* framing offscreen at a resolution independent of the window size and devicePixelRatio — for gallery/preview images, where grabbing the live canvas would be capped at the viewer pane's pixel size: - `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {}) → string | null` — one offscreen render from the live camera's pose (position, up, and orbit target — not a canonical pose) with the live viewport's aspect ratio, `size` px on the long edge (clamped into `[256, maxTextureSize]`). Renders with 4× MSAA and the same camera-relative capture lighting as `captureViews`, so the result is print-quality even from a small window on a 1× display. Returns a `data:image/jpeg;base64,…` string, or `null` when the runtime is disposed or nothing is built/visible yet — it never throws. `hideGrid: false` keeps the floor grid so the capture matches the on-screen look exactly. The live view is untouched: the camera never moves, and lights/grid/render target are restored after the render. Measurement-mode dimensions render directly in the scene, so a dimensioned capture needs no special handling — enable measure mode (`runtime.measure.setEnabled(true)`) and call `captureCurrent()`; the dims are just part of the rendered frame. With the cutaway on, the capture shows the section the way the user sees it — the part clipped, its cut faces hatched — but never the cutaway's translucent plane or its handles, which are controls, not the part (the same holds for `captureViews` and the view style popover's thumbnails). `recenter: true` centres the part: the capture becomes the largest centred sub-window of the current framing that still holds every visible vertex (equal margins on both axes, rendered at the full `size` resolution through a view offset, so it is a pixel-exact crop of what the user framed — same perspective, no re-encode). The extent is the projection of the actual mesh vertices, not a bounding box, so it is exact at any angle. The framing is kept as-is when the geometry runs past any frame edge (a user who zoomed in past the part's silhouette cropped it on purpose), when it is already centred, or when measurement dimensions are pinned (their labels sit beside the part and could otherwise be cut off). - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle counterpart (fixed view directions, each fitted so the visible assembly's projected geometry fills 90% of the frame and sits centred in it; 1024², grid hidden). Sized for feeding a vision model, not for display; use `captureCurrent` for showcase images. ### `runtime.projection` `{ get(), set(mode), onChange(cb) }` where `mode` is `"perspective"` or `"orthographic"`. The projection is **automatic**, the way Fusion 360's "Perspective with Ortho Faces" and Blender's "Auto Perspective" work: clicking one of the view cube's six **face** views (on the cube, or through its hidden per-face keyboard buttons) tweens there and settles into orthographic at the end of the tween, with no size jump; an edge, corner or iso view is perspective (an orthographic view switches back as that tween starts). In a face view, **pan and zoom keep it orthographic; the first rotation** (the view direction leaving the face axis by more than half a degree) swaps back to perspective, keeping the part's apparent size. Animation camera cues never switch into orthographic. There is no user control for it. `set("orthographic")` still works for a host, and is left the same way — by the first rotation — and `onChange` hears every automatic swap. It is **not persisted** across reloads (a reload opens in perspective); a remount carries it in `viewerState`, but only with a face-view camera — carried with any other camera it restores perspective. Drives the **live view** and `captureCurrent` only — `captureCanonicalViews`, `renderMeshPayloads`, and the CLI's `partforge render` stay perspective unconditionally, so agent-facing output does not depend on the live view. The orientation cube and the view style button (in `#viewbar`, which Sketch hides) are hidden while Sketch (annotate) mode is active, but that only governs *user-driven* view changes — the framework does not police programmatic ones. The ink is a transparent overlay and the WebGL canvas keeps rendering beneath it, so a host that calls `runtime.projection.set()` mid-sketch **visibly re-frames the 3D view underneath ink the user may still be drawing**: the elements stay where they were laid down while the model shifts out from under them, and the sketch that gets sent is misaligned, not merely mis-labelled. Deliberately unguarded, the same way it's always been free to call `setCameraState` during Sketch. ### `runtime.renderMode`, `runtime.environment`, `runtime.renderViews`, `runtime.declaresMaterials` For an embedder driving realistic mode from its own UI instead of (or in addition to) the generated view style button above: - `runtime.renderMode` — `{ get(), set(mode), onChange(cb) }` where `mode` is `"cad"` or `"realistic"`. `set()` resolves to the mode actually in effect — `"cad"` if the realistic environment's assets fail to load — and `onChange` receives `{ mode, busy, error }` so a host can show its own loading/error state. Same shape as `runtime.projection`. It drives the live view, and `runtime.captureCurrent()` follows it by default (a "capture from viewer" captures what the user sees). It never changes what an agent sees: `runtime.captureViews()` is always CAD, in either live mode, and a realistic agent render is only ever an explicit `renderViews(…, { renderMode: "realistic" })`. - `runtime.captureCurrent({ renderMode })` — pins the showcase capture's look instead of following the live view. `"cad"` always works. `"realistic"` from a CAD view works only once the current environment's assets have loaded (the call is synchronous and can't wait for them); before that it falls back to the live look. Use `renderViews` when realistic must be guaranteed. - `runtime.environment` — `{ get(), set(id), onChange(cb), list() }` for the realistic environment (`"studio"` | `"workshop"` | `"print-bed"` | `"outdoor"`, per "Materials and appearance" above). `list()` returns every environment as `[{ id, label }]`, for building your own picker. `set()` resolves to the id actually in effect; a failed switch while realistic is showing reverts to the environment still on screen, and `onChange` hears the revert too. - `runtime.declaresMaterials` — `true` when any sub-part names a `display.material`. A part with none still supports realistic mode (every sub-part renders as a PLA print in its CAD colour, a laser sheet part as its stock — "Sheet parts default to their stock"), so use this to decide whether to surface your own realistic control at all, not whether it works. Feature lines are not a preference: they draw whenever `runtime.renderMode` reads `"cad"` and never while it reads `"realistic"` — there is no switch to drive independently of it. - `await runtime.renderViews(viewNames, { renderMode? })` — the appearance-aware sibling of `runtime.captureViews` (canonical angles, framed to the visible assembly, grid hidden): `{ renderMode: "cad" }` (the default) is exactly `captureViews` — CAD whatever the live view shows — and `{ renderMode: "realistic" }` borrows the realistic look for the capture — waiting on the chosen environment's assets — **without** switching the live view. Rejects if the realistic assets fail to load. Both preferences round-trip through `mount()`'s `viewerState`: a previous mount's `runtime.getViewerState()` carries `viewerState.renderMode` (`"cad"` or `"realistic"`) and, only when the viewer's environment was actually CHOSEN rather than merely defaulted from `meta.environment`, `viewerState.environment`. `renderMode` reports the mode the user is **headed for**, not only the one on screen: a realistic restore or switch that's still loading reports `"realistic"`, so a host that remounts on every edit (as an embedder applying edits by remounting typically does) doesn't drop the in-flight choice — a load that ultimately fails still settles back to `"cad"`. Pass `viewerState` back into the next `mount()` call to resume both where the previous mount left them; omit it on a first mount and the viewer restores its own persisted choice instead, the same way it does for the camera. ### The annotation payload's camera block `onAnnotationSend(payload)` receives a `camera` block in two frames — `world` (replays exactly against the build that produced it) and `parts` (pinned to the CAD geometry, so it survives a later rebuild's bbox recentring; reread a sketch's camera intrinsics from `parts`, not `world`, once the model has been rebuilt). `ANNOTATION_VERSION` is **3**: both frames carry `projection: "perspective" | "orthographic"`, and under an orthographic camera `fov` is `null` while `orthoHeight` gives the frustum's world height instead. (v1 had `fov` only, and predates the projection toggle; v3 replaced the payload's `strokes` array with `elements` — typed pen/line/rect/ellipse shapes rather than raw ink paths — a change orthogonal to this camera block.) The payload is self-describing for LLM consumers: a top-level `summary` joins every element's plain-language `description`, and `frames` is a legend mapping each payload path to its coordinate convention (element `params` are stage-space, anchor `screen`s are per-axis normalized 0..1, descriptions are viewport percentages — `viewport.aspect` bridges them). Each element carries an `id` (`"e1"`, `"e2"`, …) for unambiguous reference in replies, `rotDeg` alongside the radian `rot`, and erased spans rendered into the description in each type's own vocabulary ("erased top edge", "erased arc 36°–126°"); each anchor of a gapped element carries the `run` index of the visible fragment it sits on. **Reconstructing rays from a sketch payload.** Every anchor also carries `ray: { origin, dir }` — a pick ray in the **parts frame** (mm origin, unit direction), computed from the live camera at send time and rounded to 4 decimals; it is omitted when `camera.parts` is `null` (no meshes at send time — the same condition under which no `hit` can exist). Unlike `hit`, the ray is present even where the stroke crosses empty space, so any anchor can be projected onto a construction plane. For screen points that have no anchor (a circle's rim, a grid over a region), `partforge/oracle` exports `annotationRay(payload, screenOrAnchor, { frame? })` — the same ray, reconstructed from the payload's camera block (perspective and orthographic both) — and `rayPlane(ray, plane)` intersects either kind of ray with `{ point, normal }` or the shorthand origin planes `"xy" | "yz" | "zx"`, returning `{ point, t }` in mm or `null` on a parallel / behind-origin miss (the same miss semantics as `hit: null`). End to end: ```js import { annotationRay, rayPlane } from "partforge/oracle"; const anchor = payload.elements.find((e) => e.id === "e3") .anchors.find((a) => a.at === "center"); const hit = rayPlane(anchor.ray ?? annotationRay(payload, anchor), "xy"); // → boss where the sketched circle's center points, on the z=0 plane: // k.prism({ points: circleProfile(r_mm, [hit.point[0], hit.point[1]]), h }) ``` **The markup convention (`demo.html` is the canonical copy-me page):** `` carries `class="pf-shell"`, the flex row that lays the viewer column next to the rail. `#app` (`class="pf-stage"`) *is* that viewer column, and now contains the floating chrome (`#topbar`, `#viewbar`, `#busy`) as absolutely-positioned siblings of the canvas, not page-level overlays. `#panel` (`class="pf-rail"`) is a full-height rail docked to the right edge, split into three children — `.pf-rail-head` / `.pf-rail-body` / `.pf-rail-foot` — of which head and foot are flex-fixed and only the body scrolls: put your heading in the head and the download row in the foot so the export buttons never scroll out of reach. The rail's drag/collapse seam is created by `rail.js` itself; don't add markup for it. This isn't decorative — get the head/body/foot split wrong and either the export buttons scroll away or a tall parameter list pushes them off-screen. See `docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md` for why the rail is shaped this way (resize/collapse behavior, breakpoints, the design rationale). **Keyboard (the seam is `role="separator"`, focusable, `tabIndex=0`):** | Key | Action | |---|---| | ← | widen the rail 16px (64px with Shift). No-op while collapsed. | | → | narrow the rail 16px (64px with Shift), clamped at the 240px minimum — never collapses. No-op while collapsed. | | Home | jump to the 240px minimum, animated. Reopens even while collapsed. | | End | jump to the clamped maximum (half the shell, capped at 560px), animated. Reopens even while collapsed. | | Enter / Space | toggle collapse — collapses if open; reopens at the remembered width if collapsed. | | double-click (on the seam) | reset to the 288px default, animated, and opens if collapsed. | Arrow keys move the **separator**, not the pane — standard `role="separator"` semantics, and why ← *widens* a right-hand rail. `Cmd`/`Ctrl`/`Alt` held with an arrow key passes through untouched (those are OS/browser-reserved combos, e.g. back navigation or window-switching); `Shift` alone still applies the larger step. Collapsed, the two arrow keys are deliberate no-ops rather than a reopen gesture — reopening would otherwise silently discard the remembered width and clamp to the minimum, and "press an arrow, get narrower" reads backwards for a rail that's already shut. Home/End and Enter/Space/double-click are exempt from that rule and always reopen, since jumping to an explicit width or toggling is an unambiguous, deliberate gesture either way. A held arrow-key repeat suppresses the 150ms width transition for the whole repeat window (not just one keydown), matching what happens during a drag. Legacy id-only markup (predating this class scheme) still renders: `app.css` keeps `:not(.pf-*)` fallbacks (`#app:not(.pf-stage)`, `#panel:not(.pf-rail)`, and placement-only ones for `#topbar`/`#viewbar`) that reproduce the old floating-card look — `:not()` rather than a plain id rule because an id selector outranks a class. New apps should still use the classed markup above; the fallback exists for pages that predate it, not as a second supported style. A host that builds its own DOM instead of using `mount`'s markup (e.g. an editor embedding the viewer/rail inside a larger UI) can adopt the same layout by importing **`partforge/chrome.css`** directly — it's deliberately class-based and id-free for that reason. It expects `partforge/tokens.css` to already be loaded for its `--pf-*` custom properties, and expects the host to size `.pf-shell` itself (`mount`'s own `app.css`, which `@import`s both, does both of these for you already). `#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 controls, including the rail toggle, without relying on an ID by passing them beside the other chrome references — and can pass the rail itself as `elements.rail` instead of relying on `#panel`: ```js mount(part, { createWorker, elements: { rail, chrome: { reframe, cutaway, measure, theme, railToggle, }, }, }); ``` `rail`/`chrome.railToggle` are both optional; a host with no rail markup gets a no-op (the resize/collapse behavior below simply doesn't attach). **Constraint:** the rail element must be a direct child of the positioned `.pf-shell` — the resize seam is created and positioned against `rail.parentElement` by default, so an extra wrapper div between them (common in a React layout) puts the seam against the wrong ancestor and silently breaks `[data-pf-dragging] .pf-stage`. A host that can't make the rail a direct child of `.pf-shell` must also pass `elements.shell` pointing at the real positioned ancestor: ```js mount(part, { createWorker, elements: { rail, shell, chrome: { railToggle } }, }); ``` > 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 > ship one, add it to `build.rollupOptions.input` in `vite.config.js`. **Styling hooks:** the rail/stage layout and palette are both plain `--pf-*` custom properties from `partforge/tokens.css`, overridable on `:root` (or `:root[data-theme="light"]`) without touching `chrome.css`. Layout/shape tokens added alongside the rail: `--pf-sans`, `--pf-rail-w`, `--pf-rail-pad`, `--pf-radius-control`, `--pf-radius-pill`, `--pf-shadow-float`, `--pf-shadow-rail`. The dev demos self-host Geist and Geist Mono (`@fontsource-variable/geist(-mono)`, a `devDependency`, imported from each `app-.js` — see `src/app-demo.js`) so a standalone forge looks like the finished product; the published library ships no font files, and a consumer that loads none falls through `--pf-sans`/`--pf-mono` to system stacks by design. ### Developing against a local (linked) partforge A normal `npm install partforge` needs no extra config. But if you `npm link` a local partforge checkout (to co-develop the framework), it lives **outside your project root**, so Vite refuses to serve its files — including the Manifold/OCCT WASM, which fails with a 403 and the kernel never boots. Allow-list it in your `vite.config.js`: ```js server: { fs: { allow: ["./", "../partforge"] } } // path to your linked checkout ``` (Geometry/asset imports are already worker-safe; this is purely Vite's dev-server file access. It's harmless to leave in when partforge is a normal install.) --- ## Testing a part Tests run under **Node 24** (`nvm use` first; the default shell Node is too old) via `npx vitest run`. The oracle half of this surface — `measure`, `verify`, gaps, match scoring — is also published on its own as `partforge/oracle` (browser-safe import closure); `partforge/testing` re-exports it, so either import works. Build geometry directly off your part with a Manifold kernel: ```js import { bootManifoldKernel, resolveDerived } from "partforge/testing"; import part from "../src/parts/.js"; const k = await bootManifoldKernel(); const solid = part.parts..build(k, part.defaults, resolveDerived(part, part.defaults)); expect(solid.toMesh().triangles).toBeGreaterThan(0); ``` **Collision check (assemblies).** `assemblyOverlaps` builds every sub-part of a view in its assembly pose and returns any interpenetrating pair with its overlap volume — parts meant to fit (e.g. seated in a pocket) read ~0 and don't trip it: ```js import { assemblyOverlaps } from "partforge/testing"; test("assembly has no interpenetrating parts", () => { expect(assemblyOverlaps(k, part, "", {})).toEqual([]); // [{a,b,volume}] on failure }); ``` See `test/framework/assembly.test.js` for a real example, and `test/framework/jobs.test.js` for exporting through the job loop. **OCCT tests** (STEP / B-rep) boot the OCCT kernel with `bootOcctKernel()` from `partforge/testing` (in a `beforeAll`) — see `test/occt-backend.test.js`. **OCCT and Manifold must not boot in the same process** — keep OCCT-booting tests in their own files (vitest isolates files). --- ## 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/.js [view] # geometric facts npx partforge render src/parts/.js [view] # canonical-angle PNGs `measure` prints a report: 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, and a **near-miss** check — sub-part pairs whose surfaces come closer than 0.5 mm without touching (`near-misses:` in the output; reported for judgment, never an exit-code gate by itself). It exits non-zero if any sub-part isn't watertight or any parts interpenetrate — so it doubles as a CI/agent gate. Add `--json` to also dump the report as JSON on stdout, or `--out report.json` to write it to a file (nothing is written otherwise). (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. Treat renders as complementary evidence, not a ruler: use several views for complex parts and the interactive viewer's cutaway for hidden interfaces, but rely on `measure` / `verify` for dimensions, contact, and clearance. Headlessly, `renderViewImages(kernel, part, view, opts)` from `partforge/testing` returns the same stills in memory as `[{ angle, png }]` (PNG buffers; `renderViews` writes them to disk through it). Its `style` option is `"cad"` (default) or `"thumbnail"`; `style.view` is only a default, so explicit `views` always win. The `measure` function is also exported for vitest (boot a Manifold kernel as in "Testing a part", then `measure(kernel, part, "")`): import { measure } from "partforge/testing"; test("part is sound", () => { const r = measure(kernel, part, ""); expect(r.ok).toBe(true); expect(r.subparts[0].holes).toBe(1); // e.g. expects one bore }); ## Linting `partforge lint` statically validates a PartDefinition without booting a geometry kernel. It runs in milliseconds and catches the authoring mistakes that otherwise surface only at runtime — or, worse, not at all. ```bash npx partforge lint src/parts/.js [--params '{"h":40}'] [--json] [--out f] [--strict] ``` Exit 0 when clean, 1 when any **error** finding is present; `--strict` also fails on warnings. `partforge measure` runs the error tier automatically before booting a kernel — pass `--no-lint` to skip it. The same check is available programmatically and in the browser: ```js import { lintPart } from "partforge/lint"; const { ok, errors, warnings } = lintPart(part, { params }); ``` `lintPart(part, { sources })` optionally takes the part's own source files (`{ files: { path: text }, entrypoint }` — `entrypoint` names the file holding the `PartDefinition`, defaulting to the first key) and unlocks a ninth rule group that reads the source itself, catching the defects evaluation erases. The CLI passes the module's own file automatically, so `partforge lint`/`measure` always run it; a programmatic caller that omits `sources` (or hands over a malformed one) just gets no findings from that group. Source findings carry `file` and `line` on top of the standard shape, and `SOURCE_RULE_IDS` names them — a host that gates rendering on lint errors uses it to keep them reported but non-blocking. `lintPart(part, { vectorDocs })` optionally takes the RAW parsed JSON of the part's declared `vectors` files — `{ name: parsedDocument }` — and unlocks the two vector rules that need to read `units`/`shapes` (below). Lint is pure and synchronous by contract, so it never fetches these itself: `vectors.js`'s `resolveVectorDocs(part.vectors)` does the async resolve (sharing the same bytes memo `resolveVectors` uses, so `lint` ahead of `measure` costs no extra fetch) and the caller passes the result in, exactly the way `sources` already works. Both built-in callers do, by different routes: `bin/cli.js` awaits `resolveVectorDocs` for `partforge lint|measure`, while the worker's `lint` job uses the synchronous `cachedVectorDocs`, which reads only documents already in the resolver's memo and never starts a fetch. That difference is deliberate — a CLI run can afford to wait for a file, but the in-app lint must stay instant and offline, because a host runs it on every edit and `fetch` has no timeout. In practice a build has loaded the artwork long before anyone reads a lint report, so both rules are live in the app too; before the first build they are simply silent. Omit `vectorDocs`, or hand over something malformed, and those two rules just stay silent rather than guess. `partforge/lint` has **zero runtime dependencies** and never imports a geometry kernel or the DOM viewer, so it runs unchanged in Node, a Web Worker, a sandboxed iframe, and Deno. A worker also answers `{ type: "lint", params }` with `{ type: "lint-report", report }` without booting its kernel. **Findings** carry the same guarantees as verify's checks — a self-contained `hint` on every one, and a stable `pattern` id where an ERROR-PATTERNS.md entry applies: ```js { rule: "features-requires-sliders", severity: "error", message: "section \"flange\" feature 0 has no `sliders` array", hint: "A `features` entry must carry a `sliders` array …", path: "parameters[1].features[0]", pattern: "features-missing-sliders" } ``` `path` is a JS accessor path rooted at the PartDefinition — `parameters[1].features[0]`, `defaults.bore`, `parts.spacer.views[0]`, `parameters[0].presets["M3"].od`. Findings about the definition as a whole use `""`. **Severity.** A finding is an `error` when the part is *provably broken* — it cannot behave as authored — whether or not that shows up as a thrown exception. Some error findings do correspond to a runtime throw (`build-throws`, `verify-expect-throws`), but others catch **silent** wrongness: `missing-meta-title`, `part-view-unknown`, `control-key-not-in-defaults`, `control-default-not-primitive`, `preset-key-not-in-defaults`, and `verify-unknown-subpart` all fire on parts that build, measure, and verify cleanly — a dead control that's silently unreachable, a view that renders nothing, or a `verify` expectation that's silently dropped so its gate never runs. That's still an error: the part doesn't do what its author wrote, the failure is just quiet instead of loud. Everything speculative or stylistic — lossy but not broken — is a `warning` and never blocks anything. Because `measure` runs the error tier as a gate (see below), a part with one of these silent defects now exits non-zero where it previously didn't; that's the fix working as intended, not a regression. ### Rule catalog **Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`, `missing-views`, `part-view-unknown`, `invalid-probes` (all errors); `view-unused`, `default-view-ambiguous` (warnings). `invalid-probes` fires when a declared `probes` block isn't an object of functions (see "Probes" above). **Parameter schema** — `features-requires-sliders`, `features-requires-on`, `control-key-not-in-defaults`, `control-default-not-primitive`, `preset-key-not-in-defaults`, `mixed-section-shape`, `duplicate-preset-name`, `duplicate-node-id`, `select-options-missing`, `select-default-not-in-options`, `log-scale-needs-positive-min`, `when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type`, `legacy-shape-widget`, `custom-control-widget-not-function`, `custom-default-not-json`, `custom-keys-not-in-defaults` (errors); `slider-range-excludes-default`, `unknown-control-field`, `duplicate-control-key`, `default-not-exposed`, `readout-unknown-derived-key`, `slider-refinement-invalid`, `group-depth`, `section-too-many-controls` (warnings). `mixed-section-shape` fires when a section mixes the new `controls` array with a legacy field (`advanced`, `toggles`, `features`, `presets`) — the two shapes can't coexist, since mixing them would make the render order arbitrary. Move the legacy entries into `controls` (a toggle becomes a checkbox control, `advanced` becomes a nested group, `presets` becomes `{ type: "preset" }` nodes), or drop `controls` and stay legacy. `custom-default-not-json` is `control-default-not-primitive`'s counterpart for a `type: "custom"` control, whose key may hold a JSON value (see "Custom controls"): it names the first member that is not one — `null`, a function, a class instance, a forbidden key, or a value past the 16 KB / depth-8 caps. `duplicate-preset-name` fires when the same preset name is declared twice (legacy `presets` and/or `{ type: "preset" }` nodes both count) — preset names are global to the part, and `verify()` expands one case per name and throws on a repeat, a worse place to find out. Rename one of them. `duplicate-node-id` fires when two panel nodes (sections, groups, or controls) share an `id` — the renderer keys its element and state maps on ids, and a collision silently cross-wires the two nodes. Rename one `id`, or drop it to use the positional default. `select-options-missing` fires when a `select`/`radio` control has no `options` array — with none the control renders empty and its parameter can never change. `select-default-not-in-options` fires when `defaults[key]` is not one of a `select`/`radio`'s option values (watch value types — `12` is not `"12"`) — without this the panel opens showing a value the user can never get back to. Add the value to `options`, or change the default. `log-scale-needs-positive-min` fires when a slider/number sets `scale: "log"` without a positive `min` — `log(0)` is `-Infinity` and the thumb-to-value mapping breaks, so raise `min` above 0 or drop `scale`. `when-key-not-in-defaults` and `when-unknown-operator` walk every authored `when` (on a control, a group, a preset, a readout, or a section itself) — `allOf`/`anyOf`/`not` recurse — and check each condition against the two things that make it real: the param key must be one `defaults` actually declares, and each comparison operator (`{ gt: 0 }`, `{ in: [...] }`, …) must be one `evalWhen` recognises. Both are silent failure modes — an unknown key reads `undefined` and an unknown operator is treated as false, so either way the condition is always false and the node never shows — which is why both are errors rather than warnings. `legacy-shape-widget` fires when an entry in the legacy shape (`advanced`, `toggles`, `features`) sets `type`, or sets `control` to anything but `slider`, `number`, `text` or `textarea`. The legacy shape never reads `type`, so a `{ type: "select", options }` there renders as a slider and writes numbers into a key the build compares against strings; put such a control in a `controls` section, where `type` picks the widget. A boolean in the legacy shape belongs in `toggles`. `unknown-control-type` fires when an authored control's `type` (e.g. a typo like `"sldier"`) isn't one of the recognised widget types — the renderer skips a node with an unrecognised type entirely, so the control silently vanishes from the panel with no other sign anything is wrong. An unrecognised type's field list falls back to the common set (`key`, `type`, `label`, `description`, `hidden`, `when`, `whenFalse`) rather than an empty one, so this error carries the diagnosis instead of every field on the control — even ordinary ones like `label` — separately warning as `unknown-control-field`. This only applies to the authored `controls` shape — a legacy descriptor's `control:` value was never validated and still isn't. `readout-unknown-derived-key` checks a `{ type: "readout" }` entry's `derivedKey` against the keys `derive()` actually produces (resolved once against `defaults`) — a readout naming a key no group returns shows an em-dash forever, so it warns rather than errors. `slider-refinement-invalid` covers a slider/number's optional `ticks` (native datalist marks; combine with `snap: true` to quantize slider drags to the nearest tick) and `recommended` (an `[lo, hi]` band tinted on the track, with the value box warning outside it): a tick outside `[min, max]`, a `recommended` that isn't exactly `[lo, hi]` with `lo < hi`, or either of them combined with `scale: "log"` (ticks and the band render on a linear track only) all warn. `group-depth` warns when authored groups nest more than two levels deep — a section plus one inner fold is as deep as a 300px rail can stay readable. Flatten by promoting the innermost group to its own section, or folding its controls into the parent. `section-too-many-controls` warns when a section (authored or legacy, desugared to a common format) shows more than 12 visible controls — the budget is deliberately conservative, revisable against real LLM-authored parts. More than a dozen in one section reads as a wall; split into multiple sections, or hide internals (`hidden: true`). Grouping controls organizes them but does not reduce the count — the check recurses into groups — so a group alone doesn't bring a section back under budget. **Kernel API**, found by executing `build()` — and every declared probe, which shares build's `(k, p, d)` contract — against a geometry-free probe — `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`, `probe-throws`, `derive-throws`, `manifold-backend-uses-occt-op`, `build-runaway` (errors); `nondeterministic-build` (warning, from diffing two probe runs). **Verify block** — `verify-unknown-metric`, `verify-unknown-subpart`, `verify-bad-expr`, `verify-bad-pair-check`, `verify-unknown-process`, `verify-unknown-orientation`, `verify-expect-throws` (all errors). Note `_view` also accepts the pair-wise `contacts` / `clearance` keys, which are not scalar view metrics; they are validated by `verify-bad-pair-check`, matching `verify.js`'s own handling. **Animations block** — static validation of each view's `animations` block, without executing `build`: `animation-not-in-view` (a top-level `animations` key, which the runtime ignores), `animations-not-object`, `animation-tracks-or-steps`, `animation-unknown-param`, `animation-param-not-numeric`, `animation-keyframes-invalid`, `animation-value-out-of-range`, `animation-opacity-unknown-part`, `animation-opacity-range`, `animation-duration-invalid`, `animation-loop-invalid`, `animation-step-label-duplicate`, `animation-easing-unknown`, `animation-camera-invalid`, `animation-description-invalid`, `animation-autoplay-invalid` (all errors). One more rule does execute `build`, geometry-free: `animation-track-rebuilds` probes each track's endpoint values and emits a **note** when the animated param feeds real geometry, or when its pose can't be read (it queries the solid or passes a function), because such a track plays best-effort rather than at frame rate. Notes are informational — they never affect `ok`, `measure`, or `--strict`. **View-pose invariants**, found by running the geometry-free pose probe (the same one animation's `animation-track-rebuilds` uses) against each `views` entry, even when `build()` queries the solid — `view-entry-invalid` (an entry that is neither `true` nor a pose function), `views-and-place` (an author `place` beside a `views` map) and `view-pose-not-rigid` (an entry that reshapes instead of moving), `views-invalid` (a sub-part whose `views` is missing or neither a map nor an array; all errors), and `place-not-rigid` (legacy `place()` form: display vs. export placement may differ only by a rigid motion — translate/rotate — never a reshape; an error). A pose the probe cannot read (it queries the solid or passes a function) stays silent for these rules and earns the `animation-track-rebuilds` note. **Appearance** (all warnings) — `unknown-material` (a `display.material` the library does not know; the viewer draws it as if it named none — a PLA print in realistic mode, or for a laser sheet part its stock's look, per "Sheet parts default to their stock"), `unknown-environment` (`meta.environment` not known; realistic mode uses `studio`), `material-key-unknown` (a `display` key that is not colour, opacity, material or one of the six overrides; ignored), `material-override-clamped` (an override outside its range, or not a number; clamped). **Geometry imports** — `import-unknown-name` (a build calls `k.import` with a name the part's `imports` field doesn't declare — this throws at build time; lint reaches it in microseconds instead), `import-mesh-on-occt` (a declared STL/3MF import on a part that routes to OCCT — mesh imports need the Manifold backend; the message names whether `meta.backend` or a CAD op forced OCCT. Only extension-detectable `imports` sources — a `URL` or string path — are checked; a bytes/thunk source's format can't be known without resolving it, so lint skips it and the lazy `k.import` error entry at build time remains the runtime authority for those cases), `reference-unknown` (a sub-part's `reference` names no declared import) (all errors); `ref-metric-without-reference` (a sub-part's `verify.expect` uses a `ref*` metric — `refXorVolume`, `refVolumeDeltaPct`, `refBboxDelta` — but the sub-part declares no `reference`, so the deviation gate always reports status "skip") (warning). **Font controls** — `font-control-not-in-fonts` (a `type: "font"` control's `key` is not read by a function-form `fonts` — a static `fonts` object or a missing `fonts` field both provably can't depend on a param, so the picker changes a param and nothing else happens; the message names which of the two it is) (error); `font-source-scheme` (`defaults` holds a value for a font control that the control's own `allow` list would refuse — at build time it's swapped for `defaults[key]`, i.e. itself, so the part boots with no usable font; use a source `allow` accepts, or widen `allow`) (warning). **Image controls** — the sibling group for `type: "image"` controls, `images`, and `k.heightfield()`. `image-control-not-in-images` (a `type: "image"` control's `key` is never returned by `images` — unlike the font rule above, this one actually calls a function-form `images` with the control's key set to a sentinel value and checks whether the sentinel comes back out, because a picker only silently does nothing if the function ignores that specific key, not just any key; a static `images` object provably can't depend on any param, so it is skipped there — that is a different mistake, not this rule's business) (error); `heightfield-unknown-image` (a build calls `k.heightfield(name, opts)` with a string `name` absent from a **static** `images` object — skipped when `images` is a function, since its keys aren't statically known; an inline `{width, height, data}` grid as the first argument is never flagged, since that is a supported call shape, not a name) (error); `image-source-scheme` (`defaults` holds a value for an image control that the control's own `allow` list would refuse — same shape as `font-source-scheme` above, including the empty-string and raw-bytes exemptions from `image-source.js`) (warning). **Source rules** — the tenth group, which runs only when the caller hands over `sources` (above) — `control-default-not-literal` (a control's `defaults` entry is written as something other than a plain literal: an expression like `13 / 3`, an array or object, a template literal, a `0x10`/`1_000` spelling. Hosts persist a panel edit by rewriting that value's span in the source, so a spelling the rewriter cannot read means the user's edit is silently lost on reload — write a plain decimal/string/boolean literal, or move the computation into `derive()`) (error); `impure-source-token` (the source contains `Math.random`, `Date.now`, `performance.now`, or an argless `new Date()` — replace it with a parameter or a `derive()` output) (warning). Only a default a **visible** control is actually **bound** to is checked: an unbound non-primitive default (a lookup table, an array of hole positions) is never rewritten by a panel save and stays legal and unflagged, and so is the default of a statically hidden control (`hidden: true` on the control, or on an enclosing group or section) — it renders no widget, so there is no panel edit to lose, and `hidden: true` is the documented idiom for an internal constant. A `when`-conditioned control is *not* hidden — it can appear, so its default is checked. `impure-source-token` is warning-tier because the behavioral `nondeterministic-build` probe stays the error authority on impurity — the source scan is the wider net that also catches an impure value stable within one probe pass. It scans `.js`/`.mjs` files only (prose in a `README.md` is not a build), and code only within them (comments and string/template *interiors* are blanked first), so an impurity token inside a `${…}` interpolation is not seen. It emits one finding per (file, token) pair, carrying the occurrence count and the first occurrence's line, rather than one per occurrence. **Vector geometry** — `vector-unknown-name` (a build calls `k.vector2d` with a name the part's `vectors` field doesn't declare — this throws at build time; lint reaches it in microseconds instead; needs no `vectorDocs`), `vector-size-missing` (a `k.vector2d` call declares none of `{ width }`, `{ height }`, or `{ fit }` **and** the named file's `units` is `"artwork"` — unlike `k.text2d`'s cap-height `size`, artwork units carry no physical meaning, so there is no safe default to fall back on; an `"mm"` file's coordinates already are millimetres, so a size is genuinely optional there), `vector-unknown-shape` (a `k.vector2d(name, { shape })` call names a shape the file's `shapes` object doesn't contain), and `vector-control-not-in-vectors` (a `type: "vector"` control whose key never reaches `vectors:` — either because `vectors` is a static object, which cannot read a param at all, or because the function form never returns the picked value; the picker then changes a param and nothing else) (all errors). `vector-unknown-name` runs only for a static `vectors` object, whose names are statically knowable; for the function form `vector-control-not-in-vectors` asks the answerable question instead, by calling the function with a sentinel — the same complementary split `heightfield-unknown-image` and `image-control-not-in-images` use. `vector-size-missing` and `vector-unknown-shape` need `vectorDocs` (above) to read the file's `units`/`shapes` — without it, both stay silent rather than fire on every correct millimetre file or guess at shape names. All three call rules judge the argument values the probe resolves under the part's default params, the same basis `import-unknown-name` uses; a call that only goes wrong for non-default params still fails correctly at build time. **Sheet parts** — `sheet-invalid`, `sheet-thickness-invalid`, `sheet-pose-invalid` (errors); `sheet-thickness-literal`, `sheet-kerf-control`, `sheet-custom-build`, `verify-process-sheets-only`, `laser-thickness-range` (warnings). Each carries `pattern: "sheet-parts"` and is described under "Sheet parts" → "What lint and verify check". `no-buildable-parts` points a sub-part with a `sheet` but no `build` at `sheetPart()`, and `verify-unknown-process` answers `process: "laser"` the same way. A rule that itself throws yields an `internal-rule-error` **warning** and the run continues: `lintPart` never throws and never blocks a part because of a linter bug. ### The diagnostics contract (for agents) `partforge measure --json` / `--out ` emits the machine-readable report. Every `fail`/`warn` check in `verify.failures` / `verify.warnings` carries: - `hint` — one self-contained corrective sentence (always present), - `pattern` — a stable [ERROR-PATTERNS.md](ERROR-PATTERNS.md) entry ID when one applies (follow it with `ERROR-PATTERNS.md#`); on a sheet-part check it is `sheet-parts`, this guide's "Sheet parts" section, instead, - `note` — an optional caveat about *how* the value was measured, or a companion reading, attached whatever the verdict. `minWall` sets one when the reading came from a sample rather than every triangle (see below); `overhangArea` sets one naming the steepest unsupported face's angle, - `location` — `[x, y, z]` in mm where the metric has one: `minWall` (thinnest sample point), `overhangArea` (the largest unsupported face's centroid) and `overlaps` (the center of the first offending intersection's *bounding box* — a nearby indicator, not an exact point: when a pair overlaps in more than one place the bbox center can fall in the empty space between regions) and the pair checks `contact` / `clearance` / `nearMiss` (the midpoint between the pair's closest surface points). Whole-solid metrics (bbox, volume, …) have none. Subpart facts include `minWall` (number or `null` — null exactly when no reading exists, e.g. the OCCT backend or min-wall measurement turned off, matching `minWallAt`'s null) and `minWallAt` (`[x,y,z]` or `null`). Min wall casts one ray per triangle, which is unbounded work on a dense mesh, so past a sample budget it casts from a spread, deterministic subset instead — `minWallSampled` (boolean) and `minWallSamples` (`{ sampled, total }` or `null`) say whether that happened. A part that opted into the overhang check (see the `verify` block) also carries `overhangArea` (mm² of unsupported downward-facing surface, `null` when not checked or on an `exportable: false` sub-part), `overhangAngle` (the steepest such face, degrees from vertical) and `overhangAt` (that face's centroid); the report's `measuredOverhang` stamps the angle the pass ran against, or `null`. A sub-part that declares `wall` (see the `verify` section below) also carries `wall` — `{ value, location, band, members }` or `null`: the declared band's worst member, located, with the band it was measured against and how many rays fell inside it. `null` unless the sub-part declares `wall` *and* min wall was measured for this run — the same "declared but not measured" gap `minWall` itself has. **The budget depends on whether the reading is checked against anything**: a part that declares a min-wall gate — a `verify.process` profile, or an `expect` mentioning `minWall` or `wall` — gets 50,000, because a gate's verdict rides on it; a part that declares neither gets 5,000, because there the number is a diagnostic for a reader rather than an assertion. Declaring the gate is what buys the resolution. `sampled` is how many triangles the walk *selected*, not how many rays were cast: a degenerate (zero-area) triangle has no normal to cast along and is skipped. A sampled reading is an **upper bound**: it can miss a thin spot, never invent one — and a sampled run that found no wall at all still reports its `minWallSamples`, so a null `minWall` there is "we looked and found nothing", not "nobody looked". Everything in `src/parts/` is far below the budget and reads exactly. The report's top-level `measuredMinWall` says whether this run cast min-wall rays at all — the difference between a null `minWall` that means "no wall found" and one that means "not measured". Overlap entries are `{ a, b, volume, location }`. Pair-distance facts are `gaps` (every sub-part pair: `{ a, b, distance, at }`, distance 0 = touching or overlapping) and `nearMisses` (the pairs with an unintended-looking gap under 0.5 mm). `measuredGaps` is the companion to `measuredMinWall` for that pass, and `gaps` is **absent** rather than empty when it did not run — an empty table means "measured, and these pairs have no distance", which a declared `clearance` gate fails on. A sheet sub-part (`sheetPart()`) also carries `sheet` — its 2-D facts: `material`, `thickness`, `flat` (the cut layer's size), `area`, `pieces`, the bisected `bridge`/`gap` widths with their `bridgeCapped`/`gapCapped` flags, `marksOutside`, `evaluated` (false when the 2-D budget ran out) and `at` (each finding's spot in the assembly) — and `sheet: null` on every other sub-part. In a view that holds one, each printed sub-part also carries `printBbox`, its size in the print (export) pose. ### Quick checks An editor may ask for a **quick** check, which skips both ray-casting passes — min wall and pair distances — and keeps everything derived from the build itself: triangles, bbox, volume, genus, watertight, the assembly overlap check, and lint. On a 460k-triangle assembly that is roughly 6.8 s down to 0.9 s. Gates still run on a quick check wherever the facts allow it, so a violated `bbox` or `holes` expectation still fails. What a quick check will **never** do is return a pass: any gate it could not evaluate is listed in `verify.unevaluated`, and one such gate makes `verify.ok` **`null`** rather than `true`. So `ok` is tri-state — `false` (something failed), `null` (nothing failed, but something went unchecked), `true` (everything declared was checked and passed) — and code that treats a truthy `ok` as "passed" stays correct without changing. Run a full check before trusting a part. A **thrown** error (bad part module, kernel failure) with `--json` prints pure JSON to stdout and exits 1: ```json { "ok": false, "error": { "message": "…", "pattern": "", "hint": "…" } } ``` `pattern`/`hint` appear when the message matches an ERROR-PATTERNS.md symptom string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. `measure`'s automatic lint pass (see "Linting" above) now catches most of the defects that used to surface this way statically, before the kernel boots, so they fail with pure JSON up front instead. The caveat narrows but doesn't disappear: lint resolves `verify.expect` once against the part's *defaults*, while `verify()` itself expands every `verify.cases` entry and re-resolves `expect(p, d)` per case — so an expectation that only names a bad metric/subpart for a non-default case (see `test/fixtures/unknown-metric-in-case-part.js`) still passes lint clean and then throws at runtime, after measure output has printed. That throw appends crash JSON after the human lines, so stdout is no longer pure JSON; prefer `--out` (or parse the trailing JSON object — the crash JSON is pretty-printed across multiple lines) for robust machine parsing. With `--out` the measure report is written to the file as soon as `measure` succeeds, so even if a later `verify` throw crashes the run the file is there — it just lacks the `verify` key. **Fresh-evidence rule.** A passing report is evidence only for the source, parameters, view, backend, and framework version that produced it. Any relevant edit makes the old result stale. Before reporting a part complete, run `measure` / `verify` again on the current source and inspect current renders where visual requirements remain. Do not cite a command that ran before the last geometry or expectation change as evidence. **Part-authored hints.** Any `verify.expect` metric accepts `{ expr, hint }` in place of a bare expression — use it to name the governing parameter: ```js verify: { expect: { body: { minWall: { expr: ">=1.2", hint: "increase `wallThickness` or reduce `twist`" } }, }, } ``` --- ## Self-verification (the `verify` block) A part can declare how it should be checked, co-located with its schema, so `partforge measure` (and vitest) can enforce selected **geometric**, **assembly**, and **DFM** properties. Add an optional top-level `verify` block: ```js verify: { process: "fdm-pla", // a DFM profile: fdm-pla | fdm-petg | resin, or an // inline { bed:[x,y,z], minWall, clearance, overhang } object orientation: "print", // optional; ONLY with this is overhang checked — it says the // part is laid out for its bed (Z up, bed at the lowest Z) cases: ["defaults", "M3"], // optional; default = defaults + every preset expect: { // design intent, by sub-part name (+ "_view") spacer: { holes: 1, bbox: "<=[60,60,60]", volume: "0.4..0.6cm3" }, _view: { overlaps: 0, contacts: [["drum", "flange"]], // these pairs must touch clearance: { "lid×body": ">=0.3" } }, // intended free fits }, } ``` **What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`), a **min-wall** warning, and — only for a part that also declares `orientation: "print"` — an **overhang** warning: `overhangArea` is the mm² of downward-facing surface steeper than the profile's `overhang` angle (45° from vertical on the FDM profiles; resin carries none, since it prints on supports), measured per sub-part in its print (export) pose — not as the view shows it — with the bed at that pose's own lowest Z, and warned past 1 mm²; the reported location is where the face sits in the view. The opt-in is deliberate: a profile says what a process can print, the orientation key says this part is laid out for it, and a part still being shaped, or one bound for a different process, should not be nagged about its underside. Writing your own `overhangArea` expectation is the other way in — it arms the measurement by itself, against the profile's angle or 45° when the profile names none, so a declared expectation is never answered "unavailable". Two bands next to the bed are never counted: the footprint itself, and faces whose centroid sits within 1 mm of the bed (the lower curl of a bottom-edge fillet or chamfer, which prints fine). A bridge (a flat underside spanning two supports) and the ceiling of a horizontal bore are reported as overhangs — the mesh alone cannot tell a bridge from a ceiling — which is why this is a warning and never a gate. Two more limits, stated: it is judged in the DISPLAY pose, so a sub-part whose `assembly` pose stands it differently from how it prints (a lid that prints flat beside its base) is measured as displayed, and `exportable: false` sub-parts are skipped. Switch it off under an FDM profile with an inline `{ base: "fdm-pla", overhang: null }`. **What `expect` gives you:** per-sub-part assertions on the facts `measure` already reports — `holes` (through-bores / genus), `volume`, `surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`, `overhangArea`, `wall` (a range — see below), `boundsMin` / `boundsMax` (the axis-aligned `{min,max}` corner positions — where the geometry sits, vs `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`, `volume`, `overlaps`, `centerOfMass`, `boundsMin`, `boundsMax`, plus the pair-wise `contacts` / `clearance` below. Passing these checks does **not** prove structural strength, fatigue life, stability, manufacturing tolerance stack-up, regulatory compliance, or safe real-world use. Load-bearing or safety-relevant parts need appropriate analytical/simulation evidence (for example FEA with declared materials, loads, supports, and safety factors) plus qualified human review. If no such evidence exists, say that physical performance is unverified. **Assertion DSL:** a bare number means equality (`holes: 1`); `">=n"`, `"<=n"`, `">n"`, `"=[x,y,z]"` where `*` skips an axis. The parser is strict — a malformed assertion fails loudly. **A part whose typeface is a parameter needs band assertions, not points.** Glyph advance widths differ by family, so a `text2d` sub-part's `bbox`/`volume` shifts with the picked face even when every other param is unchanged. Write `verify` bounds wide enough to hold across the fonts your `allow` list admits (a range, or `<=`/`>=`, rather than exact equality). `verify` runs against `defaults`, which is stable — the nameplate ships `face: ""` (the bundled Roboto), so its own `verify` cases don't need this, but a part whose default already names a specific face does. ```js verify: { expect: { stand: { boundsMin: ">=[0,0,0]", centerOfMass: "<=[*,*,25]" }, // sits in +octant, mass kept low _view: { boundsMax: "<=[220,220,250]" }, // whole assembly fits the bed } } ``` **Gates vs. warnings:** exact facts are **gates** (a failure sets a non-zero exit code); `minWall` is computed (a ray/shot wall-thickness measurement) and reported as a **warning** — it flags walls below the profile's minimum but never fails the build — and so is `overhangArea` (see above). `holes`/`watertight` are Manifold-only, so those assertions **skip** on OCCT parts rather than fail. **A wall that must stay one thickness: `wall`.** `minWall` answers "is anything too thin"; `wall` answers "does this wall stay what I declared" — the question a bend, a fillet or an offset silently breaks. Declare it as a range in mm, per sub-part: ```js verify: { expect: { tray: { wall: "1.8..2.2" } } } ``` It rides the same inward rays as `minWall`. A ray reading inside `[0.75 × min, 1.5 × max]` counts as this wall (a 1.2 mm floor under a 2 mm wall is another feature and is ignored) — but the window discriminates by **thickness alone, not intent**: anything else on that sub-part whose thickness falls in the window is counted too, so declare `wall` on a sub-part that is mostly this one wall; a rib or boss inside the window reads as a deviation, and a part that needs two thicknesses declares two sub-parts. The check reports the member farthest from the band — or, when every member is inside it, the one farthest from its midpoint — with its location, and warns when it lies outside — `wall 2.62 out of 1.8..2.2 at (22.8, -2.0, 15.1)` is a bend whose outer arc is not concentric with its inner one. Range form only (lint refuses `"<=2"`), a warning like `minWall` because it is a sampled reading. **A verify block that declares nothing verifies nothing.** `verify.ok` is tri-state: `true` when every declared check passed, `false` on any gate failure, and `null` when no verdict can be given — a quick lap that could not measure a gate, or a part with **no declared expectations** at all (no `verify` block, an empty `expect`, no profile). That last case used to read as `ok: true` with zero checks, which every reader took as "verified". It now comes back `ok: null` with `evaluated: 0` and a `no expectations declared` warning whose hint says what to pin; the CLI runs verify on every part, block or no block, prints *nothing verified* and exits 0 (a withheld verdict is not a failure). The same `null` covers a part that declared checks none of which could be answered — every one SKIPPED (a `ref*` metric on a sub-part with no `reference`, `holes` on the OCCT backend, a pair on a disabled sub-part) — with a `no expectation could be evaluated` warning instead; `declared` and `evaluated` on the report tell the two apart. A single answerable expectation — or a process profile, which brings the bed-fit gate — is enough for a verdict. Treat `null` as "not verified", never as a pass. **Forges with sheet parts.** When a view holds a `sheetPart()` sub-part, the profile's bed fits each printed sub-part in its print (export) pose — the check carries the note "measured in the print (export) pose" — instead of the assembled view, and `minWall` and `overhangArea` skip the sheet parts. The laser checks (`sheetBridge`, `sheetGap`, `sheetMarks`, `sheetPieces`, `sheetSolidMatch`) run on every sheet part as volunteered warnings that never make `ok` true on their own; see "Sheet parts" → "What lint and verify check". A view with no sheet part is verified exactly as before. **Per-case expectations.** Checks run across defaults **and every preset**, so a static `expect` breaks the moment a preset legitimately changes an asserted fact — a "cup" preset that turns the drainage hole off flips the genus from 1 to 0. For that, declare `expect` as a **pure function of the case's resolved params**, `(p, d) => ({ … })` (same `p`/`d` your `build` sees, `d` from `derive`): ```js verify: { process: "fdm-pla", expect: (p) => ({ planter: { holes: p.drain > 0 ? 1 : 0, bbox: "<=[220,220,250]" }, _view: { overlaps: 0 }, }), } ``` `src/parts/planter.js` is the worked example — its "Pen cup" and "Vase" presets disable the drain, so the hole count is pinned per case. Keep the function pure (no clock/randomness), like every other part function. **Contacts & clearance (near-miss gaps).** Volume, bbox, and render checks all miss sub-parts that *almost* touch — a flange floating 0.3 mm off its drum body passes every one of them. `measure` therefore reports `nearMisses` (pairs with a surface-to-surface gap under 0.5 mm), and `_view` accepts two pair-wise gates: - `contacts: [["drum", "flange"]]` — each listed pair must touch. The gate fails with the measured gap and the closest-point location when the surfaces don't meet. Interpenetration counts as contact — the separate `overlaps` gate owns *excessive* interpenetration. A pair naming an `enabled()`-gated sub-part **skips** in cases where that sub-part is off; a name that exists nowhere in the part still throws. - `clearance: { "lid×body": ">=0.3" }` — an intended free fit. Keys are `"a×b"` (order doesn't matter); values take the same assertion DSL as any metric (and the `{ expr, hint }` form), evaluated against the pair's minimum surface distance in mm. Any pair *not* declared either way that sits closer than 0.5 mm becomes a **warning** — the "did you mean these to touch?" signal. Declare the pair to silence it. Distances are measured mesh-to-mesh (exact triangle distance, so it works on both backends with no kernel booleans); contact tolerates ~1 µm, so a tessellation-limited curved contact (e.g. equal-radius cylinder-in-bore built with different facet counts) may read a few hundredths of a millimetre — prefer a tight `clearance` bound like `"<=0.05"` over `contacts` for those. One OCCT caveat: with no overlap detection there (`Solid.intersect` is Manifold-only), a sub-part *fully contained* inside another reads as its surface-to-surface distance, so it can surface as a near miss — check containment cases on Manifold. **Running it:** ```bash npx partforge measure src/parts/.js # auto-runs verify if a block exists npx partforge measure src/parts/.js --process resin # force/override a profile npx partforge measure src/parts/.js --no-verify # facts only ``` …and in vitest: ```js import { verify } from "partforge/testing"; test("part is printable and correct", () => { expect(verify(kernel, part).ok).toBe(true); }); ``` Checks run across the **default config plus every preset** (or your `cases` list); a preset that changes only parameters no on-screen sub-part reads is deduplicated, so coverage is cheap. When an agent authors both geometry and `verify`, the check is useful feedback but not an independent oracle. Preserve externally supplied acceptance claims verbatim (ideally with stable IDs in the surrounding specification), and test boundary/tolerance cases in addition to friendly defaults and presets. A repair should change the design, not relax the requirement that exposed the failure. --- ## Fillet, chamfer & shell Two backends build your part: **Manifold** (fast meshes — preview, STL, 3MF) and **OCCT/replicad** (exact B-rep — STEP). Most parts run on Manifold — and since contract v3 that **includes fillet and chamfer**: the mesh backend blends straight edges, circular-arc edges (bore rims, cylinder rims, the arcs where fillets meet a face), and **planar contour edges at constant dihedral** — the top/bottom rims of any extruded profile, however curvy its outline: `text2d` lettering, `Shape2D.offset` outlines, spline profiles all round natively now. Edges **between two curved faces** — a boss meeting a tube, a cross hole's rim, the ellipse where a plane cuts a cylinder — blend natively too (a per-vertex cross-section, since 0.138). Only `shell` still routes a sub-part to OCCT up front; a fillet/chamfer on an edge class the mesh backend can't blend (mixed convexity along one edge, a bend tighter than the fillet radius, knife edges) reroutes that sub-part to OCCT automatically at runtime — no declaration needed either way: | Op | Meaning | |---|---| | `s.fillet(radius)` · `s.fillet({ r, edges? })` | round edges (curve-following, exact); the bare-number scalar shorthand fillets **all** edges, the options form adds a selector | | `s.chamfer(distance)` · `s.chamfer({ d, edges? })` | bevel edges; same scalar-shorthand-or-options-with-selector shape as `fillet` | | `s.shell({ t, open })` | hollow inward, wall = `t`; `open` selector (`{inPlane,at}`/`{dir}`/`{near}`) chooses which face(s) to open. Closed (no-open-face) hollows are not supported. | `edges` (fillet/chamfer) / `open` (shell) chooses which edges/faces (omit `edges` for **all** edges — `shell` always requires `open`): - `{ 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 — **OCCT-only escape hatch**: it forces the sub-part onto OCCT (the mesh backend reroutes on sight of it) and is non-portable — parts meant to travel must use the object forms (see `KERNEL-CONTRACT.md`) ```js let s = k.box({ min: [0, 0, 0], max: [40, 30, 16] }); s = s.fillet({ r: 3, edges: { dir: "Z" } }); // round the 4 vertical edges s = s.chamfer({ d: 1, edges: { 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`; a `shell` call **on a Solid** routes that sub-part to OCCT up front, and everything else — fillet and chamfer included — stays on fast Manifold. The probe tracks which handle kind each op ran on, so `Shape2D.fillet`/`.chamfer` (the shared, backend-identical 2-D implementations — see "Editing profiles") never look like Solid ops. Force the backend with `meta.backend: "occt" | "manifold"` if you ever need to. STEP export always builds on OCCT, so a filleted part gets exact B-rep blends in its STEP even though it previews (and STL/3MF-exports) from the mesh blend — the two agree to within tessellation on the supported edge classes, with one visible exception: orthogonal box-style corners where three filleted edges meet get a true sphere-octant cap, and a planar rim's own corners blend by turn direction (salient corners steer the band around a small arc; reflex/inside corners round into an arc of the blend radius about the vertex — the rolling-ball pivot), but other blend junctions are mitred on the mesh where OCCT builds a vertex blend. If the mesh backend hits an edge class it can't blend, it signals `NEEDS_OCCT` and the framework reroutes **just that sub-part** to OCCT for those exact parameters — dialing the parameter away re-tries Manifold automatically. A zero magnitude — `fillet(0)`, `chamfer({ d: 0 })` — is the **identity** on both backends (see KERNEL-CONTRACT.md), so an unguarded `s.fillet(p.r)` needs no `if (p.r > 0)` wrapper. (`shell` is the exception: `t: 0` is degenerate, not identity, so a shell call always routes to OCCT.) **Clamp your radii.** The mesh fillet does **not** validate feasibility — an oversized radius self-intersects its cutters and yields a wrong shape rather than a skipped feature (OCCT skips instead). Clamp magnitudes against local geometry the way `filleted-box.js` does: `Math.min(p.fillet, halfWidth - 0.5, p.h - 0.5)`. **A defeated fillet/chamfer skips, and the build reports it.** On both backends a fillet or chamfer the geometry defeats does **not** fail the build: the op returns its input solid unchanged (edges left sharp) and the build result carries a feature-skip warning naming the op, its magnitude, and the reason. The same channel carries every other degrade — an `extrude` rim bevel reduced or left square, a `roundedBox` rim clamped to `round.side`, a `Shape2D` corner rounded smaller than asked — so the part on screen is real, minus that one feature, with everything downstream of it still applied. When a build answer includes such a warning, treat it as a failed feature, not a success: say so, and either adjust the geometry/radius and retry or leave the feature off deliberately. Do not conclude a fillet landed just because the build succeeded. **Preview routing is per sub-part.** Each sub-part is probed and routed independently, and a mixed part's regen fans out to both workers in parallel — a shelled body pays for OCCT while a plain lid rebuilds at Manifold speed beside it. Two scopes still route whole-part (the max over the sub-parts): **exports** (one STL/STEP/3MF job builds everything in one worker) and the **CLI** (a single Node process boots exactly one kernel; on a mesh-side `NEEDS_OCCT` it re-runs itself once with the backend pinned to OCCT). Within one sub-part's build there is no per-op backend mixing. **Shading intent.** The kernel decides what shades smooth and where edge lines draw — spheres, cylinders and fillets are smooth by construction; boolean cut seams always shade hard and draw a line; a point-ring loft's facets shade flat when its rings have fewer than 32 sides. A curve or resample loft shades by **tessellation provenance**: only wall sections that came from a smoothly tessellated contour span (an arc/Bézier run) shade smooth, sharp contour corners and silhouette-kink rings (an abrupt direction change up the stack, like a belly break) flat-shade and draw a dividing line, and a morph's snapped corners do the same. `shading: "smooth"|"faceted"` on `k.loft` overrides all of this either way. If your part previews smooth but would print faceted — or the reverse — set the hint rather than changing facet counts. > `partforge measure` reports `watertight`/`holes` as `n/a` for OCCT-run parts > (Manifold-only topology); `render` works on both. Filleted parts now measure on > Manifold with full topology. ### `roundAll(r)` — round everything at once `s.roundAll(2)` (or `s.roundAll({ r: 2 })`) rounds **every** edge of the solid — convex and concave — with radius ≈ 2 mm in one pass, on both backends, with no OCCT routing. Faces stay in place (within backend tolerance). It is the blunt, global counterpart to `fillet`/`chamfer`: there is no edge selection, and features smaller than the ball are **consumed** — walls thinner than `2r` melt away, holes narrower than `2r` seal shut. That makes it ideal for "soften this whole organic part" and wrong for parts where a specific edge must stay sharp (use `fillet` with a selector for that). **Cost note.** On a Z-aligned extrusion (constant cross-section — a plate, a text backing, any straight-sided prism) roundAll takes a fast path: the ball morphology is computed as a 2-D close-open of the cross-section plus rim fillets, so even a complex text-outline backing rounds in well under a second. Everything else pays the full morphology (three Minkowski passes), whose runtime grows steeply with triangle count — a rotated or lofted solid of a few thousand triangles can take tens of seconds. When only a specific edge needs rounding, `fillet` with a selector (e.g. `{ inPlane: "XY", at: h }` for a rim) says what you mean and is always the cheap, predictable choice; reach for roundAll when the design genuinely calls for every edge softened at once. At the fast path's corners the plan silhouette follows the rim fillet's corner rounding (radius ≈ 1.05–1.25·r rather than exactly r) — the same corner treatment fillet itself applies. Rules of thumb: - Keep `r` under half your thinnest wall unless you *want* melting. - Preview and STL/3MF export always work (mesh morphology). STEP export gets true B-rep arc surfaces while `r` is below the smallest feature size; at consuming radii OCCT cannot represent the melt and **skips the op whole** with a `roundall-skipped` warning — the STEP then has the un-rounded shape. - Relying on consumption? Add a `verify` volume assertion so a regression in the radius (or a backend skip) fails loudly. - A small ridge remaining where a thin rib was consumed is correct morphology (the rib's dilation fillet survives the opening), not a bug. ### Cost on the OCCT path: fillet/chamfer scale with edge count — and order matters These costs apply when a sub-part **does** run on OCCT (a shell, an unsupported edge class, a pinned backend, or STEP export). OCCT fillet/chamfer cost is **per selected edge**, on top of the OCCT boolean tax. Two habits keep it tolerable: - **Fillet/chamfer as early as possible, on the simplest solid.** A fillet on a bare primitive is ~15× cheaper than the same fillet after a dozen boolean cuts have multiplied the face count — and because the solid cache keys each op by its input's content hash, an early fillet is a cache **hit** when a downstream parameter changes, while a fillet-last build re-pays the whole op on every slider step of every parameter. - **Never point a rim selector at a many-point extruded profile.** `edges: {inPlane}` on a gear-like extrusion selects *every* polygon edge (hundreds); one chamfer call then costs seconds — and if the distance doesn't fit the tooth lands, the failure-rescue bisection re-runs it ~8× (`ERROR-PATTERNS.md#chamfer-rescue-bisection`). Use the loft bevel below instead. ### Beveling profile rims: extrude's bevel option For an **extruded profile** (gear, star, bracket outline — any `k.extrude` of a polygon), a top/bottom rim bevel doesn't need `chamfer` at all — it's built into `extrude`: ```js k.extrude({ profile: prof, h: 5, bevel: 0.6 }); // 45° bevel, both rims k.extrude({ profile: prof, h: 5, bevel: { top: 0.6 } }); // one rim only ``` Same 45° bevel a rim `chamfer` would cut, but it desugars into extrude + loft + intersect at the shared kernel front, so the part **stays on the fast Manifold backend** (no CAD-only op for the probe to find) and costs one boolean regardless of profile point count. Measured on a 24-tooth involute gear: ~0.1 s on Manifold vs ~40 s for the equivalent OCCT `chamfer` (576-edge rim × the rescue bisection). Every profile form works: point arrays, arc profiles, `{outer, holes}` regions (hole rims flare outward — the opening is larger at the face, as a chamfer would cut it), and `Shape2D` (multi-region shapes bevel each region and union). One fidelity caveat: curved profiles are **materialized to point rings** first — the loft envelope needs matched points — so a beveled extrusion is faceted at the sampling LOD even in STEP export. Arc contours sample at a fixed LOD identically on both backends; a `Shape2D` materializes at its own backend's LOD. If you need arc-exact STEP walls, that's the one case native `chamfer` still buys you (at its OCCT cost). Rules (throws otherwise — `ERROR-PATTERNS.md#extrude-bevel-invalid`): no `twist`/`scaleTop`, and `bottom + top < h` — clamp from your height parameter, e.g. `bevel: Math.min(p.chamfer, p.thickness / 2 - 0.2)`. A bevel that would pinch a narrow feature shut (a gear's tooth land) is deterministically reduced to the largest offset the rim can take, with a console warning (`ERROR-PATTERNS.md#extrude-bevel-reduced`). Under the hood it insets the profile with `offsetPolygon(prof, -c, { corners: "sharp" })` and intersects with a loft envelope extended past both faces (so the envelope's own end caps never coincide with the extrusion's faces — coincident caps leave sliver-triangle shading artifacts). The same construction works by hand when you need a variant the option doesn't cover. This bevels a **whole rim**; for selective edges on a solid that's already OCCT-routed, plain `chamfer` with a tight selector is still the right tool. --- ## Conventions & gotchas When something fails confusingly, **grep [ERROR-PATTERNS.md](ERROR-PATTERNS.md) for the symptom first** — it maps error text → cause → fix. The invariants, one line each: - **replicad (OCCT) transforms consume their input** — never reuse a transformed solid; `.clone()` first ([replicad-consumed-operand](ERROR-PATTERNS.md#replicad-consumed-operand)). - **Part modules are DOM-free and side-effect-free** — they load in both the main thread and the worker ([worker-imports-main-entry](ERROR-PATTERNS.md#worker-imports-main-entry)). - **`build` is a pure function of `(k, p, d)`** — impurity silently defeats the geometry cache ([impure-build-stale-preview](ERROR-PATTERNS.md#impure-build-stale-preview)). - **Units are millimetres** throughout. - **One sub-part per physical piece, built as it prints; `views` poses it.** A `views` entry is `true` or a rigid pose `(s, p, d) => s` — never a second "print" copy, never a reshape ([view-pose-not-rigid](ERROR-PATTERNS.md#view-pose-not-rigid)). - **Never sample an arc into points by hand.** A `Math.cos` loop hides the sweep direction in a sign, and a wrong sign produces a self-crossing outline that builds with inverted fill and no error — only a `profile-self-intersects` warning ([profile-self-intersects](ERROR-PATTERNS.md#profile-self-intersects)). And a sampled arc is frozen at the facets you wrote: a point list is exported exactly as written, so a print shows them, however fine the export is ([profile-sampled-arc](ERROR-PATTERNS.md#profile-sampled-arc)). Build curved outlines with `pathProfile().arcTo(to, via)` and the exact-curve `*Profile` helpers (`ringSectorProfile`, `slotProfile`, `pieProfile`, `roundedRectProfile`, `roundedProfile`); mirror a symmetric half with `mirrorProfile`. - **Preview vs print quality:** Manifold bakes segment counts in at primitive creation, so builds are quality-agnostic; the export path uses a separate "print" kernel. Preview facets every circle at 116 segments. Print sizes each circle by chord tolerance — the fewest segments that keep the facet sagitta under 0.01 mm — never fewer than the preview's 116 and never more than 480, so a small feature exports at exactly the density you previewed and only circles wider than about 54 mm get finer. A part that previews is a part that exports: the old flat 480 turned a 0.75 mm rivet into 115,200 triangles and a body with a few hundred of them into an out-of-memory trap at export ([export-kernel-out-of-memory](ERROR-PATTERNS.md#export-kernel-out-of-memory)). **Only curves the kernel knows about are refined**: primitives, a revolve's sweep, and the arcs of a path contour or `Shape2D`. A point list — from a `*Polygon` helper or a loop of your own — is exported exactly as written, so there is no resolution setting to raise; build the curve with a `*Profile` helper or `arcTo` instead. A partial `revolve` spends the circle count in proportion to its sweep (a 36° revolve takes a tenth of a circle's segments), so its facets match a full revolve's. **Doubly-curved surfaces are the exception on both tiers:** a sphere, a lathe's profile arcs (`torus`, `roundedCylinder`, a `revolve` of your own rounded `Shape2D`) and a `roundedBox`'s corners all spend the segment count squared (6,728 triangles for any sphere at 116; 27,000 for a tiny O-ring), so they are sized by chord tolerance — 0.02 mm at preview, never fewer than 24 segments per circle (a rivet sphere is 288 triangles, an O-ring ~6,000) and never more than the flat count, so only features under about 60 mm radius get coarser and none get finer. That is what keeps a body studded with a few hundred rivets inside a phone's memory ([preview-build-too-heavy-for-phones](ERROR-PATTERNS.md#preview-build-too-heavy-for-phones)). Two consequences to know: a lathe's sweep still runs at the flat count, so a small rounded cylinder is cheaper as `roundedCylinder` than as a revolve you densify by hand; and a tolerance-sized surface measures slightly smaller than the exact one (about 0.8% on a 3 mm rounded feature), so give a `verify` volume gate on small rounded parts that much slack. Spheres and rounded features are still the costliest way to add small detail — a domed rivet is 288 triangles where a short cylinder is 232 and a box is 12, and every one is a boolean operand — so prefer instancing one union of a row over a chain of per-feature booleans, and drop counts the print cannot show. - **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT ([probe-routed-to-occt](ERROR-PATTERNS.md#probe-routed-to-occt), [occt-holes-watertight-na](ERROR-PATTERNS.md#occt-holes-watertight-na)). - **Never let two cut tools share an exactly coincident face** — a bore whose radius equals a thread's root radius, a cut ending flush with a face. Give them 0.05-0.1 mm of deliberate clearance, or overshoot the cut. Mesh CSG shrugs; OCCT's boolean degenerates, so the part previews instantly and the STEP export runs for minutes ([boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang)). The exact kernel refuses the common form up front — an `exactly-touching surfaces` build error names the shared radius and this fix menu. For the case that causes this most often — a tapped hole — reach for `k.tappedBore`, which owns the bore and the thread together and cannot land them on the same face. - **A boolean that comes back geometrically impossible is a build error, not a part.** Every `cut`/`cutAll`/`intersect`/`union` result is judged by volume against its operands on both backends: a union smaller than an input, a cut that grew, a negative volume, or the exact kernel's silent "returned one operand instead of the union" all throw `boolean result invalid: …` with the fix menu above instead of shipping a wrong preview or STEP file ([boolean-dropped-operand](ERROR-PATTERNS.md#boolean-dropped-operand), [boolean-impossible-result](ERROR-PATTERNS.md#boolean-impossible-result)). A legitimately degenerate design — a hole wider than its plate — is not impossible and builds as before; `verify` is what catches that. --- ## Interactive clarification: request-a-pick An external tool (e.g. an AI agent editing your part) can ask the *user* to click geometry and receive the `Selection` back, closing the loop in the other direction from `?pick`. - Serve your app with **`?pickserver&picktoken=`** (or `?pickserver=http://127.0.0.1:4518&picktoken=`) to enable it. While idle nothing changes; when the local pick-server requests a click, a banner appears ("🤖 Claude needs you to click …") and the picker arms for one click. - The agent side runs `partforge pick-serve` once — it prints the token and the exact URL to open — then `partforge pick "" …` for one or more clicks (collected in order, returned together). The CLI blocks until the user clicks, then prints the `Selection`(s) as JSON. - **The token is required.** Every route on the pick-server (including the SSE stream) is gated by a random per-process token, requests from non-loopback origins are refused, and the server never reflects an arbitrary `Origin`. Without that, any site the user browsed to while the server was running could read the agent's prompts, inject text into the agent's output, or harvest the user's live parameter values. A `?pickserver=` pointing anywhere but loopback is ignored with a console warning. `partforge pick` finds the token automatically via `~/.partforge/pick-.token`; `--token` and `PARTFORGE_PICK_TOKEN` override it. See the bundled skill `skills/partforge/SKILL.md` for the agent workflow. This is plain click-routing

# Authoring parts This app is a small **framework** that turns a declarative **`PartDefinition`** into a full parametric-CAD web app: a 3-D viewer, a control panel built from your parameter schema, two geometry workers, and STL / STEP / 3MF export. To make a new part you write **one script** — geometry build functions + a parameter schema — and the framework does the rest. - Reusable framework: `src/framework/` (knows nothing about any specific part). - Parts: `src/parts/` — e.g. `planter.js` (full, rich) and `demo.js` (minimal). - A part module is **plain data + pure functions**: no DOM, no side effects (it loads in both the main thread and a Web Worker). Two worked examples to read alongside this guide: **`src/parts/demo.js`** (a parametric spacer — the smallest complete part) and **`src/parts/planter.js`** (a faceted planter — facets, taper, twist, even walls, an optional feature, a `derive`, and a `verify` block). **`src/parts/filleted-box.js`** is the worked example for the portable Solid fillet/chamfer API and the OCCT-only shell op. --- ## Quickstart 1. Copy `src/parts/demo.js` to `src/parts/.js` and edit it. 2. Copy the three glue files, repointing them at your part: - `demo.html` → `.html` - `src/app-demo.js` → `src/app-.js` - `src/demo-worker.js` → `src/-worker.js` 3. `nvm use && npm install` (Node 24), then `npm run dev` and open `http://localhost:5173/.html`. That's the whole loop. The chrome (panel, tabs, viewer, export buttons) is shared — your HTML is structural markup only and carries no CSS (the framework supplies it via `framework/app.css`, imported by `mount`). See "Wiring a part into a runnable app" below for what that markup must contain. --- ## Before geometry: state the engineering intent For a decorative or low-consequence part, a short dimensional description may be enough. For anything that mates with another object, carries load, or could cause harm if it fails, write down the engineering intent **before** writing `build`: - the coordinate frame, origin, and named datums; - the allowed envelope and the interfaces that must align (mating faces, axes, hole patterns, fits, clearances, and tolerances); - the manufacturing process and material assumptions; - load cases, support regions, intended load paths, and safety factors when structural behavior matters; - numbered acceptance claims with units and thresholds; and - unresolved assumptions that need the user or an engineer to answer. This may live in the task/specification, a companion design note, or comments next to the part — partforge does not prescribe a blueprint schema yet. Do not silently invent missing loads, material properties, tolerances, or safety factors. Ask, or record the property as unverified. Treat user/specification acceptance claims as **higher authority** than agent-authored geometry and checks. An agent may add conservative checks, but must not delete a claim or loosen its threshold merely to make a failing design pass; changing the contract requires explicit approval. --- ## The `PartDefinition` contract A part is a default-exported object. Full shape (optional fields marked `?`): ```js export default { meta: { title, units, background?, environment? }, // 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 } — or (p) => ({ name: source }) when a control drives the typeface imports?, // { name: source } — STEP/STL/3MF files a part's k.import() needs; same preload timing as fonts (see below) vectors?, // { name: source } — declared vector files k.vector2d() places: authored partforge-vector JSON or ingested SVG; same source grammar and preload timing as fonts derive?, // (p) => d, or { group: (p, d) => {…}, … } — dependent values computed once per build parts: { // named sub-parts; each builds ONE solid : { label?, // display name (tabs/progress); defaults to the key build: (k, p, d, onProgress?) => Solid, // REQUIRED — see kernel API views: { : true | (s, p, d) => s }, // each view the piece appears in: true = as built, or a rigid pose — see Rules enabled?: (p) => boolean, // optional — gate a conditional sub-part display?: { color?, opacity?, material?, …overrides }, // viewer-only appearance — see "Materials and appearance" export?: { name }, // filename/object name on export; defaults to the key reference?: string, // name of a declared import — measure() computes a deviation fact against it (see below) }, }, views: { : { label, default?, animations? } }, // view tabs; a view may own animations (below) probes?, // { name: (k, p, d) => Solid | Shape2D | plain JSON } — measurements reported by // measure/inspect, never rendered or exported (see "Probes" below) }; ``` **Rules:** - `build(k, p, d, onProgress?)` makes the piece **as it prints**: at the origin, flat face on the bed (z = 0). It is the exported solid and the direction layer lines run. It is the only required function per sub-part. `p` is `{ ...defaults, ...userParams }`; `d` is `derive(p)` (or `{}`). `onProgress?.("phase")` is optional per-feature progress shown during export — call it before expensive steps. - `views` maps each view the piece appears in to `true` (shown as built) or a pose `(s, p, d) => s` that only translates or rotates its argument (`translate`/`rotate`/`rotateAbout`/`along`/`at`) — no geometry queries, no `scale`/`mirror`, no new solid. A view missing from the map does not show the piece. - One sub-part per physical piece — never separate "print" and "assembled" copies. A piece's own tab is `true`; `assembly` entries move pieces into place; `print` entries spread them on the bed (`p.w + 10`, not a measurement). - A param that moves a piece (hinge angle, slide, explode distance) is read only in `views` entries; it then animates at frame rate with no rebuild. - List `assembly` first (or flag it `default: true`) among the top-level `views` (the default tab, and what headless `verify` checks), piece tabs next, `print` last. - A piece that is not printed (a filament pin, a bearing) is `exportable: false` and appears in `assembly` only. - Sheet pieces (`sheetPart`) keep their `pose`; their `views` entries are `true`, and they stay out of `print` — they are cut, not printed, and export assembled. - Exports write the checked pieces as built. STL is one file per piece; a 3MF or STEP of several printed (non-sheet) pieces lays them out on the bed automatically, 10 mm apart. The Lattice Box's `lid` shows all of it (helpers elided — see `src/parts/lattice-box.js` for the whole part, whose `swing` is `(s, p, d) => s.rotate(-p.lidAngle, d.hinge, [1, 0, 0])`): ```js lid: { build: (k, p, d) => /* flat plate with the lattice window, as printed */ k.box({ min: [0, 0, 0], max: [p.w, p.d, p.t] }), views: { assembly: (s, p, d) => swing(s.translate([0, 0, p.h]), p, d), lid: true, print: (s, p, d) => s.translate([p.w + d.gap, 0, 0]), }, }, ``` - `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` map has the view and whose `enabled(p)` is true. - **Which view the viewer opens on** is resolved in this order: the first view flagged `default: true`; else the view placing the most sub-parts at `defaults` (counting `enabled(defaults)`), which for a multi-view part is normally the assembly; else the first key in `views`. So flag the assembly view `default: true` when you want it to open but sit last in the tab bar. The chosen tab then persists per part for the rest of the browser session. The headless tools are deliberately different: `measure`, `verify` and `render` all default to the **first key** in `views`, ignoring `default: true`, so a CI gate can't move because a sub-part was added to a view. - `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. - `imports` declares the STEP/STL/3MF files a part's `k.import()` calls need, same source grammar and preload timing as `fonts` above. See "Importing geometry (STEP/STL/3MF)" below for the full contract — backend matrix, units, the `reference` field + the deviation gate, and caching. - `vectors` declares the vector files a part's `k.vector2d()` calls need, same source grammar and preload timing as `fonts` above — but the source resolves to **JSON** in the `partforge-vector` format, never to raw `.svg`. That JSON is either **authored** by hand (millimetre coordinates, placed as drawn) or the **ingested** output of `partforge/ingest`. A vector source may additionally be that JSON **already parsed** — the object itself, rather than bytes or a URL pointing at it — which is the form to use when the artwork lives beside the part and is meant to stay hand-editable. See "Vector geometry" below for the full contract. ### Legacy: views arrays and place() Parts written before 0.143 list views as an array and pose pieces with `place()`. They keep working unchanged, including their export poses; new parts use the `views` map above. A sub-part may not use both (`views-and-place`). ```js : { build: (k, p, d, onProgress?) => Solid, place?: (solid, { view, purpose, p, d }) => Solid, // optional reposition; default identity views: ["assembly", "print"], // string[] — which views show this sub-part }, ``` - `place(solid, ctx)` is an optional escape hatch for parts whose **display pose differs from their export pose**. `ctx.purpose` is `"display"` or `"export"`; `ctx.view` is the active view. Default is identity. Display placement may depend on `view`: the viewer re-poses each sub-part when the tab changes. The viewer applies the display pose as a matrix over the canonical mesh, so `build()` may query geometry freely; only `place()` has to stay a rigid motion of its argument, reading `p` and `d`, for a pose-only param to play at frame rate and for layer lines to stay on the part. - **Any difference between the display and export pose must be a rigid motion** — `translate`/`rotate`/`rotateAbout`/`along`/`at` only. Never put a `mirror` or a non-identity `scale` on one purpose but not the other: you would print the mirror image of what the viewer showed ([place-not-rigid](ERROR-PATTERNS.md#place-not-rigid)). Bake a reflected or resized form into `build` so both purposes share one canonical solid, then pose it rigidly. - Branch on `purpose` so the export pose is the print orientation: an export pose that follows an animated param pins the layer lines to the pose at the last rebuild. - A param read only inside `place()` plays at frame rate; `lint` notes a track whose `place()` it cannot read (a query on the solid, a function argument). --- ## Animations A **view** may declare named animations — pure keyframe data that drives **existing params** over time and fades the view's own sub-parts in and out. Animations belong to the view that declares them: they live under `views..animations`, never at the top level of the part (a top-level `animations` key is a lint error — `animation-not-in-view` — and is ignored at runtime: no bar, no crash). The viewer shows a transport bar (play/scrub, with ‹ › pagers between animations) **only while the active view declares animations**, listing exactly that view's set; views without animations render no bar at all. Switching views resets playback: the running animation stops, its param snapshot is restored, all opacity overrides are cleared, and the incoming view's transport starts fresh at its first animation, position 0 — no animation state survives a view switch. Hosts drive the same engine via `runtime.animation`, scoped to the active view (call `setView` first to reach another view's animations); `partforge render` can render stills at any position. The reference part is `src/parts/hinged-box.js`. Step labels surface on the scrubber rather than in a readout: hovering or dragging along the timeline names the chapter under the pointer, and with the scrubber focused **PageUp / PageDown jump whole chapters** (PageUp forward, matching the key's native slider direction). Screen readers get the same information from the scrubber's `aria-valuetext`, which reads `" — "`. This is the shipped reference part's own block — `views.box` owns all three animations, and `assemble` opens with a fade rather than a motion: ```js views: { box: { label: "Box", animations: { open: { label: "Open lid", description: "Swings the lid to **110°** about the rear hinge line.\n\nPose-only: playback runs at frame rate with no geometry rebuild.", camera: "front", // optional: intro angle, cue list, or per-step (below) duration: 1.2, // seconds tracks: { lidAngle: [[0, 0], [1, 110]] }, // param -> [t, value] keyframes }, cycle: { label: "Open / close", duration: 2.4, loop: true, // wraps continuously (single-step only) easing: "linear", // linear | ease-in | ease-out | ease-in-out autoplay: true, // at most one per view tracks: { lidAngle: [[0, 0], [0.5, 110], [1, 0]] }, }, assemble: { label: "Assemble", description: "How the parts come together: the lid fades in above the base, drops on, then swings open to check hinge clearance.", steps: [ // steps play in order; named on the scrubber as you hover/drag { label: "Lid appears", camera: "iso", duration: 0.8, opacity: { lid: [[0, 0], [1, 1]] }, // sub-part -> [t, 0..1] keyframes tracks: { lidLift: [[0, 40], [1, 40]] } }, // hold the lift while it fades in { label: "Lower the lid", camera: "left", duration: 1.0, tracks: { lidLift: [[0, 40], [1, 0]] } }, { label: "Open to check clearance", camera: "iso", duration: 1.0, tracks: { lidAngle: [[0, 0], [1, 110]] } }, ], }, }, }, }, ``` Rules (all lint-enforced): - Animations are declared under `views..animations` — one map per view, each name unique within its view. Two views may reuse a name; each owns its own animation. - An animation has **either** `tracks`/`opacity` (a single anonymous step) **or** `steps`. Never both forms, never neither. - Tracks reference numeric params from `defaults`. Keyframe `t` is normalized per step, strictly ascending from exactly 0 to exactly 1; values must sit inside the owning control's min/max (the engine applies them unclamped). - Params not tracked anywhere keep their current values; a param tracked in one step holds its nearest keyframe value while other steps play. - `opacity` sits beside `tracks` and fades sub-parts instead of moving them. It is keyed by **sub-part name**, and the sub-part must belong to the owning view (`animation-opacity-unknown-part` otherwise); values run 0 (hidden) to 1 (normal) and are lint-checked against that range (`animation-opacity-range`). Keyframes follow exactly the same rules as param tracks — per-step normalized `t`, strictly ascending from 0 to 1 — including the hold rule: a sub-part faded in step 3 holds its step-3 opening value (0, hidden) through steps 1–2, so "absent until its moment" needs no extra declaration. Sub-parts never mentioned render normally. - Opacity 0 hides the mesh **and its edge lines** entirely — it is absence, not a ghost. Values in between multiply any static `display.opacity`: a ghost part at `display.opacity: 0.5` faded to 1 shows at 0.5. - **Opacity is display-only, always** — it never touches params, export, `measure`, or `verify`, and Reset restores normal visibility. This is a deliberate asymmetry with param `tracks`, where exporting while paused exports the posed state (below): a pose is real param state, a fade is not. Because it bypasses the param pipeline, a fade runs at frame rate even when param tracks force worker-cadence rebuilds. - Fades compose with the cutaway: a half-faded surface is still sectioned by the cut plane, though its hatch cap keeps full-strength opacity for the moment the part is mid-fade. - A step may declare a `camera` and **no** `tracks`/`opacity` — an establishing shot that swings the view while the model holds still. At least one step still has to carry `tracks` or `opacity`, or the animation animates nothing; a **pure-fade** animation, carrying only `opacity`, is perfectly legal. Note the holding value is the nearest keyframe, not whatever the user last set: a leading camera-only step shows the animation's opening pose, the same one `t = 0` would show. - `loop` and `autoplay` must be literal booleans. Anything else is reported by lint and treated as `false` at runtime, so `loop: "false"` never means "loop". - Couple motions through `derive` (animate one master param; derive the rest), not by tracking dependent params separately. - `camera` cues use the seven canonical angles (`iso front back top bottom left right`) or any view-cube orientation — an edge or corner named vertical, then depth, then side (`top-front-left`, `top-back-right`, `front-left`, `bottom-back-right`, …; `top-front-right` is `iso`). One mechanism per animation: an animation-level name (an intro cue at t=0), an animation-level `[[t, angle], …]` list, or per-step names. Cues fire during play only — scrubbing never moves the camera — and a user orbit disarms the remaining cues for that run. - **A camera move takes as long as its cue asks**: a per-step `camera` sweeps across that step's whole `duration`, and a listed cue sweeps until the next cue (or the end). The move that settles the camera BEFORE playback starts — the first cue, or the governing one when play resumes mid-timeline — is always a short swing, because params wait for it. So a slow orbit timed to a motion is a camera-only opening step (the starting angle) followed by the moving step carrying the destination angle. - **To turn the view, move the camera — never rotate the part.** A "spin" param that rotates the geometry for a turntable effect looks right in CAD mode but is wrong in realistic mode: the floor, shadow and backdrop stay put in the world, so the part visibly slides around on them. Use cues instead: ```js steps: [ { label: "Start", camera: "top-front-left", duration: 0.3 }, // establishing angle { label: "Open lid", camera: "iso", duration: 1.5, // orbits to iso over 1.5 s tracks: { lidOpen: [[0, 0], [1, 100]] } }, ] ``` - Playback drives params through the real param pipeline. A param read only inside a `views` pose plays at frame rate whatever `build()` does. A param `build()` reads rebuilds at worker cadence — except through a trailing translate/rotate, which the viewer still re-poses by delta. `lint` notes a track whose pose it cannot read (a query on the solid, a function argument). - Playback pauses when the user edits any control; Reset restores the values the animation found. Because animated values are real params, exporting while paused exports the posed state — by design. - `autoplay: true` (optional, at most one animation **per view**) starts that animation on first show and again on each view switch, until the user touches the transport — or anything writes params (`runtime.setParams` included) or calls a `runtime.animation` method; any of those disarms auto-start for the session. Lint: `animation-autoplay-invalid`. It is not armed when the browser reports `prefers-reduced-motion: reduce` — self-starting motion is exactly what that setting asks a page not to do. An autoplay animation that declares a `camera` cue will sweep the camera away from the user's persisted framing on every page load, so choose cues for autoplay deliberately — the shipped example's `cycle` animation has none. Headless: `partforge render --animation open --at 0,0.5,1` renders tagged stills (`--at` is normalized over the animation's total duration, like the scrubber); `--step ` renders a step's end state; stills default to the governing camera cue's angle, and apply opacity at the rendered `t`, so a faded frame renders faded. `--animation` searches every view: a name unique across the part implies its owning view and renders there, overriding the usual first-view default. If two views declare the same name the CLI stops and asks for the existing positional view argument (`partforge render --animation shared`) — there is no compound "view/name" syntax, and `--views` already means camera angles. --- ## Materials and appearance A sub-part's `display` block says how it LOOKS. Appearance never changes geometry, exports (other than export colours, below), `measure` or `verify`, and a mistake in it never fails a build — lint warns and the viewer falls back. ```js parts: { body: { build: …, display: { material: "anodized-aluminum", color: 0xb3261e } }, knob: { build: …, display: { material: "abs-plastic", color: 0x111111, roughness: 0.25 } }, gasket: { build: …, display: { material: "rubber" } }, }, meta: { title: "…", units: "mm", environment: "studio" }, ``` - `material` — a preset id from the table below. Without one (or with one the library does not know) the sub-part keeps the CAD view's look — its `color`, else the viewer's blue-grey — and **realistic mode shows it as a PLA print** (`pla-print`'s finish and layer lines) in that same colour — except a laser `sheetPart`, which shows its stock instead (below). So an untouched part looks printed in realistic mode; name a material when it is made some other way. The PLA look is realistic-only: the CAD view, export colours and `declaresMaterials` are unaffected, and a part that names no material is not treated as declaring one. - `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets marked tintable are normally coloured this way (anodizing, plastic, paint); the others have an intrinsic colour (brass) but still accept one. - Overrides — each clamped to its range: `roughness` (0–1), `metalness` (0–1), `clearcoat` (0–1), `clearcoatRoughness` (0–1), `anisotropy` (0–1), `textureScale` (0.01–1000). Transmission, index of refraction, sheen and iridescence come only from a preset. - `opacity` — unchanged: a ghost stays a ghost and casts no shadow. - **One material per sub-part.** Something that needs two finishes (a knurled grip in rubber on an aluminium body) is two sub-parts. **Sheet parts default to their stock.** A laser `sheetPart` that names no material (or one the library does not know) is not drawn as a PLA print: realistic mode shows it as the sheet its stock label names — the first row with a stem that starts a word of the label, ignoring case (so `Plexiglas`, `Acrylite` and `poly-carbonate` match; `perplexing` does not): | A word of the stock label starts with | Realistic look | | --- | --- | | `acryl`, `perspex`, `plexi`, `pmma`, `methacryl`, `polycarb`, `lexan`, `makrolon`, `lucite` | `clear-acrylic` | | anything else — plywood, birch, basswood, poplar, MDF, hardboard — or no readable label | `plywood` | Stock that is neither wood nor acrylic — felt, leather, card, cork — takes the `plywood` look too, charred edges and all. A `color` tints the look, as it tints any preset (a stained plywood, a coloured acrylic); the CAD view still shows the `color` itself. Only a string label is read: a stock written as a `(p, d)` function counts as unreadable. Name `display.material` to choose the look yourself — for such stock, or any other. Like the PLA look, this is realistic-only and never makes a part declare a material. **Where it shows.** The CAD view (with feature lines) shows each material's colour, flattened so dark materials stay readable. **Realistic** mode — the viewer's toggle — shows the full material under environment lighting, with a ground and soft shadow and no feature lines. The part never moves when the mode changes. The ground is placed under the part when a view is shown and after each edit; while an animation plays or is scrubbed it stays where it is (dropping lower only if the part would otherwise sink into it), so a motion that changes the part's footprint never slides the floor around under it. **3D-print layer lines** (`pla-print`, `petg-print`) run perpendicular to the **export** pose's +Z — the way the part will be printed, not the way it is displayed. If the lines run the wrong way, fix `build()` so the piece is modelled in its print orientation, not the material. Wood, carbon fibre and SLS grain are fixed to the sub-part, so they never slide when the camera or an animation moves. **Laser-cut wood.** In realistic mode a laser `sheetPart` in a wood — `plywood`, `oak` or `walnut`, named or its stock's default (so a plywood sheet that names no material burns too) — shows what the laser did: its cut edges are charred, darker on thicker stock (on `plywood` the plies show through), and its engraving and score lines are scorched, while its faces stay wood. There is nothing to set, and it is still one material: the char follows from the sheet and the wood it is drawn in. It needs the sheet's own frame, so a sheet part with a custom `build` or a `views` pose of its own shows plain wood. The CAD view and every export are unchanged. **`textureScale` is millimetres, and what it measures depends on the preset's pattern** — so a value copied from one preset family is wrong on another (0.2 on oak shrinks the grain to a 0.2 mm tile, i.e. invisible noise): | Pattern | Presets | `textureScale` means | Default | | --- | --- | --- | --- | | layer lines | `pla-print`, `petg-print` | layer height | 0.2 | | SLS grain | `nylon-sls` | grain size | 0.15 | | wood | `oak`, `walnut`, `plywood` | size of one texture tile (the grain repeats every this many mm) | 250 (`oak`), 400 (`walnut`), 150 (`plywood`) | | carbon weave | `carbon-fiber` | size of one texture tile | 48 | Presets without a pattern ignore it. **3MF and STEP export** carry each sub-part's colour (its `color`, else its preset's colour), so a multi-colour print opens in a slicer already split and coloured, and each STEP body opens in a CAD tool in its own colour. A part with no `color` or `material` exports a 3MF exactly as before; its STEP bodies take the viewer's blue-grey. | Preset | Name | Tintable | Use | | --- | --- | --- | --- | | `machined-aluminum` | Machined aluminium | — | Bare CNC-milled aluminium, fine tool marks, satin sheen. | | `brushed-aluminum` | Brushed aluminium | — | Directionally brushed aluminium panels and enclosures. | | `anodized-aluminum` | Anodized aluminium | yes | Dyed anodized aluminium; tint with `color` (e.g. red, black, blue). | | `bead-blasted-aluminum` | Bead-blasted aluminium | — | Matte, even-textured aluminium (laptop-shell finish). | | `brushed-stainless` | Brushed stainless steel | — | Brushed 304 stainless: kitchen, marine and fastener hardware. | | `polished-chrome` | Polished chrome | — | Mirror chrome plating; shows the environment strongly. | | `black-oxide-steel` | Black-oxide steel | — | Blackened steel tooling and fasteners with a slight oily sheen. | | `cast-iron` | Cast iron | — | Raw sand-cast iron: dark, rough and matte. | | `titanium` | Titanium | — | Bare titanium: slightly warm grey, satin. | | `brass` | Brass | — | Yellow brass fittings and decorative hardware. | | `copper` | Copper | — | Bare copper: busbars, heat sinks, decorative parts. | | `bronze` | Bronze | — | Cast bronze bushings and sculpture. | | `powder-coat` | Powder coat | yes | Durable textured paint over metal; tint with `color`. | | `painted-metal` | Painted metal | yes | Glossy enamel or automotive-style paint; tint with `color`. | | `pla-print` | PLA print | yes | FDM-printed PLA with visible layer lines; tint with `color`. | | `petg-print` | PETG print | yes | FDM-printed PETG: glossier than PLA, visible layers; tint with `color`. | | `resin-print` | Resin print | yes | SLA/MSLA resin print: smooth, faintly waxy; tint with `color`. | | `nylon-sls` | Nylon SLS | yes | Powder-bed nylon: matte, grainy, usually white or dyed black. | | `abs-plastic` | ABS plastic | yes | Injection-moulded ABS housings and knobs; tint with `color`. | | `clear-acrylic` | Clear acrylic | yes | Transparent PMMA/polycarbonate windows and covers; tint for coloured acrylic. | | `rubber` | Rubber | yes | Matte elastomer: gaskets, feet, grips; tint with `color`. | | `oak` | Oak | — | Light oak with open grain. | | `walnut` | Walnut | — | Dark oiled walnut. | | `plywood` | Birch plywood | — | Birch plywood sheet: a pale, fine-grained face; its plies show on laser-cut edges. | | `carbon-fiber` | Carbon fibre | — | 2x2 twill carbon fibre under clear coat. | **Environments** (`meta.environment`, default `studio`; viewers can switch): `studio` (neutral soft boxes, paper sweep), `workshop` (warm interior, unfinished maple table), `print-bed` (a dim, hard-lit enclosure over a standard-size PEI build plate (180, 220, 256 or 350 mm) marked with its size), `outdoor` (overcast sky, concrete). --- ## Geometry: the kernel / `Solid` API `build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid` handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF) and **OCCT/replicad** (exact B-rep — STEP). Op lists live in `src/framework/geometry/kernel.js`; the normative semantics (conventions, value semantics, conformance classes, versioning) are in `docs/KERNEL-CONTRACT.md` — the tables below are the authoring-side view of that contract. **Calling convention.** Every multi-parameter op below takes a single **options object** — this is the canonical, documented way to call them (`k.cylinder({ r, h })`, not `k.cylinder(r, r, h)`); the object's keys are named the same across both backends, so a call is self-describing and immune to the positional-argument transposition mistake (swap two same-typed numbers, get a valid *wrong* solid). Single-argument chaining ops (`translate`, `rotate*`, `cut`, `mirror`, `scale`, …) already take one argument and are unaffected. Legacy positional calls (e.g. `k.cylinder(rBottom, rTop, h)`) still work — they're accepted silently until a future breaking contract version removes them (contract v2, partforge 0.59, did not — it only changed `offset` semantics) — but are not shown here; see `docs/KERNEL-CONTRACT.md` "Calling convention" for the full canonical/legacy table and the detection rule. **Kernel — make solids:** | Call | Result | |---|---| | `k.cylinder({ r\|d, h, center? })` · `k.cylinder({ r1, r2, h, center? })` \| `{ d1, d2, h }` | cylinder/cone along +Z (frustum for the cone form); straight takes exactly one of `r`/`d` | | `k.box({ size, center? })` · `k.box({ min, max })` | `{size:[x,y,z]}` = centered X/Y, base at z=0 (`center:true` also centers Z); `{min,max}` = explicit `[x,y,z]` corners | | `k.prism({ points, h, twist?, scaleTop? })` | extrude a 2-D polygon (or an **arc profile** from `roundedProfile`) from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) | | `k.extrude({ profile, h, twist?, scaleTop? })` | extrude a **polygon-with-holes** region from z=0 in one op — `profile` is `{ outer, holes? }` where each contour is a points array **or an arc profile** (`roundedProfile`, for true STEP fillets), or a bare points array / arc profile for outer-only; same `twist`/`scaleTop` as `prism` (both backends) | | `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). A ring's `polygon` may be a point list, `sides`+`radius`, a curve contour, or a single-region hole-free `Shape2D` (multi-region / holed shapes throw). Identical all-line rings are bit-identical on both backends (unchanged legacy). Identical curve-structure rings loft curve-natively on OCCT (STEP keeps true arcs) and facet at fixed LOD on Manifold; structurally different rings auto-resample to a common vertex count with a deterministic seam and share the same faceted STEP at sampling LOD on both backends. `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (point-ring default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth. Curve/resample rings shade by tessellation provenance — smooth only along smooth contour spans, with dividing lines at sharp corners and silhouette-kink rings; see the shading-intent note) | | `k.sweep({ profile, path, cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested | | `k.sphere({ r\|d })` | sphere centred at the origin; bare `k.sphere(r)` also stays valid | | `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); built as one hand-meshed ring stack (no booleans at all, cheaper than `fillet`'s cutters); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` | | `k.roundedCylinder({ r\|d, h, center?, round })` | cylinder with rounded rims — `round` = number (both) or `{ top?, bottom? }`; `round: r` with `top+bottom = h` gives a sphere (capsule when `h > 2r`); one lathe revolve, curve-exact in STEP | | `k.torus({ rMajor, rMinor })` | torus centered at the origin (tube centerline in z=0); `0 < rMinor < rMajor` | | `k.revolve({ profile, degrees? })` | revolve a lathe profile in `[r, z]` (r ≥ 0) around the Z axis (full or partial): a point list, a `{start, segments}` path contour (its arcs stay exact), an `{outer, holes}` region, or a `Shape2D`. A partial sweep spends the circle count in proportion to its angle | | `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove). **Not for threads** — the profile is always circular and rides a frenet frame that rolls with the helix, tilting a tooth off-axis. For threads use `k.screwSweep` | | `k.screwSweep({ profile, pitch, turns, lefthand? })` | screw-motion sweep of an **axial** lathe profile `[[r, z], …]` (same convention as `k.revolve`) — threads, worms, helical ridges. `h = pitch · turns`. The profile's axial extent must not exceed `pitch`; a profile spanning exactly `pitch` must be **periodic** (first radius == last radius) and yields a complete threaded body with no boolean (both backends) | | `k.loftSmooth({ sections, stations?, samples?, shading?, closed? })` | smooth organic loft: ≥2 sparse control sections — point rings, `sides`+`radius`, curve contours, or `Shape2D`, vertex/corner counts may differ per section — interpolated with splines on both backends — the "here are 5 airfoil sections, make it smooth" op. The surface passes through every section exactly. A point section may tag `sharp: [indices]` to keep those vertices true corners instead of letting the spline round them off; a curve/`Shape2D` section gets its corners implicitly from its own non-smooth joints. All sections need the same corner count. `closed: true` closes the loft into a loop (Manifold-only, like `k.loft`). See the propeller reference part (`sharpTE` toggle) | | `k.union(solids[])` | boolean union | **`loft` rings** — each ring is `{ polygon:[[x,y],…] | sides+radius | {start,segments} | Shape2D, z, rotate?, scale? }` (`rotate` is degrees about Z, `scale` is a number or `[sx,sy]`). A ring's `polygon` may be: - a point list `[[x,y],…]` — plain polygon - `{sides, radius}` — shorthand for a regular polygon - a curve contour `{start:[x,y], segments:[...]}` — from `roundedProfile` (true CIRCLE/CUBIC edges in STEP) - a single-region hole-free `Shape2D` — from a 2-D boolean, fillet, or other shape operation Rings with **identical all-line segment structure** (the same straight-sided shape at different z/scale/rotate) are bit-identical on both backends — unchanged legacy behavior, parity by construction. When such a ring set mixes a point-list ring with a Shape2D/contour-sourced one, start-vertex correspondence is not author-controlled (a Shape2D's contour starts wherever its outline begins) — use per-ring `rotate`, or keep every ring the same form, to control twist phase. Rings with **identical curve structure** (containing arcs/Béziers, the same shape at different z/scale/rotate) loft curve-natively on OCCT (STEP keeps exact arc edges), while a Manifold preview facets at fixed LOD. **Structurally different rings** (e.g. a square morphing to a circle, or unequal-N point lists) auto-resample to a common vertex count in shared pure-JS code, with seam = the outermost +X-ray crossing from each ring's centroid; use per-ring `rotate` to tune the twist phase. Every backend then lofts the identical resampled point rings — parity by construction on both — and STEP is faceted at the sampling LOD. Author rings CCW and ordered by ascending `z` (the `regularPolygon` / `polygon.js` helpers are already CCW); loft self-corrects a fully-inverted result so CW-wound or descending-z rings still export a valid outward solid. Multi-region or holed `Shape2D` throws — loft each region as its own solid and union the lofts, or cut holes from the lofted solid after it closes. **Smooth organic lofts.** When the silhouette should be a smooth curve rather than faceted stations, don't densify rings by hand — hand `k.loftSmooth` the few sections you can reason about and let it interpolate (both backends; `k.loft` stays the right tool for deliberate facets and exact station control): ```js const sections = [0, 0.3, 0.6, 0.85, 1].map((t) => ({ polygon: airfoil(chord(t)), // plain [[x,y],…] point rings; counts may differ z: span * t, rotate: pitch(t), // authored twist sweeps correctly — vertex j })); // is the same material line on every section const blade = k.loftSmooth({ sections }); ``` Raise `samples` if the cross-section shows facets, `stations` if banding runs along the spine. Vertex order and the vertex-0 seam are how corresponding points line up across sections (or corner 0, when sections are tagged — below). Tag a true corner (e.g. an airfoil trailing edge that shouldn't be smeared into a smooth curve) with `sharp`, an index list into that section's points — every other section needs the same *count* of corners, tagged or implicit: ```js // src/parts/propeller.js's sharpTE toggle: vertex 0 of each airfoil section // is the trailing edge (upper and lower surfaces meet there); tagging it // keeps that meeting point a crease instead of letting the spline round it. const sections = airfoilSections.map((s) => ({ ...s, sharp: [0] })); ``` A section can also be a curve contour instead of a point ring — its corners come for free from wherever the contour itself isn't smooth (a line/arc joint, say), so it needs no `sharp` of its own (and rejects one if given): ```js // a half-round "D" profile: one line segment + one arc — 2 implicit corners // (the line/arc joints), so it can loft alongside a point section tagged // with exactly 2 sharp indices. const D = { start: [0, -8], segments: [{ to: [0, 8] }, { to: [0, -8], via: [8, 0] }] }; k.loftSmooth({ sections: [{ polygon: D, z: 0 }, { polygon: D, z: 10 }] }); ``` Pass `closed: true` to close the loft into a loop instead of capping both ends (Manifold-only, same restriction as `k.loft`'s `closed`; a part that needs STEP export can't use it). **`sweep`** takes a CCW outline as its `profile` — a point list, or a path contour it samples to one at 48 points per circle (a tube's cost is its ring size times its stations) — and a plain `[[x,y,z],…]` point list as its `path`; the profile stays perpendicular to the path (a rotation-minimizing frame), with sharp mitered corners by default or `cornerRadius` fillets. Worked snippets: ```js // a square tube (extrude a region with a hole) — one op, no boolean cut k.extrude({ profile: { outer: roundedRectProfile(40, 30, 4), holes: [circleProfile(6)] }, h: 10 }); // a tapered, twisting faceted vase wall (see src/parts/faceted-vase.js) const rings = []; for (let i = 0; i <= 24; i++) { const t = i / 24; rings.push({ sides: 6, radius: 30 - 8 * t, z: 120 * t, rotate: 90 * t }); } k.loft({ rings }); // ruled walls, capped ends // a cable/hose: sweep a circle along a 3-D polyline, with rounded bends k.sweep({ profile: circleProfile(3), path: [[0, 0, 0], [0, 0, 20], [15, 0, 20]], cornerRadius: 5 }); // round every corner of any CCW outline, then extrude/loft/prism it k.prism({ points: roundedProfile(bracketOutline, 3), h: 4 }); // true CIRCLE corners, refined at export // a bayonet lug: an exact annular sector (never a sampled one — see "Profiles & patterns") k.prism({ points: ringSectorProfile(28, 30, 36), h: 2 }); // print clearance on an arbitrary cut profile, or an inset wall k.extrude({ profile: k.shape2d(slotProfile(20, 3)).offset(0.2), h: 10 }); // slot cut 0.2 mm looser; arcs stay arcs offsetPolygon(outline, -wall, { corners: "sharp" }); // inset a wall (see planter.js) // A mounting tab: square at the root, semicircular at the tip. The arc names the // point it must pass THROUGH (its apex), so its direction can never flip — there is // no sweep sign to get wrong, and no Math.cos loop to write. const tab = pathProfile([0, -w / 2]) .lineTo([len, -w / 2]) .arcTo([len, w / 2], [len + w / 2, 0]) // tip, via the apex // same arc: .arcTo([len, w / 2], { r: w / 2 }) — radius form, no via to compute .lineTo([0, w / 2]) .close(); k.extrude({ profile: tab, h: 3 }); // A free-form curved side (exact on STEP, faceted at mesh LOD): const lip = pathProfile([0, 0]) .lineTo([20, 0]).lineTo([20, 8]) .cubicTo([0, 8], [14, 16], [6, 16]) // curved top edge .close(); k.extrude({ profile: lip, h: 3 }); // Rounded enclosure: soft vertical edges, a softer lid, a flat base. const shell = k.roundedBox({ size: [60, 40, 22], round: { side: 4, top: 2, bottom: 0 } }); ``` 2-D profile helpers for `prism`/`extrude`/`revolve`/`loft`: `import { pathProfile, roundedProfile, ringSectorProfile, slotProfile, pieProfile, roundedRectProfile, circleProfile, circlePolygon, hexPolygon, regularPolygon, starPolygon, offsetPolygon } from "partforge/geometry"`. **The naming rule: `*Profile` helpers return exact curves** — a path contour whose arcs the kernel facets per quality tier, finer at export, and OCCT keeps as true circles — **and `*Polygon` helpers return straight-edged point lists**, which are built and exported exactly as written (see "Profiles & patterns"). `roundedProfile(points, r | r[])` rounds every corner of a CCW polygon (per-corner radius clamped so neighbouring arcs never overlap) and carries each arc **symbolically**, so STEP export gets real circular edges. Use it for `prism`/`extrude`/`loft` alike (loft lifts arc rings into its curve mode). A scalar `r` rounds every corner; a per-corner `r[]` (length = points) rounds selectively (a `0`, a zero-length edge, or a straight/180° corner stays sharp). `offsetPolygon(profile, delta, { corners?, segs? })` offsets a point-list polygon or `{ outer, holes }` region by `delta` mm (a path contour is sampled to points first, 48 per circle; `k.shape2d(profile).offset(delta)` keeps arcs exact) — positive grows material, negative insets; regions offset material-wise (outer `+delta`, holes `−delta`, so a clearance loosens the whole cut). `corners` picks the convex-corner style: `"round"` (default; the true Minkowski clearance), `"chamfer"`, or `"sharp"` (miter, falling back to chamfer past a miter length of 2·|delta|). It is **simple polygon in, simple polygon out**: an offset whose true result would collapse or split into multiple contours (e.g. insetting a dumbbell past its waist) **throws** a greppable error rather than returning degenerate geometry. Being pure, it works in `derive()` as well as `build()` — the natural home for clearance math. `pathProfile(start)` is a fluent builder for a curve-native path contour (`lineTo` / `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep spline edges on the OCCT/STEP backend and facet at the mesh LOD on Manifold — the same exact-vs-faceted split as `roundedProfile` arcs. `arcTo(to, via)` is a **three-point arc**: `via` is any point on the arc between the current point and `to` (its midpoint is the natural choice), and the sweep is whichever direction passes through it — so an arc's direction is a property of a point you can see, never of a sign. `arcTo(to, { r, sweep?, large? })` is the **radius form** for when you know the radius, not a point on the arc: it computes `via` from the current point, `to`, and `r`, emitting the exact same `{to, via}` segment the three-point form does. `sweep` names the direction the arc itself is traversed (default `"ccw"`), so on a counter-clockwise outline `"ccw"` bulges OUTWARD (a convex bump), and inward on a clockwise hole; `"cw"` is the reverse. `large` (default `false`) picks the major arc over the minor one when both are possible. A radius shorter than half the distance between the current point and `to` throws rather than being silently scaled up (the way SVG's arc command does) — the smallest circle joining the two points is a semicircle at `r = d/2`. Build the symmetric half of a profile once and `mirrorProfile` it (see "Editing profiles") rather than writing the mirrored arcs by hand. `loft` accepts these contours as rings (every ring with the same segment signature lofts curve-to-curve). **`pathProfile` or an authored vector file?** Reach for `pathProfile` (and the polygon helpers above) when the geometry is **computed from parameters** — a profile whose dimensions come from `p`/`d`, which a JSON file cannot see. Reach for an authored `partforge-vector` document (`k.vector2d`, see "Vector geometry" below) when the geometry is **drawn** — a logo, a faceplate outline, a decorative cutout, where each number means one thing and gets edited on its own. The two are freely composable: both produce ordinary 2-D geometry that the same booleans and editing ops accept. **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker (importing the main entry there throws `document is not defined`). **`Solid` — combine / transform / export:** | Call | Result | |---|---| | `s.cut(tool)` / `s.cutAll(tools[])` | boolean subtract (one / batch) | | `s.intersect(other)` | boolean intersection (Manifold; used by collision tests) | | `s.translate([x,y,z])` | move | | `s.rotate(deg, center, axis)` | **internal primitive** — prefer `rotateX/Y/Z` / `rotateAbout` | | `s.rotateX(deg)` / `s.rotateY(deg)` / `s.rotateZ(deg)` | rotate about a world axis through the origin | | `s.rotateAbout({ axis, deg, through? })` | general rotation: `axis` = `"X"｜"Y"｜"Z"` or `[x,y,z]`; `through` = centre (default origin) | | `s.along(dir)` | orient the canonical **+Z** build axis to point along `dir` (`"+X"｜"-X"｜"+Y"｜"-Y"｜"+Z"｜"-Z"`) | | `s.at([x,y,z])` | place an origin-built solid at a point (readable alias of `translate`) | | `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.label(name)` | name this solid's surface for hover/pick feature attribution; survives transforms + booleans; same name on several solids merges into one feature | | `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 | You normally only call the *make/combine/transform* ops; the framework handles `toMesh`/`toSTL`/`toIndexedMesh`/`toSTEP`. Units are millimetres. ### Build-step style: orient → place, and batch features Write build steps so intent is legible — an LLM (and a human) should not have to decode magic vectors. Three habits: - **Orient then place.** Build a primitive along its canonical **+Z** axis, point it with `along(dir)`, then position it with `at([x,y,z])`: ```js // ✗ cryptic: which axis? what centre? k.cylinder({ r, h: L }).rotate(-90, [0, 0, 0], [1, 0, 0]).translate([rp, y1, sz]) // ✓ legible k.cylinder({ r, h: L }).along("+Y").at([rp, y1, sz]) ``` - **Rotate about a point with `rotateAbout`** when the axis isn't through the origin (use `rotateX/Y/Z` for the common origin cases): ```js // ✗ .rotate(angle, [rp, 0, 0], [0, 0, 1]) // ✓ tool.rotateAbout({ axis: "Z", deg: angle, through: [rp, 0, 0] }) ``` - **Batch features** instead of reassigning through a cut-chain: ```js // ✗ body = body.cut(a); body = body.cut(b); body = body.cut(c); // ✓ body.cutAll([a, b, c]) // and k.union([base, f1, f2]) for additive batches ``` - **Size cut tools so no two of them land on exactly the same surface.** Booleans are cheap right up until two operands share a coincident face, at which point OCCT has to classify a surface belonging to both and the search degenerates — seconds become minutes, with no error and no warning. Manifold's mesh CSG is unaffected, so the trap is invisible until a STEP export (the one format pinned to OCCT) or an OCCT-routed build. The classic is a threaded cap: a bore sized straight off the thread's root diameter puts the bore wall and the thread root on the same cylinder. ```js // ✗ the bore wall lands exactly on the thread root const boreD = threadRootD; cap.cutAll([k.cylinder({ d: boreD, h }), thread]); // ✓ a deliberate gap, far below a printable layer const boreD = threadRootD - 2 * 0.05; ``` The same applies to a cut that stops exactly flush with a face — overshoot it instead, which is why cut tools throughout this guide carry `+ 0.4` / `- 0.2` slop. See [boolean-coincident-faces-hang](ERROR-PATTERNS.md#boolean-coincident-faces-hang). The bare `rotate(deg, center, axis)` remains available as the low-level primitive for anything `rotateX/Y/Z`/`rotateAbout` can't express, but prefer the vocabulary above. ### Naming features (`.label()`) Label your part's features, and label them **thoroughly** — this is how a user points at what they want changed. The viewer's hover tooltip, highlight, and pick selection all show a feature's label, so you, the app user, and an agent editing on their behalf share one vocabulary: "make the Drainage hole 10 mm", "raise the Motor upright". A feature with no name can't be referred to — it reads as the whole part, so the request has nowhere to land. Treat comprehensive labeling as the default, not a finishing touch. Name every feature a user could reasonably want to change: the base body, and each functional feature — grooves, mounts, bores, pockets, distinct structural members. ```js const body = k.prism({ points: d.outerPts, h: p.height, scaleTop: p.taper }).label("Faceted wall"); let s = body.cut(cavity.label("Cavity")); if (p.drain > 0) s = s.cut(k.cylinder({ r: d.drainR, h: p.floor + 4 }).at([0, 0, -2]).label("Drainage hole")); ``` - **Aim for functional groups.** Label at the granularity a user would name a thing ("Rope groove", "Tensioner pockets", "Bearing seat"), grouping repeated or related faces under one name. Fine enough to reference any feature; coarse enough that near-identical surfaces don't fragment into dozens of near-duplicates. - A label names the solid's **surface** wherever it survives into the final part — a cutting tool's label lands on the faces it leaves behind (the hole's wall). - Label **after** shaping compound tools (e.g. after an `intersect` clip) and either before or after transforms — labels ride through `at`/`rotate`/etc. Labeling a compound collapses it to ONE shading surface — the majority policy of its registered surfaces (by triangle count) applies to the whole solid, so a faceted policy also suppresses line-drawing on the compound's internal seams. - **Same label merges; distinct siblings need distinct names.** The same label on several solids merges into one feature — label a ring of four bolt holes `"Mounting holes"` and they hover/highlight as one. Conversely, when two similar features are things a user would tell apart, name them apart — two uprights as `"Drum upright"` and `"Motor upright"`, not both `"Upright"`. - Unlabeled geometry falls back to the sub-part's `label`. Faces created by `fillet`/`chamfer`/`shell` are new surfaces, so they use the fallback too. - Works on both backends. On OCCT each label keeps a geometry snapshot for mesh-time classification, so label meaningful features (functional groups — a handful to a couple dozen per part), not hundreds of individual faces. - Names should describe intent ("Drainage hole", not "cylinder2"); make them unique per sub-part unless you specifically want the merge behavior. Labels do double duty in the viewer: the hover tooltip names the feature, and **measurement mode** (the ruler button in the viewbar) measures it — a labeled hole reads ⌀ + depth, a labeled face reads its extents, and a click pins that dimension so it tracks parameter changes live. Label the features a user would want to measure; unlabeled geometry still measures as its bounding box. ### 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. The heavy primitives `loft`, `sweep`, `extrude`, `prism`, and `revolve` are cached this way too: their hash folds every shape-affecting argument (each `loft` ring's points/`z`/`rotate`/`scale`, `sweep`'s profile points/path points/`cornerRadius`/`closed`, `extrude`'s holes, an arc profile's segment specs from `roundedProfile`, and the tessellation from `twist`), so changing any of them is a fresh cache node while an identical rebuild is a hit. This holds on **both backends** — and on OCCT, `translate`/`rotate` are additionally *pose-lazy*: the backend re-poses the cached solid's cached tessellation instead of re-running any B-rep work. A parameter that only feeds a final placement rotation (a lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the slow exact kernel — keep such transforms as the last ops in `build` (or in a `views` pose) rather than baking them into the geometry earlier. In the app, such pose-only edits skip the worker entirely — the viewer re-poses the cached mesh — so they stay smooth even at animation rates (see `runtime.setParams`). A `views` pose needs no geometry: the viewer reads it off a geometry-free probe of the pose alone, so `build()` may query freely. --- ## Parameters: the control-panel schema `src/parts/planter.js`'s "Body" section is a live in-repo example of the full node shape — a preset, headline sliders, and a nested `"Wall"` group holding a `recommended` band and an `innerDia` readout. `src/parts/bracket.js`'s "Shape ops" section shows a `"radio"` control, and mixes it with two sections left on the legacy shape — proof the two coexist in one part. `parameters` is an **array of sections**. Each section is a node with a `controls` array, and **authored order is render order** — what you write top-to-bottom is what the user reads top-to-bottom: ```js { id: "body", // optional; also the node id (see "Ids" below) title: "Body", description: "...", // CommonMark, behind the section's ⓘ glyph collapsed: "auto", // true | false | "auto" (default) when: { ... }, // optional condition — see "Conditions" below controls: [ /* entries, in render order */ ], } ``` Every entry in `controls` is one of four things, told apart by its `type`: - a **control** — bound to one key in `defaults` (`type` defaults to `"slider"`, so a plain `{ key, label, min, max, step }` is a slider); - **`type: "group"`** — a nested container with its own `controls` array; - **`type: "preset"`** — a picker that writes a bundle of parameters at once; - **`type: "readout"`** — a read-only display of a `derive()` output. Groups nest, but **two levels is the limit** — a section plus one fold inside it is as deep as a 300 px rail stays readable, and `partforge lint` warns (`group-depth`) past that. Flatten by promoting the inner group to its own section. A complete section, exercising most of the model: ```js defaults: { profile: "round", facets: 6, dia: 80, wall: 2, feet: 0 }, derive: (p) => ({ innerDia: p.dia - 2 * p.wall }), parameters: [ { id: "body", title: "Body", description: "Silhouette and size of the vessel.", controls: [ { type: "preset", presets: { "Pen cup": { dia: 80, wall: 2, profile: "round" }, Vase: { dia: 120, wall: 2.4, profile: "faceted", facets: 8 }, } }, { key: "profile", type: "radio", label: "Profile", options: [{ value: "round", label: "Round" }, { value: "faceted", label: "Faceted" }], description: "**Round** revolves the silhouette; **faceted** prisms it." }, { key: "facets", type: "slider", label: "Facets", min: 3, max: 12, step: 1, when: { profile: "faceted" }, // only shown on a faceted profile description: "Sides of the prism. 6–8 reads as faceted without looking coarse." }, { key: "dia", type: "slider", label: "Diameter", unit: "mm", min: 30, max: 150, step: 1, description: "Outer diameter at the widest point; 60–100 mm suits a pen cup." }, { type: "group", title: "Wall", collapsed: "auto", controls: [ { key: "wall", type: "slider", label: "Thickness", unit: "mm", min: 0.8, max: 4, step: 0.1, recommended: [1.2, 4], description: "Wall thickness. Under 1.2 mm an FDM print gets fragile." }, { type: "readout", label: "Inner diameter", derivedKey: "innerDia", unit: "mm", description: "Diameter minus both walls — the space something actually has to fit into." }, { key: "feet", type: "checkbox", label: "Raised feet", on: 3, description: "Lift the base on four 3 mm feet so it drains and de-moulds cleanly." }, ] }, ], }, ] ``` Every control `key` must exist in `defaults`, or the control is silently dead — `control-key-not-in-defaults` is an error for exactly that reason. Its value there must be a **number, string or boolean** — a control writes one scalar, so a control bound to an array, an object, `null` or `NaN` is dead in the same silent way (`control-default-not-primitive`), and a host that saves panel settings back into `defaults` cannot write that value either. A non-primitive `defaults` entry that no control is bound to is fine: `defaults` also seeds `p` for `build()`. **Ids.** A section, a group and a preset may carry an `id`; the renderer keys its element, state and disclosure maps on ids, so they must be unique across the whole panel (`duplicate-node-id`). A **control** entry's `id` is ignored — controls get positional ids — and lint reports it as an unknown field. Leave `id` off unless you need a stable handle. ### Control types Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` and `whenFalse`. Beyond those: | `type` | Renders as | Extra fields | |---|---|---| | `"slider"` (default) | a range track plus an editable number box | `unit`, `min`, `max`, `step`, and the refinements below | | `"number"` | the number box alone — for precise or very wide ranges | `unit`, `min`, `max`, `step`, `recommended` (see below) | | `"text"` | a single-line string field | — | | `"textarea"` | a multiline string field; line breaks are preserved | — | | `"checkbox"` | an on/off box: ticked writes `on`, cleared writes `0` | `on` (default `1`) | | `"select"` | a dropdown | `options` | | `"radio"` | a segmented button row | `options` | | `"font"` | a typeface picker with a catalog, else a drop target | `allow`, `preview`, `sourceField` | | `"image"` | an image picker with a catalog, else a drop target showing the artwork | `allow`, `sourceField` | | `"vector"` | a drop target showing the artwork — no catalog exists | `sourceField` | | `"custom"` | a widget the part draws itself — see "Custom controls" below | `widget`, `keys` | Numeric controls always show the number box: drag the slider *or* type an exact value. Typed values may be finer than `step` and may sit **outside `[min, max]`**: the range bounds the slider track, not the parameter. An out-of-range value commits as typed and the build runs with it — the box turns red while the value is outside the range, the thumb pins at the nearer end of the track, and a build that can't take the value fails in the status line while the viewer keeps the last good geometry. A build that *succeeds into nothing* (a boolean that empties a sub-part) is reported there too — "empty: body produced no geometry at these values". Author `min`/`max` as the span the track should cover, not as a guard the build relies on; a build that needs a floor clamps it itself. Text fields write `params` on every keystroke, so the rebuild loop previews the new string immediately; give every text key a string default (empty strings are valid, and the build decides whether its geometry tolerates one). **`options`** (select/radio) takes either the shorthand `["round", "faceted"]` — each entry is both value and label — or the long form `[{ value, label, description? }]`. Values may be strings or numbers, and `defaults[key]` **must be one of them** (`select-default-not-in-options`; watch types, `12` is not `"12"`). An option's `description` surfaces as a hover tooltip on that one option, not as a ⓘ popover. **`sourceField: true`** (font/image/vector) adds a raw source text box to the control. It is **off by default**: the drop target already carries the preview, the drag target and click-to-choose, and where a catalog is wired there is a picker too, so on a 288 px rail a text box is the affordance earning its space least. Turn it on when typing a source by hand is something your users will actually do — pasting an `https:` URL they already have, or a host `pfc-asset:` token. Hiding it changes nothing else: the same values are accepted by the same allow list, and a source set in `defaults` or by the host still applies. For a `"font"` control with no `fontCatalog` this is the only text entry there is, so a standalone app that expects users to paste font URLs should set it. **`allow` and `preview`** (font) configure the typeface control. `allow` lists the source kinds a **param-supplied** value may use — what the picker writes, or what arrives in a share link: | value | accepts | |---|---| | `"https"` | any `https:` URL. **The default** — omitting `allow` means `["https"]` | | `"gstatic"` | `https://fonts.gstatic.com` only (hostname-exact: a lookalike host is refused) | | `"asset"` | a `pfc-asset://` token — a font the host has stored for this part | Name as many as apply (`allow: ["gstatic", "asset"]`); anything unnamed is refused, which is how `http:`, `file:`, `data:` and `blob:` are closed off. The check is deliberately narrow — **it applies only to values that arrive as params.** A source you write into `fonts` yourself is code, not user input, and stays unrestricted: `fonts: { label: "https://cdn.example.com/Courier-Prime.ttf" }` keeps working whatever `allow` says. A refused param falls back to `defaults[key]`, and the build carries a warning naming the key rather than failing (lint's `font-source-scheme` catches the case where that default is itself refused). `allow` gates what the **picker fetches** too: a family whose files it refuses is dropped from the list rather than offered, and neither that family's name-preview face nor its weight samples are ever requested. `preview` is the sample string the picker's weight list renders each face in — set it when the generic sample shows the wrong glyphs (`preview: "0123456789"` for a part that letters digits). Defaults to `Hamburgefonstiv 0123`. **`"readout"` is not a control.** It has no `key`, never writes `params`, and can never be a preset target. It displays one output of `derive()`, named by `derivedKey`, refreshed on every parameter change; `unit` is appended to numeric values. A `derivedKey` no `derive` group returns shows an em-dash forever, which `readout-unknown-derived-key` warns about. Readouts are how a panel closes the loop on design intent — show the user the clearance, the inner diameter, the resulting wall — without adding a parameter nobody should edit. **A `group`** takes `type`, `id`, `title`, `collapsed`, `bare`, `controls`, `hidden`, `when` and `whenFalse`. It deliberately takes **no `description`**: the fold's title is itself a button, and there is nowhere to hang an ⓘ glyph beside it. Put the explanation on the section or on the controls inside. `bare: true` drops the title and the disclosure entirely, leaving an indented block — useful for a run of controls that appear and disappear together under one `when`. ### Control metadata - `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 node from the panel. Its `key` must still exist in `defaults` and still drives the geometry: this is *no UI*, not *no parameter*. Use it for internal constants the end user shouldn't edit. A group left with no visible children doesn't render at all, and neither does an empty section. ### Slider refinements Three optional fields shape how a numeric track behaves. All three are worth reaching for when a raw linear slider misrepresents the parameter. - **`scale: "log"`** — the thumb travels geometrically, so a 0.1–100 range gives each decade equal width instead of burying everything below 10 in the first pixel. The number box stays linear and exact, so typing `0.5` still works. `min` **must be greater than 0** (`log(0)` is `-Infinity` and the mapping breaks); lint reports `log-scale-needs-positive-min`. - **`ticks: [...]`** — marked values on the track (a native `datalist`). Every tick must sit inside `[min, max]`. Add **`snap: true`** to quantize *slider drags* to the nearest tick; the number box stays free, so an off-tick value is always still typeable. Use it for stock sizes: M3/M4/M5, 3 mm / 6 mm plate. - **`recommended: [lo, hi]`** — tints that span of the track. This is the **visual companion to the DFM checks**: the band is where the process the part targets is comfortable (minimum wall, nozzle multiples, sane clearances), and `verify`'s `minWall` / process checks are the same judgement enforced at measure time. It is purely advisory — it never colours the number box (red is reserved for values outside `[min, max]`), and outside values remain selectable, because a user who knows their printer should not be blocked by a default profile. Say **why** the band sits where it does in the control's `description` ("below 1.2 mm a 0.4 mm nozzle prints walls poorly"); the band alone is a hint, the description is the reason. `ticks`, `snap` and `recommended` render on a **linear track only**; combined with `scale: "log"` they are ignored, and `slider-refinement-invalid` warns. On a `"number"` control there is no track at all, so `recommended`, `scale`, `ticks` and `snap` do nothing. ### Conditions: `when` and `whenFalse` `when` is valid on **any** node — a control, a group, a preset, a readout, or a section itself. It is a plain data condition evaluated against raw parameters: ```js when: { profile: "faceted" } // equality when: { wall: { gte: 1.2 } } // gt | gte | lt | lte | ne when: { style: { in: ["cup", "vase"] } } // membership when: { drain: { gt: 0 }, mode: "planter" } // multiple keys are ANDed when: { allOf: [{ drain: { gt: 0 } }, { mode: "planter" }] } when: { anyOf: [{ style: "cup" }, { style: "vase" }] } when: { not: { style: "plain" } } ``` The operators are `gt`, `gte`, `lt`, `lte`, `ne` and `in`; the combinators are `allOf`, `anyOf` and `not`. Two rules make conditions statically checkable, and both are enforced as **errors** because either failure is silent at runtime: - **Raw parameter keys only.** A `when` reads keys from `defaults`, never derived values — that is what lets lint check every referenced key against `defaults` (`when-key-not-in-defaults`), which no predicate function could support. Readouts reach derived values through their own `derivedKey`, so there is never any doubt which namespace a name is in. - **Known operators only.** `evalWhen` treats an unrecognised operator as false, so a typo would hide the node forever; `when-unknown-operator` catches it first. A malformed condition evaluates to `false` rather than throwing — a control that hides is better than a panel that crashes. When the condition is false the node is **removed from the layout**, taking its subtree with it if it is a group. Set **`whenFalse: "disable"`** to grey it in place instead, for the case where the user should see that an option exists but needs something else switched on first. Disabling propagates through the whole subtree and sets real `disabled` attributes, so a disabled control cannot be focused or dragged. **`when` is not relevance dimming.** The panel also dims controls automatically, and the two are different mechanisms that must stay visually distinct: | | Relevance dimming | `when` | |---|---|---| | Answers | "does the geometry on screen actually read this parameter?" | "did the author say this applies right now?" | | Comes from | probing the build — automatic, nothing to write | your `when` condition | | Looks like | faded but fully usable, with a "doesn't affect the parts in the current view" tooltip | gone from the layout, or genuinely disabled | A control can be relevant but conditioned away, or conditioned in but irrelevant. Both recompute on the same tick as any parameter change. Don't reach for `when` to reproduce dimming — you'd be hand-maintaining something the framework already knows. ### Collapsing Every section and every titled group is a disclosure, controlled by `collapsed`: `true` (start closed), `false` (start open), or `"auto"` (the default). `"auto"` defers to one rule: > A panel with **three or fewer visible top-level sections** opens every `"auto"` > section and fold on load. Beyond that, they all start closed. The rail is a fixed-height column, and a long part otherwise scrolls forever; three sections is a panel the user can take in at a glance. The count is over the sections in the built tree — `hidden: true` sections and sections left with nothing in them are gone before counting, but a section that a false `when` or relevance merely hides from view still counts, since it can come back without rebuilding the panel. Only the **first** render applies it — after that the user's own clicks own the folds, and a slider drag never snaps a section they opened back shut. A `bare: true` group has no disclosure at all and is never collapsed. ### Presets A preset picker is a node like any other: ```js { type: "preset", label: "Size", presets: { M3: { od: 8, bore: 3.4, h: 10 }, M5: { od: 12, bore: 5.4, h: 16 }, } } ``` Each key of `presets` is a name, each value a bundle of parameter overrides (every key of which must exist in `defaults` — `preset-key-not-in-defaults`). The picker lists the names plus **Custom**, and opens on the first name. Choosing a preset assigns its overrides over `params` and refreshes that section's controls; editing any control in the section afterwards drops the picker to **Custom**. Because it is a node, a picker can sit **anywhere** in `controls` — among the controls it affects, not necessarily at the top — and a section may carry more than one. Note that Custom-marking tracks the section's **first** picker only, so if two pickers in one section both need to show divergence, give each its own section. **Preset names are global to the part**, not to the section: `verify()` expands one case per preset name (so every preset gets measured), and a repeated name throws there. `duplicate-preset-name` catches it at lint time instead. ### Custom controls A `type: "custom"` control renders a widget the part draws itself — a clickable hex grid, an organizer whose walls toggle on click, a picture of the part's own outline with hot regions. Reach for it when the user configures **many similar things individually**, or makes a **spatial choice** no slider or select can express. Never for a value an existing control already covers: a slider is still a slider. ```js // part.js import { tilePicker } from "./tile-picker.js"; export default { defaults: { tileSize: 20, tiles: [{ q: 0, r: 0, height: 10 }, { q: 1, r: 0, height: 14 }], }, parameters: [{ title: "Tiles", controls: [ { type: "slider", key: "tileSize", min: 10, max: 40 }, { type: "custom", key: "tiles", label: "Tile layout", widget: tilePicker, description: "Click a tile to select it. Drag to move it." }, ], }], parts: { tiles: { build: (k, p) => /* p.tiles is the array */ } }, }; ``` - `key` names the param the widget owns. It may hold a **JSON value**: numbers, strings, booleans, arrays and plain objects of those, at most 16 KB serialized and 8 levels deep, never `null` (`custom-default-not-json`). `build()` reads it like any other param. This is the one place the "a control writes one scalar" rule is relaxed. - `keys` (optional) lists further scalar params the widget may also write. - `widget` is a function `(host) => …`, normally imported from a sibling file so `part.js` stays readable (`custom-control-widget-not-function`). - `label`, `description`, `hidden`, `when` and `whenFalse` behave as on any control. **The widget function.** It runs once per mount and draws into `host.el` with plain DOM and SVG. It may return `{ update, dispose }`. ```js // tile-picker.js export function tilePicker(host) { const svg = host.h("svg", { viewBox: "0 0 200 160", width: "100%" }); const detail = host.h("div"); host.el.append(svg, detail); let stopDetail = null; function draw() { const tiles = host.get(); // a fresh clone of the owned value const sel = host.state.selected ?? null; // survives the remount an edit performs svg.replaceChildren(...tiles.map((t, i) => host.h("polygon", { points: hexPoints(t.q, t.r), class: i === sel ? "pf-hit selected" : "pf-hit", onpointerdown: () => { host.setState({ selected: i }); draw(); }, }))); stopDetail?.(); stopDetail = sel === null ? null : host.controls(detail, [ { type: "slider", key: "height", label: "Height", min: 4, max: 30 }, ], { path: `${sel}` }); } draw(); return { update: draw, dispose: () => stopDetail?.() }; } ``` **The host.** | Member | Meaning | |---|---| | `host.el`, `host.doc` | The slot to draw into, and its document. | | `host.get(key?)` | A clone of the current value (default: the owned key). Any param is readable. | | `host.set(value, {key?, commit?})` | Replace a value with a **new** one — never mutate what `get` returned. Schedules the rebuild and commits, unless `commit: false`; then call `host.commit()` when the gesture ends (a drag). Throws for a key you do not own or a value outside the contract. On a **retired** widget (one whose code already threw) `set`, `commit` and `setState` are silent no-ops. | | `host.commit(keys?)` | Ends a deferred gesture. A no-op when nothing changed. | | `host.derived` | The latest `derive()` output, the same object readouts show. | | `host.state`, `host.setState(patch)` | Transient JSON (a selection, an open panel). Not a param, never persisted, but it **survives a remount**, which every edit performs. | | `host.controls(container, controls, {path})` | Mount ordinary built-in controls bound *inside* the owned value at a dotted `path` (`"3"`, `"walls.north"`). Their edits commit the owning key. Returns a disposer. One level: no custom control inside, and no `font`, `image` or `vector` sub-control at a path (their asset lookups are keyed on the part's real param names). | | `host.h(tag, attrs, ...children)` | Element builder. SVG tags get the SVG namespace; `on` attrs become listeners; `class` and `style` pass through. | | `host.svg(text)` | Parse an SVG string to an element you can append and wire up. | | `host.svgFromVector(doc)` | A partforge-vector document → inline `