rustynes_ppu/

snapshot.rs

//! Save-state encoding / decoding for the [`Ppu`].
//!
//! Hand-rolled little-endian binary so the crate stays free of `serde` and
//! `bincode`. The container format used by the bus to wrap this blob into
//! a tagged section lives in `rustynes_core::save_state`.
//!
//! Schema version 1 layout (all little-endian, top-down):
//!
//! - `version` u8
//! - region tag u8 (0=NTSC, 1=PAL, 2=Dendy)
//! - `ctrl` u8 / `mask` u8 / `mask_for_skip_check` u8 / `mask_skip_pipe1` u8 / `status` u8
//! - `oam_addr` u8 / `data_buffer` u8
//! - loopy: `v` u16 / `t` u16 / `x` u8 / `w` bool
//! - 2 KiB CIRAM (raw bytes)
//! - 256 B OAM (raw bytes)
//! - 32 B secondary OAM (raw bytes)
//! - 32 B palette RAM (raw bytes)
//! - `open_bus` u8 / 3× `open_bus_decay[i]` u32
//! - `nmi_line` / `suppress_vbl_this_frame` / `last_a12_level` u8
//! - `dot` u16 / `scanline` i16 / `frame` u64 / `frame_complete` bool
//! - `post_reset_mask_remaining` u32
//! - BG latches: `nt_latch` u8 / `at_latch` u8 / `bg_lo_latch` u8 / `bg_hi_latch` u8
//! - BG shifts (v2): `bg_shift_lo` u16 / `bg_shift_hi` u16 / `at_shift_lo` u16 /
//!   `at_shift_hi` u16. (v1 stored `at_shift_*` as u8 + two 1-bit feed bytes;
//!   v1 blobs are upconverted on read.)
//! - `ex_attr_latch` (presence u8 + `palette` u8 + `chr_bank` u16)
//! - `bg_split_latch` (presence u8 + `nt_addr` u16 + `at_addr` u16 + `fine_y` u8 + `chr_bank` u8)
//! - sprite arrays: 8× `shift_lo` / `shift_hi` / `attr` / `x` / `spr_count` u8 / `spr_zero_in_line` bool
//! - `256*240*4` framebuffer bytes

use alloc::vec::Vec;
use thiserror::Error;

use crate::bus::{BgSplitState, ExAttribute};
use crate::ppu::{FRAMEBUFFER_LEN, Ppu, PpuRegion};
use crate::registers::{PpuCtrl, PpuMask, PpuStatus};

/// Schema version for the PPU snapshot blob.
///
/// - v1: 8-bit `at_shift_lo`/`at_shift_hi` + 1-bit `at_feed_lo`/`at_feed_hi`.
/// - v2: 16-bit `at_shift_lo`/`at_shift_hi` (lockstep with the pattern
///   shifters); the feed fields are gone. v1 blobs are still read.
/// - v3 (W3-Stage-4 promotion, 2026-06-10): appends the
///   `mc-ppu-2007-render-buffer` rendering-time `$2007` PPUDATA
///   state-machine tail — `render_data_bus`, `ppudata_sm_countdown`,
///   `ppudata_v_inc_pending`, the raw (pre-h-flip) sprite pattern fetch
///   bytes, and the slot-0 garbage-NT ALE latch. Written unconditionally
///   (zeros when the feature is off) so the layout is identical across
///   feature builds; v1/v2 blobs upconvert with the tail at the inactive
///   defaults (the state the old clear-on-restore assumption imposed).
/// - v4 (v1.7.0 F3, 2026-06-18): appends the `extra_lines_remaining`
///   countdown for the in-flight PPU extra-scanlines overclock insertion.
///   At the default `extra_scanlines == 0` this is always `0`, so the
///   blob merely gains a zero `u16` and restore is behaviourally identical
///   to v3; a non-default countdown taken mid-insertion now round-trips
///   instead of restoring as `0` (which desynced). v1/v2/v3 blobs upconvert
///   with `extra_lines_remaining = 0` (no insertion in flight).
/// - v5 (v2.0.3, ADR 0030): appends the 2-cycle-ALE fetch model's in-flight
///   multiplexed-bus / octal-latch state — `octal_latch`, `address_bus`,
///   `ale_armed`, `pattern_latch_stale`, and the delayed-`CopyV` `copy_v_delay`
///   countdown. These fields carry a background fetch's ALE→read state and the
///   two modeled `$2006`/`$2007` corruption one-shots; a mid-render save/restore
///   (netplay rollback checkpoints, TAS/save-states) that landed with any of
///   them live restored them to the wrong value and desynced the re-simulated
///   framebuffer — exactly the class of bug the v3/v4 tails already fixed for
///   the `$2007` state machine and the overclock countdown. This is an ADDITIVE
///   save-state format change (a `.rns` gains the tail): v1..=4 blobs upconvert
///   with all five at their inactive defaults (`0`/`false`), i.e. the
///   "no fetch in flight" rest state, which is correct for any pre-v5 save taken
///   at rest. Not a *load-break* — a pre-v5 `.rns` still restores.
/// - v6 (v2.1.1, "Fathom"): appends the per-sprite shifter-halt flags
///   (`spr_halted[8]`), the 1-dot-delayed rendering gate
///   (`prev_rendering_enabled` / `rendering_enabled_delayed`), and the
///   OAM-corruption arming state (`oam_corruption_pending`,
///   `oam_corruption_index`, `oam_corruption_disabled`,
///   `oam_corruption_disabled_instant`). These fields were previously not
///   serialized; a frontend run-ahead `snapshot`/`restore` round-trip
///   landing with any of them live (mid-frame sprite-0 split, OAM
///   corruption arming) would restore stale constructor values and corrupt
///   rendering — the Wizards & Warriors half-blank playfield / stalled
///   audio class. v1..=5 blobs upconvert with `spr_halted = [true; 8]`
///   (halted = power-on default) and all others at `false`/`0`. Not a
///   *load-break* — a pre-v6 `.rns` still restores.
/// - v7 (v2.1.4 F2.3): appends the optional OAM-decay model's per-8-byte-row
///   last-touch timestamps (`oam_decay_cycles[32]`), stored as a **relative age**
///   (`now - timestamp` in CPU cycles) rather than the raw absolute value. The
///   absolute timestamps reference the free-running `dot_counter`, which is
///   deliberately NOT part of the save-state (it is cosmetic / re-derived); a raw
///   absolute value would be meaningless after a rollback/restore rebased that
///   counter, and would desync the decay clock. Encoding the age and reconstructing
///   `now - age` against the *live* counter on load makes a run-ahead / netplay
///   `snapshot`→`restore` byte-identical to the forward run (the property the
///   v3/v4/v5/v6 tails secured for the other mid-frame state). The enable flag
///   itself is a frontend/config knob (re-applied on load like `region` /
///   `active_palette`), so — matching the `extra_scanlines` precedent — it is NOT
///   serialized; only the in-flight ages are. At the default (decay off) the ages
///   are inert dead state, so the blob merely grows by 256 bytes and restore is
///   behaviourally identical. v1..=6 blobs upconvert by stamping every row as
///   freshly-touched at the live cycle (age 0), i.e. the rest state — correct for
///   any pre-v7 save. Not a *load-break* — a pre-v7 `.rns` still restores.
/// - v8 (run-ahead sprite-evaluation fix): appends the per-dot **sprite-evaluation
///   FSM** (`sprite_eval_read_latch`, `_n`, `_m`, `_found`, `_sec_idx`,
///   `_copying`, `_done`, `_overflow_search`, `_zero_found`, `_first_iter`), the
///   parallel **OAM-data-bus model** (`oam_bus_copybuffer`, `oam_bus_secondary[32]`,
///   `oam_bus_addr_h`, `oam_bus_addr_l`, `oam_bus_secondary_addr`,
///   `oam_bus_copy_done`, `oam_bus_sprite_in_range`, `oam_bus_overflow_counter`),
///   and the secondary-OAM clear-window write pointer `oam2_addr`. 50 bytes.
///
///   These are the mid-scanline working registers of dots 65..=256: the eval pass
///   walks primary OAM through `_n`/`_m`, stages each byte through
///   `sprite_eval_read_latch`, and commits in-range sprites into `secondary_oam`
///   at `_sec_idx`. `secondary_oam` itself was already serialized — but the
///   *pointers and phase* driving it were not, so a snapshot taken with an eval
///   pass in flight restored a full secondary-OAM buffer alongside a
///   power-on-default FSM. The frontend's run-ahead (`snapshot_core_into` →
///   N frames → `restore_quiet`, every visible frame, and ON BY DEFAULT at
///   `run_ahead = 1`) hit this every frame: the hidden frames advanced the FSM
///   and the rollback left that advance behind. Measured effect on the
///   `AccuracyCoin` battery: 141/141 headless but 138/141 through the desktop
///   frontend, failing exactly `Sprite Evaluation :: Arbitrary Sprite zero`
///   (error 2), `Sprite Evaluation :: Misaligned OAM behavior` (error 1), and
///   `PPU Behavior :: Rendering Flag Behavior` (error 2). Same bug class as the
///   v6 tail (which closed the Wizards & Warriors half-blank playfield), a
///   different uncovered field set.
///
///   Mesen2 serializes the same set — `_spriteIndex`, `_sprite0Added`,
///   `_sprite0Visible`, `_oamCopybuffer`, `_secondaryOamAddr`, `_spriteInRange`,
///   `_oamCopyDone`, `_overflowBugCounter` (`Core/NES/NesPpu.cpp`
///   `NesPpu<T>::Serialize`) — independent confirmation that this is live state,
///   not derived.
///
///   v1..=7 blobs upconvert to the constructor defaults (`0xFF` for the two read
///   latches, `[0xFF; 32]` for the parallel secondary OAM, `0`/`false` elsewhere)
///   — the at-rest state, and exactly what a pre-v8 restore left behind. NOTE
///   that `rustynes_core`'s `.rns` container is version-EXACT per section, so an
///   existing save state fails to load with a clear `VersionMismatch` rather than
///   silently misreading (ADR 0028); the in-function upconvert path serves direct
///   `Ppu::restore` callers.
///
///   Also on restore (ALL versions): the scanline-classification cache
///   (`cached_visible` / `cached_pre_render` / `cached_render_line`, keyed by
///   `flags_cached_scanline`) is INVALIDATED rather than serialized. It is a pure
///   function of `scanline` + `region`, both of which are serialized, so
///   recomputing it is equivalent and cheaper than carrying derived bytes — the
///   same choice Mesen2 makes in its `if(!s.IsSaving())` post-load fixup block.
pub const PPU_SNAPSHOT_VERSION: u8 = 8;

