rpdfium_parser/

store.rs

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

//! ObjectStore — the central data structure for PDF object access.
//!
//! Owns the source data and provides thread-safe lazy parsing of individual
//! objects via `OnceLock`. The `HashMap` key set is immutable after construction.

use std::collections::HashMap;
use std::sync::OnceLock;

use dashmap::DashMap;
use rpdfium_core::error::PdfError;
use rpdfium_core::fx_system::MAX_RECURSION_DEPTH;
use rpdfium_core::{Name, ParsingMode, PdfSource};
use smallvec::SmallVec;

use crate::header::{PdfVersion, parse_header};
use crate::object::{Object, ObjectId, StreamData};
use crate::object_parser::parse_indirect_object;
use crate::security::SecurityHandler;
use crate::trailer::{TrailerInfo, parse_all_xrefs};
use crate::xref::{XrefEntryType, XrefSection, XrefTable};

/// A slot for a single PDF object in the store.
///
/// Each slot independently lazy-initializes its parsed object via `OnceLock`.
/// The `Free` variant is transient — removed after construction.
pub(crate) enum ObjectSlot {
    /// Object at a direct byte offset in the source.
    Direct {
        offset: u64,
        parsed: OnceLock<Result<Object, PdfError>>,
    },
    /// Object inside an object stream (ObjStm).
    InStream {
        stream_id: ObjectId,
        index: u32,
        parsed: OnceLock<Result<Object, PdfError>>,
    },
    /// Transient free entry — removed after `build_slots`.
    Free,
}

/// Maximum number of ObjStm entries to cache. Beyond this, new ObjStms
/// are parsed on every access (no eviction). Typical PDFs have far fewer
/// than 256 ObjStm containers.
const MAX_OBJSTM_CACHE_ENTRIES: usize = 256;

/// The central PDF object store with thread-safe lazy parsing.
///
/// Generic over the source data type via `PdfSource`.
pub struct ObjectStore<S: PdfSource = std::sync::Arc<[u8]>> {
    source: S,
    xref: XrefTable,
    mode: ParsingMode,
    trailer: TrailerInfo,
    version: PdfVersion,
    slots: HashMap<ObjectId, ObjectSlot>,
    security_handler: Option<SecurityHandler>,
    /// Cache of parsed ObjStm contents. Key = ObjStm container's ObjectId,
    /// Value = list of (object_number, parsed_object) pairs from that stream.
    objstm_cache: DashMap<ObjectId, Vec<(u32, Object)>>,
    /// Whether the cross-reference table was rebuilt via linear scan
    /// (Lenient mode fallback).
    xref_rebuilt: bool,
    /// Whether the newest (primary) cross-reference section is an xref stream.
    /// `false` means a traditional `xref` keyword table was used.
    xref_is_stream: bool,
}

impl<S: PdfSource> ObjectStore<S> {
    /// Open a PDF source, parsing the header, xref table, and trailer.
    ///
    /// This constructs the ObjectStore with all object slots ready for
    /// lazy parsing on demand. For encrypted PDFs, use [`Self::open_with_password`].
    pub fn open(source: S, mode: ParsingMode) -> Result<Self, PdfError> {
        Self::open_with_password(source, mode, None)
    }

    /// Open a PDF source, optionally providing a password for encrypted documents.
    ///
    /// After parsing the header, xref, and trailer, if the trailer contains
    /// an `/Encrypt` entry, the encryption dictionary is resolved and a
    /// [`SecurityHandler`] is created. The password is verified against both
    /// user and owner password hashes.
    pub fn open_with_password(
        source: S,
        mode: ParsingMode,
        password: Option<&str>,
    ) -> Result<Self, PdfError> {
        let data = source.as_ref();

        // Parse header
        let (version, _header_end) = parse_header(data, mode)?;

        // Parse all xref sections and trailer
        let mut xref_rebuilt = false;
        let (xref, trailer) = match parse_all_xrefs(data, mode) {
            Ok(result) => result,
            Err(_) if mode == ParsingMode::Lenient => {
                xref_rebuilt = true;
                crate::xref::rebuild_xref(data)?
            }
            Err(e) => return Err(e),
        };

        // Build object slots from xref entries
        let slots = Self::build_slots(&xref.sections);

        // Detect whether the primary (newest) xref is a stream vs. traditional table.
        // A traditional xref starts with the keyword "xref"; anything else is a stream.
        let xref_is_stream = if xref_rebuilt {
            false
        } else {
            let start = xref.start_offset as usize;
            if start < data.len() {
                let mut pos = start;
                while pos < data.len() && matches!(data[pos], b' ' | b'\t' | b'\n' | b'\r' | 0x0C) {
                    pos += 1;
                }
                !(pos + 4 <= data.len() && &data[pos..pos + 4] == b"xref")
            } else {
                false
            }
        };

        let mut store = Self {
            source,
            xref,
            mode,
            trailer,
            version,
            slots,
            security_handler: None,
            objstm_cache: DashMap::new(),
            xref_rebuilt,
            xref_is_stream,
        };

        // Check for encryption and initialize SecurityHandler
        if let Some(encrypt_id) = store.trailer.encrypt {
            let encrypt_dict = store
                .resolve(encrypt_id)?
                .as_dict()
                .ok_or(PdfError::InvalidObject(
                    "encryption dictionary is not a dict".into(),
                ))?
                .clone();

            let file_id = store
                .trailer
                .id
                .as_ref()
                .map(|ids| ids[0].as_slice())
                .unwrap_or(&[]);

            let pwd = password.unwrap_or("");

            let handler = SecurityHandler::from_encrypt_dict(&encrypt_dict, &store, pwd, file_id)
                .map_err(|e| match e {
                crate::security::SecurityError::InvalidPassword => PdfError::InvalidPassword,
                crate::security::SecurityError::UnsupportedVersion(_, _) => {
                    PdfError::UnsupportedEncryption
                }
                _ => PdfError::InvalidObject(e.to_string()),
            })?;

            store.security_handler = Some(handler);
        }

        Ok(store)
    }

    /// Build the object slot map from xref sections.
    ///
    /// Sections are ordered newest-first. Uses `or_insert` semantics so
    /// newer entries win for the same ObjectId. Free entries are inserted
    /// as placeholders, then removed after all sections are processed.
    fn build_slots(xref_sections: &[XrefSection]) -> HashMap<ObjectId, ObjectSlot> {
        let mut slots = HashMap::new();

        // xref_sections[0] is newest, xref_sections[last] is oldest
        for section in xref_sections {
            for entry in &section.entries {
                match &entry.entry_type {
                    XrefEntryType::InUse { offset } => {
                        slots.entry(entry.id).or_insert(ObjectSlot::Direct {
                            offset: *offset,
                            parsed: OnceLock::new(),
                        });
                    }
                    XrefEntryType::InStream { stream_id, index } => {
                        slots.entry(entry.id).or_insert(ObjectSlot::InStream {
                            stream_id: *stream_id,
                            index: *index,
                            parsed: OnceLock::new(),
                        });
                    }
                    XrefEntryType::Free => {
                        slots.entry(entry.id).or_insert(ObjectSlot::Free);
                    }
                }
            }
        }

        // Remove Free entries — they represent deleted objects
        slots.retain(|_, slot| !matches!(slot, ObjectSlot::Free));
        slots
    }

