cge_nes 0.1.2

//! MMC3 (Mapper 4) implementation.
//!
//! The MMC3 is one of the most popular NES mappers. It supports:
//! - PRG ROM banking in 8KB units (with one bank fixed at the end of the address space)
//! - CHR ROM/RAM banking in 1KB or 2KB units
//! - Scanline IRQ counter driven by PPU A12 rises
//! - Configurable name table mirroring
//! - Optional PRG RAM with write-protect bit
//!
//! # Memory Map
//!
//! CPU Memory Map:
//! - `$6000-$7FFF`: 8KB PRG RAM (write-protected by PRG RAM protect register)
//! - `$8000-$9FFF`: 8KB PRG ROM bank (switchable)
//! - `$A000-$BFFF`: 8KB PRG ROM bank (switchable)
//! - `$C000-$DFFF`: 8KB PRG ROM bank (fixed to second-to-last or switchable)
//! - `$E000-$FFFF`: 8KB PRG ROM bank (fixed to last)
//!
//! PPU Memory Map:
//! - `$0000-$07FF`: 2KB CHR bank (switchable, or 2 1KB banks)
//! - `$0800-$0FFF`: 2KB CHR bank (switchable, or 2 1KB banks)
//! - `$1000-$13FF`: 1KB CHR bank (switchable, or upper half of 2KB bank)
//! - `$1400-$17FF`: 1KB CHR bank (switchable, or upper half of 2KB bank)
//! - `$1800-$1BFF`: 1KB CHR bank (switchable, or upper half of 2KB bank)
//! - `$1C00-$1FFF`: 1KB CHR bank (switchable, or upper half of 2KB bank)
//! - `$2000-$3EFF`: Name Tables (configurable mirroring)
//!
//! # Registers
//!
//! The MMC3 is configured through bank-select and bank-data writes at `$8000-$FFFF`:
//! - `$8000-$9FFF` even: Bank select (selects which internal register gets the next data write)
//! - `$8001-$9FFF` odd:  Bank data (sets the selected bank register)
//! - `$A000-$BFFF` even: Mirroring
//! - `$A001-$BFFF` odd:  PRG RAM write protect
//! - `$C000-$DFFF` even: IRQ latch
//! - `$C001-$DFFF` odd:  IRQ reload
//! - `$E000-$FFFF` even: IRQ acknowledge / disable
//! - `$E001-$FFFF` odd:  IRQ enable

use crate::cartridge::{Cartridge, ChrRomContentStatus};
use crate::rom_loader::ines::mappers::{CART_CPU_MAP_BEGIN_ADDR, LAST_UNREACHABLE_ADDRESS};
use crate::rom_loader::ines::{HeaderData, Mirroring};
use crate::{LoadRomResult, RomError};
use devices6502::size_const::*;
use devices6502::{Device, Ram, Rom};
use std::cmp::PartialEq;
use std::io;
use std::ops::Rem;

/// Size of each PRG ROM bank in bytes
const PRG_ROM_PAGE_SIZE: usize = SIZE_8K;
/// Size of each CHR ROM/RAM bank in bytes
const CHR_MEM_PAGE_SIZE: usize = SIZE_1K;

/// Size of each name table page in bytes
const NAME_TABLE_PAGE_SIZE: usize = SIZE_1K;

/// Maximum number of PRG ROM pages supported (up to 2MB)
const MAX_PRG_ROM_PAGES: usize = u8::MAX as usize;
/// Maximum number of CHR ROM pages supported (256 × 1 KB = 256 KB,
/// the full MMC3 CHR ROM ceiling per NESdev).
const MAX_CHR_ROM_PAGES: usize = 256;

/// PRG/CHR banking mode controlled by bits 6 and 7 of the bank-select register.
///
/// `Normal` follows the standard MMC3 layout, `Inverted` swaps the bank ordering
/// so that the second 2KB region uses R0/R1 instead of R2/R3 (or vice versa for PRG).
#[derive(Default, Copy, Clone, PartialEq, Eq, Debug)]
enum Mode {
    #[default]
    Normal,
    Inverted,
}

type NameTablePage = Ram<NAME_TABLE_PAGE_SIZE>;

#[derive(Default)]
struct NameTableRam {
    /// Name Table memory.
    ///
    /// Only first 2 pages are used for horizontal/vertical mirroring, all 4 pages are used for four-screen mode.
    ram_pages: [NameTablePage; 4],
    mode: Mirroring,
}

/// Abstraction over the MMC3's CHR memory backing storage.
///
/// The MMC3 can be paired with either CHR ROM banks ([`Vec<Rom<SIZE_1K>>`]) or
/// CHR RAM ([`Ram<SIZE_8K>`]). This trait lets the rest of the cartridge code
/// operate on either without knowing which one is in use.
trait ChrMem: Send {
    /// Writes a byte into CHR memory at the PPU-mapped address, applying
    /// the current [`Mode`] and bank register selection.
    fn write_chr_mem(
        &mut self,
        data: u8,
        addr: u16,
        mode: Mode,
        bank_regs: &[u8; 8],
    ) -> ChrRomContentStatus;
    /// Reads a byte from CHR memory at the PPU-mapped address, applying
    /// the current [`Mode`] and bank register selection.
    fn read_chr_mem(&self, addr: u16, mode: Mode, bank_regs: &[u8; 8]) -> u8;
    /// Returns the number of 1KB pages of CHR memory available.
    fn page_count(&self) -> u16;

    /// Returns true when the CHR backing is writable RAM (test-only helper).
    #[cfg(test)]
    fn has_chr_ram() -> bool {
        false
    }
}

#[derive(Default)]
struct Cart<TChrMem> {
    // Memory
    /// 8KB PRG RAM at $6000-$7FFF
    prg_ram: Ram<SIZE_8K>,
    /// Program ROM banks (8KB each)
    prg_rom: Vec<Rom<PRG_ROM_PAGE_SIZE>>,
    /// Character ROM banks (1KB each)
    chr_mem: TChrMem,
    /// Name table RAM with configurable mirroring
    name_tables_ram: NameTableRam,

    // Mapper State
    /// Index of the bank register (0..=7) selected by the most recent even write to $8000-$9FFF.
    bank_select: u8,
    /// Current value of each of the 8 MMC3 bank registers.
    bank_registers: [u8; 8],
    /// Whether the PRG bank order is normal or inverted (bit 6 of bank-select).
    prg_mode: Mode,
    /// Whether the CHR bank order is normal or inverted (bit 7 of bank-select).
    chr_mode: Mode,
    /// Current value of the PRG RAM write-protect bit (bit 7 of $A001).
    is_ram_writable: bool,
    /// Latched by the CPU and asserted on the IRQ pin when the counter reaches zero (if enabled).
    irq_active: bool,
    /// Value the counter is reloaded with on an A12 rising edge (set via $C000).
    irq_latch: u8,
    /// Down-counter driven by PPU A12 rising edges (decremented until it reaches 0).
    irq_counter: u8,
    /// When set, the next A12 rising edge reloads the counter from [`irq_latch`].
    irq_reload_flag: bool,
    /// Whether the IRQ pin follows the counter (set/cleared via $E000/$E001).
    irq_enable: bool,
    /// Previous PPU address bit 12 state; used to detect rising edges for the IRQ counter.
    prev_a12: bool,
}