/// v2.3.3 — high bit of the version byte, marking a **slim** snapshot: every
/// field except the 245,760-byte framebuffer.
///
/// Exists for the rewind ring, which snapshots on *every* frame inside the
/// frame budget and then XORs and LZ4-compresses the result. The framebuffer
/// is 94% of those bytes and the worst possible payload for that scheme — it
/// changes every frame, so the XOR never zeroes and the delta never
/// compresses. Measured, rewind roughly doubled the produce-interval p95
/// (31.17 ms against 17.12 ms with it off) and was the cause of a
/// user-visible judder report; see `docs/performance.md` v2.3.3 F3/F4.
///
/// Encoded as a flag on the version byte rather than a new version number so
/// the on-disk format is untouched: every `.rns` ever written has the high bit
/// clear and still parses on exactly the path it always did. Slim snapshots
/// are in-memory only and are never written to a file.
///
/// A slim blob restores every other field and **leaves the framebuffer
/// untouched**, so the caller is responsible for producing an image — see
/// `Nes::rewind_step_back`, which runs one frame to regenerate it.
pub const PPU_SNAPSHOT_SLIM_FLAG: u8 = 0x80;

const CIRAM_LEN: usize = 0x800;
const OAM_LEN: usize = 0x100;
const SEC_OAM_LEN: usize = 32;
const PAL_LEN: usize = 32;

/// Errors returned by [`Ppu::restore`].
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum PpuSnapshotError {
    /// Blob is too short for the version-1 schema.
    #[error("PPU snapshot truncated at offset {0}")]
    Truncated(usize),
    /// The blob's version byte is not understood by this build.
    #[error("PPU snapshot unsupported version {0}")]
    UnsupportedVersion(u8),
    /// Region tag was not one of `0` (NTSC), `1` (PAL), `2` (Dendy).
    #[error("PPU snapshot has invalid region tag {0}")]
    InvalidRegion(u8),
    /// Optional struct presence byte was something other than 0 or 1.
    #[error("PPU snapshot has invalid optional presence byte {0}")]
    InvalidPresence(u8),
}

const fn region_to_u8(r: PpuRegion) -> u8 {
    match r {
        PpuRegion::Ntsc => 0,
        PpuRegion::Pal => 1,
        PpuRegion::Dendy => 2,
    }
}

const fn region_from_u8(v: u8) -> Result<PpuRegion, PpuSnapshotError> {
    match v {
        0 => Ok(PpuRegion::Ntsc),
        1 => Ok(PpuRegion::Pal),
        2 => Ok(PpuRegion::Dendy),
        other => Err(PpuSnapshotError::InvalidRegion(other)),
    }
}

struct W {
    buf: Vec<u8>,
}
impl W {
    fn u8(&mut self, v: u8) {
        self.buf.push(v);
    }
    fn u16(&mut self, v: u16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn u32(&mut self, v: u32) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn u64(&mut self, v: u64) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn i16(&mut self, v: i16) {
        self.buf.extend_from_slice(&v.to_le_bytes());
    }
    fn bytes(&mut self, v: &[u8]) {
        self.buf.extend_from_slice(v);
    }
}

struct R<'a> {
    src: &'a [u8],
    pos: usize,
}
impl R<'_> {
    const fn need(&self, n: usize) -> Result<(), PpuSnapshotError> {
        if self.src.len() - self.pos < n {
            return Err(PpuSnapshotError::Truncated(self.pos));
        }
        Ok(())
    }
    fn u8(&mut self) -> Result<u8, PpuSnapshotError> {
        self.need(1)?;
        let v = self.src[self.pos];
        self.pos += 1;
        Ok(v)
    }
    fn u16(&mut self) -> Result<u16, PpuSnapshotError> {
        self.need(2)?;
        let v = u16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }
    fn u32(&mut self) -> Result<u32, PpuSnapshotError> {
        self.need(4)?;
        let mut a = [0u8; 4];
        a.copy_from_slice(&self.src[self.pos..self.pos + 4]);
        self.pos += 4;
        Ok(u32::from_le_bytes(a))
    }
    fn u64(&mut self) -> Result<u64, PpuSnapshotError> {
        self.need(8)?;
        let mut a = [0u8; 8];
        a.copy_from_slice(&self.src[self.pos..self.pos + 8]);
        self.pos += 8;
        Ok(u64::from_le_bytes(a))
    }
    fn i16(&mut self) -> Result<i16, PpuSnapshotError> {
        self.need(2)?;
        let v = i16::from_le_bytes([self.src[self.pos], self.src[self.pos + 1]]);
        self.pos += 2;
        Ok(v)
    }
    fn bytes_into(&mut self, dst: &mut [u8]) -> Result<(), PpuSnapshotError> {
        self.need(dst.len())?;
        dst.copy_from_slice(&self.src[self.pos..self.pos + dst.len()]);
        self.pos += dst.len();
        Ok(())
    }
}

