yggdrasil/api/

katex.rs

//! KaTeX 服务端数学公式渲染。
//!
//! 用纯 Rust 的 [`katex`](https://crates.io/crates/katex-rs) crate 把 TeX 公式
//! 渲染成 HTML span，供 pulldown-cmark 的 `InlineMath` / `DisplayMath` 事件调用。
//! 仅在 `feature = "server"` 时编译——前端 WASM 不参与公式渲染（SSR 即终态）。
//!
//! 渲染策略：
//! - `OutputFormat::Html`：只产出视觉层 `<span class="katex">…</span>`，不含 MathML
//!   语义层（`<math>` 等）。这样 sanitizer 无需为 MathML 标签开白名单，XSS 面最小。
//!   屏幕阅读器等无障碍场景的语义损失可接受（本站数学公式占比低）。
//! - `throw_on_error = false`：坏公式渲染成红色错误 span 而非中断整篇文章。
//!
//! 配套资源：前端必须加载 `public/katex/katex.min.css` + `fonts/`（见 Makefile
//! `katex-css`），否则只有裸 span、无数学字体排版。crate 本身不打包 CSS。

#![cfg(feature = "server")]

use std::borrow::Cow;

use katex::macros::MacroDefinition;
use katex::{KatexContext, OutputFormat, Settings};

/// 物理学常用宏表（对齐 LaTeX `physics` 宏包 + 项目文档 8.13 节「项目物理宏表」）。
///
/// `katex-rs` 默认 `Settings` 无物理宏表，导致 `\vu \dv \dd \pdv \divg \curl \grad`
/// `\qty \RR \ZZ \NN \QQ \CC \bra \ket \braket \expval \abs \norm` 等渲染为红字
/// （实测正确页面 648 的 137 个公式中 48 处物理宏坏掉）。这里把它们注册为简单
/// 字符串宏（[`MacroDefinition::StaticStr`]），crate 的 `string_to_expansion` 会自动
/// 从 `#1`/`#2` 推导参数个数。
///
/// 刻意差异：`\divg`（散度）**不**覆写内置 `\div`（除号 ÷）——文档 8.13 明确两者并存。
/// `\bra`/`\ket`/`\braket` 虽是 katex 内置宏，但内置 `\braket` 只吃 1 个参数
/// （`\langle{#1}\rangle`），物理语义需 2 个参数（`\langle #1 | #2 \rangle`），
/// 故覆写为物理版本。
///
/// `\qty(...)` / `\qty[...]` 的定界符配对无法用纯字符串宏表达，由渲染前的
/// [`expand_qty`] 预转译；这里注册的是花括号形式 `\qty{...}`。
fn physics_macros() -> &'static [(&'static str, MacroDefinition)] {
    &[
        // 数集
        (r"\RR", MacroDefinition::StaticStr(r"\mathbb{R}")),
        (r"\ZZ", MacroDefinition::StaticStr(r"\mathbb{Z}")),
        (r"\NN", MacroDefinition::StaticStr(r"\mathbb{N}")),
        (r"\QQ", MacroDefinition::StaticStr(r"\mathbb{Q}")),
        (r"\CC", MacroDefinition::StaticStr(r"\mathbb{C}")),
        // 微积分：微分与偏导。`\dd` 不带参数：physics 的花括号参数是可选的，
        // `\frac{\dd}{\dd{t}}` 里的裸 `\dd` 若声明 `#1` 会吞掉 `}` 让整个公式报错；
        // `\dd{x}` 照样展开成 `\mathrm{d}{x}`。
        (r"\dd", MacroDefinition::StaticStr(r"\mathrm{d}")),
        (
            r"\dv",
            MacroDefinition::StaticStr(r"\frac{\mathrm{d}#1}{\mathrm{d}#2}"),
        ),
        (
            r"\pdv",
            MacroDefinition::StaticStr(r"\frac{\partial #1}{\partial #2}"),
        ),
        // 场算子：grad/divg/curl（divg 刻意不复用 \div）
        (r"\grad", MacroDefinition::StaticStr(r"\nabla")),
        (r"\divg", MacroDefinition::StaticStr(r"\nabla \cdot")),
        (r"\curl", MacroDefinition::StaticStr(r"\nabla \times")),
        // 量子力学 Dirac 记号
        (r"\bra", MacroDefinition::StaticStr(r"\langle #1 |")),
        (r"\ket", MacroDefinition::StaticStr(r"| #1 \rangle")),
        (
            r"\braket",
            MacroDefinition::StaticStr(r"\langle #1 | #2 \rangle"),
        ),
        (
            r"\expval",
            MacroDefinition::StaticStr(r"\langle #1 \rangle"),
        ),
        // 向量 / 范数 / 绝对值（自动缩放定界符）
        (r"\abs", MacroDefinition::StaticStr(r"\left| #1 \right|")),
        (r"\norm", MacroDefinition::StaticStr(r"\left\| #1 \right\|")),
        // 单位向量：带帽子
        (r"\vu", MacroDefinition::StaticStr(r"\hat{\vec{#1}}")),
        // 自动缩放圆括号（花括号形式；`\qty(...)` 由 `expand_qty` 预转译）
        (r"\qty", MacroDefinition::StaticStr(r"\left( #1 \right)")),
    ]
}

