partforge 0.12.0 → 0.13.0

package/docs/AUTHORING-PARTS.md

@@ -94,18 +94,29 @@ handles. The same code runs on **Manifold** (fast meshes — preview + STL + 3MF
 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 contract v2 — 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(rBottom, rTop, h, { center? })` | cylinder/cone along +Z (frustum if radii differ) |
-| `k.box(min, max)` | axis-aligned box from `[x,y,z]` min/max |
-| `k.prism(points2D, h, { 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? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls |
-| `k.sweep(profile2D, path3D, { 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)` | sphere centred at the origin |
-| `k.revolve(points2D, { degrees })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
+| `k.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? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls |
+| `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.revolve({ profile, degrees? })` | revolve a lathe profile `[[r,z],…]` (r ≥ 0) around the Z axis (full or partial) |
 | `k.helixSweptTube({ pathR, profileR, pitch, turns, z0, lefthand })` | circle swept along a helix (e.g. a rope groove) |
 | `k.union(solids[])` | boolean union |
 
@@ -116,26 +127,26 @@ number or `[sx,sy]`). Author rings CCW and ordered by ascending `z` (the `regula
 CW-wound or descending-z rings still export a valid outward solid. (Arc profiles from
 `roundedProfile` are **not** accepted as loft rings yet — a ring must be a point array;
 use `prism`/`extrude` for true-arc STEP export.) **`sweep`** takes the same CCW
-`polygon.js` outline as its `profile2D` and a plain `[[x,y,z],…]` point list as its
-`path3D`; the profile stays perpendicular to the path (a rotation-minimizing frame), with
+`polygon.js` outline as its `profile` 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({ outer: roundedRectPolygon(40, 30, 4), holes: [circleProfile(6)] }, 10);
+k.extrude({ profile: { outer: roundedRectPolygon(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
+k.loft({ rings });                      // ruled walls, capped ends
 
 // a cable/hose: sweep a circle along a 3-D polyline, with rounded bends
-k.sweep(circleProfile(3), [[0, 0, 0], [0, 0, 20], [15, 0, 20]], { cornerRadius: 5 });
+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(filletPolygon(bracketOutline, 3), 4);       // tessellated corners (faceted in STEP)
-k.prism(roundedProfile(bracketOutline, 3), 4);      // true CIRCLE corners in STEP export
+k.prism({ points: filletPolygon(bracketOutline, 3), h: 4 });   // tessellated corners (faceted in STEP)
+k.prism({ points: roundedProfile(bracketOutline, 3), h: 4 });  // true CIRCLE corners in STEP export
 ```
 
 2-D polygon helpers for `prism`/`extrude`/`loft`: `import { piePolygon, hexPolygon,
@@ -187,9 +198,9 @@ magic vectors. Three habits:
 
   ```js
   // ✗ cryptic: which axis? what centre?
-  k.cylinder(r, r, L).rotate(-90, [0, 0, 0], [1, 0, 0]).translate([rp, y1, sz])
+  k.cylinder({ r, h: L }).rotate(-90, [0, 0, 0], [1, 0, 0]).translate([rp, y1, sz])
   // ✓ legible
-  k.cylinder(r, r, L).along("+Y").at([rp, y1, sz])
+  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
@@ -226,9 +237,9 @@ a user could reasonably want to change: the base body, and each functional featu
 grooves, mounts, bores, pockets, distinct structural members.
 
 ```js
-const body = k.prism(d.outerPts, p.height, { scaleTop: p.taper }).label("Faceted wall");
+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(d.drainR, d.drainR, p.floor + 4).at([0, 0, -2]).label("Drainage hole"));
+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
@@ -430,15 +441,15 @@ Pure helpers from `partforge/geometry` (no backend dependency):
 `ringSectorPolygon(innerR,outerR,arcDeg)` (**arcDeg < 360** — a full ring is a contour-with-hole;
 cut an inner cylinder from an outer one instead).
 `circleProfile(r, center?)` — a circle of radius `r` centered at `[cx,cy]` (default origin).
-Compose it for round solids: `k.prism(circleProfile(r), h)` is a cylinder, and
-**a torus is `k.revolve(circleProfile(minorR, [majorR, 0]))`** (with `majorR > minorR`) —
+Compose it for round solids: `k.prism({ points: circleProfile(r), h })` is a cylinder, and
+**a torus is `k.revolve({ profile: circleProfile(minorR, [majorR, 0]) })`** (with `majorR > minorR`) —
 partforge has no `torus` primitive because it's just a revolved circle.
 
 **Patterns** (return `Solid[]` — feed to `k.union(...)` for features or `s.cutAll(...)` for holes):
 `linearPattern(solid, count, [dx,dy,dz])`, `circularPattern(solid, count, { center, axis, angle, rotateCopies })`.
 
 ```js
-const hole = k.cylinder(2, 2, 20).translate([20, 0, 0]);
+const hole = k.cylinder({ r: 2, h: 20 }).translate([20, 0, 0]);
 body = body.cutAll(circularPattern(hole, 8, { axis: "Z" }));   // 8 bolt holes on a 40mm circle
 ```
 
@@ -744,11 +755,11 @@ whole part to OCCT — no declaration needed:
 
 | Op | Meaning |
 |---|---|
-| `s.fillet(radius, selector?)` | round edges (curve-following, exact) |
-| `s.chamfer(distance, selector?)` | bevel edges |
-| `s.shell(thickness, openFaces)` | hollow inward, wall = `thickness`; `openFaces` selector (`{inPlane,at}`/`{dir}`/`{near}`) chooses which face(s) to open. Closed (no-open-face) hollows are not supported. |
+| `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. |
 
-`selector` chooses which edges (omit it for **all** edges):
+`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}`)
@@ -758,9 +769,9 @@ whole part to OCCT — no declaration needed:
   (parts meant to travel must use the object forms — see `KERNEL-CONTRACT.md`)
 
 ```js
-let s = k.box([0,0,0],[40,30,16]);
-s = s.fillet(3, { dir: "Z" });            // round the 4 vertical edges
-s = s.chamfer(1, { inPlane: "XY", at: 0 }); // bevel the base
+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.

package/docs/ERROR-PATTERNS.md

@@ -131,7 +131,7 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 
 - **Symptom:** `ringSectorPolygon: arcDeg must be < 360 (use a cut for a full ring)`
 - **Cause:** A full annulus can't be a single simple polygon — it's a contour-with-hole.
-- **Fix:** Cut an inner cylinder from an outer one (or `k.extrude({ outer, holes })`); use `ringSectorPolygon` only for partial arcs. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Profiles & patterns".
+- **Fix:** Cut an inner cylinder from an outer one (or `k.extrude({ profile: { outer, holes }, h })`); use `ringSectorPolygon` only for partial arcs. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Profiles & patterns".
 
 ## occt-closed-loop-unsupported
 
@@ -163,6 +163,38 @@ The framework itself rebuilds each sub-part fresh per job and applies `place` on
 - **Cause:** Only pages listed in `build.rollupOptions.input` are compiled by the production build; other root `*.html` pages are dev-only conveniences Vite serves without building.
 - **Fix:** Add the page to `build.rollupOptions.input` in `vite.config.js` if it should ship. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
 
+## options-unknown-key
+
+- **Symptom:** `unknown option` — e.g. `cylinder: unknown option "radius" — did you mean r?`
+- **Cause:** an options-form kernel call passed a key the op does not accept (typo, or long-form vocabulary like `radius`/`height`).
+- **Fix:** use the canonical keys from the op table in [AUTHORING-PARTS.md](AUTHORING-PARTS.md); the error's did-you-mean / valid-keys hint names them.
+
+## options-missing-key
+
+- **Symptom:** `is required` — e.g. `cylinder: h is required`, `sweep: path is required`.
+- **Cause:** an options-form kernel call omitted a required key.
+- **Fix:** supply the key; canonical forms are in the [AUTHORING-PARTS.md](AUTHORING-PARTS.md) op table and KERNEL-CONTRACT.md "Calling convention".
+
+## cylinder-radius-keys
+
+- **Symptom:** `cylinder: pass exactly one of r/d, or r1+r2 / d1+d2`
+- **Cause:** mixed or missing radius vocabulary — both `r` and `d`, straight + cone keys together, only one cone end, or `r1`+`d2`.
+- **Fix:** straight cylinders take one of `r`|`d` plus `h`; cones take `r1`+`r2` or `d1`+`d2` plus `h`.
+
+The sphere variant is `sphere: pass exactly one of r/d` (same cause and fix).
+
+## box-size-vs-corners
+
+- **Symptom:** `box: pass size or min+max, not both`
+- **Cause:** the two `box` forms were mixed in one call.
+- **Fix:** either `{size, center?}` (centered in X/Y, base at z=0; `center:true` centers Z too) or `{min, max}` — see [AUTHORING-PARTS.md](AUTHORING-PARTS.md).
+
+## box-center-with-corners
+
+- **Symptom:** `box: center only applies to the size form`
+- **Cause:** `center` was passed alongside `min`/`max`, but explicit corners already fix the placement.
+- **Fix:** drop `center`, or switch to `{size, center?}` — see [AUTHORING-PARTS.md](AUTHORING-PARTS.md).
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.12.0",
+  "version": "0.13.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",

package/src/framework/app.css

@@ -7,120 +7,120 @@
 * { box-sizing: border-box; }
 html, body { margin: 0; height: 100%; overflow: hidden;
   font: 13px/1.4 -apple-system, system-ui, sans-serif; }
-#app { position: fixed; inset: 0; background: var(--bg); }
+#app { position: fixed; inset: 0; background: var(--pf-bg); }
 canvas { display: block; }
 
 #panel {
   position: fixed; top: 12px; left: 12px; width: 256px;
   max-height: calc(100vh - 24px); overflow-y: auto; z-index: 10;
-  background: var(--surface); border: 1px solid var(--border); border-radius: 10px;
-  padding: 14px; color: var(--text); box-shadow: 0 6px 24px rgba(0,0,0,.35);
+  background: var(--pf-surface); border: 1px solid var(--pf-border); border-radius: 10px;
+  padding: 14px; color: var(--pf-text); box-shadow: 0 6px 24px rgba(0,0,0,.35);
 }
-#panel h1 { font-size: 14px; margin: 0 0 2px; color: var(--text-strong); letter-spacing: -0.01em; }
+#panel h1 { font-size: 14px; margin: 0 0 2px; color: var(--pf-text-strong); letter-spacing: -0.01em; }
 #panel .sub {
-  font-family: var(--mono); color: var(--muted); font-size: 10px;
+  font-family: var(--pf-mono); color: var(--pf-muted); font-size: 10px;
   letter-spacing: 0.04em; text-transform: uppercase;
-  margin: 0 0 12px; padding-bottom: 12px; border-bottom: 1px solid var(--border);
+  margin: 0 0 12px; padding-bottom: 12px; border-bottom: 1px solid var(--pf-border);
 }
 
 .seg { display: flex; gap: 4px; margin-bottom: 12px; }
 .seg button {
-  flex: 1; padding: 7px 0; border: 1px solid var(--border); border-radius: 7px;
-  background: var(--surface-2); color: var(--muted-2); cursor: pointer;
-  font-family: var(--mono); font-size: 11px; letter-spacing: 0.02em;
+  flex: 1; padding: 7px 0; border: 1px solid var(--pf-border); border-radius: 7px;
+  background: var(--pf-surface-2); color: var(--pf-muted-2); cursor: pointer;
+  font-family: var(--pf-mono); font-size: 11px; letter-spacing: 0.02em;
 }
-.seg button.on { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+.seg button.on { background: var(--pf-accent); color: var(--pf-on-accent); border-color: var(--pf-accent); }
 
 .section {
-  border: 1px solid var(--border); border-radius: 8px; padding: 10px;
-  margin-bottom: 8px; background: var(--surface-2);
+  border: 1px solid var(--pf-border); border-radius: 8px; padding: 10px;
+  margin-bottom: 8px; background: var(--pf-surface-2);
 }
 .sec-title {
-  font-family: var(--mono); font-size: 10px; font-weight: 600;
-  letter-spacing: 0.14em; text-transform: uppercase; color: var(--muted-2); margin-bottom: 9px;
+  font-family: var(--pf-mono); font-size: 10px; font-weight: 600;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--pf-muted-2); margin-bottom: 9px;
 }
 select.preset {
-  width: 100%; background: var(--input-bg); color: var(--text-2);
-  border: 1px solid var(--border); border-radius: 6px; padding: 6px 8px;
-  font-family: var(--mono); font-size: 11px;
+  width: 100%; background: var(--pf-input-bg); color: var(--pf-text-2);
+  border: 1px solid var(--pf-border); border-radius: 6px; padding: 6px 8px;
+  font-family: var(--pf-mono); font-size: 11px;
 }
 .feat { display: flex; align-items: center; gap: 8px; margin: 6px 0;
-  color: var(--text-2); cursor: pointer; }
-.feat input { cursor: pointer; accent-color: var(--accent); }
-.feat-group { margin: 2px 0 8px; padding-left: 10px; border-left: 2px solid var(--border); }
+  color: var(--pf-text-2); cursor: pointer; }
+.feat input { cursor: pointer; accent-color: var(--pf-accent); }
+.feat-group { margin: 2px 0 8px; padding-left: 10px; border-left: 2px solid var(--pf-border); }
 .feat-group.hidden { display: none; }
 .adv-toggle {
   margin-top: 8px; padding: 4px 0; width: 100%; border: 0; border-radius: 5px;
-  background: transparent; color: var(--muted); cursor: pointer;
-  font-family: var(--mono); font-size: 10px; letter-spacing: 0.08em; text-transform: uppercase; text-align: left;
+  background: transparent; color: var(--pf-muted); cursor: pointer;
+  font-family: var(--pf-mono); font-size: 10px; letter-spacing: 0.08em; text-transform: uppercase; text-align: left;
 }
-.adv-toggle:hover { color: var(--muted-2); }
+.adv-toggle:hover { color: var(--pf-muted-2); }
 .adv.hidden { display: none; }
 .adv { margin-top: 4px; }
 
 .slider { margin: 9px 0; }
 .row { display: flex; justify-content: space-between; align-items: center;
   margin: 0 0 4px; gap: 8px; }
-.row label { font-family: var(--mono); font-size: 11px; color: var(--muted-2); letter-spacing: 0.01em; }
+.row label { font-family: var(--pf-mono); font-size: 11px; color: var(--pf-muted-2); letter-spacing: 0.01em; }
 .row .val { display: flex; align-items: baseline; gap: 4px; flex: none; }
 .row .num {
-  width: 54px; text-align: right; font-family: var(--mono); font-size: 12px; font-variant-numeric: tabular-nums;
-  background: var(--input-bg); color: var(--text-strong);
-  border: 1px solid var(--border); border-radius: 5px; padding: 3px 6px;
+  width: 54px; text-align: right; font-family: var(--pf-mono); font-size: 12px; font-variant-numeric: tabular-nums;
+  background: var(--pf-input-bg); color: var(--pf-text-strong);
+  border: 1px solid var(--pf-border); border-radius: 5px; padding: 3px 6px;
 }
-.row .num:focus { outline: none; border-color: var(--accent); box-shadow: 0 0 0 3px var(--accent-soft); }
+.row .num:focus { outline: none; border-color: var(--pf-accent); box-shadow: 0 0 0 3px var(--pf-accent-soft); }
 .row .num::-webkit-outer-spin-button, .row .num::-webkit-inner-spin-button { -webkit-appearance: none; margin: 0; }
 .row .num { -moz-appearance: textfield; }
-.row .unit { font-family: var(--mono); color: var(--muted); font-size: 10px; }
+.row .unit { font-family: var(--pf-mono); color: var(--pf-muted); font-size: 10px; }
 
 /* crafted range slider — hairline track + CAD-blue handle (the panel's signature control) */
 input[type="range"] { -webkit-appearance: none; appearance: none; width: 100%; height: 18px; margin: 0; background: transparent; cursor: pointer; }
-input[type="range"]::-webkit-slider-runnable-track { height: 3px; border-radius: 2px; background: var(--border); }
-input[type="range"]::-moz-range-track { height: 3px; border-radius: 2px; background: var(--border); }
-input[type="range"]::-moz-range-progress { height: 3px; border-radius: 2px; background: var(--accent); }
+input[type="range"]::-webkit-slider-runnable-track { height: 3px; border-radius: 2px; background: var(--pf-border); }
+input[type="range"]::-moz-range-track { height: 3px; border-radius: 2px; background: var(--pf-border); }
+input[type="range"]::-moz-range-progress { height: 3px; border-radius: 2px; background: var(--pf-accent); }
 input[type="range"]::-webkit-slider-thumb {
   -webkit-appearance: none; appearance: none; width: 14px; height: 14px; margin-top: -5.5px;
-  border-radius: 50%; background: var(--accent); border: 2px solid var(--surface-2); box-shadow: 0 0 0 1px var(--accent);
+  border-radius: 50%; background: var(--pf-accent); border: 2px solid var(--pf-surface-2); box-shadow: 0 0 0 1px var(--pf-accent);
   transition: box-shadow .12s ease;
 }
 input[type="range"]::-moz-range-thumb {
-  width: 14px; height: 14px; border-radius: 50%; background: var(--accent);
-  border: 2px solid var(--surface-2); box-shadow: 0 0 0 1px var(--accent);
+  width: 14px; height: 14px; border-radius: 50%; background: var(--pf-accent);
+  border: 2px solid var(--pf-surface-2); box-shadow: 0 0 0 1px var(--pf-accent);
 }
-input[type="range"]:hover::-webkit-slider-thumb { box-shadow: 0 0 0 5px var(--accent-soft); }
+input[type="range"]:hover::-webkit-slider-thumb { box-shadow: 0 0 0 5px var(--pf-accent-soft); }
 input[type="range"]:focus-visible { outline: none; }
-input[type="range"]:focus-visible::-webkit-slider-thumb { box-shadow: 0 0 0 5px var(--accent-soft); }
-input[type="range"]:focus-visible::-moz-range-thumb { box-shadow: 0 0 0 5px var(--accent-soft); }
+input[type="range"]:focus-visible::-webkit-slider-thumb { box-shadow: 0 0 0 5px var(--pf-accent-soft); }
+input[type="range"]:focus-visible::-moz-range-thumb { box-shadow: 0 0 0 5px var(--pf-accent-soft); }
 
 button.action {
   width: 100%; margin-top: 8px; padding: 9px; border: 0; border-radius: 7px;
-  background: var(--accent); color: var(--on-accent); font-weight: 600; cursor: pointer;
+  background: var(--pf-accent); color: var(--pf-on-accent); font-weight: 600; cursor: pointer;
 }
-button.ghost { background: var(--border); color: var(--text-2); font-weight: 500; }
+button.ghost { background: var(--pf-border); color: var(--pf-text-2); font-weight: 500; }
 button.action:disabled { opacity: .5; cursor: default; }
 
 .dl { margin-top: 14px; }
 .dl-head {
-  font-family: var(--mono); font-size: 10px; font-weight: 600;
-  letter-spacing: 0.14em; text-transform: uppercase; color: var(--muted-2); margin-bottom: 7px;
+  font-family: var(--pf-mono); font-size: 10px; font-weight: 600;
+  letter-spacing: 0.14em; text-transform: uppercase; color: var(--pf-muted-2); margin-bottom: 7px;
 }
 .dl-row { display: flex; gap: 6px; }
 .dl-row button {
-  flex: 1; padding: 8px 0; border: 1px solid var(--border); border-radius: 7px;
-  background: var(--surface-2); color: var(--text-2);
-  font-family: var(--mono); font-weight: 600; font-size: 11px; letter-spacing: 0.06em; cursor: pointer;
+  flex: 1; padding: 8px 0; border: 1px solid var(--pf-border); border-radius: 7px;
+  background: var(--pf-surface-2); color: var(--pf-text-2);
+  font-family: var(--pf-mono); font-weight: 600; font-size: 11px; letter-spacing: 0.06em; cursor: pointer;
 }
-.dl-row button:hover:not(:disabled) { border-color: var(--accent); color: var(--text-strong); }
+.dl-row button:hover:not(:disabled) { border-color: var(--pf-accent); color: var(--pf-text-strong); }
 .dl-row button:disabled { opacity: .45; cursor: default; }
-#status { font-family: var(--mono); margin-top: 12px; min-height: 16px; color: var(--status);
+#status { font-family: var(--pf-mono); margin-top: 12px; min-height: 16px; color: var(--pf-status);
   font-size: 11px; font-variant-numeric: tabular-nums; }
-#status.err { color: var(--err); }
-.hint { font-family: var(--mono); margin-top: 8px; color: var(--hint); font-size: 10px; letter-spacing: 0.02em; }
+#status.err { color: var(--pf-err); }
+.hint { font-family: var(--pf-mono); margin-top: 8px; color: var(--pf-hint); font-size: 10px; letter-spacing: 0.02em; }
 
 /* keyboard focus ring shared across the panel's interactive controls */
 .seg button:focus-visible, select.preset:focus-visible, .dl-row button:focus-visible,
 button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-visible {
-  outline: 2px solid var(--accent); outline-offset: 2px;
+  outline: 2px solid var(--pf-accent); outline-offset: 2px;
 }
 
 /* part tabs, floated top-centre over the viewport */
@@ -129,7 +129,7 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   z-index: 15;
 }
 #topbar .seg {
-  margin: 0; padding: 4px; background: var(--surface); border: 1px solid var(--border);
+  margin: 0; padding: 4px; background: var(--pf-surface); border: 1px solid var(--pf-border);
   border-radius: 9px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
 }
 #topbar .seg button { min-width: 70px; padding: 7px 10px; }
@@ -138,17 +138,17 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #viewbar {
   position: fixed; top: 12px; right: 12px; z-index: 15;
   display: flex; gap: 4px; padding: 4px;
-  background: var(--surface); border: 1px solid var(--border);
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
   border-radius: 9px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
 }
 #viewbar button {
-  width: 34px; height: 34px; border: 1px solid var(--border); border-radius: 7px;
-  background: var(--surface-2); color: var(--muted-2); cursor: pointer;
+  width: 34px; height: 34px; border: 1px solid var(--pf-border); border-radius: 7px;
+  background: var(--pf-surface-2); color: var(--pf-muted-2); cursor: pointer;
   font-size: 15px; line-height: 1;
   display: flex; align-items: center; justify-content: center;
 }
-#viewbar button:hover { color: var(--text); }
-#viewbar button.on { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+#viewbar button:hover { color: var(--pf-text); }
+#viewbar button.on { background: var(--pf-accent); color: var(--pf-on-accent); border-color: var(--pf-accent); }
 
 #busy {
   position: fixed; inset: 0; z-index: 20; pointer-events: none;
@@ -158,30 +158,30 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #busy.show { display: flex; }
 #busy .ring {
   width: 46px; height: 46px; border-radius: 50%;
-  border: 4px solid var(--border); border-top-color: var(--accent);
+  border: 4px solid var(--pf-border); border-top-color: var(--pf-accent);
   animation: spin 0.9s linear infinite;
 }
-#busy .phase { color: var(--text); font-size: 13px; text-shadow: 0 1px 6px rgba(0,0,0,.6); }
+#busy .phase { color: var(--pf-text); font-size: 13px; text-shadow: 0 1px 6px rgba(0,0,0,.6); }
 @keyframes spin { to { transform: rotate(360deg); } }
 
 /* info glyph + description popover */
 .info {
   appearance: none; border: none; background: none; cursor: pointer;
-  color: var(--muted); font-size: 12px; line-height: 1; padding: 0 0 0 5px;
+  color: var(--pf-muted); font-size: 12px; line-height: 1; padding: 0 0 0 5px;
   vertical-align: middle;
 }
-.info:hover { color: var(--text-2); }
-.info:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 3px; }
+.info:hover { color: var(--pf-text-2); }
+.info:focus-visible { outline: 2px solid var(--pf-accent); outline-offset: 2px; border-radius: 3px; }
 .popover {
   position: fixed; z-index: 50; max-width: 280px; max-height: 50vh; overflow: auto;
-  background: var(--surface); color: var(--text); border: 1px solid var(--border);
+  background: var(--pf-surface); color: var(--pf-text); border: 1px solid var(--pf-border);
   border-radius: 8px; padding: 10px 12px; box-shadow: 0 6px 24px rgba(0,0,0,.35);
   font-size: 12px; line-height: 1.5;
 }
 .popover[hidden] { display: none; }
 .popover img { max-width: 100%; height: auto; border-radius: 4px; }
-.popover code { font-family: var(--mono); background: var(--surface-2); padding: 0.05em 0.35em; border-radius: 4px; font-size: 0.9em; }
-.popover a { color: var(--accent); }
+.popover code { font-family: var(--pf-mono); background: var(--pf-surface-2); padding: 0.05em 0.35em; border-radius: 4px; font-size: 0.9em; }
+.popover a { color: var(--pf-accent); }
 .popover p:first-child { margin-top: 0; }
 .popover p:last-child { margin-bottom: 0; }
 
@@ -194,12 +194,12 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #pf-hover-tip {
   position: fixed; z-index: 30; pointer-events: none; display: none;
   padding: 4px 9px; border-radius: 6px; max-width: 260px;
-  background: var(--surface); border: 1px solid var(--border);
-  color: var(--text-strong); font-size: 12px; line-height: 1.35;
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  color: var(--pf-text-strong); font-size: 12px; line-height: 1.35;
   box-shadow: 0 2px 10px rgba(0, 0, 0, .25);
 }
 #pf-hover-tip.show { display: block; }
-#pf-hover-tip .pf-hover-sub { color: var(--muted); font-size: 11px; margin-left: 7px; }
+#pf-hover-tip .pf-hover-sub { color: var(--pf-muted); font-size: 11px; margin-left: 7px; }
 #pf-hover-tip .pf-hover-sub:empty { display: none; }
 
 /* request-a-pick: agent prompt banner, floated top-centre well below the part tabs,
@@ -208,8 +208,8 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   position: fixed; top: 78px; left: 50%; transform: translateX(-50%);
   z-index: 30; max-width: min(56ch, calc(100vw - 24px));
   padding: 10px 36px 10px 12px;
-  background: var(--surface); color: var(--text);
-  border: 1px solid var(--border); border-radius: 10px;
+  background: var(--pf-surface); color: var(--pf-text);
+  border: 1px solid var(--pf-border); border-radius: 10px;
   box-shadow: 0 6px 24px rgba(0,0,0,.35);
   font-size: 12px; line-height: 1.45;
   animation: pf-pick-in .18s ease;
@@ -218,20 +218,20 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
 #pf-pick-banner .pf-pick-avatar {
   flex: none; width: 30px; height: 30px; border-radius: 50%; font-size: 17px;
   display: flex; align-items: center; justify-content: center;
-  background: var(--surface-2); border: 1px solid var(--border);
+  background: var(--pf-surface-2); border: 1px solid var(--pf-border);
 }
 #pf-pick-banner .pf-pick-msg { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
-#pf-pick-banner .pf-pick-label { color: var(--muted); font-size: 11px; }
-#pf-pick-banner .pf-pick-prompt { color: var(--text-strong); font-weight: 600; }
+#pf-pick-banner .pf-pick-label { color: var(--pf-muted); font-size: 11px; }
+#pf-pick-banner .pf-pick-prompt { color: var(--pf-text-strong); font-weight: 600; }
 #pf-pick-close {
   position: absolute; top: 6px; right: 6px; appearance: none;
   width: 20px; height: 20px; padding: 0;
-  border: 1px solid var(--border); border-radius: 6px;
-  background: var(--surface-2); color: var(--muted);
+  border: 1px solid var(--pf-border); border-radius: 6px;
+  background: var(--pf-surface-2); color: var(--pf-muted);
   cursor: pointer; font-size: 13px; line-height: 1;
   display: flex; align-items: center; justify-content: center;
 }
-#pf-pick-close:hover { color: var(--text-strong); border-color: var(--accent); }
+#pf-pick-close:hover { color: var(--pf-text-strong); border-color: var(--pf-accent); }
 @keyframes pf-pick-in {
   from { opacity: 0; transform: translateX(-50%) translateY(-10px); }
   to   { opacity: 1; transform: translateX(-50%) translateY(0); }

package/src/framework/geometry/kernel-front.js

@@ -1,36 +1,35 @@
 // The backend-shared kernel front. Each backend builds its primitive mapping and
 // returns finishKernel(kernel), which layers on everything that is NOT
 // backend-specific:
-//   - argument validation (previously copy-pasted into both backends);
+//   - the options-object calling convention (op-options.js): one wrapper per
+//     factory op normalizes an options-form call to positional args, then runs
+//     the op's semantic check on the normalized args (both calling forms), then
+//     calls the raw backend op — so backends stay positional and the solid
+//     cache hashes normalized args;
 //   - default compound-op compositions — a backend only overrides one when it has
 //     a reason to (Manifold's boredCylinder hashes atomically for its solid cache);
 //   - a KernelCapabilityError stub for toSTEP when the backend can't write B-rep.
 // The per-Solid twin of this layer is addSugar() in solid-sugar.js.
 import { KernelCapabilityError } from "./errors.js";
+import { isPlainOptions, KERNEL_OP_SPECS } from "./op-options.js";
 
 export function finishKernel(k) {
-  const rawPrism = k.prism;
-  k.prism = (pts, h, opts) => {
-    if ((opts?.scaleTop ?? 1) < 0) throw new Error("prism: scaleTop must be ≥ 0");
-    return rawPrism(pts, h, opts);
-  };
-
-  const rawExtrude = k.extrude;
-  k.extrude = (profile, h, opts) => {
-    if ((opts?.scaleTop ?? 1) < 0) throw new Error("extrude: scaleTop must be ≥ 0");
-    return rawExtrude(profile, h, opts);
-  };
-
-  const rawRevolve = k.revolve;
-  k.revolve = (pts, opts) => {
-    for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
-    return rawRevolve(pts, opts);
-  };
-
-  // Compound: bored-through cylinder (tool overshoots 2 mm each end for a clean cut).
+  // Compound default: bored-through cylinder (tool overshoots 2 mm each end for
+  // a clean cut). Assigned BEFORE the wrap loop so the fallback composition gets
+  // the same key validation as a backend-native override.
   k.boredCylinder ??= ({ od, h, bore }) =>
     k.cylinder(od / 2, od / 2, h).cut(k.cylinder(bore / 2, bore / 2, h + 4).translate([0, 0, -2]));
 
+  for (const [op, { toArgs, check }] of Object.entries(KERNEL_OP_SPECS)) {
+    const raw = k[op];
+    if (!raw) continue;
+    k[op] = (...a) => {
+      const pos = a.length === 1 && isPlainOptions(a[0]) ? toArgs(a[0]) : a;
+      check?.(...pos);
+      return raw(...pos);
+    };
+  }
+
   k.toSTEP ??= () => { throw new KernelCapabilityError("toSTEP requires the OCCT backend"); };
 
   return k;

package/src/framework/geometry/kernel.js

@@ -2,10 +2,14 @@
 // parity tests (test/kernel-contract.test.js and the OCCT twin in
 // test/occt-backend.test.js) assert each backend exposes exactly these ops, so the
 // contract can't silently drift from the implementations — the drift class that
-// once broke the probe kernel (see probe.js). The @typedefs document signatures.
-// The prose half of the contract — conventions, value semantics, conformance
-// classes, versioning policy — is docs/KERNEL-CONTRACT.md; change either side and
-// you must update the other. (2-D polygon helpers live in ./polygon.js.)
+// once broke the probe kernel (see probe.js). The @typedefs document signatures,
+// options-object form first (the canonical calling convention — normalizers and
+// exact valid-key lists live in op-options.js, wired in at kernel-front.js
+// (finishKernel) and solid-sugar.js (addSugar); legacy positional forms stay
+// silently accepted until contract v2). The prose half of the contract —
+// conventions, value semantics, conformance classes, versioning policy — is
+// docs/KERNEL-CONTRACT.md; change either side and you must update the other.
+// (2-D polygon helpers live in ./polygon.js.)
 
 // The prose half's version: docs/KERNEL-CONTRACT.md's "Contract version" header
 // must match this number (asserted in kernel-contract.test.js). Bump only on a
@@ -65,22 +69,22 @@ export const OCCT_ONLY_OPS = ["fillet", "chamfer", "shell"];
  *           `edges` = feature-edge line segments (Manifold); quality is advisory — the Manifold kernel bakes it at creation
  * @property {(opts?: {quality?: "preview"|"print"}) => Promise<ArrayBuffer>} toSTL
  * @property {() => {positions:Float32Array, indices:Uint32Array}} toIndexedMesh   indexed mesh, for 3MF
- * @property {(radius:number, selector?:object) => Solid} fillet    round edges (OCCT only; Manifold throws KernelCapabilityError)
- * @property {(distance:number, selector?:object) => Solid} chamfer  bevel edges (OCCT only; Manifold throws KernelCapabilityError)
- * @property {(thickness:number, openFaces:object) => Solid} shell   hollow inward (OCCT only); openFaces selector required
+ * @property {(r:number|{r:number,edges?:object}) => Solid} fillet    round edges (OCCT only); fillet(3) or fillet({r,edges}); legacy (r,selector) accepted until v2
+ * @property {(d:number|{d:number,edges?:object}) => Solid} chamfer  bevel edges (OCCT only); chamfer(1) or chamfer({d,edges}); legacy (d,selector) accepted until v2
+ * @property {(o:{t:number,open:object}) => Solid} shell   hollow inward (OCCT only); legacy (thickness,openFaces) accepted until v2
  * @property {() => number} [genus]     through-hole count (Manifold only)
  * @property {() => boolean} [isEmpty]  no geometry at all (Manifold only)
  *
  * @typedef {Object} GeometryKernel
- * @property {(rBottom:number, rTop:number, h:number, opts?:{center?:boolean}) => Solid} cylinder
+ * @property {(o:{r?:number,d?:number,r1?:number,r2?:number,d1?:number,d2?:number,h:number,center?:boolean}) => Solid} cylinder   canonical: {r|d,h} straight, {r1,r2,h}|{d1,d2,h} cone; legacy (rBottom,rTop,h,opts) accepted until contract v2
  * @property {(o:{od:number,h:number,bore:number}) => Solid} boredCylinder   compound: bored-through cylinder (one cache node)
- * @property {(r:number) => Solid} sphere   sphere centred at the origin
- * @property {(min:number[], max:number[]) => Solid} box
- * @property {(points2D:number[][], h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0 (optional twist° + uniform top taper)
- * @property {(profile:number[][]|{outer:number[][],holes?:number[][][]}, h:number, opts?:{twist?:number,scaleTop?:number}) => Solid} extrude   extrude a polygon-with-holes region from z=0 in one op (bare array = outer only)
- * @property {(rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[], opts?:{ruled?:boolean,closed?:boolean}) => Solid} loft   stack polygon cross-sections (per-ring z/rotate/scale), ruled walls, capped ends
- * @property {(profile2D:number[][], path3D:number[][], opts?:{closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a fixed 2-D profile along a 3-D polyline path (sharp mitered corners or cornerRadius fillets; capped ends; closed:true loops and smooth:true native B-rep are backend-specific)
- * @property {(points2D:number[][], opts?:{degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z
+ * @property {(o:{r?:number,d?:number}) => Solid} sphere   sphere centred at the origin; {r|d}; bare sphere(r) stays valid
+ * @property {(o:{size?:number[],center?:boolean,min?:number[],max?:number[]}) => Solid} box   {size} = centered X/Y, base z=0 ({center:true} centers Z too) or {min,max}; legacy (min,max) accepted until v2
+ * @property {(o:{points:number[][],h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted until v2
+ * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number}) => Solid} extrude   polygon-with-holes region from z=0; legacy (profile,h,opts) accepted until v2
+ * @property {(o:{rings:{polygon?:number[][],sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean}) => Solid} loft   stack polygon cross-sections; legacy (rings,opts) accepted until v2
+ * @property {(o:{profile:number[][],path:number[][],closed?:boolean,cornerRadius?:number,ruled?:boolean,smooth?:boolean}) => Solid} sweep   sweep a 2-D profile along a 3-D polyline; legacy (profile,path,opts) accepted until v2
+ * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted until v2
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(solids:Solid[]) => Solid} union
  * @property {(named:{name:string,solid:Solid}[]) => Promise<ArrayBuffer>} toSTEP   OCCT only (Manifold throws KernelCapabilityError)

package/src/framework/geometry/op-options.js

@@ -0,0 +1,167 @@
+// src/framework/geometry/op-options.js
+// The options-object calling convention: pure normalizers turning each op's
+// canonical options form into the backend's positional argument list, plus the
+// detection predicate. Normative rule (KERNEL-CONTRACT.md "Calling convention"):
+// a call is options form when the op receives exactly one plain-object argument.
+// kernel-front.js and solid-sugar.js apply these at the backend-shared seams, so
+// backends stay positional and the Manifold solid cache hashes normalized args —
+// both spellings of a call share one cache entry. Geometry-free by design.
+
+export function isPlainOptions(x) {
+  if (x === null || typeof x !== "object") return false;
+  const proto = Object.getPrototypeOf(x);
+  return proto === Object.prototype || proto === null;
+}
+
+// Small capped Levenshtein for did-you-mean hints (distance > 2 reads as "no").
+function editDistance(a, b) {
+  if (Math.abs(a.length - b.length) > 2) return 3;
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i]);
+  for (let j = 1; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++)
+    for (let j = 1; j <= b.length; j++)
+      dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return dp[a.length][b.length];
+}
+
+// Prefix match first so long-form names hit their short key (radius→r,
+// height→h, diameter→d), then edit distance ≤ 2 for plain typos. A digit
+// suffix is peeled and re-attached so radius1 hints r1, not r.
+function suggest(key, valid) {
+  const lk = key.toLowerCase();
+  const m = /^([a-z]+)(\d+)$/.exec(lk);
+  if (m) for (const v of valid) if (m[1].startsWith(v.toLowerCase()) && valid.includes(v + m[2])) return v + m[2];
+  for (const v of valid) if (lk.startsWith(v.toLowerCase())) return v;
+  for (const v of valid) if (editDistance(lk, v.toLowerCase()) <= 2) return v;
+  return null;
+}
+
+function checkKeys(op, o, valid) {
+  for (const key of Object.keys(o)) {
+    if (valid.includes(key)) continue;
+    const hint = suggest(key, valid);
+    throw new Error(`${op}: unknown option ${JSON.stringify(key)}${
+      hint ? ` — did you mean ${hint}?` : ` (valid: ${valid.join(", ")})`}`);
+  }
+}
+
+function req(op, o, key) {
+  if (o[key] === undefined) throw new Error(`${op}: ${key} is required`);
+  return o[key];
+}
+
+// Trailing positional opts object, only if any of `keys` is present — an empty
+// options tail must normalize to *no* argument so it hashes identically to the
+// bare positional call.
+function tail(o, keys) {
+  const t = {};
+  let any = false;
+  for (const key of keys) if (o[key] !== undefined) { t[key] = o[key]; any = true; }
+  return any ? [t] : [];
+}
+
+export function cylinderArgs(o) {
+  checkKeys("cylinder", o, ["r", "d", "r1", "r2", "d1", "d2", "h", "center"]);
+  const has = (key) => o[key] !== undefined;
+  const straight = has("r") + has("d");
+  const coneR = has("r1") + has("r2");
+  const coneD = has("d1") + has("d2");
+  let rBottom, rTop;
+  if (straight === 1 && coneR + coneD === 0) rBottom = rTop = has("r") ? o.r : o.d / 2;
+  else if (straight === 0 && coneR === 2 && coneD === 0) { rBottom = o.r1; rTop = o.r2; }
+  else if (straight === 0 && coneR === 0 && coneD === 2) { rBottom = o.d1 / 2; rTop = o.d2 / 2; }
+  else throw new Error("cylinder: pass exactly one of r/d, or r1+r2 / d1+d2");
+  return [rBottom, rTop, req("cylinder", o, "h"), ...tail(o, ["center"])];
+}
+
+export function sphereArgs(o) {
+  checkKeys("sphere", o, ["r", "d"]);
+  const hasR = o.r !== undefined;
+  if (hasR === (o.d !== undefined)) throw new Error("sphere: pass exactly one of r/d");
+  return [hasR ? o.r : o.d / 2];
+}
+
+export function boxArgs(o) {
+  checkKeys("box", o, ["size", "center", "min", "max"]);
+  if (o.min !== undefined || o.max !== undefined) {
+    if (o.size !== undefined) throw new Error("box: pass size or min+max, not both");
+    if (o.center !== undefined) throw new Error("box: center only applies to the size form");
+    return [req("box", o, "min"), req("box", o, "max")];
+  }
+  const [x, y, z] = req("box", o, "size");
+  return o.center === true
+    ? [[-x / 2, -y / 2, -z / 2], [x / 2, y / 2, z / 2]]   // centered on all axes
+    : [[-x / 2, -y / 2, 0], [x / 2, y / 2, z]];           // canonical: centered X/Y, base at z=0
+}
+
+export function prismArgs(o) {
+  checkKeys("prism", o, ["points", "h", "twist", "scaleTop"]);
+  return [req("prism", o, "points"), req("prism", o, "h"), ...tail(o, ["twist", "scaleTop"])];
+}
+
+export function extrudeArgs(o) {
+  checkKeys("extrude", o, ["profile", "h", "twist", "scaleTop"]);
+  return [req("extrude", o, "profile"), req("extrude", o, "h"), ...tail(o, ["twist", "scaleTop"])];
+}
+
+export function revolveArgs(o) {
+  checkKeys("revolve", o, ["profile", "degrees"]);
+  return [req("revolve", o, "profile"), ...tail(o, ["degrees"])];
+}
+
+export function loftArgs(o) {
+  checkKeys("loft", o, ["rings", "ruled", "closed"]);
+  return [req("loft", o, "rings"), ...tail(o, ["ruled", "closed"])];
+}
+
+export function sweepArgs(o) {
+  checkKeys("sweep", o, ["profile", "path", "closed", "cornerRadius", "ruled", "smooth"]);
+  return [req("sweep", o, "profile"), req("sweep", o, "path"),
+    ...tail(o, ["closed", "cornerRadius", "ruled", "smooth"])];
+}
+
+// Per-op semantic validations, applied to the NORMALIZED positional args so
+// they cover both calling forms (these moved here from kernel-front.js).
+const checkScaleTop = (op) => (_profile, _h, opts) => {
+  if ((opts?.scaleTop ?? 1) < 0) throw new Error(`${op}: scaleTop must be ≥ 0`);
+};
+
+// Ops that were always options-only have no positional form to normalize —
+// toArgs validates keys/required and passes the object through unchanged, so a
+// typo'd key fails loudly instead of destructuring to undefined → NaN geometry.
+const passThrough = (op, valid, required) => (o) => {
+  checkKeys(op, o, valid);
+  for (const key of required) req(op, o, key);
+  return [o];
+};
+
+// Kernel factory ops under the options convention. finishKernel() wraps each:
+// normalize (if options form) → check → raw backend op.
+export const KERNEL_OP_SPECS = {
+  cylinder: { toArgs: cylinderArgs },
+  sphere:   { toArgs: sphereArgs },
+  box:      { toArgs: boxArgs },
+  prism:    { toArgs: prismArgs, check: checkScaleTop("prism") },
+  extrude:  { toArgs: extrudeArgs, check: checkScaleTop("extrude") },
+  revolve:  { toArgs: revolveArgs, check: (pts) => {
+    for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
+  } },
+  loft:     { toArgs: loftArgs },
+  sweep:    { toArgs: sweepArgs },
+  boredCylinder:  { toArgs: passThrough("boredCylinder", ["od", "h", "bore"], ["od", "h", "bore"]) },
+  helixSweptTube: { toArgs: passThrough("helixSweptTube",
+    ["pathR", "profileR", "pitch", "turns", "z0", "lefthand"], ["pathR", "profileR", "pitch", "turns"]) },
+};
+
+// Solid ops under the options convention; addSugar() wraps these when the
+// backend provides them natively (OCCT). The Manifold KernelCapabilityError
+// stubs ignore arguments, so options-form calls still throw the routing error.
+export const SOLID_OP_SPECS = {
+  fillet:  { toArgs: (o) => { checkKeys("fillet", o, ["r", "edges"]);
+    return [req("fillet", o, "r"), ...(o.edges !== undefined ? [o.edges] : [])]; } },
+  chamfer: { toArgs: (o) => { checkKeys("chamfer", o, ["d", "edges"]);
+    return [req("chamfer", o, "d"), ...(o.edges !== undefined ? [o.edges] : [])]; } },
+  shell:   { toArgs: (o) => { checkKeys("shell", o, ["t", "open"]);
+    return [req("shell", o, "t"), req("shell", o, "open")]; } },
+};

package/src/framework/geometry/solid-sugar.js

@@ -6,10 +6,13 @@
 //     sugar is geometry-identical on Manifold and OCCT alike;
 //   - validates arguments the backends would otherwise each check (scale factor);
 //   - derives boundingBox center/size from the backend's raw {min,max};
+//   - normalizes the options-object calling convention for fillet/chamfer/shell
+//     when the backend provides them natively (OCCT);
 //   - stubs any OCCT-only op the backend lacks with a KernelCapabilityError, so
 //     the needs-occt reroute works without hand-written per-backend stubs.
 import { KernelCapabilityError } from "./errors.js";
 import { OCCT_ONLY_OPS } from "./kernel.js";
+import { isPlainOptions, SOLID_OP_SPECS } from "./op-options.js";
 
 const ORIGIN = [0, 0, 0];
 const AXIS = { X: [1, 0, 0], Y: [0, 1, 0], Z: [0, 0, 1] };
@@ -54,6 +57,14 @@ export function addSugar(s) {
     };
   };
 
+  // Options-object calling convention for the multi-param B-rep ops. Wrap only
+  // when the backend provides the op natively (OCCT); the Manifold stubs below
+  // ignore their arguments, so options-form calls still throw the routing error.
+  for (const [op, { toArgs }] of Object.entries(SOLID_OP_SPECS)) {
+    const raw = s[op];
+    if (raw) s[op] = (...a) => raw(...(a.length === 1 && isPlainOptions(a[0]) ? toArgs(a[0]) : a));
+  }
+
   for (const op of OCCT_ONLY_OPS) {
     s[op] ??= () => { throw new KernelCapabilityError(`${op} requires the OCCT backend`); };
   }

package/src/framework/selection/pick.js

@@ -5,11 +5,40 @@ import { resolveSelection } from "./resolve.js";
 
 export { worldToSubPartLocal };
 
+const DRAG_THRESHOLD_SQUARED = 4 ** 2;
+
 export function attachPicker(viewer, { part, getContext, onPick }) {
   let active = false;
+  const pointerStarts = new Map();
+  let dragged = false;
+
+  function onPointerDown(ev) {
+    if (pointerStarts.size === 0) dragged = false;
+    pointerStarts.set(ev.pointerId, { x: ev.clientX, y: ev.clientY });
+  }
+
+  function onPointerMove(ev) {
+    const pointerStart = pointerStarts.get(ev.pointerId);
+    if (!pointerStart || dragged) return;
+    const dx = ev.clientX - pointerStart.x;
+    const dy = ev.clientY - pointerStart.y;
+    dragged = dx * dx + dy * dy > DRAG_THRESHOLD_SQUARED;
+  }
+
+  function onPointerUp(ev) {
+    pointerStarts.delete(ev.pointerId);
+  }
+
+  function onPointerCancel(ev) {
+    pointerStarts.delete(ev.pointerId);
+    if (pointerStarts.size === 0) dragged = false;
+  }
 
   function onClick(ev) {
-    if (!active) return;
+    const wasDragged = dragged;
+    pointerStarts.clear();
+    dragged = false;
+    if (!active || wasDragged) return;
     const hit = raycastViewer(viewer, ev.clientX, ev.clientY);
     if (!hit) return;
     const selection = resolveSelection(part, getContext(), hit);
@@ -17,9 +46,19 @@ export function attachPicker(viewer, { part, getContext, onPick }) {
     onPick(selection);
   }
 
+  viewer.domElement.addEventListener("pointerdown", onPointerDown);
+  viewer.domElement.addEventListener("pointermove", onPointerMove);
+  viewer.domElement.addEventListener("pointerup", onPointerUp);
+  viewer.domElement.addEventListener("pointercancel", onPointerCancel);
   viewer.domElement.addEventListener("click", onClick);
   return {
     setActive: (on) => { active = !!on; },
-    detach: () => viewer.domElement.removeEventListener("click", onClick),
+    detach: () => {
+      viewer.domElement.removeEventListener("pointerdown", onPointerDown);
+      viewer.domElement.removeEventListener("pointermove", onPointerMove);
+      viewer.domElement.removeEventListener("pointerup", onPointerUp);
+      viewer.domElement.removeEventListener("pointercancel", onPointerCancel);
+      viewer.domElement.removeEventListener("click", onClick);
+    },
   };
 }

package/src/framework/tokens.css

@@ -3,16 +3,16 @@
    consumers (e.g. partforge-cloud's app chrome) to share one source of truth. */
 :root {
   color-scheme: dark;
-  --bg: #15181d; --surface: #1f242c; --surface-2: #20262e; --border: #2c333d;
-  --text: #d6dbe2; --text-strong: #e7ebf1; --text-2: #cdd4dd;
-  --muted: #7d8794; --muted-2: #aab2bd; --status: #8b94a0; --hint: #6b7480;
-  --accent: #3f7bf0; --accent-soft: #26314a; --on-accent: #fff; --input-bg: #161a20; --err: #f8746c;
-  --mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+  --pf-bg: #15181d; --pf-surface: #1f242c; --pf-surface-2: #20262e; --pf-border: #2c333d;
+  --pf-text: #d6dbe2; --pf-text-strong: #e7ebf1; --pf-text-2: #cdd4dd;
+  --pf-muted: #7d8794; --pf-muted-2: #aab2bd; --pf-status: #8b94a0; --pf-hint: #6b7480;
+  --pf-accent: #3f7bf0; --pf-accent-soft: #26314a; --pf-on-accent: #fff; --pf-input-bg: #161a20; --pf-err: #f8746c;
+  --pf-mono: ui-monospace, "SF Mono", SFMono-Regular, "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
 }
 :root[data-theme="light"] {
   color-scheme: light;
-  --bg: #eef1f5; --surface: #ffffff; --surface-2: #f4f6f9; --border: #d4dae2;
-  --text: #2b333d; --text-strong: #1a2129; --text-2: #3a434e;
-  --muted: #6b7480; --muted-2: #59636f; --status: #6b7480; --hint: #8a93a0;
-  --accent: #1f5bd6; --accent-soft: #e6edfc; --on-accent: #fff; --input-bg: #ffffff; --err: #d8453d;
+  --pf-bg: #eef1f5; --pf-surface: #ffffff; --pf-surface-2: #f4f6f9; --pf-border: #d4dae2;
+  --pf-text: #2b333d; --pf-text-strong: #1a2129; --pf-text-2: #3a434e;
+  --pf-muted: #6b7480; --pf-muted-2: #59636f; --pf-status: #6b7480; --pf-hint: #8a93a0;
+  --pf-accent: #1f5bd6; --pf-accent-soft: #e6edfc; --pf-on-accent: #fff; --pf-input-bg: #ffffff; --pf-err: #d8453d;
 }

package/src/parts/demo.js

@@ -48,9 +48,9 @@ export default {
       views: ["spacer"],
       export: { name: "spacer" },
       build: (k, p, d) => {
-        let s = k.cylinder(p.od / 2, p.od / 2, p.h);
-        if (p.flange_d > 0) s = k.union([s, k.cylinder(p.flange_d / 2, p.flange_d / 2, p.flange_h)]);
-        return s.cut(k.cylinder(d.boreR, d.boreR, d.cutH).at([0, 0, -2]));
+        let s = k.cylinder({ d: p.od, h: p.h });
+        if (p.flange_d > 0) s = k.union([s, k.cylinder({ d: p.flange_d, h: p.flange_h })]);
+        return s.cut(k.cylinder({ r: d.boreR, h: d.cutH }).at([0, 0, -2]));
       },
     },
   },

package/src/parts/faceted-vase.js

@@ -54,10 +54,10 @@ export default {
     vase: {
       label: "Vase", views: ["vase"], export: { name: "vase" },
       build: (k, p) => {
-        const body = k.loft(vaseRings(p, false)).label("Faceted wall");
+        const body = k.loft({ rings: vaseRings(p, false) }).label("Faceted wall");
         // Hollow it: an inset loft clipped to z ≥ floor (so the base stays solid), cut from the body.
-        const cavity = k.loft(vaseRings(p, true))
-          .intersect(k.box([-1e4, -1e4, p.floor], [1e4, 1e4, p.height + 10])).label("Cavity");
+        const cavity = k.loft({ rings: vaseRings(p, true) })
+          .intersect(k.box({ min: [-1e4, -1e4, p.floor], max: [1e4, 1e4, p.height + 10] })).label("Cavity");
         return body.cut(cavity);
       },
     },

package/src/parts/filleted-box.js

@@ -24,20 +24,20 @@ export default {
       label: "Body",
       views: ["box"],
       build: (k, p) => {
-        let s = k.box([0, 0, 0], [p.w, p.d, p.h]);
+        let s = k.box({ min: [0, 0, 0], max: [p.w, p.d, p.h] });
         const half = Math.min(p.w, p.d) / 2;
         // Round the vertical edges, then the top rim — each clamped to the box so a
         // radius can't exceed the available material.
         const vFillet = Math.min(p.fillet, half - 0.5, p.h - 0.5);
-        if (vFillet > 0) s = s.fillet(vFillet, { dir: "Z" });                   // 4 vertical edges
+        if (vFillet > 0) s = s.fillet({ r: vFillet, edges: { dir: "Z" } });                    // 4 vertical edges
         const topFillet = Math.min(p.top, half - vFillet - 0.5, p.h / 2 - 0.5);
-        if (topFillet > 0) s = s.fillet(topFillet, { inPlane: "XY", at: p.h });  // top rim — curves all the way around
+        if (topFillet > 0) s = s.fillet({ r: topFillet, edges: { inPlane: "XY", at: p.h } });  // top rim — curves all the way around
         // Base chamfer AFTER the fillets, so it cuts a clean curve across the rounded
         // corners. No manual limit needed: the backend auto-clamps a chamfer to half
         // the shortest edge it touches (here the fillets' bottom arcs), so it stops at
         // its valid maximum instead of mangling the bottom face.
-        if (p.chamfer > 0) s = s.chamfer(p.chamfer, { inPlane: "XY", at: 0 });    // base edges
-        if (p.bore > 0) s = s.cut(k.cylinder(p.bore / 2, p.bore / 2, p.h + 2).at([p.w / 2, p.d / 2, -1]).label("Bore"));
+        if (p.chamfer > 0) s = s.chamfer({ d: p.chamfer, edges: { inPlane: "XY", at: 0 } });   // base edges
+        if (p.bore > 0) s = s.cut(k.cylinder({ d: p.bore, h: p.h + 2 }).at([p.w / 2, p.d / 2, -1]).label("Bore"));
         return s;
       },
     },

package/src/parts/planter.js

@@ -89,19 +89,19 @@ export default {
       views: ["planter"],
       export: { name: "planter" },
       build: (k, p, d) => {
-        const body = k.prism(d.outerPts, p.height, { scaleTop: p.taper, twist: p.twist }).label("Faceted wall");
+        const body = k.prism({ points: d.outerPts, h: p.height, scaleTop: p.taper, twist: p.twist }).label("Faceted wall");
         // Hollow it. The cavity is built from z=0 sharing the body's exact twist RATE and
         // taper slope (f rescales the ~4 mm overshoot so the rates still match), so the
         // inner and outer facets stay radially aligned at every height — the wall can't
         // pinch when twisted. Then clip the cavity to z ≥ floor so the base stays solid.
         const f = (p.height + 4) / p.height;
         const cavity = k
-          .prism(d.innerPts, p.height + 4, { scaleTop: 1 + (d.innerTaper - 1) * f, twist: p.twist * f })
-          .intersect(k.box([-1e4, -1e4, p.floor], [1e4, 1e4, p.height + 10]))
+          .prism({ points: d.innerPts, h: p.height + 4, scaleTop: 1 + (d.innerTaper - 1) * f, twist: p.twist * f })
+          .intersect(k.box({ min: [-1e4, -1e4, p.floor], max: [1e4, 1e4, p.height + 10] }))
           .label("Cavity");
         let s = body.cut(cavity);
         // Optional drainage hole straight through the base.
-        if (p.drain > 0) s = s.cut(k.cylinder(d.drainR, d.drainR, p.floor + 4).at([0, 0, -2]).label("Drainage hole"));
+        if (p.drain > 0) s = s.cut(k.cylinder({ r: d.drainR, h: p.floor + 4 }).at([0, 0, -2]).label("Drainage hole"));
         return s;
       },
     },