impl Ppu {
    /// Encode the PPU's mutable state into a versioned binary blob.
    // A flat, linear field-by-field encoder with per-version tail appends (v1
    // through v8); splitting it would only scatter the schema that is clearest read
    // top-to-bottom against the matching `restore` reader.
    #[allow(clippy::too_many_lines)]
    #[must_use]
    pub fn snapshot(&self) -> Vec<u8> {
        self.snapshot_with(false)
    }

    /// v2.3.3 — [`Ppu::snapshot`] without the framebuffer. See
    /// [`PPU_SNAPSHOT_SLIM_FLAG`].
    #[must_use]
    pub fn snapshot_slim(&self) -> Vec<u8> {
        self.snapshot_with(true)
    }

    /// Shared body writer for the full and slim encodings.
    // One long straight-line writer: every field in schema order. Splitting it
    // would make the field-order correspondence with the reader (and with the
    // ADR 0034 schema audit, which parses this body) harder to verify, which is
    // the opposite of what this code needs.
    #[allow(clippy::too_many_lines)]
    fn snapshot_with(&self, slim: bool) -> Vec<u8> {
        // Capacity hint: ~256 KiB framebuffer dominates the full encoding;
        // the slim one is ~4 KiB, so don't reserve for a buffer it omits.
        let mut w = W {
            buf: Vec::with_capacity(if slim { 4096 } else { FRAMEBUFFER_LEN + 4096 }),
        };
        w.u8(if slim {
            PPU_SNAPSHOT_VERSION | PPU_SNAPSHOT_SLIM_FLAG
        } else {
            PPU_SNAPSHOT_VERSION
        });
        w.u8(region_to_u8(self.region));

        w.u8(self.ctrl.bits());
        w.u8(self.mask.bits());
        w.u8(self.mask_for_skip_check.bits());
        w.u8(self.mask_skip_pipe1.bits());
        w.u8(self.status.bits());

        w.u8(self.oam_addr);
        w.u8(self.data_buffer);
        w.u16(self.v);
        w.u16(self.t);
        w.u8(self.x);
        w.u8(u8::from(self.w));

        // Memory blocks at fixed sizes — no length prefix needed (versioned schema).
        w.bytes(&self.ciram);
        w.bytes(&self.oam);
        w.bytes(&self.secondary_oam);
        w.bytes(&self.palette_ram);

        w.u8(self.open_bus);
        for d in self.open_bus_decay {
            w.u32(d);
        }

        w.u8(u8::from(self.nmi_line));
        w.u8(u8::from(self.suppress_vbl_this_frame));
        w.u8(u8::from(self.last_a12_level));

        w.u16(self.dot);
        w.i16(self.scanline);
        w.u64(self.frame);
        w.u8(u8::from(self.frame_complete));

        w.u32(self.post_reset_mask_remaining);

        w.u8(self.nt_latch);
        w.u8(self.at_latch);
        w.u8(self.bg_lo_latch);
        w.u8(self.bg_hi_latch);
        w.u16(self.bg_shift_lo);
        w.u16(self.bg_shift_hi);
        // v2: attribute shift registers widened to 16-bit (lockstep with
        // the pattern shifters); the v1 1-bit `at_feed_*` fields are gone.
        w.u16(self.at_shift_lo);
        w.u16(self.at_shift_hi);

        if let Some(ex) = self.ex_attr_latch {
            w.u8(1);
            w.u8(ex.palette);
            w.u16(ex.chr_bank);
        } else {
            w.u8(0);
            w.u8(0);
            w.u16(0);
        }
        if let Some(s) = self.bg_split_latch {
            w.u8(1);
            w.u16(s.nt_addr);
            w.u16(s.at_addr);
            w.u8(s.fine_y);
            w.u8(s.chr_bank);
        } else {
            w.u8(0);
            w.u16(0);
            w.u16(0);
            w.u8(0);
            w.u8(0);
        }

        w.bytes(&self.spr_shift_lo);
        w.bytes(&self.spr_shift_hi);
        w.bytes(&self.spr_attr);
        w.bytes(&self.spr_x);
        w.u8(self.spr_count);
        w.u8(u8::from(self.spr_zero_in_line));

        if !slim {
            w.bytes(&self.framebuffer);
        }

        // v3 (W3-Stage-4): the `mc-ppu-2007-render-buffer` PPUDATA
        // state-machine tail. Written unconditionally (zeros when the
        // feature is off) so the blob layout is feature-independent.
        {
            w.u8(self.render_data_bus);
            w.u8(self.ppudata_sm_countdown);
            w.u8(u8::from(self.ppudata_v_inc_pending));
            w.bytes(&self.spr_fetch_lo_raw);
            w.bytes(&self.spr_fetch_hi_raw);
            w.u16(self.ppudata_spr0_nt_addr);
        }
        // v3 (W3-Stage-4): the `mc-ppu-subpos` BG-reload freeze (the
        // `$2001`-write-commit delay that injects the BG serial-in '1's).
        // `bg_reload_render` re-syncs from the live mask when settled, but an
        // in-flight `mask_write_delay` countdown can straddle an instruction
        // boundary — serialize both so a restored state resumes the freeze
        // exactly.
        {
            w.u8(u8::from(self.bg_reload_render));
            w.u8(self.mask_write_delay);
        }

        // v4 (v1.7.0 F3): the in-flight extra-scanlines overclock countdown.
        // Always `0` at the default `extra_scanlines == 0`, so this is a
        // zero `u16` in the stock build (no behavioural change). The
        // configured count itself (`extra_scanlines`) stays a frontend knob
        // re-applied on restore, like `region` / `active_palette`.
        w.u16(self.extra_lines_remaining);

        // v5 (v2.0.3, ADR 0030): the 2-cycle-ALE fetch model's in-flight
        // multiplexed-bus / octal-latch state. All at rest (`0`/`false`) at a
        // clean fetch boundary, but a mid-render checkpoint (netplay rollback)
        // can land with `copy_v_delay`/`pattern_latch_stale`/`ale_armed` live —
        // serialize them (plus the latch + bus they splice through) so the
        // re-simulated frame is byte-identical to the forward run.
        {
            w.u8(self.octal_latch);
            w.u16(self.address_bus);
            w.u8(u8::from(self.ale_armed));
            w.u8(u8::from(self.pattern_latch_stale));
            w.u8(self.copy_v_delay);
        }

        // v6 (W&W run-ahead fix): the per-sprite shifter HALT state. Set by the
        // v2.0 sprite-shifter-counter model (a loaded-but-halted slot draws
        // immediately on re-enable), it persists across the frame boundary and
        // governs whether each of the 8 loaded sprites emits — so it is genuine
        // rendering state. It was previously unserialized, so a per-frame
        // save/restore (run-ahead, netplay rollback) drifted it: for a game that
        // toggles rendering mid-frame (Wizards & Warriors' sprite-0 status-bar
        // split), the drift accumulated into dropped/blinking sprites and a
        // half-rendered playfield. `true` (halted) is the power-on default.
        for h in &self.spr_halted {
            w.u8(u8::from(*h));
        }
        // v6 (cont.) — remaining unserialized cross-frame render state.
        w.u8(u8::from(self.prev_rendering_enabled));
        w.u8(u8::from(self.rendering_enabled_delayed));
        w.u8(u8::from(self.oam_corruption_pending));
        w.u8(self.oam_corruption_index);
        w.u8(u8::from(self.oam_corruption_disabled));
        w.u8(u8::from(self.oam_corruption_disabled_instant));

        // v7 (v2.1.4 F2.3): the optional OAM-decay model's per-row last-touch
        // timestamps, stored as a RELATIVE AGE (`now - timestamp`) so the decay
        // clock survives a rollback/restore that rebases the un-serialized
        // free-running `dot_counter`. `now` is the live CPU cycle (`dot_counter / 3`,
        // NTSC/Dendy divisor). `wrapping_sub` keeps the encode total even across the
        // (astronomically unlikely) u64 wrap. When decay is off these ages are inert
        // (never read on restore's decay path), but they still round-trip exactly.
        let now = self.dot_counter / 3;
        for ts in self.oam_decay_cycles {
            w.u64(now.wrapping_sub(ts));
        }

        // v8: the per-dot sprite-evaluation FSM + the parallel OAM-data-bus
        // model + the clear-window secondary-OAM write pointer. `secondary_oam`
        // (the buffer) was always serialized; these are the POINTERS AND PHASE
        // that fill it, and without them a mid-eval snapshot restored a full
        // buffer next to a reset walker. See the `PPU_SNAPSHOT_VERSION` rustdoc
        // for the run-ahead failure this closes and the Mesen2 cross-check.
        {
            w.u8(self.sprite_eval_read_latch);
            w.u8(self.sprite_eval_n);
            w.u8(self.sprite_eval_m);
            w.u8(self.sprite_eval_found);
            w.u8(self.sprite_eval_sec_idx);
            w.u8(u8::from(self.sprite_eval_copying));
            w.u8(u8::from(self.sprite_eval_done));
            w.u8(u8::from(self.sprite_eval_overflow_search));
            w.u8(u8::from(self.sprite_eval_zero_found));
            w.u8(u8::from(self.sprite_eval_first_iter));

            w.u8(self.oam_bus_copybuffer);
            w.bytes(&self.oam_bus_secondary);
            w.u8(self.oam_bus_addr_h);
            w.u8(self.oam_bus_addr_l);
            w.u8(self.oam_bus_secondary_addr);
            w.u8(u8::from(self.oam_bus_copy_done));
            w.u8(u8::from(self.oam_bus_sprite_in_range));
            w.u8(self.oam_bus_overflow_counter);

            w.u8(self.oam2_addr);
        }

        w.buf
    }

