//! CSS Paged Media page decoration: headers, footers, margin boxes, and counters.

//!

//! This module is the canonical home for paged-media page *decoration*. It provides:

//!

//! - `FakePageConfig` / `HeaderFooterConfig` — programmatic header/footer setup

//!   (a temporary interface until full CSS `@page` rule parsing exists)

//! - `MarginBoxContent` / `CounterFormat` — the CSS GCPM margin-box content model and

//!   page-counter number formatting (formatting delegates to `super::counters`)

//! - `PageInfo` — per-page metadata passed to content generators

//! - `TableHeaderInfo` / `TableHeaderTracker` — repeated table headers across pages

//!

//! The actual page *splitting* is performed by the display-list slicer

//! (`paginate_display_list_with_slicer_and_breaks` in `super::display_list`), which

//! consumes `HeaderFooterConfig` via its `SlicerConfig`. The continuous-vs-paged media

//! decision and page geometry are carried by `crate::paged::FragmentationContext`, and

//! CSS break properties are read via `super::getters` (`get_break_before`,

//! `get_break_after`, `is_forced_page_break`).

//!

//! **Note:** Running elements, named strings, and per-page `@page` selectors are not

//! yet implemented; only page counters and header/footer configuration are functional.

//!

//! See: <https://www.w3.org/TR/css-gcpm-3>/

use std::sync::Arc;

use azul_css::props::basic::ColorU;

/// Content that can appear in a page margin box.

///

/// This enum represents the various types of content that CSS GCPM

/// allows in margin boxes.

#[derive(Clone)]

pub enum MarginBoxContent {

    /// Empty margin box

    None,

    /// A running element referenced by name: `content: element(header)`

    RunningElement(String),

    /// A named string: `content: string(chapter)`

    NamedString(String),

    /// Page counter: `content: counter(page)`

    PageCounter,

    /// Total pages counter: `content: counter(pages)`

    PagesCounter,

    /// Page counter with format: `content: counter(page, lower-roman)`

    PageCounterFormatted { format: CounterFormat },

    /// Combined content (e.g., "Page " counter(page) " of " counter(pages))

    Combined(Vec<MarginBoxContent>),

    /// Literal text

    Text(String),

    /// Custom callback for dynamic content generation

    Custom(Arc<dyn Fn(PageInfo) -> String + Send + Sync>),

}

impl std::fmt::Debug for MarginBoxContent {

        }

}

/// Counter formatting styles (subset of CSS list-style-type).

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum CounterFormat {

    Decimal,

    DecimalLeadingZero,

    LowerRoman,

    UpperRoman,

    LowerAlpha,

    UpperAlpha,

    LowerGreek,

}

impl Default for CounterFormat {

}

impl CounterFormat {

    /// Format a number according to this counter style.

        use super::counters::{to_alphabetic, to_greek, to_roman};

        }

}

/// Information about the current page, passed to content generators.

#[derive(Debug, Clone, Copy)]

#[allow(clippy::struct_excessive_bools)] // independent page-position flags (first/last/left/right)

pub struct PageInfo {

    /// Current page number (1-indexed for display)

    pub page_number: usize,

    /// Total number of pages (may be 0 if unknown during first pass)

    pub total_pages: usize,

    /// Whether this is the first page

    pub is_first: bool,

    /// Whether this is the last page

    pub is_last: bool,

    /// Whether this is a left (verso) page (for duplex printing)

    pub is_left: bool,

    /// Whether this is a right (recto) page

    pub is_right: bool,

    /// Whether this is a blank page (inserted for left/right alignment)

    pub is_blank: bool,

}

impl PageInfo {

    /// Create `PageInfo` for a specific page.

        Self {

            is_blank: false,

        }

}

/// Default height for page headers and footers (in points).

const DEFAULT_HEADER_FOOTER_HEIGHT: f32 = 30.0;

/// Default font size for header/footer text (in points).

const DEFAULT_HEADER_FOOTER_FONT_SIZE: f32 = 10.0;

/// Configuration for page headers and footers.

///

/// This is a simplified interface for the common case of adding

/// headers and footers, consumed by the display-list slicer via its `SlicerConfig`.

#[derive(Debug, Clone)]

pub struct HeaderFooterConfig {

