Skip to content

siril9/presentation-skill / plugins/presentation-skill/skills/presentation-skill

presentation-skill

Flagged

Build, edit, redesign, render, and verify content-led, structurally diverse, clean, editable, reproducible PowerPoint `.pptx` decks. Use for scientific, lab, clinical, consulting, board, investor, editorial, policy, and operational presentations where alignment, readability, contrast, and balanced density matter.

FileKindSize
DESIGN.mdmarkdown13.7 KB
DISCOVERY.mdmarkdown6.6 KB
LICENSEother1.0 KB
SKILL.mdskill md14.7 KB
agents/discovery.jsonconfig8.2 KB
agents/openai.yamlconfig309 B
examples/outline.jsonconfig3.4 KB
package-lock.jsonmanifest22.0 KB
package.jsonmanifest1.8 KB
references/agent_picker.mdmarkdown1.9 KB
references/alignment_and_coherence.mdmarkdown2.1 KB
references/assets/visual_references/editorial_chart.jpgbinary53.2 KB
references/assets/visual_references/editorial_decision.jpgbinary100.4 KB
references/assets/visual_references/editorial_focal_metric.jpgbinary45.4 KB
references/assets/visual_references/editorial_pilot.jpgbinary62.0 KB
references/assets/visual_references/lab-native-method.jpgbinary53.9 KB
references/assets/visual_references/lab-residual-panels.jpgbinary64.8 KB
references/assets/visual_references/lab_cover.jpgbinary39.8 KB
references/assets/visual_references/lab_endpoints.jpgbinary70.8 KB
references/assets/visual_references/lab_evidence_gate.jpgbinary67.3 KB
references/assets/visual_references/lab_trend.jpgbinary60.5 KB
references/assets/visual_references/operations_handoffs.jpgbinary87.2 KB
references/assets/visual_references/operations_owner_register.jpgbinary87.2 KB
references/assets/visual_references/operations_queue.jpgbinary81.8 KB
references/assets/visual_references/operations_tradeoff.jpgbinary99.9 KB
references/benchmark_protocol.mdmarkdown12.1 KB
references/codex_guardrails.mdmarkdown10.3 KB
references/composition_grammar_catalog.mdmarkdown4.0 KB
references/deck_creation.mdmarkdown1.4 KB
references/deck_workspace_mode.mdmarkdown34.4 KB
references/design_philosophy.mdmarkdown5.5 KB
references/dynamic_design_and_subagents.mdmarkdown12.3 KB
references/editing.mdmarkdown12.4 KB
references/external_best_practices.mdmarkdown1.7 KB
references/large_style_corpus_sources.jsonconfig22.7 KB
references/model_adaptive_workflow.mdmarkdown6.6 KB
references/outline_schema.mdmarkdown44.8 KB
references/planning_schema.mdmarkdown54.8 KB
references/pptxgenjs.mdmarkdown7.6 KB
references/preview_extension.mdmarkdown1.7 KB
references/reference_script_patterns.mdmarkdown13.5 KB
references/renderer_role_contracts_v2.jsonconfig38.2 KB
references/reproducible_workflow.mdmarkdown5.1 KB
references/speed_and_rendering.mdmarkdown4.6 KB
references/style_grammar_index.jsonconfig364.2 KB
references/style_inspiration_corpus.jsonconfig32.9 KB
references/style_reference_catalog.mdmarkdown23.9 KB
references/style_reference_sources.jsonconfig35.8 KB
references/style_token_atlas.jsonconfig174.7 KB
references/subagent_patterns.mdmarkdown10.2 KB
references/visual_qa_prompt.mdmarkdown4.9 KB
references/visual_reference_catalog.jsonconfig26.6 KB
references/visual_reference_catalog.mdmarkdown6.0 KB
schemas/deck_ir.schema.jsonconfig9.5 KB
schemas/renderer_capabilities_v2.jsonconfig701 B
scripts/accessibility_qa.pyscript24.8 KB
scripts/action_registry.pyscript12.5 KB
scripts/add_slide.pyscript8.6 KB
scripts/advance_delivery.pyscript88.2 KB
scripts/advance_workspace.pyscript150.3 KB
scripts/apply_artifact_manifest_bindings.pyscript54.1 KB
scripts/apply_atom_composition.pyscript8.2 KB
scripts/apply_data_analysis_handoff.pyscript67.0 KB
scripts/apply_deck_intake_answers.pyscript35.6 KB
scripts/apply_design_contract.pyscript71.7 KB
scripts/apply_outline_authoring_handoff.pyscript23.7 KB
scripts/apply_pptx_style_fragment.pyscript19.7 KB
scripts/asset_stage.pyscript24.6 KB
scripts/audition_styles.pyscript8.7 KB
scripts/benchmark_decks.pyexecutablescript45.4 KB
scripts/build_deck.pyexecutablescript173.6 KB
scripts/build_deck_pptxgenjs.jsexecutablescript72.7 KB
scripts/build_large_style_corpus_contact_sheets.pyscript18.1 KB
scripts/build_workspace.pyscript126.2 KB
scripts/clean_unpacked.pyscript12.9 KB
scripts/compact_source_footers.pyscript17.8 KB
scripts/composition_grammar_catalog.pyscript30.3 KB
scripts/deck_benchmark.pyscript71.1 KB
scripts/deck_intake.pyscript6.9 KB
scripts/deck_ir.pyscript47.5 KB
scripts/design_catalog_selector.pyscript17.4 KB
scripts/design_rules_qa.pyscript24.8 KB
scripts/design_tokens.pyscript20.3 KB
scripts/edit_deck.pyscript8.4 KB
scripts/emit_content_research.pyscript4.6 KB
scripts/emit_data_analysis_prompt.pyscript30.1 KB
scripts/emit_deck_intake_prompt.pyexecutablescript19.9 KB
scripts/emit_deck_start_packet.pyscript97.1 KB
scripts/emit_design_contract_prompt.pyscript66.2 KB
scripts/emit_outline_authoring_prompt.pyscript35.4 KB
scripts/emit_outline_critique.pyscript11.6 KB
scripts/emit_style_content_router.pyscript49.6 KB
scripts/extract_outline.pyexecutablescript4.1 KB
scripts/extract_pptx_style.pyscript33.2 KB
scripts/fetch_wikimedia_cc.pyscript8.6 KB
scripts/finalize_quick_deck.pyscript17.6 KB
scripts/generate_openai_image.pyscript5.6 KB
scripts/init_deck_workspace.pyscript74.4 KB
scripts/inspect_artifact_manifest.pyscript29.8 KB
scripts/inventory.pyscript10.6 KB
scripts/iterate_deck.pyexecutablescript10.2 KB
scripts/layout_lint.pyscript40.4 KB
scripts/log_skill_telemetry.pyscript6.9 KB
scripts/model_adaptive_workflow.pyscript28.0 KB
scripts/office_package_hash.pyscript1.6 KB
scripts/pack_pptx.pyscript5.7 KB
scripts/palette_from_topic.pyscript4.1 KB
scripts/plan_research_assets.pyscript13.1 KB
scripts/preflight.pyscript136.9 KB
scripts/present.pyscript9.6 KB
scripts/python_runtime.pyscript787 B
scripts/qa_gate.pyexecutablescript27.4 KB
scripts/qa_visual_gate.pyexecutablescript8.5 KB
scripts/reference_deck.pyscript12.7 KB
scripts/render_cache.pyscript3.9 KB
scripts/render_mermaid.pyscript8.9 KB
scripts/render_slides.pyexecutablescript19.4 KB
scripts/repair_packet.pyscript14.7 KB
scripts/report_delivery_readiness.pyscript107.6 KB
scripts/report_workspace_readiness.pyscript244.6 KB
scripts/requirements-runtime.txtmarkdown472 B
scripts/role_layout_contracts.pyscript10.6 KB
scripts/runtime_doctor.pyscript6.3 KB
scripts/scaffold_figure_artifacts.pyscript92.3 KB
scripts/source_fidelity.pyscript30.5 KB
scripts/structural_diversity_v2.pyscript32.5 KB
scripts/style_atom_router.pyscript14.5 KB
scripts/style_inspiration_corpus.pyscript15.1 KB
scripts/style_reference_catalog.pyscript142.8 KB
scripts/style_reference_sources.pyscript12.7 KB
scripts/style_treatment_profiles.pyscript26.0 KB
scripts/summarize_skill_log.pyscript7.0 KB
scripts/taste_grammar_catalog.pyscript27.0 KB
scripts/test_structural_diversity_v2.pyscript4.9 KB
scripts/text_fit.pyscript23.6 KB
scripts/thumbnail.pyscript9.2 KB
scripts/trim_image_whitespace.pyexecutablescript5.4 KB
scripts/unpack_pptx.pyscript8.3 KB
scripts/upgrade_renderer_role_contracts_v2.pyscript7.3 KB
scripts/validate_planning.pyscript169.2 KB
scripts/verify_narration.pyscript10.6 KB
scripts/visual_qa.pyscript7.7 KB
scripts/visual_review.pyscript41.1 KB
scripts/visual_review_receipt.pyscript8.3 KB
scripts/workflow_atom_context.pyscript17.3 KB
templates/pptxgenjs/README.mdmarkdown8.4 KB
templates/pptxgenjs/presets.jsscript5.6 KB
templates/pptxgenjs/readable_role_layouts.jsscript17.5 KB
templates/pptxgenjs/render_plan.jsscript12.6 KB
templates/pptxgenjs/role_layout_contracts.jsscript4.7 KB
templates/pptxgenjs/slides.jsscript451.0 KB
templates/pptxgenjs/space_allocation.jsscript1.6 KB

scripts/build_deck.py

View on GitHub
#!/usr/bin/env python3
"""Build a styled PPTX deck from a structured JSON outline."""

from __future__ import annotations

import argparse
import csv
import json
import math
import re
import subprocess
import sys
import zlib
from copy import deepcopy
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Iterable

from pptx import Presentation
from pptx.chart.data import ChartData
from pptx.dml.color import RGBColor
from pptx.enum.chart import XL_CHART_TYPE, XL_LABEL_POSITION, XL_LEGEND_POSITION
from pptx.enum.shapes import MSO_CONNECTOR, MSO_SHAPE
from pptx.enum.text import MSO_ANCHOR, PP_ALIGN
from pptx.oxml.xmlchemy import OxmlElement
from pptx.util import Inches, Pt

from design_tokens import DEFAULT_FONT_PAIR_KEY, get_font_pair, get_style_preset

EMU_PER_INCH = 914400.0
EMOJI_PATTERN = re.compile(r"[\U0001F300-\U0001FAFF\u2600-\u27BF]")
RENDER_MODES = {"reliable", "express", "auto"}
EXPRESS_ALLOWED_SLIDE_TYPES = {"title", "section"}
EXPRESS_ALLOWED_VISUALS = {"hero", "timeline", "comparison"}
EXPRESS_ALLOWED_INTENTS = {"section", "process"}
DENSITY_VALUES = {"low", "medium", "high"}
EMOJI_MODES = {"none", "selective"}

PALETTE_LIBRARY: dict[str, dict[str, str]] = {
    "climate_coastal_v1": {
        "bg_primary": "ECFEFF",
        "bg_dark": "082F49",
        "surface": "FFFFFF",
        "text_primary": "0C4A6E",
        "text_muted": "155E75",
        "accent_primary": "0EA5E9",
        "accent_secondary": "14B8A6",
        "line": "BAE6FD",
    },
    "energy_sunset_v1": {
        "bg_primary": "F6F8F5",
        "bg_dark": "173B3F",
        "surface": "FFFFFF",
        "text_primary": "243133",
        "text_muted": "5F6F70",
        "accent_primary": "C65D3B",
        "accent_secondary": "2F7D76",
        "line": "D9DED8",
    },
    "enterprise_graphite_v1": {
        "bg_primary": "F8FAFC",
        "bg_dark": "111827",
        "surface": "FFFFFF",
        "text_primary": "111827",
        "text_muted": "4B5563",
        "accent_primary": "2563EB",
        "accent_secondary": "0891B2",
        "line": "D1D5DB",
    },
    "lab_monochrome_v1": {
        "bg_primary": "FFFFFF",
        "bg_dark": "171717",
        "surface": "FFFFFF",
        "text_primary": "171717",
        "text_muted": "525252",
        "accent_primary": "171717",
        "accent_secondary": "B42318",
        "line": "D4D4D4",
    },
    "journal_monochrome_v1": {
        "bg_primary": "FFFFFF",
        "bg_dark": "202020",
        "surface": "FFFFFF",
        "text_primary": "111111",
        "text_muted": "525252",
        "accent_primary": "111111",
        "accent_secondary": "315A74",
        "line": "D9D9D9",
    },
}

_STAGED_ASSET_LOOKUP: dict[str, dict[str, str]] = {}


TITLE_MOTIF_CHOICES = ("orbit", "stripe", "wave", "arc", "geometric")


@dataclass(frozen=True)
class DeckStyleConfig:
    font_pair: str = DEFAULT_FONT_PAIR_KEY
    palette_key: str = ""
    visual_density: str = "medium"
    emoji_mode: str = "none"
    title_motif: str = ""
    # When True, builder renders "<slide_index> / <total>" on the right
    # side of each slide's footer. Default off to avoid changing every
    # existing deck's footer treatment. Recommended for editorial-minimal
    # decks and any deck the user expects to read like a printed report.
    show_page_numbers: bool = False


@dataclass(frozen=True)
class ComplianceConfig:
    attribution_file: Path
    require_attribution: bool


@dataclass(frozen=True)
class BuildConfig:
    outline_dir: Path
    deck_style: DeckStyleConfig
    compliance: ComplianceConfig


@dataclass(frozen=True)
class RuntimePreset:
    name: str
    palette: dict[str, str]
    typography: Any
    layout: Any
    font_pair: dict[str, str]


def _default_attribution_file(outline_dir: Path) -> Path:
    return (outline_dir / "assets" / "attribution.csv").resolve()


def _as_str(value: Any, default: str = "") -> str:
    text = str(value or "").strip()
    return text if text else default


def _parse_deck_style(data: dict[str, Any]) -> DeckStyleConfig:
    raw = data.get("deck_style")
    if not isinstance(raw, dict):
        return DeckStyleConfig()
    font_pair = _as_str(raw.get("font_pair"), DEFAULT_FONT_PAIR_KEY).lower()
    palette_key = _as_str(raw.get("palette_key"), "").lower()
    visual_density = _as_str(raw.get("visual_density"), "medium").lower()
    if visual_density not in DENSITY_VALUES:
        visual_density = "medium"
    emoji_mode = _as_str(raw.get("emoji_mode"), "none").lower()
    if emoji_mode not in EMOJI_MODES:
        emoji_mode = "none"
    title_motif = _as_str(raw.get("title_motif"), "").lower()
    # Accept the sentinel "none" as an explicit opt-out (skips motif draw
    # entirely — useful when hero_image is the visual anchor).
    if title_motif and title_motif != "none" and title_motif not in TITLE_MOTIF_CHOICES:
        title_motif = ""
    show_page_numbers = bool(raw.get("show_page_numbers"))
    return DeckStyleConfig(
        font_pair=font_pair,
        palette_key=palette_key,
        visual_density=visual_density,
        emoji_mode=emoji_mode,
        title_motif=title_motif,
        show_page_numbers=show_page_numbers,
    )


def _resolve_path(raw_path: str, outline_dir: Path) -> Path:
    candidate = Path(raw_path).expanduser()
    if not candidate.is_absolute():
        candidate = outline_dir / candidate
    return candidate.resolve()


def _default_staged_manifest(outline_dir: Path) -> Path:
    return (outline_dir / "assets" / "staged" / "staged_manifest.json").resolve()


def _staged_asset_lookup(outline_dir: Path) -> dict[str, str]:
    manifest_path = _default_staged_manifest(outline_dir)
    cache_key = str(manifest_path)
    if cache_key in _STAGED_ASSET_LOOKUP:
        return _STAGED_ASSET_LOOKUP[cache_key]

    lookup: dict[str, str] = {}
    if manifest_path.exists():
        payload = json.loads(manifest_path.read_text(encoding="utf-8"))
        sections = (
            ("images", ("asset", "image")),
            ("backgrounds", ("asset", "background")),
            ("charts", ("asset", "chart")),
            ("generated_images", ("asset", "image", "generated")),
        )
        for section, prefixes in sections:
            entries = payload.get(section)
            if not isinstance(entries, list):
                continue
            for entry in entries:
                if not isinstance(entry, dict):
                    continue
                name = _as_str(entry.get("name"), "").lower()
                asset_path = _as_str(entry.get("path"), "")
                if not name or not asset_path:
                    continue
                for prefix in prefixes:
                    lookup[f"{prefix}:{name}"] = asset_path
    _STAGED_ASSET_LOOKUP[cache_key] = lookup
    return lookup


def _parse_compliance(data: dict[str, Any], outline_dir: Path) -> ComplianceConfig:
    raw = data.get("compliance")
    if not isinstance(raw, dict):
        return ComplianceConfig(
            attribution_file=_default_attribution_file(outline_dir),
            require_attribution=False,
        )
    attribution_raw = _as_str(raw.get("attribution_file"), "assets/attribution.csv")
    attribution_file = _resolve_path(attribution_raw, outline_dir)
    require_attribution = bool(raw.get("require_attribution", False))
    return ComplianceConfig(
        attribution_file=attribution_file,
        require_attribution=require_attribution,
    )


def _resolve_palette(base_palette: dict[str, str], palette_key: str) -> dict[str, str]:
    if not palette_key:
        return dict(base_palette)
    key = palette_key.strip().lower()
    override = PALETTE_LIBRARY.get(key)
    if not override:
        return dict(base_palette)
    merged = dict(base_palette)
    merged.update(override)
    return merged


def _resolve_asset_path(value: Any, outline_dir: Path) -> Path | None:
    raw = str(value or "").strip()
    if not raw:
        return None
    normalized = raw.lower()
    if normalized.startswith(("asset:", "image:", "background:", "chart:", "generated:")):
        staged_path = _staged_asset_lookup(outline_dir).get(normalized)
        if not staged_path:
            raise FileNotFoundError(
                f"Staged asset alias not found: {raw}. "
                f"Expected {_default_staged_manifest(outline_dir)}"
            )
        return _resolve_path(staged_path, outline_dir)
    if raw.lower().startswith(("http://", "https://")):
        return None
    return _resolve_path(raw, outline_dir)


# Cache: original_svg_path -> converted_png_path (or None if conversion failed).
_SVG_CONVERSION_CACHE: dict[str, Path | None] = {}
_SVG_WARNING_EMITTED = False


def _convert_svg_to_png(svg_path: Path) -> Path | None:
    """Convert an SVG icon to PNG via cairosvg if available.

    Returns the PNG path on success, or None if cairosvg is unavailable or
    conversion fails. Caches results per-session so we only warn once.
    """
    global _SVG_WARNING_EMITTED
    key = str(svg_path.resolve())
    if key in _SVG_CONVERSION_CACHE:
        return _SVG_CONVERSION_CACHE[key]
    try:
        import cairosvg  # type: ignore
    except ImportError:
        if not _SVG_WARNING_EMITTED:
            print(
                "[build_deck] cairosvg not installed; SVG icons will be skipped. "
                "Install cairosvg or provide PNG icons instead.",
                file=sys.stderr,
            )
            _SVG_WARNING_EMITTED = True
        _SVG_CONVERSION_CACHE[key] = None
        return None
    try:
        png_path = svg_path.with_suffix(".converted.png")
        cairosvg.svg2png(
            url=str(svg_path),
            write_to=str(png_path),
            output_width=256,
            output_height=256,
        )
        _SVG_CONVERSION_CACHE[key] = png_path
        return png_path
    except Exception as exc:  # pragma: no cover - defensive
        print(f"[build_deck] SVG conversion failed for {svg_path}: {exc}", file=sys.stderr)
        _SVG_CONVERSION_CACHE[key] = None
        return None


def _resolve_icon_path(value: Any, outline_dir: Path) -> Path | None:
    """Resolve an `assets.icons[]` entry to a concrete file path.

    Resolution order:
      1. Absolute path: use as-is if file exists.
      2. Relative path with extension (.png/.svg/.jpg): resolve against
         `<outline_dir>/assets/icons/` first, then against outline_dir.
      3. Bare name (no extension, no slash): resolve against
         `<outline_dir>/assets/icons/<name>.png`, then `.svg`, then `.jpg`.

    Returns None (with a stderr warning) if no file exists. Returns the
    resolved PNG path on success; SVGs are converted via cairosvg if
    available, otherwise skipped with a warning.
    """
    raw = str(value or "").strip()
    if not raw:
        return None

    icons_dir = (outline_dir / "assets" / "icons").resolve()
    candidate: Path | None = None
    expected_msg = ""

    if raw.startswith("/"):
        # Case 1: absolute path.
        candidate = Path(raw).expanduser()
        expected_msg = str(candidate)
        if not candidate.exists():
            print(
                f"[build_deck] icon not found: {raw}, expected at {expected_msg}",
                file=sys.stderr,
            )
            return None
    else:
        has_ext = Path(raw).suffix.lower() in {".png", ".svg", ".jpg", ".jpeg"}
        if has_ext or "/" in raw or "\\" in raw:
            # Case 2: relative path — try icons_dir first, then outline_dir.
            primary = (icons_dir / raw).resolve()
            fallback = (outline_dir / raw).resolve()
            if primary.exists():
                candidate = primary
            elif fallback.exists():
                candidate = fallback
            else:
                expected_msg = str(primary)
        else:
            # Case 3: bare name — try .png, .svg, .jpg in icons_dir.
            for ext in (".png", ".svg", ".jpg", ".jpeg"):
                probe = (icons_dir / f"{raw}{ext}").resolve()
                if probe.exists():
                    candidate = probe
                    break
            if candidate is None:
                expected_msg = str((icons_dir / f"{raw}.png").resolve())

    if candidate is None:
        print(
            f"[build_deck] icon not found: {raw}, expected at {expected_msg}",
            file=sys.stderr,
        )
        return None

    if candidate.suffix.lower() == ".svg":
        converted = _convert_svg_to_png(candidate)
        if converted is None:
            print(
                f"[build_deck] icon skipped (SVG, no cairosvg): {candidate}",
                file=sys.stderr,
            )
            return None
        return converted

    return candidate


