oxidize_pdf/parser/

document.rs

//! PDF Document wrapper - High-level interface for PDF parsing and manipulation
//!
//! This module provides a robust, high-level interface for working with PDF documents.
//! It solves Rust's borrow checker challenges through careful use of interior mutability
//! (RefCell) and separation of concerns between parsing, caching, and page access.
//!
//! # Architecture
//!
//! The module uses a layered architecture:
//! - **PdfDocument**: Main entry point with RefCell-based state management
//! - **ResourceManager**: Centralized object caching with interior mutability
//! - **PdfReader**: Low-level file access (wrapped in RefCell)
//! - **PageTree**: Lazy-loaded page navigation
//!
//! # Key Features
//!
//! - **Automatic caching**: Objects are cached after first access
//! - **Resource management**: Objects are cached per-document for efficient reuse
//! - **Page navigation**: Fast access to any page in the document
//! - **Reference resolution**: Automatic resolution of indirect references
//! - **Text extraction**: Built-in support for extracting text from pages
//!
//! # Example
//!
//! ```rust,no_run
//! use oxidize_pdf::parser::{PdfDocument, PdfReader};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Open a PDF document
//! let reader = PdfReader::open("document.pdf")?;
//! let document = PdfDocument::new(reader);
//!
//! // Get document information
//! let page_count = document.page_count()?;
//! let metadata = document.metadata()?;
//! println!("Title: {:?}", metadata.title);
//! println!("Pages: {}", page_count);
//!
//! // Access a specific page
//! let page = document.get_page(0)?;
//! println!("Page size: {}x{}", page.width(), page.height());
//!
//! // Extract text from all pages
//! let extracted_text = document.extract_text()?;
//! for (i, page_text) in extracted_text.iter().enumerate() {
//!     println!("Page {}: {}", i + 1, page_text.text);
//! }
//! # Ok(())
//! # }
//! ```

#[cfg(test)]
use super::objects::{PdfArray, PdfName};
use super::objects::{PdfDictionary, PdfObject, PdfStream};
use super::page_tree::{PageTree, ParsedPage};
use super::reader::PdfReader;
use super::{ParseError, ParseOptions, ParseResult};
use std::cell::RefCell;
use std::collections::{HashMap, HashSet};
use std::fs::File;
use std::io::{Read, Seek};
use std::path::Path;

/// Resource manager for efficient PDF object caching.
///
/// The ResourceManager provides centralized caching of PDF objects to avoid
/// repeated parsing overhead. It is owned exclusively by a `PdfDocument` and uses
/// `RefCell` for interior mutability, so cache writes can occur through a shared
/// borrow of the document.
///
/// # Caching Strategy
///
/// - Objects are cached on first access
/// - Cache persists for the lifetime of the document
/// - Manual cache clearing is supported for memory management
///
/// # Example
///
/// ```rust,no_run
/// use oxidize_pdf::parser::document::ResourceManager;
///
/// let resources = ResourceManager::new();
///
/// // Objects are cached automatically when accessed through PdfDocument
/// // Manual cache management:
/// resources.clear_cache(); // Free memory when needed
/// ```
pub struct ResourceManager {
    /// Cached objects indexed by (object_number, generation_number)
    object_cache: RefCell<HashMap<(u32, u16), PdfObject>>,
}

impl Default for ResourceManager {
    fn default() -> Self {
        Self::new()
    }
}

impl ResourceManager {
    /// Create a new resource manager
    pub fn new() -> Self {
        Self {
            object_cache: RefCell::new(HashMap::new()),
        }
    }

    /// Get an object from cache if available.
    ///
    /// # Arguments
    ///
    /// * `obj_ref` - Object reference (object_number, generation_number)
    ///
    /// # Returns
    ///
    /// Cloned object if cached, None otherwise.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::document::ResourceManager;
    /// # let resources = ResourceManager::new();
    /// if let Some(obj) = resources.get_cached((10, 0)) {
    ///     println!("Object 10 0 R found in cache");
    /// }
    /// ```
    pub fn get_cached(&self, obj_ref: (u32, u16)) -> Option<PdfObject> {
        self.object_cache.borrow().get(&obj_ref).cloned()
    }

    /// Cache an object for future access.
    ///
    /// # Arguments
    ///
    /// * `obj_ref` - Object reference (object_number, generation_number)
    /// * `obj` - The PDF object to cache
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::document::ResourceManager;
    /// # use oxidize_pdf::parser::objects::PdfObject;
    /// # let resources = ResourceManager::new();
    /// resources.cache_object((10, 0), PdfObject::Integer(42));
    /// ```
    pub fn cache_object(&self, obj_ref: (u32, u16), obj: PdfObject) {
        self.object_cache.borrow_mut().insert(obj_ref, obj);
    }

    /// Clear all cached objects to free memory.
    ///
    /// Use this when processing large documents to manage memory usage.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::document::ResourceManager;
    /// # let resources = ResourceManager::new();
    /// // After processing many pages
    /// resources.clear_cache();
    /// println!("Cache cleared to free memory");
    /// ```
    pub fn clear_cache(&self) {
        self.object_cache.borrow_mut().clear();
    }
}

/// High-level PDF document interface for parsing and manipulation.
///
/// `PdfDocument` provides a clean, safe API for working with PDF files.
/// It handles the complexity of PDF structure, object references, and resource
/// management behind a simple interface.
///
/// # Type Parameter
///
/// * `R` - The reader type (must implement Read + Seek)
///
/// # Architecture Benefits
///
/// - **RefCell Usage**: Allows multiple parts of the API to access the document
/// - **Lazy Loading**: Pages and resources are loaded on demand
/// - **Automatic Caching**: Frequently accessed objects are cached
/// - **Safe API**: Borrow checker issues are handled internally
///
/// # Thread Safety
///
/// `PdfDocument<R>` is `Send` for `R: Send` (issue #369): it can be moved to
/// another thread or across a Python GIL boundary (e.g. `Python::allow_threads`).
/// It is intentionally `!Sync` because `RefCell` does not permit shared concurrent
/// access; callers that need concurrent reads should use one instance per thread.
///
/// # Example
///
/// ```rust,no_run
/// use oxidize_pdf::parser::{PdfDocument, PdfReader};
/// use std::fs::File;
///
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// // From a file
/// let reader = PdfReader::open("document.pdf")?;
/// let document = PdfDocument::new(reader);
///
/// // From any Read + Seek source
/// let file = File::open("document.pdf")?;
/// let reader = PdfReader::new(file)?;
/// let document = PdfDocument::new(reader);
///
/// // Use the document
/// let page_count = document.page_count()?;
/// for i in 0..page_count {
///     let page = document.get_page(i)?;
///     // Process page...
/// }
/// # Ok(())
/// # }
/// ```
pub struct PdfDocument<R: Read + Seek> {
    /// The underlying PDF reader wrapped for interior mutability
    reader: RefCell<PdfReader<R>>,
    /// Page tree navigator (lazily initialized)
    page_tree: RefCell<Option<PageTree>>,
    /// Resource manager for object caching (owned; interior mutability via RefCell).
    /// Not shared/cloned, so a plain owned field keeps `PdfDocument<R>: Send` for
    /// `R: Send` without any locking overhead (issue #369).
    resources: ResourceManager,
    /// Cached document metadata to avoid repeated parsing
    metadata_cache: RefCell<Option<super::reader::DocumentMetadata>>,
}

impl<R: Read + Seek> PdfDocument<R> {
    /// Read the complete document outline with default resource limits.
    ///
    /// # Errors
    ///
    /// Returns an error when the page tree, outline hierarchy, sibling links,
    /// or a referenced destination is malformed or exceeds a configured limit.
    pub fn outline(&self) -> ParseResult<Option<crate::structure::OutlineTree>> {
        self.outline_with_options(&super::outline::OutlineReadOptions::default())
    }

    /// Read the complete document outline with explicit resource limits.
    ///
    /// # Errors
    ///
    /// Returns an error when the page tree, outline hierarchy, sibling links,
    /// or a referenced destination is malformed or exceeds `options`.
    pub fn outline_with_options(
        &self,
        options: &super::outline::OutlineReadOptions,
    ) -> ParseResult<Option<crate::structure::OutlineTree>> {
        if !self.catalog_dictionary()?.contains_key("Outlines") {
            return Ok(None);
        }
        let count = self.page_count()?;
        let mut pages = HashMap::with_capacity(count as usize);
        for index in 0..count {
            pages.insert(self.get_page(index)?.obj_ref, index);
        }
        super::outline::read_outline(&mut self.reader.borrow_mut(), &pages, options)
    }

    /// Create a new PDF document from a reader
    pub fn new(reader: PdfReader<R>) -> Self {
        Self {
            reader: RefCell::new(reader),
            page_tree: RefCell::new(None),
            resources: ResourceManager::new(),
            metadata_cache: RefCell::new(None),
        }
    }

    /// Get the PDF version of the document.
    ///
    /// # Returns
    ///
    /// PDF version string (e.g., "1.4", "1.7", "2.0")
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let version = document.version()?;
    /// println!("PDF version: {}", version);
    /// # Ok(())
    /// # }
    /// ```
    pub fn version(&self) -> ParseResult<String> {
        Ok(self.reader.borrow().version().to_string())
    }

    /// Return an owned catalog for crate-internal document-level consumers.
    pub(crate) fn catalog_dictionary(&self) -> ParseResult<PdfDictionary> {
        self.reader.borrow_mut().catalog().cloned()
    }

    /// Get the parse options
    pub fn options(&self) -> ParseOptions {
        self.reader.borrow().options().clone()
    }

    /// Get the total number of pages in the document.
    ///
    /// # Returns
    ///
    /// The page count as an unsigned 32-bit integer.
    ///
    /// # Errors
    ///
    /// Returns an error if the page tree is malformed or missing.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let count = document.page_count()?;
    /// println!("Document has {} pages", count);
    ///
    /// // Iterate through all pages
    /// for i in 0..count {
    ///     let page = document.get_page(i)?;
    ///     // Process page...
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn page_count(&self) -> ParseResult<u32> {
        self.ensure_page_tree()?;
        if let Some(pt) = self.page_tree.borrow().as_ref() {
            Ok(pt.page_count())
        } else {
            // Fallback: should never reach here since ensure_page_tree() just ran
            self.reader.borrow_mut().page_count()
        }
    }

    /// Get document metadata including title, author, creation date, etc.
    ///
    /// Metadata is cached after first access for performance.
    ///
    /// # Returns
    ///
    /// A `DocumentMetadata` struct containing all available metadata fields.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let metadata = document.metadata()?;
    ///
    /// if let Some(title) = &metadata.title {
    ///     println!("Title: {}", title);
    /// }
    /// if let Some(author) = &metadata.author {
    ///     println!("Author: {}", author);
    /// }
    /// if let Some(creation_date) = &metadata.creation_date {
    ///     println!("Created: {}", creation_date);
    /// }
    /// println!("PDF Version: {}", metadata.version);
    /// # Ok(())
    /// # }
    /// ```
    pub fn metadata(&self) -> ParseResult<super::reader::DocumentMetadata> {
        // Check cache first
        if let Some(metadata) = self.metadata_cache.borrow().as_ref() {
            return Ok(metadata.clone());
        }

        // Load metadata
        let metadata = self.reader.borrow_mut().metadata()?;
        self.metadata_cache.borrow_mut().replace(metadata.clone());
        Ok(metadata)
    }

