partforge 0.16.0 → 0.17.0

package/docs/AUTHORING-PARTS.md

@@ -151,11 +151,18 @@ k.prism({ points: roundedProfile(bracketOutline, 3), h: 4 });  // true CIRCLE co
 // print clearance on an arbitrary cut profile, or an inset wall
 k.extrude({ profile: offsetPolygon(slotPolygon(20, 3), 0.2), h: 10 });   // slot cut 0.2 mm looser all around
 offsetPolygon(outline, -wall, { corners: "sharp" });                     // inset a wall (see planter.js)
+
+// A tab with one free-form curved side (exact on STEP, faceted at mesh LOD):
+const tab = pathProfile([0, 0])
+  .lineTo([20, 0]).lineTo([20, 8])
+  .cubicTo([0, 8], [14, 16], [6, 16])   // curved top edge
+  .close();
+k.extrude({ profile: tab, h: 3 });
 ```
 
 2-D polygon helpers for `prism`/`extrude`/`loft`: `import { piePolygon, hexPolygon,
 regularPolygon, roundedRectPolygon, starPolygon, slotPolygon, circleProfile, filletPolygon,
-roundedProfile, offsetPolygon } from "partforge/geometry"`. `filletPolygon(points, r, { segs? })` rounds
+roundedProfile, offsetPolygon, pathProfile } from "partforge/geometry"`. `filletPolygon(points, r, { segs? })` rounds
 every corner of a CCW polygon (per-corner radius clamped so neighbouring arcs never overlap)
 and returns points usable by `prism`/`extrude`/`loft` on both backends — but it **bakes each
 corner into line facets**, so STEP corners are faceted. `roundedProfile(points, r | r[])`
@@ -173,6 +180,7 @@ an offset whose true result would collapse or split into multiple contours (e.g.
 dumbbell past its waist) **throws** a greppable error rather than returning degenerate
 geometry. Being pure, it works in `derive()` as well as `build()` — the natural home for
 clearance math.
