rustynes_mappers/

lib.rs

// SPDX-License-Identifier: GPL-3.0-or-later
//
// Provenance: this crate root contains code derived from puNES (GPL-2.0-or-later) — the JV001 security chip / mapper 147, ported from `JV001.c` / `mapper_147.c` — and from FCEUX / Mesen2 for UNIF board dispatch. See docs/originality-and-provenance.md (Section 1)
// and NOTICE for the complete, audited derivation record.
//! Cartridge file format (iNES + NES 2.0) parsing and mapper implementations.
//!
//! See `docs/mappers.md` and `docs/cartridge-format.md` for the implementation
//! specs, and `ref-docs/research-report.md` §Cartridge for the source material.
//!
//! Supports a broad set of mapper families covering the great majority of the
//! licensed NES library: `NROM`, `MMC1`, `MMC2`/`MMC4`, `MMC3` (Sharp default,
//! NEC submapper), `MMC5` (with vertical split-screen, `ExGrafix`, 4-byte fill
//! mode, dual sprite/BG CHR for 8×16 sprites), `UxROM`, `CNROM`, `AxROM`,
//! `GxROM`, Color Dreams, `CPROM`, `BNROM`/`NINA` (mapper 34 variants),
//! Camerica `BF9093`, `VRC1`, `VRC2`/`VRC4` (shared superset,
//! submapper-dispatched), `VRC3`, `VRC6`, `VRC7` (banking and IRQ; FM audio
//! deferred per `docs/adr/0004-vrc7-audio-deferred.md`), Sunsoft `FME-7`,
//! Namco 163, the Bandai discrete and FCG family, Jaleco SS88006, plus the
//! v2.1.0 Tier 2 boards Tengen RAMBO-1 (64), Irem H3001 (65), Sunsoft-3 (67),
//! Sunsoft-4 (68, CHR-ROM nametables), Holy Diver / Cosmo Carrier (78),
//! TxSROM/TLSROM (118, per-bank nametable mirroring), and Namco 175/340 (210),
//! and the v2.6.0 boards including the Nintendo Vs. System (99), the Taito
//! X1-005 (80, on-cart battery RAM) / X1-017 (82, CHR A12-inversion mode), and
//! Konami VS / VRC1-on-Vs. (151).

#![no_std]
// The chip stack carries no `unsafe`; `forbid` makes that a compile-time
// guarantee rather than an observation (core audit section 2.1). The FFI
// and platform `unsafe` lives in the frontend, cheevos and mobile crates.
#![forbid(unsafe_code)]
#![warn(missing_docs)]
// The expansion-audio synth cores (VRC6/VRC7/FDS/MMC5/N163/5B) live in their
// owning mapper modules but are reused by the NSF expansion-audio router
// (`nsf_expansion`). Exposing them `pub(crate)` from private modules is the
// intended cross-module reuse pattern, so the redundant-pub-crate lint
// (which assumes `pub(crate)` in a private module is a mistake) is wrong here.
#![allow(clippy::redundant_pub_crate)]

extern crate alloc;

#[cfg(test)]
extern crate std;

use alloc::{boxed::Box, string::ToString};

mod a12_filter;
mod bmc_simple;
mod cartridge;
mod fds;
mod header;
mod homebrew_boards;
mod jaleco_discrete;
mod kaiser;
mod m000_nrom;
mod m001_mmc1;
mod m002_uxrom;
mod m003_cnrom;
mod m004_mmc3;
mod m005_mmc5;
mod m007_axrom;
mod m009_mmc2;
mod m010_mmc4;
mod m011_color_dreams;
mod m013_cprom;
mod m016_bandai_fcg;
mod m018_jaleco_ss88006;
mod m019_namco163;
mod m021_vrc4;
mod m022_vrc2;
mod m024_vrc6;
mod m032_irem_g101;
mod m033_taito_tc0190;
mod m034_bnrom_nina001;
mod m035_jy_asic;
mod m036_txc_policeman;
mod m038_bitcorp38;
mod m039_subor39;
mod m041_caltron41;
mod m042_fds_conv_bio_miracle;
mod m048_taito_tc0690;
mod m050_fds_conv_smb2j;
mod m064_rambo1;
mod m065_irem_h3001;
mod m066_gxrom;
mod m067_sunsoft3;
mod m068_sunsoft4;
mod m069_sunsoft_fme7;
mod m070_bandai74;
mod m071_camerica_bf9093;
mod m073_vrc3;
mod m075_vrc1;
mod m076_namcot3446;
mod m077_irem_napoleon;
mod m078_irem_jaleco78;
mod m079_ave_nina03_06;
mod m080_taito_x1_005;
mod m082_taito_x1_017;
mod m083_cony;
mod m085_vrc7;
mod m087_jaleco87;
mod m088_namco118;
mod m089_sunsoft2;
mod m091_jy_sf3;
mod m093_sunsoft3r;
mod m094_un1rom;
mod m095_namcot3425;
mod m096_bandai96;
mod m097_irem_tam_s1;
mod m099_vs_system;
mod m105_nes_event;
mod m107_magic_dragon107;
mod m113_ave_nina006;
mod m118_txsrom;
mod m119_tqrom;
mod m132_txc_22211;
mod m136_sachen_3011;
mod m151_konami_vs;
mod m152_bandai152;
mod m156_daou156;
mod m163_nanjing;
mod m176_bmc_fk23c;
mod m177_hengedianzi;
mod m179_hengedianzi;
mod m180_nichibutsu180;
mod m184_sunsoft1;
mod m185_cnrom185;
mod m210_namco175;
mod m228_action52;
mod m232_camerica_bf9096;
mod m240_cne_multicart;
mod m241_bxrom241;
mod m244_cne_decathlon;
mod m246_fong_shen_bang246;
mod m250_nitra250;
mod m268_bmc_coolboy;
mod m513_sachen_9602;
mod mapper;
mod mmc3_boards;
mod mmc3_clones;
mod multicart_discrete;
mod nsf;
mod nsf_expansion;
mod ntdec;
mod sachen_8259;
mod sachen_discrete;
mod sst39sf040;
mod tier;
mod unif;
mod waixing;