    /// Whether to show a header on each page

    pub show_header: bool,

    /// Whether to show a footer on each page

    pub show_footer: bool,

    /// Height of the header area (if shown)

    pub header_height: f32,

    /// Height of the footer area (if shown)  

    pub footer_height: f32,

    /// Content generator for the header

    pub header_content: MarginBoxContent,

    /// Content generator for the footer

    pub footer_content: MarginBoxContent,

    /// Font size for header/footer text

    pub font_size: f32,

    /// Text color for header/footer

    pub text_color: ColorU,

    /// Whether to skip header/footer on first page

    pub skip_first_page: bool,

}

impl Default for HeaderFooterConfig {

}

impl HeaderFooterConfig {

    /// Create a config with page numbers in the footer.

    /// Create a config with page numbers in both header and footer.

    /// Set custom header text.

    #[must_use]

    /// Set custom footer text.

    #[must_use]

    /// Generate the text content for a margin box given page info.

    // `&self` is only reached via the recursive Combined arm; it is kept because this is a

    // public method and converting to an associated fn would break the `x.generate_content(..)` API.

    #[allow(clippy::only_used_in_recursion)]

            MarginBoxContent::PagesCounter => {

                } else {

                }

            }

                // TODO: Look up named string from document context

            }

                // Running elements are rendered as display items, not text

            }

        }

    /// Get the header text for a specific page.

    /// Get the footer text for a specific page.

}

/// Temporary configuration for page headers/footers without CSS `@page` parsing.

///

/// Provides programmatic control over page decoration until full CSS `@page`

/// rule support is implemented.

///

/// ## Supported Features

///

/// - Page numbers in header and/or footer

/// - Custom text in header and/or footer

/// - Number format (decimal, roman numerals, alphabetic, greek)

/// - Skip first page option

///

/// ## Example

///

/// ```rust

/// use azul_layout::solver3::pagination::FakePageConfig;

///

/// let config = FakePageConfig::new()

///     .with_footer_page_numbers()

///     .with_header_text("My Document")

///     .skip_first_page(true);

///

/// let header_footer = config.to_header_footer_config();

/// ```

#[derive(Debug, Clone)]

#[allow(clippy::struct_excessive_bools)] // independent header/footer toggle flags

pub struct FakePageConfig {

    /// Show header on pages

    pub show_header: bool,

    /// Show footer on pages

    pub show_footer: bool,

    /// Header text (static text, or None for page numbers only)

    pub header_text: Option<String>,

    /// Footer text (static text, or None for page numbers only)

    pub footer_text: Option<String>,

    /// Include page number in header

    pub header_page_number: bool,

    /// Include page number in footer

    pub footer_page_number: bool,

    /// Include total pages count ("of Y") in header

    pub header_total_pages: bool,

    /// Include total pages count ("of Y") in footer

    pub footer_total_pages: bool,

    /// Number format for page counters

    pub number_format: CounterFormat,

    /// Skip header/footer on first page

    pub skip_first_page: bool,

    /// Header height in points

    pub header_height: f32,

    /// Footer height in points

    pub footer_height: f32,

    /// Font size for header/footer text

    pub font_size: f32,

    /// Text color for header/footer

    pub text_color: ColorU,

    /// Break-awareness policy for pagination (all-off default = plain

    /// interval slicing; printpdf flips the flags on with a changelog entry).

    pub break_policy: crate::solver3::page_breaks::BreakPolicy,

    /// office-suite-style per-page setup sequence (`None` = uniform pages from

    /// the fields above).

    pub page_sequence: Option<PageSequence>,

}

impl Default for FakePageConfig {

}

impl FakePageConfig {

    /// Create a new empty configuration (no headers/footers).

    /// Enable footer with "Page X of Y" format.

    /// Enable header with "Page X" format.

    /// Enable both header and footer with page numbers.

    /// Set custom header text.

    #[must_use]

    /// Set custom footer text.

    #[must_use]

    /// Set the number format for page counters.

    /// Skip header/footer on the first page.

    /// Set header height.

    /// Set footer height.

    /// Set font size for header/footer text.

    /// Set text color for header/footer.

    /// Convert this fake config to the internal `HeaderFooterConfig`.

    ///