/// Loads ROM data into an MMC3 mapper implementation.
///
/// # Arguments
///
/// * `header_data` - Parsed iNES header information
/// * `rom_reader` - Reader containing ROM data positioned after the header
///
/// # Returns
///
/// Returns a `Result` containing either:
/// * `Ok(Box<dyn Cartridge>)` - A boxed cartridge implementation for the ROM
/// * `Err(RomError)` - An error if loading fails
///
/// # Errors
///
/// Returns `RomError` if:
/// * ROM data cannot be read
/// * CHR ROM size is not a multiple of 1KB or exceeds the maximum
/// * PRG ROM size is not a multiple of 8KB or exceeds the maximum
pub fn load(header: &HeaderData, reader: &mut impl io::Read) -> LoadRomResult {
    // Validate CHR ROM size doesn't exceed maximum supported size (1KB * 256 = 256KB)
    if header.chr_rom_size as usize > (MAX_CHR_ROM_PAGES * CHR_MEM_PAGE_SIZE) {
        return Err(RomError::RomFormat(
            "Wrong chr rom size using mapper 004. Up until 256K allowed".into(),
        ));
    }

    // Validate CHR ROM size is a multiple of 1KB pages
    if (header.chr_rom_size as usize % CHR_MEM_PAGE_SIZE) != 0 {
        return Err(RomError::RomFormat(
            "Wrong chr rom size using mapper 004. It must be a multiple of 1K".into(),
        ));
    }

    // Validate PRG ROM size doesn't exceed maximum supported size (8KB * 255 = ~2MB)
    if header.prg_rom_size as usize > (MAX_PRG_ROM_PAGES * PRG_ROM_PAGE_SIZE) {
        return Err(RomError::RomFormat(
            "Wrong prg rom size using mapper 004. Up until ~2MB allowed".into(),
        ));
    }

    // Validate PRG ROM size is a multiple of 8KB pages
    if (header.prg_rom_size as usize % PRG_ROM_PAGE_SIZE) != 0 {
        return Err(RomError::RomFormat(
            "Wrong prg rom size using mapper 004. It must be a multiple of 8K".into(),
        ));
    }

    // Allocate buffer for PRG ROM data
    let mut prg_rom_data = Vec::with_capacity(header.prg_rom_size as usize);
    prg_rom_data.resize(header.prg_rom_size as usize, 0u8);

    // Read PRG ROM data from file
    reader.read_exact(prg_rom_data.as_mut_slice())?;

    // Allocate and read CHR ROM data if present
    let mut chr_rom_data = Vec::new();
    chr_rom_data.resize(header.chr_rom_size as usize, 0u8);
    reader.read_exact(&mut chr_rom_data)?;

    let num_prg_pages = header.prg_rom_size as usize / PRG_ROM_PAGE_SIZE;
    let num_chr_pages = header.chr_rom_size as usize / CHR_MEM_PAGE_SIZE;

    let mut prg_rom = Vec::with_capacity(num_prg_pages);
    prg_rom_data.chunks(PRG_ROM_PAGE_SIZE).for_each(|chunk| {
        prg_rom.push(Rom::<PRG_ROM_PAGE_SIZE>::with_data(chunk));
    });

    let mut chr_mem = Vec::with_capacity(num_chr_pages);
    chr_rom_data.chunks(CHR_MEM_PAGE_SIZE).for_each(|chunk| {
        chr_mem.push(Rom::<CHR_MEM_PAGE_SIZE>::with_data(chunk));
    });

    if chr_mem.len() > 0 {
        let mut cart = Cart {
            prg_rom,
            chr_mem,
            irq_enable: true,
            ..Default::default()
        };

        match header.mirroring {
            Mirroring::Horizontal => cart.name_tables_ram.set_horizontal(),
            Mirroring::Vertical => cart.name_tables_ram.set_vertical(),
            Mirroring::FourScreen => cart.name_tables_ram.set_four_screen(),
        }

        Ok(Box::new(cart))
    } else {
        let mut cart = Cart {
            prg_rom,
            chr_mem: Ram::<SIZE_8K>::default(),
            irq_enable: true,
            ..Default::default()
        };

        match header.mirroring {
            Mirroring::Horizontal => cart.name_tables_ram.set_horizontal(),
            Mirroring::Vertical => cart.name_tables_ram.set_vertical(),
            Mirroring::FourScreen => cart.name_tables_ram.set_four_screen(),
        }

        Ok(Box::new(cart))
    }
}

/// Maps a PPU name-table address to the underlying 1KB RAM page index for a
/// given mirroring mode.
///
/// In horizontal mirroring each pair of vertically adjacent name tables share
/// the same page; in vertical mirroring the two left tables share a page and
/// the two right tables share the other. Four-screen mirroring uses each page
/// directly with no aliasing.
fn name_table_page_index(addr: u16, mode: Mirroring) -> usize {
    let page_index = addr as usize / SIZE_1K;
    match mode {
        Mirroring::Horizontal => page_index / 2,
        Mirroring::Vertical => page_index % 2,
        Mirroring::FourScreen => page_index,
    }
}

/// Returns true if `n` is even. Used to dispatch between MMC3 register-select
/// (even addresses) and register-data (odd addresses) writes.
fn is_even<T>(n: T) -> bool
where
    T: Rem<Output = T> + PartialEq + From<u8> + Copy,
{
    n % T::from(2) == T::from(0)
}

impl Device for NameTableRam {
    fn with_data(data: &[u8]) -> Self
    where
        Self: Sized,
    {
        let ranges: [_; 4] =
            core::array::from_fn(|i| i * NAME_TABLE_PAGE_SIZE..(i + 1) * NAME_TABLE_PAGE_SIZE);
        assert_eq!(data.len(), ranges.last().unwrap().end);
        Self {
            ram_pages: [
                Ram::with_data(&data[ranges[0].clone()]),
                Ram::with_data(&data[ranges[1].clone()]),
                Ram::with_data(&data[ranges[2].clone()]),
                Ram::with_data(&data[ranges[3].clone()]),
            ],
            mode: Default::default(),
        }
    }

    fn init_data(&mut self, data: &[u8]) {
        assert_eq!(data.len(), SIZE_4K);
        for i in 0..4 {
            self.ram_pages[i].init_data(&data[i * SIZE_1K..(i + 1) * SIZE_1K]);
        }
    }

    fn read(&self, addr: u16) -> u8 {
        let addr_in_page = addr % SIZE_1K as u16;
        let page_index = name_table_page_index(addr, self.mode);
        self.ram_pages[page_index].read(addr_in_page)
    }

    fn write(&mut self, data: u8, addr: u16) {
        let addr_in_page = addr % SIZE_1K as u16;
        let page_index = name_table_page_index(addr, self.mode);
        self.ram_pages[page_index].write(data, addr_in_page);
    }

