oxidize_pdf/text/

mod.rs

pub mod cid_to_unicode;
pub mod cmap;
pub(crate) mod encoding;
pub(crate) mod encoding_cmap;
pub mod extraction;
mod extraction_cmap;
pub(crate) mod flat_reading_order;
mod flow;
mod font;
pub mod font_manager;
pub mod fonts;
pub(crate) mod graphics_state_stack;
mod header_footer;
pub mod invoice;
mod layout;
mod list;
pub mod metrics;
pub mod ocr;
pub mod plaintext;
pub mod structured;
pub mod table;
pub mod table_detection;
pub mod text_block;
pub mod validation;

#[cfg(test)]
mod cmap_tests;

#[cfg(test)]
mod flat_reading_order_tests;

#[cfg(feature = "ocr-tesseract")]
pub mod tesseract_provider;

pub use encoding::{escape_pdf_string_literal, TextEncoding};
pub use extraction::{
    sanitize_extracted_text, sanitize_extracted_text_with_policy, CarriageReturnHandling,
    ExtractedText, ExtractionOptions, TextExtractor, TextFragment,
};
pub use flow::{TextAlign, TextFlowContext};
pub use font::{Font, FontEncoding, FontFamily, FontWithEncoding};
pub use font_manager::{CustomFont, FontDescriptor, FontFlags, FontManager, FontMetrics, FontType};
pub use header_footer::{HeaderFooter, HeaderFooterOptions, HeaderFooterPosition};
pub use layout::{ColumnContent, ColumnLayout, ColumnOptions, TextFormat};
pub use list::{
    BulletStyle, ListElement, ListItem, ListOptions, ListStyle as ListStyleEnum, OrderedList,
    OrderedListStyle, UnorderedList,
};
pub use metrics::{
    measure_char, measure_char_with, measure_text, measure_text_with, split_into_words,
    FontMetricsStore,
};
pub use ocr::{
    CharacterConfidence, CorrectionCandidate, CorrectionReason, CorrectionSuggestion,
    CorrectionType, FragmentType, ImagePreprocessing, MockOcrProvider, OcrEngine, OcrError,
    OcrOptions, OcrPostProcessor, OcrProcessingResult, OcrProvider, OcrRegion, OcrResult,
    OcrTextFragment, WordConfidence,
};
pub use plaintext::{LineBreakMode, PlainTextConfig, PlainTextExtractor, PlainTextResult};
pub use table::{HeaderStyle, Table, TableCell, TableOptions};
pub use text_block::{
    compute_line_widths, measure_text_block, measure_text_block_with, TextBlockMetrics,
};
pub use validation::{MatchType, TextMatch, TextValidationResult, TextValidator};

#[cfg(feature = "ocr-tesseract")]
pub use tesseract_provider::{RustyTesseractConfig, RustyTesseractProvider};

use crate::error::Result;
use crate::Color;
use std::collections::{HashMap, HashSet};

/// Text rendering mode for PDF text operations.
///
/// Re-exported via `oxidize_pdf::text::TextRenderingMode`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum TextRenderingMode {
    /// Fill text (default)
    Fill = 0,
    /// Stroke text
    Stroke = 1,
    /// Fill and stroke text
    FillStroke = 2,
    /// Invisible text (for searchable text over images)
    Invisible = 3,
    /// Fill text and add to path for clipping
    FillClip = 4,
    /// Stroke text and add to path for clipping
    StrokeClip = 5,
    /// Fill and stroke text and add to path for clipping
    FillStrokeClip = 6,
    /// Add text to path for clipping (invisible)
    Clip = 7,
}

