# Fase 8 — Plan de Implementación en Velxio

> **Destino**: el código Velxio (`frontend/`). El sandbox `test/test_circuit/` queda como referencia y banco de pruebas congelado.
> **Motor**: `eecircuit-engine` (ngspice-WASM real). **No** se inventa solver.
> **Meta**: Velxio emula **circuitos digitales + analógicos conviviendo**, con sketches reales de Arduino/ESP32 interactuando con componentes discretos (resistencias, capacitores, transistores, op-amps, sensores, MOSFETs) y con instrumentos de medición (voltímetro, amperímetro, multímetro, osciloscopio analógico).

---

## 0. Resumen ejecutivo

| | |
|---|---|
| **Motor de simulación eléctrica** | `eecircuit-engine@^1.7.0` (ngspice compilado a WASM, 39 MB) |
| **Estrategia de carga** | Lazy-load tras toggle "⚡ Electrical" en la toolbar |
| **Integración con MCU** | Co-simulación cuasi-estática: AVR/RP2040/ESP32 corre `N` ciclos, luego ngspice resuelve el netlist en `.op` o `.tran`; voltajes de nodos se inyectan en ADC; duty de PWM se traduce a fuente DC |
| **Componentes nuevos (primera oleada)** | ≈ 30: pasivos genéricos, transistores reales (2N2222, 2N3055, BC547, TIP120), MOSFETs (2N7000, IRF540), op-amps (LM358, LM741, TL072, LM324), reguladores (78xx, LM317), Zener (1N4733), referencias (TL431), 555, puente rectificador, etc. |
| **Instrumentos** | Voltímetro, amperímetro, multímetro DMM, probe de osciloscopio analógico (extiende el osciloscopio actual) |
| **Modo "Electrical"** | Tres niveles: `off` (comportamiento actual), `spice` (ngspice-WASM — predeterminado del modo), `mna-fallback` (solver hand-rolled del sandbox) — reservado para entornos sin WASM |
| **Plazo estimado** | 5 fases de 1–2 semanas cada una (ver §6). No bloquea el resto del roadmap: el feature flag permite merge seguro incremental |
| **Validación** | Portar los **47 tests** del sandbox al `frontend/src/__tests__/` |

---

## 1. Fuentes de verdad (leer antes de empezar)

Este plan **depende** de que el implementador haya leído:

- [`test/test_circuit/src/spice/SpiceEngine.js`](../src/spice/SpiceEngine.js) — wrapper de `eecircuit-engine`. A portar tal cual a `frontend/src/simulation/spice/`.
- [`test/test_circuit/src/spice/AVRSpiceBridge.js`](../src/spice/AVRSpiceBridge.js) — puente cuasi-estático. Es el patrón exacto.
- [`test/test_circuit/autosearch/04_ngspice_findings.md`](../autosearch/04_ngspice_findings.md) — trampas de ngspice ya identificadas (`&` vs `u()`, matriz singular, histéresis para memoria, etc.).
- [`docs/wiki/circuit-emulation-gotchas.md`](../../../docs/wiki/circuit-emulation-gotchas.md) — debugging log completo.
- [`docs/wiki/circuit-emulation-avr-bridge.md`](../../../docs/wiki/circuit-emulation-avr-bridge.md) — mapeo pin → puerto → ngspice.
- El informe de survey de Velxio (ver el mensaje previo del agente Explore): **componentes son metadata-driven** con `components-metadata.json` generado en build; los **cables son visuales** (sin nodos); la **API de pines** está en `PinManager.onPinChange / onPwmChange / onAnalogChange`.

Si alguno de estos ha cambiado sustancialmente cuando se empiece la fase 1, parar y replantear.

---

## 2. Arquitectura objetivo

### 2.1 Diagrama de alto nivel

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                               Velxio UI                                     │
│                                                                             │
│  ComponentPicker  Canvas  Toolbar       PropertyDialog  Oscilloscope        │
│       │             │        │               │              │               │
│       └─────────────┴────────┴───────────────┴──────────────┘               │
│                              │                                              │
│                              ▼                                              │
│                  ┌──────────────────────┐                                   │
│                  │  useSimulatorStore   │                                   │
│                  │   components[]       │                                   │
│                  │   wires[]            │                                   │
│                  │   electrical: {      │                                   │
│                  │     mode,            │                                   │
│                  │     nodeVoltages,    │                                   │
│                  │     componentI,      │                                   │
│                  │     probes[]         │                                   │
│                  │   }                  │                                   │
│                  └──────┬───────────────┘                                   │
│                         │ subscribe                                         │
│                         ▼                                                   │
│                  ┌──────────────────────┐                                   │
│                  │ ElectricalScheduler  │  debounce 50 ms                   │
│                  │  (singleton)         │  runs on wire / pin / prop change │
│                  └──────┬───────────────┘                                   │
│                         │                                                   │
│      ┌──────────────────┼──────────────────┐                                │
│      ▼                  ▼                  ▼                                │
│ ┌──────────┐   ┌──────────────┐   ┌──────────────┐                          │
│ │ Netlist  │   │  AVR/ESP     │   │ Instrument   │                          │
│ │ Builder  │   │  pin snapshot│   │ reader       │                          │
│ └────┬─────┘   └──────┬───────┘   └──────┬───────┘                          │
│      │                │                  │                                  │
│      └────────┬───────┴──────────────────┘                                  │
│               ▼                                                             │
│       ┌─────────────────────────┐                                           │
│       │  SpiceEngine (lazy)     │   if mode === 'spice'                     │
│       │  eecircuit-engine (WASM)│                                           │
│       │                         │   if mode === 'mna-fallback'              │
│       │  CircuitSolverJS        │   (hand-rolled, from sandbox)             │
│       └──────────┬──────────────┘                                           │
│                  │                                                          │
│                  ▼                                                          │
│     { nodeVoltages, branchCurrents, converged, errors }                     │
│                  │                                                          │
│                  └─► update store.electrical                                │
│                  └─► inject ADC voltages via PinManager.setAnalogVoltage    │
│                  └─► update LED brightness on each LED DynamicComponent     │
│                  └─► feed probes (voltmeter, ammeter, scope)                │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 2.2 Decisiones clave (no negociables)

