@mmerterden/multi-agent-pipeline 20.6.0 → 20.7.0

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

@@ -1,864 +1,803 @@
 #!/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.
+"""Turn a reuse-map mapping into the documents that get shared.
+
+Every run produces <slug>.md, the Confluence storage-format body
+<slug>.confluence.xml and <slug>.preview.html. A Word file and a PDF are added
+on request (--docx, --pdf, or both via --all). Output depends only on the
+mapping: no network access and no decisions are made here.
 """
 import argparse
 import html
 import json
 import os
+import re
+import shutil
+import struct
+import subprocess
 import sys
+import tempfile
+import time
+import unicodedata
+import zipfile
+from collections import namedtuple
+from xml.sax.saxutils import escape, quoteattr
+
+LANGS = ["en", "tr", "ar"] + sorted(["ru", "it", "fr", "es", "de"])
+WARN = "\u26a0\ufe0f"
+DASH = "-"
+VERDICTS = ("reuse", "review", "new")
+PLATFORM_NAMES = ("iOS", "Android", "Web")
+LEGACY_KEY_FIELDS = ("legacyKeyIOS", "legacyKeyAndroid", "legacyKeyWeb")
+FINAL_COPY = "content team's final copy"
+
+
+def summary_columns(element, shot, new_key, legacy, old, new, verdict, note):
+    return [
+        "#", element, shot, new_key,
+        *(f"{legacy} {platform}" for platform in PLATFORM_NAMES),
+        *(f"{age} {lang}" for age in (old, new) for lang in ("en", "tr")),
+        "CMS TR", "CMS EN", verdict, note,
+    ]
+
+
+def detail_columns(lang, old, new):
+    return [lang, f"{old} (legacy)", f"{new} (redesign)", "CMS"]
 
-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"],
+        "title": "Localization reuse map",
+        "intro": (
+            "For each UI element, the redesign key and value next to the legacy key per platform, "
+            f"the legacy value and the {FINAL_COPY} from Figma. "
+            "The verdict is a recommendation; the content team makes the call."
+        ),
+        "verdict": {v: v.upper() for v in VERDICTS},
+        "legend": {
+            "reuse": "same function and an equivalent value; adopt the legacy value or key, no new translation",
+            "review": "same function but the wording, value or key differs; the content team chooses",
+            "new": "no legacy counterpart; mint a key and a value",
+        },
+        "platforms": "Platforms",
+        "figma": "Figma nodes",
+        "screen": "Screen",
+        "keymap": "Key map",
+        "summary": "Summary",
+        "details": "Details",
+        "elements": "elements",
+        "cms_rows": "rows carry CMS copy",
+        "cms_drift": "differ from the new value",
+        "drift_note": (
+            f"A warning mark on a CMS cell means the {FINAL_COPY} differs from the new value. "
+            "CMS copy is context for the decision, not an input to the verdict."
+        ),
+        "no_screenshot": "No screenshot attached.",
+        "key": "Key",
+        "columns": summary_columns("UI element", "Screenshot", "New key", "Legacy", "Old", "New", "Verdict", "Note"),
+        "detail_columns": detail_columns("Lang", "Old", "New"),
+    },
+    "tr": {
+        "title": "Lokalizasyon yeniden kullan\u0131m haritas\u0131",
+        "intro": "Her aray\u00fcz \u00f6\u011fesi i\u00e7in yeni anahtar ve de\u011fer; platform baz\u0131nda eski anahtar, eski de\u011fer ve i\u00e7erik ekibinin Figma'daki son metni yan yana. Karar bir \u00f6neridir; son s\u00f6z i\u00e7erik ekibinindir.",
+        "verdict": {"reuse": "YEN\u0130DEN KULLAN", "review": "\u0130NCELE", "new": "YEN\u0130"},
+        "legend": {
+            "reuse": "ayn\u0131 i\u015flev ve e\u015fde\u011fer de\u011fer; eski de\u011fer ya da anahtar kullan\u0131l\u0131r, yeni \u00e7eviri gerekmez",
+            "review": "ayn\u0131 i\u015flev ama metin, de\u011fer ya da anahtar farkl\u0131; se\u00e7imi i\u00e7erik ekibi yapar",
+            "new": "eski kar\u015f\u0131l\u0131\u011f\u0131 yok; yeni anahtar ve de\u011fer gerekir",
+        },
+        "platforms": "Platformlar",
+        "figma": "Figma node'lar\u0131",
+        "screen": "Ekran",
+        "keymap": "Anahtar haritas\u0131",
+        "summary": "\u00d6zet",
+        "details": "Ayr\u0131nt\u0131lar",
+        "elements": "\u00f6\u011fe",
+        "cms_rows": "sat\u0131rda CMS metni var",
+        "cms_drift": "yeni de\u011ferden farkl\u0131",
+        "drift_note": "CMS h\u00fccresindeki uyar\u0131 i\u015fareti, i\u00e7erik ekibinin son metninin yeni de\u011ferden farkl\u0131 oldu\u011funu g\u00f6sterir. CMS metni karar i\u00e7in ba\u011flamd\u0131r, karar\u0131n girdisi de\u011fildir.",
+        "no_screenshot": "Ekran g\u00f6r\u00fcnt\u00fcs\u00fc eklenmedi.",
+        "key": "Anahtar",
+        "columns": summary_columns(
+            "Aray\u00fcz \u00f6\u011fesi", "Ekran g\u00f6r\u00fcnt\u00fcs\u00fc", "Yeni anahtar",
+            "Eski", "Eski", "Yeni", "Karar", "Not",
+        ),
+        "detail_columns": detail_columns("Dil", "Eski", "Yeni"),
     },
 }
 
