Spec: Bus/Bundle Wires

Overview

Add multi-bit bus/bundle wire support to DigitalWorks, allowing users to connect components with grouped signal lines (e.g., 8-bit data bus, 16-bit address bus) instead of routing individual wires for each bit.

Motivation

Currently, every signal requires its own dedicated wire. Building circuits with multi-bit data paths (CPUs, memory interfaces, ALUs) becomes tedious and visually cluttered. Bus wires are a fundamental feature for scaling beyond simple gate-level designs.

Requirements

Functional Requirements

1. Bus Wire Creation: Users can draw a bus wire that represents N bits (configurable width: 1–64 bits).
2. Bus Pin Type: Components can define bus-typed pins (e.g., an 8-bit output port).
3. Bus Splitting (Fan-out): A splitter component breaks a bus into individual signal wires or sub-buses.
4. Bus Merging (Fan-in): A merger component combines individual wires or sub-buses into a single bus.
5. Bus Labeling: Buses display their width (e.g., /8) and optional name on the canvas.
6. Bus-to-Bus Connection: Buses of the same width can be connected directly.
7. Width Mismatch Detection: The simulation engine detects and reports width mismatches at compile/run time.
8. Bus Signal Values: During simulation, each bit in the bus carries its own High/Low/Floating state.
9. Bus Probing: Logic probes and numeric output can display bus values in binary, hex, or decimal.
10. Persistence: Bus wires and their configurations are saved/loaded in the .dwm circuit file format.

Non-Functional Requirements

• Bus rendering must be visually distinct from single wires (thicker line, different style).
• Performance: Buses should not degrade simulation performance; internally they are still individual signals.
• Backward compatibility: Existing circuit files without buses must load without errors.

Design

Domain Model Changes

BusWire : Wire
├── Width: int (number of bits)
├── Name: string (optional label)
└── Signals: Signal[] (one per bit)

BusPin : Pin
├── Width: int
└── BitSignals: Signal[]

BusSplitter : Component
├── InputBusPin (N bits)
└── OutputPins[] (individual or sub-bus)

BusMerger : Component
├── InputPins[] (individual or sub-bus)
└── OutputBusPin (N bits)

Simulation Engine Impact

• SimulationStepEngine must propagate bus signals as arrays rather than single values.
• Event-driven mode: a bus change event fires when any bit in the bus changes.
• Propagation delay applies uniformly to all bits in a bus.

Rendering

• Bus wires rendered with a thicker stroke (3–4px vs 1–2px for regular wires).
• Diagonal slash with bit-width number at connection points.
• Color coding: bus wires use a distinct color (configurable in theme).

Routing

• AutoRouter must handle bus wire routing with wider clearance.
• Bus wires follow Manhattan routing like regular wires.

UI/UX

• Toolbox gains a "Bus Wire" drawing tool alongside the existing wire tool.
• Right-click on a bus wire opens properties dialog to set width and name.
• Splitter/Merger components are available in the toolbox under a "Bus" category.
• Status bar shows bus width when a bus wire is selected.

Implementation Tasks

1. Add BusPin and BusWire classes to DigitalWorks.Core/Models/.
2. Add BusSplitter and BusMerger to DigitalWorks.Core/Components/.
3. Extend SimulationStepEngine to handle bus signal propagation.
4. Add bus wire rendering in EditorCanvas (thick line, width label).
5. Extend AutoRouter for bus wire clearance.
6. Add bus-related shape definitions (JSON) for splitter/merger.
7. Update file serialization to support bus wire metadata.
8. Add bus probe display modes (binary, hex, decimal).
9. Add width mismatch validation and error reporting.
10. Update toolbox and property dialogs for bus operations.

Risks & Open Questions

• Should buses support mixed-width connections with automatic zero-extension or truncation?
• How do buses interact with existing macros (sub-circuits)? Do macro pins support bus width?
• Performance impact of array-based signal propagation on large buses (32/64 bit)?

Priority

High — Unlocks realistic multi-bit circuit design.