    /// This is the bridge between the user-facing API and the internal

    /// pagination engine.

    /// Build the `MarginBoxContent` for the header.

        )

    /// Build the `MarginBoxContent` for the footer.

        )

    /// Shared helper for building header/footer margin box content.

        } else {

        }

}

/// Information about a table that may need header repetition.

#[derive(Debug, Clone)]

pub struct TableHeaderInfo {

    /// The table's node index in the layout tree

    pub table_node_index: usize,

    /// The Y position where the table starts

    pub table_start_y: f32,

    /// The Y position where the table ends

    pub table_end_y: f32,

    /// The thead's display list items (captured during initial render)

    pub thead_items: Vec<super::display_list::DisplayListItem>,

    /// Height of the thead

    pub thead_height: f32,

    /// The Y position of the thead relative to table start

    pub thead_offset_y: f32,

}

/// Context for tracking table headers across pages.

#[derive(Debug, Default, Clone)]

pub struct TableHeaderTracker {

    /// All tables with theads that might need repetition

    pub tables: Vec<TableHeaderInfo>,

}

impl TableHeaderTracker {

    /// Register a table's thead for potential repetition.

    /// Get theads that should be repeated on a specific page.

    ///

    /// Returns the thead items that need to be injected at the top of the page,

    /// along with the Y offset where they should appear.

    ///

    /// Kept for compatibility: offsets are the LEGACY vertical stack (each

    /// thead below the previous). The slicer now uses

    /// [`Self::straddling_tables_for_page`] and places theads X-aware

    /// (side-by-side tables keep their own column, nested ones stack).

    /// The tables whose content STRADDLES this page top (started strictly

    /// above, still continuing) — the ones whose thead must repeat here.

    /// Two SIBLING tables can only both straddle when they sit side by side

    /// (or nested); the slicer decides placement from their x-extents.

        // Page 0 never repeats anything (the original thead is on it), and a

        // degenerate/inverted page has no room for a header.

}

/// Page margins in logical px (CSS order).

#[derive(Debug, Clone, Copy, PartialEq, Default)]

pub struct PageMargins {

    pub top: f32,

    pub right: f32,

    pub bottom: f32,

    pub left: f32,

}

/// ONE page's complete setup — size (orientation = which side is longer),

/// margins, and header/footer decoration. The classic office suites "page setup" unit.

#[derive(Debug, Clone)]

pub struct PageSetup {

    /// Full page size INCLUDING margins (swap the sides for landscape).

    pub page_size: azul_core::geom::LogicalSize,

    pub margins: PageMargins,

    /// Header/footer decoration for pages using this setup (heights count

    /// against the content area; text/numbering render per page).

    pub header_footer: HeaderFooterConfig,

}

impl PageSetup {

    /// Content height = page height − vertical margins − active header/footer.

    #[must_use]

        } else {

        };

        } else {

        };

    /// Content width = page width − horizontal margins.

    #[must_use]

}

/// The document's page-setup SEQUENCE: one default + sparse overrides.

///

/// The classic office suites model ("default = A4 portrait, 2cm footer, 1.5cm margins;

/// page 345 is landscape"). Resolution precedence per page:

/// explicit override > first-page setup > odd/even parity > default.

///

/// pdf2html maps its HTML dataset annotations (e.g. `data-az-page-*` on

/// section elements) + CSS onto this structure and hands it to the paged

/// pipeline.

///

/// FRAGMENTAINER-FLOW STAGING: per-page HEIGHT differences are fully live

/// (the break forward-pass consumes per-index content heights — same

/// mechanism as the repeated-thead reserve). Per-page WIDTH differences

/// (true landscape re-wrap) require laying out INTO the fragmentainer

/// sequence with re-measure at boundaries — an engine stage; until then a

/// non-uniform width falls back to the default width and says so once.

#[derive(Debug, Clone)]

pub struct PageSequence {

    pub default: PageSetup,

    /// Explicit per-page overrides (0-based page index). Strongest.

    pub overrides: std::collections::BTreeMap<usize, PageSetup>,

    /// the classic office-suite "different first page".

    pub first_page: Option<PageSetup>,

    /// the classic office-suite "different odd & even": odd = 0-based EVEN indices (page 1,

