skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/design/skills/deck-builder/scripts/build_deck.py

@@ -0,0 +1,1134 @@
+#!/usr/bin/env python3
+"""Build a .pptx from a JSON deck spec.
+
+The spec schema is documented in templates/deck-spec.json. Top-level fields:
+- title:     overall deck title
+- audience:  archetype (informational; doesn't change rendering)
+- aspect:    "16:9" (default) or "4:3" — ignored when a template is supplied
+- template:  path to a .pptx/.potx brand template; its masters, theme fonts,
+             colors and slide size are inherited
+- layout_map: logical layout -> template layout name or index (template mode)
+- palette:   a hex-color block, or a name resolvable from templates/palettes.json
+- brand:     path to a brand.json (the brand-kit skill writes one) or the same object
+             inline. It supplies anything the spec leaves out: palette colours, template,
+             logo files and fonts. --brand on the command line overrides it.
+- slide_numbers: true/false (default: true when the deck has more than 10 slides)
+- slides:    list of slide specs, each with a `layout` field
+
+Supported layouts: title, section, content, two_column, big_number, quote,
+image, table, chart, closing.
+
+Usage:
+    python3 build_deck.py <spec.json> [-o output.pptx] [--strict] [--brand brand.json]
+"""
+
+from __future__ import annotations
+
+import argparse
+import copy
+import json
+import shutil
+import sys
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from pptx import Presentation
+from pptx.chart.data import CategoryChartData
+from pptx.dml.color import RGBColor
+from pptx.enum.chart import XL_CHART_TYPE, XL_LEGEND_POSITION
+from pptx.enum.shapes import MSO_SHAPE, PP_PLACEHOLDER
+from pptx.enum.text import MSO_ANCHOR, PP_ALIGN
+from pptx.util import Emu, Inches, Pt
+
+# The design canvas every hardcoded position below is expressed in. Real slide
+# geometry comes from Canvas, which scales these to the actual deck size.
+DESIGN_W_IN = 13.333
+DESIGN_H_IN = 7.5
+
+ASPECTS = {
+    "16:9": (13.333, 7.5),
+    "4:3": (10.0, 7.5),
+    "16:10": (12.0, 7.5),
+}
+
+DEFAULT_PALETTE = {
+    "primary": "#1A2A6C",
+    "secondary": "#4A5A8C",
+    "accent": "#FDBB2D",
+    "background": "#FFFFFF",
+    "text": "#222222",
+}
+
+CHART_TYPES = {
+    "column": XL_CHART_TYPE.COLUMN_CLUSTERED,
+    "bar": XL_CHART_TYPE.BAR_CLUSTERED,
+    "line": XL_CHART_TYPE.LINE_MARKERS,
+    "pie": XL_CHART_TYPE.PIE,
+    "doughnut": XL_CHART_TYPE.DOUGHNUT,
+    "stacked_column": XL_CHART_TYPE.COLUMN_STACKED,
+    "stacked_bar": XL_CHART_TYPE.BAR_STACKED,
+}
+
+RASTER_OK = {".png", ".jpg", ".jpeg", ".gif", ".bmp", ".tif", ".tiff"}
+
+WARNINGS: list[str] = []
+
+
+# Set from brand.json in build(): fonts for the built-in design, and the logo files placed on
+# its slides. A supplied template already carries its own fonts and logo, so these are only
+# used when a slide renders on the built-in design.
+BRAND = {"heading_font": None, "body_font": None, "logo": None, "logo_on_dark": None}
+
+
+def warn(msg: str) -> None:
+    WARNINGS.append(msg)
+    sys.stderr.write(f"warning: {msg}\n")
+
+
+def die(msg: str) -> None:
+    sys.stderr.write(f"error: {msg}\n")
+    sys.exit(1)
+
+
+# ----------------------------------------------------------------- geometry
+
+
+@dataclass
+class Canvas:
+    """Maps design-canvas inches onto the real slide, whatever size it is."""
+
+    w: int  # EMU
+    h: int  # EMU
+
+    @property
+    def xr(self) -> float:
+        return self.w / Inches(DESIGN_W_IN)
+
+    @property
+    def yr(self) -> float:
+        return self.h / Inches(DESIGN_H_IN)
+
+    @property
+    def fr(self) -> float:
+        """Font scale — driven by the tighter axis, floored so text stays legible."""
+        return max(0.7, min(self.xr, self.yr))
+
+    def x(self, inches: float) -> int:
+        return int(Inches(inches) * self.xr)
+
+    def y(self, inches: float) -> int:
+        return int(Inches(inches) * self.yr)
+
+    def pt(self, size: float) -> Pt:
+        return Pt(round(size * self.fr, 1))
+
+    @property
+    def right_margin_w(self) -> int:
+        """Full content width at the standard 0.75in gutter."""
+        return self.w - 2 * self.x(0.75)
+
+
+@dataclass
+class Region:
+    """A rectangle content gets drawn into."""
+
+    left: int
+    top: int
+    width: int
+    height: int
+
+
+def default_region(c: Canvas, *, below_title_bar: bool = True) -> Region:
+    top = c.y(1.5) if below_title_bar else c.y(0.9)
+    return Region(c.x(0.75), top, c.right_margin_w, c.h - top - c.y(0.6))
+
+
+# ----------------------------------------------------------------- palette
+
+
+def hex_color(s: str) -> RGBColor:
+    return RGBColor.from_string(str(s).lstrip("#").upper())
+
+
+def resolve_palette(p, script_dir: Path) -> dict:
+    """Accepts a dict (use directly) or a string name (look up in templates/palettes.json)."""
+    if isinstance(p, dict):
+        return {**DEFAULT_PALETTE, **p}
+    if isinstance(p, str):
+        palettes_path = script_dir.parent / "templates" / "palettes.json"
+        if not palettes_path.exists():
+            warn(f"palettes file missing at {palettes_path}; using defaults")
+            return DEFAULT_PALETTE
+        all_palettes = json.loads(palettes_path.read_text())
+        if p not in all_palettes:
+            warn(f"palette {p!r} not found; using defaults")
+            return DEFAULT_PALETTE
+        return {**DEFAULT_PALETTE, **all_palettes[p]}
+    return DEFAULT_PALETTE
+
+
+def series_colors(palette: dict, n: int) -> list:
+    base = [palette["primary"], palette["accent"], palette["secondary"],
+            palette["text"], "#7A8BB5", "#C9A227"]
+    return [base[i % len(base)] for i in range(n)]
+
+
+# ----------------------------------------------------------------- template
+
+
+def _potx_to_pptx(src: Path, tmpdir: Path) -> Path:
+    """python-pptx refuses a .potx content type. Repack it as a .pptx."""
+    dst = tmpdir / (src.stem + ".pptx")
+    with zipfile.ZipFile(src) as zin, zipfile.ZipFile(dst, "w", zipfile.ZIP_DEFLATED) as zout:
+        for item in zin.infolist():
+            data = zin.read(item.filename)
+            if item.filename == "[Content_Types].xml":
+                text = data.decode("utf-8")
+                text = text.replace(
+                    "presentationml.template.main+xml",
+                    "presentationml.presentation.main+xml",
+                ).replace(
+                    "presentationml.template.macroEnabled.main+xml",
+                    "presentationml.presentation.macroEnabled.main+xml",
+                )
+                data = text.encode("utf-8")
+            zout.writestr(item, data)
+    return dst
+
+
+def clear_slides(prs) -> int:
+    """Drop any slides the template shipped with — we want its masters, not its content."""
+    sld_id_lst = prs.slides._sldIdLst
+    removed = 0
+    for sld_id in list(sld_id_lst):
+        prs.part.drop_rel(sld_id.rId)
+        sld_id_lst.remove(sld_id)
+        removed += 1
+    return removed
+
+
+def open_presentation(spec: dict, spec_dir: Path, tmpdir: Path):
+    """Return (prs, canvas, using_template)."""
+    tmpl = spec.get("template")
+    if not tmpl:
+        prs = Presentation()
+        aspect = spec.get("aspect", "16:9")
+        if aspect not in ASPECTS:
+            warn(f"unknown aspect {aspect!r}; using 16:9")
+            aspect = "16:9"
+        w_in, h_in = ASPECTS[aspect]
+        prs.slide_width = Inches(w_in)
+        prs.slide_height = Inches(h_in)
+        return prs, Canvas(prs.slide_width, prs.slide_height), False
+
+    path = Path(tmpl).expanduser()
+    if not path.is_absolute():
+        path = (spec_dir / path).resolve()
+    if not path.exists():
+        die(f"template not found: {path}")
+    if path.suffix.lower() in (".potx", ".potm"):
+        path = _potx_to_pptx(path, tmpdir)
+    elif path.suffix.lower() not in (".pptx", ".pptm"):
+        die(f"template must be .pptx or .potx, got {path.suffix!r}")
+
+    try:
+        prs = Presentation(str(path))
+    except Exception as exc:  # noqa: BLE001 — surface the real reason, don't mask it
+        die(f"could not open template {path}: {exc}")
+
+    dropped = clear_slides(prs)
+    if dropped:
+        print(f"template: dropped {dropped} sample slide(s), kept masters and layouts")
+    if spec.get("aspect"):
+        warn("`aspect` ignored — the template's own slide size wins")
+    return prs, Canvas(prs.slide_width, prs.slide_height), True
+
+
+def list_layouts(prs) -> str:
+    return "\n".join(f"  [{i}] {lay.name}" for i, lay in enumerate(prs.slide_layouts))
+
+
+def find_layout(prs, ref):
+    """Resolve a template layout by index, exact name, or case-insensitive substring."""
+    if isinstance(ref, int):
+        try:
+            return prs.slide_layouts[ref]
+        except IndexError:
+            warn(f"layout index {ref} out of range ({len(prs.slide_layouts)} layouts)")
+            return None
+    if not isinstance(ref, str):
+        return None
+    for lay in prs.slide_layouts:
+        if lay.name == ref:
+            return lay
+    low = ref.lower()
+    for lay in prs.slide_layouts:
+        if lay.name.lower() == low:
+            return lay
+    for lay in prs.slide_layouts:
+        if low in lay.name.lower():
+            return lay
+    warn(f"template layout {ref!r} not found; falling back to overlay rendering")
+    return None
+
+
+def blank_layout(prs):
+    """The emptiest layout available — index 6 in the default template."""
+    for lay in prs.slide_layouts:
+        if not lay.placeholders._element.findall(
+            ".//{http://schemas.openxmlformats.org/presentationml/2006/main}sp"
+        ):
+            return lay
+    for lay in prs.slide_layouts:
+        if lay.name.strip().lower() in ("blank", "blank slide"):
+            return lay
+    try:
+        return prs.slide_layouts[6]
+    except IndexError:
+        return prs.slide_layouts[-1]
+
+
+# ------------------------------------------------------------- placeholders
+
+
+TITLE_PH = (PP_PLACEHOLDER.TITLE, PP_PLACEHOLDER.CENTER_TITLE)
+BODY_PH = (PP_PLACEHOLDER.BODY, PP_PLACEHOLDER.OBJECT, PP_PLACEHOLDER.SUBTITLE)
+SKIP_PH = (PP_PLACEHOLDER.SLIDE_NUMBER, PP_PLACEHOLDER.FOOTER, PP_PLACEHOLDER.DATE)
+
+
+def ph_type(shape):
+    try:
+        return shape.placeholder_format.type
+    except (AttributeError, ValueError):
+        return None
+
+
+def placeholders(slide, kinds=None):
+    out = []
+    for shape in slide.placeholders:
+        t = ph_type(shape)
+        if t in SKIP_PH:
+            continue
+        if kinds is None or t in kinds:
+            out.append(shape)
+    return out
+
+
+def set_ph_text(shape, text: str, *, size_pt=None) -> None:
+    """Write into a placeholder without flattening the template's formatting.
+
+    Assigning `text_frame.text` collapses the paragraph to one unstyled run and
+    loses the template's font. Reusing the existing run keeps it.
+    """
+    tf = shape.text_frame
+    tf.word_wrap = True
+    p = tf.paragraphs[0]
+    for extra in list(tf.paragraphs)[1:]:
+        extra._p.getparent().remove(extra._p)
+    if p.runs:
+        p.runs[0].text = text
+        for extra in list(p.runs)[1:]:
+            extra._r.getparent().remove(extra._r)
+        run = p.runs[0]
+    else:
+        run = p.add_run()
+        run.text = text
+    if size_pt is not None:
+        run.font.size = size_pt
+
+
+def set_ph_bullets(shape, bullets, *, bold_first: bool = False) -> None:
+    tf = shape.text_frame
+    tf.word_wrap = True
+    template_p = copy.deepcopy(tf.paragraphs[0]._p)
+    for extra in list(tf.paragraphs)[1:]:
+        extra._p.getparent().remove(extra._p)
+    for i, text in enumerate(bullets):
+        if i == 0:
+            p = tf.paragraphs[0]
+        else:
+            tf._txBody.append(copy.deepcopy(template_p))
+            p = tf.paragraphs[-1]
+        if p.runs:
+            p.runs[0].text = str(text)
+            for extra in list(p.runs)[1:]:
+                extra._r.getparent().remove(extra._r)
+        else:
+            p.add_run().text = str(text)
+        if bold_first and i == 0 and p.runs:
+            p.runs[0].font.bold = True
+
+
+def drop_empty_placeholders(slide) -> None:
+    """Remove the 'Click to add text' ghosts a template layout leaves behind."""
+    for shape in list(slide.placeholders):
+        if ph_type(shape) in SKIP_PH:
+            continue
+        if shape.has_text_frame and not shape.text_frame.text.strip():
+            shape._element.getparent().remove(shape._element)
+
+
+def claim_body_region(slide, c: Canvas, *, below_title_bar=True, kinds=BODY_PH) -> Region:
+    """Take the biggest empty body placeholder's rectangle and remove the placeholder.
+
+    Custom content (numbers, tables, charts, images) then lands exactly where the
+    template intended content to go, instead of at our own hardcoded coordinates.
+    """
+    best, best_area = None, 0
+    for shape in placeholders(slide, kinds):
+        if shape.has_text_frame and shape.text_frame.text.strip():
+            continue
+        area = (shape.width or 0) * (shape.height or 0)
+        if area > best_area:
+            best, best_area = shape, area
+    if best is None or not best_area:
+        return default_region(c, below_title_bar=below_title_bar)
+    region = Region(best.left, best.top, best.width, best.height)
+    best._element.getparent().remove(best._element)
+    return region
+
+
+# ------------------------------------------------------------- draw helpers
+
+
+def set_background(slide, hex_str: str) -> None:
+    fill = slide.background.fill
+    fill.solid()
+    fill.fore_color.rgb = hex_color(hex_str)
+
+
+def add_textbox(slide, text: str, *, left, top, width, height,
+                size, bold: bool = False, color: str = "#222222",
+                align=PP_ALIGN.LEFT, anchor=None) -> None:
+    box = slide.shapes.add_textbox(left, top, width, height)
+    tf = box.text_frame
+    tf.word_wrap = True
+    if anchor is not None:
+        tf.vertical_anchor = anchor
+    p = tf.paragraphs[0]
+    p.alignment = align
+    run = p.add_run()
+    run.text = text
+    run.font.size = size
+    run.font.bold = bold
+    run.font.color.rgb = hex_color(color)
+    font = BRAND["heading_font"] if (bold or size >= Pt(24)) else BRAND["body_font"]
+    if font:
+        run.font.name = font
+
+
+def add_bullets(slide, bullets, *, left, top, width, height,
+                size, color: str = "#222222") -> None:
+    box = slide.shapes.add_textbox(left, top, width, height)
+    tf = box.text_frame
+    tf.word_wrap = True
+    for i, b in enumerate(bullets):
+        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        p.text = f"•  {b}"
+        p.space_after = Pt(10)
+        for run in p.runs:
+            run.font.size = size
+            run.font.color.rgb = hex_color(color)
+            if BRAND["body_font"]:
+                run.font.name = BRAND["body_font"]
+
+
+def add_rect(slide, *, left, top, width, height, fill: str) -> None:
+    shape = slide.shapes.add_shape(MSO_SHAPE.RECTANGLE, left, top, width, height)
+    shape.fill.solid()
+    shape.fill.fore_color.rgb = hex_color(fill)
+    shape.line.fill.background()
+    shape.shadow.inherit = False
+    return shape
+
+
+def set_notes(slide, notes: str) -> None:
+    slide.notes_slide.notes_text_frame.text = notes
+
+
+def add_slide_number(slide, c: Canvas, n: int, palette: dict) -> None:
+    add_textbox(slide, str(n),
+                left=c.w - c.x(1.0), top=c.h - c.y(0.55),
+                width=c.x(0.5), height=c.y(0.35),
+                size=c.pt(11), color=palette["text"], align=PP_ALIGN.RIGHT)
+
+
+# ------------------------------------------------------------ media helpers
+
+
+def place_image(slide, path_str: str, region: Region, *, spec_dir: Path,
+                palette: dict, strict: bool):
+    """Aspect-fit an image into the region. Missing/unsupported files degrade visibly."""
+    path = Path(path_str).expanduser()
+    if not path.is_absolute():
+        path = (spec_dir / path).resolve()
+
+    problem = None
+    if not path.exists():
+        problem = f"image not found: {path}"
+    elif path.suffix.lower() not in RASTER_OK:
+        problem = (f"unsupported image format {path.suffix!r} ({path.name}) — "
+                   "python-pptx reads raster only; convert SVG/EMF/PDF to PNG first")
+
+    if problem:
+        if strict:
+            die(problem)
+        warn(problem + " — drew a placeholder box instead")
+        box = add_rect(slide, left=region.left, top=region.top,
+                       width=region.width, height=region.height,
+                       fill="#EDEFF4")
+        box.line.color.rgb = hex_color(palette["secondary"])
+        box.line.width = Pt(1)
+        add_textbox(slide, f"[ missing image: {path.name} ]",
+                    left=region.left, top=region.top + region.height // 2,
+                    width=region.width, height=Emu(int(Inches(0.5))),
+                    size=Pt(14), color=palette["secondary"], align=PP_ALIGN.CENTER)
+        return None
+
+    pic = slide.shapes.add_picture(str(path), region.left, region.top)
+    scale = min(region.width / pic.width, region.height / pic.height)
+    pic.width = int(pic.width * scale)
+    pic.height = int(pic.height * scale)
+    pic.left = region.left + (region.width - pic.width) // 2
+    pic.top = region.top + (region.height - pic.height) // 2
+    return pic
+
+
+def place_table(slide, columns, rows, region: Region, c: Canvas, palette: dict) -> None:
+    n_rows = len(rows) + 1
+    n_cols = max(len(columns), max((len(r) for r in rows), default=0))
+    gfx = slide.shapes.add_table(n_rows, n_cols, region.left, region.top,
+                                 region.width, region.height)
+    table = gfx.table
+    table.first_row = True
+
+    body_pt = 16 if n_rows <= 7 else (14 if n_rows <= 10 else 12)
+
+    for j in range(n_cols):
+        cell = table.cell(0, j)
+        cell.text = str(columns[j]) if j < len(columns) else ""
+        cell.fill.solid()
+        cell.fill.fore_color.rgb = hex_color(palette["primary"])
+        cell.vertical_anchor = MSO_ANCHOR.MIDDLE
+        for p in cell.text_frame.paragraphs:
+            for run in p.runs:
+                run.font.bold = True
+                run.font.size = c.pt(body_pt + 1)
+                run.font.color.rgb = hex_color("#FFFFFF")
+                if BRAND["heading_font"]:
+                    run.font.name = BRAND["heading_font"]
+
+    for i, row in enumerate(rows, start=1):
+        for j in range(n_cols):
+            cell = table.cell(i, j)
+            cell.text = str(row[j]) if j < len(row) else ""
+            cell.fill.solid()
+            cell.fill.fore_color.rgb = hex_color("#FFFFFF" if i % 2 else "#F2F4F8")
+            cell.vertical_anchor = MSO_ANCHOR.MIDDLE
+            for p in cell.text_frame.paragraphs:
+                for run in p.runs:
+                    run.font.size = c.pt(body_pt)
+                    if BRAND["body_font"]:
+                        run.font.name = BRAND["body_font"]
+                    run.font.color.rgb = hex_color(palette["text"])
+
+
+def place_chart(slide, chart_spec: dict, region: Region, c: Canvas, palette: dict) -> None:
+    kind = str(chart_spec.get("type", "column")).lower()
+    if kind not in CHART_TYPES:
+        warn(f"unknown chart type {kind!r}; using column")
+        kind = "column"
+
+    categories = chart_spec.get("categories") or []
+    series = chart_spec.get("series") or []
+    if not categories or not series:
+        warn("chart slide has no categories or no series; skipped")
+        return
+
+    data = CategoryChartData()
+    data.categories = categories
+    for s in series:
+        values = list(s.get("values") or [])
+        if len(values) != len(categories):
+            warn(f"series {s.get('name', '?')!r} has {len(values)} values "
+                 f"for {len(categories)} categories — padded with gaps")
+            values = (values + [None] * len(categories))[:len(categories)]
+        data.add_series(str(s.get("name", "Series")), values)
+
+    gfx = slide.shapes.add_chart(CHART_TYPES[kind], region.left, region.top,
+                                 region.width, region.height, data)
+    chart = gfx.chart
+    chart.font.size = c.pt(13)
+    if BRAND["body_font"]:
+        chart.font.name = BRAND["body_font"]
+    chart.font.color.rgb = hex_color(palette["text"])
+
+    is_pie = kind in ("pie", "doughnut")
+    chart.has_legend = bool(chart_spec.get("legend", is_pie or len(series) > 1))
+    if chart.has_legend:
+        chart.legend.position = XL_LEGEND_POSITION.BOTTOM
+        chart.legend.include_in_layout = False
+
+    colors = series_colors(palette, max(len(series), len(categories)))
+    plot = chart.plots[0]
+    if is_pie:
+        plot.vary_by_categories = True
+        for i, point in enumerate(plot.series[0].points):
+            point.format.fill.solid()
+            point.format.fill.fore_color.rgb = hex_color(colors[i % len(colors)])
+    else:
+        plot.vary_by_categories = False
+        for i, s in enumerate(chart.series):
+            s.format.fill.solid()
+            s.format.fill.fore_color.rgb = hex_color(colors[i])
+        if kind == "line":
+            for i, s in enumerate(chart.series):
+                s.format.line.color.rgb = hex_color(colors[i])
+
+    if chart_spec.get("data_labels", is_pie):
+        plot.has_data_labels = True
+        labels = plot.data_labels
+        labels.font.size = c.pt(12)
+        if is_pie:
+            labels.font.color.rgb = hex_color("#FFFFFF")
+        if chart_spec.get("number_format"):
+            labels.number_format = chart_spec["number_format"]
+            labels.number_format_is_linked = False
+
+
+# ----------------------------------------------------------------- renderers
+#
+# Each renderer draws the deck's own design. In template mode the chrome comes
+# from the template layout instead, and only the parts a placeholder cannot
+# express are drawn here.
+
+
+def _title_bar(slide, c: Canvas, palette, title: str) -> None:
+    add_rect(slide, left=0, top=0, width=c.w, height=c.y(1.0),
+             fill=palette["primary"])
+    add_textbox(slide, title,
+                left=c.x(0.5), top=c.y(0.22),
+                width=c.w - c.x(1.0), height=c.y(0.7),
+                size=c.pt(26), bold=True, color="#FFFFFF")
+
+
+def render_title(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    add_rect(slide, left=0, top=c.y(3.0), width=c.w, height=c.y(0.15),
+             fill=palette["accent"])
+    add_textbox(slide, spec.get("title", "Untitled"),
+                left=c.x(0.75), top=c.y(2.0),
+                width=c.right_margin_w, height=c.y(1.2),
+                size=c.pt(44), bold=True, color=palette["primary"])
+    if spec.get("subtitle"):
+        add_textbox(slide, spec["subtitle"],
+                    left=c.x(0.75), top=c.y(3.4),
+                    width=c.right_margin_w, height=c.y(0.8),
+                    size=c.pt(24), color=palette["text"])
+    footer = "  ·  ".join([s for s in (spec.get("presenter"), spec.get("date")) if s])
+    if footer:
+        add_textbox(slide, footer,
+                    left=c.x(0.75), top=c.y(6.5),
+                    width=c.right_margin_w, height=c.y(0.5),
+                    size=c.pt(14), color=palette["text"])
+
+
+def render_section(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["primary"])
+    add_textbox(slide, spec.get("title", ""),
+                left=c.x(0.75), top=c.y(3.0),
+                width=c.right_margin_w, height=c.y(1.5),
+                size=c.pt(48), bold=True, color="#FFFFFF")
+    add_rect(slide, left=c.x(0.75), top=c.y(4.6),
+             width=c.x(2), height=c.y(0.1), fill=palette["accent"])
+
+
+def render_content(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    _title_bar(slide, c, palette, spec.get("title", ""))
+    region = default_region(c)
+    if spec.get("bullets"):
+        add_bullets(slide, spec["bullets"],
+                    left=region.left, top=region.top,
+                    width=region.width, height=region.height,
+                    size=c.pt(20), color=palette["text"])
+    if spec.get("body"):
+        top = region.top + (c.y(0.4) * len(spec.get("bullets") or []) if spec.get("bullets") else 0)
+        add_textbox(slide, spec["body"],
+                    left=region.left, top=top,
+                    width=region.width, height=region.height,
+                    size=c.pt(18), color=palette["text"])
+
+
+def render_two_column(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    _title_bar(slide, c, palette, spec.get("title", ""))
+    col_w = c.x(6.0)
+    for col_key, col_left in (("left", c.x(0.5)), ("right", c.x(6.85))):
+        col = spec.get(col_key) or {}
+        if col.get("title"):
+            add_textbox(slide, col["title"],
+                        left=col_left, top=c.y(1.3),
+                        width=col_w, height=c.y(0.6),
+                        size=c.pt(20), bold=True, color=palette["primary"])
+        if col.get("bullets"):
+            add_bullets(slide, col["bullets"],
+                        left=col_left, top=c.y(2.0),
+                        width=col_w, height=c.y(5.0),
+                        size=c.pt(18), color=palette["text"])
+        elif col.get("body"):
+            add_textbox(slide, col["body"],
+                        left=col_left, top=c.y(2.0),
+                        width=col_w, height=c.y(5.0),
+                        size=c.pt(18), color=palette["text"])
+
+
+def render_big_number(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    _title_bar(slide, c, palette, spec.get("title", ""))
+    draw_big_number(slide, c, palette, spec, default_region(c))
+
+
+def draw_big_number(slide, c, palette, spec, region: Region) -> None:
+    number = spec.get("number", "—")
+    size = 140 if len(str(number)) <= 6 else (100 if len(str(number)) <= 10 else 72)
+    add_textbox(slide, str(number),
+                left=region.left, top=region.top,
+                width=region.width, height=int(region.height * 0.68),
+                size=c.pt(size), bold=True, color=palette["accent"],
+                align=PP_ALIGN.CENTER, anchor=MSO_ANCHOR.MIDDLE)
+    if spec.get("caption"):
+        add_textbox(slide, spec["caption"],
+                    left=region.left, top=region.top + int(region.height * 0.70),
+                    width=region.width, height=int(region.height * 0.25),
+                    size=c.pt(22), color=palette["text"], align=PP_ALIGN.CENTER)
+
+
+def render_quote(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    draw_quote(slide, c, palette, spec,
+               Region(c.x(1.4), c.y(2.0), c.right_margin_w - c.x(1.3), c.y(4.0)))
+
+
+def draw_quote(slide, c, palette, spec, region: Region) -> None:
+    add_rect(slide, left=region.left, top=region.top,
+             width=c.x(0.12), height=region.height * 7 // 8, fill=palette["accent"])
+    text_left = region.left + c.x(0.5)
+    text_w = region.width - c.x(0.5)
+    add_textbox(slide, f"“{spec.get('quote', '')}”",
+                left=text_left, top=region.top,
+                width=text_w, height=int(region.height * 0.72),
+                size=c.pt(30), color=palette["primary"])
+    if spec.get("attribution"):
+        add_textbox(slide, f"— {spec['attribution']}",
+                    left=text_left, top=region.top + int(region.height * 0.80),
+                    width=text_w, height=c.y(0.7),
+                    size=c.pt(18), color=palette["text"])
+
+
+def render_image(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    position = str(spec.get("position", "full")).lower()
+    bullets = spec.get("bullets") or []
+    if spec.get("title"):
+        _title_bar(slide, c, palette, spec["title"])
+        top = c.y(1.4)
+    else:
+        top = c.y(0.6)
+    bottom = c.h - c.y(1.0 if spec.get("caption") else 0.5)
+    height = bottom - top
+
+    if bullets and position in ("left", "right"):
+        half = (c.right_margin_w - c.x(0.5)) // 2
+        img_left = c.x(0.75) if position == "left" else c.x(0.75) + half + c.x(0.5)
+        txt_left = c.x(0.75) + half + c.x(0.5) if position == "left" else c.x(0.75)
+        add_bullets(slide, bullets, left=txt_left, top=top + c.y(0.2),
+                    width=half, height=height, size=c.pt(18), color=palette["text"])
+        region = Region(img_left, top, half, height)
+    else:
+        region = Region(c.x(0.75), top, c.right_margin_w, height)
+
+    draw_image(slide, c, palette, spec, region, ctx)
+
+
+def draw_image(slide, c, palette, spec, region: Region, ctx) -> None:
+    src = spec.get("image") or spec.get("path")
+    if not src:
+        warn("image slide has no `image` path; skipped")
+        return
+    place_image(slide, src, region, spec_dir=ctx["spec_dir"],
+                palette=palette, strict=ctx["strict"])
+    if spec.get("caption"):
+        add_textbox(slide, spec["caption"],
+                    left=region.left, top=region.top + region.height + c.y(0.05),
+                    width=region.width, height=c.y(0.4),
+                    size=c.pt(13), color=palette["secondary"], align=PP_ALIGN.CENTER)
+
+
+def render_table(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    _title_bar(slide, c, palette, spec.get("title", ""))
+    draw_table(slide, c, palette, spec, default_region(c), ctx)
+
+
+def draw_table(slide, c, palette, spec, region: Region, ctx) -> None:
+    columns = spec.get("columns") or []
+    rows = spec.get("rows") or []
+    if not columns and not rows:
+        warn("table slide has no columns or rows; skipped")
+        return
+    if len(rows) > 12:
+        warn(f"table has {len(rows)} data rows — over 12 stops being readable on a slide")
+    height = min(region.height, c.y(0.45) * (len(rows) + 1))
+    place_table(slide, columns, rows,
+                Region(region.left, region.top, region.width, height), c, palette)
+    if spec.get("caption"):
+        add_textbox(slide, spec["caption"],
+                    left=region.left, top=region.top + height + c.y(0.15),
+                    width=region.width, height=c.y(0.4),
+                    size=c.pt(13), color=palette["secondary"])
+
+
+def render_chart(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["background"])
+    _title_bar(slide, c, palette, spec.get("title", ""))
+    draw_chart(slide, c, palette, spec, default_region(c), ctx)
+
+
+def draw_chart(slide, c, palette, spec, region: Region, ctx) -> None:
+    chart_spec = spec.get("chart") or {}
+    takeaway = spec.get("takeaway")
+    if takeaway:
+        add_textbox(slide, takeaway,
+                    left=region.left, top=region.top,
+                    width=region.width, height=c.y(0.45),
+                    size=c.pt(16), color=palette["text"])
+        region = Region(region.left, region.top + c.y(0.55),
+                        region.width, region.height - c.y(0.55))
+    place_chart(slide, chart_spec, region, c, palette)
+    if spec.get("source"):
+        add_textbox(slide, f"Source: {spec['source']}",
+                    left=region.left, top=region.top + region.height - c.y(0.05),
+                    width=region.width, height=c.y(0.35),
+                    size=c.pt(11), color=palette["secondary"])
+
+
+def render_closing(slide, c, palette, spec, ctx) -> None:
+    set_background(slide, palette["primary"])
+    add_textbox(slide, spec.get("title", "Thank you"),
+                left=c.x(0.5), top=c.y(2.5),
+                width=c.w - c.x(1.0), height=c.y(1.5),
+                size=c.pt(54), bold=True, color="#FFFFFF", align=PP_ALIGN.CENTER)
+    if spec.get("subtitle"):
+        add_textbox(slide, spec["subtitle"],
+                    left=c.x(0.5), top=c.y(4.3),
+                    width=c.w - c.x(1.0), height=c.y(0.8),
+                    size=c.pt(22), color=palette["accent"], align=PP_ALIGN.CENTER)
+
+
+RENDERERS = {
+    "title": render_title,
+    "section": render_section,
+    "content": render_content,
+    "two_column": render_two_column,
+    "big_number": render_big_number,
+    "quote": render_quote,
+    "image": render_image,
+    "table": render_table,
+    "chart": render_chart,
+    "closing": render_closing,
+}
+
+# Layouts a template placeholder can express on its own. Everything else keeps
+# the template's chrome but draws its content into the claimed body region.
+PLACEHOLDER_NATIVE = {"title", "section", "content", "two_column", "closing"}
+
+CUSTOM_DRAW = {
+    "big_number": draw_big_number,
+    "quote": draw_quote,
+    "image": draw_image,
+    "table": draw_table,
+    "chart": draw_chart,
+}
+
+
+# ------------------------------------------------------------ template mode
+
+
+def render_templated(slide, c, palette, spec, ctx, logical: str) -> None:
+    """Fill the template layout's placeholders; draw only what they can't hold."""
+    title_phs = placeholders(slide, TITLE_PH)
+    title_text = spec.get("title")
+    if title_text and title_phs:
+        set_ph_text(title_phs[0], title_text)
+    elif title_text:
+        add_textbox(slide, title_text, left=c.x(0.6), top=c.y(0.4),
+                    width=c.w - c.x(1.2), height=c.y(0.9),
+                    size=c.pt(28), bold=True, color=palette["primary"])
+
+    if logical in CUSTOM_DRAW:
+        kinds = BODY_PH + (PP_PLACEHOLDER.PICTURE,) if logical == "image" else BODY_PH
+        region = claim_body_region(slide, c, kinds=kinds)
+        drawer = CUSTOM_DRAW[logical]
+        if logical in ("image", "table", "chart"):
+            drawer(slide, c, palette, spec, region, ctx)
+        else:
+            drawer(slide, c, palette, spec, region)
+        drop_empty_placeholders(slide)
+        return
+
+    bodies = [b for b in placeholders(slide, BODY_PH) if b not in title_phs]
+
+    if logical == "two_column":
+        cols = [spec.get("left") or {}, spec.get("right") or {}]
+        targets = sorted(bodies, key=lambda s: s.left or 0)[:2]
+        if len(targets) >= 2:
+            for target, col in zip(targets, cols):
+                items = col.get("bullets") or ([col["body"]] if col.get("body") else [])
+                if col.get("title"):
+                    items = [col["title"]] + list(items)
+                if items:
+                    set_ph_bullets(target, items, bold_first=bool(col.get("title")))
+        else:
+            region = claim_body_region(slide, c)
+            half = (region.width - c.x(0.4)) // 2
+            for i, col in enumerate(cols):
+                left = region.left + i * (half + c.x(0.4))
+                if col.get("title"):
+                    add_textbox(slide, col["title"], left=left, top=region.top,
+                                width=half, height=c.y(0.5),
+                                size=c.pt(20), bold=True, color=palette["primary"])
+                items = col.get("bullets") or ([col["body"]] if col.get("body") else [])
+                if items:
+                    add_bullets(slide, items, left=left, top=region.top + c.y(0.6),
+                                width=half, height=region.height - c.y(0.6),
+                                size=c.pt(18), color=palette["text"])
+        drop_empty_placeholders(slide)
+        return
+
+    # Sub-headline: prefer a real subtitle placeholder, then any spare body, then
+    # a drawn textbox — a `Title Only` layout must not silently swallow the line.
+    if spec.get("subtitle"):
+        subs = [b for b in bodies if ph_type(b) == PP_PLACEHOLDER.SUBTITLE]
+        target = subs[0] if subs else (bodies[0] if bodies and not spec.get("bullets")
+                                       and not spec.get("body") else None)
+        if target is not None:
+            set_ph_text(target, spec["subtitle"])
+            bodies = [b for b in bodies if b is not target]
+        else:
+            top = (title_phs[0].top + title_phs[0].height + c.y(0.2)
+                   if title_phs else c.y(1.4))
+            add_textbox(slide, spec["subtitle"], left=c.x(0.75), top=top,
+                        width=c.right_margin_w, height=c.y(0.8),
+                        size=c.pt(20), color=palette["text"])
+
+    payload = spec.get("bullets") or ([spec["body"]] if spec.get("body") else [])
+    if payload:
+        if bodies:
+            set_ph_bullets(bodies[0], payload)
+        else:
+            region = claim_body_region(slide, c)
+            add_bullets(slide, payload, left=region.left, top=region.top,
+                        width=region.width, height=region.height,
+                        size=c.pt(18), color=palette["text"])
+
+    footer = "  ·  ".join([s for s in (spec.get("presenter"), spec.get("date")) if s])
+    if footer and logical == "title":
+        add_textbox(slide, footer, left=c.x(0.75), top=c.h - c.y(0.9),
+                    width=c.right_margin_w, height=c.y(0.4),
+                    size=c.pt(13), color=palette["text"])
+
+    drop_empty_placeholders(slide)
+
+
+def layout_numbers_slides(layout) -> bool:
+    """True when the template's own master already stamps a slide number."""
+    for shape in layout.placeholders:
+        if ph_type(shape) == PP_PLACEHOLDER.SLIDE_NUMBER:
+            return True
+    return False
+
+
+# ----------------------------------------------------------------- driver
+
+
+def load_brand(ref, base: Path):
+    """brand.json path or inline object -> (dict, directory its relative paths resolve from)."""
+    if not ref:
+        return {}, base
+    if isinstance(ref, dict):
+        return ref, base
+    path = (base / ref).expanduser() if not Path(ref).is_absolute() else Path(ref)
+    if not path.exists():
+        warn(f"brand file not found: {path}; building without it")
+        return {}, base
+    try:
+        return json.loads(path.read_text()), path.parent
+    except json.JSONDecodeError as e:
+        warn(f"brand file {path} is not valid JSON ({e}); building without it")
+        return {}, base
+
+
+def apply_brand(spec: dict, brand: dict, brand_dir: Path, spec_dir: Path) -> None:
+    """Fill what the spec leaves out from the brand. The spec always wins: a deck can still
+    override one colour or swap the template without editing the brand file."""
+    colors = {k: v for k, v in (brand.get("colors") or {}).items()
+              if k in ("primary", "secondary", "accent", "background", "text") and v}
+    if colors and not spec.get("palette"):
+        spec["palette"] = colors
+    elif colors and isinstance(spec.get("palette"), dict):
+        spec["palette"] = {**colors, **spec["palette"]}
+    tpl = (brand.get("templates") or {}).get("pptx") or brand.get("template")
+    if tpl and not spec.get("template"):
+        spec["template"] = str((brand_dir / tpl).resolve()) if not Path(tpl).is_absolute() else tpl
+    fonts = brand.get("fonts") or {}
+    BRAND["heading_font"] = (fonts.get("heading") or {}).get("family") if isinstance(fonts.get("heading"), dict) else fonts.get("heading")
+    BRAND["body_font"] = (fonts.get("body") or {}).get("family") if isinstance(fonts.get("body"), dict) else fonts.get("body")
+    logo = brand.get("logo") or {}
+    for key, field in (("logo", "primary"), ("logo_on_dark", "on_dark")):
+        ref = logo.get(field) if isinstance(logo, dict) else (logo if field == "primary" else None)
+        if not ref:
+            continue
+        lp = (brand_dir / ref) if not Path(ref).is_absolute() else Path(ref)
+        if lp.suffix.lower() not in (".png", ".jpg", ".jpeg", ".gif", ".bmp"):
+            warn(f"logo {lp.name} is {lp.suffix or 'not an image'}; PowerPoint needs PNG or JPG. Export the logo as PNG.")
+        elif not lp.exists():
+            warn(f"logo not found: {lp}")
+        else:
+            BRAND[key] = str(lp)
+
+
+def is_dark(hex_str: str) -> bool:
+    h = hex_str.lstrip("#")
+    r, g, b = (int(h[i:i + 2], 16) / 255 for i in (0, 2, 4))
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.45
+
+
+def place_logo(slide, c: "Canvas", palette: dict, logical: str) -> None:
+    """The brand logo on the built-in design: large on the cover, small in a fixed corner on
+    every other slide, using the on-dark variant on dark slides when there is one."""
+    if not BRAND["logo"] and not BRAND["logo_on_dark"]:
+        return
+    dark_bg = logical in ("section", "closing") and is_dark(palette["primary"]) or \
+        (logical == "title" and is_dark(palette["background"]))
+    path = (BRAND["logo_on_dark"] or BRAND["logo"]) if dark_bg else (BRAND["logo"] or BRAND["logo_on_dark"])
+    if logical == "title":
+        slide.shapes.add_picture(path, c.x(0.75), c.y(0.6), height=c.y(0.7))
+    elif logical == "closing":
+        pic = slide.shapes.add_picture(path, 0, c.h - c.y(1.25), height=c.y(0.6))
+        pic.left = int((c.w - pic.width) / 2)
+    else:
+        slide.shapes.add_picture(path, c.x(0.5), c.h - c.y(0.55), height=c.y(0.32))
+
+
+def build(spec_path: Path, out_path: Path, script_dir: Path, *, strict: bool, brand_ref=None) -> None:
+    spec = json.loads(spec_path.read_text())
+    spec_dir = spec_path.parent
+    brand, brand_dir = load_brand(brand_ref or spec.get("brand"), spec_dir)
+    if brand:
+        apply_brand(spec, brand, brand_dir, spec_dir)
+    palette = resolve_palette(spec.get("palette"), script_dir)
+
+    slides = spec.get("slides", [])
+    if not slides:
+        die("spec has no slides")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        prs, canvas, using_template = open_presentation(spec, spec_dir, Path(tmp))
+        layout_map = spec.get("layout_map") or {}
+        if using_template and not layout_map:
+            warn("template supplied without a `layout_map` — rendering the deck's own "
+                 "design on the template's blank layout. Map logical layouts to the "
+                 "template's layout names to inherit its slide designs:\n"
+                 + list_layouts(prs))
+
+        blank = blank_layout(prs)
+        show_numbers = spec.get("slide_numbers", len(slides) > 10)
+        ctx = {"spec_dir": spec_dir, "strict": strict, "template": using_template}
+
+        for i, slide_spec in enumerate(slides, start=1):
+            logical = slide_spec.get("layout", "content")
+            if logical not in RENDERERS:
+                warn(f"unknown layout {logical!r} on slide {i}; falling back to content")
+                logical = "content"
+
+            ref = slide_spec.get("layout_name", layout_map.get(logical))
+            tmpl_layout = find_layout(prs, ref) if (using_template and ref is not None) else None
+
+            slide = prs.slides.add_slide(tmpl_layout or blank)
+            if tmpl_layout is not None:
+                render_templated(slide, canvas, palette, slide_spec, ctx, logical)
+            else:
+                RENDERERS[logical](slide, canvas, palette, slide_spec, ctx)
+                if not using_template:  # a template's masters already carry its logo
+                    place_logo(slide, canvas, palette, logical)
+
+            if slide_spec.get("notes"):
+                set_notes(slide, slide_spec["notes"])
+            own_numbering = tmpl_layout is not None and layout_numbers_slides(tmpl_layout)
+            if (show_numbers and not own_numbering
+                    and logical not in ("title", "section", "closing")):
+                add_slide_number(slide, canvas, i, palette)
+
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        prs.save(str(out_path))
+
+    mode = "template" if using_template else "built-in design"
+    if brand:
+        mode += ", brand: " + ", ".join(x for x, on in (("colours", bool(brand.get("colors"))),
+                                                         ("logo", bool(BRAND["logo"] or BRAND["logo_on_dark"])),
+                                                         ("fonts", bool(BRAND["heading_font"] or BRAND["body_font"]))) if on)
+    print(f"wrote {out_path} ({len(slides)} slides, {mode})")
+    if WARNINGS:
+        print(f"{len(WARNINGS)} warning(s) — see stderr; fix them before presenting")
+
+
+def main(argv) -> int:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("spec", nargs="?", help="Path to deck spec JSON")
+    ap.add_argument("-o", "--output", default=None,
+                    help="Output .pptx path (default: alongside the spec)")
+    ap.add_argument("--strict", action="store_true",
+                    help="Fail on a missing/unsupported image instead of drawing a placeholder")
+    ap.add_argument("--brand", metavar="BRAND_JSON",
+                    help="brand.json (from the brand-kit skill): colours, template, logo, fonts. "
+                         "Fills anything the spec leaves out")
+    ap.add_argument("--list-layouts", metavar="TEMPLATE",
+                    help="Print a template's layout names and indices, then exit "
+                         "(use them to write layout_map)")
+    args = ap.parse_args(argv)
+
+    if args.list_layouts:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(args.list_layouts).expanduser().resolve()
+            if not path.exists():
+                die(f"template not found: {path}")
+            shown = path.name
+            if path.suffix.lower() in (".potx", ".potm"):
+                path = _potx_to_pptx(path, Path(tmp))
+            prs = Presentation(str(path))
+            print(f"{shown} — slide size "
+                  f"{prs.slide_width / 914400:.2f}in x {prs.slide_height / 914400:.2f}in")
+            print(list_layouts(prs))
+        return 0
+
+    if not args.spec:
+        ap.error("the spec argument is required (or use --list-layouts)")
+
+    spec_path = Path(args.spec).expanduser().resolve()
+    if not spec_path.exists():
+        die(f"spec file not found: {spec_path}")
+
+    out_path = (Path(args.output).expanduser().resolve()
+                if args.output else spec_path.with_suffix(".pptx"))
+
+    build(spec_path, out_path, Path(__file__).resolve().parent, strict=args.strict,
+          brand_ref=str(Path(args.brand).expanduser().resolve()) if args.brand else None)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))