    /// Decode a previously [`Ppu::snapshot`]ed blob.
    ///
    /// # Errors
    ///
    /// Returns [`PpuSnapshotError`] on a malformed blob.
    // A flat, linear field-by-field decoder with per-version tail branches (v1
    // through v8); splitting it would only scatter the schema that is clearest
    // read top-to-bottom against the matching `snapshot` writer.
    #[allow(clippy::too_many_lines)]
    pub fn restore(&mut self, data: &[u8]) -> Result<(), PpuSnapshotError> {
        // A valid v1..=8 snapshot always contains these fixed-size blocks (the
        // framebuffer, read unconditionally below at every version, dominates);
        // the version-specific tails only add to this. This is a *conservative
        // lower bound* — it deliberately omits the ~40 scalar register/latch
        // bytes and the spr shift arrays, so it can never reject a valid blob,
        // yet it rejects a clearly-truncated one BEFORE the version byte is read
        // (so short/garbled input reports `Truncated`, not a misleading
        // `UnsupportedVersion` on whatever byte sits at offset 0). `Truncated(0)`
        // matches the offset semantics `R::need` uses elsewhere (the position at
        // which a read ran out) — here, nothing valid was read.
        // v2.3.3 — a slim blob (high bit of the version byte) carries no
        // framebuffer, so the bound must drop that term for it. Read the flag
        // from byte 0 directly rather than through `R`, because this check
        // deliberately runs BEFORE the reader is constructed.
        const MIN_SLIM_SIZE: usize = 1 + CIRAM_LEN + OAM_LEN + SEC_OAM_LEN + PAL_LEN;
        const MIN_SNAPSHOT_SIZE: usize = MIN_SLIM_SIZE + FRAMEBUFFER_LEN;
        let is_slim = data
            .first()
            .is_some_and(|v| v & PPU_SNAPSHOT_SLIM_FLAG != 0);
        let min_size = if is_slim {
            MIN_SLIM_SIZE
        } else {
            MIN_SNAPSHOT_SIZE
        };
        if data.len() < min_size {
            return Err(PpuSnapshotError::Truncated(0));
        }
        let mut r = R { src: data, pos: 0 };
        let raw_version = r.u8()?;
        // v2.3.3 — the high bit marks a slim (framebuffer-less) blob; strip it
        // before the range check so the version rules are unchanged.
        let slim = raw_version & PPU_SNAPSHOT_SLIM_FLAG != 0;
        let version = raw_version & !PPU_SNAPSHOT_SLIM_FLAG;
        // Bound tied to the constant, not a literal: the acceptance range and
        // the emitted version must move together on every schema bump.
        if !matches!(version, 1..=PPU_SNAPSHOT_VERSION) {
            return Err(PpuSnapshotError::UnsupportedVersion(raw_version));
        }
        self.region = region_from_u8(r.u8()?)?;

        self.ctrl = PpuCtrl::from_bits_truncate(r.u8()?);
        self.mask = PpuMask::from_bits_truncate(r.u8()?);
        self.mask_for_skip_check = PpuMask::from_bits_truncate(r.u8()?);
        self.mask_skip_pipe1 = PpuMask::from_bits_truncate(r.u8()?);
        self.status = PpuStatus::from_bits_truncate(r.u8()?);

        self.oam_addr = r.u8()?;
        self.data_buffer = r.u8()?;
        self.v = r.u16()?;
        self.t = r.u16()?;
        self.x = r.u8()?;
        self.w = r.u8()? != 0;

        r.bytes_into(&mut self.ciram)?;
        r.bytes_into(&mut self.oam)?;
        r.bytes_into(&mut self.secondary_oam)?;
        r.bytes_into(&mut self.palette_ram)?;

        self.open_bus = r.u8()?;
        for d in &mut self.open_bus_decay {
            *d = r.u32()?;
        }

        self.nmi_line = r.u8()? != 0;
        self.suppress_vbl_this_frame = r.u8()? != 0;
        self.last_a12_level = r.u8()? != 0;

        self.dot = r.u16()?;
        self.scanline = r.i16()?;
        self.frame = r.u64()?;
        self.frame_complete = r.u8()? != 0;

        self.post_reset_mask_remaining = r.u32()?;

        self.nt_latch = r.u8()?;
        self.at_latch = r.u8()?;
        self.bg_lo_latch = r.u8()?;
        self.bg_hi_latch = r.u8()?;
        self.bg_shift_lo = r.u16()?;
        self.bg_shift_hi = r.u16()?;
        if version >= 2 {
            self.at_shift_lo = r.u16()?;
            self.at_shift_hi = r.u16()?;
        } else {
            // v1: 8-bit attribute shift registers + a 1-bit feed each.
            // Promote into the v2 16-bit registers (low byte = the v1
            // 8-bit value; the high byte was always implicitly zero in
            // the v1 model). The transient feed bits are dropped — they
            // are regenerated from `at_latch` within one scanline of
            // resumed rendering, so this is lossless in practice.
            self.at_shift_lo = u16::from(r.u8()?);
            self.at_shift_hi = u16::from(r.u8()?);
            let _at_feed_lo = r.u8()?;
            let _at_feed_hi = r.u8()?;
        }

        let ex_present = r.u8()?;
        let palette = r.u8()?;
        let chr_bank = r.u16()?;
        self.ex_attr_latch = match ex_present {
            0 => None,
            1 => Some(ExAttribute { palette, chr_bank }),
            other => return Err(PpuSnapshotError::InvalidPresence(other)),
        };
        let split_present = r.u8()?;
        let nt_addr = r.u16()?;
        let at_addr = r.u16()?;
        let fine_y = r.u8()?;
        let chr_bank8 = r.u8()?;
        self.bg_split_latch = match split_present {
            0 => None,
            1 => Some(BgSplitState {
                nt_addr,
                at_addr,
                fine_y,
                chr_bank: chr_bank8,
            }),
            other => return Err(PpuSnapshotError::InvalidPresence(other)),
        };

        r.bytes_into(&mut self.spr_shift_lo)?;
        r.bytes_into(&mut self.spr_shift_hi)?;
        r.bytes_into(&mut self.spr_attr)?;
        r.bytes_into(&mut self.spr_x)?;
        self.spr_count = r.u8()?;
        self.spr_zero_in_line = r.u8()? != 0;

        // Slim blobs carry no framebuffer; the existing one is left in place
        // and the caller regenerates the image.
        if !slim {
            r.bytes_into(&mut self.framebuffer)?;
        }

        // v3 (W3-Stage-4): the gated master-clock PPU tail. v1/v2 blobs
        // lack it; upconvert at the inactive defaults (countdown 0 = no
        // reload in flight), which is exactly what the pre-v3
        // clear-on-restore assumption imposed.
        if version >= 3 {
            self.restore_stage4_tail(&mut r)?;
        }

        // v4 (v1.7.0 F3): the in-flight extra-scanlines overclock countdown.
        // v1/v2/v3 blobs lack it; upconvert to `0` (no insertion in flight),
        // which is exactly the state a pre-v4 restore left it in.
        self.extra_lines_remaining = if version >= 4 { r.u16()? } else { 0 };

        // v5 (v2.0.3, ADR 0030): the 2-cycle-ALE in-flight fetch state. v1..=4
        // blobs lack it; upconvert to the inactive rest defaults (`0`/`false`) —
        // the state a fetch boundary leaves it in, and exactly what a pre-v5
        // restore imposed. A v5 blob taken mid-render round-trips the live values
        // so the re-simulated frame stays byte-identical (netplay rollback).
        if version >= 5 {
            self.octal_latch = r.u8()?;
            self.address_bus = r.u16()?;
            self.ale_armed = r.u8()? != 0;
            self.pattern_latch_stale = r.u8()? != 0;
            self.copy_v_delay = r.u8()?;
        } else {
            self.octal_latch = 0;
            self.address_bus = 0;
            self.ale_armed = false;
            self.pattern_latch_stale = false;
            self.copy_v_delay = 0;
        }

        // v6: per-sprite shifter halt state (see the write side). Pre-v6 blobs
        // lack it; upconvert to the power-on default (`true` = halted), which is
        // what a pre-v6 restore left it at (the field kept its constructor value).
        if version >= 6 {
            for h in &mut self.spr_halted {
                *h = r.u8()? != 0;
            }
            self.prev_rendering_enabled = r.u8()? != 0;
            self.rendering_enabled_delayed = r.u8()? != 0;
            self.oam_corruption_pending = r.u8()? != 0;
            self.oam_corruption_index = r.u8()?;
            self.oam_corruption_disabled = r.u8()? != 0;
            self.oam_corruption_disabled_instant = r.u8()? != 0;
        } else {
            self.spr_halted = [true; 8];
            self.prev_rendering_enabled = false;
            self.rendering_enabled_delayed = false;
            self.oam_corruption_pending = false;
            self.oam_corruption_index = 0;
            self.oam_corruption_disabled = false;
            self.oam_corruption_disabled_instant = false;
        }

        // v7 (v2.1.4 F2.3): the optional OAM-decay row timestamps, stored as a
        // relative age. Reconstruct the absolute timestamp against the LIVE counter
        // (`now = dot_counter / 3`, unchanged by restore) as `now - age`, so the
        // decay clock is preserved regardless of how the counter was rebased between
        // snapshot and restore (the rollback-determinism property). Pre-v7 blobs
        // lack it: stamp every row as freshly-touched at the live cycle (age 0),
        // i.e. the rest state a pre-v7 restore effectively left (the constructor's
        // all-zero array with decay off is never consulted anyway).
        let now = self.dot_counter / 3;
        if version >= 7 {
            for ts in &mut self.oam_decay_cycles {
                let age = r.u64()?;
                *ts = now.wrapping_sub(age);
            }
        } else {
            self.oam_decay_cycles = [now; 32];
        }

        // v8: the per-dot sprite-evaluation FSM + parallel OAM-data-bus model +
        // the clear-window secondary-OAM pointer. Pre-v8 blobs lack it; upconvert
        // to the constructor defaults, which is precisely the state a pre-v8
        // restore left these fields in (they simply kept whatever the instance
        // already held — for a fresh `Ppu`, these values).
        if version >= 8 {
            self.sprite_eval_read_latch = r.u8()?;
            self.sprite_eval_n = r.u8()?;
            self.sprite_eval_m = r.u8()?;
            self.sprite_eval_found = r.u8()?;
            self.sprite_eval_sec_idx = r.u8()?;
            self.sprite_eval_copying = r.u8()? != 0;
            self.sprite_eval_done = r.u8()? != 0;
            self.sprite_eval_overflow_search = r.u8()? != 0;
            self.sprite_eval_zero_found = r.u8()? != 0;
            self.sprite_eval_first_iter = r.u8()? != 0;

            self.oam_bus_copybuffer = r.u8()?;
            r.bytes_into(&mut self.oam_bus_secondary)?;
            self.oam_bus_addr_h = r.u8()?;
            self.oam_bus_addr_l = r.u8()?;
            self.oam_bus_secondary_addr = r.u8()?;
            self.oam_bus_copy_done = r.u8()? != 0;
            self.oam_bus_sprite_in_range = r.u8()? != 0;
            self.oam_bus_overflow_counter = r.u8()?;

            self.oam2_addr = r.u8()?;
        } else {
            self.sprite_eval_read_latch = 0xFF;
            self.sprite_eval_n = 0;
            self.sprite_eval_m = 0;
            self.sprite_eval_found = 0;
            self.sprite_eval_sec_idx = 0;
            self.sprite_eval_copying = false;
            self.sprite_eval_done = false;
            self.sprite_eval_overflow_search = false;
            self.sprite_eval_zero_found = false;
            self.sprite_eval_first_iter = false;

            self.oam_bus_copybuffer = 0xFF;
            self.oam_bus_secondary = [0xFF; 32];
            self.oam_bus_addr_h = 0;
            self.oam_bus_addr_l = 0;
            self.oam_bus_secondary_addr = 0;
            self.oam_bus_copy_done = false;
            self.oam_bus_sprite_in_range = false;
            self.oam_bus_overflow_counter = 0;

            self.oam2_addr = 0;
        }

        // Derived-cache fixup (every version): the scanline-classification cache
        // is a pure function of `scanline` + `region`, so it is recomputed rather
        // than carried. Resetting the key to the `Ppu::new` sentinel forces the
        // next `tick` to refill it from the restored scanline; leaving a warm key
        // behind would let a cache filled under a different timeline satisfy the
        // `scanline == flags_cached_scanline` guard on the fast dot path.
        self.cached_visible = false;
        self.cached_pre_render = false;
        self.cached_render_line = false;
        #[cfg(feature = "ppu-idle-line-fast")]
        {
            self.cached_idle_line = false;
        }
        self.flags_cached_scanline = i16::MIN;

        // sanity: the schema-fixed sizes mean we should be at end of input now.
        if r.pos != data.len() {
            return Err(PpuSnapshotError::Truncated(r.pos));
        }
        Ok(())
    }
}

