forgecad 0.9.4 → 0.9.5

package/examples/api/sdf-pattern2d-grip-tread.forge.js

@@ -0,0 +1,72 @@
+// Native Pattern2D relief for a tactile grip: diamond tread, metal collars, no JS callbacks.
+
+scene({
+  background: { top: '#eef4f7', bottom: '#ccd8df' },
+  camera: { position: [82, -118, 54], target: [0, 0, 0], fov: 32 },
+  environment: { preset: 'studio', intensity: 1.35 },
+  lights: [
+    { type: 'ambient', color: '#ffffff', intensity: 0.24 },
+    { type: 'point', position: [56, -78, 78], color: '#ffffff', intensity: 2.1, distance: 260, decay: 1.12 },
+    { type: 'point', position: [-62, 48, 46], color: '#73d8ff', intensity: 1.25, distance: 230, decay: 1.2 },
+    { type: 'directional', position: [36, -52, 130], color: '#fff0cf', intensity: 0.62 },
+  ],
+  postProcessing: {
+    toneMappingExposure: 1.08,
+    bloom: { intensity: 0.1, threshold: 0.82, radius: 0.36 },
+    vignette: { darkness: 0.13, offset: 0.58 },
+  },
+});
+
+const p = sdf.pattern2d();
+
+const diamondTread = p
+  .stripes({ direction: [1, 1], spacing: 5.2, width: 1.05, depth: 0.42 })
+  .max(p.stripes({ direction: [1, -1], spacing: 5.2, width: 1.05, depth: 0.42 }))
+  .add(p.sineWave({ direction: [0, 1], wavelength: 19, amplitude: 0.06 }))
+  .clamp(-0.54, 0.04);
+
+const collarGrooves = p
+  .stripes({ direction: [0, 1], spacing: 2.4, width: 0.45, depth: 0.09 })
+  .add(p.sineWave({ direction: [1, 0], wavelength: 8, amplitude: 0.018 }))
+  .clamp(-0.12, 0.02);
+
+const rubber = (shape) =>
+  shape.color('#1f2227').material({
+    roughness: 0.86,
+    metalness: 0.02,
+    clearcoat: 0.08,
+    clearcoatRoughness: 0.72,
+  });
+
+const satinMetal = (shape) =>
+  shape.color('#c3cbd4').material({
+    roughness: 0.34,
+    metalness: 0.78,
+    clearcoat: 0.42,
+    clearcoatRoughness: 0.18,
+  });
+
+const grip = rubber(
+  sdf.cylinder(78, 13)
+    .shell(1.7)
+    .surfaceDisplace(diamondTread, { uv: 'cylinder' })
+    .subtract(sdf.cylinder(88, 9.0)),
+);
+
+const core = satinMetal(sdf.cylinder(86, 6.8));
+const leftCollar = satinMetal(
+  sdf.torus(13.2, 1.45).surfaceDisplace(collarGrooves, { uv: 'torus' }).translate(0, 0, -39),
+);
+const rightCollar = satinMetal(
+  sdf.torus(13.2, 1.45).surfaceDisplace(collarGrooves, { uv: 'torus' }).translate(0, 0, 39),
+);
+const endLips = satinMetal(sdf.box(1.1, 1.1, 5.0).circularArray(44, 15.2));
+
+return {
+  core,
+  grip,
+  leftCollar,
+  rightCollar,
+  leftEndKnurl: endLips.translate(0, 0, -41.5),
+  rightEndKnurl: endLips.translate(0, 0, 41.5),
+};

package/examples/api/sdf-pattern2d-orbital-jewelry.forge.js

