//! Per-pixel reads and writes into raw byte buffers in a given [`PixelFormat`].
//!
//! These wrap raylib's `GetPixelColor` / `SetPixelColor` C functions and are
//! the right tools when you have a byte buffer (e.g. one you're about to
//! upload to a [`Texture2D`](crate::core::texture::Texture2D), or a CPU
//! framebuffer you generated yourself) and want to read or write a single
//! pixel value while staying format-aware.
//!
//! If you instead have an [`Image`](crate::core::texture::Image) and want
//! the pixel at coordinates `(x, y)`, use
//! [`Image::get_color`](crate::core::texture::Image::get_color) — that goes
//! through raylib's separate `GetImageColor` C function and handles the row
//! stride for you.
//!
//! # BGRA limitation
//!
//! raylib's [`PixelFormat`] enum has no `B8G8R8A8` variant. The rlsw
//! software-renderer test harness stores its framebuffer as BGRA bytes
//! while labeling them with `PIXELFORMAT_UNCOMPRESSED_R8G8B8A8`, and the
//! channel swap is expressed as a bespoke byte-swap loop in
//! `raylib::test_harness::normalize_readback`. These functions cannot
//! eliminate that loop — feeding them BGRA bytes labeled as
//! `R8G8B8A8` returns a `Color` with R and B swapped, which is the same
//! problem.

use crate::consts::PixelFormat;
use crate::core::Color;
use crate::ffi;

/// Errors returned by [`get_pixel_color`] / [`set_pixel_color`].
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum PixelColorError {
    /// The byte slice is shorter than the format requires.
    #[error("pixel format {format:?} needs {expected} bytes per pixel, got {actual}")]
    InsufficientBytes {
        /// The format the call was made against.
        format: PixelFormat,
        /// Bytes required for one pixel in this format.
        expected: usize,
        /// Bytes actually provided.
        actual: usize,
    },
    /// Compressed formats are block-addressed; they cannot be read or
    /// written one pixel at a time. raylib's `GetPixelColor` does not
    /// support them either.
    #[error("compressed pixel format {0:?} cannot be addressed pixel-by-pixel")]
    CompressedFormat(PixelFormat),
}

/// Bytes per single pixel for an uncompressed [`PixelFormat`].
///
/// Returns `None` for compressed variants — they are addressed by
/// block, not pixel.
///
/// The match is exhaustive (no wildcard). If raylib adds a new
/// `PixelFormat` variant in a future version, this function will fail
/// to compile, surfacing the change rather than silently returning
/// `None`.
pub fn bytes_per_pixel(format: PixelFormat) -> Option<usize> {
    use PixelFormat::*;
    Some(match format {
        PIXELFORMAT_UNCOMPRESSED_GRAYSCALE => 1,
        PIXELFORMAT_UNCOMPRESSED_GRAY_ALPHA => 2,
        PIXELFORMAT_UNCOMPRESSED_R5G6B5 => 2,
        PIXELFORMAT_UNCOMPRESSED_R5G5B5A1 => 2,
        PIXELFORMAT_UNCOMPRESSED_R4G4B4A4 => 2,
        PIXELFORMAT_UNCOMPRESSED_R8G8B8 => 3,
        PIXELFORMAT_UNCOMPRESSED_R8G8B8A8 => 4,
        PIXELFORMAT_UNCOMPRESSED_R32 => 4,
        PIXELFORMAT_UNCOMPRESSED_R32G32B32 => 12,
        PIXELFORMAT_UNCOMPRESSED_R32G32B32A32 => 16,
        PIXELFORMAT_UNCOMPRESSED_R16 => 2,
        PIXELFORMAT_UNCOMPRESSED_R16G16B16 => 6,
        PIXELFORMAT_UNCOMPRESSED_R16G16B16A16 => 8,
        PIXELFORMAT_COMPRESSED_DXT1_RGB
        | PIXELFORMAT_COMPRESSED_DXT1_RGBA
        | PIXELFORMAT_COMPRESSED_DXT3_RGBA
        | PIXELFORMAT_COMPRESSED_DXT5_RGBA
        | PIXELFORMAT_COMPRESSED_ETC1_RGB
        | PIXELFORMAT_COMPRESSED_ETC2_RGB
        | PIXELFORMAT_COMPRESSED_ETC2_EAC_RGBA
        | PIXELFORMAT_COMPRESSED_PVRT_RGB
        | PIXELFORMAT_COMPRESSED_PVRT_RGBA
        | PIXELFORMAT_COMPRESSED_ASTC_4x4_RGBA
        | PIXELFORMAT_COMPRESSED_ASTC_8x8_RGBA => return None,
    })
}

