From 5a430975630503e0021ecf05d7111275d9c663f1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 13 Nov 2025 21:31:56 +0000
Subject: [PATCH] feat(savestate): implement complete save state features for
 CGB and APU
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the remaining savestate features to achieve complete emulator
state preservation:

**WRAM Banking (CGB)**
- Add SVBK register (0xFF70) to CgbController for WRAM bank switching
- Expand WRAM from 8KB to 32KB (8 banks × 4KB each)
- Bank 0 (0xC000-0xCFFF) is fixed, banks 1-7 (0xD000-0xDFFF) are switchable
- SavestateManager now saves all 8 WRAM banks separately
- Maintains backward compatibility with 8KB flat format

**OAM DMA Transfer State**
- Add getter/setter methods for DMA transfer progress
- Save: dmaActive, dmaProgress, dmaDelay, dmaSource
- Preserves mid-frame DMA state (rare edge case)

**HDMA Transfer State**
- Add getter/setter methods for HDMA transfer state
- Save: hdmaActive, hblankMode, remainingBlocks
- Preserves H-Blank DMA progress for CGB games

**APU Channel Internal State**
- Save complete internal state for all 4 audio channels:
  - Channel 1: lengthCounter, currentVolume, envelopeTimer, frequencyTimer,
    dutyPosition, enabled, dacEnabled, sweepTimer, sweepShadow, sweepEnabled
  - Channel 2: lengthCounter, currentVolume, envelopeTimer, frequencyTimer,
    dutyPosition, enabled, dacEnabled
  - Channel 3: lengthCounter, frequencyTimer, samplePosition, enabled, dacEnabled
  - Channel 4: lengthCounter, currentVolume, envelopeTimer, frequencyTimer,
    enabled, dacEnabled, **lfsr** (critical for noise pattern preservation)
- Add channel accessor methods to Apu class
- Eliminates audio glitches and timing drift after savestate restore

**SavestateManager Updates**
- Bump version from 1.0.0 to 1.1.0
- Maintain backward compatibility with version 1.0.0 savestates
- Update serialization to include all new state
- Add serializeOamDma/deserializeOamDma methods
- Add serializeHdma/deserializeHdma methods
- Enhance serializeApu/deserializeApu with channel state

**Testing**
- Update CgbControllerTest to pass Wram instance to constructor
- Update SavestateManagerTest to expect version 1.1.0
- Fix Wram address masking for backward compatibility
- All unit tests passing

This completes the savestate implementation with full accuracy for:
✅ WRAM Banking (CGB) - All 8 banks × 4KB
✅ OAM DMA Transfer Progress
✅ HDMA Transfer State
✅ Full APU Channel Internal State

Closes the savestate feature gap and enables perfect emulator state
restoration for both DMG and CGB games.
---
 src/Apu/Apu.php                               |  40 +++
 src/Apu/Channel/Channel1.php                  | 102 ++++++++
 src/Apu/Channel/Channel2.php                  |  72 ++++++
 src/Apu/Channel/Channel3.php                  |  52 ++++
 src/Apu/Channel/Channel4.php                  |  72 ++++++
 src/Dma/HdmaController.php                    |  60 +++++
 src/Dma/OamDma.php                            |  80 ++++++
 src/Emulator.php                              |  22 +-
 src/Memory/Wram.php                           |  91 ++++++-
 src/Savestate/SavestateManager.php            | 236 ++++++++++++++++--
 src/System/CgbController.php                  |   6 +
 tests/Unit/Savestate/SavestateManagerTest.php |   2 +-
 tests/Unit/System/CgbControllerTest.php       |   5 +-
 13 files changed, 804 insertions(+), 36 deletions(-)

diff --git a/src/Apu/Apu.php b/src/Apu/Apu.php
index 7d9a2e5..4feacc1 100644
--- a/src/Apu/Apu.php
+++ b/src/Apu/Apu.php
@@ -471,4 +471,44 @@ public function setWaveRam(array $waveRam): void
             $this->channel3->writeWaveRam($i, $waveRam[$i]);
         }
     }
+
+    /**
+     * Get Channel 1 (for savestate serialization).
+     *
+     * @return Channel\Channel1
+     */
+    public function getChannel1(): Channel\Channel1
+    {
+        return $this->channel1;
+    }
+
+    /**
+     * Get Channel 2 (for savestate serialization).
+     *
+     * @return Channel\Channel2
+     */
+    public function getChannel2(): Channel\Channel2
+    {
+        return $this->channel2;
+    }
+
+    /**
+     * Get Channel 3 (for savestate serialization).
+     *
+     * @return Channel\Channel3
+     */
+    public function getChannel3(): Channel\Channel3
+    {
+        return $this->channel3;
+    }
+
+    /**
+     * Get Channel 4 (for savestate serialization).
+     *
+     * @return Channel\Channel4
+     */
+    public function getChannel4(): Channel\Channel4
+    {
+        return $this->channel4;
+    }
 }
diff --git a/src/Apu/Channel/Channel1.php b/src/Apu/Channel/Channel1.php
index 267b799..5a0991b 100644
--- a/src/Apu/Channel/Channel1.php
+++ b/src/Apu/Channel/Channel1.php
@@ -294,4 +294,106 @@ public function disable(): void
     {
         $this->enabled = false;
     }