    /// Initialize the page tree if not already done.
    ///
    /// Builds a flat index of all leaf Page references by walking the tree once.
    /// This provides O(1) page access and detects cycles and absurd /Count values.
    fn ensure_page_tree(&self) -> ParseResult<()> {
        if self.page_tree.borrow().is_none() {
            let pages_dict = self.load_pages_dict()?;
            let page_refs = {
                let mut reader = self.reader.borrow_mut();
                PageTree::flatten_page_tree(&mut *reader, &pages_dict)?
            };
            let page_tree = PageTree::new_with_flat_index(pages_dict, page_refs);
            self.page_tree.borrow_mut().replace(page_tree);
        }
        Ok(())
    }

    /// Load the pages dictionary
    fn load_pages_dict(&self) -> ParseResult<PdfDictionary> {
        let mut reader = self.reader.borrow_mut();
        let pages = reader.pages()?;
        Ok(pages.clone())
    }

    /// Get a page by index (0-based).
    ///
    /// Pages are cached after first access. This method handles page tree
    /// traversal and property inheritance automatically.
    ///
    /// # Arguments
    ///
    /// * `index` - Zero-based page index (0 to page_count-1)
    ///
    /// # Returns
    ///
    /// A complete `ParsedPage` with all properties and inherited resources.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Index is out of bounds
    /// - Page tree is malformed
    /// - Required page properties are missing
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// // Get the first page
    /// let page = document.get_page(0)?;
    ///
    /// // Access page properties
    /// println!("Page size: {}x{} points", page.width(), page.height());
    /// println!("Rotation: {}°", page.rotation);
    ///
    /// // Get content streams
    /// let streams = page.content_streams_with_document(&document)?;
    /// println!("Page has {} content streams", streams.len());
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_page(&self, index: u32) -> ParseResult<ParsedPage> {
        self.ensure_page_tree()?;

        // First check if page is already cached
        if let Some(page_tree) = self.page_tree.borrow().as_ref() {
            if let Some(page) = page_tree.get_cached_page(index) {
                return Ok(page.clone());
            }
        }

        // Try flat index O(1) lookup first
        let (page_ref, has_flat_index) = {
            let pt_borrow = self.page_tree.borrow();
            let pt = pt_borrow.as_ref();
            let ref_val = pt.and_then(|pt| pt.get_page_ref(index));
            let has_index = pt.map_or(false, |pt| pt.page_count() > 0 || ref_val.is_some());
            (ref_val, has_index)
        };

        let page = if let Some(page_ref) = page_ref {
            self.load_page_by_ref(page_ref)?
        } else if has_flat_index {
            // Flat index exists but page not found — index is out of range
            return Err(ParseError::SyntaxError {
                position: 0,
                message: format!(
                    "Page index {} out of range (document has {} pages)",
                    index,
                    self.page_tree
                        .borrow()
                        .as_ref()
                        .map_or(0, |pt| pt.page_count())
                ),
            });
        } else {
            // No flat index available — fallback to tree traversal
            self.load_page_at_index(index)?
        };

        // Cache it
        if let Some(page_tree) = self.page_tree.borrow_mut().as_mut() {
            page_tree.cache_page(index, page.clone());
        }

        Ok(page)
    }

    /// Load a specific page by index (legacy tree traversal fallback)
    fn load_page_at_index(&self, index: u32) -> ParseResult<ParsedPage> {
        // Get the pages root
        let pages_dict = self.load_pages_dict()?;

        // Navigate to the specific page
        let page_info = self.find_page_in_tree(&pages_dict, index, 0, None)?;

        Ok(page_info)
    }

    /// Load a page directly by its object reference (O(1) via flat index).
    fn load_page_by_ref(&self, page_ref: (u32, u16)) -> ParseResult<ParsedPage> {
        let obj = self.get_object(page_ref.0, page_ref.1)?;
        let dict = obj.as_dict().ok_or_else(|| ParseError::SyntaxError {
            position: 0,
            message: format!(
                "Page object {} {} R is not a dictionary",
                page_ref.0, page_ref.1
            ),
        })?;

        let inherited = self.collect_inherited_attributes(dict);
        self.create_parsed_page(page_ref, dict, Some(&inherited))
    }

    /// Walk up the /Parent chain to collect inheritable attributes (Resources, MediaBox, CropBox, Rotate).
    /// Uses cycle detection to prevent infinite loops in malformed PDFs.
    fn collect_inherited_attributes(&self, page_dict: &PdfDictionary) -> PdfDictionary {
        let mut inherited = PdfDictionary::new();
        let inheritable_keys = ["Resources", "MediaBox", "CropBox", "Rotate"];

        // Collect from the page's own parent chain
        let mut current_parent_ref = page_dict.get("Parent").and_then(|p| p.as_reference());
        let mut visited: std::collections::HashSet<(u32, u16)> = std::collections::HashSet::new();

        while let Some(parent_ref) = current_parent_ref {
            if !visited.insert(parent_ref) {
                break; // Cycle detected
            }

            match self.get_object(parent_ref.0, parent_ref.1) {
                Ok(obj) => {
                    if let Some(parent_dict) = obj.as_dict() {
                        for key in &inheritable_keys {
                            // Only inherit if the page itself doesn't have it
                            // and we haven't already found it in a closer ancestor
                            if !page_dict.contains_key(key) && !inherited.contains_key(key) {
                                if let Some(val) = parent_dict.get(key) {
                                    inherited.insert((*key).to_string(), val.clone());
                                }
                            }
                        }
                        current_parent_ref =
                            parent_dict.get("Parent").and_then(|p| p.as_reference());
                    } else {
                        break;
                    }
                }
                Err(_) => break,
            }
        }

        inherited
    }

    /// Find a page in the page tree (iterative implementation for stack safety)
    fn find_page_in_tree(
        &self,
        root_node: &PdfDictionary,
        target_index: u32,
        initial_current_index: u32,
        initial_inherited: Option<&PdfDictionary>,
    ) -> ParseResult<ParsedPage> {
        // Work item for the traversal queue
        #[derive(Debug)]
        struct WorkItem {
            node_dict: PdfDictionary,
            node_ref: Option<(u32, u16)>,
            current_index: u32,
            inherited: Option<PdfDictionary>,
        }

        // Initialize work queue with root node
        let mut work_queue = Vec::new();
        work_queue.push(WorkItem {
            node_dict: root_node.clone(),
            node_ref: None,
            current_index: initial_current_index,
            inherited: initial_inherited.cloned(),
        });

        // Iterative traversal
        while let Some(work_item) = work_queue.pop() {
            let WorkItem {
                node_dict,
                node_ref,
                current_index,
                inherited,
            } = work_item;

            let node_type = node_dict
                .get_type()
                .or_else(|| {
                    // If Type is missing, try to infer from content
                    if node_dict.contains_key("Kids") && node_dict.contains_key("Count") {
                        Some("Pages")
                    } else if node_dict.contains_key("Contents")
                        || node_dict.contains_key("MediaBox")
                    {
                        Some("Page")
                    } else {
                        None
                    }
                })
                .or_else(|| {
                    // If Type is missing, try to infer from structure
                    if node_dict.contains_key("Kids") {
                        Some("Pages")
                    } else if node_dict.contains_key("Contents")
                        || (node_dict.contains_key("MediaBox") && !node_dict.contains_key("Kids"))
                    {
                        Some("Page")
                    } else {
                        None
                    }
                })
                .ok_or_else(|| ParseError::MissingKey("Type".to_string()))?;

            match node_type {
                "Pages" => {
                    // This is a page tree node
                    let kids = node_dict
                        .get("Kids")
                        .and_then(|obj| obj.as_array())
                        .or_else(|| {
                            // If Kids is missing, use empty array
                            tracing::debug!(
                                "Warning: Missing Kids array in Pages node, using empty array"
                            );
                            Some(&super::objects::EMPTY_PDF_ARRAY)
                        })
                        .ok_or_else(|| ParseError::MissingKey("Kids".to_string()))?;

                    // Merge inherited attributes
                    let mut merged_inherited = inherited.unwrap_or_else(PdfDictionary::new);

                    // Inheritable attributes
                    for key in ["Resources", "MediaBox", "CropBox", "Rotate"] {
                        if let Some(value) = node_dict.get(key) {
                            if !merged_inherited.contains_key(key) {
                                merged_inherited.insert(key.to_string(), value.clone());
                            }
                        }
                    }

                    // Process kids in reverse order (since we're using a stack/Vec::pop())
                    // This ensures we process them in the correct order
                    let mut current_idx = current_index;
                    let mut pending_kids = Vec::new();

                    for kid_ref in &kids.0 {
                        let kid_ref =
                            kid_ref
                                .as_reference()
                                .ok_or_else(|| ParseError::SyntaxError {
                                    position: 0,
                                    message: "Kids array must contain references".to_string(),
                                })?;

                        // Get the kid object
                        let kid_obj = self.get_object(kid_ref.0, kid_ref.1)?;
                        let kid_dict = match kid_obj.as_dict() {
                            Some(dict) => dict,
                            None => {
                                // Skip invalid page tree nodes in lenient mode
                                tracing::debug!(
                                    "Warning: Page tree node {} {} R is not a dictionary, skipping",
                                    kid_ref.0,
                                    kid_ref.1
                                );
                                current_idx += 1; // Count as processed but skip
                                continue;
                            }
                        };

                        let kid_type = kid_dict
                            .get_type()
                            .or_else(|| {
                                // If Type is missing, try to infer from content
                                if kid_dict.contains_key("Kids") && kid_dict.contains_key("Count") {
                                    Some("Pages")
                                } else if kid_dict.contains_key("Contents")
                                    || kid_dict.contains_key("MediaBox")
                                {
                                    Some("Page")
                                } else {
                                    None
                                }
                            })
                            .ok_or_else(|| ParseError::MissingKey("Type".to_string()))?;

                        let count = if kid_type == "Pages" {
                            kid_dict
                                .get("Count")
                                .and_then(|obj| obj.as_integer())
                                .unwrap_or(1) // Fallback to 1 if Count is missing (defensive)
                                as u32
                        } else {
                            1
                        };

                        if target_index < current_idx + count {
                            // Found the right subtree/page
                            if kid_type == "Page" {
                                // This is the page we want
                                return self.create_parsed_page(
                                    kid_ref,
                                    kid_dict,
                                    Some(&merged_inherited),
                                );
                            } else {
                                // Need to traverse this subtree - add to queue
                                pending_kids.push(WorkItem {
                                    node_dict: kid_dict.clone(),
                                    node_ref: Some(kid_ref),
                                    current_index: current_idx,
                                    inherited: Some(merged_inherited.clone()),
                                });
                                break; // Found our target subtree, no need to continue
                            }
                        }

                        current_idx += count;
                    }

                    // Add pending kids to work queue in reverse order for correct processing
                    work_queue.extend(pending_kids.into_iter().rev());
                }
                "Page" => {
                    // This is a page object
                    if target_index != current_index {
                        return Err(ParseError::SyntaxError {
                            position: 0,
                            message: "Page index mismatch".to_string(),
                        });
                    }

                    // We need the reference for creating the parsed page
                    if let Some(page_ref) = node_ref {
                        return self.create_parsed_page(page_ref, &node_dict, inherited.as_ref());
                    } else {
                        return Err(ParseError::SyntaxError {
                            position: 0,
                            message: "Direct page object without reference".to_string(),
                        });
                    }
                }
                _ => {
                    return Err(ParseError::SyntaxError {
                        position: 0,
                        message: format!("Invalid page tree node type: {node_type}"),
                    });
                }
            }
        }

        // Try fallback: search for the page by direct object scanning
        tracing::debug!(
            "Warning: Page {} not found in tree, attempting direct lookup",
            target_index
        );

        // Scan for Page objects directly (try first few hundred objects)
        for obj_num in 1..500 {
            if let Ok(obj) = self.reader.borrow_mut().get_object(obj_num, 0) {
                if let Some(dict) = obj.as_dict() {
                    if let Some(obj_type) = dict.get("Type").and_then(|t| t.as_name()) {
                        if obj_type.0 == "Page" {
                            // Found a page, check if it's the right index (approximate)
                            return self.create_parsed_page((obj_num, 0), dict, None);
                        }
                    }
                }
            }
        }

        Err(ParseError::SyntaxError {
            position: 0,
            message: format!("Page {} not found in tree or document", target_index),
        })
    }