-
-def e(s):
-    return html.escape("" if s in (None, "") else str(s), quote=True)
+Look = namedtuple("Look", "status mark badge shade")
+LOOKS = {
+    "reuse": Look("Green", "\u2705", "#1e8e3e", "E6F4EA"),
+    "review": Look("Yellow", "\U0001f536", "#e37400", "FDF3E2"),
+    "new": Look("Blue", "\U0001f195", "#1a73e8", "E8F0FE"),
+}
+UNKNOWN_LOOK = Look("Grey", "", "#80868b", None)
+EMU_PER_PX = 9525
+PNG_MAGIC = bytes([0x89]) + b"PNG\r\n\x1a\n"
 
 
-def dash(s):
-    return s if s not in (None, "") else "-"
+def look(row):
+    return LOOKS.get(row.get("verdict"), UNKNOWN_LOOK)
 
 
-def md(s):
-    return ("" if s in (None, "") else str(s)).replace("|", "\\|").replace("\n", " ")
+def slug(text):
+    value = re.sub(r"[\W_]+", "-", str(text or "").strip().lower()).strip("-")
+    return value or "screen"
 
 
-def vtext(t, vd):
-    return f'{VEMOJI.get(vd, "")} {t["verdict"].get(vd, vd)}'
+def norm(value):
+    text = unicodedata.normalize("NFC", str(value or "")).strip()
+    text = re.sub(r"\s+", " ", text)
+    text = re.sub(r"[.:\u2026]+$", "", text).strip()
+    return text.lower()
 
 
-LEGACY_KEY_PREFIX = ""
+def drifts(cms_value, new_value):
+    return bool(cms_value) and bool(new_value) and norm(cms_value) != norm(new_value)
 
 
-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 row_drifts(row):
+    cms, new = row.get("cms") or {}, row.get("new") or {}
+    return any(drifts(cms.get(lang), new.get(lang)) for lang in ("en", "tr"))
 
 
-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]}'
+def cms_cell(row, lang):
+    value = (row.get("cms") or {}).get(lang) or ""
+    if value and drifts(value, (row.get("new") or {}).get(lang)):
+        return f"{WARN} {value}"
+    return value
 
 
-# ---- 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 lang_values(row, lang):
+    legacy = (row.get("legacy") or {}).get(lang) or ""
+    fresh = (row.get("new") or {}).get(lang) or ""
+    return legacy, fresh, cms_cell(row, lang)
 
-def cms_of(r):
-    return r.get("cms") or {}
 
+def legacy_key(value, prefix):
+    value = str(value or "").strip()
+    if not value:
+        return DASH
+    if value.startswith("("):
+        return value
+    return prefix + value
 
