docvortex 0.2.1__py3-none-any.whl

docvortex/content/markup/styles.py

@@ -0,0 +1,327 @@
+"""解析 XHTML/HTML 使用的有限语义 CSS 子集。"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from docvortex.foundation.xml_names import local_name
+from docvortex.foundation.type_identity import preserve_type_module
+
+
+_CSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)
+_CSS_IMPORTANT_RE = re.compile(r"!\s*important\s*$", re.IGNORECASE)
+_TEXT_STYLE_FIELDS = ("bold", "italic", "underline", "strikethrough", "superscript", "subscript")
+_VISIBILITY_FIELDS = ("display", "visibility", "opacity")
+
+
+@dataclass(frozen=True, slots=True)
+class TextStyle:
+    """保存可投影到 Middle JSON 行内协议的文字样式。"""
+
+    bold: bool = False
+    italic: bool = False
+    underline: bool = False
+    strikethrough: bool = False
+    superscript: bool = False
+    subscript: bool = False
+
+    def merge(self, other: TextStyle) -> TextStyle:
+        """合并继承样式和当前元素显式开启的样式。"""
+        return TextStyle(
+            bold=self.bold or other.bold,
+            italic=self.italic or other.italic,
+            underline=self.underline or other.underline,
+            strikethrough=self.strikethrough or other.strikethrough,
+            superscript=self.superscript or other.superscript,
+            subscript=self.subscript or other.subscript,
+        )
+
+    def names(self) -> tuple[str, ...]:
+        """按稳定顺序返回现有行内协议识别的样式名称。"""
+        return tuple(
+            name
+            for enabled, name in (
+                (self.bold, "bold"),
+                (self.italic, "italic"),
+                (self.underline, "underline"),
+                (self.strikethrough, "strikethrough"),
+                (self.superscript, "superscript"),
+                (self.subscript, "subscript"),
+            )
+            if enabled
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TextStyleDelta:
+    """保存 CSS 对各文字样式的显式开启、关闭或未声明状态。"""
+
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strikethrough: bool | None = None
+    superscript: bool | None = None
+    subscript: bool | None = None
+
+    def apply(self, base: TextStyle) -> TextStyle:
+        """把当前声明覆盖到已解析的继承/标签样式。"""
+        return TextStyle(
+            bold=base.bold if self.bold is None else self.bold,
+            italic=base.italic if self.italic is None else self.italic,
+            underline=base.underline if self.underline is None else self.underline,
+            strikethrough=base.strikethrough if self.strikethrough is None else self.strikethrough,
+            superscript=base.superscript if self.superscript is None else self.superscript,
+            subscript=base.subscript if self.subscript is None else self.subscript,
+        )
+
+    def is_empty(self) -> bool:
+        """返回当前声明是否没有触及任何受支持样式。"""
+        return all(
+            value is None
+            for value in (
+                self.bold,
+                self.italic,
+                self.underline,
+                self.strikethrough,
+                self.superscript,
+                self.subscript,
+            )
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class ElementStyle:
+    """保存元素最终文字样式、整树隐藏状态和继承可见性。"""
+
+    text: TextStyle
+    subtree_hidden: bool = False
+    visibility_hidden: bool = False
+
+    @property
+    def hidden(self) -> bool:
+        """返回当前元素是否因任一种受支持的隐藏语义而不可见。"""
+        return self.subtree_hidden or self.visibility_hidden
+
+
+@dataclass(slots=True)
+class _SelectorCascade:
+    """按 selector 聚合各属性最后一次声明及其源码顺序。"""
+
+    priority: int
+    declarations: dict[str, tuple[bool, int, bool]] = field(default_factory=dict)
+    visibility: dict[str, tuple[bool, int, bool]] = field(default_factory=dict)
+
+    def update(self, parsed: _ParsedDeclarations, order: int) -> None:
+        """按 importance 和源码顺序更新同 selector 的逐属性级联结果。"""
+        for name, (important, value) in parsed.text.items():
+            current = self.declarations.get(name)
+            if current is None or (important, order) >= current[:2]:
+                self.declarations[name] = (important, order, value)
+        for name, (important, value) in parsed.visibility.items():
+            current = self.visibility.get(name)
+            if current is None or (important, order) >= current[:2]:
+                self.visibility[name] = (important, order, value)
+
+
+@dataclass(frozen=True, slots=True)
+class _ParsedDeclarations:
+    """保存已投影 CSS 属性的 importance 与布尔值。"""
+
+    text: dict[str, tuple[bool, bool]]
+    visibility: dict[str, tuple[bool, bool]]
+
+
+def _numeric_font_weight(value: str) -> int | None:
+    """在整数转换前解析 CSS Fonts 允许的一到一千字重。"""
+    if not value.isascii() or not value.isdigit() or len(value) > 4:
+        return None
+    weight = int(value)
+    return weight if 1 <= weight <= 1_000 else None
+
+
+def _parse_declarations(value: str) -> _ParsedDeclarations:
+    """从声明串逐属性提取字体语义、隐藏状态和 important 优先级。"""
+    text: dict[str, tuple[bool, bool]] = {}
+    visibility: dict[str, tuple[bool, bool]] = {}
+    for raw_declaration in value.split(";"):
+        if ":" not in raw_declaration:
+            continue
+        name, raw_value = raw_declaration.split(":", 1)
+        name = name.strip().casefold()
+        important_match = _CSS_IMPORTANT_RE.search(raw_value)
+        important = important_match is not None
+        normalized = raw_value[: important_match.start() if important_match is not None else None].strip().casefold()
+        text_updates: dict[str, bool] = {}
+        visibility_update: tuple[str, bool] | None = None
+        if name == "font-weight":
+            if normalized in {"bold", "bolder"}:
+                text_updates["bold"] = True
+            elif normalized in {"normal", "lighter"}:
+                text_updates["bold"] = False
+            elif (weight := _numeric_font_weight(normalized)) is not None:
+                text_updates["bold"] = weight >= 600
+        elif name == "font-style":
+            text_updates["italic"] = normalized in {"italic", "oblique"}
+        elif name in {"text-decoration", "text-decoration-line"}:
+            if normalized == "none":
+                text_updates["underline"] = False
+                text_updates["strikethrough"] = False
+            else:
+                text_updates["underline"] = "underline" in normalized
+                text_updates["strikethrough"] = "line-through" in normalized
+        elif name == "vertical-align":
+            text_updates["superscript"] = normalized in {"super", "text-top"}
+            text_updates["subscript"] = normalized in {"sub", "text-bottom"}
+        elif name == "display":
+            visibility_update = ("display", normalized == "none")
+        elif name == "visibility":
+            if normalized in {"hidden", "collapse"}:
+                visibility_update = ("visibility", True)
+            elif normalized in {"visible", "initial"}:
+                visibility_update = ("visibility", False)
+        elif name == "opacity":
+            try:
+                opacity = float(normalized)
+            except ValueError:
+                pass
+            else:
+                visibility_update = ("opacity", opacity <= 0)
+        for field_name, field_value in text_updates.items():
+            current = text.get(field_name)
+            if current is None or important or not current[0]:
+                text[field_name] = (important, field_value)
+        if visibility_update is not None:
+            field_name, field_value = visibility_update
+            current = visibility.get(field_name)
+            if current is None or important or not current[0]:
+                visibility[field_name] = (important, field_value)
+    return _ParsedDeclarations(text=text, visibility=visibility)
+
+
+class MarkupStylesheet:
+    """保存按文档顺序解析的简单 tag/class CSS 规则。"""
+
+    def __init__(self) -> None:
+        """初始化按 tag、class 与 tag.class 分桶的 selector 索引。"""
+        self._tag_cascades: dict[str, _SelectorCascade] = {}
+        self._class_cascades: dict[str, _SelectorCascade] = {}
+        self._tag_class_cascades: dict[tuple[str, str], _SelectorCascade] = {}
+        self._source_order = 0
+
+    def _selector_cascade(self, tag: str | None, class_name: str | None, priority: int) -> _SelectorCascade:
+        """返回指定简单 selector 的聚合级联槽。"""
+        if class_name is None:
+            assert tag is not None
+            return self._tag_cascades.setdefault(tag, _SelectorCascade(priority))
+        if tag is None:
+            return self._class_cascades.setdefault(class_name, _SelectorCascade(priority))
+        return self._tag_class_cascades.setdefault((tag, class_name), _SelectorCascade(priority))
+
+    def add(self, css: str) -> None:
+        """追加一个 stylesheet 中受支持的简单 selector 规则。"""
+        normalized_css = _CSS_COMMENT_RE.sub("", css)
+        for chunk in normalized_css.split("}"):
+            if "{" not in chunk:
+                continue
+            selectors, declarations = chunk.split("{", 1)
+            parsed_declarations = _parse_declarations(declarations)
+            if not parsed_declarations.text and not parsed_declarations.visibility:
+                continue
+            for selector in selectors.split(","):
+                parsed = self._parse_selector(selector)
+                if parsed is None:
+                    continue
+                tag, class_name, priority = parsed
+                cascade = self._selector_cascade(tag, class_name, priority)
+                cascade.update(parsed_declarations, self._source_order)
+                self._source_order += 1
+
+    @staticmethod
+    def _parse_selector(selector: str) -> tuple[str | None, str | None, int] | None:
+        """只接受 tag、.class 和 tag.class，拒绝组合器及伪类。"""
+        normalized = selector.strip()
+        if not normalized or any(token in normalized for token in (" ", ">", "+", "~", ":", "[", "#")):
+            return None
+        if "." in normalized:
+            tag_text, class_name = normalized.split(".", 1)
+            if not class_name or "." in class_name:
+                return None
+            tag = tag_text.casefold() or None
+            return tag, class_name, 10 + (1 if tag else 0)
+        return normalized.casefold(), None, 1
+
+    def resolve(
+        self,
+        element: etree._Element,
+        inherited: TextStyle,
+        inherited_visibility_hidden: bool = False,
+    ) -> ElementStyle:
+        """计算元素的继承样式、标签默认样式、CSS 规则和 inline style。"""
+        tag = local_name(element)
+        classes = frozenset((element.get("class") or "").split())
+        tag_style = TextStyle(
+            bold=tag in {"b", "strong"},
+            italic=tag in {"cite", "dfn", "em", "i", "var"},
+            strikethrough=tag in {"del", "s", "strike"},
+            superscript=tag == "sup",
+            subscript=tag == "sub",
+        )
+        style = inherited.merge(tag_style)
+        subtree_hidden = element.get("hidden") is not None or (element.get("aria-hidden") or "").casefold() == "true"
+        matching: list[_SelectorCascade] = []
+        if cascade := self._tag_cascades.get(tag):
+            matching.append(cascade)
+        for class_name in classes:
+            if cascade := self._class_cascades.get(class_name):
+                matching.append(cascade)
+            if cascade := self._tag_class_cascades.get((tag, class_name)):
+                matching.append(cascade)
+
+        inline = _parse_declarations(element.get("style") or "")
+        resolved_values: dict[str, bool] = {}
+        for name in _TEXT_STYLE_FIELDS:
+            candidates = [
+                (important, cascade.priority, order, value)
+                for cascade in matching
+                if (declaration := cascade.declarations.get(name)) is not None
+                for important, order, value in (declaration,)
+            ]
+            if (inline_declaration := inline.text.get(name)) is not None:
+                important, value = inline_declaration
+                candidates.append((important, 1_000, self._source_order, value))
+            if candidates:
+                resolved_values[name] = max(candidates, key=lambda item: item[:3])[3]
+        style = TextStyleDelta(**resolved_values).apply(style)
+
+        resolved_visibility: dict[str, bool] = {}
+        for name in _VISIBILITY_FIELDS:
+            candidates = [
+                (important, cascade.priority, order, value)
+                for cascade in matching
+                if (declaration := cascade.visibility.get(name)) is not None
+                for important, order, value in (declaration,)
+            ]
+            if (inline_declaration := inline.visibility.get(name)) is not None:
+                important, value = inline_declaration
+                candidates.append((important, 1_000, self._source_order, value))
+            if candidates:
+                resolved_visibility[name] = max(candidates, key=lambda item: item[:3])[3]
+        subtree_hidden = (
+            subtree_hidden or resolved_visibility.get("display", False) or resolved_visibility.get("opacity", False)
+        )
+        visibility_hidden = resolved_visibility.get("visibility", inherited_visibility_hidden)
+        return ElementStyle(style, subtree_hidden, visibility_hidden)
+
+
+__all__ = ["ElementStyle", "MarkupStylesheet", "TextStyle", "TextStyleDelta"]
+
+# 保持既有公开类型的 pickle 路径，所有旧、新入口指向同一个类。
+preserve_type_module(TextStyle, "docvortex.analyzers.native._shared.markup.styles")
+preserve_type_module(TextStyleDelta, "docvortex.analyzers.native._shared.markup.styles")
+preserve_type_module(ElementStyle, "docvortex.analyzers.native._shared.markup.styles")
+preserve_type_module(_SelectorCascade, "docvortex.analyzers.native._shared.markup.styles")
+preserve_type_module(_ParsedDeclarations, "docvortex.analyzers.native._shared.markup.styles")
+preserve_type_module(MarkupStylesheet, "docvortex.analyzers.native._shared.markup.styles")

docvortex/content/mathml.py

@@ -0,0 +1,167 @@
+"""把常用 Presentation MathML 结构转换为 LaTeX。"""
+
+from __future__ import annotations
+
+import re
+
+from lxml import etree  # type: ignore[reportMissingImports]
+
+from docvortex.foundation.xml_names import local_name
+
+
+_OPERATOR_MAP = {
+    "−": "-",
+    "×": r"\times ",
+    "÷": r"\div ",
+    "·": r"\cdot ",
+    "±": r"\pm ",
+    "∓": r"\mp ",
+    "∞": r"\infty ",
+    "≠": r"\ne ",
+    "≤": r"\le ",
+    "≥": r"\ge ",
+    "≈": r"\approx ",
+    "≡": r"\equiv ",
+    "∈": r"\in ",
+    "∉": r"\notin ",
+    "⊂": r"\subset ",
+    "⊆": r"\subseteq ",
+    "∪": r"\cup ",
+    "∩": r"\cap ",
+    "∑": r"\sum ",
+    "∏": r"\prod ",
+    "∫": r"\int ",
+    "∂": r"\partial ",
+    "√": r"\sqrt{}",
+    "→": r"\to ",
+    "←": r"\leftarrow ",
+    "↔": r"\leftrightarrow ",
+}
+_GREEK_MAP = {
+    "α": r"\alpha ",
+    "β": r"\beta ",
+    "γ": r"\gamma ",
+    "δ": r"\delta ",
+    "ε": r"\epsilon ",
+    "θ": r"\theta ",
+    "λ": r"\lambda ",
+    "μ": r"\mu ",
+    "π": r"\pi ",
+    "σ": r"\sigma ",
+    "φ": r"\phi ",
+    "ω": r"\omega ",
+    "Γ": r"\Gamma ",
+    "Δ": r"\Delta ",
+    "Θ": r"\Theta ",
+    "Λ": r"\Lambda ",
+    "Π": r"\Pi ",
+    "Σ": r"\Sigma ",
+    "Φ": r"\Phi ",
+    "Ω": r"\Omega ",
+}
+_LATEX_ESCAPE_RE = re.compile(r"([#$%&_{}])")
+_LATEX_MATH_TOKEN_ESCAPES = {
+    "\\": r"\backslash{}",
+    "#": r"\#",
+    "$": r"\$",
+    "%": r"\%",
+    "&": r"\&",
+    "_": r"\_",
+    "^": r"\^{}",
+    "{": r"\{",
+    "}": r"\}",
+    "~": r"\~{}",
+}
+
+
+def _escape_text(value: str) -> str:
+    """转义进入 LaTeX 文本命令的保留字符。"""
+    return _LATEX_ESCAPE_RE.sub(r"\\\1", value)
+
+
+def _escape_math_token(value: str) -> str:
+    """转义 MathML 标识符中的 TeX 控制字符，避免字面文本改变公式结构。"""
+    return "".join(_LATEX_MATH_TOKEN_ESCAPES.get(char, char) for char in value)
+
+
+def _children(element: etree._Element) -> list[etree._Element]:
+    """返回当前元素的全部普通 XML 子元素。"""
+    return [child for child in element if isinstance(child.tag, str)]
+
+
+def _join_children(element: etree._Element) -> str:
+    """按文档顺序拼接所有子 MathML 节点。"""
+    return "".join(_convert(child) for child in _children(element))
+
+
+def _convert(element: etree._Element) -> str:
+    """递归转换一个常用 MathML 节点，未知容器保留其可解析子项。"""
+    name = local_name(element)
+    children = _children(element)
+    text = (element.text or "").strip()
+    if name == "semantics":
+        if not children or local_name(children[0]) in {"annotation", "annotation-xml"}:
+            return ""
+        return _convert(children[0])
+    if name in {"math", "mrow", "mstyle", "mpadded", "mphantom"}:
+        return _join_children(element)
+    if name in {"mi", "mn"}:
+        return _GREEK_MAP.get(text, _escape_math_token(text))
+    if name == "mo":
+        return _OPERATOR_MAP.get(text, text)
+    if name == "mtext":
+        return rf"\text{{{_escape_text(text)}}}"
+    if name == "mspace":
+        return r"\,"
+    if name == "mfrac" and len(children) >= 2:
+        return rf"\frac{{{_convert(children[0])}}}{{{_convert(children[1])}}}"
+    if name == "msqrt":
+        return rf"\sqrt{{{_join_children(element)}}}"
+    if name == "mroot" and len(children) >= 2:
+        return rf"\sqrt[{_convert(children[1])}]{{{_convert(children[0])}}}"
+    if name == "msup" and len(children) >= 2:
+        return rf"{{{_convert(children[0])}}}^{{{_convert(children[1])}}}"
+    if name == "msub" and len(children) >= 2:
+        return rf"{{{_convert(children[0])}}}_{{{_convert(children[1])}}}"
+    if name == "msubsup" and len(children) >= 3:
+        return rf"{{{_convert(children[0])}}}_{{{_convert(children[1])}}}^{{{_convert(children[2])}}}"
+    if name == "mover" and len(children) >= 2:
+        return rf"\overset{{{_convert(children[1])}}}{{{_convert(children[0])}}}"
+    if name == "munder" and len(children) >= 2:
+        return rf"\underset{{{_convert(children[1])}}}{{{_convert(children[0])}}}"
+    if name == "munderover" and len(children) >= 3:
+        base = _convert(children[0])
+        return rf"\underset{{{_convert(children[1])}}}{{\overset{{{_convert(children[2])}}}{{{base}}}}}"
+    if name == "mfenced":
+        opening = element.get("open", "(")
+        closing = element.get("close", ")")
+        separators = element.get("separators", ",") or ","
+        values = [_convert(child) for child in children]
+        return rf"\left{opening}{separators[0].join(values)}\right{closing}"
+    if name == "mtable":
+        rows = [_convert(child) for child in children if local_name(child) in {"mtr", "mlabeledtr"}]
+        return r"\begin{matrix}" + r" \\ ".join(rows) + r"\end{matrix}"
+    if name in {"mtr", "mlabeledtr"}:
+        return " & ".join(_convert(child) for child in children)
+    if name == "mtd":
+        return _join_children(element)
+    if name == "annotation" and "tex" in (element.get("encoding", "").casefold()):
+        return text
+    return _join_children(element) or text
+
+
+def mathml_to_latex(math_element: etree._Element) -> str | None:
+    """转换 MathML 根节点，并优先采用生产者保留的 TeX annotation。"""
+    for annotation in math_element.iter():
+        if not isinstance(annotation.tag, str):
+            continue
+        if local_name(annotation) != "annotation":
+            continue
+        encoding = (annotation.get("encoding") or "").casefold()
+        if "tex" in encoding and (annotation.text or "").strip():
+            return (annotation.text or "").strip()
+    latex = _convert(math_element).strip()
+    return latex or None
+
+
+__all__ = ["mathml_to_latex"]

docvortex/content/normalization.py

@@ -0,0 +1,188 @@
+"""PDF 模型输出的可见文字清洗；原始字符、布局证据及其它输入格式不在此处理。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Sequence
+import re
+from typing import Any
+
+from ..foundation.text import full_to_half_exclude_marks
+from ..schema import BlockType, RAW_CAPTION, RAW_FOOTNOTE, RAW_PHONETIC
+
+_FULLWIDTH_MODEL_TEXT = re.compile("[Ａ-Ｚａ-ｚ０-９：．／＼－＿％＋＝＠＃＆＊]")
+_PDF_SYMBOL_TRANSLATION = str.maketrans(
+    {
+        "：": ":",
+        "．": ".",
+        "／": "/",
+        "＼": "\\",
+        "－": "-",
+        "＿": "_",
+        "％": "%",
+        "＋": "+",
+        "＝": "=",
+        "＠": "@",
+        "＃": "#",
+        "＆": "&",
+        "＊": "*",
+    }
+)
+_FORMULA_OPENING = re.compile(r"\\[\(\[]")
+_NATURAL_LANGUAGE_TYPES = frozenset(
+    {
+        BlockType.TEXT,
+        BlockType.DOC_TITLE,
+        BlockType.PARAGRAPH_TITLE,
+        BlockType.ASIDE_TEXT,
+        BlockType.HEADER,
+        BlockType.FOOTER,
+        BlockType.PAGE_NUMBER,
+        BlockType.PAGE_FOOTNOTE,
+        BlockType.REF_TEXT,
+        BlockType.LIST,
+        BlockType.INDEX,
+        BlockType.IMAGE_CAPTION,
+        BlockType.IMAGE_FOOTNOTE,
+        BlockType.TABLE_CAPTION,
+        BlockType.TABLE_FOOTNOTE,
+        BlockType.CHART_CAPTION,
+        BlockType.CHART_FOOTNOTE,
+        BlockType.CODE_CAPTION,
+        BlockType.CODE_FOOTNOTE,
+        RAW_CAPTION,
+        RAW_FOOTNOTE,
+        RAW_PHONETIC,
+    }
+)
+_OPAQUE_HTML_TAGS = frozenset(
+    {"eq", "math", "pre", "code", "script", "style", "svg", "template", "textarea", "object", "embed", "canvas", "iframe"}
+)
+
+
+def _normalize_plain_text(content: str) -> str:
+    """按一对一码点映射转换英数和 PDF 符号白名单，不改变通用英数工具的契约。"""
+    return full_to_half_exclude_marks(content).translate(_PDF_SYMBOL_TRANSLATION)
+
+
+def _normalize_text(content: str) -> str:
+    """转换公式范围之外的英数及白名单符号；未闭合公式保护到逻辑文字段末尾。"""
+    if not _FULLWIDTH_MODEL_TEXT.search(content):
+        return content
+    parts: list[str] = []
+    cursor = 0
+    while match := _FORMULA_OPENING.search(content, cursor):
+        parts.append(_normalize_plain_text(content[cursor : match.start()]))
+        closing = r"\)" if match.group() == r"\(" else r"\]"
+        end = content.find(closing, match.end())
+        if end < 0:
+            parts.append(content[match.start() :])
+            return "".join(parts)
+        cursor = end + len(closing)
+        parts.append(content[match.start() : cursor])
+    parts.append(_normalize_plain_text(content[cursor:]))
+    return "".join(parts)
+
+
+def _normalize_parts(parts: Sequence[str]) -> list[str]:
+    """先识别跨节点公式，再按原长度分回节点，保持样式与链接的边界。"""
+    source = "".join(parts)
+    normalized = _normalize_text(source)
+    if source == normalized:
+        return list(parts)
+    # 英数及符号映射始终一对一；不要使用可能扩展字符的整体 Unicode 规范化。
+    result: list[str] = []
+    offset = 0
+    for part in parts:
+        result.append(normalized[offset : offset + len(part)])
+        offset += len(part)
+    return result
+
+
+def _span_parts(spans: list[Any]) -> Iterator[tuple[dict[str, Any] | None, str]]:
+    """递归遍历可见 TextSpan；不读取 URL，并用不可见屏障隔离公式和代码载荷。"""
+    for span in spans:
+        if not isinstance(span, dict):
+            yield None, "\0"
+            continue
+        content = span.get("content")
+        if span.get("type") == "text" and isinstance(content, str):
+            yield span, content
+        elif span.get("type") == "hyperlink" and isinstance(content, list):
+            yield from _span_parts(content)
+        else:
+            yield None, "\0"
+
+
+def _normalize_spans(spans: list[Any]) -> None:
+    """只更新文字叶子的内容，既不重建 Span，也不合并相邻等样式片段。"""
+    entries = list(_span_parts(spans))
+    normalized = _normalize_parts([text for _span, text in entries])
+    for (span, original), replacement in zip(entries, normalized):
+        if span is not None and replacement != original:
+            span["content"] = replacement
+
+
+def _is_opaque_html_node(node: Any) -> bool:
+    """识别现有 HTML 公式、代码及非文本载体，保持它们的内容与属性原样。"""
+    name = str(node.name).split(":")[-1].lower()
+    return (
+        name in _OPAQUE_HTML_TAGS
+        or node.get("data-block-type") in {"equation", "code", "code_body", "algorithm", "algorithm_body"}
+        or node.has_attr("data-docvortex-latex")
+        or node.has_attr("data-formula-display")
+        or "docvortex-math" in (node.get("class") or [])
+    )
+
+
+def _normalize_table(markup: str) -> str:
+    """只修改单元格的可见文本节点；没有实际变化时保留原 HTML 字节表示。"""
+    if not _FULLWIDTH_MODEL_TEXT.search(markup) and "&#" not in markup:
+        return markup
+    # 与现有表格处理保持同一 HTML 解析器，公开模块导入不触发 HTML 依赖。
+    from bs4 import BeautifulSoup, NavigableString, Tag
+
+    soup = BeautifulSoup(markup, "html.parser")
+    changed = False
+
+    def cell_parts(node: Any) -> Iterator[tuple[NavigableString | None, str]]:
+        """样式标签保持透明，嵌套表格由其自身单元格处理，换行和载荷不能拼出定界符。"""
+        if type(node) is NavigableString:
+            yield node, str(node)
+        elif isinstance(node, Tag):
+            if _is_opaque_html_node(node) or node.name in {"table", "br", "hr", "img"}:
+                yield None, "\0"
+            else:
+                for child in node.children:
+                    yield from cell_parts(child)
+
+    for cell in soup.find_all(["td", "th"]):
+        if any(isinstance(parent, Tag) and _is_opaque_html_node(parent) for parent in (cell, *cell.parents)):
+            continue
+        entries = [part for child in cell.children for part in cell_parts(child)]
+        normalized = _normalize_parts([text for _node, text in entries])
+        for (node, original), replacement in zip(entries, normalized):
+            if node is not None and replacement != original:
+                node.replace_with(NavigableString(replacement))
+                changed = True
+    return str(soup) if changed else markup
+
+
+def normalize_pdf_model_text(model_list: list[list[dict[str, Any]]]) -> None:
+    """统一 PDF 自然语言及表格可见英数与白名单符号，保留公式、代码、URL 和结构。
+
+    应在样式、上下标和链接匹配结束后、ModelJson 构造前调用；函数幂等，不修改
+    原始字符证据，也不会将字符串转换为 Span 或清理其它模型元数据。
+    """
+    for page in model_list:
+        for block in page:
+            kind, content = block.get("type"), block.get("content")
+            if kind in _NATURAL_LANGUAGE_TYPES:
+                if isinstance(content, str):
+                    block["content"] = _normalize_text(content)
+                elif isinstance(content, list):
+                    _normalize_spans(content)
+            elif kind in {BlockType.TABLE, BlockType.TABLE_BODY} and isinstance(content, str):
+                block["content"] = _normalize_table(content)
+
+
+__all__ = ["normalize_pdf_model_text"]