| # | Decisión | Razón |
|---|---|---|
| D-1 | Usar `eecircuit-engine` SIEMPRE que `mode === 'spice'` | El sandbox validó que funciona; no inventar |
| D-2 | Lazy-load del paquete (~39 MB) detrás del toggle | No penalizar tiempo de carga inicial |
| D-3 | Scheduler con debounce 50 ms | Evitar re-solver por cada frame; user-perception: instantáneo |
| D-4 | Co-simulación cuasi-estática (slice 1–10 ms) | Cycle-accurate es imposible; el sandbox probó que 1 ms alcanza para ADC + PWM |
| D-5 | Cables siguen siendo visuales; un **NetlistBuilder** hace Union-Find al vuelo | Reutiliza el modelo de datos actual de Velxio; zero-risk |
| D-6 | PWM se representa como fuente DC de `duty·Vcc` en modo `.op` | El sandbox mostró < 100 mV de error en filtros RC con esta simplificación |
| D-7 | Componentes sin modelo eléctrico (LCD, NeoPixel, sensores I²C) se **omiten** del netlist | Siguen funcionando con su lógica actual |
| D-8 | Instrumentos (voltímetro, amperímetro) son componentes Velxio normales con flag `isProbe=true` | NO se estampan en el netlist — son lectores de resultados |
| D-9 | Modo por defecto: `off`. Activar con toggle explícito | Usuarios que no necesitan analógico no ven diferencia |
| D-10 | Cada board Velxio (Uno, Mega, ESP32, RP2040) expone sus pines como nets nombrados `boardid_pin<N>` | Evita colisiones entre múltiples boards |

---

## 3. Estructura de archivos nuevos / modificados en `frontend/`

### 3.1 Archivos nuevos

```
frontend/src/simulation/spice/
├── SpiceEngine.ts                  ★ wrapper de eecircuit-engine (port del sandbox)
├── SpiceEngine.lazy.ts             ★ dynamic-import wrapper, singleton
├── NetlistBuilder.ts               ★ wires[] + components[] → netlist string
├── NetlistBuilder.unionFind.ts     ★ auxiliar
├── componentToSpice.ts             ★ tabla metadataId → spice card
├── subcircuits.ts                  ★ .subckt de op-amps, 555, etc.
├── CircuitScheduler.ts             ★ debouncer, orchestrator
├── AVRSpiceBridge.ts               ★ co-sim AVR ↔ ngspice (port del sandbox)
├── RP2040SpiceBridge.ts            ★ análogo para RP2040
├── ESP32SpiceBridge.ts             ★ análogo para ESP32 (según disponibilidad de ADC)
└── CircuitSolverJS.ts              ★ port del solver hand-rolled como fallback

frontend/src/simulation/spice/__tests__/
├── netlistBuilder.test.ts
├── componentToSpice.test.ts
├── avr-ntc-readback.test.ts        ← port directo del sandbox
├── avr-pwm-rc.test.ts              ← port
├── avr-pot-cosim.test.ts           ← port
└── (… el resto de los 47 del sandbox …)

frontend/src/components/components-analog/
├── GenericResistor.tsx             ★ cualquier valor en Ω
├── GenericCapacitor.tsx            ★ cualquier valor en F, con polaridad opcional
├── GenericInductor.tsx             ★
├── GenericDiode.tsx                ★ modelo genérico, dropdown de partes 1N4148/1N4007/1N5819
├── ZenerDiode.tsx                  ★ dropdown 1N4733/1N4742/etc. o voltaje custom
├── BJTTransistor.tsx               ★ NPN/PNP + part number (2N2222/2N3055/BC547/BC557/TIP120)
├── MOSFETTransistor.tsx            ★ N/P + parte (IRF540/IRF9540/2N7000/BS170)
├── OpAmp.tsx                       ★ LM358/LM741/TL072/LM324 (package-pin-aware)
├── VoltageRegulator.tsx            ★ 7805/7812/LM317 + externals
├── Timer555.tsx                    ★ chip NE555 en DIP-8
├── BridgeRectifier.tsx             ★ puente de 4 diodos
└── GenericSwitch.tsx               ★ SPST / SPDT / DPDT

frontend/src/components/components-instruments/
├── Voltmeter.tsx                   ★ DC: lee V(node+) − V(node−); probe de 2 terminales
├── Ammeter.tsx                     ★ DC: inserta 0.001 Ω en serie y lee i(Vsense)
├── Multimeter.tsx                  ★ DMM: V/I/R/diode/continuity
├── OscilloscopeAnalogProbe.tsx     ★ señala un nodo ngspice como canal del scope
└── SignalGenerator.tsx             ★ fuente V controlada desde UI (sin, pulse, pwl)

frontend/src/components/analog-ui/
├── ComponentValueEditor.tsx        ★ input con unidades (k, M, u, n, p)
├── ElectricalOverlay.tsx           ★ SVG overlay: V de cada nodo, I de cada cable
├── ElectricalModeToggle.tsx        ★ toolbar button ⚡
├── SpiceErrorBanner.tsx            ★ banner de no-convergencia
└── MeasurementPanel.tsx            ★ lateral con todas las lecturas de probes

frontend/scripts/
└── generate-analog-metadata.ts     ★ genera components-metadata.json para analog/instruments
```

