Spec: Circuit Diff/Versioning

Overview

Add the ability to compare two versions of a circuit visually and track changes over time, enabling users to understand what changed between saves, collaborate more effectively, and maintain design history.

Motivation

As circuits grow in complexity, it becomes difficult to remember what changed between editing sessions. When collaborating or reviewing designs, a visual diff showing added, removed, and modified components is invaluable. Version history also provides safety — users can revert to any previous state.

Requirements

Functional Requirements

1. File-Based Diff: Compare any two .dwm circuit files and highlight differences.
2. Visual Diff Overlay: Show added (green), removed (red), and modified (yellow) components on the canvas.
3. Change Summary: Text listing of all changes (components added/removed, wires changed, properties modified).
4. Version History (local): Auto-save versioned snapshots at configurable intervals or on explicit save.
5. Version Browser: UI to browse saved versions with timestamps and optional user comments.
6. Restore Version: Revert the circuit to any previous version.
7. Side-by-Side View: Optional split view showing both versions simultaneously.
8. Diff Scope: Diff covers components, wires, annotations, properties, and macro contents.
9. Change Navigation: "Next change" / "Previous change" buttons to jump between differences.
10. Export Diff Report: Save change summary as text/markdown for documentation.

Non-Functional Requirements

• Diff computation completes in under 2 seconds for circuits with up to 1000 components.
• Version history storage is space-efficient (delta-based, not full copies).
• Version history is stored alongside the circuit file (e.g., .dwm.history/ folder).

Design

Diff Algorithm

1. Parse both circuit files into component/wire/annotation lists.
2. Match elements by GUID (stable identity).
3. Classify each element:
   - Present in both → compare properties → Modified or Unchanged
   - Present only in A → Removed
   - Present only in B → Added
4. Generate DiffResult with categorized elements.

Data Model

public class CircuitDiff
{
    public List<DiffEntry> AddedComponents { get; }
    public List<DiffEntry> RemovedComponents { get; }
    public List<DiffEntry> ModifiedComponents { get; }
    public List<DiffEntry> AddedWires { get; }
    public List<DiffEntry> RemovedWires { get; }
    public List<PropertyChange> PropertyChanges { get; }
}

public class DiffEntry
{
    public Guid ElementId { get; }
    public string ElementType { get; }
    public string Name { get; }
    public DiffState State { get; }  // Added, Removed, Modified
}

public class CircuitVersion
{
    public int VersionNumber { get; }
    public DateTime Timestamp { get; }
    public string Comment { get; }
    public byte[] DeltaData { get; }  // Compressed diff from previous version
}

Version Storage

• Versions stored in <filename>.history/ directory alongside the .dwm file.
• Each version is a compressed delta (binary diff) from the previous version.
• Metadata file tracks version list with timestamps and comments.
• Configurable maximum versions to keep (default: 50).

Visual Overlay

• Diff highlighting rendered as a semi-transparent overlay on the canvas.
• Added elements: green tint + green border.
• Removed elements: red tint + dashed border (ghost rendering).
• Modified elements: yellow border + small change indicator icon.

Implementation Tasks

1. Implement circuit comparison algorithm (GUID-based matching).
2. Create CircuitDiff data model and diff computation engine.
3. Implement visual diff overlay rendering on canvas.
4. Create diff viewer UI (change summary panel, navigation buttons).
5. Implement local version history storage (delta-based).
6. Create version browser UI with timeline view.
7. Implement version restore functionality.
8. Add auto-versioning on save with configurable interval.
9. Implement side-by-side comparison view.
10. Add diff report export (markdown format).

Risks & Open Questions

• How to handle diffs when GUIDs are not stable (e.g., circuits created before GUID tracking)?
• Should version history be opt-in or always-on?
• Git integration: should this integrate with git for teams using source control?
• Performance of delta reconstruction for old versions (many deltas to apply)?

Priority

Medium-High — Valuable for iterative design and collaboration but not a blocker for basic usage.