/// Build the show-text IR op for `text` rendered with `font`. Single
/// emission path shared by `TextContext::write` and
/// `TextFlowContext::write_wrapped` so the two cannot diverge on encoding
/// or escaping (issue #240 — pre-fix, the flow path emitted raw UTF-8
/// bytes inside the literal `( … ) Tj` and any character outside ASCII
/// rendered as Windows-1252 mojibake).
///
/// - `Font::Custom(_)` → UTF-16BE hex string per ISO 32000-1 §9.10.3,
///   wrapped in `Op::ShowTextHex` so the writer emits `< … > Tj`.
/// - Any builtin font → bytes are first WinAnsi-encoded
///   ([`TextEncoding::WinAnsiEncoding`]) and then escaped for inclusion
///   in a PDF string literal via
///   [`encoding::escape_show_text_literal_bytes`].
pub(crate) fn build_show_text_op(text: &str, font: &Font) -> crate::graphics::ops::Op {
    use crate::graphics::ops::Op;

    match font {
        Font::Custom(_) => {
            let utf16_units: Vec<u16> = text.encode_utf16().collect();
            let mut hex = String::with_capacity(utf16_units.len() * 4);
            for unit in utf16_units {
                use std::fmt::Write as _;
                write!(
                    &mut hex,
                    "{:02X}{:02X}",
                    (unit >> 8) as u8,
                    (unit & 0xFF) as u8
                )
                .expect("write to String never fails");
            }
            Op::ShowTextHex(hex.into_bytes())
        }
        _ => {
            let encoded = TextEncoding::WinAnsiEncoding.encode(text);
            Op::ShowText(encoding::escape_show_text_literal_bytes(&encoded))
        }
    }
}

#[derive(Clone)]
pub struct TextContext {
    operations: Vec<crate::graphics::ops::Op>,
    current_font: Font,
    font_size: f64,
    text_matrix: [f64; 6],
    // Pending position for next write operation
    pending_position: Option<(f64, f64)>,
    // Text state parameters
    character_spacing: Option<f64>,
    word_spacing: Option<f64>,
    horizontal_scaling: Option<f64>,
    leading: Option<f64>,
    text_rise: Option<f64>,
    rendering_mode: Option<TextRenderingMode>,
    // Color parameters
    fill_color: Option<Color>,
    stroke_color: Option<Color>,
    // Track used characters per custom-font name (issue #204 — a single
    // global set caused every registered font to be subsetted with the
    // same characters, so two fonts of the same family ended up with
    // duplicated subsets). Builtin fonts are not tracked because they
    // don't need subsetting. Extended by `write` whenever the active
    // font is `Font::Custom`.
    used_characters_by_font: HashMap<String, HashSet<char>>,
    /// Per-document font metrics store threaded from `Page` (issue #230).
    /// `None` means the built-in heuristic width tables are used.
    /// Non-test callers arrive in Task 9-11 (Document integration).
    #[allow(dead_code)]
    pub(crate) font_metrics_store: Option<FontMetricsStore>,
}

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

impl TextContext {
    pub fn new() -> Self {
        Self {
            operations: Vec::new(),
            current_font: Font::Helvetica,
            font_size: 12.0,
            text_matrix: [1.0, 0.0, 0.0, 1.0, 0.0, 0.0],
            pending_position: None,
            character_spacing: None,
            word_spacing: None,
            horizontal_scaling: None,
            leading: None,
            text_rise: None,
            rendering_mode: None,
            fill_color: None,
            stroke_color: None,
            used_characters_by_font: HashMap::new(),
            font_metrics_store: None,
        }
    }

    /// Create a `TextContext` bound to a per-document `FontMetricsStore`
    /// (issue #230). `None` is equivalent to `TextContext::new()`.
    ///
    /// `pub(crate)` — wired by `Page::*_with_metrics()` constructors and
    /// by `Document::new_page_*()` factories.
    pub(crate) fn with_metrics_store(store: Option<FontMetricsStore>) -> Self {
        let mut ctx = Self::default();
        ctx.font_metrics_store = store;
        ctx
    }

    /// Inject or replace the per-Document `FontMetricsStore` on an
    /// already-constructed context. Preserves accumulated ops and any
    /// other state — only the `font_metrics_store` field is mutated.
    ///
    /// Called by `Document::add_page` for pages constructed via
    /// `Page::a4()` / `Page::letter()` / `Page::new()` (those start with
    /// `font_metrics_store: None` and may already carry ops the caller
    /// pushed before transferring ownership to the Document).
    pub(crate) fn set_metrics_store(&mut self, store: Option<FontMetricsStore>) {
        self.font_metrics_store = store;
    }

