oxidize_pdf/

page.rs

use crate::annotations::Annotation;
use crate::error::Result;
use crate::fonts::type0_parsing::{detect_type0_font, resolve_type0_hierarchy};
use crate::forms::Widget;
use crate::graphics::{GraphicsContext, Image};
use crate::objects::{Array, Dictionary, Object, ObjectReference};
use crate::text::metrics::FontMetricsStore;
use crate::text::{HeaderFooter, Table, TextContext, TextFlowContext};
use std::collections::{HashMap, HashSet};

/// Page margins in points (1/72 inch).
#[derive(Clone, Debug)]
pub struct Margins {
    /// Left margin
    pub left: f64,
    /// Right margin
    pub right: f64,
    /// Top margin
    pub top: f64,
    /// Bottom margin
    pub bottom: f64,
}

impl Default for Margins {
    fn default() -> Self {
        Self {
            left: 72.0,   // 1 inch
            right: 72.0,  // 1 inch
            top: 72.0,    // 1 inch
            bottom: 72.0, // 1 inch
        }
    }
}

/// A single page in a PDF document.
///
/// Pages have a size (width and height in points), margins, and can contain
/// graphics, text, and images.
///
/// # Example
///
/// ```rust
/// use oxidize_pdf::{Page, Font, Color};
///
/// let mut page = Page::a4();
///
/// // Add text
/// page.text()
///     .set_font(Font::Helvetica, 12.0)
///     .at(100.0, 700.0)
///     .write("Hello World")?;
///
/// // Add graphics
/// page.graphics()
///     .set_fill_color(Color::red())
///     .rect(100.0, 100.0, 200.0, 150.0)
///     .fill();
/// # Ok::<(), oxidize_pdf::PdfError>(())
/// ```
/// Validates that `name` is a well-formed PDF resource name per
/// ISO 32000-1 §7.3.5 (Name Objects).
///
/// A resource name is a `Name` token written as `/<name>` inside a
/// dictionary. The spec forbids:
///   * empty names (must have at least one regular character);
///   * whitespace characters (NUL, HT, LF, FF, CR, SP);
///   * delimiter characters `( ) < > [ ] { } / %`;
///   * the `#` character, which is reserved for the 2-digit hex escape
///     form (`#NN`) — accepting raw `#` would require callers to think
///     about hex escaping, which we decline to do at this layer.
///
/// We reject at the public API boundary so a caller cannot — even
/// unintentionally — smuggle a dict-closing token into a resource name
/// and produce a PDF where the emitted `/<name>` splits the resource
/// dict into pieces.
fn validate_pdf_resource_name(name: &str) -> Result<()> {
    use crate::error::PdfError;

    if name.is_empty() {
        return Err(PdfError::InvalidStructure(
            "PDF resource name must not be empty (ISO 32000-1 §7.3.5)".to_string(),
        ));
    }

    for (idx, byte) in name.as_bytes().iter().enumerate() {
        // Whitespace per Table 1 (§7.2.3).
        let is_whitespace = matches!(*byte, 0x00 | 0x09 | 0x0A | 0x0C | 0x0D | 0x20);
        // Delimiters per Table 2 (§7.2.3).
        let is_delimiter = matches!(
            *byte,
            b'(' | b')' | b'<' | b'>' | b'[' | b']' | b'{' | b'}' | b'/' | b'%'
        );
        // Hex-escape introducer (§7.3.5): legal only as `#NN`, but we
        // reject outright rather than trust callers to escape correctly.
        let is_hash = *byte == b'#';

        if is_whitespace || is_delimiter || is_hash {
            return Err(PdfError::InvalidStructure(format!(
                "invalid PDF resource name {name:?}: byte 0x{byte:02X} at position {idx} \
                 is not allowed per ISO 32000-1 §7.3.5 (whitespace, delimiter, or `#`)"
            )));
        }
    }
    Ok(())
}

#[derive(Clone)]
pub struct Page {
    width: f64,
    height: f64,
    margins: Margins,
    content: Vec<u8>,
    graphics_context: GraphicsContext,
    text_context: TextContext,
    images: HashMap<String, Image>,
    form_xobjects: HashMap<String, crate::graphics::FormXObject>,
    /// Registered colour spaces, emitted under `/Resources/ColorSpace`
    /// per ISO 32000-1 §8.6, Table 62. Values are typed via
    /// [`crate::graphics::PageColorSpace`] — see that enum for the two
    /// supported wire-format shapes (device alias vs. parameterised
    /// `[/<family> <<params>>]`).
    color_spaces: HashMap<String, crate::graphics::PageColorSpace>,
    /// Registered tiling patterns, emitted as indirect stream objects
    /// referenced from `/Resources/Pattern` per ISO 32000-1 §8.7.3.
    patterns: HashMap<String, crate::graphics::TilingPattern>,
    /// Registered shadings, emitted as indirect dictionary objects
    /// referenced from `/Resources/Shading` per ISO 32000-1 §8.7.4.
    shadings: HashMap<String, crate::graphics::ShadingDefinition>,
    /// Registered mesh (Type 4) and conic (Type 1) shadings, emitted into the
    /// same `/Resources/Shading` dict as `shadings` but kept in a separate map
    /// so the public `ShadingDefinition` enum stays unchanged (#407).
    advanced_shadings: HashMap<String, crate::graphics::AdvancedShading>,
    header: Option<HeaderFooter>,
    footer: Option<HeaderFooter>,
    annotations: Vec<Annotation>,
    coordinate_system: crate::coordinate_system::CoordinateSystem,
    rotation: i32, // Page rotation in degrees (0, 90, 180, 270)
    /// Next MCID (Marked Content ID) for tagged PDF
    next_mcid: u32,
    /// Currently open marked content tags (for nesting validation)
    marked_content_stack: Vec<String>,
    /// Preserved resources from original PDF (for overlay operations)
    /// Contains fonts, XObjects, ColorSpaces, etc. from parsed pages
    preserved_resources: Option<crate::pdf_objects::Dictionary>,
    /// Aggregated content-stream operators in caller-defined order
    /// (issue #227). Each call to [`Page::graphics`] or [`Page::text`]
    /// flushes the buffer of the *opposite* context here before
    /// returning the borrow, so PDF painter-model call order is
    /// preserved across context switches. The remaining tail in
    /// either context's own buffer is appended at flush time
    /// (`generate_content_with_page_info`).
    page_ops: Vec<crate::graphics::ops::Op>,
    /// Optional per-document font metrics store (issue #230 / v2.8.0).
    /// `None` on pages created via `Page::a4()` / `letter()` / `new()`.
    /// Populated by `Page::a4_with_metrics` and friends, or injected by
    /// `Document::add_page()` in Task 11.
    pub(crate) font_metrics_store: Option<FontMetricsStore>,
    /// Collision-only rename map for preserved fonts (issue #395), stamped by
    /// the writer just before content generation. Maps an original preserved
    /// `/Font` key to its disambiguated key when (and only when) that key
    /// collided with a writer-injected/overlay font. Empty for pages with no
    /// preserved fonts or no collisions — in which case the preserved content
    /// is emitted verbatim.
    pub(crate) preserved_font_rewrite_map: HashMap<String, String>,
}

impl Page {
    /// Creates a new page with the specified width and height in points.
    ///
    /// Points are 1/72 of an inch.
    pub fn new(width: f64, height: f64) -> Self {
        Self {
            width,
            height,
            margins: Margins::default(),
            content: Vec::new(),
            graphics_context: GraphicsContext::new(),
            text_context: TextContext::new(),
            images: HashMap::new(),
            form_xobjects: HashMap::new(),
            color_spaces: HashMap::new(),
            patterns: HashMap::new(),
            shadings: HashMap::new(),
            advanced_shadings: HashMap::new(),
            header: None,
            footer: None,
            annotations: Vec::new(),
            coordinate_system: crate::coordinate_system::CoordinateSystem::PdfStandard,
            rotation: 0, // Default to no rotation
            next_mcid: 0,
            marked_content_stack: Vec::new(),
            preserved_resources: None,
            page_ops: Vec::new(),
            font_metrics_store: None,
            preserved_font_rewrite_map: HashMap::new(),
        }
    }

    /// Creates a writable Page from a parsed page dictionary.
    ///
    /// This method bridges the gap between the parser (read-only) and writer (writable)
    /// by converting a parsed page into a Page structure that can be modified and saved.
    ///
    /// **IMPORTANT**: This method preserves the existing content stream and resources,
    /// allowing you to overlay new content on top of the existing page content without
    /// manual recreation.
    ///
    /// # Arguments
    ///
    /// * `parsed_page` - Reference to a parsed page from the PDF parser
    ///
    /// # Returns
    ///
    /// A writable `Page` with existing content preserved, ready for modification
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::{PdfReader, PdfDocument};
    /// use oxidize_pdf::Page;
    ///
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// // Load existing PDF
    /// let reader = PdfReader::open("input.pdf")?;
    /// let document = PdfDocument::new(reader);
    /// let parsed_page = document.get_page(0)?;
    ///
    /// // Convert to writable page
    /// let mut page = Page::from_parsed(&parsed_page)?;
    ///
    /// // Now you can add content on top of existing content
    /// page.text()
    ///     .set_font(oxidize_pdf::text::Font::Helvetica, 12.0)
    ///     .at(100.0, 100.0)
    ///     .write("Overlaid text")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn from_parsed(parsed_page: &crate::parser::page_tree::ParsedPage) -> Result<Self> {
        // Extract dimensions from MediaBox
        let media_box = parsed_page.media_box;
        let width = media_box[2] - media_box[0];
        let height = media_box[3] - media_box[1];

        // Extract rotation
        let rotation = parsed_page.rotation;

        // Create base page
        let mut page = Self::new(width, height);
        page.rotation = rotation;

        // TODO: Extract and preserve Resources (fonts, images, XObjects)
        // This requires deeper integration with the parser's resource manager

        // Extract and preserve existing content streams
        // Note: This requires a PdfDocument reference to resolve content streams
        // For now, we mark the content field to indicate it should be preserved
        // The actual content stream extraction will be done when we have access to the reader

