mohan-bee/tscircuit-robot-vacuum

docs/tscircuit-gap-register.md

# Robot vacuum: tscircuit capability and gap register

Audit date: 3 November 2026. Scope: a single custom 160 × 130 mm controller PCB inside a roughly 320 mm robot, plus native printable mechanics. This is a capability stress test and engineering draft. It is not a released vacuum-cleaner design.

The register distinguishes three things: a capability tscircuit has, a capability whose coverage is insufficient for this robot, and engineering work that this project has not completed. Missing project work must not be reported as a platform defect.

## Audited implementation

| Package | Installed version |
| --- | --- |
| `tscircuit` | `0.0.3058` |
| `@tscircuit/core` | `0.0.2254` |
| `@tscircuit/props` | `0.0.716` |
| `@tscircuit/cli` | `0.1.2429` |
| `circuit-json-to-gltf` | `0.0.164` |
| `jscad-fiber` bundled by tscircuit | `0.0.93` |
| `jscad-planner` | `0.0.21` |
| `@tscircuit/jscad` | `0.0.6` |

Use the lockfile to reproduce these versions. Web documentation can lag the installed code: the explosion page still describes collision work as being added, whereas this core package already includes the automatic collision adapter. The observations below prefer inspected and executed code over that stale sentence.

## Demonstrated native workflows

An independent `assembly.device` probe containing one board and a hollow `assembly.printedpart` was rendered with `Circuit.add`, `renderUntilSettled`, and `getCircuitJson`. It emitted a distinct `source_component` with `ftype="printedpart"` and a `cad_component.model_jscad` plan. The following exports succeeded on that native model:

| Probe | Result | What this establishes |
| --- | --- | --- |
| Circuit JSON generation | Passed | Native assembly and JSCAD geometry compile; no imported CAD model required. |
| CLI `--format glb` | Passed | Native printed geometry and the PCB can be exported into a 3D scene. |
| CLI `--format assembly-step` | Passed | Archive contained `SPACER.step`, a 70,533-byte STEP of the native hollow printed part. This option is present in CLI code/help although omitted from the web format table. |
| Project STL format adapter | Passed | `loadCadComponentMesh` produced 296 triangles for the probe; binary STL wrote successfully with zero boundary and nonmanifold edges. Geometry remained native tscircuit. |
| Automatic continuous translation collision probe | Passed | Moving a 10 mm native cube through a second cube, with clear start/end positions, emitted `cad_explosion_collision_error` with 1,000 mm³ newly swept intersection and no incomplete warning. This tests a simple solid pair, not the complete robot. |
| Board collision coverage with a native pinheader | **Reproduced failure** | Bare board and round NPTH controls produced no collision diagnostics; adding a native `pinrow2` header caused an incomplete-check warning excluding the PCB. Details below. |

The probe proves the workflow, not the final robot's fit or fabrication readiness. Final project output and checks must be read from the build report and per-part `dist/printed-parts/manifest.json`.

```sh
# The installed CLI's shebang requests Bun. Calling its JS entry with Node also
# works for the export probes, avoiding an environment-only dependency on Bun.
node node_modules/tscircuit/cli.mjs export dist/circuit.json --format glb -o robot.glb
node node_modules/tscircuit/cli.mjs export dist/circuit.json --format assembly-step -o robot-parts.zip

# The STL adapter only serializes native meshes. It does not author new CAD.
node --import tsx scripts/export-printed-parts.ts dist/circuit.json dist/printed-parts
```

## Capability matrix

Status terminology: **Native** means an implemented platform capability, **Limited** means implemented but incomplete for the stated requirement, **Gap** means no supported workflow was demonstrated in the audited APIs, and **Project work** means a design task that tscircuit can represent but this project has not completed. A gap does not assert that no related experimental repository exists.

