forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/guides/positioning.md

@@ -5,206 +5,147 @@ skill-order: 3
 
 # Positioning Strategy
 
-**This is the most important page for building multi-part assemblies.** Most positioning bugs come from manual coordinate arithmetic. Use the methods below in priority order.
+## Primitive origin convention
 
-## Priority Order
+All 3D primitives are **centered on XY, base at Z=0**:
 
-### 1. Connectors + `matchTo()` — Default choice for multi-part positioning
+| Primitive | X range | Y range | Z range |
+|-----------|---------|---------|---------|
+| `box(60, 40, 20)` | [-30, 30] | [-20, 20] | [0, 20] |
+| `cylinder(50, 10)` | [-10, 10] | [-10, 10] | [0, 50] |
+| `sphere(15)` | [-15, 15] | [-15, 15] | [-15, 15] |
+| `torus(20, 5)` | [-25, 25] | [-25, 25] | [-5, 5] |
 
-Define connectors on parts, then use `matchTo()` for automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's connector — origins coincide, axes oppose (plug-in model).
+Sphere and torus are fully centered (symmetric in Z). Box and cylinder sit on the XY ground plane — **Z goes up from zero, never negative**.
 
-```javascript
-// Define connectors on parts
-const shelf = box(200, 120, 10, true).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
-  right_tab: connector.male("dovetail", { origin: [100, 0, 0], axis: [1, 0, 0] }),
-});
+This means `box(w, d, h).translate(0, 0, -h/2)` is wrong for "center on Z" — the box is already at `[0, h]`, not `[-h/2, h/2]`.
 
-const panel = box(12, 120, 200, true).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
-  shelf_1: connector.female("dovetail", { origin: [6, 0, 50], axis: [1, 0, 0] }),
-});
-
-// Single pair: "put my left_tab into panel's shelf_0"
-const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
+---
 
-// Dictionary syntax for multiple pairs (same target):
-const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
+Most positioning bugs come from manual coordinate arithmetic. Use these methods in priority order.
 
-// Named group children auto-bubble connectors via dotted paths:
-const cabinet = group({ name: "Left", shape: panel });
-shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
-```
+## 1. `group()` — local coordinates for multi-part assemblies
 
-**Why connectors first:**
-- **Stable.** Connector positions are authored explicitly — they don't shift when you fillet, chamfer, or boolean the part.
-- **Semantic.** Connectors carry type and gender — `assembly.match()` validates compatibility before connecting.
-- **Oriented.** Full coordinate frame (origin + axis + up), not just a point.
-- **Queryable.** `shape.connectorDistance('a', 'b')` lets you derive dimensions from connector positions — e.g. compute pipe length from the distance between two fittings.
-- **Explode-aware.** Matched parts automatically separate along connector axes when the explode slider is used.
+The most common positioning bug: manually adding a parent's global offset to every sub-part. One wrong sign or forgotten variable and parts float into space. **Use `group()` to build parts in local coordinates (at the origin), then position the group once.**
 
-**Connector patterns:**
 ```javascript
-// Pipe length derived from connector spacing
-const length = frame.connectorDistance('inlet', 'outlet');
-const pipe = cylinder(length, radius);
-
-// Assembly-level connector matching with joint creation
-assembly
-  .addPart("Frame", frame)
-  .addPart("Door", door)
-  .match("Door", "Frame", { hinge_top: "hinge_top", hinge_bottom: "hinge_bottom" });
-
-// Query connector metadata
-const measurements = fitting.connectorMeasurements('flange');
-const outerDiam = measurements.outerDiameter;
+// BAD — every sub-part repeats the parent's global position
+const unitY = -18, unitZ = 70;
+const body = lib.roundedBox(100, 20, 32, 4).translate(0, unitY, unitZ);
+const panel = box(98, 2, 18).translate(0, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(0, unitY - 14, unitZ - 11);
+const led = sphere(1.2).translate(35, unitY - 12, unitZ + 9);
+
+// GOOD — build at local origin, group, translate once
+const body = lib.roundedBox(100, 20, 32, 4);
+const panel = box(98, 2, 18).translate(0, -12, 4);        // relative to local origin
+const louver = box(88, 2, 6).translate(0, -14, -11);      // relative to local origin
+const led = sphere(1.2).translate(35, -12, 9);             // relative to local origin
+const indoorUnit = group(
+  { name: 'Body', shape: body },
+  { name: 'Panel', shape: panel },
+  { name: 'Louver', shape: louver },
+  { name: 'LED', shape: led },
+).translate(0, -18, 70);  // ONE translate for the whole assembly
 ```
 
-### 2. `pointAlong()` — Orient cylinders/extrusions before positioning
-
-Cylinders default to Z-up. Instead of `rotate(90, 0, 0)` (which is confusing), use `pointAlong()`:
+**Groups nest.** Build sub-assemblies as groups, then group those into larger assemblies — each level has its own local origin.
 
 ```javascript
-// Pipe running along Y axis
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]);
-
-// Axle along X
-const axle = cylinder(80, 3).pointAlong([1, 0, 0]);
+const fan = group(hub, ...blades).translate(0, 25, 0);  // fan assembly
+const outdoorUnit = group(
+  { name: 'Body', shape: casing },
+  { name: 'Fan', shape: fan },             // already a group
+  { name: 'Grille', shape: grille },
+).translate(0, 23, -42);                    // position the whole outdoor unit
 ```
 
