rpdfium_codec/basic/

mod.rs

// Derived from PDFium's basic/basicmodule.h/cpp
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Basic stream filters — ASCII85, ASCIIHex, RunLength.
//!
//! All three filters are consolidated here, mirroring PDFium's single
//! `core/fxcodec/basic/basicmodule.h/cpp` source file.
//!
//! | PDFium `BasicModule` | rpdfium |
//! |---|---|
//! | `A85Encode()` | [`ascii85::encode`] |
//! | *(decode via codec pipeline)* | [`ascii85::decode`] |
//! | *(decode via codec pipeline)* | [`ascii_hex::decode`] |
//! | `RunLengthEncode()` | [`run_length::encode`] |
//! | *(decode via codec pipeline)* | [`run_length::decode`] |
//! | `CreateRunLengthDecoder()` | [`run_length::create_decoder`] |

// ---------------------------------------------------------------------------
// ascii85
// ---------------------------------------------------------------------------

pub mod ascii85 {
    //! ASCII85Decode / ASCII85Encode filter.

    use crate::error::DecodeError;

    /// Encode binary data as ASCII85 (base-85).
    ///
    /// - Groups of 4 bytes encode to 5 ASCII characters in `!`–`u` range.
    /// - A group of 4 zero bytes encodes to the single character `z`.
    /// - A line break (`\r\n`) is inserted every 75 output characters.
    /// - Terminated with `~>`.
    ///
    /// Mirrors PDFium's `BasicModule::A85Encode()`.
    pub fn encode(input: &[u8]) -> Vec<u8> {
        if input.is_empty() {
            return Vec::new();
        }

        // Worst case: 5/4 expansion + line breaks + "~>" terminator
        let estimated = (input.len() / 4 + 1) * 5 + input.len() / 30 + 4;
        let mut output = Vec::with_capacity(estimated);
        let mut line_length = 0usize;
        let mut pos = 0usize;

        // Process full 4-byte groups
        while pos + 4 <= input.len() {
            let val =
                u32::from_be_bytes([input[pos], input[pos + 1], input[pos + 2], input[pos + 3]]);
            pos += 4;

            if val == 0 {
                // All-zero special case: 'z'
                output.push(b'z');
                line_length += 1;
            } else {
                let mut v = val as u64;
                let mut chars = [0u8; 5];
                for c in chars.iter_mut().rev() {
                    *c = (v % 85) as u8 + 33;
                    v /= 85;
                }
                output.extend_from_slice(&chars);
                line_length += 5;
            }

            if line_length >= 75 {
                output.extend_from_slice(b"\r\n");
                line_length = 0;
            }
        }

        // Leftover bytes (1–3): pad to 4 bytes, output count+1 digits
        if pos < input.len() {
            let count = input.len() - pos;
            let mut val = 0u32;
            for k in 0..count {
                val |= u32::from(input[pos + k]) << (8 * (3 - k));
            }
            let mut v = val as u64;
            let mut chars = [0u8; 5];
            // Compute all 5 digits (most-to-least significant at indices 0–4)
            // but only write the first count+1 of them.
            for i in (0..5usize).rev() {
                if i <= count {
                    chars[i] = (v % 85) as u8 + 33;
                }
                v /= 85;
            }
            output.extend_from_slice(&chars[..count + 1]);
        }

        output.extend_from_slice(b"~>");
        output
    }