| ID | Robot requirement | Status and evidence | Effect on this robot / closure needed |
| --- | --- | --- | --- |
| PCB-01 | One custom four-layer PCB | **Native.** Board API supports 1/2/4/6/8/10 layers; `layers={4}` makes `inner1`/`inner2` available. [S1] | One physical main board is representable. This says nothing about route completion or current capacity. |
| PCB-02 | MCU, H-bridges, passives, custom pads, connectors and named nets | **Native.** Chip, footprint, pad, trace and net APIs. [S2] | Exact MPN pin maps and land patterns still need engineering verification; a generic chip body is not a verified purchased part. |
| PCB-03 | Irregular board, wheel/shaft clearance holes and cutouts | **Native.** Board outline, hole and cutout elements. [S1] | Geometry can be authored, but actual cutout dimensions remain dependent on mechanical parts. |
| PCB-04 | Routing and trace-width control | **Native / project work.** Local autorouting, explicit paths and widths exist. [S1, S3] | The delivered layout must report routing status honestly. `routingDisabled` is a project setting, not evidence that tscircuit cannot route. |
| PCB-05 | Ground and power planes | **Native, with limits.** Explicit pours on inner layers and clearances exist; same-net through-hole thermal reliefs use fixed four 0.3 mm spokes. Automatic pours run after routing and do not reserve planes. [S4] | Use explicit planes and thermal-via design for H-bridges. A pour rendering does not qualify motor-current paths. |
| PCB-06 | Current/voltage/thermal qualification of power copper and motor drivers | **Gap for complete qualification.** Audited PCB rules expose geometry constraints, not a coupled electrothermal model for stall conditions. [S1, S4] | Must supply load/stall currents, copper stack, allowable rise and thermal validation. No native proof demonstrated for the finished robot. |
| PCB-07 | Signal/power design-rule checking | **Native / limited.** CLI check/build DRC categories exist. [S5] | DRC cannot establish correctness of an intentionally absent charger or unknown motor rating; evaluate errors in context. |
| PCB-08 | Gerbers, BOM, pick-and-place export | **Native / project work.** Export pipeline includes them. [S6] | Do not publish them as orderable before schematic, layout and exact part selection are closed. Export availability is not fabrication approval. |
| MECH-01 | Native custom chassis, hollow bin, brackets and ducts | **Native, tested by probe.** `assembly.printedpart` plus JSCAD boolean solids and transforms. [S7, S8] | No external CAD authoring needed for these solids. Hollow geometry can be exported. |
| MECH-02 | Named parts, purchased-part envelopes and subassemblies | **Native.** `assembly.part`, `assembly.subassembly` and custom `cadModel`. [S9] | Simplified purchased envelopes must be labelled as such; they cannot prove connector or shaft fit. |
| MECH-03 | Static mating of motor/bracket/board faces | **Native / limited.** Named reference faces, `mountedTo`, `mountFace` and gaps exist. One PCB anchors a connected chain; PCB mounting needs an XY-parallel target. [S7, S10] | Can align mounts. Does not create screw holes or validate fasteners automatically. General arbitrarily oriented multi-PCB constraints are not needed here. |
| MECH-04 | Separate printable STL files | **Limited.** No `stl` export selector in installed CLI list. Native meshes are accessible with `loadCadComponentMesh`. [S6, S11] | This project supplies a format-only STL adapter. It is a workflow gap, not absence of printable native geometry. STL units and print orientation require explicit handling. |
| MECH-05 | Separate STEP part export | **Native, probe passed.** Installed `assembly-step` dispatches to `circuitJsonToStep(...,{exportMode:"assembly"})`; `step` dispatches to PCB mode. [S6] | Use the assembly option for individual mechanical parts. It is inaccurate to say tscircuit cannot export STEP. |
| MECH-06 | Exploded assembly view and staged disassembly | **Native / limited.** Ordered translation stages and named member references exist. [S12] | Native viewer scrubbing and static GLB pose exports are supported. Stages cannot translate PCB/cable geometry and have no rotation instruction. |
| MECH-07 | Translational collision checking along disassembly path | **Native / limited, simple runtime probe passed.** Current core includes automatic adapter; separate native solver checks continuous rigid triangle-mesh translations. [S13] | Real mesh geometry required. Unsupported/open/failed models produce incomplete warnings; absence of an error is not proof of complete coverage. |
| MECH-07A | Include populated main PCB in collision checking | **Reproduced platform defect in core 0.0.2254.** A native pinheader emits `circular_hole_with_rect_pad`; board collision `drillLoop` does not recognize it and drops the entire PCB substrate from coverage. [S16] | The robot's collision report cannot certify part-to-PCB clearance. Warning is retained; dependency and Circuit JSON were not patched to hide it. |
| MECH-08 | Initial static assembly interference check | **Gap in audited explosion semantics.** Solver deliberately subtracts the starting occupied volume; only newly swept space is checked. [S13] | Pre-existing overlaps can separate without an error. Static assembly fit requires a separate validated inspection; explosion clearance alone cannot certify it. |
| MECH-09 | Wheel revolute joints, suspension travel, caster swivel and brush motion | **Gap in audited assembly/movement APIs.** Static face mating and translations do not define revolute/prismatic joints or multibody dynamics. Rotations are explicitly outside explosion solver coverage. [S10, S12, S13] | Motors/wheels can be placed and modelled. No validated native motion/terrain-contact simulation was demonstrated. |
| MECH-10 | FDM fit, shrinkage, anisotropic strength, spring stiffness, snap-fit life | **Gap for qualification.** No tolerance/FEA/material-process workflow demonstrated by audited printed-part APIs. [S7] | Numeric hole/wall clearances can be authored manually; load-bearing and repeated-service performance remain unverified. |
| MECH-11 | Slicing, support structures, print-bed nesting and G-code | **Gap in audited CLI.** Export formats contain CAD/mesh delivery, not a printer slicer. [S6] | Exported prototype parts still need print preparation. Native shape generation does not make a 320 mm shell fit a smaller printer bed. |
| MECH-12 | Engineering drawings | **Native / project work.** Assembly drawing pages, views, dimensions and title blocks exist. [S14] | Need completed part drawings and tolerances for a released assembly. Do not list drawing support as absent. |
| HARNESS-01 | Cables between supported endpoints | **Native / limited.** Native cable geometry supports connector selection and inferred USB/JST variants. [S15] | Cable rendering does not create electrical connections or pin mapping. Electrical netlist remains separate. |
| HARNESS-02 | Collision-free harness route, controlled length, bend radius, sag and service loop | **Gap / limited.** Cable docs explicitly say no obstacle avoidance, gravity sag, length or route-hint props. [S15] | Can't qualify long wheel/sensor leads through ducts and around suspension using inferred arch alone. Routing and lengths need a documented manual process or future API. |
| SYSTEM-01 | Pressure drop, suction, filter loading, dust separation, noise | **Gap for qualification.** No CFD/acoustic solver demonstrated in audited assembly APIs. | Ducts/bin geometry are representable; cleaning performance is not established. Physical airflow tests remain necessary engineering work. |
| SYSTEM-02 | High-speed blower balancing and impeller safety | **Purchased hardware constraint / project work.** No native design qualification demonstrated. | Use a manufactured balanced blower with integrated driver. Do not turn a visual cylinder into a validated printed impeller. |
| SYSTEM-03 | ESP firmware, SLAM, mapping and Wi-Fi/app behavior | **Outside PCB/assembly authoring; project work.** A PCB description is not deployed embedded firmware. | Pin allocation can be documented in tscircuit; navigation and safety firmware need implementation and hardware tests. |
| SYSTEM-04 | Safe 3S charger, pack protection, balancing and battery qualification | **Project work.** tscircuit can represent the ICs; selecting/validating a complete reference design is not automatic. | A BQ25798 package or charging connector alone is not a complete charger; per-cell protection remains separate. |
| SYSTEM-05 | Docking contacts, alignment, communications and charging sequence | **Project work / later revision.** Static geometry and electrical models can be authored. | Mechanical dock mockup does not establish automatic docking or a working charging system. |
| SYSTEM-06 | Water/dust sealing, EMC, transport and appliance certification | **Qualification gap, not a rendering feature.** No complete end-product certification workflow demonstrated. | Enclosure drawing and source compile do not establish these results. |

