rpdfium_doc/variable_text/

variable_text.rs

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

//! Variable text layout engine (`CPVT_VariableText`).
//!
//! Ports PDFium's `CPVT_VariableText` class which performs text layout
//! (line breaking, alignment, auto font sizing) for interactive form fields.

use crate::error::{DocError, DocResult};

pub use super::vt_font_map::VtFontProvider;
pub use super::vt_line::Line;
pub use super::vt_section::Section;
pub use super::vt_word_info::WordInfo;
pub use super::vt_word_place::WordPlace;
pub use super::vt_word_range::WordRange;

/// Type alias for the stateful word iterator — backward-compatible public name.
///
/// Corresponds to upstream `CPVT_VariableText::Iterator`.
pub type VtIterator<'a, P> = VtWordIterator<'a, P>;

/// Text alignment mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Alignment {
    /// Left-aligned (default).
    #[default]
    Left,
    /// Center-aligned.
    Center,
    /// Right-aligned.
    Right,
}

impl Alignment {
    /// Parse from an integer value (`/Q` key): 0=left, 1=center, 2=right.
    pub fn from_value(v: i32) -> Self {
        match v {
            1 => Self::Center,
            2 => Self::Right,
            _ => Self::Left,
        }
    }
}

/// Font size steps used by auto-font-size binary search.
const AUTO_FONT_SIZES: &[f32] = &[
    4.0, 6.0, 8.0, 9.0, 10.0, 11.0, 12.0, 14.0, 16.0, 18.0, 20.0, 22.0, 24.0, 26.0, 28.0, 36.0,
    48.0, 72.0, 144.0,
];

/// Variable text layout engine.
///
/// Performs text layout with line breaking, alignment, character array mode,
/// password masking, and auto font sizing for form field appearance streams.
pub struct VariableText<P: VtFontProvider> {
    provider: P,
    sections: Vec<Section>,
    plate_rect: [f32; 4],
    font_size: f32,
    alignment: Alignment,
    multi_line: bool,
    auto_return: bool,
    auto_font_size: bool,
    char_array: Option<usize>,
    password_char: Option<char>,
    limit_char: Option<usize>,
    content_rect: [f32; 4],
}

impl<P: VtFontProvider> VariableText<P> {
    /// Create a new layout engine with the given font provider.
    pub fn new(provider: P) -> Self {
        Self {
            provider,
            sections: Vec::new(),
            plate_rect: [0.0; 4],
            font_size: 12.0,
            alignment: Alignment::Left,
            multi_line: false,
            auto_return: true,
            auto_font_size: false,
            char_array: None,
            password_char: None,
            limit_char: None,
            content_rect: [0.0; 4],
        }
    }

    /// Set the bounding plate rectangle [left, bottom, right, top].
    pub fn set_plate_rect(&mut self, rect: [f32; 4]) {
        self.plate_rect = rect;
    }

    /// Return the bounding plate rectangle [left, bottom, right, top].
    ///
    /// Corresponds to `CPDF_VariableText::GetPlateRect()` in PDFium.
    pub fn plate_rect(&self) -> [f32; 4] {
        self.plate_rect
    }

    /// ADR-019 alias for [`plate_rect()`](Self::plate_rect).
    ///
    /// Corresponds to `CPDF_VariableText::GetPlateRect()` in PDFium.
    #[inline]
    pub fn get_plate_rect(&self) -> [f32; 4] {
        self.plate_rect()
    }

    /// Set the font size.
    pub fn set_font_size(&mut self, size: f32) {
        self.font_size = size;
    }

    /// Set text alignment.
    pub fn set_alignment(&mut self, alignment: Alignment) {
        self.alignment = alignment;
    }

    /// Enable or disable multi-line mode.
    pub fn set_multi_line(&mut self, multi_line: bool) {
        self.multi_line = multi_line;
    }

    /// Enable or disable automatic line return.
    pub fn set_auto_return(&mut self, auto_return: bool) {
        self.auto_return = auto_return;
    }

    /// Enable or disable automatic font sizing to fit the plate rect.
    pub fn set_auto_font_size(&mut self, auto: bool) {
        self.auto_font_size = auto;
    }

    /// Set character array mode (fixed grid with N cells).
    pub fn set_char_array(&mut self, count: Option<usize>) {
        self.char_array = count;
    }

    /// Set the password masking character.
    pub fn set_password_char(&mut self, ch: Option<char>) {
        self.password_char = ch;
    }

    /// Set the maximum character limit.
    pub fn set_limit_char(&mut self, limit: Option<usize>) {
        self.limit_char = limit;
    }

    /// Parse text into sections and words.
    ///
    /// Sections are separated by line breaks (`\r\n`, `\r`, or `\n`).
    /// Each character becomes a word in the current section.
    pub fn set_text(&mut self, text: &str) {
        self.sections.clear();

        let effective_text: String = if let Some(limit) = self.limit_char {
            text.chars().take(limit).collect()
        } else {
            text.to_string()
        };

        let display_text = if let Some(pw) = self.password_char {
            pw.to_string().repeat(effective_text.chars().count())
        } else {
            effective_text
        };

        let mut current_section = Section {
            words: Vec::new(),
            lines: Vec::new(),
            rect: [0.0; 4],
        };

        let mut chars = display_text.chars().peekable();
        while let Some(ch) = chars.next() {
            if ch == '\r' {
                // \r\n or bare \r — both start a new section
                if chars.peek() == Some(&'\n') {
                    chars.next(); // consume the \n
                }
                self.sections.push(current_section);
                current_section = Section {
                    words: Vec::new(),
                    lines: Vec::new(),
                    rect: [0.0; 4],
                };
            } else if ch == '\n' {
                self.sections.push(current_section);
                current_section = Section {
                    words: Vec::new(),
                    lines: Vec::new(),
                    rect: [0.0; 4],
                };
            } else {
                current_section.words.push(WordInfo {
                    character: ch,
                    font_index: 0,
                    position_x: 0.0,
                    width: 0.0,
                });
            }
        }
        self.sections.push(current_section);
    }