/// Validate that `len` bytes is enough for one pixel in `format` and
/// that `format` is uncompressed. Returns the required byte count on
/// success.
fn validate_slice(len: usize, format: PixelFormat) -> Result<usize, PixelColorError> {
    match bytes_per_pixel(format) {
        None => Err(PixelColorError::CompressedFormat(format)),
        Some(expected) if len < expected => Err(PixelColorError::InsufficientBytes {
            format,
            expected,
            actual: len,
        }),
        Some(expected) => Ok(expected),
    }
}

/// Read a single pixel from `bytes` interpreted as `format`.
///
/// `bytes` must contain at least `bytes_per_pixel(format)?` bytes; any
/// trailing bytes are ignored. Returns
/// [`PixelColorError::CompressedFormat`] for block-compressed formats,
/// or [`PixelColorError::InsufficientBytes`] when the slice is too
/// short.
pub fn get_pixel_color(
    bytes: &[u8],
    format: PixelFormat,
) -> Result<Color, PixelColorError> {
    validate_slice(bytes.len(), format)?;
    // SAFETY: validate_slice ensured `bytes.len() >= bytes_per_pixel(format)`,
    // so raylib reads only within the slice. GetPixelColor's signature is
    // `void *` even though the C body only reads from srcPtr (verified in
    // raylib-sys/raylib/src/rtextures.c around line 5174), so casting
    // `*const u8` to `*mut u8` is sound.
    Ok(unsafe { ffi::GetPixelColor(bytes.as_ptr() as *mut _, format as i32) })
}

/// Write `color` into `bytes` encoded as `format`.
///
/// Same length / format-validity rules as [`get_pixel_color`].
/// Trailing bytes beyond `bytes_per_pixel(format)?` are not touched.
pub fn set_pixel_color(
    bytes: &mut [u8],
    color: Color,
    format: PixelFormat,
) -> Result<(), PixelColorError> {
    validate_slice(bytes.len(), format)?;
    // SAFETY: validate_slice ensured `bytes.len() >= bytes_per_pixel(format)`,
    // so raylib writes only within the slice. SetPixelColor writes exactly
    // `bytes_per_pixel(format)` bytes starting at dstPtr.
    unsafe {
        ffi::SetPixelColor(bytes.as_mut_ptr() as *mut _, color, format as i32);
    }
    Ok(())
}

pub use crate::core::pixel::{
    PixelColorError, bytes_per_pixel, get_pixel_color, set_pixel_color,
};

git add raylib/src/core/pixel.rs raylib/src/core/mod.rs raylib/src/prelude.rs
git commit -m "$(cat <<'EOF'
feat(pixel): scaffold pixel-pointers module with stubs + error type

New raylib/src/core/pixel.rs surfaces:
- PixelColorError (thiserror with InsufficientBytes + CompressedFormat)
- bytes_per_pixel(PixelFormat) -> Option<usize>     [exhaustive match]
- get_pixel_color(&[u8], PixelFormat) -> Result<Color, _>
- set_pixel_color(&mut [u8], Color, PixelFormat) -> Result<(), _>
- private validate_slice helper

Wired into raylib::core via `pub mod pixel;` + re-export, and into
raylib::prelude so `use raylib::prelude::*;` brings the four public
items into scope.

Implementation is complete (FFI calls + validation); tests follow in
the next tasks. Module-level rustdoc explains when to reach for these
vs Image::get_color, and documents the BGRA-not-supported limitation
that the test_harness BGRA quirk lives outside raylib's PixelFormat
model and cannot be wrapped through these fns.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

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

    /// Every uncompressed PixelFormat paired with its bytes-per-pixel
    /// count. Used by the round-trip tests, the bytes_per_pixel
    /// cross-check, and the trailing-bytes test.
    const UNCOMPRESSED_FORMATS: &[(PixelFormat, usize)] = &[
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_GRAYSCALE, 1),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_GRAY_ALPHA, 2),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R5G6B5, 2),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R5G5B5A1, 2),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R4G4B4A4, 2),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8, 3),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8, 4),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R32, 4),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R32G32B32, 12),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R32G32B32A32, 16),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R16, 2),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R16G16B16, 6),
        (PixelFormat::PIXELFORMAT_UNCOMPRESSED_R16G16B16A16, 8),
    ];
}

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): add shared UNCOMPRESSED_FORMATS table for the test module