    /// 3, … in 1-based speech) — stored by the 1-based convention users

    /// think in: `odd_pages` applies to 1-based odd page numbers.

    pub odd_pages: Option<PageSetup>,

    pub even_pages: Option<PageSetup>,

}

impl PageSequence {

    /// A uniform sequence (every page identical).

    #[must_use]

    /// The setup for 0-based page `index`:

    /// override > first > odd/even (1-based parity) > default.

    #[must_use]

    /// Whether every page shares the default's content WIDTH (the

    /// fragmentainer-flow precondition for the current single-measure

    /// layout). Announces the degradation once when violated.

    #[must_use]

            static ANNOUNCE: std::sync::Once = std::sync::Once::new();

                );

    /// Partition the page sequence into WIDTH SECTIONS — maximal runs of

    /// consecutive pages sharing a content width. This is the fragmentainer

    /// unit for width re-wrap: content lays out ONCE per section at that

    /// section's width and is cut at the section boundary (the classic office suites model,

    /// where page setup changes at section breaks).

    ///

    /// The last section is open-ended (`page_count: None`): once every

    /// per-page override / parity variation has been passed, the width is

    /// constant forever. `max_scan` bounds the scan (parity alternation

    /// yields one section per page up to the bound — such sequences degrade

    /// to per-page sections and remain correct, just not cheap).

    #[must_use]

        // Past the largest explicit override AND the first page AND parity

        // variation, the width can still alternate (odd/even) — only treat

        // the run as final when parity widths agree with the default.

        };

                }

            }

            // Stable tail: no more overrides ahead, first-page passed, parity

            // constant — the current section runs forever.

        }

}

/// A maximal run of consecutive pages sharing a content width — the

/// fragmentainer unit for width re-wrap. See [`PageSequence::width_sections`].

#[derive(Debug, Clone, Copy, PartialEq)]

pub struct WidthSection {

    /// 0-based index of the first page of the run.

    pub first_page: usize,

    /// Number of pages in the run; `None` = open-ended (runs to the end of

    /// the document).

    pub page_count: Option<usize>,

    pub content_width: f32,

}

/// Capture every table's `<thead>` from the master display list so the

/// slicer can repeat it on continuation pages.

///

/// The REGISTRATION side the tracker always lacked (its

/// `register_table_header` had zero production callers, so

/// `repeat_table_headers` could never do anything).

///

/// Detection is structural: `NodeType::THead` nodes and their owning

/// `NodeType::Table` ancestor; geometry comes from the display list via

/// `node_mapping` (thead items are stored REBASED to thead-local Y, which is

/// what the paginate-time `offset_display_item_y(+page offset)` expects).

#[must_use]

    use azul_core::dom::{NodeId, NodeType};

    use std::collections::BTreeMap;

    // Per table: bounds union; per (table with thead): thead item indices +

    // thead bounds union.

    struct Acc {

        table_top: f32,

        table_bottom: f32,

        thead_top: f32,

        thead_bottom: f32,

        thead_items: Vec<usize>,

    }

    // Memoized classification: which table / thead subtree (if any) a node

    // belongs to.

                Some(NodeType::Table) => {

                }

            }

        }

        };

    }

        // Rebase the thead's items to thead-local Y (paginate re-offsets

        // them to each continuation page's top).

                )

    }

/// The vertical ranges of every table ROW (`<tr>`), for

/// `BreakPolicy::atomic_table_rows` (a break may not slice a row).

#[must_use]

    use azul_core::dom::{NodeId, NodeType};

    use std::collections::BTreeMap;

                Some(NodeType::Tr) => {

                }

            }

        }

        };

    }

#[cfg(test)]

mod autotest_generated {

    use std::sync::atomic::{AtomicUsize, Ordering};

    use super::super::display_list::DisplayListItem;

    use super::*;

    // ------------------------------------------------------------------

    // Independent decoders — used to round-trip `CounterFormat::format`

    // without reusing the encoder's own arithmetic.

    // ------------------------------------------------------------------

    /// Decode a lowercase roman numeral. Uses `i64` so the subtractive

    /// prefix ("iv") cannot underflow the accumulator.