    /// Resolve an indirect object by its ID. Returns a reference to the
    /// lazily-parsed object.
    pub fn resolve(&self, id: ObjectId) -> Result<&Object, PdfError> {
        let slot = self.slots.get(&id).ok_or(PdfError::UnknownObject(id))?;

        let result = match slot {
            ObjectSlot::Direct { offset, parsed } => parsed.get_or_init(|| {
                let data = self.source.as_ref();
                match parse_indirect_object(data, *offset, self.mode) {
                    Ok((_id, obj)) => Ok(obj),
                    Err(e) => Err(e),
                }
            }),
            ObjectSlot::InStream {
                stream_id,
                index,
                parsed,
            } => parsed.get_or_init(|| self.parse_from_objstm(*stream_id, *index)),
            ObjectSlot::Free => {
                // Should never happen after construction
                return Err(PdfError::UnknownObject(id));
            }
        };

        match result {
            Ok(obj) => Ok(obj),
            Err(e) if self.mode == ParsingMode::Lenient => {
                tracing::warn!(?id, error = ?e, "parse failed, returning Null");
                // Return a static Null for lenient mode.
                // We use a const instead of static because Object doesn't impl Sync
                // (it contains HashMap). The const is promoted to a static by the compiler.
                const NULL_OBJ: Object = Object::Null;
                Ok(&NULL_OBJ)
            }
            Err(_e) => Err(PdfError::UnknownObject(id)),
        }
    }

    /// Follow a reference chain to the concrete object.
    ///
    /// Uses an iterative loop with circular reference detection
    /// via `SmallVec`. Never recurses on the call stack.
    pub fn deep_resolve<'a>(&'a self, obj: &'a Object) -> Result<&'a Object, PdfError> {
        let mut current = obj;
        let mut seen = SmallVec::<[ObjectId; 8]>::new();

        while let Object::Reference(id) = current {
            if seen.len() >= MAX_RECURSION_DEPTH as usize {
                return Err(PdfError::RecursionLimitExceeded);
            }
            if seen.contains(id) {
                return Err(PdfError::CircularReference(*id));
            }
            seen.push(*id);
            current = self.resolve(*id)?;
        }

        Ok(current)
    }

