docvortex 0.2.1__py3-none-any.whl

docvortex/render/_internal/latex/inline.py

@@ -0,0 +1,145 @@
+"""严格 InlineSpan 到安全 LaTeX 行内源码的转换。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from hashlib import sha256
+import re
+from typing import Iterable
+
+from ....content.inline import join_inline_spans
+from ....schema import CodeInlineSpan, EquationInlineSpan, HyperlinkSpan, InlineSpan, InlineStyle, TextSpan
+
+_INVALID_TEXT_CONTROL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+_TEXT_ESCAPES = {
+    "\\": r"\textbackslash{}",
+    "{": r"\{",
+    "}": r"\}",
+    "$": r"\$",
+    "&": r"\&",
+    "#": r"\#",
+    "_": r"\_",
+    "%": r"\%",
+    "~": r"\textasciitilde{}",
+    "^": r"\textasciicircum{}",
+}
+_URL_ESCAPES = {
+    "\\": "/",
+    "{": r"\{",
+    "}": r"\}",
+    "$": r"\$",
+    "&": r"\&",
+    "#": r"\#",
+    "_": r"\_",
+    "%": r"\%",
+    "~": r"\string~",
+    "^": r"\string^",
+}
+
+
+@dataclass(slots=True)
+class LatexAnchorRegistry:
+    """把原始 anchor 映射为安全稳定 target，并只发射首次定义。"""
+
+    source_targets: set[str]
+    emitted: set[str] = field(default_factory=set)
+
+    def target_for(self, anchor: str | None) -> str | None:
+        """仅为真实可见目标返回稳定的 TeX target 名。"""
+        normalized = (anchor or "").strip()
+        if not normalized or normalized not in self.source_targets:
+            return None
+        digest = sha256(normalized.encode("utf-8")).hexdigest()[:24]
+        return f"docvortex-{digest}"
+
+    def emit_target(self, anchor: str | None) -> str:
+        """首次出现时输出 hypertarget，重复 anchor 不再重复定义。"""
+        target = self.target_for(anchor)
+        if target is None or target in self.emitted:
+            return ""
+        self.emitted.add(target)
+        return rf"\hypertarget{{{target}}}{{}}"
+
+
+def escape_latex_text(content: str, *, preserve_newlines: bool = True) -> str:
+    """转义普通文本中的全部 TeX 控制字符并保留 Unicode。"""
+    normalized = _INVALID_TEXT_CONTROL_RE.sub("\ufffd", content).replace("\r\n", "\n").replace("\r", "\n")
+    parts: list[str] = []
+    for character in normalized:
+        if character == "\n":
+            parts.append(r"\DocVortexLineBreak{}" if preserve_newlines else " ")
+        else:
+            parts.append(_TEXT_ESCAPES.get(character, character))
+    return "".join(parts)
+
+
+def escape_latex_url(target: str) -> str:
+    """转义 hyperref URL 参数，同时保留 URL 的可解析结构。"""
+    normalized = _INVALID_TEXT_CONTROL_RE.sub("", target).replace("\r", "").replace("\n", "")
+    return "".join(_URL_ESCAPES.get(character, character) for character in normalized)
+
+
+def render_inline_spans(spans: Iterable[InlineSpan], anchors: LatexAnchorRegistry) -> str:
+    """按 span discriminator 渲染完整行内语义。"""
+    parts: list[str] = []
+    for span in spans:
+        if isinstance(span, TextSpan):
+            rendered = escape_latex_text(span.content)
+            parts.append(_apply_text_styles(rendered, span.styles))
+        elif isinstance(span, EquationInlineSpan):
+            parts.append(rf"\({span.content}\)")
+        elif isinstance(span, CodeInlineSpan):
+            parts.append(rf"\texttt{{{_escape_inline_code(span.content)}}}")
+        elif isinstance(span, HyperlinkSpan):
+            label = render_inline_spans(span.content, anchors)
+            if span.url.startswith("#"):
+                target = anchors.target_for(span.url[1:])
+                parts.append(rf"\hyperlink{{{target}}}{{{label}}}" if target else label)
+            else:
+                parts.append(rf"\href{{{escape_latex_url(span.url)}}}{{{label}}}")
+        else:
+            raise TypeError(f"Unsupported InlineSpan type: {type(span).__name__}")
+    return "".join(parts)
+
+
+def render_joined_inline_contents(
+    contents: Iterable[Iterable[InlineSpan]],
+    anchors: LatexAnchorRegistry,
+) -> str:
+    """按共享物理段落边界规则合并并渲染多段 InlineSpan。"""
+    return render_inline_spans(join_inline_spans(contents), anchors)
+
+
+def _apply_text_styles(content: str, styles: list[InlineStyle]) -> str:
+    """按公开固定顺序嵌套 LaTeX 文字样式。"""
+    wrappers = {
+        "bold": r"\textbf{%s}",
+        "italic": r"\textit{%s}",
+        "underline": r"\uline{%s}",
+        "emphasis": r"\CJKunderdot[format=\normalcolor]{%s}",
+        "strikethrough": r"\sout{%s}",
+        "superscript": r"\textsuperscript{%s}",
+        "subscript": r"\textsubscript{%s}",
+    }
+    rendered = content
+    for style in reversed(styles):
+        wrapper = wrappers.get(style)
+        if wrapper is None:
+            raise TypeError(f"Unsupported inline style: {style}")
+        rendered = wrapper % rendered
+    return rendered
+
+
+def _escape_inline_code(content: str) -> str:
+    """转义行内代码，并把连续空格与 Tab 转为等宽可见空格。"""
+    expanded = content.replace("\t", "    ")
+    return escape_latex_text(expanded).replace(" ", r"\ ")
+
+
+__all__ = [
+    "LatexAnchorRegistry",
+    "escape_latex_text",
+    "escape_latex_url",
+    "render_inline_spans",
+    "render_joined_inline_contents",
+]

docvortex/render/_internal/latex/renderer.py

@@ -0,0 +1,506 @@
+"""严格 MiddleJson 到 TeX Live XeLaTeX 完整文档的渲染实现。"""
+
+from __future__ import annotations
+
+import re
+
+from bs4 import BeautifulSoup
+from loguru import logger
+
+from ....content.inline import inline_plain_text
+from ....schema import (
+    PAGE_AUXILIARY_BLOCK_TYPES,
+    RAW_ALGORITHM,
+    AlgorithmBodyBlock,
+    BlockType,
+    ChartAnnotationBlock,
+    ChartBlock,
+    ChartBodyBlock,
+    CodeAnnotationBlock,
+    CodeBlock,
+    CodeBodyBlock,
+    DocTitleBlock,
+    EquationBlock,
+    ImageAnnotationBlock,
+    ImageBlock,
+    ImageBodyBlock,
+    ImagePayloadBlock,
+    IndexBlock,
+    InlineSpan,
+    ListBlock,
+    MiddleJson,
+    PageFootnoteBlock,
+    ParagraphTitleBlock,
+    RefTextBlock,
+    TableAnnotationBlock,
+    TableBlock,
+    TableBodyBlock,
+    TextBlock,
+    TitleBlockBase,
+)
+from ..common.index import strip_index_page_tail
+from ..common.list_items import ListItem, parse_list_item_marker, reference_list_needs_bullets
+from ..common.planner import PlannedBlock, build_render_plan
+from .assets import normalize_asset_base_path, remote_block_image_url, resolve_block_image_path, tex_image_path
+from .inline import LatexAnchorRegistry, escape_latex_text, escape_latex_url, render_inline_spans, render_joined_inline_contents
+from .table import LatexTableError, LatexTableRenderer
+
+_HTML_TABLE_RE = re.compile(r"<\s*table\b", re.IGNORECASE)
+_TOP_LEVEL_DISPLAY_ENV_RE = re.compile(
+    r"^\s*\\begin\{(?P<name>align\*?|equation\*?|gather\*?|multline\*?)\}",
+    re.DOTALL,
+)
+_PREAMBLE_LINES = (
+    "% !TeX program = xelatex",
+    "% Generated by DocVortex. Compile with: latexmk -xelatex <file>.tex",
+    r"\documentclass[UTF8,fontset=fandol,11pt]{ctexart}",
+    r"\usepackage[a4paper,margin=20mm]{geometry}",
+    r"\usepackage{amsmath,amssymb}",
+    r"\usepackage{graphicx}",
+    r"\usepackage{longtable}",
+    r"\usepackage{array}",
+    r"\usepackage{booktabs}",
+    r"\usepackage{multirow}",
+    r"\usepackage{enumitem}",
+    r"\usepackage[table]{xcolor}",
+    r"\usepackage[normalem]{ulem}",
+    r"\usepackage{xeCJKfntef}",
+    r"\usepackage{fvextra}",
+    r"\usepackage[unicode,hidelinks]{hyperref}",
+    r"\definecolor{DocVortexGray}{HTML}{6B7280}",
+    r"\definecolor{DocVortexSurface}{HTML}{F3F4F6}",
+    r"\definecolor{DocVortexTableHeader}{HTML}{E5E7EB}",
+    r"\setlength{\parindent}{2em}",
+    r"\setlength{\parskip}{0.4em}",
+    r"\setlist{leftmargin=*,nosep}",
+    r"\setlength{\LTpre}{0.4em}",
+    r"\setlength{\LTpost}{0.6em}",
+    r"\newcommand{\DocVortexLineBreak}{\leavevmode\hfill\break}",
+    r"\newcommand{\DocVortexPlaceholder}[1]{\fcolorbox{DocVortexGray}{DocVortexSurface}{\textit{#1}}}",
+)
+
+
+class _LatexRenderer:
+    """保存一次完整 LaTeX 文档渲染所需的确定性状态。"""
+
+    def __init__(
+        self,
+        middle_json: MiddleJson,
+        *,
+        asset_base_path: str,
+        document_title: str | None,
+    ) -> None:
+        """初始化共享 planner、anchor、表格与代码环境上下文。"""
+        self.middle_json = middle_json
+        self.asset_base_path = normalize_asset_base_path(asset_base_path)
+        self.document_title = _resolve_document_title(middle_json, document_title)
+        self.anchors = LatexAnchorRegistry(_collect_anchor_targets(middle_json))
+        self.tables = LatexTableRenderer(asset_base_path=self.asset_base_path, anchors=self.anchors)
+        self.verbatim_counter = 0
+
+    def render(self) -> str:
+        """生成包含固定 TeX Live 导言区与正文环境的完整源码。"""
+        rendered_blocks: list[str] = []
+        for page in build_render_plan(self.middle_json):
+            for planned in page:
+                if planned.removed or planned.block.type in PAGE_AUXILIARY_BLOCK_TYPES:
+                    continue
+                rendered = self._render_planned_block(planned)
+                if rendered.strip():
+                    rendered_blocks.append(rendered.strip("\n"))
+        title = escape_latex_text(self.document_title, preserve_newlines=False)
+        lines = [*_PREAMBLE_LINES, rf"\hypersetup{{pdftitle={{{title}}}}}", r"\begin{document}"]
+        if rendered_blocks:
+            lines.extend(("", "\n\n".join(rendered_blocks), ""))
+        lines.append(r"\end{document}")
+        return "\n".join(lines) + "\n"
+
+    def _render_planned_block(self, planned: PlannedBlock) -> str:
+        """按严格 PageBlock 具体类型分发 LaTeX 渲染。"""
+        block = planned.block
+        if isinstance(block, TextBlock):
+            content = render_joined_inline_contents(planned.text_contents or [block.content], self.anchors)
+            return self._anchored_paragraph(content, block.anchor)
+        if isinstance(block, RefTextBlock):
+            content = render_joined_inline_contents(planned.text_contents or [block.content], self.anchors)
+            return _paragraph(content)
+        if isinstance(block, (DocTitleBlock, ParagraphTitleBlock)):
+            return self._render_title(block)
+        if isinstance(block, PageFootnoteBlock):
+            return self._render_page_footnote(block)
+        if isinstance(block, EquationBlock):
+            return self._render_equation(block)
+        if isinstance(block, ListBlock):
+            return self._render_list(block)
+        if isinstance(block, IndexBlock):
+            return self._render_index(block)
+        if isinstance(block, ImageBlock):
+            return self._render_image_block(block)
+        if isinstance(block, TableBlock):
+            return self._render_table_block(block)
+        if isinstance(block, ChartBlock):
+            return self._render_chart_block(block)
+        if isinstance(block, CodeBlock):
+            return self._render_code_block(block)
+        raise TypeError(f"Unsupported PageBlock type: {type(block).__name__}")
+
+    def _anchored_paragraph(self, content: str, anchor: str | None) -> str:
+        """给可见正文添加首次出现的文档级 hypertarget。"""
+        if not content.strip():
+            return ""
+        target = self.anchors.emit_target(anchor)
+        return "\n".join(part for part in (target, _paragraph(content)) if part)
+
+    def _render_title(self, block: DocTitleBlock | ParagraphTitleBlock) -> str:
+        """把全局标题层级映射为无编号 LaTeX 标题命令。"""
+        content = render_inline_spans(block.content, self.anchors)
+        if not content.strip():
+            return ""
+        target = self.anchors.emit_target(block.anchor)
+        command = {
+            1: "section",
+            2: "subsection",
+            3: "subsubsection",
+            4: "paragraph",
+            5: "subparagraph",
+        }.get(block.level)
+        heading = rf"\{command}*{{{content}}}" if command is not None else rf"\par\noindent{{\small\bfseries {content}}}\par"
+        return "\n".join(part for part in (target, heading) if part)
+
+    def _render_page_footnote(self, block: PageFootnoteBlock) -> str:
+        """把页面脚注保留为可寻址的小字号灰色正文块。"""
+        content = render_inline_spans(block.content, self.anchors)
+        if not content.strip():
+            return ""
+        target = self.anchors.emit_target(block.anchor)
+        footnote = rf"{{\footnotesize\color{{DocVortexGray}} {content}\par}}"
+        return "\n".join(part for part in (target, footnote) if part)
+
+    def _render_equation(self, block: EquationBlock) -> str:
+        """原样输出块级 LaTeX；空公式按 sidecar 与占位顺序回退。"""
+        content = block.content.strip()
+        if content:
+            return _wrap_display_formula(content)
+        if not _has_image_payload(block):
+            return self._placeholder("formula unavailable") + r"\par"
+        return self._render_image_payload(block, alt_text="formula")
+
+    def _render_list(self, block: ListBlock) -> str:
+        """按共享 marker 分类递归输出原生或显式标记列表。"""
+        parsed_leaves = [
+            parse_list_item_marker(child.content)
+            for child in block.content
+            if not isinstance(child, ListBlock) and inline_plain_text(child.content).strip()
+        ]
+        add_reference_bullets = reference_list_needs_bullets(block)
+        environment, kind = _classify_list(parsed_leaves, add_reference_bullets)
+        options = "[leftmargin=*,nosep]"
+        if environment == "description":
+            options = "[style=nextline,leftmargin=3em,nosep]"
+        lines = [rf"\begin{{{environment}}}{options}"]
+        has_item = False
+        for child in block.content:
+            if isinstance(child, ListBlock):
+                nested = self._render_list(child)
+                if nested:
+                    if not has_item:
+                        lines.append(r"\item[]")
+                        has_item = True
+                    lines.append(nested)
+                continue
+            parsed = parse_list_item_marker(child.content)
+            item_spans, label = _list_item_content(parsed, child.content, kind, add_reference_bullets)
+            content = render_inline_spans(item_spans, self.anchors) or "~"
+            if environment == "description" or label is not None:
+                rendered_label = escape_latex_text(label or "", preserve_newlines=False)
+                lines.append(rf"\item[{{{rendered_label}}}] {content}")
+            else:
+                lines.append(rf"\item {content}")
+            has_item = True
+        lines.append(rf"\end{{{environment}}}")
+        return "\n".join(lines) if has_item else ""
+
+    def _render_index(self, block: IndexBlock) -> str:
+        """递归输出正文内目录，并仅链接真实 anchor target。"""
+        lines = [r"\begin{itemize}[leftmargin=*,nosep]"]
+        has_item = False
+        for child in block.content:
+            if isinstance(child, IndexBlock):
+                nested = self._render_index(child)
+                if nested:
+                    if not has_item:
+                        lines.append(r"\item[]")
+                        has_item = True
+                    lines.append(nested)
+                continue
+            content = strip_index_page_tail(child.content)
+            label = render_inline_spans(content, self.anchors).strip()
+            if not label:
+                continue
+            target = self.anchors.target_for(child.anchor)
+            if target is not None:
+                label = rf"\hyperlink{{{target}}}{{{label}}}"
+            lines.append(rf"\item {label}")
+            has_item = True
+        lines.append(r"\end{itemize}")
+        return "\n".join(lines) if has_item else ""
+
+    def _render_image_block(self, block: ImageBlock) -> str:
+        """按原始子块顺序输出图片主体及说明文本。"""
+        parts: list[str] = []
+        for child in block.content:
+            if isinstance(child, ImageBodyBlock):
+                alt = _plain_html_text(child.content) or block.sub_type or "image"
+                parts.append(self._render_image_payload(child, alt_text=alt))
+            elif isinstance(child, ImageAnnotationBlock):
+                parts.append(self._render_annotation(child))
+            else:
+                raise TypeError(f"Unsupported image child: {type(child).__name__}")
+        return _join_parts(parts)
+
+    def _render_table_block(self, block: TableBlock) -> str:
+        """优先输出原生 longtable，再回退图片、可见文本或占位。"""
+        parts: list[str] = []
+        for child in block.content:
+            if isinstance(child, TableBodyBlock):
+                parts.append(self._render_table_body(child))
+            elif isinstance(child, TableAnnotationBlock):
+                parts.append(self._render_annotation(child))
+            else:
+                raise TypeError(f"Unsupported table child: {type(child).__name__}")
+        return _join_parts(parts)
+
+    def _render_table_body(self, block: TableBodyBlock) -> str:
+        """执行结构化表格到 sidecar、文本、占位的固定回退链。"""
+        content = block.content.strip()
+        if content and _HTML_TABLE_RE.search(content):
+            try:
+                return self.tables.render(content)
+            except LatexTableError as exc:
+                logger.warning("LaTeX HTML table fallback: {}", exc)
+            image = self._render_local_image(block)
+            if image:
+                return image
+            plain = _plain_html_text(content)
+            if plain:
+                return self._render_verbatim(plain)
+            return self._placeholder("table unavailable")
+        if content:
+            return self._render_verbatim(block.content)
+        if not _has_image_payload(block):
+            return self._placeholder("table unavailable") + r"\par"
+        return self._render_image_payload(block, alt_text="table")
+
+    def _render_chart_block(self, block: ChartBlock) -> str:
+        """保留 chart 图片，并继续输出可物化的结构化表格。"""
+        parts: list[str] = []
+        for child in block.content:
+            if isinstance(child, ChartBodyBlock):
+                body_parts: list[str] = []
+                has_image_payload = bool(child.image_path or child.image_base64 or child.image_url)
+                local_image = self._render_local_image(child)
+                if local_image:
+                    body_parts.append(local_image)
+                elif has_image_payload:
+                    body_parts.append(self._render_image_payload(child, alt_text=block.sub_type or "chart"))
+                content = child.content.strip()
+                if content and _HTML_TABLE_RE.search(content):
+                    try:
+                        body_parts.append(self.tables.render(content))
+                    except LatexTableError as exc:
+                        logger.warning("LaTeX chart table fallback: {}", exc)
+                        plain = _plain_html_text(content)
+                        if plain:
+                            body_parts.append(_paragraph(escape_latex_text(plain)))
+                elif content and not local_image:
+                    body_parts.append(_paragraph(escape_latex_text(_plain_html_text(content))))
+                elif not has_image_payload and not content:
+                    body_parts.append(self._placeholder("chart unavailable"))
+                parts.append(_join_parts(body_parts))
+            elif isinstance(child, ChartAnnotationBlock):
+                parts.append(self._render_annotation(child))
+            else:
+                raise TypeError(f"Unsupported chart child: {type(child).__name__}")
+        return _join_parts(parts)
+
+    def _render_code_block(self, block: CodeBlock) -> str:
+        """输出保留空白的代码或包含公式的算法正文及说明。"""
+        parts: list[str] = []
+        for child in block.content:
+            if isinstance(child, CodeBodyBlock):
+                if block.sub_type != BlockType.CODE:
+                    raise TypeError("code_body requires code subtype")
+                parts.append(self._render_verbatim(child.content))
+            elif isinstance(child, AlgorithmBodyBlock):
+                if block.sub_type != RAW_ALGORITHM:
+                    raise TypeError("algorithm_body requires algorithm subtype")
+                content = render_inline_spans(child.content, self.anchors)
+                parts.append("\n".join((r"\begin{quote}", rf"{{\small\ttfamily {content}\par}}", r"\end{quote}")))
+            elif isinstance(child, CodeAnnotationBlock):
+                parts.append(self._render_annotation(child))
+            else:
+                raise TypeError(f"Unsupported code child: {type(child).__name__}")
+        return _join_parts(parts)
+
+    def _render_annotation(
+        self,
+        block: ImageAnnotationBlock | TableAnnotationBlock | ChartAnnotationBlock | CodeAnnotationBlock,
+    ) -> str:
+        """按 caption/footnote discriminator 输出弱化说明样式。"""
+        content = render_inline_spans(block.content, self.anchors)
+        if not content.strip():
+            return ""
+        if str(block.type).endswith("caption"):
+            return rf"{{\small\itshape {content}\par}}"
+        return rf"{{\footnotesize\color{{DocVortexGray}} {content}\par}}"
+
+    def _render_image_payload(self, block: ImagePayloadBlock, *, alt_text: str) -> str:
+        """输出本地 sidecar；其它来源降级为链接或可见占位。"""
+        local = self._render_local_image(block)
+        if local:
+            return local
+        label = self._placeholder(f"image unavailable: {alt_text}")
+        remote_url = remote_block_image_url(block)
+        if remote_url:
+            return rf"\href{{{escape_latex_url(remote_url)}}}{{{label}}}\par"
+        return label + r"\par"
+
+    def _render_local_image(self, block: ImagePayloadBlock) -> str:
+        """若存在 XeLaTeX 支持的安全 sidecar，则生成有界 includegraphics。"""
+        path = resolve_block_image_path(block, self.asset_base_path)
+        if path is None:
+            return ""
+        return (
+            rf"\noindent\includegraphics[width=\linewidth,height=.8\textheight,keepaspectratio]"
+            rf"{{{tex_image_path(path)}}}\par"
+        )
+
+    def _placeholder(self, message: str) -> str:
+        """生成不暴露二进制载荷的稳定可见占位。"""
+        return rf"\DocVortexPlaceholder{{{escape_latex_text(message, preserve_newlines=False)}}}"
+
+    def _render_verbatim(self, content: str) -> str:
+        """为每个预格式块选择正文无法提前闭合的唯一 fvextra 环境。"""
+        normalized = content.replace("\r\n", "\n").replace("\r", "\n")
+        while True:
+            self.verbatim_counter += 1
+            environment = f"DocVortexVerbatim{self.verbatim_counter}"
+            if rf"\end{{{environment}}}" not in normalized:
+                break
+        definition = (
+            rf"\DefineVerbatimEnvironment{{{environment}}}{{Verbatim}}"
+            r"{breaklines=true,breakanywhere=true,fontsize=\small}"
+        )
+        return "\n".join((definition, rf"\begin{{{environment}}}", normalized, rf"\end{{{environment}}}"))
+
+
+def render_latex(
+    middle_json: MiddleJson,
+    *,
+    asset_base_path: str = "",
+    document_title: str | None = None,
+) -> str:
+    """把严格 MiddleJson 纯函数式渲染为 TeX Live XeLaTeX 完整源码。"""
+    if not isinstance(middle_json, MiddleJson):
+        raise TypeError("render_latex expects a MiddleJson instance")
+    if not isinstance(asset_base_path, str):
+        raise TypeError("asset_base_path must be a string")
+    if document_title is not None and not isinstance(document_title, str):
+        raise TypeError("document_title must be a string or None")
+    return _LatexRenderer(
+        middle_json,
+        asset_base_path=asset_base_path,
+        document_title=document_title,
+    ).render()
+
+
+def _resolve_document_title(middle_json: MiddleJson, explicit: str | None) -> str:
+    """按显式标题、首个文档标题和固定回退值解析 metadata title。"""
+    if explicit is not None and explicit.strip():
+        return explicit.strip()
+    for page in middle_json.pages:
+        for block in page.blocks:
+            if isinstance(block, DocTitleBlock):
+                title = inline_plain_text(block.content).strip()
+                if title:
+                    return title
+    return "DocVortex Document"
+
+
+def _collect_anchor_targets(middle_json: MiddleJson) -> set[str]:
+    """收集真实可见的正文、标题和页面脚注 anchor。"""
+    targets: set[str] = set()
+    for page in middle_json.pages:
+        for block in page.blocks:
+            if not isinstance(block, (TextBlock, TitleBlockBase, PageFootnoteBlock)):
+                continue
+            anchor = (block.anchor or "").strip()
+            if anchor and inline_plain_text(block.content).strip():
+                targets.add(anchor)
+    return targets
+
+
+def _classify_list(items: list[ListItem], add_reference_bullets: bool) -> tuple[str, str]:
+    """根据直属 marker 选择 LaTeX 列表环境和内容策略。"""
+    if add_reference_bullets:
+        return "itemize", "reference"
+    if items and all(item.kind == "unordered" for item in items):
+        return "itemize", "unordered"
+    if items and all(item.kind == "ordered" for item in items):
+        styles = {item.ordered_style for item in items}
+        if len(styles) == 1:
+            return "enumerate", "ordered"
+    if items and all(item.kind == "none" for item in items):
+        return "itemize", "unmarked"
+    return "description", "explicit"
+
+
+def _list_item_content(
+    item: ListItem,
+    original: list[InlineSpan],
+    kind: str,
+    add_reference_bullets: bool,
+) -> tuple[list[InlineSpan], str | None]:
+    """决定列表项应剥离、保留还是显式显示源 marker。"""
+    if add_reference_bullets:
+        return (item.body, None) if item.kind == "unordered" else (original, None)
+    if kind == "unordered":
+        return item.body, None
+    if kind == "ordered":
+        return item.body, item.marker
+    if kind == "unmarked":
+        return item.body, None
+    return item.body, item.marker
+
+
+def _paragraph(content: str) -> str:
+    """把非空行内源码收束为一个普通 LaTeX 段落。"""
+    return f"{content}\\par" if content.strip() else ""
+
+
+def _wrap_display_formula(content: str) -> str:
+    """保留完整 AMS display 环境，其它裸公式统一放入 equation*。"""
+    match = _TOP_LEVEL_DISPLAY_ENV_RE.match(content)
+    if match is not None and content.rstrip().endswith(rf"\end{{{match.group('name')}}}"):
+        return content
+    return "\n".join((r"\begin{equation*}", content, r"\end{equation*}"))
+
+
+def _join_parts(parts: list[str]) -> str:
+    """按子块源顺序连接全部非空 LaTeX 片段。"""
+    return "\n\n".join(part for part in parts if part and part.strip())
+
+
+def _plain_html_text(content: str) -> str:
+    """从 HTML 或普通字符串提取可见文本供替代信息使用。"""
+    if not content:
+        return ""
+    return BeautifulSoup(content, "html.parser").get_text("\n", strip=True)
+
+
+def _has_image_payload(block: ImagePayloadBlock) -> bool:
+    """判断 block 是否声明任一种图片来源。"""
+    return bool(block.image_path or block.image_base64 or block.image_url)
+
+
+__all__ = ["render_latex"]