    /// Create a ParsedPage from a page dictionary
    fn create_parsed_page(
        &self,
        obj_ref: (u32, u16),
        page_dict: &PdfDictionary,
        inherited: Option<&PdfDictionary>,
    ) -> ParseResult<ParsedPage> {
        // Extract page attributes with fallback for missing MediaBox
        let media_box = match self.get_rectangle(page_dict, inherited, "MediaBox")? {
            Some(mb) => mb,
            None => {
                // Use default Letter size if MediaBox is missing
                #[cfg(debug_assertions)]
                tracing::debug!(
                    "Warning: Page {} {} R missing MediaBox, using default Letter size",
                    obj_ref.0,
                    obj_ref.1
                );
                [0.0, 0.0, 612.0, 792.0]
            }
        };

        let crop_box = self.get_rectangle(page_dict, inherited, "CropBox")?;

        let rotation = self
            .get_integer(page_dict, inherited, "Rotate")?
            .unwrap_or(0) as i32;

        // Resolve the effective /Resources into an owned dictionary so that
        // `ParsedPage::get_resources()` always yields a dictionary, even when
        // /Resources is given as an indirect reference (issue #286). The page's
        // own /Resources takes precedence over inherited ones; when it is an
        // inline dictionary `get_resources()` returns it directly from the page
        // dict, so we only need a resolved fallback for the reference / inherited
        // cases.
        let inherited_resources = {
            let own_is_inline_dict = page_dict
                .get("Resources")
                .map(|o| o.as_dict().is_some())
                .unwrap_or(false);
            if own_is_inline_dict {
                None
            } else {
                page_dict
                    .get("Resources")
                    .or_else(|| inherited.and_then(|i| i.get("Resources")))
                    .and_then(|r| self.resolve(r).ok())
                    .and_then(|r| r.as_dict().cloned())
            }
        };

        // Get annotations if present
        let annotations = page_dict
            .get("Annots")
            .and_then(|obj| obj.as_array())
            .cloned();

        Ok(ParsedPage {
            obj_ref,
            dict: page_dict.clone(),
            inherited_resources,
            media_box,
            crop_box,
            rotation,
            annotations,
        })
    }

    /// Get a rectangle value
    fn get_rectangle(
        &self,
        node: &PdfDictionary,
        inherited: Option<&PdfDictionary>,
        key: &str,
    ) -> ParseResult<Option<[f64; 4]>> {
        let array = node.get(key).or_else(|| inherited.and_then(|i| i.get(key)));

        if let Some(array) = array.and_then(|obj| obj.as_array()) {
            if array.len() != 4 {
                return Err(ParseError::SyntaxError {
                    position: 0,
                    message: format!("{key} must have 4 elements"),
                });
            }

            // After length check, we know array has exactly 4 elements
            // Safe to index directly without unwrap
            let rect = [
                array.0[0].as_real().unwrap_or(0.0),
                array.0[1].as_real().unwrap_or(0.0),
                array.0[2].as_real().unwrap_or(0.0),
                array.0[3].as_real().unwrap_or(0.0),
            ];

            Ok(Some(rect))
        } else {
            Ok(None)
        }
    }

    /// Get an integer value
    fn get_integer(
        &self,
        node: &PdfDictionary,
        inherited: Option<&PdfDictionary>,
        key: &str,
    ) -> ParseResult<Option<i64>> {
        let value = node.get(key).or_else(|| inherited.and_then(|i| i.get(key)));

        Ok(value.and_then(|obj| obj.as_integer()))
    }

    /// Get an object by its reference numbers.
    ///
    /// This method first checks the cache, then loads from the file if needed.
    /// Objects are automatically cached after loading.
    ///
    /// # Arguments
    ///
    /// * `obj_num` - Object number
    /// * `gen_num` - Generation number
    ///
    /// # Returns
    ///
    /// The resolved PDF object.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - Object doesn't exist
    /// - Object is part of an encrypted object stream
    /// - File is corrupted
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # use oxidize_pdf::parser::objects::PdfObject;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// // Get object 10 0 R
    /// let obj = document.get_object(10, 0)?;
    ///
    /// // Check object type
    /// match obj {
    ///     PdfObject::Dictionary(dict) => {
    ///         println!("Object is a dictionary with {} entries", dict.0.len());
    ///     }
    ///     PdfObject::Stream(stream) => {
    ///         println!("Object is a stream");
    ///     }
    ///     _ => {}
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_object(&self, obj_num: u32, gen_num: u16) -> ParseResult<PdfObject> {
        // Check resource cache first
        if let Some(obj) = self.resources.get_cached((obj_num, gen_num)) {
            return Ok(obj);
        }

        // Load from reader
        let obj = {
            let mut reader = self.reader.borrow_mut();
            reader.get_object(obj_num, gen_num)?.clone()
        };

        // Cache it
        self.resources.cache_object((obj_num, gen_num), obj.clone());

        Ok(obj)
    }

    /// Resolve a reference to get the actual object.
    ///
    /// If the input is a Reference, fetches the referenced object.
    /// Otherwise returns a clone of the input object.
    ///
    /// # Arguments
    ///
    /// * `obj` - The object to resolve (may be a Reference or direct object)
    ///
    /// # Returns
    ///
    /// The resolved object (never a Reference).
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # use oxidize_pdf::parser::objects::PdfObject;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// # let page = document.get_page(0)?;
    /// // Contents might be a reference or direct object
    /// if let Some(contents) = page.dict.get("Contents") {
    ///     let resolved = document.resolve(contents)?;
    ///     match resolved {
    ///         PdfObject::Stream(_) => println!("Single content stream"),
    ///         PdfObject::Array(_) => println!("Multiple content streams"),
    ///         _ => println!("Unexpected content type"),
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn resolve(&self, obj: &PdfObject) -> ParseResult<PdfObject> {
        match obj {
            PdfObject::Reference(obj_num, gen_num) => self.get_object(*obj_num, *gen_num),
            _ => Ok(obj.clone()),
        }
    }

    /// Decode a stream after resolving document-owned `/DecodeParms` references.
    ///
    /// This is the document-aware counterpart to [`PdfStream::decode`]. Use it
    /// when a stream dictionary may contain indirect filter parameter objects.
    ///
    /// # Errors
    ///
    /// Returns an error when a parameter reference is missing, circular, has an
    /// invalid type, or when the underlying filter decoder fails.
    pub fn decode_stream(&self, stream: &PdfStream) -> ParseResult<Vec<u8>> {
        let dict = self.stream_dict_with_resolved_decode_parms(&stream.dict)?;
        super::filters::decode_stream(&stream.data, &dict, &self.options())
    }

    /// Decode a stream with resolved `/DecodeParms` and a maximum output size.
    ///
    /// # Errors
    ///
    /// Returns the same errors as [`Self::decode_stream`], plus an error when a
    /// filter would exceed `max_bytes` or has no bounded decoder.
    pub fn decode_stream_with_limit(
        &self,
        stream: &PdfStream,
        max_bytes: usize,
    ) -> ParseResult<Vec<u8>> {
        let dict = self.stream_dict_with_resolved_decode_parms(&stream.dict)?;
        super::filters::decode_stream_with_limit(&stream.data, &dict, &self.options(), max_bytes)
    }

    fn stream_dict_with_resolved_decode_parms(
        &self,
        dict: &PdfDictionary,
    ) -> ParseResult<PdfDictionary> {
        let Some(decode_parms) = dict.get("DecodeParms") else {
            return Ok(dict.clone());
        };
        let mut resolved_dict = dict.clone();
        let resolved = match decode_parms {
            PdfObject::Array(array) => PdfObject::Array(super::objects::PdfArray(
                array
                    .0
                    .iter()
                    .map(|entry| self.resolve_decode_parms_entry(entry, true))
                    .collect::<ParseResult<Vec<_>>>()?,
            )),
            other => self.resolve_decode_parms_entry(other, false)?,
        };
        resolved_dict.insert("DecodeParms".into(), resolved);
        Ok(resolved_dict)
    }

    fn resolve_decode_parms_entry(
        &self,
        object: &PdfObject,
        array_entry: bool,
    ) -> ParseResult<PdfObject> {
        let mut current = object.clone();
        let mut visited = HashSet::new();
        let mut resolved_reference = false;
        while let PdfObject::Reference(object_number, generation) = current {
            resolved_reference = true;
            if !visited.insert((object_number, generation)) {
                return Err(ParseError::CircularReference);
            }
            if visited.len() > super::stack_safe::MAX_RECURSION_DEPTH {
                return Err(ParseError::SyntaxError {
                    position: 0,
                    message: "DecodeParms reference chain exceeds maximum depth".into(),
                });
            }
            current = self.get_object(object_number, generation)?;
        }
        match current {
            PdfObject::Dictionary(_) => Ok(current),
            PdfObject::Null if !resolved_reference => Ok(current),
            PdfObject::Array(array) if !array_entry => {
                Ok(PdfObject::Array(super::objects::PdfArray(
                    array
                        .0
                        .iter()
                        .map(|entry| self.resolve_decode_parms_entry(entry, true))
                        .collect::<ParseResult<Vec<_>>>()?,
                )))
            }
            _ => Err(ParseError::SyntaxError {
                position: 0,
                message: "DecodeParms must resolve to a dictionary, null, or an array of those"
                    .into(),
            }),
        }
    }

