mohan-bee/tscircuit-robot-vacuum

docs/mechanical-capability-audit.md

# Native tscircuit mechanical capability audit

Audit date: 2026-11-03. Implementation: `robot-mechanical.tsx`.

This is a runnable assembly engineering prototype. It is not a mechanically released vacuum cleaner. The model uses native `assembly.printedpart`, `assembly.part`, JSCAD JSX, a named mounting face, and native explosion stages. No enclosure or part was designed in another CAD application.

## What the implementation proves

The source builds a 320 mm diameter top cover and 318 mm chassis, an open chassis with wheel/roller/sensor openings, four PCB standoffs, lid bosses, a removable hollow dustbin and lid, dirty-air passage, clean-air adapter, roller shroud, caster cup, battery cradle, front bumper, two wheel hubs, two motor brackets and a side-brush hub. These are independent named parts, rather than a single flattened mesh. Battery, LiDAR, motors, tires, roller bristles, filter and caster are explicitly named approximate purchased-part envelopes.

The board plane is Z=0. The chassis exposes `CHASSIS.pcb` at Z=-0.8 for a board of thickness 1.6 mm. Pass `mountedTo="CHASSIS.pcb"` to the main board to exercise native face mounting. All other part locations are authored in one consistent millimetre coordinate system.

An isolated native render with an empty 160 × 130 × 1.6 mm PCB, the native mounting reference and this module was executed successfully. The final counts and checks should be read from the project build report, since integration with the populated PCB adds more CAD records.

## Actual envelope and layout decisions

| Item | Model dimensions / position | Consequence |
|---|---|---|
| Nominal body | 320 mm cover diameter; chassis radius 159 mm | The bumper extends to 328 mm and side-brush bristles protrude farther. 320 mm is not the complete swept footprint. |
| Ground plane | Z=-52.5 mm | Wheel envelopes have radius 32.5 mm at Z=-20 mm. |
| Body height | Lid top Z=35 mm | 87.5 mm from wheel contact to cover top. |
| Overall height | LiDAR top Z=58 mm | 110.5 mm overall; the original 100 mm target was not achieved. |
| PCB | 160 × 130 mm; mounting holes (±72, ±52) mm | Native chassis posts terminate at board underside Z=-0.8 mm. |
| Battery | 105 × 60 × 20 mm at (0,-80,-18) | Top Z=-8 mm gives 7.2 mm clearance to the bare PCB underside; connector/padding/pack-tolerance clearance still needs inspection. |
| Dustbin | 70 × 54 × 29 mm at (-43,-106,16.5) | Smaller than the first sketch so the rear corner clears the circular wall and vertical removal path. |
| Blower | 50 mm cylindrical envelope, 26 mm high at (70,-105,16) | Purchased-unit dimensions and inlet/outlet interfaces are not verified. |
| Wheels | X=±130 mm, Y=0, Z=-20 mm | Open side pockets allow outward removal. Brackets are fixed; suspension is not implemented. |
| Main roller | 120 mm bristle span, 40 mm diameter at Y=90,Z=-32 | Bristle envelope bottom Z=-52 mm is 0.5 mm above nominal wheel contact. Actual brush compliance needs testing. |
| Dirty air | Underside raceway at X=-95, Z=-45…-30 mm | Avoids the wheel motor body and PCB standoffs; 7.5 mm nominal ground clearance. Requires a sealed prototype and airflow verification. |

## Capability matrix grounded in current code

“Not exposed” below means no corresponding primitive was found in the inspected public assembly API; it does not mean the broader ecosystem can never support the task.

| Requirement | Current tscircuit capability | What this robot still lacks / implementation limit |
|---|---|---|
| Custom printable solid geometry | Supported: JSCAD primitive shapes, transforms and CSG union/subtract through `assembly.printedpart.jscad`. Executed here. | Fillet/chamfer support was not relied on. Sharp conceptual duct bends require refinement. Native geometry does not prove a suitable print orientation or air seal. |
| Named assembly parts | Supported: device, part, printedpart and subassembly identities. Executed here. | Purchased part envelopes must be replaced or resized from supplier mechanical drawings. |
| Board-to-part mounting | Supported: named reference rectangles and `mountedTo`; current props also support signed in-plane mount offsets and nonnegative gaps. PCB mount executed here. | Accurate screw engagement, heat-set insert tolerances and supplier motor mount patterns are project work, not automatically generated from a reference face. |
| Imported CAD | Supported: GLB/glTF, STL, OBJ/MTL, STEP and WRL model references in current props/export loaders. | No supplier CAD was imported for this prototype; identities ending in `ENVELOPE` are visibly approximate in source. |
| Exploded assembly | Supported: ordered `assembly.explosion.stage` and straight `move` offsets. Three native stages implemented. | Stages show cover removal, bin removal and outward wheel removal. They do not model screw loosening, cables unplugging or every disassembly step. |
| Collision detection | Supported and executed: core automatically checked the authored explosion and initially found actual interference; geometry and paths were corrected. | The checker tests continuous straight translations and ignores space already occupied at movement start. Zero explosion errors does **not** mean no initial static interference, no rotating interference or a collision-free operating robot. |
| Wheel/bumper/roller kinematic joints | No general revolute/prismatic joint or spring/damper primitive found in inspected `assembly` namespace / props. | Wheel rotation, suspension travel, bumper springs, brush dynamics and operating swept volumes remain unimplemented. Static parts and explosion translations are insufficient substitutes. |
| Physical harness rendering | Supported: `assembly.cable` resolves JST/USB/motor endpoints and infers a path. | Documentation explicitly says its path has no obstacle avoidance or gravity sag, and it creates no pin-to-pin electrical connectivity. This design needs verified harness lengths, wire gauges, strain relief, wire-to-terminal mapping and clamped routes. |
| Assembly drawings | Supported: drawing page, part view, dimension and titleblock primitives; CLI exports a selected drawing SVG. | A controlled drawing pack, datum/tolerance scheme and inspection dimensions are not included in this prototype. |
| Fasteners | Current props contains bolt/fastener schemas, but the inspected core assembly namespace did not export `assembly.bolt`/`assembly.fastener`. | A props schema is not evidence of a runnable primitive. This robot uses printed pilot/clearance holes; actual screw selection and insertion access must be engineered. |
| STL release pack | CLI documented format list includes GLB/glTF/STEP but no `stl` format. Native printed-part plans remain serializable geometry. | Do not infer that GLB is print-ready or that STEP input support guarantees every custom CSG part survives STEP export. If STL files are generated from these native plans, validate every resulting solid and treat them as prototype prints. |
| Printer bed / slicing | No bed-size-aware split, supports, seam planning or slicing workflow demonstrated in the inspected tscircuit assembly API. | A 320 mm cover exceeds many desktop print beds. Cover/chassis splitting, joint design, material shrinkage, orientation and supports remain unresolved. |
| Vacuum performance | A duct can be modeled, but no fluid simulation was found in this assembly workflow. | Pressure loss, leakage, filter loading, debris transport, suction power, clogging and acoustic performance require engineering and physical tests. |
| Mechanical and thermal validation | No structural/thermal solver exposed in the inspected assembly namespace. | Strength, impacts, wheel traction, deformation, battery/motor temperature and enclosure fire behavior are unvalidated. |
| Manufactured assembly | BOM geometry and hole locations are representable. | Supplier-specific motor mounts, bumper return mechanism, brush retention, wheel tread, filter seal, gasket joints, battery straps, charging contacts, sensors and their actual mounts, tolerance stack and fastener access need completion. |