        Ok(page)
    }

    /// Creates a writable Page from a parsed page with content stream preservation.
    ///
    /// This is an extended version of `from_parsed()` that requires access to the
    /// PdfDocument to extract and preserve the original content streams.
    ///
    /// # Arguments
    ///
    /// * `parsed_page` - Reference to a parsed page
    /// * `document` - Reference to the PDF document (for content stream resolution)
    ///
    /// # Returns
    ///
    /// A writable `Page` with original content streams preserved
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::parser::{PdfReader, PdfDocument};
    /// use oxidize_pdf::Page;
    ///
    /// # fn example() -> Result<(), Box<dyn std::error::Error>> {
    /// let reader = PdfReader::open("input.pdf")?;
    /// let document = PdfDocument::new(reader);
    /// let parsed_page = document.get_page(0)?;
    ///
    /// // Convert with content preservation
    /// let mut page = Page::from_parsed_with_content(&parsed_page, &document)?;
    ///
    /// // Original content is preserved, overlay will be added on top
    /// page.text()
    ///     .set_font(oxidize_pdf::text::Font::Helvetica, 12.0)
    ///     .at(100.0, 100.0)
    ///     .write("Overlay text")?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn from_parsed_with_content<R: std::io::Read + std::io::Seek>(
        parsed_page: &crate::parser::page_tree::ParsedPage,
        document: &crate::parser::document::PdfDocument<R>,
    ) -> Result<Self> {
        // Extract dimensions from MediaBox
        let media_box = parsed_page.media_box;
        let width = media_box[2] - media_box[0];
        let height = media_box[3] - media_box[1];

        // Extract rotation
        let rotation = parsed_page.rotation;

        // Create base page
        let mut page = Self::new(width, height);
        page.rotation = rotation;

        // Extract and preserve existing content streams
        let content_streams = parsed_page.content_streams_with_document(document)?;

        // Concatenate all content streams
        let mut preserved_content = Vec::new();
        for stream in content_streams {
            preserved_content.extend_from_slice(&stream);
            // Add a newline between streams for safety
            preserved_content.push(b'\n');
        }

        // Store the original content
        // We'll need to wrap it with q/Q to isolate it when overlaying
        page.content = preserved_content;

        // Extract and preserve Resources (fonts, images, XObjects, etc.)
        if let Some(resources) = parsed_page.get_resources() {
            let mut unified_resources = Self::convert_parser_dict_to_unified(resources);

            // Phase 3.2: Resolve embedded font streams
            // For each font in resources, resolve FontDescriptor and font stream references
            // and embed the stream data directly so writer doesn't need to resolve references
            // The `/Font` entry may itself be an indirect reference
            // (`/Font 1 0 R`) instead of an inline dictionary. Resolve it here
            // so the loop below sees the underlying font dictionary. The owned
            // resolved object is held in `resolved_font` to outlive the borrow:
            // returning `&convert(..)` directly fails on the MSRV (1.88) with
            // E0716, as the temporary is dropped at the end of the statement.
            let resolved_font: crate::pdf_objects::Object;
            let font_resource = match unified_resources.get("Font") {
                Some(crate::pdf_objects::Object::Reference(id)) => {
                    match document.get_object(id.number(), id.generation()) {
                        Ok(resolved_obj) => {
                            resolved_font = Self::convert_parser_object_to_unified(&resolved_obj);
                            Some(&resolved_font)
                        }
                        _ => None,
                    }
                }
                other => other,
            };

            if let Some(crate::pdf_objects::Object::Dictionary(fonts)) = font_resource {
                let fonts_clone = fonts.clone();
                let mut resolved_fonts = crate::pdf_objects::Dictionary::new();

                for (font_name, font_obj) in fonts_clone.iter() {
                    // Step 1: Resolve reference if needed to get actual font dictionary
                    let font_dict = match font_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            // Resolve reference to get actual font dictionary from document
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    // Convert parser object to unified format
                                    match Self::convert_parser_object_to_unified(&resolved_obj) {
                                        crate::pdf_objects::Object::Dictionary(dict) => dict,
                                        _ => {
                                            // Not a dictionary, keep original reference
                                            resolved_fonts.set(font_name.clone(), font_obj.clone());
                                            continue;
                                        }
                                    }
                                }
                                Err(_) => {
                                    // Resolution failed, keep original reference
                                    resolved_fonts.set(font_name.clone(), font_obj.clone());
                                    continue;
                                }
                            }
                        }
                        crate::pdf_objects::Object::Dictionary(dict) => dict.clone(),
                        _ => {
                            // Neither reference nor dictionary, keep as-is
                            resolved_fonts.set(font_name.clone(), font_obj.clone());
                            continue;
                        }
                    };

                    // Step 2: Now font_dict is guaranteed to be a Dictionary, resolve embedded streams
                    match Self::resolve_font_streams(&font_dict, document) {
                        Ok(resolved_dict) => {
                            resolved_fonts.set(
                                font_name.clone(),
                                crate::pdf_objects::Object::Dictionary(resolved_dict),
                            );
                        }
                        Err(_) => {
                            // If stream resolution fails, keep the resolved dictionary without streams
                            resolved_fonts.set(
                                font_name.clone(),
                                crate::pdf_objects::Object::Dictionary(font_dict),
                            );
                        }
                    }
                }

                // Replace Font dictionary with resolved version
                unified_resources.set(
                    "Font",
                    crate::pdf_objects::Object::Dictionary(resolved_fonts),
                );
            }

            // Phase 3.5: Resolve XObject streams (images, forms)
            // XObjects are critical for PDF content - unresolved references cause blank PDFs
            if let Some(crate::pdf_objects::Object::Dictionary(xobjects)) =
                unified_resources.get("XObject")
            {
                let xobjects_clone = xobjects.clone();
                let mut resolved_xobjects = crate::pdf_objects::Dictionary::new();

                for (xobj_name, xobj_obj) in xobjects_clone.iter() {
                    let resolved = match xobj_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            // Resolve reference to get actual XObject stream
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    Self::convert_parser_object_to_unified(&resolved_obj)
                                }
                                Err(_) => {
                                    // Resolution failed, keep reference
                                    xobj_obj.clone()
                                }
                            }
                        }
                        _ => xobj_obj.clone(),
                    };
                    resolved_xobjects.set(xobj_name.clone(), resolved);
                }

                unified_resources.set(
                    "XObject",
                    crate::pdf_objects::Object::Dictionary(resolved_xobjects),
                );
            }

            // Phase 3.5: Resolve ExtGState (graphics state parameters)
            if let Some(crate::pdf_objects::Object::Dictionary(extgstates)) =
                unified_resources.get("ExtGState")
            {
                let extgstates_clone = extgstates.clone();
                let mut resolved_extgstates = crate::pdf_objects::Dictionary::new();

                for (gs_name, gs_obj) in extgstates_clone.iter() {
                    let resolved = match gs_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    Self::convert_parser_object_to_unified(&resolved_obj)
                                }
                                Err(_) => gs_obj.clone(),
                            }
                        }
                        _ => gs_obj.clone(),
                    };
                    resolved_extgstates.set(gs_name.clone(), resolved);
                }

                unified_resources.set(
                    "ExtGState",
                    crate::pdf_objects::Object::Dictionary(resolved_extgstates),
                );
            }

            // Phase 3.5: Resolve ColorSpace references
            if let Some(crate::pdf_objects::Object::Dictionary(colorspaces)) =
                unified_resources.get("ColorSpace")
            {
                let colorspaces_clone = colorspaces.clone();
                let mut resolved_colorspaces = crate::pdf_objects::Dictionary::new();

                for (cs_name, cs_obj) in colorspaces_clone.iter() {
                    let resolved = match cs_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    Self::convert_parser_object_to_unified(&resolved_obj)
                                }
                                Err(_) => cs_obj.clone(),
                            }
                        }
                        _ => cs_obj.clone(),
                    };
                    resolved_colorspaces.set(cs_name.clone(), resolved);
                }

                unified_resources.set(
                    "ColorSpace",
                    crate::pdf_objects::Object::Dictionary(resolved_colorspaces),
                );
            }

            // Phase 3.5: Resolve Pattern references
            if let Some(crate::pdf_objects::Object::Dictionary(patterns)) =
                unified_resources.get("Pattern")
            {
                let patterns_clone = patterns.clone();
                let mut resolved_patterns = crate::pdf_objects::Dictionary::new();

                for (pat_name, pat_obj) in patterns_clone.iter() {
                    let resolved = match pat_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    Self::convert_parser_object_to_unified(&resolved_obj)
                                }
                                Err(_) => pat_obj.clone(),
                            }
                        }
                        _ => pat_obj.clone(),
                    };
                    resolved_patterns.set(pat_name.clone(), resolved);
                }

                unified_resources.set(
                    "Pattern",
                    crate::pdf_objects::Object::Dictionary(resolved_patterns),
                );
            }

            // Phase 3.5: Resolve Shading references
            if let Some(crate::pdf_objects::Object::Dictionary(shadings)) =
                unified_resources.get("Shading")
            {
                let shadings_clone = shadings.clone();
                let mut resolved_shadings = crate::pdf_objects::Dictionary::new();

                for (sh_name, sh_obj) in shadings_clone.iter() {
                    let resolved = match sh_obj {
                        crate::pdf_objects::Object::Reference(id) => {
                            match document.get_object(id.number(), id.generation()) {
                                Ok(resolved_obj) => {
                                    Self::convert_parser_object_to_unified(&resolved_obj)
                                }
                                Err(_) => sh_obj.clone(),
                            }
                        }
                        _ => sh_obj.clone(),
                    };
                    resolved_shadings.set(sh_name.clone(), resolved);
                }

                unified_resources.set(
                    "Shading",
                    crate::pdf_objects::Object::Dictionary(resolved_shadings),
                );
            }

            page.preserved_resources = Some(unified_resources);
        }

        Ok(page)
    }

    /// Creates a new A4 page (595 x 842 points).
    pub fn a4() -> Self {
        Self::new(595.0, 842.0)
    }

    /// Creates a new A4 landscape page (842 x 595 points).
    pub fn a4_landscape() -> Self {
        Self::new(842.0, 595.0)
    }

    /// Creates a new US Letter page (612 x 792 points).
    pub fn letter() -> Self {
        Self::new(612.0, 792.0)
    }

    /// Creates a new US Letter landscape page (792 x 612 points).
    pub fn letter_landscape() -> Self {
        Self::new(792.0, 612.0)
    }

    /// Returns the `FontMetricsStore` bound to this page, if any (issue #230).
    ///
    /// Pages constructed via `Document::new_page_*()` carry the Document's
    /// store; pages constructed via `Page::a4()` / `Page::letter()` /
    /// `Page::new()` are bound at `Document::add_page` time. Returns `None`
    /// for pages that have not yet been attached to a Document.
    pub fn font_metrics_store(&self) -> Option<&FontMetricsStore> {
        self.font_metrics_store.as_ref()
    }

    /// Returns the `FontMetricsStore` bound to this page's `text_context`,
    /// if any. Exposed for integration tests verifying that
    /// `Document::add_page` injects the per-Document store into the
    /// text context as well as into the page itself (issue #230 follow-up).
    ///
    /// Gated behind the `internal-testing` feature so it does not enter the
    /// production ABI. Lib unit tests get it via `cfg(test)`.
    #[cfg(any(test, feature = "internal-testing"))]
    #[doc(hidden)]
    pub fn text_context_metrics_store_for_test(
        &self,
    ) -> Option<&crate::text::metrics::FontMetricsStore> {
        self.text_context.font_metrics_store.as_ref()
    }

    /// Returns the number of operations accumulated in the page's
    /// `text_context`. Exposed for integration tests verifying that
    /// `Document::add_page` does not erase ops while injecting the
    /// per-Document `FontMetricsStore` (issue #230 follow-up).
    ///
    /// Gated behind the `internal-testing` feature so it does not enter the
    /// production ABI. Lib unit tests get it via `cfg(test)`.
    #[cfg(any(test, feature = "internal-testing"))]
    #[doc(hidden)]
    pub fn text_context_ops_count_for_test(&self) -> usize {
        self.text_context.ops_slice().len()
    }

    /// Injects or replaces the `FontMetricsStore` on this page's text
    /// context. Called by `Document::add_page` to wire the Document scope
    /// into pages constructed via `Page::a4() / Page::letter() / Page::new()`
    /// (issue #230 follow-up). Accumulated ops are preserved.
    pub(crate) fn set_text_context_metrics_store(
        &mut self,
        store: Option<crate::text::metrics::FontMetricsStore>,
    ) {
        self.text_context.set_metrics_store(store);
    }

    /// Creates a new A4 page pre-loaded with a `FontMetricsStore` (issue #230).
    ///
    /// `Page::a4()` has `font_metrics_store: None`; this variant is used by
    /// `Document::new_page_a4()` to bind the document-level store.
    pub(crate) fn a4_with_metrics(store: FontMetricsStore) -> Self {
        let mut p = Self::a4();
        p.font_metrics_store = Some(store.clone());
        p.text_context = TextContext::with_metrics_store(Some(store));
        p
    }

    /// Creates a new US Letter page pre-loaded with a `FontMetricsStore` (issue #230).
    pub(crate) fn letter_with_metrics(store: FontMetricsStore) -> Self {
        let mut p = Self::letter();
        p.font_metrics_store = Some(store.clone());
        p.text_context = TextContext::with_metrics_store(Some(store));
        p
    }

    /// Creates a new page of custom size pre-loaded with a `FontMetricsStore` (issue #230).
    pub(crate) fn new_with_metrics(width: f64, height: f64, store: FontMetricsStore) -> Self {
        let mut p = Self::new(width, height);
        p.font_metrics_store = Some(store.clone());
        p.text_context = TextContext::with_metrics_store(Some(store));
        p
    }

    /// Creates a new US Legal page (612 x 1008 points).
    pub fn legal() -> Self {
        Self::new(612.0, 1008.0)
    }

    /// Creates a new US Legal landscape page (1008 x 612 points).
    pub fn legal_landscape() -> Self {
        Self::new(1008.0, 612.0)
    }

    /// Returns a mutable reference to the graphics context for drawing shapes.
    ///
    /// As of v2.7.0, this also flushes any pending text-context operations
    /// into the page-level ordered buffer (`page_ops`) so that subsequent
    /// graphics calls are emitted *after* the text that preceded them in
    /// call order — preserving the PDF painter model across context
    /// switches (issue #227).
    pub fn graphics(&mut self) -> &mut GraphicsContext {
        if !self.text_context.ops_slice().is_empty() {
            let drained = self.text_context.drain_ops();
            self.page_ops.extend(drained);
        }
        &mut self.graphics_context
    }

    /// Returns the accumulated content-stream operators for this page.
    ///
    /// Read-only counterpart to [`Page::graphics`]. The returned string is
    /// the union of:
    /// - operators already flushed to the page-level ordered buffer
    ///   (`page_ops`) — i.e. graphics ops drawn before any
    ///   `Page::text()` / `Page::add_text_flow()` switch — and
    /// - operators still pending in the active `GraphicsContext` tail.
    ///
    /// Pre-2.7.0 this returned only the tail; the union is the correct
    /// answer for callers inspecting "what has been drawn so far"
    /// because the tail alone is incomplete after the first context
    /// switch (review finding).
    pub fn graphics_operations(&self) -> String {
        let mut buf = Vec::new();
        crate::graphics::ops::serialize_ops(&mut buf, &self.page_ops);
        let tail = self.graphics_context.operations();
        let mut out =
            String::from_utf8(buf).expect("serialize_ops emits ASCII content-stream tokens");
        out.push_str(&tail);
        out
    }

    /// Returns a mutable reference to the text context for adding text.
    ///
    /// As of v2.7.0, this also flushes any pending graphics-context
    /// operations into the page-level ordered buffer (`page_ops`) so
    /// that subsequent text calls are emitted *after* the graphics that
    /// preceded them in call order (issue #227).
    ///
    /// As of issue #239, this also propagates the current graphics-state
    /// non-stroking colour into the text context when the caller has not
    /// set an explicit text fill colour. Per ISO 32000-1 §8.6.8, `rg` is
    /// a graphics-state operator that applies both to path fills and to
    /// glyph fills at text rendering mode 0 (default). Splitting the
    /// fill-colour slot between `GraphicsContext` and `TextContext`
    /// without this handoff produced a stream where the text was painted
    /// in whatever colour the previous path fill left active, never the
    /// colour the caller intended for the text. An explicit
    /// `text().set_fill_color(...)` still overrides the inherited value.
    ///
    /// **Side effect on the returned `TextContext`:** when the handoff
    /// fires, this call mutates `text_context.fill_color` from `None`
    /// to `Some(<graphics-state colour>)` BEFORE returning the
    /// reference. Code that probes `fill_color()` as a signal of
    /// "user has set a colour" will see `Some(...)` even when the user
    /// never called `set_fill_color`, because the graphics state is now
    /// considered the source of truth for the non-stroking colour.
    /// After `clear()`, the next `text()` call will repeat the handoff.
    pub fn text(&mut self) -> &mut TextContext {
        if !self.graphics_context.ops_slice().is_empty() {
            let drained = self.graphics_context.drain_ops();
            self.page_ops.extend(drained);
        }
        if self.text_context.fill_color().is_none() {
            let inherited = self.graphics_context.fill_color();
            self.text_context.set_fill_color(inherited);
        }
        &mut self.text_context
    }

    pub fn set_margins(&mut self, left: f64, right: f64, top: f64, bottom: f64) {
        self.margins = Margins {
            left,
            right,
            top,
            bottom,
        };
    }

    pub fn margins(&self) -> &Margins {
        &self.margins
    }

    pub fn content_width(&self) -> f64 {
        self.width - self.margins.left - self.margins.right
    }

    pub fn content_height(&self) -> f64 {
        self.height - self.margins.top - self.margins.bottom
    }

    pub fn content_area(&self) -> (f64, f64, f64, f64) {
        (
            self.margins.left,
            self.margins.bottom,
            self.width - self.margins.right,
            self.height - self.margins.top,
        )
    }

    pub fn width(&self) -> f64 {
        self.width
    }

    pub fn height(&self) -> f64 {
        self.height
    }

    /// Get the current coordinate system for this page
    pub fn coordinate_system(&self) -> crate::coordinate_system::CoordinateSystem {
        self.coordinate_system
    }

    /// Set the coordinate system for this page
    pub fn set_coordinate_system(
        &mut self,
        coordinate_system: crate::coordinate_system::CoordinateSystem,
    ) -> &mut Self {
        self.coordinate_system = coordinate_system;
        self
    }

    /// Sets the page rotation in degrees.
    /// Valid values are 0, 90, 180, and 270.
    /// Other values will be normalized to the nearest valid rotation.
    pub fn set_rotation(&mut self, rotation: i32) {
        // Normalize rotation to valid values (0, 90, 180, 270)
        let normalized = rotation.rem_euclid(360); // Ensure positive
        self.rotation = match normalized {
            0..=44 | 316..=360 => 0,
            45..=134 => 90,
            135..=224 => 180,
            225..=315 => 270,
            _ => 0, // Should not happen, but default to 0
        };
    }

    /// Converts a parser Dictionary to unified pdf_objects Dictionary
    fn convert_parser_dict_to_unified(
        parser_dict: &crate::parser::objects::PdfDictionary,
    ) -> crate::pdf_objects::Dictionary {
        use crate::pdf_objects::{Dictionary, Name};

        let mut unified_dict = Dictionary::new();

        for (key, value) in &parser_dict.0 {
            let unified_key = Name::new(key.as_str());
            let unified_value = Self::convert_parser_object_to_unified(value);
            unified_dict.set(unified_key, unified_value);
        }

        unified_dict
    }

    /// Converts a parser PdfObject to unified Object
    fn convert_parser_object_to_unified(
        parser_obj: &crate::parser::objects::PdfObject,
    ) -> crate::pdf_objects::Object {
        use crate::parser::objects::PdfObject;
        use crate::pdf_objects::{Array, BinaryString, Name, Object, ObjectId, Stream};

        match parser_obj {
            PdfObject::Null => Object::Null,
            PdfObject::Boolean(b) => Object::Boolean(*b),
            PdfObject::Integer(i) => Object::Integer(*i),
            PdfObject::Real(f) => Object::Real(*f),
            PdfObject::String(s) => Object::String(BinaryString::new(s.as_bytes().to_vec())),
            PdfObject::Name(n) => Object::Name(Name::new(n.as_str())),
            PdfObject::Array(arr) => {
                let mut unified_arr = Array::new();
                for item in &arr.0 {
                    unified_arr.push(Self::convert_parser_object_to_unified(item));
                }
                Object::Array(unified_arr)
            }
            PdfObject::Dictionary(dict) => {
                Object::Dictionary(Self::convert_parser_dict_to_unified(dict))
            }
            PdfObject::Stream(stream) => {
                let dict = Self::convert_parser_dict_to_unified(&stream.dict);
                let data = stream.data.clone();
                Object::Stream(Stream::new(dict, data))
            }
            PdfObject::Reference(num, gen) => Object::Reference(ObjectId::new(*num, *gen)),
        }
    }

    /// Resolves embedded font streams from a font dictionary (Phase 3.2 + Phase 3.4)
    ///
    /// Takes a font dictionary and resolves any FontDescriptor + FontFile references,
    /// embedding the stream data directly so the writer doesn't need to resolve references.
    ///
    /// For Type0 (composite) fonts, this also resolves the complete hierarchy:
    /// Type0 → DescendantFonts → CIDFont → FontDescriptor → FontFile2/FontFile3
    ///
    /// # Returns
    /// Font dictionary with embedded streams (if font has embedded data),
    /// or original dictionary (if standard font or resolution fails)
    fn resolve_font_streams<R: std::io::Read + std::io::Seek>(
        font_dict: &crate::pdf_objects::Dictionary,
        document: &crate::parser::document::PdfDocument<R>,
    ) -> Result<crate::pdf_objects::Dictionary> {
        use crate::pdf_objects::Object;

        let mut resolved_dict = font_dict.clone();

        // Phase 3.4: Check if this is a Type0 (composite) font
        if detect_type0_font(font_dict) {
            // Create a resolver closure that converts parser objects to unified format
            let resolver =
                |id: crate::pdf_objects::ObjectId| -> Option<crate::pdf_objects::Object> {
                    match document.get_object(id.number(), id.generation()) {
                        Ok(parser_obj) => Some(Self::convert_parser_object_to_unified(&parser_obj)),
                        Err(_) => None,
                    }
                };

            // Resolve the complete Type0 hierarchy
            if let Some(info) = resolve_type0_hierarchy(font_dict, resolver) {
                // Embed the resolved CIDFont as DescendantFonts
                if let Some(cidfont) = info.cidfont_dict {
                    let mut resolved_cidfont = cidfont;

                    // Embed FontDescriptor with resolved font stream
                    if let Some(descriptor) = info.font_descriptor {
                        let mut resolved_descriptor = descriptor;

                        // Embed the font stream directly in FontDescriptor
                        if let Some(stream) = info.font_stream {
                            // Determine which key to use based on font_file_type
                            let key = match info.font_file_type {
                                Some(crate::fonts::type0_parsing::FontFileType::TrueType) => {
                                    "FontFile2"
                                }
                                Some(crate::fonts::type0_parsing::FontFileType::CFF) => "FontFile3",
                                Some(crate::fonts::type0_parsing::FontFileType::Type1) => {
                                    "FontFile"
                                }
                                None => "FontFile2", // Default for CIDFontType2
                            };
                            resolved_descriptor.set(key, Object::Stream(stream));
                        }

                        resolved_cidfont
                            .set("FontDescriptor", Object::Dictionary(resolved_descriptor));
                    }

                    // Replace DescendantFonts array with resolved CIDFont
                    let mut descendants = crate::pdf_objects::Array::new();
                    descendants.push(Object::Dictionary(resolved_cidfont));
                    resolved_dict.set("DescendantFonts", Object::Array(descendants));
                }

                // Embed ToUnicode stream if present
                if let Some(tounicode) = info.tounicode_stream {
                    resolved_dict.set("ToUnicode", Object::Stream(tounicode));
                }
            }

            return Ok(resolved_dict);
        }

        // Original Phase 3.2 logic for simple fonts (Type1, TrueType, etc.)
        // Check if font has a FontDescriptor
        if let Some(Object::Reference(descriptor_id)) = font_dict.get("FontDescriptor") {
            // Resolve FontDescriptor from document
            let descriptor_obj =
                document.get_object(descriptor_id.number(), descriptor_id.generation())?;

            // Convert to unified format
            let descriptor_unified = Self::convert_parser_object_to_unified(&descriptor_obj);

            if let Object::Dictionary(mut descriptor_dict) = descriptor_unified {
                // Check for embedded font streams (FontFile, FontFile2, FontFile3)
                let font_file_keys = ["FontFile", "FontFile2", "FontFile3"];
                let mut stream_resolved = false;

                for key in &font_file_keys {
                    if let Some(Object::Reference(stream_id)) = descriptor_dict.get(*key) {
                        // Resolve font stream from document
                        match document.get_object(stream_id.number(), stream_id.generation()) {
                            Ok(stream_obj) => {
                                // Convert to unified format (includes stream data)
                                let stream_unified =
                                    Self::convert_parser_object_to_unified(&stream_obj);

                                // Replace reference with actual stream object
                                descriptor_dict.set(*key, stream_unified);
                                stream_resolved = true;
                            }
                            Err(_) => {
                                // Resolution failed, keep reference as-is
                                continue;
                            }
                        }
                    }
                }

                // If we resolved any streams, update FontDescriptor in font dictionary
                if stream_resolved {
                    resolved_dict.set("FontDescriptor", Object::Dictionary(descriptor_dict));
                }
            }
        }

        Ok(resolved_dict)
    }

    /// Gets the preserved resources from the original PDF (if any)
    pub fn get_preserved_resources(&self) -> Option<&crate::pdf_objects::Dictionary> {
        self.preserved_resources.as_ref()
    }

    /// Gets the current page rotation in degrees.
    pub fn get_rotation(&self) -> i32 {
        self.rotation
    }

    /// Gets the effective width considering rotation.
    /// For 90° and 270° rotations, returns the height.
    pub fn effective_width(&self) -> f64 {
        match self.rotation {
            90 | 270 => self.height,
            _ => self.width,
        }
    }

    /// Gets the effective height considering rotation.
    /// For 90° and 270° rotations, returns the width.
    pub fn effective_height(&self) -> f64 {
        match self.rotation {
            90 | 270 => self.width,
            _ => self.height,
        }
    }

    pub fn text_flow(&self) -> TextFlowContext {
        // Issue #216: inherit the page-level text state (font, size, and
        // fill colour) so callers that rely on `set_font` / `set_text_color`
        // before invoking flow helpers (notably `text_flow_at` in the Python
        // and .NET wrappers) get the formatting they configured.
        //
        // Issue #222 (Phase 6 of the v2.7.0 IR refactor): the remaining
        // seven text-state parameters (character spacing, word spacing,
        // horizontal scaling, leading, text rise, rendering mode, stroke
        // colour) are now propagated as well. An explicit setter call on
        // the returned `TextFlowContext` still overrides the inherited
        // value, so this is a strict superset of the previous behaviour.
        let mut ctx = TextFlowContext::with_metrics_store(
            self.width,
            self.height,
            self.margins.clone(),
            self.font_metrics_store.clone(),
        );
        ctx.set_font(
            self.text_context.current_font().clone(),
            self.text_context.font_size(),
        );
        // Issue #239: when no explicit text fill colour was set, fall
        // back to the graphics-state non-stroking colour so the flow
        // honours `graphics().set_fill_color(...)` per ISO 32000-1
        // §8.6.8. Symmetric with the handoff in `Page::text()`.
        let effective_fill = self
            .text_context
            .fill_color()
            .unwrap_or_else(|| self.graphics_context.fill_color());
        ctx.set_fill_color(effective_fill);
        if let Some(spacing) = self.text_context.character_spacing() {
            ctx.set_character_spacing(spacing);
        }
        if let Some(spacing) = self.text_context.word_spacing() {
            ctx.set_word_spacing(spacing);
        }
        if let Some(scale) = self.text_context.horizontal_scaling() {
            ctx.set_horizontal_scaling(scale);
        }
        if let Some(leading) = self.text_context.leading() {
            ctx.set_leading(leading);
        }
        if let Some(rise) = self.text_context.text_rise() {
            ctx.set_text_rise(rise);
        }
        if let Some(mode) = self.text_context.rendering_mode() {
            ctx.set_rendering_mode(mode as u8);
        }
        if let Some(color) = self.text_context.stroke_color() {
            ctx.set_stroke_color(color);
        }
        ctx
    }

    pub fn add_text_flow(&mut self, text_flow: &TextFlowContext) {
        // Route the flow's serialised content into the page-level
        // ordered buffer so its position respects PDF painter-model
        // call order across `Page::graphics()` / `Page::text()` /
        // `Page::add_text_flow()` interleaving (issue #227, residual
        // gap surfaced by the v2.7.0 review). Drain both context tails
        // first so the page_ops timeline stays monotonic by call.
        self.flush_pending_contexts();
        let operations = text_flow.generate_operations();
        if !operations.is_empty() {
            self.page_ops
                .push(crate::graphics::ops::Op::Raw(operations));
        }
        // Absorb the text flow's per-font character tracking into the
        // page's graphics-context accumulator so the writer can subset
        // each custom font referenced by the flow (issue #204). Pre-fix
        // this merge did not happen, so a `TextFlowContext` with a
        // `Font::Custom` produced a content stream that referenced a
        // font whose subset was driven by whatever other page drew
        // with the global `used_characters` — and after the fix, the
        // unused-font skip would remove the font entirely.
        self.graphics_context
            .merge_font_usage(text_flow.get_used_characters_by_font());
    }

    /// Drain whatever ops are currently buffered in the per-context
    /// `operations` vectors into `page_ops`, preserving call order.
    /// Used by APIs that emit content directly to `page_ops`
    /// (`add_text_flow`, `append_raw_content`) so the timeline does
    /// not skip over pending tails.
    fn flush_pending_contexts(&mut self) {
        if !self.graphics_context.ops_slice().is_empty() {
            let drained = self.graphics_context.drain_ops();
            self.page_ops.extend(drained);
        }
        if !self.text_context.ops_slice().is_empty() {
            let drained = self.text_context.drain_ops();
            self.page_ops.extend(drained);
        }
    }

    pub fn add_image(&mut self, name: impl Into<String>, image: Image) {
        self.images.insert(name.into(), image);
    }

    pub fn draw_image(
        &mut self,
        name: &str,
        x: f64,
        y: f64,
        width: f64,
        height: f64,
    ) -> Result<()> {
        if self.images.contains_key(name) {
            // Draw the image using the graphics context
            self.graphics_context.draw_image(name, x, y, width, height);
            Ok(())
        } else {
            Err(crate::PdfError::InvalidReference(format!(
                "Image '{name}' not found"
            )))
        }
    }

    pub(crate) fn images(&self) -> &HashMap<String, Image> {
        &self.images
    }

    /// Adds a Form XObject resource to this page (public as of v2.5.6).
    ///
    /// `name` is the key under which the Form XObject is exposed in the
    /// page's `/Resources/XObject` dictionary — typically `F1`, `Fm0`, etc.
    /// Use this when embedding reusable graphical content, overlays, stamps
    /// or template page fragments composed with the `FormXObject` /
    /// `FormXObjectBuilder` APIs.
    ///
    /// Duplicate names overwrite silently (the same behaviour as inserting
    /// into the underlying map); if you need idempotent registration,
    /// inspect [`Page::form_xobjects`] before calling.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is empty or
    /// contains any character forbidden by ISO 32000-1 §7.3.5 (delimiter
    /// characters `( ) < > [ ] { } / %`, whitespace, or the `#` escape
    /// introducer). Emitting such a name verbatim would close the
    /// resource dict early and allow dict-level injection.
    ///
    /// ```rust
    /// use oxidize_pdf::geometry::Rectangle;
    /// use oxidize_pdf::graphics::FormXObject;
    /// use oxidize_pdf::Page;
    ///
    /// let mut page = Page::a4();
    /// let bbox = Rectangle::from_position_and_size(0.0, 0.0, 100.0, 100.0);
    /// page.add_form_xobject("F1", FormXObject::new(bbox)).unwrap();
    /// assert!(page.form_xobjects().contains_key("F1"));
    /// ```
    pub fn add_form_xobject(
        &mut self,
        name: impl Into<String>,
        form: crate::graphics::FormXObject,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        self.form_xobjects.insert(name, form);
        Ok(())
    }

    /// Returns all Form XObjects registered on this page (public as of v2.5.6).
    ///
    /// Keys correspond to `/Resources/XObject` entries emitted by the
    /// writer. The returned map is read-only; to mutate, use
    /// [`Page::add_form_xobject`].
    pub fn form_xobjects(&self) -> &HashMap<String, crate::graphics::FormXObject> {
        &self.form_xobjects
    }

    /// Registers a colour space under `name` (ISO 32000-1 §8.6).
    ///
    /// `cs` is a typed [`crate::graphics::PageColorSpace`] — either a
    /// [`PageColorSpace::DeviceAlias`] wrapping one of the four device
    /// spaces (`/DeviceGray`, `/DeviceRGB`, `/DeviceCMYK`, `/Pattern`),
    /// or a [`PageColorSpace::Parameterised`] entry producing
    /// `[/<family> <<params>>]` for the calibrated families (`CalGray`,
    /// `CalRGB`, `Lab`, `ICCBased`). Indexed / Separation / DeviceN
    /// shapes are out of scope for this wrapper at v2.5.6; see the
    /// [`page_color_space`] module docs for the rationale.
    ///
    /// The writer emits the value under `/Resources/ColorSpace/<name>`,
    /// converting the enum to its concrete wire format at serialization
    /// time.
    ///
    /// [`page_color_space`]: crate::graphics::page_color_space
    /// [`PageColorSpace::DeviceAlias`]: crate::graphics::PageColorSpace::DeviceAlias
    /// [`PageColorSpace::Parameterised`]: crate::graphics::PageColorSpace::Parameterised
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid
    /// PDF resource name per ISO 32000-1 §7.3.5 (see
    /// [`Page::add_form_xobject`] for the full rule).
    pub fn add_color_space(
        &mut self,
        name: impl Into<String>,
        cs: crate::graphics::PageColorSpace,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        self.color_spaces.insert(name, cs);
        Ok(())
    }

    /// Register an ICC-profile-backed colour space under `name`, embedding the
    /// profile bytes so the writer emits a conformant `/ICCBased` **stream**
    /// `[/ICCBased <ref>]` (ISO 32000-1 §8.6.5.5).
    ///
    /// This is the ergonomic entry point for ICC colour: it bridges an
    /// [`IccProfile`](crate::graphics::IccProfile) into the stream-backed
    /// [`PageColorSpace::IccStream`](crate::graphics::PageColorSpace) variant.
    /// Unlike registering `PageColorSpace::Parameterised` with the `IccBased`
    /// family — which can only express an inline dictionary and drops the
    /// profile data — this path preserves the profile in the output.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid PDF
    /// resource name per ISO 32000-1 §7.3.5.
    pub fn add_icc_color_space(
        &mut self,
        name: impl Into<String>,
        profile: &crate::graphics::IccProfile,
    ) -> Result<()> {
        self.add_color_space(name, crate::graphics::PageColorSpace::from(profile))
    }

    /// Returns all colour spaces registered on this page.
    ///
    /// Map values are typed as [`crate::graphics::PageColorSpace`]; the
    /// writer converts to the concrete PDF `Object` shape at emit time.
    pub fn color_spaces(&self) -> &HashMap<String, crate::graphics::PageColorSpace> {
        &self.color_spaces
    }

    /// Registers a tiling pattern under `name` (ISO 32000-1 §8.7.3).
    ///
    /// The writer emits each pattern as an indirect stream object (patterns
    /// are streams per §7.3.8.1) and references it from
    /// `/Resources/Pattern/<name>`. Inside the content stream, paint the
    /// pattern with `/<name> scn` / `/<name> SCN` after selecting the
    /// /Pattern colour space.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid
    /// PDF resource name per ISO 32000-1 §7.3.5.
    pub fn add_pattern(
        &mut self,
        name: impl Into<String>,
        pattern: crate::graphics::TilingPattern,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        self.patterns.insert(name, pattern);
        Ok(())
    }

    /// Returns all tiling patterns registered on this page.
    pub fn patterns(&self) -> &HashMap<String, crate::graphics::TilingPattern> {
        &self.patterns
    }

    /// Registers a shading under `name` (ISO 32000-1 §8.7.4).
    ///
    /// The writer emits the shading as an indirect dictionary object and
    /// references it from `/Resources/Shading/<name>`. Paint with the
    /// `sh` operator (`/<name> sh`) or via a type-2 Pattern.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid
    /// PDF resource name per ISO 32000-1 §7.3.5.
    pub fn add_shading(
        &mut self,
        name: impl Into<String>,
        shading: crate::graphics::ShadingDefinition,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        self.shadings.insert(name, shading);
        Ok(())
    }

    /// Returns all shadings registered on this page.
    pub fn shadings(&self) -> &HashMap<String, crate::graphics::ShadingDefinition> {
        &self.shadings
    }

    /// Register a Type 4 free-form Gouraud mesh shading (#407), referenced
    /// from `/Resources/Shading/<name>` and painted with `/<name> sh`. The
    /// mesh is emitted as a stream object.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid PDF
    /// resource name (ISO 32000-1 §7.3.5) or the mesh fails validation.
    pub fn add_mesh_shading(
        &mut self,
        name: impl Into<String>,
        shading: crate::graphics::FreeFormGouraudShading,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        shading.validate()?;
        self.advanced_shadings
            .insert(name, crate::graphics::AdvancedShading::Mesh(shading));
        Ok(())
    }

    /// Register an exact conic (angular) gradient as a Type 1 function-based
    /// shading (#407), referenced from `/Resources/Shading/<name>`.
    ///
    /// # Errors
    ///
    /// Returns [`PdfError::InvalidStructure`] if `name` is not a valid PDF
    /// resource name (ISO 32000-1 §7.3.5) or the shading fails validation.
    pub fn add_conic_shading(
        &mut self,
        name: impl Into<String>,
        shading: crate::graphics::ConicShading,
    ) -> Result<()> {
        let name = name.into();
        validate_pdf_resource_name(&name)?;
        shading.validate()?;
        self.advanced_shadings
            .insert(name, crate::graphics::AdvancedShading::Conic(shading));
        Ok(())
    }

    /// Returns the mesh/conic shadings registered on this page (crate-internal;
    /// consumed by the writer).
    pub(crate) fn advanced_shadings(&self) -> &HashMap<String, crate::graphics::AdvancedShading> {
        &self.advanced_shadings
    }

    /// Append raw PDF operators to the content stream and record which
    /// fonts each character was drawn with (issue #204).
    ///
    /// `font_usage` MUST account for every `Tj`/`TJ` emitted inside
    /// `data` — the caller is the only actor that has ground truth
    /// about which font was active when the operator was generated.
    /// Pre-fix this method took just `data`; the resulting silent
    /// failure mode (unused fonts being subsetted with someone else's
    /// characters, or — post-fix — missing entirely from the emitted
    /// PDF because no per-font bucket existed) is exactly what the
    /// type-gate here prevents. Future content builders must return
    /// their usage map alongside their bytes.
    ///
    /// Content appended here renders AFTER the existing page content
    /// (on top).
    pub(crate) fn append_raw_content(
        &mut self,
        data: &[u8],
        font_usage: &HashMap<String, HashSet<char>>,
    ) {
        // Mirror of `add_text_flow`: route through `page_ops` so this
        // content respects painter-model call order against
        // `graphics()` / `text()` / `add_text_flow()` calls
        // (issue #227 residual). Drain pending tails first.
        self.flush_pending_contexts();
        if !data.is_empty() {
            self.page_ops
                .push(crate::graphics::ops::Op::Raw(data.to_vec()));
        }
        self.graphics_context.merge_font_usage(font_usage);
    }

    /// Add a table to the page.
    ///
    /// This method renders a table at the specified position using the current
    /// graphics context. The table will be drawn with borders, text, and any
    /// configured styling options.
    ///
    /// # Arguments
    ///
    /// * `table` - The table to render on the page
    ///
    /// # Example
    ///
    /// ```rust
    /// use oxidize_pdf::{Page, text::{Table, TableOptions}};
    ///
    /// let mut page = Page::a4();
    ///
    /// // Create a table with 3 columns
    /// let mut table = Table::new(vec![100.0, 150.0, 100.0]);
    /// table.set_position(50.0, 700.0);
    ///
    /// // Add header row
    /// table.add_header_row(vec![
    ///     "Name".to_string(),
    ///     "Description".to_string(),
    ///     "Price".to_string()
    /// ])?;
    ///
    /// // Add data rows
    /// table.add_row(vec![
    ///     "Item 1".to_string(),
    ///     "First item description".to_string(),
    ///     "$10.00".to_string()
    /// ])?;
    ///
    /// // Render the table on the page
    /// page.add_table(&table)?;
    /// # Ok::<(), oxidize_pdf::PdfError>(())
    /// ```
    pub fn add_table(&mut self, table: &Table) -> Result<()> {
        self.graphics_context.render_table(table)
    }

    /// Get ExtGState resources from the graphics context
    pub fn get_extgstate_resources(
        &self,
    ) -> Option<&std::collections::HashMap<String, crate::graphics::ExtGState>> {
        if self.graphics_context.has_extgstates() {
            Some(self.graphics_context.extgstate_manager().states())
        } else {
            None
        }
    }

    /// Adds an annotation to this page
    pub fn add_annotation(&mut self, annotation: Annotation) {
        self.annotations.push(annotation);
    }

    /// Returns a reference to the annotations
    pub fn annotations(&self) -> &[Annotation] {
        &self.annotations
    }

    /// Returns a mutable reference to the annotations  
    pub fn annotations_mut(&mut self) -> &mut Vec<Annotation> {
        &mut self.annotations
    }

    /// Add a form field widget to the page.
    ///
    /// This method adds a widget annotation and returns the reference ID that
    /// should be used to link the widget to its corresponding form field.
    ///
    /// # Arguments
    ///
    /// * `widget` - The widget to add to the page
    ///
    /// # Returns
    ///
    /// An ObjectReference that should be used to link this widget to a form field
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::{Page, forms::Widget, geometry::{Rectangle, Point}};
    ///
    /// let mut page = Page::a4();
    /// let widget = Widget::new(
    ///     Rectangle::new(Point::new(100.0, 700.0), Point::new(300.0, 720.0))
    /// );
    /// let widget_ref = page.add_form_widget(widget);
    /// ```
    pub fn add_form_widget(&mut self, widget: Widget) -> ObjectReference {
        // Create a placeholder object reference for this widget
        // The actual ObjectId will be assigned by the document writer
        // We use a placeholder ID that doesn't conflict with real ObjectIds
        let widget_ref = ObjectReference::new(
            0, // Placeholder ID - writer will assign the real ID
            0,
        );

        // Convert widget to annotation
        let mut annot = Annotation::new(crate::annotations::AnnotationType::Widget, widget.rect);

        // Add widget-specific properties
        for (key, value) in widget.to_annotation_dict().iter() {
            annot.properties.set(key, value.clone());
        }

        // Add to page's annotations
        self.annotations.push(annot);

        widget_ref
    }

    /// Add a form field widget to the page and link it to an existing AcroForm field.
    ///
    /// Unlike [`Page::add_form_widget`], which expects the writer to track the
    /// relationship implicitly via shared field names, this variant records
    /// the `field_ref` as the widget's `/Parent` so the resulting PDF carries
    /// an explicit widget→field link per ISO 32000-1 §12.7.3.1.
    ///
    /// This is the recommended path when the field itself was created via
    /// [`crate::forms::FormManager`] (whose `add_text_field`, `add_combo_box`,
    /// etc. return the field's `ObjectReference`): the field object is
    /// serialized as an indirect object, and every widget placed on a page
    /// points back to it through `/Parent`.
    ///
    /// # Arguments
    ///
    /// * `widget` - The widget appearance/geometry to place on the page.
    /// * `field_ref` - The `ObjectReference` of the AcroForm field this
    ///   widget belongs to (as returned by `FormManager::add_*`).
    ///
    /// # Returns
    ///
    /// `Ok(())` on success. The method currently cannot fail; the `Result`
    /// return type is reserved for future validation.
    pub fn add_form_widget_with_ref(
        &mut self,
        widget: Widget,
        field_ref: ObjectReference,
    ) -> crate::error::Result<()> {
        // Convert widget to annotation, same as add_form_widget.
        let mut annot = Annotation::new(crate::annotations::AnnotationType::Widget, widget.rect);

        for (key, value) in widget.to_annotation_dict().iter() {
            annot.properties.set(key, value.clone());
        }

        // Record the parent field reference so the writer emits
        // `/Parent <field_ref>` in the widget annotation dictionary.
        // Goes through the setter so the Widget-annotation-type invariant
        // is enforced (debug_assert! in debug builds) — `field_parent` is
        // `pub(crate)` precisely to prevent external callers bypassing it.
        annot.set_field_parent(field_ref);

        self.annotations.push(annot);
        Ok(())
    }

    /// Sets the header for this page.
    ///
    /// # Example
    ///
    /// ```rust
    /// use oxidize_pdf::{Page, text::HeaderFooter};
    ///
    /// let mut page = Page::a4();
    /// page.set_header(HeaderFooter::new_header("Company Report 2024"));
    /// ```
    pub fn set_header(&mut self, header: HeaderFooter) {
        self.register_header_footer_font_usage(&header);
        self.header = Some(header);
    }

    /// Sets the footer for this page.
    ///
    /// # Example
    ///
    /// ```rust
    /// use oxidize_pdf::{Page, text::HeaderFooter};
    ///
    /// let mut page = Page::a4();
    /// page.set_footer(HeaderFooter::new_footer("Page {{page_number}} of {{total_pages}}"));
    /// ```
    pub fn set_footer(&mut self, footer: HeaderFooter) {
        self.register_header_footer_font_usage(&footer);
        self.footer = Some(footer);
    }

    /// Eagerly record the font + estimated character set of a header or
    /// footer on the page's graphics-context accumulator (gap R5 of
    /// issue #204).
    ///
    /// Header/footer content is rendered at serialization time — inside
    /// `generate_content_with_page_info` — which runs AFTER the writer
    /// has snapshotted the document's per-font map into its own
    /// `document_used_chars_by_font`. Any characters drawn at render
    /// time therefore arrive too late to be included in the font
    /// subset. We compensate here by expanding the template with
    /// canonical sample values (the numeric placeholders become the
    /// digit set; `{{date}}`, `{{time}}`, `{{month}}`, etc. expand to
    /// the current locale's rendering) and registering those chars
    /// plus the template's literal text up front.
    ///
    /// **Known limitation**: user-supplied `custom_values` passed later
    /// to the writer may introduce characters not in the template
    /// literal. Those chars will NOT appear in the embedded subset and
    /// will render as `.notdef`. Callers who need runtime-defined
    /// custom strings in a custom-font header should also draw a
    /// `page.text()` with the same font somewhere (even invisibly)
    /// so the chars reach the per-font bucket through the standard
    /// path.
    fn register_header_footer_font_usage(&mut self, hf: &HeaderFooter) {
        let font_name = hf.options().font.pdf_name();

        // Render the template with canonical sample values to capture
        // both the literal text and whatever the locale-dependent
        // placeholders expand to (month name, date format, etc.).
        // page_number=1 / total_pages=999 covers the digit 9 which is
        // the upper boundary of common PDFs; a further safety net adds
        // the full digit set below.
        let sampled = hf.render(1, 999, None);

        let mut chars: HashSet<char> = sampled.chars().collect();
        // Digits 0-9 are guaranteed to appear once the template is
        // rendered with real page numbers (the sample above only
        // covered {1, 9} digits). Include the rest so page 2..8 don't
        // render as .notdef on the last page of a >10-page document.
        chars.extend('0'..='9');

        self.graphics_context
            .merge_font_usage(&std::iter::once((font_name, chars)).collect());
    }

    /// Gets a reference to the header if set.
    pub fn header(&self) -> Option<&HeaderFooter> {
        self.header.as_ref()
    }

    /// Gets a reference to the footer if set.
    pub fn footer(&self) -> Option<&HeaderFooter> {
        self.footer.as_ref()
    }

    /// Sets the page content directly.
    ///
    /// This is used internally when processing headers and footers.
    pub(crate) fn set_content(&mut self, content: Vec<u8>) {
        self.content = content;
    }

    pub(crate) fn generate_content(&mut self) -> Result<Vec<u8>> {
        // Generate content with no page info (used for simple pages without headers/footers)
        self.generate_content_with_page_info(None, None, None)
    }

    /// Generates page content with header/footer support.
    ///
    /// This method is used internally by the writer to render pages with
    /// proper page numbering in headers and footers.
    pub(crate) fn generate_content_with_page_info(
        &mut self,
        page_number: Option<usize>,
        total_pages: Option<usize>,
        custom_values: Option<&HashMap<String, String>>,
    ) -> Result<Vec<u8>> {
        let mut final_content = Vec::new();

        // Render header if present
        if let Some(header) = &self.header {
            if let (Some(page_num), Some(total)) = (page_number, total_pages) {
                let header_content =
                    self.render_header_footer(header, page_num, total, custom_values)?;
                final_content.extend_from_slice(&header_content);
            }
        }

        // Painter-model preservation (issue #227): emit operators in
        // caller call order, not in fixed `graphics-then-text` category
        // order.
        //
        // `page_ops` already holds the operators flushed at every
        // context switch (see `Page::graphics` / `Page::text`). Whatever
        // remains in either context's own buffer is the *tail* — the
        // operators emitted after the last switch — and is appended in
        // its natural ordering. Only one of the two tails can be
        // non-empty at any given time (because the other was drained on
        // the most recent switch), so the relative order of the two
        // appends below is irrelevant.
        crate::graphics::ops::serialize_ops(&mut final_content, &self.page_ops);
        let gfx_tail = self.graphics_context.generate_operations()?;
        final_content.extend_from_slice(&gfx_tail);
        let text_tail = self.text_context.generate_operations()?;
        final_content.extend_from_slice(&text_tail);

        // Add preserved original content. Issue #395: rewrite only the font
        // references the writer disambiguated (collision-only). When no font
        // collided, `preserved_font_rewrite_map` is empty and the preserved
        // content is emitted verbatim — the common case (incl. all-non-base-14
        // inputs like `testi.pdf`), which avoids ever touching the stream.
        let content_to_add = if self.preserved_font_rewrite_map.is_empty()
            || self.content.is_empty()
        {
            self.content.clone()
        } else {
            crate::writer::rewrite_font_references(&self.content, &self.preserved_font_rewrite_map)
        };

        final_content.extend_from_slice(&content_to_add);

        // Render footer if present
        if let Some(footer) = &self.footer {
            if let (Some(page_num), Some(total)) = (page_number, total_pages) {
                let footer_content =
                    self.render_header_footer(footer, page_num, total, custom_values)?;
                final_content.extend_from_slice(&footer_content);
            }
        }

        Ok(final_content)
    }

    /// Renders a header or footer with the given page information.
    fn render_header_footer(
        &self,
        header_footer: &HeaderFooter,
        page_number: usize,
        total_pages: usize,
        custom_values: Option<&HashMap<String, String>>,
    ) -> Result<Vec<u8>> {
        use crate::text::measure_text;

        // Render the content with placeholders replaced
        let content = header_footer.render(page_number, total_pages, custom_values);

        // Calculate text width for alignment
        let text_width = measure_text(
            &content,
            &header_footer.options().font,
            header_footer.options().font_size,
        );

        // Calculate positions
        let x = header_footer.calculate_x_position(self.width, text_width);
        let y = header_footer.calculate_y_position(self.height);

        // Create a temporary text context for the header/footer
        let mut text_ctx = TextContext::new();
        text_ctx
            .set_font(
                header_footer.options().font.clone(),
                header_footer.options().font_size,
            )
            .at(x, y)
            .write(&content)?;

        text_ctx.generate_operations()
    }

    /// Convert page to dictionary for PDF structure
    pub(crate) fn to_dict(&self) -> Dictionary {
        let mut dict = Dictionary::new();

        // MediaBox
        let media_box = Array::from(vec![
            Object::Real(0.0),
            Object::Real(0.0),
            Object::Real(self.width),
            Object::Real(self.height),
        ]);
        dict.set("MediaBox", Object::Array(media_box.into()));

        // Add rotation if not zero
        if self.rotation != 0 {
            dict.set("Rotate", Object::Integer(self.rotation as i64));
        }

        // Resources (empty for now, would include fonts, images, etc.)
        let resources = Dictionary::new();
        dict.set("Resources", Object::Dictionary(resources));

        // Annotations - will be added by the writer with proper object references
        // The Page struct holds the annotation data, but the writer is responsible
        // for creating object references and writing the annotation objects
        //
        // NOTE: We don't add Annots array here anymore because the writer
        // will handle this properly with sequential ObjectIds. The temporary
        // ObjectIds (1000+) were causing invalid references in the final PDF.
        // The writer now handles all ObjectId allocation and writing.

        // Contents would be added by the writer

        dict
    }

    /// Gets all characters used in this page, bucketed by font name
    /// (issue #204).
    ///
    /// Merges the per-font maps from `graphics_context` and
    /// `text_context` — either or both may contain entries for the
    /// same font (e.g. a caller mixed `page.text()` with direct
    /// graphics-context `draw_text`). Both builtin and custom fonts
    /// appear as keys; the writer filters to the registered custom
    /// fonts at subsetting time (builtin fonts don't need subsetting).
    pub(crate) fn get_used_characters_by_font(&self) -> HashMap<String, HashSet<char>> {
        let mut merged: HashMap<String, HashSet<char>> = HashMap::new();
        for (name, chars) in self.graphics_context.get_used_characters_by_font() {
            merged.entry(name.clone()).or_default().extend(chars);
        }
        for (name, chars) in self.text_context.get_used_characters_by_font() {
            merged.entry(name.clone()).or_default().extend(chars);
        }
        merged
    }

    /// Back-compat accessor used by the legacy issue-#97 tests: returns
    /// all characters drawn on this page merged across fonts. Prefer
    /// [`Page::get_used_characters_by_font`] for new callers — the
    /// writer depends on per-font accuracy to avoid bundling the
    /// active font's coverage into unused fonts (issue #204).
    #[cfg(test)]
    pub(crate) fn get_used_characters(&self) -> Option<HashSet<char>> {
        let merged: HashSet<char> = self
            .get_used_characters_by_font()
            .into_values()
            .flatten()
            .collect();
        if merged.is_empty() {
            None
        } else {
            Some(merged)
        }
    }

    // ==================== Tagged PDF / Marked Content Support ====================

    /// Begins a marked content sequence for Tagged PDF
    ///
    /// This adds a BDC (Begin Marked Content with Properties) operator to the content stream
    /// with an MCID (Marked Content ID) property. The MCID connects the content to a
    /// structure element in the structure tree.
    ///
    /// # Returns
    ///
    /// Returns the assigned MCID, which should be added to the corresponding StructureElement
    /// via `StructureElement::add_mcid(page_index, mcid)`.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use oxidize_pdf::{Page, structure::{StructTree, StructureElement, StandardStructureType}};
    ///
    /// let mut page = Page::a4();
    /// let mut tree = StructTree::new();
    ///
    /// // Create structure
    /// let doc = StructureElement::new(StandardStructureType::Document);
    /// let doc_idx = tree.set_root(doc);
    /// let mut para = StructureElement::new(StandardStructureType::P);
    ///
    /// // Begin marked content for paragraph
    /// let mcid = page.begin_marked_content("P")?;
    ///
    /// // Add content
    /// page.text().write("Hello, Tagged PDF!")?;
    ///
    /// // End marked content
    /// page.end_marked_content()?;
    ///
    /// // Connect MCID to structure element
    /// para.add_mcid(0, mcid);  // page_index=0, mcid from above
    /// tree.add_child(doc_idx, para).map_err(|e| oxidize_pdf::PdfError::InvalidOperation(e))?;
    /// # Ok::<(), oxidize_pdf::PdfError>(())
    /// ```
    pub fn begin_marked_content(&mut self, tag: &str) -> Result<u32> {
        let mcid = self.next_mcid;
        self.next_mcid += 1;

        // Add BDC operator with MCID property to text context
        // Format: /Tag <</MCID mcid>> BDC
        let bdc_op = format!("/{} <</MCID {}>> BDC\n", tag, mcid);
        self.text_context.append_raw_operation(&bdc_op);

        self.marked_content_stack.push(tag.to_string());

        Ok(mcid)
    }

    /// Ends the current marked content sequence
    ///
    /// This adds an EMC (End Marked Content) operator to close the most recently
    /// opened marked content sequence.
    ///
    /// # Errors
    ///
    /// Returns an error if there is no open marked content sequence.
    pub fn end_marked_content(&mut self) -> Result<()> {
        if self.marked_content_stack.is_empty() {
            return Err(crate::PdfError::InvalidOperation(
                "No marked content sequence to end (EMC without BDC)".to_string(),
            ));
        }

        self.marked_content_stack.pop();

        // Add EMC operator to text context
        self.text_context.append_raw_operation("EMC\n");

        Ok(())
    }

    /// Returns the next MCID that will be assigned
    ///
    /// This is useful for pre-allocating structure elements before adding content.
    pub fn next_mcid(&self) -> u32 {
        self.next_mcid
    }

    /// Returns the current depth of nested marked content
    pub fn marked_content_depth(&self) -> usize {
        self.marked_content_stack.len()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::graphics::Color;
    use crate::text::Font;

    #[test]
    fn test_page_new() {
        let page = Page::new(100.0, 200.0);
        assert_eq!(page.width(), 100.0);
        assert_eq!(page.height(), 200.0);
        assert_eq!(page.margins().left, 72.0);
        assert_eq!(page.margins().right, 72.0);
        assert_eq!(page.margins().top, 72.0);
        assert_eq!(page.margins().bottom, 72.0);
    }

    #[test]
    fn test_page_a4() {
        let page = Page::a4();
        assert_eq!(page.width(), 595.0);
        assert_eq!(page.height(), 842.0);
    }

    #[test]
    fn test_page_letter() {
        let page = Page::letter();
        assert_eq!(page.width(), 612.0);
        assert_eq!(page.height(), 792.0);
    }

    #[test]
    fn test_set_margins() {
        let mut page = Page::a4();
        page.set_margins(10.0, 20.0, 30.0, 40.0);

        assert_eq!(page.margins().left, 10.0);
        assert_eq!(page.margins().right, 20.0);
        assert_eq!(page.margins().top, 30.0);
        assert_eq!(page.margins().bottom, 40.0);
    }

    #[test]
    fn test_content_dimensions() {
        let mut page = Page::new(300.0, 400.0);
        page.set_margins(50.0, 50.0, 50.0, 50.0);

        assert_eq!(page.content_width(), 200.0);
        assert_eq!(page.content_height(), 300.0);
    }

    #[test]
    fn test_content_area() {
        let mut page = Page::new(300.0, 400.0);
        page.set_margins(10.0, 20.0, 30.0, 40.0);

        let (left, bottom, right, top) = page.content_area();
        assert_eq!(left, 10.0);
        assert_eq!(bottom, 40.0);
        assert_eq!(right, 280.0);
        assert_eq!(top, 370.0);
    }

    #[test]
    fn test_graphics_context() {
        let mut page = Page::a4();
        let graphics = page.graphics();
        graphics.set_fill_color(Color::red());
        graphics.rect(100.0, 100.0, 200.0, 150.0);
        graphics.fill();

        // Graphics context should be accessible and modifiable
        assert!(page.generate_content().is_ok());
    }

    #[test]
    fn test_text_context() {
        let mut page = Page::a4();
        let text = page.text();
        text.set_font(Font::Helvetica, 12.0);
        text.at(100.0, 700.0);
        text.write("Hello World").unwrap();

        // Text context should be accessible and modifiable
        assert!(page.generate_content().is_ok());
    }

    #[test]
    fn test_text_flow() {
        let page = Page::a4();
        let text_flow = page.text_flow();

        // Text flow should be created with page dimensions and margins
        // Just verify it can be created
        drop(text_flow);
    }

    #[test]
    fn test_add_text_flow() {
        let mut page = Page::a4();
        let mut text_flow = page.text_flow();
        text_flow.at(100.0, 700.0);
        text_flow.set_font(Font::TimesRoman, 14.0);
        text_flow.write_wrapped("Test text flow").unwrap();

        page.add_text_flow(&text_flow);

        let content = page.generate_content().unwrap();
        assert!(!content.is_empty());
    }

    #[test]
    fn test_add_image() {
        let mut page = Page::a4();
        // Create a minimal valid JPEG with SOF0 header
        let jpeg_data = vec![
            0xFF, 0xD8, // SOI marker
            0xFF, 0xC0, // SOF0 marker
            0x00, 0x11, // Length (17 bytes)
            0x08, // Precision (8 bits)
            0x00, 0x64, // Height (100)
            0x00, 0xC8, // Width (200)
            0x03, // Components (3 = RGB)
            0xFF, 0xD9, // EOI marker
        ];
        let image = Image::from_jpeg_data(jpeg_data).unwrap();

        page.add_image("test_image", image);
        assert!(page.images().contains_key("test_image"));
        assert_eq!(page.images().len(), 1);
    }

    #[test]
    fn test_draw_image() {
        let mut page = Page::a4();
        // Create a minimal valid JPEG with SOF0 header
        let jpeg_data = vec![
            0xFF, 0xD8, // SOI marker
            0xFF, 0xC0, // SOF0 marker
            0x00, 0x11, // Length (17 bytes)
            0x08, // Precision (8 bits)
            0x00, 0x64, // Height (100)
            0x00, 0xC8, // Width (200)
            0x03, // Components (3 = RGB)
            0xFF, 0xD9, // EOI marker
        ];
        let image = Image::from_jpeg_data(jpeg_data).unwrap();

        page.add_image("test_image", image);
        let result = page.draw_image("test_image", 50.0, 50.0, 200.0, 200.0);
        assert!(result.is_ok());
    }

    #[test]
    fn test_draw_nonexistent_image() {
        let mut page = Page::a4();
        let result = page.draw_image("nonexistent", 50.0, 50.0, 200.0, 200.0);
        assert!(result.is_err());
    }

    #[test]
    fn test_generate_content() {
        let mut page = Page::a4();

        // Add some graphics
        page.graphics()
            .set_fill_color(Color::blue())
            .circle(200.0, 400.0, 50.0)
            .fill();

        // Add some text
        page.text()
            .set_font(Font::Courier, 10.0)
            .at(50.0, 650.0)
            .write("Test content")
            .unwrap();

        let content = page.generate_content().unwrap();
        assert!(!content.is_empty());
    }

    #[test]
    fn test_margins_default() {
        let margins = Margins::default();
        assert_eq!(margins.left, 72.0);
        assert_eq!(margins.right, 72.0);
        assert_eq!(margins.top, 72.0);
        assert_eq!(margins.bottom, 72.0);
    }

    #[test]
    fn test_page_clone() {
        let mut page1 = Page::a4();
        page1.set_margins(10.0, 20.0, 30.0, 40.0);
        // Create a minimal valid JPEG with SOF0 header
        let jpeg_data = vec![
            0xFF, 0xD8, // SOI marker
            0xFF, 0xC0, // SOF0 marker
            0x00, 0x11, // Length (17 bytes)
            0x08, // Precision (8 bits)
            0x00, 0x32, // Height (50)
            0x00, 0x32, // Width (50)
            0x03, // Components (3 = RGB)
            0xFF, 0xD9, // EOI marker
        ];
        let image = Image::from_jpeg_data(jpeg_data).unwrap();
        page1.add_image("img1", image);

        let page2 = page1.clone();
        assert_eq!(page2.width(), page1.width());
        assert_eq!(page2.height(), page1.height());
        assert_eq!(page2.margins().left, page1.margins().left);
        assert_eq!(page2.images().len(), page1.images().len());
    }

    #[test]
    fn test_header_footer_basic() {
        use crate::text::HeaderFooter;

        let mut page = Page::a4();

        let header = HeaderFooter::new_header("Test Header");
        let footer = HeaderFooter::new_footer("Test Footer");

        page.set_header(header);
        page.set_footer(footer);

        assert!(page.header().is_some());
        assert!(page.footer().is_some());
        assert_eq!(page.header().unwrap().content(), "Test Header");
        assert_eq!(page.footer().unwrap().content(), "Test Footer");
    }

    #[test]
    fn test_header_footer_with_page_numbers() {
        use crate::text::HeaderFooter;

        let mut page = Page::a4();

        let footer = HeaderFooter::new_footer("Page {{page_number}} of {{total_pages}}");
        page.set_footer(footer);

        // Generate content with page info
        let content = page
            .generate_content_with_page_info(Some(3), Some(10), None)
            .unwrap();
        assert!(!content.is_empty());

        // The content should contain the rendered footer
        let content_str = String::from_utf8_lossy(&content);
        assert!(content_str.contains("Page 3 of 10"));
    }

    #[test]
    fn test_page_content_with_headers_footers() {
        use crate::text::{HeaderFooter, TextAlign};

        let mut page = Page::a4();

        // Add header
        let header = HeaderFooter::new_header("Document Title")
            .with_font(Font::HelveticaBold, 14.0)
            .with_alignment(TextAlign::Center);
        page.set_header(header);

        // Add footer
        let footer = HeaderFooter::new_footer("Page {{page_number}}")
            .with_font(Font::Helvetica, 10.0)
            .with_alignment(TextAlign::Right);
        page.set_footer(footer);

        // Add main content
        page.text()
            .set_font(Font::TimesRoman, 12.0)
            .at(100.0, 700.0)
            .write("Main content here")
            .unwrap();

        // Generate with page info
        let content = page
            .generate_content_with_page_info(Some(1), Some(5), None)
            .unwrap();
        assert!(!content.is_empty());

        // Verify that content was generated (it includes header, main content, and footer)
        // Note: We generate raw PDF content streams here, not the full PDF
        // The content may be in PDF format with operators like BT/ET, Tj, etc.
        assert!(content.len() > 100); // Should have substantial content
    }

    #[test]
    fn test_no_headers_footers() {
        let mut page = Page::a4();

        // No headers/footers set
        assert!(page.header().is_none());
        assert!(page.footer().is_none());

        // Content generation should work without headers/footers
        let content = page
            .generate_content_with_page_info(Some(1), Some(1), None)
            .unwrap();
        assert!(content.is_empty() || !content.is_empty()); // May be empty or contain default content
    }

    #[test]
    fn test_header_footer_custom_values() {
        use crate::text::HeaderFooter;
        use std::collections::HashMap;

        let mut page = Page::a4();

        let header = HeaderFooter::new_header("{{company}} - {{title}}");
        page.set_header(header);

        let mut custom_values = HashMap::new();
        custom_values.insert("company".to_string(), "ACME Corp".to_string());
        custom_values.insert("title".to_string(), "Annual Report".to_string());

        let content = page
            .generate_content_with_page_info(Some(1), Some(1), Some(&custom_values))
            .unwrap();
        let content_str = String::from_utf8_lossy(&content);
        assert!(content_str.contains("ACME Corp - Annual Report"));
    }

    // Integration tests for Page ↔ Document ↔ Writer interactions
    mod integration_tests {
        use super::*;
        use crate::document::Document;
        use crate::writer::PdfWriter;
        use std::fs;
        use tempfile::TempDir;

        #[test]
        fn test_page_document_integration() {
            let mut doc = Document::new();
            doc.set_title("Page Integration Test");

            // Create pages with different sizes
            let page1 = Page::a4();
            let page2 = Page::letter();
            let mut page3 = Page::new(400.0, 600.0);

            // Add content to custom page
            page3.set_margins(20.0, 20.0, 20.0, 20.0);
            page3
                .text()
                .set_font(Font::Helvetica, 14.0)
                .at(50.0, 550.0)
                .write("Custom page content")
                .unwrap();

            doc.add_page(page1);
            doc.add_page(page2);
            doc.add_page(page3);

            assert_eq!(doc.pages.len(), 3);

            // Verify page properties are preserved
            assert_eq!(doc.pages[0].width(), 595.0); // A4
            assert_eq!(doc.pages[1].width(), 612.0); // Letter
            assert_eq!(doc.pages[2].width(), 400.0); // Custom

            // Verify content generation works
            let mut page_copy = doc.pages[2].clone();
            let content = page_copy.generate_content().unwrap();
            assert!(!content.is_empty());
        }

        #[test]
        fn test_page_writer_integration() {
            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("page_writer_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Page Writer Integration");

            // Create a page with complex content
            let mut page = Page::a4();
            page.set_margins(50.0, 50.0, 50.0, 50.0);

            // Add text content
            page.text()
                .set_font(Font::Helvetica, 16.0)
                .at(100.0, 750.0)
                .write("Integration Test Header")
                .unwrap();

            page.text()
                .set_font(Font::TimesRoman, 12.0)
                .at(100.0, 700.0)
                .write("This is body text for the integration test.")
                .unwrap();

            // Add graphics content
            page.graphics()
                .set_fill_color(Color::rgb(0.2, 0.6, 0.9))
                .rect(100.0, 600.0, 200.0, 50.0)
                .fill();

            page.graphics()
                .set_stroke_color(Color::rgb(0.8, 0.2, 0.2))
                .set_line_width(3.0)
                .circle(300.0, 500.0, 40.0)
                .stroke();

            doc.add_page(page);

            // Write to file
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            // Verify file was created and has content
            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 1000); // Should be substantial

            // Verify PDF structure (text may be compressed, so check for basic structure)
            let content = fs::read(&file_path).unwrap();
            let content_str = String::from_utf8_lossy(&content);
            assert!(content_str.contains("obj")); // Should contain PDF objects
            assert!(content_str.contains("stream")); // Should contain content streams
        }

        #[test]
        fn test_page_margins_integration() {
            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("margins_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Margins Integration Test");

            // Test different margin configurations
            let mut page1 = Page::a4();
            page1.set_margins(10.0, 20.0, 30.0, 40.0);

            let mut page2 = Page::letter();
            page2.set_margins(72.0, 72.0, 72.0, 72.0); // 1 inch margins

            let mut page3 = Page::new(500.0, 700.0);
            page3.set_margins(0.0, 0.0, 0.0, 0.0); // No margins

            // Add content that uses margin information
            for (i, page) in [&mut page1, &mut page2, &mut page3].iter_mut().enumerate() {
                let (left, bottom, right, top) = page.content_area();

                // Place text at content area boundaries
                page.text()
                    .set_font(Font::Helvetica, 10.0)
                    .at(left, top - 20.0)
                    .write(&format!(
                        "Page {} - Content area: ({:.1}, {:.1}, {:.1}, {:.1})",
                        i + 1,
                        left,
                        bottom,
                        right,
                        top
                    ))
                    .unwrap();

                // Draw border around content area
                page.graphics()
                    .set_stroke_color(Color::rgb(0.5, 0.5, 0.5))
                    .set_line_width(1.0)
                    .rect(left, bottom, right - left, top - bottom)
                    .stroke();
            }

            doc.add_page(page1);
            doc.add_page(page2);
            doc.add_page(page3);

            // Write and verify
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 500); // Should contain substantial content
        }

        #[test]
        fn test_page_image_integration() {
            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("image_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Image Integration Test");

            let mut page = Page::a4();

            // Create test images
            let jpeg_data1 = vec![
                0xFF, 0xD8, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x64, 0x00, 0xC8, 0x03, 0xFF, 0xD9,
            ];
            let image1 = Image::from_jpeg_data(jpeg_data1).unwrap();

            let jpeg_data2 = vec![
                0xFF, 0xD8, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x32, 0x00, 0x32, 0x01, 0xFF, 0xD9,
            ];
            let image2 = Image::from_jpeg_data(jpeg_data2).unwrap();

            // Add images to page
            page.add_image("image1", image1);
            page.add_image("image2", image2);

            // Draw images at different positions
            page.draw_image("image1", 100.0, 600.0, 200.0, 100.0)
                .unwrap();
            page.draw_image("image2", 350.0, 600.0, 50.0, 50.0).unwrap();

            // Add text labels
            page.text()
                .set_font(Font::Helvetica, 12.0)
                .at(100.0, 580.0)
                .write("Image 1 (200x100)")
                .unwrap();

            page.text()
                .set_font(Font::Helvetica, 12.0)
                .at(350.0, 580.0)
                .write("Image 2 (50x50)")
                .unwrap();

            // Verify images were added before moving page
            assert_eq!(page.images().len(), 2, "Two images should be added to page");

            doc.add_page(page);

            // Write and verify
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 500); // Should contain images and text

            // Verify XObject references in PDF
            let content = fs::read(&file_path).unwrap();
            let content_str = String::from_utf8_lossy(&content);

            // Debug: print what we're looking for
            tracing::debug!("PDF size: {} bytes", content.len());
            tracing::debug!("Contains 'XObject': {}", content_str.contains("XObject"));
            tracing::debug!("Contains '/XObject': {}", content_str.contains("/XObject"));

            // Check for image-related content
            if content_str.contains("/Type /Image") || content_str.contains("DCTDecode") {
                tracing::debug!("Found image-related content but no XObject dictionary");
            }

            // Verify XObject is properly written
            assert!(content_str.contains("XObject"));
        }

        #[test]
        fn test_page_text_flow_integration() {
            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("text_flow_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Text Flow Integration Test");

            let mut page = Page::a4();
            page.set_margins(50.0, 50.0, 50.0, 50.0);

            // Create text flow with long content
            let mut text_flow = page.text_flow();
            text_flow.set_font(Font::TimesRoman, 12.0);
            text_flow.at(100.0, 700.0);

            let long_text =
                "This is a long paragraph that should demonstrate text flow capabilities. "
                    .repeat(10);
            text_flow.write_wrapped(&long_text).unwrap();

            // Add the text flow to the page
            page.add_text_flow(&text_flow);

            // Also add regular text
            page.text()
                .set_font(Font::Helvetica, 14.0)
                .at(100.0, 750.0)
                .write("Regular Text Above Text Flow")
                .unwrap();

            doc.add_page(page);

            // Write and verify
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 1000); // Should contain text content

            // Verify text structure appears in PDF
            let content = fs::read(&file_path).unwrap();
            let content_str = String::from_utf8_lossy(&content);
            assert!(content_str.contains("obj")); // Should contain PDF objects
            assert!(content_str.contains("stream")); // Should contain content streams
        }

        #[test]
        fn test_page_complex_content_integration() {
            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("complex_content_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Complex Content Integration Test");

            let mut page = Page::a4();
            page.set_margins(40.0, 40.0, 40.0, 40.0);

            // Create complex layered content

            // Background graphics
            page.graphics()
                .set_fill_color(Color::rgb(0.95, 0.95, 0.95))
                .rect(50.0, 50.0, 495.0, 742.0)
                .fill();

            // Header section
            page.graphics()
                .set_fill_color(Color::rgb(0.2, 0.4, 0.8))
                .rect(50.0, 750.0, 495.0, 42.0)
                .fill();

            page.text()
                .set_font(Font::HelveticaBold, 18.0)
                .at(60.0, 765.0)
                .write("Complex Content Integration Test")
                .unwrap();

            // Content sections with mixed elements
            let mut y_pos = 700.0;
            for i in 1..=3 {
                // Section header
                page.graphics()
                    .set_fill_color(Color::rgb(0.8, 0.8, 0.9))
                    .rect(60.0, y_pos, 475.0, 20.0)
                    .fill();

                page.text()
                    .set_font(Font::HelveticaBold, 12.0)
                    .at(70.0, y_pos + 5.0)
                    .write(&format!("Section {i}"))
                    .unwrap();

                y_pos -= 30.0;

                // Section content
                page.text()
                    .set_font(Font::TimesRoman, 10.0)
                    .at(70.0, y_pos)
                    .write(&format!(
                        "This is the content for section {i}. It demonstrates mixed content."
                    ))
                    .unwrap();

                // Section graphics
                page.graphics()
                    .set_stroke_color(Color::rgb(0.6, 0.2, 0.2))
                    .set_line_width(2.0)
                    .move_to(70.0, y_pos - 10.0)
                    .line_to(530.0, y_pos - 10.0)
                    .stroke();

                y_pos -= 50.0;
            }

            // Footer
            page.graphics()
                .set_fill_color(Color::rgb(0.3, 0.3, 0.3))
                .rect(50.0, 50.0, 495.0, 30.0)
                .fill();

            page.text()
                .set_font(Font::Helvetica, 10.0)
                .at(60.0, 60.0)
                .write("Generated by oxidize-pdf integration test")
                .unwrap();

            doc.add_page(page);

            // Write and verify
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 500); // Should contain substantial content

            // Verify content structure (text may be compressed, so check for basic structure)
            let content = fs::read(&file_path).unwrap();
            let content_str = String::from_utf8_lossy(&content);
            assert!(content_str.contains("obj")); // Should contain PDF objects
            assert!(content_str.contains("stream")); // Should contain content streams
            assert!(content_str.contains("endobj")); // Should contain object endings
        }

        #[test]
        fn test_page_content_generation_performance() {
            let mut page = Page::a4();

            // Add many elements to test performance
            for i in 0..100 {
                let y = 800.0 - (i as f64 * 7.0);
                if y > 50.0 {
                    page.text()
                        .set_font(Font::Helvetica, 8.0)
                        .at(50.0, y)
                        .write(&format!("Performance test line {i}"))
                        .unwrap();
                }
            }

            // Add graphics elements
            for i in 0..50 {
                let x = 50.0 + (i as f64 * 10.0);
                if x < 550.0 {
                    page.graphics()
                        .set_fill_color(Color::rgb(0.5, 0.5, 0.8))
                        .rect(x, 400.0, 8.0, 8.0)
                        .fill();
                }
            }

            // Content generation should complete in reasonable time
            let start = std::time::Instant::now();
            let content = page.generate_content().unwrap();
            let duration = start.elapsed();

            assert!(!content.is_empty());
            assert!(duration.as_millis() < 1000); // Should complete within 1 second
        }

        #[test]
        fn test_page_error_handling() {
            let mut page = Page::a4();

            // Test drawing non-existent image
            let result = page.draw_image("nonexistent", 100.0, 100.0, 50.0, 50.0);
            assert!(result.is_err());

            // Test with invalid parameters - should still work
            let result = page.draw_image("still_nonexistent", -100.0, -100.0, 0.0, 0.0);
            assert!(result.is_err());

            // Add an image and test valid drawing
            let jpeg_data = vec![
                0xFF, 0xD8, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x32, 0x00, 0x32, 0x01, 0xFF, 0xD9,
            ];
            let image = Image::from_jpeg_data(jpeg_data).unwrap();
            page.add_image("valid_image", image);

            let result = page.draw_image("valid_image", 100.0, 100.0, 50.0, 50.0);
            assert!(result.is_ok());
        }

        #[test]
        fn test_page_memory_management() {
            let mut pages = Vec::new();

            // Create many pages to test memory usage
            for i in 0..100 {
                let mut page = Page::a4();
                page.set_margins(i as f64, i as f64, i as f64, i as f64);

                page.text()
                    .set_font(Font::Helvetica, 12.0)
                    .at(100.0, 700.0)
                    .write(&format!("Page {i}"))
                    .unwrap();

                pages.push(page);
            }

            // All pages should be valid
            assert_eq!(pages.len(), 100);

            // Content generation should work for all pages
            for page in pages.iter_mut() {
                let content = page.generate_content().unwrap();
                assert!(!content.is_empty());
            }
        }

        #[test]
        fn test_page_standard_sizes() {
            let a4 = Page::a4();
            let letter = Page::letter();
            let custom = Page::new(200.0, 300.0);

            // Test standard dimensions
            assert_eq!(a4.width(), 595.0);
            assert_eq!(a4.height(), 842.0);
            assert_eq!(letter.width(), 612.0);
            assert_eq!(letter.height(), 792.0);
            assert_eq!(custom.width(), 200.0);
            assert_eq!(custom.height(), 300.0);

            // Test content areas with default margins
            let a4_content_width = a4.content_width();
            let letter_content_width = letter.content_width();
            let custom_content_width = custom.content_width();

            assert_eq!(a4_content_width, 595.0 - 144.0); // 595 - 2*72
            assert_eq!(letter_content_width, 612.0 - 144.0); // 612 - 2*72
            assert_eq!(custom_content_width, 200.0 - 144.0); // 200 - 2*72
        }

        #[test]
        fn test_header_footer_document_integration() {
            use crate::text::{HeaderFooter, TextAlign};

            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("header_footer_test.pdf");

            let mut doc = Document::new();
            doc.set_title("Header Footer Integration Test");

            // Create multiple pages with headers and footers
            for i in 1..=3 {
                let mut page = Page::a4();

                // Set header
                let header = HeaderFooter::new_header(format!("Chapter {i}"))
                    .with_font(Font::HelveticaBold, 16.0)
                    .with_alignment(TextAlign::Center);
                page.set_header(header);

                // Set footer with page numbers
                let footer = HeaderFooter::new_footer("Page {{page_number}} of {{total_pages}}")
                    .with_font(Font::Helvetica, 10.0)
                    .with_alignment(TextAlign::Center);
                page.set_footer(footer);

                // Add content
                page.text()
                    .set_font(Font::TimesRoman, 12.0)
                    .at(100.0, 700.0)
                    .write(&format!("This is the content of chapter {i}"))
                    .unwrap();

                doc.add_page(page);
            }

            // Write to file
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            // Verify file was created
            assert!(file_path.exists());
            let metadata = fs::metadata(&file_path).unwrap();
            assert!(metadata.len() > 1000);

            // Read and verify content
            let content = fs::read(&file_path).unwrap();
            let content_str = String::from_utf8_lossy(&content);

            // PDF was created successfully and has substantial content
            assert!(content.len() > 2000);
            // Verify basic PDF structure
            assert!(content_str.contains("%PDF"));
            assert!(content_str.contains("endobj"));

            // Note: Content may be compressed, so we can't directly check for text strings
            // The important thing is that the PDF was generated without errors
        }

        #[test]
        fn test_header_footer_alignment_integration() {
            use crate::text::{HeaderFooter, TextAlign};

            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("alignment_test.pdf");

            let mut doc = Document::new();

            let mut page = Page::a4();

            // Left-aligned header
            let header = HeaderFooter::new_header("Left Header")
                .with_font(Font::Helvetica, 12.0)
                .with_alignment(TextAlign::Left)
                .with_margin(50.0);
            page.set_header(header);

            // Right-aligned footer
            let footer = HeaderFooter::new_footer("Right Footer - Page {{page_number}}")
                .with_font(Font::Helvetica, 10.0)
                .with_alignment(TextAlign::Right)
                .with_margin(50.0);
            page.set_footer(footer);

            doc.add_page(page);

            // Write to file
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());
        }

        #[test]
        fn test_header_footer_date_time_integration() {
            use crate::text::HeaderFooter;

            let temp_dir = TempDir::new().unwrap();
            let file_path = temp_dir.path().join("date_time_test.pdf");

            let mut doc = Document::new();

            let mut page = Page::a4();

            // Header with date/time
            let header = HeaderFooter::new_header("Report generated on {{date}} at {{time}}")
                .with_font(Font::Helvetica, 11.0);
            page.set_header(header);

            // Footer with year
            let footer =
                HeaderFooter::new_footer("© {{year}} Company Name").with_font(Font::Helvetica, 9.0);
            page.set_footer(footer);

            doc.add_page(page);

            // Write to file
            let mut writer = PdfWriter::new(&file_path).unwrap();
            writer.write_document(&mut doc).unwrap();

            assert!(file_path.exists());

            // Verify the file was created successfully
            let content = fs::read(&file_path).unwrap();
            assert!(content.len() > 500);

            // Verify basic PDF structure
            let content_str = String::from_utf8_lossy(&content);
            assert!(content_str.contains("%PDF"));
            assert!(content_str.contains("endobj"));

            // Note: We can't check for specific text content as it may be compressed
            // The test validates that headers/footers with date placeholders don't cause errors
        }
    }

    // ── Task 8: FontMetricsStore threading through Page ──────────────────────

    #[test]
    fn test_page_a4_default_has_no_metrics_store() {
        let page = Page::a4();
        assert!(
            page.font_metrics_store.is_none(),
            "Page::a4() must not bind a store; binding happens via Document"
        );
    }

    #[test]
    fn test_page_a4_with_metrics_carries_store() {
        use crate::text::metrics::FontMetricsStore;
        let store = FontMetricsStore::new();
        let page = Page::a4_with_metrics(store);
        assert!(page.font_metrics_store.is_some());
    }

    #[test]
    fn test_page_text_flow_propagates_store() {
        use crate::text::metrics::FontMetricsStore;
        let store = FontMetricsStore::new();
        let page = Page::a4_with_metrics(store);
        let flow = page.text_flow();
        assert!(
            flow.font_metrics_store.is_some(),
            "page.text_flow() must propagate the store handle"
        );
    }
}

