chore: fix clippy warnings and update docs to match public API

Fix 9 clippy warnings across mmc5 mapper and desktop frontend.
Sync api_contract.md and architecture.md with actual public surface.

crates/nesemu-desktop/src/main.rs

@@ -21,8 +21,6 @@ const TITLE: &str = "NES Emulator";
 const SCALE: i32 = 3;
 const SAMPLE_RATE: u32 = 48_000;
 const AUDIO_RING_CAPACITY: usize = 4096;
-const AUDIO_CALLBACK_FRAMES: u32 = 256;
-
 fn main() {
     if std::env::var_os("GSK_RENDERER").is_none() {
         unsafe {
@@ -161,7 +159,7 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
             .expect("Failed to create Cairo surface");
 
             // Fill background black
-            let _ = cr.set_source_rgb(0.0, 0.0, 0.0);
+            cr.set_source_rgb(0.0, 0.0, 0.0);
             let _ = cr.paint();
 
             let sx = width as f64 / FRAME_WIDTH as f64;
@@ -170,8 +168,8 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
             let offset_x = (width as f64 - FRAME_WIDTH as f64 * scale) / 2.0;
             let offset_y = (height as f64 - FRAME_HEIGHT as f64 * scale) / 2.0;
 
-            let _ = cr.translate(offset_x, offset_y);
-            let _ = cr.scale(scale, scale);
+            cr.translate(offset_x, offset_y);
+            cr.scale(scale, scale);
             let _ = cr.set_source_surface(&surface, 0.0, 0.0);
             cr.source().set_filter(cairo::Filter::Nearest);
             let _ = cr.paint();
@@ -249,8 +247,9 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
             let scheduler = Rc::clone(&scheduler);
             let sync_ui = Rc::clone(&sync_ui);
             chooser.connect_response(move |dialog, response| {
-                if response == gtk::ResponseType::Accept {
-                    if let Some(path) = dialog.file().and_then(|f| f.path()) {
+                if response == gtk::ResponseType::Accept
+                    && let Some(path) = dialog.file().and_then(|f| f.path())
+                {
                     let mut app_state = desktop.borrow_mut();
                     if let Err(err) = app_state.load_rom_from_path(&path) {
                         eprintln!("Failed to load ROM '{}': {err}", path.display());
@@ -260,7 +259,6 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
                         sync_ui(&app_state, Some(&name));
                     }
                 }
-                }
             });
 
             chooser.show();
@@ -370,8 +368,9 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
         let sync_ui = Rc::clone(&sync_ui);
         let drop_target = gtk::DropTarget::new(gio::File::static_type(), gdk::DragAction::COPY);
         drop_target.connect_drop(move |_, value, _, _| {
-            if let Ok(file) = value.get::<gio::File>() {
-                if let Some(path) = file.path() {
+            if let Ok(file) = value.get::<gio::File>()
+                && let Some(path) = file.path()
+            {
                 let mut app_state = desktop.borrow_mut();
                 if let Err(err) = app_state.load_rom_from_path(&path) {
                     eprintln!("Failed to load ROM '{}': {err}", path.display());
@@ -382,7 +381,6 @@ fn build_ui(app: &gtk::Application, initial_rom: Option<PathBuf>) {
                 sync_ui(&app_state, Some(&name));
                 return true;
             }
-            }
             false
         });
         drawing_area.add_controller(drop_target);
@@ -716,7 +714,6 @@ impl DesktopApp {
             Err(err) => {
                 eprintln!("Frame execution error: {err}");
                 self.state = EmulationState::Paused;
-                return;
             }
         }
     }

docs/api_contract.md

@@ -35,8 +35,13 @@ The main public API is organized around these groups:
   - `CpuBus`
   - `CpuError`
   - `NativeBus`
+  - `Ppu`
+  - `Apu`
+  - `ApuStateTail`
+  - `ChannelOutputs`
 - High-level runtime:
   - `NesRuntime`
+  - `RuntimeError`
 - Host execution and lifecycle:
   - `RuntimeHostLoop`
   - `ClientRuntime`
@@ -46,12 +51,23 @@ The main public API is organized around these groups:
   - `InputProvider`
   - `VideoOutput`
   - `AudioOutput`
+- Null/stub implementations:
+  - `NullInput`
+  - `NullVideo`
+  - `NullAudio`
+- Audio helpers:
+  - `AudioMixer`
+  - `RingBuffer`
 - Timing and pacing:
   - `FrameClock`
   - `FramePacer`
   - `PacingClock`
   - `NoopClock`
   - `VideoMode`
+- Video constants:
+  - `FRAME_WIDTH`
+  - `FRAME_HEIGHT`
+  - `FRAME_RGBA_BYTES`
 - Input helpers:
   - `JoypadButton`
   - `JoypadButtons`
@@ -59,6 +75,8 @@ The main public API is organized around these groups:
   - `JOYPAD_BUTTONS_COUNT`
   - `set_button_pressed`
   - `button_pressed`
+- State versioning:
+  - `SAVE_STATE_VERSION`
 
 ## Supported Client Flow
 

docs/architecture.md

@@ -41,6 +41,10 @@ The workspace is split into four layers:
 - `src/runtime/audio.rs`: interim PCM synthesis from core state
 - `src/runtime/timing.rs`: frame pacing types and video timing
 - `src/runtime/types.rs`: public joypad-related types and helpers
+- `src/runtime/constants.rs`: frame dimensions and video constants
+- `src/runtime/error.rs`: `RuntimeError` type definitions
+- `src/runtime/ring_buffer.rs`: lock-free ring buffer for audio sample transport
+- `src/runtime/adapters.rs`: adapter bridge types (behind `adapter-api` feature)
 - `src/runtime/host/io.rs`: host IO traits and null implementations
 - `src/runtime/host/executor.rs`: per-frame execution unit
 - `src/runtime/host/clock.rs`: clock abstraction and pacing implementations

src/native_core/mapper/mappers/mmc5.rs

@@ -530,11 +530,11 @@ impl Mapper for Mmc5 {
                 cursor += 2;
             }
         }
-        if cursor + 1 <= data.len() {
+        if cursor < data.len() {
             self.irq_scanline_counter = data[cursor];
             cursor += 1;
         }
-        if cursor + 1 <= data.len() {
+        if cursor < data.len() {
             self.sprite_8x16 = data[cursor] != 0;
             cursor += 1;
         }