+`pathProfile(start)` is a fluent builder for a curve-native path contour (`lineTo` / `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep spline edges on the OCCT/STEP backend and facet at the mesh LOD on Manifold — the same exact-vs-faceted split as `roundedProfile` arcs.
 **Import geometry helpers from `partforge/geometry`, never from `partforge`** — the main
 entry pulls in the DOM viewer/controls, and your build functions run in a Web Worker
 (importing the main entry there throws `document is not defined`).

package/docs/ERROR-PATTERNS.md

@@ -221,6 +221,18 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** the true offset of this shape at this `|delta|` is not a single simple polygon (e.g. insetting a dumbbell past its waist would split it in two) — out of `offsetPolygon`'s envelope.
 - **Fix:** reduce `|delta|`, or decompose the profile into separately-offset simple contours.
 
+## cubic-segment-mixes-arc-and-cubic
+
+- **Symptom:** `extrude: <role> segment cannot mix arc (via) and cubic (c1/c2)`
+- **Cause:** A path-contour segment carries both `via` (three-point arc) and `c1`/`c2` (cubic Bézier). A segment is exactly one kind.
+- **Fix:** Drop `via` for a cubic, or drop `c1`/`c2` for an arc. Use `pathProfile().arcTo(to, via)` or `.cubicTo(to, c1, c2)` to build segments.
+
+## cubic-segment-missing-controls
+
+- **Symptom:** `extrude: <role> cubic segment needs c1 and c2 as finite [x,y]`
+- **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`.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.16.0",
+  "version": "0.17.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/occt-backend.js

@@ -89,8 +89,9 @@ export function createOcctKernel(replicad) {
   // Draw a closed Drawing from a Contour: a legacy 2-D point list (all straight edges,
   // the former polyDrawing) OR an ArcContour whose { to, via } segments become true
   // OCCT arc edges via threePointsArcTo — so a rounded corner survives to STEP as a
-  // real CIRCLE B-rep entity, not a fan of LINEs. close() joins the last point back to
-  // the start with a straight edge (mirrors the implied ArcContour closure).
+  // real CIRCLE B-rep entity, not a fan of LINEs. Cubic segments ({ to, c1, c2 })
+  // map to cubicBezierCurveTo for exact B-rep spline edges. close() joins the last
+  // point back to the start with a straight edge (mirrors the implied ArcContour closure).
   const contourDrawing = (contour) => {
     if (Array.isArray(contour)) {
       let pen = draw(contour[0]);
@@ -98,7 +99,10 @@ export function createOcctKernel(replicad) {
       return pen.close();
     }
     let pen = draw(contour.start);
-    for (const seg of contour.segments) pen = seg.via ? pen.threePointsArcTo(seg.to, seg.via) : pen.lineTo(seg.to);
+    for (const seg of contour.segments)
+      pen = seg.c1 ? pen.cubicBezierCurveTo(seg.to, seg.c1, seg.c2)
+          : seg.via ? pen.threePointsArcTo(seg.to, seg.via)
+          : pen.lineTo(seg.to);
     return pen.close();
   };
 

package/src/framework/geometry/polygon.js

@@ -156,6 +156,32 @@ export function filletPolygon(points, r, { segs = 8 } = {}) {
   return out;
 }
 
+// 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.
+export function pathProfile(start) {
+  const fin2 = (p, what) => {
+    if (!Array.isArray(p) || p.length < 2 || !Number.isFinite(p[0]) || !Number.isFinite(p[1]))
+      throw new Error(`pathProfile: ${what} must be a finite [x,y]`);
+    return [p[0], p[1]];
+  };
+  const s = fin2(start, "start");
+  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; },
+    cubicTo(to, c1, c2) {
+      segments.push({ to: fin2(to, "cubicTo point"), c1: fin2(c1, "cubicTo c1"), c2: fin2(c2, "cubicTo c2") });
+      return api;
+    },
+    close() {
+      if (segments.length < 1) throw new Error("pathProfile: need ≥1 segment before close()");
+      return { start: [s[0], s[1]], segments: segments.slice() }; // snapshot — chaining after close() must not mutate the returned contour
+    },
+  };
+  return api;
+}
+
 // Arc-aware sibling of filletPolygon: rounds the corners of a CCW polygon with the SAME
 // tangent/centre/sweep math (via cornerArc), but instead of tessellating each arc into
 // line facets it emits a canonical ArcContour { start, segments:[{to}|{to,via}], arc:true }

package/src/framework/geometry/profile.js

@@ -1,23 +1,37 @@
 // Backend-shared 2-D region normalization + tessellation for extrude()/prism(). A contour
-// is EITHER a bare points array (legacy, all straight edges) OR a canonical ArcContour
-// { start:[x,y], segments:[{to}|{to,via}], arc:true } carrying true circular arcs (from
-// roundedProfile). normalizeProfile validates the polymorphic { outer, holes } envelope
-// (bare array = outer only), preserving each contour's shape; tessellateProfile turns the
-// arcs into point rings for the Manifold (mesh) path. The OCCT path consumes the same
-// ArcContour directly (contourDrawing → threePointsArcTo) for true CIRCLE B-rep edges.
-// Legacy point-array contours take the exact former path byte-for-byte — no cache-busting.
+// is EITHER a bare points array (legacy, all straight edges) OR a canonical path contour
+// { start:[x,y], segments:[{to}|{to,via}|{to,c1,c2}] } carrying true circular arcs ({to,via},
+// from roundedProfile) and/or cubic Béziers ({to,c1,c2}, from pathProfile). normalizeProfile
+// validates the polymorphic { outer, holes } envelope (bare array = outer only), preserving
+// each contour's shape; tessellateProfile turns arcs/cubics into point rings for the Manifold
+// (mesh) path at the mesh LOD. The OCCT path consumes the same contour directly (contourDrawing
+// → threePointsArcTo / cubicBezierCurveTo) for true CIRCLE / B-spline B-rep edges. Legacy
+// point-array contours take the exact former path byte-for-byte — no cache-busting.
 
 // An ArcContour is a non-array object carrying arcs symbolically.
 export function isArcContour(c) {
   return !!c && typeof c === "object" && !Array.isArray(c) && (c.arc === true || Array.isArray(c.segments));
 }
 
+// Curves generalize arcs; the symbolic-form predicate is the same. Prefer this name.
+export const isPathContour = isArcContour;
+
 function validateContour(c, role) {
   if (isArcContour(c)) {
     if (!Array.isArray(c.start) || c.start.length < 2)
       throw new Error(`extrude: ${role} arc contour needs a start [x,y]`);
     if (!Array.isArray(c.segments) || c.segments.length < 1)
       throw new Error(`extrude: ${role} arc contour needs ≥1 segment`);
+    for (const s of c.segments) {
+      const hasCubic = s.c1 != null || s.c2 != null;
+      if (hasCubic) {
+        if (s.via != null)
+          throw new Error(`extrude: ${role} segment cannot mix arc (via) and cubic (c1/c2)`);
+        const ok = (p) => Array.isArray(p) && p.length >= 2 && Number.isFinite(p[0]) && Number.isFinite(p[1]);
+        if (!ok(s.c1) || !ok(s.c2))
+          throw new Error(`extrude: ${role} cubic segment needs c1 and c2 as finite [x,y]`);
+      }
+    }
     return;
   }
   if (!Array.isArray(c) || c.length < 3) throw new Error(`extrude: ${role} needs ≥3 points`);
@@ -73,15 +87,50 @@ export function sampleArc(p0, via, p1, segs) {
   return out;
 }
 
+// Flatten the cubic Bézier (p0,c1,c2,p1) into points p1…pN — EXCLUDING the start
+// p0 (the ring already holds it), last point pinned exactly to p1. Adaptive: split
+// at t=½ (de Casteljau) until the control polygon's total unsigned turn is ≤ 2π/segs
+// — the exact generalization of sampleArc's "a point every 2π/segs of sweep", so a
+// cubic tracing a circular arc facets like the arc primitive at the same segs. Summing
+// |turn| at BOTH interior control points also catches S-curves a pure endpoint-tangent
+// test would miss. Depth cap guarantees termination. Pure in (args, segs).
+export function sampleBezier(p0, c1, c2, p1, segs) {
+  const maxTurn = (2 * Math.PI) / Math.max(3, segs);
+  const out = [];
+  const mid = (a, b) => [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+  const turn = (u, v) => {
+    const du = Math.hypot(u[0], u[1]), dv = Math.hypot(v[0], v[1]);
+    if (du < 1e-12 || dv < 1e-12) return 0;
+    let c = (u[0] * v[0] + u[1] * v[1]) / (du * dv);
+    if (c > 1) c = 1; else if (c < -1) c = -1;
+    return Math.acos(c);
+  };
+  const recurse = (a, b, c, d, depth) => {
+    const ab = [b[0] - a[0], b[1] - a[1]];
+    const bc = [c[0] - b[0], c[1] - b[1]];
+    const cd = [d[0] - c[0], d[1] - c[1]];
+    if (depth >= 12 || turn(ab, bc) + turn(bc, cd) <= maxTurn) { out.push([d[0], d[1]]); return; }
+    const p01 = mid(a, b), p12 = mid(b, c), p23 = mid(c, d);
+    const p012 = mid(p01, p12), p123 = mid(p12, p23), m = mid(p012, p123);
+    recurse(a, p01, p012, m, depth + 1);
+    recurse(m, p123, p23, d, depth + 1);
+  };
+  recurse(p0, c1, c2, p1, 0);
+  if (out.length === 0) out.push([p1[0], p1[1]]);
+  out[out.length - 1] = [p1[0], p1[1]];   // pin the exact endpoint
+  return out;
+}
+
 // Tessellate a single contour into a CCW point ring. A legacy array is returned unchanged
-// (identical to the former path); an ArcContour is walked start→segment→segment, lines
-// pushing their `to` and arcs pushing their sampled points.
+// (identical to the former path); a path contour is walked start→segment→segment, lines
+// pushing their `to`, arcs and cubics pushing their sampled points (sampleArc/sampleBezier).
 export function tessellateContour(contour, segs) {
   if (Array.isArray(contour)) return contour;
   const ring = [[contour.start[0], contour.start[1]]];
   let prev = contour.start;
   for (const seg of contour.segments) {
-    if (seg.via) for (const p of sampleArc(prev, seg.via, seg.to, segs)) ring.push(p);
+    if (seg.c1) for (const p of sampleBezier(prev, seg.c1, seg.c2, seg.to, segs)) ring.push(p);
+    else if (seg.via) for (const p of sampleArc(prev, seg.via, seg.to, segs)) ring.push(p);
     else ring.push([seg.to[0], seg.to[1]]);
     prev = seg.to;
   }