+
+    // Savestate serialization methods
+
+    public function getLengthCounter(): int
+    {
+        return $this->lengthCounter;
+    }
+
+    public function getCurrentVolume(): int
+    {
+        return $this->currentVolume;
+    }
+
+    public function getEnvelopeTimer(): int
+    {
+        return $this->envelopeTimer;
+    }
+
+    public function getFrequencyTimer(): int
+    {
+        return $this->frequencyTimer;
+    }
+
+    public function getDutyPosition(): int
+    {
+        return $this->dutyPosition;
+    }
+
+    public function getEnabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function getSweepTimer(): int
+    {
+        return $this->sweepTimer;
+    }
+
+    public function getSweepShadow(): int
+    {
+        return $this->sweepShadow;
+    }
+
+    public function getSweepEnabled(): bool
+    {
+        return $this->sweepEnabled;
+    }
+
+    public function getDacEnabled(): bool
+    {
+        return $this->dacEnabled;
+    }
+
+    public function setLengthCounter(int $value): void
+    {
+        $this->lengthCounter = $value;
+    }
+
+    public function setCurrentVolume(int $value): void
+    {
+        $this->currentVolume = $value;
+    }
+
+    public function setEnvelopeTimer(int $value): void
+    {
+        $this->envelopeTimer = $value;
+    }
+
+    public function setFrequencyTimer(int $value): void
+    {
+        $this->frequencyTimer = $value;
+    }
+
+    public function setDutyPosition(int $value): void
+    {
+        $this->dutyPosition = $value;
+    }
+
+    public function setEnabled(bool $value): void
+    {
+        $this->enabled = $value;
+    }
+
+    public function setSweepTimer(int $value): void
+    {
+        $this->sweepTimer = $value;
+    }
+
+    public function setSweepShadow(int $value): void
+    {
+        $this->sweepShadow = $value;
+    }
+
+    public function setSweepEnabled(bool $value): void
+    {
+        $this->sweepEnabled = $value;
+    }
+
+    public function setDacEnabled(bool $value): void
+    {
+        $this->dacEnabled = $value;
+    }
 }
diff --git a/src/Apu/Channel/Channel2.php b/src/Apu/Channel/Channel2.php
index 7bdf7b3..0a6aac2 100644
--- a/src/Apu/Channel/Channel2.php
+++ b/src/Apu/Channel/Channel2.php
@@ -215,4 +215,76 @@ public function disable(): void
     {
         $this->enabled = false;
     }
+
+    // Savestate serialization methods
+
+    public function getLengthCounter(): int
+    {
+        return $this->lengthCounter;
+    }
+
+    public function getCurrentVolume(): int
+    {
+        return $this->currentVolume;
+    }
+
+    public function getEnvelopeTimer(): int
+    {
+        return $this->envelopeTimer;
+    }
+
+    public function getFrequencyTimer(): int
+    {
+        return $this->frequencyTimer;
+    }
+
+    public function getDutyPosition(): int
+    {
+        return $this->dutyPosition;
+    }
+
+    public function getEnabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function getDacEnabled(): bool
+    {
+        return $this->dacEnabled;
+    }
+
+    public function setLengthCounter(int $value): void
+    {
+        $this->lengthCounter = $value;
+    }
+
+    public function setCurrentVolume(int $value): void
+    {
+        $this->currentVolume = $value;
+    }
+
+    public function setEnvelopeTimer(int $value): void
+    {
+        $this->envelopeTimer = $value;
+    }
+
+    public function setFrequencyTimer(int $value): void
+    {
+        $this->frequencyTimer = $value;
+    }
+
+    public function setDutyPosition(int $value): void
+    {
+        $this->dutyPosition = $value;
+    }
+
+    public function setEnabled(bool $value): void
+    {
+        $this->enabled = $value;
+    }
+
+    public function setDacEnabled(bool $value): void
+    {
+        $this->dacEnabled = $value;
+    }
 }
diff --git a/src/Apu/Channel/Channel3.php b/src/Apu/Channel/Channel3.php
index ec236d6..7555c4a 100644
--- a/src/Apu/Channel/Channel3.php
+++ b/src/Apu/Channel/Channel3.php
@@ -238,4 +238,56 @@ public function disable(): void
     {
         $this->enabled = false;
     }
+
+    // Savestate serialization methods
+
+    public function getLengthCounter(): int
+    {
+        return $this->lengthCounter;
+    }
+
+    public function getFrequencyTimer(): int
+    {
+        return $this->frequencyTimer;
+    }
+
+    public function getSamplePosition(): int
+    {
+        return $this->samplePosition;
+    }
+
+    public function getEnabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function getDacEnabled(): bool
+    {
+        return $this->dacEnabled;
+    }
+
+    public function setLengthCounter(int $value): void
+    {
+        $this->lengthCounter = $value;
+    }
+
+    public function setFrequencyTimer(int $value): void
+    {
+        $this->frequencyTimer = $value;
+    }
+
+    public function setSamplePosition(int $value): void
+    {
+        $this->samplePosition = $value;
+    }
+
+    public function setEnabled(bool $value): void
+    {
+        $this->enabled = $value;
+    }
+
+    public function setDacEnabled(bool $value): void
+    {
+        $this->dacEnabled = $value;
+    }
 }
diff --git a/src/Apu/Channel/Channel4.php b/src/Apu/Channel/Channel4.php
index 3d53ebb..b5c2a97 100644
--- a/src/Apu/Channel/Channel4.php
+++ b/src/Apu/Channel/Channel4.php
@@ -247,4 +247,76 @@ public function disable(): void
     {
         $this->enabled = false;
     }
