partforge 0.113.0 → 0.115.0

package/docs/AUTHORING-PARTS.md

@@ -745,6 +745,7 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"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]`**:
@@ -954,6 +955,132 @@ pickers in one section both need to show divergence, give each its own section.
 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<event>` 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 `<svg>` (the same renderer the `vector` control uses). |
+| `host.file(pathOrToken)` | Text of one of the part's own files, by path or a `pfc-tree://` token, or null. |
+| `host.disabled` | Whether a `when`/`whenFalse: "disable"` currently disables this control. |
+
+`update({reason, disabled})` is called when your key changes from outside the widget
+(`reason: "sync"` — a preset, undo, `setParams`), when `derived` changes
+(`"derived"`), and once after `host.state` was restored on mount (`"restore"`). It is
+**not** called for your own `set`. `dispose()` runs on teardown.
+
+**Rules that keep it working.**
+
+1. Size SVG with `viewBox` plus `width: 100%`. The rail is 288px wide by default and
+   narrower on a phone, where it is the bottom sheet.
+2. Use pointer events, not mouse events, and put `class="pf-drag"` (or
+   `touch-action: none`) on anything dragged — otherwise a finger scrolls the sheet.
+3. Keep selection and similar state in `host.state`, not in a closure: every edit
+   remounts the part and your function runs again.
+4. Hand `set` a new value. `get` returns a clone precisely so the stored value is never
+   edited in place.
+5. A throw in creation, `update`, or a listener installed through `host.h` replaces
+   the widget with an error card and reports it (a hosting agent sees it in the apply
+   result as `panelErrors`); other controls keep working. A throw in `dispose` is
+   reported the same way but leaves no card — there is nothing left to show it on. A
+   listener you attach yourself with `addEventListener`, rather than through `host.h`,
+   is **not** guarded — wire listeners through `host.h`, or wrap your own in try/catch.
+
+**Looking native.** The slot inherits the rail's font, colours and light/dark theme.
+Bare `<button>`, `<input>` and `<select>` elements pick up the built-in looks
+automatically; the built-in classes are available by name for the exact thing:
+`row`, `seg` (a segmented row of buttons), `action`, `ghost`, `num`, `text-input`,
+`select-input`; and for SVG, `pf-hit` (clickable, with a `selected` state) and
+`pf-drag`. Sub-controls mounted through `host.controls` *are* the built-in widgets.
+
+**Reading the part's own files.** Artwork can live beside the code (the tree is text,
+so an SVG, a `partforge-vector` JSON document or a JSON data file — not a PNG).
+Two routes: store the SVG as a string in a JS module (`assets/emblem.svg.js` exporting
+a template literal) and import it like any sibling file — no framework support
+needed; or read it with `host.file("assets/emblem.svg")` and inline it with
+`host.svg(text)`. Give regions ids and wire `pointerdown` on `#wall-3` to toggle
+`walls[3]` in the owned value.
+
+**What a widget cannot do.** Never `fetch` or otherwise reach the network — a widget
+is a pure function of the part and its params, and a hosted sandbox may refuse the
+request or have no credentials to make it with. Also: no imports beyond the part's
+own files, nothing outside `host.el`, and no reading of `params` except through
+`host`.
+
 ### Legacy section shapes (still supported)
 
 Everything above is what a **new part should write**. The original array-based shapes
@@ -1143,6 +1270,10 @@ defaulting everything to a slider:
   reason for a two-position slider to exist.
 - **A computed value the user should see but not set** → `"readout"`. It costs no
   parameter and answers the "so what did that do?" question in place.
+- **Many similar things configured individually, or a spatial choice** (which tiles
+  exist and how tall each is; which walls of an organizer are present) →
+  `"custom"`: a widget the part draws, holding one JSON value. See "Custom controls"
+  above; use it only when no built-in control expresses the choice.
 
 Then gate what doesn't always apply. A control that is meaningless in the current mode
 should carry a **`when`** rather than sit there inert — hide it by default, or use
@@ -2791,7 +2922,9 @@ previously didn't; that's the fix working as intended, not a regression.
 `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` (errors);