### 3.2 Archivos modificados

| Archivo | Cambio |
|---|---|
| `frontend/package.json` | + `"eecircuit-engine": "^1.7.0"` (como `dependencies`, marca de side-effect false para tree-shaking) |
| `frontend/src/store/useSimulatorStore.ts` | + estado `electrical`, + acciones `runElectricalSolve`, `setElectricalMode`, `addProbe` |
| `frontend/src/simulation/PinManager.ts` | + método `onAnyPinChange(cb)` — fires cuando cualquier pin (cualquier board) cambia; fires también en PWM update |
| `frontend/src/simulation/AVRSimulator.ts` | + invocar `PinManager.notifyAnyPinChange()` dentro del callback existente |
| `frontend/src/components/editor/EditorToolbar.tsx` | + botón `<ElectricalModeToggle />` |
| `frontend/src/components/simulator/SimulatorCanvas.tsx` | + `<ElectricalOverlay />` encima del WireLayer; + render de instrumentos |
| `frontend/src/components/DynamicComponent.tsx` | + leer `brightness` real de electrical.componentCurrents para LEDs |
| `frontend/src/components/ComponentPickerModal.tsx` | + nuevas categorías `analog-passive`, `analog-active`, `instruments` |
| `frontend/vite.config.ts` | si hace falta, marcar `eecircuit-engine` como `optimizeDeps.exclude` para que no bloquee dev server |
| `frontend/components-metadata.json` | regenerado — ahora incluye los ~30 nuevos analog components + 5 instrumentos |

---

## 4. Catálogo de componentes (primera oleada)

### 4.1 Pasivos genéricos

| Velxio `metadataId` | Tag web component | Propiedades | Netlist ngspice |
|---|---|---|---|
| `analog-resistor` | `<wokwi-resistor>` (existente) | `value` (Ω), `tolerance` (%) | `R{id} {net1} {net2} {value}` |
| `analog-capacitor` | `<wokwi-capacitor>` o propio | `value` (F), `polarized` (bool), `voltage` (max V) | `C{id} {net+} {net-} {value} IC=0` |
| `analog-electrolytic` | nuevo SVG | igual, siempre polarized=true | idem |
| `analog-inductor` | nuevo SVG | `value` (H), `dcr` (Ω) | `L{id} {n1} {n2} {value}` + `R_{id}_dcr` en serie si `dcr > 0` |
| `analog-potentiometer-generic` | extiende `Potentiometer.tsx` existente | `value` (Ω total), `curve` ("linear"\|"log"), `wiperPos` | dos resistores en serie |
| `analog-trimmer` | SVG nuevo | igual; UI distinta (tornillo chico) | idem |

**Input de valor con prefijos SI** — `ComponentValueEditor.tsx`:

```
"4.7k"   → 4700
"220"    → 220
"1Meg"   → 1_000_000
"10u"    → 0.00001  (capacitor)
"100n"   → 1e-7
"0.1u"   → 1e-7     (alias)
"22p"    → 2.2e-11
"10mH"   → 0.01     (inductor)
"1.5H"   → 1.5
```

Usar la misma sintaxis SPICE (`k`, `Meg`, `u`, `n`, `p`, `m`, `f`, `G`, `T`) para que el usuario aprenda de una vez.

### 4.2 Semiconductores discretos (reales, con part number)

| `metadataId` | Parte | SPICE model card |
|---|---|---|
| `diode-1n4148` | 1N4148 small-signal | `.model D1N4148 D(Is=2.52n N=1.752 Rs=0.568 Ibv=0.1u Bv=100 Cjo=4p M=0.333 Vj=0.5)` |
| `diode-1n4007` | 1N4007 rectifier | `.model D1N4007 D(Is=76.9n N=1.45 Rs=0.0342 Ikf=2.34 Bv=1000 Ibv=5u)` |
| `diode-1n5819` | Schottky | `.model D1N5819 D(Is=31u N=1 Rs=0.043 Bv=40 Ibv=10m Cjo=110p)` |
| `zener-1n4733` | 5.1 V zener | `.model D1N4733 D(Is=1n N=1 Rs=5 Bv=5.1 Ibv=50m)` |
| `zener-1n4742` | 12 V zener | `.model D1N4742 D(Is=1n N=1 Rs=6 Bv=12 Ibv=20m)` |
| `bjt-2n2222` | NPN general purpose | `.model Q2N2222 NPN(Is=14.34f Xti=3 Eg=1.11 Vaf=74.03 Bf=200 Ne=1.307 Ise=14.34f Ikf=0.2847 Xtb=1.5 Br=6.092 Nc=2 Isc=0 Ikr=0 Rc=1 Cjc=7.306p Mjc=0.3416 Vjc=0.75 Fc=0.5 Cje=22.01p Mje=0.377 Vje=0.75 Tr=46.91n Tf=411.1p Itf=0.6 Vtf=1.7 Xtf=3 Rb=10)` (estándar Motorola) |
| `bjt-2n3055` | NPN power | modelo Motorola estándar (`Bf=70`, `Icmax=15 A`) |
| `bjt-bc547` | NPN small-signal Europa | `.model QBC547B NPN(Is=7.049f Bf=378.6 Ikf=0.1393 Vaf=85 Br=7.202 Ne=1.25 Ise=92.22p Ikr=0.3 Rc=1.32 Cjc=6.033p Cje=8.063p Tf=575.8p Tr=1.0u Mje=0.3 Mjc=0.3 Vje=0.69 Vjc=0.69 Rb=10)` |
| `bjt-bc557` | PNP | `.model QBC557B PNP(…)` |
| `bjt-tip120` | NPN Darlington power | `.model QTIP120 NPN(Bf=1000 …)` |
| `mosfet-2n7000` | N-ch small-signal | `.model M2N7000 NMOS(Level=3 Vto=1.6 Kp=0.1 L=2u W=0.1 Rd=1 Rs=0.5)` |
| `mosfet-bs170` | N-ch TO-92 | similar |
| `mosfet-irf540` | N-ch power | `.model MIRF540 NMOS(Level=3 Vto=3.0 Kp=20 L=2u W=1 Rd=0.044 Rs=0)` |
| `mosfet-irf9540` | P-ch power | `.model MIRF9540 PMOS(Level=3 Vto=-3 Kp=15 …)` |