+
+    // Savestate serialization methods
+
+    public function getLengthCounter(): int
+    {
+        return $this->lengthCounter;
+    }
+
+    public function getCurrentVolume(): int
+    {
+        return $this->currentVolume;
+    }
+
+    public function getEnvelopeTimer(): int
+    {
+        return $this->envelopeTimer;
+    }
+
+    public function getFrequencyTimer(): int
+    {
+        return $this->frequencyTimer;
+    }
+
+    public function getEnabled(): bool
+    {
+        return $this->enabled;
+    }
+
+    public function getDacEnabled(): bool
+    {
+        return $this->dacEnabled;
+    }
+
+    public function getLfsr(): int
+    {
+        return $this->lfsr;
+    }
+
+    public function setLengthCounter(int $value): void
+    {
+        $this->lengthCounter = $value;
+    }
+
+    public function setCurrentVolume(int $value): void
+    {
+        $this->currentVolume = $value;
+    }
+
+    public function setEnvelopeTimer(int $value): void
+    {
+        $this->envelopeTimer = $value;
+    }
+
+    public function setFrequencyTimer(int $value): void
+    {
+        $this->frequencyTimer = $value;
+    }
+
+    public function setEnabled(bool $value): void
+    {
+        $this->enabled = $value;
+    }
+
+    public function setDacEnabled(bool $value): void
+    {
+        $this->dacEnabled = $value;
+    }
+
+    public function setLfsr(int $value): void
+    {
+        $this->lfsr = $value & 0x7FFF; // Keep to 15 bits
+    }
 }
diff --git a/src/Dma/HdmaController.php b/src/Dma/HdmaController.php
index d95be6b..8c6d7d9 100644
--- a/src/Dma/HdmaController.php
+++ b/src/Dma/HdmaController.php
@@ -200,4 +200,64 @@ public function onHBlank(): void
             $this->hdmaActive = false;
         }
     }
+
+    /**
+     * Get HDMA active state (for savestate serialization).
+     *
+     * @return bool True if HDMA is active
+     */
+    public function getHdmaActive(): bool
+    {
+        return $this->hdmaActive;
+    }
+
+    /**
+     * Get H-Blank mode state (for savestate serialization).
+     *
+     * @return bool True if in H-Blank mode
+     */
+    public function getHblankMode(): bool
+    {
+        return $this->hblankMode;
+    }
+
+    /**
+     * Get remaining blocks (for savestate serialization).
+     *
+     * @return int Number of 16-byte blocks remaining
+     */
+    public function getRemainingBlocks(): int
+    {
+        return $this->remainingBlocks;
+    }
+
+    /**
+     * Set HDMA active state (for savestate deserialization).
+     *
+     * @param bool $active True if HDMA is active
+     */
+    public function setHdmaActive(bool $active): void
+    {
+        $this->hdmaActive = $active;
+    }
+
+    /**
+     * Set H-Blank mode state (for savestate deserialization).
+     *
+     * @param bool $mode True if in H-Blank mode
+     */
+    public function setHblankMode(bool $mode): void
+    {
+        $this->hblankMode = $mode;
+    }
+
+    /**
+     * Set remaining blocks (for savestate deserialization).
+     *
+     * @param int $blocks Number of 16-byte blocks remaining
+     */
+    public function setRemainingBlocks(int $blocks): void
+    {
+        $this->remainingBlocks = $blocks;
+    }
 }
diff --git a/src/Dma/OamDma.php b/src/Dma/OamDma.php
index 2a3eeb7..0c2cd7d 100644
--- a/src/Dma/OamDma.php
+++ b/src/Dma/OamDma.php
@@ -165,4 +165,84 @@ public function tick(int $cycles): void
             }
         }
     }
+
+    /**
+     * Get DMA active state (for savestate serialization).
+     *
+     * @return bool True if DMA is active
+     */
+    public function getDmaActive(): bool
+    {
+        return $this->dmaActive;
+    }
+
+    /**
+     * Get DMA progress (for savestate serialization).
+     *
+     * @return int Current byte being transferred (0-159)
+     */
+    public function getDmaProgress(): int
+    {
+        return $this->dmaProgress;
+    }
+
+    /**
+     * Get DMA delay (for savestate serialization).
+     *
+     * @return int Startup delay in M-cycles
+     */
+    public function getDmaDelay(): int
+    {
+        return $this->dmaDelay;
+    }
+
+    /**
+     * Get DMA source address (for savestate serialization).
+     *
+     * @return int Source address for DMA transfer
+     */
+    public function getDmaSource(): int
+    {
+        return $this->dmaSource;
+    }
+
+    /**
+     * Set DMA active state (for savestate deserialization).
+     *
+     * @param bool $active True if DMA is active
+     */
+    public function setDmaActive(bool $active): void
+    {
+        $this->dmaActive = $active;
+    }
+
+    /**
+     * Set DMA progress (for savestate deserialization).
+     *
+     * @param int $progress Current byte being transferred (0-159)
+     */
+    public function setDmaProgress(int $progress): void
+    {
+        $this->dmaProgress = $progress;
+    }
+
+    /**
+     * Set DMA delay (for savestate deserialization).
+     *
+     * @param int $delay Startup delay in M-cycles
+     */
+    public function setDmaDelay(int $delay): void
+    {
+        $this->dmaDelay = $delay;
+    }
+
+    /**
+     * Set DMA source address (for savestate deserialization).
+     *
+     * @param int $source Source address for DMA transfer
+     */
+    public function setDmaSource(int $source): void
+    {
+        $this->dmaSource = $source;
+    }
 }