/// mhchem 键（`\bond{~}` 等）引用的宏，定义取自 KaTeX `contrib/mhchem`。
fn mhchem_macros() -> &'static [(&'static str, MacroDefinition)] {
    &[(
        r"\tripledash",
        MacroDefinition::StaticStr(
            r"{\vphantom{-}\raisebox{2.56mu}{$\mkern2mu\tiny\text{-}\mkern1mu\text{-}\mkern1mu\text{-}\mkern2mu$}}",
        ),
    )]
}

/// 把物理宏表与 mhchem 辅助宏注入到给定 `Settings` 的宏表（覆盖同名内置宏）。
fn inject_macros(settings: &mut Settings) {
    let mut map = settings.macros.borrow_mut();
    for (name, def) in physics_macros().iter().chain(mhchem_macros()) {
        map.insert((*name).to_string(), def.clone());
    }
}

/// 内联公式（`$...$`）渲染配置工厂：`display_mode = false`，含物理宏表。
fn inline_settings() -> Settings {
    let mut s = Settings {
        output: OutputFormat::Html,
        display_mode: false,
        throw_on_error: false,
        ..Settings::default()
    };
    inject_macros(&mut s);
    s
}

/// 块级公式（`$$...$$`）渲染配置工厂：`display_mode = true`（居中独占一行），含物理宏表。
fn display_settings() -> Settings {
    let mut s = Settings {
        output: OutputFormat::Html,
        display_mode: true,
        throw_on_error: false,
        ..Settings::default()
    };
    inject_macros(&mut s);
    s
}

thread_local! {
    /// KaTeX 上下文：含全部内置符号 / 宏表，应在多次渲染间复用（README 建议）。
    /// 用 thread_local 而非全局 static：`KatexContext` 内含 `RefCell<HashMap>`
    /// 宏表，非 `Sync`，不能放 `LazyLock`。tokio 多线程 runtime 下每线程各持一份。
    static KATEX_CTX: KatexContext = KatexContext::default();

    /// 每线程缓存的渲染配置，避免每次渲染都重建宏表 HashMap。
    /// `Settings` 同样因 `RefCell` 宏表非 `Sync`。
    static INLINE_SETTINGS: Settings = inline_settings();
    static DISPLAY_SETTINGS: Settings = display_settings();
}

