forgecad 0.6.3 → 0.7.0

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

@@ -5,336 +5,230 @@ skill-order: 100
 
 # Output & Annotations
 
-> **Auto-generated** from `src/forge/forge-public-api.ts`. Do not edit by hand — run `npm run gen:docs` to regenerate.
-
 Dimensions, BOM entries, verification checks, and sketch export.
 
-## Functions
+## Contents
 
-### Annotations & Output
+- [Annotations & Output](#annotations-output) — `bom`, `robotExport`, `dim`, `dimLine`
+- [Sketch Export](#sketch-export) — `sketchToDxf`, `sketchToSvg`
 
-Add dimensions, BOM entries, verification checks, and robot export.
+## Functions
 
-#### `bom()`
+### Annotations & Output
 
-```ts
-bom(quantity: number, description: string, opts?: BomOpts): void
-```
+#### `bom()` — Register a Bill of Materials entry for report export.
 
-Add a bill-of-materials entry.
+BOM entries are accumulated during script execution and exported alongside the model in report views. Rows are grouped by normalized `description + unit`. Pass an explicit `key` to force multiple descriptions to collapse into a single line item.
 
-<details><summary><code>BomOpts</code></summary>
+- `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with [`param()`](/docs/core#param)-driven counts).
+- `unit` defaults to `"pieces"` when omitted or empty.
+- The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
 
 ```ts
-interface BomOpts {
-  /** Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" */
-  unit?: string;
-  /** Optional explicit grouping key used during report aggregation. */
-  key?: string;
-}
-```
-
-</details>
+const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
+const boltCount = param("Bolt Count", 16, { min: 0, max: 200, integer: true });
 
-#### `robotExport()`
+bom(tubeLen, "iron tube 30 x 20", { unit: "mm" });
+bom(boltCount, "M4 bolt, 16 mm length");
+bom(4, "rubber foot", { key: "foot-rubber" }); // explicit aggregation key
 
-```ts
-robotExport(options: RobotExportOptions): CollectedRobotExport
+// Structured metadata for richer reports:
+bom(tubeLen, "rectangular steel tube", {
+  unit: "mm",
+  material: "steel",
+  section: [30, 20],
+  wall: 3,
+});
 ```
 
-Declare that the current script should export an assembly as a robot package for the SDF CLI. Configures inertial properties, joint limits, and optional plugins (e.g. diff-drive for Gazebo).
-
-<details><summary><code>RobotExportOptions</code></summary>
-
 ```ts
-interface RobotExportOptions {
-  assembly: Assembly;
-  modelName?: string;
-  state?: JointState;
-  static?: boolean;
-  selfCollide?: boolean;
-  allowAutoDisable?: boolean;
-  links?: Record<string, RobotLinkExportOptions>;
-  joints?: Record<string, RobotJointExportOptions>;
-  diffDrive?: RobotDiffDrivePluginOptions;
-  jointStatePublisher?: RobotJointStatePublisherOptions;
-  world?: RobotWorldOptions;
-}
+bom(quantity: number, description: string, opts?: BomOpts): void
 ```
 
-</details>
+**`BomOpts`**
 
-<details><summary><code>RobotLinkExportOptions</code></summary>
+| Option | Type | Description |
+|--------|------|-------------|
+| `unit?` | `string` | Quantity unit label, e.g. "mm", "pieces", "kg". Default: "pieces" |
+| `key?` | `string` | Optional explicit grouping key used during report aggregation. |
+| `material?` | `string` | Material name, e.g. "steel", "birch plywood", "nylon" |
+| `dimensions?` | `number[]` | Overall dimensions `[width, height]` or `[width, height, thickness]` in the entry's unit |
+| `section?` | `number[]` | Cross-section dimensions `[w, h]` for tubes and profiles |
+| `wall?` | `number` | Wall thickness for hollow sections (mm) |
+| `diameter?` | `number` | Diameter for round stock, bolts, dowels (mm) |
+| `length?` | `number` | Length for fasteners (mm) |
+| `process?` | `string` | Manufacturing process, e.g. "laser cut", "CNC", "welded" |
+| `notes?` | `string` | Free-form notes |
+| `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
-```ts
-interface RobotLinkExportOptions {
-  massKg?: number;
-  densityKgM3?: number;
-  collision?: "visual" | "convex" | "box" | "none";
-}
-```
-
-</details>
-
-<details><summary><code>RobotJointExportOptions</code></summary>
+#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
 
-```ts
-interface RobotJointExportOptions {
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
+Call `robotExport()` alongside your assembly definition. The CLI commands `forgecad export sdf` and `forgecad export urdf` pick up the declaration and produce a robot package with:
 
-</details>
+- Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
+- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
 
-<details><summary><code>RobotDiffDrivePluginOptions</code></summary>
+**Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
-```ts
-interface RobotDiffDrivePluginOptions {
-  leftJoints: string[];
-  rightJoints: string[];
-  wheelSeparationMm: number;
-  wheelRadiusMm: number;
-  topic?: string;
-  odomTopic?: string;
-  tfTopic?: string;
-  frameId?: string;
-  odomFrameId?: string;
-  maxLinearVelocity?: number;
-  maxAngularVelocity?: number;
-  linearAcceleration?: number;
-  angularAcceleration?: number;
-}
-```
+| Mode | Description | Default | |------|-------------|---------| | `'convex'` | Convex hull (separate `_collision.stl`) | Yes | | `'box'` | AABB primitive — fastest physics | | | `'visual'` | Same mesh as visual — exact but slow | | | `'none'` | No collision geometry | |
 
-</details>
+**Unit conventions:**
 
-<details><summary><code>RobotJointStatePublisherOptions</code></summary>
+- Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
+- Prismatic distances are in mm in Forge; exported in meters.
+- `massKg` is preferred; `densityKgM3` is used when mass is unknown.
+- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```ts
-interface RobotJointStatePublisherOptions {
-  enabled?: boolean;
-  joints?: string[];
-  topic?: string;
-  updateRate?: number;
-}
-```
-
-</details>
+const rover = assembly("Scout")
+  .addPart("Chassis", box(300, 220, 50, true))
+  .addPart("Left Wheel", cylinder(30, 60, undefined, 48, true))
+  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, 140, 60),
+    effort: 20, velocity: 1080,
+  });
 
-<details><summary><code>RobotWorldOptions</code></summary>
-
-```ts
-interface RobotWorldOptions {
-  name?: string;
-  generateDemoWorld?: boolean;
-  spawnPose?: RobotPose6;
-  keyboardTeleop?: RobotWorldKeyboardTeleopOptions;
-}
+robotExport({
+  assembly: rover,
+  modelName: "Scout",
+  links: {
+    Chassis: { massKg: 10 },
+    "Left Wheel": { massKg: 0.8 },
+  },
+  plugins: {
+    diffDrive: {
+      leftJoints: ["leftWheel"], rightJoints: ["rightWheel"],
+      wheelSeparationMm: 280, wheelRadiusMm: 60,
+    },
+  },
+  world: { generateDemoWorld: true },
+});
 ```
 
-</details>
+**CLI usage**
 
-<details><summary><code>RobotWorldKeyboardTeleopOptions</code></summary>
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
+```
 
 ```ts
-interface RobotWorldKeyboardTeleopOptions {
-  enabled?: boolean;
-  linearStep?: number;
-  angularStep?: number;
-}
+robotExport(options: RobotExportOptions): CollectedRobotExport
 ```
 
-</details>
+**`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world?: RobotWorldOptions`
 
-<details><summary><code>CollectedRobotExport</code></summary>
+`RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
 
-```ts
-interface CollectedRobotExport {
-  modelName: string;
-  assembly: AssemblyDefinition;
-  state: JointState;
-  static: boolean;
-  selfCollide: boolean;
-  allowAutoDisable: boolean;
-  links: Record<string, RobotLinkExportOptions>;
-  joints: Record<string, RobotJointExportOptions>;
-  diffDrive?: RobotDiffDrivePluginOptions;
-  jointStatePublisher?: RobotJointStatePublisherOptions;
-  world: RobotWorldOptions | null;
-}
-```
+`RobotJointExportOptions`: `{ effort?: number, velocity?: number, damping?: number, friction?: number }`
 
-</details>
+**`RobotDiffDrivePluginOptions`**: `leftJoints: string[]`, `rightJoints: string[]`, `wheelSeparationMm: number`, `wheelRadiusMm: number`, `topic?: string`, `odomTopic?: string`, `tfTopic?: string`, `frameId?: string`, `odomFrameId?: string`, `maxLinearVelocity?: number`, `maxAngularVelocity?: number`, `linearAcceleration?: number`, `angularAcceleration?: number`
 
-<details><summary><code>AssemblyDefinition</code></summary>
+`RobotJointStatePublisherOptions`: `{ enabled?: boolean, joints?: string[], topic?: string, updateRate?: number }`
 
-```ts
-interface AssemblyDefinition {
-  name: string;
-  parts: AssemblyPartDef[];
-  joints: AssemblyJointDef[];
-  jointCouplings: AssemblyJointCouplingDef[];
-}
-```
+`RobotWorldOptions`: `{ name?: string, generateDemoWorld?: boolean, spawnPose?: RobotPose6, keyboardTeleop?: RobotWorldKeyboardTeleopOptions }`
 
-</details>
+`RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-<details><summary><code>AssemblyPartDef</code></summary>
+**`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `diffDrive?: RobotDiffDrivePluginOptions`, `jointStatePublisher?: RobotJointStatePublisherOptions`, `world: RobotWorldOptions | null`
 
-```ts
-interface AssemblyPartDef {
-  name: string;
-  part: AssemblyPart;
-  base: Transform;
-  metadata?: PartMetadata;
-}
-```
+`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
 
-</details>
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-<details><summary><code>PartMetadata</code></summary>
+**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
 
-```ts
-interface PartMetadata {
-  material?: string;
-  process?: string;
-  tolerance?: string;
-  qty?: number;
-  notes?: string;
-  densityKgM3?: number;
-  massKg?: number;
-}
-```
+**`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`
 
-</details>
+`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
 
-<details><summary><code>AssemblyJointDef</code></summary>
+`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
-```ts
-interface AssemblyJointDef {
-  name: string;
-  type: JointType;
-  parent: string;
-  child: string;
-  frame: Transform;
-  axis: Vec3;
-  min?: number;
-  max?: number;
-  defaultValue: number;
-  unit?: string;
-  effort?: number;
-  velocity?: number;
-  damping?: number;
-  friction?: number;
-}
-```
-
-</details>
+#### `dim()` — Add a dimension annotation between two points.
 
-<details><summary><code>AssemblyJointCouplingDef</code></summary>
+Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
 
-```ts
-interface AssemblyJointCouplingDef {
-  joint: string;
-  terms: JointCouplingTermRecord[];
-  offset: number;
-}
-```
+Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or [`Point2D`](/docs/sketch#point2d) objects (Z is treated as 0 for 2D inputs).
 
-</details>
+**Ownership Rules (Report Pages)**
 
-<details><summary><code>JointCouplingTermRecord</code></summary>
+- `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
+- `component: "Part Name"` — route dimension to another named returned object.
+- Multiple owners: dimension is shared and appears on the assembly overview page.
+- No ownership set: report export infers ownership via endpoint-in-bbox.
 
 ```ts
-interface JointCouplingTermRecord {
-  joint: string;
-  ratio: number;
-}
+dim([-w / 2, 0, 0], [w / 2, 0, 0], { label: "Width" });
+dim([0, 0, -h / 2], [0, 0, h / 2], { label: "Height", offset: 14 });
+dim([0, 0, 0], [100, 0, 0], { component: "Base", color: "#00AAFF" });
 ```
 
-</details>
-
-#### `dim()`
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
 
 ```ts
-dim(from: PointArg$1, to: PointArg$1, opts?: DimOpts): void
+dim(from: PointArg, to: PointArg, opts?: DimOpts): void
 ```
 
-Add a dimension annotation between two points.
+`DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
+
+#### `dimLine()` — Add a dimension annotation along a [`Line2D`](/docs/sketch#line2d).
 
-<details><summary><code>DimOpts</code></summary>
+Convenience wrapper around { points from a constrained-sketch [`Line2D`](/docs/sketch#line2d) entity. All `opts` are forwarded unchanged.
 
 ```ts
-interface DimOpts {
-  offset?: number;
-  label?: string;
-  color?: string;
-  component?: string | string[];
-  currentComponent?: boolean;
-}
+const a = point(0, 0);
+const b = point(100, 0);
+dimLine(line(a, b), { label: "Span", offset: -8 });
 ```
 
-</details>
-
-#### `dimLine()`
-
 ```ts
 dimLine(l: Line2D, opts?: DimOpts): void
 ```
 
-Add a dimension annotation along a Line2D.
-
 ### Sketch Export
 
-Export 2D sketches to SVG or DXF format strings.
+#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
-#### `sketchToDxf()`
+For regular sketches, each polygon loop becomes a closed `LWPOLYLINE`. For constrained sketches, exports raw `LINE`, `CIRCLE`, and `ARC` entities from the constraint edge geometry, which preserves internal/shared edges that `toPolygons()` would merge away.
+
+The R12 format is chosen for maximum compatibility with CAM tools, laser-cutter software, and older CAD readers.
 
 ```ts
-sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
+const s = rect(100, 60);
+const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible). For regular sketches, each polygon loop becomes a closed LWPOLYLINE. For constraint sketches, exports LINE, CIRCLE, and ARC entities from the constraint edge geometry.
-
-<details><summary><code>SketchDxfOptions</code></summary>
-
 ```ts
-interface SketchDxfOptions {
-  /** DXF layer name. Default: "0" */
-  layer?: string;
-  /** DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black) */
-  colorIndex?: number;
-}
+sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
 ```
 
-</details>
+**`SketchDxfOptions`**
+- `layer?: string` — DXF layer name. Default: "0"
+- `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
 
-#### `sketchToSvg()`
+#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
 
-```ts
-sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
-```
+For regular sketches, exports filled polygon regions. For constrained sketches, exports raw edge geometry (LINE, ARC, CIRCLE) which preserves internal/shared edges that `toPolygons()` would merge away.
 
-Export a 2D sketch as an SVG string. For regular sketches, exports filled polygon regions. For constraint sketches, exports line/arc/circle edge geometry. The SVG uses the sketch's native coordinate system (Y-up) with a transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
+The SVG uses the sketch's native coordinate system (Y-up) with a CSS transform that flips Y so the output renders correctly in SVG's Y-down space. Coordinates are in sketch units (typically mm).
 
-<details><summary><code>SketchSvgOptions</code></summary>
+```ts
+const s = rect(100, 60);
+const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
+```
 
 ```ts
-interface SketchSvgOptions {
-  /** Stroke color. Default: "black" */
-  stroke?: string;
-  /** Stroke width in sketch units. Default: 0.5 */
-  strokeWidth?: number;
-  /** Fill color. Default: "none" */
-  fill?: string;
-  /** Padding around the sketch bounding box in sketch units. Default: 2 */
-  padding?: number;
-  /** If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. */
-  pixelsPerUnit?: number;
-}
+sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
 ```
 
-</details>
+**`SketchSvgOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `stroke?` | `string` | Stroke color. Default: "black" |
+| `strokeWidth?` | `number` | Stroke width in sketch units. Default: 0.5 |
+| `fill?` | `string` | Fill color. Default: "none" |
+| `padding?` | `number` | Padding around the sketch bounding box in sketch units. Default: 2 |
+| `pixelsPerUnit?` | `number` | If set, scale so 1 sketch-unit = this many px. Otherwise auto-fit. |