    /// Get content streams for a specific page.
    ///
    /// This method handles both single streams and arrays of streams,
    /// automatically decompressing them according to their filters.
    ///
    /// # Arguments
    ///
    /// * `page` - The page to get content streams from
    ///
    /// # Returns
    ///
    /// Vector of decompressed content stream data ready for parsing.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # use oxidize_pdf::parser::content::ContentParser;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let page = document.get_page(0)?;
    /// let streams = document.get_page_content_streams(&page)?;
    ///
    /// // Parse content streams
    /// for stream_data in streams {
    ///     let operations = ContentParser::parse(&stream_data)?;
    ///     println!("Stream has {} operations", operations.len());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    /// Get page resources dictionary.
    ///
    /// This method returns the resources dictionary for a page, which may include
    /// fonts, images (XObjects), patterns, color spaces, and other resources.
    ///
    /// # Arguments
    ///
    /// * `page` - The page to get resources from
    ///
    /// # Returns
    ///
    /// Optional resources dictionary if the page has resources.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader, PdfObject, PdfName};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let page = document.get_page(0)?;
    /// if let Some(resources) = document.get_page_resources(&page)? {
    ///     // Check for images (XObjects)
    ///     if let Some(PdfObject::Dictionary(xobjects)) = resources.0.get(&PdfName("XObject".to_string())) {
    ///         for (name, _) in xobjects.0.iter() {
    ///             println!("Found XObject: {}", name.0);
    ///         }
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_page_resources<'a>(
        &self,
        page: &'a ParsedPage,
    ) -> ParseResult<Option<&'a PdfDictionary>> {
        Ok(page.get_resources())
    }

    pub fn get_page_content_streams(&self, page: &ParsedPage) -> ParseResult<Vec<Vec<u8>>> {
        let mut streams = Vec::new();

        if let Some(contents) = page.dict.get("Contents") {
            let resolved_contents = self.resolve(contents)?;

            match &resolved_contents {
                PdfObject::Stream(stream) => {
                    streams.push(self.decode_stream(stream)?);
                }
                PdfObject::Array(array) => {
                    for item in &array.0 {
                        let resolved = self.resolve(item)?;
                        if let PdfObject::Stream(stream) = resolved {
                            streams.push(self.decode_stream(&stream)?);
                        }
                    }
                }
                _ => {
                    return Err(ParseError::SyntaxError {
                        position: 0,
                        message: "Contents must be a stream or array of streams".to_string(),
                    })
                }
            }
        }

        Ok(streams)
    }

    /// Extract text from all pages in the document.
    ///
    /// Uses the default text extraction settings. For custom settings,
    /// use `extract_text_with_options`.
    ///
    /// # Returns
    ///
    /// A vector of `ExtractedText`, one for each page in the document.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let extracted_pages = document.extract_text()?;
    ///
    /// for (page_num, page_text) in extracted_pages.iter().enumerate() {
    ///     println!("=== Page {} ===", page_num + 1);
    ///     println!("{}", page_text.text);
    ///     println!();
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn extract_text(&self) -> ParseResult<Vec<crate::text::ExtractedText>> {
        let mut extractor = crate::text::TextExtractor::new();
        extractor.extract_from_document(self)
    }

    /// Extract text from a specific page.
    ///
    /// # Arguments
    ///
    /// * `page_index` - Zero-based page index
    ///
    /// # Returns
    ///
    /// Extracted text with optional position information.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// // Extract text from first page only
    /// let page_text = document.extract_text_from_page(0)?;
    /// println!("First page text: {}", page_text.text);
    ///
    /// // Access text fragments with positions (if preserved)
    /// for fragment in &page_text.fragments {
    ///     println!("'{}' at ({}, {})", fragment.text, fragment.x, fragment.y);
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn extract_text_from_page(
        &self,
        page_index: u32,
    ) -> ParseResult<crate::text::ExtractedText> {
        let mut extractor = crate::text::TextExtractor::new();
        extractor.extract_from_page(self, page_index)
    }

    /// Extract text from a specific page with custom options.
    ///
    /// This method combines the functionality of [`extract_text_from_page`] and
    /// [`extract_text_with_options`], allowing fine control over extraction
    /// behavior for a single page.
    ///
    /// # Arguments
    ///
    /// * `page_index` - Zero-based page index
    /// * `options` - Text extraction configuration
    ///
    /// # Returns
    ///
    /// Extracted text with optional position information.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # use oxidize_pdf::text::ExtractionOptions;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// // Use higher space threshold for PDFs with micro-adjustments
    /// let options = ExtractionOptions {
    ///     space_threshold: 0.4,
    ///     ..Default::default()
    /// };
    ///
    /// let page_text = document.extract_text_from_page_with_options(0, options)?;
    /// println!("Text: {}", page_text.text);
    /// # Ok(())
    /// # }
    /// ```
    pub fn extract_text_from_page_with_options(
        &self,
        page_index: u32,
        options: crate::text::ExtractionOptions,
    ) -> ParseResult<crate::text::ExtractedText> {
        let mut extractor = crate::text::TextExtractor::with_options(options);
        extractor.extract_from_page(self, page_index)
    }

    /// Extract text with custom extraction options.
    ///
    /// Allows fine control over text extraction behavior including
    /// layout preservation, spacing thresholds, and more.
    ///
    /// # Arguments
    ///
    /// * `options` - Text extraction configuration
    ///
    /// # Returns
    ///
    /// A vector of `ExtractedText`, one for each page.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # use oxidize_pdf::text::ExtractionOptions;
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// // Configure extraction to preserve layout
    /// let options = ExtractionOptions {
    ///     preserve_layout: true,
    ///     space_threshold: 0.3,
    ///     newline_threshold: 10.0,
    ///     ..Default::default()
    /// };
    ///
    /// let extracted_pages = document.extract_text_with_options(options)?;
    ///
    /// // Text fragments will include position information
    /// for page_text in extracted_pages {
    ///     for fragment in &page_text.fragments {
    ///         println!("{:?}", fragment);
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn extract_text_with_options(
        &self,
        options: crate::text::ExtractionOptions,
    ) -> ParseResult<Vec<crate::text::ExtractedText>> {
        let mut extractor = crate::text::TextExtractor::with_options(options);
        extractor.extract_from_document(self)
    }

    /// Get annotations from a specific page.
    ///
    /// Returns a vector of annotation dictionaries for the specified page.
    /// Each annotation dictionary contains properties like Type, Rect, Contents, etc.
    ///
    /// # Arguments
    ///
    /// * `page_index` - Zero-based page index
    ///
    /// # Returns
    ///
    /// A vector of PdfDictionary objects representing annotations, or an empty vector
    /// if the page has no annotations.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let annotations = document.get_page_annotations(0)?;
    /// for annot in &annotations {
    ///     if let Some(contents) = annot.get("Contents").and_then(|c| c.as_string()) {
    ///         println!("Annotation: {:?}", contents);
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_page_annotations(&self, page_index: u32) -> ParseResult<Vec<PdfDictionary>> {
        let page = self.get_page(page_index)?;

        if let Some(annots_array) = page.get_annotations() {
            let mut annotations = Vec::new();
            let mut reader = self.reader.borrow_mut();

            for annot_ref in &annots_array.0 {
                if let Some(ref_nums) = annot_ref.as_reference() {
                    match reader.get_object(ref_nums.0, ref_nums.1) {
                        Ok(obj) => {
                            if let Some(dict) = obj.as_dict() {
                                annotations.push(dict.clone());
                            }
                        }
                        Err(_) => {
                            // Skip annotations that can't be loaded
                            continue;
                        }
                    }
                }
            }

            Ok(annotations)
        } else {
            Ok(Vec::new())
        }
    }

    /// Get all annotations from all pages in the document.
    ///
    /// Returns a vector of tuples containing (page_index, annotations) for each page
    /// that has annotations.
    ///
    /// # Returns
    ///
    /// A vector of tuples where the first element is the page index and the second
    /// is a vector of annotation dictionaries for that page.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// # let reader = PdfReader::open("document.pdf")?;
    /// # let document = PdfDocument::new(reader);
    /// let all_annotations = document.get_all_annotations()?;
    /// for (page_idx, annotations) in all_annotations {
    ///     println!("Page {} has {} annotations", page_idx, annotations.len());
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn get_all_annotations(&self) -> ParseResult<Vec<(u32, Vec<PdfDictionary>)>> {
        let page_count = self.page_count()?;
        let mut all_annotations = Vec::new();

        for i in 0..page_count {
            let annotations = self.get_page_annotations(i)?;
            if !annotations.is_empty() {
                all_annotations.push((i, annotations));
            }
        }

        Ok(all_annotations)
    }

    // --- VibeCoding Facade Methods ---

    /// Export the document to LLM-optimized Markdown format.
    ///
    /// Delegates to [`crate::ai::export_to_markdown`]. Includes YAML frontmatter
    /// with document metadata followed by extracted text content.
    #[allow(deprecated)]
    pub fn to_markdown(&self) -> crate::error::Result<String> {
        crate::ai::export_to_markdown(self)
    }

    /// Export the document to element-aware Markdown format.
    ///
    /// Unlike [`to_markdown`](Self::to_markdown), this method classifies elements
    /// by type and maps each to its canonical Markdown representation.
    pub fn to_element_markdown(&self) -> ParseResult<String> {
        let elements = self.partition()?;
        let exporter = crate::pipeline::export::ElementMarkdownExporter::default();
        Ok(exporter.export(&elements))
    }

    /// Export the document to a contextual text format for LLM consumption.
    ///
    /// Delegates to [`crate::ai::export_to_contextual`].
    #[allow(deprecated)]
    pub fn to_contextual(&self) -> crate::error::Result<String> {
        crate::ai::export_to_contextual(self)
    }

    /// Export the document to structured JSON format.
    ///
    /// Requires the `semantic` feature. Delegates to [`crate::ai::export_to_json`].
    #[cfg(feature = "semantic")]
    #[allow(deprecated)]
    pub fn to_json(&self) -> crate::error::Result<String> {
        crate::ai::export_to_json(self)
    }

    /// Extract and chunk the document into RAG-ready chunks with full metadata.
    ///
    /// Uses default [`HybridChunkConfig`](crate::pipeline::HybridChunkConfig)
    /// (512 tokens, `AnyInlineContent` merge policy). Returns serializable
    /// [`RagChunk`](crate::pipeline::RagChunk)s with page numbers, bounding boxes,
    /// element types, and heading context — everything a vector store needs.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::{PdfDocument, PdfReader};
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let chunks = doc.rag_chunks()?;
    /// for chunk in &chunks {
    ///     println!("Chunk {}: pages {:?}, ~{} tokens",
    ///         chunk.chunk_index, chunk.page_numbers, chunk.token_estimate);
    /// }
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks(&self) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        self.rag_chunks_with(crate::pipeline::HybridChunkConfig::default())
    }

    /// Extract and chunk the document with a custom chunking configuration.
    ///
    /// Use this when the default 512-token limit is too large or too small for your
    /// vector store or embedding model. All other metadata (pages, bounding boxes,
    /// element types, heading context) is identical to [`rag_chunks()`](Self::rag_chunks).
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::{PdfDocument, PdfReader};
    /// use oxidize_pdf::pipeline::HybridChunkConfig;
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let config = HybridChunkConfig {
    ///     max_tokens: 256,
    ///     ..HybridChunkConfig::default()
    /// };
    /// let chunks = doc.rag_chunks_with(config)?;
    /// println!("Got {} chunks at 256-token limit", chunks.len());
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks_with(
        &self,
        config: crate::pipeline::HybridChunkConfig,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let elements = self.partition()?;
        let context_mode = config.context_mode;
        let chunker = crate::pipeline::HybridChunker::new(config);
        let hybrid_chunks = chunker.chunk(&elements);
        Ok(self.build_rag_chunks(&hybrid_chunks, None, context_mode))
    }

    /// Extract and chunk with a custom [`TokenCounter`](crate::pipeline::TokenCounter).
    ///
    /// Identical to [`rag_chunks_with`](Self::rag_chunks_with) except the injected
    /// counter governs both the chunk split/size decisions and the reported
    /// `token_estimate` on each [`RagChunk`](crate::pipeline::RagChunk). Use with
    /// [`TiktokenCounter`](crate::pipeline::TiktokenCounter) (feature `tiktoken`)
    /// to size chunks against a real subword tokenizer.
    ///
    /// Note: this flows through [`HybridChunker`](crate::pipeline::HybridChunker).
    /// The `unstable-spi` pipeline entry points (`rag_chunks_with_pipeline` /
    /// `rag_chunks_from_elements`) remain word-proxy only.
    pub fn rag_chunks_with_counter(
        &self,
        config: crate::pipeline::HybridChunkConfig,
        counter: std::sync::Arc<dyn crate::pipeline::TokenCounter>,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let elements = self.partition()?;
        let context_mode = config.context_mode;
        let chunker = crate::pipeline::HybridChunker::new(config).with_token_counter(counter);
        let hybrid_chunks = chunker.chunk(&elements);
        Ok(self.build_rag_chunks(&hybrid_chunks, None, context_mode))
    }

    /// Build RAG chunks stamped with source-document metadata.
    ///
    /// Auto-fills `title`/`author`/`creation_date`/`total_pages` from the info
    /// dictionary (only where the caller left them `None`); the caller-supplied
    /// `source` provides `filename`/`doc_hash` (and may override any auto-filled
    /// field). `doc_hash`, when set, becomes the stable prefix of every
    /// `chunk_id`. Same chunking pipeline as [`rag_chunks`](Self::rag_chunks).
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    /// use oxidize_pdf::pipeline::DocumentSource;
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let mut source = DocumentSource::default();
    /// source.filename = Some("document.pdf".to_string());
    /// source.doc_hash = Some("sha256-prefix".to_string());
    /// let chunks = doc.rag_chunks_with_source(source)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks_with_source(
        &self,
        source: crate::pipeline::DocumentSource,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        self.rag_chunks_with_source_and_config(
            source,
            crate::pipeline::HybridChunkConfig::default(),
        )
    }

    /// Like [`rag_chunks_with_source`](Self::rag_chunks_with_source) but with a
    /// custom chunking configuration — for callers that need both
    /// source-document stamping and a non-default token budget.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    /// use oxidize_pdf::pipeline::{DocumentSource, HybridChunkConfig};
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let source = DocumentSource::with_file(Some("document.pdf".into()), None);
    /// let config = HybridChunkConfig { max_tokens: 256, ..Default::default() };
    /// let chunks = doc.rag_chunks_with_source_and_config(source, config)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks_with_source_and_config(
        &self,
        mut source: crate::pipeline::DocumentSource,
        config: crate::pipeline::HybridChunkConfig,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        self.autofill_source(&mut source);
        let elements = self.partition()?;
        let context_mode = config.context_mode;
        let chunker = crate::pipeline::HybridChunker::new(config);
        let hybrid_chunks = chunker.chunk(&elements);
        Ok(self.build_rag_chunks(&hybrid_chunks, Some(source), context_mode))
    }

    /// Fill `title`/`author`/`creation_date`/`total_pages` from the info
    /// dictionary where the caller left them `None`.
    fn autofill_source(&self, source: &mut crate::pipeline::DocumentSource) {
        if let Ok(meta) = self.metadata() {
            source.title = source.title.take().or(meta.title);
            source.author = source.author.take().or(meta.author);
            source.creation_date = source.creation_date.take().or(meta.creation_date);
            source.total_pages = source.total_pages.or(meta.page_count);
        }
        if source.total_pages.is_none() {
            source.total_pages = self.page_count().ok();
        }
    }

    /// Run a custom [`AnalysisPipeline`](crate::pipeline::AnalysisPipeline):
    /// partition, optionally classify elements, apply the pipeline's chunking
    /// strategy, build linked `RagChunk`s (ids, prev/next, metadata, optional
    /// source) exactly as the other `rag_chunks*` entry points do, then run any
    /// enrichers over each chunk's `extra` bag.
    ///
    /// `AnalysisPipeline::new()` reproduces [`rag_chunks`](Self::rag_chunks).
    ///
    /// Partitioning uses the pipeline's
    /// [`PartitionConfig`](crate::pipeline::PartitionConfig) (default unless set
    /// via [`with_partition_config`](crate::pipeline::AnalysisPipeline::with_partition_config)),
    /// so a structure-aware consumer can override the table detector when it
    /// misclassifies the document (issue #345).
    ///
    /// **Stability:** requires `unstable-spi`; exempt from semver until promoted.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// # use oxidize_pdf::parser::PdfDocument;
    /// # use oxidize_pdf::pipeline::AnalysisPipeline;
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let doc = PdfDocument::open("document.pdf")?;
    /// // Default pipeline == rag_chunks(); swap in a custom strategy/classifier/
    /// // enricher via the builder to extend it.
    /// let chunks = doc.rag_chunks_with_pipeline(&AnalysisPipeline::new())?;
    /// println!("{} chunks", chunks.len());
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "unstable-spi")]
    pub fn rag_chunks_with_pipeline(
        &self,
        pipeline: &crate::pipeline::AnalysisPipeline,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let elements = self.partition_with(pipeline.partition_config.clone())?;
        self.rag_chunks_from_elements(elements, pipeline)
    }

    /// Run a custom [`AnalysisPipeline`](crate::pipeline::AnalysisPipeline)
    /// (classify → chunk → enrich) over **caller-provided** elements, instead of
    /// the document's own partition.
    ///
    /// This is the element-source seam behind
    /// [`rag_chunks_with_pipeline`](Self::rag_chunks_with_pipeline), which is
    /// exactly `self.rag_chunks_from_elements(self.partition_with(cfg)?, pipeline)`.
    /// Use it to feed externally-recovered elements (e.g. list items a two-column
    /// layout scrambles past the partitioner) into the same enriched chunk flow
    /// as the rest of the document — with uniform classification and enrichment,
    /// avoiding the `RagChunk` metadata-stamping workaround that bypasses both
    /// (issue #360). Partitioned and recovered elements can be mixed freely.
    ///
    /// The pipeline's [`PartitionConfig`](crate::pipeline::PartitionConfig) is not
    /// consulted here — the caller has already chosen the elements. The pipeline's
    /// [`source`](crate::pipeline::AnalysisPipeline::with_source), when set, is
    /// still autofilled from this document (title/author/page count) and stamped
    /// onto the chunks, exactly as in `rag_chunks_with_pipeline`.
    ///
    /// **Stability:** requires `unstable-spi`; exempt from semver until promoted.
    #[cfg(feature = "unstable-spi")]
    pub fn rag_chunks_from_elements(
        &self,
        mut elements: Vec<crate::pipeline::Element>,
        pipeline: &crate::pipeline::AnalysisPipeline,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let mut source = pipeline.source.clone();
        if let Some(src) = source.as_mut() {
            self.autofill_source(src);
        }
        if let Some(classifier) = pipeline.classifier.as_deref() {
            // Two passes: read labels against an immutable slice, then apply —
            // the classifier inspects neighbours via `ClassifyContext`, so it
            // cannot run while the slice is being mutated.
            let labels: Vec<Option<crate::pipeline::ClassLabel>> = (0..elements.len())
                .map(|index| {
                    let ctx = crate::pipeline::ClassifyContext {
                        elements: &elements,
                        index,
                    };
                    classifier.classify(&elements[index], &ctx)
                })
                .collect();
            for (element, label) in elements.iter_mut().zip(labels) {
                if let Some(label) = label {
                    element.metadata_mut().class_label = Some(label.0.into_owned());
                }
            }
        }
        let groups = pipeline.chunking.chunk(&elements);
        let hybrid: Vec<crate::pipeline::HybridChunk> = groups
            .into_iter()
            .map(|g| crate::pipeline::HybridChunk::from_group(g, pipeline.max_tokens))
            .collect();
        // `mut` is needed only for the enricher pass below (gated `semantic`);
        // without that feature the binding is never mutated — silence the warning.
        #[allow(unused_mut)]
        let mut chunks = self.build_rag_chunks(&hybrid, source, pipeline.context_mode);
        #[cfg(feature = "semantic")]
        if !pipeline.enrichers.is_empty() {
            // Enrich each chunk's `extra` bag. The hybrid chunk (kept alongside)
            // supplies the source elements; text/heading_path are snapshotted to
            // release the immutable borrow before mutating `metadata`.
            for (chunk, hc) in chunks.iter_mut().zip(hybrid.iter()) {
                let text = chunk.text.clone();
                let heading_path = chunk.metadata.heading_path.clone();
                let ctx = crate::pipeline::EnrichContext {
                    text: &text,
                    elements: hc.elements(),
                    heading_path: &heading_path,
                };
                for enricher in &pipeline.enrichers {
                    enricher.enrich(&ctx, &mut chunk.metadata);
                }
            }
        }
        Ok(chunks)
    }

    /// Build linked [`RagChunk`]s from hybrid chunks, optionally stamping a
    /// [`DocumentSource`](crate::pipeline::DocumentSource), then wiring
    /// prev/next ids. Shared by all `rag_chunks*` entry points (DRY).
    fn build_rag_chunks(
        &self,
        hybrid_chunks: &[crate::pipeline::HybridChunk],
        source: Option<crate::pipeline::DocumentSource>,
        context_mode: crate::pipeline::ContextMode,
    ) -> Vec<crate::pipeline::RagChunk> {
        let mut chunks: Vec<crate::pipeline::RagChunk> = match &source {
            Some(s) => hybrid_chunks
                .iter()
                .enumerate()
                .map(|(i, hc)| {
                    crate::pipeline::RagChunk::from_hybrid_chunk_with_source_and_mode(
                        i,
                        hc,
                        s,
                        context_mode,
                    )
                })
                .collect(),
            None => hybrid_chunks
                .iter()
                .enumerate()
                .map(|(i, hc)| {
                    crate::pipeline::RagChunk::from_hybrid_chunk_with_mode(i, hc, context_mode)
                })
                .collect(),
        };
        crate::pipeline::chunk_metadata::link_chunks(&mut chunks);
        chunks
    }

    /// Extract and chunk the document using a pre-configured extraction profile.
    ///
    /// Combines [`partition_with_profile`](Self::partition_with_profile) with
    /// [`HybridChunker`](crate::pipeline::HybridChunker) using default chunking
    /// settings. Use [`rag_chunks_with`](Self::rag_chunks_with) when you need
    /// to tune `max_tokens` or `overlap_tokens`.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    /// use oxidize_pdf::pipeline::ExtractionProfile;
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let chunks = doc.rag_chunks_with_profile(ExtractionProfile::Rag)?;
    /// println!("Got {} RAG chunks", chunks.len());
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks_with_profile(
        &self,
        profile: crate::pipeline::ExtractionProfile,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let elements = self.partition_with_profile(profile)?;
        let chunker = crate::pipeline::HybridChunker::default();
        let hybrid_chunks = chunker.chunk(&elements);
        Ok(self.build_rag_chunks(&hybrid_chunks, None, crate::pipeline::ContextMode::Heading))
    }

    /// Combine a pre-configured extraction profile with a custom chunking config.
    ///
    /// Use this when you need both profile-tuned partitioning (e.g. `Rag` with
    /// XYCut reading order) and a non-default chunk size.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    /// use oxidize_pdf::pipeline::{ExtractionProfile, HybridChunkConfig};
    ///
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let config = HybridChunkConfig { max_tokens: 256, ..Default::default() };
    /// let chunks = doc.rag_chunks_with_profile_config(ExtractionProfile::Rag, config)?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// ```
    pub fn rag_chunks_with_profile_config(
        &self,
        profile: crate::pipeline::ExtractionProfile,
        config: crate::pipeline::HybridChunkConfig,
    ) -> ParseResult<Vec<crate::pipeline::RagChunk>> {
        let elements = self.partition_with_profile(profile)?;
        let context_mode = config.context_mode;
        let chunker = crate::pipeline::HybridChunker::new(config);
        let hybrid_chunks = chunker.chunk(&elements);
        Ok(self.build_rag_chunks(&hybrid_chunks, None, context_mode))
    }

    /// Extract chunks as a JSON string ready for vector store ingestion.
    ///
    /// # Feature flags
    ///
    /// Requires the `semantic` feature: `oxidize-pdf = { features = ["semantic"] }`.
    /// Without it this method is not compiled.
    #[cfg(feature = "semantic")]
    pub fn rag_chunks_json(&self) -> ParseResult<String> {
        let chunks = self.rag_chunks()?;
        serde_json::to_string(&chunks).map_err(|e| ParseError::SerializationError(e.to_string()))
    }

    /// Split the document text into chunks of approximately `target_tokens` size.
    ///
    /// Uses a default overlap of 10% of the target token count.
    #[deprecated(
        since = "2.2.0",
        note = "Use rag_chunks() for structure-aware RAG chunking"
    )]
    #[allow(deprecated)]
    pub fn chunk(
        &self,
        target_tokens: usize,
    ) -> crate::error::Result<Vec<crate::ai::DocumentChunk>> {
        let overlap = target_tokens / 10;
        self.chunk_with(target_tokens, overlap)
    }

    /// Split the document text into chunks with explicit size and overlap control.
    #[deprecated(
        since = "2.2.0",
        note = "Use rag_chunks_with() for structure-aware RAG chunking"
    )]
    pub fn chunk_with(
        &self,
        target_tokens: usize,
        overlap: usize,
    ) -> crate::error::Result<Vec<crate::ai::DocumentChunk>> {
        let chunker = crate::ai::DocumentChunker::new(target_tokens, overlap);
        let extracted = self.extract_text()?;
        let page_texts: Vec<(usize, String)> = extracted
            .iter()
            .enumerate()
            .map(|(i, t)| (i + 1, t.text.clone()))
            .collect();
        chunker
            .chunk_text_with_pages(&page_texts)
            .map_err(|e| crate::error::PdfError::InvalidStructure(e.to_string()))
    }

    /// Partition the document into typed elements using default configuration.
    ///
    /// Extracts text with layout preservation, then classifies fragments into
    /// [`Element`](crate::pipeline::Element) variants (Title, Paragraph, Table, etc.).
    pub fn partition(&self) -> ParseResult<Vec<crate::pipeline::Element>> {
        self.partition_with(crate::pipeline::PartitionConfig::default())
    }

    /// Partition the document into typed elements with custom configuration.
    pub fn partition_with(
        &self,
        config: crate::pipeline::PartitionConfig,
    ) -> ParseResult<Vec<crate::pipeline::Element>> {
        let options = crate::text::ExtractionOptions {
            preserve_layout: true,
            reconstruct_paragraphs: true,
            ..Default::default()
        };
        self.do_partition_pages(options, config)
    }

    /// Partition the document using a pre-configured extraction profile.
    pub fn partition_with_profile(
        &self,
        profile: crate::pipeline::ExtractionProfile,
    ) -> ParseResult<Vec<crate::pipeline::Element>> {
        let profile_cfg = profile.config();
        let options = crate::text::ExtractionOptions {
            preserve_layout: true,
            reconstruct_paragraphs: true,
            space_threshold: profile_cfg.extraction.space_threshold,
            detect_columns: profile_cfg.extraction.detect_columns,
            ..crate::text::ExtractionOptions::default()
        };
        self.do_partition_pages(options, profile_cfg.partition)
    }

    fn do_partition_pages(
        &self,
        options: crate::text::ExtractionOptions,
        config: crate::pipeline::PartitionConfig,
    ) -> ParseResult<Vec<crate::pipeline::Element>> {
        // Read the gating flags before `config` is moved into the partitioner,
        // so we avoid cloning the config just to inspect two bools.
        let extract_graphics = config.detect_tables && config.prefer_ruling_tables;

        // The reconstructed `pages` (extracted with `reconstruct_paragraphs = true`)
        // merge per-cell fragments into paragraph-granular fragments (issue #261),
        // which the ruling-based table detector cannot map back to grid cells. When
        // a page actually has a drawn table grid we re-extract just that page with
        // `reconstruct_paragraphs = false` to recover cell-granular fragments for
        // the detector; the reconstructed fragments still drive prose
        // classification. Inherit every other option (notably `space_threshold`
        // and `detect_columns`, which profiles override) so cell text is assembled
        // identically to the primary pass. Built before `options` is moved into
        // `extract_text_with_options`.
        let mut raw_options = options.clone();
        raw_options.reconstruct_paragraphs = false;

        let pages = self.extract_text_with_options(options)?;

        let partitioner = crate::pipeline::Partitioner::new(config);
        let mut graphics_extractor = crate::graphics::extraction::GraphicsExtractor::default();
        // Extracting per table-bearing page (rather than a second whole-document
        // pass) keeps the cost proportional to pages that need it and zero for
        // table-free documents even with `prefer_ruling_tables` on.
        let mut raw_extractor = crate::text::TextExtractor::with_options(raw_options);

        let mut all_elements = Vec::new();
        for (page_idx, page_text) in pages.iter().enumerate() {
            let page_idx_u32 = u32::try_from(page_idx).map_err(|_| ParseError::SyntaxError {
                position: 0,
                message: format!("Page index {} exceeds u32 range", page_idx),
            })?;
            let page_height = self
                .get_page(page_idx_u32)
                .map(|p| p.height())
                .unwrap_or(842.0);
            let page_graphics = if extract_graphics {
                graphics_extractor.extract_from_page(self, page_idx).ok()
            } else {
                None
            };
            // Re-extract cell-granular fragments only for pages with a drawn grid.
            let raw_page = if page_graphics
                .as_ref()
                .is_some_and(|g| g.has_table_structure())
            {
                raw_extractor.extract_from_page(self, page_idx_u32).ok()
            } else {
                None
            };
            let raw_fragments = raw_page.as_ref().map(|pt| pt.fragments.as_slice());
            let elements = partitioner.partition_fragments_with_graphics_raw(
                &page_text.fragments,
                raw_fragments,
                page_graphics.as_ref(),
                page_idx_u32,
                page_height,
            );
            all_elements.extend(elements);
        }

        Ok(all_elements)
    }

    /// Partition the document into typed elements and build a relationship graph.
    ///
    /// Returns a tuple of `(elements, graph)` where the graph captures parent/child
    /// and next/prev relationships between elements by index.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    /// use oxidize_pdf::pipeline::PartitionConfig;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let doc = PdfDocument::open("document.pdf")?;
    /// let (elements, graph) = doc.partition_graph(PartitionConfig::default())?;
    ///
    /// for title_idx in graph.top_level_sections() {
    ///     println!("Section: {}", elements[title_idx].text());
    ///     for child_idx in graph.elements_in_section(title_idx) {
    ///         println!("  {}", elements[child_idx].text());
    ///     }
    /// }
    /// # Ok(())
    /// # }
    /// ```
    pub fn partition_graph(
        &self,
        config: crate::pipeline::PartitionConfig,
    ) -> ParseResult<(Vec<crate::pipeline::Element>, crate::pipeline::ElementGraph)> {
        let elements = self.partition_with(config)?;
        let graph = crate::pipeline::ElementGraph::build(&elements);
        Ok((elements, graph))
    }
}