    fn decode_roman(s: &str) -> Option<i64> {

        let mut vals = Vec::new();

        for c in s.chars() {

            vals.push(match c {

                'i' => 1_i64,

                'v' => 5,

                'x' => 10,

                'l' => 50,

                'c' => 100,

                'd' => 500,

                'm' => 1000,

                _ => return None,

            });

        }

        let mut total = 0_i64;

        for i in 0..vals.len() {

            if i + 1 < vals.len() && vals[i] < vals[i + 1] {

                total -= vals[i];

            } else {

                total += vals[i];

            }

        }

        Some(total)

    }

    /// Decode a lowercase bijective base-26 string ("a" == 1, "z" == 26, "aa" == 27).

    fn decode_alpha(s: &str) -> Option<usize> {

        if s.is_empty() {

            return None;

        }

        let mut n = 0_usize;

        for c in s.chars() {

            let digit = match c {

                'a'..='z' => c as usize - 'a' as usize + 1,

                _ => return None,

            };

            n = n.checked_mul(26)?.checked_add(digit)?;

        }

        Some(n)

    }

    /// Decode a lowercase bijective base-24 greek string ("α" == 1, "ω" == 24, "αα" == 25).

    fn decode_greek(s: &str) -> Option<usize> {

        const LOWER: &[char] = &[

            'α', 'β', 'γ', 'δ', 'ε', 'ζ', 'η', 'θ', 'ι', 'κ', 'λ', 'μ', 'ν', 'ξ', 'ο', 'π', 'ρ',

            'σ', 'τ', 'υ', 'φ', 'χ', 'ψ', 'ω',

        ];

        if s.is_empty() {

            return None;

        }

        let mut n = 0_usize;

        for c in s.chars() {

            let digit = LOWER.iter().position(|l| *l == c)? + 1;

            n = n.checked_mul(LOWER.len())?.checked_add(digit)?;

        }

        Some(n)

    }

    fn table(start_y: f32, end_y: f32, thead_height: f32) -> TableHeaderInfo {

        TableHeaderInfo {

            table_node_index: 0,

            table_start_y: start_y,

            table_end_y: end_y,

            thead_items: vec![DisplayListItem::PopClip],

            thead_height,

            thead_offset_y: 0.0,

        }

    }

    // ==================================================================

    // CounterFormat::format — serializer: edge values, huge n, round-trip

    // ==================================================================

    #[test]

    fn counter_format_decimal_handles_zero_and_usize_max() {

        assert_eq!(CounterFormat::Decimal.format(0), "0");

        assert_eq!(CounterFormat::Decimal.format(1), "1");

        assert_eq!(

            CounterFormat::Decimal.format(usize::MAX),

            usize::MAX.to_string()

        );

    }

    #[test]

    fn counter_format_default_is_decimal_and_does_not_panic_on_zero() {

        let default = CounterFormat::default();

        assert_eq!(default, CounterFormat::Decimal);

        assert_eq!(default.format(0), "0");

    }

    #[test]

    fn counter_format_leading_zero_pads_to_two_but_never_truncates() {

        assert_eq!(CounterFormat::DecimalLeadingZero.format(0), "00");

        assert_eq!(CounterFormat::DecimalLeadingZero.format(7), "07");

        assert_eq!(CounterFormat::DecimalLeadingZero.format(9), "09");

        assert_eq!(CounterFormat::DecimalLeadingZero.format(10), "10");

        // A width-2 pad must not *clip* wider numbers.

        assert_eq!(CounterFormat::DecimalLeadingZero.format(12345), "12345");

        assert_eq!(

            CounterFormat::DecimalLeadingZero.format(usize::MAX),

            usize::MAX.to_string()

        );

    }

    #[test]

    fn counter_format_every_variant_survives_zero_one_and_usize_max() {

        // The contract we are pinning: no panic, no hang, output is valid UTF-8

        // with all char boundaries intact for every (variant, extreme) pair.

        let variants = [

            CounterFormat::Decimal,

            CounterFormat::DecimalLeadingZero,

            CounterFormat::LowerRoman,

            CounterFormat::UpperRoman,

            CounterFormat::LowerAlpha,

            CounterFormat::UpperAlpha,

            CounterFormat::LowerGreek,

        ];

        for v in variants {

            for n in [0_usize, 1, 25, 26, 27, 3999, 4000, usize::MAX] {

                let s = v.format(n);

                assert!(

                    s.is_char_boundary(0) && s.is_char_boundary(s.len()),

                    "{v:?}.format({n}) produced a malformed string"

                );

            }

        }

    }

