forgecad 0.7.0 → 0.8.0

package/dist-skill/docs-dev/component-model.md

@@ -0,0 +1,164 @@
+---
+skill-group: dev-conventions
+skill-order: 4
+---
+
+# The Component Model
+
+## Parts Are Components. Assemblies Are Composition.
+
+ForgeCAD's multi-part design model follows one principle:
+
+> **A part is a function from props to shape + connectors. It knows nothing about where it sits in the world. The assembly decides.**
+
+This is how React changed UI: components render content, the layout system positions them. Components don't know their screen coordinates. Before React, jQuery code positioned elements in page-space. After React, components are local and composable.
+
+ForgeCAD applies the same principle to mechanical design. Before: parts compute their assembly-space coordinates (translate to the right X, Y, Z, using a shared-dims file). After: parts build at origin in local space, declare connectors, and the assembly uses `connect()` to position everything.
+
+## The Three Rules
+
+### Rule 1: Parts Build at Origin
+
+A part is built in its own local coordinate system. Origin at `[0, 0, 0]`. No knowledge of the assembly. No imports of sibling part files. No global coordinate offsets.
+
+```js
+// WRONG — part positions itself in assembly space
+const rackPlaced = rack.translate(pinionPitchR, 0, layout.pinionZ);
+
+// RIGHT — part builds at origin, connector declares the interface
+const rack = lib.rackGear({ ... }).rotateZ(90);
+// pitch line at X=0, teeth face -X, local coordinates only
+return rack.withConnectors({
+  teeth: connector("rack-slide", { origin: [0, 0, faceWidth/2], axis: [0, 1, 0] }),
+});
+```
+
+### Rule 2: Connectors Are the Interface
+
+Every part that participates in an assembly declares connectors. A connector says: "here's where I connect, and here's what direction I face." It's the part's public interface — the only thing the assembly needs to know.
+
+```js
+return mount.withConnectors({
+  flange: connector("bolt-face", {
+    origin: [0, 0, 0],       // where the mating surface is
+    axis: [0, 0, 1],         // direction it faces (outward from part)
+  }),
+});
+```
+
+Connectors meet **face-to-face**. Both axes point outward from their respective parts. The system brings them together from opposite sides — like plugging a USB cable into a port.
+
+### Rule 3: The Assembly Is Pure Composition
+
+The assembly file does three things: instantiate parts with props, connect them, and define motion. Zero coordinate math. Zero translate calls. Zero shared-dims imports.
+
+```js
+assembly("Gripper")
+  .addPart("Base", base)
+  .addPart("Mount", mount)
+  .connect("Base.mount_face", "Mount.flange", { as: "mount-fix" })
+  .addPart("Pinion", pinion)
+  .connect("Base.pinion_seat", "Pinion.bore", { as: "spin" })
+  // ...
+```
+
+If you're writing `translate()` in an assembly file, something is wrong. Either the part should have a connector, or the prop should carry the dimension.
+
+## Data Flow: Props Down, Metadata Up
+
+Data flows in one direction: from parent (assembly) to children (parts).
+
+```
+Assembly (root)
+  ├── passes { servo, wall, clearance } → Motor Mount
+  │     └── returns { shape, boltPattern, flange connector }
+  ├── passes { gears, boltPattern } → Base Body
+  │     └── returns { shape, pinionZ, rack connectors }
+  ├── passes { gears, rackZ, armSpan } → Jaw Unit
+  │     └── returns { shape, armWidth, rack connector }
+  └── passes { boltPattern, armSlot } → Cover Plate
+        └── returns { shape, seat connector }
+```
+
+**Props flow down:** The assembly knows the cross-cutting decisions (base height, wall thickness, servo model) and passes them to parts as `require()` param overrides.
+
+**Metadata flows up:** Parts return their shape + connectors + any computed data that siblings need. The assembly reads this metadata and passes relevant pieces to other parts.
+
+**Siblings never import each other.** The cover plate doesn't import the motor mount to read bolt positions. The assembly reads the mount's bolt pattern and passes it to the cover plate. The parent mediates all sibling communication.
+
+```js
+// Assembly mediates sibling data flow
+const mount = require('./motor-mount.forge.js', { Wall: wall });
+const base  = require('./base-body.forge.js', {
+  Height: baseH,
+  BoltPattern: mount.boltPattern,  // parent passes mount's data to base
+});
+const cover = require('./cover-plate.forge.js', {
+  BoltPattern: mount.boltPattern,  // same data to cover
+  ArmSlot: jaw.armProfile,         // jaw's data to cover
+});
+```
+
+## Why This Matters
+
+### For Humans
+
+Each part file tells a complete story. You open `motor-mount.forge.js` and see everything: its geometry, its connectors, its parameters, its verifications. No chasing imports across 8 files. No 266-line shared-dims.js to understand.
+
+Modifying one part doesn't break siblings — connectors are the contract. Change the mount's internal cavity dimensions and nothing else changes, as long as the flange connector stays at the same position.
+
+### For AIs
+
+Each part file is self-contained context. An AI generates `base-body.forge.js` without reading `jaw-unit.forge.js`. The assembly file is a high-level plan — generate it from a natural language description. Props are the interface contract — the AI knows exactly what each part needs and provides.
+
+### For Swap-ability
+
+Change the servo model → the mount rebuilds with new cavity dimensions → its bolt pattern updates → the assembly passes the new pattern to base and cover → everything adapts. One change, cascading update, zero manual re-derivation.
+
+## The Connector Convention
+
+Connectors follow one convention: **face-to-face**.
+
+Each connector's axis points **outward** from its part — the direction the connection faces. When two connectors mate, the system negates one axis so they approach from opposite sides.
+
+- **Fixed joints** (bolt flange): both faces point outward, system brings them together
+- **Revolute joints** (hinge): both parts point outward along the hinge line, system opposes them
+- **Prismatic joints** (slider): both connectors point along the slide direction (co-directional exception — the slide axis IS the shared direction)
+
+```js
+// Base bottom face points down, mount flange points up → meet in the middle
+base.withConnectors({ mount_face: connector("bolt-face", { origin: [0,0,0], axis: [0,0,-1] }) });
+mount.withConnectors({ flange: connector("bolt-face", { origin: [0,0,0], axis: [0,0,1] }) });
+
+// Hinge: frame points up along hinge line, door points down → shared rotation axis
+frame.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,1] }) });
+door.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,-1] }) });
+```
+
+## One File vs. Many Files
+
+**Default: one file per assembly.** For a project-specific assembly (robot gripper, drone frame), put everything in one file. Parts are sections separated by comments. Shared data is just variables. This maximizes locality — you see the whole design by scrolling.
+
+**Split when:** A part is reusable across projects (standard servo cradle, parametric gear pair), or the file exceeds ~300 lines. Split parts into separate `.forge.js` files that export component functions.
+
+**Never split for "organization."** Eight files with 40 lines each is worse than one file with 300 lines. The context-switching cost of 8 files destroys locality.
+
+## What This Forbids
+
+1. **No shared-dims files.** If you're writing a file whose only job is to compute derived dimensions from component specs, the assembly should be doing that work (or the parts should derive their own internal dimensions from props).
+
+2. **No sibling imports.** A part file never `require()`s another part file. Data flows through the parent.
+
+3. **No assembly-space coordinates in parts.** A part doesn't know `pinionZ = 14`. It receives `rackZ: 14` as a prop, or it computes its own internal Z from its own props.
+
+4. **No `translate()` in assembly files.** If you're translating a part to position it, use a connector instead. The exception: ghost/reference geometry that isn't structural.
+
+5. **No console.log validation.** Use `verify.*` for spatial checks. It's structured, clickable, and fails visibly.
+
+## Design Gate
+
+**Every new multi-part example and every agent-built assembly must follow this model:**
+
+> Can you understand each part file without reading any other file? Does the assembly file contain zero coordinate math? Do all inter-part relationships flow through connectors and props?
+
+If the answer to any is no, refactor until it's yes.

