partforge 0.14.0 → 0.16.0

package/docs/AUTHORING-PARTS.md

@@ -147,11 +147,15 @@ k.sweep({ profile: circleProfile(3), path: [[0, 0, 0], [0, 0, 20], [15, 0, 20]],
 // round every corner of any CCW outline, then extrude/loft/prism it
 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
+
+// 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)
 ```
 
 2-D polygon helpers for `prism`/`extrude`/`loft`: `import { piePolygon, hexPolygon,
-regularPolygon, roundedRectPolygon, starPolygon, circleProfile, filletPolygon,
-roundedProfile } from "partforge/geometry"`. `filletPolygon(points, r, { segs? })` rounds
+regularPolygon, roundedRectPolygon, starPolygon, slotPolygon, circleProfile, filletPolygon,
+roundedProfile, offsetPolygon } 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[])`
@@ -159,7 +163,16 @@ rounds corners the same way but keeps them **mathematically true** — it carrie
 symbolically so STEP export gets real circular edges. Use it for `prism`/`extrude` (not yet
 `loft` — arc rings are rejected there in v1). A scalar `r` rounds every corner; a per-corner
 `r[]` (length = points) rounds selectively (a `0`, a zero-length edge, or a straight/180°
-corner stays sharp).
+corner stays sharp). `offsetPolygon(profile, delta, { corners?, segs? })` offsets a
+point-list polygon or `{ outer, holes }` region by `delta` mm — positive grows material,
+negative insets; regions offset material-wise (outer `+delta`, holes `−delta`, so a
+clearance loosens the whole cut). `corners` picks the convex-corner style: `"round"`
+(default; the true Minkowski clearance), `"chamfer"`, or `"sharp"` (miter, falling back to
+chamfer past a miter length of 2·|delta|). It is **simple polygon in, simple polygon out**:
+an offset whose true result would collapse or split into multiple contours (e.g. insetting a
+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.
 **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

@@ -195,6 +195,32 @@ The sphere variant is `sphere: pass exactly one of r/d` (same cause and fix).
 - **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).
 
+## offset-polygon-bad-input
+
+- **Symptom:** `offsetPolygon: need at least 3 points`
+- **Cause:** malformed input to `offsetPolygon` — too few points after dedup, or (variant messages) a non-finite `delta`, non-finite coordinates, an unknown `corners` style, or a profile that is neither a point list nor `{outer, holes}`.
+- **Fix:** pass a CCW `[[x,y],…]` list (≥ 3 distinct points) or `{outer, holes}`, a finite `delta` in mm, and `corners: "round" | "chamfer" | "sharp"` — see [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Profiles & patterns".
+
+Variant literals under this entry: `offsetPolygon: delta must be a finite number`, `offsetPolygon: coordinates must be finite numbers`, `offsetPolygon: corners must be "round" | "chamfer" | "sharp"`, `offsetPolygon: profile must be a point list or {outer, holes}`.
+
+## offset-polygon-input-self-intersects
+
+- **Symptom:** `offsetPolygon: input polygon self-intersects`
+- **Cause:** the input contour crosses itself — the profile is broken before any offsetting happens (checked up front so bad input is not blamed on the offset).
+- **Fix:** repair the generating math for the contour; the offset envelope requires simple polygons in and out.
+
+## offset-polygon-collapse
+
+- **Symptom:** `offsetPolygon: offset collapses the polygon`
+- **Cause:** the offset consumed the shape — either an inset ate the whole polygon (result area ≤ 0 or fewer than 3 points, `|delta|` past the narrowest half-width; also thrown for a region hole that would vanish), or an offset displaced an edge past its own length so the edge inverts (a large inset, or a large *outset* of a concave profile where `|delta|` exceeds a reflex-adjacent edge — this last case can also depend on `corners`, since `"sharp"` extends edges further than `"round"`/`"chamfer"`).
+- **Fix:** reduce `|delta|`, or clamp it from the shape's dimensions before offsetting (see planter.js's wall cap). If a vanishing hole is intended, remove the hole from the region explicitly. Realistic clearances (fractions of a mm) on any profile, and wall insets up to the narrowest feature, never trip this.
+
+## offset-polygon-result-self-intersects
+
+- **Symptom:** `offsetPolygon: offset result self-intersects (reduce |delta| or simplify the profile)`
+- **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.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

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

@@ -16,9 +16,11 @@ 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(--pf-surface); border: 1px solid var(--pf-border); border-radius: 14px;
+  background: var(--pf-surface); border: 1px solid var(--pf-border); border-radius: 16px;
   padding: 14px; color: var(--pf-text);
-  box-shadow: 0 4px 6px -1px rgb(0 0 0 / .1), 0 2px 4px -2px rgb(0 0 0 / .1);
+  /* shadow-lg, matching the partforge-cloud chat pane so the two floating
+     panes read as siblings (was the smaller shadow-md). */
+  box-shadow: 0 10px 15px -3px rgb(0 0 0 / .1), 0 4px 6px -4px rgb(0 0 0 / .1);
 }
 #panel h1 { font-size: 14px; margin: 0 0 2px; color: var(--pf-text-strong); letter-spacing: -0.01em; }
 #panel .sub {