-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 load_keyshots(mapping, mapping_dir, out_dir):
+    manifest_name = mapping.get("keyshots")
+    if not manifest_name:
+        return {}
+    hits = [
+        os.path.join(folder, manifest_name)
+        for folder in (mapping_dir, out_dir, os.getcwd())
+        if os.path.isfile(os.path.join(folder, manifest_name))
+    ]
+    if not hits:
+        print(
+            f"# warning: no keyshots manifest called {manifest_name} next to the mapping, "
+            "under --out or in the working directory; the Screenshot column is left empty",
+            file=sys.stderr,
+        )
+        return {}
+    with open(hits[0], encoding="utf-8") as stream:
+        manifest = json.load(stream)
+    folder = os.path.dirname(os.path.abspath(hits[0]))
+    shots = {}
+    for shot in manifest.get("shots") or []:
+        if str(shot.get("file", "")).endswith(".png"):
+            shots[int(shot["row"])] = os.path.join(folder, shot["file"])
+    return shots
+
+
+def node(name, attrs=(), *children):
+    opening = name + "".join(f" {k}={quoteattr(str(v))}" for k, v in attrs)
+    if not children:
+        return f"<{opening}/>"
+    return f"<{opening}>{''.join(children)}</{name}>"
+
+
+def header_cells(labels, esc):
+    return "".join(f"<th>{esc(label)}</th>" for label in labels)
+
+
+def storage_macro(kind, *children):
+    return node("ac:structured-macro", [("ac:name", kind)], *children)
+
+
+def storage_image(filename, dimension, pixels):
+    target = node("ri:attachment", [("ri:filename", os.path.basename(filename))])
+    return node("ac:image", [(f"ac:{dimension}", pixels)], target)
+
+
+class Doc:
+    def __init__(self, mapping, t, prefix, shots, out_dir):
+        self.m = mapping
+        self.t = t
+        self.prefix = prefix
+        self.shots = shots
+        self.out = out_dir
+        self.rows = mapping.get("rows") or []
+        self.counts = {v: sum(1 for r in self.rows if r.get("verdict") == v) for v in VERDICTS}
+        self.cms_rows = sum(1 for r in self.rows if (r.get("cms") or {}).get("tr") or (r.get("cms") or {}).get("en"))
+        self.drift_rows = sum(1 for r in self.rows if row_drifts(r))
+
+    def listed(self, field):
+        return ", ".join(self.m.get(field) or []) or DASH
+
+    def verdict(self, row):
+        return self.t["verdict"].get(row.get("verdict"), str(row.get("verdict") or "?").upper())
+
+    def count_line(self):
+        tally = " / ".join(f"{self.t['verdict'][v]} {self.counts[v]}" for v in VERDICTS)
+        return f"{tally} - {len(self.rows)} {self.t['elements']}"
+
+    def cms_line(self):
+        return f"CMS: {self.cms_rows} {self.t['cms_rows']}, {self.drift_rows} {self.t['cms_drift']}"
+
+    def summary_values(self, index, row):
+        old, new = row.get("legacy") or {}, row.get("new") or {}
+        keys = [legacy_key(row.get(field), self.prefix) for field in LEGACY_KEY_FIELDS]
+        texts = [side.get(lang) or "" for side in (old, new) for lang in ("en", "tr")]
+        return [
+            str(index), row.get("element") or "", None, row.get("newKey") or "",
+            *keys, *texts,
+            cms_cell(row, "tr"), cms_cell(row, "en"), None, row.get("note") or "",
+        ]
+
+    def detail_langs(self, row):
+        return LANGS + [lang for lang in (row.get("cms") or {}) if lang not in LANGS]
+
+    def md(self):
+        t, m = self.t, self.m
+
+        def flat(value):
+            return str(value).replace("|", "\\|").replace("\r", " ").replace("\n", " ")
+
+        def table_line(values):
+            return "| " + " | ".join(values) + " |"
+
+        lines = [f"# {t['title']}: {m.get('screen')}", "", t["intro"], ""]
+        lines.append(f"**{t['platforms']}:** {self.listed('platforms')}  ")
+        lines.append(f"**{t['figma']}:** {self.listed('figmaNodes')}")
+        lines += ["", f"## {t['screen']}", ""]
+        lines.append(f"![{t['screen']}]({m['screenshot']})" if m.get("screenshot") else t["no_screenshot"])
+        if m.get("overlay"):
+            lines += ["", f"## {t['keymap']}", "", f"![{t['keymap']}]({m['overlay']})"]
+        lines += ["", f"## {t['summary']}", "", self.count_line(), "", self.cms_line(), ""]
+        lines += [f"- {LOOKS[v].mark} **{t['verdict'][v]}**: {t['legend'][v]}" for v in VERDICTS]
+        lines += ["", f"> {WARN} {t['drift_note']}", ""]
+        lines.append(table_line(t["columns"]))
+        lines.append("|" + "---|" * len(t["columns"]))
+        for i, row in enumerate(self.rows, 1):
+            values = self.summary_values(i, row)
+            shot = self.shots.get(i)
+            values[2] = f"![{i}]({os.path.relpath(shot, self.out)})" if shot else DASH
+            values[3] = f"`{values[3]}`" if values[3] else DASH
+            values[4:7] = [DASH if v == DASH else f"`{v}`" for v in values[4:7]]
+            values[13] = f"{look(row).mark} {self.verdict(row)}".strip()
+            lines.append(table_line([flat(v) for v in values]))
+        lines += ["", f"## {t['details']}", ""]
+        for i, row in enumerate(self.rows, 1):
+            lines += [f"### {i}. {row.get('element') or ''} - {self.verdict(row)}", ""]
+            lines += [f"{t['key']}: `{row.get('newKey') or ''}`", ""]
+            lines.append(table_line(t["detail_columns"]))
+            lines.append("|---|---|---|---|")
+            for lang in self.detail_langs(row):
+                lines.append(table_line([lang] + [flat(v) for v in lang_values(row, lang)]))
+            lines.append("")
+        return "\n".join(lines) + "\n"
+
+    def status(self, row):
+        return storage_macro(
+            "status",
+            node("ac:parameter", [("ac:name", "colour")], look(row).status),
+            node("ac:parameter", [("ac:name", "title")], escape(self.verdict(row))),
+        )
+
+    def xml(self):
+        t, m = self.t, self.m
+        e = escape
+
+        def heading(label):
+            return f"<h2>{e(t[label])}</h2>"
+
+        def labelled(label, value):
+            return f"<strong>{e(t[label])}:</strong> {e(value)}"
+
+        legend = "".join(f"<li>{self.status({'verdict': v})} {e(t['legend'][v])}</li>" for v in VERDICTS)
+        facts = " | ".join([
+            labelled("screen", str(m.get("screen"))),
+            labelled("platforms", self.listed("platforms")),
+            labelled("figma", self.listed("figmaNodes")),
+        ])
+        notes = [t["intro"], self.count_line(), self.cms_line(), WARN + " " + t["drift_note"]]
+        info_body = f"<p>{e(notes[0])}</p><ul>{legend}</ul>" + "".join(f"<p>{e(n)}</p>" for n in notes[1:])
+        blocks = [
+            f"<p>{facts}</p>",
+            storage_macro("info", node("ac:rich-text-body", (), info_body)),
+            heading("screen"),
+        ]
+        if m.get("screenshot"):
+            blocks.append(f"<p>{storage_image(m['screenshot'], 'height', 500)}</p>")
+        else:
+            blocks.append(f"<p><em>{e(t['no_screenshot'])}</em></p>")
+        if m.get("overlay"):
+            blocks += [heading("keymap"), f"<p>{storage_image(m['overlay'], 'width', 900)}</p>"]
+        blocks.append(heading("summary"))
+        summary = []
+        for i, row in enumerate(self.rows, 1):
+            cells = []
+            for col, value in enumerate(self.summary_values(i, row)):
+                if col == 2:
+                    shot = self.shots.get(i)
+                    inner = storage_image(shot, "width", 240) if shot else DASH
+                elif col == 13:
+                    inner = self.status(row)
+                elif col in (3, 4, 5, 6) and value and value != DASH:
+                    inner = f"<code>{e(value)}</code>"
+                else:
+                    inner = e(value)
+                cells.append(f"<td>{inner}</td>")
+            summary.append("<tr>" + "".join(cells) + "</tr>")
+        blocks.append(f"<table><tbody><tr>{header_cells(t['columns'], e)}</tr>{''.join(summary)}</tbody></table>")
+        blocks.append(heading("details"))
+        for i, row in enumerate(self.rows, 1):
+            blocks.append(f"<h3>{i}. {e(row.get('element') or '')} {self.status(row)}</h3>")
+            blocks.append(f"<p>{e(t['key'])}: <code>{e(row.get('newKey') or '')}</code></p>")
+            lang_rows = "".join(
+                f"<tr><td>{lang}</td>" + "".join(f"<td>{e(v)}</td>" for v in lang_values(row, lang)) + "</tr>"
+                for lang in self.detail_langs(row)
+            )
+            blocks.append(f"<table><tbody><tr>{header_cells(t['detail_columns'], e)}</tr>{lang_rows}</tbody></table>")
+        return "\n".join(blocks) + "\n"
+
+    def src(self, path):
+        if not path:
+            return ""
+        return "file://" + path if os.path.isabs(path) else path
+
+    def preview(self):
+        t, m = self.t, self.m
+        e = html.escape
+
+        def badge(row):
+            return f'<span class="badge" style="background:{look(row).badge}">{e(self.verdict(row))}</span>'
+
+        legend = "".join(f"<li>{badge({'verdict': v})} {e(t['legend'][v])}</li>" for v in VERDICTS)
+        summary = []
+        for i, row in enumerate(self.rows, 1):
+            shot = self.shots.get(i)
+            cells = []
+            for col, value in enumerate(self.summary_values(i, row)):
+                if col == 2:
+                    inner = f'<img class="shot" src="{e(self.src(shot))}">' if shot else DASH
+                elif col == 13:
+                    inner = badge(row)
+                elif col in (3, 4, 5, 6):
+                    inner = f"<code>{e(value or DASH)}</code>"
+                else:
+                    inner = e(value)
+                cells.append(f"<td>{inner}</td>")
+            summary.append("<tr>" + "".join(cells) + "</tr>")
+        details = []
+        for i, row in enumerate(self.rows, 1):
+            lang_rows = "".join(
+                f"<tr><td>{lang}</td>" + "".join(f"<td>{e(v)}</td>" for v in lang_values(row, lang)) + "</tr>"
+                for lang in self.detail_langs(row)
+            )
+            details.append(
+                f"<h3>{i}. {e(row.get('element') or '')} {badge(row)}</h3>"
+                f"<p>{e(t['key'])}: <code>{e(row.get('newKey') or '')}</code></p>"
+                f"<table><tr>{header_cells(t['detail_columns'], e)}</tr>{lang_rows}</table>"
+            )
+        if m.get("screenshot"):
+            screen = f'<img class="screen" src="{e(self.src(m.get("screenshot")))}">'
+        else:
+            screen = f"<p>{e(t['no_screenshot'])}</p>"
+        overlay = ""
+        if m.get("overlay"):
+            overlay = f'<h3>{e(t["keymap"])}</h3><img class="overlay" src="{e(self.src(m.get("overlay")))}">'
+        small = "11px"
+        style = (
+            "body{font-family:-apple-system,Helvetica,Arial,sans-serif;margin:24px;color:#202124;}"
+            "table{border-collapse:collapse;margin:8px 0 16px;font-size:12px;}"
+            "th,td{border:1px solid #dadce0;padding:4px 6px;vertical-align:top;text-align:left;}"
+            f"th{{background:#f5f6f8;}}code{{font-size:{small};}}"
+            f".badge{{color:#fff;border-radius:4px;padding:1px 6px;font-size:{small};font-weight:600;}}"
+            ".screen{max-height:500px;}.overlay{max-width:100%;}.shot{width:200px;}"
+        )
+        caption = f"{e(t['title'])}: {e(str(m.get('screen')))}"
+        sections = [
+            (t["screen"], screen + overlay),
+            (t["summary"], f"<table><tr>{header_cells(t['columns'], e)}</tr>{''.join(summary)}</table>"),
+            (t["details"], "".join(details)),
+        ]
+        numbered = "".join(f"<h2>{n}. {e(title)}</h2>{content}" for n, (title, content) in enumerate(sections, 1))
+        return (
+            f'<!doctype html><html><head><meta charset="utf-8"><title>{caption}</title>'
+            f"<style>{style}</style></head><body>"
+            f"<h1>{caption}</h1><p>{e(t['intro'])}</p>"
+            f"<p><b>{e(t['platforms'])}:</b> {e(self.listed('platforms'))} | "
+            f"<b>{e(t['figma'])}:</b> {e(self.listed('figmaNodes'))}</p>"
+            f"<ul>{legend}</ul><p>{e(self.count_line())}<br>{e(self.cms_line())}</p><p>{e(WARN + ' ' + t['drift_note'])}</p>"
+            f"{numbered}</body></html>\n"
+        )
+
+
+def png_size(path):
+    try:
+        with open(path, "rb") as stream:
+            head = stream.read(24)
+    except OSError:
+        return None
+    if head.startswith(PNG_MAGIC):
+        return struct.unpack(">II", head[16:24])
+    return None
 