def _add_icon(
    slide: Any,
    *,
    path: Path,
    x: float,
    y: float,
    size: float,
) -> None:
    """Add a square icon image to the slide at (x, y) with given size (inches)."""
    try:
        slide.shapes.add_picture(
            str(path),
            Inches(x),
            Inches(y),
            width=Inches(size),
            height=Inches(size),
        )
    except Exception as exc:  # pragma: no cover - defensive
        print(f"[build_deck] failed to render icon {path}: {exc}", file=sys.stderr)


def _sources_footer_text(spec: dict[str, Any]) -> str:
    raw_sources = spec.get("sources")
    if not isinstance(raw_sources, list):
        return ""
    parts: list[str] = []
    for item in raw_sources:
        if isinstance(item, dict):
            text = _as_str(
                item.get("label")
                or item.get("title")
                or item.get("source")
                or item.get("source_page")
                or item.get("url"),
                "",
            )
        else:
            text = _as_str(item, "")
        if text:
            parts.append(text)
    if not parts:
        return ""
    if len(parts) > 3:
        shown = parts[:3]
        return f"Sources: {'; '.join(shown)}; +{len(parts) - 3} more"
    return f"Sources: {'; '.join(parts)}"


def _slide_footer_text(spec: dict[str, Any]) -> str:
    footer = _as_str(spec.get("footer"), "")
    sources = _sources_footer_text(spec)
    if footer and sources:
        text = f"{footer} | {sources}"
    else:
        text = footer or sources
    text = text.strip()
    if len(text) <= 180:
        return text
    return text[:177].rstrip() + "..."


def _metadata_candidates(asset_path: Path) -> list[Path]:
    return [
        asset_path.with_suffix(".metadata.json"),
        Path(f"{asset_path}.metadata.json"),
    ]


def _has_asset_metadata(asset_path: Path) -> bool:
    return any(candidate.exists() for candidate in _metadata_candidates(asset_path))


def _is_external_heuristic(asset_path: Path) -> bool:
    lowered = str(asset_path).lower()
    return (
        "tmp_assets" in lowered
        or "wikimedia" in lowered
        or "commons.wikimedia.org" in lowered
    )


def _looks_like_emoji_policy_disabled(style_preset_name: str) -> bool:
    lowered = style_preset_name.lower()
    return "boardroom" in lowered or "data-heavy" in lowered


def _strip_emojis(text: str) -> str:
    return EMOJI_PATTERN.sub("", text or "").strip()


def _limit_emojis(text: str, max_count: int) -> str:
    if max_count <= 0:
        return _strip_emojis(text)
    remaining = max_count
    output: list[str] = []
    for char in text:
        if EMOJI_PATTERN.match(char):
            if remaining <= 0:
                continue
            remaining -= 1
        output.append(char)
    return "".join(output).strip()


def _apply_emoji_policy(
    spec: dict[str, Any],
    *,
    slide_type: str,
    preset_name: str,
    emoji_mode: str,
) -> dict[str, Any]:
    if emoji_mode == "none" or _looks_like_emoji_policy_disabled(preset_name):
        sanitized = deepcopy(spec)
        for key in ("title", "subtitle", "body", "footer", "caption", "message"):
            if key in sanitized:
                sanitized[key] = _strip_emojis(str(sanitized.get(key, "")))
        if isinstance(sanitized.get("bullets"), list):
            sanitized["bullets"] = [
                _strip_emojis(str(item if not isinstance(item, dict) else item.get("text", "")))
                if not isinstance(item, dict)
                else {**item, "text": _strip_emojis(str(item.get("text", "")))}
                for item in sanitized["bullets"]
            ]
        return sanitized

    informal = _as_str(spec.get("tone"), "").lower() == "informal"
    allow = slide_type in {"title", "section"} or informal
    sanitized = deepcopy(spec)
    if not allow:
        return _apply_emoji_policy(
            sanitized,
            slide_type=slide_type,
            preset_name=preset_name,
            emoji_mode="none",
        )

    title = _as_str(sanitized.get("title"), "")
    sanitized["title"] = _limit_emojis(title, 1)
    remaining = 2 - len(EMOJI_PATTERN.findall(sanitized["title"]))
    remaining = max(0, remaining)
    for key in ("subtitle", "body", "footer", "caption", "message"):
        if key in sanitized:
            sanitized[key] = _limit_emojis(_as_str(sanitized.get(key), ""), remaining)
            remaining = max(0, remaining - len(EMOJI_PATTERN.findall(sanitized[key])))
    if isinstance(sanitized.get("bullets"), list):
        normalized_bullets: list[Any] = []
        for bullet in sanitized["bullets"]:
            if isinstance(bullet, dict):
                text = _limit_emojis(_as_str(bullet.get("text"), ""), remaining)
                remaining = max(0, remaining - len(EMOJI_PATTERN.findall(text)))
                normalized_bullets.append({**bullet, "text": text})
            else:
                text = _limit_emojis(_as_str(bullet, ""), remaining)
                remaining = max(0, remaining - len(EMOJI_PATTERN.findall(text)))
                normalized_bullets.append(text)
        sanitized["bullets"] = normalized_bullets
    return sanitized


def _coerce_render_mode(value: Any) -> str:
    # Backward compatibility and reliability-first default:
    # if render_mode is omitted, stay on deterministic reliable path.
    mode = _as_str(value, "reliable").lower()
    if mode not in RENDER_MODES:
        return "reliable"
    return mode


def _slide_density_level(spec: dict[str, Any]) -> str:
    bullets = spec.get("bullets")
    bullet_count = len(bullets) if isinstance(bullets, list) else 0
    paragraphs = spec.get("paragraphs")
    para_count = len(paragraphs) if isinstance(paragraphs, list) else 0
    cards = spec.get("cards")
    card_count = len(cards) if isinstance(cards, list) else 0
    total = bullet_count + para_count + card_count
    if total >= 9:
        return "high"
    if total <= 3:
        return "low"
    return "medium"


def _express_supported(spec: dict[str, Any], slide_type: str) -> bool:
    visual_intent = _as_str(spec.get("visual_intent"), "").lower()
    slide_intent = _as_str(spec.get("slide_intent"), "").lower()
    variant = _as_str(spec.get("variant"), "").lower()
    assets = _slide_assets(spec)
    if visual_intent == "flow" and not _as_str(assets.get("diagram"), ""):
        return False
    if slide_type in EXPRESS_ALLOWED_SLIDE_TYPES:
        return True
    if visual_intent in EXPRESS_ALLOWED_VISUALS:
        return True
    if slide_intent in EXPRESS_ALLOWED_INTENTS:
        return True
    if variant == "timeline":
        return True
    return variant == "split" and visual_intent == "comparison"


def _resolve_render_mode(
    spec: dict[str, Any],
    *,
    slide_type: str,
    deck_density: str,
) -> str:
    requested = _coerce_render_mode(spec.get("render_mode"))
    if requested == "reliable":
        return "reliable"
    supported = _express_supported(spec, slide_type)
    if requested == "express":
        return "express" if supported else "reliable"
    # auto mode
    intent = _as_str(spec.get("slide_intent"), "").lower()
    visual_intent = _as_str(spec.get("visual_intent"), "").lower()
    density = _slide_density_level(spec)
    if intent in {"section", "process"} or visual_intent in {"hero", "timeline", "comparison"}:
        if density != "high" and deck_density != "high" and supported:
            return "express"
    return "reliable"


def _collect_asset_paths(spec: dict[str, Any], outline_dir: Path) -> list[Path]:
    candidates: list[Path] = []
    bg = _resolve_asset_path(spec.get("background_image"), outline_dir)
    if bg:
        candidates.append(bg)
    thumbs = spec.get("thumbnails")
    if isinstance(thumbs, list):
        for item in thumbs:
            thumb = _resolve_asset_path(item, outline_dir)
            if thumb:
                candidates.append(thumb)
    assets = spec.get("assets")
    if isinstance(assets, dict):
        for key in ("hero_image", "diagram", "logo", "chart_data", "chart"):
            path = _resolve_asset_path(assets.get(key), outline_dir)
            if path:
                candidates.append(path)
        logos = assets.get("logos")
        if isinstance(logos, list):
            for item in logos:
                path = _resolve_asset_path(item, outline_dir)
                if path:
                    candidates.append(path)
    return candidates


def _read_attribution_rows(path: Path) -> list[dict[str, str]]:
    rows: list[dict[str, str]] = []
    if not path.exists():
        return rows
    with path.open("r", encoding="utf-8", newline="") as handle:
        reader = csv.DictReader(handle)
        for row in reader:
            rows.append({k: str(v or "").strip() for k, v in row.items()})
    return rows


def _attribution_contains(asset_path: Path, rows: list[dict[str, str]]) -> bool:
    basename = asset_path.name
    for row in rows:
        if basename in row.values() or str(asset_path) in row.values():
            return True
    return False


def _enforce_compliance(data: dict[str, Any], config: BuildConfig) -> None:
    slides = data.get("slides")
    if not isinstance(slides, list):
        return

    all_assets: list[Path] = []
    remote_refs: list[str] = []
    external_assets: list[Path] = []
    flagged_without_metadata: list[Path] = []

    for item in slides:
        if not isinstance(item, dict):
            continue
        assets = _collect_asset_paths(item, config.outline_dir)
        slide_assets = item.get("assets") if isinstance(item.get("assets"), dict) else {}
        required_assets: set[Path] = set()
        for key in ("hero_image", "diagram", "logo", "chart_data", "chart"):
            candidate = _resolve_asset_path(slide_assets.get(key), config.outline_dir)
            if candidate:
                required_assets.add(candidate)
        logos_block = slide_assets.get("logos")
        if isinstance(logos_block, list):
            for entry in logos_block:
                candidate = _resolve_asset_path(entry, config.outline_dir)
                if candidate:
                    required_assets.add(candidate)
        diagram_target = _resolve_asset_path(slide_assets.get("diagram"), config.outline_dir)
        mermaid_source = _resolve_asset_path(
            slide_assets.get("mermaid") or slide_assets.get("mermaid_source"),
            config.outline_dir,
        )
        all_assets.extend(assets)
        for asset in assets:
            if not asset.exists():
                if asset not in required_assets:
                    continue
                if (
                    diagram_target
                    and asset == diagram_target
                    and mermaid_source
                    and mermaid_source.exists()
                ):
                    # Flow diagrams can be generated from Mermaid at render time.
                    continue
                raise FileNotFoundError(f"Asset not found: {asset}")
            if _has_asset_metadata(asset):
                external_assets.append(asset)
            elif _is_external_heuristic(asset):
                flagged_without_metadata.append(asset)

        for raw in (item.get("background_image"),):
            raw_text = str(raw or "").strip().lower()
            if raw_text.startswith(("http://", "https://")):
                remote_refs.append(str(raw))
        if isinstance(slide_assets, dict):
            for key in ("hero_image", "diagram", "logo", "chart_data", "chart"):
                raw_text = str(slide_assets.get(key, "")).strip().lower()
                if raw_text.startswith(("http://", "https://")):
                    remote_refs.append(str(slide_assets.get(key)))
            logos = slide_assets.get("logos")
            if isinstance(logos, list):
                for entry in logos:
                    raw_text = str(entry or "").strip().lower()
                    if raw_text.startswith(("http://", "https://")):
                        remote_refs.append(str(entry))

    if remote_refs:
        raise ValueError(
            "Remote media URLs are not allowed. Use local files for logos and licensed assets."
        )

    if flagged_without_metadata:
        names = ", ".join(path.name for path in flagged_without_metadata[:5])
        raise ValueError(
            "External-looking assets are missing metadata sidecars. "
            f"Add <asset>.metadata.json or replace them. Examples: {names}"
        )

    needs_attribution = config.compliance.require_attribution or bool(external_assets)
    if not needs_attribution:
        return

    attribution_file = config.compliance.attribution_file
    rows = _read_attribution_rows(attribution_file)
    if not rows:
        raise ValueError(
            f"Attribution is required but file is missing/empty: {attribution_file}"
        )
    missing = [asset for asset in external_assets if not _attribution_contains(asset, rows)]
    if missing:
        names = ", ".join(path.name for path in missing[:8])
        raise ValueError(
            "External CC assets missing attribution entries: "
            f"{names}. Update {attribution_file}."
        )


def _load_build_config(data: dict[str, Any], outline_dir: Path) -> BuildConfig:
    deck_style = _parse_deck_style(data)
    compliance = _parse_compliance(data, outline_dir)
    return BuildConfig(
        outline_dir=outline_dir,
        deck_style=deck_style,
        compliance=compliance,
    )


def _layout_by_hint(prs: Presentation, hints: Iterable[str], fallback: int) -> Any:
    hint_list = [item.lower() for item in hints]
    for layout in prs.slide_layouts:
        name = (layout.name or "").lower()
        if any(hint in name for hint in hint_list):
            return layout
    if len(prs.slide_layouts) == 0:
        raise ValueError("Presentation has no slide layouts.")
    index = max(0, min(fallback, len(prs.slide_layouts) - 1))
    return prs.slide_layouts[index]


def _blank_layout(prs: Presentation) -> Any:
    return _layout_by_hint(prs, ["blank"], fallback=max(0, len(prs.slide_layouts) - 1))


def _safe_int(value: Any, default: int = 0) -> int:
    try:
        return int(value)
    except (TypeError, ValueError):
        return default


def _safe_float(value: Any, default: float | None = None) -> float | None:
    if isinstance(value, (int, float)):
        return float(value)
    text = str(value or "").strip().replace(",", "")
    if not text:
        return default
    if text.endswith("%"):
        text = text[:-1]
    try:
        return float(text)
    except (TypeError, ValueError):
        return default


def _rgb(color_hex: str) -> RGBColor:
    value = (color_hex or "000000").strip().replace("#", "")
    if len(value) != 6:
        value = "000000"
    return RGBColor.from_string(value.upper())


def _slide_w(prs: Presentation) -> float:
    return prs.slide_width / EMU_PER_INCH


def _slide_h(prs: Presentation) -> float:
    return prs.slide_height / EMU_PER_INCH


def _font_title(preset: Any) -> str:
    return str(getattr(preset, "font_pair", {}).get("title", "Trebuchet MS"))


def _font_body(preset: Any) -> str:
    return str(getattr(preset, "font_pair", {}).get("body", "Calibri"))


def _font_caption(preset: Any) -> str:
    return str(getattr(preset, "font_pair", {}).get("caption", "Calibri"))


def _clamp_title_font(typography: Any, text: str, *, density: str) -> int:
    base = typography.title_max
    if density == "high":
        base = min(base, typography.title_min + 4)
    elif density == "medium":
        base = min(base, typography.title_min + 8)
    length = len(text.strip())
    if length > 90:
        base = max(typography.title_min, base - 6)
    elif length > 60:
        base = max(typography.title_min, base - 4)
    return max(typography.title_min, min(typography.title_max, base))


def _clamp_body_font(typography: Any, requested: int) -> int:
    min_readable = max(typography.body_min, 13)
    return max(min_readable, min(typography.body_max, requested))


def _set_background(slide: Any, color_hex: str) -> None:
    fill = slide.background.fill
    fill.solid()
    fill.fore_color.rgb = _rgb(color_hex)


def _set_text_frame_defaults(frame: Any, margin: float = 0.05) -> None:
    frame.word_wrap = True
    frame.margin_left = Inches(margin)
    frame.margin_right = Inches(margin)
    frame.margin_top = Inches(max(0.01, margin * 0.7))
    frame.margin_bottom = Inches(max(0.01, margin * 0.7))


def _set_paragraph_style(
    paragraph: Any,
    *,
    font_name: str,
    font_size: int,
    color_hex: str,
    bold: bool = False,
    align: PP_ALIGN | None = None,
) -> None:
    paragraph.font.name = font_name
    paragraph.font.size = Pt(font_size)
    paragraph.font.color.rgb = _rgb(color_hex)
    paragraph.font.bold = bold
    # Keep run-level styling in sync with paragraph-level styling so text
    # measurement and downstream QA detect the real rendered font settings.
    for run in paragraph.runs:
        run.font.name = font_name
        run.font.size = Pt(font_size)
        run.font.color.rgb = _rgb(color_hex)
        run.font.bold = bold
    if align is not None:
        paragraph.alignment = align


def _set_text_box(
    slide: Any,
    *,
    text: str,
    x: float,
    y: float,
    w: float,
    h: float,
    font_name: str,
    font_size: int,
    color_hex: str,
    bold: bool = False,
    align: PP_ALIGN | None = None,
    margin: float = 0.05,
    wrap: bool = True,
) -> Any:
    box = slide.shapes.add_textbox(Inches(x), Inches(y), Inches(w), Inches(h))
    frame = box.text_frame
    frame.clear()
    _set_text_frame_defaults(frame, margin=margin)
    frame.word_wrap = wrap
    paragraph = frame.paragraphs[0]
    paragraph.text = text
    _set_paragraph_style(
        paragraph,
        font_name=font_name,
        font_size=font_size,
        color_hex=color_hex,
        bold=bold,
        align=align,
    )
    return box


def _set_lines_box(
    slide: Any,
    *,
    lines: list[str],
    x: float,
    y: float,
    w: float,
    h: float,
    font_name: str,
    font_size: int,
    color_hex: str,
    bullet: bool = False,
    margin: float = 0.05,
) -> Any:
    box = slide.shapes.add_textbox(Inches(x), Inches(y), Inches(w), Inches(h))
    frame = box.text_frame
    frame.clear()
    _set_text_frame_defaults(frame, margin=margin)
    cleaned_lines = [line.strip() for line in lines if line and line.strip()]
    if not cleaned_lines:
        return box

    def _apply_bullet(paragraph: Any, level: int = 0) -> None:
        paragraph.level = max(0, level)
        ppr = paragraph._element.get_or_add_pPr()
        for child in list(ppr):
            if child.tag.endswith("buChar") or child.tag.endswith("buNone") or child.tag.endswith("buAutoNum"):
                ppr.remove(child)
        # Use bullet formatting in paragraph properties (not unicode text symbols).
        bu_char = OxmlElement("a:buChar")
        bu_char.set("char", "•")
        ppr.append(bu_char)

    for index, line in enumerate(cleaned_lines):
        paragraph = frame.paragraphs[0] if index == 0 else frame.add_paragraph()
        paragraph.text = line
        if bullet:
            _apply_bullet(paragraph, level=0)
        else:
            paragraph.level = 0
        paragraph.space_after = Pt(8 if bullet else 6)
        _set_paragraph_style(
            paragraph,
            font_name=font_name,
            font_size=font_size,
            color_hex=color_hex,
        )
    return box


def _add_line(
    slide: Any,
    *,
    x: float,
    y: float,
    w: float,
    color_hex: str,
    width_pt: float = 2.0,
) -> None:
    line = slide.shapes.add_connector(
        MSO_CONNECTOR.STRAIGHT,
        Inches(x),
        Inches(y),
        Inches(x + w),
        Inches(y),
    )
    line.line.color.rgb = _rgb(color_hex)
    line.line.width = Pt(width_pt)


def _estimate_text_lines(text: str, *, width_in: float, font_size_pt: float) -> int:
    if not text.strip():
        return 0
    usable_width = max(0.4, width_in - 0.16)
    char_width_in = max(0.055, (font_size_pt / 72.0) * 0.55)
    chars_per_line = max(6, int(usable_width / char_width_in))
    total = 0
    for paragraph in text.splitlines() or [text]:
        stripped = paragraph.strip()
        total += max(1, int(math.ceil(len(stripped) / float(chars_per_line)))) if stripped else 1
    return total


def _estimate_text_height(lines: list[str], *, width_in: float, font_size_pt: float) -> float:
    text = "\n".join(line.strip() for line in lines if line and line.strip())
    if not text:
        return 0.0
    line_count = _estimate_text_lines(text, width_in=width_in, font_size_pt=font_size_pt)
    return line_count * (font_size_pt / 72.0) * 1.24


