@quybt93/pcgf 0.0.1

package/plugins/phaser-casual-game-factory/skills/game-art/client/imglib.py

@@ -0,0 +1,2138 @@
+"""Hàm xử lý ảnh thuần cho skill restyle-asset.
+
+Không CLI, không mạng, không biết layout thư mục — chỉ nhận/trả PIL Image.
+Nhờ vậy test được offline. Mọi phép toán pixel dùng numpy (Pillow 12 đã bỏ ImageMath.eval).
+"""
+from __future__ import annotations
+
+import base64
+import html as _html
+import io
+import json as _json
+import math
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter
+
+# Màu key ứng viên, theo thứ tự ưu tiên. Xanh lá đứng đầu vì đó là mặc định mong muốn.
+KEY_CANDIDATES = ["#00FF00", "#FF00FF", "#00FFFF", "#0000FF"]
+
+# chroma_key() mặc định t_high=170: alpha CHỈ đạt 255 (đục hoàn toàn) khi khoảng cách tới
+# key >= 170. Một margin "an toàn" mà thấp hơn t_high là VÔ NGHĨA — pixel chủ thể ở đúng
+# khoảng cách margin đó sẽ không đạt alpha đục, tức là chủ thể bị bào mờ (Finding I1: đo
+# thực tế asset màu (0,230,70), margin=131 tới #00FF00, ra alpha~169 — ma). Margin phải
+# LỚN HƠN t_high mới thật sự an toàn; 190 = t_high(170) + buffer ~20 unit dự phòng
+# rounding/variance giữa các lần đo màu.
+MIN_KEY_MARGIN = 190.0
+
+# "An toàn" nghĩa là margin của asset gốc tới #00FF00 phải vượt MIN_KEY_MARGIN. Dùng
+# CHUNG một hằng số ở đây và ở cảnh báo `key_safe` trong CLI `plan` để hai nơi luôn khớp
+# nhau — tách rời chúng là đúng lỗi I1 (một ngưỡng "an toàn" thấp hơn t_high thực tế).
+# Thực tế khoảng cách giữa #00FF00 và #00C800 (xanh lá đậm) là 110.0 trên thang redmean,
+# tức là dưới MIN_KEY_MARGIN, nên xanh lá đậm vẫn ĐẨY được ta sang màu key khác — đúng ý.
+GREEN_SAFE_THRESHOLD = MIN_KEY_MARGIN
+
+ALPHA_FLOOR = 8      # alpha > ngưỡng này mới tính là nội dung (khi tìm bbox)
+PALETTE_ALPHA_FLOOR = 16  # alpha > ngưỡng này khi lấy mẫu bảng màu (muốn pixel mờ bị bỏ qua vì màu blended)
+BAD_HIGH = 0.95      # alpha phủ hơn mức này -> nền không tách được
+BAD_LOW = 0.02       # alpha phủ dưới mức này -> chủ thể NHỎ (không nhất thiết hỏng, xem
+                     # bad_subject trong postprocess() — coverage thấp một mình không còn
+                     # đủ để kết luận "hỏng" kể từ Finding I3)
+
+
+def hex_to_rgb(h: str) -> tuple[int, int, int]:
+    h = h.lstrip("#")
+    return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+
+
+def rgb_to_hex(c) -> str:
+    r, g, b = (int(round(v)) for v in tuple(c)[:3])
+    return f"#{r:02X}{g:02X}{b:02X}"
+
+
+def color_dist(c1, c2) -> float:
+    """Khoảng cách màu 'redmean' — xấp xỉ cảm nhận mắt người, rẻ hơn CIELAB nhiều.
+
+    Thang 0..~765. Dùng chung một công thức cho cả pick_key_color và chroma_key
+    để ngưỡng ở hai nơi so sánh được với nhau.
+    """
+    r1, g1, b1 = (float(v) for v in c1[:3])
+    r2, g2, b2 = (float(v) for v in c2[:3])
+    rm = (r1 + r2) / 2.0
+    dr, dg, db = r1 - r2, g1 - g2, b1 - b2
+    return math.sqrt(
+        (2 + rm / 256.0) * dr * dr + 4 * dg * dg + (2 + (255 - rm) / 256.0) * db * db
+    )
+
+
+def extract_palette(img: Image.Image, n: int = 8) -> list[tuple[str, float]]:
+    """Bảng màu chủ đạo, bỏ qua pixel trong suốt. Trả [(hex, tỉ lệ)] giảm dần."""
+    arr = np.asarray(img.convert("RGBA"))
+    opaque = arr[arr[..., 3] > PALETTE_ALPHA_FLOOR][:, :3]
+    if opaque.size == 0:
+        return []
+
+    strip = Image.fromarray(opaque.reshape(1, -1, 3).astype(np.uint8), "RGB")
+    q = strip.quantize(colors=max(1, n), method=Image.Quantize.MEDIANCUT)
+    pal = q.getpalette() or []
+    counts = q.getcolors(maxcolors=256) or []
+    total = float(sum(c for c, _ in counts)) or 1.0
+
+    out: list[tuple[str, float]] = []
+    for count, idx in sorted(counts, key=lambda t: t[0], reverse=True):
+        rgb = pal[idx * 3 : idx * 3 + 3]
+        if len(rgb) == 3:
+            out.append((rgb_to_hex(rgb), count / total))
+    return out
+
+
+def pick_key_color(
+    img: Image.Image, avoid: list[tuple[int, int, int]] | None = None
+) -> tuple[str, float]:
+    """Chọn màu key xa mọi màu trong asset nhất, ưu tiên xanh lá.
+
+    Trả (hex, margin) — margin là khoảng cách tới màu GẦN NHẤT trong asset (hoặc trong
+    `avoid`, xem dưới). Margin thấp = rủi ro ăn thủng chủ thể. KHÔNG BAO GIỜ raise — kể cả
+    khi mọi ứng viên đều tệ (margin thấp/0), hàm này vẫn trả ứng viên tốt nhất tìm được;
+    nơi gọi (CLI `plan`) chịu trách nhiệm surface rủi ro đó qua field `key_safe`, không
+    phải hàm này từ chối chạy.
+
+    `avoid`: các màu RGB THÊM VÀO việc chấm điểm, không lấy từ palette của `img`. Cần vì
+    chroma_key() chạy trên ẢNH ĐÃ RESTYLE — một phong cách MỚI, bảng màu MỚI, khác hẳn
+    palette của asset gốc mà hàm này đọc được. Nếu phong cách mới có màu nổi bật (vd neon
+    xanh lá trên một asset gốc toàn màu đỏ), chấm điểm chỉ dựa trên palette nguồn sẽ báo
+    xanh lá "an toàn" (đúng với nguồn) rồi Gemini vẽ ra đúng highlight đó và bị chroma-key
+    ăn mất. Truyền bảng màu của style preset vào `avoid` (CLI: `plan --avoid`) để gộp
+    nguy cơ đó vào điểm số TRƯỚC khi sinh ảnh.
+    """
+    colors = [hex_to_rgb(h) for h, _ in extract_palette(img, n=16)]
+    colors += list(avoid or [])
+    if not colors:
+        return KEY_CANDIDATES[0], float("inf")
+
+    scored = [
+        (min(color_dist(c, hex_to_rgb(k)) for c in colors), k) for k in KEY_CANDIDATES
+    ]
+    green_margin = next(m for m, k in scored if k == "#00FF00")
+    if green_margin > GREEN_SAFE_THRESHOLD:
+        return "#00FF00", green_margin
+
+    # Green không an toàn; chọn ứng viên tốt nhất TRỪ green
+    margin, key = max((m, k) for m, k in scored if k != "#00FF00")
+    return key, margin
+
+
+def _dist_map(arr_rgb: np.ndarray, key: tuple[int, int, int]) -> np.ndarray:
+    """color_dist() bản vector hoá, cho cả ảnh cùng lúc."""
+    r = arr_rgb[..., 0].astype(np.float64)
+    g = arr_rgb[..., 1].astype(np.float64)
+    b = arr_rgb[..., 2].astype(np.float64)
+    kr, kg, kb = (float(v) for v in key)
+    rm = (r + kr) / 2.0
+    dr, dg, db = r - kr, g - kg, b - kb
+    return np.sqrt(
+        (2 + rm / 256.0) * dr * dr + 4 * dg * dg + (2 + (255 - rm) / 256.0) * db * db
+    )
+
+
+def chroma_key(
+    img: Image.Image, key_hex: str, t_low: float = 70.0, t_high: float = 170.0
+) -> Image.Image:
+    """Tách nền bằng ngưỡng MỀM.
+
+    Pixel cách màu key < t_low  -> trong suốt hoàn toàn.
+    Pixel cách màu key > t_high -> đục hoàn toàn.
+    Ở giữa -> smoothstep. Ngưỡng mềm là thứ giữ cho mép không bị răng cưa;
+    ngưỡng cứng sẽ làm hỏng anti-alias mà Gemini vẽ ra.
+    """
+    key = hex_to_rgb(key_hex)
+    rgb = np.asarray(img.convert("RGB"), dtype=np.uint8)
+    d = _dist_map(rgb, key)
+
+    t = np.clip((d - t_low) / max(1e-6, t_high - t_low), 0.0, 1.0)
+    alpha = t * t * (3.0 - 2.0 * t)  # smoothstep
+
+    out = np.dstack([rgb.astype(np.float64), alpha * 255.0])
+    return Image.fromarray(np.rint(out).clip(0, 255).astype(np.uint8), "RGBA")
+
+
+def despill(img: Image.Image, key_hex: str, strength: float = 1.0) -> Image.Image:
+    """Khử ám màu key còn sót Ở MÉP (green fringe) — KHÔNG đụng vào chủ thể đục.
+
+    Kênh nào 'sáng' trong màu key thì bị kẹp xuống mức trung bình của các kênh còn lại.
+    Với #00FF00 -> kẹp G xuống (R+B)/2. Với #FF00FF -> kẹp R và B xuống G.
+
+    Mức kẹp được NHÂN theo `weight = (1 - alpha/255) * strength`, alpha là alpha của
+    CHÍNH pixel đó SAU chroma_key: pixel đục hoàn toàn (alpha=255, chủ thể thật) có
+    weight=0 -> KHÔNG bị đụng vào một chút nào; pixel trong suốt hoàn toàn (alpha=0, nền)
+    có weight=1 -> bị kẹp full; pixel mép bán trong suốt được kẹp tỉ lệ theo alpha.
+
+    VÌ SAO CẦN WEIGHT NÀY (Finding C1 — trước đây là bug CRITICAL): nền trong pipeline
+    này là một mảng phẳng số hoá mà Gemini vẽ ra (được yêu cầu vẽ nền màu key thuần),
+    không phải phông xanh vật lý bị ánh sáng dội lên diễn viên — nên KHÔNG hề có "ánh
+    sáng key dội vào chủ thể" ở pixel đục. Spill thật sự chỉ tồn tại ở dải anti-alias nơi
+    Gemini blend RGB của chủ thể với RGB của nền. Bản cũ áp công thức kẹp lên MỌI pixel
+    bất kể alpha — tức là một phép crush kênh TOÀN CỤC, không phải sửa mép — và ăn cả
+    màu vàng/nâu/đỏ hợp lệ của chủ thể: đo được trên bản cũ, vàng #FFD700 trên key xanh
+    lá ra (255,128,0) cam; đỏ (200,30,40) trên key hồng ra gần đen. Xem
+    test_despill_never_touches_opaque_subject_pixels (test hồi quy cho đúng bug này) và
+    test_despill_still_removes_edge_fringe (chứng minh mép bán trong suốt vẫn được sửa).
+    """
+    key = hex_to_rgb(key_hex)
+    spill = [i for i in range(3) if key[i] >= 200]
+    base = [i for i in range(3) if key[i] < 200]
+    if not spill or not base:
+        return img.convert("RGBA")
+
+    arr = np.asarray(img.convert("RGBA"), dtype=np.float64)
+    weight = (1.0 - arr[..., 3] / 255.0) * strength
+    limit = arr[..., base].mean(axis=-1)
+    for i in spill:
+        ch = arr[..., i]
+        arr[..., i] = np.where(ch > limit, ch + (limit - ch) * weight, ch)
+    return Image.fromarray(np.rint(arr).clip(0, 255).astype(np.uint8), "RGBA")
+
+
+def alpha_coverage(img: Image.Image) -> float:
+    """Tỉ lệ pixel được coi là nội dung. Dùng để phát hiện bản sinh hỏng."""
+    a = np.asarray(img.convert("RGBA"))[..., 3]
+    return float((a > ALPHA_FLOOR).sum()) / float(a.size)
+
+
+# Alpha từ mức này trở lên mới coi là "đục thật" (không phải pixel mép anti-alias).
+SOLID_ALPHA = 200
+
+# Dưới tỉ lệ này thì chủ thể coi như bị bào thành bóng ma trong suốt.
+# Đặt thấp (0.25) là cố ý: line-art mảnh (râu mèo) có rất nhiều pixel mép hợp lệ,
+# không được báo nhầm chúng là hỏng.
+BAD_SOLID_RATIO = 0.25
+
+
+def solid_ratio(img: Image.Image) -> float:
+    """Tỉ lệ pixel ĐỤC THẬT trên tổng pixel CÓ NỘI DUNG.
+
+    alpha_coverage() chỉ trả lời "có pixel không", hàm này trả lời "pixel có đặc không".
+    Cần cả hai: màu key sát màu chủ thể sẽ bào chủ thể xuống alpha ~40 — vẫn đếm là
+    'có nội dung' nên coverage trông bình thường, nhưng asset thực tế là một bóng ma.
+    """
+    a = np.asarray(img.convert("RGBA"))[..., 3]
+    content = int((a > ALPHA_FLOOR).sum())
+    if content == 0:
+        return 0.0
+    return float((a >= SOLID_ALPHA).sum()) / float(content)
+
+
+def content_bbox(img: Image.Image, floor: int = ALPHA_FLOOR) -> tuple[int, int, int, int] | None:
+    """Bbox của phần nhìn thấy được. Trả None nếu ảnh rỗng hoàn toàn.
+
+    Không dùng Image.getbbox() vì nó lấy alpha > 0, tức là dính cả nhiễu alpha=1
+    mà chroma key mềm để lại quanh mép.
+    """
+    a = np.asarray(img.convert("RGBA"))[..., 3]
+    ys, xs = np.nonzero(a > floor)
+    if xs.size == 0:
+        return None
+    return (int(xs.min()), int(ys.min()), int(xs.max()) + 1, int(ys.max()) + 1)
+
+
+# Trên tỉ lệ này thì coi vùng thủng bên trong bbox là đáng ngờ (Finding I2).
+BAD_HOLE_RATIO = 0.10
+
+
+def hole_ratio(img: Image.Image, bbox: tuple[int, int, int, int] | None = None) -> float:
+    """Tỉ lệ pixel BÊN TRONG content_bbox bị thủng hoàn toàn (alpha <= ALPHA_FLOOR).
+
+    Bịt lỗ hổng cấu trúc của coverage/solid_ratio/border_impurity: cả ba đều đo tín hiệu
+    TOÀN CỤC hoặc VÀNH NGOÀI, nên một màu sát-key nằm LỌT THỎM giữa chủ thể (vd một viên
+    ngọc xanh lá trên nền chủ thể đỏ-nâu) bị chroma_key khoét thành lỗ trong suốt giữa
+    asset — coverage/solid_ratio/border_impurity đều không nhìn vào GIỮA bbox nên không
+    thấy gì, report ra "ok", `flags: []`, và asset lọt lưới với một lỗ thủng giữa thân.
+
+    CẢNH BÁO — cờ `bad_holes` dùng hàm này CHỈ MANG TÍNH THAM KHẢO, không phải gate cứng:
+    art hollow HỢP LỆ rất phổ biến (nhẫn, chữ "O", khung ảnh, bánh donut) và có thể có
+    hole_ratio cao mà không hề hỏng. BAD_HOLE_RATIO được chọn để bắt một viên ngọc bị
+    khoét GIỮA chủ thể (test_hole_ratio_flags_interior_hole) trong khi vẫn bỏ qua một
+    hình khối rỗng vừa phải, hợp lệ (test_hole_ratio_tolerates_legit_hollow_shape).
+    Ngưỡng này KHÔNG THỂ phân biệt hoàn hảo mọi trường hợp — art hollow rất lớn (interior
+    chiếm phần lớn bbox) vẫn có thể bị flag nhầm. Vì vậy `bad_holes` không bao giờ được
+    dùng để tự động loại bỏ asset (không trả None, không ép `bad_subject`) — contact
+    sheet, nơi người duyệt nhìn bằng mắt, mới là cửa gác thật sự.
+    """
+    if bbox is None:
+        bbox = content_bbox(img)
+    if bbox is None:
+        return 0.0
+    x0, y0, x1, y1 = bbox
+    a = np.asarray(img.convert("RGBA"))[..., 3]
+    inner = a[y0:y1, x0:x1]
+    if inner.size == 0:
+        return 0.0
+    return float((inner <= ALPHA_FLOOR).sum()) / float(inner.size)
+
+
+# Vệt rác nhỏ hơn tỉ lệ này (so với mảng lớn nhất) thì bị xoá.
+# Ca thật bắt buộc phải có nó: Gemini ĐÓNG DẤU WATERMARK ✦ lên góc dưới-phải MỌI ảnh nó sinh ra.
+# Watermark đó là màu xanh hơi lệch key — đo được (81,249,77), cách #00FF00 đúng 176 trên thang
+# redmean, tức là NHỈNH HƠN t_high=170 — nên nó sống sót qua chroma key và thành một chấm xanh
+# ĐỤC HOÀN TOÀN nằm trong asset. Không despeckle thì mọi asset xuất ra đều dính chấm xanh.
+SPECKLE_RATIO = 0.01
+
+
+def _components(mask: np.ndarray) -> tuple[list, dict, dict]:
+    """Gán nhãn liên thông 4-hướng bằng run-length + union-find.
+
+    scipy.ndimage.label không có trong môi trường này. Nhưng duyệt theo RUN (đoạn pixel liền
+    nhau trên một hàng) thay vì theo từng pixel thì số phần tử tụt từ ~1 triệu xuống vài nghìn,
+    nên union-find thuần Python vẫn nhanh.
+    """
+    h, w = mask.shape
+    parent: dict[int, int] = {}
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(a: int, b: int) -> None:
+        ra, rb = find(a), find(b)
+        if ra != rb:
+            parent[rb] = ra
+
+    rows: list[list[tuple[int, int, int]]] = []
+    nxt = 0
+    for y in range(h):
+        edge = np.diff(np.concatenate(([0], mask[y].astype(np.int8), [0])))
+        runs = []
+        for s, e in zip(np.flatnonzero(edge == 1), np.flatnonzero(edge == -1)):
+            parent[nxt] = nxt
+            runs.append((int(s), int(e), nxt))
+            nxt += 1
+        if y > 0:
+            for s, e, lbl in runs:
+                for ps, pe, plbl in rows[-1]:
+                    if ps < e and s < pe:          # hai run chồng nhau theo cột -> cùng mảng
+                        union(plbl, lbl)
+        rows.append(runs)
+
+    areas: dict[int, int] = {}
+    for runs in rows:
+        for s, e, lbl in runs:
+            r = find(lbl)
+            areas[r] = areas.get(r, 0) + (e - s)
+    return rows, {"find": find}, areas
+
+
+def component_boxes(mask: np.ndarray, min_size: int = 24) -> list[tuple[int, int, int, int]]:
+    """Bounding box (x0, y0, x1, y1) của từng mảng liên thông True trong `mask`.
+
+    Dùng cho chế độ SCREEN SHEET: dải chi tiết là các chủ thể rời nhau trên nền key —
+    mỗi mảng liên thông = một asset. Bỏ mảng mà CẢ HAI chiều đều dưới `min_size`
+    (nhiễu/speck; asset mảnh dài như thanh progress 200×10 vẫn giữ vì một chiều đủ lớn).
+
+    Thứ tự trả về là THỨ TỰ ĐỌC: gom theo hàng (mảng nào có tâm-y nằm trong dải-y của
+    hàng hiện có thì vào hàng đó), hàng trên trước, trong hàng thì trái trước — để
+    cell1..cellN ổn định và khớp với cách người nhìn sheet."""
+    rows, uf, _areas = _components(mask)
+    find = uf["find"]
+    boxes: dict[int, list[int]] = {}
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            r = find(lbl)
+            b = boxes.get(r)
+            if b is None:
+                boxes[r] = [s, y, e, y + 1]
+            else:
+                if s < b[0]:
+                    b[0] = s
+                if e > b[2]:
+                    b[2] = e
+                b[3] = y + 1
+    keep = [tuple(b) for b in boxes.values()
+            if (b[2] - b[0]) >= min_size or (b[3] - b[1]) >= min_size]
+
+    keep.sort(key=lambda b: b[1])
+    bands: list[list[tuple[int, int, int, int]]] = []
+    for b in keep:
+        cy = (b[1] + b[3]) / 2
+        for band in bands:
+            if min(x[1] for x in band) <= cy <= max(x[3] for x in band):
+                band.append(b)
+                break
+        else:
+            bands.append([b])
+    ordered: list[tuple[int, int, int, int]] = []
+    for band in bands:
+        band.sort(key=lambda b: b[0])
+        ordered.extend(band)
+    return ordered
+
+
+def despeckle(img: Image.Image, ratio: float = SPECKLE_RATIO) -> tuple[Image.Image, int]:
+    """Xoá các mảng liên thông nhỏ hơn `ratio` lần mảng lớn nhất. Trả (ảnh, số mảng đã xoá).
+
+    Chủ yếu để diệt watermark của Gemini (xem SPECKLE_RATIO), tiện thể dọn luôn nhiễu lấm tấm
+    mà chroma key để sót.
+
+    RỦI RO đã biết: asset gồm nhiều mảnh rời hợp lệ mà có mảnh rất nhỏ (hạt lấp lánh quanh ngôi
+    sao, dấu chấm trên chữ "i") thì mảnh đó có thể bị xoá oan. Ngưỡng 1% là bảo thủ, và số mảng
+    bị xoá LUÔN được báo trong report (`speckles_removed`) để người duyệt thấy — nhưng contact
+    sheet vẫn là cửa gác cuối, không phải con số này.
+    """
+    arr = np.array(img.convert("RGBA"))
+    mask = arr[..., 3] > ALPHA_FLOOR
+    if not mask.any():
+        return img, 0
+
+    rows, uf, areas = _components(mask)
+    find = uf["find"]
+    biggest = max(areas.values())
+    doomed = {r for r, a in areas.items() if a < ratio * biggest}
+    if not doomed:
+        return img, 0
+
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            if find(lbl) in doomed:
+                arr[y, s:e, 3] = 0
+
+    return Image.fromarray(arr, "RGBA"), len(doomed)
+
+
+# ── Watermark ✦ của Gemini: hằng số ĐO ĐƯỢC, không phải đoán ────────────────────────────
+# Gemini web dán một ngôi sao 4 cánh TRẮNG vào ô 48x48 px, cách cạnh phải và cạnh dưới đúng
+# 96 px. Hiệu chuẩn bằng 3 ảnh "nền đen thuần" sinh riêng: hình học trùng khít từng pixel
+# (828 pixel sáng, đỉnh 78/255, lệch giữa 3 mẫu < 1.4/255), và ba kênh RGB lệch nhau ĐÚNG 0.0
+# -> overlay là TRẮNG THUẦN với alpha CỐ ĐỊNH. Đo lại trên canvas 1024x1024: vẫn 48x48 @ 96px,
+# tức hình học KHÔNG scale theo cạnh ảnh.
+#
+# Vì alpha cố định, đây là phép trộn tuyến tính ĐẢO ĐƯỢC:
+#     O = S*(1-α) + 255*α    =>    S = (O - 255*α) / (1-α)
+# nên lấy lại được ĐÚNG pixel gốc — không cần inpaint/blur đoán nội dung. Sai số duy nhất là
+# lượng tử hoá, bị khuếch đại 1/(1-α) ≈ 1.44 lần, tức tối đa ~±1.4 mức: mắt không thấy.
+# Tính chất phụ tiện lợi: nền TRẮNG thuần (255) thì watermark vô hình VÀ phép đảo là ánh xạ
+# đồng nhất, nên chạy trên ảnh nền trắng cũng vô hại.
+_WM_BOX = 48        # cạnh ô watermark (px)
+_WM_MARGIN = 96     # lề từ ô tới cạnh phải/dưới (px)
+
+# 48x48 PNG grayscale, mỗi pixel = round(α*255). Nhúng base64 để imglib TỰ CHỨA: một file
+# mask rời rất dễ bị bỏ quên khi copy skill sang máy khác, và thiếu nó thì watermark lặng lẽ
+# không được xoá.
+_WM_ALPHA_B64 = (
+    "iVBORw0KGgoAAAANSUhEUgAAADAAAAAwCAAAAAByaaZbAAABlUlEQVR42p2WwU/CMBTGv6KL0EQXswkjphcO48rReeU/94Ax"
+    "XDwKBzWOhBFpjB66mJHpgTlW1q6d79J07e+9167vawG1TaeagY76s0ep3woYAoNWwABgbQCPAo7fAmAAENoDlP2FsQRCqTED"
+    "tFgv8y2B6CiSZCeKhIZlqN2HRQQ6rrAX5gg0ciqj/VVuAqLzas+5jA3ApH8UkCaNwIQB5NAlgHtESIBzE9Q3zQ3eMw3gRq7q"
+    "33aDTaYERpOu+kQ7I8KrWe7NDz3oTdwLGaAhQ7PFS3EAmr2XyGoLgMAfMAd2JpLNlkz3ZUJ+LJlOsQjL+SAEXjDsWfrfvSWc"
+    "AIDHmMV0vuD/3lYAoLc9o3cJAMKxNvenl/rRaAiSzj/VpzVLrs5kF/t0ZkJXD9krrR/weJ43VFxSI+LH5ppOfFlRvx5MujRP"
+    "5fUadSnn1xUnd8Isld/5QWmWiY0YP5cFnC7s1LucNrOUe17IYyxsb6Cl1FgAgmsDaG7RBQCsWly7fAek2zYvgRhYt3o6rIGN"
+    "euRUU5Ip1BnhFzx/an1wRZA/AAAAAElFTkSuQmCC"
+)
+
+_WM_CACHE: dict[str, np.ndarray] = {}
+
+
+def _wm_alpha() -> np.ndarray:
+    """Mask alpha 48x48 (float 0..1) của ngôi sao. Cache vì gọi cho mọi ảnh tải về."""
+    a = _WM_CACHE.get("a")
+    if a is None:
+        raw = base64.b64decode(_WM_ALPHA_B64)
+        a = np.asarray(Image.open(io.BytesIO(raw)).convert("L")).astype(np.float64) / 255.0
+        _WM_CACHE["a"] = a
+    return a
+
+
+def _wm_seam_energy(gray: np.ndarray, edge_w: np.ndarray) -> float:
+    """Năng lượng gradient của `gray`, CHỈ tính trên đường viền ngôi sao (`edge_w`).
+
+    Dùng làm bằng chứng watermark có mặt hay không: viền ngôi sao là bước nhảy alpha
+    0 -> 0.3 trong ~1px, nên nếu watermark có thật thì gradient dồn đúng vào đó, và
+    sau khi đảo phép trộn nó phải TAN đi. Nếu ảnh KHÔNG có watermark, phép đảo tạo ra một
+    ngôi sao TỐI -> năng lượng viền TĂNG. Nhờ vậy một phép đo phân biệt được cả hai chiều.
+    """
+    gy, gx = np.gradient(gray)
+    return float((np.hypot(gx, gy) * edge_w).sum())
+
+
+def unwatermark_gemini(
+    img: Image.Image, verify: bool = False, search: int = 0, min_gain: float = 0.25
+) -> tuple[Image.Image, dict | None]:
+    """Xoá ngôi sao ✦ của Gemini bằng cách ĐẢO phép trộn alpha. Trả (ảnh, info|None).
+
+    Phải chạy TRƯỚC mọi thao tác khác (tách nền, cắt sheet, resize): watermark nằm trong
+    pixel màu, nên mọi bước sau đó đều bôi nó ra hoặc bake nó vào asset. Sau khi resize/cắt,
+    hình học 48x48@96px không còn đúng và không còn cách nào lấy lại pixel gốc.
+
+    verify=False (mặc định): đảo VÔ ĐIỀU KIỆN tại đúng ô đã hiệu chuẩn. Dùng cho ảnh CHẮC
+        CHẮN từ Gemini web — ở đó không cần dò, và dò thì chỉ thêm đường hỏng.
+    verify=True: chỉ đảo khi đo được bằng chứng watermark có thật. Dùng cho ảnh NGUỒN LẪN
+        (vd process_raws nhận cả ảnh Codex/GPT Image 2 không có watermark) — ở đó đảo bừa sẽ
+        ĐÓNG một ngôi sao TỐI vào ảnh sạch.
+
+    `search` = bán kính dò lệch vị trí, MẶC ĐỊNH 0 vì hình học đã hiệu chuẩn là chính xác.
+        Bật lên chỉ khi Google dịch watermark: dò trên nền có hoa văn tuần hoàn có thể khớp
+        nhầm chỗ và đảo sai (đo được: nền vạch sọc chu kỳ 7px, sai số phục hồi vọt lên 67 mức).
+
+    info: {"box": (x0,y0,w,h), "gain": float|None} nếu đã xoá, None nếu bỏ qua.
+    """
+    alpha = _wm_alpha()
+    box = _WM_BOX
+    rgb = img.convert("RGB") if img.mode not in ("RGB", "RGBA") else img
+    arr = np.asarray(rgb.convert("RGB")).astype(np.float64)
+    H, W = arr.shape[:2]
+    if W < box + _WM_MARGIN or H < box + _WM_MARGIN:
+        return img, None      # ảnh nhỏ hơn cả lề -> không phải khung Gemini gốc
+
+    x_nom = W - _WM_MARGIN - box
+    y_nom = H - _WM_MARGIN - box
+    a3 = alpha[..., None]
+    inv = 1.0 - a3
+
+    def restore(x0: int, y0: int) -> np.ndarray:
+        reg = arr[y0:y0 + box, x0:x0 + box]
+        return (reg - 255.0 * a3) / inv
+
+    if not verify:
+        best = (x_nom, y_nom, None)
+    else:
+        gy, gx = np.gradient(alpha)
+        edge_w = np.hypot(gx, gy)
+        solid = alpha > 0.29     # lòng ngôi sao: alpha hằng, ~744 px
+        clear = alpha <= 0.0     # bốn góc ô 48x48: hoàn toàn ngoài ngôi sao, ~1400 px
+        if edge_w.sum() <= 0 or not solid.any() or not clear.any():
+            return img, None
+        a_solid = float(alpha[solid].mean())
+
+        # Hai VÀNH sát viền ngôi sao — một vành ngay trong, một vành ngay ngoài. Cần chúng vì
+        # so trung bình lòng-sao với bốn góc ô BỎ SÓT khi nền có hoa văn cỡ gần bằng ô (đo
+        # được: checker 16px lọt, do nền ở lòng sao khác nền ở góc). Hai vành kề nhau nên
+        # nền CỤC BỘ khớp, hiệu giữa chúng gần như chỉ còn phần watermark cộng vào.
+        sm = Image.fromarray((solid * 255).astype(np.uint8), "L")
+        grown = np.asarray(sm.filter(ImageFilter.MaxFilter(7))) > 127
+        shrunk = np.asarray(sm.filter(ImageFilter.MinFilter(7))) > 127
+        rim_in = solid & ~shrunk
+        rim_out = grown & clear
+        use_rim = rim_in.any() and rim_out.any()
+        a_rim = float(alpha[rim_in].mean()) if use_rim else 0.0
+
+        best_score, best = -1e9, None
+        for dy in range(-search, search + 1):
+            for dx in range(-search, search + 1):
+                x0, y0 = x_nom + dx, y_nom + dy
+                if x0 < 0 or y0 < 0 or x0 + box > W or y0 + box > H:
+                    continue
+                reg = arr[y0:y0 + box, x0:x0 + box]
+                g = reg.mean(axis=2)
+
+                # RÀNG BUỘC CỨNG loại trước mọi phép đo mềm: nếu ô này thật sự có lớp trắng
+                # alpha α phủ lên ảnh gốc S ≥ 0 thì buộc O = S(1-α) + 255α ≥ 255α. Vậy chỉ cần
+                # thấy pixel trong lòng sao TỐI HƠN 255α là giả thiết SAI hẳn — không cần đoán
+                # thêm. Đây là thứ chặn ảnh sạch có chi tiết tối ở góc (đo được: nền checker
+                # 8px sạch từng bị xoá bừa trước khi có cổng này). Nới 6 mức cho nhiễu nén, và
+                # cho phép 1% pixel vi phạm.
+                floor = 255.0 * a_solid - 6.0
+                if float((g[solid] < floor).mean()) > 0.01:
+                    continue
+
+                before = _wm_seam_energy(g, edge_w)
+                after = _wm_seam_energy(restore(x0, y0).mean(axis=2), edge_w)
+                gain = (before - after) / before if before > 1e-9 else 0.0
+
+                # Phép đo thứ hai, MIỄN NHIỄM với texture tần số cao: lấy trung bình trên
+                # ~744 px lòng sao so với ~1400 px bốn góc ô. Lớp phủ trắng alpha hằng nâng
+                # lòng sao lên đúng α*(255 - nền); nhiễu/checker bị triệt vì lấy trung bình
+                # hàng trăm pixel. Cần phép này vì đo gradient viền một mình BỎ SÓT khi nền
+                # rối (đo được: nền noise và checker 16px đều lọt).
+                def step_conf(inside: np.ndarray, outside: np.ndarray, a_in: float) -> float:
+                    """Độ tin cậy từ bậc sáng: 1.0 khi bậc đo được khớp đúng α*(255-nền)."""
+                    bg = float(g[outside].mean())
+                    pred = a_in * (255.0 - bg)
+                    if pred <= 2.0:      # nền gần trắng -> watermark vô hình, phép này vô nghĩa
+                        return -1e9
+                    r = (float(g[inside].mean()) - bg) / pred
+                    return 1.0 - abs(r - 1.0) / 0.4 if 0.6 <= r <= 1.4 else -1e9
+
+                # Điểm = mức tin cậy CAO NHẤT trong ba phép đo độc lập, để mỗi phép bù điểm yếu
+                # của phép kia (gradient viền chịu nền rối; bậc sáng chịu nền có hoa văn to).
+                # Ràng buộc hai phía của tỉ lệ bậc sáng khiến ngôi sao THẬT với alpha khác
+                # (vd 0.6) KHÔNG bị nhận nhầm là watermark.
+                score = max(gain, step_conf(solid, clear, a_solid))
+                if use_rim:
+                    score = max(score, step_conf(rim_in, rim_out, a_rim))
+                if score > best_score:
+                    best_score, best = score, (x0, y0, gain)
+        if best is None or best_score < min_gain:
+            return img, None
+
+    x0, y0, gain = best
+    out = np.asarray(img.convert("RGBA") if img.mode == "RGBA" else rgb.convert("RGB")).copy()
+    out[y0:y0 + box, x0:x0 + box, :3] = np.clip(
+        np.rint(restore(x0, y0)), 0, 255).astype(np.uint8)
+    return Image.fromarray(out, img.mode if img.mode == "RGBA" else "RGB"), {
+        "box": (x0, y0, box, box), "gain": gain,
+    }
+
+
+def strip_gemini_watermark(
+    img: Image.Image, corner: float = 0.22, max_ratio: float = 0.08
+) -> tuple[Image.Image, int]:
+    """LƯỚI AN TOÀN dọn dấu ✦ còn sót SAU khi đã tách nền. Không phải đường xoá chính.
+
+    Đường chính bây giờ là unwatermark_gemini(): nó đảo phép trộn alpha NGAY khi ảnh tải về,
+    lấy lại đúng pixel gốc. Bình thường tới đây không còn gì để xoá (`speckles_removed: 0`).
+    Giữ hàm này cho trường hợp Google đổi hình học watermark khiến phép đảo không khớp nữa —
+    lúc đó dấu ✦ lại sống sót qua chroma key và cần dọn thô ở đây.
+
+    Cách làm THÔ, chỉ dùng được sau tách nền: xoá mọi mảng liên thông nằm GỌN trong ô góc
+    dưới-phải (`corner` phần cạnh) VÀ nhỏ hơn `max_ratio` lần mảng lớn nhất — nên không đụng
+    chủ thể chính, nhưng cũng KHÔNG cứu được khi watermark nằm đè lên chủ thể hoặc trên nền
+    đục (vd mockup screen-sheet). Đó chính là lý do phải xoá sớm ở unwatermark_gemini().
+    """
+    arr = np.array(img.convert("RGBA"))
+    H, W = arr.shape[:2]
+    mask = arr[..., 3] > ALPHA_FLOOR
+    if not mask.any():
+        return img, 0
+
+    rows, uf, areas = _components(mask)
+    find = uf["find"]
+    biggest = max(areas.values())
+
+    boxes: dict[int, list[int]] = {}
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            r = find(lbl)
+            b = boxes.get(r)
+            if b is None:
+                boxes[r] = [s, y, e, y + 1]
+            else:
+                b[0] = min(b[0], s); b[1] = min(b[1], y)
+                b[2] = max(b[2], e); b[3] = max(b[3], y + 1)
+
+    cx0, cy0 = W * (1.0 - corner), H * (1.0 - corner)
+    doomed = {
+        r for r, b in boxes.items()
+        if areas[r] < max_ratio * biggest and b[0] >= cx0 and b[1] >= cy0
+    }
+    if not doomed:
+        return img, 0
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            if find(lbl) in doomed:
+                arr[y, s:e, 3] = 0
+    return Image.fromarray(arr, "RGBA"), len(doomed)
+
+
+def fit_into(
+    content: Image.Image,
+    canvas_size: tuple[int, int],
+    target_box: tuple[int, int, int, int],
+    upscale=None,
+    report: dict | None = None,
+) -> Image.Image:
+    """Scale `content` vừa khít (contain) vào target_box, căn giữa, dán lên canvas trong suốt.
+
+    Giữ đúng tỉ lệ của content — thà chừa khoảng trống còn hơn bóp méo asset.
+
+    `upscale`: callable phóng 4x một mảng HxWx3 uint8 (xem upscale.upscale_rgb). Chỉ dùng
+    khi phải PHÓNG TO (scale > UPSCALE_MIN_GAIN) — đó đúng là ca LANCZOS làm ảnh mềm nhũn.
+    Thu nhỏ thì LANCZOS đã là tốt nhất, không đụng tới. Truyền None để giữ hành vi cũ.
+    `report`: dict tuỳ chọn, sẽ được NHÉT THÊM báo cáo chọn cách phóng to (xem best_upscale).
+    """
+    tx0, ty0, tx1, ty1 = target_box
+    tw, th = max(1, tx1 - tx0), max(1, ty1 - ty0)
+    cw, ch = content.size
+
+    scale = min(tw / cw, th / ch)
+    nw, nh = max(1, round(cw * scale)), max(1, round(ch * scale))
+
+    if scale > UPSCALE_MIN_GAIN:
+        scaled, up_rep = best_upscale(content, (nw, nh), backend=upscale)
+    else:
+        # Gọi thẳng resize(): Pillow tự convert RGBA -> RGBa (premultiplied) bên trong rồi
+        # convert ngược, nên mép không bị rỉ màu. Premultiply BẰNG TAY ở đây là phản tác dụng —
+        # Pillow sẽ nhân lần hai và phá màu ở alpha thấp (đo được: R 255 -> 0 tại alpha ~2).
+        scaled = content.convert("RGBA").resize((nw, nh), Image.LANCZOS)
+        up_rep = {"upscale_method": None, "upscale_factor": round(scale, 4)}
+    if report is not None:
+        report.update(up_rep)
+    canvas = Image.new("RGBA", canvas_size, (0, 0, 0, 0))
+    canvas.paste(scaled, (tx0 + (tw - nw) // 2, ty0 + (th - nh) // 2))
+    return canvas
+
+
+# ---------------------------------------------------------------------- PHÓNG TO
+# Ảnh AI sinh ra hay NHỎ hơn kích thước đích (Gemini/GPT trả về khung cố định, còn asset
+# game thì cần đúng size gốc). LANCZOS phóng to chỉ trải mép ra cho mềm đi — nó không có
+# thông tin nào để thêm. Real-ESRGAN anime_6B thì dựng lại nét. Nhưng nó cũng có thể BỊA:
+# thêm quầng sáng, đổi nét, ăn mất chi tiết nhỏ. Nên ở đây cũng chạy nhiều cách rồi chấm
+# điểm chọn bản tốt nhất, đúng như đường tách nền.
+
+UPSCALE_MIN_GAIN = 1.02   # phóng dưới mức này thì LANCZOS đã đủ, không gọi model làm gì
+UPSCALE_MAX_PASS = 2      # tối đa 2 lượt x4 = 16x; hơn nữa là ảnh nguồn quá nhỏ, vô vọng
+UPSCALE_GRAY = 128.0      # nền xám để "nhìn thấy" ảnh RGBA lúc đo (xem _visible)
+UPSCALE_RING_TOL = 3.0    # vượt biên min/max cục bộ quá mức này mới tính là quầng/ringing
+UPSCALE_BLEED_ITERS = 8   # số vòng loang màu tiền cảnh ra vùng trong suốt trước khi phóng
+UPSCALE_FLAT_ENERGY = 1e-6  # dưới mức này coi ảnh nguồn là PHẲNG (xem score_upscale)
+
+# Ngưỡng LOẠI THẲNG — LƯỚI AN TOÀN cho ca thảm hoạ, KHÔNG phải công cụ xếp hạng. Đặt cao
+# hẳn trên vùng giá trị của bản TỐT, vì loại nhầm bản tốt thì hậu quả là âm thầm rơi về
+# LANCZOS mờ — tệ hơn hẳn việc để lọt một bản hơi kém.
+# Số đo (bản dựng sẵn cho 4 cảnh x 2 độ phân giải, xem SKILL.md § Phóng to):
+#   lr_err  bản OK 1.0–6.5 (asset thật lên tới 14.4) | ảnh SAI HẲN 72.8–87.7
+#   cov_err bản OK <= 0.053                          | matte bị phá 0.099–0.122
+UPSCALE_BAD_LR = 30.0     # thu nhỏ ngược lại mà lệch ảnh gốc quá mức này -> bịa nội dung
+UPSCALE_BAD_COV = 0.08    # coverage lệch quá mức này -> matte bị ăn mòn hoặc phình ra
+
+# Trọng số chấm điểm — DÒ ĐƯỢC, không phải chọn cho đẹp. Cách dò: vẽ cùng một cảnh ở CẢ
+# HAI độ phân giải (không ảnh nào suy ra từ ảnh kia) rồi tìm bộ trọng số cho thứ tự xếp
+# hạng trùng với LPIPS. Kết quả: đúng 87.5% trên phần huấn luyện VÀ 87.5% trên nửa giữ
+# lại. Hai chi tiết đáng nhớ vì chúng đi ngược trực giác:
+#
+#  1. `ring` mới là tiêu chí phân định, không phải `lr_err`. Bỏ ring (W_RING=0) thì độ đúng
+#     tụt xuống 66.9% — đúng bằng mức của "cứ luôn chọn esrgan", tức là bộ điểm không còn
+#     đóng góp gì. Chính ring bắt được đúng nhóm ca mà LANCZOS thật sự thắng (hoạ tiết
+#     dày, nét mảnh san sát — chỗ model bịa ra nhiều nhất).
+#  2. `lr_err` và `cov_err` KHÔNG có sức xếp hạng. Dò ra trọng số tối ưu của chúng bằng 0;
+#     đẩy W_LR lên 0.2 làm độ đúng tụt còn 80.6%. Giữ W_LR bé xíu chỉ để phá thế hoà, còn
+#     cov_err rời hẳn khỏi tổng điểm — nó sống bằng vai trò loại thẳng ở trên.
+W_BLUR = 3.0
+W_RING = 0.40             # trên thang mức màu vượt biên trung bình (0.2–0.6 đều cho 87.5%)
+W_LR = 0.05               # trên thang mức màu 0..255 — chỉ để phá thế hoà
+
+
+def _shift(a: np.ndarray, dy: int, dx: int) -> np.ndarray:
+    """Dịch mảng `dy/dx` pixel, chỗ trống điền 0 (KHÔNG cuộn vòng như np.roll)."""
+    out = np.zeros_like(a)
+    h, w = a.shape[:2]
+    ys0, ys1 = max(0, -dy), h - max(0, dy)
+    xs0, xs1 = max(0, -dx), w - max(0, dx)
+    out[max(0, dy):h - max(0, -dy), max(0, dx):w - max(0, -dx)] = a[ys0:ys1, xs0:xs1]
+    return out
+
+
+def _bleed_rgb(rgb: np.ndarray, opaque: np.ndarray,
+               iters: int = UPSCALE_BLEED_ITERS) -> np.ndarray:
+    """Loang màu tiền cảnh ra vùng trong suốt trước khi đưa vào model phóng to.
+
+    BẮT BUỘC, không phải tinh chỉnh: sau unmix_cutout, pixel nền vẫn GIỮ NGUYÊN màu key
+    (magenta/xanh lá) với alpha 0 — vô hình khi hiển thị, nhưng model phóng to chỉ nhận
+    RGB nên nó thấy magenta thật và kéo màu đó vào mép chủ thể. Kết quả: viền hồng trên
+    ảnh mà đường tách nền vừa mới làm sạch tới mức cast = 0.
+    """
+    out = rgb.astype(np.float32).copy()
+    if not opaque.any():
+        return out
+    known = opaque.copy()
+    for _ in range(max(0, iters)):
+        if known.all():
+            break
+        k = known.astype(np.float32)
+        s = np.zeros_like(out)
+        c = np.zeros_like(k)
+        for dy, dx in ((-1, 0), (1, 0), (0, -1), (0, 1)):
+            s += _shift(out * k[..., None], dy, dx)
+            c += _shift(k, dy, dx)
+        fill = (~known) & (c > 0)
+        if not fill.any():
+            break
+        out[fill] = s[fill] / c[fill][:, None]
+        known |= fill
+    if not known.all():
+        # Vùng trong suốt rộng, loang không tới: điền màu trung bình chủ thể. Miễn là KHÔNG
+        # còn màu key nằm lại, còn màu gì thì cũng vô hình (alpha 0).
+        out[~known] = rgb[opaque].mean(axis=0)
+    return out
+
+
+def upscale_rgba(img: Image.Image, backend, alpha_esrgan: bool = True) -> Image.Image:
+    """Phóng 4x một ảnh RGBA bằng `backend` (callable HxWx3 uint8 -> 4x uint8).
+
+    RGB và ALPHA được phóng RIÊNG: model chỉ ăn 3 kênh. Alpha đi qua chính model đó dưới
+    dạng ảnh xám 3 kênh (`alpha_esrgan=True`) — mặc định này là kết quả ĐO, không phải
+    phỏng đoán; xem bảng trong SKILL.md § Phóng to. Đặt False để phóng alpha bằng LANCZOS.
+    """
+    a = np.asarray(img.convert("RGBA"))
+    rgb, al = a[..., :3], a[..., 3]
+    opaque = al > 0
+
+    if opaque.all():
+        big = backend(np.ascontiguousarray(rgb))
+        alpha = np.full(big.shape[:2], 255, np.uint8)
+        return Image.fromarray(np.dstack([big, alpha]), "RGBA")
+
+    filled = np.clip(_bleed_rgb(rgb.astype(np.float32), opaque), 0, 255).astype(np.uint8)
+    big = backend(np.ascontiguousarray(filled))
+    th, tw = big.shape[:2]
+    if alpha_esrgan:
+        gray = backend(np.ascontiguousarray(np.dstack([al, al, al])))
+        alpha = gray[..., 0]
+        if alpha.shape != (th, tw):        # backend giả trong test có thể lệch
+            alpha = np.asarray(Image.fromarray(alpha, "L").resize((tw, th), Image.LANCZOS))
+    else:
+        alpha = np.asarray(Image.fromarray(al, "L").resize((tw, th), Image.LANCZOS))
+    return Image.fromarray(np.dstack([big, alpha]), "RGBA")
+
+
+def _visible(img: Image.Image) -> np.ndarray:
+    """Ảnh RGBA ghép lên nền xám -> float32 HxWx3: đúng thứ MẮT THẤY.
+
+    Đo trên kênh RGB thô là sai: sau tách nền, vùng alpha 0 vẫn mang màu key, và mọi tiêu
+    chí sẽ bị màu vô hình đó chi phối thay vì bị chi phối bởi chủ thể.
+    """
+    a = np.asarray(img.convert("RGBA"), dtype=np.float32)
+    al = a[..., 3:4] / 255.0
+    return a[..., :3] * al + UPSCALE_GRAY * (1.0 - al)
+
+
+def _grad_energy(g: np.ndarray) -> float:
+    """NĂNG LƯỢNG gradient (bình phương), KHÔNG phải độ lớn trung bình.
+
+    Phân biệt sắc/mờ phải dùng bình phương: một cạnh cao Δ trải qua s pixel có tổng |∇|
+    KHÔNG đổi (vẫn = Δ) nên |∇| trung bình mù với độ mờ; còn tổng ∇² tụt từ Δ² xuống
+    Δ²/s. Đây chính là chỗ LANCZOS thua và là lý do tiêu chí `blur` tồn tại.
+    """
+    gy = np.diff(g, axis=0)
+    gx = np.diff(g, axis=1)
+    return float((gy ** 2).mean() + (gx ** 2).mean())
+
+
+def _local_minmax(v: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Min/max trong cửa sổ 3x3 cho từng kênh (numpy thuần)."""
+    lo, hi = v.copy(), v.copy()
+    for dy in (-1, 0, 1):
+        for dx in (-1, 0, 1):
+            if dy == 0 and dx == 0:
+                continue
+            # Ngoài biên coi như chính pixel đó -> không tạo ra cực trị giả ở mép ảnh.
+            s = _shift(v, dy, dx)
+            edge = _shift(np.ones(v.shape[:2], np.float32), dy, dx) == 0
+            s[edge] = v[edge]
+            lo = np.minimum(lo, s)
+            hi = np.maximum(hi, s)
+    return lo, hi
+
+
+def score_upscale(src: Image.Image, out: Image.Image) -> dict:
+    """Chấm điểm một bản phóng to. ĐIỂM THẤP = TỐT (giống score_cutout).
+
+    XẾP HẠNG bằng hai tiêu chí, mỗi cái bắt một kiểu hỏng mà cái kia mù hoàn toàn:
+
+      blur    Năng lượng gradient (bình phương) so với bản phóng NEAREST — NEAREST giữ
+              nguyên độ cao mọi bậc nhảy của ảnh gốc nên nó là trần lý thuyết của độ sắc.
+              Bắt ảnh MỀM NHŨN, đúng thứ LANCZOS luôn mắc phải khi phóng to.
+      ring    Độ lớn TRUNG BÌNH mà pixel vượt ra ngoài biên min/max cục bộ của ảnh gốc
+              (đơn vị mức màu). Bắt QUẦNG SÁNG và chi tiết BỊA RA — thứ `blur` chấm
+              NGƯỢC: quầng làm gradient mạnh hơn nên blur tưởng là "sắc nét, tốt".
+
+    Hai tiêu chí còn lại được ĐO là KHÔNG có sức xếp hạng, nên chúng chỉ làm LƯỚI AN TOÀN
+    (loại thẳng), không kéo điểm:
+
+      lr_err  Thu nhỏ bản phóng về đúng size gốc rồi so với gốc — chỗ duy nhất có sự thật
+              nền tuyệt đối. Nghe thì cứng nhất, nhưng nó thiên vị ảnh MỜ một cách có hệ
+              thống (đúng bài toán distortion–perception), nên dùng nó để xếp hạng là tự
+              tay chọn bản mờ. Vào tổng điểm với trọng số bé xíu, chỉ để phá thế hoà.
+      cov_err Chỉ cho ảnh RGBA: lệch alpha_coverage so với gốc. Bắt matte bị ăn mòn hoặc
+              phình ra. Đo được là quá thô để xếp hạng (matte hỏng vẫn cho cov_err 0.002),
+              nhưng vẫn chặn được ca phá hoại rõ rệt.
+    """
+    sw, sh = src.size
+    tw, th = out.size
+    vs = _visible(src)
+    vo = _visible(out)
+
+    # 1. back-projection: thu nhỏ bản phóng về size gốc rồi so với gốc.
+    back = out.resize((sw, sh), Image.LANCZOS)
+    lr_err = float(np.sqrt(((_visible(back) - vs) ** 2).mean()))
+
+    # 2. độ sắc, lấy bản NEAREST làm mốc trần.
+    nn = src.convert("RGBA").resize((tw, th), Image.NEAREST)
+    e_nn = _grad_energy(_visible(nn) @ np.array([0.299, 0.587, 0.114], np.float32))
+    e_out = _grad_energy(vo @ np.array([0.299, 0.587, 0.114], np.float32))
+    if e_nn <= UPSCALE_FLAT_ENERGY:
+        # Ảnh nguồn PHẲNG (mảng màu đặc, khung trơn): không có cạnh nào để mà làm sắc, nên
+        # "mờ" là khái niệm vô nghĩa ở đây. Không có nhánh này thì e_nn ~ 0 biến sharp thành
+        # 0/0 -> blur = 1.0 cho MỌI ứng viên, điểm bằng nhau, và bản thắng rơi vào tay thứ
+        # tự dict — tức là chọn bừa. Bắt được nhờ test end-to-end trên chủ thể màu đặc.
+        sharp, blur = 1.0, 0.0
+    else:
+        sharp = e_out / e_nn
+        blur = max(0.0, 1.0 - min(1.0, sharp))
+
+    # 3. quầng sáng: ĐỘ LỚN vượt biên trung bình (đơn vị mức màu 0..255), không phải SỐ
+    # ĐẾM pixel vượt biên. Bản đếm đã thử và bỏ: nó báo 27–37% pixel "ringing" trên ảnh
+    # đục, trong khi sai số thật lại nói bản đó TỐT HƠN — thứ nó đếm là vân nhiễu li ti
+    # của GAN (vượt biên 1–4 mức), không phải quầng. Quầng thật vượt biên hàng chục mức
+    # và nằm cạnh cạnh mạnh, nên đo độ lớn mới tách được hai thứ đó ra.
+    lo, hi = _local_minmax(vs)
+    yi = np.minimum((np.arange(th) * sh) // max(1, th), sh - 1)
+    xi = np.minimum((np.arange(tw) * sw) // max(1, tw), sw - 1)
+    over = 0.0
+    for c in range(3):
+        lo_c = lo[..., c][yi][:, xi]
+        hi_c = hi[..., c][yi][:, xi]
+        o_c = vo[..., c]
+        ex = np.maximum(np.maximum(o_c - hi_c, lo_c - o_c) - UPSCALE_RING_TOL, 0.0)
+        over += float(ex.mean())
+    ring = over / 3.0
+
+    cov_err = abs(alpha_coverage(out) - alpha_coverage(src))
+
+    m = {
+        "lr_err": lr_err,
+        "blur": blur,
+        "sharp": sharp,
+        "ring": ring,
+        "cov_err": cov_err,
+    }
+    dq: list[str] = []
+    if lr_err > UPSCALE_BAD_LR:
+        dq.append("bia_noi_dung")
+    if cov_err > UPSCALE_BAD_COV:
+        dq.append("lech_matte")
+    m["disqualified"] = dq
+
+    m["score"] = W_BLUR * blur + W_RING * ring + W_LR * lr_err + (10.0 if dq else 0.0)
+    return m
+
+
+def best_upscale(img: Image.Image, target: tuple[int, int], backend=None) -> tuple[Image.Image, dict]:
+    """Phóng `img` lên đúng `target`, chạy NHIỀU cách rồi chấm điểm chọn bản tốt nhất.
+
+    Ứng viên:
+      lanczos      Pillow LANCZOS thẳng tới đích. Luôn có, luôn là lưới an toàn.
+      esrgan       Real-ESRGAN 4x (lặp tới khi đủ lớn, tối đa UPSCALE_MAX_PASS lượt) rồi
+                   LANCZOS thu về đúng đích. Tốt nhất khi đích <= 4x.
+      esrgan-pre   LANCZOS lên đích/4 TRƯỚC rồi mới 4x. Chỉ dựng khi đích > 4x: lúc đó
+                   `esrgan` phải LANCZOS PHÓNG TO lần nữa sau model (mờ lại đúng thứ vừa
+                   làm nét), còn cách này để model chạy sau cùng.
+
+    `backend=None` (thiếu torch) -> chỉ còn lanczos, vẫn trả ảnh đúng size. Model nổ giữa
+    chừng cũng vậy: ghi vào report["upscale_errors"] rồi đi tiếp, KHÔNG làm hỏng pipeline.
+    """
+    tw, th = int(target[0]), int(target[1])
+    sw, sh = img.size
+    factor = max(tw / max(1, sw), th / max(1, sh))
+    src = img.convert("RGBA")
+
+    cands: list[tuple[str, Image.Image]] = [("lanczos", src.resize((tw, th), Image.LANCZOS))]
+    errs: list[str] = []
+
+    if backend is not None and factor > UPSCALE_MIN_GAIN:
+        def _net(im: Image.Image, passes: int) -> Image.Image:
+            for _ in range(passes):
+                im = upscale_rgba(im, backend)
+            return im
+
+        passes = min(UPSCALE_MAX_PASS, max(1, math.ceil(math.log(max(factor, 1.0), 4) - 1e-9)))
+        try:
+            big = _net(src, passes)
+            cands.append(("esrgan", big.resize((tw, th), Image.LANCZOS)))
+        except Exception as e:
+            errs.append(f"esrgan: {type(e).__name__}: {e}")
+
+        if factor > 4.0:
+            try:
+                pre = src.resize((max(1, -(-tw // 4)), max(1, -(-th // 4))), Image.LANCZOS)
+                out = _net(pre, 1)
+                if out.size != (tw, th):
+                    out = out.resize((tw, th), Image.LANCZOS)
+                cands.append(("esrgan-pre", out))
+            except Exception as e:
+                errs.append(f"esrgan-pre: {type(e).__name__}: {e}")
+
+    table: dict[str, dict] = {}
+    for name, im in cands:
+        try:
+            table[name] = score_upscale(src, im)
+        except Exception as e:                    # chấm điểm hỏng != ảnh hỏng
+            errs.append(f"score {name}: {type(e).__name__}: {e}")
+            table[name] = {"score": float("inf"), "disqualified": ["khong_cham_duoc"]}
+
+    best = min(table, key=lambda k: table[k]["score"])
+    report = {
+        "upscale_method": best,
+        "upscale_score": table[best]["score"],
+        "upscale_table": table,
+        "upscale_factor": round(factor, 4),
+        "upscale_from": [sw, sh],
+        "upscale_to": [tw, th],
+        "upscale_candidates": [n for n, _ in cands],
+        "upscale_all_disqualified": all(t.get("disqualified") for t in table.values()),
+    }
+    if errs:
+        report["upscale_errors"] = errs
+    return dict(cands)[best], report
+
+
+# Bề dày vành ngoài dùng để kiểm nền, tính bằng pixel của ảnh Gemini sinh ra.
+BORDER_PX = 4
+
+# Vành ngoài lệch màu key quá mức này -> nền không phẳng (Gemini vẽ bóng/gradient/viền lên nền).
+BAD_BORDER_DIST = 60.0
+
+
+def border_impurity(img: Image.Image, key_hex: str, border: int = BORDER_PX) -> float:
+    """Khoảng cách trung bình của VÀNH NGOÀI ảnh so với màu key.
+
+    Kiểm nền một cách TRỰC TIẾP. alpha_coverage chỉ suy ra gián tiếp: nó chỉ nổ khi
+    nền hỏng TOÀN BỘ (coverage > 95%). Nền hỏng MỘT PHẦN — bóng đổ, gradient, viền —
+    thì coverage không thấy gì, mà mảng đặc đó lại thổi phồng solid_ratio và che mất
+    chủ thể bóng ma. Vành ngoài gần như luôn là nền thuần, nên đo thẳng vào đó.
+
+    GIẢ ĐỊNH CHƯA GHI RÕ TRƯỚC ĐÂY, nay ghi lại: hàm này giả định bản sinh của Gemini
+    CHỪA MỘT LỀ NỀN quanh chủ thể — tức là vành `border` px ngoài cùng thực sự là nền,
+    không phải một phần của chủ thể. Prompt gửi Gemini BẮT BUỘC phải yêu cầu điều này
+    ("chủ thể không được chạm mép ảnh"). Nếu Gemini vẫn vẽ chủ thể tràn sát mép canvas
+    (không chừa lề key nào) — có thật, asset `cell_base.png` của game có bbox phủ kín
+    cả canvas 249x249, nên một model được yêu cầu restyle nó hoàn toàn có thể vẽ tràn
+    mép — thì vành ngoài sẽ chứa pixel CHỦ THỂ chứ không phải nền, và hàm này sẽ báo
+    `bad_background` dù nền thật ra ổn (hoặc dù không hề có "nền" nào cả).
+
+    Đây là đánh đổi CÓ CHỦ ĐÍCH, không sửa: false positive (báo hỏng nhầm) là lỗi AN
+    TOÀN — cái giá là một lần sinh lại tốn kém vài giây, và asset lỗi không bao giờ lọt
+    được vào game. False negative (không báo hỏng) mới là thứ nguy hiểm — asset bị bóng
+    ma/nền lỗi sẽ lọt thẳng vào game. Nên giữa hai loại sai, hàm này LUÔN chọn nghiêng
+    về false positive. Xem test_border_impurity_false_positive_when_subject_touches_edge
+    để thấy ca này được đo và chấp nhận, không phải một bug chờ sửa.
+    """
+    rgb = np.asarray(img.convert("RGB"), dtype=np.uint8)
+    h, w = rgb.shape[:2]
+    b = max(1, min(border, h // 2, w // 2))
+
+    ring = np.concatenate([
+        rgb[:b, :, :].reshape(-1, 3),
+        rgb[-b:, :, :].reshape(-1, 3),
+        rgb[b:-b, :b, :].reshape(-1, 3),
+        rgb[b:-b, -b:, :].reshape(-1, 3),
+    ])
+    return float(_dist_map(ring.reshape(1, -1, 3), hex_to_rgb(key_hex)).mean())
+
+
+def sample_border_color(img: Image.Image, border: int = BORDER_PX) -> tuple[str, float]:
+    """Màu nền THẬT của bản sinh, đo từ vành ngoài `border`px, kèm độ thuần của vành.
+
+    Trả (hex, purity). purity = tỉ lệ pixel vành nằm trong BAD_BORDER_DIST quanh màu
+    trung bình — purity cao nghĩa là vành thực sự là MỘT màu nền phẳng, và hex đó chính
+    là màu key hiệu dụng để chroma_key.
+
+    Lý do tồn tại (đo thật): model có thể vẽ nền "xanh studio" (#2ED246, vignette nhẹ)
+    thay vì #00FF00 được yêu cầu — chroma_key theo key yêu cầu khi đó trượt CẢ khung
+    (coverage=1.0, bad_background) dù bản sinh hoàn toàn dùng được. Dò màu nền thật rồi
+    key lại cứu được bản đó mà không tốn lượt sinh nào. Cùng giả định lề với
+    border_impurity: vành ngoài phải là nền (prompt đã ép chủ thể chừa lề)."""
+    rgb = np.asarray(img.convert("RGB"), dtype=np.float32)
+    h, w = rgb.shape[:2]
+    b = max(1, min(border, h // 2, w // 2))
+    ring = np.concatenate([
+        rgb[:b, :, :].reshape(-1, 3),
+        rgb[-b:, :, :].reshape(-1, 3),
+        rgb[b:-b, :b, :].reshape(-1, 3),
+        rgb[b:-b, -b:, :].reshape(-1, 3),
+    ])
+    mean = ring.mean(axis=0)
+    d = np.sqrt(((ring - mean) ** 2).sum(axis=1))
+    purity = float((d <= BAD_BORDER_DIST).mean())
+    return rgb_to_hex(tuple(int(round(float(x))) for x in mean)), purity
+
+
+# Ngưỡng cho lớp dọn nền SÓT (strip_bg_residue / bg_residue). Đo theo redmean, so với màu
+# nền ĐO ĐƯỢC (sample_border_color) — KHÔNG phải màu key yêu cầu. Vì sao: model gần như không
+# bao giờ vẽ đúng #00FF00; đo thật trên ảnh sinh ra là #0CF508 và #0BD009 (G=209!). Key theo màu
+# YÊU CẦU để lại tới 100% nền dưới dạng màng bán trong suốt, key theo màu ĐO ĐƯỢC thì sạch 0 px.
+BG_RESIDUE_TOL = 48.0    # sát màu nền đo được thì mới coi là nền sót (chặt, tránh gặm vào art)
+BAD_BG_RESIDUE = 0.02    # còn >2% pixel đục mang màu nền -> cờ bad_background
+
+
+def bg_residue(img: Image.Image, bg_hex: str, tol: float = BG_RESIDUE_TOL) -> float:
+    """Tỉ lệ pixel ĐỤC vẫn đang mang màu nền — thước đo "tách nền còn bẩn không".
+
+    Thay cho border_impurity trên đường BEN2: border_impurity đo VÀNH ẢNH GỐC theo màu key,
+    nên khi BEN2 chạy nó vô nghĩa và trước đây bị ép cứng `0.0` — tức KHÔNG cờ nào báo được
+    nền còn sót, lỗi cứ thế đi thẳng vào asset. Hàm này đo trên ẢNH ĐÃ TÁCH nên đúng thứ cần biết.
+    """
+    arr = np.asarray(img.convert("RGBA"))
+    opaque = arr[..., 3] > ALPHA_FLOOR
+    if not opaque.any():
+        return 0.0
+    d = _dist_map(arr[..., :3].astype(np.float64), hex_to_rgb(bg_hex))
+    return float((d[opaque] <= tol).mean())
+
+
+def strip_bg_residue(
+    img: Image.Image, bg_hex: str, tol: float = BG_RESIDUE_TOL
+) -> tuple[Image.Image, int]:
+    """Xoá màng/vệt nền còn sót sau tách nền, theo MÀU NỀN ĐO ĐƯỢC. Trả (ảnh, số px đã xoá).
+
+    Chỉ xoá vùng màu-nền **LIỀN MẠCH với nền đã trong suốt** (hoặc chạm vành ảnh). Ràng buộc
+    liên thông này là phần quan trọng nhất: bản thử nghiệm xoá theo màu/hue KHÔNG kèm liên
+    thông đã gặm mép thành rỗ như mối ăn (đo thật trên ảnh bánh răng) vì nó đục cả những pixel
+    art tình cờ trùng màu. Có liên thông thì art nằm trong lòng chủ thể không bao giờ bị chạm —
+    muốn bị xoá, một vùng phải nối được ra tới nền thật.
+
+    KHÔNG cứu được ca model dùng chính hue của key làm MÀU NÉT trong tranh (vd viền xanh đậm
+    quanh bánh răng): thứ đó là art thật, nằm kẹp giữa hai lớp art khác nên không liền mạch
+    với nền, và về nguyên tắc không phân biệt được bằng màu. Ca đó phải chặn từ prompt —
+    xem reference/prompt-template.md § Đừng để model dùng màu key làm màu nét.
+    """
+    arr = np.array(img.convert("RGBA"))
+    alpha = arr[..., 3]
+    d = _dist_map(arr[..., :3].astype(np.float64), hex_to_rgb(bg_hex))
+    cand = d <= tol
+    clear = alpha <= ALPHA_FLOOR
+    if not cand.any():
+        return img, 0
+
+    # Vùng để dò liên thông = pixel màu-nền CỘNG pixel đã trong suốt. Phải gộp cả pixel trong
+    # suốt vào: nếu bộ tách nền xoá luôn RGB về 0 thì nền đã xoá không còn "màu nền" nữa và
+    # mọi vệt sót sẽ mất đường nối ra ngoài.
+    region = cand | clear
+    rows, uf, _ = _components(region)
+    find = uf["find"]
+
+    h, w = alpha.shape
+    doomed: set[int] = set()
+    for y, runs in enumerate(rows):
+        edge_row = y == 0 or y == h - 1
+        for s, e, lbl in runs:
+            # Mầm: chạm nền đã trong suốt, hoặc chạm vành ảnh (theo hợp đồng prompt lề rộng,
+            # vành ngoài là nền — cùng giả định của sample_border_color/border_impurity).
+            if clear[y, s:e].any() or edge_row or s == 0 or e >= w:
+                doomed.add(find(lbl))
+    if not doomed:
+        return img, 0
+
+    killed = 0
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            if find(lbl) not in doomed:
+                continue
+            seg_a = arr[y, s:e, 3]
+            seg_c = cand[y, s:e]
+            hit = seg_c & (seg_a > ALPHA_FLOOR)   # chỉ chạm pixel MÀU NỀN còn đang đục
+            if hit.any():
+                killed += int(hit.sum())
+                seg_a[hit] = 0
+    if not killed:
+        return img, 0
+    return Image.fromarray(arr, "RGBA"), killed
+
+
+def _erode_alpha(img: Image.Image, px: int = 1) -> Image.Image:
+    """Bào rìa alpha `px` pixel bằng min-filter — cắt vành anti-alias/viền key còn
+    sót quanh silhouette mà KHÔNG đổi màu pixel nào (chỉ hạ alpha ở mép). RGB giữ
+    nguyên; chỉ kênh A co lại. `px<=0` -> trả nguyên ảnh."""
+    if px <= 0:
+        return img.convert("RGBA")
+    rgba = img.convert("RGBA")
+    a = rgba.getchannel("A")
+    for _ in range(px):
+        a = a.filter(ImageFilter.MinFilter(3))
+    rgba.putalpha(a)
+    return rgba
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════
+# Tách nền ĐA PHƯƠNG PHÁP: chạy nhiều cách, tự chấm điểm, lấy bản tốt nhất
+# ══════════════════════════════════════════════════════════════════════════════════════════
+# VÌ SAO không có MỘT phương pháp thắng mọi ảnh (đo thật, 10 cách trên 4 bản sinh):
+#   • BEN2 hạng nhất trên asset rời có mép lông/tơ, nhưng trên ảnh NỀN full-bleed (thảm cỏ
+#     tràn hết khung, không có "vật thể nổi bật") nó ăn mất 8.99% chủ thể và làm mép nhoè
+#     thành dải 77.425 px — trong khi các cách theo màu chỉ ~1.500 px.
+#   • chroma_key theo màu key YÊU CẦU để lại viền hồng nhìn thấy rõ, vì model vẽ #FB0EE0
+#     chứ không phải #FF00FF được yêu cầu, và khoảng cách trung vị 57.7 chỉ còn 12 đơn vị
+#     biên an toàn dưới t_low=70.
+#   • Bề rộng dải anti-alias KHÁC NHAU theo nguồn: đo được 2px trên bản GPT nhưng 7–8px trên
+#     bản Gemini (chân trời vẽ nhoè). Một hằng số cố định thì hoặc sót viền hoặc gặm chủ thể.
+# Nên cách đúng là ĐO rồi CHỌN, không phải chọn trước rồi tin.
+
+CUTOUT_BAND_MAX = 12          # trần nới dải AA — trên mức này gần như chắc là đo sai
+CUTOUT_LOOSE_TOL = 60.0       # ngưỡng "coi như màu nền" khi dựng mask thô (redmean)
+CUTOUT_BAD_FG_LOSS = 0.02     # ăn >2% lòng chủ thể -> loại thẳng, không cần so điểm
+CUTOUT_MIN_BORDER_SHARE = 0.10  # mode viền phải chiếm >=10% vành mới tin là màu nền
+
+
+def modal_border_color(
+    img: Image.Image, border: int = BORDER_PX, quant: int = 8,
+    key_hex: str | None = None, max_dist: float = MIN_KEY_MARGIN,
+) -> tuple[str, float]:
+    """Màu nền trên vành ảnh theo MODE, kèm tỉ lệ vành mà nó chiếm. Trả (hex, share).
+
+    Khác `sample_border_color` ở chỗ dùng mode chứ không phải mean, và ĐÓ LÀ LÝ DO nó tồn
+    tại: với ảnh NỀN full-bleed (nửa trên là trời màu key, nửa dưới là thảm cỏ tràn ra tận
+    vành), mean trộn hai nửa thành bùn tím — đo thật trên home_grass/gpt1.png:
+    sample_border_color trả `#AC4978` với purity **0.0002**, tức đường auto-key trong MCP
+    KHÔNG BAO GIỜ kích hoạt và cả pipeline rơi về màu key yêu cầu. Mode trả `#FB0EE0`, đúng
+    màu model đã vẽ.
+
+    `key_hex` (NÊN LUÔN TRUYỀN): chỉ xét pixel vành nằm trong `max_dist` quanh màu key YÊU
+    CẦU, rồi lấy mode trong số đó. Không có nó thì mode toàn cục CHỈ ĐÚNG NHỜ MAY: nó thắng
+    trên ảnh thật vì nền key phẳng còn thảm cỏ có vân (không bin xanh nào áp đảo), nhưng
+    trên ảnh mà chủ thể PHẲNG và chiếm nhiều vành hơn nền thì mode trả về màu CHỦ THỂ — và
+    key theo màu chủ thể sẽ xoá mất chính chủ thể. Ca này bắt được bằng test
+    (`_plate` có nền xanh phẳng: vành có 1312 px xanh so với 1168 px hồng, mode toàn cục
+    chọn XANH). Lọc theo màu key yêu cầu thì hết phụ thuộc vào vân bề mặt.
+
+    `quant` gộp màu về lưới 8 mức để nhiễu số hoá không xé mode thành nghìn bin riêng lẻ.
+    share thấp (< CUTOUT_MIN_BORDER_SHARE) nghĩa là vành không có mảng màu-key nào đáng kể
+    -> đừng tin, quay về màu key yêu cầu.
+    """
+    rgb = np.asarray(img.convert("RGB"), dtype=np.int32)
+    h, w = rgb.shape[:2]
+    b = max(1, min(border, h // 2, w // 2))
+    ring = np.concatenate([
+        rgb[:b, :, :].reshape(-1, 3),
+        rgb[-b:, :, :].reshape(-1, 3),
+        rgb[b:-b, :b, :].reshape(-1, 3),
+        rgb[b:-b, -b:, :].reshape(-1, 3),
+    ])
+    total = len(ring)
+    if not total:
+        return "#000000", 0.0
+
+    if key_hex is not None:
+        near = _dist_map(ring.reshape(1, -1, 3).astype(np.uint8), hex_to_rgb(key_hex))
+        ring = ring[near.reshape(-1) <= max_dist]
+        if not len(ring):
+            return key_hex, 0.0
+
+    q = ring // quant
+    keys = (q[:, 0] << 16) | (q[:, 1] << 8) | q[:, 2]
+    vals, cnt = np.unique(keys, return_counts=True)
+    top = vals[int(cnt.argmax())]
+    share = float(cnt.max()) / float(total)     # so với TOÀN vành, không chỉ phần đã lọc
+    mean = ring[keys == top].mean(axis=0)
+    return rgb_to_hex(tuple(int(round(float(x))) for x in mean)), share
+
+
+def _dilate(mask: np.ndarray, px: int = 1) -> np.ndarray:
+    """Nới mask `px` pixel theo 4 hướng (numpy thuần — không có scipy trong môi trường này)."""
+    out = mask
+    for _ in range(max(0, px)):
+        p = np.pad(out, 1, constant_values=False)
+        out = out | p[:-2, 1:-1] | p[2:, 1:-1] | p[1:-1, :-2] | p[1:-1, 2:]
+    return out
+
+
+def _frame_mask(mask: np.ndarray) -> np.ndarray:
+    """Chỉ giữ những vùng liền mạch của `mask` có CHẠM vành ảnh — tức nền thật.
+
+    Cùng ràng buộc liên thông với strip_bg_residue, và cùng một lý do: art nằm trong lòng
+    chủ thể mà tình cờ trùng màu nền thì không nối được ra vành, nên không bao giờ bị xoá.
+    """
+    if not mask.any():
+        return np.zeros_like(mask)
+    rows, uf, _ = _components(mask)
+    find = uf["find"]
+    h, w = mask.shape
+    good: set[int] = set()
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            if y == 0 or y == h - 1 or s == 0 or e == w:
+                good.add(find(lbl))
+    out = np.zeros_like(mask)
+    for y, runs in enumerate(rows):
+        for s, e, lbl in runs:
+            if find(lbl) in good:
+                out[y, s:e] = True
+    return out
+
+
+def _cutout_regions(img: Image.Image, bg_hex: str) -> dict:
+    """Các vùng dùng để CHẤM ĐIỂM, dựng từ ảnh gốc — KHÔNG từ đầu ra của cách nào cả.
+
+    Mọi phương pháp phải được đo trên cùng một bộ vùng, nếu không thì so điểm là vô nghĩa.
+    Trả dict: hard (nền chắc chắn), band (dải AA đã đo bề rộng), far (lòng chủ thể), band_w.
+    """
+    u8 = np.asarray(img.convert("RGB"))
+    bg = hex_to_rgb(bg_hex)
+    d = _dist_map(u8, bg)
+    hard = _frame_mask(d <= CUTOUT_LOOSE_TOL)
+
+    out = {"hard": hard, "d": d, "band_w": 0,
+           "band": np.zeros_like(hard), "far": ~hard, "d_fg": float(np.percentile(d, 95))}
+    if not hard.any():
+        return out
+
+    outer = ~_dilate(hard, CUTOUT_BAND_MAX + 4)
+    out["d_fg"] = float(np.median(d[outer])) if outer.any() else float(np.percentile(d, 95))
+
+    # Bề rộng dải AA ĐO TỪ ẢNH, không phải hằng số: nới từng ring một, dừng khi ring đã
+    # gần như tiền cảnh thuần. Đo thật: bản GPT dừng ở 2, bản Gemini đi tới 7–8.
+    k, prev = 0, hard
+    while k < CUTOUT_BAND_MAX:
+        cur = _dilate(hard, k + 1)
+        ring = cur & ~prev
+        if not ring.any():
+            break
+        k += 1
+        if float(np.median(d[ring])) >= 0.90 * out["d_fg"]:
+            break            # ring này gần như fg thuần -> đã lấy nó rồi thì dừng
+        prev = cur
+    out["band_w"] = max(1, k)
+    out["band"] = _dilate(hard, out["band_w"]) & ~hard
+    out["far"] = ~_dilate(hard, out["band_w"] + 3)
+    return out
+
+
+def unmix_cutout(
+    img: Image.Image, bg_hex: str, regions: dict | None = None
+) -> tuple[Image.Image, dict]:
+    """Tách nền bằng NGHỊCH ĐẢO ĐẠI SỐ phương trình ghép ảnh. Trả (RGBA, info).
+
+    despill là heuristic kẹp kênh. Nhưng ta ĐO ĐƯỢC màu nền, nên đảo thẳng được:
+
+        O = F·α + BG·(1−α)      ->      F = (O − BG·(1−α)) / α
+
+    α lấy từ ramp tuyến tính theo khoảng cách màu trên dải AA (bề rộng đo từ ảnh), 0 trong
+    vùng nền liền-vành, 255 ngoài dải. Kiểm chứng bằng roundtrip (ghép kết quả trở lại lên
+    màu nền rồi so với ảnh gốc): sai số trên dải mềm **0.228** so với 25.09 của region-grow
+    +despill và 16.45 của chroma_key+despill. Nới rộng dải là AN TOÀN vì α tính từ khoảng
+    cách màu thật — pixel đã là tiền cảnh thuần thì tự nhận α=255, nằm trong dải cũng không
+    bị hạ. Đo thật: cast (px còn ám màu nền khi ghép lên trắng/đen) = 0 trên cả 4 bản sinh.
+    """
+    u8 = np.asarray(img.convert("RGB"))
+    rgb = u8.astype(np.float64)
+    r = regions if regions is not None else _cutout_regions(img, bg_hex)
+    hard, band, d = r["hard"], r["band"], r["d"]
+    bg = np.array(hex_to_rgb(bg_hex), dtype=np.float64)
+
+    info = {"band_w": r["band_w"], "bg_hex": bg_hex, "soft_px": 0,
+            "clipped_px": 0, "hard_frac": float(hard.mean())}
+    if not hard.any():
+        # Không có vùng màu-nền nào chạm vành -> không có gì để xoá. Trả ảnh đục nguyên vẹn
+        # thay vì đoán bừa; lớp chấm điểm sẽ thấy bg_residue cao và loại nó nếu có cách khác.
+        return Image.fromarray(
+            np.dstack([u8, np.full(u8.shape[:2], 255, np.uint8)]), "RGBA"), info
+
+    base = float(np.percentile(d[hard], 98))
+    span = max(1e-6, r["d_fg"] - base)
+    alpha = np.where(hard, 0.0, 255.0)
+    if band.any():
+        alpha[band] = np.clip((d[band] - base) / span, 0.0, 1.0) * 255.0
+
+    a = (alpha / 255.0)[..., None]
+    F = rgb.copy()
+    solve = band & (alpha > ALPHA_FLOOR) & (alpha < 255.0)
+    if solve.any():
+        with np.errstate(divide="ignore", invalid="ignore"):
+            cand = (rgb - bg[None, None, :] * (1.0 - a)) / np.maximum(a, 1e-6)
+        info["clipped_px"] = int(((cand < -10) | (cand > 265)).any(axis=2)[solve].sum())
+        F[solve] = np.clip(cand[solve], 0.0, 255.0)
+        info["soft_px"] = int(solve.sum())
+
+    out = np.dstack([F, alpha])
+    return Image.fromarray(np.rint(out).clip(0, 255).astype(np.uint8), "RGBA"), info
+
+
+def score_cutout(src: Image.Image, out: Image.Image, bg_hex: str,
+                 regions: dict | None = None) -> dict:
+    """Chấm điểm một bản tách nền — KHÔNG cần ảnh tham chiếu. Điểm THẤP là tốt.
+
+    Bốn thành phần, mỗi cái bắt một kiểu hỏng khác nhau; thiếu bất kỳ cái nào là mở đường
+    cho một cách dở thắng điểm:
+      • cast      — số px còn ÁM MÀU NỀN khi ghép lên trắng/đen. Bắt "viền hồng/xanh còn
+                    sót". Đo trên dải AA lấy từ ẢNH GỐC nên mọi cách chịu cùng một thước.
+      • f_err     — màu tiền cảnh lệch bao nhiêu so với nghịch đảo đại số. Bắt "giữ nguyên
+                    màu đã bị nền trộn vào". Một mình nó KHÔNG đủ: cách nào để alpha=255
+                    khắp dải sẽ có f_err=0 hiển nhiên (vì khi α=1 thì F_ideal ≡ O) — chính
+                    `cast` mới bắt được ca đó.
+      • fg_loss   — % lòng chủ thể (vùng `far`) bị làm không-đục. Bắt "ăn mất chủ thể":
+                    BEN2 trên ảnh nền full-bleed đo được 8.99%.
+      • bg_residue— % px đục vẫn mang màu nền. Bắt "để nguyên nền".
+    Giả định: chủ thể ĐỤC ở trong lòng (đúng với asset game trên phông key phẳng). Chủ thể
+    trong suốt thật (kính, khói) sẽ bị fg_loss phạt oan — khi đó dùng multi=False.
+    """
+    r = regions if regions is not None else _cutout_regions(src, bg_hex)
+    O = np.asarray(src.convert("RGB"), dtype=np.float64)
+    arr = np.asarray(out.convert("RGBA"), dtype=np.float64)
+    al, F = arr[..., 3], arr[..., :3]
+    bg = np.array(hex_to_rgb(bg_hex), dtype=np.float64)
+
+    m: dict = {}
+    far, band = r["far"], r["band"]
+
+    # `far` (lòng chủ thể) chỉ có nghĩa khi TÌM ĐƯỢC vùng màu nền. Nếu không có pixel nào
+    # mang màu key chạm vành — ảnh chụp/tranh nền thật, không có phông key — thì `hard` rỗng,
+    # `far` biến thành TOÀN ẢNH, và fg_loss quay ra đo "bao nhiêu phần ảnh không đục", tức
+    # PHẠT ĐÚNG cách đã tách nền thành công. Bug thật đã gặp: BEN2 tách đúng chủ thể
+    # (coverage 0.156 so với diện tích thật 0.181) nhưng bị loại với fg_loss 0.8484, và bản
+    # KHÔNG LÀM GÌ CẢ thắng, giao ra ảnh nguyên vẹn. Khi không có phông key thì bỏ hẳn tiêu
+    # chí này và để `coverage` làm cửa gác — nó loại đúng những cách phủ kín khung.
+    fg_valid = bool(r["hard"].any()) and bool(far.any())
+    m["fg_loss"] = float((al[far] < 247).mean()) if fg_valid else 0.0
+    m["fg_loss_valid"] = fg_valid
+    m["bg_residue"] = bg_residue(out, bg_hex)
+    m["coverage"] = float((al > ALPHA_FLOOR).mean())
+    m["soft_px"] = int(((al > ALPHA_FLOOR) & (al < 247)).sum())
+
+    # cast: hướng sắc của pixel đã ghép có trùng hướng sắc của màu nền không (không phụ
+    # thuộc hue cụ thể -> dùng được cho cả key xanh lá và key hồng).
+    vb = bg - bg.mean()
+    nb = float(np.linalg.norm(vb))
+    zone = band & (al > ALPHA_FLOOR)
+    cast = 0
+    if nb > 1e-6 and zone.any():
+        for back in (255.0, 32.0):
+            aa = (al[zone] / 255.0)[:, None]
+            comp = F[zone] * aa + back * (1.0 - aa)
+            u = comp - comp.mean(axis=1, keepdims=True)
+            nu = np.linalg.norm(u, axis=1)
+            cos = (u @ vb) / np.maximum(nu * nb, 1e-6)
+            cast += int(((cos > 0.85) & (nu > 12.0)).sum())
+    m["cast"] = cast
+
+    soft = band & (al > ALPHA_FLOOR) & (al < 247)
+    if soft.sum() >= 50:
+        aa = (al[soft] / 255.0)[:, None]
+        ideal = (O[soft] - bg[None, :] * (1.0 - aa)) / np.maximum(aa, 1e-6)
+        m["f_err"] = float(np.abs(F[soft] - np.clip(ideal, 0.0, 255.0)).mean())
+    else:
+        m["f_err"] = 0.0
+
+    aa = (al / 255.0)[..., None]
+    m["roundtrip"] = float(np.abs(F * aa + bg[None, None, :] * (1.0 - aa) - O).mean())
+
+    # Loại thẳng (không so điểm) những kiểu hỏng mà không đánh đổi nào bù được.
+    dq = []
+    if m["fg_loss"] > CUTOUT_BAD_FG_LOSS:
+        dq.append("an_chu_the")
+    if m["bg_residue"] > BAD_BG_RESIDUE:
+        dq.append("sot_nen")
+    if m["coverage"] < BAD_LOW or m["coverage"] > BAD_HIGH:
+        dq.append("phu_bat_thuong")
+    m["disqualify"] = dq
+
+    band_n = max(1, int(band.sum()))
+    m["score"] = (3.0 * cast / band_n
+                  + 1.0 * m["f_err"] / 255.0
+                  + 0.5 * m["roundtrip"] / 255.0
+                  + 2.0 * m["fg_loss"]
+                  + 2.0 * m["bg_residue"])
+    return m
+
+
+def best_cutout(
+    img: Image.Image, key_hex: str, bg_hex: str | None = None, cutout=None
+) -> tuple[Image.Image, dict]:
+    """Chạy NHIỀU cách tách nền, chấm điểm từng cách, trả bản điểm tốt nhất.
+
+    Trả (RGBA, report). report["cutout_method"] là tên cách đã thắng, report["cutout_table"]
+    là bảng điểm ĐẦY ĐỦ của mọi cách (kể cả cách bị loại) để người duyệt thấy VÌ SAO nó thắng.
+
+    `bg_hex` bỏ trống -> tự đo bằng modal_border_color, nhưng chỉ nhận nếu vừa chiếm đủ
+    vành vừa KHÔNG lệch màu key yêu cầu quá MIN_KEY_MARGIN. Cửa gác thứ hai đó là để chặn ca
+    chủ thể tràn sát vành: khi đó màu đo được là màu CHỦ THỂ (vẫn "thuần" một màu!) và key
+    theo nó sẽ xoá mất chính chủ thể. Ngưỡng 190 là ĐO ĐƯỢC, không phải đoán: độ lệch
+    model-vẽ-so-với-yêu-cầu đo trên 6 bản sinh nằm trong 6.0–96.5, còn khoảng cách từ màu key
+    tới màu chủ thể thật là 353–536. 190 nằm giữa với biên ~2× cả hai phía.
+    """
+    # Lọc theo màu key yêu cầu NGAY trong modal_border_color: mode toàn cục có thể trả về
+    # màu CHỦ THỂ khi chủ thể phẳng và chiếm nhiều vành hơn nền (xem docstring hàm đó).
+    sampled, share = modal_border_color(img, key_hex=key_hex)
+    chosen, why = bg_hex, "duoc_truyen_vao"
+    if chosen is None:
+        if share >= CUTOUT_MIN_BORDER_SHARE:
+            chosen, why = sampled, "mode_vien"
+        else:
+            chosen, why = key_hex, "khong_thay_mau_key_o_vien"
+
+    regions = _cutout_regions(img, chosen)
+    cands: list[tuple[str, Image.Image]] = []
+
+    unm, unm_info = unmix_cutout(img, chosen, regions)
+    cands.append(("unmix", unm))
+    cands.append(("chroma-bg", despill(chroma_key(img, chosen), chosen)))
+    if color_dist(hex_to_rgb(chosen), hex_to_rgb(key_hex)) > 1.0:
+        # Lưới an toàn: nếu màu đo được sai thì key theo màu YÊU CẦU vẫn còn đó để thắng.
+        cands.append(("chroma-key", despill(chroma_key(img, key_hex), key_hex)))
+    if cutout is not None:
+        try:
+            ben = cutout(img)
+            if ben.mode != "RGBA":
+                ben = ben.convert("RGBA")
+            cands.append(("ben2", _erode_alpha(ben, 1)))
+        except Exception as exc:                                  # noqa: BLE001
+            cands.append(("ben2-loi", None))                      # ghi lại để báo cáo
+            del exc
+
+    table = []
+    ranked: list[tuple[float, str, Image.Image]] = []
+    for name, im in cands:
+        if im is None:
+            table.append({"method": name, "error": True})
+            continue
+        s = score_cutout(img, im, chosen, regions)
+        s["method"] = name
+        table.append(s)
+        if not s["disqualify"]:
+            ranked.append((s["score"], name, im))
+
+    table.sort(key=lambda t: (bool(t.get("error")), bool(t.get("disqualify")), t.get("score", 9e9)))
+    if ranked:
+        ranked.sort(key=lambda t: t[0])
+        win_score, win_name, win_img = ranked[0]
+    else:
+        # Mọi cách đều bị loại -> lấy cách điểm thấp nhất trong số không-lỗi và NÓI RA,
+        # không âm thầm trả ảnh rỗng. Cờ bad_* của postprocess vẫn sẽ bắt tiếp.
+        ok = [t for t in table if not t.get("error")]
+        win_name = ok[0]["method"] if ok else "unmix"
+        win_score = ok[0]["score"] if ok else float("nan")
+        win_img = dict(cands)[win_name] if win_name in dict(cands) else unm
+
+    report = {
+        "cutout_method": win_name,
+        "cutout_score": win_score,
+        "cutout_table": table,
+        "cutout_candidates": [n for n, _ in cands],
+        "bg_color_used": chosen,
+        "bg_source": why,
+        "bg_sampled_mode": sampled,
+        "bg_mode_share": share,
+        "band_w": regions["band_w"],
+        "unmix_info": unm_info,
+        "all_disqualified": not ranked,
+    }
+    return win_img, report
+
+
+def postprocess(
+    gen: Image.Image,
+    key_hex: str,
+    src: Image.Image | None = None,
+    size: tuple[int, int] | None = None,
+    cutout=None,
+    bg_hex: str | None = None,
+    multi: bool = True,
+    full_bleed: bool = False,
+    upscale=None,
+) -> tuple[Image.Image | None, dict]:
+    """Ảnh Gemini thô -> asset game dùng được ngay.
+
+    Mặc định BÁM GỐC: canvas = size của src, nội dung căn vào đúng bbox của src
+    -> thay 1-1 vào game, không phải chỉnh anchor/hitbox/layout.
+    Truyền `size` để ép ra kích thước khác (asset hoàn toàn mới).
+
+    `cutout`: hàm (Image -> RGBA) để TÁCH NỀN. Truyền vào thì dùng nó (vd BEN2
+    qua bgremove.remove_background) — segmentation ngữ nghĩa, không cần màu key,
+    không viền xanh. BỎ TRỐNG -> quay về chroma-key + despill như cũ (đường mặc
+    định, thuần, test offline được). `key_hex` vẫn cần cho despeckle/báo cáo.
+
+    `bg_hex`: màu nền THẬT đo từ bản sinh (sample_border_color). Truyền vào thì MỌI phép
+    dựa-trên-màu dùng nó thay cho `key_hex`: chroma_key, despill và lớp dọn nền sót. Đây là
+    thứ quyết định độ sạch — model gần như không bao giờ vẽ đúng màu key được yêu cầu (đo
+    thật: yêu cầu #00FF00, model vẽ #0CF508 và #0BD009), và key theo màu yêu cầu có thể để
+    lại NGUYÊN nền dưới dạng màng bán trong suốt. Bỏ trống -> dùng `key_hex` như cũ.
+
+    `multi` (MẶC ĐỊNH BẬT): chạy NHIỀU cách tách nền qua best_cutout() rồi lấy bản chấm
+    điểm tốt nhất, thay vì tin sẵn một cách. Không có cách nào thắng mọi ảnh — đo thật 10
+    cách trên 4 bản sinh: BEN2 hạng nhất ở asset rời nhưng ăn mất 8.99% chủ thể ở ảnh nền
+    full-bleed; chroma_key theo màu key yêu cầu để lại viền hồng thấy rõ; bề rộng dải AA
+    khác nhau 2px vs 7–8px tuỳ nguồn. `cutout` khi đó là MỘT ứng viên (không còn độc quyền).
+    Tắt (`multi=False`) khi chủ thể trong suốt thật (kính, khói) — fg_loss sẽ phạt oan.
+
+    `full_bleed`: BẬT cho ảnh NỀN tràn viền (background plate, thumbnail) — tranh phủ kín
+    khung, chủ thể CHẠM vành ảnh là đúng thiết kế. Nó tắt duy nhất cửa gác `border_impurity`,
+    KHÔNG tắt `bg_residue`/`coverage`/bộ chấm điểm.
+
+    VÌ SAO phải là THAM SỐ chứ không tự suy ra: `border_impurity` giả định vành ảnh toàn là
+    nền. Với ảnh nền full-bleed giả định đó sai (đo thật home_grass/gpt1.png: thảm cỏ tràn ra
+    vành dưới và hai vành bên) nên nó báo bad_background trên một bản tách nền HOÀN HẢO —
+    cast 0, bg_residue 0.0000 — và cả 4 bản sinh đều bị đánh hỏng. Đó không còn là "một lượt
+    sinh lại tốn kém" như docstring border_impurity chấp nhận, mà là chặn vĩnh viễn cả một
+    lớp asset. Nhưng KHÔNG suy ra được từ pixel: "thảm cỏ chạm vành dưới" và "mảng xám panel
+    chưa key chạm vành trên" đều là nội dung đục chạm vành, chỉ khác Ý ĐỊNH. Tỉ lệ vành mang
+    màu key cũng không tách được hai ca: đo tay 0.552 ở ca CẦN gác (test_postprocess_flags_
+    partial_background_failure) so với 0.225–0.390 ở ảnh nền cần TẮT gác — quá gần nhau để
+    đặt ngưỡng. Nên người gọi phải nói ra. Mặc định False giữ nguyên hành vi cũ.
+
+    `upscale`: hàm phóng 4x mảng HxWx3 uint8 (upscale.upscale_rgb). CHỈ dùng khi bản sinh
+    NHỎ HƠN khung đích — lúc đó LANCZOS chỉ trải mép ra cho mềm chứ không thêm được gì.
+    Cũng chạy nhiều cách rồi chấm điểm chọn (xem best_upscale). Bỏ trống -> LANCZOS như cũ.
+    """
+    bg_for_color = bg_hex or key_hex
+    multi_rep: dict | None = None
+    diag: Image.Image | None = None
+    if multi:
+        keyed, multi_rep = best_cutout(gen, key_hex, bg_hex=bg_hex, cutout=cutout)
+        bg_for_color = multi_rep["bg_color_used"]
+        # Ảnh CHẨN ĐOÁN, tách khỏi ảnh GIAO RA. Đây là điểm dễ hiểu sai nhất của khối này.
+        #
+        # Toàn bộ lớp cờ của postprocess đọc alpha theo NGỮ NGHĨA RAMP MỀM của chroma_key:
+        # "có nội dung nhưng không đục" (ALPHA_FLOOR < a < SOLID_ALPHA) chính là cách nó
+        # phát hiện chủ thể bóng ma, lỗ khoét giữa thân, và mảng nền chưa key. `unmix` lại
+        # cố ý cho alpha GẦN NHƯ NHỊ PHÂN — đúng cái làm nó sạch — nên nếu đo cờ trên đầu ra
+        # của nó thì mọi tín hiệu đó biến mất: đo thật, 4 test defect (viên ngọc giữa thân,
+        # bóng ma, mảng xám chưa key, hai-lỗi-cùng-lúc) đều tụt xuống status "ok".
+        #
+        # Nhưng các chỉ số đó trả lời câu "BẢN SINH có dùng được không?", không phải câu
+        # "thuật toán tách nền nào sạch hơn?" — chúng độc lập với việc sau đó ta cắt bằng gì.
+        # Nên: cờ đo trên bản chroma_key (giữ nguyên hợp đồng đời cũ), pixel giao ra lấy từ
+        # bản thắng điểm. `bg_residue` thì vẫn đo trên bản GIAO RA, vì nó hỏi đúng câu
+        # "ảnh mình sắp ghi ra có còn bẩn không".
+        diag = chroma_key(gen, bg_for_color)
+        impurity = None
+    elif cutout is not None:
+        # Đường BEN2: alpha đã là segmentation của chủ thể, không dính màu nền
+        # -> border_impurity (đo theo màu key) VÔ NGHĨA ở đây, ép 0 để không báo
+        # nhầm bad_background. Coverage>BAD_HIGH vẫn là cửa gác thật (segmentation
+        # trượt, phủ nguyên khung -> đục hết).
+        keyed = cutout(gen)
+        if keyed.mode != "RGBA":
+            keyed = keyed.convert("RGBA")
+        # BEN2 đôi khi gộp cả dải anti-alias (nơi Gemini blend chủ thể với nền
+        # key) vào mask ĐỤC -> viền xanh mảnh bám theo silhouette, rõ nhất trên chủ
+        # thể sáng/viền trắng như logo. despill CHỈ chạm pixel bán trong suốt nên
+        # KHÔNG dọn được dải đục này. Bào 1px alpha (min-filter) cắt đúng vành ngoài
+        # đó — an toàn màu (không declamp xanh nên hoa xanh/teal không hề hấn), chỉ
+        # thu silhouette 1px. Sau đó despill dọn nốt mép mềm mới lộ ra.
+        keyed = _erode_alpha(keyed, 1)
+        impurity = 0.0
+    else:
+        keyed = chroma_key(gen, bg_for_color)
+        impurity = None   # tính bằng border_impurity bên dưới
+
+    # Dọn nền SÓT rồi ĐO độ bẩn — cả hai việc phải làm TRƯỚC despill. despill kéo kênh màu key
+    # xuống, nên sau nó nền sót không còn mang màu nền nữa và mọi phép so-màu đều mù: đo thật
+    # trên ca nền sống sót 100% khung, chạy sau despill thì bg_residue báo 0.0000 và lớp dọn xoá
+    # được 0 px. Đây cũng là lý do despill KHÔNG còn nằm chung dòng với chroma_key/cutout ở trên.
+    keyed, bg_killed = strip_bg_residue(keyed, bg_for_color)
+    residue = bg_residue(keyed, bg_for_color)
+    if not multi:
+        keyed = despill(keyed, bg_for_color)
+    # Ở đường multi TUYỆT ĐỐI KHÔNG despill lần nữa. Hai lý do, cả hai đều làm ảnh XẤU ĐI:
+    #   1. Ứng viên nào CẦN despill thì đã được despill ngay trong best_cutout() rồi
+    #      (`chroma-bg`, `chroma-key`) — chạy lần hai là kẹp kênh hai lần.
+    #   2. Với bản `unmix` thắng, F đã là NGHIỆM CHÍNH XÁC của phương trình ghép ảnh.
+    #      despill chỉ chạm pixel alpha<255 — tức đúng dải AA mà unmix vừa giải xong — nên
+    #      nó sẽ kéo nghiệm đúng lệch trở lại về phía heuristic kẹp kênh. Đo thật: sai màu
+    #      tiền cảnh 0.44/255 sau unmix, chạy thêm despill thì vọt lên hàng chục.
+
+    # Despeckle TRƯỚC khi đo bất cứ chỉ số nào: watermark ✦ của Gemini là một mảng ĐỤC HOÀN
+    # TOÀN ~580px ở góc dưới-phải mọi ảnh nó sinh. Để nguyên thì nó vừa hiện thành chấm xanh
+    # trong asset, vừa làm lệch coverage/solid_ratio/bbox/hole_ratio. Đo sau khi dọn mới đúng.
+    keyed, speckles = despeckle(keyed)
+    keyed, wm = strip_gemini_watermark(keyed)   # diệt hẳn dấu ✦ ở góc dưới-phải nếu despeckle sót
+    speckles += wm
+
+    if impurity is None:
+        impurity = border_impurity(gen, bg_for_color)
+
+    if diag is not None:
+        # Cùng chuỗi dọn dẹp như bản giao ra, để cờ đo trên ảnh tương đương — chỉ khác là
+        # bản này CÓ despill (đúng ngữ nghĩa đời cũ mà lớp cờ được thiết kế quanh nó).
+        diag, _ = strip_bg_residue(diag, bg_for_color)
+        diag = despill(diag, bg_for_color)
+        diag, _ = despeckle(diag)
+        diag, _ = strip_gemini_watermark(diag)
+        metric_img = diag
+    else:
+        metric_img = keyed
+
+    coverage = alpha_coverage(metric_img)
+    solid = solid_ratio(metric_img)
+    bbox = content_bbox(metric_img)
+    holes = hole_ratio(metric_img, bbox)
+
+    # bbox dùng để CẮT ảnh giao ra thì phải lấy từ chính ảnh giao ra, không phải từ bản
+    # chẩn đoán: hai bản có silhouette khác nhau (unmix giữ lại vùng mà chroma_key khoét
+    # thủng), cắt theo bbox của bản kia sẽ lệch khung.
+    out_bbox = content_bbox(keyed) if diag is not None else bbox
+
+    flags: list[str] = []
+    # `residue` là cửa gác THẬT cho đường BEN2 (ở đó impurity bị ép 0 vì đo theo vành ảnh gốc
+    # là vô nghĩa). Đo trên ảnh ĐÃ tách nên bắt được đúng thứ trước đây trôi lọt.
+    impurity_gates = not full_bleed          # xem docstring `full_bleed`
+    if ((impurity_gates and impurity > BAD_BORDER_DIST)
+            or coverage > BAD_HIGH or residue > BAD_BG_RESIDUE):
+        flags.append("bad_background")
+    # Ở đường multi, bộ chấm điểm là một cửa gác ĐỘC LẬP: mọi ứng viên đều bị loại nghĩa là
+    # KHÔNG cách nào tách sạch được bản sinh này (nền sót, hoặc ăn chủ thể, hoặc phủ bất
+    # thường) -> đó là lỗi của BẢN SINH, cần sinh lại, chứ không phải chọn bản đỡ tệ nhất
+    # rồi im lặng đi tiếp.
+    elif multi_rep is not None and multi_rep.get("all_disqualified"):
+        flags.append("bad_background")
+
+    # Finding I3: coverage thấp MỘT MÌNH không còn nghĩa là "hỏng" — icon/line-art nhỏ
+    # (vd nút X 12px nét) đo được coverage=0.0161 < BAD_LOW nhưng solid_ratio=1.0, một
+    # bản sinh HOÀN HẢO bị bản cũ vứt bỏ (trả None) vì "nhỏ" bị đánh đồng với "hỏng", và
+    # retry đổi màu key không thể cứu ca này vì màu key chưa từng là vấn đề. bad_subject
+    # giờ chỉ bật khi chủ thể THẬT SỰ bị phá huỷ: bbox rỗng hoàn toàn, HOẶC vừa nhỏ vừa
+    # không đục (ăn thủng thành bóng ma mờ). "Nhỏ nhưng đặc" không phải lỗi.
+    bad_subject = bbox is None or (coverage < BAD_LOW and solid < BAD_SOLID_RATIO)
+    if bad_subject:
+        flags.append("bad_subject")
+    elif coverage < BAD_LOW:
+        flags.append("sparse")   # thông tin, KHÔNG phải lỗi — xem docstring ở trên
+
+    # Lưu ý: nếu bad_background đã lên tiếng thì solid_ratio KHÔNG còn đáng tin — mảng nền
+    # hỏng (bóng/gradient/viền chưa key) tự nó đã đục, bơm phồng solid_ratio giả, không phản
+    # ánh chủ thể thật (xem test_postprocess_flags_partial_background_failure). ĐỪNG bỏ
+    # border_impurity đi với lý do "solid_ratio đã bắt được rồi" — nó không bắt được ca này.
+    if solid < BAD_SOLID_RATIO:
+        flags.append("bad_translucent")
+
+    # Finding I2: cờ THAM KHẢO, không phải gate cứng — xem docstring hole_ratio(). KHÔNG
+    # ép bad_subject, KHÔNG trả None chỉ vì bad_holes — contact sheet mới là cửa gác thật.
+    if bbox is not None and holes > BAD_HOLE_RATIO:
+        flags.append("bad_holes")
+
+    report: dict = {
+        "status": flags[0] if flags else "ok",   # nặng nhất trước; xem thứ tự append ở trên
+        "flags": flags,                          # BÁO ĐỦ: một bản sinh có thể hỏng nhiều kiểu
+        "coverage": coverage,
+        "solid_ratio": solid,     # luôn báo cáo, kể cả khi ok — người duyệt cần thấy con số
+        "border_impurity": impurity,
+        "bg_residue": residue,        # tỉ lệ pixel đục còn mang màu nền SAU khi dọn
+        "bg_px_removed": bg_killed,   # số px nền sót mà strip_bg_residue đã xoá
+        "bg_color_used": bg_for_color,   # màu thực sự dùng để key/despill/dọn sót
+        "hole_ratio": holes,      # luôn báo cáo, kể cả khi ok — xem hole_ratio() (advisory)
+        "speckles_removed": speckles,   # >0 là bình thường: watermark Gemini luôn bị dọn
+        "key": key_hex,
+        "full_bleed": full_bleed,
+        # Nói RÕ border_impurity có quyền phủ quyết hay không, để người đọc report không phải
+        # đoán vì sao một impurity cao lại không sinh ra cờ nào.
+        "impurity_gated": impurity_gates,
+    }
+    if multi_rep is not None:
+        # Báo cáo ĐỦ bảng điểm, kể cả ứng viên bị loại: người duyệt cần thấy VÌ SAO cách này
+        # thắng, chứ không chỉ thấy tên nó.
+        report.update({k: multi_rep[k] for k in (
+            "cutout_method", "cutout_score", "cutout_table", "cutout_candidates",
+            "bg_source", "bg_sampled_mode", "bg_mode_share", "band_w", "all_disqualified",
+        )})
+        # coverage/solid_ratio ở trên đo trên bản CHẨN ĐOÁN (xem khối diag). Hai số dưới đây
+        # đo trên bản THỰC SỰ GIAO RA, để chênh lệch giữa chúng không bị che đi.
+        report["out_coverage"] = alpha_coverage(keyed)
+        report["out_solid_ratio"] = solid_ratio(keyed)
+
+    if bad_subject:
+        report["status"] = "bad_subject"
+        return None, report
+
+    if size is not None:
+        canvas_size = size
+        target_box = (0, 0, size[0], size[1])
+    elif src is not None:
+        canvas_size = src.size
+        target_box = content_bbox(src) or (0, 0, src.size[0], src.size[1])
+    else:
+        raise ValueError("postprocess() cần `src` hoặc `size`")
+
+    report["size"] = canvas_size
+    report["target_box"] = target_box
+    out = fit_into(keyed.crop(out_bbox or bbox), canvas_size, target_box,
+                   upscale=upscale, report=report)
+    return out, report
+
+
+LABEL_H = 20
+SHEET_LIGHT = (240, 240, 240)
+SHEET_DARK = (28, 28, 32)
+SHEET_CHECKER = ((205, 205, 205), (170, 170, 170))
+CHECKER_SIZE = 8
+
+
+# ── Thumbnail cửa hàng: 3 tỉ lệ cố định ─────────────────────────────────────────────────
+# Model sinh ảnh KHÔNG cho chọn kích thước đầu ra — nó trả size riêng của nó. Đo thật trên
+# Gemini web: yêu cầu dọc → 864x1216 (0.7105), ngang → 1376x768 (1.7917), vuông → 1024x1024
+# (1.0000). Tức nó TÔN TRỌNG HƯỚNG và rơi rất sát mục tiêu, nên đường đi đúng là: sinh ở tỉ lệ
+# gần nhất → cắt bù phần lệch (đo được ≤1%) → resize về ĐÚNG số pixel yêu cầu.
+# Giá trị dưới đây theo yêu cầu cửa hàng: 1:1 tối thiểu 512x512, 5:7 đúng 540x756,
+# 16:9 tối thiểu 1280x720. Với 1:1 giao 1024 thay vì 512 vì nguồn vốn đã 1024 — hạ xuống 512
+# là bỏ chi tiết không lý do (yêu cầu là SÀN, không phải trần).
+THUMB_PRESETS: dict[str, tuple[int, int]] = {
+    "1:1": (1024, 1024),
+    "5:7": (540, 756),
+    "16:9": (1280, 720),
+}
+
+
+def fit_thumb(
+    img: Image.Image, target: tuple[int, int], anchor: str = "center", upscale=None
+) -> tuple[Image.Image, dict]:
+    """Cắt về đúng tỉ lệ `target` rồi resize về ĐÚNG số pixel đó. Trả (ảnh, info).
+
+    KHÔNG tách nền, KHÔNG bám bbox asset gốc — thumbnail là tranh full-bleed, khác hẳn đường
+    restyle asset. Đừng đưa ảnh thumb qua postprocess/process_raws.
+
+    `anchor` quyết định giữ phần nào khi cắt: "center" (mặc định), "top", "bottom", "left",
+    "right". Thumb dọc hay đặt logo/tiêu đề ở trên → dùng "top" cho chắc.
+
+    info: src, target, crop (hộp đã cắt), lost_frac (tỉ lệ pixel bị cắt bỏ), scale,
+    upscaled (True nếu phải PHÓNG TO — ảnh sẽ mềm, nên biết mà sinh lại to hơn).
+    """
+    tw, th = int(target[0]), int(target[1])
+    if tw <= 0 or th <= 0:
+        raise ValueError(f"target không hợp lệ: {target!r}")
+    w, h = img.size
+    ta, sa = tw / th, w / h
+
+    if sa > ta:                      # nguồn RỘNG hơn mục tiêu -> cắt bớt chiều ngang
+        cw, ch = max(1, round(h * ta)), h
+    else:                            # nguồn CAO hơn -> cắt bớt chiều dọc
+        cw, ch = w, max(1, round(w / ta))
+    cw, ch = min(cw, w), min(ch, h)
+
+    if anchor == "left":
+        x0, y0 = 0, (h - ch) // 2
+    elif anchor == "right":
+        x0, y0 = w - cw, (h - ch) // 2
+    elif anchor == "top":
+        x0, y0 = (w - cw) // 2, 0
+    elif anchor == "bottom":
+        x0, y0 = (w - cw) // 2, h - ch
+    else:
+        x0, y0 = (w - cw) // 2, (h - ch) // 2
+
+    box = (x0, y0, x0 + cw, y0 + ch)
+    out = img.crop(box)
+    info = {
+        "src": [w, h],
+        "target": [tw, th],
+        "crop": list(box),
+        "lost_frac": 1.0 - (cw * ch) / float(w * h),
+        "scale": tw / float(cw),
+        "upscaled": tw > cw or th > ch,
+    }
+    if out.size != (tw, th):
+        if info["upscaled"] and tw / float(cw) > UPSCALE_MIN_GAIN:
+            out, up_rep = best_upscale(out, (tw, th), backend=upscale)
+            info.update(up_rep)
+        else:
+            out = out.resize((tw, th), Image.LANCZOS)
+    return out, info
+
+
+def _checker(size: tuple[int, int]) -> Image.Image:
+    """Nền caro — kiểu 'ô cờ' của Photoshop. Lộ rõ pixel bán trong suốt."""
+    w, h = size
+    a, b = SHEET_CHECKER
+    tile = np.zeros((h, w, 3), dtype=np.uint8)
+    yy, xx = np.mgrid[0:h, 0:w]
+    odd = ((xx // CHECKER_SIZE) + (yy // CHECKER_SIZE)) % 2 == 1
+    tile[...] = a
+    tile[odd] = b
+    return Image.fromarray(tile, "RGB")
+
+
+def _bg(size: tuple[int, int], row: int) -> Image.Image:
+    if row == 0:
+        return Image.new("RGB", size, SHEET_LIGHT)
+    if row == 1:
+        return Image.new("RGB", size, SHEET_DARK)
+    return _checker(size)
+
+
+def _contain(img: Image.Image, box: int) -> Image.Image:
+    w, h = img.size
+    s = min(box / max(1, w), box / max(1, h))
+    return img.resize((max(1, round(w * s)), max(1, round(h * s))), Image.LANCZOS)
+
+
+def make_sheet(
+    cells: list[tuple[str, Image.Image]], cell: int = 160, pad: int = 12
+) -> Image.Image:
+    """Lưới so sánh: mỗi cột 1 ảnh, mỗi hàng 1 nền (sáng / tối / caro).
+
+    Ba nền là có chủ đích: nền sáng lộ viền tối, nền tối lộ viền sáng và spill,
+    nền caro lộ vùng bán trong suốt. Một nền thôi là sẽ bỏ sót lỗi.
+    """
+    n = max(1, len(cells))
+    width = n * (cell + pad) + pad
+    height = 3 * (cell + pad) + pad + LABEL_H
+
+    sheet = Image.new("RGB", (width, height), (255, 255, 255))
+    draw = ImageDraw.Draw(sheet)
+
+    for col, (label, img) in enumerate(cells):
+        x = pad + col * (cell + pad)
+        draw.text((x, 4), label[:22], fill=(0, 0, 0))
+
+        thumb = _contain(img.convert("RGBA"), cell)
+        for row in range(3):
+            y = LABEL_H + pad + row * (cell + pad)
+            tile = _bg((cell, cell), row)
+            tile.paste(thumb, ((cell - thumb.width) // 2, (cell - thumb.height) // 2), thumb)
+            sheet.paste(tile, (x, y))
+
+    return sheet
+
+
+def _png_b64(img: Image.Image) -> str:
+    """Ảnh -> chuỗi base64 PNG (RGBA) để nhúng thẳng vào HTML (self-contained)."""
+    buf = io.BytesIO()
+    img.convert("RGBA").save(buf, "PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def compare_sheet(
+    groups: list[tuple[str, Image.Image | None, list[tuple[str, Image.Image]]]],
+    cell: int = 240,
+) -> str:
+    """Trang HTML ĐỐI CHIẾU gốc↔mới, tự chứa. Đây là bản giao cho user sau MỖI lượt thiết kế.
+
+    Khác `web_sheet` (lưới thẻ phẳng, mọi ảnh ngang hàng): ở đây ảnh được NHÓM THEO ASSET,
+    bản gốc nằm ngay cạnh các biến thể của chính nó, và mỗi thẻ biến thể lật được về gốc
+    NGAY TẠI CHỖ (nhấn giữ; nháy đúp để khoá). Đặt chồng đúng một vị trí và một kích thước
+    là cách duy nhất thấy được lệch hình dạng/tỉ lệ nhỏ — hai thẻ nằm cạnh nhau thì mắt
+    không bắt được. Lô nhiều asset mà không nhóm lại thì user phải tự nhớ ảnh nào của asset
+    nào; đó là lý do gom nhóm chứ không phải để trang trí.
+
+    `groups`: list (tên asset, ảnh gốc | None, [(nhãn, ảnh biến thể), ...]).
+        Gốc = None thì thẻ chỉ hiện biến thể, không có nút lật (vd cells screen-sheet vốn
+        không có asset gốc 1-1).
+
+    Ảnh gốc được nhúng MỘT LẦN cho mỗi nhóm rồi gán bằng JS lúc lật, chứ không nhúng lại
+    trong từng thẻ — một lô 10 asset × 4 biến thể mà nhúng lặp thì file phình vô ích.
+    """
+    origs: list[str] = []
+    sections: list[str] = []
+
+    for gi, (name, orig, variants) in enumerate(groups):
+        nm = _html.escape(str(name))[:60]
+        cards = []
+
+        if orig is not None:
+            origs.append(_png_b64(orig))
+            ow, oh = orig.size
+            cards.append(
+                '<figure class="card is-orig">'
+                f'<figcaption><span class="lbl">GỐC</span>'
+                f'<span class="dim">{ow}×{oh}</span></figcaption>'
+                f'<div class="stage"><img src="data:image/png;base64,{origs[-1]}" '
+                f'alt="{nm} gốc" loading="lazy"></div>'
+                "</figure>"
+            )
+        else:
+            origs.append("")
+
+        for label, img in variants:
+            w, h = img.size
+            lbl = _html.escape(str(label))[:40]
+            flip = (
+                f'<img class="ov" data-g="{gi}" alt="" loading="lazy">'
+                if orig is not None else ""
+            )
+            cards.append(
+                f'<figure class="card{" can-flip" if orig is not None else ""}" data-g="{gi}">'
+                f'<figcaption><span class="lbl">{lbl}</span>'
+                f'<span class="state"></span>'
+                f'<span class="dim">{w}×{h}</span></figcaption>'
+                f'<div class="stage"><img class="nw" '
+                f'src="data:image/png;base64,{_png_b64(img)}" alt="{lbl}" loading="lazy">'
+                f"{flip}</div>"
+                "</figure>"
+            )
+
+        sections.append(
+            f'<section class="grp"><h2>{nm}'
+            f'<span class="cnt">{len(variants)} bản</span></h2>'
+            f'<div class="row">{"".join(cards)}</div></section>'
+        )
+
+    doc = """<!doctype html><html lang="vi"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>game-art — đối chiếu gốc / mới</title>
+<style>
+ :root{--cell:__CELL__px;--custom:#3aa675;color-scheme:dark light}
+ *{box-sizing:border-box}
+ body{margin:0;background:#0d1117;color:#e6edf3;font:14px/1.5 system-ui,Segoe UI,sans-serif}
+ header{position:sticky;top:0;z-index:5;background:#161b22e6;backdrop-filter:blur(8px);
+   border-bottom:1px solid #30363d;padding:12px 20px;display:flex;gap:14px;align-items:center;flex-wrap:wrap}
+ h1{font-size:16px;margin:0 12px 0 0}
+ .seg{display:inline-flex;border:1px solid #30363d;border-radius:8px;overflow:hidden}
+ .seg button{background:#0d1117;color:#adbac7;border:0;padding:6px 12px;cursor:pointer;font:inherit}
+ .seg button+button{border-left:1px solid #30363d}
+ .seg button.on{background:#1f6feb;color:#fff}
+ label.ctl{display:inline-flex;gap:6px;align-items:center;color:#8b949e}
+ input[type=range]{width:130px}
+ input[type=color]{width:30px;height:26px;border:1px solid #30363d;border-radius:6px;background:none;padding:0}
+ .hint{color:#8b949e;font-size:12px;margin-left:auto}
+ .hint kbd{background:#21262d;border:1px solid #30363d;border-radius:4px;padding:1px 5px;font:inherit}
+ main{padding:20px}
+ .grp{margin:0 0 26px}
+ .grp h2{font-size:14px;margin:0 0 10px;padding-bottom:7px;border-bottom:1px solid #30363d;
+   display:flex;align-items:center;gap:10px;color:#e6edf3}
+ .cnt{color:#8b949e;font-weight:400;font-size:12px}
+ .row{display:grid;gap:14px;grid-template-columns:repeat(auto-fill,minmax(var(--cell),1fr))}
+ .card{background:#161b22;border:1px solid #30363d;border-radius:10px;overflow:hidden}
+ .card.is-orig{border-color:#8957e5}
+ .card.can-flip{cursor:pointer;user-select:none}
+ figcaption{display:flex;justify-content:space-between;align-items:center;gap:8px;
+   padding:7px 10px;font-size:12px;border-bottom:1px solid #30363d}
+ .lbl{font-weight:600;color:#e6edf3}
+ .is-orig .lbl{color:#d2a8ff}
+ .dim{color:#8b949e;font-variant-numeric:tabular-nums}
+ .state{margin-left:auto;font-size:11px;color:#8b949e}
+ .showing-orig .state{color:#d2a8ff;font-weight:600}
+ .stage{position:relative;height:var(--cell);display:flex;align-items:center;justify-content:center;padding:8px}
+ .stage img{max-width:100%;max-height:100%;object-fit:contain}
+ .ov{position:absolute;inset:8px;margin:auto;display:none}
+ .showing-orig .nw{visibility:hidden}
+ .showing-orig .ov{display:block}
+ [data-bg=light] .stage{background:#f2f2f2}
+ [data-bg=dark] .stage{background:#181818}
+ [data-bg=custom] .stage{background:var(--custom)}
+ [data-bg=checker] .stage{background-color:#fff;background-image:
+   linear-gradient(45deg,#c9c9c9 25%,transparent 25%,transparent 75%,#c9c9c9 75%),
+   linear-gradient(45deg,#c9c9c9 25%,transparent 25%,transparent 75%,#c9c9c9 75%);
+   background-size:22px 22px;background-position:0 0,11px 11px}
+</style></head>
+<body data-bg="checker">
+ <header>
+  <h1>\U0001f3ae game-art — đối chiếu gốc / mới</h1>
+  <div class="seg" id="bgseg">
+   <button data-b="checker" class="on">Caro</button>
+   <button data-b="light">Sáng</button>
+   <button data-b="dark">Tối</button>
+   <button data-b="custom">Màu</button>
+  </div>
+  <label class="ctl">Nền <input type="color" id="pick" value="#3aa675"></label>
+  <label class="ctl">Zoom <input type="range" id="zoom" min="140" max="560" value="__CELL__"></label>
+  <div class="seg"><button id="allorig">Xem tất cả bản GỐC</button></div>
+  <div class="hint"><kbd>nhấn giữ</kbd> lật về gốc · <kbd>nháy đúp</kbd> khoá</div>
+ </header>
+ <main>
+__SECTIONS__
+ </main>
+ <script>
+  var ORIG=__ORIGS__;
+  var body=document.body,root=document.documentElement;
+  document.querySelectorAll('#bgseg button').forEach(function(b){
+    b.onclick=function(){
+      document.querySelectorAll('#bgseg button').forEach(function(x){x.classList.remove('on')});
+      b.classList.add('on'); body.dataset.bg=b.dataset.b;
+    };
+  });
+  var pick=document.getElementById('pick');
+  pick.oninput=function(){
+    root.style.setProperty('--custom',pick.value);
+    body.dataset.bg='custom';
+    document.querySelectorAll('#bgseg button').forEach(function(x){x.classList.toggle('on',x.dataset.b==='custom')});
+  };
+  document.getElementById('zoom').oninput=function(){root.style.setProperty('--cell',this.value+'px')};
+
+  // Ảnh gốc chỉ gán src lúc CẦN, từ bảng ORIG nhúng một lần mỗi nhóm — tránh lặp base64.
+  function fill(card){
+    var ov=card.querySelector('.ov');
+    if(ov && !ov.getAttribute('src')) ov.src=ORIG[card.dataset.g];
+  }
+  function show(card,on){
+    if(!card.classList.contains('can-flip')) return;
+    fill(card);
+    card.classList.toggle('showing-orig',on);
+    var s=card.querySelector('.state'); if(s) s.textContent=on?'đang xem GỐC':'';
+  }
+  document.querySelectorAll('.card.can-flip').forEach(function(card){
+    card.addEventListener('pointerdown',function(){show(card,true)});
+    card.addEventListener('pointerup',function(){if(card.dataset.lock!=='1')show(card,false)});
+    card.addEventListener('pointerleave',function(){if(card.dataset.lock!=='1')show(card,false)});
+    card.addEventListener('dblclick',function(){
+      card.dataset.lock=card.dataset.lock==='1'?'0':'1';
+      show(card,card.dataset.lock==='1');
+    });
+  });
+  var all=false,btn=document.getElementById('allorig');
+  btn.onclick=function(){
+    all=!all; btn.classList.toggle('on',all);
+    btn.textContent=all?'Xem tất cả bản MỚI':'Xem tất cả bản GỐC';
+    document.querySelectorAll('.card.can-flip').forEach(function(c){
+      c.dataset.lock=all?'1':'0'; show(c,all);
+    });
+  };
+ </script>
+</body></html>"""
+    return (doc.replace("__CELL__", str(int(cell)))
+               .replace("__SECTIONS__", "\n".join(sections))
+               .replace("__ORIGS__", _json.dumps(
+                   {i: (f"data:image/png;base64,{b}" if b else "") for i, b in enumerate(origs)})))
+
+
+def web_sheet(cells: list[tuple[str, Image.Image]], cell: int = 240) -> str:
+    """Trang HTML DUYỆT BẰNG MẮT, tự chứa (nhúng base64 PNG) — thay contact sheet tĩnh.
+
+    Ưu điểm so với PNG: đổi nền TRỰC TIẾP (sáng/tối/caro/màu tùy chọn) để soi mép cutout
+    và vùng bán trong suốt, kéo slider phóng to từng ảnh, không cần mở Photoshop. Một file
+    HTML duy nhất, mở bằng trình duyệt nào cũng chạy, không phụ thuộc file ngoài.
+
+    `cells`: list (nhãn, ảnh RGBA) — vd [("original", src), ("v1", var1), ...].
+    """
+    cards = []
+    for label, img in cells:
+        w, h = img.size
+        lbl = _html.escape(str(label))[:40]
+        cards.append(
+            '<figure class="card">'
+            f'<figcaption><span class="lbl">{lbl}</span>'
+            f'<span class="dim">{w}×{h}</span></figcaption>'
+            f'<div class="stage"><img src="data:image/png;base64,{_png_b64(img)}" '
+            f'alt="{lbl}" loading="lazy"></div>'
+            "</figure>"
+        )
+    grid = "\n".join(cards)
+
+    doc = """<!doctype html><html lang="vi"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>game-art — review cutout</title>
+<style>
+ :root{--cell:__CELL__px;--custom:#3aa675;color-scheme:dark light}
+ *{box-sizing:border-box}
+ body{margin:0;background:#0d1117;color:#e6edf3;font:14px/1.5 system-ui,Segoe UI,sans-serif}
+ header{position:sticky;top:0;z-index:5;background:#161b22e6;backdrop-filter:blur(8px);
+   border-bottom:1px solid #30363d;padding:12px 20px;display:flex;gap:14px;align-items:center;flex-wrap:wrap}
+ h1{font-size:16px;margin:0 12px 0 0}
+ .seg{display:inline-flex;border:1px solid #30363d;border-radius:8px;overflow:hidden}
+ .seg button{background:#0d1117;color:#adbac7;border:0;padding:6px 12px;cursor:pointer;font:inherit}
+ .seg button+button{border-left:1px solid #30363d}
+ .seg button.on{background:#1f6feb;color:#fff}
+ label.ctl{display:inline-flex;gap:6px;align-items:center;color:#8b949e}
+ input[type=range]{width:130px}
+ input[type=color]{width:30px;height:26px;border:1px solid #30363d;border-radius:6px;background:none;padding:0}
+ main{padding:20px;display:grid;gap:16px;grid-template-columns:repeat(auto-fill,minmax(var(--cell),1fr))}
+ .card{background:#161b22;border:1px solid #30363d;border-radius:10px;overflow:hidden}
+ figcaption{display:flex;justify-content:space-between;align-items:center;padding:7px 10px;font-size:12px;border-bottom:1px solid #30363d}
+ .lbl{font-weight:600;color:#e6edf3}
+ .dim{color:#8b949e;font-variant-numeric:tabular-nums}
+ .stage{height:var(--cell);display:flex;align-items:center;justify-content:center;padding:8px}
+ .stage img{max-width:100%;max-height:100%;object-fit:contain;image-rendering:auto}
+ [data-bg=light] .stage{background:#f2f2f2}
+ [data-bg=dark] .stage{background:#181818}
+ [data-bg=custom] .stage{background:var(--custom)}
+ [data-bg=checker] .stage{background-color:#fff;background-image:
+   linear-gradient(45deg,#c9c9c9 25%,transparent 25%,transparent 75%,#c9c9c9 75%),
+   linear-gradient(45deg,#c9c9c9 25%,transparent 25%,transparent 75%,#c9c9c9 75%);
+   background-size:22px 22px;background-position:0 0,11px 11px}
+</style></head>
+<body data-bg="checker">
+ <header>
+  <h1>\U0001f3ae game-art — review</h1>
+  <div class="seg" id="bgseg">
+   <button data-b="checker" class="on">Caro</button>
+   <button data-b="light">Sáng</button>
+   <button data-b="dark">Tối</button>
+   <button data-b="custom">Màu</button>
+  </div>
+  <label class="ctl">Nền <input type="color" id="pick" value="#3aa675"></label>
+  <label class="ctl">Zoom <input type="range" id="zoom" min="140" max="560" value="__CELL__"></label>
+ </header>
+ <main id="grid">
+__GRID__
+ </main>
+ <script>
+  var body=document.body,root=document.documentElement;
+  document.querySelectorAll('#bgseg button').forEach(function(b){
+    b.onclick=function(){
+      document.querySelectorAll('#bgseg button').forEach(function(x){x.classList.remove('on')});
+      b.classList.add('on'); body.dataset.bg=b.dataset.b;
+    };
+  });
+  var pick=document.getElementById('pick');
+  pick.oninput=function(){
+    root.style.setProperty('--custom',pick.value);
+    body.dataset.bg='custom';
+    document.querySelectorAll('#bgseg button').forEach(function(x){x.classList.toggle('on',x.dataset.b==='custom')});
+  };
+  document.getElementById('zoom').oninput=function(){root.style.setProperty('--cell',this.value+'px')};
+ </script>
+</body></html>"""
+    return doc.replace("__CELL__", str(int(cell))).replace("__GRID__", grid)