/// 把公式中的 `\ce{...}` / `\pu{...}` 预转译为标准 LaTeX（mhchem）。
///
/// `katex-rs` 无 mhchem 解析器，化学公式渲染为红字。这里在渲染前扫描 `\ce`/`\pu`
/// 调用，用嵌套花括号配对读取参数（支持 `\ce{[Cu(NH3)4]^2+}` 这类含 `{}` 的内容），
/// 转译后替换原 `\ce{...}`，其余文本原样拼接。未闭合 `\ce{` 保留原样（让 katex
/// 报红，符合容错设计）。无 `\ce`/`\pu` 时零成本原样返回。
fn expand_chem(tex: &str) -> String {
    // 快速路径：绝大多数公式不含化学公式，避免分配。
    if !tex.contains(r"\ce") && !tex.contains(r"\pu") {
        return tex.to_string();
    }
    let mut out = String::with_capacity(tex.len());
    let mut rest = tex;
    loop {
        // 找下一个 `\ce` 或 `\pu`，取较早出现者（两者均为 3 字节 ASCII）。
        let ce = rest.find(r"\ce");
        let pu = rest.find(r"\pu");
        let next = match (ce, pu) {
            (None, None) => None,
            (Some(a), None) => Some((a, false)),
            (None, Some(b)) => Some((b, true)),
            (Some(a), Some(b)) => Some(if a <= b { (a, false) } else { (b, true) }),
        };
        match next {
            None => {
                // 命令之后再无 `\ce`/`\pu`：原样拷贝剩余文本。
                out.push_str(rest);
                return out;
            }
            Some((pos, is_pu)) => {
                // C2 修复：拷贝命令前的原文用 `push_str(&str 切片)`，
                // 而非旧的逐字节 `bytes[i] as char`（Latin-1 转换会破坏多字节 UTF-8，
                // 如 `\text{浓度} \ce{H2O}` 里的中文）。
                out.push_str(&rest[..pos]);
                let bytes = rest.as_bytes();
                // `\ce` 与 `\pu` 均为 3 字节，`{` 紧随其后（C1 修复：旧代码 `\pu` 误用 i+4，
                // 实际 `{` 在 i+3，导致 `\pu` 永不匹配、mhchem::pu 从不触发）。
                let after_cmd = pos + 3;
                // 精确匹配命令边界：\ce/\pu 后须紧跟 `{`（否则可能是 \cellbox 之类）。
                if after_cmd < bytes.len() && bytes[after_cmd] == b'{' {
                    // read_braced 按字节索引扫描，仅计数 ASCII `{`/`}`；
                    // 花括号配对不会跨多字节字符边界，返回的切片落在字符边界上，UTF-8 安全。
                    if let Some((content, close_end)) = read_braced(rest, after_cmd) {
                        let translated = if is_pu {
                            crate::api::mhchem::pu(content)
                        } else {
                            crate::api::mhchem::ce(content)
                        };
                        out.push_str(&translated);
                        rest = &rest[close_end..];
                        continue;
                    }
                    // 未闭合 `{`：原样输出剩余，交由 katex 报红。
                    out.push_str(&rest[after_cmd..]);
                    return out;
                } else {
                    // 命令后非 `{`：保留命令字面量，从其后再扫。
                    out.push_str(&rest[pos..after_cmd]);
                    rest = &rest[after_cmd..];
                    continue;
                }
            }
        }
    }
}

/// 把 physics 宏包的定界符形式 `\qty(...)` / `\qty[...]` 预转译为
/// `\left(...\right)` / `\left[...\right]`。
///
/// 宏表里的 `\qty` 只能吃花括号参数：`\qty(\dfrac{a}{b})` 会把 `(` 当成 `#1`，
/// 渲染成「(()a/b)」且不报红字。这里按 TeX 记号扫描：控制序列整体跳过（`\\qty`
/// 不算、`\(` 不计数），只在同一花括号层级内配对同种括号，嵌套的 `\qty(` 各自替换。
/// 括号不闭合的保留原文（与 katex 报错容错一致）。`\qty{...}` 仍走宏表。
fn expand_qty(tex: &str) -> Cow<'_, str> {
    if !tex.contains(r"\qty") {
        return Cow::Borrowed(tex);
    }
    let bytes = tex.as_bytes();
    // (起, 止, 替换文本)：开头替换 `\qty(`（含中间空白），结尾替换配对的 `)`。
    let mut edits: Vec<(usize, usize, &'static str)> = Vec::new();
    let mut i = 0;
    while i < bytes.len() {
        if bytes[i] != b'\\' {
            i += 1;
            continue;
        }
        let name_start = i + 1;
        let name_end = control_sequence_end(bytes, name_start);
        if &bytes[name_start..name_end] == b"qty" {
            let mut open = name_end;
            while open < bytes.len() && bytes[open].is_ascii_whitespace() {
                open += 1;
            }
            let pair = match bytes.get(open) {
                Some(b'(') => Some((b'(', b')', r"\left(", r"\right)")),
                Some(b'[') => Some((b'[', b']', r"\left[", r"\right]")),
                _ => None,
            };
            if let Some((open_ch, close_ch, left, right)) = pair {
                if let Some(close) = find_matching_delimiter(bytes, open, open_ch, close_ch) {
                    edits.push((i, open + 1, left));
                    edits.push((close, close + 1, right));
                }
            }
        }
        // 从控制序列之后继续扫描，括号内容里的嵌套 `\qty(` 也会被找到。
        i = name_end;
    }
    if edits.is_empty() {
        return Cow::Borrowed(tex);
    }
    edits.sort_unstable_by_key(|&(start, _, _)| start);
    let mut out = String::with_capacity(tex.len() + edits.len() * 4);
    let mut copied = 0;
    for (start, end, replacement) in edits {
        // 替换边界都落在 ASCII 字节上，切片不会截断多字节 UTF-8。
        out.push_str(&tex[copied..start]);
        out.push_str(replacement);
        copied = end;
    }
    out.push_str(&tex[copied..]);
    Cow::Owned(out)
}