def _card_body_font(
    body_lines: list[str],
    *,
    width_in: float,
    typography: Any,
    available_height_in: float | None = None,
) -> int:
    text = " ".join(line.strip() for line in body_lines if line and line.strip())
    longest_line = max((len(line.strip()) for line in body_lines if line and line.strip()), default=0)
    requested = typography.body_max - max(0, (len(text) - 120) // 40)
    if width_in < 5.2:
        requested -= 1
    if width_in < 4.6:
        requested -= 1
    if width_in < 4.0:
        requested -= 1
    if longest_line > 34:
        requested -= 1
    if longest_line > 46:
        requested -= 1
    font = _clamp_body_font(typography, requested)
    if available_height_in is None:
        return font

    usable_width = max(0.6, width_in - 0.28)
    while font > typography.body_min:
        body_h = _estimate_text_height(body_lines[:6], width_in=usable_width, font_size_pt=font)
        if body_h <= available_height_in:
            break
        font -= 1
    # Fix 2a safety: when text still overflows at the preset body_min (e.g.
    # tight multi-card slides after the body_min bump from 13 -> 15), allow a
    # small emergency dip below body_min to prevent card overflow. Floor at
    # 12pt so nothing becomes illegible.
    emergency_floor = max(12, typography.body_min - 3)
    while font > emergency_floor:
        body_h = _estimate_text_height(body_lines[:6], width_in=usable_width, font_size_pt=font)
        if body_h <= available_height_in:
            break
        font -= 1
    return max(emergency_floor, font)


def _card_title_layout(title_text: str, width_in: float, typography: Any, preset: Any) -> tuple[int, float]:
    title_font_name = _font_title(preset)
    is_serif_title = any(
        token in title_font_name.lower()
        for token in ("georgia", "times", "palatino", "garamond", "cambria")
    )
    base_cap = 21 if is_serif_title else 24
    heading_font = max(typography.section_min - 2, min(typography.section_max - 2, base_cap))
    if width_in < 2.6:
        heading_font = min(heading_font, 17 if is_serif_title else 18)
    if width_in < 2.3:
        heading_font = min(heading_font, 16 if is_serif_title else 17)
    chars_per_line = max(8, int((width_in - 0.32) * 7.0))
    estimated_lines = max(1, min(2, int(math.ceil(len(title_text) / float(chars_per_line)))))
    if estimated_lines > 1:
        heading_font = max(
            typography.section_min - 5,
            heading_font - (3 if is_serif_title else 2),
        )
    title_h = min(1.02, max(0.60, 0.38 + estimated_lines * 0.24))
    return heading_font, title_h


def _preferred_card_height(
    *,
    title_text: str,
    body_lines: list[str],
    width_in: float,
    typography: Any,
    preset: Any,
    rail_h: float,
    min_h: float,
    max_h: float,
    icon_height: float = 0.0,
) -> float:
    heading_font, title_h = _card_title_layout(title_text, width_in, typography, preset)
    body_font = _card_body_font(
        body_lines,
        width_in=width_in,
        typography=typography,
    )
    body_h = _estimate_text_height(body_lines[:6], width_in=width_in - 0.28, font_size_pt=body_font)
    preferred = rail_h + icon_height + title_h + 0.16 + body_h + 0.20
    return min(max(max(min_h, preferred), 0.9), max_h)


def _add_card(
    slide: Any,
    *,
    x: float,
    y: float,
    w: float,
    h: float,
    title: str,
    body_lines: list[str],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    rail_h: float,
    accent_key: str = "accent_primary",
    dark: bool = False,
    body_vertical_anchor: Any = None,
    icon_path: Path | None = None,
    icon_size: float = 0.0,
) -> None:
    fill_color = palette["bg_dark"] if dark else palette["surface"]
    line_color = palette["line"] if not dark else palette["accent_primary"]
    text_color = "FFFFFF" if dark else palette["text_primary"]
    muted_color = "CBD5E1" if dark else palette["text_muted"]

    # Keep rail + card geometry coherent: accent rails are rectangular, so
    # the card body must be rectangular too (no rounded-corner mismatch).
    card = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(h),
    )
    card.fill.solid()
    card.fill.fore_color.rgb = _rgb(fill_color)
    card.line.color.rgb = _rgb(line_color)
    card.line.width = Pt(1.25)

    rail = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(rail_h),
    )
    rail.fill.solid()
    rail.fill.fore_color.rgb = _rgb(palette.get(accent_key, palette["accent_primary"]))
    rail.line.fill.background()

    # When the caller passes an empty title explicitly, skip the title
    # row entirely — the slide's own header already frames the card and
    # a stale default like "Key Points" reads as auto-generated filler.
    title_text = title.strip()
    suppress_title = title_text == ""
    title_font_name = _font_title(preset)
    if suppress_title:
        heading_font = typography.section_min
        title_h = 0.0
    else:
        heading_font, title_h = _card_title_layout(title_text, w, typography, preset)
    body_gap = 0.16 if not suppress_title else 0.10

    # Icon block: positioned inside the card, below the rail, above the title.
    # Adds icon_size + icon_pad to the title-top so title/body shift down.
    icon_pad = 0.15 if (icon_path is not None and icon_size > 0) else 0.0
    icon_block_h = (icon_size + icon_pad) if (icon_path is not None and icon_size > 0) else 0.0
    if icon_path is not None and icon_size > 0:
        icon_top = y + rail_h + 0.08
        icon_left = x + (w - icon_size) / 2.0
        _add_icon(slide, path=icon_path, x=icon_left, y=icon_top, size=icon_size)

    title_top = y + rail_h + icon_block_h + 0.06
    body_y = y + rail_h + icon_block_h + title_h + body_gap
    body_h = max(0.5, h - rail_h - icon_block_h - title_h - body_gap - 0.08)
    body_font = _card_body_font(
        body_lines,
        width_in=w,
        typography=typography,
        available_height_in=body_h,
    )

    if not suppress_title:
        _set_text_box(
            slide,
            text=title_text,
            x=x + 0.14,
            y=title_top,
            w=w - 0.28,
            h=max(0.36, title_h - 0.02),
            font_name=title_font_name,
            font_size=heading_font,
            color_hex=text_color,
            bold=True,
            margin=0.01,
        )
    body_box = _set_lines_box(
        slide,
        lines=body_lines[:6],
        x=x + 0.14,
        y=body_y,
        w=w - 0.28,
        h=body_h,
        font_name=_font_body(preset),
        font_size=body_font,
        color_hex=muted_color if len(body_lines) > 1 else text_color,
        bullet=False,
        margin=0.01,
    )
    # Fix 1/2b: when caller requests a vertical anchor (e.g. MIDDLE), apply it
    # to the body text frame so expanded cards don't leave dead space below
    # short content.
    if body_vertical_anchor is not None and body_box is not None:
        try:
            body_box.text_frame.vertical_anchor = body_vertical_anchor
        except Exception:
            pass


def _normalize_bullets(items: Any) -> list[tuple[str, int]]:
    normalized: list[tuple[str, int]] = []
    if not isinstance(items, list):
        return normalized
    for item in items:
        if isinstance(item, str):
            text = item.strip()
            if text:
                normalized.append((text, 0))
            continue
        if isinstance(item, dict):
            text = str(item.get("text", "")).strip()
            if not text:
                continue
            level = max(0, min(_safe_int(item.get("level", 0), 0), 8))
            normalized.append((text, level))
    return normalized


def _extract_lines(spec: dict[str, Any]) -> list[str]:
    bullets = _normalize_bullets(spec.get("bullets"))
    if bullets:
        return [text for text, _ in bullets]
    paragraphs = spec.get("paragraphs")
    if isinstance(paragraphs, list):
        return [str(item).strip() for item in paragraphs if str(item).strip()]
    body = str(spec.get("body", "")).strip()
    if not body:
        return []
    parts = [part.strip() for part in body.replace("\n", ". ").split(".")]
    return [part for part in parts if part]


def _content_header(
    slide: Any,
    *,
    title: str,
    subtitle: str,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    margin_x: float,
    right_reserve: float = 0.0,
) -> float:
    header_w = max(6.0, 8.6 - right_reserve)
    title_text = title.strip() or "Content"
    title_cap = 28 if right_reserve >= 3.0 else 30
    title_font = max(typography.section_min, min(typography.section_max, title_cap))
    title_lines = max(1, min(3, _estimate_text_lines(title_text, width_in=header_w, font_size_pt=title_font)))
    title_h = min(1.18, max(0.62, 0.30 + title_lines * 0.32))
    if right_reserve >= 3.0:
        title_h = min(1.28, title_h + 0.10)
    title_y = 0.34

    # Editorial-minimal treatment: pure white slides carry one strong
    # color, used as a left accent bar flanking the title. The title
    # text itself stays in near-black — the colored bar is the branding
    # element, not the typography. This is the "heading title box with
    # color" look for editorial/research decks.
    preset_name = getattr(preset, "name", "")
    editorial = preset_name == "editorial-minimal"
    lab_report = preset_name == "lab-report"
    title_x = margin_x
    title_color_override: str | None = None
    subtitle_color_override: str | None = None

    if editorial:
        bar_w = 0.10
        bar_gap = 0.20
        bar = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(margin_x),
            Inches(title_y + 0.06),
            Inches(bar_w),
            Inches(max(0.50, title_h - 0.12)),
        )
        bar.fill.solid()
        bar.fill.fore_color.rgb = _rgb(palette.get("accent_primary", "D4461E"))
        bar.line.fill.background()
        title_x = margin_x + bar_w + bar_gap
        header_w = max(4.0, header_w - (bar_w + bar_gap))

    elif lab_report:
        # Clinical-data aesthetic inspired by (not cloned from) lab
        # comparison decks: dark header block + thin accent rule
        # beneath it signals technical precision. Pulls the actual
        # slide width from the presentation rather than assuming 13.33"
        # so this scales to any canvas.
        try:
            slide_w_actual = slide.part.package.presentation_part.presentation.slide_width / 914400.0
        except Exception:
            slide_w_actual = 13.33
        header_h = 0.94
        accent_h = 0.04
        bar = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(0),
            Inches(0),
            Inches(slide_w_actual),
            Inches(header_h),
        )
        bar.fill.solid()
        bar.fill.fore_color.rgb = _rgb(palette.get("bg_dark", "0B2545"))
        bar.line.fill.background()
        # Thin accent rule beneath the header — skill-signature touch.
        accent = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(0),
            Inches(header_h),
            Inches(slide_w_actual),
            Inches(accent_h),
        )
        accent.fill.solid()
        accent.fill.fore_color.rgb = _rgb(palette.get("accent_secondary", "C9302C"))
        accent.line.fill.background()
        title_y = 0.14
        title_h = min(0.54, title_h)
        title_color_override = "FFFFFF"
        subtitle_color_override = "D1D5DB"

    _set_text_box(
        slide,
        text=title_text,
        x=title_x,
        y=title_y,
        w=header_w,
        h=title_h,
        font_name=_font_title(preset),
        font_size=title_font,
        color_hex=title_color_override or palette["text_primary"],
        bold=True,
        margin=0.01,
    )
    header_bottom = title_y + title_h
    if subtitle.strip():
        subtitle_w = max(6.2, 9.0 - right_reserve)
        subtitle_cap = 15 if right_reserve >= 3.0 else 16
        subtitle_font = max(typography.caption_min + 1, min(typography.caption_max + 2, subtitle_cap))
        subtitle_lines = max(
            1,
            min(2, _estimate_text_lines(subtitle.strip(), width_in=subtitle_w, font_size_pt=subtitle_font)),
        )
        subtitle_h = min(0.62, max(0.26, 0.12 + subtitle_lines * 0.22))
        if right_reserve >= 3.0:
            subtitle_h = min(0.70, subtitle_h + 0.08)
        subtitle_y = header_bottom + 0.04
        _set_text_box(
            slide,
            text=subtitle.strip(),
            x=title_x,
            y=subtitle_y,
            w=subtitle_w,
            h=subtitle_h,
            font_name=_font_caption(preset),
            font_size=subtitle_font,
            color_hex=subtitle_color_override or palette["text_muted"],
            margin=0.01,
        )
        header_bottom = subtitle_y + subtitle_h
    return header_bottom


def _footer_geometry(slide_h: float) -> tuple[float, float]:
    footer_h = 0.28
    footer_bottom_pad = 0.08
    footer_y = slide_h - footer_h - footer_bottom_pad
    return footer_y, footer_h


def _content_bottom(slide_h: float, *, has_footer: bool, layout: Any) -> float:
    if has_footer:
        footer_y, _ = _footer_geometry(slide_h)
        return footer_y - 0.10
    return slide_h - max(0.22, float(getattr(layout, "bottom_safe", 0.30)))


def _add_background_image(
    slide: Any,
    spec: dict[str, Any],
    *,
    slide_w: float,
    slide_h: float,
    palette: dict[str, str],
    outline_dir: Path,
) -> bool:
    candidate = _resolve_asset_path(spec.get("background_image"), outline_dir)
    if not candidate:
        return False
    if not candidate.exists() or not candidate.is_file():
        return False
    slide.shapes.add_picture(
        str(candidate),
        Inches(0),
        Inches(0),
        width=Inches(slide_w),
        height=Inches(slide_h),
    )
    overlay = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(0),
        Inches(0),
        Inches(slide_w),
        Inches(slide_h),
    )
    overlay.fill.solid()
    overlay.fill.fore_color.rgb = _rgb(palette["bg_primary"])
    try:
        overlay.fill.transparency = 20
    except Exception:
        pass
    overlay.line.fill.background()
    return True


def _add_content_motif(
    slide: Any,
    *,
    palette: dict[str, str],
    slide_w: float,
    margin_x: float,
) -> None:
    anchors = [
        (0.42, 0.30, "accent_primary", 85),
        (0.28, 0.78, "accent_secondary", 88),
        (0.20, 1.12, "line", 90),
    ]
    for size, y, color_key, transparency in anchors:
        shape = slide.shapes.add_shape(
            MSO_SHAPE.OVAL,
            Inches(slide_w - margin_x - size),
            Inches(y),
            Inches(size),
            Inches(size),
        )
        shape.fill.solid()
        shape.fill.fore_color.rgb = _rgb(palette.get(color_key, palette["accent_primary"]))
        try:
            shape.fill.transparency = transparency
        except Exception:
            pass
        shape.line.fill.background()


def _add_section_motif_enrichment(
    slide: Any,
    *,
    palette: dict[str, str],
    slide_w: float,
    slide_h: float,
    margin_x: float,
) -> None:
    """Quiet decorative footprint for content-free section dividers.

    Draws a horizontal accent rail ~60% down the canvas plus three
    circular motif dots sitting along that rail. Low-contrast on
    purpose -- this is enrichment, not content.
    """
    rail_y = slide_h * 0.60
    rail_height = 0.10
    rail_w = slide_w - margin_x * 2
    rail = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(margin_x),
        Inches(rail_y),
        Inches(rail_w),
        Inches(rail_height),
    )
    rail.fill.solid()
    rail.fill.fore_color.rgb = _rgb(palette.get("accent_primary", palette.get("line", "BAE6FD")))
    try:
        rail.fill.transparency = 55
    except Exception:
        pass
    rail.line.fill.background()

    dot_diameters = [0.48, 0.36, 0.30]
    # Offsets from left margin where each dot centers.
    centers = [
        margin_x + rail_w * 0.18,
        margin_x + rail_w * 0.48,
        margin_x + rail_w * 0.82,
    ]
    color_keys = ["accent_primary", "accent_secondary", "accent_primary"]
    transparencies = [70, 65, 78]
    rail_center_y = rail_y + rail_height / 2.0
    for center_x, diameter, color_key, transparency in zip(
        centers, dot_diameters, color_keys, transparencies
    ):
        dot = slide.shapes.add_shape(
            MSO_SHAPE.OVAL,
            Inches(center_x - diameter / 2.0),
            Inches(rail_center_y - diameter / 2.0),
            Inches(diameter),
            Inches(diameter),
        )
        dot.fill.solid()
        dot.fill.fore_color.rgb = _rgb(
            palette.get(color_key, palette.get("accent_primary", "0EA5E9"))
        )
        try:
            dot.fill.transparency = transparency
        except Exception:
            pass
        dot.line.fill.background()


def _add_thumbnail_strip(
    slide: Any,
    *,
    thumbnails: list[str],
    slide_w: float,
    margin_x: float,
    palette: dict[str, str],
    outline_dir: Path,
) -> None:
    valid: list[Path] = []
    for item in thumbnails:
        candidate = _resolve_asset_path(item, outline_dir)
        if not candidate:
            continue
        if candidate.exists() and candidate.is_file():
            valid.append(candidate)
        if len(valid) >= 3:
            break
    if not valid:
        return
    thumb_w = 0.90
    thumb_h = 0.50
    gap = 0.10
    total_w = len(valid) * thumb_w + (len(valid) - 1) * gap
    start_x = max(margin_x + 6.5, slide_w - margin_x - total_w)
    y = 0.30
    for index, path in enumerate(valid):
        x = start_x + index * (thumb_w + gap)
        frame = slide.shapes.add_shape(
            MSO_SHAPE.ROUNDED_RECTANGLE,
            Inches(x),
            Inches(y),
            Inches(thumb_w),
            Inches(thumb_h),
        )
        frame.fill.solid()
        frame.fill.fore_color.rgb = _rgb(palette["surface"])
        frame.line.color.rgb = _rgb(palette["line"])
        frame.line.width = Pt(0.8)
        try:
            frame.adjustments[0] = 0.08
        except Exception:
            pass
        slide.shapes.add_picture(
            str(path),
            Inches(x + 0.02),
            Inches(y + 0.02),
            width=Inches(thumb_w - 0.04),
            height=Inches(thumb_h - 0.04),
        )


def _slide_assets(spec: dict[str, Any]) -> dict[str, Any]:
    assets = spec.get("assets")
    if isinstance(assets, dict):
        return assets
    return {}


def _slide_icon_paths(
    spec: dict[str, Any], outline_dir: Path, count: int
) -> list[Path | None]:
    """Return a list of resolved icon paths sized to `count` (None for missing).

    Never raises. Icons are v1 supported on cards-2/cards-3, timeline, stats.
    Missing icons become None so callers can render the element without the
    icon. A stderr warning is emitted per miss by `_resolve_icon_path`.
    """
    assets = _slide_assets(spec)
    raw_icons = assets.get("icons")
    if not isinstance(raw_icons, list) or count <= 0:
        return [None] * max(0, count)
    resolved: list[Path | None] = []
    for idx in range(count):
        if idx >= len(raw_icons):
            resolved.append(None)
            continue
        resolved.append(_resolve_icon_path(raw_icons[idx], outline_dir))
    return resolved


def _asset_from_spec(spec: dict[str, Any], key: str, outline_dir: Path) -> Path | None:
    assets = _slide_assets(spec)
    return _resolve_asset_path(assets.get(key), outline_dir)


def _render_mermaid_asset_if_needed(spec: dict[str, Any], outline_dir: Path) -> Path | None:
    assets = _slide_assets(spec)
    diagram = _resolve_asset_path(assets.get("diagram"), outline_dir)
    if diagram and diagram.exists():
        return diagram
    mermaid_source = _resolve_asset_path(
        assets.get("mermaid") or assets.get("mermaid_source"),
        outline_dir,
    )
    if not mermaid_source or not mermaid_source.exists():
        return diagram

    target = diagram or mermaid_source.with_suffix(".png")
    render_script = Path(__file__).resolve().parent / "render_mermaid.py"
    if not render_script.exists():
        return diagram
    try:
        result = subprocess.run(
            [
                sys.executable,
                str(render_script),
                "--input",
                str(mermaid_source),
                "--output",
                str(target),
            ],
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True,
            check=False,
        )
        if result.returncode == 0 and target.exists():
            return target
    except Exception:
        return diagram
    return diagram


def _load_chart_payload(spec: dict[str, Any], outline_dir: Path) -> dict[str, Any]:
    candidates = [
        spec.get("chart"),
        _slide_assets(spec).get("chart_data"),
        _slide_assets(spec).get("chart"),
    ]
    for candidate in candidates:
        if isinstance(candidate, dict):
            return deepcopy(candidate)
        if not candidate:
            continue
        path = _resolve_asset_path(candidate, outline_dir)
        if not path:
            continue
        if not path.exists():
            raise FileNotFoundError(f"Chart data file not found: {path}")
        payload = json.loads(path.read_text(encoding="utf-8"))
        if isinstance(payload, dict):
            return payload
        raise ValueError(f"Chart data must decode to a JSON object: {path}")
    return {}