-**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
+**When to use something else:** `group()` preserves individual shapes — you can't boolean (subtract/intersect) a group. If a sub-part needs a boolean with the parent body, do that boolean first in local coordinates, then group the result.
 
-### 3. `attachTo()` — Quick bounding-box positioning
+## 2. Connectors + `matchTo()` — default for mating interfaces
 
-For simple "stack this on that" placement where you don't need connectors. Uses bounding-box anchor points — fast to write but fragile if geometry changes.
+Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
 
 ```javascript
-const base = box(100, 100, 10);
-const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
+const shelf = box(200, 120, 10, true).withConnectors({
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+});
+const panel = box(12, 120, 200, true).withConnectors({
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+});
+const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
+// Dictionary form for multiple pairs on same target:
+const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
+// Named group children bubble connectors via dotted paths:
+const cabinet = group({ name: "Left", shape: panel });
+shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
 ```
 
-`child.attachTo(parent, parentAnchor, selfAnchor, offset)` — parentAnchor/selfAnchor are bounding-box anchors like `'top'`, `'bottom-front-left'`, etc.
-
-**Limitations:** Anchor points are derived from the bounding box, so they shift when you fillet, chamfer, or boolean the part. No orientation, no validation, no semantic meaning. Prefer connectors for anything beyond quick prototyping.
-
-### 5. `rotateAroundTo()` — Aim a point around a hinge/axis
+**Why connectors first:** stable (don't shift on fillet/chamfer/boolean), semantic (carry type/gender), oriented (full frame), queryable (`shape.connectorDistance('a','b')`), explode-aware.
 
-Use this when a part already has the correct pivot/axis, and you want to solve the angle from geometry instead of doing trig by hand.
+## 3. `pointAlong()` — orient cylinders before positioning
 
 ```javascript
-const arm = box(80, 8, 8, true)
-  .translate(40, 0, 0)
-  .withReferences({ points: { tip: [80, 0, 0] } });
-
-// Rotate around Z until the tip lies in the plane formed by the Z axis and the target point
-const aimed = arm.rotateAroundTo(
-  [0, 0, 1],
-  [0, 0, 0],
-  "tip",
-  [30, 30, 20],
-);
-
-// Exact line solve: throws if the target line is unreachable while preserving radius about the axis
-const lineHit = arm.rotateAroundTo(
-  [0, 0, 1],
-  [0, 0, 0],
-  "tip",
-  [30, 30, 0],
-  { mode: 'line' },
-);
+// BAD
+const pipe = cylinder(100, 5).rotateX(90).translate(x, y, z);
+// GOOD — reads as "pipe pointing along Y"
+const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
 ```
 
-### 6. `moveToLocal()` — Position relative to another shape's corner
+**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
 
-When you need to place something at a specific offset from another shape's bounding box origin (min corner):
+## 4. `attachTo()` — quick bounding-box positioning
 
 ```javascript
-const base = box(100, 100, 10);
-const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
+const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
 ```
 
-### 7. `translate()` — Only for simple offsets or connecting independently-positioned parts
+`child.attachTo(parent, parentAnchor, selfAnchor, offset)`. Anchor points shift on fillet/chamfer/boolean — fragile for assembly interfaces, fine for quick prototyping.
 
-Use `translate()` when:
-- Moving a shape by a known fixed amount
-- Positioning between two shapes whose locations you've already computed via `boundingBox()`
+## 5. `rotateAroundTo()` — aim a point around a hinge/axis
 
 ```javascript
-// Pipe spanning between two independently-positioned units
-const bb1 = indoor.boundingBox();
-const bb2 = outdoor.boundingBox();
-const pipeLen = bb2.min[1] - bb1.max[1];
-const pipe = cylinder(pipeLen, 5)
-  .pointAlong([0, 1, 0])
-  .translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
+const aimed = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 20]);
+// Exact line solve:
+const lineHit = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 0], { mode: 'line' });
 ```
 
-### 8. `placeReference()` / named import references — For reusable multi-file parts
-
-When a part will be imported elsewhere, define semantic placement references once in the source file:
+## 6. `moveToLocal()` — offset from another shape's min corner
 
 ```javascript
-// widget.forge.js
-return union(base, post).withReferences({
-  points: {
-    mount: [0, -16, -4],
-  },
-  objects: {
-    post,
-  },
-});
+const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
 ```
 
-Then consume them in the importing file:
+## 7. `translate()` — for simple offsets or bridging computed locations
 
 ```javascript
-const widget = require("./widget.forge.js")
-  .placeReference("mount", [120, 40, 0]);
+const pipeLen = bb2.min[1] - bb1.max[1];
+const pipe = cylinder(pipeLen, 5).pointAlong([0, 1, 0]).translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
 ```
 
-Use this when manual coordinate math starts to feel like assembly bookkeeping. For cross-file parts that need proper alignment, prefer connectors on the exported shape over placement references.
+## 8. `placeReference()` — align any anchor to a world coordinate
 
-## Common Mistakes
+Place a shape so a named anchor point lands exactly where you want it. Accepts all built-in anchors (`'bottom'`, `'center'`, `'top-front-left'`, etc.) plus custom references from `withReferences()`.
 
-### ❌ Manual center-offset math
 ```javascript
-// BAD: easy to get wrong, hard to read
-const child = box(w, d, h, true)
-  .translate(0, -parentThickness/2 - d/2 - 5, parentHeight/2 - h/2 - 20);
-```
+// Ground a shape — bottom face center at Z = 0
+const grounded = shape.placeReference('bottom', [0, 0, 0])
 
-### ✅ Connector-based positioning
-```javascript
-// GOOD: stable, semantic, self-documenting
-const parent = box(100, 40, 60, true).withConnectors({
-  mount: connector.female("bracket", { origin: [0, -20, 10], axis: [0, -1, 0] }),
-});
-const child = box(w, d, h, true).withConnectors({
-  tab: connector.male("bracket", { origin: [0, d/2, 0], axis: [0, 1, 0] }),
-});
-const placed = child.matchTo(parent, "tab", "mount");
-```
+// Center at the world origin
+const centered = shape.placeReference('center', [0, 0, 0])
 
-### ❌ rotate() for cylinder orientation
-```javascript
-// BAD: which axis? what happens to center?
-const pipe = cylinder(100, 5).rotate(90, 0, 0).translate(x, y, z);
+// Align left edge to X = 10
+const aligned = shape.placeReference('left', [10, 0, 0])
 ```
 
-### ✅ pointAlong() for cylinder orientation
-```javascript
-// GOOD: reads as "pipe pointing along Y"
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
-```
+Also works with custom placement references for cross-file parts:
 
-### ❌ Bounding-box positioning for assembly interfaces
 ```javascript
-// BAD: fragile — changes if parent geometry is filleted or modified
-const shelf = plank.attachTo(sidePanel, 'left', 'right', [0, 0, -50]);
-```
+// widget.forge.js — define once
+return union(base, post).withReferences({ points: { mount: [0, -16, -4] } });
 
-### ✅ Connectors for assembly interfaces
-```javascript
-// GOOD: connector positions are explicit and stable
-const shelf = plank.matchTo(sidePanel, "left_tab", "shelf_slot_0");
+// importer — consume
+const widget = require("./widget.forge.js").placeReference("mount", [120, 40, 0]);
 ```
+
+For cross-file parts needing proper alignment, prefer connectors over placement references.

package/dist-skill/docs-dev/API/core/concepts.md

@@ -0,0 +1,78 @@
+---
+skill-group: core
+skill-order: 1
+---
+
+# ForgeCAD Core Concepts
+
+ForgeCAD scripts are JavaScript that returns geometry. The forge API is globally available — no imports needed.
+
+```javascript
+const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
+return box(width, 30, 10);
+```
+
+## Execution Model
+
+- Scripts re-execute on every parameter change (400ms debounce)
+- All operations are **immutable** — return new shapes, never modify in place
+- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Array` of shapes/sketches/groups, `Array` of `{ name, shape?, sketch?, color? }`, or a **metadata object** (see below)
+
+### Metadata Object Return
+
+A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
+
+```javascript
+// motor-mount.forge.js — renders standalone, exports metadata via require()
+const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
+return {
+  shape: mount.color('#556B2F'),                        // rendered
+  bolts: { dia: 5.3, pos: holePositions },              // metadata — skipped in render, available via require()
+};
+
+// base-body.forge.js — imports mount, accesses .bolts
+const mount = require('./motor-mount.forge.js');
+for (const [x, y] of mount.bolts.pos) { ... }          // use metadata
+// mount.shape is the Shape if you need it in an assembly
+```
+
+Arrays inside the object are also rendered:
+
+```javascript
+return {
+  parts: [{ name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }],
+  armWidth: 6,  // metadata
+};
+```
+
+## Coordinate System
+
+Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
+
+## Colors
+
+`.color(hex)` works on `Shape` and `Sketch`. Colors survive transforms. In booleans the first operand's color wins.
+
+**`union()` removes colors** — shapes merge into one solid mesh. Return named objects instead:
+
+```javascript
+return [
+  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
+  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
+];
+```
+
+## Face Operations
+
+Shapes carry semantic face labels through their lifecycle. The flow is:
+
+1. **Primitives** assign canonical names — `box()` gives you `top`, `bottom`, `side-left`, etc.; `cylinder()` gives `top`, `bottom`, `side`.
+2. **Extrusions** inherit labels from the sketch and add `top`/`bottom`.
+3. **Transforms** (translate, rotate, scale, mirror) preserve all labels.
+4. **Booleans** preserve labels from the first operand where geometry survives.
+
+You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
+
+## SDF Modeling
+
+For organic shapes, smooth blending, TPMS lattices, and surface deformations. SDF shapes convert via `.toShape()`. See [sdf-primitives.md](sdf-primitives.md).