impl Ppu {
    /// v3 (W3-Stage-4) tail decode: the `mc-ppu-2007-render-buffer` PPUDATA
    /// state machine + the `mc-ppu-subpos` BG-reload freeze. Bytes are
    /// always present in a v3 blob; fields whose cargo feature is off are
    /// consumed and discarded.
    fn restore_stage4_tail(&mut self, r: &mut R<'_>) -> Result<(), PpuSnapshotError> {
        let render_data_bus = r.u8()?;
        let ppudata_sm_countdown = r.u8()?;
        let ppudata_v_inc_pending = r.u8()? != 0;
        let mut spr_fetch_lo_raw = [0u8; 8];
        let mut spr_fetch_hi_raw = [0u8; 8];
        r.bytes_into(&mut spr_fetch_lo_raw)?;
        r.bytes_into(&mut spr_fetch_hi_raw)?;
        let ppudata_spr0_nt_addr = r.u16()?;
        {
            self.render_data_bus = render_data_bus;
            self.ppudata_sm_countdown = ppudata_sm_countdown;
            self.ppudata_v_inc_pending = ppudata_v_inc_pending;
            self.spr_fetch_lo_raw = spr_fetch_lo_raw;
            self.spr_fetch_hi_raw = spr_fetch_hi_raw;
            self.ppudata_spr0_nt_addr = ppudata_spr0_nt_addr;
        }
        let bg_reload_render = r.u8()? != 0;
        let mask_write_delay = r.u8()?;
        {
            self.bg_reload_render = bg_reload_render;
            self.mask_write_delay = mask_write_delay;
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn snapshot_round_trip() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.ciram[10] = 0xAB;
        p.oam[20] = 0xCD;
        p.palette_ram[5] = 0x21;
        p.framebuffer[100] = 0xEF;
        p.dot = 123;
        p.scanline = -1;
        p.frame = 42;
        p.ex_attr_latch = Some(ExAttribute {
            palette: 2,
            chr_bank: 0x123,
        });
        p.bg_split_latch = Some(BgSplitState {
            nt_addr: 0x2400,
            at_addr: 0x23C0,
            fine_y: 5,
            chr_bank: 7,
        });

        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Pal);
        q.restore(&blob).unwrap();
        assert_eq!(q.region, PpuRegion::Ntsc);
        assert_eq!(q.ciram[10], 0xAB);
        assert_eq!(q.oam[20], 0xCD);
        assert_eq!(q.palette_ram[5], 0x21);
        assert_eq!(q.framebuffer[100], 0xEF);
        assert_eq!(q.dot, 123);
        assert_eq!(q.scanline, -1);
        assert_eq!(q.frame, 42);
        assert_eq!(
            q.ex_attr_latch,
            Some(ExAttribute {
                palette: 2,
                chr_bank: 0x123
            })
        );
        assert_eq!(
            q.bg_split_latch,
            Some(BgSplitState {
                nt_addr: 0x2400,
                at_addr: 0x23C0,
                fine_y: 5,
                chr_bank: 7,
            })
        );
    }