+`when-key-not-in-defaults`, `when-unknown-operator`, `unknown-control-type`,
+`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).
@@ -2802,6 +2935,10 @@ 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
@@ -3505,7 +3642,14 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
   `slotPolygon`, `ringSectorPolygon` and `circleProfile`; 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 high-res "print" kernel.
+  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)).
 - **Display placement is view-independent**; only `place(..., { purpose: "export" })` may
   depend on `view` ([view-dependent-display-place](ERROR-PATTERNS.md#view-dependent-display-place)).
 - **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT

package/docs/ERROR-PATTERNS.md

@@ -823,6 +823,12 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** *(partforge ≥ 0.112.)* A hand-authored 2-D profile (a point list, a `pathProfile` contour, a `{outer, holes}` region — handed to a factory op, to `k.shape2d`, or as a `Shape2D` boolean operand) crosses itself. Manifold fills a point ring even-odd, so the crossing quietly inverts the fill on one side instead of failing. The usual author of the crossing is an arc sampled into points by hand (a `Math.cos` loop) whose sweep sign or endpoint order is wrong, or a mirrored half whose point order was not reversed. The kernel now runs `validateProfile` on the way in and reports each crossing on the build result's `warnings`; a `Shape2D` is not re-validated, `text2d`/`vector2d` lifts are trusted, and a profile over 4000 segments is skipped (for `loft`, the ceiling is the sum over all its rings). At most **three** crossings are reported per profile — the third reads `… (and N more crossings on this profile)` — so one badly-drawn star cannot evict every other warning in the build. A hole whose edge touches or runs along its outer is **not** reported: that builds exactly as drawn, and only a contour crossing itself inverts the fill.
 - **Fix:** Rebuild the curved parts of the outline with `pathProfile(start).lineTo(p).arcTo(to, via).close()` — a three-point arc sweeps through `via`, so its direction cannot flip — or with the `partforge/geometry` helpers (`roundedProfile`, `filletPolygon`, `slotPolygon`, `ringSectorPolygon`, `circleProfile`); build a symmetric half once and `mirrorProfile` it rather than writing the mirror by hand. Confirm with `validateProfile(profile).ok` before extruding. The reported coordinate is in the profile's own frame (before any `rotate`/`at`).
 
+## export-kernel-out-of-memory
+
+- **Symptom:** `Out of bounds memory access` (Safari) or `memory access out of bounds` (Chrome, Node) from an STL or 3MF export — or from a build — of a part whose preview renders fine; often followed, on every later build in the same session, by `Manifold instance already deleted`, `Out of bounds call_indirect`, `call_indirect to a signature that does not match`, `table index is out of bounds`, or `null function or function signature mismatch`.
+- **Cause:** The mesh kernel's WASM heap ran out while building the print-quality mesh, and a WASM trap leaves that kernel instance corrupt — every later call into it fails until the worker is replaced or the page reloaded. Before partforge 0.115 the print tier meshed every circle at a flat 480 segments whatever its radius, so a part with a few hundred small spheres or cylinders (a 0.75 mm rivet was 115,200 triangles — 176 of them are 20 M before a single boolean) exhausted a 4 GB heap on its first export while its whole unioned preview was a few hundred thousand triangles. Since 0.115 print sizes circles by a 0.01 mm chord tolerance, floored at the preview count, so a part that previews normally exports at roughly the preview's cost; a part that still traps is genuinely too heavy for the browser at ANY quality — usually thousands of repeated small features, or a boolean chain whose intermediates dwarf the result.
+- **Fix:** Reload the page (or let the host replace the kernel worker) before retrying anything — the trapped instance cannot recover. Then reduce what the export has to hold at once: build repeated detail as one union of instances rather than a chain of per-feature booleans, drop feature counts that exceed what the print can show (a 0.75 mm sphere prints as a dot), or pass `segs` to `revolve` where a coarser sweep is acceptable ([Preview vs print quality](AUTHORING-PARTS.md#conventions--gotchas)). Do NOT strip visible detail from the part to dodge a pre-0.115 trap — update partforge instead; the geometry was never the problem.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -375,7 +375,12 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 
 `quality` (`"preview"` | `"print"`) is **advisory**: it trades tessellation density for
 speed and a backend may bake it at kernel creation (Manifold does). A part must never
-depend on triangle counts, segment counts, or normals being present.
+depend on triangle counts, segment counts, or normals being present. The in-repo
+backends both define `print` as a **chord tolerance of 0.01 mm** (OCCT's linear
+deflection; Manifold's per-circle segment rule in `geometry/circle-segs.js`, floored at
+the preview's 116 segments so print is never coarser than preview and capped at 480), so
+a small feature costs the export exactly what its preview cost — the property that makes
+"if it previews, it exports" hold. Preview is a flat 116 on Manifold, a visual choice.
 
 ### Shading intent (toMesh normals and edges)
 
@@ -554,8 +559,9 @@ curve-exact (they integrate the real curves; they do not measure a tessellation)
 so it is backend-identical too, like everything else in this list.
 
 **Lazy materialization.** Backend geometry is built only where it is unavoidable.
-Three readbacks tessellate to point rings at the backend's own LOD (Manifold 116
-preview / 480 print, OCCT 64): `toRegions()`, `simple()` (its unwrapped form), and
+Three readbacks tessellate to point rings at the backend's own LOD (Manifold 116 per
+circle at preview and, at print, the fewest segments holding a 0.01 mm chord sagitta
+between 116 and 480 — per arc, by its radius; OCCT 64): `toRegions()`, `simple()` (its unwrapped form), and
 `regions()` — scission currently round-trips through `toRegions()`, so each returned
 `Shape2D` is a faceted copy, not a curve-native slice of the original. `extrude` and
 `revolve` materialize the shape into the backend's own form instead (Manifold: a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.113.0",
+  "version": "0.115.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,10 @@
       "types": "./types/ingest.d.ts",
       "default": "./src/ingest.js"
     },
+    "./panel-values": {
+      "types": "./types/panel-values.d.ts",
+      "default": "./src/panel-values.js"
+    },
     "./tokens.css": "./src/framework/tokens.css",
     "./chrome.css": "./src/framework/chrome.css"
   },
@@ -83,6 +87,9 @@
       ],
       "ingest": [
         "./types/ingest.d.ts"
+      ],
+      "panel-values": [
+        "./types/panel-values.d.ts"
       ]
     }
   },

package/src/framework/app.css

@@ -64,8 +64,10 @@ canvas { display: block; }
    Condition-hidden sections (.hidden, a `when` that evaluated false) are excluded
    for the same reason. Do not simplify this to `.section:first-child { border-top: 0 }` — that
    matches DOM position rather than visibility, and leaves a stray divider
-   floating at the top whenever applyRelevance hides the first section. */
-.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden) {
+   floating at the top whenever applyRelevance hides the first section. A bare
+   sub-panel section (host.controls inside a custom control) never gets the divider
+   because the widget owns its framing. */
+.section:not(.section-hidden):not(.hidden) ~ .section:not(.section-hidden):not(.hidden):not(.bare) {
   border-top: 1px solid var(--pf-border);
 }
 /* Section disclosure header: the whole row is the click target (render.js
@@ -382,6 +384,52 @@ button.ghost { background: transparent; border: 1px solid var(--pf-border); colo
 button.ghost:hover:not(:disabled) { background: var(--pf-surface-2); }
 button.action:disabled { opacity: .5; cursor: default; }
 
+/* Custom controls (type: "custom"): a part-authored widget in the rail. The
+   slot inherits the rail's cascade (font, colours, --pf-* tokens); these rules
+   give BARE elements the built-in controls' look so a widget written with
+   plain <button>/<input>/<select> still reads as native, and provide two
+   opt-in classes for SVG: .pf-hit (a clickable region) and .pf-drag (a
+   dragged one — touch-action: none is what lets a finger drag it on a phone
+   instead of scrolling the sheet). */
+.pf-custom { margin: 9px 0; }
+.pf-custom.hidden { display: none; }
+.pf-custom-slot { display: flow-root; }
+/* Every selector in this block is wrapped so the WHOLE thing resolves to
+   (0,0,0) — including the :not([type=...]) chain, which is otherwise an
+   attribute selector per :not() and would still out-specify a class rule
+   like .text-input (0,1,0) or .row .num (0,2,0). At true zero specificity,
+   any class rule wins, so a named built-in class (.seg button, .text-input,
+   select.select-input, …) always beats these bare-element defaults. */
+:where(.pf-custom) :where(svg) { display: block; max-width: 100%; height: auto; }
+:where(.pf-custom) :where(button) {
+  font: inherit; font-size: 12px; padding: 5px 9px; cursor: pointer;
+  background: transparent; border: 1px solid var(--pf-border); color: var(--pf-text-2);
+  border-radius: var(--pf-radius-control);
+}
+:where(.pf-custom) :where(button:hover:not(:disabled)) { background: var(--pf-surface-2); }
+:where(.pf-custom) :where(button:disabled) { opacity: .5; cursor: default; }
+:where(.pf-custom) :where(input:not([type="range"]):not([type="checkbox"]):not([type="radio"]), select) {
+  font: 12px/1.4 var(--pf-mono);
+  background: var(--pf-input-bg); color: var(--pf-text-strong);
+  border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); padding: 6px 8px;
+}
+:where(.pf-custom) :where(input:focus, select:focus, button:focus-visible) {
+  outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
+}
+.pf-custom .pf-hit { cursor: pointer; }
+.pf-custom .pf-hit:hover { fill: color-mix(in oklab, var(--pf-accent) 25%, transparent); }
+.pf-custom .pf-hit.selected { fill: color-mix(in oklab, var(--pf-accent) 45%, transparent); stroke: var(--pf-accent); }
+.pf-custom .pf-drag { touch-action: none; }
+.pf-custom-error {
+  margin: 4px 0; padding: 6px 8px; border: 1px solid var(--pf-err); border-radius: var(--pf-radius-control);
+  color: var(--pf-err); font-family: var(--pf-mono); font-size: 11px; line-height: 1.4; word-break: break-word;
+}
+.pf-custom-error-title { font-weight: 600; margin-bottom: 2px; }
+/* A sub-panel inside a custom control (host.controls): no header, no indent. */
+.section.bare > .sec-body { padding: 0; }
+.section.bare { padding: 0; border: 0; }
+
 .dl { margin-top: 14px; }
 .dl-head {
   font-family: var(--pf-mono); font-size: 10px; font-weight: 600;

package/src/framework/geometry/circle-segs.js

@@ -0,0 +1,56 @@
+// Per-circle segment counts for the mesh backend's two quality tiers.
+//
+// `preview` is a flat count: 116 segments per full circle whatever the radius. It is
+// a VISUAL choice — the density every part is previewed, captured and thumbnailed
+// at — and it already holds a 0.05 mm chord sagitta out to a 136 mm radius, so
+// nothing is gained by scaling it.
+//
+// `print` used to be a flat 480, sized (whether anyone meant it or not) for a circle
+// nearly a metre across: 480 segments meet a 0.01 mm sagitta at r ≈ 467 mm. Spent on
+// a 0.75 mm rivet sphere that is 115,200 triangles for a chord error of 1.6e-5 mm —
+// a thousandth of any printer's resolution — and a part carrying 176 such rivets
+// (20 M triangles of rivets before a single boolean, against a preview whose whole
+// unioned body was 530k) trapped the WASM kernel with "memory access out of bounds"
+// on its first STL export, on a fresh 4 GB instance. So the print tier is now
+// tolerance-based: the fewest segments that keep the chord sagitta r·(1 − cos(π/n))
+// under SAGITTA_TOL.print — the same 0.01 mm the OCCT backend's print tessellation
+// uses, and the same formula `roundAllSegs` (mesh-roundall.js) and `blendSegs`
+// (mesh-fillet.js) already apply to their own circles. Those two keep their own
+// tolerances and clamps on purpose (roundAll has a preview tolerance and a 12..64
+// window; the fillet blends at 1 µm) — this table is not theirs to share, and
+// `roundAllSegs(r, "preview")` against it would collapse to a flat 12. Two clamps
+// make the rule here safe:
+//
+// - FLOOR at the preview count. An export must never be coarser than the preview the
+//   user approved on screen, so below the radius where 116 segments already meet the
+//   tolerance (r ≈ 27 mm) print and preview facet identically — which is also what
+//   makes "if it previews, it exports" true for small features: the export costs what
+//   the preview already paid.
+// - CAP at the old flat count. A circle large enough to need more than 480 keeps
+//   exactly the density it always had; nothing gets FINER than before.
+//
+// One rule, one place: every Manifold-backend site that facets a circle of known
+// radius — sphere, cylinder, boredCylinder, roundedBox, revolve, and the arc and
+// Bézier samplers behind prism/extrude/Shape2D — sizes through `circleSegs`. The
+// helix tube's station/ring counts (TUBE in manifold-backend.js) and mesh-fillet's
+// blend bands keep their own sizing; loft rings keep LOFT_SEGS.
+//
+// Pure, dependency-free: profile.js's samplers take a `(r) => n` function in place of
+// a count, and this is what the backend hands them.
+
+export const SEGS = { preview: 116, print: 480 };       // full-circle segments (flat / cap)
+export const SAGITTA_TOL = { print: 0.01 };             // mm — max chord sagitta per tier
+
+// Segments per full circle for a circle of radius `r` at `quality`. A tier with no
+// tolerance (preview, or an unknown tier) is flat. A degenerate radius (0, negative,
+// NaN, undefined) takes the floor: it facets like the preview and never throws.
+export function circleSegs(r, quality) {
+  const cap = SEGS[quality] ?? SEGS.preview;
+  const tol = SAGITTA_TOL[quality];
+  if (tol === undefined) return cap;
+  const floor = SEGS.preview;
+  if (!(r > tol)) return floor;
+  // acos(1 − tol/r) is the half-angle of a chord with sagitta tol; π over it is the
+  // full-circle count. r = Infinity gives acos(1) = 0 → Infinity → the cap.
+  return Math.min(cap, Math.max(floor, Math.ceil(Math.PI / Math.acos(1 - tol / r))));
+}

package/src/framework/geometry/manifold-backend.js

@@ -19,6 +19,7 @@ import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
 import { meshFillet, meshChamfer, UnsupportedEdgeError } from "./mesh-fillet.js";
 import { meshRoundAll, prismSection, roundAllSegs } from "./mesh-roundall.js";
+import { SEGS, circleSegs } from "./circle-segs.js";
 import { checkBooleanResult } from "./boolean-gate.js";
 import { KernelCapabilityError } from "./errors.js";
 import { heightfieldMesh, hashGridData } from "./heightfield.js";
@@ -26,7 +27,10 @@ import { heightfieldMesh, hashGridData } from "./heightfield.js";
 const PLANE_NORMAL = { XY: [0, 0, 1], XZ: [0, 1, 0], YZ: [1, 0, 0] };
 // 'preview' = interactive view (fast); 'print' = STL export (high-res, used only
 // by the export path — Manifold meshing is cheap, so we tessellate generously).
-const SEGS = { preview: 116, print: 480 };       // circular segments
+// Full-circle segment counts live in circle-segs.js: preview is a flat SEGS.preview,
+// print sizes each circle by chord tolerance through circleSegs (floored at the
+// preview count, capped at SEGS.print). `segs` below is the tier's cap — the hash
+// key and the count handed to consumers that size themselves (mesh-fillet, loft).
 const TUBE = { preview: { stationsPerTurn: 38, ringSegs: 24 }, print: { stationsPerTurn: 160, ringSegs: 40 } };
 
 // true axis-angle rotation as a column-major 4x4 (manifold Mat4), translation 0
@@ -44,6 +48,9 @@ function axisAngleMat4(axis, deg) {
 export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   const { Manifold, CrossSection } = wasm;
   const segs = SEGS[quality], tube = TUBE[quality];
+  // Per-radius count for every site that facets a circle it knows the radius of; the
+  // samplers behind prism/extrude/Shape2D take it as a function (profile.js).
+  const segsAt = (r) => circleSegs(r, quality);
 
   // Manifold/CrossSection are WASM objects with no garbage collection — every
   // primitive and boolean op allocates a new one. Track them all and free them
@@ -166,7 +173,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // on it in pure JS; no CrossSection is built until a shape is handed to a kernel op.
   // `extrude`/`revolve` are thunks because `kernel` below is defined after this.
   const shape2d = makeShape2dFactory({
-    segs,
+    segs: segsAt, // the readbacks (toRegions/simple) tessellate at the same per-radius LOD as the kernel ops
     extrude: (o) => kernel.extrude(o),
     revolve: (o) => kernel.revolve(o),
     recordWarning,
@@ -177,7 +184,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // once, and the cache's pin/dispose keeps the WASM object alive exactly as long as
   // the entry (cleanup() skips pinned objects).
   const csFor = (shape) => cache.lookup(h("cs2d", shape._hash, segs), () => {
-    const cs = T(CrossSection.ofPolygons(regionPolys(shape._regions, segs), "EvenOdd"));
+    const cs = T(CrossSection.ofPolygons(regionPolys(shape._regions, segsAt), "EvenOdd"));
     return { value: cs, pin: cs, dispose: () => cs.delete?.() };
   });
 
@@ -401,13 +408,13 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       if (typeof selector === "function") throw new KernelCapabilityError("fillet: function selectors need the OCCT backend");
       if (r === 0) return wrap(m, hash); // contract: zero magnitude is the identity
       return cached(h("fillet", hash, r, selector ?? null, segs), () =>
-        meshCadOp("fillet", m, () => meshFillet(kernel, wrap(m, hash), { r, edges: selector, segs })));
+        meshCadOp("fillet", m, () => meshFillet(kernel, wrap(m, hash), { r, edges: selector, segs, segsAt })));
     },
     _chamferRaw: (d, selector) => {
       if (typeof selector === "function") throw new KernelCapabilityError("chamfer: function selectors need the OCCT backend");
       if (d === 0) return wrap(m, hash);
       return cached(h("chamfer", hash, d, selector ?? null, segs), () =>
-        meshCadOp("chamfer", m, () => meshChamfer(kernel, wrap(m, hash), { d, edges: selector, segs })));
+        meshCadOp("chamfer", m, () => meshChamfer(kernel, wrap(m, hash), { d, edges: selector, segs, segsAt })));
     },
 
     // The AUTHOR-FACING ops degrade on failure instead of failing the build (the
@@ -628,14 +635,16 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   };
 
   const kernel = finishKernel({
-    cylinder: (rb, rt, h2, { center = false } = {}) =>
-      wrap(T(Manifold.cylinder(h2, rb, rt, segs, center)), h("cylinder", rb, rt, h2, center, segs)),
+    cylinder: (rb, rt, h2, { center = false } = {}) => {
+      const n = segsAt(Math.max(rb, rt)); // a cone is sized by its wider end
+      return wrap(T(Manifold.cylinder(h2, rb, rt, n, center)), h("cylinder", rb, rt, h2, center, n));
+    },
     // Compound op: hashed ATOMICALLY from its own args, so it is a single cache
     // node — its internal cylinders/cut are never retained. The template for
     // future compounds: build internals with T(), return the final tracked solid.
-    boredCylinder: ({ od, h: height, bore }) => cached(h("boredCylinder", od, height, bore, segs), () => {
-      const body = T(Manifold.cylinder(height, od / 2, od / 2, segs, false));
-      const tool0 = T(Manifold.cylinder(height + 4, bore / 2, bore / 2, segs, false));
+    boredCylinder: ({ od, h: height, bore }) => cached(h("boredCylinder", od, height, bore, segsAt(od / 2), segsAt(bore / 2)), () => {
+      const body = T(Manifold.cylinder(height, od / 2, od / 2, segsAt(od / 2), false));
+      const tool0 = T(Manifold.cylinder(height + 4, bore / 2, bore / 2, segsAt(bore / 2), false));
       const tool = T(tool0.translate([0, 0, -2])); // raw ops: track each result
       return T(body.subtract(tool));
     }),
@@ -644,19 +653,20 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // spec). Reuses loftMesh's stitch/cap/winding machinery. Atomic cache
     // node hashed from its own args, like boredCylinder.
     roundedBox: ({ size, center, round }) => cached(
-      h("roundedBox", size, center, round.side, round.top, round.bottom, segs),
+      h("roundedBox", size, center, round.side, round.top, round.bottom, segsAt(Math.max(round.side, round.top, round.bottom))),
       () => {
-        const solid = T(loftMesh(wasm, roundedBoxRings(size, round, segs)));
+        // One count serves every corner and rim arc, so it is sized for the largest.
+        const solid = T(loftMesh(wasm, roundedBoxRings(size, round, segsAt(Math.max(round.side, round.top, round.bottom)))));
         return center ? T(solid.translate([0, 0, -size[2] / 2])) : solid;
       }),
-    sphere: (r) => wrap(T(Manifold.sphere(r, segs)), h("sphere", r, segs)),
+    sphere: (r) => wrap(T(Manifold.sphere(r, segsAt(r))), h("sphere", r, segsAt(r))),
     box: (min, max) => {
       const cube = T(Manifold.cube([max[0] - min[0], max[1] - min[1], max[2] - min[2]]));
       return wrap(T(cube.translate(min)), h("box", min, max));
     },
     prism: (pts, height, { twist = 0, scaleTop = 1 } = {}) =>
       cached(h("prism", pts, height, twist, scaleTop, segs), () => {
-        const cs = T(CrossSection.ofPolygons([tessellateContour(pts, segs)]));
+        const cs = T(CrossSection.ofPolygons([tessellateContour(pts, segsAt)]));
         if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
         const nDiv = Math.max(1, Math.ceil(Math.abs(twist) / 5));
         // Manifold's extrude scaleTop is a Vec2 — a scalar is NOT broadcast (it scales
@@ -711,7 +721,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
       const shape = profile && profile._shape2d ? profile : null;
       return cached(h("extrude", shape ? shape._hash : profile, height, twist, scaleTop, segs), () => {
         const cs = shape ? csFor(shape) : (() => {
-          const { outer, holes } = tessellateProfile(profile, segs);
+          const { outer, holes } = tessellateProfile(profile, segsAt);
           return T(CrossSection.ofPolygons([outer, ...holes], "EvenOdd"));
         })();
         if (twist === 0 && scaleTop === 1) return T(cs.extrude(height));
@@ -757,10 +767,26 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // opts.segs may only COARSEN below the kernel's quality (min), never exceed it:
     // callers use it where a small feature's sagitta bound needs fewer facets than
     // the per-circle quality would spend (mesh-fillet's free-standing corner arcs).
+    // Density around the axis: by default sized for the profile's outermost radius —
+    // the largest circle the revolve sweeps — through the tier's per-radius rule. An
+    // explicit `segs` is the caller's own sizing (mesh-fillet's blend tools compute
+    // theirs from a 1 µm sagitta bound and rely on getting exactly that count — the
+    // dephase and horn-containment arithmetic assume it), bounded only by the tier's
+    // cap: it may still never EXCEED kernel quality, but it is not re-bounded by the
+    // part-scale rule meant for circles nobody sized by hand.
     revolve: (pts, { degrees = 360, segs: segsOverride } = {}) => {
-      const density = Math.min(segs, segsOverride ?? segs);
-      if (pts && pts._shape2d)
-        return cached(h("revolve", pts._hash, degrees, density), () => T(csFor(pts).revolve(density, degrees)));
+      const densityFor = (maxR) => segsOverride != null ? Math.min(segs, segsOverride) : segsAt(maxR);
+      if (pts && pts._shape2d) {
+        // Keyed on the override, not the resolved density, so a cache hit never
+        // materializes the CrossSection just to measure its bounds.
+        return cached(h("revolve", pts._hash, degrees, segsOverride ?? null), () => {
+          const cs = csFor(pts);
+          const b = cs.bounds();
+          return T(cs.revolve(densityFor(Math.max(Math.abs(b.min[0]), Math.abs(b.max[0]))), degrees));
+        });
+      }
+      const maxR = Array.isArray(pts) ? pts.reduce((m, p) => Math.max(m, Math.abs(p?.[0] ?? 0)), 0) : 0;
+      const density = densityFor(maxR);
       return cached(h("revolve", pts, degrees, density), () => T(Manifold.revolve([pts], density, degrees)));
     },
     // A one-solid union is an identity — no new WASM / cache entry (avoids double-free):