braillify 2.2.0

use std::{borrow::Cow, cell::RefCell};

/// Small, semantic-neutral predicates shared with the NIKL analysis example.
/// Keeping them here lets the ordinary library test target verify analyzer
/// input boundaries without making the whole example a coverage target.
#[doc(hidden)]
pub mod corpus_analysis {
    /// Whether a corpus filename belongs to the deterministic sentence shards.
    pub fn is_sentence_corpus_shard_name(name: &str) -> bool {
        name.starts_with("sentence_") && name.ends_with(".json")
    }

    /// Whether the Unicode scalar immediately before `byte_index` is an ASCII
    /// letter or digit. Callers provide a boundary from `str::char_indices`.
    pub fn has_ascii_alphanumeric_before(input: &str, byte_index: usize) -> bool {
        input
            .get(..byte_index)
            .unwrap_or_default()
            .chars()
            .next_back()
            .is_some_and(|previous| previous.is_ascii_alphanumeric())
    }

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

        #[rstest::rstest]
        #[case::sentence_json("sentence_000.json", true)]
        #[case::wrong_prefix("document_000.json", false)]
        #[case::wrong_extension("sentence_000.txt", false)]
        fn classifies_sentence_corpus_shard_names(#[case] name: &str, #[case] expected: bool) {
            assert_eq!(is_sentence_corpus_shard_name(name), expected);
        }

        #[rstest::rstest]
        #[case::start_of_input("A(14)", 0, false)]
        #[case::ascii_letter("BA(14)", 1, true)]
        #[case::ascii_digit("1A(14)", 1, true)]
        #[case::korean_scalar("가A(14)", 3, false)]
        #[case::non_scalar_boundary("가A(14)", 1, false)]
        fn detects_ascii_alphanumeric_immediately_before_boundary(
            #[case] input: &str,
            #[case] byte_index: usize,
            #[case] expected: bool,
        ) {
            assert_eq!(has_ascii_alphanumeric_before(input, byte_index), expected);
        }
    }
}

mod char_shortcut;
pub(crate) mod char_struct;
#[cfg(feature = "cli")]
pub mod cli;
mod encoder;
pub(crate) mod english;
pub(crate) mod english_logic;
pub(crate) mod fraction;
mod hanja;
mod ipa;
mod jauem;
mod korean_char;
mod korean_part;
mod math_symbol_shortcut;
mod moeum;
pub(crate) mod number;
mod rule;
pub(crate) mod rules;
mod split;
pub(crate) mod symbol_shortcut;
pub(crate) mod unicode;
pub(crate) mod utils;
pub(crate) mod word_shortcut;
use ipa::{detect_ipa_context, encode_ipa, is_ipa_phonetic_symbol};
/// Shared test helpers (cfg(test) only).
///
/// Provides reusable builders for `RuleContext` and friends so individual
/// rule tests don't have to repeat 10+ lines of field initialization.
/// Inlined here per project convention: test-only `.rs` files must be
/// either inline in their owning module or in `tests/`. Since this helper
/// is shared across 38+ rule modules (all crate-internal), the crate root
/// is the owning module.
#[cfg(test)]
mod test_helpers {
    use crate::char_struct::CharType;
    use crate::rules::context::{EncoderState, RuleContext};

    /// Borrowed snapshot used by `make_ctx`. Owns everything `RuleContext` needs
    /// references to (chars, char_type, state, etc.) so the caller can hand out
    /// a single mutable view.
    pub(crate) struct CtxOwned {
        pub word_chars: Vec<char>,
        pub char_types: Vec<CharType>,
        pub skip_count: usize,
        pub state: EncoderState,
        pub result: Vec<u8>,
        pub prev_word: String,
        pub remaining_words: Vec<String>,
        pub roman_section_continues_from_previous_word: bool,
    }

    impl CtxOwned {
        /// Build a fresh owned context for `text`. Each char is classified via
        /// `CharType::new`. The `index` parameter is used by callers when
        /// constructing the actual `RuleContext` borrow.
        pub(crate) fn for_text(text: &str, english_indicator: bool) -> Self {
            let word_chars: Vec<char> = text.chars().collect();
            let char_types: Vec<CharType> = word_chars
                .iter()
                .map(|c| CharType::new(*c).expect("CharType::new should not fail in tests"))
                .collect();
            Self {
                word_chars,
                char_types,
                skip_count: 0,
                state: EncoderState::new(english_indicator),
                result: Vec::new(),
                prev_word: String::new(),
                remaining_words: Vec::new(),
                roman_section_continues_from_previous_word: false,
            }
        }

        /// Builder: set the `prev_word` field that the borrowed `RuleContext` exposes.
        pub(crate) fn with_prev_word(mut self, prev_word: impl Into<String>) -> Self {
            self.prev_word = prev_word.into();
            self
        }

        /// Mark this print word as a continuation of an already active Roman
        /// section.
        pub(crate) fn with_roman_section_continuation(mut self) -> Self {
            self.roman_section_continues_from_previous_word = true;
            self
        }

        /// Builder: set the `remaining_words` field that the borrowed `RuleContext`
        /// exposes. Stores owned strings so the borrowed context can outlive call sites.
        pub(crate) fn with_remaining_words<I, S>(mut self, words: I) -> Self
        where
            I: IntoIterator<Item = S>,
            S: Into<String>,
        {
            self.remaining_words = words.into_iter().map(Into::into).collect();
            self
        }

        /// Borrow a `RuleContext` at the given index. The borrow is exclusive
        /// against `self`, so call this once per rule invocation.
        pub(crate) fn ctx_at<'a>(&'a mut self, index: usize) -> RuleContext<'a> {
            // Build a transient Vec<&str> view over the owned strings. The view's
            // lifetime is tied to `self` because each &str borrows from an entry
            // in `self.remaining_words`. We can't store the Vec<&str> in `self`
            // (self-referential), so we leak the indirection through the caller's
            // borrow: the returned RuleContext borrows it via the slice below.
            let remaining: Vec<&str> = self.remaining_words.iter().map(String::as_str).collect();
            // SAFETY: We need to give `RuleContext` a `&[&str]` whose lifetime
            // matches `self`. Leaking the Vec lets us produce that slice while
            // keeping the owned strings alive for the duration of `self`.
            let leaked: &'a [&'a str] = Box::leak(remaining.into_boxed_slice());
            RuleContext {
                word_chars: &self.word_chars,
                index,
                char_type: &self.char_types[index],
                prev_word: &self.prev_word,
                remaining_words: leaked,
                has_korean_char: self.word_chars.iter().any(|c| {
                    let cp = *c as u32;
                    (0xAC00..=0xD7A3).contains(&cp)
                }),
                is_all_uppercase: false,
                ascii_starts_at_beginning: false,
                roman_section_continues_from_previous_word: self
                    .roman_section_continues_from_previous_word,
                skip_count: &mut self.skip_count,
                state: &mut self.state,
                result: &mut self.result,
            }
        }
    }
}

pub use encoder::Encoder;

thread_local! {
    static ENCODER_CACHE: RefCell<Option<Encoder>> = const { RefCell::new(None) };
}

fn with_encoder<F, R>(english_indicator: bool, f: F) -> R
where
    F: FnOnce(&mut Encoder) -> R,
{
    ENCODER_CACHE.with(|cell| {
        let Ok(mut cached) = cell.try_borrow_mut() else {
            let mut encoder = Encoder::new(english_indicator);
            encoder.reset_state();
            return f(&mut encoder);
        };

        if !matches!(&*cached, Some(encoder) if encoder.english_indicator() == english_indicator) {
            *cached = Some(Encoder::new(english_indicator));
        }

        let encoder = cached.as_mut().expect("encoder cache just initialized");
        encoder.reset_state();
        f(encoder)
    })
}

/// Options for controlling encoding behavior.
/// Used when context cannot be derived from input text alone.
#[derive(Debug, Clone, Default)]
pub struct EncodeOptions {
    /// Override the default encoding mode (normally Korean).
    pub default_mode: Option<crate::rules::context::EncodingMode>,
}

/// A formatting span applied to the input text.
#[derive(Debug, Clone)]
pub struct FormattingSpan {
    /// Byte offset range in the input string (start..end)
    pub range: std::ops::Range<usize>,
    /// Type of formatting
    pub kind: FormattingKind,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FormattingKind {
    /// 드러냄표/밑줄 — wraps in ⠠⠤ ... ⠤⠄ (제56항)
    Emphasis,
    /// 굵은 글자 — wraps in ⠰⠤ ... ⠤⠆ (제56항)
    Bold,
    /// 제1점역자 정의 글자체 — wraps in ⠐⠤ ... ⠤⠂ (제56항 [붙임])
    Custom1,
    /// 제2점역자 정의 글자체 — wraps in ⠈⠤ ... ⠤⠁ (제56항 [붙임])
    Custom2,
}

impl FormattingKind {
    pub(crate) fn markers(self) -> ([u8; 2], [u8; 2]) {
        match self {
            Self::Emphasis => ([32, 36], [36, 4]),
            Self::Bold => ([48, 36], [36, 6]),
            Self::Custom1 => ([16, 36], [36, 2]),
            Self::Custom2 => ([8, 36], [36, 1]),
        }
    }
}

pub fn encode(text: &str) -> Result<Vec<u8>, String> {
    encode_with_options(text, &EncodeOptions::default())
}

/// PDF 수학 — Unicode Mathematical Alphanumeric Symbols(U+1D400–U+1D7FF)와
/// 첨자 라틴 문자를 ASCII 라틴 문자로 정규화한다.
/// 한국 점자 수학 규정은 글꼴 변형(italic/bold/script 등)을 별도 표기하지
/// 않으므로 `𝑃`(MATH ITALIC CAPITAL P) ≡ 일반 `P`로 취급한다.
fn normalize_math_alphanumeric_char(c: char) -> char {
    let cp = c as u32;
    // Mathematical Italic small h는 U+1D455 자리 비고 U+210E (Planck) 사용.
    if cp == 0x210E {
        return 'h';
    }
    const BLOCKS: &[(u32, char)] = &[
        (0x1D400, 'A'),
        (0x1D41A, 'a'),
        (0x1D434, 'A'),
        (0x1D44E, 'a'),
        (0x1D468, 'A'),
        (0x1D482, 'a'),
        (0x1D49C, 'A'),
        (0x1D4B6, 'a'),
        (0x1D4D0, 'A'),
        (0x1D4EA, 'a'),
        (0x1D504, 'A'),
        (0x1D51E, 'a'),
        (0x1D538, 'A'),
        (0x1D552, 'a'),
        (0x1D56C, 'A'),
        (0x1D586, 'a'),
        (0x1D5A0, 'A'),
        (0x1D5BA, 'a'),
        (0x1D5D4, 'A'),
        (0x1D5EE, 'a'),
        (0x1D608, 'A'),
        (0x1D622, 'a'),
        (0x1D63C, 'A'),
        (0x1D656, 'a'),
        (0x1D670, 'A'),
        (0x1D68A, 'a'),
    ];
    for &(start, base) in BLOCKS {
        if cp >= start && cp < start + 26 {
            return char::from(base as u8 + (cp - start) as u8);
        }
    }
    const DIGIT_BLOCKS: &[u32] = &[0x1D7CE, 0x1D7D8, 0x1D7E2, 0x1D7EC, 0x1D7F6];
    for &start in DIGIT_BLOCKS {
        if cp >= start && cp < start + 10 {
            return char::from(b'0' + (cp - start) as u8);
        }
    }
    c
}

fn may_normalize_math_alphanumeric(c: char) -> bool {
    let cp = c as u32;
    cp == 0x210E || (0x1D400..=0x1D7FF).contains(&cp)
}

fn normalize_math_alphanumeric_string(text: &str) -> Cow<'_, str> {
    if !text.chars().any(may_normalize_math_alphanumeric) {
        return Cow::Borrowed(text);
    }

    Cow::Owned(text.chars().map(normalize_math_alphanumeric_char).collect())
}

fn may_normalize_roman_numeral_presentation(c: char) -> bool {
    (0x2160..=0x217f).contains(&(c as u32))
}

fn may_normalize_parenthesized_hangul_presentation(c: char) -> bool {
    (0x3200..=0x321e).contains(&(c as u32))
}

fn may_normalize_word_separator_middle_dot(c: char) -> bool {
    c == '\u{2e31}'
}

fn pure_roman_compatibility_unit_decomposition(c: char) -> Option<Vec<char>> {
    use unicode_normalization::UnicodeNormalization;

    let parts =
        crate::rules::korean::rule_69::compatibility_unit_decomposition(c).or_else(|| {
            crate::rules::korean::rule_68::is_rule_68_symbol(c)
                .then(|| std::iter::once(c).nfkc().collect())
        })?;
    parts.iter().all(char::is_ascii_alphabetic).then_some(parts)
}

/// Korean Braille rule 36 transcribes a Roman numeral with its corresponding
/// Roman letters. Unicode U+2160–U+217F are presentation forms whose NFKC
/// decomposition is exactly that Roman-letter spelling (`Ⅱ` → `II`). Normalize
/// only this block; the existing rule-36 token logic remains responsible for
/// numeral validity, case indicators, context, and Roman termination.
fn normalize_roman_numeral_presentation<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    use unicode_normalization::UnicodeNormalization;

    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        if may_normalize_roman_numeral_presentation(ch) {
            out.extend(std::iter::once(ch).nfkc());
        } else {
            out.push(ch);
        }
    }
    Cow::Owned(out)
}

/// Unicode U+3200-U+321E are compatibility presentation forms whose visible
/// content is ordinary Hangul enclosed by literal parentheses (`㈜` -> `(주)`,
/// `㈔` -> `(사)`). The Korean braille standard already defines both the
/// enclosed Hangul and the parentheses; expanding the presentation form lets
/// those existing rules own the transcription without assigning a new braille
/// symbol to each Unicode glyph.
fn normalize_parenthesized_hangul_presentation<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    use unicode_normalization::UnicodeNormalization;

    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        if may_normalize_parenthesized_hangul_presentation(ch) {
            out.extend(std::iter::once(ch).nfkc());
        } else {
            out.push(ch);
        }
    }
    Cow::Owned(out)
}

/// U+2E31 WORD SEPARATOR MIDDLE DOT is a visible presentation of a word
/// boundary, not U+00B7 MIDDLE DOT punctuation. Preserve that semantic
/// distinction by expanding it to one ordinary print space before tokenization;
/// the existing Korean spacing rules then emit one blank braille cell.
fn normalize_word_separator_middle_dot<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        if may_normalize_word_separator_middle_dot(ch) {
            out.push(' ');
        } else {
            out.push(ch);
        }
    }
    Cow::Owned(out)
}

/// Korean Braille rule 69 assigns Unicode compatibility unit glyphs the
/// transcription of their semantic Roman spelling.  When such a glyph is
/// immediately combined with ordinary Roman letters (`㎾h` -> `kWh`) or with
/// another unit component (`W/㎏` -> `W/kg`), encoding it as a self-contained
/// symbol would incorrectly close and reopen the Roman section at the Unicode
/// code-point boundary.
///
/// Expand only unit glyphs whose complete NFKC decomposition consists of Roman
/// letters *and* which are joined to another Roman unit component. Standalone
/// compatibility units retain their dedicated rule-68/69 encoding.
/// Compatibility forms containing a slash or an exponent (`㎧`, `㎥`) and
/// non-unit compatibility characters remain untouched.
fn normalize_pure_roman_compatibility_units<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    let chars = text.chars().collect::<Vec<_>>();
    let mut out = String::with_capacity(text.len());
    for (index, ch) in chars.iter().copied().enumerate() {
        let is_roman_unit_component = |candidate: char| {
            candidate.is_ascii_alphabetic()
                || candidate == 'μ'
                || pure_roman_compatibility_unit_decomposition(candidate).is_some()
        };
        let directly_joined = index
            .checked_sub(1)
            .and_then(|previous| chars.get(previous))
            .is_some_and(|previous| is_roman_unit_component(*previous))
            || chars
                .get(index + 1)
                .is_some_and(|next| is_roman_unit_component(*next));
        let joined_through_slash = (index >= 2
            && matches!(chars[index - 1], '/' | '\u{2044}' | '\u{2215}')
            && is_roman_unit_component(chars[index - 2]))
            || (index + 2 < chars.len()
                && matches!(chars[index + 1], '/' | '\u{2044}' | '\u{2215}')
                && is_roman_unit_component(chars[index + 2]));

        if (directly_joined || joined_through_slash)
            && let Some(parts) = pure_roman_compatibility_unit_decomposition(ch)
        {
            out.extend(parts);
        } else {
            out.push(ch);
        }
    }
    Cow::Owned(out)
}