    /// Reflow all sections into lines.
    ///
    /// Must be called after `set_text()` to compute the layout.
    pub fn rearrange(&mut self) {
        if self.auto_font_size {
            self.font_size = self.find_auto_font_size();
        }

        let plate_width = self.plate_rect[2] - self.plate_rect[0];

        let mut total_y = self.plate_rect[3]; // start from top

        for section in &mut self.sections {
            // Measure character widths
            for word in &mut section.words {
                word.width = self.provider.char_width(
                    word.font_index,
                    word.character as u16,
                    self.font_size,
                );
            }

            section.lines.clear();

            if let Some(cell_count) = self.char_array {
                // Character array mode: fixed grid
                let cell_width = if cell_count > 0 {
                    plate_width / cell_count as f32
                } else {
                    plate_width
                };
                let ascent = self.provider.ascent(0, self.font_size);
                let descent = self.provider.descent(0, self.font_size);

                let mut x_pos = 0.0;
                for (i, word) in section.words.iter_mut().enumerate() {
                    if i >= cell_count {
                        break;
                    }
                    // Center character in cell
                    word.position_x = x_pos + (cell_width - word.width) / 2.0;
                    x_pos += cell_width;
                }

                let line_width = section
                    .words
                    .iter()
                    .take(cell_count)
                    .next_back()
                    .map(|w| w.position_x + w.width)
                    .unwrap_or(0.0);

                let word_count = section.words.len().min(cell_count);
                total_y -= ascent;
                section.lines.push(Line {
                    word_start: 0,
                    word_count,
                    x: 0.0,
                    y: total_y,
                    width: line_width,
                    ascent,
                    descent,
                });
                total_y += descent;
            } else {
                // Normal line-breaking layout
                let ascent = self.provider.ascent(0, self.font_size);
                let descent = self.provider.descent(0, self.font_size);

                let mut line_start = 0;
                let mut line_width = 0.0_f32;
                let mut x_pos = 0.0_f32;

                for (i, word) in section.words.iter_mut().enumerate() {
                    let char_width = word.width;

                    // Check for line break
                    let should_break = self.multi_line
                        && self.auto_return
                        && line_width + char_width > plate_width
                        && i > line_start;

                    if should_break {
                        // Finalize current line
                        let word_count = i - line_start;
                        total_y -= ascent;
                        section.lines.push(Line {
                            word_start: line_start,
                            word_count,
                            x: 0.0,
                            y: total_y,
                            width: line_width,
                            ascent,
                            descent,
                        });
                        total_y += descent;

                        // Start new line
                        line_start = i;
                        line_width = 0.0;
                        x_pos = 0.0;
                    }

                    word.position_x = x_pos;
                    x_pos += char_width;
                    line_width += char_width;
                }

                // Final line
                let word_count = section.words.len() - line_start;
                if word_count > 0 || section.lines.is_empty() {
                    total_y -= ascent;
                    section.lines.push(Line {
                        word_start: line_start,
                        word_count,
                        x: 0.0,
                        y: total_y,
                        width: line_width,
                        ascent,
                        descent,
                    });
                    total_y += descent;
                }
            }

            // Apply alignment
            for line in &mut section.lines {
                line.x = match self.alignment {
                    Alignment::Left => 0.0,
                    Alignment::Center => (plate_width - line.width) / 2.0,
                    Alignment::Right => plate_width - line.width,
                };
            }

            // Compute section rect
            if let (Some(first), Some(last)) = (section.lines.first(), section.lines.last()) {
                section.rect = [
                    self.plate_rect[0],
                    last.y + last.descent,
                    self.plate_rect[2],
                    first.y + first.ascent,
                ];
            }
        }

        // Compute content rect
        if let (Some(first_sec), Some(last_sec)) = (self.sections.first(), self.sections.last()) {
            self.content_rect = [
                self.plate_rect[0],
                last_sec.rect[1],
                self.plate_rect[2],
                first_sec.rect[3],
            ];
        }
    }

    /// Return the bounding box of the laid-out text.
    pub fn content_rect(&self) -> [f32; 4] {
        self.content_rect
    }

    /// ADR-019 alias for [`content_rect()`](Self::content_rect).
    ///
    /// Corresponds to `CPDF_VariableText::GetContentRect()` in PDFium.
    #[inline]
    pub fn get_content_rect(&self) -> [f32; 4] {
        self.content_rect()
    }

    /// Return the sections after layout.
    pub fn sections(&self) -> &[Section] {
        &self.sections
    }

    /// Return the current font size (may differ from set value if auto-sizing).
    pub fn font_size(&self) -> f32 {
        self.font_size
    }

    /// Map a point (x, y) to the nearest WordPlace.
    pub fn hit_test(&self, x: f32, y: f32) -> Option<WordPlace> {
        let rel_x = x - self.plate_rect[0];
        let rel_y = y;

        for (si, section) in self.sections.iter().enumerate() {
            for (li, line) in section.lines.iter().enumerate() {
                let line_top = line.y + line.ascent;
                let line_bottom = line.y + line.descent;

                if rel_y <= line_top && rel_y >= line_bottom {
                    // Find the nearest word on this line
                    let line_x = rel_x - line.x;
                    let end = line.word_start + line.word_count;
                    for wi in line.word_start..end {
                        let word = &section.words[wi];
                        if line_x <= word.position_x + word.width / 2.0 {
                            return Some(WordPlace {
                                section: si,
                                line: li,
                                word: wi - line.word_start,
                            });
                        }
                    }
                    // Past end of line
                    return Some(WordPlace {
                        section: si,
                        line: li,
                        word: line.word_count.saturating_sub(1),
                    });
                }
            }
        }
        // Below all lines — return last position
        if let Some(last_sec) = self.sections.last() {
            if let Some(last_line) = last_sec.lines.last() {
                return Some(WordPlace {
                    section: self.sections.len() - 1,
                    line: last_sec.lines.len() - 1,
                    word: last_line.word_count.saturating_sub(1),
                });
            }
        }
        None
    }

    /// Convert a WordPlace to a flat character index.
    pub fn word_place_to_index(&self, place: &WordPlace) -> usize {
        let mut index = 0;
        for (si, section) in self.sections.iter().enumerate() {
            if si < place.section {
                index += section.words.len();
                index += 1; // count the \n separator
            } else {
                // Find the offset within this section
                if let Some(line) = section.lines.get(place.line) {
                    index += line.word_start + place.word;
                }
                break;
            }
        }
        index
    }

    /// Insert text at a given position.
    ///
    /// Characters are inserted at the section/line/word position described by
    /// `place`. The layout is automatically re-computed via `rearrange()`.
    pub fn insert(&mut self, place: &WordPlace, text: &str) -> DocResult<()> {
        let si = place.section;
        if si >= self.sections.len() {
            return Err(DocError::InvalidIndex(si));
        }

        // Compute absolute word index within the section.
        let abs_idx = {
            let section = &self.sections[si];
            if section.lines.is_empty() {
                0
            } else {
                let li = place.line.min(section.lines.len() - 1);
                let line = &section.lines[li];
                let wi = place.word.min(line.word_count);
                line.word_start + wi
            }
        };

        // Inherit font_index from the neighbour at abs_idx (if any).
        let font_index = self.sections[si]
            .words
            .get(abs_idx)
            .or_else(|| self.sections[si].words.get(abs_idx.saturating_sub(1)))
            .map(|w| w.font_index)
            .unwrap_or(0);

        // Insert one WordInfo per character.
        for (offset, ch) in text.chars().enumerate() {
            self.sections[si].words.insert(
                abs_idx + offset,
                WordInfo {
                    character: ch,
                    font_index,
                    position_x: 0.0,
                    width: 0.0,
                },
            );
        }

        self.rearrange();
        Ok(())
    }

    /// Delete text within a range.
    ///
    /// `range.begin` and `range.end` must refer to the same section.
    /// Characters from `begin` (inclusive) through `end` (exclusive) are
    /// removed. The layout is automatically re-computed via `rearrange()`.
    pub fn delete(&mut self, range: &WordRange) -> DocResult<()> {
        let si = range.begin.section;
        if si >= self.sections.len() {
            return Err(DocError::InvalidIndex(si));
        }
        if range.end.section != si {
            return Err(DocError::TypeMismatch {
                expected: "same-section range".into(),
                got: "cross-section range".into(),
            });
        }

        // Convert WordPlace to absolute section word indices.
        let begin_abs = {
            let section = &self.sections[si];
            if section.lines.is_empty() {
                return Ok(());
            }
            let li = range.begin.line.min(section.lines.len() - 1);
            let line = &section.lines[li];
            line.word_start + range.begin.word.min(line.word_count)
        };
        let end_abs = {
            let section = &self.sections[si];
            let li = range.end.line.min(section.lines.len() - 1);
            let line = &section.lines[li];
            (line.word_start + range.end.word.min(line.word_count)).min(section.words.len())
        };

        if begin_abs < end_abs {
            self.sections[si].words.drain(begin_abs..end_abs);
            self.rearrange();
        }
        Ok(())
    }

