# 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`
  - `Ppu`
  - `Apu`
  - `ApuStateTail`
  - `ChannelOutputs`
- High-level runtime:
  - `NesRuntime`
  - `RuntimeError`
- Host execution and lifecycle:
  - `RuntimeHostLoop`
  - `ClientRuntime`
  - `HostConfig`
  - `EmulationState`
- Host IO traits:
  - `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`
  - `JOYPAD_BUTTON_ORDER`
  - `JOYPAD_BUTTONS_COUNT`
  - `set_button_pressed`
  - `button_pressed`
- State versioning:
  - `SAVE_STATE_VERSION`

## 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