forgecad 0.10.0 → 0.10.2

package/examples/robotics/scout-cam-rover-simready/README.md

@@ -0,0 +1,119 @@
+# Scout Cam Rover SimReady Example
+
+This is a copied, source-authored simulation version of the personal Scout Cam Rover model. The `.forge.js` file returns the normal assembly, and the same assembly carries the simulation contract through `withSimulation(...)`.
+
+## What Is Sim-Ready Here
+
+- Every assembly part has `Sim.body(...)` metadata with mass, physical material, and collision intent.
+- The TPU tires expose connector-based wheel contact surfaces through `Sim.contact.wheelSurface("tread")`.
+- The two wheel joints have velocity drive intent through `Sim.drive.velocity(...)`.
+- The root assembly uses `withSimulation(...)` with a `Sim.controller.diffDrive(...)` controller.
+- SDF export emits a Gazebo Sim DiffDrive plugin that listens on `/model/scout_cam_rover/cmd_vel`.
+
+## Local Checks
+
+Run from the ForgeCAD repo root:
+
+```bash
+node dist-cli/forgecad.js run examples/robotics/scout-cam-rover-simready/main.forge.js
+node dist-cli/forgecad.js check simready examples/robotics/scout-cam-rover-simready/main.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-mjcf
+node dist-cli/forgecad.js export sdf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-sdf
+node dist-cli/forgecad.js export urdf examples/robotics/scout-cam-rover-simready/main.forge.js --output /tmp/scout-cam-rover-urdf
+```
+
+The MJCF package is written to:
+
+```text
+/tmp/scout-cam-rover-mjcf/scout_cam_rover.xml
+/tmp/scout-cam-rover-mjcf/scene.xml
+/tmp/scout-cam-rover-mjcf/scripts/gym_env.py
+/tmp/scout-cam-rover-mjcf/scripts/smoke_control.py
+/tmp/scout-cam-rover-mjcf/scripts/train_balance.py
+/tmp/scout-cam-rover-mjcf/scripts/play_balance.py
+/tmp/scout-cam-rover-mjcf/simready-manifest.json
+```
+
+The SDF package is written to:
+
+```text
+/tmp/scout-cam-rover-sdf/models/scout_cam_rover/model.sdf
+/tmp/scout-cam-rover-sdf/simready-manifest.json
+```
+
+The URDF package is written to:
+
+```text
+/tmp/scout-cam-rover-urdf/scout_cam_rover.urdf
+/tmp/scout-cam-rover-urdf/simready-manifest.json
+```
+
+## Moving It In A Simulator
+
+The fastest local path is MuJoCo. The MJCF export includes a runnable scene and a package-local smoke controller that discovers the exported actuator names from `manifest.json`.
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with pillow python scripts/smoke_control.py --render-gif drive.gif
+```
+
+That command compiles the generated `scene.xml`, commands the wheel velocity actuators, prints a motion summary, and writes `/tmp/scout-cam-rover-mjcf/drive.gif`.
+The generated smoke controller calibrates the diff-drive motor signs inside MuJoCo before it commands semantic forward/turn/reverse motion, so mirrored wheel axes do not require hand-flipped script edits.
+
+The MJCF package also includes a small Gymnasium control lab and starter balance trainer:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/train_balance.py --render-gif balance.gif --fps 10
+```
+
+That writes `policies/balance_linear.json` and `balance.gif`. The trainer is intentionally editable Python boilerplate: ForgeCAD wires the model, actuators, calibrated diff-drive semantics, and observation plumbing; the reward, policy class, curriculum, and RL library choice stay outside the CAD API.
+The GIF duration is controlled by both the simulated `--seconds` value and the rendered `--fps`; 10 FPS maps to a clean 100 ms GIF frame delay in common viewers.
+
+After training, push the policy with an external force pulse:
+
+```bash
+cd /tmp/scout-cam-rover-mjcf
+uv run --python 3.11 --with mujoco --with numpy --with gymnasium --with pillow python scripts/play_balance.py \
+  --policy policies/balance_linear.json \
+  --push-y 1 \
+  --push-at 2 \
+  --push-duration 0.15 \
+  --render-gif balance_push.gif \
+  --fps 10
+```
+
+`play_balance.py` applies the pulse through MuJoCo's root-body external force array and prints the final tilt, survival time, frame count, and approximate GIF duration.
+
+If your desktop supports MuJoCo's GLFW viewer, you can also open the generated scene:
+
+```bash
+uv run --python 3.11 --with mujoco python -m mujoco.viewer --mjcf=/tmp/scout-cam-rover-mjcf/scene.xml
+```
+
+Gazebo Sim is the SDF path, because ForgeCAD's SDF exporter already emits a DiffDrive plugin for the `Sim.controller.diffDrive(...)` metadata.
+
+```bash
+export GZ_SIM_RESOURCE_PATH=/tmp/scout-cam-rover-sdf/models:${GZ_SIM_RESOURCE_PATH}
+gz sim empty.sdf
+gz service -s /world/empty/create \
+  --reqtype gz.msgs.EntityFactory \
+  --reptype gz.msgs.Boolean \
+  --timeout 300 \
+  --req 'sdf_filename: "/tmp/scout-cam-rover-sdf/models/scout_cam_rover/model.sdf", name: "scout_cam_rover"'
+gz topic -t /model/scout_cam_rover/cmd_vel \
+  -m gz.msgs.Twist \
+  -p 'linear: {x: 0.15}, angular: {z: 0.0}'
+```
+
+Those commands require Gazebo Sim to be installed on the host. This repo check does not execute Gazebo, Isaac Sim, MuJoCo, or any physics engine.
+
+## Important Physics Caveat
+
+This robot is a two-wheel self-balancing rover. The exported DiffDrive controller can command the wheel joints, and the generated MuJoCo package includes a starter balance trainer, but the policy itself is simulator-side code. In a real physics project, the model usually needs one of these next:
+
+- A quick demo stabilizer: add a caster, skid, or temporary roll/pitch constraint so basic drive motion is inspectable.
+- A faithful robot controller: add IMU feedback and a balance PID/LQR loop that commands the wheel velocity or torque.
+- A simulator integration layer: connect the exported model to ROS 2 control, Gazebo systems, Isaac controllers, PufferLib, MJX, or another MuJoCo actuator/controller stack.
+
+Without that controller or stabilizer, the wheels can move but the body may fall over.

