partforge 0.111.1 → 0.113.0

package/docs/AUTHORING-PARTS.md

@@ -430,12 +430,23 @@ k.prism({ points: roundedProfile(bracketOutline, 3), h: 4 });  // true CIRCLE co
 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])
+// A mounting tab: square at the root, semicircular at the tip. The arc names the
+// point it must pass THROUGH (its apex), so its direction can never flip — there is
+// no sweep sign to get wrong, and no Math.cos loop to write.
+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 });
+
+// A free-form curved side (exact on STEP, faceted at mesh LOD):
+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: tab, h: 3 });
+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 } });
@@ -448,8 +459,7 @@ every corner of a CCW polygon (per-corner radius clamped so neighbouring arcs ne
 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[])`
 rounds corners the same way but keeps them **mathematically true** — it carries the arc
-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
+symbolically so STEP export gets real circular edges. Use it for `prism`/`extrude`/`loft` alike (loft lifts arc rings into its curve mode). 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). `offsetPolygon(profile, delta, { corners?, segs? })` offsets a
 point-list polygon or `{ outer, holes }` region by `delta` mm — positive grows material,
@@ -462,6 +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. `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
@@ -1416,6 +1427,7 @@ Three rules worth internalizing before reaching for any of this:
   on a narrow profile can produce arcs that cross the far side). `validateProfile`
   never throws, so it's cheap to call after any edit and inspect `issues` before
   committing to the result.