/// Print variants of characters the standard already defines. U+02DA RING ABOVE
/// is typed for the degree sign (제69항 [붙임 2] `°`); U+2010/U+2011/U+2043 are
/// Unicode hyphen forms of the 붙임표 `-` (제72항 lists the same cell for the
/// hyphen bullet); `°C`/`°F` are the decomposed spellings of the unit glyphs
/// `℃`/`℉` (제69항 [붙임 2]). U+00AD SOFT HYPHEN is an invisible line-break
/// hint and carries no print, so it is dropped.
///
/// The same holds for the compatibility spellings of characters the standard
/// already defines: U+FF01–U+FF5E are the fullwidth forms of ASCII `!`–`~`
/// (`％`, `ｍ`, `＆`), U+30FB/U+FF65/U+2027 are CJK spellings of the 가운뎃점 `·`
/// (제50항), U+301C is the wave-dash form of the 물결표 `~` (제49항), and U+00B4
/// is a typed acute accent standing for the 아포스트로피 `'` (제61항). The
/// zero-width marks U+200B–U+200D and U+FEFF carry no print at all, so they are
/// dropped like the soft hyphen.
///
/// U+FF1A `：` and U+FF03 `＃` are excluded: the standard gives those fullwidth
/// glyphs their own meanings — the 옛한글 장음 표시 of 제27항 and the 기수 기호 of
/// 수학 제65항 — so they are not print variants of ASCII `:` and `#`.
fn is_foldable_fullwidth(c: char) -> bool {
    matches!(c, '\u{FF01}'..='\u{FF5E}') && !matches!(c, '\u{FF03}' | '\u{FF1A}')
}

/// U+2474–U+2487 은 괄호 안에 숫자를 넣은 표기(`⑸`)의 한 글자 표기이므로 제34항의
/// 괄호와 제40항의 수표로 풀어 적는다. 제64항의 동그라미 숫자(`①`)는 규정이 따로
/// 점형을 정하므로 여기서 건드리지 않는다.
fn parenthesized_number_expansion(c: char) -> Option<String> {
    let value = (c as u32).checked_sub(0x2473)?;
    (1..=20).contains(&value).then(|| format!("({value})"))
}

fn may_normalize_print_variant(c: char) -> bool {
    matches!(
        c,
        '\u{02DA}' | '\u{2010}' | '\u{2011}' | '\u{2043}' | '\u{00AD}' | '\u{00B0}' | '²' | '³'
    ) || is_foldable_fullwidth(c)
        || parenthesized_number_expansion(c).is_some()
        || matches!(
            c,
            '\u{30FB}'
                | '\u{FF65}'
                | '\u{2027}'
                | '\u{2024}'
                | '\u{2A2F}'
                | '\u{301C}'
                | '\u{00B4}'
                | '\u{200B}'
                | '\u{200C}'
                | '\u{200D}'
                | '\u{FEFF}'
        )
}

/// The CJK compatibility square unit whose NFKC decomposition is exactly
/// `letters` + `exponent` (`km` + `2` → `㎢`), so a printed `km²` takes the
/// 제68항/제69항 transcription of that unit glyph.
fn square_unit_presentation(letters: &[char], exponent: char) -> Option<char> {
    use unicode_normalization::UnicodeNormalization;

    let spelled: String = letters.iter().chain(std::iter::once(&exponent)).collect();
    (0x3371..=0x33DF)
        .filter_map(char::from_u32)
        .find(|candidate| std::iter::once(*candidate).nfkc().eq(spelled.chars()))
}

/// 제69항 [붙임 2] 의 `℃`/`℉` 는 도 기호와 글자를 이어 쓴 `°C`/`°F` 로도 입력된다.
/// U+02DA RING ABOVE 는 도 기호의 활자체 표기다.
fn degree_unit_glyph(ch: char, next: Option<char>) -> Option<char> {
    if !matches!(ch, '\u{00B0}' | '\u{02DA}') {
        return None;
    }
    match next {
        Some('C') => Some('\u{2103}'),
        Some('F') => Some('\u{2109}'),
        _ => None,
    }
}
fn normalize_print_variants<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    let chars = text.chars().collect::<Vec<_>>();
    let mut out = String::with_capacity(text.len());
    let mut index = 0usize;
    while index < chars.len() {
        let ch = chars[index];
        if let Some(glyph) = degree_unit_glyph(ch, chars.get(index + 1).copied()) {
            out.push(glyph);
            index += 2;
            continue;
        }
        let starts_letter_run = ch.is_ascii_alphabetic()
            && index
                .checked_sub(1)
                .is_none_or(|previous| !chars[previous].is_ascii_alphabetic());
        if starts_letter_run {
            let run_end = index
                + chars[index..]
                    .iter()
                    .take_while(|c| c.is_ascii_alphabetic())
                    .count();
            let exponent = match chars.get(run_end) {
                Some('²') => Some('2'),
                Some('³') => Some('3'),
                _ => None,
            };
            if let Some(exponent) = exponent
                && let Some(unit) = square_unit_presentation(&chars[index..run_end], exponent)
            {
                out.push(unit);
                index = run_end + 1;
                continue;
            }
        }
        match ch {
            '\u{02DA}' => out.push('\u{00B0}'),
            '\u{2010}' | '\u{2011}' | '\u{2043}' => out.push('-'),
            '\u{30FB}' | '\u{FF65}' | '\u{2027}' | '\u{2024}' => {
                out.push('\u{00B7}');
            }
            '\u{2A2F}' => out.push('\u{00D7}'),
            _ if parenthesized_number_expansion(ch).is_some() => {
                out.push_str(&parenthesized_number_expansion(ch).unwrap_or_default());
            }
            '\u{301C}' => out.push('~'),
            '\u{00B4}' => out.push('\''),
            '\u{00AD}' | '\u{200B}' | '\u{200C}' | '\u{200D}' | '\u{FEFF}' => {}
            _ if is_foldable_fullwidth(ch) => {
                out.push(char::from_u32(ch as u32 - 0xFEE0).unwrap_or(ch));
            }
            _ => out.push(ch),
        }
        index += 1;
    }
    Cow::Owned(out)
}

/// 국어 문장 안의 한자는 그 한자의 한국어 독음으로 적으므로(`支線` → 지선), 점역
/// 전에 독음으로 바꾼다. 표에 없는 한자는 그대로 두어 뒤 단계가 오류를 보고한다.
///
/// 제19~27항의 옛한글은 한자를 독음으로 바꾸지 않고 옛한글 점형으로 적으므로
/// (`轉輪륜王` → `⠊⠸⠩⠱⠒…`) 그 문맥은 건너뛴다. 옛한글임을 알리는 표시는 홀로 쓴
/// 자모(`洪ㄱ字`), 방점(`·갈`, `中國·귁`), 한자 뒤에 곧바로 붙인 독음(`君군`,
/// `轉輪륜王`의 `輪륜`), 그리고 한글이 하나도 없는 한자만의 표기(`榮養`)다.
fn is_middle_korean_hanja_context(chars: &[char]) -> bool {
    let has_old_jamo = chars.iter().any(|c| {
        matches!(*c, '\u{3131}'..='\u{318E}' | '\u{1100}'..='\u{11FF}' | '\u{E000}'..='\u{F8FF}')
    });
    let has_tone_mark = chars.iter().any(|c| matches!(*c, '\u{00B7}' | '\u{FF1A}'));
    let has_modern_hangul = chars.iter().any(|c| matches!(*c, '\u{AC00}'..='\u{D7A3}'));
    let has_gloss = chars.iter().enumerate().any(|(index, c)| {
        hanja::reading(*c).is_some_and(|reading| {
            chars[index + 1..]
                .iter()
                .take(reading.chars().count())
                .copied()
                .eq(reading.chars())
        })
    });
    has_old_jamo || has_tone_mark || has_gloss || !has_modern_hangul
}

fn expand_hanja_readings<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    let chars: Vec<char> = text.chars().collect();
    if is_middle_korean_hanja_context(&chars) {
        return text;
    }
    let mut out = String::with_capacity(text.len());
    for ch in chars {
        match hanja::reading(ch) {
            Some(reading) => out.push_str(reading),
            None => out.push(ch),
        }
    }
    Cow::Owned(out)
}

/// Pictographs that the NIKL reference corpus transcribes by their printed
/// meaning rather than by a symbol cell: the telephone sign is written as the
/// Roman word `Tel` before the number (`☏051-514-9901` → `⠴⠠⠞⠑⠇⠼⠚⠑⠁…`).
fn may_expand_pictograph(c: char) -> bool {
    matches!(c, '\u{260E}' | '\u{260F}')
}

fn expand_pictographs<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        if may_expand_pictograph(ch) {
            out.push_str("Tel");
        } else {
            out.push(ch);
        }
    }
    Cow::Owned(out)
}

/// Default-route whole expressions that contain math-only relational/grouping
/// glyphs which cannot be encoded correctly one space-separated token at a time.
///
/// This is intentionally narrower than [`rules::english_ueb::is_math_owned`]:
/// Korean unit/symbol testcases contain standalone `′`, `″`, `|`, and script
/// forms (`A⁺⁺`, `B₆`) that the legacy token pipeline already owns. Whole-route
/// only when a glyph is attached to surrounding math operands.
fn default_math_expression_needs_whole_route(text: &str) -> bool {
    let chars: Vec<char> = text.chars().collect();
    if chars.len() < 2 {
        return false;
    }

    // "Attached to surrounding math operands": the expression must carry at
    // least one alphanumeric operand (`△ABC`, `p → q`, `x□y=…`). A glyph-only
    // sequence such as `□□□` is the 한글 제58항 빠짐표 (or 제72항 글머리표)
    // usage, not a math expression, and stays on the character pipeline.
    let has_operand = chars.iter().any(|c| c.is_ascii_alphanumeric());
    has_operand
        && chars.iter().enumerate().any(|(i, c)| match *c {
            // 수학 제32·33항의 합동/기하 연산 기호도 양쪽 변수를 포함한
            // 하나의 수식이다. 공백 단위 token 경로로 나누면 뒤쪽 대문자
            // 변수가 국어 제29항의 로마자 연속으로 오인될 수 있다.
            '→' | '←' | '↗' | '↘' | '↑' | '↓' | '△' | '□' | '≅' | '▷' | '◁' => {
                true
            }
            // 수학 제34/37항 hat/bar 결합부호는 단일 문자 operand에 붙는다
            // (`x̂`, `x̄`, `p̂`, `2̄.3010`). NFD 분해된 악센트 단어(`maître` →
            // `mai`+◌̂+`tre`)처럼 결합부호가 3글자 이상 단어 내부에 있으면
            // 영어/외국어 산문이므로 수학 신호로 세지 않는다.
            '\u{0304}' | '\u{0302}' => combining_mark_on_single_letter(&chars, i),
            _ => false,
        })
}

/// Whether the combining mark at `chars[i]` decorates a lone operand letter
/// (math usage) rather than sitting inside a multi-letter word (accented prose).
/// Other combining marks are transparent when measuring the letter run.
fn combining_mark_on_single_letter(chars: &[char], i: usize) -> bool {
    let is_combining = |c: char| ('\u{0300}'..='\u{036F}').contains(&c);
    let mut letters = 0usize;
    let mut j = i;
    while j > 0 {
        let c = chars[j - 1];
        if c.is_alphabetic() {
            letters += 1;
        } else if !is_combining(c) {
            break;
        }
        j -= 1;
    }
    let mut j = i + 1;
    while j < chars.len() {
        let c = chars[j];
        if c.is_alphabetic() {
            letters += 1;
        } else if !is_combining(c) {
            break;
        }
        j += 1;
    }
    letters < 3
}

#[derive(Clone, Copy, Default)]
struct NormalizationTriggers {
    has_math_alphanumeric: bool,
    has_roman_numeral_presentation: bool,
    has_parenthesized_hangul_presentation: bool,
    has_word_separator_middle_dot: bool,
    has_pure_roman_compatibility_unit: bool,
    has_print_variant: bool,
    has_hanja: bool,
    has_pictograph: bool,
    has_decomposable_latin: bool,
    has_negation_combiner: bool,
    has_vector_mark: bool,
    has_formatting_mark_or_sentinel: bool,
    has_ipa_group_start: bool,
    has_ipa_symbol: bool,
}

impl NormalizationTriggers {
    fn scan(text: &str) -> Self {
        let mut triggers = Self::default();
        for c in text.chars() {
            triggers.has_math_alphanumeric |= may_normalize_math_alphanumeric(c);
            triggers.has_roman_numeral_presentation |= may_normalize_roman_numeral_presentation(c);
            triggers.has_parenthesized_hangul_presentation |=
                may_normalize_parenthesized_hangul_presentation(c);
            triggers.has_word_separator_middle_dot |= may_normalize_word_separator_middle_dot(c);
            triggers.has_pure_roman_compatibility_unit |=
                pure_roman_compatibility_unit_decomposition(c).is_some();
            triggers.has_print_variant |= may_normalize_print_variant(c);
            triggers.has_hanja |= hanja::is_hanja(c);
            triggers.has_pictograph |= may_expand_pictograph(c);
            triggers.has_decomposable_latin |= may_decompose_accented_latin(c);
            triggers.has_negation_combiner |= c == '\u{0338}';
            triggers.has_vector_mark |= is_vector_mark(c);
            triggers.has_formatting_mark_or_sentinel |=
                is_formatting_mark(c) || is_formatting_sentinel(c);
            triggers.has_ipa_group_start |= matches!(c, '[' | '/');
            triggers.has_ipa_symbol |= is_ipa_phonetic_symbol(c);
        }
        triggers
    }

    fn may_need_emphasis_expansion(self) -> bool {
        // NFD decomposition can introduce formatting combining marks (for example U+0307).
        self.has_formatting_mark_or_sentinel || self.has_decomposable_latin
    }

    fn may_contain_ipa_context(self) -> bool {
        self.has_ipa_group_start && self.has_ipa_symbol
    }
}

/// PDF 수학 제34항 — 부정 결합 부호(U+0338 COMBINING LONG SOLIDUS OVERLAY)는
/// 점역 시 피수정 문자 앞으로 이동한다. 예: `ℛ̸` → `̸ℛ` → 점자 `⠨⠠⠗`.
fn move_negation_combiner_before_base<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    if !text.as_ref().contains('\u{0338}') {
        return text;
    }

    let source = text.as_ref();
    let chars: Vec<char> = source.chars().collect();
    let mut out = String::with_capacity(source.len());
    let mut i = 0;
    while i < chars.len() {
        if i + 1 < chars.len() && chars[i + 1] == '\u{0338}' {
            out.push(chars[i + 1]);
            out.push(chars[i]);
            i += 2;
        } else {
            out.push(chars[i]);
            i += 1;
        }
    }
    Cow::Owned(out)
}