#[cfg(test)]
mod unit_tests {
    use super::*;
    use crate::graphics::Color;
    use crate::text::Font;

    // ============= Constructor Tests =============

    #[test]
    fn test_new_page_dimensions() {
        let page = Page::new(100.0, 200.0);
        assert_eq!(page.width(), 100.0);
        assert_eq!(page.height(), 200.0);
    }

    #[test]
    fn test_a4_page_dimensions() {
        let page = Page::a4();
        assert_eq!(page.width(), 595.0);
        assert_eq!(page.height(), 842.0);
    }

    #[test]
    fn test_letter_page_dimensions() {
        let page = Page::letter();
        assert_eq!(page.width(), 612.0);
        assert_eq!(page.height(), 792.0);
    }

    #[test]
    fn test_legal_page_dimensions() {
        let page = Page::legal();
        assert_eq!(page.width(), 612.0);
        assert_eq!(page.height(), 1008.0);
    }

    // ============= Margins Tests =============

    #[test]
    fn test_default_margins() {
        let page = Page::a4();
        let margins = page.margins();
        assert_eq!(margins.left, 72.0);
        assert_eq!(margins.right, 72.0);
        assert_eq!(margins.top, 72.0);
        assert_eq!(margins.bottom, 72.0);
    }

    #[test]
    fn test_set_margins() {
        let mut page = Page::a4();
        page.set_margins(10.0, 20.0, 30.0, 40.0);

        let margins = page.margins();
        assert_eq!(margins.left, 10.0);
        assert_eq!(margins.right, 20.0);
        assert_eq!(margins.top, 30.0);
        assert_eq!(margins.bottom, 40.0);
    }