> **Fuente de los parámetros**: se copiarán de las librerías SPICE estándar distribuidas con LTspice/Orcad (dominio público por práctica de la industria, los fabricantes los publican). Los modelos viven en `subcircuits.ts` como strings constantes. Un test (`modelCompiles.test.ts`) verifica que cada `.model` line se parsee sin errores.

### 4.3 Integrados analógicos (subcircuitos)

| `metadataId` | Parte | Implementación |
|---|---|---|
| `opamp-lm358` | LM358 (dual, single-supply) | `.subckt LM358 inv non_inv VEE OUT VCC` — macromodelo con slew-rate, GBW=1MHz, CMRR, etc. |
| `opamp-lm741` | LM741 single | `.subckt LM741 …` |
| `opamp-tl072` | TL072 JFET-input | `.subckt TL072 …` |
| `opamp-lm324` | LM324 quad | `.subckt LM324 …` |
| `reg-7805` | LM7805 +5V regulator | `.subckt LM7805 Vin Vout GND` |
| `reg-7812` | LM7812 +12V | `.subckt LM7812 Vin Vout GND` |
| `reg-lm317` | Adjustable | `.subckt LM317 Vin Vout ADJ` |
| `ref-tl431` | 2.5V shunt reference | `.subckt TL431 cathode anode ref` |
| `timer-555` | NE555 bipolar | `.subckt NE555 GND TRIG OUT RESET CTRL THR DIS VCC` |
| `bridge-rect` | DF04 bridge rectifier | 4× `D1N4007` estampados juntos |

**Fuente de los `.subckt`**: igualmente dominio público; los que existen en manuales de fabricante (TI, ON Semi, Fairchild) y se distribuyen con spice libraries. Commitear en `frontend/src/simulation/spice/subcircuits/*.cir` y cargar con `import.meta.glob` o similar al primer uso.

### 4.4 Sensores y entradas

Ya existen como componentes Velxio (`Potentiometer`, `NTCThermistor`, `Photoresistor`, `Pushbutton`). Se añade una **capa de emisión SPICE** sin cambiar el wokwi-element:

| Existente | Emisión SPICE |
|---|---|
| `ntc-temperature-sensor` | `R{id} {net1} {net2} {R(T)}` calculado desde `temperature` slider |
| `photoresistor` | `R{id} {net1} {net2} {R(lux)}` |
| `pushbutton` | `R{id} {net1} {net2} {pressed ? 0.01 : 1G}` |
| `slide-switch` | `R` con valor según posición |
| `rotary-encoder` | pines digitales, sin estampa (fuera del solver) |

### 4.5 Instrumentos (componentes "probe", no se estampan)

| `metadataId` | Función | Cómo lee |
|---|---|---|
| `instr-voltmeter-dc` | Mide V entre dos terminales | `result.nodeVoltage(net+) − result.nodeVoltage(net−)` |
| `instr-ammeter-dc` | Mide I en serie con un cable | Inserta `V{id}_sense 0V` en serie; lee `i(V{id}_sense)` |
| `instr-multimeter` | V / I / R / Diode / Continuity | V y I igual que arriba. Para R: inyecta 1 mA de prueba y lee ΔV |
| `instr-scope-probe` | Agrega el nodo como canal del osciloscopio (modo analógico) | Durante `.tran`, samplea `v(node)` y lo publica al `useOscilloscopeStore` |
| `instr-signal-generator` | Fuente de señal editable (sin, pulse, pwl) | Estampa una `V{id}` con la forma de onda configurada |

**Amperímetro — detalle de implementación crítica**: ngspice no puede medir corriente en un cable arbitrario directamente. Hay que **intercalar una fuente de voltaje 0 V** en el cable:

```
; en vez de: R1 a b 1k
;              cable a → ammeter → R1 → cable b

V_amm_X pre_r1 a 0       ; inserta V 0V para medir i
R1 pre_r1 b 1k

; y leemos: i(V_amm_X)
```

El NetlistBuilder detecta cuando un cable pasa por un amperímetro y corta la net para insertar la fuente.

---

## 5. Algoritmo del NetlistBuilder

Toma `{ components, wires, boards, pinStates }` y produce un netlist string para ngspice.

