import logging
import re
import warnings
from contextlib import contextmanager
from copy import deepcopy
from io import BytesIO
from pathlib import Path
from typing import Any, Callable, Final
from urllib.parse import urlparse

from docling_core.types.doc import (
    ContentLayer,
    DocItem,
    DocItemLabel,
    DoclingDocument,
    DocumentOrigin,
    GroupLabel,
    ImageRef,
    ListGroup,
    NodeItem,
    RefItem,
    RichTableCell,
    TableCell,
    TableData,
    TableItem,
)
from docling_core.types.doc.document import FineRef, Formatting, Script
from docx import Document
from docx.document import Document as DocxDocument
from docx.oxml.table import CT_Tc
from docx.oxml.xmlchemy import BaseOxmlElement
from docx.styles.style import ParagraphStyle
from docx.table import Table, _Cell
from docx.text.hyperlink import Hyperlink
from docx.text.paragraph import Paragraph
from docx.text.run import Run
from lxml import etree
from PIL import Image, UnidentifiedImageError
from pydantic import AnyUrl
from typing_extensions import override

from docling.backend.abstract_backend import DeclarativeDocumentBackend
from docling.backend.docx.drawingml.utils import (
    get_docx_to_pdf_converter,
    get_pil_from_dml_docx,
)
from docling.backend.docx.latex.omml import oMath2Latex
from docling.datamodel.base_models import InputFormat
from docling.datamodel.document import InputDocument
from docling.exceptions import DocumentLoadError

_log = logging.getLogger(__name__)


