forgecad 0.6.3 → 0.7.0

package/dist/docs-raw/generated/assembly.md

@@ -5,85 +5,78 @@ skill-order: 100
 
 # Assembly API
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Kinematic assemblies, joints, couplings, and robot export.
 
+## Contents
+
+- [Assembly & Joints](#assembly-joints) — `bomToCsv`, `assembly`, `joint`
+- [Assembly](#assembly) — Structure, Joints, Solving
+- [ImportedAssembly](#importedassembly)
+- [SolvedAssembly](#solvedassembly)
+- [MateBuilder](#matebuilder)
+
 ## Functions
 
 ### Assembly & Joints
 
-Build kinematic assemblies with joints and couplings.
+#### `bomToCsv()` — Convert an array of BOM rows into a CSV string.
 
-#### `bomToCsv()`
+Produces a CSV with columns: `part`, `qty`, `material`, `process`, `tolerance`, `notes`. String values are quoted and internal double-quotes are escaped. Prefer calling `solvedAssembly.bomCsv()` directly — this function is exposed for custom BOM processing.
 
 ```ts
 bomToCsv(rows: BomRow[]): string
 ```
 
-Convert BOM rows from a solved assembly into a CSV string.
+**`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
 
-<details><summary><code>BomRow</code></summary>
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-```ts
-interface BomRow {
-  part: string;
-  qty: number;
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  notes?: string;
-  metadata?: PartMetadata;
-}
-```
+#### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
-</details>
+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.
 
-<details><summary><code>PartMetadata</code></summary>
+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.
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+The higher-level `connect()` API uses declared **connectors** to compute joint frames automatically. The `match()` API uses typed connectors (with gender and type metadata) for automatic compatibility validation and joint creation.
 
-</details>
+For multi-file assemblies, a file that returns an `Assembly` is importable via [`require()`](/docs/core#require) and yields an `ImportedAssembly`. Use `mergeInto()` to flatten a sub-assembly into a parent assembly.
 
-#### `assembly()`
+```ts
+const mech = assembly("Arm")
+  .addPart("base", box(80, 80, 20, true), {
+    metadata: { material: "PETG", process: "FDM", qty: 1 },
+  })
+  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
+  .addRevolute("shoulder", "base", "link", {
+    axis: [0, 1, 0],
+    min: -30, max: 120, default: 25,
+    frame: Transform.identity().translate(0, 0, 20),
+  });
+
+return mech; // auto-solved at defaults, renders all parts
+```
 
 ```ts
 assembly(name?: string): Assembly
 ```
 
-Create an assembly container with named parts and joints for kinematic mechanisms. Build with addPart(), addJoint(), addJointCoupling(), addGearCoupling(), then solve() to get positioned parts. Supports revolute, prismatic, and fixed joint types.
+#### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
 
-#### `joint()`
+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.
 
 ```ts
-joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
+const arm = joint("Shoulder", armShape, [0, 0, 20], {
+  axis: [0, 1, 0],
+  min: -30, max: 120, default: 25,
+});
+return arm;
 ```
 
-Create a revolute (hinge) joint. Auto-creates a param slider and rotates the shape.
-
-<details><summary><code>RevoluteJointOpts</code></summary>
-
 ```ts
-interface RevoluteJointOpts {
-  min?: number;
-  max?: number;
-  default?: number;
-  unit?: string;
-  reverse?: boolean;
-}
+joint(name: string, shape: Shape, pivot: [ number, number, number ], opts?: RevoluteJointOpts): Shape
 ```
 
-</details>
+`RevoluteJointOpts`: `{ min?: number, max?: number, default?: number, unit?: string, reverse?: boolean }`
 
 ---
 
@@ -91,61 +84,507 @@ interface RevoluteJointOpts {
 
 ### `Assembly`
 
+Container for a kinematic mechanism made up of named parts and joints.
+
+An assembly is a directed graph where **parts** are nodes and **joints** are directed edges from parent to child. The graph must be a forest (one or more trees with no cycles). Root parts (no incoming joint) are fixed to world space.
+
+Each joint carries a `frame` transform (from the parent part frame to the joint's zero-state frame) and a motion formula:
+
+```
+childWorld = parentWorld × frame × motion(value) × childBase
+```
+
+Three joint types are supported:
+
+- **revolute** — rotates the child around an axis by `value` degrees
+- **prismatic** — translates the child along an axis by `value` mm
+- **fixed** — no motion; rigidly attaches the child at `frame`
+
+**Quick start**
+
+```ts
+const mech = assembly("Arm")
+  .addPart("base", box(80, 80, 20, true))
+  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
+  .addJoint("shoulder", "revolute", "base", "link", {
+    axis: [0, 1, 0],
+    min: -30, max: 120, default: 25,
+    frame: Transform.identity().translate(0, 0, 20),
+  });
+
+return mech; // auto-solved at defaults
+```
+
+Returning an unsolved `Assembly` auto-solves at default joint values. Return a `SolvedAssembly` directly for a specific pose:
+
+```ts
+return mech.solve({ shoulder: 60 });
+```
+
+**Return types**
+
+| Return value | Standalone | `require()` result type | |---|---|---| | `Assembly` (unsolved) | yes | `ImportedAssembly` | | `SolvedAssembly` | yes | `SolvedAssembly` |
+
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
 | `name` | `string` | — |
 
-**Methods:**
+**Solving**
+
+#### `solve()` — Solve the assembly at the given joint state and return positioned parts.
+
+Performs a depth-first traversal of the joint graph. Each joint's value is taken from `state`, falling back to `defaultValue`. Coupled joints compute their value from source joints. Values outside `[min, max]` are clamped (a warning is added to `SolvedAssembly.warnings()`).
+
+If mate constraints were registered via `mate()`, the solver runs a pre-pass to derive base transforms, then the kinematic DFS applies joints on top of those positions.
+
+**Pitfall — [`jointsView`](/docs/viewport#jointsview) double-rotation:** When calling `toJointsView()`, always solve at the rest pose (all joint values = 0 or default). Solving at a non-zero angle and then animating will double-rotate parts. Use the `defaults` option on `toJointsView()` to set the initial display angle instead.
+
+```ts
+const solved = mech.solve({ shoulder: 45, elbow: -20 });
+return solved.toGroup();
+```
+
+```ts
+solve(state?: JointState): SolvedAssembly
+```
+
+**Other**
 
-- `get usedPortRefs()` — Port refs (e.g. "PartName.portName") consumed by connect/match calls.
-- `mate()` — Register mate constraints between parts. Constraints are solved during `solve()` to derive part positions and explode hints. Part references use "partName:featureName" format.
-- `withReferences()` — Attach named placement reference points to this assembly. These are surfaced automatically on the ImportedAssembly when this file is imported via require(), so consumers can use placeReference() without re-declaring them. Returns `this` for chaining.
-- `getReferences()` — getReferences(): PlacementReferences
-- `withPorts()` — Attach named ports to a specific part or the assembly root. Ports declared this way are in the part's local coordinate system.
-- `getPorts()` — Get ports declared on a part (in part-local space).
-- `getAllPorts()` — getAllPorts(): Map<string, PortMap>
-- `getPort()` — Parse a "PartName.portName" reference and return the resolved port. Throws descriptive errors if the part or port doesn't exist.
-- `addFrame()` — Add a virtual reference frame (no geometry) to the assembly graph.
-- `addPart()` — addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
-- `addJoint()` — addJoint(name: string, type: JointType, parent: string, child: string, options?:
-- `addRevolute()` — addRevolute(name: string, parent: string, child: string, options?: JointOptions)
-- `addPrismatic()` — addPrismatic(name: string, parent: string, child: string, options?: JointOptions
-- `addFixed()` — addFixed(name: string, parent: string, child: string, options?: JointOptions): A
-- `connect()` — Connect two parts by aligning their declared ports. `parentPortRef` and `childPortRef` use "PartName.portName" format. The system computes the joint frame and axis automatically from port alignment. ```javascript const mech = assembly("Arm") .addPart("Base", base) .addPart("Link", link) .connect("Base.top", "Link.bottom", { as: "J1", type: "revolute" }); ```
-- `match()` — Match connectors between two parts, auto-positioning and auto-creating joints. The connector metadata (type, gender, kind) determines the joint type automatically. If a connector is revolute, a revolute joint is created. If fixed or unspecified, fixed. ```javascript const mech = assembly("Door") .addPart("Frame", frame) .addPart("Door", door) .match("Door", "Frame", { hinge_top: "hinge_top", hinge_bottom: "hinge_bottom" }); ```
-- `addJointCoupling()` — addJointCoupling(jointName: string, options: JointCouplingOptions): Assembly
-- `addGearCoupling()` — addGearCoupling(drivenJointName: string, driverJointName: string, options?: Gear
-- `solve()` — solve(state?: JointState): SolvedAssembly
-- `sweepJoint()` — sweepJoint(jointName: string, from: number, to: number, steps: number, baseState
-- `toJointsView()` — Derive `jointsView()` configuration from this assembly's joint graph and call it. Computes world-space pivots and axes from the solved rest pose, so you don't have to manually restate joint kinematics for the viewport runtime.
-- `toDisassemblyView()` — Generate a cinematic disassembly animation from the assembly's joint graph. Creates a `jointsView()` configuration with a "Disassemble" animation that sequences joint motions in reverse topological order (leaves first): - Revolute joints swing open to their max angle - Prismatic joints extend to their max distance - Fastener-named parts get extra rotation (unscrewing effect) Translation/separation is handled by the explode system (auto-configured by `solve()` with joint-derived directions). Use the explode slider in combination with this animation for the full disassembly effect.
-- `describe()` — describe(): AssemblyDefinition
+#### `usedPortRefs()` — Connector refs (e.g. "PartName.connectorName") consumed by connect/match calls.
+
+```ts
+get usedPortRefs(): ReadonlySet<string>
+```
+
+#### `mate()` — Register mate constraints between parts. Constraints are solved during `solve()` to derive part positions and explode hints. Part references use "partName:featureName" format.
+
+```ts
+mate(fn: (m: MateBuilder) => void): Assembly
+```
+
+#### `withReferences()` — Attach named placement reference points to this assembly. These are surfaced automatically on the ImportedAssembly when this file is imported via require(), so consumers can use placeReference() without re-declaring them. Returns `this` for chaining.
+
+```ts
+withReferences(refs: Pick<PlacementReferenceInput, "points">): Assembly
+```
+
+#### `withConnectors()` — Attach named connectors to a specific part or the assembly as a whole.
+
+Connectors declared this way are in the part's local coordinate system. They are captured automatically if the incoming [`Shape`](/docs/core#shape) already has connectors via `shape.withConnectors(...)`, but you can also add or override connectors after the fact with this method.
+
+Use the single-argument overload to attach assembly-level connectors — these are exposed when this assembly is imported as a sub-assembly.
+
+```ts
+withConnectors(partName: string, connectors: Record<string, ConnectorInput>): Assembly
+```
+
+#### `withPorts()` — Backward-compatible alias for `withConnectors()`.
+
+```ts
+withPorts(partNameOrPorts: string | Record<string, PortInput>, maybePorts?: Record<string, PortInput>): Assembly
+```
+
+#### `getConnectors()` — Get connectors declared on a part in part-local space.
+
+```ts
+getConnectors(partName: string): PortMap
+```
+
+#### `getPorts()` — Backward-compatible alias for `getConnectors()`.
+
+```ts
+getPorts(partName: string): PortMap
+```
+
+#### `getPort()` — Parse a "PartName.connectorName" reference and return the resolved connector. Throws descriptive errors if the part or connector doesn't exist.
+
+```ts
+getPort(ref: string): { partName: string; portName: string; port: PortDef; }
+```
+
+#### `addFrame()` — Add a virtual reference frame (no geometry) to the assembly graph.
+
+Useful when you need a named pivot point or coordinate frame that has no visual geometry. Acts like a zero-volume part and can be connected to other parts via joints.
+
+```ts
+addFrame(name: string, options?: PartOptions): Assembly
+```
+
+#### `addPart()` — Add a named part to the assembly.
+
+Connectors declared on the part (via `withConnectors()`) are captured automatically. Parts are positioned at world origin by default unless a `transform` is provided in `options`. For root parts (no incoming joint), `transform` is their final world position.
+
+When a part is a [`ShapeGroup`](/docs/core#shapegroup), name the group children explicitly to get readable viewport labels (e.g. `"Base Assembly.Body"` instead of `"Base Assembly.1"`):
+
+```ts
+const housing = group(
+  { name: "Body", shape: body },
+  { name: "Lid", shape: lid },
+);
+assembly.addPart("Base Assembly", housing);
+```
+
+```ts
+addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
+```
+
+#### `addJoint()` — Add a kinematic joint between a parent and child part.
+
+`frame` is a transform from the **parent part frame** to the **joint frame at zero state**. The child's world position is computed as:
+
+```
+childWorld = parentWorld × frame × motion(value) × childBase
+```
+
+For revolute joints `value` is in degrees; for prismatic joints `value` is in mm. Coupled joints (see `addJointCoupling`) ignore the `state` value passed to `solve()` and compute their value from source joints.
+
+```ts
+addJoint(name: string, type: JointType, parent: string, child: string, options?: JointOptions): Assembly
+```
+
+#### `addRevolute()` — Shorthand for `addJoint(name, 'revolute', parent, child, options)`.
+
+```ts
+addRevolute(name: string, parent: string, child: string, options?: JointOptions): Assembly
+```
+
+#### `addPrismatic()` — Shorthand for `addJoint(name, 'prismatic', parent, child, options)`.
+
+```ts
+addPrismatic(name: string, parent: string, child: string, options?: JointOptions): Assembly
+```
+
+#### `addFixed()` — Shorthand for `addJoint(name, 'fixed', parent, child, options)`.
+
+Fixed joints rigidly attach a child part to its parent at `frame` with no motion. Before calling `mergeInto()`, use `addFixed()` to collapse multiple root parts into a single root.
+
+```ts
+addFixed(name: string, parent: string, child: string, options?: JointOptions): Assembly
+```
+
+#### `connect()` — Connect two parts by aligning their declared connectors, automatically computing frame and axis.
+
+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.
+
+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();
+```
+
+```ts
+connect(parentPortRef: string, childPortRef: string, options?: ConnectOptions): Assembly
+```
+
+#### `match()` — Auto-create a joint by matching typed connectors between two parts.
+
+Connectors are ports with a `connectorType` string and a `gender` (`'male'`, `'female'`, or `'neutral'`). `match()` validates type and gender compatibility (use `{ force: true }` to skip validation) and creates the joint automatically from the connector's `kind` metadata.
+
+The `pairs` map is `{ childConnector: parentConnector }`. The first pair drives joint creation; additional pairs are validated but do not create additional joints (they constrain the same rigid connection).
+
+Define connectors on shapes with `shape.withConnectors(...)`:
+
+```ts
+const door = doorShape.withConnectors({
+  hinge_top: connector.male("hinge", { origin: [0, 0, 90], axis: [0, 0, 1] }),
+  hinge_bottom: connector.male("hinge", { origin: [0, 0, 10], axis: [0, 0, 1] }),
+});
+```
+
+Then match in the assembly:
+
+```ts
+const mech = assembly("Door")
+  .addPart("Frame", frame)
+  .addPart("Door", door)
+  .match("Door", "Frame", { hinge_top: "hinge_top", hinge_bottom: "hinge_bottom" });
+// Revolute connectors → auto-creates revolute joint. No manual addRevolute needed.
+```
+
+```ts
+match(childPartName: string, parentPartName: string, pairs: Record<string, string>, options?: MatchToOptions & { as?: string; }): Assembly
+```
+
+#### `addJointCoupling()` — Link a joint's value to a linear combination of other joint values.
+
+The driven joint's value is computed as:
+
+```
+driven = offset + Σ(ratio_i × source_i)
+```
+
+Coupled joints ignore any value passed in `solve(state)` — a warning is emitted if you try to override one. Coupling cycles are rejected. You cannot sweep a coupled joint directly; sweep one of its source joints instead.
+
+```ts
+assembly
+  .addRevolute("Steering", "Base", "Turret", { axis: [0, 0, 1] })
+  .addRevolute("WheelDrive", "Turret", "Wheel", { axis: [1, 0, 0] })
+  .addRevolute("TopGear", "Base", "TopInput", { axis: [0, 0, 1] })
+  .addJointCoupling("TopGear", {
+    terms: [
+      { joint: "Steering", ratio: 1 },
+      { joint: "WheelDrive", ratio: 20 / 14 },
+    ],
+  });
+```
+
+```ts
+addJointCoupling(jointName: string, options: JointCouplingOptions): Assembly
+```
+
+#### `addGearCoupling()` — Link two revolute joints via a gear ratio.
+
+Choose exactly one ratio source:
+
+- `ratio` — explicit numeric ratio (driven/driver, negative for external mesh)
+- `pair` — a `GearRatioLike` from `lib.gearPair`, `lib.bevelGearPair`, etc. (uses `pair.jointRatio`)
+- `driverTeeth` + `drivenTeeth` — auto-computes ratio; use `mesh` to control sign (`'external'` = negative/opposite rotation, `'internal'` = positive, `'bevel'`/`'face'` = negative)
+
+When `pair` carries a `phaseDeg`, it is auto-applied as the coupling `offset` to align teeth correctly. Override with `offset: 0` if gear shapes already have the phase baked in.
+
+```ts
+const pair = lib.gearPair({ pinion: { module: 1.25, teeth: 14 }, gear: { module: 1.25, teeth: 42 } });
+assembly
+  .addRevolute("Pinion", "Base", "PinionPart", { axis: [0, 0, 1] })
+  .addRevolute("Driven", "Base", "GearPart", { axis: [0, 0, 1] })
+  .addGearCoupling("Driven", "Pinion", { pair });
+```
+
+```ts
+addGearCoupling(drivenJointName: string, driverJointName: string, options?: GearCouplingOptions): Assembly
+```
+
+#### `sweepJoint()` — Sample a joint through its motion range, collecting collision data at each step.
+
+Divides `[from, to]` into `steps` intervals (producing `steps + 1` frames). At each sample, the assembly is solved with the sweeping joint at that value and `baseState` for all others. Returns one `JointSweepFrame` per sample with the joint value, collision findings, and any solve warnings.
+
+You cannot sweep a coupled joint — sweep one of its source joints instead.
+
+```ts
+const sweep = mech.sweepJoint("elbow", -10, 135, 12, { shoulder: 35 });
+const hits = sweep.filter(frame => frame.collisions.length > 0);
+console.log(`Collisions at ${hits.length} of ${sweep.length} poses`);
+```
+
+```ts
+sweepJoint(jointName: string, from: number, to: number, steps: number, baseState?: JointState, collisionOptions?: CollisionOptions): JointSweepFrame[]
+```
+
+#### `toJointsView()` — Derive viewport joint controls from the assembly graph and register them.
+
+Solves the assembly at rest (all joints = default), then converts each joint into a `JointViewInput` with world-space pivot and axis. Fixed joints become hidden zero-range revolute entries so attached parts follow their parent during animation. Joint couplings are forwarded to the viewport automatically.
+
+**Critical pitfall:** Always call `toJointsView()` before solving for display. Then solve at the **rest pose** (no state overrides) and return that result. Do not solve at a non-zero angle when using `toJointsView()` — the viewport will apply the same rotation again, double-rotating the part.
+
+```ts
+mech.toJointsView({
+  defaults: { J1: 30 },
+  animations: [{
+    name: "Swing", duration: 2, loop: true,
+    keyframes: [{ values: { J1: -45 } }, { values: { J1: 45 } }, { values: { J1: -45 } }],
+  }],
+});
+
+// Solve at REST — viewport handles posing
+return mech.solve().toGroup();
+```
+
+```ts
+toJointsView(options?: ToJointsViewOptions): void
+```
+
+#### `describe()` — Return the serializable assembly definition used by solve/inspect pipelines.
+
+```ts
+describe(): AssemblyDefinition
+```
 
 ### `ImportedAssembly`
 
-Wraps an imported Assembly, giving access to named parts and group conversion without losing the kinematic structure. Supports placement references (`.withReferences()` / `.placeReference()`) so sub-assemblies can be positioned the same way as imported parts and groups.
+A wrapper around an imported `Assembly` that provides kinematic access and convenient transform helpers.
 
-**Methods:**
+When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core#require) wraps it in an `ImportedAssembly`. This preserves the kinematic structure — you can call `solve()`, `sweepJoint()`, and `mergeInto()` — while also allowing convenience transforms that auto-solve at default values.
+
+**Kinematic access**
+
+```ts
+const arm = require("./arm.forge.js");
+
+const solved = arm.solve({ shoulder: 45 });   // full kinematic solve
+const link   = arm.part("Link", { shoulder: 60 }); // single part at state
+const group  = arm.toGroup({ shoulder: 45 });  // ShapeGroup with named children
+```
+
+**Convenience transforms** (auto-solve at defaults, return [`ShapeGroup`](/docs/core#shapegroup)):
+
+```ts
+const positioned = arm.rotateZ(-90).translate(0, -20, 50);
+```
+
+**Merging into a parent**
+
+```ts
+require("./arm.forge.js").mergeInto(robot, {
+  prefix: "Left Arm",
+  mountParent: "Chassis",
+  mountJoint: "leftMount",
+  mountOptions: { frame: Transform.identity().translate(-70, 0, 10) },
+});
+```
+
+#### `assembly()` — The underlying Assembly — use for sweepJoint, addPart into parent, etc.
+
+```ts
+get assembly(): Assembly
+```
+
+#### `solve()` — Solve the assembly at the given joint state (defaults to each joint's default value).
 
-- `get assembly()` — The underlying Assembly — use for sweepJoint, addPart into parent, etc.
-- `solve()` — Solve the assembly at the given joint state (defaults to each joint's default value).
-- `part()` — Return a specific named part positioned at the given joint state, with any stored placement offset applied.
-- `toGroup()` — Convert all assembly parts to a ShapeGroup with named children. Child names match the part names used in the assembly. Any stored placement offset and placement references are forwarded to the group.
-- `withReferences()` — Attach named placement reference points to this assembly. Points are simple 3D coordinates (relative to the assembly's own origin). Returns a new ImportedAssembly — does not mutate.
-- `referenceNames()` — List all attached placement reference names.
-- `placeReference()` — Translate the assembly so the named reference point lands on `target`. Returns a new ImportedAssembly — does not mutate. All point refs are translated by the same delta.
-- `translate()` — Solve at defaults and return a translated ShapeGroup.
-- `rotate()` — Solve at defaults and return a rotated ShapeGroup (Euler XYZ degrees).
-- `scale()` — Solve at defaults and return a scaled ShapeGroup.
-- `mirror()` — Solve at defaults and return a mirrored ShapeGroup.
-- `color()` — Solve at defaults and return a colored ShapeGroup.
-- `child()` — Solve at defaults, get a named child part from the resulting group.
-- `mergeInto()` — Flatten this sub-assembly's parts and joints into `parent`, then wire a mount joint connecting `mountParent` (a part already in `parent`) to the sub-assembly root. All part names and joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions. After the merge you can drive sub-assembly joints from the parent: `parent.solve({ "Left Arm.shoulder": 45 })`. Throws if the sub-assembly has multiple root parts (connect them with addFixed first). Returns `parent` for chaining.
+```ts
+solve(state?: JointState): SolvedAssembly
+```
+
+#### `part()` — Return a specific named part positioned at the given joint state, with any stored placement offset applied.
+
+```ts
+part(name: string, state?: JointState): AssemblyPart
+```
+
+#### `toGroup()` — Convert all assembly parts to a ShapeGroup with named children. Child names match the part names used in the assembly. Any stored placement offset and placement references are forwarded to the group.
+
+```ts
+toGroup(state?: JointState): ShapeGroup
+```
+
+#### `withReferences()` — Attach named placement reference points to this assembly. Points are simple 3D coordinates (relative to the assembly's own origin). Returns a new ImportedAssembly — does not mutate.
+
+```ts
+withReferences(refs: Pick<PlacementReferenceInput, "points">): ImportedAssembly
+```
+
+#### `referenceNames()` — List all attached placement reference names.
+
+```ts
+referenceNames(kind?: PlacementReferenceKind): string[]
+```
+
+#### `placeReference()` — Translate the assembly so the named reference point lands on `target`. Returns a new ImportedAssembly — does not mutate. All point refs are translated by the same delta.
+
+```ts
+placeReference(ref: string, target: [ number, number, number ], offset?: [ number, number, number ]): ImportedAssembly
+```
+
+#### `translate()` — Solve at defaults and return a translated ShapeGroup.
+
+```ts
+translate(x: number, y: number, z: number): ShapeGroup
+```
+
+#### `rotate()` — Solve at defaults and return a rotated ShapeGroup.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
+
+#### `rotateX()` — Solve at defaults and return a ShapeGroup rotated around X.
+
+```ts
+rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
+
+#### `rotateY()` — Solve at defaults and return a ShapeGroup rotated around Y.
+
+```ts
+rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
+
+#### `rotateZ()` — Solve at defaults and return a ShapeGroup rotated around Z.
+
+```ts
+rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
+```
+
+#### `scale()` — Solve at defaults and return a scaled ShapeGroup.
+
+```ts
+scale(v: number | [ number, number, number ]): ShapeGroup
+```
+
+#### `mirror()` — Solve at defaults and return a mirrored ShapeGroup.
+
+```ts
+mirror(normal: [ number, number, number ]): ShapeGroup
+```
+
+#### `color()` — Solve at defaults and return a colored ShapeGroup.
+
+```ts
+color(hex: string): ShapeGroup
+```
+
+#### `child()` — Solve at defaults, get a named child part from the resulting group.
+
+```ts
+child(name: string): Shape | Sketch | ShapeGroup
+```
+
+#### `mergeInto()` — Flatten this sub-assembly's parts and joints into `parent` and wire a mount joint.
+
+All part and joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions. After the merge, sub-assembly joints are driven from the parent using the prefixed names:
+
+```ts
+parent.solve({ "Left Arm.shoulder": 45, "Right Arm.shoulder": -20 })
+```
+
+Joint couplings inside the sub-assembly are preserved and rewritten with the prefix. Ports from sub-assembly parts are forwarded with the prefix.
+
+The sub-assembly must have exactly one root part. If it has multiple roots, use `addFixed()` first to consolidate them before merging.
+
+```ts
+const robot = assembly("Robot").addPart("Chassis", chassis);
+
+require("./arm.forge.js").mergeInto(robot, {
+  prefix: "Left Arm",
+  mountParent: "Chassis",
+  mountJoint: "leftMount",
+  mountOptions: { frame: Transform.identity().translate(-70, 0, 10) },
+});
+```
+
+```ts
+mergeInto(parent: Assembly, options: MergeIntoOptions): Assembly
+```
 
 ### `SolvedAssembly`
 
+The result of solving an assembly at a specific joint state.
+
+`SolvedAssembly` holds world-space transforms for every part at a given pose. Use `toGroup()` to convert all parts into a renderable [`ShapeGroup`](/docs/core#shapegroup), or use `getPart()` / `getTransform()` to inspect individual parts programmatically.
+
+**Validation**
+
+Call `collisionReport()` to detect overlapping parts, or `sweepJoint()` on the parent `Assembly` to check for interference across the joint's motion range.
+
+```ts
+const solved = mech.solve({ shoulder: 45, elbow: -20 });
+console.log("Collisions", solved.collisionReport());
+return solved.toGroup();
+```
+
 **Properties:**
 
 | Property | Type | Description |
@@ -154,20 +593,106 @@ Wraps an imported Assembly, giving access to named parts and group conversion wi
 
 **Methods:**
 
-- `warnings()` — warnings(): string[]
-- `getJointState()` — getJointState(): JointState
-- `get mateExplodeHints()` — Explode direction hints derived from mate constraints, or null if no mates.
-- `get mateDof()` — Remaining degrees of freedom after mate constraints, or null if no mates.
-- `get mateConverged()` — Whether the mate constraint solver converged, or null if no mates.
-- `getTransform()` — getTransform(partName: string): Transform
-- `getPart()` — getPart(partName: string): AssemblyPart
-- `toGroup()` — Convert all solved parts to a ShapeGroup with named children. Each part becomes a child, positioned at its solved transform. This is the primary way to get a group for rendering, `show()`, or embedding.
-- `toSceneObjects()` — Return an array of named scene objects for the viewport renderer. Each part becomes `{ name, shape }` or `{ name, group: [...] }` if the part is a ShapeGroup.  Prefer `toGroup()` for most uses; this method exists for advanced scene-graph control.
-- `toScene()` — toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; sh
-- `bom()` — bom(): BomRow[]
-- `bomCsv()` — bomCsv(): string
-- `collisionReport()` — collisionReport(options?: CollisionOptions): CollisionFinding[]
-- `minClearance()` — minClearance(partA: string, partB: string, searchLength?: number): number
+#### `warnings()` — Return any warnings generated during solve (clamped joints, unconverged mates, etc.).
+
+```ts
+warnings(): string[]
+```
+
+#### `getJointState()` — Return a snapshot of resolved joint values (after clamping and coupling).
+
+```ts
+getJointState(): JointState
+```
+
+#### `mateExplodeHints()` — Explode direction hints derived from mate constraints, or null if no mates.
+
+```ts
+get mateExplodeHints(): Record<string, { direction: Vec3; }> | null
+```
+
+#### `mateDof()` — Remaining degrees of freedom after mate constraints, or null if no mates.
+
+```ts
+get mateDof(): number | null
+```
+
+#### `mateConverged()` — Whether the mate constraint solver converged, or null if no mates.
+
+```ts
+get mateConverged(): boolean | null
+```
+
+#### `getTransform()` — Return the world-space [`Transform`](/docs/core#transform) for the named part at the solved pose.
+
+```ts
+getTransform(partName: string): Transform
+```
+
+#### `getPart()` — Return the named part already positioned at its solved world transform.
+
+```ts
+getPart(partName: string): AssemblyPart
+```
+
+#### `toGroup()` — Convert all solved parts into a [`ShapeGroup`](/docs/core#shapegroup) with named children.
+
+Each part becomes a named child in the group, already positioned at its solved world transform. This is the primary method for rendering, passing to `show()`, or embedding the assembly into a parent model.
+
+```ts
+return mech.solve({ shoulder: 60 }).toGroup();
+```
+
+```ts
+toGroup(): ShapeGroup
+```
+
+#### `toSceneObjects()` — Return an array of named scene objects for the viewport renderer.
+
+Each part becomes `{ name, shape }` or `{ name, group: [...] }` if the part is a [`ShapeGroup`](/docs/core#shapegroup). Prefer `toGroup()` for most use cases. This method exists for advanced scene-graph control where you need access to the flat per-part array with metadata.
+
+```ts
+toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+```
+
+#### `toScene()` — Backward-compatible alias for `toSceneObjects()`.
+
+```ts
+toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+```
+
+#### [`bom()`](/docs/output#bom) — Generate a bill of materials for all parts in the solved assembly.
+
+```ts
+bom(): BomRow[]
+```
+
+#### `bomCsv()` — Generate a bill of materials as a CSV string.
+
+```ts
+bomCsv(): string
+```
+
+#### `collisionReport()` — Detect overlapping (colliding) part pairs in this solved pose.
+
+Computes boolean intersections between all part pairs and returns findings where the overlap volume exceeds `minOverlapVolume` (default 0.1 mm³).
+
+```ts
+const solved = mech.solve({ shoulder: 35, elbow: 60 });
+console.log("Collisions", solved.collisionReport());
+```
+
+```ts
+collisionReport(options?: CollisionOptions): CollisionFinding[]
+```
+
+#### `minClearance()` — Compute the minimum gap (clearance) between two parts in this solved pose.
+
+Returns `0` if the parts are touching or overlapping. Requires the Manifold backend. `searchLength` bounds the search radius in mm — increase it for widely separated parts.
+
+```ts
+minClearance(partA: string, partB: string, searchLength?: number): number
+```
 
 ### `MateBuilder`
 
@@ -179,14 +704,68 @@ Wraps an imported Assembly, giving access to named parts and group conversion wi
 
 **Methods:**
 
-- `flush()` — flush(faceA: string, faceB: string): string
-- `align()` — align(faceA: string, faceB: string): string
-- `parallel()` — parallel(faceA: string, faceB: string): string
-- `faceDistance()` — faceDistance(faceA: string, faceB: string, distance: number): string
-- `concentric()` — concentric(axisA: string, axisB: string): string
-- `axisParallel()` — axisParallel(axisA: string, axisB: string): string
-- `pointCoincident()` — pointCoincident(pointA: string, pointB: string): string
-- `pointOnFace()` — pointOnFace(point: string, face: string): string
-- `pointOnAxis()` — pointOnAxis(point: string, axis: string): string
-- `angle()` — angle(faceA: string, faceB: string, degrees: number): string
-- `get totalEquations()` — Total constraint equations.
+#### `flush()` — Constrain two faces so they stay flush.
+
+```ts
+flush(faceA: string, faceB: string): string
+```
+
+#### `align()` — Constrain two faces so their normals align.
+
+```ts
+align(faceA: string, faceB: string): string
+```
+
+#### `parallel()` — Constrain two faces so they remain parallel.
+
+```ts
+parallel(faceA: string, faceB: string): string
+```
+
+#### `faceDistance()` — Constrain the distance between two faces.
+
+```ts
+faceDistance(faceA: string, faceB: string, distance: number): string
+```
+
+#### `concentric()` — Constrain two axes to share the same center line.
+
+```ts
+concentric(axisA: string, axisB: string): string
+```
+
+#### `axisParallel()` — Constrain two axes to remain parallel.
+
+```ts
+axisParallel(axisA: string, axisB: string): string
+```
+
+#### `pointCoincident()` — Constrain two points to coincide.
+
+```ts
+pointCoincident(pointA: string, pointB: string): string
+```
+
+#### `pointOnFace()` — Constrain a point to lie on a face.
+
+```ts
+pointOnFace(point: string, face: string): string
+```
+
+#### `pointOnAxis()` — Constrain a point to lie on an axis.
+
+```ts
+pointOnAxis(point: string, axis: string): string
+```
+
+#### `angle()` — Constrain the angle between two faces.
+
+```ts
+angle(faceA: string, faceB: string, degrees: number): string
+```
+
+#### `totalEquations()` — Total constraint equations.
+
+```ts
+get totalEquations(): number
+```