    /// Decode ASCII85 (base-85) encoded data.
    ///
    /// - Groups of 5 ASCII characters in the range `!` (33) to `u` (117)
    ///   decode to 4 binary bytes.
    /// - The character `z` is a shortcut for 4 zero bytes.
    /// - The end-of-data marker is `~>`.
    /// - Whitespace is ignored.
    pub fn decode(input: &[u8]) -> Result<Vec<u8>, DecodeError> {
        let mut output = Vec::with_capacity(input.len() * 4 / 5);
        let mut group = [0u8; 5];
        let mut count = 0usize;

        let mut i = 0;
        while i < input.len() {
            let b = input[i];
            i += 1;

            // Whitespace — skip
            if b == b' ' || b == b'\t' || b == b'\n' || b == b'\r' || b == b'\x0C' {
                continue;
            }

            // End-of-data marker
            if b == b'~' {
                if i < input.len() && input[i] == b'>' {
                    break; // consume '>'
                }
                break; // '~' without '>' — lenient
            }

            // 'z' shortcut for four zero bytes
            if b == b'z' {
                if count != 0 {
                    return Err(DecodeError::InvalidInput(
                        "ASCII85: 'z' inside a group".into(),
                    ));
                }
                output.extend_from_slice(&[0, 0, 0, 0]);
                continue;
            }

            // Valid ASCII85 character range: '!' (33) to 'u' (117)
            if !(b'!'..=b'u').contains(&b) {
                return Err(DecodeError::InvalidInput(format!(
                    "ASCII85: invalid character 0x{b:02X}"
                )));
            }

            group[count] = b - b'!';
            count += 1;

            if count == 5 {
                let value = u64::from(group[0]) * 85 * 85 * 85 * 85
                    + u64::from(group[1]) * 85 * 85 * 85
                    + u64::from(group[2]) * 85 * 85
                    + u64::from(group[3]) * 85
                    + u64::from(group[4]);

                if value > u64::from(u32::MAX) {
                    return Err(DecodeError::InvalidInput(
                        "ASCII85: group value exceeds 2^32-1".into(),
                    ));
                }

                let value = value as u32;
                output.push((value >> 24) as u8);
                output.push((value >> 16) as u8);
                output.push((value >> 8) as u8);
                output.push(value as u8);
                count = 0;
            }
        }

        // Handle remaining partial group (1-4 chars)
        if count > 0 {
            if count == 1 {
                return Err(DecodeError::InvalidInput(
                    "ASCII85: single trailing character is invalid".into(),
                ));
            }

            // Pad with 'u' (84) to make a full group
            for slot in group.iter_mut().skip(count) {
                *slot = 84; // 'u' - '!' = 84
            }

            let value = u64::from(group[0]) * 85 * 85 * 85 * 85
                + u64::from(group[1]) * 85 * 85 * 85
                + u64::from(group[2]) * 85 * 85
                + u64::from(group[3]) * 85
                + u64::from(group[4]);

            if value > u64::from(u32::MAX) {
                return Err(DecodeError::InvalidInput(
                    "ASCII85: padded group value exceeds 2^32-1".into(),
                ));
            }

            let value = value as u32;
            let bytes = value.to_be_bytes();
            output.extend_from_slice(&bytes[..count - 1]);
        }

        Ok(output)
    }

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

        // --- encode ---

        #[test]
        fn test_encode_empty() {
            assert!(encode(&[]).is_empty());
        }

        #[test]
        fn test_encode_basic() {
            assert_eq!(encode(b"Man "), b"9jqo^~>");
        }

        #[test]
        fn test_encode_all_zeros() {
            assert_eq!(encode(&[0, 0, 0, 0]), b"z~>");
        }

        #[test]
        fn test_encode_partial_group() {
            let result = encode(b"a");
            assert!(result.ends_with(b"~>"));
            assert_eq!(result.len(), 4); // 2 digits + "~>"
        }

        #[test]
        fn test_encode_decode_roundtrip() {
            let original = b"Hello, World! This is a test of ASCII85.";
            let decoded = decode(&encode(original)).unwrap();
            assert_eq!(decoded, original);
        }

        #[test]
        fn test_encode_decode_roundtrip_all_bytes() {
            let original: Vec<u8> = (0u8..=255).collect();
            assert_eq!(decode(&encode(&original)).unwrap(), original);
        }

        #[test]
        fn test_encode_line_break_at_75() {
            let input = vec![0xABu8; 80];
            let encoded = encode(&input);
            assert!(encoded.windows(2).any(|w| w == b"\r\n"));
        }

        // --- decode ---

        #[test]
        fn test_decode_basic() {
            assert_eq!(decode(b"9jqo^~>").unwrap(), b"Man ");
        }

        #[test]
        fn test_decode_z_shortcut() {
            assert_eq!(decode(b"z~>").unwrap(), vec![0, 0, 0, 0]);
        }

        #[test]
        fn test_decode_z_shortcut_multiple() {
            assert_eq!(decode(b"zz~>").unwrap(), vec![0u8; 8]);
        }

        #[test]
        fn test_decode_whitespace_ignored() {
            assert_eq!(decode(b"9 jqo ^\n~>").unwrap(), b"Man ");
        }

        #[test]
        fn test_decode_empty() {
            assert!(decode(b"~>").unwrap().is_empty());
        }