pub use bmc_simple::{new_m164, new_m261, new_m286, new_m289, new_m320, new_m336, new_m349};
pub use cartridge::{Cartridge, ConsoleType, Mirroring, Region, RomError, VsPpuPalette, VsPpuType};
pub use fds::{
    DISK_BYTE_CYCLES, FDS_SIDE_LEN, Fds, FdsDisk, FdsQuirk, FdsTraceRec, HEAD_RESEEK_CYCLES,
    fds_crc32, parse_fds, quirk_for_crc,
};
pub use header::{
    ExpansionDevice, ExtendedConsoleType, Header, VsHardwareType, parse_header,
    serialize_header_preserving,
};
pub use homebrew_boards::{Action53M28, Cufrom29, Gtrom111, Inl31, MagicFloor218, Unrom512M30};
pub use jaleco_discrete::{Jaleco72, Jaleco86, Jaleco92, Jaleco101, Jaleco140};
pub use kaiser::{new_m56, new_m142, new_m303, new_m305, new_m306, new_m312};
pub use m000_nrom::Nrom;
pub use m001_mmc1::Mmc1;
pub use m002_uxrom::UxRom;
pub use m003_cnrom::CnRom;
pub use m004_mmc3::{Mmc3, Mmc3Revision, Mmc3Variant};
pub use m005_mmc5::Mmc5;
pub use m007_axrom::AxRom;
pub use m009_mmc2::Mmc2;
pub use m010_mmc4::Mmc4;
pub use m011_color_dreams::ColorDreams;
pub use m013_cprom::Cprom;
pub use m016_bandai_fcg::{BandaiFcg, FcgVariant};
pub use m018_jaleco_ss88006::JalecoSs88006;
pub use m019_namco163::Namco163;
pub use m021_vrc4::Vrc4;
pub use m022_vrc2::Vrc2;
pub use m024_vrc6::Vrc6;
pub use m032_irem_g101::IremG101;
pub use m033_taito_tc0190::TaitoTc0190;
pub use m034_bnrom_nina001::{M34, M34Variant};
pub use m035_jy_asic::{JyAsic, JyBoard};
pub use m036_txc_policeman::Txc36;
pub use m038_bitcorp38::Bitcorp38;
pub use m039_subor39::Subor39;
pub use m041_caltron41::Caltron41;
pub use m042_fds_conv_bio_miracle::Mapper42;
pub use m048_taito_tc0690::TaitoTc0690;
pub use m050_fds_conv_smb2j::Mapper50;
pub use m064_rambo1::Rambo1;
pub use m065_irem_h3001::IremH3001;
pub use m066_gxrom::GxRom;
pub use m067_sunsoft3::Sunsoft3;
pub use m068_sunsoft4::Sunsoft4;
pub use m069_sunsoft_fme7::Fme7;
pub use m070_bandai74::Bandai74;
pub use m071_camerica_bf9093::Camerica;
pub use m073_vrc3::Vrc3;
pub use m075_vrc1::Vrc1;
pub use m076_namcot3446::Namcot3446M76;
pub use m077_irem_napoleon::Irem77;
pub use m078_irem_jaleco78::{M78, M78Variant};
pub use m079_ave_nina03_06::Nina0379;
pub use m080_taito_x1_005::TaitoX1005;
pub use m082_taito_x1_017::TaitoX1017;
pub use m083_cony::Cony83;
pub use m085_vrc7::Vrc7;
pub use m087_jaleco87::Jaleco87;
pub use m088_namco118::{Namco118, Namco118Board};
pub use m089_sunsoft2::Sunsoft2;
pub use m091_jy_sf3::Jy91;
pub use m093_sunsoft3r::Sunsoft3r;
pub use m094_un1rom::Un1rom94;
pub use m095_namcot3425::Namcot3425M95;
pub use m096_bandai96::Bandai96;
pub use m097_irem_tam_s1::Irem97;
pub use m099_vs_system::VsSystem;
pub use m105_nes_event::{NWC_TOURNAMENT_DIP, NesEvent105};
pub use m107_magic_dragon107::MagicDragon107;
pub use m113_ave_nina006::Nina006M113;
pub use m118_txsrom::TxSrom;
pub use m119_tqrom::Tqrom;
pub use m132_txc_22211::Txc132;
pub use m136_sachen_3011::new_m136;
pub use m151_konami_vs::KonamiVs;
pub use m152_bandai152::Bandai152;
pub use m156_daou156::Daou156;
pub use m163_nanjing::Nanjing163;
pub use m176_bmc_fk23c::new_m176;
pub use m177_hengedianzi::Hengedianzi177;
pub use m179_hengedianzi::Hengedianzi179;
pub use m180_nichibutsu180::Nichibutsu180;
pub use m184_sunsoft1::Sunsoft1;
pub use m185_cnrom185::CnRom185;
pub use m210_namco175::{Namco175, Namco175Board};
pub use m228_action52::Action52M228;
pub use m232_camerica_bf9096::Camerica232;
pub use m240_cne_multicart::Cne240;
pub use m241_bxrom241::Bxrom241;
pub use m244_cne_decathlon::Decathlon244;
pub use m246_fong_shen_bang246::FongShenBang246;
pub use m250_nitra250::Nitra250;
pub use m268_bmc_coolboy::new_m268;
pub use m513_sachen_9602::new_m513;
pub use mapper::{
    BgSplitState, ExAttribute, Mapper, MapperCaps, MapperDebugInfo, MapperError, MapperFrameEvents,
    mirroring_name,
};
pub use mmc3_boards::{Board as Mmc3BoardKind, Mmc3Board};
pub use mmc3_clones::{
    Mmc3CloneMapper, new_m44, new_m49, new_m52, new_m115, new_m134, new_m189, new_m205, new_m238,
    new_m245, new_m348, new_m366,
};
pub use multicart_discrete::{
    DiscreteBoard, DiscreteMapper, Maxi15M234, Multicart15, Multicart58, Multicart60, Multicart61,
    Multicart62, Multicart200, Multicart201, Multicart202, Multicart203, Multicart212,
    Multicart213, Multicart214, Multicart225, Multicart226, Multicart227, Multicart229,
    Multicart231, Multicart233, new_m46, new_m51, new_m57, new_m104, new_m120, new_m204, new_m290,
    new_m299, new_m301,
};
pub use nsf::{Nsf, NsfMapper, is_nsf, parse_nsf};
pub use ntdec::{Ntdec63, Ntdec81, Ntdec174, Ntdec2722M40, NtdecAsder112, new_m193, new_m221};
pub use sachen_8259::{Sachen8259, Sachen8259M137, Sachen8259Variant};
pub use sachen_discrete::{
    Sa020aBoard, Sachen133, Sachen145, Sachen146, Sachen148, Sachen149, Sachen150, Sachen3018M147,
    SachenTca01M143,
};
pub use tier::{MapperTier, mapper_tier};
pub use unif::{UnifError, UnifImage, board_to_mapper, parse_unif, unif_to_ines};
pub use waixing::{Waixing178, Waixing242, WaixingFs304M162, new_m253};

/// Returns the crate version string.
#[must_use]
pub const fn version() -> &'static str {
    env!("CARGO_PKG_VERSION")
}

/// Build one of the v2.9.6 MMC3 boards (`mmc3_boards.rs`) from a parsed header.
///
/// Work RAM and the CHR-RAM overlay are taken from the header only when it is
/// NES 2.0: iNES 1.0 reports a nominal 8 KiB of PRG-RAM for every image
/// (`header.rs`), which would put RAM on multicarts that have a register in
/// that window instead. Each board then falls back to its own documented
/// default (`Board::default_wram` / `Board::overlay_bytes`).
fn mmc3_board(
    kind: Mmc3BoardKind,
    prg_rom: Box<[u8]>,
    chr_rom: Box<[u8]>,
    h: &Header,
) -> Result<Box<dyn Mapper>, RomError> {
    let (wram, chr_ram) = if h.is_nes2 {
        (h.prg_ram_window() as usize, h.chr_ram_size as usize)
    } else {
        (0, 0)
    };
    Ok(Box::new(
        Mmc3Board::new(kind, prg_rom, chr_rom, h.mirroring, wram, chr_ram)
            .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
    ))
}

