@mmerterden/multi-agent-pipeline 20.5.0 → 20.7.0

package/pipeline/skills/shared/external/localization-reuse-map/scripts/render-overlay.py

@@ -1,528 +1,523 @@
 #!/usr/bin/env python3
-"""Render a "which key ↔ which UI element" overlay image for one screen.
-
-Figma's own image render does NOT include the Dev Mode annotation overlay, so this
-RECONSTRUCTS it deterministically: the screen image (REST render or an MCP-supplied
-data URL) on the right, one card per keyable text element on the left, each card
-tying the **localization key** to the element and showing the content team's
-**CMS TR/EN** copy where annotated. No AI image generation  -  pure geometry + HTML +
-headless Chrome (with an `.html` fallback when no Chrome is present).
-
-Two input modes (mirrors fetch-annotations.py's REST/MCP split):
-  * REST (default)  -  needs a Figma token (--token / env / keychain FIGMA_ACCESS_TOKEN):
-      geometry  `GET /v1/files/<key>/nodes?ids=<id>`  → absoluteBoundingBox
-      image     `GET /v1/images/<key>?ids=<id>&format=png&scale=<n>` → PNG url → data URL
-  * --spec <file> (MCP / no network): { fileKey, pages:[{nodeId,name,image:<dataUrl>,
-      frame:{w,h}, nodes:[{characters,tr,en,x,y,w,h}] }] }  -  the orchestrator builds
-      this from get_screenshot + use_figma so no REST calls happen.
-
-Cards are keyed off the run's **mapping JSON** (`--mapping`): each text node is matched to
-a mapping row (by `cmsNodeId`, else by normalized value) to label the card with its
-`newKey`. A node carrying a Final UX Writing annotation → pink "İçerik (CMS)" card with
-TR/EN; a keyable node without one → gray "Öneri bekleniyor" card with the on-screen text.
-Non-keyable text (no key, no annotation) is dropped.
-
-**No annotations needed.** When value-matching is unreliable (design wording ≠ resolved
-values, or the frame mixes in background content), anchor explicitly: set each row's
-`cmsNodeId` to a synthetic id and feed a `--spec` whose nodes carry the same `id` + the
-box read off the clean screenshot  -  `cmsNodeId` matching is exact, so the overlay is
-faithful with zero annotations. (`design-export/.../tree.json` is component-instance level
-- use its root `nodeId` for the REST frame, not for per-label boxes.)
-
-Output: `<out>/<slug>.overlay.png` (or `<slug>.overlay.html` fallback) + a sibling
-`<slug>.overlay.manifest.json` (`page → file → {fileKey,nodeId}`) so the publish step
-can find the image to attach. Read-only against every source.
+"""Draw the overlay that ties each localization key to its place on one screen.
+
+The screen image sits in the middle; every keyed element gets a numbered card
+at the side and a dashed line leading to it. A card's number equals the index,
+counted from 1, of its matching entry in mapping.rows. Boxes are read from
+Figma over REST, or taken from a --spec file, and headless Chrome turns the
+HTML page into a PNG. The same input always gives the same picture; nothing is
+generated by a model.
 """
 import argparse
 import base64
+import html
 import json
 import os
 import re
+import shutil
 import ssl
 import subprocess
 import sys
 import tempfile
+import time
 import unicodedata
 import urllib.error
 import urllib.parse
 import urllib.request
 
-FIGMA_API = "https://api.figma.com/v1"
-OUT_SUFFIX = ".overlay.png"
+API = "https://api.figma.com/v1"
+SEP = "[:\\-\u2013]"
+TR_RE = re.compile("^(?:tr|tr[kc]e|t[\u00fcu]rk[\u00e7c]e)\\s*" + SEP + "\\s*(.+)$", re.IGNORECASE)
+EN_RE = re.compile("^(?:en|eng|ing|[i\u0130]ngilizce)\\s*" + SEP + "\\s*(.+)$", re.IGNORECASE)
 
-# --- card layout constants (ported from web render-annotations.mjs) --------
 CARD_W = 320
-COL_X = 24
+COLUMN_X = 24
 CHANNEL = 190
-DESIGN_X = COL_X + CARD_W + CHANNEL
-RIGHT_MARGIN = 40
 TOP = 60
 CARD_H = 116
-CARD_GAP = 14
+GAP = 14
+RIGHT_MARGIN = 40
 PINK = "#EC1E91"
 GRAY = "#9aa0a6"
+BACKGROUND = "#1e1e1e"
+LABEL_CMS = "\u0130\u00e7erik (CMS)"
+LABEL_PENDING = "\u00d6neri bekleniyor"
+LABEL_UNMATCHED = "(e\u015fle\u015fmedi)"
 
-# Annotation authors separate label from value with a colon, a hyphen, or the
-# en-dash their editor auto-inserts. Built from the codepoint so this file
-# carries no literal dash variant of its own.
-_DASHES = ':\\-' + chr(0x2013)
-RE_TR = re.compile(rf"^(?:tr|tr[kc]e|t[üu]rk[çc]e)\s*[{_DASHES}]\s*(.+)$", re.I)
-RE_EN = re.compile(rf"^(?:en|eng|ing|[iİ]ngilizce)\s*[{_DASHES}]\s*(.+)$", re.I)
-
-
-def split_lang(raw):
-    if not raw:
-        return {"tr": None, "en": None}
-    lines = [ln.strip() for ln in re.split(r"\r?\n", raw) if ln.strip()]
-    tr = en = None
-    bare = []
-    for ln in lines:
-        m = RE_TR.match(ln)
-        if m and tr is None:
-            tr = m.group(1).strip()
-            continue
-        m = RE_EN.match(ln)
-        if m and en is None:
-            en = m.group(1).strip()
-            continue
-        bare.append(ln)
-    if tr is not None or en is not None:
-        bi = 0
-        if tr is None and bi < len(bare):
-            tr = bare[bi]; bi += 1
-        if en is None and bi < len(bare):
-            en = bare[bi]; bi += 1
-        return {"tr": tr, "en": en}
-    if len(bare) >= 2:
-        return {"tr": bare[0], "en": bare[1]}
-    if len(bare) == 1:
-        return {"tr": bare[0], "en": None}
-    return {"tr": None, "en": None}
-
-
-def canon_id(s):
-    return re.sub(r"^(\d+)-(\d+)$", r"\1:\2", (s or "").strip())
-
-
-def norm(s):
-    """NFC → trim → collapse whitespace → strip trailing .:... → lower (web `norm`)."""
-    if not s:
-        return ""
-    s = unicodedata.normalize("NFC", s).strip()
-    s = re.sub(r"\s+", " ", s)
-    s = re.sub(r"[.:...]+$", "", s).strip()
-    return s.lower()
-
-
-def slug(s):
-    s = (s or "screen").strip()
-    s = re.sub(r'[/\\:*?"<>|]+', "-", s)
-    s = re.sub(r"\s+", "-", s)
-    s = re.sub(r"-{2,}", "-", s)
-    return s.strip("-").lower() or "screen"
-
-
-def esc(s):
-    return (str(s) if s is not None else "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
-
-
-# --- Figma token + HTTP (self-contained, mirrors fetch-annotations.py) ------
-def figma_token(args):
-    if args.token:
-        return args.token
-    for env in ("FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN"):
-        v = os.environ.get(env)
-        if v:
-            return v.strip()
-    try:
-        r = subprocess.run(
-            ["security", "find-generic-password", "-s", "FIGMA_ACCESS_TOKEN", "-w"],
-            capture_output=True, text=True)
-        if r.returncode == 0 and r.stdout.strip():
-            return r.stdout.strip()
-    except Exception:
-        pass
-    return None
+PAGE_OPEN = "<!doctype html><html><head>"
+META_UTF8 = '<meta charset="utf-8">'
+
+
+def mac_app(bundle):
+    return f"/Applications/{bundle}.app/Contents/MacOS/{bundle}"
+
+
+MAC_CHROMES = [mac_app(name) for name in ("Google Chrome", "Chromium", "Microsoft Edge")]
+PATH_CHROMES = (
+    [f"google-chrome{tail}" for tail in ("", "-stable")]
+    + [f"chromium{tail}" for tail in ("", "-browser")]
+    + ["chrome"]
+)
+
+
+def canon_id(node_id):
+    return str(node_id or "").strip().replace("-", ":")
+
+
+def slug(text):
+    value = re.sub(r"[\W_]+", "-", str(text or "").strip().lower()).strip("-")
+    return value or "screen"
+
+
+def split_lang(text):
+    picked = {"tr": None, "en": None}
+    loose = []
+    for line in filter(None, (piece.strip() for piece in str(text or "").splitlines())):
+        tr_hit, en_hit = TR_RE.match(line), EN_RE.match(line)
+        if tr_hit and picked["tr"] is None:
+            picked["tr"] = tr_hit.group(1).strip()
+        elif en_hit and picked["en"] is None:
+            picked["en"] = en_hit.group(1).strip()
+        else:
+            loose.append(line)
+    if picked["tr"] is None and picked["en"] is None:
+        padded = loose + [None, None]
+        style = {0: "empty", 1: "single"}.get(len(loose), "two-line")
+        return {"tr": padded[0], "en": padded[1], "mode": style}
+    spare = iter(loose)
+    for lang in ("tr", "en"):
+        if picked[lang] is None:
+            picked[lang] = next(spare, None)
+    return dict(picked, mode="prefixed")
+
+
+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()
 
 
-def _ctx(ca_file):
-    return ssl.create_default_context(cafile=ca_file) if ca_file else ssl.create_default_context()
+def build_index(rows):
+    by_id, by_value = {}, {}
+    for position, entry in enumerate(rows):
+        if entry.get("cmsNodeId"):
+            by_id.setdefault(canon_id(entry["cmsNodeId"]), position)
+        texts = [(entry.get(block) or {}).get(lang) for block in ("new", "cms", "legacy") for lang in ("tr", "en")]
+        texts.append(entry.get("element"))
+        for text in texts:
+            normalised = norm(text)
+            if normalised:
+                by_value.setdefault(normalised, position)
+    return {"id": by_id, "value": by_value}
+
+
+def match_row(node, index):
+    node_id = canon_id(node.get("id"))
+    if node_id in index["id"]:
+        return index["id"][node_id]
+    for field in ("tr", "characters"):
+        key = norm(node.get(field))
+        if key and key in index["value"]:
+            return index["value"][key]
+    return None
 
 
-def http_get_json(url, headers, ca_file):
-    req = urllib.request.Request(url, headers=headers)
+def keychain_secret(service):
     try:
-        with urllib.request.urlopen(req, context=_ctx(ca_file), timeout=60) as r:
-            return json.load(r)
-    except urllib.error.HTTPError as e:
-        if e.code == 429:
-            sys.exit("Figma 429 (rate-limited)  -  re-run with --spec (MCP path) instead.")
-        sys.exit(f"Figma HTTP {e.code} for {url}: {e.read()[:200]!r}")
-    except urllib.error.URLError as e:
-        sys.exit(f"Figma request failed: {getattr(e, 'reason', e)}")
+        lookup = subprocess.run(
+            ["security", "find-generic-password", "-s", service, "-w"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    secret = lookup.stdout.strip()
+    return secret if lookup.returncode == 0 and secret else None
+
 
+def figma_token(explicit):
+    if explicit:
+        return explicit
+    from_env = next((os.environ[v] for v in ("FIGMA_ACCESS_TOKEN", "FIGMA_TOKEN") if os.environ.get(v)), None)
+    return from_env or keychain_secret("FIGMA_ACCESS_TOKEN")
 
-def http_get_bytes(url, ca_file):
+
+def _open(url, headers, ca_file, timeout):
+    tls = ssl.create_default_context(cafile=ca_file) if ca_file else None
     try:
-        with urllib.request.urlopen(url, context=_ctx(ca_file), timeout=120) as r:
-            return r.read()
-    except Exception as e:
-        sys.exit(f"image fetch failed: {e}")
-
-
-# --- node collection (REST) ------------------------------------------------
-def node_anno(node):
-    anns = node.get("annotations")
-    if not isinstance(anns, list):
-        return {"tr": None, "en": None}
-    for a in anns:
-        if not isinstance(a, dict):
-            continue
-        lbl = a.get("label") or a.get("labelMarkdown") or ""
-        if lbl:
-            p = split_lang(lbl)
-            if p["tr"] is not None or p["en"] is not None:
-                return p
-    return {"tr": None, "en": None}
-
-
-def collect_rest_nodes(file_key, node_id, token, ca_file, scale):
-    headers = {"X-Figma-Token": token}
-    data = http_get_json(f"{FIGMA_API}/files/{file_key}/nodes?ids={urllib.parse.quote(node_id, safe='')}",
-                         headers, ca_file)
-    entry = (data.get("nodes") or {}).get(node_id) or {}
-    doc = entry.get("document")
-    if not doc:
-        sys.exit(f"node {node_id} not found in file {file_key}")
-    fb = doc.get("absoluteBoundingBox") or {"x": 0, "y": 0, "width": 0, "height": 0}
-    frame = {"w": round(fb.get("width", 0)), "h": round(fb.get("height", 0))}
-    nodes = []
+        with urllib.request.urlopen(urllib.request.Request(url, headers=headers), timeout=timeout, context=tls) as reply:
+            return reply.read()
+    except urllib.error.HTTPError as exc:
+        if exc.code == 429:
+            sys.exit("Figma is rate limiting (HTTP 429). Measure the boxes on the screenshot and supply them through --spec.")
+        snippet = exc.read()[:200].decode("utf-8", "replace")
+        sys.exit(f"Figma HTTP {exc.code} for {url}: {snippet}")
+    except urllib.error.URLError as exc:
+        sys.exit(f"Could not reach Figma: {exc.reason}")
 
-    def walk(n):
-        b = n.get("absoluteBoundingBox")
-        is_text = n.get("type") == "TEXT" and isinstance(n.get("characters"), str) and n["characters"].strip()
-        ann = node_anno(n)
-        if b and (is_text or ann["tr"] is not None or ann["en"] is not None):
-            nodes.append({
-                "id": n.get("id"),
-                "characters": n.get("characters") if is_text else "",
-                "tr": ann["tr"], "en": ann["en"],
-                "x": round(b["x"] - fb["x"]), "y": round(b["y"] - fb["y"]),
-                "w": round(b["width"]), "h": round(b["height"]),
-            })
-        for c in n.get("children", []) or []:
-            walk(c)
-
-    walk(doc)
-
-    # image render → data URL
-    img = http_get_json(
-        f"{FIGMA_API}/images/{file_key}?ids={urllib.parse.quote(node_id, safe='')}&format=png&scale={scale}",
-        headers, ca_file)
-    url = (img.get("images") or {}).get(node_id)
-    if not url:
-        sys.exit(f"no image render returned for {node_id}")
-    raw = http_get_bytes(url, ca_file)
-    data_url = "data:image/png;base64," + base64.b64encode(raw).decode("ascii")
-    return {"nodeId": node_id, "image": data_url, "frame": frame, "nodes": nodes}
-
-
-# --- card model ------------------------------------------------------------
-def build_index(rows):
-    by_node, by_val = {}, {}
-    for r in rows:
-        key = r.get("newKey")
-        if not key:
-            continue
-        nid = r.get("cmsNodeId")
-        if nid:
-            by_node[canon_id(nid)] = r
-        # index every known value (tr + en across new / cms / legacy) so a node
-        # matches its key regardless of the frame's language or wording source
-        for src in (r.get("new") or {}, r.get("cms") or {}, r.get("legacy") or {}):
-            if isinstance(src, dict):
-                for lang in ("tr", "en"):
-                    v = src.get(lang)
-                    if v:
-                        by_val.setdefault(norm(v), r)
-        if r.get("element"):
-            by_val.setdefault(norm(r["element"]), r)
-    return by_node, by_val
-
-
-def match_row(node, by_node, by_val):
-    nid = canon_id(node.get("id") or "")
-    if nid in by_node:
-        return by_node[nid]
-    for v in (node.get("tr"), node.get("characters")):
-        if v and norm(v) in by_val:
-            return by_val[norm(v)]
+
+def http_json(url, token, ca_file, timeout=60):
+    return json.loads(_open(url, {"X-Figma-Token": token}, ca_file, timeout).decode("utf-8"))
+
+
+def http_bytes(url, ca_file, timeout=120):
+    return _open(url, {}, ca_file, timeout)
+
+
+def as_data_uri(png_bytes):
+    return "data:image/png;base64," + base64.b64encode(png_bytes).decode("ascii")
+
+
+def fetch_node(file_key, node_id, token, ca_file):
+    ids = urllib.parse.quote(node_id, safe="")
+    reply = http_json(f"{API}/files/{file_key}/nodes?ids={ids}", token, ca_file)
+    entry = (reply.get("nodes") or {}).get(node_id) or {}
+    return entry.get("document")
+
+
+def render_image(file_key, node_id, scale, token, ca_file):
+    ids = urllib.parse.quote(node_id, safe="")
+    reply = http_json(f"{API}/images/{file_key}?ids={ids}&format=png&scale={scale}", token, ca_file)
+    link = (reply.get("images") or {}).get(node_id)
+    return as_data_uri(http_bytes(link, ca_file)) if link else None
+
+
+def walk(root):
+    stack = [root]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, dict):
+            yield node
+            stack.extend(reversed(node.get("children") or []))
+
+
+def annotation_copy(node):
+    for note in node.get("annotations") or []:
+        text = note.get("label") or note.get("labelMarkdown") if isinstance(note, dict) else note
+        parsed = split_lang(text)
+        if parsed["tr"] or parsed["en"]:
+            return parsed
     return None
 
 
+def image_source(value, base_dir):
+    if not value or str(value).startswith("data:"):
+        return value
+    path = os.path.join(base_dir, value) if not os.path.isabs(value) else value
+    if os.path.isfile(path):
+        with open(path, "rb") as stream:
+            return as_data_uri(stream.read())
+    sys.exit(f"the --spec image does not exist: {path}")
+
+
+def page_from_rest(file_key, node_id, scale, token, ca_file):
+    document = fetch_node(file_key, node_id, token, ca_file)
+    if not document:
+        sys.exit(f"Figma file {file_key} has no node {node_id}")
+    box = document.get("absoluteBoundingBox") or {}
+    fx, fy = box.get("x", 0), box.get("y", 0)
+    nodes = []
+    for node in walk(document):
+        bbox = node.get("absoluteBoundingBox")
+        if not bbox or node is document:
+            continue
+        copy = annotation_copy(node)
+        text = node.get("characters") if node.get("type") == "TEXT" else None
+        if not (text and text.strip()) and not copy:
+            continue
+        nodes.append({
+            "id": node.get("id"),
+            "characters": text,
+            "tr": copy["tr"] if copy else None,
+            "en": copy["en"] if copy else None,
+            "x": round(bbox["x"] - fx),
+            "y": round(bbox["y"] - fy),
+            "w": round(bbox["width"]),
+            "h": round(bbox["height"]),
+            "side": "left",
+        })
+    image = render_image(file_key, node_id, scale, token, ca_file)
+    if not image:
+        sys.exit(f"Figma returned no image for {node_id}")
+    return {
+        "nodeId": node_id,
+        "name": document.get("name"),
+        "image": image,
+        "frame": {"w": round(box.get("width", 0)), "h": round(box.get("height", 0))},
+        "nodes": nodes,
+    }
+
+
 def build_cards(page, rows):
-    by_node, by_val = build_index(rows)
-    # 1-based index of every row in the mapping → the SAME number build-artifact prints
-    # in the summary/detail tables (both enumerate rows in order). The overlay card badge
-    # uses it so a mark on the screen and its table row always carry the same number.
-    row_num = {id(r): i for i, r in enumerate(rows, 1)}
+    index = build_index(rows)
     cards = []
-    for n in page["nodes"]:
-        row = match_row(n, by_node, by_val)
-        key = row.get("newKey") if row else None
-        # CMS values: prefer the node's own annotation, else the matched row's cms.*
-        tr = n.get("tr")
-        en = n.get("en")
-        if tr is None and en is None and row and isinstance(row.get("cms"), dict):
-            tr, en = row["cms"].get("tr"), row["cms"].get("en")
-        if not key and tr is None and en is None:
-            continue  # non-keyable
+    taken = set()
+    extra_number = len(rows)
+    for node in page.get("nodes") or []:
+        position = match_row(node, index)
+        if position is not None and position in taken:
+            continue
+        entry = rows[position] if position is not None else None
+        cms = (entry.get("cms") if entry else {}) or {}
+        tr = node.get("tr") or cms.get("tr")
+        en = node.get("en") or cms.get("en")
+        new_key = entry.get("newKey") if entry else None
+        if not (new_key or tr or en):
+            continue
+        if position is None:
+            extra_number += 1
+            number = extra_number
+        else:
+            taken.add(position)
+            number = position + 1
+        box = {axis: float(node.get(axis, 0)) for axis in ("x", "y", "w", "h")}
         cards.append({
-            "key": key or "(eşleşmedi)",
-            "tr": tr, "en": en,
-            "designText": n.get("characters") or "",
-            "x": n["x"], "y": n["y"], "w": n["w"], "h": n["h"],
-            "annotated": tr is not None or en is not None,
-            "side": (n.get("side") or "left").lower(),
-            "num": row_num.get(id(row)) if row else None,   # table row number (or None → sequential)
+            "num": number,
+            "key": new_key or LABEL_UNMATCHED,
+            "tr": tr,
+            "en": en,
+            "text": node.get("characters") or "",
+            "annotated": bool(tr or en),
+            "side": "right" if node.get("side") == "right" else "left",
+            **box,
         })
-    cards.sort(key=lambda c: c["y"])
     return cards
 
 
-# --- HTML composition ------------------------------------------------------
-def build_html(page, cards, title):
-    """Lay out cards on EITHER side of the frame (per-card `side`: left|right). Cards
-    that don't read well on the left (e.g. right-column UI like the amenity grid's
-    right entries) are placed on the right so their connector stays short and doesn't
-    cross the whole frame. Each column is ordered by target y and greedily stacked;
-    each link gets its own lane and a numbered dot matching its card. Returns
-    (html, canvas_w, canvas_h)."""
-    frame_w = page["frame"]["w"] or 800
-    frame_h = page["frame"]["h"] or 600
-    left_card_right = COL_X + CARD_W
-    design_right = DESIGN_X + frame_w
-    right_col_x = design_right + CHANNEL
-
-    items = []
-    for c in cards:
-        tx = DESIGN_X + c["x"] + c["w"] / 2
-        ty = TOP + c["y"] + c["h"] / 2
-        items.append({"tx": tx, "ty": ty, "c": c, "side": c.get("side", "left")})
-
-    left = sorted([it for it in items if it["side"] != "right"], key=lambda it: it["ty"])
-    right = sorted([it for it in items if it["side"] == "right"], key=lambda it: it["ty"])
-    has_right = bool(right)
-
-    def place(col):
-        cursor = TOP
-        for it in col:
-            it["y"] = max(cursor, it["ty"] - CARD_H / 2, TOP)
-            cursor = it["y"] + CARD_H + CARD_GAP
-        return cursor
-    cur_l, cur_r = place(left), place(right)
-
-    canvas_w = (right_col_x + CARD_W + RIGHT_MARGIN) if has_right else (design_right + RIGHT_MARGIN)
-    canvas_h = max(TOP + frame_h + TOP, cur_l + TOP, cur_r + TOP)
-
-    # numbering: use the matched row's table number so the mark on the screen and its
-    # table row agree; fall back to sequential only for a card with no matched row.
-    seq = 1
-    for it in left + right:
-        n = it["c"].get("num")
-        if n is None:
-            n = seq
-        it["num"] = n
-        seq += 1
-
-    nL, nR = len(left), len(right)
-    lane_step_l = (CHANNEL - 30) / max(1, nL - 1) if nL > 1 else 0
-    lane_step_r = (CHANNEL - 30) / max(1, nR - 1) if nR > 1 else 0
-
-    connectors, card_html = [], []
-
-    def emit(it, idx, side):
-        c, tx, ty, y, num = it["c"], it["tx"], it["ty"], it["y"], it["num"]
-        card_mid = y + CARD_H / 2
-        colour = PINK if c["annotated"] else GRAY
-        if side == "right":
-            lane = design_right + 16 + idx * lane_step_r
-            path = f'M {right_col_x} {card_mid:.0f} H {lane:.0f} V {ty:.0f} H {tx:.0f}'
-            left_px = right_col_x
-        else:
-            lane = left_card_right + 16 + idx * lane_step_l
-            path = f'M {left_card_right} {card_mid:.0f} H {lane:.0f} V {ty:.0f} H {tx:.0f}'
-            left_px = COL_X
-        connectors.append(
-            f'<path d="{path}" '
-            f'stroke="{colour}" stroke-width="1.4" stroke-dasharray="5 4" fill="none" opacity="0.85"/>'
-            f'<circle cx="{tx:.0f}" cy="{ty:.0f}" r="9" fill="{colour}"/>'
-            f'<text x="{tx:.0f}" y="{ty + 3.5:.0f}" text-anchor="middle" font-size="11" '
-            f'font-weight="700" fill="#fff">{num}</text>')
-        badge = f'<span class="num" style="background:{colour}">{num}</span>'
-        if c["annotated"]:
-            pill = f'<span class="pill" style="background:{PINK}">İçerik (CMS)</span>'
-            rows = f'<div class="row"><span class="lang">TR:</span> {esc(c["tr"]) if c["tr"] else "-"}</div>'
-            if c["en"] is not None:
-                rows += f'<div class="row"><span class="lang">EN:</span> {esc(c["en"])}</div>'
-            klass = ""
-        else:
-            pill = f'<span class="pill" style="background:{GRAY}">Öneri bekleniyor</span>'
-            rows = f'<div class="row muted">metin: {esc(c["designText"]) or "-"}</div>'
-            klass = " keyonly"
-        card_html.append(
-            f'<div class="card{klass}" style="left:{left_px:.0f}px;top:{y:.0f}px">'
-            f'<div class="hd">{badge}{pill}</div>'
-            f'<div class="key">{esc(c["key"])}</div>{rows}</div>')
-
-    for i, it in enumerate(left):
-        emit(it, i, "left")
-    for i, it in enumerate(right):
-        emit(it, i, "right")
-
-    html = f"""<!doctype html><html><head><meta charset="utf-8"><style>
-  * {{ box-sizing:border-box; }}
-  body {{ margin:0; background:#1e1e1e; font-family:-apple-system,'Segoe UI',Roboto,Arial,sans-serif; }}
-  .canvas {{ position:relative; width:{canvas_w}px; height:{canvas_h:.0f}px; }}
-  .design {{ position:absolute; left:{DESIGN_X}px; top:{TOP}px; width:{frame_w}px; height:{frame_h}px;
-            box-shadow:0 0 0 1px #333; }}
-  svg.links {{ position:absolute; left:0; top:0; width:{canvas_w}px; height:{canvas_h:.0f}px; pointer-events:none; }}
-  .card {{ position:absolute; width:{CARD_W}px; min-height:{CARD_H}px; background:#2b2b2b; color:#e8e8e8;
-          border-radius:10px; padding:10px 14px; box-shadow:0 1px 4px rgba(0,0,0,.4); }}
-  .card.keyonly {{ background:#f4f5f6; color:#202124; }}
-  .hd {{ display:flex; align-items:center; gap:7px; margin-bottom:6px; }}
-  .num {{ display:inline-flex; align-items:center; justify-content:center; width:18px; height:18px;
-         border-radius:50%; color:#fff; font-size:11px; font-weight:700; flex:none; }}
-  .pill {{ display:inline-block; color:#fff; font-size:11px; font-weight:600; padding:2px 8px;
-          border-radius:10px; }}
-  .key {{ font-family:'SF Mono',Menlo,Consolas,monospace; font-size:12px; color:#9ad; margin-bottom:6px;
-         word-break:break-all; }}
-  .card.keyonly .key {{ color:#1666c8; }}
-  .row {{ font-size:13px; line-height:1.35; }}
-  .row.muted {{ color:#5f6368; }}
-  .lang {{ color:{PINK}; font-weight:600; }}
-  .title {{ position:absolute; left:{COL_X}px; top:18px; color:#bbb; font-size:13px; }}
-</style></head><body><div class="canvas">
-  <div class="title">{esc(title)}</div>
-  <img class="design" src="{page['image']}">
-  <svg class="links">{''.join(connectors)}</svg>
-  {''.join(card_html)}
-</div></body></html>"""
-    return html, canvas_w, canvas_h
-
-
-# --- rasterize -------------------------------------------------------------
-def find_chrome():
-    for p in (
-        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-        "/Applications/Chromium.app/Contents/MacOS/Chromium",
-        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-    ):
-        if os.path.isfile(p) and os.access(p, os.X_OK):
-            return p
-    from shutil import which
-    for c in ("google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "chrome"):
-        w = which(c)
-        if w:
-            return w
-    return None
+def centre_y(card):
+    return card["y"] + card["h"] / 2
 
 
-def render_png(html, out_path, canvas_w, canvas_h, scale):
-    chrome = find_chrome()
-    if not chrome:
-        alt = out_path[:-4] + ".html" if out_path.endswith(".png") else out_path + ".html"
-        with open(alt, "w", encoding="utf-8") as fh:
-            fh.write(html)
-        sys.stderr.write(f"# no headless Chrome found  -  wrote {alt} (open/print to PDF)\n")
-        return alt
-    with tempfile.NamedTemporaryFile("w", suffix=".html", delete=False, encoding="utf-8") as tf:
-        tf.write(html)
-        tmp = tf.name
-    try:
-        r = subprocess.run(
-            [chrome, "--headless", "--disable-gpu", "--hide-scrollbars",
-             f"--force-device-scale-factor={scale}",
-             f"--window-size={canvas_w},{int(canvas_h)}",
-             f"--screenshot={out_path}", tmp],
-            capture_output=True, text=True, timeout=120)
-        if not os.path.isfile(out_path):
-            sys.exit(f"Chrome screenshot failed: {r.stderr[:300]}")
-    finally:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
-    return out_path
+def stack_side(cards):
+    cards.sort(key=centre_y)
+    bottom = TOP - GAP
+    for card in cards:
+        target = TOP + card["y"] + card["h"] / 2 - CARD_H / 2
+        card["cardY"] = max(target, bottom + GAP, TOP)
+        bottom = card["cardY"] + CARD_H
+    return bottom
+
+
+def chip(kind, colour, content):
+    return f'<span class="{kind}" style="background:{colour}">{content}</span>'
+
+
+def card_html(card, left):
+    colour = PINK if card["annotated"] else GRAY
+    pill = LABEL_CMS if card["annotated"] else LABEL_PENDING
+    if card["annotated"]:
+        body = "".join(
+            f'<div class="line"><b>{label}</b> {html.escape(card[lang] or "-")}</div>'
+            for label, lang in (("TR", "tr"), ("EN", "en"))
+        )
+    else:
+        body = f'<div class="line muted">{html.escape(card["text"] or "-")}</div>'
+    head = chip("num", colour, card["num"]) + chip("pill", colour, html.escape(pill))
+    return (
+        f'<div class="card" style="left:{left}px;top:{card["cardY"]:.0f}px;border-color:{colour}">'
+        f'<div class="head">{head}</div>'
+        f'<div class="key">{html.escape(card["key"])}</div>{body}</div>'
+    )
+
+
+def connector(card, lane, lane_count, start_x, target_x, from_left):
+    colour = PINK if card["annotated"] else GRAY
+    step = (CHANNEL - 40) / max(lane_count, 1)
+    bend = start_x + 20 + step * lane if from_left else start_x - 20 - step * lane
+    card_mid = card["cardY"] + CARD_H / 2
+    dot_y = TOP + centre_y(card)
+    x, y = f"{target_x:.0f}", f"{dot_y:.0f}"
+    label_y = f"{dot_y + 4:.0f}"
+    route = f"{start_x:.0f},{card_mid:.0f} {bend:.0f},{card_mid:.0f} {bend:.0f},{y} {x},{y}"
+    return (
+        f'<polyline points="{route}" fill="none" stroke="{colour}" stroke-width="2" stroke-dasharray="6 4"/>'
+        f'<circle cx="{x}" cy="{y}" r="11" fill="{colour}"/>'
+        f'<text x="{x}" y="{label_y}" text-anchor="middle" font-size="12" font-weight="700" fill="#fff">{card["num"]}</text>'
+    )
+
+
+def build_html(page, cards):
+    fw, fh = page["frame"]["w"], page["frame"]["h"]
+    sides = {"left": [], "right": []}
+    for card in cards:
+        sides[card["side"]].append(card)
+    screen_x = COLUMN_X + CARD_W + CHANNEL
+    right_x = screen_x + fw + CHANNEL
+    width = right_x + CARD_W + RIGHT_MARGIN if sides["right"] else screen_x + fw + RIGHT_MARGIN
+    height = int(max(TOP + fh, stack_side(sides["left"]), stack_side(sides["right"])) + TOP)
+
+    boxes, wires = [], []
+    for card_x, group in ((COLUMN_X, sides["left"]), (right_x, sides["right"])):
+        from_left = card_x == COLUMN_X
+        for lane, card in enumerate(group):
+            boxes.append(card_html(card, card_x))
+            if from_left:
+                wire = connector(card, lane, len(group), COLUMN_X + CARD_W, screen_x + card["x"], True)
+            else:
+                wire = connector(card, lane, len(group), right_x, screen_x + card["x"] + card["w"], False)
+            wires.append(wire)
+
+    mid = "center"
+    pin = "left:0;top:0;"
+    style = (
+        f"html,body{{margin:0;padding:0;background:{BACKGROUND};}}"
+        f"body{{width:{width}px;height:{height}px;position:relative;font-family:-apple-system,Helvetica,Arial,sans-serif;}}"
+        f".shot{{position:absolute;left:{screen_x}px;top:{TOP}px;width:{fw}px;height:{fh}px;}}"
+        f".card{{position:absolute;box-sizing:border-box;width:{CARD_W}px;height:{CARD_H}px;background:#fff;"
+        "border:2px solid;border-radius:10px;padding:8px 10px;overflow:hidden;color:#1f1f1f;}}"
+        ".head{display:flex;gap:6px;align-items:center;margin-bottom:4px;}"
+        ".num{color:#fff;border-radius:10px;min-width:20px;height:20px;font-size:12px;font-weight:700;"
+        f"display:inline-flex;align-items:{mid};justify-content:{mid};padding:0 4px;}}"
+        ".pill{color:#fff;border-radius:9px;font-size:11px;padding:2px 8px;}"
+        ".key{font-family:Menlo,monospace;font-size:11px;color:#444;margin-bottom:4px;white-space:nowrap;"
+        "overflow:hidden;text-overflow:ellipsis;}"
+        ".line{font-size:12px;line-height:16px;max-height:32px;overflow:hidden;}"
+        ".muted{color:#666;font-style:italic;}"
+        f"svg{{position:absolute;{pin}}}"
+    )
+    document = (
+        f"{PAGE_OPEN}{META_UTF8}<style>{style}</style></head><body>"
+        f'<img class="shot" src="{page["image"]}">'
+        f'<svg width="{width}" height="{height}">{"".join(wires)}</svg>'
+        f'{"".join(boxes)}</body></html>'
+    )
+    return document, width, height
+
+
+def find_chrome():
+    for path in [os.environ.get("CHROME_BIN")] + MAC_CHROMES:
+        if path and os.path.isfile(path) and os.access(path, os.X_OK):
+            return path
+    return next(filter(None, map(shutil.which, PATH_CHROMES)), None)
+
+
+def wait_until_stable(proc, path, limit, pause):
+    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(pause)
+    if proc.poll() is None:
+        proc.kill()
+        proc.wait()
+
+
+def chrome_screenshot(chrome, html_text, out_png, width, height, scale):
+    target = os.path.abspath(out_png)
+    with tempfile.TemporaryDirectory() as scratch:
+        page = os.path.join(scratch, "page.html")
+        with open(page, "w", encoding="utf-8") as sink:
+            sink.write(html_text)
+        if os.path.exists(target):
+            os.remove(target)
+        log_path = os.path.join(scratch, "chrome.log")
+        window = f"{int(width)},{int(height)}"
+        argv = [
+            chrome, "--hide-scrollbars", "--headless", "--disable-gpu",
+            f"--window-size={window}", f"--force-device-scale-factor={scale}",
+            f"--screenshot={target}", f"--user-data-dir={os.path.join(scratch, 'profile')}",
+            "file://" + page,
+        ]
+        with open(log_path, "w") as log:
+            proc = subprocess.Popen(argv, stdout=log, stderr=subprocess.STDOUT)
+            wait_until_stable(proc, target, 120, 0.5)
+        if os.path.isfile(target) and os.path.getsize(target) > 0:
+            return
+        with open(log_path, errors="replace") as log:
+            raise RuntimeError((log.read() or "no output").strip()[-300:])
+
+
+def load_spec_pages(path):
+    with open(path, encoding="utf-8") as stream:
+        spec = json.load(stream)
+    folder = os.path.dirname(os.path.abspath(path))
+    pages = spec.get("pages") or []
+    for page in pages:
+        page["image"] = image_source(page.get("image"), folder)
+    return spec, pages
+
+
+def split_nodes(flag, mapping):
+    given = [piece for piece in (flag or "").split(",") if piece.strip()]
+    return given or list(mapping.get("figmaNodes") or [])
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__,
-                                 formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--mapping", required=True, help="mapping JSON (rows + figmaFileKey/figmaNodes + screen)")
-    ap.add_argument("--spec", help="MCP spec JSON (no network)")
-    ap.add_argument("--file", help="Figma fileKey (REST; else from --mapping figmaFileKey)")
-    ap.add_argument("--nodes", help="node-ids (REST; else from --mapping figmaNodes)")
-    ap.add_argument("--scale", type=int, default=2)
-    ap.add_argument("--token")
-    ap.add_argument("--ca-file")
-    ap.add_argument("--out", default=".", help="output dir")
-    ap.add_argument("--slug", help="override slug (default from screen name)")
-    args = ap.parse_args()
-
-    with open(args.mapping, encoding="utf-8") as fh:
-        m = json.load(fh)
-    rows = m.get("rows") or []
-    screen = m.get("screen") or "screen"
-    sl = args.slug or slug(screen)
-    os.makedirs(args.out, exist_ok=True)
-
-    file_key = args.file or m.get("figmaFileKey")
-    node_ids = [n.strip() for n in (args.nodes or "").split(",") if n.strip()] or \
-        [str(n) for n in (m.get("figmaNodes") or [])]
-
-    # one overlay for the screen: use the FIRST node as the framing node (the screen frame)
-    if args.spec:
-        with open(args.spec, encoding="utf-8") as fh:
-            spec = json.load(fh)
-        pages = spec.get("pages") or []
+    cli = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    cli.add_argument("--mapping", required=True, help="the reuse-map JSON")
+    cli.add_argument("--spec", help="geometry from MCP or measured by hand: {fileKey, pages:[{nodeId, image, frame, nodes}]}")
+    cli.add_argument("--file", help="Figma file key; falls back to figmaFileKey in the mapping")
+    cli.add_argument("--nodes", help="node-ids separated by commas, the screen frame first; falls back to figmaNodes")
+    cli.add_argument("--scale", default=2, type=int)
+    cli.add_argument("--token", help="Figma token; FIGMA_ACCESS_TOKEN or the keychain is safer since other processes can read argv")
+    cli.add_argument("--ca-file", help="PEM roots to trust when a proxy intercepts TLS")
+    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")
+    opts = cli.parse_args()
+
+    with open(opts.mapping, encoding="utf-8") as stream:
+        mapping = json.load(stream)
+    stem = opts.slug or slug(mapping.get("screen"))
+
+    if opts.spec:
+        spec, pages = load_spec_pages(opts.spec)
         if not pages:
-            sys.exit("--spec has no pages")
+            sys.exit("--spec lists no pages")
         page = pages[0]
-        file_key = file_key or spec.get("fileKey")
+        file_key = spec.get("fileKey") or mapping.get("figmaFileKey")
     else:
-        if not (file_key and node_ids):
-            ap.error("REST needs a fileKey + node-ids (via --file/--nodes or the mapping). "
-                     "Or pass --spec for the MCP path.")
-        token = figma_token(args)
+        file_key = opts.file or mapping.get("figmaFileKey")
+        nodes = split_nodes(opts.nodes, mapping)
+        if not (file_key and nodes):
+            cli.error("need a Figma file key and frame node-id (flags or mapping), or --spec")
+        token = figma_token(opts.token)
         if not token:
-            sys.exit("No Figma token  -  pass --token, set FIGMA_ACCESS_TOKEN, or add the "
-                     "keychain item FIGMA_ACCESS_TOKEN (or use --spec).")
-        page = collect_rest_nodes(file_key, canon_id(node_ids[0]), token, args.ca_file, args.scale)
-        page["name"] = screen
+            sys.exit("No Figma token found (FIGMA_ACCESS_TOKEN, FIGMA_TOKEN, keychain FIGMA_ACCESS_TOKEN or --token). "
+                     "Without one, measure the boxes on the screenshot and hand them over with --spec.")
+        page = page_from_rest(file_key, canon_id(nodes[0]), opts.scale, token, opts.ca_file)
 
-    cards = build_cards(page, rows)
-    if not cards:
-        sys.stderr.write("# warning: no keyable cards built (no node matched a row / no annotations)\n")
-    html, canvas_w, canvas_h = build_html(page, cards, screen)
-    out_png = os.path.join(args.out, sl + OUT_SUFFIX)
-    written = render_png(html, out_png, canvas_w, canvas_h, args.scale)
+    cards = build_cards(page, mapping.get("rows") or [])
+    document, width, height = build_html(page, cards)
+    os.makedirs(opts.target_dir, exist_ok=True)
+
+    def output(suffix):
+        return os.path.join(opts.target_dir, f"{stem}.overlay.{suffix}")
 
+    chrome = find_chrome()
+    if chrome:
+        written = output("png")
+        try:
+            chrome_screenshot(chrome, document, written, width, height, opts.scale)
+        except (RuntimeError, subprocess.SubprocessError) as exc:
+            sys.exit(f"Chrome could not take the screenshot: {exc}")
+    else:
+        written = output("html")
+        with open(written, "w", encoding="utf-8") as sink:
+            sink.write(document)
+        print(f"# Chrome, Chromium and Edge are all missing; saved {written} in place of a PNG", file=sys.stderr)
+
+    with_copy = len([card for card in cards if card["annotated"]])
     manifest = {
-        "screen": screen,
+        "screen": mapping.get("screen"),
         "file": os.path.basename(written),
         "fileKey": file_key,
-        "nodeId": canon_id(node_ids[0]) if node_ids else page.get("nodeId"),
+        "nodeId": page.get("nodeId"),
         "cardCount": len(cards),
-        "annotatedCount": sum(1 for c in cards if c["annotated"]),
-        "width": canvas_w, "height": int(canvas_h), "scale": args.scale,
+        "annotatedCount": with_copy,
+        "width": width,
+        "height": height,
+        "scale": opts.scale,
     }
-    mpath = os.path.join(args.out, sl + ".overlay.manifest.json")
-    with open(mpath, "w", encoding="utf-8") as fh:
-        json.dump(manifest, fh, ensure_ascii=False, indent=2)
-        fh.write("\n")
-    sys.stderr.write(f"# overlay: {len(cards)} card(s), {manifest['annotatedCount']} annotated → "
-                     f"{written}\n")
+    with open(output("manifest.json"), "w", encoding="utf-8") as sink:
+        json.dump(manifest, sink, indent=2, ensure_ascii=False)
+        sink.write("\n")
+
+    if not cards:
+        print("# warning: the overlay is empty; no node matched a row and no node had an annotation", file=sys.stderr)
+    print(f"# overlay: {len(cards)} card(s), {with_copy} with CMS copy -> {written}", file=sys.stderr)
 
 
 if __name__ == "__main__":