```typescript
function buildNetlist(ctx: {
  components: Component[];
  wires: Wire[];
  boards: BoardInstance[];
  pinStates: Record<string, { v: 0 | 5 } | { duty: number }>;
  probes: Probe[];
  analysis: 'op' | 'tran' | 'ac';
  tranStep?: number;
  tranStop?: number;
}): string {
  // 1. Build Union-Find of (componentId, pinName) pairs from wires.
  const uf = new UnionFind<string>();
  for (const w of ctx.wires) {
    const a = `${w.start.componentId}:${w.start.pinName}`;
    const b = `${w.end.componentId}:${w.end.pinName}`;
    uf.add(a); uf.add(b);
    uf.union(a, b);
  }

  // 2. Canonicalize known special nets: any pin labeled GND / VSS / VEE → 'gnd' (= '0' in spice)
  //    VCC / VDD / 5V / 3V3 → 'vcc_<voltage>'
  for (const comp of ctx.components) {
    for (const pin of pinsOf(comp)) {
      const key = `${comp.id}:${pin.name}`;
      if (isGroundPin(pin)) uf.setCanonical(key, '0');
      else if (isVccPin(pin)) uf.setCanonical(key, 'vcc_rail');
    }
  }
  for (const board of ctx.boards) {
    for (const pin of boardGndPins(board)) uf.setCanonical(`${board.id}:${pin}`, '0');
    for (const pin of boardVccPins(board)) uf.setCanonical(`${board.id}:${pin}`, 'vcc_rail');
  }

  // 3. Allocate auto-names for every other net. Use stable hashing so netlists are diffable.
  const netNames = assignNetNames(uf);  // net0, net1, ... deterministic

  // 4. Detect floating nodes: nets with only reactive connections (C, L).
  //    Add an auto-pull to 0 with 100 MΩ to prevent ngspice singular-matrix hang.
  const floatingNets = detectFloatingNets(ctx.components, netNames);

  // 5. Emit cards
  const lines = [`Velxio circuit @ ${new Date().toISOString()}`];
  const uses: Set<string> = new Set();  // which .model / .subckt we need

  for (const comp of ctx.components) {
    if (isInstrument(comp)) continue;                  // probes don't stamp
    const card = componentToSpice(comp, netNames, uses);
    if (card) lines.push(card);
  }

  // 6. Ammeters: rewrite — for every ammeter, insert V<id>_sense 0 V between its terminals
  //    and re-point connected components accordingly. (Handled inside componentToSpice.)

  // 7. Add board GPIO sources
  for (const board of ctx.boards) {
    for (const [pinName, state] of Object.entries(ctx.pinStates[board.id] ?? {})) {
      const net = netNames.get(`${board.id}:${pinName}`);
      if (!net) continue;
      const v = 'duty' in state ? state.duty * board.vcc : state.v;
      lines.push(`V_${board.id}_${pinName} ${net} 0 DC ${v}`);
    }
  }

  // 8. Vcc rail source
  if (uf.has('vcc_rail')) lines.push(`V_VCC vcc_rail 0 DC ${dominantBoardVcc(ctx.boards)}`);

  // 9. Auto-pull-downs on floating nets
  for (const net of floatingNets) lines.push(`R_autopull_${net} ${net} 0 100Meg`);

  // 10. Models and subcircuits
  for (const m of uses) lines.push(...modelOrSubcktText(m));

  // 11. Analysis
  if (ctx.analysis === 'op') lines.push('.op');
  else if (ctx.analysis === 'tran') lines.push(`.tran ${ctx.tranStep} ${ctx.tranStop}`);
  else if (ctx.analysis === 'ac') lines.push('.ac dec 20 1 1Meg');

  lines.push('.end');
  return lines.join('\n');
}
```

### 5.1 Detección de nodos flotantes

**Regla práctica del sandbox** (gotcha G-8): cualquier nodo que sólo se conecte a capacitores/inductores y/o diodos/transistores sin camino DC a 0 hará que ngspice se cuelgue 60 s en recovery. La solución barata es añadir `R 100 MΩ` a ground en cada uno.

Algoritmo: para cada net, itera sus conexiones; si hay al menos una `R` finita en el mismo camino UF hacia `0`, es seguro. Si no, etiquétalo como flotante y añade el pull-down. Implementación O(V+E) con BFS.

### 5.2 Cache del netlist

Si `components` y `wires` no han cambiado desde la última invocación, reutiliza el string anterior y sólo sustituye los valores de las fuentes (pin states). Evita 10–30 ms de re-construcción de string en cada solve.

---

## 6. Fases de entrega

### Fase 8.1 — Fundamentos (1 semana)

**Goal**: `eecircuit-engine` funcionando en el proyecto de Velxio, sin UI. Tests pasan en `frontend/src/__tests__/`.

**Entregables**:
- `npm install eecircuit-engine` + marca de lazy-load en Vite.
- Port de `SpiceEngine.ts` y `SpiceEngine.lazy.ts` (copia fiel del sandbox con tipos TS).
- Smoke test: `frontend/src/__tests__/spice-smoke.test.ts` ejecuta un divisor de voltaje y verifica `v(out) = 6`.
- Port de los 22 tests `spice_*.test.js` del sandbox.
- Telemetría: logs `[SpiceEngine] boot in Xms` y `[SpiceEngine] solve in Xms`.

**DoD (Definition of Done)**:
- `npm test` en `frontend/` pasa los 22 tests.
- Bundle de dev (`npm run dev`) funciona sin errores de ESM/WASM.
- Bundle de prod (`npm run build:docker`) no crece (el lazy chunk es separado).

### Fase 8.2 — Netlist Builder + mapeo de componentes existentes (1 semana)

**Goal**: NetlistBuilder puede tomar un escenario de Velxio (con R, LED, pot, NTC) y emitir un netlist válido. No hay UI todavía.

**Entregables**:
- `NetlistBuilder.ts` con algoritmo de §5, UnionFind.
- `componentToSpice.ts` — soporta los 4 pasivos de Velxio hoy: `resistor`, `led`, `capacitor`, `potentiometer`, + NTC, photoresistor, pushbutton.
- Tests: `netlistBuilder.test.ts` con 10+ escenarios (divisor, RC charging, LED+R, pot+ADC).
- Integración con `useSimulatorStore`: acción `runElectricalSolve` (no-op si `mode === 'off'`).

**DoD**:
- Creamos un escenario programáticamente (no por UI), llamamos `runElectricalSolve`, verificamos que `store.electrical.nodeVoltages` tiene los valores correctos.
- Port de los tests end-to-end del sandbox: `e2e_pot_pwm_led` y `e2e_thermistor` funcionan dentro de Velxio.

