spectre_parse 1.0.0

//! `Document` — the entry point.
//!
//! `Document::open(bytes)` parses the header, locates `startxref`,
//! reads the xref table(s), and parses the trailer. **No object body
//! is materialized.** Object access goes through `get_object`, which
//! parses on demand and caches.
//!
//! Caching uses an [`std::sync::RwLock`]: read-mostly workloads hit
//! the read lock; cache misses take the write lock to insert.

use crate::error::{Error, ParseError, Result, XrefError};
use crate::object::{Dictionary, Object, ObjectId, Stream};
use crate::parser::{
    parse_header, parse_startxref, parse_xref_and_trailer, read_indirect_object_at, Cursor,
};
use crate::xref::{Xref, XrefEntry};
use std::collections::{BTreeMap, HashSet};
use std::sync::RwLock;

/// A parsed PDF document. Lazy: `open` does xref + trailer only.
///
/// The source bytes are copied into the `Document` so callers don't
/// have to keep the original `&[u8]` alive.
pub struct Document {
    /// Source bytes. Owned so derived `&[u8]` references (stream
    /// content windows) outlive the open call.
    pub(crate) buffer: Vec<u8>,
    /// `%PDF-x.y` header version string (e.g. `"1.5"`).
    pub(crate) version: String,
    pub(crate) trailer: Dictionary,
    pub(crate) xref: Xref,
    cache: RwLock<BTreeMap<ObjectId, Object>>,
    /// Set when the source PDF is encrypted and we've authenticated
    /// a password. Every object materialized through [`Self::get_object`]
    /// is decrypted in place before caching.
    pub(crate) decryptor: Option<crate::decrypt::Decryptor>,
}

impl std::fmt::Debug for Document {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Document")
            .field("version", &self.version)
            .field("xref_entries", &self.xref.len())
            .field("trailer_keys", &self.trailer.len())
            .finish()
    }
}

impl Document {
    /// Parse PDF bytes lazily. Returns once the xref table and trailer
    /// have been read; object bodies stay unparsed until accessed.
    pub fn open(pdf_bytes: &[u8]) -> Result<Self> {
        Self::open_with_password(pdf_bytes, b"")
    }

    /// Same as [`Self::open`] but with an explicit password. The empty
    /// password works for documents encrypted with an owner password
    /// but no user password.
    pub fn open_with_password(pdf_bytes: &[u8], password: &[u8]) -> Result<Self> {
        if pdf_bytes.is_empty() {
            return Err(ParseError::InvalidFileHeader.into());
        }
        let (version, _header_offset) = parse_header(pdf_bytes)?;

        let xref_start = parse_startxref(pdf_bytes)?;
        if xref_start >= pdf_bytes.len() {
            return Err(XrefError::Start.into());
        }

        // Walk the xref chain — newest first, then prev pointers older.
        let (mut xref, mut trailer) = parse_xref_and_trailer(pdf_bytes, xref_start)?;
        let mut seen: HashSet<i64> = HashSet::new();
        seen.insert(xref_start as i64);

        let mut next_prev = trailer.get_optional(b"Prev").cloned();
        loop {
            let prev_offset: usize = match next_prev {
                Some(Object::Integer(n)) if n > 0 => n as usize,
                Some(Object::Real(f)) if f > 0.0 => f as usize,
                _ => break,
            };
            if prev_offset >= pdf_bytes.len() {
                return Err(XrefError::PrevStart.into());
            }
            if !seen.insert(prev_offset as i64) {
                break; // cycle guard
            }
            let (older_xref, older_trailer) =
                parse_xref_and_trailer(pdf_bytes, prev_offset)?;
            xref.merge_older(older_xref);
            // Newest trailer wins; older keys fill in blanks.
            for (k, v) in older_trailer.iter() {
                if trailer.get_optional(k).is_none() {
                    trailer.set(k.clone(), v.clone());
                }
            }
            next_prev = older_trailer.get_optional(b"Prev").cloned();
        }

        // Normalize Size if the trailer disagrees with the xref.
        let max_num = xref.iter().next_back().map(|(k, _)| *k).unwrap_or(0);
        if xref.size <= max_num {
            xref.size = max_num + 1;
        }

        let decryptor = if let Some(encrypt_obj) = trailer.get_optional(b"Encrypt").cloned() {
            // /Encrypt is normally an indirect reference; resolve it
            // against the xref WITHOUT decryption (the key isn't built yet).
            let encrypt_dict = match &encrypt_obj {
                Object::Dictionary(d) => d.clone(),
                Object::Reference(id) => {
                    let entry = *xref.get(id.0).ok_or(Error::ObjectNotFound(id.0, id.1))?;
                    if let crate::xref::XrefEntry::Normal { offset, .. } = entry {
                        let (_pid, body) = crate::parser::read_indirect_object_at(
                            &pdf_bytes,
                            offset as usize,
                        )?;
                        match body {
                            Object::Dictionary(d) => d,
                            other => return Err(Error::Type {
                                expected: "Dictionary",
                                found: other.type_name(),
                            }),
                        }
                    } else {
                        return Err(Error::ObjectNotFound(id.0, id.1));
                    }
                }
                other => return Err(Error::Type {
                    expected: "Dictionary or Reference",
                    found: other.type_name(),
                }),
            };
            // /ID — array of two byte strings; we use the first.
            let file_id_bytes = trailer
                .get_optional(b"ID")
                .and_then(|o| match o {
                    Object::Array(a) => a.first().cloned(),
                    _ => None,
                })
                .and_then(|first| match first {
                    Object::String(b, _) => Some(b),
                    _ => None,
                })
                .unwrap_or_default();
            Some(crate::decrypt::Decryptor::from_trailer(
                &encrypt_dict,
                &file_id_bytes,
                password,
            )?)
        } else {
            None
        };

        Ok(Self {
            buffer: pdf_bytes.to_vec(),
            version,
            trailer,
            xref,
            cache: RwLock::new(BTreeMap::new()),
            decryptor,
        })
    }

    /// Number of xref entries (rough proxy for object count).
    pub fn xref_size(&self) -> u32 {
        self.xref.size
    }

    /// `%PDF-x.y` header version string (e.g. `"1.5"`).
    pub fn version(&self) -> &str {
        &self.version
    }

    /// Trailer dictionary. Direct read access; do not mutate.
    pub fn trailer(&self) -> &Dictionary {
        &self.trailer
    }

    /// Resolve the document catalog (`/Root`).
    pub fn catalog(&self) -> Result<Dictionary> {
        let root_ref = self.trailer.get(b"Root")?;
        let id = root_ref.as_reference()?;
        self.get_dictionary(id)
    }

    /// Walk the catalog's `/Pages` tree and return a `(page_num,
    /// page_id)` map in document order. Page numbers are 1-indexed.
    pub fn get_pages(&self) -> std::collections::BTreeMap<u32, ObjectId> {
        let mut out = std::collections::BTreeMap::new();
        let Ok(cat) = self.catalog() else {
            return out;
        };
        let Ok(pages_ref) = cat.get(b"Pages").and_then(|o| o.as_reference()) else {
            return out;
        };
        let mut counter: u32 = 0;
        self.walk_page_tree(pages_ref, &mut counter, &mut out, 0);
        out
    }

    fn walk_page_tree(
        &self,
        node_id: ObjectId,
        counter: &mut u32,
        out: &mut std::collections::BTreeMap<u32, ObjectId>,
        depth: usize,
    ) {
        if depth > 64 {
            return; // defensive cycle guard
        }
        let Ok(dict) = self.get_dictionary(node_id) else {
            return;
        };
        let is_page = dict.has_type(b"Page");
        let is_pages = dict.has_type(b"Pages");
        if is_page {
            *counter += 1;
            out.insert(*counter, node_id);
            return;
        }
        if !is_pages {
            // Malformed PDFs may omit /Type; treat any node with /Kids
            // as a pages node.
            if dict.get_optional(b"Kids").is_none() {
                return;
            }
        }
        let Some(kids_obj) = dict.get_optional(b"Kids") else {
            return;
        };
        let Ok(kids) = kids_obj.as_array() else {
            return;
        };
        for kid in kids {
            if let Ok(child_id) = kid.as_reference() {
                self.walk_page_tree(child_id, counter, out, depth + 1);
            }
        }
    }

    /// Concatenated content-stream bytes for one page. `/Contents` may
    /// be a single stream or an array of streams; the array form is
    /// joined with `\n` so the tokenizer sees one logical stream.
    pub fn get_page_content(&self, page_id: ObjectId) -> Result<Vec<u8>> {
        let page = self.get_dictionary(page_id)?;
        let contents_obj = page.get(b"Contents")?;
        self.concat_content(contents_obj)
    }

    fn concat_content(&self, obj: &Object) -> Result<Vec<u8>> {
        match obj {
            Object::Reference(id) => {
                let inner = self.get_object(*id)?;
                match inner {
                    Object::Stream(s) => Ok(s.content),
                    Object::Array(arr) => self.concat_content(&Object::Array(arr)),
                    _ => Ok(Vec::new()),
                }
            }
            Object::Array(arr) => {
                // Cap the capacity hint against hostile /Contents arrays
                // that would otherwise force a multi-gigabyte upfront
                // allocation. 64 MB is well above any real document.
                let cap = arr.len().saturating_mul(1024).min(64 * 1024 * 1024);
                let mut out = Vec::with_capacity(cap);
                for (i, item) in arr.iter().enumerate() {
                    if i > 0 {
                        out.push(b'\n');
                    }
                    let part = self.concat_content(item)?;
                    out.extend_from_slice(&part);
                }
                Ok(out)
            }
            Object::Stream(s) => Ok(s.content.clone()),
            _ => Ok(Vec::new()),
        }
    }

    /// Resolve `/Resources` for a page, walking the parent chain when
    /// the leaf page omits its own (PDF spec §7.7.3.4 inheritance).
    pub fn get_page_resources(&self, page_id: ObjectId) -> Result<Dictionary> {
        let mut current = Some(self.get_dictionary(page_id)?);
        let mut depth = 0usize;
        while let Some(dict) = current {
            if let Some(res_obj) = dict.get_optional(b"Resources") {
                let resolved = match res_obj {
                    Object::Reference(id) => self.get_dictionary(*id)?,
                    Object::Dictionary(d) => d.clone(),
                    _ => return Ok(Dictionary::new()),
                };
                return Ok(resolved);
            }
            if depth > 64 {
                break;
            }
            depth += 1;
            current = match dict.get_optional(b"Parent") {
                Some(Object::Reference(id)) => self.get_dictionary(*id).ok(),
                _ => None,
            };
        }
        Ok(Dictionary::new())
    }

    /// Map `/Font` resource-name → font-dict for one page. Keyed by
    /// the resource name (e.g. `b"F1"`) so a `Tf` operator resolves
    /// the active font directly.
    pub fn get_page_fonts(
        &self,
        page_id: ObjectId,
    ) -> Result<std::collections::BTreeMap<Vec<u8>, Dictionary>> {
        let mut out = std::collections::BTreeMap::new();
        let resources = self.get_page_resources(page_id)?;
        let Some(fonts_obj) = resources.get_optional(b"Font") else {
            return Ok(out);
        };
        let fonts_dict = match fonts_obj {
            Object::Dictionary(d) => d.clone(),
            Object::Reference(id) => self.get_dictionary(*id)?,
            _ => return Ok(out),
        };
        for (name, val) in fonts_dict.iter() {
            let resolved = match val {
                Object::Reference(id) => self.get_dictionary(*id).ok(),
                Object::Dictionary(d) => Some(d.clone()),
                _ => None,
            };
            if let Some(font_dict) = resolved {
                out.insert(name.clone(), font_dict);
            }
        }
        Ok(out)
    }

    /// Annotations on a page — `/Annots` array resolved, each entry
    /// dereferenced to its dict.
    pub fn get_page_annotations(&self, page_id: ObjectId) -> Vec<Dictionary> {
        let mut out = Vec::new();
        let Ok(page) = self.get_dictionary(page_id) else {
            return out;
        };
        let Some(annots_obj) = page.get_optional(b"Annots") else {
            return out;
        };
        let arr = match annots_obj {
            Object::Reference(id) => match self.get_object(*id) {
                Ok(Object::Array(a)) => a,
                _ => return out,
            },
            Object::Array(a) => a.clone(),
            _ => return out,
        };
        for item in arr {
            if let Ok(id) = item.as_reference() {
                if let Ok(d) = self.get_dictionary(id) {
                    out.push(d);
                }
            }
        }
        out
    }

    /// Inventory of image XObjects referenced from a page's
    /// `/Resources/XObject`. Inventory-only — see [`PdfImageInfo`].
    pub fn get_page_images(&self, page_id: ObjectId) -> Vec<PdfImageInfo> {
        let mut out = Vec::new();
        let resources = match self.get_page_resources(page_id) {
            Ok(r) => r,
            Err(_) => return out,
        };
        let Some(xobj_raw) = resources.get_optional(b"XObject") else {
            return out;
        };
        let xobj_dict = match xobj_raw {
            Object::Dictionary(d) => d.clone(),
            Object::Reference(id) => match self.get_dictionary(*id) {
                Ok(d) => d,
                Err(_) => return out,
            },
            _ => return out,
        };
        let mut seen: std::collections::HashSet<ObjectId> = std::collections::HashSet::new();
        self.walk_xobject_for_images(&xobj_dict, &mut seen, &mut out, 0);
        out
    }

    /// Recursive walk of an `/XObject` dict collecting `/Subtype/Image`
    /// streams. PDF files commonly wrap an actual image inside a Form
    /// XObject (e.g. to apply a transform + clip); without recursion
    /// every Form-wrapped image is silently dropped.
    ///
    /// `seen` guards against cyclic Form references — the spec doesn't
    /// forbid them and hostile/malformed PDFs can include one.
    fn walk_xobject_for_images(
        &self,
        xobj_dict: &Dictionary,
        seen: &mut std::collections::HashSet<ObjectId>,
        out: &mut Vec<PdfImageInfo>,
        depth: usize,
    ) {
        if depth > 16 {
            return; // defensive: real Form-XObject nesting is shallow
        }
        for (_name, value) in xobj_dict.iter() {
            let Ok(id) = value.as_reference() else { continue };
            if !seen.insert(id) {
                continue;
            }
            let Ok(obj) = self.get_object(id) else { continue };
            let Object::Stream(stream) = obj else { continue };
            let subtype = stream
                .dict
                .get_optional(b"Subtype")
                .and_then(|o| o.as_name().ok())
                .map(|n| n.to_vec());
            match subtype.as_deref() {
                Some(b"Image") => {
                    out.push(make_image_info(id, &stream));
                }
                Some(b"Form") => {
                    let inner_xobj = stream
                        .dict
                        .get_optional(b"Resources")
                        .and_then(|r| self.deref_dict(r))
                        .and_then(|res| {
                            res.get_optional(b"XObject")
                                .and_then(|x| self.deref_dict(x))
                        });
                    if let Some(inner) = inner_xobj {
                        self.walk_xobject_for_images(&inner, seen, out, depth + 1);
                    }
                }
                _ => {}
            }
        }
    }

    /// Resolve a `Reference` or `Dictionary` to an owned `Dictionary`.
    fn deref_dict(&self, obj: &Object) -> Option<Dictionary> {
        match obj {
            Object::Dictionary(d) => Some(d.clone()),
            Object::Reference(id) => self.get_dictionary(*id).ok(),
            _ => None,
        }
    }

    /// `true` when the document has an `/Encrypt` trailer entry.
    pub fn is_encrypted(&self) -> bool {
        self.trailer.get_optional(b"Encrypt").is_some()
    }

    /// Walk `/AcroForm/Fields` and return one [`FormField`] per terminal
    /// field. Partial names from interior `/T` entries concatenate down
    /// the tree into a `Foo.bar.baz`-style fully qualified name per
    /// PDF spec §12.7.4.2.
    pub fn get_form_fields(&self) -> Vec<FormField> {
        let mut out: Vec<FormField> = Vec::new();
        let Ok(cat) = self.catalog() else { return out };
        let Some(acroform_obj) = cat.get_optional(b"AcroForm") else {
            return out;
        };
        let Some(acroform) = self.deref_dict(acroform_obj) else {
            return out;
        };
        let Some(fields_obj) = acroform.get_optional(b"Fields") else {
            return out;
        };
        let fields = match fields_obj {
            Object::Array(a) => a.clone(),
            Object::Reference(id) => match self.get_object(*id) {
                Ok(Object::Array(a)) => a,
                _ => return out,
            },
            _ => return out,
        };
        let page_id_to_num: std::collections::BTreeMap<ObjectId, u32> = self
            .get_pages()
            .into_iter()
            .map(|(n, id)| (id, n))
            .collect();
        let mut seen: std::collections::HashSet<ObjectId> =
            std::collections::HashSet::new();
        for entry in &fields {
            if let Ok(id) = entry.as_reference() {
                self.walk_form_field(id, None, "", &page_id_to_num, &mut out, &mut seen, 0);
            }
        }
        out
    }

    fn walk_form_field(
        &self,
        field_id: ObjectId,
        inherited_type: Option<Vec<u8>>,
        prefix: &str,
        page_id_to_num: &std::collections::BTreeMap<ObjectId, u32>,
        out: &mut Vec<FormField>,
        seen: &mut std::collections::HashSet<ObjectId>,
        depth: usize,
    ) {
        if depth > 32 || !seen.insert(field_id) {
            return;
        }
        let Ok(dict) = self.get_dictionary(field_id) else {
            return;
        };
        let partial = dict
            .get_optional(b"T")
            .and_then(|o| o.as_str().ok())
            .map(decode_pdf_text_string)
            .unwrap_or_default();
        let full_name = if prefix.is_empty() {
            partial.clone()
        } else if partial.is_empty() {
            prefix.to_string()
        } else {
            format!("{prefix}.{partial}")
        };
        // /FT can be inherited from a parent node.
        let field_type_bytes = dict
            .get_optional(b"FT")
            .and_then(|o| o.as_name().ok())
            .map(|n| n.to_vec())
            .or(inherited_type);
        // PDF lets a parent reuse /Kids for widget annotations on a
        // single terminal field with multiple appearances. Distinguish
        // by checking whether the kid carries its own /T: kid-with-/T
        // is a subfield (recurse); kid-without-/T is an annotation
        // appearance (treat this node as terminal).
        if let Some(kids_obj) = dict.get_optional(b"Kids") {
            let kids = match kids_obj {
                Object::Array(a) => a.clone(),
                Object::Reference(id) => match self.get_object(*id) {
                    Ok(Object::Array(a)) => a,
                    _ => Vec::new(),
                },
                _ => Vec::new(),
            };
            let mut any_subfield_kid = false;
            for k in &kids {
                if let Ok(kid_id) = k.as_reference() {
                    if let Ok(kd) = self.get_dictionary(kid_id) {
                        let kid_has_t = kd.get_optional(b"T").is_some();
                        if kid_has_t {
                            any_subfield_kid = true;
                            self.walk_form_field(
                                kid_id,
                                field_type_bytes.clone(),
                                &full_name,
                                page_id_to_num,
                                out,
                                seen,
                                depth + 1,
                            );
                        }
                    }
                }
            }
            if any_subfield_kid {
                return;
            }
        }
        let field_type = field_type_bytes
            .as_deref()
            .map(|b| match b {
                b"Tx" => FormFieldType::Text,
                b"Btn" => FormFieldType::Button,
                b"Ch" => FormFieldType::Choice,
                b"Sig" => FormFieldType::Signature,
                _ => FormFieldType::Unknown,
            })
            .unwrap_or(FormFieldType::Unknown);
        let value = dict
            .get_optional(b"V")
            .map(|o| form_value_to_string(o))
            .unwrap_or_default();
        let default_value = dict
            .get_optional(b"DV")
            .map(|o| form_value_to_string(o))
            .unwrap_or_default();
        let flags = dict
            .get_optional(b"Ff")
            .and_then(|o| o.as_i64().ok())
            .unwrap_or(0);
        let rect = dict
            .get_optional(b"Rect")
            .and_then(|o| o.as_array().ok())
            .and_then(|arr| {
                if arr.len() >= 4 {
                    Some([
                        arr[0].as_float().unwrap_or(0.0),
                        arr[1].as_float().unwrap_or(0.0),
                        arr[2].as_float().unwrap_or(0.0),
                        arr[3].as_float().unwrap_or(0.0),
                    ])
                } else {
                    None
                }
            });
        let page = dict
            .get_optional(b"P")
            .and_then(|o| o.as_reference().ok())
            .and_then(|id| page_id_to_num.get(&id).copied());
        out.push(FormField {
            name: full_name,
            value,
            default_value,
            field_type,
            flags,
            rect,
            page,
        });
    }

    /// Decoded byte buffer for an image XObject, suitable for direct
    /// write to a viewer-supported file. DCTDecode passes through as
    /// JPEG, JPX as JPEG 2000, JBIG2 / CCITT as raw encoded streams;
    /// raw flate-decoded pixel data is wrapped as a single-strip PNG.
    pub fn get_image_bytes(&self, image_id: ObjectId) -> Option<(ImageEncoding, Vec<u8>)> {
        let obj = self.get_object(image_id).ok()?;
        let stream = match obj {
            Object::Stream(s) => s,
            _ => return None,
        };
        let filters: Vec<Vec<u8>> = match stream.dict.get_optional(b"Filter") {
            Some(Object::Name(n)) => vec![n.clone()],
            Some(Object::Array(a)) => a
                .iter()
                .filter_map(|o| o.as_name().ok().map(|n| n.to_vec()))
                .collect(),
            _ => Vec::new(),
        };
        let last_filter = filters.last().map(|v| v.as_slice());
        // Image-only codecs are passthrough — their raw bytes are
        // already a viewer-loadable file format (or, for JBIG2/CCITT,
        // the only thing we can hand the caller).
        if matches!(last_filter, Some(b"DCTDecode")) {
            return Some((ImageEncoding::Jpeg, stream.content.clone()));
        }
        if matches!(last_filter, Some(b"JPXDecode")) {
            return Some((ImageEncoding::Jpeg2000, stream.content.clone()));
        }
        if matches!(last_filter, Some(b"JBIG2Decode")) {
            return Some((ImageEncoding::Jbig2, stream.content.clone()));
        }
        if matches!(last_filter, Some(b"CCITTFaxDecode")) {
            return Some((ImageEncoding::Ccitt, stream.content.clone()));
        }
        // Otherwise the stream content is already decoded (the lazy
        // parser ran the filter chain at materialize time). Wrap raw
        // pixel data as PNG.
        let width = stream.dict.get_optional(b"Width").and_then(|o| o.as_i64().ok())?;
        let height = stream.dict.get_optional(b"Height").and_then(|o| o.as_i64().ok())?;
        let bpc = stream
            .dict
            .get_optional(b"BitsPerComponent")
            .and_then(|o| o.as_i64().ok())
            .unwrap_or(8);
        // Resolve /ColorSpace through one level of indirection.
        // Real-world images commonly point at a named entry in
        // /Resources/ColorSpace; without the deref we mis-classify
        // them as "unknown channels" and drop them.
        let cs_obj_resolved = stream.dict.get_optional(b"ColorSpace").map(|o| {
            self.dereference(o)
                .map(|(_, v)| v)
                .unwrap_or_else(|_| o.clone())
        });
        let cs_name = cs_obj_resolved.as_ref().and_then(extract_color_space_name);
        // Indexed colorspace `[/Indexed <base> <hival> <lookup>]`:
        // expand each 1-byte index into base-channel triplets via
        // the palette lookup table.
        if matches!(cs_name.as_deref(), Some("Indexed")) {
            if let Some(Object::Array(arr)) = cs_obj_resolved.as_ref() {
                if arr.len() >= 4 {
                    let base = extract_color_space_name(&arr[1]);
                    let base_channels = match base.as_deref() {
                        Some("DeviceGray") | Some("CalGray") => 1,
                        Some("DeviceCMYK") => 4,
                        _ => 3,
                    };
                    let lookup_bytes = match &arr[3] {
                        Object::String(b, _) => Some(b.clone()),
                        Object::Reference(id) => match self.get_object(*id).ok()? {
                            Object::Stream(s) => Some(s.content),
                            Object::String(b, _) => Some(b),
                            _ => None,
                        },
                        _ => None,
                    };
                    if let Some(lookup) = lookup_bytes {
                        // Bound against hostile dimensions before allocating.
                        let need = (width as usize).checked_mul(height as usize)?;
                        let cap = need.checked_mul(base_channels)?;
                        if need > 16_384 * 16_384 {
                            return None;
                        }
                        if stream.content.len() >= need {
                            let mut expanded = Vec::with_capacity(cap);
                            for &idx in &stream.content[..need] {
                                let off = (idx as usize) * base_channels;
                                if off + base_channels <= lookup.len() {
                                    expanded.extend_from_slice(
                                        &lookup[off..off + base_channels],
                                    );
                                } else {
                                    for _ in 0..base_channels {
                                        expanded.push(0);
                                    }
                                }
                            }
                            let png = encode_png(
                                &expanded,
                                width as u32,
                                height as u32,
                                base_channels as u8,
                            )?;
                            return Some((ImageEncoding::Png, png));
                        }
                    }
                }
            }
        }
        let channels = match cs_name.as_deref() {
            Some("DeviceRGB") | Some("CalRGB") => 3,
            Some("DeviceGray") | Some("CalGray") => 1,
            Some("DeviceCMYK") => 4,
            // ICCBased: `[/ICCBased <ref>]` where the ICC stream's /N
            // declares the channel count.
            Some("ICCBased") => cs_obj_resolved
                .as_ref()
                .and_then(|o| o.as_array().ok())
                .and_then(|arr| arr.get(1))
                .and_then(|o| self.dereference(o).ok())
                .map(|(_, v)| v)
                .and_then(|v| match v {
                    Object::Stream(s) => Some(s.dict),
                    _ => None,
                })
                .and_then(|d| d.get_optional(b"N").and_then(|o| o.as_i64().ok()))
                .unwrap_or(0) as usize,
            _ => 0,
        };
        if channels == 0 || bpc != 8 {
            return None;
        }
        let png = encode_png(&stream.content, width as u32, height as u32, channels as u8)?;
        Some((ImageEncoding::Png, png))
    }

    /// Walk the `/Outlines` tree and produce a flat list of
    /// `(level, title, page_num)`. Returns `Err(Error::NoOutline)`
    /// when the catalog lacks an `/Outlines` entry.
    pub fn get_toc(&self) -> Result<Vec<TocEntry>> {
        let catalog = self.catalog()?;
        let outlines_obj = catalog
            .get_optional(b"Outlines")
            .ok_or(crate::error::Error::NoOutline)?
            .clone();
        let outlines_root = match outlines_obj {
            Object::Reference(id) => self.get_dictionary(id)?,
            Object::Dictionary(d) => d,
            _ => return Err(crate::error::Error::NoOutline),
        };
        let page_id_to_num: std::collections::BTreeMap<ObjectId, u32> = self
            .get_pages()
            .into_iter()
            .map(|(num, id)| (id, num))
            .collect();
        let mut out: Vec<TocEntry> = Vec::new();
        if let Some(first_ref) = outlines_root.get_optional(b"First") {
            if let Ok(id) = first_ref.as_reference() {
                self.walk_outline_level(id, 1, &page_id_to_num, &mut out, 0);
            }
        }
        Ok(out)
    }

    fn walk_outline_level(
        &self,
        node_id: ObjectId,
        level: usize,
        page_id_to_num: &std::collections::BTreeMap<ObjectId, u32>,
        out: &mut Vec<TocEntry>,
        depth: usize,
    ) {
        if depth > 64 {
            return;
        }
        let mut cur_id = node_id;
        let mut visited = std::collections::HashSet::new();
        loop {
            if !visited.insert(cur_id) {
                break;
            }
            let Ok(node) = self.get_dictionary(cur_id) else {
                break;
            };
            let title = node
                .get_optional(b"Title")
                .and_then(|o| match o {
                    Object::String(b, _) => Some(decode_pdf_text_string(b)),
                    _ => None,
                })
                .unwrap_or_default();
            let page = self.resolve_outline_dest(&node, page_id_to_num);
            out.push(TocEntry {
                level,
                title,
                page,
            });
            if let Some(first) = node.get_optional(b"First").cloned() {
                if let Ok(child) = first.as_reference() {
                    self.walk_outline_level(child, level + 1, page_id_to_num, out, depth + 1);
                }
            }
            let Some(next) = node.get_optional(b"Next") else {
                break;
            };
            let Ok(next_id) = next.as_reference() else {
                break;
            };
            cur_id = next_id;
        }
    }

    fn resolve_outline_dest(
        &self,
        node: &Dictionary,
        page_id_to_num: &std::collections::BTreeMap<ObjectId, u32>,
    ) -> Option<u32> {
        // /Dest takes precedence over /A.
        if let Some(dest) = node.get_optional(b"Dest") {
            return self.resolve_dest_object(dest, page_id_to_num);
        }
        if let Some(action_obj) = node.get_optional(b"A") {
            let action_dict = match action_obj {
                Object::Reference(id) => self.get_dictionary(*id).ok(),
                Object::Dictionary(d) => Some(d.clone()),
                _ => None,
            };
            if let Some(action) = action_dict {
                if let Some(d) = action.get_optional(b"D") {
                    return self.resolve_dest_object(d, page_id_to_num);
                }
            }
        }
        None
    }