    #[test]
    fn snapshot_round_trips_16bit_attribute_shifters() {
        // v2 widened `at_shift_lo`/`at_shift_hi` from u8 to u16 (lockstep
        // with the BG pattern shifters; the 086ce4d left-edge palette
        // fix). Verify the full 16-bit value survives a round trip — a
        // regression that truncated to 8 bits would re-introduce the
        // attribute/pattern drift after a save-state load.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.at_shift_lo = 0xAB12;
        p.at_shift_hi = 0xCD34;
        p.bg_shift_lo = 0x5678;
        p.bg_shift_hi = 0x9ABC;
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.at_shift_lo, 0xAB12);
        assert_eq!(q.at_shift_hi, 0xCD34);
        assert_eq!(q.bg_shift_lo, 0x5678);
        assert_eq!(q.bg_shift_hi, 0x9ABC);
    }

    #[test]
    fn snapshot_reads_v1_attribute_shifters_as_low_byte() {
        // A v1 blob stored `at_shift_lo`/`at_shift_hi` as u8 plus two
        // 1-bit `at_feed_*` bytes. The v2 reader must accept v1 blobs and
        // promote the 8-bit attribute value into the low byte of the new
        // 16-bit register (the high byte was always implicitly zero in
        // the v1 model). Synthesize a v1 blob by snapshotting v2, then
        // rewriting the version byte + the 4-byte attribute region in the
        // v1 (u8 + u8 + u8 + u8) layout.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.at_shift_lo = 0x00CD; // v1 could only hold the low byte
        p.at_shift_hi = 0x00EF;
        let v2 = p.snapshot();

        // Locate the attribute field: it follows bg_shift_lo (u16) +
        // bg_shift_hi (u16). We rebuild the blob as v1 by re-serialising
        // up to that point and splicing a v1-shaped attribute block. The
        // simplest robust construction: decode the v2 layout offset by
        // searching for the known 16-bit AT-low bytes we set.
        // at_shift_lo = 0x00CD -> LE bytes [0xCD, 0x00]; at_shift_hi =
        // 0x00EF -> [0xEF, 0x00]. In v1 these become [0xCD][0xEF] plus two
        // feed bytes. Build the v1 blob field-by-field by copying the
        // prefix, then the v1 attribute block, then the v2 tail (which is
        // identical from `ex_attr_latch` onward).
        // Find the 4-byte AT region: bytes [.., 0xCD,0x00, 0xEF,0x00, ..].
        let mut idx = None;
        for w in 0..v2.len().saturating_sub(4) {
            if v2[w] == 0xCD && v2[w + 1] == 0x00 && v2[w + 2] == 0xEF && v2[w + 3] == 0x00 {
                idx = Some(w);
                break;
            }
        }
        let at = idx.expect("locate v2 16-bit AT region");
        let mut v1 = Vec::new();
        v1.extend_from_slice(&v2[..at]); // prefix (incl. bg shifters)
        v1.push(0xCD); // v1 at_shift_lo (u8)
        v1.push(0xEF); // v1 at_shift_hi (u8)
        v1.push(0x01); // v1 at_feed_lo (u8)
        v1.push(0x00); // v1 at_feed_hi (u8)
        // Tail from ex_attr_latch onward, MINUS the v3 W3-Stage-4 tail
        // (23 bytes: u8*3 + [u8;8]*2 + u16 PPUDATA state machine, then
        // u8*2 BG-reload freeze), the v4 extra-scanlines countdown (2 bytes:
        // u16 `extra_lines_remaining`), the v5 2-cycle-ALE fetch-state tail
        // (6 bytes: u8 `octal_latch` + u16 `address_bus` + u8 `ale_armed` + u8
        // `pattern_latch_stale` + u8 `copy_v_delay`), the v6 render-state
        // tail (14 bytes: [u8;8] `spr_halted` + u8 `prev_rendering_enabled` + u8
        // `rendering_enabled_delayed` + u8*4 `oam_corruption_*`), the v7
        // OAM-decay tail (256 bytes: [u64;32] relative-age `oam_decay_cycles`),
        // AND the v8 sprite-evaluation tail (50 bytes: u8*5 + bool*5 eval FSM,
        // then u8 + [u8;32] + u8*3 + bool*2 + u8 OAM-data-bus model, then u8
        // `oam2_addr`) — 351 bytes total, none of which a v1 blob carried.
        v1.extend_from_slice(&v2[at + 4..v2.len() - 351]);
        v1[0] = 1; // version byte -> v1

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&v1).expect("v1 blob must upconvert");
        assert_eq!(q.at_shift_lo, 0x00CD, "v1 low byte promoted to 16-bit");
        assert_eq!(q.at_shift_hi, 0x00EF);
    }

    #[test]
    fn snapshot_rejects_short_blob() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        assert!(matches!(
            p.restore(&[]).unwrap_err(),
            PpuSnapshotError::Truncated(_)
        ));
        // The regression this size guard prevents: a SHORT blob whose first byte
        // is an unknown version must be classified `Truncated` (the guard runs
        // before the version check), NOT `UnsupportedVersion(0xFF)`.
        assert!(matches!(
            p.restore(&[0xFF; 4]).unwrap_err(),
            PpuSnapshotError::Truncated(_)
        ));
    }

    #[test]
    fn snapshot_rejects_bad_version() {
        let mut p = Ppu::new(PpuRegion::Ntsc);
        // A full-size blob (past the truncation guard) whose version byte is
        // unknown must be rejected at the version check — not mistaken for a
        // truncated blob. (A short bad-version blob is a Truncated case,
        // covered by `snapshot_rejects_short_blob`.)
        let mut blob = p.snapshot();
        blob[0] = 0xFF;
        let err = p.restore(&blob).unwrap_err();
        assert!(matches!(err, PpuSnapshotError::UnsupportedVersion(0xFF)));
    }

    #[test]
    fn snapshot_is_deterministic() {
        let p = Ppu::new(PpuRegion::Ntsc);
        assert_eq!(p.snapshot(), p.snapshot());
    }

    #[test]
    fn snapshot_round_trips_sprite_evaluation_state() {
        // v8: a snapshot taken with a sprite-evaluation pass in flight (dots
        // 65..=256) must restore the FSM's pointers and phase, not just the
        // `secondary_oam` buffer they fill. Before this tail, run-ahead's
        // per-frame snapshot/restore silently reset the walker while keeping the
        // buffer, costing three AccuracyCoin tests on the desktop frontend.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.sprite_eval_read_latch = 0x5A;
        p.sprite_eval_n = 37;
        p.sprite_eval_m = 2;
        p.sprite_eval_found = 6;
        p.sprite_eval_sec_idx = 25;
        p.sprite_eval_copying = true;
        p.sprite_eval_done = false;
        p.sprite_eval_overflow_search = true;
        p.sprite_eval_zero_found = true;
        p.sprite_eval_first_iter = false;
        p.oam_bus_copybuffer = 0xC3;
        p.oam_bus_secondary = [0x11; 32];
        p.oam_bus_secondary[7] = 0x99;
        p.oam_bus_addr_h = 41;
        p.oam_bus_addr_l = 3;
        p.oam_bus_secondary_addr = 18;
        p.oam_bus_copy_done = true;
        p.oam_bus_sprite_in_range = true;
        p.oam_bus_overflow_counter = 5;
        p.oam2_addr = 12;

        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.sprite_eval_read_latch, 0x5A);
        assert_eq!(q.sprite_eval_n, 37);
        assert_eq!(q.sprite_eval_m, 2);
        assert_eq!(q.sprite_eval_found, 6);
        assert_eq!(q.sprite_eval_sec_idx, 25);
        assert!(q.sprite_eval_copying);
        assert!(!q.sprite_eval_done);
        assert!(q.sprite_eval_overflow_search);
        assert!(q.sprite_eval_zero_found);
        assert!(!q.sprite_eval_first_iter);
        assert_eq!(q.oam_bus_copybuffer, 0xC3);
        assert_eq!(q.oam_bus_secondary[7], 0x99);
        assert_eq!(q.oam_bus_secondary[0], 0x11);
        assert_eq!(q.oam_bus_addr_h, 41);
        assert_eq!(q.oam_bus_addr_l, 3);
        assert_eq!(q.oam_bus_secondary_addr, 18);
        assert!(q.oam_bus_copy_done);
        assert!(q.oam_bus_sprite_in_range);
        assert_eq!(q.oam_bus_overflow_counter, 5);
        assert_eq!(q.oam2_addr, 12);
    }

    #[test]
    fn restore_invalidates_the_scanline_classification_cache() {
        // The cache is derived (a pure function of `scanline` + `region`) and so
        // deliberately NOT serialized. Restore must therefore reset its KEY to
        // the `Ppu::new` sentinel: a warm key inherited from another timeline
        // would otherwise satisfy the fast dot path's
        // `scanline == flags_cached_scanline` guard against a stale value.
        let p = Ppu::new(PpuRegion::Ntsc);
        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.cached_visible = true;
        q.cached_pre_render = true;
        q.cached_render_line = true;
        q.flags_cached_scanline = 42;
        q.restore(&blob).unwrap();
        assert!(!q.cached_visible);
        assert!(!q.cached_pre_render);
        assert!(!q.cached_render_line);
        assert_eq!(q.flags_cached_scanline, i16::MIN);
    }

    #[test]
    fn snapshot_round_trips_extra_lines_remaining() {
        // v1.7.0 F3: a save-state taken mid-insertion (extra_lines_remaining
        // > 0) must restore the in-flight countdown, not reset it to 0.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_extra_scanlines(8);
        p.extra_lines_remaining = 5;
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.extra_lines_remaining, 5);
    }

    #[test]
    fn snapshot_round_trips_2cycle_ale_fetch_state() {
        // v2.0.3 (ADR 0030): a checkpoint taken mid-render (netplay rollback)
        // can land with the 2-cycle-ALE fetch model's in-flight state live —
        // the octal latch / multiplexed bus, the ALE arm, and the two corruption
        // one-shots (`pattern_latch_stale`, the delayed-`CopyV` `copy_v_delay`).
        // They must round-trip so the re-simulated frame is byte-identical to the
        // forward run (else the peers desync). Regression pin for the promotion.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.octal_latch = 0x19;
        p.address_bus = 0x2F19;
        p.ale_armed = true;
        p.pattern_latch_stale = true;
        p.copy_v_delay = 3;
        let blob = p.snapshot();

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.octal_latch, 0x19);
        assert_eq!(q.address_bus, 0x2F19);
        assert!(q.ale_armed);
        assert!(q.pattern_latch_stale);
        assert_eq!(q.copy_v_delay, 3);
    }

    /// v2.3.3 — a slim blob must be dramatically smaller, and the size
    /// difference must be exactly the framebuffer.
    #[test]
    fn slim_snapshot_omits_exactly_the_framebuffer() {
        let p = Ppu::new(PpuRegion::Ntsc);
        let full = p.snapshot();
        let slim = p.snapshot_slim();
        assert_eq!(
            full.len() - slim.len(),
            FRAMEBUFFER_LEN,
            "slim must differ from full by exactly the framebuffer"
        );
    }

    /// A slim blob restores every field EXCEPT the framebuffer, which it must
    /// leave untouched (the caller regenerates the image).
    #[test]
    fn slim_restore_preserves_the_existing_framebuffer() {
        let mut src = Ppu::new(PpuRegion::Ntsc);
        src.framebuffer[100] = 0xAB;
        src.spr_count = 5;
        let slim = src.snapshot_slim();

        let mut dst = Ppu::new(PpuRegion::Ntsc);
        dst.framebuffer[100] = 0xEF; // must survive the restore
        dst.spr_count = 0;
        dst.restore(&slim).expect("slim blob restores");
        assert_eq!(dst.spr_count, 5, "non-framebuffer state must restore");
        assert_eq!(
            dst.framebuffer[100], 0xEF,
            "slim restore must not touch the framebuffer"
        );
    }

    /// The flag must not disturb the existing format: a full blob still round
    /// trips its framebuffer, and its version byte has the flag clear.
    #[test]
    fn full_snapshot_is_unchanged_by_the_slim_flag() {
        let mut src = Ppu::new(PpuRegion::Ntsc);
        src.framebuffer[100] = 0xAB;
        let full = src.snapshot();
        assert_eq!(full[0] & PPU_SNAPSHOT_SLIM_FLAG, 0, "flag clear on full");
        assert_eq!(full[0], PPU_SNAPSHOT_VERSION);
        let mut dst = Ppu::new(PpuRegion::Ntsc);
        dst.restore(&full).expect("full blob restores");
        assert_eq!(dst.framebuffer[100], 0xAB);
    }

    /// A truncated slim blob must still be rejected — the relaxed minimum
    /// must not become a hole that accepts garbage.
    #[test]
    fn truncated_slim_blob_is_still_rejected() {
        let p = Ppu::new(PpuRegion::Ntsc);
        let slim = p.snapshot_slim();
        let mut dst = Ppu::new(PpuRegion::Ntsc);
        assert!(dst.restore(&slim[..slim.len() / 2]).is_err());
    }

    #[test]
    fn snapshot_round_trips_oam_decay_ages() {
        // v2.1.4 F2.3: the optional OAM-decay per-row timestamps must round-trip.
        // They are stored as a RELATIVE AGE against the un-serialized `dot_counter`,
        // so the exact absolute value is preserved only when the restoring instance
        // shares the same live counter (the normal same-instance snapshot/restore).
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_oam_decay(true);
        p.dot_counter = 90_000; // now = 30_000 CPU cycles
        // Distinct per-row timestamps (ages 0, 3, 6, ... spread across the array).
        for (i, ts) in p.oam_decay_cycles.iter_mut().enumerate() {
            *ts = 30_000 - (i as u64 * 3);
        }
        let blob = p.snapshot();
        assert_eq!(
            blob[0], PPU_SNAPSHOT_VERSION,
            "blob carries current version"
        );

        // Restore into an instance with the SAME live counter → exact timestamps.
        let mut q = Ppu::new(PpuRegion::Pal);
        q.dot_counter = 90_000;
        q.restore(&blob).unwrap();
        assert_eq!(
            q.oam_decay_cycles, p.oam_decay_cycles,
            "absolute timestamps preserved when the live counter matches"
        );

        // Restore into an instance whose counter has been REBASED (the rollback
        // case): the *relative age* — what the decay clock actually consumes — must
        // be identical, even though the absolute timestamps differ.
        let mut q2 = Ppu::new(PpuRegion::Ntsc);
        q2.dot_counter = 3 * 1_000_000; // a wildly different base (now = 1_000_000)
        q2.restore(&blob).unwrap();
        let now_p = p.dot_counter / 3;
        let now_q2 = q2.dot_counter / 3;
        for i in 0..32 {
            let age_p = now_p.wrapping_sub(p.oam_decay_cycles[i]);
            let age_q2 = now_q2.wrapping_sub(q2.oam_decay_cycles[i]);
            assert_eq!(age_p, age_q2, "row {i} age preserved across counter rebase");
        }
    }

    #[test]
    fn snapshot_pre_v7_blob_upconverts_oam_decay_to_rest() {
        // A v6 blob lacks the OAM-decay tail; the v7 reader must upconvert it by
        // stamping every row as freshly-touched at the live cycle (age 0), which is
        // the rest state (decay is off in any pre-v7 build, so the array is inert).
        // Synthesize a v6 blob by snapshotting the current version and truncating
        // BOTH the v8 sprite-evaluation tail (50 bytes) and the v7 OAM-decay tail
        // (256 bytes), then rewriting the version byte.
        let p = Ppu::new(PpuRegion::Ntsc);
        let cur = p.snapshot();
        let mut v6 = cur[..cur.len() - (50 + 256)].to_vec();
        v6[0] = 6;

        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.dot_counter = 3 * 12_345; // now = 12_345
        q.restore(&v6).expect("v6 blob must upconvert");
        assert_eq!(
            q.oam_decay_cycles, [12_345u64; 32],
            "pre-v7 rows stamped fresh at the live cycle"
        );
    }

    #[test]
    fn snapshot_default_extra_lines_remaining_is_zero() {
        // At the default extra_scanlines == 0 the countdown is always 0, so
        // the v4 field is a zero u16 and restore is behaviourally identical.
        let p = Ppu::new(PpuRegion::Ntsc);
        assert_eq!(p.extra_lines_remaining, 0);
        let blob = p.snapshot();
        let mut q = Ppu::new(PpuRegion::Ntsc);
        q.restore(&blob).unwrap();
        assert_eq!(q.extra_lines_remaining, 0);
    }

    #[test]
    fn set_extra_scanlines_resets_in_flight_countdown() {
        // Changing the configured count cancels any in-flight insertion so
        // the per-frame countdown cannot remain stale/out-of-bounds.
        let mut p = Ppu::new(PpuRegion::Ntsc);
        p.set_extra_scanlines(8);
        p.extra_lines_remaining = 6;
        p.set_extra_scanlines(2);
        assert_eq!(p.extra_lines_remaining, 0);
        p.extra_lines_remaining = 1;
        p.set_extra_scanlines(0); // disable
        assert_eq!(p.extra_lines_remaining, 0);
    }
}