### Fase 8.3 — UI: toggle y overlay de voltajes (1 semana)

**Goal**: usuario puede activar modo eléctrico y ver voltajes en el canvas.

**Entregables**:
- `ElectricalModeToggle.tsx` en toolbar (icono ⚡).
- `ElectricalOverlay.tsx` — SVG overlay que etiqueta cada nodo con `V(n) ≈ 2.50 V`.
- `SpiceErrorBanner.tsx` — si `!converged`, muestra banner con mensaje de ngspice (`getError()`).
- `LED.tsx` — usar `brightness = electrical.componentCurrents[id] / 0.020` en lugar del bool actual.
- Scheduler con debounce 50 ms.
- Hook en `PinManager.onAnyPinChange` → solve.

**DoD**:
- Activar toggle con un sketch "Blink" cargado → pin 13 alterna → LED se enciende con brillo calculado real.
- Activar toggle con circuito NTC → `analogRead(A0)` refleja el voltaje real del divisor.
- Probar con 5+ circuitos típicos del tutorial Velxio; todos convergen.

### Fase 8.4 — Nuevos componentes analógicos (2 semanas)

**Goal**: las 30 piezas nuevas del §4 aparecen en el ComponentPicker, se pueden arrastrar al canvas, tienen editor de valores.

**Entregables**:
- Todos los React wrappers en `components-analog/` (15+ componentes con SVG, properties, pinInfo).
- Metadata regenerada (`generate-analog-metadata.ts`) y agregada a `components-metadata.json`.
- `ComponentValueEditor.tsx` con parser SI (`k`, `Meg`, `u`, `n`, `p`).
- `componentToSpice.ts` expandido con todos los part numbers + `.subckt` para IC.
- Biblioteca `subcircuits/` con los macromodelos (LM358, LM741, 555, 7805, LM317, TL431).
- Tests: un test por parte (`bjt-2n3055`, `opamp-lm358` Schmitt trigger, `timer-555` astable real, etc.).

**DoD**:
- Usuario puede construir un amplificador con LM358, medir la ganancia y coincide con cálculo manual.
- Usuario puede construir un 555 astable, verificar la frecuencia con osciloscopio.
- Usuario puede construir un regulador 7805 con capacitores y ver la salida estabilizada.
- Todos los nuevos componentes aparecen en el picker bajo `analog-passive` / `analog-active`.

### Fase 8.5 — Instrumentos de medición (1 semana)

**Goal**: voltímetro, amperímetro, multímetro, signal generator, osciloscopio analógico.

**Entregables**:
- `Voltmeter.tsx` — 2 terminales; display con unidades (mV/V/kV según magnitud).
- `Ammeter.tsx` — inserta V sense en el cable; display con unidades (nA/µA/mA/A).
- `Multimeter.tsx` — dial con modos V/I/R/Continuity/Diode.
- `OscilloscopeAnalogProbe.tsx` — clip que se conecta a un nodo; extiende `useOscilloscopeStore` con canales analógicos.
- Modificación de `Oscilloscope.tsx`: renderiza waveforms analógicos además de digitales. Usa `.tran` de ngspice para samplear.
- `SignalGenerator.tsx` — UI con selector de forma de onda (DC/sine/square/triangle/PWL), amplitud, frecuencia, offset.
- `MeasurementPanel.tsx` — panel lateral con tabla de todas las lecturas.

**DoD**:
- Usuario pone voltímetro en un divisor → lee `3.33 V`, refresca al mover slider.
- Usuario pone amperímetro en serie con un LED → lee `~13 mA`.
- Usuario conecta signal generator (1 kHz sine, 1 Vpp) a filtro RC, probe del osciloscopio en la salida → ve Bode manual (atenuación visible al 10 kHz).

### Fase 8.6 — Validación + rollout (1–2 semanas)

**Goal**: release behind feature flag, telemetría, docs de usuario.

**Entregables**:
- Feature flag: `VITE_ELECTRICAL_SIM=true` (prod), `false` (si bugs).
- Docs de usuario: `docs/wiki/electrical-simulation-user-guide.md`.
- Telemetría: opt-in, envía `solve_ms`, `component_count`, `converged` a un endpoint interno.
- Tests de regresión: ningún sketch del examples gallery debe romperse.
- Checklist de QA (en el PR final):
  - [ ] LED blink con nueva simulación eléctrica → brillo correcto
  - [ ] Pot + ADC → monotónico
  - [ ] NTC + ADC → temperatura recuperable
  - [ ] 555 astable → frecuencia correcta ±10 %
  - [ ] Op-amp inverter → ganancia −10
  - [ ] MOSFET switch → V_drain conmuta
  - [ ] Voltímetro / amperímetro → lecturas coinciden con cálculo manual
  - [ ] Toggle on/off → performance acceptable (< 100 ms solve)
  - [ ] Bundle size production → lazy chunk no bloquea initial load
  - [ ] 0 regresiones en examples gallery

**DoD**:
- PR merged a `master`.
- Blog post / release notes.
- Roadmap actualizado.

---

## 7. Mapeo de boards (múltiples MCUs conviviendo)

El survey reveló que Velxio tiene `boards[]`: múltiples Arduinos, RP2040, ESP32 en el mismo canvas. El NetlistBuilder debe manejar esto:

- Cada board **declara sus propios nets** con prefijo `{boardId}_{pinName}`. Ej: `uno1_d13`, `esp32a_gpio5`.
- El **VCC rail no se comparte automáticamente** entre boards (pueden alimentarse a 5 V y 3.3 V).
- Un cable entre `uno1:5V` y `esp32a:5V` los une en la misma net vía Union-Find.
- Un cable entre `uno1:D2` y `esp32a:GPIO5` es legal (y común para buses UART/I²C). Ambos lados se modelan como `V<source>` pero sólo uno puede ser "driver" en un instante dado. En caso de conflicto (ambos OUTPUT diferente valor) → banner rojo "bus conflict" y ngspice resolverá con el promedio via GMIN.

