partforge 0.131.0 → 0.132.0

package/docs/AUTHORING-PARTS.md

@@ -1501,7 +1501,8 @@ in STEP. Use these for every round outline that shows or fits:
 ring is a region with a hole: extrude `{ outer, holes }` or cut an inner cylinder from an outer
 one), `pieProfile(tipR,arcDeg)` (a sector from the origin), `slotProfile(length,r)` (overall
 length = `length + 2r`; `length` 0 is a circle), `roundedRectProfile(w,h,r)` (r clamped to
-min(w,h)/2), `roundedProfile(points,r)` (round any polygon's corners), and `pathProfile()`.
+min(w,h)/2), `circleProfile(r, center?)` (a circle), `roundedProfile(points,r)` (round any
+polygon's corners), and `pathProfile()`.
 
 *Straight edges* — CCW point arrays, built and exported exactly as written:
 `regularPolygon(n,r,{flat})`, `hexPolygon(r)`, `starPolygon(points,outerR,innerR)`,
@@ -1509,14 +1510,13 @@ min(w,h)/2), `roundedProfile(points,r)` (round any polygon's corners), and `path
 `circlePolygon(r, center?, segs = 48)` — a circle as a fixed point list, for a deliberately
 faceted circle or point math of your own (mapping, indexing, spreading its points).
 
-*Circles.* `circleProfile(r, center?)` is the circle to hand to an op — `prism`, an `extrude`
-outline or hole, `k.shape2d`, `revolve`, `hull`, `loft`, `sweep`. **It is in transition**:
-today it returns the same 48 points as `circlePolygon`, and a coming release turns it into an
-exact curve like the other `*Profile` helpers. So pass it straight to an op and **never map,
-index or spread its result — use `circlePolygon` for that**. Until then, an exact circle in a
-2-D profile is `slotProfile(0, r)`. For a round SOLID use `k.cylinder` (a prism of 48 points is
-a 48-sided prism, never refined at export), and **use `k.torus({ rMajor, rMinor })` for a
-torus** — the primitive keeps real TORUS faces in STEP.
+*Circles.* `circleProfile(r, center?)` is an exact circle, like the other `*Profile` helpers:
+hand it to any op — `prism`, an `extrude` outline or hole, `k.shape2d`, `revolve`, `hull`,
+`loft`, `sweep` (sweep and `offsetPolygon` sample it at 48 points). It is a path contour, not
+an array, so for point math of your own use `circlePolygon`. (Before partforge 0.132 it
+returned `circlePolygon`'s points; it takes no `segs`.) For a round SOLID use `k.cylinder`,
+and **use `k.torus({ rMajor, rMinor })` for a torus** — the primitive keeps real TORUS faces
+in STEP.
 
 **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 })`.

package/docs/ERROR-PATTERNS.md

@@ -826,8 +826,8 @@ between the Manifold preview and the OCCT STEP export.
 ## profile-sampled-arc
 
 - **Symptom:** The build succeeds and its result carries a warning like `prism: profile traces an arc in straight facets (radius ≈ 30.0 mm, 9.0° per facet, up to 0.09 mm inside the true curve) — a point list is built and exported exactly as written, so a print shows those facets. …` (also `extrude: profile …`, `revolve: profile …`, `shape2d: profile …`). A printed part with that outline shows flat spots, and a fit built on it (a bayonet lug in its track, a pin in a slot) binds or rattles. Identical text on both backends.
-- **Cause:** *(partforge ≥ 0.131.)* A point list is built and exported exactly as written: only curves the kernel knows about — primitives, a revolve's sweep, and the arcs of a path contour or `Shape2D` — are faceted per quality tier and refined at export. An arc sampled into a point list keeps the facets it was sampled with, however fine the export. The round `*Polygon` helpers sample at 32 per circle (`ringSectorPolygon`, `slotPolygon`, `piePolygon`, and `roundedRectPolygon`'s corners), `filletPolygon` at 8 segments per corner whatever its angle, `circlePolygon` (and, until it becomes an exact curve, `circleProfile`) at 48, and a hand-written `Math.cos` loop at whatever it was given. The kernel reports the worst run in a profile: three or more facets turning by the same amount, at most 20° each, whose chord sits more than 0.05 mm inside the true arc. The end facets of a run may be shorter (an offset trims them), and coordinates may carry about 0.01 mm of rounding. Hexagons and other deliberate polygons, small holes, and finely sampled loops stay quiet, as does an arc of only two facets, which can't be told from a bend. It checks the outlines the author hands to `prism`, `extrude`, `revolve` and `k.shape2d`, including a bevelled `extrude`'s. It doesn't check what the kernel samples itself (a bevel's rim, a `screwSweep`'s section, a `hull`), or `loft` and `sweep`, which sample curve rings at their own fixed detail. At most three lines are reported per build.
-- **Fix:** Rebuild the outline from exact curves: `ringSectorProfile`, `slotProfile`, `pieProfile` and `roundedRectProfile` trace the same outlines as their `*Polygon` namesakes, `roundedProfile` rounds any polygon's corners, and `pathProfile(start).arcTo(to, via)` builds anything else — all are path contours the kernel facets per tier and refines at export (and OCCT keeps as true circles in STEP). There is no export-resolution setting to raise instead. For an exact circle in a 2-D profile use `slotProfile(0, r)`; for a round solid, `k.cylinder`. Sampling more points by hand only moves the facets, and it keeps them frozen.
+- **Cause:** *(partforge ≥ 0.131.)* A point list is built and exported exactly as written: only curves the kernel knows about — primitives, a revolve's sweep, and the arcs of a path contour or `Shape2D` — are faceted per quality tier and refined at export. An arc sampled into a point list keeps the facets it was sampled with, however fine the export. The round `*Polygon` helpers sample at 32 per circle (`ringSectorPolygon`, `slotPolygon`, `piePolygon`, and `roundedRectPolygon`'s corners), `filletPolygon` at 8 segments per corner whatever its angle, `circlePolygon` at 48 (and `circleProfile`, before partforge 0.132), and a hand-written `Math.cos` loop at whatever it was given. The kernel reports the worst run in a profile: three or more facets turning by the same amount, at most 20° each, whose chord sits more than 0.05 mm inside the true arc. The end facets of a run may be shorter (an offset trims them), and coordinates may carry about 0.01 mm of rounding. Hexagons and other deliberate polygons, small holes, and finely sampled loops stay quiet, as does an arc of only two facets, which can't be told from a bend. It checks the outlines the author hands to `prism`, `extrude`, `revolve` and `k.shape2d`, including a bevelled `extrude`'s. It doesn't check what the kernel samples itself (a bevel's rim, a `screwSweep`'s section, a `hull`), or `loft` and `sweep`, which sample curve rings at their own fixed detail. At most three lines are reported per build.
+- **Fix:** Rebuild the outline from exact curves: `ringSectorProfile`, `slotProfile`, `pieProfile`, `roundedRectProfile` and `circleProfile` trace the same outlines as their `*Polygon` namesakes, `roundedProfile` rounds any polygon's corners, and `pathProfile(start).arcTo(to, via)` builds anything else — all are path contours the kernel facets per tier and refines at export (and OCCT keeps as true circles in STEP). There is no export-resolution setting to raise instead. For an exact circle use `circleProfile`; for a round solid, `k.cylinder`. Sampling more points by hand only moves the facets, and it keeps them frozen.
 
 ## export-kernel-out-of-memory
 

package/docs/KERNEL-CONTRACT.md

@@ -722,9 +722,8 @@ case appears; add its deterministic fixture and establish the source-domain trut
 `roundedRectProfile`, `circlePolygon`) are pure functions from numbers to plain CCW point
 lists or arc profiles — *data already in this contract's input format*, with no kernel
 dependency at all. The naming rule: `*Profile` builders return path contours with symbolic
-arcs, `*Polygon` builders return point lists. `circleProfile` is in transition: it still
-returns `circlePolygon`'s 48 points, and becomes a path contour in 0.132, once stored parts
-that do point math on it have been migrated to `circlePolygon`. The **solid patterns** (`linearPattern`, `circularPattern`) take a
+arcs, `*Polygon` builders return point lists. (`circleProfile` returned `circlePolygon`'s 48
+points until 0.132.) The **solid patterns** (`linearPattern`, `circularPattern`) take a
 `Solid` and call only ops from the tables above (`clone`/`translate`/`rotate`/
 `boundingBox`). The **profile transform** (`offsetPolygon`) takes a point list or
 `{outer, holes}` region and grows or shrinks it by a delta in mm — printer-clearance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.131.0",
+  "version": "0.132.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/geometry/polygon.js

@@ -412,15 +412,24 @@ export function circlePolygon(r, center = [0, 0], segs = 48) {
   return pts;
 }
 
-// A circle for passing to a kernel op (prism, extrude outline or hole, shape2d, revolve,
-// hull, loft, sweep). TRANSITIONAL: today it returns exactly circlePolygon's 48 points;
-// partforge 0.132 turns it into an exact curve like the other *Profile helpers. Stored
-// parts that do point math on it are migrated to circlePolygon before that release
-// (see docs/superpowers/specs/2026-09-28-curve-profile-helpers-design.md), so new code
-// should never map, index or spread its result — use circlePolygon for that.
-export function circleProfile(r, center = [0, 0], segs = 48) {
+// An exact circle of radius r centred at [cx, cy]: a path contour of two three-point
+// semicircles, starting at angle 0 like circlePolygon's points. The kernel facets it per
+// quality tier (finer at export) and OCCT keeps a true CIRCLE; sweep and offsetPolygon,
+// which take point lists, sample it at 48 per circle (contourToPoints) — the density it
+// had as a point list. Until partforge 0.132 this returned circlePolygon's 48 points;
+// stored parts that did point math on it were migrated to circlePolygon first. A third
+// `segs` argument belonged to the point list, so it is refused by name rather than
+// silently ignored.
+export function circleProfile(r, center = [0, 0], ...rest) {
   if (!(r > 0)) throw new Error("circleProfile: r must be > 0");
-  return circlePolygon(r, center, segs);
+  if (rest.length > 0 && rest[0] !== undefined)
+    throw new Error("circleProfile: an exact circle takes no segs — use circlePolygon(r, center, segs) for a faceted circle");
+  const [cx, cy] = center;
+  const start = [cx + r, cy];
+  return contourFrom(start)
+    .arc([cx - r, cy], [cx, cy + r])
+    .arc([cx + r, cy], [cx, cy - r])
+    .close();
 }
 
 // --- offsetPolygon ---------------------------------------------------------

package/src/framework/geometry/profile-warnings.js

@@ -100,7 +100,7 @@ const NOISE_MM = 0.01;
 const SAMPLED_ARC_COACH =
   "a point list is built and exported exactly as written, so a print shows those facets. " +
   "Build curves with the *Profile helpers (ringSectorProfile, slotProfile, pieProfile, " +
-  "roundedRectProfile, roundedProfile) or pathProfile().arcTo(…) — the kernel facets those, finer at export.";
+  "roundedRectProfile, circleProfile, roundedProfile) or pathProfile().arcTo(…) — the kernel facets those, finer at export.";
 
 // The worst sampled-arc run in one closed point ring, or null.
 // → { r, stepDeg, sag } for the run with the largest chord sagitta.

package/src/parts/bracket.js

@@ -4,11 +4,10 @@
 //   • cutAll      — four corner bolt holes drilled in one batch
 //   • cut         — a central bore
 //   • offset      — an optional print-clearance grow with rounded corners
-// The rounded corners and the clip disc are exact arcs (*Profile helpers; slotProfile(0, r)
-// is an exact circle), which the kernel refines at export. The small bolt holes use
-// circleProfile's fixed 48-gon, within 0.05 mm of round at this size.
+// The rounded corners, the clip disc and the holes are exact arcs (*Profile helpers), so
+// the whole outline stays curve-exact and the kernel refines it at export.
 // Open /bracket.html after `npm run dev`.
-import { roundedRectProfile, slotProfile, circleProfile } from "partforge/geometry";
+import { roundedRectProfile, circleProfile } from "partforge/geometry";
 
 export default {
   meta: { title: "Cross bracket", units: "mm", background: 0x15181d, environment: "workshop" },
@@ -65,7 +64,7 @@ export default {
         const barH = k.shape2d(roundedRectProfile(p.span, p.bar, p.corner));
         const barV = k.shape2d(roundedRectProfile(p.bar, p.span, p.corner));
         let plate = barH.union(barV);                                        // union
-        if (p.clip) plate = plate.intersect(k.shape2d(slotProfile(0, p.span / 2)));  // intersect (an exact disc)
+        if (p.clip) plate = plate.intersect(k.shape2d(circleProfile(p.span / 2)));  // intersect
         const d = p.span / 2 - p.inset;
         const holes = [[d, d], [-d, d], [d, -d], [-d, -d]].map((c) => circleProfile(p.hole_d / 2, c));
         plate = plate.cutAll(holes);                                         // batch cut

package/types/geometry.d.ts

@@ -71,12 +71,12 @@ export function ringSectorPolygon(innerR: number, outerR: number, arcDeg: number
 export function circlePolygon(r: number, center?: Point2, segs?: number): PointsContour;
 
 /**
- * A circle for passing to a kernel op (prism, extrude outline or hole, shape2d, revolve,
- * hull, loft, sweep). Transitional: today it returns exactly `circlePolygon`'s 48 points,
- * and partforge 0.132 turns it into an exact curve like the other `*Profile` helpers —
- * so never map, index or spread its result; use `circlePolygon` for point math.
+ * An exact circle of radius `r` centred at `center`: a path contour of two semicircles
+ * starting at angle 0, which the kernel facets per tier (finer at export) and OCCT keeps as
+ * a true circle. Not an array — use `circlePolygon` for point math. (Until 0.132 this
+ * returned `circlePolygon`'s 48 points; it takes no `segs`.)
  */
-export function circleProfile(r: number, center?: Point2, segs?: number): PointsContour;
+export function circleProfile(r: number, center?: Point2): ArcContour;
 
 /**
  * Per-corner rounding geometry shared by `filletPolygon` and `roundedProfile`: