rpdfium_text/textpage/

mod.rs

// Derived from PDFium's fpdf_text.cpp text extraction and analysis
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! Text extraction from a single PDF page with character-level position data.
//! Implements text extraction, segmentation, reading order, and search.

pub mod fx_bidi;

use std::collections::HashMap;

#[cfg(feature = "icu")]
use unicode_normalization::UnicodeNormalization;

use rpdfium_core::{Matrix, Name};
use rpdfium_graphics::{
    BlendMode, ClipPath, Color, ColorSpaceFamily, ImageRef, PathOp, PathStyle, TextRenderingMode,
};
use rpdfium_page::display::{DisplayVisitor, SoftMask, TextRun};
use rpdfium_page::shading::ShadingDict;
use rpdfium_parser::Operand;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CharType {
    /// Normal character decoded from glyph bytes.
    #[default]
    Normal,
    /// Synthesized space inserted by gap detection.
    Generated,
    /// Soft or hard hyphen character.
    Hyphen,
    /// Part of a decomposed ligature (2nd+ character).
    Piece,
    /// Character code could not be mapped to Unicode (upstream `kNotUnicode`).
    NotUnicode,
}

/// A single extracted character with its position, size, and font metadata.
///
/// All fields are private, matching upstream PDFium where `CharInfo` is a
/// private struct inside `CPDF_TextPage`.  External access goes through
/// indexed getters on [`TextPage`] (e.g. `get_unicode()`, `get_font_size()`).
#[derive(Debug, Clone)]
pub struct TextCharacter {
    /// The Unicode character.
    unicode: char,
    /// Raw font encoding code before Unicode mapping (upstream `CharInfo::char_code`).
    /// For ActualText runs and generated spaces, this is `0`.
    char_code: u32,
    /// Tight bounding box in page space (upstream `CharInfo::char_box_`).
    char_box: CharRect,
    /// Font size in text space units.
    font_size: f32,
    /// Name of the font used for this character.
    font_name: String,
    /// Width of the space character for this font in page space (if available).
    /// Used for dynamic word-gap threshold in segmentation.
    space_width: Option<f32>,
    /// True if this character is a soft hyphen (U+00AD).
    is_soft_hyphen: bool,
    /// Classification of this character's origin.
    char_type: CharType,
    /// Per-character text matrix `[a, b, c, d, e, f]` in page space.
    /// `a/b/c/d` are from the run matrix; `e/f` are the character's page-space origin.
    matrix: [f32; 6],
    /// Expanded bounding box using font ascent/descent (upstream `loose_char_box`).
    /// `None` for ActualText and generated characters.
    loose_char_box: Option<CharRect>,
    /// Fill color at the time this character was rendered (upstream `FPDFText_GetFillColor`).
    fill_color: Option<Color>,
    /// Stroke color at the time this character was rendered (upstream `FPDFText_GetStrokeColor`).
    stroke_color: Option<Color>,
    /// Font weight (100–900, CSS-style) from the font descriptor (upstream `FPDFText_GetFontWeight`).
    font_weight: Option<i32>,
    /// PDF font descriptor flags (Table 123) from the font descriptor (upstream `FPDFText_GetFontInfo` flags param).
    font_flags: Option<u32>,
    /// Text rendering mode at the time this character was rendered (upstream `FPDFText_GetTextRenderMode`).
    rendering_mode: TextRenderingMode,
}

/// Maximum size of the duplicate-detection ring buffer.
const RECENT_RING_CAPACITY: usize = 7;

/// Extracts text characters from a `DisplayTree` by visiting text nodes.
pub struct TextExtractor {
    characters: Vec<TextCharacter>,
    /// Parallel array of run IDs (same length as `characters`).
    /// Tracks which text run each character belongs to.
    run_ids: Vec<Option<u32>>,
    /// Ring buffer of recently added characters for duplicate detection.
    recent_chars: Vec<TextCharacter>,
    /// Last emitted ActualText span ID for deduplication.
    last_actual_text_id: Option<u64>,
    /// Monotonic counter for assigning run IDs to characters.
    next_run_id: u32,
    /// When true, use RTL base direction for bidi reordering.
    rtl: bool,
}

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

impl TextExtractor {
    /// Create a new empty text extractor.
    pub fn new() -> Self {
        Self {
            characters: Vec::new(),
            run_ids: Vec::new(),
            recent_chars: Vec::with_capacity(RECENT_RING_CAPACITY),
            last_actual_text_id: None,
            next_run_id: 0,
            rtl: false,
        }
    }

    /// Create a new text extractor with an RTL base direction hint.
    ///
    /// When `rtl` is true and the `icu` feature is enabled, bidi reordering
    /// uses RTL as the default paragraph direction.
    pub fn with_rtl(rtl: bool) -> Self {
        Self {
            characters: Vec::new(),
            run_ids: Vec::new(),
            recent_chars: Vec::with_capacity(RECENT_RING_CAPACITY),
            last_actual_text_id: None,
            next_run_id: 0,
            rtl,
        }
    }

    /// Returns the RTL hint configured for this extractor.
    pub fn is_rtl(&self) -> bool {
        self.rtl
    }

    /// Check if a character is a duplicate of a recently added character.
    ///
    /// A character is considered a duplicate if it has the same unicode codepoint,
    /// the same font name, and both x and y positions are within 1% of font_size.
    fn is_duplicate(&self, ch: &TextCharacter) -> bool {
        let tolerance = ch.font_size * 0.01;
        self.recent_chars.iter().any(|recent| {
            recent.unicode == ch.unicode
                && recent.font_name == ch.font_name
                && (recent.char_box.left - ch.char_box.left).abs() < tolerance
                && (recent.char_box.bottom - ch.char_box.bottom).abs() < tolerance
        })
    }

    /// Add a character to the ring buffer (always, whether duplicate or not).
    fn push_recent(&mut self, ch: &TextCharacter) {
        if self.recent_chars.len() >= RECENT_RING_CAPACITY {
            self.recent_chars.remove(0);
        }
        self.recent_chars.push(ch.clone());
    }

    /// Consume the extractor and return all collected characters with their run IDs.
    pub fn into_characters(self) -> (Vec<TextCharacter>, Vec<Option<u32>>) {
        (self.characters, self.run_ids)
    }

    /// Try to add a character, skipping if it's a duplicate.
    /// Always adds the character to the ring buffer.
    fn try_add_character(&mut self, ch: TextCharacter, run_id: Option<u32>) {
        let is_dup = self.is_duplicate(&ch);
        self.push_recent(&ch);
        if !is_dup {
            self.characters.push(ch);
            self.run_ids.push(run_id);
        }
    }

    /// Extract characters from a single `TextRun`.
    fn extract_run(&mut self, run: &TextRun) {
        // Skip invisible text (rendering mode 3 = invisible)
        if run.rendering_mode == TextRenderingMode::Invisible {
            return;
        }

        // Deduplicate runs with the same ActualText span ID.
        // Multiple text runs within a single BDC ActualText sequence share
        // the same ID — only the first should emit characters.
        if let Some(id) = run.actual_text_id {
            if self.last_actual_text_id == Some(id) {
                return;
            }
            if run.actual_text.is_some() {
                self.last_actual_text_id = Some(id);
            }
        }

        // Assign a run ID to all characters from this run.
        let run_id = self.next_run_id;
        self.next_run_id += 1;

        let font_name_str = run.font_name.as_str().to_string();
        let font_size = run.font_size;
        let matrix = &run.matrix;

        // Compute effective height from the matrix: scale factor on y-axis
        let height = (matrix.b * matrix.b + matrix.d * matrix.d).sqrt() as f32 * font_size;

        // Precompute matrix scale factor for width calculation (constant per run)
        let width_scale = (matrix.a * matrix.a + matrix.c * matrix.c).sqrt() as f32;

        // Precompute run matrix components for per-character matrix field
        let mat_a = matrix.a as f32;
        let mat_b = matrix.b as f32;
        let mat_c = matrix.c as f32;
        let mat_d = matrix.d as f32;

        // Compute font ascent/descent for loose_char_box (in 1/1000 em units)
        let (font_ascent, font_descent) = run
            .resolved_font
            .as_ref()
            .map(|rf| (rf.ascent as f32, rf.descent as f32))
            .unwrap_or((750.0, -250.0));

        // Detect vertical CID font mode (WMode=1 with CID font type).
        // Vertical CID fonts advance downward and use vert_origins / VerticalMetrics
        // for bounding box computation instead of ascent/descent.
        let is_vertical_cid = run.is_vertical
            && run
                .resolved_font
                .as_ref()
                .map(|rf| rf.is_cid_font())
                .unwrap_or(false);

        // Compute space width from the resolved font for dynamic word-gap threshold
        let space_width = run.resolved_font.as_ref().map(|rf| {
            let w = rf.char_width(32) as f32;
            w * font_size / 1000.0 * width_scale
        });

        // If /ActualText is present, emit those characters instead of decoding glyphs.
        // Distribute the total advance width proportionally across ActualText characters.
        if let Some(ref actual) = run.actual_text {
            let total_advance: f32 = run.positions.iter().sum();
            let total_width = width_scale * total_advance;
            let decomposed_actual = decompose_ligatures(actual);
            let actual_chars: Vec<char> = decomposed_actual.chars().collect();
            let char_count = actual_chars.len().max(1);
            let per_char_width = total_width / char_count as f32;

            for (i, ch) in actual_chars.iter().enumerate() {
                let tx = total_advance * i as f32 / char_count as f32;
                let ty = run.rise;
                let page_x = (matrix.a * tx as f64 + matrix.c * ty as f64 + matrix.e) as f32;
                let page_y = (matrix.b * tx as f64 + matrix.d * ty as f64 + matrix.f) as f32;

                let is_hyphen = *ch == '\u{00AD}'
                    || *ch == '\u{002D}'
                    || *ch == '\u{2010}'
                    || *ch == '\u{2011}';
                self.try_add_character(
                    TextCharacter {
                        unicode: *ch,
                        char_code: 0,
                        char_box: CharRect {
                            left: page_x,
                            bottom: page_y,
                            right: page_x + per_char_width,
                            top: page_y + height,
                        },
                        font_size,
                        font_name: font_name_str.clone(),
                        space_width,
                        is_soft_hyphen: *ch == '\u{00AD}',
                        char_type: if is_hyphen {
                            CharType::Hyphen
                        } else {
                            CharType::Normal
                        },
                        matrix: [mat_a, mat_b, mat_c, mat_d, page_x, page_y],
                        loose_char_box: None,
                        fill_color: run.fill_color.clone(),
                        stroke_color: run.stroke_color.clone(),
                        font_weight: run.resolved_font.as_ref().and_then(|rf| rf.weight),
                        font_flags: run.resolved_font.as_ref().and_then(|rf| rf.flags),
                        rendering_mode: run.rendering_mode,
                    },
                    Some(run_id),
                );
            }
            return;
        }

        // Determine character codes depending on whether we have a CID font
        let char_codes: Vec<(u32, usize)> = if let Some(ref resolved) = run.resolved_font {
            if resolved.is_cid_font() {
                if let Some(ref cmap) = resolved.cid_cmap {
                    cmap.extract_char_codes(&run.text)
                } else {
                    // Default: 2-byte codes for CID fonts without explicit CMap
                    extract_two_byte_codes(&run.text)
                }
            } else {
                // Simple fonts: 1 byte per character
                run.text.iter().map(|&b| (b as u32, 1)).collect()
            }
        } else {
            // No resolved font: treat as 1-byte codes
            run.text.iter().map(|&b| (b as u32, 1)).collect()
        };

        // Compute the space gap threshold for intra-run space insertion.
        let gap_threshold =
            space_width.map(|sw| space_threshold(sw as f64, font_size as f64) as f32);

        // Track previous character's page-space x position for intra-run gap detection.
        let mut prev_page_end_x: Option<f32> = None;

        // Walk through character codes, using the positions array for advances.
        // Track accumulated advance incrementally to avoid O(n^2) re-summation.
        let mut accumulated_advance: f32 = 0.0;
        for (pos_idx, (code, _byte_len)) in char_codes.iter().enumerate() {
            let code = *code;

            // Decode to Unicode
            let unicode_str = if let Some(ref resolved) = run.resolved_font {
                resolved.unicode_from_char_code(code)
            } else {
                // Fallback: try ASCII if in range
                if (0x20..0x7F).contains(&code) {
                    Some((code as u8 as char).to_string())
                } else {
                    None
                }
            };

            // Get advance width from positions array
            let advance = if pos_idx < run.positions.len() {
                run.positions[pos_idx]
            } else {
                0.0
            };

            if let Some(ustr) = unicode_str {
                let normalized = normalize_text(&ustr);
                // Decompose ligatures
                let decomposed = decompose_ligatures(&normalized);
                let chars: Vec<char> = decomposed.chars().collect();
                let char_count = chars.len().max(1);

                // Check for intra-run space: gap between previous char end and current char start
                let tx = accumulated_advance;
                let ty = run.rise;
                let page_x = (matrix.a * tx as f64 + matrix.c * ty as f64 + matrix.e) as f32;
                let page_y = (matrix.b * tx as f64 + matrix.d * ty as f64 + matrix.f) as f32;

                if let (Some(prev_end), Some(threshold)) = (prev_page_end_x, gap_threshold) {
                    let gap = page_x - prev_end;
                    if gap > 0.0 && gap > threshold {
                        self.try_add_character(
                            TextCharacter {
                                unicode: ' ',
                                char_code: 0x20,
                                char_box: CharRect {
                                    left: prev_end,
                                    bottom: page_y,
                                    right: prev_end + gap,
                                    top: page_y + height,
                                },
                                font_size,
                                font_name: font_name_str.clone(),
                                space_width,
                                is_soft_hyphen: false,
                                char_type: CharType::Generated,
                                matrix: [mat_a, mat_b, mat_c, mat_d, prev_end, page_y],
                                loose_char_box: None,
                                fill_color: run.fill_color.clone(),
                                stroke_color: run.stroke_color.clone(),
                                font_weight: run.resolved_font.as_ref().and_then(|rf| rf.weight),
                                font_flags: run.resolved_font.as_ref().and_then(|rf| rf.flags),
                                rendering_mode: run.rendering_mode,
                            },
                            None,
                        );
                    }
                }

                // Width in page space distributed among decomposed characters
                let total_width = width_scale * advance;
                let per_char_width = total_width / char_count as f32;

                for (ci, ch) in chars.iter().enumerate() {
                    let char_offset = per_char_width * ci as f32;
                    let char_x = page_x + char_offset;

                    let is_hyphen = *ch == '\u{00AD}'
                        || *ch == '\u{002D}'
                        || *ch == '\u{2010}'
                        || *ch == '\u{2011}';
                    let ctype = if ci > 0 {
                        CharType::Piece
                    } else if is_hyphen {
                        CharType::Hyphen
                    } else {
                        CharType::Normal
                    };
                    // For vertical CID fonts, use vert_origin + w1y metrics
                    // matching PDFium's CPDF_TextPage::GenerateCharacter() which calls
                    // pFont->GetVertOriginX/Y() and pFont->GetVertWidth() instead of
                    // ascent/descent when the font has WMode=1.
                    let loose = if is_vertical_cid {
                        // Look up vertical metrics for this CID from the font's
                        // /DW2 / /W2 dictionaries (VerticalMetrics::lookup).
                        // (w1y, vx, vy) — w1y is the vertical advance (typically −1000),
                        // vy is the vertical origin Y offset (typically 880).
                        let (w1y, vy) = run
                            .resolved_font
                            .as_ref()
                            .and_then(|rf| rf.vertical_metrics.as_ref())
                            .map(|vm| {
                                let (w1y, _vx, vy) = vm.lookup(code as u16);
                                (w1y as f32, vy as f32)
                            })
                            .unwrap_or((-1000.0, 880.0));
                        // Per-glyph vert_origins may override vy when the interpreter
                        // has already resolved the origin from the font dictionary.
                        let vy = run
                            .vert_origins
                            .get(pos_idx)
                            .map(|&(_vx, run_vy)| run_vy as f32)
                            .unwrap_or(vy);
                        compute_loose_char_box_vertical(
                            char_x,
                            page_y,
                            per_char_width,
                            font_size,
                            vy,
                            w1y,
                            mat_a,
                            mat_b,
                            mat_c,
                            mat_d,
                        )
                    } else {
                        compute_loose_char_box(
                            char_x,
                            page_y,
                            per_char_width,
                            font_size,
                            font_ascent,
                            font_descent,
                            mat_a,
                            mat_b,
                            mat_c,
                            mat_d,
                        )
                    };
                    self.try_add_character(
                        TextCharacter {
                            unicode: *ch,
                            char_code: code,
                            char_box: CharRect {
                                left: char_x,
                                bottom: page_y,
                                right: char_x + per_char_width,
                                top: page_y + height,
                            },
                            font_size,
                            font_name: font_name_str.clone(),
                            space_width,
                            is_soft_hyphen: *ch == '\u{00AD}',
                            char_type: ctype,
                            matrix: [mat_a, mat_b, mat_c, mat_d, char_x, page_y],
                            loose_char_box: Some(loose),
                            fill_color: run.fill_color.clone(),
                            stroke_color: run.stroke_color.clone(),
                            font_weight: run.resolved_font.as_ref().and_then(|rf| rf.weight),
                            font_flags: run.resolved_font.as_ref().and_then(|rf| rf.flags),
                            rendering_mode: run.rendering_mode,
                        },
                        Some(run_id),
                    );
                }

                prev_page_end_x = Some(page_x + total_width);
            }

            // Incrementally accumulate for the next character
            accumulated_advance += advance;
        }
    }
}

/// Compute the loose bounding box for a character using font ascent/descent.
///
/// The loose box expands the character's tight bounding box vertically
/// to account for diacritics and descenders, using the font's ascent and
/// descent metrics (in 1/1000 em units). The box is transformed to page
/// space using the character's matrix components.
#[allow(clippy::too_many_arguments)]
fn compute_loose_char_box(
    x: f32,
    y: f32,
    width: f32,
    font_size: f32,
    font_ascent: f32,
    font_descent: f32,
    mat_a: f32,
    mat_b: f32,
    mat_c: f32,
    mat_d: f32,
) -> CharRect {
    let ascent_page = font_ascent * font_size / 1000.0;
    let descent_page = font_descent * font_size / 1000.0;

    // Transform the four corners of the loose box through the matrix
    // The text-space box is [0, descent_page] to [width, ascent_page]
    // relative to the character origin, but we apply only the a/b/c/d
    // rotation/scale components (e/f is already in x/y).
    let scale = (mat_a * mat_a + mat_c * mat_c).sqrt();
    let width_scaled = if scale > 0.0 { width / scale } else { width };

    // Compute corners in text space then transform
    let corners = [
        (0.0f32, descent_page),
        (width_scaled, descent_page),
        (width_scaled, ascent_page),
        (0.0, ascent_page),
    ];

    let mut min_x = f32::INFINITY;
    let mut min_y = f32::INFINITY;
    let mut max_x = f32::NEG_INFINITY;
    let mut max_y = f32::NEG_INFINITY;

    for &(cx, cy) in &corners {
        let px = x + mat_a * cx + mat_c * cy;
        let py = y + mat_b * cx + mat_d * cy;
        min_x = min_x.min(px);
        min_y = min_y.min(py);
        max_x = max_x.max(px);
        max_y = max_y.max(py);
    }

    CharRect {
        left: min_x,
        bottom: min_y,
        right: max_x,
        top: max_y,
    }
}

/// Compute the loose bounding box for a character in a vertical CID font.
///
/// For vertical CID fonts (WMode=1), the character box is oriented around the
/// vertical writing direction. The vertical origin Y (`vert_origin_y`) and
/// vertical advance (`vert_w1y`) from the font's `/DW2`/`/W2` dictionaries
/// replace the ascent/descent used for horizontal text.
///
/// This matches PDFium's `CPDF_TextPage::GenerateCharacter()` which calls
/// `pFont->GetVertOriginY()` and `pFont->GetVertWidth()` for CID fonts with
/// `WMode=1` (checked via `pFont->IsVertWriting()`).
///
/// # Parameters
/// - `x`, `y`: character origin in page space
/// - `width`: character advance width in page space
/// - `font_size`: font size in text space units
/// - `vert_origin_y`: vertical origin Y in 1/1000 em (typically 880)
/// - `vert_w1y`: vertical advance in 1/1000 em (typically −1000, negative = downward)
/// - `mat_a..mat_d`: text-to-page matrix rotation/scale components
#[allow(clippy::too_many_arguments)]
fn compute_loose_char_box_vertical(
    x: f32,
    y: f32,
    width: f32,
    font_size: f32,
    vert_origin_y: f32,
    vert_w1y: f32,
    mat_a: f32,
    mat_b: f32,
    mat_c: f32,
    mat_d: f32,
) -> CharRect {
    // In vertical writing mode the glyph's bounding box is defined by:
    //   top    = vert_origin_y scaled to page units (offset above writing pos)
    //   bottom = top + vert_w1y scaled to page units (vert_w1y < 0 → descends)
    //   left   = 0 (writing position x)
    //   right  = width (glyph advance width, which is the cell width)
    let top_page = vert_origin_y * font_size / 1000.0;
    let bottom_page = (vert_origin_y + vert_w1y) * font_size / 1000.0;

    // Build the four corners in text-relative space and transform through
    // the matrix a/b/c/d components (x/y translation is already in x, y).
    let scale = (mat_a * mat_a + mat_c * mat_c).sqrt();
    let width_scaled = if scale > 0.0 { width / scale } else { width };

    let corners = [
        (0.0f32, bottom_page),
        (width_scaled, bottom_page),
        (width_scaled, top_page),
        (0.0, top_page),
    ];

    let mut min_x = f32::INFINITY;
    let mut min_y = f32::INFINITY;
    let mut max_x = f32::NEG_INFINITY;
    let mut max_y = f32::NEG_INFINITY;

    for &(cx, cy) in &corners {
        let px = x + mat_a * cx + mat_c * cy;
        let py = y + mat_b * cx + mat_d * cy;
        min_x = min_x.min(px);
        min_y = min_y.min(py);
        max_x = max_x.max(px);
        max_y = max_y.max(py);
    }

    CharRect {
        left: min_x,
        bottom: min_y,
        right: max_x,
        top: max_y,
    }
}

/// Decompose Unicode ligature codepoints into their component characters.
///
/// Returns the input string unchanged if it contains no ligatures.
fn decompose_ligatures(text: &str) -> String {
    let mut result = String::with_capacity(text.len());
    for ch in text.chars() {
        match ch {
            '\u{FB00}' => result.push_str("ff"),
            '\u{FB01}' => result.push_str("fi"),
            '\u{FB02}' => result.push_str("fl"),
            '\u{FB03}' => result.push_str("ffi"),
            '\u{FB04}' => result.push_str("ffl"),
            '\u{FB05}' | '\u{FB06}' => result.push_str("st"),
            _ => result.push(ch),
        }
    }
    result
}

/// Apply NFC normalization to a string when the `icu` feature is enabled.
#[cfg(feature = "icu")]
pub fn normalize_text(text: &str) -> String {
    text.nfc().collect()
}

/// Identity pass-through when the `icu` feature is disabled.
#[cfg(not(feature = "icu"))]
pub fn normalize_text(text: &str) -> String {
    text.to_string()
}

/// Extract 2-byte character codes from raw bytes (for CID fonts without CMap).
fn extract_two_byte_codes(data: &[u8]) -> Vec<(u32, usize)> {
    let mut result = Vec::new();
    let mut i = 0;
    while i + 1 < data.len() {
        let code = ((data[i] as u32) << 8) | (data[i + 1] as u32);
        result.push((code, 2));
        i += 2;
    }
    // Handle trailing odd byte
    if i < data.len() {
        result.push((data[i] as u32, 1));
    }
    result
}

impl DisplayVisitor for TextExtractor {
    fn enter_group(
        &mut self,
        _blend_mode: BlendMode,
        _clip: Option<&ClipPath>,
        _opacity: f32,
        _isolated: bool,
        _knockout: bool,
        _soft_mask: &Option<Box<SoftMask>>,
    ) -> bool {
        true // always descend
    }

    fn leave_group(&mut self) {
        // no-op
    }

    fn visit_path(
        &mut self,
        _ops: &[PathOp],
        _style: &PathStyle,
        _matrix: &Matrix,
        _fill_color: Option<&Color>,
        _stroke_color: Option<&Color>,
        _fill_color_space: Option<&ColorSpaceFamily>,
        _stroke_color_space: Option<&ColorSpaceFamily>,
        _transfer_function: Option<&rpdfium_page::function::TransferFunction>,
        _overprint: bool,
        _overprint_mode: u32,
    ) {
        // no-op for text extraction
    }

    fn visit_image(
        &mut self,
        _image_ref: &ImageRef,
        _matrix: &Matrix,
        _mask: Option<&rpdfium_page::display::ImageMask>,
        _fill_color: Option<&Color>,
        _transfer_function: Option<&rpdfium_page::function::TransferFunction>,
    ) {
        // no-op for text extraction
    }

    fn visit_inline_image(
        &mut self,
        _properties: &HashMap<Name, Operand>,
        _data: &[u8],
        _matrix: &Matrix,
    ) {
        // no-op for text extraction
    }

    fn visit_shading_fill(&mut self, _shading: &ShadingDict, _matrix: &Matrix) {
        // no-op for text extraction
    }

    fn visit_pattern_fill(
        &mut self,
        _path_ops: &[PathOp],
        _fill_rule: rpdfium_graphics::FillRule,
        _pattern: &rpdfium_page::pattern::TilingPattern,
        _pattern_tree: &rpdfium_page::display::DisplayTree,
        _fill_color: Option<&Color>,
        _matrix: &rpdfium_core::Matrix,
    ) {
        // no-op for text extraction
    }

    fn visit_text(&mut self, runs: &[TextRun]) {
        for run in runs {
            self.extract_run(run);
        }
    }
}

/// A word extracted from the page — a sequence of adjacent characters.
#[derive(Debug, Clone)]
pub struct TextWord {
    /// The concatenated Unicode text of this word.
    pub text: String,
    /// X coordinate of the word's left edge in page space.
    pub x: f32,
    /// Y coordinate of the word's baseline in page space.
    pub y: f32,
    /// Total advance width of the word in page space.
    pub width: f32,
    /// Height of the word (maximum character height).
    pub height: f32,
}

/// A line of text extracted from the page — a sequence of words on the
/// same baseline.
#[derive(Debug, Clone)]
pub struct TextLine {
    /// The full text of the line, with words separated by spaces.
    pub text: String,
    /// Words composing this line, in reading order (left to right).
    pub words: Vec<TextWord>,
    /// Y coordinate of the line's baseline.
    pub y: f32,
    /// Height of the line (maximum word height).
    pub height: f32,
}

/// Threshold multiplier for gap-based word breaking.
///
/// A gap larger than `average_char_width * WORD_GAP_THRESHOLD` between
/// two consecutive characters triggers a word boundary.
const WORD_GAP_THRESHOLD: f32 = 0.3;

/// Upstream-faithful NormalizeThreshold (cpdf_textpage.cpp:47-60).
///
/// `threshold` is in 1/1000 of text space units.
/// Returns normalized threshold in the same units.
fn normalize_threshold(threshold: f32, t1: i32, t2: i32, t3: i32) -> f32 {
    debug_assert!(t1 < t2 && t2 < t3);
    if threshold < t1 as f32 {
        threshold / 2.0
    } else if threshold < t2 as f32 {
        threshold / 4.0
    } else if threshold < t3 as f32 {
        threshold / 5.0
    } else {
        threshold / 6.0
    }
}

/// Compute space detection threshold for a character.
///
/// Input: `char_width_thou` is the space character width in 1/1000 text space
/// units (from `ResolvedFont::char_width(32)`). `font_size_h` is the horizontal
/// font size in page space (font_size * |matrix.a|).
///
/// Uses upstream tier boundaries (300, 500, 700) for character-width threshold.
pub fn space_threshold(char_width_thou: f64, font_size_h: f64) -> f64 {
    let normalized = normalize_threshold(char_width_thou as f32, 300, 500, 700);
    font_size_h * normalized as f64 / 1000.0
}

/// Y-tolerance factor for grouping characters into lines.
///
/// Characters within `font_size * LINE_Y_TOLERANCE` of each other's
/// y-coordinate are considered part of the same line.
const LINE_Y_TOLERANCE: f32 = 0.5;

/// Segment a sequence of characters into words by detecting gaps.
///
/// Characters are grouped left-to-right. A new word starts when the
/// horizontal gap between two consecutive characters exceeds
/// `average_char_width * WORD_GAP_THRESHOLD`, or when the y-coordinate
/// changes significantly.
pub fn segment_words(chars: &[TextCharacter]) -> Vec<TextWord> {
    if chars.is_empty() {
        return Vec::new();
    }

    let total: f32 = chars
        .iter()
        .map(|c| c.char_box.right - c.char_box.left)
        .sum();
    let avg_width = total / chars.len() as f32;

    let fallback_threshold = avg_width * WORD_GAP_THRESHOLD;

    let mut words = Vec::new();
    let mut current_chars: Vec<&TextCharacter> = vec![&chars[0]];

    for i in 1..chars.len() {
        let prev = &chars[i - 1];
        let curr = &chars[i];

        // Check if there's a significant horizontal gap or vertical change.
        // A negative gap means characters overlap (e.g. kerning) — never break.
        let gap = curr.char_box.left - prev.char_box.right;
        let y_diff = (curr.char_box.bottom - prev.char_box.bottom).abs();
        let y_threshold = prev.font_size * LINE_Y_TOLERANCE;

        // Soft hyphens at end-of-line continue the word (don't break).
        if prev.is_soft_hyphen {
            current_chars.push(curr);
            continue;
        }

        // CJK ideographs are treated as individual words regardless of gap.
        let cjk_break = is_cjk_ideograph(curr.unicode) || is_cjk_ideograph(prev.unicode);

        // Use space_width from the current character (or previous) if available,
        // falling back to average width * WORD_GAP_THRESHOLD.
        // Applies piecewise NormalizeThreshold when space_width is known.
        let gap_threshold = curr
            .space_width
            .or(prev.space_width)
            .map(|sw| space_threshold(sw as f64, curr.font_size as f64) as f32)
            .unwrap_or(fallback_threshold);

        if cjk_break || (gap > 0.0 && gap > gap_threshold) || y_diff > y_threshold {
            // Finish current word
            words.push(build_word(&current_chars));
            current_chars.clear();
        }

        current_chars.push(curr);
    }

    // Finish last word
    if !current_chars.is_empty() {
        words.push(build_word(&current_chars));
    }

    words
}

/// Segment a sequence of characters into lines by grouping on y-position.
///
/// Characters close in y-coordinate are grouped into the same line,
/// then sorted left-to-right. Lines are sorted top-to-bottom (descending y
/// in PDF coordinates).
pub fn segment_lines(chars: &[TextCharacter]) -> Vec<TextLine> {
    if chars.is_empty() {
        return Vec::new();
    }

    // Sort characters by y (descending, since PDF y=0 is bottom) then by x
    let mut sorted: Vec<&TextCharacter> = chars.iter().collect();
    sorted.sort_by(|a, b| {
        b.char_box
            .bottom
            .partial_cmp(&a.char_box.bottom)
            .unwrap_or(std::cmp::Ordering::Equal)
            .then_with(|| {
                a.char_box
                    .left
                    .partial_cmp(&b.char_box.left)
                    .unwrap_or(std::cmp::Ordering::Equal)
            })
    });

    // Group into lines by y-proximity
    let mut lines: Vec<Vec<&TextCharacter>> = Vec::new();
    let mut current_line: Vec<&TextCharacter> = vec![sorted[0]];
    let mut line_y = sorted[0].char_box.bottom;

    for &ch in &sorted[1..] {
        let y_threshold = ch.font_size * LINE_Y_TOLERANCE;
        if (ch.char_box.bottom - line_y).abs() <= y_threshold {
            current_line.push(ch);
        } else {
            lines.push(current_line);
            current_line = vec![ch];
            line_y = ch.char_box.bottom;
        }
    }
    lines.push(current_line);

    // Build TextLine from each group
    lines
        .into_iter()
        .map(|line_chars| {
            // Sort by x within the line
            let mut sorted_line = line_chars;
            sorted_line.sort_by(|a, b| {
                a.char_box
                    .left
                    .partial_cmp(&b.char_box.left)
                    .unwrap_or(std::cmp::Ordering::Equal)
            });

            // Collect owned chars for word segmentation
            let owned: Vec<TextCharacter> = sorted_line.iter().map(|&c| c.clone()).collect();
            let words = segment_words(&owned);

            let y = sorted_line[0].char_box.bottom;
            let height = sorted_line
                .iter()
                .map(|c| c.char_box.top - c.char_box.bottom)
                .fold(0.0f32, f32::max);
            let text = words
                .iter()
                .map(|w| w.text.as_str())
                .collect::<Vec<_>>()
                .join(" ");

            TextLine {
                text,
                words,
                y,
                height,
            }
        })
        .collect()
}

