feat(pdf-filter): implement LZWDecode filter with predictor support

Add LZW decompression (PDF spec §7.4.4) and shared Predictor
post-processing (§7.4.4.4) to the pdf-filter crate.

New modules:
- lzw.rs: Pure-Rust LZW decoder with EarlyChange parameter support,
  variable-width codes (9-12 bits), MSB-first bit packing.
- predictor.rs: TIFF Predictor 2 (horizontal differencing) and PNG
  predictors (None/Sub/Up/Average/Paeth). Shared by LZWDecode and
  FlateDecode.

Changes:
- bitreader.rs: Add read_bits(n) for variable-width code extraction.
- filter.rs: Add LZWDecode variant, Lzw/Flate DecodeParms, wire into
  decode pipeline. Also wire predictor support into FlateDecode.
- lib.rs: Register new modules, update crate documentation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Velli20

crates/pdf-filter/src/bitreader.rs

@@ -41,6 +41,26 @@ impl<'a> BitReader<'a> {
         }
     }
 
+    /// Read `n` bits MSB-first and return them as a `u16`.
+    ///
+    /// Returns `None` if there are fewer than `n` bits remaining. `n` must be
+    /// at most 16.
+    #[allow(clippy::arithmetic_side_effects)]
+    pub fn read_bits(&mut self, n: u8) -> Option<u16> {
+        let total_bits = self.src.len().saturating_mul(8);
+        if self.bit_pos.saturating_add(usize::from(n)) > total_bits {
+            return None;
+        }
+        let mut value: u16 = 0;
+        for _ in 0..n {
+            value <<= 1;
+            if self.next_bit()? {
+                value |= 1;
+            }
+        }
+        Some(value)
+    }
+
     /// Advance to the next byte boundary, but only if all padding bits are 0.
     /// Returns `true` if alignment happened, `false` if a non-zero pad bit was
     /// found (the caller should disable byte-alignment for remaining rows).
@@ -83,4 +103,41 @@ mod tests {
         r.skip_bits(100); // should not panic
         assert!(r.exhausted());
     }
+
+    #[test]
+    fn read_bits_returns_msb_first_value() {
+        // 0b1010_0110 = 0xA6
+        let data = [0xA6u8];
+        let mut r = BitReader::new(&data);
+        // Read 4 bits: 1010 = 10
+        assert_eq!(r.read_bits(4), Some(0b1010));
+        // Read 4 bits: 0110 = 6
+        assert_eq!(r.read_bits(4), Some(0b0110));
+    }
+
+    #[test]
+    fn read_bits_across_byte_boundary() {
+        let data = [0b1111_0000u8, 0b1010_1010u8];
+        let mut r = BitReader::new(&data);
+        r.skip_bits(4);
+        // Read 8 bits spanning bytes: 0000_1010 = 0x0A
+        assert_eq!(r.read_bits(8), Some(0b0000_1010));
+    }
+
+    #[test]
+    fn read_bits_returns_none_when_exhausted() {
+        let data = [0xFFu8];
+        let mut r = BitReader::new(&data);
+        assert_eq!(r.read_bits(9), None);
+    }
+
+    #[test]
+    fn read_bits_9_bit_code() {
+        // Two bytes: 0b1_0000_0001 0xxxxxxx
+        // Code 0x101 = 257 in 9 bits MSB-first
+        // Byte 0: 1000_0000  Byte 1: 1xxxxxxx
+        let data = [0b1000_0000u8, 0b1000_0000u8];
+        let mut r = BitReader::new(&data);
+        assert_eq!(r.read_bits(9), Some(0b1_0000_0001)); // 257
+    }
 }

crates/pdf-filter/src/filter.rs

@@ -1,7 +1,7 @@
 use std::borrow::Cow;
 use std::fmt;
 
-use crate::{ccitt_fax_params::CCITTFaxParams, error::FilterError};
+use crate::{ccitt_fax_params::CCITTFaxParams, error::FilterError, predictor::PredictorParams};
 
 use pdf_object::{
     dictionary::Dictionary,
@@ -43,6 +43,11 @@ pub enum Filter {
     /// bytes. The special character `z` represents four zero bytes. The
     /// end-of-data marker is `~>`.
     ASCII85Decode,
+    /// The LZW (Lempel-Ziv-Welch) filter, a lossless compression algorithm.
+    ///
+    /// Based on variable-length code substitution. This was used in older PDFs
+    /// before FlateDecode became the standard. See PDF spec §7.4.4.
+    LZWDecode,
     /// A filter that is not currently supported by this implementation.
     ///
     /// The contained string holds the original filter name from the PDF,
@@ -58,6 +63,7 @@ impl From<Cow<'_, str>> for Filter {
             "JPXDecode" => Self::JPXDecode,
             "CCITTFaxDecode" => Self::CCITTFaxDecode,
             "ASCII85Decode" => Self::ASCII85Decode,
+            "LZWDecode" => Self::LZWDecode,
             _ => Self::Unsupported(name.into_owned()),
         }
     }
