Documentação

Início rápido§

O Circuit Forge é um simulador de circuitos analógicos baseado em código que roda 100% no navegador, sem backend. Você descreve o circuito em TypeScript — com pinos nomeados como anode/cathode e +/- — e o motor numérico (Modified Nodal Analysis + Newton-Raphson, análises DC e transiente) resolve tudo localmente. O editor visual em canvas, com probes e osciloscópio, é uma projeção do código, nunca o contrário.

Além do simulador, existe o forge: um loop de verificação pensado para agentes LLM (e humanos). Uma bancada .bench.ts descreve circuito + spec; o CLI roda a escada lint → op → tran e devolve diagnósticos com código estável (tipo F105), localização no código-fonte, hints de dimensionamento verificados por simulação e exit codes com semântica — para que um agente convirja para um circuito funcional em poucas iterações, sem parsear texto solto.

Como rodar§

$ npm install
$ npm run dev                                          # app em http://localhost:5173
$ npm test                                             # suíte Vitest
$ npm run forge -- verify bench/led-driver.bench.ts    # escada de verificação

Primeiro circuito no simulador§

No editor de código do simulador (aba Simulador), este divisor de tensão é o "olá, mundo": crie o circuito, conecte os pinos, analise e leia os resultados no console.

const circuit = new Circuit();
const gnd = new Ground();

const v1 = new VoltageSource(10);
const r1 = new Resistor(1000);
const r2 = new Resistor(2000);

v1.pin('+').connect(r1.pin('1'));
r1.pin('2').connect(r2.pin('1'));
r2.pin('2').connect(gnd.pin('1'));
v1.pin('-').connect(gnd.pin('1'));

circuit.analyze('dc');

console.log('V_out (R2):', r2.voltage.toFixed(3), 'V');
console.log('Corrente:', (r1.current * 1000).toFixed(3), 'mA');

Você deve ver V_out (R2): 6.667 V — o divisor 1k/2k sobre 10 V. A partir daí, abra os exemplos prontos ou vá direto para as bancadas.

Bancadas§

Uma bancada (arquivo .bench.ts) é o artefato completo de verificação: circuito + parâmetros livres + asserções. A função bench(nome, fn) recebe um testbench builder tb com esta API:

• tb.add(id, componente) — registra um componente com id estável ('R1', 'D1'…). Esse id é a identidade nos diagnósticos, nas sondas e no --set.
• tb.gnd — o nó de referência (terra). Todo circuito precisa de caminho DC até ele.
• tb.name(nome, pin) — dá nome estável a um net (ex.: 'out') para poder sondá-lo em asserções op.
• tb.param(id, {min, max, scale}) — delegação de dimensionamento: declara o parâmetro livre. LLMs são bons em topologia e ruins em dimensionamento contínuo; quando uma asserção falha, a plataforma varre a faixa, simula cada ponto e devolve a faixa que passa (hint verificado) — o agente nunca chuta números.
• tb.expect.op(...) / tb.expect.tran(...) — as asserções: o spec como teste.

Unidades§

Valores aceitam número ou string com sufixo de engenharia: '4.7k', '10m', '2u', '1M', '1e-6'.

bench/led-driver.bench.ts comentado§

import { bench, VoltageSource, Resistor, LED } from 'circuit-forge';

/**
 * Driver de LED: fonte de 5 V, resistor em série, LED para o terra.
 * O "olá, mundo" canônico da escada de verificação — passa como está.
 */
export default bench('led-driver', (tb) => {
  // ids estáveis: são a identidade nos diagnósticos, sondas e --set
  const v1 = tb.add('V1', new VoltageSource(5));
  const r1 = tb.add('R1', new Resistor('330'));
  const d1 = tb.add('D1', new LED());

  // pinos nomeados eliminam a classe de erro mais comum dos LLMs
  v1.pin('+').connect(r1.pin('1'));
  r1.pin('2').connect(d1.pin('anode'));
  d1.pin('cathode').connect(tb.gnd);
  v1.pin('-').connect(tb.gnd);

  // net nomeado: agora 'led' é endereçável nas asserções op
  tb.name('led', d1.pin('anode'));

  // dimensionamento é da plataforma: se uma asserção op falhar,
  // ela varre esta faixa e devolve um hint VERIFICADO por simulação
  tb.param('R1', { min: '100', max: '10k', scale: 'log' });

  // o spec como teste
  tb.expect.op('D1.i').toBeWithin('5m', '15m'); // LED aceso, mas seguro
  tb.expect.op('led').toBeWithin(1.8, 2.6);     // queda direta plausível
});

Rode com npm run forge -- verify bench/led-driver.bench.ts. Há exemplos quebrados de propósito em bench/broken/ para ver cada diagnóstico em ação.

Sondas§

Toda asserção mede uma sonda. A gramática é curta:

Nets automáticos (n1, n2, …) não são endereçáveis de propósito: a numeração muda quando você adiciona ou remove componentes, então uma sonda 'n3' quebraria silenciosamente entre edições. Nomeie o net com tb.name('out', pin) para garantir estabilidade — e por isso o padrão n<dígitos> é reservado e não pode ser usado como nome de net.