+  Since 0.112 the kernel runs it for you on the way IN to `extrude`/`prism`/`revolve`/`sweep`/`loft`/`shape2d` and reports each crossing as a build warning ([profile-self-intersects](ERROR-PATTERNS.md#profile-self-intersects)); the manual call is for inspecting a result BEFORE committing to it.
 - **Guard vanishing features with `isEmpty()`.** A boolean chain can legitimately
   produce an *empty* shape (an `intersect` of shapes a parameter drove apart, a `cut`
   that removed everything). The empty shape is a fine 2-D value — further booleans,
@@ -3485,6 +3497,13 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
 - **`build` is a pure function of `(k, p, d)`** — impurity silently defeats the geometry
   cache ([impure-build-stale-preview](ERROR-PATTERNS.md#impure-build-stale-preview)).
 - **Units are millimetres** throughout.
+- **Never sample an arc into points by hand.** A `Math.cos` loop hides the sweep direction
+  in a sign, and a wrong sign produces a self-crossing outline that builds with inverted
+  fill and no error — only a `profile-self-intersects` warning
+  ([profile-self-intersects](ERROR-PATTERNS.md#profile-self-intersects)). Build curved
+  outlines with `pathProfile().arcTo(to, via)`, `roundedProfile`, `filletPolygon`,
+  `slotPolygon`, `ringSectorPolygon` and `circleProfile`; mirror a symmetric half with
+  `mirrorProfile`.
 - **Preview vs print quality:** Manifold bakes segment counts in at primitive creation,
   so builds are quality-agnostic; the export path uses a separate high-res "print" kernel.
 - **Display placement is view-independent**; only `place(..., { purpose: "export" })` may

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())`
@@ -773,7 +779,7 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** *(partforge ≥ 0.69.)* A fillet/chamfer the geometry (or its own selector) defeats no longer fails the whole build on either backend: the op returns its input solid unchanged, everything downstream still applies, and the skip is recorded on the build result's `warnings` (`kernel.takeBuildWarnings()` / the `meshes` message's `warnings: [{part, message}]`).
 - **Fix:** Read the parenthesized reason. A bad selector (unknown plane, wrong `at` height) is a part bug — fix the selector. A geometry-defeated blend usually wants a smaller magnitude or simpler input (clamp per the entry above), or the feature deliberately left off. Treat the warning as "this feature did not land", never as a cosmetic note — the shape on screen genuinely lacks it.
 
-  The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
+  The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. The same channel also carries [profile-self-intersects](#profile-self-intersects) — a hand-authored outline that crosses itself and built with inverted fill. A build result's `warnings` is the complete list of what the part asked for and did not get — or, for `profile-self-intersects`, asked for and should not have.
 
 ## control-default-not-literal
 
@@ -811,6 +817,12 @@ between the Manifold preview and the OCCT STEP export.
 - **Cause:** OCCT's heightfield path triangulates the depth-map grid the same way Manifold does, then goes mesh → STL → B-rep (`StlAPI_Reader` + `ShapeUpgrade_UnifySameDomain` + `MakeSolid`) so the result can boolean/fillet/export to STEP like any other B-rep shape. That sewing step can fail outright on a large or high-frequency grid — before failure, a triangle count above the plan's measured threshold already emits a slow-sew/large-STEP warning on the same build (see `feature-skipped-warning`'s sibling channel), and this is what happens when the grid is pushed further still.
 - **Fix:** Raise `pitch` on the `k.heightfield` call to coarsen the grid (fewer triangles to sew), or keep this sub-part on the Manifold backend (drop the `meta.backend`/CAD-op pin forcing OCCT) — Manifold's heightfield path never sews through OCCT, so it has no equivalent failure mode. STEP export specifically needs OCCT, so a part that must export a relief to STEP has to bring the triangle count under the sewable range rather than avoid OCCT.
 
+## profile-self-intersects
+
+- **Symptom:** The build succeeds and its result carries a warning like `extrude: profile self-intersects near (12.3400, -6.3800) — the outline crosses itself, so the fill inverts there …` (also `prism: profile …`, `revolve: profile …`, `sweep: profile …`, `loft: ring 2 …`, `shape2d: profile …`), and the rendered part has a cavity, a missing lobe, or a sliver where a curved edge should be. Identical text on both backends.
+- **Cause:** *(partforge ≥ 0.112.)* A hand-authored 2-D profile (a point list, a `pathProfile` contour, a `{outer, holes}` region — handed to a factory op, to `k.shape2d`, or as a `Shape2D` boolean operand) crosses itself. Manifold fills a point ring even-odd, so the crossing quietly inverts the fill on one side instead of failing. The usual author of the crossing is an arc sampled into points by hand (a `Math.cos` loop) whose sweep sign or endpoint order is wrong, or a mirrored half whose point order was not reversed. The kernel now runs `validateProfile` on the way in and reports each crossing on the build result's `warnings`; a `Shape2D` is not re-validated, `text2d`/`vector2d` lifts are trusted, and a profile over 4000 segments is skipped (for `loft`, the ceiling is the sum over all its rings). At most **three** crossings are reported per profile — the third reads `… (and N more crossings on this profile)` — so one badly-drawn star cannot evict every other warning in the build. A hole whose edge touches or runs along its outer is **not** reported: that builds exactly as drawn, and only a contour crossing itself inverts the fill.
+- **Fix:** Rebuild the curved parts of the outline with `pathProfile(start).lineTo(p).arcTo(to, via).close()` — a three-point arc sweeps through `via`, so its direction cannot flip — or with the `partforge/geometry` helpers (`roundedProfile`, `filletPolygon`, `slotPolygon`, `ringSectorPolygon`, `circleProfile`); build a symmetric half once and `mirrorProfile` it rather than writing the mirror by hand. Confirm with `validateProfile(profile).ok` before extruding. The reported coordinate is in the profile's own frame (before any `rotate`/`at`).
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -704,6 +704,25 @@ the helpers come along unmodified. (`test/kernel-contract.test.js` asserts every
   `arcTo` / `cubicTo` / `close`); cubic segments become exact B-rep on OCCT and
   facet at mesh LOD on Manifold.
 
+**Profile validation on the way in** (0.112). `prism`, `extrude`, `revolve`, `sweep`,
+`loft` (per ring) and `shape2d` (including boolean operands) run `validateProfile` on a
+hand-authored profile — a point list, a `{start, segments}` contour, a `{outer, holes}`
+region — and record each `self-intersection` issue on the build's warnings
+(`takeBuildWarnings()`), prefixed `<op>: profile` / `loft: ring <i>`, deduplicated per
+drain. It never throws and never changes the built geometry; a `Shape2D` is never
+re-validated. Three bounds keep it cheap and keep its output readable: a profile over
+4000 contour segments (counted as authored, before curve sampling) is skipped; `loft`
+applies that ceiling to the **sum** over its rings, not per ring, so a many-ring loft
+(everything `loftSmooth` produces) is skipped whole rather than validated ring by ring on
+every rebuild; and at most **three** crossings are reported per profile, the third
+carrying `(and N more crossings on this profile)`. A contact between two contours of one
+region — a hole drawn flush with its outer — is **not** reported: it builds exactly as
+drawn, so `validateProfile` tags it `crosses` and the warning skips it. This lives in the
+shared front (`profile-warnings.js`), so both backends emit identical text — a host
+implementing the kernel gets it by wiring one warner (build it beside the warnings list,
+expose `_warnProfile`, pass `warnProfile` to the Shape2D factory, reset it on drain). Not
+a contract-version change (additive, the import-op precedent).
+
 ### 2-D editing ops
 
 The **2-D editing ops** are the free-function twins of the `Shape2D` transforms,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.111.1",
+  "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/contour-ops.js

@@ -1109,9 +1109,16 @@ function selfIntersectionInRegion(contours) {
         if (!pt) continue;
         const first = eI.contourIndex <= eJ.contourIndex ? eI : eJ;
         const other = first === eI ? eJ : eI;
-        const crossSuffix = other.contourIndex === first.contourIndex ? "" : ` (or crosses contour ${other.contourIndex})`;
+        const crossContour = other.contourIndex !== first.contourIndex;
+        const crossSuffix = crossContour ? ` (or crosses contour ${other.contourIndex})` : "";
         issues.push({
           type: "self-intersection", contourIndex: first.contourIndex, segmentIndex: first.segmentIndex, point: pt,
+          // `crosses` (present ONLY on a contact between two contours of this
+          // region — an outer and its own hole, typically a hole drawn flush with
+          // the outer wall) separates that case from a contour crossing ITSELF.
+          // Both are reported; only the latter inverts the fill, so the build
+          // warning in profile-warnings.js reports the ones without this key.
+          ...(crossContour ? { crosses: other.contourIndex } : {}),
           message: `contour ${first.contourIndex} self-intersects${crossSuffix} near (${pt[0].toFixed(4)}, ${pt[1].toFixed(4)})`,
         });
         flagged.add(eI.contourIndex); flagged.add(eJ.contourIndex);

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

@@ -158,7 +158,7 @@ export function finishKernel(k) {
       : k.loft({ rings: smoothLoftRings(sections, { stations, samples, closed }), ...(shading ? { shading } : {}), closed });
   };
 
-  for (const [op, { toArgs, check }] of Object.entries(KERNEL_OP_SPECS)) {
+  for (const [op, { toArgs, check, warn }] of Object.entries(KERNEL_OP_SPECS)) {
     const raw = k[op];
     if (!raw) continue;
     k[op] = (...a) => {
@@ -167,6 +167,10 @@ export function finishKernel(k) {
       // degrade has to reach the build's warning list, not just the console.
       const pos = a.length === 1 && isPlainOptions(a[0]) ? toArgs(a[0], k._recordWarning) : a;
       check?.(...pos);
+      // A self-crossing hand-authored profile is a warning, never a failure
+      // (profile-warnings.js). Runs after `check` so a rejected input reports
+      // the op's own error, and before the backend so both backends warn alike.
+      warn?.(k._warnProfile, ...pos);
       return raw(...pos);
     };
   }
@@ -231,7 +235,9 @@ export function finishKernel(k) {
     const parsed = resolveFont(font);
     const regions = textGlyphs(parsed, string, { size, align, valign, lineHeight, tracking, kerning });
     if (regions.length === 0) throw new Error("text2d: string produced no glyph geometry (empty or all-whitespace?)");
-    return regions.map((r) => k.shape2d(r)).reduce((a, b) => a.union(b));
+    // Glyph regions are machine-resolved by curve-fill — trusted, so a text
+    // part does not pay profile validation per glyph per rebuild.
+    return regions.map((r) => k.shape2d.trusted(r)).reduce((a, b) => a.union(b));
   };
 
   // 2-D vector art as a Shape2D. Backend-agnostic for the same reason text2d is:
@@ -250,8 +256,9 @@ export function finishKernel(k) {
       throw new Error("vector2d: first argument must be the name of an entry in the part's `vectors` field");
     const doc = k._vectors.get(name);
     if (!doc) throw new Error(`vector2d: unknown vector "${name}" — declare it in the part's \`vectors\` field`);
+    // vector documents carry their own validation (VECTOR-FORMAT.md); trusted lift
     const lift = (regions, measureAgainst = regions) =>
-      placeRegions(regions, doc.units, opts, { measureAgainst, name }).map((r) => k.shape2d(r)).reduce((a, b) => a.union(b));
+      placeRegions(regions, doc.units, opts, { measureAgainst, name }).map((r) => k.shape2d.trusted(r)).reduce((a, b) => a.union(b));
     if (opts.shape != null) {
       const entry = doc.shapes.get(opts.shape);
       if (!entry) {

package/src/framework/geometry/kernel.js

@@ -146,11 +146,11 @@ export const ROUTED_CAD_OPS = ["shell"];
  * @property {(o:{rMajor:number,rMinor:number}) => Solid} torus   centered at origin, tube centerline in the z=0 plane; 0 < rMinor < rMajor; options-only
  * @property {(o:{size:number[],center?:boolean,round:number|{side?:number,top?:number,bottom?:number}}) => Solid} roundedBox   selective edge rounding (side = vertical edges, top/bottom = rims); 0 < side < rim clamps rims down to side with a console.warn; options-only
  * @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 for now (see file header)
- * @property {(o:{points:number[][],h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted for now (see file header)
- * @property {(o:{profile:number[][]|{outer:number[][],holes?:number[][][]},h:number,twist?:number,scaleTop?:number,bevel?:number|{bottom?:number,top?:number}}) => Solid} extrude   polygon-with-holes region from z=0; bevel = 45° rim bevel (any profile form incl. Shape2D, materialized to point rings; no twist/scaleTop); legacy (profile,h,opts) accepted for now (see file header)
+ * @property {(o:{points:number[][]|{start:number[],segments:object[]},h:number,twist?:number,scaleTop?:number}) => Solid} prism   extrude polygon from z=0; legacy (points,h,opts) accepted for now (see file header)
+ * @property {(o:{profile:number[][]|{start:number[],segments:object[]}|{outer:number[][],holes?:number[][][]}|Shape2D,h:number,twist?:number,scaleTop?:number,bevel?:number|{bottom?:number,top?:number}}) => Solid} extrude   polygon-with-holes region from z=0; bevel = 45° rim bevel (any profile form incl. Shape2D, materialized to point rings; no twist/scaleTop); legacy (profile,h,opts) accepted for now (see file header)
  * @property {(o:{rings:{polygon?:number[][]|{start:number[],segments:object[]}|Shape2D,sides?:number,radius?:number,z:number,rotate?:number,scale?:number|number[]}[],ruled?:boolean,closed?:boolean,shading?:"smooth"|"faceted"}) => Solid} loft   stack polygon cross-sections; polygon accepts point lists, curve contours, or hole-free Shape2D; shading overrides facet-vs-smooth shading inference; legacy (rings,opts) accepted for now (see file header)
  * @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 for now (see file header)
- * @property {(o:{profile:number[][],degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted for now (see file header)
+ * @property {(o:{profile:number[][]|Shape2D,degrees?:number}) => Solid} revolve   revolve a lathe profile [[r,z],…] around Z; legacy (points,opts) accepted for now (see file header)
  * @property {(o:{pathR:number,profileR:number,pitch:number,turns:number,z0:number,lefthand:boolean}) => Solid} helixSweptTube
  * @property {(o:{profile:number[][],pitch:number,turns:number,lefthand?:boolean}) => Solid} screwSweep   screw-motion sweep of an axial [[r,z]] profile — threads; options-only
  * @property {(o:{d:number,pitch:number,turns:number,depth?:number,crest?:number,lefthand?:boolean,rootSink?:number,overshoot?:number}) => Solid} tappedBore   compound: a tapped hole as ONE cut tool — bore plus thread, root sunk inside the bore so the two never share a face

package/src/framework/geometry/manifold-backend.js

@@ -13,6 +13,7 @@ import { addSugar } from "./solid-sugar.js";
 import { makeShape2dFactory } from "./shape2d.js";
 import { offsetRegions } from "./contour-offset.js";
 import { finishKernel } from "./kernel-front.js";
+import { makeProfileWarner } from "./profile-warnings.js";
 import { meshToStl } from "./mesh-stl.js";
 import { creasedNormals } from "./creased-normals.js";
 import { loftShadingPolicy, SMOOTH, BLEND } from "./shading-policy.js";
@@ -116,6 +117,9 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
   // every degrade in the build lands in one drainable list rather than only in
   // the console.
   const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
+  // Profile-validity warnings (profile-warnings.js): one warner per kernel so a
+  // self-crossing profile built six times records ONE line; reset per drain.
+  const profileWarner = makeProfileWarner(recordWarning);
   const skipFeature = (key, op, magnitude, err) => {
     const msg = `${op} ${magnitude} failed (${String(err?.message || err).slice(0, 200)}) — feature skipped, edges left sharp`;
     skippedOps.set(key, msg);
@@ -166,6 +170,7 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     extrude: (o) => kernel.extrude(o),
     revolve: (o) => kernel.revolve(o),
     recordWarning,
+    warnProfile: profileWarner.warn,
   });
   // Lazy CrossSection materialization, memoized through the solid cache by content
   // hash + LOD: the same shape extruded twice (or extruded and revolved) tessellates
@@ -831,10 +836,12 @@ export function createManifoldKernel(wasm, { quality = "preview" } = {}) {
     // Drain the feature-skip warnings recorded since the last drain (see
     // buildWarnings above). jobs.js calls this per sub-part so a warning is
     // attributed to the sub-part whose build recorded it.
-    takeBuildWarnings: () => buildWarnings.splice(0),
+    takeBuildWarnings: () => { profileWarner.reset(); return buildWarnings.splice(0); },
     // Internal (underscore = not the contract surface): the recorder shared,
     // backend-neutral helpers report their own degrades through.
     _recordWarning: recordWarning,
+    // Internal: the profile-validity warner the kernel front's `warn` slot calls.
+    _warnProfile: profileWarner.warn,
     // Free every WASM object created since the last cleanup EXCEPT solids the cache
     // still pins (they must survive for the next build to resume from them).
     cleanup: () => { for (const o of tracked) if (!cache.isPinned(o)) o.delete?.(); tracked.length = 0; },

package/src/framework/geometry/occt-backend.js

@@ -22,6 +22,7 @@ import { toFaceFinder } from "./face-selector.js";
 import { addSugar } from "./solid-sugar.js";
 import { makeShape2dFactory } from "./shape2d.js";
 import { finishKernel } from "./kernel-front.js";
+import { makeProfileWarner } from "./profile-warnings.js";
 import { createOcctRepair } from "./occt-repair.js";
 import { occtRoundAll } from "./occt-roundall.js";
 import { classifyFaceGroups } from "./feature-attribution.js";
@@ -119,6 +120,9 @@ export function createOcctKernel(replicad) {
   // Manifold backend's fillet/chamfer degradation.
   const buildWarnings = [];
   const recordWarning = (msg) => { buildWarnings.push(msg); console.warn(`partforge: ${msg}`); };
+  // Profile-validity warnings (profile-warnings.js): one warner per kernel so a
+  // self-crossing profile built six times records ONE line; reset per drain.
+  const profileWarner = makeProfileWarner(recordWarning);
   // The raw OCCT instance, for the coincident-boolean guard (occt-coincidence.js).
   // Absent (older replicad, or a boot path that skipped setOC) the guard is a no-op —
   // detection is an upgrade, never a dependency.
@@ -534,6 +538,7 @@ export function createOcctKernel(replicad) {
     extrude: (o) => kernel.extrude(o),
     revolve: (o) => kernel.revolve(o),
     recordWarning,
+    warnProfile: profileWarner.warn,
   });
   // Lazy Drawing materialization for the kernel ops that need one. drawingFromRegions
   // draws a FRESH Drawing on every call, so callers never need to .clone() the result
@@ -797,10 +802,12 @@ export function createOcctKernel(replicad) {
     resetCacheStats: () => cache.resetStats(),
     // Drain the feature-skip warnings recorded since the last drain — the
     // Manifold backend's channel, mirrored (see occt-repair.js for the sources).
-    takeBuildWarnings: () => buildWarnings.splice(0),
+    takeBuildWarnings: () => { profileWarner.reset(); return buildWarnings.splice(0); },
     // Internal: the recorder shared, backend-neutral helpers report through
     // (rim-bevel, roundedBox's clamp, Shape2D corner-op clamps).
     _recordWarning: recordWarning,
+    // Internal: the profile-validity warner the kernel front's `warn` slot calls.
+    _warnProfile: profileWarner.warn,
   });
   return kernel;
 }

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

@@ -5,7 +5,10 @@
 // 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.
+// both spellings of a call share one cache entry. Geometry-free by design — it is
+// inside partforge/lint's import closure (test/lint-purity.test.js), so it may not
+// import profile-warnings.js either: that reaches paper.js through contour-ops.js.
+// The `warn` slots take everything they need on the warner they are handed.
 
 export function isPlainOptions(x) {
   if (x === null || typeof x !== "object") return false;
@@ -250,11 +253,15 @@ export const KERNEL_OP_SPECS = {
   cylinder: { toArgs: cylinderArgs },
   sphere:   { toArgs: sphereArgs },
   box:      { toArgs: boxArgs },
-  prism:    { toArgs: prismArgs, check: checkScaleTop("prism") },
+  // `warn` (finishKernel calls it after `check`, with the kernel's profile
+  // warner first) reports a self-crossing hand-authored profile as a build
+  // warning — the build proceeds; see profile-warnings.js.
+  prism:    { toArgs: prismArgs, check: checkScaleTop("prism"),
+    warn: (warnProfile, points) => warnProfile?.("prism: profile", points) },
   extrude:  { toArgs: extrudeArgs, check: (profile, h, opts) => {
     checkNonEmptyProfile("extrude", profile);
     checkScaleTop("extrude")(profile, h, opts);
-  } },
+  }, warn: (warnProfile, profile) => warnProfile?.("extrude: profile", profile) },
   revolve:  { toArgs: revolveArgs, check: (pts) => {
     checkNonEmptyProfile("revolve", pts);
     if (pts && pts._shape2d) {
@@ -265,10 +272,32 @@ export const KERNEL_OP_SPECS = {
       if (pts.boundingBox().min[0] < -1e-5) throw new Error("revolve: profile radius must be ≥ 0");
       return;
     }
+    // revolve takes a lathe POINT LIST or a Shape2D — it has no contour path, and a
+    // {start, segments} contour used to reach the loop below and die as a bare
+    // "pts is not iterable" TypeError. Name the real problem instead.
+    if (!Array.isArray(pts) || !pts.every((p) => Array.isArray(p)))
+      throw new Error("revolve: profile must be an [[r, z], …] point list or a Shape2D (a {start, segments} contour is not accepted — lift it with k.shape2d first)");
     for (const [r] of pts) if (r < 0) throw new Error("revolve: profile radius must be ≥ 0");
+  }, warn: (warnProfile, pts) => warnProfile?.("revolve: profile", pts) },
+  // The loft ceiling is an AGGREGATE over the rings, never per ring: loftSmooth
+  // densifies a handful of control sections into dozens of rings, each of which
+  // sits comfortably under the per-profile bound, so a per-ring ceiling let a
+  // many-ring loft revalidate the whole stack on every rebuild (+30% measured on
+  // src/parts/propeller.js). Sum first; past the ceiling the whole loft is skipped.
+  loft:     { toArgs: loftArgs, warn: (warnProfile, rings) => {
+    if (!Array.isArray(rings) || !warnProfile) return;
+    const authored = (r) => r?.polygon && !r.polygon._shape2d;
+    // `segmentCount`/`maxSegments` ride on the warner (makeProfileWarner) rather
+    // than being imported, to keep this module geometry-free — see the header. A
+    // warner without them can still warn; it just cannot bound the whole loft.
+    if (warnProfile.segmentCount) {
+      let total = 0;
+      for (const r of rings) if (authored(r)) total += warnProfile.segmentCount(r.polygon);
+      if (total > warnProfile.maxSegments) return;
+    }
+    rings.forEach((r, i) => { if (authored(r)) warnProfile(`loft: ring ${i}`, r.polygon); });
   } },
-  loft:     { toArgs: loftArgs },
-  sweep:    { toArgs: sweepArgs },
+  sweep:    { toArgs: sweepArgs, warn: (warnProfile, profile) => warnProfile?.("sweep: profile", profile) },
   boredCylinder:  { toArgs: passThrough("boredCylinder", ["od", "h", "bore"], ["od", "h", "bore"]) },
   helixSweptTube: { toArgs: passThrough("helixSweptTube",
     ["pathR", "profileR", "pitch", "turns", "z0", "lefthand"], ["pathR", "profileR", "pitch", "turns"]) },

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/src/framework/geometry/profile-warnings.js

@@ -0,0 +1,93 @@
+// Profile-validity warnings: the pure half of the "your outline crosses itself"
+// signal. A hand-authored 2-D profile (a point list, a pathProfile contour, a
+// {outer, holes} region) that self-intersects builds WITHOUT error on both
+// backends — Manifold fills even-odd, so the crossing quietly inverts the fill
+// (a lobe becomes a hole). Nothing told the author. This module turns
+// validateProfile's self-intersection issues into build-warning messages;
+// the kernel front (KERNEL_OP_SPECS' `warn` slot) and the Shape2D factory's
+// liftRegions call it, and each backend owns one warner so a message lands at
+// most once per build (six placements of one bad socket profile = one line).
+//
+// Never throws, never blocks: a profile liftProfile rejects is left for the
+// op's own error path, and a Shape2D is never re-validated (it was validated
+// when it was lifted, and every boolean it went through resolves crossings).
+import { liftProfile, validateProfile } from "./contour-ops.js";
+
+// Contour segments above which validation is skipped, so an unusually dense
+// authored profile can never make this the slowest step of a build. The count is
+// of CONTOUR SEGMENTS as authored, BEFORE curve sampling: the validator expands
+// each curved segment into VALIDATE_SEGS (8) sampled edges, so a curve-heavy
+// profile at the ceiling costs roughly 8× the edges a polyline one does. The
+// ceiling therefore bounds AUTHORED SIZE, not validator work exactly. Authored
+// geometry is expected to sit far below it. `loft` applies it to the SUM over its
+// rings (see op-options.js) — per ring it would not bound a many-ring loft at all.
+export const PROFILE_VALIDATE_MAX_SEGMENTS = 4000;
+
+// Messages emitted per profile. A profile that crosses itself once usually
+// crosses itself many times (a 24-point {24/7} star reports 144), and the host's
+// warning list is short and shared with every other degrade in the build — an
+// unbounded profile would evict all of them. The last message carries the count
+// of the crossings it stands in for.
+export const PROFILE_WARN_MAX_PER_PROFILE = 3;
+
+const COACH =
+  "the outline crosses itself, so the fill inverts there (a lobe becomes a hole, or vice versa). " +
+  "A hand-sampled arc traversed the wrong way is the usual cause; build curved contours with " +
+  "pathProfile().arcTo(to, via) or the partforge/geometry helpers, and check the outline with validateProfile().";
+
+const segmentCount = (regions) =>
+  regions.reduce((n, rg) => n + rg.outer.segments.length + rg.holes.reduce((m, h) => m + h.segments.length, 0), 0);
+
+// Authored contour segments in one profile, before curve sampling. 0 for a
+// Shape2D (never re-validated) and for anything liftProfile rejects (the op's own
+// error path) — both are profiles this module will not validate anyway, so they
+// contribute nothing to a caller summing the ceiling across several profiles.
+export function profileSegmentCount(profile) {
+  if (!profile || profile._shape2d) return 0;
+  try { return segmentCount(liftProfile(profile).regions); } catch { return 0; }
+}
+
+// One message per self-intersection issue, prefixed by the op and role that
+// received the profile (`extrude: profile`, `loft: ring 2`, `shape2d: profile`).
+export function profileWarningMessages(prefix, profile) {
+  if (!profile || profile._shape2d) return [];
+  let lifted;
+  try { lifted = liftProfile(profile); } catch { return []; }
+  if (segmentCount(lifted.regions) > PROFILE_VALIDATE_MAX_SEGMENTS) return [];
+  let result;
+  try { result = validateProfile(profile); } catch { return []; }
+  // `crosses` marks a contact BETWEEN two contours of one region — an outer and
+  // its own hole sharing an edge, the commonest of which is a hole flush with the
+  // outer wall. validateProfile files those under self-intersection, but they
+  // build exactly as drawn and inverted fill is not what happens, so they are not
+  // this warning's subject. Only a contour crossing ITSELF is reported.
+  const crossings = result.issues.filter(
+    (i) => i.type === "self-intersection" && i.crosses === undefined && Array.isArray(i.point));
+  const text = (i) => `${prefix} self-intersects near (${i.point[0].toFixed(4)}, ${i.point[1].toFixed(4)}) — ${COACH}`;
+  const msgs = crossings.slice(0, PROFILE_WARN_MAX_PER_PROFILE).map(text);
+  const more = crossings.length - PROFILE_WARN_MAX_PER_PROFILE;
+  if (more > 0) msgs[msgs.length - 1] += ` (and ${more} more crossings on this profile)`;
+  return msgs;
+}
+
+// A per-kernel warner: `warn` records each distinct message at most once until
+// `reset` (the backend calls reset inside takeBuildWarnings, i.e. per drain).
+export function makeProfileWarner(recordWarning) {
+  const seen = new Set();
+  const warn = (prefix, profile) => {
+    if (typeof recordWarning !== "function") return;
+    for (const msg of profileWarningMessages(prefix, profile)) {
+      if (seen.has(msg)) continue;
+      seen.add(msg);
+      recordWarning(msg);
+    }
+  };
+  // The ceiling and the counter travel WITH the warner because op-options.js's
+  // `loft` slot has to apply them to the SUM over the rings and that module must
+  // stay geometry-free — it sits inside partforge/lint's import closure, which
+  // may reach no geometry module at all (test/lint-purity.test.js), and this one
+  // reaches paper.js through contour-ops.js.
+  warn.segmentCount = profileSegmentCount;
+  warn.maxSegments = PROFILE_VALIDATE_MAX_SEGMENTS;
+  return { reset: () => seen.clear(), warn };
+}

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

@@ -10,7 +10,10 @@ export function addShape2dSugar(s, { shape2d, extrude, revolve }) {
     return regions[0];
   };
   // .regions() → scission: each disjoint region as its own live Shape2D (booleanable further).
-  s.regions = () => s.toRegions().map((r) => shape2d(r));
+  // `trusted`: these regions are this shape's own, already validated when it was
+  // lifted and resolved by every boolean since — re-lifting them untrusted would
+  // re-run profile validation on machine-produced geometry on every call.
+  s.regions = () => s.toRegions().map((r) => shape2d.trusted(r));
   // .extrude({ h, twist?, scaleTop? }) / .revolve({ degrees? }) → Solid. Sugar for
   // k.extrude({ profile: shape, … }) / k.revolve({ profile: shape, … }). Passed as an
   // options object (not positional) so the kernel op's key/required-arg validation still

package/src/framework/geometry/shape2d.js

@@ -49,13 +49,18 @@ const checkProfile = (x) => {
 // occt-backend). Corner ops CLAMP a magnitude the geometry cannot take rather
 // than throwing, and a clamp that only reached the console would leave a caller
 // believing it got the radius it asked for.
-export function makeShape2dFactory({ segs, extrude, revolve, recordWarning }) {
+export function makeShape2dFactory({ segs, extrude, revolve, recordWarning, warnProfile }) {
   // Lift any accepted profile form into stored regions: a live Shape2D is deep-copied out
   // via its own toContours() (value semantics — never alias another shape's storage);
-  // anything else goes through liftProfile + per-ring winding normalization.
-  const liftRegions = (x) => {
+  // anything else goes through liftProfile + per-ring winding normalization. A raw
+  // profile is also the one place a hand-authored outline enters 2-D storage — from
+  // k.shape2d(x) or as a boolean operand — so it is where a self-crossing one is
+  // reported (profile-warnings.js). `trusted` skips that for the kernel's own
+  // machine-resolved lifts (text2d glyphs, vector2d documents).
+  const liftRegions = (x, { trusted = false } = {}) => {
     if (x && x._shape2d) return deepCopy(x._regions);
     checkProfile(x);
+    if (!trusted) warnProfile?.("shape2d: profile", x);
     return liftProfile(x).regions.map(ensureRegionWinding);
   };
 
@@ -99,5 +104,6 @@ export function makeShape2dFactory({ segs, extrude, revolve, recordWarning }) {
     return addShape2dSugar(s, { shape2d, extrude, revolve });
   };
   const shape2d = (profile) => (profile && profile._shape2d ? profile : make(liftRegions(profile)));
+  shape2d.trusted = (profile) => (profile && profile._shape2d ? profile : make(liftRegions(profile, { trusted: true })));
   return shape2d;
 }

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. */