diff --git a/src/Emulator.php b/src/Emulator.php
index 9ce6e0e..b7d9826 100644
--- a/src/Emulator.php
+++ b/src/Emulator.php
@@ -197,9 +197,9 @@ private function initializeSystem(): void
         $this->bus->attachIoDevice($this->hdma, 0xFF51, 0xFF52, 0xFF53, 0xFF54, 0xFF55);
 
         // Create CGB controller
-        $this->cgb = new CgbController($vram, $isCgbMode);
-        // CGB registers: KEY0, KEY1, VBK, RP, OPRI
-        $this->bus->attachIoDevice($this->cgb, 0xFF4C, 0xFF4D, 0xFF4F, 0xFF56, 0xFF6C);
+        $this->cgb = new CgbController($vram, $wram, $isCgbMode);
+        // CGB registers: KEY0, KEY1, VBK, RP, OPRI, SVBK
+        $this->bus->attachIoDevice($this->cgb, 0xFF4C, 0xFF4D, 0xFF4F, 0xFF56, 0xFF6C, 0xFF70);
 
         // Create joypad
         $this->joypad = new Joypad($interruptController);
@@ -676,6 +676,22 @@ public function getApu(): ?Apu
         return $this->apu;
     }
 
+    /**
+     * Get the OAM DMA controller.
+     */
+    public function getOamDma(): ?\Gb\Dma\OamDma
+    {
+        return $this->oamDma;
+    }
+
+    /**
+     * Get the HDMA controller.
+     */
+    public function getHdma(): ?\Gb\Dma\HdmaController
+    {
+        return $this->hdma;
+    }
+
     /**
      * Save the current emulator state to a file.
      *
diff --git a/src/Memory/Wram.php b/src/Memory/Wram.php
index 474764e..d4c43b8 100644
--- a/src/Memory/Wram.php
+++ b/src/Memory/Wram.php
@@ -10,20 +10,26 @@
  * Working RAM (WRAM)
  *
  * 8KB of working RAM mapped to 0xC000-0xDFFF.
- * In DMG mode: Single 8KB bank
- * In CGB mode: Bank 0 (0xC000-0xCFFF) + switchable banks 1-7 (0xD000-0xDFFF)
+ * In DMG mode: Single 8KB bank (only bank 0 and 1 used)
+ * In CGB mode: Bank 0 (0xC000-0xCFFF) fixed + switchable banks 1-7 (0xD000-0xDFFF)
  *
- * For now, implements DMG-style 8KB WRAM. CGB bank switching will be added later.
+ * Total: 8 banks × 4KB = 32KB
  */
 final class Wram implements DeviceInterface
 {
-    /** @var array<int, int> Working RAM storage (8KB = 8192 bytes) */
-    private array $ram;
+    /** @var array<int, array<int, int>> Working RAM storage (8 banks × 4KB) */
+    private array $banks;
+
+    /** @var int Current bank selected for 0xD000-0xDFFF (1-7) */
+    private int $currentBank = 1;
 
     public function __construct()
     {
-        // Initialize 8KB of RAM with 0x00
-        $this->ram = array_fill(0, 8192, 0x00);
+        // Initialize 8 banks of 4KB each
+        $this->banks = [];
+        for ($bank = 0; $bank < 8; $bank++) {
+            $this->banks[$bank] = array_fill(0, 4096, 0x00);
+        }
     }
 
     /**
@@ -34,8 +40,17 @@ public function __construct()
      */
     public function readByte(int $address): int
     {
-        $offset = $address & 0x1FFF; // Mask to 8KB
-        return $this->ram[$offset];
+        // Mask to 8KB for backward compatibility
+        $address = $address & 0x1FFF;
+
+        if ($address < 0x1000) {
+            // 0xC000-0xCFFF: Bank 0 (fixed)
+            return $this->banks[0][$address];
+        } else {
+            // 0xD000-0xDFFF: Switchable bank (1-7)
+            $offset = $address - 0x1000;
+            return $this->banks[$this->currentBank][$offset];
+        }
     }
 
     /**
@@ -46,7 +61,61 @@ public function readByte(int $address): int
      */
     public function writeByte(int $address, int $value): void
     {
-        $offset = $address & 0x1FFF; // Mask to 8KB
-        $this->ram[$offset] = $value & 0xFF;
+        // Mask to 8KB for backward compatibility
+        $address = $address & 0x1FFF;
+        $value = $value & 0xFF;
+
+        if ($address < 0x1000) {
+            // 0xC000-0xCFFF: Bank 0 (fixed)
+            $this->banks[0][$address] = $value;
+        } else {
+            // 0xD000-0xDFFF: Switchable bank (1-7)
+            $offset = $address - 0x1000;
+            $this->banks[$this->currentBank][$offset] = $value;
+        }
+    }
+
+    /**
+     * Get current bank number (for savestate serialization).
+     *
+     * @return int Current bank (1-7)
+     */
+    public function getCurrentBank(): int
+    {
+        return $this->currentBank;
+    }
+
+    /**
+     * Set current bank number.
+     *
+     * @param int $bank Bank number (0-7, but 0 is treated as 1)
+     */
+    public function setCurrentBank(int $bank): void
+    {
+        // Bank 0 is treated as bank 1
+        $this->currentBank = ($bank & 0x07) === 0 ? 1 : ($bank & 0x07);
+    }
+
+    /**
+     * Get all bank data (for savestate serialization).
+     *
+     * @return array<int, array<int, int>> All 8 banks
+     */
+    public function getAllBanks(): array
+    {
+        return $this->banks;
+    }
+
+    /**
+     * Set bank data (for savestate deserialization).
+     *
+     * @param int $bankNumber Bank number (0-7)
+     * @param array<int, int> $data Bank data (4096 bytes)
+     */
+    public function setBankData(int $bankNumber, array $data): void
+    {
+        if ($bankNumber >= 0 && $bankNumber < 8) {
+            $this->banks[$bankNumber] = $data;
+        }
     }
 }