@@ -0,0 +1,62 @@
+// Native Pattern2D relief plus folded circular array accents for an ornamental SDF piece.
+
+scene({
+  background: { top: '#101420', bottom: '#223242' },
+  camera: { position: [74, -104, 58], target: [0, 0, 4], fov: 31 },
+  environment: { preset: 'night', intensity: 1.18 },
+  lights: [
+    { type: 'ambient', color: '#172030', intensity: 0.18 },
+    { type: 'point', position: [48, -66, 72], color: '#ffd36f', intensity: 2.35, distance: 250, decay: 1.08 },
+    { type: 'point', position: [-52, 48, 58], color: '#58e5ff', intensity: 1.85, distance: 230, decay: 1.14 },
+    { type: 'point', position: [0, 36, 76], color: '#ff7ab8', intensity: 1.15, distance: 220, decay: 1.2 },
+    { type: 'directional', position: [28, -48, 138], color: '#ffffff', intensity: 0.58 },
+  ],
+  fog: { color: '#101420', near: 130, far: 330 },
+  postProcessing: {
+    toneMappingExposure: 1.32,
+    bloom: { intensity: 0.44, threshold: 0.56, radius: 0.56 },
+    vignette: { darkness: 0.42, offset: 0.44 },
+  },
+});
+
+const p = sdf.pattern2d();
+
+const braidedGold = p
+  .overUnderWeave({ spacing: 1.6, threadWidth: 0.72, depth: 0.18 })
+  .add(p.sineWave({ direction: [1, 0], wavelength: 7.2, amplitude: 0.035 }))
+  .clamp(-0.23, 0.04);
+
+const opalSkin = p
+  .sineWave({ direction: [1, 0], wavelength: 6, amplitude: 0.18 })
+  .add(p.sineWave({ direction: [0, 1], wavelength: 4.2, amplitude: 0.12 }))
+  .add(p.stripes({ direction: [1, 1], spacing: 5.5, width: 0.7, depth: 0.08 }))
+  .clamp(-0.2, 0.22);
+
+const gold = (shape) =>
+  shape.color('#e8b95f').material({
+    roughness: 0.25,
+    metalness: 0.92,
+    clearcoat: 0.45,
+    clearcoatRoughness: 0.08,
+    reflectivity: 0.72,
+  });
+
+const opal = (shape) =>
+  shape.color('#9be9dd').material({
+    roughness: 0.12,
+    metalness: 0,
+    clearcoat: 1,
+    clearcoatRoughness: 0.03,
+    opacity: 0.86,
+    transmission: 0.22,
+    reflectivity: 0.84,
+    ior: 1.42,
+  });
+
+const braidedBand = gold(sdf.torus(24, 2.9).surfaceDisplace(braidedGold, { uv: 'torus' }));
+const centerStone = opal(sdf.sphere(8.8).surfaceDisplace(opalSkin).translate(0, 0, 0.8));
+const beadHalo = gold(sdf.sphere(1.8).circularArray(32, 31).translate(0, 0, 0.8));
+const northStar = opal(sdf.sphere(3.3).surfaceDisplace(opalSkin).translate(0, 31, 1.1));
+const southStar = opal(sdf.sphere(3.3).surfaceDisplace(opalSkin).translate(0, -31, 1.1));
+
+return { braidedBand, centerStone, beadHalo, northStar, southStar };

package/examples/api/sdf-surface-basket-weave.forge.js

