rpdfium 7676.6.4

#![forbid(unsafe_code)]
#![doc = "rpdfium — a faithful Rust port of Google's PDFium PDF rendering engine."]

pub mod arc;
pub use arc::{ArcDocument, ArcLibrary, ArcPage};

#[cfg(feature = "edit")]
pub mod edit;

mod image_decode;

use image_decode::{convert_to_rgba, get_dict_int, read_decode_array, resolve_image_color_space};

use std::sync::{Arc, OnceLock};

use rpdfium_font::{DashMapFontCache, FontCache as _, FontRef, ResolvedFont};
use rpdfium_page::display::{DisplayTree, walk};
use rpdfium_page::resource::ResourceDict;
use rpdfium_page::{InterpreterContext, collect_page_ids, interpret, resolve_resources};
use rpdfium_parser::{ObjectStore, tokenize_content_stream};

// Re-exports from rpdfium-core
pub use rpdfium_core::error::{ObjectId, ParseError, PdfError, PdfResult};
pub use rpdfium_core::{Name, PdfString, PdfStringEncoding};

// Re-exports from rpdfium-parser
pub use rpdfium_parser::object::{Object, StreamData};

// Re-exports from rpdfium-render
pub use rpdfium_render::{
    RenderError, RgbaColor, compute_page_transform, render, render_with_images,
};

// Re-exports from rpdfium-font
pub use rpdfium_font::{
    FolderFontScanner, FontMapper, FontMatch, FontRequest, FontWeight, GlyphUsageTracker,
    base14_substitute, subset_truetype_font,
};

// Re-exports from rpdfium-doc
pub use rpdfium_doc::{
    Action, ActionType, Annotation, AnnotationBorder, AnnotationFlags, AnnotationSubtypeData,
    AnnotationType, AttributeValue, Bookmark, BorderStyle, Destination, DocError, DocMdpPermission,
    DocResult, DocumentMetadata, DuplexMode, ElementsForPage, FdfData, FieldValue, FileSpec,
    FormFieldFlags, HitTestResult, InteractiveForm, JavaScriptAction, LinkObject, McidMapping,
    NameTree, NumberTree, PageFit, PageLabel, PageLabelStyle, PageMode, PageStructure, PdfFormType,
    ReadingDirection, SignatureObject, StructAttribute, StructElement, StructTree,
    ViewerPreferences, collect_attachments, collect_javascript_actions, collect_links,
    collect_named_destinations, collect_signatures, export_fdf, find_bookmark,
    find_link_at_position, format_label, import_fdf, is_tagged, link_at_point, link_enumerate,
    link_get_link_at_point, next_sibling_bookmark, page_mode, parse_annotations, parse_bookmarks,
    parse_destination, parse_metadata, parse_page_labels,
};
#[allow(deprecated)]
pub use rpdfium_doc::{enumerate, enumerate_links, get_bookmark_by_title, get_link_at_point};

// Re-exports from rpdfium-parser
pub use rpdfium_parser::PdfVersion;

// Re-exports from rpdfium-text
pub use rpdfium_text::{
    CharOrigin, CharRect, CharType, Link, LinkKind, SearchOptions, SearchResult, TextCharacter,
    TextExtractor, TextPage, TextPageFind, extract_links, search, search_case_insensitive,
    search_consecutive, search_normalized, search_normalized_case_insensitive, search_whole_word,
    search_whole_word_case_insensitive, segment_lines, segment_words,
};

// Re-exports from rpdfium-graphics
pub use rpdfium_graphics::{Bitmap, BitmapFormat, Color};

// Re-exports from rpdfium-page
pub use rpdfium_page::{DisplayNode, DisplayVisitor, OCContext, PageError, UsageType};

// Additional re-exports from rpdfium-core
pub use rpdfium_core::{Matrix, OpenOptions, ParsingMode, Point, Rect, Size};

// Re-export RenderConfig and ColorScheme
pub use rpdfium_render::{ColorScheme, RenderConfig};

// ---------------------------------------------------------------------------
// Unified Error type
// ---------------------------------------------------------------------------

/// Unified error type for the rpdfium facade.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// An error from the PDF parser layer.
    #[error(transparent)]
    Parse(#[from] PdfError),

    /// An error from the page interpreter.
    #[error(transparent)]
    Page(#[from] PageError),

    /// An error from the renderer.
    #[error(transparent)]
    Render(#[from] RenderError),

    /// An error from the document structure layer.
    #[error(transparent)]
    Doc(#[from] DocError),

    /// Page index is out of range.
    #[error("page index out of range: {index} (document has {count} pages)")]
    PageOutOfRange {
        /// The requested page index.
        index: u32,
        /// The total page count.
        count: u32,
    },
}

/// Convenience result alias for [`Error`].
pub type Result<T> = std::result::Result<T, Error>;

// ---------------------------------------------------------------------------
// FileIdentifierType
// ---------------------------------------------------------------------------

/// Selects which of the two PDF file identifiers to retrieve.
///
/// The PDF trailer `/ID` array always contains exactly two identifiers:
/// - `Permanent` (index 0): assigned when the document is first created.
/// - `Changing` (index 1): updated each time the document is saved.
///
/// Corresponds to `FPDF_FILEIDTYPE` in PDFium (`fpdf_view.h`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[repr(usize)]
pub enum FileIdentifierType {
    /// The permanent (original) document identifier — index 0 in the `/ID` array.
    Permanent = 0,
    /// The changing (revision) document identifier — index 1 in the `/ID` array.
    Changing = 1,
}

// ---------------------------------------------------------------------------
// Font cache bridge
// ---------------------------------------------------------------------------

/// Bridges the rpdfium-page `FontCache` trait to the rpdfium-font
/// `DashMapFontCache` implementation.
pub(crate) struct FontCacheBridge<'a> {
    pub(crate) font_cache: &'a DashMapFontCache,
    pub(crate) store: &'a ObjectStore<Arc<[u8]>>,
    pub(crate) resources: &'a ResourceDict,
}

impl rpdfium_page::FontCache for FontCacheBridge<'_> {
    fn glyph_width(&self, font_name: &Name, char_code: u16) -> Option<f32> {
        let font_id = self.resources.fonts.get(font_name)?;
        let font_ref = FontRef::new(*font_id);
        let resolved = self.font_cache.get_or_load(&font_ref, self.store).ok()?;
        Some(resolved.char_width(char_code) as f32)
    }

    fn get_resolved_font(&self, font_name: &Name) -> Option<Arc<ResolvedFont>> {
        let font_id = self.resources.fonts.get(font_name)?;
        let font_ref = FontRef::new(*font_id);
        self.font_cache.get_or_load(&font_ref, self.store).ok()
    }
}

// ---------------------------------------------------------------------------
// PageActionType
// ---------------------------------------------------------------------------

/// Event type for page-level additional actions (`/AA` on a page dict).
///
/// PDF pages can have an `/AA` dictionary (ISO 32000-2 Table 197) with two
/// keys:
/// - `/O` — triggered when the page is opened.
/// - `/C` — triggered when the page is closed.
///
/// Corresponds to `FPDF_PAGE_AACTION_OPEN`/`FPDF_PAGE_AACTION_CLOSE` in
/// PDFium's `fpdf_doc.h`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PageActionType {
    /// Page opened (`/O`). Corresponds to `FPDF_PAGE_AACTION_OPEN = 0`.
    Open = 0,
    /// Page closed (`/C`). Corresponds to `FPDF_PAGE_AACTION_CLOSE = 1`.
    Close = 1,
}

impl PageActionType {
    /// Returns the PDF dictionary key string for this page action type.
    pub fn pdf_key(self) -> &'static str {
        match self {
            Self::Open => "O",
            Self::Close => "C",
        }
    }
}

// ---------------------------------------------------------------------------
// PdfReader trait (FPDF_LoadCustomDocument equivalent)
// ---------------------------------------------------------------------------

/// Custom PDF data source, equivalent to `FPDF_FILEACCESS`.
///
/// Implement this trait to load a PDF from any source (network stream,
/// encrypted container, memory-mapped file, etc.).  Pass the implementor to
/// [`Document::open_custom()`] or [`ArcDocument::open_custom()`].
///
/// Corresponds to `FPDF_FILEACCESS` in PDFium's `fpdf_view.h`.
///
/// # Contract
///
/// Implementations **must** satisfy the following:
///
/// - [`file_len()`](Self::file_len) returns the total number of bytes in the
///   source.  It must be stable for the lifetime of the reader.
/// - [`read_at()`](Self::read_at) reads up to `buf.len()` bytes starting at
///   byte position `offset` into `buf`.  The number of bytes actually read is
///   returned.  Returning fewer bytes than `buf.len()` is allowed (short
///   read); the caller will continue issuing further reads.
/// - When `offset >= file_len()`, [`read_at()`](Self::read_at) **must** return
///   `Ok(0)` (EOF) rather than panicking or returning an error.
/// - Implementations may be called from multiple threads concurrently; they
///   must be `Send + Sync`.
pub trait PdfReader: Send + Sync {
    /// Total size of the PDF data in bytes.
    ///
    /// Must be stable; called once before the first [`read_at()`](Self::read_at).
    fn file_len(&self) -> u64;

    /// Read bytes into `buf` starting at `offset`.
    ///
    /// Returns the number of bytes actually copied into `buf`.  Returns `Ok(0)`
    /// when `offset >= file_len()` (EOF).  Partial reads are allowed.
    fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<usize>;
}

// ---------------------------------------------------------------------------
// Library
// ---------------------------------------------------------------------------

/// The top-level library instance.
///
/// In the lifetime-based API, all documents and pages borrow from
/// the `Library`, ensuring they cannot outlive the engine context.
pub struct Library {
    _private: (),
    font_mapper: Option<Box<dyn FontMapper>>,
}

impl Library {
    /// Create a new `Library` instance with default system font discovery.
    pub fn new() -> Self {
        Self {
            _private: (),
            font_mapper: Some(Box::new(FolderFontScanner::new())),
        }
    }

    /// Create a `Library` with a custom font mapper.
    ///
    /// Use this for WASM targets, embedded systems, or when you want to
    /// provide fonts from a custom source.
    pub fn with_font_mapper(mapper: Box<dyn FontMapper>) -> Self {
        Self {
            _private: (),
            font_mapper: Some(mapper),
        }
    }

    /// Returns a reference to the font mapper, if configured.
    pub fn font_mapper(&self) -> Option<&dyn FontMapper> {
        self.font_mapper.as_deref()
    }
}

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

// ---------------------------------------------------------------------------
// Document
// ---------------------------------------------------------------------------

