partforge 0.112.0 → 0.113.0

package/docs/AUTHORING-PARTS.md

@@ -436,6 +436,7 @@ offsetPolygon(outline, -wall, { corners: "sharp" });                     // inse
 const tab = pathProfile([0, -w / 2])
   .lineTo([len, -w / 2])
   .arcTo([len, w / 2], [len + w / 2, 0])   // tip, via the apex
+  // same arc: .arcTo([len, w / 2], { r: w / 2 }) — radius form, no via to compute
   .lineTo([0, w / 2])
   .close();
 k.extrude({ profile: tab, h: 3 });
@@ -445,6 +446,7 @@ const lip = pathProfile([0, 0])
   .lineTo([20, 0]).lineTo([20, 8])
   .cubicTo([0, 8], [14, 16], [6, 16])   // curved top edge
   .close();
+k.extrude({ profile: lip, h: 3 });
 
 // Rounded enclosure: soft vertical edges, a softer lid, a flat base.
 const shell = k.roundedBox({ size: [60, 40, 22], round: { side: 4, top: 2, bottom: 0 } });
@@ -470,7 +472,7 @@ dumbbell past its waist) **throws** a greppable error rather than returning dege
 geometry. Being pure, it works in `derive()` as well as `build()` — the natural home for
 clearance math.
 `pathProfile(start)` is a fluent builder for a curve-native path contour (`lineTo` / `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep spline edges on the OCCT/STEP backend and facet at the mesh LOD on Manifold — the same exact-vs-faceted split as `roundedProfile` arcs.
-`arcTo(to, via)` is a **three-point arc**: `via` is any point on the arc between the current point and `to` (its midpoint is the natural choice), and the sweep is whichever direction passes through it — so an arc's direction is a property of a point you can see, never of a sign. Build the symmetric half of a profile once and `mirrorProfile` it (see "Editing profiles") rather than writing the mirrored arcs by hand. `loft` accepts these contours as rings (every ring with the same segment signature lofts curve-to-curve).
+`arcTo(to, via)` is a **three-point arc**: `via` is any point on the arc between the current point and `to` (its midpoint is the natural choice), and the sweep is whichever direction passes through it — so an arc's direction is a property of a point you can see, never of a sign. `arcTo(to, { r, sweep?, large? })` is the **radius form** for when you know the radius, not a point on the arc: it computes `via` from the current point, `to`, and `r`, emitting the exact same `{to, via}` segment the three-point form does. `sweep` names the direction the arc itself is traversed (default `"ccw"`), so on a counter-clockwise outline `"ccw"` bulges OUTWARD (a convex bump), and inward on a clockwise hole; `"cw"` is the reverse. `large` (default `false`) picks the major arc over the minor one when both are possible. A radius shorter than half the distance between the current point and `to` throws rather than being silently scaled up (the way SVG's arc command does) — the smallest circle joining the two points is a semicircle at `r = d/2`. Build the symmetric half of a profile once and `mirrorProfile` it (see "Editing profiles") rather than writing the mirrored arcs by hand. `loft` accepts these contours as rings (every ring with the same segment signature lofts curve-to-curve).
 **`pathProfile` or an authored vector file?** Reach for `pathProfile` (and the polygon helpers above) when the geometry is **computed from parameters** — a profile whose dimensions come from `p`/`d`, which a JSON file cannot see. Reach for an authored `partforge-vector` document (`k.vector2d`, see "Vector geometry" below) when the geometry is **drawn** — a logo, a faceplate outline, a decorative cutout, where each number means one thing and gets edited on its own. The two are freely composable: both produce ordinary 2-D geometry that the same booleans and editing ops accept.
 **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main
 entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker

package/docs/ERROR-PATTERNS.md

@@ -316,6 +316,12 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** A cubic segment is missing `c1` or `c2`, or a control point is not a finite `[x,y]` (e.g. `NaN`, wrong length).
 - **Fix:** Provide both control points as finite `[x,y]`. A cubic Bézier needs two controls between the previous point and `to`.
 
+## arcto-radius-too-short
+
+- **Symptom:** `pathProfile: arcTo r=<r> is shorter than half the chord (<half-chord>) from (<x0>, <y0>) to (<x1>, <y1>) — the smallest arc that can join these points has r=<half-chord> (a semicircle)`
+- **Cause:** `pathProfile().arcTo(to, { r, sweep?, large? })`'s `r` is smaller than half the distance between the current point and `to` — no circle of that radius passes through both points.
+- **Fix:** Raise `r` to at least half the chord (the message states the exact minimum), or move the endpoint closer. Unlike SVG's arc command, partforge refuses rather than silently scaling `r` up to fit — the model should learn the number it wrote was wrong rather than have it quietly corrected.
+
 ## shape2d-simple-not-single-region
 
 - **Symptom:** `Shape2D.simple: result has N regions, not 1 (use toRegions())`

package/package.json

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

@@ -157,8 +157,9 @@ export function filletPolygon(points, r, { segs = 8 } = {}) {
 }
 
 // Fluent builder for a curve-native path contour { start, segments }. Segment kinds:
-// lineTo → {to}, arcTo → {to,via} (three-point arc), cubicTo → {to,c1,c2} (cubic Bézier).
-// close() returns the plain contour object (feeds extrude/revolve/prism), not a Solid.
+// lineTo → {to}, arcTo → {to,via} (three-point arc) or {to,via} computed from a radius
+// spec, cubicTo → {to,c1,c2} (cubic Bézier). close() returns the plain contour object
+// (feeds extrude/revolve/prism), not a Solid.
 export function pathProfile(start) {
   const fin2 = (p, what) => {
     if (!Array.isArray(p) || p.length < 2 || !Number.isFinite(p[0]) || !Number.isFinite(p[1]))
@@ -166,12 +167,73 @@ export function pathProfile(start) {
     return [p[0], p[1]];
   };
   const s = fin2(start, "start");
+  let cur = s;
   const segments = [];
   const api = {
-    lineTo(to) { segments.push({ to: fin2(to, "lineTo point") }); return api; },
-    arcTo(to, via) { segments.push({ to: fin2(to, "arcTo point"), via: fin2(via, "arcTo via") }); return api; },
+    lineTo(to) {
+      const p = fin2(to, "lineTo point");
+      segments.push({ to: p });
+      cur = p;
+      return api;
+    },
+    // arcTo(to, via) is the three-point form: `via` is any point on the arc.
+    // arcTo(to, { r, sweep?, large? }) is the radius form: `via` is computed here
+    // from the current point, `to`, and the radius spec so the emitted segment is
+    // byte-for-byte what the three-point form emits (see docs/AUTHORING-PARTS.md).
+    arcTo(to, second) {
+      const p1 = fin2(to, "arcTo point");
+      if (Array.isArray(second)) {
+        const via = fin2(second, "arcTo via");
+        segments.push({ to: p1, via });
+        cur = p1;
+        return api;
+      }
+      if (second !== null && typeof second === "object") {
+        const ARC_SPEC_KEYS = ["r", "sweep", "large"];
+        const unknownKeys = Object.keys(second).filter((k) => !ARC_SPEC_KEYS.includes(k));
+        if (unknownKeys.length > 0)
+          throw new Error(
+            `pathProfile: arcTo arc spec has unknown ${unknownKeys.length > 1 ? "keys" : "key"} ${unknownKeys.map((k) => JSON.stringify(k)).join(", ")} — the keys are r, sweep, large`,
+          );
+        const { r, sweep = "ccw", large = false } = second;
+        // Cheap key/enum/boolean checks run BEFORE the numeric ones below, so a
+        // typo'd sweep/large is reported on its own rather than being masked by
+        // an unrelated radius complaint on the same call.
+        if (sweep !== "ccw" && sweep !== "cw")
+          throw new Error(`pathProfile: arcTo sweep must be "ccw" or "cw", got ${JSON.stringify(sweep)}`);
+        if (typeof large !== "boolean")
+          throw new Error("pathProfile: arcTo large must be a boolean");
+        const [x0, y0] = cur;
+        const [x1, y1] = p1;
+        const dx = x1 - x0, dy = y1 - y0;
+        const d = Math.hypot(dx, dy);
+        if (d < 1e-9)
+          throw new Error(`pathProfile: arcTo to (${x1}, ${y1}) coincides with the current point`);
+        if (!(r > 0) || !Number.isFinite(r))
+          throw new Error(`pathProfile: arcTo r must be > 0 and finite, got ${JSON.stringify(r)}`);
+        if (r < d / 2 - 1e-9)
+          throw new Error(
+            `pathProfile: arcTo r=${r} is shorter than half the chord (${(d / 2).toFixed(4)}) from (${x0}, ${y0}) to (${x1}, ${y1}) — the smallest arc that can join these points has r=${(d / 2).toFixed(4)} (a semicircle)`,
+          );
+        const rr = Math.max(r, d / 2);                    // absorb the 1e-9 tolerance so h is never NaN
+        const h = Math.sqrt(rr * rr - (d / 2) * (d / 2));  // centre's distance from the chord midpoint
+        const ux = dx / d, uy = dy / d;                    // unit chord direction
+        const nx = -uy, ny = ux;                           // unit LEFT normal of the direction of travel
+        const mx = (x0 + x1) / 2, my = (y0 + y1) / 2;
+        const side = sweep === "ccw" ? -1 : 1;             // which side of the chord the arc bulges to
+        const sgn = large ? side : -side;
+        const cx = mx + nx * h * sgn, cy = my + ny * h * sgn;
+        const via = [cx + nx * rr * side, cy + ny * rr * side]; // the arc's midpoint
+        segments.push({ to: p1, via });
+        cur = p1;
+        return api;
+      }
+      throw new Error("pathProfile: arcTo needs a via [x,y] or an { r, sweep?, large? } arc spec");
+    },
     cubicTo(to, c1, c2) {
-      segments.push({ to: fin2(to, "cubicTo point"), c1: fin2(c1, "cubicTo c1"), c2: fin2(c2, "cubicTo c2") });
+      const p = fin2(to, "cubicTo point");
+      segments.push({ to: p, c1: fin2(c1, "cubicTo c1"), c2: fin2(c2, "cubicTo c2") });
+      cur = p;
       return api;
     },
     close() {

package/types/geometry.d.ts

@@ -86,6 +86,8 @@ export interface PathProfileBuilder {
   lineTo(to: Point2): PathProfileBuilder;
   /** A circular arc to `to` passing through `via`. */
   arcTo(to: Point2, via: Point2): PathProfileBuilder;
+  /** A circular arc to `to` of radius `r`; `via` is computed from the current point. */
+  arcTo(to: Point2, arc: { r: number; sweep?: "ccw" | "cw"; large?: boolean }): PathProfileBuilder;
   /** A cubic Bézier to `to` with control points `c1`/`c2`. */
   cubicTo(to: Point2, c1: Point2, c2: Point2): PathProfileBuilder;
   /** Close the contour and return it. Needs at least one segment. */