regen.mde 0.2.2 → 0.7.0

package/src/build_corpus/docx_exporter.py

@@ -1,798 +1,1055 @@
-from __future__ import annotations
-
-import json
-import os
-import re
-import shutil
-import subprocess
-import tempfile
-from html.parser import HTMLParser
-from contextlib import ExitStack
-from dataclasses import dataclass, field
-from importlib.resources import as_file, files
-from pathlib import Path
-from zipfile import ZipFile
-
-from docx import Document
-from docx.enum.style import WD_STYLE_TYPE
-from docx.enum.text import WD_BREAK
-from docx.oxml import OxmlElement
-from docx.oxml.ns import qn
-from docx.shared import Inches, Pt, RGBColor
-from docx.image.exceptions import UnrecognizedImageError
-
-
-INLINE_TOKEN_RE = re.compile(
-    r"(!\[[^\]]*\]\([^)]+\)|\[[^\]]+\]\([^)]+\)|`[^`]+`|\$\$[^$]+\$\$|\$[^$\n]+\$|\*\*\*.+?\*\*\*|\*\*.+?\*\*|\*.+?\*)"
-)
-BARE_URL_RE = re.compile(r"https?://[^\s<>()]+(?:\([^\s<>()]*\)[^\s<>()]*)*")
-LIST_ITEM_RE = re.compile(r"^(\s*)([-*+]|\d+\.)\s+(.*)$")
-TABLE_SEPARATOR_RE = re.compile(r"^\s*\|?(?:\s*:?-{3,}:?\s*\|)+\s*:?-{3,}:?\s*\|?\s*$")
-DEFAULT_TEMPLATE_FILENAME = "md-to-word-template.dotx"
-
-
-@dataclass
-class WordExportStats:
-    paragraphs: int = 0
-    headings: int = 0
-    lists: int = 0
-    tables: int = 0
-    code_blocks: int = 0
-    blockquotes: int = 0
-    images: int = 0
-    equations: int = 0
-    warnings: list[str] = field(default_factory=list)
-
-
-def strip_fence(line: str) -> str:
-    return line.strip()[3:].strip()
-
-
-def split_table_row(line: str) -> list[str]:
-    text = line.strip()
-    if text.startswith("|"):
-        text = text[1:]
-    if text.endswith("|"):
-        text = text[:-1]
-    cells: list[str] = []
-    buffer: list[str] = []
-    escape = False
-    for char in text:
-        if escape:
-            buffer.append(char)
-            escape = False
-            continue
-        if char == "\\":
-            escape = True
-            buffer.append(char)
-            continue
-        if char == "|":
-            cells.append("".join(buffer).strip())
-            buffer.clear()
-            continue
-        buffer.append(char)
-    cells.append("".join(buffer).strip())
-    return cells
-
-
-def markdown_link_parts(token: str) -> tuple[str, str]:
-    match = re.fullmatch(r"!?\[([^\]]*)\]\(([^)]+)\)", token)
-    if not match:
-        return token, ""
-    return match.group(1), match.group(2).strip()
-
-
-def unescape_markdown_text(text: str) -> str:
-    return re.sub(r"\\([\\`*_{}\[\]()#+.!|$-])", r"\1", text)
-
-
-class HTMLTableParser(HTMLParser):
-    def __init__(self) -> None:
-        super().__init__()
-        self.rows: list[list[str]] = []
-        self.current_row: list[str] | None = None
-        self.current_cell: list[str] | None = None
-
-    def handle_starttag(self, tag: str, attrs) -> None:  # type: ignore[override]
-        normalized = tag.lower()
-        if normalized == "tr":
-            self.current_row = []
-        elif normalized == "td":
-            self.current_cell = []
-        elif normalized == "br" and self.current_cell is not None:
-            self.current_cell.append("\n")
-
-    def handle_endtag(self, tag: str) -> None:  # type: ignore[override]
-        normalized = tag.lower()
-        if normalized == "td" and self.current_row is not None and self.current_cell is not None:
-            self.current_row.append("".join(self.current_cell).strip())
-            self.current_cell = None
-        elif normalized == "tr" and self.current_row is not None:
-            self.rows.append(self.current_row)
-            self.current_row = None
-
-    def handle_data(self, data: str) -> None:  # type: ignore[override]
-        if self.current_cell is not None:
-            self.current_cell.append(data)
-
-
-def parse_html_table(markup: str) -> list[list[str]]:
-    parser = HTMLTableParser()
-    parser.feed(markup)
-    parser.close()
-    return [row for row in parser.rows if any(cell.strip() for cell in row)]
-
-
-def packaged_template_resource():
-    package_root = f"{__package__}.templates" if __package__ else "build_corpus.templates"
-    return files(package_root).joinpath(DEFAULT_TEMPLATE_FILENAME)
-
-
-def resolve_default_template_path() -> Path | None:
-    try:
-        packaged_template_resource()
-    except ModuleNotFoundError:
-        return None
-    return Path(f"bundled:{DEFAULT_TEMPLATE_FILENAME}")
-
-
-def set_cell_text(cell, text: str) -> None:
-    lines = [segment.strip() for segment in text.replace("<br>", "\n").splitlines()]
-    lines = [line for line in lines if line]
-    if not lines:
-        cell.text = ""
-        return []
-    return lines
-
-
-def append_text_with_breaks(paragraph, text: str) -> None:
-    text = unescape_markdown_text(text)
-    parts = text.split("\n")
-    for index, part in enumerate(parts):
-        if part:
-            paragraph.add_run(part)
-        if index < len(parts) - 1:
-            paragraph.add_run().add_break(WD_BREAK.LINE)
-
-
-def split_trailing_url_punctuation(url: str) -> tuple[str, str]:
-    trailing = []
-    core = url
-    while core and core[-1] in ".,;:!?":
-        trailing.append(core[-1])
-        core = core[:-1]
-    return core, "".join(reversed(trailing))
-
-
-def convert_windows_metafile_to_png(source: Path) -> Path | None:
-    if os.name != "nt":
-        return None
-    target_dir = Path(tempfile.gettempdir()) / "build-corpus-image-fallbacks"
-    target_dir.mkdir(parents=True, exist_ok=True)
-    target = target_dir / f"{source.stem}.png"
-    source_literal = str(source).replace("'", "''")
-    target_literal = str(target).replace("'", "''")
-    command = (
-        "Add-Type -AssemblyName System.Drawing; "
-        f"$img = [System.Drawing.Image]::FromFile('{source_literal}'); "
-        f"$bmp = New-Object System.Drawing.Bitmap $img.Width, $img.Height; "
-        "$gfx = [System.Drawing.Graphics]::FromImage($bmp); "
-        "$gfx.DrawImage($img, 0, 0, $img.Width, $img.Height); "
-        f"$bmp.Save('{target_literal}', [System.Drawing.Imaging.ImageFormat]::Png); "
-        "$gfx.Dispose(); $bmp.Dispose(); $img.Dispose()"
-    )
-    result = subprocess.run(
-        ["powershell", "-NoProfile", "-Command", command],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0 or not target.exists():
-        return None
-    return target
-
-
-def set_paragraph_shading(paragraph, fill: str) -> None:
-    paragraph_pr = paragraph._p.get_or_add_pPr()
-    shading = paragraph_pr.find(qn("w:shd"))
-    if shading is None:
-        shading = OxmlElement("w:shd")
-        paragraph_pr.append(shading)
-    shading.set(qn("w:fill"), fill)
-
-
-def set_paragraph_border(paragraph, color: str) -> None:
-    paragraph_pr = paragraph._p.get_or_add_pPr()
-    borders = paragraph_pr.find(qn("w:pBdr"))
-    if borders is None:
-        borders = OxmlElement("w:pBdr")
-        paragraph_pr.append(borders)
-    left = borders.find(qn("w:left"))
-    if left is None:
-        left = OxmlElement("w:left")
-        borders.append(left)
-    left.set(qn("w:val"), "single")
-    left.set(qn("w:sz"), "10")
-    left.set(qn("w:space"), "12")
-    left.set(qn("w:color"), color)
-
-
-def add_hyperlink(paragraph, text: str, url: str):
-    part = paragraph.part
-    relationship_id = part.relate_to(
-        url,
-        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
-        is_external=True,
-    )
-    hyperlink = OxmlElement("w:hyperlink")
-    hyperlink.set(qn("r:id"), relationship_id)
-
-    run = OxmlElement("w:r")
-    rpr = OxmlElement("w:rPr")
-
-    color = OxmlElement("w:color")
-    color.set(qn("w:val"), "2563EB")
-    rpr.append(color)
-
-    underline = OxmlElement("w:u")
-    underline.set(qn("w:val"), "single")
-    rpr.append(underline)
-    run.append(rpr)
-
-    text_node = OxmlElement("w:t")
-    text_node.text = text
-    run.append(text_node)
-    hyperlink.append(run)
-    paragraph._p.append(hyperlink)
-    return hyperlink
-
-
-def append_hyperlink_run(hyperlink, text: str, bold: bool = False, italic: bool = False, code: bool = False) -> None:
-    run = OxmlElement("w:r")
-    rpr = OxmlElement("w:rPr")
-
-    color = OxmlElement("w:color")
-    color.set(qn("w:val"), "2563EB")
-    rpr.append(color)
-
-    underline = OxmlElement("w:u")
-    underline.set(qn("w:val"), "single")
-    rpr.append(underline)
-
-    if bold:
-        rpr.append(OxmlElement("w:b"))
-    if italic:
-        rpr.append(OxmlElement("w:i"))
-
-    fonts_needed = code
-    if fonts_needed:
-        fonts = OxmlElement("w:rFonts")
-        fonts.set(qn("w:ascii"), "Consolas")
-        fonts.set(qn("w:hAnsi"), "Consolas")
-        fonts.set(qn("w:cs"), "Consolas")
-        rpr.append(fonts)
-        size = OxmlElement("w:sz")
-        size.set(qn("w:val"), "20")
-        rpr.append(size)
-
-    run.append(rpr)
-    text_node = OxmlElement("w:t")
-    text_node.text = text
-    run.append(text_node)
-    hyperlink.append(run)
-
-
-def set_picture_metadata(run, source_name: str) -> None:
-    filename = Path(source_name).name
-    try:
-        doc_props = run._r.xpath(".//*[local-name()='docPr']")
-    except Exception:
-        doc_props = []
-    for doc_prop in doc_props:
-        doc_prop.set("name", filename)
-        doc_prop.set("descr", filename)
-        doc_prop.set("title", filename)
-
-
-class MarkdownToDocxExporter:
-    def __init__(
-        self,
-        input_path: Path,
-        output_dir: Path,
-        output_docx: Path | None = None,
-        report_path: Path | None = None,
-        template_path: Path | None = None,
-    ):
-        self.input_path = input_path
-        self.output_dir = output_dir
-        self.output_docx = output_docx or (output_dir / f"{input_path.stem}.docx")
-        self.report_path = report_path or (output_dir / "export-report.json")
-        self._template_resource_stack = ExitStack()
-        self.template_path = self.resolve_template_path(template_path)
-        self.use_template_styles = self.template_path is not None
-        self.stats = WordExportStats()
-
-    def export(self) -> dict:
-        try:
-            self.output_dir.mkdir(parents=True, exist_ok=True)
-            if self.template_path and not self.template_path.exists():
-                raise FileNotFoundError(f"Word template not found: {self.template_path}")
-
-            document = Document()
-            if not self.template_path:
-                self.apply_modern_styles(document)
-            self.ensure_custom_styles(document)
-
-            markdown = self.input_path.read_text(encoding="utf-8")
-            self.render_markdown(document, markdown)
-            document.save(self.output_docx)
-            if self.template_path:
-                self.apply_template_package(self.output_docx, self.template_path)
-
-            report = {
-                "input": str(self.input_path),
-                "output": str(self.output_docx),
-                "template": str(self.template_path) if self.template_path else None,
-                "stats": self.stats.__dict__,
-            }
-            self.report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
-            return report
-        finally:
-            self._template_resource_stack.close()
-
-    def resolve_template_path(self, template_path: Path | None) -> Path | None:
-        if template_path is not None:
-            return Path(template_path)
-
-        try:
-            return self._template_resource_stack.enter_context(as_file(packaged_template_resource()))
-        except (FileNotFoundError, ModuleNotFoundError):
-            return None
-
-    def apply_modern_styles(self, document: Document) -> None:
-        section = document.sections[0]
-        section.top_margin = Inches(0.8)
-        section.bottom_margin = Inches(0.8)
-        section.left_margin = Inches(0.9)
-        section.right_margin = Inches(0.9)
-
-        normal = document.styles["Normal"]
-        normal.font.name = "Aptos"
-        normal.font.size = Pt(11)
-        normal.font.color.rgb = RGBColor(31, 41, 55)
-        normal.paragraph_format.space_after = Pt(8)
-        normal.paragraph_format.line_spacing = 1.15
-
-        for level, size in ((1, 22), (2, 17), (3, 14), (4, 12)):
-            style = document.styles[f"Heading {level}"]
-            style.font.name = "Aptos Display"
-            style.font.size = Pt(size)
-            style.font.bold = True
-            style.font.color.rgb = RGBColor(15, 23, 42)
-            style.paragraph_format.space_before = Pt(12 if level == 1 else 10)
-            style.paragraph_format.space_after = Pt(4)
-
-        self.ensure_custom_styles(document)
-
-    def ensure_custom_styles(self, document: Document) -> None:
-        if self.use_template_styles:
-            return
-        if "BuildCorpus Code" not in document.styles:
-            style = document.styles.add_style("BuildCorpus Code", WD_STYLE_TYPE.PARAGRAPH)
-            style.base_style = document.styles["Normal"]
-            style.font.name = "Consolas"
-            style.font.size = Pt(10)
-            style.paragraph_format.left_indent = Inches(0.2)
-            style.paragraph_format.right_indent = Inches(0.2)
-            style.paragraph_format.space_before = Pt(4)
-            style.paragraph_format.space_after = Pt(6)
-
-        if "BuildCorpus Quote" not in document.styles:
-            style = document.styles.add_style("BuildCorpus Quote", WD_STYLE_TYPE.PARAGRAPH)
-            style.base_style = document.styles["Normal"]
-            style.font.italic = True
-            style.font.color.rgb = RGBColor(71, 85, 105)
-            style.paragraph_format.left_indent = Inches(0.35)
-            style.paragraph_format.space_after = Pt(6)
-
-    def render_markdown(self, document: Document, markdown: str) -> None:
-        lines = markdown.splitlines()
-        index = 0
-        while index < len(lines):
-            line = lines[index]
-            stripped = line.strip()
-
-            if not stripped:
-                index += 1
-                continue
-
-            if stripped.startswith("```"):
-                info = strip_fence(line)
-                buffer: list[str] = []
-                index += 1
-                while index < len(lines) and not lines[index].strip().startswith("```"):
-                    buffer.append(lines[index])
-                    index += 1
-                if index < len(lines):
-                    index += 1
-                self.add_code_block(document, "\n".join(buffer), info)
-                continue
-
-            if stripped == "$$":
-                buffer: list[str] = []
-                index += 1
-                while index < len(lines) and lines[index].strip() != "$$":
-                    buffer.append(lines[index])
-                    index += 1
-                if index < len(lines):
-                    index += 1
-                self.add_equation_block(document, "\n".join(buffer).strip())
-                continue
-
-            if stripped.startswith("$$") and stripped.endswith("$$") and len(stripped) > 4:
-                self.add_equation_block(document, stripped[2:-2].strip())
-                index += 1
-                continue
-
-            if stripped.startswith("#"):
-                level = len(stripped) - len(stripped.lstrip("#"))
-                text = stripped[level:].strip()
-                self.add_heading(document, level, text)
-                index += 1
-                continue
-
-            if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
-                table_lines = [line, lines[index + 1]]
-                index += 2
-                while index < len(lines) and "|" in lines[index]:
-                    if not lines[index].strip():
-                        break
-                    table_lines.append(lines[index])
-                    index += 1
-                self.add_table(document, table_lines)
-                continue
-
-            if stripped.lower() == "<table>":
-                table_lines = [line]
-                index += 1
-                while index < len(lines):
-                    table_lines.append(lines[index])
-                    if lines[index].strip().lower() == "</table>":
-                        index += 1
-                        break
-                    index += 1
-                self.add_html_table(document, "\n".join(table_lines))
-                continue
-
-            list_match = LIST_ITEM_RE.match(line)
-            if list_match:
-                index = self.add_list(document, lines, index)
-                continue
-
-            if stripped.startswith(">"):
-                quote_lines: list[str] = []
-                while index < len(lines) and lines[index].strip().startswith(">"):
-                    quote_lines.append(lines[index].strip()[1:].strip())
-                    index += 1
-                self.add_blockquote(document, " ".join(quote_lines))
-                continue
-
-            if re.fullmatch(r"[-*_]{3,}", stripped):
-                document.add_paragraph("")
-                index += 1
-                continue
-
-            paragraph_lines = [line.strip()]
-            paragraph_lines = [line.rstrip()]
-            paragraph_breaks = [line.endswith("  ") or line.endswith("\\")]
-            index += 1
-            while index < len(lines):
-                candidate = lines[index]
-                if not candidate.strip():
-                    break
-                if candidate.strip().startswith(("```", "#", ">")):
-                    break
-                if LIST_ITEM_RE.match(candidate):
-                    break
-                if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
-                    break
-                paragraph_lines.append(candidate.rstrip())
-                paragraph_breaks.append(candidate.endswith("  ") or candidate.endswith("\\"))
-                index += 1
-            self.add_paragraph(document, self.combine_paragraph_lines(paragraph_lines, paragraph_breaks))
-
-    @staticmethod
-    def combine_paragraph_lines(lines: list[str], breaks: list[bool]) -> str:
-        if not lines:
-            return ""
-        combined = lines[0]
-        for index in range(1, len(lines)):
-            separator = "\n" if breaks[index - 1] else " "
-            combined += separator + lines[index]
-        return combined
-
-    @staticmethod
-    def apply_template_package(output_docx: Path, template_path: Path) -> None:
-        transplant_parts = {
-            "word/styles.xml",
-            "word/stylesWithEffects.xml",
-            "word/numbering.xml",
-            "word/fontTable.xml",
-            "word/settings.xml",
-            "word/webSettings.xml",
-            "word/theme/theme1.xml",
-        }
-        with tempfile.TemporaryDirectory(prefix="build-corpus-template-") as tmp:
-            tmp_dir = Path(tmp)
-            patched = tmp_dir / output_docx.name
-            with ZipFile(output_docx) as out_zip, ZipFile(template_path) as template_zip, ZipFile(patched, "w") as patched_zip:
-                template_names = set(template_zip.namelist())
-                output_names = set(out_zip.namelist())
-                for name in out_zip.namelist():
-                    if name in transplant_parts and name in template_names:
-                        patched_zip.writestr(name, template_zip.read(name))
-                    else:
-                        patched_zip.writestr(name, out_zip.read(name))
-                for name in transplant_parts:
-                    if name in template_names and name not in output_names:
-                        patched_zip.writestr(name, template_zip.read(name))
-            shutil.move(str(patched), output_docx)
-
-    def add_heading(self, document: Document, level: int, text: str) -> None:
-        paragraph = document.add_paragraph(style=f"Heading {min(level, 6)}")
-        self.render_inline(paragraph, text)
-        self.stats.headings += 1
-
-    def add_paragraph(self, document: Document, text: str) -> None:
-        paragraph = document.add_paragraph(style="Normal")
-        self.render_inline(paragraph, text)
-        self.stats.paragraphs += 1
-
-    def add_code_block(self, document: Document, code: str, info: str) -> None:
-        paragraph = document.add_paragraph(style="Normal" if self.use_template_styles else "BuildCorpus Code")
-        if info:
-            label = paragraph.add_run(f"{info}\n")
-            label.bold = True
-            label.font.color.rgb = RGBColor(37, 99, 235)
-        run = paragraph.add_run(code)
-        run.font.name = "Consolas"
-        run.font.size = Pt(10)
-        set_paragraph_shading(paragraph, "F8FAFC")
-        self.stats.code_blocks += 1
-
-    def add_equation_block(self, document: Document, equation: str) -> None:
-        paragraph = document.add_paragraph(style="Normal")
-        paragraph.paragraph_format.left_indent = Inches(0.3)
-        paragraph.paragraph_format.right_indent = Inches(0.3)
-        paragraph.paragraph_format.space_before = Pt(4)
-        paragraph.paragraph_format.space_after = Pt(8)
-        run = paragraph.add_run(equation)
-        run.font.name = "Cambria Math"
-        run.font.size = Pt(11)
-        self.stats.equations += 1
-
-    def add_blockquote(self, document: Document, text: str) -> None:
-        paragraph = document.add_paragraph(style="Quote" if self.use_template_styles else "BuildCorpus Quote")
-        self.render_inline(paragraph, text)
-        set_paragraph_border(paragraph, "CBD5E1")
-        self.stats.blockquotes += 1
-
-    def add_list(self, document: Document, lines: list[str], start: int) -> int:
-        index = start
-        while index < len(lines):
-            match = LIST_ITEM_RE.match(lines[index])
-            if not match:
-                break
-            indent, marker, body = match.groups()
-            ordered = marker.endswith(".")
-            body_lines = [body]
-            lookahead = index + 1
-            while lookahead < len(lines):
-                candidate = lines[lookahead]
-                stripped = candidate.strip()
-                if not stripped:
-                    break
-                if candidate.strip().startswith(("```", "#", ">")):
-                    break
-                if LIST_ITEM_RE.match(candidate):
-                    break
-                if TABLE_SEPARATOR_RE.match(lines[lookahead + 1]) if lookahead + 1 < len(lines) else False:
-                    break
-                if not candidate[:1].isspace():
-                    break
-                body_lines.append(candidate.rstrip())
-                lookahead += 1
-            style_name = self.list_style_name(document, ordered, indent)
-            paragraph = document.add_paragraph(style=style_name)
-            if style_name in {"List Bullet", "List Number"}:
-                paragraph.paragraph_format.left_indent = Inches(0.25 + (len(indent.replace("\t", "  ")) // 2) * 0.18)
-            self.render_inline(paragraph, "\n".join(body_lines))
-            self.stats.lists += 1
-            index = lookahead
-        return index
-
-    def list_style_name(self, document: Document, ordered: bool, indent: str) -> str:
-        level = min(3, max(1, (len(indent.replace("\t", "  ")) // 2) + 1))
-        base = "List Number" if ordered else "List Bullet"
-        candidate = base if level == 1 else f"{base} {level}"
-        return candidate if candidate in document.styles else base
-
-    def add_table(self, document: Document, table_lines: list[str]) -> None:
-        rows = [split_table_row(line) for line in table_lines if not TABLE_SEPARATOR_RE.match(line)]
-        self.add_table_rows(document, rows)
-
-    def add_html_table(self, document: Document, table_markup: str) -> None:
-        self.add_table_rows(document, parse_html_table(table_markup))
-
-    def add_table_rows(self, document: Document, rows: list[list[str]]) -> None:
-        if not rows:
-            return
-        width = max(len(row) for row in rows)
-        table = document.add_table(rows=len(rows), cols=width)
-        table.style = "Light List Accent 1" if "Light List Accent 1" in document.styles else "Table Grid"
-        for row_index, row in enumerate(rows):
-            for col_index in range(width):
-                value = row[col_index] if col_index < len(row) else ""
-                self.render_table_cell(table.cell(row_index, col_index), value)
-        self.stats.tables += 1
-
-    def render_table_cell(self, cell, text: str) -> None:
-        lines = set_cell_text(cell, text)
-        if not lines:
-            cell.text = ""
-            return
-        first = cell.paragraphs[0]
-        first.text = ""
-        self.render_inline(first, lines[0])
-        for line in lines[1:]:
-            paragraph = cell.add_paragraph("")
-            self.render_inline(paragraph, line)
-
-    def render_inline(self, paragraph, text: str) -> None:
-        cursor = 0
-        for match in INLINE_TOKEN_RE.finditer(text):
-            if match.start() > cursor:
-                self.render_plain_text(paragraph, text[cursor:match.start()])
-            token = match.group(0)
-            self.render_inline_token(paragraph, token)
-            cursor = match.end()
-        if cursor < len(text):
-            self.render_plain_text(paragraph, text[cursor:])
-
-    def render_plain_text(self, paragraph, text: str) -> None:
-        cursor = 0
-        for match in BARE_URL_RE.finditer(text):
-            if match.start() > cursor:
-                append_text_with_breaks(paragraph, text[cursor:match.start()])
-            url = match.group(0)
-            normalized_url, trailing = split_trailing_url_punctuation(url)
-            if normalized_url:
-                add_hyperlink(paragraph, normalized_url, normalized_url)
-            if trailing:
-                append_text_with_breaks(paragraph, trailing)
-            cursor = match.end()
-        if cursor < len(text):
-            append_text_with_breaks(paragraph, text[cursor:])
-
-    def render_inline_token(self, paragraph, token: str) -> None:
-        if token.startswith("!["):
-            alt, target = markdown_link_parts(token)
-            image_path = (self.input_path.parent / target).resolve()
-            if target.startswith(("http://", "https://", "data:")):
-                paragraph.add_run(f"[image: {alt or target}]")
-                self.stats.warnings.append(f"Skipped non-local image target: {target}")
-                return
-            if image_path.exists():
-                run = paragraph.add_run()
-                try:
-                    run.add_picture(str(image_path), width=Inches(5.8))
-                    set_picture_metadata(run, target)
-                    self.stats.images += 1
-                except UnrecognizedImageError:
-                    converted = convert_windows_metafile_to_png(image_path)
-                    if converted is not None:
-                        run.add_picture(str(converted), width=Inches(5.8))
-                        set_picture_metadata(run, target)
-                        self.stats.images += 1
-                        self.stats.warnings.append(f"Converted unsupported image to PNG: {target}")
-                    else:
-                        paragraph.add_run(f"[unsupported image: {target}]")
-                        self.stats.warnings.append(f"Unsupported image asset: {target}")
-            else:
-                paragraph.add_run(f"[missing image: {target}]")
-                self.stats.warnings.append(f"Missing image asset: {target}")
-            return
-
-        if token.startswith("["):
-            label, target = markdown_link_parts(token)
-            hyperlink = add_hyperlink(paragraph, "", target)
-            self.render_hyperlink_label(hyperlink, label)
-            return
-
-        if token.startswith("`"):
-            run = paragraph.add_run(token[1:-1])
-            run.font.name = "Consolas"
-            run.font.size = Pt(10)
-            return
-
-        if token.startswith("$$") and token.endswith("$$"):
-            run = paragraph.add_run(token[2:-2])
-            run.font.name = "Cambria Math"
-            run.font.size = Pt(11)
-            self.stats.equations += 1
-            return
-
-        if token.startswith("$") and token.endswith("$"):
-            run = paragraph.add_run(token[1:-1])
-            run.font.name = "Cambria Math"
-            run.font.size = Pt(11)
-            self.stats.equations += 1
-            return
-
-        if token.startswith("***") and token.endswith("***"):
-            run = paragraph.add_run(token[3:-3])
-            run.bold = True
-            run.italic = True
-            return
-
-        if token.startswith("**") and token.endswith("**"):
-            run = paragraph.add_run(token[2:-2])
-            run.bold = True
-            return
-
-        if token.startswith("*") and token.endswith("*"):
-            run = paragraph.add_run(token[1:-1])
-            run.italic = True
-            return
-
-        paragraph.add_run(token)
-
-    def render_hyperlink_label(self, hyperlink, text: str) -> None:
-        cursor = 0
-        for match in INLINE_TOKEN_RE.finditer(text):
-            if match.start() > cursor:
-                append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:match.start()]))
-            token = match.group(0)
-            self.render_hyperlink_token(hyperlink, token)
-            cursor = match.end()
-        if cursor < len(text):
-            append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:]))
-
-    def render_hyperlink_token(self, hyperlink, token: str) -> None:
-        if token.startswith("`") and token.endswith("`"):
-            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), code=True)
-            return
-        if token.startswith("***") and token.endswith("***"):
-            append_hyperlink_run(hyperlink, unescape_markdown_text(token[3:-3]), bold=True, italic=True)
-            return
-        if token.startswith("**") and token.endswith("**"):
-            append_hyperlink_run(hyperlink, unescape_markdown_text(token[2:-2]), bold=True)
-            return
-        if token.startswith("*") and token.endswith("*"):
-            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), italic=True)
-            return
-        append_hyperlink_run(hyperlink, unescape_markdown_text(token))
-
-
-def export_markdown_to_docx(
-    input_path: Path,
-    output_root: Path,
-    out_same_dir: bool,
-    template_path: Path | None = None,
-) -> dict:
-    if out_same_dir:
-        output_dir = input_path.parent
-        output_docx = input_path.with_suffix(".docx")
-        report_path = input_path.with_name(f"{input_path.stem}.export-report.json")
-    else:
-        output_dir = output_root / input_path.stem
-        output_docx = None
-        report_path = None
-
-    exporter = MarkdownToDocxExporter(
-        input_path=input_path,
-        output_dir=output_dir,
-        output_docx=output_docx,
-        report_path=report_path,
-        template_path=template_path,
-    )
-    return exporter.export()
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from html.parser import HTMLParser
+from contextlib import ExitStack
+from dataclasses import dataclass, field
+from importlib.resources import as_file, files
+from pathlib import Path
+from zipfile import ZipFile
+
+from docx import Document
+from docx.enum.style import WD_STYLE_TYPE
+from docx.enum.text import WD_BREAK
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Inches, Pt, RGBColor
+from docx.image.exceptions import UnrecognizedImageError
+
+try:
+    from .equations import latex_to_omath, latex_to_omath_para
+except ImportError:  # pragma: no cover - script-style invocation
+    from build_corpus.equations import latex_to_omath, latex_to_omath_para
+
+try:
+    from .frontmatter import inject_frontmatter_into_package, strip_mdk_frontmatter
+except ImportError:  # pragma: no cover - script-style invocation
+    from build_corpus.frontmatter import inject_frontmatter_into_package, strip_mdk_frontmatter
+
+
+# Math delimiters use a (?<!\\) lookbehind so escaped dollars — e.g. currency
+# like "\$252.3B" — are NOT mistaken for inline-math fences. Escaped dollars then
+# flow through the plain-text path and are unescaped to "$" (counted as a fixup).
+INLINE_TOKEN_RE = re.compile(
+    r"(!\[[^\]]*\]\([^)]+\)|\[[^\]]+\]\([^)]+\)|`[^`]+`|(?<!\\)\$\$[^$]+\$\$|(?<!\\)\$[^$\n]+\$|\*\*\*.+?\*\*\*|\*\*.+?\*\*|\*.+?\*)"
+)
+
+# Image targets python-docx can never embed as a picture (need an external
+# render pipeline, e.g. headless-browser screenshot — NOT build-corpus's job).
+UNRENDERABLE_IMAGE_EXTS = (".html", ".htm", ".jsx", ".tsx", ".js", ".svg", ".md")
+# Vector/metafile formats embeddable only after a metafile->PNG conversion
+# (available on Windows / where LibreOffice is present).
+METAFILE_IMAGE_EXTS = (".emf", ".wmf")
+STYLE_PACKAGE_COMMENT_RE = re.compile(r'<!--\s*build-corpus:word-style-package\b[^>]*\bpath="([^"]+)"[^>]*-->', re.IGNORECASE)
+
+
+def count_input_elements(markdown: str) -> dict:
+    """Count source-side Markdown elements for input/output reconciliation."""
+    lines = markdown.splitlines()
+    counts = {"tables": 0, "equations": 0, "images": 0,
+              "code_blocks": 0, "headings": 0, "links": 0}
+    in_fence = False
+    index = 0
+    while index < len(lines):
+        stripped = lines[index].strip()
+        if stripped.startswith("```"):
+            counts["code_blocks"] += 1
+            index += 1
+            while index < len(lines) and not lines[index].strip().startswith("```"):
+                index += 1
+            index += 1
+            continue
+        if stripped == "$$":
+            counts["equations"] += 1
+            index += 1
+            while index < len(lines) and lines[index].strip() != "$$":
+                index += 1
+            index += 1
+            continue
+        if stripped.startswith("$$") and stripped.endswith("$$") and len(stripped) > 4:
+            # standalone single-line display equation (counted once; matches render_markdown)
+            counts["equations"] += 1
+            index += 1
+            continue
+        if stripped.startswith("#"):
+            counts["headings"] += 1
+        elif index + 1 < len(lines) and TABLE_SEPARATOR_RE.match(lines[index + 1]):
+            counts["tables"] += 1
+        line_text = lines[index]
+        # inline elements on this line
+        counts["images"] += len(re.findall(r"!\[[^\]]*\]\([^)]+\)", line_text))
+        # display $$...$$ embedded in a line with surrounding text (render tokenizes these too)
+        counts["equations"] += len(re.findall(r"(?<!\\)\$\$[^$]+\$\$", line_text))
+        # inline math: standalone $...$ not part of $$ and not escaped
+        counts["equations"] += len(re.findall(r"(?<!\\)(?<!\$)\$[^$\n]+\$(?!\$)", line_text))
+        # links that are not images
+        counts["links"] += len(re.findall(r"(?<!!)\[[^\]]+\]\([^)]+\)", line_text))
+        index += 1
+    return counts
+
+
+def count_text_fixups(markdown: str) -> dict:
+    """Count markdown-escape unescapes the exporter applies to body prose.
+
+    Escapes inside fenced code blocks and inline code spans are not unescaped by
+    the renderer, so they are excluded here to match actual behavior.
+    """
+    # strip fenced code blocks
+    no_fences = re.sub(r"```.*?```", "", markdown, flags=re.DOTALL)
+    # strip inline code spans
+    no_code = re.sub(r"`[^`]+`", "", no_fences)
+    matches = re.findall(r"\\([\\`*_{}\[\]()#+.!|$-])", no_code)
+    return {"total": len(matches), "currency_unescaped": matches.count("$")}
+
+
+def image_looks_like_svg(path: Path) -> bool:
+    """Sniff a file's first bytes to detect SVG/XML content (even if mislabeled)."""
+    try:
+        head = path.read_bytes()[:512].lstrip()
+    except OSError:
+        return False
+    lowered = head[:256].lower()
+    return lowered.startswith(b"<svg") or (lowered.startswith(b"<?xml") and b"<svg" in head.lower())
+BARE_URL_RE = re.compile(r"https?://[^\s<>()]+(?:\([^\s<>()]*\)[^\s<>()]*)*")
+LIST_ITEM_RE = re.compile(r"^(\s*)([-*+]|\d+\.)\s+(.*)$")
+TABLE_SEPARATOR_RE = re.compile(r"^\s*\|?(?:\s*:?-{3,}:?\s*\|)+\s*:?-{3,}:?\s*\|?\s*$")
+DEFAULT_TEMPLATE_FILENAME = "md-to-word-template.dotx"
+
+
+@dataclass
+class WordExportStats:
+    paragraphs: int = 0
+    headings: int = 0
+    lists: int = 0
+    tables: int = 0
+    code_blocks: int = 0
+    blockquotes: int = 0
+    links: int = 0
+    images: int = 0
+    images_failed: int = 0
+    equations: int = 0
+    equations_omml: int = 0
+    equations_fell_back: int = 0
+    warnings: list[str] = field(default_factory=list)
+    issues: list[dict] = field(default_factory=list)
+
+
+def strip_fence(line: str) -> str:
+    return line.strip()[3:].strip()
+
+
+def split_table_row(line: str) -> list[str]:
+    text = line.strip()
+    if text.startswith("|"):
+        text = text[1:]
+    if text.endswith("|"):
+        text = text[:-1]
+    cells: list[str] = []
+    buffer: list[str] = []
+    escape = False
+    for char in text:
+        if escape:
+            buffer.append(char)
+            escape = False
+            continue
+        if char == "\\":
+            escape = True
+            buffer.append(char)
+            continue
+        if char == "|":
+            cells.append("".join(buffer).strip())
+            buffer.clear()
+            continue
+        buffer.append(char)
+    cells.append("".join(buffer).strip())
+    return cells
+
+
+def markdown_link_parts(token: str) -> tuple[str, str]:
+    match = re.fullmatch(r"!?\[([^\]]*)\]\(([^)]+)\)", token)
+    if not match:
+        return token, ""
+    return match.group(1), match.group(2).strip()
+
+
+def unescape_markdown_text(text: str) -> str:
+    return re.sub(r"\\([\\`*_{}\[\]()#+.!|$-])", r"\1", text)
+
+
+class HTMLTableParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.rows: list[list[str]] = []
+        self.current_row: list[str] | None = None
+        self.current_cell: list[str] | None = None
+
+    def handle_starttag(self, tag: str, attrs) -> None:  # type: ignore[override]
+        normalized = tag.lower()
+        if normalized == "tr":
+            self.current_row = []
+        elif normalized == "td":
+            self.current_cell = []
+        elif normalized == "br" and self.current_cell is not None:
+            self.current_cell.append("\n")
+
+    def handle_endtag(self, tag: str) -> None:  # type: ignore[override]
+        normalized = tag.lower()
+        if normalized == "td" and self.current_row is not None and self.current_cell is not None:
+            self.current_row.append("".join(self.current_cell).strip())
+            self.current_cell = None
+        elif normalized == "tr" and self.current_row is not None:
+            self.rows.append(self.current_row)
+            self.current_row = None
+
+    def handle_data(self, data: str) -> None:  # type: ignore[override]
+        if self.current_cell is not None:
+            self.current_cell.append(data)
+
+
+def parse_html_table(markup: str) -> list[list[str]]:
+    parser = HTMLTableParser()
+    parser.feed(markup)
+    parser.close()
+    return [row for row in parser.rows if any(cell.strip() for cell in row)]
+
+
+def packaged_template_resource():
+    package_root = f"{__package__}.templates" if __package__ else "build_corpus.templates"
+    return files(package_root).joinpath(DEFAULT_TEMPLATE_FILENAME)
+
+
+def resolve_default_template_path() -> Path | None:
+    try:
+        packaged_template_resource()
+    except ModuleNotFoundError:
+        return None
+    return Path(f"bundled:{DEFAULT_TEMPLATE_FILENAME}")
+
+
+def set_cell_text(cell, text: str) -> None:
+    lines = [segment.strip() for segment in text.replace("<br>", "\n").splitlines()]
+    lines = [line for line in lines if line]
+    if not lines:
+        cell.text = ""
+        return []
+    return lines
+
+
+def append_text_with_breaks(paragraph, text: str) -> None:
+    text = unescape_markdown_text(text)
+    parts = text.split("\n")
+    for index, part in enumerate(parts):
+        if part:
+            paragraph.add_run(part)
+        if index < len(parts) - 1:
+            paragraph.add_run().add_break(WD_BREAK.LINE)
+
+
+def split_trailing_url_punctuation(url: str) -> tuple[str, str]:
+    trailing = []
+    core = url
+    while core and core[-1] in ".,;:!?":
+        trailing.append(core[-1])
+        core = core[:-1]
+    return core, "".join(reversed(trailing))
+
+
+def convert_windows_metafile_to_png(source: Path) -> Path | None:
+    if os.name != "nt":
+        return None
+    target_dir = Path(tempfile.gettempdir()) / "build-corpus-image-fallbacks"
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / f"{source.stem}.png"
+    source_literal = str(source).replace("'", "''")
+    target_literal = str(target).replace("'", "''")
+    command = (
+        "Add-Type -AssemblyName System.Drawing; "
+        f"$img = [System.Drawing.Image]::FromFile('{source_literal}'); "
+        f"$bmp = New-Object System.Drawing.Bitmap $img.Width, $img.Height; "
+        "$gfx = [System.Drawing.Graphics]::FromImage($bmp); "
+        "$gfx.DrawImage($img, 0, 0, $img.Width, $img.Height); "
+        f"$bmp.Save('{target_literal}', [System.Drawing.Imaging.ImageFormat]::Png); "
+        "$gfx.Dispose(); $bmp.Dispose(); $img.Dispose()"
+    )
+    result = subprocess.run(
+        ["powershell", "-NoProfile", "-Command", command],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0 or not target.exists():
+        return None
+    return target
+
+
+def set_paragraph_shading(paragraph, fill: str) -> None:
+    paragraph_pr = paragraph._p.get_or_add_pPr()
+    shading = paragraph_pr.find(qn("w:shd"))
+    if shading is None:
+        shading = OxmlElement("w:shd")
+        paragraph_pr.append(shading)
+    shading.set(qn("w:fill"), fill)
+
+
+def set_paragraph_border(paragraph, color: str) -> None:
+    paragraph_pr = paragraph._p.get_or_add_pPr()
+    borders = paragraph_pr.find(qn("w:pBdr"))
+    if borders is None:
+        borders = OxmlElement("w:pBdr")
+        paragraph_pr.append(borders)
+    left = borders.find(qn("w:left"))
+    if left is None:
+        left = OxmlElement("w:left")
+        borders.append(left)
+    left.set(qn("w:val"), "single")
+    left.set(qn("w:sz"), "10")
+    left.set(qn("w:space"), "12")
+    left.set(qn("w:color"), color)
+
+
+def add_hyperlink(paragraph, text: str, url: str):
+    part = paragraph.part
+    relationship_id = part.relate_to(
+        url,
+        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
+        is_external=True,
+    )
+    hyperlink = OxmlElement("w:hyperlink")
+    hyperlink.set(qn("r:id"), relationship_id)
+
+    run = OxmlElement("w:r")
+    rpr = OxmlElement("w:rPr")
+
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "2563EB")
+    rpr.append(color)
+
+    underline = OxmlElement("w:u")
+    underline.set(qn("w:val"), "single")
+    rpr.append(underline)
+    run.append(rpr)
+
+    text_node = OxmlElement("w:t")
+    text_node.text = text
+    run.append(text_node)
+    hyperlink.append(run)
+    paragraph._p.append(hyperlink)
+    return hyperlink
+
+
+def append_hyperlink_run(hyperlink, text: str, bold: bool = False, italic: bool = False, code: bool = False) -> None:
+    run = OxmlElement("w:r")
+    rpr = OxmlElement("w:rPr")
+
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "2563EB")
+    rpr.append(color)
+
+    underline = OxmlElement("w:u")
+    underline.set(qn("w:val"), "single")
+    rpr.append(underline)
+
+    if bold:
+        rpr.append(OxmlElement("w:b"))
+    if italic:
+        rpr.append(OxmlElement("w:i"))
+
+    fonts_needed = code
+    if fonts_needed:
+        fonts = OxmlElement("w:rFonts")
+        fonts.set(qn("w:ascii"), "Consolas")
+        fonts.set(qn("w:hAnsi"), "Consolas")
+        fonts.set(qn("w:cs"), "Consolas")
+        rpr.append(fonts)
+        size = OxmlElement("w:sz")
+        size.set(qn("w:val"), "20")
+        rpr.append(size)
+
+    run.append(rpr)
+    text_node = OxmlElement("w:t")
+    text_node.text = text
+    run.append(text_node)
+    hyperlink.append(run)
+
+
+def set_picture_metadata(run, source_name: str) -> None:
+    filename = Path(source_name).name
+    try:
+        doc_props = run._r.xpath(".//*[local-name()='docPr']")
+    except Exception:
+        doc_props = []
+    for doc_prop in doc_props:
+        doc_prop.set("name", filename)
+        doc_prop.set("descr", filename)
+        doc_prop.set("title", filename)
+
+
+class MarkdownToDocxExporter:
+    def __init__(
+        self,
+        input_path: Path,
+        output_dir: Path,
+        output_docx: Path | None = None,
+        report_path: Path | None = None,
+        template_path: Path | None = None,
+    ):
+        self.input_path = input_path
+        self.output_dir = output_dir
+        self.output_docx = output_docx or (output_dir / f"{input_path.stem}.docx")
+        self.report_path = report_path or (output_dir / "export-report.json")
+        self._template_resource_stack = ExitStack()
+        self.template_path = self.resolve_template_path(template_path)
+        self.use_template_styles = self.template_path is not None
+        self.stats = WordExportStats()
+
+    def export(self) -> dict:
+        try:
+            self.output_dir.mkdir(parents=True, exist_ok=True)
+            if self.template_path and not self.template_path.exists():
+                raise FileNotFoundError(f"Word template not found: {self.template_path}")
+
+            document = Document()
+            if not self.template_path:
+                self.apply_modern_styles(document)
+            self.ensure_custom_styles(document)
+
+            raw_markdown = self.input_path.read_text(encoding="utf-8")
+            frontmatter, markdown = strip_mdk_frontmatter(raw_markdown)
+            self.render_markdown(document, markdown)
+            document.save(self.output_docx)
+            if self.template_path:
+                self.apply_template_package(self.output_docx, self.template_path)
+            if frontmatter:
+                inject_frontmatter_into_package(self.output_docx, frontmatter)
+
+            input_counts = count_input_elements(markdown)
+            text_fixups = count_text_fixups(markdown)
+            reconciliation = self.build_reconciliation(input_counts)
+            fidelity_ok = all(row["ok"] for row in reconciliation.values())
+
+            report = {
+                "input": str(self.input_path),
+                "output": str(self.output_docx),
+                "template": str(self.template_path) if self.template_path else None,
+                "fidelity_ok": fidelity_ok,
+                "reconciliation": reconciliation,
+                "text_fixups": text_fixups,
+                "issues": self.stats.issues,
+                "stats": self.stats.__dict__,
+            }
+            self.report_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+            self._print_digest(reconciliation, text_fixups, fidelity_ok)
+            return report
+        finally:
+            self._template_resource_stack.close()
+
+    def build_reconciliation(self, input_counts: dict) -> dict:
+        """Compare source-side element counts to what was emitted."""
+        s = self.stats
+        equations_in = input_counts["equations"]
+        return {
+            "tables": {
+                "in": input_counts["tables"], "out": s.tables,
+                "ok": input_counts["tables"] == s.tables,
+            },
+            "equations": {
+                "in": equations_in, "out_omml": s.equations_omml,
+                "fell_back": s.equations_fell_back,
+                "ok": s.equations_omml == equations_in and s.equations_fell_back == 0,
+            },
+            "images": {
+                "in": input_counts["images"], "out": s.images, "failed": s.images_failed,
+                "ok": s.images_failed == 0 and s.images == input_counts["images"],
+            },
+            "code_blocks": {
+                "in": input_counts["code_blocks"], "out": s.code_blocks,
+                "ok": input_counts["code_blocks"] == s.code_blocks,
+            },
+            "headings": {
+                "in": input_counts["headings"], "out": s.headings,
+                "ok": input_counts["headings"] == s.headings,
+            },
+            "links": {
+                "in": input_counts["links"], "out": s.links,
+                "ok": input_counts["links"] == s.links,
+            },
+        }
+
+    def _print_digest(self, reconciliation: dict, text_fixups: dict, fidelity_ok: bool) -> None:
+        """Print a one-line human-readable fidelity summary to stdout."""
+        parts = []
+        for name, row in reconciliation.items():
+            out = row.get("out_omml", row.get("out", 0))
+            mark = "OK" if row["ok"] else "!!"
+            label = f"[{mark}] {name} {out}/{row['in']}"
+            if name == "equations" and row["fell_back"]:
+                label += f" ({row['fell_back']} fell back)"
+            if name == "images" and row.get("failed"):
+                label += f" ({row['failed']} failed)"
+            parts.append(label)
+        if text_fixups["total"]:
+            parts.append(f"text_fixups {text_fixups['total']} "
+                         f"({text_fixups['currency_unescaped']} currency)")
+        bad_lines = sorted({i["line"] for i in self.stats.issues if i.get("line")})
+        if bad_lines:
+            parts.append("issue lines: " + ",".join(str(n) for n in bad_lines))
+        print("  ".join(parts) + f"  -> fidelity_ok={str(fidelity_ok).lower()}")
+
+    def resolve_template_path(self, template_path: Path | None) -> Path | None:
+        if template_path is not None:
+            return Path(template_path)
+
+        roundtrip_template = self.resolve_roundtrip_template_path()
+        if roundtrip_template is not None:
+            return roundtrip_template
+
+        try:
+            return self._template_resource_stack.enter_context(as_file(packaged_template_resource()))
+        except (FileNotFoundError, ModuleNotFoundError):
+            return None
+
+    def resolve_roundtrip_template_path(self) -> Path | None:
+        sidecar_template = self.input_path.with_suffix(".wordstyle") / "style-package.docx"
+        if sidecar_template.exists():
+            return sidecar_template
+        try:
+            head = self.input_path.read_text(encoding="utf-8")[:4096]
+        except OSError:
+            return None
+        match = STYLE_PACKAGE_COMMENT_RE.search(head)
+        if not match:
+            return None
+        candidate = Path(match.group(1))
+        if not candidate.is_absolute():
+            candidate = self.input_path.parent / candidate
+        return candidate if candidate.exists() else None
+
+    def apply_modern_styles(self, document: Document) -> None:
+        section = document.sections[0]
+        section.top_margin = Inches(0.8)
+        section.bottom_margin = Inches(0.8)
+        section.left_margin = Inches(0.9)
+        section.right_margin = Inches(0.9)
+
+        normal = document.styles["Normal"]
+        normal.font.name = "Aptos"
+        normal.font.size = Pt(11)
+        normal.font.color.rgb = RGBColor(31, 41, 55)
+        normal.paragraph_format.space_after = Pt(8)
+        normal.paragraph_format.line_spacing = 1.15
+
+        for level, size in ((1, 22), (2, 17), (3, 14), (4, 12)):
+            style = document.styles[f"Heading {level}"]
+            style.font.name = "Aptos Display"
+            style.font.size = Pt(size)
+            style.font.bold = True
+            style.font.color.rgb = RGBColor(15, 23, 42)
+            style.paragraph_format.space_before = Pt(12 if level == 1 else 10)
+            style.paragraph_format.space_after = Pt(4)
+
+        self.ensure_custom_styles(document)
+
+    def ensure_custom_styles(self, document: Document) -> None:
+        if self.use_template_styles:
+            return
+        if "BuildCorpus Code" not in document.styles:
+            style = document.styles.add_style("BuildCorpus Code", WD_STYLE_TYPE.PARAGRAPH)
+            style.base_style = document.styles["Normal"]
+            style.font.name = "Consolas"
+            style.font.size = Pt(10)
+            style.paragraph_format.left_indent = Inches(0.2)
+            style.paragraph_format.right_indent = Inches(0.2)
+            style.paragraph_format.space_before = Pt(4)
+            style.paragraph_format.space_after = Pt(6)
+
+        if "BuildCorpus Quote" not in document.styles:
+            style = document.styles.add_style("BuildCorpus Quote", WD_STYLE_TYPE.PARAGRAPH)
+            style.base_style = document.styles["Normal"]
+            style.font.italic = True
+            style.font.color.rgb = RGBColor(71, 85, 105)
+            style.paragraph_format.left_indent = Inches(0.35)
+            style.paragraph_format.space_after = Pt(6)
+
+    def render_markdown(self, document: Document, markdown: str) -> None:
+        lines = markdown.splitlines()
+        index = 0
+        while index < len(lines):
+            line = lines[index]
+            self.current_line = index + 1
+            stripped = line.strip()
+
+            if not stripped:
+                index += 1
+                continue
+
+            if stripped.startswith("<!--") and stripped.endswith("-->"):
+                index += 1
+                continue
+
+            if stripped.startswith("```"):
+                info = strip_fence(line)
+                buffer: list[str] = []
+                index += 1
+                while index < len(lines) and not lines[index].strip().startswith("```"):
+                    buffer.append(lines[index])
+                    index += 1
+                if index < len(lines):
+                    index += 1
+                self.add_code_block(document, "\n".join(buffer), info)
+                continue
+
+            if stripped == "$$":
+                buffer: list[str] = []
+                index += 1
+                while index < len(lines) and lines[index].strip() != "$$":
+                    buffer.append(lines[index])
+                    index += 1
+                if index < len(lines):
+                    index += 1
+                self.add_equation_block(document, "\n".join(buffer).strip())
+                continue
+
+            if stripped.startswith("$$") and stripped.endswith("$$") and len(stripped) > 4:
+                self.add_equation_block(document, stripped[2:-2].strip())
+                index += 1
+                continue
+
+            if stripped.startswith("#"):
+                level = len(stripped) - len(stripped.lstrip("#"))
+                text = stripped[level:].strip()
+                self.add_heading(document, level, text)
+                index += 1
+                continue
+
+            if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
+                table_lines = [line, lines[index + 1]]
+                index += 2
+                while index < len(lines) and "|" in lines[index]:
+                    if not lines[index].strip():
+                        break
+                    table_lines.append(lines[index])
+                    index += 1
+                self.add_table(document, table_lines)
+                continue
+
+            if stripped.lower() == "<table>":
+                table_lines = [line]
+                index += 1
+                while index < len(lines):
+                    table_lines.append(lines[index])
+                    if lines[index].strip().lower() == "</table>":
+                        index += 1
+                        break
+                    index += 1
+                self.add_html_table(document, "\n".join(table_lines))
+                continue
+
+            list_match = LIST_ITEM_RE.match(line)
+            if list_match:
+                index = self.add_list(document, lines, index)
+                continue
+
+            if stripped.startswith(">"):
+                quote_lines: list[str] = []
+                while index < len(lines) and lines[index].strip().startswith(">"):
+                    quote_lines.append(lines[index].strip()[1:].strip())
+                    index += 1
+                self.add_blockquote(document, " ".join(quote_lines))
+                continue
+
+            if re.fullmatch(r"[-*_]{3,}", stripped):
+                document.add_paragraph("")
+                index += 1
+                continue
+
+            paragraph_lines = [line.strip()]
+            paragraph_lines = [line.rstrip()]
+            paragraph_breaks = [line.endswith("  ") or line.endswith("\\")]
+            index += 1
+            while index < len(lines):
+                candidate = lines[index]
+                if not candidate.strip():
+                    break
+                if candidate.strip().startswith(("```", "#", ">")):
+                    break
+                if LIST_ITEM_RE.match(candidate):
+                    break
+                if TABLE_SEPARATOR_RE.match(lines[index + 1]) if index + 1 < len(lines) else False:
+                    break
+                paragraph_lines.append(candidate.rstrip())
+                paragraph_breaks.append(candidate.endswith("  ") or candidate.endswith("\\"))
+                index += 1
+            self.add_paragraph(document, self.combine_paragraph_lines(paragraph_lines, paragraph_breaks))
+
+    @staticmethod
+    def combine_paragraph_lines(lines: list[str], breaks: list[bool]) -> str:
+        if not lines:
+            return ""
+        combined = lines[0]
+        for index in range(1, len(lines)):
+            separator = "\n" if breaks[index - 1] else " "
+            combined += separator + lines[index]
+        return combined
+
+    @staticmethod
+    def apply_template_package(output_docx: Path, template_path: Path) -> None:
+        transplant_parts = {
+            "word/styles.xml",
+            "word/stylesWithEffects.xml",
+            "word/numbering.xml",
+            "word/fontTable.xml",
+            "word/settings.xml",
+            "word/webSettings.xml",
+            "word/theme/theme1.xml",
+        }
+        with tempfile.TemporaryDirectory(prefix="build-corpus-template-") as tmp:
+            tmp_dir = Path(tmp)
+            patched = tmp_dir / output_docx.name
+            with ZipFile(output_docx) as out_zip, ZipFile(template_path) as template_zip, ZipFile(patched, "w") as patched_zip:
+                template_names = set(template_zip.namelist())
+                output_names = set(out_zip.namelist())
+                for name in out_zip.namelist():
+                    if name in transplant_parts and name in template_names:
+                        patched_zip.writestr(name, template_zip.read(name))
+                    else:
+                        patched_zip.writestr(name, out_zip.read(name))
+                for name in transplant_parts:
+                    if name in template_names and name not in output_names:
+                        patched_zip.writestr(name, template_zip.read(name))
+            shutil.move(str(patched), output_docx)
+
+    def add_heading(self, document: Document, level: int, text: str) -> None:
+        paragraph = document.add_paragraph(style=f"Heading {min(level, 6)}")
+        self.render_inline(paragraph, text)
+        self.stats.headings += 1
+
+    def add_paragraph(self, document: Document, text: str) -> None:
+        paragraph = document.add_paragraph(style="Normal")
+        self.render_inline(paragraph, text)
+        self.stats.paragraphs += 1
+
+    def add_code_block(self, document: Document, code: str, info: str) -> None:
+        paragraph = document.add_paragraph(style="Normal" if self.use_template_styles else "BuildCorpus Code")
+        if info:
+            label = paragraph.add_run(f"{info}\n")
+            label.bold = True
+            label.font.color.rgb = RGBColor(37, 99, 235)
+        run = paragraph.add_run(code)
+        run.font.name = "Consolas"
+        run.font.size = Pt(10)
+        set_paragraph_shading(paragraph, "F8FAFC")
+        self.stats.code_blocks += 1
+
+    def add_equation_block(self, document: Document, equation: str) -> None:
+        paragraph = document.add_paragraph(style="Normal")
+        paragraph.paragraph_format.left_indent = Inches(0.3)
+        paragraph.paragraph_format.right_indent = Inches(0.3)
+        paragraph.paragraph_format.space_before = Pt(4)
+        paragraph.paragraph_format.space_after = Pt(8)
+        omath = latex_to_omath_para(equation)
+        if omath is not None:
+            self.add_hidden_math_source(paragraph, equation)
+            paragraph._p.append(omath)
+            self.stats.equations_omml += 1
+        else:
+            run = paragraph.add_run(equation)
+            run.font.name = "Cambria Math"
+            run.font.size = Pt(11)
+            self._record_equation_fallback(equation)
+        self.stats.equations += 1
+
+    def _add_inline_equation(self, paragraph, latex: str) -> None:
+        """Append an inline OMML equation, falling back to Cambria Math text."""
+        omath = latex_to_omath(latex)
+        if omath is not None:
+            self.add_hidden_math_source(paragraph, latex)
+            paragraph._p.append(omath)
+            self.stats.equations_omml += 1
+        else:
+            run = paragraph.add_run(latex)
+            run.font.name = "Cambria Math"
+            run.font.size = Pt(11)
+            self._record_equation_fallback(latex)
+        self.stats.equations += 1
+
+    @staticmethod
+    def add_hidden_math_source(paragraph, latex: str) -> None:
+        run = paragraph.add_run(latex)
+        run.font.name = "Cambria Math"
+        rpr = run._r.get_or_add_rPr()
+        rpr.append(OxmlElement("w:vanish"))
+
+    def _record_equation_fallback(self, latex: str) -> None:
+        """Record a LaTeX fragment that could not be converted to OMML."""
+        self.stats.equations_fell_back += 1
+        line = getattr(self, "current_line", 0)
+        message = f"Equation kept as text (LaTeX not parsed): {latex[:60]}"
+        self.stats.warnings.append(message)
+        self.stats.issues.append({
+            "type": "equation",
+            "line": line,
+            "source": latex[:120],
+            "reason": "latex-parse-failed",
+        })
+
+    def _record_image_failure(self, target: str, reason: str, message: str) -> None:
+        """Record an image that could not be embedded, with a specific reason."""
+        self.stats.images_failed += 1
+        self.stats.warnings.append(f"{message}: {target}")
+        self.stats.issues.append({
+            "type": "image",
+            "line": getattr(self, "current_line", 0),
+            "target": target,
+            "reason": reason,
+        })
+
+    def add_blockquote(self, document: Document, text: str) -> None:
+        paragraph = document.add_paragraph(style="Quote" if self.use_template_styles else "BuildCorpus Quote")
+        self.render_inline(paragraph, text)
+        set_paragraph_border(paragraph, "CBD5E1")
+        self.stats.blockquotes += 1
+
+    def add_list(self, document: Document, lines: list[str], start: int) -> int:
+        index = start
+        while index < len(lines):
+            match = LIST_ITEM_RE.match(lines[index])
+            if not match:
+                break
+            indent, marker, body = match.groups()
+            ordered = marker.endswith(".")
+            body_lines = [body]
+            lookahead = index + 1
+            while lookahead < len(lines):
+                candidate = lines[lookahead]
+                stripped = candidate.strip()
+                if not stripped:
+                    break
+                if candidate.strip().startswith(("```", "#", ">")):
+                    break
+                if LIST_ITEM_RE.match(candidate):
+                    break
+                if TABLE_SEPARATOR_RE.match(lines[lookahead + 1]) if lookahead + 1 < len(lines) else False:
+                    break
+                if not candidate[:1].isspace():
+                    break
+                body_lines.append(candidate.rstrip())
+                lookahead += 1
+            style_name = self.list_style_name(document, ordered, indent)
+            paragraph = document.add_paragraph(style=style_name)
+            if style_name in {"List Bullet", "List Number"}:
+                paragraph.paragraph_format.left_indent = Inches(0.25 + (len(indent.replace("\t", "  ")) // 2) * 0.18)
+            self.render_inline(paragraph, "\n".join(body_lines))
+            self.stats.lists += 1
+            index = lookahead
+        return index
+
+    def list_style_name(self, document: Document, ordered: bool, indent: str) -> str:
+        level = min(3, max(1, (len(indent.replace("\t", "  ")) // 2) + 1))
+        base = "List Number" if ordered else "List Bullet"
+        candidate = base if level == 1 else f"{base} {level}"
+        return candidate if candidate in document.styles else base
+
+    def add_table(self, document: Document, table_lines: list[str]) -> None:
+        rows = [split_table_row(line) for line in table_lines if not TABLE_SEPARATOR_RE.match(line)]
+        self.add_table_rows(document, rows)
+
+    def add_html_table(self, document: Document, table_markup: str) -> None:
+        self.add_table_rows(document, parse_html_table(table_markup))
+
+    def add_table_rows(self, document: Document, rows: list[list[str]]) -> None:
+        if not rows:
+            return
+        width = max(len(row) for row in rows)
+        table = document.add_table(rows=len(rows), cols=width)
+        table.style = "Light List Accent 1" if "Light List Accent 1" in document.styles else "Table Grid"
+        for row_index, row in enumerate(rows):
+            for col_index in range(width):
+                value = row[col_index] if col_index < len(row) else ""
+                self.render_table_cell(table.cell(row_index, col_index), value)
+        self.stats.tables += 1
+
+    def render_table_cell(self, cell, text: str) -> None:
+        lines = set_cell_text(cell, text)
+        if not lines:
+            cell.text = ""
+            return
+        first = cell.paragraphs[0]
+        first.text = ""
+        self.render_inline(first, lines[0])
+        for line in lines[1:]:
+            paragraph = cell.add_paragraph("")
+            self.render_inline(paragraph, line)
+
+    def render_inline(self, paragraph, text: str) -> None:
+        cursor = 0
+        for match in INLINE_TOKEN_RE.finditer(text):
+            if match.start() > cursor:
+                self.render_plain_text(paragraph, text[cursor:match.start()])
+            token = match.group(0)
+            self.render_inline_token(paragraph, token)
+            cursor = match.end()
+        if cursor < len(text):
+            self.render_plain_text(paragraph, text[cursor:])
+
+    def render_plain_text(self, paragraph, text: str) -> None:
+        cursor = 0
+        for match in BARE_URL_RE.finditer(text):
+            if match.start() > cursor:
+                append_text_with_breaks(paragraph, text[cursor:match.start()])
+            url = match.group(0)
+            normalized_url, trailing = split_trailing_url_punctuation(url)
+            if normalized_url:
+                add_hyperlink(paragraph, normalized_url, normalized_url)
+            if trailing:
+                append_text_with_breaks(paragraph, trailing)
+            cursor = match.end()
+        if cursor < len(text):
+            append_text_with_breaks(paragraph, text[cursor:])
+
+    def render_inline_token(self, paragraph, token: str) -> None:
+        if token.startswith("!["):
+            alt, target = markdown_link_parts(token)
+            image_path = (self.input_path.parent / target).resolve()
+            ext = image_path.suffix.lower()
+            if target.startswith(("http://", "https://", "data:")):
+                paragraph.add_run(f"[image: {alt or target}]")
+                self._record_image_failure(target, "skipped-remote",
+                                           "Skipped non-local image target")
+                return
+            if ext == ".svg" or (ext in UNRENDERABLE_IMAGE_EXTS and image_looks_like_svg(image_path)):
+                paragraph.add_run(f"[unsupported image: {target}]")
+                self._record_image_failure(target, "svg-needs-rasterization",
+                                           "SVG cannot be embedded by python-docx; rasterize to PNG via the render pipeline")
+                return
+            if ext in UNRENDERABLE_IMAGE_EXTS:
+                # HTML/JSX can never be embedded as a picture — flag for the
+                # external render pipeline. We deliberately do NOT rasterize here.
+                paragraph.add_run(f"[unsupported image: {target}]")
+                self._record_image_failure(target, "unsupported-format",
+                                           f"Image format cannot be embedded ({ext}); route to render pipeline")
+                return
+            if not image_path.exists():
+                paragraph.add_run(f"[missing image: {target}]")
+                self._record_image_failure(target, "missing-file", "Missing image asset")
+                return
+            run = paragraph.add_run()
+            try:
+                run.add_picture(str(image_path), width=Inches(5.8))
+                set_picture_metadata(run, target)
+                self.stats.images += 1
+            except UnrecognizedImageError:
+                converted = convert_windows_metafile_to_png(image_path)
+                if converted is not None:
+                    run.add_picture(str(converted), width=Inches(5.8))
+                    set_picture_metadata(run, target)
+                    self.stats.images += 1
+                    self.stats.warnings.append(f"Converted unsupported image to PNG: {target}")
+                elif image_looks_like_svg(image_path):
+                    # SVG content mislabeled with a raster extension (e.g. .png that
+                    # is really SVG+PNG-fallback the extractor flattened wrong).
+                    paragraph.add_run(f"[unsupported image: {target}]")
+                    self._record_image_failure(target, "mislabeled-svg",
+                                               f"{target} is SVG content with a {ext or 'raster'} extension; rasterize to PNG and repoint")
+                elif ext in METAFILE_IMAGE_EXTS:
+                    paragraph.add_run(f"[unsupported image: {target}]")
+                    self._record_image_failure(target, "unsupported-on-platform",
+                                               f"{ext} needs metafile->PNG conversion (install LibreOffice / run on Windows)")
+                else:
+                    paragraph.add_run(f"[unsupported image: {target}]")
+                    self._record_image_failure(target, "unsupported-format",
+                                               "Image format not recognized by python-docx")
+            return
+
+        if token.startswith("["):
+            label, target = markdown_link_parts(token)
+            hyperlink = add_hyperlink(paragraph, "", target)
+            self.render_hyperlink_label(hyperlink, label)
+            self.stats.links += 1
+            return
+
+        if token.startswith("`"):
+            run = paragraph.add_run(token[1:-1])
+            run.font.name = "Consolas"
+            run.font.size = Pt(10)
+            return
+
+        if token.startswith("$$") and token.endswith("$$"):
+            self._add_inline_equation(paragraph, token[2:-2])
+            return
+
+        if token.startswith("$") and token.endswith("$"):
+            self._add_inline_equation(paragraph, token[1:-1])
+            return
+
+        if token.startswith("***") and token.endswith("***"):
+            run = paragraph.add_run(token[3:-3])
+            run.bold = True
+            run.italic = True
+            return
+
+        if token.startswith("**") and token.endswith("**"):
+            run = paragraph.add_run(token[2:-2])
+            run.bold = True
+            return
+
+        if token.startswith("*") and token.endswith("*"):
+            run = paragraph.add_run(token[1:-1])
+            run.italic = True
+            return
+
+        paragraph.add_run(token)
+
+    def render_hyperlink_label(self, hyperlink, text: str) -> None:
+        cursor = 0
+        for match in INLINE_TOKEN_RE.finditer(text):
+            if match.start() > cursor:
+                append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:match.start()]))
+            token = match.group(0)
+            self.render_hyperlink_token(hyperlink, token)
+            cursor = match.end()
+        if cursor < len(text):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(text[cursor:]))
+
+    def render_hyperlink_token(self, hyperlink, token: str) -> None:
+        if token.startswith("`") and token.endswith("`"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), code=True)
+            return
+        if token.startswith("***") and token.endswith("***"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[3:-3]), bold=True, italic=True)
+            return
+        if token.startswith("**") and token.endswith("**"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[2:-2]), bold=True)
+            return
+        if token.startswith("*") and token.endswith("*"):
+            append_hyperlink_run(hyperlink, unescape_markdown_text(token[1:-1]), italic=True)
+            return
+        append_hyperlink_run(hyperlink, unescape_markdown_text(token))
+
+
+def export_markdown_to_docx(
+    input_path: Path,
+    output_root: Path,
+    out_same_dir: bool,
+    template_path: Path | None = None,
+) -> dict:
+    if out_same_dir:
+        output_dir = input_path.parent
+        output_docx = input_path.with_suffix(".docx")
+        report_path = input_path.with_name(f"{input_path.stem}.export-report.json")
+    else:
+        output_dir = output_root / input_path.stem
+        output_docx = None
+        report_path = None
+
+    exporter = MarkdownToDocxExporter(
+        input_path=input_path,
+        output_dir=output_dir,
+        output_docx=output_docx,
+        report_path=report_path,
+        template_path=template_path,
+    )
+    return exporter.export()