forgecad 0.9.16 → 0.10.1

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

@@ -9,14 +9,14 @@ Dimensions, BOM entries, verification checks, and sketch export.
 
 ## Contents
 
-- [Annotations & Output](#annotations-output) — `bom`, `robotExport`, `dim`, `dimLine`
-- [Sketch Export](#sketch-export) — `sketchToDxf`, `sketchToSvg`
+- [Annotations & Output](#annotations-output)
+- [Sketch Export](#sketch-export)
 
 ## Functions
 
 ### Annotations & Output
 
-#### `bom()` — Register a Bill of Materials entry for report export.
+#### `bom(quantity: number, description: string, opts?: BomOpts): void` — Register a Bill of Materials entry for report export.
 
 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.
 
@@ -42,10 +42,6 @@ bom(tubeLen, "rectangular steel tube", {
 });
 ```
 
-```ts
-bom(quantity: number, description: string, opts?: BomOpts): void
-```
-
 **`BomOpts`**
 
 | Option | Type | Description |
@@ -62,12 +58,14 @@ bom(quantity: number, description: string, opts?: BomOpts): void
 | `notes?` | `string` | Free-form notes |
 | `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
-#### `robotExport()` — Declare that this script should export the assembly as a SDF/URDF robot package.
+#### `robotExport(options: RobotExportOptions): CollectedRobotExport` — Compatibility shim for SDF/URDF robot package metadata.
 
-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:
+Prefer returning `assembly(...).withSimulation(...)` with `Sim.body(...)`, `Sim.drive.*(...)`, and `Sim.controller.*(...)` metadata. The CLI commands `forgecad export sdf` and `forgecad export urdf` now read that assembly simulation contract directly.
+
+`robotExport()` remains available for one compatibility window. It converts the legacy descriptor into the same internal simulation model used by source-authored `Sim` metadata and produces a robot package with:
 
 - Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
-- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Separate collision meshes
 - Joint limits, effort/velocity/damping/friction metadata from assembly joints
 
 **Collision mesh modes** (set per-link via `links["PartName"].collision`):
@@ -86,23 +84,13 @@ Call `robotExport()` alongside your assembly definition. The CLI commands `forge
 - `massKg` is preferred; `densityKgM3` is used when mass is unknown.
 - Compatibility coupling metadata, when present, maps only the primary term (largest ratio) to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
-```ts
-const rover = assembly("Scout")
-  .addPart("Chassis", box(300, 220, 50).translate(0, 0, -25))
-  .addPart("Left Wheel", cylinder(30, 60, undefined, 48).translate(0, 0, -15))
-  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
-    axis: [0, 1, 0],
-    frame: Transform.identity().translate(90, 140, 60),
-    effort: 20, velocity: 1080,
-  });
+**Legacy example**
 
+```ts
 robotExport({
-  assembly: rover,
+  assembly: rover, // assembly() with parts + revolute wheel joints
   modelName: "Scout",
-  links: {
-    Chassis: { massKg: 10 },
-    "Left Wheel": { massKg: 0.8 },
-  },
+  links: { Chassis: { massKg: 10 }, "Left Wheel": { massKg: 0.8 } },
   plugins: {
     diffDrive: {
       leftJoints: ["leftWheel"], rightJoints: ["rightWheel"],
@@ -113,17 +101,13 @@ robotExport({
 });
 ```
 
-**CLI usage**
+**Preferred CLI usage**
 
 ```bash
 forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
 forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
 ```
 
-```ts
-robotExport(options: RobotExportOptions): CollectedRobotExport
-```
-
 **`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `plugins?: { diffDrive?: RobotDiffDrivePluginOptions; jointStatePublisher?: RobotJointStatePublisherOptions; }`, `world?: RobotWorldOptions`
 
 `RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
@@ -138,58 +122,20 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-**`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `plugins: { diffDrive?: RobotDiffDrivePluginOptions; jointStatePublisher?: RobotJointStatePublisherOptions; }`, `world: RobotWorldOptions | null`
-
-**`AssemblyDefinition`**: `name: string`, `parts: AssemblyPartDef[]`, `joints: AssemblyJointDef[]`, `jointCouplings: AssemblyJointCouplingDef[]`, `kinematics: AssemblyKinematicGraphDef`, `frames: AssemblyFrameDef[]`, `frameJoints: AssemblyFrameJointDef[]`, `frameEdges: AssemblyFrameEdgeDef[]`
-
-**`AssemblyPartDef`**: `name: string`, `part: AssemblyPart`, `base: Transform`, `metadata?: PartMetadata`, `mates: AssemblyPartMateInput[]`, `bindToFrame?: string`
-
-**`PartMetadata`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
-| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
-
-**`AssemblyPartMateInput`**
-- `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
-- `toLink: string` — Name of the link this connector's origin is pinned to.
-- `aimLink?: string` — Optional second link to orient toward. When set, the part is rotated so the connector's **axis** aims from `toLink` toward `aimLink`, posing an oriented bone instead of only translating it. For full pose without relying on a connector axis, declare a second mate (two connectors → two links).
-
-**`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`, `connectorRefs?: JointConnectorRefs`
-
-`JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
-
-`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
-
-`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
-
-**`AssemblyKinematicGraphDef`**: `links: AssemblyLinkDef[]`, `edges: AssemblyEdgeBetweenLinksDef[]`, `angles: AssemblyAngleBetweenLinksDef[]`, `derivedLinks: AssemblyDerivedLinkDef[]`
-
-`AssemblyLinkDef`: `{ name: string, at: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
-
-**`AssemblyEdgeBetweenLinksDef`**: `name: string`, `a: string`, `b: string`, `length: number | null`, `min?: number`, `max?: number`, `visualOnly: boolean`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+#### `dim()` — Add a dimension annotation between two points, or along an entity.
 
-`AssemblyKinematicControlOptions`: `{ min?: number, max?: number, default?: number, unit?: string }`
+Overloads:
 
-**`AssemblyAngleBetweenLinksDef`**: `name: string`, `a?: string`, `b: string`, `c: string`, `reference?: AssemblyAngleReferenceDef`, `target?: number`, `min?: number`, `max?: number`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
-
-`AssemblyAngleReferenceDef`: `{ kind: "worldDirection", direction: Vec3 }`
-
-`AssemblyDerivedLinkDef`: `{ name: string, fromLink: string, referenceLink: string, distance: number, direction: AssemblyDerivedLinkDirection }`
-
-`AssemblyFrameDef`: `{ name: string, origin: Vec3, axis: Vec3, up: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
-
-**`AssemblyFrameJointDef`**: `name: string`, `type: AssemblyFrameJointType`, `parent: string`, `child: string`, `rest: Transform`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `control: boolean`, `metadata?: Record<string, unknown>`
-
-`AssemblyFrameEdgeDef`: `{ name: string, a: string, b: string, metadata?: Record<string, unknown> }`
-
-#### `dim()` — Add a dimension annotation between two points.
+- `dim(line: Line2D, opts?: DimOpts): void`
+- `dim(edge: EdgeRef, opts?: DimOpts): void`
+- `dim(from: PointArg, to: PointArg, opts?: DimOpts): void`
 
 Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.
 
 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).
 
+Entity arguments: pass a single [`Line2D`](/docs/sketch#line2d) (from a constrained sketch) or an `EdgeRef` (from `shape.edge('left')`) as the first argument to dimension along that entity directly — no manual endpoint extraction needed.
+
 **Ownership Rules (Report Pages)**
 
 - `currentComponent: true` — deterministic ownership by the calling import instance. Use when authoring reusable imported parts.
@@ -201,33 +147,31 @@ Point arguments accept 2D tuples `[x, y]`, 3D tuples `[x, y, z]`, or [`Point2D`]
 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" });
+dim(sk.line(a, b), { label: "Span", offset: -8 });   // Line2D entity
+dim(myBox.edge("top-right"), { label: "Depth" });    // EdgeRef entity
 ```
 
-`component` (string or string[] — report ownership), `currentComponent` (boolean)
+[`Line2D`](/docs/sketch#line2d) / `EdgeRef` entity (then pass `opts` as the second argument)
 
-```ts
-dim(from: PointArg, to: PointArg, opts?: DimOpts): void
-```
+`component` (string or string[] — report ownership), `currentComponent` (boolean)
 
 `DimOpts`: `{ offset?: number, label?: string, color?: string, component?: string | string[], currentComponent?: boolean }`
 
-#### `dimLine()` — Add a dimension annotation along a [`Line2D`](/docs/sketch#line2d).
-
-Convenience wrapper around { points from a constrained-sketch [`Line2D`](/docs/sketch#line2d) entity. All `opts` are forwarded unchanged.
+**`EdgeRef`**
 
-```ts
-const a = point(0, 0);
-const b = point(100, 0);
-dimLine(line(a, b), { label: "Span", offset: -8 });
-```
+| Option | Type | Description |
+|--------|------|-------------|
+| `start` | `Vec3` | Start point |
+| `end` | `Vec3` | End point |
+| `query?` | `EdgeQueryRef` | Compiler-owned edge query when available. |
+| `curve?` | `EdgeCurve` | Exact or parametric curve family when the backend/source can identify one. |
+| `faceName?` | `string` | Owning face name when the edge is associated with one face in a larger topology. |
 
-```ts
-dimLine(l: Line2D, opts?: DimOpts): void
-```
+Also: `name: EdgeName`.
 
 ### Sketch Export
 
-#### `sketchToDxf()` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
+#### `sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible).
 
 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.
 
@@ -238,15 +182,11 @@ const s = rect(100, 60);
 const dxf = sketchToDxf(s, { layer: 'cut' });
 ```
 
-```ts
-sketchToDxf(sketch: Sketch, options?: SketchDxfOptions): string
-```
-
 **`SketchDxfOptions`**
 - `layer?: string` — DXF layer name. Default: "0"
 - `colorIndex?: number` — DXF color index (1–255, AutoCAD ACI). Default: 7 (white/black)
 
-#### `sketchToSvg()` — Export a 2D sketch as an SVG string.
+#### `sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string` — Export a 2D sketch as an SVG 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.
 
@@ -257,10 +197,6 @@ const s = rect(100, 60);
 const svg = sketchToSvg(s, { stroke: '#333', strokeWidth: 0.8 });
 ```
 
-```ts
-sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
-```
-
 **`SketchSvgOptions`**
 
 | Option | Type | Description |

package/dist/docs-raw/generated/runtime-names.md

@@ -14,35 +14,35 @@ Agents should avoid declaring these names with top-level `const`, `let`, destruc
 These collision-reserved names are case-sensitive:
 
 ```text
-activateBackend, Analysis, arcSlot, assembly, Assembly, assemblyInstructions, assemblyPreview, Blend
-bom, bomToCsv, boolParam, box, cameraTrajectory, Carrier, chamfer, chamferTrackedEdge
-choiceParam, circle, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d, coalesceEdges
-combine, COMMON_KERFS, compareWith, composeChain, connector, console, constrainedSketch, Constraint
-Counterbore, Curve, Curve3D, cutPlane, cylinder, degrees, difference, difference2d
-dim, dimLine, draft, ellipse, explodeView, faceProfile, fillet, filletCorners
-filletTrackedEdge, fingerJoint, flatPanel, flatPart, formatInstructions, Function, gcode, GCodeBuilder
-getActiveBackend, global, globalThis, group, highlight, Import, ImportedAssembly, importMesh
-importStep, importSvgSketch, initKernel, intersection, intersection2d, intersectWithPlane, joint, jointsView
-laserKit, lib, line, Line2D, linearPattern, linearPattern2d, listParam, loadFont
-loft, Loft, lookupKerf, mirrorCopy, mock, ngon, NurbsCurve3D, nurbsSurface
-NurbsSurface, offsetSolid, param, Param, path, point, Point2D, Points
-polygon, polygonVertices, port, Product, ProductHandleBuilder, ProductHandleFeature, ProductPanelBuilder, ProductRibbonBuilder
-ProductSkin, ProductSkinBuilder, ProductSpoutBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask
-radians, rect, Rectangle2D, Ribs, robotExport, roundedRect, Route3D, scene
-Sculpt, sdf, SdfShape, selectEdge, selectEdges, self, setActiveBackend, setImmediate
-setInterval, setTimeout, Shape, ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch
-sketchToDxf, sketchToSvg, slot, Slot, SolvedAssembly, spec, sphere, spline2d
-star, stroke, Surface, SurfaceBody, SurfaceMembers, surfacePatch, sweep, tabSlot
-text2d, textWidth, torus, toShape, Transform, union, union2d, variableSweep
-verify, viewConfig, Viewport, window, Wood
+activateBackend, Analysis, arcSlot, assembly, Assembly, Blend, bom, box
+cameraTrajectory, Carrier, chamfer, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d
+coalesceEdges, compareWith, connector, console, constrainedSketch, Curve, Curve3D, cutPlane
+cylinder, difference, difference2d, dim, draft, ellipse, explodeView, faceProfile
+fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis, group
+Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint, Laser
+lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft, mirrorCopy
+mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param, path
+Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, ProductRibbonBuilder
+ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
+Rectangle2D, robotExport, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
+selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, torus, toShape, Transform, union
+union2d, variableSweep, verify, Viewport, window, Wood
 ```
 
 <!-- forgecad-skill:exclude-start symbol="compatibility runtime names" reason="Compatibility-only renamed runtime globals." -->
 Compatibility-only renamed runtime globals are also reserved in human-authored scripts, but are omitted from shipped agent skills so agents do not learn retired authoring APIs:
 
 ```text
-connectEdges, Helix, HelixCurve, hermiteTransitionG2, loftAlongSpine, nurbs3d, spline3d, transitionCurve
-transitionSurface
+assemblyInstructions, assemblyPreview, bomToCsv, boolParam, chamferTrackedEdge, choiceParam, circle, combine
+COMMON_KERFS, composeChain, connectEdges, Constraint, Counterbore, degrees, dimLine, filletCorners
+filletTrackedEdge, fingerJoint, flatPanel, flatPart, formatInstructions, Helix, HelixCurve, hermiteTransitionG2
+highlight, importMesh, importStep, importSvgSketch, jointsView, laserKit, line, listParam
+loftAlongSpine, lookupKerf, nurbs3d, nurbsSurface, point, ProductHandleBuilder, ProductHandleFeature, ProductSpoutBuilder
+radians, Ribs, Slot, spline3d, star, surfacePatch, tabSlot, transitionCurve
+transitionSurface, viewConfig
 ```
 <!-- forgecad-skill:exclude-end -->