impl PdfDocument<File> {
    /// Open a PDF file by path — the simplest way to start working with a PDF.
    ///
    /// This is a convenience method that combines `PdfReader::open()` and
    /// `PdfDocument::new()` into a single call.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::PdfDocument;
    ///
    /// let doc = PdfDocument::open("report.pdf").unwrap();
    /// let text = doc.extract_text().unwrap();
    /// let markdown = doc.to_markdown().unwrap();
    /// ```
    pub fn open<P: AsRef<Path>>(path: P) -> ParseResult<Self> {
        PdfReader::open_document(path)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::parser::objects::{PdfObject, PdfString};
    use std::io::Cursor;

    // Issue #369: PdfDocument<R> must be Send so callers (e.g. the PyO3
    // bindings) can release a thread-blocking lock around reader operations.
    #[test]
    fn test_pdf_document_is_send() {
        fn assert_send<T: Send>() {}
        assert_send::<PdfDocument<std::fs::File>>();
        assert_send::<PdfDocument<Cursor<Vec<u8>>>>();
        assert_send::<PdfDocument<Cursor<&'static [u8]>>>();
    }

    // Issue #369: dropping the unshared Rc must not change cache behavior.
    #[test]
    fn test_resource_cache_roundtrip_after_owned_field() {
        let rm = ResourceManager::new();
        assert!(rm.get_cached((7, 0)).is_none());
        rm.cache_object((7, 0), PdfObject::Integer(42));
        assert_eq!(rm.get_cached((7, 0)), Some(PdfObject::Integer(42)));
        rm.clear_cache();
        assert!(rm.get_cached((7, 0)).is_none());
    }

    // Helper function to create a minimal PDF in memory
    fn create_minimal_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();

        // PDF header
        pdf.extend_from_slice(b"%PDF-1.4\n");

        // Catalog object
        pdf.extend_from_slice(b"1 0 obj\n");
        pdf.extend_from_slice(b"<< /Type /Catalog /Pages 2 0 R >>\n");
        pdf.extend_from_slice(b"endobj\n");

        // Pages object
        pdf.extend_from_slice(b"2 0 obj\n");
        pdf.extend_from_slice(b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>\n");
        pdf.extend_from_slice(b"endobj\n");

        // Page object
        pdf.extend_from_slice(b"3 0 obj\n");
        pdf.extend_from_slice(
            b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << >> >>\n",
        );
        pdf.extend_from_slice(b"endobj\n");

        // Cross-reference table
        let xref_pos = 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 \n");
        pdf.extend_from_slice(b"0000000009 00000 n \n");
        pdf.extend_from_slice(b"0000000058 00000 n \n");
        pdf.extend_from_slice(b"0000000115 00000 n \n");

        // Trailer
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(b"startxref\n");
        pdf.extend_from_slice(format!("{xref_pos}\n").as_bytes());
        pdf.extend_from_slice(b"%%EOF\n");

        pdf
    }

    // Helper to create a PDF with metadata
    fn create_pdf_with_metadata() -> Vec<u8> {
        let mut pdf = Vec::new();

        // PDF header
        pdf.extend_from_slice(b"%PDF-1.5\n");

        // Record positions for xref
        let obj1_pos = pdf.len();

        // Catalog object
        pdf.extend_from_slice(b"1 0 obj\n");
        pdf.extend_from_slice(b"<< /Type /Catalog /Pages 2 0 R >>\n");
        pdf.extend_from_slice(b"endobj\n");

        let obj2_pos = pdf.len();

        // Pages object
        pdf.extend_from_slice(b"2 0 obj\n");
        pdf.extend_from_slice(b"<< /Type /Pages /Kids [] /Count 0 >>\n");
        pdf.extend_from_slice(b"endobj\n");

        let obj3_pos = pdf.len();

        // Info object
        pdf.extend_from_slice(b"3 0 obj\n");
        pdf.extend_from_slice(
            b"<< /Title (Test Document) /Author (Test Author) /Subject (Test Subject) >>\n",
        );
        pdf.extend_from_slice(b"endobj\n");

        // Cross-reference table
        let xref_pos = 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 \n");
        pdf.extend_from_slice(format!("{obj1_pos:010} 00000 n \n").as_bytes());
        pdf.extend_from_slice(format!("{obj2_pos:010} 00000 n \n").as_bytes());
        pdf.extend_from_slice(format!("{obj3_pos:010} 00000 n \n").as_bytes());

        // Trailer
        pdf.extend_from_slice(b"trailer\n");
        pdf.extend_from_slice(b"<< /Size 4 /Root 1 0 R /Info 3 0 R >>\n");
        pdf.extend_from_slice(b"startxref\n");
        pdf.extend_from_slice(format!("{xref_pos}\n").as_bytes());
        pdf.extend_from_slice(b"%%EOF\n");

        pdf
    }

    #[test]
    fn test_pdf_document_new() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Verify document is created with empty caches
        assert!(document.page_tree.borrow().is_none());
        assert!(document.metadata_cache.borrow().is_none());
    }