/// Group lines into paragraphs based on vertical spacing.
///
/// A new paragraph starts when the vertical gap between consecutive lines
/// exceeds the average line spacing by a factor of 1.5, or when the first
/// word of the next line is significantly indented.
pub fn segment_paragraphs(lines: &[TextLine]) -> Vec<Vec<TextLine>> {
    if lines.is_empty() {
        return Vec::new();
    }
    if lines.len() == 1 {
        return vec![lines.to_vec()];
    }

    // Calculate average line gap
    let mut gaps: Vec<f32> = Vec::new();
    for i in 0..lines.len() - 1 {
        let gap = (lines[i].y - lines[i + 1].y).abs();
        gaps.push(gap);
    }
    let avg_gap = if gaps.is_empty() {
        0.0
    } else {
        gaps.iter().sum::<f32>() / gaps.len() as f32
    };

    let para_threshold = avg_gap * 1.5;

    let mut paragraphs = Vec::new();
    let mut current_para = vec![lines[0].clone()];

    for i in 1..lines.len() {
        let gap = (lines[i - 1].y - lines[i].y).abs();
        if para_threshold > 0.0 && gap > para_threshold {
            paragraphs.push(current_para);
            current_para = vec![lines[i].clone()];
        } else {
            current_para.push(lines[i].clone());
        }
    }
    paragraphs.push(current_para);

    paragraphs
}

/// Returns `true` if the character is a CJK ideograph.
///
/// CJK ideographs are treated as individual words in segmentation because
/// they are not separated by spaces in typical CJK text.
fn is_cjk_ideograph(c: char) -> bool {
    matches!(c,
        '\u{4E00}'..='\u{9FFF}'   // CJK Unified Ideographs
        | '\u{3400}'..='\u{4DBF}' // CJK Unified Ideographs Extension A
        | '\u{F900}'..='\u{FAFF}' // CJK Compatibility Ideographs
    )
}

fn build_word(chars: &[&TextCharacter]) -> TextWord {
    let text: String = chars.iter().map(|c| c.unicode).collect();
    let x = chars[0].char_box.left;
    let y = chars[0].char_box.bottom;
    let last = chars.last().unwrap();
    let width = last.char_box.right - x;
    let height = chars
        .iter()
        .map(|c| c.char_box.top - c.char_box.bottom)
        .fold(0.0f32, f32::max);

    TextWord {
        text,
        x,
        y,
        width,
        height,
    }
}

pub use rpdfium_core::fx_bidi::mirror_char;

/// A detected column boundary in page space.
#[derive(Debug, Clone)]
pub struct ColumnBound {
    /// Left edge of the column.
    pub x_start: f32,
    /// Right edge of the column.
    pub x_end: f32,
}

/// Dominant text flow orientation within a column or page.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TextFlowOrientation {
    /// Left-to-right (or right-to-left) horizontal text.
    Horizontal,
    /// Top-to-bottom vertical text (CJK convention).
    Vertical,
    /// Could not determine orientation (upstream `kUnknown`).
    Unknown,
}

/// Minimum column width as a fraction of total page width.
/// Columns narrower than this are rejected as noise.
const MIN_COLUMN_WIDTH_FRACTION: f32 = 0.10;

/// Minimum number of lines that must fall within a candidate column
/// for it to be accepted. Single-line "columns" are likely noise.
const MIN_LINES_PER_COLUMN: usize = 2;

/// Sort lines into reading order: top-to-bottom, left-to-right.
///
/// For single-column layouts, this simply sorts by descending y (top first).
/// For multi-column layouts, lines are grouped by column, then sorted
/// column-by-column (left column first), top-to-bottom within each column.
///
/// Vertical text columns (detected by character aspect ratios) are sorted
/// right-to-left (traditional CJK convention), top-to-bottom within each
/// column.
pub fn sort_reading_order(lines: &mut [TextLine]) {
    if lines.len() <= 1 {
        return;
    }

    let columns = detect_columns(lines);
    let orientation = detect_orientation_from_lines(lines);

    if columns.len() <= 1 {
        // Single column — sort by y descending (top of page first)
        lines.sort_by(|a, b| b.y.partial_cmp(&a.y).unwrap_or(std::cmp::Ordering::Equal));
    } else if orientation == TextFlowOrientation::Vertical {
        // Vertical text: columns right-to-left, within each column top-to-bottom
        lines.sort_by(|a, b| {
            let col_a = column_index_for_line(a, &columns);
            let col_b = column_index_for_line(b, &columns);
            // Reverse column order: higher column index (rightmost) first
            col_b
                .cmp(&col_a)
                .then_with(|| b.y.partial_cmp(&a.y).unwrap_or(std::cmp::Ordering::Equal))
        });
    } else {
        // Horizontal multi-column — assign each line to a column, then sort by
        // (column_index, descending y)
        lines.sort_by(|a, b| {
            let col_a = column_index_for_line(a, &columns);
            let col_b = column_index_for_line(b, &columns);
            col_a
                .cmp(&col_b)
                .then_with(|| b.y.partial_cmp(&a.y).unwrap_or(std::cmp::Ordering::Equal))
        });
    }
}

/// Detect column boundaries from line positions.
///
/// Uses histogram-based gap detection: builds a histogram of x-gaps between
/// line spans, finds natural break points, and validates candidate columns
/// against minimum width and line count thresholds.
///
/// Returns one `ColumnBound` per detected column, sorted left-to-right.
/// Falls back to a single column when detection is ambiguous.
pub fn detect_columns(lines: &[TextLine]) -> Vec<ColumnBound> {
    if lines.is_empty() {
        return Vec::new();
    }

    // Collect (x_start, x_end) for each line, skipping empty lines
    let mut line_spans: Vec<(f32, f32)> = lines
        .iter()
        .filter_map(|line| {
            if line.words.is_empty() {
                None
            } else {
                let x_start = line.words[0].x;
                let last_word = line.words.last().unwrap();
                let x_end = last_word.x + last_word.width;
                Some((x_start, x_end))
            }
        })
        .collect();

    if line_spans.is_empty() {
        return Vec::new();
    }

    // Find the overall extent
    let overall_left = line_spans
        .iter()
        .map(|(s, _)| *s)
        .fold(f32::INFINITY, f32::min);
    let overall_right = line_spans
        .iter()
        .map(|(_, e)| *e)
        .fold(f32::NEG_INFINITY, f32::max);

    let page_width = overall_right - overall_left;
    if page_width < 1.0 {
        return vec![ColumnBound {
            x_start: overall_left,
            x_end: overall_right,
        }];
    }

    let min_column_width = page_width * MIN_COLUMN_WIDTH_FRACTION;

    // Sort by x_start for gap analysis
    line_spans.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));

    // Build histogram of x-gaps between non-overlapping spans.
    // Merge overlapping spans into clusters, then measure gaps between clusters.
    let mut merged: Vec<(f32, f32)> = Vec::new();
    for &(start, end) in &line_spans {
        if let Some(last) = merged.last_mut() {
            // Merge if overlapping or touching
            if start <= last.1 {
                last.1 = last.1.max(end);
            } else {
                merged.push((start, end));
            }
        } else {
            merged.push((start, end));
        }
    }

    if merged.len() <= 1 {
        return vec![ColumnBound {
            x_start: overall_left,
            x_end: overall_right,
        }];
    }

    // Collect inter-cluster gaps
    let mut gaps: Vec<(f32, usize)> = Vec::new(); // (gap_size, index_before_gap)
    for i in 0..merged.len() - 1 {
        let gap = merged[i + 1].0 - merged[i].1;
        if gap > 0.0 {
            gaps.push((gap, i));
        }
    }

    if gaps.is_empty() {
        return vec![ColumnBound {
            x_start: overall_left,
            x_end: overall_right,
        }];
    }

    // Find the natural break point: the largest gap that produces valid columns.
    // Sort gaps descending by size.
    gaps.sort_by(|a, b| b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal));

    // Try the largest gap first; verify it produces valid columns
    for &(_gap_size, gap_idx) in &gaps {
        let left_col = ColumnBound {
            x_start: merged[0].0,
            x_end: merged[gap_idx].1,
        };
        let right_col = ColumnBound {
            x_start: merged[gap_idx + 1].0,
            x_end: merged.last().unwrap().1,
        };

        // Validate minimum column width
        let left_width = left_col.x_end - left_col.x_start;
        let right_width = right_col.x_end - right_col.x_start;
        if left_width < min_column_width || right_width < min_column_width {
            continue;
        }

        // Validate minimum line count per column
        let left_count = count_lines_in_column(lines, &left_col);
        let right_count = count_lines_in_column(lines, &right_col);
        if left_count < MIN_LINES_PER_COLUMN || right_count < MIN_LINES_PER_COLUMN {
            continue;
        }

        // Check for ambiguity: if any line spans both columns, fall back
        let has_spanning_line = lines.iter().any(|line| {
            if line.words.is_empty() {
                return false;
            }
            let lx = line.words[0].x;
            let last_w = line.words.last().unwrap();
            let rx = last_w.x + last_w.width;
            lx < left_col.x_end && rx > right_col.x_start
        });
        if has_spanning_line {
            continue;
        }

        return vec![left_col, right_col];
    }

    // No valid split found — single column
    vec![ColumnBound {
        x_start: overall_left,
        x_end: overall_right,
    }]
}

/// Count how many lines have their center within the given column bounds.
fn count_lines_in_column(lines: &[TextLine], col: &ColumnBound) -> usize {
    lines
        .iter()
        .filter(|line| {
            if line.words.is_empty() {
                return false;
            }
            let first = &line.words[0];
            let last = line.words.last().unwrap();
            let center = (first.x + last.x + last.width) / 2.0;
            center >= col.x_start && center <= col.x_end
        })
        .count()
}

/// Detect text flow orientation using coverage masks (upstream `FindTextlineFlowOrientation`).
///
/// Uses `TextCharacter` bounding boxes as proxy for page objects.
/// Builds horizontal and vertical coverage masks, comparing fill ratios
/// to determine whether text flows horizontally or vertically.
pub fn detect_orientation(
    chars: &[TextCharacter],
    page_width: f32,
    page_height: f32,
) -> TextFlowOrientation {
    let pw = page_width as usize;
    let ph = page_height as usize;
    if pw == 0 || ph == 0 || chars.is_empty() {
        return TextFlowOrientation::Unknown;
    }

    // Clamp dimensions to avoid excessive allocation (8192px max)
    let pw = pw.min(8192);
    let ph = ph.min(8192);

    let mut h_mask = vec![false; pw];
    let mut v_mask = vec![false; ph];
    let mut line_height: f32 = 0.0;
    let (mut start_h, mut end_h) = (pw, 0usize);
    let (mut start_v, mut end_v) = (ph, 0usize);

    for ch in chars {
        if ch.char_type == CharType::Generated {
            continue;
        }
        let min_h = (ch.char_box.left.max(0.0) as usize).min(pw);
        let max_h = (ch.char_box.right.max(0.0) as usize).min(pw);
        let min_v = (ch.char_box.bottom.max(0.0) as usize).min(ph);
        let max_v = (ch.char_box.top.max(0.0) as usize).min(ph);
        if min_h >= max_h || min_v >= max_v {
            continue;
        }

        for cell in &mut h_mask[min_h..max_h] {
            *cell = true;
        }
        for cell in &mut v_mask[min_v..max_v] {
            *cell = true;
        }

        start_h = start_h.min(min_h);
        end_h = end_h.max(max_h);
        start_v = start_v.min(min_v);
        end_v = end_v.max(max_v);

        if line_height <= 0.0 {
            line_height = ch.char_box.top - ch.char_box.bottom;
        }
    }

    let double_lh = (2.0 * line_height) as usize;
    if end_v.saturating_sub(start_v) < double_lh {
        return TextFlowOrientation::Horizontal;
    }
    if end_h.saturating_sub(start_h) < double_lh {
        return TextFlowOrientation::Vertical;
    }

    let sum_h = mask_percent_filled(&h_mask, start_h, end_h);
    if sum_h > 0.8 {
        return TextFlowOrientation::Horizontal;
    }
    let sum_v = mask_percent_filled(&v_mask, start_v, end_v);
    if sum_h > sum_v {
        TextFlowOrientation::Horizontal
    } else if sum_h < sum_v {
        TextFlowOrientation::Vertical
    } else {
        TextFlowOrientation::Unknown
    }
}

/// Compute the percentage of `true` values in a mask slice.
fn mask_percent_filled(mask: &[bool], start: usize, end: usize) -> f32 {
    if start >= end {
        return 0.0;
    }
    let count = mask[start..end].iter().filter(|&&b| b).count();
    count as f32 / (end - start) as f32
}

/// Line-based orientation detection (backward-compatible wrapper).
///
/// Derives approximate character extents from line/word geometry
/// and delegates to the coverage mask algorithm.
fn detect_orientation_from_lines(lines: &[TextLine]) -> TextFlowOrientation {
    if lines.is_empty() {
        return TextFlowOrientation::Unknown;
    }

    let mut vertical_count = 0usize;
    let mut total_count = 0usize;

    for line in lines {
        if line.words.is_empty() {
            continue;
        }
        total_count += 1;
        let first = &line.words[0];
        let last = line.words.last().unwrap();
        let line_width = (last.x + last.width) - first.x;
        if line_width > 0.0 && line_width < line.height * 1.5 {
            vertical_count += 1;
        }
    }

    if total_count > 0 && vertical_count * 2 > total_count {
        TextFlowOrientation::Vertical
    } else {
        TextFlowOrientation::Horizontal
    }
}

pub use self::fx_bidi::reorder_bidi;
#[cfg(feature = "icu")]
use self::fx_bidi::reorder_bidi_with_direction;

fn column_index_for_line(line: &TextLine, columns: &[ColumnBound]) -> usize {
    if line.words.is_empty() {
        return 0;
    }
    let line_center = {
        let first = &line.words[0];
        let last = line.words.last().unwrap();
        (first.x + last.x + last.width) / 2.0
    };

    columns
        .iter()
        .enumerate()
        .min_by(|(_, a), (_, b)| {
            let mid_a = (a.x_start + a.x_end) / 2.0;
            let mid_b = (b.x_start + b.x_end) / 2.0;
            let dist_a = (line_center - mid_a).abs();
            let dist_b = (line_center - mid_b).abs();
            dist_a
                .partial_cmp(&dist_b)
                .unwrap_or(std::cmp::Ordering::Equal)
        })
        .map(|(idx, _)| idx)
        .unwrap_or(0)
}

/// Bounding rectangle for a character or merged selection region.
#[derive(Debug, Clone, PartialEq)]
pub struct CharRect {
    pub left: f32,
    pub bottom: f32,
    pub right: f32,
    pub top: f32,
}

/// Page-space origin of a character (upstream `CFX_PointF` from `CharInfo::origin_`).
///
/// Returned by [`TextPage::get_char_origin`] (upstream `FPDFText_GetCharOrigin`).
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CharOrigin {
    pub x: f32,
    pub y: f32,
}

/// Extracted text from a single PDF page, with character-level position data.
#[derive(Debug, Clone)]
pub struct TextPage {
    characters: Vec<TextCharacter>,
    text: String,
    /// Run IDs for each character (same length as `characters`).
    /// Internal tracking for `text_object()` / `text_by_object()`.
    run_ids: Vec<Option<u32>>,
}

impl TextPage {
    /// Create a new `TextPage` from extracted characters.
    ///
    /// Run IDs default to `None` for all characters. Use
    /// [`new_with_run_ids`](Self::new_with_run_ids) to supply run tracking data.
    pub fn new(characters: Vec<TextCharacter>) -> Self {
        let run_ids = vec![None; characters.len()];
        Self::new_with_run_ids(characters, run_ids, false)
    }

    /// Create a new `TextPage` with an explicit RTL direction hint.
    ///
    /// When `rtl` is true and the `icu` feature is enabled, bidi reordering
    /// uses RTL as the default paragraph direction.
    pub fn new_with_direction(characters: Vec<TextCharacter>, rtl: bool) -> Self {
        let run_ids = vec![None; characters.len()];
        Self::new_with_run_ids(characters, run_ids, rtl)
    }

    /// Create a new `TextPage` with run ID tracking and optional RTL hint.
    ///
    /// `run_ids` must have the same length as `characters`. Each entry maps
    /// a character to its originating text run (or `None` for generated characters).
    pub fn new_with_run_ids(
        characters: Vec<TextCharacter>,
        run_ids: Vec<Option<u32>>,
        rtl: bool,
    ) -> Self {
        debug_assert_eq!(characters.len(), run_ids.len());
        let mut characters = characters;
        let mut run_ids = run_ids;
        if rtl {
            #[cfg(feature = "icu")]
            reorder_bidi_with_direction(&mut characters, &mut run_ids, true);
            #[cfg(not(feature = "icu"))]
            reorder_bidi(&mut characters, &mut run_ids);
        } else {
            reorder_bidi(&mut characters, &mut run_ids);
        }
        // Rebuild text from reordered characters (bidi may change order)
        let text: String = characters.iter().map(|c| c.unicode).collect();
        let text = normalize_text(&text);
        Self {
            characters,
            text,
            run_ids,
        }
    }