/// 控制序列名的结束位置：`start` 指向 `\` 之后。字母串是控制词，否则是单字符控制符。
fn control_sequence_end(bytes: &[u8], start: usize) -> usize {
    match bytes.get(start) {
        Some(b) if b.is_ascii_alphabetic() => {
            let mut end = start;
            while end < bytes.len() && bytes[end].is_ascii_alphabetic() {
                end += 1;
            }
            end
        }
        // 非 ASCII 控制符只跳过首字节；续字节 ≥ 0x80，不会被当成定界符。
        Some(_) => start + 1,
        None => start,
    }
}

/// 从 `open`（指向开括号）找同一花括号层级内配对的闭括号位置；先遇到外层 `}` 或到结尾返回 `None`。
fn find_matching_delimiter(bytes: &[u8], open: usize, open_ch: u8, close_ch: u8) -> Option<usize> {
    let mut depth = 0usize;
    let mut braces = 0usize;
    let mut i = open;
    while i < bytes.len() {
        match bytes[i] {
            b'\\' => {
                i = control_sequence_end(bytes, i + 1);
                continue;
            }
            b'{' => braces += 1,
            b'}' => braces = braces.checked_sub(1)?,
            c if braces == 0 && c == open_ch => depth += 1,
            c if braces == 0 && c == close_ch => {
                depth -= 1;
                if depth == 0 {
                    return Some(i);
                }
            }
            _ => {}
        }
        i += 1;
    }
    None
}

/// 从 `open`（指向 `{`）读取配对花括号内容，返回 `(内容, 闭括号后位置)`。
/// 不闭合返回 `None`。嵌套 `{}` 正确计数。
fn read_braced(s: &str, open: usize) -> Option<(&str, usize)> {
    let bytes = s.as_bytes();
    debug_assert_eq!(bytes[open], b'{');
    let mut depth = 0i32;
    let mut i = open;
    while i < bytes.len() {
        match bytes[i] {
            b'{' => depth += 1,
            b'}' => {
                depth -= 1;
                if depth == 0 {
                    return Some((&s[open + 1..i], i + 1));
                }
            }
            _ => {}
        }
        i += 1;
    }
    None
}

/// 渲染内联公式 `$...$`（定界符由 pulldown-cmark 剥除）→ HTML 字符串。
///
/// 渲染失败（坏 TeX）时回退到 HTML 转义后的原文，保证文章不因一个坏公式全篇崩。
pub fn render_inline(tex: &str) -> String {
    let tex = expand_chem(&expand_qty(tex));
    KATEX_CTX.with(|ctx| {
        INLINE_SETTINGS.with(|settings| {
            katex::render_to_string(ctx, &tex, settings)
                .map(|html| sort_svg_attributes(&html))
                .unwrap_or_else(|_| crate::utils::html::escape_html(&tex))
        })
    })
}

/// 渲染块级公式 `$$...$$`（定界符由 pulldown-cmark 剥除）→ HTML 字符串。
///
/// 与 [`render_inline`] 同样在失败时回退到转义原文。调用方负责块级包裹
/// （如 `<p class="math-display">`），这里只产出 KaTeX 的 span 串。
pub fn render_display(tex: &str) -> String {
    let tex = expand_chem(&expand_qty(tex));
    KATEX_CTX.with(|ctx| {
        DISPLAY_SETTINGS.with(|settings| {
            katex::render_to_string(ctx, &tex, settings)
                .map(|html| sort_svg_attributes(&html))
                .unwrap_or_else(|_| crate::utils::html::escape_html(&tex))
        })
    })
}