    fn addr_space_size() -> u32
    where
        Self: Sized,
    {
        NameTablePage::addr_space_size() * 4
    }

    fn addr_space_size_dyn(&self) -> u32 {
        self.ram_pages[0].addr_space_size_dyn() * 4
    }
}

impl NameTableRam {
    /// Switches to four-screen mirroring. Once set, the mirroring mode is sticky
    /// (additional set_horizontal/set_vertical calls are ignored) so the cartridge
    /// can opt into four-screen without being overridden by the iNES header.
    fn set_four_screen(&mut self) {
        self.mode = Mirroring::FourScreen;
    }

    /// Switches to vertical mirroring. Ignored if four-screen mode is already active.
    fn set_vertical(&mut self) {
        if self.mode != Mirroring::FourScreen {
            self.mode = Mirroring::Vertical;
        }
    }

    /// Switches to horizontal mirroring. Ignored if four-screen mode is already active.
    fn set_horizontal(&mut self) {
        if self.mode != Mirroring::FourScreen {
            self.mode = Mirroring::Horizontal;
        }
    }
}

impl<TChrMem: ChrMem> Cartridge for Cart<TChrMem> {
    fn read_cpu_mapped(&self, addr: u16) -> u8 {
        let addr = addr + CART_CPU_MAP_BEGIN_ADDR;
        match addr {
            0x000..=LAST_UNREACHABLE_ADDRESS => unreachable!(),
            CART_CPU_MAP_BEGIN_ADDR..=0x5FFF => 0, // not mapped
            0x6000..=0x7FFF => self.read_prg_ram(addr - 0x6000),
            0x8000..=0xFFFF => self.read_prg_rom(addr - 0x8000),
        }
    }

    fn write_cpu_mapped(&mut self, data: u8, addr: u16) -> ChrRomContentStatus {
        let addr = addr + CART_CPU_MAP_BEGIN_ADDR;
        match addr {
            0x0000..=LAST_UNREACHABLE_ADDRESS => unreachable!(),
            CART_CPU_MAP_BEGIN_ADDR..=0x5FFF => (), // not mapped
            // PRG RAM region; the write is gated by `is_ram_writable` inside `write_prg_ram`.
            0x6000..=0x7FFF => self.write_prg_ram(addr - 0x6000, data),
            // Bank-select / bank-data: even addresses pick which internal register
            // gets the next data write, odd addresses write the value to it.
            0x8000..=0x9FFF => {
                if is_even(addr) {
                    self.write_bank_select(data);
                } else {
                    self.write_bank_data(data);
                }
            }
            // Mirroring and PRG RAM write-protect: bit 0 of data picks horizontal/vertical,
            // odd addresses write bit 7 into the PRG RAM protect flag.
            0xA000..=0xBFFF => {
                if is_even(addr) {
                    if is_even(data) {
                        self.name_tables_ram.set_vertical();
                    } else {
                        self.name_tables_ram.set_horizontal();
                    };
                } else {
                    self.is_ram_writable = (data & 0x80) != 0;
                }
            }
            // IRQ latch / reload: even address latches the reload value, odd
            // address arms the reload to happen on the next A12 rising edge.
            0xC000..=0xDFFF => {
                if is_even(addr) {
                    self.irq_latch = data;
                } else {
                    self.irq_reload_flag = true;
                }
            }
            // IRQ disable / enable: even address disables the IRQ and acknowledges any
            // pending interrupt; odd address enables the IRQ.
            0xE000..=0xFFFF => {
                if is_even(addr) {
                    self.irq_enable = false;
                    self.irq_active = false;
                } else {
                    self.irq_enable = true;
                }
            }
        }

        ChrRomContentStatus::Unchanged
    }

    fn read_ppu_mapped(&mut self, addr: u16) -> u8 {
        // Pattern table reads on the NES toggle PPU address bit 12, so every
        // CHR access also feeds the IRQ counter through A12 edge detection.
        self.irq_update(addr);
        match addr {
            0x0000..=0x1FFF => self
                .chr_mem
                .read_chr_mem(addr, self.chr_mode, &self.bank_registers),
            0x2000..=0x3EFF => self.name_tables_ram.read(addr - 0x2000),
            _ => unreachable!(),
        }
    }

    fn write_ppu_mapped(&mut self, data: u8, addr: u16) -> ChrRomContentStatus {
        // Same A12 edge tracking applies on writes, which is how CHR-RAM
        // games also get the scanline counter to advance.
        self.irq_update(addr);
        match addr {
            0x0000..=0x1FFF => {
                self.chr_mem
                    .write_chr_mem(data, addr, self.chr_mode, &self.bank_registers)
            }
            0x2000..=0x3EFF => {
                self.name_tables_ram.write(data, addr - 0x2000);
                ChrRomContentStatus::Unchanged
            }
            _ => unreachable!(),
        }
    }

    fn irq_pin(&self) -> bool {
        self.irq_active
    }

    fn requires_cycle_accurate_sprites(&self) -> bool {
        true
    }

    fn notify_vram_addr_change(&mut self, _old_addr: u16, new_addr: u16) {
        // The PPU's VRAM address changed (e.g. via $2007 auto-increment).
        // Feed the new address to `irq_update` so the MMC3 can detect an A12
        // rising edge on the post-increment value.
        self.irq_update(new_addr);
    }
}

/// 8KB of CHR RAM, used when the iNES header reports a CHR ROM size of zero.
///
/// All writes are tracked as `Changed` so the PPU can invalidate any caches.
impl ChrMem for Ram<SIZE_8K> {
    fn write_chr_mem(
        &mut self,
        data: u8,
        addr: u16,
        _mode: Mode,
        _bank_regs: &[u8; 8],
    ) -> ChrRomContentStatus {
        self.write(data, addr);
        ChrRomContentStatus::Changed
    }

    fn read_chr_mem(&self, addr: u16, _mode: Mode, _bank_regs: &[u8; 8]) -> u8 {
        self.read(addr)
    }

    fn page_count(&self) -> u16 {
        8
    }

    #[cfg(test)]
    fn has_chr_ram() -> bool {
        true
    }
}

/// Resolves which 1KB CHR page backs a given PPU-mapped address, based on the
/// current bank register values and [`Mode`].
///
/// Bank registers 0-5 control the six 1KB CHR windows ($0000, $0400, $0800,
/// $1000, $1400, $1800). Registers 0-1 always form a paired 2KB region for
/// `$0000-$07FF` (or `$0800-$0FFF` in inverted mode), and registers 2-3 form
/// the paired 2KB region for `$1000-$17FF` (or `$0000-$07FF` in inverted mode).
fn chr_mem_page_index(chr_addr: u16, mode: Mode, bank_registers: &[u8; 8]) -> usize {
    let eighth = chr_addr / SIZE_1K as u16;
    match (eighth, mode) {
        (0, Mode::Normal) | (4, Mode::Inverted) => bank_registers[0] as usize,
        (1, Mode::Normal) | (5, Mode::Inverted) => bank_registers[0] as usize + 1,
        (2, Mode::Normal) | (6, Mode::Inverted) => bank_registers[1] as usize,
        (3, Mode::Normal) | (7, Mode::Inverted) => bank_registers[1] as usize + 1,
        (4, Mode::Normal) | (0, Mode::Inverted) => bank_registers[2] as usize,
        (5, Mode::Normal) | (1, Mode::Inverted) => bank_registers[3] as usize,
        (6, Mode::Normal) | (2, Mode::Inverted) => bank_registers[4] as usize,
        (7, Mode::Normal) | (3, Mode::Inverted) => bank_registers[5] as usize,
        _ => unreachable!(),
    }
}