    /// Public destination resolver. Accepts any destination shape PDF
    /// readers see (name, string, destination array, or indirect ref
    /// to either) and returns a 1-indexed page number if resolvable.
    pub fn resolve_destination_to_page(&self, dest: &Object) -> Option<u32> {
        let page_id_to_num: std::collections::BTreeMap<ObjectId, u32> = self
            .get_pages()
            .into_iter()
            .map(|(num, id)| (id, num))
            .collect();
        self.resolve_dest_object(dest, &page_id_to_num)
    }

    fn resolve_dest_object(
        &self,
        dest: &Object,
        page_id_to_num: &std::collections::BTreeMap<ObjectId, u32>,
    ) -> Option<u32> {
        match dest {
            Object::Array(arr) => {
                let first = arr.first()?;
                let id = first.as_reference().ok()?;
                page_id_to_num.get(&id).copied()
            }
            Object::Reference(id) => self
                .get_object(*id)
                .ok()
                .and_then(|o| self.resolve_dest_object(&o, page_id_to_num)),
            // Named destination — looked up in catalog's /Names/Dests
            // (PDF 1.2+) or /Dests dictionary (PDF 1.1).
            Object::Name(name) => self.resolve_named_destination(name, page_id_to_num),
            Object::String(bytes, _) => self.resolve_named_destination(bytes, page_id_to_num),
            // Destination dictionary: `<< /D [page_ref /XYZ x y z] >>`
            // per PDF spec §12.3.2.3 — explicit-destination dicts
            // wrap the array under /D.
            Object::Dictionary(d) => d
                .get_optional(b"D")
                .and_then(|inner| self.resolve_dest_object(inner, page_id_to_num)),
            _ => None,
        }
    }

    /// Resolve a named destination by walking the catalog's
    /// `/Names/Dests` name-tree (PDF 1.2+) or `/Dests` dictionary
    /// (PDF 1.1). Without this, name-tree outlines resolve to no page.
    fn resolve_named_destination(
        &self,
        name: &[u8],
        page_id_to_num: &std::collections::BTreeMap<ObjectId, u32>,
    ) -> Option<u32> {
        let catalog = self.catalog().ok()?;
        // PDF 1.1: /Dests is a flat dictionary { name → dest-array }.
        if let Some(dests_obj) = catalog.get_optional(b"Dests") {
            if let Some(dests) = self.deref_dict(dests_obj) {
                if let Some(target) = dests.get_optional(name) {
                    return self.resolve_dest_object(target, page_id_to_num);
                }
            }
        }
        // PDF 1.2+: /Names/Dests is a name-tree.
        let names = catalog
            .get_optional(b"Names")
            .and_then(|n| self.deref_dict(n))?;
        let dests_tree = names
            .get_optional(b"Dests")
            .and_then(|d| self.deref_dict(d))?;
        let dest_value = self.lookup_name_tree(&dests_tree, name)?;
        // The leaf value can be `<< /D [page_ref /XYZ ...] >>` or the
        // dest array directly; handle both.
        match &dest_value {
            Object::Dictionary(d) => {
                if let Some(d_val) = d.get_optional(b"D") {
                    self.resolve_dest_object(d_val, page_id_to_num)
                } else {
                    None
                }
            }
            _ => self.resolve_dest_object(&dest_value, page_id_to_num),
        }
    }

    /// Walk a PDF name-tree (`/Names`, `/Kids`, `/Limits`) per spec
    /// §7.9.6. `/Limits` lets us descend only the relevant kid.
    fn lookup_name_tree(&self, node: &Dictionary, key: &[u8]) -> Option<Object> {
        // Leaf: /Names is an array of alternating key/value pairs.
        if let Some(names_obj) = node.get_optional(b"Names") {
            if let Ok(names_arr) = names_obj.as_array() {
                let mut i = 0;
                while i + 1 < names_arr.len() {
                    if let Object::String(k_bytes, _) = &names_arr[i] {
                        if k_bytes.as_slice() == key {
                            return Some(names_arr[i + 1].clone());
                        }
                    }
                    i += 2;
                }
            }
        }
        // Interior: /Kids is an array of refs to sub-trees with their
        // own /Limits.
        if let Some(kids_obj) = node.get_optional(b"Kids") {
            if let Ok(kids) = kids_obj.as_array() {
                for kid in kids {
                    let Ok(kid_id) = kid.as_reference() else { continue };
                    let Ok(kid_dict) = self.get_dictionary(kid_id) else { continue };
                    // /Limits = [low, high]: descend only when key is in range.
                    if let Some(limits_obj) = kid_dict.get_optional(b"Limits") {
                        if let Ok(limits) = limits_obj.as_array() {
                            if limits.len() >= 2 {
                                let lo = match &limits[0] {
                                    Object::String(b, _) => b.as_slice(),
                                    _ => continue,
                                };
                                let hi = match &limits[1] {
                                    Object::String(b, _) => b.as_slice(),
                                    _ => continue,
                                };
                                if key < lo || key > hi {
                                    continue;
                                }
                            }
                        }
                    }
                    if let Some(v) = self.lookup_name_tree(&kid_dict, key) {
                        return Some(v);
                    }
                }
            }
        }
        None
    }

    /// Extract text from the listed page numbers (1-indexed), in
    /// order.
    pub fn extract_text(&self, page_numbers: &[u32]) -> Result<String> {
        let mut out = String::with_capacity(4096);
        let pages = self.get_pages();
        for &n in page_numbers {
            let Some(&page_id) = pages.get(&n) else {
                return Err(ParseError::Other(format!("page {n} not found")).into());
            };
            let content = self.get_page_content(page_id).unwrap_or_default();
            let fonts = self.get_page_fonts(page_id).unwrap_or_default();
            let encodings = crate::encoding::resolve_page_encodings(self, &fonts);
            let extracted =
                crate::content::extract_text_from_stream(&content, &encodings);
            out.push_str(&extracted);
        }
        Ok(out)
    }

    /// Lazily resolve an object. Cached on first hit.
    pub fn get_object(&self, id: ObjectId) -> Result<Object> {
        if let Some(obj) = self.cache.read().ok().and_then(|c| c.get(&id).cloned()) {
            return Ok(obj);
        }
        let entry = *self
            .xref
            .get(id.0)
            .ok_or(Error::ObjectNotFound(id.0, id.1))?;
        let mut parsed = match entry {
            XrefEntry::Normal { offset, generation } => {
                if generation != id.1 && id.1 != 0 {
                    return Err(XrefError::Generation.into());
                }
                let (parsed_id, body) =
                    read_indirect_object_at(&self.buffer, offset as usize)?;
                let parsed = self.materialize_stream_body(parsed_id, body)?;
                parsed
            }
            XrefEntry::Compressed { container, index } => {
                self.materialize_compressed_object(id, container, index)?
            }
            XrefEntry::Free => return Err(Error::ObjectNotFound(id.0, id.1)),
        };
        // Objects stored inside an object stream are NOT individually
        // encrypted — only the container is. Skip the per-object pass
        // when this entry came from a Compressed slot.
        if let Some(dec) = &self.decryptor {
            let is_from_object_stream =
                matches!(entry, XrefEntry::Compressed { .. });
            if !is_from_object_stream {
                dec.decrypt_object(&mut parsed, id);
            }
        }
        if let Ok(mut cache) = self.cache.write() {
            cache.entry(id).or_insert_with(|| parsed.clone());
        }
        Ok(parsed)
    }

    /// `get_object` resolved to a `Dictionary` (or a stream's dict).
    pub fn get_dictionary(&self, id: ObjectId) -> Result<Dictionary> {
        let obj = self.get_object(id)?;
        match obj {
            Object::Dictionary(d) => Ok(d),
            Object::Stream(s) => Ok(s.dict),
            other => Err(Error::Type {
                expected: "Dictionary",
                found: other.type_name(),
            }),
        }
    }

    /// Resolve a possibly-indirect reference to its concrete object.
    /// Returns `(Some(id), object)` when a reference was traversed,
    /// `(None, object)` when the input was already direct.
    pub fn dereference(&self, obj: &Object) -> Result<(Option<ObjectId>, Object)> {
        let mut cur = obj.clone();
        let mut last_id = None;
        let mut hops = 0usize;
        while let Object::Reference(id) = cur {
            if hops > 32 {
                return Err(ParseError::Other("reference cycle".into()).into());
            }
            last_id = Some(id);
            cur = self.get_object(id)?;
            hops += 1;
        }
        Ok((last_id, cur))
    }

    /// Promote a parsed `Object::Stream` whose body hasn't been
    /// captured yet into one whose `content` is the *decoded* bytes.
    /// Applies the `/Filter` chain with `/DecodeParms` predictor
    /// decoding. Streams whose filter chain ends in an image-only
    /// codec (DCTDecode, JPX, JBIG2, CCITT) keep their raw content.
    fn materialize_stream_body(&self, id: ObjectId, obj: Object) -> Result<Object> {
        match obj {
            Object::Stream(mut s) => {
                if let Some(start) = s.start_position {
                    let len = self.stream_length(&s.dict)?;
                    let end = start + len;
                    if end > self.buffer.len() {
                        return Ok(Object::Stream(s)); // truncated; leave empty
                    }
                    // PDF spec §7.6.3: stream contents are encrypted on
                    // disk; the /Filter chain operates on the decrypted
                    // bytes. /Type /XRef streams are exempt from
                    // encryption per spec.
                    let raw_bytes: Vec<u8> = if let Some(dec) = &self.decryptor {
                        let is_xref = s
                            .dict
                            .get_optional(b"Type")
                            .and_then(|o| o.as_name().ok())
                            .map(|n| n == b"XRef")
                            .unwrap_or(false);
                        if is_xref {
                            self.buffer[start..end].to_vec()
                        } else {
                            let mut tmp = self.buffer[start..end].to_vec();
                            dec.decrypt_stream_bytes(&mut tmp, id);
                            tmp
                        }
                    } else {
                        self.buffer[start..end].to_vec()
                    };
                    let filters = stream_filters(&s.dict);
                    if filters.is_empty() {
                        s.content = raw_bytes;
                    } else {
                        let parms = s.dict.get_optional(b"DecodeParms");
                        match crate::filter::apply_chain(&raw_bytes, &filters, parms) {
                            Ok(decoded) => s.content = decoded,
                            Err(crate::error::Error::UnsupportedFilter(_)) => {
                                // Image-only filter chain — leave the
                                // decrypted-but-encoded bytes for
                                // get_image_bytes to pass through.
                                s.content = raw_bytes;
                            }
                            Err(e) => return Err(e),
                        }
                    }
                }
                Ok(Object::Stream(s))
            }
            other => Ok(other),
        }
    }

    /// Materialize one object stored inside a PDF 1.5+ object-stream
    /// container (`/Type/ObjStm`) per spec §7.5.7. Decompressed content
    /// begins with `N` `(object_num, byte_offset)` pairs; `/First` is
    /// the byte offset (within decompressed content) of the first
    /// payload, and each payload starts at `First + byte_offset`.
    fn materialize_compressed_object(
        &self,
        target_id: ObjectId,
        container_num: u32,
        index: u32,
    ) -> Result<Object> {
        let container_id = (container_num, 0);
        let container_obj = self.get_object(container_id)?;
        let stream = match container_obj {
            Object::Stream(s) => s,
            _ => {
                return Err(ParseError::Other(format!(
                    "object {} {} expected to be ObjStm container but got {}",
                    container_id.0,
                    container_id.1,
                    container_obj.type_name()
                ))
                .into());
            }
        };
        let n = stream
            .dict
            .get(b"N")
            .map_err(|_| ParseError::Other("ObjStm missing /N".into()))?
            .as_i64()? as usize;
        let first = stream
            .dict
            .get(b"First")
            .map_err(|_| ParseError::Other("ObjStm missing /First".into()))?
            .as_i64()? as usize;
        let content = &stream.content;
        if first > content.len() {
            return Err(ParseError::Other("ObjStm /First past content end".into()).into());
        }
        if (index as usize) >= n {
            return Err(ParseError::Other(format!(
                "ObjStm index {index} out of bounds (N={n})"
            ))
            .into());
        }
        // Header: 2N whitespace-separated integers (object_num, offset).
        let mut c = crate::parser::Cursor::at(content, 0);
        let mut header: Vec<(u32, usize)> = Vec::with_capacity(n);
        for _ in 0..n {
            c.skip_ws_and_comments();
            let obj_num = crate::parser::read_integer(&mut c)?;
            c.skip_ws_and_comments();
            let offset = crate::parser::read_integer(&mut c)?;
            if obj_num < 0 || offset < 0 {
                return Err(ParseError::Other("ObjStm negative header value".into()).into());
            }
            header.push((obj_num as u32, offset as usize));
        }
        let (obj_num, payload_offset) = header[index as usize];
        if obj_num != target_id.0 {
            return Err(ParseError::Other(format!(
                "ObjStm index {index} declared object {obj_num} but we requested {}",
                target_id.0
            ))
            .into());
        }
        let start = first + payload_offset;
        if start >= content.len() {
            return Err(ParseError::Other("ObjStm payload start past content end".into()).into());
        }
        // Spec forbids raw Stream entries inside an ObjStm container.
        let mut payload = crate::parser::Cursor::at(content, start);
        let parsed = crate::parser::read_object(&mut payload)?;
        Ok(parsed)
    }

    /// Resolve a stream's `/Length` to a concrete usize. The length
    /// may be an indirect reference to another integer object.
    fn stream_length(&self, dict: &Dictionary) -> Result<usize> {
        let raw = dict.get(b"Length")?;
        let (_id, resolved) = self.dereference(raw)?;
        let n = resolved.as_i64()?;
        if n < 0 {
            return Err(ParseError::Other("negative stream length".into()).into());
        }
        Ok(n as usize)
    }
}

fn form_value_to_string(obj: &Object) -> String {
    match obj {
        Object::String(b, _) => decode_pdf_text_string(b),
        Object::Name(b) => decode_pdf_text_string(b),
        Object::Integer(i) => i.to_string(),
        Object::Real(f) => format!("{f}"),
        Object::Boolean(b) => b.to_string(),
        Object::Array(a) => a
            .iter()
            .map(form_value_to_string)
            .collect::<Vec<_>>()
            .join(", "),
        _ => String::new(),
    }
}

fn encode_png(raw: &[u8], width: u32, height: u32, channels: u8) -> Option<Vec<u8>> {
    use std::io::Write;
    // Defensive bounds — a hostile PDF can declare arbitrary /Width
    // and /Height; without this guard a multi-petabyte capacity hint
    // would abort the allocator. 16384 covers every real-world image.
    const MAX_DIM: u32 = 16_384;
    if channels == 0 || width == 0 || height == 0 || width > MAX_DIM || height > MAX_DIM {
        return None;
    }
    let row_len = (width as usize).checked_mul(channels as usize)?;
    let need = row_len.checked_mul(height as usize)?;
    if raw.len() < need {
        return None;
    }
    let cap = row_len.checked_add(1)?.checked_mul(height as usize)?;
    let mut filtered = Vec::with_capacity(cap);
    for row in 0..height as usize {
        filtered.push(0u8);
        let start = row * row_len;
        let end = start + row_len;
        if channels == 4 {
            for px in raw[start..end].chunks_exact(4) {
                let (c, m, y, k) = (px[0] as f32, px[1] as f32, px[2] as f32, px[3] as f32);
                let r = ((255.0 - c) * (255.0 - k) / 255.0).clamp(0.0, 255.0).round() as u8;
                let g = ((255.0 - m) * (255.0 - k) / 255.0).clamp(0.0, 255.0).round() as u8;
                let bl = ((255.0 - y) * (255.0 - k) / 255.0).clamp(0.0, 255.0).round() as u8;
                filtered.push(r);
                filtered.push(g);
                filtered.push(bl);
            }
        } else {
            filtered.extend_from_slice(&raw[start..end]);
        }
    }
    use flate2::write::ZlibEncoder;
    use flate2::Compression;
    let mut enc = ZlibEncoder::new(Vec::new(), Compression::default());
    enc.write_all(&filtered).ok()?;
    let zlib = enc.finish().ok()?;
    let color_type: u8 = match if channels == 4 { 3 } else { channels } {
        1 => 0,
        3 => 2,
        _ => return None,
    };
    let mut out = Vec::with_capacity(zlib.len() + 64);
    out.extend_from_slice(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]);
    let mut ihdr = Vec::with_capacity(13);
    ihdr.extend_from_slice(&width.to_be_bytes());
    ihdr.extend_from_slice(&height.to_be_bytes());
    ihdr.push(8);
    ihdr.push(color_type);
    ihdr.push(0);
    ihdr.push(0);
    ihdr.push(0);
    write_png_chunk(&mut out, b"IHDR", &ihdr).ok()?;
    write_png_chunk(&mut out, b"IDAT", &zlib).ok()?;
    write_png_chunk(&mut out, b"IEND", &[]).ok()?;
    Some(out)
}

fn write_png_chunk(
    out: &mut Vec<u8>,
    chunk_type: &[u8; 4],
    data: &[u8],
) -> std::io::Result<()> {
    use std::io::Write;
    out.write_all(&(data.len() as u32).to_be_bytes())?;
    out.write_all(chunk_type)?;
    out.write_all(data)?;
    let mut crc = Crc32::new();
    crc.update(chunk_type);
    crc.update(data);
    out.write_all(&crc.finalize().to_be_bytes())?;
    Ok(())
}

struct Crc32 {
    state: u32,
}

impl Crc32 {
    fn new() -> Self {
        Self { state: 0xFFFF_FFFF }
    }
    fn update(&mut self, bytes: &[u8]) {
        for &b in bytes {
            let mut c = (self.state ^ b as u32) & 0xFF;
            for _ in 0..8 {
                c = if c & 1 != 0 { 0xEDB8_8320 ^ (c >> 1) } else { c >> 1 };
            }
            self.state = c ^ (self.state >> 8);
        }
    }
    fn finalize(self) -> u32 {
        self.state ^ 0xFFFF_FFFF
    }
}

/// One AcroForm field returned by [`Document::get_form_fields`].
/// Dot-separated partial names per PDF spec §12.7.4.2 — a nested
/// field "address" → "street" → "city" lands as `address.street.city`.
#[derive(Debug, Clone)]
pub struct FormField {
    pub name: String,
    pub value: String,
    pub default_value: String,
    pub field_type: FormFieldType,
    pub flags: i64,
    pub rect: Option<[f32; 4]>,
    pub page: Option<u32>,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FormFieldType {
    Text,
    Button,
    Choice,
    Signature,
    Unknown,
}

impl FormFieldType {
    pub fn as_pdf_name(self) -> &'static str {
        match self {
            Self::Text => "Tx",
            Self::Button => "Btn",
            Self::Choice => "Ch",
            Self::Signature => "Sig",
            Self::Unknown => "",
        }
    }
}

/// Container hint for [`Document::get_image_bytes`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageEncoding {
    Jpeg,
    Jpeg2000,
    Png,
    Jbig2,
    Ccitt,
}

impl ImageEncoding {
    pub fn extension(self) -> &'static str {
        match self {
            Self::Jpeg => "jpg",
            Self::Jpeg2000 => "jp2",
            Self::Png => "png",
            Self::Jbig2 => "jb2",
            Self::Ccitt => "tiff",
        }
    }
}

/// Image inventory returned by [`Document::get_page_images`].
#[derive(Debug, Clone)]
pub struct PdfImageInfo {
    pub id: ObjectId,
    pub width: i64,
    pub height: i64,
    /// `/ColorSpace` name (or first array element when colorspace is
    /// an array). Standardized colorspace names are ASCII so a lossy
    /// UTF-8 decode preserves exact matches.
    pub color_space: Option<String>,
    pub bits_per_component: Option<i64>,
    /// Filter chain (`DCTDecode`, `FlateDecode`, etc.).
    pub filters: Vec<String>,
    /// Raw encoded byte length (we don't decode image content).
    pub content_len: usize,
}

/// One outline (TOC) entry returned by [`Document::get_toc`].
#[derive(Debug, Clone)]
pub struct TocEntry {
    /// 1-indexed depth (root chapters at level 1).
    pub level: usize,
    /// Title after PDF-string decoding (BOM-aware UTF-16 / PDFDocEncoding).
    pub title: String,
    /// 1-indexed destination page number, when resolvable.
    pub page: Option<u32>,
}

/// Decode a PDF text string per spec §7.9.2.2 — handles UTF-16BE BOM,
/// UTF-16LE BOM, and PDFDocEncoding (the implicit default).
///
/// PDFDocEncoding is **not** Latin-1: bytes 0x18..=0x1F and 0x80..=0x9F
/// map to specific glyphs (e.g. 0x92 → `'` U+2019). Latin-1 round-trip
/// silently butchers them.
fn decode_pdf_text_string(bytes: &[u8]) -> String {
    if bytes.len() >= 2 && bytes[0] == 0xfe && bytes[1] == 0xff {
        let utf16: Vec<u16> = bytes[2..]
            .chunks_exact(2)
            .map(|c| u16::from_be_bytes([c[0], c[1]]))
            .collect();
        String::from_utf16_lossy(&utf16)
    } else if bytes.len() >= 2 && bytes[0] == 0xff && bytes[1] == 0xfe {
        let utf16: Vec<u16> = bytes[2..]
            .chunks_exact(2)
            .map(|c| u16::from_le_bytes([c[0], c[1]]))
            .collect();
        String::from_utf16_lossy(&utf16)
    } else {
        bytes
            .iter()
            .map(|&b| pdf_doc_encoding_to_char(b))
            .collect()
    }
}