    #[test]
    fn test_content_width() {
        let mut page = Page::new(600.0, 800.0);
        page.set_margins(50.0, 50.0, 0.0, 0.0);
        assert_eq!(page.content_width(), 500.0);
    }

    #[test]
    fn test_content_height() {
        let mut page = Page::new(600.0, 800.0);
        page.set_margins(0.0, 0.0, 100.0, 100.0);
        assert_eq!(page.content_height(), 600.0);
    }

    #[test]
    fn test_content_area() {
        let mut page = Page::new(600.0, 800.0);
        page.set_margins(50.0, 60.0, 70.0, 80.0);

        let (x, y, right, top) = page.content_area();
        assert_eq!(x, 50.0); // left margin
        assert_eq!(y, 80.0); // bottom margin
        assert_eq!(right, 540.0); // page width (600) - right margin (60)
        assert_eq!(top, 730.0); // page height (800) - top margin (70)
    }

    // ============= Graphics Context Tests =============

    #[test]
    fn test_graphics_context_access() {
        let mut page = Page::a4();
        let gc = page.graphics();

        // Test that we can perform basic operations
        gc.move_to(0.0, 0.0);
        gc.line_to(100.0, 100.0);

        // Operations should be recorded
        let ops = gc.get_operations();
        assert!(!ops.is_empty());
    }

    #[test]
    fn test_graphics_operations_chain() {
        let mut page = Page::a4();

        page.graphics()
            .set_fill_color(Color::red())
            .rectangle(10.0, 10.0, 100.0, 50.0)
            .fill();

        let ops = page.graphics().get_operations();
        assert!(ops.contains("re")); // rectangle operator
        assert!(ops.contains("f")); // fill operator
    }

    // ============= Text Context Tests =============

    #[test]
    fn test_text_context_access() {
        let mut page = Page::a4();
        let tc = page.text();

        tc.set_font(Font::Helvetica, 12.0);
        tc.at(100.0, 100.0);

        // Should be able to write text without error
        let result = tc.write("Test text");
        assert!(result.is_ok());
    }

    // Issue #97: Test that get_used_characters combines both contexts
    #[test]
    fn test_get_used_characters_from_text_context() {
        let mut page = Page::a4();

        // Write text via text_context
        page.text().write("ABC").unwrap();

        // Should capture characters from text_context
        let chars = page.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'A'));
        assert!(chars.contains(&'B'));
        assert!(chars.contains(&'C'));
    }

    #[test]
    fn test_get_used_characters_combines_both_contexts() {
        let mut page = Page::a4();

        // Write text via text_context
        page.text().write("AB").unwrap();

        // Write text via graphics_context
        let _ = page.graphics().draw_text("CD", 100.0, 100.0);

        // Should capture characters from both contexts
        let chars = page.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'A'));
        assert!(chars.contains(&'B'));
        assert!(chars.contains(&'C'));
        assert!(chars.contains(&'D'));
    }

    #[test]
    fn test_get_used_characters_cjk_via_text_context() {
        let mut page = Page::a4();

        // Write CJK text via text_context (the bug scenario from issue #97)
        page.text()
            .set_font(Font::Custom("NotoSansCJK".to_string()), 12.0);
        page.text().write("中文").unwrap();

        let chars = page.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'中'));
        assert!(chars.contains(&'文'));
    }

    #[test]
    fn test_text_flow_creation() {
        let page = Page::a4();
        let text_flow = page.text_flow();

        // Test that text flow is created without panic
        // TextFlowContext doesn't expose its internal state
        // but we can verify it's created correctly
        let _ = text_flow; // Just ensure it can be created
    }

    // ============= Image Tests =============

    #[test]
    fn test_add_image() {
        let mut page = Page::a4();

        // Create a minimal JPEG image
        let image_data = vec![
            0xFF, 0xD8, // SOI marker
            0xFF, 0xC0, // SOF0 marker
            0x00, 0x11, // Length
            0x08, // Precision
            0x00, 0x10, // Height
            0x00, 0x10, // Width
            0x03, // Components
            0x01, 0x11, 0x00, // Component 1
            0x02, 0x11, 0x00, // Component 2
            0x03, 0x11, 0x00, // Component 3
            0xFF, 0xD9, // EOI marker
        ];

        let image = Image::from_jpeg_data(image_data).unwrap();
        page.add_image("test_image", image);

        // Image should be stored
        assert!(page.images.contains_key("test_image"));
    }

    #[test]
    fn test_draw_image_simple() {
        let mut page = Page::a4();

        // Create and add image
        let image_data = vec![
            0xFF, 0xD8, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x10, 0x00, 0x10, 0x03, 0x01, 0x11,
            0x00, 0x02, 0x11, 0x00, 0x03, 0x11, 0x00, 0xFF, 0xD9,
        ];

        let image = Image::from_jpeg_data(image_data).unwrap();
        page.add_image("img1", image);

        // Draw the image
        let result = page.draw_image("img1", 100.0, 100.0, 200.0, 200.0);
        assert!(result.is_ok());
    }

    // ============= Annotations Tests =============

    #[test]
    fn test_add_annotation() {
        use crate::annotations::{Annotation, AnnotationType};
        use crate::geometry::{Point, Rectangle};

        let mut page = Page::a4();
        let rect = Rectangle::new(Point::new(100.0, 100.0), Point::new(200.0, 150.0));
        let annotation = Annotation::new(AnnotationType::Text, rect);

        page.add_annotation(annotation);
        assert_eq!(page.annotations().len(), 1);
    }

    #[test]
    fn test_annotations_mut() {
        use crate::annotations::{Annotation, AnnotationType};
        use crate::geometry::{Point, Rectangle};

        let mut page = Page::a4();
        let _rect = Rectangle::new(Point::new(100.0, 100.0), Point::new(200.0, 150.0));

        // Add multiple annotations
        for i in 0..3 {
            let annotation = Annotation::new(
                AnnotationType::Text,
                Rectangle::new(
                    Point::new(100.0 + i as f64 * 10.0, 100.0),
                    Point::new(200.0 + i as f64 * 10.0, 150.0),
                ),
            );
            page.add_annotation(annotation);
        }

        // Modify annotations
        let annotations = page.annotations_mut();
        annotations.clear();
        assert_eq!(page.annotations().len(), 0);
    }

    // ============= Form Widget Tests =============

    #[test]
    fn test_add_form_widget() {
        use crate::forms::Widget;
        use crate::geometry::{Point, Rectangle};

        let mut page = Page::a4();
        let rect = Rectangle::new(Point::new(100.0, 100.0), Point::new(200.0, 120.0));
        let widget = Widget::new(rect);

        let obj_ref = page.add_form_widget(widget);
        assert_eq!(obj_ref.number(), 0);
        assert_eq!(obj_ref.generation(), 0);

        // Annotations should include the widget
        assert_eq!(page.annotations().len(), 1);
    }

    // ============= Header/Footer Tests =============

    #[test]
    fn test_set_header() {
        use crate::text::HeaderFooter;

        let mut page = Page::a4();
        let header = HeaderFooter::new_header("Test Header");

        page.set_header(header);
        assert!(page.header().is_some());

        if let Some(h) = page.header() {
            assert_eq!(h.content(), "Test Header");
        }
    }

    #[test]
    fn test_set_footer() {
        use crate::text::HeaderFooter;

        let mut page = Page::a4();
        let footer = HeaderFooter::new_footer("Page {{page}} of {{total}}");

        page.set_footer(footer);
        assert!(page.footer().is_some());

        if let Some(f) = page.footer() {
            assert_eq!(f.content(), "Page {{page}} of {{total}}");
        }
    }

    #[test]
    fn test_header_footer_rendering() {
        use crate::text::HeaderFooter;

        let mut page = Page::a4();

        // Set both header and footer
        page.set_header(HeaderFooter::new_header("Header"));
        page.set_footer(HeaderFooter::new_footer("Footer"));

        // Generate content with header/footer
        let result = page.generate_content_with_page_info(Some(1), Some(1), None);
        assert!(result.is_ok());

        let content = result.unwrap();
        assert!(!content.is_empty());
    }

    // ============= Table Tests =============

    #[test]
    fn test_add_table() {
        use crate::text::Table;

        let mut page = Page::a4();
        let mut table = Table::with_equal_columns(2, 200.0);

        // Add some rows
        table
            .add_row(vec!["Cell 1".to_string(), "Cell 2".to_string()])
            .unwrap();
        table
            .add_row(vec!["Cell 3".to_string(), "Cell 4".to_string()])
            .unwrap();

        let result = page.add_table(&table);
        assert!(result.is_ok());
    }

    // ============= Content Generation Tests =============

    #[test]
    fn test_generate_operations_empty() {
        let page = Page::a4();
        // Page doesn't have generate_operations, use graphics_context
        let ops = page.graphics_context.generate_operations();

        // Even empty page should have valid PDF operations
        assert!(ops.is_ok());
    }

    #[test]
    fn test_generate_operations_with_graphics() {
        let mut page = Page::a4();

        page.graphics().rectangle(50.0, 50.0, 100.0, 100.0).fill();

        // Page doesn't have generate_operations, use graphics_context
        let ops = page.graphics_context.generate_operations();
        assert!(ops.is_ok());

        let content = ops.unwrap();
        let content_str = String::from_utf8_lossy(&content);
        assert!(content_str.contains("re")); // rectangle
        assert!(content_str.contains("f")); // fill
    }

    #[test]
    fn test_generate_operations_with_text() {
        let mut page = Page::a4();

        page.text()
            .set_font(Font::Helvetica, 12.0)
            .at(100.0, 700.0)
            .write("Hello")
            .unwrap();

        // Text operations are in text_context, not graphics_context
        let ops = page.text_context.generate_operations();
        assert!(ops.is_ok());

        let content = ops.unwrap();
        let content_str = String::from_utf8_lossy(&content);
        assert!(content_str.contains("BT")); // Begin text
        assert!(content_str.contains("ET")); // End text
    }

    // ============= Edge Cases and Error Handling =============

    #[test]
    fn test_negative_margins() {
        let mut page = Page::a4();
        page.set_margins(-10.0, -20.0, -30.0, -40.0);

        // Negative margins should still work (might be intentional)
        let margins = page.margins();
        assert_eq!(margins.left, -10.0);
        assert_eq!(margins.right, -20.0);
    }

    #[test]
    fn test_zero_dimensions() {
        let page = Page::new(0.0, 0.0);
        assert_eq!(page.width(), 0.0);
        assert_eq!(page.height(), 0.0);

        // Content area with default margins would be negative
        let (_, _, width, height) = page.content_area();
        assert!(width < 0.0);
        assert!(height < 0.0);
    }

    #[test]
    fn test_huge_dimensions() {
        let page = Page::new(1_000_000.0, 1_000_000.0);
        assert_eq!(page.width(), 1_000_000.0);
        assert_eq!(page.height(), 1_000_000.0);
    }

    #[test]
    fn test_draw_nonexistent_image() {
        let mut page = Page::a4();

        // Try to draw an image that wasn't added
        let result = page.draw_image("nonexistent", 100.0, 100.0, 200.0, 200.0);

        // Should fail gracefully
        assert!(result.is_err());
    }

    #[test]
    fn test_clone_page() {
        let mut page = Page::a4();
        page.set_margins(10.0, 20.0, 30.0, 40.0);

        page.graphics().rectangle(50.0, 50.0, 100.0, 100.0).fill();

        let cloned = page.clone();
        assert_eq!(cloned.width(), page.width());
        assert_eq!(cloned.height(), page.height());
        assert_eq!(cloned.margins().left, page.margins().left);
    }

    #[test]
    fn test_page_from_parsed_basic() {
        use crate::parser::objects::PdfDictionary;
        use crate::parser::page_tree::ParsedPage;

        // Create a test parsed page
        let parsed_page = ParsedPage {
            obj_ref: (1, 0),
            dict: PdfDictionary::new(),
            inherited_resources: None,
            media_box: [0.0, 0.0, 612.0, 792.0], // US Letter
            crop_box: None,
            rotation: 0,
            annotations: None,
        };

        // Convert to writable page
        let page = Page::from_parsed(&parsed_page).unwrap();

        // Verify dimensions
        assert_eq!(page.width(), 612.0);
        assert_eq!(page.height(), 792.0);
        assert_eq!(page.get_rotation(), 0);
    }

    #[test]
    fn test_page_from_parsed_with_rotation() {
        use crate::parser::objects::PdfDictionary;
        use crate::parser::page_tree::ParsedPage;

        // Create a test parsed page with 90-degree rotation
        let parsed_page = ParsedPage {
            obj_ref: (1, 0),
            dict: PdfDictionary::new(),
            inherited_resources: None,
            media_box: [0.0, 0.0, 595.0, 842.0], // A4
            crop_box: None,
            rotation: 90,
            annotations: None,
        };

        // Convert to writable page
        let page = Page::from_parsed(&parsed_page).unwrap();

        // Verify rotation was preserved
        assert_eq!(page.get_rotation(), 90);
        assert_eq!(page.width(), 595.0);
        assert_eq!(page.height(), 842.0);

        // Verify effective dimensions (rotated)
        assert_eq!(page.effective_width(), 842.0);
        assert_eq!(page.effective_height(), 595.0);
    }

    #[test]
    fn test_page_from_parsed_with_cropbox() {
        use crate::parser::objects::PdfDictionary;
        use crate::parser::page_tree::ParsedPage;

        // Create a test parsed page with CropBox
        let parsed_page = ParsedPage {
            obj_ref: (1, 0),
            dict: PdfDictionary::new(),
            inherited_resources: None,
            media_box: [0.0, 0.0, 612.0, 792.0],
            crop_box: Some([10.0, 10.0, 602.0, 782.0]),
            rotation: 0,
            annotations: None,
        };

        // Convert to writable page
        let page = Page::from_parsed(&parsed_page).unwrap();

        // CropBox doesn't affect page dimensions (only visible area)
        assert_eq!(page.width(), 612.0);
        assert_eq!(page.height(), 792.0);
    }

    #[test]
    fn test_page_from_parsed_small_mediabox() {
        use crate::parser::objects::PdfDictionary;
        use crate::parser::page_tree::ParsedPage;

        // Create a test parsed page with custom small dimensions
        let parsed_page = ParsedPage {
            obj_ref: (1, 0),
            dict: PdfDictionary::new(),
            inherited_resources: None,
            media_box: [0.0, 0.0, 200.0, 300.0],
            crop_box: None,
            rotation: 0,
            annotations: None,
        };

        // Convert to writable page
        let page = Page::from_parsed(&parsed_page).unwrap();

        assert_eq!(page.width(), 200.0);
        assert_eq!(page.height(), 300.0);
    }

    #[test]
    fn test_page_from_parsed_non_zero_origin() {
        use crate::parser::objects::PdfDictionary;
        use crate::parser::page_tree::ParsedPage;

        // Create a test parsed page with non-zero origin
        let parsed_page = ParsedPage {
            obj_ref: (1, 0),
            dict: PdfDictionary::new(),
            inherited_resources: None,
            media_box: [10.0, 20.0, 610.0, 820.0], // Offset origin
            crop_box: None,
            rotation: 0,
            annotations: None,
        };

        // Convert to writable page
        let page = Page::from_parsed(&parsed_page).unwrap();

        // Width and height should be calculated correctly
        assert_eq!(page.width(), 600.0); // 610 - 10
        assert_eq!(page.height(), 800.0); // 820 - 20
    }

    #[test]
    fn test_page_rotation() {
        let mut page = Page::a4();

        // Test default rotation
        assert_eq!(page.get_rotation(), 0);

        // Test setting valid rotations
        page.set_rotation(90);
        assert_eq!(page.get_rotation(), 90);

        page.set_rotation(180);
        assert_eq!(page.get_rotation(), 180);

        page.set_rotation(270);
        assert_eq!(page.get_rotation(), 270);

        page.set_rotation(360);
        assert_eq!(page.get_rotation(), 0);

        // Test rotation normalization
        page.set_rotation(45);
        assert_eq!(page.get_rotation(), 90);

        page.set_rotation(135);
        assert_eq!(page.get_rotation(), 180);

        page.set_rotation(-90);
        assert_eq!(page.get_rotation(), 270);
    }

    #[test]
    fn test_effective_dimensions() {
        let mut page = Page::new(600.0, 800.0);

        // No rotation - same dimensions
        assert_eq!(page.effective_width(), 600.0);
        assert_eq!(page.effective_height(), 800.0);

        // 90 degree rotation - swapped dimensions
        page.set_rotation(90);
        assert_eq!(page.effective_width(), 800.0);
        assert_eq!(page.effective_height(), 600.0);

        // 180 degree rotation - same dimensions
        page.set_rotation(180);
        assert_eq!(page.effective_width(), 600.0);
        assert_eq!(page.effective_height(), 800.0);

        // 270 degree rotation - swapped dimensions
        page.set_rotation(270);
        assert_eq!(page.effective_width(), 800.0);
        assert_eq!(page.effective_height(), 600.0);
    }

    #[test]
    fn test_rotation_in_pdf_dict() {
        let mut page = Page::a4();

        // No rotation should not include Rotate field
        let dict = page.to_dict();
        assert!(dict.get("Rotate").is_none());

        // With rotation should include Rotate field
        page.set_rotation(90);
        let dict = page.to_dict();
        assert_eq!(dict.get("Rotate"), Some(&Object::Integer(90)));

        page.set_rotation(270);
        let dict = page.to_dict();
        assert_eq!(dict.get("Rotate"), Some(&Object::Integer(270)));
    }
}

/// Layout manager for intelligent positioning of elements on a page
///
/// This manager handles automatic positioning of tables, images, and other elements
/// using different coordinate systems while preventing overlaps and managing page flow.
#[derive(Debug)]
pub struct LayoutManager {
    /// Coordinate system being used
    pub coordinate_system: crate::coordinate_system::CoordinateSystem,
    /// Current Y position for next element
    pub current_y: f64,
    /// Page dimensions
    pub page_width: f64,
    pub page_height: f64,
    /// Page margins
    pub margins: Margins,
    /// Spacing between elements
    pub element_spacing: f64,
}

impl LayoutManager {
    /// Create a new layout manager for the given page
    pub fn new(page: &Page, coordinate_system: crate::coordinate_system::CoordinateSystem) -> Self {
        let current_y = match coordinate_system {
            crate::coordinate_system::CoordinateSystem::PdfStandard => {
                // PDF coordinates: start from top (high Y value)
                page.height() - page.margins().top
            }
            crate::coordinate_system::CoordinateSystem::ScreenSpace => {
                // Screen coordinates: start from top (low Y value)
                page.margins().top
            }
            crate::coordinate_system::CoordinateSystem::Custom(_) => {
                // For custom systems, start conservatively in the middle
                page.height() / 2.0
            }
        };

        Self {
            coordinate_system,
            current_y,
            page_width: page.width(),
            page_height: page.height(),
            margins: page.margins().clone(),
            element_spacing: 10.0,
        }
    }