def _normalize_chart_payload(spec: dict[str, Any], outline_dir: Path) -> dict[str, Any]:
    raw = _load_chart_payload(spec, outline_dir)
    if not raw:
        return {}

    chart_type = _as_str(raw.get("type"), "bar").lower()
    options = raw.get("options") if isinstance(raw.get("options"), dict) else {}
    # Fix 1: accept both series-level `labels` (legacy schema) and chart-level
    # `categories` (common shorthand). If series omit `labels`, copy
    # `categories` in as a fallback before validation.
    chart_level_categories = None
    raw_categories = raw.get("categories")
    if isinstance(raw_categories, list) and raw_categories:
        chart_level_categories = raw_categories
    elif isinstance(raw.get("labels"), list) and raw.get("labels"):
        chart_level_categories = raw.get("labels")

    def _error(reason: str) -> dict[str, Any]:
        """Return an error marker so the renderer can draw a red banner and QA can pick it up."""
        return {
            "__error__": reason,
            "type": chart_type,
            "title": _as_str(raw.get("title"), ""),
            "subtitle": _as_str(raw.get("subtitle"), ""),
            "notes": _as_str(raw.get("notes") or raw.get("message") or raw.get("caption"), ""),
            "sources": raw.get("sources") if isinstance(raw.get("sources"), list) else [],
            "facts": raw.get("facts") if isinstance(raw.get("facts"), list) else raw.get("stats"),
            "series": [],
            "options": options,
            "color1": _as_str(raw.get("color1"), ""),
            "color2": _as_str(raw.get("color2"), ""),
            "color3": _as_str(raw.get("color3"), ""),
            "color4": _as_str(raw.get("color4"), ""),
        }

    series_items = raw.get("series")
    normalized_series: list[dict[str, Any]] = []
    invalid_reasons: list[str] = []
    if isinstance(series_items, list) and series_items:
        for index, item in enumerate(series_items):
            if not isinstance(item, dict):
                invalid_reasons.append(
                    f"series[{index}] is not an object"
                )
                continue
            series_labels = item.get("labels") if isinstance(item.get("labels"), list) else None
            # Fallback priority: series.labels -> chart.categories -> chart.labels
            labels = series_labels if series_labels else chart_level_categories
            values = item.get("values")
            if not isinstance(labels, list) or not labels:
                invalid_reasons.append(
                    f"series[{index}] missing labels/categories"
                )
                continue
            if not isinstance(values, list) or not values:
                invalid_reasons.append(
                    f"series[{index}] missing values"
                )
                continue
            if len(labels) != len(values):
                invalid_reasons.append(
                    f"series[{index}] length mismatch: {len(labels)} labels vs {len(values)} values"
                )
                continue
            parsed_values = [_safe_float(value) for value in values]
            if any(value is None for value in parsed_values):
                invalid_reasons.append(
                    f"series[{index}] contains non-numeric values"
                )
                continue
            paired = [
                (str(label).strip(), value)
                for label, value in zip(labels, parsed_values)
                if str(label).strip() and value is not None
            ]
            if not paired:
                invalid_reasons.append(
                    f"series[{index}] has no usable (label, value) pairs"
                )
                continue
            normalized_series.append(
                {
                    "name": _as_str(item.get("name"), f"Series {index + 1}"),
                    "labels": [label for label, _ in paired],
                    "values": [float(value) for _, value in paired],
                }
            )
    else:
        # Flat schema: {labels: [...], values: [...]} or {categories: [...], values: [...]}
        labels = chart_level_categories
        values = raw.get("values")
        if isinstance(labels, list) and isinstance(values, list):
            if len(labels) != len(values):
                invalid_reasons.append(
                    f"flat chart length mismatch: {len(labels)} labels vs {len(values)} values"
                )
            else:
                parsed_values = [_safe_float(value) for value in values]
                if any(value is None for value in parsed_values):
                    invalid_reasons.append("flat chart contains non-numeric values")
                else:
                    paired = [
                        (str(label).strip(), value)
                        for label, value in zip(labels, parsed_values)
                        if str(label).strip() and value is not None
                    ]
                    if paired:
                        normalized_series.append(
                            {
                                "name": _as_str(raw.get("series_name"), "Series A"),
                                "labels": [label for label, _ in paired],
                                "values": [float(value) for _, value in paired],
                            }
                        )
        elif series_items is None:
            invalid_reasons.append("chart payload has no series and no flat labels/values")

    if not normalized_series:
        if invalid_reasons:
            return _error("; ".join(invalid_reasons))
        # Raw payload exists but contained nothing actionable.
        return _error("chart payload present but produced no series")

    return {
        "type": chart_type,
        "title": _as_str(raw.get("title"), ""),
        "subtitle": _as_str(raw.get("subtitle"), ""),
        "notes": _as_str(raw.get("notes") or raw.get("message") or raw.get("caption"), ""),
        "sources": raw.get("sources") if isinstance(raw.get("sources"), list) else [],
        "facts": raw.get("facts") if isinstance(raw.get("facts"), list) else raw.get("stats"),
        "series": normalized_series,
        "options": options,
        "color1": _as_str(raw.get("color1"), ""),
        "color2": _as_str(raw.get("color2"), ""),
        "color3": _as_str(raw.get("color3"), ""),
        "color4": _as_str(raw.get("color4"), ""),
    }


def _normalize_fact_items(spec: dict[str, Any], chart_payload: dict[str, Any] | None = None) -> list[dict[str, str]]:
    collections: list[Any] = []
    for owner in (spec, chart_payload or {}):
        for key in ("facts", "stats", "evidence"):
            value = owner.get(key)
            if isinstance(value, list) and value:
                collections = value
                break
        if collections:
            break

    normalized: list[dict[str, str]] = []
    for item in collections:
        if isinstance(item, str):
            text = item.strip()
            if not text:
                continue
            normalized.append(
                {
                    "value": "",
                    "label": text,
                    "detail": "",
                    "source": "",
                    "accent": "",
                }
            )
            continue
        if not isinstance(item, dict):
            continue
        value = _as_str(item.get("value") or item.get("metric"), "")
        label = _as_str(item.get("label") or item.get("title"), "")
        detail = _as_str(item.get("detail") or item.get("body") or item.get("text"), "")
        source = _as_str(item.get("source") or item.get("citation"), "")
        accent = _as_str(item.get("accent"), "")
        if not any((value, label, detail, source)):
            continue
        if not label:
            label = detail or value or "Key Fact"
            if detail and value:
                detail = detail
            elif detail == label:
                detail = ""
        normalized.append(
            {
                "value": value,
                "label": label,
                "detail": detail if detail != label else "",
                "source": source,
                "accent": accent,
            }
        )
    return normalized[:4]


def _add_visual_assets(
    slide: Any,
    *,
    spec: dict[str, Any],
    slide_w: float,
    margin_x: float,
    outline_dir: Path,
) -> None:
    hero = _asset_from_spec(spec, "hero_image", outline_dir)
    if hero and hero.exists():
        box_w = 3.25
        box_h = 2.05
        x = slide_w - margin_x - box_w
        y = 1.42
        frame = slide.shapes.add_shape(
            MSO_SHAPE.ROUNDED_RECTANGLE,
            Inches(x),
            Inches(y),
            Inches(box_w),
            Inches(box_h),
        )
        frame.fill.solid()
        frame.fill.fore_color.rgb = _rgb("FFFFFF")
        frame.line.fill.background()
        try:
            frame.adjustments[0] = 0.08
        except Exception:
            pass
        slide.shapes.add_picture(
            str(hero),
            Inches(x + 0.02),
            Inches(y + 0.02),
            width=Inches(box_w - 0.04),
            height=Inches(box_h - 0.04),
        )

    logo = _asset_from_spec(spec, "logo", outline_dir)
    if logo and logo.exists():
        slide.shapes.add_picture(
            str(logo),
            Inches(slide_w - margin_x - 1.10),
            Inches(0.20),
            width=Inches(0.95),
            height=Inches(0.34),
        )


def _add_flow_diagram_layout(
    prs: Presentation,
    spec: dict[str, Any],
    *,
    preset: Any,
    outline_dir: Path,
) -> Any:
    typography = preset.typography
    palette = preset.palette
    layout = preset.layout
    slide = prs.slides.add_slide(_blank_layout(prs))
    sw = _slide_w(prs)
    sh = _slide_h(prs)
    mx = layout.margin_x
    _set_background(slide, palette["bg_primary"])
    _content_header(
        slide,
        title=_as_str(spec.get("title"), "Flow"),
        subtitle=_as_str(spec.get("subtitle"), ""),
        palette=palette,
        typography=typography,
        preset=preset,
        margin_x=mx,
    )

    diagram = _render_mermaid_asset_if_needed(spec, outline_dir)
    diagram_y = 1.45
    diagram_h = 4.95
    frame = slide.shapes.add_shape(
        MSO_SHAPE.ROUNDED_RECTANGLE,
        Inches(mx),
        Inches(diagram_y),
        Inches(sw - mx * 2),
        Inches(diagram_h),
    )
    frame.fill.solid()
    frame.fill.fore_color.rgb = _rgb(palette["surface"])
    frame.line.color.rgb = _rgb(palette["line"])
    frame.line.width = Pt(1.2)
    try:
        frame.adjustments[0] = 0.03
    except Exception:
        pass

    if diagram and diagram.exists():
        slide.shapes.add_picture(
            str(diagram),
            Inches(mx + 0.08),
            Inches(diagram_y + 0.08),
            width=Inches(sw - mx * 2 - 0.16),
            height=Inches(diagram_h - 0.16),
        )
    else:
        _set_text_box(
            slide,
            text="Diagram asset missing. Provide assets.diagram for flow slides.",
            x=mx + 0.2,
            y=diagram_y + 2.1,
            w=sw - mx * 2 - 0.4,
            h=0.8,
            font_name=_font_body(preset),
            font_size=_clamp_body_font(typography, typography.body_max),
            color_hex=palette["text_muted"],
            align=PP_ALIGN.CENTER,
        )

    message = _as_str(spec.get("message"), "")
    caption = _as_str(spec.get("caption"), "")
    if not message:
        message = "Decision: Confirm the process owner and transition criteria."
    if not caption:
        caption = "Diagram source should map directly to the above decision."
    _set_text_box(
        slide,
        text=message,
        x=mx,
        y=6.48,
        w=sw - mx * 2,
        h=0.35,
        font_name=_font_title(preset),
        font_size=max(typography.caption_min + 1, 12),
        color_hex=palette["text_primary"],
        bold=True,
        margin=0.01,
    )
    _set_text_box(
        slide,
        text=caption,
        x=mx,
        y=6.83,
        w=sw - mx * 2,
        h=0.35,
        font_name=_font_caption(preset),
        font_size=max(typography.caption_min, 11),
        color_hex=palette["text_muted"],
        margin=0.01,
    )
    return slide


def _add_summary_callout(
    slide: Any,
    *,
    text: str,
    palette: dict[str, str],
    preset: Any,
    slide_w: float,
    slide_h: float,
    margin_x: float,
    has_footer: bool,
) -> float:
    """Render a rounded-rectangle summary callout anchored at the bottom.

    Inspired by the TB-LAMP-Seq / lab-data deck pattern: a full-width
    rounded box just above the footer carrying a single bold prose line
    that answers "so what?" for the slide. Universal — sits below any
    variant. Returns the Y-coordinate the callout occupies so callers
    can account for the space (most callers don't need to, since content
    zone is sized independently and the callout overlays the slide's
    bottom padding area).
    """
    body = (text or "").strip()
    if not body:
        return 0.0
    # Bottom anchoring: callout sits just above the footer if present,
    # otherwise just above the slide bottom-safe margin.
    footer_reserve = 0.50 if has_footer else 0.25
    callout_h = 0.78
    callout_y = slide_h - footer_reserve - callout_h
    callout_w = slide_w - margin_x * 2.2
    callout_x = margin_x * 1.1
    # Use ROUNDED_RECTANGLE so the shape reads as a pill/callout, not a card.
    box = slide.shapes.add_shape(
        MSO_SHAPE.ROUNDED_RECTANGLE,
        Inches(callout_x),
        Inches(callout_y),
        Inches(callout_w),
        Inches(callout_h),
    )
    # Deep accent fill + light text — the callout should visually punch
    # above the body text, like a pull-quote.
    accent_color = palette.get("accent_primary", "14B8A6")
    box.fill.solid()
    box.fill.fore_color.rgb = _rgb(accent_color)
    box.line.fill.background()
    _set_text_box(
        slide,
        text=body,
        x=callout_x + 0.25,
        y=callout_y + 0.08,
        w=callout_w - 0.50,
        h=callout_h - 0.16,
        font_name=_font_body(preset),
        font_size=max(13, min(16, preset.typography.body_max)),
        color_hex="FFFFFF",
        bold=True,
        align=PP_ALIGN.CENTER,
        margin=0.04,
    )
    return callout_h


def _add_footer(
    slide: Any,
    *,
    text: str,
    palette: dict[str, str],
    preset: Any,
    slide_h: float,
    margin_x: float,
    dark: bool = False,
    page_index: int | None = None,
    page_total: int | None = None,
    slide_w: float = 13.33,
) -> None:
    footer_y, footer_h = _footer_geometry(slide_h)
    color = "94A3B8" if dark else palette["text_muted"]
    show_page = (
        isinstance(page_index, int)
        and isinstance(page_total, int)
        and page_total > 0
        and 1 <= page_index <= page_total
    )
    if not text.strip() and not show_page:
        return

    # Reserve a right-aligned slot for the page number when present so the
    # source line doesn't overlap it. Two text boxes: source on left,
    # page indicator on right. When only one is present, it spans the
    # full footer width.
    if show_page:
        page_text = f"{page_index} / {page_total}"
        page_w = 1.2
        page_x = slide_w - margin_x - page_w
        _set_text_box(
            slide,
            text=page_text,
            x=page_x,
            y=footer_y,
            w=page_w,
            h=footer_h,
            font_name=_font_caption(preset),
            font_size=10,
            color_hex=color,
            margin=0.0,
            align=PP_ALIGN.RIGHT,
            wrap=False,
        )
        left_w = max(1.0, page_x - margin_x - 0.20)
    else:
        left_w = slide_w - margin_x * 2

    if text.strip():
        font_size = 10 if len(text.strip()) <= 84 else 9
        _set_text_box(
            slide,
            text=text.strip(),
            x=margin_x,
            y=footer_y,
            w=min(10.5, left_w),
            h=footer_h,
            font_name=_font_caption(preset),
            font_size=font_size,
            color_hex=color,
            margin=0.0,
            wrap=False,
        )


# ---------------------------------------------------------------------------
# Fix 3: title-slide motif variety. All motifs share the same top-right
# footprint (~1.2" wide x ~1.0" tall, anchored around x ~= sw - 2.6, y ~= 0.5)
# and use only palette accent_primary/accent_secondary so they stay quiet.
# ---------------------------------------------------------------------------


def _draw_title_motif_orbit(slide: Any, *, palette: dict[str, str], slide_w: float) -> None:
    """Original three-orbit-dots motif (kept for backward compatibility)."""
    for index, scale in enumerate([0.9, 0.72, 0.55]):
        circle = slide.shapes.add_shape(
            MSO_SHAPE.OVAL,
            Inches(slide_w - (2.6 - index * 0.65)),
            Inches(0.7 + index * 0.42),
            Inches(scale),
            Inches(scale),
        )
        circle.fill.solid()
        circle.fill.fore_color.rgb = _rgb(
            palette["accent_primary"] if index != 1 else palette["accent_secondary"]
        )
        circle.line.fill.background()


def _draw_title_motif_stripe(slide: Any, *, palette: dict[str, str], slide_w: float) -> None:
    """Three horizontal accent stripes, descending widths, top-right corner."""
    stripes = [
        (1.20, 0.55, "accent_primary"),
        (0.90, 0.78, "accent_secondary"),
        (0.60, 1.01, "accent_primary"),
    ]
    right_edge = slide_w - 0.55
    for width, y_off, color_key in stripes:
        stripe = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(right_edge - width),
            Inches(y_off),
            Inches(width),
            Inches(0.12),
        )
        stripe.fill.solid()
        stripe.fill.fore_color.rgb = _rgb(palette[color_key])
        stripe.line.fill.background()


def _draw_title_motif_wave(slide: Any, *, palette: dict[str, str], slide_w: float) -> None:
    """Quiet wave made from three small rounded-rectangle segments."""
    base_x = slide_w - 2.40
    # Three short stubby rounded rects at staggered heights to evoke a wave.
    segments = [
        (0.00, 0.80, 0.55, "accent_primary"),
        (0.55, 0.55, 0.55, "accent_secondary"),
        (1.10, 0.80, 0.55, "accent_primary"),
    ]
    for dx, y_off, width, color_key in segments:
        seg = slide.shapes.add_shape(
            MSO_SHAPE.ROUNDED_RECTANGLE,
            Inches(base_x + dx),
            Inches(y_off),
            Inches(width),
            Inches(0.22),
        )
        try:
            seg.adjustments[0] = 0.5
        except Exception:
            pass
        seg.fill.solid()
        seg.fill.fore_color.rgb = _rgb(palette[color_key])
        seg.line.fill.background()
    # Thin connector tint to tie them together
    tint = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(base_x),
        Inches(1.12),
        Inches(1.65),
        Inches(0.06),
    )
    tint.fill.solid()
    tint.fill.fore_color.rgb = _rgb(palette["accent_secondary"])
    tint.line.fill.background()


def _draw_title_motif_arc(slide: Any, *, palette: dict[str, str], slide_w: float) -> None:
    """Three concentric quarter-arcs (stacked ovals) in the top-right corner."""
    # Large to small ovals give a concentric-ring feel with no fills colliding.
    rings = [
        (1.30, "accent_primary"),
        (0.95, "accent_secondary"),
        (0.60, "accent_primary"),
    ]
    anchor_x = slide_w - 2.45
    anchor_y = 0.55
    for size, color_key in rings:
        ring = slide.shapes.add_shape(
            MSO_SHAPE.OVAL,
            Inches(anchor_x + (1.30 - size) / 2),
            Inches(anchor_y + (1.30 - size) / 2),
            Inches(size),
            Inches(size),
        )
        ring.fill.background()
        ring.line.color.rgb = _rgb(palette[color_key])
        ring.line.width = Pt(2.25)


def _draw_title_motif_geometric(
    slide: Any, *, palette: dict[str, str], slide_w: float
) -> None:
    """Three overlapping small triangle/square shapes, top-right corner."""
    base_x = slide_w - 2.35
    # Triangle + square + triangle, overlapping slightly.
    tri1 = slide.shapes.add_shape(
        MSO_SHAPE.ISOSCELES_TRIANGLE,
        Inches(base_x),
        Inches(0.55),
        Inches(0.65),
        Inches(0.72),
    )
    tri1.fill.solid()
    tri1.fill.fore_color.rgb = _rgb(palette["accent_primary"])
    tri1.line.fill.background()

    sq = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(base_x + 0.48),
        Inches(0.72),
        Inches(0.55),
        Inches(0.55),
    )
    sq.fill.solid()
    sq.fill.fore_color.rgb = _rgb(palette["accent_secondary"])
    sq.line.fill.background()

    tri2 = slide.shapes.add_shape(
        MSO_SHAPE.ISOSCELES_TRIANGLE,
        Inches(base_x + 0.98),
        Inches(0.55),
        Inches(0.60),
        Inches(0.72),
    )
    tri2.fill.solid()
    tri2.fill.fore_color.rgb = _rgb(palette["accent_primary"])
    tri2.line.fill.background()


_TITLE_MOTIFS: dict[str, Any] = {
    "orbit": _draw_title_motif_orbit,
    "stripe": _draw_title_motif_stripe,
    "wave": _draw_title_motif_wave,
    "arc": _draw_title_motif_arc,
    "geometric": _draw_title_motif_geometric,
}


# Keyword → motif mapping. First match wins, stable iteration order.
# Word-boundary matched against lowercased title_text + subtitle_text.
_TITLE_MOTIF_KEYWORDS: list[tuple[str, tuple[str, ...]]] = [
    ("wave", (
        "water", "flow", "ocean", "river", "stream", "tide", "current",
        "energy", "wave", "transition", "change", "shift",
    )),
    ("arc", (
        "journey", "arc", "bridge", "transform", "evolution", "trajectory",
        "growth", "path", "pivot",
    )),
    ("orbit", (
        "system", "network", "ecosystem", "platform", "cycle", "loop",
        "orbit", "galaxy", "cluster",
    )),
    ("stripe", (
        "process", "pipeline", "stages", "phases", "roadmap", "workflow",
        "sequence", "timeline", "stripe", "strategy",
    )),
    ("geometric", (
        "framework", "structure", "matrix", "grid", "architecture",
        "model", "blueprint", "schema",
    )),
]


def _pick_title_motif(
    *,
    title_text: str,
    deck_style: DeckStyleConfig,
    subtitle_text: str = "",
) -> str:
    """Pick motif name using tiered resolution:

    1. Explicit override (`deck_style.title_motif`) — "none" skips motif
       entirely, any valid choice wins.
    2. Keyword match against title+subtitle (word-boundary regex).
    3. Fallback: crc32(title_text) % 5 — keeps decks with generic titles
       from rendering a barren title slide.

    Returns "" when the caller should skip drawing a motif.
    """
    override = (deck_style.title_motif or "").strip().lower()
    if override == "none":
        return ""
    if override in TITLE_MOTIF_CHOICES:
        return override

    combined = f"{title_text or ''} {subtitle_text or ''}".lower()
    if combined.strip():
        # Word-boundary match avoids false hits like "processor" → stripe.
        for motif_name, words in _TITLE_MOTIF_KEYWORDS:
            pattern = r"\b(?:" + "|".join(re.escape(w) for w in words) + r")\b"
            if re.search(pattern, combined):
                return motif_name

    key = (title_text or "").encode("utf-8")
    idx = zlib.crc32(key) % len(TITLE_MOTIF_CHOICES)
    return TITLE_MOTIF_CHOICES[idx]