## Reproduced defect: native header excludes PCB from collision coverage

This is a platform defect observed using native output, independent of the robot's custom IC footprints.

Run `node --import tsx capability-audit/board-hole-collision-probe.tsx`. The probe builds three otherwise identical 20 × 20 mm boards and moves a printed cover upward, away from the PCB. Complete results are in `capability-audit/board-hole-collision-results.json`.

| Control / reproduction | Hole emitted in Circuit JSON | Observed collision diagnostics |
| --- | --- | --- |
| Bare board | None | None |
| Board with one 3.2 mm round NPTH | `hole_shape: "circle"` | None |
| Board with native `<pinheader pinCount={2} footprint="pinrow2" />` | Pin 1: `shape: "circular_hole_with_rect_pad"`, `hole_diameter: 1`, rectangular copper pad 1.5 × 1.5 mm; pin 2: `shape: "circle"` | `cad_explosion_collision_check_warning`, `reason: "unsupported_geometry"`, `pcb_board_ids: ["pcb_board_0"]` |

The warning message is: `Explosion collision checking is incomplete: unsupported geometry for "PCB"`.

Minimal failing structure:

```tsx
import { assembly, jscad } from "tscircuit"

export default () => (
  <assembly.device name="hole-check">
    <board name="B" width={20} height={20} routingDisabled>
      <pinheader name="J1" pinCount={2} footprint="pinrow2" />
    </board>
    <assembly.printedpart name="COVER"
      jscad={<jscad.cuboid size={[18, 18, 2]} center={[0, 0, 10]} />} />
    <assembly.explosion.stage name="lift">
      <assembly.explosion.move targetRefs="COVER" offZ={10} />
    </assembly.explosion.stage>
  </assembly.device>
)
```