/// Parse an iNES 1.0 / NES 2.0 ROM file.
///
/// Validates the magic, detects the format, applies the appropriate sizing
/// rules, slices out the trainer (if any), PRG-ROM, and CHR-ROM, and returns
/// a fully populated [`Cartridge`] plus a constructed `dyn Mapper` ready for
/// the bus to consume.
///
/// # Errors
///
/// - [`RomError::Truncated`] if the file is shorter than the declared sections.
/// - [`RomError::BadMagic`] if the first 4 bytes are not `"NES\x1A"`.
/// - [`RomError::UnsupportedMapper`] if the mapper id is outside the supported
///   set listed at crate level.
/// - [`RomError::InvalidConfig`] for inconsistent header fields (e.g.,
///   exponent overflow).
#[allow(clippy::too_many_lines)]
pub fn parse(bytes: &[u8]) -> Result<(Cartridge, Box<dyn Mapper>), RomError> {
    // Famicom Disk System: a `.fds` disk image carries no embedded BIOS, so it
    // cannot be constructed through the ordinary cartridge path (which has no
    // `disksys.rom` to hand it). The real disk path is `crate::fds::parse_fds`
    // plus `rustynes_core::Nes::from_disk(disk_bytes, bios_bytes)`. Detect the two
    // on-disk forms here — the fwNES container (`"FDS\x1A"` magic) and a raw
    // 65500-byte disk side whose first block opens with `\x01*NINTENDO-HVC*` —
    // and return [`RomError::FdsUnsupported`] so a frontend that has not yet
    // wired `from_disk` (no BIOS prompt) gets a clear message instead of a
    // generic bad-magic error. FDS Stage 1 (drive + BIOS + IRQ/timing) landed
    // in v2.2.0; audio + write + persistence are Stage 2. See `fds.rs`.
    if bytes.len() >= 4 && &bytes[0..4] == b"FDS\x1A" {
        return Err(RomError::FdsUnsupported);
    }
    if bytes.len() >= 15 && bytes[0] == 0x01 && &bytes[1..15] == b"*NINTENDO-HVC*" {
        return Err(RomError::FdsUnsupported);
    }

    // NSF music files (`"NESM\x1A"`) have no iNES header and no PPU program;
    // they run through the dedicated `rustynes_core::Nes::from_nsf` path (which
    // builds an `NsfMapper`), not this cartridge parser. Detect the magic here
    // and return a clear message so a frontend that hands NSF bytes to `parse`
    // by mistake gets a routing hint instead of a generic bad-magic error.
    if nsf::is_nsf(bytes) {
        return Err(RomError::InvalidConfig(
            "NSF music file — load via Nes::from_nsf, not parse()".into(),
        ));
    }

    // UNIF container (`"UNIF"` magic): resolve the MAPR board name to an iNES
    // mapper, synthesize an equivalent NES 2.0 image, and parse that through the
    // standard path below — reusing all mapper construction + Cartridge assembly
    // (v1.6.0 Workstream E2). The synthetic image carries `"NES\x1A"` magic, so
    // it never re-enters this branch.
    if bytes.len() >= 4 && &bytes[0..4] == unif::UNIF_MAGIC {
        let img = unif::parse_unif(bytes).map_err(|e| RomError::InvalidConfig(e.to_string()))?;
        return parse(&unif::unif_to_ines(&img));
    }

    let h = parse_header(bytes)?;

    let mut cursor = header::HEADER_LEN;
    if h.has_trainer {
        if bytes.len() < cursor + header::TRAINER_LEN {
            return Err(RomError::Truncated {
                needed: cursor + header::TRAINER_LEN,
                got: bytes.len(),
            });
        }
        cursor += header::TRAINER_LEN;
    }

    if bytes.len() < cursor + h.prg_size {
        return Err(RomError::Truncated {
            needed: cursor + h.prg_size,
            got: bytes.len(),
        });
    }
    let prg_rom: Box<[u8]> = bytes[cursor..cursor + h.prg_size]
        .to_vec()
        .into_boxed_slice();
    cursor += h.prg_size;

    if bytes.len() < cursor + h.chr_size {
        return Err(RomError::Truncated {
            needed: cursor + h.chr_size,
            got: bytes.len(),
        });
    }
    let chr_rom: Box<[u8]> = bytes[cursor..cursor + h.chr_size]
        .to_vec()
        .into_boxed_slice();

    // Tail bytes beyond declared PRG+CHR are ignored for iNES 1.0; in NES 2.0
    // they are the optional misc-ROM block which we do not surface yet.

    // Arcade-platform (Vs. System / PlayChoice-10) detection drives the RGB
    // PPU palette. Two signals, applied in order:
    //
    // 1. **Mapper-driven** (the most robust): mapper 99 (Vs. DualSystem CHR
    //    bank) and mapper 151 (Konami VRC1 on a Vs. board) are Vs.-only — no
    //    licensed home game uses either — so a cart bearing one is forced to
    //    `ConsoleType::VsSystem` + the 2C03 RGB PPU (the most common Vs. PPU)
    //    whenever the header did not already carry a resolved Vs. PPU type.
    //
    // 2. **Clean-byte-7 arcade flag** (real No-Intro arcade dumps): a genuine
    //    Vs./PC10 dump is clean iNES 1.0 with byte 7 EXACTLY `0x01` (Vs.) or
    //    `0x02` (PC10) — NOT NES 2.0, mapper-hi-nibble 0. We accept ONLY those
    //    two exact values on a non-NES-2.0 header. This is the critical guard:
    //    the notorious corruption is byte 7 == `0x0A` (console field = 2,
    //    PlayChoice-10, PLUS the NES-2.0 marker bits 2-3 = `10`), carried by
    //    many home dumps (e.g. the committed `Excitebike.nes`). Because `0x0A`
    //    is NES 2.0 AND is neither `0x01` nor `0x02`, it is ignored and the
    //    cart stays whatever `h.console_type` parsed (it never reaches the RGB
    //    palette: a corrupted console-2 home dump resolves to
    //    `VsPpuType::None` -> `Composite2C02`, byte-for-byte the legacy path).
    //    A survey confirmed no oracle/home ROM carries a clean `0x01`/`0x02`.
    //    Both Vs. AND PC10 use the 2C03 RGB PPU.
    //
    // A true NES-2.0 Vs. dump (console field = 1) keeps the existing behaviour:
    // `h.console_type == VsSystem` already resolved `h.vs_ppu_type` from byte 13
    // in the header parser, so it falls through the final `else`. We do NOT
    // special-case an NES-2.0 PlayChoice-10 console field, precisely because
    // that field is the corrupted-home-dump signal in this library.
    let clean_ines = !h.is_nes2;
    let (console_type, vs_ppu_type) = if h.mapper_id == 99 || h.mapper_id == 151 {
        let vs = if h.vs_ppu_type == VsPpuType::None {
            VsPpuType::Rp2C03
        } else {
            h.vs_ppu_type
        };
        (ConsoleType::VsSystem, vs)
    } else if clean_ines && bytes[7] == 0x01 {
        // Clean iNES Vs. System arcade dump.
        (ConsoleType::VsSystem, VsPpuType::Rp2C03)
    } else if clean_ines && bytes[7] == 0x02 {
        // Clean iNES PlayChoice-10 arcade dump. PC10 used the 2C03 RGB PPU;
        // route it through the 2C03 palette by resolving its (otherwise-`None`)
        // Vs. PPU type to the 2C03.
        (ConsoleType::Playchoice10, VsPpuType::Rp2C03)
    } else {
        (h.console_type, h.vs_ppu_type)
    };

    // A mapper-30 image that declares CHR-ROM is not UNROM-512 and is built as
    // WAIXING-FS005 below. The cartridge identity has to say so too, or every
    // consumer keyed on `(mapper_id, submapper)` -- above all `mapper_tier`,
    // which would answer Curated (accuracy-gated) for id 30 -- describes a board
    // that is not the one running. That would bypass the BestEffort
    // classification 176/2 carries precisely for these ROMs, which is the
    // honesty gate reporting evidence it does not have.
    let (identity_mapper, identity_submapper) = if h.mapper_id == 30 && !chr_rom.is_empty() {
        (176, 2)
    } else {
        (h.mapper_id, h.submapper)
    };

    let cart = Cartridge {
        prg_rom: prg_rom.clone(),
        chr_rom: chr_rom.clone(),
        mapper_id: identity_mapper,
        submapper: identity_submapper,
        mirroring: h.mirroring,
        region: h.region,
        console_type,
        vs_ppu_type,
        // From the header byte-13 high nibble; independent of the mapper-99/151
        // console-type forcing above (a non-dual Vs. cart stays false).
        vs_dual_system: h.is_vs_dual_system(),
        // The whole window, volatile + NVRAM, as the field held before the
        // header split them (v2.9.8).
        prg_ram_size: h.prg_ram_window(),
        chr_ram_size: h.chr_ram_size,
        has_battery: h.has_battery,
        has_trainer: h.has_trainer,
        is_nes2: h.is_nes2,
        nametable_wiring_bits: bytes[6] & 0x09,
    };

    let mapper: Box<dyn Mapper> = match h.mapper_id {
        0 => {
            let nrom = Nrom::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(nrom)
        }
        1 => {
            // MMC1. Default revision is Sharp (no NES 2.0 submapper). Submapper
            // values (1-5) signal SUROM / SOROM / SXROM / SEROM variants —
            // observationally equivalent at the register-protocol level.
            let prg_ram_bytes = if h.prg_ram_window() == 0 {
                0
            } else {
                h.prg_ram_window() as usize
            };
            let mmc1 = Mmc1::new(prg_rom, chr_rom, h.mirroring, prg_ram_bytes)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(mmc1)
        }
        2 => {
            let uxrom = UxRom::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(uxrom)
        }
        3 => {
            let cnrom = CnRom::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(cnrom)
        }
        // v2.9.6: mapper 4 submapper 5 carries the T9552 scrambler
        // (`T9552.md`); it is otherwise an MMC3 board.
        4 if h.is_nes2 && h.submapper == 5 => {
            mmc3_board(Mmc3BoardKind::M4T9552, prg_rom, chr_rom, &h)?
        }
        249 => mmc3_board(Mmc3BoardKind::M249, prg_rom, chr_rom, &h)?,
        4 => {
            // MMC3, and the boards that share its iNES number. NES 2.0
            // submappers (`NES_2_0_submappers.md`; corrected in v2.9.6, which
            // had 1 as "NEC" and 4 as Sharp):
            //   0 — Sharp MMC3 (default; Star Trek 25th Anniversary needs it).
            //   1 — MMC6 (StarTropics): its own 1 KiB PRG-RAM scheme.
            //   2 — MMC3C with hard-wired mirroring.
            //   3 — Acclaim MC-ACC: falling-edge A12 counter, /8 prescaler.
            //   4 — NEC MMC3 ("Loading the latch with 0 disables IRQ").
            //   5 — T9552 scrambler, dispatched to `mmc3_boards.rs` above.
            // An iNES 1.0 StarTropics stays a plain MMC3, as the page advises
            // for headers that cannot say which chip it is.
            let sub = if h.is_nes2 { h.submapper } else { 0 };
            let revision = if sub == 4 {
                Mmc3Revision::Nec
            } else {
                Mmc3Revision::Sharp
            };
            let variant = match sub {
                1 => Mmc3Variant::Mmc6,
                2 => Mmc3Variant::HardwiredMirroring,
                3 => Mmc3Variant::McAcc,
                _ => Mmc3Variant::Standard,
            };
            let prg_ram_bytes = if h.prg_ram_window() == 0 {
                0
            } else {
                h.prg_ram_window() as usize
            };
            let mmc3 = Mmc3::new(prg_rom, chr_rom, h.mirroring, prg_ram_bytes, revision)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?
                .with_variant(variant);
            Box::new(mmc3)
        }
        5 => {
            // MMC5 v0: banking + ExRAM modes 10/11 + scanline IRQ. Several
            // features deferred (vertical split, dual sprite/BG CHR for
            // 8x16 sprites, ExGrafix attribute injection, audio extension);
            // see `crates/rustynes-mappers/src/m005_mmc5.rs` module docs.
            let prg_ram_bytes = if h.prg_ram_window() == 0 {
                0
            } else {
                h.prg_ram_window() as usize
            };
            let mmc5 = Mmc5::new(prg_rom, chr_rom, h.mirroring, prg_ram_bytes)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(mmc5)
        }
        7 => {
            let axrom =
                AxRom::new(prg_rom, chr_rom).map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(axrom)
        }
        9 => {
            let mmc2 = Mmc2::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(mmc2)
        }
        10 => {
            let mmc4 = Mmc4::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(mmc4)
        }
        11 => {
            let cd = ColorDreams::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(cd)
        }
        13 => {
            let cprom = Cprom::new(prg_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(cprom)
        }
        // VRC2 / VRC4 share iNES mapper IDs across submapper variants.
        // We dispatch by (mapper, submapper) pair.  Default mapping below
        // is conservative; refer to nesdev wiki for the full table.
        21 | 23 | 25 => {
            // Mapper 21 -> VRC4 only (a/c).
            // Mapper 22 -> VRC2a (no submapper).
            // Mapper 23 -> VRC2b/VRC4e/VRC4f.
            // Mapper 25 -> VRC2c/VRC4b/VRC4d.
            // We model VRC4 with CPU-cycle IRQ as the superset; submapper
            // selects pin-decoder variant.  Banking matches between VRC2
            // and VRC4; the difference is mostly the IRQ counter which
            // VRC2 lacks (we just leave it idle).
            let m021_vrc4 = Vrc4::new(prg_rom, chr_rom, h.mapper_id, h.submapper, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m021_vrc4)
        }
        22 => {
            let vrc2 = Vrc2::new(prg_rom, chr_rom, 22, h.submapper, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(vrc2)
        }
        24 | 26 => {
            let vrc6 = Vrc6::new(prg_rom, chr_rom, h.mapper_id, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(vrc6)
        }
        34 => {
            let variant = if h.is_nes2 && h.submapper == 1 {
                M34Variant::Nina001
            } else {
                M34Variant::Bnrom
            };
            let m34 = M34::new(prg_rom, chr_rom, h.mirroring, variant)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m34)
        }
        66 => {
            let gxrom = GxRom::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(gxrom)
        }
        69 => {
            let fme7 = Fme7::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(fme7)
        }
        71 => {
            // Some Camerica boards (BF9097) have $9000 mirroring control
            // (subm 1).  Default off.
            let has_single_screen = h.is_nes2 && h.submapper == 1;
            let cam = Camerica::new(prg_rom, h.mirroring, has_single_screen)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(cam)
        }
        75 => {
            let vrc1 = Vrc1::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(vrc1)
        }
        19 => {
            let n163 = Namco163::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(n163)
        }
        16 => {
            // Bandai FCG family. Submapper selects the register window +
            // counter latching + EEPROM (nesdev INES_Mapper_016 §submappers):
            //   0 — unspecified (emulate both windows; LZ93D50 behaviour).
            //   4 — FCG-1/2 ($6000-$7FFF window, direct counter, no EEPROM).
            //   5 — LZ93D50 ($8000-$FFFF window, latched counter, 24C02).
            // Submappers 1/2/3 are deprecated aliases of mappers 159/157/153;
            // a mapper-16 cart carrying them is treated as the closest FCG
            // behaviour (LZ93D50 + 24C02) here.
            let variant = match h.submapper {
                4 => FcgVariant::Fcg,
                5 => FcgVariant::Lz93d50_24c02,
                _ => FcgVariant::Both,
            };
            let fcg = BandaiFcg::new(prg_rom, chr_rom, h.mirroring, variant)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(fcg)
        }
        153 => {
            // v2.9.6: Bandai LZ93D50 with 8 KiB WRAM and an outer PRG bank
            // (`INES_Mapper_153.md`).
            let fcg = BandaiFcg::new(prg_rom, chr_rom, h.mirroring, FcgVariant::Lz93d50Wram)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(fcg)
        }
        159 => {
            // Bandai LZ93D50 with a 128-byte X24C01 serial EEPROM.
            let fcg = BandaiFcg::new(prg_rom, chr_rom, h.mirroring, FcgVariant::Lz93d50_24c01)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(fcg)
        }
        18 => {
            // Jaleco SS88006 (Ganbare Goemon Gaiden, Magical Kids Doropie).
            let ss = JalecoSs88006::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(ss)
        }
        32 => {
            // Irem G-101 (Image Fight, Major League, Kaiketsu Yancha Maru 2,
            // Magical Pop's): two switchable 8 KiB PRG banks with a software
            // swap-mode bit, eight 1 KiB CHR banks, software H/V mirroring.
            // Submapper 1 (Major League) hard-wires single-screen A and ignores
            // the $9000 mirroring bit. Many dumps omit the submapper byte; the
            // $9000 mirroring control still works for the other titles, so we
            // only force one-screen on an explicit submapper-1 flag.
            let force_one_screen = h.is_nes2 && h.submapper == 1;
            let m32 = IremG101::new(prg_rom, chr_rom, h.mirroring, force_one_screen)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m32)
        }
        33 => {
            // Taito TC0190 / TC0350 (Don Doko Don, Power Blazer): two
            // switchable 8 KiB PRG banks, 2x2 KiB + 4x1 KiB CHR banks, and a
            // software mirroring bit. No IRQ (that is the very-similar
            // mapper 48 / TC0690).
            let m33 = TaitoTc0190::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m33)
        }
        48 => {
            // Taito TC0690 (Don Doko Don 2, Flintstones 2, Jetsons, Bakushou!!
            // Jinsei Gekijou 3): TC0190 banking plus an MMC3-style A12 scanline
            // IRQ and an $E000 mirroring register.
            let m48 = TaitoTc0690::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m48)
        }
        70 => {
            // Bandai discrete (UxROM-like): PRG bits 4-7, CHR bits 0-3.
            let m70 = Bandai74::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m70)
        }
        87 => {
            // Jaleco/Konami CNROM-style (Argus, Choplifter, The Goonies, City
            // Connection): fixed PRG + a single bit-swapped 8 KiB CHR-bank
            // register in the $6000-$7FFF window. No IRQ.
            let m87 = Jaleco87::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m87)
        }
        89 => {
            // Sunsoft-2 on the Sunsoft-3 board (Tenka no Goikenban: Mito
            // Koumon): one $8000-$FFFF register switches a 16 KiB PRG bank, an
            // 8 KiB CHR bank (with an A16 high bit), and one-screen mirroring.
            // No IRQ.
            let m89 = Sunsoft2::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m89)
        }
        184 => {
            // Sunsoft-1 (Atlantis no Nazo, The Wing of Madoola, Kid Niki):
            // fixed PRG + two 4 KiB CHR banks selected by a single register in
            // the $6000-$7FFF window. No IRQ.
            let m184 = Sunsoft1::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m184)
        }
        93 => {
            // Sunsoft-3R / Sunsoft-2 IC (Shanghai, Fantasy Zone): UxROM-like
            // 16 KiB PRG bank (bits 4-6) + CHR-RAM enable (bit 0); last PRG
            // bank fixed. CHR is 8 KiB RAM. No IRQ.
            let m93 = Sunsoft3r::new(prg_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m93)
        }
        99 => {
            // Nintendo Vs. System: fixed PRG (8/16/32 KiB) + an 8 KiB CHR bank
            // selected by bit 2 of the $4016 write. Detecting mapper 99 forces
            // ConsoleType::VsSystem + the 2C03 RGB PPU above (mapper-driven, so
            // robust against the byte-7 trap). The bus forwards every $4016
            // write to the mapper for the CHR-select bit.
            let m99 = VsSystem::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m99)
        }
        152 => {
            // Bandai 74161/161 1-screen (Arkanoid II, Pocket Zaurus): UxROM-like
            // 16 KiB PRG bank (bits 4-6) + 8 KiB CHR bank (bits 0-3) + a bit-7
            // software 1-screen mirroring select; last PRG bank fixed. No IRQ.
            let m152 = Bandai152::new(prg_rom, chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m152)
        }
        73 => {
            // Konami VRC3 (Salamander JP): 16-bit CPU-cycle IRQ, no CHR
            // banking (8 KiB CHR-RAM), 16 KiB PRG bank at $F000.
            let vrc3 = Vrc3::new(prg_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(vrc3)
        }
        64 => {
            // Tengen RAMBO-1 (Klax, Skull & Crossbones): MMC3-like banking
            // with a third switchable PRG bank, finer CHR banking, and a
            // dual-mode (scanline A12 / CPU-cycle) IRQ.
            let m64 = Rambo1::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m64)
        }
        65 => {
            // Irem H3001 (Daiku no Gen-san 2, Spartan X 2): 16-bit CPU-cycle
            // down-counter IRQ with a write-high/write-low reload latch.
            let m65 = IremH3001::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m65)
        }
        67 => {
            // Sunsoft-3 (Fantasy Zone 2): 16-bit CPU-cycle IRQ written as a
            // two-write (high-then-low) toggling counter.
            let m67 = Sunsoft3::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m67)
        }
        68 => {
            // Sunsoft-4 (After Burner, Maharaja): PRG/CHR banking + CHR-ROM
            // as nametables (two nametable bank registers + enable bit). No
            // IRQ.
            let m68 = Sunsoft4::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m68)
        }
        78 => {
            // Holy Diver / Uchuusen Cosmo Carrier: UxROM-like 16 KiB PRG +
            // 8 KiB CHR with submapper-selected mirroring. NES 2.0
            // submapper 3 = Holy Diver (H/V switch); submapper 1 = Cosmo
            // Carrier (single-screen A/B). Without a submapper (iNES 1.0, or
            // NES 2.0 submapper 0) the header's "alternative nametables" bit
            // decides, per NESdev `INES_Mapper_078`: iNES images "often set
            // [it] for Holy Diver and cleared it for Cosmo Carrier", and
            // Nestopia / FCEUX default to Cosmo Carrier's 1scA/1scB wiring.
            // Until v2.9.8 the no-submapper case was always Holy Diver, which
            // ignored the bit and contradicted both statements.
            let variant = match (h.is_nes2, h.submapper) {
                (true, 1) => M78Variant::CosmoCarrier,
                (true, 3) => M78Variant::HolyDiver,
                _ if h.mirroring == Mirroring::FourScreen => M78Variant::HolyDiver,
                _ => M78Variant::CosmoCarrier,
            };
            let m78 = M78::new(prg_rom, chr_rom, variant)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m78)
        }
        118 => {
            // TxSROM / TLSROM (Armadillo, NES Play Action Football, Alien
            // Syndrome): MMC3 banking + IRQ plus per-bank nametable mirroring
            // driven by CHR bank bit 7.
            let prg_ram_bytes = if h.prg_ram_window() == 0 {
                0
            } else {
                h.prg_ram_window() as usize
            };
            let m118 = TxSrom::new(prg_rom, chr_rom, h.mirroring, prg_ram_bytes)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m118)
        }
        119 => {
            // TQROM (Pin*Bot, High Speed): MMC3 PRG/IRQ/mirroring plus a mixed
            // CHR address space — 64 KiB CHR-ROM + 8 KiB CHR-RAM, selected per
            // 1 KiB bank by bit 6 of the resolved CHR bank number (set =
            // CHR-RAM). See `crates/rustynes-mappers/src/m119_tqrom.rs`.
            let prg_ram_bytes = if h.prg_ram_window() == 0 {
                0
            } else {
                h.prg_ram_window() as usize
            };
            let m119 = Tqrom::new(prg_rom, chr_rom, h.mirroring, prg_ram_bytes)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m119)
        }
        210 => {
            // Namco 175 / 340: Namco-163-board variants without the
            // expansion audio (and without an IRQ on either). NES 2.0
            // submapper 1 = Namco 175 (hardwired H/V mirroring, optional
            // enable-gated WRAM); submapper 2 = Namco 340 (H/V/1sc mirroring
            // control). Without a submapper, the wiki recommends 175 if the
            // header battery bit is set (WRAM present) and 340 otherwise.
            let board = if h.is_nes2 && h.submapper == 2 {
                Namco175Board::N340
            } else if (h.is_nes2 && h.submapper == 1) || h.has_battery {
                Namco175Board::N175
            } else {
                Namco175Board::N340
            };
            let m210 = Namco175::new(prg_rom, chr_rom, h.mirroring, board)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m210)
        }
        80 => {
            // Taito X1-005 (Kyonshiizu 2, Bakushou!! Jinsei Gekijou): a small
            // $7EF0-$7EFF register window (two 2 KiB + four 1 KiB CHR banks,
            // two switchable 8 KiB PRG banks, software H/V mirroring) plus an
            // on-cart 128-byte battery RAM at $7F00-$7FFF unlocked by writing
            // $A3 to both $7EF8 and $7EF9. No IRQ.
            let m80 = TaitoX1005::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m80)
        }
        82 => {
            // Taito X1-017 (Kyuukyoku Harikiri Koushien / Stadium III): like the
            // X1-005 but with a CHR A12-inversion mode bit (the non-linear
            // 2 KiB/1 KiB CHR-region swap), three protectable 8 KiB PRG-RAM
            // regions, value-shifted CHR (2 KiB banks >> 1) + PRG ($7EFA-$7EFC
            // banks >> 2) registers. The IRQ surface is decoded but unused by
            // the licensed games.
            let m82 = TaitoX1017::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m82)
        }
        151 => {
            // Konami VS (Vs. Gradius / Vs. The Goonies): Konami's VRC1
            // silicon on a Nintendo Vs. System board. Banking is byte-identical
            // to mapper 75 (VRC1); the console type was forced to Vs. System +
            // the 2C03 RGB PPU above (mapper-driven, like mapper 99).
            let m151 = KonamiVs::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m151)
        }
        88 => {
            // Namco 118 with PPU A12 -> CHR A16 (disjoint 64 KiB halves).
            let m88 = Namco118::new(prg_rom, chr_rom, h.mirroring, Namco118Board::M88)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m88)
        }
        154 => {
            // NAMCOT-3453: mapper 88 plus a one-screen nametable select. The
            // board powers up with whatever the header claims; the game sets it
            // on its first $8000-$FFFF write.
            let m154 = Namco118::new(prg_rom, chr_rom, h.mirroring, Namco118Board::M154)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m154)
        }
        206 => {
            // DxROM / Namco 118 base: MMC3 banking subset, no IRQ / A12.
            let m206 = Namco118::new(prg_rom, chr_rom, h.mirroring, Namco118Board::Dxrom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(m206)
        }
        85 => {
            // VRC7 (Mapper 85; Lagrange Point JP).  Banking + IRQ
            // identical to VRC6.  FM audio is deferred per ADR-0004
            // (`docs/adr/0004-vrc7-audio-deferred.md`) — there is no
            // permissively-licensed Rust OPLL crate, and the workspace
            // does not take a C build dependency.  The audio register
            // surface at $9010 / $9030 is still decoded and latched so
            // a future v1.x synthesizer integration can read the byte
            // stream without changing the banking / IRQ / save-state
            // layout.
            let vrc7 = Vrc7::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?;
            Box::new(vrc7)
        }
        // --- v1.2.0 Workstream A, curated (Tier-1) long-tail boards. ---
        // Simple discrete-logic mappers; see `tier.rs` (`MapperTier::Curated`)
        // and `docs/adr/0011-mapper-tiering.md`. Each is register-decode
        // unit-tested in its own per-board module.
        38 => Box::new(
            Bitcorp38::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        41 => Box::new(
            Caltron41::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        79 => Box::new(
            Nina0379::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        86 => Box::new(
            Jaleco86::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Mapper 113: mirroring is register-controlled (no header arg).
        113 => Box::new(
            Nina006M113::new(prg_rom, chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        140 => Box::new(
            Jaleco140::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        232 => Box::new(
            Camerica232::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        240 => Box::new(
            Cne240::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        241 => Box::new(
            Bxrom241::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?
                .with_battery(h.has_battery),
        ),
        // --- v1.2.0 Workstream A, best-effort (Tier-2) long-tail sweep
        // Reference-ported discrete / multicart boards,
        // register-decode unit-tested only, NOT accuracy-gated. See `tier.rs`
        // (`MapperTier::BestEffort`) + `docs/adr/0011-mapper-tiering.md`.
        15 => Box::new(
            Multicart15::new(prg_rom, &chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        36 => Box::new(
            Txc36::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        39 => Box::new(
            Subor39::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        61 => Box::new(
            Multicart61::new(prg_rom, &chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        62 => Box::new(
            Multicart62::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        72 => Box::new(
            Jaleco72::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        77 => Box::new(
            Irem77::new(prg_rom, chr_rom).map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        92 => Box::new(
            Jaleco92::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        96 => Box::new(
            Bandai96::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        97 => Box::new(
            Irem97::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        132 => Box::new(
            Txc132::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        133 => Box::new(
            Sachen133::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        145 => Box::new(
            Sachen145::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        146 => Box::new(
            Sachen146::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        147 => Box::new(
            Sachen3018M147::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        148 => Box::new(
            Sachen148::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        149 => Box::new(
            Sachen149::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        150 => Box::new(
            Sachen150::new(prg_rom, chr_rom).map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Same SA-020A ASIC as mapper 150, on the PCB it was designed for; only
        // the CHR/PRG bank-bit significance differs (NESdev mapper 243 Errata).
        243 => Box::new(
            Sachen150::new_on_board(prg_rom, chr_rom, Sa020aBoard::Sa020a)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        180 => Box::new(
            Nichibutsu180::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        185 => Box::new(
            CnRom185::new(prg_rom, chr_rom, h.mirroring, h.submapper)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        200 => Box::new(
            Multicart200::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        201 => Box::new(
            Multicart201::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        202 => Box::new(
            Multicart202::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        203 => Box::new(
            Multicart203::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        212 => Box::new(
            Multicart212::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        213 => Box::new(
            Multicart213::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        214 => Box::new(
            Multicart214::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.3.0 "Bedrock" Workstream D1, best-effort (Tier-2) sweep
        // Reference-ported discrete / multicart boards,
        // register-decode unit-tested only, NOT accuracy-gated. See `tier.rs`
        // (`MapperTier::BestEffort`) + `docs/adr/0011-mapper-tiering.md`.
        29 => Box::new(
            Cufrom29::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        31 => Box::new(
            Inl31::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        58 => Box::new(
            Multicart58::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        60 => Box::new(
            Multicart60::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        94 => Box::new(
            Un1rom94::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        101 => Box::new(
            Jaleco101::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        107 => Box::new(
            MagicDragon107::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Mapper 111 with CHR-ROM is not GTROM: it is the Chinese *Ninja
        // Ryukenden* translation's board, an MMC1 variant whose registers are
        // written directly with six data bits and address 256 KiB of CHR
        // (`GTROM.md`, "Variations"; forums.nesdev.org t=24276). Neither source
        // gives its address decode or bit mapping, so it is refused with a
        // clear message rather than run as a GTROM that renders garbage.
        111 if !chr_rom.is_empty() => {
            return Err(RomError::InvalidConfig(
                "mapper 111 with CHR-ROM is the Ninja Ryukenden MMC1 variant, which is not \
                 supported (GTROM carries CHR-RAM)"
                    .into(),
            ));
        }
        // Mapper 111: 4-screen CHR-RAM; no header CHR / mirroring arg.
        111 => Box::new(
            Gtrom111::new(prg_rom, &chr_rom).map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        143 => Box::new(
            SachenTca01M143::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Mappers 177 / 179: CHR-RAM; mirroring is register-controlled.
        177 => Box::new(
            Hengedianzi177::new(prg_rom, &chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        179 => Box::new(
            Hengedianzi179::new(prg_rom, &chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        218 => {
            // Magic Floor wires CIRAM A10 to one PPU address line chosen by
            // the RAW flags-6 bits 3 and 0 (NESdev "INES Mapper 218"): with
            // bit 3 set, bit 0 picks A13 (`$A9`, single screen B) over A12
            // (`$A8`, single screen A). The generic parser has already folded
            // bit 0 into `FourScreen`, so re-read it here, as mapper 30 does.
            let mirroring = if h.four_screen {
                if (bytes[6] & 0x01) != 0 {
                    Mirroring::SingleScreenB
                } else {
                    Mirroring::SingleScreenA
                }
            } else {
                h.mirroring
            };
            Box::new(
                MagicFloor218::new(prg_rom, &chr_rom, mirroring)
                    .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
            )
        }
        231 => Box::new(
            Multicart231::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        234 => Box::new(
            Maxi15M234::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.4.0 "Fidelity" Workstream G, best-effort (Tier-2) sweep
        // Reference-ported discrete / multicart boards,
        // register-decode unit-tested only, NOT accuracy-gated. See `tier.rs`
        // (`MapperTier::BestEffort`) + `docs/adr/0011-mapper-tiering.md`.
        28 => Box::new(
            Action53M28::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // A mapper-30 header that also declares CHR-ROM is provably wrong:
        // UNROM 512 is a CHR-RAM-only board, so there is no CHR-ROM for the
        // header to be describing. The known dumps in this shape are Waixing
        // 2005+ re-releases on the FS005 board, which is mapper 176 submapper 2
        // -- an 8025 ASIC whose MMC3 core happens to run a mapper-30-sized image
        // without complaint, which is exactly why the mis-header goes unnoticed.
        // Route them to the board they actually are rather than emulating a
        // board that cannot exist. Genuine mapper-30 images declare 0 CHR-ROM
        // and are untouched.
        30 if !chr_rom.is_empty() => Box::new(
            new_m176(prg_rom, chr_rom, h.mirroring, 2)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        30 => {
            // UNROM-512 decodes its nametable wiring from the RAW iNES byte-6
            // N/M bits (bit 3 = four-screen, bit 0 = vertical), which use an
            // inverted convention from the generic parser; pass them through.
            // `bytes[6]` is always the real iNES header here (the UNIF path
            // recurses on a synthesized iNES image before reaching this point).
            let four_screen = h.four_screen;
            let vertical = (bytes[6] & 0x01) != 0;
            Box::new(
                Unrom512M30::new(
                    prg_rom,
                    &chr_rom,
                    four_screen,
                    vertical,
                    h.submapper,
                    h.has_battery,
                )
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
            )
        }
        63 => Box::new(
            Ntdec63::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        76 => Box::new(
            Namcot3446M76::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        174 => Box::new(
            Ntdec174::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        225 => Box::new(
            Multicart225::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        226 => Box::new(
            Multicart226::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        227 => Box::new(
            Multicart227::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?
                .with_battery(h.has_battery),
        ),
        229 => Box::new(
            Multicart229::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        233 => Box::new(
            Multicart233::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        242 => Box::new(
            Waixing242::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        246 => Box::new(
            FongShenBang246::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.5.0 "Lens" Workstream F, best-effort (Tier-2) sweep
        // Reference-ported discrete / multicart / pirate boards,
        // register-decode + save-state unit-tested only, NOT accuracy-gated.
        // See `tier.rs` (`MapperTier::BestEffort`) + `docs/adr/0011-mapper-tiering.md`.
        40 => Box::new(
            Ntdec2722M40::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        81 => Box::new(
            Ntdec81::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        95 => Box::new(
            Namcot3425M95::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        112 => Box::new(
            NtdecAsder112::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        137 => Box::new(
            Sachen8259M137::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        156 => Box::new(
            Daou156::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?
                .with_battery(h.has_battery),
        ),
        162 => Box::new(
            WaixingFs304M162::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        178 => Box::new(
            Waixing178::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        244 => Box::new(
            Decathlon244::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        250 => Box::new(
            Nitra250::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.6.0 "Studio" Workstream E, best-effort (Tier-2): J.Y. Company
        // ASIC. One silicon implementation behind three iNES mapper numbers;
        // 90 inhibits the ROM-nametable / extended-mirroring feature, 209
        // register-enables it, 211 forces it on. The register-decode is derived
        // from Mesen2's `JyCompany` (GPL-3.0-or-later) and the nesdev "J.Y.
        // Company ASIC" page. See NOTICE + docs/originality-and-provenance.md §1.
        // Register-decode +
        // save-state unit-tested only, NOT accuracy-gated (`tier.rs`).
        90 => Box::new(
            JyAsic::new(prg_rom, chr_rom, h.mirroring, JyBoard::M90)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        209 => Box::new(
            JyAsic::new(prg_rom, chr_rom, h.mirroring, JyBoard::M209)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        211 => Box::new(
            JyAsic::new(prg_rom, chr_rom, h.mirroring, JyBoard::M211)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // J.Y. Company ASIC, single-game "extended" board (same silicon as
        // 90/209/211; the ROM-nametable feature is register-enabled like 209).
        35 => Box::new(
            JyAsic::new(prg_rom, chr_rom, h.mirroring, JyBoard::M35)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.6.0 "Studio" Workstream E, best-effort (Tier-2) sweep
        // MMC3-clone variants (shared MMC3-style core + A12 IRQ),
        // Sachen 8259 A/B/C, and discrete multicarts. Register-decode +
        // save-state unit-tested only, NOT accuracy-gated (`tier.rs`).
        // v2.9.6 "Roster": MMC3 boards written from their NESdev pages
        // (`mmc3_boards.rs`). Mapper 12 submapper 1 (the Magic Card 4M
        // extraction) is a different device and is not supported.
        12 if h.submapper == 0 => mmc3_board(Mmc3BoardKind::M12, prg_rom, chr_rom, &h)?,
        83 => Box::new(
            Cony83::new(prg_rom, chr_rom, h.is_nes2.then_some(h.submapper))
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        91 => Box::new(
            Jy91::new(prg_rom, chr_rom, h.mirroring, h.submapper)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        105 => Box::new(
            NesEvent105::new(prg_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        163 => Box::new(
            Nanjing163::new(prg_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        228 => Box::new(
            Action52M228::new(prg_rom, chr_rom)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        37 => mmc3_board(Mmc3BoardKind::M37, prg_rom, chr_rom, &h)?,
        45 => mmc3_board(Mmc3BoardKind::M45, prg_rom, chr_rom, &h)?,
        47 => mmc3_board(Mmc3BoardKind::M47, prg_rom, chr_rom, &h)?,
        74 => mmc3_board(Mmc3BoardKind::M74, prg_rom, chr_rom, &h)?,
        121 => mmc3_board(Mmc3BoardKind::M121, prg_rom, chr_rom, &h)?,
        191 => mmc3_board(Mmc3BoardKind::M191, prg_rom, chr_rom, &h)?,
        192 => mmc3_board(Mmc3BoardKind::M192, prg_rom, chr_rom, &h)?,
        194 => mmc3_board(Mmc3BoardKind::M194, prg_rom, chr_rom, &h)?,
        195 => mmc3_board(Mmc3BoardKind::M195, prg_rom, chr_rom, &h)?,
        44 => Box::new(
            new_m44(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        49 => Box::new(
            new_m49(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        52 => Box::new(
            new_m52(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        115 => Box::new(
            new_m115(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        134 => Box::new(
            new_m134(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        189 => Box::new(
            new_m189(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        205 => Box::new(
            new_m205(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        238 => Box::new(
            new_m238(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        245 => Box::new(
            new_m245(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        348 => Box::new(
            new_m348(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        366 => Box::new(
            new_m366(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Sachen 8259 A/B/C (the 2 KiB-CHR variants; 8259D is mapper 137).
        141 => Box::new(
            Sachen8259::new(Sachen8259Variant::A, prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        138 => Box::new(
            Sachen8259::new(Sachen8259Variant::B, prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        139 => Box::new(
            Sachen8259::new(Sachen8259Variant::C, prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // Discrete unlicensed / multicart boards. m42 + m50 carry a CPU-cycle
        // IRQ; the rest are hook-free.
        42 => Box::new(
            Mapper42::new(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        50 => Box::new(
            Mapper50::new(prg_rom, &chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        46 => Box::new(
            new_m46(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        51 => Box::new(
            new_m51(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        57 => Box::new(
            new_m57(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        104 => Box::new(
            new_m104(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        120 => Box::new(
            new_m120(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        290 => Box::new(
            new_m290(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        301 => Box::new(
            new_m301(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.7.0 "Forge" Workstream G1, best-effort (Tier-2) reusable-ASIC
        // BMC / pirate cores. FK23C / COOLBOY / MINDKIDS / Sachen /
        // Waixing / Kaiser clusters. Register-decode + save-state unit-tested
        // only, NOT accuracy-gated (`tier.rs`).
        176 => Box::new(
            new_m176(prg_rom, chr_rom, h.mirroring, h.submapper)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        268 => Box::new(
            new_m268(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        513 => Box::new(
            new_m513(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        136 => Box::new(
            new_m136(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        164 => Box::new(
            new_m164(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        253 => Box::new(
            new_m253(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        286 => Box::new(
            new_m286(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        56 => Box::new(
            new_m56(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        142 => Box::new(
            new_m142(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        303 => Box::new(
            new_m303(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        305 => Box::new(
            new_m305(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        306 => Box::new(
            new_m306(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        312 => Box::new(
            new_m312(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        261 => Box::new(
            new_m261(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        289 => Box::new(
            new_m289(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        320 => Box::new(
            new_m320(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        336 => Box::new(
            new_m336(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        349 => Box::new(
            new_m349(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        // --- v1.8.9 "Backlog" beta.6, best-effort (Tier-2) NTDEC / TXC / BMC
        // multicart cores. Register-decode + save-state unit-tested
        // only, NOT accuracy-gated (`tier.rs`).
        193 => Box::new(
            new_m193(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        204 => Box::new(
            new_m204(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        221 => Box::new(
            new_m221(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        299 => Box::new(
            new_m299(prg_rom, chr_rom, h.mirroring)
                .map_err(|e| RomError::InvalidConfig(e.to_string()))?,
        ),
        other => return Err(RomError::UnsupportedMapper(other)),
    };

    // v2.9.6: on a self-flashable board the flash chip IS the non-volatile
    // save, whatever the header's battery bit says (GTROM headers do not set
    // it, and UNROM 512 submappers 1/3/4 are flashable without it). The
    // frontends persist a battery save only when this flag is set, so it is
    // raised here for the boards whose `save_data()` is their flash image.
    let mut cart = cart;
    if matches!(h.mapper_id, 30 | 111) && !mapper.save_data().is_empty() {
        cart.has_battery = true;
    }

    Ok((cart, mapper))
}

#[cfg(test)]
#[allow(clippy::cast_possible_truncation)]
mod tests {
    use super::*;
    use alloc::{vec, vec::Vec};

    fn synth_nrom_rom(prg_kib: usize, chr_kib: usize) -> Vec<u8> {
        let mut bytes = Vec::with_capacity(16 + prg_kib * 1024 + chr_kib * 1024);
        bytes.extend_from_slice(&header::MAGIC);
        bytes.push((prg_kib / 16) as u8); // PRG units
        bytes.push((chr_kib / 8) as u8); // CHR units
        bytes.push(0x00); // flags6: mapper 0, horizontal
        bytes.push(0x00); // flags7
        bytes.extend_from_slice(&[0u8; 8]); // bytes 8-15

        // PRG payload: byte = lower 8 bits of address.
        for i in 0..(prg_kib * 1024) {
            bytes.push((i & 0xFF) as u8);
        }
        // CHR payload: byte = inverted address.
        for i in 0..(chr_kib * 1024) {
            bytes.push(!(i as u8));
        }
        bytes
    }

    #[test]
    fn version_is_non_empty() {
        assert_ne!(version(), "");
    }

    #[test]
    fn parse_synthetic_nrom_16k() {
        let rom = synth_nrom_rom(16, 8);
        let (cart, mut mapper) = parse(&rom).unwrap();
        assert_eq!(cart.mapper_id, 0);
        assert_eq!(cart.prg_rom.len(), 16 * 1024);
        assert_eq!(cart.chr_rom.len(), 8 * 1024);
        assert_eq!(cart.mirroring, Mirroring::Horizontal);
        // Confirm 16K mirroring through the mapper.
        assert_eq!(mapper.cpu_read(0x8000), mapper.cpu_read(0xC000));
    }

    #[test]
    fn parse_synthetic_nrom_32k() {
        let rom = synth_nrom_rom(32, 8);
        let (cart, _mapper) = parse(&rom).unwrap();
        assert_eq!(cart.prg_rom.len(), 32 * 1024);
    }

    /// A mapper-78 image: 32 KiB PRG, 8 KiB CHR. `flags6_low` carries the
    /// mirroring / alternative-nametables bits; `nes2_sub` makes it NES 2.0
    /// with that submapper.
    fn synth_m78(flags6_low: u8, nes2_sub: Option<u8>) -> Vec<u8> {
        let mut rom = synth_nrom_rom(32, 8);
        rom[6] = 0xE0 | (flags6_low & 0x0F); // mapper 78 low nibble = 0xE
        rom[7] = 0x40; // mapper 78 high nibble = 0x4
        if let Some(sub) = nes2_sub {
            rom[7] |= 0x08;
            rom[8] = sub << 4;
        }
        rom
    }

    /// The mirroring a mapper-78 image selects once bit 3 of the bank register
    /// is set: Vertical on the Holy Diver wiring, single-screen B on Cosmo
    /// Carrier's.
    fn m78_mirroring_with_bit3(rom: &[u8]) -> Mirroring {
        let (_cart, mut mapper) = parse(rom).unwrap();
        mapper.cpu_write(0x8000, 0x08);
        mapper.current_mirroring()
    }

    #[test]
    fn mapper_78_ines_header_selects_wiring_by_alt_nametables_bit() {
        // NESdev `INES_Mapper_078`: "iNES1 ROM image headers often set the
        // 'alternative nametables' flag for Holy Diver and cleared it for
        // Cosmo Carrier", and Nestopia / FCEUX default to Cosmo Carrier's
        // 1scA/1scB wiring. So an iNES 1.0 image with the flag clear is
        // Cosmo Carrier, and with it set is Holy Diver.
        assert_eq!(
            m78_mirroring_with_bit3(&synth_m78(0x00, None)),
            Mirroring::SingleScreenB,
            "iNES 1.0, flag clear: Cosmo Carrier wiring"
        );
        assert_eq!(
            m78_mirroring_with_bit3(&synth_m78(0x08, None)),
            Mirroring::Vertical,
            "iNES 1.0, flag set: Holy Diver wiring"
        );
        // NES 2.0 submapper 0 says nothing, so it falls back to the same rule.
        assert_eq!(
            m78_mirroring_with_bit3(&synth_m78(0x00, Some(0))),
            Mirroring::SingleScreenB,
            "NES 2.0 submapper 0, flag clear: Cosmo Carrier wiring"
        );
        // A named submapper wins over the flag, in both directions.
        assert_eq!(
            m78_mirroring_with_bit3(&synth_m78(0x08, Some(1))),
            Mirroring::SingleScreenB,
            "submapper 1: Cosmo Carrier"
        );
        assert_eq!(
            m78_mirroring_with_bit3(&synth_m78(0x00, Some(3))),
            Mirroring::Vertical,
            "submapper 3: Holy Diver"
        );
    }

    #[test]
    fn parse_truncated_returns_typed_error() {
        let mut rom = synth_nrom_rom(32, 8);
        rom.truncate(16 + 100);
        let err = parse(&rom).err().expect("must error");
        assert!(
            matches!(err, RomError::Truncated { .. }),
            "expected Truncated, got {err:?}"
        );
    }

    #[test]
    fn parse_unsupported_mapper_errors() {
        let mut rom = synth_nrom_rom(32, 8);
        // Set mapper 248 — outside the coverage matrix.
        // iNES encoding: mapper_lo = (byte6 >> 4) & 0xF, mapper_hi = byte7 & 0xF0.
        // 248 = 0xF8 -> lo nibble = 8, hi nibble = 0xF. byte6 = 0x80, byte7 = 0xF0.
        rom[6] = 0x80;
        rom[7] = 0xF0;
        let err = parse(&rom).err().expect("must error");
        assert!(
            matches!(err, RomError::UnsupportedMapper(_)),
            "expected UnsupportedMapper, got {err:?}"
        );
    }

    #[test]
    fn parse_fds_image_reports_fds_unsupported() {
        // fwNES container header.
        let mut fwnes = alloc::vec![0u8; 16 + 65500];
        fwnes[0..4].copy_from_slice(b"FDS\x1A");
        fwnes[4] = 1; // one disk side
        assert!(
            matches!(parse(&fwnes).err(), Some(RomError::FdsUnsupported)),
            "fwNES FDS header must report FdsUnsupported"
        );
        // Raw (headerless) disk side opening with the disk-info block.
        let mut raw = alloc::vec![0u8; 65500];
        raw[0] = 0x01;
        raw[1..15].copy_from_slice(b"*NINTENDO-HVC*");
        assert!(
            matches!(parse(&raw).err(), Some(RomError::FdsUnsupported)),
            "raw FDS disk side must report FdsUnsupported"
        );
    }

    #[test]
    fn parse_mapper_5_dispatches_to_mmc5() {
        // Synthesize a 32 KiB PRG / 8 KiB CHR ROM with mapper id 5 (MMC5).
        // iNES: 5 -> low nibble = 5, byte6 = 0x50.
        let mut rom = synth_nrom_rom(32, 8);
        rom[6] = 0x50;
        let (cart, mut mapper) = parse(&rom).expect("MMC5 ROM must parse");
        assert_eq!(cart.mapper_id, 5);
        // Default PRG mode is 3 (4x8K) and $5117 = last bank ROM, so
        // $E000 reads the last 8 KiB. Just exercise the read path.
        let _ = mapper.cpu_read(0xE000);
    }

    #[test]
    fn parse_random_bytes_does_not_panic() {
        // Cheap smoke fuzz; fixed seeds keep test deterministic.
        let seeds: [u64; 8] = [1, 17, 99, 12345, 0xDEAD_BEEF, 0xCAFE, 0x55AA, 0xFF];
        for &s in &seeds {
            let mut state = s;
            let mut bytes = Vec::with_capacity(64);
            for _ in 0..64 {
                state = state
                    .wrapping_mul(6_364_136_223_846_793_005)
                    .wrapping_add(1);
                bytes.push((state >> 32) as u8);
            }
            // Should not panic; result is don't-care.
            let _ = parse(&bytes);
        }
    }

    #[test]
    fn parse_with_trainer_skips_trainer_bytes() {
        let mut rom = Vec::new();
        rom.extend_from_slice(&header::MAGIC);
        rom.push(2); // 32 KiB PRG
        rom.push(1); // 8 KiB CHR
        rom.push(0b0000_0100); // trainer bit set
        rom.push(0);
        rom.extend_from_slice(&[0u8; 8]);
        rom.extend_from_slice(&[0xAB; 512]); // trainer
        rom.extend_from_slice(&vec![0u8; 32 * 1024]); // PRG
        rom.extend_from_slice(&vec![0u8; 8 * 1024]); // CHR
        let (cart, _) = parse(&rom).unwrap();
        assert!(cart.has_trainer);
        assert_eq!(cart.prg_rom.len(), 32 * 1024);
    }
}

/// Tripwire pinning every expansion-audio **level** constant.
///
/// ## Why this exists
///
/// Changing one of these constants changes the audio of every game on that
/// board — correctly, when the change is a deliberate recalibration. The
/// problem is *where the evidence of that lives*. The 60-ROM commercial oracle
/// (`tests/external_real_games.rs`) hashes real cartridge audio and is the only
/// gate that would notice, but it needs `--features commercial-roms` **and**
/// local gitignored ROM dumps, so neither CI nor the default
/// `--features test-roms` gate can run it. A golden vector nothing executes is
/// not a gate.
///
/// That gap bit for real. `VRC6_MIX_SCALE` and all three MMC5 constants were
/// recalibrated in v2.1.6 (`fd82485c`, 2026-07-11); the commercial-oracle
/// snapshots had last been blessed on 2026-06-13, 28 days earlier. Six rows sat
/// silently stale across several releases until someone ran the suite by hand.
///
/// This test **can** run in CI. It fails the moment a level constant moves,
/// with instructions naming the suites that must be re-blessed in the same
/// change. It asserts nothing about correctness — the oracles do that
/// (`audio_expansion.rs`'s `level_db_*` decibel tests, `docs/apu-2a03.md`
/// §Expansion-audio levels). Its only job is to make a silent change loud.
///
/// **If this test fails and the change was intentional:** update the value
/// here, then re-bless BOTH `cargo test -p rustynes-test-harness --features
/// test-roms --test audio_expansion` and `cargo test -p rustynes-test-harness
/// --features test-roms,commercial-roms --test external_real_games` (the latter
/// needs the local dumps; if you do not have them, say so in the PR rather than
/// leaving the rows stale).
#[cfg(test)]
mod expansion_level_tripwire {
    const RE_BLESS: &str = "expansion-audio level constant changed -- re-bless \
        `audio_expansion` AND the gitignored `external_real_games` \
        (--features commercial-roms) in this same change; see this module's docs";

    #[test]
    fn expansion_audio_levels_are_pinned() {
        assert_eq!(crate::m024_vrc6::VRC6_MIX_SCALE, 650, "VRC6: {RE_BLESS}");
        assert_eq!(
            crate::m005_mmc5::MMC5_PULSE_SCALE,
            650,
            "MMC5 pulse: {RE_BLESS}"
        );
        assert_eq!(crate::m005_mmc5::MMC5_PCM_SCALE, 40, "MMC5 PCM: {RE_BLESS}");
        assert_eq!(
            crate::m019_namco163::NAMCO163_MIX_SCALE,
            261,
            "N163: {RE_BLESS}"
        );
        assert_eq!(
            crate::m069_sunsoft_fme7::SUNSOFT5B_MIX_SCALE_NUM,
            2549,
            "5B numerator: {RE_BLESS}"
        );
        assert_eq!(
            crate::m069_sunsoft_fme7::SUNSOFT5B_MIX_SCALE_DEN,
            138,
            "5B denominator: {RE_BLESS}"
        );
    }

    /// `MMC5_MIX_BIAS` is derived from the two MMC5 scales, so it cannot drift
    /// independently — but pin the derivation itself, since an edit to the
    /// formula would move every MMC5 game's DC offset without touching a scale.
    #[test]
    fn mmc5_mix_bias_stays_the_midpoint_of_its_two_scales() {
        assert_eq!(
            crate::m005_mmc5::MMC5_MIX_BIAS,
            i16::midpoint(
                30 * crate::m005_mmc5::MMC5_PULSE_SCALE,
                127 * crate::m005_mmc5::MMC5_PCM_SCALE
            ),
            "MMC5 bias formula: {RE_BLESS}"
        );
    }
}