def _add_title_slide(
    prs: Presentation,
    spec: dict[str, Any],
    preset: Any,
    *,
    config: BuildConfig,
) -> Any:
    typography = preset.typography
    palette = preset.palette
    slide = prs.slides.add_slide(_blank_layout(prs))
    sw = _slide_w(prs)
    sh = _slide_h(prs)
    margin_x = preset.layout.margin_x

    _set_background(slide, palette["bg_dark"])

    left_rail = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(0),
        Inches(0),
        Inches(0.16),
        Inches(sh),
    )
    left_rail.fill.solid()
    left_rail.fill.fore_color.rgb = _rgb(palette["accent_primary"])
    left_rail.line.fill.background()

    title_text = str(spec.get("title", "Untitled Presentation")).strip()
    _set_text_box(
        slide,
        text=title_text,
        x=margin_x + 0.1,
        y=2.0,
        w=sw - margin_x * 2 - 2.7,
        h=2.0,
        font_name=_font_title(preset),
        font_size=_clamp_title_font(
            typography,
            title_text,
            density=config.deck_style.visual_density,
        ),
        color_hex="FFFFFF",
        bold=True,
        margin=0.01,
    )

    subtitle = str(spec.get("subtitle", "")).strip()
    if subtitle:
        subtitle_w = sw - margin_x * 2 - 2.8
        subtitle_font = max(typography.section_min, 22)
        subtitle_h = min(
            1.15,
            max(
                0.6,
                _estimate_text_height(
                    [subtitle],
                    width_in=subtitle_w,
                    font_size_pt=subtitle_font,
                )
                + 0.10,
            ),
        )
        _set_text_box(
            slide,
            text=subtitle,
            x=margin_x + 0.1,
            y=4.55,
            w=subtitle_w,
            h=subtitle_h,
            font_name=_font_body(preset),
            font_size=subtitle_font,
            color_hex=palette["accent_primary"],
            bold=True,
            margin=0.01,
        )

    # Fix 3: hash-rotated title motif variety. If a hero image is present,
    # the hero code path has already drawn it (or will draw it) and we skip
    # the decorative motif entirely so it doesn't compete. Otherwise the
    # motif is picked deterministically from the deck title, with optional
    # explicit override from `deck_style.title_motif`.
    hero_asset = _asset_from_spec(spec, "hero_image", config.outline_dir)
    has_hero = bool(hero_asset and hero_asset.exists())
    if not has_hero:
        motif_choice = _pick_title_motif(
            title_text=title_text,
            deck_style=config.deck_style,
            subtitle_text=str(spec.get("subtitle", "")),
        )
        # Empty string = explicit opt-out via deck_style.title_motif: "none".
        if motif_choice:
            motif_fn = _TITLE_MOTIFS.get(motif_choice, _draw_title_motif_orbit)
            motif_fn(slide, palette=palette, slide_w=sw)

    # Bug 4 fix: Only draw footer when author actually provided one.
    # Do not fall back to "Prepared deck" or similar tells.
    title_footer_text = _slide_footer_text(spec)
    if not title_footer_text:
        date_value = _as_str(spec.get("date"), "")
        if date_value:
            title_footer_text = date_value
    if title_footer_text:
        _add_footer(
            slide,
            text=title_footer_text,
            palette=palette,
            preset=preset,
            slide_h=sh,
            margin_x=margin_x + 0.1,
            dark=True,
        )
    return slide


def _add_section_slide(
    prs: Presentation,
    spec: dict[str, Any],
    preset: Any,
    *,
    config: BuildConfig,
) -> Any:
    typography = preset.typography
    palette = preset.palette
    slide = prs.slides.add_slide(_blank_layout(prs))
    sw = _slide_w(prs)
    sh = _slide_h(prs)
    mx = preset.layout.margin_x

    _set_background(slide, palette["bg_primary"])
    _add_content_motif(slide, palette=palette, slide_w=sw, margin_x=mx)

    title_text = str(spec.get("title", "Section")).strip()
    _set_text_box(
        slide,
        text=title_text,
        x=mx,
        y=1.45,
        w=sw - mx * 2,
        h=1.0,
        font_name=_font_title(preset),
        font_size=max(
            typography.title_min,
            _clamp_title_font(typography, title_text, density=config.deck_style.visual_density) - 2,
        ),
        color_hex=palette["text_primary"],
        bold=True,
        margin=0.01,
    )
    subtitle = str(spec.get("subtitle", "")).strip()
    if subtitle:
        _set_text_box(
            slide,
            text=subtitle,
            x=mx,
            y=2.55,
            w=sw - mx * 2,
            h=0.7,
            font_name=_font_body(preset),
            font_size=_clamp_body_font(typography, typography.body_max),
            color_hex=palette["text_muted"],
            margin=0.01,
        )

    # Bug 6 enrichment: section dividers tend to leave the bottom ~75% of
    # the canvas empty. When the author has not provided bullets, body,
    # or caption, drop in a quiet decorative footprint (accent rail +
    # orbit dots) below the subtitle stack. This is enrichment, not
    # content, so the styling is deliberately low-contrast.
    has_section_content = (
        bool(str(spec.get("body", "")).strip())
        or bool(str(spec.get("caption", "")).strip())
        or (isinstance(spec.get("bullets"), list) and any(
            str(item if not isinstance(item, dict) else item.get("text", "")).strip()
            for item in spec.get("bullets", [])
        ))
    )
    if not has_section_content:
        _add_section_motif_enrichment(
            slide,
            palette=palette,
            slide_w=sw,
            slide_h=sh,
            margin_x=mx,
        )

    _add_footer(
        slide,
        text=_slide_footer_text(spec),
        palette=palette,
        preset=preset,
        slide_h=sh,
        margin_x=mx,
    )
    return slide


def _add_standard_content(
    slide: Any,
    *,
    lines: list[str],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    intro_paragraph: str | None = None,
    card_heading: str = "",
) -> None:
    x = layout.margin_x
    y = content_top
    w = slide_w - x * 2
    intro_text = (intro_paragraph or "").strip()

    # Fix 2b: single-card standard variant should expand the card to fill
    # the available content zone (content_top -> content_bottom). This gives
    # the slide a confident, deliberate block rather than a short card
    # floating above dead space. Fix 1: pair with MIDDLE vertical anchor so
    # bullets don't orphan at the top when they don't fill the card.
    # We cap at 85% of the available height to leave breathing room below
    # the card and stay within the preset's max_density budget (the density
    # lint counts card area against whole-slide area; a 100% fill plus header
    # and footer pushes density past most presets' 0.80 cap).
    available_h = max(1.2, content_bottom - y)
    expand_cap = max(2.5, min(available_h * 0.85, 4.6))

    # Card-heading resolution: outline can set `card_heading` explicitly.
    # Default: "" (no card heading) — the slide's own header already
    # frames the card, and a stale default like "Key Points" reads as
    # auto-generated filler. The caller in _add_content_slide passes
    # `card_heading` through from the outline spec.
    card_heading = (card_heading or "").strip()
    if intro_text:
        preferred = _preferred_card_height_with_intro(
            title_text=card_heading or "Key Points",  # measure uses a non-empty string
            intro_text=intro_text,
            body_lines=lines[:6],
            width_in=w,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            min_h=2.25,
            max_h=expand_cap,
        )
        # Fix 2b: grow to fill the zone, capping at the zone height minus a
        # small breathing margin so the card doesn't crowd the bottom edge.
        h = max(preferred, expand_cap)
        _add_card_with_intro(
            slide,
            x=x,
            y=y,
            w=w,
            h=h,
            title=card_heading,
            intro_text=intro_text,
            body_lines=lines[:6],
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key="accent_primary",
            body_vertical_anchor=MSO_ANCHOR.MIDDLE,
        )
        return

    preferred = _preferred_card_height(
        title_text=card_heading or "Key Points",
        body_lines=lines[:6],
        width_in=w,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        min_h=2.25,
        max_h=expand_cap,
    )
    h = max(preferred, expand_cap)
    _add_card(
        slide,
        x=x,
        y=y,
        w=w,
        h=h,
        title=card_heading,
        body_lines=lines[:6],
        palette=palette,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        accent_key="accent_primary",
        body_vertical_anchor=MSO_ANCHOR.MIDDLE,
    )


def _preferred_card_height_with_intro(
    *,
    title_text: str,
    intro_text: str,
    body_lines: list[str],
    width_in: float,
    typography: Any,
    preset: Any,
    rail_h: float,
    min_h: float,
    max_h: float,
) -> float:
    heading_font, title_h = _card_title_layout(title_text, width_in, typography, preset)
    usable_width = max(0.6, width_in - 0.28)
    intro_font = _clamp_body_font(typography, typography.body_max - 1)
    intro_h = _estimate_text_height([intro_text], width_in=usable_width, font_size_pt=intro_font)
    body_font = _card_body_font(body_lines, width_in=width_in, typography=typography)
    body_h = _estimate_text_height(body_lines[:6], width_in=usable_width, font_size_pt=body_font)
    preferred = rail_h + title_h + 0.16 + intro_h + 0.14 + body_h + 0.24
    return min(max(max(min_h, preferred), 0.9), max_h)


def _add_card_with_intro(
    slide: Any,
    *,
    x: float,
    y: float,
    w: float,
    h: float,
    title: str,
    intro_text: str,
    body_lines: list[str],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    rail_h: float,
    accent_key: str = "accent_primary",
    dark: bool = False,
    body_vertical_anchor: Any = None,
) -> None:
    fill_color = palette["bg_dark"] if dark else palette["surface"]
    line_color = palette["line"] if not dark else palette["accent_primary"]
    text_color = "FFFFFF" if dark else palette["text_primary"]
    muted_color = "CBD5E1" if dark else palette["text_muted"]

    card = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(h),
    )
    card.fill.solid()
    card.fill.fore_color.rgb = _rgb(fill_color)
    card.line.color.rgb = _rgb(line_color)
    card.line.width = Pt(1.25)

    rail = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(rail_h),
    )
    rail.fill.solid()
    rail.fill.fore_color.rgb = _rgb(palette.get(accent_key, palette["accent_primary"]))
    rail.line.fill.background()

    # Same empty-title-suppression behavior as _add_card: an empty title
    # skips the title row so the card's top decoration is just the rail.
    # Callers use this when the slide's own header already frames the
    # card (e.g., standard variant with a subtitle present).
    title_text = title.strip()
    suppress_title = title_text == ""
    title_font_name = _font_title(preset)
    if suppress_title:
        title_h = 0.0
    else:
        heading_font, title_h = _card_title_layout(title_text, w, typography, preset)
        _set_text_box(
            slide,
            text=title_text,
            x=x + 0.14,
            y=y + rail_h + 0.06,
            w=w - 0.28,
            h=max(0.36, title_h - 0.02),
            font_name=title_font_name,
            font_size=heading_font,
            color_hex=text_color,
            bold=True,
            margin=0.01,
        )

    usable_width = max(0.6, w - 0.28)
    intro_font = _clamp_body_font(typography, typography.body_max - 1)
    intro_h_est = _estimate_text_height([intro_text], width_in=usable_width, font_size_pt=intro_font)
    available_after_title = max(0.5, h - rail_h - title_h - 0.16 - 0.24)
    intro_h = min(max(0.32, intro_h_est + 0.04), available_after_title * 0.55)
    intro_y = y + rail_h + (title_h + 0.16 if not suppress_title else 0.12)
    _set_text_box(
        slide,
        text=intro_text,
        x=x + 0.14,
        y=intro_y,
        w=usable_width,
        h=intro_h,
        font_name=_font_body(preset),
        font_size=intro_font,
        color_hex=text_color,
        margin=0.01,
    )

    body_y = intro_y + intro_h + 0.10
    body_h = max(0.5, (y + h) - body_y - 0.12)
    body_font = _card_body_font(
        body_lines,
        width_in=w,
        typography=typography,
        available_height_in=body_h,
    )
    body_box = _set_lines_box(
        slide,
        lines=body_lines[:6],
        x=x + 0.14,
        y=body_y,
        w=usable_width,
        h=body_h,
        font_name=_font_body(preset),
        font_size=body_font,
        color_hex=muted_color,
        bullet=True,
        margin=0.01,
    )
    # Fix 1/2b: optionally center bullets vertically when the card has been
    # expanded to fill the content zone and the bullets don't fill the gap.
    if body_vertical_anchor is not None and body_box is not None:
        try:
            body_box.text_frame.vertical_anchor = body_vertical_anchor
        except Exception:
            pass


def _add_hero_content(
    slide: Any,
    *,
    lines: list[str],
    hero_image: Path | None,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    image_w = 3.25
    gutter = layout.gutter
    text_w = max(4.8, total_w - image_w - gutter)
    text_lines = (lines or ["Add core mission update."])[:6]
    card_h = _preferred_card_height(
        title_text="Key Message",
        body_lines=text_lines,
        width_in=text_w,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        min_h=2.35,
        max_h=max(2.8, min(content_bottom - y, 3.55)),
    )
    _add_card(
        slide,
        x=x,
        y=y,
        w=text_w,
        h=card_h,
        title="Key Message",
        body_lines=text_lines,
        palette=palette,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        accent_key="accent_primary",
    )

    image_h = min(max(2.2, card_h), max(2.2, content_bottom - y))
    frame_x = x + text_w + gutter
    frame = slide.shapes.add_shape(
        MSO_SHAPE.ROUNDED_RECTANGLE,
        Inches(frame_x),
        Inches(y),
        Inches(image_w),
        Inches(image_h),
    )
    frame.fill.solid()
    frame.fill.fore_color.rgb = _rgb(palette["surface"])
    frame.line.color.rgb = _rgb(palette["line"])
    frame.line.width = Pt(1.0)
    try:
        frame.adjustments[0] = 0.05
    except Exception:
        pass
    if hero_image and hero_image.exists():
        slide.shapes.add_picture(
            str(hero_image),
            Inches(frame_x + 0.03),
            Inches(y + 0.03),
            width=Inches(image_w - 0.06),
            height=Inches(image_h - 0.06),
        )
    else:
        _set_text_box(
            slide,
            text="Provide assets.hero_image or asset:<alias> for the hero visual.",
            x=frame_x + 0.14,
            y=y + max(0.6, image_h / 2.0 - 0.25),
            w=image_w - 0.28,
            h=0.5,
            font_name=_font_body(preset),
            font_size=max(typography.caption_min, 10),
            color_hex=palette["text_muted"],
            align=PP_ALIGN.CENTER,
            margin=0.01,
        )


def _image_contain_geometry(image_path: Path, x: float, y: float, w: float, h: float) -> tuple[float, float, float, float]:
    try:
        from PIL import Image as PILImage

        with PILImage.open(image_path) as im:
            img_w, img_h = im.size
        if img_w <= 0 or img_h <= 0:
            return x, y, w, h
        box_ratio = w / max(h, 0.01)
        img_ratio = img_w / img_h
        if img_ratio >= box_ratio:
            fit_w = w
            fit_h = w / img_ratio
        else:
            fit_h = h
            fit_w = h * img_ratio
        return x + (w - fit_w) / 2.0, y + (h - fit_h) / 2.0, fit_w, fit_h
    except Exception:
        return x, y, w, h


def _generated_image_metadata(image_path: Path | None, spec: dict[str, Any]) -> dict[str, str]:
    metadata: dict[str, str] = {}
    if image_path is not None:
        metadata_path = Path(f"{image_path}.metadata.json")
        if metadata_path.exists():
            try:
                raw = json.loads(metadata_path.read_text(encoding="utf-8"))
                if isinstance(raw, dict):
                    for key in ("model", "prompt", "revised_prompt", "purpose", "edit_note", "created_at"):
                        value = raw.get(key)
                        if value is not None:
                            metadata[key] = str(value)
            except Exception:
                pass
    slide_meta = spec.get("image_generation")
    if isinstance(slide_meta, dict):
        for key in ("model", "prompt", "revised_prompt", "purpose", "edit_note", "created_at"):
            value = slide_meta.get(key)
            if value is not None and str(value).strip():
                metadata[key] = str(value)
    return metadata


def _add_generated_image_content(
    slide: Any,
    *,
    image_path: Path | None,
    spec: dict[str, Any],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    panel_w = 3.0
    gutter = layout.gutter
    image_w = total_w - panel_w - gutter
    content_h = max(2.7, content_bottom - y)

    frame = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(image_w),
        Inches(content_h),
    )
    frame.fill.solid()
    frame.fill.fore_color.rgb = _rgb(palette["surface"])
    frame.line.color.rgb = _rgb(palette["line"])
    frame.line.width = Pt(1.0)

    if image_path and image_path.exists():
        ix, iy, iw, ih = _image_contain_geometry(image_path, x + 0.08, y + 0.08, image_w - 0.16, content_h - 0.16)
        slide.shapes.add_picture(str(image_path), Inches(ix), Inches(iy), width=Inches(iw), height=Inches(ih))
    else:
        _set_text_box(
            slide,
            text="Generated image asset missing. Rebuild with --allow-generated-images or replace this slide.",
            x=x + 0.35,
            y=y + content_h / 2.0 - 0.35,
            w=image_w - 0.70,
            h=0.70,
            font_name=_font_body(preset),
            font_size=max(typography.body_min, 14),
            color_hex=palette["text_muted"],
            align=PP_ALIGN.CENTER,
            margin=0.01,
        )

    meta = _generated_image_metadata(image_path, spec)
    panel_x = x + image_w + gutter
    panel = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(panel_x),
        Inches(y),
        Inches(panel_w),
        Inches(content_h),
    )
    panel.fill.solid()
    panel.fill.fore_color.rgb = _rgb(palette["bg_dark"])
    panel.line.fill.background()

    label_color = palette["accent_primary"]
    _set_text_box(
        slide,
        text="GENERATED VISUAL",
        x=panel_x + 0.20,
        y=y + 0.22,
        w=panel_w - 0.40,
        h=0.30,
        font_name=_font_title(preset),
        font_size=12,
        color_hex=label_color,
        bold=True,
        margin=0.01,
    )
    details = [
        f"Model: {meta.get('model', 'OpenAI image model')}",
        f"Purpose: {meta.get('purpose', 'Concept visual')}",
        "Delete this slide if source-backed imagery is preferred.",
    ]
    edit_note = meta.get("edit_note", "").strip()
    if edit_note:
        details.append(f"Edit note: {edit_note}")
    prompt = meta.get("prompt") or meta.get("revised_prompt") or ""
    if prompt:
        details.append(f"Prompt: {prompt[:280]}")
    _set_lines_box(
        slide,
        lines=details,
        x=panel_x + 0.20,
        y=y + 0.66,
        w=panel_w - 0.40,
        h=content_h - 0.88,
        font_name=_font_body(preset),
        font_size=12,
        color_hex="FFFFFF",
        bullet=False,
        margin=0.01,
    )


