# Fusible Roadmap & Architecture
Fusible is the electronic linter and hardware–firmware bridge for tscircuit projects. It enforces electrical validity ("blowing the fuse") before firmware codegen or compilation can occur.
## 1. Monorepo Architecture
Projects using Fusible are structured as hardware + firmware monorepos:
```text
my-project/
├── fusible.yml # Unified hardware + firmware manifest
├── hardware/ # tscircuit board and component definitions (.tsx)
│ ├── package.json
│ └── index.tsx # Top-level board entry point
├── firmware/ # Rust (Embassy / Cortex-M) or C/C++ firmware
│ ├── Cargo.toml
│ └── src/
│ ├── main.rs
│ └── pins.rs # Auto-generated by Fusible (fuse intact only)
└── dist/ # Generated artifacts (circuit.json, gerbers, 3d)
```
## 2. `fusible.yml` Specification
A minimal, ergonomic YAML syntax with sensible defaults:
```yaml
name: sensor-node
hardware:
entry: hardware/index.tsx # Entry point (.tsx or circuit.json)
out_dir: dist # Output directory for circuit artifacts
port: 3020 # Dev server port for interactive viewer
mcu:
chip: stm32g431 # Target silicon identifier
firmware:
path: firmware # Directory containing firmware crate
build_cmd: cargo build # Optional build command
```
## 3. CLI Subcommand Suite
Fusible unifies the hardware development workflow by wrapping tscircuit commands:
* `fusible [options]` / `fusible check [file]`: Runs the electrical linter. If target is `.tsx`, evaluates circuit to JSON first. Exits `0` (intact), `1` (fuse blown), or `2` (tool error).
* `fusible dev [file] [--port P]` (aliases: `view`, `webview`): Starts the tscircuit interactive web previewer (`tsci dev` / `@tscircuit/runframe`) with hot reloading.
* `fusible export [file] [-f format] [-o out]`: Wraps `tsci export` to generate Gerbers, SVGs, 3D models (GLB/STEP), or netlists.
* `fusible build`: Compiles `.tsx` to Circuit JSON, validates electrical rules, generates `pins.rs`, and builds firmware.
* `fusible init`: Scaffolds a starter monorepo with `fusible.yml`, `hardware/`, and `firmware/`.
## 4. Implementation Milestones
- [x] **Milestone 1: MVP Core** — Circuit JSON parser, fail-closed electrical linter, miette diagnostics, exit code contract (0: intact, 1: blown, 2: tool error).
- [x] **Milestone 2: Project Manifest (`src/config/`)** — `fusible.yml` schema, auto-discovery, fallback defaults.
- [x] **Milestone 3: tscircuit Runner (`src/tscircuit/`)** — Auto-detection (`tsci`, `bun x tscircuit`, `npx tscircuit`), dev viewer, export presets (`fab`, `cad`, `docs`), build, add, install, search, and doctor.
- [x] **Milestone 4: CLI Subcommands (`src/cli.rs`, `src/main.rs`)** — `dev`, `check`, `export`, `init`, `build`, `add`, `install`, `search`, and `doctor`.
- [x] **Milestone 5: Firmware Pin Binding Codegen (`src/codegen/pins.rs`)** — Extraction of MCU peripheral mappings and typed Rust HAL bindings (`pins.rs`) for firmware monorepos.
- [x] **Milestone 6: Bidirectional EDA Collaboration** — KiCad export (`kicad_project`, `.kicad_pro`, `.kicad_sch`, `.kicad_pcb`), KiCad linter integration, tested end-to-end on `FieldCam`.
- [x] **Milestone 7: Packaging & Release** — Published `fusible v0.3.0` on crates.io with 100% test pass rate and zero clippy warnings.
- [x] **Milestone 8: Pure Rust Fabrication** (`v0.4.0`) — RS-274X Gerber and Excellon drill generator in pure Rust (`<5ms` generation time, zero runner dependencies).
- [x] **Milestone 9: Silicon Pin-Muxing Engine & Alternate Function (AF) Validation** (`v0.5.0`):
- Silicon database for STM32 (AF0–AF15), RP2040 (F1–F9 function select), and ESP32-S3 (boot strapping and reserved flash pins).
- Validation of assigned GPIOs against physical silicon capabilities with alternative pin recommendations.
- Fail-closed fuse contract enforcement (`exit 1`) on AF mismatch, pin collisions, and strapping violations.
- [x] **Milestone 10: Native SVG Documentation Exporter & Advanced Electrical DRC** (`v0.6.0`):
- Pure-Rust vector rendering engine for multi-layer PCB layout (`pcb.svg`) and schematic symbol graphs (`schematic.svg`).
- Decoupling capacitor proximity rule (`decoupling_capacitor`): verifies power supply rails on ICs have bypass capacitors.
- Physical copper clearance rule (`trace_clearance`): detects copper short-circuits and spacing violations (< 0.15mm).
- [x] **Milestone 11: Native Fusible Studio Dev Server & Dark Theme UI** (`v0.7.0`):
- Embedded HTTP server and live-reload event streamer using `tiny_http` and Server-Sent Events (SSE).
- Debounced filesystem watcher (`notify-debouncer-mini`) reacting to code updates in 150ms.
- Standalone dark-theme engineering web dashboard with interactive pan-zoom PCB and schematic layout viewers.
- Live electrical fuse status indicator and miette-style diagnostics inspector.
- [x] **Milestone 12: Parallel Autorouter, Bidirectional KiCad Sync, and 3D Studio** (`v0.8.0`):
- Parallel multi-core topological autorouter (`fusible route`) with `rstar` AABB spatial trees and `rayon` thread pool.
- Multi-layer 3D A* pathfinder supporting 45-degree and 90-degree traces and via transitions.
- Bidirectional KiCad syncer (`fusible diff` and `fusible sync`) with pure Rust S-expression parser and `manual-edits.json` synchronization.
- Vitrine brutalist dark UI redesign and Three.js 3D PCB board previewer embedded in `fusible dev` (`03 // 3D VIEW`).
## 5. Phase 2: Turnkey Automation
- [ ] **Turnkey CI GitHub Action (`fusible-action`)**:
- Automated PR checking in CI to prevent defective hardware or breaking pin drifts from reaching main.