    /// Record `text` as drawn with the currently-active font, bucketed
    /// under the font's PDF name (issue #204). Builtin and custom fonts
    /// are both tracked; the writer later filters to the set of
    /// registered custom fonts when subsetting.
    fn record_used_chars(&mut self, text: &str) {
        let name = match &self.current_font {
            Font::Custom(name) => name.clone(),
            builtin => builtin.pdf_name(),
        };
        self.used_characters_by_font
            .entry(name)
            .or_default()
            .extend(text.chars());
    }

    /// Introspection helper for Task 7 tests (issue #230).
    #[cfg(test)]
    pub(crate) fn font_metrics_store_for_test(&self) -> Option<&FontMetricsStore> {
        self.font_metrics_store.as_ref()
    }

    /// Get the characters used in this text context (merged across all
    /// fonts). Test-only compatibility accessor; callers that need
    /// per-font accuracy for subsetting should use
    /// [`TextContext::get_used_characters_by_font`] (issue #204).
    #[cfg(test)]
    pub(crate) fn get_used_characters(&self) -> Option<HashSet<char>> {
        let merged: HashSet<char> = self
            .used_characters_by_font
            .values()
            .flat_map(|s| s.iter().copied())
            .collect();
        if merged.is_empty() {
            None
        } else {
            Some(merged)
        }
    }

    /// Get the per-font character map for font subsetting (issue #204).
    pub(crate) fn get_used_characters_by_font(&self) -> &HashMap<String, HashSet<char>> {
        &self.used_characters_by_font
    }

    pub fn set_font(&mut self, font: Font, size: f64) -> &mut Self {
        self.current_font = font;
        self.font_size = size;
        self
    }

    /// Get the current font
    #[allow(dead_code)]
    pub(crate) fn current_font(&self) -> &Font {
        &self.current_font
    }

    /// Current non-stroking (fill) colour, if one has been explicitly set.
    /// Used by `Page::text_flow` to propagate the page-level text colour
    /// into derived `TextFlowContext`s (issue #216).
    pub(crate) fn fill_color(&self) -> Option<Color> {
        self.fill_color
    }

    /// Accessors for the remaining text-state parameters (issue #222 —
    /// Phase 6 of the v2.7.0 IR refactor). Used by `Page::text_flow` to
    /// propagate the configured page-level state into derived
    /// `TextFlowContext`s. Mirror of `fill_color()` above.
    pub(crate) fn character_spacing(&self) -> Option<f64> {
        self.character_spacing
    }
    pub(crate) fn word_spacing(&self) -> Option<f64> {
        self.word_spacing
    }
    pub(crate) fn horizontal_scaling(&self) -> Option<f64> {
        self.horizontal_scaling
    }
    pub(crate) fn leading(&self) -> Option<f64> {
        self.leading
    }
    pub(crate) fn text_rise(&self) -> Option<f64> {
        self.text_rise
    }
    pub(crate) fn rendering_mode(&self) -> Option<TextRenderingMode> {
        self.rendering_mode
    }
    pub(crate) fn stroke_color(&self) -> Option<Color> {
        self.stroke_color
    }

    pub fn at(&mut self, x: f64, y: f64) -> &mut Self {
        // Update text_matrix immediately and store for write() operation
        self.text_matrix[4] = x;
        self.text_matrix[5] = y;
        self.pending_position = Some((x, y));
        self
    }

    pub fn write(&mut self, text: &str) -> Result<&mut Self> {
        use crate::graphics::ops::Op;

        self.operations.push(Op::BeginText);

        // Set font
        self.operations.push(Op::SetFont {
            name: self.current_font.pdf_name(),
            size: self.font_size,
        });

        // Apply text state parameters (Tc/Tw/Tz/TL/Ts/Tr + colour)
        self.apply_text_state_parameters();

        // Set text position using pending_position if available, otherwise use text_matrix
        let (x, y) = if let Some((px, py)) = self.pending_position.take() {
            (px, py)
        } else {
            (self.text_matrix[4], self.text_matrix[5])
        };
        self.operations.push(Op::SetTextPosition { x, y });

        // Shared encoding + escape pipeline (issue #240): builtin fonts
        // route through WinAnsi + literal-string escape; Custom (CJK)
        // fonts route through UTF-16BE hex. Mirror of the same call in
        // `TextFlowContext::write_wrapped` — single source of truth.
        self.operations
            .push(build_show_text_op(text, &self.current_font));

        // Track used characters for font subsetting bucketed by the
        // active custom font (issue #204).
        self.record_used_chars(text);

        self.operations.push(Op::EndText);

        Ok(self)
    }