    /// Iterate over all lines across all sections.
    pub fn iter_lines(&self) -> impl Iterator<Item = (usize, &Line)> {
        self.sections
            .iter()
            .flat_map(|section| section.lines.iter())
            .enumerate()
    }

    /// Iterate over all words across all sections.
    pub fn iter_words(&self) -> impl Iterator<Item = &WordInfo> {
        self.sections
            .iter()
            .flat_map(|section| section.words.iter())
    }

    /// Return the total number of lines across all sections.
    pub fn total_lines(&self) -> usize {
        self.sections.iter().map(|s| s.lines.len()).sum()
    }

    /// Return the total number of characters across all sections.
    pub fn total_words(&self) -> usize {
        self.sections.iter().map(|s| s.words.len()).sum()
    }

    /// Total word count as `i32` — upstream `CPVT_VariableText::GetTotalWords()` signature.
    ///
    /// Returns the same value as [`total_words()`](Self::total_words) cast to `i32`
    /// to match the upstream C++ return type.
    ///
    /// Corresponds to `CPVT_VariableText::GetTotalWords()` in PDFium.
    pub fn get_total_words(&self) -> i32 {
        self.total_words() as i32
    }

    /// Beginning of all content — section 0, line 0, word 0.
    pub fn begin_word_place(&self) -> WordPlace {
        WordPlace::default()
    }

    /// ADR-019 alias for `begin_word_place()`.
    #[inline]
    pub fn get_begin_word_place(&self) -> WordPlace {
        self.begin_word_place()
    }

    /// End of all content — last section, last line, last word.
    pub fn end_word_place(&self) -> WordPlace {
        if self.sections.is_empty() {
            return WordPlace::default();
        }
        let si = self.sections.len() - 1;
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return WordPlace {
                section: si,
                line: 0,
                word: 0,
            };
        }
        let li = section.lines.len() - 1;
        let word_count = section.lines[li].word_count;
        WordPlace {
            section: si,
            line: li,
            word: word_count.saturating_sub(1),
        }
    }

    /// ADR-019 alias for `end_word_place()`.
    #[inline]
    pub fn get_end_word_place(&self) -> WordPlace {
        self.end_word_place()
    }

    /// Previous word position (move backward by one character).
    ///
    /// Returns the same place if already at the beginning.
    pub fn prev_word_place(&self, place: &WordPlace) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let mut si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            if si == 0 {
                return WordPlace::default();
            }
            si -= 1;
            return self.section_end_place_for(si);
        }
        let mut li = place.line.min(section.lines.len() - 1);
        let mut wi = place.word;

        if wi > 0 {
            return WordPlace {
                section: si,
                line: li,
                word: wi - 1,
            };
        }
        if li > 0 {
            li -= 1;
            wi = self.sections[si].lines[li].word_count.saturating_sub(1);
            return WordPlace {
                section: si,
                line: li,
                word: wi,
            };
        }
        if si > 0 {
            si -= 1;
            return self.section_end_place_for(si);
        }
        WordPlace::default()
    }

    /// ADR-019 alias for `prev_word_place()`.
    #[inline]
    pub fn get_prev_word_place(&self, place: &WordPlace) -> WordPlace {
        self.prev_word_place(place)
    }

    /// Next word position (move forward by one character).
    ///
    /// Returns the same place if already at the end.
    pub fn next_word_place(&self, place: &WordPlace) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            if si + 1 < self.sections.len() {
                return WordPlace {
                    section: si + 1,
                    line: 0,
                    word: 0,
                };
            }
            return *place;
        }
        let li = place.line.min(section.lines.len() - 1);
        let line = &section.lines[li];
        let wi = place.word;

        if wi + 1 < line.word_count {
            return WordPlace {
                section: si,
                line: li,
                word: wi + 1,
            };
        }
        if li + 1 < section.lines.len() {
            return WordPlace {
                section: si,
                line: li + 1,
                word: 0,
            };
        }
        if si + 1 < self.sections.len() {
            return WordPlace {
                section: si + 1,
                line: 0,
                word: 0,
            };
        }
        *place
    }

    /// ADR-019 alias for `next_word_place()`.
    #[inline]
    pub fn get_next_word_place(&self, place: &WordPlace) -> WordPlace {
        self.next_word_place(place)
    }

    /// Hit-test: find the word place closest to an (x, y) plate coordinate.
    ///
    /// Equivalent to upstream `SearchWordPlace(point)`.
    pub fn search_word_place(&self, point: (f32, f32)) -> WordPlace {
        self.hit_test(point.0, point.1)
            .unwrap_or_else(|| self.end_word_place())
    }

    /// Move up one line from `place`, keeping the x-coordinate from `point`.
    ///
    /// Equivalent to upstream `GetUpWordPlace(place, point)`.
    pub fn up_word_place(&self, place: &WordPlace, point: (f32, f32)) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return *place;
        }
        let li = place.line.min(section.lines.len() - 1);

        let (target_si, target_li) = if li > 0 {
            (si, li - 1)
        } else if si > 0 {
            let prev_si = si - 1;
            let prev_lines = self.sections[prev_si].lines.len();
            if prev_lines == 0 {
                return *place;
            }
            (prev_si, prev_lines - 1)
        } else {
            return *place;
        };

        self.closest_word_on_line(target_si, target_li, point.0)
    }

    /// ADR-019 alias for `up_word_place()`.
    #[inline]
    pub fn get_up_word_place(&self, place: &WordPlace, point: (f32, f32)) -> WordPlace {
        self.up_word_place(place, point)
    }

    /// Move down one line from `place`, keeping the x-coordinate from `point`.
    ///
    /// Equivalent to upstream `GetDownWordPlace(place, point)`.
    pub fn down_word_place(&self, place: &WordPlace, point: (f32, f32)) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return *place;
        }
        let li = place.line.min(section.lines.len() - 1);

        let (target_si, target_li) = if li + 1 < section.lines.len() {
            (si, li + 1)
        } else if si + 1 < self.sections.len() {
            let next_si = si + 1;
            if self.sections[next_si].lines.is_empty() {
                return *place;
            }
            (next_si, 0)
        } else {
            return *place;
        };

        self.closest_word_on_line(target_si, target_li, point.0)
    }

    /// ADR-019 alias for `down_word_place()`.
    #[inline]
    pub fn get_down_word_place(&self, place: &WordPlace, point: (f32, f32)) -> WordPlace {
        self.down_word_place(place, point)
    }

    /// First word of the line containing `place`.
    ///
    /// Equivalent to upstream `GetLineBeginPlace(place)`.
    pub fn line_begin_place(&self, place: &WordPlace) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return WordPlace {
                section: si,
                line: 0,
                word: 0,
            };
        }
        let li = place.line.min(section.lines.len() - 1);
        WordPlace {
            section: si,
            line: li,
            word: 0,
        }
    }

    /// ADR-019 alias for `line_begin_place()`.
    #[inline]
    pub fn get_line_begin_place(&self, place: &WordPlace) -> WordPlace {
        self.line_begin_place(place)
    }

    /// Last word of the line containing `place`.
    ///
    /// Equivalent to upstream `GetLineEndPlace(place)`.
    pub fn line_end_place(&self, place: &WordPlace) -> WordPlace {
        if self.sections.is_empty() {
            return *place;
        }
        let si = place.section.min(self.sections.len() - 1);
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return WordPlace {
                section: si,
                line: 0,
                word: 0,
            };
        }
        let li = place.line.min(section.lines.len() - 1);
        let word_count = section.lines[li].word_count;
        WordPlace {
            section: si,
            line: li,
            word: word_count.saturating_sub(1),
        }
    }

    /// ADR-019 alias for `line_end_place()`.
    #[inline]
    pub fn get_line_end_place(&self, place: &WordPlace) -> WordPlace {
        self.line_end_place(place)
    }

    /// First word of the section containing `place`.
    ///
    /// Equivalent to upstream `GetSectionBeginPlace(place)`.
    pub fn section_begin_place(&self, place: &WordPlace) -> WordPlace {
        let si = if self.sections.is_empty() {
            0
        } else {
            place.section.min(self.sections.len() - 1)
        };
        WordPlace {
            section: si,
            line: 0,
            word: 0,
        }
    }

    /// ADR-019 alias for `section_begin_place()`.
    #[inline]
    pub fn get_section_begin_place(&self, place: &WordPlace) -> WordPlace {
        self.section_begin_place(place)
    }

    /// Last word of the section containing `place`.
    ///
    /// Equivalent to upstream `GetSectionEndPlace(place)`.
    pub fn section_end_place(&self, place: &WordPlace) -> WordPlace {
        if self.sections.is_empty() {
            return WordPlace::default();
        }
        let si = place.section.min(self.sections.len() - 1);
        self.section_end_place_for(si)
    }

    /// ADR-019 alias for `section_end_place()`.
    #[inline]
    pub fn get_section_end_place(&self, place: &WordPlace) -> WordPlace {
        self.section_end_place(place)
    }

    /// Clamp `place` to the nearest valid position.
    ///
    /// Equivalent to upstream `UpdateWordPlace(place)`.
    pub fn update_word_place(&self, place: &mut WordPlace) {
        if self.sections.is_empty() {
            *place = WordPlace::default();
            return;
        }
        place.section = place.section.min(self.sections.len() - 1);
        let section = &self.sections[place.section];
        if section.lines.is_empty() {
            place.line = 0;
            place.word = 0;
            return;
        }
        place.line = place.line.min(section.lines.len() - 1);
        let word_count = section.lines[place.line].word_count;
        if word_count == 0 {
            place.word = 0;
        } else {
            place.word = place.word.min(word_count - 1);
        }
    }

    /// Convert a `WordPlace` to a flat word index across all sections.
    ///
    /// This counts the newline separators between sections.
    /// Equivalent to upstream `WordPlaceToWordIndex(place)`.
    #[inline]
    pub fn word_place_to_word_index(&self, place: &WordPlace) -> usize {
        self.word_place_to_index(place)
    }

    /// Convert a flat word index to a `WordPlace`.
    ///
    /// Equivalent to upstream `WordIndexToWordPlace(index)`.
    pub fn word_index_to_word_place(&self, index: usize) -> WordPlace {
        let mut remaining = index;
        for (si, section) in self.sections.iter().enumerate() {
            let words_in_section = section.words.len();
            if remaining < words_in_section {
                for (li, line) in section.lines.iter().enumerate() {
                    if remaining < line.word_start + line.word_count {
                        let word = remaining.saturating_sub(line.word_start);
                        return WordPlace {
                            section: si,
                            line: li,
                            word,
                        };
                    }
                }
                return self.section_end_place_for(si);
            }
            remaining -= words_in_section;
            if remaining == 0 && si + 1 < self.sections.len() {
                return WordPlace {
                    section: si + 1,
                    line: 0,
                    word: 0,
                };
            }
            if si + 1 < self.sections.len() {
                remaining = remaining.saturating_sub(1);
            }
        }
        self.end_word_place()
    }

    // -----------------------------------------------------------------------
    // Plate dimensions and coordinate conversion
    // -----------------------------------------------------------------------

    /// Width of the plate rectangle.
    ///
    /// Equivalent to upstream `GetPlateWidth()`.
    pub fn plate_width(&self) -> f32 {
        self.plate_rect[2] - self.plate_rect[0]
    }

    /// ADR-019 alias for `plate_width()`.
    #[inline]
    pub fn get_plate_width(&self) -> f32 {
        self.plate_width()
    }

    /// Height of the plate rectangle.
    ///
    /// Equivalent to upstream `GetPlateHeight()`.
    pub fn plate_height(&self) -> f32 {
        self.plate_rect[3] - self.plate_rect[1]
    }

    /// ADR-019 alias for `plate_height()`.
    #[inline]
    pub fn get_plate_height(&self) -> f32 {
        self.plate_height()
    }

    /// Begin text point — top-left corner of the content area in plate space.
    ///
    /// Equivalent to upstream `GetBTPoint()`.
    pub fn begin_text_point(&self) -> (f32, f32) {
        (self.plate_rect[0], self.plate_rect[3])
    }

    /// ADR-019 alias for `begin_text_point()`.
    #[inline]
    pub fn get_bt_point(&self) -> (f32, f32) {
        self.begin_text_point()
    }

    /// End text point — bottom-right corner of the content area in plate space.
    ///
    /// Equivalent to upstream `GetETPoint()`.
    pub fn end_text_point(&self) -> (f32, f32) {
        (self.plate_rect[2], self.plate_rect[1])
    }

    /// ADR-019 alias for `end_text_point()`.
    #[inline]
    pub fn get_et_point(&self) -> (f32, f32) {
        self.end_text_point()
    }

    /// Convert internal (layout) coordinates to plate/output coordinates.
    ///
    /// Equivalent to upstream `InToOut(point)`.
    pub fn in_to_out(&self, point: (f32, f32)) -> (f32, f32) {
        (point.0 + self.plate_rect[0], self.plate_rect[3] - point.1)
    }

    /// Convert plate coordinates to internal layout coordinates.
    ///
    /// Equivalent to upstream `OutToIn(point)`.
    pub fn out_to_in(&self, point: (f32, f32)) -> (f32, f32) {
        (point.0 - self.plate_rect[0], self.plate_rect[3] - point.1)
    }

    // -----------------------------------------------------------------------
    // Configuration getters
    // -----------------------------------------------------------------------

    /// Return the password substitution character (upstream `GetPasswordChar()`).
    pub fn password_char(&self) -> Option<char> {
        self.password_char
    }

    /// ADR-019 alias for `password_char()`.
    #[inline]
    pub fn get_password_char(&self) -> Option<char> {
        self.password_char()
    }

    /// Return the password substitution character (upstream `GetSubWord()` name).
    ///
    /// Deprecated: neither the idiomatic Rust primary nor the exact upstream alias.
    /// Use [`password_char()`](Self::password_char) (primary) or
    /// [`get_sub_word()`](Self::get_sub_word) (upstream-aligned alias) instead.
    #[deprecated(
        since = "0.1.0",
        note = "use password_char() or get_sub_word() instead"
    )]
    #[inline]
    pub fn sub_word(&self) -> Option<char> {
        self.password_char()
    }

    /// ADR-019 alias for [`password_char()`](Self::password_char).
    ///
    /// Corresponds to `CPVT_VariableText::GetSubWord()` in PDFium.
    #[inline]
    pub fn get_sub_word(&self) -> Option<char> {
        self.password_char()
    }

    /// Return the configured font size.
    #[inline]
    pub fn get_font_size(&self) -> f32 {
        self.font_size()
    }

    /// Return the text alignment.
    pub fn alignment(&self) -> Alignment {
        self.alignment
    }

    /// ADR-019 alias for `alignment()`.
    #[inline]
    pub fn get_alignment(&self) -> Alignment {
        self.alignment()
    }

    /// Return whether multi-line mode is enabled.
    pub fn is_multi_line(&self) -> bool {
        self.multi_line
    }

    /// Return whether automatic line return is enabled.
    pub fn is_auto_return(&self) -> bool {
        self.auto_return
    }

    /// Return the character array cell count, if set.
    ///
    /// When `Some(n)`, the field is laid out as a fixed grid of `n` cells.
    /// Corresponds to upstream `CPDF_VariableText::GetCharArray()`.
    pub fn char_array(&self) -> Option<usize> {
        self.char_array
    }

    /// Upstream-aligned alias for [`char_array()`](Self::char_array).
    ///
    /// Corresponds to `CPDF_VariableText::GetCharArray()` in PDFium.
    #[inline]
    pub fn get_char_array(&self) -> Option<usize> {
        self.char_array()
    }

    /// Return the maximum character limit, if set.
    ///
    /// When `Some(n)`, input is capped at `n` characters.
    /// Corresponds to upstream `CPDF_VariableText::GetLimitChar()`.
    pub fn limit_char(&self) -> Option<usize> {
        self.limit_char
    }

    /// Upstream-aligned alias for [`limit_char()`](Self::limit_char).
    ///
    /// Corresponds to `CPDF_VariableText::GetLimitChar()` in PDFium.
    #[inline]
    pub fn get_limit_char(&self) -> Option<usize> {
        self.limit_char()
    }

    // -----------------------------------------------------------------------
    // Metrics helpers
    // -----------------------------------------------------------------------

    /// Approximate line leading (line-to-line distance).
    ///
    /// Computed as `ascent - descent` using font index 0.
    /// Equivalent to upstream `GetLineLeading()`.
    pub fn line_leading(&self) -> f32 {
        let asc = self.provider.ascent(0, self.font_size);
        let desc = self.provider.descent(0, self.font_size);
        asc - desc
    }

    /// ADR-019 alias for `line_leading()`.
    #[inline]
    pub fn get_line_leading(&self) -> f32 {
        self.line_leading()
    }

    /// Font ascent at the current font size for font index 0.
    ///
    /// Equivalent to upstream `GetLineAscent()`.
    pub fn line_ascent(&self) -> f32 {
        self.provider.ascent(0, self.font_size)
    }

    /// Font descent at the current font size for font index 0.
    ///
    /// Equivalent to upstream `GetLineDescent()`.
    pub fn line_descent(&self) -> f32 {
        self.provider.descent(0, self.font_size)
    }

    /// Create a stateful iterator over this `VariableText`.
    ///
    /// Returns a `VtWordIterator` positioned at the beginning of the text.
    pub fn word_iterator(&self) -> VtWordIterator<'_, P> {
        VtWordIterator::new(self)
    }

    // -----------------------------------------------------------------------
    // Private helpers
    // -----------------------------------------------------------------------

    /// Return the `WordPlace` for the last character of section `si`.
    fn section_end_place_for(&self, si: usize) -> WordPlace {
        if si >= self.sections.len() {
            return self.end_word_place();
        }
        let section = &self.sections[si];
        if section.lines.is_empty() {
            return WordPlace {
                section: si,
                line: 0,
                word: 0,
            };
        }
        let li = section.lines.len() - 1;
        let word_count = section.lines[li].word_count;
        WordPlace {
            section: si,
            line: li,
            word: word_count.saturating_sub(1),
        }
    }

    /// Find the closest word to x-coordinate `x` on line `li` of section `si`.
    fn closest_word_on_line(&self, si: usize, li: usize, x: f32) -> WordPlace {
        let section = &self.sections[si];
        let line = &section.lines[li];
        if line.word_count == 0 {
            return WordPlace {
                section: si,
                line: li,
                word: 0,
            };
        }
        let rel_x = x - self.plate_rect[0] - line.x;
        let end = line.word_start + line.word_count;
        for wi in line.word_start..end {
            let word = &section.words[wi];
            if rel_x <= word.position_x + word.width / 2.0 {
                return WordPlace {
                    section: si,
                    line: li,
                    word: wi - line.word_start,
                };
            }
        }
        WordPlace {
            section: si,
            line: li,
            word: line.word_count - 1,
        }
    }

    /// Find the best font size that fits all text within the plate rect.
    fn find_auto_font_size(&self) -> f32 {
        let plate_width = self.plate_rect[2] - self.plate_rect[0];
        let plate_height = self.plate_rect[3] - self.plate_rect[1];

        if plate_width <= 0.0 || plate_height <= 0.0 {
            return 1.0;
        }

        let total_chars: usize = self.sections.iter().map(|s| s.words.len()).sum();
        if total_chars == 0 {
            return self.font_size;
        }

        // Linear scan through ascending sizes — keep the largest that fits
        let mut best = AUTO_FONT_SIZES[0];

        for &size in AUTO_FONT_SIZES {
            if self.text_fits_at_size(size, plate_width, plate_height) {
                best = size;
            } else {
                break;
            }
        }

        best
    }

    /// Check if the current text fits in the plate at a given font size.
    fn text_fits_at_size(&self, size: f32, plate_width: f32, plate_height: f32) -> bool {
        let ascent = self.provider.ascent(0, size);
        let descent = self.provider.descent(0, size);
        let line_height = ascent - descent;

        if line_height <= 0.0 {
            return false;
        }

        let mut total_lines = 0_usize;

        for section in &self.sections {
            if section.words.is_empty() {
                total_lines += 1;
                continue;
            }

            let mut line_width = 0.0_f32;
            let mut lines_in_section = 1_usize;

            for word in &section.words {
                let w = self
                    .provider
                    .char_width(word.font_index, word.character as u16, size);
                if self.multi_line
                    && self.auto_return
                    && line_width + w > plate_width
                    && line_width > 0.0
                {
                    lines_in_section += 1;
                    line_width = w;
                } else {
                    line_width += w;
                }

                // Single-line: check total width
                if !self.multi_line && line_width > plate_width {
                    return false;
                }
            }

            total_lines += lines_in_section;
        }

        let total_height = total_lines as f32 * line_height;
        total_height <= plate_height
    }
}