### 7.1 RP2040 — ADC y PWM

- RP2040 tiene 3 canales ADC (GP26, GP27, GP28) + sensor de temperatura interno (GP4 hidden).
- `RP2040SpiceBridge.ts` es prácticamente igual al de AVR, con:
  - Tensión de referencia 3.3 V
  - 12-bit ADC en lugar de 10
  - PWM: hasta 16 canales, cualquier pin; leer duty via `rp2040.getPWMDuty(pin)` (ya existe en `RP2040Simulator.ts`).

### 7.2 ESP32 — limitaciones

- ESP32 ADC es notoriamente no-lineal; el modelo SPICE de su ADC necesita una curva de corrección. MVP: lineal 0–3.3 V, 12-bit.
- PWM ("LEDC") con 16 canales, resolución configurable hasta 20 bits. Leer duty via `esp32.getPWMDuty(channel)` (disponible en el emulador QEMU).

---

## 8. Riesgos y mitigaciones

| Riesgo | Impacto | Mitigación |
|---|---|---|
| **Bundle +39 MB** | Usuarios en red lenta se frustran | Lazy-load detrás de toggle. Chunk separado. Cache agresivo. Primer click del toggle: splash "Downloading simulator (39 MB)…" |
| **ngspice cuelga 60 s por matriz singular** | Freeze de UI | Validación pre-solve: detectar nodos flotantes con BFS; añadir pull-down 100 MΩ automáticamente. Logs claros si ocurre. Timeout 3 s con abort. |
| **Co-sim > 100 ms por slice con circuitos grandes** | Lag visible | 1) debounce 50 ms en scheduler, 2) mover a Web Worker si > 20 componentes, 3) modo "DC only" por defecto, 4) UI indicador "computing…" si > 200 ms |
| **Conflicto entre Velxio pin simulado y SPICE** | Resultados incorrectos | SPICE es la fuente de verdad para tensiones analógicas. Las mutaciones manuales vía UI (click en LED) se convierten en modo "sim off". |
| **Modelos SPICE de terceros con licencia unclear** | Bloqueo legal | Usar sólo modelos **publicados por fabricantes** (TI, ON, Microchip) y distribuir como strings en el source bajo cláusula de fair use educativa. Documentar origen por cada `.subckt` en un comentario. |
| **PWM cuasi-estático incorrecto para circuitos sensibles a ripple** | Mala UX en audio / switching power | Detectar: si hay capacitor < 1 µF en el camino del PWM → escalar automáticamente a modo `.tran` con edges reales y aviso "switching detail enabled, may be slower" |
| **Regresión del emulador digital** | Tests existentes fallan | Toggle off es zero-risk (nada cambia en el solver). Tests de regresión de `frontend/src/__tests__/` deben seguir pasando con `VITE_ELECTRICAL_SIM=false`. |
| **Modelos BJT/MOSFET no convergen en esquemas exotic** | Usuario frustrado | Modo "Beginner": modelos ideales (VCVS para op-amp, switch para transistor). Modo "Expert": modelos reales con `.model`. Toggle en opciones. |

---

## 9. Criterios de éxito / métricas

**Cuantitativos**:

| Métrica | Objetivo |
|---|---|
| Tests de portabilidad desde sandbox | **47/47 pasando** en `frontend/` |
| Tiempo de boot de ngspice (primera vez) | < 800 ms en laptop estándar |
| Tiempo de solve para circuito típico (20 componentes) | < 50 ms |
| Tamaño del chunk lazy | ≤ 45 MB comprimido |
| Precisión en tests E2E vs analítico | < 2 % error |
| Zero regresiones en modo off | 100 % de tests previos pasan |

**Cualitativos**:

- Un usuario con conocimiento de electrónica básica puede armar un amplificador BJT y ver la ganancia correcta en el osciloscopio.
- Un usuario puede armar un 555 astable y medir la frecuencia con un probe.
- Un usuario puede conectar un termistor a un Arduino y leer la temperatura real convertida desde ADC.
- Un tutorial de "control de brillo de LED con potenciómetro" funciona end-to-end sin intervención manual.

---

## 10. Fuera de alcance (futuras fases)

Se documentan aquí para que no se cuelen en esta fase por scope creep.

- **Análisis `.noise`** — ruido Johnson/shot/flicker. ngspice lo soporta; lo dejamos para cuando haya UI de audio.
- **Análisis Monte Carlo de tolerancias** — simular 100 copias con ±5 % en resistencias.
- **Temperatura ambiente global** — afecta parámetros de todos los componentes.
- **Análisis `.pz`** (pole-zero) — diseño de filtros avanzados.
- **Análisis S-parameter** — RF.
- **Emulación de ICs digitales discretos** (74HC00, 74HC595, 4017) con timing real. Actualmente se podrían hacer con B-sources, pero se dejará para fase 9.
- **Transformadores acoplados** (ngspice `K`) — para SMPS.
- **Modelos térmicos** — acoplar disipación de potencia con perfil térmico.
- **Biblioteca de "circuitos ejemplo"** — pre-cargados en el picker (Darlington, diff-amp, current mirror, etc.).

---

## 11. Apéndices

### 11.1 Ejemplo concreto de netlist generado

Escenario: Arduino Uno con sketch que hace `analogWrite(9, 127)`, conectado a una red RC (10 kΩ + 1 µF) y un voltímetro en la salida.