    #[test]
    fn test_version() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        let version = document.version().unwrap();
        assert_eq!(version, "1.4");
    }

    #[test]
    fn test_page_count() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        let count = document.page_count().unwrap();
        assert_eq!(count, 1);
    }

    #[test]
    fn test_metadata() {
        let pdf_data = create_pdf_with_metadata();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        let metadata = document.metadata().unwrap();
        assert_eq!(metadata.title, Some("Test Document".to_string()));
        assert_eq!(metadata.author, Some("Test Author".to_string()));
        assert_eq!(metadata.subject, Some("Test Subject".to_string()));

        // Verify caching works
        let metadata2 = document.metadata().unwrap();
        assert_eq!(metadata.title, metadata2.title);
    }

    #[test]
    fn test_get_page() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Get first page
        let page = document.get_page(0).unwrap();
        assert_eq!(page.media_box, [0.0, 0.0, 612.0, 792.0]);

        // Verify caching works
        let page2 = document.get_page(0).unwrap();
        assert_eq!(page.media_box, page2.media_box);
    }

    #[test]
    fn test_get_page_out_of_bounds() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Try to get page that doesn't exist
        let result = document.get_page(10);
        // With fallback lookup, this might succeed or fail gracefully
        if result.is_err() {
            assert!(result.unwrap_err().to_string().contains("Page"));
        } else {
            // If succeeds, should return a valid page
            let _page = result.unwrap();
        }
    }

    #[test]
    fn test_resource_manager_caching() {
        let resources = ResourceManager::new();

        // Test caching an object
        let obj_ref = (1, 0);
        let obj = PdfObject::String(PdfString("Test".as_bytes().to_vec()));

        assert!(resources.get_cached(obj_ref).is_none());

        resources.cache_object(obj_ref, obj.clone());

        let cached = resources.get_cached(obj_ref).unwrap();
        assert_eq!(cached, obj);

        // Test clearing cache
        resources.clear_cache();
        assert!(resources.get_cached(obj_ref).is_none());
    }

    #[test]
    fn test_get_object() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Get catalog object
        let catalog = document.get_object(1, 0).unwrap();
        if let PdfObject::Dictionary(dict) = catalog {
            if let Some(PdfObject::Name(name)) = dict.get("Type") {
                assert_eq!(name.0, "Catalog");
            } else {
                panic!("Expected /Type name");
            }
        } else {
            panic!("Expected dictionary object");
        }
    }

    #[test]
    fn test_resolve_reference() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Create a reference to the catalog
        let ref_obj = PdfObject::Reference(1, 0);

        // Resolve it
        let resolved = document.resolve(&ref_obj).unwrap();
        if let PdfObject::Dictionary(dict) = resolved {
            if let Some(PdfObject::Name(name)) = dict.get("Type") {
                assert_eq!(name.0, "Catalog");
            } else {
                panic!("Expected /Type name");
            }
        } else {
            panic!("Expected dictionary object");
        }
    }

    #[test]
    fn test_resolve_non_reference() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Try to resolve a non-reference object
        let obj = PdfObject::String(PdfString("Test".as_bytes().to_vec()));
        let resolved = document.resolve(&obj).unwrap();

        // Should return the same object
        assert_eq!(resolved, obj);
    }

    #[test]
    fn test_invalid_pdf_data() {
        let invalid_data = b"This is not a PDF";
        let cursor = Cursor::new(invalid_data.to_vec());
        let result = PdfReader::new(cursor);

        assert!(result.is_err());
    }

    #[test]
    fn test_empty_page_tree() {
        // Create PDF with empty page tree
        let pdf_data = create_pdf_with_metadata(); // This has 0 pages
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        let count = document.page_count().unwrap();
        assert_eq!(count, 0);

        // Try to get a page from empty document
        let result = document.get_page(0);
        assert!(result.is_err());
    }

    #[test]
    fn test_extract_text_empty_document() {
        let pdf_data = create_pdf_with_metadata();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        let text = document.extract_text().unwrap();
        assert!(text.is_empty());
    }

    #[test]
    fn test_concurrent_access() {
        let pdf_data = create_minimal_pdf();
        let cursor = Cursor::new(pdf_data);
        let reader = PdfReader::new(cursor).unwrap();
        let document = PdfDocument::new(reader);

        // Access multiple things concurrently
        let version = document.version().unwrap();
        let count = document.page_count().unwrap();
        let page = document.get_page(0).unwrap();

        assert_eq!(version, "1.4");
        assert_eq!(count, 1);
        assert_eq!(page.media_box[2], 612.0);
    }

    // Additional comprehensive tests
    mod comprehensive_tests {
        use super::*;

        #[test]
        fn test_resource_manager_default() {
            let resources = ResourceManager::default();
            assert!(resources.get_cached((1, 0)).is_none());
        }

        #[test]
        fn test_resource_manager_multiple_objects() {
            let resources = ResourceManager::new();

            // Cache multiple objects
            resources.cache_object((1, 0), PdfObject::Integer(42));
            resources.cache_object((2, 0), PdfObject::Boolean(true));
            resources.cache_object(
                (3, 0),
                PdfObject::String(PdfString("test".as_bytes().to_vec())),
            );

            // Verify all are cached
            assert!(resources.get_cached((1, 0)).is_some());
            assert!(resources.get_cached((2, 0)).is_some());
            assert!(resources.get_cached((3, 0)).is_some());

            // Clear and verify empty
            resources.clear_cache();
            assert!(resources.get_cached((1, 0)).is_none());
            assert!(resources.get_cached((2, 0)).is_none());
            assert!(resources.get_cached((3, 0)).is_none());
        }

        #[test]
        fn test_resource_manager_object_overwrite() {
            let resources = ResourceManager::new();

            // Cache an object
            resources.cache_object((1, 0), PdfObject::Integer(42));
            assert_eq!(resources.get_cached((1, 0)), Some(PdfObject::Integer(42)));

            // Overwrite with different object
            resources.cache_object((1, 0), PdfObject::Boolean(true));
            assert_eq!(resources.get_cached((1, 0)), Some(PdfObject::Boolean(true)));
        }

        #[test]
        fn test_get_object_caching() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Get object first time (should cache)
            let obj1 = document.get_object(1, 0).unwrap();

            // Get same object again (should use cache)
            let obj2 = document.get_object(1, 0).unwrap();

            // Objects should be identical
            assert_eq!(obj1, obj2);

            // Verify it's cached
            assert!(document.resources.get_cached((1, 0)).is_some());
        }

        #[test]
        fn test_get_object_different_generations() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Get object with generation 0
            let _obj1 = document.get_object(1, 0).unwrap();

            // Try to get same object with different generation (should fail)
            let result = document.get_object(1, 1);
            assert!(result.is_err());

            // Original should still be cached
            assert!(document.resources.get_cached((1, 0)).is_some());
        }

        #[test]
        fn test_get_object_nonexistent() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Try to get non-existent object
            let result = document.get_object(999, 0);
            assert!(result.is_err());
        }

        #[test]
        fn test_resolve_nested_references() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Test resolving a reference
            let ref_obj = PdfObject::Reference(2, 0);
            let resolved = document.resolve(&ref_obj).unwrap();

            // Should resolve to the pages object
            if let PdfObject::Dictionary(dict) = resolved {
                if let Some(PdfObject::Name(name)) = dict.get("Type") {
                    assert_eq!(name.0, "Pages");
                }
            }
        }

        #[test]
        fn test_resolve_various_object_types() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Test resolving different object types
            let test_objects = vec![
                PdfObject::Integer(42),
                PdfObject::Boolean(true),
                PdfObject::String(PdfString("test".as_bytes().to_vec())),
                PdfObject::Real(3.14),
                PdfObject::Null,
            ];

            for obj in test_objects {
                let resolved = document.resolve(&obj).unwrap();
                assert_eq!(resolved, obj);
            }
        }

        #[test]
        fn test_get_page_cached() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Get page first time
            let page1 = document.get_page(0).unwrap();

            // Get same page again
            let page2 = document.get_page(0).unwrap();

            // Should be identical
            assert_eq!(page1.media_box, page2.media_box);
            assert_eq!(page1.rotation, page2.rotation);
            assert_eq!(page1.obj_ref, page2.obj_ref);
        }

        #[test]
        fn test_metadata_caching() {
            let pdf_data = create_pdf_with_metadata();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Get metadata first time
            let meta1 = document.metadata().unwrap();

            // Get metadata again
            let meta2 = document.metadata().unwrap();

            // Should be identical
            assert_eq!(meta1.title, meta2.title);
            assert_eq!(meta1.author, meta2.author);
            assert_eq!(meta1.subject, meta2.subject);
            assert_eq!(meta1.version, meta2.version);
        }

        #[test]
        fn test_page_tree_initialization() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Initially page tree should be None
            assert!(document.page_tree.borrow().is_none());

            // After getting page count, page tree should be initialized
            let _count = document.page_count().unwrap();
            // Note: page_tree is private, so we can't directly check it
            // But we can verify it works by getting a page
            let _page = document.get_page(0).unwrap();
        }

        #[test]
        fn test_get_page_resources() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let page = document.get_page(0).unwrap();
            let resources = document.get_page_resources(&page).unwrap();

            // The minimal PDF has empty resources
            assert!(resources.is_some());
        }

        #[test]
        fn test_get_page_content_streams_empty() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let page = document.get_page(0).unwrap();
            let streams = document.get_page_content_streams(&page).unwrap();

            // Minimal PDF has no content streams
            assert!(streams.is_empty());
        }

        #[test]
        fn test_extract_text_from_page() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let result = document.extract_text_from_page(0);
            // Should succeed even with empty page
            assert!(result.is_ok());
        }

        #[test]
        fn test_extract_text_from_page_out_of_bounds() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let result = document.extract_text_from_page(999);
            // With fallback lookup, this might succeed or fail gracefully
            if result.is_err() {
                assert!(result.unwrap_err().to_string().contains("Page"));
            } else {
                // If succeeds, should return empty or valid text
                let _text = result.unwrap();
            }
        }

        #[test]
        fn test_extract_text_with_options() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let options = crate::text::ExtractionOptions {
                preserve_layout: true,
                space_threshold: 0.5,
                newline_threshold: 15.0,
                ..Default::default()
            };

            let result = document.extract_text_with_options(options);
            assert!(result.is_ok());
        }

        #[test]
        fn test_version_different_pdf_versions() {
            // Test with different PDF versions
            let versions = vec!["1.3", "1.4", "1.5", "1.6", "1.7"];

            for version in versions {
                let mut pdf_data = Vec::new();

                // PDF header
                pdf_data.extend_from_slice(format!("%PDF-{version}\n").as_bytes());

                // Track positions for xref
                let obj1_pos = pdf_data.len();

                // Catalog object
                pdf_data.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");

                let obj2_pos = pdf_data.len();

                // Pages object
                pdf_data
                    .extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [] /Count 0 >>\nendobj\n");

                // Cross-reference table
                let xref_pos = pdf_data.len();
                pdf_data.extend_from_slice(b"xref\n");
                pdf_data.extend_from_slice(b"0 3\n");
                pdf_data.extend_from_slice(b"0000000000 65535 f \n");
                pdf_data.extend_from_slice(format!("{obj1_pos:010} 00000 n \n").as_bytes());
                pdf_data.extend_from_slice(format!("{obj2_pos:010} 00000 n \n").as_bytes());

                // Trailer
                pdf_data.extend_from_slice(b"trailer\n");
                pdf_data.extend_from_slice(b"<< /Size 3 /Root 1 0 R >>\n");
                pdf_data.extend_from_slice(b"startxref\n");
                pdf_data.extend_from_slice(format!("{xref_pos}\n").as_bytes());
                pdf_data.extend_from_slice(b"%%EOF\n");

                let cursor = Cursor::new(pdf_data);
                let reader = PdfReader::new(cursor).unwrap();
                let document = PdfDocument::new(reader);

                let pdf_version = document.version().unwrap();
                assert_eq!(pdf_version, version);
            }
        }

        #[test]
        fn test_page_count_zero() {
            let pdf_data = create_pdf_with_metadata(); // Has 0 pages
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let count = document.page_count().unwrap();
            assert_eq!(count, 0);
        }

        #[test]
        fn test_multiple_object_access() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Access multiple objects
            let catalog = document.get_object(1, 0).unwrap();
            let pages = document.get_object(2, 0).unwrap();
            let page = document.get_object(3, 0).unwrap();

            // Verify they're all different objects
            assert_ne!(catalog, pages);
            assert_ne!(pages, page);
            assert_ne!(catalog, page);
        }

        #[test]
        fn test_error_handling_invalid_object_reference() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Try to resolve an invalid reference
            let invalid_ref = PdfObject::Reference(999, 0);
            let result = document.resolve(&invalid_ref);
            assert!(result.is_err());
        }

        #[test]
        fn test_concurrent_metadata_access() {
            let pdf_data = create_pdf_with_metadata();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Access metadata and other properties concurrently
            let metadata = document.metadata().unwrap();
            let version = document.version().unwrap();
            let count = document.page_count().unwrap();

            assert_eq!(metadata.title, Some("Test Document".to_string()));
            assert_eq!(version, "1.5");
            assert_eq!(count, 0);
        }

        #[test]
        fn test_page_properties_comprehensive() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            let page = document.get_page(0).unwrap();

            // Test all page properties
            assert_eq!(page.media_box, [0.0, 0.0, 612.0, 792.0]);
            assert_eq!(page.crop_box, None);
            assert_eq!(page.rotation, 0);
            assert_eq!(page.obj_ref, (3, 0));

            // Test width/height calculation
            assert_eq!(page.width(), 612.0);
            assert_eq!(page.height(), 792.0);
        }

        #[test]
        fn test_memory_usage_efficiency() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Access same page multiple times
            for _ in 0..10 {
                let _page = document.get_page(0).unwrap();
            }

            // Should only have one copy in cache
            let page_count = document.page_count().unwrap();
            assert_eq!(page_count, 1);
        }

        #[test]
        fn test_reader_borrow_safety() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Multiple concurrent borrows should work
            let version = document.version().unwrap();
            let count = document.page_count().unwrap();
            let metadata = document.metadata().unwrap();

            assert_eq!(version, "1.4");
            assert_eq!(count, 1);
            assert!(metadata.title.is_none());
        }

        #[test]
        fn test_cache_consistency() {
            let pdf_data = create_minimal_pdf();
            let cursor = Cursor::new(pdf_data);
            let reader = PdfReader::new(cursor).unwrap();
            let document = PdfDocument::new(reader);

            // Get object and verify caching
            let obj1 = document.get_object(1, 0).unwrap();
            let cached = document.resources.get_cached((1, 0)).unwrap();

            assert_eq!(obj1, cached);

            // Clear cache and get object again
            document.resources.clear_cache();
            let obj2 = document.get_object(1, 0).unwrap();

            // Should be same content but loaded fresh
            assert_eq!(obj1, obj2);
        }
    }

    #[test]
    fn test_resource_manager_new() {
        let resources = ResourceManager::new();
        assert!(resources.get_cached((1, 0)).is_none());
    }

    #[test]
    fn test_resource_manager_cache_and_get() {
        let resources = ResourceManager::new();

        // Cache an object
        let obj = PdfObject::Integer(42);
        resources.cache_object((10, 0), obj.clone());

        // Should be retrievable
        let cached = resources.get_cached((10, 0));
        assert!(cached.is_some());
        assert_eq!(cached.unwrap(), obj);

        // Non-existent object
        assert!(resources.get_cached((11, 0)).is_none());
    }

    #[test]
    fn test_resource_manager_clear_cache() {
        let resources = ResourceManager::new();

        // Cache multiple objects
        resources.cache_object((1, 0), PdfObject::Integer(1));
        resources.cache_object((2, 0), PdfObject::Integer(2));
        resources.cache_object((3, 0), PdfObject::Integer(3));

        // Verify they're cached
        assert!(resources.get_cached((1, 0)).is_some());
        assert!(resources.get_cached((2, 0)).is_some());
        assert!(resources.get_cached((3, 0)).is_some());

        // Clear cache
        resources.clear_cache();

        // Should all be gone
        assert!(resources.get_cached((1, 0)).is_none());
        assert!(resources.get_cached((2, 0)).is_none());
        assert!(resources.get_cached((3, 0)).is_none());
    }

    #[test]
    fn test_resource_manager_overwrite_cached() {
        let resources = ResourceManager::new();

        // Cache initial object
        resources.cache_object((1, 0), PdfObject::Integer(42));
        assert_eq!(
            resources.get_cached((1, 0)).unwrap(),
            PdfObject::Integer(42)
        );

        // Overwrite with new object
        resources.cache_object((1, 0), PdfObject::Integer(100));
        assert_eq!(
            resources.get_cached((1, 0)).unwrap(),
            PdfObject::Integer(100)
        );
    }

    #[test]
    fn test_resource_manager_multiple_generations() {
        let resources = ResourceManager::new();

        // Cache objects with different generations
        resources.cache_object((1, 0), PdfObject::Integer(10));
        resources.cache_object((1, 1), PdfObject::Integer(11));
        resources.cache_object((1, 2), PdfObject::Integer(12));

        // Each should be distinct
        assert_eq!(
            resources.get_cached((1, 0)).unwrap(),
            PdfObject::Integer(10)
        );
        assert_eq!(
            resources.get_cached((1, 1)).unwrap(),
            PdfObject::Integer(11)
        );
        assert_eq!(
            resources.get_cached((1, 2)).unwrap(),
            PdfObject::Integer(12)
        );
    }

    #[test]
    fn test_resource_manager_cache_complex_objects() {
        let resources = ResourceManager::new();

        // Cache different object types
        resources.cache_object((1, 0), PdfObject::Boolean(true));
        resources.cache_object((2, 0), PdfObject::Real(3.14159));
        resources.cache_object(
            (3, 0),
            PdfObject::String(PdfString::new(b"Hello PDF".to_vec())),
        );
        resources.cache_object((4, 0), PdfObject::Name(PdfName::new("Type".to_string())));

        let mut dict = PdfDictionary::new();
        dict.insert(
            "Key".to_string(),
            PdfObject::String(PdfString::new(b"Value".to_vec())),
        );
        resources.cache_object((5, 0), PdfObject::Dictionary(dict));

        let array = vec![PdfObject::Integer(1), PdfObject::Integer(2)];
        resources.cache_object((6, 0), PdfObject::Array(PdfArray(array)));

        // Verify all cached correctly
        assert_eq!(
            resources.get_cached((1, 0)).unwrap(),
            PdfObject::Boolean(true)
        );
        assert_eq!(
            resources.get_cached((2, 0)).unwrap(),
            PdfObject::Real(3.14159)
        );
        assert_eq!(
            resources.get_cached((3, 0)).unwrap(),
            PdfObject::String(PdfString::new(b"Hello PDF".to_vec()))
        );
        assert_eq!(
            resources.get_cached((4, 0)).unwrap(),
            PdfObject::Name(PdfName::new("Type".to_string()))
        );
        assert!(matches!(
            resources.get_cached((5, 0)).unwrap(),
            PdfObject::Dictionary(_)
        ));
        assert!(matches!(
            resources.get_cached((6, 0)).unwrap(),
            PdfObject::Array(_)
        ));
    }

    // Tests for PdfDocument removed due to API incompatibilities
    // The methods tested don't exist in the current implementation

    /*
        #[test]
        fn test_pdf_document_new_initialization() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            // Document should be created successfully
            // Initially no page tree loaded
            assert!(document.page_tree.borrow().is_none());
            assert!(document.metadata_cache.borrow().is_none());
        }

        #[test]
        fn test_pdf_document_version() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            let version = document.version().unwrap();
            assert!(!version.is_empty());
            // Most PDFs are version 1.4 to 1.7
            assert!(version.starts_with("1.") || version.starts_with("2."));
        }

        #[test]
        fn test_pdf_document_page_count() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            let count = document.page_count().unwrap();
            assert!(count > 0);
        }

        #[test]
        fn test_pdf_document_metadata() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            let metadata = document.metadata().unwrap();
            // Metadata should be cached after first access
            assert!(document.metadata_cache.borrow().is_some());

            // Second call should use cache
            let metadata2 = document.metadata().unwrap();
            assert_eq!(metadata.title, metadata2.title);
        }

        #[test]
        fn test_pdf_document_get_page() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            // Get first page
            let page = document.get_page(0).unwrap();
            assert!(page.width() > 0.0);
            assert!(page.height() > 0.0);

            // Page tree should be loaded now
            assert!(document.page_tree.borrow().is_some());
        }

        #[test]
        fn test_pdf_document_get_page_out_of_bounds() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            let page_count = document.page_count().unwrap();

            // Try to get page beyond count
            let result = document.get_page(page_count + 10);
            assert!(result.is_err());
        }


        #[test]
        fn test_pdf_document_get_object() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            // Get an object (catalog is usually object 1 0)
            let obj = document.get_object(1, 0);
            assert!(obj.is_ok());

            // Object should be cached
            assert!(document.resources.get_cached((1, 0)).is_some());
        }



        #[test]
        fn test_pdf_document_extract_text_from_page() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            // Try to extract text from first page
            let result = document.extract_text_from_page(0);
            // Even if no text, should not error
            assert!(result.is_ok());
        }

        #[test]
        fn test_pdf_document_extract_all_text() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            let extracted = document.extract_text().unwrap();
            let page_count = document.page_count().unwrap();

            // Should have text for each page
            assert_eq!(extracted.len(), page_count);
        }


        #[test]
        fn test_pdf_document_ensure_page_tree() {
            // Create a minimal PDF for testing
            let data = b"%PDF-1.4
    1 0 obj<</Type/Catalog/Pages 2 0 R>>endobj
    2 0 obj<</Type/Pages/Kids[3 0 R]/Count 1>>endobj
    3 0 obj<</Type/Page/Parent 2 0 R/MediaBox[0 0 612 792]>>endobj
    xref
    0 4
    0000000000 65535 f
    0000000009 00000 n
    0000000052 00000 n
    0000000101 00000 n
    trailer<</Size 4/Root 1 0 R>>
    startxref
    164
    %%EOF";
            let reader = PdfReader::new(std::io::Cursor::new(data.to_vec())).unwrap();
            let document = PdfDocument::new(reader);

            // Initially no page tree
            assert!(document.page_tree.borrow().is_none());

            // After ensuring, should be loaded
            document.ensure_page_tree().unwrap();
            assert!(document.page_tree.borrow().is_some());

            // Second call should not error
            document.ensure_page_tree().unwrap();
        }

        #[test]
        fn test_resource_manager_concurrent_access() {
            let resources = ResourceManager::new();

            // Simulate concurrent-like access pattern
            resources.cache_object((1, 0), PdfObject::Integer(1));
            let obj1 = resources.get_cached((1, 0));

            resources.cache_object((2, 0), PdfObject::Integer(2));
            let obj2 = resources.get_cached((2, 0));

            // Both should be accessible
            assert_eq!(obj1.unwrap(), PdfObject::Integer(1));
            assert_eq!(obj2.unwrap(), PdfObject::Integer(2));
        }

        #[test]
        fn test_resource_manager_large_cache() {
            let resources = ResourceManager::new();

            // Cache many objects
            for i in 0..1000 {
                resources.cache_object((i, 0), PdfObject::Integer(i as i64));
            }

            // Verify random access
            assert_eq!(resources.get_cached((500, 0)).unwrap(), PdfObject::Integer(500));
            assert_eq!(resources.get_cached((999, 0)).unwrap(), PdfObject::Integer(999));
            assert_eq!(resources.get_cached((0, 0)).unwrap(), PdfObject::Integer(0));

            // Clear should remove all
            resources.clear_cache();
            assert!(resources.get_cached((500, 0)).is_none());
        }
        */
}