forgecad 0.9.16 → 0.10.1

package/dist-skill/website/skills/forgecad.md

@@ -0,0 +1,122 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit docs/permanent/ instead. -->
+
+# forgecad
+
+ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, validating scripts, or using ForgeCAD export/render tooling.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | Generated from `docs/permanent/` by `scripts/build-forgecad-skill.mjs` |
+
+---
+
+## ForgeCAD
+
+Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.
+
+### Workflow
+
+1. Identify the artifact: `.forge.js`, SVG asset, or CLI/export task.
+2. **If the model has any moving parts, load the `assembly` group and `docs/permanent/guides/joint-design.md` upfront** — do not defer the kinematic structure to a refactor pass.
+3. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed, and prefer these docs and recipes over ad-hoc repo examples.
+4. If any two parts are intended to touch or mate in the final model, load `docs/permanent/guides/positioning.md` immediately and default to connectors + `matchTo()`.
+5. Default to a concrete first pass — easy iteration beats speculative design review.
+6. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
+7. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues; pass `--backend manifold|occt|truck` when the backend matters).
+8. For moving assemblies, return the `Assembly` directly so runtime controls re-solve the link/edge kinematics model instead of stacking viewport-only transforms.
+9. Model the physical artifact, not an educational diagram. No explanatory labels, arrows, legends, or text plaques unless the user explicitly asks for a presentation or teaching view; product markings only where the real object would carry them.
+10. Build the real closed CAD first. Never bake cutaways, sectioned shells, permanently exploded layouts, or hidden-parts views into the default model just to show internals — use viewer-only cut planes, `explodeView`, object hiding, transparency, or `inspect sections` after the artifact exists.
+
+#### Import and Composition
+
+- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; never destructure those names from helpers (`const { bom } = require("./bom.js")`). Import helper files under a project-specific name such as `const bomHelpers = require("./bom.js")`.
+- For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
+- Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use it only when you need `ShapeGroup` composition, transforms, or named-child lookup.
+- `Import.svgSketch()` loads SVG files (file format loader, not a module import).
+- `.placeReference('bottom', [0,0,0])` aligns any built-in anchor to a world coordinate; also works with custom `.withReferences()`.
+- Plain `.js` modules hold shared helpers/constants (not model imports).
+
+### Source Map
+
+Load groups top-to-bottom, stopping when you have what the task needs.
+
+#### 1. Core API (always read first)
+
+Execution model, colors, coordinate system, primitives, booleans, patterns, imports, parameters, topology, edge queries.
+
+- `docs/permanent/API/core/concepts.md`
+- `docs/permanent/generated/runtime-names.md`
+- `docs/permanent/generated/core.md`
+
+#### 2. Static Assembly and Positioning (for any multi-part model)
+
+Axis conventions, winding rules, and placement strategy. If parts should touch in the final model, read this group before writing placement code. Connectors + `matchTo()` are the default for mating interfaces; raw `translate()` and `rotate()` are for free offsets, not assembly contracts.
+
+- `docs/permanent/guides/coordinate-system.md`
+- `docs/permanent/guides/positioning.md`
+
+#### 3. Sketch APIs
+
+2D construction, transforms, booleans, paths, on-face sketching, extrusion, anchors, text, regions.
+
+- `docs/permanent/generated/sketch.md`
+
+#### 4. Curves and Surfacing (for lofts, sweeps, splines)
+
+Smooth curves, Hermite splines, lofted and swept solids. For straps, inlays, guards, brace members, vents, or physical bands that live on a carrier surface, use `Carrier` + `SurfaceBody` surface-member primitives before reaching for `variableSweep`, SDF sculpting, or manual boolean overlap recipes.
+
+- `docs/permanent/guides/surface-members.md`
+- `docs/permanent/generated/curves.md`
+
+#### 5. Assemblies and Mechanisms (for joints or kinematics)
+
+Assembly graph, joint types, couplings, validation, robot export.
+
+- `docs/permanent/generated/assembly.md`
+
+#### 6. Sheet Metal (for bent parts, K-factor, flat patterns)
+
+Bend operations, flat pattern unfolding, K-factor configuration.
+
+- `docs/permanent/generated/sheet-metal.md`
+
+#### 7. Output and Export (for STL/3MF/STEP, BOM, dimensions)
+
+Mesh export, exact geometry export, bill of materials, dimension annotations.
+
+- `docs/permanent/generated/output.md`
+
+#### 8. Toolbox (fasteners and standard parts)
+
+Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural profiles.
+
+- `docs/permanent/generated/lib.md`
+- `docs/permanent/generated/wood.md`
+
+#### 9. Runtime Viewport APIs (for cut planes, exploded views, hiding, and animation playback)
+
+Viewer-only APIs such as cutPlane, explodeView, render labels, comparison references, and runtime display behavior.
+
+- `docs/permanent/generated/viewport.md`
+
+#### 10. Recipes and Debugging (for patterns and troubleshooting)
+
+Modeling patterns, debugging tactics, copyable snippets.
+
+- `docs/permanent/guides/scene-presentation.md`
+- `docs/permanent/guides/joint-design.md`
+
+#### 11. CLI (for validation/render/export tasks)
+
+Test-run, export pipelines, debug flags.
+
+- `docs/permanent/CLI.md`
+- `docs/permanent/guides/inspection-bundles.md`
+
+#### SDF Modeling (smooth booleans, TPMS, deformations, fromFunction)
+
+Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas. The doc preamble's precision caution applies to every SDF workflow.
+
+- `docs/permanent/generated/sdf.md`