def _add_split_content(
    slide: Any,
    *,
    lines: list[str],
    highlights: list[str],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    left_w = total_w * 0.58
    right_w = total_w - left_w - layout.gutter
    left_lines = (lines or ["Add main narrative point."])[:6]
    right_lines = (highlights or lines[:4] or ["Add checklist item"])[:6]
    # Fix 2b: the left column of split is a single "primary" card and should
    # fill the available content zone. The right column (checklist) keeps its
    # compact, measured-height behavior. Like the standard variant we leave
    # breathing room so the preset's density budget still passes.
    available_h = max(1.6, content_bottom - y)
    expand_cap = max(2.8, min(available_h * 0.85, 4.6))
    left_preferred = _preferred_card_height(
        title_text="Main Narrative",
        body_lines=left_lines,
        width_in=left_w,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        min_h=2.1,
        max_h=expand_cap,
    )
    right_h = _preferred_card_height(
        title_text="Checklist",
        body_lines=right_lines,
        width_in=right_w,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        min_h=1.5,
        max_h=max(2.25, min(content_bottom - y, 3.1)),
    )
    left_box_h = max(left_preferred, expand_cap)
    compact_right = len(right_lines) <= 2 and max((len(line) for line in right_lines), default=0) <= 34
    if compact_right:
        right_box_h = min(max(1.55, right_h), max(1.8, left_box_h * 0.62))
    else:
        # Let the right card grow to match the left when it has substantive
        # content; cap it at the available zone so it still reads as a card.
        right_box_h = min(left_box_h, max(right_h, min(left_box_h, available_h)))
    # Fix 2: anchor body text to the TOP of split cards so the gap between the
    # card title and the body matches the normal padding. Previously the left
    # card used MSO_ANCHOR.MIDDLE, which leaves a visible half-card gap between
    # title and body when the card was sized for a density budget taller than
    # the body text. Both cards now anchor-top for a consistent rhythm.
    _add_card(
        slide,
        x=x,
        y=y,
        w=left_w,
        h=left_box_h,
        title="Main Narrative",
        body_lines=left_lines,
        palette=palette,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        accent_key="accent_primary",
        body_vertical_anchor=MSO_ANCHOR.TOP,
    )
    _add_card(
        slide,
        x=x + left_w + layout.gutter,
        y=y,
        w=right_w,
        h=right_box_h,
        title="Checklist",
        body_lines=right_lines,
        palette=palette,
        typography=typography,
        preset=preset,
        rail_h=layout.rail_height,
        accent_key="accent_secondary",
        body_vertical_anchor=MSO_ANCHOR.TOP,
    )


def _add_cards_grid_promoted(
    slide: Any,
    *,
    cards: list[dict[str, Any]],
    promote_index: int,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    icon_paths: list[Path | None] | None = None,
) -> None:
    """Asymmetric cards-3 layout: one card doubles as a left-column anchor,
    the other two stack on the right. Breaks the symmetric 3-up grid.
    """
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    gutter = layout.gutter
    # Left column (promoted): 2/3 width - gutter/2; right column: 1/3 width.
    left_w = total_w * 0.60 - gutter / 2.0
    right_w = total_w * 0.40 - gutter / 2.0
    total_h = max(2.6, content_bottom - y)
    small_h = (total_h - gutter) / 2.0
    icons = icon_paths or []
    icon_size = 0.5
    icon_pad = 0.15

    promote_index = max(0, min(2, promote_index))
    order = [promote_index] + [i for i in range(3) if i != promote_index]
    positions = [
        (x, y, left_w, total_h),                                   # big left card
        (x + left_w + gutter, y, right_w, small_h),                # top right
        (x + left_w + gutter, y + small_h + gutter, right_w, small_h),  # bottom right
    ]
    dark_bg = palette["bg_primary"].upper() == palette["bg_dark"].upper()

    for slot, idx in enumerate(order):
        card = cards[idx] if idx < len(cards) else {}
        title = str(card.get("title", f"Pillar {idx + 1}")).strip()
        body = card.get("body_lines") or card.get("body") or card.get("text") or ""
        if isinstance(body, list):
            body_lines = [str(item).strip() for item in body if str(item).strip()]
        else:
            body_lines = [
                part.strip() for part in str(body).replace("\n", ". ").split(".")
                if part.strip()
            ]
        if not body_lines:
            body_lines = [f"Define {title.lower()} execution detail."]
        accent_raw = str(card.get("accent", "")).strip()
        accent_key = accent_raw if accent_raw in palette else (
            "accent_primary" if slot == 0 else "accent_secondary"
        )
        icon_path = icons[idx] if idx < len(icons) else None
        cx, cy, cw, ch = positions[slot]
        # Promoted card gets more body lines; the small cards get tighter copy.
        max_lines = 7 if slot == 0 else 4
        _add_card(
            slide,
            x=cx,
            y=cy,
            w=cw,
            h=ch,
            title=title,
            body_lines=body_lines[:max_lines],
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key=accent_key,
            dark=dark_bg,
            icon_path=icon_path,
            icon_size=icon_size if icon_path else 0.0,
        )


def _add_cards_grid(
    slide: Any,
    *,
    cards: list[dict[str, Any]],
    columns: int,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    icon_paths: list[Path | None] | None = None,
    promote_card: int | None = None,
) -> None:
    columns = max(2, min(3, columns))
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    gutter = layout.gutter
    card_w = (total_w - gutter * (columns - 1)) / columns

    # Promoted-card asymmetric layout (cards-3 only). The promoted card
    # occupies the full left column (2×card_w + gutter); the other two
    # stack in the right column. Breaks the 3-up grid rigidity without
    # adding a new variant.
    if (
        columns == 3
        and promote_card is not None
        and 0 <= promote_card < len(cards)
        and len(cards) >= 3
    ):
        _add_cards_grid_promoted(
            slide,
            cards=cards,
            promote_index=int(promote_card),
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=slide_w,
            content_bottom=content_bottom,
            content_top=content_top,
            icon_paths=icon_paths,
        )
        return
    card_entries: list[tuple[str, list[str], str]] = []
    preferred_heights: list[float] = []
    min_card_h = 1.2 if columns == 2 else 1.15
    max_card_h = max(1.5, min(content_bottom - y, 2.6 if columns == 2 else 2.3))
    icon_size = 0.5
    icons = icon_paths or []
    icon_pad = 0.15
    for idx in range(columns):
        card = cards[idx] if idx < len(cards) else {}
        title = str(card.get("title", f"Pillar {idx + 1}")).strip()
        body = card.get("body_lines") or card.get("body") or card.get("text") or ""
        if isinstance(body, list):
            body_lines = [str(item).strip() for item in body if str(item).strip()]
        else:
            body_lines = [part.strip() for part in str(body).replace("\n", ". ").split(".") if part.strip()]
        if not body_lines:
            body_lines = [f"Define {title.lower()} execution detail."]
        accent = str(card.get("accent", "accent_primary")).strip() or "accent_primary"
        card_entries.append((title, body_lines[:5], accent if accent in palette else "accent_primary"))
        icon_here = idx < len(icons) and icons[idx] is not None
        icon_block = (icon_size + icon_pad) if icon_here else 0.0
        preferred_heights.append(
            _preferred_card_height(
                title_text=title,
                body_lines=body_lines[:5],
                width_in=card_w,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                min_h=min_card_h,
                max_h=max_card_h,
                icon_height=icon_block,
            )
        )
    card_h = max(preferred_heights) if preferred_heights else max(min_card_h, max_card_h)
    for idx, (title, body_lines, accent_key) in enumerate(card_entries):
        icon_path = icons[idx] if idx < len(icons) else None
        _add_card(
            slide,
            x=x + idx * (card_w + gutter),
            y=y,
            w=card_w,
            h=card_h,
            title=title,
            body_lines=body_lines,
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key=accent_key,
            dark=palette["bg_primary"].upper() == palette["bg_dark"].upper(),
            icon_path=icon_path,
            icon_size=icon_size if icon_path else 0.0,
        )


def _fact_body_lines(item: dict[str, str], *, include_source: bool = True) -> list[str]:
    lines: list[str] = []
    detail = _as_str(item.get("detail"), "")
    source = _as_str(item.get("source"), "")
    if detail:
        lines.extend([part.strip() for part in detail.replace("\n", ". ").split(".") if part.strip()])
    if include_source and source:
        lines.append(f"Source: {source}")
    return lines[:3]


def _preferred_fact_card_height(
    item: dict[str, str],
    *,
    width_in: float,
    typography: Any,
    preset: Any,
    rail_h: float,
    min_h: float,
    max_h: float,
    include_source: bool = True,
    icon_height: float = 0.0,
) -> float:
    label = _as_str(item.get("label"), "Key Fact")
    detail_lines = _fact_body_lines(item, include_source=include_source)
    label_font = max(typography.body_min, typography.caption_min + 2, min(typography.section_min, 15))
    detail_font = _card_body_font(
        detail_lines or [label],
        width_in=width_in,
        typography=typography,
    )
    value = _as_str(item.get("value"), "")
    value_h = 0.74 if value else 0.0
    label_h = _estimate_text_height([label], width_in=max(0.8, width_in - 0.28), font_size_pt=label_font)
    detail_h = _estimate_text_height(detail_lines, width_in=max(0.8, width_in - 0.28), font_size_pt=detail_font)
    preferred = rail_h + icon_height + 0.14 + value_h + label_h + detail_h + 0.24
    return min(max(max(min_h, preferred), 1.0), max_h)


def _add_fact_card(
    slide: Any,
    *,
    item: dict[str, str],
    x: float,
    y: float,
    w: float,
    h: float,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    rail_h: float,
    accent_key: str,
    include_source: bool = True,
    icon_path: Path | None = None,
    icon_size: float = 0.0,
) -> None:
    accent = accent_key if accent_key in palette else "accent_primary"
    card = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(h),
    )
    card.fill.solid()
    card.fill.fore_color.rgb = _rgb(palette["surface"])
    card.line.color.rgb = _rgb(palette["line"])
    card.line.width = Pt(1.2)

    rail = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(rail_h),
    )
    rail.fill.solid()
    rail.fill.fore_color.rgb = _rgb(palette[accent])
    rail.line.fill.background()

    cursor_y = y + rail_h + 0.10

    # Icon: rendered centered above the value, inside the tile (below rail).
    icon_pad = 0.15 if (icon_path is not None and icon_size > 0) else 0.0
    if icon_path is not None and icon_size > 0:
        icon_left = x + (w - icon_size) / 2.0
        _add_icon(slide, path=icon_path, x=icon_left, y=cursor_y, size=icon_size)
        cursor_y += icon_size + icon_pad

    value = _as_str(item.get("value"), "")
    if value:
        value_font = max(typography.section_max - 1, typography.title_min)
        if w < 4.0:
            value_font = min(value_font, 20)
        _set_text_box(
            slide,
            text=value,
            x=x + 0.14,
            y=cursor_y,
            w=w - 0.28,
            h=0.62,
            font_name=_font_title(preset),
            font_size=value_font,
            color_hex=palette[accent],
            bold=True,
            margin=0.01,
        )
        cursor_y += 0.72

    label = _as_str(item.get("label"), "Key Fact")
    label_font = max(typography.body_min, typography.caption_min + 2, min(typography.section_min, 15))
    label_lines = max(1, min(2, _estimate_text_lines(label, width_in=max(0.8, w - 0.28), font_size_pt=label_font)))
    label_h = min(0.50, max(0.22, 0.12 + label_lines * 0.16))
    _set_text_box(
        slide,
        text=label,
        x=x + 0.14,
        y=cursor_y,
        w=w - 0.28,
        h=label_h,
        font_name=_font_body(preset),
        font_size=label_font,
        color_hex=palette["text_primary"],
        bold=True,
        margin=0.01,
    )
    cursor_y += label_h + 0.08

    detail_lines = _fact_body_lines(item, include_source=include_source)
    if detail_lines:
        body_h = max(0.30, h - (cursor_y - y) - 0.12)
        body_font = _card_body_font(
            detail_lines,
            width_in=max(0.8, w - 0.28),
            typography=typography,
            available_height_in=max(0.24, body_h - 0.02),
        )
        _set_lines_box(
            slide,
            lines=detail_lines,
            x=x + 0.14,
            y=cursor_y,
            w=w - 0.28,
            h=body_h,
            font_name=_font_body(preset),
            font_size=body_font,
            color_hex=palette["text_muted"],
            bullet=False,
            margin=0.01,
        )


def _add_stats_content(
    slide: Any,
    *,
    facts: list[dict[str, str]],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    icon_paths: list[Path | None] | None = None,
) -> None:
    items = facts[:4] if facts else [
        {"value": "42%", "label": "Primary outcome", "detail": "Add sourced evidence detail.", "source": ""},
        {"value": "6 mo", "label": "Time window", "detail": "Add timing or throughput context.", "source": ""},
        {"value": "$12M", "label": "Envelope", "detail": "Add bound or planning detail.", "source": ""},
    ]
    count = len(items)
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    gutter = layout.gutter
    columns = 2 if count >= 4 else max(1, count)
    rows = max(1, int(math.ceil(count / float(columns))))
    card_w = (total_w - gutter * (columns - 1)) / columns
    total_h = max(1.6, content_bottom - y)
    max_card_h = (total_h - gutter * (rows - 1)) / rows

    icons = icon_paths or []
    icon_size = 0.4
    icon_pad = 0.15

    row_heights = [1.25 for _ in range(rows)]
    prepared: list[tuple[int, int, dict[str, str]]] = []
    for index, item in enumerate(items):
        row = index // columns
        col = index % columns
        prepared.append((row, col, item))
        icon_here = index < len(icons) and icons[index] is not None
        icon_block = (icon_size + icon_pad) if icon_here else 0.0
        row_heights[row] = max(
            row_heights[row],
            _preferred_fact_card_height(
                item,
                width_in=card_w,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                min_h=1.22,
                max_h=max(1.45, min(2.2, max_card_h)),
                icon_height=icon_block,
            ),
        )

    row_h = min(max_card_h, max(row_heights))
    for idx_item, (row, col, item) in enumerate(prepared):
        accent = _as_str(item.get("accent"), "")
        if accent not in palette:
            accent = "accent_primary" if (row * columns + col) % 2 == 0 else "accent_secondary"
        icon_path = icons[idx_item] if idx_item < len(icons) else None
        _add_fact_card(
            slide,
            item=item,
            x=x + col * (card_w + gutter),
            y=y + row * (row_h + gutter),
            w=card_w,
            h=row_h,
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key=accent,
            icon_path=icon_path,
            icon_size=icon_size if icon_path else 0.0,
        )


def _chart_colors(chart_payload: dict[str, Any], palette: dict[str, str]) -> list[str]:
    colors: list[str] = []
    options = chart_payload.get("options") if isinstance(chart_payload.get("options"), dict) else {}
    raw_colors = options.get("chartColors")
    if isinstance(raw_colors, list):
        for value in raw_colors:
            color = _as_str(value, "").replace("#", "")
            if len(color) == 6:
                colors.append(color.upper())
    for key in ("color1", "color2", "color3", "color4"):
        color = _as_str(chart_payload.get(key), "").replace("#", "")
        if len(color) == 6:
            colors.append(color.upper())
    fallback = [
        palette["accent_primary"],
        palette["accent_secondary"],
        palette["text_muted"],
        palette["line"],
    ]
    colors.extend([item for item in fallback if item not in colors])
    return colors


def _chart_type_from_payload(chart_payload: dict[str, Any]) -> XL_CHART_TYPE:
    chart_type = _as_str(chart_payload.get("type"), "bar").lower()
    if chart_type == "line":
        return XL_CHART_TYPE.LINE_MARKERS
    if chart_type == "pie":
        return XL_CHART_TYPE.PIE
    return XL_CHART_TYPE.COLUMN_CLUSTERED


def _legend_position(value: str) -> XL_LEGEND_POSITION:
    token = value.strip().lower()
    if token == "l":
        return XL_LEGEND_POSITION.LEFT
    if token == "t":
        return XL_LEGEND_POSITION.TOP
    if token == "b":
        return XL_LEGEND_POSITION.BOTTOM
    return XL_LEGEND_POSITION.RIGHT


def _add_chart_frame(
    slide: Any,
    *,
    chart_payload: dict[str, Any],
    x: float,
    y: float,
    w: float,
    h: float,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
) -> None:
    frame = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(x),
        Inches(y),
        Inches(w),
        Inches(h),
    )
    frame.fill.solid()
    frame.fill.fore_color.rgb = _rgb(palette["surface"])
    frame.line.color.rgb = _rgb(palette["line"])
    frame.line.width = Pt(1.2)

    # Fix 1: when chart payload arrived but failed schema validation, render
    # a bold red banner so the slide visibly flags the problem instead of
    # silently showing a generic "provide chart data" placeholder.
    error_reason = chart_payload.get("__error__") if isinstance(chart_payload, dict) else None
    if error_reason:
        banner_h = min(0.72, max(0.48, h * 0.22))
        banner_y = y + max(0.10, (h - banner_h) / 2.0)
        banner = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(x + 0.20),
            Inches(banner_y),
            Inches(max(1.0, w - 0.40)),
            Inches(banner_h),
        )
        banner.fill.solid()
        banner.fill.fore_color.rgb = _rgb("B91C1C")
        banner.line.color.rgb = _rgb("7F1D1D")
        banner.line.width = Pt(1.0)
        _set_text_box(
            slide,
            text="Chart data malformed \u2014 see QA report",
            x=x + 0.28,
            y=banner_y + 0.02,
            w=max(0.8, w - 0.56),
            h=banner_h - 0.04,
            font_name=_font_body(preset),
            font_size=max(typography.caption_min + 2, 13),
            color_hex="FFFFFF",
            bold=True,
            align=PP_ALIGN.CENTER,
            margin=0.02,
        )
        return

    if not chart_payload.get("series"):
        _set_text_box(
            slide,
            text="Provide chart data as an inline chart object or a staged chart:<alias> JSON file.",
            x=x + 0.20,
            y=y + max(0.9, h / 2.0 - 0.22),
            w=w - 0.40,
            h=0.44,
            font_name=_font_body(preset),
            font_size=max(typography.caption_min + 1, 11),
            color_hex=palette["text_muted"],
            align=PP_ALIGN.CENTER,
            margin=0.01,
        )
        return

    data = ChartData()
    primary_series = chart_payload["series"][0]
    data.categories = primary_series["labels"]
    if _chart_type_from_payload(chart_payload) == XL_CHART_TYPE.PIE:
        data.add_series(primary_series["name"], primary_series["values"])
    else:
        for item in chart_payload["series"]:
            data.add_series(item["name"], item["values"])

    chart_box_y = y + 0.14
    chart_box_h = max(1.6, h - 0.24)
    graphic_frame = slide.shapes.add_chart(
        _chart_type_from_payload(chart_payload),
        Inches(x + 0.16),
        Inches(chart_box_y),
        Inches(max(2.2, w - 0.30)),
        Inches(chart_box_h),
        data,
    )
    chart = graphic_frame.chart
    chart.has_title = False
    options = chart_payload.get("options") if isinstance(chart_payload.get("options"), dict) else {}
    colors = _chart_colors(chart_payload, palette)
    show_legend = bool(options.get("showLegend", len(chart.series) > 1 or _chart_type_from_payload(chart_payload) == XL_CHART_TYPE.PIE))
    chart.has_legend = show_legend
    if chart.has_legend:
        chart.legend.position = _legend_position(_as_str(options.get("legendPos"), "r"))
        chart.legend.include_in_layout = False
        try:
            chart.legend.font.name = _font_body(preset)
            chart.legend.font.size = Pt(max(typography.caption_min, 10))
        except Exception:
            pass

    if _chart_type_from_payload(chart_payload) == XL_CHART_TYPE.PIE:
        series = chart.series[0]
        series.has_data_labels = True
        try:
            chart.plots[0].data_labels.position = XL_LABEL_POSITION.OUTSIDE_END
        except Exception:
            pass
        for index, point in enumerate(series.points):
            color = colors[index % len(colors)]
            point.format.fill.solid()
            point.format.fill.fore_color.rgb = _rgb(color)
    else:
        for index, series in enumerate(chart.series):
            color = colors[index % len(colors)]
            series.format.fill.solid()
            series.format.fill.fore_color.rgb = _rgb(color)
            series.format.line.color.rgb = _rgb(color)
            try:
                series.format.line.width = Pt(2.2)
            except Exception:
                pass
        try:
            chart.value_axis.has_major_gridlines = True
            chart.value_axis.major_gridlines.format.line.color.rgb = _rgb(palette["line"])
            chart.value_axis.tick_labels.font.name = _font_caption(preset)
            chart.value_axis.tick_labels.font.size = Pt(max(typography.caption_min, 10))
            chart.category_axis.tick_labels.font.name = _font_caption(preset)
            chart.category_axis.tick_labels.font.size = Pt(max(typography.caption_min, 10))
            cat_axis_title = _as_str(options.get("catAxisTitle"), "")
            if cat_axis_title:
                chart.category_axis.has_title = True
                chart.category_axis.axis_title.text_frame.text = cat_axis_title
            val_axis_title = _as_str(options.get("valAxisTitle"), "")
            if val_axis_title:
                chart.value_axis.has_title = True
                chart.value_axis.axis_title.text_frame.text = val_axis_title
        except Exception:
            pass


def _add_chart_content(
    slide: Any,
    *,
    chart_payload: dict[str, Any],
    facts: list[dict[str, str]],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    note_text: str,
) -> None:
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    gutter = layout.gutter
    fact_items = facts[:3]
    note_h = 0.0
    facts_h = 0.0
    if fact_items:
        columns = len(fact_items)
        card_w = (total_w - gutter * (columns - 1)) / columns
        pref_h = [
            _preferred_fact_card_height(
                item,
                width_in=card_w,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                min_h=1.05,
                max_h=1.95,
                include_source=False,
            )
            for item in fact_items
        ]
        facts_h = min(1.95, max(pref_h)) if pref_h else 1.35
    if note_text and not fact_items:
        note_h = 0.50
    chart_h = max(2.2, content_bottom - y - facts_h - note_h - (gutter if fact_items else 0.0) - (0.10 if note_h else 0.0))
    _add_chart_frame(
        slide,
        chart_payload=chart_payload,
        x=x,
        y=y,
        w=total_w,
        h=chart_h,
        palette=palette,
        typography=typography,
        preset=preset,
    )
    if fact_items:
        columns = len(fact_items)
        card_w = (total_w - gutter * (columns - 1)) / columns
        fact_y = y + chart_h + gutter
        for index, item in enumerate(fact_items):
            accent = _as_str(item.get("accent"), "")
            if accent not in palette:
                accent = "accent_primary" if index % 2 == 0 else "accent_secondary"
            _add_fact_card(
                slide,
                item=item,
                x=x + index * (card_w + gutter),
                y=fact_y,
                w=card_w,
                h=facts_h,
                palette=palette,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                accent_key=accent,
                include_source=False,
            )
        return

    if note_text and note_h > 0.0:
        _set_text_box(
            slide,
            text=note_text,
            x=x,
            y=y + chart_h + 0.08,
            w=total_w,
            h=note_h,
            font_name=_font_caption(preset),
            font_size=max(typography.caption_min, 11),
            color_hex=palette["text_muted"],
            margin=0.01,
        )


