PCB Stage (tscircuit)

PCBs are authored as React/TSX code and compiled to circuit JSON, then exported to fabrication files. The tsci binary lives at <repo>/node_modules/.bin/tsci.

Workflow

1. Prerequisite: product/bom.json exists with bom_ready: true. Every populated BOM row must map to a component in the circuit source.
2. Scaffold once per project: create pcb/index.circuit.tsx (see references/tscircuit-basics.md for syntax) — do not invent JSX props; stick to documented elements: <board>, <chip>, <resistor>, <capacitor>, <led>, <pinheader>, <trace>, etc.
3. Import real JLC parts instead of hand-writing footprints when possible:

cd <project>/pcb && <repo>/node_modules/.bin/tsci add C2913202   # imports part by LCSC code

4. Build = DRC gate. A clean build is the equivalent of Replicator's pcb.run(profile="check"):

cd <project>/pcb && <repo>/node_modules/.bin/tsci build          # emits circuit.json, fails on errors

Read the error output; fix source until the build is clean.

5. Visual check: tsci export index.circuit.tsx -f pcb-svg (and -f schematic-svg) then convert or open the SVG; inspect the board image before release.
6. Release = export the fabrication package into a numbered folder:

mkdir -p releases/1 && cd <project>/pcb
<repo>/node_modules/.bin/tsci export index.circuit.tsx -f gerbers -o releases/1/gerbers.zip
<repo>/node_modules/.bin/tsci export index.circuit.tsx -f readable-netlist -o releases/1/netlist.txt

Also generate JLC assembly files when SMT assembly is intended (BOM csv from product/bom.json designators; CPL from circuit JSON placements).

7. A release is only "published" when: build clean + Gerbers exported + BOM/CPL consistent with product/bom.json. Record the release in releases/<n>/README.md with date and source git hash.
8. After a release, if enclosure CAD already exists, check whether the PCB change affects it (outline, mounting holes, connector positions/heights). Report specifics ("USB-C moved 1.2mm right"), not "PCB changed".

References

• Load the vendored upstream tscircuit skill (MIT, by tscircuit) for authoritative syntax, workflow, and checklists: SYNTAX.md, WORKFLOW.md, CHECKLIST.md, CLI.md, and per-element docs under elements/.
• references/tscircuit-basics.md - quick cheat sheet for common patterns.
• Deep PCB know-how (vendored verbatim originals) at <repo>/reference/replicator-original/project-replicator/pcb/references/:
  • footprints.md - CRITICAL: footprint chirality rules (never transcribe bottom-side coordinates - tscircuit x-negates on bottom placement, double-mirror scrambles pins invisibly to DRC), Pin-1/origin/rotation conventions, JLC CPL rotation corrections, footprint source decision order.
  • built-in-elements.md - element gotchas (net names can't start with digits, via geometry, keepout limits).
  • pcb-config.md - manufacturing numbers: trace 0.30mm nominal / 0.25mm min signal, via 0.6/0.3mm default, net class schemas, copper weight rules.
• <repo>/seeds/hardware-profiles.json - per-board pin capability maps (gpio/pwm/i2c/uart per pin). Use these instead of guessing MCU pinouts.
• Before claiming a release order-ready, run the review criteria in <repo>/reference/replicator-original/me/pcb-release-review/SKILL.md (P0 = board wrong if fabricated: connectivity, part identity, footprint mismatch, missing opening, reversed connector).
• references/cpl-rotation-checklist.md - manual CPL rotation verification before paying for JLC PCBA.
• Upstream docs: https://docs.tscircuit.com

Measurement & gates (scripts/)

Run with any python3 (stdlib only), from the skill's scripts/ dir:

• pcb_measure.py <circuit.json> [--report board|components|drills|routing|gaps|all] - physical facts from the built board (open pcb.measure): board dims/layers, per-component side+rotation+pads, drill table, per-net trace widths and vias, smallest differently-netted pad gaps. Generate input with npx tsci export -f circuit-json <entry>.circuit.tsx. Use it to verify claims instead of eyeballing footprint source.
• release.py <pcb_dir> --artifacts <files...> - content-addressed release gate: hashes editable source, refuses a release content-identical to an existing one, writes releases/<n>/manifest.json with source + artifact sha256. --check prints status.
• kicad_drc.py <entry>.circuit.tsx - independent second-opinion DRC: exports .kicad_pcb via tsci, runs kicad-cli pcb drc. Degrades gracefully (exit 2 + instructions) when KiCad is not installed (brew install --cask kicad).

Bulk autorouting with Freerouting (scripts/freeroute.mjs)

The open equivalent of Replicator's managed pcb-toolchain runtime (Temurin JRE + Freerouting jar, installed by install.sh into <repo>/runtime/pcb-toolchain/). Use when tscircuit's built-in autorouter fails, leaves nets unrouted, or violates clearance:

npx tsci export -f circuit-json <entry>.circuit.tsx   # or tsci build
node <repo>/skills/replicator-pcb/scripts/freeroute.mjs dist/.../circuit.json \
  --passes 20 --out routed.circuit.json

Chain: circuit JSON → Specctra DSN (dsn-converter) → Freerouting headless (-de/-do, exits when done) → SES → routed pcb_trace/pcb_via merged back → routed circuit JSON + SVG preview.

Rules learned from the original: Freerouting owns the complete copper layer — existing routes are stripped before the DSN export (leaving them in trips Freerouting 2.x's parser: "padstack name expected"). Run pcb_measure.py and kicad_drc.py on the routed output before releasing; Freerouting optimizes completion, not your process floor.