package/src/framework/geometry/polygon.js

@@ -227,3 +227,180 @@ export function circleProfile(r, center = [0, 0], segs = 48) {
   }
   return pts;
 }
+
+// --- offsetPolygon ---------------------------------------------------------
+
+const OFFSET_EPS = 1e-9;
+
+// Fresh copies, consecutive duplicates dropped, closing point (== first) dropped.
+function dedupePoints(points) {
+  const out = [];
+  for (const p of points) {
+    const last = out[out.length - 1];
+    if (!last || Math.hypot(p[0] - last[0], p[1] - last[1]) > OFFSET_EPS) out.push([p[0], p[1]]);
+  }
+  while (out.length > 1 &&
+    Math.hypot(out[0][0] - out[out.length - 1][0], out[0][1] - out[out.length - 1][1]) <= OFFSET_EPS) out.pop();
+  return out;
+}
+
+function polySignedArea(pts) {
+  let a = 0;
+  for (let i = 0; i < pts.length; i++) {
+    const [x1, y1] = pts[i], [x2, y2] = pts[(i + 1) % pts.length];
+    a += x1 * y2 - x2 * y1;
+  }
+  return a / 2;
+}
+
+// True where segments a-b and c-d properly cross. Shared endpoints and collinear
+// touches don't count — adjacent edges always share a vertex, and the collinear
+// case is degenerate input the dedupe/straight-vertex paths already absorb.
+function segmentsCross(a, b, c, d) {
+  const orient = (p, q, r) => (q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]);
+  return orient(a, b, c) * orient(a, b, d) < 0 && orient(c, d, a) * orient(c, d, b) < 0;
+}
+
+// True where p lies strictly inside segment a-b (not at either endpoint) —
+// a degenerate touch that segmentsCross's proper-crossing test doesn't see.
+function pointOnSegment(p, a, b) {
+  const cross = (b[0] - a[0]) * (p[1] - a[1]) - (b[1] - a[1]) * (p[0] - a[0]);
+  if (Math.abs(cross) > OFFSET_EPS) return false;
+  const dot = (p[0] - a[0]) * (b[0] - a[0]) + (p[1] - a[1]) * (b[1] - a[1]);
+  const lenSq = (b[0] - a[0]) ** 2 + (b[1] - a[1]) ** 2;
+  return dot > OFFSET_EPS && dot < lenSq - OFFSET_EPS;
+}
+
+// O(n²) simplicity test — trivial at profile point counts (tens to hundreds).
+function isSimplePolygon(pts) {
+  const n = pts.length;
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      if (j === i + 1 || (i === 0 && j === n - 1)) continue;   // adjacent edges share a vertex
+      const [a, b] = [pts[i], pts[(i + 1) % n]], [c, d] = [pts[j], pts[(j + 1) % n]];
+      if (segmentsCross(a, b, c, d)) return false;
+      // A vertex landing exactly on a non-adjacent edge is also a self-touch —
+      // e.g. an inset waist pinching two opposite edges together.
+      if (pointOnSegment(a, c, d) || pointOnSegment(b, c, d) ||
+          pointOnSegment(c, a, b) || pointOnSegment(d, a, b)) return false;
+    }
+  }
+  return true;
+}
+
+// Intersection of two infinite lines given as point + unit direction; null if parallel.
+function lineIntersect(p, dp, q, dq) {
+  const denom = dp[0] * dq[1] - dp[1] * dq[0];
+  if (Math.abs(denom) < OFFSET_EPS) return null;
+  const t = ((q[0] - p[0]) * dq[1] - (q[1] - p[1]) * dq[0]) / denom;
+  return [p[0] + dp[0] * t, p[1] + dp[1] * t];
+}
+
+// Offset a profile by `delta` mm: positive grows material outward, negative
+// insets. `profile` is a CCW [[x,y],…] point list (either winding accepted,
+// output always CCW) or an {outer, holes} region — regions offset as material:
+// outer by +delta, holes by −delta, so a +0.2 clearance on a cut region loosens
+// the whole cut. Corners where the offset edges diverge fill per `corners`:
+// "round" (arc of radius |delta| about the original vertex, `segs` segments —
+// the true Minkowski clearance), "chamfer" (the arc's chord), or "sharp" (true
+// miter, falling back to chamfer past a miter length of 2·|delta|). Where
+// offset edges cross (reflex on outset, convex on inset) they trim to their
+// intersection regardless of style. Simple polygon in, simple polygon out:
+// a result that self-intersects or vanishes THROWS (greppable errors below)
+// rather than returning degenerate geometry — offsets that would split a
+// region (dumbbell insets) are out of scope. Pure and deterministic; usable in
+// derive() and build() alike. See AUTHORING-PARTS.md "Profiles & patterns".
+export function offsetPolygon(profile, delta, opts = {}) {
+  const { corners = "round", segs = 8 } = opts;
+  if (profile !== null && typeof profile === "object" && !Array.isArray(profile)) {
+    if (!Array.isArray(profile.outer)) throw new Error("offsetPolygon: profile must be a point list or {outer, holes}");
+    const region = { outer: offsetPolygon(profile.outer, delta, opts) };
+    if (profile.holes) region.holes = profile.holes.map((h) => offsetPolygon(h, -delta, opts));
+    return region;
+  }
+  if (!Array.isArray(profile)) throw new Error("offsetPolygon: profile must be a point list or {outer, holes}");
+  if (typeof delta !== "number" || !Number.isFinite(delta)) throw new Error("offsetPolygon: delta must be a finite number");
+  if (corners !== "round" && corners !== "chamfer" && corners !== "sharp")
+    throw new Error('offsetPolygon: corners must be "round" | "chamfer" | "sharp"');
+  for (const p of profile)
+    if (!Array.isArray(p) || !Number.isFinite(p[0]) || !Number.isFinite(p[1]))
+      throw new Error("offsetPolygon: coordinates must be finite numbers");
+
+  const pts = dedupePoints(profile);
+  if (pts.length < 3) throw new Error("offsetPolygon: need at least 3 points");
+  if (polySignedArea(pts) < 0) pts.reverse();                     // work in CCW
+  if (!isSimplePolygon(pts)) throw new Error("offsetPolygon: input polygon self-intersects");
+  if (delta === 0) return pts;
+
+  // Each edge i (pts[i] → pts[i+1]): unit direction and endpoints displaced
+  // along the outward normal (CCW ⇒ outward = (dy, −dx)).
+  const n = pts.length, dir = [], off = [];
+  for (let i = 0; i < n; i++) {
+    const p = pts[i], q = pts[(i + 1) % n];
+    const len = Math.hypot(q[0] - p[0], q[1] - p[1]);
+    const d = [(q[0] - p[0]) / len, (q[1] - p[1]) / len];
+    const mx = d[1] * delta, my = -d[0] * delta;
+    dir.push(d);
+    off.push([[p[0] + mx, p[1] + my], [q[0] + mx, q[1] + my]]);
+  }
+
+  // Join edge (i−1)'s offset to edge i's offset at each original vertex. Also
+  // track each edge's start/end parameter along its own direction: a heavily
+  // over-inset edge can be trimmed from both ends past its own start and still
+  // trace out a simple-looking (but phantom, reflected) loop — isSimplePolygon
+  // only catches crossing segments, not a reversed edge, so that case needs
+  // this separate check below.
+  const out = [];
+  const tStart = new Array(n), tEnd = new Array(n);
+  const paramOf = (i, p) => (p[0] - off[i][0][0]) * dir[i][0] + (p[1] - off[i][0][1]) * dir[i][1];
+  const join = (prev, i, point) => {
+    out.push(point);
+    tEnd[prev] = paramOf(prev, point);
+    tStart[i] = paramOf(i, point);
+  };
+  for (let i = 0; i < n; i++) {
+    const prev = (i + n - 1) % n, V = pts[i];
+    const endPrev = off[prev][1], startNext = off[i][0];
+    const cross = dir[prev][0] * dir[i][1] - dir[prev][1] * dir[i][0];
+
+    if (Math.abs(cross) < OFFSET_EPS) { join(prev, i, endPrev); continue; }   // straight vertex
+
+    if (cross * delta < 0) {                                             // offset edges cross → trim
+      const m = lineIntersect(off[prev][0], dir[prev], off[i][0], dir[i]);
+      join(prev, i, m ?? endPrev);
+      continue;
+    }
+
+    // Offset edges diverge → fill the wedge per style.
+    if (corners === "sharp") {
+      const m = lineIntersect(off[prev][0], dir[prev], off[i][0], dir[i]);
+      if (m && Math.hypot(m[0] - V[0], m[1] - V[1]) <= 2 * Math.abs(delta)) { join(prev, i, m); continue; }
+      out.push(endPrev, startNext);                                      // past the miter limit → chamfer
+      tEnd[prev] = paramOf(prev, endPrev); tStart[i] = paramOf(i, startNext);
+    } else if (corners === "chamfer") {
+      out.push(endPrev, startNext);
+      tEnd[prev] = paramOf(prev, endPrev); tStart[i] = paramOf(i, startNext);
+    } else {                                                             // round: short arc about V
+      tEnd[prev] = paramOf(prev, endPrev); tStart[i] = paramOf(i, startNext);
+      const a0 = Math.atan2(endPrev[1] - V[1], endPrev[0] - V[0]);
+      let dA = Math.atan2(startNext[1] - V[1], startNext[0] - V[0]) - a0;
+      while (dA <= -Math.PI) dA += 2 * Math.PI;
+      while (dA > Math.PI) dA -= 2 * Math.PI;
+      const r = Math.abs(delta);
+      for (let s = 0; s <= segs; s++) {
+        const a = a0 + (dA * s) / segs;
+        out.push([V[0] + r * Math.cos(a), V[1] + r * Math.sin(a)]);
+      }
+    }
+  }
+
+  for (let i = 0; i < n; i++)
+    if (tEnd[i] < tStart[i] - OFFSET_EPS) throw new Error("offsetPolygon: offset collapses the polygon");
+
+  const cleaned = dedupePoints(out);
+  if (cleaned.length < 3 || polySignedArea(cleaned) <= OFFSET_EPS)
+    throw new Error("offsetPolygon: offset collapses the polygon");
+  if (!isSimplePolygon(cleaned))
+    throw new Error("offsetPolygon: offset result self-intersects (reduce |delta| or simplify the profile)");
+  return cleaned;
+}