package/dist-skill/website/skills/index.md

@@ -0,0 +1,26 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/*/SKILL.md instead. -->
+
+# ForgeCAD Skills
+
+These are the agent skills shipped in the ForgeCAD npm package. The default install path installs the core `forgecad` skill plus the companion workflow skills listed here.
+
+```bash
+forgecad skill install
+```
+
+| Skill | Installed by | Purpose |
+| --- | --- | --- |
+| [forgecad](/docs/skills/forgecad) | `forgecad skill install` | ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, validating scripts, or using ForgeCAD export/render tooling. |
+| [forgecad-3d-reconstruction](/docs/skills/forgecad-3d-reconstruction) | `forgecad skill install` | Reconstruct a parametric ForgeCAD model from an existing 3D CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP; inspect the source asset directly, author real ForgeCAD geometry, and iteratively compare the candidate with `forgecad compare 3d`. |
+| [forgecad-blockout-model](/docs/skills/forgecad-blockout-model) | `forgecad skill install` | Create rough high-level ForgeCAD concept models from simple primitives to explore layout, proportions, motion, and part relationships without production detail. Use when asked for a quick model sketch, blockout, spatial mockup, or intuitive low-detail 3D concept. |
+| [forgecad-component-model](/docs/skills/forgecad-component-model) | `forgecad skill install` | Enforce the ForgeCAD Component Model when building multi-part assemblies. Parts build at origin, connectors position them, data flows down from parent. Use when building or reviewing any multi-file ForgeCAD project. |
+| [forgecad-high-level-spec](/docs/skills/forgecad-high-level-spec) | `forgecad skill install` | Write a high-level design document (HLD) for a model, mechanism, or assembly before detailed specification or coding. Use when starting a new design, rethinking an existing one, or when the user asks to spec out, plan, or think through a model at a high level. Works backwards from requirements — defines the problem, explores alternatives, records decisions. Produces a right-sized design document for review and iteration. |
+| [forgecad-image-replicator](/docs/skills/forgecad-image-replicator) | `forgecad skill install` | Build real ForgeCAD geometry from one or more reference images by treating images as evidence, inferring the object, then validating against both reference-matched and canonical views. |
+| [forgecad-lld](/docs/skills/forgecad-lld) | `forgecad skill install` | Write a Low-Level Design (LLD) for a CAD model — exact dimensions, constraints, parameters, and verification criteria. Use after a High-Level Design (HLD) exists and decisions are locked, or for simple parts that don't need an HLD. The detailed design document that code implements. |
+| [forgecad-make-a-model](/docs/skills/forgecad-make-a-model) | `forgecad skill install` | Create manufacture-realistic prototype ForgeCAD (.forge.js) models in the active CAD project. Handles file placement, invokes the forgecad skill for API guidance, and validates the result. |
+| [forgecad-model-grader](/docs/skills/forgecad-model-grader) | `forgecad skill install` | Analyze, verify, and grade ForgeCAD or CAD-as-code models against a user requirement, design brief, prompt, reference, or acceptance criteria. Use when asked to evaluate, judge, QA, benchmark, score, rate, or compare a CAD model; render it from multiple angles, run targeted inspections when needed, visually verify the evidence, and produce a 0-10 score with concise justification. |
+| [forgecad-prepare-prompt](/docs/skills/forgecad-prepare-prompt) | `forgecad skill install` | Turn a fuzzy physical product, mechanism, or CAD artifact request into a concrete manufacture-realistic prototype ForgeCAD build brief and a single master prompt for the modeling pass. Use when the engineering brief is incomplete, manufacturing/process choice is underspecified, or the work needs a specific operating story to avoid generic toy solutions. |
+| [forgecad-project](/docs/skills/forgecad-project) | `forgecad skill install` | ForgeCAD project CLI workflow — creating, managing, syncing projects and files on forgecad.io. Covers init, push, pull, file operations, member management, publishing, and sharing. |
+| [forgecad-reconstruction-benchmark](/docs/skills/forgecad-reconstruction-benchmark) | `forgecad skill install` | Solve ForgeCAD CAD reconstruction benchmark or RL episodes in a prepared workspace by rebuilding a visible reference asset as readable parametric ForgeCAD in the fixed submission path, using visual and geometric self-checks while respecting sandbox limits. |
+| [forgecad-render-inspect](/docs/skills/forgecad-render-inspect) | `forgecad skill install` | Run and interpret ForgeCAD inspection bundles for model verification. Use when asked to inspect a ForgeCAD model, analyze an inspection bundle, validate collisions, wall thickness, connectivity, floating bodies, sections, masks, depth, normals, or Zebra stripes. |
+| [forgecad-visual-spec](/docs/skills/forgecad-visual-spec) | `forgecad skill install` | Turn a concrete ForgeCAD artifact, build brief, HLD, or existing model into builder-honest image prompts for AI image models. Use when the user wants visual-spec renders that show the final product while keeping mechanisms, seams, hardware, and build cues visible instead of drifting into concept art. |

package/examples/api/comparison-imported-sphere-candidate.forge.js

@@ -11,7 +11,7 @@ compareWith("../assets/sphere.stl", {
   label: "Original STL Sphere",
 });
 
-const source = importMesh("../assets/sphere.stl");
+const source = Import.mesh("../assets/sphere.stl");
 const bb = source.boundingBox();
 const width = bb.max[0] - bb.min[0];
 const depth = bb.max[1] - bb.min[1];

package/examples/api/conformal-product-ribbon.forge.js

@@ -5,7 +5,7 @@
 
 Product.scenePreset('product');
 
-viewConfig({
+scene({
   camera: { position: [78, -180, 88], target: [0, 0, 58], fov: 31 },
 });
 

package/examples/api/exact-sheet-shell-assembly.forge.js

@@ -1,7 +1,7 @@
 const width = param('Width', 112);
 const depth = param('Depth', 78);
 const height = param('Height', 44);
-const showConstruction = boolParam('Show Construction Sheets', false);
+const showConstruction = Param.bool('Show Construction Sheets', false);
 const constructionOffset = param('Construction Offset', 22);
 
 const materials = {

package/examples/api/extrude-options.forge.js

@@ -23,8 +23,10 @@ const tapered = circle2d(r).extrude(h, { scaleTop: taper })
   .translate(2 * spacing, 0, 0)
   .color('#44cc88');
 
-// 4. Combined: twist + taper
-const combo = star(5, r, r * 0.5).extrude(h, {
+// 4. Combined: twist + taper, on a five-pointed star built from layout primitives
+const tips = polygonVertices(5, r, { startDeg: -90 });
+const valleys = polygonVertices(5, r * 0.5, { startDeg: -90 + 180 / 5 });
+const combo = polygon(tips.flatMap((tip, i) => [tip, valleys[i]])).extrude(h, {
   twist: twist,
   scaleTop: taper,
   divisions: 32,

package/examples/api/field-loft-drive-tip.forge.js

@@ -0,0 +1,40 @@
+/**
+ * Field-interpolated loft for profiles that change character.
+ *
+ * Red uses the regular stitched loft. Green uses Loft.field(), which blends
+ * profile signed-distance fields and avoids boundary-point correspondence.
+ */
+
+scene({
+  camera: { position: [80, -105, 55], target: [0, 0, 9], fov: 36 },
+});
+
+const heights = [0, 5, 11, 17];
+const shank = circle2d(6, 80);
+
+function crossProfile(radius, armWidth) {
+  return union2d(rect(radius * 2.05, armWidth), rect(armWidth, radius * 2.05));
+}
+
+const profiles = [
+  shank,
+  shank,
+  crossProfile(6, 3),
+  crossProfile(4.3, 2.1),
+];
+
+const stitched = loft(profiles, heights, { edgeLength: 0.22 })
+  .translate(-12, 0, 0)
+  .color('#c2574b');
+
+const field = Loft.field(profiles, heights, {
+  edgeLength: 0.14,
+  maxTriangles: 5000,
+})
+  .translate(12, 0, 0)
+  .color('#4c8f73');
+
+return [
+  { name: 'regular loft', shape: stitched },
+  { name: 'field loft', shape: field },
+];