    /// Set custom spacing between elements
    pub fn with_element_spacing(mut self, spacing: f64) -> Self {
        self.element_spacing = spacing;
        self
    }

    /// Check if an element of given height will fit on the current page
    pub fn will_fit(&self, element_height: f64) -> bool {
        let required_space = element_height + self.element_spacing;

        match self.coordinate_system {
            crate::coordinate_system::CoordinateSystem::PdfStandard => {
                // In PDF coords, we subtract height and check against bottom margin
                self.current_y - required_space >= self.margins.bottom
            }
            crate::coordinate_system::CoordinateSystem::ScreenSpace => {
                // In screen coords, we add height and check against page height
                self.current_y + required_space <= self.page_height - self.margins.bottom
            }
            crate::coordinate_system::CoordinateSystem::Custom(_) => {
                // Conservative check for custom coordinate systems
                required_space <= (self.page_height - self.margins.top - self.margins.bottom) / 2.0
            }
        }
    }

    /// Get the current available space remaining on the page
    pub fn remaining_space(&self) -> f64 {
        match self.coordinate_system {
            crate::coordinate_system::CoordinateSystem::PdfStandard => {
                (self.current_y - self.margins.bottom).max(0.0)
            }
            crate::coordinate_system::CoordinateSystem::ScreenSpace => {
                (self.page_height - self.margins.bottom - self.current_y).max(0.0)
            }
            crate::coordinate_system::CoordinateSystem::Custom(_) => {
                self.page_height / 2.0 // Conservative estimate
            }
        }
    }