diff --git a/src/Savestate/SavestateManager.php b/src/Savestate/SavestateManager.php
index c33f8e5..f54841c 100644
--- a/src/Savestate/SavestateManager.php
+++ b/src/Savestate/SavestateManager.php
@@ -13,22 +13,23 @@
  * allowing users to save and restore their game progress instantly.
  *
  * Format: JSON (human-readable, debuggable)
- * Version: 1.0.0
+ * Version: 1.1.0
  *
  * Savestate includes:
  * - CPU registers (AF, BC, DE, HL, SP, PC, IME, halted, stopped)
- * - Memory: VRAM, WRAM, HRAM, OAM, cartridge RAM
+ * - Memory: VRAM (both banks), WRAM (all 8 banks), HRAM, OAM, cartridge RAM
  * - PPU state: mode, cycle count, LY, scroll registers, palettes
- * - APU state: channel registers, frame sequencer position
+ * - APU state: channel registers, frame sequencer, channel internal state
  * - Timer state: DIV, TIMA, TMA, TAC
  * - Interrupt state: IF, IE
  * - Cartridge state: current ROM/RAM banks
  * - RTC state (if MBC3)
+ * - DMA state: OAM DMA and HDMA progress
  * - Clock: total cycle count
  */
 final class SavestateManager
 {
-    private const VERSION = '1.0.0';
+    private const VERSION = '1.1.0';
     private const MAGIC = 'PHPBOY_SAVESTATE';
 
     private Emulator $emulator;
@@ -106,6 +107,8 @@ public function serialize(): array
 
         $cgbController = $this->emulator->getCgbController();
         $apu = $this->emulator->getApu();
+        $oamDma = $this->emulator->getOamDma();
+        $hdma = $this->emulator->getHdma();
 
         return [
             'magic' => self::MAGIC,
@@ -119,6 +122,8 @@ public function serialize(): array
             'interrupts' => $interruptController !== null ? $this->serializeInterrupts($interruptController) : null,
             'cgb' => $cgbController !== null ? $this->serializeCgb($cgbController) : null,
             'apu' => $apu !== null ? $this->serializeApu($apu) : null,
+            'oamDma' => $oamDma !== null ? $this->serializeOamDma($oamDma) : null,
+            'hdma' => $hdma !== null ? $this->serializeHdma($hdma) : null,
             'clock' => [
                 'cycles' => $clock->getCycles(),
             ],
@@ -184,6 +189,18 @@ public function deserialize(array $state): void
             $this->deserializeApu($apu, $state['apu']);
         }
 
+        // Restore OAM DMA state (optional for backward compatibility)
+        $oamDma = $this->emulator->getOamDma();
+        if (isset($state['oamDma']) && is_array($state['oamDma']) && $oamDma !== null) {
+            $this->deserializeOamDma($oamDma, $state['oamDma']);
+        }
+
+        // Restore HDMA state (optional for backward compatibility)
+        $hdma = $this->emulator->getHdma();
+        if (isset($state['hdma']) && is_array($state['hdma']) && $hdma !== null) {
+            $this->deserializeHdma($hdma, $state['hdma']);
+        }
+
         // Restore clock
         if (isset($state['clock']['cycles']) && is_int($state['clock']['cycles'])) {
             $clock->reset();
@@ -327,11 +344,20 @@ private function serializeMemory(\Gb\Bus\SystemBus $bus): array
         $vramBank1 = $vram->getData(1);
         $currentVramBank = $vram->getBank();
 
-        $wram = [];
-        for ($i = 0xC000; $i <= 0xDFFF; $i++) {
-            $wram[] = $bus->readByte($i);
+        // Get WRAM from bus to save all banks
+        $wram = $bus->getDevice('wram');
+        if (!($wram instanceof \Gb\Memory\Wram)) {
+            throw new \RuntimeException("Cannot serialize memory: WRAM not found");
         }
 
+        // Save all 8 WRAM banks (32KB total)
+        $wramBanks = [];
+        $allBanks = $wram->getAllBanks();
+        foreach ($allBanks as $bankNumber => $bankData) {
+            $wramBanks["bank{$bankNumber}"] = base64_encode(pack('C*', ...$bankData));
+        }
+        $currentWramBank = $wram->getCurrentBank();
+
         $hram = [];
         for ($i = 0xFF80; $i <= 0xFFFE; $i++) {
             $hram[] = $bus->readByte($i);
@@ -346,7 +372,8 @@ private function serializeMemory(\Gb\Bus\SystemBus $bus): array
             'vramBank0' => base64_encode(pack('C*', ...$vramBank0)),
             'vramBank1' => base64_encode(pack('C*', ...$vramBank1)),
             'vramCurrentBank' => $currentVramBank,
-            'wram' => base64_encode(pack('C*', ...$wram)),
+            'wramBanks' => $wramBanks,
+            'wramCurrentBank' => $currentWramBank,
             'hram' => base64_encode(pack('C*', ...$hram)),
             'oam' => base64_encode(pack('C*', ...$oam)),
         ];
@@ -410,13 +437,38 @@ private function deserializeMemory(\Gb\Bus\SystemBus $bus, array $data): void
         }
 
         // Restore WRAM
-        $wramUnpacked = unpack('C*', base64_decode((string) $data['wram']));
-        if ($wramUnpacked === false) {
-            throw new \RuntimeException('Failed to unpack WRAM data');
-        }
-        $wram = array_values($wramUnpacked);
-        for ($i = 0; $i < count($wram); $i++) {
-            $bus->writeByte(0xC000 + $i, $wram[$i]);
+        $wram = $bus->getDevice('wram');
+        if (!($wram instanceof \Gb\Memory\Wram)) {
+            throw new \RuntimeException("Cannot deserialize memory: WRAM not found");
+        }
+
+        if (isset($data['wramBanks']) && is_array($data['wramBanks'])) {
+            // New format: all 8 banks saved separately
+            for ($bankNumber = 0; $bankNumber < 8; $bankNumber++) {
+                $bankKey = "bank{$bankNumber}";
+                if (isset($data['wramBanks'][$bankKey])) {
+                    $bankUnpacked = unpack('C*', base64_decode((string) $data['wramBanks'][$bankKey]));
+                    if ($bankUnpacked !== false) {
+                        $wram->setBankData($bankNumber, array_values($bankUnpacked));
+                    }
+                }
+            }
+
+            // Restore current bank selection
+            if (isset($data['wramCurrentBank'])) {
+                $wram->setCurrentBank((int) $data['wramCurrentBank']);
+            }
+        } elseif (isset($data['wram'])) {
+            // Old format: flat 8KB (backward compatibility)
+            // This maps to bank 0 (0xC000-0xCFFF) and bank 1 (0xD000-0xDFFF)
+            $wramUnpacked = unpack('C*', base64_decode((string) $data['wram']));
+            if ($wramUnpacked === false) {
+                throw new \RuntimeException('Failed to unpack WRAM data');
+            }
+            $wramData = array_values($wramUnpacked);
+            for ($i = 0; $i < count($wramData); $i++) {
+                $bus->writeByte(0xC000 + $i, $wramData[$i]);
+            }
         }
 
         // Restore HRAM
@@ -557,8 +609,8 @@ private function deserializeCgb(\Gb\System\CgbController $cgb, array $data): voi
     /**
      * Serialize APU state.
      *
-     * Note: This saves register state and basic APU state, but not full channel
-     * internal state (timers, counters). This provides partial audio restoration.
+     * Saves complete APU state including channel internal state for perfect audio
+     * restoration after savestate load.
      *
      * @return array<string, mixed>
      */
@@ -598,6 +650,12 @@ private function serializeApu(\Gb\Apu\Apu $apu): array
             'nr52' => $apu->readByte(0xFF26),
         ];
 
+        // Save channel internal state
+        $ch1 = $apu->getChannel1();
+        $ch2 = $apu->getChannel2();
+        $ch3 = $apu->getChannel3();
+        $ch4 = $apu->getChannel4();
+
         return [
             'registers' => $registers,
             'waveRam' => base64_encode(pack('C*', ...$apu->getWaveRam())),
@@ -605,6 +663,43 @@ private function serializeApu(\Gb\Apu\Apu $apu): array
             'frameSequencerStep' => $apu->getFrameSequencerStep(),
             'sampleCycles' => $apu->getSampleCycles(),
             'enabled' => $apu->isEnabled(),
+            'channel1' => [
+                'lengthCounter' => $ch1->getLengthCounter(),
+                'currentVolume' => $ch1->getCurrentVolume(),
+                'envelopeTimer' => $ch1->getEnvelopeTimer(),
+                'frequencyTimer' => $ch1->getFrequencyTimer(),
+                'dutyPosition' => $ch1->getDutyPosition(),
+                'enabled' => $ch1->getEnabled(),
+                'dacEnabled' => $ch1->getDacEnabled(),
+                'sweepTimer' => $ch1->getSweepTimer(),
+                'sweepShadow' => $ch1->getSweepShadow(),
+                'sweepEnabled' => $ch1->getSweepEnabled(),
+            ],
+            'channel2' => [
+                'lengthCounter' => $ch2->getLengthCounter(),
+                'currentVolume' => $ch2->getCurrentVolume(),
+                'envelopeTimer' => $ch2->getEnvelopeTimer(),
+                'frequencyTimer' => $ch2->getFrequencyTimer(),
+                'dutyPosition' => $ch2->getDutyPosition(),
+                'enabled' => $ch2->getEnabled(),
+                'dacEnabled' => $ch2->getDacEnabled(),
+            ],
+            'channel3' => [
+                'lengthCounter' => $ch3->getLengthCounter(),
+                'frequencyTimer' => $ch3->getFrequencyTimer(),
+                'samplePosition' => $ch3->getSamplePosition(),
+                'enabled' => $ch3->getEnabled(),
+                'dacEnabled' => $ch3->getDacEnabled(),
+            ],
+            'channel4' => [
+                'lengthCounter' => $ch4->getLengthCounter(),
+                'currentVolume' => $ch4->getCurrentVolume(),
+                'envelopeTimer' => $ch4->getEnvelopeTimer(),
+                'frequencyTimer' => $ch4->getFrequencyTimer(),
+                'enabled' => $ch4->getEnabled(),
+                'dacEnabled' => $ch4->getDacEnabled(),
+                'lfsr' => $ch4->getLfsr(),
+            ],
         ];
     }
 
@@ -672,6 +767,106 @@ private function deserializeApu(\Gb\Apu\Apu $apu, array $data): void
         if (isset($data['enabled'])) {
             $apu->setEnabled((bool) $data['enabled']);
         }
+
+        // Restore channel internal state (optional for backward compatibility)
+        if (isset($data['channel1']) && is_array($data['channel1'])) {
+            $ch1 = $apu->getChannel1();
+            $ch1->setLengthCounter((int) ($data['channel1']['lengthCounter'] ?? 0));
+            $ch1->setCurrentVolume((int) ($data['channel1']['currentVolume'] ?? 0));
+            $ch1->setEnvelopeTimer((int) ($data['channel1']['envelopeTimer'] ?? 0));
+            $ch1->setFrequencyTimer((int) ($data['channel1']['frequencyTimer'] ?? 0));
+            $ch1->setDutyPosition((int) ($data['channel1']['dutyPosition'] ?? 0));
+            $ch1->setEnabled((bool) ($data['channel1']['enabled'] ?? false));
+            $ch1->setDacEnabled((bool) ($data['channel1']['dacEnabled'] ?? false));
+            $ch1->setSweepTimer((int) ($data['channel1']['sweepTimer'] ?? 0));
+            $ch1->setSweepShadow((int) ($data['channel1']['sweepShadow'] ?? 0));
+            $ch1->setSweepEnabled((bool) ($data['channel1']['sweepEnabled'] ?? false));
+        }
+
+        if (isset($data['channel2']) && is_array($data['channel2'])) {
+            $ch2 = $apu->getChannel2();
+            $ch2->setLengthCounter((int) ($data['channel2']['lengthCounter'] ?? 0));
+            $ch2->setCurrentVolume((int) ($data['channel2']['currentVolume'] ?? 0));
+            $ch2->setEnvelopeTimer((int) ($data['channel2']['envelopeTimer'] ?? 0));
+            $ch2->setFrequencyTimer((int) ($data['channel2']['frequencyTimer'] ?? 0));
+            $ch2->setDutyPosition((int) ($data['channel2']['dutyPosition'] ?? 0));
+            $ch2->setEnabled((bool) ($data['channel2']['enabled'] ?? false));
+            $ch2->setDacEnabled((bool) ($data['channel2']['dacEnabled'] ?? false));
+        }
+
+        if (isset($data['channel3']) && is_array($data['channel3'])) {
+            $ch3 = $apu->getChannel3();
+            $ch3->setLengthCounter((int) ($data['channel3']['lengthCounter'] ?? 0));
+            $ch3->setFrequencyTimer((int) ($data['channel3']['frequencyTimer'] ?? 0));
+            $ch3->setSamplePosition((int) ($data['channel3']['samplePosition'] ?? 0));
+            $ch3->setEnabled((bool) ($data['channel3']['enabled'] ?? false));
+            $ch3->setDacEnabled((bool) ($data['channel3']['dacEnabled'] ?? false));
+        }
+
+        if (isset($data['channel4']) && is_array($data['channel4'])) {
+            $ch4 = $apu->getChannel4();
+            $ch4->setLengthCounter((int) ($data['channel4']['lengthCounter'] ?? 0));
+            $ch4->setCurrentVolume((int) ($data['channel4']['currentVolume'] ?? 0));
+            $ch4->setEnvelopeTimer((int) ($data['channel4']['envelopeTimer'] ?? 0));
+            $ch4->setFrequencyTimer((int) ($data['channel4']['frequencyTimer'] ?? 0));
+            $ch4->setEnabled((bool) ($data['channel4']['enabled'] ?? false));
+            $ch4->setDacEnabled((bool) ($data['channel4']['dacEnabled'] ?? false));
+            $ch4->setLfsr((int) ($data['channel4']['lfsr'] ?? 0x7FFF));
+        }
+    }
+
+    /**
+     * Serialize OAM DMA state.
+     *
+     * @return array<string, mixed>
+     */
+    private function serializeOamDma(\Gb\Dma\OamDma $dma): array
+    {
+        return [
+            'active' => $dma->getDmaActive(),
+            'progress' => $dma->getDmaProgress(),
+            'delay' => $dma->getDmaDelay(),
+            'source' => $dma->getDmaSource(),
+        ];
+    }
+
+    /**
+     * Deserialize OAM DMA state.
+     *
+     * @param array<string, mixed> $data
+     */
+    private function deserializeOamDma(\Gb\Dma\OamDma $dma, array $data): void
+    {
+        $dma->setDmaActive((bool) ($data['active'] ?? false));
+        $dma->setDmaProgress((int) ($data['progress'] ?? 0));
+        $dma->setDmaDelay((int) ($data['delay'] ?? 0));
+        $dma->setDmaSource((int) ($data['source'] ?? 0));
+    }
+
+    /**
+     * Serialize HDMA state.
+     *
+     * @return array<string, mixed>
+     */
+    private function serializeHdma(\Gb\Dma\HdmaController $hdma): array
+    {
+        return [
+            'active' => $hdma->getHdmaActive(),
+            'hblankMode' => $hdma->getHblankMode(),
+            'remainingBlocks' => $hdma->getRemainingBlocks(),
+        ];
+    }
+
+    /**
+     * Deserialize HDMA state.
+     *
+     * @param array<string, mixed> $data
+     */
+    private function deserializeHdma(\Gb\Dma\HdmaController $hdma, array $data): void
+    {
+        $hdma->setHdmaActive((bool) ($data['active'] ?? false));
+        $hdma->setHblankMode((bool) ($data['hblankMode'] ?? false));
+        $hdma->setRemainingBlocks((int) ($data['remainingBlocks'] ?? 0));
     }
 
     /**
@@ -691,10 +886,11 @@ private function validateState(array $state): void
         }
 
         // Version compatibility check
-        // For now, we only support exact version match
-        if ($state['version'] !== self::VERSION) {
+        // Allow loading of older versions for backward compatibility
+        $validVersions = ['1.0.0', '1.1.0'];
+        if (!in_array($state['version'], $validVersions, true)) {
             throw new \RuntimeException(
-                "Incompatible savestate version: " . (string) $state['version'] . " (expected " . self::VERSION . ")"
+                "Incompatible savestate version: " . (string) $state['version'] . " (expected " . implode(' or ', $validVersions) . ")"
             );
         }
 
diff --git a/src/System/CgbController.php b/src/System/CgbController.php
index 2f55145..729f73f 100644
--- a/src/System/CgbController.php
+++ b/src/System/CgbController.php
@@ -6,6 +6,7 @@
 
 use Gb\Bus\DeviceInterface;
 use Gb\Memory\Vram;
+use Gb\Memory\Wram;
 
 /**
  * Game Boy Color Controller
@@ -16,6 +17,7 @@
  * - VBK (0xFF4F): VRAM bank select
  * - RP (0xFF56): Infrared communications port (stub)
  * - OPRI (0xFF6C): Object priority mode
+ * - SVBK (0xFF70): WRAM bank select (CGB only)
  * - HDMA1-5 (0xFF51-0xFF55): HDMA registers (future)
  *
  * Reference: Pan Docs - CGB Registers
@@ -28,6 +30,7 @@ final class CgbController implements DeviceInterface
     private const VBK = 0xFF4F;  // VRAM bank
     private const RP = 0xFF56;   // Infrared port
     private const OPRI = 0xFF6C; // Object priority mode
+    private const SVBK = 0xFF70; // WRAM bank
 
     /** @var int KEY0 register: CGB mode enable (0x04=DMG mode, 0x80=CGB mode) */
     private int $key0 = 0x00;
