forgecad 0.10.0 → 0.10.2

package/dist-cli/{forgecad_geometry-QOQIIP53.js → forgecad_geometry-7TVSNVUB.js}

@@ -154,6 +154,25 @@ function geometry_create_revolved_regions(regions_json, degrees, segments) {
   }
   return ret[0] >>> 0;
 }
+function geometry_create_sdf_mesh(abi_version, opcodes, arg_a, arg_b, arg_c, constants, output, slot_count, options_json) {
+  const ptr0 = passArray8ToWasm0(opcodes, wasm.__wbindgen_malloc);
+  const len0 = WASM_VECTOR_LEN;
+  const ptr1 = passArray32ToWasm0(arg_a, wasm.__wbindgen_malloc);
+  const len1 = WASM_VECTOR_LEN;
+  const ptr2 = passArray32ToWasm0(arg_b, wasm.__wbindgen_malloc);
+  const len2 = WASM_VECTOR_LEN;
+  const ptr3 = passArray32ToWasm0(arg_c, wasm.__wbindgen_malloc);
+  const len3 = WASM_VECTOR_LEN;
+  const ptr4 = passArrayF64ToWasm0(constants, wasm.__wbindgen_malloc);
+  const len4 = WASM_VECTOR_LEN;
+  const ptr5 = passStringToWasm0(options_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+  const len5 = WASM_VECTOR_LEN;
+  const ret = wasm.geometry_create_sdf_mesh(abi_version, ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3, ptr4, len4, output, slot_count, ptr5, len5);
+  if (ret[2]) {
+    throw takeFromExternrefTable0(ret[1]);
+  }
+  return ret[0] >>> 0;
+}
 function geometry_create_side_profile_cut(spec_json) {
   const ptr0 = passStringToWasm0(spec_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
   const len0 = WASM_VECTOR_LEN;
@@ -249,6 +268,9 @@ function geometry_delete_nurbs_curve(handle) {
 function geometry_delete_nurbs_surface(handle) {
   wasm.geometry_delete_nurbs_surface(handle);
 }
+function geometry_delete_sdf_mesh(handle) {
+  wasm.geometry_delete_sdf_mesh(handle);
+}
 function geometry_export_step(handle) {
   let deferred2_0;
   let deferred2_1;
@@ -509,6 +531,47 @@ function geometry_sample_nurbs_surface(handle, u_samples, v_samples) {
     wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
   }
 }
+function geometry_sdf_mesh_metadata(handle) {
+  let deferred2_0;
+  let deferred2_1;
+  try {
+    const ret = wasm.geometry_sdf_mesh_metadata(handle);
+    var ptr1 = ret[0];
+    var len1 = ret[1];
+    if (ret[3]) {
+      ptr1 = 0;
+      len1 = 0;
+      throw takeFromExternrefTable0(ret[2]);
+    }
+    deferred2_0 = ptr1;
+    deferred2_1 = len1;
+    return getStringFromWasm0(ptr1, len1);
+  } finally {
+    wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+  }
+}
+function geometry_sdf_mesh_tri_verts(handle) {
+  const ret = wasm.geometry_sdf_mesh_tri_verts(handle);
+  if (ret[3]) {
+    throw takeFromExternrefTable0(ret[2]);
+  }
+  var v1 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+  wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+  return v1;
+}
+function geometry_sdf_mesh_vert_properties(handle) {
+  const ret = wasm.geometry_sdf_mesh_vert_properties(handle);
+  if (ret[3]) {
+    throw takeFromExternrefTable0(ret[2]);
+  }
+  var v1 = getArrayF32FromWasm0(ret[0], ret[1]).slice();
+  wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+  return v1;
+}
+function geometry_sdf_mesher_abi_version() {
+  const ret = wasm.geometry_sdf_mesher_abi_version();
+  return ret >>> 0;
+}
 function geometry_select_edges(handle, query_json) {
   let deferred3_0;
   let deferred3_1;
@@ -621,9 +684,38 @@ function __wbg_get_imports() {
     "./forgecad_geometry_bg.js": import0
   };
 }
+function getArrayF32FromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+function getArrayU32FromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
+}
+var cachedFloat32ArrayMemory0 = null;
+function getFloat32ArrayMemory0() {
+  if (cachedFloat32ArrayMemory0 === null || cachedFloat32ArrayMemory0.byteLength === 0) {
+    cachedFloat32ArrayMemory0 = new Float32Array(wasm.memory.buffer);
+  }
+  return cachedFloat32ArrayMemory0;
+}
+var cachedFloat64ArrayMemory0 = null;
+function getFloat64ArrayMemory0() {
+  if (cachedFloat64ArrayMemory0 === null || cachedFloat64ArrayMemory0.byteLength === 0) {
+    cachedFloat64ArrayMemory0 = new Float64Array(wasm.memory.buffer);
+  }
+  return cachedFloat64ArrayMemory0;
+}
 function getStringFromWasm0(ptr, len) {
   return decodeText(ptr >>> 0, len);
 }
+var cachedUint32ArrayMemory0 = null;
+function getUint32ArrayMemory0() {
+  if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
+    cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
+  }
+  return cachedUint32ArrayMemory0;
+}
 var cachedUint8ArrayMemory0 = null;
 function getUint8ArrayMemory0() {
   if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
@@ -631,6 +723,24 @@ function getUint8ArrayMemory0() {
   }
   return cachedUint8ArrayMemory0;
 }
+function passArray32ToWasm0(arg, malloc) {
+  const ptr = malloc(arg.length * 4, 4) >>> 0;
+  getUint32ArrayMemory0().set(arg, ptr / 4);
+  WASM_VECTOR_LEN = arg.length;
+  return ptr;
+}
+function passArray8ToWasm0(arg, malloc) {
+  const ptr = malloc(arg.length * 1, 1) >>> 0;
+  getUint8ArrayMemory0().set(arg, ptr / 1);
+  WASM_VECTOR_LEN = arg.length;
+  return ptr;
+}
+function passArrayF64ToWasm0(arg, malloc) {
+  const ptr = malloc(arg.length * 8, 8) >>> 0;
+  getFloat64ArrayMemory0().set(arg, ptr / 8);
+  WASM_VECTOR_LEN = arg.length;
+  return ptr;
+}
 function passStringToWasm0(arg, malloc, realloc) {
   if (realloc === void 0) {
     const buf = cachedTextEncoder.encode(arg);
@@ -698,6 +808,9 @@ function __wbg_finalize_init(instance, module) {
   wasmInstance = instance;
   wasm = instance.exports;
   wasmModule = module;
+  cachedFloat32ArrayMemory0 = null;
+  cachedFloat64ArrayMemory0 = null;
+  cachedUint32ArrayMemory0 = null;
   cachedUint8ArrayMemory0 = null;
   wasm.__wbindgen_start();
   return wasm;
@@ -791,6 +904,7 @@ export {
   geometry_create_nurbs_surface_handle,
   geometry_create_path_swept_regions,
   geometry_create_revolved_regions,
+  geometry_create_sdf_mesh,
   geometry_create_side_profile_cut,
   geometry_create_sphere,
   geometry_create_surface_grid,
@@ -804,6 +918,7 @@ export {
   geometry_delete,
   geometry_delete_nurbs_curve,
   geometry_delete_nurbs_surface,
+  geometry_delete_sdf_mesh,
   geometry_export_step,
   geometry_export_step_multi,
   geometry_fillet_edges,
@@ -818,6 +933,10 @@ export {
   geometry_nurbs_surface_tessellation,
   geometry_sample_nurbs_curve,
   geometry_sample_nurbs_surface,
+  geometry_sdf_mesh_metadata,
+  geometry_sdf_mesh_tri_verts,
+  geometry_sdf_mesh_vert_properties,
+  geometry_sdf_mesher_abi_version,
   geometry_select_edges,
   geometry_topology,
   geometry_transform,

package/dist-skill/CONTEXT.md

@@ -39,16 +39,16 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 ### Validation and export commands (ask the user to run these)
 
 ```bash
-forgecad run <file.forge.js>                        # geometry diagnostics, verify.* results — run after every edit
-forgecad run <file.forge.js> --debug-imports        # trace import-chain failures
-forgecad check print <file.forge.js> --json         # collisions, mesh health, walls, overhangs, bed contact
-forgecad render 3d <file.forge.js>                  # shaded PNG render
-forgecad render wireframe <file.forge.js>           # edges only — internal geometry, edge flow
-forgecad render section <file.forge.js> --plane XZ  # 2D cross-section (SVG/PNG)
-forgecad capture gif <file.forge.js>                # animated orbit or joint-playback GIF
-forgecad export stl <file.forge.js>                 # mesh for 3D printing
-forgecad export 3mf <file.forge.js>                 # mesh + metadata for 3D printing
-forgecad export step <file.forge.js>                # exact B-rep for CAD interchange
+forgecad run <file.forge.js> [file ...]                        # geometry diagnostics, verify.* results — run after every edit
+forgecad run <file.forge.js> --debug-imports                   # trace import-chain failures
+forgecad check print <file.forge.js> [file ...] --json         # collisions, mesh health, walls, overhangs, bed contact
+forgecad render 3d <file.forge.js> [file ...]                  # shaded PNG render
+forgecad render wireframe <file.forge.js> [file ...]           # edges only — internal geometry, edge flow
+forgecad render section <file.forge.js> [file ...] --plane XZ  # 2D cross-section (SVG/PNG)
+forgecad capture gif <file.forge.js> [file ...]                # animated orbit or joint-playback GIF
+forgecad export stl <file.forge.js> [file ...]                 # mesh for 3D printing
+forgecad export 3mf <file.forge.js> [file ...]                 # mesh + metadata for 3D printing
+forgecad export step <file.forge.js> [file ...]                # exact B-rep for CAD interchange
 ```
 
 Add `--param Name=Value` to test a specific parameter value. Pick the export that matches the goal: STL/3MF for printing, STEP for exact CAD interchange.
@@ -89,7 +89,7 @@ A script must return one of three shapes:
    ];
    ```
 
-3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`.
+3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`. Each key becomes a named group, so don't pile independent parts into one array key (`{ parts: [a, b, c] }`) — the integrity gate reads that as a single fragmented part. Give each part its own key (`{ collar12, collar16, plug }`) or use named descriptors (form 2).
 
 Return an unsolved `Assembly` directly — ForgeCAD solves it at default joint values for display. Use `assembly.solve(state)` for a specific pose. Never call `.toGroup()` just to make an assembly render; use it only when you need `ShapeGroup` composition or named-child lookup.
 
@@ -114,7 +114,7 @@ Resolve labels with `.face(name)` or `.face(query)` — see the Shape class docs
 
 **No explanatory text inside CAD geometry.** Model the physical artifact; explain the design through names, comments, BOM entries, and docs. Use `text2d()` only when letters are part of the real object (engraving, branding, gauge ticks); use `Viewport.label()` only for temporary review/debug annotation — never to compensate for unclear geometry.
 
-**SDF shapes preview natively** when returned directly; call `.toShape()` only when mesh-backed CAD/export behavior is needed. See [SDF docs](../../generated/sdf.md).
+**SDF shapes preview natively** when returned directly — including plain object/array trees of SDF leaves; call `.toShape()` only when mesh-backed CAD/export behavior is needed. See [SDF docs](../../generated/sdf.md).
 
 ---
 
@@ -143,10 +143,10 @@ Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, P
 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, 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
+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
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.
@@ -263,6 +263,8 @@ The `edges` parameter is flexible:
 
 Throws if no edges match the selection, or if `radius` is not a positive finite number.
 
+Selectorless (all-edges) calls draw from a per-run broad edge-feature budget. Exceeding it throws — except in live preview, which skips the finish with a warning for responsiveness. Explicit edge selectors are never budgeted; `FORGECAD_BROAD_EDGE_FEATURE_BUDGET` / `FORGECAD_ALLOW_BROAD_EDGE_FEATURES=1` raise or lift the budget.
+
 ```ts
 // Fillet all edges
 fillet(myShape, 2)
@@ -285,6 +287,8 @@ fillet(base, 5, base.edge('vert-br'))
 
 Produces a 45° bevel at the specified `size` (distance from edge). Edge selections compile into backend operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
 
+Selectorless (all-edges) calls draw from a per-run broad edge-feature budget. Exceeding it throws — except in live preview, which skips the finish with a warning for responsiveness. Explicit edge selectors are never budgeted; `FORGECAD_BROAD_EDGE_FEATURE_BUDGET` / `FORGECAD_ALLOW_BROAD_EDGE_FEATURES=1` raise or lift the budget.
+
 The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, a tracked `EdgeRef` from `shape.edge('vert-br')` (exact compiler-owned path), or `undefined` (all sharp edges).
 
 ```ts
@@ -303,7 +307,7 @@ chamfer(base, 3, base.edge('vert-br'))
 
 Adds a taper angle to the vertical faces of a solid so that it can be extracted from a mold. The neutral plane is the Z position where the draft angle is zero — faces above and below are tapered symmetrically. Typical values for injection molding are 1–5°.
 
-Truck supports vertical-prism solids with Z-axis pull directions. OCCT uses its native draft operation when available. Manifold throws.
+SDF, Manifold, and Truck lower supported vertical-prism solids with Z-axis pull directions to a tapered loft. OCCT uses its native draft operation when available.
 
 ```ts
 // Add 3° draft to a box for injection molding
@@ -1558,18 +1562,21 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
 
 - `dxfSketch(fileName: string, options?: DxfImportOptions): Sketch` — Parse a DXF file and return closed 2D profile geometry as a Sketch. The result can be extruded directly.
 - `svgSketch(fileName: string, options?: SvgImportOptions): Sketch` — Parse an SVG file and return it as a Sketch with options for region filtering, scaling, and simplification.
-- `mesh(fileName: string, options?: { scale?: number; center?: boolean; object?: string; separateObjects?: boolean; }): Shape | ShapeGroup` — Import an external mesh file (STL, OBJ, 3MF).
+- `mesh(fileName: string, options?: MeshImportOptions): Shape | ShapeGroup` — Import an external mesh file (STL, OBJ, 3MF).
 
   By default, 3MF build items are flattened into one Shape for compatibility. Use `separateObjects: true` to import 3MF build items/resource objects as a named ShapeGroup whose children are targetable by `forgecad ls`. Use `object` to import one item by the stable ref/name reported by `forgecad run`.
 
   For 3MF sources, `forgecad run` prints a source-structure table with one line per build item: `[3mf:build:NNN:object:N] name type=... verts=... tris=... bbox=[min] → [max]`. Build items are numbered from `001`; files with no build items list resource objects as `3mf:object:N` instead. Per-item bboxes reveal multi-part structure — account for every substantial item before flattening. Pass any listed stable ref or name as `object` to import that item alone.
 
+  Use `sourceFrame: { up: "+Y" }` when the file was authored in a non-Z-up coordinate system. ForgeCAD remains Z-up; the import is rotated so the named source axis becomes ForgeCAD +Z. Supported values: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
+
   ```js
   const all = Import.mesh("./assembly.3mf", { separateObjects: true });
   const pin = all.child("Pin #001");
   const plate = Import.mesh("./assembly.3mf", { object: "3mf:build:001:object:7" });
+  const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
-- `step(fileName: string): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend.
+- `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.
 
 ---
 
@@ -3868,7 +3875,7 @@ const arm = bottle.path()
 
 # Assembly API
 
-Assembly-owned links, constraints, connectors, solved poses, and robot export.
+Assembly-owned links, constraints, connectors, solved poses, and source-level simulation metadata.
 
 ## Contents
 
@@ -3881,6 +3888,59 @@ Assembly-owned links, constraints, connectors, solved poses, and robot export.
 
 ### Assembly & Joints
 
+#### `Sim.material(name: string, options?: SimMaterialOptions): SimMaterialDef` — Create a named physical material with density and contact coefficients for simulation export and checks.
+
+`SimMaterialOptions`: `{ densityKgM3?: number, staticFriction?: number, dynamicFriction?: number, restitution?: number }`
+
+`SimMaterialDef`: `{ kind: "material", name: string }`
+
+#### `Sim.body(options: SimBodyOptions): SimBodyDef` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces.
+
+**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`
+
+`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string }`
+
+`SimContactDef`: `{ kind: "wheelSurface" | "gripperSurface", connectorName: string }`
+
+`SimBodyDef`: `{ kind: "body" }`
+
+#### `Sim.collider` — Collision-geometry intent constructors for physical parts.
+
+- `Sim.collider.convexHull(): SimColliderDef` — Use a generated collision mesh for the part. This is the default fast rigid-body collider for irregular parts.
+- `Sim.collider.boundingBox(): SimColliderDef` — Use the part bounding box as the collision geometry. This is fastest and works well for chassis and simple blocks.
+- `Sim.collider.visualMesh(): SimColliderDef` — Use the visual mesh as collision geometry. This is exact but usually slower in physics engines.
+- `Sim.collider.none(reason: string): SimColliderDef` — Disable collision for a part with an explicit reason, such as a sensor-only or decorative object.
+
+#### `Sim.drive` — Joint-drive intent constructors for passive or powered assembly joints.
+
+- `Sim.drive.passive(options?: SimPassiveDriveOptions): SimDriveDef` — Mark a joint as passive while preserving damping and friction metadata for simulation export.
+- `Sim.drive.velocity(options: SimVelocityDriveOptions): SimDriveDef` — Mark a revolute joint as velocity-driven with torque and speed limits. Speed is authored in rpm and exported as deg/s or rad/s as needed.
+
+`SimPassiveDriveOptions`: `{ damping?: number, friction?: number }`
+
+`SimVelocityDriveOptions`: `{ maxTorqueNm: number, maxSpeedRpm: number }`
+
+#### `Sim.contact` — Contact-surface metadata over existing part connectors.
+
+- `Sim.contact.wheelSurface(connectorName: string): SimContactDef` — Mark a connector as the wheel tread contact surface for offline checks and downstream simulation metadata.
+- `Sim.contact.gripperSurface(connectorName: string): SimContactDef` — Mark a connector as a gripper pad/contact surface for offline checks and downstream grasp-readiness metadata.
+
+#### `Sim.profile` — Named validation/export profile constructors.
+
+- `Sim.profile.robotBodyRunnable(): SimProfileDef` — SimReady-style profile for a robot body that should be runnable in a physics simulator.
+- `Sim.profile.robotBodyIsaac(): SimProfileDef` — SimReady-style profile for robot bodies targeting Isaac Sim readiness.
+- `Sim.profile.roboticsAssetPhysx(): SimProfileDef` — SimReady-style profile for robotics assets with PhysX-ready rigid bodies and colliders.
+
+`SimProfileDef`: `{ kind: "profile", name: SimProfileName }`
+
+#### `Sim.controller` — Standard controller metadata constructors for simulator package generation.
+
+- `Sim.controller.diffDrive(options: SimDiffDriveControllerOptions): SimDiffDriveControllerDef` — Describe a differential-drive controller from left/right wheel joints and wheel dimensions.
+
+**`SimDiffDriveControllerOptions`**: `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`
+
+`SimDiffDriveControllerDef`: `{ kind: "diffDrive" }`
+
 #### `assembly(name?: string): Assembly` — Create an assembly container with named parts, connectors, and kinematic links.
 
 **Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
@@ -4014,7 +4074,7 @@ const housing = group(
 assembly.addPart("Base Assembly", housing);
 ```
 
-**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
 
 **`PartMetadata`**
 
@@ -4075,7 +4135,9 @@ Frame semantics: `origin` is the pivot/contact point, `axis` the hinge or slide
 
 **Face-to-face:** each connector's axis points outward from its part; mating makes the axes anti-parallel, like a plug meeting a socket (same convention as `matchTo()`).
 
-**Mirrored revolute axes:** revolute values follow the right-hand rule, so a mirrored hinge axis (`[1, 0, 0]` vs `[-1, 0, 0]`) rotates oppositely for the same `+theta`: negate the mirrored side's value and mirror limits as `[min, max] -> [-max, -min]`. Prismatic joints have no handedness flip. Use an explicit per-side sign mapping (or side-neutral link controls) for bilateral mechanisms.
+**Revolute sign:** a positive joint value follows the right-hand rule about the **child** connector's placed axis. Because face-to-face mating makes the axes anti-parallel, that is the *left*-hand rule about the parent connector's outward axis — if `+30` swings the opposite way you expected, you predicted from the parent's axis. `forgecad debug assembly` prints each joint's resolved world axis.
+
+**Mirrored revolute axes:** because of the right-hand rule, a mirrored hinge axis (`[1, 0, 0]` vs `[-1, 0, 0]`) rotates oppositely for the same `+theta`: negate the mirrored side's value and mirror limits as `[min, max] -> [-max, -min]`. Prismatic joints have no handedness flip. Use an explicit per-side sign mapping (or side-neutral link controls) for bilateral mechanisms.
 
 Joint type defaults to the connector's `kind`. For `start`/`end` connectors, `align` / `parentAlign` / `childAlign` (`'start' | 'middle' | 'end'`) choose which point meets.
 
@@ -4102,7 +4164,7 @@ assembly("Door").addPart("Frame", frame).addPart("Door", door)
 | `align?` | `PortAlign` | Shorthand: set both parentAlign and childAlign at once. |
 | `follows?` | `JointFollowOptions` | Slave this joint to another joint: `value = ratio × source + offset` (e.g. a mirrored jaw with `ratio: -1`). |
 
-Also: `as?: string`, `type?: JointType`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`.
+Also: `as?: string`, `type?: JointType`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `drive?: SimDriveDef`.
 
 **`JointFollowOptions`**
 - `joint: string` — Name of the source joint that drives this one.
@@ -4162,6 +4224,12 @@ return mech.solve({ theta: 45 });
 
 **Other**
 
+#### `withSimulation(options: SimAssemblySimulationOptions): Assembly` — Attach the root simulation contract for this assembly.
+
+Use this after adding physical parts and joints. Robot-body profiles require `rootPart`; asset profiles can describe one-part or multi-part physical assets. URDF/SDF exporters and `forgecad check simready` read this contract directly, so model files no longer need a separate `robotExport(...)` side effect.
+
+`SimAssemblySimulationOptions`: `{ profile: SimProfileDef, rootPart?: string, controllers?: SimControllerDef[] }`
+
 #### `edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly` — Add a visual skeleton edge between two rig frame origins.
 
 Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
@@ -4297,7 +4365,7 @@ The sub-assembly must have exactly one root part before it can be merged (collap
 | `connectorRefs?` | `JointConnectorRefs` | Connector refs that define this joint contract. Usually set by `connect()` / `match()`. |
 | `follows?` | `JointFollowOptions` | Slave this joint to another joint: `value = ratio × source + offset`. Use for mechanisms with one physical DOF expressed through several joints — a mirrored gripper jaw (`ratio: -1`), a gear pair, a drive crank turning with its servo. A followed joint stops being an independent control: the Motion view drives it from its source, `solve()` derives its value (a direct state override is ignored with a warning), and limits still clamp the derived value. |
 
-Also: `frame?: TransformInput`, `origin?: Vec3`, `axis?: Vec3`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`.
+Also: `frame?: TransformInput`, `origin?: Vec3`, `axis?: Vec3`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `drive?: SimDriveDef`.
 
 `JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
 
@@ -4369,7 +4437,7 @@ console.log("Collisions", solved.collisionReport());
 
 #### `minClearance(partA: string, partB: string, searchLength?: number): number` — 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.
+Returns `0` if the parts are touching or overlapping. Manifold-backed parts use the exact Manifold gap query. SDF-backed parts use a mesh-derived sampled gap. `searchLength` bounds the Manifold search radius in mm — increase it for widely separated Manifold parts.
 
 ---
 
@@ -4430,12 +4498,14 @@ bom(tubeLen, "rectangular steel tube", {
 | `notes?` | `string` | Free-form notes |
 | `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
-#### `robotExport(options: RobotExportOptions): CollectedRobotExport` — 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. `forgecad export sdf` / `forgecad export urdf` pick up the declaration (see the CLI docs for flags) 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`):
@@ -4454,6 +4524,8 @@ Call `robotExport()` alongside your assembly definition. `forgecad export sdf` /
 - `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.
 
+**Legacy example**
+
 ```ts
 robotExport({
   assembly: rover, // assembly() with parts + revolute wheel joints
@@ -4469,6 +4541,13 @@ robotExport({
 });
 ```
 
+**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)
+```
+
 **`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" }`
@@ -4483,46 +4562,6 @@ robotExport({
 
 `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` — defined in [assembly](/docs/assembly).
-
-`AssemblyPartMateInput` — defined in [assembly](/docs/assembly).
-
-**`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` — defined in [assembly](/docs/assembly).
-
-`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>`
-
-`AssemblyKinematicControlOptions` — defined in [assembly](/docs/assembly).
-
-**`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`**
-- `distance: number` — Signed: positive moves from `fromLink` toward `towardLink`, negative moves away.
-- Also: `name: string`, `fromLink: string`, `towardLink: string`.
-
-`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, or along an entity.
 
 Overloads:

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

@@ -23,7 +23,7 @@ A script must return one of three shapes:
    ];
    ```
 
-3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`.
+3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`. Each key becomes a named group, so don't pile independent parts into one array key (`{ parts: [a, b, c] }`) — the integrity gate reads that as a single fragmented part. Give each part its own key (`{ collar12, collar16, plug }`) or use named descriptors (form 2).
 
 Return an unsolved `Assembly` directly — ForgeCAD solves it at default joint values for display. Use `assembly.solve(state)` for a specific pose. Never call `.toGroup()` just to make an assembly render; use it only when you need `ShapeGroup` composition or named-child lookup.
 
@@ -48,4 +48,4 @@ Resolve labels with `.face(name)` or `.face(query)` — see the Shape class docs
 
 **No explanatory text inside CAD geometry.** Model the physical artifact; explain the design through names, comments, BOM entries, and docs. Use `text2d()` only when letters are part of the real object (engraving, branding, gauge ticks); use `Viewport.label()` only for temporary review/debug annotation — never to compensate for unclear geometry.
 
-**SDF shapes preview natively** when returned directly; call `.toShape()` only when mesh-backed CAD/export behavior is needed. See [SDF docs](../../generated/sdf.md).
+**SDF shapes preview natively** when returned directly — including plain object/array trees of SDF leaves; call `.toShape()` only when mesh-backed CAD/export behavior is needed. See [SDF docs](../../generated/sdf.md).