// ---------------------------------------------------------------------------
// VtWordIterator — stateful position-based iterator
// ---------------------------------------------------------------------------

/// Stateful iterator over character positions in a `VariableText`.
///
/// Corresponds to the inner `Iterator` class in upstream `CPVT_VariableText`.
/// Unlike `VtIterator` (which is a Rust `Iterator` over `WordInfo` values),
/// `VtWordIterator` mirrors the upstream class with explicit `next_word()` /
/// `next_line()` step methods and a `word_place()` position query.
pub struct VtWordIterator<'a, P: VtFontProvider> {
    vt: &'a VariableText<P>,
    current: WordPlace,
}

impl<'a, P: VtFontProvider> VtWordIterator<'a, P> {
    /// Create a new iterator positioned at the beginning.
    pub fn new(vt: &'a VariableText<P>) -> Self {
        Self {
            vt,
            current: vt.begin_word_place(),
        }
    }

    /// Move the iterator to the position described by a flat word index.
    ///
    /// Equivalent to upstream `Iterator::SetAt(int32_t index)`.
    pub fn set_at_index(&mut self, word_index: i32) {
        let idx = if word_index < 0 {
            0
        } else {
            word_index as usize
        };
        self.current = self.vt.word_index_to_word_place(idx);
    }

    /// Move the iterator to an explicit place.
    ///
    /// Equivalent to upstream `Iterator::SetAt(const CPVT_WordPlace& place)`.
    pub fn set_at_place(&mut self, place: WordPlace) {
        self.current = place;
    }