@@ -46,6 +49,7 @@ final class CgbController implements DeviceInterface
 
     public function __construct(
         private readonly Vram $vram,
+        private readonly Wram $wram,
         bool $isCgbMode = false,
     ) {
         // Initialize KEY0 and OPRI based on CGB mode
@@ -66,6 +70,7 @@ public function readByte(int $address): int
             self::VBK => $this->vram->getBank() | 0xFE, // Only bit 0 used, others return 1
             self::RP => 0xFF, // Infrared stub: always return 0xFF
             self::OPRI => $this->opri | 0xFE, // Only bit 0 used, others return 1
+            self::SVBK => $this->wram->getCurrentBank() | 0xF8, // Only bits 2-0 used, others return 1
             default => 0xFF,
         };
     }
@@ -78,6 +83,7 @@ public function writeByte(int $address, int $value): void
             self::VBK => $this->vram->setBank($value & 0x01),
             self::RP => null, // Infrared stub: ignore writes
             self::OPRI => $this->opri = $value & 0x01, // Only bit 0 is writable
+            self::SVBK => $this->wram->setCurrentBank($value & 0x07), // Bits 2-0 for bank 0-7
             default => null,
         };
     }
diff --git a/tests/Unit/Savestate/SavestateManagerTest.php b/tests/Unit/Savestate/SavestateManagerTest.php
index 8af68ad..f3a74df 100644
--- a/tests/Unit/Savestate/SavestateManagerTest.php
+++ b/tests/Unit/Savestate/SavestateManagerTest.php
@@ -49,7 +49,7 @@ public function it_returns_valid_structure_on_serialize(): void
         $this->assertArrayHasKey('clock', $state);
 
         $this->assertEquals('PHPBOY_SAVESTATE', $state['magic']);
-        $this->assertEquals('1.0.0', $state['version']);
+        $this->assertEquals('1.1.0', $state['version']);
     }
 
     #[Test]
diff --git a/tests/Unit/System/CgbControllerTest.php b/tests/Unit/System/CgbControllerTest.php
index 92c6213..5244931 100644
--- a/tests/Unit/System/CgbControllerTest.php
+++ b/tests/Unit/System/CgbControllerTest.php
@@ -5,6 +5,7 @@
 namespace Tests\Unit\System;
 
 use Gb\Memory\Vram;
+use Gb\Memory\Wram;
 use Gb\System\CgbController;
 use PHPUnit\Framework\Attributes\Test;
 use PHPUnit\Framework\TestCase;
@@ -13,11 +14,13 @@ final class CgbControllerTest extends TestCase
 {
     private CgbController $controller;
     private Vram $vram;
+    private Wram $wram;
 
     protected function setUp(): void
     {
         $this->vram = new Vram();
-        $this->controller = new CgbController($this->vram);
+        $this->wram = new Wram();
+        $this->controller = new CgbController($this->vram, $this->wram);
     }
 
     #[Test]