@mohanscodex/spectra-code 0.4.8 → 0.5.0

package/skills/slides/scripts/detect_font.py

@@ -0,0 +1,873 @@
+#!/usr/bin/env python3
+"""Copyright (c) OpenAI. All rights reserved.
+
+Detect missing fonts for PPTX rendering by converting to ODP and inspecting the resolved font
+families per slide.
+
+Overview
+========
+PowerPoint files (PPTX) declare requested font families in runs and theme defaults, but the actual
+font used at render time depends on the renderer (LibreOffice in our pipeline), platform
+availability, and style inheritance. To make detection stable and renderer-accurate, this module:
+
+- Extracts requested families from PPTX per slide (reads a:r/a:rPr plus document defaults, grouped
+  by script: latin/ea/cs/sym). Analysis is done per run: we infer the script from run text and
+  select the matching a:rPr child (e.g., latin/ea/cs). Fonts declared for other scripts in the same
+  run are not counted as used.
+- Converts the PPTX to ODP using headless LibreOffice and parses ODP content.xml and styles.xml to
+  discover which families LibreOffice actually resolved for each slide (including master pages and
+  defaults).
+- Classifies each requested family on each slide into two buckets:
+  - font_missing: the family is not installed on the system (per fontconfig synonyms), so resolution
+    cannot possibly match the request.
+  - font_substituted: the family is installed but was resolved to another family in ODP for the
+    slide (theme/style inheritance or glyph coverage), i.e., installed but substituted.
+
+Key Design
+-----------------------
+1) Inspect the renderer's decision, not only the author's request. Reading PPTX alone tells you what
+   was requested, not what LibreOffice will choose after applying styles and availability checks.
+   Converting to ODP and reading the resolved fo:font-family/style:font-name* values yields a
+   faithful view of what the renderer actually used for each slide.
+
+2) Robust style resolution across ODP structures. Fonts can be specified under multiple layers. We
+   parse office:automatic-styles (both content.xml and styles.xml), office:styles and
+   style:default-style, draw:master-page references used by slides, nested style:text-properties
+   under paragraph-properties, and parent style chains (style:parent-style-name). A text-based
+   fallback parser supplements XML namespace lookups when vendor XML variations occur.
+
+3) Scalable aliasing via fontconfig synonyms, not ad hoc maps. PostScript names, full names, and
+   family names often differ. We build a synonym map from fc-list that unifies those identifiers. We
+   deliberately do NOT use fc-match -s fallback chains for matching, because fallback families
+   (e.g., DejaVu Sans) would mask missing/substitution cases and produce false passes.
+
+4) Clear classification: missing vs substituted.
+   - Missing: no synonym of the requested base family is present in the installed font set (per
+     fontconfig). These require installation.
+   - Substituted: the family is installed, but ODP does not reference it on the slide (LibreOffice
+     chose another family), which is useful for diagnosing style/theme issues or glyph-coverage
+     driven substitutions.
+
+Not Chosen (and why)
+--------------------
+- PDF inspection (e.g., pdffonts): PostScript names don't reliably map back to authoring families;
+  PDFs often reflect subsetted fonts and fallback choices, making robust detection noisy.
+- Ad hoc alias tables: unscalable for large-scale fonts and platform variants; the fontconfig
+  synonym corpus covers family/fullname/PostScript consistently.
+- Treating fallback families as matches (fc-match -s): causes false negatives by accepting generic
+  fallbacks when the requested family is missing.
+- Hardcoding checks in the renderer: we keep detection separate from render_slides to avoid
+  coupling and allow standalone checking.
+
+CLI
+---
+- JSON output exposes two categories by default (and text mode mirrors them): font_missing_overall/
+  font_missing_by_slide and font_substituted_overall/font_substituted_by_slide.
+- Flags include_missing/include_substituted control which categories are emitted (default True/True).
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import xml.etree.ElementTree as ET
+from functools import lru_cache
+from os.path import abspath, basename, exists, expanduser, join, splitext
+from zipfile import ZipFile
+
+STYLE_TOKENS = [
+    "regular",
+    "condensed",
+    "compressed",
+    "narrow",
+    "italic",
+    "oblique",
+    "semibold",
+    "demibold",
+    "bold",
+    "black",
+    "extra light",
+    "ultra light",
+    "extralight",
+    "ultralight",
+    "light",
+    "thin",
+    "medium",
+]
+
+
+def normalize_font_family_name(name: str) -> str:
+    s = name.casefold()
+    s = re.sub(r"\([^)]*\)", " ", s)
+    s = re.sub(r"[\s\-\_\.,/\'\"]+", " ", s)
+    return s.strip()
+
+
+def _or_dummy(node: ET.Element | None) -> ET.Element:
+    """Return the element if not None, otherwise a harmless dummy element.
+
+    Avoids deprecated truthiness checks on Element instances (`elem or dummy`).
+    """
+    return node if node is not None else ET.Element("dummy")
+
+
+@lru_cache(maxsize=1)
+def _build_fc_synonym_map() -> dict[str, set[str]]:
+    """Build synonym map from fontconfig; raise on failures; memoized (size=1)."""
+    proc = subprocess.run(
+        [
+            "fc-list",
+            "--format",
+            "%{family}\t%{fullname}\t%{postscriptname}\n",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    syn: dict[str, set[str]] = {}
+    for line in (proc.stdout or "").splitlines():
+        parts = line.split("\t")
+        if len(parts) != 3:
+            continue
+        fam_field, full_field, ps_field = parts
+        names: set[str] = set()
+        for field in (fam_field, full_field, ps_field):
+            for item in field.split(","):
+                norm = normalize_font_family_name(item)
+                if norm:
+                    names.add(norm)
+                    names.add(norm.replace(" ", ""))
+        for name in list(names):
+            bucket = syn.setdefault(name, set())
+            bucket.update(names)
+    return syn
+
+
+def _expand_via_fontconfig(family_base_norm: str) -> set[str]:
+    # Accept only true aliases/synonyms (family/fullname/PostScript) — not fallback replacements
+    acceptable: set[str] = {family_base_norm, family_base_norm.replace(" ", "")}
+    syn = _build_fc_synonym_map()
+    if family_base_norm in syn:
+        acceptable.update(syn[family_base_norm])
+    no_space = family_base_norm.replace(" ", "")
+    if no_space in syn:
+        acceptable.update(syn[no_space])
+    return acceptable
+
+
+def parse_font_family_base_and_styles(name_norm: str) -> tuple[str, set[str]]:
+    tokens = name_norm.split()
+    required: set[str] = set()
+    weight_code_map = {
+        "25": "ultra light",
+        "35": "thin",
+        "45": "light",
+        "55": "regular",
+        "65": "medium",
+        "75": "bold",
+        "85": "black",
+        "95": "black",
+    }
+    if tokens and tokens[0].isdigit() and tokens[0] in weight_code_map:
+        required.add(weight_code_map[tokens[0]])
+        tokens = tokens[1:]
+    if len(tokens) == 1:
+        t = tokens[0]
+        fused_map = [
+            ("extralight", "extra light"),
+            ("ultralight", "ultra light"),
+            ("semibold", "semibold"),
+            ("demibold", "semibold"),
+            ("condensed", "condensed"),
+            ("compressed", "condensed"),
+            ("narrow", "condensed"),
+            ("italic", "italic"),
+            ("oblique", "italic"),
+            ("bold", "bold"),
+            ("black", "black"),
+            ("light", "light"),
+            ("thin", "thin"),
+            ("medium", "medium"),
+            ("regular", "regular"),
+        ]
+        changed = True
+        while changed:
+            changed = False
+            for suf, tok in fused_map:
+                if t.endswith(suf) and len(t) > len(suf):
+                    t = t[: -len(suf)]
+                    required.add(tok)
+                    changed = True
+                    break
+        return (t.strip(), required)
+
+    while tokens:
+        tail = " ".join(tokens[-2:]) if len(tokens) >= 2 else tokens[-1]
+        matched = None
+        for style in STYLE_TOKENS:
+            if tail == style:
+                matched = style
+                break
+        if matched is None and tokens[-1] in STYLE_TOKENS:
+            matched = tokens[-1]
+        if matched is None:
+            break
+        if matched in ("compressed", "narrow"):
+            required.add("condensed")
+        elif matched == "roman":
+            required.add("regular")
+        elif matched == "demibold":
+            required.add("semibold")
+        else:
+            required.add(matched)
+        if " " in matched:
+            tokens = tokens[:-2]
+        else:
+            tokens = tokens[:-1]
+    return (" ".join(tokens).strip(), required)
+
+
+def _split_odf_family_list(value: str) -> list[str]:
+    out: list[str] = []
+    for part in value.split(","):
+        p = part.strip().strip("\"' ")
+        if p:
+            out.append(normalize_font_family_name(p))
+    return out
+
+
+def extract_used_fonts_from_pptx(pptx_path: str) -> dict[int, set[str]]:
+    by_slide: dict[int, set[str]] = {}
+    with ZipFile(pptx_path, "r") as zf:
+        for name in zf.namelist():
+            if not (name.startswith("ppt/slides/slide") and name.endswith(".xml")):
+                continue
+            base = os.path.basename(name)
+            m = re.search(r"(?i)slide(\d+)\.xml$", base)
+            slide_num = int(m.group(1)) if m else None
+            with zf.open(name) as f:
+                tree = ET.parse(f)
+            root = tree.getroot()
+            ns = {"a": "http://schemas.openxmlformats.org/drawingml/2006/main"}
+            defaults = _collect_default_font_faces(root)
+            for r in root.findall(".//a:r", ns):
+                parts: list[str] = []
+                for t in r.findall("a:t", ns):
+                    if t.text:
+                        parts.append(t.text)
+                text = "".join(parts)
+                if not text:
+                    continue
+                script = _detect_script_tag(text)
+                rpr = r.find("a:rPr", ns)
+                face_norm: str | None = None
+                if rpr is not None:
+                    child = rpr.find(f"a:{script}", ns)
+                    if child is not None:
+                        face = child.get("typeface")
+                        if face and not face.startswith("+"):
+                            face_norm = normalize_font_family_name(face)
+                bucket = by_slide.setdefault(slide_num or -1, set())
+                if face_norm is None:
+                    for f in defaults.get(script, set()):
+                        bucket.add(f)
+                else:
+                    bucket.add(face_norm)
+    return {k: v for k, v in by_slide.items() if k is not None and k != -1}
+
+
+def _detect_script_tag(text: str) -> str:
+    for ch in text:
+        cp = ord(ch)
+        if (
+            0x4E00 <= cp <= 0x9FFF
+            or 0x3400 <= cp <= 0x4DBF
+            or 0xF900 <= cp <= 0xFAFF
+            or 0x3040 <= cp <= 0x309F
+            or 0x30A0 <= cp <= 0x30FF
+            or 0x31F0 <= cp <= 0x31FF
+            or 0xAC00 <= cp <= 0xD7AF
+            or 0x3100 <= cp <= 0x312F
+            or 0x3000 <= cp <= 0x303F
+        ):
+            return "ea"
+    for ch in text:
+        cp = ord(ch)
+        if (
+            0x0590 <= cp <= 0x05FF
+            or 0x0600 <= cp <= 0x06FF
+            or 0x0700 <= cp <= 0x077F
+            or 0x0780 <= cp <= 0x07BF
+            or 0x0900 <= cp <= 0x0D7F
+            or 0x0E00 <= cp <= 0x0E7F
+            or 0x0E80 <= cp <= 0x0EFF
+            or 0xFB50 <= cp <= 0xFDFF
+            or 0xFE70 <= cp <= 0xFEFF
+        ):
+            return "cs"
+    for ch in text:
+        cp = ord(ch)
+        if (
+            (0x0041 <= cp <= 0x005A)
+            or (0x0061 <= cp <= 0x007A)
+            or (0x0030 <= cp <= 0x0039)
+            or (0x00C0 <= cp <= 0x024F)
+            or (0x1E00 <= cp <= 0x1EFF)
+        ):
+            return "latin"
+    return "latin"
+
+
+def _collect_default_font_faces(root: ET.Element) -> dict[str, set[str]]:
+    ns = {"a": "http://schemas.openxmlformats.org/drawingml/2006/main"}
+    defaults: dict[str, set[str]] = {"latin": set(), "ea": set(), "cs": set(), "sym": set()}
+    for defrpr in root.findall(".//a:defRPr", ns):
+        for tag in ("latin", "ea", "cs", "sym"):
+            child = defrpr.find(f"a:{tag}", ns)
+            if child is not None:
+                face = child.get("typeface")
+                if face and not face.startswith("+"):
+                    defaults[tag].add(normalize_font_family_name(face))
+    return defaults
+
+
+def _run_soffice_convert(cmd: list[str]) -> None:
+    subprocess.run(
+        cmd,
+        check=False,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        env=os.environ.copy(),
+    )
+
+
+def _export_to_odp(pptx_path: str, user_profile: str, out_dir: str, stem: str) -> str:
+    bin_path = shutil.which("soffice") or shutil.which("libreoffice") or "/usr/bin/libreoffice"
+    cmd_odp = [
+        bin_path,
+        "-env:UserInstallation=file://" + user_profile,
+        "--invisible",
+        "--headless",
+        "--norestore",
+        "--convert-to",
+        "odp",
+        "--outdir",
+        out_dir,
+        pptx_path,
+    ]
+    _run_soffice_convert(cmd_odp)
+    odp_path = join(out_dir, f"{stem}.odp")
+    return odp_path if exists(odp_path) else ""
+
+
+def _collect_face_map(root: ET.Element, ns: dict[str, str]) -> dict[str, str]:
+    face_map: dict[str, str] = {}
+    decls = root.find("office:font-face-decls", ns)
+    if decls is None:
+        return face_map
+    for ff in decls.findall("style:font-face", ns):
+        name_attr = ff.get("{urn:oasis:names:tc:opendocument:xmlns:style:1.0}name") or ff.get(
+            "style:name"
+        )
+        fam_attr = ff.get("{urn:oasis:names:tc:opendocument:xmlns:svg-compatible:1.0}font-family")
+        if not name_attr or not fam_attr:
+            continue
+        face_map[normalize_font_family_name(name_attr)] = normalize_font_family_name(fam_attr)
+    return face_map
+
+
+def _families_from_text_properties(
+    tp: ET.Element, ns: dict[str, str], face_map: dict[str, str]
+) -> set[str]:
+    fams: set[str] = set()
+    # Inspect current node for direct font-family
+    fam_attr = tp.get("{urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0}font-family")
+    if fam_attr:
+        fams.update(_split_odf_family_list(fam_attr))
+    # Inspect font-name aliases on current node
+    for key in (
+        "{urn:oasis:names:tc:opendocument:xmlns:style:1.0}font-name",
+        "style:font-name",
+        "style:font-name-asian",
+        "style:font-name-complex",
+    ):
+        val = tp.get(key)
+        if val:
+            norm_val = normalize_font_family_name(val)
+            mapped = face_map.get(norm_val)
+            if mapped:
+                fams.add(normalize_font_family_name(mapped))
+            else:
+                fams.add(norm_val)
+    # Some styles nest text-properties under paragraph-properties or default-style blocks
+    if not fams:
+        nested = None
+        # paragraph-properties/text-properties
+        pp = tp.find("style:paragraph-properties", ns)
+        if pp is not None:
+            nested = pp.find("style:text-properties", ns)
+        if nested is None:
+            # When tp is actually the style:style node, try finding child text-properties directly
+            nested = tp.find("style:text-properties", ns)
+        if nested is not None and nested is not tp:
+            fams.update(_families_from_text_properties(nested, ns, face_map))
+    return fams
+
+
+def _extract_styles_from_container(
+    container: ET.Element | None, ns: dict[str, str], face_map: dict[str, str]
+) -> tuple[dict[str, set[str]], set[str]]:
+    styles: dict[str, set[str]] = {}
+    defaults: set[str] = set()
+    if container is None:
+        return styles, defaults
+    for st in container.findall("style:style", ns):
+        name = st.get("{urn:oasis:names:tc:opendocument:xmlns:style:1.0}name") or st.get(
+            "style:name"
+        )
+        if not name:
+            continue
+        fams = _families_from_text_properties(
+            _or_dummy(st.find("style:text-properties", ns)), ns, face_map
+        )
+        if fams:
+            styles[name] = fams
+    for ds in container.findall("style:default-style", ns):
+        defaults.update(
+            _families_from_text_properties(
+                _or_dummy(ds.find("style:text-properties", ns)), ns, face_map
+            )
+        )
+    return styles, defaults
+
+
+def _build_style_map(
+    content: ET.Element,
+    styles_root: ET.Element | None,
+    ns: dict[str, str],
+    face_map: dict[str, str],
+) -> tuple[dict[str, set[str]], set[str]]:
+    style_map: dict[str, set[str]] = {}
+    default_fams: set[str] = set()
+    auto_styles = content.find("office:automatic-styles", ns)
+    styles_part, defaults_part = _extract_styles_from_container(auto_styles, ns, face_map)
+    style_map.update(styles_part)
+    default_fams.update(defaults_part)
+    if styles_root is not None:
+        # Also parse automatic-styles within styles.xml (document-styles)
+        styles_auto = styles_root.find("office:automatic-styles", ns)
+        styles_part, defaults_part = _extract_styles_from_container(styles_auto, ns, face_map)
+        for k, v in styles_part.items():
+            if k not in style_map:
+                style_map[k] = v
+        default_fams.update(defaults_part)
+        common_styles = styles_root.find("office:styles", ns)
+        styles_part, defaults_part = _extract_styles_from_container(common_styles, ns, face_map)
+        for k, v in styles_part.items():
+            if k not in style_map:
+                style_map[k] = v
+        default_fams.update(defaults_part)
+        # top-level default-style under styles_root
+        for ds in styles_root.findall("style:default-style", ns):
+            default_fams.update(
+                _families_from_text_properties(
+                    _or_dummy(ds.find("style:text-properties", ns)), ns, face_map
+                )
+            )
+        # Fallback: include any remaining style:style definitions anywhere in styles.xml
+        for st in styles_root.findall(".//style:style", ns):
+            name = st.get("{urn:oasis:names:tc:opendocument:xmlns:style:1.0}name") or st.get(
+                "style:name"
+            )
+            if not name or name in style_map:
+                continue
+            fams = _families_from_text_properties(
+                _or_dummy(st.find("style:text-properties", ns)), ns, face_map
+            )
+            if fams:
+                style_map[name] = fams
+    # also check top-level default-style in content root
+    for ds in content.findall("style:default-style", ns):
+        default_fams.update(
+            _families_from_text_properties(
+                _or_dummy(ds.find("style:text-properties", ns)), ns, face_map
+            )
+        )
+    # Fallback: include any remaining style:style definitions anywhere in content.xml
+    for st in content.findall(".//style:style", ns):
+        name = st.get("{urn:oasis:names:tc:opendocument:xmlns:style:1.0}name") or st.get(
+            "style:name"
+        )
+        if not name or name in style_map:
+            continue
+        fams = _families_from_text_properties(
+            _or_dummy(st.find("style:text-properties", ns)), ns, face_map
+        )
+        if fams:
+            style_map[name] = fams
+    return style_map, default_fams
+
+
+def _lookup_style_families(
+    style_name: str, ns: dict[str, str], face_map: dict[str, str], roots: list[ET.Element | None]
+) -> set[str]:
+    fams: set[str] = set()
+    if not style_name:
+        return fams
+    visited: set[str] = set()
+
+    def _resolve(name: str) -> None:
+        if not name or name in visited:
+            return
+        visited.add(name)
+        for root in roots:
+            if root is None:
+                continue
+            node = root.find(f".//style:style[@style:name='{name}']", ns)
+            if node is None:
+                node = root.find(f".//style:style[@{{{ns['style']}}}name='{name}']", ns)
+            if node is None:
+                continue
+            fams.update(
+                _families_from_text_properties(
+                    _or_dummy(node.find("style:text-properties", ns)), ns, face_map
+                )
+            )
+            # Follow parent style chain if present
+            parent = node.get(
+                "{urn:oasis:names:tc:opendocument:xmlns:style:1.0}parent-style-name"
+            ) or node.get("style:parent-style-name")
+            if parent:
+                _resolve(parent)
+
+    _resolve(style_name)
+    return fams
+
+
+def _collect_slide_families(
+    page: ET.Element,
+    ns: dict[str, str],
+    style_map: dict[str, set[str]],
+    face_map: dict[str, str],
+    roots: list[ET.Element | None],
+    text_style_map: dict[str, set[str]] | None = None,
+) -> set[str]:
+    slide_fams: set[str] = set()
+    for el in page.iter():
+        fam_attr = el.get(
+            "{urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0}font-family"
+        )
+        if fam_attr:
+            slide_fams.update(_split_odf_family_list(fam_attr))
+        for attr in (
+            "{urn:oasis:names:tc:opendocument:xmlns:text:1.0}style-name",
+            "text:style-name",
+            "{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}text-style-name",
+            "draw:text-style-name",
+            "draw:style-name",
+            "presentation:style-name",
+        ):
+            style_name = el.get(attr)
+            if not style_name:
+                continue
+            resolved_fams: set[str] = set()
+            if style_name in style_map:
+                resolved_fams.update(style_map[style_name])
+            if not resolved_fams:
+                # Fallback: resolve on the fly from XML if not present in prebuilt style_map
+                resolved_fams.update(_lookup_style_families(style_name, ns, face_map, roots))
+            if not resolved_fams and text_style_map and style_name in text_style_map:
+                resolved_fams.update(text_style_map[style_name])
+            if resolved_fams:
+                slide_fams.update(resolved_fams)
+    return slide_fams
+
+
+def _build_style_map_text(xml_text: str) -> dict[str, set[str]]:
+    # Best-effort textual extraction for cases missed by XML namespace lookups
+    # Finds style:style name="X" blocks and extracts fo:font-family and style:font-name attributes
+    style_map: dict[str, set[str]] = {}
+    # Non-greedy match of a style:style block
+    for m in re.finditer(
+        r"<style:style[^>]*?\bstyle:name=\"([^\"]+)\"[\s\S]*?(?:</style:style>)",
+        xml_text,
+        flags=re.IGNORECASE,
+    ):
+        name = m.group(1).strip()
+        block = m.group(0)
+        fams: set[str] = set()
+        # fo:font-family may be a comma list
+        mff = re.search(r"fo:font-family=\"([^\"]+)\"", block, flags=re.IGNORECASE)
+        if mff:
+            for f in _split_odf_family_list(mff.group(1)):
+                fams.add(f)
+        # style:font-name may be a face alias; treat as family directly if present
+        mfn = re.search(r"style:font-name=\"([^\"]+)\"", block, flags=re.IGNORECASE)
+        if mfn:
+            fams.add(normalize_font_family_name(mfn.group(1)))
+        if fams:
+            style_map[name] = fams
+    return style_map
+
+
+def _extract_slide_families_from_odp(odp_path: str) -> dict[int, set[str]]:
+    ns = {
+        "office": "urn:oasis:names:tc:opendocument:xmlns:office:1.0",
+        "style": "urn:oasis:names:tc:opendocument:xmlns:style:1.0",
+        "fo": "urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0",
+        "draw": "urn:oasis:names:tc:opendocument:xmlns:drawing:1.0",
+        "text": "urn:oasis:names:tc:opendocument:xmlns:text:1.0",
+    }
+    by_slide: dict[int, set[str]] = {}
+    with ZipFile(odp_path, "r") as zf:
+        content_bytes = zf.read("content.xml")
+        styles_bytes = zf.read("styles.xml") if "styles.xml" in zf.namelist() else None
+        content = ET.fromstring(content_bytes)
+        styles_root = ET.fromstring(styles_bytes) if styles_bytes is not None else None
+        styles_text = (
+            styles_bytes.decode("utf-8", errors="ignore") if styles_bytes is not None else ""
+        )
+
+        face_map: dict[str, str] = {}
+        face_map.update(_collect_face_map(content, ns))
+        if styles_root is not None:
+            face_map.update(_collect_face_map(styles_root, ns))
+
+        style_map, default_fams = _build_style_map(content, styles_root, ns, face_map)
+        # Augment style_map with textual parsing fallback (helps with tricky namespace emissions)
+        text_style_map: dict[str, set[str]] = {}
+        if styles_text:
+            text_style_map = _build_style_map_text(styles_text)
+            for k, v in text_style_map.items():
+                if k not in style_map:
+                    style_map[k] = v
+
+        master_map: dict[str, set[str]] = _build_master_page_map(styles_root, ns, style_map)
+
+        pres = content.find("office:body", ns)
+        if pres is not None:
+            pres = pres.find("office:presentation", ns)
+        if pres is None:
+            return {}
+        pages = pres.findall("draw:page", ns)
+        global_fams: set[str] = set()
+        for idx, page in enumerate(pages, start=1):
+            slide_fams = _collect_slide_families(
+                page, ns, style_map, face_map, [content, styles_root], text_style_map
+            )
+            mp_name = page.get(
+                "{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}master-page-name"
+            ) or page.get("draw:master-page-name")
+            if mp_name and mp_name in master_map:
+                slide_fams.update(master_map[mp_name])
+            # If theme placeholders like +mn lt are present, augment with defaults
+            if any(f.startswith("+") for f in slide_fams) and default_fams:
+                slide_fams.update(default_fams)
+            if not slide_fams and default_fams:
+                slide_fams.update(default_fams)
+            expanded: set[str] = set()
+            for f in slide_fams:
+                base, _ = parse_font_family_base_and_styles(f)
+                expanded.add(f)
+                expanded.add(base)
+                expanded.add(base.replace(" ", ""))
+            by_slide[idx] = expanded
+            global_fams.update(expanded)
+        # As a last resort, use global families
+        if global_fams:
+            for idx in list(by_slide.keys()):
+                if not by_slide[idx]:
+                    by_slide[idx] = set(global_fams)
+                elif all(f.startswith("+") for f in by_slide[idx]):
+                    by_slide[idx].update(global_fams)
+    return by_slide
+
+
+def _build_master_page_map(
+    styles_root: ET.Element | None, ns: dict[str, str], style_map: dict[str, set[str]]
+) -> dict[str, set[str]]:
+    master_map: dict[str, set[str]] = {}
+    if styles_root is None:
+        return master_map
+    master_styles = styles_root.find("office:master-styles", ns)
+    if master_styles is None:
+        return master_map
+    for mp in master_styles.findall("draw:master-page", ns):
+        mname = mp.get("{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}name") or mp.get(
+            "draw:name"
+        )
+        if not mname:
+            continue
+        fams: set[str] = set()
+        for el in mp.iter():
+            fam_attr = el.get(
+                "{urn:oasis:names:tc:opendocument:xmlns:xsl-fo-compatible:1.0}font-family"
+            )
+            if fam_attr:
+                fams.update(_split_odf_family_list(fam_attr))
+            for attr in (
+                "{urn:oasis:names:tc:opendocument:xmlns:text:1.0}style-name",
+                "text:style-name",
+                "{urn:oasis:names:tc:opendocument:xmlns:drawing:1.0}text-style-name",
+                "draw:text-style-name",
+                "draw:style-name",
+                "presentation:style-name",
+            ):
+                sname = el.get(attr)
+                if sname and sname in style_map:
+                    fams.update(style_map[sname])
+        if fams:
+            expanded: set[str] = set()
+            for f in fams:
+                base, _ = parse_font_family_base_and_styles(f)
+                expanded.add(f)
+                expanded.add(base)
+                expanded.add(base.replace(" ", ""))
+            master_map[mname] = expanded
+    return master_map
+
+
+def detect_missing_fonts_odp(pptx_path: str) -> tuple[set[str], dict[int, list[str]]]:
+    pptx_path = abspath(pptx_path)
+    used = extract_used_fonts_from_pptx(pptx_path)
+    with tempfile.TemporaryDirectory(prefix="soffice_profile_") as prof:
+        with tempfile.TemporaryDirectory(prefix="soffice_convert_") as out:
+            stem = splitext(basename(pptx_path))[0]
+            odp_path = _export_to_odp(pptx_path, prof, out, stem)
+            if not odp_path:
+                return set(), {}
+            slide_fams = _extract_slide_families_from_odp(odp_path)
+
+    missing_overall: set[str] = set()
+    missing_by_slide: dict[int, list[str]] = {}
+    syn_map = _build_fc_synonym_map()
+    for slide_num, req_fams in used.items():
+        odp_fams = slide_fams.get(slide_num, set())
+        slide_missing: list[str] = []
+        for req in req_fams:
+            fam_base, _ = parse_font_family_base_and_styles(req)
+            # Accept fontconfig-resolved aliases and no-space variants for the requested base family
+            acceptable: set[str] = _expand_via_fontconfig(fam_base)
+            # Determine if any acceptable alias is actually installed on system
+            installed = any(alias in syn_map for alias in acceptable)
+            # Missing if not installed at all, or if installed but not resolved in ODP families
+            if (not installed) or ((req not in odp_fams) and not (acceptable & odp_fams)):
+                slide_missing.append(req)
+                missing_overall.add(req)
+        if slide_missing:
+            missing_by_slide[slide_num] = sorted(slide_missing)
+    return missing_overall, missing_by_slide
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Detect missing/substituted fonts for a PPTX by converting to ODP and inspecting resolved families."
+        )
+    )
+    parser.add_argument("pptx_path", help="Path to .pptx file")
+    parser.add_argument(
+        "--json", dest="output_json", action="store_true", default=False, help="Emit JSON output"
+    )
+    parser.add_argument(
+        "--include-missing",
+        dest="include_missing",
+        action="store_true",
+        default=True,
+        help="Include missing category",
+    )
+    parser.add_argument(
+        "--include-substituted",
+        dest="include_substituted",
+        action="store_true",
+        default=True,
+        help="Include substituted category",
+    )
+    args = parser.parse_args()
+
+    pptx_path = abspath(expanduser(args.pptx_path))
+    used = extract_used_fonts_from_pptx(pptx_path)
+    # Only build ODP families if we need to report substitutions
+    slide_fams: dict[int, set[str]] = {}
+    odp_available = False
+    if args.include_substituted:
+        with tempfile.TemporaryDirectory(prefix="soffice_profile_") as prof:
+            with tempfile.TemporaryDirectory(prefix="soffice_convert_") as out:
+                stem = splitext(basename(pptx_path))[0]
+                odp_path = _export_to_odp(pptx_path, prof, out, stem)
+                if odp_path:
+                    slide_fams = _extract_slide_families_from_odp(odp_path)
+                    odp_available = True
+
+    syn_map = _build_fc_synonym_map()
+    font_missing_by_slide: dict[int, list[str]] = {}
+    font_substituted_by_slide: dict[int, list[str]] = {}
+    for slide_num, req_fams in used.items():
+        if args.include_substituted and odp_available:
+            odp_fams = slide_fams.get(slide_num, set())
+        else:
+            odp_fams = set()
+        miss_missing: list[str] = []
+        miss_sub: list[str] = []
+        for req in req_fams:
+            fam_base, _ = parse_font_family_base_and_styles(req)
+            acceptable: set[str] = _expand_via_fontconfig(fam_base)
+            installed = any(alias in syn_map for alias in acceptable)
+            if args.include_missing and not installed:
+                miss_missing.append(req)
+            if (
+                args.include_substituted
+                and odp_available
+                and installed
+                and (req not in odp_fams)
+                and not (acceptable & odp_fams)
+            ):
+                miss_sub.append(req)
+        if miss_missing:
+            font_missing_by_slide[slide_num] = sorted(miss_missing)
+        if miss_sub:
+            font_substituted_by_slide[slide_num] = sorted(miss_sub)
+
+    font_missing_overall: set[str] = (
+        set().union(*font_missing_by_slide.values()) if font_missing_by_slide else set()
+    )
+    font_substituted_overall: set[str] = (
+        set().union(*font_substituted_by_slide.values()) if font_substituted_by_slide else set()
+    )
+
+    if args.output_json:
+        payload: dict[str, object] = {}
+        if args.include_missing:
+            payload["font_missing_overall"] = sorted(font_missing_overall)
+            payload["font_missing_by_slide"] = {str(k): v for k, v in font_missing_by_slide.items()}
+        if args.include_substituted:
+            payload["font_substituted_overall"] = sorted(font_substituted_overall)
+            payload["font_substituted_by_slide"] = {
+                str(k): v for k, v in font_substituted_by_slide.items()
+            }
+        print(json.dumps(payload))
+    else:
+        any_missing = args.include_missing and bool(font_missing_overall)
+        any_sub = args.include_substituted and bool(font_substituted_overall)
+        if any_missing or any_sub:
+            if any_missing:
+                print("Fonts missing (not installed):")
+                print(", ".join(sorted(font_missing_overall)))
+                for slide_num in sorted(font_missing_by_slide.keys()):
+                    print(f"Slide {slide_num} missing: ", end="")
+                    print(", ".join(font_missing_by_slide[slide_num]))
+            if any_sub:
+                print("Fonts substituted (installed but substituted during rendering):")
+                print(", ".join(sorted(font_substituted_overall)))
+                for slide_num in sorted(font_substituted_by_slide.keys()):
+                    print(f"Slide {slide_num} substituted: ", end="")
+                    print(", ".join(font_substituted_by_slide[slide_num]))
+        else:
+            print("No font issues detected.")
+
+
+if __name__ == "__main__":
+    main()