breadkit 0.1.0 → 0.2.0

data/docs/dsl.md

@@ -1,6 +1,6 @@
 # Breadkit DSL
 
-Breadkit evaluates a Ruby file into a breadboard circuit, resolves pin and wire locations, and exposes the result as nets and JSON IR. DSL files are executable Ruby; only load files you trust. Use IR JSON when the input must remain data-only.
+Breadkit evaluates a Ruby file into a breadboard circuit, resolves pin and wire locations, and exposes the result as nets and JSON IR. DSL files are executable Ruby; only load files you trust. Use [YAML or TOML circuit files](DECLARATIVE.md) when the input must remain data-only.
 
 ## A small circuit
 
@@ -28,35 +28,226 @@ end
 | Method | Purpose |
 | --- | --- |
 | `title(text)` | Diagram title. |
-| `board(id, split_rails: false)` | Select `:full`, `:half`, `:mini`, or a custom board ID. |
-| `use_parts(path)` / `use_boards(path)` | Load additional YAML definitions relative to the DSL file. Paths may use globs. |
-| `supply(name, voltage:, plus:, minus:)` | Add a DC source. Both terminals occupy board holes. |
+| `board(id, split_rails: false, as: nil)` | Select `:double_full` (1660 holes), `:full`, `:half`, `:mini`, `:universal`, `:stripboard`, or a custom board ID. Name each board with `as:` when using multiple boards. |
+| `use_parts(path)` / `use_boards(path)` | Load additional YAML definitions relative to the DSL file. Paths may use globs. Run `breadkit lock FILE` to pin the matched local definitions. |
+| `include(path)` | Evaluate another trusted DSL file in the same circuit. Relative paths resolve from the including file; circular includes are rejected. |
+| `block(name) { ... }` / `use_block(name, *args, **kwargs)` | Define and expand a reusable group of DSL declarations. Each name is unique within the circuit. |
+| `bus(name, **lines)` | Label the explicit reference for each line as `NAME_LINE`, for example `I2C_SCL`. |
+| `step(number, title: nil) { ... }` | Group assembly declarations under a numbered step. Numbers start at 1 and increase by 1. |
+| `supply(name, voltage:, plus:, minus:, current_limit: nil)` | Add a DC source. Both terminals occupy board holes. Optional `current_limit:` is the supply's positive output limit in amperes. |
+| `supply(from:, plus:, minus:)` | Route a defined offboard power output and its return pin to board holes or rails. |
 | `net(name, at:)` | Label a hole or component pin. |
 | `part(ref, type, value = nil, pins: ..., at: ..., **attrs)` | Place a defined part. `pins:` accepts pin order arrays or pin-name hashes. |
 | `wire(from, to, color: nil, id: nil, route: :straight, layer: nil, electrical: true, dashed: false)` | Connect two holes or pin references. `route: :arc` curves the wire; `route: :edge` routes around an outer board edge or from an external module along its terminal row. `layer:` groups wires in interactive SVG output; `electrical: false` draws a visual alternative without changing circuit connectivity. |
+| `connect(from, to, when: nil)` | Declare that two references should be connected. This is an intent assertion; it does not place a wire. |
 | `offboard(name, type, side: :left, at: nil, unused: [], **attrs)` | Place a module beside the board; `at:` aligns its first pin to a board position, and attrs such as `address:` are shown on the module. |
-| `expect { ... }` | Declare `connected`, `isolated`, or named `net` expectations. `strict: true` also rejects unlisted pins on declared nets. |
+| `expect { ... }` | Declare `connected`, `isolated`, or named `net` expectations. `strict: true` also rejects unlisted pins on declared nets. Use `when: "SW1"` to check a selected switch state. |
+| `expect_voltage(ref, range)` / `expect_current(ref, range)` | Declare inclusive DC ranges for a net or component. Current is compared by magnitude in amperes. These methods also work inside `expect(when: "SW1")`. |
 | `lint_disable(rule, on: nil, reason: nil)` | Suppress a lint rule, optionally for one target. |
 
 Short forms are available for `resistor`, `capacitor`, `electrolytic`, `diode`, `led`, `transistor`, `pot`, `button`, and `ic`.
 
