Initial commit: NES emulator with GTK4 desktop frontend

Full NES emulation: CPU, PPU, APU, 47 mappers, iNES/NES 2.0 parsing.
GTK4 desktop client with HeaderBar, pixel-perfect Cairo rendering,
drag-and-drop ROM loading, and keyboard shortcuts.
187 tests covering core emulation, mappers, and runtime.

README.md

@@ -0,0 +1,102 @@
+# nesemu
+
+NES/Famicom emulation workspace in Rust.
+
+The workspace is built around a reusable core library. It also contains optional adapter crates and a GTK4 desktop frontend for manual testing.
+
+## What Is Here
+
+- `nesemu`: core emulation library
+- `nesemu-adapter-api`: backend-agnostic adapter traits
+- `nesemu-adapter-headless`: null/headless adapter implementations
+- `nesemu-desktop`: GTK4 desktop frontend
+
+## What The Core Library Provides
+
+- CPU, PPU, APU, bus, and cartridge mapper emulation
+- iNES ROM parsing
+- Save/load state support
+- Host-facing runtime wrappers for frame execution and pacing
+- Public API and behavior tests
+
+## Quick Start
+
+Add the main crate as a dependency:
+
+```toml
+[dependencies]
+nesemu = { path = "../nesemu" }
+```
+
+Enable optional adapter support if needed:
+
+```toml
+[dependencies]
+nesemu = { path = "../nesemu", features = ["adapter-api", "adapter-headless"] }
+```
+
+Recommended import style:
+
+```rust
+use nesemu::prelude::*;
+```
+
+Minimal setup:
+
+```rust
+use nesemu::{Cpu6502, NativeBus, create_mapper, parse_rom};
+
+let rom_bytes = std::fs::read("game.nes")?;
+let rom = parse_rom(&rom_bytes)?;
+let mapper = create_mapper(rom)?;
+let mut bus = NativeBus::new(mapper);
+let mut cpu = Cpu6502::default();
+cpu.reset(&mut bus);
+```
+
+Higher-level runtime setup:
+
+```rust
+use nesemu::{FRAME_RGBA_BYTES, NesRuntime};
+
+let rom_bytes = std::fs::read("game.nes")?;
+let mut runtime = NesRuntime::from_rom_bytes(&rom_bytes)?;
+runtime.run_until_frame_complete()?;
+
+let mut rgba = vec![0; FRAME_RGBA_BYTES];
+runtime.render_frame_rgba(&mut rgba)?;
+```
+
+## Desktop Frontend
+
+Run the GTK4 desktop frontend:
+
+```bash
+cargo run -p nesemu-desktop -- path/to/game.nes
+```
+
+Linux build requirements: GTK4 development packages and `pkg-config` (for example on Debian/Ubuntu: `libgtk-4-dev pkg-config`).
+
+Controls:
+- `Esc`: quit
+- `P`: pause/resume
+- `Open ROM`: load `.nes` file
+- Arrow keys: D-pad
+- `X`: A
+- `Z`: B
+- `Enter`: Start
+- `Left Shift` / `Right Shift`: Select
+
+## Development
+
+```bash
+cargo fmt --all
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+## Documentation Map
+
+- [API Contract](docs/api_contract.md): supported external surface and stability expectations
+- [Integration Guide](docs/integration.md): how to embed the library into a host or frontend
+- [Architecture](docs/architecture.md): internal module layout and layering