    /// Reserve space for an element and return its Y position
    ///
    /// Returns `None` if the element doesn't fit on the current page.
    /// If it fits, returns the Y coordinate where the element should be placed
    /// and updates the internal current_y for the next element.
    pub fn add_element(&mut self, element_height: f64) -> Option<f64> {
        if !self.will_fit(element_height) {
            return None;
        }

        let position_y = match self.coordinate_system {
            crate::coordinate_system::CoordinateSystem::PdfStandard => {
                // Position element at current_y (top of element)
                // Then move current_y down by element height + spacing
                let y_position = self.current_y - element_height;
                self.current_y = y_position - self.element_spacing;
                self.current_y + element_height // Return the bottom Y of the element area
            }
            crate::coordinate_system::CoordinateSystem::ScreenSpace => {
                // Position element at current_y (top of element)
                // Then move current_y down by element height + spacing
                let y_position = self.current_y;
                self.current_y += element_height + self.element_spacing;
                y_position
            }
            crate::coordinate_system::CoordinateSystem::Custom(_) => {
                // Simple implementation for custom coordinate systems
                let y_position = self.current_y;
                self.current_y -= element_height + self.element_spacing;
                y_position
            }
        };

        Some(position_y)
    }

    /// Reset the layout manager for a new page
    pub fn new_page(&mut self) {
        self.current_y = match self.coordinate_system {
            crate::coordinate_system::CoordinateSystem::PdfStandard => {
                self.page_height - self.margins.top
            }
            crate::coordinate_system::CoordinateSystem::ScreenSpace => self.margins.top,
            crate::coordinate_system::CoordinateSystem::Custom(_) => self.page_height / 2.0,
        };
    }

    /// Get the X position for centering an element of given width
    pub fn center_x(&self, element_width: f64) -> f64 {
        let available_width = self.page_width - self.margins.left - self.margins.right;
        self.margins.left + (available_width - element_width) / 2.0
    }

    /// Get the left margin X position
    pub fn left_x(&self) -> f64 {
        self.margins.left
    }

    /// Get the right margin X position minus element width
    pub fn right_x(&self, element_width: f64) -> f64 {
        self.page_width - self.margins.right - element_width
    }
}

#[cfg(test)]
mod layout_manager_tests {
    use super::*;
    use crate::coordinate_system::CoordinateSystem;

    #[test]
    fn test_layout_manager_pdf_standard() {
        let page = Page::a4(); // 595 x 842
        let mut layout = LayoutManager::new(&page, CoordinateSystem::PdfStandard);

        // Check initial position (should be near top in PDF coords)
        // A4 height is 842, with default margin of 72, so current_y should be 842 - 72 = 770
        assert!(layout.current_y > 750.0); // Near top of A4, adjusted for actual margins

        // Add an element
        let element_height = 100.0;
        let position = layout.add_element(element_height);

        assert!(position.is_some());
        let y_pos = position.unwrap();
        assert!(y_pos > 700.0); // Should be positioned high up

        // Current Y should have moved down
        assert!(layout.current_y < y_pos);
    }

    #[test]
    fn test_layout_manager_screen_space() {
        let page = Page::a4();
        let mut layout = LayoutManager::new(&page, CoordinateSystem::ScreenSpace);

        // Check initial position (should be near top in screen coords)
        assert!(layout.current_y < 100.0); // Near top margin

        // Add an element
        let element_height = 100.0;
        let position = layout.add_element(element_height);

        assert!(position.is_some());
        let y_pos = position.unwrap();
        assert!(y_pos < 100.0); // Should be positioned near top

        // Current Y should have moved down (increased)
        assert!(layout.current_y > y_pos);
    }

    #[test]
    fn test_layout_manager_overflow() {
        let page = Page::a4();
        let mut layout = LayoutManager::new(&page, CoordinateSystem::PdfStandard);

        // Try to add an element that's too large
        let huge_element = 900.0; // Larger than page height
        let position = layout.add_element(huge_element);

        assert!(position.is_none()); // Should not fit

        // Fill the page with smaller elements
        let mut count = 0;
        while layout.add_element(50.0).is_some() {
            count += 1;
            if count > 100 {
                break;
            } // Safety valve
        }

        // Should have added multiple elements
        assert!(count > 5);

        // Next element should not fit
        assert!(layout.add_element(50.0).is_none());
    }

    #[test]
    fn test_layout_manager_centering() {
        let page = Page::a4();
        let layout = LayoutManager::new(&page, CoordinateSystem::PdfStandard);

        let element_width = 200.0;
        let center_x = layout.center_x(element_width);

        // Should be centered considering margins
        let expected_center = page.margins().left
            + (page.width() - page.margins().left - page.margins().right - element_width) / 2.0;
        assert_eq!(center_x, expected_center);
    }
}