/// A parsed PDF document, borrowing from the [`Library`].
pub struct Document<'lib> {
    #[allow(dead_code)]
    library: &'lib Library,
    store: ObjectStore<Arc<[u8]>>,
    font_cache: DashMapFontCache,
    page_ids: Vec<ObjectId>,
    catalog_id: ObjectId,
    options: OpenOptions,
    oc_context: Option<rpdfium_page::OCContext>,
}

impl<'lib> Document<'lib> {
    /// Open a PDF document from in-memory data.
    ///
    /// Parses the file structure, resolves the page tree, and prepares
    /// the document for page access.
    pub fn open(
        library: &'lib Library,
        data: Vec<u8>,
        options: &OpenOptions,
    ) -> Result<Document<'lib>> {
        let arc_data: Arc<[u8]> = Arc::from(data);
        let store = ObjectStore::open_with_password(
            arc_data,
            options.parsing_mode,
            options.password.as_deref(),
        )?;
        let page_ids = collect_page_ids(&store)?;
        let catalog_id = store.trailer().root;
        let font_cache = DashMapFontCache::new();
        let oc_context = rpdfium_page::OCContext::from_catalog(&store, catalog_id);

        Ok(Document {
            library,
            store,
            font_cache,
            page_ids,
            catalog_id,
            options: options.clone(),
            oc_context,
        })
    }

    /// Upstream-aligned alias for [`open()`](Self::open).
    ///
    /// Corresponds to `FPDF_LoadMemDocument`.
    #[inline]
    pub fn load_mem_document(
        library: &'lib Library,
        data: Vec<u8>,
        options: &OpenOptions,
    ) -> Result<Document<'lib>> {
        Self::open(library, data, options)
    }

    /// Open a PDF document from a file path.
    ///
    /// This is a convenience wrapper around [`Document::open()`] that reads
    /// the file contents into memory before parsing.
    ///
    /// # Examples
    ///
    /// ```no_run
    /// # use rpdfium::{Library, OpenOptions};
    /// let lib = Library::new();
    /// let opts = OpenOptions::default();
    /// let doc = rpdfium::Document::open_file(&lib, "document.pdf", &opts)?;
    /// # Ok::<(), rpdfium::Error>(())
    /// ```
    pub fn open_file(
        library: &'lib Library,
        path: impl AsRef<std::path::Path>,
        options: &OpenOptions,
    ) -> Result<Document<'lib>> {
        let data = std::fs::read(path).map_err(PdfError::Io)?;
        Self::open(library, data, options)
    }

    /// Upstream-aligned alias for [`open_file()`](Self::open_file).
    ///
    /// Corresponds to `FPDF_LoadDocument`.
    #[inline]
    pub fn load_document(
        library: &'lib Library,
        path: impl AsRef<std::path::Path>,
        options: &OpenOptions,
    ) -> Result<Document<'lib>> {
        Self::open_file(library, path, options)
    }

    /// Load a PDF document from a custom reader.
    ///
    /// Reads all data from `reader` into memory, then delegates to
    /// [`Document::open()`].  This is the idiomatic way to load PDFs from
    /// non-filesystem sources (network, encrypted containers, custom VFS).
    ///
    /// Corresponds to `FPDF_LoadCustomDocument` in PDFium's `fpdf_view.h`.
    pub fn open_custom(
        library: &'lib Library,
        reader: impl PdfReader,
        options: &OpenOptions,
    ) -> Result<Self> {
        let len = reader.file_len() as usize;
        let mut data = vec![0u8; len];
        let mut offset = 0;
        while offset < data.len() {
            let n = reader
                .read_at(offset as u64, &mut data[offset..])
                .map_err(PdfError::Io)?;
            if n == 0 {
                break;
            }
            offset += n;
        }
        data.truncate(offset);
        Self::open(library, data, options)
    }

    /// Upstream-aligned alias for [`open_custom()`](Self::open_custom).
    ///
    /// Corresponds to `FPDF_LoadCustomDocument`.
    #[inline]
    pub fn load_custom_document(
        library: &'lib Library,
        reader: impl PdfReader,
        options: &OpenOptions,
    ) -> Result<Self> {
        Self::open_custom(library, reader, options)
    }

    /// Returns the number of pages in the document.
    ///
    /// Corresponds to `FPDF_GetPageCount`.
    pub fn page_count(&self) -> u32 {
        self.page_ids.len() as u32
    }

    /// Upstream-aligned alias for [`Self::page_count()`].
    ///
    /// Corresponds to `FPDF_GetPageCount`.
    #[inline]
    pub fn get_page_count(&self) -> u32 {
        self.page_count()
    }

    /// Get a page by its zero-based index.
    pub fn page(&self, index: u32) -> Result<Page<'_>> {
        let count = self.page_count();
        if index >= count {
            return Err(Error::PageOutOfRange { index, count });
        }
        let page_dict_id = self.page_ids[index as usize];

        // Resolve the page dictionary to extract /MediaBox
        let page_obj = self.store.resolve(page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(page_dict_id))?;

        let media_box = parse_rect(page_dict, &Name::media_box(), &self.store)
            .or_else(|| {
                // Inherit /MediaBox from parent Pages node (PDF spec 7.7.3.4)
                let inherited =
                    rpdfium_page::find_inherited_entry(&self.store, page_dict, &Name::media_box())
                        .ok()??;
                parse_rect_from_obj(&inherited)
            })
            .unwrap_or(Rect::new(0.0, 0.0, 612.0, 792.0));

        Ok(Page {
            store: &self.store,
            font_cache: &self.font_cache,
            page_index: index,
            page_dict_id,
            media_box,
            display_tree: OnceLock::new(),
            options: &self.options,
            oc_context: self.oc_context.as_ref(),
        })
    }

    /// Upstream-aligned alias for [`page()`](Self::page).
    ///
    /// Corresponds to `FPDF_LoadPage`.
    #[inline]
    pub fn load_page(&self, index: u32) -> Result<Page<'_>> {
        self.page(index)
    }

    /// Parse document metadata from the `/Info` dictionary.
    pub fn metadata(&self) -> Result<Option<DocumentMetadata>> {
        match self.store.trailer().info {
            Some(info_id) => {
                let info_obj = self.store.resolve(info_id)?;
                let meta = parse_metadata(info_obj, &self.store)?;
                Ok(Some(meta))
            }
            None => Ok(None),
        }
    }

    /// Parse the document's bookmark (outline) tree.
    pub fn bookmarks(&self) -> Result<Vec<Bookmark>> {
        let catalog_obj = self.store.resolve(self.catalog_id)?;
        let bookmarks = parse_bookmarks(catalog_obj, &self.store)?;
        Ok(bookmarks)
    }

    /// Search the document's bookmark tree for the first bookmark with the
    /// given title (case-sensitive, exact Unicode match).
    ///
    /// Returns `Ok(None)` if no matching bookmark is found.
    /// Corresponds to `FPDFBookmark_Find`.
    pub fn find_bookmark(&self, title: &str) -> Result<Option<Bookmark>> {
        let bookmarks = self.bookmarks()?;
        Ok(find_bookmark(&bookmarks, title).cloned())
    }

    /// Upstream-aligned alias for [`find_bookmark()`](Self::find_bookmark).
    ///
    /// Corresponds to `FPDFBookmark_Find`.
    #[inline]
    pub fn bookmark_find(&self, title: &str) -> Result<Option<Bookmark>> {
        self.find_bookmark(title)
    }

    /// Deprecated — use [`bookmark_find()`](Self::bookmark_find) instead.
    ///
    /// Corresponds to `FPDFBookmark_Find`.
    #[deprecated(note = "use `bookmark_find()` — matches upstream `FPDFBookmark_Find`")]
    #[inline]
    pub fn find(&self, title: &str) -> Result<Option<Bookmark>> {
        self.find_bookmark(title)
    }

    /// Legacy alias — use [`bookmark_find()`](Self::bookmark_find) instead.
    ///
    /// Corresponds to `FPDFBookmark_Find`.
    #[deprecated(note = "use `bookmark_find()` — matches upstream `FPDFBookmark_Find`")]
    #[inline]
    pub fn get_bookmark_by_title(&self, title: &str) -> Result<Option<Bookmark>> {
        self.find_bookmark(title)
    }

    /// Returns the next sibling of `bookmark` within `siblings`, or `None`
    /// if `bookmark` is the last sibling.
    ///
    /// **Architectural note**: PDFium's `FPDFBookmark_GetNextSibling` takes a
    /// document handle and a bookmark handle and follows the PDF `/Next` link
    /// in the raw outline dictionary.  In rpdfium the outline is eagerly
    /// parsed into an owned `Vec<Bookmark>` tree, so the caller must provide
    /// the parent's children slice (or the root slice for top-level siblings).
    ///
    /// Typical usage:
    /// ```ignore
    /// let bms = doc.bookmarks()?;
    /// let second = doc.next_sibling_bookmark(&bms, &bms[0]);
    /// ```
    ///
    /// Corresponds to `FPDFBookmark_GetNextSibling`.
    pub fn next_sibling_bookmark<'a>(
        &self,
        siblings: &'a [Bookmark],
        bookmark: &Bookmark,
    ) -> Option<&'a Bookmark> {
        next_sibling_bookmark(siblings, bookmark)
    }

    /// Upstream-aligned alias for [`next_sibling_bookmark()`](Self::next_sibling_bookmark).
    ///
    /// Corresponds to `FPDFBookmark_GetNextSibling`.
    #[inline]
    pub fn bookmark_get_next_sibling<'a>(
        &self,
        siblings: &'a [Bookmark],
        bookmark: &Bookmark,
    ) -> Option<&'a Bookmark> {
        self.next_sibling_bookmark(siblings, bookmark)
    }

    /// Non-upstream alias — use [`bookmark_get_next_sibling()`](Self::bookmark_get_next_sibling).
    #[deprecated(
        note = "use `bookmark_get_next_sibling()` — matches upstream `FPDFBookmark_GetNextSibling`"
    )]
    #[inline]
    pub fn get_next_sibling<'a>(
        &self,
        siblings: &'a [Bookmark],
        bookmark: &Bookmark,
    ) -> Option<&'a Bookmark> {
        self.next_sibling_bookmark(siblings, bookmark)
    }

    /// Collect all digital signature fields from the document's AcroForm.
    ///
    /// Returns an empty `Vec` if the document has no AcroForm or no signature
    /// fields. Corresponds to `FPDF_GetSignatureCount` /
    /// `FPDF_GetSignatureObject` in PDFium's `fpdf_signature.h`.
    pub fn signatures(&self) -> Result<Vec<SignatureObject>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(collect_signatures(catalog, &self.store)?)
    }

    /// Returns the total number of digital signature fields in the document.
    ///
    /// Corresponds to `FPDF_GetSignatureCount`.
    pub fn signature_count(&self) -> Result<usize> {
        Ok(self.signatures()?.len())
    }

    /// ADR-019 alias for [`signature_count()`](Self::signature_count).
    ///
    /// Corresponds to `FPDF_GetSignatureCount`.
    #[inline]
    pub fn get_signature_count(&self) -> Result<usize> {
        self.signature_count()
    }

    /// Returns the Nth digital signature field (zero-based index).
    ///
    /// Returns `Ok(None)` if `index` is out of range.
    /// Corresponds to `FPDF_GetSignatureObject`.
    pub fn signature_object(&self, index: usize) -> Result<Option<SignatureObject>> {
        let sigs = self.signatures()?;
        Ok(sigs.into_iter().nth(index))
    }

    /// ADR-019 alias for [`signature_object()`](Self::signature_object).
    ///
    /// Corresponds to `FPDF_GetSignatureObject`.
    #[inline]
    pub fn get_signature_object(&self, index: usize) -> Result<Option<SignatureObject>> {
        self.signature_object(index)
    }

    /// Returns one of the file identifier bytes from the PDF trailer `/ID` array.
    ///
    /// PDFs contain a two-element `/ID` array in the trailer dictionary:
    /// - Index 0 (`FileIdentifierType::Permanent`): set when the document is created and
    ///   never changes, even through edits.
    /// - Index 1 (`FileIdentifierType::Changing`): updated each time the document is modified.
    ///
    /// Returns `None` if the document has no `/ID` entry in its trailer.
    /// Corresponds to `FPDF_GetFileIdentifier`.
    pub fn file_identifier(&self, id_type: FileIdentifierType) -> Option<Vec<u8>> {
        self.store
            .trailer()
            .id
            .as_ref()
            .map(|ids| ids[id_type as usize].clone())
    }

    /// ADR-019 alias — see [`Self::file_identifier`].
    #[inline]
    pub fn get_file_identifier(&self, id_type: FileIdentifierType) -> Option<Vec<u8>> {
        self.file_identifier(id_type)
    }

    /// Returns the effective PDF version for this document.
    ///
    /// Per ISO 32000-1 §7.7.2, the document catalog's `/Version` entry overrides
    /// the file header version when present. Returns `(major, minor)`.
    ///
    /// Returns the PDF version as `(major, minor)` — e.g. `(1, 7)` for PDF 1.7.
    /// Corresponds to `FPDF_GetFileVersion`.
    pub fn pdf_version(&self) -> (u8, u8) {
        let header = self.store.file_version();
        let header_pair = (header.major, header.minor);

        // Check catalog /Version override per ISO 32000-1 Table 28
        let catalog_id = self.store.trailer().root;
        let override_ver = (|| -> Option<(u8, u8)> {
            let catalog_obj = self.store.resolve(catalog_id).ok()?;
            let dict = catalog_obj.as_dict()?;
            let ver_val = dict.get(&Name::from_bytes(b"Version".to_vec()))?;
            let resolved = self.store.deep_resolve(ver_val).ok()?;
            let ver_name = resolved.as_name()?;
            let b = ver_name.as_bytes();
            // Must be exactly "M.m" format (e.g. "1.7")
            if b.len() == 3 && b[1] == b'.' && b[0].is_ascii_digit() && b[2].is_ascii_digit() {
                Some((b[0] - b'0', b[2] - b'0'))
            } else {
                None
            }
        })();

        override_ver.unwrap_or(header_pair)
    }

    /// Upstream-aligned alias for [`Self::pdf_version()`].
    ///
    /// Corresponds to `FPDF_GetFileVersion`.
    #[inline]
    pub fn get_file_version(&self) -> (u8, u8) {
        self.pdf_version()
    }

    /// Returns the document access permissions as a raw bit field.
    ///
    /// Returns `None` if the document is not encrypted.
    /// Corresponds to `FPDF_GetDocPermissions`.
    pub fn permissions(&self) -> Option<u32> {
        self.store
            .security_handler()
            .map(|h| h.permissions().bits() as u32)
    }

    /// Non-upstream convenience alias for [`permissions()`](Self::permissions).
    ///
    /// Prefer [`get_doc_user_permissions()`](Self::get_doc_user_permissions),
    /// which matches the upstream `FPDF_GetDocUserPermissions` name exactly.
    ///
    /// Corresponds to `FPDF_GetDocUserPermissions`.
    #[deprecated(
        note = "use `get_doc_user_permissions()` — matches upstream FPDF_GetDocUserPermissions"
    )]
    #[inline]
    pub fn user_permissions(&self) -> Option<u32> {
        self.permissions()
    }

    /// Upstream-aligned alias for [`Self::permissions()`].
    ///
    /// Corresponds to `FPDF_GetDocPermissions`.
    #[inline]
    pub fn get_doc_permissions(&self) -> Option<u32> {
        self.permissions()
    }

    /// Upstream-aligned alias for [`Self::permissions()`].
    ///
    /// Corresponds to `FPDF_GetDocUserPermissions`.
    #[inline]
    pub fn get_doc_user_permissions(&self) -> Option<u32> {
        self.permissions()
    }

    /// Returns the security handler revision number.
    ///
    /// Returns `None` if the document is not encrypted.
    /// Corresponds to `FPDF_GetSecurityHandlerRevision`.
    pub fn security_revision(&self) -> Option<u32> {
        self.store.security_handler().map(|h| h.revision())
    }

    /// Upstream-aligned alias for [`Self::security_revision()`].
    ///
    /// Corresponds to `FPDF_GetSecurityHandlerRevision`.
    #[inline]
    pub fn get_security_handler_revision(&self) -> Option<u32> {
        self.security_revision()
    }

    /// Parse the document's viewer preferences from `/ViewerPreferences`.
    ///
    /// Returns `None` if no `/ViewerPreferences` dictionary is present in
    /// the catalog.  Corresponds to the `FPDF_VIEWERREF_*` family.
    pub fn viewer_preferences(&self) -> Result<Option<ViewerPreferences>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        let catalog_dict = catalog
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.catalog_id))?;
        let vp_obj = match catalog_dict
            .get(&Name::viewer_preferences())
            .and_then(|o| self.store.deep_resolve(o).ok())
        {
            Some(o) => o,
            None => return Ok(None),
        };
        let vp_dict = match vp_obj.as_dict() {
            Some(d) => d,
            None => return Ok(None),
        };
        Ok(Some(ViewerPreferences::from_dict(vp_dict, &self.store)))
    }

    /// Returns whether print scaling is enabled for this document.
    ///
    /// Returns `true` (scaling enabled) when `/PrintScaling` is absent or not
    /// `"None"`; returns `false` when scaling is suppressed.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetPrintScaling`.
    pub fn viewerref_get_print_scaling(&self) -> Result<bool> {
        Ok(self
            .viewer_preferences()?
            .map(|vp| vp.print_scaling())
            .unwrap_or(true))
    }

    /// Returns the number of copies to print as specified in viewer preferences.
    ///
    /// Returns `1` if no `/NumCopies` entry is present.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetNumCopies`.
    pub fn viewerref_get_num_copies(&self) -> Result<i32> {
        Ok(self
            .viewer_preferences()?
            .and_then(|vp| vp.num_copies())
            .map(|n| n as i32)
            .unwrap_or(1))
    }

    /// Returns the print page range from viewer preferences, if any.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetPrintPageRange`.
    pub fn viewerref_get_print_page_range(&self) -> Result<Option<Vec<i64>>> {
        Ok(self
            .viewer_preferences()?
            .and_then(|vp| vp.print_page_range().map(|r| r.to_vec())))
    }

    /// Returns the number of elements in a print page range slice.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetPrintPageRangeCount`.
    pub fn viewerref_get_print_page_range_count(&self, range: &[i64]) -> usize {
        range.len()
    }

    /// Returns the element at `index` within a print page range slice.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetPrintPageRangeElement`.
    pub fn viewerref_get_print_page_range_element(
        &self,
        range: &[i64],
        index: usize,
    ) -> Option<i64> {
        range.get(index).copied()
    }

    /// Returns the duplex printing mode from viewer preferences.
    ///
    /// Returns `DuplexMode::Simplex` if no `/Duplex` entry is present.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetDuplex`.
    pub fn viewerref_get_duplex(&self) -> Result<DuplexMode> {
        Ok(self
            .viewer_preferences()?
            .map(|vp| vp.duplex_mode())
            .unwrap_or(DuplexMode::Simplex))
    }

    /// Returns the value of a named viewer preference entry.
    ///
    /// Looks up `key` in the `/ViewerPreferences` dictionary and returns the
    /// value as a string. Returns `None` if absent or not a string/name.
    ///
    /// Corresponds to `FPDF_VIEWERREF_GetName`.
    pub fn viewerref_get_name(&self, key: &str) -> Result<Option<String>> {
        Ok(self
            .viewer_preferences()?
            .and_then(|vp| vp.generic_name(key).map(|s| s.to_owned())))
    }

    /// Collect all embedded file attachments from `/Root/Names/EmbeddedFiles`.
    ///
    /// Returns an empty `Vec` if the document has no attachments.
    /// Corresponds to `FPDFDoc_GetAttachmentCount` / `FPDFDoc_GetAttachment`.
    pub fn attachments(&self) -> Result<Vec<FileSpec>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(collect_attachments(catalog, &self.store)?)
    }

    /// Returns the number of embedded file attachments in the document.
    ///
    /// Corresponds to `FPDFDoc_GetAttachmentCount`.
    pub fn attachment_count(&self) -> Result<usize> {
        Ok(self.attachments()?.len())
    }

    /// Upstream-aligned alias for [`attachment_count()`](Self::attachment_count).
    ///
    /// Corresponds to `FPDFDoc_GetAttachmentCount`.
    #[inline]
    pub fn doc_get_attachment_count(&self) -> Result<usize> {
        self.attachment_count()
    }

    #[deprecated(
        note = "use `doc_get_attachment_count()` — matches upstream `FPDFDoc_GetAttachmentCount`"
    )]
    #[inline]
    pub fn get_attachment_count(&self) -> Result<usize> {
        self.attachment_count()
    }

    /// Returns the embedded file attachment at the given zero-based index.
    ///
    /// Returns `Ok(None)` if `index` is out of range.
    ///
    /// Corresponds to `FPDFDoc_GetAttachment`.
    pub fn attachment_at(&self, index: usize) -> Result<Option<FileSpec>> {
        let all = self.attachments()?;
        Ok(all.into_iter().nth(index))
    }

    /// Upstream-aligned alias for [`attachment_at()`](Self::attachment_at).
    ///
    /// Corresponds to `FPDFDoc_GetAttachment`.
    #[inline]
    pub fn doc_get_attachment(&self, index: usize) -> Result<Option<FileSpec>> {
        self.attachment_at(index)
    }

    #[deprecated(note = "use `doc_get_attachment()` — matches upstream `FPDFDoc_GetAttachment`")]
    #[inline]
    pub fn get_attachment(&self, index: usize) -> Result<Option<FileSpec>> {
        self.attachment_at(index)
    }

    /// Collect all named destinations from the document catalog.
    ///
    /// Returns a `Vec` of `(name, Destination)` pairs from the `/Names/Dests`
    /// name tree, or from the old-style `/Dests` dictionary.
    /// Corresponds to `FPDF_CountNamedDests` / `FPDF_GetNamedDest`.
    pub fn named_destinations(&self) -> Result<Vec<(String, Destination)>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(collect_named_destinations(catalog, &self.store)?)
    }

    /// Look up a named destination by name.
    ///
    /// Searches the document's named-destination table (`/Names/Dests` or the
    /// old-style `/Dests` dictionary) for an entry whose key matches `name`
    /// exactly (case-sensitive).
    ///
    /// Returns `Ok(Some(dest))` if found, `Ok(None)` if no such name exists.
    ///
    /// Corresponds to `FPDF_GetNamedDestByName`.
    pub fn named_dest_by_name(&self, name: &str) -> Result<Option<Destination>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        let dests = collect_named_destinations(catalog, &self.store)?;
        Ok(dests.into_iter().find(|(n, _)| n == name).map(|(_, d)| d))
    }

    /// Upstream-aligned alias for [`Self::named_dest_by_name()`].
    ///
    /// Corresponds to `FPDF_GetNamedDestByName`.
    #[inline]
    pub fn get_named_dest_by_name(&self, name: &str) -> Result<Option<Destination>> {
        self.named_dest_by_name(name)
    }

    /// Returns the total number of named destinations in the document.
    ///
    /// Counts entries in `/Names/Dests` (name tree) or the legacy `/Dests`
    /// dictionary in the document catalog.
    ///
    /// Corresponds to `FPDF_CountNamedDests`.
    pub fn named_dest_count(&self) -> Result<u32> {
        let dests = self.named_destinations()?;
        Ok(dests.len() as u32)
    }

    /// ADR-019 alias for [`named_dest_count()`](Self::named_dest_count).
    ///
    /// Corresponds to `FPDF_CountNamedDests`.
    #[inline]
    pub fn count_named_dests(&self) -> Result<u32> {
        self.named_dest_count()
    }

    /// Returns the named destination at the given 0-based index.
    ///
    /// Returns the `(name, Destination)` pair at `index` in the collection
    /// returned by [`named_destinations()`](Self::named_destinations), or
    /// `Ok(None)` if the index is out of range.
    ///
    /// Corresponds to `FPDF_GetNamedDest`.
    pub fn named_dest_at(&self, index: usize) -> Result<Option<(String, Destination)>> {
        let dests = self.named_destinations()?;
        Ok(dests.into_iter().nth(index))
    }

    /// ADR-019 alias for [`named_dest_at()`](Self::named_dest_at).
    ///
    /// Corresponds to `FPDF_GetNamedDest`.
    #[inline]
    pub fn get_named_dest(&self, index: usize) -> Result<Option<(String, Destination)>> {
        self.named_dest_at(index)
    }

    /// Returns a specific metadata tag value from the document's `/Info`
    /// dictionary.
    ///
    /// `tag` is one of: `"Title"`, `"Author"`, `"Subject"`, `"Keywords"`,
    /// `"Creator"`, `"Producer"`, `"CreationDate"`, `"ModDate"`.
    ///
    /// Returns `Ok(None)` if the tag is not present in the document or if
    /// the document has no `/Info` dictionary.
    ///
    /// Corresponds to `FPDF_GetMetaText`.
    pub fn meta_text(&self, tag: &str) -> Result<Option<String>> {
        let meta = match self.metadata()? {
            Some(m) => m,
            None => return Ok(None),
        };
        let value = match tag {
            "Title" => meta.title,
            "Author" => meta.author,
            "Subject" => meta.subject,
            "Keywords" => meta.keywords,
            "Creator" => meta.creator,
            "Producer" => meta.producer,
            "CreationDate" => meta.creation_date,
            "ModDate" => meta.mod_date,
            _ => None,
        };
        Ok(value)
    }

    /// ADR-019 alias for [`meta_text()`](Self::meta_text).
    ///
    /// Corresponds to `FPDF_GetMetaText`.
    #[inline]
    pub fn get_meta_text(&self, tag: &str) -> Result<Option<String>> {
        self.meta_text(tag)
    }

    /// Returns the formatted page label for the given 0-based page index.
    ///
    /// The label is computed by resolving the page label ranges from the
    /// document's `/PageLabels` number tree, then formatting the label for
    /// the specific page using [`format_label`].
    ///
    /// Returns `Ok(None)` if the document has no page labels or the page
    /// index is out of range.
    ///
    /// Corresponds to `FPDF_GetPageLabel`.
    pub fn page_label(&self, page_index: u32) -> Result<Option<String>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        let labels = parse_page_labels(catalog, &self.store)?;
        if labels.is_empty() {
            return Ok(None);
        }
        let idx = page_index as i64;
        // Find the last label range whose start is <= page_index.
        let range_entry = labels.iter().rfind(|(start, _)| *start <= idx);
        match range_entry {
            Some((range_start, label)) => {
                let offset = idx - range_start;
                Ok(Some(format_label(label, offset)))
            }
            None => Ok(None),
        }
    }

    /// ADR-019 alias for [`page_label()`](Self::page_label).
    ///
    /// Corresponds to `FPDF_GetPageLabel`.
    #[inline]
    pub fn get_page_label(&self, page_index: u32) -> Result<Option<String>> {
        self.page_label(page_index)
    }

    /// Parse the tagged PDF structure tree from the document catalog.
    ///
    /// Returns `Ok(None)` if the document has no `/StructTreeRoot` entry (i.e.,
    /// it is not a tagged PDF document).
    ///
    /// Corresponds to `FPDF_StructTree_GetForPage` in concept — the full document
    /// structure tree is returned rather than just a page-filtered view.
    /// Use [`StructTree::elements_for_page`] or [`PageStructure::for_page`] to
    /// filter the tree to a specific page.
    pub fn structure_tree(&self) -> Result<Option<StructTree>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        let catalog_dict = catalog
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.catalog_id))?;
        Ok(StructTree::from_catalog(catalog_dict, &self.store)?)
    }

    /// ADR-019 T2 alias for [`structure_tree()`](Self::structure_tree).
    ///
    /// Exact snake_case of `FPDF_StructTree_GetForPage` (strip `FPDF_` prefix).
    /// Note: rpdfium returns the full document tree rather than a page-filtered
    /// view, because the parser has no page-level filtering at this layer.
    #[inline]
    pub fn struct_tree_get_for_page(&self) -> Result<Option<StructTree>> {
        self.structure_tree()
    }

    /// Deprecated non-upstream alias — use
    /// [`struct_tree_get_for_page()`](Self::struct_tree_get_for_page) instead.
    ///
    /// `get_for_page` strips too much of the upstream name `FPDF_StructTree_GetForPage`.
    /// The correct T2 alias is [`struct_tree_get_for_page()`](Self::struct_tree_get_for_page).
    #[deprecated(
        note = "use `struct_tree_get_for_page()` — exact T2 alias for FPDF_StructTree_GetForPage"
    )]
    #[inline]
    pub fn get_for_page(&self) -> Result<Option<StructTree>> {
        self.structure_tree()
    }

    /// Deprecated non-upstream alias — use
    /// [`struct_tree_get_for_page()`](Self::struct_tree_get_for_page) instead.
    ///
    /// Corresponds to `FPDF_StructTree_GetForPage`.
    #[deprecated(
        note = "use `struct_tree_get_for_page()` — exact T2 alias for FPDF_StructTree_GetForPage"
    )]
    #[inline]
    pub fn get_structure_tree(&self) -> Result<Option<StructTree>> {
        self.structure_tree()
    }

    /// Returns `true` if the document is a tagged PDF.
    ///
    /// Checks the `/MarkInfo/Marked` boolean in the document catalog.
    /// Returns `false` if the document has no `/MarkInfo` entry or if
    /// `/Marked` is absent or `false`.
    ///
    /// Corresponds to `FPDFCatalog_IsTagged`.
    pub fn is_tagged(&self) -> Result<bool> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(is_tagged(catalog, &self.store))
    }

    /// Upstream-aligned alias for [`is_tagged()`](Self::is_tagged).
    ///
    /// Corresponds to `FPDFCatalog_IsTagged`.
    #[inline]
    pub fn catalog_is_tagged(&self) -> Result<bool> {
        self.is_tagged()
    }

    /// Returns the document's initial page display mode.
    ///
    /// Reads `/PageMode` from the document catalog.
    /// Returns [`PageMode::Unknown`] if the entry is absent or unrecognised.
    ///
    /// Corresponds to `FPDFDoc_GetPageMode`.
    pub fn page_mode(&self) -> Result<PageMode> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(page_mode(catalog, &self.store))
    }

    /// Upstream-aligned alias for [`page_mode()`](Self::page_mode).
    ///
    /// Corresponds to `FPDFDoc_GetPageMode`.
    #[inline]
    pub fn doc_get_page_mode(&self) -> Result<PageMode> {
        self.page_mode()
    }

    /// Deprecated: use [`doc_get_page_mode()`](Self::doc_get_page_mode) — matches upstream `FPDFDoc_GetPageMode`.
    #[deprecated(note = "use `doc_get_page_mode()` — matches upstream `FPDFDoc_GetPageMode`")]
    #[inline]
    pub fn get_page_mode(&self) -> Result<PageMode> {
        self.page_mode()
    }

    /// Returns the type of interactive form contained in the document.
    ///
    /// Inspects `/Root/AcroForm` and the nested `/XFA` key as well as the
    /// catalog's `/NeedsRendering` boolean to distinguish between no form,
    /// AcroForm, XFA-full, and XFA-foreground form types.
    ///
    /// Returns [`PdfFormType::None`] if there is no form or the catalog
    /// cannot be resolved.
    ///
    /// Corresponds to `FPDF_GetFormType` in PDFium's `fpdf_formfill.h`
    /// (implemented in `fpdfsdk/fpdf_view.cpp`).
    pub fn form_type(&self) -> Result<PdfFormType> {
        let catalog = self.store.resolve(self.catalog_id)?;
        Ok(rpdfium_doc::pdf_form_type(catalog, &self.store))
    }

    /// ADR-019 alias for [`form_type()`](Self::form_type).
    ///
    /// Corresponds to `FPDF_GetFormType`.
    #[inline]
    pub fn get_form_type(&self) -> Result<PdfFormType> {
        self.form_type()
    }

    /// Attempt to load XFA form data for the document.
    ///
    /// # Not Supported
    ///
    /// rpdfium does not implement the XFA runtime environment. XFA form
    /// rendering and execution require a full XFA processor which is out of
    /// scope for this library (ADR-017 stub).
    ///
    /// Always returns `Err(NotSupported(...))`. Use [`Self::form_type()`] to
    /// detect whether the document contains XFA forms.
    ///
    /// Corresponds to `FPDF_LoadXFA` in PDFium's `fpdf_formfill.h`.
    pub fn load_xfa(&self) -> Result<()> {
        Err(Error::Doc(DocError::NotSupported(
            "load_xfa: XFA form processing is not implemented in rpdfium".into(),
        )))
    }

    /// Get a page-level additional action from the page's `/AA` dictionary.
    ///
    /// PDF page dictionaries can contain an `/AA` entry (ISO 32000-2 Table 197)
    /// with optional `/O` (open) and `/C` (close) action entries.
    ///
    /// Returns `Ok(None)` if:
    /// - `page_index` is out of range,
    /// - the page has no `/AA` dictionary,
    /// - the requested action key is absent in the `/AA` dict.
    ///
    /// Corresponds to `FPDF_GetPageAAction` in PDFium.
    pub fn page_additional_action(
        &self,
        page_index: usize,
        action_type: PageActionType,
    ) -> Result<Option<Action>> {
        if page_index >= self.page_ids.len() {
            return Ok(None);
        }
        let page_dict_id = self.page_ids[page_index];
        let page_obj = self.store.resolve(page_dict_id)?;
        let page_dict = match page_obj.as_dict() {
            Some(d) => d,
            None => return Ok(None),
        };

        // Look for /AA in the page dict
        let aa_obj = match page_dict.get(&Name::aa()) {
            Some(obj) => obj,
            None => return Ok(None),
        };

        // Resolve /AA to a dict
        let aa_resolved = match self.store.deep_resolve(aa_obj) {
            Ok(obj) => obj,
            Err(_) => return Ok(None),
        };
        let aa_dict = match aa_resolved.as_dict() {
            Some(d) => d,
            None => return Ok(None),
        };

        // Look for the specific action key (/O or /C)
        let key = Name::from(action_type.pdf_key());
        let action_obj = match aa_dict.get(&key) {
            Some(obj) => obj,
            None => return Ok(None),
        };

        // Parse the action
        match rpdfium_doc::action::parse_action(action_obj, &self.store) {
            Ok(action) => Ok(Some(action)),
            Err(_) => Ok(None),
        }
    }

    /// Upstream-aligned alias for [`page_additional_action()`](Self::page_additional_action).
    ///
    /// Corresponds to `FPDF_GetPageAAction`.
    #[inline]
    pub fn get_page_a_action(
        &self,
        page_index: usize,
        action_type: PageActionType,
    ) -> Result<Option<Action>> {
        self.page_additional_action(page_index, action_type)
    }

    /// Legacy alias — use [`get_page_a_action()`](Self::get_page_a_action) instead.
    ///
    /// Corresponds to `FPDF_GetPageAAction`.
    #[deprecated(note = "Use `get_page_a_action()` (strict upstream name)")]
    #[inline]
    pub fn get_page_additional_action(
        &self,
        page_index: usize,
        action_type: PageActionType,
    ) -> Result<Option<Action>> {
        self.page_additional_action(page_index, action_type)
    }

    /// Returns the z-order (painting order) of the link annotation closest to
    /// the given point on the specified page.
    ///
    /// # Not Supported
    ///
    /// rpdfium does not track per-annotation painting order (z-order). This
    /// stub is provided for API completeness per ADR-017.
    ///
    /// Corresponds to `FPDFLink_GetLinkZOrderAtPoint()` in PDFium's
    /// `fpdf_doc.h`.
    pub fn link_z_order_at_point(&self, _page_index: usize, _x: f64, _y: f64) -> Result<i32> {
        Err(Error::Doc(DocError::NotSupported(
            "link_z_order_at_point: annotation z-order tracking is not implemented".into(),
        )))
    }

    /// ADR-019 Tier 2 alias for [`link_z_order_at_point()`](Self::link_z_order_at_point).
    ///
    /// Corresponds to `FPDFLink_GetLinkZOrderAtPoint`.
    #[inline]
    pub fn link_get_link_z_order_at_point(&self, page_index: usize, x: f64, y: f64) -> Result<i32> {
        self.link_z_order_at_point(page_index, x, y)
    }

    /// Use [`link_get_link_z_order_at_point()`](Self::link_get_link_z_order_at_point) — matches
    /// upstream `FPDFLink_GetLinkZOrderAtPoint`.
    #[deprecated(
        note = "use `link_get_link_z_order_at_point()` — matches upstream `FPDFLink_GetLinkZOrderAtPoint`"
    )]
    #[inline]
    pub fn get_link_z_order_at_point(&self, page_index: usize, x: f64, y: f64) -> Result<i32> {
        self.link_z_order_at_point(page_index, x, y)
    }

    /// Returns true if the cross-reference table was rebuilt during parsing (Lenient mode).
    ///
    /// Non-upstream convenience accessor — prefer
    /// [`has_valid_cross_reference_table()`](Self::has_valid_cross_reference_table) which
    /// corresponds to the public `FPDF_DocumentHasValidCrossReferenceTable` API.
    #[deprecated(
        note = "use `has_valid_cross_reference_table()` — matches upstream FPDF_DocumentHasValidCrossReferenceTable"
    )]
    #[inline]
    pub fn xref_rebuilt(&self) -> bool {
        self.store.xref_table_rebuilt()
    }

    /// Returns `true` if the document's cross-reference table was intact when loaded.
    /// Returns `false` if the parser had to rebuild (repair) the xref table due to corruption.
    ///
    /// Corresponds to `FPDF_DocumentHasValidCrossReferenceTable`.
    pub fn has_valid_cross_reference_table(&self) -> bool {
        !self.store.xref_table_rebuilt()
    }

    /// Upstream-aligned alias for [`Self::has_valid_cross_reference_table()`].
    ///
    /// Corresponds to `FPDF_DocumentHasValidCrossReferenceTable`.
    #[inline]
    pub fn document_has_valid_cross_reference_table(&self) -> bool {
        self.has_valid_cross_reference_table()
    }

    /// Returns the byte offsets of all `%%EOF` / trailer section ends in the PDF.
    ///
    /// Corresponds to `FPDF_GetTrailerEnds`. Returns an empty vec if the positions
    /// cannot be determined from in-memory data.
    ///
    /// # Not Supported
    ///
    /// Full trailer-end tracking requires recording positions during parse and is
    /// not currently implemented (ADR: implementation complexity vs. use case).
    pub fn trailer_ends(&self) -> Vec<u64> {
        Vec::new()
    }

    /// Upstream-aligned alias for [`Self::trailer_ends()`].
    ///
    /// Corresponds to `FPDF_GetTrailerEnds`.
    #[inline]
    pub fn get_trailer_ends(&self) -> Vec<u64> {
        self.trailer_ends()
    }

    /// Returns the page dimensions at the given zero-based page index.
    ///
    /// Corresponds to `FPDF_GetPageSizeByIndexF`.
    pub fn page_size_by_index_f(&self, index: u32) -> Result<(f32, f32)> {
        let page = self.page(index)?;
        let mb = page.media_box();
        Ok((mb.width() as f32, mb.height() as f32))
    }

    /// Upstream-aligned alias for [`page_size_by_index_f()`](Self::page_size_by_index_f).
    ///
    /// Corresponds to `FPDF_GetPageSizeByIndexF`.
    #[inline]
    pub fn get_page_size_by_index_f(&self, index: u32) -> Result<(f32, f32)> {
        self.page_size_by_index_f(index)
    }

    // -----------------------------------------------------------------------
    // Catalog language (FPDFCatalog_GetLanguage)
    // -----------------------------------------------------------------------

    /// Returns the document's language tag from the catalog `/Lang` entry.
    ///
    /// Returns `Ok(None)` when the catalog has no `/Lang` entry.
    ///
    /// Corresponds to `FPDFCatalog_GetLanguage`.
    pub fn catalog_language(&self) -> Result<Option<String>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        let dict = match catalog.as_dict() {
            Some(d) => d,
            None => return Ok(None),
        };
        let lang = match dict.get(&Name::lang()) {
            Some(o) => o,
            None => return Ok(None),
        };
        let resolved = self
            .store
            .deep_resolve(lang)
            .map_err(|e| Error::Doc(DocError::NotSupported(e.to_string())))?;
        if let Some(s) = resolved.as_string() {
            return Ok(Some(s.to_string_lossy()));
        }
        Ok(None)
    }

    /// Upstream-aligned alias for [`catalog_language()`](Self::catalog_language).
    ///
    /// Corresponds to `FPDFCatalog_GetLanguage`.
    #[inline]
    pub fn catalog_get_language(&self) -> Result<Option<String>> {
        self.catalog_language()
    }

    // -----------------------------------------------------------------------
    // Page size by index (FPDF_GetPageSizeByIndex)
    // -----------------------------------------------------------------------

    /// Returns the page dimensions (width, height) at the given zero-based page
    /// index as `f64` values.
    ///
    /// Corresponds to `FPDF_GetPageSizeByIndex` (the `double`-returning variant).
    /// For the `float` variant see [`page_size_by_index_f()`](Self::page_size_by_index_f).
    pub fn page_size_by_index(&self, index: u32) -> Result<(f64, f64)> {
        let (w, h) = self.page_size_by_index_f(index)?;
        Ok((f64::from(w), f64::from(h)))
    }

    /// Upstream-aligned alias for [`page_size_by_index()`](Self::page_size_by_index).
    ///
    /// Corresponds to `FPDF_GetPageSizeByIndex`.
    #[inline]
    pub fn get_page_size_by_index(&self, index: u32) -> Result<(f64, f64)> {
        self.page_size_by_index(index)
    }

    // -----------------------------------------------------------------------
    // Document-level JavaScript actions (fpdf_javascript.h)
    // -----------------------------------------------------------------------

    /// Returns all document-level JavaScript actions from the `/Names/JavaScript`
    /// name tree.
    ///
    /// Returns an empty `Vec` when the document has no JavaScript name tree.
    ///
    /// Corresponds to `FPDFDoc_GetJavaScriptActionCount` +
    /// `FPDFDoc_GetJavaScriptAction` from `fpdf_javascript.h`.
    pub fn javascript_actions(&self) -> Result<Vec<JavaScriptAction>> {
        let catalog = self.store.resolve(self.catalog_id)?;
        collect_javascript_actions(catalog, &self.store).map_err(Error::Doc)
    }

    /// Returns the number of document-level JavaScript actions.
    ///
    /// Corresponds to `FPDFDoc_GetJavaScriptActionCount`.
    pub fn javascript_action_count(&self) -> Result<usize> {
        Ok(self.javascript_actions()?.len())
    }

    /// Upstream-aligned alias for [`javascript_action_count()`](Self::javascript_action_count).
    ///
    /// Corresponds to `FPDFDoc_GetJavaScriptActionCount`.
    #[inline]
    pub fn doc_get_javascript_action_count(&self) -> Result<usize> {
        self.javascript_action_count()
    }

    /// Returns the JavaScript action at the given index, or `None` if out of range.
    ///
    /// Corresponds to `FPDFDoc_GetJavaScriptAction`.
    pub fn javascript_action_at(&self, index: usize) -> Result<Option<JavaScriptAction>> {
        let mut actions = self.javascript_actions()?;
        if index < actions.len() {
            Ok(Some(actions.swap_remove(index)))
        } else {
            Ok(None)
        }
    }

    /// Upstream-aligned alias for [`javascript_action_at()`](Self::javascript_action_at).
    ///
    /// Corresponds to `FPDFDoc_GetJavaScriptAction`.
    #[inline]
    pub fn doc_get_javascript_action(&self, index: usize) -> Result<Option<JavaScriptAction>> {
        self.javascript_action_at(index)
    }

    /// Returns a reference to the underlying object store.
    pub fn store(&self) -> &ObjectStore<Arc<[u8]>> {
        &self.store
    }
}

