@quybt93/pcgf 0.0.1

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

@@ -0,0 +1,1647 @@
+"""Test cho imglib. KHÔNG dùng pytest (môi trường không có).
+Chạy: python test_imglib.py
+"""
+import sys
+import traceback
+from PIL import Image, ImageDraw, ImageFilter
+import numpy as np
+
+import imglib as L
+
+
+def _solid(size, rgba):
+    return Image.new("RGBA", size, rgba)
+
+
+def test_hex_roundtrip():
+    assert L.hex_to_rgb("#00FF00") == (0, 255, 0)
+    assert L.hex_to_rgb("00ff00") == (0, 255, 0)
+    assert L.rgb_to_hex((0, 255, 0)) == "#00FF00"
+
+
+def test_color_dist_zero_for_same_color():
+    assert L.color_dist((10, 20, 30), (10, 20, 30)) == 0.0
+
+
+def test_color_dist_green_vs_white_is_large():
+    assert L.color_dist((0, 255, 0), (255, 255, 255)) > 400
+
+
+def test_dist_map_agrees_with_color_dist():
+    """_dist_map() là bản vector hoá của color_dist() — mọi ngưỡng trong hệ thống
+    (t_low/t_high của chroma_key, BAD_BORDER_DIST, GREEN_SAFE_THRESHOLD/MIN_KEY_MARGIN)
+    đều giả định hai hàm cho ra CÙNG một con số trên cùng một cặp màu. Không có test nào
+    khoá điều đó lại trước đây — một thay đổi vô tình làm lệch một trong hai hàm sẽ khiến
+    mọi ngưỡng hiệu chỉnh bằng color_dist() không còn khớp với dữ liệu _dist_map() thực sự
+    dùng để quyết định alpha/impurity, mà không test nào bắt được.
+    """
+    key = (0, 255, 0)
+    samples = [
+        (0, 255, 0), (255, 255, 255), (200, 30, 40), (128, 190, 128),
+        (255, 0, 255), (0, 0, 0), (10, 250, 10), (140, 70, 50),
+    ]
+    for c in samples:
+        scalar = L.color_dist(c, key)
+        vec = L._dist_map(np.array([[c]], dtype=np.uint8), key)[0, 0]
+        assert abs(scalar - vec) < 1e-6, f"color_dist={scalar} != _dist_map={vec} cho {c}"
+
+
+def test_extract_palette_finds_dominant_color():
+    img = _solid((20, 20), (200, 30, 40, 255))
+    pal = L.extract_palette(img, n=4)
+    assert pal[0][0] == "#C81E28"
+    assert pal[0][1] > 0.99
+
+
+def test_extract_palette_ignores_transparent_pixels():
+    img = Image.new("RGBA", (20, 20), (0, 255, 0, 0))   # xanh lá nhưng TRONG SUỐT
+    img.paste((200, 30, 40, 255), (5, 5, 15, 15))
+    hexes = [h for h, _ in L.extract_palette(img, n=4)]
+    assert "#00FF00" not in hexes
+    assert "#C81E28" in hexes
+
+
+def test_extract_palette_empty_for_fully_transparent():
+    assert L.extract_palette(Image.new("RGBA", (8, 8), (0, 0, 0, 0))) == []
+
+
+def test_pick_key_prefers_green_when_asset_has_no_green():
+    img = _solid((16, 16), (200, 30, 40, 255))          # đỏ
+    key, margin = L.pick_key_color(img)
+    assert key == "#00FF00"
+    assert margin > L.GREEN_SAFE_THRESHOLD
+
+
+def test_pick_key_avoids_green_when_asset_is_green():
+    img = _solid((16, 16), (0, 200, 0, 255))            # xanh lá đậm — sát màu key
+    key, _ = L.pick_key_color(img)
+    assert key != "#00FF00"
+    assert key in L.KEY_CANDIDATES
+
+
+def test_pick_key_falls_back_to_green_when_image_empty():
+    key, _ = L.pick_key_color(Image.new("RGBA", (8, 8), (0, 0, 0, 0)))
+    assert key == "#00FF00"
+
+
+def test_pick_key_avoids_green_even_when_green_has_largest_raw_margin():
+    """Regression test for Finding 1: green must be excluded from fallback selection.
+
+    Multi-hue asset where extracted palette has colors near magenta, cyan, and blue
+    (making those candidates unsafe with small margins) plus dark green (making green
+    unsafe with margin ~110 < GREEN_SAFE_THRESHOLD). Green has largest margin among
+    candidates, but fallback must exclude it and pick a non-green candidate.
+    """
+    img = Image.new("RGBA", (20, 20), (0, 200, 0, 255))    # dark green base
+    img.paste((255, 0, 200, 255), (0, 0, 5, 20))    # magenta-ish
+    img.paste((0, 255, 200, 255), (5, 0, 10, 20))   # cyan-ish
+    img.paste((0, 0, 255, 255), (10, 0, 15, 20))    # blue
+
+    key, margin = L.pick_key_color(img)
+    # The function must NOT return green, even though green margin (~110) is largest.
+    # The fallback must exclude green and pick among remaining candidates.
+    assert key != "#00FF00", f"Should have excluded green, but got {key} (margin {margin})"
+    assert key in L.KEY_CANDIDATES
+
+
+def test_pick_key_rejects_green_with_marginal_but_previously_accepted_margin():
+    """Regression cho Finding I1: asset màu (0,230,70) có margin ~131 tới #00FF00.
+
+    Dưới ngưỡng CŨ (GREEN_SAFE_THRESHOLD=120), margin 131 được coi là "an toàn" và
+    green được chọn — nhưng chroma_key()'s t_high mặc định = 170: alpha chỉ đạt 255 ở
+    khoảng cách >= 170. Ở margin 131 (< t_high), pixel màu (0,230,70) của CHÍNH chủ thể
+    chỉ đạt alpha ~169 (đo thực tế) — chủ thể bị bào mờ dù `plan` báo "an toàn". Với
+    MIN_KEY_MARGIN=190 (> t_high), margin 131 giờ bị từ chối, ép fallback sang key khác.
+    """
+    img = Image.new("RGBA", (16, 16), (0, 230, 70, 255))
+    key, margin = L.pick_key_color(img)
+    assert key != "#00FF00", f"margin {margin:.1f} phải bị từ chối là không an toàn cho xanh lá"
+
+
+def test_pick_key_avoid_folds_extra_colors_into_scoring():
+    """`avoid` (dùng bởi CLI `plan --avoid`) phải gộp được màu NGOÀI palette nguồn vào
+    chấm điểm — cần cho Finding I1's phần "structural": chroma key chạy trên ẢNH ĐÃ
+    RESTYLE, có palette MỚI (style preset) khác hẳn palette của asset gốc mà hàm này tự
+    đọc. Asset gốc ở đây thuần đỏ (không hề có xanh lá) nên mặc định sẽ chọn xanh lá;
+    truyền một màu xanh lá neon vào `avoid` (giả lập palette style preset) phải đẩy lựa
+    chọn ra khỏi xanh lá.
+    """
+    img = _solid((16, 16), (200, 30, 40, 255))          # đỏ, không hề có xanh lá
+    key_default, _ = L.pick_key_color(img)
+    assert key_default == "#00FF00"
+
+    key_avoided, margin_avoided = L.pick_key_color(img, avoid=[(10, 250, 10)])
+    assert key_avoided != "#00FF00", "avoid màu gần key phải đẩy lựa chọn ra khỏi green"
+
+
+def _subject_on_key(size=(64, 64), key=(0, 255, 0), subject=(200, 30, 40), box=None):
+    """Ảnh giả lập output Gemini: khối chủ thể đặc, đặt trên nền key phẳng.
+
+    `box` cho phép chỉnh TỈ LỆ chủ thể — cần để test riêng ca cùng tỉ lệ với bbox gốc
+    và ca lệch tỉ lệ.
+    """
+    img = Image.new("RGB", size, key)
+    if box is None:
+        w, h = size
+        box = (w // 4, h // 4, w * 3 // 4, h * 3 // 4)
+    img.paste(subject, box)
+    return img
+
+
+def test_chroma_key_makes_background_transparent():
+    keyed = L.chroma_key(_subject_on_key(), "#00FF00")
+    assert keyed.mode == "RGBA"
+    assert keyed.getpixel((2, 2))[3] == 0           # góc = nền = trong suốt
+    assert keyed.getpixel((32, 32))[3] == 255       # tâm = chủ thể = đục
+
+
+def test_chroma_key_leaves_no_key_coloured_pixels():
+    keyed = L.despill(L.chroma_key(_subject_on_key(), "#00FF00"), "#00FF00")
+    arr = np.asarray(keyed)
+    visible = arr[arr[..., 3] > L.ALPHA_FLOOR][:, :3]
+    worst = min(L.color_dist(px, (0, 255, 0)) for px in visible)
+    assert worst > 40, f"còn pixel ám màu key, khoảng cách gần nhất = {worst:.1f}"
+
+
+def test_chroma_key_produces_soft_edge():
+    """Ngưỡng mềm phải cho ra alpha trung gian trên một dải blend biết trước.
+
+    KHÔNG dựng mép bằng cách resize phóng to rồi thu nhỏ (LANCZOS) và hy vọng
+    bộ resample để lại pixel blend rơi đúng vào khoảng (t_low, t_high): khoảng
+    cách redmean giữa xanh lá key và màu đỏ chủ thể ở đây rất lớn (~550), nên
+    một pixel do resample tạo ra bão hoà về alpha 0 hoặc 255 chỉ sau một phần
+    nhỏ tỉ lệ pha trộn — test kiểu đó thực chất đang kiểm tra bộ resampler chứ
+    không kiểm tra chroma_key. Thay vào đó, dựng TRỰC TIẾP một dải cột là blend
+    tuyến tính ĐÃ BIẾT giữa màu key và màu chủ thể (p chạy từ 0.0 đến 1.0), rồi
+    kiểm tra alpha có giá trị nằm strictly giữa 0 và 255 hay không — chứng
+    minh ramp smoothstep thực sự tồn tại ở ngưỡng đã khai báo, vì một ngưỡng
+    cứng nhị phân sẽ phá hỏng mép anti-alias mà Gemini vẽ ra.
+    """
+    key = (0, 255, 0)
+    subject = (200, 30, 40)
+    width, height = 101, 4
+
+    p = np.linspace(0.0, 1.0, width)
+    key_arr = np.array(key, dtype=np.float64)
+    subj_arr = np.array(subject, dtype=np.float64)
+    row = np.round(
+        (1 - p)[:, None] * key_arr[None, :] + p[:, None] * subj_arr[None, :]
+    ).astype(np.uint8)
+    arr = np.tile(row[None, :, :], (height, 1, 1))
+    img = Image.fromarray(arr, "RGB")
+
+    keyed = L.chroma_key(img, "#00FF00")
+    alphas = np.asarray(keyed)[..., 3].ravel().tolist()
+    assert any(0 < a < 255 for a in alphas), "không có alpha trung gian -> mép sẽ răng cưa"
+
+
+def test_despill_removes_green_fringe():
+    """Pixel xám ám xanh (128,190,128), alpha=0 (nền/mép trong suốt hoàn toàn) phải bị
+    kéo kênh G về mức của R/B.
+
+    alpha=0 -> weight=(1-0/255)*1.0=1.0 -> đúng công thức kẹp CŨ (không suy giảm theo
+    alpha) — đây là ca "weight tối đa", dùng để pin phần lõi toán học của công thức kẹp
+    vẫn hoạt động đúng sau khi Finding C1 nhân thêm hệ số weight vào.
+    """
+    img = Image.new("RGBA", (4, 4), (128, 190, 128, 0))
+    out = L.despill(img, "#00FF00")
+    r, g, b, a = out.getpixel((1, 1))
+    assert g <= 130, f"green chưa được khử: {g}"
+    assert (r, b) == (128, 128), "kênh không phải key bị đụng vào"
+    assert a == 0, "despill không được đụng vào alpha"
+
+
+def test_despill_magenta_key_touches_r_and_b_only():
+    """Rewrite cho Finding C1 (CRITICAL). Bản CŨ của test này assert r<=105 và b<=105
+    cho một pixel ĐỤC HOÀN TOÀN (alpha=255) — tức là nó khẳng định phần bị phá màu là
+    ĐÚNG, chính là bug: despill từng kẹp kênh trên MỌI pixel bất kể alpha, ăn cả màu hợp
+    lệ của chủ thể. Bản mới assert đúng hành vi: một pixel ĐỤC (chủ thể thật, không có
+    mép để mà despill) phải được giữ NGUYÊN xi.
+    """
+    img = Image.new("RGBA", (4, 4), (200, 100, 200, 255))
+    r, g, b, a = L.despill(img, "#FF00FF").getpixel((1, 1))
+    assert (r, g, b, a) == (200, 100, 200, 255), (
+        f"pixel đục (alpha=255) không được đụng vào, ra {(r, g, b, a)}"
+    )
+
+
+def test_despill_never_touches_opaque_subject_pixels():
+    """Test hồi quy cho Finding C1 (CRITICAL): despill() từng là một phép CRUSH KÊNH
+    TOÀN CỤC áp lên MỌI pixel bất kể alpha, không phải sửa mép anti-alias. Đo được trên
+    code cũ (trước fix):
+        key=#00FF00, chủ thể vàng   #FFD700 (255,215,0) -> ra (255,128,0)   cam
+        key=#00FF00, chủ thể cỏ     (110,190,80)         -> ra (110,95,80)  bùn
+        key=#FF00FF, chủ thể đỏ     (200,30,40)           -> ra (30,30,30)   gần đen
+        key=#FF00FF, chủ thể hồng   (230,90,200)          -> ra (90,90,90)   xám
+
+    Mỗi pixel dưới đây có alpha=255 (chủ thể đục hoàn toàn, không phải mép) — với công
+    thức weight=(1-alpha/255)*strength, weight=0, nên RGB PHẢI ra nguyên vẹn, không đổi
+    một chút nào. Nếu test này FAIL, ai đó đã revert phần nhân weight trong despill().
+    """
+    cases = [
+        ("#00FF00", (255, 215, 0)),   # vàng gold trên key xanh lá
+        ("#00FF00", (110, 190, 80)),  # cỏ trên key xanh lá
+        ("#FF00FF", (200, 30, 40)),   # đỏ trên key hồng/magenta
+        ("#FF00FF", (230, 90, 200)),  # hồng trên key hồng/magenta
+    ]
+    for key_hex, subject in cases:
+        img = Image.new("RGBA", (4, 4), (*subject, 255))
+        out = L.despill(img, key_hex)
+        got = out.getpixel((1, 1))
+        assert got == (*subject, 255), (
+            f"key={key_hex} subject={subject}: pixel ĐỤC (alpha=255) bị đổi màu -> {got} "
+            "— đây chính là Finding C1"
+        )
+
+
+def test_despill_still_removes_edge_fringe():
+    """Pixel MÉP bán trong suốt (alpha=128, giữa nền và chủ thể) mang ám màu key VẪN
+    phải được sửa — chỉ chủ thể ĐỤC mới được miễn, không phải toàn bộ ảnh.
+
+    weight = (1 - 128/255) * 1.0 ~= 0.498 -> sửa MỘT PHẦN, không sửa full (khác test
+    test_despill_removes_green_fringe dùng alpha=0 -> weight=1.0 sửa full).
+    """
+    img = Image.new("RGBA", (4, 4), (128, 190, 128, 128))
+    out = L.despill(img, "#00FF00")
+    r, g, b, a = out.getpixel((1, 1))
+    assert a == 128, "despill không được đụng vào alpha"
+    assert (r, b) == (128, 128), "kênh không phải key bị đụng vào"
+    assert g < 190, f"mép bán trong suốt vẫn phải được sửa ít nhiều: g={g}"
+    assert g > 128, f"weight<1 nên KHÔNG được sửa full về limit: g={g}"
+
+
+def test_alpha_coverage():
+    assert L.alpha_coverage(Image.new("RGBA", (10, 10), (0, 0, 0, 255))) == 1.0
+    assert L.alpha_coverage(Image.new("RGBA", (10, 10), (0, 0, 0, 0))) == 0.0
+    half = Image.new("RGBA", (10, 10), (0, 0, 0, 0))
+    half.paste((9, 9, 9, 255), (0, 0, 10, 5))
+    assert abs(L.alpha_coverage(half) - 0.5) < 1e-9
+
+
+def _fake_src(canvas=(144, 144), box=(20, 30, 120, 110)):
+    """Asset 'gốc' giả: canvas cố định, nội dung nằm LỆCH TÂM trong bbox biết trước."""
+    img = Image.new("RGBA", canvas, (0, 0, 0, 0))
+    img.paste((10, 20, 200, 255), box)
+    return img
+
+
+def test_content_bbox_finds_content():
+    assert L.content_bbox(_fake_src()) == (20, 30, 120, 110)
+
+
+def test_content_bbox_none_when_empty():
+    assert L.content_bbox(Image.new("RGBA", (8, 8), (0, 0, 0, 0))) is None
+
+
+def test_hole_ratio_zero_for_solid_subject():
+    """Chủ thể đặc, không lỗ -> hole_ratio phải bằng 0."""
+    img = Image.new("RGBA", (100, 100), (0, 0, 0, 0))
+    img.paste((200, 30, 40, 255), (10, 10, 90, 90))
+    assert L.hole_ratio(img) == 0.0
+
+
+def test_hole_ratio_flags_interior_hole():
+    """Regression cho Finding I2: một 'viên ngọc' màu sát key bị chroma-key khoét thành
+    lỗ trong suốt GIỮA chủ thể — coverage (toàn cục), solid_ratio (trên nội dung) và
+    border_impurity (vành ngoài) đều KHÔNG nhìn vào giữa bbox nên không thấy gì, báo
+    'ok' dù asset có một lỗ thủng giữa thân. hole_ratio() phải bắt được ca này.
+    """
+    img = Image.new("RGBA", (100, 100), (0, 0, 0, 0))
+    img.paste((200, 30, 40, 255), (10, 10, 90, 90))    # chủ thể đặc 80x80 = 6400px
+    img.paste((0, 0, 0, 0), (35, 35, 65, 65))          # lỗ thủng giữa: 30x30=900/6400=14.1%
+    ratio = L.hole_ratio(img)
+    assert ratio > L.BAD_HOLE_RATIO, f"lỗ thủng giữa chủ thể phải vượt ngưỡng: {ratio}"
+
+
+def test_hole_ratio_tolerates_legit_hollow_shape():
+    """Art hollow HỢP LỆ (nhẫn, chữ O, khung ảnh, donut) không được báo bad_holes — chỉ
+    một lỗ khoét CHIẾM ĐA SỐ diện tích giữa mới đáng ngờ. Dựng một hình 'nhẫn' có lỗ giữa
+    chiếm tỉ lệ vừa phải (6.25%, dưới BAD_HOLE_RATIO=10%) để pin ranh giới trade-off này —
+    xem docstring hole_ratio() về việc ngưỡng này KHÔNG hoàn hảo với hollow rất lớn.
+    """
+    img = Image.new("RGBA", (100, 100), (0, 0, 0, 0))
+    img.paste((200, 30, 40, 255), (10, 10, 90, 90))    # vành nhẫn 80x80 = 6400px
+    img.paste((0, 0, 0, 0), (40, 40, 60, 60))          # lỗ giữa nhẫn: 20x20=400/6400=6.25%
+    ratio = L.hole_ratio(img)
+    assert ratio < L.BAD_HOLE_RATIO, f"nhẫn mỏng hợp lệ không được vượt ngưỡng: {ratio}"
+
+
+def test_resize_keeps_edge_colour_clean():
+    """TEST GIẢ ĐỊNH: pin hành vi của Pillow mà pipeline đang DỰA VÀO.
+
+    Pillow tự premultiply bên trong resize(): RGBA -> "RGBa" -> resize -> RGBA
+    (Image.py). Nhờ vậy RGB của pixel trong suốt (ở đây là màu key xanh lá còn sót)
+    KHÔNG rỉ vào pixel mép. Ta gọi thẳng resize() và dựa vào đúng tính chất này.
+
+    KHÔNG được premultiply BẰNG TAY trước khi gọi resize(): Pillow sẽ nhân lần thứ hai.
+    Ở alpha thấp, giá trị premultiplied bị lượng tử hoá về uint8 (alpha=2: RGB 255 -> 2),
+    Pillow nhân tiếp (2 * 2/255 -> 0.02 -> làm tròn thành 0), và un-premultiply không
+    cứu lại được. Đo thực tế trên dải alpha 2..40: R 255 -> R min = 0, R mean 177.8.
+    Tức là premultiply thủ công PHÁ HỎNG đúng những mép anti-alias mảnh mà dự án này
+    quan tâm nhất (line-art, râu mèo). Vì thế resize_premul() đã bị xoá.
+
+    HÌNH HỌC PHẢI LỆCH LƯỚI (65x65, box (17,15,47,51) -> 31x31). Với hình học chia chẵn
+    đúng 2x và mép trùng lưới (64x64, box (16,16,48,48) -> 32x32), kernel LANCZOS nhảy
+    alpha thẳng từ ~14 lên ~228 trong đúng một pixel: KHÔNG có mẫu nào rơi vào dải alpha
+    một phần, test không chạm được vào mép và trở thành vô nghĩa. Guard `len(edge) > 0`
+    bên dưới là để chặn ca đó.
+    """
+    # Pixel trong suốt mang màu KEY (xanh lá) — đúng ca thật sau khi chroma key.
+    img = Image.new("RGBA", (65, 65), (0, 255, 0, 0))
+    img.paste((255, 0, 0, 255), (17, 15, 47, 51))
+    small = img.resize((31, 31), Image.LANCZOS)
+    arr = np.asarray(small).astype(int)
+    edge = arr[(arr[..., 3] > 40) & (arr[..., 3] < 220)]
+    assert len(edge) > 0, "test vô nghĩa nếu không có pixel mép"
+    assert edge[:, 0].min() > 180, f"mép bị ngả đen, R nhỏ nhất = {edge[:, 0].min()}"
+    # Đây mới là assertion sẽ nổ nếu Pillow thôi không premultiply nội bộ nữa:
+    assert edge[:, 1].max() < 40, f"mép bị rỉ màu key, G lớn nhất = {edge[:, 1].max()}"
+
+
+def test_postprocess_matches_source_geometry():
+    """Bám gốc, chủ thể CÙNG tỉ lệ với bbox gốc -> output TRÙNG size và TRÙNG bbox."""
+    src = _fake_src()                                     # bbox (20,30,120,110) = 100x80 (5:4)
+    gen = _subject_on_key(size=(256, 256), box=(28, 48, 228, 208))   # 200x160 = 5:4
+    out, report = L.postprocess(gen, "#00FF00", src=src)
+
+    assert report["status"] == "ok"
+    assert out.size == src.size == (144, 144)
+    sb, ob = L.content_bbox(src), L.content_bbox(out)
+    for i in range(4):
+        assert abs(sb[i] - ob[i]) <= 1, f"bbox lệch: gốc={sb} out={ob}"
+
+
+def test_postprocess_contains_and_centres_when_aspect_differs():
+    """Chủ thể VUÔNG, bbox gốc chữ nhật -> KHÔNG bóp méo.
+
+    Hợp đồng thật là 'contain + căn giữa trong bbox gốc', không phải 'lấp kín bbox gốc'.
+    Thà chừa lề còn hơn kéo méo asset.
+    """
+    src = _fake_src()                                     # bbox 100x80
+    gen = _subject_on_key(size=(256, 256))                # chủ thể vuông 128x128
+    out, _ = L.postprocess(gen, "#00FF00", src=src)
+
+    sb, ob = (20, 30, 120, 110), L.content_bbox(out)
+    assert ob[0] >= sb[0] and ob[1] >= sb[1] and ob[2] <= sb[2] and ob[3] <= sb[3], \
+        f"tràn ra ngoài bbox gốc: {ob}"
+    assert ob[3] - ob[1] == 80, "chiều bị ràng buộc (cao) phải lấp đầy bbox gốc"
+    left, right = ob[0] - sb[0], sb[2] - ob[2]
+    assert abs(left - right) <= 1, f"không căn giữa: lề trái={left} lề phải={right}"
+
+
+def test_postprocess_handles_bbox_touching_canvas_edge():
+    """Ca thật: cell_base.png có bbox phủ KÍN canvas. Không được crash / lệch."""
+    src = _fake_src(canvas=(249, 249), box=(0, 0, 249, 249))
+    out, report = L.postprocess(_subject_on_key(size=(256, 256)), "#00FF00", src=src)
+    assert report["status"] == "ok"
+    assert out.size == (249, 249)
+    assert L.content_bbox(out) == (0, 0, 249, 249)
+
+
+def test_postprocess_non_square_source():
+    """Asset thật hay không vuông (346x78). Phải giữ đúng, không ép về vuông."""
+    src = _fake_src(canvas=(346, 78), box=(2, 0, 344, 78))
+    out, _ = L.postprocess(_subject_on_key(size=(256, 256)), "#00FF00", src=src)
+    assert out.size == (346, 78)
+
+
+def test_postprocess_explicit_size_overrides_source():
+    out, report = L.postprocess(
+        _subject_on_key(size=(256, 256)), "#00FF00", src=_fake_src(), size=(64, 64)
+    )
+    assert out.size == (64, 64)
+    assert report["size"] == (64, 64)
+
+
+def test_postprocess_flags_unkeyed_background():
+    """Gemini vẽ nền KHÔNG phải màu key -> không tách được -> phải báo bad_background."""
+    gen = Image.new("RGB", (64, 64), (120, 120, 130))   # nền xám, không có xanh lá
+    out, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+    assert report["status"] == "bad_background"
+    assert report["coverage"] > L.BAD_HIGH
+    # bad_background vẫn phải TRẢ ẢNH — người duyệt cần thấy defect trong contact sheet,
+    # chỉ bad_subject mới được trả None.
+    assert out is not None
+
+
+def test_postprocess_flags_eaten_subject():
+    """Chủ thể trùng màu key -> bị ăn thủng -> phải báo bad_subject, không trả ảnh rác."""
+    gen = Image.new("RGB", (64, 64), (0, 255, 0))       # toàn màu key
+    out, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+    assert report["status"] == "bad_subject"
+    assert out is None
+
+
+def test_postprocess_sparse_but_solid_glyph_is_not_bad_subject():
+    """Regression cho Finding I3: coverage thấp một mình KHÔNG còn nghĩa là 'hỏng'.
+
+    Trước fix, một icon/line-art nhỏ như nút X 12px nét (đo thực tế trên canvas ~1024^2:
+    coverage=0.0161 < BAD_LOW=0.02, solid_ratio=1.0, border_impurity=0.0 — một bản sinh
+    HOÀN HẢO) bị `postprocess` vứt bỏ (trả None) vì coverage thấp bị đánh đồng với
+    'hỏng', và SKILL.md khuyên 'sinh lại với màu key khác' — vô nghĩa, màu key chưa từng
+    là vấn đề ở đây. Không có `--force`, icon/glyph mảnh đơn giản KHÔNG dùng được qua tool.
+
+    Dựng glyph chữ X mảnh, đặc (numpy trực tiếp, không qua ImageDraw, để kiểm soát chính
+    xác tỉ lệ diện tích thay vì phụ thuộc anti-alias của bộ vẽ) — coverage đo được ở đây
+    (~0.0078 trên canvas 256x256) cùng bậc với ca thật của reviewer, dưới BAD_LOW.
+    """
+    n = 256
+    key = (0, 255, 0)
+    subject = (20, 20, 20)
+    yy, xx = np.mgrid[0:n, 0:n]
+    mask = (np.abs(xx - yy) == 0) | (np.abs(xx + yy - (n - 1)) == 0)
+    arr = np.zeros((n, n, 3), dtype=np.uint8)
+    arr[...] = key
+    arr[mask] = subject
+    gen = Image.fromarray(arr, "RGB")
+
+    out, report = L.postprocess(gen, "#00FF00", size=(n, n))
+
+    assert report["coverage"] < L.BAD_LOW, f"glyph phải nhỏ hơn BAD_LOW: {report['coverage']}"
+    assert report["solid_ratio"] == 1.0, "glyph không AA -> phải đục hoàn toàn"
+    assert out is not None, "chủ thể nhỏ nhưng ĐẶC không được vứt bỏ — người duyệt cần thấy nó"
+    assert "bad_subject" not in report["flags"], report["flags"]
+    assert "sparse" in report["flags"], report["flags"]
+
+
+def test_postprocess_flags_interior_hole():
+    """Tái hiện repro của reviewer cho Finding I2: chủ thể đỏ-nâu với một 'viên ngọc' màu
+    sát key nằm GIỮA thân bị chroma-key khoét thành lỗ trong suốt. Trước fix,
+    coverage/solid_ratio/border_impurity đều 'sạch' -> status: ok, flags: [] dù output có
+    alpha=0 ngay giữa chủ thể. Sau fix: report luôn có `hole_ratio`, và `bad_holes` phải
+    xuất hiện vì lỗ đủ lớn (16% diện tích bbox, trên BAD_HOLE_RATIO=10%) — nhưng ảnh vẫn
+    được ghi ra (bad_holes chỉ tham khảo, không phải gate cứng).
+    """
+    size = (120, 120)
+    key = (0, 255, 0)
+    subject = (140, 70, 50)      # đỏ-nâu, cách key rất xa -> đục hoàn toàn
+    gem = (20, 235, 10)          # gần key -> bị chroma-key khoét thủng hoàn toàn
+
+    arr = np.full((size[1], size[0], 3), key, dtype=np.uint8)
+    arr[10:110, 10:110, :] = subject     # chủ thể đặc 100x100 = 10000px
+    arr[35:75, 35:75, :] = gem           # viên ngọc giữa: 40x40=1600/10000=16%
+    gen = Image.fromarray(arr, "RGB")
+
+    out, report = L.postprocess(gen, "#00FF00", size=size)
+
+    assert out is not None, "bad_holes chỉ tham khảo — vẫn phải ghi ảnh ra"
+    assert report["hole_ratio"] > L.BAD_HOLE_RATIO, report["hole_ratio"]
+    assert "bad_holes" in report["flags"], report["flags"]
+    assert "bad_subject" not in report["flags"], report["flags"]
+
+
+def test_solid_ratio_full_for_opaque_subject():
+    img = Image.new("RGBA", (10, 10), (0, 0, 0, 0))
+    img.paste((10, 20, 30, 255), (2, 2, 8, 8))
+    assert L.solid_ratio(img) == 1.0
+
+
+def test_solid_ratio_zero_for_ghost_subject():
+    """Chủ thể chỉ còn alpha 40 -> có mặt nhưng KHÔNG đục -> solid_ratio phải = 0."""
+    img = Image.new("RGBA", (10, 10), (0, 0, 0, 0))
+    img.paste((10, 20, 30, 40), (2, 2, 8, 8))
+    assert L.alpha_coverage(img) > 0.3          # coverage vẫn "bình thường"...
+    assert L.solid_ratio(img) == 0.0            # ...nhưng không đục chút nào
+
+
+def test_solid_ratio_zero_for_empty_image():
+    assert L.solid_ratio(Image.new("RGBA", (8, 8), (0, 0, 0, 0))) == 0.0
+
+
+def test_postprocess_flags_translucent_ghost():
+    """Màu key sát màu chủ thể -> chủ thể bị bào thành bóng ma.
+
+    Đây là ca mà coverage KHÔNG bắt được: pixel vẫn tồn tại nên coverage nằm trong dải
+    "ok", nhưng chúng gần như trong suốt. Không có solid_ratio thì asset mờ tịt sẽ lọt lưới.
+    """
+    # redmean nhân kênh G với hệ số 4, nên chỉ lệch G thì d = 2*|dg|.
+    # Chủ thể (0, 207, 0): d = 2*48 = 96 -> nằm giữa t_low=70 và t_high=170
+    # -> smoothstep cho alpha ~43. Chủ thể "có mặt" nhưng gần như trong suốt.
+    gen = _subject_on_key(size=(256, 256), subject=(0, 207, 0))
+    out, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+
+    assert L.BAD_LOW < report["coverage"] < L.BAD_HIGH, "coverage phải nằm trong dải 'ok'"
+    assert report["solid_ratio"] < L.BAD_SOLID_RATIO
+    assert report["status"] == "bad_translucent"
+    # bad_translucent vẫn phải TRẢ ẢNH — người duyệt cần thấy defect trong contact sheet,
+    # chỉ bad_subject mới được trả None.
+    assert out is not None
+
+
+def test_postprocess_ok_reports_solid_ratio():
+    """solid_ratio luôn có mặt trong report, kể cả khi status ok."""
+    _, report = L.postprocess(_subject_on_key(size=(256, 256)), "#00FF00", src=_fake_src())
+    assert report["status"] == "ok"
+    assert report["solid_ratio"] > 0.9
+
+
+def test_border_impurity_zero_on_flat_key_background():
+    """Vành ngoài là màu key thuần (ca bình thường) -> border_impurity phải bằng 0 tuyệt đối."""
+    img = _subject_on_key(size=(64, 64), key=(0, 255, 0), subject=(200, 30, 40))
+    assert L.border_impurity(img, "#00FF00") == 0.0
+
+
+def test_border_impurity_high_when_background_not_key():
+    """Nền xám phủ toàn khung (không hề có màu key) -> vành ngoài lệch xa màu key."""
+    img = Image.new("RGB", (64, 64), (120, 120, 130))
+    assert L.border_impurity(img, "#00FF00") > L.BAD_BORDER_DIST
+
+
+def test_postprocess_flags_partial_background_failure():
+    """Tái hiện chính xác ca của reviewer: nền hỏng MỘT PHẦN thì coverage và solid_ratio
+    đều bị qua mặt cùng lúc, chỉ có border_impurity mới bắt được — đây là cái lỗ hổng mà
+    Finding 1 yêu cầu vá.
+
+    Bố cục canvas 100x100 (tổng 10000px):
+    - 40 hàng trên cùng (0..39), toàn bộ chiều rộng: một MẢNG XÁM ĐẶC chưa từng được key
+      hoá (Gemini vẽ bóng đổ/panel/vignette đè lên nền thay vì để trống) -> sau chroma_key
+      vẫn đục hoàn toàn (khoảng cách tới key ~390, > t_high=170 -> alpha=255, solid).
+      4000/10000 px = 40% diện tích.
+    - 60 hàng dưới (40..99): nền màu key THUẦN, TRỪ một dải cột giữa (25..74) là CHỦ THỂ
+      BÓNG MA màu (0,207,0) sát màu key (0,255,0) -> khoảng cách redmean = 96, nằm giữa
+      t_low=70/t_high=170 -> smoothstep cho alpha ~43 (có nội dung, nhưng không đục).
+      Phần còn lại của 60 hàng dưới là nền key thuần -> alpha=0 (không tính là nội dung).
+
+    Tính tay: coverage = (4000 xám + 3000 bóng ma) / 10000 = 0.70 -> nằm NGUYÊN trong dải
+    "ok" (0.02, 0.95), vì alpha_coverage không phân biệt được "đục vì nền hỏng" với "đục
+    vì chủ thể thật". solid_ratio = 4000 đục thật / 7000 có-nội-dung = 0.571 -> CŨNG vượt
+    qua BAD_SOLID_RATIO=0.25, chính vì mảng xám hỏng đó bơm phồng "đục thật" giả. Cả hai
+    tín hiệu cũ đều bị qua mặt y hệt ca reviewer báo cáo (coverage 0.63, solid_ratio 0.65
+    trên input của họ) -> asset ghosted lọt lưới với status "ok".
+
+    Chỉ có border_impurity, đo trực tiếp vành ngoài 4px, mới thấy được mảng xám: phần lớn
+    vành ngoài của ảnh này (viền trên hoàn toàn, phần lớn viền trái/phải) nằm trong mảng
+    xám chưa key, nên khoảng cách trung bình của vành >> BAD_BORDER_DIST=60.
+    """
+    size = (100, 100)
+    arr = np.full((size[1], size[0], 3), (0, 255, 0), dtype=np.uint8)   # nền key thuần
+    arr[0:40, :, :] = (120, 120, 130)     # mảng xám chưa key, 40% diện tích, KHÔNG bị chroma-key
+    arr[40:100, 25:75, :] = (0, 207, 0)   # chủ thể bóng ma, sát màu key
+    gen = Image.fromarray(arr, "RGB")
+
+    _, report = L.postprocess(gen, "#00FF00", src=_fake_src(canvas=size, box=(10, 10, 90, 90)))
+
+    assert L.BAD_LOW < report["coverage"] < L.BAD_HIGH, (
+        f"coverage phải nằm trong dải 'ok' (bị qua mặt): {report['coverage']}"
+    )
+    assert report["solid_ratio"] > L.BAD_SOLID_RATIO, (
+        f"solid_ratio cũng phải bị qua mặt, bơm phồng bởi mảng xám: {report['solid_ratio']}"
+    )
+    assert report["status"] != "ok", "lỗ hổng cũ: bản sinh hỏng lọt lưới với status=ok"
+    assert "bad_background" in report["flags"], "border_impurity phải bắt được mảng xám chưa key"
+
+
+def test_postprocess_ok_has_empty_flags():
+    """Bản sinh sạch: không cờ nào được set, border_impurity gần như bằng 0."""
+    gen = _subject_on_key(size=(256, 256))
+    _, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+    assert report["status"] == "ok"
+    assert report["flags"] == []
+    assert report["border_impurity"] == 0.0
+
+
+def test_postprocess_ok_reports_hole_ratio():
+    """`hole_ratio` phải luôn có mặt trong report, kể cả khi status ok (không lỗ nào)."""
+    gen = _subject_on_key(size=(256, 256))
+    _, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+    assert report["hole_ratio"] == 0.0
+
+
+def test_border_impurity_false_positive_when_subject_touches_edge():
+    """Ghim CA FALSE POSITIVE ĐÃ BIẾT VÀ CHẤP NHẬN của border_impurity — không phải bug.
+
+    border_impurity giả định Gemini luôn chừa một lề nền quanh chủ thể. Test này dựng
+    đúng ca giả định đó bị PHÁ VỠ: chủ thể (200,30,40) phủ box=(0,0,64,64) — tức là
+    TOÀN BỘ canvas 64x64, không chừa một pixel lề key nào. Đây là hình dạng thật của
+    asset `cell_base.png` trong game (bbox phủ kín canvas 249x249) — một model được
+    yêu cầu restyle nó hoàn toàn có thể vẽ tràn mép y hệt thế này.
+
+    Vành ngoài lúc này toàn màu chủ thể, cách màu key rất xa (đo thực tế ~549.8, so
+    với ngưỡng BAD_BORDER_DIST=60) -> border_impurity báo cao NGẤT, và postprocess báo
+    bad_background — dù thực chất "nền" ở đây không hề tồn tại để mà hỏng.
+
+    Đây KHÔNG phải lỗi cần vá. Đây là đánh đổi có chủ đích: false positive (báo hỏng
+    nhầm một bản sinh có thể vẫn ổn) chỉ tốn một lần sinh lại; false negative (bỏ lọt
+    một bản sinh thật sự ma/lỗi) mới là thứ khiến asset hỏng lọt vào game. Test này tồn
+    tại để nếu sau này ai đó đổi hành vi (nới lỏng border_impurity, hoặc thêm ngoại lệ
+    cho "chủ thể phủ kín canvas"), họ phải chủ động sửa test này chứ không phát hiện ra
+    sự thay đổi khi asset ma đã lọt vào production.
+    """
+    gen = _subject_on_key(size=(64, 64), key=(0, 255, 0), subject=(200, 30, 40), box=(0, 0, 64, 64))
+    impurity = L.border_impurity(gen, "#00FF00")
+    assert impurity > L.BAD_BORDER_DIST, (
+        f"vành ngoài toàn chủ thể phải cách xa màu key: {impurity}"
+    )
+
+    src = _fake_src(canvas=(64, 64), box=(0, 0, 64, 64))
+    _, report = L.postprocess(gen, "#00FF00", src=src)
+    assert report["border_impurity"] == impurity
+    assert "bad_background" in report["flags"], (
+        "false positive CHẤP NHẬN ĐƯỢC: chủ thể tràn mép -> báo hỏng nền dù nền "
+        "không hề tồn tại; đây là đánh đổi cố ý, không phải điều cần sửa"
+    )
+    assert report["status"] == "bad_background"
+
+
+def test_postprocess_reports_multiple_flags_at_once():
+    """Ghim cấu trúc if/if (KHÔNG PHẢI if/elif) của postprocess — Finding 2.
+
+    postprocess() được cố ý đổi từ if/elif sang các khối if ĐỘC LẬP để một bản sinh
+    hỏng NHIỀU KIỂU cùng lúc báo ĐỦ tất cả cờ trong `flags`, không chỉ cờ đầu tiên khớp.
+    Nhưng test_postprocess_flags_partial_background_failure (fix round 3) không thực sự
+    kiểm chứng điều đó: solid_ratio ở test đó (0.5714) vẫn nằm TRÊN BAD_SOLID_RATIO, nên
+    flags của nó chỉ có đúng 1 phần tử ('bad_background') — một regression âm thầm đổi
+    if thứ hai trở lại thành elif vẫn sẽ lọt qua toàn bộ suite. Test này dựng một ca
+    hỏng THẬT SỰ 2 kiểu cùng lúc để bắt đúng regression đó.
+
+    Tính tay trên canvas 100x100 (10000px), BORDER_PX=4:
+    - VÀNH NGOÀI (đúng dải mà border_impurity đo: 4px trên/dưới/trái/phải) = màu xám
+      (120,120,130), CHƯA từng được key hoá -> 1536px xám, đục hoàn toàn sau chroma-key
+      (cách màu key ~389.5, đo thực tế, vượt xa t_high=170 nên alpha=255 và vượt xa
+      BAD_BORDER_DIST=60) -> bad_background.
+    - PHẦN LỚN vùng bên trong vành (92x92, trừ một dải cột hẹp) = màu (0,207,0), CHỦ
+      THỂ BÓNG MA sát màu key (0,255,0) -> cách màu key = 96.0 (nằm giữa t_low=70 và
+      t_high=170) -> alpha ~43 sau chroma-key: CÓ nội dung (>ALPHA_FLOOR=8) nhưng KHÔNG
+      đục (<SOLID_ALPHA=200). Vùng này chiếm 92 hàng x 82 cột = 7544px — DOMINANT so
+      với 1536px xám, nên nó mới là thứ quyết định solid_ratio.
+    - Một dải cột hẹp còn lại bên trong vành (92 hàng x 10 cột = 920px, sát cạnh phải
+      nhưng KHÔNG chạm vành) vẫn là màu key thuần -> alpha=0, không tính vào nội dung.
+      Dải này tồn tại chỉ để giữ coverage không tràn lên 1.0 (không cần thiết cho hai
+      cờ mục tiêu, nhưng cho coverage một khoảng đệm rõ ràng dưới BAD_HIGH=0.95).
+
+    Số đo tay: coverage = (1536 xám + 7544 bóng ma) / 10000 = 0.908 -> nằm trong dải ok
+    (0.02, 0.95), không đủ cao để tự nó kích bad_background qua nhánh coverage, không đủ
+    thấp để kích bad_subject — cờ bad_background ở đây đến từ border_impurity, đúng như
+    Finding 1 mô tả. solid_ratio = 1536 xám (đục) / 9080 nội dung = 0.16916 -> DƯỚI
+    BAD_SOLID_RATIO=0.25 vì mảng bóng ma 7544px áp đảo mảng xám 1536px trong mẫu số.
+
+    Test dựng thẳng bằng numpy (không qua _subject_on_key) để kiểm soát chính xác vành
+    ngoài trùng khít với dải mà border_impurity thực sự đọc — xem imglib.border_impurity:
+    rgb[:b], rgb[-b:], rgb[b:-b,:b], rgb[b:-b,-b:].
+    """
+    size = (100, 100)
+    key = (0, 255, 0)
+    grey = (120, 120, 130)
+    ghost = (0, 207, 0)
+
+    arr = np.full((size[1], size[0], 3), key, dtype=np.uint8)
+    arr[4:96, 4:86, :] = ghost      # chủ thể bóng ma, chiếm áp đảo (7544px)
+    arr[0:4, :, :] = grey           # vành trên
+    arr[-4:, :, :] = grey           # vành dưới
+    arr[:, 0:4, :] = grey           # vành trái
+    arr[:, -4:, :] = grey           # vành phải (cùng với 3 dòng trên: đúng 1536px vành)
+    gen = Image.fromarray(arr, "RGB")
+
+    src = _fake_src(canvas=size, box=(10, 10, 90, 90))
+    _, report = L.postprocess(gen, "#00FF00", src=src)
+
+    assert L.BAD_LOW < report["coverage"] < L.BAD_HIGH, (
+        f"coverage phải nằm trong dải ok để bad_subject KHÔNG bật: {report['coverage']}"
+    )
+    assert report["border_impurity"] > L.BAD_BORDER_DIST, (
+        f"vành xám phải kích bad_background: {report['border_impurity']}"
+    )
+    assert report["solid_ratio"] < L.BAD_SOLID_RATIO, (
+        f"bóng ma áp đảo phải kéo solid_ratio xuống dưới ngưỡng: {report['solid_ratio']}"
+    )
+    assert "bad_background" in report["flags"], report["flags"]
+    assert "bad_translucent" in report["flags"], report["flags"]
+    assert "bad_subject" not in report["flags"], report["flags"]
+    assert report["status"] == "bad_background", (
+        "cờ nặng nhất (bad_background, đứng trước trong thứ tự append) phải thắng status"
+    )
+
+
+def test_make_sheet_layout():
+    """3 hàng nền x N cột, cộng dải nhãn phía trên."""
+    cells = [
+        ("original", _fake_src()),
+        ("v1", _fake_src(box=(10, 10, 100, 100))),
+        ("v2", _fake_src(box=(30, 30, 130, 130))),
+    ]
+    sheet = L.make_sheet(cells, cell=64, pad=8)
+    assert sheet.mode == "RGB"
+    # 3 cột x (64 + 8) + 8 mép
+    assert sheet.width == 3 * (64 + 8) + 8
+    # 3 hàng nền x (64 + 8) + 8 mép + 20 dải nhãn
+    assert sheet.height == 3 * (64 + 8) + 8 + 20
+
+
+def test_make_sheet_backgrounds_differ():
+    """Hàng nền sáng và hàng nền tối phải KHÁC nhau — nếu giống thì sheet vô dụng."""
+    sheet = L.make_sheet([("a", _fake_src())], cell=64, pad=8)
+    light = sheet.getpixel((10, 20 + 8 + 2))            # góc ô hàng 1
+    dark = sheet.getpixel((10, 20 + 8 + 64 + 8 + 2))    # góc ô hàng 2
+    assert light != dark
+
+
+def test_make_sheet_checker_row_alternates():
+    """Checker row (row 2) reveals semi-transparent subjects and alternates properly.
+
+    The checker row is the final gate before an asset is written into the game —
+    it alone reveals semi-transparent/ghosted subjects that would hide in solid rows.
+    Without this test, a future refactor collapsing _checker() to a solid fill or
+    breaking the alternation would pass silently and the sheet would stop exposing
+    the exact defect it exists to expose.
+    """
+    sheet = L.make_sheet([("test", _fake_src())], cell=160, pad=12)
+
+    # Row 2 y-offset from layout arithmetic: LABEL_H + pad + 2 * (cell + pad)
+    row2_y = L.LABEL_H + 12 + 2 * (160 + 12)  # 20 + 12 + 344 = 376
+    x = 12  # pad
+
+    # Sample two points one checker square apart in the transparent cell corner.
+    # _fake_src() has transparent margins, so corners read the background, not content.
+    px1 = sheet.getpixel((x + 2, row2_y + 2))
+    px2 = sheet.getpixel((x + 2 + L.CHECKER_SIZE, row2_y + 2))
+
+    # Checker must alternate: samples one square apart must differ
+    assert px1 != px2, f"checker not alternating: {px1} vs {px2}"
+
+    # Checker colors must be from SHEET_CHECKER, not solid light/dark fill
+    assert px1 in L.SHEET_CHECKER, f"checker color {px1} not in SHEET_CHECKER"
+    assert px2 in L.SHEET_CHECKER, f"checker color {px2} not in SHEET_CHECKER"
+
+
+def test_make_sheet_empty_cells_is_safe():
+    sheet = L.make_sheet([], cell=64, pad=8)
+    assert sheet.size[0] > 0 and sheet.size[1] > 0
+
+
+def test_despeckle_removes_gemini_watermark():
+    """Ca THẬT, đo từ một lần gọi Gemini thật — không phải fixture bịa.
+
+    Gemini đóng dấu watermark ✦ lên góc dưới-phải MỌI ảnh nó sinh. Watermark đó có màu
+    (81,249,77) — xanh lá hơi lệch key, cách #00FF00 đúng ~176 trên thang redmean, tức là
+    NHỈNH HƠN t_high=170 — nên chroma_key coi nó là chủ thể và giữ lại ĐỤC HOÀN TOÀN.
+    Kết quả: mọi asset xuất ra đều dính một chấm xanh. Chỉ có chạy thật mới phát hiện được.
+    """
+    gen = Image.new("RGB", (256, 256), (0, 255, 0))
+    gen.paste((200, 30, 40), (64, 64, 192, 192))          # chủ thể
+    gen.paste((81, 249, 77), (238, 238, 250, 250))        # watermark Gemini (đo thật)
+
+    keyed = L.despill(L.chroma_key(gen, "#00FF00"), "#00FF00")
+    assert keyed.getpixel((244, 244))[3] > 200, "test vô nghĩa nếu watermark không sống sót key"
+
+    cleaned, removed = L.despeckle(keyed)
+    assert removed == 1, f"phải xoá đúng 1 mảng rác, xoá {removed}"
+    assert cleaned.getpixel((244, 244))[3] == 0, "watermark vẫn còn"
+    assert cleaned.getpixel((128, 128))[3] == 255, "chủ thể bị xoá oan"
+
+
+def test_despeckle_keeps_main_subject_when_nothing_to_clean():
+    gen = Image.new("RGB", (128, 128), (0, 255, 0))
+    gen.paste((200, 30, 40), (32, 32, 96, 96))
+    keyed = L.despill(L.chroma_key(gen, "#00FF00"), "#00FF00")
+    cleaned, removed = L.despeckle(keyed)
+    assert removed == 0
+    assert L.content_bbox(cleaned) == L.content_bbox(keyed)
+
+
+def test_despeckle_keeps_comparable_sized_parts():
+    """Asset nhiều mảnh rời cỡ tương đương (vd đống xu) KHÔNG được mất mảnh nào."""
+    img = Image.new("RGBA", (128, 128), (0, 0, 0, 0))
+    for box in [(10, 10, 50, 50), (70, 10, 110, 50), (10, 70, 50, 110)]:
+        img.paste((200, 30, 40, 255), box)
+    cleaned, removed = L.despeckle(img)
+    assert removed == 0, "ba mảng cỡ bằng nhau, không được xoá cái nào"
+
+
+def test_postprocess_reports_speckles_removed():
+    gen = _subject_on_key(size=(256, 256))
+    gen.paste((81, 249, 77), (240, 240, 250, 250))        # watermark
+    _, report = L.postprocess(gen, "#00FF00", src=_fake_src())
+    assert report["speckles_removed"] == 1
+
+
+# ── unwatermark_gemini: đảo lớp phủ ✦ của Gemini ────────────────────────────────────────
+# Ảnh thử luôn phải ĐỦ TO cho hình học đã hiệu chuẩn (48x48 cách cạnh phải/dưới 96px),
+# nên dùng 400x300 chứ không phải 256x256 như các test khác.
+_WM_W, _WM_H = 400, 300
+
+
+def _wm_bake(bg_rgb, size=(_WM_W, _WM_H)):
+    """Dán watermark ✦ ĐÚNG như Gemini: phủ trắng alpha cố định lên ảnh nền cho trước."""
+    a = L._wm_alpha()
+    arr = np.asarray(Image.new("RGB", size, bg_rgb)).astype(float)
+    W, H = size
+    x0, y0 = W - 144, H - 144
+    reg = arr[y0:y0 + 48, x0:x0 + 48]
+    arr[y0:y0 + 48, x0:x0 + 48] = reg * (1 - a[..., None]) + 255 * a[..., None]
+    return Image.fromarray(np.clip(np.rint(arr), 0, 255).astype("uint8"), "RGB"), (x0, y0)
+
+
+def _wm_box_px(img, x0, y0):
+    return np.asarray(img.convert("RGB")).astype(int)[y0:y0 + 48, x0:x0 + 48]
+
+
+def test_unwatermark_restores_flat_background_exactly():
+    """Phép đảo phải trả lại ĐÚNG màu nền — sai số chỉ do lượng tử hoá (<=1 mức)."""
+    for bg in [(0, 0, 0), (128, 128, 128), (60, 90, 200), (250, 250, 250)]:
+        wm, (x0, y0) = _wm_bake(bg)
+        assert _wm_box_px(wm, x0, y0).std() > 0, f"nền {bg}: watermark không dán được"
+        out, info = L.unwatermark_gemini(wm)
+        assert info is not None and info["box"] == (x0, y0, 48, 48)
+        err = np.abs(_wm_box_px(out, x0, y0) - np.array(bg)).max()
+        assert err <= 1, f"nền {bg}: sai số phục hồi {err} > 1"
+
+
+def test_unwatermark_verify_detects_real_watermark():
+    wm, _ = _wm_bake((40, 40, 40))
+    _, info = L.unwatermark_gemini(wm, verify=True)
+    assert info is not None and info["gain"] > 0.5
+
+
+def test_unwatermark_verify_skips_clean_image():
+    """Ảnh KHÔNG có watermark phải được bỏ qua — đảo bừa sẽ đóng ngôi sao TỐI vào ảnh sạch."""
+    for bg in [(0, 0, 0), (128, 128, 128), (255, 255, 255), (200, 30, 30)]:
+        clean = Image.new("RGB", (_WM_W, _WM_H), bg)
+        out, info = L.unwatermark_gemini(clean, verify=True)
+        assert info is None, f"nền {bg}: xoá bừa trên ảnh sạch"
+        assert np.array_equal(np.asarray(out), np.asarray(clean))
+
+
+def test_unwatermark_verify_is_idempotent():
+    """Chạy lần hai không được đục thêm — chống xoá hai lần khi ảnh qua nhiều bước."""
+    wm, _ = _wm_bake((70, 70, 70))
+    once, info1 = L.unwatermark_gemini(wm, verify=True)
+    twice, info2 = L.unwatermark_gemini(once, verify=True)
+    assert info1 is not None and info2 is None
+    assert np.array_equal(np.asarray(once), np.asarray(twice))
+
+
+def test_unwatermark_rejects_star_with_different_alpha():
+    """Ngôi sao THẬT do người vẽ (alpha khác) không được nhận nhầm là watermark."""
+    a = L._wm_alpha()
+    arr = np.asarray(Image.new("RGB", (_WM_W, _WM_H), (60, 60, 60))).astype(float)
+    x0, y0 = _WM_W - 144, _WM_H - 144
+    reg = arr[y0:y0 + 48, x0:x0 + 48]
+    arr[y0:y0 + 48, x0:x0 + 48] = reg * (1 - 0.6 * a[..., None]) + 255 * 0.6 * a[..., None]
+    img = Image.fromarray(np.clip(np.rint(arr), 0, 255).astype("uint8"), "RGB")
+    _, info = L.unwatermark_gemini(img, verify=True)
+    assert info is None
+
+
+def test_unwatermark_skips_image_smaller_than_geometry():
+    """Ảnh nhỏ hơn cả lề 96px thì không phải khung Gemini gốc -> không được chạm vào."""
+    small = Image.new("RGB", (100, 80), (10, 20, 30))
+    out, info = L.unwatermark_gemini(small)
+    assert info is None and np.array_equal(np.asarray(out), np.asarray(small))
+
+
+def test_unwatermark_keeps_alpha_channel():
+    """Ảnh RGBA phải giữ nguyên mode và kênh alpha (chỉ sửa RGB)."""
+    wm, (x0, y0) = _wm_bake((50, 50, 50))
+    rgba = wm.convert("RGBA")
+    rgba.putalpha(Image.new("L", rgba.size, 123))
+    out, info = L.unwatermark_gemini(rgba)
+    assert info is not None and out.mode == "RGBA"
+    assert np.asarray(out)[..., 3].min() == 123
+    err = np.abs(_wm_box_px(out, x0, y0) - 50).max()
+    assert err <= 1
+
+
+def test_unwatermark_leaves_rest_of_image_untouched():
+    """Chỉ ô 48x48 được sửa — không được lan ra phần còn lại của ảnh."""
+    wm, (x0, y0) = _wm_bake((90, 120, 60))
+    out, _ = L.unwatermark_gemini(wm)
+    a, b = np.asarray(wm).astype(int), np.asarray(out).astype(int)
+    diff = np.abs(a - b).sum(axis=2)
+    diff[y0:y0 + 48, x0:x0 + 48] = 0
+    assert diff.max() == 0
+
+
+# ── Tách nền đa phương pháp: modal_border_color / unmix / score / best_cutout ───────────
+
+def _plate(size=(120, 200), bg=(251, 14, 224), fg=(120, 170, 40), horizon=90, aa=2):
+    """Ảnh NỀN full-bleed: nửa trên là màu nền, nửa dưới là 'thảm cỏ' tràn ra TẬN VÀNH.
+
+    Đây là hình dạng mà `sample_border_color` (dùng mean) không xử lý được, và là hình dạng
+    thật của ảnh nền game: home_grass/gpt1.png. `aa` là bề rộng dải anti-alias ở chân trời —
+    tham số hoá để test được việc dò bề rộng tự động (đo thật: 2px ở bản GPT, 7–8px ở Gemini).
+    """
+    w, h = size
+    arr = np.zeros((h, w, 3), dtype=np.float64)
+    arr[:horizon] = bg
+    arr[horizon + aa:] = fg
+    for i in range(aa):                      # dải blend tuyến tính giữa nền và tiền cảnh
+        t = (i + 1) / (aa + 1)
+        arr[horizon + i] = np.array(bg) * (1 - t) + np.array(fg) * t
+    return Image.fromarray(np.rint(arr).clip(0, 255).astype(np.uint8), "RGB")
+
+
+def test_modal_border_color_survives_half_subject_border():
+    """MODE trên vành chịu được vành nửa-nền-nửa-chủ-thể; MEAN thì không.
+
+    Đây là lý do tồn tại của modal_border_color. Đo thật trên home_grass/gpt1.png:
+    sample_border_color trả #AC4978 với purity 0.0002 — bùn tím, không phải màu nào có thật
+    trong ảnh — nên cửa `purity >= _AUTOKEY_MIN_PURITY` trong MCP không bao giờ mở và cả
+    pipeline rơi về màu key yêu cầu. Mode trên cùng ảnh đó trả #FB0EE0, đúng màu đã vẽ.
+    """
+    bg = (251, 14, 224)
+    img = _plate(bg=bg)
+
+    mode_hex, share = L.modal_border_color(img, key_hex="#FF00FF")
+    assert L.color_dist(L.hex_to_rgb(mode_hex), bg) < 20.0, mode_hex
+    assert share >= L.CUTOUT_MIN_BORDER_SHARE, share
+
+    mean_hex, purity = L.sample_border_color(img)
+    assert purity < 0.5, f"mean phải tỏ ra 'không thuần' trên vành trộn: {purity}"
+    assert L.color_dist(L.hex_to_rgb(mean_hex), bg) > 100.0, (
+        f"mean trộn hai nửa thành màu không có thật: {mean_hex}"
+    )
+
+
+def test_modal_border_color_without_key_can_pick_the_subject():
+    """Ghim VÌ SAO phải truyền `key_hex`: mode TOÀN CỤC có thể trả về màu CHỦ THỂ.
+
+    `_plate` có nền xanh PHẲNG tràn ra vành: đếm tay trên vành 4px của canvas 120x200 —
+    xanh 1312 px so với hồng 1168 px, nên mode toàn cục chọn XANH, tức màu chủ thể. Key
+    theo nó sẽ xoá mất chính chủ thể. Mode toàn cục chỉ đúng trên ảnh thật NHỜ MAY: nền key
+    phẳng còn thảm cỏ có vân nên không bin xanh nào áp đảo. Lọc theo màu key thì hết may rủi.
+    """
+    bg = (251, 14, 224)
+    fg = (120, 170, 40)
+    img = _plate(bg=bg, fg=fg)
+
+    loose, _ = L.modal_border_color(img)                        # không truyền key
+    assert L.color_dist(L.hex_to_rgb(loose), fg) < 20.0, (
+        f"ghim hành vi đã biết: mode toàn cục bám màu chủ thể, {loose}"
+    )
+    tight, _ = L.modal_border_color(img, key_hex="#FF00FF")     # có truyền key
+    assert L.color_dist(L.hex_to_rgb(tight), bg) < 20.0, tight
+
+
+def test_unmix_roundtrip_reconstructs_original():
+    """(F, α) của unmix phải là một PHÂN RÃ HỢP LỆ: ghép lại lên màu nền ra đúng ảnh gốc.
+
+    Đây là kiểm chứng ground-truth thật sự, không phải so sánh tương đối: nếu F và α cùng
+    đúng thì F·α + BG·(1−α) phải tái tạo được O. Đo thật trên gpt1.png dải mềm: unmix 0.228
+    so với 25.09 của region-grow+despill và 16.45 của chroma_key+despill.
+    """
+    bg = (251, 14, 224)
+    img = _plate(bg=bg, aa=3)
+    out, info = L.unmix_cutout(img, L.rgb_to_hex(bg))
+
+    O = np.asarray(img, dtype=np.float64)
+    arr = np.asarray(out, dtype=np.float64)
+    a = (arr[..., 3] / 255.0)[..., None]
+    recomp = arr[..., :3] * a + np.array(bg, dtype=np.float64) * (1 - a)
+    assert np.abs(recomp - O).mean() < 1.0, np.abs(recomp - O).mean()
+    assert info["soft_px"] > 0, "phải có pixel dải AA được giải"
+
+
+def test_unmix_band_width_adapts_to_source():
+    """Bề rộng dải AA phải ĐO TỪ ẢNH, không phải hằng số.
+
+    Bug thật gặp trong lúc phát triển: bản đầu cố định dải 2px, chạy sạch trên ảnh GPT
+    (AA 2px) nhưng để lại 433 px viền hồng ĐỤC trên ảnh Gemini (AA 7–8px, chân trời vẽ
+    nhoè). Hằng số cố định thì hoặc sót viền hoặc gặm chủ thể — không có giá trị nào đúng cả.
+    """
+    bg = (251, 14, 224)
+    narrow = L.unmix_cutout(_plate(bg=bg, aa=1), L.rgb_to_hex(bg))[1]["band_w"]
+    wide = L.unmix_cutout(_plate(bg=bg, aa=7), L.rgb_to_hex(bg))[1]["band_w"]
+    assert wide > narrow, f"dải phải nới theo ảnh: hẹp={narrow} rộng={wide}"
+    assert narrow <= 3, narrow
+    assert wide >= 5, wide
+
+
+def test_unmix_leaves_no_background_tint_on_kept_pixels():
+    """Không một pixel GIỮ LẠI nào còn ám màu nền — chỉ tiêu chính của cả việc này."""
+    bg = (251, 14, 224)
+    img = _plate(bg=bg, aa=3)
+    out, _ = L.unmix_cutout(img, L.rgb_to_hex(bg))
+    m = L.score_cutout(img, out, L.rgb_to_hex(bg))
+    assert m["cast"] == 0, m
+    assert m["f_err"] < 2.0, m["f_err"]
+    assert not m["disqualify"], m["disqualify"]
+
+
+def test_unmix_keeps_interior_art_of_background_colour():
+    """Ràng buộc LIÊN THÔNG: vùng trùng màu nền nằm trong lòng chủ thể KHÔNG bị xoá.
+
+    Cùng lý lẽ với strip_bg_residue: muốn bị coi là nền, một vùng phải nối được ra tới vành
+    ảnh. Không có ràng buộc này thì art tình cờ trùng màu key bị khoét thủng.
+    """
+    bg = (251, 14, 224)
+    arr = np.full((120, 120, 3), (120, 170, 40), dtype=np.uint8)
+    arr[:20, :, :] = bg                    # nền thật, chạm vành trên
+    arr[60:80, 60:80, :] = bg               # 'viên ngọc' trùng màu nền, nằm giữa thân
+    img = Image.fromarray(arr, "RGB")
+    out, _ = L.unmix_cutout(img, L.rgb_to_hex(bg))
+    al = np.asarray(out)[..., 3]
+    assert al[70, 70] == 255, "art trong lòng chủ thể không được xoá"
+    assert al[5, 60] == 0, "nền chạm vành phải bị xoá"
+
+
+def test_score_cutout_disqualifies_method_that_eats_subject():
+    """fg_loss phải LOẠI THẲNG cách ăn vào lòng chủ thể — ca BEN2 trên ảnh nền full-bleed.
+
+    Đo thật: BEN2 trên home_grass/gpt1.png ăn mất 8.99% thảm cỏ và làm mép nhoè thành dải
+    77.425 px. Không có cửa này thì nó vẫn có thể thắng điểm nhờ cast thấp.
+    """
+    bg = (251, 14, 224)
+    img = _plate(bg=bg, aa=2)
+    good, _ = L.unmix_cutout(img, L.rgb_to_hex(bg))
+
+    arr = np.asarray(good).copy()
+    arr[150:190, :, 3] = 60          # bào mờ một dải giữa lòng 'thảm cỏ'
+    eaten = Image.fromarray(arr, "RGBA")
+
+    m_ok = L.score_cutout(img, good, L.rgb_to_hex(bg))
+    m_bad = L.score_cutout(img, eaten, L.rgb_to_hex(bg))
+    assert m_bad["fg_loss"] > L.CUTOUT_BAD_FG_LOSS, m_bad["fg_loss"]
+    assert "an_chu_the" in m_bad["disqualify"], m_bad["disqualify"]
+    assert not m_ok["disqualify"], m_ok["disqualify"]
+    assert m_bad["score"] > m_ok["score"]
+
+
+def test_score_cutout_catches_opaque_fringe_that_f_err_cannot():
+    """`cast` bắt được ca mà `f_err` một mình bị qua mặt — vì sao cần CẢ HAI.
+
+    Cách nào để alpha=255 khắp dải AA sẽ có f_err≈0 HIỂN NHIÊN, vì khi α=1 thì nghịch đảo
+    đại số F_ideal ≡ O, tức 'màu đúng' chính là màu đã bị nền trộn vào. Chỉ `cast` mới thấy
+    viền còn ám màu nền đó. Đo thật: region-nofeather có f_err thấp nhưng cast 391.
+    """
+    bg = (251, 14, 224)
+    img = _plate(bg=bg, aa=4)
+    hard_edge = np.asarray(img.convert("RGBA")).copy()
+    hard_edge[:90, :, 3] = 0          # cắt cứng đúng chân trời, giữ NGUYÊN dải AA đục
+    blunt = Image.fromarray(hard_edge, "RGBA")
+
+    m = L.score_cutout(img, blunt, L.rgb_to_hex(bg))
+    assert m["f_err"] < 1.0, f"f_err bị qua mặt như dự đoán: {m['f_err']}"
+    assert m["cast"] > 0, "cast phải bắt được dải AA còn ám màu nền"
+
+    clean, _ = L.unmix_cutout(img, L.rgb_to_hex(bg))
+    assert L.score_cutout(img, clean, L.rgb_to_hex(bg))["score"] < m["score"]
+
+
+def test_best_cutout_picks_unmix_and_reports_full_table():
+    """best_cutout phải trả tên cách thắng VÀ bảng điểm đủ mọi ứng viên."""
+    bg = (251, 14, 224)
+    img = _plate(bg=bg, aa=3)
+    out, rep = L.best_cutout(img, "#FF00FF")
+
+    assert rep["cutout_method"] == "unmix", rep["cutout_method"]
+    assert rep["bg_source"] == "mode_vien", rep["bg_source"]
+    assert L.color_dist(L.hex_to_rgb(rep["bg_color_used"]), bg) < 20.0
+    assert len(rep["cutout_table"]) >= 2, rep["cutout_table"]
+    assert all("score" in r or r.get("error") for r in rep["cutout_table"])
+    assert not rep["all_disqualified"]
+    assert L.score_cutout(img, out, rep["bg_color_used"])["cast"] == 0
+
+
+def test_best_cutout_rejects_measured_colour_when_subject_fills_border():
+    """Cửa gác MIN_KEY_MARGIN: vành toàn CHỦ THỂ thì màu đo được phải bị TỪ CHỐI.
+
+    Vành có thể 'thuần một màu' mà vẫn không phải nền — khi chủ thể tràn kín canvas thì màu
+    đo được là màu chủ thể, key theo nó sẽ xoá mất chính chủ thể. Ngưỡng 190 là ĐO ĐƯỢC:
+    độ lệch model-vẽ-so-với-yêu-cầu 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.
+    """
+    img = Image.new("RGB", (64, 64), (200, 30, 40))       # đỏ kín khung, không có nền
+    _, rep = L.best_cutout(img, "#00FF00")
+    assert rep["bg_color_used"] == "#00FF00", rep["bg_color_used"]
+    assert rep["bg_source"] == "khong_thay_mau_key_o_vien", rep["bg_source"]
+    assert rep["bg_mode_share"] == 0.0, rep["bg_mode_share"]
+
+
+def test_score_cutout_ignores_fg_loss_when_no_key_field_exists():
+    """Không có phông key -> `far` vô nghĩa, KHÔNG được dùng fg_loss để loại.
+
+    Bug thật đã gặp và đã sửa: với ảnh KHÔNG có màu key ở vành (tranh nền thật, ảnh chụp),
+    `hard` rỗng nên `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 vừa tách nền THÀNH CÔNG. Đo thật lúc đó: cutout 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, nền còn nguyên.
+    """
+    rng = np.random.default_rng(7)
+    arr = rng.integers(60, 200, size=(120, 120, 3), dtype=np.int16).astype(np.uint8)
+    arr[40:80, 40:80] = (190, 60, 55)                  # 'chủ thể' 40x40 giữa khung
+    img = Image.fromarray(arr, "RGB")
+
+    seg = np.zeros((120, 120, 4), dtype=np.uint8)      # cutout LÝ TƯỞNG: đúng ô chủ thể
+    seg[..., :3] = arr
+    seg[40:80, 40:80, 3] = 255
+    good = Image.fromarray(seg, "RGBA")
+
+    regions = L._cutout_regions(img, "#00FF00")
+    assert not regions["hard"].any(), "ảnh này không được có vùng màu key nào"
+
+    m = L.score_cutout(img, good, "#00FF00", regions)
+    assert m["fg_loss_valid"] is False, m
+    assert m["fg_loss"] == 0.0, m["fg_loss"]
+    assert "an_chu_the" not in m["disqualify"], m["disqualify"]
+
+    # còn bản KHÔNG LÀM GÌ (đục hết khung) vẫn phải bị loại — bởi `coverage`, không phải fg_loss
+    untouched = img.convert("RGBA")
+    m_bad = L.score_cutout(img, untouched, "#00FF00", regions)
+    assert "phu_bat_thuong" in m_bad["disqualify"], m_bad["disqualify"]
+
+
+def test_best_cutout_lets_cutout_model_win_when_there_is_no_key_field():
+    """Ảnh không có phông key -> ứng viên `cutout` (BEN2) phải THẮNG, không bị loại oan."""
+    rng = np.random.default_rng(11)
+    arr = rng.integers(60, 200, size=(120, 120, 3), dtype=np.int16).astype(np.uint8)
+    arr[40:80, 40:80] = (190, 60, 55)
+    img = Image.fromarray(arr, "RGB")
+
+    def fake_ben2(im):
+        seg = np.zeros((120, 120, 4), dtype=np.uint8)
+        seg[..., :3] = np.asarray(im.convert("RGB"))
+        seg[38:82, 38:82, 3] = 255        # rộng hơn 2px để _erode_alpha(1) không ăn mất
+        return Image.fromarray(seg, "RGBA")
+
+    _, rep = L.best_cutout(img, "#00FF00", cutout=fake_ben2)
+    assert rep["cutout_method"] == "ben2", rep["cutout_table"]
+    assert rep["bg_source"] == "khong_thay_mau_key_o_vien", rep["bg_source"]
+
+
+def test_postprocess_multi_reports_method_and_does_not_despill_unmix():
+    """postprocess(multi=True) phải báo cách đã dùng, và KHÔNG despill lại bản unmix.
+
+    despill chỉ chạm pixel alpha<255 — tức đúng dải AA mà unmix vừa giải chính xác — nên
+    chạy nó lần nữa sẽ kéo nghiệm đúng lệch về phía heuristic kẹp kênh.
+    """
+    bg = (251, 14, 224)
+    img = _plate(size=(120, 200), bg=bg, aa=3)
+    out, rep = L.postprocess(img, "#FF00FF", size=(120, 200))
+
+    assert out is not None, rep
+    assert rep["cutout_method"] == "unmix", rep["cutout_method"]
+    assert "cutout_table" in rep and "cutout_score" in rep
+    assert "out_coverage" in rep and "out_solid_ratio" in rep
+    assert L.score_cutout(img, out, rep["bg_color_used"])["f_err"] < 2.0, "dấu hiệu bị despill lại"
+
+
+def test_postprocess_multi_can_be_turned_off():
+    """`multi=False` phải giữ NGUYÊN đường đơn phương pháp đời cũ — không có khoá báo cáo mới."""
+    img = _plate(bg=(251, 14, 224), aa=2)
+    _, rep = L.postprocess(img, "#FF00FF", size=(120, 200), multi=False)
+    assert "cutout_method" not in rep
+    assert "cutout_table" not in rep
+
+
+# ── fit_thumb: thumbnail cửa hàng, đúng số pixel ────────────────────────────────────────
+def test_fit_thumb_hits_exact_target_from_real_gemini_sizes():
+    """Ba size Gemini ĐO ĐƯỢC thật phải ra đúng 3 size cửa hàng, cắt bù dưới 1%."""
+    cases = [((1024, 1024), "1:1"), ((864, 1216), "5:7"), ((1376, 768), "16:9")]
+    for src, preset in cases:
+        target = L.THUMB_PRESETS[preset]
+        out, info = L.fit_thumb(Image.new("RGB", src, (10, 20, 30)), target)
+        assert out.size == target, f"{preset}: ra {out.size}, cần {target}"
+        assert info["lost_frac"] < 0.01, f"{preset}: cắt mất {info['lost_frac']:.3%}"
+        assert not info["upscaled"]
+
+
+def test_fit_thumb_anchor_top_keeps_top_edge():
+    """Thumb dọc hay có logo ở trên — anchor='top' phải giữ nguyên hàng pixel đầu."""
+    _, info = L.fit_thumb(Image.new("RGB", (864, 1216)), (540, 756), anchor="top")
+    assert info["crop"][1] == 0
+    _, mid = L.fit_thumb(Image.new("RGB", (864, 1216)), (540, 756))
+    assert mid["crop"][1] > 0        # center thì phải cắt cả hai đầu
+
+
+def test_fit_thumb_flags_upscale():
+    """Nguồn nhỏ hơn đích -> phải BÁO, vì thumb phóng to sẽ mềm."""
+    _, info = L.fit_thumb(Image.new("RGB", (300, 300)), (1024, 1024))
+    assert info["upscaled"] and info["scale"] > 1
+
+
+def test_fit_thumb_extreme_ratio_still_exact():
+    """Tỉ lệ nguồn lệch xa mục tiêu vẫn phải ra ĐÚNG size (chỉ cắt nhiều hơn)."""
+    out, info = L.fit_thumb(Image.new("RGB", (2000, 400)), (540, 756))
+    assert out.size == (540, 756)
+    assert info["lost_frac"] > 0.5    # panorama -> 5:7 thì mất rất nhiều, đúng như kỳ vọng
+
+
+def test_fit_thumb_rejects_bad_target():
+    for bad in [(0, 100), (100, 0), (-5, 10)]:
+        try:
+            L.fit_thumb(Image.new("RGB", (100, 100)), bad)
+        except ValueError:
+            continue
+        raise AssertionError(f"target {bad} phải bị từ chối")
+
+
+# ── strip_bg_residue / bg_residue: dọn nền SÓT theo màu nền ĐO ĐƯỢC ─────────────────────
+def _film(size=(200, 200), bg=(11, 208, 9), subject=(210, 170, 60)):
+    """Ảnh RGBA mô phỏng ca hỏng thật: nền còn nguyên dưới dạng màng BÁN TRONG SUỐT.
+
+    Đúng thứ đo được khi chroma-key theo màu key YÊU CẦU trong lúc model vẽ nền sắc độ khác:
+    alpha>8 phủ 100% khung, chủ thể đục ở giữa.
+    """
+    w, h = size
+    arr = np.zeros((h, w, 4), np.uint8)
+    arr[..., :3] = bg
+    arr[..., 3] = 60                      # màng nền: bán trong suốt, KHÔNG phải 0
+    arr[h // 4:3 * h // 4, w // 4:3 * w // 4, :3] = subject
+    arr[h // 4:3 * h // 4, w // 4:3 * w // 4, 3] = 255
+    return Image.fromarray(arr, "RGBA")
+
+
+def test_bg_residue_sees_film_that_border_impurity_cannot():
+    img = _film()
+    assert L.bg_residue(img, "#0BD009") > 0.5
+
+
+def test_strip_bg_residue_removes_film_and_keeps_subject():
+    img = _film()
+    out, killed = L.strip_bg_residue(img, "#0BD009")
+    a = np.asarray(out)
+    assert killed > 0
+    assert L.bg_residue(out, "#0BD009") < 0.01
+    # chủ thể còn nguyên vẹn, đục hoàn toàn
+    assert (a[60:140, 60:140, 3] == 255).all()
+    # bbox co về đúng chủ thể thay vì cả khung
+    assert L.content_bbox(out) == (50, 50, 150, 150)
+
+
+def test_strip_bg_residue_keeps_interior_art_of_bg_colour():
+    """Chi tiết art TRÙNG màu nền nhưng nằm KÍN trong chủ thể phải sống.
+
+    Đây là ràng buộc liên thông — bản thử xoá theo màu/hue KHÔNG kèm liên thông đã gặm mép
+    thành rỗ. Muốn bị xoá, một vùng phải nối được ra tới nền thật.
+    """
+    img = _film()
+    a = np.array(img)
+    a[95:105, 95:105, :3] = (11, 208, 9)     # đốm màu-nền giữa lòng chủ thể
+    a[95:105, 95:105, 3] = 255
+    out, _ = L.strip_bg_residue(Image.fromarray(a, "RGBA"), "#0BD009")
+    assert (np.asarray(out)[95:105, 95:105, 3] == 255).all()
+
+
+def test_strip_bg_residue_noop_when_already_clean():
+    img = Image.new("RGBA", (200, 200), (0, 0, 0, 0))
+    img.paste(Image.new("RGBA", (80, 80), (210, 170, 60, 255)), (60, 60))
+    out, killed = L.strip_bg_residue(img, "#0BD009")
+    assert killed == 0
+    assert np.array_equal(np.asarray(out), np.asarray(img))
+
+
+def test_postprocess_uses_bg_hex_over_requested_key():
+    """Đo thật: model vẽ nền #0BD009 khi được yêu cầu #00FF00. Key theo màu YÊU CẦU để lại
+    NGUYÊN nền; key theo màu ĐO ĐƯỢC thì sạch.
+
+    Test này ghim ca đó trên đường ĐƠN PHƯƠNG PHÁP (`multi=False`) — nơi lỗi gốc tồn tại và
+    nơi `bg_hex` là thứ duy nhất cứu được nó. Số đo tay: chủ thể 80x80 trên canvas 200x200
+    = 6400/40000 = 0.16, nên coverage đúng phải là 0.16; key theo #00FF00 cho 1.0000, tức
+    TOÀN BỘ nền sống sót thành "nội dung".
+    """
+    gen = Image.new("RGB", (200, 200), (11, 208, 9))
+    gen.paste(Image.new("RGB", (80, 80), (210, 170, 60)), (60, 60))
+    src = Image.new("RGBA", (64, 64), (0, 0, 0, 0))
+    _, bad = L.postprocess(gen, "#00FF00", src=src, multi=False)
+    _, good = L.postprocess(gen, "#00FF00", src=src, bg_hex="#0BD009", multi=False)
+    assert bad["bg_color_used"] == "#00FF00"
+    assert good["bg_color_used"] == "#0BD009"
+    assert good["bg_residue"] <= bad["bg_residue"]
+    assert good["coverage"] < bad["coverage"], (      # nền không còn bị tính là nội dung
+        f"key theo màu yêu cầu phải để sót nền: {bad['coverage']} vs {good['coverage']}"
+    )
+    assert bad["coverage"] > 0.95, f"ca lỗi gốc: nền sống sót gần trọn khung, {bad['coverage']}"
+
+
+def test_postprocess_multi_finds_drifted_key_without_being_told():
+    """Đường ĐA PHƯƠNG PHÁP phải tự dò ra màu nền lệch, KHÔNG cần ai truyền `bg_hex`.
+
+    Cùng ảnh với test trên. Đời cũ (`multi=False`, không `bg_hex`) đo được coverage 1.0000 —
+    nền sống sót trọn khung. `multi=True` phải tự đo ra #0BD009 qua modal_border_color và
+    cho ra ĐÚNG kết quả của nhánh được-truyền-tay (0.16), vì màu nền là thứ đo được chứ
+    không phải thứ phải hỏi. Đây là lý do tồn tại của cả khối best_cutout.
+    """
+    gen = Image.new("RGB", (200, 200), (11, 208, 9))
+    gen.paste(Image.new("RGB", (80, 80), (210, 170, 60)), (60, 60))
+    src = Image.new("RGBA", (64, 64), (0, 0, 0, 0))
+    _, auto = L.postprocess(gen, "#00FF00", src=src)               # multi bật mặc định
+    _, told = L.postprocess(gen, "#00FF00", src=src, bg_hex="#0BD009")
+
+    assert auto["bg_color_used"] == "#0BD009", auto["bg_color_used"]
+    assert auto["bg_source"] == "mode_vien", auto["bg_source"]
+    assert abs(auto["coverage"] - told["coverage"]) < 1e-9, (
+        f"tự dò phải ra đúng kết quả được-truyền-tay: {auto['coverage']} vs {told['coverage']}"
+    )
+    assert auto["coverage"] < 0.95, "không được để nền sống sót trọn khung như đời cũ"
+
+
+# ── compare_sheet: trang HTML đối chiếu gốc↔mới ─────────────────────────────────────────
+def _cs_groups():
+    o = Image.new("RGBA", (64, 64), (200, 160, 40, 255))
+    v1 = Image.new("RGBA", (64, 64), (240, 200, 60, 255))
+    v2 = Image.new("RGBA", (64, 64), (180, 140, 20, 255))
+    cell = Image.new("RGBA", (80, 80), (200, 80, 80, 255))
+    return [("coin", o, [("agy1", v1), ("gpt1", v2)]), ("cells", None, [("cell1", cell)])]
+
+
+def test_compare_sheet_is_self_contained():
+    """Không được tham chiếu file/CDN ngoài — trang phải gửi đi một mình vẫn xem được."""
+    html = L.compare_sheet(_cs_groups())
+    import re
+    assert not re.findall(r'(?:src|href)="(?!data:)([^"]+)', html)
+    assert "base64," in html
+
+
+def test_compare_sheet_groups_and_labels_present():
+    html = L.compare_sheet(_cs_groups())
+    for token in ["coin", "cells", "agy1", "gpt1", "cell1", "GỐC"]:
+        assert token in html, f"thiếu {token!r}"
+    assert html.count('class="grp"') == 2
+
+
+def test_compare_sheet_embeds_original_once_per_group():
+    """Gốc nhúng 1 lần/nhóm, KHÔNG lặp trong từng thẻ — lô lớn mà lặp thì file phình vô ích."""
+    html = L.compare_sheet(_cs_groups())
+    # 1 thẻ gốc + 3 biến thể + 1 bản gốc trong bảng ORIG (nhóm 'cells' không có gốc)
+    assert html.count("base64,") == 5
+
+
+def test_compare_sheet_no_flip_when_original_missing():
+    """Nhóm không có gốc thì thẻ KHÔNG được có nút lật — không có gì để lật về."""
+    html = L.compare_sheet([("cells", None, [("cell1", Image.new("RGBA", (32, 32), (1, 2, 3, 255)))])])
+    assert 'data-g="0"' in html                    # vẫn dựng được section
+    assert 'class="card can-flip"' not in html     # nhưng không thẻ nào lật được
+    assert 'class="ov"' not in html                # và không có lớp ảnh gốc chờ lật
+
+
+def test_compare_sheet_escapes_labels():
+    """Nhãn/tên asset đi thẳng vào HTML — phải escape, không để chèn thẻ."""
+    evil = '<img src=x onerror=alert(1)>"'
+    html = L.compare_sheet([(evil, None, [(evil, Image.new("RGBA", (8, 8), (0, 0, 0, 255)))])])
+    # Chuỗi vẫn HIỆN ra dưới dạng chữ (đúng), nhưng phải mất khả năng thành thẻ/thoát attribute.
+    assert "<img src=x" not in html, "nhãn chèn được thẻ <img> thật"
+    assert "&lt;img src=x" in html, "nhãn không được escape"
+    assert "&quot;" in html, 'dấu " trong nhãn không được escape -> thoát được attribute alt'
+
+
+# ------------------------------------------------------------------ PHÓNG TO (upscale)
+# Backend thật (Real-ESRGAN) cần torch + trọng số tải về, nên MỌI test ở đây dùng backend
+# GIẢ. Đó không phải né tránh: nó khoá đúng phần imglib chịu trách nhiệm — điều phối RGBA,
+# loang màu, chấm điểm, chọn bản — độc lập với chất lượng của model.
+
+def _fake_x4(arr):
+    """Backend giả: nhân đôi pixel 4 lần (NEAREST). Sắc nét, không bịa gì."""
+    return np.repeat(np.repeat(arr, 4, axis=0), 4, axis=1)
+
+
+def _blur_x4(arr):
+    """Backend giả kiểu 'mềm': phóng NEAREST rồi làm mờ. Dùng để dựng ứng viên KÉM."""
+    im = Image.fromarray(arr, "RGB").resize(
+        (arr.shape[1] * 4, arr.shape[0] * 4), Image.BICUBIC
+    ).filter(ImageFilter.GaussianBlur(2.0))
+    return np.asarray(im)
+
+
+def _sprite(size=(40, 40)):
+    """Sprite RGBA có mép mềm, nằm giữa nền TRONG SUỐT nhưng RGB vẫn là màu key."""
+    w, h = size
+    # Nền: magenta ĐỤC trong kênh RGB nhưng alpha 0 — đúng thứ unmix_cutout để lại.
+    a = np.zeros((h, w, 4), np.uint8)
+    a[..., :3] = (255, 0, 255)
+    yy, xx = np.mgrid[0:h, 0:w]
+    r = np.sqrt((xx - w / 2) ** 2 + (yy - h / 2) ** 2)
+    inside = r <= min(w, h) * 0.35
+    a[inside, :3] = (40, 120, 220)
+    a[inside, 3] = 255
+    return Image.fromarray(a, "RGBA")
+
+
+def test_bleed_removes_key_colour_from_transparent_area():
+    """_bleed_rgb phải QUÉT SẠCH màu nền khỏi vùng trong suốt trước khi phóng to.
+
+    Đây là bước dễ bỏ quên nhất của cả tính năng: sau tách nền, pixel nền vẫn mang màu key
+    trong kênh RGB (alpha 0 nên vô hình). Model phóng to chỉ nhận RGB — nó thấy magenta
+    thật và kéo vào mép, làm hỏng đúng cái viền mà đường tách nền vừa làm sạch.
+    """
+    img = _sprite()
+    a = np.asarray(img)
+    opaque = a[..., 3] > 0
+    filled = L._bleed_rgb(a[..., :3].astype(np.float32), opaque)
+    key = np.array([255, 0, 255], np.float32)
+    d = np.abs(filled - key).sum(axis=2)
+    assert d.min() > 60.0, f"vẫn còn pixel màu key sau khi loang (min |Δ| = {d.min():.1f})"
+    # Pixel ĐỤC phải giữ nguyên màu — loang chỉ được điền chỗ trong suốt.
+    assert np.array_equal(filled[opaque], a[..., :3][opaque].astype(np.float32))
+
+
+def test_upscale_rgba_does_not_pull_key_colour_into_edge():
+    """Hết đường: phóng to xong, mép sprite KHÔNG được ám màu nền."""
+    img = _sprite()
+    big = L.upscale_rgba(img, _fake_x4)
+    assert big.size == (img.width * 4, img.height * 4)
+    a = np.asarray(big)
+    # Nhìn ở nơi MẮT THẤY: pixel có alpha đáng kể.
+    vis = a[a[..., 3] > 40][:, :3].astype(np.float32)
+    magenta_ish = (vis[:, 0] > 150) & (vis[:, 1] < 90) & (vis[:, 2] > 150)
+    assert not magenta_ish.any(), f"{int(magenta_ish.sum())} px mép bị ám màu nền"
+
+
+def test_upscale_rgba_routes_alpha_through_backend():
+    """Alpha phải đi QUA backend, không phải LANCZOS — đo được là sai số matte giảm hơn nửa.
+
+    Cách phân biệt: backend giả nhân đôi pixel (bậc thang cứng), còn LANCZOS nội suy mềm.
+    Mép matte có giá trị trung gian hay không sẽ tố cáo đường nào đã chạy.
+    """
+    img = _sprite()
+    hard = np.asarray(L.upscale_rgba(img, _fake_x4, alpha_esrgan=True))[..., 3]
+    soft = np.asarray(L.upscale_rgba(img, _fake_x4, alpha_esrgan=False))[..., 3]
+    mid_hard = int(((hard > 20) & (hard < 235)).sum())
+    mid_soft = int(((soft > 20) & (soft < 235)).sum())
+    assert mid_hard < mid_soft, (
+        f"alpha không đi qua backend: bậc trung gian {mid_hard} vs LANCZOS {mid_soft}")
+
+
+def test_score_upscale_punishes_blur():
+    """Tiêu chí `blur` phải phạt bản mềm — đó là lý do cả tính năng tồn tại."""
+    img = _sprite()
+    sharp = L.upscale_rgba(img, _fake_x4)
+    soft = img.resize(sharp.size, Image.LANCZOS).filter(ImageFilter.GaussianBlur(2.0))
+    assert L.score_upscale(img, sharp)["blur"] < L.score_upscale(img, soft)["blur"]
+
+
+def test_score_upscale_ring_catches_overshoot():
+    """`ring` phải bắt quầng sáng — thứ `blur` chấm NGƯỢC (quầng làm gradient mạnh lên)."""
+    img = _sprite()
+    base = L.upscale_rgba(img, _fake_x4)
+    a = np.asarray(base).astype(np.float32)
+    a[..., :3] = np.clip((a[..., :3] - 128) * 2.2 + 128, 0, 255)   # đẩy tương phản -> quầng
+    over = Image.fromarray(a.astype(np.uint8), "RGBA")
+    s_base, s_over = L.score_upscale(img, base), L.score_upscale(img, over)
+    assert s_over["ring"] > s_base["ring"], "ring không thấy quầng"
+    # Và đây là chỗ blur một mình sẽ chọn SAI: nó cho bản quầng điểm ngang hoặc tốt hơn.
+    assert s_over["blur"] <= s_base["blur"] + 1e-9, (
+        "tiền đề của test hỏng — bản quầng phải không hề 'mờ' hơn theo blur")
+    assert s_over["score"] > s_base["score"], "tổng điểm vẫn chọn bản quầng"
+
+
+def test_best_upscale_without_backend_still_returns_exact_size():
+    """Thiếu torch -> chỉ còn LANCZOS, nhưng KHÔNG được lỗi và size phải đúng tuyệt đối."""
+    img = _sprite((30, 20))
+    out, rep = L.best_upscale(img, (97, 65), backend=None)
+    assert out.size == (97, 65)
+    assert rep["upscale_method"] == "lanczos"
+    assert rep["upscale_candidates"] == ["lanczos"]
+
+
+def test_best_upscale_survives_broken_backend():
+    """Model nổ giữa chừng KHÔNG được làm hỏng cả pipeline — rơi về LANCZOS và ghi lại lỗi."""
+    def boom(arr):
+        raise RuntimeError("hết VRAM giả lập")
+
+    img = _sprite((24, 24))
+    out, rep = L.best_upscale(img, (72, 72), backend=boom)
+    assert out.size == (72, 72)
+    assert rep["upscale_method"] == "lanczos"
+    assert any("esrgan" in e for e in rep.get("upscale_errors", [])), rep
+
+
+def test_best_upscale_picks_sharp_over_blurry_backend():
+    """Bộ chấm điểm phải CHỌN ĐƯỢC: backend sắc thắng, backend mềm thua LANCZOS."""
+    img = _sprite((32, 32))
+    _, rep_sharp = L.best_upscale(img, (128, 128), backend=_fake_x4)
+    assert rep_sharp["upscale_method"] == "esrgan", rep_sharp["upscale_table"]
+    _, rep_soft = L.best_upscale(img, (128, 128), backend=_blur_x4)
+    assert rep_soft["upscale_method"] == "lanczos", rep_soft["upscale_table"]
+
+
+def test_best_upscale_adds_pre_candidate_only_beyond_4x():
+    """`esrgan-pre` chỉ hợp lý khi đích > 4x. Dưới đó nó THU NHỎ nguồn trước khi phóng."""
+    img = _sprite((16, 16))
+    _, r3 = L.best_upscale(img, (48, 48), backend=_fake_x4)
+    _, r6 = L.best_upscale(img, (96, 96), backend=_fake_x4)
+    assert "esrgan-pre" not in r3["upscale_candidates"]
+    assert "esrgan-pre" in r6["upscale_candidates"]
+
+
+def test_score_upscale_disqualifies_a_different_image():
+    """Lưới an toàn: bản phóng ra ẢNH KHÁC HẲN phải bị loại thẳng, dù có sắc nét đến đâu."""
+    img = _sprite((32, 32))
+    other = Image.new("RGBA", (128, 128), (250, 240, 40, 255))
+    m = L.score_upscale(img, other)
+    assert "bia_noi_dung" in m["disqualified"], m
+
+
+def test_score_upscale_disqualifies_destroyed_matte():
+    img = _sprite((32, 32))
+    big = L.upscale_rgba(img, _fake_x4)
+    a = np.asarray(big).copy()
+    a[..., 3] = 255                       # matte bị xoá sạch -> sprite thành khối vuông
+    m = L.score_upscale(img, Image.fromarray(a, "RGBA"))
+    assert "lech_matte" in m["disqualified"], m
+
+
+def test_fit_into_upscales_only_when_enlarging():
+    """Chỉ gọi model khi PHÓNG TO. Thu nhỏ thì LANCZOS đã là tốt nhất — gọi model là phí."""
+    calls = []
+
+    def spy(arr):
+        calls.append(arr.shape)
+        return _fake_x4(arr)
+
+    big = _sprite((80, 80))
+    L.fit_into(big, (40, 40), (0, 0, 40, 40), upscale=spy)
+    assert calls == [], "đã gọi model khi THU NHỎ"
+
+    small = _sprite((20, 20))
+    rep: dict = {}
+    out = L.fit_into(small, (80, 80), (0, 0, 80, 80), upscale=spy, report=rep)
+    assert calls, "không gọi model khi PHÓNG TO"
+    assert out.size == (80, 80)
+    assert rep["upscale_method"] == "esrgan", rep
+    assert rep["upscale_from"] == [20, 20] and rep["upscale_to"] == [80, 80]
+
+
+def test_fit_into_without_upscaler_matches_old_behaviour():
+    """Không truyền backend -> hành vi y hệt đời cũ (LANCZOS), size và vị trí không đổi."""
+    img = _sprite((20, 20))
+    a = L.fit_into(img, (60, 60), (0, 0, 60, 60))
+    b = img.convert("RGBA").resize((60, 60), Image.LANCZOS)
+    canvas = Image.new("RGBA", (60, 60), (0, 0, 0, 0))
+    canvas.paste(b, (0, 0))
+    assert np.array_equal(np.asarray(a), np.asarray(canvas))
+
+
+def test_fit_thumb_upscales_and_reports_method():
+    img = _sprite((50, 50))
+    out, info = L.fit_thumb(img, (200, 200), upscale=_fake_x4)
+    assert out.size == (200, 200)
+    assert info["upscaled"] is True
+    assert info["upscale_method"] == "esrgan", info
+
+
+def test_fit_thumb_downscale_untouched_by_upscaler():
+    """Thumb thu nhỏ (ca thường gặp) không được đổi hành vi khi có backend."""
+    img = _sprite((400, 400))
+    a, ia = L.fit_thumb(img, (100, 100), upscale=_fake_x4)
+    b, ib = L.fit_thumb(img, (100, 100))
+    assert np.array_equal(np.asarray(a), np.asarray(b))
+    assert ia["upscaled"] is False and ia.get("upscale_method") is None
+
+
+def _detailed_on_key(size=(48, 48), key=(0, 255, 0)):
+    """Như _subject_on_key nhưng chủ thể CÓ HOẠ TIẾT — cần cho mọi test về độ sắc.
+
+    Chủ thể màu đặc làm năng lượng gradient bằng 0, tức là không có gì để làm sắc, và mọi
+    ứng viên phóng to đều tương đương (xem test_score_upscale_flat_source_is_not_called_blurry).
+    """
+    img = Image.new("RGB", size, key)
+    d = ImageDraw.Draw(img)
+    w, h = size
+    d.rectangle((w // 4, h // 4, w * 3 // 4, h * 3 // 4), fill=(200, 30, 40))
+    for i in range(w // 4 + 2, w * 3 // 4 - 1, 3):
+        d.line((i, h // 4 + 2, i, h * 3 // 4 - 2), fill=(250, 230, 60))
+    return img
+
+
+def test_score_upscale_flat_source_is_not_called_blurry():
+    """Ảnh nguồn PHẲNG: không có cạnh nào để làm sắc -> blur phải là 0, không phải 1.
+
+    Không có nhánh riêng cho ca này thì e_nn ~ 0 biến sharp thành 0/0, blur = 1.0 cho MỌI
+    ứng viên, điểm hoà hết, và bản 'thắng' rơi vào tay thứ tự dict — chọn bừa mà vẫn báo
+    cáo như một quyết định có cơ sở.
+    """
+    flat = Image.new("RGBA", (24, 24), (200, 30, 40, 255))
+    for cand in (flat.resize((96, 96), Image.LANCZOS), L.upscale_rgba(flat, _fake_x4)):
+        m = L.score_upscale(flat, cand)
+        assert m["blur"] == 0.0, m
+        assert m["score"] < 0.5, m
+
+
+def test_postprocess_reports_upscale_when_target_bigger():
+    """Đường end-to-end: bản sinh nhỏ hơn khung đích -> report phải nói đã phóng bằng cách nào."""
+    gen = _detailed_on_key()
+    out, rep = L.postprocess(gen, "#00FF00", size=(200, 200), upscale=_fake_x4)
+    assert out is not None and out.size == (200, 200)
+    assert rep.get("upscale_method") == "esrgan", {
+        k: v for k, v in rep.items() if k.startswith("upscale")}
+    assert rep["upscale_factor"] > 1.0
+
+
+def test_postprocess_without_upscaler_reports_no_method():
+    gen = _detailed_on_key()
+    out, rep = L.postprocess(gen, "#00FF00", size=(200, 200))
+    assert out is not None and out.size == (200, 200)
+    assert rep.get("upscale_method") == "lanczos", rep.get("upscale_table")
+
+
+def main():
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    failed = 0
+    for t in tests:
+        try:
+            t()
+            print(f"  PASS  {t.__name__}")
+        except Exception:
+            failed += 1
+            print(f"  FAIL  {t.__name__}")
+            traceback.print_exc()
+    print(f"\n{len(tests) - failed}/{len(tests)} passed")
+    # Minor fix: trả về SỐ LƯỢNG test fail thật sự, không phải cờ 0/1. cmd_selftest()
+    # cộng trực tiếp giá trị trả về của test_imglib.main() và test_restyle.main() để ra
+    # tổng số fail — nếu hàm này chỉ trả cờ 1/0, "TOTAL: N failed" sẽ SAI bất cứ khi nào
+    # có từ 2 test trở lên cùng fail ở đây (chỉ cộng thêm 1, không phải N).
+    return failed
+
+
+if __name__ == "__main__":
+    sys.exit(main())