## Known prototype limitations, not platform deficiencies

The clean-air adapter ends at an approximate side of the blower envelope. The chosen blower's real inlet/outlet must determine the final adapter. Dirty-air passages have sharp bends and are a packaging study; the collector/duct connection is not a verified sealed system. The bin needs a gasket, retention latch, filter frame and a serviceable seal. The caster, tires and bristles are simplified envelopes. Motor brackets do not implement suspension or a validated supplier bolt pattern. Cliff apertures do not establish their optical field of view. The body has no tolerance-qualified bumper/sensor arrangement or wheel-drop detection mechanics. The LiDAR is a rough body envelope, not an exact RPLIDAR C1 vendor model or a proven unobstructed scanning plane.

The chassis has pilot holes and the cover has clearance holes, but a full fastener and insert schedule is still required. No high-speed impeller is printed. The battery is a purchased protected 3S pack envelope, and its protection electronics do not become part of the one custom main PCB. These points must not be mislabeled as missing tscircuit features.

## Reproduced native tessellation defect and authoring workaround

The first direct STL serialization of the native `loadCadComponentMesh` output found a numerical CSG seam defect in two compound parts. These were not open-edge defects: CHASSIS had 5,158 triangles, zero boundary edges, six nonmanifold edges, one inconsistent edge and five degenerate triangles. CASTER_CUP had 1,532 triangles, zero boundary edges, four nonmanifold edges, two inconsistent edges and four degenerate triangles. Degenerate triangles contained essentially duplicate cylinder seam vertices, for example X=0 versus X=-1.49×10⁻¹³ mm at the same Y and Z.

The source now uses a `StableCylinder` synchronous JSCAD JSX helper only inside those two parts. It rotates each round primitive locally by 0.017 radians before translation. This offsets the polygonal cylinder seam from the aligned cardinal CSG cut planes while preserving feature centres, heights and nominal radii. The same native loader then generated 5,682 CHASSIS triangles and 1,556 CASTER_CUP triangles with zero boundary, nonmanifold, inconsistent or degenerate counts. No exported triangle data was welded, deleted or repaired. Other round parts retain their original authoring.

This is a verified native geometry/tessellation robustness limitation, with a native authoring workaround. The resulting topology diagnostics still do not prove absence of self-intersections, printability or mechanical fit.

## Primary source evidence

Sources were read on 2026-11-03. Documentation and repository `main` can change; local tests use the pinned project dependencies.

- [Printed parts and named face mounting](https://docs.tscircuit.com/elements/assembly-printedpart).
- [Advanced assembly and arbitrary attachment face orientation](https://docs.tscircuit.com/guides/advanced-assembly).
- [Assembly cable capabilities and stated routing limits](https://docs.tscircuit.com/elements/assembly-cable).
- [Explosion stages, move semantics and sampling](https://docs.tscircuit.com/elements/assembly-explosion-stage).
- [CLI export format list and STEP/GLB support](https://docs.tscircuit.com/command-line/tsci-export).
- [Drawing dimensions](https://docs.tscircuit.com/elements/assembly-drawing-dimension).
- [Pinned inspected core assembly namespace](https://github.com/tscircuit/core/blob/0ef57435c535a65d3d49826443b9da70f248b358/lib/namespaced-elements/assembly.ts).
- [Pinned inspected native swept collision implementation](https://github.com/tscircuit/core/blob/0ef57435c535a65d3d49826443b9da70f248b358/lib/assembly-explosion/check-circuit-json-assembly-explosion-collisions.ts).
- [Pinned inspected printed-part implementation](https://github.com/tscircuit/core/blob/0ef57435c535a65d3d49826443b9da70f248b358/lib/components/primitive-components/AssemblyPrintedPart.ts).
- [Pinned inspected mounting props](https://github.com/tscircuit/props/blob/2db8fce73939d910d81ad1a602ad21a9075171dc/lib/assembly/face-mounting.ts).