super-document-processor 0.1.3__py3-none-any.whl

super_document_processor/utils/pptx_components_extract.py

@@ -0,0 +1,2197 @@
+import zipfile
+import re
+import io
+import struct
+import datetime
+import xml.etree.ElementTree as ET
+from collections import defaultdict, Counter
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+from pptx.enum.dml import MSO_FILL, MSO_COLOR_TYPE
+
+PUA_GLYPH_MAP = {
+    '\uf0b7': '•',
+    '\uf06f': 'o',
+    '\uf0a7': '▪',
+    '\uf0a8': '▫',
+    '\uf0d8': '➢',
+    '\uf0fc': '✔',
+    '\uf075': '◆',
+    '\u25cf': '•',
+}
+
+def sanitize_table_cell(text):
+    if not text:
+        return ""
+    text_str = str(text)
+    clean = text_str.replace('\r\n', '\n').replace('\r', '\n').replace('\x0b', '\n').replace('\v', '\n').replace('\x0c', '\n').replace('\u2028', '\n').replace('\u2029', '\n')
+    lines = [l.strip() for l in clean.split('\n') if l.strip()]
+    return "<br>".join(lines).replace('|', '¦').strip()
+
+def format_table_markdown(table):
+    rows = []
+    for i, row in enumerate(table.rows):
+        cells = [sanitize_table_cell(cell.text) for cell in row.cells]
+        row_line = "| " + " | ".join(cells) + " |"
+        if i == 0:
+            separator = "| " + " | ".join("---" for _ in cells) + " |"
+            rows.append(row_line)
+            rows.append(separator)
+        else:
+            rows.append(row_line)
+    return "\n".join(rows)
+
+def format_run_text(run):
+    txt = getattr(run, 'text', '') or ''
+    if not txt:
+        return ""
+    try:
+        hlink = getattr(run, 'hyperlink', None)
+        address = getattr(hlink, 'address', None) if hlink else None
+        if address and address.strip():
+            addr = address.strip()
+            stripped_txt = txt.strip()
+            if stripped_txt == addr or stripped_txt.startswith(('http://', 'https://', 'mailto:')):
+                return txt
+            return f"[{txt}]({addr})"
+    except Exception:
+        pass
+    return txt
+
+def get_layout_placeholder(shape):
+    if not getattr(shape, 'is_placeholder', False):
+        return None
+    try:
+        slide = shape.part
+        slide_layout = getattr(slide, 'slide_layout', None)
+        if not slide_layout:
+            return None
+        ph = shape.placeholder_format
+        idx = ph.idx
+        for l_ph in slide_layout.placeholders:
+            if l_ph.placeholder_format.idx == idx:
+                return l_ph
+        for l_ph in slide_layout.placeholders:
+            if l_ph.placeholder_format.type == ph.type:
+                return l_ph
+    except Exception:
+        pass
+    return None
+
+def int_to_roman(n):
+    if not isinstance(n, int) or n <= 0:
+        return str(n)
+    val = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1]
+    syb = ["M", "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I"]
+    roman_num = ""
+    i = 0
+    while n > 0 and i < len(val):
+        for _ in range(n // val[i]):
+            roman_num += syb[i]
+            n -= val[i]
+        i += 1
+    return roman_num
+
+def int_to_alpha(n):
+    if not isinstance(n, int) or n <= 0:
+        return str(n)
+    result = ""
+    while n > 0:
+        n, remainder = divmod(n - 1, 26)
+        result = chr(65 + remainder) + result
+    return result
+
+def format_autonum_prefix(num_type, index):
+    if not num_type:
+        return f"{index}."
+    
+    # Roman Upper
+    if num_type in ('romanUcPeriod', 'romanUpperLetter'):
+        return f"{int_to_roman(index)}."
+    elif num_type == 'romanUcParenRight':
+        return f"{int_to_roman(index)})"
+    elif num_type == 'romanUcParenBoth':
+        return f"({int_to_roman(index)})"
+    
+    # Roman Lower
+    elif num_type in ('romanLcPeriod', 'romanLowerLetter'):
+        return f"{int_to_roman(index).lower()}."
+    elif num_type == 'romanLcParenRight':
+        return f"{int_to_roman(index).lower()})"
+    elif num_type == 'romanLcParenBoth':
+        return f"({int_to_roman(index).lower()})"
+    
+    # Alpha Upper
+    elif num_type in ('alphaUcPeriod', 'alphaUpperLetter'):
+        return f"{int_to_alpha(index)}."
+    elif num_type == 'alphaUcParenRight':
+        return f"{int_to_alpha(index)})"
+    elif num_type == 'alphaUcParenBoth':
+        return f"({int_to_alpha(index)})"
+    
+    # Alpha Lower
+    elif num_type in ('alphaLcPeriod', 'alphaLowerLetter'):
+        return f"{int_to_alpha(index).lower()}."
+    elif num_type == 'alphaLcParenRight':
+        return f"{int_to_alpha(index).lower()})"
+    elif num_type == 'alphaLcParenBoth':
+        return f"({int_to_alpha(index).lower()})"
+    
+    # Arabic / numbers
+    elif num_type in ('arabicPeriod', 'arabicPlain', 'arabic1Period'):
+        return f"{index}."
+    elif num_type == 'arabicParenRight':
+        return f"{index})"
+    elif num_type == 'arabicParenBoth':
+        return f"({index})"
+    
+    # Fallback prefixes
+    elif num_type.startswith('romanUc'):
+        return f"{int_to_roman(index)}."
+    elif num_type.startswith('romanLc'):
+        return f"{int_to_roman(index).lower()}."
+    elif num_type.startswith('alphaUc'):
+        return f"{int_to_alpha(index)}."
+    elif num_type.startswith('alphaLc'):
+        return f"{int_to_alpha(index).lower()}."
+    else:
+        return f"{index}."
+
+def resolve_paragraph_bullet_format(shape, p):
+    """
+    Resolves bullet formatting for a paragraph using OpenXML presentation inheritance:
+    1. Paragraph pPr (<a:buNone/> or <a:buChar/> / <a:buAutoNum/> / <a:buFont/>)
+    2. Shape txBody <a:lstStyle>
+    3. Layout placeholder <a:lstStyle> and <a:pPr>
+    4. PresentationML default (body placeholders default to bullets; title/other default to none)
+    Returns tuple: (is_bullet: bool, bu_char: str or None, autonum_type: str or None, start_at: int or None)
+    """
+    level = getattr(p, 'level', 0) or 0
+    lvl_tag = f'{{http://schemas.openxmlformats.org/drawingml/2006/main}}lvl{level+1}pPr'
+    bu_none_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}buNone'
+    bu_char_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}buChar'
+    bu_auto_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}buAutoNum'
+    bu_font_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}buFont'
+    lst_style_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}lstStyle'
+    p_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}p'
+    p_pr_tag = '{http://schemas.openxmlformats.org/drawingml/2006/main}pPr'
+
+    # 1. Paragraph-level pPr
+    try:
+        pPr = p._p.pPr
+        if pPr is not None:
+            if pPr.find(bu_none_tag) is not None:
+                return False, None, None, None
+            buChar_el = pPr.find(bu_char_tag)
+            if buChar_el is not None:
+                return True, buChar_el.attrib.get('char'), None, None
+            buAuto_el = pPr.find(bu_auto_tag)
+            if buAuto_el is not None:
+                num_type = buAuto_el.attrib.get('type')
+                start_at_raw = buAuto_el.attrib.get('startAt')
+                start_at = int(start_at_raw) if start_at_raw and start_at_raw.isdigit() else None
+                return True, None, num_type, start_at
+            if pPr.find(bu_font_tag) is not None:
+                return True, None, None, None
+    except Exception:
+        pass
+
+    # 2. Shape-level lstStyle
+    if shape is not None:
+        try:
+            txBody = shape._element.find('{http://schemas.openxmlformats.org/drawingml/2006/main}txBody') or getattr(shape._element, 'txBody', None)
+            if txBody is not None:
+                lstStyle = txBody.find(lst_style_tag)
+                if lstStyle is not None:
+                    lvl_el = lstStyle.find(lvl_tag)
+                    if lvl_el is not None:
+                        if lvl_el.find(bu_none_tag) is not None:
+                            return False, None, None, None
+                        buChar_el = lvl_el.find(bu_char_tag)
+                        if buChar_el is not None:
+                            return True, buChar_el.attrib.get('char'), None, None
+                        buAuto_el = lvl_el.find(bu_auto_tag)
+                        if buAuto_el is not None:
+                            num_type = buAuto_el.attrib.get('type')
+                            start_at_raw = buAuto_el.attrib.get('startAt')
+                            start_at = int(start_at_raw) if start_at_raw and start_at_raw.isdigit() else None
+                            return True, None, num_type, start_at
+                        if lvl_el.find(bu_font_tag) is not None:
+                            return True, None, None, None
+        except Exception:
+            pass
+
+    # 3. Slide layout placeholder lstStyle and pPr
+    if shape is not None:
+        try:
+            l_ph = get_layout_placeholder(shape)
+            if l_ph is not None:
+                l_txBody = l_ph._element.find('{http://schemas.openxmlformats.org/drawingml/2006/main}txBody') or getattr(l_ph._element, 'txBody', None)
+                if l_txBody is not None:
+                    lstStyle = l_txBody.find(lst_style_tag)
+                    if lstStyle is not None:
+                        lvl_el = lstStyle.find(lvl_tag)
+                        if lvl_el is not None:
+                            if lvl_el.find(bu_none_tag) is not None:
+                                return False, None, None, None
+                            buChar_el = lvl_el.find(bu_char_tag)
+                            if buChar_el is not None:
+                                return True, buChar_el.attrib.get('char'), None, None
+                            buAuto_el = lvl_el.find(bu_auto_tag)
+                            if buAuto_el is not None:
+                                num_type = buAuto_el.attrib.get('type')
+                                start_at_raw = buAuto_el.attrib.get('startAt')
+                                start_at = int(start_at_raw) if start_at_raw and start_at_raw.isdigit() else None
+                                return True, None, num_type, start_at
+                    for lp in l_txBody.findall(p_tag):
+                        lpPr = lp.find(p_pr_tag)
+                        if lpPr is not None:
+                            l_lvl = int(lpPr.attrib.get('lvl', '0'))
+                            if l_lvl == level:
+                                if lpPr.find(bu_none_tag) is not None:
+                                    return False, None, None, None
+                                buChar_el = lpPr.find(bu_char_tag)
+                                if buChar_el is not None:
+                                    return True, buChar_el.attrib.get('char'), None, None
+                                buAuto_el = lpPr.find(bu_auto_tag)
+                                if buAuto_el is not None:
+                                    num_type = buAuto_el.attrib.get('type')
+                                    start_at_raw = buAuto_el.attrib.get('startAt')
+                                    start_at = int(start_at_raw) if start_at_raw and start_at_raw.isdigit() else None
+                                    return True, None, num_type, start_at
+        except Exception:
+            pass
+
+    # 4. Body / content placeholders default to bullet points in PowerPoint
+    if shape is not None and getattr(shape, 'is_placeholder', False):
+        try:
+            ph_type = shape.placeholder_format.type
+            if ph_type in (2, 7, 12, 13) or (ph_type not in (1, 3, 4, 5, 6, 8) and ph_type is not None):
+                return True, None, None, None
+        except Exception:
+            pass
+
+    return (level > 0), None, None, None
+
+def format_paragraph_text(p, shape=None, bullet_info=None):
+    p_text = "".join(format_run_text(run) for run in p.runs).strip()
+    if not p_text:
+        return ""
+
+    level = getattr(p, 'level', 0) or 0
+    indent = "    " * level
+
+    ALL_BULLETS_PATTERN = (
+        r'^(?:([•*➢➤➔➜►▶→⇒»›✓✔★✦✧\u25cf\u25a0\u25a1\u25aa\u25ab\u25cb\u25e6\u25c6\u25c7\u25c8\u2756\u2219'
+        r'\uf0b7\u27a2\uf0d8\uf0fc\uf06f\uf0a7\uf0a8\uf075]|[-–—]\s+|o\s+|\d{1,3}[.)]\s+(?!\d|%|k\b|m\b|cr\b|bn\b|lakh\b|x\b|\$)|'
+        r'\([a-zA-Z0-9]{1,3}\)\s+|\[\d{1,3}\]\s+|'
+        r'(?!(?:e\.g\.|i\.e\.|etc\.|vs\.|w\.r\.t\.)\b)[a-z][.)]\s+|[A-Z][.)]\s+(?=[A-Z0-9])|(?:[ivxIVX]+)[.)]\s+)\s*)(.*)$'
+    )
+    m_bullet = re.match(ALL_BULLETS_PATTERN, p_text)
+
+    if m_bullet:
+        raw_glyph = m_bullet.group(1).strip()
+        rest = m_bullet.group(2).strip()
+        glyph = PUA_GLYPH_MAP.get(raw_glyph, raw_glyph)
+        if level == 0:
+            return f"{glyph} {rest}" if rest else glyph
+        elif level == 1:
+            return f"{indent}o {rest}" if glyph in ('•', '-', '*') else f"{indent}{glyph} {rest}"
+        else:
+            return f"{indent}▪ {rest}" if glyph in ('•', '-', '*') else f"{indent}{glyph} {rest}"
+
+    if bullet_info is not None:
+        is_bullet, bu_char, autonum_type, autonum_idx = bullet_info
+    else:
+        res = resolve_paragraph_bullet_format(shape, p)
+        if len(res) == 4:
+            is_bullet, bu_char, autonum_type, autonum_start = res
+            autonum_idx = autonum_start or 1
+        else:
+            is_bullet, bu_char = res
+            autonum_type, autonum_idx = None, None
+
+    if autonum_type is not None and autonum_idx is not None:
+        prefix = format_autonum_prefix(autonum_type, autonum_idx)
+        return f"{indent}{prefix} {p_text}"
+
+    if is_bullet:
+        if level == 0:
+            bullet_char = PUA_GLYPH_MAP.get(bu_char, '•') if bu_char else '•'
+            return f"{bullet_char} {p_text}"
+        elif level == 1:
+            return f"{indent}o {p_text}"
+        else:
+            return f"{indent}▪ {p_text}"
+
+    return f"{indent}{p_text}"
+
+def is_slide_header_shape(shape, slide_height=6858000, slide_width=12192000):
+    """
+    Determines if a PowerPoint shape represents the slide title / main header using pure structural properties:
+    1. Placeholder type is TITLE or CENTER_TITLE.
+    2. Positioned in the top 14% of the slide and starting in the left-hand portion (<= 35% width).
+    3. Contains 1-2 short lines with no bullet formatting, excluding corner annotations/units.
+    """
+    try:
+        if getattr(shape, 'is_placeholder', False):
+            ph_format = getattr(shape, 'placeholder_format', None)
+            if ph_format is not None:
+                ph_type = getattr(ph_format, 'type', None)
+                if ph_type in (1, 3):  # PP_PLACEHOLDER.TITLE or CENTER_TITLE
+                    return True
+    except Exception:
+        pass
+
+    try:
+        top = getattr(shape, 'top', None)
+        left = getattr(shape, 'left', 0) or 0
+        if top is not None and top <= 0.14 * (slide_height or 6858000):
+            # Exclude right-aligned corner notes and right-side columns
+            if left > 0.35 * (slide_width or 12192000):
+                return False
+            if getattr(shape, 'has_text_frame', False):
+                tf = shape.text_frame
+                paras = [p for p in tf.paragraphs if p.text.strip()]
+                if 1 <= len(paras) <= 2:
+                    p = paras[0]
+                    p_text = p.text.strip()
+                    is_bul, _, auto_type, _ = resolve_paragraph_bullet_format(shape, p)
+                    if not is_bul and auto_type is None and not p_text.startswith(('•', '-', '*', '1.', '2.', '3.', '4.', '5.')):
+                        if len(p_text) <= 140:
+                            return True
+    except Exception:
+        pass
+
+    return False
+
+def extract_text_from_shape(shape, is_header=False):
+    # Ignore invisible shapes (e.g. transparent background with white font color)
+    try:
+        if getattr(shape, 'has_text_frame', False):
+            has_no_fill = False
+            sp_fill = getattr(shape, 'fill', None)
+            if sp_fill is not None and getattr(sp_fill, 'type', None) == MSO_FILL.BACKGROUND:
+                has_no_fill = True
+            if hasattr(shape, '_element'):
+                spPr = shape._element.find('{http://schemas.openxmlformats.org/presentationml/2006/main}spPr')
+                if spPr is not None and spPr.find('{http://schemas.openxmlformats.org/drawingml/2006/main}noFill') is not None:
+                    has_no_fill = True
+            if has_no_fill:
+                runs = [r for p in shape.text_frame.paragraphs for r in p.runs if r.text.strip()]
+                if runs and all(
+                    getattr(r.font, 'color', None) is not None and
+                    getattr(r.font.color, 'type', None) == MSO_COLOR_TYPE.RGB and
+                    str(getattr(r.font.color, 'rgb', '')).upper() == 'FFFFFF'
+                    for r in runs
+                ):
+                    return ""
+    except Exception:
+        pass
+
+    if getattr(shape, 'shape_type', None) == MSO_SHAPE_TYPE.GROUP:
+        sub_texts = []
+        for s in shape.shapes:
+            t = extract_text_from_shape(s)
+            if t:
+                sub_texts.append(t)
+        return "\n".join(sub_texts)
+    elif getattr(shape, 'has_text_frame', False):
+        lines = []
+        autonum_counters = {}
+        prefix_parent = {}
+        prev_level = 0
+        for p in shape.text_frame.paragraphs:
+            p_text_raw = "".join(format_run_text(run) for run in p.runs).strip()
+            if not p_text_raw:
+                continue
+            level = getattr(p, 'level', 0) or 0
+            
+            res = resolve_paragraph_bullet_format(shape, p)
+            if len(res) == 4:
+                is_bullet, bu_char, autonum_type, start_at = res
+            else:
+                is_bullet, bu_char = res
+                autonum_type, start_at = None, None
+            
+            if autonum_type is not None:
+                if level < prev_level:
+                    for k in list(prefix_parent.keys()):
+                        if k >= level:
+                            del prefix_parent[k]
+
+                if start_at is not None:
+                    autonum_counters[level] = start_at
+                else:
+                    autonum_counters[level] = autonum_counters.get(level, 0) + 1
+                curr_val = autonum_counters[level]
+
+                is_arabic = (autonum_type in ('arabicPeriod', 'arabicPlain', 'arabic1Period', 'arabicParenRight', 'arabicParenBoth') or str(autonum_type).startswith('arabic'))
+
+                # When a child list starts with the same bullet number as its immediate parent (e.g. 1 under 1)
+                parent_val = autonum_counters.get(level - 1)
+                if is_arabic and level > 0 and level > prev_level and parent_val is not None:
+                    if curr_val == parent_val:
+                        prefix_parent[level] = parent_val
+
+                if level in prefix_parent:
+                    curr_idx = f"{prefix_parent[level]}.{curr_val}"
+                else:
+                    curr_idx = curr_val
+                prev_level = level
+            else:
+                curr_idx = None
+            
+            formatted = format_paragraph_text(p, shape=shape, bullet_info=(is_bullet, bu_char, autonum_type, curr_idx))
+            if formatted:
+                lines.append(formatted)
+        if not lines:
+            return ""
+        if is_header:
+            header_lines = []
+            for i, line in enumerate(lines):
+                cleaned = line.strip()
+                if i == 0 and not cleaned.startswith('#'):
+                    header_lines.append(f"## {cleaned}")
+                else:
+                    header_lines.append(line)
+            return "\n".join(header_lines)
+        return "\n".join(lines)
+    return ""
+
+def get_pptx_card_boxes(slide):
+    """
+    Extracts visual container/card boxes from PPTX shapes.
+    Identifies shapes that act as visual cards (e.g. rounded rectangles, callouts, cards enclosing text).
+    """
+    raw_boxes = []
+    slide_w = getattr(slide, 'width', 12192000) or 12192000
+    slide_h = getattr(slide, 'height', 6858000) or 6858000
+
+    for s in slide.shapes:
+        try:
+            top = getattr(s, 'top', None)
+            left = getattr(s, 'left', None)
+            width = getattr(s, 'width', 0) or 0
+            height = getattr(s, 'height', 0) or 0
+            if top is None or left is None or width < 800000 or height < 400000:
+                continue
+
+            if width >= slide_w * 0.92 and height >= slide_h * 0.92:
+                continue
+
+            is_container = False
+            if s.shape_type == MSO_SHAPE_TYPE.GROUP:
+                is_container = True
+            elif s.shape_type == MSO_SHAPE_TYPE.AUTO_SHAPE:
+                is_container = True
+
+            if is_container:
+                box = {
+                    'left': int(left),
+                    'top': int(top),
+                    'right': int(left) + int(width),
+                    'bottom': int(top) + int(height),
+                    'width': int(width),
+                    'height': int(height)
+                }
+                raw_boxes.append(box)
+        except Exception:
+            continue
+
+    unique_boxes = []
+    for b in raw_boxes:
+        if not any(
+            abs(ub['left'] - b['left']) < 50000 and
+            abs(ub['top'] - b['top']) < 50000 and
+            abs(ub['right'] - b['right']) < 50000 and
+            abs(ub['bottom'] - b['bottom']) < 50000
+            for ub in unique_boxes
+        ):
+            unique_boxes.append(b)
+
+    clean_boxes = []
+    for b in unique_boxes:
+        children = [
+            other for other in unique_boxes
+            if other != b and
+            b['left'] <= other['left'] + 50000 and
+            b['top'] <= other['top'] + 50000 and
+            b['right'] >= other['right'] - 50000 and
+            b['bottom'] >= other['bottom'] - 50000 and
+            (other['width'] * other['height']) < 0.8 * (b['width'] * b['height'])
+        ]
+        if len(children) >= 2:
+            continue
+        clean_boxes.append(b)
+
+    return clean_boxes
+
+def apply_pptx_box_decorations(ordered_elements, card_boxes):
+    """
+    Identifies elements enclosed inside PowerPoint card boxes / callouts and frames them with '---'
+    without creating consecutive duplicate separators.
+    """
+    if not card_boxes:
+        clean = []
+        for e in ordered_elements:
+            t = e if isinstance(e, str) else e.get('text', '')
+            if t.strip() == '---':
+                if clean and (clean[-1] if isinstance(clean[-1], str) else clean[-1].get('text', '')).strip() == '---':
+                    continue
+            clean.append(t if isinstance(e, dict) else e)
+        return clean
+
+    decorated = []
+    current_box_elements = []
+    active_box = None
+
+    for el in ordered_elements:
+        matching_box = None
+        if isinstance(el, dict) and el.get('type') != 'header' and 'left' in el and 'top' in el:
+            el_cx = el['left'] + el.get('width', 0) / 2.0
+            el_cy = el['top'] + el.get('height', 0) / 2.0
+            for box in card_boxes:
+                if (box['left'] - 50000 <= el_cx <= box['right'] + 50000 and
+                    box['top'] - 50000 <= el_cy <= box['bottom'] + 50000):
+                    matching_box = box
+                    break
+
+        el_text = el['text'] if isinstance(el, dict) else str(el)
+        if not el_text.strip():
+            continue
+
+        if matching_box != active_box:
+            if active_box is not None and current_box_elements:
+                decorated.append('---')
+                decorated.extend(current_box_elements)
+                decorated.append('---')
+                current_box_elements = []
+            active_box = matching_box
+
+        if active_box is not None:
+            current_box_elements.append(el_text)
+        else:
+            decorated.append(el_text)
+
+    if active_box is not None and current_box_elements:
+        decorated.append('---')
+        decorated.extend(current_box_elements)
+        decorated.append('---')
+
+    clean_decorated = []
+    for text in decorated:
+        if text.strip() == '---':
+            if clean_decorated and clean_decorated[-1].strip() == '---':
+                continue
+        clean_decorated.append(text)
+
+    return clean_decorated
+
+def get_all_shapes_flattened(shapes):
+    """
+    Recursively unpacks Group shapes into their individual shapes so every text frame,
+    table, or shape is individually placed in reading order and extracted.
+    Computes absolute slide coordinates for children in group coordinate transforms.
+    """
+    flat = []
+    for s in shapes:
+        if getattr(s, 'shape_type', None) == MSO_SHAPE_TYPE.GROUP or hasattr(s, 'shapes'):
+            try:
+                grp_spPr = s._element.xpath('./p:grpSpPr') if hasattr(s, '_element') else []
+                off_x, off_y = 0, 0
+                chOff_x, chOff_y = 0, 0
+                scale_x, scale_y = 1.0, 1.0
+                if grp_spPr:
+                    xfrm = grp_spPr[0].xpath('./a:xfrm')
+                    if xfrm:
+                        off = xfrm[0].xpath('./a:off')
+                        chOff = xfrm[0].xpath('./a:chOff')
+                        ext = xfrm[0].xpath('./a:ext')
+                        chExt = xfrm[0].xpath('./a:chExt')
+                        if off:
+                            off_x = int(off[0].get('x', 0))
+                            off_y = int(off[0].get('y', 0))
+                        if chOff:
+                            chOff_x = int(chOff[0].get('x', 0))
+                            chOff_y = int(chOff[0].get('y', 0))
+                        if ext and chExt:
+                            cx = int(ext[0].get('cx', 1))
+                            cy = int(ext[0].get('cy', 1))
+                            ch_cx = int(chExt[0].get('cx', 1))
+                            ch_cy = int(chExt[0].get('cy', 1))
+                            scale_x = cx / ch_cx if ch_cx else 1.0
+                            scale_y = cy / ch_cy if ch_cy else 1.0
+
+                for cs in s.shapes:
+                    if getattr(cs, 'shape_type', None) == MSO_SHAPE_TYPE.GROUP or hasattr(cs, 'shapes'):
+                        flat.extend(get_all_shapes_flattened([cs]))
+                    else:
+                        try:
+                            orig_l = cs.left
+                            orig_t = cs.top
+                            abs_l = off_x + int((orig_l - chOff_x) * scale_x)
+                            abs_t = off_y + int((orig_t - chOff_y) * scale_y)
+                            cs.left = abs_l
+                            cs.top = abs_t
+                        except Exception:
+                            pass
+                        flat.append(cs)
+            except Exception:
+                flat.append(s)
+        else:
+            flat.append(s)
+    return flat
+
+def get_spatial_shape_reading_order(shapes, slide_h=6858000, slide_w=12192000):
+    """
+    Sorts PowerPoint slide shapes into natural 2D reading order (Recursive XY-Cut):
+    1. Header/Title at the top (peeled first).
+    2. Spanning footer at the bottom.
+    3. Distinct vertical columns (left-to-right) with top-to-bottom shape order.
+    """
+    all_shapes = get_all_shapes_flattened(shapes)
+    valid_shapes = []
+    unpositioned = []
+
+    for s in all_shapes:
+        try:
+            top = getattr(s, 'top', None)
+            left = getattr(s, 'left', None)
+            width = getattr(s, 'width', 0) or 0
+            height = getattr(s, 'height', 0) or 0
+            if top is not None and left is not None:
+                # Filter out purely decorative background shapes with no readable content
+                has_content = False
+                if getattr(s, 'has_table', False) or getattr(s, 'shape_type', None) == MSO_SHAPE_TYPE.TABLE:
+                    has_content = True
+                elif getattr(s, 'has_text_frame', False):
+                    if s.text_frame.text.strip():
+                        has_content = True
+                elif getattr(s, 'shape_type', None) == MSO_SHAPE_TYPE.GROUP or hasattr(s, 'shapes'):
+                    group_text = extract_text_from_shape(s)
+                    if group_text.strip():
+                        has_content = True
+                elif hasattr(s, '_element') and s._element is not None:
+                    # Check for embedded media / blip (EMF/WMF vector drawings, charts, OLE tables)
+                    if len(s._element.xpath('.//a:blip')) > 0:
+                        has_content = True
+
+                if not has_content:
+                    continue
+
+                is_hdr = is_slide_header_shape(s, slide_h, slide_w)
+                effective_w = width
+                if is_hdr and getattr(s, 'has_text_frame', False):
+                    t_len = len(s.text_frame.text.strip())
+                    if t_len < 40 and width > 0.5 * (slide_w or 12192000):
+                        effective_w = min(width, int((slide_w or 12192000) * 0.4))
+
+                valid_shapes.append({
+                    'shape': s,
+                    'left': int(left),
+                    'top': int(top),
+                    'width': int(width),
+                    'height': int(height),
+                    'right': int(left) + int(width),
+                    'bottom': int(top) + int(height),
+                    'is_header': is_hdr
+                })
+            else:
+                unpositioned.append(s)
+        except Exception:
+            unpositioned.append(s)
+
+    if not valid_shapes:
+        return list(all_shapes)
+
+    def order_shape_items(items, min_gutter_x=100000, min_band_gap_y=120000):
+        if len(items) <= 1:
+            return items
+
+        min_x = min(item['left'] for item in items)
+        max_x = max(item['right'] for item in items)
+        total_w = max_x - min_x
+
+        sorted_by_y = sorted(items, key=lambda it: (it['top'], it['left']))
+
+        # 1a. Header at top (peeled first if slide title or strictly above everything)
+        slide_hdrs = [
+            it for it in items
+            if it.get('is_header')
+            and it['left'] <= 0.35 * (slide_w or 12192000)
+            and it['top'] <= 0.20 * (slide_h or 6858000)
+            and (
+                (getattr(it['shape'], 'is_placeholder', False) and getattr(it['shape'], 'placeholder_format', None) and getattr(it['shape'].placeholder_format, 'type', None) in (1, 3))
+                or len(items) == len(valid_shapes)
+            )
+        ]
+        if slide_hdrs:
+            hdr = min(slide_hdrs, key=lambda it: (it['top'], it['left']))
+            rest = [it for it in items if it is not hdr]
+            return [hdr] + order_shape_items(rest, min_gutter_x, min_band_gap_y)
+
+        top_item = sorted_by_y[0]
+        if len(sorted_by_y) > 1:
+            other_min_top = min(it['top'] for it in sorted_by_y[1:])
+            if top_item.get('is_header') and (top_item['left'] <= 0.35 * (slide_w or 12192000)):
+                rest = [it for it in items if it is not top_item]
+                return [top_item] + order_shape_items(rest, min_gutter_x, min_band_gap_y)
+            elif top_item['bottom'] <= other_min_top:
+                rest = [it for it in items if it is not top_item]
+                return [top_item] + order_shape_items(rest, min_gutter_x, min_band_gap_y)
+
+        # 1b. Spanning Footer at bottom
+        bottom_item = sorted_by_y[-1]
+        if bottom_item['width'] >= 0.35 * total_w and len(sorted_by_y) > 1:
+            other_max_bottom = max(it['bottom'] for it in sorted_by_y[:-1])
+            y_gap = bottom_item['top'] - other_max_bottom
+            if y_gap >= min_band_gap_y * 0.5:
+                rest = [it for it in items if it is not bottom_item]
+                return order_shape_items(rest, min_gutter_x, min_band_gap_y) + [bottom_item]
+
+        # 2. Check for horizontal band split (rows) FIRST
+        y_cuts = []
+        cur_bottom = sorted_by_y[0]['bottom']
+        cur_group = [sorted_by_y[0]]
+
+        for it in sorted_by_y[1:]:
+            if it['top'] >= cur_bottom + min_band_gap_y:
+                y_cuts.append(cur_group)
+                cur_group = [it]
+                cur_bottom = it['bottom']
+            else:
+                cur_group.append(it)
+                cur_bottom = max(cur_bottom, it['bottom'])
+        if cur_group:
+            y_cuts.append(cur_group)
+
+        if len(y_cuts) > 1:
+            result = []
+            for group in y_cuts:
+                result.extend(order_shape_items(group, min_gutter_x, min_band_gap_y))
+            return result
+
+        # 3. Check for vertical column split (gutters)
+        sorted_by_x = sorted(items, key=lambda it: (it['left'], it['top']))
+        columns = []
+        cur_col = [sorted_by_x[0]]
+        cur_right = sorted_by_x[0]['right']
+
+        for it in sorted_by_x[1:]:
+            if it['left'] >= cur_right + min_gutter_x:
+                columns.append(cur_col)
+                cur_col = [it]
+                cur_right = it['right']
+            else:
+                cur_col.append(it)
+                cur_right = max(cur_right, it['right'])
+        if cur_col:
+            columns.append(cur_col)
+
+        if len(columns) > 1:
+            ordered = []
+            for col in columns:
+                ordered.extend(order_shape_items(col, min_gutter_x, min_band_gap_y))
+            return ordered
+
+        # 3b. Check for distinct left-anchor column clustering
+        # (Handles staircase/chevron diagrams where wide arrow banners overlap horizontally)
+        distinct_lefts = sorted(set(it['left'] for it in items))
+        if len(distinct_lefts) >= 2 and total_w > min_gutter_x * 4:
+            left_clusters = []
+            cur_group = [distinct_lefts[0]]
+            for l in distinct_lefts[1:]:
+                if l - cur_group[-1] <= min_gutter_x * 0.75:
+                    cur_group.append(l)
+                else:
+                    left_clusters.append((min(cur_group), max(cur_group)))
+                    cur_group = [l]
+            if cur_group:
+                left_clusters.append((min(cur_group), max(cur_group)))
+
+            if len(left_clusters) >= 2:
+                clustered_cols = [[] for _ in left_clusters]
+                for it in items:
+                    best_idx = 0
+                    min_dist = float('inf')
+                    for ci, (c_min, c_max) in enumerate(left_clusters):
+                        dist = abs(it['left'] - (c_min + c_max) / 2.0)
+                        if dist < min_dist:
+                            min_dist = dist
+                            best_idx = ci
+                    clustered_cols[best_idx].append(it)
+
+                if all(len(c) > 0 for c in clustered_cols):
+                    # Verify clusters are genuinely separate columns rather than nested/overlapping elements
+                    col_spans = [(min(it['left'] for it in c), max(it['right'] for it in c)) for c in clustered_cols]
+                    overlapping = any(
+                        not (col_spans[i][1] <= col_spans[j][0] + min_gutter_x or col_spans[j][1] <= col_spans[i][0] + min_gutter_x)
+                        for i in range(len(col_spans))
+                        for j in range(i + 1, len(col_spans))
+                    )
+                    if not overlapping:
+                        ordered = []
+                        for col in clustered_cols:
+                            ordered.extend(order_shape_items(col, min_gutter_x, min_band_gap_y))
+                        return ordered
+
+        return sorted(items, key=lambda it: (it['top'], it['left']))
+
+    ordered_items = order_shape_items(valid_shapes)
+    return [it['shape'] for it in ordered_items] + unpositioned
+
+def extract_smartart_texts_per_slide(filename, page_num):
+    try:
+        with zipfile.ZipFile(filename, 'r') as pptx:
+            slide_diagram_map = defaultdict(list)
+
+            for file in pptx.namelist():
+                if file.startswith('ppt/slides/_rels/') and file.endswith('.rels'):
+                    with pptx.open(file) as rels_file:
+                        rels_tree = ET.parse(rels_file)
+                        rels_root = rels_tree.getroot()
+                        for rel in rels_root.findall('{http://schemas.openxmlformats.org/package/2006/relationships}Relationship'):
+                            target = rel.attrib.get('Target', '')
+                            if 'diagrams/' in target:
+                                slide_num = int(file.split('/')[-1].replace('slide', '').replace('.xml.rels', ''))
+                                diagram_path = 'ppt/' + target.replace('../', '')
+                                if diagram_path in pptx.namelist() and diagram_path not in slide_diagram_map[slide_num]:
+                                    slide_diagram_map[slide_num].append(diagram_path)
+
+            namespaces = {
+                'dgm': 'http://schemas.openxmlformats.org/drawingml/2006/diagram',
+                'a': 'http://schemas.openxmlformats.org/drawingml/2006/main'
+            }
+
+            slide_texts = {}
+
+            for slide_num, diagram_files in slide_diagram_map.items():
+                if page_num is not None and slide_num != page_num:
+                    continue
+
+                texts_in_slide = []
+                data_files = [f for f in diagram_files if 'diagrams/data' in f]
+                other_files = [f for f in diagram_files if 'diagrams/data' not in f]
+
+                # 1. Attempt structured hierarchical extraction from SmartArt data model
+                for df in data_files:
+                    if df not in pptx.namelist():
+                        continue
+                    try:
+                        with pptx.open(df) as f:
+                            root = ET.parse(f).getroot()
+
+                        pts = {}
+                        for pt in root.findall('.//dgm:pt', namespaces):
+                            mid = pt.attrib.get('modelId')
+                            p_texts = [''.join(t.text for t in p.findall('.//a:t', namespaces) if t.text).strip() for p in pt.findall('.//a:p', namespaces)]
+                            txt = ' '.join(t for t in p_texts if t).strip()
+                            if txt:
+                                pts[mid] = txt
+
+                        cxns = defaultdict(list)
+                        for cxn in root.findall('.//dgm:cxn', namespaces):
+                            c_type = cxn.attrib.get('type')
+                            if c_type is None or c_type == 'None':
+                                src = cxn.attrib.get('srcId')
+                                dest = cxn.attrib.get('destId')
+                                src_ord = int(cxn.attrib.get('srcOrd', 0))
+                                cxns[src].append((src_ord, dest))
+
+                        incoming = {d for dsts in cxns.values() for _, d in dsts}
+                        roots = [mid for mid in cxns if mid not in incoming]
+                        has_sub = any(cxns.get(ch) for r in roots for _, ch in cxns.get(r, []))
+
+                        if has_sub:
+                            for r in roots:
+                                for _, top_id in sorted(cxns.get(r, [])):
+                                    top_text = pts.get(top_id, '')
+                                    children = [pts.get(ch_id, '') for _, ch_id in sorted(cxns.get(top_id, [])) if pts.get(ch_id, '')]
+                                    if top_text and children:
+                                        texts_in_slide.append(f"### {top_text}")
+                                        for ch in children:
+                                            texts_in_slide.append(f"• {ch}")
+                                    elif top_text:
+                                        texts_in_slide.append(f"• {top_text}")
+                        else:
+                            for r in roots:
+                                for _, ch_id in sorted(cxns.get(r, [])):
+                                    txt = pts.get(ch_id, '')
+                                    if txt and txt not in texts_in_slide:
+                                        texts_in_slide.append(txt)
+                    except Exception:
+                        pass
+
+                # 2. Fallback to drawing files or legacy extraction if no structured text found
+                if not texts_in_slide:
+                    for diagram_file in other_files or diagram_files:
+                        if diagram_file in pptx.namelist():
+                            with pptx.open(diagram_file) as f:
+                                tree = ET.parse(f)
+                                root = tree.getroot()
+
+                                for paragraph in root.findall('.//a:p', namespaces):
+                                    text_parts = paragraph.findall('.//a:t', namespaces)
+                                    combined_text = ''.join(t.text for t in text_parts if t.text)
+                                    cleaned_text = combined_text.replace('\n', ' ').strip()
+                                    if cleaned_text and cleaned_text not in texts_in_slide:
+                                        texts_in_slide.append(cleaned_text)
+
+                                for dgm_t in root.findall('.//dgm:t', namespaces):
+                                    if dgm_t.text and dgm_t.text.strip():
+                                        cleaned_text = dgm_t.text.replace('\n', ' ').strip()
+                                        if cleaned_text and cleaned_text not in texts_in_slide:
+                                            texts_in_slide.append(cleaned_text)
+
+                slide_texts[slide_num] = texts_in_slide
+
+            return slide_texts
+    except Exception:
+        return {}
+
+def extract_ole_streams(raw_bytes):
+    """
+    Parses a Microsoft Compound File Binary (CFBF / OLE2) and extracts all streams by name.
+    """
+    import struct
+    if len(raw_bytes) < 512 or raw_bytes[:8] != b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1":
+        return {}
+
+    try:
+        sector_shift = struct.unpack_from("<H", raw_bytes, 30)[0]
+        sector_size = 1 << sector_shift
+        mini_sector_shift = struct.unpack_from("<H", raw_bytes, 32)[0]
+        mini_sector_size = 1 << mini_sector_shift
+
+        c_fat = struct.unpack_from("<I", raw_bytes, 44)[0]
+        first_dir_sect = struct.unpack_from("<I", raw_bytes, 48)[0]
+        first_mini_fat = struct.unpack_from("<I", raw_bytes, 60)[0]
+        c_mini_fat = struct.unpack_from("<I", raw_bytes, 64)[0]
+
+        difat = list(struct.unpack_from("<109I", raw_bytes, 76))
+        fat = []
+        for fat_sect in difat[:c_fat]:
+            if fat_sect in (0xFFFFFFFE, 0xFFFFFFFF):
+                break
+            offset = (fat_sect + 1) * sector_size
+            fat.extend(struct.unpack_from(f"<{sector_size // 4}I", raw_bytes, offset))
+
+        def get_chain(start_sect):
+            chain = []
+            curr = start_sect
+            while curr < len(fat) and curr < 0xFFFFFFFC:
+                chain.append(curr)
+                curr = fat[curr]
+            return chain
+
+        dir_chain = get_chain(first_dir_sect)
+        dir_bytes = b"".join(raw_bytes[(s + 1) * sector_size:(s + 2) * sector_size] for s in dir_chain)
+
+        entries = []
+        for i in range(0, len(dir_bytes), 128):
+            entry_raw = dir_bytes[i:i + 128]
+            if len(entry_raw) < 128:
+                break
+            name_len = struct.unpack_from("<H", entry_raw, 64)[0]
+            name = entry_raw[:name_len].decode("utf-16le", errors="ignore").rstrip("\x00")
+            entry_type = entry_raw[66]
+            start_sect = struct.unpack_from("<I", entry_raw, 116)[0]
+            stream_size = struct.unpack_from("<Q", entry_raw, 120)[0]
+            if entry_type in (2, 5) and name:
+                entries.append((name, entry_type, start_sect, stream_size))
+
+        root_entry = next((e for e in entries if e[1] == 5), None)
+        mini_stream = b""
+        if root_entry:
+            mini_chain = get_chain(root_entry[2])
+            mini_stream = b"".join(raw_bytes[(s + 1) * sector_size:(s + 2) * sector_size] for s in mini_chain)[:root_entry[3]]
+
+        mini_fat = []
+        if first_mini_fat < 0xFFFFFFFC:
+            mf_chain = get_chain(first_mini_fat)
+            for s in mf_chain[:c_mini_fat]:
+                offset = (s + 1) * sector_size
+                mini_fat.extend(struct.unpack_from(f"<{sector_size // 4}I", raw_bytes, offset))
+
+        def get_mini_chain(start_sect):
+            chain = []
+            curr = start_sect
+            while curr < len(mini_fat) and curr < 0xFFFFFFFC:
+                chain.append(curr)
+                curr = mini_fat[curr]
+            return chain
+
+        streams = {}
+        for name, entry_type, start_sect, size in entries:
+            if entry_type == 2 and size > 0:
+                if size < 4096 and mini_stream and mini_fat:
+                    chain = get_mini_chain(start_sect)
+                    stream_data = b"".join(mini_stream[s * mini_sector_size:(s + 1) * mini_sector_size] for s in chain)[:size]
+                else:
+                    chain = get_chain(start_sect)
+                    stream_data = b"".join(raw_bytes[(s + 1) * sector_size:(s + 2) * sector_size] for s in chain)[:size]
+                streams[name] = stream_data
+
+        return streams
+    except Exception:
+        return {}
+
+def decode_biff_rk(rk_int):
+    """Decodes a BIFF8 RK number to float."""
+    import struct
+    if rk_int & 0x02:
+        val = float(rk_int >> 2)
+    else:
+        val = struct.unpack("<d", struct.pack("<I", 0) + struct.pack("<I", rk_int & 0xFFFFFFFC))[0]
+    if rk_int & 0x01:
+        val /= 100.0
+    return val
+
+def parse_biff8_workbook(wb_bytes):
+    """
+    Parses a BIFF8 (Excel 97-2003) Workbook stream to extract shared strings and cell values into a Markdown table.
+    """
+    import struct
+    pos = 0
+    sst = []
+    rows_dict = defaultdict(dict)
+    max_col = 0
+
+    try:
+        while pos + 4 <= len(wb_bytes):
+            rec_type, rec_len = struct.unpack_from("<HH", wb_bytes, pos)
+            pos += 4
+            rec_data = wb_bytes[pos:pos + rec_len]
+            pos += rec_len
+
+            # SST (Shared String Table) record: 0x00FC
+            if rec_type == 0x00FC and len(rec_data) >= 8:
+                c_strings = struct.unpack_from("<I", rec_data, 4)[0]
+                str_pos = 8
+                for _ in range(c_strings):
+                    if str_pos + 3 > len(rec_data):
+                        break
+                    c_chars = struct.unpack_from("<H", rec_data, str_pos)[0]
+                    flags = rec_data[str_pos + 2]
+                    is_unicode = bool(flags & 0x01)
+                    str_pos += 3
+                    if flags & 0x08:
+                        str_pos += 2
+                    if flags & 0x04:
+                        str_pos += 4
+                    char_byte_len = c_chars * 2 if is_unicode else c_chars
+                    if str_pos + char_byte_len > len(rec_data):
+                        break
+                    s_bytes = rec_data[str_pos:str_pos + char_byte_len]
+                    str_pos += char_byte_len
+                    encoding = "utf-16le" if is_unicode else "latin-1"
+                    sst.append(s_bytes.decode(encoding, errors="ignore"))
+
+            # LABELSST (0x00FD)
+            elif rec_type == 0x00FD and len(rec_data) >= 10:
+                row, col, _, sst_idx = struct.unpack_from("<HHHI", rec_data, 0)
+                if sst_idx < len(sst):
+                    rows_dict[row][col] = sst[sst_idx]
+                    max_col = max(max_col, col)
+
+            # LABEL (0x0204)
+            elif rec_type == 0x0204 and len(rec_data) >= 8:
+                row, col, _, str_len = struct.unpack_from("<HHHH", rec_data, 0)
+                str_bytes = rec_data[8:8 + str_len]
+                rows_dict[row][col] = str_bytes.decode("latin-1", errors="ignore")
+                max_col = max(max_col, col)
+
+            # NUMBER (0x0203)
+            elif rec_type == 0x0203 and len(rec_data) >= 14:
+                row, col, _ = struct.unpack_from("<HHH", rec_data, 0)
+                num_val = struct.unpack_from("<d", rec_data, 6)[0]
+                val_str = f"{num_val:.3f}".rstrip('0').rstrip('.') if not num_val.is_integer() else str(int(num_val))
+                rows_dict[row][col] = val_str
+                max_col = max(max_col, col)
+
+            # RK (0x027E)
+            elif rec_type == 0x027E and len(rec_data) >= 10:
+                row, col, _, rk_raw = struct.unpack_from("<HHHI", rec_data, 0)
+                num_val = decode_biff_rk(rk_raw)
+                val_str = f"{num_val:.3f}".rstrip('0').rstrip('.') if not num_val.is_integer() else str(int(num_val))
+                rows_dict[row][col] = val_str
+                max_col = max(max_col, col)
+
+            # MULRK (0x00BD)
+            elif rec_type == 0x00BD and len(rec_data) >= 6:
+                row, first_col = struct.unpack_from("<HH", rec_data, 0)
+                last_col = struct.unpack_from("<H", rec_data, len(rec_data) - 2)[0]
+                rk_pos = 4
+                for col in range(first_col, last_col + 1):
+                    if rk_pos + 6 > len(rec_data):
+                        break
+                    _, rk_raw = struct.unpack_from("<HI", rec_data, rk_pos)
+                    rk_pos += 6
+                    num_val = decode_biff_rk(rk_raw)
+                    val_str = f"{num_val:.3f}".rstrip('0').rstrip('.') if not num_val.is_integer() else str(int(num_val))
+                    rows_dict[row][col] = val_str
+                    max_col = max(max_col, col)
+
+        if not rows_dict:
+            return ""
+
+        sorted_rows = sorted(rows_dict.keys())
+        num_cols = max_col + 1
+        grid = []
+        for r in sorted_rows:
+            row_cells = [rows_dict[r].get(c, "") for c in range(num_cols)]
+            if any(str(cell).strip() for cell in row_cells):
+                grid.append(row_cells)
+
+        if not grid:
+            return ""
+
+        header = "| " + " | ".join(sanitize_table_cell(str(c)) for c in grid[0]) + " |"
+        sep = "| " + " | ".join("---" for _ in range(num_cols)) + " |"
+        table_lines = [header, sep]
+        for row in grid[1:]:
+            table_lines.append("| " + " | ".join(sanitize_table_cell(str(c)) for c in row) + " |")
+
+        return "\n".join(table_lines)
+    except Exception:
+        return ""
+
+def _col_ref_to_index(cell_ref):
+    """Converts an Excel column reference like 'A1' or 'BC12' to a 0-based column index."""
+    col_str = ''.join(c for c in cell_ref if c.isalpha()).upper()
+    idx = 0
+    for c in col_str:
+        idx = idx * 26 + (ord(c) - ord('A') + 1)
+    return max(0, idx - 1)
+
+def _parse_xlsx_stream(zip_stream):
+    """Parses an open XML zip stream into Markdown tables."""
+    tables = []
+    with zipfile.ZipFile(zip_stream, 'r') as xlsx:
+        shared_strings = []
+        if 'xl/sharedStrings.xml' in xlsx.namelist():
+            sst_tree = ET.parse(xlsx.open('xl/sharedStrings.xml'))
+            ns_ss = {'s': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
+            for si in sst_tree.getroot().findall('.//s:si', ns_ss):
+                t_parts = [t.text for t in si.findall('.//s:t', ns_ss) if t.text]
+                shared_strings.append("".join(t_parts))
+
+        sheet_files = sorted([f for f in xlsx.namelist() if f.startswith('xl/worksheets/sheet') and f.endswith('.xml')])
+        for sheet_file in sheet_files:
+            sheet_tree = ET.parse(xlsx.open(sheet_file))
+            ns_s = {'s': 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'}
+            rows_dict = defaultdict(dict)
+            max_col_idx = 0
+
+            for row_el in sheet_tree.getroot().findall('.//s:sheetData/s:row', ns_s):
+                row_idx = int(row_el.attrib.get('r', len(rows_dict) + 1))
+                for c in row_el.findall('s:c', ns_s):
+                    cell_ref = c.attrib.get('r', '')
+                    col_idx = _col_ref_to_index(cell_ref) if cell_ref else len(rows_dict[row_idx])
+                    max_col_idx = max(max_col_idx, col_idx)
+
+                    c_type = c.attrib.get('t', '')
+                    val = ""
+                    if c_type == 's':
+                        v_el = c.find('s:v', ns_s)
+                        if v_el is not None and v_el.text and v_el.text.strip().isdigit():
+                            s_idx = int(v_el.text.strip())
+                            if s_idx < len(shared_strings):
+                                val = shared_strings[s_idx]
+                    elif c_type == 'inlineStr':
+                        is_t = c.find('.//s:t', ns_s)
+                        if is_t is not None and is_t.text:
+                            val = is_t.text
+                    else:
+                        v_el = c.find('s:v', ns_s)
+                        if v_el is not None and v_el.text:
+                            val = v_el.text
+
+                    if val:
+                        rows_dict[row_idx][col_idx] = val
+
+            if rows_dict:
+                sorted_row_indices = sorted(rows_dict.keys())
+                grid = []
+                num_cols = max_col_idx + 1
+
+                for r_i in sorted_row_indices:
+                    row_data = [rows_dict[r_i].get(c_i, "") for c_i in range(num_cols)]
+                    if any(str(c).strip() for c in row_data):
+                        grid.append(row_data)
+
+                if grid:
+                    header = "| " + " | ".join(sanitize_table_cell(c) for c in grid[0]) + " |"
+                    sep = "| " + " | ".join("---" for _ in range(num_cols)) + " |"
+                    table_lines = [header, sep]
+                    for row in grid[1:]:
+                        table_lines.append("| " + " | ".join(sanitize_table_cell(c) for c in row) + " |")
+                    tables.append("\n".join(table_lines))
+    return tables
+
+def extract_embedded_excel_tables(pptx_file, target_slide=None):
+    """
+    Extracts tables from embedded Excel worksheets (.xlsx, .xlsm, .bin OLE objects) associated with slides.
+    """
+    slide_excel_map = defaultdict(list)
+    try:
+        with zipfile.ZipFile(pptx_file, 'r') as pptx:
+            for file in pptx.namelist():
+                if file.startswith('ppt/slides/_rels/slide') and file.endswith('.rels'):
+                    slide_num = int(file.split('/')[-1].replace('slide', '').replace('.xml.rels', ''))
+                    if target_slide is not None and slide_num != target_slide:
+                        continue
+                    with pptx.open(file) as rels_file:
+                        rels_tree = ET.parse(rels_file)
+                        rels_root = rels_tree.getroot()
+                        for rel in rels_root.findall('{http://schemas.openxmlformats.org/package/2006/relationships}Relationship'):
+                            target = rel.attrib.get('Target', '')
+                            if 'embeddings/' in target or 'package' in rel.attrib.get('Type', '').lower() or 'oleobject' in rel.attrib.get('Type', '').lower():
+                                emb_path = 'ppt/' + target.replace('../', '') if not target.startswith('ppt/') else target
+                                if emb_path in pptx.namelist() and emb_path not in slide_excel_map[slide_num]:
+                                    slide_excel_map[slide_num].append(emb_path)
+
+            slide_excel_tables = {}
+            for slide_num, emb_files in slide_excel_map.items():
+                tables = []
+                for emb_path in emb_files:
+                    try:
+                        raw_data = pptx.read(emb_path)
+
+                        # 1. Try Direct ZIP/XLSX
+                        if raw_data.startswith(b"PK\x03\x04"):
+                            parsed = _parse_xlsx_stream(io.BytesIO(raw_data))
+                            tables.extend(parsed)
+                            continue
+
+                        # 2. Try OLE2 CFBF Container (Package / Workbook streams)
+                        if raw_data.startswith(b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"):
+                            ole_streams = extract_ole_streams(raw_data)
+                            if "Package" in ole_streams:
+                                parsed = _parse_xlsx_stream(io.BytesIO(ole_streams["Package"]))
+                                tables.extend(parsed)
+                                continue
+                            elif "Workbook" in ole_streams:
+                                biff_md = parse_biff8_workbook(ole_streams["Workbook"])
+                                if biff_md:
+                                    tables.append(biff_md)
+                                    continue
+                            elif "Book" in ole_streams:
+                                biff_md = parse_biff8_workbook(ole_streams["Book"])
+                                if biff_md:
+                                    tables.append(biff_md)
+                                    continue
+
+                        # 3. Fallback: Search for embedded PK (ZIP) header anywhere in binary
+                        pk_idx = raw_data.find(b"PK\x03\x04")
+                        if pk_idx != -1:
+                            parsed = _parse_xlsx_stream(io.BytesIO(raw_data[pk_idx:]))
+                            tables.extend(parsed)
+                            continue
+
+                    except Exception:
+                        pass
+                if tables:
+                    slide_excel_tables[slide_num] = tables
+            return slide_excel_tables
+    except Exception:
+        return {}
+
+def format_chart_category_val(val_text, format_code=''):
+    if not val_text:
+        return ""
+    is_date_fmt = any(k in format_code.lower() for k in ['yy', 'mmm', 'dd', 'd-', 'm-']) if format_code else False
+    try:
+        f_val = float(val_text)
+        if (is_date_fmt and 1 <= f_val <= 100000) or (not format_code and 35000 <= f_val <= 60000):
+            dt = datetime.datetime(1899, 12, 30) + datetime.timedelta(days=f_val)
+            if format_code and ('d' in format_code.lower()):
+                return dt.strftime('%d-%b-%y')
+            return dt.strftime('%b-%y')
+    except Exception:
+        pass
+    return str(val_text)
+
+def format_chart_num_val(val_str, is_percent=False):
+    if not val_str:
+        return ""
+    try:
+        val_float = float(val_str)
+        if is_percent:
+            pct_val = val_float * 100.0 if abs(val_float) <= 1.0 else val_float
+            if pct_val.is_integer():
+                return f"{int(pct_val)}%"
+            formatted = f"{pct_val:.3f}".rstrip('0').rstrip('.')
+            return f"{formatted}%"
+
+        if val_float.is_integer():
+            return str(int(val_float))
+        formatted = f"{val_float:.3f}".rstrip('0').rstrip('.')
+        return formatted
+    except Exception:
+        return str(val_str)
+
+def extract_chart_data_from_pptx(pptx_file, target_slide=None):
+    with zipfile.ZipFile(pptx_file, 'r') as pptx:
+        slide_chart_map = defaultdict(list)
+
+        for file in pptx.namelist():
+            if file.startswith('ppt/slides/_rels/slide') and file.endswith('.xml.rels'):
+                slide_num = int(file.split('/')[-1].replace('slide', '').replace('.xml.rels', ''))
+                if target_slide is not None and slide_num != target_slide:
+                    continue
+
+                with pptx.open(file) as rels_file:
+                    rels_tree = ET.parse(rels_file)
+                    rels_root = rels_tree.getroot()
+                    for rel in rels_root.findall('{http://schemas.openxmlformats.org/package/2006/relationships}Relationship'):
+                        target = rel.attrib.get('Target', '')
+                        if 'charts/chart' in target:
+                            chart_path = 'ppt/' + target.replace('../', '')
+                            slide_chart_map[slide_num].append(chart_path)
+
+        namespaces = {
+            'c': 'http://schemas.openxmlformats.org/drawingml/2006/chart',
+            'a': 'http://schemas.openxmlformats.org/drawingml/2006/main',
+        }
+
+        slide_chart_data = {}
+
+        for slide_num, chart_files in slide_chart_map.items():
+            charts_in_slide = []
+
+            for chart_file in chart_files:
+                if chart_file not in pptx.namelist():
+                    continue
+
+                with pptx.open(chart_file) as f:
+                    tree = ET.parse(f)
+                    root = tree.getroot()
+
+                    # Extract Chart Title if present
+                    chart_title = None
+                    title_el = root.find('.//c:chart//c:title', namespaces)
+                    if title_el is not None:
+                        title_parts = [t.text for t in title_el.findall('.//a:t', namespaces) if t.text]
+                        if not title_parts:
+                            title_parts = [v.text for v in title_el.findall('.//c:v', namespaces) if v.text]
+                        if title_parts:
+                            chart_title = "".join(title_parts).strip()
+
+                    chart_series_list = []
+
+                    for ser in root.findall('.//c:ser', namespaces):
+                        series_name = ser.find('.//c:tx//c:v', namespaces)
+                        if series_name is None:
+                            series_name = ser.find('.//c:tx//a:t', namespaces)
+                        series_name = series_name.text if series_name is not None else 'Series'
+
+                        # Check for percentage format code in OpenXML or explicit '%' in series name
+                        format_code = ""
+                        num_fmt_el = ser.find('.//c:numFmt', namespaces) or ser.find('.//c:formatCode', namespaces)
+                        if num_fmt_el is not None:
+                            format_code = num_fmt_el.attrib.get('formatCode', '') or num_fmt_el.text or ''
+
+                        is_percent = '%' in format_code or '%' in series_name
+
+                        cat_el = ser.find('.//c:cat', namespaces)
+                        cat_format_code = ""
+                        if cat_el is not None:
+                            cat_fmt_el = cat_el.find('.//c:numFmt', namespaces) or cat_el.find('.//c:formatCode', namespaces)
+                            if cat_fmt_el is not None:
+                                cat_format_code = cat_fmt_el.attrib.get('formatCode', '') or cat_fmt_el.text or ''
+
+                        categories = [
+                            format_chart_category_val(cat_pt.text, cat_format_code) for cat_pt in ser.findall('.//c:cat//c:pt//c:v', namespaces)
+                        ]
+                        raw_values = [
+                            val_el.text for val_el in ser.findall('.//c:val//c:pt//c:v', namespaces)
+                        ]
+
+                        formatted_values = [
+                            format_chart_num_val(v, is_percent=is_percent) for v in raw_values
+                        ]
+
+                        data_points = list(zip(categories, formatted_values)) if categories else formatted_values
+                        chart_series_list.append({
+                            'series': series_name,
+                            'data': data_points
+                        })
+
+                    if chart_series_list:
+                        all_cats = []
+                        for s in chart_series_list:
+                            for dp in s['data']:
+                                if isinstance(dp, tuple) and dp[0] not in all_cats:
+                                    all_cats.append(dp[0])
+
+                        table_parts = []
+                        if chart_title:
+                            table_parts.append(chart_title)
+
+                        if all_cats:
+                            header = "| " + " | ".join(["Series"] + all_cats) + " |"
+                            sep = "| " + " | ".join(["---"] + ["---" for _ in all_cats]) + " |"
+                            rows = [header, sep]
+                            for s in chart_series_list:
+                                val_dict = {dp[0]: dp[1] for dp in s['data'] if isinstance(dp, tuple)}
+                                row_cells = [s['series']] + [val_dict.get(c, "-") for c in all_cats]
+                                rows.append("| " + " | ".join(row_cells) + " |")
+                            table_parts.append("\n".join(rows))
+                        else:
+                            lines = []
+                            for s in chart_series_list:
+                                lines.append(f"• {s['series']}: " + ", ".join(str(d) for d in s['data']))
+                            table_parts.append("\n".join(lines))
+
+                        charts_in_slide.append("\n\n".join(table_parts))
+
+            slide_chart_data[slide_num] = charts_in_slide
+
+        return slide_chart_data
+
+from collections import namedtuple
+
+# TextItem preserves backward compatibility where it[0]=x, it[1]=y, it[2]=text
+# while exposing it.right and it.bottom for exact physical bounding boxes.
+TextItem = namedtuple('TextItem', ['x', 'y', 'text', 'right', 'bottom'])
+
+def extract_wmf_text_records(wmf_bytes):
+    """
+    Decodes vector text records from a 16-bit Windows Metafile (WMF) binary stream:
+    - META_EXTTEXTOUT (0x0A32 / 2610)
+    - META_TEXTOUT (0x0521 / 1313)
+    Returns a list of TextItem(x, y, text, right, bottom) tuples.
+    """
+    items = []
+    offset = 0
+    # Check Placeable Header (magic: 0x9AC6CDD7)
+    if len(wmf_bytes) > 22 and wmf_bytes[:4] == b'\xd7\xcd\xc6\x9a':
+        offset = 22
+    if len(wmf_bytes) < offset + 18:
+        return items
+    offset += 18
+    while offset < len(wmf_bytes) - 6:
+        rd_size, rd_func = struct.unpack_from('<IH', wmf_bytes, offset)
+        if rd_size == 0:
+            break
+        rec_len_bytes = rd_size * 2
+        if offset + rec_len_bytes > len(wmf_bytes):
+            break
+        rec_data = wmf_bytes[offset:offset+rec_len_bytes]
+        if rd_func == 0x0A32 and len(rec_data) >= 12:
+            y, x, count, fw_opts = struct.unpack_from('<hhHH', rec_data, 6)
+            str_offset = 14
+            rec_rect = None
+            if (fw_opts & 0x0006) != 0 and len(rec_data) >= 22:
+                r_left, r_top, r_right, r_bottom = struct.unpack_from('<hhhh', rec_data, 14)
+                rec_rect = (int(r_left), int(r_top), int(r_right), int(r_bottom))
+                str_offset = 22
+            if str_offset + count <= len(rec_data):
+                raw_s = rec_data[str_offset:str_offset+count]
+                try:
+                    s = raw_s.decode('utf-8')
+                except Exception:
+                    s = raw_s.decode('latin1', errors='ignore')
+                s = s.strip()
+                if s:
+                    if rec_rect and rec_rect[2] > rec_rect[0]:
+                        items.append(TextItem(rec_rect[0], rec_rect[1], s, rec_rect[2], rec_rect[3]))
+                    else:
+                        items.append(TextItem(int(x), int(y), s, int(x) + len(s) * 7, int(y) + 14))
+        elif rd_func == 0x0521 and len(rec_data) >= 12:
+            count = struct.unpack_from('<H', rec_data, 6)[0]
+            str_offset = 8
+            pad_count = count + (count % 2)
+            if str_offset + pad_count + 4 <= len(rec_data):
+                y, x = struct.unpack_from('<hh', rec_data, str_offset + pad_count)
+                raw_s = rec_data[str_offset:str_offset+count]
+                try:
+                    s = raw_s.decode('utf-8')
+                except Exception:
+                    s = raw_s.decode('latin1', errors='ignore')
+                s = s.strip()
+                if s:
+                    items.append(TextItem(int(x), int(y), s, int(x) + len(s) * 7, int(y) + 14))
+        offset += rec_len_bytes
+    return items
+
+def extract_emf_text_records(emf_bytes):
+    """
+    Decodes vector text records from an Enhanced Metafile (EMF) binary stream:
+    - EMR_EXTTEXTOUTW (0x54 / 84) - UTF-16LE text
+    - EMR_EXTTEXTOUTA (0x53 / 83) - ANSI/Latin1 text
+    Extracts the true physical bounding box [left, top, right, bottom] written by Windows GDI.
+    Returns a list of TextItem(x, y, text, right, bottom) tuples.
+    """
+    offset = 0
+    items = []
+    cur_dx, cur_dy = 0.0, 0.0
+    while offset < len(emf_bytes) - 8:
+        itype, nsize = struct.unpack_from('<II', emf_bytes, offset)
+        if nsize <= 0 or offset + nsize > len(emf_bytes):
+            break
+        rec_data = emf_bytes[offset:offset+nsize]
+        if itype in (35, 36) and len(rec_data) >= 32:  # EMR_SETWORLDTRANSFORM / EMR_MODIFYWORLDTRANSFORM
+            try:
+                _, _, _, _, eDx, eDy = struct.unpack_from('<ffffff', rec_data, 8)
+                cur_dx, cur_dy = float(eDx), float(eDy)
+            except Exception:
+                pass
+        elif itype in (83, 84) and len(rec_data) >= 76:  # EMR_EXTTEXTOUTW / EMR_EXTTEXTOUTA
+            rcl_left, rcl_top, rcl_right, rcl_bottom = struct.unpack_from('<iiii', rec_data, 8)
+            ref_x, ref_y = struct.unpack_from('<ii', rec_data, 36)
+            nchars, off_str = struct.unpack_from('<II', rec_data, 44)
+            is_w = (itype == 84)
+            char_len = nchars * 2 if is_w else nchars
+            if off_str + char_len <= len(rec_data):
+                raw_bytes = rec_data[off_str:off_str + char_len]
+                s = raw_bytes.decode('utf-16le' if is_w else 'latin1', errors='ignore').strip()
+                if s:
+                    eff_x = cur_dx if (ref_x == 0 and cur_dx != 0.0) else float(ref_x)
+                    eff_y = cur_dy if (ref_y == 0 and cur_dy != 0.0) else float(ref_y)
+                    if rcl_right > rcl_left:
+                        item_l = float(rcl_left)
+                        item_r = float(rcl_right)
+                        item_t = float(rcl_top)
+                        item_b = float(rcl_bottom)
+                    else:
+                        item_l = eff_x
+                        item_t = eff_y
+                        item_r = eff_x + len(s) * 7.0
+                        item_b = eff_y + 14.0
+                    items.append(TextItem(item_l, item_t, s, item_r, item_b))
+        offset += nsize
+    return items
+
+
+def extract_metafile_text_records(data):
+    """
+    Dispatches decoding between EMF (32-bit) and WMF (16-bit) vector formats.
+    """
+    if not data or len(data) < 18:
+        return []
+    # EMF header magic (record type 1 at offset 0)
+    if len(data) >= 4 and data[:4] == b'\x01\x00\x00\x00':
+        return extract_emf_text_records(data)
+    # WMF placeable magic or standard header
+    if (len(data) >= 4 and data[:4] == b'\xd7\xcd\xc6\x9a') or (len(data) >= 2 and data[:2] == b'\x01\x00'):
+        return extract_wmf_text_records(data)
+    # Fallback try EMF first then WMF
+    res = extract_emf_text_records(data)
+    if not res:
+        res = extract_wmf_text_records(data)
+    return res
+
+def split_side_by_side_blocks(items):
+    """
+    Geometrically detects and splits side-by-side sub-tables/blocks in vector drawings
+    by finding column gutters separating parallel table headers/blocks.
+    """
+    if not items or len(items) < 10:
+        return [items] if items else []
+    sorted_by_y = sorted(items, key=lambda it: (it[1], it[0]))
+    min_y = sorted_by_y[0][1]
+
+    # Find top-row section titles (e.g. 2 or 3 parallel titles at the top edge)
+    top_items = [it for it in sorted_by_y if it[1] <= min_y + 8 and any(c.isalpha() for c in it[2]) and len(it[2].strip()) >= 2]
+    top_items.sort(key=lambda it: it[0])
+
+    # If top row has > 3 items, it is a multi-column table header row (e.g. wide single table), NOT table titles!
+    if len(top_items) < 2 or len(top_items) > 3:
+        return [items]
+
+    candidate_splits = []
+    for i in range(len(top_items) - 1):
+        t1_x = top_items[i][0]
+        t2_x = top_items[i+1][0]
+        if t2_x - t1_x > 200:
+            window_xs = sorted(set(it[0] for it in items if t1_x <= it[0] <= t2_x + 50))
+            gaps = []
+            for j in range(len(window_xs) - 1):
+                g = window_xs[j+1] - window_xs[j]
+                if g >= 35:
+                    gaps.append((window_xs[j], window_xs[j+1], g))
+            
+            if gaps:
+                chosen_split = None
+                for x_left, x_right, _ in reversed(gaps):
+                    col_items = [it for it in items if abs(it[0] - x_right) <= 20]
+                    if x_right <= t2_x:
+                        if len(col_items) >= 2 or x_right >= t2_x - 30:
+                            chosen_split = (x_left + x_right) / 2
+                            if len(col_items) >= 2:
+                                break
+                if chosen_split is None:
+                    chosen_split = (gaps[-1][0] + gaps[-1][1]) / 2
+                candidate_splits.append(chosen_split)
+
+    if not candidate_splits or len(candidate_splits) != len(top_items) - 1:
+        return [items]
+
+    def count_cols_in_block(b_items):
+        col_means = []
+        for it in sorted(b_items, key=lambda x: x[0]):
+            x = it[0]
+            matched = False
+            for c in col_means:
+                if abs(c['mean'] - x) <= 30:
+                    c['items'].append(it)
+                    c['mean'] = sum(i[0] for i in c['items']) / len(c['items'])
+                    matched = True
+                    break
+            if not matched:
+                col_means.append({'mean': x, 'items': [it]})
+        return len(col_means)
+
+    bounds = [0] + sorted(candidate_splits) + [999999]
+    blocks = []
+    for i in range(len(bounds) - 1):
+        b_items = [it for it in items if bounds[i] <= it[0] < bounds[i+1]]
+        if len(b_items) < 10 or count_cols_in_block(b_items) < 2:
+            return [items]
+        blocks.append(b_items)
+
+    # Validate that each block represents an independent sub-table with its own row labels/categories.
+    # If blocks lack text labels in data rows (e.g. they only contain numbers/values under a spanning header banner),
+    # they are columns of a single unified table with zero space between sections, NOT separate tables!
+    for b in blocks:
+        rg_list = []
+        for it in sorted(b, key=lambda x: (x[1], x[0])):
+            if not rg_list or abs(rg_list[-1]['y'] - it[1]) > 8:
+                rg_list.append({'y': it[1], 'items': [it]})
+            else:
+                rg_list[-1]['items'].append(it)
+
+        def is_num(t):
+            s = t.strip().rstrip('%').lstrip('$').lstrip('₹').replace(',', '').replace('(', '-').replace(')', '')
+            try:
+                float(s)
+                return True
+            except ValueError:
+                return False
+
+        first_data_y = None
+        for rg in rg_list:
+            if sum(1 for it in rg['items'] if is_num(it[2])) >= 1:
+                first_data_y = rg['y']
+                break
+
+        if first_data_y is not None:
+            text_labels = [it[2] for it in b if it[1] >= first_data_y and any(c.isalpha() for c in it[2]) and it[2] != '-']
+            if not text_labels:
+                return [items]
+
+    return blocks if blocks else [items]
+
+def build_table_from_emf_items(sub_items):
+    """
+    Converts a clustered block of 2D EMF/WMF vector text coordinates into a Markdown table or structured text.
+    Handles multi-tier table headers with spanning banner forward-fill and parenthesized subheaders.
+    """
+    if not sub_items:
+        return ""
+    sorted_by_y = sorted(sub_items, key=lambda it: (it[1], it[0]))
+    min_y = sorted_by_y[0][1]
+
+    # Filter out single rogue digits at top edge and zero-height placeholder dashes
+    clean_items = [it for it in sorted_by_y if not (it[1] <= min_y + 10 and len(it[2].strip()) == 1 and it[2].strip().isdigit()) and not (it[2] == '-' and it.bottom <= it[1])]
+    if not clean_items:
+        return ""
+    min_y = clean_items[0][1]
+
+    # Title detection
+    title = ""
+    min_x = min(it[0] for it in clean_items) if clean_items else 0
+    max_x = max(it[0] for it in clean_items) if clean_items else 0
+    width = max(max_x - min_x, 1)
+    top_row = [it for it in clean_items if it[1] <= min_y + 8 and any(c.isalpha() for c in it[2])]
+    if len(top_row) == 1 and (top_row[0][0] - min_x) <= width * 0.7:
+        title = top_row[0][2]
+        remaining = [it for it in clean_items if it not in top_row]
+    else:
+        remaining = clean_items
+
+    # Separate footnote lines at the bottom (lone item at bottom edge starting with * or Note)
+    footnotes = []
+    if not remaining:
+        return ""
+    max_y = max(it[1] for it in remaining)
+    bottom_items = [it for it in remaining if it[1] >= max_y - 10]
+    if len(bottom_items) == 1 and bottom_items[0][2].startswith(('*', 'Note:', 'Note -', '#')):
+        footnotes.append(bottom_items[0][2])
+        remaining = [it for it in remaining if it not in bottom_items]
+
+    # Group into rows by Y (threshold 8px)
+    row_groups = []
+    for it in remaining:
+        if not row_groups or abs(row_groups[-1]['y'] - it[1]) > 8:
+            row_groups.append({'y': it[1], 'items': [it]})
+        else:
+            row_groups[-1]['items'].append(it)
+
+    # Merge wrapped multiline rows (continuation lines)
+    merged = []
+    i = 0
+    while i < len(row_groups):
+        rg = row_groups[i]
+        # Lookahead: single-item line followed by multi-item row where next row lacks item at this X
+        if len(rg['items']) == 1 and i + 1 < len(row_groups) and len(row_groups[i+1]['items']) >= 2:
+            next_rg = row_groups[i+1]
+            it_x = rg['items'][0][0]
+            if all(abs(it[0] - it_x) > 30 for it in next_rg['items']) and (next_rg['y'] - rg['y']) <= 25:
+                next_rg['items'].append(rg['items'][0])
+                next_rg['items'].sort(key=lambda x: x[0])
+                i += 1
+                continue
+        # Lookahead: multi-item row followed by single-item continuation line
+        if len(rg['items']) >= 2 and i + 1 < len(row_groups) and len(row_groups[i+1]['items']) == 1:
+            next_rg = row_groups[i+1]
+            it_next = next_rg['items'][0]
+            matched_item = None
+            for it in rg['items']:
+                if abs(it[0] - it_next[0]) <= 30:
+                    matched_item = it
+                    break
+            if matched_item is not None and (next_rg['y'] - rg['y']) <= 25:
+                idx_in_rg = rg['items'].index(matched_item)
+                merged_text = f"{matched_item[2]} {it_next[2]}"
+                merged_right = max(matched_item.right, it_next.right)
+                merged_bottom = max(matched_item.bottom, it_next.bottom)
+                merged_it = TextItem(matched_item[0], matched_item[1], merged_text, merged_right, merged_bottom)
+                rg['items'][idx_in_rg] = merged_it
+                merged.append(rg)
+                i += 2
+                continue
+        merged.append(rg)
+        i += 1
+    row_groups = merged
+
+    # Filter pure separator lines (rows where all items are '-')
+    row_groups = [r for r in row_groups if not all(it[2] == '-' for it in r['items'])]
+
+    if not row_groups:
+        return title
+
+    for r in row_groups:
+        r['items'].sort(key=lambda it: it[0])
+
+    if len(row_groups) <= 1 or max(len(rg['items']) for rg in row_groups) <= 1:
+        lines = []
+        if title:
+            lines.append(f"### {title}\n")
+        for rg in row_groups:
+            r_text = " ".join(it[2] for it in rg['items'])
+            if r_text:
+                lines.append(r_text)
+        if footnotes:
+            lines.append("\n" + "\n".join(footnotes))
+        return "\n".join(lines)
+
+    # Separate Header Rows vs Data Rows
+    def is_cell_numeric(text):
+        if not text:
+            return False
+        s = text.strip().rstrip('%').lstrip('$').lstrip('₹').lstrip('€').lstrip('£').strip()
+        s = s.replace(',', '').replace('(', '-').replace(')', '')
+        try:
+            float(s)
+            return True
+        except ValueError:
+            return False
+
+    first_data_idx = None
+    for idx, rg in enumerate(row_groups):
+        num_numeric = sum(1 for it in rg['items'] if is_cell_numeric(it[2]))
+        if num_numeric >= 2 or (num_numeric >= 1 and idx >= 1):
+            first_data_idx = idx
+            break
+
+    if first_data_idx is None:
+        header_rows = [row_groups[0]]
+        data_rows = row_groups[1:]
+    elif first_data_idx == 0:
+        header_rows = []
+        data_rows = row_groups
+    else:
+        if first_data_idx > 1 and len(row_groups[first_data_idx - 1]['items']) == 1 and len(row_groups[first_data_idx - 2]['items']) >= 3:
+            first_data_idx -= 1
+        header_rows = row_groups[:first_data_idx]
+        data_rows = row_groups[first_data_idx:]
+
+    # Check for unaligned header (missing stub header like in Slide 9 Actuals where data has a column far to the left of all header items)
+    if header_rows and data_rows:
+        min_hdr_x = min(it[0] for r in header_rows for it in r['items'])
+        data_xs_left_of_hdr = [it[0] for r in data_rows for it in r['items'] if it[0] < min_hdr_x - 100]
+        if len(data_xs_left_of_hdr) >= max(1, len(data_rows) * 0.5):
+            left_x = min(data_xs_left_of_hdr)
+            for r in header_rows:
+                stub_y = r['items'][0][1]
+                stub_bottom = r['items'][0].bottom if hasattr(r['items'][0], 'bottom') else stub_y + 14.0
+                r['items'].insert(0, TextItem(left_x, stub_y, '-', left_x + 10.0, stub_bottom))
+
+    # Derive column clusters from all header items using column spacing threshold
+    all_header_items = [it for hr in header_rows for it in hr['items']]
+    sh_clusters = []
+    if all_header_items:
+        data_items = [it for r in data_rows for it in r['items']]
+        cluster_gap = 18.0
+        if data_items:
+            data_xs = sorted(it[0] for it in data_items)
+            d_cl = []
+            for x in data_xs:
+                if not d_cl or abs(d_cl[-1][-1] - x) > 30:
+                    d_cl.append([x])
+                else:
+                    d_cl[-1].append(x)
+            data_centers = [sum(c) / len(c) for c in d_cl]
+            d_spacings = [data_centers[c + 1] - data_centers[c] for c in range(len(data_centers) - 1)]
+            if d_spacings:
+                cluster_gap = max(18.0, min(d_spacings) * 0.45)
+
+        all_header_items_sorted = sorted(all_header_items, key=lambda x: x[0])
+        for it in all_header_items_sorted:
+            if not sh_clusters or (it[0] - sh_clusters[-1][-1][0] > cluster_gap):
+                sh_clusters.append([it])
+            else:
+                sh_clusters[-1].append(it)
+
+    valid_lens = [len(r['items']) for r in (header_rows + data_rows) if len(r['items']) >= 2]
+    max_cols = max(valid_lens) if valid_lens else (len(row_groups[0]['items']) if row_groups else 1)
+
+    # Collect column items for each column from full-width rows to establish geometric column extents
+    full_rows = [r['items'] for r in data_rows if len(r['items']) == max_cols]
+    if len(full_rows) == 1 and any('total' in it[2].lower() for it in full_rows[0]):
+        non_total_rows = [r['items'] for r in data_rows if not any('total' in it[2].lower() for it in r['items'])]
+        if non_total_rows:
+            total_first_x = full_rows[0][0][0]
+            stubs_in_data = [it for it in non_total_rows[0] if it[0] < total_first_x]
+            if stubs_in_data:
+                full_rows = []
+
+    if not full_rows:
+        fallback_rows = [r['items'] for r in (header_rows + data_rows) if len(r['items']) == max_cols]
+        # Do not fall back to the single summary row that was just disqualified
+        if not (len(fallback_rows) == 1 and any('total' in it[2].lower() for it in fallback_rows[0])):
+            full_rows = fallback_rows
+
+    if full_rows:
+        full_xs = [sum(r[c][0] for r in full_rows) / len(full_rows) for c in range(len(full_rows[0]))]
+        full_rights = [sum(r[c].right for r in full_rows) / len(full_rows) for c in range(len(full_rows[0]))]
+        unmatched = []
+        for r in data_rows:
+            if len(r['items']) >= 2:
+                for it in r['items']:
+                    if not any(abs(it[0] - fx) < 25 or abs(it.right - fr) < 20 for fx, fr in zip(full_xs, full_rights)):
+                        unmatched.append(it)
+        persistent = []
+        if unmatched:
+            unmatched.sort(key=lambda it: it[0])
+            u_clusters = []
+            for u in unmatched:
+                if not u_clusters or abs(u[0] - u_clusters[-1][-1][0]) > 25:
+                    u_clusters.append([u])
+                else:
+                    u_clusters[-1].append(u)
+            persistent = [cl for cl in u_clusters if len(cl) >= 2]
+
+        if persistent:
+            all_col_centers = sorted(full_xs + [sum(u[0] for u in cl) / len(cl) for cl in persistent])
+            num_cols = len(all_col_centers)
+            col_items_by_c = [[] for _ in range(num_cols)]
+            for r in data_rows:
+                for it in r['items']:
+                    best_c = min(range(num_cols), key=lambda c: abs(it[0] - all_col_centers[c]))
+                    if abs(it[0] - all_col_centers[best_c]) < 35:
+                        col_items_by_c[best_c].append(it)
+            col_boxes = []
+            for c_idx in range(num_cols):
+                items_c = col_items_by_c[c_idx]
+                if items_c:
+                    mn = min(it.x for it in items_c)
+                    mx = max(it.right for it in items_c)
+                    col_boxes.append((mn, mx, (mn + mx) / 2.0))
+                else:
+                    col_boxes.append((all_col_centers[c_idx], all_col_centers[c_idx] + 20, all_col_centers[c_idx] + 10))
+        else:
+            num_cols = len(full_rows[0])
+            col_items_by_c = [[] for _ in range(num_cols)]
+            for r_items in full_rows:
+                for c_idx, it in enumerate(r_items):
+                    col_items_by_c[c_idx].append(it)
+            col_boxes = []
+            for c_idx in range(num_cols):
+                items_c = col_items_by_c[c_idx]
+                if items_c:
+                    mn = min(it.x for it in items_c)
+                    mx = max(it.right for it in items_c)
+                    col_boxes.append((mn, mx, (mn + mx) / 2.0))
+                else:
+                    col_boxes.append((0, 0, 0))
+    elif sh_clusters:
+        num_cols = len(sh_clusters)
+        col_boxes = []
+        for cl in sh_clusters:
+            mn = min(it.x for it in cl)
+            mx = max(it.right for it in cl)
+            col_boxes.append((mn, mx, (mn + mx) / 2.0))
+    else:
+        num_cols = max_cols
+        col_boxes = [(0, 0, 0) for _ in range(num_cols)]
+
+    # Calculate exact geometric dividers between adjacent columns
+    dividers = []
+    for c in range(num_cols - 1):
+        end_c = col_boxes[c][1]
+        start_next = col_boxes[c+1][0]
+        if start_next > end_c:
+            div = (end_c + start_next) / 2.0
+        else:
+            div = (col_boxes[c][0] + start_next) / 2.0
+        dividers.append(div)
+
+    col_bounds = []
+    for c in range(num_cols):
+        l = -float('inf') if c == 0 else dividers[c - 1]
+        r = float('inf') if c == num_cols - 1 else dividers[c]
+        col_bounds.append((l, r))
+
+    def get_col(it):
+        center = (it.x + it.right) / 2.0
+        return [ci for ci, (l, r) in enumerate(col_bounds) if l <= center < r][0]
+
+    def get_col_for_x(x):
+        return [ci for ci, (l, r) in enumerate(col_bounds) if l <= x < r][0]
+
+    # Detect true multi-column banners in the top header row
+    # A true banner has a physical text box [it.x, it.right] that spans across multiple column boundaries
+    # or whose text width significantly exceeds the column width (> 1.1x col_w)
+    banner_spans = {}
+    if num_cols >= 2 and len(header_rows) >= 2:
+        top_items = header_rows[0]['items']
+        banner_candidates = []
+        for it in top_items:
+            c_start = get_col_for_x(it.x)
+            c_end = get_col_for_x(it.right)
+            col_w_start = col_bounds[c_start][1] - col_bounds[c_start][0]
+            # True multi-column banner: physically spans across columns or width exceeds column width
+            if (c_end > c_start and (it.right - it.x) > col_w_start * 1.1) or (c_end - c_start >= 1 and (it.right - col_bounds[c_start][1]) > col_w_start * 0.15):
+                sub_cols = set(get_col(sub) for r in header_rows[1:] for sub in r['items'] if not (sub.right <= it.x or sub.x >= it.right))
+                if len(sub_cols) >= 2 or c_end - c_start >= 2 or (c_end > c_start and (it.right - it.x) > 100):
+                    banner_candidates.append(it)
+        if banner_candidates:
+            sorted_banners = sorted(banner_candidates, key=lambda it: it.x)
+            banner_centers = [(it.x + it.right) / 2.0 for it in sorted_banners]
+            first_b_start_c = get_col_for_x(sorted_banners[0].x)
+            if first_b_start_c > 0 and len(header_rows) >= 2:
+                upper_rows = header_rows[:-1]
+                for c_prev in range(first_b_start_c - 1, 0, -1):
+                    # Stop if column has an independent header in any row above the leaf header row
+                    has_upper = any(get_col(it) == c_prev for r in upper_rows for it in r['items'] if it not in banner_candidates)
+                    if has_upper:
+                        break
+                    first_b_start_c = c_prev
+            for c in range(first_b_start_c, num_cols):
+                col_c = (col_boxes[c][0] + col_boxes[c][1]) / 2.0
+                best_idx = min(range(len(sorted_banners)), key=lambda bi: abs(col_c - banner_centers[bi]))
+                b_cand = sorted_banners[best_idx]
+                # Check if this column physically overlaps the banner
+                c_overlaps = max(b_cand.x, col_bounds[c][0]) < min(b_cand.right, col_bounds[c][1])
+                # Check column's own header items in lower rows
+                col_sub_text = ' '.join(it[2] for r in header_rows[1:] for it in r['items'] if get_col(it) == c and it not in banner_candidates).strip()
+                # If column does not physically overlap the banner and its own header is an independent metric contained in the banner, do not span
+                if not c_overlaps and col_sub_text and len(col_sub_text) >= 3 and col_sub_text.lower() in b_cand[2].lower():
+                    if best_idx > 0 and col_c < banner_centers[best_idx]:
+                        b_cand = sorted_banners[best_idx - 1]
+                        c_overlaps = max(b_cand.x, col_bounds[c][0]) < min(b_cand.right, col_bounds[c][1])
+                        if not c_overlaps and col_sub_text and len(col_sub_text) >= 3 and col_sub_text.lower() in b_cand[2].lower():
+                            continue
+                    else:
+                        continue
+                banner_spans.setdefault(b_cand, []).append(c)
+
+    # Build Header Matrix: map banners across their spanned columns, and standard items into physical columns
+    h_matrix = [['' for _ in range(num_cols)] for _ in range(len(header_rows))]
+    for b_it, cols in banner_spans.items():
+        for c in cols:
+            h_matrix[0][c] = b_it[2]
+
+    for r_idx in range(len(header_rows) - 1, -1, -1):
+        for it in header_rows[r_idx]['items']:
+            if it in banner_spans:
+                continue
+            c_idx = get_col(it)
+            if h_matrix[r_idx][c_idx]:
+                h_matrix[r_idx][c_idx] += ' ' + it[2]
+            else:
+                h_matrix[r_idx][c_idx] = it[2]
+
+    # Multi-tier sub-banner forward-fill across parent banner columns
+    if len(header_rows) >= 3 and banner_spans:
+        for b_it, cols in banner_spans.items():
+            for r_i in range(1, len(header_rows) - 1):
+                sub_items_in_cols = [it for it in header_rows[r_i]['items'] if any(col_bounds[c][0] <= (it.x + it.right)/2.0 < col_bounds[c][1] for c in cols)]
+                if len(sub_items_in_cols) == 1:
+                    sub_b = sub_items_in_cols[0]
+                    # Verify that this is a true sub-tier banner overarching the columns below it,
+                    # i.e., lower header rows must contain child subheaders covering all columns in cols
+                    lower_cols = set(get_col(lit) for lr in range(r_i + 1, len(header_rows)) for lit in header_rows[lr]['items'] if any(col_bounds[c][0] <= (lit.x + lit.right)/2.0 < col_bounds[c][1] for c in cols))
+                    if lower_cols == set(cols):
+                        for c in cols:
+                            h_matrix[r_i][c] = sub_b[2]
+
+    # Multi-tier Header Merging
+    if len(header_rows) >= 2:
+        header_names = []
+        banner_texts = set(b_it[2] for b_it in banner_spans.keys())
+        for c in range(num_cols):
+            parts = [h_matrix[r][c] for r in range(len(header_rows)) if h_matrix[r][c]]
+            if not parts:
+                header_names.append('-')
+            elif len(parts) == 1:
+                header_names.append(parts[0])
+            else:
+                top = parts[0]
+                sub = ' '.join(parts[1:])
+                if sub.lower() in top.lower():
+                    header_names.append(top)
+                elif top.lower() in sub.lower():
+                    header_names.append(sub)
+                elif top not in banner_texts:
+                    header_names.append(f'{top} {sub}')
+                elif sub.startswith('('):
+                    header_names.append(f'{top} {sub}')
+                elif '(' in sub and ')' in sub:
+                    header_names.append(f'{top} {sub}')
+                else:
+                    header_names.append(f'{top} ({sub})')
+    elif len(header_rows) == 1:
+        header_names = [h_matrix[0][c] if h_matrix[0][c] else '-' for c in range(num_cols)]
+    else:
+        header_names = ['-' for _ in range(num_cols)]
+
+    if title and all(h in ('-', '') for h in header_names):
+        header_names = [title] + [""] * (num_cols - 1)
+        title = ""
+
+    # Map Data Rows into Grid
+    grid = []
+    for rg in data_rows:
+        row_cells = [""] * num_cols
+        for it in rg['items']:
+            c_idx = get_col(it)
+            if row_cells[c_idx]:
+                row_cells[c_idx] += ' ' + it[2]
+            else:
+                row_cells[c_idx] = it[2]
+        grid.append(row_cells)
+
+    separator = ["---"] * len(header_names)
+
+    md_lines = []
+    if title:
+        md_lines.append(f"### {title}\n")
+    md_lines.append("| " + " | ".join(header_names) + " |")
+    md_lines.append("| " + " | ".join(separator) + " |")
+
+    for r in grid:
+        md_lines.append("| " + " | ".join(r) + " |")
+
+    if footnotes:
+        md_lines.append("\n" + "\n".join(footnotes))
+
+    return "\n".join(md_lines)
+
+def extract_emf_tables_and_text(media_bytes):
+    """
+    Parses an EMF or WMF byte stream and returns formatted Markdown tables / text.
+    Builds standard multi-column Markdown tables using geometric row/column clustering.
+    """
+    items = extract_metafile_text_records(media_bytes)
+    if not items:
+        return ""
+
+    blocks = split_side_by_side_blocks(items)
+    results = []
+    for b in blocks:
+        t = build_table_from_emf_items(b)
+        if t.strip():
+            results.append(t.strip())
+    return "\n\n".join(results)
+
+def extract_emf_content_per_slide(pptx_file, target_slide=None):
+    """
+    Extracts all EMF/WMF vector tables and text associated with slides in a PPTX archive.
+    Returns a dict mapping slide_num -> list of markdown strings ordered spatially.
+    """
+    slide_emf_map = defaultdict(list)
+    try:
+        with zipfile.ZipFile(pptx_file, 'r') as pptx:
+            for file in pptx.namelist():
+                if file.startswith('ppt/slides/_rels/slide') and file.endswith('.xml.rels'):
+                    slide_num = int(file.split('/')[-1].replace('slide', '').replace('.xml.rels', ''))
+                    if target_slide is not None and slide_num != target_slide:
+                        continue
+                    
+                    rid_to_target = {}
+                    with pptx.open(file) as rels_file:
+                        rels_tree = ET.parse(rels_file)
+                        rels_root = rels_tree.getroot()
+                        for rel in rels_root.findall('{http://schemas.openxmlformats.org/package/2006/relationships}Relationship'):
+                            rid = rel.attrib.get('Id')
+                            target = rel.attrib.get('Target', '')
+                            ext = target.lower().split('.')[-1]
+                            if ext in ('emf', 'wmf'):
+                                media_path = 'ppt/' + target.replace('../', '') if not target.startswith('ppt/') else target
+                                if media_path in pptx.namelist():
+                                    rid_to_target[rid] = media_path
+                                    
+                    # Parse slide xml to sort metafiles by shape 2D reading order (Row-by-row: Y then X)
+                    slide_xml_name = f"ppt/slides/slide{slide_num}.xml"
+                    ordered_emfs = []
+                    if slide_xml_name in pptx.namelist():
+                        try:
+                            slide_root = ET.fromstring(pptx.read(slide_xml_name))
+                            for elem in slide_root.iter():
+                                if elem.tag.endswith('}graphicFrame') or elem.tag.endswith('}pic') or elem.tag.endswith('}sp'):
+                                    blip = elem.find('.//{http://schemas.openxmlformats.org/drawingml/2006/main}blip')
+                                    if blip is not None:
+                                        embed_rid = blip.get('{http://schemas.openxmlformats.org/officeDocument/2006/relationships}embed')
+                                        if embed_rid in rid_to_target:
+                                            media_path = rid_to_target[embed_rid]
+                                            xfrm = elem.find('.//{http://schemas.openxmlformats.org/drawingml/2006/main}xfrm')
+                                            off = xfrm.find('{http://schemas.openxmlformats.org/drawingml/2006/main}off') if xfrm is not None else None
+                                            x = int(off.get('x', 0)) if off is not None else 0
+                                            y = int(off.get('y', 0)) if off is not None else 0
+                                            if not any(item[2] == media_path for item in ordered_emfs):
+                                                ordered_emfs.append((y, x, media_path))
+                        except Exception:
+                            pass
+                            
+                    if ordered_emfs:
+                        # Cluster rows within ~15% slide height tolerance then order left to right
+                        ordered_emfs.sort(key=lambda item: (round(item[0] / 1000000), item[1]))
+                        for _, _, media_path in ordered_emfs:
+                            if media_path not in slide_emf_map[slide_num]:
+                                slide_emf_map[slide_num].append(media_path)
+                    else:
+                        for media_path in rid_to_target.values():
+                            if media_path not in slide_emf_map[slide_num]:
+                                slide_emf_map[slide_num].append(media_path)
+
+            slide_emf_data = {}
+            for slide_num, emf_paths in slide_emf_map.items():
+                slide_results = []
+                for media_path in emf_paths:
+                    try:
+                        raw_data = pptx.read(media_path)
+                        content = extract_emf_tables_and_text(raw_data)
+                        if content.strip():
+                            slide_results.append(content.strip())
+                    except Exception:
+                        pass
+                if slide_results:
+                    slide_emf_data[slide_num] = slide_results
+            return slide_emf_data
+    except Exception:
+        return {}