/// PDF 한글 제56항 — 결합 부호 기반 글자체 표지 처리.
///
/// 강조 대상 문자마다 결합 부호를 부착하는 **순환소수 스타일** 평문 표기를 지원한다.
/// 결합 부호는 `FormattingKind`와 1:1 매핑되며, PUA sentinel(U+E000~U+E007)로
/// 변환되어 후속 단계에서 점자 marker로 전개된다. 인접한 같은 종류 wrap은
/// [`merge_adjacent_formatting_wraps`]에 의해 자동으로 하나로 병합된다.
///
/// | 결합 부호 | 외관 | FormattingKind | 점자 |
/// |---|---|---|---|
/// | U+0307 (DOT ABOVE) | ̇ | 드러냄표/밑줄 (Emphasis) | ⠠⠤...⠤⠄ |
/// | U+0331 (MACRON BELOW) | ̱ | 굵은 글자 (Bold) | ⠰⠤...⠤⠆ |
/// | U+0332 (LOW LINE) | ̲ | 점역자1 글자체 (Custom1) | ⠐⠤...⠤⠂ |
/// | U+0333 (DOUBLE LOW LINE) | ̳ | 점역자2 글자체 (Custom2) | ⠈⠤...⠤⠁ |
///
/// 사용 규칙:
/// - **단위:** 각 결합 부호는 직전 1개의 비공백 문자를 글자체로 감싼다.
///   (per-char 컨벤션. 인접한 같은 종류 wrap은 자동 병합되어 연속 강조 단어를
///   `⠠⠤단어1 단어2⠤⠄` 형태의 단일 wrap으로 emit한다.)
/// - **N개 trailing 호환:** 단일 음절 뒤에 같은 결합 부호 N개를 연속(공백 허용)으로
///   붙이면 직전 N개 비공백 문자를 한 묶음으로 감싼다 (legacy 표기 호환).
/// - **숫자 흡수:** 한글 음절 직전에 결합된 숫자/`,`/`.` 연쇄는 같은 wrap에 자동
///   포함된다. (예: `15,000원̳` → `⠈⠤15,000원⠤⠁`. 한글 토큰의 일부로 본다.)
/// - **수학 컨텍스트 자동 회피:** 현재 토큰(공백으로 구분된 비공백 연쇄)에 한글
///   음절이 없으면 결합 부호의 본래 결합 의미(반복소수 ̇, 수학 변수 underline ̲)를
///   보존하기 위해 변환하지 않는다.
fn expand_emphasis_marks<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    /// (결합 부호, 시작 sentinel, 종료 sentinel).
    /// PUA U+E000~U+E007이 symbol_shortcut에서 점자 marker로 매핑된다.
    const FORMATTING_MARKS: &[(char, char, char)] = &[
        ('\u{0307}', '\u{E000}', '\u{E001}'), // 드러냄표/밑줄
        ('\u{0331}', '\u{E002}', '\u{E003}'), // 굵은 글자
        ('\u{0332}', '\u{E004}', '\u{E005}'), // 점역자1
        ('\u{0333}', '\u{E006}', '\u{E007}'), // 점역자2
    ];

    if !text
        .as_ref()
        .chars()
        .any(|c| is_formatting_sentinel(c) || is_formatting_mark(c))
    {
        return text;
    }

    let source = text.as_ref();
    let chars: Vec<char> = source.chars().collect();

    // Pre-scan: 각 char 위치의 토큰(공백으로 구분된 비공백 연쇄)에 한글이 있는지 표시.
    // 토큰에 한글이 없으면 결합 부호의 본래 결합 의미를 보존한다 (수학/영어 컨텍스트).
    let mut token_has_korean = vec![false; chars.len()];
    {
        let mut i = 0;
        while i < chars.len() {
            if chars[i] == ' ' {
                i += 1;
                continue;
            }
            let start = i;
            while i < chars.len() && chars[i] != ' ' {
                i += 1;
            }
            let has = chars[start..i].iter().any(|c| utils::is_korean_char(*c));
            for slot in token_has_korean.iter_mut().take(i).skip(start) {
                *slot = has;
            }
        }
    }

    let mut out: Vec<char> = Vec::with_capacity(chars.len());
    let mut i = 0;
    while i < chars.len() {
        let mark_entry = FORMATTING_MARKS
            .iter()
            .find(|(mark, _, _)| *mark == chars[i]);
        let Some(&(mark_char, start_sentinel, end_sentinel)) = mark_entry else {
            out.push(chars[i]);
            i += 1;
            continue;
        };

        // 토큰에 한글이 없으면 결합 부호 그대로 보존 (수학/영어 컨텍스트).
        if !token_has_korean[i] {
            out.push(chars[i]);
            i += 1;
            continue;
        }

        // 같은 결합 부호 그룹 수집 (사이 공백 허용).
        // legacy `돼지̇ ̇ ̇ ̇ ̇` 표기 호환: 첫 마크의 직전 토큰을 기준으로 N개 묶음 wrap.
        let mut count = 1;
        let mut last = i;
        let mut j = i + 1;
        while j < chars.len() {
            if chars[j] == mark_char {
                count += 1;
                last = j;
                j += 1;
            } else if chars[j] == ' ' && j + 1 < chars.len() && chars[j + 1] == mark_char {
                j += 1;
            } else {
                break;
            }
        }

        // out에서 N개의 비공백 문자(content unit)를 walk back. 공백/이미 삽입된
        // sentinel은 건너뛴다. 한글 음절뿐 아니라 숫자/구두점도 1 unit으로 센다.
        let mut units = 0;
        let mut start_in_out = out.len();
        while start_in_out > 0 && units < count {
            let c = out[start_in_out - 1];
            if c == ' ' || is_formatting_sentinel(c) {
                start_in_out -= 1;
            } else {
                units += 1;
                start_in_out -= 1;
            }
        }
        if units == count {
            // 한글 음절 직전 숫자/`,`/`.` 연쇄는 같은 wrap에 흡수 (per-token 단위 강조).
            while start_in_out > 0 {
                let c = out[start_in_out - 1];
                if c.is_ascii_digit() || matches!(c, ',' | '.') {
                    start_in_out -= 1;
                } else {
                    break;
                }
            }
            out.insert(start_in_out, start_sentinel);
            out.push(end_sentinel);
        } else {
            // 유닛 수가 부족하면 결합 부호를 그대로 보존한다.
            for _ in 0..count {
                out.push(mark_char);
            }
        }
        // 결합 부호 그룹 모두 skip
        i = last + 1;
    }
    merge_adjacent_formatting_wraps(Cow::Owned(out.into_iter().collect()))
}

/// 포매팅 sentinel(U+E000~U+E007) 여부.
fn is_formatting_sentinel(c: char) -> bool {
    matches!(c as u32, 0xE000..=0xE007)
}

fn is_formatting_mark(c: char) -> bool {
    matches!(c, '\u{0307}' | '\u{0331}' | '\u{0332}' | '\u{0333}')
}

/// 인접한 같은 종류 글자체 wrap을 하나로 병합한다.
///
/// PDF 제56항 — 사용자가 강조 대상을 단어별로 표시(`왜̇ 사느냐̇̇̇`)하면 각 단어가
/// 독립 wrap으로 인코딩되어 `⠠⠤왜⠤⠄ ⠠⠤사느냐⠤⠄`처럼 분리된다. 그러나 PDF는
/// 인접한 강조 단어를 하나의 wrap `⠠⠤왜 사느냐⠤⠄`로 묶는다. 이 함수는 같은
/// 종류 sentinel 쌍 사이의 공백만 포함된 구간을 감지하여 inner sentinel을 제거한다.
fn merge_adjacent_formatting_wraps<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    /// (시작 sentinel, 종료 sentinel) — `FORMATTING_MARKS`와 1:1 대응.
    const SENTINEL_PAIRS: &[(char, char)] = &[
        ('\u{E000}', '\u{E001}'),
        ('\u{E002}', '\u{E003}'),
        ('\u{E004}', '\u{E005}'),
        ('\u{E006}', '\u{E007}'),
    ];

    if !text.as_ref().chars().any(is_formatting_sentinel) {
        return text;
    }

    let mut chars: Vec<char> = text.as_ref().chars().collect();
    // 단순 반복: 한 번 병합이 일어나면 위치가 바뀌므로 다시 처음부터 스캔.
    let mut any_changed = false;
    let mut changed = true;
    while changed {
        changed = false;
        for &(open, close) in SENTINEL_PAIRS {
            let mut i = 0;
            while i < chars.len() {
                if chars[i] != close {
                    i += 1;
                    continue;
                }
                // `close` 직후가 공백 0개 이상 + 같은 종류 `open`이면 병합.
                let mut j = i + 1;
                while j < chars.len() && chars[j] == ' ' {
                    j += 1;
                }
                if j < chars.len() && chars[j] == open {
                    // close와 open을 제거. 공백은 보존.
                    chars.remove(j);
                    chars.remove(i);
                    changed = true;
                    any_changed = true;
                    // i는 그대로 둔다. 다음 close 찾기 시도.
                } else {
                    i += 1;
                }
            }
        }
    }
    if any_changed {
        Cow::Owned(chars.into_iter().collect())
    } else {
        text
    }
}

fn is_vector_mark(c: char) -> bool {
    matches!(c, '\u{20D6}' | '\u{20D7}' | '\u{20E1}' | '\u{20D1}')
}

/// PDF 수학 제37,38항 — 벡터/반직선/직선 결합 부호 처리.
/// 연속된 영문 대문자에 U+20D7(→), U+20D6(←), U+20E1(↔), U+20D1(반직선) 등의
/// 결합 부호가 각각 붙어 있으면, 결합부호를 한 번만 prefix하고 본문은 연쇄로 본다.
/// 예: `A⃗B⃗` → `⃗AB` → 점자 `⠒⠕⠠⠠⠁⠃`.
fn collapse_repeated_vector_marks<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    // Caller (line 483) guards with `normalization_triggers.has_vector_mark`, so
    // this function only runs when text contains at least one vector mark. The
    // defensive guard is preserved for safety but is structurally unreachable
    // under current call patterns.
    debug_assert!(text.as_ref().chars().any(is_vector_mark));

    let source = text.as_ref();
    let chars: Vec<char> = source.chars().collect();
    let mut out = String::with_capacity(source.len());
    let mut i = 0;
    let mut changed = false;
    while i < chars.len() {
        // PDF 제37,38항 — 벡터/반직선 결합부호는 점자에서 letter 앞에 prefix한다.
        // 단독 `A⃗`도 `⃗A` 순으로 변환한다.
        if chars[i].is_ascii_alphabetic() && i + 1 < chars.len() && is_vector_mark(chars[i + 1]) {
            changed = true;
            let mark = chars[i + 1];
            // 연속된 letter+mark 쌍을 수집한다 (예: A⃗B⃗ → ⃗AB).
            let mut letters = vec![chars[i]];
            let mut j = i + 2;
            while j + 1 < chars.len() && chars[j].is_ascii_alphabetic() && chars[j + 1] == mark {
                letters.push(chars[j]);
                j += 2;
            }
            // 결합부호를 한 번만 prefix하고 letter 연쇄를 그대로 emit
            out.push(mark);
            for l in letters {
                out.push(l);
            }
            i = j;
            continue;
        }
        out.push(chars[i]);
        i += 1;
    }
    if changed { Cow::Owned(out) } else { text }
}

fn may_decompose_accented_latin(c: char) -> bool {
    let cp = c as u32;
    // Å, å는 단위(옹스트롬)/고유 문자로 단독 의미를 가지므로 NFD 분해하지 않는다.
    !matches!(c, '\u{00C5}' | '\u{00E5}')
        && ((0x00C0..=0x024F).contains(&cp) || (0x1E00..=0x1EFF).contains(&cp))
}

/// PDF 수학 제65항 5 — 라틴 문자 + 결합 부호(악센트)는 base letter + 결합 부호로
/// NFD 분해한다. (예: `ã` → `a` + `\u{0303}`, `ä` → `a` + `\u{0308}`)
/// 한글/CJK 문자는 분해되지 않도록 라틴 확장 범위에만 적용한다.
///
/// Caller (`encode_with_options`) guards this with `has_decomposable_latin`, so
/// the inner re-check is omitted — it would be a structurally unreachable
/// defensive branch that tarpaulin can never cover.
fn decompose_accented_latin<'a>(text: Cow<'a, str>) -> Cow<'a, str> {
    use unicode_normalization::UnicodeNormalization;

    let mut out = String::new();
    for c in text.as_ref().chars() {
        // Latin-1 Supplement, Latin Extended-A/B/Additional, IPA Extensions
        if may_decompose_accented_latin(c) {
            for d in std::iter::once(c).nfd() {
                out.push(d);
            }
        } else {
            out.push(c);
        }
    }
    Cow::Owned(out)
}

/// 제37항 — 입력이 (공백을 제외하고) 전부 ASCII 로마자(알파벳)로만 이루어진
/// "고립된 로마자 구간"인지 판별한다. 이런 입력은 국어 점자 문맥(context:korean)에서
/// 로마자표 ⠴ … 종료표 ⠲로 감싼다. `%p`(제69항 단위표)처럼 비알파벳 기호가 섞인
/// 입력은 로마자 구간이 아니므로 제외된다.
fn is_isolated_roman_section(text: &str) -> bool {
    let mut has_letter = false;
    for ch in text.chars() {
        if ch == ' ' {
            continue;
        }
        if ch.is_ascii_alphabetic() {
            has_letter = true;
        } else {
            return false;
        }
    }
    has_letter
}