    #[test]

    fn counter_format_alphabetic_and_greek_return_empty_at_zero() {

        // KNOWN DIVERGENCE (asserted, not papered over): `format_counter` in

        // `super::counters` applies a CSS decimal fallback when an alphabetic or

        // greek style cannot represent a value, but `CounterFormat::format` does

        // not — so a page counter at 0 renders as a *blank* margin box here while

        // roman renders "0". Page numbers are 1-indexed so this is unreachable in

        // the current pipeline; the test exists to catch it becoming reachable.

        assert_eq!(CounterFormat::LowerAlpha.format(0), "");

        assert_eq!(CounterFormat::UpperAlpha.format(0), "");

        assert_eq!(CounterFormat::LowerGreek.format(0), "");

        assert_eq!(CounterFormat::LowerRoman.format(0), "0");

        assert_eq!(CounterFormat::UpperRoman.format(0), "0");

    }

    #[test]

    fn counter_format_roman_falls_back_to_decimal_past_3999() {

        assert_eq!(CounterFormat::LowerRoman.format(3999), "mmmcmxcix");

        assert_eq!(CounterFormat::UpperRoman.format(3999), "MMMCMXCIX");

        // 4000 is not representable -> decimal, in *both* cases (no stray casing).

        assert_eq!(CounterFormat::LowerRoman.format(4000), "4000");

        assert_eq!(CounterFormat::UpperRoman.format(4000), "4000");

        assert_eq!(

            CounterFormat::UpperRoman.format(usize::MAX),

            usize::MAX.to_string()

        );

    }

    #[test]

    fn counter_format_roman_round_trips_over_its_whole_representable_range() {

        for n in 1..=3999_usize {

            let lower = CounterFormat::LowerRoman.format(n);

            let upper = CounterFormat::UpperRoman.format(n);

            assert_eq!(

                decode_roman(&lower),

                Some(n as i64),

                "lower-roman round-trip failed for {n} -> {lower}"

            );

            assert_eq!(upper, lower.to_uppercase(), "casing mismatch for {n}");

        }

    }

    #[test]

    fn counter_format_alphabetic_round_trips_and_is_injective() {

        let mut seen = std::collections::HashSet::new();

        for n in 1..=3000_usize {

            let lower = CounterFormat::LowerAlpha.format(n);

            let upper = CounterFormat::UpperAlpha.format(n);

            assert_eq!(

                decode_alpha(&lower),

                Some(n),

                "lower-alpha round-trip failed for {n} -> {lower}"

            );

            assert_eq!(upper, lower.to_uppercase(), "casing mismatch for {n}");

            assert!(seen.insert(lower), "two page numbers collided at {n}");

        }

        // Bijective base-26 boundaries — the classic off-by-one zone.

        assert_eq!(CounterFormat::LowerAlpha.format(26), "z");

        assert_eq!(CounterFormat::LowerAlpha.format(27), "aa");

        assert_eq!(CounterFormat::LowerAlpha.format(52), "az");

        assert_eq!(CounterFormat::LowerAlpha.format(53), "ba");

    }

    #[test]

    fn counter_format_greek_round_trips_and_emits_whole_code_points() {

        for n in 1..=2000_usize {

            let s = CounterFormat::LowerGreek.format(n);

            assert_eq!(

                decode_greek(&s),

                Some(n),

                "lower-greek round-trip failed for {n} -> {s}"

            );

            // Every greek letter is 2 bytes: byte len must be exactly 2x char count,

            // i.e. the encoder's `insert(0, ..)` never split a code point.

            assert_eq!(s.len(), s.chars().count() * 2, "sliced a code point at {n}");

        }

        assert_eq!(CounterFormat::LowerGreek.format(24), "ω");

        assert_eq!(CounterFormat::LowerGreek.format(25), "αα");

    }

    #[test]