Root cause verified in both installed code and the current primary source [S16]: `drillLoop` recognizes `circle`, `oval`, `rect`, `square`, `pill` and `rotated_pill`. It receives the compound pad/hole shape `circular_hole_with_rect_pad`, returns `undefined`, and `createBoardCollisionSolid` then returns `undefined` for the whole board. The rectangular copper pad does not change the physical circular drill; the adapter should derive the drill profile from the compound shape's hole dimensions. Similar compound shapes need explicit coverage tests rather than a one-string special case.

Suggested acceptance test: the native `pinrow2` probe above retains PCB collision coverage, still subtracts both 1 mm circular drill holes, and reports a part swept through the board substrate as a collision. Other compound plated-hole shapes, offsets and rotations should have regression fixtures. A bare-board fallback would conceal drills and would not close the defect.

No patch was made to tscircuit dependencies, the probe output or the robot warning. No upstream issue was posted.

## Observed schematic scaling limit and native workaround

During integration, putting the entire draft netlist on a flat schematic remained in `SchematicTraceRender` and was stopped after approximately 66 seconds. Dividing the same design into eight native schematic sheets allowed the build to complete. This is one observed project run, not a benchmark, and does not establish a universal capacity limit or a reproducible solver defect by itself. The delivered project uses those native sheets; no alternate schematic engine was substituted. Future regression work should retain the flat input, collect solver progress/timings, and compare it with the eight-sheet input under the same package versions.

## Design work that must not be blamed on tscircuit

### Additional measured robot results

The final populated assembly uses 79 PCB component records, 63 named nets, eight schematic sheets, 15 printed parts, and three explosion stages. Its build retains the reproduced PCB collision coverage warning rather than substituting a bare-board model. The final exact diagnostic counts and release boundaries are in `build-report.md`.

Native four-layer routing was also executed on a separate copy of this electrical design. The default preflight declined to start with more than 50 remaining traces; setting the supported `routeRemaining=true` option allowed the native solver to complete in 20.335 seconds. It produced 213 PCB traces and 173 vias, used all four copper layers, and reported no unconnected-port errors. This establishes routing capability. Every resulting wire segment was 0.15 mm wide, so the experiment does not qualify power distribution. See `../capability-audit/routing-forced-summary.json` and the runnable probe. The final review layout remains deliberately unrouted.

The STL adapter exposed a native tessellation robustness problem on this robot: the original chassis produced 6 nonmanifold edges, 1 inconsistent edge and 5 degenerate triangles; the caster cup produced 4, 2 and 4 respectively. There were no boundary edges, so checking only for open surfaces would miss the defects. A native authoring workaround rotates the cylinder facet seam by 0.017 radians before translating it. All 15 final parts then pass all four mesh diagnostics. No external CAD or mesh repair was used. This is a demonstrated numerical robustness limitation with an available native workaround; it does not prove that every similar CSG operation fails. See `mechanical-capability-audit.md` for measured coordinates and the `StableCylinder` implementation.

The embedded ChatGPT PCB viewer service returned internal errors on two attempts to display the complete source. The same source compiled and exported through the pinned local tscircuit runtime. Record this as an integration failure in this session, not evidence that the tscircuit engine cannot render the robot. Native TSX, GLB scenes and preview images are included.

The initial robot's missing BQ25798 support circuitry, 5 V/3.3 V converters, completed motor/charger ratings, verified connector MPNs, route closure, thermal vias, all fasteners, seals, brush bristles, wheels/treads, suspension springs, firmware, sensor calibration, suction testing and automatic docking are engineering tasks. Most physical shapes and schematic elements can already be authored. Their absence from an initial draft is not evidence of a platform limitation.

The one-custom-PCB target permits purchased assemblies containing their own electronics: ESP32 module, LiDAR module, encoder motors, protected pack and integrated BLDC driver. If “one PCB” instead means no circuit boards inside any purchased assembly, this architecture does not meet that stricter interpretation.

## Recommended platform work, in priority order