/// Encode text to braille with explicit options.
pub fn encode_with_options(text: &str, options: &EncodeOptions) -> Result<Vec<u8>, String> {
    use crate::rules::context::EncodingMode;

    // PDF 수학 — Mathematical Alphanumeric 변형(italic/bold/script 등)을 ASCII로
    // 정규화. 한국 점자 수학 규정은 글꼴 변형을 별도 표기하지 않으므로
    // `𝑃`(MATH ITALIC CAPITAL P)는 일반 `P`와 동일하게 처리한다.
    // 또한 PDF 수학 제65항 5의 결합 부호 처리를 위해 악센트 라틴 문자를 NFD 분해한다.
    // 그리고 PDF 수학 제34항 부정 결합(U+0338)을 피수정 문자 앞으로 이동한다.
    // 또한 PDF 수학 제37,38항 벡터/반직선 결합부호를 prefix 형태로 정규화한다.
    // PDF 제56항 — U+0307 결합 강조점을 sentinel U+E000/U+E001로 변환하여
    // N개 한글 음절을 cross-word 묶음으로 wrap. sentinel은 symbol_shortcut에서
    // braille marker (⠠⠤/⠤⠄)로 emit된다.
    let normalization_triggers = NormalizationTriggers::scan(text);
    // Content-routed English must be considered before math normalization. The
    // legacy math path decomposes accented Latin for Korean math 제65항, which turns
    // UEB §4.2 modified letters (`Rhône`, `Hwǣr`) into combining-mark sequences and
    // can make ordinary English prose look math-owned. A default-mode, non-Korean,
    // UEB-eligible input that is not math-owned in its original spelling is routed
    // through the UEB engine here; ambiguous letterless/single-accent inputs remain
    // with the legacy Korean/math defaults because `is_ueb_eligible` rejects them.
    if options.default_mode.is_none()
        && !text.chars().any(crate::utils::is_korean_char)
        && crate::rules::english_ueb::is_ueb_eligible(text)
        && !crate::rules::english_ueb::is_math_owned(text)
        && let Some(bytes) = crate::rules::english_ueb::try_encode(text)
    {
        return Ok(bytes);
    }
    // `EncodingMode::English` forces the UEB engine even for a letterless numeric or
    // symbol fragment (`4:30`→`⠼⠙⠒⠼⠉⠚`), where content-based routing would otherwise
    // treat it as a Korean-context number (colon `⠐⠂`). A bare `N:M`/`N(x)` is
    // ambiguous from input alone, so the testcase declares its language via `context`.
    if matches!(options.default_mode, Some(EncodingMode::English))
        && let Some(bytes) = crate::rules::english_ueb::encode_forced(text)
    {
        return Ok(bytes);
    }
    let normalized_text = if normalization_triggers.has_math_alphanumeric {
        normalize_math_alphanumeric_string(text)
    } else {
        Cow::Borrowed(text)
    };
    let normalized_text = if normalization_triggers.has_roman_numeral_presentation {
        normalize_roman_numeral_presentation(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_parenthesized_hangul_presentation {
        normalize_parenthesized_hangul_presentation(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_word_separator_middle_dot {
        normalize_word_separator_middle_dot(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_pure_roman_compatibility_unit {
        normalize_pure_roman_compatibility_units(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_print_variant {
        normalize_print_variants(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_hanja {
        expand_hanja_readings(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_pictograph {
        expand_pictographs(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_decomposable_latin {
        decompose_accented_latin(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_negation_combiner {
        move_negation_combiner_before_base(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.has_vector_mark {
        collapse_repeated_vector_marks(normalized_text)
    } else {
        normalized_text
    };
    let normalized_text = if normalization_triggers.may_need_emphasis_expansion() {
        expand_emphasis_marks(normalized_text)
    } else {
        normalized_text
    };

    let text: &str = normalized_text.as_ref();

    // PDF 제12항 붙임 1 — 입력에 `행렬` 키워드가 있으면 행렬명 컨텍스트 활성화.
    // 활성화 시 연속된 2개 대문자는 행렬명(각 글자에 ⠠ 개별 부착)으로 점역된다.
    // 이 컨텍스트는 thread-local이 아니라 현재 encoder/math engine state에 주입된다.
    let matrix_context = text.contains("행렬");
    let math_mode = matches!(options.default_mode, Some(EncodingMode::Math));
    let math_context = crate::rules::math::math_token_rule::MathContext {
        matrix_context_active: matrix_context,
        math_mode_active: math_mode,
    };

    // PDF 제38항 — IPA 모드: 발음 기호 표기.
    // 알고리즘 일반화: 입력은 묶음 기호 `[...]` 또는 `/.../`로 시작/종료한다.
    //   대괄호: 여는 `[` → ⠐⠘⠷ (16,24,55), 닫는 `]` → ⠘⠾ (24,62)
    //   빗금:   여는 `/` → ⠐⠘⠌ (16,24,12), 닫는 `/` → ⠘⠌ (24,12)
    // 묶음 사이의 알파벳은 영자(영어) 점자 그대로, 음운 기호는 국제음성기호
    // 점자 변환표(PDF 제38항)에 따른 단일/이중 셀로 매핑한다.
    //
    // IPA 컨텍스트는 explicit mode 명시(`Ipa`) 또는 input의 AST 분석(묶음 안
    // 음운 기호 존재)으로 자동 감지된다. 자동 감지가 가능한 입력은 testcase에
    // 별도 context 명시가 필요 없다.
    let ipa_auto = options.default_mode.is_none()
        && normalization_triggers.may_contain_ipa_context()
        && detect_ipa_context(text);
    if ipa_auto || matches!(options.default_mode, Some(EncodingMode::Ipa)) {
        return encode_ipa(text);
    }

    // PDF 제49항 [37] — ObjectSymbol 모드: 사물부호 ○ × △ □.
    // 알고리즘: ⠸(56) + 도형별 점형 + ⠇(7) 마무리.
    // 제72항의 글머리 기호와 동일 문자이지만, 사물부호로 쓰일 때만 ⠇ 마무리를 붙인다.
    if let Some(EncodingMode::ObjectSymbol) = options.default_mode {
        let chars: Vec<char> = text.chars().collect();
        if chars.len() == 1 {
            let mark = match chars[0] {
                '○' => Some(52u8), // ⠴
                '×' => Some(45u8), // ⠭
                '△' => Some(44u8), // ⠬
                '□' => Some(54u8), // ⠶
                _ => None,
            };
            if let Some(m) = mark {
                return Ok(vec![56, m, 7]); // ⠸ + 도형 + ⠇
            }
        }
    }

    // PDF 한글 점자 제36항 — Number 모드: 로마 숫자 (I·V·X·L·C·D·M 만으로 구성된 문자열).
    // 알고리즘: 영자표시 ⠴ + 대문자 표시(단일 대문자 ⠠ / 모두 대문자 ⠠⠠)
    //          + 소문자화한 letter들의 점자 + 마침표 ⠲(50).
    // Math 모드의 변수(제12항)와 동형이지만 종료표 ⠲이 붙는다는 점이 다르다.
    if let Some(EncodingMode::Number) = options.default_mode {
        let chars: Vec<char> = text.chars().collect();
        if !chars.is_empty()
            && chars.iter().all(|c| {
                matches!(
                    c.to_ascii_uppercase(),
                    'I' | 'V' | 'X' | 'L' | 'C' | 'D' | 'M'
                )
            })
        {
            let mut out = vec![52u8]; // ⠴ 영자표시
            if chars.iter().all(|c| c.is_ascii_uppercase()) {
                out.push(32); // ⠠ 대문자 표시
                if chars.len() >= 2 {
                    out.push(32); // ⠠⠠ 대문자 묶음
                }
            }
            for ch in &chars {
                out.push(crate::english::encode_english(ch.to_ascii_lowercase())?);
            }
            out.push(50); // ⠲ 마침표
            return Ok(out);
        }
    }

    // PDF 수학 점자 — math mode에서 input의 형태에 따른 PDF 정의 매핑.
    // Default routing also enters this branch for expressions that carry an
    // unambiguous math-only signal (`x′`, `p → q`, `|x|`, `△ABC`). Otherwise the
    // token pipeline sees each space-separated word independently and can mark
    // variables/operators as UEB grade-1 text instead of one math expression.
    let default_math_owned = options.default_mode.is_none()
        && default_math_expression_needs_whole_route(text)
        && !text.chars().any(crate::utils::is_korean_char);
    if matches!(options.default_mode, Some(EncodingMode::Math)) || default_math_owned {
        // Explicit math mode still accepts the public testcase/API LaTeX form
        // `$...$`.  The whole-expression fast path below consumes already
        // normalized math text, so sending the dollar delimiters and LaTeX
        // commands to it directly makes otherwise valid expressions fall back
        // to the raw symbol encoder.  Reuse the same LaTeX normalization and
        // math encoder as the token pipeline for one complete math block.
        if math_mode
            && text.len() >= 3
            && text.starts_with('$')
            && text.ends_with('$')
            && text.matches('$').count() == 2
        {
            let inner = &text[1..text.len() - 1];
            return crate::rules::token_rules::latex_math::encode_latex_math_bytes_with_context(
                inner,
                math_context,
            );
        }

        let chars: Vec<char> = text.chars().collect();

        // PDF 수학 제12항: 단일 ASCII lowercase = 영자표시 ⠴(52) + 알파벳 점자.
        // (수학 모드의 단독 소문자는 변수이며 종료표 ⠲을 붙이지 않는다.)
        if chars.len() == 1 && chars[0].is_ascii_lowercase() {
            return Ok(vec![52, crate::english::encode_english(chars[0])?]);
        }

        // PDF 수학 점자 — 괄호 단일 기호 매핑 (default = math_bracket).
        // math_system_bracket / math_group은 input만으로 구분 불가능하므로
        // 가장 일반적인 math_bracket 점형으로 default 처리.
        if chars.len() == 1 {
            match chars[0] {
                '(' => return Ok(vec![38]),     // ⠦
                ')' => return Ok(vec![52]),     // ⠴
                '{' => return Ok(vec![54]),     // ⠶
                '}' => return Ok(vec![54]),     // ⠶
                '[' => return Ok(vec![55, 4]),  // ⠷⠄
                ']' => return Ok(vec![32, 62]), // ⠠⠾
                _ => {}
            }
        }

        // PDF 수학 점자 — 단일 기호 직접 매핑.
        // 단독 입력(·, |, ′, π, Η, …)은 일반 인코더 파이프라인을 거치며 곱셈 점,
        // 절댓값 prefix(⠸), 영자표시(⠴), 대문자 표시(⠠) 등이 잘못 부착될 수 있어,
        // 단일 글자 입력에 한해 math_symbol_shortcut의 raw 매핑을 직접 사용한다.
        if chars.len() == 1
            && let Ok(code) =
                crate::math_symbol_shortcut::encode_char_math_symbol_shortcut(chars[0])
        {
            return Ok(code.to_vec());
        }
        // PDF — 다중 char math 입력은 math expression engine에 직접 위임한다.
        // (예: `tan90° = ∞`, `A⃗ = (A₁, A₂, A₃)` 등이 prose context 없이 순수 math일 때.)
        // 순수 math 컨텍스트에서는 binary operator 주변 공백이 의미가 없으므로 제거한다.
        let cleaned: String = {
            let mut s = String::with_capacity(text.len());
            let chs: Vec<char> = text.chars().collect();
            let mut i = 0;
            while i < chs.len() {
                let c = chs[i];
                // 공백 + binary op + 공백 → binary op만 유지
                if c == ' '
                    && i + 1 < chs.len()
                    && matches!(chs[i + 1], '=' | '+' | '-' | '<' | '>')
                {
                    i += 1;
                    continue;
                }
                if matches!(c, '=' | '+' | '-' | '<' | '>')
                    && i + 1 < chs.len()
                    && chs[i + 1] == ' '
                {
                    s.push(c);
                    i += 2;
                    continue;
                }
                s.push(c);
                i += 1;
            }
            s
        };
        if let Ok(bytes) =
            rules::math::encoder::encode_math_expression_with_context(&cleaned, math_context)
        {
            return Ok(bytes);
        }
    }

    let english_indicator = text
        .split(' ')
        .filter(|w| !w.is_empty())
        .any(|word| word.chars().any(utils::is_korean_char));

    with_encoder(english_indicator, |encoder| {
        encoder.set_matrix_context_active(matrix_context);
        encoder.set_math_mode_active(math_mode);

        if let Some(mode) = options.default_mode {
            encoder.set_default_mode(mode);
        }

        let mut result = Vec::new();
        encoder.encode(text, &mut result)?;
        // 제37항 — 국어 점자 문맥(context:korean) 안의 "고립된 로마자 구간"(공백 제외
        // 전부 ASCII 알파벳)은 로마자표 ⠴(52) … 종료표 ⠲(50)로 감싼다. 단독
        // `EncodingMode::English` 입력도 동일한 로마자 구간이므로 같은 처리를 받는다.
        // `%p`(제69항 단위표)처럼 비알파벳이 섞인 입력은 제외된다.
        let wrap_roman_section = matches!(options.default_mode, Some(EncodingMode::English))
            || (matches!(options.default_mode, Some(EncodingMode::Korean))
                && is_isolated_roman_section(text));
        if wrap_roman_section && !result.is_empty() {
            result.insert(0, 52);
            result.push(50);
        }
        Ok(result)
    })
}

/// Encode text with explicit formatting spans.
pub fn encode_with_formatting(text: &str, spans: &[FormattingSpan]) -> Result<Vec<u8>, String> {
    if spans.is_empty() {
        return encode(text);
    }

    let english_indicator = text
        .split(' ')
        .filter(|w| !w.is_empty())
        .any(|word| word.chars().any(utils::is_korean_char));

    with_encoder(english_indicator, |encoder| {
        let mut result = Vec::new();
        encoder.encode_with_formatting(text, spans, &mut result)?;
        Ok(result)
    })
}

pub fn encode_to_unicode(text: &str) -> Result<String, String> {
    let result = encode(text)?;
    Ok(result
        .iter()
        .map(|c| unicode::encode_unicode(*c))
        .collect::<String>())
}

/// Unicode version of [`encode_with_formatting`].
pub fn encode_to_unicode_with_formatting(
    text: &str,
    spans: &[FormattingSpan],
) -> Result<String, String> {
    let result = encode_with_formatting(text, spans)?;
    Ok(result
        .iter()
        .map(|c| unicode::encode_unicode(*c))
        .collect::<String>())
}

pub fn encode_to_braille_font(text: &str) -> Result<String, String> {
    let result = encode(text)?;
    Ok(result
        .iter()
        .map(|c| unicode::encode_unicode(*c))
        .collect::<String>())
}

#[cfg(test)]
mod state_bleed_tests {
    use super::encode;

    #[test]
    fn cached_encoder_resets_between_different_contexts() {
        let before = encode("안녕").unwrap();
        let _english = encode("hello").unwrap();
        let after = encode("안녕").unwrap();

        assert_eq!(before, after);
    }
}

#[cfg(test)]
mod test {
    //! Main test suite for braillify (extracted from lib.rs).

    use std::{collections::HashMap, fs::File};

    use crate::{symbol_shortcut, unicode::encode_unicode};
    use proptest::prelude::*;

    use super::*;

    /// Find the first occurrence of `needle` in `text` and return its byte range.
    /// (Was previously parameterized by `nth` but only ever called with `nth=0`;
    /// simplified for coverage clarity.)
    fn find_nth_range(text: &str, needle: &str, _nth: usize) -> std::ops::Range<usize> {
        let start = text
            .find(needle)
            .unwrap_or_else(|| panic!("substring '{needle}' not found in '{text}'"));
        start..start + needle.len()
    }

    #[test]
    fn english_continuation_after_inline_number() {
        let output = encode("가 a1a").unwrap();
        assert!(
            output.contains(&48),
            "inline number should trigger english continuation indicator"
        );
    }

    #[test]
    fn symbol_triggers_english_segment_at_start() {
        let output = encode("(A 가").unwrap();
        let english_symbol = symbol_shortcut::encode_english_char_symbol_shortcut('(').unwrap();
        assert_eq!(output[0], 52);
        assert!(output.len() > english_symbol.len());
        assert_eq!(
            &output[1..1 + english_symbol.len()],
            english_symbol,
            "opening english symbol should use english shortcut"
        );
    }

    #[rstest::rstest]
    #[case::slash_forced_symbol("가 a/")]
    #[case::underscore_leave_english("가 a_b")]
    fn english_symbol_terminator_variants(#[case] input: &str) {
        let output = encode(input).unwrap();
        assert!(
            output.contains(&50),
            "english terminator (50) absent for {input:?}"
        );
    }

    #[test]
    fn comma_prefix_variants_and_korean_following() {
        let output = encode("가 A,가").unwrap();
        let comma = symbol_shortcut::encode_char_symbol_shortcut(',').unwrap();
        assert!(
            output.windows(comma.len()).any(|window| window == comma),
            "comma before Korean should use Korean punctuation mapping"
        );

        // smoke-check for punctuation transition path
        assert!(encode("가 A!,가").is_ok());
    }

    #[test]
    fn next_word_single_letter_sets_continuation_flag() {
        let output = encode("가 a b").unwrap();
        assert!(
            output.contains(&48),
            "single-letter following word should trigger continuation marker"
        );
    }

    #[rstest::rstest]
    #[case::forced_symbol_inserts_terminator("가 a /", 50)]
    #[case::skip_symbol_requests_continuation("가 a . b", 48)]
    fn next_word_symbol_rules_apply(#[case] input: &str, #[case] expected_byte: u8) {
        let output = encode(input).unwrap();
        assert!(
            output.contains(&expected_byte),
            "expected byte {expected_byte} not in output for {input:?}"
        );
    }

    #[test]
    fn next_word_with_invalid_char_returns_error() {
        let err = encode("가 a 😀");
        assert!(err.is_err());
    }

    #[test]
    fn encode_with_formatting_wraps_markers() {
        let text = "다음 보기에서 명사가 아닌 것은?";
        let spans = vec![FormattingSpan {
            range: find_nth_range(text, "아닌", 0),
            kind: FormattingKind::Emphasis,
        }];
        let unicode = encode_to_unicode_with_formatting(text, &spans).unwrap();
        assert!(unicode.contains("⠠⠤⠣⠉⠟⠤⠄"));
    }

    #[test]
    fn encode_with_formatting_rejects_non_boundary_range() {
        let text = "왜";
        let spans = [FormattingSpan {
            range: 1..3,
            kind: FormattingKind::Emphasis,
        }];
        let err = encode_with_formatting(text, &spans);
        assert!(err.is_err());
    }

    #[derive(serde::Deserialize, Default)]
    #[serde(rename_all = "camelCase")]
    struct TestCaseRuleConfig {
        #[serde(default)]
        benchmark: bool,
        #[serde(default)]
        shards: bool,
    }

    type TestCaseRuleMap = HashMap<String, TestCaseRuleConfig>;

    fn load_test_case_rule_map() -> TestCaseRuleMap {
        serde_json::from_str(
            &std::fs::read_to_string(concat!(env!("CARGO_MANIFEST_DIR"), "/../../rule_map.json"))
                .unwrap(),
        )
        .unwrap()
    }

    /// Resolves a physical JSON file to its logical `rule_map.json` key.
    ///
    /// Most fixtures map one-to-one (`korean/rule_1.json` -> `korean/rule_1`).
    /// A rule-map entry with `shards: true` may instead own numbered files such
    /// as `2025_corpus/sentence_01.json` and `2025_corpus/sentence_02.json`. Unknown files
    /// keep their physical key so the rule-map integrity check reports them.
    fn logical_test_case_key(physical_key: &str, rule_map: &TestCaseRuleMap) -> String {
        if rule_map.contains_key(physical_key) {
            return physical_key.to_string();
        }

        let mut matches = rule_map
            .iter()
            .filter(|(_, config)| config.shards)
            .filter_map(|(key, _)| {
                physical_key
                    .strip_prefix(key)
                    .and_then(|suffix| suffix.strip_prefix('_'))
                    .filter(|suffix| {
                        !suffix.is_empty() && suffix.bytes().all(|byte| byte.is_ascii_digit())
                    })
                    .map(|_| key.clone())
            })
            .collect::<Vec<_>>();
        matches.sort();
        assert!(
            matches.len() <= 1,
            "fixture {physical_key:?} matches multiple sharded rule-map entries: {matches:?}"
        );
        matches.pop().unwrap_or_else(|| physical_key.to_string())
    }

    /// Recursively scans `test_cases/`, returning physical paths paired with
    /// logical rule-map keys. Multiple shard paths may therefore share one key.
    fn collect_test_files(rule_map: &TestCaseRuleMap) -> Vec<(std::path::PathBuf, String)> {
        let test_cases_dir =
            std::path::Path::new(concat!(env!("CARGO_MANIFEST_DIR"), "/../../test_cases"));
        let mut files = Vec::new();
        for entry in std::fs::read_dir(test_cases_dir).unwrap() {
            let entry = entry.unwrap();
            let path = entry.path();
            if path.is_dir() {
                let subdir = path.file_name().unwrap().to_string_lossy().to_string();
                for sub_entry in std::fs::read_dir(&path).unwrap() {
                    let sub_entry = sub_entry.unwrap();
                    let sub_path = sub_entry.path();
                    if sub_path.extension().unwrap_or_default() == "json" {
                        let stem = sub_path.file_stem().unwrap().to_string_lossy().to_string();
                        let physical_key = format!("{}/{}", subdir, stem);
                        let key = logical_test_case_key(&physical_key, rule_map);
                        files.push((sub_path, key));
                    }
                }
            }
        }
        files.sort_by(|a, b| a.1.cmp(&b.1).then_with(|| a.0.cmp(&b.0)));
        files
    }

    #[rstest::rstest]
    #[case::exact_rule("korean/rule_1", "korean/rule_1")]
    #[case::numbered_shard("2025_corpus/sentence_04", "2025_corpus/sentence")]
    #[case::unregistered_file("2025_corpus/other_01", "2025_corpus/other_01")]
    fn resolves_physical_fixture_to_logical_rule_key(
        #[case] physical_key: &str,
        #[case] expected: &str,
    ) {
        let rule_map = HashMap::from([
            ("korean/rule_1".to_string(), TestCaseRuleConfig::default()),
            (
                "2025_corpus/sentence".to_string(),
                TestCaseRuleConfig {
                    shards: true,
                    ..TestCaseRuleConfig::default()
                },
            ),
        ]);

        assert_eq!(logical_test_case_key(physical_key, &rule_map), expected);
    }

    fn testcase_answer_forms(
        record: &serde_json::Value,
        filename: &str,
        line_num: usize,
    ) -> Vec<(String, String, String)> {
        if let Some(serde_json::Value::Array(alternatives)) = record.get("alternatives") {
            return alternatives
                .iter()
                .map(|alternative| {
                    let internal = alternative["internal"].as_str().unwrap_or_else(|| {
                        panic!(
                            "'alternatives.internal' 필드를 읽는 중 오류 발생: at {} in {}",
                            line_num, filename
                        )
                    });
                    let expected = alternative["expected"].as_str().unwrap_or_else(|| {
                        panic!(
                            "'alternatives.expected' 필드를 읽는 중 오류 발생: at {} in {}",
                            line_num, filename
                        )
                    });
                    let unicode = alternative["unicode"].as_str().unwrap_or_else(|| {
                        panic!(
                            "'alternatives.unicode' 필드를 읽는 중 오류 발생: at {} in {}",
                            line_num, filename
                        )
                    });
                    (
                        internal.to_string(),
                        expected.to_string(),
                        unicode.to_string(),
                    )
                })
                .collect();
        }

        let internal = record["internal"].as_str().unwrap_or_else(|| {
            panic!(
                "'internal' 필드를 읽는 중 오류 발생: at {} in {}",
                line_num, filename
            )
        });
        let expected = record["expected"].as_str().unwrap_or_else(|| {
            panic!(
                "'expected' 필드를 읽는 중 오류 발생: at {} in {}",
                line_num, filename
            )
        });
        let unicode = record["unicode"].as_str().unwrap_or_else(|| {
            panic!(
                "'unicode' 필드를 읽는 중 오류 발생: at {} in {}",
                line_num, filename
            )
        });
        vec![(
            internal.to_string(),
            expected.to_string(),
            unicode.to_string(),
        )]
    }

    #[derive(serde::Deserialize)]
    struct NiklCorpusCase {
        input: String,
        unicode: String,
    }

    fn load_test_case_group<T: serde::de::DeserializeOwned>(key: &str) -> Vec<T> {
        let rule_map = load_test_case_rule_map();
        assert!(rule_map.contains_key(key), "unknown test-case group: {key}");
        let paths = collect_test_files(&rule_map)
            .into_iter()
            .filter_map(|(path, logical_key)| (logical_key == key).then_some(path))
            .collect::<Vec<_>>();
        assert!(!paths.is_empty(), "test-case group {key} has no JSON files");
        let mut cases = Vec::new();
        for path in paths {
            let mut shard: Vec<T> = serde_json::from_reader(
                File::open(&path).expect("test-case JSON must be readable"),
            )
            .unwrap_or_else(|error| panic!("{} must be valid JSON: {error}", path.display()));
            cases.append(&mut shard);
        }
        cases
    }

    fn load_nikl_2025_corpus_cases() -> Vec<NiklCorpusCase> {
        load_test_case_group("2025_corpus/sentence")
    }

    type TestStatusRow = (
        String,
        String,
        String,
        String,
        bool,
        String,
        bool,
        String,
        bool,
    );

    const REPORT_PAGE_SIZE: usize = 250;

    #[derive(serde::Serialize)]
    #[serde(rename_all = "camelCase")]
    struct ReportPageInfo {
        page_size: usize,
        page_count: usize,
    }

    /// Splits a group's rows into the pages the landing app fetches on demand.
    /// Always yields at least one page so every group has a `page-1.json`.
    fn paginate_rows(rows: Vec<TestStatusRow>) -> Vec<Vec<TestStatusRow>> {
        if rows.is_empty() {
            return vec![Vec::new()];
        }
        rows.chunks(REPORT_PAGE_SIZE)
            .map(<[TestStatusRow]>::to_vec)
            .collect()
    }

    #[rstest::rstest]
    #[case::no_rows(0, 1)]
    #[case::partial_page(1, 1)]
    #[case::exact_page(REPORT_PAGE_SIZE, 1)]
    #[case::page_overflow(REPORT_PAGE_SIZE + 1, 2)]
    #[case::many_pages(REPORT_PAGE_SIZE * 3, 3)]
    fn paginate_rows_publishes_every_row(#[case] row_count: usize, #[case] expected_pages: usize) {
        let rows = (0..row_count)
            .map(|index| -> TestStatusRow {
                (
                    format!("가{index}"),
                    String::new(),
                    "⠈⠣".to_string(),
                    "⠈⠣".to_string(),
                    index % 2 == 0,
                    String::new(),
                    false,
                    String::new(),
                    false,
                )
            })
            .collect::<Vec<TestStatusRow>>();

        let pages = paginate_rows(rows.clone());

        assert_eq!(pages.len(), expected_pages);
        assert_eq!(pages.concat(), rows);
        assert!(pages.iter().all(|page| page.len() <= REPORT_PAGE_SIZE));
    }

    #[derive(Default)]
    struct NiklFailureStats {
        encoding_errors: usize,
        contains_latin: usize,
        contains_digits: usize,
        contains_delimiters: usize,
        korean_text_only: usize,
    }

    fn classify_nikl_failure(input: &str, is_encoding_error: bool, stats: &mut NiklFailureStats) {
        if is_encoding_error {
            stats.encoding_errors += 1;
        }

        let contains_latin = input.chars().any(|ch| ch.is_ascii_alphabetic());
        let contains_digits = input.chars().any(|ch| ch.is_ascii_digit());
        let contains_delimiters = input.chars().any(|ch| {
            matches!(
                ch,
                '(' | ')' | '[' | ']' | '{' | '}' | '“' | '”' | '‘' | '’' | '"' | '\''
            )
        });

        stats.contains_latin += usize::from(contains_latin);
        stats.contains_digits += usize::from(contains_digits);
        stats.contains_delimiters += usize::from(contains_delimiters);
        stats.korean_text_only +=
            usize::from(!contains_latin && !contains_digits && !contains_delimiters);
    }

    /// NIKL Korean–Korean Braille Parallel Corpus (2025 v1.0) regression suite.
    ///
    /// The fixture uses the shared logical-group loader and the project's standard
    /// `input`/`internal`/`expected`/`unicode` shape. This dedicated assertion keeps
    /// the full benchmark available as an opt-in regression gate while
    /// `test_by_testcase` records its current accuracy for the landing page.
    #[test]
    #[ignore = "NIKL 2025 corpus support is tracked as a benchmark until it reaches 100%"]
    fn test_nikl_2025_parallel_corpus() {
        let cases = load_nikl_2025_corpus_cases();
        assert!(
            !cases.is_empty(),
            "NIKL 2025 corpus fixture must not be empty"
        );

        let mut failures = Vec::new();
        let mut failure_stats = NiklFailureStats::default();
        for case in &cases {
            match encode_to_unicode(&case.input) {
                Ok(actual) if actual == case.unicode => {}
                Ok(actual) => {
                    classify_nikl_failure(&case.input, false, &mut failure_stats);
                    failures.push((
                        case.input.as_str(),
                        case.input.as_str(),
                        case.unicode.as_str(),
                        "mismatch",
                        actual,
                    ));
                }
                Err(error) => {
                    classify_nikl_failure(&case.input, true, &mut failure_stats);
                    failures.push((
                        case.input.as_str(),
                        case.input.as_str(),
                        case.unicode.as_str(),
                        "encoding error",
                        error,
                    ));
                }
            }
        }

        if !failures.is_empty() {
            let preview = failures
                .iter()
                .take(20)
                .map(|(id, input, expected, kind, actual)| {
                    format!(
                        "{id} ({kind})\n  input: {input}\n  expected: {expected}\n  actual: {actual}"
                    )
                })
                .collect::<Vec<_>>()
                .join("\n");
            panic!(
                "NIKL 2025 corpus: {}/{} cases differ from the reference.\n\
                 Failure traits (overlapping): encoding errors={}, Latin={}, digits={}, delimiters={}, Korean-text-only={}.\n\
                 First {}:\n{}",
                failures.len(),
                cases.len(),
                failure_stats.encoding_errors,
                failure_stats.contains_latin,
                failure_stats.contains_digits,
                failure_stats.contains_delimiters,
                failure_stats.korean_text_only,
                failures.len().min(20),
                preview
            );
        }
    }

    #[test]
    pub fn test_by_testcase() {
        let rule_map = load_test_case_rule_map();
        let files = collect_test_files(&rule_map);
        let mut total = 0;
        let mut failed = 0;
        let mut failed_cases = Vec::new();
        // (filename, line_num, input, reason) — limitation 필드로 skip된 케이스.
        let mut skipped_cases: Vec<(String, usize, String, String)> = Vec::new();
        let mut file_stats = std::collections::BTreeMap::new();

        let rule_map_keys: std::collections::HashSet<String> = rule_map.keys().cloned().collect();
        let file_keys: std::collections::HashSet<_> =
            files.iter().map(|(_, key)| key.clone()).collect();
        let missing_keys = rule_map_keys.difference(&file_keys).collect::<Vec<_>>();
        let extra_keys = file_keys.difference(&rule_map_keys).collect::<Vec<_>>();
        if !missing_keys.is_empty() || !extra_keys.is_empty() {
            panic!(
                "rule_map.json 파일이 올바르지 않습니다. missing: {:?}, extra: {:?}",
                missing_keys, extra_keys
            );
        }

        for (path, file_stem) in &files {
            let config = rule_map
                .get(file_stem)
                .unwrap_or_else(|| panic!("missing rule-map config for {file_stem}"));
            let content = std::fs::read_to_string(path).unwrap();
            let filename = path.file_name().unwrap().to_string_lossy();
            let records: Vec<serde_json::Value> = serde_json::from_str(&content)
                .unwrap_or_else(|e| panic!("JSON 파일을 읽는 중 오류 발생: {} in {}", e, filename));

            let mut file_total = 0;
            let mut file_failed = 0;
            let mut file_world_total = 0;
            let mut file_world_failed = 0;
            let mut file_jeomsarang_total = 0;
            let mut file_jeomsarang_failed = 0;
            let mut test_status: Vec<TestStatusRow> = Vec::new();

            for (line_num, record) in records.iter().enumerate() {
                // `limitation` 필드는 testcase 자체의 구조적 한계(예: 묵자 input에 시각
                // 강조 정보가 없어 알고리즘 추론 불가능)를 명시한다. 이후 input 메타데이터
                // 보강이나 별도 API(예: FormattingSpan)로 해결할 때까지 본 테스트에서는
                // 제외한다. 한계 인정은 0-fail 달성 자체를 위한 우회가 아닌, 알고리즘
                // 일반화 원칙(AGENTS.md)을 지키기 위한 명시적 deferral이다.
                //
                // 가드레일: limitation 항목은 실제로 실패해야만 한다. 알고리즘이 개선되어
                // 이미 통과하는 케이스가 limitation으로 표시되면(=stale) 패닉으로 표시한다.
                if let Some(reason) = record.get("limitation").and_then(|v| v.as_str()) {
                    let input = record["input"].as_str().unwrap_or("");
                    let expected_values = testcase_answer_forms(record, &filename, line_num)
                        .into_iter()
                        .map(|(_, _, unicode)| unicode)
                        .collect::<Vec<_>>();
                    if let Ok(actual) = crate::encode_to_unicode(input)
                        && expected_values.contains(&actual)
                    {
                        panic!(
                            "STALE limitation in {} line {}: input={:?} passes but is marked limitation: {:?}",
                            filename, line_num, input, reason
                        );
                    }
                    skipped_cases.push((
                        filename.to_string(),
                        line_num + 1,
                        input.to_string(),
                        reason.to_string(),
                    ));
                    continue;
                }
                if !config.benchmark {
                    total += 1;
                }
                file_total += 1;
                let input = record["input"].as_str().unwrap_or_else(|| {
                    panic!(
                        "'input' 필드를 읽는 중 오류 발생: at {} in {}",
                        line_num, filename
                    )
                });
                let context = record["context"].as_str().unwrap_or("");
                let note = record["note"].as_str().unwrap_or("").to_string();
                // Benchmark fixtures are evaluated only against their own Unicode
                // reference. Competitor fields remain untouched in the source JSON
                // and are intentionally excluded from pass/fail metrics.
                let (world, jeomsarang) = if config.benchmark {
                    (String::new(), String::new())
                } else {
                    (
                        record["world"].as_str().unwrap_or("").to_string(),
                        record["jeomsarang"].as_str().unwrap_or("").to_string(),
                    )
                };
                if !config.benchmark {
                    file_world_total += 1;
                    file_jeomsarang_total += 1;
                }
                // 테스트 케이스 파일의 숫자 코드에서 앞뒤 공백 제거 후 비교
                let answer_forms = testcase_answer_forms(record, &filename, line_num);
                let expected_forms = answer_forms
                    .iter()
                    .map(|(_, expected, _)| expected)
                    .map(|expected| expected.trim().replace(" ", "⠀"))
                    .collect::<Vec<_>>();
                let unicode_forms = answer_forms
                    .into_iter()
                    .map(|(_, _, unicode)| unicode)
                    .collect::<Vec<_>>();
                let expected_display = expected_forms.join(" / ");
                let unicode_display = unicode_forms.join(" / ");
                // testcase JSON `context` 필드는 `EncodingMode` enum과 1:1 매핑.
                // input만으로는 모호한 케이스(예: 영문자 "a"가 일반 영자인지 수학 변수인지)는
                // testcase가 mode를 명시한다. 옛 한글(중세국어)은 input 안 옛 자모/한자가
                // 자동 detect되므로 production encode()의 token rule이 처리한다.
                //
                // `strip_prefix:X` ad-hoc 메타데이터는 testcase 단계에서 입력 X를 제거하고
                // 인코딩한다. 일반 알고리즘은 묵음 한자(砌 등)를 단독으로 만나면 빈 cell을
                // 남기지 않을 책임이 있지만, 그 책임 일반화는 별도 작업이며, 본 메타데이터는
                // testcase 본문에 묵음 한자가 등장하는 케이스를 정확한 인코딩 입력으로
                // 좁혀 검증하기 위한 testcase-level 도구다.
                //
                // 알 수 없는 context (빈 값/기타 ad-hoc 메타데이터)는 default 인코딩 사용.
                let input_for_encoding: String =
                    if let Some(prefix) = context.strip_prefix("strip_prefix:") {
                        input.strip_prefix(prefix).unwrap_or(input).to_string()
                    } else {
                        input.to_string()
                    };
                let encoding_result = match context.parse::<crate::rules::context::EncodingMode>() {
                    Ok(mode) => encode_with_options(
                        &input_for_encoding,
                        &EncodeOptions {
                            default_mode: Some(mode),
                        },
                    ),
                    Err(_) => encode(&input_for_encoding),
                };

                match encoding_result {
                    Ok(actual) => {
                        let braille_expected = actual
                            .iter()
                            .map(|c| unicode::encode_unicode(*c))
                            .collect::<String>();
                        let actual_str = actual
                            .iter()
                            .map(|c| {
                                if *c == 255 {
                                    "\n".to_string()
                                } else {
                                    c.to_string()
                                }
                            })
                            .collect::<String>();
                        let case_matches = expected_forms.contains(&actual_str);

                        if !case_matches {
                            file_failed += 1;
                            if !config.benchmark {
                                failed += 1;
                                failed_cases.push((
                                    filename.to_string(),
                                    line_num + 1,
                                    input.to_string(),
                                    expected_display.clone(),
                                    actual_str.clone(),
                                    braille_expected.clone(),
                                    unicode_display.clone(),
                                ));
                            }
                        }
                        let world_is_success = !world.is_empty() && unicode_forms.contains(&world);
                        if !config.benchmark && !world_is_success {
                            file_world_failed += 1;
                        }
                        let jeomsarang_is_success =
                            !jeomsarang.is_empty() && unicode_forms.contains(&jeomsarang);
                        if !config.benchmark && !jeomsarang_is_success {
                            file_jeomsarang_failed += 1;
                        }

                        test_status.push((
                            input.to_string(),
                            note.clone(),
                            unicode_display.clone(),
                            braille_expected.clone(),
                            case_matches,
                            world.clone(),
                            world_is_success,
                            jeomsarang.clone(),
                            jeomsarang_is_success,
                        ));
                    }
                    Err(e) => {
                        if !config.benchmark {
                            println!("Error: {}", e);
                        }
                        file_failed += 1;
                        if !config.benchmark {
                            failed += 1;
                            failed_cases.push((
                                filename.to_string(),
                                line_num + 1,
                                input.to_string(),
                                expected_display.clone(),
                                "".to_string(),
                                e.to_string(),
                                unicode_display.clone(),
                            ));
                        }

                        let world_is_success = !world.is_empty() && unicode_forms.contains(&world);
                        if !config.benchmark && !world_is_success {
                            file_world_failed += 1;
                        }
                        let jeomsarang_is_success =
                            !jeomsarang.is_empty() && unicode_forms.contains(&jeomsarang);
                        if !config.benchmark && !jeomsarang_is_success {
                            file_jeomsarang_failed += 1;
                        }

                        test_status.push((
                            input.to_string(),
                            note.clone(),
                            unicode_display.clone(),
                            e.to_string(),
                            false,
                            world.clone(),
                            world_is_success,
                            jeomsarang.clone(),
                            jeomsarang_is_success,
                        ));
                    }
                }
            }
            let stats = file_stats
                .entry(file_stem.clone())
                .or_insert_with(|| (0, 0, 0, 0, 0, 0, Vec::<TestStatusRow>::new()));
            stats.0 += file_total;
            stats.1 += file_failed;
            stats.2 += file_world_total;
            stats.3 += file_world_failed;
            stats.4 += file_jeomsarang_total;
            stats.5 += file_jeomsarang_failed;
            stats.6.append(&mut test_status);
        }

        if !failed_cases.is_empty() {
            println!("\n실패한 케이스:");
            println!("=================");
            for (filename, line_num, input, expected, actual, unicode, braille) in failed_cases {
                let diff = {
                    let unicode_words: Vec<&str> = unicode.split(encode_unicode(0)).collect();
                    let braille_words: Vec<&str> = braille.split(encode_unicode(0)).collect();
                    let mut diff = Vec::new();
                    for (i, (u, b)) in unicode_words.iter().zip(braille_words.iter()).enumerate() {
                        if u != b {
                            diff.push(i);
                        }
                    }
                    diff
                };

                let input_words: Vec<&str> = input.split(' ').collect();
                let unicode_words: Vec<&str> = unicode.split(encode_unicode(0)).collect();
                if input_words.len() != unicode_words.len() {
                    println!("파일: {}, 라인 {}: '{}'", filename, line_num, input);
                    println!("  예상: {}", expected);
                    println!("  실제: {}", actual);
                    println!("  유니코드 Result:   {}", unicode);
                    println!("  유니코드 Expected: {}", braille);
                } else {
                    let mut colored_input = String::new();
                    let mut colored_unicode = String::new();

                    for (i, word) in input_words.iter().enumerate() {
                        if diff.contains(&i) {
                            colored_input.push_str(&format!("\x1b[31m{}\x1b[0m", word));
                            colored_unicode
                                .push_str(&format!("\x1b[31m{}\x1b[0m", unicode_words[i]));
                        } else {
                            colored_input.push_str(word);
                            colored_unicode.push_str(unicode_words[i]);
                        }
                        if i < input_words.len() - 1 {
                            colored_input.push(' ');
                            colored_unicode.push(' ');
                        }
                    }
                    println!("파일: {}, 라인 {}: '{}'", filename, line_num, colored_input);
                    println!("  예상: {}", expected);
                    println!("  실제: {}", actual);
                    println!("  유니코드 Result:   {}", colored_unicode);
                    println!("  유니코드 Expected: {}", braille);
                }
                println!();
            }
        }

        if !skipped_cases.is_empty() {
            println!("\nSkip된 케이스 (limitation):");
            println!("=================");
            for (filename, line_num, input, reason) in &skipped_cases {
                println!(
                    "\x1b[33m파일: {}, 라인 {}: '{}'\x1b[0m",
                    filename, line_num, input
                );
                println!("  사유: {}", reason);
                println!();
            }
            println!("총 Skip: {}건", skipped_cases.len());
        }

        // Rows for every group are drained out of `file_stats` into paged JSON the
        // landing app loads on demand, leaving `test_status.json` as pure
        // aggregates. Inlining them instead put 467k corpus rows into one route's
        // payload, which is what broke the export (`ERR_ENCODING_INVALID_ENCODED_DATA`)
        // and grew the site past the GitHub Pages 1 GB ceiling.
        let report_root = std::path::PathBuf::from(concat!(
            env!("CARGO_MANIFEST_DIR"),
            "/../../apps/landing/public/test-status"
        ));
        if report_root.exists() {
            std::fs::remove_dir_all(&report_root).unwrap_or_else(|error| {
                panic!(
                    "failed to clear report directory {}: {error}",
                    report_root.display()
                )
            });
        }
        let mut report_manifest = std::collections::BTreeMap::new();
        for (key, stats) in &mut file_stats {
            let pages = paginate_rows(std::mem::take(&mut stats.6));
            let group_dir = report_root.join(key);
            std::fs::create_dir_all(&group_dir).unwrap_or_else(|error| {
                panic!(
                    "failed to create report directory {}: {error}",
                    group_dir.display()
                )
            });
            for (index, page) in pages.iter().enumerate() {
                let page_path = group_dir.join(format!("page-{}.json", index + 1));
                serde_json::to_writer(File::create(&page_path).unwrap(), page).unwrap();
            }
            report_manifest.insert(
                key.clone(),
                ReportPageInfo {
                    page_size: REPORT_PAGE_SIZE,
                    page_count: pages.len(),
                },
            );
        }
        // Written last so a half-generated directory can never look complete.
        std::fs::create_dir_all(&report_root).unwrap();
        serde_json::to_writer_pretty(
            File::create(report_root.join("manifest.json")).unwrap(),
            &report_manifest,
        )
        .unwrap();

        // Write per-file stats to the workspace-root status file.
        let status_path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../test_status.json");
        serde_json::to_writer_pretty(File::create(status_path).unwrap(), &file_stats).unwrap();

        // Per-category (korean/math/english) totals — aggregated here because the
        // per-file loop below consumes `file_stats`. Keys are owned so the summary
        // can print after that loop.
        let mut category_stats: std::collections::BTreeMap<String, (usize, usize)> =
            std::collections::BTreeMap::new();
        for (key, value) in &file_stats {
            let category = key.split('/').next().unwrap_or(key.as_str()).to_string();
            let entry = category_stats.entry(category).or_insert((0, 0));
            entry.0 += value.0;
            entry.1 += value.1;
        }

        println!("\n파일별 테스트 결과:");
        println!("=================");
        for (filename, (file_total, file_failed, _, _, _, _, _)) in file_stats {
            let success_rate =
                ((file_total - file_failed) as f64 / file_total as f64 * 100.0) as i32;
            let color = if success_rate == 100 {
                "\x1b[32m" // 초록색
            } else if success_rate == 0 {
                "\x1b[31m" // 빨간색
            } else {
                "\x1b[33m" // 주황색
            };
            println!(
                "{}: {}개 중 {}개 성공 (성공률: {}{}%\x1b[0m)",
                filename,
                file_total,
                file_total - file_failed,
                color,
                success_rate
            );
        }
        println!("\n카테고리별 결과:");
        println!("=================");
        for (category, (cat_total, cat_failed)) in &category_stats {
            println!(
                "{}: {}/{} 성공",
                category,
                cat_total - cat_failed,
                cat_total
            );
        }
        println!("\n전체 테스트 결과 요약:");
        println!("=================");
        println!("총 테스트 케이스: {}", total);
        println!("성공: {}", total - failed);
        println!("실패: {}", failed);
        println!("Skip (limitation): {}", skipped_cases.len());
        if failed > 0 {
            panic!("{} test cases failed.", failed);
        }
    }

    proptest! {
        #[test]
        fn test_encode_proptest(s: String) {
            let result = encode(&s);
            let _encoded = match result {
                Ok(encoded) => {
                    // Empty result is valid for input that emits no braille: spaces,
                    // or standalone combining marks (제56항/제64항 — a combining mark
                    // with no base character is consumed to nothing / no-op, as
                    // asserted by `rule_64::lone_combining_square_is_no_op`).
                    let is_only_nonemitting = s.chars().all(|c| {
                        c == ' '
                            || matches!(
                                crate::char_struct::CharType::new(c),
                                Ok(crate::char_struct::CharType::CombiningMark)
                            )
                    });
                    assert!(!encoded.is_empty() || s.is_empty() || is_only_nonemitting);

                    let unicode_result = encode_to_unicode(&s);
                    assert!(unicode_result.is_ok());

                    let unicode_string = unicode_result.unwrap();
                    assert!(!unicode_string.is_empty() || s.is_empty() || is_only_nonemitting);

                    encoded
                }
                Err(_) => {
                    return Ok(()); // ok
                }
            };

            // let decoded = decode(&encoded);
            // assert_eq!(s, decoded, "Decoded string does not match original input: {}", s);
        }
    }

    /// Non-panicking accuracy report — run with `cargo test test_accuracy_report -- --nocapture`
    #[test]
    fn test_accuracy_report() {
        let rule_map = load_test_case_rule_map();
        let files = collect_test_files(&rule_map)
            .into_iter()
            .filter(|(_, key)| !rule_map[key].benchmark)
            .collect::<Vec<_>>();

        let mut total = 0usize;
        let mut passed = 0usize;
        let mut per_file: Vec<(String, usize, usize)> = Vec::new();

        for (path, filename) in &files {
            let content = std::fs::read_to_string(path).unwrap();
            let records: Vec<serde_json::Value> = serde_json::from_str(&content).unwrap();
            let mut file_total = 0;
            let mut file_passed = 0;

            for (line_num, record) in records.iter().enumerate() {
                let input = record["input"].as_str().unwrap();
                let expected_forms = testcase_answer_forms(record, filename, line_num)
                    .into_iter()
                    .map(|(_, expected, _)| expected.trim().replace(" ", "⠀"))
                    .collect::<Vec<_>>();
                if expected_forms
                    .iter()
                    .any(|expected| expected.chars().any(|c| !c.is_ascii_digit()))
                {
                    continue;
                }
                total += 1;
                file_total += 1;
                if let Ok(actual) = encode(input) {
                    let actual_str = actual.iter().map(|c| c.to_string()).collect::<String>();
                    if expected_forms.contains(&actual_str) {
                        passed += 1;
                        file_passed += 1;
                    }
                }
            }
            per_file.push((filename.clone(), file_total, file_passed));
        }

        per_file.sort();
        println!("\n═══════════════════════════════════════════════");
        println!("  BRAILLIFY ACCURACY REPORT (engine-driven)");
        println!("═══════════════════════════════════════════════");
        for (name, ft, fp) in &per_file {
            let pct = (*fp * 100).checked_div(*ft).unwrap_or(100);
            let status = if pct == 100 { "✓" } else { "✗" };
            if pct < 100 {
                println!("  {} {:20} {:>3}/{:<3} ({:>3}%)", status, name, fp, ft, pct);
            }
        }
        let all_pass: usize = per_file.iter().filter(|(_, t, p)| t == p).count();
        let some_fail: usize = per_file.len() - all_pass;
        println!("───────────────────────────────────────────────");
        println!(
            "  Files:    {} total, {} all-pass, {} with failures",
            per_file.len(),
            all_pass,
            some_fail
        );
        println!(
            "  Cases:    {}/{} passed ({:.1}%)",
            passed,
            total,
            passed as f64 / total as f64 * 100.0
        );
        println!("═══════════════════════════════════════════════\n");
    }

    #[test]
    fn test_encoder_streaming() {
        // A reused encoder treats each `encode` call as its own word, so streaming
        // "test" then "ing" must equal encoding each word INDEPENDENTLY — not the
        // one-shot "testing". §10.4.3 suppresses the word-initial `ing` groupsign in
        // a standalone "ing" (spelled out), whereas the medial `ing` of "testing"
        // keeps it; the streaming result therefore legitimately differs from
        // `encode("testing")`. This still verifies reuse: no state leaks between
        // calls, so the buffer matches two fresh per-word encodings concatenated.
        let mut encoder = Encoder::new(false); // English only test
        let mut buffer = Vec::new();

        encoder.encode("test", &mut buffer).unwrap();
        encoder.encode("ing", &mut buffer).unwrap();

        let mut expected = encode("test").unwrap();
        expected.extend(encode("ing").unwrap());
        assert_eq!(buffer, expected);
    }
}

#[cfg(test)]
mod coverage_targeted_tests {
    //! Coverage-targeted tests (extracted from lib.rs).

    use super::*;
    use crate::rules::context::EncodingMode;

    /// All four FormattingKind variants must produce their declared markers.
    /// Covers `FormattingKind::markers` arms for Emphasis/Bold/Custom1/Custom2.
    /// `FormattingKind::markers()` — 각 강조 종류별 시작·종료 점형 페어.
    #[rstest::rstest]
    #[case::emphasis(FormattingKind::Emphasis, [32, 36], [36, 4])]
    #[case::bold(FormattingKind::Bold, [48, 36], [36, 6])]
    #[case::custom1(FormattingKind::Custom1, [16, 36], [36, 2])]
    #[case::custom2(FormattingKind::Custom2, [8, 36], [36, 1])]
    fn formatting_kind_markers_all_variants(
        #[case] kind: FormattingKind,
        #[case] start: [u8; 2],
        #[case] end: [u8; 2],
    ) {
        assert_eq!(kind.markers(), (start, end));
    }

    /// Mathematical italic small h (U+210E) normalizes to plain 'h'.
    #[test]
    fn normalize_math_planck_h() {
        assert_eq!(normalize_math_alphanumeric_char('\u{210E}'), 'h');
    }

    /// Each block of Mathematical Alphanumeric Symbols maps to its ASCII base.
    /// Covers the BLOCKS loop and the `Self::Symbol(c)` style return.
    #[rstest::rstest]
    #[case::bold_capital_a('\u{1D400}', 'A')]
    #[case::bold_small_a('\u{1D41A}', 'a')]
    #[case::bold_digit_zero('\u{1D7CE}', '0')]
    #[case::passthrough_ascii('Z', 'Z')]
    fn normalize_math_alphanumeric_block_mapping(#[case] input: char, #[case] expected: char) {
        assert_eq!(normalize_math_alphanumeric_char(input), expected);
    }

    #[rstest::rstest]
    #[case::upper_one("Ⅰ", "I")]
    #[case::upper_two("Ⅱ", "II")]
    #[case::upper_seven("Ⅶ", "VII")]
    #[case::lower_four("ⅳ", "iv")]
    #[case::embedded("제Ⅲ장", "제III장")]
    fn normalizes_roman_numeral_presentation(#[case] input: &str, #[case] expected: &str) {
        assert_eq!(
            normalize_roman_numeral_presentation(Cow::Borrowed(input)),
            expected
        );
    }

    /// Rule 36 spells Roman numerals with Roman letters. Presentation forms must
    /// therefore enter the same existing encoder path in spaced, attached,
    /// particle-adjacent, and lower-case contexts.
    #[rstest::rstest]
    #[case::pdf_sentence(
        "가영이는 미적분학 Ⅱ 과목을 수강하고 있다.",
        "가영이는 미적분학 II 과목을 수강하고 있다."
    )]
    #[case::attached_chapter("제Ⅲ장", "제III장")]
    #[case::adjacent_particle("Ⅶ을", "VII을")]
    #[case::lowercase_indicator("ⅳ를", "iv를")]
    fn unicode_roman_numeral_matches_ascii_rule_36_path(
        #[case] presentation: &str,
        #[case] ascii: &str,
    ) {
        assert_eq!(encode_to_unicode(presentation), encode_to_unicode(ascii));
    }

    #[test]
    fn roman_numeral_normalization_leaves_other_nfkc_characters_unchanged() {
        let input = "ↀ㈜";
        assert_eq!(
            normalize_roman_numeral_presentation(Cow::Borrowed(input)),
            input
        );
    }

    #[rstest::rstest]
    #[case::parenthesized_jamo("㈀", "(ᄀ)")]
    #[case::parenthesized_syllable("㈎", "(가)")]
    #[case::incorporated_association("㈔", "(사)")]
    #[case::incorporated_company("㈜", "(주)")]
    #[case::afternoon("㈞", "(오후)")]
    fn normalizes_parenthesized_hangul_presentation(#[case] input: &str, #[case] expected: &str) {
        assert_eq!(
            normalize_parenthesized_hangul_presentation(Cow::Borrowed(input)),
            expected
        );
    }

    /// The compatibility glyph carries no independent braille semantics: its
    /// expanded print-equivalent must follow the ordinary Korean parenthesis
    /// and Hangul rules in every surrounding position.
    #[rstest::rstest]
    #[case::association_prefix("㈔한국", "(사)한국")]
    #[case::company_prefix("㈜한빛", "(주)한빛")]
    #[case::attached_company_suffix("한빛㈜", "한빛(주)")]
    fn parenthesized_hangul_presentation_matches_expanded_print(
        #[case] presentation: &str,
        #[case] expanded: &str,
    ) {
        assert_eq!(encode_to_unicode(presentation), encode_to_unicode(expanded));
    }

    #[test]
    fn normalizes_word_separator_middle_dot_to_print_space() {
        assert_eq!(
            normalize_word_separator_middle_dot(Cow::Borrowed("인증⸱실천⸱교육")),
            "인증 실천 교육"
        );
    }

    #[test]
    fn word_separator_middle_dot_matches_visible_word_spacing() {
        assert_eq!(
            encode_to_unicode("인증⸱실천⸱교육"),
            encode_to_unicode("인증 실천 교육")
        );
    }

    #[rstest::rstest]
    #[case::kilowatt_hour("㎾h", "kWh")]
    #[case::milli_sievert("m㏜", "mSv")]
    #[case::watt_per_kilogram("W/㎏", "W/kg")]
    #[case::kilogram_carbon_equivalent("㎏CO2eq", "kgCO2eq")]
    #[case::milligram_per_gram("㎎/g", "mg/g")]
    fn normalizes_pure_roman_compatibility_unit_components(
        #[case] input: &str,
        #[case] expected: &str,
    ) {
        assert_eq!(
            normalize_pure_roman_compatibility_units(Cow::Borrowed(input)),
            expected
        );
    }

    #[rstest::rstest]
    #[case::superscript("㎥")]
    #[case::quotient("㎧")]
    #[case::standalone_hectare("㏊")]
    #[case::non_unit_compatibility_abbreviation("㏚")]
    fn pure_roman_unit_normalization_preserves_other_compatibility_forms(#[case] input: &str) {
        assert_eq!(
            normalize_pure_roman_compatibility_units(Cow::Borrowed(input)),
            input
        );
    }

    /// Rule 69: a compatibility unit presentation and its semantic Roman
    /// spelling are one unit section even when joined to another component.
    #[rstest::rstest]
    #[case::kilowatt_hour("용량은 1㎾h이다", "용량은 1kWh이다")]
    #[case::milli_sievert("선량은 1m㏜보다 낮다", "선량은 1mSv보다 낮다")]
    #[case::watt_per_kilogram("기준은 4.0W/㎏이다", "기준은 4.0W/kg이다")]
    fn compound_compatibility_units_match_semantic_roman_spelling(
        #[case] presentation: &str,
        #[case] expanded: &str,
    ) {
        assert_eq!(
            encode_to_unicode(presentation),
            encode_to_unicode(expanded),
            "presentation={presentation:?}"
        );
    }

    #[test]
    fn normalize_math_alphanumeric_runtime_block_offset() {
        let input = std::hint::black_box('\u{1D44F}');

        assert_eq!(normalize_math_alphanumeric_char(input), 'b');
    }

    #[test]
    fn normalize_math_alphanumeric_runtime_digit_offset() {
        let input = std::hint::black_box('\u{1D7D9}');

        assert_eq!(normalize_math_alphanumeric_char(input), '1');
    }

    /// `normalize_math_alphanumeric_string` short-circuits when no trigger char
    /// is present (Cow::Borrowed) and otherwise allocates a new String (Cow::Owned).
    #[test]
    fn normalize_math_string_no_trigger() {
        let result = normalize_math_alphanumeric_string("plain ASCII");
        assert!(matches!(result, Cow::Borrowed(_)));
    }

    #[test]
    fn normalize_math_string_with_trigger() {
        // Contains U+1D400 → should allocate Owned variant
        let result = normalize_math_alphanumeric_string("X = \u{1D400}");
        assert!(matches!(result, Cow::Owned(_)));
        assert_eq!(result.as_ref(), "X = A");
    }

    #[test]
    fn encode_decomposes_runtime_accented_latin_when_triggered() {
        let input = std::hint::black_box("café");

        let encoded = encode_with_options(input, &EncodeOptions::default()).unwrap();

        assert_eq!(
            encoded,
            encode_with_options("cafe\u{301}", &EncodeOptions::default()).unwrap()
        );
    }

    /// Korean 제68항 — compact uppercase + subscript digit is Korean/math-owned by
    /// default, not UEB §3.24.  This protects both plain Unicode and LaTeX token
    /// forms from the English §9 styled-letter preflight.
    #[rstest::rstest]
    #[case::plain_subscript("B₆")]
    #[case::latex_subscript("$B_6$")]
    fn korean_rule68_compact_subscript_default_routes_to_korean(#[case] input: &str) {
        let expected = vec![52, 32, 3, 48, 60, 11];
        let plain = encode("B₆").unwrap();
        let encoded = encode(input).unwrap();
        assert_eq!(plain, expected);
        assert_eq!(encoded, plain);
    }

    /// `move_negation_combiner_before_base` early-returns when no U+0338 is
    /// present. Covers line 174-175.
    #[test]
    fn negation_combiner_absent_short_circuits() {
        let input: Cow<'_, str> = Cow::Borrowed("no combiner here");
        let result = move_negation_combiner_before_base(input);
        assert_eq!(result.as_ref(), "no combiner here");
    }

    /// ObjectSymbol mode dispatch — covers lines around 698-709.
    #[rstest::rstest]
    #[case::circle("○", &[56, 52, 7])]
    #[case::cross("×", &[56, 45, 7])]
    #[case::triangle("△", &[56, 44, 7])]
    #[case::square("□", &[56, 54, 7])]
    fn encode_object_symbol_mode_each_glyph(#[case] input: &str, #[case] expected: &[u8]) {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::ObjectSymbol),
        };
        assert_eq!(encode_with_options(input, &opts).unwrap(), expected);
    }

    /// ObjectSymbol mode with non-matching char falls through to normal pipeline.
    #[test]
    fn encode_object_symbol_mode_non_matching_falls_through() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::ObjectSymbol),
        };
        // 'A' is not an object symbol → should not error, falls through
        let result = encode_with_options("A", &opts);
        assert!(result.is_ok());
    }

    /// Number mode with Roman numerals (제36항).
    /// Covers lines 718-732 including the multi-uppercase double 大문자 표시.
    #[test]
    fn encode_number_mode_roman_uppercase() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Number),
        };
        // Single uppercase: ⠴ ⠠ <letter> ⠲
        let single = encode_with_options("I", &opts).unwrap();
        assert!(single.starts_with(&[52, 32]));
        assert!(single.ends_with(&[50]));
        // Multi uppercase: ⠴ ⠠ ⠠ <letters> ⠲
        let multi = encode_with_options("IV", &opts).unwrap();
        assert_eq!(multi[0], 52);
        assert_eq!(multi[1], 32);
        assert_eq!(multi[2], 32);
        assert_eq!(multi[multi.len() - 1], 50);
    }

    /// Number mode lowercase Roman skips the uppercase markers.
    #[test]
    fn encode_number_mode_roman_lowercase() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Number),
        };
        let result = encode_with_options("ix", &opts).unwrap();
        assert_eq!(result[0], 52); // ⠴
        assert_ne!(result[1], 32); // no 대문자 표시
        assert_eq!(result[result.len() - 1], 50); // ⠲
    }

    /// Number mode with non-Roman char falls through.
    #[test]
    fn encode_number_mode_non_roman_falls_through() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Number),
        };
        // Z is not Roman → falls through
        let result = encode_with_options("Z", &opts);
        assert!(result.is_ok());
    }

    /// Math mode — single lowercase variable (제12항).
    /// Covers lines 742-743.
    #[test]
    fn encode_math_mode_single_lowercase() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Math),
        };
        let result = encode_with_options("x", &opts).unwrap();
        assert_eq!(result[0], 52); // ⠴
        assert_eq!(result.len(), 2);
    }

    /// Math mode — single bracket character. Covers lines 750-756.
    #[test]
    fn encode_math_mode_single_brackets() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Math),
        };
        assert_eq!(encode_with_options("(", &opts).unwrap(), vec![38]);
        assert_eq!(encode_with_options(")", &opts).unwrap(), vec![52]);
        assert_eq!(encode_with_options("{", &opts).unwrap(), vec![54]);
        assert_eq!(encode_with_options("}", &opts).unwrap(), vec![54]);
        assert_eq!(encode_with_options("[", &opts).unwrap(), vec![55, 4]);
        assert_eq!(encode_with_options("]", &opts).unwrap(), vec![32, 62]);
    }

    /// Math mode — single math symbol via shortcut. Covers lines 765-768.
    #[test]
    fn encode_math_mode_single_math_symbol() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Math),
        };
        // '+' is in math_symbol_shortcut SHORTCUT_MAP
        let result = encode_with_options("+", &opts);
        assert!(result.is_ok());
    }

    /// 수학 제32·33항: 수학 전용 관계 기호 양쪽의 대문자는 하나의 수식
    /// 안의 변수다. 뒤쪽 변수를 국어 로마자 연속 항목으로 보아 ⠰를 붙이지 않는다.
    #[rstest::rstest]
    #[case::congruence("A ≅ B", "⠠⠁⠀⠈⠔⠒⠒⠀⠠⠃")]
    #[case::right_geometric_operation("G ▷ N", "⠠⠛⠀⠸⠜⠀⠠⠝")]
    #[case::left_geometric_operation("N ◁ G", "⠠⠝⠀⠸⠣⠀⠠⠛")]
    fn default_route_keeps_math_relation_operands_in_one_expression(
        #[case] input: &str,
        #[case] expected: &str,
    ) {
        assert_eq!(encode_to_unicode(input).as_deref(), Ok(expected));
    }

    /// Math mode — multi-char expression with spaces around operators.
    /// Covers the whitespace-cleaning loop (lines 777-790).
    #[test]
    fn encode_math_mode_multichar_strips_spaces() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Math),
        };
        let a = encode_with_options("x = y", &opts).unwrap();
        let b = encode_with_options("x=y", &opts).unwrap();
        assert_eq!(a, b, "Spaces around '=' must be stripped in math mode");
        // Same for '+'
        let c = encode_with_options("a + b", &opts).unwrap();
        let d = encode_with_options("a+b", &opts).unwrap();
        assert_eq!(c, d);
    }

    /// `encode_with_options` with default_mode != Korean. Covers lines 805-806.
    #[test]
    fn encode_with_options_explicit_default_mode() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::English),
        };
        let result = encode_with_options("hello", &opts);
        assert!(result.is_ok());
    }

    /// 제37항 — 국어 점자 문맥(Korean mode)에서 고립된 로마자 단어/구절은 로마자표
    /// ⠴(52)로 시작하고 종료표 ⠲(50)로 끝난다. 반면 제69항 단위표 `%p`는 로마자
    /// 구간이 아니므로 종료표로 감싸지 않는다.
    #[test]
    fn korean_context_wraps_isolated_roman_section() {
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Korean),
        };
        let wrapped = encode_with_options("but", &opts).unwrap();
        assert_eq!(
            wrapped.first(),
            Some(&52),
            "고립 로마자는 로마자표 ⠴로 시작"
        );
        assert_eq!(wrapped.last(), Some(&50), "고립 로마자는 종료표 ⠲로 끝남");

        let phrase = encode_with_options("Table of Contents", &opts).unwrap();
        assert_eq!(phrase.first(), Some(&52));
        assert_eq!(phrase.last(), Some(&50));

        let unit = encode_with_options("%p", &opts).unwrap();
        assert_ne!(unit.last(), Some(&50), "%p(제69항)는 종료표로 감싸지 않음");
    }

    /// `is_isolated_roman_section` — 공백 제외 전부 알파벳이면 true,
    /// 비알파벳 혼입/빈 입력/공백만은 false.
    #[rstest::rstest]
    #[case::word("but", true)]
    #[case::phrase_with_spaces("Table of Contents", true)]
    #[case::percent_unit("%p", false)]
    #[case::has_digit("abc123", false)]
    #[case::empty("", false)]
    #[case::only_space(" ", false)]
    fn is_isolated_roman_section_paths(#[case] input: &str, #[case] expected: bool) {
        assert_eq!(is_isolated_roman_section(input), expected);
    }

    /// `encode_with_formatting` with empty spans delegates to plain `encode`.
    /// Covers line 819-820.
    #[test]
    fn encode_with_formatting_empty_spans_delegates() {
        let plain = encode("hello").unwrap();
        let formatted = encode_with_formatting("hello", &[]).unwrap();
        assert_eq!(plain, formatted);
    }

    /// `encode_to_braille_font` is the unicode wrapper. Covers lines 843-845.
    #[test]
    fn encode_to_braille_font_basic() {
        let result = encode_to_braille_font("a").unwrap();
        assert!(!result.is_empty());
        // Must be valid Braille Unicode
        for ch in result.chars() {
            let cp = ch as u32;
            assert!((0x2800..=0x28FF).contains(&cp), "non-braille char {:?}", ch);
        }
    }

    /// `encode_to_unicode_with_formatting` empty spans path.
    #[test]
    fn encode_to_unicode_with_formatting_empty() {
        let result = encode_to_unicode_with_formatting("a", &[]).unwrap();
        assert!(!result.is_empty());
    }

    /// `detect_ipa_context` should return false for text without IPA markers.
    /// `detect_ipa_context` — `[…]` 또는 `/…/` 내부의 IPA 음성 기호 검출.
    /// `no_markers`: 마커 자체가 없음 (line 491).
    /// `brackets_ipa`: `[ ]` 안에 IPA.
    /// `brackets_without_ipa_then_slashes_ipa`: 첫 `[…]`은 무관, 이후 `/…/` 매치 (lines 504-505).
    /// `slashes_with_ipa`: `/…/` 안에 IPA (lines 508-513).
    #[rstest::rstest]
    #[case::no_markers("plain text", false)]
    #[case::brackets_ipa("[əbaut]", true)]
    #[case::brackets_without_ipa_then_slashes_ipa("[abc] /əb/", true)]
    #[case::slashes_with_ipa("/əb/", true)]
    fn detect_ipa_context_variants(#[case] input: &str, #[case] expected: bool) {
        assert_eq!(detect_ipa_context(input), expected, "input={input:?}");
    }

    /// `detect_ipa_context` slash group without IPA continues scanning.
    /// Covers lines 514-515 then final return false on line 522.
    #[test]
    fn detect_ipa_context_slashes_without_ipa() {
        // The text has '/' delimiters AND a phonetic char, but the phonetic
        // char is OUTSIDE all delimited groups. Each delimited group is empty
        // → continues past 514-515 to fall through to line 522 (`false`).
        // Note: function needs has_group_start AND has_ipa_symbol both true to
        // proceed past line 490; we provide both via // (group start, empty)
        // and a phonetic symbol elsewhere.
        let s = "abc // \u{0259} xyz";
        let _ = detect_ipa_context(s);
    }

    /// Comprehensive LaTeX coverage sweep — exercises many code paths in
    /// latex_math.rs / math/encoder.rs / math/parser.rs / math_expression.rs
    /// through a wide variety of LaTeX inputs. Each call must succeed.
    #[test]
    fn latex_math_comprehensive_sweep() {
        let inputs: &[&str] = &[
            // Plain math, no LaTeX
            "1+2",
            "x = 1",
            "a + b - c",
            "x \\times y",
            // Single-dollar inline LaTeX
            "$x$",
            "$x = 1$",
            "$x + y$",
            "$\\frac{1}{2}$",
            "$\\frac{a+b}{c-d}$",
            "$x^2$",
            "$x^{n+1}$",
            "$x_n$",
            "$x_{i+1}$",
            "$\\sqrt{2}$",
            "$\\sqrt[3]{x}$",
            "$\\sum_{i=1}^{n} i$",
            "$\\int_0^1 f(x) dx$",
            "$\\lim_{x \\to 0} f(x)$",
            "$f(x) = x^2 + 1$",
            "$y \\neq 0$",
            "$x \\geq 0$",
            "$x \\leq 1$",
            // Logical and set operators
            "$A \\cup B$",
            "$A \\cap B$",
            "$A \\subset B$",
            "$\\emptyset$",
            "$\\forall x$",
            "$\\exists y$",
            // Greek letters
            "$\\alpha$",
            "$\\beta$",
            "$\\pi$",
            "$\\theta$",
            // Multi-dollar across spaces (LatexMergeRule)
            "$x + $ $y$",
            "1 + $x$ = 2",
            // Multi-dollar in a single word
            "$x$ and $y$",
            // Functions
            "$\\sin x$",
            "$\\cos x$",
            "$\\log x$",
            "$\\ln x$",
            // Matrix
            "$\\begin{matrix} 1 & 2 \\\\ 3 & 4 \\end{matrix}$",
            "$\\begin{pmatrix} a & b \\\\ c & d \\end{pmatrix}$",
            "$\\begin{bmatrix} 1 \\\\ 2 \\end{bmatrix}$",
            "$\\begin{array}{cc} x & y \\\\ z & w \\end{array}$",
            // Mixed Korean + LaTeX
            "수식 $x + 1$ 입니다",
            "함수 $f(x)$",
            // Subscript variants
            "$a_1$",
            "$a_{12}$",
            "$x_n y_n$",
            // Superscript variants
            "$x^2 + y^2$",
            "$2^{10}$",
            // Combined
            "$x_i^j$",
            "$a^b_c$",
            // Math without LaTeX delimiters
            "1+2=3",
            "10×5=50",
            "x/y",
            // Comparison operators
            "1<2",
            "3>2",
            "x≥0",
            // Fraction inputs that may trigger inline fraction rule
            "1/2",
            "3/4 cup",
            "x1/2y",
            // LaTeX with brackets
            "$(x+y)$",
            "$[a,b]$",
            "$\\{x | x > 0\\}$",
            // Empty $$ pair
            "$$",
            // Unclosed (defensive)
            "$x = ",
        ];
        for input in inputs {
            // Each input MUST succeed without panicking.
            let _ = encode(input);
            // Also exercise unicode variant.
            let _ = encode_to_unicode(input);
        }
    }

    /// Math mode encoding sweep — covers math/encoder + math/parser paths.
    #[test]
    fn math_mode_comprehensive_sweep() {
        let inputs: &[&str] = &[
            "1+2", "x=1", "a+b-c", "x*y", "x/y", "(a+b)", "{c}", "[d]", "x^2", "x_n", "x≥0", "y≤1",
            "a≠b", "+", "-", "*", "/", "=", "<", ">", "≠", "≥", "≤", "π", "α", "β", "∞", "∂",
            "f(x)", "1 + 2", // spaces
            "x = y",
        ];
        let opts = EncodeOptions {
            default_mode: Some(EncodingMode::Math),
        };
        for input in inputs {
            let _ = encode_with_options(input, &opts);
        }
    }

    /// lib.rs:348 — combining-mark wrap absorbs leading digits/commas/periods.
    /// Input has digits + Korean syllable + combining mark above (U+0307 드러냄표).
    /// The wrap walks back through the Korean unit, then absorbs the preceding digits.
    #[test]
    fn formatting_mark_wrap_absorbs_leading_digits() {
        // "5강\u{0307}" — 1 combining mark, 1 Korean unit, leading digit "5".
        // After consuming 강 as the unit, the algorithm walks back to absorb '5'.
        let _ = encode("5강\u{0307}");
        // With comma and period interspersed.
        let _ = encode("1,000원\u{0307}");
        let _ = encode("3.14를\u{0307}");
    }

    /// lib.rs:357-358 — combining mark count exceeds available units,
    /// algorithm preserves the marks as-is (no wrap).
    #[test]
    fn formatting_mark_preserved_when_units_insufficient() {
        // Korean syllable followed by MORE combining marks than there are units.
        // "한\u{0307}\u{0307}\u{0307}\u{0307}" — 4 marks, only 1 Korean unit → units < count → preserve.
        let _ = encode("한\u{0307}\u{0307}\u{0307}\u{0307}");
        // 2 Korean units, 5 marks: units=2 < count=5 → preserve.
        let _ = encode("한글\u{0307}\u{0307}\u{0307}\u{0307}\u{0307}");
        // No-Korean-in-token preserves via earlier branch, but with Korean elsewhere
        // in the document the token_has_korean flag may still trigger.
        let _ = encode("\u{0307}\u{0307}");
    }

    /// lib.rs:492 — `decompose_accented_latin` early-return when no accented chars.
    /// Reached via direct encode() of plain ASCII or Korean input. The
    /// has_decomposable_latin flag triggers the call but the inner re-check
    /// against may_decompose_accented_latin returns false → early Cow return.
    /// This branch is structurally defensive (the scan triggers when at least one
    /// char is decomposable, and the inner check uses the same predicate, so the
    /// inner check should always be true). The branch is preserved as a no-op
    /// defensive guard against trigger-scan drift; we exercise it via plain input
    /// which goes through the `else` arm (no call to decompose_accented_latin).
    #[test]
    fn decompose_accented_latin_not_called_for_plain_input() {
        // Plain Korean: no accented latin chars → has_decomposable_latin = false →
        // function is NOT called. The else-branch (line 530-532) is taken.
        let _ = encode("안녕하세요");
        let _ = encode("hello");
    }

    /// lib.rs:495, 529 — `decompose_accented_latin` is called and produces output
    /// when input contains an accented Latin char (e.g. é, ñ, ã).
    #[test]
    fn decompose_accented_latin_called_for_accented_input() {
        // 'é' U+00E9 — Latin-1 Supplement, decomposable to 'e' + U+0301.
        // has_decomposable_latin = true → line 529 hits, function called.
        let _ = encode(std::hint::black_box("café"));
        // 'ñ' U+00F1 decomposes to 'n' + U+0303.
        let _ = encode(std::hint::black_box("piñata"));
        // 'ã' U+00E3 decomposes to 'a' + U+0303.
        let _ = encode(std::hint::black_box("ão"));
    }

    #[test]
    fn decompose_accented_latin_directly_expands_latin_marks() {
        assert_eq!(
            decompose_accented_latin(Cow::Borrowed("café Å")),
            Cow::<str>::Owned("cafe\u{0301} Å".to_string())
        );
    }

    #[test]
    fn default_mode_routes_styled_english_and_inline_nemeth_to_ueb() {
        assert!(encode("𝐡𝐢𝐬 𝐡𝐞𝐫𝐬 𝐢𝐭𝐬").is_ok());
        assert!(encode("solve $x+1$ now").is_ok());
    }

    /// lib.rs:147 — Math Alphanumeric DIGIT blocks (𝟎-𝟗 across 5 styles) normalize
    /// to ASCII '0'-'9'. The DIGIT_BLOCKS loop returns at line 147 for matching codepoints.
    /// lib.rs:147 — Math Alphanumeric DIGIT blocks (𝟎-𝟯 across 5 styles) normalize
    /// to ASCII '0'-'9'. DIGIT_BLOCKS 의 각 base에서 ZERO offset 확인.
    #[rstest::rstest]
    #[case::bold_zero('\u{1D7CE}', '0')]
    #[case::bold_one('\u{1D7CF}', '1')]
    #[case::bold_nine('\u{1D7D7}', '9')]
    #[case::double_struck_zero('\u{1D7D8}', '0')]
    #[case::sans_serif_zero('\u{1D7E2}', '0')]
    #[case::sans_serif_bold_zero('\u{1D7EC}', '0')]
    #[case::monospace_zero('\u{1D7F6}', '0')]
    #[case::monospace_nine('\u{1D7FF}', '9')]
    fn normalize_math_alphanumeric_digits(#[case] input: char, #[case] expected: char) {
        assert_eq!(
            normalize_math_alphanumeric_char(std::hint::black_box(input)),
            expected
        );
    }

    #[test]
    fn encode_normalizes_math_alphanumeric_digit_blocks() {
        assert!(encode(std::hint::black_box("𝟘+𝟙=𝟙")).is_ok());
    }

    #[rstest::rstest]
    #[case::bold_capital_a('\u{1D400}', 'A')]
    #[case::bold_lower_a('\u{1D41A}', 'a')]
    #[case::italic_lower_h('\u{210E}', 'h')]
    fn normalize_math_alphanumeric_letters(#[case] input: char, #[case] expected: char) {
        assert_eq!(normalize_math_alphanumeric_char(input), expected);
    }

    #[test]
    fn may_normalize_math_alphanumeric_detects_supported_ranges() {
        assert!(may_normalize_math_alphanumeric('\u{210E}'));
        assert!(may_normalize_math_alphanumeric('\u{1D400}'));
        assert!(!may_normalize_math_alphanumeric('A'));
    }
}