// ---------------------------------------------------------------------------
// Page
// ---------------------------------------------------------------------------

/// A single page within a [`Document`].
pub struct Page<'doc> {
    store: &'doc ObjectStore<Arc<[u8]>>,
    font_cache: &'doc DashMapFontCache,
    page_index: u32,
    page_dict_id: ObjectId,
    media_box: Rect,
    display_tree: OnceLock<DisplayTree>,
    options: &'doc OpenOptions,
    oc_context: Option<&'doc rpdfium_page::OCContext>,
}

impl<'doc> Page<'doc> {
    /// Returns the page's media box (the bounding box of the physical medium).
    ///
    /// Corresponds to `FPDFPage_GetMediaBox`.
    pub fn media_box(&self) -> Rect {
        self.media_box
    }

    /// Upstream-aligned alias for [`Self::media_box()`].
    ///
    /// Corresponds to `FPDFPage_GetMediaBox`.
    #[inline]
    pub fn page_get_media_box(&self) -> Rect {
        self.media_box()
    }

    #[deprecated(note = "use `page_get_media_box()` — matches upstream `FPDFPage_GetMediaBox`")]
    #[inline]
    pub fn get_media_box(&self) -> Rect {
        self.media_box()
    }

    /// Returns the page width in points as `f32`.
    ///
    /// Corresponds to `FPDF_GetPageWidthF`.
    pub fn page_width_f(&self) -> f32 {
        self.media_box.width() as f32
    }