| Priority | Deliverable | Acceptance test on this robot |
| --- | --- | --- |
| P0 | Fix compound plated-hole collision parsing | Native pinrow2 and common square-pad connectors preserve PCB collision coverage without editing Circuit JSON or replacing the populated board. |
| P0 | Robust native CSG tessellation and mesh diagnostics | Original chassis/caster booleans produce closed, consistently oriented meshes without degenerate triangles or seam-phase workarounds. |
| P0 | Fix compound plated-hole support in board collision geometry | Native `pinrow2` headers no longer exclude the board; real circular drills remain subtracted and a substrate-crossing motion is detected. |
| P0 | First-class per-part STL/3MF export with unit/orientation metadata | One command exports only printable parts, retains stable identities, and reports open/nonmanifold geometry without hiding failures. |
| P0 | Static interference report plus explicit per-model check coverage | Reports board-to-standoff, battery-to-bin and wheel-to-chassis interferences at the assembled pose, with exclusions and unsupported meshes listed. |
| P1 | Rotary/prismatic joints and rotation-sweep checking | Wheel/suspension envelope, caster swivel and bin latch can be evaluated over declared ranges; report start/finish and swept collisions separately. |
| P1 | Harness route constraints with wire/pin mapping | All power, sensor and motor wires have bend radii, measured lengths, service loops and matching endpoint pins; paths avoid solids. |
| P1 | Manufacturing-fit metadata and tolerance reporting | M3 hole-to-post alignment, motor shaft/hub fits and bin seal dimensions carry nominal/tolerance values with a stack-up report. |
| P2 | Integrated print preparation and material/strength analysis hooks | A 320 mm chassis can be split/nested with documented joint features and printable orientations; validation status remains explicit. |
| P2 | Export parity checks | PCB, interactive viewer, GLB, per-part STEP and STL show the same origin, scale, cutouts and assembly pose. |

## Primary sources

- **S1** [Board API: layers, widths, outline, autorouting and automatic pours](https://docs.tscircuit.com/elements/board)
- **S2** [Chip API](https://docs.tscircuit.com/elements/chip) and [footprint API](https://docs.tscircuit.com/elements/footprint)
- **S3** [Trace API: manual paths and thickness](https://docs.tscircuit.com/elements/trace)
- **S4** [Copper pour API and thermal relief limits](https://docs.tscircuit.com/elements/copperpour)
- **S5** [Build DRC options](https://docs.tscircuit.com/command-line/tsci-build) and [check command](https://docs.tscircuit.com/command-line/tsci-check)
- **S6** [CLI export implementation and exact format dispatch](https://github.com/tscircuit/cli/blob/main/lib/shared/export-snippet.ts), [CLI registration](https://github.com/tscircuit/cli/blob/main/cli/export/register.ts), and [export docs](https://docs.tscircuit.com/command-line/tsci-export)
- **S7** [Printed-part API, reference faces and limits](https://docs.tscircuit.com/elements/assembly-printedpart)
- **S8** [jscad-fiber native React/JSCAD implementation](https://github.com/tscircuit/jscad-fiber)
- **S9** [Part API](https://docs.tscircuit.com/elements/assembly-part) and [subassembly API](https://docs.tscircuit.com/elements/assembly-subassembly)
- **S10** [Advanced assembly: static mounting and limitations](https://docs.tscircuit.com/guides/advanced-assembly)
- **S11** [Native mesh loading API and coordinate semantics](https://github.com/tscircuit/circuit-json-to-gltf#cad-geometry-for-physics-and-solid-checks)
- **S12** [Explosion stages, viewer use and rotation/target restrictions](https://docs.tscircuit.com/elements/assembly-explosion-stage)
- **S13** [cad-collision-checking: supported geometry, continuous translations, initial-overlap semantics and limits](https://github.com/tscircuit/cad-collision-checking/blob/main/README.md). Installed core adapter: `node_modules/@tscircuit/core/dist/chunk-VWT4VTBG.js` and final-render integration in `node_modules/@tscircuit/core/dist/index.js`.
- **S14** [Drawing page API](https://docs.tscircuit.com/elements/assembly-drawing-page)
- **S15** [Cable API: no obstacle avoidance, sag, length or route-hint props](https://docs.tscircuit.com/elements/assembly-cable)
- **S16** [Core board collision geometry: `drillLoop` and `createBoardCollisionSolid`](https://github.com/tscircuit/core/blob/main/lib/assembly-explosion/collision/create-board-collision-solid.ts), verified against installed `@tscircuit/core@0.0.2254` and the included three-case native probe.

No upstream issues or pull requests were created by this audit.