    /// Advance one character forward.
    ///
    /// Returns `true` if the iterator moved; `false` if already at the end.
    /// Equivalent to upstream `Iterator::NextWord()`.
    pub fn next_word(&mut self) -> bool {
        let next = self.vt.next_word_place(&self.current);
        if next == self.current {
            return false;
        }
        self.current = next;
        true
    }

    /// Advance to the start of the next line.
    ///
    /// Returns `true` if the iterator moved; `false` if already on the last line.
    /// Equivalent to upstream `Iterator::NextLine()`.
    pub fn next_line(&mut self) -> bool {
        if self.vt.sections.is_empty() {
            return false;
        }
        let si = self.current.section.min(self.vt.sections.len() - 1);
        let section = &self.vt.sections[si];
        if section.lines.is_empty() {
            return false;
        }
        let li = self.current.line.min(section.lines.len() - 1);
        if li + 1 < section.lines.len() {
            self.current = WordPlace {
                section: si,
                line: li + 1,
                word: 0,
            };
            return true;
        }
        if si + 1 < self.vt.sections.len() {
            self.current = WordPlace {
                section: si + 1,
                line: 0,
                word: 0,
            };
            return true;
        }
        false
    }

    /// Return the current iterator position.
    ///
    /// Equivalent to upstream `Iterator::GetWordPlace()`.
    pub fn word_place(&self) -> &WordPlace {
        &self.current
    }