@@ -0,0 +1,67 @@
+// Native SDF surface relief — user-composed Pattern2D IR lowers to shader + CPU.
+// These raw SDF leaves raymarch directly; call .toShape() only for export.
+
+scene({
+  background: { top: '#f6fbff', bottom: '#dfe9f3' },
+  camera: { position: [92, -128, 72], target: [0, 0, 3], fov: 34 },
+  environment: { preset: 'studio', intensity: 1.2 },
+  lights: [
+    { type: 'ambient', color: '#ffffff', intensity: 0.22 },
+    { type: 'point', position: [56, -72, 86], color: '#fff0cf', intensity: 2.0, distance: 260, decay: 1.15 },
+    { type: 'point', position: [-70, 52, 64], color: '#79d9ff', intensity: 1.45, distance: 240, decay: 1.2 },
+    { type: 'directional', position: [36, -68, 150], color: '#ffffff', intensity: 0.7 },
+  ],
+  postProcessing: {
+    toneMappingExposure: 1.12,
+    bloom: { intensity: 0.18, threshold: 0.74, radius: 0.42 },
+    vignette: { darkness: 0.18, offset: 0.58 },
+  },
+});
+
+const textile = (shape, color) =>
+  shape.color(color).material({
+    roughness: 0.72,
+    metalness: 0,
+    clearcoat: 0.22,
+    clearcoatRoughness: 0.58,
+  });
+
+const p = sdf.pattern2d();
+const weave = p.overUnderWeave({ spacing: 2.8, threadWidth: 1.2, depth: 0.55 });
+const diagonalRipple = p.sineWave({ direction: [1, 1], wavelength: 11, amplitude: 0.08 });
+const bowlPattern = weave.add(diagonalRipple).clamp(-0.68, 0.08);
+
+const bowl = textile(
+  sdf.sphere(24)
+    .shell(1.8)
+    .surfaceDisplace(bowlPattern)
+    .subtract(sdf.box(70, 70, 36).translate(0, 0, 20))
+    .translate(-46, 0, 0),
+  '#d9826b',
+);
+
+const sleevePattern = p
+  .overUnderWeave({ spacing: 2.15, threadWidth: 0.95, depth: 0.45 })
+  .add(p.stripes({ direction: [1, 0], spacing: 7, width: 0.7, depth: 0.18 }));
+
+const sleeve = textile(
+  sdf.cylinder(38, 13)
+    .shell(1.4)
+    .surfaceDisplace(sleevePattern, { uv: 'cylinder' })
+    .subtract(sdf.cylinder(46, 9.8))
+    .translate(0, 0, 0),
+  '#6fa6a3',
+);
+
+const ringPattern = p
+  .overUnderWeave({ spacing: 1.75, threadWidth: 0.78, depth: 0.28 })
+  .add(p.sineWave({ direction: [0, 1], wavelength: 5.4, amplitude: 0.05 }));
+
+const ring = textile(
+  sdf.torus(18, 3.4)
+    .surfaceDisplace(ringPattern, { uv: 'torus' })
+    .translate(46, 0, 0),
+  '#c6a15b',
+);
+
+return { bowl, sleeve, ring };

package/examples/api/sector-gear-body.forge.js

@@ -0,0 +1,34 @@
+// Sector gear demo: partial tooth window composed with a visual/structural body.
+
+const moduleSize = Param.number("Module", 1.2, { min: 0.8, max: 2.5, step: 0.05, unit: "mm" });
+const teethOnFullCircle = Param.number("Pitch Teeth", 36, { min: 24, max: 72, integer: true });
+const toothCount = Param.number("Active Teeth", 11, { min: 2, max: 24, integer: true });
+const firstTooth = Param.number("First Tooth", 2, { min: 0, max: 35, integer: true });
+const faceWidth = Param.number("Face Width", 8, { min: 4, max: 16, unit: "mm" });
+
+const pitchRadius = (moduleSize * teethOnFullCircle) / 2;
+const rootRadius = pitchRadius - moduleSize * 1.25;
+const rimWidth = Math.max(2.4, moduleSize * 2);
+const hubDiameter = Math.max(8, moduleSize * 8);
+
+const body = lib.gearBodies.spoked({
+  outerRadius: rootRadius,
+  rimWidth,
+  hubDiameter,
+  boreDiameter: 5,
+  spokeCount: 5,
+  spokeWidth: Math.max(2, moduleSize * 1.8),
+  faceWidth,
+});
+
+const sector = lib.sectorGear({
+  module: moduleSize,
+  teethOnFullCircle,
+  firstTooth: Math.min(firstTooth, teethOnFullCircle - 1),
+  toothCount: Math.min(toothCount, teethOnFullCircle),
+  pressureAngleDeg: 20,
+  faceWidth,
+  body,
+});
+
+return [{ name: "Sector Gear", shape: sector.color("#d5a15f") }];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgecad",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Code-first parametric CAD for JavaScript/TypeScript, in the browser and CLI.",
   "license": "BUSL-1.1",
   "type": "module",