/// Decode a single byte from a non-BOM PDF text string. Pragmatic
/// rather than spec-pure: the PDF spec calls for PDFDocEncoding
/// (Annex D §D.2), but real-world Windows PDF generators emit CP1252
/// byte values where the two encodings disagree. PDFDocEncoding-only
/// glyphs (0x18..=0x1F, 0x9F) are still mapped per spec.
fn pdf_doc_encoding_to_char(b: u8) -> char {
    match b {
        // PDFDocEncoding-only: §D.2 byte 0x18..=0x1F.
        0x18 => '\u{02D8}', // BREVE
        0x19 => '\u{02C7}', // CARON
        0x1A => '\u{02C6}', // MODIFIER LETTER CIRCUMFLEX ACCENT
        0x1B => '\u{02D9}', // DOT ABOVE
        0x1C => '\u{02DD}', // DOUBLE ACUTE ACCENT
        0x1D => '\u{02DB}', // OGONEK
        0x1E => '\u{02DA}', // RING ABOVE
        0x1F => '\u{02DC}', // SMALL TILDE
        // CP1252-compatible high-byte glyphs.
        0x80 => '\u{20AC}', // €
        0x82 => '\u{201A}', // ‚
        0x83 => '\u{0192}', // ƒ
        0x84 => '\u{201E}', // „
        0x85 => '\u{2026}', // …
        0x86 => '\u{2020}', // †
        0x87 => '\u{2021}', // ‡
        0x88 => '\u{02C6}', // ˆ
        0x89 => '\u{2030}', // ‰
        0x8A => '\u{0160}', // Š
        0x8B => '\u{2039}', // ‹
        0x8C => '\u{0152}', // Œ
        0x8E => '\u{017D}', // Ž
        // 0x90: PDFDocEncoding spec emits U+2019 here; CP1252 leaves
        // this slot unused.
        0x90 => '\u{2019}', // '
        0x91 => '\u{2018}', // '
        0x92 => '\u{2019}', // ' (CP1252 path for Windows generators)
        0x93 => '\u{201C}', // "
        0x94 => '\u{201D}', // "
        0x95 => '\u{2022}', // •
        0x96 => '\u{2013}', // –
        0x97 => '\u{2014}', // —
        0x98 => '\u{02DC}', // ˜
        0x99 => '\u{2122}', // ™
        0x9A => '\u{0161}', // š
        0x9B => '\u{203A}', // ›
        0x9C => '\u{0153}', // œ
        0x9E => '\u{017E}', // ž
        0x9F => '\u{0178}', // Ÿ
        // Everything else maps as Latin-1.
        _ => b as char,
    }
}

/// Construct a [`PdfImageInfo`] from an image-XObject stream.
/// `extract_color_space_name` surfaces the colorspace name from any
/// of the four real-world shapes (plain name, array, indirect ref,
/// resource-name) — see [`extract_color_space_name`].
fn make_image_info(id: ObjectId, stream: &Stream) -> PdfImageInfo {
    let width = stream
        .dict
        .get_optional(b"Width")
        .and_then(|o| o.as_i64().ok())
        .unwrap_or(0);
    let height = stream
        .dict
        .get_optional(b"Height")
        .and_then(|o| o.as_i64().ok())
        .unwrap_or(0);
    let bits_per_component = stream
        .dict
        .get_optional(b"BitsPerComponent")
        .and_then(|o| o.as_i64().ok());
    let color_space = stream
        .dict
        .get_optional(b"ColorSpace")
        .and_then(extract_color_space_name);
    let filters = stream_filters(&stream.dict);
    PdfImageInfo {
        id,
        width,
        height,
        color_space,
        bits_per_component,
        filters,
        content_len: stream.content.len(),
    }
}

/// Extract a colorspace name from any of these shapes:
/// 1. `/DeviceRGB` (or other simple name)
/// 2. `[/ICCBased <ref>]` / `[/Indexed ...]` array — first element wins
/// 3. indirect ref into `/Resources/ColorSpace` (caller must deref first)
/// 4. resource-name like `/CS1` (returned as-is; caller resolves)
fn extract_color_space_name(obj: &Object) -> Option<String> {
    match obj {
        Object::Name(n) => Some(String::from_utf8_lossy(n).into_owned()),
        Object::Array(arr) => arr.first().and_then(|first| match first {
            Object::Name(n) => Some(String::from_utf8_lossy(n).into_owned()),
            _ => None,
        }),
        _ => None,
    }
}

/// Read a stream's `/Filter` entry as a list of codec names. Returns
/// an empty `Vec` when the entry is absent or in an unexpected form.
pub(crate) fn stream_filters(dict: &Dictionary) -> Vec<String> {
    match dict.get_optional(b"Filter") {
        Some(Object::Name(n)) => vec![String::from_utf8_lossy(n).into_owned()],
        Some(Object::Array(arr)) => arr
            .iter()
            .filter_map(|o| match o {
                Object::Name(n) => Some(String::from_utf8_lossy(n).into_owned()),
                _ => None,
            })
            .collect(),
        _ => Vec::new(),
    }
}

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

    /// Hand-built minimal classical-xref PDF: catalog → pages → one
    /// page, followed by xref / trailer / startxref / %%EOF.
    fn build_minimal_pdf() -> Vec<u8> {
        let mut body = String::new();
        // Four 0x80+ bytes are the spec-required binary marker comment.
        let header = b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n";

        let off1 = header.len();
        let obj1 = "1 0 obj\n<< /Type /Catalog /Pages 2 0 R >>\nendobj\n";
        body.push_str(obj1);

        let off2 = header.len() + body.len();
        let obj2 = "2 0 obj\n<< /Type /Pages /Kids [3 0 R] /Count 1 >>\nendobj\n";
        body.push_str(obj2);

        let off3 = header.len() + body.len();
        let obj3 = "3 0 obj\n<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>\nendobj\n";
        body.push_str(obj3);

        let xref_start = header.len() + body.len();
        let mut xref = String::new();
        xref.push_str("xref\n0 4\n");
        xref.push_str("0000000000 65535 f \n");
        xref.push_str(&format!("{off1:010} 00000 n \n"));
        xref.push_str(&format!("{off2:010} 00000 n \n"));
        xref.push_str(&format!("{off3:010} 00000 n \n"));

        let tail = format!(
            "trailer\n<< /Size 4 /Root 1 0 R >>\nstartxref\n{xref_start}\n%%EOF\n"
        );

        let mut out = Vec::with_capacity(header.len() + body.len() + xref.len() + tail.len());
        out.extend_from_slice(header);
        out.extend_from_slice(body.as_bytes());
        out.extend_from_slice(xref.as_bytes());
        out.extend_from_slice(tail.as_bytes());
        out
    }

    #[test]
    fn open_returns_version_and_trailer_keys() {
        let bytes = build_minimal_pdf();
        let doc = Document::open(&bytes).expect("open");
        assert_eq!(doc.version, "1.4");
        assert!(doc.trailer.get_optional(b"Root").is_some());
        assert!(doc.trailer.get_optional(b"Size").is_some());
        // free entry + 3 objects.
        assert_eq!(doc.xref.len(), 4, "xref entries: {}", doc.xref.len());
    }

    #[test]
    fn get_object_resolves_catalog_to_dictionary() {
        let bytes = build_minimal_pdf();
        let doc = Document::open(&bytes).expect("open");
        let root_ref = doc
            .trailer
            .get(b"Root")
            .expect("Root present")
            .as_reference()
            .expect("Root is reference");
        let cat = doc.get_object(root_ref).expect("get_object catalog");
        let dict = cat.as_dict().expect("catalog is dict");
        assert!(dict.has_type(b"Catalog"));
    }

    #[test]
    fn second_get_object_call_hits_cache() {
        // Regression: two calls must return equal objects without
        // panicking on the second materialization path.
        let bytes = build_minimal_pdf();
        let doc = Document::open(&bytes).expect("open");
        let root_ref = doc.trailer.get(b"Root").unwrap().as_reference().unwrap();
        let a = doc.get_object(root_ref).unwrap();
        let b = doc.get_object(root_ref).unwrap();
        assert_eq!(format!("{a:?}"), format!("{b:?}"));
    }
}