tb.name('out', r1.pin('2'));          // nomeia o net do pino
tb.expect.op('out').toBeCloseTo(2.5, 0.1); // agora é sondável

Asserções§

Estágio op — ponto de operação DC§

Formato: tb.expect.op(sonda).método(...).

Estágio tran — transiente§

Formato: tb.expect.tran({tstop, dt}).probe(sonda).método(...) — encadeável, com múltiplas sondas e checagens na mesma janela.

Exemplo real, de bench/rc-lowpass.bench.ts (R = 1k, C = 1µ, τ = 1 ms):

tb.expect
  .tran({ tstop: '6m', dt: '10u' })
  .probe('C1.v')
  .toSettleWithin({ target: 5, tol: 0.05, by: '4m' })
  .toNeverExceed(5.5)
  .toEndCloseTo(5, 0.1)
  .probe('R1.i')
  .toStayBelow('6m'); // corrente de inrush limitada por V/R

Diagnósticos§

Todo erro tem código estável (nunca renumerado — parsers e agentes podem depender dele), localização no código-fonte e correção. forge explain <código> traz a explicação longa com a física por trás de cada um.

Faixas§

Códigos ativos§

Contrato de confiança dos fixes§

Todo fix carrega confidence:

Invariantes (aplicados em code review): nunca emitir fix que referencia flag ou capacidade que não existe; nunca emitir número não simulado sem rótulo suggested.

Exit codes§

Notas de semântica§

• O lint sempre roda (mesmo com --stage op): resolver um circuito que o lint rejeitaria significaria descartar componentes silenciosamente e reportar números fabricados.
• settleWithin que nunca estabiliza reporta measured = fim da janela (finito) — nunca Infinity, que viraria null no JSON.
• O hint.passingRange cobre apenas a maior sequência contígua de amostras aprovadas (cada amostra passa no lint E em todas as asserções op); os valores exatos simulados estão em passingSamples.

CLI§

O forge roda via npm run forge -- <comando>. A saída é determinística — sem timestamps e sem cores no texto —, então dois runs idênticos fazem diff limpo.

USAGE
  forge verify <bench.ts> [opções]    # roda a escada: lint → op → tran
  forge log list [--json]             # lista runs do ledger (.forge/runs.jsonl)
  forge log show <runId> [--json]     # RunRecord completo de um run passado
  forge explain <código>              # docs de um diagnóstico, ex.: forge explain F101
  forge catalog [tipo] [--json]       # datasheet dos componentes + gramática

OPÇÕES DO VERIFY
  --stage op,tran        # roda só estes estágios (o lint SEMPRE roda)
  --set R1=330,V1=5      # sobrescreve valores sem editar a bancada
  --json                 # emite o RunRecord completo em JSON no stdout
  --no-hints             # pula hints verificados de dimensionamento (mais rápido)
  --no-ledger            # não grava este run em .forge/runs.jsonl

Sessão completa: fail com hint → --set → pass§

Com bench/broken/led-overcurrent.bench.ts — resistor de série pequeno demais (LED a ~28 mA contra spec de 8–12 mA):

$ npm run forge -- verify bench/broken/led-overcurrent.bench.ts

bench led-overcurrent  netlist cb4f1e998fc8  ([email protected])

  ✓ lint  pass
  ✗ op    fail
        A301 a1: D1.i within [8m, 12m] — measured 28.04m (outside by 16.04m, 2.34x)
          at bench/broken/led-overcurrent.bench.ts:22
          hint (verified): R1 in [261, 316.2] passes all op assertions — try R1 = 261
  – tran  skipped (op assertions failed)

FAIL · 1 problem · first failure: a1 · exit 1
run cb4f1e998fc8-001 → .forge/runs.jsonl (forge log show cb4f1e998fc8-001)

$ npm run forge -- verify bench/broken/led-overcurrent.bench.ts --set R1=280

bench led-overcurrent  netlist cb4f1e998fc8  set R1=280  ([email protected])

  ✓ lint  pass
  ✓ op    pass
        1 assertion passed

PASS · exit 0

Exit code 1 disse "circuito válido, spec não atingido"; o hint verificado deu a faixa que passa; --set R1=280 aplicou a correção sem editar código. Para agentes, --json devolve o mesmo conteúdo como RunRecord estruturado, e forge log list mantém o histórico do que já foi tentado fora do contexto (anti context attrition).

Componentes§

O catálogo abaixo é o mesmo que forge catalog devolve — o "datasheet" que o agente consulta. Valores aceitam número ou string com unidades ('4.7k', '10m', '2u', '1M'; lembre: m = mili, M = mega).

Além dos built-in, componentes customizados podem ser definidos via defineComponent({ pins, params, stamp, onStep, ... }) — com estado interno e flag nonlinear — como no exemplo MCU + LEDs.

Roadmap§

O v0.1 já entrega o loop completo: motor MNA validado (DC + transiente, Newton-Raphson), DSL bench(), lint estrutural pré-solver, hints verificados por simulação e o CLI com ledger. Daqui em diante: