# ViceSharp Iteration Roadmap

## Iteration 0: Foundations ✅ COMPLETED

**Goal:** Runnable scaffolding with zero emulation.

- Solution structure and build system (Nuke)
- 33+ public interfaces in ViceSharp.Abstractions
- Roslyn source generator for device registration
- ROM fetch tool
- CI/CD target definitions (the historical Azure pipelines are retired; GitHub `origin` is the source of truth)
- Comprehensive documentation and GraphRAG knowledge base
- Determinism test harness (empty machine, bit-exact snapshots)

**Exit criteria:** `dotnet test` passes, the managed console app starts and exits cleanly, all docs written.

## Iteration 1: C64 (MVP) ✅ COMPLETED

**Goal:** Playable Commodore 64 emulation.

**Status:** The managed C64 core now runs in cycle-exact lockstep with VICE's
`x64sc`. An automated harness drives both the managed core and the native
`x64sc` engine and diffs them at per-cycle checkpoints (CPU + bus, VIC-II
raster/sprite state, CIA, SID register reads); 322 x64sc variant lockstep
cases pass across the no-cartridge C64 family (C64 / C64C / SX-64, PAL + NTSC)
at multi-frame depth, on top of the 335-case lockstep/checkpoint gate and
100k-cycle parity. Gate at the v1.0.2 release: 2594 passed, 21 skipped,
0 failed (2615 total, standard category filter).

- MOS 6510 CPU - full instruction set, cycle-accurate
- VIC-II (6567/6569) - raster engine, sprites, border, badlines, DMA stealing
- SID (6581/8580) - 3 voices, filters, envelope, ring mod, sync
- CIA x2 (6526) - timers, TOD, keyboard matrix, joystick, IEC serial
- PLA (906114) - memory banking, address decoding
- 1541 drive emulation - GCR, IEC bus, DOS
- Datasette - TAP playback, motor control
- Cartridge support - Ocean, EasyFlash, Action Replay, Final Cartridge III
- Keyboard, joystick, mouse, lightpen input
- Media capture - screenshots (PNG), video (MP4 via FFmpeg), audio (WAV)
- Monitor/debugger - disassembly, breakpoints, memory view, watch
- Save/load state snapshots
- Avalonia desktop UI

**Exit criteria:** Loads and runs commercial C64 software, passes Klaus Dormann test suite, SID audio plays correctly, save/load state round-trips deterministically.

## Iteration 2: VIC-20

**Goal:** Add VIC-20 as a second architecture.

**Status (2026-08-11):** Core complete on `main`. Every-cycle native lockstep green for multi-second PAL and NTSC. READY present-path, expansion UX, FE3 flash040 command FSM, and xvic visible-frame capture landed.

- MOS 6502 CPU (reuse 6510 core minus I/O port)
- VIC-I (6560/6561) character-mode video (`Mos6561`) with PAL/NTSC timing
- VIA x2 (shared `Via6522`) at $9110 NMI / $9120 IRQ; keyboard matrix + joystick glue
- VIA timer CPU `Read` uses pre-Tick bus-visible counters (VICE LOAD at `maincpu_clk` before `CLK_INC`); peeks stay post-Tick
- Color RAM 4-bit + V-bus open-bus high nibble (`Vic20ColorRam` / `BasicBus`)
- 5KB base RAM + expansion packs; Avalonia Settings wrap BLK0/1/2/3/5 toggles (product path)
- Cartridge map: BLK PRG/raw + FE3 / Ultimem / Mega-Cart attach; Flash Cart Builder (`docs/FlashCart-Builder.md`); FE3 MODE_FLASH uses VICE TYPE_B erase-cycle budgets; dirty FE3/Ultimem flash and Mega-Cart NVRAM persist atomically on detach
- READY present geometry Exact-scoped: VICE viewport `first_x` crop (PAL 48), L+R borders, paper origin
- xvic pixel FB capture: PAL normal 448x284 BGRA; full SequenceEqual ratchet open
- Default drive unit 8 = **1540** (`DriveModel.C1540`); C64 remains 1541
- Launcher `xvic` topology; host session create; supported product shells Avalonia + Console
- Native oracle: `native/vice_xvic.dll` via `ViceNative.CreateInstance("vic20"|"vic20ntsc")`
- Every-cycle A/X/Y/S/P/PC lockstep vs xvic:
  - **PAL 10 s:** 11_084_050 cycles (`EveryCycle_CpuRegs_Match_TenSecondPal`)
  - **NTSC 10 s:** 10_227_270 cycles (`EveryCycle_CpuRegs_Match_TenSecondNtsc`)
  - Env: `VICESHARP_LOCKSTEP_10S=1` (and `VICESHARP_LOCKSTEP_2S=1` for 2 s PAL)
  - Receipts: `docs/receipts-lockstep-10s-2026-08-06.txt`, `docs/receipts-lockstep-10s-ntsc-2026-08-06.txt`
- Audit matrix: `docs/audit-vic20-vs-vice-2026-08-07.md` (Exact only for named rules)

**Exit criteria:** Runs VIC-20 software, architecture switching works at runtime, and multi-second every-cycle register lockstep vs native xvic. Met for READY fingerprint, character frames, session factory, focused `FullyQualifiedName~Vic20` gates, and the 10 s PAL + NTSC diverge probes. Timed FE3 erase, cartridge write-back, deterministic batched VIC-I sound, and scoped pixel-index parity are also covered. Remaining polish: full-canvas BGRA parity, input E2E, the native snapshot write hang, niche carts/peripherals, and zip virtual media (`PLAN-ZIPMEDIA-001`); see `HANDOFF.md`.

## Iteration 3: C128

**Goal:** Add Commodore 128 with dual-CPU support.

- MOS 8502 CPU (2 MHz mode)
- Z80 coprocessor (CP/M mode)
- VIC-IIe (6569 superset with 2 MHz support)
- VDC (8563) - 80-column display
- MMU - extended banking, shared RAM
- 1571/1581 drive support
- C128/C64 mode switching

**Exit criteria:** Boots in C128 mode, switches to C64 mode, CP/M mode starts.

## Iteration 4: PET

**Goal:** Add Commodore PET family.

- MOS 6502 CPU
- PIA (6520) and VIA (6522) I/O
- CRTC (6545) video controller
- IEEE-488 bus
- PET keyboard (business/graphics)
- PET 2001, 3032, 4032, 8032 variants

## Iteration 5: Plus/4 and C16

**Goal:** Add TED-based machines.

- MOS 7501/8501 CPU
- TED (7360/8360) - combined video+audio+timer
- Plus/4 built-in software ROM
- C16 reduced memory model

## Future Iterations

- **Performance:** SIMD rendering, JIT CPU core, GPU-accelerated video
- **Networking:** RS-232 emulation, TCP/IP stack (RR-Net/TFE)
- **Peripherals:** REU, GeoRAM, IDE64, SD2IEC
- **Platform:** WebAssembly target, mobile (MAUI)
- **Community:** Plugin system, Lua scripting, ROM repository integration