package/examples/robotics/scout-cam-rover-simready/lib/dims.js

@@ -0,0 +1,140 @@
+// Scout cam rover — shared dimension tree (pure data/math, no geometry).
+// World frame: Z up, ground z=0, axle along X at z=AXLE_Z, front of robot faces -Y.
+// All printed-part interfaces derive from these numbers; change here, not in parts.
+
+function compute(p) {
+  const wall = p.wall; // printed shell wall thickness
+
+  // ---- drive line / wheels --------------------------------------------------
+  const tireOD = p.wheelOD; // outer diameter incl. TPU tire
+  const tireThk = 5; // radial
+  const tireW = 14;
+  const rimOD = tireOD - 2 * tireThk;
+  const rimID = rimOD - 12; // rim band 6 thick radially
+  const rimW = 14;
+  const axleZ = tireOD / 2;
+
+  // N20 micro gearmotor (purchased): body 12 wide x 10 tall, 24 long incl gearbox,
+  // D-shaft d3 x 9.5 with 2.5 flat.
+  const motor = {
+    w: 12, h: 10, len: 24, // gearbox front face = mating plane
+    shaftD: 3, shaftFlat: 2.5, shaftLen: 9.5,
+    noseBossD: 4, noseBossL: 1.2, // small ring around shaft exit
+  };
+
+  // ---- chassis tub ----------------------------------------------------------
+  const tub = {
+    w: 70, d: 72, h: 52, z0: axleZ - 26, // base z (world) — axle centered in tub height
+    cornerR: 6,
+    wall: wall,
+    floorT: 2.8,
+    postSq: 12, postInset: 6, // corner posts receiving the shell plugs
+    sideScrewZ: 47, // tub-local height of the 4 horizontal shell screws
+  };
+  tub.axleZl = axleZ - tub.z0; // axle height in tub-local Z
+
+  // motor pod (printed, black): hides shaft exit, wheel hub runs inside its bore
+  const pod = {
+    od: 34, len: 14, boreD: 24,
+    screwR: 14.0, screwN: 3, // M2 from inside tub through the wall into pod bosses
+    pilotD: 1.7, wallClearD: 1.9, pilotDepth: 6,
+  };
+
+  // wheel hub geometry (wheel-local: z=0 bore mouth face, +Z outward)
+  const hub = {
+    bossD: 20,
+    bossL: 14, // reaches from inside pod bore out to the spoke web
+    boreD: 3.2, boreFlat: 2.65, boreDepth: 9,
+    faceHoleN: 5, faceHoleD: 2.6, faceHoleR: 6,
+  };
+  const web = { t: 6, z0: hub.bossL }; // spoke web axial band (wheel-local)
+  const rim = { z0: web.z0 - (rimW - web.t) / 2 }; // rim band centered on web
+  // wheel-local Z of bore mouth maps to world |x| = tub.w/2 + 1.5 (mouth sits 1.5 outside the wall,
+  // inside the pod bore). Pod outer face at tub.w/2 + pod.len.
+  const wheelMouthX = tub.w / 2 + 1.5;
+
+  // battery: 2x18650 holder (purchased) mounted vertically on the body shell rear
+  // inner wall — high mass is correct for an inverted-pendulum self-balancer.
+  const batt = { w: 70, h: 42, d: 21, mountHoleSpan: 50, zc: 38 }; // zc = shell-local center
+
+  // service door in the tub front wall (exposes driver / IMU / wiring bay)
+  const door = {
+    openW: 44, openH: 22, zc: 19, // tub-local opening, center height
+    panelW: 54, panelH: 34, panelT: 2.0,
+    plugT: 2.2, slop: 0.3, // plug per-side clearance into opening
+    recess: 1.0, recessSlop: 0.4,
+    screwDX: 23.5, screwDZ: 13.5, // screw offsets from door center
+    pilotD: 1.7, screwHeadD: 3.8, bossD: 6, bossLen: 7,
+  };
+
+  // electronics in the tub bay (purchased modules on printed floor posts)
+  const boards = {
+    standoffH: 4,
+    drv: { w: 16, d: 18, t: 1.6, x: -12, y: -22.5 },  // DRV8833 dual H-bridge
+    buck: { w: 22, d: 17, t: 1.6, x: 7.6, y: -22.5 }, // MP1584 5V buck
+    mpu: { w: 16.5, d: 21.5, t: 1.6, x: 0, y: 3 },    // MPU6050 IMU (mid-bay)
+  };
+  const sw = { w: 13, h: 9, t: 9, plateW: 15, plateH: 11, plateT: 1.8, zc: 14 }; // rocker, rear wall
+
+  // ---- body shell (upper cube) ---------------------------------------------
+  const body = {
+    w: 84, d: 92, h: 88, cornerR: 13,
+    yOff: -4, // shell center sits 4mm toward the front of the tub center
+    topT: 3.0,
+    plugSq: 8, plugL: 9.7, socketSq: 8.3, socketDepth: 10, // 4 corner plugs into tub posts
+    plugInsetX: 10, plugInsetY: 10, // plug centers from tub inner corners
+  };
+  // neck + ring on top of shell (printed as part of shell)
+  const neck = { od: 44, h: 14, boreD: 36, ringOD: 50, ringH: 4 };
+
+  // camera (front face of shell, shell-local: centered XY, base z=0)
+  const cam = {
+    zc: 52, // lens center height above shell base
+    recessD: 44, recessDepth: 1.0,
+    holeD: 26,
+    screwR: 18.5, screwN: 4, pilotD: 1.7, screwStartDeg: 0,
+    bezelOD: 43.4, bezelID: 28, bezelT: 3.4, // proud of face by bezelT - recessDepth
+    cowlD: 27.8, cowlT: 3.0, apertureD: 9.5,
+  };
+
+  // ESP32-CAM (purchased): PCB 27 x 40.5 x 1.6, lens barrel d8 x 6.5 on front
+  const esp = { pcbW: 27, pcbH: 40.5, pcbT: 1.6, barrelD: 8, barrelL: 6.5, compT: 3.0 };
+
+  // side vents: skewed recessed panel + 5 vertical through slots, both side faces
+  const vent = {
+    n: 5, slotW: 4.5, slotL: 36, pitch: 11,
+    recessDepth: 0.8, skewDZ: 14, // rear edge of band this much higher than front
+    yc: 3, zc: 56, bandW: 58, bandH: 52, // band center (shell-local y/z) and size
+  };
+
+  // SG90 servo (purchased) hung under a bridge bar across the neck-bore opening.
+  // Servo-local frame: z=0 at the tab TOP plane (mates upward against the bosses);
+  // spline axis at local x=0.
+  const servo = {
+    bodyW: 23, bodyD: 12.4, bodyDown: 19, bodyUp: 4.5, // body extent below/above tab plane
+    bodyXc: -5.6, // body center offset so the spline sits at x=0
+    tabSpan: 32.4, tabT: 2.5, tabHoleXa: -13.75, tabHoleXb: 13.75, // relative to body center
+    towerH: 4.6, towerD: 11.8, splineD: 4.8, splineH: 3.2,
+    hornD: 20.6, hornT: 1.8, hornHubD: 7.4, // round horn pressed on the spline
+    tabPlaneZ: 78.2, // shell-local height of the tab plane
+    bossSq: 8, // printed bosses hanging from the bridge bar
+  };
+  const bridge = { w: 10, holeD: 13 }; // bar left across the neck-bore wall opening
+
+  // turret (printed black) rides the servo horn through the neck bore
+  const turret = {
+    baseD: 40, baseH: 5, lugN: 4, lugW: 5, lugT: 2, lugH: 2.4,
+    barrelD: 34, barrelH: 15, capD: 37, capH: 3,
+    colD: 14, colHubD: 25, colHubH: 5, colLen: 12.5, // column reaches the horn through the neck
+    socketD: 21.2, socketDepth: 2.0,
+    gapAboveNeck: 1.2, // running gap between turret base underside and neck ring top
+  };
+
+  return {
+    wall, axleZ, tireOD, tireThk, tireW, rimOD, rimID, rimW,
+    motor, tub, pod, hub, web, rim, wheelMouthX,
+    batt, door, boards, sw, body, neck, cam, esp, vent, servo, bridge, turret,
+  };
+}
+
+module.exports = { compute };