    /// Upstream-aligned alias for [`Self::page_width_f()`].
    ///
    /// Corresponds to `FPDF_GetPageWidthF`.
    #[inline]
    pub fn get_page_width_f(&self) -> f32 {
        self.page_width_f()
    }

    /// Returns the page width in points as `f64`.
    ///
    /// Corresponds to `FPDF_GetPageWidth`.
    pub fn page_width(&self) -> f64 {
        self.media_box.width()
    }

    /// Upstream-aligned alias for [`Self::page_width()`].
    ///
    /// Corresponds to `FPDF_GetPageWidth`.
    #[inline]
    pub fn get_page_width(&self) -> f64 {
        self.page_width()
    }

    /// Returns the page height in points as `f32`.
    ///
    /// Corresponds to `FPDF_GetPageHeightF`.
    pub fn page_height_f(&self) -> f32 {
        self.media_box.height() as f32
    }

    /// Upstream-aligned alias for [`Self::page_height_f()`].
    ///
    /// Corresponds to `FPDF_GetPageHeightF`.
    #[inline]
    pub fn get_page_height_f(&self) -> f32 {
        self.page_height_f()
    }

    /// Returns the page height in points as `f64`.
    ///
    /// Corresponds to `FPDF_GetPageHeight`.
    pub fn page_height(&self) -> f64 {
        self.media_box.height()
    }

