forgecad 0.6.3 → 0.7.0

package/dist-skill/docs/generated/wood.md

@@ -0,0 +1,104 @@
+---
+skill-group: toolbox
+skill-order: 100
+---
+
+# Woodworking
+
+Wood boards with grain/species metadata, and joinery operations: dado, rabbet, mortise & tenon. Access via `Wood.*`.
+
+## Contents
+
+- [WoodBoard](#woodboard)
+- [Wood](#wood)
+
+---
+
+## Classes
+
+### `WoodBoard`
+
+A board of wood with metadata for manufacturing: grain direction, species, and dimensions. The underlying geometry is a simple box.
+
+Shape is mutable — joint operations (Wood.dado, Wood.rabbet, Wood.mortiseAndTenon) subtract material in-place. Transform methods return new WoodBoard instances preserving all metadata.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `shape` | `Shape` | The underlying 3D shape — mutable, joints modify it in-place. |
+| `width` | `number` | Board width (mm) — the longer flat dimension |
+| `height` | `number` | Board height (mm) — the shorter flat dimension |
+| `thickness` | `number` | Board thickness (mm) |
+| `grain` | `string` | Grain direction: "long" or "cross" |
+| `species` | `string` | Wood species, e.g. "birch", "oak" |
+| `material` | `string` | Material label for BOM |
+
+**Methods:**
+
+#### `cut()` — Subtract a cutter from this board, modifying it in-place. Used by joint functions (dado, rabbet, mortiseAndTenon).
+
+```ts
+cut(cutter: Shape): this
+```
+
+#### `translate()` — Translate the board in 3D space.
+
+```ts
+translate(x: number, y: number, z: number): WoodBoard
+```
+
+#### `rotate()` — Rotate the board around an axis by a given angle in degrees.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): WoodBoard
+```
+
+#### `rotateX()` — Rotate the board around the X axis by a given angle in degrees.
+
+```ts
+rotateX(angleDeg: number): WoodBoard
+```
+
+#### `rotateY()` — Rotate the board around the Y axis by a given angle in degrees.
+
+```ts
+rotateY(angleDeg: number): WoodBoard
+```
+
+#### `rotateZ()` — Rotate the board around the Z axis by a given angle in degrees.
+
+```ts
+rotateZ(angleDeg: number): WoodBoard
+```
+
+#### `mirror()` — Mirror the board across a plane defined by its normal.
+
+```ts
+mirror(normal: [ number, number, number ]): WoodBoard
+```
+
+#### `color()` — Set the board's display color.
+
+```ts
+color(value: string): WoodBoard
+```
+
+#### `clone()` — Clone the board (creates an independent copy of the underlying shape).
+
+```ts
+clone(): WoodBoard
+```
+
+---
+
+## Constants
+
+### `Wood`
+
+Woodworking namespace — create boards and cut joints. **Boards:** `Wood.board()` creates a WoodBoard with grain, species, and BOM metadata. **Joints:** `Wood.dado()`, `Wood.rabbet()`, `Wood.mortiseAndTenon()` mutate boards in-place by subtracting material, following the same pattern as LaserKit's [`fingerJoint()`](/docs/sheet-metal#fingerjoint).
+
+- `readonly board: (width: number, height: number, thickness: number, opts?: WoodBoardOptions) => WoodBoard` — Create a wood board with metadata for manufacturing. The board is a box(width, height, thickness) centered on XY, base at Z=0. Width along X, height along Y, thickness along Z (0 to thickness).
+- `dado(host: WoodBoard, guest: WoodBoard, opts: DadoOptions): void` — Cut a dado (channel) across the face of a host board for a guest board to sit in. Mutates `host.shape` by subtracting a rectangular channel.
+- `rabbet(board: WoodBoard, opts: RabbetOptions): void` — Cut a rabbet (L-shaped step) along an edge of a board. Mutates `board.shape` by subtracting a step from the specified edge.
+- `mortiseAndTenon(mortiseBoard: WoodBoard, tenonBoard: WoodBoard, opts?: MortiseAndTenonOptions): void` — Cut a mortise in one board and shape a tenon on another. Mutates both boards — subtracts the mortise pocket and removes shoulder material to form the tenon.

package/dist-skill/docs/guides/coordinate-system.md

@@ -17,19 +17,18 @@ ForgeCAD uses a **Z-up** right-handed coordinate system.
 
 ## Standard Views
 
-| View   | Camera position direction | Sees plane | Camera up |
-|--------|--------------------------|------------|-----------|
-| Front  | −Y (camera at −Y)        | XZ         | Z         |
-| Back   | +Y (camera at +Y)        | XZ         | Z         |
-| Right  | +X (camera at +X)        | YZ         | Z         |
-| Left   | −X (camera at −X)        | YZ         | Z         |
-| Top    | +Z (camera at +Z)        | XY         | +Y        |
-| Bottom | −Z (camera at −Z)        | XY         | −Y        |
-| Iso    | +X −Y +Z (diagonal)      | —          | Z         |
+| View   | Camera position direction | Sees plane |
+|--------|--------------------------|------------|
+| Front  | −Y                       | XZ         |
+| Back   | +Y                       | XZ         |
+| Right  | +X                       | YZ         |
+| Left   | −X                       | YZ         |
+| Top    | +Z                       | XY         |
+| Bottom | −Z                       | XY         |
 
 ## GizmoViewcube Face Mapping
 
-Three.js BoxGeometry material indices (cube face order):
+Three.js BoxGeometry material indices vs ForgeCAD labels (Z-up remapping):
 
 | Index | Three.js direction | ForgeCAD label |
 |-------|--------------------|----------------|
@@ -40,13 +39,8 @@ Three.js BoxGeometry material indices (cube face order):
 | 4     | +Z                 | Top            |
 | 5     | −Z                 | Bottom         |
 
-Default drei labels are `['Right', 'Left', 'Top', 'Bottom', 'Front', 'Back']` (Y-up).
-For Z-up we pass `faces={['Right', 'Left', 'Front', 'Back', 'Top', 'Bottom']}`.
-
-## Kernel Axis Convention
-
-Manifold (the geometry kernel) is Y-up internally. ForgeCAD is Z-up externally. If a kernel-facing operation behaves as if axes are swapped, check whether a Manifold call is still assuming Y-up semantics.
+Default drei labels are Y-up; ForgeCAD passes `faces={['Right','Left','Front','Back','Top','Bottom']}`.
 
 ## Grid
 
-The ground plane is XY (Z = 0). The grid lies on this plane.
+The ground plane is XY (Z = 0). Extrusion goes along +Z. Manifold is Y-up internally — if a kernel-facing operation behaves as if axes are swapped, check for Manifold Y-up semantics leaking through.

package/dist-skill/docs/guides/geometry-conventions.md

@@ -5,105 +5,48 @@ skill-order: 2
 
 # Geometry Conventions
 
-ForgeCAD wraps Manifold (a mesh kernel) and Three.js (a Y-up renderer). These libraries have their own conventions that conflict with each other and with CAD norms. This doc captures every convention mismatch and how ForgeCAD resolves it.
-
-**Core principle: the user script should never need to know about kernel or renderer internals.** If the user writes something geometrically reasonable, it should work. All convention translation happens inside ForgeCAD's layer.
+ForgeCAD wraps Manifold (mesh kernel) and Three.js (Y-up renderer). This doc captures convention mismatches and how ForgeCAD resolves them.
 
 ## Winding Order
 
-**What it is:** The order of vertices in a 2D polygon determines its "direction" — counter-clockwise (CCW) = positive area, clockwise (CW) = negative/zero area in Manifold's `CrossSection`.
-
-**The problem:** Manifold silently produces empty geometry for CW polygons. A user writing `polygon([[0,0], [50,0], [50,30]])` vs `polygon([[0,0], [50,30], [50,0]])` gets either a triangle or nothing, with no error.
-
-**ForgeCAD's fix:** All entry points that accept raw points auto-fix winding:
-- `polygon(points)` — computes signed area, reverses if CW
+CCW = positive area, CW = empty in Manifold's `CrossSection`. ForgeCAD auto-fixes at all entry points:
+- `polygon(points)` — computes signed area (shoelace), reverses if CW
 - `path().close()` — same fix
 
-**Signed area test** (shoelace formula):
-```
-signedArea = Σ (x₂ - x₁)(y₂ + y₁)
-```
-If `signedArea > 0` → CW → reverse to make CCW.
-
-**Implementation:** `src/forge/sketch/primitives.ts` (polygon), `src/forge/sketch/path.ts` (close).
-
-**Rule for new code:** Any function that takes user-provided point arrays and creates a `CrossSection` MUST auto-fix winding. Never pass raw user points to Manifold without this check.
+**Rule for new code:** Any function accepting user point arrays that creates a `CrossSection` MUST auto-fix winding.
 
 ## Coordinate System (Z-up vs Y-up)
 
-**The problem:** Three.js uses Y-up. CAD convention (and ForgeCAD) uses Z-up.
-
-**ForgeCAD's fix:** We set `camera.up = (0, 0, 1)` everywhere. Geometry coordinates are native Z-up — no matrix swizzling. The camera orientation handles the visual mapping.
-
-**Where this matters:**
-- `camera.up.set(0, 0, 1)` in `sceneBuilder.ts` and `render.ts`
-- GizmoViewcube face labels remapped (see coordinate-system.md)
-- Grid plane is XY (Z=0)
-- Extrusion goes along +Z
-- Revolution axis is Y (sketch plane), result maps to Z-up space
-
-**Rule for new code:** Never swap Y/Z in geometry. Always fix it at the camera/renderer level.
+Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0,0,1)`) — geometry coordinates are native Z-up. Never swap Y/Z in geometry.
 
 ## Revolution Axis
 
-**What it is:** `CrossSection.revolve()` in Manifold revolves around the Y axis. The sketch profile must be in the X-Y plane with X = radius (distance from axis) and Y = height.
-
-**The mapping:**
-- Profile X coordinate → radial distance from center
-- Profile Y coordinate → height (becomes Z after revolution)
-- Profile must be on the positive X side (X > 0) for valid geometry
-
-**Rule for new code:** Document which axis any new sweep/revolution operation uses. If it differs from user expectation, add a transform wrapper.
+`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
 
 ## Boolean Winding (3D)
 
-**What it is:** Manifold requires consistent face normals (outward-pointing) for boolean operations. Manifold handles this internally for its own primitives, but imported meshes or degenerate operations can produce inside-out faces.
-
-**ForgeCAD's fix:** We only create meshes through Manifold's own constructors (`extrude`, `revolve`, `cylinder`, `sphere`, etc.), which guarantee correct normals. No raw mesh import path exists yet.
-
-**Rule for new code:** If adding mesh import (STL, OBJ), run `Manifold.asOriginal()` or validate manifoldness before allowing booleans.
+Manifold requires consistent outward face normals. ForgeCAD only creates meshes through Manifold's own constructors, which guarantee correct normals.
 
 ## Transform Order
 
-**What it is:** Transforms are applied in call order (left to right in the chain). Default `rotate()`, `scale()`, and `mirror()` operate around the shape's own bounding-box center, so `shape.translate(10,0,0).rotate(0,0,45)` moves first and then spins in place. To orbit around world origin, use `rotateAround([0,0,0], ...)`.
+Transforms apply left-to-right. `rotate()`, `scale()`, `mirror()` operate around bounding-box center. Use `rotateAround([0,0,0], ...)` to orbit around world origin.
 
-**Convention:** This matches the standard "post-multiply" convention. No surprises here, but worth noting because some systems (OpenSCAD) apply transforms in reverse order.
-
-For explicit transform objects:
-- `A.mul(B)` means **apply A, then B**.
-- `composeChain(A, B, C)` means **A -> B -> C**.
-
-**Rule for new code:** Keep this chain order everywhere. Document any operation that deviates.
+For explicit transform objects: `A.mul(B)` = apply A then B; `composeChain(A, B, C)` = A→B→C.
 
 ## Assembly Frame Composition
 
-This is where regressions are most likely if convention is unclear.
-
-For a point in child geometry-local coordinates:
-- local -> `childBase` -> `jointMotion(value)` -> `jointFrame` -> `parentWorld`
-
-In Forge chain notation:
 ```ts
 childWorld = composeChain(childBase, jointMotion, jointFrame, parentWorld)
 ```
 
-Equivalent matrix-style equation (for reference):
-```txt
-T_world_child = T_parent_world * T_joint_frame * T_joint_motion * T_child_base
-```
-
-**Rule for new code:** In kinematics/assembly code, prefer `composeChain(...)` over manual `.mul(...).mul(...)` sequences to avoid order mistakes.
+Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code to avoid order mistakes.
 
-## Summary of Shield Points
-
-These are the places where ForgeCAD translates between "what the user means" and "what the kernel needs":
+## Summary
 
 | Convention | User sees | Kernel needs | Where we fix it |
 |---|---|---|---|
 | Winding | Any point order | CCW | `polygon()`, `path().close()` |
 | Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
-| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented, not auto-fixed |
+| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
 | Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
-| Transform order | Left-to-right chain | Post-multiply | Native match, no fix needed |
-
-When adding new geometry operations, check this table. If the operation introduces a new convention mismatch between user intent and kernel requirement, either auto-fix it (preferred) or document it clearly in the API docs.
+| Transform order | Left-to-right chain | Post-multiply | Native match |

package/dist-skill/docs/guides/modeling-recipes.md

@@ -5,246 +5,73 @@ skill-order: 1
 
 # Modeling Recipes
 
-This file collects patterns, best practices, debugging tips, and example snippets that are useful once you already know the model-building API.
-
 ## Iteration Bias
 
-- For unfamiliar or high-risk geometry work, start in a notebook and keep setup, experiments, and validation in separate cells until the structure is obvious.
-- Default to a buildable first pass instead of a long proposal when the user clearly wants geometry changed.
-- Replace a broken or incoherent model wholesale when that is faster and cleaner than incremental patching.
-- Keep printed hardware structurally honest: use it for guides, spacers, retainers, and moderate-load mechanisms; use wood or metal for primary strength.
-- Validate early with `forgecad run <file>` and refine from the actual runtime result.
-- Prefer a few clean part files over one giant script once a design has repeated hardware or a small mechanism.
-
-Notebook helpers worth using during iteration:
-
-- `show(...)` pins the current intermediate geometry in the viewport
-- `forgecad notebook view <file> preview` prints the preview cell with stored outputs in the terminal
-- `forgecad run <file>.forge-notebook.json` validates the preview cell and runs the usual spatial analysis
+- Default to a buildable first pass instead of a long proposal.
+- Replace a broken model wholesale when that is faster than incremental patching.
+- Validate early with `forgecad run <file>`.
 
 ## Common Patterns
 
-### Parametric Box with Holes
-```javascript
-const w = param("Width", 80, { min: 40, max: 150, unit: "mm" });
-const h = param("Height", 60, { min: 30, max: 100, unit: "mm" });
-const t = param("Thickness", 5, { min: 2, max: 10, unit: "mm" });
-const holeD = param("Hole Diameter", 8, { min: 4, max: 20, unit: "mm" });
-
-const base = box(w, h, t);
-const hole = cylinder(t + 2, holeD / 2).translate(w / 2, h / 2, -1);
-
-return base.subtract(hole);
-```
-
-### Hollow Shell (Wall Thickness)
+### Hollow Shell
 ```javascript
-const outer = param("Outer Size", 50, { min: 20, max: 100, unit: "mm" });
-const wall = param("Wall", 3, { min: 1, max: 10, unit: "mm" });
-
 const outerBox = box(outer, outer, outer, true);
 const innerBox = box(outer - 2 * wall, outer - 2 * wall, outer - 2 * wall, true);
-
 return outerBox.subtract(innerBox);
 ```
 
-### Array/Pattern
-```javascript
-const count = param("Count", 5, { min: 2, max: 10 });
-const spacing = param("Spacing", 15, { min: 5, max: 30, unit: "mm" });
-
-let shapes = [];
-for (let i = 0; i < count; i++) {
-  shapes.push(cylinder(10, 5).translate(i * spacing, 0, 0));
-}
-
-return union(...shapes);
-```
-
-### Sketch-Based Design
+### Sketch-Based Twist
 ```javascript
-const sides = param("Sides", 6, { min: 3, max: 12 });
-const radius = param("Radius", 25, { min: 10, max: 50, unit: "mm" });
-const height = param("Height", 60, { min: 20, max: 120, unit: "mm" });
-const wall = param("Wall", 3, { min: 1, max: 8, unit: "mm" });
-
 const outer = ngon(sides, radius);
 const inner = ngon(sides, radius - wall);
-const profile = outer.subtract(inner);
-
-return profile.extrude(height, { twist: 45, divisions: 32 });
+return outer.subtract(inner).extrude(height, { twist: 45, divisions: 32 });
 ```
 
 ### Rounded Profiles
 ```javascript
+// All convex corners — offset trick
 const base = rect(50, 30).offset(-3, 'Round').offset(3, 'Round');
-return base.extrude(10);
-```
-
-Use that pattern when every convex corner should round. For mixed sharp-and-rounded outlines, fillet only the intended vertices instead:
-
-```javascript
-const roofPoints = [
-  [0, 0],
-  [90, 0],
-  [90, 44],
-  [66, 74],
-  [45, 86],
-  [24, 74],
-  [0, 44],
-];
 
+// Selected corners only
 const roof = filletCorners(roofPoints, [
   { index: 3, radius: 19 },
   { index: 4, radius: 19 },
   { index: 5, radius: 19 },
 ]);
-
-return roof.extrude(12);
-```
-
-### Chamfers and Fillets
-```javascript
-const part = box(50, 50, 20);
-const chamfer = box(10, 60, 10)
-  .rotate(0, 45, 0)
-  .translate(50, -5, 15);
-
-return part.subtract(chamfer);
 ```
 
 ### Choosing the right sketch-rounding tool
 
-- `offset(-r).offset(+r)` for rounding every convex corner of a closed outline
-- `stroke(points, width, 'Round')` for centerline-based geometry such as ribs or traces
-- `filletCorners(points, ...)` for selective true-corner fillets on mixed profiles
+- `offset(-r).offset(+r)` — round every convex corner of a closed outline
+- `stroke(points, width, 'Round')` — centerline-based geometry (ribs, traces)
+- `filletCorners(points, ...)` — selective true-corner fillets on mixed profiles
 
 ## Best Practices
 
-### Performance
-- Boolean operations are expensive; minimize them
-- Use parameters for values that might change
-- Avoid deep nesting of operations in loops
-
-### Readability
-```javascript
-const base = box(100, 100, 10);
-const hole = cylinder(12, 8);
-const result = base.subtract(hole.translate(50, 50, 0));
-return result;
-```
-
-Prefer named intermediate values over deeply nested one-liners.
-
-### Units
-- All dimensions are millimeters by default
-- Angles are degrees
-- Use the `unit` parameter option when it helps the reader
-
-### Centering
-```javascript
-const centered = box(50, 50, 50, true).translate(x, y, z);
-const corner = box(50, 50, 50).translate(x - 25, y - 25, z - 25);
-```
-
-Centered primitives are usually easier to position.
+- All dimensions in millimeters; angles in degrees.
+- Primitives are centered on XY, base at Z=0. Use `placeReference('center', [0,0,0])` to center on all axes.
+- Prefer named intermediate values over deeply nested one-liners.
+- `union2d`, `difference2d`, `intersection2d` batch faster than chained `.add()` / `.subtract()`.
 
 ## Debugging
 
-### Console Output
 ```javascript
-console.log("Width:", width);
 console.log("Volume:", shape.volume());
 ```
 
-### Incremental Building
-```javascript
-const base = box(50, 50, 10);
-// return base;
-
-const withHole = base.subtract(cylinder(12, 5).translate(25, 25, 0));
-// return withHole;
-
-return withHole.add(cylinder(20, 3).translate(25, 25, 10));
-```
-
-For sketch-heavy work, compare the raw profile and the rounded profile before extruding:
+For sketch-heavy work, compare the raw profile and rounded profile side-by-side before extruding:
 
 ```javascript
-const raw = polygon(roofPoints);
-const rounded = filletCorners(roofPoints, [
-  { index: 3, radius: 19 },
-  { index: 4, radius: 19 },
-  { index: 5, radius: 19 },
-]);
-
 return [
-  { name: "Raw", sketch: raw },
-  { name: "Rounded", sketch: rounded.translate(120, 0) },
+  { name: "Raw", sketch: polygon(roofPoints) },
+  { name: "Rounded", sketch: filletCorners(roofPoints, [...]).translate(120, 0) },
 ];
 ```
 
-## Error Handling
-
-Common errors:
-- `"Kernel not initialized"` - internal/runtime issue, reload the app
-- `"Cannot read property of undefined"` - usually a bad variable name or missing declaration
-- invalid geometry - commonly caused by zero dimensions or self-intersecting sketches
-- script execution error - inspect the JS error in console output
-
-## Example Snippets
-
-### Parametric Phone Stand
-```javascript
-const width = param("Width", 80, { min: 40, max: 150, unit: "mm" });
-const depth = param("Depth", 60, { min: 30, max: 100, unit: "mm" });
-const thick = param("Thickness", 5, { min: 2, max: 15, unit: "mm" });
-const backH = param("Back Height", 40, { min: 20, max: 80, unit: "mm" });
-const cableD = param("Cable Hole", 8, { min: 4, max: 15, unit: "mm" });
-
-const base = box(width, depth, thick);
-const back = box(width, thick, backH).translate(0, depth - thick, thick);
-const lip = box(width, 10, 8).translate(0, 0, thick);
-const hole = cylinder(thick + 2, cableD / 2)
-  .rotate(90, 0, 0)
-  .translate(width / 2, depth / 2, -1);
-
-return union(base, back, lip).subtract(hole);
-```
-
-### Multi-Object Scene with Colors
-```javascript
-const base = box(100, 100, 5).color('#888888');
-const col1 = cylinder(40, 5).translate(20, 20, 5).color('#cc4444');
-const col2 = cylinder(40, 5).translate(80, 20, 5).color('#4444cc');
-const col3 = cylinder(40, 5).translate(50, 80, 5).color('#44cc44');
-const top = box(100, 100, 3).translate(0, 0, 45).color('#888888');
-
-return [
-  { name: "Base", shape: base },
-  { name: "Column A", shape: col1 },
-  { name: "Column B", shape: col2 },
-  { name: "Column C", shape: col3 },
-  { name: "Top", shape: top },
-];
-```
-
-### Entity-Based Design with Topology
-```javascript
-const baseRect = rectangle(0, 0, 80, 60);
-const base = baseRect.extrude(20);
-
-const result = filletEdge(base.toShape(), base.edge('vert-br'), 8, [-1, -1])
-  .hole(base.face('top'), { diameter: 6, u: -16, v: 10, depth: 8 });
-
-const holes = circularPattern(
-  cylinder(25, 4).translate(40, 30, -1),
-  4, 40, 30,
-);
-
-return result.subtract(holes);
-```
+## Common Errors
 
-Use the original tracked body (`base`) when you need semantic faces after edge finishing, and keep using its untouched sibling vertical tracked edges if you apply another supported fillet/chamfer later. Those sibling edges can now also survive a later supported union when the compiler still records one preserved propagated edge lineage for them. The currently selected finished edge is still recorded as a merged descendant set, so Forge does not claim a new durable tracked edge for that rewritten corner yet.
+- `"Kernel not initialized"` — internal/runtime issue, reload the app
+- zero dimensions or self-intersecting sketches → invalid geometry
+- wrong variable name → `"Cannot read property of undefined"`
 
 For larger runnable examples, read `examples/api/`.