@@ -77,6 +83,7 @@ impl fmt::Display for Filter {
             Self::FlateDecode => f.write_str("FlateDecode"),
             Self::CCITTFaxDecode => f.write_str("CCITTFaxDecode"),
             Self::ASCII85Decode => f.write_str("ASCII85Decode"),
+            Self::LZWDecode => f.write_str("LZWDecode"),
             Self::Unsupported(name) => f.write_str(name),
         }
     }
@@ -92,6 +99,13 @@ pub(crate) enum DecodeParms {
     None,
     /// Parameters for the `CCITTFaxDecode` filter.
     CcittFax(CCITTFaxParams),
+    /// Parameters for `LZWDecode`: EarlyChange flag + optional predictor.
+    Lzw {
+        early_change: bool,
+        predictor: PredictorParams,
+    },
+    /// Predictor parameters for `FlateDecode`.
+    Flate { predictor: PredictorParams },
 }
 
 /// Methods for parsing the `/Filter` entry from a PDF dictionary.
@@ -229,6 +243,27 @@ pub fn decode(stream: &StreamObject) -> Result<Cow<'_, [u8]>, FilterError> {
         match filter {
             Filter::FlateDecode => {
                 let decoded = Filter::decode_flate(&data)?;
+                let decoded = match params {
+                    DecodeParms::Flate { predictor } if !predictor.is_none() => {
+                        crate::predictor::apply_predictor(&decoded, predictor)?
+                    }
+                    _ => decoded,
+                };
+                data = Cow::Owned(decoded);
+            }
+            Filter::LZWDecode => {
+                let (early_change, predictor) = match params {
+                    DecodeParms::Lzw {
+                        early_change,
+                        predictor,
+                    } => (*early_change, Some(predictor)),
+                    _ => (true, None),
+                };
+                let decoded = crate::lzw::decode(&data, early_change)?;
+                let decoded = match predictor {
+                    Some(p) if !p.is_none() => crate::predictor::apply_predictor(&decoded, p)?,
+                    _ => decoded,
+                };
                 data = Cow::Owned(decoded);
             }
             Filter::JPXDecode => {
@@ -246,7 +281,7 @@ pub fn decode(stream: &StreamObject) -> Result<Cow<'_, [u8]>, FilterError> {
             Filter::CCITTFaxDecode => {
                 let ccitt_params = match params {
                     DecodeParms::CcittFax(p) => p,
-                    DecodeParms::None => &CCITTFaxParams::DEFAULT,
+                    _ => &CCITTFaxParams::DEFAULT,
                 };
                 let decoded = crate::ccitt::decode(&data, ccitt_params)?;
                 data = Cow::Owned(decoded);
@@ -302,6 +337,29 @@ fn parse_decode_params(
                 DecodeParms::CcittFax(p)
             }
             (Filter::CCITTFaxDecode, None) => DecodeParms::CcittFax(CCITTFaxParams::default()),
+            (Filter::LZWDecode, Some(d)) => {
+                let early_change = d
+                    .get("EarlyChange")
+                    .and_then(|v| v.try_number::<i64>(objects).ok())
+                    .unwrap_or(1)
+                    != 0;
+                let predictor = PredictorParams::from_dictionary(d, objects).unwrap_or_default();
+                DecodeParms::Lzw {
+                    early_change,
+                    predictor,
+                }
+            }
+            (Filter::LZWDecode, None) => DecodeParms::Lzw {
+                early_change: true,
+                predictor: PredictorParams::default(),
+            },
+            (Filter::FlateDecode, Some(d)) => {
+                let predictor = PredictorParams::from_dictionary(d, objects).unwrap_or_default();
+                DecodeParms::Flate { predictor }
+            }
+            (Filter::FlateDecode, None) => DecodeParms::Flate {
+                predictor: PredictorParams::default(),
+            },
             _ => DecodeParms::None,
         })
         .collect()

crates/pdf-filter/src/lib.rs

@@ -4,6 +4,7 @@
 //! specification (§7.4):
 //!
 //! - **FlateDecode** — zlib/deflate (RFC 1950 / RFC 1951)
+//! - **LZWDecode** — LZW compression (§7.4.4)
 //! - **DCTDecode** — baseline JPEG
 //! - **JPXDecode** — JPEG 2000
 //! - **CCITTFaxDecode** — Group 3 / Group 4 fax compression
@@ -20,3 +21,5 @@ pub(crate) mod ccitt_fax_params;
 mod ccitt_tables;
 pub mod error;
 pub mod filter;
+pub(crate) mod lzw;
+pub(crate) mod predictor;