        #[test]
        fn test_decode_partial_group() {
            let result = decode(b"9jqo^BlbD~>").unwrap();
            assert_eq!(&result[..4], b"Man ");
            assert_eq!(result.len(), 7);
        }

        #[test]
        fn test_decode_single_trailing_char_invalid() {
            assert!(decode(b"A~>").is_err());
        }

        #[test]
        fn test_decode_invalid_char() {
            assert!(decode(b"9jqo^{~>").is_err());
        }

        #[test]
        fn test_decode_z_inside_group_error() {
            assert!(decode(b"Az~>").is_err());
        }

        #[test]
        fn test_decode_no_eod_marker() {
            assert_eq!(decode(b"9jqo^").unwrap(), b"Man ");
        }

        #[test]
        fn test_decode_known_string() {
            assert_eq!(decode(b"87cURDe~>").unwrap(), b"Hello");
        }
    }
}

// ---------------------------------------------------------------------------
// ascii_hex
// ---------------------------------------------------------------------------

pub mod ascii_hex {
    //! ASCIIHexDecode filter.
    //!
    //! Note: PDFium's `BasicModule` does not include an ASCIIHex encoder;
    //! this decode-only module is an rpdfium extension.

    use crate::error::DecodeError;

    /// Decode ASCIIHex-encoded data.
    ///
    /// - Pairs of hexadecimal digits decode to bytes.
    /// - `>` marks end of data.
    /// - Whitespace is ignored.
    /// - An odd trailing nibble is zero-padded on the right (e.g., `A` → `0xA0`).
    pub fn decode(input: &[u8]) -> Result<Vec<u8>, DecodeError> {
        let mut output = Vec::with_capacity(input.len() / 2);
        let mut high_nibble: Option<u8> = None;

        for &b in input {
            if b == b'>' {
                break;
            }
            if b == b' ' || b == b'\t' || b == b'\n' || b == b'\r' || b == b'\x0C' {
                continue;
            }

            let nibble = hex_nibble(b)?;
            match high_nibble.take() {
                None => high_nibble = Some(nibble),
                Some(high) => output.push((high << 4) | nibble),
            }
        }

        // Odd trailing nibble: pad with 0 on the right
        if let Some(high) = high_nibble {
            output.push(high << 4);
        }

        Ok(output)
    }

    fn hex_nibble(b: u8) -> Result<u8, crate::error::DecodeError> {
        match b {
            b'0'..=b'9' => Ok(b - b'0'),
            b'a'..=b'f' => Ok(b - b'a' + 10),
            b'A'..=b'F' => Ok(b - b'A' + 10),
            _ => Err(crate::error::DecodeError::InvalidInput(format!(
                "ASCIIHex: invalid hex character 0x{b:02X}"
            ))),
        }
    }

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

        #[test]
        fn test_decode_basic() {
            assert_eq!(decode(b"48656C6C6F>").unwrap(), b"Hello");
        }

        #[test]
        fn test_decode_lowercase() {
            assert_eq!(decode(b"48656c6c6f>").unwrap(), b"Hello");
        }

        #[test]
        fn test_decode_whitespace_ignored() {
            assert_eq!(decode(b"48 65 6C\n6C 6F>").unwrap(), b"Hello");
        }

        #[test]
        fn test_decode_odd_nibble() {
            assert_eq!(decode(b"A>").unwrap(), vec![0xA0]);
        }

        #[test]
        fn test_decode_empty() {
            assert!(decode(b">").unwrap().is_empty());
        }

        #[test]
        fn test_decode_no_eod_marker() {
            assert_eq!(decode(b"4865").unwrap(), b"He");
        }

        #[test]
        fn test_decode_invalid_char() {
            assert!(decode(b"4G>").is_err());
        }

        #[test]
        fn test_decode_all_zeros() {
            assert_eq!(decode(b"0000>").unwrap(), vec![0, 0]);
        }

        #[test]
        fn test_decode_all_ff() {
            assert_eq!(decode(b"FFFF>").unwrap(), vec![0xFF, 0xFF]);
        }