The const table pairs each of the 13 uncompressed PixelFormat variants
with its bytes-per-pixel count. Used by upcoming round-trip,
bytes_per_pixel cross-check, and trailing-bytes tests so each test is
data-driven and a future enum addition only needs the table updated.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

    #[test]
    fn bytes_per_pixel_agrees_with_raylib() {
        for &(format, expected) in UNCOMPRESSED_FORMATS {
            let bpp = bytes_per_pixel(format)
                .unwrap_or_else(|| panic!("{format:?} should be uncompressed"));
            assert_eq!(bpp, expected, "{format:?}: table says {expected}, fn says {bpp}");

            // raylib computes the same byte count via GetPixelDataSize(1, 1, ...).
            let raylib_bpp = unsafe {
                crate::ffi::GetPixelDataSize(1, 1, format as i32)
            } as usize;
            assert_eq!(
                bpp, raylib_bpp,
                "{format:?}: rust says {bpp}, raylib's GetPixelDataSize(1,1,...) says {raylib_bpp}"
            );
        }
    }

    #[test]
    fn bytes_per_pixel_none_for_every_compressed_variant() {
        // Listed exhaustively (no for-loop over a slice) so an enum addition
        // surfaces as a missing arm here, matching the exhaustive-match
        // pattern in bytes_per_pixel itself.
        use PixelFormat::*;
        for format in [
            PIXELFORMAT_COMPRESSED_DXT1_RGB,
            PIXELFORMAT_COMPRESSED_DXT1_RGBA,
            PIXELFORMAT_COMPRESSED_DXT3_RGBA,
            PIXELFORMAT_COMPRESSED_DXT5_RGBA,
            PIXELFORMAT_COMPRESSED_ETC1_RGB,
            PIXELFORMAT_COMPRESSED_ETC2_RGB,
            PIXELFORMAT_COMPRESSED_ETC2_EAC_RGBA,
            PIXELFORMAT_COMPRESSED_PVRT_RGB,
            PIXELFORMAT_COMPRESSED_PVRT_RGBA,
            PIXELFORMAT_COMPRESSED_ASTC_4x4_RGBA,
            PIXELFORMAT_COMPRESSED_ASTC_8x8_RGBA,
        ] {
            assert_eq!(
                bytes_per_pixel(format),
                None,
                "{format:?} should return None"
            );
        }
    }

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): bytes_per_pixel cross-check vs raylib + None-for-compressed

Two tests:
- bytes_per_pixel_agrees_with_raylib iterates UNCOMPRESSED_FORMATS and
  checks each entry against raylib's own GetPixelDataSize(1, 1, F).
  A future raylib format-layout change trips here immediately.