+Standalone supplies require a positive voltage. Use the positive and negative
+terminal positions to express polarity; an inclusive voltage range must have
+two positive, ascending limits. By default, net labels `GND`, `0V`, `VSS`, and
+`GROUND` anchor the potential calculation at 0 V regardless of case. A custom
+board definition can replace that list with `ground_labels: [RETURN, AGND]`.
+
+## Connection intent before placement
+
+Declare an intended connection before placing parts:
+
+```ruby
+connect "R1.1", "D1.anode"
+board :mini
+resistor :R1, "330", pins: %w[a1 a3]
+led :D1, color: :red, anode: "b5", cathode: "b6"
+wire "b1", "a5"
+```
+
+`connect` records an expectation and does not add a physical wire or change
+the resolved nets. Run `bklint` to find an `Intent/ConnectionMismatch` when
+the placed circuit fails to join the references. Add or correct a `wire`
+declaration to satisfy it. The references may be declared before their parts;
+unknown pins are reported after resolution. Use `when: "SW1"` to check a
+selected switch state. This declaration uses the existing `connected`
+expectation in JSON IR. Run `breadkit suggest FILE` to see conservative
+free-hole candidates for unmet default-state intent. If the wire above is
+omitted, it prints JSON such as
+`[{"from":"c1","to":"c5","refs":["R1.1","D1.anode"]}]` without editing the
+circuit. State-specific intent, offboard pins, occupied strips, holes under
+component bodies, and known voltage conflicts are skipped. The proposed route
+and physical fit still need review before adding a `wire` declaration.
+
+## Power from an offboard module
+
+The Arduino Uno definition declares 5 V and 3.3 V outputs relative to GND.
+Connect one output and its return to breadboard rails with:
+
+```ruby
+board :half
+offboard :UNO, :arduino_uno
+supply from: "UNO.5V", plus: "T+", minus: "T-"
+```
+
+`T+` and `T-` each select a free rail hole. The call expands to wires from
+`UNO.5V` and `UNO.GND`; it does not add another voltage source. Use
+`from: "UNO.3V3"` for the 3.3 V output. The source must match a `provides`
+entry on the placed offboard part, and both destinations are required. For
+named boards, qualify the destinations, for example `B1.T+` and `B1.T-`.
+The resolved IR stores the two ordinary wires.
+
+## Reusable blocks and buses
+
+A block runs in the same DSL context each time it is used. Pass the references
+and holes for each instance explicitly so every component gets a distinct name
+and placement:
+
+```ruby
+board :mini
+
+block :indicator do |number, resistor_pins:, led_pins:|
+  resistor "R#{number}", "330", pins: resistor_pins
+  led "D#{number}", color: :red, **led_pins
+end
+
+use_block :indicator, 1,
+          resistor_pins: %w[a1 a3], led_pins: { anode: "b3", cathode: "b4" }
+use_block :indicator, 2,
+          resistor_pins: %w[a6 a8], led_pins: { anode: "b8", cathode: "b9" }
+```
+
+Blocks defined in an included DSL file are available to the including file.
+Recursive calls and duplicate block names are rejected. The resolved circuit
+and JSON IR contain the expanded parts and wires, with no separate block
+record.
+
+Use a bus to name related nets at their explicit board holes or pin references:
+
+```ruby
+bus :I2C, scl: "f22", sda: "f24"
+# Creates I2C_SCL at f22 and I2C_SDA at f24.
+```
+
+The call adds labels. Add `wire` declarations for physical connections to
+devices on each line. The bus helper accepts any named lines; it does not
+perform I2C protocol analysis.
+
+## Assembly steps
+
+Place the declarations for each assembly stage inside a numbered `step` block:
+
+```ruby
+board :mini
+
+step 1, title: "Install the resistor" do
+  resistor :R1, "330", pins: %w[b1 b3]
+end
+
+step 2, title: "Add the LED and return wire" do
+  led :D1, color: :red, anode: "c3", cathode: "c4"
+  wire "d4", "b2", color: :black
+end
+```
+
+Steps must be declared in order, starting at 1. Nested steps are rejected.
+Supplies, net labels, parts, and wires declared inside a step keep that step
+number; declarations outside steps have no number. Normal placement and
+connectivity checks still apply. `circuit.steps` holds each number and title,
+while each resolved item exposes `.step`. JSON IR carries the same `steps`
+list and optional `step` field on those items. Existing IR files without steps
+remain valid.
+
+## Multiple boards
+
+Name each board and qualify every physical hole or rail reference when a
+circuit has more than one breadboard:
+
+```ruby
+board :half, as: :B1
+board :mini, as: :B2
+
+supply :BAT, voltage: 5, plus: "B1.b1", minus: "B2.b2"
+resistor :R1, "330", pins: %w[B1.a1 B1.a3]
+led :D1, color: :red, anode: "B2.a1", cathode: "B2.a2"
+wire "B1.b3", "B2.b1", color: :red
+```
+
+The boards have separate conductive strips. A wire may cross between boards;
+one component's placed pins must stay on one board. Board names are unique and
+use letters, digits, and underscores, starting with a letter. Unqualified
+holes such as `a1` and rails such as `T+` are invalid in a named-board circuit.
+Component pin references such as `R1.1` remain global. An unindexed named rail
+such as `B2.T+` still selects a free hole on that board's rail.
+
+`circuit.boards` maps names to boards, and `circuit.board` exposes the combined
+qualified hole and strip lookup. Named-board circuits export IR schema version
+2 with a `boards` array of names, definitions, and options. Existing unnamed
+single-board circuits continue to export version 1. The version 2 schema is
+[`schema/ir-v2.json`](../schema/ir-v2.json).
+
 ## Hole and pin references
 