-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 fit(size, max_w, max_h):
+    w, h = size[0] * EMU_PER_PX, size[1] * EMU_PER_PX
+    ratio = min(max_w / w, max_h / h, 1.0)
+    return int(w * ratio), int(h * ratio)
 
-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)
 
+OOXML = "http://schemas.openxmlformats.org/"
+NS_DRAWING = OOXML + "drawingml/2006/"
+NS_DOC_REL = OOXML + "officeDocument/2006/relationships"
+XML_DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+MIME_OOXML = "application/vnd.openxmlformats-"
 
-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 prefixed(ns):
+    def build(tag, *children, **attrs):
+        return node(f"{ns}:{tag}", [(f"{ns}:{k}", v) for k, v in attrs.items()], *children)
+    return build
 
-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]}'
 
+w = prefixed("w")
 
-# ---- 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 plain(ns):
+    def build(tag, *children, **attrs):
+        return node(f"{ns}:{tag}", list(attrs.items()), *children)
+    return build
 
 
-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
+a, pic, wp = plain("a"), plain("pic"), plain("wp")
 
 
-# ---- 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)}
-"""
+class Docx:
+    def __init__(self):
+        self.media = []
 
+    def image(self, path, rid, max_w, max_h, number):
+        size = png_size(path)
+        if not size:
+            return ""
+        cx, cy = fit(size, max_w, max_h)
+        media_name = f"image{number}.png"
+        self.media.append((rid, path, media_name))
+        extent = {"cx": cx, "cy": cy}
+        origin = {"x": 0, "y": 0}
+        shape = pic(
+            "spPr",
+            a("xfrm", a("off", **origin), a("ext", **extent)),
+            a("prstGeom", a("avLst"), prst="rect"),
+        )
+        fill = pic("blipFill", node("a:blip", [("r:embed", rid)]), a("stretch", a("fillRect")))
+        identity = pic("nvPicPr", pic("cNvPr", id=number, name=media_name), pic("cNvPicPr"))
+        picture = node("pic:pic", [("xmlns:pic", NS_DRAWING + "picture")], identity, fill, shape)
+        graphic = node(
+            "a:graphic", [("xmlns:a", NS_DRAWING + "main")],
+            a("graphicData", picture, uri=NS_DRAWING + "picture"),
+        )
+        inline = wp("inline", wp("extent", **extent), wp("docPr", id=number, name=f"Picture {number}"), graphic)
+        return w("r", w("drawing", inline))
 
-# ---- 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 para(text, bold=False, size=None, rtl=False):
+    styling = []
+    if bold:
+        styling.append(w("b"))
+    if size:
+        styling.append(w("sz", val=size))
+    if rtl:
+        styling.append(w("rtl"))
+    run = [w("rPr", *styling)] if styling else []
+    run.append(node("w:t", [("xml:space", "preserve")], escape(str(text))))
+    lead = [w("pPr", w("bidi"))] if rtl else []
+    return w("p", *lead, w("r", *run))
 
 
-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 tcell(content, fill=None, raw=False, rtl=False):
+    inner = content if raw else para(content, rtl=rtl)
+    shading = [w("tcPr", w("shd", val="clear", color="auto", fill=fill))] if fill else []
+    return w("tc", *shading, inner or w("p"))
 
 
-def _dxe(s):
-    """Escape text for WordprocessingML (same rules as XML)."""
-    return html.escape("" if s in (None, "") else str(s), quote=True)
+EDGES = ("top", "left", "bottom", "right") + tuple("inside" + axis for axis in "HV")
 
 
-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 table(rows_xml):
+    lines = "".join(w(edge, val="single", sz=4, color="DADCE0") for edge in EDGES)
+    props = w("tblPr", w("tblW", w=0, type="auto"), w("tblBorders", lines))
+    return w("tbl", props, *rows_xml)
 
 
-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 local_file(doc, name):
+    if not name:
+        return None
+    if os.path.isabs(name):
+        return name if os.path.isfile(name) else None
+    for base in (doc.base, doc.out):
+        candidate = os.path.join(base, name)
+        if os.path.isfile(candidate):
+            return candidate
+    return None
 
 
-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 table_row(cells):
+    return "<w:tr>" + "".join(cells) + "</w:tr>"
+
+
+def heading(text):
+    return para(text, bold=True, size=28)
+
+
+def summary_table(doc, dx, t):
+    lines = [table_row(tcell(c, fill="F5F6F8") for c in t["columns"])]
+    for i, row in enumerate(doc.rows, 1):
+        cells = []
+        for col, value in enumerate(doc.summary_values(i, row)):
+            if col == 2:
+                shot_file = doc.shots.get(i)
+                drawing = dx.image(shot_file, f"rId{200 + i}", 1_900_000, 2_600_000, 200 + i) if shot_file else ""
+                cells.append(tcell(f"<w:p>{drawing}</w:p>" if drawing else para(DASH), raw=True))
+            elif col == 13:
+                cells.append(tcell(doc.verdict(row), fill=look(row).shade))
+            elif col == 11:
+                tr_drift = drifts((row.get("cms") or {}).get("tr"), (row.get("new") or {}).get("tr"))
+                cells.append(tcell(value, fill="FCE4F1" if tr_drift else None))
+            else:
+                cells.append(tcell(value))
+        lines.append(table_row(cells))
+    return table(lines)
+
+
+def detail_blocks(doc, t):
+    blocks = []
+    for i, row in enumerate(doc.rows, 1):
+        blocks.append(para(f"{i}. {row.get('element') or ''} - {doc.verdict(row)}", bold=True))
+        blocks.append(para(f"{t['key']}: {row.get('newKey') or ''}"))
+        lines = [table_row(tcell(c, fill="F5F6F8") for c in t["detail_columns"])]
+        for lang in doc.detail_langs(row):
+            lines.append(table_row(tcell(v, rtl=lang == "ar") for v in (lang, *lang_values(row, lang))))
+        blocks.append(table(lines))
+    return blocks
+
+
+def page_setup():
+    margins = dict.fromkeys(("top", "right", "bottom", "left"), 720)
+    return w(
+        "sectPr",
+        w("pgSz", w=16838, h=11906, orient="landscape"),
+        w("pgMar", **margins, header=360, footer=360, gutter=0),
     )
 
 
-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)):
+def docx_parts(document, media):
+    image_rels = "".join(
+        node("Relationship", [("Id", rid), ("Type", NS_DOC_REL + "/image"), ("Target", f"media/{name}")])
+        for rid, _, name in media
+    )
+    defaults = [("rels", MIME_OOXML + "package.relationships+xml"), ("xml", "application/xml"), ("png", "image/png")]
+    types = "".join(node("Default", [("Extension", ext), ("ContentType", kind)]) for ext, kind in defaults)
+    types += node("Override", [
+        ("PartName", "/word/document.xml"),
+        ("ContentType", MIME_OOXML + "officedocument.wordprocessingml.document.main+xml"),
+    ])
+    root_rel = node("Relationship", [
+        ("Id", "rId1"), ("Type", NS_DOC_REL + "/officeDocument"), ("Target", "word/document.xml"),
+    ])
+    rels_ns = f'<Relationships xmlns="{OOXML}package/2006/relationships">'
+    return [
+        ("[Content_Types].xml", f'{XML_DECL}<Types xmlns="{OOXML}package/2006/content-types">{types}</Types>'),
+        ("_rels/.rels", f"{XML_DECL}{rels_ns}{root_rel}</Relationships>"),
+        ("word/_rels/document.xml.rels", f"{XML_DECL}{rels_ns}{image_rels}</Relationships>"),
+        ("word/document.xml", document),
+    ]
+
+
+def build_docx(doc, path):
+    t, m = doc.t, doc.m
+    dx = Docx()
+    body = [
+        para(f"{t['title']}: {m.get('screen')}", bold=True, size=32),
+        para(t["intro"]),
+        para(f"{t['platforms']}: {doc.listed('platforms')} | {t['figma']}: {doc.listed('figmaNodes')}"),
+    ]
+    body += [para(f"{t['verdict'][v]}: {t['legend'][v]}") for v in VERDICTS]
+    body += [para(doc.count_line()), para(doc.cms_line()), para(f"{WARN} {t['drift_note']}")]
+    body.append(heading(t["screen"]))
+    screenshot = local_file(doc, m.get("screenshot"))
+    if screenshot:
+        body.append(w("p", dx.image(screenshot, "rId100", 5_000_000, 5_500_000, 100)))
+    else:
+        body.append(para(t["no_screenshot"]))
+    overlay = local_file(doc, m.get("overlay"))
+    if overlay:
+        body += [heading(t["keymap"]), w("p", dx.image(overlay, "rId101", 9_000_000, 5_500_000, 101))]
+    body += [heading(t["summary"]), summary_table(doc, dx, t), heading(t["details"])]
+    body += detail_blocks(doc, t)
+    namespaces = [
+        ("xmlns:w", OOXML + "wordprocessingml/2006/main"),
+        ("xmlns:r", NS_DOC_REL),
+        ("xmlns:wp", NS_DRAWING + "wordprocessingDrawing"),
+    ]
+    document = XML_DECL + node("w:document", namespaces, w("body", *body, page_setup()))
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as archive:
+        for member, text in docx_parts(document, dx.media):
+            archive.writestr(member, text)
+        for _, source, media_name in dx.media:
+            archive.write(source, f"word/media/{media_name}")
+
+
+def mac_app(bundle, binary=None):
+    return f"/Applications/{bundle}.app/Contents/MacOS/{binary or bundle}"
+
+
+BROWSER_APPS = [mac_app("Google Chrome"), mac_app("Chromium"), mac_app("Microsoft Edge")]
+BROWSER_COMMANDS = (
+    [f"google-chrome{tail}" for tail in ("", "-stable")]
+    + [f"chromium{tail}" for tail in ("", "-browser")]
+    + ["chrome"]
+)
+
+
+def chrome_candidates():
+    listed = [os.environ.get("CHROME_BIN")] + BROWSER_APPS
+    found = [path for path in listed if path and os.path.isfile(path)]
+    found += [hit for hit in map(shutil.which, BROWSER_COMMANDS) if hit]
+    return found
+
+
+def pdf_libreoffice(docx_path, out_dir):
+    binaries = [shutil.which("soffice"), shutil.which("libreoffice"), mac_app("LibreOffice", "soffice")]
+    expected = os.path.splitext(docx_path)[0] + ".pdf"
+    for binary in binaries:
+        if not (binary and os.path.isfile(binary)):
             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
+        try:
+            subprocess.run([binary, "--headless", "--convert-to", "pdf", "--outdir", out_dir, docx_path],
+                           capture_output=True, timeout=180)
+        except (OSError, subprocess.SubprocessError):
+            continue
+        if os.path.isfile(expected) and os.path.getsize(expected) > 0:
+            return expected
+    return None
 
 
-def _nonempty(path):
-    return bool(path) and os.path.exists(path) and os.path.getsize(path) > 0
+def settle(proc, path, limit):
+    deadline = time.time() + limit
+    previous = -1
+    while time.time() < deadline and proc.poll() is None:
+        current = os.path.getsize(path) if os.path.exists(path) else -1
+        if current > 0 and current == previous:
+            break
+        previous = current
+        time.sleep(1)
+    if proc.poll() is None:
+        proc.kill()
+        proc.wait()
 
 
-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)}"
+def pdf_chrome(preview_path, pdf_path):
+    page = "file://" + os.path.abspath(preview_path)
+    for chrome in chrome_candidates():
         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"
-
+            with tempfile.TemporaryDirectory() as profile:
+                if os.path.exists(pdf_path):
+                    os.remove(pdf_path)
+                argv = [chrome, headless, "--disable-gpu", f"--user-data-dir={profile}", "--no-pdf-header-footer",
+                        f"--print-to-pdf={pdf_path}", page]
+                try:
+                    proc = subprocess.Popen(argv, stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
+                except OSError:
+                    break
+                settle(proc, pdf_path, 90)
+                if os.path.isfile(pdf_path) and os.path.getsize(pdf_path) > 0:
+                    return pdf_path
     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'
-        '#   printf \'Authorization: Bearer %s\\n\' "$TOKEN" | curl -sS -H @- -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 pdf_wkhtml(preview_path, pdf_path):
+    binary = shutil.which("wkhtmltopdf")
+    if not binary:
+        return None
+    try:
+        subprocess.run([binary, "--enable-local-file-access", preview_path, pdf_path], capture_output=True, timeout=120)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return pdf_path if os.path.isfile(pdf_path) and os.path.getsize(pdf_path) > 0 else None
+
+
+def print_upload(name, mapping, screen):
+    prefix = os.environ.get("LOCALIZATION_PAGE_PREFIX", "Localization")
+    flags = [f"--xml {name}.confluence.xml", f'--screen "{screen}"']
+    flags += [f"--{field} {mapping[field]}" for field in ("screenshot", "overlay", "keyshots") if mapping.get(field)]
+    flags.append(f"--attach {name}.localization.xlsx")
+    print(" \\\n  ".join(["python3 scripts/publish-confluence.py"] + flags))
+    print()
+    print("# The same call by hand, for Server/DC with a Bearer PAT read from the keychain (argv never sees the token):")
+    print("#   printf 'header = \"Authorization: Bearer %s\"\\n' \"$(security find-generic-password -s CONFLUENCE_API_TOKEN -w)\" > auth.curlrc; chmod 600 auth.curlrc")
+    print("#   curl -sS -K auth.curlrc -X POST -H 'Content-Type: application/json' \"$CONFLUENCE_BASE_URL/rest/api/content\" \\")
+    print(f"#     --data '{{\"type\":\"page\",\"title\":\"{prefix} - {screen}\",\"space\":{{\"key\":\"'$CONFLUENCE_SPACE'\"}},"
+          "\"ancestors\":[{\"id\":\"'$CONFLUENCE_PARENT'\"}],\"body\":{\"storage\":{\"value\":\"...\",\"representation\":\"storage\"}}}'")
+    print("#   rm auth.curlrc")
+
+
+def read_mapping(source):
+    if source == "-":
+        return json.load(sys.stdin), os.getcwd()
+    with open(source, encoding="utf-8") as stream:
+        return json.load(stream), os.path.dirname(os.path.abspath(source))
+
+
+def make_pdf(docx_path, out_dir, stem, keep_docx):
+    preview = os.path.join(out_dir, f"{stem}.preview.html")
+    target = os.path.join(out_dir, f"{stem}.pdf")
+    made = pdf_libreoffice(docx_path, out_dir) or pdf_chrome(preview, target) or pdf_wkhtml(preview, target)
+    if not made:
+        fallback = docx_path if os.path.exists(docx_path) else preview
+        print(f"# no PDF: LibreOffice, Chrome and wkhtmltopdf are all missing; hand out {fallback} instead", file=sys.stderr)
+        return
+    print(f"wrote {made}")
+    if not keep_docx and os.path.exists(docx_path):
+        os.remove(docx_path)
 
 
 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))
+    cli = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    cli.add_argument("mapping", help="reuse-map JSON file; pass - to read it from stdin")
+    cli.add_argument("--out", dest="target_dir", default=".", help="folder that receives the generated files")
+    cli.add_argument("--slug", help="stem for the file names; derived from the screen name when omitted")
+    cli.add_argument("--ui-lang", choices=["en", "tr"], default="en", help="language used for headings, the legend and labels")
+    cli.add_argument("--docx", action="store_true", help="add a Word document to the outputs")
+    cli.add_argument("--pdf", action="store_true", help="add a PDF to the outputs")
+    cli.add_argument("--all", action="store_true", help="shorthand for --docx plus --pdf")
+    cli.add_argument("--print-upload", action="store_true", help="show the publish command and a hand-rolled curl version of it")
+    opts = cli.parse_args()
+
+    mapping, mapping_dir = read_mapping(opts.mapping)
+    if not isinstance(mapping, dict) or "screen" not in mapping or "rows" not in mapping:
+        cli.error("mapping must be a JSON object with screen and rows")
+
+    stem = opts.slug or slug(mapping.get("screen"))
+    out_dir = os.path.abspath(opts.target_dir)
+    os.makedirs(out_dir, exist_ok=True)
+    shots = load_keyshots(mapping, mapping_dir, out_dir)
+    doc = Doc(mapping, T[opts.ui_lang], mapping.get("legacyKeyPrefix") or "", shots, out_dir)
+    doc.base = mapping_dir
+
+    renderers = [("md", doc.md), ("confluence.xml", doc.xml), ("preview.html", doc.preview)]
+    for suffix, render in renderers:
+        target = os.path.join(out_dir, f"{stem}.{suffix}")
+        with open(target, "w", encoding="utf-8") as sink:
+            sink.write(render())
+        print(f"wrote {target}")
+
+    keep_docx = opts.docx or opts.all
+    need_pdf = opts.pdf or opts.all
+    docx_path = os.path.join(out_dir, f"{stem}.docx")
+    if keep_docx or need_pdf:
+        build_docx(doc, docx_path)
+        if keep_docx:
+            print(f"wrote {docx_path}")
+    if need_pdf:
+        make_pdf(docx_path, out_dir, stem, keep_docx)
+
+    if opts.print_upload:
+        print_upload(stem, mapping, mapping.get("screen"))
 
 
 if __name__ == "__main__":