    /// Upstream-aligned alias for [`Self::page_height()`].
    ///
    /// Corresponds to `FPDF_GetPageHeight`.
    #[inline]
    pub fn get_page_height(&self) -> f64 {
        self.page_height()
    }

    /// Returns the page's crop box, if explicitly set.
    ///
    /// Defaults to the media box per the PDF spec if not present, but this
    /// method returns `None` when the key is absent.
    /// Corresponds to `FPDFPage_GetCropBox`.
    pub fn crop_box(&self) -> Result<Option<Rect>> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        Ok(parse_rect(page_dict, &Name::crop_box(), self.store))
    }

    /// Upstream-aligned alias for [`Self::crop_box()`].
    ///
    /// Corresponds to `FPDFPage_GetCropBox`.
    #[inline]
    pub fn page_get_crop_box(&self) -> Result<Option<Rect>> {
        self.crop_box()
    }

    #[deprecated(note = "use `page_get_crop_box()` — matches upstream `FPDFPage_GetCropBox`")]
    #[inline]
    pub fn get_crop_box(&self) -> Result<Option<Rect>> {
        self.crop_box()
    }

    /// Returns the page's bleed box, if explicitly set.
    ///
    /// Corresponds to `FPDFPage_GetBleedBox`.
    pub fn bleed_box(&self) -> Result<Option<Rect>> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        Ok(parse_rect(page_dict, &Name::bleed_box(), self.store))
    }

    /// Upstream-aligned alias for [`Self::bleed_box()`].
    ///
    /// Corresponds to `FPDFPage_GetBleedBox`.
    #[inline]
    pub fn page_get_bleed_box(&self) -> Result<Option<Rect>> {
        self.bleed_box()
    }

    #[deprecated(note = "use `page_get_bleed_box()` — matches upstream `FPDFPage_GetBleedBox`")]
    #[inline]
    pub fn get_bleed_box(&self) -> Result<Option<Rect>> {
        self.bleed_box()
    }

    /// Returns the page's trim box, if explicitly set.
    ///
    /// Corresponds to `FPDFPage_GetTrimBox`.
    pub fn trim_box(&self) -> Result<Option<Rect>> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        Ok(parse_rect(page_dict, &Name::trim_box(), self.store))
    }

    /// Upstream-aligned alias for [`Self::trim_box()`].
    ///
    /// Corresponds to `FPDFPage_GetTrimBox`.
    #[inline]
    pub fn page_get_trim_box(&self) -> Result<Option<Rect>> {
        self.trim_box()
    }

    #[deprecated(note = "use `page_get_trim_box()` — matches upstream `FPDFPage_GetTrimBox`")]
    #[inline]
    pub fn get_trim_box(&self) -> Result<Option<Rect>> {
        self.trim_box()
    }

    /// Returns the page's art box, if explicitly set.
    ///
    /// Corresponds to `FPDFPage_GetArtBox`.
    pub fn art_box(&self) -> Result<Option<Rect>> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        Ok(parse_rect(page_dict, &Name::art_box(), self.store))
    }

    /// Upstream-aligned alias for [`Self::art_box()`].
    ///
    /// Corresponds to `FPDFPage_GetArtBox`.
    #[inline]
    pub fn page_get_art_box(&self) -> Result<Option<Rect>> {
        self.art_box()
    }

    #[deprecated(note = "use `page_get_art_box()` — matches upstream `FPDFPage_GetArtBox`")]
    #[inline]
    pub fn get_art_box(&self) -> Result<Option<Rect>> {
        self.art_box()
    }

    /// Returns the page bounding box: intersection of media box and crop box.
    ///
    /// If no crop box is set, returns the media box.
    /// Corresponds to `FPDF_GetPageBoundingBox`.
    pub fn bounding_box(&self) -> Result<Rect> {
        let crop = self.crop_box()?;
        let media = self.media_box;
        Ok(match crop {
            Some(c) => Rect::new(
                media.left.max(c.left),
                media.bottom.max(c.bottom),
                media.right.min(c.right),
                media.top.min(c.top),
            ),
            None => media,
        })
    }

    /// Upstream-aligned alias for [`Self::bounding_box()`].
    ///
    /// Corresponds to `FPDF_GetPageBoundingBox`.
    #[inline]
    pub fn get_page_bounding_box(&self) -> Result<Rect> {
        self.bounding_box()
    }

    /// Returns the page rotation in degrees (0, 90, 180, or 270).
    ///
    /// Corresponds to `FPDFPage_GetRotation`.
    pub fn rotation(&self) -> Result<u32> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        let rotation = page_dict
            .get(&Name::rotate())
            .and_then(|obj| self.store.deep_resolve(obj).ok().and_then(|o| o.as_i64()))
            .unwrap_or(0);
        // Normalize to 0-359 range (handles negative values from malformed PDFs)
        Ok(rotation.rem_euclid(360) as u32)
    }

    /// Upstream-aligned alias for [`Self::rotation()`].
    ///
    /// Corresponds to `FPDFPage_GetRotation`.
    #[inline]
    pub fn page_get_rotation(&self) -> Result<u32> {
        self.rotation()
    }

    /// Non-upstream alias — use [`page_get_rotation()`](Self::page_get_rotation) instead.
    ///
    /// Corresponds to `FPDFPage_GetRotation`.
    #[deprecated(note = "use `page_get_rotation()` — matches upstream `FPDFPage_GetRotation`")]
    #[inline]
    pub fn get_rotation(&self) -> Result<u32> {
        self.rotation()
    }

    /// Non-upstream alias — use [`page_get_rotation()`](Self::page_get_rotation) instead.
    ///
    /// Corresponds to `FPDFPage_GetRotation`.
    #[deprecated(note = "use `page_get_rotation()` — matches upstream `FPDFPage_GetRotation`")]
    #[inline]
    pub fn get_page_rotation(&self) -> Result<u32> {
        self.rotation()
    }

    /// Interpret the page content stream into a display tree.
    ///
    /// The result is cached in a `OnceLock` so subsequent calls return
    /// the same tree without re-interpretation.
    pub fn interpret(&self) -> Result<&DisplayTree> {
        if let Some(tree) = self.display_tree.get() {
            return Ok(tree);
        }

        let tree = self.interpret_inner()?;

        // Store the tree; if another thread raced us, that's fine — we
        // just discard ours and use theirs.
        let _ = self.display_tree.set(tree);
        Ok(self.display_tree.get().unwrap())
    }

    /// Internal interpretation logic.
    fn interpret_inner(&self) -> Result<DisplayTree> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;

        // Decode content stream(s)
        let content_bytes = decode_page_contents(page_dict, self.store)?;

        // Tokenize
        let operators = tokenize_content_stream(&content_bytes)?;

        // Resolve resources
        let resources = resolve_resources(self.store, page_dict)?;

        // Create the font cache bridge
        let bridge = FontCacheBridge {
            font_cache: self.font_cache,
            store: self.store,
            resources: &resources,
        };

        let ctx = InterpreterContext {
            store: self.store,
            font_cache: &bridge,
            mode: self.options.parsing_mode,
            oc_context: self.oc_context,
        };

        let tree = interpret(
            &operators,
            &ctx,
            &resources,
            self.options.max_operators_per_page,
        )?;
        Ok(tree)
    }

    /// Render the page to a bitmap.
    ///
    /// Corresponds to `FPDF_RenderPageBitmap`.
    pub fn render(&self, config: &RenderConfig) -> Result<rpdfium_graphics::Bitmap> {
        let tree = self.interpret()?;
        let decoder = image_decode::PdfImageDecoder::new(self.store);
        let bitmap = rpdfium_render::render_with_images(tree, config, &decoder)?;
        Ok(bitmap)
    }

    /// Upstream-aligned alias for [`render()`](Self::render).
    ///
    /// Corresponds to `FPDF_RenderPageBitmap`.
    #[inline]
    pub fn render_page_bitmap(&self, config: &RenderConfig) -> Result<rpdfium_graphics::Bitmap> {
        self.render(config)
    }

    /// Render the page using a custom transformation matrix and optional
    /// device-space clip rectangle.
    ///
    /// `matrix` maps PDF user-space coordinates to device pixel coordinates,
    /// bypassing the `media_box`/`rotation` calculation in `RenderConfig`.
    /// `clip` is an optional device-space clip rectangle (pixels outside it are
    /// replaced with the background colour).  `width` and `height` define the
    /// output bitmap dimensions.
    ///
    /// Corresponds to `FPDF_RenderPageBitmapWithMatrix`.
    pub fn render_with_matrix(
        &self,
        matrix: Matrix,
        clip: Option<Rect>,
        width: u32,
        height: u32,
    ) -> Result<rpdfium_graphics::Bitmap> {
        let mut config = RenderConfig::default()
            .with_size(width, height)
            .with_transform(matrix);
        if let Some(r) = clip {
            config = config.with_clip(r);
        }
        self.render(&config)
    }

    /// Upstream-aligned alias for [`render_with_matrix()`](Self::render_with_matrix).
    ///
    /// Corresponds to `FPDF_RenderPageBitmapWithMatrix`.
    #[inline]
    pub fn render_page_bitmap_with_matrix(
        &self,
        matrix: Matrix,
        clip: Option<Rect>,
        width: u32,
        height: u32,
    ) -> Result<rpdfium_graphics::Bitmap> {
        self.render_with_matrix(matrix, clip, width, height)
    }

    /// Extract text from the page.
    pub fn text(&self) -> Result<TextPage> {
        let tree = self.interpret()?;
        let mut extractor = TextExtractor::new();
        walk(tree, &mut extractor);
        let (characters, run_ids) = extractor.into_characters();
        Ok(TextPage::new_with_run_ids(characters, run_ids, false))
    }

    /// Parse annotations on this page.
    pub fn annotations(&self) -> Result<Vec<Annotation>> {
        let page_obj = self.store.resolve(self.page_dict_id)?;
        let page_dict = page_obj
            .as_dict()
            .ok_or(PdfError::UnknownObject(self.page_dict_id))?;
        match page_dict.get(&Name::annots()) {
            Some(annots_obj) => {
                let annots = parse_annotations(annots_obj, self.store)?;
                Ok(annots)
            }
            None => Ok(Vec::new()),
        }
    }

    /// Returns the number of annotations on this page.
    ///
    /// Corresponds to `FPDFPage_GetAnnotCount`.
    pub fn annotation_count(&self) -> Result<usize> {
        Ok(self.annotations()?.len())
    }

    /// Upstream-aligned alias for [`annotation_count()`](Self::annotation_count).
    ///
    /// Corresponds to `FPDFPage_GetAnnotCount`.
    #[inline]
    pub fn page_get_annot_count(&self) -> Result<usize> {
        self.annotation_count()
    }

    /// Deprecated: use [`page_get_annot_count()`](Self::page_get_annot_count) — matches upstream `FPDFPage_GetAnnotCount`.
    #[deprecated(note = "use `page_get_annot_count()` — matches upstream `FPDFPage_GetAnnotCount`")]
    #[inline]
    pub fn get_annot_count(&self) -> Result<usize> {
        self.annotation_count()
    }

    /// Returns the annotation at `index` on this page, or `None` if out of range.
    ///
    /// Corresponds to `FPDFPage_GetAnnot`.
    pub fn annotation_at(&self, index: usize) -> Result<Option<Annotation>> {
        Ok(self.annotations()?.into_iter().nth(index))
    }

    /// Upstream-aligned alias for [`annotation_at()`](Self::annotation_at).
    ///
    /// Corresponds to `FPDFPage_GetAnnot`.
    #[inline]
    pub fn page_get_annot(&self, index: usize) -> Result<Option<Annotation>> {
        self.annotation_at(index)
    }

    /// Deprecated: use [`page_get_annot()`](Self::page_get_annot) — matches upstream `FPDFPage_GetAnnot`.
    #[deprecated(note = "use `page_get_annot()` — matches upstream `FPDFPage_GetAnnot`")]
    #[inline]
    pub fn get_annot(&self, index: usize) -> Result<Option<Annotation>> {
        self.annotation_at(index)
    }

    /// Returns the index of `annot` within this page's annotation list, or `None`.
    ///
    /// Corresponds to `FPDFPage_GetAnnotIndex`.
    pub fn annotation_index(&self, annot: &Annotation) -> Result<Option<usize>> {
        Ok(self
            .annotations()?
            .iter()
            .position(|a| std::ptr::eq(a as *const Annotation, annot as *const Annotation)))
    }

    /// Upstream-aligned alias for [`annotation_index()`](Self::annotation_index).
    ///
    /// Corresponds to `FPDFPage_GetAnnotIndex`.
    #[inline]
    pub fn page_get_annot_index(&self, annot: &Annotation) -> Result<Option<usize>> {
        self.annotation_index(annot)
    }

    /// Deprecated: use [`page_get_annot_index()`](Self::page_get_annot_index) — matches upstream `FPDFPage_GetAnnotIndex`.
    #[deprecated(note = "use `page_get_annot_index()` — matches upstream `FPDFPage_GetAnnotIndex`")]
    #[inline]
    pub fn get_annot_index(&self, annot: &Annotation) -> Result<Option<usize>> {
        self.annotation_index(annot)
    }

    /// Returns the page's embedded thumbnail image, if present.
    ///
    /// PDF pages may contain a `/Thumb` entry pointing to an image XObject
    /// that serves as a thumbnail preview. This method decodes that stream
    /// and returns it as an RGBA32 `Bitmap`.
    ///
    /// Returns `Ok(None)` if the page has no thumbnail.
    ///
    /// Corresponds to `FPDFPage_GetThumbnailAsBitmap`.
    pub fn thumbnail(&self) -> Result<Option<Bitmap>> {
        decode_page_thumbnail(self.store, self.page_dict_id)
    }

    /// Upstream-aligned alias for [`thumbnail()`](Self::thumbnail).
    ///
    /// Corresponds to `FPDFPage_GetThumbnailAsBitmap`.
    #[inline]
    pub fn page_get_thumbnail_as_bitmap(&self) -> Result<Option<Bitmap>> {
        self.thumbnail()
    }

    /// Non-upstream alias — use [`page_get_thumbnail_as_bitmap()`](Self::page_get_thumbnail_as_bitmap).
    ///
    /// Corresponds to `FPDFPage_GetThumbnailAsBitmap`.
    #[deprecated(
        note = "use `page_get_thumbnail_as_bitmap()` — matches upstream `FPDFPage_GetThumbnailAsBitmap`"
    )]
    #[inline]
    pub fn get_thumbnail_as_bitmap(&self) -> Result<Option<Bitmap>> {
        self.thumbnail()
    }

    /// Returns the decoded (decompressed) thumbnail image data, if present.
    ///
    /// The returned bytes are the raw pixel data after applying the stream's
    /// filter chain (e.g. FlateDecode). Returns `Ok(None)` if the page has
    /// no `/Thumb` entry.
    ///
    /// Corresponds to `FPDFPage_GetDecodedThumbnailData`.
    pub fn thumbnail_decoded_bytes(&self) -> Result<Option<Vec<u8>>> {
        thumbnail_raw_or_decoded(self.store, self.page_dict_id, true)
    }

    /// Upstream-aligned alias for [`thumbnail_decoded_bytes()`](Self::thumbnail_decoded_bytes).
    ///
    /// Corresponds to `FPDFPage_GetDecodedThumbnailData`.
    #[inline]
    pub fn page_get_decoded_thumbnail_data(&self) -> Result<Option<Vec<u8>>> {
        self.thumbnail_decoded_bytes()
    }

    /// Non-upstream alias — use [`page_get_decoded_thumbnail_data()`](Self::page_get_decoded_thumbnail_data).
    ///
    /// Corresponds to `FPDFPage_GetDecodedThumbnailData`.
    #[deprecated(
        note = "use `page_get_decoded_thumbnail_data()` — matches upstream `FPDFPage_GetDecodedThumbnailData`"
    )]
    #[inline]
    pub fn get_decoded_thumbnail_data(&self) -> Result<Option<Vec<u8>>> {
        self.thumbnail_decoded_bytes()
    }

    /// Returns the raw (compressed) thumbnail stream data, if present.
    ///
    /// The returned bytes are the stream data as stored in the PDF, before
    /// any filter decoding. Returns `Ok(None)` if the page has no `/Thumb`
    /// entry.
    ///
    /// Corresponds to `FPDFPage_GetRawThumbnailData`.
    pub fn thumbnail_raw_bytes(&self) -> Result<Option<Vec<u8>>> {
        thumbnail_raw_or_decoded(self.store, self.page_dict_id, false)
    }

    /// Upstream-aligned alias for [`thumbnail_raw_bytes()`](Self::thumbnail_raw_bytes).
    ///
    /// Corresponds to `FPDFPage_GetRawThumbnailData`.
    #[inline]
    pub fn page_get_raw_thumbnail_data(&self) -> Result<Option<Vec<u8>>> {
        self.thumbnail_raw_bytes()
    }

    /// Non-upstream alias — use [`page_get_raw_thumbnail_data()`](Self::page_get_raw_thumbnail_data).
    ///
    /// Corresponds to `FPDFPage_GetRawThumbnailData`.
    #[deprecated(
        note = "use `page_get_raw_thumbnail_data()` — matches upstream `FPDFPage_GetRawThumbnailData`"
    )]
    #[inline]
    pub fn get_raw_thumbnail_data(&self) -> Result<Option<Vec<u8>>> {
        self.thumbnail_raw_bytes()
    }

    /// Returns the zero-based page index.
    pub fn index(&self) -> u32 {
        self.page_index
    }
}

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