#[cfg(test)]
mod debug_reader {
    use crate::rules::english_ueb;
    #[test]
    fn debug_reader() {
        for input in ["reader", "READER", "READER'S", "(READER'S DIGEST)"] {
            if let Some(result) = english_ueb::try_encode(input) {
                let unicode: String = result
                    .iter()
                    .map(|c| crate::unicode::encode_unicode(*c))
                    .collect();
                eprintln!("[{}] result: {:?}", input, result);
                eprintln!("[{}] unicode: {}", input, unicode);
            } else {
                eprintln!("[{}] returned None", input);
            }
        }
    }
}

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

    #[rstest::rstest]
    #[case::celsius("25\u{00B0}C", "25\u{2103}")]
    #[case::fahrenheit("77\u{00B0}F", "77\u{2109}")]
    #[case::ring_celsius("25\u{02DA}C", "25\u{2103}")]
    #[case::ring_fahrenheit("77\u{02DA}F", "77\u{2109}")]
    #[case::letter_without_a_degree("25C", "25C")]
    #[case::degree_at_the_end("25\u{00B0}", "25\u{00B0}")]
    #[case::degree_before_another_letter("25\u{00B0}K", "25\u{00B0}K")]
    fn degree_letter_pair_folds_to_the_unit_glyph(#[case] input: &str, #[case] expected: &str) {
        assert_eq!(
            normalize_print_variants(std::borrow::Cow::Borrowed(input)).as_ref(),
            expected
        );
    }

    #[rstest::rstest]
    #[case::fullwidth_percent('\u{FF05}', true)]
    #[case::fullwidth_letter('\u{FF4D}', true)]
    #[case::fullwidth_hash_is_the_math_cardinal('\u{FF03}', false)]
    #[case::fullwidth_colon_is_the_old_hangul_mark('\u{FF1A}', false)]
    #[case::ascii_is_not_a_variant('m', false)]
    fn fullwidth_folding_excludes_the_two_reserved_glyphs(
        #[case] input: char,
        #[case] expected: bool,
    ) {
        assert_eq!(is_foldable_fullwidth(input), expected);
    }

    #[rstest::rstest]
    #[case::before_slash("\u{338F}/h")]
    #[case::after_slash("h/\u{338F}")]
    fn a_square_unit_joined_through_a_slash_decomposes(#[case] input: &str) {
        let folded = normalize_pure_roman_compatibility_units(std::borrow::Cow::Borrowed(input));
        assert!(
            folded.contains("kg"),
            "expected the unit to spell out, got {folded:?}"
        );
    }

    #[test]
    fn a_detached_square_unit_keeps_its_glyph() {
        let folded =
            normalize_pure_roman_compatibility_units(std::borrow::Cow::Borrowed("\u{338F}"));
        assert_eq!(folded.as_ref(), "\u{338F}");
    }
}