/// Vector of 1KB CHR ROM banks, used when the iNES header reports a non-zero
/// CHR ROM size. Writes still report `Changed` to mirror how the trait is used
/// by other call sites, but the underlying [`Rom`] ignores the write.
impl ChrMem for Vec<Rom<SIZE_1K>> {
    fn write_chr_mem(
        &mut self,
        data: u8,
        addr: u16,
        mode: Mode,
        bank_regs: &[u8; 8],
    ) -> ChrRomContentStatus {
        debug_assert!(addr < SIZE_8K as u16);
        let addr_in_page = addr % SIZE_8K as u16;
        let page_index = chr_mem_page_index(addr, mode, bank_regs);

        self[page_index].write(data, addr_in_page);
        ChrRomContentStatus::Changed
    }

    fn read_chr_mem(&self, addr: u16, mode: Mode, bank_regs: &[u8; 8]) -> u8 {
        debug_assert!(addr < SIZE_8K as u16);
        let addr_in_page = addr % SIZE_8K as u16;
        let page_index = chr_mem_page_index(addr, mode, bank_regs);

        self[page_index].read(addr_in_page)
    }

    fn page_count(&self) -> u16 {
        self.len() as u16
    }
}

impl<TChrMem: ChrMem> Cart<TChrMem> {
    /// Forwards [`ChrMem::has_chr_ram`] from the CHR backing type to the cart.
    #[cfg(test)]
    fn has_chr_ram(&self) -> bool {
        TChrMem::has_chr_ram()
    }

    /// Writes a byte to PRG RAM at $6000-$7FFF, respecting the PRG RAM protect bit.
    fn write_prg_ram(&mut self, addr: u16, data: u8) {
        if self.is_ram_writable {
            self.prg_ram.write(data, addr);
        }
    }

    /// Updates the bank-select register, PRG mode (bit 6), and CHR mode (bit 7).
    ///
    /// Bits 0-2 of `data` select which of the 8 internal bank registers the next
    /// odd-address write at $8001 will target. Bit 6 selects the PRG banking mode
    /// and bit 7 selects the CHR banking mode.
    fn write_bank_select(&mut self, data: u8) {
        self.bank_select = data % 8;
        // MMC3 uses bit 6 for PRG mode and bit 7 for CHR inversion
        self.prg_mode = if (data & 0x40) != 0 {
            Mode::Inverted
        } else {
            Mode::Normal
        };
        self.chr_mode = if (data & 0x80) != 0 {
            Mode::Inverted
        } else {
            Mode::Normal
        };

        #[cfg(feature = "mapper_debug_log")]
        if false {
            println!("write_bank_select bank:{}", self.bank_select);
            println!(
                "prg_mode: {:?}, chr_mode: {:?}",
                self.prg_mode, self.chr_mode
            );
            println!();
        }
    }

    /// Stores a value in the bank register selected by the most recent
    /// `write_bank_select` call, applying the appropriate mask:
    /// - Registers 0-1 are CHR bank pairs (2KB): the LSB is cleared so the
    ///   pair stays aligned.
    /// - Registers 2-5 are single 1KB CHR banks: stored as-is.
    /// - Registers 6-7 are PRG banks: value modulo the PRG ROM page count.
    fn write_bank_data(&mut self, data: u8) {
        let data = if self.bank_select < 6 {
            // Chr Mem page. Compute the modulo in u16 so a 256-page CHR ROM
            // doesn't overflow and produce a panic from `% 0`.
            let data = (data as u16 % self.chr_mem.page_count()) as u8;
            if self.bank_select < 2 {
                data & !1 // even page index for 2KB bank
            } else {
                data
            }
        } else {
            // PRG bank modulo its page count (page count fits in u8 today;
            // widen to u16 in case future boards accept more than 255 pages).
            (data as u16 % self.prg_rom.len() as u16) as u8
        };
        self.bank_registers[self.bank_select as usize] = data;
        #[cfg(feature = "mapper_debug_log")]
        {
            println!(
                "write_bank_data\tbank:{}\tvalue:{}",
                self.bank_select, self.bank_registers[self.bank_select as usize]
            );
        }
    }

    /// Reads a byte from PRG RAM at $6000-$7FFF.
    fn read_prg_ram(&self, addr: u16) -> u8 {
        debug_assert!(addr < SIZE_8K as u16);
        self.prg_ram.read(addr)
    }

    /// Reads a byte from the PRG ROM window at $8000-$FFFF, dispatching to the
    /// right bank register based on the address quarter and PRG banking mode.
    ///
    /// In normal mode, $8000-$9FFF uses R6, $A000-$BFFF uses R7, $C000-$DFFF
    /// is fixed to the second-to-last page, and $E000-$FFFF is fixed to the last
    /// page. Inverted mode swaps the R6/R7 windows with the fixed ones.
    fn read_prg_rom(&self, addr: u16) -> u8 {
        debug_assert!(addr < SIZE_32K as u16);
        let quarter = addr / SIZE_8K as u16;
        let addr_in_page = addr % SIZE_8K as u16;
        match (quarter, self.prg_mode) {
            (0, Mode::Normal) | (2, Mode::Inverted) => {
                self.prg_rom[self.bank_registers[6] as usize].read(addr_in_page)
            }
            (1, _) => self.prg_rom[self.bank_registers[7] as usize].read(addr_in_page),
            (2, Mode::Normal) | (0, Mode::Inverted) => {
                self.prg_rom[self.second_to_last_prg_rom_page_index()].read(addr_in_page)
            }
            (3, _) => self.prg_rom[self.last_prg_rom_page_index()].read(addr_in_page),
            _ => unreachable!(),
        }
    }

    /// Feeds an observed PPU address into the MMC3 scanline IRQ counter.
    ///
    /// On every rising edge of address bit 12 (the line that distinguishes
    /// $0FFF from $1000 in the PPU address space), the counter is either
    /// reloaded from the latch (if a reload was armed via $C001, or if the
    /// counter was already 0) or decremented. Whenever the counter is zero
    /// after the edge and IRQs are enabled, the IRQ pin is asserted until
    /// the CPU acknowledges it via $E000.
    fn irq_update(&mut self, addr: u16) {
        let current_a12 = (addr & 0x1000) != 0;
        if current_a12 && !self.prev_a12 {
            if self.irq_reload_flag || (self.irq_counter == 0) {
                self.irq_counter = self.irq_latch;
                self.irq_reload_flag = false;
            } else {
                self.irq_counter = self.irq_counter.wrapping_sub(1);
            }

            if self.irq_enable && (self.irq_counter == 0) {
                self.irq_active = true;
            }
        }
        self.prev_a12 = current_a12;
    }