/// Parse a rectangle from a dictionary key (e.g. /MediaBox, /CropBox).
pub(crate) fn parse_rect(
    dict: &std::collections::HashMap<Name, Object>,
    key: &Name,
    store: &ObjectStore<Arc<[u8]>>,
) -> Option<Rect> {
    let obj = dict.get(key)?;
    let resolved = store.deep_resolve(obj).ok()?;
    parse_rect_from_obj(resolved)
}

/// Parse a rectangle from an already-resolved Object.
pub(crate) fn parse_rect_from_obj(obj: &Object) -> Option<Rect> {
    let arr = obj.as_array()?;
    if arr.len() < 4 {
        return None;
    }
    let vals: Vec<f64> = arr.iter().take(4).filter_map(|o| o.as_f64()).collect();
    if vals.len() < 4 {
        return None;
    }
    Some(Rect::new(vals[0], vals[1], vals[2], vals[3]))
}

/// Decode page /Contents into a single byte buffer.
///
/// /Contents can be a single stream reference or an array of stream references.
pub(crate) fn decode_page_contents(
    page_dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<Arc<[u8]>>,
) -> std::result::Result<Vec<u8>, PdfError> {
    let contents_obj = match page_dict.get(&Name::contents()) {
        Some(obj) => obj,
        None => return Ok(Vec::new()),
    };

    let resolved = store.deep_resolve(contents_obj)?;
    match resolved {
        Object::Stream { .. } => {
            // Single stream — decode it
            store.decode_stream(resolved)
        }
        Object::Array(arr) => {
            // Array of stream references — concatenate decoded bytes
            let mut all_bytes = Vec::new();
            for item in arr {
                if let Some(ref_id) = item.as_reference() {
                    let stream_obj = store.resolve(ref_id)?;
                    if let Object::Stream { .. } = stream_obj {
                        let decoded = store.decode_stream(stream_obj)?;
                        if !all_bytes.is_empty() {
                            // Ensure streams are separated by whitespace
                            all_bytes.push(b' ');
                        }
                        all_bytes.extend_from_slice(&decoded);
                    }
                }
            }
            Ok(all_bytes)
        }
        Object::Reference(id) => {
            // A reference that resolved to something — try to decode it as a stream
            let stream_obj = store.resolve(*id)?;
            if let Object::Stream { .. } = stream_obj {
                store.decode_stream(stream_obj)
            } else {
                Ok(Vec::new())
            }
        }
        _ => Ok(Vec::new()),
    }
}

