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.

src/lib.rs

@@ -0,0 +1,43 @@
+//! `nesemu` is a core NES/Famicom emulation library.
+//!
+//! It exposes CPU/PPU/APU/bus primitives and ROM/mapper helpers so a host app
+//! can provide platform-specific frontend (windowing, audio device, input).
+//!
+//! # API Stability
+//! - `runtime` and root re-exports are the supported public `v0` API for external clients.
+//! - `native_core` modules are available for advanced integrations, but treated as lower-level
+//!   surface that may evolve faster between minor releases.
+
+pub mod native_core;
+pub mod runtime;
+
+#[cfg(feature = "adapter-api")]
+pub use nesemu_adapter_api as adapter_api;
+#[cfg(feature = "adapter-headless")]
+pub use nesemu_adapter_headless as adapter_headless;
+
+pub use native_core::apu::{Apu, ApuStateTail};
+pub use native_core::bus::NativeBus;
+pub use native_core::cpu::{Cpu6502, CpuBus, CpuError};
+pub use native_core::ines::{InesHeader, InesRom, Mirroring, parse_header, parse_rom};
+pub use native_core::mapper::{Mapper, create_mapper};
+pub use native_core::ppu::Ppu;
+#[cfg(feature = "adapter-api")]
+pub use runtime::{AudioAdapter, ClockAdapter, InputAdapter, VideoAdapter};
+pub use runtime::{
+    AudioMixer, AudioOutput, ClientRuntime, EmulationState, FRAME_HEIGHT, FRAME_RGBA_BYTES,
+    FRAME_WIDTH, FrameClock, FramePacer, HostConfig, InputProvider, JOYPAD_BUTTON_ORDER,
+    JOYPAD_BUTTONS_COUNT, JoypadButton, JoypadButtons, NesRuntime, NoopClock, NullAudio, NullInput,
+    NullVideo, PacingClock, RuntimeError, RuntimeHostLoop, SAVE_STATE_VERSION, VideoMode,
+    VideoOutput, button_pressed, set_button_pressed,
+};
+
+pub mod prelude {
+    #[cfg(feature = "adapter-api")]
+    pub use crate::{AudioAdapter, ClockAdapter, InputAdapter, VideoAdapter};
+    pub use crate::{
+        AudioOutput, ClientRuntime, EmulationState, HostConfig, InputProvider, JoypadButton,
+        JoypadButtons, NesRuntime, RuntimeError, RuntimeHostLoop, VideoOutput, button_pressed,
+        create_mapper, parse_rom, set_button_pressed,
+    };
+}