    /// Returns the index of the last 8KB PRG ROM page (always mapped at $E000-$FFFF).
    fn last_prg_rom_page_index(&self) -> usize {
        self.prg_rom.len() - 1
    }

    /// Returns the index of the second-to-last 8KB PRG ROM page.
    fn second_to_last_prg_rom_page_index(&self) -> usize {
        self.last_prg_rom_page_index() - 1
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn build_pages() -> Vec<u8> {
        // Create 4 pages with distinct byte values: 0x00, 0x11, 0x22, 0x33
        let mut data = vec![0u8; NAME_TABLE_PAGE_SIZE * 4];
        for i in 0..4 {
            let val = (i as u8).wrapping_mul(0x11);
            for b in data
                .iter_mut()
                .take((i + 1) * NAME_TABLE_PAGE_SIZE)
                .skip(i * NAME_TABLE_PAGE_SIZE)
            {
                *b = val;
            }
        }
        data
    }

    #[test]
    fn horizontal_mapping_read_write() {
        let data = build_pages();
        let mut nt = NameTableRam::with_data(&data);
        // Default mode is Horizontal
        // Pages: [0x00, 0x11, 0x22, 0x33]
        assert_eq!(nt.read(0x000), 0x00);
        assert_eq!(nt.read(0x400), 0x00); // maps to page 0 as well
        assert_eq!(nt.read(0x800), 0x11);
        assert_eq!(nt.read(0xC00), 0x11);

        // Write through should affect the mirrored addresses
        nt.write(0xAA, 0x400); // writes to page 0
        assert_eq!(nt.read(0x000), 0xAA);
        assert_eq!(nt.read(0x400), 0xAA);
    }

    #[test]
    fn vertical_mapping_read_write() {
        let data = build_pages();
        let mut nt = NameTableRam::with_data(&data);
        nt.set_vertical();
        // Vertical mapping: pages 0 & 2 -> page 0; pages 1 & 3 -> page 1
        assert_eq!(nt.read(0x000), 0x00);
        assert_eq!(nt.read(0x400), 0x11);
        assert_eq!(nt.read(0x800), 0x00);
        assert_eq!(nt.read(0xC00), 0x11);

        nt.write(0xBB, 0x800); // writes to page 0 mirror
        assert_eq!(nt.read(0x000), 0xBB);
        assert_eq!(nt.read(0x800), 0xBB);
    }

    #[test]
    fn four_screen_mapping_read_write() {
        let data = build_pages();
        let mut nt = NameTableRam::with_data(&data);
        nt.set_four_screen();
        // Four screen mapping: direct pages
        assert_eq!(nt.read(0x000), 0x00);
        assert_eq!(nt.read(0x400), 0x11);
        assert_eq!(nt.read(0x800), 0x22);
        assert_eq!(nt.read(0xC00), 0x33);

        nt.write(0xCC, 0xC00); // write to page 3
        assert_eq!(nt.read(0xC00), 0xCC);
    }

    #[test]
    fn is_even_various_types() {
        assert!(is_even(0u8));
        assert!(is_even(2u8));
        assert!(!is_even(3u8));
        assert!(is_even(4u16));
        assert!(!is_even(5u16));
        assert!(is_even(10i32));
        assert!(!is_even(11i32));
    }

    #[test]
    fn name_table_page_index_function() {
        // Horizontal: page_index / 2
        assert_eq!(name_table_page_index(0x000, Mirroring::Horizontal), 0);
        assert_eq!(name_table_page_index(0x400, Mirroring::Horizontal), 0);
        assert_eq!(name_table_page_index(0x800, Mirroring::Horizontal), 1);

        // Vertical: page_index % 2
        assert_eq!(name_table_page_index(0x000, Mirroring::Vertical), 0);
        assert_eq!(name_table_page_index(0x400, Mirroring::Vertical), 1);
        assert_eq!(name_table_page_index(0x800, Mirroring::Vertical), 0);

        // FourScreen: direct
        assert_eq!(name_table_page_index(0x000, Mirroring::FourScreen), 0);
        assert_eq!(name_table_page_index(0x400, Mirroring::FourScreen), 1);
        assert_eq!(name_table_page_index(0x800, Mirroring::FourScreen), 2);
    }

    fn build_cart(prg_pages: usize, chr_pages: usize) -> Cart<Vec<Rom<SIZE_1K>>> {
        let mut prg = Vec::new();
        for i in 0..prg_pages {
            let data = vec![i as u8; PRG_ROM_PAGE_SIZE];
            prg.push(Rom::<PRG_ROM_PAGE_SIZE>::with_data(&data));
        }
        let mut chr = Vec::new();
        for i in 0..chr_pages {
            let data = vec![i as u8; CHR_MEM_PAGE_SIZE];
            chr.push(Rom::<CHR_MEM_PAGE_SIZE>::with_data(&data));
        }

        Cart {
            prg_rom: prg,
            chr_mem: chr,
            bank_select: 0,
            bank_registers: [0u8; 8],
            prg_mode: Mode::Normal,
            chr_mode: Mode::Normal,
            is_ram_writable: false,
            ..Default::default()
        }
    }

    #[test]
    fn write_bank_select_and_data() {
        let mut cart = build_cart(4, 8);
        // set bank_select to 0, prg_mode normal, chr_mode normal
        cart.write_bank_select(0);
        assert_eq!(cart.bank_select, 0);
        assert_eq!(cart.prg_mode, Mode::Normal);
        assert_eq!(cart.chr_mode, Mode::Normal);

        // write bank data for bank 0 (CHR 2KB pair) with odd value should clear LSB
        cart.write_bank_data(3);
        assert_eq!(cart.bank_registers[0], 2);

        // set bank_select to 6 (PRG bank) and write data that exceeds prg count
        cart.write_bank_select(6);
        cart.write_bank_data(6); // 6 % 4 == 2
        assert_eq!(cart.bank_registers[6], 2);
    }

    #[test]
    fn read_prg_rom_mapping_quarters() {
        // create 4 PRG pages with distinct byte content equal to page index
        let mut cart = build_cart(4, 0);
        // set bank registers for 6 and 7
        cart.bank_registers[6] = 1; // for quarter 0 in Normal mode
        cart.bank_registers[7] = 2; // for quarter 1
        cart.prg_mode = Mode::Normal;

        // quarter 0 -> bank_registers[6] (page 1)
        let val_q0 = cart.read_prg_rom(0 * SIZE_8K as u16 + 0x000);
        assert_eq!(val_q0, 1u8);

        // quarter 1 -> bank_registers[7] (page 2)
        let val_q1 = cart.read_prg_rom(1 * SIZE_8K as u16 + 0x123);
        assert_eq!(val_q1, 2u8);

        // quarter 2 -> second_to_last_prg_rom_page_index() -> should be second-to-last (len-2)
        let val_q2 = cart.read_prg_rom(2 * SIZE_8K as u16 + 0x1);
        assert_eq!(val_q2, 2u8);
    }

    #[test]
    fn chr_mem_page_index_and_write_behavior() {
        let mut cart = build_cart(2, 8);
        // set bank registers for chr banks
        cart.bank_registers[0] = 4;
        cart.bank_registers[1] = 6;
        cart.bank_registers[2] = 8;
        cart.bank_registers[3] = 9;
        cart.bank_registers[4] = 10;
        cart.bank_registers[5] = 11;

        // Normal mode mapping checks
        cart.chr_mode = Mode::Normal;
        assert_eq!(
            chr_mem_page_index(0 * SIZE_1K as u16, cart.chr_mode, &cart.bank_registers),
            cart.bank_registers[0] as usize
        );
        assert_eq!(
            chr_mem_page_index(1 * SIZE_1K as u16, cart.chr_mode, &cart.bank_registers),
            cart.bank_registers[0] as usize + 1
        );
        assert_eq!(
            chr_mem_page_index(2 * SIZE_1K as u16, cart.chr_mode, &cart.bank_registers),
            cart.bank_registers[1] as usize
        );

        // Inverted mode mapping checks
        cart.chr_mode = Mode::Inverted;
        assert_eq!(
            chr_mem_page_index(0 * SIZE_1K as u16, cart.chr_mode, &cart.bank_registers),
            cart.bank_registers[2] as usize
        );
        assert_eq!(
            chr_mem_page_index(4 * SIZE_1K as u16, cart.chr_mode, &cart.bank_registers),
            cart.bank_registers[0] as usize
        );
    }

    #[test]
    fn has_chr_ram_and_indices_helpers() {
        let cart_with_chr = build_cart(1, 1);
        assert!(!cart_with_chr.has_chr_ram()); // has_chr_ram returns true when chr_mem.len() == 0

        let cart1 = build_cart(3, 0);
        // For 3 pages indices are 0,1,2
        assert_eq!(cart1.last_prg_rom_page_index(), 2);
        assert_eq!(cart1.second_to_last_prg_rom_page_index(), 1);
    }

    #[test]
    fn name_table_addr_space_and_init() {
        // static size
        assert_eq!(
            NameTableRam::addr_space_size(),
            (NAME_TABLE_PAGE_SIZE as u32) * 4
        );

        // dynamic size
        let nt = NameTableRam::default();
        assert_eq!(nt.addr_space_size_dyn(), (NAME_TABLE_PAGE_SIZE as u32) * 4);

        // init_data fills pages correctly
        let data = build_pages();
        let mut nt2 = NameTableRam::default();
        nt2.init_data(&data);
        // default horizontal: 0x000 and 0x400 map to same page (val 0x00)
        assert_eq!(nt2.read(0x000), 0x00);
        assert_eq!(nt2.read(0x400), 0x00);
        // four screen direct mapping after set_four_screen
        nt2.set_four_screen();
        assert_eq!(nt2.read(0x800), 0x22);
    }

    #[test]
    fn set_four_screen_prevents_changes() {
        let data = build_pages();
        let mut nt = NameTableRam::with_data(&data);
        nt.set_four_screen();
        // attempts to change mode should not affect four-screen
        nt.set_horizontal();
        nt.set_vertical();
        // still four screen mapping
        assert_eq!(nt.read(0x000), 0x00);
        assert_eq!(nt.read(0x400), 0x11);
        assert_eq!(nt.read(0x800), 0x22);
        assert_eq!(nt.read(0xC00), 0x33);
    }

    fn build_cart_with_prg_ram(prg_pages: usize) -> Cart<Ram<SIZE_8K>> {
        let mut prg = Vec::new();
        for i in 0..prg_pages {
            let data = vec![i as u8; PRG_ROM_PAGE_SIZE];
            prg.push(Rom::<PRG_ROM_PAGE_SIZE>::with_data(&data));
        }

        Cart {
            prg_rom: prg,
            bank_select: 0,
            bank_registers: [0u8; 8],
            prg_mode: Mode::Normal,
            chr_mode: Mode::Normal,
            is_ram_writable: false,
            ..Default::default()
        }
    }

    #[test]
    fn write_cpu_mapped_bank_select_and_data_via_wrapper() {
        let mut cart = build_cart(4, 8);
        // write bank select via even CPU-mapped address (0x8000)
        let sel_addr = (0x8000 - CART_CPU_MAP_BEGIN_ADDR) as u16;
        // set bits 6 and 7 to enable PRG and CHR inversion
        cart.write_cpu_mapped(0xC0, sel_addr);
        assert_eq!(cart.bank_select, 0xC0 % 8);
        assert_eq!(cart.prg_mode, Mode::Inverted);
        assert_eq!(cart.chr_mode, Mode::Inverted);

        // now write bank data via odd address (0x8001)
        let data_addr = (0x8001 - CART_CPU_MAP_BEGIN_ADDR) as u16;
        cart.write_cpu_mapped(3, data_addr);
        assert_eq!(cart.bank_registers[cart.bank_select as usize], 2);
    }

    #[test]
    fn write_cpu_mapped_mirroring_and_prg_ram_write_enable() {
        let mut cart = build_cart_with_prg_ram(2);
        // set vertical first
        cart.name_tables_ram.set_vertical();
        // set horizontal via even write to 0xA000 (bit0 == 1 => horizontal)
        let a_even = (0xA000 - CART_CPU_MAP_BEGIN_ADDR) as u16;
        cart.write_cpu_mapped(1, a_even);
        // horizontal: 0x000 and 0x400 map to same page (mirrored horizontally means pages 0/1 mirror?)
        assert_eq!(
            cart.read_ppu_mapped(0x2000),
            cart.read_ppu_mapped(0x2000 + 0x400)
        );

        // enable PRG RAM writing via odd address 0xA001 with bit7 set
        let a_odd = (0xA001 - CART_CPU_MAP_BEGIN_ADDR) as u16;
        cart.write_cpu_mapped(0x80, a_odd); // bit7 set -> writable
                                            // write to PRG RAM region via write_cpu_mapped at 0x6000
        let ram_write_addr = (0x6000 - CART_CPU_MAP_BEGIN_ADDR) as u16;
        cart.write_cpu_mapped(0x7A, ram_write_addr);
        // read back from same address
        let val = cart.read_cpu_mapped(ram_write_addr);
        assert_eq!(val, 0x7A);

        // disable writing and ensure writes ignored
        cart.write_cpu_mapped(0x00, a_odd); // bit7 clear -> not writable
        cart.write_cpu_mapped(0x55, ram_write_addr);
        let val2 = cart.read_cpu_mapped(ram_write_addr);
        assert_eq!(val2, 0x7A);
    }

    #[test]
    fn read_write_ppu_mapped_chr_and_name_table() {
        // test with vector-backed CHR
        let mut cart = build_cart(4, 8);
        cart.bank_registers[0] = 4;
        cart.chr_mode = Mode::Normal;
        let chr_val = cart.read_ppu_mapped(0x0000);
        assert_eq!(chr_val, 4u8);

        // write to name table via PPU mapped write
        let nt_write_res = cart.write_ppu_mapped(0xAB, 0x2000);
        assert_eq!(nt_write_res, ChrRomContentStatus::Unchanged);
        assert_eq!(cart.read_ppu_mapped(0x2000), 0xAB);
    }

    fn cart_addr(cpu_addr: u16) -> u16 {
        cpu_addr - CART_CPU_MAP_BEGIN_ADDR
    }

    #[test]
    fn prg_rom_normal_mode_full_layout() {
        // 4 PRG pages, expected layout in Normal mode:
        //   $8000..$9FFF -> R6 (switchable)
        //   $A000..$BFFF -> R7 (switchable)
        //   $C000..$DFFF -> second-to-last page (index 2)
        //   $E000..$FFFF -> last page (index 3)
        let mut cart = build_cart(4, 8);
        cart.bank_registers[6] = 0;
        cart.bank_registers[7] = 1;
        cart.prg_mode = Mode::Normal;

        assert_eq!(cart.read_prg_rom(0 * SIZE_8K as u16), 0u8); // page 0
        assert_eq!(cart.read_prg_rom(1 * SIZE_8K as u16), 1u8); // page 1
        assert_eq!(cart.read_prg_rom(2 * SIZE_8K as u16), 2u8); // fixed second-to-last
        assert_eq!(cart.read_prg_rom(3 * SIZE_8K as u16), 3u8); // fixed last
    }

    #[test]
    fn prg_rom_inverted_mode_full_layout() {
        // Same cart but with PRG mode = Inverted:
        //   $8000..$9FFF -> second-to-last page (index 2)
        //   $A000..$BFFF -> R7 (switchable)
        //   $C000..$DFFF -> R6 (switchable)
        //   $E000..$FFFF -> last page (index 3)
        let mut cart = build_cart(4, 8);
        cart.bank_registers[6] = 0;
        cart.bank_registers[7] = 1;
        cart.prg_mode = Mode::Inverted;

        assert_eq!(cart.read_prg_rom(0 * SIZE_8K as u16), 2u8); // fixed second-to-last
        assert_eq!(cart.read_prg_rom(1 * SIZE_8K as u16), 1u8); // R7
        assert_eq!(cart.read_prg_rom(2 * SIZE_8K as u16), 0u8); // R6
        assert_eq!(cart.read_prg_rom(3 * SIZE_8K as u16), 3u8); // fixed last
    }

    #[test]
    fn write_bank_data_chr_pair_clears_lsb() {
        // Writing to a 2KB CHR pair (bank 0 or 1) must clear the LSB so the
        // bank points at the start of a 2KB-aligned pair.
        let mut cart = build_cart(4, 8);
        cart.bank_select = 0;
        cart.write_bank_data(5); // odd value should become even
        assert_eq!(cart.bank_registers[0], 4);

        cart.bank_select = 1;
        cart.write_bank_data(7);
        assert_eq!(cart.bank_registers[1], 6);
    }

    #[test]
    fn write_bank_data_chr_single_keeps_value() {
        // 1KB CHR banks (bank 2..5) keep the written value modulo page_count.
        let mut cart = build_cart(4, 8);
        cart.bank_select = 2;
        cart.write_bank_data(5);
        assert_eq!(cart.bank_registers[2], 5);

        cart.bank_select = 5;
        cart.write_bank_data(7);
        assert_eq!(cart.bank_registers[5], 7);
    }

    #[test]
    fn write_bank_data_prg_modulo_page_count() {
        // PRG bank writes wrap around the available PRG ROM page count.
        let mut cart = build_cart(4, 8);
        cart.bank_select = 6;
        cart.write_bank_data(7); // 7 % 4 == 3
        assert_eq!(cart.bank_registers[6], 3);

        cart.bank_select = 7;
        cart.write_bank_data(9); // 9 % 4 == 1
        assert_eq!(cart.bank_registers[7], 1);
    }

    /// Regression test: 256-page CHR ROM (256 KB, the MMC3 maximum) must not
    /// cause `write_bank_data` to panic from `% 0`. The previous
    /// implementation returned `page_count` as `u8`, which silently overflows
    /// to 0 for a 256-element `Vec`, and the modulo-by-zero panicked on the
    /// very first CHR bank register write.
    #[test]
    fn write_bank_data_chr_with_256_pages_does_not_panic() {
        let mut cart = build_cart(2, 256);

        // bank_select = 0 (CHR 2KB pair 0): LSB is cleared.
        cart.bank_select = 0;
        cart.write_bank_data(0xFF); // 0xFF % 256 == 0xFF, then & !1 == 0xFE
        assert_eq!(cart.bank_registers[0], 0xFE);

        // bank_select = 3 (CHR 1KB): value kept modulo page count.
        cart.bank_select = 3;
        cart.write_bank_data(0xFF); // 0xFF % 256 == 0xFF
        assert_eq!(cart.bank_registers[3], 0xFF);

        // bank_select = 5 (CHR 1KB): another modulo, confirms no overflow.
        cart.bank_select = 5;
        cart.write_bank_data(200); // 200 % 256 == 200
        assert_eq!(cart.bank_registers[5], 200);

        // page_count itself must report 256 exactly.
        assert_eq!(cart.chr_mem.page_count(), 256);
    }

    #[test]
    fn irq_default_inactive() {
        let cart = build_cart(2, 4);
        assert!(!cart.irq_pin());
        assert!(!cart.irq_active);
        assert!(!cart.irq_enable);
    }

    #[test]
    fn irq_enable_disable_via_cpu_mapped() {
        let mut cart = build_cart(2, 4);
        // Even address at $E000 acknowledges and disables the IRQ.
        cart.write_cpu_mapped(0x00, cart_addr(0xE000));
        assert!(!cart.irq_enable);
        assert!(!cart.irq_active);

        // Odd address at $E001 re-enables IRQ (but does not assert it).
        cart.write_cpu_mapped(0x00, cart_addr(0xE001));
        assert!(cart.irq_enable);
        assert!(!cart.irq_active);
    }

    #[test]
    fn irq_latch_and_reload_flag() {
        let mut cart = build_cart(2, 4);

        // Latch a reload value via even $C000 write.
        cart.write_cpu_mapped(0x05, cart_addr(0xC000));
        assert_eq!(cart.irq_latch, 0x05);

        // Arm the reload via odd $C001 write.
        cart.write_cpu_mapped(0x00, cart_addr(0xC001));
        assert!(cart.irq_reload_flag);

        // First A12 rising edge reloads and clears the flag.
        cart.read_ppu_mapped(0x0000);
        cart.read_ppu_mapped(0x1000);
        assert_eq!(cart.irq_counter, 0x05);
        assert!(!cart.irq_reload_flag);
    }

    #[test]
    fn irq_a12_rising_edge_decrements_counter() {
        let mut cart = build_cart(2, 4);
        cart.irq_latch = 0x10;
        cart.irq_counter = 0x10;
        cart.irq_enable = true;

        // Each rising edge of A12 should decrement the counter by one.
        for _ in 0..0x10 {
            cart.read_ppu_mapped(0x0000); // a12 low (no edge)
            cart.read_ppu_mapped(0x1000); // a12 high -> rising edge -> decrement
        }

        // After all decrements the counter reached zero and IRQ is asserted.
        assert_eq!(cart.irq_counter, 0);
        assert!(cart.irq_pin());
    }

    #[test]
    fn irq_not_asserted_when_disabled() {
        let mut cart = build_cart(2, 4);
        cart.irq_latch = 0x01;
        cart.irq_counter = 0x01;
        cart.irq_enable = false;

        cart.read_ppu_mapped(0x0000);
        cart.read_ppu_mapped(0x1000); // rising edge: counter -> 0
        assert_eq!(cart.irq_counter, 0);
        // IRQ pin is not asserted because the IRQ is disabled.
        assert!(!cart.irq_pin());
    }

    #[test]
    fn irq_falling_edge_does_not_decrement() {
        let mut cart = build_cart(2, 4);
        cart.irq_latch = 0x10;
        cart.irq_counter = 0x10;

        // Prime prev_a12 by reading with A12 low first (no edge, sets prev=false).
        cart.read_ppu_mapped(0x0000);
        // Now the next read with A12 high is a rising edge.
        cart.read_ppu_mapped(0x1000);
        assert_eq!(cart.irq_counter, 0x0F);
        // A subsequent read with A12 low is a falling edge and must not change the counter.
        cart.read_ppu_mapped(0x0000);
        assert_eq!(cart.irq_counter, 0x0F);
        // Another rising edge decrements again.
        cart.read_ppu_mapped(0x1000);
        assert_eq!(cart.irq_counter, 0x0E);
    }

    #[test]
    fn irq_counter_reloads_on_zero_or_reload_flag() {
        // When the counter reaches 0 and no reload flag is armed, the next
        // rising edge reloads from the latch. This is how the counter cycles.
        let mut cart = build_cart(2, 4);
        cart.irq_latch = 0x03;
        cart.irq_counter = 0x03;
        cart.irq_enable = false;

        // Each rising edge decrements the counter by one starting from 3.
        let expected_after_each_edge = [0x02u8, 0x01, 0x00];
        for &expected in &expected_after_each_edge {
            cart.read_ppu_mapped(0x0000);
            cart.read_ppu_mapped(0x1000);
            assert_eq!(cart.irq_counter, expected);
        }

        // The next edge reloads the counter from the latch (counter was 0).
        cart.read_ppu_mapped(0x0000);
        cart.read_ppu_mapped(0x1000);
        assert_eq!(cart.irq_counter, 0x03);
    }

    #[test]
    fn irq_acknowledge_clears_pin() {
        let mut cart = build_cart(2, 4);
        cart.irq_latch = 0x01;
        cart.irq_counter = 0x01;
        cart.irq_enable = true;

        cart.read_ppu_mapped(0x0000);
        cart.read_ppu_mapped(0x1000); // counter -> 0, IRQ asserted
        assert!(cart.irq_pin());

        // Acknowledging via $E000 clears the pin and disables further IRQs.
        cart.write_cpu_mapped(0x00, cart_addr(0xE000));
        assert!(!cart.irq_pin());
        assert!(!cart.irq_enable);
    }

    #[test]
    fn requires_cycle_accurate_sprites() {
        let cart = build_cart(2, 4);
        assert!(cart.requires_cycle_accurate_sprites());
    }

    #[test]
    fn should_reload_and_set_irq_every_clock_when_reload_is_zero() {
        let mut cart = build_cart(2, 4);
        // Latch = 0 (reload value is 0)
        cart.write_cpu_mapped(0x00, cart_addr(0xC000));
        // Enable IRQ
        cart.write_cpu_mapped(0x00, cart_addr(0xE001));
        assert!(cart.irq_enable);
        assert!(!cart.irq_active);

        // Every A12 rising edge should reload counter (to 0) and assert IRQ.
        for _ in 0..16 {
            cart.read_ppu_mapped(0x0000); // A12 low (no rising edge)
            assert!(!cart.irq_pin());
            cart.read_ppu_mapped(0x1000); // A12 high (rising edge)
            assert!(
                cart.irq_pin(),
                "IRQ should be asserted after A12 rising edge"
            );
            assert_eq!(
                cart.irq_counter, 0x00,
                "counter should reload to 0 (latch value)"
            );

            // Acknowledge IRQ; subsequent rising edges should not assert IRQ
            // because $E000 also disables IRQ. Re-enable to continue.
            cart.write_cpu_mapped(0x00, cart_addr(0xE000));
            assert!(!cart.irq_pin());
            cart.write_cpu_mapped(0x00, cart_addr(0xE001));
        }
    }

    /// Regression test: MMC3 ROMs with the maximum legal CHR ROM size
    /// (32 × 8 KB = 256 KB, e.g. Wario's Woods) must load successfully. The
    /// earlier cap of 255 × 1 KB = 255 KB silently rejected them.
    #[test]
    fn load_accepts_max_chr_rom_size() {
        use crate::rom_loader::ines::HeaderData;

        // header[5] = 32 → 32 × 8 KB = 256 KB CHR ROM.
        // mapper = 4 (MMC3), mirroring = horizontal.
        let mut header = [0u8; 16];
        header[0..4].copy_from_slice(b"NES\x1A");
        header[4] = 4; // 4 × 16 KB = 64 KB PRG
        header[5] = 32; // 32 × 8 KB = 256 KB CHR ROM
        header[6] = 0b0100_0000; // mapper_lo = 4
        header[7] = 0x00;
        let header_data = HeaderData::new(&header);

        let prg = vec![0u8; header_data.prg_rom_size as usize];
        let chr = vec![0u8; header_data.chr_rom_size as usize];

        // Build a reader yielding PRG then CHR.
        let mut payload = Vec::new();
        payload.extend_from_slice(&prg);
        payload.extend_from_slice(&chr);

        let cart = load(&header_data, &mut payload.as_slice());
        assert!(
            cart.is_ok(),
            "MMC3 with 256 KB CHR ROM must load: got {}",
            if cart.is_err() { "Err" } else { "Ok" }
        );
    }

    /// Sanity check that the chr-rom-size error message identifies the right
    /// mapper (the old copy-pasted message wrongly said "basic mapper").
    #[test]
    fn load_error_message_references_mapper_004() {
        use crate::rom_loader::ines::HeaderData;

        let mut header = [0u8; 16];
        header[0..4].copy_from_slice(b"NES\x1A");
        header[4] = 2;
        header[5] = 255; // 255 × 8 KB = 2040 KB, well over the 256 KB cap
        header[6] = 0b0100_0000;
        header[7] = 0x00;
        let header_data = HeaderData::new(&header);

        // Empty body is fine; validation runs before any read.
        let mut empty: &[u8] = &[];
        let result = load(&header_data, &mut empty);
        let err = match result {
            Ok(_) => panic!("expected an error for oversized CHR ROM"),
            Err(e) => e,
        };
        let msg = format!("{err}");
        assert!(
            msg.contains("mapper 004"),
            "error should name mapper 004, got: {msg}"
        );
        assert!(
            !msg.contains("basic mapper"),
            "error should not say basic mapper, got: {msg}"
        );
    }
}