    /// Returns all extracted text from the page (upstream `GetAllPageText`).
    pub fn all_page_text(&self) -> &str {
        &self.text
    }

    /// Upstream-aligned alias for [`all_page_text()`](Self::all_page_text).
    #[inline]
    pub fn get_all_page_text(&self) -> &str {
        self.all_page_text()
    }

    /// All extracted characters with position metadata.
    pub fn characters(&self) -> &[TextCharacter] {
        &self.characters
    }

    /// Returns the number of extracted characters (upstream `CountChars`).
    pub fn char_count(&self) -> usize {
        self.characters.len()
    }

    /// Upstream-aligned alias for [`char_count()`](Self::char_count).
    ///
    /// Corresponds to `FPDFText_CountChars`.
    #[inline]
    pub fn text_count_chars(&self) -> usize {
        self.char_count()
    }

    /// Use [`text_count_chars()`](Self::text_count_chars) instead (upstream `FPDFText_CountChars`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_count_chars()` (upstream `FPDFText_CountChars`)"
    )]
    #[inline]
    pub fn count_chars(&self) -> usize {
        self.char_count()
    }

    /// Returns the number of extracted characters.
    ///
    /// Upstream-aligned alias for [`char_count()`](Self::char_count).
    ///
    /// Corresponds to `CPDF_TextPage::size()`.
    #[inline]
    pub fn size(&self) -> usize {
        self.char_count()
    }

    // --- Indexed character property getters (upstream FPDF_Text alignment) ---

    /// Get a reference to the character at `index`, or `None` if out of bounds.
    fn get_char(&self, index: usize) -> Option<&TextCharacter> {
        self.characters.get(index)
    }

    /// Get the character info at `index` (upstream `CPDF_TextPage::GetCharInfo()`).
    ///
    /// Returns `None` if `index` is out of bounds.
    /// The returned `TextCharacter` holds unicode, char_code, char_box,
    /// font_size, font_name, matrix, loose_char_box, fill/stroke colors, and more.
    pub fn char_info(&self, index: usize) -> Option<&TextCharacter> {
        self.characters.get(index)
    }

    /// Upstream-aligned alias for [`char_info()`](Self::char_info).
    ///
    /// Corresponds to `CPDF_TextPage::GetCharInfo()`.
    #[inline]
    pub fn get_char_info(&self, index: usize) -> Option<&TextCharacter> {
        self.char_info(index)
    }

    /// Get the Unicode character at `index` (upstream `FPDFText_GetUnicode`).
    pub fn unicode(&self, index: usize) -> Option<char> {
        self.get_char(index).map(|c| c.unicode)
    }

    /// Upstream-aligned alias for [`unicode()`](Self::unicode).
    ///
    /// Corresponds to `FPDFText_GetUnicode`.
    #[inline]
    pub fn text_get_unicode(&self, index: usize) -> Option<char> {
        self.unicode(index)
    }

    /// Use [`text_get_unicode()`](Self::text_get_unicode) instead (upstream `FPDFText_GetUnicode`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_unicode()` (upstream `FPDFText_GetUnicode`)"
    )]
    #[inline]
    pub fn get_unicode(&self, index: usize) -> Option<char> {
        self.unicode(index)
    }

    /// Get the raw font encoding code before Unicode mapping at `index`
    /// (upstream `CharInfo::char_code`).
    ///
    /// Returns `0` for ActualText runs and generated spaces.
    pub fn char_code(&self, index: usize) -> Option<u32> {
        self.get_char(index).map(|c| c.char_code)
    }

    /// Alias for [`char_code()`](Self::char_code).
    ///
    /// Note: there is no upstream `FPDFText_GetCharCode` or `GetCharCode()`
    /// C/C++ function. `char_code` is a field on `CharInfo`, not a method on
    /// `CPDF_TextPage`. Use [`char_code()`](Self::char_code) directly.
    #[deprecated(
        since = "0.1.0",
        note = "Use `char_code()` directly; no upstream GetCharCode() method exists"
    )]
    #[inline]
    pub fn get_char_code(&self, index: usize) -> Option<u32> {
        self.char_code(index)
    }

    /// Check if the character at `index` is generated (upstream `FPDFText_IsGenerated`).
    pub fn is_generated(&self, index: usize) -> Option<bool> {
        self.get_char(index)
            .map(|c| c.char_type == CharType::Generated)
    }

    /// Upstream-aligned alias for [`is_generated()`](Self::is_generated).
    ///
    /// Corresponds to `FPDFText_IsGenerated`.
    #[inline]
    pub fn text_is_generated(&self, index: usize) -> Option<bool> {
        self.is_generated(index)
    }

    /// Check if the character at `index` is a hyphen (upstream `FPDFText_IsHyphen`).
    pub fn is_hyphen(&self, index: usize) -> Option<bool> {
        self.get_char(index)
            .map(|c| c.char_type == CharType::Hyphen || c.is_soft_hyphen)
    }

    /// Upstream-aligned alias for [`is_hyphen()`](Self::is_hyphen).
    ///
    /// Corresponds to `FPDFText_IsHyphen`.
    #[inline]
    pub fn text_is_hyphen(&self, index: usize) -> Option<bool> {
        self.is_hyphen(index)
    }

    /// Check if the character at `index` had a Unicode mapping error
    /// (upstream `FPDFText_HasUnicodeMapError`).
    pub fn has_unicode_map_error(&self, index: usize) -> Option<bool> {
        self.get_char(index)
            .map(|c| c.char_type == CharType::NotUnicode)
    }

    /// Upstream-aligned alias for [`has_unicode_map_error()`](Self::has_unicode_map_error).
    ///
    /// Corresponds to `FPDFText_HasUnicodeMapError`.
    #[inline]
    pub fn text_has_unicode_map_error(&self, index: usize) -> Option<bool> {
        self.has_unicode_map_error(index)
    }

    /// Get the font size of the character at `index`
    /// (upstream `CPDF_TextPage::GetCharFontSize()` / `FPDFText_GetFontSize`).
    pub fn font_size(&self, index: usize) -> Option<f32> {
        self.get_char(index).map(|c| c.font_size)
    }

    /// Upstream-aligned alias for [`font_size()`](Self::font_size).
    ///
    /// Corresponds to `CPDF_TextPage::GetCharFontSize()`.
    #[inline]
    pub fn get_char_font_size(&self, index: usize) -> Option<f32> {
        self.font_size(index)
    }

    /// Upstream-aligned alias for [`font_size()`](Self::font_size).
    ///
    /// Corresponds to `FPDFText_GetFontSize`.
    #[inline]
    pub fn text_get_font_size(&self, index: usize) -> Option<f32> {
        self.font_size(index)
    }

    /// Use [`text_get_font_size()`](Self::text_get_font_size) instead (upstream `FPDFText_GetFontSize`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_font_size()` (upstream `FPDFText_GetFontSize`)"
    )]
    #[inline]
    pub fn get_font_size(&self, index: usize) -> Option<f32> {
        self.font_size(index)
    }

    /// Get the font name of the character at `index` (upstream `FPDFText_GetFontInfo`).
    pub fn font_info(&self, index: usize) -> Option<&str> {
        self.get_char(index).map(|c| c.font_name.as_str())
    }

    /// Upstream-aligned alias for [`font_info()`](Self::font_info).
    ///
    /// Corresponds to `FPDFText_GetFontInfo`.
    #[inline]
    pub fn text_get_font_info(&self, index: usize) -> Option<&str> {
        self.font_info(index)
    }

    /// Use [`text_get_font_info()`](Self::text_get_font_info) instead (upstream `FPDFText_GetFontInfo`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_font_info()` (upstream `FPDFText_GetFontInfo`)"
    )]
    #[inline]
    pub fn get_font_info(&self, index: usize) -> Option<&str> {
        self.font_info(index)
    }

    /// Get the rotation angle of the character at `index` in radians,
    /// normalized to `[0, 2*PI)` (upstream `FPDFText_GetCharAngle`).
    pub fn char_angle(&self, index: usize) -> Option<f32> {
        self.get_char(index).map(|c| {
            let angle = c.matrix[1].atan2(c.matrix[0]);
            if angle < 0.0 {
                angle + std::f32::consts::TAU
            } else {
                angle
            }
        })
    }

    /// Upstream-aligned alias for [`char_angle()`](Self::char_angle).
    ///
    /// Corresponds to `FPDFText_GetCharAngle`.
    #[inline]
    pub fn text_get_char_angle(&self, index: usize) -> Option<f32> {
        self.char_angle(index)
    }

    /// Use [`text_get_char_angle()`](Self::text_get_char_angle) instead (upstream `FPDFText_GetCharAngle`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_char_angle()` (upstream `FPDFText_GetCharAngle`)"
    )]
    #[inline]
    pub fn get_char_angle(&self, index: usize) -> Option<f32> {
        self.char_angle(index)
    }

    /// Get the tight bounding box of the character at `index`
    /// (upstream `FPDFText_GetCharBox`).
    pub fn char_box(&self, index: usize) -> Option<CharRect> {
        self.get_char(index).map(|c| c.char_box.clone())
    }

    /// Upstream-aligned alias for [`char_box()`](Self::char_box).
    ///
    /// Corresponds to `FPDFText_GetCharBox`.
    #[inline]
    pub fn text_get_char_box(&self, index: usize) -> Option<CharRect> {
        self.char_box(index)
    }

    /// Use [`text_get_char_box()`](Self::text_get_char_box) instead (upstream `FPDFText_GetCharBox`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_char_box()` (upstream `FPDFText_GetCharBox`)"
    )]
    #[inline]
    pub fn get_char_box(&self, index: usize) -> Option<CharRect> {
        self.char_box(index)
    }

    /// Get the loose bounding box of the character at `index`, using font
    /// ascent/descent metrics
    /// (upstream `CPDF_TextPage::GetCharLooseBounds()` / `FPDFText_GetLooseCharBox`).
    ///
    /// Returns `None` if the index is out of bounds or the character has no
    /// loose box (e.g. generated/ActualText characters).
    pub fn loose_char_box(&self, index: usize) -> Option<CharRect> {
        self.get_char(index).and_then(|c| c.loose_char_box.clone())
    }

    /// Corresponds to internal `CPDF_TextPage::GetCharLooseBounds()` (not a public FPDF_* API).
    /// Use [`text_get_loose_char_box()`](Self::text_get_loose_char_box) — matches public
    /// upstream `FPDFText_GetLooseCharBox`.
    #[deprecated(
        note = "use `text_get_loose_char_box()` — matches upstream `FPDFText_GetLooseCharBox`"
    )]
    #[inline]
    pub fn get_char_loose_bounds(&self, index: usize) -> Option<CharRect> {
        self.loose_char_box(index)
    }

    /// Upstream-aligned alias for [`loose_char_box()`](Self::loose_char_box).
    ///
    /// Corresponds to `FPDFText_GetLooseCharBox`.
    #[inline]
    pub fn text_get_loose_char_box(&self, index: usize) -> Option<CharRect> {
        self.loose_char_box(index)
    }

    /// Use [`text_get_loose_char_box()`](Self::text_get_loose_char_box) instead (upstream `FPDFText_GetLooseCharBox`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_loose_char_box()` (upstream `FPDFText_GetLooseCharBox`)"
    )]
    #[inline]
    pub fn get_loose_char_box(&self, index: usize) -> Option<CharRect> {
        self.loose_char_box(index)
    }

    /// Get the text matrix `[a, b, c, d, e, f]` of the character at `index`
    /// (upstream `FPDFText_GetMatrix`).
    pub fn matrix(&self, index: usize) -> Option<[f32; 6]> {
        self.get_char(index).map(|c| c.matrix)
    }

    /// Upstream-aligned alias for [`matrix()`](Self::matrix).
    ///
    /// Corresponds to `FPDFText_GetMatrix`.
    #[inline]
    pub fn text_get_matrix(&self, index: usize) -> Option<[f32; 6]> {
        self.matrix(index)
    }

    /// Use [`text_get_matrix()`](Self::text_get_matrix) instead (upstream `FPDFText_GetMatrix`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_matrix()` (upstream `FPDFText_GetMatrix`)"
    )]
    #[inline]
    pub fn get_matrix(&self, index: usize) -> Option<[f32; 6]> {
        self.matrix(index)
    }

    /// Get the page-space origin of the character at `index`
    /// (upstream `FPDFText_GetCharOrigin`).
    pub fn char_origin(&self, index: usize) -> Option<CharOrigin> {
        self.get_char(index).map(|c| CharOrigin {
            x: c.matrix[4],
            y: c.matrix[5],
        })
    }

    /// Upstream-aligned alias for [`char_origin()`](Self::char_origin).
    ///
    /// Corresponds to `FPDFText_GetCharOrigin`.
    #[inline]
    pub fn text_get_char_origin(&self, index: usize) -> Option<CharOrigin> {
        self.char_origin(index)
    }

    /// Use [`text_get_char_origin()`](Self::text_get_char_origin) instead (upstream `FPDFText_GetCharOrigin`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_char_origin()` (upstream `FPDFText_GetCharOrigin`)"
    )]
    #[inline]
    pub fn get_char_origin(&self, index: usize) -> Option<CharOrigin> {
        self.char_origin(index)
    }

    /// Get the text run ID of the character at `index`
    /// (upstream `FPDFText_GetTextObject`).
    pub fn text_object(&self, index: usize) -> Option<u32> {
        self.run_ids.get(index).copied().flatten()
    }

    /// Upstream-aligned alias for [`text_object()`](Self::text_object).
    ///
    /// Corresponds to `FPDFText_GetTextObject`.
    #[inline]
    pub fn text_get_text_object(&self, index: usize) -> Option<u32> {
        self.text_object(index)
    }

    /// Deprecated: use [`text_get_text_object()`](Self::text_get_text_object) — matches upstream `FPDFText_GetTextObject`.
    #[deprecated(note = "use `text_get_text_object()` — matches upstream `FPDFText_GetTextObject`")]
    #[inline]
    pub fn get_text_object(&self, index: usize) -> Option<u32> {
        self.text_object(index)
    }

    /// Get the fill color of the character at `index`
    /// (upstream `FPDFText_GetFillColor`).
    pub fn fill_color(&self, index: usize) -> Option<&Color> {
        self.get_char(index).and_then(|c| c.fill_color.as_ref())
    }

    /// Upstream-aligned alias for [`fill_color()`](Self::fill_color).
    ///
    /// Corresponds to `FPDFText_GetFillColor`.
    #[inline]
    pub fn text_get_fill_color(&self, index: usize) -> Option<&Color> {
        self.fill_color(index)
    }

    /// Use [`text_get_fill_color()`](Self::text_get_fill_color) instead (upstream `FPDFText_GetFillColor`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_fill_color()` (upstream `FPDFText_GetFillColor`)"
    )]
    #[inline]
    pub fn get_fill_color(&self, index: usize) -> Option<&Color> {
        self.fill_color(index)
    }

    /// Get the stroke color of the character at `index`
    /// (upstream `FPDFText_GetStrokeColor`).
    pub fn stroke_color(&self, index: usize) -> Option<&Color> {
        self.get_char(index).and_then(|c| c.stroke_color.as_ref())
    }

    /// Upstream-aligned alias for [`stroke_color()`](Self::stroke_color).
    ///
    /// Corresponds to `FPDFText_GetStrokeColor`.
    #[inline]
    pub fn text_get_stroke_color(&self, index: usize) -> Option<&Color> {
        self.stroke_color(index)
    }

    /// Use [`text_get_stroke_color()`](Self::text_get_stroke_color) instead (upstream `FPDFText_GetStrokeColor`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_stroke_color()` (upstream `FPDFText_GetStrokeColor`)"
    )]
    #[inline]
    pub fn get_stroke_color(&self, index: usize) -> Option<&Color> {
        self.stroke_color(index)
    }

    /// Get the font weight of the character at `index` (100-900, CSS-style)
    /// (upstream `FPDFText_GetFontWeight`).
    pub fn font_weight(&self, index: usize) -> Option<i32> {
        self.get_char(index).and_then(|c| c.font_weight)
    }

    /// Upstream-aligned alias for [`font_weight()`](Self::font_weight).
    ///
    /// Corresponds to `FPDFText_GetFontWeight`.
    #[inline]
    pub fn text_get_font_weight(&self, index: usize) -> Option<i32> {
        self.font_weight(index)
    }

    /// Use [`text_get_font_weight()`](Self::text_get_font_weight) instead (upstream `FPDFText_GetFontWeight`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_font_weight()` (upstream `FPDFText_GetFontWeight`)"
    )]
    #[inline]
    pub fn get_font_weight(&self, index: usize) -> Option<i32> {
        self.font_weight(index)
    }

    /// Get the font descriptor flags of the character at `index`
    /// (upstream `FPDFText_GetFontInfo` flags output parameter).
    pub fn font_flags(&self, index: usize) -> Option<u32> {
        self.get_char(index).and_then(|c| c.font_flags)
    }

    /// No dedicated upstream `FPDF_Text_GetFontFlags` function exists; flags are a
    /// sub-value of [`text_get_font_info()`](Self::text_get_font_info).
    #[deprecated(
        note = "use `font_flags()` directly; no upstream `FPDFText_GetFontFlags()` method exists"
    )]
    #[inline]
    pub fn get_font_flags(&self, index: usize) -> Option<u32> {
        self.font_flags(index)
    }

    /// Get the text rendering mode of the character at `index`
    /// (upstream `FPDFTextObj_GetTextRenderMode`, cached at extraction time).
    pub fn char_render_mode(&self, index: usize) -> Option<TextRenderingMode> {
        self.get_char(index).map(|c| c.rendering_mode)
    }

    /// Deprecated — use [`char_render_mode()`](Self::char_render_mode).
    ///
    /// Note: there is no public `FPDFText_GetTextRenderMode` in the PDFium C API.
    /// The page-object-level API is `FPDFTextObj_GetTextRenderMode` (available as
    /// [`text_obj_get_text_render_mode()`](crate::textpage::TextPage) on `TextObject` in
    /// rpdfium-edit). The rendering mode is cached per character at text page extraction time.
    #[deprecated(
        note = "use `char_render_mode()` — no public `FPDFText_GetTextRenderMode`; for page-object API see `text_obj_get_text_render_mode()` on TextObject"
    )]
    #[inline]
    pub fn text_get_text_render_mode(&self, index: usize) -> Option<TextRenderingMode> {
        self.char_render_mode(index)
    }

    #[deprecated(
        note = "use `char_render_mode()` — no public `FPDFText_GetTextRenderMode`; for page-object API see `text_obj_get_text_render_mode()` on TextObject"
    )]
    #[inline]
    pub fn get_text_render_mode(&self, index: usize) -> Option<TextRenderingMode> {
        self.char_render_mode(index)
    }

    /// Get the fill color as RGBA u8 tuple.
    ///
    /// Convenience helper — not a direct upstream method.
    /// The upstream C API `FPDFText_GetFillColor` is covered by
    /// [`fill_color()`](Self::fill_color) / [`get_fill_color()`](Self::get_fill_color).
    pub fn fill_color_rgba(&self, index: usize) -> Option<(u8, u8, u8, u8)> {
        self.fill_color(index).map(|c| c.to_rgba_u8())
    }

    /// Get the stroke color as RGBA u8 tuple.
    ///
    /// Convenience helper — not a direct upstream method.
    /// The upstream C API `FPDFText_GetStrokeColor` is covered by
    /// [`stroke_color()`](Self::stroke_color) / [`get_stroke_color()`](Self::get_stroke_color).
    pub fn stroke_color_rgba(&self, index: usize) -> Option<(u8, u8, u8, u8)> {
        self.stroke_color(index).map(|c| c.to_rgba_u8())
    }

    /// Get text belonging to a specific text object (upstream `GetTextByObject`).
    ///
    /// Uses run IDs as proxy for the upstream `CPDF_TextObject*` pointer.
    /// Iterates all characters, collecting those matching the given run ID.
    /// Trailing spaces after matched characters are included.
    /// Line breaks (`\r\n`) are inserted when the Y position changes between
    /// non-adjacent matched characters.
    ///
    /// Corresponds to `CPDF_TextPage::GetTextByObject()`.
    pub fn text_by_object(&self, run_id: u32) -> String {
        let mut result = String::new();
        let mut prev_y: f32 = 0.0;
        let mut has_prev = false;
        let mut need_line_feed = false;

        for (ch, rid) in self.characters.iter().zip(self.run_ids.iter()) {
            if *rid == Some(run_id) {
                if need_line_feed
                    && !has_prev
                    && (prev_y - ch.char_box.bottom).abs() > 0.0
                    && !result.is_empty()
                {
                    result.push_str("\r\n");
                }
                prev_y = ch.char_box.bottom;
                has_prev = true;
                need_line_feed = false;
                if ch.unicode != '\0' {
                    result.push(ch.unicode);
                }
            } else if ch.unicode == ' ' {
                if has_prev {
                    result.push(' ');
                    has_prev = false;
                    need_line_feed = false;
                }
            } else {
                has_prev = false;
                need_line_feed = true;
            }
        }
        result
    }

    /// Upstream-aligned alias for [`text_by_object()`](Self::text_by_object).
    ///
    /// Corresponds to `CPDF_TextPage::GetTextByObject()`.
    #[inline]
    pub fn get_text_by_object(&self, run_id: u32) -> String {
        self.text_by_object(run_id)
    }

    /// Rust-idiomatic alias for [`text_by_object()`](Self::text_by_object).
    ///
    /// Prefer [`text_by_object()`](Self::text_by_object) which matches the upstream C++ name.
    #[deprecated(since = "0.1.0", note = "Use `text_by_object()` instead")]
    #[inline]
    pub fn text_by_run(&self, run_id: u32) -> String {
        self.text_by_object(run_id)
    }

    /// Check whether two characters (by index) belong to the same text object.
    ///
    /// Two characters are considered from the same text object if they have
    /// the same run ID. Falls back to comparing unicode, font name,
    /// and position within 1% tolerance when run IDs are not available.
    pub fn is_same_text_object(&self, a: usize, b: usize) -> bool {
        if let (Some(Some(id_a)), Some(Some(id_b))) = (self.run_ids.get(a), self.run_ids.get(b)) {
            return id_a == id_b;
        }
        // Fallback: position + font comparison
        if let (Some(ca), Some(cb)) = (self.get_char(a), self.get_char(b)) {
            let tolerance = ca.font_size * 0.01;
            ca.unicode == cb.unicode
                && ca.font_name == cb.font_name
                && (ca.char_box.left - cb.char_box.left).abs() < tolerance
                && (ca.char_box.bottom - cb.char_box.bottom).abs() < tolerance
        } else {
            false
        }
    }

    /// Extract links (URLs and email addresses) from the page text.
    pub fn extract_links(&self) -> Vec<crate::linkextract::Link> {
        crate::linkextract::extract_links(&self.text)
    }

    /// Upstream-aligned alias for [`extract_links()`](Self::extract_links).
    ///
    /// Corresponds to `FPDFLink_LoadWebLinks`.
    #[inline]
    pub fn link_load_web_links(&self) -> Vec<crate::linkextract::Link> {
        self.extract_links()
    }

    /// Use [`link_load_web_links()`](Self::link_load_web_links) instead (upstream `FPDFLink_LoadWebLinks`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `link_load_web_links()` (upstream `FPDFLink_LoadWebLinks`)"
    )]
    #[inline]
    pub fn load_web_links(&self) -> Vec<crate::linkextract::Link> {
        self.extract_links()
    }

    /// Return the page text with soft hyphens (U+00AD) removed and
    /// hyphenated words re-joined.
    pub fn text_without_soft_hyphens(&self) -> String {
        self.characters
            .iter()
            .filter(|c| !c.is_soft_hyphen)
            .map(|c| c.unicode)
            .collect()
    }

    /// Find the character index closest to the given position within tolerance.
    ///
    /// Matches upstream PDFium's `CPDF_TextPage::GetIndexAtPos` algorithm:
    /// 1. Direct hit (point inside char_box) → return immediately.
    /// 2. Tolerance: expand char_box by `x_tol/2` and `y_tol/2` on each side,
    ///    compute Manhattan distance to nearest edge, track minimum.
    pub fn index_at_pos(&self, x: f32, y: f32, x_tol: f32, y_tol: f32) -> Option<usize> {
        let mut nearest: Option<(usize, f32)> = None;
        for (i, ch) in self.characters.iter().enumerate() {
            let r = &ch.char_box;
            // Direct hit: point is inside the tight bounding box.
            if x >= r.left && x <= r.right && y >= r.bottom && y <= r.top {
                return Some(i);
            }
            // Skip if no tolerance is specified.
            if x_tol <= 0.0 && y_tol <= 0.0 {
                continue;
            }
            // Check expanded rect (char_box expanded by tol/2 on each side).
            let ext_left = r.left - x_tol / 2.0;
            let ext_right = r.right + x_tol / 2.0;
            let ext_bottom = r.bottom - y_tol / 2.0;
            let ext_top = r.top + y_tol / 2.0;
            if x < ext_left || x > ext_right || y < ext_bottom || y > ext_top {
                continue;
            }
            // Manhattan distance to nearest edge of the original (non-expanded) box.
            let dx = (x - r.left).abs().min((x - r.right).abs());
            let dy = (y - r.bottom).abs().min((y - r.top).abs());
            let dist = dx + dy;
            if nearest.is_none_or(|(_, d)| dist < d) {
                nearest = Some((i, dist));
            }
        }
        nearest.map(|(i, _)| i)
    }

    /// Upstream-aligned alias for [`index_at_pos()`](Self::index_at_pos).
    #[inline]
    pub fn get_index_at_pos(&self, x: f32, y: f32, x_tol: f32, y_tol: f32) -> Option<usize> {
        self.index_at_pos(x, y, x_tol, y_tol)
    }

    /// Find the character index at the given position with tolerance
    /// (upstream `FPDFText_GetCharIndexAtPos`).
    ///
    /// This is a convenience wrapper around [`index_at_pos()`](Self::index_at_pos)
    /// that accepts `f64` parameters to match the upstream C API signature.
    pub fn char_index_at_pos(&self, x: f64, y: f64, x_tol: f64, y_tol: f64) -> Option<usize> {
        self.index_at_pos(x as f32, y as f32, x_tol as f32, y_tol as f32)
    }

    /// Upstream-aligned alias for [`char_index_at_pos()`](Self::char_index_at_pos).
    ///
    /// Corresponds to `FPDFText_GetCharIndexAtPos`.
    #[inline]
    pub fn text_get_char_index_at_pos(
        &self,
        x: f64,
        y: f64,
        x_tol: f64,
        y_tol: f64,
    ) -> Option<usize> {
        self.char_index_at_pos(x, y, x_tol, y_tol)
    }

    /// Use [`text_get_char_index_at_pos()`](Self::text_get_char_index_at_pos) instead (upstream `FPDFText_GetCharIndexAtPos`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_char_index_at_pos()` (upstream `FPDFText_GetCharIndexAtPos`)"
    )]
    #[inline]
    pub fn get_char_index_at_pos(&self, x: f64, y: f64, x_tol: f64, y_tol: f64) -> Option<usize> {
        self.char_index_at_pos(x, y, x_tol, y_tol)
    }

    /// Get bounding rectangles for each character in range `[start, end)`.
    pub fn char_rects(&self, start: usize, end: usize) -> Vec<CharRect> {
        let end = end.min(self.characters.len());
        let start = start.min(end);
        self.characters[start..end]
            .iter()
            .map(|ch| ch.char_box.clone())
            .collect()
    }

    /// Get selection rectangles that merge adjacent same-run characters.
    ///
    /// Matches upstream PDFium's `CPDF_TextPage::GetRectArray` algorithm:
    /// - Skips `CharType::Generated` characters (synthesized spaces).
    /// - Skips zero-size bounding boxes (width or height below epsilon).
    /// - Merges consecutive characters that share the same non-None run ID
    ///   into a single rectangle (equivalent to grouping by text object).
    /// - Starts a new rectangle whenever the run ID changes.
    pub fn rect_array(&self, start: usize, end: usize) -> Vec<CharRect> {
        let end_clamped = end.min(self.characters.len());
        let start_clamped = start.min(end_clamped);
        if start_clamped >= end_clamped {
            return Vec::new();
        }

        let chars = &self.characters[start_clamped..end_clamped];
        let run_ids = &self.run_ids[start_clamped..end_clamped];

        const EPSILON: f32 = 1e-6;
        let mut merged: Vec<CharRect> = Vec::new();
        let mut current_run_id: Option<Option<u32>> = None;

        for (ch, &rid) in chars.iter().zip(run_ids.iter()) {
            // Skip generated (synthesized) characters.
            if ch.char_type == CharType::Generated {
                continue;
            }
            let r = &ch.char_box;
            // Skip zero-size boxes.
            let w = r.right - r.left;
            let h = r.top - r.bottom;
            if w < EPSILON || h < EPSILON {
                continue;
            }

            // Determine whether this character starts a new run group.
            // Two characters are in the same group iff they share the same
            // non-None run ID. None run IDs always start a new group.
            let same_run = match (current_run_id, rid) {
                (Some(Some(prev)), Some(curr)) => prev == curr,
                _ => false,
            };

            if same_run {
                let last = merged.last_mut().unwrap();
                last.left = last.left.min(r.left);
                last.bottom = last.bottom.min(r.bottom);
                last.right = last.right.max(r.right);
                last.top = last.top.max(r.top);
            } else {
                merged.push(r.clone());
                current_run_id = Some(rid);
            }
        }

        merged
    }

    /// Upstream-aligned alias for [`rect_array()`](Self::rect_array).
    #[inline]
    pub fn get_rect_array(&self, start: usize, end: usize) -> Vec<CharRect> {
        self.rect_array(start, end)
    }

    /// Count the bounding rectangles for characters in `[start_index, start_index + count)`.
    ///
    /// Corresponds to `FPDFText_CountRects()`.  Upstream caches the result for a
    /// subsequent `FPDFText_GetRect()` call; rpdfium computes this statelessly —
    /// call [`rect_array()`](Self::rect_array) to retrieve the rectangles directly.
    ///
    /// Returns the number of merged character rectangles, or `0` if out of range.
    pub fn rect_count(&self, start_index: usize, count: usize) -> usize {
        self.rect_array(start_index, start_index.saturating_add(count))
            .len()
    }

    /// Upstream-aligned alias for [`rect_count()`](Self::rect_count).
    ///
    /// Corresponds to `FPDFText_CountRects`.
    #[inline]
    pub fn text_count_rects(&self, start_index: usize, count: usize) -> usize {
        self.rect_count(start_index, count)
    }

    /// Use [`text_count_rects()`](Self::text_count_rects) instead (upstream `FPDFText_CountRects`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_count_rects()` (upstream `FPDFText_CountRects`)"
    )]
    #[inline]
    pub fn count_rects(&self, start_index: usize, count: usize) -> usize {
        self.rect_count(start_index, count)
    }

    /// Return the bounding rectangle at `rect_index` within the set computed for
    /// `[start_index, start_index + total_count)`.
    ///
    /// Corresponds to `FPDFText_GetRect()`. Upstream retrieves by index from an
    /// internal cache set by `FPDFText_CountRects()`; rpdfium recomputes statelessly.
    /// Prefer [`rect_array()`](Self::rect_array) when all rectangles are needed.
    ///
    /// Returns `None` if `rect_index` is out of range.
    pub fn rect_at(
        &self,
        start_index: usize,
        total_count: usize,
        rect_index: usize,
    ) -> Option<CharRect> {
        self.rect_array(start_index, start_index.saturating_add(total_count))
            .into_iter()
            .nth(rect_index)
    }

    /// Upstream-aligned alias for [`rect_at()`](Self::rect_at).
    ///
    /// Corresponds to `FPDFText_GetRect`.
    #[inline]
    pub fn text_get_rect(
        &self,
        start_index: usize,
        total_count: usize,
        rect_index: usize,
    ) -> Option<CharRect> {
        self.rect_at(start_index, total_count, rect_index)
    }

    /// Use [`text_get_rect()`](Self::text_get_rect) instead (upstream `FPDFText_GetRect`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_rect()` (upstream `FPDFText_GetRect`)"
    )]
    #[inline]
    pub fn get_rect(
        &self,
        start_index: usize,
        total_count: usize,
        rect_index: usize,
    ) -> Option<CharRect> {
        self.rect_at(start_index, total_count, rect_index)
    }

    /// Return the page text with line breaks (`\r\n`) inserted between lines.
    ///
    /// Uses [`segment_lines`] to detect
    /// line boundaries and joins consecutive lines with `\r\n`.
    pub fn text_with_line_breaks(&self) -> String {
        let lines = segment_lines(&self.characters);
        if lines.is_empty() {
            return String::new();
        }
        lines
            .iter()
            .map(|l| l.text.as_str())
            .collect::<Vec<_>>()
            .join("\r\n")
    }

    /// Extract text within a rectangular region (in page coordinates).
    ///
    /// Returns the concatenated Unicode characters whose origin falls
    /// within the rectangle defined by `(x1, y1)` (bottom-left) and
    /// `(x2, y2)` (top-right).
    pub fn text_by_rect(&self, x1: f32, y1: f32, x2: f32, y2: f32) -> String {
        self.characters
            .iter()
            .filter(|c| {
                c.char_box.left >= x1
                    && c.char_box.left <= x2
                    && c.char_box.bottom >= y1
                    && c.char_box.bottom <= y2
            })
            .map(|c| c.unicode)
            .collect()
    }

    /// ADR-019 alias for [`text_by_rect()`](Self::text_by_rect).
    ///
    /// Corresponds to `CPDF_TextPage::GetTextByRect`.
    #[inline]
    pub fn get_text_by_rect(&self, x1: f32, y1: f32, x2: f32, y2: f32) -> String {
        self.text_by_rect(x1, y1, x2, y2)
    }

    /// Return all text whose character boxes intersect the given rectangle
    /// (upstream `FPDFText_GetBoundedText`).
    ///
    /// Parameters use the upstream convention: `(left, top, right, bottom)`.
    /// This is a convenience wrapper around [`text_by_rect()`](Self::text_by_rect)
    /// that accepts `f64` parameters and reorders to `(left, bottom, right, top)`.
    pub fn text_in_rect(&self, left: f64, top: f64, right: f64, bottom: f64) -> String {
        self.text_by_rect(left as f32, bottom as f32, right as f32, top as f32)
    }

    /// Non-upstream convenience wrapper for [`text_in_rect()`](Self::text_in_rect).
    ///
    /// There is no `GetTextInRect()` in upstream PDFium. Use
    /// [`get_bounded_text()`](Self::get_bounded_text) which corresponds to the
    /// real upstream `FPDFText_GetBoundedText`.
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_in_rect()` or `get_bounded_text()` (upstream `FPDFText_GetBoundedText`) instead"
    )]
    #[inline]
    pub fn get_text_in_rect(&self, left: f64, top: f64, right: f64, bottom: f64) -> String {
        self.text_in_rect(left, top, right, bottom)
    }

    /// Upstream-aligned alias for [`text_in_rect()`](Self::text_in_rect).
    ///
    /// Corresponds to `FPDFText_GetBoundedText`.
    #[inline]
    pub fn text_get_bounded_text(&self, left: f64, top: f64, right: f64, bottom: f64) -> String {
        self.text_in_rect(left, top, right, bottom)
    }

    /// Use [`text_get_bounded_text()`](Self::text_get_bounded_text) instead (upstream `FPDFText_GetBoundedText`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_bounded_text()` (upstream `FPDFText_GetBoundedText`)"
    )]
    #[inline]
    pub fn get_bounded_text(&self, left: f64, top: f64, right: f64, bottom: f64) -> String {
        self.text_in_rect(left, top, right, bottom)
    }

    /// Get a substring of the page text starting at character index `start`
    /// for `count` characters (upstream `GetPageText(start, count)`).
    ///
    /// Indices are clamped to the character count.
    pub fn page_text(&self, start: usize, count: usize) -> String {
        let len = self.characters.len();
        let s = start.min(len);
        let e = (s + count).min(len);
        self.characters[s..e].iter().map(|c| c.unicode).collect()
    }

    /// Upstream-aligned alias for [`page_text()`](Self::page_text).
    #[inline]
    pub fn get_page_text(&self, start: usize, count: usize) -> String {
        self.page_text(start, count)
    }

    /// Upstream-aligned alias for [`page_text()`](Self::page_text).
    ///
    /// Corresponds to `FPDFText_GetText`.
    #[inline]
    pub fn text_get_text(&self, start: usize, count: usize) -> String {
        self.page_text(start, count)
    }

    /// Use [`text_get_text()`](Self::text_get_text) instead (upstream `FPDFText_GetText`).
    #[deprecated(
        since = "0.1.0",
        note = "Use `text_get_text()` (upstream `FPDFText_GetText`)"
    )]
    #[inline]
    pub fn get_text(&self, start: usize, count: usize) -> String {
        self.page_text(start, count)
    }

    /// Convert a text index (position in the full text string) to a
    /// character index (position in the characters array).
    ///
    /// # Identity mapping
    ///
    /// rpdfium uses an identity mapping (text index == char index) because
    /// every character stored in `self.characters` appears exactly once in
    /// `self.text`.  This contrasts with upstream PDFium, which maintains a
    /// separate `char_indices_` segment array to skip over "silent" kHyphen
    /// characters (U+FFFE) that are stored in `char_list_` but omitted from
    /// `text_buf_`.  rpdfium never inserts such silent characters into
    /// `self.characters`, so the mapping is always 1:1.
    ///
    /// Returns `None` if `text_index` is out of bounds (`≥ char_count()`).
    pub fn char_index_from_text_index(&self, text_index: usize) -> Option<usize> {
        if text_index < self.characters.len() {
            Some(text_index)
        } else {
            None
        }
    }

    /// Upstream-aligned alias for [`char_index_from_text_index()`](Self::char_index_from_text_index).
    ///
    /// Corresponds to `FPDFText_GetCharIndexFromTextIndex`.
    #[inline]
    pub fn text_get_char_index_from_text_index(&self, text_index: usize) -> Option<usize> {
        self.char_index_from_text_index(text_index)
    }

    /// Deprecated: use [`text_get_char_index_from_text_index()`](Self::text_get_char_index_from_text_index) — matches upstream `FPDFText_GetCharIndexFromTextIndex`.
    #[deprecated(
        note = "use `text_get_char_index_from_text_index()` — matches upstream `FPDFText_GetCharIndexFromTextIndex`"
    )]
    #[inline]
    pub fn get_char_index_from_text_index(&self, text_index: usize) -> Option<usize> {
        self.char_index_from_text_index(text_index)
    }

    /// Convert a character index (position in the characters array) to a
    /// text index (position in the full text string).
    ///
    /// # Identity mapping
    ///
    /// rpdfium uses an identity mapping (char index == text index) because
    /// every entry in `self.characters` maps directly to one position in
    /// `self.text`.  See [`char_index_from_text_index`](Self::char_index_from_text_index)
    /// for the rationale.
    ///
    /// Returns `None` if `char_index` is out of bounds (`≥ char_count()`).
    pub fn text_index_from_char_index(&self, char_index: usize) -> Option<usize> {
        if char_index < self.characters.len() {
            Some(char_index)
        } else {
            None
        }
    }

    /// Upstream-aligned alias for [`text_index_from_char_index()`](Self::text_index_from_char_index).
    ///
    /// Corresponds to `FPDFText_GetTextIndexFromCharIndex`.
    #[inline]
    pub fn text_get_text_index_from_char_index(&self, char_index: usize) -> Option<usize> {
        self.text_index_from_char_index(char_index)
    }

    /// Deprecated: use [`text_get_text_index_from_char_index()`](Self::text_get_text_index_from_char_index) — matches upstream `FPDFText_GetTextIndexFromCharIndex`.
    #[deprecated(
        note = "use `text_get_text_index_from_char_index()` — matches upstream `FPDFText_GetTextIndexFromCharIndex`"
    )]
    #[inline]
    pub fn get_text_index_from_char_index(&self, char_index: usize) -> Option<usize> {
        self.text_index_from_char_index(char_index)
    }

    /// Returns the index of the page object (in the edit layer) corresponding to the
    /// character at `char_index`, if any.
    ///
    /// # Not Supported
    ///
    /// Mapping text characters to page object indices requires cross-layer access
    /// between the text extraction layer and the edit layer, which is not currently
    /// wired up in rpdfium.
    ///
    /// Corresponds to `FPDFText_GetCharObject`.
    pub fn char_object_index(&self, _char_index: usize) -> Option<usize> {
        None
    }

    /// Upstream-aligned alias for [`char_object_index()`](Self::char_object_index).
    ///
    /// Corresponds to `FPDFText_GetCharObject`.
    #[inline]
    pub fn text_get_char_object(&self, char_index: usize) -> Option<usize> {
        self.char_object_index(char_index)
    }

    /// Deprecated — use [`text_get_char_object()`](Self::text_get_char_object) — matches upstream `FPDFText_GetCharObject`.
    #[deprecated(note = "use `text_get_char_object()` — matches upstream `FPDFText_GetCharObject`")]
    #[inline]
    pub fn get_char_object(&self, char_index: usize) -> Option<usize> {
        self.char_object_index(char_index)
    }

    /// Returns `true` if the character at `char_index` has an associated page object.
    ///
    /// Corresponds to `FPDFText_HasTextObjectForChar`.
    pub fn has_text_object_for_char(&self, char_index: usize) -> bool {
        self.char_object_index(char_index).is_some()
    }

    /// Get bounding rectangles for a link's text span.
    ///
    /// Converts the link's byte indices to character indices and
    /// delegates to [`rect_array()`](TextPage::rect_array).
    pub fn link_rects(&self, link: &crate::linkextract::Link) -> Vec<CharRect> {
        // Link indices are byte offsets in the text string.
        // Convert to char indices.
        let start_char = self.text[..link.start_index.min(self.text.len())]
            .chars()
            .count();
        let end_char = start_char
            + self.text[link.start_index.min(self.text.len())..link.end_index.min(self.text.len())]
                .chars()
                .count();
        self.rect_array(start_char, end_char)
    }
}

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

    /// Helper to build a `TextCharacter` with minimal defaults.
    fn make_char(unicode: char, x: f32, y: f32) -> TextCharacter {
        TextCharacter {
            unicode,
            char_code: unicode as u32,
            char_box: CharRect {
                left: x,
                bottom: y,
                right: x + 10.0,
                top: y + 12.0,
            },
            font_size: 12.0,
            font_name: "TestFont".to_string(),
            space_width: Some(4.0),
            is_soft_hyphen: false,
            char_type: CharType::Normal,
            matrix: [1.0, 0.0, 0.0, 1.0, x, y],
            loose_char_box: None,
            fill_color: None,
            stroke_color: None,
            font_weight: None,
            font_flags: None,
            rendering_mode: TextRenderingMode::Fill,
        }
    }

    // --- Phase A: TextCharacter field tests ---

    #[test]
    fn test_text_character_has_char_code_field() {
        let ch = make_char('A', 0.0, 0.0);
        assert_eq!(ch.char_code, 65);
    }

    #[test]
    fn test_text_character_has_matrix_field() {
        let ch = make_char('B', 10.0, 20.0);
        assert_eq!(ch.matrix, [1.0, 0.0, 0.0, 1.0, 10.0, 20.0]);
    }

    #[test]
    fn test_get_text_object_via_run_ids() {
        let chars = vec![make_char('C', 0.0, 0.0)];
        let run_ids = vec![Some(42)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert_eq!(page.text_object(0), Some(42));
    }

    #[test]
    fn test_char_type_not_unicode_variant() {
        let ct = CharType::NotUnicode;
        assert_ne!(ct, CharType::Normal);
        assert_eq!(ct, CharType::NotUnicode);
    }

    // --- Phase B: loose_char_box tests ---

    #[test]
    fn test_compute_loose_char_box_identity_matrix() {
        let rect = compute_loose_char_box(
            10.0, 20.0, 8.0, 12.0, // x, y, width, font_size
            750.0, -250.0, // ascent, descent
            1.0, 0.0, 0.0, 1.0, // identity matrix
        );
        // Descent = -250 * 12 / 1000 = -3.0
        // Ascent  = 750 * 12 / 1000 = 9.0
        assert!(rect.left <= 10.0);
        assert!(rect.bottom < 20.0);
        assert!(rect.right >= 18.0);
        assert!(rect.top > 20.0);
    }

    #[test]
    fn test_compute_loose_char_box_scaled_matrix() {
        let rect = compute_loose_char_box(0.0, 0.0, 16.0, 12.0, 750.0, -250.0, 2.0, 0.0, 0.0, 2.0);
        // Width of 16.0 at scale 2 → text-space width = 8
        // Vertical: descent = -3 * 2 = -6, ascent = 9 * 2 = 18
        assert!(rect.top > 0.0);
        assert!(rect.bottom < 0.0);
    }

    #[test]
    fn test_compute_loose_char_box_vertical_identity_matrix() {
        // vert_origin_y = 880, vert_w1y = -1000 (typical CJK defaults)
        // font_size = 12, identity matrix
        // top_page    = 880 * 12 / 1000 = 10.56
        // bottom_page = (880 + -1000) * 12 / 1000 = -120 * 12 / 1000 = -1.44
        let rect = compute_loose_char_box_vertical(
            0.0, 0.0, // x, y (origin)
            10.0, 12.0, // width, font_size
            880.0, -1000.0, // vert_origin_y, vert_w1y
            1.0, 0.0, 0.0, 1.0, // identity matrix
        );
        // top should be above writing position (positive)
        assert!(rect.top > 0.0, "top={}", rect.top);
        // bottom should be below writing position (negative)
        assert!(rect.bottom < 0.0, "bottom={}", rect.bottom);
        // right should be > left (valid width)
        assert!(rect.right > rect.left);
        // approximate values
        assert!((rect.top - 10.56).abs() < 0.01, "top={}", rect.top);
        assert!(
            (rect.bottom - (-1.44)).abs() < 0.01,
            "bottom={}",
            rect.bottom
        );
    }

    #[test]
    fn test_compute_loose_char_box_vertical_with_offset() {
        // With a non-zero origin: x=5, y=100
        // vert_origin_y=880, vert_w1y=-1000, font_size=10, identity matrix
        // top_page    = 880 * 10 / 1000 = 8.8 → abs top  = 100 + 8.8 = 108.8
        // bottom_page = (880 - 1000) * 10 / 1000 = -1.2 → abs bot = 100 - 1.2 = 98.8
        let rect = compute_loose_char_box_vertical(
            5.0, 100.0, 10.0, 10.0, 880.0, -1000.0, 1.0, 0.0, 0.0, 1.0,
        );
        assert!((rect.top - 108.8).abs() < 0.01, "top={}", rect.top);
        assert!((rect.bottom - 98.8).abs() < 0.01, "bottom={}", rect.bottom);
    }

    #[test]
    fn test_loose_char_box_is_none_for_generated_chars() {
        let mut ch = make_char(' ', 0.0, 0.0);
        ch.char_type = CharType::Generated;
        ch.loose_char_box = None;
        assert!(ch.loose_char_box.is_none());
    }

    // --- Phase C: TextPage methods ---

    #[test]
    fn test_get_page_text_basic() {
        let chars = vec![make_char('H', 0.0, 0.0), make_char('i', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.page_text(0, 2), "Hi");
        assert_eq!(page.page_text(0, 1), "H");
        assert_eq!(page.page_text(1, 1), "i");
    }

    #[test]
    fn test_get_page_text_clamped() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.page_text(0, 100), "AB");
        assert_eq!(page.page_text(5, 10), "");
    }

    #[test]
    fn test_char_index_from_text_index_identity() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.char_index_from_text_index(0), Some(0));
        assert_eq!(page.char_index_from_text_index(1), Some(1));
        assert_eq!(page.char_index_from_text_index(2), None);
    }

    #[test]
    fn test_text_index_from_char_index_identity() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.text_index_from_char_index(0), Some(0));
        assert_eq!(page.text_index_from_char_index(1), Some(1));
        assert_eq!(page.text_index_from_char_index(2), None);
    }

    #[test]
    fn test_is_same_text_object_same_run() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let run_ids = vec![Some(5), Some(5)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert!(page.is_same_text_object(0, 1));
    }

    #[test]
    fn test_is_same_text_object_different_run() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let run_ids = vec![Some(5), Some(6)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert!(!page.is_same_text_object(0, 1));
    }

    #[test]
    fn test_is_same_text_object_fallback_no_run_id() {
        let chars = vec![make_char('A', 10.0, 20.0), make_char('A', 10.05, 20.05)];
        let run_ids = vec![None, None];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        // Within 1% of font_size (0.12) → same
        assert!(page.is_same_text_object(0, 1));
    }

    #[test]
    fn test_is_same_text_object_fallback_different_position() {
        let chars = vec![make_char('A', 10.0, 20.0), make_char('A', 50.0, 20.0)];
        let run_ids = vec![None, None];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert!(!page.is_same_text_object(0, 1));
    }

    // --- TextExtractor constructor tests ---

    #[test]
    fn test_text_extractor_default_not_rtl() {
        let ext = TextExtractor::new();
        assert!(!ext.is_rtl());
    }

    #[test]
    fn test_text_extractor_with_rtl() {
        let ext = TextExtractor::with_rtl(true);
        assert!(ext.is_rtl());
    }

    #[test]
    fn test_text_extractor_with_rtl_false() {
        let ext = TextExtractor::with_rtl(false);
        assert!(!ext.is_rtl());
    }

    // --- TextPage new_with_direction ---

    #[test]
    fn test_text_page_new_with_direction_false() {
        let chars = vec![make_char('H', 0.0, 0.0), make_char('i', 10.0, 0.0)];
        let page = TextPage::new_with_direction(chars, false);
        assert_eq!(page.all_page_text(), "Hi");
    }

    #[test]
    fn test_text_page_new_with_direction_true() {
        let chars = vec![make_char('H', 0.0, 0.0), make_char('i', 10.0, 0.0)];
        let page = TextPage::new_with_direction(chars, true);
        // LTR text with RTL hint: bidi reordering may or may not reorder
        // plain LTR text, but the result should still be valid
        assert_eq!(page.char_count(), 2);
    }

    // --- link_rects ---

    // --- Phase D: Indexed getter tests ---

    #[test]
    fn test_get_unicode_returns_char() {
        let chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.unicode(0), Some('A'));
        assert_eq!(page.unicode(1), Some('B'));
        assert_eq!(page.unicode(2), None);
    }

    #[test]
    fn test_is_generated_false_for_normal() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.is_generated(0), Some(false));
    }

    #[test]
    fn test_is_generated_true_for_generated() {
        let mut ch = make_char(' ', 0.0, 0.0);
        ch.char_type = CharType::Generated;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.is_generated(0), Some(true));
    }

    #[test]
    fn test_is_generated_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert_eq!(page.is_generated(0), None);
    }

    #[test]
    fn test_is_hyphen_true_for_hyphen_char_type() {
        let mut ch = make_char('-', 0.0, 0.0);
        ch.char_type = CharType::Hyphen;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.is_hyphen(0), Some(true));
    }

    #[test]
    fn test_is_hyphen_true_for_soft_hyphen() {
        let mut ch = make_char('\u{00AD}', 0.0, 0.0);
        ch.is_soft_hyphen = true;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.is_hyphen(0), Some(true));
    }

    #[test]
    fn test_is_hyphen_false_for_normal() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.is_hyphen(0), Some(false));
    }

    #[test]
    fn test_has_unicode_map_error_true_for_not_unicode() {
        let mut ch = make_char('\u{FFFD}', 0.0, 0.0);
        ch.char_type = CharType::NotUnicode;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.has_unicode_map_error(0), Some(true));
    }

    #[test]
    fn test_has_unicode_map_error_false_for_normal() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.has_unicode_map_error(0), Some(false));
    }

    #[test]
    fn test_get_font_size_returns_size() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.font_size(0), Some(12.0));
        assert_eq!(page.font_size(1), None);
    }

    #[test]
    fn test_get_font_info_returns_name() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.font_info(0), Some("TestFont"));
        assert_eq!(page.font_info(1), None);
    }

    #[test]
    fn test_get_char_angle_identity_matrix() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        let angle = page.char_angle(0).unwrap();
        // atan2(0, 1) = 0
        assert!(angle.abs() < 0.001);
    }

    #[test]
    fn test_get_char_angle_rotated() {
        let mut ch = make_char('A', 0.0, 0.0);
        // 90-degree rotation: a=0, b=1, c=-1, d=0
        ch.matrix = [0.0, 1.0, -1.0, 0.0, 0.0, 0.0];
        let page = TextPage::new(vec![ch]);
        let angle = page.char_angle(0).unwrap();
        assert!((angle - std::f32::consts::FRAC_PI_2).abs() < 0.001);
    }

    #[test]
    fn test_get_char_angle_negative_normalized() {
        let mut ch = make_char('A', 0.0, 0.0);
        // -90 degree rotation: a=0, b=-1
        ch.matrix = [0.0, -1.0, 1.0, 0.0, 0.0, 0.0];
        let page = TextPage::new(vec![ch]);
        let angle = page.char_angle(0).unwrap();
        // Should be normalized to >= 0 (3*PI/2)
        assert!(angle >= 0.0);
        assert!((angle - 3.0 * std::f32::consts::FRAC_PI_2).abs() < 0.001);
    }

    #[test]
    fn test_get_char_box_basic() {
        let chars = vec![make_char('A', 10.0, 20.0)];
        let page = TextPage::new(chars);
        let rect = page.char_box(0).unwrap();
        assert_eq!(rect.left, 10.0);
        assert_eq!(rect.bottom, 20.0);
        assert_eq!(rect.right, 20.0); // 10 + width(10)
        assert_eq!(rect.top, 32.0); // 20 + height(12)
    }

    #[test]
    fn test_get_char_box_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert!(page.char_box(0).is_none());
    }

    #[test]
    fn test_get_loose_char_box_none_when_absent() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        // make_char sets loose_char_box to None
        assert!(page.loose_char_box(0).is_none());
    }

    #[test]
    fn test_get_loose_char_box_some_when_present() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.loose_char_box = Some(CharRect {
            left: -1.0,
            bottom: -3.0,
            right: 11.0,
            top: 9.0,
        });
        let page = TextPage::new(vec![ch]);
        let rect = page.loose_char_box(0).unwrap();
        assert_eq!(rect.left, -1.0);
        assert_eq!(rect.top, 9.0);
    }

    #[test]
    fn test_get_matrix_returns_matrix() {
        let chars = vec![make_char('A', 5.0, 10.0)];
        let page = TextPage::new(chars);
        let m = page.matrix(0).unwrap();
        assert_eq!(m, [1.0, 0.0, 0.0, 1.0, 5.0, 10.0]);
        assert!(page.matrix(1).is_none());
    }

    #[test]
    fn test_get_char_origin_returns_ef() {
        let chars = vec![make_char('A', 100.0, 200.0)];
        let page = TextPage::new(chars);
        let o = page.char_origin(0).unwrap();
        assert_eq!(o.x, 100.0);
        assert_eq!(o.y, 200.0);
    }

    #[test]
    fn test_get_text_object_returns_run_id() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let run_ids = vec![Some(42)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert_eq!(page.text_object(0), Some(42));
    }

    #[test]
    fn test_get_text_object_none_for_generated() {
        let mut ch = make_char(' ', 0.0, 0.0);
        ch.char_type = CharType::Generated;
        let run_ids = vec![None];
        let page = TextPage::new_with_run_ids(vec![ch], run_ids, false);
        assert_eq!(page.text_object(0), None);
    }

    #[test]
    fn test_get_fill_color_none_by_default() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert!(page.fill_color(0).is_none());
    }

    #[test]
    fn test_get_fill_color_some_when_set() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.fill_color = Some(Color::rgb(1.0, 0.0, 0.0));
        let page = TextPage::new(vec![ch]);
        let color = page.fill_color(0).unwrap();
        assert_eq!(color.components[0], 1.0);
        assert_eq!(color.components[1], 0.0);
    }

    #[test]
    fn test_get_stroke_color_none_by_default() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert!(page.stroke_color(0).is_none());
    }

    #[test]
    fn test_get_stroke_color_some_when_set() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.stroke_color = Some(Color::gray(0.5));
        let page = TextPage::new(vec![ch]);
        let color = page.stroke_color(0).unwrap();
        assert_eq!(color.components[0], 0.5);
    }

    #[test]
    fn test_get_font_weight_none_by_default() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.font_weight(0), None);
    }

    #[test]
    fn test_get_font_weight_some_when_set() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.font_weight = Some(700);
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.font_weight(0), Some(700));
    }

    #[test]
    fn test_get_font_weight_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert_eq!(page.font_weight(0), None);
    }

    #[test]
    fn test_link_rects_basic() {
        let chars: Vec<TextCharacter> = "Hello"
            .chars()
            .enumerate()
            .map(|(i, c)| make_char(c, i as f32 * 10.0, 0.0))
            .collect();
        // All 5 chars share run ID 1 — they merge into a single rect.
        let run_ids: Vec<Option<u32>> = vec![Some(1); 5];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        let link = crate::linkextract::Link {
            url: "Hello".to_string(),
            start_index: 0,
            end_index: 5,
            kind: crate::linkextract::LinkKind::WebUrl,
        };
        let rects = page.link_rects(&link);
        assert!(!rects.is_empty());
        // All chars share the same run ID — should merge to 1 rect.
        assert_eq!(rects.len(), 1);
    }

    // --- G1: font_flags getter tests ---

    #[test]
    fn test_get_font_flags_none_by_default() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.font_flags(0), None);
    }

    #[test]
    fn test_get_font_flags_returns_value() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.font_flags = Some(0x42); // Serif + Symbolic
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.font_flags(0), Some(0x42));
    }

    #[test]
    fn test_get_font_flags_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert_eq!(page.font_flags(0), None);
    }

    // --- G2: RGBA convenience getter tests ---

    #[test]
    fn test_get_fill_color_rgba_returns_tuple() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.fill_color = Some(Color::rgb(1.0, 0.0, 0.0));
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.fill_color_rgba(0), Some((255, 0, 0, 255)));
    }

    #[test]
    fn test_get_stroke_color_rgba_returns_tuple() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.stroke_color = Some(Color::rgb(0.0, 1.0, 0.0));
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.stroke_color_rgba(0), Some((0, 255, 0, 255)));
    }

    #[test]
    fn test_get_fill_color_rgba_none_when_no_color() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.fill_color_rgba(0), None);
    }

    // --- G3: text_by_object / get_text_by_object tests ---

    #[test]
    fn test_text_by_object_single_run() {
        let chars = vec![make_char('H', 0.0, 0.0), make_char('i', 10.0, 0.0)];
        let run_ids = vec![Some(1), Some(1)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert_eq!(page.text_by_object(1), "Hi");
    }

    #[test]
    fn test_text_by_object_nonexistent() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let run_ids = vec![Some(1)];
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        assert_eq!(page.text_by_object(99), "");
    }

    #[test]
    fn test_text_by_object_with_trailing_space() {
        let mut chars = vec![make_char('A', 0.0, 0.0), make_char('B', 10.0, 0.0)];
        let mut run_ids: Vec<Option<u32>> = vec![Some(1), Some(1)];
        // Add a space after the run
        let mut sp = make_char(' ', 20.0, 0.0);
        sp.char_type = CharType::Generated;
        chars.push(sp);
        run_ids.push(None);
        // Add a different run
        chars.push(make_char('X', 30.0, 0.0));
        run_ids.push(Some(2));
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        // Trailing space after run 1 should be included
        assert_eq!(page.text_by_object(1), "AB ");
    }

    #[test]
    fn test_text_by_object_multi_line() {
        let mut chars = vec![make_char('A', 0.0, 100.0), make_char('B', 10.0, 100.0)];
        let mut run_ids: Vec<Option<u32>> = vec![Some(1), Some(1)];
        // Different run on a different line
        chars.push(make_char('C', 0.0, 80.0));
        run_ids.push(Some(2));
        // Same run 1 on a new line
        chars.push(make_char('D', 0.0, 60.0));
        run_ids.push(Some(1));
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        let text = page.text_by_object(1);
        assert!(text.contains("AB"));
        assert!(text.contains("D"));
        // Line break between AB and D
        assert!(text.contains("\r\n"));
    }

    // --- A1: NormalizeThreshold tests ---

    #[test]
    fn test_normalize_threshold_below_t1() {
        // threshold < 300 → threshold / 2.0
        let result = normalize_threshold(200.0, 300, 500, 700);
        assert!((result - 100.0).abs() < 0.01);
    }

    #[test]
    fn test_normalize_threshold_between_t1_t2() {
        // 300 <= threshold < 500 → threshold / 4.0
        let result = normalize_threshold(400.0, 300, 500, 700);
        assert!((result - 100.0).abs() < 0.01);
    }

    #[test]
    fn test_normalize_threshold_between_t2_t3() {
        // 500 <= threshold < 700 → threshold / 5.0
        let result = normalize_threshold(600.0, 300, 500, 700);
        assert!((result - 120.0).abs() < 0.01);
    }

    #[test]
    fn test_normalize_threshold_above_t3() {
        // threshold >= 700 → threshold / 6.0
        let result = normalize_threshold(900.0, 300, 500, 700);
        assert!((result - 150.0).abs() < 0.01);
    }

    #[test]
    fn test_normalize_threshold_zero() {
        let result = normalize_threshold(0.0, 300, 500, 700);
        assert!((result - 0.0).abs() < 0.01);
    }

    // --- A2: Orientation detection tests ---

    #[test]
    fn test_detect_orientation_empty() {
        let result = detect_orientation(&[], 612.0, 792.0);
        assert_eq!(result, TextFlowOrientation::Unknown);
    }

    #[test]
    fn test_detect_orientation_horizontal_text() {
        // Wide characters spread across the page horizontally
        let chars: Vec<TextCharacter> = (0..20)
            .map(|i| {
                let mut c = make_char('A', i as f32 * 30.0, 700.0);
                c.char_box = CharRect {
                    left: c.char_box.left,
                    bottom: c.char_box.bottom,
                    right: c.char_box.left + 25.0,
                    top: c.char_box.bottom + 12.0,
                };
                c
            })
            .collect();
        let result = detect_orientation(&chars, 612.0, 792.0);
        assert_eq!(result, TextFlowOrientation::Horizontal);
    }

    #[test]
    fn test_detect_orientation_vertical_text() {
        // Narrow characters stacked vertically
        let chars: Vec<TextCharacter> = (0..20)
            .map(|i| {
                let mut c = make_char('A', 500.0, 700.0 - i as f32 * 30.0);
                c.char_box = CharRect {
                    left: c.char_box.left,
                    bottom: c.char_box.bottom,
                    right: c.char_box.left + 12.0,
                    top: c.char_box.bottom + 25.0,
                };
                c
            })
            .collect();
        let result = detect_orientation(&chars, 612.0, 792.0);
        assert_eq!(result, TextFlowOrientation::Vertical);
    }

    #[test]
    fn test_detect_orientation_zero_dimensions() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let result = detect_orientation(&chars, 0.0, 0.0);
        assert_eq!(result, TextFlowOrientation::Unknown);
    }

    // --- Bidi reordering tests (audit gap: no bidirectional integration tests) ---

    #[test]
    fn test_bidi_reordering_rtl_chars_reordered() {
        // Arabic characters: BA (U+0628) and ALEF (U+0627) — both have bidi class AL.
        // TextPage::new() calls reorder_bidi(), which may reorder them visually.
        // Regardless of reordering, all characters must be preserved.
        let chars = vec![
            make_char('\u{0628}', 10.0, 0.0), // ب BA
            make_char('\u{0627}', 0.0, 0.0),  // ا ALEF
        ];
        let page = TextPage::new(chars);
        assert_eq!(
            page.char_count(),
            2,
            "bidi reordering must not lose Arabic characters"
        );
        let text = page.all_page_text();
        assert!(
            text.contains('\u{0628}') && text.contains('\u{0627}'),
            "both Arabic characters must be present after bidi reordering, got: {:?}",
            text
        );
    }

    #[test]
    fn test_bidi_reordering_mixed_ltr_rtl() {
        // Mix of Latin LTR characters and Arabic RTL characters.
        // Bidi reordering may change visual order but must preserve all chars.
        let chars = vec![
            make_char('H', 0.0, 0.0),
            make_char('i', 10.0, 0.0),
            make_char('\u{0627}', 20.0, 0.0), // ا ALEF (RTL)
            make_char('\u{0628}', 30.0, 0.0), // ب BA (RTL)
        ];
        let page = TextPage::new(chars);
        assert_eq!(
            page.char_count(),
            4,
            "mixed bidi must preserve all 4 characters"
        );
        let text = page.all_page_text();
        assert!(
            text.contains('H') && text.contains('i'),
            "LTR characters must survive bidi reordering: {:?}",
            text
        );
        assert!(
            text.contains('\u{0627}') && text.contains('\u{0628}'),
            "RTL characters must survive bidi reordering: {:?}",
            text
        );
    }

    // --- Large-page / stress tests (upstream analogue: BigtableTextExtraction, Bug921, CountRects, TextSearch) ---

    #[test]
    fn test_large_page_count_chars_500() {
        // Upstream analogue: FPDFText_CountChars on a large page.
        // Bug921 embedder test uses 278 chars; scaled here to 500.
        let chars: Vec<TextCharacter> = (0..500u32)
            .map(|i| {
                let col = (i % 50) as f32;
                let row = (i / 50) as f32;
                let ch = (b'A' + (i % 26) as u8) as char;
                make_char(ch, col * 10.0, 700.0 - row * 20.0)
            })
            .collect();
        let page = TextPage::new(chars);
        assert_eq!(page.char_count(), 500);
    }

    #[test]
    fn test_large_page_get_page_text_complete() {
        // Upstream analogue: FPDFText_GetText looping all chars on a large page
        // (Bug921 embedder test loops all 278 chars; scaled here to 500).
        // Verifies get_all_page_text() and get_page_text(start, count) are consistent.
        let chars: Vec<TextCharacter> = (0..500u32)
            .map(|i| {
                let col = (i % 50) as f32;
                let row = (i / 50) as f32;
                let ch = (b'A' + (i % 26) as u8) as char;
                make_char(ch, col * 10.0, 700.0 - row * 20.0)
            })
            .collect();
        let expected: String = (0..500u32)
            .map(|i| (b'A' + (i % 26) as u8) as char)
            .collect();
        let page = TextPage::new(chars);
        assert_eq!(page.all_page_text(), expected);
        // Subrange: chars 10..20
        let sub: String = (10..20u32)
            .map(|i| (b'A' + (i % 26) as u8) as char)
            .collect();
        assert_eq!(page.page_text(10, 10), sub);
    }

    #[test]
    fn test_large_page_all_char_getters_return_some() {
        // Upstream analogue: FPDFText_GetUnicode / GetFontSize / GetCharBox /
        // GetMatrix / GetCharOrigin / IsGenerated / IsHyphen / HasUnicodeMapError
        // for every valid index.
        // BigtableTextExtraction loops all 65 chars; scaled here to 300.
        let chars: Vec<TextCharacter> = (0..300u32)
            .map(|i| make_char((b'A' + (i % 26) as u8) as char, i as f32 * 10.0, 700.0))
            .collect();
        let page = TextPage::new(chars);
        for i in 0..300 {
            assert!(page.unicode(i).is_some(), "get_unicode({i})");
            assert!(page.char_code(i).is_some(), "get_char_code({i})");
            assert!(page.font_size(i).is_some(), "get_font_size({i})");
            assert!(page.font_info(i).is_some(), "get_font_info({i})");
            assert!(page.char_angle(i).is_some(), "get_char_angle({i})");
            assert!(page.char_box(i).is_some(), "get_char_box({i})");
            assert!(page.matrix(i).is_some(), "get_matrix({i})");
            assert!(page.char_origin(i).is_some(), "get_char_origin({i})");
            assert!(page.is_generated(i).is_some(), "is_generated({i})");
            assert!(page.is_hyphen(i).is_some(), "is_hyphen({i})");
            assert!(
                page.has_unicode_map_error(i).is_some(),
                "has_unicode_map_error({i})"
            );
        }
        // Out-of-bounds must return None (upstream: invalid index returns false/−1)
        assert!(page.unicode(300).is_none());
        assert!(page.char_box(300).is_none());
        assert!(page.char_origin(300).is_none());
        assert!(page.matrix(300).is_none());
    }

    #[test]
    fn test_large_page_char_box_valid_bounds() {
        // Upstream analogue: CharBox test extended to large N.
        // Upstream checks exact char-box dimensions for 9 chars in font_matrix.pdf;
        // here we verify the structural invariant (left ≤ right, bottom ≤ top) for 200 chars.
        let chars: Vec<TextCharacter> = (0..200u32)
            .map(|i| make_char('A', i as f32 * 12.0, 500.0))
            .collect();
        let page = TextPage::new(chars);
        for i in 0..200 {
            let rect = page.char_box(i).expect("get_char_box should be Some");
            assert!(
                rect.right >= rect.left,
                "rect.right >= rect.left violated at index {i}"
            );
            assert!(
                rect.top >= rect.bottom,
                "rect.top >= rect.bottom violated at index {i}"
            );
        }
    }

    #[test]
    fn test_large_page_char_origin_matches_matrix_ef() {
        // Upstream analogue: FPDFText_GetCharOrigin returns (matrix.e, matrix.f) per spec.
        // The GetMatrix embedder test verifies this relationship; here we verify
        // the invariant holds for all 200 characters.
        let chars: Vec<TextCharacter> = (0..200u32)
            .map(|i| make_char('X', i as f32 * 7.5, 300.0 + (i % 10) as f32 * 15.0))
            .collect();
        let page = TextPage::new(chars);
        for i in 0..200 {
            let origin = page.char_origin(i).expect("get_char_origin should be Some");
            let matrix = page.matrix(i).expect("get_matrix should be Some");
            assert_eq!(
                origin.x, matrix[4],
                "CharOrigin.x != matrix[4] at index {i}"
            );
            assert_eq!(
                origin.y, matrix[5],
                "CharOrigin.y != matrix[5] at index {i}"
            );
        }
    }

    #[test]
    fn test_large_page_segmentation_scales_to_10_lines() {
        // Upstream analogue: orientation detection / line segmentation on a multi-line page.
        // Build 200 chars across 10 lines (20 chars per line).
        let chars: Vec<TextCharacter> = (0..200u32)
            .map(|i| {
                let col = (i % 20) as f32;
                let row = (i / 20) as f32;
                make_char(
                    (b'A' + (i % 26) as u8) as char,
                    col * 10.0,
                    700.0 - row * 20.0,
                )
            })
            .collect();
        let lines = segment_lines(&chars);
        assert_eq!(
            lines.len(),
            10,
            "expected 10 lines from 200 chars at 20/line"
        );
        for (idx, line) in lines.iter().enumerate() {
            assert!(
                !line.words.is_empty(),
                "line {idx} should have at least one word"
            );
        }
    }

    #[test]
    fn test_large_page_search_finds_repeated_pattern() {
        // Upstream analogue: FPDFText_FindNext loops until no more results.
        // TextSearch embedder test uses "world" in a 30-char page; scaled here to
        // 300 chars = 100 repetitions of "ABC".
        let chars: Vec<TextCharacter> = (0..300u32)
            .map(|i| {
                let ch = match i % 3 {
                    0 => 'A',
                    1 => 'B',
                    _ => 'C',
                };
                make_char(ch, i as f32 * 8.0, 500.0)
            })
            .collect();
        let page = TextPage::new(chars);
        let text = page.all_page_text().to_string();
        let mut finder = crate::textpagefind::TextPageFind::new(
            &text,
            "ABC",
            crate::textpagefind::SearchOptions::default(),
        );
        let mut count = 0usize;
        while finder.find_next().is_some() {
            count += 1;
        }
        assert_eq!(
            count, 100,
            "expected 100 occurrences of 'ABC' in 300-char page"
        );
    }

    #[test]
    fn test_large_page_rect_array_single_line_merges_to_one() {
        // Upstream analogue: FPDFText_CountRects / FPDFText_GetRect (CountRects embedder test).
        // 50 chars on a single horizontal line with the same run ID should merge into 1 rect.
        let chars: Vec<TextCharacter> = (0..50u32)
            .map(|i| make_char('A', i as f32 * 10.0, 500.0))
            .collect();
        // All chars share run ID 1 — they should merge into a single rect.
        let run_ids: Vec<Option<u32>> = (0..50).map(|_| Some(1)).collect();
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        let rects = page.rect_array(0, 50);
        assert_eq!(
            rects.len(),
            1,
            "50 chars with same run ID should merge into 1 rect, got {}",
            rects.len()
        );
        assert_eq!(rects[0].left, 0.0);
        assert!(rects[0].right > rects[0].left);
    }

    // --- Duplicate detection tests (audit gap: no duplicate text object tests) ---

    #[test]
    fn test_duplicate_same_position_same_run_deduplicated() {
        // Two characters with identical unicode, font_name, and position should
        // be deduplicated by the TextExtractor ring buffer mechanism.
        // Tolerance = font_size * 0.01 = 12 * 0.01 = 0.12 → both at (72, 700) → same.
        let ch1 = make_char('A', 72.0, 700.0);
        let ch2 = make_char('A', 72.0, 700.0);
        let mut extractor = TextExtractor::new();
        extractor.try_add_character(ch1, Some(1));
        extractor.try_add_character(ch2, Some(1));
        let (chars, run_ids) = extractor.into_characters();
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        // The second 'A' is a duplicate — only 1 should remain.
        assert!(
            page.char_count() < 2,
            "expected duplicate 'A' at same position to be removed, got {} chars",
            page.char_count()
        );
    }

    #[test]
    fn test_duplicate_overlapping_position_no_dedup_different_content() {
        // Two characters at the same position but with different unicode codepoints
        // must NOT be deduplicated — they represent distinct rendered glyphs.
        let ch1 = make_char('A', 72.0, 700.0);
        let ch2 = make_char('B', 72.0, 700.0);
        let mut extractor = TextExtractor::new();
        extractor.try_add_character(ch1, Some(1));
        extractor.try_add_character(ch2, Some(2));
        let (chars, run_ids) = extractor.into_characters();
        let page = TextPage::new_with_run_ids(chars, run_ids, false);
        // 'A' and 'B' have different unicode — dedup must not fire.
        assert_eq!(
            page.char_count(),
            2,
            "expected both 'A' and 'B' to be preserved (different unicode)"
        );
    }

    // --- Item 2: CharIndex / TextIndex round-trip invariant tests ---
    //
    // rpdfium uses an identity mapping between text indices and char indices.
    // This is architecturally correct because rpdfium never stores "silent"
    // characters in `self.characters` that are filtered out of the text string.
    // Upstream PDFium's `char_indices_` segment array is needed because
    // PDFium stores kHyphen (U+FFFE) characters in char_list_ but excludes
    // them from text_buf_.  rpdfium instead simply does not add those
    // characters to `self.characters` at all, so the mapping is always 1:1.
    //
    // The tests below verify:
    //   1. index 0 maps to 0 in both directions
    //   2. full round-trip: text_index_from_char_index(char_index_from_text_index(i)) == i
    //   3. out-of-bounds returns None in both directions
    //   4. the mapping is consistent with char_count() / text length

    #[test]
    fn test_char_index_from_text_index_first_is_zero() {
        let chars = vec![make_char('H', 0.0, 0.0), make_char('i', 10.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(
            page.char_index_from_text_index(0),
            Some(0),
            "first text index must map to first char index"
        );
    }

    #[test]
    fn test_char_text_index_round_trip_all_positions() {
        let chars = vec![
            make_char('H', 0.0, 0.0),
            make_char('e', 10.0, 0.0),
            make_char('l', 20.0, 0.0),
            make_char('l', 30.0, 0.0),
            make_char('o', 40.0, 0.0),
        ];
        let page = TextPage::new(chars);
        for i in 0..5 {
            let char_idx = page.char_index_from_text_index(i);
            assert!(char_idx.is_some(), "text index {} must be in bounds", i);
            let round_trip = page.text_index_from_char_index(char_idx.unwrap());
            assert_eq!(
                round_trip,
                Some(i),
                "round-trip text->char->text failed at index {}",
                i
            );
        }
    }

    #[test]
    fn test_char_index_from_text_index_out_of_bounds_returns_none() {
        let chars = vec![make_char('X', 0.0, 0.0)];
        let page = TextPage::new(chars);
        // Index equal to char_count() is out of bounds.
        assert_eq!(page.char_index_from_text_index(1), None);
        // Large index is also out of bounds.
        assert_eq!(page.char_index_from_text_index(999), None);
    }

    #[test]
    fn test_text_index_from_char_index_out_of_bounds_returns_none() {
        let chars = vec![make_char('Y', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.text_index_from_char_index(1), None);
        assert_eq!(page.text_index_from_char_index(usize::MAX), None);
    }

    #[test]
    fn test_char_text_index_mapping_consistent_with_char_count() {
        let chars = vec![
            make_char('A', 0.0, 0.0),
            make_char('B', 10.0, 0.0),
            make_char('C', 20.0, 0.0),
        ];
        let page = TextPage::new(chars);
        let n = page.char_count();
        // All indices in [0, n) must be valid in both directions.
        for i in 0..n {
            assert!(
                page.char_index_from_text_index(i).is_some(),
                "text index {} should be valid (char_count={})",
                i,
                n
            );
            assert!(
                page.text_index_from_char_index(i).is_some(),
                "char index {} should be valid (char_count={})",
                i,
                n
            );
        }
        // Index n itself must be out of bounds.
        assert!(page.char_index_from_text_index(n).is_none());
        assert!(page.text_index_from_char_index(n).is_none());
    }

    #[test]
    fn test_char_text_index_empty_page_both_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert_eq!(page.char_index_from_text_index(0), None);
        assert_eq!(page.text_index_from_char_index(0), None);
    }

    // --- char_render_mode tests ---

    #[test]
    fn test_char_render_mode_default_is_fill() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.char_render_mode(0), Some(TextRenderingMode::Fill));
    }

    #[test]
    fn test_char_render_mode_stroke() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.rendering_mode = TextRenderingMode::Stroke;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.char_render_mode(0), Some(TextRenderingMode::Stroke));
    }

    #[test]
    fn test_char_render_mode_fill_stroke_clip() {
        let mut ch = make_char('A', 0.0, 0.0);
        ch.rendering_mode = TextRenderingMode::FillStrokeClip;
        let page = TextPage::new(vec![ch]);
        assert_eq!(
            page.char_render_mode(0),
            Some(TextRenderingMode::FillStrokeClip)
        );
    }

    #[test]
    fn test_char_render_mode_out_of_bounds() {
        let page = TextPage::new(vec![]);
        assert_eq!(page.char_render_mode(0), None);
    }

    #[test]
    fn test_char_render_mode_returns_mode() {
        let mut ch = make_char('B', 0.0, 0.0);
        ch.rendering_mode = TextRenderingMode::Invisible;
        let page = TextPage::new(vec![ch]);
        assert_eq!(page.char_render_mode(0), Some(TextRenderingMode::Invisible));
    }

    // --- char_index_at_pos f64 tests ---

    #[test]
    fn test_char_index_at_pos_f64_basic() {
        let chars = vec![make_char('A', 10.0, 20.0), make_char('B', 30.0, 20.0)];
        let page = TextPage::new(chars);
        // Center of 'A' is at (15, 26), hit with zero tolerance
        assert_eq!(page.char_index_at_pos(15.0, 26.0, 0.0, 0.0), Some(0));
    }

    #[test]
    fn test_char_index_at_pos_f64_with_tolerance() {
        // make_char('A', 10.0, 20.0) → char_box = [10..20, 20..32].
        // New upstream algorithm: expanded box = [left-tol/2 .. right+tol/2, bottom-tol/2 .. top+tol/2].
        // With x_tol=6, y_tol=2: expanded = [10-3=7 .. 20+3=23, 20-1=19 .. 32+1=33].
        // Point (8.0, 26.0) is inside the expanded box (x: 8≥7, y: 26 in [19,33]).
        let chars = vec![make_char('A', 10.0, 20.0)];
        let page = TextPage::new(chars);
        // Point just outside the tight box but within tol/2 — should hit via tolerance pass.
        assert_eq!(page.char_index_at_pos(8.0, 26.0, 6.0, 2.0), Some(0));
        // Point too far outside: x=4 < ext_left=7, should return None.
        assert_eq!(page.char_index_at_pos(4.0, 26.0, 6.0, 2.0), None);
    }

    #[test]
    fn test_char_index_at_pos_f64_no_match() {
        let chars = vec![make_char('A', 10.0, 20.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.char_index_at_pos(100.0, 100.0, 1.0, 1.0), None);
    }

    // --- text_in_rect f64 tests ---

    #[test]
    fn test_text_in_rect_basic() {
        let chars = vec![
            make_char('A', 10.0, 20.0),
            make_char('B', 30.0, 20.0),
            make_char('C', 50.0, 50.0),
        ];
        let page = TextPage::new(chars);
        // Rect encompassing A and B (left=0, top=40, right=40, bottom=10)
        assert_eq!(page.text_in_rect(0.0, 40.0, 40.0, 10.0), "AB");
    }

    #[test]
    fn test_text_in_rect_empty() {
        let chars = vec![make_char('A', 10.0, 20.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.text_in_rect(100.0, 200.0, 200.0, 100.0), "");
    }

    #[allow(deprecated)]
    #[test]
    fn test_text_in_rect_alias() {
        let chars = vec![make_char('X', 5.0, 5.0)];
        let page = TextPage::new(chars);
        assert_eq!(page.get_text_in_rect(0.0, 20.0, 20.0, 0.0), "X");
    }

    // -----------------------------------------------------------------------
    // Batch 17: FPDFText_GetCharObject / FPDFText_HasTextObjectForChar stubs
    // -----------------------------------------------------------------------

    #[test]
    fn test_text_page_char_object_index_returns_none() {
        let chars = vec![make_char('A', 0.0, 0.0)];
        let page = TextPage::new(chars);
        // char_object_index is a None stub — cross-layer access not wired yet
        assert!(page.char_object_index(0).is_none());
        assert!(page.text_get_char_object(0).is_none());
    }

    #[test]
    fn test_text_page_has_text_object_for_char_false() {
        let chars = vec![make_char('B', 10.0, 10.0)];
        let page = TextPage::new(chars);
        // has_text_object_for_char is false since char_object_index returns None
        assert!(!page.has_text_object_for_char(0));
        assert!(!page.has_text_object_for_char(99));
    }
}