    fn counter_format_usize_max_terminates_for_the_positional_styles() {

        // `(n - 1) / base` strictly decreases, so these must halt rather than hang.

        let alpha = CounterFormat::LowerAlpha.format(usize::MAX);

        let greek = CounterFormat::LowerGreek.format(usize::MAX);

        assert!(!alpha.is_empty() && alpha.chars().all(|c| c.is_ascii_lowercase()));

        assert!(!greek.is_empty());

        assert_eq!(greek.len(), greek.chars().count() * 2);

    }

    // ==================================================================

    // PageInfo::new — constructor invariants

    // ==================================================================

    #[test]

    fn page_info_new_sets_flags_for_a_representative_page() {

        let info = PageInfo::new(1, 3);

        assert_eq!(info.page_number, 1);

        assert_eq!(info.total_pages, 3);

        assert!(info.is_first);

        assert!(!info.is_last);

        assert!(info.is_right, "page 1 (odd) is a recto page");

        assert!(!info.is_left);

        assert!(!info.is_blank);

    }

    #[test]

    fn page_info_left_and_right_are_always_mutually_exclusive() {

        for n in [0_usize, 1, 2, 3, 100, 101, usize::MAX - 1, usize::MAX] {

            let info = PageInfo::new(n, 0);

            assert!(

                info.is_left != info.is_right,

                "page {n} claimed to be both/neither verso and recto"

            );

            assert_eq!(info.is_left, n % 2 == 0);

            assert!(!info.is_blank, "new() must never fabricate a blank page");

        }

    }

    #[test]

    fn page_info_is_last_is_false_when_the_total_is_unknown() {

        // total_pages == 0 means "unknown during the first pass" — nothing is last.

        for n in [0_usize, 1, 7, usize::MAX] {

            assert!(!PageInfo::new(n, 0).is_last, "page {n} of 0 claimed is_last");

        }

    }

    #[test]

    fn page_info_page_zero_is_degenerate_but_does_not_panic() {

        let info = PageInfo::new(0, 0);

        assert!(!info.is_first, "1-indexed: page 0 is not the first page");

        assert!(!info.is_last);

        assert!(info.is_left, "0 is even, so it lands on the verso branch");

    }

    #[test]

    fn page_info_out_of_range_page_number_does_not_claim_to_be_last() {

        // page_number > total_pages is nonsense input; it must not silently

        // become `is_last` (which would duplicate the last-page decoration).

        let info = PageInfo::new(9, 3);

        assert!(!info.is_last);

        assert!(!info.is_first);

    }

    #[test]

    fn page_info_usize_max_extremes_do_not_overflow() {

        let info = PageInfo::new(usize::MAX, usize::MAX);

        assert!(info.is_last, "the final page of a MAX-page document is last");

        assert!(!info.is_first);

        assert!(info.is_right, "usize::MAX is odd");

        let single = PageInfo::new(1, 1);

        assert!(single.is_first && single.is_last);

    }

    // ==================================================================

    // HeaderFooterConfig — constructors + content generation

    // ==================================================================

    #[test]

    fn header_footer_default_renders_nothing_on_any_page() {

        let cfg = HeaderFooterConfig::default();

        assert!(!cfg.show_header && !cfg.show_footer);

        assert!(matches!(cfg.header_content, MarginBoxContent::None));

        assert!(matches!(cfg.footer_content, MarginBoxContent::None));

        assert_eq!(cfg.header_text(PageInfo::new(1, 1)), "");

        assert_eq!(cfg.footer_text(PageInfo::new(usize::MAX, usize::MAX)), "");

        assert_eq!(cfg.text_color.a, 255);

    }

    #[test]

    fn header_footer_with_page_numbers_only_enables_the_footer() {

        let cfg = HeaderFooterConfig::with_page_numbers();

        assert!(cfg.show_footer);

        assert!(!cfg.show_header, "with_page_numbers must not enable a header");

        assert_eq!(cfg.footer_text(PageInfo::new(2, 7)), "Page 2 of 7");

        assert_eq!(cfg.header_text(PageInfo::new(2, 7)), "");

    }

    #[test]

    fn header_footer_unknown_total_renders_a_question_mark_not_a_zero() {

        let cfg = HeaderFooterConfig::with_page_numbers();

        assert_eq!(cfg.footer_text(PageInfo::new(1, 0)), "Page 1 of ?");

    }