    pub fn write_line(&mut self, text: &str) -> Result<&mut Self> {
        self.write(text)?;
        self.text_matrix[5] -= self.font_size * 1.2; // Move down for next line
        Ok(self)
    }

    pub fn set_character_spacing(&mut self, spacing: f64) -> &mut Self {
        self.character_spacing = Some(spacing);
        self
    }

    pub fn set_word_spacing(&mut self, spacing: f64) -> &mut Self {
        self.word_spacing = Some(spacing);
        self
    }

    pub fn set_horizontal_scaling(&mut self, scale: f64) -> &mut Self {
        self.horizontal_scaling = Some(scale);
        self
    }

    pub fn set_leading(&mut self, leading: f64) -> &mut Self {
        self.leading = Some(leading);
        self
    }

    pub fn set_text_rise(&mut self, rise: f64) -> &mut Self {
        self.text_rise = Some(rise);
        self
    }

    /// Set the text rendering mode
    pub fn set_rendering_mode(&mut self, mode: TextRenderingMode) -> &mut Self {
        self.rendering_mode = Some(mode);
        self
    }

    /// Set the text fill color
    pub fn set_fill_color(&mut self, color: Color) -> &mut Self {
        self.fill_color = Some(color);
        self
    }

    /// Set the text stroke color
    pub fn set_stroke_color(&mut self, color: Color) -> &mut Self {
        self.stroke_color = Some(color);
        self
    }

    /// Apply text state parameters as `Op` values pushed into `self.operations`.
    ///
    /// All non-finite floats are clamped to `0.0` at serialisation time by
    /// `serialize_ops` (issues #220 + #221 extend to non-colour emitters in
    /// the v2.7.0 IR refactor).
    fn apply_text_state_parameters(&mut self) {
        use crate::graphics::ops::Op;

        if let Some(spacing) = self.character_spacing {
            self.operations.push(Op::SetCharSpacing(spacing));
        }
        if let Some(spacing) = self.word_spacing {
            self.operations.push(Op::SetWordSpacing(spacing));
        }
        if let Some(scale) = self.horizontal_scaling {
            // Tz operator takes a percentage. The setter accepts a 0.0–1.0
            // ratio and the original implementation multiplied by 100 at
            // emission; preserve that contract.
            self.operations
                .push(Op::SetHorizontalScaling(scale * 100.0));
        }
        if let Some(leading) = self.leading {
            self.operations.push(Op::SetLeading(leading));
        }
        if let Some(rise) = self.text_rise {
            self.operations.push(Op::SetTextRise(rise));
        }
        if let Some(mode) = self.rendering_mode {
            self.operations.push(Op::SetRenderingMode(mode as u8));
        }

        // Fill / stroke colour delegates to the IR variants which in turn
        // delegate to `write_fill_color_bytes` / `write_stroke_color_bytes`
        // (issues #220 + #221).
        if let Some(color) = self.fill_color {
            self.operations.push(Op::SetFillColor(color));
        }
        if let Some(color) = self.stroke_color {
            self.operations.push(Op::SetStrokeColor(color));
        }
    }

    pub(crate) fn generate_operations(&self) -> Result<Vec<u8>> {
        let mut buf = Vec::new();
        crate::graphics::ops::serialize_ops(&mut buf, &self.operations);
        Ok(buf)
    }

    /// Take ownership of the accumulated `Op` buffer, leaving an empty
    /// `Vec` in its place. Mirror of `GraphicsContext::drain_ops` —
    /// used by `Page` to flush the text buffer into a unified content
    /// stream on context switch (issue #227).
    pub(crate) fn drain_ops(&mut self) -> Vec<crate::graphics::ops::Op> {
        std::mem::take(&mut self.operations)
    }