- bytes_per_pixel_none_for_every_compressed_variant lists the 11
  compressed variants explicitly (no wildcard) so an enum addition
  surfaces as a missing entry in the test.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

    #[test]
    fn get_returns_insufficient_bytes_on_short_slice() {
        // R8G8B8A8 needs 4 bytes.
        let empty = &[] as &[u8];
        assert_eq!(
            get_pixel_color(empty, PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8),
            Err(PixelColorError::InsufficientBytes {
                format: PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
                expected: 4,
                actual: 0,
            }),
        );

        let two_bytes = [0u8; 2];
        assert_eq!(
            get_pixel_color(&two_bytes, PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8),
            Err(PixelColorError::InsufficientBytes {
                format: PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
                expected: 4,
                actual: 2,
            }),
        );
    }

    #[test]
    fn set_returns_insufficient_bytes_on_short_slice() {
        let mut empty: Vec<u8> = vec![];
        assert_eq!(
            set_pixel_color(
                &mut empty,
                Color::new(255, 0, 0, 255),
                PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
            ),
            Err(PixelColorError::InsufficientBytes {
                format: PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
                expected: 4,
                actual: 0,
            }),
        );

        let mut two_bytes = [0u8; 2];
        assert_eq!(
            set_pixel_color(
                &mut two_bytes,
                Color::new(255, 0, 0, 255),
                PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
            ),
            Err(PixelColorError::InsufficientBytes {
                format: PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
                expected: 4,
                actual: 2,
            }),
        );
    }

    #[test]
    fn get_returns_compressed_format_for_compressed_input() {
        let bytes = [0u8; 8];
        assert_eq!(
            get_pixel_color(&bytes, PixelFormat::PIXELFORMAT_COMPRESSED_DXT1_RGB),
            Err(PixelColorError::CompressedFormat(
                PixelFormat::PIXELFORMAT_COMPRESSED_DXT1_RGB
            )),
        );
    }

    #[test]
    fn set_returns_compressed_format_for_compressed_input() {
        let mut bytes = [0u8; 8];
        assert_eq!(
            set_pixel_color(
                &mut bytes,
                Color::new(0, 0, 0, 0),
                PixelFormat::PIXELFORMAT_COMPRESSED_DXT1_RGB,
            ),
            Err(PixelColorError::CompressedFormat(
                PixelFormat::PIXELFORMAT_COMPRESSED_DXT1_RGB
            )),
        );
    }

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): error-variant coverage for get/set_pixel_color

Four #[test] functions covering the two error variants:
- get/set_returns_insufficient_bytes_on_short_slice: empty + 2-byte
  slice against R8G8B8A8 (which needs 4 bytes).
- get/set_returns_compressed_format_for_compressed_input: 8-byte slice
  fed to DXT1_RGB rejects with CompressedFormat regardless of slice
  length — the format validation runs first.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

    #[test]
    fn round_trip_all_ff_for_every_uncompressed_format() {
        let input = Color::new(0xFF, 0xFF, 0xFF, 0xFF);
        for &(format, bpp) in UNCOMPRESSED_FORMATS {
            let mut bytes = vec![0u8; bpp];
            set_pixel_color(&mut bytes, input, format).unwrap_or_else(|e| {
                panic!("set_pixel_color({format:?}) errored: {e}")
            });
            let got = get_pixel_color(&bytes, format).unwrap_or_else(|e| {
                panic!("get_pixel_color({format:?}) errored: {e}")
            });
            assert_eq!(
                got, input,
                "{format:?}: all-FF round-trip diverged (got {got:?}, expected {input:?})"
            );
        }
    }

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): all-FF round-trip for every uncompressed format