    /// ADR-019 alias for `word_place()`.
    #[inline]
    pub fn get_word_place(&self) -> &WordPlace {
        self.word_place()
    }
}

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

    /// Simple fixed-width font provider for testing.
    struct FixedWidthProvider {
        char_width: f32,
        ascent: f32,
        descent: f32,
    }

    impl FixedWidthProvider {
        fn new(char_width: f32) -> Self {
            Self {
                char_width,
                ascent: 10.0,
                descent: -3.0,
            }
        }
    }

    impl VtFontProvider for FixedWidthProvider {
        fn char_width(&self, _font_index: usize, _word: u16, font_size: f32) -> f32 {
            self.char_width * (font_size / 12.0)
        }
        fn ascent(&self, _font_index: usize, font_size: f32) -> f32 {
            self.ascent * (font_size / 12.0)
        }
        fn descent(&self, _font_index: usize, font_size: f32) -> f32 {
            self.descent * (font_size / 12.0)
        }
    }

    fn make_vt(provider: FixedWidthProvider) -> VariableText<FixedWidthProvider> {
        let mut vt = VariableText::new(provider);
        vt.set_plate_rect([0.0, 0.0, 200.0, 100.0]);
        vt.set_font_size(12.0);
        vt
    }

    #[test]
    fn test_empty_text() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 1);
        assert_eq!(vt.sections()[0].words.len(), 0);
        assert_eq!(vt.sections()[0].lines.len(), 1);
    }

    #[test]
    fn test_single_line_text() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 1);
        assert_eq!(vt.sections()[0].words.len(), 5);
        assert_eq!(vt.sections()[0].lines.len(), 1);
        assert_eq!(vt.sections()[0].lines[0].word_count, 5);
    }

    #[test]
    fn test_multi_section_text() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Line1\nLine2\nLine3");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 3);
        assert_eq!(vt.sections()[0].words.len(), 5);
        assert_eq!(vt.sections()[1].words.len(), 5);
        assert_eq!(vt.sections()[2].words.len(), 5);
    }

    #[test]
    fn test_line_breaking() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_multi_line(true);
        vt.set_auto_return(true);
        // Plate width = 200, char width = 6, so ~33 chars per line
        // 50 chars should break into 2 lines
        let text: String = "A".repeat(50);
        vt.set_text(&text);
        vt.rearrange();
        assert_eq!(vt.sections()[0].lines.len(), 2);
    }

    #[test]
    fn test_no_line_breaking_single_line_mode() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_multi_line(false);
        let text: String = "A".repeat(50);
        vt.set_text(&text);
        vt.rearrange();
        assert_eq!(vt.sections()[0].lines.len(), 1);
        assert_eq!(vt.sections()[0].lines[0].word_count, 50);
    }

    #[test]
    fn test_alignment_left() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_alignment(Alignment::Left);
        vt.set_text("Hi");
        vt.rearrange();
        assert!((vt.sections()[0].lines[0].x - 0.0).abs() < 0.01);
    }

    #[test]
    fn test_alignment_center() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_alignment(Alignment::Center);
        vt.set_text("Hi");
        vt.rearrange();
        let line = &vt.sections()[0].lines[0];
        // 2 chars * 6.0 = 12.0, plate_width = 200.0, offset = (200-12)/2 = 94.0
        assert!((line.x - 94.0).abs() < 0.01);
    }

    #[test]
    fn test_alignment_right() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_alignment(Alignment::Right);
        vt.set_text("Hi");
        vt.rearrange();
        let line = &vt.sections()[0].lines[0];
        // offset = 200 - 12 = 188
        assert!((line.x - 188.0).abs() < 0.01);
    }

    #[test]
    fn test_alignment_from_value() {
        assert_eq!(Alignment::from_value(0), Alignment::Left);
        assert_eq!(Alignment::from_value(1), Alignment::Center);
        assert_eq!(Alignment::from_value(2), Alignment::Right);
        assert_eq!(Alignment::from_value(99), Alignment::Left);
    }

    #[test]
    fn test_char_array_mode() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_char_array(Some(10));
        vt.set_text("ABC");
        vt.rearrange();
        let section = &vt.sections()[0];
        assert_eq!(section.lines.len(), 1);
        assert_eq!(section.lines[0].word_count, 3);
        // Cell width = 200/10 = 20, first char centered in cell
        let first_word = &section.words[0];
        let expected_x = (20.0 - 6.0) / 2.0; // centered in 20pt cell
        assert!((first_word.position_x - expected_x).abs() < 0.01);
    }

    #[test]
    fn test_char_array_limits_to_count() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_char_array(Some(3));
        vt.set_text("ABCDE");
        vt.rearrange();
        assert_eq!(vt.sections()[0].lines[0].word_count, 3);
    }

    #[test]
    fn test_password_masking() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_password_char(Some('*'));
        vt.set_text("secret");
        vt.rearrange();
        let section = &vt.sections()[0];
        assert_eq!(section.words.len(), 6);
        for word in &section.words {
            assert_eq!(word.character, '*');
        }
    }

    #[test]
    fn test_limit_char() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_limit_char(Some(5));
        vt.set_text("Hello World");
        vt.rearrange();
        assert_eq!(vt.sections()[0].words.len(), 5);
    }

    #[test]
    fn test_auto_font_size() {
        let mut vt = VariableText::new(FixedWidthProvider::new(6.0));
        vt.set_plate_rect([0.0, 0.0, 100.0, 20.0]);
        vt.set_auto_font_size(true);
        vt.set_text("Hello World This Is Long");
        vt.rearrange();
        // Auto-size should have found a size that fits
        let content_height = vt.content_rect()[3] - vt.content_rect()[1];
        assert!(content_height <= 20.0 + 1.0); // small tolerance
    }

    #[test]
    fn test_auto_font_size_empty() {
        let mut vt = VariableText::new(FixedWidthProvider::new(6.0));
        vt.set_plate_rect([0.0, 0.0, 100.0, 20.0]);
        vt.set_font_size(12.0);
        vt.set_auto_font_size(true);
        vt.set_text("");
        vt.rearrange();
        assert_eq!(vt.font_size(), 12.0);
    }

    #[test]
    fn test_hit_test_first_char() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let line = &vt.sections()[0].lines[0];
        let y = line.y + line.ascent / 2.0;
        let place = vt.hit_test(1.0, y);
        assert!(place.is_some());
        assert_eq!(place.unwrap().word, 0);
    }

    #[test]
    fn test_hit_test_past_end() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hi");
        vt.rearrange();
        let line = &vt.sections()[0].lines[0];
        let y = line.y + line.ascent / 2.0;
        let place = vt.hit_test(100.0, y);
        assert!(place.is_some());
        assert_eq!(place.unwrap().word, 1); // last char
    }

    #[test]
    fn test_word_place_to_index_first() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let idx = vt.word_place_to_index(&WordPlace {
            section: 0,
            line: 0,
            word: 0,
        });
        assert_eq!(idx, 0);
    }

    #[test]
    fn test_word_place_to_index_second_section() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("AB\nCD");
        vt.rearrange();
        let idx = vt.word_place_to_index(&WordPlace {
            section: 1,
            line: 0,
            word: 0,
        });
        assert_eq!(idx, 3); // 2 chars + 1 newline separator
    }

    #[test]
    fn test_word_place_to_index_mid() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let idx = vt.word_place_to_index(&WordPlace {
            section: 0,
            line: 0,
            word: 3,
        });
        assert_eq!(idx, 3);
    }

    #[test]
    fn test_content_rect_non_empty() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let cr = vt.content_rect();
        assert!(cr[3] > cr[1]); // top > bottom
    }

    #[test]
    fn test_multi_line_many_breaks() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_multi_line(true);
        vt.set_auto_return(true);
        // Plate is 200 wide, char is 6, so 33 chars per line
        // 100 chars → ceil(100/33) = 4 lines
        let text: String = "X".repeat(100);
        vt.set_text(&text);
        vt.rearrange();
        let line_count = vt.sections()[0].lines.len();
        assert!(line_count >= 3);
        assert!(line_count <= 4);
    }

    #[test]
    fn test_word_info_positions_increase() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("ABCDE");
        vt.rearrange();
        let words = &vt.sections()[0].words;
        for i in 1..words.len() {
            assert!(words[i].position_x > words[i - 1].position_x);
        }
    }

    #[test]
    fn test_cjk_characters_layout() {
        // CJK characters are wider — use a wider char width
        let mut vt = VariableText::new(FixedWidthProvider::new(12.0));
        vt.set_plate_rect([0.0, 0.0, 100.0, 100.0]);
        vt.set_font_size(12.0);
        vt.set_multi_line(true);
        vt.set_auto_return(true);
        // 100 / 12 = ~8 chars per line, 15 chars → 2 lines
        let text: String = "\u{4E00}".repeat(15);
        vt.set_text(&text);
        vt.rearrange();
        assert!(vt.sections()[0].lines.len() >= 2);
    }

    #[test]
    fn test_multi_line_auto_font_size() {
        let mut vt = VariableText::new(FixedWidthProvider::new(6.0));
        vt.set_plate_rect([0.0, 0.0, 50.0, 30.0]);
        vt.set_multi_line(true);
        vt.set_auto_return(true);
        vt.set_auto_font_size(true);
        vt.set_text("This is a fairly long text that needs to fit");
        vt.rearrange();
        assert!(vt.font_size() < 12.0); // should have reduced
        assert!(vt.font_size() >= 4.0); // but not below minimum
    }

    #[test]
    fn test_line_y_positions_decrease() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Line1\nLine2\nLine3");
        vt.rearrange();
        let y0 = vt.sections()[0].lines[0].y;
        let y1 = vt.sections()[1].lines[0].y;
        let y2 = vt.sections()[2].lines[0].y;
        assert!(y0 > y1);
        assert!(y1 > y2);
    }

    #[test]
    fn test_hit_test_below_all_lines() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        // Very low y value
        let place = vt.hit_test(5.0, -100.0);
        assert!(place.is_some());
    }

    #[test]
    fn test_word_range_creation() {
        let range = WordRange {
            begin: WordPlace {
                section: 0,
                line: 0,
                word: 0,
            },
            end: WordPlace {
                section: 0,
                line: 0,
                word: 5,
            },
        };
        assert_eq!(range.begin.word, 0);
        assert_eq!(range.end.word, 5);
    }

    #[test]
    fn test_cr_line_endings() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Line1\rLine2\rLine3");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 3);
        assert_eq!(vt.sections()[0].words.len(), 5);
        assert_eq!(vt.sections()[1].words.len(), 5);
        assert_eq!(vt.sections()[2].words.len(), 5);
    }

    #[test]
    fn test_crlf_line_endings() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Line1\r\nLine2\r\nLine3");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 3);
        assert_eq!(vt.sections()[0].words.len(), 5);
        assert_eq!(vt.sections()[1].words.len(), 5);
        assert_eq!(vt.sections()[2].words.len(), 5);
    }

    #[test]
    fn test_mixed_line_endings() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("A\r\nB\rC\nD");
        vt.rearrange();
        assert_eq!(vt.sections().len(), 4);
        assert_eq!(vt.sections()[0].words.len(), 1); // A
        assert_eq!(vt.sections()[1].words.len(), 1); // B
        assert_eq!(vt.sections()[2].words.len(), 1); // C
        assert_eq!(vt.sections()[3].words.len(), 1); // D
    }

    #[test]
    fn test_insert_adds_chars_and_rearranges() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let place = WordPlace {
            section: 0,
            line: 0,
            word: 2,
        };
        vt.insert(&place, "XY").unwrap();
        // "He" + "XY" + "llo" = 7 chars
        assert_eq!(vt.sections()[0].words.len(), 7);
        assert_eq!(vt.sections()[0].words[2].character, 'X');
        assert_eq!(vt.sections()[0].words[3].character, 'Y');
    }

    #[test]
    fn test_delete_removes_chars_and_rearranges() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let range = WordRange {
            begin: WordPlace {
                section: 0,
                line: 0,
                word: 0,
            },
            end: WordPlace {
                section: 0,
                line: 0,
                word: 3,
            },
        };
        vt.delete(&range).unwrap();
        // "Hello" with indices 0..3 removed → "lo"
        assert_eq!(vt.sections()[0].words.len(), 2);
        assert_eq!(vt.sections()[0].words[0].character, 'l');
        assert_eq!(vt.sections()[0].words[1].character, 'o');
    }

    #[test]
    fn test_iter_lines_count() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Line1\nLine2\nLine3");
        vt.rearrange();
        assert_eq!(vt.iter_lines().count(), 3);
        assert_eq!(vt.total_lines(), 3);
    }

    #[test]
    fn test_iter_words_count() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        assert_eq!(vt.iter_words().count(), 5);
        assert_eq!(vt.total_words(), 5);
    }

    #[test]
    fn test_iter_words_across_sections() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("AB\nCD");
        vt.rearrange();
        assert_eq!(vt.iter_words().count(), 4);
        assert_eq!(vt.total_words(), 4);
    }

    // -----------------------------------------------------------------------
    // Navigation / query method tests
    // -----------------------------------------------------------------------

    #[test]
    fn test_total_words_empty() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("");
        vt.rearrange();
        assert_eq!(vt.total_words(), 0);
        assert_eq!(vt.get_total_words(), 0);
    }

    #[test]
    fn test_total_words_single() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("A");
        vt.rearrange();
        assert_eq!(vt.total_words(), 1);
    }

    #[test]
    fn test_total_words_multi() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello\nWorld");
        vt.rearrange();
        assert_eq!(vt.total_words(), 10);
    }

    #[test]
    fn test_begin_and_end_word_place_empty() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("");
        vt.rearrange();
        let begin = vt.begin_word_place();
        assert_eq!(begin, WordPlace::default());
        let end = vt.end_word_place();
        assert_eq!(end.section, 0);
    }

    #[test]
    fn test_begin_and_end_word_place_non_empty() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let begin = vt.begin_word_place();
        assert_eq!(
            begin,
            WordPlace {
                section: 0,
                line: 0,
                word: 0
            }
        );
        let end = vt.end_word_place();
        assert_eq!(end.section, 0);
        assert_eq!(end.word, 4);
    }

    #[test]
    fn test_word_place_to_word_index_round_trip() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("ABCDE");
        vt.rearrange();
        for i in 0..5 {
            let place = WordPlace {
                section: 0,
                line: 0,
                word: i,
            };
            let idx = vt.word_place_to_word_index(&place);
            assert_eq!(idx, i, "index mismatch at word {i}");
            let back = vt.word_index_to_word_place(idx);
            assert_eq!(back, place, "round-trip mismatch at word {i}");
        }
    }

    #[test]
    fn test_word_index_to_place_across_sections() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("AB\nCD");
        vt.rearrange();
        let p0 = vt.word_index_to_word_place(0);
        assert_eq!(
            p0,
            WordPlace {
                section: 0,
                line: 0,
                word: 0
            }
        );
        let p1 = vt.word_index_to_word_place(1);
        assert_eq!(
            p1,
            WordPlace {
                section: 0,
                line: 0,
                word: 1
            }
        );
        let p3 = vt.word_index_to_word_place(3);
        assert_eq!(p3.section, 1);
        assert_eq!(p3.word, 0);
    }

    #[test]
    fn test_prev_next_word_place_navigation() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("ABCDE");
        vt.rearrange();

        let mut place = vt.begin_word_place();
        let mut count = 0;
        loop {
            count += 1;
            let next = vt.next_word_place(&place);
            if next == place {
                break;
            }
            place = next;
        }
        assert_eq!(count, 5);

        place = vt.end_word_place();
        count = 0;
        loop {
            count += 1;
            let prev = vt.prev_word_place(&place);
            if prev == place {
                break;
            }
            place = prev;
        }
        assert_eq!(count, 5);
    }

    #[test]
    fn test_line_begin_and_end_place() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let mid = WordPlace {
            section: 0,
            line: 0,
            word: 2,
        };
        let begin = vt.line_begin_place(&mid);
        assert_eq!(begin.word, 0);
        let end = vt.line_end_place(&mid);
        assert_eq!(end.word, 4);
    }

    #[test]
    fn test_section_begin_and_end_place() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello\nWorld");
        vt.rearrange();
        let mid_sec1 = WordPlace {
            section: 1,
            line: 0,
            word: 2,
        };
        let sec_begin = vt.section_begin_place(&mid_sec1);
        assert_eq!(
            sec_begin,
            WordPlace {
                section: 1,
                line: 0,
                word: 0
            }
        );
        let sec_end = vt.section_end_place(&mid_sec1);
        assert_eq!(sec_end.section, 1);
        assert_eq!(sec_end.word, 4);
    }

    #[test]
    fn test_plate_width_and_height() {
        let vt = make_vt(FixedWidthProvider::new(6.0));
        assert!((vt.plate_width() - 200.0).abs() < 0.01);
        assert!((vt.plate_height() - 100.0).abs() < 0.01);
        assert!((vt.get_plate_width() - 200.0).abs() < 0.01);
        assert!((vt.get_plate_height() - 100.0).abs() < 0.01);
    }

    #[test]
    fn test_in_to_out_and_out_to_in_inverse() {
        let vt = make_vt(FixedWidthProvider::new(6.0));
        let original = (50.0_f32, 30.0_f32);
        let out = vt.in_to_out(original);
        let back = vt.out_to_in(out);
        assert!((back.0 - original.0).abs() < 0.001, "x mismatch");
        assert!((back.1 - original.1).abs() < 0.001, "y mismatch");
    }

    #[test]
    fn test_vt_word_iterator_next_word_advances() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("ABCDE");
        vt.rearrange();
        let mut it = vt.word_iterator();
        let mut count = 0;
        while it.next_word() {
            count += 1;
        }
        assert_eq!(count, 4);
    }

    #[test]
    fn test_vt_word_iterator_set_at_index() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("ABCDE");
        vt.rearrange();
        let mut it = vt.word_iterator();
        it.set_at_index(3);
        assert_eq!(it.word_place().word, 3);
    }

    #[test]
    fn test_vt_word_iterator_set_at_place() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let target = WordPlace {
            section: 0,
            line: 0,
            word: 2,
        };
        let mut it = vt.word_iterator();
        it.set_at_place(target);
        assert_eq!(*it.get_word_place(), target);
    }

    #[test]
    fn test_config_getters() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Test");
        vt.rearrange();
        assert!((vt.font_size() - 12.0).abs() < 0.01);
        assert!((vt.get_font_size() - 12.0).abs() < 0.01);
        assert_eq!(vt.alignment(), Alignment::Left);
        assert_eq!(vt.get_alignment(), Alignment::Left);
        assert!(!vt.is_multi_line());
        assert!(vt.is_auto_return());
    }

    #[test]
    fn test_password_char_getter() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        assert_eq!(vt.password_char(), None);
        assert_eq!(vt.get_password_char(), None);
        assert_eq!(vt.get_sub_word(), None);
        vt.set_password_char(Some('*'));
        assert_eq!(vt.password_char(), Some('*'));
        assert_eq!(vt.get_sub_word(), Some('*'));
        assert_eq!(vt.get_password_char(), Some('*'));
    }

    #[test]
    fn test_line_leading_positive() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hi");
        vt.rearrange();
        // ascent=10, descent=-3, leading=13
        assert!((vt.line_leading() - 13.0).abs() < 0.01);
        assert!((vt.get_line_leading() - 13.0).abs() < 0.01);
    }

    #[test]
    fn test_update_word_place_clamping() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hi");
        vt.rearrange();
        let mut out_of_bounds = WordPlace {
            section: 99,
            line: 99,
            word: 99,
        };
        vt.update_word_place(&mut out_of_bounds);
        assert_eq!(out_of_bounds.section, 0);
        assert_eq!(out_of_bounds.line, 0);
        assert!(out_of_bounds.word <= 1);
    }

    #[test]
    fn test_search_word_place_returns_valid() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello");
        vt.rearrange();
        let line = &vt.sections()[0].lines[0];
        let y = line.y + line.ascent / 2.0;
        let place = vt.search_word_place((10.0, y));
        assert_eq!(place.section, 0);
    }

    #[test]
    fn test_vt_word_iterator_next_line_across_sections() {
        let mut vt = make_vt(FixedWidthProvider::new(6.0));
        vt.set_text("Hello\nWorld");
        vt.rearrange();
        let mut it = vt.word_iterator();
        assert_eq!(it.word_place().section, 0);
        assert!(it.next_line());
        assert_eq!(it.word_place().section, 1);
        assert_eq!(it.word_place().line, 0);
        assert!(!it.next_line());
    }
}