@tasksai/install 0.1.38 → 0.1.40

package/runtime/document_renderer.py

@@ -0,0 +1,882 @@
+"""Shared local Word renderer used by the loader and saved workflows."""
+import re
+
+__all__ = ['markdown_table_row', 'markdown_table_alignments', 'is_markdown_table_start', 'inferred_plain_heading_level', 'labeled_fact', 'add_labeled_text', 'add_labeled_fact', 'iter_inline_markdown', 'add_hyperlink', 'add_markdown_text', 'add_markdown_heading', 'add_horizontal_rule', 'set_cell_shading', 'set_cell_margins', 'repeat_table_header', 'prevent_table_row_split', 'add_page_number', 'add_markdown_table', 'write_docx']
+
+def markdown_table_row(line):
+    """Return parsed table cells when a line looks like a Markdown table row."""
+    stripped = line.strip()
+    if "|" not in stripped:
+        return None
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    cells = []
+    current = []
+    escaped = False
+    for char in stripped:
+        if escaped:
+            current.append(char)
+            escaped = False
+        elif char == "\\":
+            escaped = True
+        elif char == "|":
+            cells.append("".join(current).strip())
+            current = []
+        else:
+            current.append(char)
+    cells.append("".join(current).strip())
+    return cells if cells else None
+
+
+def markdown_table_alignments(separator_cells):
+    """Return column alignments if cells are a valid Markdown table separator."""
+    alignments = []
+    for cell in separator_cells or []:
+        compact = cell.replace(" ", "")
+        if not re.match(r"^:?-{3,}:?$", compact):
+            return None
+        if compact.startswith(":") and compact.endswith(":"):
+            alignments.append("center")
+        elif compact.endswith(":"):
+            alignments.append("right")
+        else:
+            alignments.append("left")
+    return alignments
+
+
+def is_markdown_table_start(lines, index):
+    """True when lines[index:index+2] form a Markdown table header."""
+    if index + 1 >= len(lines):
+        return False
+    header = markdown_table_row(lines[index])
+    separator = markdown_table_row(lines[index + 1])
+    return bool(header and markdown_table_alignments(separator))
+
+
+def inferred_plain_heading_level(lines, index):
+    """Infer conservative headings when an AI omits Markdown # markers."""
+    # Explicit Markdown line breaks belong to one prose block (for example,
+    # a sender name and brokerage). Title case does not make them headings.
+    if lines[index].endswith("  ") or (index > 0 and lines[index - 1].endswith("  ")):
+        return None
+    text = lines[index].strip()
+    if not text or len(text) > 90 or "|" in text or ":" in text:
+        return None
+    if re.match(r"^(?:[-*+]\s+|\d+\.\s+|>|<!--)", text):
+        return None
+    if text.endswith((".", "?", "!", ";")):
+        return None
+
+    letters = [char for char in text if char.isalpha()]
+    if len(letters) >= 4 and all(char.isupper() for char in letters):
+        return 2
+
+    next_index = index + 1
+    while next_index < len(lines) and not lines[next_index].strip():
+        next_index += 1
+    next_line = lines[next_index] if next_index < len(lines) else ""
+    introduces_list = bool(
+        re.match(r"^\s*[-*+]\s+\S", next_line)
+        or re.match(r"^\s*\d+\.\s+\S", next_line)
+    )
+    introduces_facts = bool(re.match(r"^\s*[^:\n]{1,55}:\s+\S", next_line))
+    if introduces_list or introduces_facts or text.istitle():
+        return 3
+    return None
+
+
+def labeled_fact(line):
+    """Return a label/value pair for a short professional fact line."""
+    bold_match = re.match(r"^\*\*([^*\n:]{1,55}):\*\*\s+(.+)$", line.strip())
+    if bold_match:
+        return bold_match.group(1).strip(), bold_match.group(2).strip()
+    match = re.match(r"^([^:\n]{1,55}):\s+(.+)$", line.strip())
+    if not match:
+        return None
+    if re.search(r"[`*_\[\]]", match.group(1)):
+        # A colon after inline Markdown is sentence punctuation, not a
+        # short label/value field. Let the normal inline parser handle it.
+        return None
+    return match.group(1).strip(), match.group(2).strip()
+
+
+def add_labeled_text(paragraph, label, value):
+    """Render a label/value pair in an existing Word paragraph."""
+    label_run = paragraph.add_run(f"{label}: ")
+    label_run.bold = True
+    add_markdown_text(paragraph, value)
+
+
+def add_labeled_fact(doc, label, value):
+    """Render a fact line with a bold label and distinct Word paragraph."""
+    paragraph = doc.add_paragraph()
+    add_labeled_text(paragraph, label, value)
+
+
+def iter_inline_markdown(text):
+    """Yield (text, marks) spans for common inline Markdown."""
+    text = re.sub(r"\\([\\`*_{}\[\]()#+.!-])", r"\1", text)
+    token_re = re.compile(
+        r"(`[^`]+`|\*\*[^*]+\*\*|(?<!_)__(?![_\s])[^_]+?(?<!\s)__(?!_)|\*[^*\s][^*]*\*|(?<!\w)_[^_\s][^_]*_(?!\w)|\[[^\]]+\]\([^)]+\))"
+    )
+    pos = 0
+    for match in token_re.finditer(text):
+        if match.start() > pos:
+            yield text[pos:match.start()], {}
+        token = match.group(0)
+        marks = {}
+        value = token
+        if token.startswith("**") and token.endswith("**"):
+            value = token[2:-2]
+            marks["bold"] = True
+        elif token.startswith("__") and token.endswith("__"):
+            value = token[2:-2]
+            marks["bold"] = True
+        elif token.startswith("`") and token.endswith("`"):
+            value = token[1:-1]
+            marks["code"] = True
+        elif token.startswith("["):
+            link = re.match(r"^\[([^\]]+)\]\(([^)]+)\)$", token)
+            if link:
+                value = link.group(1)
+                marks["link"] = link.group(2)
+        elif token[0] in {"*", "_"} and token.endswith(token[0]):
+            value = token[1:-1]
+            marks["italic"] = True
+        yield value, marks
+        pos = match.end()
+    if pos < len(text):
+        yield text[pos:], {}
+
+
+def add_hyperlink(paragraph, text, url):
+    """Add a clickable hyperlink run when python-docx low-level APIs are available."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    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_element = OxmlElement("w:r")
+    properties = OxmlElement("w:rPr")
+
+    color = OxmlElement("w:color")
+    color.set(qn("w:val"), "0563C1")
+    properties.append(color)
+
+    underline = OxmlElement("w:u")
+    underline.set(qn("w:val"), "single")
+    properties.append(underline)
+
+    run_element.append(properties)
+    text_element = OxmlElement("w:t")
+    text_element.text = text
+    run_element.append(text_element)
+    hyperlink.append(run_element)
+    paragraph._p.append(hyperlink)
+
+
+def add_markdown_text(paragraph, text):
+    """Add common inline Markdown formatting to a python-docx paragraph."""
+    for value, marks in iter_inline_markdown(text):
+        if not value:
+            continue
+        if marks.get("link"):
+            try:
+                add_hyperlink(paragraph, value, marks["link"])
+            except Exception:
+                paragraph.add_run(f"{value} ({marks['link']})")
+            continue
+        run = paragraph.add_run(value)
+        if marks.get("bold"):
+            run.bold = True
+            if re.match(r"^\+\d", value):
+                # Aptos substitution in some headless Word renderers maps a
+                # bold leading plus sign to a diamond. Arial preserves the
+                # intended glyph and remains portable in Office.
+                run.font.name = "Arial"
+        if marks.get("italic"):
+            run.italic = True
+        if marks.get("code"):
+            run.font.name = "Courier New"
+
+
+def add_markdown_heading(doc, text, level):
+    """Create a Word heading while parsing any inline Markdown in its text."""
+
+    paragraph = doc.add_heading(level=level)
+    add_markdown_text(paragraph, text)
+    return paragraph
+
+
+def add_horizontal_rule(paragraph):
+    """Render a horizontal Markdown rule as a Word paragraph border."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    p_pr = paragraph._p.get_or_add_pPr()
+    borders = p_pr.first_child_found_in("w:pBdr")
+    if borders is None:
+        borders = OxmlElement("w:pBdr")
+        p_pr.append(borders)
+    bottom = OxmlElement("w:bottom")
+    bottom.set(qn("w:val"), "single")
+    bottom.set(qn("w:sz"), "6")
+    bottom.set(qn("w:space"), "1")
+    bottom.set(qn("w:color"), "BFBFBF")
+    borders.append(bottom)
+
+
+def set_cell_shading(cell, fill):
+    """Apply a solid background color to a Word table cell."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    cell_properties = cell._tc.get_or_add_tcPr()
+    shading = cell_properties.find(qn("w:shd"))
+    if shading is None:
+        shading = OxmlElement("w:shd")
+        cell_properties.append(shading)
+    shading.set(qn("w:fill"), fill)
+
+
+def set_cell_margins(cell, top=70, start=90, bottom=70, end=90):
+    """Set compact, readable table cell margins in twentieths of a point."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    cell_properties = cell._tc.get_or_add_tcPr()
+    margins = cell_properties.first_child_found_in("w:tcMar")
+    if margins is None:
+        margins = OxmlElement("w:tcMar")
+        cell_properties.append(margins)
+    for name, value in (("top", top), ("start", start), ("bottom", bottom), ("end", end)):
+        node = margins.find(qn(f"w:{name}"))
+        if node is None:
+            node = OxmlElement(f"w:{name}")
+            margins.append(node)
+        node.set(qn("w:w"), str(value))
+        node.set(qn("w:type"), "dxa")
+
+
+def repeat_table_header(row):
+    """Repeat the first row of a long table on subsequent pages."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    row_properties = row._tr.get_or_add_trPr()
+    repeat = row_properties.find(qn("w:tblHeader"))
+    if repeat is None:
+        repeat = OxmlElement("w:tblHeader")
+        row_properties.append(repeat)
+    repeat.set(qn("w:val"), "true")
+
+
+def prevent_table_row_split(row):
+    """Keep a table row together when Word paginates the document."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    row_properties = row._tr.get_or_add_trPr()
+    if row_properties.find(qn("w:cantSplit")) is None:
+        row_properties.append(OxmlElement("w:cantSplit"))
+
+
+def add_page_number(paragraph):
+    """Add a dynamic PAGE field to a footer paragraph."""
+    from docx.oxml import OxmlElement
+    from docx.oxml.ns import qn
+
+    run = paragraph.add_run()
+    begin = OxmlElement("w:fldChar")
+    begin.set(qn("w:fldCharType"), "begin")
+    instruction = OxmlElement("w:instrText")
+    instruction.set(qn("xml:space"), "preserve")
+    instruction.text = " PAGE "
+    end = OxmlElement("w:fldChar")
+    end.set(qn("w:fldCharType"), "end")
+    run._r.extend((begin, instruction, end))
+
+
+def add_markdown_table(doc, rows, alignments):
+    """Render a Markdown pipe table as a native Word table."""
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.enum.section import WD_SECTION_START, WD_ORIENT
+    from docx.shared import Pt, RGBColor
+
+    if not rows:
+        return
+
+    width = max(len(row) for row in rows)
+    # A few records with many fields are easier to compare down the page.
+    # Transpose only rectangular tables that would require landscape; preserve every cell and
+    # leave the caller's data (including the Excel representation) untouched.
+    if width > 6 and 2 <= len(rows) <= 6 and all(len(row) == width for row in rows):
+        rows = [list(column) for column in zip(*rows)]
+        width = len(rows[0])
+        alignments = ["left"] * width
+    original=doc.sections[-1]
+    page_size=(original.page_width,original.page_height,original.orientation)
+    landscape=width>6 and original.page_width<original.page_height
+    # Carry a nearby heading and short introduction onto the table page.
+    # Only inspect adjacent paragraphs; never cross another table.
+    lead=None
+    introductions=[]
+    lead_count=0
+    introduction_length=0
+    heading_count=0
+    following_node=doc._element.body.sectPr
+    for paragraph in reversed(doc.paragraphs[-6:]):
+        if paragraph._p.xpath('./w:pPr/w:sectPr'):break
+        if paragraph._p.getnext() is not following_node or len(paragraph.text)>600:break
+        introduction_length+=len(paragraph.text)
+        if introduction_length>600:break
+        following_node=paragraph._p
+        introductions.append(paragraph)
+        visible_runs=[run for run in paragraph.runs if run.text.strip()]
+        if paragraph.style.name.startswith('Heading') or (visible_runs and all(run.bold for run in visible_runs)):
+            lead=paragraph._p
+            lead_count=len(introductions)
+            heading_count+=1
+            # A portrait table needs only its own major section heading.
+            # Landscape transitions also carry nearby introductory sections
+            # because the inserted page boundary overrides their keep rules.
+            if not landscape and paragraph.style.name in ('Heading 1', 'Heading 2'):
+                break
+            # A table caption can follow a short introduction and its section
+            # heading. Continue across those adjacent paragraphs so they travel
+            # together instead of leaving an introduction on its own page.
+            if heading_count==2:break
+    # A longer section introduction may exceed the bounded scan before its
+    # section heading is reached. Keep the adjacent short tail with the wide
+    # table caption rather than stranding it on a portrait page by itself.
+    if landscape and heading_count==1 and len(introductions)>lead_count:
+        lead=introductions[-1]._p
+        lead_count=len(introductions)
+    # A section title can sit directly above a second title in the scanned
+    # introduction. Carry that adjacent heading too; otherwise an inserted
+    # landscape boundary overrides Word's keep-with-next and strands it.
+    from docx.text.paragraph import Paragraph
+    from docx.oxml.ns import qn
+    if landscape and lead is not None:
+        for _ in range(2):
+            previous = lead.getprevious()
+            if previous is None or previous.tag != qn('w:p') or previous.xpath('./w:pPr/w:sectPr'):
+                break
+            paragraph = Paragraph(previous, doc._body)
+            if not paragraph.style.name.startswith('Heading') or introduction_length + len(paragraph.text) > 600:
+                break
+            introduction_length += len(paragraph.text)
+            paragraph.paragraph_format.keep_with_next = True
+            lead = previous
+    if lead is not None:
+        for introduction in introductions[:lead_count]:
+            introduction.paragraph_format.keep_with_next = True
+    boundary=lead.getprevious() if lead is not None else None
+    # A short table footnote or total can sit between two table sections.
+    # Keep that bridge in the existing landscape group instead of creating a
+    # nearly empty portrait page. Longer narrative and intervening headings
+    # remain separate; never cross another table or a non-paragraph element.
+    cursor=boundary
+    bridge_characters=0
+    for _ in range(5):
+        if cursor is None or cursor.tag != qn('w:p'):break
+        if cursor.find(qn('w:pPr')+'/'+qn('w:sectPr')) is not None:
+            boundary=cursor
+            break
+        bridge=Paragraph(cursor,doc)
+        bridge_characters+=len(bridge.text)
+        if bridge.style.name.startswith('Heading') or bridge_characters>600:break
+        cursor=cursor.getprevious()
+    prior_section=boundary.find(qn('w:pPr')+'/'+qn('w:sectPr')) if boundary is not None else None
+    prior_size=prior_section.find(qn('w:pgSz')) if prior_section is not None else None
+    continuing_landscape=bool(prior_size is not None and prior_size.get(qn('w:orient'))=='landscape' and not ''.join(boundary.itertext()).strip())
+    # Adjacent table groups can contain narrower tables too. Keep the group
+    # together instead of inserting portrait pages between landscape tables.
+    landscape=landscape or (continuing_landscape and original.page_width<original.page_height)
+    # A first table after a brief introduction has ample first-page space.
+    # Avoid turning that introduction into an accidental cover page.
+    brief_opening = not doc.tables and sum(len(p.text) for p in doc.paragraphs) <= 700 and len(doc.paragraphs) <= 8
+    if len(rows) > 20 and not landscape and not brief_opening:
+        # Start long comparisons with their heading on a fresh page. Some
+        # Office renderers can omit continuation rows when a nearly page-sized
+        # table begins in the last available line of the preceding page.
+        start=next((p for p in doc.paragraphs if p._p is lead),None)
+        if start is not None:
+            paragraphs=doc.paragraphs
+            index=next(i for i,p in enumerate(paragraphs) if p._p is lead)
+            if index and paragraphs[index-1].text.strip()==start.text.strip():
+                start=paragraphs[index-1]
+                start.paragraph_format.keep_with_next=True
+        else:
+            start=doc.add_paragraph()
+            start.paragraph_format.keep_with_next=True
+        start.paragraph_format.page_break_before=True
+    if landscape:
+        if continuing_landscape:
+            # Extend the landscape section through this table, its short
+            # introduction and any bounded notes after the previous table.
+            boundary.getparent().remove(boundary)
+            wide=doc.sections[-1]
+        elif brief_opening:
+            # Use the opening page for its first wide table instead of leaving
+            # a short title/introduction on an otherwise empty portrait page.
+            wide=original
+        else:
+            wide=doc.add_section(WD_SECTION_START.NEW_PAGE)
+            if lead is not None:lead.addprevious(doc.paragraphs[-1]._p)
+        wide.orientation=WD_ORIENT.LANDSCAPE
+        wide.page_width,wide.page_height=page_size[1],page_size[0]
+    normalized = [row + [""] * (width - len(row)) for row in rows]
+    table = doc.add_table(rows=len(normalized), cols=width)
+    table.style = "Table Grid"
+    table.autofit = True
+    # Email addresses are read as a unit. In a small contact directory, reserve
+    # enough width for a raw-address column instead of stranding its last letter.
+    if 3 <= width <= 4 and len(normalized) > 2:
+        email_columns = [i for i in range(width) if any(row[i].strip() for row in normalized[1:])
+                         and all(not row[i].strip() or re.fullmatch(r'[^\s@]+@[^\s@]+\.[^\s@]+', row[i].strip()) for row in normalized[1:])]
+        if len(email_columns) == 1:
+            email_column = email_columns[0]
+            section = doc.sections[-1]
+            available = section.page_width - section.left_margin - section.right_margin
+            longest = max(len(row[email_column]) for row in normalized[1:])
+            fraction = min(0.45, max(1 / width, (longest * 4.5 + 12) / (available / 12700)))
+            table.autofit = False
+            for i, column in enumerate(table.columns):
+                size = int(available * (fraction if i == email_column else (1 - fraction) / (width - 1)))
+                column.width = size
+                for cell in column.cells:
+                    cell.width = size
+    # Give a dominant narrative column room beside short owner/date/status
+    # fields. Restrict this to narrow tables; balanced comparisons keep their
+    # existing layout. No headings or cell contents are rewritten.
+    if 3 <= width <= 4 and len(normalized) > 2:
+        averages = [sum(len(row[i]) for row in normalized[1:]) / (len(normalized)-1) for i in range(width)]
+        dominant = max(range(width), key=averages.__getitem__)
+        others = [value for i, value in enumerate(averages) if i != dominant]
+        if averages[dominant] >= 100 and averages[dominant] >= 3 * max(others):
+            section = doc.sections[-1]
+            available = section.page_width - section.left_margin - section.right_margin
+            table.autofit = False
+            for i, column in enumerate(table.columns):
+                size = int(available * (0.5 if i == dominant else 0.5 / (width-1)))
+                column.width = size
+                for cell in column.cells:
+                    cell.width = size
+    repeat_table_header(table.rows[0])
+    # Short summaries should travel as a unit instead of leaving their final
+    # one or two rows on an otherwise empty page. Bound both row count and
+    # estimated wrapping so long narrative tables can still paginate normally.
+    import math
+    section = doc.sections[-1]
+    cell_characters = max(12, int((section.page_width.pt-section.left_margin.pt-section.right_margin.pt)/width/4.5)-4)
+    row_lines = [max((sum(max(1, math.ceil(len(line)/cell_characters)) for line in value.split('\n')) for value in row), default=1) for row in normalized]
+    compact_table = len(normalized) <= 12 and sum(row_lines) <= 22
+    # Let long tables flow, but avoid a lone opening or closing data row when
+    # its neighboring rows form a small block. Do not chain very tall rows.
+    opening_block = len(normalized) >= 3 and sum(row_lines[:3]) <= 12
+    closing_block = len(normalized) >= 3 and sum(row_lines[-2:]) <= 12
+    for row_index, row in enumerate(normalized):
+        row_characters = sum(len(value) for value in row)
+        longest_cell = max((len(value) for value in row), default=0)
+        if row_index == 0 or (row_characters <= 600 and longest_cell <= 350):
+            # Keep ordinary rows intact so a cell does not strand a fragment
+            # on the next page. Exceptionally large rows may still split to
+            # avoid creating a mostly blank page.
+            prevent_table_row_split(table.rows[row_index])
+        for column_index, value in enumerate(row):
+            cell = table.cell(row_index, column_index)
+            set_cell_margins(cell)
+            if row_index == 0:
+                set_cell_shading(cell, "17365D")
+            elif row_index % 2 == 0:
+                set_cell_shading(cell, "EEF3F8")
+            paragraph = cell.paragraphs[0]
+            if (compact_table and row_index < len(normalized)-1) or (opening_block and row_index < 2) or (closing_block and row_index == len(normalized)-2):
+                paragraph.paragraph_format.keep_with_next = True
+            paragraph.paragraph_format.space_after = Pt(0)
+            add_markdown_text(paragraph, value)
+            if row_index == 0:
+                for run in paragraph.runs:
+                    run.bold = True
+                    run.font.color.rgb = RGBColor(255, 255, 255)
+            alignment = alignments[column_index] if column_index < len(alignments) else "left"
+            if alignment == "right":
+                paragraph.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+            elif alignment == "center":
+                paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
+            for run in paragraph.runs:
+                run.font.size = Pt(9)
+
+    doc.add_paragraph()
+    if landscape:
+        following=doc.add_section(WD_SECTION_START.NEW_PAGE)
+        following.page_width,following.page_height,following.orientation=page_size
+
+
+def write_docx(path, title, content_markdown, product_name, large_print=False, monochrome=False, page_header=''):
+    """Write a professionally styled DOCX file locally."""
+    try:
+        from docx import Document
+        from docx.enum.text import WD_ALIGN_PARAGRAPH
+        from docx.shared import Inches, Pt, RGBColor
+    except Exception as exc:
+        raise RuntimeError(
+            "python-docx is not installed. Re-run the official installer or install python-docx in the MCP runtime environment."
+        ) from exc
+
+    doc = Document()
+    doc.core_properties.title = title or f"{product_name} Work Product"
+    doc.core_properties.author = product_name
+
+    section = doc.sections[0]
+    section.top_margin = Inches(1.1 if page_header and large_print else 0.8 if page_header else 0.55)
+    section.bottom_margin = Inches(0.55)
+    section.left_margin = Inches(0.7)
+    section.right_margin = Inches(0.7)
+    section.header_distance = Inches(0.3)
+    section.footer_distance = Inches(0.3)
+
+    styles = doc.styles
+    normal = styles["Normal"]
+    normal.font.name = "Aptos"
+    normal.font.size = Pt(9.3)
+    normal.font.color.rgb = RGBColor(31, 41, 55)
+    normal.paragraph_format.space_after = Pt(4)
+    normal.paragraph_format.line_spacing = 1.05
+
+    title_style = styles["Title"]
+    title_style.font.name = "Aptos Display"
+    title_style.font.size = Pt(19)
+    title_style.font.bold = True
+    title_style.font.color.rgb = RGBColor(23, 54, 93)
+    title_style.paragraph_format.space_after = Pt(5)
+
+    heading_sizes = {1: 14, 2: 11.5, 3: 10.5, 4: 9.5}
+    for level, size in heading_sizes.items():
+        style = styles[f"Heading {level}"]
+        style.font.name = "Aptos Display"
+        style.font.size = Pt(size)
+        style.font.bold = True
+        style.font.color.rgb = RGBColor(23, 54, 93)
+        style.paragraph_format.space_before = Pt(8 if level <= 2 else 5)
+        style.paragraph_format.space_after = Pt(3)
+        style.paragraph_format.keep_with_next = True
+
+    header = section.header.paragraphs[0]
+    header.text = page_header or f"{product_name}  |  Professional Work Product"
+    header.alignment = WD_ALIGN_PARAGRAPH.RIGHT
+    for run in header.runs:
+        run.font.name = "Aptos"
+        run.font.size = Pt(7.5)
+        run.font.color.rgb = RGBColor(100, 116, 139)
+
+    footer = section.footer.paragraphs[0]
+    footer.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    footer_run = footer.add_run(f"Generated locally by {product_name}  |  Private local output  |  Page ")
+    footer_run.font.name = "Aptos"
+    footer_run.font.size = Pt(7.5)
+    footer_run.font.color.rgb = RGBColor(100, 116, 139)
+    add_page_number(footer)
+
+    if title:
+        doc.add_heading(title, level=0)
+
+    lines = content_markdown.splitlines()
+    paragraph_buffer = []
+
+    def flush_paragraph():
+        if not paragraph_buffer:
+            return
+        text_parts = []
+        for part in paragraph_buffer:
+            clean = part.strip()
+            if not clean:
+                continue
+            text_parts.append(clean)
+            text_parts.append("\n" if part.endswith("  ") else " ")
+        text = "".join(text_parts).rstrip()
+        paragraph_buffer.clear()
+        if text:
+            add_markdown_text(doc.add_paragraph(), text)
+
+    in_code_block = False
+    keep_checklist_together = False
+    list_number_id = None
+    email_start = None
+
+    def finish_email():
+        nonlocal email_start
+        if email_start is None:
+            return
+        # Keep a short sender/sign-off tail with the final body paragraph.
+        # Restrict this to a recognized greeting and a structural boundary.
+        paragraphs = doc.paragraphs[email_start:]
+        for offset in range(1, min(3, len(paragraphs))):
+            tail = paragraphs[-offset]
+            if not tail.text.strip() or len(tail.text) > 160:
+                break
+            paragraphs[-offset - 1].paragraph_format.keep_with_next = True
+        email_start = None
+
+    index = 0
+    while index < len(lines):
+        raw_line = lines[index]
+        line = raw_line.rstrip("\r\n")
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            flush_paragraph()
+            in_code_block = not in_code_block
+            index += 1
+            continue
+        if in_code_block:
+            para = doc.add_paragraph()
+            run = para.add_run(line)
+            run.font.name = "Courier New"
+            run.font.size = Pt(9)
+            index += 1
+            continue
+        if not stripped:
+            flush_paragraph()
+            index += 1
+            continue
+
+        heading = re.match(r"^(#{1,4})\s+(.+)$", stripped)
+        standalone_bold_heading = re.fullmatch(r"\*\*([^*\n]{1,120})\*\*", stripped)
+        inferred_heading = inferred_plain_heading_level(lines, index)
+        if email_start is not None:
+            # Plain title-case sender names and bold closing notes inside an
+            # email are prose. Explicit Markdown headings remain boundaries.
+            inferred_heading = None
+            standalone_bold_heading = None
+        bullet = re.match(r"^(\s*)[-*+]\s+(.+)$", line)
+        numbered = re.match(r"^(\s*)\d+\.\s+(.+)$", line)
+        if not numbered:
+            list_number_id = None
+        quote = re.match(r"^>\s?(.+)$", stripped)
+        fact = (
+            labeled_fact(stripped)
+            if not paragraph_buffer
+            and not line.endswith("  ")
+            and not bullet
+            and not numbered
+            and not quote
+            else None
+        )
+
+        if re.fullmatch(r"<!--\s*[^\n]*?\s*-->", stripped):
+            # Public-copy delimiters and other machine-readable Markdown
+            # comments are useful in the source but must not appear in the
+            # downloadable customer document.
+            flush_paragraph()
+            index += 1
+            continue
+        if stripped == ">":
+            # A blank line inside a Markdown blockquote is structural spacing,
+            # not a literal greater-than character in the Word document.
+            flush_paragraph()
+            index += 1
+            continue
+        if re.fullmatch(r"(?:(?:Hi|Hello)(?: [^\n,#*]{1,80})?|Dear [^\n,#*]{1,80}),", stripped):
+            flush_paragraph()
+            finish_email()
+            header = []
+            preceding_lines = []
+            for preceding in reversed(lines[max(0, index - 20):index]):
+                if re.match(r'^\s*#', preceding) or preceding.strip() in {'---', '***', '___'}:
+                    break
+                preceding_lines.append(preceding)
+            has_subject = any(re.match(r'^\s*(?:\*\*)?Subject:', item) for item in preceding_lines)
+            for previous in reversed(doc.paragraphs[-8:] if has_subject else []):
+                if not previous.text.strip() or len(previous.text) > 200:
+                    break
+                header.append(previous)
+                if previous.style.name in ('Heading 1', 'Heading 2', 'Heading 3'):
+                    # Inferred branding headings can follow the subject line;
+                    # stop only once an actual mail header has been found.
+                    if any(re.search(r'(^|\n)Subject:', p.text) for p in header):
+                        break
+            if any(re.search(r'(^|\n)Subject:', p.text) for p in header):
+                for previous in header:
+                    previous.paragraph_format.keep_with_next = True
+            email_start = len(doc.paragraphs)
+            paragraph = doc.add_paragraph()
+            paragraph.paragraph_format.keep_with_next = True
+            add_markdown_text(paragraph, stripped)
+            index += 1
+            continue
+        if re.fullmatch(r"(?:Warmly|Sincerely|Regards|Best|Best regards|Kind regards|Best wishes|Respectfully|Yours sincerely|Yours truly),", stripped, re.I):
+            flush_paragraph()
+            # A conventional email closing and adjacent sender lines are prose,
+            # not inferred headings. Keep the preceding closing sentence with it.
+            if doc.paragraphs:
+                previous = doc.paragraphs[-1]
+                if previous.text.strip() and len(previous.text) <= 500:
+                    previous.paragraph_format.keep_with_next = True
+            paragraph = doc.add_paragraph()
+            paragraph.paragraph_format.keep_together = True
+            add_markdown_text(paragraph, stripped)
+            index += 1
+            for _ in range(4):
+                if index >= len(lines):
+                    break
+                sender = lines[index].strip()
+                if not sender or sender in {"---", "***", "___"} or len(sender) > 120 or re.match(r"^(?:#|>|[-*+]\s|\d+\.\s|\|)", sender):
+                    break
+                paragraph.add_run().add_break()
+                add_markdown_text(paragraph, sender)
+                index += 1
+            continue
+        if is_markdown_table_start(lines, index):
+            flush_paragraph()
+            finish_email()
+            header = markdown_table_row(lines[index])
+            alignments = markdown_table_alignments(markdown_table_row(lines[index + 1]))
+            table_rows = [header]
+            index += 2
+            while index < len(lines):
+                row = markdown_table_row(lines[index])
+                if not row:
+                    break
+                table_rows.append(row)
+                index += 1
+            add_markdown_table(doc, table_rows, alignments)
+            continue
+        elif heading:
+            flush_paragraph()
+            finish_email()
+            heading_text = heading.group(2).strip()
+            if not (
+                title
+                and index == 0
+                and re.sub(r"\W+", "", heading_text).casefold()
+                == re.sub(r"\W+", "", title).casefold()
+            ):
+                add_markdown_heading(doc, heading_text, min(len(heading.group(1)), 4))
+                keep_checklist_together = "checklist" in heading_text.casefold()
+            index += 1
+        elif standalone_bold_heading:
+            flush_paragraph()
+            add_markdown_heading(doc, standalone_bold_heading.group(1).strip(), 3)
+            index += 1
+        elif inferred_heading:
+            flush_paragraph()
+            add_markdown_heading(doc, stripped, inferred_heading)
+            keep_checklist_together = "checklist" in stripped.casefold()
+            index += 1
+        elif fact:
+            flush_paragraph()
+            add_labeled_fact(doc, fact[0], fact[1])
+            index += 1
+        elif bullet:
+            flush_paragraph()
+            para = doc.add_paragraph(style="List Bullet")
+            indent_level = min(len(bullet.group(1).replace("\t", "    ")) // 2, 4)
+            para.paragraph_format.left_indent = Inches(0.25 * indent_level)
+            text = bullet.group(2).strip()
+            checkbox = re.match(r"^\[([ xX])\]\s+(.+)$", text)
+            if checkbox:
+                text = f"[{checkbox.group(1).lower()}] {checkbox.group(2).strip()}"
+            bullet_fact = labeled_fact(text)
+            if bullet_fact:
+                add_labeled_text(para, bullet_fact[0], bullet_fact[1])
+            else:
+                add_markdown_text(para, text)
+            next_is_bullet = bool(
+                index + 1 < len(lines)
+                and re.match(r"^\s*[-*+]\s+\S", lines[index + 1])
+            )
+            if keep_checklist_together and next_is_bullet:
+                para.paragraph_format.keep_with_next = True
+            elif keep_checklist_together:
+                keep_checklist_together = False
+            index += 1
+        elif numbered:
+            flush_paragraph()
+            para = doc.add_paragraph(style="List Number")
+            if list_number_id is None:
+                numbering = doc.part.numbering_part.element
+                style_num = doc.styles['List Number'].element.pPr.numPr.numId.val
+                abstract_id = numbering.num_having_numId(style_num).abstractNumId.val
+                instance = numbering.add_num(abstract_id)
+                start = int(re.match(r"^\s*(\d+)\.", line).group(1))
+                instance.add_lvlOverride(ilvl=0).add_startOverride(start)
+                list_number_id = instance.numId
+            num_pr = para._p.get_or_add_pPr().get_or_add_numPr()
+            num_pr.get_or_add_ilvl().val = 0
+            num_pr.get_or_add_numId().val = list_number_id
+            indent_level = min(len(numbered.group(1).replace("\t", "    ")) // 2, 4)
+            para.paragraph_format.left_indent = Inches(0.25 * indent_level)
+            add_markdown_text(para, numbered.group(2).strip())
+            index += 1
+        elif quote:
+            flush_paragraph()
+            try:
+                para = doc.add_paragraph(style="Quote")
+            except Exception:
+                para = doc.add_paragraph()
+            para.paragraph_format.left_indent = Inches(0.25)
+            add_markdown_text(para, quote.group(1).strip())
+            index += 1
+        elif stripped in {"---", "***", "___"}:
+            flush_paragraph()
+            finish_email()
+            add_horizontal_rule(doc.add_paragraph())
+            index += 1
+        else:
+            paragraph_buffer.append(line)
+            index += 1
+
+    flush_paragraph()
+    finish_email()
+
+    if large_print:
+        # Apply the requested reading size to actual text, including tables and
+        # page furniture. Standard-size pagination estimates no longer apply.
+        paragraphs = list(doc.paragraphs)
+        for table in doc.tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    for paragraph in cell.paragraphs:
+                        paragraph.paragraph_format.keep_with_next = False
+                        paragraphs.append(paragraph)
+        for section in doc.sections:
+            paragraphs.extend(section.header.paragraphs)
+            paragraphs.extend(section.footer.paragraphs)
+        for paragraph in paragraphs:
+            for run in paragraph.runs:
+                inherited = paragraph.style.font.size
+                size = run.font.size or inherited
+                run.font.size = Pt(max(16, size.pt if size is not None else 16))
+                run.font.name = 'Arial'
+        doc.styles['Normal'].font.size = Pt(16)
+        doc.styles['Normal'].font.name = 'Arial'
+
+    if monochrome:
+        from docx.oxml.ns import qn
+        # Explicit colors override Office themes in body text, links, styles,
+        # table borders and page furniture. White fills avoid heavy ink use.
+        trees = [doc._element, doc.styles.element]
+        for section in doc.sections:
+            trees.extend([section.header._element, section.footer._element])
+        for tree in trees:
+            for element in tree.iter():
+                if element.tag == qn('w:color'):
+                    element.set(qn('w:val'), '000000')
+                if qn('w:color') in element.attrib:
+                    element.set(qn('w:color'), '000000')
+                if element.tag == qn('w:shd'):
+                    element.set(qn('w:val'), 'clear')
+                    element.set(qn('w:fill'), 'FFFFFF')
+                for attribute in ('themeColor', 'themeTint', 'themeShade', 'themeFill', 'themeFillTint', 'themeFillShade'):
+                    element.attrib.pop(qn('w:' + attribute), None)
+    doc.save(path)