def _add_timeline_content(
    slide: Any,
    *,
    milestones: list[dict[str, Any]],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    icon_paths: list[Path | None] | None = None,
) -> None:
    x = layout.margin_x
    y = max(1.5, content_top + 0.04)
    total_w = slide_w - x * 2
    items = milestones[:4] if milestones else [
        {"label": "Q1", "title": "Discover", "body": "Define baseline"},
        {"label": "Q2", "title": "Build", "body": "Pilot delivery"},
        {"label": "Q3", "title": "Scale", "body": "Expand coverage"},
        {"label": "Q4", "title": "Optimize", "body": "Harden operations"},
    ]
    count = len(items)
    gutter = layout.gutter
    card_w = (total_w - gutter * (count - 1)) / max(1, count)
    card_w = max(2.15, min(2.65, card_w))
    content_w = card_w * count + gutter * (count - 1)
    start_x = x + max(0.0, (total_w - content_w) / 2.0)
    icons = icon_paths or []
    has_any_icon = any(p is not None for p in icons)
    icon_size = 0.5
    icon_pad = 0.15
    # When icons are present, shift the timeline line down so icons fit above
    # the dot label without overlapping the slide header.
    icon_offset = (icon_size + icon_pad) if has_any_icon else 0.0
    line_y = y + 1.1 + icon_offset
    _add_line(
        slide,
        x=start_x,
        y=line_y,
        w=content_w,
        color_hex=palette["line"],
        width_pt=5.0,
    )

    # Render icons centered above each dot (above the line_y marker).
    if has_any_icon:
        for idx in range(count):
            icon_path = icons[idx] if idx < len(icons) else None
            if icon_path is None:
                continue
            card_x = start_x + idx * (card_w + gutter)
            cx = card_x + card_w / 2.0
            icon_top = line_y - icon_offset
            icon_left = cx - icon_size / 2.0
            _add_icon(slide, path=icon_path, x=icon_left, y=icon_top, size=icon_size)

    # Bug 3 fix: the timeline used to render the milestone label twice —
    # once via the dot marker (drawn below) and again as the first body
    # line inside the card. Keep only the dot label, write the label
    # text inside the dot, and drop it from the card body.
    card_h = 1.8
    for idx, item in enumerate(items):
        title = str(item.get("title", item.get("label", f"Step {idx + 1}"))).strip()
        body = str(item.get("body", item.get("text", ""))).strip()
        body_lines = [part.strip() for part in body.split(".") if part.strip()]
        card_h = max(
            card_h,
            _preferred_card_height(
                title_text=title,
                body_lines=body_lines[:4],
                width_in=card_w,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                min_h=1.55,
                max_h=max(1.7, min(2.2, content_bottom - (line_y + 0.34))),
            ),
        )
    card_h = min(card_h, max(1.7, min(2.2, content_bottom - (line_y + 0.34))))
    marker_height = 0.44
    label_font_size = max(10, min(14, int(typography.caption_max)))
    for idx, item in enumerate(items):
        card_x = start_x + idx * (card_w + gutter)
        cx = card_x + card_w / 2.0
        accent_hex = palette["accent_primary"] if idx % 2 == 0 else palette["accent_secondary"]

        label = str(item.get("label", f"{idx + 1}")).strip()
        # Size the marker to fit the label. Single-digit "1"/"Q1" →
        # circle. Multi-char "3 PM"/"Step 1" → pill. Width scales with
        # label length; height stays constant so the baseline aligns.
        label_chars = len(label)
        if label_chars <= 2:
            marker_w = marker_height  # circle
            shape = MSO_SHAPE.OVAL
        else:
            # ~0.10" per char + 0.24" padding, clamped to card width.
            marker_w = min(card_w - 0.20, max(marker_height, 0.24 + label_chars * 0.10))
            shape = MSO_SHAPE.ROUNDED_RECTANGLE
        marker = slide.shapes.add_shape(
            shape,
            Inches(cx - marker_w / 2.0),
            Inches(line_y - marker_height / 2.0),
            Inches(marker_w),
            Inches(marker_height),
        )
        marker.fill.solid()
        marker.fill.fore_color.rgb = _rgb(accent_hex)
        marker.line.color.rgb = _rgb(palette["bg_primary"])
        marker.line.width = Pt(1)

        if label:
            # Render the label as readable white text centered in the marker.
            label_box = _set_text_box(
                slide,
                text=label,
                x=cx - marker_w / 2.0,
                y=line_y - marker_height / 2.0,
                w=marker_w,
                h=marker_height,
                font_name=_font_title(preset),
                font_size=label_font_size,
                color_hex="FFFFFF",
                bold=True,
                align=PP_ALIGN.CENTER,
                margin=0.02,
            )
            try:
                label_box.text_frame.vertical_anchor = MSO_ANCHOR.MIDDLE
            except Exception:
                pass

        body_lines = [
            part.strip()
            for part in str(item.get("body", item.get("text", ""))).strip().split(".")
            if part.strip()
        ][:4]
        _add_card(
            slide,
            x=card_x,
            y=line_y + 0.34,
            w=card_w,
            h=card_h,
            title=str(item.get("title", item.get("label", f"Step {idx + 1}"))).strip(),
            body_lines=body_lines,
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key="accent_primary" if idx % 2 == 0 else "accent_secondary",
        )


def _add_matrix_content(
    slide: Any,
    *,
    quadrants: list[dict[str, Any]],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    icon_paths: list[Path | None] | None = None,
) -> None:
    x = layout.margin_x
    y = content_top
    total_w = slide_w - x * 2
    total_h = max(2.8, content_bottom - y)
    gutter = layout.gutter
    card_w = (total_w - gutter) / 2
    max_card_h = (total_h - gutter) / 2

    items = quadrants[:4] if quadrants else [
        {"title": "Strengths", "body": "Current advantages and proof points"},
        {"title": "Weaknesses", "body": "Known gaps and constraints"},
        {"title": "Opportunities", "body": "High-probability expansion paths"},
        {"title": "Threats", "body": "External risks to mitigate"},
    ]
    icons = list(icon_paths) if icon_paths else []
    row_pref = [1.35, 1.35]
    prepared: list[tuple[int, int, str, list[str]]] = []
    for idx in range(4):
        item = items[idx] if idx < len(items) else {}
        row = idx // 2
        col = idx % 2
        title = str(item.get("title", f"Quadrant {idx + 1}")).strip()
        body = str(item.get("body", item.get("text", ""))).strip()
        body_lines = [part.strip() for part in body.replace("\n", ". ").split(".") if part.strip()]
        if not body_lines:
            body_lines = [f"Add {title.lower()} content."]
        prepared.append((row, col, title, body_lines[:4]))
        row_pref[row] = max(
            row_pref[row],
            _preferred_card_height(
                title_text=title,
                body_lines=body_lines[:4],
                width_in=card_w,
                typography=typography,
                preset=preset,
                rail_h=layout.rail_height,
                min_h=1.35,
                max_h=max(1.5, min(2.0, max_card_h)),
            ),
        )
    card_h = min(max_card_h, max(row_pref))
    # Matrix cards are ~2x2 and shorter than cards-3 columns, so icons use a
    # smaller footprint (0.4") than the 0.5" used in cards-3.
    icon_size = 0.4
    for idx, (row, col, title, body_lines) in enumerate(prepared):
        card_x = x + col * (card_w + gutter)
        card_y = y + row * (card_h + gutter)
        icon_path = icons[idx] if idx < len(icons) else None
        _add_card(
            slide,
            x=card_x,
            y=card_y,
            w=card_w,
            h=card_h,
            title=title,
            body_lines=body_lines,
            palette=palette,
            typography=typography,
            preset=preset,
            rail_h=layout.rail_height,
            accent_key="accent_primary" if ((row * 2) + col) % 2 == 0 else "accent_secondary",
            icon_path=icon_path,
            icon_size=icon_size if icon_path else 0.0,
        )


def _luminance(hex_color: str) -> float:
    """WCAG-style relative luminance [0..1] for a 6-char hex color."""
    try:
        h = hex_color.lstrip("#")
        if len(h) != 6:
            return 0.5
        r, g, b = int(h[0:2], 16) / 255.0, int(h[2:4], 16) / 255.0, int(h[4:6], 16) / 255.0
    except (ValueError, TypeError):
        return 0.5

    def _chan(v: float) -> float:
        return v / 12.92 if v <= 0.03928 else ((v + 0.055) / 1.055) ** 2.4

    return 0.2126 * _chan(r) + 0.7152 * _chan(g) + 0.0722 * _chan(b)


def _contrast_ok(fg: str, bg: str, threshold: float = 0.35) -> bool:
    """True when fg and bg luminances differ by more than `threshold`.
    Not full WCAG — just a "will you see it at all" check that rejects
    near-black-on-black or near-white-on-white.
    """
    if not fg or not bg:
        return False
    return abs(_luminance(fg) - _luminance(bg)) >= threshold


def _kpi_value_font_size(value_text: str) -> int:
    """Length-aware autosize for kpi-hero value. Prevents overflow on long values.

    ≤4 chars (e.g., '42%'): 120pt
    5-6 chars (e.g., '98.5%', '$1.2M'): 96pt
    7-8 chars (e.g., '2,456ms'): 72pt
    ≥9 chars: 60pt
    """
    n = len(value_text.strip())
    if n <= 4:
        return 120
    if n <= 6:
        return 96
    if n <= 8:
        return 72
    return 60


def _add_kpi_hero_content(
    slide: Any,
    *,
    value: str,
    label: str,
    context: str,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
    dark: bool = True,
) -> None:
    """Single-KPI poster layout.

    Renders with a dark background by default — kpi-hero's job is to break
    the light-content rhythm, not just the layout rhythm. Set `dark=False`
    in the outline (`"theme": "light"`) to keep it on the deck's default bg.
    """
    value_text = str(value).strip() or "?"
    label_text = str(label).strip()
    context_text = str(context).strip()

    # Resolve colors against the (potentially inverted) palette locally.
    # Only the 4 keys kpi-hero touches — keeps the palette-swap scope
    # minimal per earlier review. Background is set by the caller in
    # _add_content_slide based on the same `dark` decision.
    if dark:
        # Pick the accent that actually reads on a dark bg. Most presets
        # have a bright accent_secondary (amber, orange) — that's the
        # default. But presets like editorial-minimal use accent_secondary
        # as a dark neutral, which would render invisible on pure black.
        # Fall back to accent_primary when the secondary is too dark.
        bg_color = palette.get("bg_dark", "0F172A")
        sec = palette.get("accent_secondary", "")
        prim = palette.get("accent_primary", "F59E0B")
        value_color = sec if _contrast_ok(sec, bg_color) else prim
        if not _contrast_ok(value_color, bg_color):
            value_color = "F59E0B"  # last-resort amber always reads on dark
        label_color = "FFFFFF"
        context_color = "CBD5E1"
    else:
        value_color = palette["accent_primary"]
        label_color = palette["text_primary"]
        context_color = palette["text_muted"]

    content_h = max(2.5, content_bottom - content_top)
    value_font = _kpi_value_font_size(value_text)
    value_h = min(2.6, max(1.6, value_font / 72.0 * 1.35))
    label_font = min(typography.section_max + 6, 28)
    label_h = 0.55
    context_font = min(typography.caption_max + 1, 16)
    context_h = 0.42

    total = value_h + 0.18 + (label_h if label_text else 0.0) + \
            (0.10 + context_h if context_text else 0.0)
    value_y = content_top + max(0.10, (content_h - total) / 2.0)

    _set_text_box(
        slide,
        text=value_text,
        x=layout.margin_x,
        y=value_y,
        w=slide_w - layout.margin_x * 2,
        h=value_h,
        font_name=_font_title(preset),
        font_size=value_font,
        color_hex=value_color,
        bold=True,
        align=PP_ALIGN.CENTER,
        margin=0.02,
    )

    next_y = value_y + value_h + 0.18
    if label_text:
        _set_text_box(
            slide,
            text=label_text,
            x=layout.margin_x,
            y=next_y,
            w=slide_w - layout.margin_x * 2,
            h=label_h,
            font_name=_font_title(preset),
            font_size=label_font,
            color_hex=label_color,
            bold=True,
            align=PP_ALIGN.CENTER,
            margin=0.02,
        )
        next_y += label_h + 0.10

    if context_text:
        _set_text_box(
            slide,
            text=context_text,
            x=layout.margin_x + 1.2,
            y=next_y,
            w=slide_w - (layout.margin_x + 1.2) * 2,
            h=context_h,
            font_name=_font_caption(preset),
            font_size=context_font,
            color_hex=context_color,
            align=PP_ALIGN.CENTER,
            margin=0.02,
        )


def _add_comparison_content(
    slide: Any,
    *,
    left: dict[str, Any],
    right: dict[str, Any],
    verdict: str,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    """Two-column comparison with dividing rule. Optional verdict strip at bottom."""
    margin_x = layout.margin_x
    gutter = 0.45
    usable_w = slide_w - margin_x * 2
    col_w = (usable_w - gutter) / 2.0

    has_verdict = bool(verdict and verdict.strip())
    verdict_h = 0.6 if has_verdict else 0.0
    verdict_gap = 0.20 if has_verdict else 0.0

    col_top = content_top + 0.05
    col_bottom = content_bottom - verdict_h - verdict_gap
    col_h = max(2.4, col_bottom - col_top)

    def _render_column(side_spec: dict[str, Any], x: float, accent_key: str) -> None:
        side_title = str(side_spec.get("title", "")).strip()
        body = side_spec.get("body", "")
        if isinstance(body, list):
            body_lines = [str(item).strip() for item in body if str(item).strip()]
        else:
            body_lines = [
                part.strip() for part in str(body).replace("\n", ". ").split(".")
                if part.strip()
            ]

        # No accent rule above the title — that pattern ("thin colored line
        # under/over titles") is a documented AI-slide tell. Instead the
        # column gets its identity from (1) oversized, colored title, and
        # (2) the vertical divider between columns.
        title_y = col_top
        title_font = min(typography.section_max + 4, 28)
        title_h = 0.72
        _set_text_box(
            slide,
            text=side_title or "—",
            x=x,
            y=title_y,
            w=col_w,
            h=title_h,
            font_name=_font_title(preset),
            font_size=title_font,
            color_hex=palette[accent_key],
            bold=True,
            margin=0.01,
        )

        body_y = title_y + title_h + 0.14
        body_h = max(0.8, col_h - (body_y - col_top) - 0.08)
        body_font = _card_body_font(
            body_lines if body_lines else [""],
            width_in=col_w,
            typography=typography,
            available_height_in=body_h,
        )
        _set_lines_box(
            slide,
            lines=body_lines or ["Add comparison content."],
            x=x,
            y=body_y,
            w=col_w,
            h=body_h,
            font_name=_font_body(preset),
            font_size=body_font,
            color_hex=palette["text_primary"],
            bullet=True,
            margin=0.04,
        )

    _render_column(left, margin_x, "accent_primary")
    _render_column(right, margin_x + col_w + gutter, "accent_secondary")

    # Vertical divider rule between columns — rendered as a thin filled
    # rectangle (not a connector) so it stays visible at 1.5pt and reads
    # clearly as "A vs B" rather than two parallel lists.
    divider_x = margin_x + col_w + gutter / 2.0 - 0.02
    divider_y_top = col_top + 0.06
    divider_height = col_h - 0.12
    divider = slide.shapes.add_shape(
        MSO_SHAPE.RECTANGLE,
        Inches(divider_x),
        Inches(divider_y_top),
        Inches(0.04),
        Inches(divider_height),
    )
    divider.fill.solid()
    divider.fill.fore_color.rgb = _rgb(palette.get("line", palette["text_muted"]))
    divider.line.fill.background()

    if has_verdict:
        verdict_y = col_bottom + verdict_gap
        verdict_x = margin_x + 0.6
        verdict_w = usable_w - 1.2
        # Dark strip gives the synthesis visual weight that reads
        # immediately — a subtle surface panel gets lost. Left accent
        # bar reinforces this is the "answer" of the comparison.
        strip = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(verdict_x),
            Inches(verdict_y),
            Inches(verdict_w),
            Inches(verdict_h),
        )
        strip.fill.solid()
        strip.fill.fore_color.rgb = _rgb(palette.get("bg_dark", "0F172A"))
        strip.line.fill.background()

        accent_bar = slide.shapes.add_shape(
            MSO_SHAPE.RECTANGLE,
            Inches(verdict_x),
            Inches(verdict_y),
            Inches(0.08),
            Inches(verdict_h),
        )
        accent_bar.fill.solid()
        accent_bar.fill.fore_color.rgb = _rgb(palette.get("accent_primary", "14B8A6"))
        accent_bar.line.fill.background()

        _set_text_box(
            slide,
            text=str(verdict).strip(),
            x=verdict_x + 0.24,
            y=verdict_y + 0.04,
            w=verdict_w - 0.40,
            h=verdict_h - 0.08,
            font_name=_font_body(preset),
            font_size=min(typography.body_max + 1, 16),
            color_hex="FFFFFF",
            bold=True,
            align=PP_ALIGN.CENTER,
            margin=0.04,
        )