package/examples/api/guided-loft-olive-oil-bottle.forge.js

@@ -7,7 +7,7 @@
 
 Product.scenePreset('product');
 
-viewConfig({
+scene({
   camera: { position: [190, -250, 150], target: [8, 0, 88], fov: 34 },
 });
 

package/examples/api/highlight-debug.forge.js

@@ -1,36 +1,36 @@
 /**
  * Debug Highlight API — visual debugging for any geometry
  *
- * highlight() accepts points, edges, planes, faces, shapes, and sketch entities.
+ * Viewport.highlight() accepts points, edges, planes, faces, shapes, and sketch entities.
  * Each highlighted item renders as a colored overlay in the viewport.
  */
 
 const b = box(30, 20, 15);
 
 // Point highlight — rendered as a small sphere
-highlight([0, 0, 0], { color: 'cyan', label: 'origin' });
-highlight([30, 20, 15], { color: 'cyan', label: 'corner' });
+Viewport.highlight([0, 0, 0], { color: 'cyan', label: 'origin' });
+Viewport.highlight([30, 20, 15], { color: 'cyan', label: 'corner' });
 
 // Edge highlight — rendered as a line segment with endpoint spheres
-highlight([[0, 0, 0], [30, 20, 15]], { color: 'yellow', label: 'diagonal' });
+Viewport.highlight([[0, 0, 0], [30, 20, 15]], { color: 'yellow', label: 'diagonal' });
 
 // Plane highlight — rendered as a semi-transparent disc with normal arrow
-highlight({ normal: [0, 0, 1], offset: 7.5 }, { color: 'lime', label: 'z=7.5', size: 30 });
+Viewport.highlight({ normal: [0, 0, 1], offset: 7.5 }, { color: 'lime', label: 'z=7.5', size: 30 });
 
 // Plane from normal + point
-highlight({ normal: [1, 0, 0], point: [15, 0, 0] }, { color: 'orange', label: 'x=15' });
+Viewport.highlight({ normal: [1, 0, 0], point: [15, 0, 0] }, { color: 'orange', label: 'x=15' });
 
 // Face reference — highlight a named face from a tracked shape
-highlight(b.face('top'), { color: 'red', label: 'top face' });
+Viewport.highlight(b.face('top'), { color: 'red', label: 'top face' });
 
 // Edge reference — highlight a named edge
-highlight(b.edge('top-right'), { color: 'blue', label: 'top-right edge' });
+Viewport.highlight(b.edge('top-right'), { color: 'blue', label: 'top-right edge' });
 
 // Shape highlight — transparent colored overlay on the entire shape
-highlight(b, { color: '#ff00ff' });
+Viewport.highlight(b, { color: '#ff00ff' });
 
 // Intermediary shape highlight — snapshot a temporary shape that is not returned
 const temporary = b.translate(40, 0, 0);
-highlight(temporary, { color: '#00ffff', label: 'temporary snapshot' });
+Viewport.highlight(temporary, { color: '#00ffff', label: 'temporary snapshot' });
 
 return b;

package/examples/api/mesh-import-slats.forge.js

@@ -8,7 +8,7 @@ const slatThickness = Param.number("Slat thickness", 1.2, { min: 0.4, max: 3, un
 const gap = Param.number("Gap", 1.5, { min: 0.5, max: 5, unit: "mm" });
 
 // Import an external mesh file
-const mesh = importMesh("assets/sphere.stl");
+const mesh = Import.mesh("assets/sphere.stl");
 const bb = mesh.boundingBox();
 const size = [bb.max[0] - bb.min[0], bb.max[1] - bb.min[1], bb.max[2] - bb.min[2]];
 const center = [(bb.min[0] + bb.max[0]) / 2, (bb.min[1] + bb.max[1]) / 2, (bb.min[2] + bb.max[2]) / 2];

package/examples/api/real-product-curves.forge.js

@@ -8,7 +8,7 @@
 
 Product.scenePreset('product');
 
-viewConfig({
+scene({
   camera: { position: [190, -265, 160], target: [0, -18, 70], fov: 34 },
 });
 

package/examples/api/sculpt-box-circle-booleans.forge.js

@@ -22,7 +22,7 @@ const slab = Sculpt.box(86, 44, 20, { radius: 8 }).polish({
   reflectivity: 0.66,
 });
 
-const circularWindow = Sculpt.circle(13, 34).tilt(90, 'x').at(-22, 0, 0);
+const circularWindow = Sculpt.disk(13, 34).tilt(90, 'x').at(-22, 0, 0);
 const ringGroove = Sculpt.torus(25, 2.8).tilt(90, 'x').at(20, 0, 0);
 const diagonalBite = Sculpt.curve(
   [

package/examples/api/sdf-shapes.forge.js

@@ -18,11 +18,8 @@ const smoothCarve = sdf.smoothDifference(
   .translate(40, 0, 0)
   .color('#cc4444');
 
-const morphed = sdf.morph(
-  sdf.sphere(12),
-  sdf.box(20, 20, 20),
-  0.5,
-)
+const morphed = sdf.sphere(12)
+  .morph(sdf.box(20, 20, 20), 0.5)
   .translate(80, 0, 0)
   .color('#44cc88');
 

package/examples/api/sketch-rounding-strategies.forge.js

@@ -41,16 +41,16 @@ const mergedCircles = union2d(
     circle2d(radius).translate(bodyWidth - shoulderInset, bodyHeight + shoulderRise),
   ),
 ).color('#7f5af0');
-const selectiveFillet = filletCorners(roofPoints, [
-  { index: 3, radius },
-  { index: 4, radius },
-  { index: 5, radius },
-]).color('#e63946');
+const selectiveFillet = polygon(roofPoints)
+  .filletCorner([bodyWidth - shoulderInset, bodyHeight + shoulderRise], radius)
+  .filletCorner([bodyWidth / 2, bodyHeight + peakRise], radius)
+  .filletCorner([shoulderInset, bodyHeight + shoulderRise], radius)
+  .color('#e63946');
 
 return [
   { name: "Raw polygon", sketch: rawProfile },
   { name: "offset(-r).offset(+r)", sketch: roundedAllCorners.translate(gap, 0) },
   { name: "stroke(..., 'Round')", sketch: strokedCenterline.translate(gap * 2, 0) },
   { name: "union2d() of circles", sketch: mergedCircles.translate(gap * 3, 0) },
-  { name: "filletCorners()", sketch: selectiveFillet.translate(gap * 4, 0) },
+  { name: ".filletCorner([x, y], r)", sketch: selectiveFillet.translate(gap * 4, 0) },
 ];

package/examples/api/surface-member-bottle-cage.forge.js

@@ -7,8 +7,8 @@ const cage = SurfaceBody('road-bike-bottle-cage')
   .at(bottle.back({ offset: 7 }))
   .size(30, 118)
   .section({ thickness: 5.4, edgeRadius: 1 })
-  .slot('upper-mount-slot', Slot.rounded({ length: 12, width: 5.7 }).verticalTravel(6).at({ z: 82 }))
-  .slot('lower-mount-slot', Slot.rounded({ length: 12, width: 5.7 }).verticalTravel(6).at({ z: 18 }))
+  .slot('upper-mount-slot', SurfaceMembers.roundedSlot({ length: 12, width: 5.7 }).verticalTravel(6).at({ z: 82 }))
+  .slot('lower-mount-slot', SurfaceMembers.roundedSlot({ length: 12, width: 5.7 }).verticalTravel(6).at({ z: 18 }))
   .member('left-arm')
   .band()
   .path(bottle.path().from({ angle: -145, z: 18 }).through({ angle: -116, z: 42 }).through({ angle: -72, z: 78 }).to({ angle: -34, z: 112 }))
@@ -24,7 +24,7 @@ const cage = SurfaceBody('road-bike-bottle-cage')
   .band()
   .path(bottle.path().from({ angle: -135, z: 92 }).through({ angle: 180, z: 54 }).to({ angle: 135, z: 92 }))
   .section({ width: 12, thickness: 5, edgeRadius: 1.3 })
-  .cutout('lightening-slot', Slot.rounded({ length: 54, width: 7 }))
+  .cutout('lightening-slot', SurfaceMembers.roundedSlot({ length: 54, width: 7 }))
   .join('left-arm', 'lower-cup').blend({ radius: 6, style: 'structural' })
   .join('right-arm', 'lower-cup').blend({ radius: 6, style: 'structural' })
   .join('front-sweep', ['left-arm', 'right-arm']).blend({ radius: 5 })

package/examples/api/surface-member-conformal-product-ribbon.forge.js

@@ -6,7 +6,7 @@
 
 Product.scenePreset('product');
 
-viewConfig({
+scene({
   camera: { position: [78, -180, 88], target: [0, 0, 58], fov: 31 },
 });
 
@@ -39,12 +39,12 @@ const inserts = SurfaceBody('surface-member-conformal-inserts')
   .band()
   .path(handle.surface('left').path().from({ u: 0.3, v: 0.18 }).through({ u: 0.34, v: 0.48 }).to({ u: 0.32, v: 0.78 }))
   .section({ width: 5.8, thickness: 0.9, material: rubber })
-  .features(Ribs.repeated({ count: 10, height: 0.28 }))
+  .features(SurfaceMembers.ribs({ count: 10, height: 0.28 }))
   .member('right-grip')
   .band()
   .path(handle.surface('right').path().from({ u: 0.7, v: 0.18 }).through({ u: 0.66, v: 0.48 }).to({ u: 0.68, v: 0.78 }))
   .section({ width: 5.8, thickness: 0.9, material: rubber })
-  .features(Ribs.repeated({ count: 10, height: 0.28 }))
+  .features(SurfaceMembers.ribs({ count: 10, height: 0.28 }))
   .build();
 
 return group(

package/examples/api/surface-member-razor-inlay.forge.js

@@ -15,7 +15,7 @@ const inlay = SurfaceBody('razor-overmold')
   .band()
   .path(handle.surface('left').path().from({ u: 0.35, v: 0.12 }).through({ u: 0.22, v: 0.55 }).to({ u: 0.42, v: 0.9 }))
   .section({ width: 8, thickness: 0.9, edgeRadius: 0.45, material: Product.materials.softRubber({ color: '#22262a' }) })
-  .features(Ribs.repeated({ count: 18, height: 0.35 }))
+  .features(SurfaceMembers.ribs({ count: 18, height: 0.35 }))
   .member('right-grip')
   .mirrorOf('left-grip')
   .join('left-grip', 'right-grip').blend({ radius: 2, style: 'separate-overmold' })

package/examples/api/variable-sweep-test.forge.js

@@ -1,12 +1,12 @@
 // Variable Sweep test — tapered tube along a curved spine
 // Demonstrates variableSweep() with different cross-sections at different t values
 
-const spine = Curve.Spline([
+const spine = Curve.Fit([
   [0, 0, 0],
   [20, 0, 10],
   [40, 10, 20],
   [60, 10, 30],
-], { tension: 0.4 });
+]);
 
 const smallCircle = circle2d(3);
 const largeCircle = circle2d(8);
@@ -20,6 +20,6 @@ const tapered = variableSweep(spine, [
   samples: 64,
 });
 
-verify.boundingBoxSize('variableSweep along Curve.Spline keeps the tapered tube envelope', tapered, [66, 22, 36], 8);
+verify.boundingBoxSize('variableSweep along Curve.Fit keeps the tapered tube envelope', tapered, [66, 22, 36], 8);
 
 return tapered.color('#8899aa');

package/examples/mechanical/airplane-propeller.forge.js

@@ -121,20 +121,28 @@ function twistAt(r) {
   return Math.atan(Math.tan(pitchAngle * DEG) * 0.75 * R / r) / DEG;
 }
 
-// Chord: GA propeller distribution — structural root + Betz-optimal taper.
-// Peaks near 25% span, maintains width at root for structural attachment,
-// smooth cosine taper to tip.
+// Chord: GA propeller distribution — structural root + Betz-optimal taper,
+// closed by an elliptical rounded tip. Peaks near 25% span, maintains width
+// at root for structural attachment, cosine taper to 92% span, then an
+// elliptical arc rounds the tip in planform (real propellers never taper to
+// a razor point — the tip cap needs finite chord to close cleanly).
+const TIP_ROUND_START = 0.92;
+
 function chordAt(rNorm) {
-  const r = rNorm;
+  const r = Math.min(rNorm, TIP_ROUND_START);
   // Root: rises from 55% at hub to 100% at ~25% span
   const rootRise = r < 0.25
     ? 0.55 + 0.45 * Math.pow(r / 0.25, 0.7)
     : 1.0;
-  // Cosine taper from peak to tip (exponent < 1 for fuller planform)
+  // Cosine taper from peak to the start of the tip round
   const tipTaper = r < 0.25
     ? 1.0
     : Math.pow(Math.cos(Math.PI / 2 * ((r - 0.25) / 0.75)), 0.5);
-  return maxChord * rootRise * tipTaper;
+  const base = maxChord * rootRise * tipTaper;
+  if (rNorm <= TIP_ROUND_START) return base;
+  // Elliptical closure from 92% span to the tip, floored for a clean cap
+  const s = (rNorm - TIP_ROUND_START) / (1 - TIP_ROUND_START);
+  return Math.max(base * Math.sqrt(Math.max(0, 1 - s * s)), maxChord * 0.05);
 }
 
 // Thickness ratio: thick root for structure, thin tip for aero.
@@ -163,27 +171,41 @@ function camberAt(rNorm) {
 //   - Zero pitch → chord along tangential (Y in world)
 //   - Positive β → leading edge tilts toward thrust axis (+Z)
 
-const NUM_STATIONS = 12;
+const NUM_STATIONS = 24;
 const NACA_PTS     = 40;      // points per airfoil surface (80 total outline)
 const CAMBER_POS   = 0.4;     // max camber at 40% chord (standard for props)
+const rRoot        = rHub * 0.55;  // blade shank starts inside the spinner
 
-const profiles = [];
-const heights  = [];
-
-for (let i = 0; i <= NUM_STATIONS; i++) {
-  const rNorm = i / NUM_STATIONS;
-  const r     = rHub + rNorm * (R - rHub);
-
-  const chord = Math.max(chordAt(rNorm), 5);  // minimum 5mm to avoid degenerate polygon
-  const thick = thicknessRatioAt(rNorm);
+// Airfoil section at a given normalized span position (clamped to the
+// aerodynamic range — the shank inside the spinner reuses the hub section).
+function bladeSection(rNorm, r) {
+  const chord  = chordAt(rNorm);
+  const thick  = thicknessRatioAt(rNorm);
   const camber = camberAt(rNorm);
-  const twist = twistAt(r);
+  const twist  = twistAt(Math.max(r, rHub));
 
-  // Generate NACA points and rotate to blade orientation
   let pts = nacaPoints(camber, CAMBER_POS, thick, chord, NACA_PTS);
   pts = rotate2D(pts, 90 + twist);  // 90° aligns chord with tangential, +twist adds pitch
+  return polygon(pts);
+}
+
+const profiles = [];
+const heights  = [];
 
-  profiles.push(polygon(pts));
+// Shank stations buried inside the spinner — a constant hub section carries
+// the blade to a structural attachment instead of floating at the hub surface.
+for (const r of [rRoot, rHub * 0.92]) {
+  profiles.push(bladeSection(0, rHub));
+  heights.push(r);
+}
+
+// Aerodynamic stations from the hub surface to the tip. Cosine spacing
+// clusters stations at the root (where the BEMT twist gradient is steepest)
+// and at the tip (where the planform rounds off).
+for (let i = 0; i <= NUM_STATIONS; i++) {
+  const rNorm = 0.5 - 0.5 * Math.cos(Math.PI * i / NUM_STATIONS);
+  const r     = rHub + rNorm * (R - rHub);
+  profiles.push(bladeSection(rNorm, r));
   heights.push(r);
 }
 
@@ -195,24 +217,27 @@ const blade = bladeRaw.rotateY(90);
 
 // ─── Spinner / Hub ──────────────────────────────────────────────
 //
-// Ogive spinner: parabolic nose + cylindrical body + rear taper.
+// Ogive spinner: elliptical nose + cylindrical body + rear taper.
 // Built as a loft of circular profiles along the propeller axis (Z).
+// The cylindrical body is centered on the blade plane (z = 0) so the
+// blade shanks bury fully into the spinner at maximum radius.
 
 const spinnerLen = hubDiameter * 1.3;
 const spinnerR   = rHub * 0.95;
-const HUB_STATIONS = 10;
+const HUB_STATIONS = 36;
 
 const hubProfiles = [];
 const hubHeights  = [];
 
 for (let i = 0; i <= HUB_STATIONS; i++) {
-  const t = i / HUB_STATIONS;   // 0 = nose (front), 1 = back
+  // Cosine clustering at the nose, where curvature is highest
+  const t = 1 - Math.cos(Math.PI / 2 * i / HUB_STATIONS);   // 0 = nose (front), 1 = back
 
   let r;
   if (t < 0.35) {
-    // Nose: parabolic ogive for low drag
-    const tn = t / 0.35;
-    r = spinnerR * Math.sqrt(tn);
+    // Nose: elliptical ogive — rounds to a closed dome instead of a flat disc
+    const tn = (0.35 - t) / 0.35;
+    r = spinnerR * Math.sqrt(Math.max(0, 1 - tn * tn));
   } else if (t < 0.7) {
     // Cylindrical body where blades attach
     r = spinnerR;
@@ -222,41 +247,51 @@ for (let i = 0; i <= HUB_STATIONS; i++) {
     r = spinnerR * (1 - 0.25 * tb * tb);
   }
 
-  hubProfiles.push(circle2d(Math.max(r, 3)));
-  hubHeights.push(-spinnerLen * 0.35 + t * spinnerLen);
+  hubProfiles.push(circle2d(Math.max(r, 0.8)));
+  hubHeights.push(-spinnerLen * 0.525 + t * spinnerLen);
 }
 
 const spinner = loft(hubProfiles, hubHeights, { edgeLength: meshRes });
 
 // ─── Assembly ───────────────────────────────────────────────────
+//
+// Real propellers are built from separate parts: the blades bolt into an
+// internal hub barrel, and the spinner is a thin dome with blade-shaped
+// cutouts (with running clearance) that the blades pass through. Modeling
+// it that way also keeps the aerodynamic skin free of boolean cuts and
+// near-tangent surface overlaps.
 
 const allBlades = circularPattern(blade, numBlades);
 
+// Internal hub barrel the blade shanks merge into (hidden by the spinner)
+const hubBarrel = cylinder(spinnerLen * 0.5, rHub * 0.62)
+  .translate(0, 0, -spinnerLen * 0.2);
+
+const bladeAssembly = union(allBlades, hubBarrel);
+
+// Blade-shaped cutouts through the spinner with a small running
+// clearance: the blade cross-section is grown in chord and thickness
+// (x/y before the radial rotation), keeping the span direction exact.
+const bladeCutout = bladeRaw.scale([1.04, 1.04, 1]).rotateY(90);
+const spinnerCutouts = circularPattern(bladeCutout, numBlades);
+
 // ─── Optional: Airfoil Section Visualization ────────────────────
 //
 // When enabled, shows thin extrusions of each airfoil cross-section
 // along the blade, revealing the twist and chord distribution.
 
 const result = [
-  { name: "Blades",  shape: allBlades.color('#2d2d30') },
-  { name: "Spinner", shape: spinner.color('#c8c8cc') },
+  { name: "Blades",  shape: bladeAssembly.color('#2d2d30') },
+  { name: "Spinner", shape: spinner.subtract(spinnerCutouts).color('#c8c8cc') },
 ];
 
 if (showSections) {
   const sectionShapes = [];
   for (let i = 0; i <= NUM_STATIONS; i++) {
-    const rNorm = i / NUM_STATIONS;
+    const rNorm = 0.5 - 0.5 * Math.cos(Math.PI * i / NUM_STATIONS);
     const r     = rHub + rNorm * (R - rHub);
 
-    const chord = Math.max(chordAt(rNorm), 5);
-    const thick = thicknessRatioAt(rNorm);
-    const camber = camberAt(rNorm);
-    const twist = twistAt(r);
-
-    let pts = nacaPoints(camber, CAMBER_POS, thick, chord, NACA_PTS);
-    pts = rotate2D(pts, 90 + twist);
-
-    const section = polygon(pts).extrude(2)
+    const section = bladeSection(rNorm, r).extrude(2)
       .rotateY(90)
       .translate(r, 0, 0)
       .color('#ff4422');

package/examples/nurbs-surface.forge.js

@@ -5,4 +5,4 @@ const grid = [
   [[0,20,1], [10,20,6], [20,20,6], [30,20,1]],
   [[0,30,0], [10,30,2], [20,30,2], [30,30,0]],
 ];
-return nurbsSurface(grid, { thickness: 1.5 });
+return Surface.Nurbs(grid, { thickness: 1.5 });