@mmerterden/multi-agent-pipeline 14.2.1 → 14.2.2

package/pipeline/skills/shared/external/localization-reuse-map/scripts/build-artifact.py

@@ -0,0 +1,865 @@
+#!/usr/bin/env python3
+"""Render a screen localization-reuse mapping into shareable artifacts.
+
+Input: a mapping JSON (schema in reference/format-and-output.md). Output, into --out:
+  <slug>.confluence.xml  -  Confluence *storage format* (what the REST API wants)
+  <slug>.md  -  Markdown mirror (PR / quick read)
+  <slug>.preview.html  -  standalone HTML to eyeball in a browser before upload
+  <slug>.docx  -  Word doc for the content team (--docx; pure-stdlib, offline)
+  <slug>.pdf  -  read-only share copy (--pdf; via an installed renderer)
+
+The three text artifacts above are always written. `.docx` / `.pdf` are opt-in
+(`--docx` / `--pdf`, or `--all` for everything). The .docx is generated with the
+stdlib only (a .docx is a ZIP of OOXML)  -  no third-party dependency, no network.
+The .pdf is produced by whatever renderer the machine has (LibreOffice `soffice`,
+then Chrome/Chromium headless, then `wkhtmltopdf`); if none is installed the PDF is
+skipped with a note pointing at the .docx / .html (still no pip, no network).
+
+Document language defaults to **English**; pass `--ui-lang tr` for Turkish chrome.
+Author it in whatever language the content team actually reads. Only the template
+chrome is localised  -  the key/value data is rendered verbatim.
+
+Two-level layout: a Summary table (Old en/tr · New en/tr · CMS tr/en at a glance +
+keys + verdict) and Details (one block per element, all 8 languages, Old vs New vs
+CMS). The CMS columns carry the content team's actual final copy from Figma Dev Mode
+annotations (mapping `cms`, from scripts/fetch-annotations.py); a ⚠ marks a CMS value
+that drifts from the new design value. If the mapping has a top-level `overlay`
+(a key↔UI image from scripts/render-overlay.py), it is embedded as a "key map" section.
+
+Deterministic rendering only  -  no judgement, no network. Live Confluence upload is a
+separate step (scripts/publish-confluence.py  -  Server/DC Bearer, idempotent
+update-in-place); `--print-upload` prints the ready publish command.
+"""
+import argparse
+import html
+import json
+import os
+import sys
+
+VCOLOUR = {"reuse": "Green", "review": "Yellow", "new": "Blue"}
+VEMOJI = {"reuse": "✅", "review": "🔶", "new": "🆕"}
+PAGE_TITLE_PREFIX = os.environ.get("LOCALIZATION_PAGE_PREFIX", "Localization")
+SUMMARY_LANGS = ["en", "tr"]
+DETAIL_LANGS = ["en", "tr", "ar", "de", "es", "fr", "it", "ru"]
+
+# UI chrome strings  -  English default, Turkish alternate (--ui-lang).
+T = {
+    "tr": {
+        "title": "Lokalizasyon Yeniden Kullanım Haritası",
+        "intro": "İçerik yönetimi için  -  hangi yeni tasarım metinleri mevcut bir çeviriyi yeniden kullanabilir. "
+                 "Karar bir öneridir; içerik ekibi onaylar.",
+        "platforms": "Platformlar", "screen": "Ekran", "summary": "Özet",
+        "details": "Detaylar  -  tüm diller", "from_export": "design-export'tan (tek depo)",
+        "verdict": {"reuse": "YENİDEN KULLAN", "review": "İNCELE", "new": "YENİ"},
+        "legend": {"reuse": "mevcut değeri/anahtarı yeniden kullan",
+                   "review": "aynı işlev, farklılık var  -  içerik ekibi karar verir",
+                   "new": "eski karşılığı yok"},
+        "counts": ["yeniden kullan", "incele", "yeni", "öğe"],
+        "cms_counts": ["içerik onaylı", "içerik farkı"],
+        "keymap": "Ekran  -  anahtar eşlemesi",
+        "drift_note": "⚠ = içerik ekibi (CMS) metni yeni tasarım değerinden farklı",
+        "cols": ["#", "UI öğesi", "Ekran Görüntüsü", "Yeni anahtar", "Eski iOS", "Eski Android", "Eski Web",
+                 "Eski en", "Eski tr", "Yeni en", "Yeni tr", "İçerik TR", "İçerik EN", "Karar", "Not"],
+        "dcols": ["Dil", "Eski (mevcut)", "Yeni (tasarım)", "İçerik (CMS)"],
+    },
+    "en": {
+        "title": "Localization Reuse Map",
+        "intro": "For content management  -  which redesign strings can reuse an existing translation. "
+                 "Verdict is a recommendation; content team confirms.",
+        "platforms": "Platforms", "screen": "Screen", "summary": "Summary",
+        "details": "Details  -  all languages", "from_export": "from design-export (single-repo)",
+        "verdict": {"reuse": "REUSE", "review": "REVIEW", "new": "NEW"},
+        "legend": {"reuse": "reuse the legacy value/key",
+                   "review": "same function, drift  -  content team decides",
+                   "new": "no legacy counterpart"},
+        "counts": ["reuse", "review", "new", "elements"],
+        "cms_counts": ["with CMS copy", "CMS differs"],
+        "keymap": "Screen  -  key map",
+        "drift_note": "⚠ = CMS copy differs from the new design value",
+        "cols": ["#", "UI element", "Screenshot", "New key", "Legacy iOS", "Legacy Android", "Legacy Web",
+                 "Old en", "Old tr", "New en", "New tr", "CMS TR", "CMS EN", "Verdict", "Note"],
+        "dcols": ["Lang", "Old (legacy)", "New (redesign)", "CMS"],
+    },
+}
+
+
+def e(s):
+    return html.escape("" if s in (None, "") else str(s), quote=True)
+
+
+def dash(s):
+    return s if s not in (None, "") else "-"
+
+
+def md(s):
+    return ("" if s in (None, "") else str(s)).replace("|", "\\|").replace("\n", " ")
+
+
+def vtext(t, vd):
+    return f'{VEMOJI.get(vd, "")} {t["verdict"].get(vd, vd)}'
+
+
+LEGACY_KEY_PREFIX = ""
+
+
+def legdisp(k):
+    """Legacy keys are stored bare in the mapping. When the legacy backend namespaces
+    them under a prefix the app strips, the content team still wants the full stored
+    key  -  set the mapping's `legacyKeyPrefix` and it is re-added for display only.
+    Parenthesised markers and empties pass through."""
+    if k in (None, ""):
+        return "-"
+    return k if k.startswith("(") else LEGACY_KEY_PREFIX + k
+
+
+def counts_line(t, rows):
+    c = {k: sum(1 for r in rows if r.get("verdict") == k) for k in VCOLOUR}
+    cn = t["counts"]
+    return f'{c["reuse"]} {cn[0]} · {c["review"]} {cn[1]} · {c["new"]} {cn[2]} · {len(rows)} {cn[3]}'
+
+
+# ---- CMS (content team) annotation copy ----
+# `cms` is the content team's actual final copy, fetched from Figma Dev Mode
+# annotations (see scripts/fetch-annotations.py). 8-lang-capable; the Summary shows
+# tr/en, the Details table shows every language that has a CMS value.
+
+def cms_of(r):
+    return r.get("cms") or {}
+
+
+def _cnorm(s):
+    """Normalize for drift comparison: NFC, collapse whitespace, strip trailing .:..., lowercase.
+    So casing/spacing/trailing-punctuation differences don't read as a real CMS drift."""
+    import re
+    import unicodedata
+    if s in (None, ""):
+        return ""
+    s = unicodedata.normalize("NFC", str(s)).strip()
+    s = re.sub(r"\s+", " ", s)
+    return re.sub(r"[.:...]+$", "", s).strip().lower()
+
+
+def _drifts(cms_val, new_val):
+    return (cms_val not in (None, "") and new_val not in (None, "")
+            and _cnorm(cms_val) != _cnorm(new_val))
+
+
+def row_drift(r):
+    """True if any summary-lang CMS value differs (meaningfully) from the new value."""
+    nw, cms = r.get("new") or {}, cms_of(r)
+    return any(_drifts(cms.get(l), nw.get(l)) for l in SUMMARY_LANGS)
+
+
+def cms_disp(r, lang):
+    """CMS value for a lang, with a ⚠ marker when it drifts from the new value; '  -  ' if absent."""
+    cms, nw = cms_of(r), r.get("new") or {}
+    v = cms.get(lang)
+    if v in (None, ""):
+        return "-"
+    return ("⚠ " if _drifts(v, nw.get(lang)) else "") + str(v)
+
+
+def cms_line(t, rows):
+    have = sum(1 for r in rows if cms_of(r).get("tr") or cms_of(r).get("en"))
+    drift = sum(1 for r in rows if row_drift(r))
+    cc = t["cms_counts"]
+    return f'{have} {cc[0]} · {drift} {cc[1]}'
+
+
+# ---- per-key keyshots (annotated screenpieces) ----
+# The mapping's top-level `keyshots` names the manifest render-key-shots.py wrote
+# (`<slug>.keyshots.manifest.json`); each shot is a cropped screenshot with a red box
+# around that row's element. The Summary table's "Ekran Görüntüsü" cell embeds it  -  
+# rows absent from the manifest render "-" (never a guessed crop, same rule as values).
+
+def keyshots_of(m):
+    """{row number: relative file} for the embeddable (.png) shots, else {}."""
+    return m.get("_keyshots") or {}
+
+
+def load_keyshots(m, bases):
+    """Resolve + parse the manifest named by mapping `keyshots`; keep .png shots only
+    (an .html Chrome-fallback can't be embedded). Stores {row: relpath} on the mapping
+    and returns the manifest's directory (for resolving shot files), or None."""
+    name = m.get("keyshots")
+    if not name:
+        return None
+    for b in bases:
+        cand = name if os.path.isabs(name) else os.path.join(b, name)
+        if os.path.isfile(cand):
+            with open(cand, encoding="utf-8") as fh:
+                man = json.load(fh)
+            m["_keyshots"] = {s["row"]: s["file"] for s in man.get("shots", [])
+                              if s.get("file", "").endswith(".png")}
+            return os.path.dirname(os.path.abspath(cand))
+    print(f"warning: keyshots manifest not found: {name}  -  table cells stay blank",
+          file=sys.stderr)
+    return None
+
+
+# ---- Confluence storage format ----
+
+def status_macro(t, vd):
+    return (f'<ac:structured-macro ac:name="status"><ac:parameter ac:name="colour">{VCOLOUR.get(vd,"Grey")}</ac:parameter>'
+            f'<ac:parameter ac:name="title">{e(t["verdict"].get(vd, vd))}</ac:parameter></ac:structured-macro>')
+
+
+def render_storage(m, t):
+    rows = m["rows"]
+    shot = m.get("screenshot")
+    shot_xml = (f'<ac:image ac:height="500"><ri:attachment ri:filename="{e(os.path.basename(shot))}"/></ac:image>'
+                if shot else "<p><em>[screenshot]</em></p>")
+    over = m.get("overlay")
+    over_xml = (f'<h2>{e(t["keymap"])}</h2>'
+                f'<ac:image ac:width="900"><ri:attachment ri:filename="{e(os.path.basename(over))}"/></ac:image>'
+                if over else "")
+    legend = " &nbsp; ".join(f'{status_macro(t, k)} {e(t["legend"][k])}' for k in VCOLOUR)
+    head = (f'<p><strong>{e(t["screen"])}:</strong> {e(m["screen"])} &nbsp; '
+            f'<strong>{e(t["platforms"])}:</strong> {e(", ".join(m.get("platforms", [])))} &nbsp; '
+            f'<strong>Figma:</strong> {e(", ".join(m.get("figmaNodes", [])))}</p>'
+            f'<ac:structured-macro ac:name="info"><ac:rich-text-body><p>{legend} &nbsp;|&nbsp; '
+            f'{e(counts_line(t, rows))} &nbsp;|&nbsp; {e(cms_line(t, rows))}</p>'
+            f'<p><em>{e(t["drift_note"])}</em></p></ac:rich-text-body></ac:structured-macro>')
+    head_row = "".join(f"<th>{e(c)}</th>" for c in t["cols"])
+    body = []
+    shots = keyshots_of(m)
+    for i, r in enumerate(rows, 1):
+        nw, old = r.get("new", {}) or {}, r.get("legacy", {}) or {}
+        ks = (f'<ac:image ac:width="240"><ri:attachment ri:filename="{e(os.path.basename(shots[i]))}"/></ac:image>'
+              if i in shots else "-")
+        tds = [str(i), e(r.get("element")), ks, f'<code>{e(r.get("newKey"))}</code>',
+               f'<code>{e(legdisp(r.get("legacyKeyIOS")))}</code>', f'<code>{e(legdisp(r.get("legacyKeyAndroid")))}</code>',
+               f'<code>{e(legdisp(r.get("legacyKeyWeb")))}</code>']
+        tds += [e(dash(old.get(l))) for l in SUMMARY_LANGS] + [e(dash(nw.get(l))) for l in SUMMARY_LANGS]
+        tds += [e(cms_disp(r, "tr")), e(cms_disp(r, "en"))]
+        tds += [status_macro(t, r.get("verdict", "")), e(r.get("note"))]
+        body.append("<tr>" + "".join(f"<td>{c}</td>" for c in tds) + "</tr>")
+    summary = f"<h2>{e(t['summary'])}</h2><table><tbody><tr>{head_row}</tr>{''.join(body)}</tbody></table>"
+    det = [f"<h2>{e(t['details'])}</h2>"]
+    for i, r in enumerate(rows, 1):
+        nw, old, cms = r.get("new", {}) or {}, r.get("legacy", {}) or {}, cms_of(r)
+        lr = "".join(f"<tr><td>{l}</td><td>{e(dash(old.get(l)))}</td><td>{e(dash(nw.get(l)))}</td>"
+                     f"<td>{e(dash(cms.get(l)))}</td></tr>" for l in DETAIL_LANGS)
+        dh = "".join(f"<th>{e(c)}</th>" for c in t["dcols"])
+        det.append(f"<h3>{i}. {e(r.get('element'))} {status_macro(t, r.get('verdict',''))}</h3>"
+                   f"<p>{e(t['cols'][3])} <code>{e(r.get('newKey'))}</code> · {e(t['cols'][4])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyIOS')))}</code> · {e(t['cols'][5])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyAndroid')))}</code> · {e(t['cols'][6])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyWeb')))}</code></p>"
+                   f"<table><tbody><tr>{dh}</tr>{lr}</tbody></table>")
+    return head + f"<h2>{e(t['screen'])}</h2>{shot_xml}" + over_xml + summary + "".join(det)
+
+
+# ---- Markdown mirror ----
+
+def render_markdown(m, t):
+    rows = m["rows"]
+    over = m.get("overlay")
+    over_md = ([f"## {t['keymap']}", "", f"![keymap]({os.path.basename(over)})", ""] if over else [])
+    out = [f"# {t['title']}  -  {m['screen']}", "", f"_{t['intro']}_", "",
+           f"**{t['platforms']}:** {', '.join(m.get('platforms', []))} · **Figma:** {', '.join(m.get('figmaNodes', []))}", "",
+           f"## {t['screen']}", "", f"![{t['screen'].lower()}]({os.path.basename(m.get('screenshot','screenshot.png'))})", "",
+           *over_md,
+           f"## {t['summary']}  -  {counts_line(t, rows)} · {cms_line(t, rows)}", "",
+           f"_{t['drift_note']}_", "",
+           "| " + " | ".join(t["cols"]) + " |", "|" + "|".join("---" for _ in t["cols"]) + "|"]
+    shots = keyshots_of(m)
+    for i, r in enumerate(rows, 1):
+        nw, old = r.get("new", {}) or {}, r.get("legacy", {}) or {}
+        c = [str(i), md(r.get("element")), f"![{i}]({shots[i]})" if i in shots else "-",
+             f'`{r.get("newKey")}`',
+             f'`{legdisp(r.get("legacyKeyIOS"))}`', f'`{legdisp(r.get("legacyKeyAndroid"))}`',
+             f'`{legdisp(r.get("legacyKeyWeb"))}`']
+        c += [md(dash(old.get(l))) for l in SUMMARY_LANGS] + [md(dash(nw.get(l))) for l in SUMMARY_LANGS]
+        c += [md(cms_disp(r, "tr")), md(cms_disp(r, "en"))]
+        c += [vtext(t, r.get("verdict", "")), md(r.get("note"))]
+        out.append("| " + " | ".join(c) + " |")
+    out += ["", f"## {t['details']}", ""]
+    for i, r in enumerate(rows, 1):
+        nw, old, cms = r.get("new", {}) or {}, r.get("legacy", {}) or {}, cms_of(r)
+        out += [f"### {i}. {r.get('element')}  -  {vtext(t, r.get('verdict',''))}",
+                f"{t['cols'][3]} `{r.get('newKey')}` · {t['cols'][4]} `{legdisp(r.get('legacyKeyIOS'))}` · "
+                f"{t['cols'][5]} `{legdisp(r.get('legacyKeyAndroid'))}` · {t['cols'][6]} `{legdisp(r.get('legacyKeyWeb'))}`",
+                "", "| " + " | ".join(t["dcols"]) + " |", "|" + "|".join("---" for _ in t["dcols"]) + "|"]
+        for l in DETAIL_LANGS:
+            out.append(f"| {l} | {md(dash(old.get(l)))} | {md(dash(nw.get(l)))} | {md(dash(cms.get(l)))} |")
+        out.append("")
+    return "\n".join(out) + "\n"
+
+
+# ---- Browser preview ----
+
+def render_html(m, t):
+    rows = m["rows"]
+    bgc = {"reuse": "#e6f4ea", "review": "#fdf3e2", "new": "#e8f0fe"}
+    fgc = {"reuse": "#1f8a4c", "review": "#b06a00", "new": "#1666c8"}
+
+    def badge(vd):
+        return (f'<span style="background:{bgc.get(vd,"#eee")};color:{fgc.get(vd,"#555")};font-weight:600;'
+                f'padding:2px 8px;border-radius:10px;font-size:12px;white-space:nowrap">{e(vtext(t, vd))}</span>')
+
+    summ = ["<table><thead><tr>" + "".join(f"<th>{e(c)}</th>" for c in t["cols"]) + "</tr></thead><tbody>"]
+    shots = keyshots_of(m)
+    for i, r in enumerate(rows, 1):
+        nw, old = r.get("new", {}) or {}, r.get("legacy", {}) or {}
+        ks = (f'<img src="{e(shots[i])}" style="max-width:240px;border:1px solid #ddd;border-radius:6px">'
+              if i in shots else "-")
+        cells = ([str(i), e(r.get("element")), ks, f"<code>{e(r.get('newKey'))}</code>",
+                  f"<code>{e(legdisp(r.get('legacyKeyIOS')))}</code>", f"<code>{e(legdisp(r.get('legacyKeyAndroid')))}</code>",
+                  f"<code>{e(legdisp(r.get('legacyKeyWeb')))}</code>"]
+                 + [e(dash(old.get(l))) for l in SUMMARY_LANGS] + [e(dash(nw.get(l))) for l in SUMMARY_LANGS]
+                 + [e(cms_disp(r, "tr")), e(cms_disp(r, "en"))]
+                 + [badge(r.get("verdict", "")), f"<span style='color:#555'>{e(r.get('note'))}</span>"])
+        summ.append("<tr>" + "".join(f"<td>{c}</td>" for c in cells) + "</tr>")
+    summ.append("</tbody></table>")
+    det = []
+    for i, r in enumerate(rows, 1):
+        nw, old, cms = r.get("new", {}) or {}, r.get("legacy", {}) or {}, cms_of(r)
+        lr = "".join(f"<tr><td>{l}</td><td>{e(dash(old.get(l)))}</td><td>{e(dash(nw.get(l)))}</td>"
+                     f"<td>{e(dash(cms.get(l)))}</td></tr>" for l in DETAIL_LANGS)
+        dh = "".join(f"<th>{e(c)}</th>" for c in t["dcols"])
+        det.append(f"<h3>{i}. {e(r.get('element'))} {badge(r.get('verdict',''))}</h3>"
+                   f"<p>{e(t['cols'][3])} <code>{e(r.get('newKey'))}</code> · {e(t['cols'][4])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyIOS')))}</code> · {e(t['cols'][5])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyAndroid')))}</code> · {e(t['cols'][6])} "
+                   f"<code>{e(legdisp(r.get('legacyKeyWeb')))}</code><br><span style='color:#777'>{e(r.get('note'))}</span></p>"
+                   f"<table style='max-width:780px'><thead><tr>{dh}</tr></thead><tbody>{lr}</tbody></table>")
+    def img_src(p):
+        # absolute path → file:// URL; bare filename → relative (preview.html sits in
+        # the same out dir, and Chrome's html→pdf resolves it too)
+        return f"file://{e(p)}" if os.path.isabs(p or "") else e(p)
+
+    shot = m.get("screenshot")
+    shot_html = (f'<img src="{img_src(shot)}" style="max-height:520px;border:1px solid #ddd;border-radius:8px">'
+                 if shot else '<div style="color:#999">[screenshot]</div>')
+    over = m.get("overlay")
+    over_html = (f'<h2>{e(t["keymap"])}</h2><img src="{img_src(over)}" '
+                 'style="max-width:100%;border:1px solid #ddd;border-radius:8px">' if over else "")
+    return f"""<!doctype html><meta charset=utf-8><title>{e(t['title'])}  -  {e(m['screen'])}</title>
+<style>
+ body{{font:13.5px -apple-system,Segoe UI,Roboto,sans-serif;margin:26px;color:#1a1a1a;max-width:1280px}}
+ h1{{font-size:22px}} h2{{font-size:17px;margin-top:30px;border-bottom:2px solid #eee;padding-bottom:4px}}
+ h3{{font-size:15px;margin-top:20px}} code{{font:12px Menlo,monospace;color:#a3306e}}
+ table{{border-collapse:collapse;width:100%;margin-top:8px}}
+ th,td{{border:1px solid #e3e3e3;padding:6px 9px;text-align:left;vertical-align:top}}
+ th{{background:#f5f6f8}} tr:nth-child(even) td{{background:#fafbfc}}
+</style>
+<h1>{e(t['title'])}  -  {e(m['screen'])}</h1>
+<p style="color:#555">{e(t['intro'])}</p>
+<h2>1 · {e(t['screen'])}</h2>{shot_html}
+<p style="color:#777">Figma {e(', '.join(m.get('figmaNodes',[])))}  -  {e(t['from_export'])}.</p>
+{over_html}
+<h2>2 · {e(t['summary'])} <span style="font-weight:400;color:#666">  -  {e(counts_line(t, rows))} · {e(cms_line(t, rows))}</span></h2>
+<p style="color:#777">{e(t['drift_note'])}</p>
+{''.join(summ)}
+<h2>3 · {e(t['details'])}</h2>{''.join(det)}
+"""
+
+
+# ---- DOCX (pure stdlib  -  a .docx is a ZIP of OOXML) ----
+# No third-party dependency: we emit the minimal Office Open XML package by hand
+# (zipfile + XML strings), so the skill stays offline and dependency-free. Word
+# resolves the per-language fonts itself; we set bidi/rtl on Arabic cells.
+
+EMU_PER_PX = 9525          # at 96 dpi (914400 EMU / inch)
+DOCX_IMG_MAX_W_EMU = 5_000_000   # ~5.5 in wide
+DOCX_IMG_MAX_H_EMU = 5_500_000   # ~6 in tall  -  keep portrait phone shots on one landscape page
+DV_FILL = {"reuse": "E6F4EA", "review": "FDF3E2", "new": "E8F0FE"}   # mirror the HTML badges
+HEAD_FILL = "F5F6F8"
+
+
+def _png_size(path):
+    """(w, h) in px from a PNG header, or None. Stdlib only."""
+    import struct
+    try:
+        with open(path, "rb") as fh:
+            head = fh.read(24)
+    except OSError:
+        return None
+    if len(head) < 24 or head[:8] != b"\x89PNG\r\n\x1a\n" or head[12:16] != b"IHDR":
+        return None
+    return struct.unpack(">II", head[16:24])
+
+
+def _dxe(s):
+    """Escape text for WordprocessingML (same rules as XML)."""
+    return html.escape("" if s in (None, "") else str(s), quote=True)
+
+
+def _run(text, *, bold=False, color=None, rtl=False):
+    rpr = []
+    if bold:
+        rpr.append("<w:b/>")
+    if rtl:
+        rpr.append("<w:rtl/>")
+    if color:
+        rpr.append(f'<w:color w:val="{color}"/>')
+    rpr = f"<w:rPr>{''.join(rpr)}</w:rPr>" if rpr else ""
+    return f'<w:r>{rpr}<w:t xml:space="preserve">{_dxe(text)}</w:t></w:r>'
+
+
+def _para(runs, *, rtl=False, spacing_after=40):
+    if isinstance(runs, str):
+        runs = [_run(runs)]
+    ppr = [f'<w:spacing w:after="{spacing_after}"/>']
+    if rtl:
+        ppr.append("<w:bidi/>")
+    return f"<w:p><w:pPr>{''.join(ppr)}</w:pPr>{''.join(runs)}</w:p>"
+
+
+def _heading(text, level=1):
+    sz = {1: "32", 2: "26", 3: "22"}.get(level, "24")
+    return (f'<w:p><w:pPr><w:spacing w:before="200" w:after="80"/></w:pPr>'
+            f'<w:r><w:rPr><w:b/><w:sz w:val="{sz}"/></w:rPr>'
+            f'<w:t xml:space="preserve">{_dxe(text)}</w:t></w:r></w:p>')
+
+
+def _cell(content_para, *, fill=None, width=None):
+    tcpr = []
+    if width:
+        tcpr.append(f'<w:tcW w:w="{width}" w:type="dxa"/>')
+    if fill:
+        tcpr.append(f'<w:shd w:val="clear" w:color="auto" w:fill="{fill}"/>')
+    tcpr = f"<w:tcPr>{''.join(tcpr)}</w:tcPr>" if tcpr else ""
+    return f"<w:tc>{tcpr}{content_para}</w:tc>"
+
+
+def _table(grid_widths, header_cells, body_rows):
+    borders = ("<w:tblBorders>"
+               + "".join(f'<w:{s} w:val="single" w:sz="4" w:space="0" w:color="D9D9D9"/>'
+                         for s in ("top", "left", "bottom", "right", "insideH", "insideV"))
+               + "</w:tblBorders>")
+    grid = "<w:tblGrid>" + "".join(f'<w:gridCol w:w="{w}"/>' for w in grid_widths) + "</w:tblGrid>"
+    tblpr = ('<w:tblPr><w:tblStyle w:val="TableGrid"/><w:tblW w:w="5000" w:type="pct"/>'
+             '<w:tblLayout w:type="autofit"/>' + borders + "</w:tblPr>")
+    hdr = "<w:tr>" + "".join(header_cells) + "</w:tr>"
+    body = "".join("<w:tr>" + "".join(r) + "</w:tr>" for r in body_rows)
+    return f"<w:tbl>{tblpr}{grid}{hdr}{body}</w:tbl>"
+
+
+def _image_para(rid, cx, cy, *, name="screenshot.png", uid=1):
+    return (
+        '<w:p><w:pPr><w:spacing w:after="120"/></w:pPr><w:r><w:drawing>'
+        f'<wp:inline distT="0" distB="0" distL="0" distR="0">'
+        f'<wp:extent cx="{cx}" cy="{cy}"/><wp:docPr id="{uid}" name="{_dxe(name)}"/>'
+        '<a:graphic xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">'
+        '<a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">'
+        '<pic:pic xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">'
+        f'<pic:nvPicPr><pic:cNvPr id="{uid}" name="{_dxe(name)}"/><pic:cNvPicPr/></pic:nvPicPr>'
+        f'<pic:blipFill><a:blip r:embed="{rid}"/><a:stretch><a:fillRect/></a:stretch></pic:blipFill>'
+        f'<pic:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="{cx}" cy="{cy}"/></a:xfrm>'
+        '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr>'
+        '</pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r></w:p>'
+    )
+
+
+def _docx_document_xml(m, t, *, has_image, img_cx, img_cy, has_overlay=False, ov_cx=0, ov_cy=0,
+                       keyshots=None):
+    keyshots = keyshots or {}   # {row number: (rid, cx, cy)}  -  per-key screenpieces
+    rows = m["rows"]
+    body = [_heading(f"{t['title']}  -  {m['screen']}", 1),
+            _para([_run(t["intro"], color="555555")]),
+            _para([_run(f"{t['platforms']}: ", bold=True), _run(", ".join(m.get("platforms", []))),
+                   _run("   ·   Figma: ", bold=True), _run(", ".join(m.get("figmaNodes", [])))])]
+    # legend + counts
+    leg = []
+    for k in VCOLOUR:
+        leg.append(_run(f"■ ", color=VCOLOUR.get(k, "808080")))
+        leg.append(_run(f"{t['verdict'][k]}  -  {t['legend'][k]}    "))
+    body.append(_para(leg))
+    body.append(_para([_run(counts_line(t, rows), bold=True)]))
+
+    # section Screen
+    body.append(_heading(t["screen"], 2))
+    if has_image:
+        body.append(_image_para("rId100", img_cx, img_cy))
+    else:
+        body.append(_para([_run("[screenshot]", color="999999")]))
+    if has_overlay:
+        body.append(_heading(t["keymap"], 2))
+        body.append(_image_para("rId101", ov_cx, ov_cy, name="overlay.png", uid=2))
+
+    # section Summary table
+    body.append(_heading(t["summary"], 2))
+    cols = t["cols"]
+    grid = [600, 2400, 2300, 2800, 1500, 1500, 1500, 1500, 1500, 1500, 1500, 1500, 1500, 1400, 2400]
+    head_cells = [_cell(_para([_run(c, bold=True)]), fill=HEAD_FILL) for c in cols]
+    body_rows = []
+    for i, r in enumerate(rows, 1):
+        nw, old = r.get("new", {}) or {}, r.get("legacy", {}) or {}
+        vd = r.get("verdict", "")
+        if i in keyshots:
+            rid, kcx, kcy = keyshots[i]
+            ks_cell = _cell(_image_para(rid, kcx, kcy, name=f"keyshot{i}.png", uid=100 + i))
+        else:
+            ks_cell = _cell(_para("-"))
+        cells = [_cell(_para(str(i))),
+                 _cell(_para(dash(r.get("element")))),
+                 ks_cell,
+                 _cell(_para([_run(r.get("newKey"))])),
+                 _cell(_para([_run(legdisp(r.get("legacyKeyIOS")))])),
+                 _cell(_para([_run(legdisp(r.get("legacyKeyAndroid")))])),
+                 _cell(_para([_run(legdisp(r.get("legacyKeyWeb")))]))]
+        cells += [_cell(_para(dash(old.get(l)))) for l in SUMMARY_LANGS]
+        cells += [_cell(_para(dash(nw.get(l)))) for l in SUMMARY_LANGS]
+        cells.append(_cell(_para([_run(cms_disp(r, "tr"))]), fill="FCE4F1" if row_drift(r) else None))
+        cells.append(_cell(_para([_run(cms_disp(r, "en"))])))
+        cells.append(_cell(_para([_run(vtext(t, vd), bold=True)]), fill=DV_FILL.get(vd)))
+        cells.append(_cell(_para(dash(r.get("note")))))
+        body_rows.append(cells)
+    body.append(_table(grid, head_cells, body_rows))
+
+    # section Details  -  per element, all 8 languages
+    body.append(_heading(t["details"], 2))
+    for i, r in enumerate(rows, 1):
+        nw, old, cms = r.get("new", {}) or {}, r.get("legacy", {}) or {}, cms_of(r)
+        vd = r.get("verdict", "")
+        body.append(_heading(f"{i}. {r.get('element')}  -  {vtext(t, vd)}", 3))
+        body.append(_para([_run(f"{cols[3]} "), _run(r.get("newKey")),
+                           _run(f"  ·  {cols[4]} "), _run(legdisp(r.get("legacyKeyIOS"))),
+                           _run(f"  ·  {cols[5]} "), _run(legdisp(r.get("legacyKeyAndroid"))),
+                           _run(f"  ·  {cols[6]} "), _run(legdisp(r.get("legacyKeyWeb")))]))
+        if r.get("note"):
+            body.append(_para([_run(r.get("note"), color="777777")]))
+        dh = [_cell(_para([_run(c, bold=True)]), fill=HEAD_FILL) for c in t["dcols"]]
+        drows = []
+        for l in DETAIL_LANGS:
+            rtl = l == "ar"
+            drows.append([_cell(_para([_run(l, bold=True)])),
+                          _cell(_para([_run(dash(old.get(l)), rtl=rtl)], rtl=rtl)),
+                          _cell(_para([_run(dash(nw.get(l)), rtl=rtl)], rtl=rtl)),
+                          _cell(_para([_run(dash(cms.get(l)), rtl=rtl)], rtl=rtl))])
+        body.append(_table([800, 4200, 4200, 4200], dh, drows))
+
+    sect = ('<w:sectPr><w:pgSz w:w="16838" w:h="11906" w:orient="landscape"/>'
+            '<w:pgMar w:top="720" w:right="720" w:bottom="720" w:left="720" '
+            'w:header="0" w:footer="0" w:gutter="0"/></w:sectPr>')
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" '
+        'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" '
+        'xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing">'
+        f'<w:body>{"".join(body)}{sect}</w:body></w:document>'
+    )
+
+
+def _emu_fit(path, max_w, max_h):
+    """Scaled (cx, cy) EMU for a PNG to fit a box, or a safe default if dims unknown."""
+    size = _png_size(path)
+    if size:
+        w, h = size
+        nat_w, nat_h = w * EMU_PER_PX, h * EMU_PER_PX
+        scale = min(max_w / nat_w, max_h / nat_h, 1.0)
+        return int(nat_w * scale), int(nat_h * scale)
+    return max_w, max_w
+
+
+def write_docx(m, t, out_path, screenshot_path=None, overlay_path=None, keyshot_paths=None):
+    """Write a self-contained .docx. Paths are absolute file paths or None;
+    keyshot_paths is {row number: absolute PNG path} (per-key screenpieces)."""
+    import zipfile
+
+    img_bytes = None
+    img_cx = img_cy = 0
+    if screenshot_path and os.path.exists(screenshot_path):
+        with open(screenshot_path, "rb") as fh:
+            img_bytes = fh.read()
+        img_cx, img_cy = _emu_fit(screenshot_path, DOCX_IMG_MAX_W_EMU, DOCX_IMG_MAX_H_EMU)
+    has_image = img_bytes is not None
+
+    # the overlay (key-map) is wide → allow the full landscape width
+    ov_bytes = None
+    ov_cx = ov_cy = 0
+    if overlay_path and os.path.exists(overlay_path):
+        with open(overlay_path, "rb") as fh:
+            ov_bytes = fh.read()
+        ov_cx, ov_cy = _emu_fit(overlay_path, 9_000_000, 5_500_000)
+    has_overlay = ov_bytes is not None
+
+    # per-key screenpieces → one image part + rel each (rId200+row); thumbnail-fit
+    ks_meta, ks_bytes = {}, {}
+    for row, path in (keyshot_paths or {}).items():
+        if not (path and os.path.exists(path)):
+            continue
+        with open(path, "rb") as fh:
+            ks_bytes[row] = fh.read()
+        cx, cy = _emu_fit(path, 1_900_000, 2_600_000)
+        ks_meta[row] = (f"rId{200 + row}", cx, cy)
+
+    content_types = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+                     '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">'
+                     '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>'
+                     '<Default Extension="xml" ContentType="application/xml"/>'
+                     '<Default Extension="png" ContentType="image/png"/>'
+                     '<Override PartName="/word/document.xml" '
+                     'ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
+                     '</Types>')
+    root_rels = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+                 '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+                 '<Relationship Id="rId1" '
+                 'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" '
+                 'Target="word/document.xml"/></Relationships>')
+    doc_rels_items = ""
+    if has_image:
+        doc_rels_items += ('<Relationship Id="rId100" '
+                           'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" '
+                           'Target="media/screenshot.png"/>')
+    if has_overlay:
+        doc_rels_items += ('<Relationship Id="rId101" '
+                           'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" '
+                           'Target="media/overlay.png"/>')
+    for row, (rid, _, _) in sorted(ks_meta.items()):
+        doc_rels_items += (f'<Relationship Id="{rid}" '
+                           'Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" '
+                           f'Target="media/keyshot{row}.png"/>')
+    doc_rels = ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+                '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+                f'{doc_rels_items}</Relationships>')
+    document = _docx_document_xml(m, t, has_image=has_image, img_cx=img_cx, img_cy=img_cy,
+                                 has_overlay=has_overlay, ov_cx=ov_cx, ov_cy=ov_cy,
+                                 keyshots=ks_meta)
+
+    with zipfile.ZipFile(out_path, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("[Content_Types].xml", content_types)
+        z.writestr("_rels/.rels", root_rels)
+        z.writestr("word/document.xml", document)
+        z.writestr("word/_rels/document.xml.rels", doc_rels)
+        if has_image:
+            z.writestr("word/media/screenshot.png", img_bytes)
+        if has_overlay:
+            z.writestr("word/media/overlay.png", ov_bytes)
+        for row, data in sorted(ks_bytes.items()):
+            z.writestr(f"word/media/keyshot{row}.png", data)
+
+
+# ---- PDF (convert via whatever renderer the machine has  -  no pip, no network) ----
+# Multilingual (Arabic + Cyrillic + Latin) PDF needs real font shaping, so we don't
+# hand-roll it: we drive an installed converter. Order = best table fidelity first.
+
+def _chrome_candidates():
+    env = os.environ.get("CHROME_BIN")
+    cands = [env] if env else []
+    cands += ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser",
+              "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+              "/Applications/Chromium.app/Contents/MacOS/Chromium"]
+    return cands
+
+
+def _which(cmd):
+    import shutil
+    if os.path.isabs(cmd):
+        return cmd if os.path.exists(cmd) else None
+    return shutil.which(cmd)
+
+
+def _run_tool(cmd, timeout):
+    """Run a converter, swallowing TimeoutExpired/OSError. Some headless browsers write
+    the PDF and then hang on shutdown, so we never trust the return code alone  -  the
+    caller checks the output file. Returns the CompletedProcess, or None on error."""
+    import subprocess
+    try:
+        return subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return None      # process already killed by run(); output may still exist
+    except OSError:
+        return None
+
+
+def _nonempty(path):
+    return bool(path) and os.path.exists(path) and os.path.getsize(path) > 0
+
+
+def _run_until_file(cmd, out_path, timeout):
+    """Launch cmd and return as soon as out_path is written and its size stops growing  -  
+    then kill the process tree. For headless browsers that print the PDF in ~1s but hang
+    on shutdown, this avoids blocking on the full timeout. Returns True if out_path exists."""
+    import signal
+    import subprocess
+    import time
+    if os.path.exists(out_path):
+        os.remove(out_path)
+    try:
+        proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                                start_new_session=True)
+    except OSError:
+        return False
+    deadline = time.time() + timeout
+    last_size, stable = -1, 0
+    try:
+        while time.time() < deadline:
+            if proc.poll() is not None:           # exited on its own
+                break
+            if os.path.exists(out_path):
+                size = os.path.getsize(out_path)
+                stable = stable + 1 if size == last_size and size > 0 else 0
+                last_size = size
+                if stable >= 3:                   # ~0.45s unchanged → fully written
+                    break
+            time.sleep(0.15)
+    finally:
+        if proc.poll() is None:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+            except (ProcessLookupError, PermissionError):
+                proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                try:
+                    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+                except (ProcessLookupError, PermissionError):
+                    proc.kill()
+    return _nonempty(out_path)
+
+
+def to_pdf(out_pdf, *, docx_path=None, html_path=None):
+    """Convert to PDF using the first available renderer. Returns the tool name used,
+    or None if no converter is installed (caller prints a skip note)."""
+    import tempfile
+
+    # 1) LibreOffice  -  best fidelity for the table-heavy docx.
+    soffice = next((_which(c) for c in
+                    ("soffice", "libreoffice",
+                     "/Applications/LibreOffice.app/Contents/MacOS/soffice") if _which(c)), None)
+    if soffice and _nonempty(docx_path):
+        with tempfile.TemporaryDirectory() as td:
+            _run_tool([soffice, "--headless", "--convert-to", "pdf", "--outdir", td, docx_path], 180)
+            produced = os.path.join(td, os.path.splitext(os.path.basename(docx_path))[0] + ".pdf")
+            if _nonempty(produced):
+                with open(produced, "rb") as src, open(out_pdf, "wb") as dst:
+                    dst.write(src.read())
+                return "libreoffice"
+
+    # 2) Chrome/Chromium headless  -  html → pdf. Chrome often writes the PDF and then
+    #    hangs on exit; _run_tool absorbs the timeout and we judge by the file.
+    chrome = next((_which(c) for c in _chrome_candidates() if _which(c)), None)
+    if chrome and html_path:
+        url = f"file://{os.path.abspath(html_path)}"
+        for headless in ("--headless=new", "--headless"):
+            with tempfile.TemporaryDirectory() as td:
+                ok = _run_until_file([chrome, headless, "--disable-gpu", "--no-sandbox",
+                                      f"--user-data-dir={td}", "--no-pdf-header-footer",
+                                      "--allow-file-access-from-files",
+                                      f"--print-to-pdf={out_pdf}", url], out_pdf, 90)
+                if ok:
+                    return "chrome"
+
+    # 3) wkhtmltopdf  -  html → pdf.
+    wk = _which("wkhtmltopdf")
+    if wk and html_path:
+        _run_tool([wk, "--enable-local-file-access", "--quiet", html_path, out_pdf], 120)
+        if _nonempty(out_pdf):
+            return "wkhtmltopdf"
+
+    return None
+
+
+# ---- UPLOAD HOOK ----
+# Live upload now lives in scripts/publish-confluence.py (Server/DC Bearer, idempotent
+# update-in-place). --print-upload prints the ready command + the equivalent raw curl.
+
+def upload_curl(slug, m):
+    screen = m["screen"]
+    over = " --overlay {}.overlay.png".format(slug) if m.get("overlay") else ""
+    ks = " --keyshots {}.keyshots.manifest.json".format(slug) if m.get("keyshots") else ""
+    return (
+        "# LIVE publish (idempotent update-in-place under the localizations parent):\n"
+        f"python3 publish-confluence.py --xml {slug}.confluence.xml --screen {json.dumps(screen)} "
+        f"--screenshot screenshot.png{over}{ks} --attach {slug}.localization.xlsx\n"
+        "#\n"
+        "# Equivalent by hand (curl, Server/DC Bearer PAT  -  NOT Cloud user:token).\n"
+        "# $CONFLUENCE_BASE_URL / $CONFLUENCE_SPACE / $CONFLUENCE_PARENT are your wiki's target:\n"
+        '#   TOKEN=$(security find-generic-password -s CONFLUENCE_API_TOKEN -w)\n'
+        '#   curl -sS -H "Authorization: Bearer $TOKEN" -X POST '
+        '"$CONFLUENCE_BASE_URL/rest/api/content" \\\n'
+        '#     -H "Content-Type: application/json" -d @- <<JSON\n'
+        f'#   {{"type":"page","title":{json.dumps(PAGE_TITLE_PREFIX + "-" + screen)},'
+        '"space":{"key":"$CONFLUENCE_SPACE"},'
+        '"ancestors":[{"id":"$CONFLUENCE_PARENT"}],'
+        f'"body":{{"storage":{{"value":"<{slug}.confluence.xml>","representation":"storage"}}}}}}\n#   JSON\n'
+        "#   (then attach screenshot.png + the overlay by filename).")
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("mapping", help="path to the mapping JSON (- for stdin)")
+    ap.add_argument("--out", default=".")
+    ap.add_argument("--slug")
+    ap.add_argument("--ui-lang", choices=["tr", "en"], default="en", help="document chrome language (default en)")
+    ap.add_argument("--docx", action="store_true", help="also write <slug>.docx (Word; stdlib, offline)")
+    ap.add_argument("--pdf", action="store_true", help="also write <slug>.pdf (via an installed renderer)")
+    ap.add_argument("--all", action="store_true", help="write every format (implies --docx --pdf)")
+    ap.add_argument("--print-upload", action="store_true")
+    args = ap.parse_args()
+    want_docx = args.docx or args.all
+    want_pdf = args.pdf or args.all
+
+    src = sys.stdin if args.mapping == "-" else open(args.mapping, encoding="utf-8")
+    m = json.load(src)
+    if "rows" not in m or "screen" not in m:
+        ap.error("mapping JSON needs at least 'screen' and 'rows' (see reference/format-and-output.md)")
+    global LEGACY_KEY_PREFIX
+    LEGACY_KEY_PREFIX = m.get("legacyKeyPrefix", "") or ""
+    t = T[args.ui_lang]
+    slug = args.slug or "".join(ch if ch.isalnum() else "-" for ch in m["screen"].lower()).strip("-")
+    while "--" in slug:
+        slug = slug.replace("--", "-")
+    os.makedirs(args.out, exist_ok=True)
+    ks_bases = ([os.path.dirname(os.path.abspath(args.mapping))] if args.mapping != "-" else [])
+    ks_bases += [os.path.abspath(args.out), os.getcwd()]
+    ks_dir = load_keyshots(m, ks_bases)   # fills m["_keyshots"] for the renderers
+    files = {f"{slug}.confluence.xml": render_storage(m, t),
+             f"{slug}.md": render_markdown(m, t),
+             f"{slug}.preview.html": render_html(m, t)}
+    for name, content in files.items():
+        with open(os.path.join(args.out, name), "w", encoding="utf-8") as fh:
+            fh.write(content)
+        print("wrote", os.path.join(args.out, name))
+
+    # Resolve a bare filename (screenshot / overlay) to an absolute path for embedding
+    # (docx) / loading (pdf): look beside the mapping, then in --out, then cwd.
+    def resolve_asset(name):
+        if not name:
+            return None
+        bases = [os.path.dirname(os.path.abspath(args.mapping))] if args.mapping != "-" else []
+        bases += [os.path.abspath(args.out), os.getcwd()]
+        for b in bases:
+            cand = name if os.path.isabs(name) else os.path.join(b, name)
+            if os.path.exists(cand):
+                return os.path.abspath(cand)
+        return None
+
+    shot_abs = resolve_asset(m.get("screenshot"))
+    overlay_abs = resolve_asset(m.get("overlay"))
+
+    docx_path = os.path.join(args.out, f"{slug}.docx")
+    html_path = os.path.join(args.out, f"{slug}.preview.html")
+    ks_abs = ({row: os.path.join(ks_dir, rel) for row, rel in keyshots_of(m).items()}
+              if ks_dir else None)
+    if want_docx or want_pdf:
+        # PDF via LibreOffice needs the docx; build it whenever either format is requested.
+        write_docx(m, t, docx_path, screenshot_path=shot_abs, overlay_path=overlay_abs,
+                   keyshot_paths=ks_abs)
+        if want_docx:
+            print("wrote", docx_path)
+    if want_pdf:
+        pdf_path = os.path.join(args.out, f"{slug}.pdf")
+        tool = to_pdf(pdf_path, docx_path=docx_path, html_path=html_path)
+        if tool:
+            print(f"wrote {pdf_path} (via {tool})")
+            # docx was only built as a means to the pdf and wasn't requested → clean it up
+            if not want_docx and os.path.exists(docx_path):
+                os.remove(docx_path)
+        else:
+            # leave the docx in place as the fallback we point the user at
+            keep = f"{slug}.docx" if (want_docx or os.path.exists(docx_path)) else f"{slug}.preview.html"
+            print(f"skipped {slug}.pdf  -  no PDF renderer found "
+                  f"(install LibreOffice/Chrome/wkhtmltopdf); share {keep} or {slug}.preview.html instead",
+                  file=sys.stderr)
+
+    if args.print_upload:
+        print("\n" + upload_curl(slug, m))
+
+
+if __name__ == "__main__":
+    main()