#[cfg(test)]
mod print_variant_fold_coverage {
    use super::*;
    use std::borrow::Cow;

    /// 제49·50·61·69항 + 수학 제65항: 규정이 이미 점형을 정한 문자의 활자체·호환
    /// 표기는 그 문자로 접어 적고, 보이지 않는 문자는 버린다.
    #[rstest::rstest]
    #[case::ring_above_alone("\u{02DA}", "\u{00B0}")]
    #[case::unicode_hyphen("\u{2010}", "-")]
    #[case::non_breaking_hyphen("\u{2011}", "-")]
    #[case::katakana_middle_dot("\u{30FB}", "\u{00B7}")]
    #[case::halfwidth_middle_dot("\u{FF65}", "\u{00B7}")]
    #[case::hyphenation_point("\u{2027}", "\u{00B7}")]
    #[case::one_dot_leader("\u{2024}", "\u{00B7}")]
    #[case::vector_cross("\u{2A2F}", "\u{00D7}")]
    #[case::parenthesised_five("\u{2478}", "(5)")]
    #[case::parenthesised_twenty("\u{2487}", "(20)")]
    #[case::wave_dash("\u{301C}", "~")]
    #[case::acute_accent("\u{00B4}", "'")]
    #[case::soft_hyphen("\u{00AD}", "")]
    #[case::zero_width_space("\u{200B}", "")]
    #[case::zero_width_joiner("\u{200D}", "")]
    #[case::byte_order_mark("\u{FEFF}", "")]
    #[case::fullwidth_percent("\u{FF05}", "%")]
    #[case::fullwidth_letter("\u{FF4D}", "m")]
    #[case::plain_char_is_kept("m", "m")]
    fn a_print_variant_folds_to_the_character_the_standard_defines(
        #[case] input: &str,
        #[case] expected: &str,
    ) {
        assert_eq!(
            normalize_print_variants(Cow::Borrowed(input)).as_ref(),
            expected
        );
    }

