partforge 0.85.2 → 0.85.4

package/docs/ERROR-PATTERNS.md

@@ -529,9 +529,9 @@ Variant literal for a curve-adjacent corner: `filletProfile: corner <i> at (<x>,
 
 ## loftsmooth-samples-out-of-range
 
-- **Symptom:** `loftSmooth: samples must be 8…2048` — possibly without ever passing `samples`.
-- **Cause:** `samples` is clamped to 8…2048. The default is `max(64, largest section)`, so a control section with more than 2048 points pushes the DEFAULT out of range — the throw then names an option the caller never passed.
-- **Fix:** pass a `samples` value in 8…2048, and thin any control section above ~2048 points — `loftSmooth` interpolates a smooth outline through the points, so sections that dense defeat the sparse-sections design (pass the dense rings straight to `k.loft` instead). See the `loftSmooth` row in [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md).
+- **Symptom:** `loftSmooth: samples must be 8…2048` — an explicit `samples` was rejected.
+- **Cause:** `samples` is clamped to 8…2048. The default `max(64, largest section)` caps itself at 2048, so omitting the option never trips this — even when a control section has more than 2048 points.
+- **Fix:** pass a `samples` value in 8…2048, or omit it for the capped default — and thin any control section above ~2048 points: `loftSmooth` interpolates a smooth outline through sparse control points, so sections that dense defeat the sparse-sections design (pass the dense rings straight to `k.loft` instead). See the `loftSmooth` row in [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md).
 
 ## duplicate-preset-name-throws
 

package/docs/KERNEL-CONTRACT.md

@@ -288,7 +288,7 @@ above. All ops return a `Solid`.
 | `sweep({profile, path, closed?, cornerRadius?, ruled?, smooth?})` | Sweep a fixed CCW profile along a polyline with a rotation-minimizing frame; sharp mitered corners, or `cornerRadius` fillets; capped ends. |
 | `helixSweptTube({pathR, profileR, pitch, turns, z0, lefthand})` | Circle of radius `profileR` swept along a helix (e.g. a rope groove). Circular profile on a frenet frame that rolls with the helix — **not for threads**; use `screwSweep`. |
 | `screwSweep({profile, pitch, turns, lefthand})` | Screw-motion sweep of an axial lathe profile `[[r, z], …]` (r ≥ 0) — threads. The profile travels to `(r·cosθ, r·sinθ, z + pitch·θ/2π)`; `h = pitch · turns`. Axial extent must not exceed `pitch` or consecutive turns interpenetrate (throws). A profile spanning exactly `pitch` is **periodic**: first and last radius must agree, and it yields a complete threaded body needing no boolean. Compound: the polar-remapped, densified section extruded with `twist = 360 · turns`, exactly as composed in `kernel-front.js`; a backend may override only for caching, never for different geometry. Options-only. Parity: **within tolerance, not by construction** — both backends receive the identical densified polygon, but the mesh backend facets the twist at its own resolution while the B-rep backend builds an exact spline (`hull`'s parity class). |
-| `loftSmooth({sections, stations?, samples?, shading?, closed?})` | Spline-interpolated loft of ≥2 sparse control sections — loft-style ring specs `{polygon\|sides+radius\|curve contour\|Shape2D, z, rotate?, scale?, sharp?}`; vertex counts **may differ**. A point section may tag `sharp: [indices]` as true corners (integers in `0…points.length-1`, sorted/deduped silently); a curve/`Shape2D` section takes corners implicitly from its non-smooth joints (single-region, hole-free, `loftSmooth:`-prefixed `k.loft` validation) and rejects an explicit `sharp`. Every section must resolve to the **same corner count `m`** (frozen error otherwise); with `m ≥ 1` corner 0 anchors the seam (replacing vertex 0), with `m = 0` v1's vertex-0 anchor holds verbatim. Compound (`kernel-front.js` + `loft-smooth.js`): each section's outline is a closed centripetal Catmull-Rom split into `m` clamped open arcs at its corners (or one closed periodic CR when `m = 0`); the `samples` budget is apportioned across arcs by mean arc-length fraction (largest-remainder, min 1 span/arc) and each arc resampled by arc length — total ring vertex count is `samples`, identical across sections, exactly v1's invariant now corner-anchored. The cross-station direction is v1 verbatim (shared centroid-spine knots, per-vertex CR, reflection phantoms at the ends, or periodic knots when `closed: true`). What's new is emission: every station — the dense list and the sparse `stations:"controls"` list alike — is fitted back to an **all-cubic Bézier contour**, arc-by-arc, via exact 4-point CR→Bézier inversion, so **both backends receive identical curve rings**. A B-rep kernel lofts the sparse control wires with its native smooth skin (`ruled: false`) — curve-exact around each ring in STEP (the densified-*point*-wire alternative measured 23 s / WASM-abort territory, which curve wires don't hit). A mesh kernel densifies `stations` rings and lofts them through `k.loft`'s curve-mode per-segment sampling, creasing sharp/corner columns via loft's geometric corner policy. `closed: true` (default false; needs ≥3 control sections, frozen error otherwise) makes the cross-station CR periodic (no reflection phantoms, ring 0 not repeated) and is **Manifold-only**, same restriction as `loft` `closed: true`: a B-rep kernel throws `loftSmooth: closed:true loops are only supported on the Manifold backend` in the composition, before building any rings; combining `closed: true` with `stations:"controls"` is rejected as a defensive invariant (reachable only by explicitly passing the internal `stations:"controls"` value; the composition never produces the combination itself). Options-only. Defaults `stations = (n−1)·8+1` open / `n·8` closed (raised to the section count `n` when lower), `samples = max(64, largest section)` (raised to the corner count `m` when lower); clamps 2…1024 / 8…2048. The surface interpolates every control section exactly. Parity: **within tolerance** (`screwSweep`'s class, unchanged from v1 — ~0.4% measured on the propeller reference part, test-gated at 2%). STEP is now curve-exact around each ring (previously faceted at the `samples` LOD); the cross-station skin remains ThruSections' native fit, not the shared CR — exact cross-station B-splines are a v3 candidate. Additive: `sharp`, curve/`Shape2D` sections, and `closed` are new options on top of v1's `{sections, stations?, samples?, shading?}`; `CONTRACT_VERSION` stays 4 — the same non-bump precedent as `import` above, a refinement inside the op's already-stated tolerance class rather than a new one. |
+| `loftSmooth({sections, stations?, samples?, shading?, closed?})` | Spline-interpolated loft of ≥2 sparse control sections — loft-style ring specs `{polygon\|sides+radius\|curve contour\|Shape2D, z, rotate?, scale?, sharp?}`; vertex counts **may differ**. A point section may tag `sharp: [indices]` as true corners (integers in `0…points.length-1`, sorted/deduped silently); a curve/`Shape2D` section takes corners implicitly from its non-smooth joints (single-region, hole-free, `loftSmooth:`-prefixed `k.loft` validation) and rejects an explicit `sharp`. Every section must resolve to the **same corner count `m`** (frozen error otherwise); with `m ≥ 1` corner 0 anchors the seam (replacing vertex 0), with `m = 0` v1's vertex-0 anchor holds verbatim. Compound (`kernel-front.js` + `loft-smooth.js`): each section's outline is a closed centripetal Catmull-Rom split into `m` clamped open arcs at its corners (or one closed periodic CR when `m = 0`); the `samples` budget is apportioned across arcs by mean arc-length fraction (largest-remainder, min 1 span/arc) and each arc resampled by arc length — total ring vertex count is `samples`, identical across sections, exactly v1's invariant now corner-anchored. The cross-station direction is v1 verbatim (shared centroid-spine knots, per-vertex CR, reflection phantoms at the ends, or periodic knots when `closed: true`). What's new is emission: every station — the dense list and the sparse `stations:"controls"` list alike — is fitted back to an **all-cubic Bézier contour**, arc-by-arc, via exact 4-point CR→Bézier inversion, so **both backends receive identical curve rings**. A B-rep kernel lofts the sparse control wires with its native smooth skin (`ruled: false`) — curve-exact around each ring in STEP (the densified-*point*-wire alternative measured 23 s / WASM-abort territory, which curve wires don't hit). A mesh kernel densifies `stations` rings and lofts them through `k.loft`'s curve-mode per-segment sampling, creasing sharp/corner columns via loft's geometric corner policy. `closed: true` (default false; needs ≥3 control sections, frozen error otherwise) makes the cross-station CR periodic (no reflection phantoms, ring 0 not repeated) and is **Manifold-only**, same restriction as `loft` `closed: true`: a B-rep kernel throws `loftSmooth: closed:true loops are only supported on the Manifold backend` in the composition, before building any rings; combining `closed: true` with `stations:"controls"` is rejected as a defensive invariant (reachable only by explicitly passing the internal `stations:"controls"` value; the composition never produces the combination itself). Options-only. Defaults `stations = (n−1)·8+1` open / `n·8` closed (raised to the section count `n` when lower), `samples = max(64, largest section)` (raised to the corner count `m` when lower); clamps 2…1024 / 8…2048 — the defaults cap themselves at the ceilings, only explicit out-of-range values throw. The surface interpolates every control section exactly. Parity: **within tolerance** (`screwSweep`'s class, unchanged from v1 — ~0.4% measured on the propeller reference part, test-gated at 2%). STEP is now curve-exact around each ring (previously faceted at the `samples` LOD); the cross-station skin remains ThruSections' native fit, not the shared CR — exact cross-station B-splines are a v3 candidate. Additive: `sharp`, curve/`Shape2D` sections, and `closed` are new options on top of v1's `{sections, stations?, samples?, shading?}`; `CONTRACT_VERSION` stays 4 — the same non-bump precedent as `import` above, a refinement inside the op's already-stated tolerance class rather than a new one. |
 | `union(solids[])` | Boolean union of one or more solids. |
 | `text2d(string, {size, font?, align?, valign?, lineHeight?, tracking?, kerning?})` | Outline-font text → `Shape2D`. `size` = cap height (mm). `font` = declared name / inline bytes / default. Build-time; curve-exact on OCCT, faceted on Manifold. |
 | `hull(inputs[])` | Convex hull of all inputs (each a `Shape2D`, a curve contour, or an `[[x,y],…]` point list) → a convex `Shape2D`. Backend-agnostic: a pure-JS monotone-chain hull over the inputs' sampled points (curved inputs tessellated at a fixed LOD), lifted via `shape2d` (see the parity note below). Throws on an empty input array or a degenerate (collinear/point-count < 3) hull. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.85.2",
+  "version": "0.85.4",
   "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/loft-smooth.js

@@ -309,7 +309,8 @@ function reconcile(resolved, V) {
  *     — the B-rep path, where the backend's native smooth loft (`ruled: false`)
  *     does the skinning through exact wires and only the around-ring
  *     reconciliation is needed; incompatible with closed:true;
- *   samples  — output vertex count around each ring (default max(64, largest section));
+ *   samples  — output vertex count around each ring (default max(64, largest
+ *     section), capped at 2048);
  *   closed   — periodic spine: the spline wraps from the last control section back
  *     to the first (no duplicate ring at the wrap point), needs ≥ 3 sections.
  * @returns {Array<{polygon: {start, segments}, z: number}>}
@@ -320,10 +321,11 @@ export function smoothLoftRings(sections, { stations, samples, closed = false }
   if (closed && stations === "controls")
     throw new Error('loftSmooth: closed:true cannot combine with stations:"controls"');
   if (closed && n < 3) throw new Error("loftSmooth: closed:true needs at least 3 control sections");
-  // The default caps at the clamp ceiling: at 129+ sections the raw formula
+  // The defaults cap at the clamp ceilings: at 129+ sections the raw 8-per-span
+  // stations (and at a 2049+-point section the raw largest-section samples)
   // would trip the range check on an option the caller never passed.
   const S = stations ?? Math.min(closed ? n * 8 : (n - 1) * 8 + 1, 1024);
-  const V = samples ?? Math.max(64, ...resolved.map((r) => r.pts2d.length));
+  const V = samples ?? Math.min(Math.max(64, ...resolved.map((r) => r.pts2d.length)), 2048);
   if (stations !== "controls" && !(Number.isFinite(S) && S >= 2 && S <= 1024))
     throw new Error('loftSmooth: stations must be 2…1024 (or "controls")');
   if (!(Number.isFinite(V) && V >= 8 && V <= 2048)) throw new Error("loftSmooth: samples must be 8…2048");

package/src/parts/propeller.js

@@ -1,15 +1,56 @@
-// The k.loftSmooth reference part: a boat propeller — bored hub + N airfoil
-// blades, each blade a spline-interpolated loft of 5 sparse control sections.
-// The "Surface" section keeps the didactic A/B: untick **Smooth** to see the raw
-// k.loft of the same control sections. Specs:
-// docs/superpowers/specs/2026-08-24-loft-smooth-design.md
-// docs/superpowers/specs/2026-08-25-loft-smooth-v2-design.md
+// THE reference part for organic lofted geometry (docs/AUTHORING-PARTS.md "Smooth
+// organic lofts"): a boat propeller — bored hub + N airfoil blades, each blade one
+// `k.loftSmooth` of 5 sparse control sections. If you are building a boat propeller,
+// a fan, an impeller, or an airplane prop, start from this file: the blade recipe
+// (airfoil ring → chord/twist schedule up the span → smooth loft → radial placement)
+// is the whole pattern, and everything else is ordinary hub plumbing.
+//
+// Vocabulary → code:
+//   span       — blade length root→tip (the loft's z axis, before placement)
+//   chord      — airfoil width at a station (`rootChord`→`tipChord` × CHORD_MUL)
+//   pitch      — per-section `rotate` (deg): angle between chord and rotation plane
+//   washout    — the root→tip pitch DROP (`twistRoot` > `twistTip`), standard on
+//                real props/fans so the tip doesn't stall/over-bite
+//   camber     — curvature of the airfoil midline (% chord): lift/thrust asymmetry
+//   handedness — `lefthand` mirrors every section and negates pitch: a true
+//                mirror-image prop for counter-rotating pairs or reversed shafts
+//
+// The blade-frame trick: each blade is lofted SPAN-UP (+Z), so its sections are
+// plain 2-D rings and `rotate` is exactly the pitch angle; `rotateY(90)` then lays
+// it radial along +X, where the chord sits in the axis/rotation-plane frame. Clone
+// and `rotateZ` for the other blades; never author sections in the placed frame.
+//
+// Adapting this part (change parameters, not plumbing):
+//   boat propeller — the defaults: 3 blades, high pitch (62°→30°), thick sections,
+//     generous camber, stubby hub. Wide-chord "kaplan" styles: raise CHORD_MUL mid.
+//   fan / desk fan — more blades (4–6+), FLAT pitch (`twistRoot` ~35°, `twistTip`
+//     ~20°), thin sections (`thickness` 5–8%), modest camber (2–4%), longer span
+//     relative to hub. Reversible fans want `camber: 0` (symmetric sections).
+//   airplane prop — 2 blades, long span, small chord, washout similar to defaults.
+//   counter-rotating pair — build twice, second with `lefthand: 1`.
+// Leave alone: the loft/`sharp` plumbing, the blade frame, the CCW/TE-at-vertex-0
+// contracts of `airfoil()` below.
+//
+// The "Surface" section is didactic, not part of the propeller: untick **Smooth**
+// to see the raw `k.loft` of the same sparse sections (the chunky failure mode
+// `loftSmooth` exists to fix). Contract: docs/KERNEL-CONTRACT.md `loftSmooth` row.
+// Specs: docs/superpowers/specs/2026-08-24-loft-smooth-design.md,
+//        docs/superpowers/specs/2026-08-25-loft-smooth-v2-design.md
 
-// NACA-4-ish airfoil contour, closed and CCW, centered near the quarter chord so
-// per-ring `rotate` twists about a sensible pitch axis. `n` points per surface;
-// cosine spacing clusters points at the leading edge, which is exactly the uneven
-// spacing the centripetal densifier is supposed to handle.
-const airfoil = (chord, thickPct, camberPct, n) => {
+/**
+ * NACA-4-ish airfoil section as a closed CCW point ring.
+ * Contract (relied on by `bladeSections` and the `sharp` tag): the ring starts at
+ * the TRAILING EDGE (vertex 0), runs TE→LE along the upper surface, LE→TE along
+ * the lower, stays CCW, and is centered near the quarter chord so per-section
+ * `rotate` pitches about a sensible axis. `n` points per surface; cosine spacing
+ * clusters points at the leading edge — exactly the uneven spacing loftSmooth's
+ * centripetal resampler is built for, so ~12 points per surface is plenty.
+ * @param {number} chord     section width, mm
+ * @param {number} thickPct  max thickness, % of chord
+ * @param {number} camberPct midline camber, % of chord (0 = symmetric)
+ * @param {number} n         points per surface (ring has 2n vertices)
+ */
+export const airfoil = (chord, thickPct, camberPct, n) => {
   const t = thickPct / 100, m = camberPct / 100, p = 0.4;
   const yt = (x) => 5 * t * (0.2969 * Math.sqrt(x) - 0.126 * x - 0.3516 * x * x + 0.2843 * x ** 3 - 0.1036 * x ** 4);
   const yc = (x) => (x < p ? (m / (p * p)) * (2 * p * x - x * x) : (m / ((1 - p) ** 2)) * (1 - 2 * p + 2 * p * x - x * x));
@@ -24,31 +65,52 @@ const airfoil = (chord, thickPct, camberPct, n) => {
   return pts.map(([x, y]) => [(x - 0.3) * chord, y * chord]);
 };
 
-// Five control stations up the span: a propeller-y chord outline (widest mid-span,
-// closing toward a rounded tip) and a root→tip pitch-angle washout.
+// Mirror a section ring across its chord (y → −y) for a lefthand blade, keeping
+// both `airfoil()` contracts intact: re-reversing the order restores CCW winding,
+// and pinning the first point keeps the trailing edge at vertex 0 for `sharp`.
+const mirrorRing = (pts) => {
+  const m = pts.map(([x, y]) => [x, -y]);
+  return [m[0], ...m.slice(1).reverse()];
+};
+
+// The blade's spanwise schedules. SPAN_T places the 5 control stations along the
+// span (clustered toward the tip, where shape changes fastest); CHORD_MUL shapes
+// the outline on top of the root→tip chord taper — widest mid-span, closing to a
+// rounded tip. This is where a different blade silhouette lives.
 const SPAN_T = [0, 0.3, 0.6, 0.85, 1];
 const CHORD_MUL = [1, 1.12, 1.0, 0.72, 0.28];
-const bladeSections = (p) =>
-  SPAN_T.map((t, i) => ({
-    polygon: airfoil(
+
+/**
+ * The 5 sparse control sections for one blade, span-up: `{polygon, z, rotate,
+ * sharp?}` ring specs ready for `k.loftSmooth({sections})`. Chord tapers
+ * root→tip (× CHORD_MUL), thickness thins 45% toward the tip, pitch interpolates
+ * `twistRoot`→`twistTip` (washout). `lefthand` mirrors each ring and negates
+ * pitch — together exactly a mirror of the whole blade.
+ */
+export const bladeSections = (p) =>
+  SPAN_T.map((t, i) => {
+    const ring = airfoil(
       (p.rootChord + (p.tipChord - p.rootChord) * t) * CHORD_MUL[i],
       p.thickness * (1 - 0.45 * t), // blades thin toward the tip
       p.camber,
       p.sectionPts,
-    ),
-    // The trailing edge is the ring's two end vertices (upper TE vertex 0, lower
-    // TE the last) — this NACA closure (coefficient -0.1036) already brings them
-    // together at the same point, so the "gap" between them is a genuine zero-
-    // length edge, not a blunt base. Tagging vertex 0 as the single corner keeps
-    // that meeting point a crease instead of letting the CR spline round it off;
-    // a *second* tag at the last vertex would mark a zero-length arc between two
-    // coincident corners, which — after the per-section pitch `rotate` below
-    // collapses their sub-epsilon separation to bit-identical floats — the
-    // resampler rejects as a zero-perimeter section.
-    ...(p.sharpTE && p.smooth ? { sharp: [0] } : {}),
-    z: p.span * t,
-    rotate: p.twistRoot + (p.twistTip - p.twistRoot) * t,
-  }));
+    );
+    return {
+      polygon: p.lefthand ? mirrorRing(ring) : ring,
+      // The trailing edge is the ring's two end vertices (upper TE vertex 0, lower
+      // TE the last) — this NACA closure (coefficient -0.1036) already brings them
+      // together at the same point, so the "gap" between them is a genuine zero-
+      // length edge, not a blunt base. Tagging vertex 0 as the single corner keeps
+      // that meeting point a crease instead of letting the CR spline round it off;
+      // a *second* tag at the last vertex would mark a zero-length arc between two
+      // coincident corners, which — after the per-section pitch `rotate` below
+      // collapses their sub-epsilon separation to bit-identical floats — the
+      // resampler rejects as a zero-perimeter section.
+      ...(p.sharpTE && p.smooth ? { sharp: [0] } : {}),
+      z: p.span * t,
+      rotate: (p.lefthand ? -1 : 1) * (p.twistRoot + (p.twistTip - p.twistRoot) * t),
+    };
+  });
 
 export default {
   meta: { title: "Propeller", units: "mm", background: 0x15181d },
@@ -56,22 +118,32 @@ export default {
     {
       id: "prop",
       title: "Propeller",
-      description: "A boat propeller: bored hub + airfoil blades. The blade is the organic-surface exerciser — every surface is a `loftSmooth` of 5 sparse control sections.",
+      description: "A boat propeller: bored hub + airfoil blades, every blade surface a `loftSmooth` of 5 sparse control sections. Also the starting point for fans and airplane props — see the file header's \"Adapting this part\".",
       controls: [
-        { key: "blades", label: "Blades", min: 2, max: 6, step: 1 },
-        { key: "span", label: "Blade span", unit: "mm", min: 30, max: 120, step: 1 },
-        { key: "rootChord", label: "Root chord", unit: "mm", min: 10, max: 50, step: 1 },
-        { key: "tipChord", label: "Tip chord", unit: "mm", min: 6, max: 40, step: 1 },
+        { key: "blades", label: "Blades", min: 2, max: 6, step: 1,
+          description: "Boat props: 3–4. Fans: 4–6. Airplane props: 2." },
+        { key: "span", label: "Blade span", unit: "mm", min: 30, max: 120, step: 1,
+          description: "Root-to-tip blade length. Overall diameter ≈ hub + 2×span." },
+        { key: "rootChord", label: "Root chord", unit: "mm", min: 10, max: 50, step: 1,
+          description: "Airfoil width where the blade meets the hub." },
+        { key: "tipChord", label: "Tip chord", unit: "mm", min: 6, max: 40, step: 1,
+          description: "Airfoil width at the tip, before the outline's own taper closes it." },
         { key: "twistRoot", label: "Root pitch", unit: "°", min: 0, max: 80, step: 1,
-          description: "Blade angle at the root. 0° puts the chord in the rotation plane." },
-        { key: "twistTip", label: "Tip pitch", unit: "°", min: 0, max: 80, step: 1 },
+          description: "Blade angle at the root; 0° puts the chord in the rotation plane. Boat props run steep (50–70°); fans flat (25–40°)." },
+        { key: "twistTip", label: "Tip pitch", unit: "°", min: 0, max: 80, step: 1,
+          description: "Blade angle at the tip. Keep it below root pitch (washout) so the tip doesn't over-bite." },
         { key: "thickness", label: "Thickness", unit: "%", min: 4, max: 25, step: 1,
-          description: "Airfoil thickness as % of chord, at the root." },
-        { key: "camber", label: "Camber", unit: "%", min: 0, max: 12, step: 1 },
+          description: "Airfoil thickness as % of chord, at the root (thins 45% toward the tip). Boat props 10–15%; fans 5–8%." },
+        { key: "camber", label: "Camber", unit: "%", min: 0, max: 12, step: 1,
+          description: "Midline curvature as % of chord — the thrust asymmetry. 0 = symmetric section (reversible fans)." },
+        { key: "lefthand", type: "checkbox", label: "Left-hand rotation",
+          description: "Mirror-image blades for a counter-rotating pair or a reversed shaft. Every section mirrors and pitch negates — a true mirror of the whole propeller." },
         { type: "group", title: "Hub", collapsed: "auto", controls: [
-          { key: "hubD", label: "Hub diameter", unit: "mm", min: 14, max: 60, step: 1 },
+          { key: "hubD", label: "Hub diameter", unit: "mm", min: 14, max: 60, step: 1,
+            description: "Blade roots sink to 62% of hub radius, so the union always has generous overlap." },
           { key: "hubH", label: "Hub length", unit: "mm", min: 10, max: 60, step: 1 },
-          { key: "boreD", label: "Shaft bore", unit: "mm", min: 2, max: 20, step: 0.5 },
+          { key: "boreD", label: "Shaft bore", unit: "mm", min: 2, max: 20, step: 0.5,
+            description: "Through-hole for the shaft — the part's one expected hole (see `verify`)." },
         ] },
       ],
     },
@@ -81,11 +153,13 @@ export default {
       description: "**Smooth** interpolates the 5 sparse control sections with `loftSmooth`; off shows the raw `k.loft` of the same sections. **Sharp trailing edge** tags the TE vertex as a crease instead of letting the spline smear it. **Stations/Samples** are the densifier resolution; **Section points** is how sparse the control sections are.",
       controls: [
         { key: "smooth", type: "checkbox", label: "Smooth (loftSmooth)",
-          description: "A/B toggle: spline-densified vs raw loft of identical control sections." },
+          description: "A/B toggle: spline-densified vs raw loft of identical control sections. Leave ON in real parts — the raw loft is the chunky failure mode." },
         { key: "sharpTE", type: "checkbox", label: "Sharp trailing edge", when: { smooth: 1 },
           description: "Tags the trailing-edge vertex as a true corner — the spline interpolates it with a crease instead of smearing it round." },
-        { key: "stations", label: "Stations", min: 5, max: 128, step: 1, when: { smooth: 1 } },
-        { key: "samples", label: "Samples / ring", min: 16, max: 512, step: 4, when: { smooth: 1 } },
+        { key: "stations", label: "Stations", min: 5, max: 128, step: 1, when: { smooth: 1 },
+          description: "Interpolated rings along the span. The default (48) is visually converged; more costs build time." },
+        { key: "samples", label: "Samples / ring", min: 16, max: 512, step: 4, when: { smooth: 1 },
+          description: "Spline-fit resolution around each ring. STEP file size scales with this; volume converges by ~48." },
         { key: "sectionPts", label: "Section points", min: 6, max: 40, step: 1,
           description: "Points per airfoil *surface* in each control section — the sparse input both paths share." },
       ],
@@ -93,7 +167,7 @@ export default {
   ],
   defaults: {
     blades: 3, span: 70, rootChord: 26, tipChord: 16, twistRoot: 62, twistTip: 30,
-    thickness: 12, camber: 6, hubD: 30, hubH: 26, boreD: 8,
+    thickness: 12, camber: 6, lefthand: 0, hubD: 30, hubH: 26, boreD: 8,
     smooth: 1, sharpTE: 1, stations: 48, samples: 128, sectionPts: 12,
   },
   parts: {
@@ -120,7 +194,9 @@ export default {
   views: { propeller: { label: "Propeller" } },
   verify: {
     expect: {
-      // One through-hole (the shaft bore); everything unioned into one watertight body.
+      // holes: 1 — exactly the shaft bore; a second hole means a blade/hub union
+      // gap. bbox bounds catch a runaway parameter. overlaps: 0 — the union must
+      // leave one watertight body, no interpenetrating leftovers.
       propeller: { holes: 1, bbox: "<=[300,300,300]" },
       _view: { overlaps: 0 },
     },

package/types/kernel.d.ts

@@ -401,7 +401,7 @@ export interface LoftSmoothOptions {
   sections: LoftSmoothSection[];
   /** Output ring count along the spine (default 8 per span + 1; closed: 8 per section; capped at 1024). */
   stations?: number;
-  /** Output vertex count around each ring (default max(64, largest section)). */
+  /** Output vertex count around each ring (default max(64, largest section), capped at 2048). */
   samples?: number;
   shading?: "smooth" | "faceted";
   /** Capless loop — Manifold only, ≥3 sections. */