package/dist/docs-raw/skills/forgecad-api-dogfood.md

@@ -1,130 +0,0 @@
-# forgecad-api-dogfood
-
-Build a ForgeCAD model while actively hunting for API friction — missing helpers, awkward patterns, bad defaults, verbose boilerplate. Use when asked to dogfood, stress-test the API, or build a model with the goal of improving ForgeCAD.
-
-| Field | Value |
-| --- | --- |
-| Installed by | `forgecad skill install` |
-| Source | `skills/forgecad-api-dogfood/SKILL.md` |
-
----
-
-## API Dogfood: Build to Find Friction
-
-Build a real ForgeCAD model **and** systematically surface every point where the API fights the developer. The model is the vehicle; the real output is a prioritized list of API improvements with concrete proposals.
-
-### Mindset
-
-You are Steve Jobs reviewing a developer API. Every extra line of code is a failure of the framework. Every time you think "I wish I could just..." — that's a finding. The API should make the obvious thing trivial, the common thing easy, and the hard thing possible.
-
-### Workflow
-
-#### 1. Pick or receive a model to build
-
-Choose something that exercises real geometry: curves, patterns, assemblies, boolean operations, fillets, parametric dimensions. Simple boxes won't surface friction. Good candidates:
-- Mechanical parts (gears, hinges, enclosures)
-- Organic shapes (vases, sculptures, ergonomic grips)
-- Multi-part assemblies (furniture, toys, mechanisms)
-- Patterns and repetition (tiles, lattices, arrays)
-
-#### 2. Load the ForgeCAD skill
-
-Invoke the `forgecad` skill to get the current API docs. Read the Core API reference thoroughly — you need to know what exists before you can identify what's missing.
-
-#### 3. Build bottom-up, journal friction as you go
-
-Follow the same decomposition strategy as forgecad-make-a-model (smallest piece first, verify, compose upward). But at every step, maintain a **friction journal** — a running list of issues encountered.
-
-For each friction point, capture:
-- **What you were trying to do** (intent)
-- **What you had to write** (actual code)
-- **What you wish you could write** (dream API)
-- **Category** (see below)
-
-#### 4. Friction categories
-
-| Category | Description | Example |
-|----------|-------------|---------|
-| **Missing primitive** | A common shape/op that doesn't exist | No `torus()`, no `wedge()` |
-| **Verbose boilerplate** | Too many lines for a simple intent | 5 lines to create a circular pattern |
-| **Bad defaults** | Default behavior is rarely what you want | `center` defaulting to `false` when `true` is almost always better |
-| **Missing transform** | A transform that should be chainable but isn't | No `.mirrorX()` shorthand |
-| **Naming friction** | Name doesn't match mental model | Function named differently than what you'd search for |
-| **Composition gap** | Hard to combine things that should compose naturally | Can't easily array along a curve |
-| **Error unhelpfulness** | Error message doesn't help you fix the problem | "Invalid geometry" with no indication of where or why |
-| **Discovery gap** | Feature exists but you couldn't find it | Had to read source to discover a useful helper |
-| **Parameter awkwardness** | Argument order or types feel wrong | Height before radius when you think radius-first |
-
-#### 5. Validate the model
-
-Run `forgecad run <file>` after each piece. Note any errors — confusing error messages are themselves friction findings.
-
-#### 6. Write the friction report
-
-After the model is complete, produce a structured report. Place it alongside the model file as `<model-name>.friction.md`.
-
-```markdown
-# API Friction Report: <Model Name>
-
-## Summary
-- Model: <what was built>
-- Lines of code: <count>
-- Friction points found: <count>
-- Estimated lines with dream API: <count>
-
-## Critical (API should not ship without fixing)
-### <Title>
-- **Intent**: What I wanted to do
-- **Actual**: ```js\n<what I had to write>\n```
-- **Dream**: ```js\n<what I wish I could write>\n```
-- **Proposed fix**: Concrete API change
-
-## High (Common operation, significant friction)
-...
-
-## Medium (Nice to have)
-...
-
-## Low (Paper cuts)
-...
-```
-
-#### 7. Propose API changes
-
-For the top 3 friction points, go beyond the report:
-- Draft the actual API signature
-- Show how it would simplify the model code
-- Check if it conflicts with existing API surface
-- Estimate implementation complexity (trivial / moderate / significant)
-
-If a fix is trivial (< 20 lines, no breaking changes), offer to implement it right now.
-
-### What makes a great friction finding
-
-- **Specific**: "I needed 4 lines to round-robin colors on an array" not "coloring is hard"
-- **Comparative**: Show the actual code vs. the dream code side by side
-- **Prioritized**: Based on how often other users would hit this, not just your annoyance
-- **Actionable**: Includes a concrete proposal, not just a complaint
-
-### Anti-patterns to avoid
-
-- Don't invent API surface nobody would use just because you can imagine it
-- Don't confuse "I didn't know about this feature" with "this feature is missing" — check the docs first
-- Don't propose breaking changes for minor ergonomic gains
-- Don't let the friction hunt derail the model — build the model first, journal as you go
-- Don't propose thin wrappers that add no real value (`.moveRight(x)` vs `.translate([x,0,0])`)
-
-### File Placement
-
-Place model files in the ForgeCAD project under:
-```
-docs/temporary/dogfood/YYYY-MM-DD/<model-name>.forge.js
-docs/temporary/dogfood/YYYY-MM-DD/<model-name>.friction.md
-```
-
-### Tips
-
-- The most valuable friction is the kind you almost didn't notice — the "oh I always have to do this" patterns
-- Compare with other CAD APIs (OpenSCAD, CadQuery, JSCAD) — what do they make easy that we don't?
-- Pay special attention to the first 5 minutes of building — onboarding friction compounds
-- If you find yourself copy-pasting code between parts, that's a composition gap