+The built-in `universal` model has 30 × 20 isolated pads. The built-in
+`stripboard` model has 20 continuous copper strips, one per row, with 30 holes
+per strip. The stripboard model assumes uncut tracks; cuts and custom copper
+patterns require a custom board definition or explicit layout support. These
+are example sizes, not a universal hardware standard. A custom board can set
+`terminal.strip_direction: row` to connect each terminal row across its
+columns; the default `column` connects each declared group within a column.
+Set `terminal.wire_attachment: solder` for a soldered board. A wire naming a
+placed component pin uses another free hole on the same strip when available;
+when none exists, it joins that pin's occupied pad. Explicit wires can also
+share solder pads. The default `socket` behavior keeps breadboard holes
+exclusive to one inserted lead or wire. Component leads still cannot share a
+hole in either model. For example:
+
+```ruby
+board :universal
+resistor :R1, "330", pins: %w[a1 a2]
+wire "R1.1", "b1"
+```
+
+No generic MB102 power-supply model is included because jumper-selected
+output voltages and pin locations vary by module.
+
 - Terminal holes use rows `a` through `j` and 1-based columns, such as `a10` or `J30`.
 - Rail holes use `T+`, `T-`, `B+`, and `B-`, optionally followed by a 1-based index. A rail without an index selects the nearest free hole.
 - A custom board may define other row and rail IDs in its YAML. For example, rows `u` and `v` use `u1` and `v1`; a rail with `id: PWR` uses `PWR1` or the unindexed `PWR`. Set each rail's `polarity:` to `+` or `-` for polarity-aware rendering.
+- Custom rails use `side: top|bottom|left|right|center` and a zero-based `order`. Left and right rails run vertically; `rail_layout.start_row` (default `1`) positions their first hole. Center rails occupy the two free rows of the declared `terminal.ravine_between` gap, so only orders `0` and `1` fit. Horizontal rails use `rail_layout.start_column` as before.
 - Component pins use `R1.1`, `D1.anode`, `U1.8`, or `U1.VCC`. A wire endpoint naming a placed pin selects a free hole in that pin's conductive strip.
 - The built-in `ne555` and generic `dip` definitions must straddle the center gap. For a generic package, set `pin_count`, for example `part :U2, :dip, pin_count: 14, at: "e20"`.
 - A generic pin header can be sized with `part :J1, :pin_header, pin_count: 4, pins: %w[a1 a2 a3 a4]`.
+- Footprint parts accept `rotate: 0|90|180|270` and `mirror: true|false`, for example `part :J1, :pin_header, pin_count: 3, at: "c10", rotate: 90`. Rotation is clockwise on the board; mirroring reflects left to right before rotation. The same orientation is checked when pins are placed explicitly.
+- A custom `placement: footprint` part may use `footprint_mm` instead of `footprint` to declare every pin offset in millimeters, for example `footprint_mm: {"1": [0, 0], "2": [5.08, 0]}`. Offsets must land on the 2.54 mm hole grid; Breadkit rejects a dimension that cannot fit rather than snapping it to another hole. Set the anchor at the first pin with `at:`. Use `render.size_mm` for body dimensions, which need not be multiples of the hole pitch.
+- A placed part with `render.size_mm` exposes its physical rectangle as `component.body_bounds(circuit.board)`, in board hole pitch units (`[x, y, width, height]`).
+- A custom two-pin part with `placement: leads` may set `max_lead_span_mm` to a positive number. This is the maximum supported distance between the two occupied hole centers after bending its leads. Set it from the actual package and usable lead length; generic built-in parts leave it unspecified. The linter can check placed parts that provide this limit.
 
 Values accept SI suffixes and RKM notation such as `4.7k`, `4k7`, `1M`, `100n`, `10uF`, and `4.7kΩ`.
 
 ## Switch states and IR
 