/// 把 `<svg>` / `<path>` 开标签的属性按名称排序。
///
/// `katex-rs` 用 `HashMap` 存 SVG 属性，同一公式两次渲染的属性顺序不同（实测同一
/// 输入 10 次中 9 次不同）。顺序不影响显示，但会让「同一正文渲染结果逐字相同」的
/// 前提失效——富文本往返守卫（`posts::roundtrip`）靠比较渲染 HTML 判断有损，
/// 含根号 / 矩阵竖线等 SVG 的正文因此永远被误判为有损。KaTeX 产出的这两种标签的
/// 属性值是不含 `>` 与 `"` 的双引号字符串，可以直接扫描。
fn sort_svg_attributes(html: &str) -> String {
    let mut out = String::with_capacity(html.len());
    let mut rest = html;
    while let Some(start) = ["<svg ", "<path "]
        .iter()
        .filter_map(|tag| rest.find(tag))
        .min()
    {
        let Some(end) = rest[start..].find('>').map(|i| start + i) else {
            break;
        };
        let tag_end = rest[start + 1..].find(' ').map_or(end, |i| start + 1 + i);
        let (self_closing, attrs_end) = if rest[..end].ends_with('/') {
            (true, end - 1)
        } else {
            (false, end)
        };
        let mut attrs: Vec<&str> = Vec::new();
        let mut cursor = tag_end;
        let attr_src = &rest[..attrs_end];
        while let Some(eq) = attr_src[cursor..].find("=\"").map(|i| cursor + i) {
            let value_start = eq + 2;
            let Some(value_end) = attr_src[value_start..].find('"').map(|i| value_start + i) else {
                break;
            };
            attrs.push(attr_src[cursor..=value_end].trim_start());
            cursor = value_end + 1;
        }
        attrs.sort_unstable();
        out.push_str(&rest[..tag_end]);
        for attr in attrs {
            out.push(' ');
            out.push_str(attr);
        }
        if self_closing {
            out.push('/');
        }
        out.push('>');
        rest = &rest[end + 1..];
    }
    out.push_str(rest);
    out
}

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

    #[test]
    fn render_inline_produces_katex_span() {
        let html = render_inline("E = mc^2");
        assert!(
            html.contains("katex"),
            "内联公式应产出含 katex class 的 span, got: {html}"
        );
    }

    #[test]
    fn render_display_produces_katex_display() {
        let html = render_display("\\frac{a}{b}");
        assert!(
            html.contains("katex-display"),
            "块级公式应产出含 katex-display class 的结构, got: {html}"
        );
    }

    #[test]
    fn render_inline_does_not_emit_math_tag() {
        // OutputFormat::Html 不应产出 <math> 标签（那是 HtmlAndMathml / Mathml 模式）。
        let html = render_inline("a^2 + b^2 = c^2");
        assert!(
            !html.contains("<math"),
            "Html 输出不应含 <math> 标签, got: {html}"
        );
    }

    // ── 物理宏表（Fix 3a） ─────────────────────────────────────────
    // katex-rs 默认无物理宏，未注册时 \vu \dd \RR 等渲染为 katex-error 红字。

    #[test]
    fn physics_macro_unit_vector_renders() {
        // \vu{i} → \hat{\vec{i}}：带帽子单位向量。
        let html = render_inline(r"\vu{i}");
        assert!(
            html.contains("katex") && !html.contains("katex-error"),
            "\\vu 应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn physics_macro_divergence_does_not_override_division() {
        // 刻意差异：\divg（散度）与 \div（除号 ÷）并存。
        let divg = render_inline(r"\divg \vec{F}");
        let div = render_inline(r"a \div b");
        assert!(
            !divg.contains("katex-error"),
            "\\divg 应正确渲染而非红字, got: {divg}"
        );
        assert!(
            !div.contains("katex-error"),
            "\\div 应仍是除号而非红字, got: {div}"
        );
        // 两者输出不同（\divg 展开为 \nabla \cdot，\div 是除号符号）。
        assert_ne!(divg, div, "\\divg 与 \\div 输出应不同");
    }

    #[test]
    fn physics_macro_number_sets_renders() {
        for m in [r"\RR", r"\ZZ", r"\NN", r"\QQ", r"\CC"] {
            let html = render_inline(m);
            assert!(
                !html.contains("katex-error"),
                "{m} 应正确渲染而非红字, got: {html}"
            );
        }
    }

    #[test]
    fn physics_macro_calculus_renders() {
        // \dv{f}{x} → d f / d x；\pdv{f}{x} → ∂ f / ∂ x；\dd{x} → dx。
        for tex in [r"\dv{f}{x}", r"\pdv{f}{x}", r"\dd{x}"] {
            let html = render_inline(tex);
            assert!(
                !html.contains("katex-error"),
                "{tex} 应正确渲染而非红字, got: {html}"
            );
        }
    }

    #[test]
    fn physics_macro_bare_dd_renders() {
        // 文章 48 的麦克斯韦方程组（积分形式）与欧拉-拉格朗日方程：`\frac{\dd}{\dd{t}}`
        // 里的裸 `\dd` 曾吞掉 `}`，整块公式退化成红色原文。
        for tex in [
            r"\frac{\dd}{\dd{t}}",
            r"\begin{aligned} \oint_{\partial S} \vec{E} \cdot \dd{\vec{l}} &= -\frac{\dd}{\dd{t}} \int_S \vec{B} \cdot \dd{\vec{A}} \end{aligned}",
            r"\frac{\dd}{\dd{t}} \pdv{\mathcal{L}}{\dot{q}_i} - \pdv{\mathcal{L}}{q_i} = 0",
            r"\int f(x) \dd x",
        ] {
            let html = render_display(tex);
            assert!(
                !html.contains("#cc0000"),
                "{tex} 应正确渲染而非红字, got: {html}"
            );
        }
        // 带参数时与原先的 `\mathrm{d}#1` 等价：直立 d 后紧跟参数。
        let html = render_inline(r"\dd{x}");
        assert!(html.contains(">d<") && html.contains(">x<"), "got: {html}");
    }

    #[test]
    fn physics_macro_dirac_notation_renders() {
        for tex in [
            r"\bra{\psi}",
            r"\ket{\phi}",
            r"\braket{\psi}{\phi}",
            r"\expval{A}",
        ] {
            let html = render_inline(tex);
            assert!(
                !html.contains("katex-error"),
                "{tex} 应正确渲染而非红字, got: {html}"
            );
        }
    }

    #[test]
    fn physics_macro_abs_norm_qty_renders() {
        for tex in [r"\abs{x}", r"\norm{v}", r"\qty{a + b}"] {
            let html = render_inline(tex);
            assert!(
                !html.contains("katex-error"),
                "{tex} 应正确渲染而非红字, got: {html}"
            );
        }
    }

    #[test]
    fn expand_qty_rewrites_delimiter_forms() {
        for (input, expected) in [
            (r"\qty(\dfrac{a}{b})", r"\left(\dfrac{a}{b}\right)"),
            (r"\qty[a, b]", r"\left[a, b\right]"),
            (r"\qty (x)", r"\left(x\right)"),
            // 内层普通括号参与配对，不会提前收尾。
            (r"\qty(f(x) + g(x))^2", r"\left(f(x) + g(x)\right)^2"),
            (r"\qty(f\qty(x))", r"\left(f\left(x\right)\right)"),
            // 花括号内的括号、`\{` `\)` 这类控制符都不计数。
            (r"\qty(\text{)} x)", r"\left(\text{)} x\right)"),
            (r"\qty(\{x\} \))", r"\left(\{x\} \)\right)"),
            (r"\qty(\text{浓度})", r"\left(\text{浓度}\right)"),
            (r"a \qty(b) c \qty[d]", r"a \left(b\right) c \left[d\right]"),
        ] {
            assert_eq!(expand_qty(input), expected, "input: {input}");
        }
    }

    #[test]
    fn expand_qty_leaves_other_forms_untouched() {
        for input in [
            r"\qty{a + b}",
            r"\qtyx(a)",
            r"a \\qty(b)",
            // 不闭合，或外层花括号先关闭：保留原文。
            r"\qty(a",
            r"{\qty(a} )",
            r"x^2",
        ] {
            assert!(
                matches!(expand_qty(input), Cow::Borrowed(s) if s == input),
                "{input} 应原样保留"
            );
        }
    }

    #[test]
    fn physics_macro_qty_parentheses_render_as_left_right() {
        // 文章 48 的 `$\qty(\dfrac{a}{b})$` 曾渲染成「(()a/b)」：宏表把 `(` 当成参数。
        assert_eq!(
            render_inline(r"\qty(\dfrac{a}{b})"),
            render_inline(r"\left(\dfrac{a}{b}\right)")
        );
        assert_eq!(
            render_display(r"\qty[\frac{1}{2}]"),
            render_display(r"\left[\frac{1}{2}\right]")
        );
    }

    // ── mhchem 化学公式（Fix 3b） ──────────────────────────────────────
    // \ce/\pu 预转译后渲染，不应出现 katex-error 红字。

    #[test]
    fn mhchem_water_renders() {
        let html = render_inline(r"\ce{H2O}");
        assert!(
            html.contains("katex") && !html.contains("katex-error"),
            "\\ce{{H2O}} 应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn mhchem_reaction_with_arrow_renders() {
        let html = render_display(r"\ce{2H2 + O2 -> 2H2O}");
        assert!(
            !html.contains("katex-error"),
            "反应方程式应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn mhchem_gas_arrow_superscript_renders() {
        // 气体符号 ^ —— 转译后变成 \uparrow，消解原 mhchem 行尾 ^ 解析错误
        // （文档 8.20 这正是当前唯一 1 个 katex-error 的根因）。
        let html = render_display(r"\ce{CaCO3 ->[\Delta] CaO + CO2 ^}");
        assert!(
            !html.contains("katex-error"),
            "气体箭头公式应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn mhchem_pu_units_renders() {
        // C1 回归：`\pu` 旧 off-by-one 使其永不匹配，mhchem::pu 从不触发。
        // 旧测试只断言 `!contains("katex-error")`，而 katex-rs 对未知命令走 color node
        // （无 katex-error class），故无论转译与否都通过——等于空测试。这里改为断言
        // 转译真正发生：产出含 katex 的 HTML，且不再是裸 `\pu{...}` 原文。
        let html = render_inline(r"\pu{9.8 m/s^2}");
        assert!(
            html.contains("katex") && !html.contains("katex-error"),
            "\\pu 单位应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn expand_chem_pu_is_actually_translated() {
        // C1 直接回归：expand_chem 必须把 `\pu{...}` 转译掉，不得原样保留命令。
        let out = expand_chem(r"\pu{9.8 m/s^2}");
        assert_ne!(
            out, r"\pu{9.8 m/s^2}",
            "\\pu 应被 mhchem::pu 转译而非原样保留, got: {out}"
        );
        assert!(
            !out.contains(r"\pu{"),
            "转译后不应残留 \\pu{{ 命令, got: {out}"
        );
    }

    #[test]
    fn expand_chem_preserves_multibyte_utf8() {
        // C2 回归：旧的 `out.push(bytes[i] as char)` 按单字节 Latin-1 转 char，
        // 含 `\ce`/`\pu` 且含非 ASCII（如中文 `\text{浓度}`）的公式会被破坏成乱码。
        let out = expand_chem(r"\text{浓度} \ce{H2O}");
        assert!(out.contains("浓度"), "中文应原样保留, got: {out}");
        assert!(
            !out.contains(r"\ce{"),
            "化学公式应被转译、不残留 \\ce{{ 命令, got: {out}"
        );
        // 仅含非 ASCII、无化学公式时零成本原样返回。
        assert_eq!(expand_chem(r"纯中文无公式"), r"纯中文无公式");
    }

    // issue #13：保留真实渲染回归。katex-rs 0.3 已支持文本模式 U+00B7，
    // 不再预处理 TeX。未知命令也可能产出 color node，不能只检查 katex-error。

    #[test]
    fn text_mode_middle_dot_does_not_render_red() {
        let html = render_inline(r"\text{m·K}");
        assert!(
            !html.contains("#cc0000"),
            "\\text{{m·K}} 不应渲染为红字错误, got: {html}"
        );
        // 与 KaTeX JS 一致的 glyph：U+22C5。
        assert!(html.contains('⋅'), "应渲染 U+22C5 glyph, got: {html}");
    }

    #[test]
    fn issue13_wien_law_formula_does_not_render_red() {
        // issue #13 原始公式（维恩位移定律 b 的单位 m·K）。
        let html = render_inline(r"b \approx 2.898\times10^{-3}\,\text{m·K}");
        assert!(
            !html.contains("#cc0000"),
            "issue #13 公式不应有红字, got: {html}"
        );
    }

    #[test]
    fn text_family_commands_render_middle_dot() {
        for cmd in [r"\text", r"\textbf", r"\textit", r"\texttt"] {
            let html = render_inline(&format!(r"{cmd}{{m·K}}"));
            assert!(
                !html.contains("#cc0000"),
                "{cmd}{{m·K}} 不应渲染为红字错误, got: {html}"
            );
        }
    }

    #[test]
    fn math_mode_middle_dot_renders_as_punctuation() {
        // 数学模式 U+00B7 是标点符号，保持 \cdotp 的间距语义。
        let html = render_inline("a · b");
        assert!(
            !html.contains("#cc0000"),
            "数学模式 · 本就能渲染, got: {html}"
        );
        assert!(
            html.contains("mpunct"),
            "数学模式 · 应保持 \\cdotp（mpunct）语义, got: {html}"
        );
    }

    #[test]
    fn display_mode_middle_dot_renders() {
        let html = render_display(r"T = \frac{b}{\lambda}, \text{单位 m·K}");
        assert!(
            !html.contains("#cc0000"),
            "块级公式 \\text{{m·K}} 不应渲染为红字错误, got: {html}"
        );
    }

    #[test]
    fn mhchem_ion_with_nested_braces_renders() {
        // 嵌套花括号 / 络离子：扫描器必须正确配对 {}。
        let html = render_inline(r"\ce{[Cu(NH3)4]^2+}");
        assert!(
            !html.contains("katex-error"),
            "络离子公式应正确渲染而非红字, got: {html}"
        );
    }

    #[test]
    fn mhchem_arrows_and_bonds_do_not_render_red() {
        // MathJax 专有命令（\longrightleftharpoons、\raise、\tripledash 等）在 katex-rs
        // 下会变成红色 color node（不带 katex-error），必须单独断言 #cc0000。
        for input in [
            r"\ce{CO2 + H2O <=> H2CO3}",
            r"\ce{A <--> B}",
            r"\ce{A <=>> B}",
            r"\ce{A <<=> B}",
            r"\ce{A <-> B}",
            r"\ce{A <- B}",
            r"\ce{A ->[H2O][\Delta] B}",
            r"\ce{A <=>[k_1][k_2] B}",
            r"\ce{A\bond{~}B}",
            r"\ce{A\bond{~-}B}",
            r"\ce{A\bond{~=}B}",
            r"\ce{A\bond{-~-}B}",
            r"\ce{^{227}_{90}Th}",
        ] {
            let html = render_display(input);
            assert!(
                !html.contains("#cc0000"),
                "{input} 不应渲染为红字, got: {html}"
            );
        }
    }

    #[test]
    fn svg_formulas_render_deterministically() {
        // 根号带 <svg>/<path>；katex-rs 的 HashMap 属性顺序曾让同一输入每次渲染都不同。
        let first = render_display(r"\sqrt{\pi} + \sqrt{\frac{a}{b}}");
        assert!(first.contains("<svg"), "应含 svg, got: {first}");
        for _ in 0..20 {
            assert_eq!(first, render_display(r"\sqrt{\pi} + \sqrt{\frac{a}{b}}"));
        }
    }

    #[test]
    fn sort_svg_attributes_orders_names_and_keeps_rest() {
        let html = r#"<span class="a"><svg xmlns="x" width="1em" height="2em"><path d="M0 0 L1 1"/></svg></span>"#;
        assert_eq!(
            sort_svg_attributes(html),
            r#"<span class="a"><svg height="2em" width="1em" xmlns="x"><path d="M0 0 L1 1"/></svg></span>"#
        );
    }
}