```
Velxio circuit @ 2026-04-15T12:00:00Z
* Board pin sources
V_uno1_d9 uno1_d9 0 DC 2.5        ; duty=0.5 × 5V
* Components
R_r1 uno1_d9 net0 10k              ; R1 from D9 to intermediate net
C_c1 net0 0 1u IC=0                ; C1 from intermediate to ground
* Auto-pull (net0 has cap-to-ground, so it has a DC path via V_uno1_d9 → R_r1)
* Vcc rail
V_VCC vcc_rail 0 DC 5
* Analysis
.op
.end
```

Tras `runSim`: `v(net0) ≈ 2.5 V`. El voltímetro (que conoce sus 2 terminales = `net0` y `0`) muestra `2.50 V`.

### 11.2 Ejemplo con transistor

Escenario: 2N2222 en common-emitter, señal de entrada 10 mV AC a 1 kHz desde un signal generator, R_C=4.7k, R_E=1k bypasseado con 100 µF, osciloscopio en colector.

```
Velxio amplifier
V_VCC vcc_rail 0 DC 12
V_sg1 sg1_out 0 SIN(0 0.01 1k)
C_cin sg1_out net_base 1u
R_rb1 vcc_rail net_base 47k
R_rb2 net_base 0 10k
R_rc vcc_rail net_coll 4.7k
R_re net_em 0 1k
C_ce net_em 0 100u
Q_q1 net_coll net_base net_em Q2N2222
.model Q2N2222 NPN(Is=14.34f Bf=200 Vaf=74.03 …)
C_cout net_coll scope_probe1 1u
R_scope_input scope_probe1 0 1Meg       ; high-Z scope input (1 MΩ)
.tran 10u 6m
.end
```

El osciloscopio samplea `v(scope_probe1)`; muestra la onda invertida y amplificada.

### 11.3 Tabla de conversión wokwi-elements existentes → SPICE

Extensión del mapeo del §4; fuente: survey de Velxio.

| wokwi tagName | `metadataId` actual | Emite SPICE | Notas |
|---|---|---|---|
| `<wokwi-resistor>` | `resistor` | **sí** | R lineal |
| `<wokwi-resistor-us>` | `resistor-us` | **sí** | idem |
| `<wokwi-led>` | `led` | **sí** | D con Is/n por color |
| `<wokwi-rgb-led>` | `rgb-led` | parcialmente | 3 LEDs independientes |
| `<wokwi-pushbutton>` | `pushbutton` | **sí** | R conmutable |
| `<wokwi-slide-switch>` | `slide-switch` | **sí** | |
| `<wokwi-potentiometer>` | `slide-potentiometer` | **sí** | dos R |
| `<wokwi-photoresistor>` | `photoresistor` | **sí** | R(lux) |
| `<wokwi-ntc-temperature-sensor>` | `ntc-temperature-sensor` | **sí** | R(T) |
| `<wokwi-7segment>` | `7-segment` | **sí** | 8 LEDs |
| `<wokwi-buzzer>` | `buzzer` | como R de 100 Ω | sonido fuera del solver |
| `<wokwi-servo>` | `servo-horn` | R=50 Ω consumo | ángulo fuera del solver |
| `<wokwi-dc-motor>` | `dc-motor` | R + L serie | back-EMF opcional |
| `<wokwi-dht22>` | `dht22` | **no** | protocolo 1-wire, fuera |
| `<wokwi-lcd1602>` | `lcd1602` | **no** | display, fuera |
| `<wokwi-ssd1306>` | `ssd1306` | **no** | I²C, fuera |
| `<wokwi-neopixel-matrix>` | `neopixel-matrix` | **no** | protocolo WS2812, fuera |
| `<wokwi-mpu6050>` | `mpu6050` | **no** | I²C, fuera |

### 11.4 Mapeo de pines de part numbers reales

Ejemplo: **LM358** (DIP-8 dual op-amp).

```
       +──┐  ┐──+
   OUT1─1  \_/ 8─VCC
   IN−1─2      7─OUT2
   IN+1─3      6─IN−2
    GND─4      5─IN+2
       +───────+
```

En Velxio, el `<wokwi-lm358>` (nuevo) expondrá 8 pines con esos nombres. El `componentToSpice` para el metadataId `opamp-lm358` emite:

```
X_{id} {inp1} {inn1} {vcc} {out1} {gnd} {inp2} {inn2} {out2} LM358
```

Y el `.subckt LM358` (importado de la biblioteca) hace el macromodelo completo.

---

## 12. Checklist final antes de mergear cada PR

- [ ] Todos los tests del sandbox siguen pasando en su ubicación actual (baseline preservado)
- [ ] Nuevos tests en `frontend/src/__tests__/` pasan
- [ ] `npm run build:docker` exitoso
- [ ] `npm run lint` clean
- [ ] Feature flag `VITE_ELECTRICAL_SIM` respeta default off en prod hasta Fase 8.6
- [ ] Bundle analyzer: el chunk de `eecircuit-engine` es `import()` separado
- [ ] QA manual: al menos 3 circuitos representativos validados
- [ ] Docs actualizados: entrada en `docs/wiki/` para cada nuevo componente
- [ ] CLAUDE.md actualizado: sección "Electrical simulation"
- [ ] Changelog: release notes preparadas

---

## 13. Referencias cruzadas

- Sandbox madre: [`test/test_circuit/`](../..)
- Plan inicial (baseline): [`plan1.md`](./plan1.md)
- Findings del sandbox: [`../autosearch/`](../autosearch/)
- Wiki docs: [`docs/wiki/circuit-emulation.md`](../../../docs/wiki/circuit-emulation.md)
- Plan anterior de integración (superseded): [`docs/wiki/circuit-emulation-velxio-integration.md`](../../../docs/wiki/circuit-emulation-velxio-integration.md) → este documento lo reemplaza con más detalle de componentes e instrumentos.