-`circuit.states("none")`, `circuit.states("single")`, and `circuit.states("all")` control switch contact simulation. `Breadkit.load(path)` reads `.bk.rb` DSL or `.json` IR. `circuit.to_ir` returns the resolved circuit representation; automatically selected holes are fixed in IR and are not selected again when loaded.
+`circuit.states("none")`, `circuit.states("single")`, and `circuit.states("all")` control switch contact simulation. `Breadkit.load(path)` reads `.bk.rb` DSL, `.bk.yml` / `.bk.yaml` / `.bk.toml` circuit files, or `.json` IR. `circuit.to_ir` returns the resolved circuit representation; automatically selected holes are fixed in IR and are not selected again when loaded.
+
+For independent SPST positions in a custom part, set `switch: [[P1A, P1B], [P2A, P2B]]` and `independent_switches: true`. Every contact pair must use distinct pins. The corresponding state names are `SW1.1` and `SW1.2` for an instance named `SW1`; `circuit.state("SW1.1,SW1.2")` selects both. The built-in C&K BD04 uses this model. Place it with `part :SW1, :ck_bd04, at: "e20"`; its four contacts occupy rows 20–23 across the center gap. The `PnA`/`PnB` labels are logical position-side names because the [C&K BD datasheet](https://www.littelfuse.com/assetdocs/littelfuse-ck-dip-bd-series-datasheet?assetguid=c1d4e4f2-7607-4309-afba-ad965b566d35) does not specify every terminal number in its drawing. Check the physical switch's marked position 1 and orientation before wiring it.
+
+`old_circuit.diff(new_circuit)` returns a hash of changed board, supply, component, label, and wire entries. Each value is `[before, after]`, with `nil` for an added or removed entry. The CLI `breadkit diff OLD NEW` prints the same changes.
 
 The core CLI provides `breadkit nets`, `breadkit parts`, and `breadkit ir`.
 
 Custom module pins can declare their kind with `type:` in the part YAML, for example `power`, `ground`, `clock`, `data`, `address`, or `interrupt`. The renderer colors typed pin markers and dims pins without a wire connection.
+For a rail-mounted supply with independent output selectors, see the [ShillehTek MB102 four-pin guide](MB102_POWER.md). This variant requires explicit rail-hole positions and jumper settings; its data file does not assume a universal MB102 contact layout.
+Custom part YAML may set `datasheet_url: https://example.com/part.pdf` to
+retain a source link in part listings and JSON IR. Use an actual HTTPS
+datasheet URL for a published part; URLs with embedded credentials are rejected.
+An individual pin may also declare `max_current: 0.012` for a 12 mA limit.
+Use a verified limit from that part's datasheet; pins without this field have
+no inferred current limit. The value is preserved in JSON IR for lint tools.
+For a pin explicitly named as `provides.positive`, DC analysis reports the
+source current under `REF.PIN`. Other GPIO output states remain unknown to the
+DC solver; `max_current` alone does not assign an output voltage.
+Use `type:` for new definitions; the legacy `role:` spelling is accepted and
+normalized to `type:`. A pin cannot declare both. Unknown part and pin keys,
+and unsupported pin types, are rejected when the definition is loaded.
 
 Assign the same `layer:` to wires and components to make them appear together in the interactive SVG layer controls. A layer may be a string or a list of strings when an item belongs to multiple views. Components without a layer remain visible in every view. Use `electrical: false, dashed: true` for an alternate connection that must not affect connectivity analysis.

data/exe/breadkit-lsp

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require "breadkit/lsp_server"
+
+options = { trusted_ruby: false }
+OptionParser.new do |parser|
+  parser.banner = "Usage: breadkit-lsp [--root DIRECTORY] [--trusted-ruby]"
+  parser.on("--root DIRECTORY") { |value| options[:root] = value }
+  parser.on("--trusted-ruby") { options[:trusted_ruby] = true }
+end.parse!
+Breadkit::LSPServer.new(**options).run

data/exe/breadkit-mcp

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "breadkit/mcp_server"
+
+unless ARGV.empty? || (ARGV.length == 2 && ARGV.first == "--root")
+  warn "Usage: breadkit-mcp [--root DIRECTORY]"
+  exit 2
+end
+
+root = ARGV.empty? ? Dir.pwd : ARGV.last
+Breadkit::MCPServer.new(root: root).run

data/lib/breadkit/analysis.rb

@@ -28,45 +28,70 @@ module Breadkit
       @parent[right] = left
       @rank[left] += 1 if @rank[left] == @rank[right]
     end
+
+    def snapshot
+      copy = dup
+      copy.instance_variable_set(:@parent, @parent.dup)
+      copy.instance_variable_set(:@rank, @rank.dup)
+      copy
+    end
   end
 
   class Circuit
     attr_reader :title, :board, :components, :wires, :supplies, :labels, :expectations,
-                :lint_disables, :diagnostics
+                :lint_disables, :diagnostics, :source_root, :steps
 
-    def initialize(title:, board:, components:, wires:, supplies:, labels:, expectations:, lint_disables:, diagnostics:)
+    def initialize(title:, board:, components:, wires:, supplies:, labels:, expectations:, lint_disables:, diagnostics:, steps: [], source_root: nil)
       @title, @board, @components, @wires, @supplies, @labels = title, board, components, wires, supplies, labels
       @expectations, @lint_disables, @diagnostics = expectations, lint_disables, diagnostics
+      @steps = steps
+      @source_root = source_root
       @net_cache, @net_index, @potential_cache = {}, {}, {}
     end
 
-    def states(mode = "single")
-      switches = components.values.select { |component| !Array(component.part.data["switch"]).empty? }
+    def states(mode = "single", budget: nil)
+      raise ArgumentError, "state budget must be a positive integer" if budget && (!budget.is_a?(Integer) || budget <= 0)
+
+      switches = switch_units
       return [State.new(name: nil, closed_switches: [])] if mode.to_s == "none" || switches.empty?
-      # ponytail: exhaustive state generation stops at 8 switches; use a configurable search budget for larger circuits.
-      if mode.to_s == "all" && switches.length <= 8
+      combinations = 1 << switches.length
+      raise ArgumentError, "#{combinations} switch states exceed budget #{budget}" if mode.to_s == "all" && budget && combinations > budget
+
+      # ponytail: calls without an explicit budget keep the legacy eight-switch fallback.
+      if mode.to_s == "all" && (budget ? combinations <= budget : switches.length <= 8)
         (0...(1 << switches.length)).map do |bits|
-          selected = switches.each_with_index.filter_map { |component, index| component if bits[index] == 1 }
-          closed = selected.flat_map { |component| Array(component.part.data["switch"]).map { |pair| [component, pair] } }
-          State.new(name: selected.empty? ? nil : selected.map(&:ref).join(","), closed_switches: closed)
+          selected = switches.each_with_index.filter_map { |unit, index| unit if bits[index] == 1 }
+          State.new(name: selected.empty? ? nil : selected.map(&:first).join(","), closed_switches: selected.flat_map(&:last))
         end
       else
-        singles = switches.map do |component|
-          pairs = Array(component.part.data["switch"]).map { |pair| [component, pair] }
-          State.new(name: component.ref, closed_switches: pairs)
+        singles = switches.map do |name, pairs|
+          State.new(name: name, closed_switches: pairs)
         end
         all_pairs = singles.flat_map(&:closed_switches)
-        singles << State.new(name: switches.map(&:ref).join(","), closed_switches: all_pairs) if mode.to_s == "all"
+        singles << State.new(name: switches.map(&:first).join(","), closed_switches: all_pairs) if mode.to_s == "all"
         [State.new(name: nil, closed_switches: [])] + singles
       end
     end
 
+    def state(name)
+      return nil unless name
+
+      names = name.split(",", -1)
+      units = switch_units.to_h
+      if names.uniq.length != names.length || names.any? { |unit| !units.key?(unit) }
+        raise ArgumentError, "unknown switch state #{name}"
+      end
+
+      State.new(name: name, closed_switches: names.flat_map { |unit| units.fetch(unit) })
+    end
+
     def nets(state = nil)
       state ||= State.new(name: nil, closed_switches: [])
       key = state_key(state)
       return @net_cache[key] if @net_cache.key?(key)
 
-      resolved = Connectivity.new(self).build(state)
+      @connectivity ||= Connectivity.new(self)
+      resolved = @connectivity.build(state)
       @net_index[key] = resolved.each_with_object({}) do |net, index|
         index[net.name] ||= net
         net.members.each do |member|
@@ -90,6 +115,17 @@ module Breadkit
       @potential_cache.fetch(state_key(state))
     end
 
+    def voltage_sources
+      supplies + components.values.flat_map do |component|
+        component.provided_sources.map do |source|
+          Supply.new(name: "#{component.ref}.#{source.fetch('positive')}", voltage: Value.parse(source.fetch("voltage")),
+                     plus: "#{component.ref}.#{source.fetch('positive')}",
+                     minus: "#{component.ref}.#{source.fetch('negative')}", location: component.location,
+                     isolated: false, voltage_range: nil)
+        end
+      end
+    end
+
     def net_of(reference, state = nil)
       text = reference.to_s
       nets(state)
@@ -101,6 +137,55 @@ module Breadkit
       IR::Writer.new.write(self)
     end
 
+    def boards
+      board.is_a?(BoardSet) ? board.boards : {}
+    end
+
+    def multi_board?
+      board.is_a?(BoardSet)
+    end
+
+    def diff(other)
+      raise ArgumentError, "expected a Breadkit::Circuit" unless other.is_a?(Circuit)
+
+      before, after = diff_items, other.diff_items
+      (before.keys | after.keys).sort.each_with_object({}) do |key, changes|
+        changes[key] = [before[key], after[key]] unless before[key] == after[key]
+      end
+    end
+
+    protected
+
+    def diff_items
+      items = if multi_board?
+        boards.to_h { |name, item| ["board #{name}", "#{item.definition.id}#{' (split rails)' if item.split_rails}"] }
+      else
+        { "board" => "#{board.definition.id}#{' (split rails)' if board.split_rails}" }
+      end
+      supplies.each do |supply|
+        voltage = supply.voltage_range ? supply.voltage_range.join("..") : supply.voltage
+        limit = supply.current_limit ? ", #{supply.current_limit} A limit" : ""
+        items["supply #{supply.name}"] = "#{voltage} V, #{supply.plus} to #{supply.minus}#{limit}"
+      end
+      labels.each { |label| items["label #{label.name}@#{label.at}"] = true }
+      components.each_value do |component|
+        pins = component.pins.values.map { |pin| "#{pin.name}=#{pin.hole_id || '-'}" }.join(", ")
+        attrs = component.attrs.map { |key, value| [key.to_s, value] }.sort_by(&:first).to_h
+        details = [component.part.id, component.value, pins]
+        details << "attrs=#{attrs.inspect}" unless attrs.empty?
+        details << "unused=#{component.unused.inspect}" unless component.unused.empty?
+        items["component #{component.ref}"] = details.compact.join(" ")
+      end
+      wires.each do |wire|
+        options = [wire.color, wire.route, wire.layer, wire.electrical, wire.dashed]
+        key = "wire #{[wire.from, wire.to].sort.join(' ↔ ')} #{options.inspect}"
+        items[key] = items.fetch(key, 0) + 1
+      end
+      items
+    end
+
+    public
+
     def shortest_path(terminal_a, terminal_b, state = nil)
       start, finish = hole_for_reference(terminal_a.to_s), hole_for_reference(terminal_b.to_s)
       return [] unless start && finish
@@ -146,6 +231,9 @@ module Breadkit
     end
 
     def node_for_reference(reference)
+      hole = board.hole(reference)
+      return "hole:#{hole.id}" if hole
+
       if reference.include?(".")
         prefix, pin = reference.split(".", 2)
         if components[prefix]
@@ -155,7 +243,6 @@ module Breadkit
         supply = supplies.find { |item| item.name == prefix }
         return "supply:#{reference}" if supply && %w[+ -].include?(pin)
       end
-      return "hole:#{board.hole(reference).id}" if board.hole(reference)
       "label:#{reference}" if labels.any? { |item| item.name == reference }
     rescue ArgumentError
       nil
@@ -163,7 +250,23 @@ module Breadkit
 
     private
 
+    def switch_units
+      components.values.flat_map do |component|
+        pairs = Array(component.part.data["switch"])
+        next [] if pairs.empty?
+
+        if component.part.data["independent_switches"]
+          pairs.each_with_index.map { |pair, index| ["#{component.ref}.#{index + 1}", [[component, pair]]] }
+        else
+          [[component.ref, pairs.map { |pair| [component, pair] }]]
+        end
+      end
+    end
+
     def hole_for_reference(reference)
+      hole = board.hole(reference)
+      return hole.id if hole
+
       if reference.include?(".")
         prefix, pin = reference.split(".", 2)
         supply = supplies.find { |item| item.name == prefix }
@@ -195,30 +298,18 @@ module Breadkit
   class Connectivity
     def initialize(circuit)
       @circuit = circuit
+      @uf = UnionFind.new
+      build_static_connections
+      @base_uf = @uf
+      @exposed_nodes = exposed_nodes
     end
 
     def build(state)
-      @uf = UnionFind.new
-      circuit.board.strips.each_value { |ids| ids.each_cons(2) { |a, b| @uf.union(hole_node(a), hole_node(b)) } }
-      circuit.components.each_value do |component|
-        component.pins.each_value { |pin| @uf.union(pin.node_id, hole_node(pin.hole_id)) if pin.hole_id }
-        Array(component.part.data["internal"]).each { |pair| join_pins(component, pair) }
-      end
-      circuit.wires.each do |wire|
-        next if wire.electrical == false
-
-        id = wire_node(wire.id)
-        @uf.union(id, endpoint_node(wire.from))
-        @uf.union(id, endpoint_node(wire.to))
-      end
-      circuit.supplies.each do |supply|
-        @uf.union(supply_node(supply.name, "+"), hole_node(supply.plus))
-        @uf.union(supply_node(supply.name, "-"), hole_node(supply.minus))
-      end
+      @uf = @base_uf.snapshot
       state.closed_switches.each { |component, pair| join_pins(component, pair) }
 
       groups = Hash.new { |hash, key| hash[key] = { members: [], holes: [], labels: [], supplies: [] } }
-      exposed_nodes.each do |node, member, kind|
+      @exposed_nodes.each do |node, member, kind|
         entry = groups[@uf.find(node)]
         entry[:members] << member if member
         entry[:holes] << node.delete_prefix("hole:") if kind == :hole
@@ -231,10 +322,14 @@ module Breadkit
       roots = groups.keys.select { |root| !groups[root][:members].empty? || !groups[root][:labels].empty? }
                    .sort_by { |root| order_for(groups[root][:holes]) }
       used_names = {}
+      unnamed_count = 0
       roots.map.with_index do |root, index|
         data = groups[root]
         chosen = data[:labels].first&.name || supply_name(data[:supplies])
-        chosen ||= "N#{roots.take(index + 1).count { |candidate| groups[candidate][:labels].empty? && groups[candidate][:supplies].empty? }}"
+        unless chosen
+          unnamed_count += 1
+          chosen = "N#{unnamed_count}"
+        end
         name = chosen
         if used_names[name]
           # Multiple nets can have the same label; retain deterministic unique display names.
@@ -252,6 +347,25 @@ module Breadkit
 
     attr_reader :circuit
 
+    def build_static_connections
+      circuit.board.strips.each_value { |ids| ids.each_cons(2) { |a, b| @uf.union(hole_node(a), hole_node(b)) } }
+      circuit.components.each_value do |component|
+        component.pins.each_value { |pin| @uf.union(pin.node_id, hole_node(pin.hole_id)) if pin.hole_id }
+        Array(component.part.data["internal"]).each { |pair| join_pins(component, pair) }
+      end
+      circuit.wires.each do |wire|
+        next if wire.electrical == false
+
+        id = wire_node(wire.id)
+        @uf.union(id, endpoint_node(wire.from))
+        @uf.union(id, endpoint_node(wire.to))
+      end
+      circuit.supplies.each do |supply|
+        @uf.union(supply_node(supply.name, "+"), hole_node(supply.plus))
+        @uf.union(supply_node(supply.name, "-"), hole_node(supply.minus))
+      end
+    end
+
     def exposed_nodes
       list = []
       circuit.board.holes.each_key { |id| list << [hole_node(id), nil, :hole] }
@@ -323,54 +437,60 @@ module Breadkit
     end
 
     def solve(state)
-      edges = circuit.supplies.map do |supply|
-        [supply, circuit.net_of("#{supply.name}.-", state), circuit.net_of("#{supply.name}.+", state)]
+      edges = circuit.voltage_sources.map do |supply|
+        [supply, circuit.net_of(supply.minus, state), circuit.net_of(supply.plus, state)]
       end
       values, conflicts = {}, []
       adjacency = Hash.new { |hash, key| hash[key] = [] }
       edges.each do |supply, from, to|
         next unless from && to
-        adjacency[from.name] << [supply, to.name, supply.voltage, "#{supply.name}.+"]
-        adjacency[to.name] << [supply, from.name, -supply.voltage, "#{supply.name}.-"]
+        adjacency[from.name] << [supply, to.name, supply.voltage, terminal_for(supply, "+")]
+        adjacency[to.name] << [supply, from.name, -supply.voltage, terminal_for(supply, "-")]
       end
-      ground = circuit.nets(state).find { |net| net.labels.include?("GND") }&.name
-      components, witnesses, seen_conflicts = [], {}, {}
+      ground_labels = Array(circuit.board.definition.data["ground_labels"] || %w[GND 0V VSS GROUND]).map(&:upcase)
+      ground = circuit.nets(state).find { |net| net.labels.any? { |label| ground_labels.include?(label.upcase) } }&.name
+      components, witnesses, witness_sources, seen_conflicts = [], {}, {}, {}
       starts = adjacency.keys
       starts = [ground, *(starts - [ground])] if starts.include?(ground)
       starts.each do |start|
         next if values.key?(start)
         components << start
         values[start] = 0.0
-        witnesses[start] = edges.lazy.filter_map do |supply, from, to|
-          if from&.name == start
-            "#{supply.name}.-"
-          elsif to&.name == start
-            "#{supply.name}.+"
-          end
-        end.first
+        origin, from = edges.find { |_supply, negative, positive| negative&.name == start || positive&.name == start }
+        witnesses[start] = terminal_for(origin, from&.name == start ? "-" : "+")
+        witness_sources[start] = origin
         queue = [start]
         until queue.empty?
           current = queue.shift
           adjacency[current].each do |supply, target, delta, terminal|
             proposed = values[current] + delta
             if values.key?(target)
-              next if (values[target] - proposed).abs <= 1e-9 || seen_conflicts[supply.name]
+              next if (values[target] - proposed).abs <= 1e-9
 
               first, second = witnesses[target], terminal
+              next if first == second
+              pair = [first, second].sort
+              next if seen_conflicts[pair]
               path = circuit.shortest_path(first, second, state)
               path_wires = circuit.wires.select { |wire| path.include?(wire.id) }
               conflicts << { supply: supply, net: target, expected: values[target], actual: proposed,
                              terminal_a: first, terminal_b: second, path: path,
-                             wires: path_wires.map(&:id), location: path_wires.max_by { |wire| wire.location&.line.to_i }&.location || supply.location }
-              seen_conflicts[supply.name] = true
+                             wires: path_wires.map(&:id), location: path_wires.max_by { |wire| wire.location&.line.to_i }&.location || supply.location,
+                             source_pair: [witness_sources[target].name, supply.name].sort }
+              seen_conflicts[pair] = true
             else
               values[target] = proposed
               witnesses[target] = terminal
+              witness_sources[target] = supply
               queue << target
             end
           end
         end
       end
+      # A wired short can be seen again on an already shared return or series junction.
+      wired_pairs = conflicts.filter_map { |item| item[:source_pair] unless item[:wires].empty? }
+      conflicts.reject! { |item| item[:wires].empty? && wired_pairs.include?(item[:source_pair]) }
+      conflicts.each { |item| item.delete(:source_pair) }
       values[ground] = 0.0 if ground && !values.key?(ground)
       PotentialResult.new(values: values, conflicts: conflicts, components: components)
     end
@@ -378,5 +498,9 @@ module Breadkit
     private
 
     attr_reader :circuit
+
+    def terminal_for(supply, side)
+      circuit.supplies.include?(supply) ? "#{supply.name}.#{side}" : (side == "+" ? supply.plus : supply.minus)
+    end
   end
 end