    /// Read-only access to the operation list.
    pub(crate) fn ops_slice(&self) -> &[crate::graphics::ops::Op] {
        &self.operations
    }

    /// Appends a raw PDF operation to the text context
    ///
    /// This is used internally for marked content operators (BDC/EMC) and other
    /// low-level PDF operations that need to be interleaved with text operations.
    pub(crate) fn append_raw_operation(&mut self, operation: &str) {
        self.operations
            .push(crate::graphics::ops::Op::Raw(operation.as_bytes().to_vec()));
    }

    /// Get the current font size
    pub fn font_size(&self) -> f64 {
        self.font_size
    }

    /// Get the current text matrix
    pub fn text_matrix(&self) -> [f64; 6] {
        self.text_matrix
    }

    /// Get the current position
    pub fn position(&self) -> (f64, f64) {
        (self.text_matrix[4], self.text_matrix[5])
    }

    /// Clear all operations and reset text state parameters
    pub fn clear(&mut self) {
        self.operations.clear();
        self.character_spacing = None;
        self.word_spacing = None;
        self.horizontal_scaling = None;
        self.leading = None;
        self.text_rise = None;
        self.rendering_mode = None;
        self.fill_color = None;
        self.stroke_color = None;
    }

    /// Get the operations as a serialised PDF content-stream `String`.
    ///
    /// Pre-2.7.0 this returned `&str`. The IR migration replaced the
    /// internal `String` buffer with a typed `Vec<Op>`, so the legacy
    /// borrow is materialised on demand. Internal callers prefer
    /// `generate_operations()` which returns the byte buffer directly.
    pub fn operations(&self) -> String {
        crate::graphics::ops::ops_to_string(&self.operations)
    }