    /// Resolve a dictionary value by key, following references.
    pub fn dict_resolve<'a>(
        &'a self,
        dict: &'a HashMap<Name, Object>,
        key: &Name,
    ) -> Result<Option<&'a Object>, PdfError> {
        match dict.get(key) {
            Some(obj) => Ok(Some(self.deep_resolve(obj)?)),
            None => Ok(None),
        }
    }

    /// Decode stream data on demand using the filter chain from the stream dictionary.
    ///
    /// Resolves `/Filter` and `/DecodeParms` from the stream dictionary,
    /// then applies the codec pipeline via [`rpdfium_codec::apply_filter_chain`].
    pub fn decode_stream(&self, stream: &Object) -> Result<Vec<u8>, PdfError> {
        let (dict, data) = match stream {
            Object::Stream { dict, data } => (dict, data),
            _ => return Err(PdfError::NotAStream),
        };

        match data {
            StreamData::Raw { offset, length } => {
                let source = self.source.as_ref();
                let start = *offset as usize;
                let end = start
                    .checked_add(*length as usize)
                    .ok_or(PdfError::StreamTooLarge)?;
                if end > source.len() {
                    return Err(PdfError::StreamTooLarge);
                }
                let raw = &source[start..end];

                let mut filters = crate::filter::resolve_filter_chain(dict);
                if filters.is_empty() {
                    return Ok(raw.to_vec());
                }

                self.resolve_jbig2_globals(dict, &mut filters);

                rpdfium_codec::apply_filter_chain(raw, &filters)
                    .map_err(|e| PdfError::StreamDecodeError(e.to_string()))
            }
            StreamData::Decoded { data: bytes } => Ok(bytes.clone()),
        }
    }

    /// Parse an object from an object stream (ObjStm).
    ///
    /// Uses a per-ObjStm cache: on the first access to any object in a given
    /// ObjStm, all objects from that stream are parsed and cached. Subsequent
    /// accesses to objects in the same ObjStm are served from the cache.
    fn parse_from_objstm(&self, stream_id: ObjectId, index: u32) -> Result<Object, PdfError> {
        // Check the cache first
        if let Some(cached) = self.objstm_cache.get(&stream_id) {
            return match cached.get(index as usize) {
                Some((_obj_num, obj)) => Ok(obj.clone()),
                None => Err(PdfError::InvalidObjectStream),
            };
        }

        // Cache miss — parse the entire ObjStm
        let stream_obj = self.resolve(stream_id)?;

        // Decode the stream — use decode_stream_for_object so encrypted
        // object streams are decrypted before decompression.
        let decoded = self.decode_stream_for_object(stream_obj, stream_id)?;

        let dict = match stream_obj {
            Object::Stream { dict, .. } => dict,
            _ => return Err(PdfError::NotAStream),
        };

        // Parse the object stream contents from decoded data
        let contents = crate::object_stream::parse_object_stream(&decoded, dict, self.mode)?;

        // Store in cache if below the size limit
        if self.objstm_cache.len() < MAX_OBJSTM_CACHE_ENTRIES {
            let result = contents
                .objects
                .get(index as usize)
                .map(|(_obj_num, obj)| obj.clone())
                .ok_or(PdfError::InvalidObjectStream);

            self.objstm_cache.insert(stream_id, contents.objects);

            result
        } else {
            // Cache full — serve directly without caching
            match crate::object_stream::get_object_from_stream(&contents, index) {
                Some(obj) => Ok(obj.clone()),
                None => Err(PdfError::InvalidObjectStream),
            }
        }
    }

    /// Get the parsing mode.
    pub fn parsing_mode(&self) -> ParsingMode {
        self.mode
    }

    /// Get the trailer info.
    pub fn trailer(&self) -> &TrailerInfo {
        &self.trailer
    }

    /// ADR-019 alias for [`trailer()`](Self::trailer).
    ///
    /// Corresponds to `CPDF_Parser::GetTrailer()` in PDFium.
    #[inline]
    pub fn get_trailer(&self) -> &TrailerInfo {
        self.trailer()
    }

    /// Get the PDF version from the header.
    ///
    /// Corresponds to `CPDF_Parser::GetFileVersion()` in PDFium.
    pub fn file_version(&self) -> PdfVersion {
        self.version
    }

    /// ADR-019 alias for [`file_version()`](Self::file_version).
    ///
    /// Corresponds to `CPDF_Parser::GetFileVersion()` in PDFium.
    #[inline]
    pub fn get_file_version(&self) -> PdfVersion {
        self.file_version()
    }

    /// Rust-idiomatic alias for [`file_version()`](Self::file_version).
    #[inline]
    #[deprecated(since = "0.0.0", note = "use `file_version()` or `get_file_version()`")]
    pub fn version(&self) -> PdfVersion {
        self.file_version()
    }

    /// Get the cross-reference table.
    pub fn xref(&self) -> &XrefTable {
        &self.xref
    }

    /// Get the number of object slots.
    pub fn object_count(&self) -> usize {
        self.slots.len()
    }

    /// Check if an object ID exists in the store.
    pub fn contains(&self, id: ObjectId) -> bool {
        self.slots.contains_key(&id)
    }

    /// Get all known object IDs.
    pub fn object_ids(&self) -> impl Iterator<Item = &ObjectId> {
        self.slots.keys()
    }

    /// Returns a reference to the security handler, if the document is encrypted.
    pub fn security_handler(&self) -> Option<&SecurityHandler> {
        self.security_handler.as_ref()
    }

    /// ADR-019 alias for [`security_handler()`](Self::security_handler).
    ///
    /// Corresponds to `CPDF_Parser::GetSecurityHandler()` in PDFium.
    #[inline]
    pub fn get_security_handler(&self) -> Option<&SecurityHandler> {
        self.security_handler()
    }

    /// Returns the document access permissions, if the document is encrypted.
    ///
    /// Delegates to [`SecurityHandler::permissions()`]. Returns `None` for
    /// unencrypted documents (all permissions implicitly granted).
    ///
    /// Corresponds to `CPDF_Parser::GetPermissions()` in PDFium.
    pub fn permissions(&self) -> Option<crate::security::Permissions> {
        self.security_handler.as_ref().map(|h| h.permissions())
    }

    /// ADR-019 alias for [`permissions()`](Self::permissions).
    ///
    /// Corresponds to `CPDF_Parser::GetPermissions()` in PDFium.
    #[inline]
    pub fn get_permissions(&self) -> Option<crate::security::Permissions> {
        self.permissions()
    }

    /// Returns the encoded password bytes used during authentication, if the
    /// document is encrypted.
    ///
    /// Delegates to [`SecurityHandler::encoded_password()`]. Returns `None` for
    /// unencrypted documents.
    ///
    /// Corresponds to `CPDF_Parser::GetEncodedPassword()` in PDFium.
    pub fn encoded_password(&self) -> Option<&[u8]> {
        self.security_handler.as_ref().map(|h| h.encoded_password())
    }

    /// ADR-019 alias for [`encoded_password()`](Self::encoded_password).
    ///
    /// Corresponds to `CPDF_Parser::GetEncodedPassword()` in PDFium.
    #[inline]
    pub fn get_encoded_password(&self) -> Option<&[u8]> {
        self.encoded_password()
    }

    /// Returns true if the cross-reference table was rebuilt (Lenient mode recovery).
    ///
    /// When `true`, the original xref table could not be parsed and the parser
    /// fell back to a linear scan for `N G obj` markers.
    ///
    /// Corresponds to `CPDF_Parser::IsXRefTableRebuilt()` in PDFium.
    pub fn xref_table_rebuilt(&self) -> bool {
        self.xref_rebuilt
    }

    /// ADR-019 alias for [`xref_table_rebuilt()`](Self::xref_table_rebuilt).
    ///
    /// Corresponds to `CPDF_Parser::IsXRefTableRebuilt()` in PDFium.
    #[inline]
    pub fn is_xref_table_rebuilt(&self) -> bool {
        self.xref_table_rebuilt()
    }

    /// Abbreviated alias for [`xref_table_rebuilt()`](Self::xref_table_rebuilt).
    #[inline]
    #[deprecated(
        since = "0.0.0",
        note = "use `xref_table_rebuilt()` or `is_xref_table_rebuilt()`"
    )]
    pub fn xref_rebuilt(&self) -> bool {
        self.xref_table_rebuilt()
    }

    /// Returns `true` if the newest cross-reference section is an xref stream
    /// (PDF 1.5+ compressed xref), `false` if it is a traditional `xref` table.
    ///
    /// Corresponds to `CPDF_Parser::IsXRefStream()` in PDFium.
    pub fn is_xref_stream(&self) -> bool {
        self.xref_is_stream
    }

    /// Returns the byte offset of the given object in the source data, if the
    /// object is a direct (non-stream) object. Returns `None` for objects
    /// embedded in object streams (ObjStm).
    ///
    /// Corresponds to `CPDF_Parser::GetObjectPositionOrZero()` in PDFium.
    pub fn object_position_or_zero(&self, id: ObjectId) -> Option<u64> {
        match self.slots.get(&id)? {
            ObjectSlot::Direct { offset, .. } => Some(*offset),
            ObjectSlot::InStream { .. } | ObjectSlot::Free => None,
        }
    }

    /// ADR-019 alias for [`object_position_or_zero()`](Self::object_position_or_zero).
    ///
    /// Corresponds to `CPDF_Parser::GetObjectPositionOrZero()` in PDFium.
    #[inline]
    pub fn get_object_position_or_zero(&self, id: ObjectId) -> Option<u64> {
        self.object_position_or_zero(id)
    }

    /// Rust-idiomatic alias for [`object_position_or_zero()`](Self::object_position_or_zero).
    #[inline]
    #[deprecated(
        since = "0.0.0",
        note = "use `object_position_or_zero()` or `get_object_position_or_zero()`"
    )]
    pub fn object_offset(&self, id: ObjectId) -> Option<u64> {
        self.object_position_or_zero(id)
    }

    /// Returns a reference to the raw source data.
    pub fn source_data(&self) -> &S {
        &self.source
    }

    /// Returns the maximum object number in the store.
    ///
    /// Corresponds to `CPDF_Parser::GetLastObjNum()` in PDFium.
    pub fn last_obj_num(&self) -> u32 {
        self.slots.keys().map(|id| id.number).max().unwrap_or(0)
    }

    /// ADR-019 alias for [`last_obj_num()`](Self::last_obj_num).
    ///
    /// Corresponds to `CPDF_Parser::GetLastObjNum()` in PDFium.
    #[inline]
    pub fn get_last_obj_num(&self) -> u32 {
        self.last_obj_num()
    }

    /// Rust-idiomatic alias for [`last_obj_num()`](Self::last_obj_num).
    #[inline]
    #[deprecated(since = "0.0.0", note = "use `last_obj_num()` or `get_last_obj_num()`")]
    pub fn max_object_number(&self) -> u32 {
        self.last_obj_num()
    }

    /// Returns the byte offset of the last `startxref` value.
    ///
    /// This is needed for incremental saves to set the `/Prev` trailer key.
    ///
    /// Corresponds to `CPDF_Parser::GetLastXRefOffset()` in PDFium.
    pub fn last_xref_offset(&self) -> u64 {
        self.xref.start_offset
    }

    /// Rust-idiomatic alias for [`last_xref_offset()`](Self::last_xref_offset).
    #[inline]
    #[deprecated(
        since = "0.0.0",
        note = "use `last_xref_offset()` or `get_last_xref_offset()`"
    )]
    pub fn xref_start_offset(&self) -> u64 {
        self.last_xref_offset()
    }

    /// Returns `true` if the given object number exists in the cross-reference
    /// table (i.e. is a valid, non-free indirect object).
    ///
    /// Corresponds to `CPDF_Parser::IsValidObjectNumber()` in PDFium.
    pub fn is_valid_object_number(&self, number: u32) -> bool {
        self.contains(ObjectId::new(number, 0)) || self.slots.keys().any(|id| id.number == number)
    }

    /// ADR-019 alias for [`last_xref_offset()`](Self::last_xref_offset).
    ///
    /// Corresponds to `CPDF_Parser::GetLastXRefOffset()` in PDFium.
    #[inline]
    pub fn get_last_xref_offset(&self) -> u64 {
        self.last_xref_offset()
    }

    /// Returns `true` if the given object number is marked free or null (i.e. does not
    /// exist as an in-use object in the store).
    ///
    /// Corresponds to `CPDF_Parser::IsObjectFreeOrNull()` in PDFium.
    pub fn is_object_free(&self, number: u32) -> bool {
        !self.slots.keys().any(|id| id.number == number)
    }

    /// ADR-019 alias for [`is_object_free()`](Self::is_object_free).
    ///
    /// Corresponds to `CPDF_Parser::IsObjectFreeOrNull()` in PDFium.
    #[inline]
    pub fn is_object_free_or_null(&self, number: u32) -> bool {
        self.is_object_free(number)
    }

    /// Returns the total size of the source document in bytes.
    ///
    /// Corresponds to `CPDF_Parser::GetDocumentSize()` in PDFium.
    pub fn document_size(&self) -> usize {
        self.source.as_ref().len()
    }

    /// ADR-019 alias for [`document_size()`](Self::document_size).
    ///
    /// Corresponds to `CPDF_Parser::GetDocumentSize()` in PDFium.
    #[inline]
    pub fn get_document_size(&self) -> usize {
        self.document_size()
    }

    /// Decode stream data for a specific object, applying decryption if needed.
    ///
    /// Like [`Self::decode_stream`], but also decrypts the raw stream data before
    /// applying the filter chain when the document is encrypted.
    pub fn decode_stream_for_object(
        &self,
        stream: &Object,
        obj_id: ObjectId,
    ) -> Result<Vec<u8>, PdfError> {
        let (dict, data) = match stream {
            Object::Stream { dict, data } => (dict, data),
            _ => return Err(PdfError::NotAStream),
        };

        match data {
            StreamData::Raw { offset, length } => {
                let source = self.source.as_ref();
                let start = *offset as usize;
                let end = start
                    .checked_add(*length as usize)
                    .ok_or(PdfError::StreamTooLarge)?;
                if end > source.len() {
                    return Err(PdfError::StreamTooLarge);
                }
                let raw = &source[start..end];

                // Decrypt if we have a security handler
                let decrypted;
                let raw_data = if let Some(handler) = &self.security_handler {
                    decrypted = handler.decrypt_stream(raw, obj_id);
                    &decrypted
                } else {
                    raw
                };

                let mut filters = crate::filter::resolve_filter_chain(dict);
                if filters.is_empty() {
                    return Ok(raw_data.to_vec());
                }

                self.resolve_jbig2_globals(dict, &mut filters);

                rpdfium_codec::apply_filter_chain(raw_data, &filters)
                    .map_err(|e| PdfError::StreamDecodeError(e.to_string()))
            }
            StreamData::Decoded { data: bytes } => Ok(bytes.clone()),
        }
    }

    /// Return the raw (optionally decrypted) stream bytes without applying any
    /// filter chain. This is useful when the caller needs to handle a specific
    /// filter (like JPXDecode) specially to extract metadata.
    pub fn raw_stream_bytes_for_object(
        &self,
        stream: &Object,
        obj_id: ObjectId,
    ) -> Result<Vec<u8>, PdfError> {
        let (_dict, data) = match stream {
            Object::Stream { dict, data } => (dict, data),
            _ => return Err(PdfError::NotAStream),
        };

        match data {
            StreamData::Raw { offset, length } => {
                let source = self.source.as_ref();
                let start = *offset as usize;
                let end = start
                    .checked_add(*length as usize)
                    .ok_or(PdfError::StreamTooLarge)?;
                if end > source.len() {
                    return Err(PdfError::StreamTooLarge);
                }
                let raw = &source[start..end];

                // Decrypt if we have a security handler
                if let Some(handler) = &self.security_handler {
                    Ok(handler.decrypt_stream(raw, obj_id))
                } else {
                    Ok(raw.to_vec())
                }
            }
            StreamData::Decoded { data: bytes } => Ok(bytes.clone()),
        }
    }

    /// If the filter chain contains a JBIG2 filter, look up `/JBIG2Globals`
    /// in the stream's `/DecodeParms`, resolve the referenced stream, decode
    /// it, and store the bytes in the filter params.
    fn resolve_jbig2_globals(
        &self,
        dict: &HashMap<Name, Object>,
        filters: &mut [(rpdfium_codec::DecodeFilter, rpdfium_codec::FilterParams)],
    ) {
        use rpdfium_codec::DecodeFilter;

        // Find the JBIG2 filter entry, if any
        let jbig2_entry = filters.iter_mut().find(|(f, _)| *f == DecodeFilter::JBIG2);
        let jbig2_params = match jbig2_entry {
            Some((_, params)) => params,
            None => return,
        };

        // Look up /DecodeParms to find /JBIG2Globals
        let decode_parms = match dict.get(&Name::decode_parms()) {
            Some(obj) => obj,
            None => return,
        };

        // /DecodeParms can be a dict or an array; for a single JBIG2 filter it's
        // usually a dict. For arrays, find the entry matching the JBIG2 filter index.
        let parms_dict = match decode_parms {
            Object::Dictionary(d) => Some(d),
            Object::Array(arr) => {
                // Find the index of the JBIG2 filter
                let filter_obj = dict.get(&Name::filter());
                let jbig2_idx = match filter_obj {
                    Some(Object::Array(filter_arr)) => filter_arr.iter().position(|o| {
                        o.as_name().is_some_and(|n| {
                            n.as_bytes() == b"JBIG2Decode" || n.as_bytes() == b"JBIG2"
                        })
                    }),
                    _ => Some(0), // Single filter → index 0
                };
                jbig2_idx
                    .and_then(|idx| arr.get(idx))
                    .and_then(|o| o.as_dict())
            }
            _ => None,
        };

        let parms_dict = match parms_dict {
            Some(d) => d,
            None => return,
        };

        // Get the /JBIG2Globals reference
        let globals_obj = match parms_dict.get(&Name::jbig2_globals()) {
            Some(obj) => obj,
            None => return,
        };

        // Resolve the reference to the globals stream and decode it
        let globals_stream = match globals_obj {
            Object::Reference(id) => match self.resolve(*id) {
                Ok(obj) => obj,
                Err(_) => return,
            },
            _ => return,
        };

        if let Ok(decoded) = self.decode_stream(globals_stream) {
            jbig2_params.jbig2_globals = Some(decoded);
        }
    }

    /// Returns the number of cached ObjStm entries (for testing/diagnostics).
    #[cfg(test)]
    pub(crate) fn objstm_cache_len(&self) -> usize {
        self.objstm_cache.len()
    }

    /// Decrypt a string value from an encrypted document.
    ///
    /// If the document is not encrypted, returns the input bytes unchanged.
    pub fn decrypt_string(&self, data: &[u8], obj_id: ObjectId) -> Vec<u8> {
        match &self.security_handler {
            Some(handler) => handler.decrypt_string(data, obj_id),
            None => data.to_vec(),
        }
    }
}

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

    #[test]
    fn test_build_slots_newest_wins() {
        let newer = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(1, 0),
                entry_type: XrefEntryType::InUse { offset: 100 },
            }],
        };
        let older = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(1, 0),
                entry_type: XrefEntryType::InUse { offset: 50 },
            }],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[newer, older]);
        assert_eq!(slots.len(), 1);

        match &slots[&ObjectId::new(1, 0)] {
            ObjectSlot::Direct { offset, .. } => assert_eq!(*offset, 100),
            _ => panic!("expected Direct slot"),
        }
    }

    #[test]
    fn test_build_slots_free_entries_removed() {
        let section = XrefSection {
            entries: vec![
                crate::xref::XrefEntry {
                    id: ObjectId::new(0, 65535),
                    entry_type: XrefEntryType::Free,
                },
                crate::xref::XrefEntry {
                    id: ObjectId::new(1, 0),
                    entry_type: XrefEntryType::InUse { offset: 100 },
                },
            ],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[section]);
        assert_eq!(slots.len(), 1);
        assert!(slots.contains_key(&ObjectId::new(1, 0)));
        assert!(!slots.contains_key(&ObjectId::new(0, 65535)));
    }

    #[test]
    fn test_build_slots_free_hides_older() {
        // Newer section marks object as free
        let newer = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(5, 0),
                entry_type: XrefEntryType::Free,
            }],
        };
        // Older section has the object in-use
        let older = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(5, 0),
                entry_type: XrefEntryType::InUse { offset: 200 },
            }],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[newer, older]);
        // Free entry should have been inserted first, hiding the older in-use entry.
        // Then Free entries are removed.
        assert!(!slots.contains_key(&ObjectId::new(5, 0)));
    }

    #[test]
    fn test_build_slots_in_stream() {
        let section = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(10, 0),
                entry_type: XrefEntryType::InStream {
                    stream_id: ObjectId::new(3, 0),
                    index: 2,
                },
            }],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[section]);
        assert_eq!(slots.len(), 1);
        match &slots[&ObjectId::new(10, 0)] {
            ObjectSlot::InStream {
                stream_id, index, ..
            } => {
                assert_eq!(*stream_id, ObjectId::new(3, 0));
                assert_eq!(*index, 2);
            }
            _ => panic!("expected InStream slot"),
        }
    }

    #[test]
    fn test_deep_resolve_non_reference() {
        // A minimal valid PDF for testing
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient);
        // If open succeeds, test deep_resolve on a non-reference object
        if let Ok(store) = store {
            let obj = Object::Integer(42);
            let resolved = store.deep_resolve(&obj).unwrap();
            assert_eq!(resolved.as_i64(), Some(42));
        }
    }

    /// Build a minimal valid PDF for testing.
    fn build_minimal_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    #[test]
    fn test_open_minimal_pdf() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        assert_eq!(store.file_version(), PdfVersion::new(1, 4));
        assert_eq!(store.trailer().root, ObjectId::new(1, 0));
        assert_eq!(store.trailer().size, 3);
        assert!(store.contains(ObjectId::new(1, 0)));
        assert!(store.contains(ObjectId::new(2, 0)));
        assert!(!store.contains(ObjectId::new(0, 65535)));
    }

    #[test]
    fn test_resolve_object_from_minimal_pdf() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let obj = store.resolve(ObjectId::new(1, 0)).unwrap();
        let dict = obj.as_dict().unwrap();
        assert!(dict.contains_key(&Name::r#type()));
    }

    #[test]
    fn test_resolve_unknown_object() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let result = store.resolve(ObjectId::new(999, 0));
        assert!(result.is_err());
    }

    #[test]
    fn test_deep_resolve_follows_reference() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let reference = Object::Reference(ObjectId::new(1, 0));
        let resolved = store.deep_resolve(&reference).unwrap();
        assert!(resolved.as_dict().is_some());
    }

    #[test]
    fn test_dict_resolve_present() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let catalog = store.resolve(ObjectId::new(1, 0)).unwrap();
        let dict = catalog.as_dict().unwrap();

        // /Pages is a reference — dict_resolve should follow it
        let pages = store.dict_resolve(dict, &Name::pages()).unwrap();
        assert!(pages.is_some());
        let pages_obj = pages.unwrap();
        assert!(pages_obj.as_dict().is_some());
    }

    #[test]
    fn test_dict_resolve_absent() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let catalog = store.resolve(ObjectId::new(1, 0)).unwrap();
        let dict = catalog.as_dict().unwrap();

        let nonexistent = store.dict_resolve(dict, &Name::encrypt()).unwrap();
        assert!(nonexistent.is_none());
    }

    // -----------------------------------------------------------------------
    // Circular reference detection tests
    // -----------------------------------------------------------------------

    /// deep_resolve should detect a self-referencing object (A → A).
    #[test]
    fn test_deep_resolve_self_reference() {
        // Build a PDF where object 3 is a Reference to itself
        let pdf = build_self_referencing_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let reference = Object::Reference(ObjectId::new(3, 0));
        let result = store.deep_resolve(&reference);
        assert!(result.is_err());
    }

    /// deep_resolve returns the concrete object for non-references immediately.
    #[test]
    fn test_deep_resolve_concrete_types() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        // Boolean
        let obj = Object::Boolean(true);
        assert_eq!(store.deep_resolve(&obj).unwrap().as_bool(), Some(true));

        // Integer
        let obj = Object::Integer(99);
        assert_eq!(store.deep_resolve(&obj).unwrap().as_i64(), Some(99));

        // Null
        let obj = Object::Null;
        assert!(store.deep_resolve(&obj).unwrap().is_null());

        // String
        let obj = Object::String(rpdfium_core::PdfString::from_bytes(b"test".to_vec()));
        assert!(store.deep_resolve(&obj).unwrap().as_string().is_some());
    }

    /// deep_resolve with an unknown reference ID returns error.
    #[test]
    fn test_deep_resolve_unknown_reference() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let reference = Object::Reference(ObjectId::new(999, 0));
        let result = store.deep_resolve(&reference);
        assert!(result.is_err());
    }

    // -----------------------------------------------------------------------
    // ObjectStore::open edge cases
    // -----------------------------------------------------------------------

    /// Opening a completely empty source should fail.
    #[test]
    fn test_open_empty_source() {
        let result = ObjectStore::open(Vec::new(), ParsingMode::Strict);
        assert!(result.is_err());
    }

    /// Opening garbage data should fail.
    #[test]
    fn test_open_garbage_data() {
        let result = ObjectStore::open(b"this is not a pdf".to_vec(), ParsingMode::Strict);
        assert!(result.is_err());
    }

    /// Opening data with only a header but no xref/trailer should fail.
    #[test]
    fn test_open_header_only() {
        let result = ObjectStore::open(b"%PDF-1.4\n".to_vec(), ParsingMode::Strict);
        assert!(result.is_err());
    }

    // -----------------------------------------------------------------------
    // build_slots edge cases
    // -----------------------------------------------------------------------

    /// Empty xref sections produces no slots.
    #[test]
    fn test_build_slots_empty() {
        let slots = ObjectStore::<Vec<u8>>::build_slots(&[]);
        assert!(slots.is_empty());
    }

    /// Multiple sections with different objects are all included.
    #[test]
    fn test_build_slots_disjoint_sections() {
        let section1 = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(1, 0),
                entry_type: XrefEntryType::InUse { offset: 100 },
            }],
        };
        let section2 = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(2, 0),
                entry_type: XrefEntryType::InUse { offset: 200 },
            }],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[section1, section2]);
        assert_eq!(slots.len(), 2);
        assert!(slots.contains_key(&ObjectId::new(1, 0)));
        assert!(slots.contains_key(&ObjectId::new(2, 0)));
    }

    /// InStream slot stores the correct stream_id and index.
    #[test]
    fn test_build_slots_in_stream_fields() {
        let section = XrefSection {
            entries: vec![crate::xref::XrefEntry {
                id: ObjectId::new(42, 0),
                entry_type: XrefEntryType::InStream {
                    stream_id: ObjectId::new(10, 0),
                    index: 7,
                },
            }],
        };

        let slots = ObjectStore::<Vec<u8>>::build_slots(&[section]);
        match &slots[&ObjectId::new(42, 0)] {
            ObjectSlot::InStream {
                stream_id, index, ..
            } => {
                assert_eq!(*stream_id, ObjectId::new(10, 0));
                assert_eq!(*index, 7);
            }
            _ => panic!("expected InStream"),
        }
    }

    // -----------------------------------------------------------------------
    // ObjectStore metadata tests
    // -----------------------------------------------------------------------

    /// Verify object_count and object_ids match expected values.
    #[test]
    fn test_object_count_and_ids() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        assert_eq!(store.object_count(), 2);

        let ids: Vec<ObjectId> = store.object_ids().copied().collect();
        assert!(ids.contains(&ObjectId::new(1, 0)));
        assert!(ids.contains(&ObjectId::new(2, 0)));
    }

    /// Verify parsing_mode accessor.
    #[test]
    fn test_parsing_mode_accessor() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        assert_eq!(store.parsing_mode(), ParsingMode::Strict);
    }

    /// Lenient mode returns Null for parse-failed objects.
    #[test]
    fn test_lenient_mode_returns_null_for_bad_object() {
        // Build a PDF where the xref points to a garbage offset
        let pdf = build_pdf_with_bad_object();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();

        // Object 3 points to garbage — lenient mode should return Null
        let result = store.resolve(ObjectId::new(3, 0));
        match result {
            Ok(obj) => assert!(obj.is_null()),
            Err(_) => {
                // Some implementations may still error — either is acceptable
            }
        }
    }

    // -----------------------------------------------------------------------
    // Decode stream tests
    // -----------------------------------------------------------------------

    /// decode_stream on a non-stream object should fail.
    #[test]
    fn test_decode_stream_not_a_stream() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let obj = Object::Integer(42);
        let result = store.decode_stream(&obj);
        assert!(result.is_err());
    }

    // -----------------------------------------------------------------------
    // Stream decode integration tests
    // -----------------------------------------------------------------------

    /// decode_stream on a Flate-compressed stream should decompress correctly.
    #[test]
    fn test_decode_stream_flate() {
        let pdf = build_pdf_with_flate_stream();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let stream_obj = store.resolve(ObjectId::new(3, 0)).unwrap();
        let decoded = store.decode_stream(stream_obj).unwrap();
        assert_eq!(decoded, b"Hello, PDF stream!");
    }

    /// decode_stream on an ASCIIHex-encoded stream should decode correctly.
    #[test]
    fn test_decode_stream_ascii_hex() {
        let pdf = build_pdf_with_ascii_hex_stream();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let stream_obj = store.resolve(ObjectId::new(3, 0)).unwrap();
        let decoded = store.decode_stream(stream_obj).unwrap();
        assert_eq!(decoded, b"Hello");
    }

    /// decode_stream on an unfiltered stream should return raw bytes.
    #[test]
    fn test_decode_stream_no_filter() {
        let pdf = build_pdf_with_raw_stream();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let stream_obj = store.resolve(ObjectId::new(3, 0)).unwrap();
        let decoded = store.decode_stream(stream_obj).unwrap();
        assert_eq!(decoded, b"raw data");
    }

    // -----------------------------------------------------------------------
    // Helpers
    // -----------------------------------------------------------------------

    /// Build a PDF with a Flate-compressed stream (object 3).
    fn build_pdf_with_flate_stream() -> Vec<u8> {
        use flate2::Compression;
        use flate2::write::ZlibEncoder;
        use std::io::Write;

        let original = b"Hello, PDF stream!";
        let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
        encoder.write_all(original).unwrap();
        let compressed = encoder.finish().unwrap();

        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        let obj3_offset = pdf.len();
        let stream_dict = format!(
            "3 0 obj\n<< /Length {} /Filter /FlateDecode >>\nstream\n",
            compressed.len()
        );
        pdf.extend_from_slice(stream_dict.as_bytes());
        pdf.extend_from_slice(&compressed);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Build a PDF with an ASCIIHex-encoded stream (object 3).
    fn build_pdf_with_ascii_hex_stream() -> Vec<u8> {
        let hex_data = b"48656C6C6F>";

        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        let obj3_offset = pdf.len();
        let stream_dict = format!(
            "3 0 obj\n<< /Length {} /Filter /ASCIIHexDecode >>\nstream\n",
            hex_data.len()
        );
        pdf.extend_from_slice(stream_dict.as_bytes());
        pdf.extend_from_slice(hex_data);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Build a PDF with a raw (unfiltered) stream (object 3).
    fn build_pdf_with_raw_stream() -> Vec<u8> {
        let raw = b"raw data";

        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        let obj3_offset = pdf.len();
        let stream_dict = format!("3 0 obj\n<< /Length {} >>\nstream\n", raw.len());
        pdf.extend_from_slice(stream_dict.as_bytes());
        pdf.extend_from_slice(raw);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Build a PDF with a self-referencing object (object 3 → 3 0 R).
    fn build_self_referencing_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        let obj3_offset = pdf.len();
        pdf.extend_from_slice(b"3 0 obj\n3 0 R\nendobj\n");

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Build a PDF where object 3 points to garbage offset.
    fn build_pdf_with_bad_object() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");

        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        // Object 3 offset will point to the middle of existing data (garbage)
        let obj3_offset = 5; // Points to "-1.4\n" — not a valid object

        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n");
        pdf.extend_from_slice(b"0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Build a PDF with a corrupt/missing startxref but valid objects and trailer.
    fn build_pdf_with_corrupt_xref() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        // Include a trailer dict but corrupt the xref/startxref
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(b"startxref\n99999\n%%EOF");
        pdf
    }

    // -----------------------------------------------------------------------
    // XRef rebuild fallback tests
    // -----------------------------------------------------------------------

    /// Lenient mode with corrupt xref falls back to rebuild and succeeds.
    #[test]
    fn test_open_corrupt_xref_lenient_rebuilds() {
        let pdf = build_pdf_with_corrupt_xref();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();

        // Should have found the catalog and pages objects
        assert!(store.contains(ObjectId::new(1, 0)));
        assert!(store.contains(ObjectId::new(2, 0)));
        assert_eq!(store.trailer().root, ObjectId::new(1, 0));
    }

    /// Strict mode with corrupt xref does NOT fall back — returns error.
    #[test]
    fn test_open_corrupt_xref_strict_fails() {
        let pdf = build_pdf_with_corrupt_xref();
        let result = ObjectStore::open(pdf, ParsingMode::Strict);
        assert!(result.is_err());
    }

    /// PDF with valid xref uses the normal path (not rebuild).
    #[test]
    fn test_open_valid_xref_uses_normal_path() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        assert!(store.contains(ObjectId::new(1, 0)));
        assert!(store.contains(ObjectId::new(2, 0)));
        assert_eq!(store.trailer().root, ObjectId::new(1, 0));
        assert_eq!(store.trailer().size, 3);
    }

    /// xref_rebuilt() returns true when xref was rebuilt in lenient mode.
    #[test]
    fn test_xref_rebuilt_true_for_corrupt_xref() {
        let pdf = build_pdf_with_corrupt_xref();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        assert!(store.xref_table_rebuilt());
    }

    /// xref_rebuilt() returns false for a valid PDF.
    #[test]
    fn test_xref_rebuilt_false_for_valid_pdf() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        assert!(!store.xref_table_rebuilt());
    }

    /// is_xref_stream() returns false for a traditional xref table.
    #[test]
    fn test_is_xref_stream_false_for_traditional_xref() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        assert!(!store.is_xref_stream());
    }

    /// is_xref_stream() returns false when xref was rebuilt (no original xref stream).
    #[test]
    fn test_is_xref_stream_false_when_rebuilt() {
        let pdf = build_pdf_with_corrupt_xref();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        assert!(!store.is_xref_stream());
    }

    /// object_position_or_zero() returns the byte offset for a direct object.
    #[test]
    fn test_object_offset_returns_offset_for_direct_object() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        // Object 1 should be at a known offset; just verify it is Some and > 0
        let offset = store.object_position_or_zero(ObjectId::new(1, 0));
        assert!(offset.is_some());
        assert!(offset.unwrap() > 0);
    }

    /// object_position_or_zero() returns None for unknown objects.
    #[test]
    fn test_object_offset_returns_none_for_unknown_object() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        assert_eq!(store.object_position_or_zero(ObjectId::new(999, 0)), None);
    }

    /// PDF where /Size in trailer is smaller than the actual number of objects.
    /// This should still work because build_slots uses xref entries, not /Size.
    #[test]
    fn test_open_wrong_xref_size_still_resolves() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(
            b"2 0 obj\n<< /Type /Pages /MediaBox [0 0 200 300] /Count 1 /Kids [3 0 R] >>\nendobj\n",
        );
        let obj3_offset = pdf.len();
        pdf.extend_from_slice(b"3 0 obj\n<< /Type /Page /Parent 2 0 R >>\nendobj\n");
        let obj4_offset = pdf.len();
        let content = b"q 0 0 0 rg 0 290 10 10 re B* Q";
        pdf.extend_from_slice(
            format!("4 0 obj\n<< /Length {} >>\nstream\n", content.len()).as_bytes(),
        );
        pdf.extend_from_slice(content);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 5\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj4_offset).as_bytes());
        // Deliberately set /Size to 4 instead of 5
        pdf.extend_from_slice(b"trailer\n<< /Root 1 0 R /Size 4 >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());

        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        // All 4 real objects should be accessible even though /Size says 4
        assert!(store.contains(ObjectId::new(1, 0)));
        assert!(store.contains(ObjectId::new(2, 0)));
        assert!(store.contains(ObjectId::new(3, 0)));
        assert!(store.contains(ObjectId::new(4, 0)));
        assert_eq!(store.trailer().root, ObjectId::new(1, 0));
        // /Size is 4 per the trailer, but all 5 xref entries are in slots
        assert_eq!(store.trailer().size, 4);
    }

    // -----------------------------------------------------------------------
    // ObjStm caching tests
    // -----------------------------------------------------------------------

    /// Build a PDF 1.5 with an Object Stream (obj 3) containing two objects
    /// (obj numbers 10 and 11), using a cross-reference stream.
    fn build_pdf_with_objstm() -> Vec<u8> {
        use flate2::Compression;
        use flate2::write::ZlibEncoder;
        use std::io::Write;

        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.5\n");

        // Object 1: Catalog
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

        // Object 2: Pages
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

        // Object 3: ObjStm containing objects 10 and 11
        // ObjStm header: "10 0 11 3 " (obj 10 at offset 0, obj 11 at offset 3)
        // ObjStm data after /First: "42 true"
        let objstm_raw = b"10 0 11 3 42 true";
        let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
        encoder.write_all(objstm_raw).unwrap();
        let objstm_compressed = encoder.finish().unwrap();

        let obj3_offset = pdf.len();
        let objstm_dict = format!(
            "3 0 obj\n<< /Type /ObjStm /N 2 /First 10 /Length {} /Filter /FlateDecode >>\nstream\n",
            objstm_compressed.len()
        );
        pdf.extend_from_slice(objstm_dict.as_bytes());
        pdf.extend_from_slice(&objstm_compressed);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");

        // Cross-reference stream (object 4)
        // We have objects: 0 (free), 1, 2, 3 (direct), 10, 11 (in ObjStm 3)
        // Use /W [1 2 1] — type: 1 byte, field2: 2 bytes, field3: 1 byte
        // /Index [0 4 10 2] — subsections: 0-3 and 10-11

        let mut xref_data = Vec::new();
        // Entry 0: free (type=0, next_free=0, gen=255)
        xref_data.push(0);
        xref_data.extend_from_slice(&(0u16).to_be_bytes());
        xref_data.push(255);
        // Entry 1: in-use at obj1_offset
        xref_data.push(1);
        xref_data.extend_from_slice(&(obj1_offset as u16).to_be_bytes());
        xref_data.push(0);
        // Entry 2: in-use at obj2_offset
        xref_data.push(1);
        xref_data.extend_from_slice(&(obj2_offset as u16).to_be_bytes());
        xref_data.push(0);
        // Entry 3: in-use at obj3_offset
        xref_data.push(1);
        xref_data.extend_from_slice(&(obj3_offset as u16).to_be_bytes());
        xref_data.push(0);
        // Entry 10: in ObjStm 3 at index 0
        xref_data.push(2);
        xref_data.extend_from_slice(&(3u16).to_be_bytes()); // stream_id = 3
        xref_data.push(0); // index = 0
        // Entry 11: in ObjStm 3 at index 1
        xref_data.push(2);
        xref_data.extend_from_slice(&(3u16).to_be_bytes()); // stream_id = 3
        xref_data.push(1); // index = 1

        let xref_offset = pdf.len();
        let xref_dict = format!(
            "4 0 obj\n<< /Type /XRef /Size 12 /W [1 2 1] /Index [0 4 10 2] /Root 1 0 R /Length {} >>\nstream\n",
            xref_data.len()
        );
        pdf.extend_from_slice(xref_dict.as_bytes());
        pdf.extend_from_slice(&xref_data);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");

        pdf.extend_from_slice(format!("startxref\n{}\n%%EOF", xref_offset).as_bytes());

        pdf
    }

    /// Resolving an object from an ObjStm should work.
    #[test]
    fn test_resolve_object_from_objstm() {
        let pdf = build_pdf_with_objstm();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        // Object 10 is integer 42 (index 0 in ObjStm 3)
        let obj10 = store.resolve(ObjectId::new(10, 0)).unwrap();
        assert_eq!(obj10.as_i64(), Some(42));

        // Object 11 is boolean true (index 1 in ObjStm 3)
        let obj11 = store.resolve(ObjectId::new(11, 0)).unwrap();
        assert_eq!(obj11.as_bool(), Some(true));
    }

    /// Resolving the same ObjStm object twice returns the same result.
    #[test]
    fn test_objstm_same_object_twice() {
        let pdf = build_pdf_with_objstm();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        let first = store.resolve(ObjectId::new(10, 0)).unwrap();
        let second = store.resolve(ObjectId::new(10, 0)).unwrap();
        assert_eq!(first.as_i64(), second.as_i64());
        assert_eq!(first.as_i64(), Some(42));
    }

    /// After resolving one object from an ObjStm, the entire ObjStm is cached.
    #[test]
    fn test_objstm_cache_populated_after_first_access() {
        let pdf = build_pdf_with_objstm();
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();

        // Cache should be empty initially
        assert_eq!(store.objstm_cache_len(), 0);

        // Resolve object 10 (triggers ObjStm 3 parse and cache)
        let _ = store.resolve(ObjectId::new(10, 0)).unwrap();

        // Cache should now have 1 entry (ObjStm 3)
        assert_eq!(store.objstm_cache_len(), 1);

        // Resolve object 11 from the same ObjStm — should hit cache
        let obj11 = store.resolve(ObjectId::new(11, 0)).unwrap();
        assert_eq!(obj11.as_bool(), Some(true));

        // Cache should still have 1 entry (same ObjStm)
        assert_eq!(store.objstm_cache_len(), 1);
    }

    /// Cache size limit: only MAX_OBJSTM_CACHE_ENTRIES are cached.
    #[test]
    fn test_objstm_cache_size_limit() {
        // Verify the constant is reasonable
        assert_eq!(MAX_OBJSTM_CACHE_ENTRIES, 256);
    }

    // -----------------------------------------------------------------------
    // Malformed PDF resilience tests
    // -----------------------------------------------------------------------

    /// Corrupted xref offsets — lenient mode should recover via rebuild or fail gracefully.
    #[test]
    fn test_malformed_wrong_xref_offsets_lenient() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        // obj1_offset intentionally unused — we supply a wrong offset below
        let _obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        // Wrong offset for obj 1 (points to wrong location)
        pdf.extend_from_slice(b"0000099999 00000 n \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        // Lenient mode — should not panic, may recover via rebuild
        let _ = ObjectStore::open(pdf, ParsingMode::Lenient);
    }

    /// Corrupted xref offsets — strict mode should fail.
    #[test]
    fn test_malformed_wrong_xref_offsets_strict() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        // obj1_offset intentionally unused — we supply a wrong offset below
        let _obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(b"0000099999 00000 n \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let store = ObjectStore::open(pdf, ParsingMode::Strict).unwrap();
        // Resolving the object at the bad offset should fail
        let result = store.resolve(ObjectId::new(1, 0));
        assert!(result.is_err());
    }

    /// Truncated PDF — file cut off mid-object.
    #[test]
    fn test_malformed_truncated_pdf() {
        let pdf = b"%PDF-1.4\n1 0 obj\n<< /Type /Cat".to_vec();
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        assert!(result.is_err());
    }

    /// Missing %%EOF marker — lenient should still handle.
    #[test]
    fn test_malformed_missing_eof_marker() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n").as_bytes());
        // No %%EOF
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        // Should not panic — may succeed or fail gracefully
        let _ = result;
    }

    /// Empty PDF — should fail gracefully.
    #[test]
    fn test_malformed_empty_pdf() {
        let result = ObjectStore::open(Vec::new(), ParsingMode::Lenient);
        assert!(result.is_err());
    }

    /// PDF header only — no objects, no xref.
    #[test]
    fn test_malformed_header_only() {
        let result = ObjectStore::open(b"%PDF-1.4\n".to_vec(), ParsingMode::Lenient);
        assert!(result.is_err());
    }

    /// Invalid startxref value pointing beyond file.
    #[test]
    fn test_malformed_invalid_startxref() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(b"startxref\n99999999\n%%EOF");
        // Lenient should attempt rebuild or fail gracefully
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        let _ = result;
    }

    /// Duplicate keys in dictionary — should parse without panic.
    #[test]
    fn test_malformed_duplicate_dict_keys() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        // Dict with duplicate /Type keys
        pdf.extend_from_slice(
            b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R /Type /Catalog >>\nendobj\n",
        );
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        assert!(result.is_ok());
    }

    /// Oversized /Size in trailer — should not cause OOM.
    #[test]
    fn test_malformed_oversized_trailer_size() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        // Absurdly large /Size
        pdf.extend_from_slice(b"trailer\n<< /Size 999999999 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        // Should handle gracefully (no OOM panic)
        let _ = result;
    }

    /// Resolve non-existent object — should return error.
    #[test]
    fn test_malformed_resolve_nonexistent_object() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        let result = store.resolve(ObjectId::new(999, 0));
        assert!(result.is_err());
    }

    /// Object with wrong generation number — should not panic.
    #[test]
    fn test_malformed_wrong_generation() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        // Object 1 exists with gen 0; try gen 1
        let result = store.resolve(ObjectId::new(1, 1));
        // May succeed (lenient) or fail — just shouldn't panic
        let _ = result;
    }

    /// Deeply nested arrays — should handle depth limit without stack overflow.
    #[test]
    fn test_malformed_deeply_nested_arrays() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        let mut nested = String::from("1 0 obj\n");
        for _ in 0..100 {
            nested.push('[');
        }
        nested.push_str("true");
        for _ in 0..100 {
            nested.push(']');
        }
        nested.push_str("\nendobj\n");
        pdf.extend_from_slice(nested.as_bytes());
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Catalog /Pages 3 0 R >>\nendobj\n");
        let obj3_offset = pdf.len();
        pdf.extend_from_slice(b"3 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 4 /Root 2 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        // Should handle depth without stack overflow
        let _ = result;
    }

    /// Resolve object 0 (free head entry) — should not panic.
    #[test]
    fn test_malformed_resolve_object_zero() {
        let pdf = build_minimal_pdf();
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        // Object 0 is the free head entry; resolving it should fail gracefully
        let result = store.resolve(ObjectId::new(0, 0));
        let _ = result;
    }

    /// Stream with wrong /Length — lenient mode should handle endstream scanning.
    #[test]
    fn test_malformed_stream_wrong_length() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let obj3_offset = pdf.len();
        let content = b"BT /F1 12 Tf 10 10 Td (Hello) Tj ET";
        // Declare wrong length (much larger than actual)
        pdf.extend_from_slice(b"3 0 obj\n<< /Length 99999 >>\nstream\n");
        pdf.extend_from_slice(content);
        pdf.extend_from_slice(b"\nendstream\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj3_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        // Should parse successfully or fail gracefully
        let _ = result;
    }

    /// Missing /Root in trailer with catalog object — lenient recovers via rebuild fallback.
    #[test]
    fn test_malformed_missing_root_with_catalog() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        // Trailer without /Root — rebuild fallback scans for /Type /Catalog
        pdf.extend_from_slice(b"trailer\n<< /Size 3 >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        // Lenient mode recovers by scanning objects for /Type /Catalog
        assert!(result.is_ok());
    }

    /// Missing /Root in trailer without any catalog object — should fail.
    #[test]
    fn test_malformed_missing_root_no_catalog() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        // No /Type /Catalog — just a plain dictionary
        pdf.extend_from_slice(b"1 0 obj\n<< /Foo /Bar >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        // Trailer without /Root and no /Type /Catalog object to find
        pdf.extend_from_slice(b"trailer\n<< /Size 3 >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        assert!(result.is_err());
    }

    /// Circular reference between objects — resolve should not infinite-loop.
    #[test]
    fn test_malformed_circular_reference() {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let obj1_offset = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R /Extra 2 0 R >>\nendobj\n");
        let obj2_offset = pdf.len();
        pdf.extend_from_slice(
            b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 /Parent 1 0 R >>\nendobj\n",
        );
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 3\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj1_offset).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", obj2_offset).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 3 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        let store = ObjectStore::open(pdf, ParsingMode::Lenient).unwrap();
        // Resolving should work — circular refs are in dict values, not ref chains
        let obj1 = store.resolve(ObjectId::new(1, 0)).unwrap();
        assert!(obj1.as_dict().is_some());
    }

    /// PDF with only whitespace after header — should fail gracefully.
    #[test]
    fn test_malformed_whitespace_only_after_header() {
        let pdf = b"%PDF-1.4\n   \n   \n".to_vec();
        let result = ObjectStore::open(pdf, ParsingMode::Lenient);
        assert!(result.is_err());
    }
}