For each of the 13 uncompressed PixelFormat variants, encode
Color::new(0xFF, 0xFF, 0xFF, 0xFF) via set_pixel_color and decode via
get_pixel_color; assert exact equality. Max values quantize cleanly
through every variant including the lossy 5/6/4-bit channels (31 → 255
for 5-bit, 63 → 255 for 6-bit, 15 → 255 for 4-bit).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

    /// Per-channel tolerance for a format's lossy quantization.
    /// Returns (rgb_tol, alpha_tol) where each is the maximum allowed
    /// `|got - expected|` for the given channel.
    fn tolerance(format: PixelFormat) -> (u8, u8) {
        use PixelFormat::*;
        match format {
            // 8-bit channels: exact except for the lossy GRAYSCALE collapse.
            PIXELFORMAT_UNCOMPRESSED_R8G8B8 => (0, 0),
            PIXELFORMAT_UNCOMPRESSED_R8G8B8A8 => (0, 0),
            // 32-bit float channels: ±1 LSB from the `u8 → f32 / 255 → * 255 → u8`
            // truncation (e.g. 192 → 0.7529... → 191.999... → 191).
            PIXELFORMAT_UNCOMPRESSED_R32 => (1, 0),
            PIXELFORMAT_UNCOMPRESSED_R32G32B32 => (1, 0),
            PIXELFORMAT_UNCOMPRESSED_R32G32B32A32 => (1, 1),
            // 16-bit half-float: ±1 LSB from half-float precision.
            PIXELFORMAT_UNCOMPRESSED_R16 => (1, 0),
            PIXELFORMAT_UNCOMPRESSED_R16G16B16 => (1, 0),
            PIXELFORMAT_UNCOMPRESSED_R16G16B16A16 => (1, 1),
            // 5/6/4-bit channels: quantization step roughly 255/(2^k - 1):
            // 5-bit -> step 8 -> tolerance 4 (half-step). Allow 8 to absorb
            // any rounding choice the C code makes.
            PIXELFORMAT_UNCOMPRESSED_R5G6B5 => (8, 0),
            PIXELFORMAT_UNCOMPRESSED_R5G5B5A1 => (8, 0), // alpha is 0 or 255 only
            PIXELFORMAT_UNCOMPRESSED_R4G4B4A4 => (16, 16), // 4-bit step ~17.
            // Grayscale: collapses R/G/B to a single channel; the round-trip
            // produces three identical channels. We don't compare per-channel
            // tolerance for these — they get a separate assertion path.
            PIXELFORMAT_UNCOMPRESSED_GRAYSCALE => (0, 0),
            PIXELFORMAT_UNCOMPRESSED_GRAY_ALPHA => (0, 0),
            // Compressed formats can't reach this code path.
            f => unreachable!("tolerance() called with non-uncompressed format {f:?}"),
        }
    }

    fn within_tolerance(got: u8, expected: u8, tol: u8) -> bool {
        got.abs_diff(expected) <= tol
    }

    #[test]
    fn round_trip_channel_distinct_with_tolerance() {
        let input = Color::new(0xC0, 0x80, 0x40, 0xFF);
        for &(format, bpp) in UNCOMPRESSED_FORMATS {
            let mut bytes = vec![0u8; bpp];
            set_pixel_color(&mut bytes, input, format).unwrap();
            let got = get_pixel_color(&bytes, format).unwrap();

            use PixelFormat::*;
            match format {
                // Grayscale collapses R/G/B; the round-trip's three RGB
                // channels are identical to each other, and alpha is fixed
                // to 255 (GRAYSCALE) or input.a (GRAY_ALPHA).
                PIXELFORMAT_UNCOMPRESSED_GRAYSCALE => {
                    assert_eq!(got.r, got.g, "{format:?}: R==G after collapse");
                    assert_eq!(got.g, got.b, "{format:?}: G==B after collapse");
                    assert_eq!(got.a, 255, "{format:?}: alpha forced to 255");
                }
                PIXELFORMAT_UNCOMPRESSED_GRAY_ALPHA => {
                    assert_eq!(got.r, got.g, "{format:?}: R==G after collapse");
                    assert_eq!(got.g, got.b, "{format:?}: G==B after collapse");
                    assert_eq!(got.a, input.a, "{format:?}: alpha exact");
                }
                _ => {
                    let (rgb_tol, a_tol) = tolerance(format);
                    assert!(
                        within_tolerance(got.r, input.r, rgb_tol),
                        "{format:?}: R got {} expected {} (tol {rgb_tol})",
                        got.r, input.r
                    );
                    assert!(
                        within_tolerance(got.g, input.g, rgb_tol),
                        "{format:?}: G got {} expected {} (tol {rgb_tol})",
                        got.g, input.g
                    );
                    assert!(
                        within_tolerance(got.b, input.b, rgb_tol),
                        "{format:?}: B got {} expected {} (tol {rgb_tol})",
                        got.b, input.b
                    );
                    assert!(
                        within_tolerance(got.a, input.a, a_tol),
                        "{format:?}: A got {} expected {} (tol {a_tol})",
                        got.a, input.a
                    );
                }
            }
        }
    }

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): channel-distinct round-trip with per-format tolerance

Encode Color::new(0xC0, 0x80, 0x40, 0xFF) into every uncompressed
PixelFormat and verify the decoded color matches within a
quantization-step-aware tolerance:

- 8-bit RGB(A) formats: exact (tol 0).
- 32-bit / 16-bit float formats: ±1 LSB (float rounding).
- 5/6-bit channels: ±8 LSBs (5-bit step ~8.2).
- 4-bit channels: ±16 LSBs (4-bit step ~17).
- GRAYSCALE / GRAY_ALPHA: assert the channel-collapse invariant
  (R==G==B post-round-trip) and alpha handling, not specific values.