package/dist-skill/library/forgecad-api-dogfood/SKILL.md

@@ -1,125 +0,0 @@
----
-name: forgecad-api-dogfood
-description: Build a ForgeCAD model while actively hunting for API friction — missing helpers, awkward patterns, bad defaults, verbose boilerplate. Use when asked to dogfood, stress-test the API, or build a model with the goal of improving ForgeCAD.
-forgecad-public: true
----
-
-# API Dogfood: Build to Find Friction
-
-Build a real ForgeCAD model **and** systematically surface every point where the API fights the developer. The model is the vehicle; the real output is a prioritized list of API improvements with concrete proposals.
-
-## Mindset
-
-You are Steve Jobs reviewing a developer API. Every extra line of code is a failure of the framework. Every time you think "I wish I could just..." — that's a finding. The API should make the obvious thing trivial, the common thing easy, and the hard thing possible.
-
-## Workflow
-
-### 1. Pick or receive a model to build
-
-Choose something that exercises real geometry: curves, patterns, assemblies, boolean operations, fillets, parametric dimensions. Simple boxes won't surface friction. Good candidates:
-- Mechanical parts (gears, hinges, enclosures)
-- Organic shapes (vases, sculptures, ergonomic grips)
-- Multi-part assemblies (furniture, toys, mechanisms)
-- Patterns and repetition (tiles, lattices, arrays)
-
-### 2. Load the ForgeCAD skill
-
-Invoke the `forgecad` skill to get the current API docs. Read the Core API reference thoroughly — you need to know what exists before you can identify what's missing.
-
-### 3. Build bottom-up, journal friction as you go
-
-Follow the same decomposition strategy as forgecad-make-a-model (smallest piece first, verify, compose upward). But at every step, maintain a **friction journal** — a running list of issues encountered.
-
-For each friction point, capture:
-- **What you were trying to do** (intent)
-- **What you had to write** (actual code)
-- **What you wish you could write** (dream API)
-- **Category** (see below)
-
-### 4. Friction categories
-
-| Category | Description | Example |
-|----------|-------------|---------|
-| **Missing primitive** | A common shape/op that doesn't exist | No `torus()`, no `wedge()` |
-| **Verbose boilerplate** | Too many lines for a simple intent | 5 lines to create a circular pattern |
-| **Bad defaults** | Default behavior is rarely what you want | `center` defaulting to `false` when `true` is almost always better |
-| **Missing transform** | A transform that should be chainable but isn't | No `.mirrorX()` shorthand |
-| **Naming friction** | Name doesn't match mental model | Function named differently than what you'd search for |
-| **Composition gap** | Hard to combine things that should compose naturally | Can't easily array along a curve |
-| **Error unhelpfulness** | Error message doesn't help you fix the problem | "Invalid geometry" with no indication of where or why |
-| **Discovery gap** | Feature exists but you couldn't find it | Had to read source to discover a useful helper |
-| **Parameter awkwardness** | Argument order or types feel wrong | Height before radius when you think radius-first |
-
-### 5. Validate the model
-
-Run `forgecad run <file>` after each piece. Note any errors — confusing error messages are themselves friction findings.
-
-### 6. Write the friction report
-
-After the model is complete, produce a structured report. Place it alongside the model file as `<model-name>.friction.md`.
-
-```markdown
-# API Friction Report: <Model Name>
-
-## Summary
-- Model: <what was built>
-- Lines of code: <count>
-- Friction points found: <count>
-- Estimated lines with dream API: <count>
-
-## Critical (API should not ship without fixing)
-### <Title>
-- **Intent**: What I wanted to do
-- **Actual**: ```js\n<what I had to write>\n```
-- **Dream**: ```js\n<what I wish I could write>\n```
-- **Proposed fix**: Concrete API change
-
-## High (Common operation, significant friction)
-...
-
-## Medium (Nice to have)
-...
-
-## Low (Paper cuts)
-...
-```
-
-### 7. Propose API changes
-
-For the top 3 friction points, go beyond the report:
-- Draft the actual API signature
-- Show how it would simplify the model code
-- Check if it conflicts with existing API surface
-- Estimate implementation complexity (trivial / moderate / significant)
-
-If a fix is trivial (< 20 lines, no breaking changes), offer to implement it right now.
-
-## What makes a great friction finding
-
-- **Specific**: "I needed 4 lines to round-robin colors on an array" not "coloring is hard"
-- **Comparative**: Show the actual code vs. the dream code side by side
-- **Prioritized**: Based on how often other users would hit this, not just your annoyance
-- **Actionable**: Includes a concrete proposal, not just a complaint
-
-## Anti-patterns to avoid
-
-- Don't invent API surface nobody would use just because you can imagine it
-- Don't confuse "I didn't know about this feature" with "this feature is missing" — check the docs first
-- Don't propose breaking changes for minor ergonomic gains
-- Don't let the friction hunt derail the model — build the model first, journal as you go
-- Don't propose thin wrappers that add no real value (`.moveRight(x)` vs `.translate([x,0,0])`)
-
-## File Placement
-
-Place model files in the ForgeCAD project under:
-```
-docs/temporary/dogfood/YYYY-MM-DD/<model-name>.forge.js
-docs/temporary/dogfood/YYYY-MM-DD/<model-name>.friction.md
-```
-
-## Tips
-
-- The most valuable friction is the kind you almost didn't notice — the "oh I always have to do this" patterns
-- Compare with other CAD APIs (OpenSCAD, CadQuery, JSCAD) — what do they make easy that we don't?
-- Pay special attention to the first 5 minutes of building — onboarding friction compounds
-- If you find yourself copy-pasting code between parts, that's a composition gap