class MsWordDocumentBackend(DeclarativeDocumentBackend):
    """Backend for parsing Microsoft Word (.docx) documents.

    Note:
        Images with a total area (width * height) less than or equal to
        `SPACER_IMAGE_AREA_THRESHOLD` (default: 25px) are considered layout
        artifacts (such as invisible spacers) and are discarded during parsing.
    """

    _W_NS: Final[str] = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
    _W_NS_CLARK: Final[str] = f"{{{_W_NS}}}"

    _BLIP_NAMESPACES: Final = {
        "a": "http://schemas.openxmlformats.org/drawingml/2006/main",
        "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
        "w": _W_NS,
        "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
        "mc": "http://schemas.openxmlformats.org/markup-compatibility/2006",
        "v": "urn:schemas-microsoft-com:vml",
        "wps": "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
        "w10": "urn:schemas-microsoft-com:office:word",
        "a14": "http://schemas.microsoft.com/office/drawing/2010/main",
        "w14": "http://schemas.microsoft.com/office/word/2010/wordml",
    }

    SPACER_IMAGE_AREA_THRESHOLD: Final[int] = (
        25  # Images with an area (w*h) below this are dropped as layout artifacts
    )

    @override
    def __init__(self, in_doc: "InputDocument", path_or_stream: BytesIO | Path) -> None:
        super().__init__(in_doc, path_or_stream)
        self.XML_KEY = f"{self._W_NS_CLARK}val"
        self.xml_namespaces = {
            "w": "http://schemas.microsoft.com/office/word/2003/wordml"
        }
        self.blip_xpath_expr = etree.XPath(
            ".//a:blip", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
        )
        self.vml_imagedata_xpath_expr = etree.XPath(
            ".//v:imagedata", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
        )
        # self.initialise(path_or_stream)
        # Word file:
        self.path_or_stream: BytesIO | Path = path_or_stream
        self.valid: bool = False
        # Initialise the parents for the hierarchy
        self.max_levels: int = 10
        self.level_at_new_list: int | None = None
        self.parents: dict[int, NodeItem | None] = {}
        self.numbered_headers: dict[int, int] = {}
        self.equation_bookends: str = "<eq>{EQ}</eq>"
        # Track processed textbox elements to avoid duplication
        self.processed_textbox_elements: list[int] = []
        self.docx_to_pdf_converter: Callable | None = None
        self.docx_to_pdf_converter_init = False
        self.display_drawingml_warning = True

        for i in range(-1, self.max_levels):
            self.parents[i] = None

        self.level = 0
        self.listIter = 0
        # Track list counters per numId and ilvl
        self.list_counters: dict[tuple[int, int], int] = {}
        # Track the last numId to handle list continuation after interruptions
        self.last_numid: int | None = None
        # Track the last list group and its parent to reuse only in same context
        self.last_list_group: ListGroup | None = None
        self.last_list_group_numid: int | None = None
        self.last_list_group_parent: NodeItem | None = None
        # Set starting content layer
        self.content_layer = ContentLayer.BODY

        self.history: dict[str, Any] = {
            "names": [None],
            "levels": [None],
            "numids": [None],
            "indents": [None],
        }

        # Track comment mappings: comment_id -> comment object
        self.comment_map: dict[str, Any] = {}
        # Track paragraph elements to their comment IDs
        self.paragraph_comment_map: dict[int, list[str]] = {}
        # Track text items created from each paragraph element
        self.paragraph_to_items: dict[int, list[RefItem]] = {}

        self.docx_obj = self.load_msword_file(
            path_or_stream=self.path_or_stream, document_hash=self.document_hash
        )
        if self.docx_obj:
            self.valid = True
            self.current_part = self.docx_obj.part
            # Build comment mappings after loading document
            self._extract_comment_ranges()

    @override
    def is_valid(self) -> bool:
        return self.valid

    @classmethod
    @override
    def supports_pagination(cls) -> bool:
        return False

    @override
    def unload(self):
        if isinstance(self.path_or_stream, BytesIO):
            self.path_or_stream.close()

        self.path_or_stream = None

    @classmethod
    @override
    def supported_formats(cls) -> set[InputFormat]:
        return {InputFormat.DOCX}

    @override
    def convert(self) -> DoclingDocument:
        """Parses the DOCX into a structured document model.

        Returns:
            The parsed document.
        """

        origin = DocumentOrigin(
            filename=self.file.name or "file",
            mimetype="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            binary_hash=self.document_hash,
        )

        doc = DoclingDocument(name=self.file.stem or "file", origin=origin)
        if self.is_valid():
            assert self.docx_obj is not None
            # Reset mappings for a fresh conversion pass
            self.paragraph_comment_map.clear()
            self.paragraph_to_items.clear()
            doc, _ = self._walk_linear(self.docx_obj.element.body, doc)
            self._add_header_footer(self.docx_obj, doc)
            # Add comments and link them to annotated paragraphs
            self._add_comments(self.docx_obj, doc)

            return doc
        else:
            raise RuntimeError(
                f"Cannot convert doc with {self.document_hash} because the backend failed to init."
            )

    @staticmethod
    def load_msword_file(
        path_or_stream: BytesIO | Path, document_hash: str
    ) -> DocxDocument:
        try:
            if isinstance(path_or_stream, BytesIO):
                return Document(path_or_stream)
            elif isinstance(path_or_stream, Path):
                return Document(str(path_or_stream))
            else:
                return None
        except Exception as e:
            raise DocumentLoadError(
                f"MsWordDocumentBackend could not load document with hash {document_hash}"
            ) from e

    def _update_history(
        self,
        name: str,
        level: int | None,
        numid: int | None,
        ilevel: int | None,
    ):
        self.history["names"].append(name)
        self.history["levels"].append(level)

        self.history["numids"].append(numid)
        self.history["indents"].append(ilevel)

    def _prev_name(self) -> str | None:
        return self.history["names"][-1]

    def _prev_level(self) -> int | None:
        return self.history["levels"][-1]

    def _prev_numid(self) -> int | None:
        return self.history["numids"][-1]

    def _prev_indent(self) -> int | None:
        return self.history["indents"][-1]

    def _get_level(self) -> int:
        """Return the first None index."""
        for k, v in self.parents.items():
            if k >= 0 and v is None:
                return k
        return 0

    def _can_reuse_list_group(self, numid: int, parent: NodeItem | None) -> bool:
        """Check if we can reuse the cached list group.

        Returns True only if we're continuing the same numId in the same parent context.
        """
        return (
            self.last_numid == numid
            and self.last_list_group is not None
            and self.last_list_group_numid == numid
            and self.last_list_group_parent == parent
        )

    def _get_or_create_list_group(
        self,
        doc: DoclingDocument,
        numid: int,
        parent: NodeItem | None,
        elem_ref: list[RefItem],
    ) -> ListGroup:
        """Get existing list group if reusable, otherwise create a new one.

        Args:
            doc: The DoclingDocument being constructed.
            numid: The numbering ID for this list.
            parent: The parent node for the list group.
            elem_ref: List to append new group reference to (if created).

        Returns:
            The list group to use (either reused or newly created).
        """
        if self._can_reuse_list_group(numid, parent):
            # When reusing a list group, remove any empty text item that was added
            # between the last list item and this one (from closing the list)
            if doc.texts and len(doc.texts) > 0:
                last_text = doc.texts[-1]
                if not last_text.text or not last_text.text.strip():
                    doc.delete_items(node_items=[last_text])
            return self.last_list_group

        list_gr = doc.add_list_group(
            name="list",
            parent=parent,
            content_layer=self.content_layer,
        )
        elem_ref.append(list_gr.get_ref())

        # Update cache for potential future reuse
        self.last_list_group = list_gr
        self.last_list_group_numid = numid
        self.last_list_group_parent = parent

        return list_gr

    def _clear_list_group_cache(self) -> None:
        """Clear the cached list group to prevent reuse across contexts."""
        self.last_list_group = None
        self.last_list_group_numid = None
        self.last_list_group_parent = None

    @contextmanager
    def _isolated_list_context(self):
        """Preserve list state during table cell processing.

        This context manager saves the list-related state (history, level_at_new_list,
        and parents) before entering a table cell, and restores it after processing.
        This ensures that lists in different table cells are treated independently,
        even when they share the same numId.
        """
        saved_history = {
            "names": self.history["names"].copy(),
            "levels": self.history["levels"].copy(),
            "numids": self.history["numids"].copy(),
            "indents": self.history["indents"].copy(),
        }
        saved_level_at_new_list = self.level_at_new_list
        saved_parents = self.parents.copy()
        # Save and clear list group cache to prevent reuse across table cells
        saved_last_list_group = self.last_list_group
        saved_last_list_group_numid = self.last_list_group_numid
        saved_last_list_group_parent = self.last_list_group_parent
        self._clear_list_group_cache()

        try:
            yield
        finally:
            self.history = saved_history
            self.level_at_new_list = saved_level_at_new_list
            self.parents = saved_parents
            self.last_list_group = saved_last_list_group
            self.last_list_group_numid = saved_last_list_group_numid
            self.last_list_group_parent = saved_last_list_group_parent

    def _walk_linear(
        self,
        body: BaseOxmlElement,
        doc: DoclingDocument,
        # parent:
    ) -> tuple[DoclingDocument, list[RefItem]]:
        added_elements = []
        for element in body:
            tag_name = etree.QName(element).localname
            # Check for Inline Images (blip elements)
            _raw_drawing_blip = self.blip_xpath_expr(element)
            _raw_drawingml_els = element.findall(
                ".//w:drawing", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
            )
            _raw_vml_images = self.vml_imagedata_xpath_expr(element)

            # Filter out images inside textboxes to prevent double-extraction
            # (they will be properly extracted by _handle_textbox_content instead)
            def _in_textbox(elem):
                return any(
                    etree.QName(anc).localname in ["txbxContent", "textbox"]
                    for anc in elem.iterancestors()
                )

            drawing_blip = [x for x in _raw_drawing_blip if not _in_textbox(x)]
            drawingml_els = [x for x in _raw_drawingml_els if not _in_textbox(x)]
            vml_images = [x for x in _raw_vml_images if not _in_textbox(x)]

            # Check for textbox content - check multiple textbox formats
            # Only process if the element hasn't been processed before
            element_id = id(element)
            if element_id not in self.processed_textbox_elements:
                # Modern Word textboxes
                txbx_xpath = etree.XPath(
                    ".//w:txbxContent|.//v:textbox//w:p",
                    namespaces=MsWordDocumentBackend._BLIP_NAMESPACES,
                )
                textbox_elements = txbx_xpath(element)

                # No modern textboxes found, check for alternate/legacy textbox formats
                if not textbox_elements:
                    # Additional checks for textboxes in DrawingML and VML formats
                    alt_txbx_xpath = etree.XPath(
                        ".//wps:txbx//w:p|.//w10:wrap//w:p|.//v:textbox//w:txbxContent//w:p",
                        namespaces=MsWordDocumentBackend._BLIP_NAMESPACES,
                    )
                    textbox_elements = alt_txbx_xpath(element)

                    # Check for shape text that's not in a standard textbox
                    if not textbox_elements:
                        shape_text_xpath = etree.XPath(
                            ".//a:bodyPr/ancestor::*//a:t|.//a:txBody//a:t",
                            namespaces=MsWordDocumentBackend._BLIP_NAMESPACES,
                        )
                        shape_text_elements = shape_text_xpath(element)
                        if shape_text_elements:
                            # Create custom text elements from shape text
                            text_content = " ".join(
                                [t.text for t in shape_text_elements if t.text]
                            )
                            if text_content.strip():
                                _log.debug(f"Found shape text: {text_content[:50]}...")
                                # Create a paragraph-like element to process with standard handler
                                level = self._get_level()
                                shape_group = doc.add_group(
                                    label=GroupLabel.SECTION,
                                    parent=self.parents[level - 1],
                                    name="shape-text",
                                    content_layer=self.content_layer,
                                )
                                added_elements.append(shape_group.get_ref())
                                doc.add_text(
                                    label=DocItemLabel.TEXT,
                                    parent=shape_group,
                                    text=text_content,
                                    content_layer=self.content_layer,
                                )

                if textbox_elements:
                    # Mark the parent element as processed
                    self.processed_textbox_elements.append(element_id)
                    # Also mark all found textbox elements as processed
                    for tb_element in textbox_elements:
                        self.processed_textbox_elements.append(id(tb_element))

                    _log.debug(
                        f"Found textbox content with {len(textbox_elements)} elements"
                    )
                    tbc = self._handle_textbox_content(textbox_elements, doc)
                    added_elements.extend(tbc)

            # Check for Tables
            if tag_name == "tbl":
                try:
                    t = self._handle_tables(element, doc)
                    added_elements.extend(t)
                except Exception:
                    _log.debug("could not parse a table, broken docx table")
            # Check for Image
            elif drawing_blip:
                pics = self._handle_pictures(drawing_blip, doc)
                added_elements.extend(pics)
                # Check for Text after the Image
                if (
                    tag_name == "p"
                    and element.find(
                        ".//w:t", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
                    )
                    is not None
                ):
                    te1 = self._handle_text_elements(element, doc)
                    added_elements.extend(te1)
            # Check for VML images (legacy format, e.g., embedded Visio drawings)
            elif vml_images:
                vml_pics = self._handle_vml_pictures(vml_images, doc)
                added_elements.extend(vml_pics)
                # Check for Text after the VML Image
                if (
                    tag_name == "p"
                    and element.find(
                        ".//w:t", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
                    )
                    is not None
                ):
                    te2 = self._handle_text_elements(element, doc)
                    added_elements.extend(te2)
            # Check for DrawingML elements
            elif drawingml_els:
                if (
                    self.docx_to_pdf_converter is None
                    and self.docx_to_pdf_converter_init is False
                ):
                    self.docx_to_pdf_converter = get_docx_to_pdf_converter()
                    self.docx_to_pdf_converter_init = True

                if self.docx_to_pdf_converter is None:
                    if self.display_drawingml_warning:
                        _log.warning(
                            "Found DrawingML elements in document, but no DOCX to PDF converters. "
                            "If you want these exported, make sure you have "
                            "LibreOffice binary in PATH or specify its path with DOCLING_LIBREOFFICE_CMD."
                        )
                        self.display_drawingml_warning = False
                else:
                    self._handle_drawingml(doc=doc, drawingml_els=drawingml_els)

                # Always process text in paragraph
                if (
                    tag_name == "p"
                    and element.find(
                        ".//w:t", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
                    )
                    is not None
                ):
                    te = self._handle_text_elements(element, doc, skip_empty_text=True)
                    added_elements.extend(te)
            # Check for the sdt containers, like table of contents
            elif tag_name == "sdt":
                sdt_content = element.find(
                    "./w:sdtContent", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
                )
                if sdt_content is not None:
                    # Recursively walk the SDT content to catch textboxes, tables, and nested structures
                    _, te = self._walk_linear(sdt_content, doc)
                    added_elements.extend(te)
            # Check for Text
            elif tag_name == "p":
                # "tcPr", "sectPr"
                te = self._handle_text_elements(element, doc)
                added_elements.extend(te)
            else:
                _log.debug(f"Ignoring element in DOCX with tag: {tag_name}")

        return doc, added_elements

    def _is_invisible_spacer(self, pil_image: Image.Image | None) -> bool:
        """Check if an image is an invisible layout spacer rather than a meaningful graphic."""
        if pil_image is None:
            return False

        # Filter tiny spacer images
        if pil_image.width * pil_image.height <= self.SPACER_IMAGE_AREA_THRESHOLD:
            return True

        try:
            extrema = pil_image.getextrema()
            if extrema is not None:
                if pil_image.mode in ("RGBA", "LA"):
                    # extrema[-1] is the Alpha channel. If max alpha is 0, it is 100% invisible.
                    if extrema[-1][1] == 0:
                        return True
                elif pil_image.mode == "RGB":
                    # If all channels are exactly 255, it is a pure white spacing box.
                    if extrema == ((255, 255), (255, 255), (255, 255)):
                        return True
        except Exception:
            pass  # pragma: no cover

        return False

    def _str_to_int(self, s: str | None, default: int | None = 0) -> int | None:
        if s is None:
            return None
        try:
            return int(s)
        except ValueError:
            return default

    def _split_text_and_number(self, input_string: str) -> list[str]:
        match = re.match(r"(\D+)(\d+)$|^(\d+)(\D+)", input_string)
        if match:
            parts = list(filter(None, match.groups()))
            return parts
        else:
            return [input_string]

    def _get_numId_and_ilvl(
        self, paragraph: Paragraph
    ) -> tuple[int | None, int | None]:
        # Access the XML element of the paragraph
        numPr = paragraph._element.find(
            ".//w:numPr", namespaces=paragraph._element.nsmap
        )

        if numPr is not None:
            # Get the numId element and extract the value
            numId_elem = numPr.find("w:numId", namespaces=paragraph._element.nsmap)
            ilvl_elem = numPr.find("w:ilvl", namespaces=paragraph._element.nsmap)
            numId = numId_elem.get(self.XML_KEY) if numId_elem is not None else None
            ilvl = ilvl_elem.get(self.XML_KEY) if ilvl_elem is not None else None

            return self._str_to_int(numId, None), self._str_to_int(ilvl, None)

        # If not found directly in paragraph, check if the style defines numbering
        if paragraph.style is not None:
            style_elem = getattr(paragraph.style, "element", None)
            if style_elem is not None:
                style_numPr = style_elem.find(f".//{self._W_NS_CLARK}numPr")
                if style_numPr is not None:
                    numId_elem = style_numPr.find(f"{self._W_NS_CLARK}numId")
                    ilvl_elem = style_numPr.find(f"{self._W_NS_CLARK}ilvl")
                    numId = (
                        numId_elem.get(self.XML_KEY) if numId_elem is not None else None
                    )
                    ilvl = (
                        ilvl_elem.get(self.XML_KEY) if ilvl_elem is not None else None
                    )

                    # If numId is found but ilvl is not specified, default to level 0
                    if numId is not None and ilvl is None:
                        ilvl = "0"

                    return self._str_to_int(numId, None), self._str_to_int(ilvl, None)

        return None, None  # If the paragraph is not part of a list

    def _get_level_element(self, numid: int, ilvl: int) -> BaseOxmlElement | None:
        """Find the level element from the numbering XML for a given numId and ilvl."""
        try:
            if not hasattr(self.docx_obj, "part") or not hasattr(
                self.docx_obj.part, "package"
            ):
                return None

            numbering_part = None
            for part in self.docx_obj.part.package.parts:
                if "numbering" in part.partname:
                    numbering_part = part
                    break

            if numbering_part is None:
                return None

            numbering_root = numbering_part.element
            namespaces = {"w": self._W_NS}

            num_element = numbering_root.find(
                f".//w:num[@w:numId='{numid}']", namespaces=namespaces
            )
            if num_element is None:
                return None

            abstract_num_id_elem = num_element.find(
                ".//w:abstractNumId", namespaces=namespaces
            )
            if abstract_num_id_elem is None:
                return None

            abstract_num_id = abstract_num_id_elem.get(self.XML_KEY)
            if abstract_num_id is None:
                return None

            abstract_num_element = numbering_root.find(
                f".//w:abstractNum[@w:abstractNumId='{abstract_num_id}']",
                namespaces=namespaces,
            )
            if abstract_num_element is None:
                return None

            return abstract_num_element.find(
                f".//w:lvl[@w:ilvl='{ilvl}']", namespaces=namespaces
            )
        except Exception as e:
            _log.debug(f"Error finding level element: {e}")
            return None

    def _get_start_value(self, numid: int, ilvl: int) -> int:
        """Read the start value from the abstractNum definition."""
        lvl_element = self._get_level_element(numid, ilvl)
        if lvl_element is not None:
            namespaces = {"w": self._W_NS}
            start_element = lvl_element.find(".//w:start", namespaces=namespaces)
            if start_element is not None:
                val = start_element.get(self.XML_KEY)
                if val is not None:
                    return int(val)
        return 1

    def _get_list_counter(self, numid: int, ilvl: int) -> int:
        """Get and increment the counter for a specific numId and ilvl combination."""
        key = (numid, ilvl)
        if key not in self.list_counters:
            start = self._get_start_value(numid, ilvl)
            self.list_counters[key] = start - 1
        self.list_counters[key] += 1
        # Reset sub-level counters since parent level advanced
        for k in [k for k in self.list_counters if k[0] == numid and k[1] > ilvl]:
            self.list_counters[k] = 0
        return self.list_counters[key]

    def _reset_list_counters_for_new_sequence(self, numid: int):
        """Reset counters when starting a new numbering sequence."""
        # Reset all counters for this numid
        keys_to_reset = [key for key in self.list_counters.keys() if key[0] == numid]
        for key in keys_to_reset:
            self.list_counters[key] = 0

    def _build_enum_marker(self, numid: int, ilvl: int) -> str:
        """Build enumeration marker from the lvlText template (e.g. 'Proposal %1:').

        Uses lvlText when it contains a text prefix/suffix beyond simple
        placeholders and separators.  Falls back to the default '1.2.3.'
        pattern for plain numeric markers.
        """
        lvl_element = self._get_level_element(numid, ilvl)
        namespaces = {"w": self._W_NS}
        lvl_text = None
        if lvl_element is not None:
            lt = lvl_element.find(".//w:lvlText", namespaces=namespaces)
            if lt is not None:
                lvl_text = lt.get(self.XML_KEY)

        # Use lvlText as template only when it contains %N placeholders
        # alongside non-trivial text (e.g. "Proposal %1:", "Table %1").
        # Skip when lvlText is a bare bullet symbol like "o" or "•".
        if lvl_text and re.search(r"%\d+", lvl_text):
            stripped = re.sub(r"%\d+", "", lvl_text)
            stripped = stripped.strip(" .)(:[]")
            if stripped:

                def _replace(match):
                    lvl_idx = int(match.group(1)) - 1
                    counter = self.list_counters.get((numid, lvl_idx))
                    if counter is None:
                        counter = self._get_start_value(numid, lvl_idx)
                    return str(counter)

                return re.sub(r"%(\d+)", _replace, lvl_text)

        # Fallback: default hierarchical '1.2.3.' pattern
        parts = []
        for lvl in range(ilvl + 1):
            counter = self.list_counters.get((numid, lvl))
            if counter is None:
                counter = self._get_start_value(numid, lvl)
            parts.append(str(counter))
        return ".".join(parts) + "."

    def _is_numbered_list(self, numId: int, ilvl: int) -> bool:
        """Check if a list is numbered based on its numFmt value."""
        try:
            lvl_element = self._get_level_element(numId, ilvl)
            if lvl_element is None:
                return False

            namespaces = {"w": self._W_NS}
            num_fmt_element = lvl_element.find(".//w:numFmt", namespaces=namespaces)
            if num_fmt_element is None:
                return False

            num_fmt = num_fmt_element.get(self.XML_KEY)

            numbered_formats = {
                "decimal",
                "lowerRoman",
                "upperRoman",
                "lowerLetter",
                "upperLetter",
                "decimalZero",
            }

            return num_fmt in numbered_formats

        except Exception as e:
            _log.debug(f"Error determining if list is numbered: {e}")
            return False

    def _get_outline_level_from_style(self, paragraph: Paragraph) -> int | None:
        """Extract outlineLvl from paragraph's style definition.

        In OOXML, outlineLvl is 0-indexed (0-8 for heading levels 1-9).
        This method returns the 1-indexed heading level (outlineLvl + 1).
        """
        if paragraph.style is None:
            return None

        style_elem = getattr(paragraph.style, "element", None)
        if style_elem is None:
            return None

        # Look for outlineLvl in the style's paragraph properties
        outline_elem = style_elem.find(f".//{self._W_NS_CLARK}outlineLvl")
        if outline_elem is not None:
            val = outline_elem.get(f"{self._W_NS_CLARK}val")
            if val is not None:
                try:
                    # Convert 0-indexed outlineLvl to 1-indexed heading level
                    return int(val) + 1
                except ValueError:
                    pass
        return None

    def _get_heading_and_level(self, style_label: str) -> tuple[str, int | None]:
        parts = self._split_text_and_number(style_label)

        if len(parts) == 2:
            parts.sort()
            label_str: str = ""
            label_level: int | None = 0
            if parts[0].strip().lower() == "heading":
                label_str = "Heading"
                label_level = self._str_to_int(parts[1], None)
            if parts[1].strip().lower() == "heading":
                label_str = "Heading"
                label_level = self._str_to_int(parts[0], None)
            # Ensure heading level is at least 1 (e.g., custom "Heading 0" styles)
            if isinstance(label_level, int) and label_level < 1:
                label_level = 1
            return label_str, label_level

        return style_label, None

    def _get_label_and_level(self, paragraph: Paragraph) -> tuple[str, int | None]:
        if paragraph.style is None:
            return "Normal", None

        label: str = paragraph.style.style_id
        name: str = paragraph.style.name or ""
        base_style_label: str | None = None
        base_style_name: str | None = None
        if isinstance(
            base_style := getattr(paragraph.style, "base_style", None), ParagraphStyle
        ):
            base_style_label = base_style.style_id
            base_style_name = base_style.name

        if not label:
            return "Normal", None

        if ":" in label:
            parts = label.split(":")
            if len(parts) == 2:
                return parts[0], self._str_to_int(parts[1], None)

        # Check if this is a heading style
        is_heading = (
            "heading" in label.lower()
            or "heading" in name.lower()
            or (base_style_label and "heading" in base_style_label.lower())
            or (base_style_name and "heading" in base_style_name.lower())
        )

        if is_heading:
            # First try to get the level from outlineLvl (authoritative source)
            outline_level = self._get_outline_level_from_style(paragraph)
            if outline_level is not None:
                return "Heading", outline_level

            # Fall back to parsing level from style name
            if "heading" in label.lower():
                return self._get_heading_and_level(label)
            if "heading" in name.lower():
                return self._get_heading_and_level(name)
            if base_style_label and "heading" in base_style_label.lower():
                return self._get_heading_and_level(base_style_label)
            if base_style_name and "heading" in base_style_name.lower():
                return self._get_heading_and_level(base_style_name)

        return label, None

    @classmethod
    def _get_format_from_run(
        cls, run: Run, paragraph: Paragraph | None = None
    ) -> Formatting | None:
        is_bold = run.bold

        if not is_bold:
            try:
                # Check the raw XML of the run itself for <w:b> tags
                if hasattr(run, "_element") and run._element is not None:
                    b_tags = run._element.xpath(".//w:b | .//w:bCs")
                    for b in b_tags:
                        val = b.get(
                            "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val"
                        )
                        if val not in ["0", "false"]:
                            is_bold = True
                            break

                # Check the paragraph's direct formatting properties
                if (
                    not is_bold
                    and hasattr(run, "_parent")
                    and hasattr(run._parent, "_element")
                ):
                    pPr_b = run._parent._element.xpath(
                        "./w:pPr/w:rPr/w:b | ./w:pPr/w:rPr/w:bCs"
                    )
                    for b in pPr_b:
                        val = b.get(
                            "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}val"
                        )
                        if val not in ["0", "false"]:
                            is_bold = True
                            break

                # Recursively climb the paragraph's Master Style Sheet
                if (
                    not is_bold
                    and paragraph is not None
                    and getattr(paragraph, "style", None)
                ):
                    current_style = paragraph.style
                    while current_style is not None:
                        if hasattr(current_style, "font") and current_style.font.bold:
                            is_bold = True
                            break

                        current_style = getattr(current_style, "base_style", None)
            except Exception:
                pass

        is_bold = is_bold or False

        is_italic = run.italic or False
        is_strikethrough = run.font.strike or False
        # Convert any non-None underline value to True
        is_underline = bool(run.underline is not None and run.underline)
        is_sub = run.font.subscript or False
        is_sup = run.font.superscript or False
        script = Script.SUB if is_sub else Script.SUPER if is_sup else Script.BASELINE

        return Formatting(
            bold=is_bold,
            italic=is_italic,
            underline=is_underline,
            strikethrough=is_strikethrough,
            script=script,
        )

    def _get_hyperlink_target(self, hyperlink: Hyperlink) -> AnyUrl | Path | None:
        if hyperlink.address:
            return (
                AnyUrl(hyperlink.address)
                if urlparse(hyperlink.address).scheme
                else Path(hyperlink.address)
            )

        return None

    def _iter_paragraph_content(
        self, paragraph: Paragraph
    ) -> list[tuple[str, Formatting | None, AnyUrl | Path | None]]:
        if not hasattr(paragraph, "_p"):
            return []

        content: list[tuple[str, Formatting | None, AnyUrl | Path | None]] = []

        def _get_children_recursive(node):
            for child in node:
                tag_name = etree.QName(child).localname
                if tag_name in {"smartTag", "customXml", "ins", "fldSimple"}:
                    yield from _get_children_recursive(child)
                else:
                    yield child

        for child in _get_children_recursive(paragraph._p):
            tag_name = etree.QName(child).localname

            if tag_name == "sdt":
                text = "".join(
                    child.xpath(
                        ".//w:sdtContent//w:t/text()",
                        namespaces=MsWordDocumentBackend._BLIP_NAMESPACES,
                    )
                )
                if len(text) == 0:
                    continue

                runs = child.xpath(
                    ".//w:sdtContent//w:r",
                    namespaces=MsWordDocumentBackend._BLIP_NAMESPACES,
                )
                fmt = (
                    self._get_format_from_run(Run(runs[0], paragraph), paragraph)
                    if runs
                    else None
                )
                content.append((text, fmt, None))
                continue

            if tag_name not in {"r", "hyperlink"}:
                continue

            item = (
                Run(child, paragraph)
                if tag_name == "r"
                else Hyperlink(child, paragraph)
            )

            if isinstance(item, Hyperlink):
                content.append(
                    (
                        item.text,
                        (
                            self._get_format_from_run(item.runs[0], paragraph)
                            if item.runs and len(item.runs) > 0
                            else None
                        ),
                        self._get_hyperlink_target(item),
                    )
                )
            elif isinstance(item, Run):
                content.append(
                    (item.text, self._get_format_from_run(item, paragraph), None)
                )

        return content

    def _get_paragraph_text(self, paragraph: Paragraph) -> str:
        if not hasattr(paragraph, "iter_inner_content") or not hasattr(paragraph, "_p"):
            return paragraph.text

        return "".join(
            text
            for text, _format, _hyperlink in self._iter_paragraph_content(paragraph)
        )

    def _get_paragraph_elements(self, paragraph: Paragraph):
        """
        Extract paragraph elements along with their formatting and hyperlink
        """

        # for now retain empty paragraphs for backwards compatibility:
        if self._get_paragraph_text(paragraph).strip() == "":
            return [("", None, None)]

        paragraph_elements: list[
            tuple[str, Formatting | None, AnyUrl | Path | None]
        ] = []
        group_text = ""
        previous_format = None
        last_format = None

        # Iterate over the runs of the paragraph and group them by format
        for text, format, hyperlink in self._iter_paragraph_content(paragraph):
            last_format = format

            if (len(text.strip()) and format != previous_format) or (
                hyperlink is not None
            ):
                # If the style changes for a non empty text, add the previous group
                if len(group_text.strip()) > 0:
                    paragraph_elements.append(
                        (group_text.strip(), previous_format, None)
                    )
                group_text = ""

                # If there is a hyperlink, add it immediately
                if hyperlink is not None:
                    paragraph_elements.append((text.strip(), format, hyperlink))
                    text = ""
                else:
                    previous_format = format

            group_text += text

        # Format the last group
        if len(group_text.strip()) > 0:
            paragraph_elements.append((group_text.strip(), last_format, None))

        return paragraph_elements

    def _has_checkbox(self, element: BaseOxmlElement) -> bool:
        """Check if a paragraph element contains a checkbox.

        Args:
            element: The paragraph element to check for checkbox presence.

        Returns:
            True if the element contains a checkbox, False otherwise.
        """
        try:
            checkboxes = element.findall(
                f".//{{{self._BLIP_NAMESPACES['w14']}}}checkbox"
            )
            return len(checkboxes) > 0
        except (AttributeError, TypeError):
            return False

    def _is_checkbox_checked(self, element: BaseOxmlElement) -> bool:
        """Check if a checkbox in the paragraph is checked.

        Args:
            element: The paragraph element containing the checkbox.

        Returns:
            True if checked (w14:checked val="1"), False if unchecked
                (val="0" or missing).
        """
        w14_ns = self._BLIP_NAMESPACES["w14"]
        checkboxes = element.findall(f".//{{{w14_ns}}}checkbox")
        if not checkboxes:
            return False

        checkbox = checkboxes[0]
        checked_elem = checkbox.find(f".//{{{w14_ns}}}checked")

        if checked_elem is not None:
            val = checked_elem.get(f"{{{w14_ns}}}val")
            return val == "1"

        return False

    def _get_checkbox_label(self, element: BaseOxmlElement) -> DocItemLabel | None:
        """Get the appropriate checkbox label for a paragraph element.

        Args:
            element: The paragraph element to check for checkbox.

        Returns:
            DocItemLabel.CHECKBOX_SELECTED if checked, DocItemLabel.CHECKBOX_UNSELECTED
                if unchecked, or None if no checkbox is present.
        """
        if not self._has_checkbox(element):
            return None

        if self._is_checkbox_checked(element):
            return DocItemLabel.CHECKBOX_SELECTED
        else:
            return DocItemLabel.CHECKBOX_UNSELECTED

    def _clean_checkbox_symbols(self, text: str) -> str:
        """Remove checkbox symbols from text.

        Removes common checkbox symbols like ☐, ☑, ☒ from the beginning of text.

        Args:
            text: The text string to clean.

        Returns:
            The text with checkbox symbols removed from the beginning.
        """
        # Common checkbox symbols in docx documents
        checkbox_symbols = ["☐", "☑", "☒", "□", "■", "▪", "▫"]

        text = text.strip()
        for symbol in checkbox_symbols:
            if text.startswith(symbol):
                text = text[len(symbol) :].strip()
                break

        return text

    def _get_paragraph_position(self, paragraph_element):
        """Extract vertical position information from paragraph element."""
        # First try to directly get the index from w:p element that has an order-related attribute
        if (
            hasattr(paragraph_element, "getparent")
            and paragraph_element.getparent() is not None
        ):
            parent = paragraph_element.getparent()
            # Get all paragraph siblings
            paragraphs = [
                p for p in parent.getchildren() if etree.QName(p).localname == "p"
            ]
            # Find index of current paragraph within its siblings
            try:
                paragraph_index = paragraphs.index(paragraph_element)
                return paragraph_index  # Use index as position for consistent ordering
            except ValueError:
                pass

        # Look for position hints in element attributes and ancestor elements
        for elem in (*[paragraph_element], *paragraph_element.iterancestors()):
            # Check for direct position attributes
            for attr_name in ["y", "top", "positionY", "y-position", "position"]:
                value = elem.get(attr_name)
                if value:
                    try:
                        # Remove any non-numeric characters (like 'pt', 'px', etc.)
                        clean_value = re.sub(r"[^0-9.]", "", value)
                        if clean_value:
                            return float(clean_value)
                    except (ValueError, TypeError):
                        pass

            # Check for position in transform attribute
            transform = elem.get("transform")
            if transform:
                # Extract translation component from transform matrix
                match = re.search(r"translate\([^,]+,\s*([0-9.]+)", transform)
                if match:
                    try:
                        return float(match.group(1))
                    except ValueError:
                        pass

            # Check for anchors or relative position indicators in Word format
            # 'dist' attributes can indicate relative positioning
            for attr_name in ["distT", "distB", "anchor", "relativeFrom"]:
                if elem.get(attr_name) is not None:
                    return elem.sourceline  # Use the XML source line number as fallback

        # For VML shapes, look for specific attributes
        for ns_uri in paragraph_element.nsmap.values():
            if "vml" in ns_uri:
                # Try to extract position from style attribute
                style = paragraph_element.get("style")
                if style:
                    match = re.search(r"top:([0-9.]+)pt", style)
                    if match:
                        try:
                            return float(match.group(1))
                        except ValueError:
                            pass

        # If no better position indicator found, use XML source line number as proxy for order
        return (
            paragraph_element.sourceline
            if hasattr(paragraph_element, "sourceline")
            else None
        )

    def _collect_textbox_paragraphs(self, textbox_elements):
        """Collect and organize paragraphs from textbox elements."""
        processed_paragraphs = []
        container_paragraphs = {}

        for element in textbox_elements:
            element_id = id(element)
            # Skip if we've already processed this exact element
            if element_id in processed_paragraphs:
                continue

            tag_name = etree.QName(element).localname
            processed_paragraphs.append(element_id)

            # Handle paragraphs directly found (VML textboxes)
            if tag_name == "p":
                # Find the containing textbox or shape element
                container_id = None
                for ancestor in element.iterancestors():
                    if any(ns in ancestor.tag for ns in ["textbox", "shape", "txbx"]):
                        container_id = id(ancestor)
                        break

                if container_id not in container_paragraphs:
                    container_paragraphs[container_id] = []
                container_paragraphs[container_id].append(
                    (element, self._get_paragraph_position(element))
                )

            # Handle txbxContent elements (Word DrawingML textboxes)
            elif tag_name == "txbxContent":
                paragraphs = element.findall(".//w:p", namespaces=element.nsmap)
                container_id = id(element)
                if container_id not in container_paragraphs:
                    container_paragraphs[container_id] = []

                for p in paragraphs:
                    p_id = id(p)
                    if p_id not in processed_paragraphs:
                        processed_paragraphs.append(p_id)
                        container_paragraphs[container_id].append(
                            (p, self._get_paragraph_position(p))
                        )
            else:
                # Try to extract any paragraphs from unknown elements
                paragraphs = element.findall(".//w:p", namespaces=element.nsmap)
                container_id = id(element)
                if container_id not in container_paragraphs:
                    container_paragraphs[container_id] = []

                for p in paragraphs:
                    p_id = id(p)
                    if p_id not in processed_paragraphs:
                        processed_paragraphs.append(p_id)
                        container_paragraphs[container_id].append(
                            (p, self._get_paragraph_position(p))
                        )

        return container_paragraphs

    def _handle_textbox_content(
        self,
        textbox_elements: list,
        doc: DoclingDocument,
    ) -> list[RefItem]:
        """Process textbox content and add it to the document structure."""
        elem_ref: list[RefItem] = []
        level = self._get_level()
        # Create a textbox group to contain all text from the textbox
        textbox_group = doc.add_group(
            label=GroupLabel.SECTION,
            parent=self.parents[level - 1],
            name="textbox",
            content_layer=self.content_layer,
        )
        elem_ref.append(textbox_group.get_ref())
        # Set this as the current parent to ensure textbox content
        # is properly nested in document structure
        original_parent = self.parents[level]
        self.parents[level] = textbox_group

        # Collect and organize paragraphs
        container_paragraphs = self._collect_textbox_paragraphs(textbox_elements)

        # Process all paragraphs
        all_paragraphs = []

        # Sort paragraphs within each container, then process containers
        for paragraphs in container_paragraphs.values():
            # Sort by vertical position within each container
            sorted_container_paragraphs = sorted(
                paragraphs,
                key=lambda x: (
                    x[1] is None,
                    x[1] if x[1] is not None else float("inf"),
                ),
            )

            # Add the sorted paragraphs to our processing list
            all_paragraphs.extend(sorted_container_paragraphs)

        # Track processed paragraphs to avoid duplicates
        processed_paragraphs = set()

        # Process all the paragraphs
        for p, position in all_paragraphs:
            # Create paragraph object to get text content
            paragraph = Paragraph(p, self.docx_obj)
            text_content = paragraph.text.strip()

            if text_content:
                # Deduplicate AlternateContent by exact text natively
                if text_content in processed_paragraphs:
                    continue
                processed_paragraphs.add(text_content)
            else:
                # Preserve empty regions (images) based on position
                paragraph_id = (text_content, position)
                if paragraph_id in processed_paragraphs:
                    continue
                processed_paragraphs.add(paragraph_id)

            elem_ref.extend(self._handle_text_elements(p, doc))

            # Extract embedded images inside the text box
            tb_drawing_blip = self.blip_xpath_expr(p)
            tb_vml_images = self.vml_imagedata_xpath_expr(p)
            tb_drawingml_els = p.findall(
                ".//w:drawing", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
            )

            if tb_drawing_blip:
                pics = self._handle_pictures(tb_drawing_blip, doc)
                elem_ref.extend(pics)
            elif tb_vml_images:
                vml_pics = self._handle_vml_pictures(tb_vml_images, doc)
                elem_ref.extend(vml_pics)
            elif tb_drawingml_els:
                self._handle_drawingml(doc=doc, drawingml_els=tb_drawingml_els)

        # Restore original parent
        self.parents[level] = original_parent
        return elem_ref

    def _handle_equations_in_text(self, element, text):
        only_texts = []
        only_equations = []
        texts_and_equations = []

        # Collect oMath elements and text runs from the paragraph.
        # Use direct children iteration first; fall back to deep iteration
        # only if no oMath elements are found at the direct level.
        direct_omaths = [
            child
            for child in element
            if "oMath" in child.tag and "oMathPara" not in child.tag
        ]

        if direct_omaths:
            # Iterate direct children to preserve sibling order and avoid
            # processing nested oMath descendants of an already-converted node.
            for child in element:
                if "oMath" in child.tag and "oMathPara" not in child.tag:
                    latex_equation = str(oMath2Latex(child)).strip()
                    if len(latex_equation) > 0:
                        only_equations.append(
                            self.equation_bookends.format(EQ=latex_equation)
                        )
                        texts_and_equations.append(
                            self.equation_bookends.format(EQ=latex_equation)
                        )
                else:
                    # Collect text from non-math children (e.g. <w:r> runs)
                    for t_elem in child.iter():
                        t_tag = etree.QName(t_elem).localname
                        if t_tag == "t" and "math" not in t_elem.tag:
                            if isinstance(t_elem.text, str):
                                only_texts.append(t_elem.text)
                                texts_and_equations.append(t_elem.text)
        else:
            # Original deep-iteration fallback for nested oMath (e.g.
            # inside oMathPara or other wrapper elements).
            for subt in element.iter():
                tag_name = etree.QName(subt).localname
                if tag_name == "t" and "math" not in subt.tag:
                    if isinstance(subt.text, str):
                        only_texts.append(subt.text)
                        texts_and_equations.append(subt.text)
                elif "oMath" in subt.tag and "oMathPara" not in subt.tag:
                    latex_equation = str(oMath2Latex(subt)).strip()
                    if len(latex_equation) > 0:
                        only_equations.append(
                            self.equation_bookends.format(EQ=latex_equation)
                        )
                        texts_and_equations.append(
                            self.equation_bookends.format(EQ=latex_equation)
                        )

        if len(only_equations) < 1:
            return text, []

        if (
            re.sub(r"\s+", "", "".join(only_texts)).strip()
            != re.sub(r"\s+", "", text).strip()
        ):
            # If we are not able to reconstruct the initial raw text
            # do not try to parse equations and return the original
            return text, []

        # Insert equations into original text
        # This is done to preserve white space structure
        output_text = ""
        text_pos = 0

        for substr in texts_and_equations:
            if len(substr) == 0:
                continue
            if substr.startswith("<eq>"):
                # This is an equation - insert it directly
                output_text += substr
            else:
                # This is a text fragment - find it in original text
                pos = text.find(substr, text_pos)
                if pos >= 0:
                    output_text += substr
                    text_pos = pos + len(substr)
                else:
                    # Fallback: if not found, just append it
                    output_text += substr

        return output_text, only_equations

    def _create_or_reuse_parent(
        self,
        *,
        doc: DoclingDocument,
        prev_parent: NodeItem | None,
        paragraph_elements: list,
    ) -> NodeItem | None:
        return (
            doc.add_inline_group(parent=prev_parent, content_layer=self.content_layer)
            if len(paragraph_elements) > 1
            else prev_parent
        )

    def _handle_text_elements(
        self,
        element: BaseOxmlElement,
        doc: DoclingDocument,
        skip_empty_text: bool = False,
    ) -> list[RefItem]:
        elem_ref: list[RefItem] = []
        paragraph = Paragraph(element, self.docx_obj)
        paragraph_elements = self._get_paragraph_elements(paragraph)
        text, equations = self._handle_equations_in_text(
            element=element, text=self._get_paragraph_text(paragraph)
        )

        if text is None:
            return elem_ref
        text = text.strip()

        # Track the paragraph element ID for comment linking
        para_element_id = id(element)
        comment_ids = self._get_comment_ids_for_element(element)

        # Check if this paragraph contains a checkbox
        checkbox_label = self._get_checkbox_label(element)

        # Common styles for bullet and numbered lists.
        # "List Bullet", "List Number", "List Paragraph"
        # Identify whether list is a numbered list or not
        p_style_id, p_level = self._get_label_and_level(paragraph)
        numid, ilevel = self._get_numId_and_ilvl(paragraph)

        if numid == 0:
            numid = None

        # Handle lists
        if (
            numid is not None
            and ilevel is not None
            and p_style_id not in ["Title", "Heading"]
        ):
            # Check if this is actually a numbered list by examining the numFmt
            is_numbered = self._is_numbered_list(numid, ilevel)

            # If there are equations in the list item, handle them specially
            if len(equations) > 0:
                li = self._add_list_item_with_equations(
                    doc=doc,
                    numid=numid,
                    ilevel=ilevel,
                    text=text,
                    equations=equations,
                    is_numbered=is_numbered,
                )
            else:
                li = self._add_list_item(
                    doc=doc,
                    numid=numid,
                    ilevel=ilevel,
                    elements=paragraph_elements,
                    is_numbered=is_numbered,
                )
            elem_ref.extend(li)  # MUST BE REF!!!
            self._update_history(p_style_id, p_level, numid, ilevel)
            return elem_ref
        elif (
            numid is None
            and self._prev_numid() is not None
            and p_style_id not in ["Title", "Heading"]
        ):  # Close list
            self.last_numid = self._prev_numid()
            # Store the list group and its parent for potential reuse
            if self.level_at_new_list and self.level_at_new_list in self.parents:
                parent_item = self.parents.get(self.level_at_new_list)
                if isinstance(parent_item, ListGroup):
                    self.last_list_group = parent_item
                    self.last_list_group_numid = self.last_numid
                    self.last_list_group_parent = self.parents.get(
                        self.level_at_new_list - 1
                    )

            if self.level_at_new_list:
                for key in range(len(self.parents)):
                    if key >= self.level_at_new_list:
                        self.parents[key] = None
                self.level = self.level_at_new_list - 1
                self.level_at_new_list = None
            else:
                for key in range(len(self.parents)):
                    self.parents[key] = None
                self.level = 0

        if p_style_id in ["Title"]:
            for key in range(len(self.parents)):
                self.parents[key] = None
            te = doc.add_text(
                parent=None,
                label=DocItemLabel.TITLE,
                text=text,
                content_layer=self.content_layer,
            )
            self.parents[0] = te
            elem_ref.append(te.get_ref())
        elif "Heading" in p_style_id:
            style_element = getattr(paragraph.style, "element", None)
            if style_element is not None:
                is_numbered_style = (
                    "<w:numPr>" in style_element.xml or "<w:numPr>" in element.xml
                )
            else:
                is_numbered_style = False
            h1 = self._add_heading(doc, p_level, text, is_numbered_style)
            elem_ref.extend(h1)

        elif len(equations) > 0:
            if (paragraph.text is None or len(paragraph.text.strip()) == 0) and len(
                text
            ) > 0:
                # Standalone equation(s) — emit each as a separate formula
                level = self._get_level()
                parent = self.parents[level - 1]
                if len(equations) > 1:
                    for eq in equations:
                        eq_text = eq.replace("<eq>", "").replace("</eq>", "").strip()
                        if len(eq_text) > 0:
                            t1 = doc.add_text(
                                label=DocItemLabel.FORMULA,
                                parent=parent,
                                text=eq_text,
                                content_layer=self.content_layer,
                            )
                            elem_ref.append(t1.get_ref())
                else:
                    t1 = doc.add_text(
                        label=DocItemLabel.FORMULA,
                        parent=parent,
                        text=text.replace("<eq>", "").replace("</eq>", ""),
                        content_layer=self.content_layer,
                    )
                    elem_ref.append(t1.get_ref())
            else:
                # Inline equation
                level = self._get_level()
                inline_equation = doc.add_inline_group(
                    parent=self.parents[level - 1], content_layer=self.content_layer
                )
                elem_ref.append(inline_equation.get_ref())

                self._add_inline_equations_to_parent(
                    doc=doc,
                    parent=inline_equation,
                    text=text,
                    equations=equations,
                    elem_ref=elem_ref,
                )

        else:
            level = self._get_level()
            parent = self._create_or_reuse_parent(
                doc=doc,
                prev_parent=self.parents.get(level - 1),
                paragraph_elements=paragraph_elements,
            )
            for text, format, hyperlink in paragraph_elements:
                # Clean checkbox symbols from text if this is a checkbox item
                clean_text = (
                    self._clean_checkbox_symbols(text) if checkbox_label else text
                )

                # Skip empty text items
                if skip_empty_text and (not clean_text or not clean_text.strip()):
                    continue

                text_item = doc.add_text(
                    label=checkbox_label if checkbox_label else DocItemLabel.TEXT,
                    parent=parent,
                    text=clean_text,
                    formatting=format,
                    hyperlink=hyperlink,
                    content_layer=self.content_layer,
                )
                elem_ref.append(text_item.get_ref())

        self._update_history(p_style_id, p_level, numid, ilevel)

        # Store mapping of paragraph element to created items for comment linking
        if elem_ref and para_element_id:
            self.paragraph_to_items[para_element_id] = elem_ref
            if comment_ids:
                self.paragraph_comment_map[para_element_id] = list(comment_ids)

        return elem_ref

    def _add_heading(
        self,
        doc: DoclingDocument,
        curr_level: int | None,
        text: str,
        is_numbered_style: bool = False,
    ) -> list[RefItem]:
        elem_ref: list[RefItem] = []
        level = self._get_level()
        if isinstance(curr_level, int):
            if curr_level > level:
                # add invisible group
                for i in range(level, curr_level):
                    gr1 = doc.add_group(
                        parent=self.parents[i - 1],
                        label=GroupLabel.SECTION,
                        name=f"header-{i}",
                    )
                    elem_ref.append(gr1.get_ref())
                    self.parents[i] = gr1

            elif curr_level < level:
                # remove the tail
                for key in range(len(self.parents)):
                    if key >= curr_level:
                        self.parents[key] = None

            # Defense in depth: ensure level is at least 1
            curr_level = max(1, curr_level)
            current_level = curr_level
            parent_level = curr_level - 1
            add_level = curr_level
        else:
            current_level = self.level
            parent_level = self.level - 1
            add_level = 1

        if is_numbered_style:
            if add_level in self.numbered_headers:
                self.numbered_headers[add_level] += 1
            else:
                self.numbered_headers[add_level] = 1
            text = f"{self.numbered_headers[add_level]} {text}"

            # Reset deeper levels
            next_level = add_level + 1
            while next_level in self.numbered_headers:
                self.numbered_headers[next_level] = 0
                next_level += 1

            # Scan upper levels
            previous_level = add_level - 1
            while previous_level in self.numbered_headers:
                # MSWord convention: no empty sublevels
                # I.e., sub-sub section (2.0.1) without a sub-section (2.1)
                # is processed as 2.1.1
                if self.numbered_headers[previous_level] == 0:
                    self.numbered_headers[previous_level] += 1

                text = f"{self.numbered_headers[previous_level]}.{text}"
                previous_level -= 1

        hd = doc.add_heading(
            parent=self.parents[parent_level],
            text=text,
            level=add_level,
        )
        self.parents[current_level] = hd
        elem_ref.append(hd.get_ref())
        return elem_ref

    def _add_formatted_list_item(
        self,
        doc: DoclingDocument,
        elements: list,
        marker: str,
        enumerated: bool,
        level: int,
    ) -> list[RefItem]:
        elem_ref: list[RefItem] = []
        # This should not happen by construction
        if not isinstance(self.parents[level], ListGroup):
            _log.warning(
                "Parent element of the list item is not a ListGroup. The list item will be ignored."
            )
            return elem_ref
        if not elements:
            return elem_ref

        if len(elements) == 1:
            text, format, hyperlink = elements[0]
            if text:
                doc.add_list_item(
                    marker=marker,
                    enumerated=enumerated,
                    parent=self.parents[level],
                    text=text,
                    formatting=format,
                    hyperlink=hyperlink,
                )
        else:
            new_item = doc.add_list_item(
                marker=marker,
                enumerated=enumerated,
                parent=self.parents[level],
                text="",
            )
            new_parent = doc.add_inline_group(parent=new_item)
            for text, format, hyperlink in elements:
                if text:
                    doc.add_text(
                        label=DocItemLabel.TEXT,
                        parent=new_parent,
                        text=text,
                        formatting=format,
                        hyperlink=hyperlink,
                        content_layer=self.content_layer,
                    )
        return elem_ref

    def _add_list_item_with_marker(
        self,
        doc: DoclingDocument,
        elements: list,
        numid: int,
        ilevel: int,
        is_numbered: bool,
        level: int,
    ) -> None:
        """Resolve enumeration marker and add a formatted list item."""
        if is_numbered:
            self._get_list_counter(numid, ilevel)
            enum_marker = self._build_enum_marker(numid, ilevel)
        else:
            enum_marker = ""
        self._add_formatted_list_item(doc, elements, enum_marker, is_numbered, level)

    def _add_inline_equations_to_parent(
        self,
        *,
        doc: DoclingDocument,
        parent: NodeItem,
        text: str,
        equations: list[str],
        elem_ref: list[RefItem] | None = None,
    ) -> None:
        """Add text and inline equations as children of a parent element.

        This helper method splits text by equation markers and adds alternating
        TEXT and FORMULA elements as children of the given parent. This logic
        is shared between regular paragraphs with inline equations and list items
        with inline equations.

        Args:
            doc: The DoclingDocument being constructed.
            parent: The parent element (inline_group) to add children to.
            text: The paragraph text with equation placeholders (e.g., "<eq>formula</eq>").
            equations: List of equation strings with markers (e.g., ["<eq>A=B</eq>", ...]).
            elem_ref: Optional list to append created element references to.
        """
        text_tmp = text
        for eq in equations:
            if len(text_tmp) == 0:
                break

            split_text_tmp = text_tmp.split(eq.strip(), maxsplit=1)

            pre_eq_text = split_text_tmp[0]
            text_tmp = "" if len(split_text_tmp) == 1 else split_text_tmp[1]

            if len(pre_eq_text) > 0:
                e1 = doc.add_text(
                    label=DocItemLabel.TEXT,
                    parent=parent,
                    text=pre_eq_text,
                    content_layer=self.content_layer,
                )
                if elem_ref is not None:
                    elem_ref.append(e1.get_ref())

            e2 = doc.add_text(
                label=DocItemLabel.FORMULA,
                parent=parent,
                text=eq.replace("<eq>", "").replace("</eq>", ""),
                content_layer=self.content_layer,
            )
            if elem_ref is not None:
                elem_ref.append(e2.get_ref())

        if len(text_tmp) > 0:
            e3 = doc.add_text(
                label=DocItemLabel.TEXT,
                parent=parent,
                text=text_tmp.strip(),
                content_layer=self.content_layer,
            )
            if elem_ref is not None:
                elem_ref.append(e3.get_ref())

    def _manage_list_structure(
        self,
        *,
        doc: DoclingDocument,
        numid: int,
        ilevel: int,
    ) -> tuple[list[RefItem], int]:
        """Manage list structure and return elem_ref and use_level.

        This helper method handles the list group creation and level management
        that is common to both regular list items and list items with equations.
        It determines whether to open a new list, continue an existing one, handle
        indentation changes, or close lists based on the numbering context.

        Args:
            doc: The DoclingDocument being constructed.
            numid: The numbering ID from the DOCX paragraph properties.
            ilevel: The indentation level from the DOCX paragraph properties.

        Returns:
            A tuple containing the list of references to created list groups and
            the level at which the list item should be added.
        """
        elem_ref: list[RefItem] = []
        level = self._get_level()
        prev_indent = self._prev_indent()

        if self._prev_numid() is None or (
            self._prev_numid() == numid and self.level_at_new_list is None
        ):  # Open new list
            self.level_at_new_list = level
            # Only reset counters if this is a truly new list (different numId)
            if self.last_numid != numid:
                self._reset_list_counters_for_new_sequence(numid)

            list_gr = self._get_or_create_list_group(
                doc=doc,
                numid=numid,
                parent=self.parents[level - 1],
                elem_ref=elem_ref,
            )

            self.parents[level] = list_gr
            use_level = level
            self.last_numid = numid

        elif (
            self._prev_numid() == numid
            and self.level_at_new_list is not None
            and prev_indent is not None
            and prev_indent < ilevel
        ):  # Open indented list
            for i in range(
                self.level_at_new_list + prev_indent + 1,
                self.level_at_new_list + ilevel + 1,
            ):
                list_gr1 = doc.add_list_group(
                    name="list",
                    parent=self.parents[i - 1],
                    content_layer=self.content_layer,
                )
                self.parents[i] = list_gr1
                elem_ref.append(list_gr1.get_ref())
            use_level = self.level_at_new_list + ilevel

        elif (
            self._prev_numid() == numid
            and self.level_at_new_list is not None
            and prev_indent is not None
            and ilevel < prev_indent
        ):  # Close list
            for k in self.parents:
                if k > self.level_at_new_list + ilevel:
                    self.parents[k] = None
            use_level = self.level_at_new_list + ilevel

        elif self._prev_numid() == numid and isinstance(
            self.parents.get(level - 1), ListGroup
        ):
            # Continue existing list
            use_level = level - 1

        elif self._prev_numid() != numid or not isinstance(
            self.parents.get(level - 1), ListGroup
        ):
            # New list sequence
            if self.level_at_new_list is not None:
                use_level = self.level_at_new_list + ilevel
                for k in list(self.parents.keys()):
                    if k > use_level:
                        self.parents[k] = None
            else:
                use_level = level
                self.level_at_new_list = use_level

            # Only reset counters if this is a different numId
            if self.last_numid != numid:
                self._reset_list_counters_for_new_sequence(numid)

            list_gr = self._get_or_create_list_group(
                doc=doc,
                numid=numid,
                parent=self.parents[use_level - 1],
                elem_ref=elem_ref,
            )

            self.parents[use_level] = list_gr
            self.last_numid = numid
        else:
            use_level = level - 1

        return elem_ref, use_level

    def _add_list_item(
        self,
        *,
        doc: DoclingDocument,
        numid: int,
        ilevel: int,
        elements: list,
        is_numbered: bool = False,
    ) -> list[RefItem]:
        """Add a regular list item without inline equations.

        Args:
            doc: The DoclingDocument being constructed.
            numid: The numbering ID from the DOCX paragraph properties.
            ilevel: The indentation level from the DOCX paragraph properties.
            elements: List of (text, formatting, hyperlink) tuples representing the paragraph content.
            is_numbered: Whether this is a numbered list (True) or bulleted list (False).

        Returns:
            List of references to created document elements.
        """
        if not elements:
            return []

        elem_ref, use_level = self._manage_list_structure(
            doc=doc, numid=numid, ilevel=ilevel
        )

        if is_numbered:
            self._get_list_counter(numid, ilevel)
            enum_marker = self._build_enum_marker(numid, ilevel)
        else:
            enum_marker = ""

        self._add_formatted_list_item(
            doc, elements, enum_marker, is_numbered, use_level
        )
        return elem_ref

    def _add_list_item_with_equations(
        self,
        *,
        doc: DoclingDocument,
        numid: int,
        ilevel: int,
        text: str,
        equations: list[str],
        is_numbered: bool = False,
    ) -> list[RefItem]:
        """Add a list item that contains inline equations.

        This method handles list items with inline formulas by creating an inline_group
        structure similar to how non-list paragraphs with equations are handled. The text
        is split by equation markers, and alternating TEXT and FORMULA elements are added
        as children of the inline_group.

        Args:
            doc: The DoclingDocument being constructed.
            numid: The numbering ID from the DOCX paragraph properties.
            ilevel: The indentation level from the DOCX paragraph properties.
            text: The paragraph text with equation placeholders (e.g., "<eq>formula</eq>").
            equations: List of equation strings with markers (e.g., ["<eq>A=B</eq>", ...]).
            is_numbered: Whether this is a numbered list (True) or bulleted list (False).

        Returns:
            List of references to created document elements.
        """
        elem_ref, use_level = self._manage_list_structure(
            doc=doc, numid=numid, ilevel=ilevel
        )

        if is_numbered:
            self._get_list_counter(numid, ilevel)
            enum_marker = self._build_enum_marker(numid, ilevel)
        else:
            enum_marker = ""

        if not isinstance(self.parents[use_level], ListGroup):
            _log.warning(
                "Parent element of the list item is not a ListGroup. The list item will be ignored."
            )
            return elem_ref

        list_item = doc.add_list_item(
            marker=enum_marker,
            enumerated=is_numbered,
            parent=self.parents[use_level],
            text="",
        )

        inline_group = doc.add_inline_group(
            parent=list_item,
            content_layer=self.content_layer,
        )

        self._add_inline_equations_to_parent(
            doc=doc,
            parent=inline_group,
            text=text,
            equations=equations,
        )

        return elem_ref

    @staticmethod
    def _group_cell_elements(
        group_name: str,
        doc: DoclingDocument,
        provs_in_cell: list[RefItem],
        docling_table: TableItem,
        content_layer: ContentLayer = ContentLayer.BODY,
    ) -> RefItem:
        group_element = doc.add_group(
            label=GroupLabel.UNSPECIFIED,
            name=group_name,
            parent=docling_table,
            content_layer=content_layer,
        )
        for prov in provs_in_cell:
            group_element.children.append(prov)
            pr_item = prov.resolve(doc)
            item_parent = pr_item.parent.resolve(doc)
            if pr_item.get_ref() in item_parent.children:
                item_parent.children.remove(pr_item.get_ref())
            pr_item.parent = group_element.get_ref()
        ref_for_rich_cell = group_element.get_ref()
        return ref_for_rich_cell

    def _handle_tables(
        self,
        element: BaseOxmlElement,
        doc: DoclingDocument,
    ) -> list[RefItem]:
        elem_ref: list[RefItem] = []
        table: Table = Table(element, self.docx_obj)
        num_rows = len(table.rows)
        num_cols = len(table.columns)
        _log.debug(f"Table grid with {num_rows} rows and {num_cols} columns")

        if num_rows == 1 and num_cols == 1:
            cell_element = table.rows[0].cells[0]
            # In case we have a table of only 1 cell, we consider it furniture
            # And proceed processing the content of the cell as though it's in the document body
            self._clear_list_group_cache()
            self._walk_linear(cell_element._element, doc)
            return elem_ref

        data = TableData(num_rows=num_rows, num_cols=num_cols)
        level = self._get_level()
        docling_table = doc.add_table(
            data=data, parent=self.parents[level - 1], content_layer=self.content_layer
        )
        elem_ref.append(docling_table.get_ref())

        cell_set: set[CT_Tc] = set()
        for row_idx, row in enumerate(table.rows):
            _log.debug(f"Row index {row_idx} with {len(row.cells)} populated cells")
            col_idx = 0
            while col_idx < num_cols:
                # Handle merged cells: row may have fewer cells than num_cols
                if col_idx >= len(row.cells):
                    break
                cell: _Cell = row.cells[col_idx]
                _log.debug(
                    f" col {col_idx} grid_span {cell.grid_span} grid_cols_before {row.grid_cols_before}"
                )
                if cell is None or cell._tc in cell_set:
                    _log.debug("  skipped since repeated content")
                    col_idx += cell.grid_span
                    continue
                else:
                    cell_set.add(cell._tc)

                spanned_idx = row_idx
                spanned_tc: CT_Tc | None = cell._tc
                while spanned_tc == cell._tc:
                    spanned_idx += 1
                    spanned_tc = (
                        table.rows[spanned_idx].cells[col_idx]._tc
                        if spanned_idx < num_rows
                        else None
                    )
                _log.debug(f"  spanned before row {spanned_idx}")

                # Detect equations in cell text
                text, equations = self._handle_equations_in_text(
                    element=cell._element, text=cell.text
                )
                if len(equations) == 0:
                    text = cell.text
                else:
                    text = text.replace("<eq>", "$").replace("</eq>", "$")

                provs_in_cell: list[RefItem] = []
                rich_table_cell: bool = self._is_rich_table_cell(cell)

                if rich_table_cell:
                    with self._isolated_list_context():
                        _, provs_in_cell = self._walk_linear(cell._element, doc)
                _log.debug(f"Table cell {row_idx},{col_idx} rich? {rich_table_cell}")

                if len(provs_in_cell) > 0:
                    # Cell has multiple elements, we need to group them
                    rich_table_cell = True
                    group_name = f"rich_cell_group_{len(doc.tables)}_{col_idx}_{row.grid_cols_before + row_idx}"
                    ref_for_rich_cell = MsWordDocumentBackend._group_cell_elements(
                        group_name,
                        doc,
                        provs_in_cell,
                        docling_table,
                        content_layer=self.content_layer,
                    )

                if rich_table_cell:
                    rich_cell = RichTableCell(
                        text=text,
                        row_span=spanned_idx - row_idx,
                        col_span=cell.grid_span,
                        start_row_offset_idx=row.grid_cols_before + row_idx,
                        end_row_offset_idx=row.grid_cols_before + spanned_idx,
                        start_col_offset_idx=col_idx,
                        end_col_offset_idx=col_idx + cell.grid_span,
                        column_header=row.grid_cols_before + row_idx == 0,
                        row_header=False,
                        ref=ref_for_rich_cell,  # points to an artificial group around children
                    )
                    doc.add_table_cell(table_item=docling_table, cell=rich_cell)
                    col_idx += cell.grid_span
                else:
                    simple_cell = TableCell(
                        text=text,
                        row_span=spanned_idx - row_idx,
                        col_span=cell.grid_span,
                        start_row_offset_idx=row.grid_cols_before + row_idx,
                        end_row_offset_idx=row.grid_cols_before + spanned_idx,
                        start_col_offset_idx=col_idx,
                        end_col_offset_idx=col_idx + cell.grid_span,
                        column_header=row.grid_cols_before + row_idx == 0,
                        row_header=False,
                    )
                    doc.add_table_cell(table_item=docling_table, cell=simple_cell)
                    col_idx += cell.grid_span
        return elem_ref

    def _has_blip(self, element: BaseOxmlElement) -> bool:
        """Check if a docx element holds any BLIP as a child.

        Args:
            element: a docx element

        Returns:
            Whether the element contains a BLIP as a direct child.
        """

        for item in element:
            if self.blip_xpath_expr(item):
                return True
            if item.findall(
                ".//w:drawing", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
            ):
                return True

        return False

    def _is_rich_table_cell(self, cell: _Cell) -> bool:
        """Determine whether a docx cell should be parsed as a Docling RichTableCell.

        A docx cell can hold rich content and be parsed with a Docling RichTableCell.
        However, this requires walking through the lxml elements and creating
        node items. If the cell holds only plain text, a TableCell, the parsing
        is simpler and using a TableCell is prefered.

        Plain text means:
        - The cell has only one paragraph
        - The paragraph consists solely of runs with no run properties
          (no need of Docling formatting).
        - No other block-level elements are present inside the cell element.

        Args:
            cell: A docx cell

        Returns:
            Whether the docx cell should be parsed as RichTableCell
        """
        tc = cell._tc

        # must contain only one paragraph
        paragraphs = list(tc.iterchildren(f"{self._W_NS_CLARK}p"))
        if len(paragraphs) > 1:
            return True

        # no other content
        allowed_tags = {"p", "tcPr"}  # paragraph or table-cell properties
        for child in tc:
            tag = child.tag.split("}")[-1]
            if tag not in allowed_tags:
                return True
        if self._has_blip(tc):
            return True

        # paragraph must contain runs with no run-properties
        for para in paragraphs:
            runs = list(para.iterchildren(f"{self._W_NS_CLARK}r"))
            for rn in runs:
                item: Run = Run(rn, self.docx_obj)
                if item is not None:
                    fm = MsWordDocumentBackend._get_format_from_run(item)
                    if fm != Formatting():
                        return True

        # All checks passed: plain text only
        return False

    def _get_image_from_relationship(
        self, element: Any, rel_attr: str, image_type: str = "image"
    ) -> bytes | None:
        """Get image data from a relationship ID.

        Args:
            element: The XML element containing the relationship reference
            rel_attr: The attribute name for the relationship ID
            image_type: Type of image for warning messages

        Returns:
            Image data as bytes, or None if not found or external
        """
        image_data: bytes | None = None
        rId = element.get(rel_attr)
        active_part = getattr(self, "current_part", self.docx_obj.part)
        if rId and rId in active_part.rels:
            rel = active_part.rels[rId]
            if rel.is_external:
                warnings.warn(
                    f"Skipping external {image_type} reference: {rel.target_ref}",
                    UserWarning,
                    stacklevel=2,
                )
                return None
            # Access the image part using the relationship ID
            image_part = rel.target_part
            image_data = image_part.blob  # Get the binary image data
        return image_data

    def _add_picture_to_doc(
        self,
        doc: DoclingDocument,
        parent: NodeItem | None,
        pil_image: Image.Image | None,
        is_spacer: bool = False,
    ) -> RefItem:
        """Add a picture element to the document.

        Args:
            doc: The DoclingDocument being constructed
            parent: Parent node for the picture
            pil_image: PIL Image object, or None for placeholder
            is_spacer: Flag indicating whether the parsed image is a layout spacer artifact to be excluded

        Returns:
            Reference to the added picture element
        """
        target_layer = ContentLayer.INVISIBLE if is_spacer else self.content_layer
        if pil_image is not None:
            p = doc.add_picture(
                parent=parent,
                image=ImageRef.from_pil(image=pil_image, dpi=72),
                caption=None,
                content_layer=target_layer,
            )
        else:
            p = doc.add_picture(
                parent=parent,
                caption=None,
                content_layer=target_layer,
            )
        return p.get_ref()

    def _convert_elements_via_docx(
        self, elements: Any | list[Any], element_tag: str | list[str] | None = None
    ) -> Image.Image | None:
        """Convert XML element(s) to image by rendering through DOCX->PDF->PNG.

        This method creates a temporary DOCX with the specified element(s),
        converts it to PDF using LibreOffice, then renders to PNG.

        Args:
            elements: Single XML element or list of elements to convert
            element_tag: Tag name(s) to look for in parent hierarchy when processing a
                single element. If None, elements are added directly without searching
                for parent.

        Returns:
            PIL Image object, or None if conversion failed
        """
        # Initialize converter if needed
        if (
            self.docx_to_pdf_converter is None
            and self.docx_to_pdf_converter_init is False
        ):
            self.docx_to_pdf_converter = get_docx_to_pdf_converter()
            self.docx_to_pdf_converter_init = True

        if self.docx_to_pdf_converter is None:
            return None

        try:
            # Create a temporary document with just these elements
            temp_doc = self.load_msword_file(self.path_or_stream, self.document_hash)
            body = temp_doc._element.body
            for child in list(body):
                body.remove(child)

            # Add elements to empty document
            new_para = temp_doc.add_paragraph()
            new_r = new_para.add_run()

            # Handle list of elements (e.g., multiple DrawingML elements)
            if isinstance(elements, list):
                for elem in elements:
                    new_r._r.append(deepcopy(elem))
            else:
                # Handle single element - find parent if element_tag specified
                if element_tag is not None:
                    if isinstance(element_tag, str):
                        element_tag = [element_tag]

                    parent_elem = elements
                    while parent_elem is not None:
                        tag = etree.QName(parent_elem).localname
                        if tag in element_tag:
                            new_r._r.append(deepcopy(parent_elem))
                            break
                        parent_elem = parent_elem.getparent()

                    if parent_elem is None:
                        return None
                else:
                    # Add element directly
                    new_r._r.append(deepcopy(elements))

            # Convert DOCX->PDF->PNG
            pil_image = get_pil_from_dml_docx(
                temp_doc, converter=self.docx_to_pdf_converter
            )
            return pil_image
        except Exception as e:
            _log.debug(f"Element conversion via DOCX failed: {e}")
            return None

    def _handle_pictures(
        self, drawing_blip: Any, doc: DoclingDocument
    ) -> list[RefItem]:
        """Handle DrawingML pictures with blip elements."""
        elem_ref: list[RefItem] = []
        if drawing_blip:
            level = self._get_level()
            parent: NodeItem | None = (
                self.parents[level - 1]
                if len(drawing_blip) == 1
                else doc.add_group(
                    label=GroupLabel.PICTURE_AREA,
                    parent=self.parents[level - 1],
                    content_layer=self.content_layer,
                )
            )
            for image in drawing_blip:
                image_data = self._get_image_from_relationship(
                    image,
                    "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}embed",
                    "image",
                )
                pil_image: Image.Image | None = None

                if image_data is None:
                    _log.warning("Warning: image cannot be found")
                else:
                    try:
                        image_bytes = BytesIO(image_data)
                        pil_image = Image.open(image_bytes)
                        # Try to ensure the image is usable by converting to PNG
                        # This will fail for WMF/EMF files that PIL can't render
                        test_bytes = BytesIO()
                        pil_image.save(test_bytes, format="PNG")
                        test_bytes.seek(0)
                        pil_image = Image.open(test_bytes)
                    except (UnidentifiedImageError, OSError) as e:
                        _log.warning(f"Warning: image cannot be loaded by Pillow: {e}")
                        pil_image = None

                if pil_image is None and image is not None and image_data is not None:
                    _log.debug(
                        "Direct PIL loading failed, trying DOCX conversion via LibreOffice"
                    )
                    pil_image = self._convert_elements_via_docx(
                        image, ["drawing", "pict"]
                    )

                is_spacer = self._is_invisible_spacer(pil_image)
                elem_ref.append(
                    self._add_picture_to_doc(
                        doc, parent, pil_image, is_spacer=is_spacer
                    )
                )

        return elem_ref

    def _handle_vml_pictures(
        self, vml_imagedatas: Any, doc: DoclingDocument
    ) -> list[RefItem]:
        """Handle VML (Vector Markup Language) images.

        VML images are legacy format images often used for embedded objects like Visio
        drawings, charts, etc. They use v:imagedata elements instead of a:blip
        elements.

        For EMF/WMF formats that PIL cannot render, we use the same approach as
        DrawingML: create a temporary DOCX with the VML element, convert to PDF via
        LibreOffice, then render to PNG.

        Args:
            vml_imagedatas: List of v:imagedata elements
            doc: The DoclingDocument being constructed

        Returns:
            List of RefItem references to the added picture elements
        """
        elem_ref: list[RefItem] = []
        if vml_imagedatas:
            level = self._get_level()
            parent: NodeItem | None = (
                self.parents[level - 1]
                if len(vml_imagedatas) == 1
                else doc.add_group(
                    label=GroupLabel.PICTURE_AREA,
                    parent=self.parents[level - 1],
                    content_layer=self.content_layer,
                )
            )
            for imagedata in vml_imagedatas:
                image_data = self._get_image_from_relationship(
                    imagedata,
                    "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}id",
                    "VML image",
                )
                pil_image: Image.Image | None = None

                if image_data is None:
                    _log.warning("Warning: VML image cannot be found")
                else:
                    try:
                        image_bytes = BytesIO(image_data)
                        pil_image = Image.open(image_bytes)
                        test_bytes = BytesIO()
                        pil_image.save(test_bytes, format="PNG")
                        test_bytes.seek(0)
                        pil_image = Image.open(test_bytes)
                    except (UnidentifiedImageError, OSError, Exception) as e:
                        _log.debug(
                            f"Direct PIL loading failed: {e}, trying DOCX conversion"
                        )
                        pil_image = None

                    if pil_image is None and image_data is not None:
                        pil_image = self._convert_elements_via_docx(
                            imagedata, ["object", "pict"]
                        )
                        if pil_image is None:
                            _log.warning(
                                "Warning: VML image cannot be loaded. "
                                "Install LibreOffice for better VML/EMF/WMF support."
                            )

                is_spacer = self._is_invisible_spacer(pil_image)
                elem_ref.append(
                    self._add_picture_to_doc(
                        doc, parent, pil_image, is_spacer=is_spacer
                    )
                )

        return elem_ref

    def _handle_drawingml(self, doc: DoclingDocument, drawingml_els: Any):
        """Handle DrawingML elements by converting to image via DOCX->PDF->PNG.

        DrawingML elements without blips (e.g., charts, SmartArt) need to be
        rendered through LibreOffice to extract as images.

        Args:
            doc: The DoclingDocument being constructed
            drawingml_els: List of DrawingML elements to process
        """
        level = self._get_level()
        parent = self.parents[level - 1]

        try:
            pil_image = self._convert_elements_via_docx(drawingml_els, element_tag=None)
            if pil_image is None:
                raise UnidentifiedImageError

            is_spacer = self._is_invisible_spacer(pil_image)
            self._add_picture_to_doc(doc, parent, pil_image, is_spacer=is_spacer)

        except (UnidentifiedImageError, OSError):
            _log.warning("Warning: DrawingML image cannot be loaded by Pillow")
            self._add_picture_to_doc(doc, parent, None)

        return

    def _add_header_footer(self, docx_obj: DocxDocument, doc: DoclingDocument) -> None:
        """Add section headers and footers.

        Headers and footers are added in the furniture content and only the text paragraphs
        are parsed. The paragraphs are attached to a single group item for the header or the
        footer. If the document has a section with new header and footer, they will be parsed
        in new group items.

        Args:
            docx_obj: A docx Document object to be parsed.
            doc: A DoclingDocument object to add the header and footer from docx_obj.
        """
        current_layer = self.content_layer
        base_parent = self.parents[0]
        self.content_layer = ContentLayer.FURNITURE

        txbx_xpath = etree.XPath(
            ".//w:txbxContent|.//v:textbox//w:p|.//wps:txbx//w:p|.//a:p//a:t",
            namespaces=self._BLIP_NAMESPACES,
        )
        for sec_idx, section in enumerate(docx_obj.sections):
            if sec_idx > 0 and not section.different_first_page_header_footer:
                continue

            hdr = (
                section.first_page_header
                if section.different_first_page_header_footer
                else section.header
            )
            par = [txt for txt in (par.text.strip() for par in hdr.paragraphs) if txt]
            tables = hdr.tables
            has_blip = self._has_blip(hdr._element)
            has_txbx = len(txbx_xpath(hdr._element)) > 0

            if par or tables or has_blip or has_txbx:
                self.parents[0] = doc.add_group(
                    label=GroupLabel.SECTION,
                    name="page header",
                    content_layer=self.content_layer,
                )
                self.current_part = hdr.part
                self._walk_linear(hdr._element, doc)
                self.current_part = self.docx_obj.part

            ftr = (
                section.first_page_footer
                if section.different_first_page_header_footer
                else section.footer
            )
            par = [txt for txt in (par.text.strip() for par in ftr.paragraphs) if txt]
            tables = ftr.tables
            has_blip = self._has_blip(ftr._element)
            has_txbx = len(txbx_xpath(ftr._element)) > 0

            if par or tables or has_blip or has_txbx:
                self.parents[0] = doc.add_group(
                    label=GroupLabel.SECTION,
                    name="page footer",
                    content_layer=self.content_layer,
                )
                self.current_part = ftr.part
                self._walk_linear(ftr._element, doc)
                self.current_part = self.docx_obj.part

        self.content_layer = current_layer
        self.parents[0] = base_parent

    def _add_comments(self, docx_obj: DocxDocument, doc: DoclingDocument) -> None:
        """Add document comments (reviewer annotations) and link to annotated items.

        Comments are added in the NOTES content layer using the add_comment API.
        Comments are linked to their annotated text items via the comments field
        (FineRef references).

        The comment text format is:
            [author: Name (initials), time: ISO-timestamp]: comment text

        Examples:
            [author: Jane Editor (JE), time: 2026-01-04T05:48:07.000+00:00]: Review this.
            [author: John Doe]: Simple comment without timestamp.

        Args:
            docx_obj: A docx Document object to be parsed.
            doc: A DoclingDocument object to add the comments from docx_obj.
        """
        # Check if document has any comments
        if not hasattr(docx_obj, "comments") or len(docx_obj.comments) == 0:
            return

        # Process each comment and link to target items
        for comment in docx_obj.comments:
            # Build comment text with metadata prefix
            metadata_parts = []
            if comment.author:
                author_str = f"author: {comment.author}"
                if comment.initials:
                    author_str += f" ({comment.initials})"
                metadata_parts.append(author_str)
            if comment.timestamp:
                metadata_parts.append(
                    f"time: {comment.timestamp.isoformat(timespec='milliseconds')}"
                )

            metadata_prefix = ", ".join(metadata_parts)
            comment_text = comment.text.strip() if comment.text else ""

            if metadata_prefix and comment_text:
                full_text = f"[{metadata_prefix}]: {comment_text}"
            elif metadata_prefix:
                full_text = f"[{metadata_prefix}]"
            elif comment_text:
                full_text = comment_text
            else:
                # Skip empty comments
                continue

            # Collect target items for this comment
            targets: list[Any] = []
            comment_id = str(comment.comment_id)

            # Find paragraphs that have this comment
            for para_id, comment_ids in self.paragraph_comment_map.items():
                if comment_id in comment_ids:
                    # Get the text items created from this paragraph
                    if para_id in self.paragraph_to_items:
                        for item_ref in self.paragraph_to_items[para_id]:
                            try:
                                item = item_ref.resolve(doc)
                                if item not in targets:
                                    targets.append(item)
                            except Exception as e:
                                _log.debug(f"Error resolving item ref: {e}")

            # Create a group for this comment in NOTES and add the comment there
            comment_group = doc.add_group(
                label=GroupLabel.COMMENT_SECTION,
                name=f"comment-{comment_id}",
                content_layer=ContentLayer.NOTES,
            )
            # Add the comment text without targets first
            doc.add_comment(
                text=full_text,
                targets=None,
                parent=comment_group,
            )

            # Manually link targets to the comment GROUP (not the text item)
            # This allows multiple comment replies to be grouped together
            if targets:
                group_ref = FineRef(cref=comment_group.self_ref)
                for target in targets:
                    # Only DocItem has a 'comments' field; GroupItem does not,
                    # so skip non-DocItem targets (fixes #2955).
                    if isinstance(target, DocItem):
                        target.comments.append(group_ref)

            _log.debug(
                f"Added comment {comment_id} in group with {len(targets)} linked item(s)"
            )

    def _extract_comment_ranges(self) -> None:
        """Extract comment range markers from the document.

        Parses the DOCX XML to find commentRangeStart and commentRangeEnd markers
        and builds a map of paragraph elements to their associated comment IDs.
        """
        if not self.docx_obj or not hasattr(self.docx_obj, "element"):
            return

        # Parse the document body for comment range markers
        namespaces = {
            "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
        }

        try:
            # Find all paragraphs with comment ranges
            body = self.docx_obj.element.body
            for paragraph in body.findall(".//w:p", namespaces):
                para_id = id(paragraph)

                # Find comment range start markers in this paragraph
                comment_starts = paragraph.findall(".//w:commentRangeStart", namespaces)
                comment_ends = paragraph.findall(".//w:commentRangeEnd", namespaces)

                # Collect comment IDs from both start and end markers
                comment_ids = set()

                for start_marker in comment_starts:
                    comment_id = start_marker.get(
                        "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}id"
                    )
                    if comment_id:
                        comment_ids.add(comment_id)

                for end_marker in comment_ends:
                    comment_id = end_marker.get(
                        "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}id"
                    )
                    if comment_id:
                        comment_ids.add(comment_id)

                # Store the mapping if comments were found
                if comment_ids:
                    self.paragraph_comment_map[para_id] = list(comment_ids)
                    _log.debug(
                        f"Found {len(comment_ids)} comment(s) for paragraph {para_id}"
                    )

        except Exception as e:
            _log.debug(f"Error extracting comment ranges: {e}")

    def _get_comment_ids_for_element(self, element: BaseOxmlElement) -> set[str]:
        """Return the set of comment IDs attached to a paragraph element."""
        namespaces = {
            "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
        }
        comment_ids: set[str] = set()

        for marker in element.findall(".//w:commentRangeStart", namespaces):
            comment_id = marker.get(
                "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}id"
            )
            if comment_id:
                comment_ids.add(comment_id)

        for marker in element.findall(".//w:commentRangeEnd", namespaces):
            comment_id = marker.get(
                "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}id"
            )
            if comment_id:
                comment_ids.add(comment_id)

        # Some documents only contain commentReference nodes without range markers
        for marker in element.findall(".//w:commentReference", namespaces):
            comment_id = marker.get(
                "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}id"
            )
            if comment_id:
                comment_ids.add(comment_id)

        return comment_ids