// ---------------------------------------------------------------------------
// Coordinate conversion (FPDF_PageToDevice / FPDF_DeviceToPage equivalents)
// ---------------------------------------------------------------------------

/// Convert PDF page coordinates to device (pixel) coordinates.
///
/// `page_width` and `page_height` are the render target dimensions in pixels.
/// `rotate` is the page rotation in degrees (0, 90, 180, or 270).
///
/// Corresponds to `FPDF_PageToDevice`.
pub fn page_to_device(
    page: &Page<'_>,
    page_width: u32,
    page_height: u32,
    rotate: u32,
    page_x: f64,
    page_y: f64,
) -> (i32, i32) {
    let matrix = compute_page_transform(&page.media_box(), page_width, page_height, rotate);
    let pt = matrix.transform_point(Point {
        x: page_x,
        y: page_y,
    });
    (pt.x.round() as i32, pt.y.round() as i32)
}

/// Convert device (pixel) coordinates to PDF page coordinates.
///
/// `page_width` and `page_height` are the render target dimensions in pixels.
/// `rotate` is the page rotation in degrees (0, 90, 180, or 270).
///
/// Corresponds to `FPDF_DeviceToPage`.
pub fn device_to_page(
    page: &Page<'_>,
    page_width: u32,
    page_height: u32,
    rotate: u32,
    device_x: i32,
    device_y: i32,
) -> (f64, f64) {
    let matrix = compute_page_transform(&page.media_box(), page_width, page_height, rotate);
    match matrix.inverse() {
        Some(inv) => {
            let pt = inv.transform_point(Point {
                x: device_x as f64,
                y: device_y as f64,
            });
            (pt.x, pt.y)
        }
        None => (0.0, 0.0),
    }
}