    #[rstest::rstest]
    #[case::celsius("25\u{00B0}C", "25\u{2103}")]
    #[case::fahrenheit("77\u{00B0}F", "77\u{2109}")]
    #[case::letter_without_a_degree("25C", "25C")]
    #[case::degree_at_the_end("25\u{00B0}", "25\u{00B0}")]
    fn a_degree_letter_pair_folds_to_the_unit_glyph(#[case] input: &str, #[case] expected: &str) {
        assert_eq!(
            normalize_print_variants(Cow::Borrowed(input)).as_ref(),
            expected
        );
    }

    /// 전화 기호는 묵자의 뜻대로 `Tel` 로 적는다.
    #[rstest::rstest]
    #[case::black_telephone("\u{260E}051", "Tel051")]
    #[case::white_telephone("\u{260F}051", "Tel051")]
    #[case::other_char_is_kept("051", "051")]
    fn a_telephone_sign_expands_to_its_printed_meaning(
        #[case] input: &str,
        #[case] expected: &str,
    ) {
        assert_eq!(expand_pictographs(Cow::Borrowed(input)).as_ref(), expected);
    }

    #[rstest::rstest]
    #[case::before_slash("\u{338F}/h")]
    #[case::after_slash("h/\u{338F}")]
    fn a_square_unit_joined_through_a_slash_decomposes(#[case] input: &str) {
        let folded = normalize_pure_roman_compatibility_units(Cow::Borrowed(input));
        assert!(folded.contains("kg"), "expected kg in {folded:?}");
    }

    #[test]
    fn a_detached_square_unit_keeps_its_glyph() {
        assert_eq!(
            normalize_pure_roman_compatibility_units(Cow::Borrowed("\u{338F}")).as_ref(),
            "\u{338F}"
        );
    }
}