package/examples/robotics/scout-cam-rover-simready/main.forge.js

@@ -0,0 +1,343 @@
+// Scout Cam Rover — a two-wheel self-balancing camera robot, replicated from a
+// reference render. Fully home-buildable: FDM-printed teal PLA shells, black PLA
+// pods/turret, TPU tires, and cheap purchased electronics (2x N20 gearmotors,
+// ESP32-CAM behind the front bezel, SG90 pan servo under the top turret,
+// DRV8833 + MPU6050 + MP1584, 2x18650 pack high in the body — an inverted
+// pendulum balances better with mass up high; firmware: any ESP32 balance-bot
+// sketch, e.g. B-robot style PID on the MPU6050).
+//
+// World frame: Z up, ground z=0, axle along X at z=55, front faces -Y.
+// Motion joints: drive_left / drive_right (wheel spin, mirrored axes; MuJoCo
+// calibration confirms forward roll is drive_left=+θ with drive_right=−θ)
+// and turret_pan (SG90, ±90°).
+
+const wallP = param('wall_thickness', 2.4, { min: 2.0, max: 3.0, step: 0.1, unit: 'mm' });
+const wheelODP = param('wheel_od', 110, { min: 96, max: 130, step: 1, unit: 'mm' });
+const auditP = Param.bool('Audit collisions (slow)', false);
+
+const dimsMod = require('./lib/dims.js');
+const D = dimsMod.compute({ wall: wallP, wheelOD: wheelODP });
+
+const paramsDown = { wall_thickness: wallP, wheel_od: wheelODP };
+const wheelMod = require('./parts/wheel.forge.js', paramsDown);
+const chassisMod = require('./parts/chassis.forge.js', paramsDown);
+const bodyMod = require('./parts/body.forge.js', paramsDown);
+const turretMod = require('./parts/turret.forge.js', paramsDown);
+const hwMod = require('./parts/hardware.forge.js');
+
+const simMaterials = {
+  plaTeal: Sim.material('FDM PLA teal', {
+    densityKgM3: 1240,
+    staticFriction: 0.42,
+    dynamicFriction: 0.32,
+    restitution: 0.05,
+  }),
+  plaBlack: Sim.material('FDM PLA black', {
+    densityKgM3: 1240,
+    staticFriction: 0.4,
+    dynamicFriction: 0.3,
+    restitution: 0.05,
+  }),
+  tpu: Sim.material('TPU 95A tire', {
+    densityKgM3: 1200,
+    staticFriction: 1.0,
+    dynamicFriction: 0.85,
+    restitution: 0.18,
+  }),
+  steel: Sim.material('steel hardware', {
+    densityKgM3: 7850,
+    staticFriction: 0.35,
+    dynamicFriction: 0.25,
+    restitution: 0.04,
+  }),
+  electronics: Sim.material('electronics assembly', {
+    densityKgM3: 1500,
+    staticFriction: 0.45,
+    dynamicFriction: 0.32,
+    restitution: 0.04,
+  }),
+  battery: Sim.material('18650 lithium cell', {
+    densityKgM3: 2600,
+    staticFriction: 0.35,
+    dynamicFriction: 0.25,
+    restitution: 0.03,
+  }),
+};
+
+const simBody = (massKg, material, options = {}) => Sim.body({
+  massKg,
+  material,
+  collider: options.collider ?? Sim.collider.convexHull(),
+  contacts: options.contacts,
+});
+
+const wheelContact = { tread: Sim.contact.wheelSurface('tread') };
+const wheelRadiusMm = D.tireOD / 2;
+const wheelSeparationMm = 2 * (D.wheelMouthX + D.rim.z0 + D.tireW / 2);
+
+// ---- build all parts in their local frames ----------------------------------
+const tub = chassisMod.make.buildTub(D);
+const door = chassisMod.make.buildDoor(D);
+const podL = chassisMod.make.buildPod(D);
+const podR = chassisMod.make.buildPod(D);
+const motorL = chassisMod.make.buildMotor(D);
+const motorR = chassisMod.make.buildMotor(D);
+const mods = chassisMod.make.buildBoards(D);
+const rocker = chassisMod.make.buildSwitch(D);
+
+const shell = bodyMod.make.buildShell(D);
+const bezel = bodyMod.make.buildBezel(D);
+const cowl = bodyMod.make.buildCowl(D);
+const espParts = bodyMod.make.buildEsp(D);
+const servoParts = bodyMod.make.buildServo(D);
+const battHolder = bodyMod.make.buildBatteryHolder(D);
+const cellA = bodyMod.make.buildCell(D, -1);
+const cellB = bodyMod.make.buildCell(D, 1);
+
+const wheelL = wheelMod.make.buildWheel(D);
+const wheelR = wheelMod.make.buildWheel(D);
+const turret = turretMod.make.buildTurret(D);
+
+// ---- assembly ----------------------------------------------------------------
+let rover = assembly('Scout Cam Rover')
+  .addPart('Chassis Tub', tub, {
+    transform: Transform.translation(0, 0, D.tub.z0),
+    metadata: { material: 'PLA teal', process: 'FDM', qty: 1 },
+    sim: simBody(0.11, simMaterials.plaTeal),
+  })
+  .addPart('Service Door', door, { metadata: { material: 'PLA teal', process: 'FDM' }, sim: simBody(0.018, simMaterials.plaTeal) })
+  .addPart('Motor Pod L', podL, { metadata: { material: 'PLA black', process: 'FDM' }, sim: simBody(0.022, simMaterials.plaBlack) })
+  .addPart('Motor Pod R', podR, { metadata: { material: 'PLA black', process: 'FDM' }, sim: simBody(0.022, simMaterials.plaBlack) })
+  .addPart('Gearmotor L', motorL, { metadata: { material: 'purchased', notes: 'N20 6V 150RPM' }, sim: simBody(0.012, simMaterials.steel, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Gearmotor R', motorR, { metadata: { material: 'purchased', notes: 'N20 6V 150RPM' }, sim: simBody(0.012, simMaterials.steel, { collider: Sim.collider.boundingBox() }) })
+  .addPart('DRV8833', mods.drv, { metadata: { material: 'purchased' }, sim: simBody(0.004, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('MP1584 Buck', mods.buck, { metadata: { material: 'purchased' }, sim: simBody(0.006, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('MPU6050', mods.mpu, { metadata: { material: 'purchased' }, sim: simBody(0.003, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Rocker Switch', rocker, { metadata: { material: 'purchased' }, sim: simBody(0.006, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Body Shell', shell, { metadata: { material: 'PLA teal', process: 'FDM' }, sim: simBody(0.16, simMaterials.plaTeal) })
+  .addPart('Camera Bezel', bezel, { metadata: { material: 'PLA teal', process: 'FDM' }, sim: simBody(0.012, simMaterials.plaTeal) })
+  .addPart('Lens Cowl', cowl, { metadata: { material: 'PLA black', process: 'FDM' }, sim: simBody(0.008, simMaterials.plaBlack) })
+  .addPart('ESP32-CAM Board', espParts.board, { metadata: { material: 'purchased' }, sim: simBody(0.008, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('ESP32-CAM Optics', espParts.optics, { metadata: { material: 'purchased' }, sim: simBody(0.004, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Servo Body', servoParts.body, { metadata: { material: 'purchased', notes: 'SG90 9g' }, sim: simBody(0.009, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Servo Horn', servoParts.horn, { metadata: { material: 'purchased', notes: 'SG90 round horn' }, sim: simBody(0.002, simMaterials.plaBlack) })
+  .addPart('Battery Holder', battHolder, { metadata: { material: 'purchased', notes: '2x18650 holder' }, sim: simBody(0.025, simMaterials.electronics, { collider: Sim.collider.boundingBox() }) })
+  .addPart('18650 Cell A', cellA, { metadata: { material: 'purchased' }, sim: simBody(0.045, simMaterials.battery, { collider: Sim.collider.boundingBox() }) })
+  .addPart('18650 Cell B', cellB, { metadata: { material: 'purchased' }, sim: simBody(0.045, simMaterials.battery, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Wheel Rim L', wheelL.rim, { metadata: { material: 'PLA teal', process: 'FDM' }, sim: simBody(0.028, simMaterials.plaTeal) })
+  .addPart('Tire L', wheelL.tire, { metadata: { material: 'TPU 95A', process: 'FDM' }, sim: simBody(0.038, simMaterials.tpu, { contacts: wheelContact }) })
+  .addPart('Drive Shaft L', wheelL.shaft, { metadata: { material: 'purchased', notes: 'N20 output shaft' }, sim: simBody(0.002, simMaterials.steel, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Wheel Rim R', wheelR.rim, { metadata: { material: 'PLA teal', process: 'FDM' }, sim: simBody(0.028, simMaterials.plaTeal) })
+  .addPart('Tire R', wheelR.tire, { metadata: { material: 'TPU 95A', process: 'FDM' }, sim: simBody(0.038, simMaterials.tpu, { contacts: wheelContact }) })
+  .addPart('Drive Shaft R', wheelR.shaft, { metadata: { material: 'purchased', notes: 'N20 output shaft' }, sim: simBody(0.002, simMaterials.steel, { collider: Sim.collider.boundingBox() }) })
+  .addPart('Turret', turret, { metadata: { material: 'PLA black', process: 'FDM' }, sim: simBody(0.024, simMaterials.plaBlack) });
+
+// individual screws (separate purchased parts, one bearing connector each)
+const screwSpecs = [];
+for (let i = 0; i < 4; i++) screwSpecs.push([`Door Screw ${i + 1}`, 8, 'Chassis Tub', `door_screw_${i}`]);
+for (const sd of ['l', 'r']) for (let i = 0; i < 3; i++) {
+  screwSpecs.push([`Pod Screw ${sd.toUpperCase()}${i + 1}`, 8, 'Chassis Tub', `pod_screw_${sd}_${i}`]);
+}
+for (let i = 0; i < 4; i++) screwSpecs.push([`Shell Screw ${i + 1}`, 8, 'Chassis Tub', `shell_screw_${i}`]);
+for (let i = 0; i < 4; i++) screwSpecs.push([`Bezel Screw ${i + 1}`, 6, 'Body Shell', `bezel_screw_${i}`]);
+for (const [name, len, parent, conn] of screwSpecs) {
+  rover = rover.addPart(name, hwMod.make.screwM2(len), {
+    metadata: { material: 'steel', notes: `M2x${len}` },
+    sim: simBody(len >= 8 ? 0.0005 : 0.00035, simMaterials.steel, { collider: Sim.collider.boundingBox() }),
+  });
+  rover = rover.connect(`${parent}.${conn}`, `${name}.seat`, { as: `${conn}_joint`, type: 'fixed' });
+}
+
+// fixed mounts (each interface is a connector pair)
+rover = rover
+  .connect('Chassis Tub.door_frame', 'Service Door.back', { as: 'door_mount', type: 'fixed' })
+  .connect('Chassis Tub.pod_seat_l', 'Motor Pod L.flange', { as: 'pod_l_mount', type: 'fixed' })
+  .connect('Chassis Tub.pod_seat_r', 'Motor Pod R.flange', { as: 'pod_r_mount', type: 'fixed' })
+  .connect('Chassis Tub.motor_seat_l', 'Gearmotor L.nose', { as: 'motor_l_mount', type: 'fixed' })
+  .connect('Chassis Tub.motor_seat_r', 'Gearmotor R.nose', { as: 'motor_r_mount', type: 'fixed' })
+  .connect('Chassis Tub.boards_drv', 'DRV8833.mount', { as: 'drv_mount', type: 'fixed' })
+  .connect('Chassis Tub.boards_buck', 'MP1584 Buck.mount', { as: 'buck_mount', type: 'fixed' })
+  .connect('Chassis Tub.boards_mpu', 'MPU6050.mount', { as: 'mpu_mount', type: 'fixed' })
+  .connect('Chassis Tub.switch_seat', 'Rocker Switch.mount', { as: 'switch_mount', type: 'fixed' })
+  .connect('Chassis Tub.deck', 'Body Shell.base', { as: 'shell_mount', type: 'fixed' })
+  .connect('Body Shell.cam_recess', 'Camera Bezel.back', { as: 'bezel_mount', type: 'fixed' })
+  .connect('Body Shell.cam_cowl', 'Lens Cowl.back', { as: 'cowl_mount', type: 'fixed' })
+  .connect('Body Shell.esp_cradle', 'ESP32-CAM Board.face', { as: 'esp_mount', type: 'fixed' })
+  .connect('Body Shell.esp_optics', 'ESP32-CAM Optics.face', { as: 'esp_optics_mount', type: 'fixed' })
+  .connect('Body Shell.servo_mount', 'Servo Body.tabs', { as: 'servo_mount', type: 'fixed' })
+  .connect('Body Shell.servo_horn_mount', 'Servo Horn.tabs', { as: 'servo_horn_mount', type: 'fixed' })
+  .connect('Body Shell.batt_mount', 'Battery Holder.back', { as: 'batt_mount', type: 'fixed' })
+  .connect('Body Shell.cell_a', '18650 Cell A.back', { as: 'cell_a_mount', type: 'fixed' })
+  .connect('Body Shell.cell_b', '18650 Cell B.back', { as: 'cell_b_mount', type: 'fixed' });
+
+// motion joints; tires and shafts are fixed children of the spinning rims
+rover = rover
+  .connect('Gearmotor L.shaft_tip', 'Wheel Rim L.bore', {
+    as: 'drive_left', min: -720, max: 720, default: 0, unit: '°',
+    drive: Sim.drive.velocity({ maxTorqueNm: 0.08, maxSpeedRpm: 150, damping: 0.015, friction: 0.006 }),
+  })
+  .connect('Gearmotor R.shaft_tip', 'Wheel Rim R.bore', {
+    as: 'drive_right', min: -720, max: 720, default: 0, unit: '°',
+    drive: Sim.drive.velocity({ maxTorqueNm: 0.08, maxSpeedRpm: 150, damping: 0.015, friction: 0.006 }),
+  })
+  .connect('Wheel Rim L.tire_seat', 'Tire L.seat', { as: 'tire_l_fit', type: 'fixed' })
+  .connect('Wheel Rim L.shaft_seat', 'Drive Shaft L.seat', { as: 'shaft_l_fit', type: 'fixed' })
+  .connect('Wheel Rim R.tire_seat', 'Tire R.seat', { as: 'tire_r_fit', type: 'fixed' })
+  .connect('Wheel Rim R.shaft_seat', 'Drive Shaft R.seat', { as: 'shaft_r_fit', type: 'fixed' })
+  .connect('Servo Horn.spline', 'Turret.hub', {
+    as: 'turret_pan', min: -90, max: 90, default: 0, unit: '°',
+    drive: Sim.drive.velocity({ maxTorqueNm: 0.16, maxSpeedRpm: 60, damping: 0.04, friction: 0.01 }),
+  });
+
+rover = rover.withSimulation({
+  rootPart: 'Chassis Tub',
+  profile: Sim.profile.robotBodyRunnable(),
+  controllers: [
+    Sim.controller.diffDrive({
+      leftJoints: ['drive_left'],
+      rightJoints: ['drive_right'],
+      wheelRadiusMm,
+      wheelSeparationMm,
+    }),
+  ],
+});
+
+// ---- animations ---------------------------------------------------------------
+// forward roll = drive_left +θ, drive_right −θ (mirrored revolute axes)
+rover = rover
+  .addAnimation('Drive & scan', {
+    duration: 9, loop: true, continuous: true, default: true,
+    keyframes: [
+      { values: { drive_left: 0, drive_right: 0, turret_pan: 0 } },
+      { values: { drive_left: 240, drive_right: -240, turret_pan: 55 } },
+      { values: { drive_left: 480, drive_right: -480, turret_pan: -55 } },
+      { values: { drive_left: 720, drive_right: -720, turret_pan: 0 } },
+    ],
+  })
+  .addAnimation('Spin in place', {
+    duration: 6, loop: true, continuous: true,
+    keyframes: [
+      { values: { drive_left: 0, drive_right: 0, turret_pan: 0 } },
+      { values: { drive_left: -360, drive_right: -360, turret_pan: 45 } },
+      { values: { drive_left: -720, drive_right: -720, turret_pan: -45 } },
+      { values: { drive_left: -720, drive_right: -720, turret_pan: 0 } },
+    ],
+  })
+  .addAnimation('Camera sweep', {
+    duration: 4, loop: true, continuous: true,
+    keyframes: [
+      { values: { turret_pan: 0 } },
+      { values: { turret_pan: 88 } },
+      { values: { turret_pan: -88 } },
+      { values: { turret_pan: 0 } },
+    ],
+  });
+
+// ---- pose verification ---------------------------------------------------------
+const poses = [
+  { drive_left: 0, drive_right: 0, turret_pan: 0 },
+  { drive_left: -45, drive_right: 45, turret_pan: 60 },
+  { drive_left: -137, drive_right: 290, turret_pan: -90 },
+  { drive_left: 720, drive_right: -720, turret_pan: 90 },
+];
+for (const pose of poses) {
+  const s = rover.solve(pose);
+  const tag = `dl=${pose.drive_left} dr=${pose.drive_right} pan=${pose.turret_pan}`;
+  verify.that(`solve converges (${tag})`, () => s.warnings().length === 0,
+    `solver warnings: ${s.warnings().join('; ')}`);
+  verify.clearanceBetween(`wheel R clears pod R (${tag})`, s.getPart('Wheel Rim R'), s.getPart('Motor Pod R'), 0.4, 80);
+  verify.clearanceBetween(`wheel L clears tub (${tag})`, s.getPart('Wheel Rim L'), s.getPart('Chassis Tub'), 0.4, 80);
+  verify.clearanceBetween(`tire R clears body shell (${tag})`, s.getPart('Tire R'), s.getPart('Body Shell'), 2.0, 80);
+  verify.clearanceBetween(`turret clears shell neck (${tag})`, s.getPart('Turret'), s.getPart('Body Shell'), 0.4, 80);
+  verify.clearanceBetween(`turret clears servo body (${tag})`, s.getPart('Turret'), s.getPart('Servo Body'), 0.4, 80);
+}
+
+const sDefault = rover.solve({});
+const gDefault = sDefault.toGroup();
+verify.connectorDistance('wheel L bore on motor L shaft', gDefault, 'Wheel Rim L.bore', 'Gearmotor L.shaft_tip', 0, 0.01);
+verify.connectorDistance('wheel R bore on motor R shaft', gDefault, 'Wheel Rim R.bore', 'Gearmotor R.shaft_tip', 0, 0.01);
+verify.connectorDistance('turret hub on servo spline', gDefault, 'Turret.hub', 'Servo Horn.spline', 0, 0.01);
+verify.connectorDistance('shell base on tub deck', gDefault, 'Body Shell.base', 'Chassis Tub.deck', 0, 0.01);
+
+// ground contact: tire bottoms at z=0
+const wheelBB = sDefault.getPart('Tire L').boundingBox();
+verify.equal('left tire touches the ground', wheelBB.min[2], 0, 0.05);
+verify.equal('wheel OD as designed', wheelBB.max[2] - wheelBB.min[2], wheelODP, 0.1);
+
+// full pairwise audit (slow) — run with --param "Audit collisions (slow)=1"
+if (auditP) {
+  for (const pose of poses) {
+    const s = rover.solve(pose);
+    const findings = s.collisionReport({ minOverlapVolume: 0.5 });
+    verify.that(`no collisions at dl=${pose.drive_left} pan=${pose.turret_pan}`,
+      () => findings.length === 0,
+      findings.map(f => `${f.partA ?? f.a} vs ${f.partB ?? f.b}: ${JSON.stringify(f)}`).join(' | ').slice(0, 400));
+  }
+}
+
+verify.physicalComponentCount('one jointed assembly', 1);
+
+// ---- BOM ------------------------------------------------------------------------
+bom(1, 'chassis tub', { material: 'PLA teal', process: 'FDM printed' });
+bom(1, 'service door', { material: 'PLA teal', process: 'FDM printed' });
+bom(1, 'body shell', { material: 'PLA teal', process: 'FDM printed' });
+bom(1, 'camera bezel', { material: 'PLA teal', process: 'FDM printed' });
+bom(2, 'wheel rim', { material: 'PLA teal', process: 'FDM printed' });
+bom(2, 'motor pod', { material: 'PLA black', process: 'FDM printed' });
+bom(1, 'lens cowl', { material: 'PLA black', process: 'FDM printed' });
+bom(1, 'pan turret', { material: 'PLA black', process: 'FDM printed' });
+bom(2, 'tire', { material: 'TPU 95A gray', process: 'FDM printed', notes: 'print ID 0.5mm under rim OD for stretch fit' });
+bom(2, 'N20 micro gearmotor 6V 150RPM, 3mm D-shaft', { notes: '~$3 ea' });
+bom(1, 'ESP32-CAM (AI-Thinker) + OV2640', { notes: 'camera + wifi + controller, ~$9' });
+bom(1, 'SG90 micro servo + round horn', { notes: 'turret pan, ~$2.5' });
+bom(1, 'DRV8833 dual H-bridge module', { notes: '~$2' });
+bom(1, 'MPU6050 IMU module', { notes: 'balance sensing, ~$2' });
+bom(1, 'MP1584EN 5V buck module', { notes: '~$1.5' });
+bom(1, 'KCD11 mini rocker switch', { notes: '~$0.5' });
+bom(1, '2x18650 battery holder (wire leads)', { notes: '~$1.5' });
+bom(2, '18650 Li-ion cell, flat top', { notes: 'charge externally' });
+bom(14, 'M2x8 self-tapping screw', { notes: 'door 4, pods 6, shell 4' });
+bom(4, 'M2x6 self-tapping screw, bezel set');
+bom(2, 'M2x6 screw, servo tabs' );
+bom(2, 'M2x6 screw, battery holder');
+bom(1, 'M2x10 screw, turret-to-horn retention');
+bom(1, 'hookup wire + heat-shrink set', { notes: 'motor, battery, servo runs' });
+
+// ---- dimension annotations -------------------------------------------------------
+const trackOuter = D.wheelMouthX + D.rim.z0 + D.tireW;
+dim([-trackOuter, 0, D.axleZ], [trackOuter, 0, D.axleZ], { label: 'Overall width', offset: 30 });
+dim([0, -D.tireOD / 2, 0], [0, -D.tireOD / 2, D.tireOD], { label: 'Wheel OD', offset: 20 });
+dim([0, 60, 0], [0, 60, D.tub.z0 + D.tub.h + D.body.h + D.neck.h + D.turret.baseH + D.turret.barrelH + D.turret.capH + D.turret.gapAboveNeck],
+  { label: 'Overall height', offset: 24 });
+dim([-D.body.w / 2, -4, D.tub.z0 + D.tub.h + 2], [D.body.w / 2, -4, D.tub.z0 + D.tub.h + 2], { label: 'Body width', offset: 16 });
+dim([-D.tub.w / 2, 0, D.tub.z0], [D.tub.w / 2, 0, D.tub.z0], { label: 'Tub width', offset: 12 });
+dim([0, 0, 0], [0, 0, D.axleZ], { label: 'Axle height', offset: 18 });
+
+// ---- scene -----------------------------------------------------------------------
+scene({
+  background: { top: '#c3ccd7', bottom: '#566474' },
+  camera: { position: [320, -380, 300], target: [0, 0, 100], fov: 38 },
+  environment: { preset: 'studio', intensity: 0.2, background: false },
+  lights: [
+    { type: 'ambient', color: '#efe7dc', intensity: 0.16 },
+    { type: 'directional', position: [260, -320, 420], color: '#ffe2bf', intensity: 2.8, castShadow: true },
+    { type: 'directional', position: [-260, 210, 220], color: '#d4e6fb', intensity: 0.85 },
+    { type: 'hemisphere', skyColor: '#c7d3df', groundColor: '#495463', intensity: 0.15 },
+  ],
+  ground: { visible: true, color: '#3c4654', height: 0, receiveShadow: true },
+  postProcessing: {
+    bloom: { intensity: 0.04, threshold: 0.94, radius: 0.28 },
+    vignette: { darkness: 0.4, offset: 0.32 },
+    toneMappingExposure: 1.1,
+  },
+  views: {
+    hero: { camera: { position: [320, -380, 300], target: [0, 0, 100], up: [0, 0, 1], fov: 38 } },
+    front: { camera: { position: [0, -520, 130], target: [0, 0, 105], up: [0, 0, 1], fov: 32 } },
+    side: { camera: { position: [520, 0, 130], target: [0, 0, 105], up: [0, 0, 1], fov: 32 } },
+    rear: { camera: { position: [-300, 380, 280], target: [0, 0, 100], up: [0, 0, 1], fov: 38 } },
+    top: { camera: { position: [10, -40, 560], target: [0, 0, 80], up: [0, 1, 0], fov: 32 } },
+    underside: { camera: { position: [180, -260, -180], target: [0, 0, 70], up: [0, 0, 1], fov: 40 } },
+  },
+});
+
+return rover;