package/dist-skill/docs-dev/generated/assembly.md

@@ -33,6 +33,8 @@ bomToCsv(rows: BomRow[]): string
 
 #### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
+**Use this from iteration 1 for any model with moving parts.** Hinges, sliders, gears, articulated fingers, doors — all start with `assembly()`, not with manual rotation math. Don't build a static "extended pose" first and refactor to an assembly later: joint sliders, animations, sweeps, collision detection, and robot export all flow from the kinematic graph.
+
 An assembly models a mechanism as a directed graph of parts connected by joints. Parts are the nodes; joints are directed edges from parent to child. The graph must be a forest (no cycles). Root parts (those with no incoming joint) are anchored to world space.
 
 Three joint types are supported: `'revolute'` (hinge), `'prismatic'` (slider), and `'fixed'` (rigid attachment). Use `addPart()` to add geometry, `addJoint()` (or the shorthands `addRevolute()`, `addPrismatic()`, `addFixed()`) to connect parts, and `solve()` to compute world-space positions at a given joint state.
@@ -62,7 +64,7 @@ assembly(name?: string): Assembly
 
 #### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
 
-This is a convenience wrapper for single-shape, single-joint use cases. It calls [`param()`](/docs/core#param) to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
+This is a convenience wrapper for single-shape, single-joint use cases. It calls `param()` to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
 
 ```ts
 const arm = joint("Shoulder", armShape, [0, 0, 20], {
@@ -268,22 +270,28 @@ addFixed(name: string, parent: string, child: string, options?: JointOptions): A
 
 Connector references use `"PartName.connectorName"` format. The system aligns connector origins (child connector lands exactly on parent connector) and derives the joint frame and axis from the connector geometry — no manual `frame` or `axis` math needed.
 
-The joint type is inferred from the connector's `kind` field if not specified in `options`. Use `flip: true` for mirrored parts whose connector axis is reflected.
+**Face-to-face convention:** Connectors always meet face-to-face, like a USB plug meeting a socket. Each connector's axis points "outward" from its part. When two connectors mate, the system brings them together so their axes oppose (anti-parallel). This is the same convention used by `matchTo()`.
+
+For a revolute joint (hinge), both connectors' axes should point outward from their respective parts along the hinge line. For a prismatic joint (slider), both axes should point along the slide direction from their part's perspective.
+
+The joint type is inferred from the connector's `kind` field if not specified in `options`.
 
 When connectors are defined with `start`/`end`, you can control which point on each connector meets via `align` / `parentAlign` / `childAlign` (`'start'`, `'middle'`, `'end'`).
 
 Use `connect()` when connector origins must physically coincide (flange-to-flange, bolt-into-bore). For mechanisms where parts share an axis but are deliberately spaced apart, use `addRevolute()` with pre-positioned parts instead.
 
 ```ts
-const mech = assembly("Arm")
-  .addPart("Base", base)
-  .addPart("Link", link)
-  .connect("Base.top", "Link.shoulder", {
-    as: "J1",
-    min: -90, max: 90, default: 0,
-  });
-
-return mech.solve({ J1: 45 }).toGroup();
+// Hinge: both axes point outward along the hinge line
+const frame = box(100, 10, 80).withConnectors({
+  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, 1] }),
+});
+const door = box(60, 4, 80).withConnectors({
+  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, -1] }),
+});
+assembly("Door")
+  .addPart("Frame", frame)
+  .addPart("Door", door)
+  .connect("Frame.hinge", "Door.hinge", { as: "swing", min: 0, max: 110 });
 ```
 
 ```ts