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.

docs/api_contract.md

@@ -0,0 +1,116 @@
+# API Contract
+
+This document defines the supported external contract for `nesemu` `0.x`.
+
+Use this file as the boundary of what external clients should rely on. For practical embedding examples, see `integration.md`. For internal structure, see `architecture.md`.
+
+## Supported Surface
+
+External users should prefer these entry points:
+
+- Root crate re-exports from `src/lib.rs`
+- `nesemu::runtime::*`
+- `nesemu::prelude::*`
+
+Optional adapter-facing API is available behind features:
+
+- `adapter-api`
+- `adapter-headless`
+
+## Recommended Public Entry Points
+
+The main public API is organized around these groups:
+
+- ROM loading:
+  - `parse_header`
+  - `parse_rom`
+  - `InesHeader`
+  - `InesRom`
+  - `Mirroring`
+- Cartridge mapping:
+  - `create_mapper`
+  - `Mapper`
+- Low-level execution:
+  - `Cpu6502`
+  - `CpuBus`
+  - `CpuError`
+  - `NativeBus`
+- High-level runtime:
+  - `NesRuntime`
+- Host execution and lifecycle:
+  - `RuntimeHostLoop`
+  - `ClientRuntime`
+  - `HostConfig`
+  - `EmulationState`
+- Host IO traits:
+  - `InputProvider`
+  - `VideoOutput`
+  - `AudioOutput`
+- Timing and pacing:
+  - `FrameClock`
+  - `FramePacer`
+  - `PacingClock`
+  - `NoopClock`
+  - `VideoMode`
+- Input helpers:
+  - `JoypadButton`
+  - `JoypadButtons`
+  - `JOYPAD_BUTTON_ORDER`
+  - `JOYPAD_BUTTONS_COUNT`
+  - `set_button_pressed`
+  - `button_pressed`
+
+## Supported Client Flow
+
+The expected integration flow is:
+
+1. Load ROM bytes and parse them, or construct `NesRuntime` directly from ROM bytes.
+2. Choose your integration level:
+   - use `Cpu6502` + `NativeBus` for low-level control
+   - use `NesRuntime` for a higher-level core wrapper
+   - use `RuntimeHostLoop` or `ClientRuntime` for host-facing frame execution
+3. Provide input, video, and audio implementations through the public host traits.
+4. Use save/load state through the runtime or bus APIs when snapshot behavior is needed.
+
+## Stability Rules
+
+The following are considered the primary supported surface for `0.x`:
+
+- root re-exports
+- `runtime`
+- `prelude`
+
+The following are available but less stable:
+
+- `native_core::*` for advanced or experimental integrations
+
+Lower-level modules may evolve faster than the root re-export surface.
+
+## Compatibility Notes
+
+- Types marked `#[non_exhaustive]` may gain fields or variants without a major version bump.
+- Save-state compatibility is only guaranteed within the same crate version unless explicitly documented otherwise.
+- Optional features may expose additional adapter-facing API, but they do not change the baseline contract of the main library.
+
+## Extension Points
+
+The intended extension points for hosts and frontends are:
+
+- `InputProvider`
+- `VideoOutput`
+- `AudioOutput`
+- `FrameClock`
+- optional adapter bridge types when `adapter-api` is enabled:
+  - `InputAdapter`
+  - `VideoAdapter`
+  - `AudioAdapter`
+  - `ClockAdapter`
+
+## Out Of Scope
+
+This contract does not promise stability for:
+
+- GTK frontend behavior in `nesemu-desktop`
+- internal module layout under `native_core` and `runtime`
+- concrete implementation details of mapper modules
+- cross-version save-state compatibility unless explicitly documented