    /// Generate text state operations for testing purposes.
    /// Routes through the IR so the same sanitisation applies.
    #[cfg(test)]
    pub fn generate_text_state_operations(&self) -> String {
        use crate::graphics::ops::{ops_to_string, Op};

        let mut ops = Vec::new();
        if let Some(spacing) = self.character_spacing {
            ops.push(Op::SetCharSpacing(spacing));
        }
        if let Some(spacing) = self.word_spacing {
            ops.push(Op::SetWordSpacing(spacing));
        }
        if let Some(scale) = self.horizontal_scaling {
            ops.push(Op::SetHorizontalScaling(scale * 100.0));
        }
        if let Some(leading) = self.leading {
            ops.push(Op::SetLeading(leading));
        }
        if let Some(rise) = self.text_rise {
            ops.push(Op::SetTextRise(rise));
        }
        if let Some(mode) = self.rendering_mode {
            ops.push(Op::SetRenderingMode(mode as u8));
        }
        ops_to_string(&ops)
    }
}

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

    #[test]
    fn test_text_context_new() {
        let context = TextContext::new();
        assert_eq!(context.current_font, Font::Helvetica);
        assert_eq!(context.font_size, 12.0);
        assert_eq!(context.text_matrix, [1.0, 0.0, 0.0, 1.0, 0.0, 0.0]);
        assert!(context.operations.is_empty());
    }

    #[test]
    fn test_text_context_default() {
        let context = TextContext::default();
        assert_eq!(context.current_font, Font::Helvetica);
        assert_eq!(context.font_size, 12.0);
    }

    #[test]
    fn test_set_font() {
        let mut context = TextContext::new();
        context.set_font(Font::TimesBold, 14.0);
        assert_eq!(context.current_font, Font::TimesBold);
        assert_eq!(context.font_size, 14.0);
    }

    #[test]
    fn test_position() {
        let mut context = TextContext::new();
        context.at(100.0, 200.0);
        let (x, y) = context.position();
        assert_eq!(x, 100.0);
        assert_eq!(y, 200.0);
        assert_eq!(context.text_matrix[4], 100.0);
        assert_eq!(context.text_matrix[5], 200.0);
    }

    #[test]
    fn test_write_simple_text() {
        let mut context = TextContext::new();
        context.write("Hello").unwrap();

        let ops = context.operations();
        assert!(ops.contains("BT\n"));
        assert!(ops.contains("ET\n"));
        assert!(ops.contains("/Helvetica 12 Tf"));
        assert!(ops.contains("(Hello) Tj"));
    }

    #[test]
    fn test_write_text_with_escaping() {
        let mut context = TextContext::new();
        context.write("(Hello)").unwrap();

        let ops = context.operations();
        assert!(ops.contains("(\\(Hello\\)) Tj"));
    }

    #[test]
    fn test_write_line() {
        let mut context = TextContext::new();
        let initial_y = context.text_matrix[5];
        context.write_line("Line 1").unwrap();

        // Y position should have moved down
        let new_y = context.text_matrix[5];
        assert!(new_y < initial_y);
        assert_eq!(new_y, initial_y - 12.0 * 1.2); // font_size * 1.2
    }

    #[test]
    fn test_character_spacing() {
        let mut context = TextContext::new();
        context.set_character_spacing(2.5);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("2.50 Tc"));
    }

    #[test]
    fn test_word_spacing() {
        let mut context = TextContext::new();
        context.set_word_spacing(1.5);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("1.50 Tw"));
    }

    #[test]
    fn test_horizontal_scaling() {
        let mut context = TextContext::new();
        context.set_horizontal_scaling(1.25);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("125.00 Tz")); // 1.25 * 100
    }

    #[test]
    fn test_leading() {
        let mut context = TextContext::new();
        context.set_leading(15.0);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("15.00 TL"));
    }

    #[test]
    fn test_text_rise() {
        let mut context = TextContext::new();
        context.set_text_rise(3.0);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("3.00 Ts"));
    }

    #[test]
    fn test_clear() {
        let mut context = TextContext::new();
        context.write("Hello").unwrap();
        assert!(!context.operations().is_empty());

        context.clear();
        assert!(context.operations().is_empty());
    }

    #[test]
    fn test_generate_operations() {
        let mut context = TextContext::new();
        context.write("Test").unwrap();

        let ops_bytes = context.generate_operations().unwrap();
        let ops_string = String::from_utf8(ops_bytes).unwrap();
        assert_eq!(ops_string, context.operations());
    }

    #[test]
    fn test_method_chaining() {
        let mut context = TextContext::new();
        context
            .set_font(Font::Courier, 10.0)
            .at(50.0, 100.0)
            .set_character_spacing(1.0)
            .set_word_spacing(2.0);

        assert_eq!(context.current_font(), &Font::Courier);
        assert_eq!(context.font_size(), 10.0);
        let (x, y) = context.position();
        assert_eq!(x, 50.0);
        assert_eq!(y, 100.0);
    }

    #[test]
    fn test_text_matrix_access() {
        let mut context = TextContext::new();
        context.at(25.0, 75.0);

        let matrix = context.text_matrix();
        assert_eq!(matrix, [1.0, 0.0, 0.0, 1.0, 25.0, 75.0]);
    }

    #[test]
    fn test_special_characters_encoding() {
        let mut context = TextContext::new();
        context.write("Test\nLine\tTab").unwrap();

        let ops = context.operations();
        assert!(ops.contains("\\n"));
        assert!(ops.contains("\\t"));
    }

    #[test]
    fn test_rendering_mode_fill() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::Fill);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("0 Tr"));
    }

    #[test]
    fn test_rendering_mode_stroke() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::Stroke);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("1 Tr"));
    }

    #[test]
    fn test_rendering_mode_fill_stroke() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::FillStroke);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("2 Tr"));
    }

    #[test]
    fn test_rendering_mode_invisible() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::Invisible);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("3 Tr"));
    }

    #[test]
    fn test_rendering_mode_fill_clip() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::FillClip);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("4 Tr"));
    }

    #[test]
    fn test_rendering_mode_stroke_clip() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::StrokeClip);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("5 Tr"));
    }

    #[test]
    fn test_rendering_mode_fill_stroke_clip() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::FillStrokeClip);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("6 Tr"));
    }

    #[test]
    fn test_rendering_mode_clip() {
        let mut context = TextContext::new();
        context.set_rendering_mode(TextRenderingMode::Clip);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("7 Tr"));
    }

    #[test]
    fn test_text_state_parameters_chaining() {
        let mut context = TextContext::new();
        context
            .set_character_spacing(1.5)
            .set_word_spacing(2.0)
            .set_horizontal_scaling(1.1)
            .set_leading(14.0)
            .set_text_rise(0.5)
            .set_rendering_mode(TextRenderingMode::FillStroke);

        let ops = context.generate_text_state_operations();
        assert!(ops.contains("1.50 Tc"));
        assert!(ops.contains("2.00 Tw"));
        assert!(ops.contains("110.00 Tz"));
        assert!(ops.contains("14.00 TL"));
        assert!(ops.contains("0.50 Ts"));
        assert!(ops.contains("2 Tr"));
    }

    #[test]
    fn test_all_text_state_operators_generated() {
        let mut context = TextContext::new();

        // Test all operators in sequence
        context.set_character_spacing(1.0); // Tc
        context.set_word_spacing(2.0); // Tw
        context.set_horizontal_scaling(1.2); // Tz
        context.set_leading(15.0); // TL
        context.set_text_rise(1.0); // Ts
        context.set_rendering_mode(TextRenderingMode::Stroke); // Tr

        let ops = context.generate_text_state_operations();

        // Verify all PDF text state operators are present
        assert!(
            ops.contains("Tc"),
            "Character spacing operator (Tc) not found"
        );
        assert!(ops.contains("Tw"), "Word spacing operator (Tw) not found");
        assert!(
            ops.contains("Tz"),
            "Horizontal scaling operator (Tz) not found"
        );
        assert!(ops.contains("TL"), "Leading operator (TL) not found");
        assert!(ops.contains("Ts"), "Text rise operator (Ts) not found");
        assert!(
            ops.contains("Tr"),
            "Text rendering mode operator (Tr) not found"
        );
    }

    #[test]
    fn test_text_color_operations() {
        use crate::Color;

        let mut context = TextContext::new();

        // Test RGB fill color
        context.set_fill_color(Color::rgb(1.0, 0.0, 0.0));
        context.apply_text_state_parameters();

        let ops = context.operations();
        assert!(
            ops.contains("1.000 0.000 0.000 rg"),
            "RGB fill color operator (rg) not found in: {ops}"
        );

        // Clear and test RGB stroke color
        context.clear();
        context.set_stroke_color(Color::rgb(0.0, 1.0, 0.0));
        context.apply_text_state_parameters();

        let ops = context.operations();
        assert!(
            ops.contains("0.000 1.000 0.000 RG"),
            "RGB stroke color operator (RG) not found in: {ops}"
        );

        // Clear and test grayscale fill color
        context.clear();
        context.set_fill_color(Color::gray(0.5));
        context.apply_text_state_parameters();

        let ops = context.operations();
        assert!(
            ops.contains("0.500 g"),
            "Gray fill color operator (g) not found in: {ops}"
        );

        // Clear and test CMYK stroke color
        context.clear();
        context.set_stroke_color(Color::cmyk(0.2, 0.3, 0.4, 0.1));
        context.apply_text_state_parameters();

        let ops = context.operations();
        assert!(
            ops.contains("0.200 0.300 0.400 0.100 K"),
            "CMYK stroke color operator (K) not found in: {ops}"
        );

        // Test both fill and stroke colors together
        context.clear();
        context.set_fill_color(Color::rgb(1.0, 0.0, 0.0));
        context.set_stroke_color(Color::rgb(0.0, 0.0, 1.0));
        context.apply_text_state_parameters();

        let ops = context.operations();
        assert!(
            ops.contains("1.000 0.000 0.000 rg") && ops.contains("0.000 0.000 1.000 RG"),
            "Both fill and stroke colors not found in: {ops}"
        );
    }

    // Issue #97: Test used_characters tracking
    #[test]
    fn test_used_characters_tracking_ascii() {
        let mut context = TextContext::new();
        context.write("Hello").unwrap();

        let chars = context.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'H'));
        assert!(chars.contains(&'e'));
        assert!(chars.contains(&'l'));
        assert!(chars.contains(&'o'));
        assert_eq!(chars.len(), 4); // H, e, l, o (l appears twice but HashSet dedupes)
    }

    #[test]
    fn test_used_characters_tracking_cjk() {
        let mut context = TextContext::new();
        context.set_font(Font::Custom("NotoSansCJK".to_string()), 12.0);
        context.write("中文测试").unwrap();

        let chars = context.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'中'));
        assert!(chars.contains(&'文'));
        assert!(chars.contains(&'测'));
        assert!(chars.contains(&'试'));
        assert_eq!(chars.len(), 4);
    }

    #[test]
    fn test_used_characters_empty_initially() {
        let context = TextContext::new();
        assert!(context.get_used_characters().is_none());
    }

    #[test]
    fn test_used_characters_multiple_writes() {
        let mut context = TextContext::new();
        context.write("AB").unwrap();
        context.write("CD").unwrap();

        let chars = context.get_used_characters();
        assert!(chars.is_some());
        let chars = chars.unwrap();
        assert!(chars.contains(&'A'));
        assert!(chars.contains(&'B'));
        assert!(chars.contains(&'C'));
        assert!(chars.contains(&'D'));
        assert_eq!(chars.len(), 4);
    }

    /// RED for Phase 2 of the v2.7.0 IR refactor: with the legacy `String`
    /// emission, `set_character_spacing(f64::NAN)` propagates `NaN` into a
    /// `Tc` operator, which is invalid per ISO 32000-1 §7.3.3. Once the
    /// migration routes Tc through `serialize_ops`, `finite_or_zero`
    /// clamps non-finite values to `0.0` and the assertion below passes.
    #[test]
    fn nan_char_spacing_sanitised_at_emission() {
        let mut ctx = TextContext::new();
        ctx.set_character_spacing(f64::NAN);
        ctx.write("hi").unwrap();
        let ops = ctx.operations();
        assert!(
            ops.contains("0.00 Tc\n"),
            "NaN char spacing must emit `0.00 Tc`, got: {ops:?}"
        );
        assert!(
            !ops.contains("NaN") && !ops.contains("inf"),
            "non-finite tokens must not appear in any Tc/Tw/Tz/TL/Ts emission, got: {ops:?}"
        );
    }

    #[test]
    fn pos_inf_word_spacing_sanitised_at_emission() {
        let mut ctx = TextContext::new();
        ctx.set_word_spacing(f64::INFINITY);
        ctx.write("hi").unwrap();
        let ops = ctx.operations();
        assert!(
            ops.contains("0.00 Tw\n"),
            "+inf word spacing must emit `0.00 Tw`, got: {ops:?}"
        );
        assert!(
            !ops.contains("inf"),
            "`inf` must not appear in Tw output, got: {ops:?}"
        );
    }

    #[test]
    fn nan_horizontal_scaling_sanitised_at_emission() {
        let mut ctx = TextContext::new();
        ctx.set_horizontal_scaling(f64::NAN);
        ctx.write("hi").unwrap();
        let ops = ctx.operations();
        assert!(
            ops.contains("0.00 Tz\n"),
            "NaN horizontal scaling must emit `0.00 Tz`, got: {ops:?}"
        );
    }

    #[test]
    fn nan_leading_and_text_rise_sanitised_at_emission() {
        let mut ctx = TextContext::new();
        ctx.set_leading(f64::NEG_INFINITY);
        ctx.set_text_rise(f64::NAN);
        ctx.write("hi").unwrap();
        let ops = ctx.operations();
        assert!(
            ops.contains("0.00 TL\n"),
            "-inf leading must emit `0.00 TL`, got: {ops:?}"
        );
        assert!(
            ops.contains("0.00 Ts\n"),
            "NaN text rise must emit `0.00 Ts`, got: {ops:?}"
        );
    }

    #[test]
    fn test_text_context_threads_metrics_store() {
        use crate::text::metrics::{FontMetrics, FontMetricsStore};
        let store = FontMetricsStore::new();
        let ctx = TextContext::with_metrics_store(Some(store.clone()));
        // The store handle round-trips.
        assert!(ctx.font_metrics_store_for_test().is_some());
        // Cloning shares state.
        store.register("X", FontMetrics::new(400));
        assert_eq!(
            ctx.font_metrics_store_for_test().unwrap().len(),
            1,
            "TextContext must hold a clone that shares the underlying registry"
        );
    }
}