        // ---------------------------------------------------------------
        // Tests ported from upstream fpdf_parser_decode_unittest.cpp
        // ---------------------------------------------------------------

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — empty src string
        #[test]
        fn test_parser_hex_decode_empty() {
            assert!(decode(b"").unwrap().is_empty());
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — empty content with EOD
        #[test]
        fn test_parser_hex_decode_empty_content() {
            assert!(decode(b">").unwrap().is_empty());
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — only whitespace
        #[test]
        fn test_parser_hex_decode_only_whitespace() {
            assert!(decode(b"\t   \r\n>").unwrap().is_empty());
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — regular conversion
        #[test]
        fn test_parser_hex_decode_regular() {
            assert_eq!(decode(b"12Ac>zzz").unwrap(), vec![0x12, 0xAC]);
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — skip whitespace
        #[test]
        fn test_parser_hex_decode_skip_whitespace() {
            assert_eq!(
                decode(b"12 Ac\t02\r\nBF>zzz>").unwrap(),
                vec![0x12, 0xAC, 0x02, 0xBF]
            );
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — non-multiple length
        #[test]
        fn test_parser_hex_decode_non_multiple() {
            assert_eq!(decode(b"12A>zzz").unwrap(), vec![0x12, 0xA0]);
        }

        /// Upstream: TEST(ParserDecodeTest, HexDecode) — no ending mark
        #[test]
        fn test_parser_hex_decode_no_ending_mark() {
            assert_eq!(
                decode(b"12AcED3c3456").unwrap(),
                vec![0x12, 0xAC, 0xED, 0x3C, 0x34, 0x56]
            );
        }
    }
}

// ---------------------------------------------------------------------------
// run_length
// ---------------------------------------------------------------------------

pub mod run_length {
    //! RunLengthDecode / RunLengthEncode filter and scanline decoder.
    //!
    //! Mirrors PDFium's `BasicModule::RunLengthEncode()`,
    //! `BasicModule::CreateRunLengthDecoder()`, and the internal
    //! `RLScanlineDecoder`.

    use crate::error::DecodeError;
    use crate::scanline::ScanlineDecoder;

    // -----------------------------------------------------------------------
    // Batch decode
    // -----------------------------------------------------------------------

    /// Decode run-length encoded data.
    ///
    /// - Length byte 0–127: copy the next `length + 1` bytes literally.
    /// - Length byte 129–255: repeat the next byte `257 - length` times.
    /// - Length byte 128: end of data (EOD).
    pub fn decode(input: &[u8]) -> Result<Vec<u8>, DecodeError> {
        let mut output = Vec::new();
        let mut i = 0;

        while i < input.len() {
            let length = input[i];
            i += 1;

            if length == 128 {
                break; // EOD
            }

            if length <= 127 {
                let count = usize::from(length) + 1;
                if i + count > input.len() {
                    return Err(DecodeError::InvalidInput(
                        "RunLength: literal run extends past end of input".into(),
                    ));
                }
                output.extend_from_slice(&input[i..i + count]);
                i += count;
            } else {
                if i >= input.len() {
                    return Err(DecodeError::InvalidInput(
                        "RunLength: repeat run missing data byte".into(),
                    ));
                }
                let count = 257 - usize::from(length);
                let byte = input[i];
                i += 1;
                output.resize(output.len() + count, byte);
            }
        }

        Ok(output)
    }

    // -----------------------------------------------------------------------
    // Encode
    // -----------------------------------------------------------------------

    /// Encode data using run-length encoding.
    ///
    /// - Matched runs of 2–128 identical bytes → `[257 - run_len, byte]`.
    /// - Mismatched runs of 1–128 distinct bytes → `[run_len - 1, b0, b1, ...]`.
    /// - Terminated with the EOD marker `128`.
    ///
    /// Mirrors PDFium's `BasicModule::RunLengthEncode()`.
    pub fn encode(input: &[u8]) -> Vec<u8> {
        if input.is_empty() {
            return vec![];
        }
        if input.len() == 1 {
            return vec![0, input[0], 128];
        }

        // Worst case: 4 output bytes per 3 input (plus terminator).
        let estimated = input.len().div_ceil(3) * 4 + 1;
        let mut result = vec![0u8; estimated];
        let mut wpos = 0usize;

        let mut run_start = 0usize;
        let mut run_end = 1usize;
        let mut x = input[run_start];
        let mut y = input[run_end];

        while run_end < input.len() {
            let max_len = 128usize.min(input.len() - run_start);

            while x == y && run_end - run_start < max_len - 1 {
                run_end += 1;
                y = input[run_end];
            }

            if x == y {
                run_end += 1;
                if run_end < input.len() {
                    y = input[run_end];
                }
            }

            if run_end - run_start > 1 {
                result[wpos] = (257 - (run_end - run_start)) as u8;
                result[wpos + 1] = x;
                wpos += 2;
                x = y;
                run_start = run_end;
                run_end += 1;
                if run_end < input.len() {
                    y = input[run_end];
                }
                continue;
            }

            while x != y && run_end <= run_start + max_len {
                result[wpos + (run_end - run_start)] = x;
                x = y;
                run_end += 1;
                if run_end == input.len() {
                    if run_end <= run_start + max_len {
                        result[wpos + (run_end - run_start)] = x;
                        run_end += 1;
                    }
                    break;
                }
                y = input[run_end];
            }
            result[wpos] = (run_end - run_start - 2) as u8;
            wpos += run_end - run_start;
            run_start = run_end - 1;
        }

        if run_start < input.len() {
            result[wpos] = 0;
            result[wpos + 1] = x;
            wpos += 2;
        }

        result[wpos] = 128; // EOD
        result.truncate(wpos + 1);
        result
    }

    // -----------------------------------------------------------------------
    // ScanlineDecoder (RLScanlineDecoder port)
    // -----------------------------------------------------------------------

    /// State of the current run-length operator between scanlines.
    #[derive(Clone, Copy)]
    enum RunOp {
        Literal { remaining: usize },
        Repeat { remaining: usize, byte: u8 },
        Eod,
        Init,
    }

    /// Scanline-based RunLength decoder.
    ///
    /// Yields one decoded scanline at a time, maintaining run-length state
    /// across scanline boundaries. Mirrors PDFium's `RLScanlineDecoder`.
    ///
    /// Construct via [`create_decoder`].
    pub struct RunLengthScanlineDecoder {
        src: Vec<u8>,
        width: u32,
        height: u32,
        comps: u8,
        bpc: u8,
        row_stride: usize,
        scanline: Vec<u8>,
        src_offset: usize,
        op: RunOp,
        lines_decoded: usize,
    }

    /// Create a scanline decoder for RunLength-encoded image data.
    ///
    /// Validates that `src` contains enough bytes to decode `width × height`
    /// pixels, then returns a decoder ready to yield one scanline per call.
    ///
    /// Mirrors PDFium's `BasicModule::CreateRunLengthDecoder()`.
    pub fn create_decoder(
        src: &[u8],
        width: u32,
        height: u32,
        comps: u8,
        bpc: u8,
    ) -> Result<RunLengthScanlineDecoder, DecodeError> {
        let row_stride = (width as usize * comps as usize * bpc as usize).div_ceil(8);
        let decoder = RunLengthScanlineDecoder {
            src: src.to_vec(),
            width,
            height,
            comps,
            bpc,
            row_stride,
            scanline: vec![0u8; row_stride],
            src_offset: 0,
            op: RunOp::Init,
            lines_decoded: 0,
        };
        if !decoder.check_dest_size() {
            return Err(DecodeError::InvalidInput(
                "RunLength: compressed data too small for image dimensions".into(),
            ));
        }
        Ok(decoder)
    }

    impl RunLengthScanlineDecoder {
        /// Pre-validate that `src` decodes to at least the required number of
        /// bytes. Mirrors `RLScanlineDecoder::CheckDestSize()`.
        fn check_dest_size(&self) -> bool {
            let mut i = 0usize;
            let mut dest: u64 = 0;
            while i < self.src.len() {
                let b = self.src[i];
                if b < 128 {
                    dest += b as u64 + 1;
                    i += b as usize + 2;
                } else if b > 128 {
                    dest += 257 - b as u64;
                    i += 2;
                } else {
                    break; // EOD
                }
            }
            let required =
                self.width as u64 * self.comps as u64 * self.bpc as u64 * self.height as u64;
            dest * 8 >= required
        }

        fn read_next_op(&mut self) {
            if self.src_offset >= self.src.len() {
                self.op = RunOp::Eod;
                return;
            }
            let b = self.src[self.src_offset];
            self.src_offset += 1;
            self.op = if b < 128 {
                RunOp::Literal {
                    remaining: b as usize + 1,
                }
            } else if b > 128 {
                let data_byte = if self.src_offset < self.src.len() {
                    self.src[self.src_offset]
                } else {
                    0
                };
                RunOp::Repeat {
                    remaining: 257 - b as usize,
                    byte: data_byte,
                }
            } else {
                RunOp::Eod
            };
        }

        /// Mirrors `RLScanlineDecoder::GetNextLine()`.
        fn fill_scanline(&mut self) -> bool {
            if matches!(self.op, RunOp::Init) {
                self.read_next_op();
            }
            if matches!(self.op, RunOp::Eod) {
                return false;
            }

            self.scanline.fill(0);
            let mut col = 0usize;

            loop {
                let space = self.row_stride - col;
                if space == 0 {
                    break;
                }

                match self.op {
                    RunOp::Literal { remaining } => {
                        let src_left = self.src.len().saturating_sub(self.src_offset);
                        let copy = remaining.min(space).min(src_left);
                        let src_end = self.src_offset + copy;
                        self.scanline[col..col + copy]
                            .copy_from_slice(&self.src[self.src_offset..src_end]);
                        col += copy;
                        self.src_offset += copy;
                        let new_remaining = remaining - copy;
                        if new_remaining == 0 {
                            self.read_next_op();
                        } else {
                            self.op = RunOp::Literal {
                                remaining: new_remaining,
                            };
                            break;
                        }
                    }
                    RunOp::Repeat { remaining, byte } => {
                        let copy = remaining.min(space);
                        self.scanline[col..col + copy].fill(byte);
                        col += copy;
                        let new_remaining = remaining - copy;
                        if new_remaining == 0 {
                            self.src_offset += 1;
                            self.read_next_op();
                        } else {
                            self.op = RunOp::Repeat {
                                remaining: new_remaining,
                                byte,
                            };
                            break;
                        }
                    }
                    RunOp::Eod | RunOp::Init => break,
                }

                if matches!(self.op, RunOp::Eod) {
                    break;
                }
            }

            true
        }
    }

    impl ScanlineDecoder for RunLengthScanlineDecoder {
        fn width(&self) -> u32 {
            self.width
        }
        fn height(&self) -> u32 {
            self.height
        }
        fn comps_count(&self) -> u8 {
            self.comps
        }
        fn bpc(&self) -> u8 {
            self.bpc
        }
        fn row_stride(&self) -> usize {
            self.row_stride
        }

        fn decode_scanline(&mut self) -> Result<Option<&[u8]>, DecodeError> {
            if self.lines_decoded >= self.height as usize {
                return Ok(None);
            }
            if !self.fill_scanline() {
                return Ok(None);
            }
            self.lines_decoded += 1;
            Ok(Some(&self.scanline))
        }

        fn reset(&mut self) -> Result<(), DecodeError> {
            self.scanline.fill(0);
            self.src_offset = 0;
            self.op = RunOp::Init;
            self.lines_decoded = 0;
            Ok(())
        }

        fn current_line(&self) -> Option<usize> {
            if self.lines_decoded == 0 {
                None
            } else {
                Some(self.lines_decoded - 1)
            }
        }
    }

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

        // --- decode ---

        #[test]
        fn test_decode_literal_run() {
            assert_eq!(decode(&[2, b'A', b'B', b'C', 128]).unwrap(), b"ABC");
        }

        #[test]
        fn test_decode_repeat_run() {
            assert_eq!(decode(&[253, b'X', 128]).unwrap(), b"XXXX");
        }

        #[test]
        fn test_decode_mixed_runs() {
            assert_eq!(decode(&[1, b'A', b'B', 254, b'Z', 128]).unwrap(), b"ABZZZ");
        }

        #[test]
        fn test_decode_eod_marker() {
            assert!(decode(&[128]).unwrap().is_empty());
        }

        #[test]
        fn test_decode_empty_input() {
            assert!(decode(&[]).unwrap().is_empty());
        }

        #[test]
        fn test_decode_truncated_literal() {
            assert!(decode(&[1, b'A']).is_err());
        }

        #[test]
        fn test_decode_truncated_repeat() {
            assert!(decode(&[255]).is_err());
        }

        #[test]
        fn test_decode_single_literal() {
            assert_eq!(decode(&[0, b'Q', 128]).unwrap(), b"Q");
        }

        #[test]
        fn test_decode_max_repeat() {
            let result = decode(&[129, b'Y', 128]).unwrap();
            assert_eq!(result.len(), 128);
            assert!(result.iter().all(|&b| b == b'Y'));
        }

        // --- encode ---

        #[test]
        fn test_encode_empty() {
            assert!(encode(&[]).is_empty());
        }

        #[test]
        fn test_encode_single_byte() {
            assert_eq!(encode(&[b'A']), &[0, b'A', 128]);
        }

        #[test]
        fn test_encode_eod_terminator() {
            assert_eq!(*encode(b"Hello").last().unwrap(), 128);
        }

        #[test]
        fn test_encode_decode_roundtrip_literal() {
            let original = b"ABCDEFGH";
            assert_eq!(decode(&encode(original)).unwrap(), original);
        }

        #[test]
        fn test_encode_decode_roundtrip_repeated() {
            let original = vec![b'X'; 64];
            let encoded = encode(&original);
            assert!(encoded.len() < original.len());
            assert_eq!(decode(&encoded).unwrap(), original);
        }

        #[test]
        fn test_encode_decode_roundtrip_all_bytes() {
            let original: Vec<u8> = (0u8..=255).collect();
            assert_eq!(decode(&encode(&original)).unwrap(), original);
        }

        #[test]
        fn test_encode_max_repeat_128() {
            let original = vec![b'Z'; 128];
            assert_eq!(decode(&encode(&original)).unwrap(), original);
        }

        // --- RunLengthScanlineDecoder ---

        fn make_rl_image(rows: &[&[u8]]) -> Vec<u8> {
            let mut encoded = Vec::new();
            for row in rows {
                for chunk in row.chunks(128) {
                    encoded.push((chunk.len() - 1) as u8);
                    encoded.extend_from_slice(chunk);
                }
            }
            encoded.push(128);
            encoded
        }

        #[test]
        fn test_rl_scanline_basic() {
            let src = make_rl_image(&[&[1u8, 2, 3], &[4u8, 5, 6]]);
            let mut dec = create_decoder(&src, 3, 2, 1, 8).unwrap();

            assert_eq!(dec.width(), 3);
            assert_eq!(dec.height(), 2);
            assert_eq!(dec.comps_count(), 1);
            assert_eq!(dec.bpc(), 8);
            assert_eq!(dec.row_stride(), 3);

            assert_eq!(dec.decode_scanline().unwrap().unwrap(), &[1, 2, 3]);
            assert_eq!(dec.current_line(), Some(0));
            assert_eq!(dec.decode_scanline().unwrap().unwrap(), &[4, 5, 6]);
            assert_eq!(dec.current_line(), Some(1));
            assert!(dec.decode_scanline().unwrap().is_none());
        }

        #[test]
        fn test_rl_scanline_repeat_run() {
            let src = [253u8, b'A', 128];
            let mut dec = create_decoder(&src, 4, 1, 1, 8).unwrap();
            assert_eq!(
                dec.decode_scanline().unwrap().unwrap(),
                &[b'A', b'A', b'A', b'A']
            );
            assert!(dec.decode_scanline().unwrap().is_none());
        }

        #[test]
        fn test_rl_scanline_reset() {
            let src = make_rl_image(&[&[1u8, 2, 3, 4], &[1u8, 2, 3, 4]]);
            let mut dec = create_decoder(&src, 4, 2, 1, 8).unwrap();
            let first = dec.decode_scanline().unwrap().unwrap().to_vec();
            dec.reset().unwrap();
            assert_eq!(dec.current_line(), None);
            assert_eq!(dec.decode_scanline().unwrap().unwrap(), first);
        }

        #[test]
        fn test_rl_scanline_current_line_before_read() {
            let src = make_rl_image(&[&[0u8, 0, 0]]);
            assert_eq!(
                create_decoder(&src, 3, 1, 1, 8).unwrap().current_line(),
                None
            );
        }

        #[test]
        fn test_rl_scanline_too_small_returns_error() {
            let src = [0u8, 42, 128];
            assert!(create_decoder(&src, 2, 2, 1, 8).is_err());
        }

        #[test]
        fn test_rl_scanline_run_spanning_rows() {
            let src = [251u8, b'X', 128]; // 257-251=6 × 'X', 3 bytes/row
            let mut dec = create_decoder(&src, 3, 2, 1, 8).unwrap();
            assert_eq!(dec.decode_scanline().unwrap().unwrap(), &[b'X', b'X', b'X']);
            assert_eq!(dec.decode_scanline().unwrap().unwrap(), &[b'X', b'X', b'X']);
            assert!(dec.decode_scanline().unwrap().is_none());
        }
    }
}