package/src/parts/planter.js

@@ -9,6 +9,8 @@
 // pens, the drainage hole is a real functional choice (planter vs. cup), and dropping
 // Wall below the fdm-pla 1.2 mm minimum trips partforge's min-wall warning.
 
+import { offsetPolygon } from "partforge/geometry";
+
 // A regular n-gon of circumradius R, in the XY plane, as [[x,y],…] for k.prism.
 // A small rotation seats a flat edge toward the viewer so even-sided shapes read right.
 const ngon = (R, n) => {
@@ -69,14 +71,18 @@ export default {
   // build needs, sized so the wall stays even (see build()).
   derive: (p) => {
     const Rout = p.dia / 2;
-    // Offset the inner polygon inward by `wall` along the FACE normals, not the radius:
-    // for a regular n-gon an edge offset of `wall` shrinks the circumradius by
-    // wall / cos(π/n). This keeps the perpendicular wall = `wall` on every flat.
-    // clamp only matters if wall is set past the slider bounds via the API
-    const Rin = Math.max(Rout - p.wall / Math.cos(Math.PI / p.facets), 1);
+    // Inset the outer polygon inward by `wall` along the FACE normals via
+    // offsetPolygon (sharp corners keep the n-gon exact — see the closed-form
+    // pin in test/offset-polygon.test.js). Cap the wall so the inset can never
+    // collapse below circumradius 1 — same clamp as the old closed form (only
+    // matters if wall is set past the slider bounds via the API).
+    const wall = Math.min(p.wall, (Rout - 1) * Math.cos(Math.PI / p.facets));
+    const outerPts = ngon(Rout, p.facets);
+    const innerPts = offsetPolygon(outerPts, -wall, { corners: "sharp" });
+    const Rin = Math.hypot(innerPts[0][0], innerPts[0][1]);   // read back from the geometry
     return {
-      outerPts: ngon(Rout, p.facets),
-      innerPts: ngon(Rin, p.facets),
+      outerPts,
+      innerPts,
       // Inner taper that holds the wall constant top-to-bottom even as the body flares:
       // pick it so inner_radius(top) = outer_radius(top) − wall.
       innerTaper: 1 + (Rout * (p.taper - 1)) / Rin,