// ---------------------------------------------------------------------------
// Thumbnail decoding
// ---------------------------------------------------------------------------

/// Decode the `/Thumb` image stream from a page dictionary, if present.
///
/// Returns the thumbnail as an RGBA32 `Bitmap`, or `None` if the page has
/// no `/Thumb` entry. Reuses the same image decoding infrastructure as the
/// render pipeline.
fn decode_page_thumbnail(
    store: &ObjectStore<Arc<[u8]>>,
    page_dict_id: ObjectId,
) -> Result<Option<Bitmap>> {
    let page_obj = store.resolve(page_dict_id)?;
    let page_dict = page_obj
        .as_dict()
        .ok_or(PdfError::UnknownObject(page_dict_id))?;

    let thumb_obj = match page_dict.get(&Name::thumb()) {
        Some(obj) => obj,
        None => return Ok(None),
    };

    // Resolve the /Thumb reference to the stream object
    let resolved = store.deep_resolve(thumb_obj)?;
    let stream_dict = match resolved.as_stream_dict() {
        Some(d) => d,
        None => return Ok(None),
    };

    let width = get_dict_int(stream_dict, &Name::width(), store).unwrap_or(0) as u32;
    let height = get_dict_int(stream_dict, &Name::height(), store).unwrap_or(0) as u32;
    let bpc = get_dict_int(stream_dict, &Name::bits_per_component(), store).unwrap_or(8) as u32;

    if width == 0 || height == 0 {
        return Ok(None);
    }

    let (n_components, cs_type) = resolve_image_color_space(stream_dict, store);

    // Decode the stream data through the standard filter chain
    let decoded = store.decode_stream(resolved)?;

    let decode_array = read_decode_array(stream_dict, n_components, store);

    let rgba = convert_to_rgba(
        &decoded,
        width,
        height,
        bpc,
        n_components,
        &cs_type,
        &decode_array,
        false,
    );

    let stride = width * 4; // RGBA32 = 4 bytes per pixel
    Ok(Some(Bitmap {
        width,
        height,
        format: BitmapFormat::Rgba32,
        stride,
        data: rgba,
    }))
}

/// Returns the thumbnail stream data, either decoded or raw.
///
/// When `decode` is `true`, the stream is decoded through the filter chain
/// (corresponds to `FPDFPage_GetDecodedThumbnailData`).
/// When `false`, the raw stream bytes are returned as stored
/// (corresponds to `FPDFPage_GetRawThumbnailData`).
pub(crate) fn thumbnail_raw_or_decoded(
    store: &ObjectStore<Arc<[u8]>>,
    page_dict_id: ObjectId,
    decode: bool,
) -> Result<Option<Vec<u8>>> {
    let page_obj = store.resolve(page_dict_id)?;
    let page_dict = page_obj
        .as_dict()
        .ok_or(PdfError::UnknownObject(page_dict_id))?;

    let thumb_obj = match page_dict.get(&Name::thumb()) {
        Some(obj) => obj,
        None => return Ok(None),
    };

    // Resolve through references to find the stream and its object ID
    let (thumb_id, resolved) = match thumb_obj {
        Object::Reference(id) => (*id, store.resolve(*id)?),
        other => {
            let r = store.deep_resolve(other)?;
            // No object ID available for inline streams
            return match r {
                Object::Stream { .. } if decode => {
                    let decoded = store.decode_stream(r)?;
                    Ok(Some(decoded))
                }
                Object::Stream {
                    data: rpdfium_parser::object::StreamData::Decoded { data },
                    ..
                } => Ok(Some(data.clone())),
                _ => Ok(None),
            };
        }
    };

    match resolved {
        Object::Stream { .. } => {
            if decode {
                let decoded = store.decode_stream(resolved)?;
                Ok(Some(decoded))
            } else {
                let raw = store.raw_stream_bytes_for_object(resolved, thumb_id)?;
                Ok(Some(raw))
            }
        }
        _ => Ok(None),
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

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

    /// Build a minimal single-page PDF with a valid cross-reference table.
    fn minimal_pdf() -> Vec<u8> {
        let mut pdf = Vec::new();
        pdf.extend_from_slice(b"%PDF-1.4\n");
        let off1 = pdf.len();
        pdf.extend_from_slice(b"1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n");
        let off2 = pdf.len();
        pdf.extend_from_slice(b"2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n");
        let off3 = pdf.len();
        pdf.extend_from_slice(
            b"3 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>\nendobj\n",
        );
        let xref_offset = pdf.len();
        pdf.extend_from_slice(b"xref\n0 4\n");
        pdf.extend_from_slice(b"0000000000 65535 f \r\n");
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", off1).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", off2).as_bytes());
        pdf.extend_from_slice(format!("{:010} 00000 n \r\n", off3).as_bytes());
        pdf.extend_from_slice(b"trailer\n<< /Size 4 /Root 1 0 R >>\n");
        pdf.extend_from_slice(format!("startxref\n{xref_offset}\n%%EOF").as_bytes());
        pdf
    }

    #[test]
    fn test_has_valid_cross_reference_table_valid_pdf() {
        let lib = Library::new();
        let opts = OpenOptions::default();
        let doc = Document::open(&lib, minimal_pdf(), &opts).unwrap();
        assert!(doc.has_valid_cross_reference_table());
    }

    #[test]
    fn test_trailer_ends_returns_empty_vec() {
        let lib = Library::new();
        let opts = OpenOptions::default();
        let doc = Document::open(&lib, minimal_pdf(), &opts).unwrap();
        // Stub returns empty for now
        let ends = doc.trailer_ends();
        let _ = ends; // just verify it doesn't panic
    }
}