Tolerances are pinned to the minimum that passes; if any future raylib
quantization change tightens or relaxes them, update the table.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

    #[test]
    fn trailing_bytes_are_ignored() {
        // 64-byte buffer fed to a 4-byte format must produce the same result
        // as exactly 4 bytes.
        let exact = [0x11, 0x22, 0x33, 0x44];
        let long = [
            0x11, 0x22, 0x33, 0x44, // first pixel
            0xAA, 0xBB, 0xCC, 0xDD, // these bytes must be ignored
            0xEE, 0xFF, 0x00, 0x11, //
            0x22, 0x33, 0x44, 0x55, //
        ];

        let got_exact = get_pixel_color(
            &exact,
            PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
        )
        .unwrap();
        let got_long = get_pixel_color(
            &long,
            PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
        )
        .unwrap();
        assert_eq!(got_exact, got_long, "trailing bytes must not affect read");

        // Symmetric check for set: writing to a too-long buffer touches
        // only the first N bytes.
        let mut exact_out = [0u8; 4];
        let mut long_out = [0u8; 16];
        let sentinel = 0xA5;
        long_out[4..].fill(sentinel);
        let color = Color::new(0x11, 0x22, 0x33, 0x44);

        set_pixel_color(
            &mut exact_out,
            color,
            PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
        )
        .unwrap();
        set_pixel_color(
            &mut long_out,
            color,
            PixelFormat::PIXELFORMAT_UNCOMPRESSED_R8G8B8A8,
        )
        .unwrap();

        assert_eq!(&long_out[..4], &exact_out, "first 4 bytes must match");
        for (i, &b) in long_out[4..].iter().enumerate() {
            assert_eq!(b, sentinel, "byte {} past the pixel must be untouched", i + 4);
        }
    }

git add raylib/src/core/pixel.rs
git commit -m "$(cat <<'EOF'
test(pixel): trailing-bytes-ignored contract

set/get_pixel_color must touch only the first bytes_per_pixel(format)
bytes of the slice. The test:
- Confirms get_pixel_color on a 16-byte buffer matches the result on a
  4-byte buffer with the same prefix.
- Confirms set_pixel_color leaves bytes past the pixel untouched
  (verified via a sentinel pattern).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

- 🟥 `GetPixelColor` — GAP. Action: small fix-now (cheatsheet audit §3).

- ✅ `GetPixelColor` — wrapped at `raylib/src/core/pixel.rs::get_pixel_color`.

- New module `raylib::core::pixel` with safe wrappers over raylib's
  pixel-pointer C functions:
  - `get_pixel_color(bytes: &[u8], format: PixelFormat) -> Result<Color, PixelColorError>`
  - `set_pixel_color(bytes: &mut [u8], color: Color, format: PixelFormat) -> Result<(), PixelColorError>`
  - `bytes_per_pixel(format: PixelFormat) -> Option<usize>` helper
  - `PixelColorError` (thiserror) with `InsufficientBytes` and `CompressedFormat` variants
  All four are re-exported through `raylib::prelude`.

git add docs/superpowers/notes/cheatsheet-parity-audit.md CHANGELOG.md
git commit -m "$(cat <<'EOF'
docs(pixel-pointers): mark GetPixelColor / SetPixelColor as covered

The pixel-pointers workstream from cheatsheet-parity-audit.md §4 #1 is
done; reconcile the audit + CHANGELOG accordingly.

- cheatsheet-parity-audit.md:
  - §1 entries for GetPixelColor + SetPixelColor flip 🟥 -> ✅ pointing
    at raylib/src/core/pixel.rs.
  - §0 totals: Covered 486 -> 488, gaps 13 -> 11, small fixes 5 -> 3.
  - §4 workstream #1 (pixel-pointers) removed; remaining items
    renumbered (hashes -> #1, mixed-audio -> #2).
- CHANGELOG.md ## 6.0.0-rc.1 (unreleased) ### Added: lists the new
  raylib::core::pixel module with the four public items.

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"

git add CLAUDE.md
git commit -m "$(cat <<'EOF'
docs(roadmap): pixel-pointers complete; hashes is next

CLAUDE.md status line: pre-WS9 queue head flips from pixel-pointers to
hashes. See docs/superpowers/notes/cheatsheet-parity-audit.md for the
updated cheatsheet coverage (488 / 500 in-scope).

Co-Authored-By: Claude Opus 4.7 <[email protected]>
EOF
)"
git push fork 6.0-rc
git push fork 6.0-rc:unstable