def _add_table_content(
    slide: Any,
    *,
    headers: list[str],
    rows: list[list[Any]],
    caption: str,
    column_weights: list[float] | None,
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    """Native OOXML table renderer. Used when parallel-field data reads
    better as a grid than as cards. Header row is accent-colored; body
    rows alternate surface for readability.
    """
    margin_x = layout.margin_x
    usable_w = slide_w - margin_x * 2
    has_caption = bool(caption and caption.strip())
    caption_gap = 0.14
    caption_h = 0.42 if has_caption else 0.0

    available_h = max(1.4, content_bottom - content_top - caption_h - caption_gap)

    col_count = max(1, len(headers))
    row_count = len(rows) + 1  # + header row

    # Row height: header slightly taller than body rows.
    # Target total table height: row_count * ~0.5" but clamp to available.
    ideal_row_h = 0.55
    ideal_header_h = 0.62
    total_ideal = ideal_header_h + (row_count - 1) * ideal_row_h
    scale = min(1.0, available_h / total_ideal) if total_ideal > 0 else 1.0
    header_h = max(0.42, ideal_header_h * scale)
    body_row_h = max(0.36, ideal_row_h * scale)
    table_h = header_h + (row_count - 1) * body_row_h

    table_shape = slide.shapes.add_table(
        row_count,
        col_count,
        Inches(margin_x),
        Inches(content_top),
        Inches(usable_w),
        Inches(table_h),
    )
    table = table_shape.table

    # Column widths — proportional to weights, or equal if not provided.
    weights = column_weights if column_weights and len(column_weights) == col_count else None
    if weights:
        total = sum(weights)
        if total <= 0:
            weights = None
    if weights:
        running = 0.0
        for i, w in enumerate(weights):
            col_w = usable_w * (w / sum(weights))
            table.columns[i].width = Inches(col_w)
            running += col_w
    else:
        col_w = usable_w / col_count
        for i in range(col_count):
            table.columns[i].width = Inches(col_w)

    # Row heights
    table.rows[0].height = Inches(header_h)
    for i in range(1, row_count):
        table.rows[i].height = Inches(body_row_h)

    header_fill = palette.get("accent_primary", "14B8A6")
    header_text = "FFFFFF"
    body_text = palette.get("text_primary", "0F172A")
    body_fill_a = palette.get("surface", "FFFFFF")
    body_fill_b = palette.get("bg_primary", "F4F8FB")
    header_font_size = min(typography.body_max + 1, 15)
    body_font_size = min(typography.body_max, 13)

    font_title = _font_title(preset)
    font_body = _font_body(preset)

    for col_idx, header in enumerate(headers):
        cell = table.cell(0, col_idx)
        cell.fill.solid()
        cell.fill.fore_color.rgb = _rgb(header_fill)
        cell.text = ""  # clear default
        tf = cell.text_frame
        tf.margin_left = Inches(0.08)
        tf.margin_right = Inches(0.08)
        tf.margin_top = Inches(0.04)
        tf.margin_bottom = Inches(0.04)
        tf.word_wrap = True
        p = tf.paragraphs[0]
        p.text = str(header).strip()
        _set_paragraph_style(
            p,
            font_name=font_title,
            font_size=header_font_size,
            color_hex=header_text,
            bold=True,
        )

    for row_idx, row in enumerate(rows, start=1):
        fill_color = body_fill_a if (row_idx % 2) == 1 else body_fill_b
        for col_idx in range(col_count):
            value = row[col_idx] if col_idx < len(row) else ""
            cell = table.cell(row_idx, col_idx)
            cell.fill.solid()
            cell.fill.fore_color.rgb = _rgb(fill_color)
            cell.text = ""
            tf = cell.text_frame
            tf.margin_left = Inches(0.08)
            tf.margin_right = Inches(0.08)
            tf.margin_top = Inches(0.04)
            tf.margin_bottom = Inches(0.04)
            tf.word_wrap = True
            p = tf.paragraphs[0]
            p.text = str(value).strip()
            _set_paragraph_style(
                p,
                font_name=font_body,
                font_size=body_font_size,
                color_hex=body_text,
            )

    if has_caption:
        caption_y = content_top + table_h + caption_gap
        _set_text_box(
            slide,
            text=caption.strip(),
            x=margin_x,
            y=caption_y,
            w=usable_w,
            h=caption_h,
            font_name=_font_caption(preset),
            font_size=min(typography.caption_max + 1, 12),
            color_hex=palette.get("text_muted", "475569"),
            margin=0.01,
        )


def _add_image_sidebar_content(
    slide: Any,
    *,
    image_path: Path | None,
    image_side: str,
    sidebar_sections: list[dict[str, Any]],
    palette: dict[str, str],
    typography: Any,
    preset: Any,
    layout: Any,
    slide_w: float,
    content_bottom: float,
    content_top: float,
) -> None:
    """Image on one side, sidebar with 2-4 labeled sections on the other.

    The dominant lab-data / research-deck composition: a chart, figure,
    or photo takes the visual weight; the sidebar gives the reader
    labeled sections of bullets explaining it. Inspired by the TB
    LAMP-Seq results slides (Run 1/2/3) and the CDC workflow slide.
    """
    margin_x = layout.margin_x
    usable_w = slide_w - margin_x * 2
    content_h = max(2.8, content_bottom - content_top)
    gap = 0.32

    side = (image_side or "left").strip().lower()
    if side not in ("left", "right"):
        side = "left"

    # Image takes ~60% of usable width when present, sidebar takes rest.
    if image_path is not None and image_path.exists():
        image_w = usable_w * 0.58
        sidebar_w = usable_w - image_w - gap
    else:
        image_w = 0.0
        sidebar_w = usable_w

    if side == "left":
        image_x = margin_x
        sidebar_x = margin_x + image_w + (gap if image_w else 0.0)
    else:
        sidebar_x = margin_x
        image_x = margin_x + sidebar_w + gap

    # Place the image — aspect-ratio preserving within the allotted box.
    if image_path is not None and image_path.exists() and image_w > 0:
        try:
            from PIL import Image as PILImage
            with PILImage.open(image_path) as im:
                iw, ih = im.size
            ratio = ih / iw if iw > 0 else 0.75
        except Exception:
            ratio = 0.6
        img_h_fit = min(content_h, image_w * ratio)
        img_w_fit = img_h_fit / ratio if ratio > 0 else image_w
        img_w_fit = min(image_w, img_w_fit)
        img_h_fit = img_w_fit * ratio
        # Center vertically in content zone
        img_y = content_top + (content_h - img_h_fit) / 2.0
        slide.shapes.add_picture(
            str(image_path),
            Inches(image_x),
            Inches(img_y),
            width=Inches(img_w_fit),
            height=Inches(img_h_fit),
        )

    # Sidebar sections — bold label + bullet list per section.
    sections = [s for s in (sidebar_sections or []) if isinstance(s, dict)][:4]
    if not sections:
        return
    n = len(sections)
    # Allocate vertical space per section, account for inter-section gap.
    section_gap = 0.18
    total_gaps = section_gap * max(0, n - 1)
    section_h = (content_h - total_gaps) / n
    label_font = min(typography.section_max, 18)
    body_font = max(typography.body_min, min(typography.body_max, 13))

    for idx, section in enumerate(sections):
        sy = content_top + idx * (section_h + section_gap)
        label = str(section.get("title", "")).strip()
        body_raw = section.get("body", "")
        if isinstance(body_raw, list):
            lines = [str(item).strip() for item in body_raw if str(item).strip()]
        else:
            lines = [
                part.strip()
                for part in str(body_raw).replace("\n", "\n").split("\n")
                if part.strip()
            ]

        if label:
            _set_text_box(
                slide,
                text=label,
                x=sidebar_x,
                y=sy,
                w=sidebar_w,
                h=0.40,
                font_name=_font_title(preset),
                font_size=label_font,
                color_hex=palette.get("accent_primary", "14B8A6"),
                bold=True,
                margin=0.01,
            )
            body_y = sy + 0.48
        else:
            body_y = sy

        body_h = max(0.4, section_h - (body_y - sy) - 0.04)
        if lines:
            _set_lines_box(
                slide,
                lines=lines,
                x=sidebar_x,
                y=body_y,
                w=sidebar_w,
                h=body_h,
                font_name=_font_body(preset),
                font_size=body_font,
                color_hex=palette.get("text_primary", "0F172A"),
                bullet=True,
                margin=0.01,
            )


def _add_content_slide(
    prs: Presentation,
    spec: dict[str, Any],
    preset: Any,
    *,
    config: BuildConfig,
    render_mode: str,
    page_index: int | None = None,
    page_total: int | None = None,
) -> Any:
    typography = preset.typography
    palette = preset.palette
    layout = preset.layout
    visual_intent = _as_str(spec.get("visual_intent"), "").lower()
    if visual_intent == "flow":
        return _add_flow_diagram_layout(
            prs,
            spec,
            preset=preset,
            outline_dir=config.outline_dir,
        )

    slide = prs.slides.add_slide(_blank_layout(prs))
    sw = _slide_w(prs)
    sh = _slide_h(prs)
    chart_payload = _normalize_chart_payload(spec, config.outline_dir)
    facts = _normalize_fact_items(spec, chart_payload)
    footer_spec = spec
    if not spec.get("sources") and chart_payload.get("sources"):
        footer_spec = deepcopy(spec)
        footer_spec["sources"] = chart_payload["sources"]
    footer = _slide_footer_text(footer_spec)
    has_footer = bool(footer)
    thumbnails = spec.get("thumbnails")
    thumb_items = [str(item).strip() for item in thumbnails] if isinstance(thumbnails, list) else []
    lines = _extract_lines(spec)
    hero_asset = _asset_from_spec(spec, "hero_image", config.outline_dir)
    variant = str(spec.get("variant", "")).strip().lower()
    if visual_intent == "hero" and hero_asset and hero_asset.exists():
        variant = "hero"

    if not variant:
        if isinstance(spec.get("cards"), list):
            variant = "cards-3" if len(spec["cards"]) >= 3 else "cards-2"
        elif isinstance(spec.get("milestones"), list):
            variant = "timeline"
        elif isinstance(spec.get("quadrants"), list):
            variant = "matrix"
        elif chart_payload:
            variant = "chart"
        elif facts:
            variant = "stats"
        elif isinstance(spec.get("highlights"), list):
            variant = "split"
        elif visual_intent == "comparison":
            variant = "split"
        else:
            variant = "standard"

    right_reserve = 0.0
    if thumb_items:
        right_reserve = max(right_reserve, 3.05)
    if variant == "hero":
        right_reserve = max(right_reserve, 3.55)
    content_bottom = _content_bottom(sh, has_footer=has_footer, layout=layout)

    # Rhythm-breaking dark treatment for kpi-hero. A single dark content
    # slide in a light-bg deck snaps the eye's rhythm far more than any
    # new layout on the same background. Only 4 palette keys actually get
    # swapped (bg, title text, subtitle text, footer text) — the variant
    # body renders its own colors internally.
    kpi_dark = variant == "kpi-hero" and _as_str(spec.get("theme"), "dark").lower() != "light"
    if kpi_dark:
        _set_background(slide, palette["bg_dark"])
    else:
        _set_background(slide, palette["bg_primary"])
    _add_background_image(
        slide,
        spec,
        slide_w=sw,
        slide_h=sh,
        palette=palette,
        outline_dir=config.outline_dir,
    )
    if render_mode == "express" and not kpi_dark:
        _add_content_motif(slide, palette=palette, slide_w=sw, margin_x=layout.margin_x)
    header_palette = palette
    if kpi_dark:
        header_palette = dict(palette)
        header_palette["text_primary"] = "FFFFFF"
        header_palette["text_muted"] = "CBD5E1"
    header_bottom = _content_header(
        slide,
        title=str(spec.get("title", "Content")),
        subtitle=str(spec.get("subtitle", "")),
        palette=header_palette,
        typography=typography,
        preset=preset,
        margin_x=layout.margin_x,
        right_reserve=right_reserve,
    )
    content_top = max(1.35, header_bottom + 0.12)
    if thumb_items:
        _add_thumbnail_strip(
            slide,
            thumbnails=thumb_items,
            slide_w=sw,
            margin_x=layout.margin_x,
            palette=palette,
            outline_dir=config.outline_dir,
        )

    # Icon support (v1): cards-2/cards-3, timeline, stats.
    # Other variants log a debug warning and ignore icons rather than crash.
    has_icons_requested = isinstance(_slide_assets(spec).get("icons"), list) and bool(
        _slide_assets(spec).get("icons")
    )
    ICON_SUPPORTED_VARIANTS = {"cards-2", "cards-3", "timeline", "stats", "matrix"}
    if has_icons_requested and variant not in ICON_SUPPORTED_VARIANTS:
        print(
            f"[build_deck] debug: assets.icons ignored on variant '{variant}' "
            f"(supported: cards-2, cards-3, timeline, stats, matrix)",
            file=sys.stderr,
        )

    if variant == "hero":
        _add_hero_content(
            slide,
            lines=lines,
            hero_image=hero_asset,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    elif variant == "generated-image":
        generated_asset = _asset_from_spec(spec, "generated_image", config.outline_dir)
        if generated_asset is None:
            generated_asset = _asset_from_spec(spec, "hero_image", config.outline_dir)
        if generated_asset is None:
            generated_asset = _asset_from_spec(spec, "image", config.outline_dir)
        _add_generated_image_content(
            slide,
            image_path=generated_asset,
            spec=spec,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    elif variant in {"cards-2", "cards-3"}:
        cards = spec.get("cards")
        if not isinstance(cards, list):
            cards = []
        if not cards and lines:
            for idx, line in enumerate(lines[:3]):
                cards.append(
                    {
                        "title": f"Pillar {idx + 1}",
                        "body": line,
                        "accent": "accent_primary" if idx % 2 == 0 else "accent_secondary",
                    }
                )
        columns = 2 if variant == "cards-2" else 3
        icon_paths = _slide_icon_paths(spec, config.outline_dir, columns)
        promote_raw = spec.get("promote_card")
        promote_index: int | None = None
        if columns == 3 and isinstance(promote_raw, int) and 0 <= promote_raw < len(cards):
            promote_index = promote_raw
        _add_cards_grid(
            slide,
            cards=cards,
            columns=columns,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            icon_paths=icon_paths,
            promote_card=promote_index,
        )
    elif variant == "split":
        highlights = spec.get("highlights")
        if not isinstance(highlights, list):
            highlights = []
        _add_split_content(
            slide,
            lines=lines,
            highlights=[str(item) for item in highlights],
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    elif variant == "timeline":
        milestones = spec.get("milestones")
        if not isinstance(milestones, list):
            milestones = []
        milestone_count = min(4, len(milestones)) if milestones else 4
        icon_paths = _slide_icon_paths(spec, config.outline_dir, milestone_count)
        _add_timeline_content(
            slide,
            milestones=milestones,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            icon_paths=icon_paths,
        )
    elif variant == "matrix":
        quadrants = spec.get("quadrants")
        if not isinstance(quadrants, list):
            quadrants = []
        icon_paths = _slide_icon_paths(spec, config.outline_dir, 4)
        _add_matrix_content(
            slide,
            quadrants=quadrants,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            icon_paths=icon_paths,
        )
    elif variant == "stats":
        fact_count = min(4, len(facts)) if facts else 3
        icon_paths = _slide_icon_paths(spec, config.outline_dir, fact_count)
        _add_stats_content(
            slide,
            facts=facts,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            icon_paths=icon_paths,
        )
    elif variant == "chart":
        _add_chart_content(
            slide,
            chart_payload=chart_payload,
            facts=facts,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            note_text=_as_str(spec.get("message") or spec.get("caption"), "") or _as_str(chart_payload.get("notes"), ""),
        )
    elif variant == "kpi-hero":
        _add_kpi_hero_content(
            slide,
            value=_as_str(spec.get("value"), ""),
            label=_as_str(spec.get("label"), ""),
            context=_as_str(spec.get("context"), ""),
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            dark=kpi_dark,
        )
    elif variant == "comparison-2col":
        left_spec = spec.get("left") if isinstance(spec.get("left"), dict) else {}
        right_spec = spec.get("right") if isinstance(spec.get("right"), dict) else {}
        _add_comparison_content(
            slide,
            left=left_spec,
            right=right_spec,
            verdict=_as_str(spec.get("verdict"), ""),
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    elif variant == "image-sidebar":
        image_asset = _asset_from_spec(spec, "hero_image", config.outline_dir)
        if image_asset is None:
            image_asset = _asset_from_spec(spec, "image", config.outline_dir)
        sections = spec.get("sidebar_sections") if isinstance(spec.get("sidebar_sections"), list) else []
        _add_image_sidebar_content(
            slide,
            image_path=image_asset,
            image_side=_as_str(spec.get("image_side"), "left"),
            sidebar_sections=sections,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    elif variant == "table":
        headers = spec.get("headers") if isinstance(spec.get("headers"), list) else []
        rows = spec.get("rows") if isinstance(spec.get("rows"), list) else []
        cw_raw = spec.get("column_weights")
        column_weights = (
            [float(w) for w in cw_raw]
            if isinstance(cw_raw, list) and all(isinstance(w, (int, float)) for w in cw_raw)
            else None
        )
        _add_table_content(
            slide,
            headers=[str(h) for h in headers],
            rows=[list(r) if isinstance(r, list) else [r] for r in rows],
            caption=_as_str(spec.get("caption"), ""),
            column_weights=column_weights,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
        )
    else:
        # Bug 1 fix: on standard variant, when the outline supplies both
        # `body` and `bullets`, pass `body` through as an intro paragraph
        # rendered above the bullets inside the card. `_extract_lines`
        # already prefers bullets when both are present, so `lines` holds
        # the bullets and the body text stays separate.
        raw_body = _as_str(spec.get("body"), "").strip()
        raw_bullets = spec.get("bullets")
        has_bullets = isinstance(raw_bullets, list) and any(
            str(item if not isinstance(item, dict) else item.get("text", "")).strip()
            for item in raw_bullets
        )
        intro_paragraph = raw_body if raw_body and has_bullets else None
        card_heading_override = _as_str(spec.get("card_heading"), "").strip()
        _add_standard_content(
            slide,
            lines=lines,
            palette=palette,
            typography=typography,
            preset=preset,
            layout=layout,
            slide_w=sw,
            content_bottom=content_bottom,
            content_top=content_top,
            intro_paragraph=intro_paragraph,
            card_heading=card_heading_override,
        )

    if render_mode == "express":
        _add_visual_assets(
            slide,
            spec=spec,
            slide_w=sw,
            margin_x=layout.margin_x,
            outline_dir=config.outline_dir,
        )

    # Universal summary callout (the "oval box for key points" pattern
    # from lab-data decks). Sits above the footer on any variant when
    # the outline sets `summary_callout`. Skip on variants that already
    # carry their own bottom emphasis (kpi-hero is the callout itself;
    # comparison-2col already has a verdict strip; pull-quote is a
    # single-element variant).
    callout_text = _as_str(spec.get("summary_callout"), "")
    callout_conflicts = {
        "kpi-hero",
        "generated-image",
        "comparison-2col" if _as_str(spec.get("verdict"), "") else "",
        "pull-quote",
    }
    if callout_text and variant not in callout_conflicts:
        _add_summary_callout(
            slide,
            text=callout_text,
            palette=palette,
            preset=preset,
            slide_w=sw,
            slide_h=sh,
            margin_x=layout.margin_x,
            has_footer=bool(footer),
        )

    show_page = bool(config.deck_style.show_page_numbers)
    if footer or show_page:
        _add_footer(
            slide,
            text=footer or "",
            palette=palette,
            preset=preset,
            slide_h=sh,
            margin_x=layout.margin_x,
            dark=kpi_dark,
            page_index=page_index if show_page else None,
            page_total=page_total if show_page else None,
            slide_w=sw,
        )
    return slide


def _build(prs: Presentation, data: dict[str, Any], preset: Any, *, config: BuildConfig) -> int:
    slides = data.get("slides")
    count = 0

    if not isinstance(slides, list) or len(slides) == 0:
        title = str(data.get("title", "")).strip()
        subtitle = str(data.get("subtitle", "")).strip()
        if title or subtitle:
            _add_title_slide(
                prs,
                {"title": title or "Presentation", "subtitle": subtitle},
                preset,
                config=config,
            )
            return 1
        raise ValueError("Outline JSON must include a non-empty slides array.")

    for index, item in enumerate(slides, start=1):
        if not isinstance(item, dict):
            continue
        slide_type = str(item.get("type", "content")).strip().lower()
        spec = _apply_emoji_policy(
            item,
            slide_type=slide_type,
            preset_name=preset.name,
            emoji_mode=config.deck_style.emoji_mode,
        )
        resolved_mode = _resolve_render_mode(
            spec,
            slide_type=slide_type,
            deck_density=config.deck_style.visual_density,
        )
        try:
            if slide_type == "title":
                slide = _add_title_slide(prs, spec, preset, config=config)
                if resolved_mode == "express":
                    _add_visual_assets(
                        slide,
                        spec=spec,
                        slide_w=_slide_w(prs),
                        margin_x=preset.layout.margin_x,
                        outline_dir=config.outline_dir,
                    )
            elif slide_type == "section":
                slide = _add_section_slide(prs, spec, preset, config=config)
                if resolved_mode == "express":
                    _add_visual_assets(
                        slide,
                        spec=spec,
                        slide_w=_slide_w(prs),
                        margin_x=preset.layout.margin_x,
                        outline_dir=config.outline_dir,
                    )
            else:
                _add_content_slide(
                    prs,
                    spec,
                    preset,
                    config=config,
                    render_mode=resolved_mode,
                    page_index=index,
                    page_total=len(slides),
                )
        except Exception as exc:
            if resolved_mode != "express":
                raise
            # Hard fallback: express path must never break full deck generation.
            print(
                f"[warn] slide {index}: express render failed ({exc}); "
                "falling back to reliable mode."
            )
            if slide_type == "title":
                _add_title_slide(prs, spec, preset, config=config)
            elif slide_type == "section":
                _add_section_slide(prs, spec, preset, config=config)
            else:
                _add_content_slide(
                    prs,
                    spec,
                    preset,
                    config=config,
                    render_mode="reliable",
                    page_index=index,
                    page_total=len(slides),
                )
        count += 1

    return count


def _args() -> argparse.Namespace:
    parser = argparse.ArgumentParser(description="Build a .pptx deck from JSON outline.")
    parser.add_argument("--outline", required=True, help="Path to outline JSON file")
    parser.add_argument("--output", required=True, help="Output .pptx file")
    parser.add_argument("--template", help="Optional template .pptx")
    parser.add_argument(
        "--style-preset",
        default="executive-clinical",
        help="Style preset for typography defaults",
    )
    parser.add_argument(
        "--layout-16x9",
        action="store_true",
        help="Force 16:9 wide layout (13.333x7.5) when no template is used",
    )
    parser.add_argument(
        "--font-pair",
        help="Optional font pair key override (for example: editorial_serif_v1)",
    )
    parser.add_argument(
        "--palette-key",
        help="Optional palette key override (for example: climate_coastal_v1)",
    )
    parser.add_argument("--overwrite", action="store_true", help="Overwrite output if it exists")
    return parser.parse_args()


def main() -> int:
    args = _args()
    outline_path = Path(args.outline).expanduser().resolve()
    output_path = Path(args.output).expanduser().resolve()
    template_path = Path(args.template).expanduser().resolve() if args.template else None
    base_preset = get_style_preset(args.style_preset)

    if not outline_path.exists():
        raise FileNotFoundError(f"Outline file not found: {outline_path}")
    if template_path and not template_path.exists():
        raise FileNotFoundError(f"Template file not found: {template_path}")
    if output_path.exists() and not args.overwrite:
        raise FileExistsError(f"Output exists: {output_path}. Use --overwrite to replace it.")

    with outline_path.open("r", encoding="utf-8") as handle:
        data = json.load(handle)
    if not isinstance(data, dict):
        raise ValueError("Outline JSON root must be an object.")
    build_config = _load_build_config(data, outline_path.parent)

    deck_style = build_config.deck_style
    if args.font_pair:
        deck_style = DeckStyleConfig(
            font_pair=str(args.font_pair).strip().lower(),
            palette_key=deck_style.palette_key,
            visual_density=deck_style.visual_density,
            emoji_mode=deck_style.emoji_mode,
            title_motif=deck_style.title_motif,
        )
    if args.palette_key:
        deck_style = DeckStyleConfig(
            font_pair=deck_style.font_pair,
            palette_key=str(args.palette_key).strip().lower(),
            visual_density=deck_style.visual_density,
            emoji_mode=deck_style.emoji_mode,
            title_motif=deck_style.title_motif,
        )
    build_config = BuildConfig(
        outline_dir=build_config.outline_dir,
        deck_style=deck_style,
        compliance=build_config.compliance,
    )

    try:
        font_tokens = get_font_pair(build_config.deck_style.font_pair)
    except ValueError as exc:
        print(f"[warn] {exc} Falling back to {DEFAULT_FONT_PAIR_KEY}.")
        font_tokens = get_font_pair(DEFAULT_FONT_PAIR_KEY)

    runtime_preset = RuntimePreset(
        name=base_preset.name,
        palette=_resolve_palette(base_preset.palette, build_config.deck_style.palette_key),
        typography=base_preset.typography,
        layout=base_preset.layout,
        font_pair={
            "title": font_tokens.title,
            "body": font_tokens.body,
            "caption": font_tokens.caption,
        },
    )
    _enforce_compliance(data, build_config)

    prs = Presentation(str(template_path)) if template_path else Presentation()
    if not template_path and args.layout_16x9:
        prs.slide_width = Inches(13.333)
        prs.slide_height = Inches(7.5)
    elif not template_path and not args.layout_16x9:
        # Default to 16:9 for reproducible deck QA in this workspace.
        prs.slide_width = Inches(13.333)
        prs.slide_height = Inches(7.5)

    slide_count = _build(prs, data, runtime_preset, config=build_config)
    output_path.parent.mkdir(parents=True, exist_ok=True)
    prs.save(str(output_path))
    print(
        f"Wrote {slide_count} slide(s) to {output_path} "
        f"with style preset '{runtime_preset.name}', "
        f"font pair '{build_config.deck_style.font_pair}', "
        f"palette '{build_config.deck_style.palette_key or 'preset-default'}'."
    )
    return 0


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except Exception as exc:  # pragma: no cover - CLI error path
        print(f"Error: {exc}")
        raise SystemExit(1)
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 197kUpdated Claude CodeCodexVerifiedInstall